diff --git a/.cargo/config.toml b/.cargo/config.toml
new file mode 100644
index 00000000..0f5db367
--- /dev/null
+++ b/.cargo/config.toml
@@ -0,0 +1,5 @@
+# `cargo play` — the run loop. Same optimization as `--release`, plus incremental compilation (see
+# `[profile.play]` in the workspace Cargo.toml for why it is a separate profile and not a flip of
+# `release`). Env vars still prefix it: `WOW_USER=one WOW_PASS=pone cargo play`.
+[alias]
+play = "run --profile play -p benilla"
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
new file mode 100644
index 00000000..e27a53a9
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,25 @@
+name: Bug report
+description: Something benilla gets wrong, or does differently from 1.12.1.
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: Screenshots or a clip help a lot; drag them in here.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What 1.12.1 does instead
+  - type: textarea
+    id: steps
+    attributes:
+      label: How to see it
+      placeholder: Where you were and what you did.
+  - type: input
+    id: build
+    attributes:
+      label: Build and setup
+      description: The `benilla build` line from the start of the terminal output, your OS, and the server you play on.
+      placeholder: "benilla build 64cca13 · 2026-09-24 · release, macOS 15, vmangos"
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 00000000..cdea83c4
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Discord
+    url: https://discord.gg/wJSJx467G4
+    about: Questions, ideas and chat.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000..3a23b396
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,7 @@
+<!-- One change per pull request. docs/CONTRIBUTING.md says what gets in. -->
+
+**What this changes**
+
+**What 1.12.1 does, and how you know** (the client's behaviour, a DBC field, a FrameXML line, a capture)
+
+**How you checked it** (`scripts/check.sh` or `scripts/gates.sh`, and before and after)
diff --git a/.github/workflows/close-prs.yml b/.github/workflows/close-prs.yml
deleted file mode 100644
index f2b9dfc8..00000000
--- a/.github/workflows/close-prs.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-# GitHub has no switch to disable pull requests, so this closes them on arrival.
-# Uses pull_request_target (base-repo context, no PR code checked out) so it can
-# comment and close on PRs from forks.
-name: close-prs
-on:
-  pull_request_target:
-    types: [opened, reopened]
-permissions:
-  pull-requests: write
-jobs:
-  close:
-    runs-on: ubuntu-latest
-    steps:
-      - run: |
-          gh pr comment "$PR" --repo "$REPO" --body \
-            "Thanks for the interest! benilla is a solo project and isn't taking pull requests for now — please bring bug reports and ideas to the Discord instead: https://discord.gg/wJSJx467G4"
-          gh pr close "$PR" --repo "$REPO"
-        env:
-          GH_TOKEN: ${{ github.token }}
-          PR: ${{ github.event.pull_request.number }}
-          REPO: ${{ github.repository }}
diff --git a/.gitignore b/.gitignore
index 706cf583..11050328 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,18 +4,40 @@
 # Cargo.lock IS committed (this workspace produces binaries).
 
 # --- Blizzard-owned content: NEVER commit ---
-# A legally-installed 1.12.1 client, read at runtime; not redistributed.
+# The user's legally-installed 1.12.1 client. Read at runtime; not redistributed.
 /WoW
-# Cached / extracted assets derived from an install.
+# Cached / extracted assets derived from the user's install.
 /extracted/
 /out/
 # Real client files used as test fixtures (document expected paths, do not commit).
 **/tests/fixtures/
 
-# Profiling output (`--features bevy/trace_chrome`).
+# --- benilla's own local state ---
+# The one folder benilla persists into: config.toml, macros/, bindings/, saved-variables.lua,
+# camera/. A dev build resolves it to the main checkout (so linked worktrees share one); a
+# release build puts it beside the binary — which is why it is not called `benilla/`: that name
+# collides with the binary of the same name. Machine-local by definition — `crate::local_state`
+# is the only thing in the tree that may write it.
+/benilla-config
+
+# The account a scripted run from this checkout logs in as (scripts/probe-identity.sh and the
+# client's account guard read it): WOW_USER=, WOW_PASS=, WOW_CHAR=, one per line. A credential.
+/.probe-identity
+
+# Profiling output: `--features bevy/trace_chrome` drops a multi-GB flame chart in the cwd, which
+# otherwise leaves the checkout "dirty".
 trace-*.json
 
 # OS / editor cruft
 .DS_Store
 *.swp
 /.idea/
+# Claude Code: settings and skills under .claude/ are each person's own.
+/.claude/
+
+# Python bytecode from the `scripts/` tooling.
+__pycache__/
+
+# The vanilla addon corpus the UI engine's real-addon tests read (third-party content): a symlink
+# beside `WoW`, or `BENILLA_ADDON_CORPUS`.
+/wow-addons-vanilla
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..a0b67e0d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,17 @@
+# benilla
+
+A from-scratch World of Warcraft 1.12.1 client in Rust and Bevy. The reference client is the
+spec: benilla is a faithful, modern implementation of it, not a place to get creative.
+
+Read, in this order:
+
+1. `docs/METHOD.md` — the rules and how we work. Binding for every session.
+2. `docs/MAP.md` — what is built right now, generated from the code. Orient here before
+   touching anything.
+3. `docs/CONTRIBUTING.md` — what gets in and how a change is judged.
+
+The rest of the root is code and data: `crates/` the workspace, `reference/` the 1.12 name
+catalogues the tests check against, `scripts/` the gates and instruments, `third_party/`
+vendored code.
+
+@docs/METHOD.md
diff --git a/Cargo.lock b/Cargo.lock
index f775f249..ab0e83e3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -513,7 +513,6 @@ dependencies = [
  "benilla-formats",
  "benilla-protocol",
  "benilla-ui",
- "benilla-wmo",
  "benilla-world",
  "bevy",
  "bevy_egui",
@@ -674,7 +673,6 @@ dependencies = [
  "bevy",
  "bytemuck",
  "image",
- "libc",
  "objc2 0.5.2",
  "objc2-app-kit 0.2.2",
  "objc2-foundation 0.2.2",
diff --git a/Cargo.toml b/Cargo.toml
index 0552b3cc..9ff6207c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -8,33 +8,18 @@ edition = "2021"
 license = "MIT OR Apache-2.0"
 authors = ["sam <samuv.eth@gmail.com>"]
 
-# Shared pins live here; promote a dep the moment two crates pin the same version (the policy
-# since day one, enacted at the 0530 debt sweep). Per-crate feature additions stay in the crate.
-# `image` deliberately stays per-crate: its default-features/feature sets differ per consumer,
-# and a workspace default-features choice can't be subtracted from downstream.
-# **Lint policy** (decision 2266 §C4). `too_many_arguments` is a readability lint for plain
-# functions; on a Bevy system the parameter list IS the scheduler's dependency declaration, and
-# a system that reads eight resources has eight parameters by construction. The lint had fired
-# 364 times in this workspace and been allowed 364 times, 281 of them on systems — a lint whose
-# every verdict is overridden is not a gate, it is a tax on adding a system. Allowed once here;
-# the per-site attributes are gone. `type_complexity` stays on: it fires on shapes a type alias
-# or a `SystemParam` bundle genuinely fixes.
+# A version two crates share is pinned in `[workspace.dependencies]`; feature additions stay per
+# crate. `image` stays per-crate: its consumers differ on default features, and a member cannot
+# turn off default features that a workspace entry enables.
+# `too_many_arguments` is off: a Bevy system's parameter list is its dependency declaration.
 [workspace.lints.clippy]
 too_many_arguments = "allow"
 
 [workspace.dependencies]
 anyhow = "1.0.102"
-# bevy's `default` is `["2d", "3d", "ui"]`, and every one of those three pulls `audio`
-# (= `bevy_audio` + `vorbis`) — so a default bevy compiles rodio, a second cpal, a second ALSA
-# binding and an ogg/vorbis decoder into a client that mixes through kira and has had bevy's
-# `AudioPlugin` disabled at boot since 0530. This spells the same `default` out with `audio`
-# taken away: `2d`/`3d`/`ui` decomposed into the parts they are made of, which is the whole
-# union of the three minus that one entry (decision 1932 has the expansion, verified against a
-# before/after feature tree). Nothing else in the graph asks for it — avian3d, bevy_egui and
-# bevy_transform_interpolation all take bevy with `default-features = false`.
-#
-# If a future bevy needs another member, add it here by name; do not reach back for `2d`/`3d`/
-# `ui`, which would quietly bring the audio stack with it.
+# bevy's default features spelled out without `audio`: `2d`, `3d` and `ui` each pull `bevy_audio`
+# and `vorbis`, and the client mixes through kira. Add a feature by name, never `2d`/`3d`/`ui`; a
+# plugin that takes bevy with its default features brings the audio stack back too.
 bevy = { version = "0.18.1", default-features = false, features = [
     "default_app",
     "default_platform",
@@ -45,88 +30,44 @@ bevy = { version = "0.18.1", default-features = false, features = [
     "scene",
     "picking",
 ] }
-# The render app's raw GPU handles (the WOW_GPU_MS meter's query set): bevy 0.18 does not wrap
-# wgpu's QuerySet family, so the meter reaches for the same wgpu the workspace already builds.
+# For the `WOW_GPU_MS` meter's query set, which bevy 0.18 does not wrap; must match bevy's wgpu.
 wgpu = "27"
 clap = { version = "4.6.1", features = ["derive"] }
 sha1 = "0.10.6"
 
-# The WoW format + protocol stack is fully in-repo (decision 0021), so there are no warcraft-rs /
-# wow_messages crates (or forks of them) anywhere in the tree. That is still true and is why this
-# section stood empty for the project's whole life.
-#
-# The one entry below is not a fork of a WoW crate at all. `lua-src` compiles the Lua the client's
-# addon VM runs on, and benilla's Lua has to accept EXACTLY the grammar the 1.12.1 client's Lua
-# accepts — no more and no less. Six hunks, all byte-read out of the client's own parser and VM:
-# three restore what 5.1 removed (the iterator-less generic-for `for k, v in someTable do`, which
-# 183 of 218 corpus addons are reached by; nesting long strings; the constructor's compat
-# semicolon), three delete what 5.1 added (`...` as an expression, `#`, `%`). Both directions are
-# below the reach of any layer above the VM — an opcode and a grammar are not a library function,
-# a global, or a metamethod — and the corpus ASKS about the second direction directly: 170
-# `loadstring` sites compile a vararg expression purely to find out which interpreter they are on.
-#
-# The fork landed BYTE-IDENTICAL to upstream's 5.1.5 sources on purpose: the pipeline was proven
-# transparent before any behavioural payload went into it, so when the suite moved, the patch was
-# the only thing that could have moved it. `third_party/lua-src/BENILLA.md` has the current state,
-# the per-hunk byte evidence and the verifying command (decisions 1215, 1315, 2101).
+# lua-src builds the addon VM's Lua 5.1.5, patched to accept exactly the 1.12 client's grammar;
+# the hunks and the command that checks them: `third_party/lua-src/BENILLA.md`.
 [patch.crates-io]
 lua-src = { path = "third_party/lua-src" }
-# kira 0.12.1 with one patch: spatial gains and the volume tween evaluated per CHUNK and
-# interpolated, not per frame (decision 1945; `third_party/kira/BENILLA.md`).
+# kira 0.12.1, patched to compute spatial gains and the volume tween per output chunk and
+# interpolate them, not per sample frame (`third_party/kira/BENILLA.md`).
 kira = { path = "third_party/kira" }
 
-# Optimize *dependencies* even in dev builds. avian/parry collision math (and wgpu/bevy render) is
-# unusably slow at opt-level 0 — a plain `cargo run` crawls to <1 fps once physics is doing real work.
-# opt-level 3 on deps (the standard Bevy fix) makes debug builds playable while our own crates stay
-# lightly optimized for fast incremental rebuilds. One-time cost: deps recompile optimized the first time.
+# Dependencies at opt-level 3 in dev: at opt-level 0, avian/parry collision drops a run to <1 fps.
 [profile.dev.package."*"]
 opt-level = 3
 
-# Our own crates at opt-level 1, not 0: Bevy's generic hot paths (material specialization scans,
-# query par_for_each closures) monomorphize INTO our crate, so at opt 0 they run at debug codegen
-# speed over every resident entity — measured at Stormwind as the difference between ~45 fps and a
-# pinned 60 (decision 0362). Warm incremental rebuild cost measured at ~zero. NB: FPS probe numbers
-# in decisions ≤ 0361 were taken at opt 0 and are not comparable with post-0362 probes.
+# Our crates at opt-level 1: Bevy's generic hot paths monomorphize into them, and at opt-level 0
+# Stormwind drops from a pinned 60 fps to ~45; the warm incremental rebuild cost is ~0.
 [profile.dev]
 opt-level = 1
 
-# No debuginfo trimming: `debug = "line-tables-only"` was A/B-measured (decision 0192) at zero
-# recurring win on this stack (macOS unpacked split-debuginfo; sccache; fast ld) — not worth
-# invalidating every warm target and the sccache cache for.
+# No debuginfo trimming: `debug = "line-tables-only"` measures no recurring win on macOS + sccache.
 
-# Shipping-grade optimization, A/B-graded at the pin (decision 0736): −1.0 cpu_ms (−5 %) vs
-# default release, flat at the empty-map and bare-Bevy floors. The campaign keeps grading on
-# default `release` — same-day A/B is the law, and fat LTO's link time would tax every
-# iteration for a constant offset. Build with `--profile ship` for actual releases (add
-# `RUSTFLAGS=-Ctarget-cpu=native` for a machine-local binary; not set here — it isn't portable).
+# The shipping build (`--profile ship`): fat LTO measures -1.0 cpu_ms (-5 %) against `release`,
+# which stays the measured profile because fat LTO's link time would tax every iteration.
+# `-Ctarget-cpu=native` is not set: it is not portable.
 [profile.ship]
 inherits = "release"
 lto = "fat"
 codegen-units = 1
 
-# The director's play loop (decision 1157): `release` plus incremental compilation. `benilla-app` is one crate of
-# ~243k lines, and release is non-incremental by cargo's default, so a one-line edit re-optimizes
-# all of it — measured 2m47s (43s frontend, ~121s LLVM at opt-level 3) against a 1.8s stamp rebuild
-# and a 2.5s no-op. Incremental caches both halves per codegen unit, so an edit pays for what it
-# touched. Cargo applies `incremental` to workspace members ONLY (verified: `target/debug/incremental`
-# holds our 16 crates and zero registry deps), so the ~760 dependencies stay non-incremental and
-# sccache-cacheable — 0192's wrapper and the cold-slot build are untouched.
-#
-# Why a separate profile rather than flipping `release`: incremental raises the codegen-unit count
-# and drops cross-unit inlining, which is a real codegen difference. The FPS campaign grades on
-# default `release` (0736) and same-day A/B is the law, so the graded profile must not quietly
-# change under it. Run it as `cargo play` (the alias in `.cargo/config.toml`).
+# `release` plus incremental, run as `cargo play`: under `release` a one-line edit to
+# `benilla-app` costs 2m47s. Incremental applies to workspace members only, so dependencies stay
+# sccache-cacheable; it changes codegen, so it lives here and not in the measured `release`.
 [profile.play]
 inherits = "release"
 incremental = true
-# ThinLTO OFF, and it is not a performance choice -- it is the fix for rustc #86049. `release`
-# implies thin-LOCAL LTO (ThinLTO across a crate's own codegen units), which promotes each CGU's
-# internal anonymous constants to external symbols named `anon.<hash>.N.llvm.<moduleid>`. Under
-# `incremental` some CGUs come back from the cache carrying names minted in an earlier compile,
-# so a promoted reference finds no definition and `cc` fails with "symbol(s) not found for
-# architecture arm64" -- an intermittent link failure with no source-level cause, cleared only by
-# a full rebuild. Measured on the 2026-08-29 occurrence: 7 poisoned CGUs in `benilla-formats`, 48
-# unresolved symbols. `lto = "off"` disables the promotion step entirely (verified: the play rlib
-# goes from 381 undefined `anon.*.llvm.*` symbols to 0). `release` and `ship` are UNTOUCHED -- they
-# are non-incremental, cannot hit this, and stay the graded profiles (0736). Decision 1698.
+# Not for speed: under `incremental`, thin-local LTO leaves promoted `anon.*.llvm.*` symbols
+# unresolved and the link fails intermittently (rustc #86049).
 lto = "off"
diff --git a/LIGHTING.md b/LIGHTING.md
index f2039a1e..2122d3df 100644
--- a/LIGHTING.md
+++ b/LIGHTING.md
@@ -2,7 +2,7 @@
 
 A dynamic light and shadow system for [benilla](https://github.com/samwhosung/benilla), the Rust +
 Bevy reimplementation of the 1.12.1 client. This branch is upstream benilla (merged at
-`edec5b22`) plus the lighting work, and nothing else. It needs no data changes: everything is
+`fd386e75`) plus the lighting work, the enhanced water module and volumetric fog, and nothing else. It needs no data changes: everything is
 derived from what a 1.12 install already carries (WMO `MOLT` lights, `MOCV` vertex colour, portals,
 M2 particle emitters, `Light.dbc`).
 
diff --git a/README.md b/README.md
index aa6f4c9d..9d73c9d0 100644
--- a/README.md
+++ b/README.md
@@ -8,12 +8,6 @@
   </p>
 </div>
 
-> [!IMPORTANT]
-> **Issues and pull requests are closed here.** benilla is a solo project developed in a private
-> tree; this repo is its export, published as squashed snapshots, so a PR here has nothing to land
-> on. The best way to contribute is to join the [Discord](https://discord.gg/wJSJx467G4) and report
-> the bugs you find. Questions and ideas are welcome in the same place.
-
 benilla speaks the original 1.12.1 protocol, so it connects to any server the real client could,
 and reads its game data at runtime from your own 1.12.1 install. Every file format and the network
 protocol are implemented from scratch, with no original client code, no third-party WoW crates,
@@ -34,12 +28,12 @@ and no bundled game assets.
   modes from slow fall to roots, a follow camera with collision, boats, zeppelins and taxi flights.
 - **Networking:** SRP6 auth through world-session crypto, the object mirror into the ECS, and live
   wire coverage from movement and chat through spells, party, quests, mail, trade, vendors, bank,
-  loot, the auction house and PvP honor.
-- **UI:** a from-scratch FrameXML + Lua engine driving the built-in interface, from the login and
-  character screens through the full HUD, the classic windows (guild, macros and key bindings
-  included), chat, nameplates, floating combat text and tooltips; third-party addons load from
-  a `benilla-config/AddOns/` folder beside the executable (partial: AtlasLoot and Bagnon run,
-  see below).
+  loot, the auction house, PvP honor and battlegrounds.
+- **UI:** a from-scratch FrameXML + Lua engine that runs the client's own stock interface off
+  your install's patch chain, from the login and character screens through the full HUD, the
+  classic windows (guild, macros and key bindings included), chat, nameplates, floating combat
+  text and tooltips; third-party addons load from a `benilla-config/AddOns/` folder beside the
+  executable (partial: AtlasLoot and Bagnon run).
 - **Combat:** melee on the faithful swing law, ranged and Auto Shot, casting with GCD and
   cooldowns, combo points, crowd control that really holds you, and the spell visual pipeline.
 - **Audio:** music, ambience and SFX under the client's own selection and crossfade rules, with
@@ -51,10 +45,8 @@ benilla is done when a 1.12.1 player can do everything here that they could in t
 client, it looks and feels the same, and it runs from a download on Windows, Linux and macOS.
 No dates; the order is what is likely, not a promise.
 
-- Battlegrounds, then the long tail of small features that separates a working client from a
-  finished one.
+- The long tail of small features that separates a working client from a finished one.
 - Addons, options and performance, ongoing.
-- The no-brainer fixes from VanillaFixes, SuperWoW and the like.
 - Playable downloads for Windows, Linux and macOS. Linux first.
 
 Not planned: other expansions or client versions, Warden (anticheat).
@@ -62,8 +54,10 @@ Not planned: other expansions or client versions, Warden (anticheat).
 ## Running it
 
 You need a **1.12.1 (build 5875) client install** for game data, a vanilla server to connect to,
-and stable Rust. Any 1.12.1 core works; [vmangos](https://github.com/vmangos/core) is what
-development runs against, and cMaNGOS and the rest speak the same protocol.
+stable Rust and a C compiler (the Lua is built from source; on macOS the Xcode command line
+tools, on Linux the ALSA and udev development packages). Any 1.12.1 core works;
+[vmangos](https://github.com/vmangos/core) is what development runs against, and cMaNGOS and
+the rest speak the same protocol.
 
 ```sh
 WOW_DATA=/path/to/WoW/Data cargo run --release -p benilla
@@ -74,6 +68,12 @@ at any IP or hostname, appending the auth port if yours is remapped
 (`WOW_HOST=play.example.com:5000`). Credentials go in at the login screen, or set `WOW_USER` /
 `WOW_PASS` to skip it.
 
+## Contributing
+
+Issues and pull requests are open. [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) says what gets
+in and how a change is judged. Bugs, questions and ideas are welcome on the
+[Discord](https://discord.gg/wJSJx467G4) too.
+
 ---
 
 Early inspiration and file format guidance came from the
@@ -82,9 +82,11 @@ Early inspiration and file format guidance came from the
 
 benilla is an independent fan project, not affiliated with or endorsed by Blizzard Entertainment.
 It ships **no Blizzard content** — no art, models, sounds, maps, MPQ contents or FrameXML; you
-provide your own legally obtained 1.12.1 client. The interface code under
-`crates/benilla-app/assets/ui/` is ours, written to the client's own layout and API names so that
-the windows look right and 1.12.1 addons find the names they expect.
+provide your own legally obtained 1.12.1 client. The stock interface runs off your own install's
+FrameXML at runtime; the handful of files under `crates/benilla-app/assets/ui/` are our own
+adapters and developer frames, not copies of it.
 
 World of Warcraft is a trademark of Blizzard Entertainment, Inc. Our own code is licensed under
-[MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your option.
+[MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your option. The two vendored components
+under `third_party/` — the kira audio engine, and a Lua 5.1 patched to the 1.12 client's dialect —
+keep their own upstream licenses, alongside each.
diff --git a/crates/benilla-adt/Cargo.toml b/crates/benilla-adt/Cargo.toml
index 10ad7516..5af32449 100644
--- a/crates/benilla-adt/Cargo.toml
+++ b/crates/benilla-adt/Cargo.toml
@@ -3,7 +3,7 @@ name = "benilla-adt"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "ADT terrain-tile reader for WoW 1.12.1 (build 5875) — in-repo, decision 0021"
+description = "ADT terrain-tile reader for WoW 1.12.1 (build 5875)"
 
 [lints]
 workspace = true
diff --git a/crates/benilla-adt/src/combined_alpha.rs b/crates/benilla-adt/src/combined_alpha.rs
index 05316818..016bb37f 100644
--- a/crates/benilla-adt/src/combined_alpha.rs
+++ b/crates/benilla-adt/src/combined_alpha.rs
@@ -1,13 +1,11 @@
-//! MCAL → one 64×64 RGBA alpha map (R/G/B = the opacity of texture layers 1/2/3; A = 255). Ported
-//! from wow-adt's `CombinedAlphaMap` so the output is byte-identical: layers are ingested in MCLY
-//! order (skipping the opaque base), each decoded into the next channel; encodings are 4-bit packed
-//! (×16), 8-bit raw, or Blizzard RLE (token bit 7 = fill, else copy; low 7 bits = count). `fix_alpha`
-//! reconstructs a 64×64 plane from 63×63 source by duplicating the previous pixel at the last row/col.
+//! MCAL to one 64×64 RGBA alpha map, ported from wow-adt's `CombinedAlphaMap`: R, G, B are the
+//! opacity of texture layers 1, 2, 3 and A is 255. Layers go in MCLY order after the opaque base. A
+//! layer is 4-bit packed (×17: the reference packs it into an RGBA4444 texel, read as `n / 15`),
+//! 8-bit raw, or RLE (token bit 7 fill, else copy; the low 7 bits are the count).
 
 use crate::McnkChunk;
 
-/// Assembles the per-layer MCAL alpha maps into one 64×64 RGBA buffer (`y`-major, then `x`, then
-/// channel R,G,B,A).
+/// The combined 64×64 RGBA alpha map, `y`-major.
 pub struct CombinedAlphaMap {
     map: Vec<u8>, // 64*64*4, [y][x][rgba]
     x: usize,
@@ -20,12 +18,13 @@ pub struct CombinedAlphaMap {
 const W: usize = 64;
 
 impl CombinedAlphaMap {
-    /// Construct and ingest `chunk`'s alpha layers. `has_big_alpha`/`fix_alpha` select the uncompressed
-    /// encoding width and the 63→64 edge fix (vanilla: `false`, `true`).
+    /// Decode `chunk`'s alpha layers. `has_big_alpha` makes uncompressed layers 8-bit, and
+    /// `fix_alpha` fills the last row and column from their neighbours (a 63×63 source); vanilla
+    /// is `false`, `true`.
     pub fn new(chunk: &McnkChunk, has_big_alpha: bool, fix_alpha: bool) -> Self {
         let mut map = vec![0u8; W * W * 4];
         for px in map.as_chunks_mut::<4>().0 {
-            px[3] = 255; // A unused, set opaque for tool visibility (matches wow-adt)
+            px[3] = 255; // A is unused; opaque, so a dump shows the channels
         }
         let mut s = Self {
             map,
@@ -76,10 +75,10 @@ impl CombinedAlphaMap {
         const PACKED: usize = W * W / 2;
         if offset + PACKED <= raw.len() {
             for &p in &raw[offset..offset + PACKED] {
-                if !self.set_next((p & 0x0F) * 16) {
+                if !self.set_next((p & 0x0F) * 17) {
                     break;
                 }
-                if !self.set_next(((p >> 4) & 0x0F) * 16) {
+                if !self.set_next(((p >> 4) & 0x0F) * 17) {
                     break;
                 }
             }
@@ -171,3 +170,33 @@ impl CombinedAlphaMap {
         self.y = 0;
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn blank() -> CombinedAlphaMap {
+        CombinedAlphaMap {
+            map: vec![0; W * W * 4],
+            x: 0,
+            y: 0,
+            layer: 0,
+            has_big_alpha: false,
+            fix_alpha: true,
+        }
+    }
+
+    /// The reference packs a 4-bit weight into an RGBA4444 texel (64×64 `0x6b03d0`, 32×32
+    /// `0x6b08d0`), read as `n / 15`, so nibble 15 is full coverage.
+    #[test]
+    fn four_bit_alpha_reads_as_n_over_15() {
+        let mut m = blank();
+        // Low nibble first: texel 0 = 0xF, texel 1 = 0x8.
+        m.ingest_small(&[0x8F; W * W / 2], 0);
+        assert_eq!(m.get(0, 0, 0), 255, "nibble 15 is full coverage");
+        assert_eq!(m.get(1, 0, 0), 136, "nibble 8 is 8/15");
+        let mut z = blank();
+        z.ingest_small(&[0x00; W * W / 2], 0);
+        assert_eq!(z.get(0, 0, 0), 0);
+    }
+}
diff --git a/crates/benilla-adt/src/lib.rs b/crates/benilla-adt/src/lib.rs
index ebee4e03..8e89a478 100644
--- a/crates/benilla-adt/src/lib.rs
+++ b/crates/benilla-adt/src/lib.rs
@@ -1,27 +1,11 @@
-//! An ADT terrain-tile reader for **WoW 1.12.1 (build 5875)** — in-repo, replacing `wow-adt`
-//! (decision 0021).
-//!
-//! Vanilla ADTs are monolithic, chunked (`IFF`-style: a 4-char magic — stored **reversed** on disk —
-//! plus a `u32` size, then payload). The root file holds `MTEX` (textures), `MMDX`/`MMID` (M2 paths),
-//! `MWMO`/`MWID` (WMO paths), `MDDF`/`MODF` (placements), and 256 `MCNK` terrain chunks. Each `MCNK` is
-//! a 128-byte header followed by sub-chunks (`MCVT` heights, `MCNR` normals, `MCLY` layers, `MCAL`
-//! alpha, `MCSH` shadow, `MCLQ` liquid), which we locate by **scanning** the chunk payload for their
-//! magics (robust, and identical to the header-offset data for vanilla).
-//!
-//! The shape mirrors what the renderer's terrain/liquid mesher consumes; quirks the consumer
-//! compensates for (the MCNR `[x,z,y]` byte order, the split predominant-texture/noEffectDoodad
-//! grids) are preserved deliberately. Proven against `wow-adt` over real ADTs during the decision-0021
-//! migration (oracle test in git history); the `benilla-formats` terrain golden tests pin the meshing
-//! end-to-end on every run.
-//!
-//! Byte access goes through `benilla-bytes` (decision 0064): every read is bounds-checked and a
-//! truncated chunk/record is a typed [`Error::Truncated`], never a panic.
+//! A reader for 1.12.1's monolithic root ADTs: IFF chunks (a reversed magic, a `u32` size, the
+//! payload) holding the asset names, the placements and 256 `MCNK` terrain chunks.
 
 use std::io::Cursor;
 
 use benilla_bytes::{chunks, ByteExt};
 
-/// A terrain vertex normal — stored on disk as `x, z, y` signed bytes.
+/// A terrain vertex normal: three signed bytes, named `x, z, y` in disk order.
 #[derive(Debug, Clone, Copy)]
 pub struct VertexNormal {
     pub x: i8,
@@ -30,8 +14,7 @@ pub struct VertexNormal {
 }
 
 impl VertexNormal {
-    /// `[x/127, y/127, z/127]` — i.e. on-disk `[b0, b2, b1]` / 127 (kept bit-identical to wow-adt; the
-    /// consumer cancels the z/y swap).
+    /// `[x, y, z] / 127`, which is disk bytes `[b0, b2, b1]`; the terrain mesher swaps them back.
     pub fn to_normalized(&self) -> [f32; 3] {
         [
             f32::from(self.x) / 127.0,
@@ -41,19 +24,19 @@ impl VertexNormal {
     }
 }
 
-/// MCVT — 145 heights (9×9 outer + 8×8 inner, stride-17 interleave).
+/// MCVT: 145 heights (9×9 outer + 8×8 inner, stride-17 interleave).
 #[derive(Debug, Clone)]
 pub struct McvtChunk {
     pub heights: Vec<f32>,
 }
 
-/// MCNR — one normal per MCVT vertex.
+/// MCNR: one normal per MCVT vertex.
 #[derive(Debug, Clone)]
 pub struct McnrChunk {
     pub normals: Vec<VertexNormal>,
 }
 
-/// MCLY per-layer flags (we only need the alpha-compression bit).
+/// MCLY per-layer flags.
 #[derive(Debug, Clone, Copy)]
 pub struct MclyFlags {
     pub value: u32,
@@ -66,7 +49,7 @@ impl MclyFlags {
     }
 }
 
-/// MCLY — one texture layer (16 bytes on disk).
+/// MCLY: one texture layer (16 bytes on disk).
 #[derive(Debug, Clone)]
 pub struct MclyLayer {
     pub texture_id: u32,
@@ -75,19 +58,19 @@ pub struct MclyLayer {
     pub effect_id: u32,
 }
 
-/// MCLY — the chunk's texture layers (0–4; layer 0 is the opaque base).
+/// MCLY: the chunk's texture layers (0–4; layer 0 is the opaque base).
 #[derive(Debug, Clone)]
 pub struct MclyChunk {
     pub layers: Vec<MclyLayer>,
 }
 
-/// MCAL — raw alpha-map bytes (indexed per layer via [`MclyLayer::offset_in_mcal`]).
+/// MCAL: raw alpha-map bytes (indexed per layer via [`MclyLayer::offset_in_mcal`]).
 #[derive(Debug, Clone)]
 pub struct McalChunk {
     pub data: Vec<u8>,
 }
 
-/// MCSH — a 64×64 1-bit baked shadow map (512 bytes).
+/// MCSH: a 64×64 1-bit baked shadow map (512 bytes).
 #[derive(Debug, Clone)]
 pub struct McshChunk {
     pub shadow_map: Vec<u8>,
@@ -104,11 +87,8 @@ impl McshChunk {
     }
 }
 
-/// One MCLQ liquid vertex (8 bytes: 4 union bytes + an absolute height).
-///
-/// The leading 4 bytes are a **union whose meaning is the block's liquid type** — water/ocean spend
-/// them on a depth byte + flow/foam, magma/slime on a `u16` texture-coordinate pair. Both readers are
-/// below; which one applies is the caller's decision, from the cell nibble.
+/// One MCLQ liquid vertex, 8 bytes: 4 union bytes and an absolute height. The union follows the
+/// cell's liquid type: a depth byte and flow for water and ocean, a UV pair for magma and slime.
 #[derive(Debug, Clone, Copy)]
 pub struct LiquidVertex {
     pub union_data: [u8; 4],
@@ -116,19 +96,14 @@ pub struct LiquidVertex {
 }
 
 impl LiquidVertex {
-    /// The depth byte (union byte 0) — drives the water depth-swatch on the render side. Water and
-    /// ocean blocks only; on a magma block these bytes are [`Self::texcoords`] instead.
+    /// The water or ocean depth byte (union byte 0).
     pub fn depth_byte(&self) -> u8 {
         self.union_data[0]
     }
 
-    /// The authored `(s, t)` texture-coordinate pair — two little-endian `u16`s over the same 4
-    /// union bytes. **Magma blocks only**: the reference's lava vert-fill is single-stage and reads
-    /// its `tc0` straight from here, where water/ocean instead write a UV into the depth-ramp
-    /// texture (VERIFIED bit-exact `WoW.exe 0x68d890` `liquid_render_verts`, emulation-diffed in
-    /// wow-re `crates/terrain`: `u = (s as i32 as f64 · 3/256) as f32`, same for `t`). The field is
-    /// authored world-continuous — a chunk's east edge repeats its neighbour's west edge exactly —
-    /// so lava tiles seamlessly across MCNK borders.
+    /// A magma block's authored `(s, t)`, two little-endian `u16`s the reference's lava fill takes
+    /// as its UV (`0x68d890`: `u = (s as i32 as f64 · 3/256) as f32`, same for `t`). The field is
+    /// world-continuous, so lava tiles seamlessly across MCNK borders.
     pub fn texcoords(&self) -> [u16; 2] {
         [
             u16::from_le_bytes([self.union_data[0], self.union_data[1]]),
@@ -137,51 +112,33 @@ impl LiquidVertex {
     }
 }
 
-/// One MCLQ liquid **block** — a 9×9 absolute-height grid + an 8×8 cell-flag grid, `0x324` bytes.
-///
-/// An MCNK carries **one block per set liquid header bit** (bits 2–5), packed back to back and with
-/// absent bits consuming nothing (VERIFIED wow-re `system/terrain/scratch/adt-format.md`, the cursor
-/// walk at `0x6af7a3`–`0x6af7cb`). Most liquid chunks set exactly one bit; **28 shipped Azeroth
-/// chunks set two** — a river *and* the sea, at a river mouth — and carry two blocks at different
-/// heights (measured: `sizeMCLQ` 1616 = 8 + 2·`0x324`, block 0 the stream at z≈5.0, block 1 the
-/// ocean at z=0). Reading only the first is how the sea goes missing there.
-///
-/// **No liquid type here on purpose.** The header-bit→type ordering (bit2 river / bit3 ocean /
-/// bit4 magma / bit5 slime) is *INFERRED* upstream — never byte-proven — while the per-cell flag low
-/// nibble IS the type, VERIFIED at both consumers (`0x6ba970` `and al,0xf`, `0x68d9b0`). So this
-/// reader takes only the block *count* from the flags and leaves the type to whoever reads
-/// [`Self::tile_flags`]. (The old `LiquidType::from_mcnk_flags` priority guess labelled all 28
-/// two-bit chunks "ocean" while handing back the river block's bytes.)
+/// One MCLQ liquid block: a 9×9 absolute-height grid and an 8×8 cell-flag grid. An MCNK carries
+/// one per set liquid header bit, back to back (`0x6af7a3`–`0x6af7cb`): two at the 28 shipped river
+/// mouths. The liquid type is each cell's flag nibble (`0x6ba970`, `0x68d9b0`), not a header bit.
 #[derive(Debug, Clone)]
 pub struct MclqChunk {
     pub min_height: f32,
     pub max_height: f32,
     pub vertices: Vec<LiquidVertex>,
-    /// Per-cell flags, row-major 8×8. Low nibble = liquid type (`0xf` = dry/hole); `0x80` shared.
-    /// `0x40` ("fishable") is carried but deliberately unread: its only compiled reader, the
-    /// reference's fishable query `0x69b5d0`, is a zero-caller dead island — fishability is the
-    /// server's verdict (`SPELL_FAILED_NOT_FISHABLE` passthru). Decision 1825.
+    /// Per-cell flags, row-major 8×8: the low nibble is the liquid type (`0xf` dry), `0x80`
+    /// shared. `0x40`, fishable, is unread: the reference's only reader (`0x69b5d0`) has no
+    /// caller, and the server decides fishability.
     pub tile_flags: [u8; 64],
 }
 
-/// MCNK header flag **bit 1** — the chunk a mover may not enter (the "impassable" band that walls
-/// Searing Gorge and the other mountain rims off from their neighbours).
-///
-/// The *producer* is VERIFIED per-instruction in wow-re (`system/terrain/scratch/adt-format.md`,
-/// the MCNK header walk: `hdr+0x00` bit1 → `chunk+0xc |= 0x40`); the *name* is wow-re's INFERRED
-/// label for that bit. Consuming it is decision 1266 / report B129.
+/// MCNK header flag bit 1: a chunk a mover may not enter, the bands along mountain rims such as
+/// Searing Gorge's. The reference's header walk copies it to its chunk flag `0x40` (`0x6af5f0`).
 pub const MCNK_IMPASSABLE: u32 = 0x2;
 
-/// The fields of the 128-byte MCNK header the renderer reads. `pred_tex`/`no_effect_doodad`/
-/// `unknown_8bytes` mirror wow-adt's (mis)split of the predominant-texture + noEffectDoodad region,
-/// which the consumer reconstructs — kept identical on purpose.
+/// The MCNK header fields the renderer reads. The names mislead: `pred_tex` and `no_effect_doodad`
+/// are the two halves of the predominant-texture map at `+0x40`, and `unknown_8bytes` is the real
+/// noEffectDoodad at `+0x50`; the consumer reassembles them.
 #[derive(Debug, Clone)]
 pub struct McnkHeader {
     pub flags: u32,
     pub index_x: u32,
     pub index_y: u32,
-    /// `AreaTable.dbc` id of this chunk (header +0x34) — the zone/subzone the player is standing
-    /// in; drives zone music/ambience/reverb selection (decision 0070).
+    /// `AreaTable.dbc` id of the chunk's zone or subzone (`+0x34`).
     pub area_id: u32,
     pub holes_low_res: u16,
     pub pred_tex: [u8; 8],
@@ -191,9 +148,7 @@ pub struct McnkHeader {
 }
 
 impl McnkHeader {
-    /// Is this chunk flagged [`MCNK_IMPASSABLE`]? The flag is a header bit, so its granularity is
-    /// the whole 33.333 yd chunk; in the shipped data the set chunks form contiguous ribbons along
-    /// zone rims (Searing Gorge's is 48 chunks of `Azeroth_33_44` alone).
+    /// Whether the raw header sets [`MCNK_IMPASSABLE`], which covers the whole 33.333 yd chunk.
     pub fn impassable(&self) -> bool {
         self.flags & MCNK_IMPASSABLE != 0
     }
@@ -208,12 +163,11 @@ pub struct McnkChunk {
     pub layers: Option<MclyChunk>,
     pub alpha: Option<McalChunk>,
     pub shadow: Option<McshChunk>,
-    /// The chunk's MCLQ liquid blocks — **one per set liquid header bit**, in on-disk order (see
-    /// [`MclqChunk`]). Empty on a dry chunk; two at a river mouth.
+    /// The MCLQ liquid blocks in disk order: none on a dry chunk, two at a river mouth.
     pub liquids: Vec<MclqChunk>,
 }
 
-/// MDDF — a placed M2 doodad (36 bytes).
+/// MDDF: a placed M2 doodad (36 bytes).
 #[derive(Debug, Clone)]
 pub struct DoodadPlacement {
     pub name_id: u32,
@@ -224,7 +178,7 @@ pub struct DoodadPlacement {
     pub flags: u16,
 }
 
-/// MODF — a placed WMO (64 bytes).
+/// MODF: a placed WMO (64 bytes).
 #[derive(Debug, Clone)]
 pub struct WmoPlacement {
     pub name_id: u32,
@@ -233,8 +187,8 @@ pub struct WmoPlacement {
     pub rotation: [f32; 3],
     pub flags: u16,
     pub doodad_set: u16,
-    /// `WMOAreaTable.NameSetID` selector — which naming/audio variant of the building this
-    /// placement is (Northshire Abbey vs Tyr's Hand Abbey are one WMO, different name sets).
+    /// `WMOAreaTable.NameSetID`: which name and audio variant of the WMO this placement is
+    /// (Northshire Abbey and Tyr's Hand Abbey are one WMO).
     pub name_set: u16,
 }
 
@@ -249,8 +203,7 @@ pub struct RootAdt {
     pub mcnk_chunks: Vec<McnkChunk>,
 }
 
-/// Either a vanilla monolithic root ADT (all we produce) — kept as an enum to mirror the consumer's
-/// `ParsedAdt::Root(..)` match.
+/// A parsed ADT; vanilla has only the monolithic root.
 #[derive(Debug, Clone)]
 pub enum ParsedAdt {
     Root(Box<RootAdt>),
@@ -274,8 +227,7 @@ impl std::error::Error for Error {}
 
 type Result<T> = std::result::Result<T, Error>;
 
-/// Split a NUL-separated string blob into a `Vec<u32>` of start offsets paired with strings (used to
-/// resolve MMDX/MWMO via MMID/MWID offsets).
+/// The NUL-terminated string at `offset`: an MMDX or MWMO name by its MMID or MWID offset.
 fn cstring_at(blob: &[u8], offset: usize) -> String {
     let end = blob[offset.min(blob.len())..]
         .iter()
@@ -285,7 +237,7 @@ fn cstring_at(blob: &[u8], offset: usize) -> String {
     String::from_utf8_lossy(&blob[offset.min(blob.len())..end]).into_owned()
 }
 
-/// Parse a vanilla monolithic ADT. (`cursor` position is ignored; the file starts at the first chunk.)
+/// Parse a vanilla monolithic ADT; the cursor's position is ignored.
 pub fn parse_adt(cursor: &mut Cursor<&[u8]>) -> Result<ParsedAdt> {
     let b: &[u8] = cursor.get_ref();
 
@@ -312,7 +264,7 @@ pub fn parse_adt(cursor: &mut Cursor<&[u8]>) -> Result<ParsedAdt> {
         }
     }
 
-    // Resolve model/WMO paths via the offset tables (the order MDDF/MODF `name_id` indexes).
+    // MDDF/MODF `name_id` indexes the MMID/MWID offset tables.
     let models = mmid
         .iter()
         .map(|&o| cstring_at(&mmdx, o as usize))
@@ -340,7 +292,6 @@ fn split_strings(blob: &[u8]) -> Vec<String> {
         .collect()
 }
 
-/// `name` tags the truncation error with the chunk this record list came from (MMID/MWID).
 fn read_u32_list(data: &[u8], name: &'static str) -> Result<Vec<u32>> {
     data.as_chunks::<4>()
         .0
@@ -388,18 +339,17 @@ fn read_modf(data: &[u8]) -> Result<Vec<WmoPlacement>> {
                 r.f32_at(24).ok_or(Error::Truncated("MODF"))?,
                 r.f32_at(28).ok_or(Error::Truncated("MODF"))?,
             ],
-            // 0x20..0x38 = bounding box (6 f32); then:
+            // 0x20..0x38: the bounding box (6 f32), unread.
             flags: r.u16_at(56).ok_or(Error::Truncated("MODF"))?,
             doodad_set: r.u16_at(58).ok_or(Error::Truncated("MODF"))?,
             name_set: r.u16_at(60).ok_or(Error::Truncated("MODF"))?,
-            // 0x3E scale u16 — unused.
+            // 0x3E: a u16, unread.
         });
     }
     Ok(out)
 }
 
-/// Parse one MCNK: a 128-byte header, then sub-chunks located by scanning the payload for their
-/// (reversed) magics.
+/// Parse one MCNK: the 128-byte header, then the sub-chunks at the header's offsets.
 fn read_mcnk(data: &[u8]) -> Result<McnkChunk> {
     if data.len() < 128 {
         return Err(Error::Truncated("MCNK header"));
@@ -443,14 +393,9 @@ fn read_mcnk(data: &[u8]) -> Result<McnkChunk> {
         liquids: Vec::new(),
     };
 
-    // Locate sub-chunks by the MCNK header offsets (the authoritative method — sequential scanning
-    // breaks when sub-chunks aren't contiguous, e.g. AhnQiraj). MCVT/MCNR offsets live in the
-    // `multipurpose_field` (0x14/0x18); the rest are explicit header fields. The offset base differs
-    // across sources (relative to the MCNK magic vs the MCNK data), so we auto-detect per sub-chunk by
-    // validating the (reversed) magic at both candidate positions. Returns the payload `(start, size)`.
-    // `ofs` comes straight off a (possibly corrupt) file's header, so both the "minus 8" candidate
-    // and the 8-byte header read use checked/bounds-checked arithmetic (`checked_sub`/`bytes_at`/
-    // `u32_at`) — a wrapped or out-of-range offset yields `None`, never a panic.
+    // Sub-chunks sit at the header's offsets, not in sequence (AhnQiraj's are not contiguous).
+    // An offset may count from the MCNK magic or from its data, so the reversed magic is checked
+    // at both; yields the payload's `(start, size)`.
     let locate = |ofs: u32, magic: &[u8; 4]| -> Option<(usize, usize)> {
         if ofs == 0 {
             return None;
@@ -464,8 +409,7 @@ fn read_mcnk(data: &[u8]) -> Result<McnkChunk> {
         }
         None
     };
-    // `start` always comes from a `locate` hit (bounds-proven above); `len` is attacker-controlled,
-    // so the end is saturating before clamping to the buffer.
+    // `locate` proves `start` in bounds; `len` is unvalidated, so the end saturates, then clamps.
     let slice = |start: usize, len: usize| &data[start..start.saturating_add(len).min(data.len())];
 
     if let Some((p, n)) = locate(
@@ -517,8 +461,8 @@ fn read_mcnk(data: &[u8]) -> Result<McnkChunk> {
         }
         chunk.layers = Some(MclyChunk { layers });
     }
-    // MCAL's data length is the header's `size_alpha`, NOT the sub-chunk's declared size (they differ
-    // on some files, e.g. AhnQiraj — wow-adt reads `size_alpha`).
+    // MCAL's length is the header's `size_alpha`, not the sub-chunk's own size: they differ on some
+    // files (AhnQiraj).
     if let Some((p, _)) = locate(
         h.u32_at(0x24).ok_or(Error::Truncated("MCNK header"))?,
         b"LACM",
@@ -540,8 +484,7 @@ fn read_mcnk(data: &[u8]) -> Result<McnkChunk> {
         shadow_map[..k].copy_from_slice(&sub[..k]);
         chunk.shadow = Some(McshChunk { shadow_map });
     }
-    // MCLQ, like MCAL, takes its length from the MCNK header (`size_liquid`): the MCLQ sub-chunk's
-    // own declared size is always 0.
+    // MCLQ's length is the header's `size_liquid` too: its own declared size is always 0.
     if let Some((p, _)) = locate(
         h.u32_at(0x60).ok_or(Error::Truncated("MCNK header"))?,
         b"QLCM",
@@ -555,14 +498,12 @@ fn read_mcnk(data: &[u8]) -> Result<McnkChunk> {
 
 /// Bytes per MCLQ block: `{f32 min, f32 max, 81×8B verts, 64B cell flags, u32 nFlow, 2×40B flow}`.
 const MCLQ_BLOCK: usize = 0x324;
-/// Liquid header bits (2–5) — their **count** is the number of packed MCLQ blocks. Only the count is
-/// read: the bit→type ordering is INFERRED, the cell nibble is VERIFIED (see [`MclqChunk`]).
+/// Liquid header bits 2–5: how many are set is how many MCLQ blocks there are.
 const MCNK_LIQUID_BITS: u32 = 0x3c;
 
-/// Read the packed MCLQ blocks — one per set liquid header bit, back to back (VERIFIED wow-re
-/// `adt-format.md`). Stops early on a block the payload can't cover, so a truncated tail degrades to
-/// the blocks that *are* whole rather than to nothing. A chunk with an MCLQ sub-chunk but no liquid
-/// bit set still yields one block, matching the pre-multi-block reader.
+/// Read the packed MCLQ blocks, stopping at the first one the payload cannot hold. A chunk with an
+/// MCLQ sub-chunk but no liquid bit set still yields one block; the reference creates one per set
+/// bit only (`0x6af760`).
 fn read_mclq_blocks(sub: &[u8], mcnk_flags: u32) -> Vec<MclqChunk> {
     let want = (mcnk_flags & MCNK_LIQUID_BITS).count_ones().max(1) as usize;
     let mut out = Vec::with_capacity(want);
@@ -578,9 +519,8 @@ fn read_mclq_blocks(sub: &[u8], mcnk_flags: u32) -> Vec<MclqChunk> {
     out
 }
 
-/// `None` (not an error) below the minimum size: too-short MCLQ data is treated as "no liquid",
-/// matching the pre-0064 reader — a real-data tolerance, not a hardening carve-out. (The minimum is
-/// the *read* span, short of the full [`MCLQ_BLOCK`]: the trailing flow vectors are unread.)
+/// Too-short MCLQ data is no liquid, not an error. The minimum stops short of [`MCLQ_BLOCK`]: the
+/// trailing flow data is unread.
 fn read_mclq_block(sub: &[u8]) -> Option<MclqChunk> {
     const NEED: usize = 8 + 81 * 8 + 64;
     if sub.len() < NEED {
@@ -621,9 +561,7 @@ mod tests {
         v
     }
 
-    /// A 128-byte MCNK header with a single MCVT (145 heights) sub-chunk placed right after it,
-    /// referenced via the "offset relative to the MCNK magic" convention (multipurpose field @0x14
-    /// pointing at the MCVT chunk's own magic, 128 bytes in).
+    /// An MCNK header and one MCVT after it, the `0x14` offset pointing at MCVT's magic, 128 in.
     fn mcnk_with_mcvt() -> Vec<u8> {
         let mut data = vec![0u8; 128];
         data[0x14..0x18].copy_from_slice(&128u32.to_le_bytes());
@@ -679,9 +617,7 @@ mod tests {
 
     #[test]
     fn partial_trailing_mddf_record_is_dropped_not_a_panic() {
-        // A record shorter than the 36-byte MDDF stride: `chunks_exact` drops the short remainder
-        // (a pre-existing, unchanged leniency — every *complete* 36-byte record is still
-        // bounds-checked via `ByteExt`, so this can never panic or misread).
+        // Shorter than the 36-byte stride: `as_chunks` drops the remainder.
         let b = chunk(b"FDDM", &[0u8; 10]);
         let ParsedAdt::Root(root) = parse(&b).expect("parses");
         assert!(root.doodad_placements.is_empty());
@@ -695,9 +631,7 @@ mod tests {
 
     #[test]
     fn corrupt_mcnk_subchunk_offset_skips_cleanly_never_panics() {
-        // ofs = 3: `checked_sub(8)` on the second candidate is `None`, and the first candidate (3)
-        // doesn't land on a valid magic — must yield `None`, not wrap/panic (the verified
-        // `ofs.wrapping_sub(8)` trap this replaces).
+        // ofs = 3: the minus-8 candidate underflows and 3 holds no magic.
         let mut data = vec![0u8; 128];
         data[0x14..0x18].copy_from_slice(&3u32.to_le_bytes());
         let b = chunk(b"KNCM", &data);
@@ -716,20 +650,16 @@ mod tests {
     fn short_mclq_is_treated_as_no_liquid_not_an_error() {
         let mut data = vec![0u8; 128];
         data[0x60..0x64].copy_from_slice(&128u32.to_le_bytes()); // MCLQ offset
-        data[0x64..0x68].copy_from_slice(&4u32.to_le_bytes()); // size_liquid — far short of NEED
+        data[0x64..0x68].copy_from_slice(&4u32.to_le_bytes()); // size_liquid, far short of NEED
         data.extend(chunk(b"QLCM", &[0u8; 4]));
         let b = chunk(b"KNCM", &data);
         let ParsedAdt::Root(root) = parse(&b).expect("parses");
         assert!(root.mcnk_chunks[0].liquids.is_empty());
     }
 
-    /// **One MCLQ block per set liquid header bit**, packed back to back — the shape that made the
-    /// sea vanish at 28 shipped river mouths when only the first was read (see [`MclqChunk`]).
-    /// Two bits set ⇒ two blocks, each keeping its OWN cell flags, so the consumer can tell the
-    /// river block from the ocean block by nibble.
+    /// Each block keeps its own cell flags, so the river and the ocean tell apart by nibble.
     #[test]
     fn a_two_bit_mcnk_yields_two_mclq_blocks_in_disk_order() {
-        // One block: min/max, 81×8B verts, 64B cell flags, then the flow tail — 0x324 total.
         let block = |height: f32, nibble: u8| {
             let mut b = vec![0u8; MCLQ_BLOCK];
             b[0..4].copy_from_slice(&height.to_le_bytes());
@@ -740,11 +670,11 @@ mod tests {
             b[8 + 81 * 8..8 + 81 * 8 + 64].fill(nibble);
             b
         };
-        let mut payload = block(5.0, 4); // bit 2 (river) — first on disk
-        payload.extend(block(0.0, 1)); // bit 3 (ocean) — second
+        let mut payload = block(5.0, 4); // the river, first on disk
+        payload.extend(block(0.0, 1)); // the ocean, second
 
         let mut data = vec![0u8; 128];
-        data[0x00..0x04].copy_from_slice(&0x0cu32.to_le_bytes()); // liquid bits 2 AND 3
+        data[0x00..0x04].copy_from_slice(&0x0cu32.to_le_bytes()); // liquid bits 2 and 3
         data[0x60..0x64].copy_from_slice(&128u32.to_le_bytes());
         data[0x64..0x68].copy_from_slice(&((payload.len() + 8) as u32).to_le_bytes());
         data.extend(chunk(b"QLCM", &payload));
@@ -759,9 +689,7 @@ mod tests {
         assert_eq!(liquids[1].min_height, 0.0);
     }
 
-    /// The magma union bytes are an authored `(s, t)` u16 pair, little-endian over the same 4 bytes
-    /// the water blocks spend on a depth byte — VERIFIED `0x68d890` reads them as `u16 → i32`, so
-    /// `0xffff` is 65535 and never −1.
+    /// `0x68d890` reads the magma pair as `u16 → i32`, so `0xffff` is 65535, never −1.
     #[test]
     fn magma_union_bytes_read_as_two_unsigned_u16_texcoords() {
         let v = LiquidVertex {
diff --git a/crates/benilla-app/Cargo.toml b/crates/benilla-app/Cargo.toml
index 18380dad..e61c481a 100644
--- a/crates/benilla-app/Cargo.toml
+++ b/crates/benilla-app/Cargo.toml
@@ -3,164 +3,85 @@ name = "benilla-app"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "The Bevy app as a library: everything but the build-id stamp, which lives in the `benilla` launcher shim so a commit dirties ~30 lines instead of this crate (decision 0993)"
+description = "The Bevy app as a library: everything but the build-id stamp, which lives in the `benilla` launcher so a new commit does not rebuild this crate"
 
 [lints]
 workspace = true
 
 [features]
-# **The dev/player seam** (decisions 0026 + 1173). Default-ON, so every ordinary `cargo run`,
-# capture, probe and gate builds exactly what it built before. `--no-default-features` compiles
-# the instruments — the debug panel, the perf HUD, the inspector, the capture harness and the
-# probe fleet — physically OUT: not dormant behind a runtime flag, absent. That is the whole
-# requirement a player client has of them, and a runtime toggle cannot meet it.
-#
-# The rule the seam enforces is one-directional: **dev may see anything; nothing may depend on
-# dev.** It is enforced by `cargo build -p benilla --no-default-features` in `scripts/gates.sh`,
-# not by anyone remembering it — 0026 adopted the rule in June 2026 with no failing build behind
-# it, and twenty-four couplings had accumulated by August (1173).
+# `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.
 default = ["dev"]
-#
-# The three benilla crates below are taken with `default-features = false` and their `dev`
-# re-exported here (1175). Their `dev` is default-on too, so without the round trip a
-# `--no-default-features` build gets the feature back through unification — and the binary
-# carries the build machine's source-tree path after all. Same trap as the shim's, one level down.
+# `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.
 dev = ["benilla-assets/dev", "benilla-formats/dev", "benilla-world/dev", "dep:bevy_egui"]
-# Opt-in Tracy profiling: `cargo run --features tracy` streams per-system `info_span!` markers (on the
-# hot systems) + render-pass CPU timings to a Tracy capture (decision 0026 — the dev/player seam;
-# a `docs/howto/running.md` this once cited never landed).
 tracy = ["bevy/trace_tracy"]
-# Opt-in Chrome-trace profiling: `cargo run --features trace_chrome` writes a `trace-<ts>.json` of
-# every system's per-run span next to the working dir. Tracy's offline twin — it needs no GUI and no
-# live capture, so a per-system cost question is answerable from a terminal (and from a run someone
-# else recorded). Aggregate it with `scripts/tracesum.py`.
+# `--features trace_chrome` writes every system's per-run span to `trace-<ts>.json` in the cwd.
 trace_chrome = ["bevy/trace_chrome"]
 
 [dependencies]
 anyhow.workspace = true
-# OS clipboard access for the UI EditBox copy/cut/paste chords (chat input). Already in the tree via
-# bevy_egui; pinned to the same 3.x so there's one copy. Read on the main thread (the UI key feed is
-# a NonSend system) — required for the macOS NSPasteboard path. Covers macOS, Windows, and Linux/BSD
-# under X11; the Wayland backend is `smithay-clipboard` below (decision 0702).
+# 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.
 arboard = "3"
 benilla-ui = { path = "../benilla-ui" }
 bevy.workspace = true
 wgpu.workspace = true
-# Optional: the dev overlays are its only consumers (the panel, the perf pill, the inspector
-# card), so a player build does not link it at all (`dev` feature, decision 1173).
 bevy_egui = { version = "0.39", optional = true }
-# Zero-copy POD→bytes for the shared light storage buffer (one per-frame write_buffer). Already in
-# the tree transitively; pinned to the same version as the dev-dep below.
 bytemuck = { version = "1", features = ["derive"] }
-# `f16` decode for the booth-target dump (`WOW_BOOTH_DUMP`): the booth render targets are
-# `Rgba16Float` (decision 0804) and the PNG wants display bytes. Already in the tree via
-# wgpu/bevy_image; declared so the call site is an honest dependency.
+# `f16` decode for the `WOW_BOOTH_DUMP` dump of the `Rgba16Float` booth render targets.
 half = "2"
-# The shipped FrameXML tree, compiled into the binary (decision 1175 §2): 61 files, ~2.8 MB, so the
-# client cannot boot without its interface on a machine that has never seen our source. A proc
-# macro plus a no-dependency runtime shim — it adds nothing to the graph at runtime, and it is the
-# crate everyone uses for this. `assets/ui` is OUR content (MIT/Apache), not Blizzard's.
+# 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 are PCRE over shipped DBCs (decision 2077; `text_filter`): 2289 profanity
-# expressions and 28 spam ones, compiled once at startup and run over every chat line. `RegexSet` is
-# exactly the shape that needs — one automaton over the whole list for the "can anything match at
-# all" pass — and the crate is already in the tree transitively.
+# 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.
 regex = "1"
-# `getrusage` — whole-process CPU time (all threads), the perf probes' `cpu_ms`/`cpu_pct` metric
-# (`perf::process_cpu_secs`). Wall-clock fps is unusable as a regression instrument on a machine
-# running parallel sessions' builds; CPU-per-frame is, and it is also the number the Mac report
-# is about ("250 % CPU at 59 fps"). Was dev-only; since 1857 the output backend needs it in every
-# build too (`mach_absolute_time`, the host clock its meters read; `thread_policy_set`, the render
-# thread's realtime policy).
+# `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.
 libc = "0.2"
-# Resample varying-size layer BLPs to a uniform size for the terrain texture array; `png` so we can
-# encode the cursor image into data an NSImage can load (macOS hardware cursor).
+# PNG encoding only: the macOS hardware cursor's NSImage data and screenshots.
 image = { version = "0.25", default-features = false, features = ["png"] }
-# The net↔ECS bridge: a background IO thread streams typed `SessionEvent`s to the ECS over a
-# channel, and outbound `ClientCommand`s back. crossbeam's Sender/Receiver are `Send + Sync + Clone`
-# (std's mpsc Sender is `!Sync`, so it can't be a Bevy resource without a mutex — the very thing this
-# bridge deletes). The canonical Bevy background-thread→channel→system idiom. See decision 0006.
+# 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.
 crossbeam-channel = "0.5"
 benilla-assets = { path = "../benilla-assets", default-features = false }
 benilla-formats = { path = "../benilla-formats", default-features = false }
 benilla-protocol = { path = "../benilla-protocol" }
 benilla-world = { path = "../benilla-world", default-features = false }
-# The CVar config diff (`benilla/config.toml`, decision 0954): serde derive on the persisted
-# shape, toml as its format. (serde_json left with the era manifest — 0978.)
+# The CVar diff persisted in `benilla-config/config.toml`.
 serde = { version = "1", features = ["derive"] }
 toml = "0.8"
-# ECS-native physics: collider storage + broadphase BVH + shape-casts, with a thin custom kinematic
-# character controller on top (decision 0009). Pinned 0.6: it targets Bevy 0.18 (verified single,
-# unified bevy 0.18.1 in the tree); 0.7.0 jumps to Bevy 0.19 and would duplicate bevy. avian wraps
-# parry under the hood, so adopting it lets us drop the *direct* parry3d dep once the bespoke
-# CollisionWorld is gone. See docs… (decision 0007 superseded by 0009).
+# Collision for our kinematic character controller; 0.6 targets Bevy 0.18, 0.7 moves to 0.19.
 avian3d = "0.6"
-# The glyph shaper + rasterizer for `FontString` text (decision 0068 §2, probe-verified in
-# `probes/text-glyph`). Pinned to 0.16 — the exact version already in the tree transitively
-# (`bevy_text`'s own dependency, see `Cargo.lock`) — so this is the *same* `cosmic-text` the decision
-# already commits to, not a second copy. Used as a standalone shaper/rasterizer (`FontSystem` +
-# `Buffer` + `SwashCache`) in `ui_text.rs`, never `bevy_text`'s `Text2d`/ECS integration (that path
-# doesn't feed our custom z-ordered `UiQuad` stream).
+# Shapes and rasterizes `FontString` text standalone (`ui_text`), at bevy_text's own 0.16.
 cosmic-text = "0.16"
-# The font database `cosmic-text` 0.16 uses (its `Source`/`ID`/`FaceInfo` appear in `ui_text.rs`'s
-# public-in-crate types). Pinned to the exact version `cosmic-text` 0.16 depends on so there's one
-# `fontdb` in the graph.
+# `cosmic-text`'s font database, whose types `ui_text` names; must stay the version it depends on.
 fontdb = "0.23"
-# kira renders the mix; the device it plays through is OURS (`sound::output`, decision 1857) —
-# kira's own `cpal` backend is not enabled on any target. On macOS that took cpal out of the graph
-# entirely: it could neither report a lost default device nor rebuild on one, and it discarded the
-# IO-cycle timestamp the deadline meters need. Off macOS cpal is back (1920) but as OUR device
-# layer under the same backend, not as kira's — the ring, the render thread and the meters are the
-# same code on every platform.
+# 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"] }
-# The realtime-audio allocation tripwire (decision 1857): `assert_no_alloc(|| …)` around the output
-# IO callback and the render pass aborts a DEBUG build on any allocation inside them, so a
-# realtime-safety regression fails a test or a smoke instead of reaching an ear. Release builds
-# compile it out (`disable_release`, the crate's default) and carry no allocator wrapper.
+# Aborts a debug build on an allocation in the audio IO callback or render pass; off in release.
 assert_no_alloc = "1.1"
-# kira's own decoder, named directly for one trait: the mixer feeds streams through its own
-# `MediaSource` so kira's per-stream decode thread runs OUR code and can promote its QoS (decision
-# 1109 — a bare-spawned decode thread starves under the world-entry burst and zero-fills the mix).
-# No codecs of its own (kira's features enable those); must stay the version kira resolves — one
-# symphonia in the graph, or the trait impl won't line up.
+# 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.
 symphonia = { version = "0.5", default-features = false }
-# The mix tap's audio-thread → writer-thread ring (decision 1112): the tap effect must never
-# block or allocate on the render path. kira's own SPSC ring crate; kept on the version kira
-# resolves so the graph carries one rtrb.
+# 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 is a weighted random DRAW per menu-open, not a fixed pick (wow-re
-# `gossip-npctext-law.md` — the reference re-rolls in its gossip handler), so the app needs a uniform
-# source. Pinned to 0.8: the version `benilla-srp` already depends on, so this adds no crate.
+# The gossip greeting's weighted draw, re-rolled per open as in the reference; `benilla-srp`'s 0.8.
 rand = "0.8"
 
-[dev-dependencies]
-# The WMO portal-cull audit's raw-face instruments (`WOW_PIN_COL`): the pin probe compares the
-# filtered walking-collision set against the group file's FULL face list with per-face MOPY flags,
-# which only the raw parser exposes — benilla-formats' gathers are exactly the filtered views.
-benilla-wmo = { path = "../benilla-wmo" }
-
-# Linux/BSD: the Wayland clipboard (decision 0702). We build with bevy's `wayland` feature, so on a
-# Wayland session winit gives us a native Wayland window and `arboard` — X11-only without its
-# non-default `wayland-data-control` feature — finds no X11 CLIPBOARD owner and every paste fails.
-# smithay-clipboard is the right crate for a windowed app: it drives the *standard* `wl_data_device`
-# off our own `wl_display`/seat, which every compositor supports. arboard's own Wayland feature would
-# not do: it speaks `wlr-data-control`, a privileged manager protocol GNOME/Mutter deliberately
-# doesn't implement. `raw-window-handle` (pinned to the 0.6 already in the tree via bevy_window, so
-# this adds no crate) is only needed to read the `wl_display` out of bevy's `RawHandleWrapper`.
+# 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.
 [target.'cfg(all(unix, not(any(target_os = "macos", target_os = "android"))))'.dependencies]
 raw-window-handle = "0.6"
 smithay-clipboard = "0.7"
 
-# macOS: drive a native NSCursor for a crisp hardware cursor. winit drives the cursor via AppKit
-# cursor-rects, which our continuous Metal render loop doesn't honor on mouse-move (custom cursor /
-# hide revert to the arrow); we bypass it with NSCursor + NSWindow::disableCursorRects. See
-# docs/knowledge/camera-control.md.
+# 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`).
 [target.'cfg(target_os = "macos")'.dependencies]
-# The audio device layer (decision 1857, `sound::output::coreaudio`): the HAL output unit through
-# coreaudio-rs's `AudioUnit`, and the AudioObject property/listener API through the objc2 CoreAudio
-# bindings — the two crates cpal itself stood on, now used directly. The versions are the ones the
-# graph already carries; the feature sets are the ones cpal proved to compile against.
+# 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.
 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"] }
@@ -178,20 +99,12 @@ objc2-app-kit = { version = "0.2", features = [
 ] }
 objc2-foundation = { version = "0.2", features = ["NSArray", "NSData", "NSGeometry"] }
 
-# Everywhere else: the same device layer over cpal (decision 1920, `sound::output::cpal`). 1857
-# owns the mix-ahead ring, the render thread and the meters on every platform; only the last
-# hop — find the default device, open a stream on it, hand back one buffer per cycle — is
-# platform code, and off macOS that hop is ALSA/PipeWire, WASAPI or the host's own API. cpal is
-# the layer that already speaks all of them; on macOS it is still not in the graph, because
-# there its defects (a no-op error callback on the default device, a pinned `DefaultOutput`
-# unit, the discarded IO-cycle timestamp) are exactly what 1857 went direct to escape. On an
-# unsupported target cpal compiles to its Null host, which reports no device — the same silent
-# posture the old `stub.rs` had, without a second file to rot.
+# 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.
 [target.'cfg(not(target_os = "macos"))'.dependencies]
 cpal = "0.17"
 
-# Windows: the journal's and the probes' CPU clocks (decision 2219, `perf::clock`) —
-# `GetProcessTimes`, `GetThreadTimes` and `GetSystemTimes`, the twins of the `getrusage`,
-# `clock_gettime` and `host_statistics64` arms. The version is one the graph already carries.
+# Windows CPU clocks for `perf::clock`: `GetProcessTimes`, `GetThreadTimes`, `GetSystemTimes`.
 [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 d2b71067..d6f168ae 100644
--- a/crates/benilla-app/assets/ui/ContainerFrameAdapters.xml
+++ b/crates/benilla-app/assets/ui/ContainerFrameAdapters.xml
@@ -1,65 +1,19 @@
 <!--
-    OUR adapters over the reference's own `Interface\FrameXML\ContainerFrame.xml`/`.lua`.
-
-    **This client does not transcribe those files — it EXECUTES them, off the player's own patch
-    chain** (decision 1751; `ui_script::reference_ui` carries the rule, and `benilla.toc` carries
-    the position). The bag windows on screen ARE `ContainerFrame1..12`. What is in THIS file is
-    only benilla's, and only where a reference body reaches for something this client genuinely
-    does not have.
-
-    The rule, restated in one line so it can be applied without re-reading the module: the sourced
-    file's globals stand unmodified; ours, loading after, win where both define a name; and where a
-    reference body needs a benilla answer, it is WRAPPED here — never silently stubbed.
-
-    TWO THINGS THIS FILE USED TO DO AND NO LONGER DOES, both retired by 1751's swap:
-    · It declared `ContainerFrameItemButtonTemplate`, transcribed from ContainerFrame.xml, because
-      the Lua could be sourced and the XML could not. The XML is sourced now, so the reference's
-      own declaration is the live one and the copy is deleted — the whole point of the migration.
-    · It defined `updateContainerFrameAnchors()` as a deliberate no-op, because the reference's
-      body walks twelve `ContainerFrame` windows this client did not build. It builds them, so the
-      reference's own body is correct here and the stub is deleted. Five corpus addons (Bongos,
-      Bongos_ActionBar, the CT_BarMod family) hook that global and call through; they now reach the
-      real thing.
-
-    ── The adapters, and why neither is a stub ──────────────────────────────────────────────────
-    `ContainerFrameItemButton_OnEnter` opens with a keyring fork (ref l.615-620):
-
-        if this:GetParent():GetID() == KEYRING_CONTAINER then
-            GameTooltip:SetInventoryItem("player", KeyRingButtonIDToInvSlotID(this:GetID()))
-            CursorUpdate()
-            return
-        end
-
-    That fork exists because the REAL client's keyring items are inventory slots, not container
-    slots, so it has to detour out of the container API to describe one. benilla's keyring is an
-    ordinary container (id -2, decision 0765): its slots come through `GetContainerItemInfo` and
-    `GameTooltip:SetBagItem` like every other bag's — which is exactly why the reference's keyring
-    WINDOW, its verbs and its sounds all take our keyring unchanged, and why this one line is the
-    only thing in that file the swap did not simply inherit. The detour is not merely unavailable
-    here (`KeyRingButtonIDToInvSlotID` is not a binding here) — it is *wrong* here, and supplying
-    the verb would buy an empty tooltip, because our keyring items were never fed into the
-    inventory-slot space it reads.
-
-    So the wrapper below answers the keyring case the way benilla answers every other bag, and
-    hands EVERY other slot straight to the reference's own body. The path the player is actually
-    on — hovering an ordinary bag slot — runs the real client's code, unedited.
-
-    ── Named, not hidden: what still does not work through the sourced files ────────────────────
-    · `REPAIR_COST` is read by the reference's repair-mode arm. It is a `GlobalStrings.lua` key and
-      this client sources that file too, so it resolves at runtime — and the arm is unreachable
-      today regardless, since `GameTooltip:SetBagItem`'s repairCost is an INTERIM 0.
-    · `NO_EMPTY_KEYRING_SLOTS` is read by the reference's `PutKeyInKeyRing` when the ring is full,
-      and no such GlobalString exists — 1.12 ships only `NO_EMPTY_KEYRING_SLOTS_ERROR`. That is a
-      REFERENCE BUG, and this client used to un-quirk it. It does not any more: the reference's own
-      file runs, so a full keyring prints the reference's own empty error line. Faithful, and
-      deliberately so (1751: a divergence becomes faithful or becomes a record, never silent).
+    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.
 -->
 <Ui xmlns="http://www.blizzard.com/wow/ui/">
     <Script><![CDATA[
-        -- The reference's own body, captured before we shadow the name. Nil on a machine with no
-        -- client data (nothing was sourced) — which must be LOUD at the call, not a quiet no-op:
-        -- a bag hover that silently does nothing is precisely the failure mode that let Bagnon
-        -- ship "working" through four green survey columns.
+        -- 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.
         local refItemButtonOnEnter = ContainerFrameItemButton_OnEnter
 
         function ContainerFrameItemButton_OnEnter(button)
@@ -68,9 +22,8 @@
             end
             if not button then return end
 
-            -- benilla's keyring is a CONTAINER (0765), so the reference's inventory-slot detour is
-            -- both unavailable and wrong here; this is the same pair of calls its general path
-            -- makes for every other bag, which is all a keyring slot ever needed.
+            -- 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.
             if button:GetParent():GetID() == KEYRING_CONTAINER then
                 if (button:GetRight() or 0) >= (GetScreenWidth() / 2) then
                     GameTooltip:SetOwner(button, "ANCHOR_LEFT")
@@ -90,50 +43,30 @@
             refItemButtonOnEnter(button)
         end
 
-        -- ══ The three bag verbs benilla answers differently (decisions 0561 + 1751) ═════════
-        --
-        -- `CloseAllBags`, `OpenBackpack` and `CloseBackpack` all exist in the sourced
-        -- `ContainerFrame.lua` too, and benilla's differ for one reason, not three: **0561, the
-        -- director's call that a window which opens your bags opens EVERY equipped bag**, not just
-        -- the backpack. The vendor/bank/mail/trade windows call `OpenBackpack` from their OnShow so
-        -- your bags come up with them and you can sell or deposit from one; the reference's own
-        -- body touches bag 0 alone. `CloseBackpack` is its inverse and has to match it, and
-        -- `CloseAllBags` is the same family's unconditional form.
-        --
-        -- **The `Benilla*` names, and the publish under them, are load ORDER** (1751). Order
-        -- decides every collision and the manifest is the order: this file loads after the
-        -- reference's `ContainerFrame.xml`, so the three publishes at the foot are the ones that
-        -- stand. The bodies lived in our UIParent.lua counterpart until 1988 retired it — a
-        -- harness with no bag stack now meets the loader's stand-ins for the three names
-        -- (`test_ui::UIPARENT_STAND_INS`), not a nil.
-        --
-        -- What CHANGED with the swap is only the plumbing: these used to walk five benilla windows
-        -- by name and stash `wasOpen` on each frame. The windows are the reference's recycled
-        -- `ContainerFrame1..12` now — frame N is a different bag every time it opens — so the
-        -- was-open memory is keyed by BAG ID, and every open and close goes through the
-        -- reference's own `OpenBag`/`CloseBag`/`IsBagOpen` rather than a raw Show/Hide. That buys
-        -- the reference's own guards for free (OpenBag's CanOpenPanels + NotWhileDeadError,
-        -- ToggleBag's `size > 0`) and means an addon replacing those verbs is honoured here too.
+        -- ══ 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.
         BENILLA_BAG_WAS_OPEN = {}
 
-        -- The UNCONDITIONAL close, called by ShowUIPanel's native-center branch above: a centre
-        -- frame takes the whole screen, so nothing is being "restored afterwards" the way a vendor
-        -- window restores the bags it opened, and the was-open memory is deliberately ignored.
-        -- Range 0..NUM_CONTAINER_FRAMES rather than the old five names — the reference's own
-        -- CloseAllBags covers the bank bags too (l.702-707), and now so does this.
+        -- 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).
         function BenillaCloseAllBags()
             for bagId = 0, (NUM_CONTAINER_FRAMES or -1) do
                 CloseBag(bagId)
             end
         end
 
-        -- OpenBackpack — 0561's all-bags form. A bag already open is REMEMBERED and left alone, so
-        -- the paired CloseBackpack does not close a window the player opened themselves; that
-        -- memory is the reference's own `backpackWasOpen`, one entry per bag instead of one flag.
+        -- 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.
         function BenillaOpenBackpack()
             for bagId = 0, (NUM_BAG_FRAMES or -1) do
-                -- The backpack always exists; an equipped-bag window only when a bag is in the
-                -- slot — `OpenBag` makes the same test itself, but the memory has to agree with it.
+                -- OpenBag's own test, repeated so the memory agrees with it: the backpack always,
+                -- another bag only when its slot holds one.
                 if bagId == 0 or GetContainerNumSlots(bagId) > 0 then
                     if IsBagOpen(bagId) then
                         BENILLA_BAG_WAS_OPEN[bagId] = 1
@@ -153,9 +86,8 @@
             end
         end
 
-        -- The publish — after the reference's container file, so these are the definitions that
-        -- stand (the stock `ShowUIPanel` calls `CloseAllBags` and the vendor's OnShow
-        -- `OpenBackpack`, and they reach 0561's bodies).
+        -- 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`).
         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 deec951e..72422d9b 100644
--- a/crates/benilla-app/assets/ui/GameMenuFrame.xml
+++ b/crates/benilla-app/assets/ui/GameMenuFrame.xml
@@ -1,106 +1,20 @@
 <Ui>
     <!--
-        The GAME MENU — the frame ESC opens (decision 0674). The last hole in the game shell's
-        outermost layer: until now ESC's chain ran out of things to close and did nothing, and the
-        Main Menu micro button was drawn but dead (our since-retired MicroMenu.xml's SCOPE note).
-
-        PROVENANCE (0985 — the three-source split, stated the same way in every era-shaped
-        window; OptionsFrame.xml carries the sibling block):
-        · STRUCTURE & BEHAVIOR — the 1.15 era client (wow-ui-source-era @ 1.15.9.68940): the
-          ladder shape, its groups and gaps, which entries exist (the SCOPE section below).
-          If 1.15 has the mechanism, it STAYS.
-        · CHROME MECHANISM — this window predates 1.13: the 1.12 client's OWN GameMenuFrame
-          is the chrome ground truth (the dialog backdrop, header plate, red buttons — the
-          same dialog family the 1.13/1.14 options windows kept), quoted below.
-        · ART BYTES — the 1.12 MPQ chain only; nothing later-client at runtime (0978's law).
-
-        Ground truth, all quoted rather than re-derived:
-        · **The frame** — ref `GameMenuFrame.xml` (patch.MPQ, extracted): 195x246, `frameStrata`
-          DIALOG, the UI-DialogBox backdrop with the 11/12/12/11 insets and 32px tile/edge, the
-          256x64 UI-DialogBox-Header at TOP +12 with MAIN_MENU centered 14px down it, and the
-          eight-button ladder — first button CENTER on the frame's TOP at (0,-37), each next one
-          TOP-to-BOTTOM at (0,-1), and Return to Game hung (0,-16) below Exit Game (the one gap in
-          the stack, which is what makes the last entry read as separate).
-        · **The button** — ref `GameMenuButtonTemplate` (UIPanelTemplates.xml l.403-410): a 144x21
-          `UIPanelButtonTemplate` (the UI-Panel-Button Up/Down/Disabled/Highlight four-state art,
-          TexCoords 0..0.625 / 0..0.6875) whose label trio is overridden to
-          GameFontHighlight/GameFontHighlight/GameFontDisable — i.e. the menu's labels are WHITE,
-          not the gold a normal panel button wears, and grey when disabled.
-        · **The labels** — GlobalStrings.lua (patch-2.MPQ), verbatim: VIDEOOPTIONS_MENU "Video
-          Options", SOUNDOPTIONS_MENU "Sound Options", UIOPTIONS_MENU "Interface Options",
-          MACROS "Macros", LOGOUT "Logout", EXIT_GAME "Exit Game",
-          RETURN_TO_GAME "Return to Game", MAIN_MENU "Main Menu". Declared as the real globals
-          (they are addon-visible API, decision 0068) and carried on each button's own
-          `text=` attribute — which this engine resolves as a global-string lookup exactly as
-          the reference does (decision 0995, `loader/widgets.rs`'s `resolve_text`).
-        · **The sounds** — the ref's own OnClick lines: igMainMenuOption (the five option buttons),
-          igMainMenuLogout, igMainMenuQuit, igMainMenuContinue. All four kits verified present in
-          SoundEntries.dbc (patch-2.MPQ) alongside the igMainMenuOpen/Close pair already in use.
-        · **The two logout dialogs** — ref `StaticPopup.lua` l.564-600 (CAMP + QUIT) is the
-          SPECIFICATION for them: the two dialog keys, the field names, the 20 s timeout and the
-          asymmetric button sets are contract, and the entries carrying them are written here in
-          our own shape on the shared popup engine (the stock StaticPopup), whose countdown-text branch
-          already lists both `which` names. Their driver events are the reference's own
-          (`re/events/event-catalog.tsv`: 276 PLAYER_CAMPING, 277 PLAYER_QUITING,
-          278 LOGOUT_CANCEL), fired by `crate::ui_logout` off `SMSG_LOGOUT_RESPONSE`.
-
-        NAMES are the reference's, unprefixed (`GameMenuFrame`, `GameMenuButton*`) — the same call
-        our retired MicroMenu.xml made for its straight transcriptions, and required here besides: `ToggleGameMenu`
-        and `GameMenuFrame` are Era API surface an addon addresses by name.
-
-        SCOPE / divergences (noted, not bugs):
-        - **The ladder is the ERA menu's** (director's call on the 0951 review — supersedes 0951
-          §3's five-button collapse): the Era client's own ESC menu shape, greyed where benilla
-          has nothing behind the entry yet. Geometry quoted from the era dump @ 1.15.9 (Gethe
-          wow-ui-source, classic_era, the 0950 pin):
-          · Blizzard_SharedXML/Classic/Frame/MainMenuFrameTemplates.xml l.18-33 — the menu is a
-            VerticalLayoutFrame, buttonTemplate MainMenuFrameButtonTemplate, padding
-            top/bottom/left/right = 32/28/28/28, spacing 0; l.11-16 — the button is a 144x21
-            UIPanelButtonTemplate with the white/white/grey label trio (the SAME art + trio the
-            1.12 GameMenuButtonTemplate carries — no era-only art in this menu at all).
-          · Shared/Frame/MainMenuFrameTemplates.lua l.61-71 — AddSection() puts a 20-unit gap
-            (the next button's topPadding) between groups; AddCloseButton uses the same 20.
-          · Shared/GameMenuFrame.lua l.62-162 — the Era ladder: Options · [gap] · AddOns, Edit
-            Mode, Support, Macros · [gap] · Logout, Exit Game · [gap] · Return to Game. (Store /
-            Rewards / What's New / Ratings are structurally off in Era — store disabled, no
-            account store, IsStandard() false, koKR only.)
-          · The layout math those constants produce, precomputed here (this engine has no layout
-            frames) — for OUR seven rungs, the era's eight minus AddOns (next bullet): width
-            28+144+28 = 200; button tops 32/73/94/115/156/177/218; height 218+21+28 = 267.
-            Anchored as a TOPLEFT chain so the gaps read in the XML.
-          · No Key Bindings rung — the era menu's own shape: 1.15 ceded the entry to the
-            Settings panel, and since decision 1008 ours lives there too (the Options window's
-            Keybindings category, KeyBindingsPage.xml). 0997 had carved the 1.13/1.14 seat back
-            in for its standalone window; that seat left with the window.
-          · No AddOns rung — the director's call: the char-select AddOns screen
-            (`char_select::addons`, the reference's own glue-side home for this list) is the only
-            addon UI. The in-game panel 1197 put behind this rung (AddonList.xml) is retired,
-            and the rung left with it — 1.12's own ESC menu has no AddOns row either.
-          · The header — Classic/Dialog/DialogTemplates.xml l.11-43 (ClassicDialogHeaderTemplate):
-            the same 256x64 UI-DialogBox-Header art, text = MAINMENU_BUTTON, swapped to
-            GameFontNormalMed1 (13px) by MainMenuFrameMixin:OnLoad. Both header idioms (1.12's
-            TOP+12 texture / era's 39-tall frame with the art centered) seat the art within half
-            a unit of each other; the 1.12 transcription is kept, the font and string are era's.
-        - **Edit Mode / Support ship DISABLED** — nothing behind them yet
-          (`GameMenuButton_Pending`): the template's own `-Disabled` art + grey label, exactly
-          how the era menu greys a dead entry (SetEnabled(false) → DisabledFont). Each goes live
-          by deleting one `GameMenuButton_Pending` call and writing its OnClick.
-        - The Options label stays a literal "Options": 1.12 GlobalStrings has no era
-          GAMEMENU_OPTIONS (checked; its OPTIONS_MENU is "Options Menu", a different string).
-        - The ref frame is `toplevel="true" movable="true" parent="UIParent"`. `parent="UIParent"` is
-          ours too, and it attaches for real: the loader does read a cross-file `parent=`, resolving
-          the name by global lookup at load (decision 1734), and the frame below declares it. Only
-          `movable` is dropped, and it is inert in the ref too (GameMenuFrame defines no drag
-          scripts, so it never actually moves).
-          `frameStrata="DIALOG"` is what puts it over the world UI, and that is kept.
-          **The "no frame-level raise" half of that reason is gone**: the raise law is built
-          (`script::object::toplevel`, wow-re `ui/scratch/toplevel-raise.md`), the loader honours
-          `toplevel="true"`, and the frame below carries it — so the Esc menu does come to the
-          front over any other DIALOG-strata frame it overlaps.
+        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.
     -->
     <Script><![CDATA[
-        -- The reference GlobalStrings (patch-2.MPQ Interface\FrameXML\GlobalStrings.lua), quoted
-        -- verbatim. `X = X or "..."` so a later real strings table wins, the retired MicroMenu.xml's idiom.
+        -- Label strings as `X = X or "..."`, so a stock GlobalStrings value wins where one exists.
         MAIN_MENU = MAIN_MENU or "Main Menu"
         HUD_EDIT_MODE_MENU = HUD_EDIT_MODE_MENU or "Edit Mode"
         GAMEMENU_SUPPORT = GAMEMENU_SUPPORT or "Support"
@@ -110,50 +24,29 @@
         RETURN_TO_GAME = RETURN_TO_GAME or "Return to Game"
         CANCEL = CANCEL or "Cancel"
 
-        -- One label setter for a button with nothing behind it yet (Edit Mode and Support): set
-        -- the ref's text, then disable (grey label + the template's -Disabled art). Making it
-        -- live is deleting the call and writing its ref OnClick.
+        -- 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.
         function GameMenuButton_Pending(button, text)
             button:SetText(text)
             button:Disable()
         end
 
-        -- ══ THE THREE STOCK CONSUMERS THAT ASK "IS AN OPTIONS WINDOW OPEN?" (decision 2177) ══
-        -- All three are the reference's own, off the chain, and all three name the reference's
-        -- three windows literally. Two of those names are now REAL hidden stock frames
-        -- (`SoundOptionsFrame` since 2147, `UIOptionsFrame` since 2115) and the third,
-        -- `OptionsFrame`, became one when the stock VIDEO window joined the manifest — so the
-        -- whole chain now reads "no", always, while the window the player actually opens is up.
-        -- Until then `OptionsFrame` WAS our window and every one of them answered by accident.
-        --
-        -- **Wrappers, not replacements.** Each stock function keeps running and keeps deciding;
-        -- ours adds the one term the reference could not know about. A rewrite would be thirty
-        -- lines of the reference's ladder copied into our tree to drift.
-        --
-        -- **HERE, not in `OptionsFrame.xml`, because of load order.** `UpdateMicroButtons` is
-        -- defined by `MainMenuBarMicroButtons.xml`, manifest l.576 — AFTER our options window at
-        -- l.522, where a wrapper would capture a nil. This file is the manifest's LAST row
-        -- (l.1273), so all three exist. It is also the right home on the merits: this is the ESC
-        -- menu, and these three are exactly "the ESC ladder and the micro button know about our
-        -- options window".
+        -- ══ 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.
         local Ref_IsOptionFrameOpen = IsOptionFrameOpen
         local Ref_ToggleGameMenu = ToggleGameMenu
         local Ref_UpdateMicroButtons = UpdateMicroButtons
 
-        -- The one term all three add. Existence-guarded because these three wrappers stand in a
-        -- file that can be seated without the options window: in the client `BenillaOptionsFrame`
-        -- is manifest row 38 and this file is the last row, so it is always real — but a test kit
-        -- that seats the game menu alone must get "no options window is open", not a raise inside
-        -- the ESC handler.
+        -- Guarded for a test kit that loads the game menu without the options window.
         local function BenillaOptions_IsOpen()
             return BenillaOptionsFrame and BenillaOptionsFrame:IsVisible()
         end
 
-        -- `UIParent.lua:996`. One caller: `CloseAllWindows_WithExceptions`, which passes
-        -- `ignoreCenter = 1` when an options window is up so the ESC sweep does not close the
-        -- centre panel out from under it. Ours IS the centre panel (`UIPanelWindows` row,
-        -- `area = "center"`), so answering "no" would have ESC close it through the sweep instead
-        -- of through its own rung, discarding pending edits with no Cancel semantics.
+        -- `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.
         function IsOptionFrameOpen()
             if BenillaOptions_IsOpen() then
                 return 1
@@ -161,20 +54,13 @@
             return Ref_IsOptionFrameOpen()
         end
 
-        -- `UIParent.lua:1465-1497`. The ESC ladder, and the rung matters as much as the answer:
-        -- the reference tries the static popup FIRST, then an open options window, then the game
-        -- menu. So this runs that first rung itself and returns if it fired — `StaticPopup_Escape        -- Pressed` is a pure scan when nothing is shown (`StaticPopup.lua:1879-1893`), so the
-        -- delegate below re-running it costs nothing and changes nothing — then takes the options
-        -- rung, then hands the rest of the ladder back untouched.
-        --
-        -- The close is our own Close button's click, which is the same discard-and-hide the
-        -- reference reaches through `OptionsFrameCancel:Click()`: our `<OnHide>` drops the pending
-        -- page. (That alias is retired — `OptionsFrameCancel` is the stock video window's own
-        -- button now, and ours loading later would have clobbered it.)
+        -- `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()`.
         function ToggleGameMenu(clicked)
             if clicked then
-                -- The reference's `clicked` arm closes an open options window and then goes on to
-                -- toggle the game menu, rather than returning. Same here.
+                -- As the reference's `clicked` arm: close an options window, then still toggle.
                 if BenillaOptions_IsOpen() then
                     BenillaOptionsFrameCloseButton:Click()
                 end
@@ -190,17 +76,9 @@
             return Ref_ToggleGameMenu(clicked)
         end
 
-        -- `MainMenuBarMicroButtons.lua:47-58`. A POST-hook that can only ever push the button, never
-        -- release it: the reference has already decided from the six frames it knows, and this adds
-        -- the seventh. Written this way round so it cannot fight that decision — a wrapper that also
-        -- set NORMAL would be a second copy of the reference's whole `or` chain.
-        --
-        -- **Existence-guarded, and only here.** The shipped manifest always carries
-        -- `MainMenuBarMicroButtons.xml`, so in the client `Ref_UpdateMicroButtons` and
-        -- `MainMenuMicroButton` are always real. A partial test kit that seats this file and not
-        -- the micro bar is the case the guards are for, and a guard is the honest answer there:
-        -- there is no micro button to push, so there is nothing to do — as against a raise inside
-        -- an unrelated window's OnShow, which is what an unguarded wrapper turns that into.
+        -- `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.
         function UpdateMicroButtons()
             if Ref_UpdateMicroButtons then
                 Ref_UpdateMicroButtons()
@@ -210,35 +88,20 @@
             end
         end
 
-        -- The CAMP/QUIT dialogs and the three-event driver MOVED OUT, to our UIParent.lua counterpart (the stock UIParent.lua since 1988) — the
-        -- reference's own homes for both (StaticPopup.lua l.564/586; UIParent.lua l.304-315).
-        -- They were here only because this is where they were first needed, and 1751 moving them
-        -- is one less thing to carry when this window follows them onto the chain.
     ]]></Script>
 
-    <!-- The era header text size (Classic/Dialog/DialogTemplates.xml + the OnLoad font swap):
-         GameFontNormalMed1 = SystemFont_Med2 = FRIZQT 13, gold, the MasterFont shadow. Era's
-         name, declared here beside its one consumer (the 0951 residue convention: Fonts.xml
-         stays the complete 1.12 set). -->
+    <!-- The era's header font, GameFontNormalMed1 (FRIZQT 13, gold): an era name 1.12's Fonts.xml
+         lacks, declared beside its one consumer. -->
     <Font name="GameFontNormalMed1" inherits="GameFontNormal" virtual="true">
         <FontHeight><AbsValue val="13"/></FontHeight>
     </Font>
 
-    <!-- `GameMenuButtonTemplate` MOVED OUT, to UIPanelTemplates.xml — the reference's own file for
-         it (ref UIPanelTemplates.xml l.403-410), and now ColorPickerFrame.xml's Okay/Cancel need it
-         too, from far above this file's LAST-in-the-toc seat. It lived here, with its four state
-         textures inlined, only because `UIPanelButtonTemplate` had not been transcribed yet; it now
-         has been, so the reference's actual body (`inherits="UIPanelButtonTemplate"`, 144x21, the
-         white/white/grey label trio) replaces the private copy verbatim. Era's
-         MainMenuFrameButtonTemplate (Classic/Frame/MainMenuFrameTemplates.xml l.11-16) is that same
-         button — same art, same trio, same size — so the header's ART BYTES note is unchanged. -->
 
-    <!-- `toplevel` is the ref's own (GameMenuFrame.xml l.3) and was dropped here: without the bit
-         a DIALOG-strata window opened over another one stays behind it (the B180/Bagnon class,
-         decision 1318). Restored alone; the ref's `movable`/`parent` stay off deliberately. -->
+    <!-- The reference frame's attributes (GameMenuFrame.xml l.3) except `movable`, which is inert
+         there: the reference defines no drag scripts. -->
     <Frame name="GameMenuFrame" parent="UIParent" frameStrata="DIALOG" toplevel="true" enableMouse="true" hidden="true">
-        <!-- The era layout engine's own numbers (header SCOPE note): 28+144+28 wide, 32-top /
-             28-bottom padding around our seven 21-unit rungs with three 20-unit section gaps. -->
+        <!-- The era layout: 28+144+28 wide; 32 top and 28 bottom padding around seven 21-unit
+             rungs and three 20-unit section gaps. -->
         <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">
@@ -252,9 +115,8 @@
                     <Size><AbsDimension x="256" y="64"/></Size>
                     <Anchors><Anchor point="TOP"><Offset><AbsDimension x="0" y="12"/></Offset></Anchor></Anchors>
                 </Texture>
-                <!-- Era swaps the header text to 13px (MainMenuFrameMixin:OnLoad →
-                     SetHeaderFont(GameFontNormalMed1)); the seat is the 1.12 one (within half a
-                     unit of era's — header SCOPE note). -->
+                <!-- The era's 13px header font (MainMenuFrameMixin:OnLoad) on the 1.12 seat, which
+                     is 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>
@@ -263,18 +125,10 @@
             </Layer>
         </Layers>
         <Frames>
-            <!-- The era ladder minus its AddOns rung (header SCOPE notes): Options · gap ·
-                 Edit Mode, Support, Macros · gap · Logout, Exit Game · gap · Return to Game.
-                 A TOPLEFT chain at the era layout engine's numbers — x 28, first top -32, 0
-                 between group members, -20 at each section break. Live entries wire the era
-                 OnClick intent; pending ones grey out through GameMenuButton_Pending until
-                 something exists behind them. -->
 
-            <!-- Options — live: the era GameMenuFrame.lua l.88 entry (ShowUIPanel(SettingsPanel)
-                 there, BenillaOptionsFrame here) plus an explicit HideUIPanel first. The ref leans on
-                 the center-replacement rule for the swap (ShowUIPanel l.697-702: native-center
-                 frames replace each other); hiding the menu explicitly says the same thing
-                 without relying on the eviction path. -->
+            <!-- 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". -->
             <Button name="GameMenuButtonOptions" inherits="GameMenuButtonTemplate" text="Options">
                 <Anchors>
                     <Anchor point="TOPLEFT"><Offset><AbsDimension x="28" y="-32"/></Offset></Anchor>
@@ -304,8 +158,7 @@
                 <Anchors>
                     <Anchor point="TOPLEFT" relativeTo="GameMenuButtonSupport" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="0"/></Offset></Anchor>
                 </Anchors>
-                <!-- LIVE since decision 0983 (MacroFrame.xml). The ref's own body
-                     (GameMenuFrame.xml l.118-122): hide the menu, then ShowMacroFrame(). -->
+                <!-- The reference's body (GameMenuFrame.xml l.118-122). -->
                 <Scripts>
                     <OnClick>
                         PlaySound("igMainMenuOption")
@@ -315,10 +168,8 @@
                 </Scripts>
             </Button>
 
-            <!-- The three that are live. The ref's OnShow on both Logout and Quit disables the
-                 button while either logout dialog is already up (you cannot re-arm a running
-                 countdown); it runs on the menu's own show, which is when a re-opened menu has to
-                 re-read that state. -->
+            <!-- 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. -->
             <Button name="GameMenuButtonLogout" inherits="GameMenuButtonTemplate" text="LOGOUT">
                 <Anchors>
                     <Anchor point="TOPLEFT" relativeTo="GameMenuButtonMacros" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-20"/></Offset></Anchor>
@@ -369,23 +220,14 @@
                 </Scripts>
             </Button>
         </Frames>
-        <!-- ref GameMenuFrame OnShow/OnHide, verbatim: the micro row's Main Menu button pushes in
-             while the menu is up, and the bag bar greys out under it (you cannot open bags from
-             behind the menu — ShowUIPanel's center gate would refuse the window anyway, so the
-             greying is the visible half of a rule the panel manager already enforces). Guarded, in
-             the `CloseMenus and CloseMenus()` posture our retired panel file used: a headless test
-             loads this file without the action bar behind it. -->
+        <!-- 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. -->
         <Scripts>
             <OnShow>
-                -- The shared era-window scale first (ERA_WINDOW_SCALE, OptionsFrame.xml — loaded
-                -- before this file): the era menu has no scale of its own (GameMenuFrame.xml +
-                -- MainMenuFrameTemplates, grepped clean), it draws at UIParent's px-per-unit —
-                -- the SAME density as the era options window, whose checkFit caps at 1. The knob
-                -- is our stand-in for that UIParent scale; without it the menu drew 28% larger
-                -- relative to the options window than the era pair ("esc menu scale too big" —
-                -- director, 2026-08-04). `or 1` guards a load-order regression only. NOTE: this
-                -- lives INSIDE the existing OnShow — a second Scripts/OnShow block on the same
-                -- frame would silently REPLACE this one (SetScript semantics: last wins).
+                -- 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.
                 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 f25a4bde..2c316954 100644
--- a/crates/benilla-app/assets/ui/KeyBindingsPage.xml
+++ b/crates/benilla-app/assets/ui/KeyBindingsPage.xml
@@ -1,77 +1,24 @@
 <Ui>
     <!--
-        The KEY BINDINGS page (decision 1008, superseding 0997's standalone window) — the
-        Options window's Keybindings category, over the engine's binding table
-        (benilla_ui::script::keybind + crate::bindings — GetNumBindings/GetBinding/SetBinding/
-        GetBindingKey/GetBindingAction/LoadBindings/SaveBindings/GetCurrentBindingSet, the 1.12
-        Lua API verbatim). This file is the page MODULE: the templates and the whole script; the
-        page's static furniture (the rows, the checkbox row, the scroll seam, the search rows)
-        lives in OptionsFrame.xml as ordinary children of its Keybindings body, inheriting these
-        templates (manifest order puts this file first). Rows are the HONEST TREE: only commands
-        the engine really dispatches are registered, so only they (and only their non-empty
-        categories) appear.
-
-        PROVENANCE (0985 — the three-source split; OptionsFrame.xml carries the sibling block):
-        · STRUCTURE & BEHAVIOR — the era Settings panel's own Keybindings page (wow-ui-source-era
-          @ 1.15.9.68940: Blizzard_SettingsDefinitions_Frame/Keybindings.lua + Classic/
-          KeybindingsOverrides.lua + Blizzard_Settings_Shared/Blizzard_Keybindings.*): 1.15 put
-          keybindings INSIDE the Options window — the director's call this move executes — as
-          ONE list of EXPANDABLE per-category sections (SettingsKeybindingSectionMixin over
-          SettingsExpandableSectionMixin; 25-tall rows, sections COLLAPSED by default, categories
-          in first-appearance order, a bar's section existing only when the bar does — their
-          PROXY_SHOW_ACTIONBAR_N gate is our honest tree), the Character Specific Keybindings
-          checkbox as the page's first row (PROXY_CHARACTER_SPECIFIC_BINDINGS, confirm popup on
-          UNCHECK only), and per-binding search tags whose category REDIRECTS to this page
-          (Blizzard_SettingsPanel.lua l.578 `category.redirectCategory or category`) with the
-          matched rows LIVE in the results.
-        · CAPTURE & SET LAW — 1.12's own Blizzard_BindingUI (extracted from patch.MPQ, 0997),
-          KEPT over the era's listener where they differ (the game's fidelity truth is 1.12;
-          the window furniture is the era's): click a key capsule to arm; the next key or
-          mouse-3/4/5 press binds IMMEDIATELY (the host capture seam hands the canonical
-          ALT-CTRL-SHIFT chord to KeyBindings_OnHostKey); a stolen key names its victim in red
-          (KEY_UNBOUND_ERROR) only when the victim goes bare; left/right clicks select/deselect,
-          never bind; lone modifiers are ignored; the wheel binds like any other key, to ANY
-          command (decision 1295 — SetBinding refuses nothing but a key string that is not a key,
-          and the KEYBINDINGFRAME_MOUSEWHEEL_ERROR arm below is that refusal's message, not a
-          wheel rule); ESC while armed BINDS Escape (1.12's OnKeyDown has no ESCAPE filter — the
-          era's ESC-cancels law is the one era behavior NOT taken, recorded in 1008; the Unbind
-          Key button is the clearing affordance). ESC with nothing armed never reaches any of
-          this: the ladder is the TOGGLEGAMEMENU binding, and the armed seam swallows the press.
-        · ART BYTES — the 1.12 MPQ chain only (0978/0985): the capsules wear 1.12's own
-          UIPanelButtonTemplate2 panel-button art (the Classic client's silver stretch set —
-          UI-Silver-Button-Up/-Down/-Highlight/-Select, a 9-slice — is VERIFIED ABSENT from
-          the 1.12 chain: 0997, re-pinned and reverted-to-red in 1088 after 1085's gray-dress
-          detour), selection is 1.12's LockHighlight glow; section headers wear the 1.12
-          collapsible-list dress — the QuestLog's own UI-PlusButton/UI-MinusButton square
-          and gold label.
-
-        COMMIT LAW (1008, the page's one big behavior change from 0997): binds are LIVE-COMMIT.
-        The options window's whole grammar writes live (SetCVar on click, no Okay/Cancel pair),
-        and the era Settings panel commits keybinds as they land too — so every successful
-        bind/steal/unbind/reset saves the current set to disk at once
-        (SaveBindings(GetCurrentBindingSet())); 0997's Okay/Cancel/revert and the
-        CONFIRM_LOSE_BINDING_CHANGES popup die with the standalone window. The two destructive
-        gestures keep their confirms: Reset To Default (the page Defaults button) and leaving
-        the character-specific set (which permanently deletes it).
-
-        All strings are the 1.12 GlobalStrings globals (the VM executes the real file at boot)
-        through the `getglobal(...) or raw` fallback (the era's own `_G[x] or x` posture), so a
-        headless test without GlobalStrings still renders raw tokens.
-
-        SCOPE / divergences (noted, not bugs — the ledger is 1008):
-        - No Quick Keybind Mode row (era furniture over an overlay mechanism benilla lacks).
-        - 1.12's BLANK spacer-headers between multibar blocks are not modeled — both bottom
-          bars sit under the one MultiActionBar section.
-        - 1.12's "Key Bindings for <name>" title swap died with the standalone window: the page
-          title stays the category's, the checkbox is the character-set state (era's own shape).
-        - Search shows at most KEYBINDINGS_SEARCH_ROWS matched bindings (static row pool; the
-          era's results list scrolls, ours doesn't yet) — the group head jumps to the full page.
+        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).
+        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.
     -->
 
-    <!-- One KEY CAPSULE (1.12 KeyBindingFrameBindingButtonTemplate: UIPanelButtonTemplate2 at
-         180x22 with the small-highlight font trio; its RegisterForClicks takes all five
-         buttons so middle/4/5 presses reach the capture law). The SELECTED state is 1.12's
-         LockHighlight — the ADD highlight held on. -->
+    <!-- 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. -->
     <Button name="KeyBindingButtonTemplate" virtual="true">
         <Size><AbsDimension x="180" y="22"/></Size>
         <ButtonText name="$parentText"/>
@@ -87,14 +34,10 @@
         </Scripts>
     </Button>
 
-    <!-- One LIST ROW, dual-mode (the era list mixes section headers and binding rows in one
-         25-tall rhythm — SettingsKeybindingSectionInitializer:GetExtent's single bindingHeight).
-         BIND mode: command name 170 wide at LEFT, the two capsules at 175/355 (0997's seats,
-         kept). HEADER mode: the whole row is one toggle button wearing 1.12's own collapsible
-         dress — the QuestLogTitleButton's 16x16 UI-Plus/MinusButton square at LEFT and the gold
-         label (the era's Options_ListExpand arrows have no 1.12 counterpart). The paint
-         (KeyBindings_PaintBindRow / _PaintHeaderRow) shows one mode's furniture and hides the
-         other's. -->
+    <!-- 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). -->
     <Frame name="KeyBindingRowTemplate" virtual="true">
         <Size><AbsDimension x="560" y="25"/></Size>
         <Layers>
@@ -141,19 +84,17 @@
     </Frame>
 
     <Script><![CDATA[
-        -- ── Strings ── the 1.12 GlobalStrings globals, each with the raw fallback (a headless
-        -- harness without GlobalStrings still works; the era's own `_G[x] or x` posture).
+        -- ── Strings ── a 1.12 GlobalStrings global, or the fallback for a harness without them.
         function KeyBindings_String(name, fallback)
             local s = getglobal(name)
             if s then return s end
             return fallback
         end
 
-        -- ── Key display ── the 1.12 GetBindingText law by hand: modifier prefixes stay the
-        -- canonical uppercase tokens, the base key reads its KEY_* global (Spacebar, Up Arrow,
-        -- Mouse Button 4...) else itself. "CTRL--" renders CTRL + the minus key. (The action
-        -- bar's ABBREVIATED labels ride the stock GetBindingText (UIParent.lua);
-        -- this page and the tooltips show the full form, both references' own split.)
+        -- ── 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.
         function KeyBindings_KeyText(key)
             if not key then
                 return NORMAL_FONT_COLOR_CODE .. KeyBindings_String("NOT_BOUND", "Not Bound") .. FONT_COLOR_CODE_CLOSE
@@ -178,10 +119,9 @@
             return prefix .. KeyBindings_String("KEY_" .. rest, rest)
         end
 
-        -- ── Page state ── no root frame anymore: the page's state lives here. `sections` is the
-        -- era section model; `selected`/`keyID` the 1.12 selection; `searchPainted` the live
-        -- search-result rows (rowName → binding index), set by OptionsFrame.xml's search display
-        -- and repainted after a bind lands on one.
+        -- ── 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).
         KeyBindingsPage = { sections = {}, items = {} }
 
         KEYBINDINGS_ROW_BASE = "BenillaOptionsFrameContainerBodyKeybindingsRow"
@@ -189,10 +129,9 @@
         KEYBINDINGS_ROW_HEIGHT = 25
         KEYBINDINGS_SEARCH_ROWS = 8
 
-        -- ── The section model (era CreateKeybindingInitializers, cut to the honest tree): walk
-        -- GetBinding(i), group runs of one category token; order = first appearance, which IS
-        -- 1.12's Bindings.xml order (the registry registers in it). Sections default COLLAPSED
-        -- (the era Classic overrides pass no `expanded`); a rebuild keeps each token's state.
+        -- ── 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.
         function KeyBindings_BuildSections()
             local page = KeyBindingsPage
             local was = {}
@@ -214,8 +153,8 @@
             KeyBindings_Flatten()
         end
 
-        -- The flattened visible list (era EvaluateVisibility): every header, then the expanded
-        -- sections' rows. The faux scroll runs over this.
+        -- The visible list the faux scroll runs over (the era's EvaluateVisibility): each header,
+        -- then its rows when expanded.
         function KeyBindings_Flatten()
             local page = KeyBindingsPage
             page.items = {}
@@ -229,8 +168,7 @@
             end
         end
 
-        -- The expand/collapse click (era OnExpandedChanged; the sound is the checkbox kit's,
-        -- the page's one click voice).
+        -- A header click (the era's OnExpandedChanged), voiced with the checkbox sound.
         function KeyBindings_ToggleSection(n)
             local sec = KeyBindingsPage.sections[n]
             if not sec then return end
@@ -240,8 +178,7 @@
             KeyBindingsPage_Update()
         end
 
-        -- Expand/collapse by section index without the click voice — the capture fixture uses
-        -- it to open a section for the lens.
+        -- Expands or collapses a section silently; the capture fixture opens sections with it.
         function KeyBindings_ExpandSection(n, on)
             local sec = KeyBindingsPage.sections[n]
             if not sec then return end
@@ -249,9 +186,8 @@
             KeyBindings_Flatten()
         end
 
-        -- ── Painters ── one row, one mode. Shared by the list repaint and the search rows
-        -- (which are the SAME template painted bind-mode — the era reflows live rows into its
-        -- results, and these capsules run the full capture law in place).
+        -- ── 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.
         function KeyBindings_PaintBindRow(name, index)
             local command, _, key1, key2 = GetBinding(index)
             local b1 = getglobal(name .. "Key1Button")
@@ -265,7 +201,6 @@
             local desc = getglobal(name .. "Description")
             desc:SetText(KeyBindings_String("BINDING_NAME_" .. command, command))
             desc:Show()
-            -- The 1.12 selection highlight: the pressed capsule holds its glow.
             local page = KeyBindingsPage
             if page.selected == command and page.keyID == 1 then
                 b1:LockHighlight()
@@ -320,16 +255,14 @@
             end
             FauxScrollFrame_Update(scroll, table.getn(page.items),
                 KEYBINDINGS_DISPLAYED, KEYBINDINGS_ROW_HEIGHT)
-            -- The trough is OURS — the reference has no trough at all, so nothing in its kit shows
-            -- one. The owner pairs it with the bar the reference's `_Update` just decided about
-            -- (1860); `BenillaScrollBar_SetShown` used to do it and is off this path now.
+            -- The trough is ours and the stock kit never shows one, so it follows the bar
+            -- `FauxScrollFrame_Update` has just shown or hidden.
             BenillaScrollTrough_Follow(scroll:GetName())
             KeyBindings_UpdateUnbindKey()
         end
 
-        -- The page entry (BenillaOptionsFrame_SelectCategory's Keybindings arm): rebuild the tree —
-        -- the table may have moved under us (a rebind, a set switch) — sync the checkbox to
-        -- the live set, park the scroll at the top, repaint.
+        -- 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.
         function KeyBindingsPage_Refresh()
             KeyBindings_BuildSections()
             local box = getglobal("BenillaOptionsFrameContainerBodyKeybindingsCharacterRowCheck")
@@ -346,9 +279,9 @@
             getglobal("BenillaOptionsFrameContainerBodyKeybindingsOutput"):SetText(text)
         end
 
-        -- ── Selection + the capture arm ── selecting a capsule arms the HOST's capture seam
-        -- (BenillaBindCapture): raw input is swallowed there and comes back canonical through
-        -- KeyBindings_OnHostKey. Deselecting (either way) disarms.
+        -- ── Selection ── selecting a capsule arms the host's capture (BenillaBindCapture), which
+        -- swallows raw input and hands the canonical chord to KeyBindings_OnHostKey; deselecting
+        -- disarms.
         function KeyBindings_SetSelected(command, keyID)
             KeyBindingsPage.selected = command
             KeyBindingsPage.keyID = keyID
@@ -364,9 +297,8 @@
             end
         end
 
-        -- Repaint whichever view currently shows binding rows: the page list, or the live
-        -- search-result rows (a bind landed from one must relabel it — and its victim, which
-        -- may sit on another visible row).
+        -- 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.
         function KeyBindings_RepaintVisible()
             if KeyBindingsPage.searchPainted then
                 for name, index in pairs(KeyBindingsPage.searchPainted) do
@@ -379,10 +311,9 @@
         end
 
         function KeyBindingButton_OnClick(button)
-            -- The 1.12 law: while something is selected, only LEFT/RIGHT on a capsule
-            -- re-select or deselect — a middle/4/5 press is a BIND, and the host's armed
-            -- capture seam (which runs after this click) takes it, so this handler must not
-            -- touch the selection for those buttons.
+            -- 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.
             local page = KeyBindingsPage
             if page.selected then
                 if button ~= "LeftButton" and button ~= "RightButton" then
@@ -406,15 +337,14 @@
             KeyBindings_RepaintVisible()
         end
 
-        -- The live-commit half of every mutation (1008's commit law — the header block): the
-        -- table already moved; persist the set it belongs to.
+        -- 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` is canonical (ALT-CTRL-SHIFT-TOKEN). The body is
-        -- 1.12's OnKeyDown selected-branch verbatim: steal message, clear the command's keys,
-        -- rebind in slot order so the pressed slot takes the new chord — then the live commit.
+        -- 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.
         function KeyBindings_OnHostKey(chord)
             local page = KeyBindingsPage
             if not page.selected then
@@ -449,11 +379,9 @@
             KeyBindings_RepaintVisible()
         end
 
-        -- 1.12 KeyBindingFrame_SetBinding, kept verbatim: a refused bind restores the slot's old
-        -- key and says why. The reference wrote this arm with the wheel in mind and named its
-        -- string for it, but the engine refuses only a key string that is not a key
-        -- (decision 1295), so this fires for a chord the capture seam could not name — never for
-        -- a wheel notch. The message stays 1.12's; ours is not the place to correct Blizzard.
+        -- 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.
         function KeyBindings_SetOrRestore(key, command, oldKey)
             if not SetBinding(key, command) then
                 if oldKey then SetBinding(oldKey, command) end
@@ -463,8 +391,8 @@
             end
         end
 
-        -- The Unbind Key button (the Container header band, OptionsFrame.xml): 1.12's body —
-        -- the selected slot empties, the other slides into slot order — plus the live commit.
+        -- 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.
         function KeyBindings_Unbind()
             local page = KeyBindingsPage
             local key1, key2 = GetBindingKey(page.selected)
@@ -481,14 +409,12 @@
             KeyBindings_RepaintVisible()
         end
 
-        -- ── The character-specific set (1.12's three-set model under the era checkbox row) ──
-        -- CHECK: switch to the character set and save it at once — it starts as a copy of what
-        -- you had (LoadBindings(2) falls back to the account snapshot; SaveBindings(2) makes it
-        -- exist, which IS the checkbox's persisted truth). UNCHECK: destructive — the era
-        -- confirm-on-uncheck-only law; the box springs back until the popup decides. The accept
-        -- order is load-then-save: LoadBindings(1) puts the account set live FIRST, so
-        -- SaveBindings(1) persists it unchanged while dropping the character set (the confirmed
-        -- permanent delete — saving live-as-account here would smuggle the character binds in).
+        -- ── 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.
         function KeyBindings_CharacterToggle(box)
             PlaySound("igMainMenuOptionCheckBoxOn")
             if box:GetChecked() then
@@ -516,9 +442,8 @@
                 KeyBindingsPage_Refresh()
             end,
         }
-        -- Reset To Default — the page's Defaults button (era: Defaults confirms; the string is
-        -- ours, 0997's note: the era's lives in its client binary, 1.12 has none). The reset
-        -- lands in the CURRENT set and commits live like every other mutation.
+        -- 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.
         StaticPopupDialogs["CONFIRM_RESET_KEYBINDINGS"] = {
             text = "Are you sure you want to reset all keybindings to their defaults?",
             button1 = KeyBindings_String("OKAY", "Okay"),
@@ -533,12 +458,11 @@
             end,
         }
 
-        -- ── Search (the era redirect law) ── every binding's search tag is its display name
-        -- uppercased (era AddSearchTags(GetBindingName(action))); matches score by the shared
-        -- law (OptionsSearch_Score) and surface under the Keybindings group head, whose click
-        -- jumps to this page (era Blizzard_SettingsPanel.lua l.578: the fake category's results
-        -- carry `redirectCategory`). The matched rows are LIVE (era reflows real initializers);
-        -- OptionsFrame.xml paints them onto its static KeybindSearch row pool.
+        -- ── 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.
         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 7646d50d..71e19e82 100644
--- a/crates/benilla-app/assets/ui/OptionsFrame.xml
+++ b/crates/benilla-app/assets/ui/OptionsFrame.xml
@@ -1,178 +1,18 @@
 <Ui>
     <!--
-        The OPTIONS window (decision 0950) — the shell (slice A) and the real PAGES: Audio
-        (0957), Graphics (0959), Controls (0961), Nameplates (0992, with the dropdown row
-        shape). Opened from the game menu's Options button.
-        Setting rows ride the CVar store (0954): rows read GetCVar on show, write SetCVar on
-        interaction, and Defaults resets the visible page's CVars to their registered defaults.
-        Pages without rows are still empty and keep Defaults disabled. One row defers — uiScale
-        stages a pending value and commits through the era Apply button (0961), because a live
-        write would rescale the very slider being dragged.
-
-        PROVENANCE (0985 — the three-source split, stated the same way in every era-shaped
-        window; GameMenuFrame.xml carries the sibling block):
-        · STRUCTURE & BEHAVIOR — the 1.15 era client (wow-ui-source-era @ 1.15.9.68940):
-          layout, geometry grammar, interaction, functionality — the single all-in-one
-          window, the category tree, the search, the Apply flow. If 1.15 has the mechanism,
-          it STAYS, even where the older clients had none — except a DIRECTED CUT the
-          director makes on look, each recorded (0989: the slider steppers and the corner
-          close X; the split bends to taste only by record, never silently).
-        · CHROME MECHANISM — the 1.13/1.14 clients' own UI source (wow-ui-source @ 1.14.4,
-          their System window family; 0981/0984): HOW surfaces are textured — the dialog
-          backdrop, the outline boxes, the title plate, the select/hover washes and their
-          tints, the hairlines. Geometry may bend where 1.15 furniture needs a seat (the
-          -52 band below); the mechanism holds.
-        · ART BYTES — the 1.12 MPQ chain only, or a plain color fill (0978 retired every
-          era-atlas extraction and the `era:` scheme; one install, nothing later-client at
-          runtime).
-        So: the 1.12 OptionsFrame family (four separate panels) collapses into the era's
-        single window — a category list, one page area — every texture 1.12-native. The era
-        art names in the bullets below stay as GEOMETRY CITATIONS, not drawn art:
-        · **Root** — Blizzard_SettingsPanel.xml `SettingsPanel`: 920x724, CENTER, strata HIGH,
-          hidden. Skin per `SettingsFrameTemplate` (Classic/Blizzard_SettingsPanelTemplates.xml):
-          FlatPanelBackgroundTemplate at TOPLEFT (7,-18) → BOTTOMRIGHT (-3,3), the
-          `ButtonFrameTemplateNoPortrait` nine-slice (Classic/NineSliceLayouts.lua l.132 — right
-          edge x=-8/x1=8), the `_UI-Frame-TitleTileBg` title band (256x17, TexCoords
-          .2890625/.421875, TOPLEFT (8,-3) → TOPRIGHT (0,-3)), title GameFontNormal TOP (0,-5).
-        · **Category list** — Blizzard_CategoryList.xml + .lua: rows/headers STRETCH to the
-          scroll target's width (199, no scroll bar); header 30 tall (label 14px white at
-          LEFT (20,-1), Options_CategoryHeader_<n> wash at TOPLEFT at atlas size, n cycling
-          per header); row 20 tall (label GameFontNormal TOPLEFT (36,+1); bg CENTER —
-          options_list_active selected / options_list_hover hover, at atlas size); 2 between
-          elements, 18-tall spacer between groups (so 22 row-to-header).
-        · **Page area** — Blizzard_SettingsList.xml: title 20px white TOPLEFT (7,-22), the
-          options_horizontaldivider at TOP (0,-50), Defaults 96x22 at TOPRIGHT (-36,-16).
-        · **Tabs** — SharedXML Shared/Tabs/MinimalTab.{xml,lua}: a bottom-anchored three-slice
-          of Options_Tab[_Active]_{Left,Middle,Right}, GameTab TOPLEFT (32,-27) h37, AddOnsTab
-          5 right of it; width text+40; selected = white small text at BOTTOM+6, unselected =
-          gold small at BOTTOM+4.
-        · **Search box** — SharedXML SearchBoxTemplate → InputBoxVisualTemplate
-          (SecureUIPanelTemplates.xml l.42-67): the common-search-border three-slice (8x20 caps,
-          left hung 5 outside, middle stretched, all centered on the 22 box), 10x10 magnifier at
-          LEFT (1,-1), 17x17 clear button at RIGHT (-3), TextInsets 16/20, instructions label
-          GameFontDisableSmall tinted 0.35 at TOPLEFT (16,0) → BOTTOMRIGHT (-20,0).
-        THE 1.12 ART MAPPING (0978 base set, 0981 chrome — every file verified present in the
-        5875 MPQ chain; the CHROME recipe is the 1.14 System window's own, read verbatim from
-        wow-ui-source @1.14.4 OptionsFrameTemplates.xml + InterfaceOptionsFrame.xml, whose
-        every piece is 1.12-native or a color):
-        · window chrome — BACKDROP_DIALOG_32_32, the 1.14 options frames' backdrop: tiled
-          UI-DialogBox-Background ground (uniform black at 60% alpha — the world reads
-          through, the reference screenshot's actual mechanism; 0978 misread that ground as
-          parchment) + UI-DialogBox-Border rope edge 32, insets 11/12/12/11. Title plate
-          UI-DialogBox-Header at the options frames' 300x68 TOP (0,+12) seat, title on it.
-          ON TOP of that tile, inside the rope, a plain black 0.7 fill (1476) takes the
-          composite ground to 0.88: at the bare tile the world reached the option labels
-          hard enough to break them over bright terrain. The read-through stays, dimmed.
-        · the era's one dark Options_InnerFrame panel → TWO 1.14 OptionsFrameListTemplate
-          boxes: tooltip-border backdrops with the FILL AT ALPHA 0 (outlines — the ground
-          shows through) and the border tinted LIGHTGRAY_FONT_COLOR 0.6, tops at -52 (1.14's
-          own -40 band deepened 12 to hold the era search seat — 0984), tabs seated on the
-          category box's top edge (BOTTOMLEFT → box TOPLEFT (6,-3), the file-folder tuck).
-        · category rows — the 1.14 list-button wash, verbatim mechanism (0984,
-          OptionsFrameTemplates.{xml l.216-229, lua l.107-131}): ONE UI-QuestLogTitleHighlight
-          quad in ADD blend at the era plate seat (187x21 centered), steel-blue (.196,.388,.8)
-          as the hover and locked GOLD (1,1,0) as the selection, white hover/selected text.
-          The Options_CategoryHeader_<n> washes have no 1.12 counterpart and are DROPPED —
-          headers are their label alone.
-        · checkboxes: the UI-CheckBox four-state set at the era 30x29 seat (no HighlightTexture
-          — hover feedback stays the era row-wide wash, unchanged behavior).
-        · sliders: the 1.12 OptionsSliderTemplate groove — UI-SliderBar-Background/-Border
-          backdrop, its exact edge 8 / tile 8 / insets 3/3/6/6 — on a 17-tall Groove frame at
-          the era track seat, and the 32x32 UI-SliderBar-Button-Horizontal thumb. NO steppers
-          (0989, a directed cut of era structure): the bar is the whole control, 1.12's own
-          look — and the whole bar is live (thumb drag, or press anywhere on the track to
-          seat the thumb there and keep dragging; the engine's 0989 track-press law).
-        · tabs: UI-Character-ActiveTab / -InActiveTab flipped vertically via TexCoords (1.12
-          ships only bottom-tab plates; the flip turns them top-tab), one stretched piece per
-          plate instead of the era three-slice, at the era plate heights (26 active / 23 not).
-          (1.14's own UI-OptionsFrame-{Active,InActive}Tab three-slice is a 2.x file — not in
-          the 1.12 chain, verified absent.)
-        · search box: the classic Common-Input-Border three-slice (the file IS in 1.12
-          interface.MPQ — 0950's pull list mislabeled it era-only), the InputBoxTemplate UVs.
-          The era magnifier has no 1.12 counterpart and is DROPPED (the "Search" placeholder
-          carries the affordance) — and with it the era's 16-left TextInsets seat, which
-          exists to clear that magnifier: text and caret sit at 5, snug to the border ink
-          (0989). The clear-X wears the UI-Panel-MinimizeButton ball at its 17x17 seat,
-          half-lit, full-lit on hover (the era ClearButtonMixin's alpha law).
-        · divider: a 1-unit white hairline at 0.3 alpha, a color fill — what the era's
-          options_horizontaldivider atlas member actually is (decoded: a 630x1 pure-white row,
-          alpha peaking ~0.4, mean ~0.26). 0978's stretched UI-DialogBox-Divider is retired.
-
-        SCOPE / divergences (noted, not bugs):
-        - **No corner close X (0989, a directed cut)** — the era HAS one
-          (UIPanelCloseButtonNoScripts: the UI-Panel-MinimizeButton family at TOPRIGHT (+4,+4),
-          Classic SharedUIPanelTemplates.xml l.172-180), and 0981/0984 wore it; the director
-          cut it. The red Close button and ESC close the window, and the freed corner returns
-          the search box to the era's full-width TOPRIGHT seat.
-        - **Tabs are STATIC MinimalTab plates** (slice B): Game wears the selected state
-          permanently, AddOns the unselected gold — the era swaps these in code
-          (MinimalTabMixin), and with nothing behind AddOns the selection can never change, so
-          the two states are authored rather than driven. The mixin port comes with the addon
-          list. Width is era's text+40 law, fitted once from each tab's own `<OnShow>` (2028 —
-          the engine's measurer answers in the call that asks); the era's
-          measure-at-the-medium-font quirk is deliberately dropped (~6 units of padding).
-        - **Search WORKS (0984)** — the era SettingsPanel mechanism re-expressed (the Script
-          block's search section): label-tag substring match scored by matched length,
-          results grouped under clickable category heads ordered by best score, a matched
-          child pulls its parent row in, "Search Results" title with Defaults hidden while
-          the search holds the page, the no-results line, and the search ends on a category
-          click or hide (the era's own ClearSearchBox law). The result rows are the LIVE
-          rows, reflowed — values, writes and dependencies all work mid-search. The two
-          strings ("Search Results", "No results found.") are ours: the era's
-          SETTINGS_SEARCH_* globals live in the client binary, not the dump.
-        - **The PAGE AREA scrolls; the category tree does not.** The static tree (9 rows, 2
-          headers) fits its 199px column outright, and every CVar page fits its area, so nothing
-          on a settled page has a bar. The page area is a real ScrollFrame all the same (B217 —
-          the era's SettingsList is a ScrollBox with a MinimalScrollBar, and results and pages
-          ride the same one): a SEARCH chains group heads and matched rows from every category
-          into one column, which for a broad query outran the page and drew out through the
-          window onto the world. The body is the scroll child, sized to the visible rect until
-          the content outgrows it (OptionsScroll_Fit). The KEYBINDINGS page (decision 1008 — the
-          1.15 Settings panel's own Keybindings category, module + provenance in
-          KeyBindingsPage.xml) keeps its OWN faux-scroll list inside that body — it fills the
-          body exactly, so the outer scroll's range on it is 0 and the two bars are never live
-          together; its search results reflow live binding rows under a Keybindings group head
-          whose click jumps to the page (the era redirect law), capped at the static pool's size.
-          Both bars wear the shared kit's trough (the recessed channel — 1.12 authors that art
-          per window, so it is opt-in there and declared beside each bar here).
-        - **Row tooltips are 1.12's own strings on the era's seat (B223, decision 1054)**: every
-          row whose setting exists in a 1.12 panel raises that panel's `OPTION_TOOLTIP_*` text —
-          the description ALONE, wrapped, in the engine's default gold (the 1.12/1.14 option-row
-          plate, and this window's own since 1008's Character Specific row), seated the era way
-          (ANCHOR_RIGHT off the label half, x -10). The era's name-line-then-description pair
-          (`Settings.InitTooltip` → `GameTooltip_AddHighlightLine(name)`) is cut: its title would
-          repeat the label the cursor is already on. **Auto Loot** is the one row with no 1.12
-          string — no 1.12 row exists for it (its label is era's too) — and raises no plate.
-        - **Setting-page cuts (0957 Audio, 0959 Graphics)**: Defaults resets the VISIBLE page only (the
-          era confirm dialog is not modeled); era rows with no 1.12 CVar +
-          benilla knob behind them (output device, Dialog volume, loop music, channels, cache;
-          the whole era Graphics dropdown zoo) don't ship. A slider shows the 1.12 panel's
-          range even where the benilla knob's clamp is wider (uiScale's env clamp is 0.5..1.5):
-          a config value outside the page range displays clamped — thumb and readout agree on
-          the nearest expressible value, the engine keeps running the config's truth, and
-          nothing writes back until the player actually moves the row.
-        - **Apply-flow cuts (0961)**: the era's close-with-pending 3-button confirm dialog
-          (GAME_SETTINGS_CONFIRM_DISCARD) is not modeled — hiding the window silently discards
-          pending edits (the era's own hide path wipes without committing too); the 8-second
-          "keep these settings?" revert timer (CommitFlag.Revertable) is not modeled either —
-          Apply commits outright.
-        - Era rows this slice does not ship: the Accessibility group, and Languages/Network under
-          System — pages with no benilla knobs behind them yet (0950's "only rows backed by real
-          knobs" rule). Nameplates joined the tree in slice B on the promise of its knobs; the
-          page went LIVE in 0992 (the three UnitName* checkbox rows).
-        - **The window rides a scale knob** (slice B): fonts ride frame scale engine-wide now
-          (the 0219 §2 divergence closed), so ERA_WINDOW_SCALE × the era checkFit shrink
-          (UIPanelUpdateScaleForFit, re-expressed in this file) sizes the whole window; 0.78 is
-          the director's-eye starting point, live-tunable. The knob is SHARED: it stands in for
-          the era client's UIParent scale (smaller than our 1.12 768-canvas on modern screens),
-          so every era-shaped window wears it — GameMenuFrame.xml reads it in its OnShow.
+        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 two era fonts this window needs beyond Fonts.xml's 1.12 set (the era
-         GameFontHighlightMedium / GameFontHighlightHuge — Blizzard_Fonts_Shared: FRIZQT 14 and
-         20, white). Named Options* rather than the era names on purpose: Fonts.xml is the
-         COMPLETE 1.12 set and stays that way; these are this window's own, defined with
-         MasterFont's exact shadow inlined (its only content — Fonts.xml l.62). -->
+    <!-- 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). -->
     <Font name="OptionsFontHighlightMedium" font="Fonts\FRIZQT__.TTF" virtual="true">
         <Shadow>
             <Offset><AbsDimension x="1" y="-1"/></Offset>
@@ -191,62 +31,17 @@
     </Font>
 
     <Script><![CDATA[
-        -- ══ WHAT THIS FILE NO LONGER DECLARES, AND WHERE IT COMES FROM NOW (decision 2115) ══════
-        --
-        -- benilla's options window is THIS file and it is the one the player opens. But the
-        -- reference's own `UIOptionsFrame.xml` is now loaded too — hidden, off the player's chain,
-        -- at the manifest's l.21 seat above this row — so that a third-party addon reaching for
-        -- `UIOptionsFrame`, `UIOptionsFrameCheckButton42` or `UIOptionsFrame_Load()` finds the real
-        -- thing instead of an alias onto us. Three things this file used to carry are the stock
-        -- file's, and are gone from here rather than duplicated:
-        --
-        --   · **The 30 options uvars.** `UIOptionsFrame_Init` (stock UIOptionsFrame.lua l.93-185)
-        --     assigns every one its factory value and `RegisterForSave`s it — SIMPLE_CHAT,
-        --     CHAT_LOCKED, REMOVE_CHAT_DELAY, SHOW_NEWBIE_TIPS, LOCK_ACTIONBAR,
-        --     SHOW_BUFF_DURATIONS, ALWAYS_SHOW_MULTIBARS, SHOW_PARTY_PETS, QUEST_FADING_DISABLE,
-        --     SHOW_PARTY_BACKGROUND, HIDE_PARTY_INTERFACE, SHOW_TARGET_OF_TARGET(+_STATE),
-        --     HIDE_OUTDOOR_WORLD_STATE, AUTO_QUEST_WATCH, the fourteen COMBAT_TEXT_* rows and
-        --     COMBAT_TEXT_FLOAT_MODE, plus NAMEPLATES_ON/FRIENDNAMEPLATES_ON. Every value we used
-        --     to write here was already the reference's (1804 made them so), so this is a pure
-        --     de-duplication and the DEFAULT IS NOW THE REFERENCE'S BY CONSTRUCTION: our rows read
-        --     the global at their OnLoad (`OptionsGlobalRow_OnLoad`'s `udefault`), and the stock
-        --     file has assigned it long before, so Defaults still walks back to the shipped value.
-        --     Five it declares that we never did come free: SIMPLE_CHAT, SHOW_PARTY_PETS,
-        --     SHOW_PARTY_BACKGROUND, HIDE_PARTY_INTERFACE, and the nameplate pair's save rows.
-        --
-        --   · **`UIOptionsFrameCheckButtons`.** The reference's option table, whose home is that
-        --     file. Stock `MultiActionBars.lua:10` writes five rows into it at ITS load ("Hack to
-        --     get around load order dependencies"), which is why the stock window's row must sit
-        --     above MultiActionBars.xml in benilla.toc — it does, at l.21 exactly as the
-        --     reference's toc has it. Our rows never read this table; they keep their own store
-        --     (`OptionsRow_Get`'s three kinds).
-        --
-        --   · **`UpdateNameplates`.** `UIOptionsFrame.lua` l.768-780 — the reference's own home
-        --     for it, and the four verbs it calls (Show/HideNameplates, Show/HideFriendNameplates)
-        --     are ours in `script/cvars.rs`, unchanged. **One line of that body came back here**
-        --     (decision 2132) — see the re-declaration below; the de-duplication otherwise stands.
-        --
-        -- ── THE ONE ASSIGNMENT THAT STAYS, AND WHY IT IS AN OVERRIDE ────────────────────────────
-        -- `AUTO_QUEST_WATCH` is the string `"1"` ON PURPOSE (decision 1136): the reference assigns
-        -- the NUMBER 1 (`UIOptionsFrame.lua` l.122) while every consumer — stock
-        -- `QuestLogFrame.lua:64/68` and the checkbox's own load — compares against the STRING, and
-        -- in Lua 5.0 `1 ~= "1"`. So on a fresh 1.12 install the box paints unchecked and the
-        -- advertised auto-watch is dead until the player clicks it. We ship the string so the
-        -- advertised default is the real one — a recorded deviation under 1804's rule, not a quiet
-        -- one.
-        --
-        -- **This file loads AFTER the stock one** (manifest l.21 vs this window's seat before
-        -- GameMenuFrame), so this line runs after `UIOptionsFrame_Init` and wins. It is a
-        -- re-assignment, not a declaration: the `RegisterForSave` is the stock file's, and a second
-        -- one would be redundant — but it is kept, because `RegisterForSave` is idempotent and a
-        -- reader of this line should not have to know the stock file registered it to know the
-        -- global is persisted.
+        -- 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.
+        -- 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.
         AUTO_QUEST_WATCH = "1"
         RegisterForSave("AUTO_QUEST_WATCH")
 
-        -- The family's apply, ref UIOptionsFrame_Save l.371-376 verbatim: the addon is
-        -- LoadOnDemand, so turning the master on loads it, and the update runs only once it is
-        -- there. Every combat-text row's `applyFunc` is this (1964).
+        -- 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.
         function CombatText_UpdateOrLoad()
             if ( SHOW_COMBAT_TEXT == "1" ) then
                 UIParentLoadAddOn("Blizzard_CombatText")
@@ -255,28 +50,17 @@
                 CombatText_UpdateDisplayedMessages()
             end
         end
-        -- The Remove Chat Hover Delay row's applyFunc: the reference's own line
-        -- (UIOptionsFrame.lua l.216, `SetChatMouseOverDelay(REMOVE_CHAT_DELAY)`) under the name the
-        -- row resolves at apply time. `SetChatMouseOverDelay` is FloatingChatFrame.lua's.
+        -- The Remove Chat Hover Delay row's applyFunc (UIOptionsFrame.lua l.216).
         function ChatFrame_ApplyMouseOverDelay()
-            if SetChatMouseOverDelay then -- a VM that loaded this file without the chat files — a test's
+            if SetChatMouseOverDelay then -- nil in a VM loaded without the chat files
                 SetChatMouseOverDelay(REMOVE_CHAT_DELAY)
             end
         end
 
-        -- ── Show Tutorials' SETTER: the reference's own Save arm (decision 2077) ────────────
-        -- UIOptionsFrame.lua l.318-327, verbatim in behaviour. Its CheckButtons row is a bare
-        -- `{ index = 28 }` with no cvar and no uvar, which is why decision 1140's census filed it
-        -- as an "index-only entry with no store at all" and left it out; that reading is wrong.
-        -- The store is not in the TABLE, it is in the three special-case arms `UIOptionsFrame_Load`
-        -- (l.239), `_Save` (l.318) and `_SetDefaults` (l.645) keep for this key — the getter is
-        -- `TutorialsEnabled()` and the setter is the Reset/Clear pair, because "disable tutorials"
-        -- in 1.12 literally means "mark every bit of the acknowledged bank", not a CVar (1976;
-        -- wow-re censused all 210 `CVar::Register` sites and there is no tutorial CVar).
-        --
-        -- The `~=` guard is the reference's and it matters: `TutorialsEnabled()` returns the NUMBER
-        -- 1 or nil, so re-ticking an already-on row does not re-`ResetTutorials()` — which would
-        -- re-arm every tutorial the player has already dismissed.
+        -- 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.
         function BenillaOptionsFrame_SetTutorialsEnabled(value)
             if ( tonumber(value) ~= TutorialsEnabled() ) then
                 if ( value == "1" ) then
@@ -289,29 +73,11 @@
             end
         end
 
-        -- ── `UpdateNameplates` — OURS AGAIN, and the deviation is ONE LINE (decision 2132) ──────
-        -- The stock body is `UIOptionsFrame.lua` l.768-780, running off the chain since 2115.
-        -- This file loads after it (manifest l.21 vs this window's seat), so this re-declaration
-        -- wins. It is transcribed verbatim except that l.776 is dropped, and both halves of the
-        -- reason are benilla facts, not taste:
-        --
-        --   · **l.774-776 is a stock typo.** `if ( FRIENDNAMEPLATES_ON ) then
-        --     ShowFriendNameplates(); HideFriendNameplates();` — show, then hide, so BOTH branches
-        --     end hidden. On 1.12 that only clears volatile engine bits, and the friendly global is
-        --     not even saved (its l.182 registers `NAMEPLATES_ON` a second time where
-        --     `FRIENDNAMEPLATES_ON` was meant). On benilla the four verbs write the CVar pair, and
-        --     the CVar pair IS the store (`vplates.rs`, `script/cvars.rs`) — so those two lines
-        --     erase a persisted setting at every world entry and untick this window's own
-        --     Friendly Name Plates row.
-        --   · **There is no volatile level here to replay into.** The reference clears
-        --     `[0xc4da34]` on every EnterWorld and this function restores it; `VPlateMode` is never
-        --     cleared, so the replay has nothing to restore. What it still owes is the other
-        --     direction — an addon that sets `NAMEPLATES_ON` and calls this expects plates to move
-        --     — which is why the body stays rather than becoming a no-op (1203's posture).
-        --
-        -- The globals it reads are kept true by the host (`vplates::push_plate_globals`), seeded
-        -- ahead of `VARIABLES_LOADED` on the load edge, so in the steady state every branch here
-        -- writes a value the CVar already holds and queues nothing at all.
+        -- 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.
         function UpdateNameplates()
             if ( NAMEPLATES_ON ) then
                 ShowNameplates()
@@ -337,19 +103,12 @@
             "Graphics", "AdvancedGraphics", "Audio",
         }
 
-        -- The era-window scale (shared, director-owned — the 0219 WORLDMAP_WINDOWED_SCALE
-        -- pattern): the era client's UIParent draws smaller against the screen than our 1.12
-        -- 768-canvas does on modern displays, and this knob is that mapping — every era-shaped
-        -- window wears it (this window here; GameMenuFrame in its OnShow — in the era both draw
-        -- at the SAME UIParent px-per-unit, the parity the director's eye checked). At 1.0 the
-        -- 724-tall window fills ~85% of the screen's height in our 768-virtual space, where the
-        -- reference at typical resolutions reads nearer two-thirds.
+        -- 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.
         ERA_WINDOW_SCALE = 0.78
 
         function BenillaOptionsFrame_UpdateScale()
-            -- The era panel is registered `checkFit = 1`: the panel manager also shrinks it to
-            -- fit a small screen (UIPanelUpdateScaleForFit: min over width/height ratios
-            -- against the panel + 20 units of air each way, capped at 1) — re-expressed here.
+            -- The era panel's checkFit = 1: UIPanelUpdateScaleForFit also shrinks it to fit.
             local k = ERA_WINDOW_SCALE
             local wFit = GetScreenWidth() / 940
             local hFit = GetScreenHeight() / 744
@@ -358,31 +117,16 @@
             BenillaOptionsFrame:SetScale(k)
         end
 
-        -- The era tab width law (MinimalTab.lua l.7): label width + 40, measured ONCE per show —
-        -- the 1.12 CharacterFrameTabButtonTemplate's own seat (its <OnShow> calls
-        -- PanelTemplates_TabResize; decision 1993), and it has to be a show rather than the era's
-        -- OnLoad for a reason that outlives the measure: GetStringWidth answers in the REGION'S
-        -- OWN units, so its number depends on the owner's effective scale (glyph advances snap to
-        -- whole physical pixels, so the same label is not proportionally the same width at two
-        -- scales) — and this window's scale is set by BenillaOptionsFrame_UpdateScale in its own <OnShow>,
-        -- after every OnLoad has already run. Fired from the tabs' <OnShow>, which the engine
-        -- runs pre-order behind the window's own, the scale is the drawn one. No poll and no latch:
-        -- the engine's font measurer answers inside the Lua call that asked (benilla-ui
-        -- script/measure.rs), and a re-show re-fits at whatever scale the window then wears.
-        -- Deliberate divergence: the era measures with the MEDIUM font it is about to swap away
-        -- (an accident of its code order, ~6 units of extra padding); we measure the small font
-        -- the label actually wears.
+        -- 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.
         function OptionsTab_FitWidth(tab)
             tab:SetWidth(getglobal(tab:GetName() .. "Text"):GetStringWidth() + 40)
         end
 
-        -- Each row's OnLoad: remember the key + title, paint the label, size the wash plate —
-        -- the era sized it via SetAtlas(name, true) at atlas size (187x21, centered: 6 units
-        -- in from either edge of the 199 row); with plain SetTexture the size is authored
-        -- here once — and set the 1.14 base tint: OptionsListButton_OnLoad's own
-        -- SetVertexColor(.196, .388, .8), the steel-blue every unselected row's hover wears
-        -- (OptionsFrameTemplates.lua l.130-131). The whole row identity lives here so adding
-        -- a category is one XML row + one key in the table above.
+        -- 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.
         function OptionsCategoryRow_OnLoad(row, key, label)
             row.categoryKey = key
             row.pageTitle = label
@@ -393,22 +137,15 @@
             bg:SetVertexColor(0.196, 0.388, 0.8)
         end
 
-        -- The selection — 1.14's OptionsList_SelectButton/_ClearSelection pair, re-expressed
-        -- (OptionsFrameTemplates.lua l.107-121): the selected row's wash goes GOLD (1,1,0)
-        -- and locks on; every other row drops back to the blue hover tint, wash off. The
-        -- white selected label is LockHighlight's own text state, carried by the font swap.
-        -- Also the era law on top (SettingsPanelMixin:SelectCategory clears the search box —
-        -- Blizzard_SettingsPanel.lua l.793): picking a category ENDS a live search; the
-        -- SetText("") round-trips through OnTextChanged -> restore -> back here, so this call
-        -- returns early and lets the re-entry do the work once.
-        -- Then the page swap: a category with rows (OPTIONS_PAGE_ROWS) shows its body
-        -- refreshed from the CVars and Defaults goes live with it; every other page is still
-        -- empty, Defaults disabled.
+        -- 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.
         function BenillaOptionsFrame_SelectCategory(key)
             BenillaOptionsFrame.selectedCategory = key
             if BenillaOptionsFrameSearchBox:GetText() ~= "" then
                 BenillaOptionsFrameSearchBox:SetText("")
-                return -- the OnTextChanged restore re-entered with this same key and finished
+                return -- the restore re-entered with this key and finished
             end
             for _, k in ipairs(OPTIONS_CATEGORY_KEYS) do
                 local row = getglobal("BenillaOptionsFrameCategoryListRow" .. k)
@@ -428,18 +165,10 @@
                 local body = getglobal("BenillaOptionsFrameContainerBody" .. k)
                 if k == key then body:Show() else body:Hide() end
             end
-            -- A category switch starts at the TOP (2180), which is what entering and leaving a
-            -- search have always done two functions down and what the era's own ScrollBox does
-            -- per category. It was invisible until this record, because no PAGE outran its area
-            -- — only the search results did, and both of their edges reset. Now that Controls
-            -- carries sixteen rows, leaving it scrolled and clicking Interface would land the
-            -- player halfway down a page they have not seen the top of.
+            -- A category switch starts at the top, as the era ScrollBox does per category.
             BenillaOptionsFrameContainerScroll:SetVerticalScroll(0)
-            -- The Keybindings page (KeyBindingsPage.xml, decision 1008) body-swaps like the
-            -- CVar pages but runs its own machinery: entering rebuilds the section tree;
-            -- leaving disarms a straggling capture (the host seam must never outlive the page)
-            -- and clears its message line. Its Defaults is the confirmed Reset To Default (the
-            -- button's OnClick forks), and the Unbind Key button exists only here.
+            -- Keybindings: entering rebuilds the section tree; leaving disarms a pending capture,
+            -- which must never outlive the page.
             local kb = getglobal("BenillaOptionsFrameContainerBodyKeybindings")
             if key == "Keybindings" then
                 kb:Show()
@@ -460,21 +189,12 @@
             end
         end
 
-        -- ── Search (0984): the era SettingsPanel mechanism, re-expressed ────────────────────
-        -- Blizzard_SettingsPanel.lua l.566-692 + Blizzard_Settings.lua l.65-77, cut to our
-        -- static rows: a setting's search tag is its LABEL uppercased (the era's default tag
-        -- is exactly the setting name — SettingControls.lua l.773); a query matches by plain
-        -- substring, scored by matched-word length; matches group under their category, the
-        -- groups ordered by their best score; each group opens with a clickable category
-        -- header (SettingsListSearchCategoryTemplate — click = jump to the category, which
-        -- ends the search); no match shows the section-header "no results" line. The results
-        -- ARE the live rows — the era reflows the real initializers into a fresh vertical
-        -- layout, so ours re-anchor the real row frames (values, writes, dependencies all
-        -- work in place) and the restore path lays every page back down by the one layout
-        -- law below.
+        -- ── 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.
 
-        -- The era's word list (l.569-572): the WHOLE query first — a phrase match outranks
-        -- its own words — then every comma/space-separated token.
+        -- 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 }
@@ -484,9 +204,7 @@
             return words
         end
 
-        -- The era score (Blizzard_Settings.lua l.65-77 MatchesSearchTags): first word that
-        -- hits the tag scores last-first (matched length - 1); no hit is no match. Plain
-        -- find — the era passes plain=true, no pattern magic.
+        -- The era score (MatchesSearchTags, Blizzard_Settings.lua l.65-77), with a plain find.
         function OptionsSearch_Score(tag, words)
             for _, w in ipairs(words) do
                 local first, last = string.find(tag, w, 1, true)
@@ -495,10 +213,7 @@
             return nil
         end
 
-        -- The era gather+group (l.575-636): rows bucketed by score, scores walked high to
-        -- low; a category's group is born the first time one of its rows surfaces — so the
-        -- group ORDER is best-score order — and collects that category's matches as the walk
-        -- descends. Returns the ordered group list { key, rkeys } .. .
+        -- 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 = {}, {}
@@ -517,10 +232,7 @@
                     end
                 end
             end
-            -- The keybinding entries join the same buckets (the era's searchable fake category
-            -- whose results REDIRECT to the Keybindings page — KeyBindingsPage.xml's search
-            -- note). Their rkey is the BINDING INDEX; the display fork below tells them apart
-            -- by the group key.
+            -- Keybinding matches join the buckets, as in the era; their rkey is the binding index.
             for _, m in ipairs(KeyBindings_SearchMatches(words)) do
                 if not buckets[m.score] then
                     buckets[m.score] = {}
@@ -542,20 +254,10 @@
             return order, groups
         end
 
-        -- ── The page scroll (B217) ──────────────────────────────────────────────────────────
-        -- The body is the scroll child (the ScrollFrame above it), so what these two do is
-        -- decide how TALL it is: the content's own extent, or the visible page rect, whichever
-        -- is larger. Below the rect nothing changes at all — range 0, no bar, every page seated
-        -- exactly where its XML puts it — and above it the overflow becomes a scroll instead of
-        -- a spill.
-        --
-        -- The measured set is every element that takes a seat in the ONE layout law's chain:
-        -- each page's rows, the search group heads, and the keybinding result pool. All of them
-        -- hang off the body's TOP, so their extent is independent of the height being computed —
-        -- which is what makes this converge. Nothing anchored to the body's BOTTOM may join them
-        -- (the Keybindings page's output line is the live example): growing the body would move
-        -- it down, which would grow the body. IsVisible, not IsShown: a hidden page's rows keep
-        -- their own shown flag, and only what the player can actually see may set the height.
+        -- ── 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.
         function OptionsScroll_ContentBottom()
             local bottom = nil
             local function take(name)
@@ -580,12 +282,8 @@
             return bottom
         end
 
-        -- Size the body to that, from the scroll frame's OnUpdate. Frame-late by nature, and for
-        -- a reason that has nothing to do with the text measure: RECTS resolve after Lua runs, so
-        -- a pass that reads GetHeight() to reflow answers off the previous resolve however it is
-        -- driven. Write-gated: SetWidth/SetHeight invalidate layout, so an every-frame write
-        -- would fight the resolver. UpdateScrollChildRect re-drives the bar through
-        -- OnScrollRangeChanged, which is what shows and hides it (and its trough).
+        -- Size the body from OnUpdate, off the previous frame's rects; writes are gated because
+        -- SetWidth and SetHeight invalidate layout.
         function OptionsScroll_Fit()
             local sf = BenillaOptionsFrameContainerScroll
             local body = BenillaOptionsFrameContainerBody
@@ -604,11 +302,8 @@
             end
         end
 
-        -- THE one layout law (era SettingsList: verticalPad 10, padLeft 25/padRight 0 →
-        -- first element at (10,-12) off the body, spacing 9 → chain at (0,-9)). The rows'
-        -- authored XML anchors state exactly this chain as the initial layout; search
-        -- reflows steal rows out of it, and this function is how ANY element — row or search
-        -- head — takes a seat in it. prev is a global frame NAME (nil = the chain head).
+        -- 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.
         function OptionsSearch_Place(name, prev)
             local f = getglobal(name)
             f:ClearAllPoints()
@@ -621,8 +316,7 @@
             end
         end
 
-        -- Lay a page's rows back down on their authored chain (the XML anchors' law,
-        -- re-stated after a search reflow; the pin test holds the two equal).
+        -- Lay a page's rows back on their 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
@@ -633,15 +327,10 @@
             end
         end
 
-        -- The results view (era OnSearchTextChanged's hasText arm, l.659-691): every page
-        -- body SHOWS (they are bare row hosts sharing one rect) with every row hidden, then
-        -- the groups chain down — category head, then its matches; a matched CHILD row pulls
-        -- its parent row in first (l.665-670, the era parentInitializer rule — our Audio
-        -- volumes ride under Master). Title reads "Search Results", Defaults hides while the
-        -- search holds the page (l.684-688), and an empty result shows the no-results line
-        -- (l.680-682).
+        -- 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)
-            -- A new result set starts at the top (the era's own ScrollBox reset on a search).
             BenillaOptionsFrameContainerScroll:SetVerticalScroll(0)
             for k in pairs(OPTIONS_PAGE_ROWS) do
                 getglobal("BenillaOptionsFrameContainerBody" .. k):Show()
@@ -650,9 +339,7 @@
                 end
                 getglobal("BenillaOptionsFrameContainerBodySearchHead" .. k):Hide()
             end
-            -- The Keybindings furniture leaves the stage with the rest: its body hides (the
-            -- search paints matched bindings on the shared pool below, not the page list), a
-            -- straggling capture disarms, and the pool starts blank.
+            -- 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
@@ -677,9 +364,7 @@
                 getglobal(head):Show()
                 prev = head
                 if key == "Keybindings" then
-                    -- Matched bindings painted LIVE onto the static pool (the era reflows its
-                    -- real rows the same way; the pool caps the count — the SCOPE note in
-                    -- KeyBindingsPage.xml — and the head above jumps to the full page).
+                    -- Matched bindings paint onto the pool, capped at its size.
                     KeyBindingsPage.searchPainted = {}
                     local shown = 0
                     for _, index in ipairs(groups[key]) do
@@ -717,9 +402,7 @@
             end
         end
 
-        -- Ending a search: every page back on its authored chain, heads away, and the
-        -- selection re-applied — SelectCategory re-shows the one body, retitles, and brings
-        -- Defaults back (the era's no-text arm, l.655-658).
+        -- 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
@@ -736,9 +419,7 @@
             BenillaOptionsFrame_SelectCategory(BenillaOptionsFrame.selectedCategory or "Controls")
         end
 
-        -- The text gate (era OnSearchTextChanged l.640-652): a repeat of the same text is a
-        -- no-op, and the FIRST change (searchText still nil — load-time initialization)
-        -- arms without acting; text clearing restores only if a search was actually live.
+        -- 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 ~= ""
@@ -750,56 +431,32 @@
             end
         end
 
-        -- ── The setting pages: 1.12 rows in the era Settings grammar ────────────────────────
-        -- One machinery, every page (Audio 0957, the first). Semantics (rows, CVars, labels,
-        -- dependencies, the click-sound quirk) are the 1.12 client's own panels, quoted
-        -- verbatim (SoundOptionsFrame.lua / OptionsFrame.lua + GlobalStrings.lua); geometry is
-        -- the era settings list (Blizzard_SettingControls.xml/.lua + Blizzard_SettingsList.lua
-        -- @1.15.9 — 26-tall rows on a 9 spacing, label LEFT+37 → CENTER-85, control at
-        -- CENTER-80, child rows +15 indent in the small font). Era rows with no 1.12 CVar +
-        -- benilla knob behind them (Enable Sound=Sound_EnableAllSound, Dialog, output device,
-        -- channels…) do not ship — the 0950 honest-tree rule applied to settings.
-        -- The options strings that are NOT the reference's (1639, 1650). Every other
-        -- tooltip on this window resolves an OPTION_TOOLTIP_* out of 1.12's GlobalStrings, and a
-        -- benilla row with no counterpart there has so far simply gone mute (the nameplate pair).
-        -- Render Scale cannot afford to: the director's own reaction to the dial was "not really
-        -- sure what this does". So it gets a description, under a BENILLA_ prefix rather than an
-        -- invented OPTION_TOOLTIP_ -- the reference's namespace stays the reference's, and an
-        -- addon reading GlobalStrings still finds exactly what 1.12 defined.
+        -- ── 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.
         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 (1847). An era row: 1.12 hardcodes the behaviour and has no
-        -- checkbox, so there is no OPTION_TOOLTIP_* to resolve and the BENILLA_ prefix applies
-        -- for the same reason Render Scale's does -- the reference's namespace stays the
-        -- reference's. The last line is not padding: mute is not pause on either client, and a
-        -- player who expects a paused fight to resume where it stopped is owed the difference.
+        -- Enable Sound in Background: 1.12 has no checkbox; silenced sounds keep running.
         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 (1650). 1.12's own OPTION_TOOLTIP_WINDOWED_MODE cannot ride this row: it
-        -- is written for the checkbox it belonged to ("Check to play in a non-fullscreen
-        -- window..."), and its second half describes a desktop-gamma consequence of an exclusive
-        -- mode-set we do not do. The row also has to answer the question a player arrives with —
-        -- "where is Fullscreen?" — which no reference string was ever written to answer.
+        -- Display Mode: 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 (2182). 1.12's own OPTION_TOOLTIP_GAMMA cannot ride this row: its whole
-        -- second sentence is "Increase brightness until you can clearly see all 21 levels of gray
-        -- bars to the right", and those bars are the stock video window's own calibration art,
-        -- which this page does not have (2182 §7 names it as a follow-up). The row also has to answer the
-        -- question the reference never had to — why a brightness control works here at all, when
-        -- 1.12's did nothing outside exclusive fullscreen.
+        -- Brightness: 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"
@@ -1104,21 +761,10 @@
         end
 
         OPTIONS_PAGE_ROWS = {
-            -- Seven rows became sixteen at 2180, and the nine that arrived were not new
-            -- settings: every one names a CVar this client already registered AND read, with no
-            -- control anywhere a player could reach. The four camera toggles are why the record
-            -- exists — 2149 built their mechanisms and 2179 rebuilt water collision, and none of
-            -- the four could be turned off from inside the game.
-            --
-            -- SEATS: every row that was already here keeps the era-derived seat it had; each new
-            -- row takes the seat its own 1.12 box gives it, that box's COLUMNS read left to
-            -- right and flattened into this single one (the rule this page's Block Trades
-            -- comment already states). BasicOptionsGeneral runs 45 -> 3 -> 16 down its middle
-            -- column and 14 -> 61 down its right, so Attack on assist and Auto Clear AFK follow
-            -- Sticky Targeting and Auto Self Cast follows Block Trades. BasicOptionsCamera runs
-            -- the following-style dropdown -> 24 -> 26, then Slider2 -> 27 -> 15, then Slider3
-            -- -> Slider4 — which is the block below verbatim, and which leaves Max Camera
-            -- Distance exactly where it already sat, last.
+            -- 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.
             Controls = {
                 "RowStickyTarget", "RowAssistAttack", "RowClearAFK",
                 "RowBlockTrades", "RowAutoSelfCast",
@@ -1156,30 +802,14 @@
                 "RowFireLight", "RowFireFlicker", "RowSpellLights", "RowLavaGlow",
                 "RowNightDarkness", "RowInteriorDarkness",
             },
-            -- Player Guild Names (2180) rides as a CHILD of Player Names, which is the
-            -- reference's own relationship twice over: its CheckButton22 hangs off 21 with a +26
-            -- x indent, and UIOptionsFrame_UpdateDependencies l.702-708 greys 22 (and 23) from
-            -- 21's own tick. Its knob is `UnitNamePlayerGuild`, built by 2149's §6.
+            -- Player Guild Names is a child of Player Names, as in 1.12 (l.702-708).
             Nameplates = {
                 "RowEnemyPlates", "RowFriendlyPlates",
                 "RowPlayerNames", "RowGuildNames", "RowNpcNames", "RowOwnName",
             },
-            -- The stock globals that were already defined AND consumed when 1134 opened the store
-            -- (1136; Buff Durations 1139), plus the two equipment-display toggles (1472), in the
-            -- reference's own on-screen order. Its Basic Options Display box is three COLUMNS read
-            -- left to right: A gives Enhanced Tooltips (CheckButton12, added 2180) then Status
-            -- Text (2), B gives Show Cloak → Show Helm
-            -- (31 → 20, sitting under the name toggles that live on our Nameplates page), C gives
-            -- the 42 → 39 → 66 chain. The **Help** box closes the page, and since 2077 it is
-            -- the box's own order rather than its one shippable row: 28 (Show Tutorials), 44
-            -- (Show Loading Screen Tips, anchored under 28 there) then 29 (Show Detailed
-            -- Tooltips). 28 was left out by 1140's census as an "index-only entry
-            -- with no store at all"; that reading missed the three special-case arms
-            -- `UIOptionsFrame_Load`/`_Save`/`_SetDefaults` keep for the key, which are its store.
-            -- The target-of-target pair (decision 1576) breaks that left-to-right reading, and
-            -- it has to: 1.12 keeps it in a box this window has no page for — Advanced Options'
-            -- "Raid & Party" — so there is no column order to preserve, only a neighbour to pick.
-            -- It sits under Status Text because that is the other unit-frame readout on the page.
+            -- 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.
             Interface = {
                 "RowEnhancedTooltips", "RowStatusText", "RowTargetOfTarget", "RowTargetOfTargetMode",
                 "RowShowCloak", "RowShowHelm",
@@ -1187,98 +817,42 @@
                 "RowProfanityFilter",
                 "RowShowTutorials", "RowTipOfTheDay", "RowNewbieTips",
             },
-            -- 1.12's Advanced Options **Chat** box (decision 1589, B246 — "no chat section in
-            -- options"). The page was called `Social` and held exactly the two chat-bubble
-            -- switches 1139 put on it; it is the reference's own `CHAT_LABEL` box now, and grew
-            -- into it. Order is the reference's own anchor chain (UIOptionsFrame.xml l.751-840:
-            -- CheckButton 7 → 8 → 13 → 18 → 37 → 46 → 38 → 51 → 68), with the rows we have no
-            -- mechanism for skipped rather than stubbed:
-            --   · 7  Simple Chat        — needs FCF_Set_SimpleChat's re-layout (0288 §2)
-            --   · 8  Lock Chat Settings — the ONE row here whose machinery now exists: 1594
-            --        built the move, the resize and the blanket `CHAT_LOCKED` switch this
-            --        checkbox drives (`FCF_Set_ChatLocked`/`FCF_Get_ChatLocked`, gating both
-            --        verbs). It is unbuilt because nobody has asked for it, not because it
-            --        would be inert — and the per-window lock the tab menu carries is the one
-            --        a player actually reaches for. Ships when it is wanted
-            --   · 51 Auto-join Guild Recruitment Channel — **this note used to say the row is
-            --        inert in the reference too, and that was wrong** (corrected by 2115; it is
-            --        exactly the mistake 2077 corrected for SHOW_TUTORIALS). The table entry is a
-            --        bare `{ index = 51 }`, but the store is not in the TABLE — it is in the three
-            --        special-case arms `UIOptionsFrame_Load` (l.243-248, `GetGuildRecruitmentMode`),
-            --        `_Save` (l.326-331, `SetGuildRecruitmentMode`) and `_SetDefaults` (l.649) keep
-            --        for the key. Both verbs are ours now (2115), over the chat cache's
-            --        `OPTION_GUILD_RECRUITMENT_CHANNEL` latch. The row is unshipped here because
-            --        nobody has asked for it, not because it would be inert
-            -- Row 68, Disable Spam Filter, **shipped by 2077** — and the note it replaces was
-            -- wrong twice over, both corrected at the bytes by wow-re's `text-filter-law.md`.
-            -- The filter is not a word list, it is 28 compiled PCRE patterns from
-            -- `SpamMessages.dbc`; and it does not drop `CHAT_MSG_FILTERED` lines, it is armed for
-            -- every type EXCEPT that one (`0x49aad2`'s `jne` skips the disarm, which the older
-            -- note read backwards). It drops a matching line silently, with nothing in its place.
-            -- 1139's note about the 37 → 46 → 38 gap is closed by this record: 46 is Loot Spam,
-            -- and it has a knob now.
+            -- 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.
             Chat = {
                 "RowGuildMemberAlert", "RowRemoveChatDelay", "RowChatBubbles", "RowLootSpam",
                 "RowPartyChatBubbles", "RowSpamFilter",
             },
-            -- 1.12's Advanced Options "Action Bars" group, whole (decision 1500 completing 1136).
-            -- Its six rows, the four bar toggles then the grid switch then the lock. That is the
-            -- DIRECTOR's order, not the reference's: 1.12's box is two columns and leads with the
-            -- lock (CheckButton32 at its TOPLEFT, then 33/40/34 down the left, 35/36 down the
-            -- right), which does not survive being flattened into one column — the five switches
-            -- that decide what is on screen belong above the one that decides whether it can be
-            -- dragged. 1136 could ship only the lock, because the other five had
-            -- nothing behind them: the two bottom bars were unconditionally on and the two vertical
-            -- ones unconditionally hidden (0270/1219). 1500 made all four bars options, which is
-            -- what gave the five rows a store to read.
-            --
-            -- Two DIFFERENT stores on one page, and the split is verified rather than chosen: the
-            -- four bar rows are `func` rows over the server's own PLAYER_FIELD_BYTES byte 2 (no
-            -- local store exists to save), while Always Show ActionBars is a `uvar` row — the
-            -- engine binding takes exactly four arguments and silently drops the fifth the
-            -- reference passes it, so that switch has no server side at all. Decision 1500 and
-            -- wow-re action-bar-toggles.md carry the byte-level evidence.
+            -- 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.
             ActionBars = {
                 "RowMultiBar1", "RowMultiBar2", "RowMultiBar3", "RowMultiBar4",
                 "RowAlwaysShowMultibars", "RowLockActionBar",
             },
-            -- The floating-combat-text family (decision 1134), in the reference's own on-screen
-            -- order — its AdvancedOptionsCombatText box's anchor chain, master → scroll mode →
-            -- the twelve, NOT its check-button index order (which jumps 58→60→63…59→69).
+            -- The combat-text box in its anchor-chain order, not its CheckButton index order.
             Combat = {
                 "RowCombatText", "RowFloatMode", "RowLowHealthMana", "RowAuras", "RowAuraFade",
                 "RowCombatState", "RowDodgeParryMiss", "RowResistances", "RowReputation",
                 "RowReactives", "RowFriendlyNames", "RowComboPoints", "RowEnergyGains",
                 "RowHonorGained",
-                -- The damage-NUMBER trio (2180) shares the reference's box and NOT its master:
-                -- 19 -> 11 -> 9 close the AdvancedOptionsCombatText anchor chain, and the
-                -- "Additional combat text dependancies" block that greys 53…69 never names them
-                -- — 19 runs its own pair instead (UIOptionsFrame.lua l.709-714). So Show Target
-                -- Damage is a second, independent master on this page, and the two under it are
-                -- its children.
+                -- 19 -> 11 -> 9 close the chain under their own master (l.709-714).
                 "RowShowDamage", "RowPeriodicDamage", "RowPetDamage",
             },
         }
 
-        -- `tip` is the GlobalStrings KEY of the row's description (B223, decision 1054) — the key,
-        -- not the text: it resolves at HOVER, the way the 1.12 Interface panel resolves its own
-        -- (UIOptionsFrame.lua l.265, `getglobal("OPTION_TOOLTIP_"..key)`), so the row is wired
-        -- before GlobalStrings has to exist. nil = no 1.12 string for this setting (Auto Loot).
+        -- `tip` is a GlobalStrings key, resolved at hover as UIOptionsFrame.lua l.265 does.
         function OptionsRow_OnLoad(row, cvar, label, tip, child)
             row.cvar = cvar
             row.tip = tip
-            -- The search tag: the era's default is exactly the setting's display name
-            -- (SettingControls.lua l.773 AddSearchTags(name)), uppercased at registration
-            -- (Blizzard_Settings.lua l.60).
+            -- The era search tag: the display name (SettingControls.lua l.773), uppercased.
             row.searchTag = string.upper(label)
-            -- Kept, not just applied: the disabled-state font (OptionsRow_SetEnabled) has to pick
-            -- the SAME size the indent chose, or greying a child row also promotes it.
+            -- Kept for OptionsRow_SetEnabled, whose 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: +15 label indent and the small font
-                -- (SettingControls.lua l.319-322); the control itself does not indent.
+                -- 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)
@@ -1286,27 +860,10 @@
             end
         end
 
-        -- ── The row's STORE: a CVar, a saved-variable global, or an API pair (1134, 1472) ──
-        -- 1.12's own Interface panel has THREE stores, not one: each UIOptionsFrameCheckButtons
-        -- entry carries `cvar = "name"` (an engine knob), `uvar = "GLOBAL"` (a RegisterForSave'd
-        -- Lua global), or a `func`/`setFunc` pair (an engine getter/setter with no client-side
-        -- store at all) — and UIOptionsFrame_Load/_Save fork on exactly that field
-        -- (UIOptionsFrame.lua l.230-377; the func fork at l.237-238 and l.296-297). Values are
-        -- strings in all three — "1"/"0" for a toggle — so only the accessor differs, and every row
-        -- in this file reads and writes through this trio instead of calling Get/SetCVar directly.
-        --
-        -- The third kind is what Show Helm / Show Cloak are: the preference is a bit of the
-        -- character's own server-side PLAYER_FLAGS, so there is nothing local to save and nothing
-        -- to restore at load — the getter IS the state (decision 1472).
-        -- **Does this row have somewhere to put a value?** The three stores of 1134, asked in the
-        -- order `OptionsRow_Set` tries them. A row with none is display-only and must not be
-        -- written.
-        --
-        -- It exists because the slider's OnValueChanged guarded on `row.cvar or row.uvar` — two of
-        -- the three — and so wrote nothing for a row whose store is an engine pair. The readout
-        -- still moved, which is the worst shape that bug can take: the control looks alive, the
-        -- setting never leaves the window, and nothing anywhere errors. Asking one predicate keeps
-        -- every caller in step with the setter by construction instead of by memory.
+        -- ── 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.
         function OptionsRow_HasStore(row)
             return row.uvar or row.setFunc or row.cvar
         end
@@ -1314,13 +871,8 @@
         function OptionsRow_Get(row)
             if row.uvar then return getglobal(row.uvar) end
             if row.getFunc then
-                -- A NUMERIC api row (2182): the store is an engine getter whose answer is a
-                -- number, not a flag. 1.12's own video panel is where this shape comes from --
-                -- its slider table's `func` fork calls `getglobal("Get"..func)` and feeds the
-                -- result straight to `slider:SetValue` (OptionsFrame.lua l.110/135) -- and the
-                -- Brightness row is the one benilla ships. Normalised through the SAME two-decimal
-                -- strip the slider writes with, so a value sitting on the default compares equal
-                -- to it as a string and the pending/committed test below still works.
+                -- 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.
                 if row.numeric then
                     return (string.gsub(string.format("%.2f", row.getFunc()), "%.?0+$", ""))
                 end
@@ -1343,24 +895,16 @@
         function OptionsRow_Set(row, value)
             if row.uvar then
                 setglobal(row.uvar, value)
-                -- `applyFunc` is a global's NAME: the rows are read at this file's load, which since
-                -- 1938 sits at the reference's slot — before every file an apply lives in — so the
-                -- function is looked up when the row is applied, not when it is declared. A name
-                -- with no global behind it (a page harness without that definer) applies nothing,
-                -- which is what a nil capture always did.
+                -- `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.
                 local apply = row.applyFunc
                 if type(apply) == "string" then apply = getglobal(apply) end
                 if apply then apply() end
                 return
             end
-            -- An API row hands the setter the row's own "1"/"0" STRING, which is what 1.12 does
-            -- (UIOptionsFrame_Save l.290-297 builds value.value as a string and passes it
-            -- straight through) — so the engine binding reads its argument numerically and "0"
-            -- means off. No applyFunc: the setter IS the side effect.
+            -- An API row passes the "1"/"0" string, as UIOptionsFrame_Save l.290-297 does.
             if row.setFunc then
-                -- A numeric api row hands the setter a NUMBER, which is what 1.12 does for the
-                -- shape it borrows from: `OptionsFrame_Save` passes `slider:GetValue()`
-                -- (OptionsFrame.lua l.206-226), not a string.
+                -- A numeric one passes a number, as OptionsFrame_Save does (l.206-226).
                 if row.numeric then
                     row.setFunc(tonumber(value))
                 else
@@ -1372,19 +916,10 @@
             OptionsRow_WritePartner(row, value)
         end
 
-        -- **The PARTNER write (2180).** Three of 1.12's own rows drive a SECOND CVar that
-        -- appears in neither option table, from the special-case arms of `UIOptionsFrame_Save`:
-        -- Show Pet Melee Damage writes `PetSpellDamage` beside `PetMeleeDamage` (l.334-336), and
-        -- the two camera-speed sliders each write their pitch twin at a fixed ratio (l.351-356,
-        -- yaw/4 for the follow speed and yaw/2 for the look speed). Without this a row is a HALF
-        -- write — the box reads "pet damage off" while pet SPELL damage keeps floating — and it
-        -- is silent, because `SetCVar` on a name nobody wrote is not an error, it is a value
-        -- that stayed where it was.
-        --
-        -- `scale` nil means a flag: the same "1"/"0" string goes to both. A number scales, and
-        -- the result is formatted the way the slider path formats its own write (two decimals,
-        -- trailing zeros stripped) so a partner sitting at its registered default compares equal
-        -- to it as a STRING and stays out of the config file.
+        -- 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.
         function OptionsRow_WritePartner(row, value)
             if not row.partner then return end
             local v = value
@@ -1395,31 +930,23 @@
             SetCVar(row.partner.cvar, v)
         end
 
-        -- The registered default — GetCVarDefault's counterpart for a global. `udefault` is the
-        -- value the defining XML assigned at FILE SCOPE, captured at this row's OnLoad: the whole
-        -- UI's XML loads before the saved-variables chunk executes over it (decision 1128's load
-        -- order), so at OnLoad the global still holds its shipped default. That makes the
-        -- assignment the single source of the default — the panel restates nothing and so cannot
-        -- drift from it, where the reference's table carries a second hand-written copy.
+        -- 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.
         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 row whose store is a saved-variable global rather than a CVar. Same signature as
-        -- OptionsRow_OnLoad with the global's name in the cvar seat; the caller adds `applyFunc`
-        -- afterwards when the setting needs one.
+        -- A uvar row: 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
 
-        -- A row with no store: an engine getter/setter pair, 1.12's own `func`/`setFunc` shape
-        -- (decision 1472). `default` has to be stated because there is no registered default to
-        -- ask for — the reference states it the same way, as a hand-written arm of
-        -- UIOptionsFrame_SetDefaults (l.631-634, SHOW_CLOAK and SHOW_HELM both SetChecked(1)).
+        -- 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).
         function OptionsFuncRow_OnLoad(row, getFunc, setFunc, default, label, tip, child)
             OptionsRow_OnLoad(row, nil, label, tip, child)
             row.getFunc = getFunc
@@ -1427,129 +954,33 @@
             row.fdefault = default
         end
 
-        -- The same, for a pair whose value is a NUMBER rather than a flag (2182) -- 1.12's video
-        -- panel's own `func` fork. `default` is still a string, because every store in this kit
-        -- answers in strings and the row compares them; the Brightness row computes it from
-        -- GetCVarDefault so the CVar table stays the one source.
+        -- A numeric API row; `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
 
-        -- ── THE LOAD-TIME LADDER IS THE REFERENCE'S OWN AGAIN (decision 2115) ──────────────
-        --
-        -- The problem it solves is real and unchanged (decision 1139): the whole UI's XML runs
-        -- BEFORE the saved chunk executes over it (1128's load order), so every file-scope
-        -- consumer of a `RegisterForSave`'d global already ran against the SHIPPED default, and
-        -- the saved value landing afterwards changes the variable while leaving the world it
-        -- configured alone. A CVar row needs nothing — the host reads its own table at boot.
-        --
-        -- 1.12 closes it with a hand-written ladder in `UIOptionsFrame_OnEvent`'s VARIABLES_LOADED
-        -- arm (UIOptionsFrame.lua l.193-227): `BuffButtons_UpdatePositions`, the SIMPLE_CHAT and
-        -- CHAT_LOCKED arms, `SetChatMouseOverDelay(REMOVE_CHAT_DELAY)`,
-        -- `MultiActionBar_ShowAllGrids`, `RaidOptionsFrame_UpdatePartyFrames`, and
-        -- `UIParentLoadAddOn("Blizzard_CombatText")`. **That arm runs here now**, off the player's
-        -- chain, because the stock file is loaded (hidden) at the manifest's l.21 seat — so this
-        -- window used to re-express a ladder that did not exist and now would be a SECOND copy of
-        -- one that does.
-        --
-        -- So the walk is gone, and with it `OptionsFrame_ApplySavedSettings`, this window's
-        -- VARIABLES_LOADED registration, and the multibar grid row's `loadFunc`. What the walk did
-        -- that the stock arm does not, checked one by one rather than assumed:
-        --
-        --   · `BuffButtons_UpdatePositions`, `SetChatMouseOverDelay`, `MultiActionBar_ShowAllGrids`
-        --     and `UIParentLoadAddOn("Blizzard_CombatText")` — the stock arm does all four, and it
-        --     runs FIRST (its frame registers at the l.21 seat, ours would register 30 rows later).
-        --   · `CombatText_UpdateDisplayedMessages` — the stock arm does not call it, and does not
-        --     need to: `Blizzard_CombatText`'s own `CombatText_OnLoad` calls it as its first act
-        --     (Blizzard_CombatText.lua l.81-84), and the addon loads INSIDE the stock arm, by
-        --     which time the saved uvars are already in place.
-        --   · `TargetofTarget_Update` — the stock arm does not call it either, and at
-        --     VARIABLES_LOADED there is no target, so `TargetFrame.lua:504`'s guard takes the else
-        --     branch and hides a frame that is already hidden. The row keeps it as its `applyFunc`,
-        --     which is the click behaviour and the only thing it was ever needed for.
-        --
-        -- The property the walk carried that still matters is `OptionsRow_Set`'s, and it stays
-        -- there: an `applyFunc` is a NAME, resolved when the row is applied, so a row whose
-        -- defining file a test harness never loaded applies nothing instead of raising.
+        -- 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.
 
-        -- A slider row's own range and readout, when the template's 0..1 / 5% / percent (the
-        -- volume shape) isn't it — called after OptionsRow_OnLoad in the row's OnLoad. The
-        -- refreshing guard: SetMinMaxValues re-clamps the held value and fires OnValueChanged,
-        -- and that clamp is wiring, not a player gesture — without the guard every load would
-        -- SetCVar the template's 0 clamped into the new range.
-        -- ── OptionsFrameSliders — THE REFERENCE'S TABLE, NOT OURS ANY MORE (2177) ───────────
-        -- `OptionsFrameSliders` is the video options window's own slider table (ref
-        -- `OptionsFrame.lua` l.24-34): one row per graphics slider, carrying the bounds the slider
-        -- is built with, PUBLISHED so addons can read and write it — pfUI's `hdgraphic` opens with
-        -- `_G.OptionsFrameSliders[3].maxValue = 15` (modules/hdgraphic.lua l.3).
-        --
-        -- **This file used to declare it, and no longer does.** Until 2177 the video window was not
-        -- loaded, so the name was free and our Graphics page published its own three rows into it
-        -- to keep that addon write landing on something. The stock window is on the manifest now
-        -- and brings the reference's own nine rows — and this file loads AFTER it, so a declaration
-        -- here would not sit beside them, it would REPLACE them, and `OptionsFrame_Load`'s
-        -- `getglobal("OptionsFrameSlider"..index)` walk would silently stop at three of nine.
-        --
-        -- **Nothing is lost, because our three rows WERE its rows 1-3.** Same order, same `func`
-        -- strings, same bounds: `uiscale` 0.64-1.0 step 0.01, `farclip` 177-777 step
-        -- (777-177)/10 = 60, `WorldDetail` 0-2 step 1. The Graphics page below still reads
-        -- `OptionsFrameSliders[1..3]` for its bounds — now off the reference's own table rather
-        -- than a transcription of it, which is the whole point of 1751 — and pfUI's index 3 still
-        -- lands on Environment Detail.
-        --
-        -- What WAS ours in those rows is the `benillaRow` field, and it moves here.
-        -- `BENILLA_GRAPHICS_SLIDER_ROWS` is index → the child of our Graphics page that the
-        -- reference's row drives; the reference addresses its own sliders as
-        -- `OptionsFrameSlider1..9`, a numbering our page does not use. An index with no entry is a
-        -- reference row we ship no knob for (rows 4, 5, 7 and 8: TerrainMip, BaseMip,
-        -- anisotropic, spellEffectLevel), and the OnShow re-apply loop skips it. Rows 6 and 9 are
-        -- Brightness (2182) and Weather Intensity (2181), which is why this table now has HOLES
-        -- rather than a run: the loop below is `for i, name in` — Lua 5.0's old-style `pairs` —
-        -- so it walks the keys that exist and an `ipairs` would have stopped at 3.
+        -- 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.
         BENILLA_GRAPHICS_SLIDER_ROWS = {
             "RowUiScale", "RowFarclip", "RowWorldDetail",
             [6] = "RowBrightness", [9] = "RowWeatherDensity",
         }
-        --
-        -- **Both WorldDetail verbs are bound** (2163), which is what makes pfUI's module RUN
-        -- rather than merely load: it hooks `SetWorldDetail`/`GetWorldDetail`, and hooking a nil
-        -- took its extended arm down at the first call. `SetWorldDetail` is `0x488dd0`'s carve —
-        -- truncate toward zero, `[0, 2]` or raise `"value must be in the range 0, 2"`, write the
-        -- `0x804518` stops {16, 32, 48} — and `GetWorldDetail` is `0x488d70` answering the stop.
-        -- They live in `benilla_ui::script::cvars`, not here; this page still drives the CVar
-        -- directly, so nothing on it calls either. The STOCK file does, now that it is loaded:
-        -- `OptionsFrame_Save`/`_Load` prefer `getglobal("Set"..func)` / `("Get"..func)` over
-        -- `SetCVar`/`GetCVar` (`OptionsFrame.lua` l.110/135/206-226) — but nothing of ours calls
-        -- those functions, because nothing of ours shows that window.
-        --
-        -- **The nine CVars pfUI's `hdgraphic` drives through `ConsoleExec`, each pinned** (2163;
-        -- `ConsoleExec` itself is bound since 1948 — it writes a registered CVar or pushes a
-        -- console command the app dispatches). Registered here, so the write lands:
-        -- `frillDensity` (2151, the clutter knob) and `nearClip` (2163, the camera near plane —
-        -- `0x511bd4` re-stamps `[cam+0x38]` from its record every frame, so it was never the dead
-        -- knob our own const claimed). Registered in the REFERENCE but with no benilla reader, so
-        -- they reach nothing here and registering them would be 1203's silent pretence:
-        -- `lodDist` (`0x688524`, "100.0" — its `[0x867960]` IS read at `0x6afb1d`, the doodad LOD
-        -- swap we do not have), `footstepBias` (`0x6888b4`, "0.125" — alive at `0x68fcb6`, but a
-        -- derived constant here with nothing to honour a write), `mapObjLightLOD` (`0x6886ec`,
-        -- "0") and `SkyCloudLOD` (`0x6d1d33`, "0"). Registered there and DEAD there — one writer,
-        -- no reader image-wide, so the reference renders identically whatever they say (wow-re
-        -- `cvar/scratch/graphics-cost-cvar-census.md` §8): `DistCull` (`0x688570`) and
-        -- `texLodBias` (`0x6885e2`, whose sink `0x672640` is literally `ret 4`). And `maxLOD` is
-        -- **not a CVar at all** — zero of the 214 `CVar::Register 0x63db90` sites name it — so
-        -- pfUI's `ConsoleExec("maxLOD " .. arg)` reaches nothing in the real client either.
 
+        -- 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, which is a share of this row's own range.
+            -- Kept for the "travel" readout, a share of the row's own range.
             row.minv, row.maxv = min, max
-            -- A grid that IS a short named ladder passes its names here (Environment Detail's
-            -- Low/Medium/High over 0/1/2): the groove is still the reference's slider, and the
-            -- readout says the stop rather than its index. 1.12's own slider printed no value at
-            -- all — it labelled the two ENDS — but every slider row in this kit carries a readout,
-            -- and "1" is the one thing that seat could say that means nothing to a player.
+            -- 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.
             row.stops = stops
             row.refreshing = 1
             slider:SetMinMaxValues(min, max)
@@ -1557,19 +988,14 @@
             row.refreshing = nil
         end
 
-        -- ── The dropdown rows (0992): the 1.12 kit under the era row grammar ────────────────
-        -- A dropdown row's choices: entries = { {text=..., value=...}, ... }, values the CVar's
-        -- own strings. The kit does the rest: every open re-runs the init through the stored
-        -- initialize (Toggle's own law), and AddButton auto-checks the entry matching the
-        -- capsule's selectedValue — which OptionsDropdown_ShowValue keeps equal to the CVar.
+        -- ── 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.
         function OptionsDropdownRow_Setup(row, entries)
             row.entries = entries
             local dd = getglobal(row:GetName() .. "Dropdown")
             UIDropDownMenu_SetWidth(180, dd)
             UIDropDownMenu_Initialize(dd, OptionsDropdownRow_InitMenu)
-            -- The capsule's toggle button is a mouse-enabled child — it steals hover from the
-            -- row, so it carries the row wash like the checkbox rows' box does. Hooked here
-            -- (SetScript) because the capsule template is the shared kit's, not this file's.
+            -- The capsule's button steals hover from the row, so it carries the row wash too.
             local btn = getglobal(dd:GetName() .. "Button")
             btn:SetScript("OnEnter", function() OptionsRow_Hover(this:GetParent():GetParent(), 1) end)
             btn:SetScript("OnLeave", function() OptionsRow_Hover(this:GetParent():GetParent(), nil) end)
@@ -1587,8 +1013,7 @@
             end
         end
 
-        -- The entry click (`this` = the list row, the kit's own calling law): the write, then
-        -- the capsule redisplay. The kit closes the list and plays its own click sound.
+        -- An entry 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()
@@ -1596,28 +1021,16 @@
             OptionsDropdown_ShowValue(row)
         end
 
-        -- Paint the capsule from the CVar. selectedValue is written as a FIELD, not through
-        -- SetSelectedValue: that helper's Refresh walks the SHARED DropDownList1 buttons, which
-        -- may still hold another dropdown's rows on this refresh path (the list is closed) —
-        -- a foreign row matching by value would repaint our capsule with its text. An off-grid
-        -- CVar value (an env A/B, a hand edit) displays the NEAREST stop — 0959's out-of-range
-        -- law, dropdown-flavored: control and check agree on the nearest expressible value,
-        -- the engine keeps running the config's truth, nothing writes back until the player
-        -- actually picks an entry. (A non-numeric stray shows raw and checks nothing.)
+        -- 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.
         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` is a second value the same entry ANSWERS to (1502): 1.12's own Camera
-                -- Following Style dropdown writes "3" for Never where the engine's tables are
-                -- indexed 0/1/2, so a config or addon carrying that value means Never — and the
-                -- nearest-stop fallback below, which assumes the values are ordinal, would show
-                -- "Always" for it. A categorical dropdown says which strays are its own.
-                -- `e.alt ~= nil` guards the nil-eats-everything case: a row whose store is not
-                -- there yet reads nil, and every entry without an `alt` would otherwise ANSWER to
-                -- it (nil == nil), leaving the capsule showing the last entry and the row wearing
-                -- its description. An entry answers to a second value only if it has one.
+                -- `alt`: 1.12's camera dropdown writes "3" for Never, which the nearest-value
+                -- fallback would show as Always. `e.alt ~= nil` keeps a nil value matching none.
                 if e.value == v or (e.alt ~= nil and e.alt == v) then match = e end
             end
             if not match and tonumber(v) then
@@ -1633,11 +1046,8 @@
             if match then
                 dd.selectedValue = match.value
                 UIDropDownMenu_SetText(match.text, dd)
-                -- A dropdown whose ENTRIES each carry their own description repaints the row's
-                -- plate as the selection moves — the reference's own shape for exactly this row
-                -- (UIOptionsFrameCameraDropDown_OnClick: `tooltip = getglobal("OPTION_TOOLTIP_
-                -- CAMERA"..GetSelectedID())`). Rows whose entries carry no `tip` keep the single
-                -- key OptionsRow_OnLoad gave them.
+                -- An entry with its own `tip` retargets the row's description, as
+                -- UIOptionsFrameCameraDropDown_OnClick does with OPTION_TOOLTIP_CAMERA<id>.
                 if match.tip then row.tip = match.tip end
             else
                 dd.selectedValue = v
@@ -1645,27 +1055,20 @@
             end
         end
 
-        -- The right-hand readout text (era MinimalSlider's RIGHT label seat): rounded percent
-        -- (era FormatPercentage, Audio.lua l.406-411) unless the row asked for the raw number.
+        -- 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 out its stop's name (see OptionsSliderRow_Setup). The index is
-            -- clamped, not wrapped: the slider itself has already clamped a config value from
-            -- outside the range, so this only ever guards a stops table shorter than the grid.
+            -- A named ladder reads its stop's name; 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
                 if i > table.getn(row.stops) then i = table.getn(row.stops) end
                 return row.stops[i]
             end
-            -- A row whose stored value is a CENTRED OFFSET: show where the thumb is, as a share
-            -- of the groove (2182). Brightness is the case -- its stored unit is the reference's
-            -- own `1 - gamma`, which runs -0.5 .. +0.5 with the default at 0, and a readout of
-            -- "0%" on a brightness control that is doing nothing wrong is exactly backwards. As
-            -- travel it reads 0 .. 100 with the default at 50, the way a brightness control reads
-            -- everywhere else, while the value the store keeps stays the reference's.
+            -- "travel": the thumb's share of the groove. Brightness stores the reference's
+            -- `1 - gamma` (-0.5 to +0.5, default 0) and reads 0 to 100% with the default at 50.
             if row.fmt == "travel" and row.minv and row.maxv and row.maxv > row.minv then
                 return string.format("%d%%",
                     math.floor((value - row.minv) / (row.maxv - row.minv) * 100 + 0.5))
@@ -1701,12 +1104,8 @@
             return string.format("%d%%", math.floor(value * 100 + 0.5))
         end
 
-        -- The era row-wide hover wash (HoverBackgroundTemplate, white a=0.1): the row and every
-        -- control on it show the SAME texture, so crossing from label to slider doesn't blink.
-        -- ONE seam carries the wash AND the plate (B223): every surface that lights the row also
-        -- raises its tooltip, so the two can never disagree — and the crossing is still seamless,
-        -- since the engine fires OnLeave before OnEnter within a move (pointer.rs), leaving the
-        -- hide/re-show inside a single frame.
+        -- 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.
         function OptionsRow_Hover(row, on)
             local hover = getglobal(row:GetName() .. "Hover")
             if on then
@@ -1718,30 +1117,17 @@
             end
         end
 
-        -- The row's descriptive plate (B223, decision 1054).
-        -- STRING: 1.12's own per-option text, by GlobalStrings key (see OptionsRow_OnLoad). A row
-        -- with no 1.12 string raises NOTHING — a plate whose only line echoes the label the cursor
-        -- is on is noise, and inventing a description would be inventing fidelity.
-        -- SHAPE: the 1.12/1.14 option-row plate — the description alone, wrapped, in the tooltip's
-        -- default gold (OptionsFrameTemplates.xml l.52-64: SetOwner + SetText(text, …, 1)); this
-        -- window already wears it on the Keybindings page's Character Specific row (1008). The era
-        -- pair (a white name line over the description) is cut — see the SCOPE note.
-        -- SEAT: the era's (DefaultTooltipMixin.OnEnter — ANCHOR_RIGHT, x -10, off the row's LABEL
-        -- half), carried by the $parentTip region, so the plate opens at the same column on every
-        -- row whichever surface the cursor crossed.
+        -- 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.
         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
-                -- A mute row PUTS AWAY whatever the last row raised. Entering a row asserts "this
-                -- row's plate is what shows", so an early return isn't enough: the ordinary cursor
-                -- path is saved by the outgoing row's own OnLeave, but any caller that enters
-                -- without one (a driven hover, a re-layout under the cursor) would leave the
-                -- neighbour's description standing over a row it doesn't describe — a plate saying
-                -- the wrong thing is worse than a row saying nothing. 1.12's own handler has the
-                -- bare early-out; this is deliberate, and it is why the mute case has a test.
+                -- 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.
                 GameTooltip:Hide()
             end
         end
@@ -1749,10 +1135,8 @@
         function OptionsCheckbox_OnClick(box)
             local row = box:GetParent()
             local checked = box:GetChecked()
-            -- Click kits: the 1.12 panels disagree with EACH OTHER — the interface panel's
-            -- PlayClickSound maps checked→CheckBoxOn (OptionsFrame.lua l.509), while the sound
-            -- panel's own OnClick maps checked→CheckBoxOff (SoundOptionsFrame.lua, the 0957
-            -- quirk) — so each page keeps its own panel's mapping (soundQuirk on Audio rows).
+            -- The 1.12 panels disagree: the interface panel plays CheckBoxOn when checked
+            -- (OptionsFrame.lua l.509), the sound panel CheckBoxOff; Audio rows carry soundQuirk.
             local kitOn = checked
             if row.soundQuirk then kitOn = not kitOn end
             if kitOn then
@@ -1760,9 +1144,7 @@
             else
                 PlaySound("igMainMenuOptionCheckBoxOff")
             end
-            -- The write: checked = 1 — unless the row is value-INVERTED (Sticky Targeting:
-            -- 1.12 checks it when deselectOnClick is "0", era wraps the same CVar in
-            -- NegateBoolean; both references agree).
+            -- An inverted row (Sticky Targeting, Disable Spam Filter) writes the opposite.
             local on = checked
             if row.invert then on = not on end
             if on then
@@ -1777,11 +1159,8 @@
             local control = slider:GetParent()
             local row = control:GetParent()
             if not row.refreshing then
-                -- era obeyStepOnDrag (MinimalSlider.xml l.5-7): user moves snap to the step
-                -- grid — anchored at the range MINIMUM, the reference slider's own anchor
-                -- (farclip's 1.12 grid is 177+n*60, not the multiples of 60). A refresh
-                -- writes the stored value raw (era SetValue does not snap), so an off-grid
-                -- config value still lands where it said.
+                -- 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.
                 local step = slider:GetValueStep()
                 if step and step > 0 then
                     local minv = slider:GetMinMaxValues()
@@ -1795,18 +1174,12 @@
             end
             getglobal(control:GetName() .. "Value"):SetText(OptionsRow_FormatValue(row, value))
             if OptionsRow_HasStore(row) and not row.refreshing then
-                -- Two decimals cover every page's grid (the 5% volumes, uiScale's 0.01, whole
-                -- yards); trailing zeros stripped so a value at the registered default
-                -- compares equal to it as a STRING and stays out of the config file ("0.40"
-                -- would read as moved-off-"0.4").
+                -- Two decimals, trailing zeros stripped, so a value at its default compares
+                -- equal as a string and stays out of the config file.
                 local str = string.gsub(string.format("%.2f", value), "%.?0+$", "")
                 if row.deferred then
-                    -- era CommitFlag.Apply, re-expressed (Blizzard_Setting.lua's staged
-                    -- SetValue half): the control shows the new value, the ENGINE keeps the
-                    -- old one, and the CVar moves only when Apply commits — dragging a
-                    -- slider that rescales itself mid-drag is exactly what this flag
-                    -- exists to prevent. Dragging back onto the committed value clears the
-                    -- pending (era's IsModified: a pending EQUAL to current isn't one).
+                    -- Era CommitFlag.Apply: shown at once, stored on Apply. A pending equal to
+                    -- the committed value is dropped, as the era's IsModified does.
                     if str == OptionsRow_Get(row) then
                         row.pending = nil
                     else
@@ -1825,10 +1198,8 @@
                 local row = getglobal(base .. rkey)
                 local box = getglobal(base .. rkey .. "Check")
                 if box then
-                    -- SetChecked takes the CVar string exactly like the 1.12 panel: the numeric
-                    -- read means "0" unchecks (button-check-and-state-texture.md). A
-                    -- value-inverted row checks on "0" instead — UIOptionsFrame.lua's own
-                    -- GAMEFIELD_DESELECT arm (`checked = 1` when the CVar reads "0").
+                    -- 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).
                     if row.invert then
                         local checked
                         if OptionsRow_Get(row) == "0" then checked = 1 end
@@ -1841,14 +1212,11 @@
                 else
                     local slider = getglobal(base .. rkey .. "ControlSlider")
                     row.refreshing = 1
-                    -- Pending first (era GetValue returns the pendingValue while one is
-                    -- staged): coming back to a page with an un-applied edit shows the edit.
+                    -- 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 — write the readout unconditionally,
-                    -- from the slider's OWN value: in range that IS the CVar (SetValue stores
-                    -- raw), out of range the thumb and the number at least agree on the
-                    -- nearest expressible value.
+                    -- SetValue fires only on a change, so the readout is written here, from the
+                    -- slider's own (clamped) value.
                     getglobal(base .. rkey .. "ControlValue"):SetText(
                         OptionsRow_FormatValue(row, slider:GetValue()))
                 end
@@ -1904,20 +1272,13 @@
         -- Speech; Enable Music stays live, the panel's own quirk).
         function OptionsPage_UpdateDependencies(key)
             if key == "Combat" then
-                -- The 1.12 rule, verbatim (UIOptionsFrame_UpdateDependencies' "Additional combat
-                -- text dependancies" block): the master off greys every FLOATING-TEXT sub-toggle
-                -- and the scroll dropdown. Combo Points carries the reference's second gate too —
-                -- it is disabled for anyone who is not a rogue or a druid, since nobody else has
-                -- combo points.
+                -- The combat-text block: the master off greys the floating-text rows, and Combo
+                -- Points is greyed for anyone but a rogue or druid.
                 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 (2180). The reference's own
-                -- "Additional combat text dependancies" block names 53…69 and stops; 19/11/9 are
-                -- governed by the separate test at l.709-714. Greying them here would be a rule
-                -- the reference does not have, and it would read as "floating combat text off
-                -- means no damage numbers", which is the opposite of what CombatDamage does.
+                -- The damage-number trio is not under this master: that block names 53..69 only.
                 local damage = {
                     RowShowDamage = 1, RowPeriodicDamage = 1, RowPetDamage = 1,
                 }
@@ -1929,12 +1290,7 @@
                             getglobal("BenillaOptionsFrameContainerBodyCombat" .. rkey), live)
                     end
                 end
-                -- 1.12's second gate on this page, verbatim (l.709-714): Show Target Damage off
-                -- greys Periodic Damage and Pet Damage. The CVars keep their values — this is a
-                -- UI dependency, not a write — and the engine agrees with the shape: at
-                -- `CombatDamage` "0" both of `0x607140`/`0x6128b0`'s branch targets are
-                -- epilogues, so nothing floats from any source and the two sub-gates below have
-                -- nothing left to gate.
+                -- l.709-714: Show Target Damage off greys Periodic and Pet Damage.
                 local dmg = GetCVar("CombatDamage") ~= "0"
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyCombatRowPeriodicDamage, dmg)
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyCombatRowPetDamage, dmg)
@@ -1962,48 +1318,33 @@
                 return
             end
             if key == "Controls" then
-                -- 1.12's own rule (l.715-719): the Auto-Follow Speed slider is dead while the
-                -- following style is Never, because there is no follow to set a speed for. The
-                -- reference tests its dropdown's selected ID against 3; ours stores the ENGINE's
-                -- values, where Never is "0" — and answers to "3" as well, since that is what
-                -- the reference's own dropdown writes and what a config or addon carrying it
-                -- means (the row's `alt`, decision 1502).
+                -- l.715-719: Auto-Follow Speed is dead while the style is Never, "0" in the
+                -- engine's values and "3" as the reference's dropdown writes it.
                 local style = GetCVar("cameraSmoothStyle")
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyControlsRowAutoFollowSpeed,
                     style ~= "0" and style ~= "3")
                 return
             end
             if key == "Nameplates" then
-                -- 1.12's own rule (l.702-708): Player Names off greys Player Guild Names. The
-                -- reference greys its PvP-title twin (CheckButton23) from the same test; that
-                -- row is still on the unbacked census, so there is one child here, not two.
+                -- l.702-708: Player Names off greys Player Guild Names.
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyNameplatesRowGuildNames,
                     GetCVar("UnitNamePlayer") ~= "0")
                 return
             end
             if key == "Interface" then
-                -- 1.12's own rule for this pair (UIOptionsFrame_UpdateDependencies l.694-700):
-                -- the mode picker is dead while the switch is unticked. It is the only
-                -- cross-row dependency on this page.
+                -- l.694-700: the target-of-target mode is dead while its switch is off.
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyInterfaceRowTargetOfTargetMode,
                     SHOW_TARGET_OF_TARGET ~= "0")
                 return
             end
             if key == "ActionBars" then
-                -- 1.12's own rule for this pair, verbatim in effect (UIOptionsFrame.lua l.722-726):
-                -- Show Right ActionBar 2 is dead while Show Right ActionBar is unticked, because
-                -- MultiBarLeft does not appear without MultiBarRight under it (stock
-                -- MultiActionBar_Update's conjunction). It is the only cross-row dependency on this page — the two bottom
-                -- bars, the grid switch and the lock are all independent.
+                -- l.722-726: Right ActionBar 2 is dead while Right ActionBar is off.
                 OptionsRow_SetEnabled(BenillaOptionsFrameContainerBodyActionBarsRowMultiBar4,
                     SHOW_MULTI_ACTIONBAR_3)
                 return
             end
             if key ~= "Audio" then return end
-            -- 1.12's own rule, both halves: SoundOptionsFrame_UpdateDependencies greys check
-            -- button 2 (Enable Ambience) AND button 4 (Enable Error Speech) while the master
-            -- enable is unticked. Enable Music is deliberately left alive — the quirk the
-            -- reference's own file has.
+            -- SoundOptionsFrame_UpdateDependencies; Enable Music stays live, as in 1.12.
             local on = GetCVar("MasterSoundEffects") ~= "0"
             for _, row in {"RowEnableAmbience", "RowEnableErrorSpeech"} do
                 local box = getglobal("BenillaOptionsFrameContainerBodyAudio"..row.."Check")
@@ -2018,29 +1359,14 @@
             end
         end
 
-        -- Grey or wake one row, whichever control it wears (the Audio rule above predates this and
-        -- reaches its one checkbox by name). A dropdown row greys the way 1.12's own
-        -- OptionsFrame_DisableDropDown does — the capsule's toggle BUTTON disabled so the list
-        -- cannot open, and its text in GRAY_FONT_COLOR — since the chain's own
-        -- UIDropDownMenu_DisableButton addresses a LIST row (level, id), not the capsule, and
-        -- 1.12 has no `UIDropDownMenu_DisableDropDown` at all.
+        -- Grey or wake one row. A dropdown greys as OptionsFrame_DisableDropDown does, button
+        -- disabled and text gray; 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 row greys the way 1.12's own OptionsFrame_DisableSlider does (l.481-486):
-            -- the THUMB is hidden — which is what says "this groove is dead" at a glance — and
-            -- the readout goes gray. Its Low/High end captions have no counterpart here; this kit
-            -- carries one readout instead of the reference's two.
-            --
-            -- **And the mouse bit, which the reference does not need and we do.** There is no
-            -- `Slider:Disable()` to call — 1.12 gives a Slider no enabled state at all, which is
-            -- why this kit's Slider has no such method (script/slider.rs's `begin_drag`) — and a
-            -- thumbless 1.12 slider is already undraggable. Ours is not: a press anywhere on the
-            -- track seats the value (0250 §5's jump), so a greyed groove would still answer a
-            -- click. `EnableMouse(false)` is how the reference keeps anything off the press, and
-            -- it takes the frame out of the hit test, so the row underneath keeps its hover wash
-            -- instead of losing it with the control.
+            -- 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.
             local sl = getglobal(name .. "ControlSlider")
             if box then
                 if on then box:Enable() else box:Disable() end
@@ -2076,10 +1402,7 @@
             end
         end
 
-        -- Defaults, live on any page with rows: every row's CVar back to its registered
-        -- default (era resets per-setting the same way; the era all-pages confirm dialog is
-        -- not modeled — Defaults resets the VISIBLE page). A pending edit dies with it — the
-        -- default write supersedes what Apply would have committed.
+        -- Defaults: the visible page back to its registered defaults, pending edits dropped.
         function OptionsPage_Defaults(key)
             local base = "BenillaOptionsFrameContainerBody" .. key
             for _, rkey in ipairs(OPTIONS_PAGE_ROWS[key]) do
@@ -2090,14 +1413,10 @@
             OptionsPage_Refresh(key)
         end
 
-        -- ── The Apply flow (0961): era CommitFlag.Apply, cut to our rows ────────────────────
-        -- Pending edits are PANEL-wide like era's modified table: they survive a category
-        -- switch (the row redisplays its pending on return) and commit together; only hiding
-        -- the window discards them (era wipes on hide too — its close-time 3-button confirm
-        -- dialog and the 8-second revert timer are not modeled, SCOPE note).
+        -- ── The Apply flow: era CommitFlag.Apply ──
+        -- Pending edits are panel-wide: they survive a category switch; hiding discards them.
 
-        -- The era Apply gate (HasUnappliedSettings + SetApplyButtonEnabled): the button is
-        -- enabled AND shown together — it EXISTS only while something is pending.
+        -- 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
@@ -2115,8 +1434,7 @@
             end
         end
 
-        -- Commit (era SettingsPanelMixin:CommitSettings, cut to our rows): every pending
-        -- value everywhere becomes a real SetCVar, and the button goes away.
+        -- Commit every pending edit (era SettingsPanelMixin:CommitSettings).
         function OptionsPage_Apply()
             for key, rows in pairs(OPTIONS_PAGE_ROWS) do
                 local base = "BenillaOptionsFrameContainerBody" .. key
@@ -2131,8 +1449,7 @@
             OptionsApply_Update()
         end
 
-        -- Hide = discard (era's WipeModifiedTable-on-hide; the confirm dialog is cut): the
-        -- next open re-reads the committed CVars, so the sliders land back on the truth.
+        -- 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
@@ -2144,9 +1461,8 @@
         end
     ]]></Script>
 
-    <!-- The red panel button (era UIPanelButtonTemplate seat, 96x22): GameMenuButtonTemplate's
-         four-state UI-Panel-Button art + white/white/grey label trio, copied at this window's
-         size (GameMenuFrame.xml l.145 is the shared original; templates don't cross files). -->
+    <!-- The red panel button (era UIPanelButtonTemplate, 96x22), a copy of
+         GameMenuButtonTemplate (GameMenuFrame.xml l.145), which loads after this file. -->
     <Button name="OptionsRedButtonTemplate" virtual="true">
         <Size><AbsDimension x="96" y="22"/></Size>
         <ButtonText name="$parentText"/>
@@ -2159,20 +1475,9 @@
         <DisabledFont inherits="GameFontDisable"/>
     </Button>
 
-    <!-- One category row (era Blizzard_CategoryList.xml's category button): the template's
-         175 width is never rendered in the era either — the ScrollBox stretches every row to
-         the scroll target's width, 199 with no scroll bar (CategoryList.lua l.176-197 +
-         ScrollBoxViewUtil), and ours is the no-bar case. Gold label centered in the row (the
-         full-row box below).
-         The select/hover wash is the 1.14 OptionsListButtonTemplate mechanism VERBATIM (0984;
-         wow-ui-source @1.14.4 OptionsFrameTemplates.xml l.216-229 + .lua l.107-131 — 0978's
-         two-texture BLEND washes drew as opaque bars, the director's report): ONE
-         UI-QuestLogTitleHighlight quad in ADD blend, tinted steel-blue (.196,.388,.8) as the
-         hover and locked GOLD (1,1,0) on the selected row — 1.14's SetVertexColor pair around
-         LockHighlight/UnlockHighlight, carried here as Show/Hide on the Bg (our selection is
-         Lua-driven, not button-state-driven). Geometry stays the era plate seat (187x21
-         centered, 6 units in from either edge of the 199 row — sized once in
-         OptionsCategoryRow_OnLoad); hover text goes white via HighlightFont, 1.14's own trio. -->
+    <!-- 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. -->
     <Button name="OptionsCategoryRowTemplate" virtual="true">
         <Size><AbsDimension x="199" y="20"/></Size>
         <Layers>
@@ -2182,13 +1487,8 @@
                 </Texture>
             </Layer>
         </Layers>
-        <!-- The era label is a box spanning the WHOLE row — TOPLEFT (36,+1) AND BOTTOMRIGHT
-             (0,+1), era CategoryList.xml l.72-77 — so the default MIDDLE vertical justify
-             CENTERS the text in the 20-tall row (1 unit high of true center, the era's own
-             nudge). The first cut had only the TOPLEFT corner: the auto-sized label hung from
-             the row TOP, ~4 units high of center ("text not vertically centered" — director,
-             2026-08-04). justifyH LEFT is the era's own attribute; a full-row box without it
-             would center horizontally. -->
+        <!-- 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. -->
         <ButtonText name="$parentText" justifyH="LEFT">
             <Anchors>
                 <Anchor point="TOPLEFT"><Offset><AbsDimension x="36" y="1"/></Offset></Anchor>
@@ -2200,8 +1500,7 @@
         <DisabledFont inherits="GameFontDisable"/>
         <Scripts>
             <OnClick>BenillaOptionsFrame_SelectCategory(this.categoryKey)</OnClick>
-            <!-- 1.14's highlight shows on hover with the blue tint standing (the selected row
-                 holds its locked gold — the guard is UnlockHighlight's job here). -->
+            <!-- The hover wash; the selected row keeps its locked gold. -->
             <OnEnter>
                 if BenillaOptionsFrame.selectedCategory ~= this.categoryKey then
                     getglobal(this:GetName() .. "Bg"):Show()
@@ -2215,10 +1514,8 @@
         </Scripts>
     </Button>
 
-    <!-- A category group header (era SettingsCategoryListHeaderTemplate geometry: 30 tall,
-         stretched to the 199 row width like the rows, 14px white label at LEFT (20,-1)). The
-         era's Options_CategoryHeader_<n> background wash has no 1.12 counterpart and is
-         dropped (header mapping note) — the header is its label alone. -->
+    <!-- A category header (era SettingsCategoryListHeaderTemplate); the era's
+         Options_CategoryHeader_<n> wash has no 1.12 art and is dropped. -->
     <Frame name="OptionsCategoryHeaderTemplate" virtual="true">
         <Size><AbsDimension x="199" y="30"/></Size>
         <Layers>
@@ -2230,13 +1527,9 @@
         </Layers>
     </Frame>
 
-    <!-- A search-results group header (era SettingsListSearchCategoryTemplate —
-         Blizzard_SettingsList.xml l.65-87 + .lua l.14-33): 45 tall, the category's name in
-         GameFontNormalLarge at TOPLEFT (16,-16), clickable — the click selects its category,
-         which ends the search (the era's own jump; SelectCategory clears the box). Unanchored
-         until a search chains it in (OptionsSearch_Place). The era's mouseover is a 0.1-gray
-         ADD overlay; this wears the setting rows' white-0.1 wash instead — the same read, the
-         file's one hover idiom (0984 notes the divergence). -->
+    <!-- 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. -->
     <Button name="OptionsSearchHeadTemplate" virtual="true" hidden="true">
         <Size><AbsDimension y="45"/></Size>
         <Layers>
@@ -2262,15 +1555,9 @@
         </Scripts>
     </Button>
 
-    <!-- One SETTING row, checkbox flavor (era SettingsCheckboxControlTemplate over
-         SettingsListElementTemplate, Blizzard_SettingControls.xml l.50-112): 26 tall, stretched
-         to the page width by its instance anchors; label GameFontNormal in a LEFT(37) →
-         CENTER(-85) box (the era mixin's runtime anchors, SettingControls.lua l.322-323); the
-         30x29 box at LEFT = row CENTER-80 (l.473). The checkbox art is the 1.12 UI-CheckBox
-         set at the era state seats (0978 mapping; the era used its minimal set): Up normal,
-         Down pushed, Check checked, Check-Disabled disabled+checked; no HighlightTexture —
-         hover feedback stays the era row-wide Hover wash (HoverBackgroundTemplate: white
-         a=0.1, hung 10 left / 5 right of the row), so the box doesn't double-light. -->
+    <!-- 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. -->
     <Frame name="OptionsCheckboxRowTemplate" virtual="true" enableMouse="true">
         <Size><AbsDimension y="26"/></Size>
         <Layers>
@@ -2293,12 +1580,8 @@
             </Layer>
         </Layers>
         <Frames>
-            <!-- The tooltip's SEAT (B223): the era's own anchor region, verbatim geometry — the
-                 row's LABEL half, TOPLEFT out to (BOTTOM, -80), i.e. the control column
-                 (SettingsListElementTemplate's $parentTooltip, Blizzard_SettingControls.xml
-                 l.57-61). The era hangs its hover wash AND its mouse scripts here; ours borrows
-                 the RECT only — the row lights and raises as one surface (OptionsRow_Hover) — so
-                 this frame stays mouse-less and can never steal the row's own hover. -->
+            <!-- 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. -->
             <Frame name="$parentTip">
                 <Anchors>
                     <Anchor point="TOPLEFT"/>
@@ -2325,29 +1608,11 @@
         </Scripts>
     </Frame>
 
-    <!-- One SETTING row, slider flavor (era SettingsSliderControlTemplate →
-         MinimalSliderWithSteppersTemplate, SettingControls.lua l.550-552 + MinimalSlider.xml):
-         the same 26-tall row and label box; the 250x40 control at LEFT = row CENTER(-80,+3)
-         (its 40 height overrides the row symmetrically). Inside: the Slider inset 19 each
-         side — spanning the groove exactly — hit area the full height, the way era's is
-         (mouse-enabled by the widget's own construction, 0250's law — no attr needed). The
-         TRACK is the 0978 mapping — the 1.12 OptionsSliderTemplate groove verbatim
-         (extracted OptionsFrameTemplates.xml l.74: UI-SliderBar-Background/-Border backdrop,
-         edge 8, tile 8, insets 3/3/6/6) on a 17-tall Groove frame at the era track seat (the
-         era's own three-slice was 17 tall, centered), with the 1.12 32x32
-         UI-SliderBar-Button-Horizontal thumb. NO steppers — 0984 wore them at 26x26 as kept
-         era structure; 0989 cut them by the director's call (a recorded exception to 0985's
-         keep): the bar alone is the control, and the whole bar is live — thumb drag always
-         worked but the visible knob is a small target, so 0989's engine track-press law
-         seats the thumb under a press anywhere on the bar and drags on from there. The
-         readout is era's RIGHT label seat — 6 right of the control (MinimalSlider.xml
-         l.73-77), rounded-percent formatted.
-         THE +3 LIVES ON THE ART, NOT ON THE CONTROL (B232, decision 1641). It seats the
-         17-tall groove and the 32 px thumb inside the 26-tall row, so it belongs to the two
-         frames that draw them — $parentGroove and $parentSlider. It used to sit on
-         $parentControl itself, where the readout inherited it: every slider row drew its number
-         3 units above its own label, one line asked to read as two. The art's seat is unchanged
-         to the pixel; the text is what moved. -->
+    <!-- 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. -->
     <Frame name="OptionsSliderRowTemplate" virtual="true" enableMouse="true">
         <Size><AbsDimension y="26"/></Size>
         <Layers>
@@ -2370,10 +1635,8 @@
             </Layer>
         </Layers>
         <Frames>
-            <!-- The tooltip's seat — the era label-half region (the checkbox template's comment is
-                 the recipe). The era anchors a SLIDER row's plate off the slider itself instead
-                 (SettingControls.lua l.556, ANCHOR_RIGHT +20); ours keeps the one column, so a
-                 walk down a page doesn't make the plate hop 250 units per row. -->
+            <!-- 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. -->
             <Frame name="$parentTip">
                 <Anchors>
                     <Anchor point="TOPLEFT"/>
@@ -2391,9 +1654,7 @@
                     </Layer>
                 </Layers>
                 <Frames>
-                    <!-- The groove: the 1.12 slider's own backdrop on a frame at the era track
-                         seat (17 tall, vertically centered, spanning the slider's run).
-                         Declared before the Slider so the thumb draws above it. -->
+                    <!-- The groove, declared before the Slider so the thumb draws above it. -->
                     <Frame name="$parentGroove">
                         <Size><AbsDimension y="17"/></Size>
                         <Anchors>
@@ -2429,18 +1690,9 @@
         </Scripts>
     </Frame>
 
-    <!-- One SETTING row, dropdown flavor (0992 — the first): the same era 26-tall row and
-         label box; the control is the 1.12 dropdown CAPSULE verbatim (UIDropDownMenuTemplate —
-         the kit every 1.12 dropdown wears, UIDropDownMenu.xml), seated so its box ink opens at
-         the era control column (the capsule's Left cap carries ~10 units of air before its
-         ink, hence the -71 anchor against the sliders' CENTER-80 + 19 groove seat; width 180
-         makes the ink span read as the slider track's). SHAPE provenance: the era's own
-         control for an enumerated setting is a dropdown (SettingsDropdownControlTemplate — its
-         Graphics page is a zoo of them), while 1.12 shaped this row's setting as a 3-stop
-         slider; the era grammar wins the shape by the director's call ("some with dropdown"),
-         recorded in 0992. The list the capsule opens rides the kit's own law — shared
-         DropDownList1, FULLSCREEN_DIALOG strata (above this HIGH window), the owner's
-         effective scale (the kit's 0992 correction), the 2-second hover-away close. -->
+    <!-- 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. -->
     <Frame name="OptionsDropdownRowTemplate" virtual="true" enableMouse="true">
         <Size><AbsDimension y="26"/></Size>
         <Layers>
@@ -2463,8 +1715,7 @@
             </Layer>
         </Layers>
         <Frames>
-            <!-- The tooltip's seat — the era label-half region (the checkbox template's comment is
-                 the recipe). -->
+            <!-- The tooltip seat, as on the checkbox row. -->
             <Frame name="$parentTip">
                 <Anchors>
                     <Anchor point="TOPLEFT"/>
@@ -2481,18 +1732,13 @@
         </Scripts>
     </Frame>
 
-    <!-- `toplevel` restored (ref OptionsFrame.xml l.3) — same class as the B180/Bagnon dialog
-         (decision 1318). NOTE our strata is HIGH where the ref is DIALOG; left as-is, flagged in
-         the record rather than silently changed. -->
+    <!-- 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. -->
     <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 dialog, verbatim (BACKDROP_DIALOG_32_32 — wow-ui-source
-             @1.14.4 Backdrop.lua l.17-25, the backdrop OptionsFrameTemplate/
-             InterfaceOptionsFrame wear): the tiled UI-DialogBox-Background ground — a uniform
-             pure-black 60%-alpha tile, so the world reads through the window exactly like the
-             reference screenshot (0981: the reference was never parchment) — inside the rope
-             border. Both files are 1.12's own. -->
+        <!-- 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. -->
         <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>
@@ -2500,28 +1746,9 @@
         </Backdrop>
         <Layers>
             <Layer level="BACKGROUND">
-                <!-- THE GROUND DIM (1476) — a plain black fill over the tiled ground, because
-                     the tile alone is not a readable page. UI-DialogBox-Background decodes to a
-                     uniform (0,0,0,153) — pure black at 0.6 — so 40% of the world reaches the
-                     text: over snow, noon water or a lit sky the page ground lands near mid-grey
-                     and the option labels stop reading (the director's report). 0.6 is right for
-                     a dialog you glance at; the options window is a page you READ, and the era's
-                     own answer is an OPAQUE FlatPanelBackgroundTemplate panel — so darkening
-                     toward it is the era structure 0985 already gives us, wearing a plain colour
-                     fill, which 0985 names as an art byte we may author.
-                     Alpha 0.7 over the 0.6 tile composites to 0.88 (the world reaches the page at
-                     0.12), not 1.0: the faint read-through is the window's character, and 0981's
-                     "the reference was never parchment" finding stands — this dims the ground, it
-                     does not replace it.
-                     SEAT: inset 15 on all four sides, NOT the backdrop's own 11/12/12/11 bg
-                     insets. Regions sort AFTER the frame's own draw slot, which is where the
-                     backdrop's bg AND its 8 border pieces both live (extract.rs) — so this fill
-                     paints OVER the rope, and at the bg insets it would smear 0.7 black across
-                     the border's inner half. The rope's ink is measured, not guessed: every edge
-                     slice of UI-DialogBox-Border is opaque only in its outer ~11 units and dead
-                     by texel 16 of 32, and the corner slices' ink ends by 14 (decoded). 15 clears
-                     every inked texel and leaves at most a 1-unit lighter hairline inside the
-                     rope, where the rope reads as frame anyway. -->
+                <!-- 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. -->
                 <Texture name="$parentGroundDim">
                     <Anchors>
                         <Anchor point="TOPLEFT"><Offset><AbsDimension x="15" y="-15"/></Offset></Anchor>
@@ -2531,20 +1758,15 @@
                 </Texture>
             </Layer>
             <Layer level="ARTWORK">
-                <!-- The carved title plate at the 1.14 options frames' own seat: 300x68 at
-                     TOP (0,+12) — OptionsFrameTemplates.xml l.244-255 (GameMenuFrame's plate
-                     is the smaller 256x64 dialog cut). -->
+                <!-- 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">
-                <!-- Title ON the plate (GameMenuFrame's seat), not the era's bare TOP (0,-5)
-                     band seat — the plate is where a 1.12 dialog carries its name. GameFontNormal
-                     rather than the menu's GameFontNormalMed1: that font object is declared
-                     beside its consumer in GameMenuFrame.xml (0952's residue convention), which
-                     loads AFTER this file. -->
+                <!-- The title on the plate, as a 1.12 dialog carries it. 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>
@@ -2553,19 +1775,10 @@
             </Layer>
         </Layers>
         <Frames>
-            <!-- ── The two boxes — 1.14's OptionsFrameListTemplate / $parentPanelContainer
-                 idiom, verbatim mechanism (OptionsFrameTemplates.xml l.113-116 + l.286-289 +
-                 SharedTooltipTemplates.xml l.117-121): a TOOLTIP-BORDER backdrop with the
-                 FILL AT ALPHA 0 — the boxes are outlines; the window's translucent ground
-                 reads through them — and the border tinted LIGHTGRAY_FONT_COLOR (0.6, the
-                 engine-side constant; the 0981 record cites it). Declared FIRST so every
-                 sibling draws above them. Anchors are window-absolute (the boxed frames are
-                 declared later; no forward refs): both tops at -52 — 0981 took 1.14's -40
-                 band verbatim, but 1.14's band never held a search box; ours holds the
-                 era's (structure is the era's — 0985's split), and at -40 the box line ran
-                 through the search's seat (the director's "make some space up there"). -52
-                 is the depth that gives the era search seat its clearances while the tabs
-                 stay tucked on the box line below. -->
+            <!-- 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. -->
             <Frame name="$parentCategoryBox">
                 <Anchors>
                     <Anchor point="TOPLEFT"><Offset><AbsDimension x="10" y="-52"/></Offset></Anchor>
@@ -2600,19 +1813,10 @@
                     </OnLoad>
                 </Scripts>
             </Frame>
-            <!-- ── Tabs — seated the 1.14 way: the tab's BOTTOM sits on the category box's
-                 top edge, tucked 3 units INTO it (InterfaceOptionsFrame.xml l.152-158:
-                 Tab1 BOTTOMLEFT → Categories TOPLEFT (6,-3)) — the file-folder read, no dead
-                 band above (0981; 0978 floated them at the era's TOPLEFT (32,-27) over a
-                 24-unit bare strip, the director's gap report). Era width/text law kept
-                 (width text+40 measured once per show, selected white small text at BOTTOM+6
-                 vs gold at BOTTOM+4),
-                 authored STATIC: Game is the only tab with anything behind it, so it wears
-                 the selected state permanently and AddOns the unselected one (still dead to
-                 clicks; the mixin port comes with an addon list). The PLATE is the 0978
-                 mapping, kept: one UI-Character-{Active,InActive}Tab piece, bottom-anchored
-                 at the era plate height (26/23), flipped vertically via TexCoords (1.12 only
-                 ships bottom-tab plates; the flip turns them top-tab). -->
+            <!-- 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. -->
             <Button name="$parentGameTab">
                 <Size><AbsDimension x="72" y="37"/></Size>
                 <Anchors>
@@ -2663,26 +1867,22 @@
                 <NormalFont inherits="GameFontNormalSmall"/>
                 <HighlightFont inherits="GameFontNormalSmall"/>
                 <DisabledFont inherits="GameFontNormalSmall"/>
-                <!-- No addon list behind it: dead to clicks, but wearing the era's unselected
-                     GOLD (not disabled grey) — the director's capture is the call. -->
+                <!-- No addon list behind it: disabled, but 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 (era CategoryList; static, it fits) ── -->
             <Frame name="$parentCategoryList">
                 <Size><AbsDimension x="199"/></Size>
-                <!-- Top rides the box line: box top -52 + the same 12-unit interior pad the
-                     -76 seat gave the era's -64 box (the era's own list-to-box air). -->
+                <!-- The top: the box top (-52) plus the era's 12-unit list-to-box pad. -->
                 <Anchors>
                     <Anchor point="TOPLEFT"><Offset><AbsDimension x="18" y="-64"/></Offset></Anchor>
                     <Anchor point="BOTTOMLEFT"><Offset><AbsDimension x="18" y="46"/></Offset></Anchor>
                 </Anchors>
-                <!-- The era list rhythm (CreateScrollBoxListLinearView spacing=2 + the 18-tall
-                     SettingsCategoryListSpacerTemplate between groups): 2 between every
-                     element, 2+18+2 = 22 from a group's last row to the next header. -->
+                <!-- The era list rhythm: spacing 2, and an 18-tall spacer between groups. -->
                 <Frames>
                     <Frame name="$parentHeaderGameplay" inherits="OptionsCategoryHeaderTemplate">
                         <Anchors><Anchor point="TOPLEFT"/></Anchors>
@@ -2714,8 +1914,7 @@
                         <Anchors><Anchor point="TOPLEFT" relativeTo="$parentRowChat" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-2"/></Offset></Anchor></Anchors>
                         <Scripts><OnLoad>OptionsCategoryRow_OnLoad(self, "Keybindings", "Keybindings")</OnLoad></Scripts>
                     </Button>
-                    <!-- Nameplates — the era Gameplay group's own last row (NAMEPLATE_OPTIONS_LABEL,
-                         order 15), backed by benilla's real nameplate knobs when the pages land. -->
+                    <!-- The era Gameplay group's last row (NAMEPLATE_OPTIONS_LABEL). -->
                     <Button name="$parentRowNameplates" inherits="OptionsCategoryRowTemplate">
                         <Anchors><Anchor point="TOPLEFT" relativeTo="$parentRowKeybindings" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-2"/></Offset></Anchor></Anchors>
                         <Scripts><OnLoad>OptionsCategoryRow_OnLoad(self, "Nameplates", "Nameplates")</OnLoad></Scripts>
@@ -2747,7 +1946,7 @@
                 </Frames>
             </Frame>
 
-            <!-- ── The page area (era SettingsList's header; the body is next slice's) ─────── -->
+            <!-- ── The page area (era SettingsList) ── -->
             <Frame name="$parentContainer">
                 <Anchors>
                     <Anchor point="TOPLEFT" relativeTo="$parentCategoryList" relativePoint="TOPRIGHT"><Offset><AbsDimension x="16" y="0"/></Offset></Anchor>
@@ -2755,13 +1954,8 @@
                 </Anchors>
                 <Layers>
                     <Layer level="ARTWORK">
-                        <!-- The era options_horizontaldivider seat (TOP, -50) wearing what
-                             that atlas member actually IS — decoded from the era sheet
-                             (fdid 1318750, a 630x1 row): pure white at ~0.3 alpha, a
-                             hairline. Authored as a 1-unit color fill (0981; no art file —
-                             0978's UI-DialogBox-Divider ink band stretched thin read as
-                             artifacts, the director's separator report). Span keeps the
-                             0978 seat: the container minus 20 units each side. -->
+                        <!-- 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). -->
                         <Texture name="$parentDivider">
                             <Size><AbsDimension y="1"/></Size>
                             <Anchors>
@@ -2772,17 +1966,14 @@
                         </Texture>
                     </Layer>
                     <Layer level="OVERLAY">
-                        <!-- The page title — BenillaOptionsFrame_SelectCategory writes it. -->
+                        <!-- The page title, written by BenillaOptionsFrame_SelectCategory. -->
                         <FontString name="$parentTitle" inherits="OptionsFontHighlightHuge">
                             <Anchors><Anchor point="TOPLEFT"><Offset><AbsDimension x="7" y="-22"/></Offset></Anchor></Anchors>
                         </FontString>
                     </Layer>
                 </Layers>
                 <Frames>
-                    <!-- Live on any page with rows (OPTIONS_PAGE_ROWS) and on the Keybindings
-                         page, where it is 1.12's Reset To Default behind the era confirm
-                         (KeyBindingsPage.xml's popup); BenillaOptionsFrame_SelectCategory
-                         enables/disables it with the page swap. -->
+                    <!-- On the Keybindings page, 1.12's Reset To Default behind a confirm. -->
                     <Button name="$parentDefaults" inherits="OptionsRedButtonTemplate" text="Defaults">
                         <Anchors><Anchor point="TOPRIGHT"><Offset><AbsDimension x="-36" y="-16"/></Offset></Anchor></Anchors>
                         <Scripts>
@@ -2796,9 +1987,7 @@
                             </OnClick>
                         </Scripts>
                     </Button>
-                    <!-- Unbind Key (1.12's own button, reseated in the header band): exists only
-                         on the Keybindings page, live only while a capsule is selected
-                         (KeyBindings_UpdateUnbindKey drives the enable). -->
+                    <!-- 1.12's Unbind Key: Keybindings only, live while a capsule is selected. -->
                     <Button name="$parentUnbind" inherits="OptionsRedButtonTemplate" hidden="true">
                         <Anchors><Anchor point="RIGHT" relativeTo="$parentDefaults" relativePoint="LEFT"><Offset><AbsDimension x="-2" y="0"/></Offset></Anchor></Anchors>
                         <Scripts>
@@ -2812,29 +2001,9 @@
                             </OnClick>
                         </Scripts>
                     </Button>
-                    <!-- ── The page area SCROLLS (the real-scroll kit, decision 0112) ────────────
-                         The body below IS this frame's scroll child, so every page, row, search
-                         head and keybinding capsule under it pans and CLIPS to the visible page
-                         rect instead of drawing past the window. 0950's header said "MinimalScrollBar
-                         arrives when one outgrows the space"; the SEARCH is what outgrew it first —
-                         a query that matches across categories chains five group heads and every
-                         matched row into one column, which for a broad query runs ~150 units past
-                         the body's own bottom and out through the dialog border onto the world
-                         (B217). The era's answer is the same one: its SettingsList is a ScrollBox
-                         with a MinimalScrollBar (Blizzard_SettingsList.xml l.48-58), and results and
-                         pages ride the same one.
-
-                         The body is sized by OptionsScroll_Fit each frame: normally EXACTLY this
-                         frame's rect — range 0, no bar, every page seated where it has always been,
-                         including the Keybindings page that fills the body and runs its own faux
-                         list inside it — and grown to the measured content only when a layout
-                         outruns it. So nothing about the fitting pages moves; the scroll appears
-                         only where the overflow is.
-
-                         enableMouse so a wheel spin over blank page area lands here rather than
-                         falling through to the window (hit-testing only sees mouse-enabled frames);
-                         a spin over the Keybindings page still hits ITS handler first, which is the
-                         nearer ancestor, so the inner list keeps the wheel where it owns it. -->
+                    <!-- 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. -->
                     <ScrollFrame name="$parentScroll" enableMouse="true">
                         <Anchors>
                             <Anchor point="TOPLEFT"><Offset><AbsDimension x="0" y="-50"/></Offset></Anchor>
@@ -2849,54 +2018,28 @@
                             <OnScrollRangeChanged>BenillaScroll_SyncBar(this)</OnScrollRangeChanged>
                         </Scripts>
                         <Frames>
-                            <!-- The bar's trough (the shared kit's). No anchors: it seats itself on
-                                 the bar named by dropping this frame's "Trough" suffix, at the ref's
-                                 own hang — the socket law is one law and lives in
-                                 BenillaScrollTrough_Seat, not restated here. That puts it in the
-                                 SAME gutter the Keybindings page's own bar uses — the two are never
-                                 live together (this one's range is 0 on that page, since the page
-                                 fills the body), so the gutter holds exactly one bar at a time.
-                                 Declared before the body and the bar so it is beneath both by
-                                 link-stamp as well as by layer. -->
+                            <!-- 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. -->
                             <Frame name="$parentBarTrough" inherits="BenillaScrollTroughTemplate"/>
-                            <!-- The page body: one child frame per category with rows, shown by
-                                 BenillaOptionsFrame_SelectCategory (Audio 0957, Graphics 0959). Named in
-                                 full rather than `$parent…`: it keeps the name every page, row and
-                                 search seat is derived from, across the scroll frame that now sits
-                                 between it and the container. Its SIZE is authored here because a
-                                 scroll child's anchors are the engine's (SetScrollChild pins it
-                                 TOPLEFT, offset by the scroll — layout.rs) and only its own width
-                                 and height are read; these are the container's own 665 x (613-50),
-                                 the seat it held before, and OptionsScroll_Fit keeps them true
-                                 against the live rect from there on. -->
+                            <!-- 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. -->
                             <Frame name="BenillaOptionsFrameContainerBody">
                                 <Size><AbsDimension x="665" y="563"/></Size>
                             <Layers>
                                 <Layer level="OVERLAY">
-                                    <!-- The empty-search line (era SETTINGS_SEARCH_NOTHING_FOUND
-                                         on the SettingsListSectionHeaderTemplate seat:
-                                         GameFontHighlightLarge, the header's (7,-16) inside the
-                                         first 45-tall slot -> (17,-28) off the body with the
-                                         layout pads). Shown only by a no-match search. -->
+                                    <!-- The no-match line (era SETTINGS_SEARCH_NOTHING_FOUND, 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 (0961): the gameplay checkboxes with benilla
-                                     knobs behind them, in the era Controls page's own row order
-                                     (Controls.lua @1.15.9: Sticky Targeting #1, Auto Loot #6,
-                                     Invert Mouse #12 — its Mouse section header is cut while one
-                                     row survives under it). Sticky Targeting is value-INVERTED in
-                                     BOTH references (1.12 UIOptionsFrame checks it on
-                                     deselectOnClick=="0"; era wraps the CVar in NegateBoolean);
-                                     labels are 1.12 GlobalStrings where the row exists there
-                                     (GAMEFIELD_DESELECT_TEXT, INVERT_MOUSE), era's for Auto Loot
-                                     (no 1.12 row exists) — and the tooltip keys are those same
-                                     1.12 keys through the panel's own `_TEXT`-stripping lookup
-                                     (UIOptionsFrame.lua l.265), which is why Sticky Targeting's
-                                     description is GAMEFIELD_DESELECT's. -->
+                                <!-- 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"). -->
                                 <Frame name="$parentControls" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -2914,19 +2057,7 @@
                                                 self.invert = 1
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Block Trades (decision 1764). Seated here because
-                                             this page is where 1.12's Basic Options GENERAL box
-                                             lands, and Sticky Targeting above is the other row we
-                                             ship from it — the reference's own box order runs 45
-                                             (Sticky Targeting) down the left column and 14 (this)
-                                             down the right, so the two belong adjacent when the
-                                             box is flattened to one column. Its tooltip key IS the
-                                             reference's, unlike the row above. -->
-                                        <!-- The three BasicOptionsGeneral switches whose knob this client already had and
-                                             whose box nobody could reach (2180). Labels are the reference's GlobalStrings
-                                             verbatim, ASSIST_ATTACK's sentence case included — the page's own rule is
-                                             "1.12 GlobalStrings where the row exists there", and quietly Title-Casing one
-                                             string is how a transcription starts drifting from what it transcribes. -->
+                                        <!-- Labels verbatim, ASSIST_ATTACK's sentence case too. -->
                                         <Frame name="$parentRowAssistAttack" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowStickyTarget" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -2955,12 +2086,9 @@
                                             <Scripts><OnLoad>OptionsRow_OnLoad(self, "BlockTrades", "Block Trades",
                                                 "OPTION_TOOLTIP_BLOCK_TRADES")</OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Auto Self Cast (1745). The one row on this page that ships at a value the
-                                             reference does not register — "1" against its "0", a named deviation in
-                                             `cvars::REGISTERED` because with it off an unbindable friendly cast falls
-                                             into the targeting-cursor machine, which is unmodeled, leaving no path at
-                                             all. The Defaults button walks it back to OUR shipped value, which is what
-                                             GetCVarDefault answers and the only value that is true here. -->
+                                        <!-- Deviation: ships "1" where 1.12 registers "0"
+                                             (`cvars::REGISTERED`): 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>
@@ -2976,10 +2104,7 @@
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowAutoSelfCast" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowAutoSelfCast" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
-                                            <!-- No tip: 1.12 has no Auto Loot row, so no
-                                                 OPTION_TOOLTIP_* for it either (verified — the
-                                                 5875 GlobalStrings has no AUTO_LOOT key at all,
-                                                 and no 1.12 panel names the CVar). -->
+                                            <!-- No tip: 1.12 has no AUTO_LOOT string. -->
                                             <Scripts><OnLoad>OptionsRow_OnLoad(self, "autoLootDefault", "Auto Loot")</OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowInvertMouse" inherits="OptionsCheckboxRowTemplate">
@@ -2990,16 +2115,7 @@
                                             <Scripts><OnLoad>OptionsRow_OnLoad(self, "mouseInvertPitch", "Invert Mouse",
                                                 "OPTION_TOOLTIP_INVERT_MOUSE")</OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Mouse Sensitivity (decision 1140). Last because 1.12
-                                             puts its four sliders in their own box BELOW the
-                                             checkbox columns (UIOptionsFrameSliders), and it was the
-                                             only one of the four whose knob we had when 1140
-                                             wrote this row. All four ship now — the
-                                             max-follow-distance factor below it (1140), and the
-                                             auto-follow and mouse-look speeds in the camera block
-                                             under the following-style dropdown (2180). Range and step are the reference's
-                                             own (0.5 .. 1.5 by 0.05); the percent readout is the
-                                             era's default and reads a multiplier exactly right. -->
+                                        <!-- The reference's range and step. -->
                                         <Frame name="$parentRowMouseSpeed" inherits="OptionsSliderRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowInvertMouse" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3011,31 +2127,10 @@
                                                 OptionsSliderRow_Setup(self, 0.5, 1.5, 0.05)
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Max Camera Distance (decision 1140), the second of
-                                             1.12's four sliders whose knob we have. The stored
-                                             value is the FACTOR over `cameraDistanceMax`'s 15 yd
-                                             base — the reference's own arrangement, and the reason
-                                             the readout is raw yards here rather than a percent:
-                                             "22" means the wheel stops at 22 yards, which is the
-                                             thing being chosen. The slider rests at 1.0 (15 yd),
-                                             1.12's own registered default — it sat at the top of
-                                             the range (30 yd) from 1140 until 1804. -->
-                                        <!-- Camera Following Style (1493, values re-pinned by
-                                             1502): 1.12's own dropdown
-                                             (UIOptionsFrameCameraDropDown) in its own order —
-                                             Smart, Always, Never — each entry carrying the
-                                             reference's own description key (keyed by POSITION,
-                                             OPTION_TOOLTIP_CAMERA1..3) so the row's plate changes
-                                             with the selection, the way that dropdown's does.
-                                             The VALUES are the ENGINE's, not that dropdown's: the
-                                             reference writes 1/2/3 and 3 is not a style at all —
-                                             its validator accepts it while the terrain-tilt
-                                             consumer indexes 360 bytes off the end of its table.
-                                             0/1/2 is what the client's own tables are indexed by
-                                             (wow-re camera-smooth-style.md §2/§4). Seated at the
-                                             head of the camera block because it decides whether
-                                             the camera follows at all; the distance slider under
-                                             it decides how far. -->
+                                        <!-- 1.12's UIOptionsFrameCameraDropDown, with its
+                                             tooltips. Deviation: values are the engine's 0/1/2;
+                                             1.12 writes 3 for Never, which its terrain-tilt
+                                             consumer reads past its table's end. -->
                                         <Frame name="$parentRowCameraFollowStyle" inherits="OptionsDropdownRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowMouseSpeed" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3051,18 +2146,7 @@
                                                 })
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- ── The four 1.12 camera toggles, and the two speed sliders (2180) ──────
-                                             2149 built all four mechanisms and 2179 rebuilt water collision at the
-                                             bytes; until this block none of them could be turned off from inside the
-                                             game. The stock UIOptionsFrame carries all four checkboxes and benilla
-                                             loads that window HIDDEN, deliberately (2115) — so "the reference has the
-                                             box" and "the player can reach the box" had come apart, and only this
-                                             window can close it.
-
-                                             Order is BasicOptionsCamera's own, its three columns flattened: the
-                                             following-style dropdown above, then 24 -> 26, then Slider2 -> 27 -> 15,
-                                             then Slider3 -> Slider4. Labels and OPTION_TOOLTIP_* keys are the
-                                             reference's GlobalStrings verbatim. -->
+                                        <!-- 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>
@@ -3073,11 +2157,8 @@
                                                     "OPTION_TOOLTIP_FOLLOW_TERRAIN")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Head Bob is FIRST PERSON ONLY, and nothing in the row says so because
-                                             nothing in the reference's row does either: the gate's first conjunct is
-                                             `[cam+0xec] <= 1/6` on the zoom distance (2149 §3). A player who ticks it
-                                             at an over-the-shoulder zoom sees no change, which is the reference's own
-                                             behaviour and not a dead row. -->
+                                        <!-- First person only, as in 1.12: the gate requires
+                                             `[cam+0xec] <= 1/6` on the zoom distance. -->
                                         <Frame name="$parentRowHeadBob" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowFollowTerrain" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3088,18 +2169,9 @@
                                                     "OPTION_TOOLTIP_HEAD_BOB")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Auto-Follow Speed (1502 built the knob; this is its slider). Range and step
-                                             are UIOptionsFrameSliders row 2's own — 90..270 by 10, deg/s — stated here
-                                             rather than read off that table, which is what the two sliders already on
-                                             this page do. Greyed while the following style is Never, the reference's
-                                             own dependency (see OptionsPage_UpdateDependencies).
-
-                                             **One HALF of the reference's write, on purpose.** `UIOptionsFrame_Save`
-                                             also writes `cameraPitchSmoothSpeed` at a quarter of this value; benilla
-                                             does not register that name, because the auto-follow here has ONE rate
-                                             (`FollowRig`, a single `yaw_speed`) and a CVar with no reader is 1134 §4's
-                                             silent pretence. Its Mouse Look Speed neighbour below does carry its
-                                             partner, because that one's twin is real here. -->
+                                        <!-- UIOptionsFrameSliders row 2. Deviation: no partner
+                                             write of cameraPitchSmoothSpeed, which has no reader:
+                                             the follow here has one rate. -->
                                         <Frame name="$parentRowAutoFollowSpeed" inherits="OptionsSliderRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowHeadBob" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3111,10 +2183,9 @@
                                                 OptionsSliderRow_Setup(self, 90, 270, 10, "raw")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Water Collision (2179). ONE CVar with two consumers that may never again be
-                                             separated: the `0xf0000` nibble rides the trace mask to all three of
-                                             `0x50e570`'s queries, and `0x50e629`'s `test esi,0xf0000` admits the pivot
-                                             floor/cap block. Ticking this box moves both halves or neither. -->
+                                        <!-- One CVar, two consumers that move together: 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>
@@ -3135,12 +2206,8 @@
                                                     "OPTION_TOOLTIP_SMART_PIVOT")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Mouse Look Speed (2115 registered the CVar; this is the control it never
-                                             had). UIOptionsFrameSliders row 3, 90..270 by 10. It carries the
-                                             reference's PARTNER write — `cameraPitchMoveSpeed` at half the yaw value
-                                             (UIOptionsFrame.lua l.355-356), which is exactly the 180/90 pair both are
-                                             registered at — so dragging this row keeps the two axes in the ratio the
-                                             reference ships them in instead of moving one and leaving the other. -->
+                                        <!-- UIOptionsFrameSliders row 3, with the partner write
+                                             of cameraPitchMoveSpeed at half (l.355-356). -->
                                         <Frame name="$parentRowMouseLookSpeed" inherits="OptionsSliderRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowSmartPivot" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3166,15 +2233,9 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Audio page. Row seats transcribe the era settings list
-                                     (Blizzard_SettingsList.lua l.43-47 + .xml: scroll box hung
-                                     -15/-20 off the header block with padLeft 25 / padRight 0 and
-                                     verticalPad 10 → first row at (10,-12); spacing 9 → 35 pitch).
-                                     Row ORDER is the era Audio page's grammar (volume block first,
-                                     then the enables) over the 1.12 row set: the three category
-                                     volumes ride as CHILDREN of Master Volume exactly like era's,
-                                     in the 1.12 panel's own slider order (Sound, Music, Ambience —
-                                     SoundOptionsFrame.lua's index order). -->
+                                <!-- 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. -->
                                 <Frame name="$parentAudio" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -3208,8 +2269,7 @@
                                             <Scripts><OnLoad>
                                                 OptionsRow_OnLoad(self, "SoundVolume", "Sound Volume",
                                                     "OPTION_TOOLTIP_SOUND_VOLUME", 1)
-                                                -- era parentInitializer (search pulls Master in
-                                                -- above a matched child, SettingsPanel.lua l.665)
+                                                -- Era parentInitializer (SettingsPanel.lua l.665).
                                                 self.parentRow = "RowMaster"
                                             </OnLoad></Scripts>
                                         </Frame>
@@ -3257,11 +2317,7 @@
                                                 self.soundQuirk = 1
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- 1.12's fourth Sound checkbox, ENABLE_ERROR_SPEECH
-                                             (SoundOptionsFrame.lua l.2) — the race/sex refusal
-                                             lines your character says aloud, decision 1815. Its
-                                             label and tooltip are the reference's own
-                                             GlobalStrings entries. -->
+                                        <!-- 1.12's checkbox 4 (SoundOptionsFrame.lua l.2). -->
                                         <Frame name="$parentRowEnableErrorSpeech" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowEnableAmbience" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3273,14 +2329,9 @@
                                                 self.soundQuirk = 1
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Sound in the background (decision 1847). The one
-                                             Audio row 1.12 has no checkbox for: it mutes on its
-                                             window-activation event unconditionally, so this row
-                                             offers the way out the reference never did, shipped
-                                             OFF at the reference's own behaviour. Era's label and
-                                             era's CVar spelling, the autoLootDefault posture.
-                                             soundQuirk like every box on this page - the mapping
-                                             belongs to the panel, not to the row's provenance. -->
+                                        <!-- 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. -->
                                         <Frame name="$parentRowBackgroundSound" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowEnableErrorSpeech" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3295,23 +2346,9 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Graphics page (0959): the 1.12 OptionsFrameSliders rows
-                                     that have a benilla knob behind them, in the table's own order
-                                     (OptionsFrame.lua l.25-27). UI Scale: uiscale 0.64..1.0 step
-                                     0.01 (UI_SCALE "UI Scale", percent readout — era's own
-                                     FormatPercentageRounded on its uiscale row); 1.12's useUiScale
-                                     gate has no benilla knob (our scale always applies; off ≡ 1.0)
-                                     so the checkbox doesn't ship. Terrain Distance: farclip
-                                     177..777 step 60 = (max-min)/10 (FARCLIP "Terrain Distance",
-                                     raw-yards readout — era's law when a slider has no formatter);
-                                     retired by the director in 0961 and back by their call in
-                                     1513, now that the one number moves the far-clip wall AND how
-                                     much terrain is resident, as it does in the reference.
-                                     Environment Detail is the same table's WorldDetail row
-                                     (0..2 step 1, label ENVIRONMENT_DETAIL) over the clutter-density
-                                     knob. 0992 wore it as a dropdown; 1649 puts it back on the
-                                     SLIDER the reference actually uses, keeping 0992's stop names
-                                     in the readout seat. -->
+                                <!-- 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. -->
                                 <Frame name="$parentGraphics" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -3329,10 +2366,8 @@
                                                 OptionsSliderRow_Setup(self, OptionsFrameSliders[1].minValue,
                                                     OptionsFrameSliders[1].maxValue,
                                                     OptionsFrameSliders[1].valueStep)
-                                                -- era registers its uiscale row CommitFlag.Apply
-                                                -- (Graphics.lua l.684): the one row whose live
-                                                -- write would rescale the very slider mid-drag —
-                                                -- it stages and commits through the Apply button.
+                                                -- Era CommitFlag.Apply (Graphics.lua l.684): a
+                                                -- live write would rescale the slider mid-drag.
                                                 self.deferred = 1
                                             </OnLoad></Scripts>
                                         </Frame>
@@ -3357,42 +2392,24 @@
                                             <Scripts><OnLoad>
                                                 OptionsRow_OnLoad(self, "WorldDetail", "Environment Detail",
                                                     "OPTION_TOOLTIP_ENVIRONMENT_DETAIL")
-                                                -- The stop names are the era preset ladder's (its
-                                                -- quality dropdowns say Low/Medium/High); 1.12's
-                                                -- slider had no stop labels to quote.
+                                                -- Stop names from the era quality ladder.
                                                 OptionsSliderRow_Setup(self, OptionsFrameSliders[3].minValue,
                                                     OptionsFrameSliders[3].maxValue,
                                                     OptionsFrameSliders[3].valueStep, nil,
                                                     { "Low", "Medium", "High" })
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Brightness (2182) — the reference's slider 6, and the
-                                             one row on this page whose store is an engine PAIR
-                                             rather than the CVar directly. That is 1.12's own
-                                             arrangement: its slider table gives this row
-                                             `func = "Gamma"`, so `OptionsFrame_Load`/`_Save` reach
-                                             `GetGamma`/`SetGamma` and the CVar is written by the
-                                             engine, not the panel. The reason it matters here is
-                                             the UNIT — `GetGamma()` is `1 - gamma`, an offset
-                                             centred on 0, and a row that wrote the slider value
-                                             into `gamma` directly would invert the control and
-                                             put a fully white ramp at the top of its travel. -->
+                                        <!-- 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. -->
                                         <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>
-                                                -- The default is the reference's own computation
-                                                -- rather than a second copy of the number:
-                                                -- OptionsFrame_SetDefaults displays this row as
-                                                -- `1 - GetCVarDefault("gamma")` (OptionsFrame.lua
-                                                -- l.441-445), so the CVar table stays the single
-                                                -- source and Restore Defaults here lands exactly
-                                                -- where the reference's would. The `or 1` is for a
-                                                -- VM whose host registered nothing (a bare kit),
-                                                -- where the reference would have had a record to
-                                                -- read because its own lookup creates one.
+                                                -- OptionsFrame_SetDefaults' default (l.441-445);
+                                                -- `or 1` covers a VM with no CVars.
                                                 local gd = tonumber(GetCVarDefault("gamma")) or 1
                                                 OptionsNumFuncRow_OnLoad(self, GetGamma, SetGamma,
                                                     tostring(1 - gd), "Brightness",
@@ -3402,17 +2419,9 @@
                                                     OptionsFrameSliders[6].valueStep, "travel")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Weather Intensity (2181) — the reference's slider 9,
-                                             the last of its nine and the nearest of 2177 §10's
-                                             named-not-done: benilla has driven precipitation off
-                                             `weatherDensity` since 0310 and only the switch was
-                                             missing. It rides the CVar directly like every other
-                                             row here; the reference's own row would reach it
-                                             through `SetCVar` too (`func = "weatherDensity"` is a
-                                             CVar name, not one of the four engine bindings — its
-                                             `Setfarclip`-shaped `getglobal("Set".."weatherDensity")`
-                                             finds nothing, so `OptionsFrame_Save` falls through).
-                                             -->
+                                        <!-- The reference's slider 9, on the CVar directly, as
+                                             1.12's lands: with no SetweatherDensity global,
+                                             OptionsFrame_Save falls through to SetCVar. -->
                                         <Frame name="$parentRowWeatherDensity" inherits="OptionsSliderRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowBrightness" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3421,16 +2430,9 @@
                                             <Scripts><OnLoad>
                                                 OptionsRow_OnLoad(self, "weatherDensity", "Weather Intensity",
                                                     "OPTION_TOOLTIP_WEATHER_DETAIL")
-                                                -- The stop names are OURS, and they name the
-                                                -- reference's own quality table rather than a
-                                                -- borrowed preset ladder: `0x67b870` maps 0/1/2/3
-                                                -- onto the spawn-rate gains {0.1, 0.33, 0.66, 1.0}
-                                                -- in `[0x8680ec]`, so the top stop really is the
-                                                -- full rate and the bottom is a tenth of it. 1.12
-                                                -- labelled no stop on this slider -- it labelled
-                                                -- the two ENDS -- but every slider row in this kit
-                                                -- carries a readout, and "2" is the one thing that
-                                                -- seat could say that means nothing to a player.
+                                                -- 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]`.
                                                 OptionsSliderRow_Setup(self, OptionsFrameSliders[9].minValue,
                                                     OptionsFrameSliders[9].maxValue,
                                                     OptionsFrameSliders[9].valueStep, nil,
@@ -3443,32 +2445,11 @@
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowWeatherDensity" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                -- Display Mode (1650): MODERN CLASSIC's row, not
-                                                -- 1.12's, because 1627 already gave us modern
-                                                -- Classic's two states and a checkbox could only
-                                                -- name one of them.
-                                                --
-                                                -- Blizzard_SettingsDefinitions_Shared/Graphics.lua
-                                                -- (live, classic AND classic_era, all identical):
-                                                -- a BOOLEAN proxy rendered as a dropdown, with
-                                                -- exactly two entries -- container:Add(true,
-                                                -- VIDEO_OPTIONS_WINDOWED_FULLSCREEN) and
-                                                -- container:Add(false, VIDEO_OPTIONS_WINDOWED).
-                                                -- There is no Fullscreen entry anywhere in it;
-                                                -- 8.0.1 removed the exclusive mode those clients
-                                                -- had, which is the same reason 1627 ships none.
-                                                --
-                                                -- It rides gxWindow, OUR persisted CVar, not the
-                                                -- gxMaximize the modern client uses -- that client
-                                                -- deleted gxWindow entirely and had to move; we
-                                                -- did not, and repointing would orphan every
-                                                -- config.toml already holding the row for nothing.
-                                                -- Polarity is gxWindow's own: "0" is not-windowed,
-                                                -- which 1627 redefined as the borderless window.
-                                                --
-                                                -- Not deferred, for the same reason as Vertical
-                                                -- Sync below: the reference row carries
-                                                -- gxRestart = 1 and ours applies on the click.
+                                                -- 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.
                                                 OptionsRow_OnLoad(self, "gxWindow", "Display Mode",
                                                     "BENILLA_TOOLTIP_DISPLAY_MODE")
                                                 OptionsDropdownRow_Setup(self, {
@@ -3483,12 +2464,9 @@
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowDisplayMode" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                -- Vertical Sync: 1.12's own Video Options checkbox
-                                                -- 5 (gxVSync), over the window's present mode.
-                                                -- The reference row carries gxRestart = 1; ours
-                                                -- does not and must not be marked deferred --
-                                                -- wgpu swaps the presentation interval live, so
-                                                -- the box takes effect as you click it.
+                                                -- 1.12's Video Options checkbox 5. Not deferred
+                                                -- despite its gxRestart = 1: the present mode
+                                                -- changes live.
                                                 OptionsRow_OnLoad(self, "gxVSync", "Vertical Sync",
                                                     "OPTION_TOOLTIP_VERTICAL_SYNC")
                                             </OnLoad></Scripts>
@@ -3506,33 +2484,11 @@
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowVerticalSync" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                -- Render Scale (decision 1639) -- benilla's own
-                                                -- row, no 1.12 counterpart: the reference renders
-                                                -- straight to the backbuffer and has no second
-                                                -- image to size. It CLOSES the page, and it is
-                                                -- the only antialiasing control on it: the
-                                                -- reference's own Multisampling row was pulled
-                                                -- 2026-08-27 (decision 1648, the director's call).
-                                                -- gxMultisample survives as a CVar and $WOW_MSAA
-                                                -- -- what went is the row, because multisampling
-                                                -- cannot touch the alpha-tested cutouts that carry
-                                                -- most of this game's visible aliasing, and above
-                                                -- 100% this row can.
-                                                --
-                                                -- 50-200%, narrower than the CVar's own clamp
-                                                -- (RENDER_SCALE_RANGE, 0.25-4.0). That clamp stops
-                                                -- an absurd value and leaves room for the
-                                                -- supersampling instrument; this is what a player
-                                                -- should be offered, and it is where every engine
-                                                -- puts the same slider.
-                                                --
-                                                -- DEFERRED, and for the reason the flag exists.
-                                                -- Committing live would rebuild the world's render
-                                                -- target on every drag tick -- tens of megabytes,
-                                                -- thirty times across one sweep of the handle.
-                                                -- Staging to Apply makes that exactly one rebuild,
-                                                -- which is the same answer uiScale's row already
-                                                -- reaches for a different reason.
+                                                -- 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.
                                                 OptionsRow_OnLoad(self, "renderScale", "Render Scale",
                                                     "BENILLA_TOOLTIP_RENDER_SCALE")
                                                 OptionsSliderRow_Setup(self, 0.5, 2.0, 0.05)
@@ -3540,16 +2496,9 @@
                                             </OnLoad></Scripts>
                                         </Frame>
                                     </Frames>
-                                    <!-- Re-apply the slider bounds from the REFERENCE's OptionsFrameSliders every time the page is shown.
-                                         The rows read the table at OnLoad, which is long before any addon runs; an addon that
-                                         writes a bound (pfUI's hdgraphic raises Environment Detail's maxValue to 15) would
-                                         otherwise never move the slider it just rewrote. The reference does the same loop in
-                                         OptionsFrame_Load; ours lives here rather than under that name because our page
-                                         implements almost none of the rest of that function's contract and publishing a
-                                         reference name over a partial body is how a gap hides.
-                                    
-                                         fmt and stops are read back off the row rather than the table: they are OUR readout
-                                         grammar (0992/1649's stop names), set at OnLoad, and no addon addresses them. -->
+                                    <!-- 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. -->
                                     <Scripts>
                                         <OnShow>
                                             for i, name in BENILLA_GRAPHICS_SLIDER_ROWS do
@@ -3889,18 +2838,8 @@
                                         <OnUpdate>AdvGfx_OnUpdate(this, arg1)</OnUpdate>
                                     </Scripts>
                                 </Frame>
-                                <!-- The COMBAT page (decision 1134) — the first page whose rows
-                                     write saved-variable GLOBALS rather than CVars, and the first
-                                     thing that can change any of the ~20 stock globals 1128
-                                     ported. It is 1.12's AdvancedOptionsCombatText box, whole: the
-                                     master, the scroll-mode dropdown, and the twelve sub-toggles,
-                                     in the reference box's own anchor-chain order, with its
-                                     GlobalStrings labels and OPTION_TOOLTIP_* keys verbatim and
-                                     each sub-toggle at the reference's default (the assignment in
-                                     CombatText.xml, which is also where the Defaults button reads
-                                     from). Every row runs CombatText_UpdateDisplayedMessages as
-                                     its applyFunc — the reference's own post-Save call, moved to
-                                     the click because this window writes live (0961). -->
+                                <!-- The Combat page: 1.12's AdvancedOptionsCombatText box as uvar
+                                     rows, each applying CombatText_UpdateOrLoad on the click. -->
                                 <Frame name="$parentCombat" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -3915,12 +2854,10 @@
                                             <Scripts><OnLoad>
                                                 OptionsGlobalRow_OnLoad(self, "SHOW_COMBAT_TEXT",
                                                     "Enable Floating Combat Text", "OPTION_TOOLTIP_SHOW_COMBAT_TEXT")
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The scroll mode. 1.12's own dropdown, values and all
-                                             (UIOptionsFrameCombatTextDropDown_Initialize: "1" up,
-                                             "2" down, "3" arc), worn as an era dropdown row. -->
+                                        <!-- 1.12's scroll-mode values: 1 up, 2 down, 3 arc. -->
                                         <Frame name="$parentRowFloatMode" inherits="OptionsDropdownRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowCombatText" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -3935,7 +2872,7 @@
                                                     { text = "Arc", value = "3" },
                                                 })
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowLowHealthMana" inherits="OptionsCheckboxRowTemplate">
@@ -3948,7 +2885,7 @@
                                                     "Show Low Mana and Health",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_LOW_HEALTH_MANA", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowAuras" inherits="OptionsCheckboxRowTemplate">
@@ -3960,7 +2897,7 @@
                                                 OptionsGlobalRow_OnLoad(self, "COMBAT_TEXT_SHOW_AURAS",
                                                     "Show Auras", "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_AURAS", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowAuraFade" inherits="OptionsCheckboxRowTemplate">
@@ -3972,7 +2909,7 @@
                                                 OptionsGlobalRow_OnLoad(self, "COMBAT_TEXT_SHOW_AURA_FADE",
                                                     "Show Fading Auras", "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_AURA_FADE", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowCombatState" inherits="OptionsCheckboxRowTemplate">
@@ -3985,7 +2922,7 @@
                                                     "Show Combat State",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_COMBAT_STATE", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowDodgeParryMiss" inherits="OptionsCheckboxRowTemplate">
@@ -3998,7 +2935,7 @@
                                                     "Show Dodge/Parries/Misses",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_DODGE_PARRY_MISS", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowResistances" inherits="OptionsCheckboxRowTemplate">
@@ -4011,7 +2948,7 @@
                                                     "Show Damage Reduction",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_RESISTANCES", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowReputation" inherits="OptionsCheckboxRowTemplate">
@@ -4024,7 +2961,7 @@
                                                     "Show Reputation",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_REPUTATION", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowReactives" inherits="OptionsCheckboxRowTemplate">
@@ -4037,7 +2974,7 @@
                                                     "Show Reactive Spells and Abilities",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_REACTIVES", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowFriendlyNames" inherits="OptionsCheckboxRowTemplate">
@@ -4050,12 +2987,10 @@
                                                     "Show Friendly Healer Names",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_FRIENDLY_NAMES", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Combo Points carries the reference's SECOND gate: greyed
-                                             for anyone who is not a rogue or a druid — see
-                                             OptionsPage_UpdateDependencies. -->
+                                        <!-- Greyed for all but rogues and druids, as in 1.12. -->
                                         <Frame name="$parentRowComboPoints" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowFriendlyNames" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4066,7 +3001,7 @@
                                                     "Show Combo Points",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_COMBO_POINTS", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowEnergyGains" inherits="OptionsCheckboxRowTemplate">
@@ -4079,7 +3014,7 @@
                                                     "Show Energy Gains",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_MANA", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowHonorGained" inherits="OptionsCheckboxRowTemplate">
@@ -4092,22 +3027,12 @@
                                                     "Show Honor Gained",
                                                     "OPTION_TOOLTIP_COMBAT_TEXT_SHOW_HONOR_GAINED", 1)
                                                 self.parentRow = "RowCombatText"
-                                                self.applyFunc = "CombatText_UpdateOrLoad" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "CombatText_UpdateOrLoad"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- ── The damage NUMBERS (2180): a second master and its two children ──────
-                                             Same box as the floating-combat-text family above and a different
-                                             hierarchy: `CombatDamage` is the master of what floats over a UNIT,
-                                             `SHOW_COMBAT_TEXT` of what scrolls beside the player, and the reference
-                                             keeps their dependency blocks apart (UIOptionsFrame.lua l.709-714 against
-                                             l.727-741). All three are CVar rows with host readers, so the write is the
-                                             apply and none carries the family's `applyFunc`.
-
-                                             `CombatDamage`'s help text says "damage numbers" and it does more than
-                                             that: its only two readers are the localized-WORD emitter `0x607140` and
-                                             the "%d" NUMBER emitter `0x6128b0`, and both branch targets are epilogues
-                                             — at "0" nothing floats over any unit from any source, misses and
-                                             immunities included. -->
+                                        <!-- CombatDamage masters what floats over a unit, apart
+                                             from SHOW_COMBAT_TEXT (l.709-714); 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>
@@ -4118,12 +3043,8 @@
                                                     "OPTION_TOOLTIP_SHOW_DAMAGE")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Periodic Damage reaches further than its label: `CombatLogPeriodicSpells`
-                                             off takes the whole `SMSG_PERIODICAURALOG` body — every
-                                             CHAT_MSG_SPELL_PERIODIC_* line AND the DoT/HoT tick number AND the
-                                             periodic miss word (`0x626dee` jumps to a bare epilogue). The row is the
-                                             reference's wording over the reference's behaviour; neither is ours to
-                                             improve. -->
+                                        <!-- Off drops the whole SMSG_PERIODICAURALOG body
+                                             (`0x626dee`): lines, tick numbers and misses. -->
                                         <Frame name="$parentRowPeriodicDamage" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowShowDamage" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4135,12 +3056,7 @@
                                                 self.parentRow = "RowShowDamage"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Pet Damage carries the reference's PARTNER write: its box drives BOTH
-                                             `PetMeleeDamage` and `PetSpellDamage` (UIOptionsFrame_Save l.334-336), the
-                                             second of which appears in no option table at all — which is why 2077's
-                                             census, reading that table, could see two of the three. Without the
-                                             partner the box would say "pet damage off" while pet SPELL damage kept
-                                             floating, and nothing would say so. -->
+                                        <!-- Also writes PetSpellDamage (l.334-336). -->
                                         <Frame name="$parentRowPetDamage" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowPeriodicDamage" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4155,45 +3071,11 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The ACTION BARS page (1136's lock row; the five switches above
-                                     it are 1500). 1.12's Advanced Options group, whole.
-
-                                     The four bar rows are API (`func`) rows — the third store, the
-                                     one Show Cloak / Show Helm opened in 1472 — because there is
-                                     nothing local to save: the preference is four bits of this
-                                     CHARACTER's server-side PLAYER_FIELD_BYTES byte 2, written with
-                                     CMSG_SET_ACTIONBAR_TOGGLES. The getter reads the live Lua
-                                     global (the client never re-reads the field and nothing fires
-                                     on a change to it, so the global IS the state between logins);
-                                     the setter writes the global, re-derives the bars, and re-sends
-                                     the whole byte. Default OFF for all four — a fresh character's
-                                     byte is 0.
-
-                                     Always Show ActionBars is a SAVED-VARIABLE row instead, and the
-                                     split is a verified consequence of the engine binding rather
-                                     than an authoring choice: `SetActionBarToggles` takes exactly
-                                     four arguments and silently DROPS the fifth that the reference
-                                     passes it (`cmp esi,4` at 0x4e770e), so that switch has no
-                                     server store to write and the reference RegisterForSave's it
-                                     locally too (UIOptionsFrame.lua l.106-107). Decision 1500 and
-                                     wow-re action-bar-toggles.md carry the whole byte-level finding.
-
-                                     The getters and setters are written here as closures rather
-                                     than captured from the bar file by name, deliberately: a row's
-                                     OnLoad captures a function VALUE, so a named import would make
-                                     this page depend on load ORDER — and a harness (or a manifest
-                                     reordering) that loaded the window without the bars would give
-                                     every row a nil store instead of an unticked box. A closure
-                                     resolves its callee when the player clicks.
-
-                                     Labels and OPTION_TOOLTIP_* keys are 1.12's GlobalStrings
-                                     verbatim (SHOW_MULTIBAR1..4_TEXT l.3444-3447,
-                                     ALWAYS_SHOW_MULTIBARS_TEXT l.51) — including the leading
-                                     "Show ", which is part of the reference's own display text.
-
-                                     The lock itself had to be BUILT before it could have a row:
-                                     ActionBar.xml and PetActionBar.xml guard their drag ends on it,
-                                     the way the reference does. -->
+                                <!-- 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. -->
                                 <Frame name="$parentActionBars" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -4260,15 +3142,8 @@
                                                     "0", "Show Right ActionBar", "OPTION_TOOLTIP_SHOW_MULTIBAR3")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Bar 4 is a CHILD row: MultiBarLeft only shows when bar 3
-                                             is also on (MultiBars.xml's conjunction — its column
-                                             hangs off MultiBarRight's edge), so the switch is
-                                             meaningless on its own. `child` carries the era's
-                                             indent-and-small-font subordination; the GREYING is
-                                             OptionsPage_UpdateDependencies' ActionBars arm, which
-                                             is the reference's own rule for this exact pair
-                                             (UIOptionsFrame.lua l.722-726 disables CheckButton36
-                                             while 35 is unchecked). -->
+                                        <!-- A child of bar 3: MultiBarLeft shows only beside
+                                             MultiBarRight (l.722-726). -->
                                         <Frame name="$parentRowMultiBar4" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowMultiBar3" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4297,14 +3172,8 @@
                                             <Scripts><OnLoad>
                                                 OptionsGlobalRow_OnLoad(self, "ALWAYS_SHOW_MULTIBARS",
                                                     "Always Show ActionBars", "OPTION_TOOLTIP_ALWAYS_SHOW_MULTIBARS")
-                                                -- A CLICK runs MultiActionBar_UpdateGridVisibility, the
-                                                -- reference's own click arm (UIOptionsFrame.xml:683).
-                                                -- The LOAD arm — which only ever SHOWS, because every hide
-                                                -- is a counted decrement on each well (ActionButton_HideGrid)
-                                                -- and a load-time hide against wells nobody opened would push
-                                                -- the count negative — is the stock file's
-                                                -- VARIABLES_LOADED arm now (UIOptionsFrame.lua l.218-220),
-                                                -- which is why this row carries no `loadFunc` (2115).
+                                                -- The click arm (UIOptionsFrame.xml:683); the load
+                                                -- arm is the stock VARIABLES_LOADED one.
                                                 self.applyFunc = "MultiActionBar_UpdateGridVisibility"
                                             </OnLoad></Scripts>
                                         </Frame>
@@ -4320,47 +3189,17 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The INTERFACE page (decision 1136; the Buff Durations row is
-                                     1139, the two equipment-display rows 1472) — the second
-                                     store's second page, and the one 1134 §3 named as ready: stock
-                                     globals already defined AND consumed, needing only a row. Rows
-                                     in the reference's own on-screen order — Basic Options' anchor
-                                     chain runs CheckButton42 → 39 → 62 → 66 in Display, then 29 in
-                                     Help, and we hold all of those but 62
-                                     (HIDE_OUTDOOR_WORLD_STATE: there is no zone-objective tracker
-                                     to hide); Show Cloak → Show Helm (31 → 20) are that box's
-                                     middle column, seated after Status Text because the two rows
-                                     above them there — the player/NPC name toggles — live on our
-                                     Nameplates page. Labels and OPTION_TOOLTIP_* keys are its
-                                     GlobalStrings verbatim.
-
-                                     Only Buff Durations carries an `applyFunc`, and the split is
-                                     the honest one rather than an omission: the other three are
-                                     read at the moment their consumer acts — the tooltip as it is
-                                     built, the quest panel as it shows, the auto-watch as progress
-                                     arrives — so the write IS the apply. A setting is owed an
-                                     applyFunc exactly when something DERIVED from it is stated
-                                     once and kept: the buff bar's row pitch, the combat-text
-                                     family's event registrations. -->
+                                <!-- 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. -->
                                 <Frame name="$parentInterface" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
                                         <Anchor point="BOTTOMRIGHT"/>
                                     </Anchors>
                                     <Frames>
-                                        <!-- Status Bar Text (decision 1140). First because it is
-                                             first in the reference's file: its own Display column
-                                             runs CheckButton12 -> **2** -> 21, and 2 is declared
-                                             ahead of the 42 chain below it. The one row in this
-                                             window carrying a `cvarEvent`: TextStatusBar.xml has
-                                             had a CVAR_UPDATE watcher since 1082 and nothing to
-                                             wake it. -->
-                                        <!-- Enhanced Tooltips (2180), and it takes the head seat because it takes the
-                                             reference's: the Display box's first column is 12 -> 2 -> 21, and 12 is the
-                                             first CheckButton the file declares. Its consumers are LUA — the action and
-                                             pet bars fork their plate corner on `GetCVar("UberTooltips")` — which is why
-                                             `apply_to_knobs` has nothing to do for it and why the row had none of the
-                                             usual "no reader" reason to be absent; it was simply never seated. -->
+                                        <!-- CheckButtons 12 and 2 head the Display box; the
+                                             cvarEvent wakes TextStatusBar.xml's CVAR_UPDATE. -->
                                         <Frame name="$parentRowEnhancedTooltips" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT"><Offset><AbsDimension x="10" y="-12"/></Offset></Anchor>
@@ -4380,19 +3219,9 @@
                                                 self.cvarEvent = "STATUS_BAR_TEXT"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The target-of-target pair (decision 1576): the switch
-                                             and, indented under it, when the frame is allowed to
-                                             stand. Both are `uvar` rows — 1.12 keeps these two as
-                                             saved globals, not CVars (UnitFrames.xml declares and
-                                             RegisterForSave's them) — and both carry the same
-                                             applyFunc, because the saved chunk lands after the XML
-                                             that read it: without the re-run, a saved "1" would
-                                             leave the frame hidden until the next target change.
-                                             The mode row is a CHILD (indent + small font + greyed
-                                             with the switch off), which is the reference's own
-                                             relationship: its dropdown hangs off CheckButton50's
-                                             BOTTOMLEFT and OptionsFrame_DisableDropDown greys it
-                                             from the same test (UIOptionsFrame.lua l.694-700). -->
+                                        <!-- 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). -->
                                         <Frame name="$parentRowTargetOfTarget" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowStatusText" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4401,17 +3230,11 @@
                                             <Scripts><OnLoad>
                                                 OptionsGlobalRow_OnLoad(self, "SHOW_TARGET_OF_TARGET",
                                                     "Show Target of Target", "OPTION_TOOLTIP_SHOW_TARGET_OF_TARGET")
-                                                self.applyFunc = "TargetofTarget_Update" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "TargetofTarget_Update"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The label is ours: the reference declares a Label
-                                             FontString for this dropdown and never sets its text,
-                                             so in 1.12 the picker sits under the checkbox with no
-                                             name at all. An indented row in this window has to say
-                                             what it picks, and the row above supplies the subject.
-                                             The five values are the reference's own strings, and
-                                             its own order (its OPTION_TOOLTIP_TARGETOFTARGET1..5
-                                             describe them in exactly this sequence). -->
+                                        <!-- Deviation: the label is ours; 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>
@@ -4427,17 +3250,11 @@
                                                     { text = "Party or Raid", value = "4", tip = "OPTION_TOOLTIP_TARGETOFTARGET4" },
                                                     { text = "Always", value = "5", tip = "OPTION_TOOLTIP_TARGETOFTARGET5" },
                                                 })
-                                                self.applyFunc = "TargetofTarget_Update" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "TargetofTarget_Update"
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The two equipment-display toggles (decision 1472,
-                                             B123). Neither has a store: the preference is a bit of
-                                             this character's own server-side PLAYER_FLAGS, so the
-                                             row reads the engine getter and writes the engine
-                                             setter — 1.12's own `func`/`setFunc` pair for exactly
-                                             these two rows (UIOptionsFrame.lua l.18-19), and the
-                                             reason there is no CVar to register. Default "1" for
-                                             both, the reference's own hand-written arm. -->
+                                        <!-- Bits of the character's PLAYER_FLAGS: API rows, as
+                                             1.12's `func` pair (UIOptionsFrame.lua l.18-19). -->
                                         <Frame name="$parentRowShowCloak" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowTargetOfTargetMode" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4468,12 +3285,7 @@
                                                     "Instant Quest Text", "OPTION_TOOLTIP_SHOW_QUEST_FADING")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The reference's own next link in that chain
-                                             (CheckButton39, anchored under 42), and the one row on
-                                             this page that DOES carry an applyFunc: the timer text
-                                             is re-decided by the bar's per-frame poll, but the row
-                                             PITCH is stated once and has to be re-stated when the
-                                             switch moves (decision 1139). -->
+                                        <!-- Its applyFunc re-states the buff bar's row pitch. -->
                                         <Frame name="$parentRowBuffDurations" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowInstantQuestText" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4482,7 +3294,7 @@
                                             <Scripts><OnLoad>
                                                 OptionsGlobalRow_OnLoad(self, "SHOW_BUFF_DURATIONS",
                                                     "Buff Durations", "OPTION_TOOLTIP_SHOW_BUFF_DURATION")
-                                                self.applyFunc = "BuffButtons_UpdatePositions" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "BuffButtons_UpdatePositions"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowAutoQuestWatch" inherits="OptionsCheckboxRowTemplate">
@@ -4495,19 +3307,8 @@
                                                     "Automatic Quest Tracking", "OPTION_TOOLTIP_AUTO_QUEST_WATCH")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Column C's last link (decision 2077): 1.12 anchors
-                                             CheckButton5 TOP to CheckButton66's BOTTOM, so
-                                             Profanity Filter closes the 42 -> 39 -> 66 chain the
-                                             three rows above are. It reads as a chat setting and
-                                             the reference files it under Display; the reference's
-                                             seat wins, as everywhere else on this page.
-
-                                             What it actually does is wider than its neighbours
-                                             suggest: `profanityFilter` gates INSIDE the shared
-                                             masker (`0x4a1a66`), so one tick covers all thirteen
-                                             of its call sites. benilla wires the largest — the
-                                             fourteen social chat types — and `crate::text_filter`
-                                             names the twelve still to come. -->
+                                        <!-- CheckButton5, closing the chain under 66. 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>
@@ -4516,39 +3317,23 @@
                                             <Scripts><OnLoad>OptionsRow_OnLoad(self, "profanityFilter", "Profanity Filter",
                                                 "OPTION_TOOLTIP_PROFANITY_FILTER")</OnLoad></Scripts>
                                         </Frame>
-                                        <!-- The HELP box opens here (decision 2077). 1.12 seats
-                                             CheckButton28 at its TOPLEFT and hangs 44 (Show
-                                             Loading Screen Tips) under it, with 29 (this page's
-                                             Show Detailed Tooltips) off to the right of the Reset
-                                             Tutorials button — so 28 -> 44 -> 29 is the box's own
-                                             reading order flattened into our column, which is the
-                                             order below.
-                                             The Reset Tutorials BUTTON itself is not here: it is
-                                             not a checkbox, and `ResetTutorials()` is exactly what
-                                             ticking this row already does. -->
+                                        <!-- The Help box, 28 -> 44 -> 29. Reset Tutorials does
+                                             not ship: 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>
-                                            <!-- A `func` row, like Show Cloak / Show Helm: there is
-                                                 no store, the bank IS the state. Its default is the
-                                                 reference's own hand-written one
-                                                 (UIOptionsFrame_SetDefaults l.645,
-                                                 `OptionsFrame_EnableCheckBox(checkButton, 1, 1)`). -->
+                                            <!-- An API row over the tutorial bank, default "1"
+                                                 (UIOptionsFrame_SetDefaults l.645). -->
                                             <Scripts><OnLoad>
                                                 OptionsFuncRow_OnLoad(self, TutorialsEnabled,
                                                     BenillaOptionsFrame_SetTutorialsEnabled, "1",
                                                     "Show Tutorials", "OPTION_TOOLTIP_SHOW_TUTORIALS")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- CheckButton44, anchored under 28 in the reference's own
-                                             Help box. Its LABEL is 1.12's own and it is not the
-                                             name the tooltip uses: `SHOW_TIPOFTHEDAY_TEXT` reads
-                                             "Show Loading Screen Tips", while the description
-                                             under `OPTION_TOOLTIP_SHOW_TIPOFTHEDAY` still calls it
-                                             the tip of the day. Both are the reference's strings,
-                                             so both stand. -->
+                                        <!-- The label and its tooltip name the tips
+                                             differently; both are 1.12's strings. -->
                                         <Frame name="$parentRowTipOfTheDay" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowShowTutorials" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4570,29 +3355,9 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The SOCIAL page (decision 1139) — the last category in this
-                                     window that opened onto nothing. Both rows are CVar rows, not
-                                     globals: `ChatBubbles`/`ChatBubblesParty` are 1.12's own
-                                     registrar CVars, and chat_bubble.rs held them as a pair of
-                                     `const bool` from 0598 — a gate transcribed faithfully with no
-                                     way to reach it, which is the same shape as the action-bar lock
-                                     and fixed the same way (the knob first, then the row).
-
-                                     1.12's own order, with one gap named: its Advanced Options chat
-                                     chain runs CheckButton37 (Chat Bubbles) → 46 (Loot Spam) → 38
-                                     (Party Chat Bubbles), and 46 is not ours to ship — no
-                                     `showLootSpam` knob exists. So these two are adjacent here and
-                                     in the reference's relative order. Neither is a dependency child:
-                                     the client gates party lines on their own CVar, so party bubbles
-                                     survive turning say/yell bubbles off. -->
-                                <!-- The Chat page (decision 1589 — B246, "no chat section in
-                                     options"). 1.12's Advanced Options CHAT_LABEL box, in its own
-                                     anchor-chain order; which of its nine rows we ship and why the
-                                     other five are absent is the OPTIONS_PAGE_ROWS entry's note.
-                                     The window's *look* — background tint, opacity, font size —
-                                     is deliberately NOT here: the reference puts it on the chat
-                                     tab's right-click menu (ChatFrame.xml), and inventing a second
-                                     home for it would be a divergence, not a convenience. -->
+                                <!-- 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. -->
                                 <Frame name="$parentChat" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -4605,11 +3370,7 @@
                                                 <Anchor point="TOPRIGHT"><Offset><AbsDimension x="-20" y="-12"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                <!-- Registered "0" — the one row on this page that
-                                                     ships its feature OFF, and byte-read rather
-                                                     than chosen (cvars.rs cites the site). No
-                                                     applyFunc: the guild sign-on handler reads the
-                                                     knob as each event lands. -->
+                                                <!-- 1.12 registers it "0" (cvars.rs cites it). -->
                                                 OptionsRow_OnLoad(self, "guildMemberNotify",
                                                     "Guild Member Alert",
                                                     "OPTION_TOOLTIP_GUILDMEMBER_ALERT")
@@ -4621,17 +3382,12 @@
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowGuildMemberAlert" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                <!-- A uvar, like the reference's (CheckButton18).
-                                                     Its applyFunc is the whole feature: the two
-                                                     fade constants live in ChatFrame.xml and
-                                                     SetChatMouseOverDelay is what moves them. The
-                                                     row needs one because nothing re-reads the
-                                                     global per frame — the fade reads the
-                                                     constants, and only this writes them. -->
+                                                <!-- A uvar, as 1.12's CheckButton18; its applyFunc
+                                                     moves ChatFrame.xml's fade constants. -->
                                                 OptionsGlobalRow_OnLoad(self, "REMOVE_CHAT_DELAY",
                                                     "Remove Chat Hover Delay",
                                                     "OPTION_TOOLTIP_REMOVE_CHAT_DELAY")
-                                                self.applyFunc = "ChatFrame_ApplyMouseOverDelay" -- by NAME, resolved when applied: this file loads before its definer now (1938)
+                                                self.applyFunc = "ChatFrame_ApplyMouseOverDelay"
                                             </OnLoad></Scripts>
                                         </Frame>
                                         <Frame name="$parentRowChatBubbles" inherits="OptionsCheckboxRowTemplate">
@@ -4650,13 +3406,7 @@
                                                 <Anchor point="TOPRIGHT" relativeTo="$parentRowChatBubbles" relativePoint="BOTTOMRIGHT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
                                             </Anchors>
                                             <Scripts><OnLoad>
-                                                <!-- "Detailed Loot Information" is the label; the
-                                                     CVar is `showLootSpam` and it is about GROUP
-                                                     LOOT ROLLS, not about loot messages generally
-                                                     (its own tooltip: "Uncheck this to hide
-                                                     individual loot roll messages and only show
-                                                     the winner"). No applyFunc: the loot-roll
-                                                     lines read the CVar as each one is composed. -->
+                                                <!-- Group loot-roll lines only. -->
                                                 OptionsRow_OnLoad(self, "showLootSpam",
                                                     "Detailed Loot Information",
                                                     "OPTION_TOOLTIP_SHOW_LOOT_SPAM")
@@ -4672,23 +3422,10 @@
                                                     "Show Party Chat Bubbles", "OPTION_TOOLTIP_PARTY_CHAT_BUBBLES")
                                             </OnLoad></Scripts>
                                         </Frame>
-                                        <!-- CheckButton 68, the last link in the reference's chat
-                                             chain, and the row this page's note has been promising
-                                             since 1589 ("the row lands with the filter"). It lands
-                                             with decision 2077.
-
-                                             **Value-INVERTED**, like Sticky Targeting: the label
-                                             says *Disable* Spam Filter, so the box is checked when
-                                             `spamFilter` reads "0". That is the reference's own
-                                             pair of arms — `UIOptionsFrame.lua` l.253 checks it on
-                                             `GetCVar == "0"` and l.337 flips the value before
-                                             writing.
-
-                                             The filter behind it drops a line matching any of
-                                             `SpamMessages.dbc`'s 28 gold-seller patterns, silently
-                                             and with nothing in its place — every chat type except
-                                             CHAT_MSG_FILTERED, never for a GM-tagged line or a GM
-                                             viewer. See `crate::text_filter`. -->
+                                        <!-- 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
+                                             CHAT_MSG_FILTERED (`0x49aad2`). -->
                                         <Frame name="$parentRowSpamFilter" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowPartyChatBubbles" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4702,28 +3439,10 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The Nameplates page (0992 — the page 0952 promised when the
-                                     category row joined). Two groups, plates first: the V-key
-                                     HEALTH-BAR plates (vplates.rs VPlateMode — the engine bitmask
-                                     [0xc4da34] bit 0 / bit 3), then the three 1.12 UnitName*
-                                     checkboxes over the overhead-name gates (nameplates.rs
-                                     NameConfig), rows in the 1.12 Interface Options' own index
-                                     order (21/22/30/67 — 22, Player Guild Names, arrived with
-                                     2180), labels its GlobalStrings verbatim (SHOW_PLAYER_NAMES/
-                                     SHOW_GUILD_NAMES/SHOW_NPC_NAMES/SHOW_OWN_NAME).
-
-                                     The plate pair leads because it is what "Nameplates" means to
-                                     a player pressing V, and it is the pair that had no surface at
-                                     all — 1.12's own options UI has NO nameplate row (its
-                                     UIOptionsFrame keeps NAMEPLATES_ON/FRIENDNAMEPLATES_ON as
-                                     RegisterForSave'd globals driven only by the keybinding, and
-                                     says so in a comment), so the rows are era grammar over a
-                                     1.12 knob — 0959's law, the WorldDetail dropdown's posture.
-                                     Labels take the 1.12 binding names' own two-word spelling
-                                     ("Name Plates", BINDING_NAME_NAMEPLATES) with the era's
-                                     enemy/friendly split naming the two bits; no 1.12
-                                     OPTION_TOOLTIP string exists for either (nil, like Auto
-                                     Loot). -->
+                                <!-- 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. -->
                                 <Frame name="$parentNameplates" hidden="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -4754,13 +3473,8 @@
                                             <Scripts><OnLoad>OptionsRow_OnLoad(self, "UnitNamePlayer", "Player Names",
                                                 "OPTION_TOOLTIP_SHOW_PLAYER_NAMES")</OnLoad></Scripts>
                                         </Frame>
-                                        <!-- Player Guild Names (2149 §6 built the line; 2180 seats the row). A CHILD of
-                                             Player Names in both of the reference's own senses: its CheckButton22 hangs
-                                             off 21 with a +26 x indent, and UIOptionsFrame_UpdateDependencies greys it
-                                             from 21's tick. `UnitNamePlayerGuild` is not a SHOW gate — ShouldShowName
-                                             reads only bits 0x1/0x2/0x4 — it gates one LINE of the overhead stack, which
-                                             is why the dependency is real rather than cosmetic: with player names off
-                                             there is no stack for the guild line to be the second row of. -->
+                                        <!-- A child of Player Names, as CheckButton22 hangs off
+                                             21; it gates the guild line of the name stack. -->
                                         <Frame name="$parentRowGuildNames" inherits="OptionsCheckboxRowTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT" relativeTo="$parentRowPlayerNames" relativePoint="BOTTOMLEFT"><Offset><AbsDimension x="0" y="-9"/></Offset></Anchor>
@@ -4790,18 +3504,9 @@
                                         </Frame>
                                     </Frames>
                                 </Frame>
-                                <!-- The KEYBINDINGS page body (decision 1008 — the era Settings
-                                     panel's Keybindings category folded into this window; the module,
-                                     provenance and commit law: KeyBindingsPage.xml). First the
-                                     Character Specific row (the era page's first setting row, confirm
-                                     on uncheck only), then the section list — 19 dual-mode rows under
-                                     the shared faux-scroll kit, sections collapsed by default — and
-                                     the 1.12 window's message line (KEY_BOUND / the red steal / the
-                                     refused key string) at the foot. -->
-                                <!-- enableMouse: the page catches the wheel ITSELF on any point no
-                                     child claims (hit-testing only sees mouse-enabled frames —
-                                     pointer.rs; rows are plain Frames, so a spin over a row's name
-                                     would otherwise fall through to the window and die). -->
+                                <!-- The Keybindings page (its logic is KeyBindingsPage.xml).
+                                     enableMouse: rows are plain Frames, so the page itself
+                                     catches the wheel. -->
                                 <Frame name="$parentKeybindings" hidden="true" enableMouse="true">
                                     <Anchors>
                                         <Anchor point="TOPLEFT"/>
@@ -4815,15 +3520,8 @@
                                         </Layer>
                                     </Layers>
                                     <Frames>
-                                        <!-- Character Specific Key Bindings — the era checkbox-row
-                                             geometry (label left, the UI-CheckBox set at the
-                                             control column) over 1.12's set model; the click law
-                                             is KeyBindings_CharacterToggle. This bespoke row's
-                                             column sits at CENTER-40, not the shared CENTER-80:
-                                             1.12's string is longer than the era's and clipped at
-                                             the shared split ("…Key Bindin…" — the first capture);
-                                             no other control shares this page's column, so the
-                                             shift is free. -->
+                                        <!-- The box at CENTER-40, not CENTER-80: the 1.12
+                                             string is longer than the era's and clips there. -->
                                         <Frame name="$parentCharacterRow" enableMouse="true">
                                             <Size><AbsDimension y="26"/></Size>
                                             <Anchors>
@@ -4980,22 +3678,12 @@
                                         <Anchor point="TOPRIGHT" relativeTo="$parentRow18" relativePoint="BOTTOMRIGHT"/>
                                     </Anchors>
                                 </Frame>
-                                        <!-- That bar's TROUGH — the recessed channel it rides in (the
-                                             shared kit's template; 1.12 authors this art per window,
-                                             never in the bar template). Named off the bar, which is
-                                             how BenillaScrollBar_SetShown finds it, and carrying no
-                                             anchors of its own: it seats itself on that bar at the
-                                             ref's hang (BenillaScrollTrough_Seat), which is what
-                                             lands the channel's arrow sockets on the arrows. Sits
-                                             here, BEFORE the faux frame, so it draws beneath it. -->
+                                        <!-- 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. -->
                                         <Frame name="$parentScrollFrameScrollBarTrough" inherits="BenillaScrollTroughTemplate"/>
-                                        <!-- The faux scroll over the rows (the shared kit, 0997's own
-                                             seam). The kit's bar hangs 6px RIGHT of this frame's edge,
-                                             so the frame ends at the rows' own -32 and the 16-wide bar
-                                             rides the -26..-10 gutter inside the body (the TrainerFrame
-                                             seating). The wheel handler is NOT here: a spin over a row
-                                             bubbles up the PARENT chain (pointer.rs), and this frame is
-                                             the rows' sibling — it lives on the body below. -->
+                                        <!-- Ends at -32 so the kit's bar, hung 6 right, rides
+                                             the -26..-10 gutter (the TrainerFrame seating). -->
                                         <ScrollFrame name="$parentScrollFrame" inherits="FauxScrollFrameTemplate">
                                             <Anchors>
                                                 <Anchor point="TOPLEFT"><Offset><AbsDimension x="10" y="-47"/></Offset></Anchor>
@@ -5003,28 +3691,13 @@
                                             </Anchors>
                                             <Scripts>
                                                 <OnLoad>ScrollFrame_OnLoad()</OnLoad>
-                                                <!-- The reference's kit writes `frame.offset` ONLY
-                                                     from here (its `updateFunc` field does not
-                                                     exist); without this the bar moves and the list
-                                                     does not follow. `KEYBINDINGS_ROW_HEIGHT` is a
-                                                     file-scope global in KeyBindingsPage.xml, so it
-                                                     is visible to this handler's own chunk — a
-                                                     `local` would not be (1860). -->
+                                                <!-- The 1.12 kit updates `offset` only here.
+                                                     KEYBINDINGS_ROW_HEIGHT must stay a global:
+                                                     this chunk cannot see another file's local. -->
                                                 <OnVerticalScroll>FauxScrollFrame_OnVerticalScroll(KEYBINDINGS_ROW_HEIGHT, KeyBindingsPage_Update)</OnVerticalScroll>
-                                                <!-- **The armed guard has to be restated HERE.**
-                                                     While a capsule is armed the wheel is a BIND,
-                                                     never a scroll (1.12's law; the body below
-                                                     guards its own arm the same way). Our retired
-                                                     `FauxScrollFrameTemplate` was a plain `<Frame>`
-                                                     with no wheel handler, so the body's guard was
-                                                     the only path. The reference's template
-                                                     inherits `UIPanelScrollFrameTemplate`, which
-                                                     carries `<OnMouseWheel>` of its own — and that
-                                                     one fires on this frame, ahead of the body,
-                                                     bypassing the guard entirely. An instance's
-                                                     handler REPLACES the inherited one, so this is
-                                                     the reference's verb with our law back in front
-                                                     of it (1860). -->
+                                                <!-- Replaces the inherited wheel handler, which
+                                                     fires before the page's guard: while a capsule
+                                                     is armed the wheel binds, never scrolls. -->
                                                 <OnMouseWheel>
                                                     if not KeyBindingsPage.selected then
                                                         ScrollFrameTemplate_OnMouseWheel(arg1)
@@ -5033,11 +3706,8 @@
                                             </Scripts>
                                         </ScrollFrame>
                                     </Frames>
-                                    <!-- The page's wheel: rows and the bar all bubble here (the
-                                         QuestLog/Trainer lesson — a handler on the sibling catcher
-                                         never sees a spin over a row). The guard is 1.12's law:
-                                         while a capsule is armed the wheel is a BIND (the host
-                                         seam swallows it) — never a scroll. -->
+                                    <!-- Rows and the bar bubble the wheel here; an armed
+                                         capsule binds it instead. -->
                                     <Scripts>
                                         <OnMouseWheel>
                                             if not KeyBindingsPage.selected then
@@ -5046,11 +3716,8 @@
                                         </OnMouseWheel>
                                     </Scripts>
                                 </Frame>
-                                <!-- The search-results group headers — one per page WITH rows
-                                     (the OPTIONS_PAGE_ROWS set; a page that gains rows gains its
-                                     head here). Unanchored and hidden until a search chains them
-                                     in; the label is the category's pageTitle, the era
-                                     GetQualifiedName. -->
+                                <!-- The search heads, one per OPTIONS_PAGE_ROWS page; a new
+                                     page needs one here. -->
                                 <Button name="$parentSearchHeadControls" inherits="OptionsSearchHeadTemplate">
                                     <Scripts><OnLoad>
                                         self.categoryKey = "Controls"
@@ -5113,12 +3780,8 @@
                                         getglobal(self:GetName() .. "Label"):SetText("Keybindings")
                                     </OnLoad></Scripts>
                                 </Button>
-                                <!-- The keybinding search-result pool (decision 1008): the era
-                                     reflows LIVE binding rows into its results; ours is this static
-                                     pool of the same template, painted and chained by the search
-                                     display (capped at KEYBINDINGS_SEARCH_ROWS — the SCOPE note in
-                                     KeyBindingsPage.xml). Unanchored until a search places them;
-                                     the capsules run the full capture law in place. -->
+                                <!-- The keybinding search pool: one frame per
+                                     KEYBINDINGS_SEARCH_ROWS (8). -->
                                 <Frame name="$parentKeybindSearch1" inherits="KeyBindingRowTemplate" hidden="true"/>
                                 <Frame name="$parentKeybindSearch2" inherits="KeyBindingRowTemplate" hidden="true"/>
                                 <Frame name="$parentKeybindSearch3" inherits="KeyBindingRowTemplate" hidden="true"/>
@@ -5129,21 +3792,9 @@
                                 <Frame name="$parentKeybindSearch8" inherits="KeyBindingRowTemplate" hidden="true"/>
                             </Frames>
                             </Frame>
-                            <!-- The bar: the shared Slider (drag + arrows, decision 0250) on the
-                                 real-scroll handler, hidden until the content overflows. Seated
-                                 INSIDE the frame's right edge rather than 6 units outside it (the
-                                 UIPanelScrollFrameTemplate shape the faux kit uses): outside would
-                                 put it past the page box, and the -20 right inset the rows already
-                                 carry leaves the -26..-10 gutter free — the very gutter the
-                                 Keybindings list's bar rides.
-
-                                 Inset 21/20 vertically, not the ref's 16/16, because HERE the
-                                 scroll frame IS the page rect: the trough seats itself 21 above and
-                                 20 below the bar (BenillaScrollTrough_Seat), so these are the
-                                 offsets that put the whole channel — caps and all — exactly on the
-                                 page rect instead of poking 5 units up through the header divider
-                                 and 4 down past the container. The bar↔trough relationship is the
-                                 ref's either way; this only chooses which of the two is flush. -->
+                            <!-- 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. -->
                             <Slider name="$parentBar" inherits="BenillaScrollBarTemplate" hidden="true">
                                 <Anchors>
                                     <Anchor point="TOPRIGHT"><Offset><AbsDimension x="-10" y="-21"/></Offset></Anchor>
@@ -5156,24 +3807,12 @@
                 </Frames>
             </Frame>
 
-            <!-- ── The search box (era SearchBoxTemplate GEOMETRY: a 20-tall three-slice
-                 vertically centered on the 22 box — left cap 8x20 hung 5 outside, right cap
-                 8x20 flush, middle stretched between — a 17x17 clear button at RIGHT (-3)
-                 that appears with text). The slices wear the classic Common-Input-Border
-                 (0978 mapping) at the InputBoxTemplate UVs (caps u 0..1/16 and 15/16..1,
-                 ink v 0..0.625 of the 128x32 file). The era magnifier is DROPPED (no 1.12
-                 counterpart; the "Search" placeholder carries the affordance) — and with it
-                 the era's 16-left TextInsets seat that cleared it: text and caret sit at 5
-                 (0989). The clear X wears the UI-Panel-MinimizeButton ball, half-lit,
-                 full on hover (the era ClearButtonMixin alpha law). -->
+            <!-- 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. -->
             <EditBox name="$parentSearchBox" autoFocus="false" letters="64">
                 <Size><AbsDimension x="350" y="22"/></Size>
-                <!-- The era seat VERBATIM (SettingsPanel.xml l.76-81: 350x22, BOTTOMRIGHT ->
-                     Container TOPRIGHT (4, +20)). 0981 rebased y to -4 (the box line ran
-                     through it — the crowding report); 0984 restored y and bent x/width
-                     (-18/300) around the corner X ball; 0989 cut that X, so the last bend
-                     unwinds. The 1.14 title plate's tail (decoded: art ends x=539) still
-                     clears — this seat's left edge lands at x=552, 13 free. -->
+                <!-- 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>
@@ -5199,8 +3838,7 @@
                         </Texture>
                     </Layer>
                     <Layer level="ARTWORK">
-                        <!-- The "Search" placeholder (era instructions label: GameFontDisableSmall
-                             tinted 0.35). OnTextChanged below toggles it on first text. -->
+                        <!-- The placeholder (the era instructions label, tinted 0.35). -->
                         <FontString name="$parentInstructions" inherits="GameFontDisableSmall" justifyH="LEFT" text="Search">
                             <Anchors>
                                 <Anchor point="TOPLEFT"><Offset><AbsDimension x="5" y="0"/></Offset></Anchor>
@@ -5211,8 +3849,7 @@
                     </Layer>
                 </Layers>
                 <Frames>
-                    <!-- The clear X (era ClearButtonMixin: shown while text exists, half-alpha
-                         icon, click wipes). Shown/hidden by the box's OnTextChanged below. -->
+                    <!-- The clear button (era ClearButtonMixin), half alpha until hovered. -->
                     <Button name="$parentClearButton" hidden="true">
                         <Size><AbsDimension x="17" y="17"/></Size>
                         <Anchors><Anchor point="RIGHT"><Offset><AbsDimension x="-3" y="0"/></Offset></Anchor></Anchors>
@@ -5236,7 +3873,6 @@
                 </Frames>
                 <TextInsets><AbsInset left="5" right="20" top="0" bottom="0"/></TextInsets>
                 <Scripts>
-                    <!-- Placeholder + clear-button toggle, then the search proper (0984). -->
                     <OnTextChanged>
                         if this:GetText() == "" then
                             BenillaOptionsFrameSearchBoxInstructions:Show()
@@ -5252,8 +3888,7 @@
                 <FontString inherits="GameFontHighlightSmall"/>
             </EditBox>
 
-            <!-- ── Close (no corner X — 0989's directed cut, header SCOPE note; the red
-                 button and ESC are the window's exits) ─────────────────────────────────── -->
+            <!-- ── 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>
@@ -5264,10 +3899,7 @@
                     </OnClick>
                 </Scripts>
             </Button>
-            <!-- The era Apply (SettingsPanel.ApplyButton: 96x22, RIGHT of Close's LEFT at -2,
-                 Blizzard_SettingsPanel.xml l.52-57): exists only while a deferred row holds a
-                 pending value — era enables and SHOWS it together (SetApplyButtonEnabled) —
-                 and commits every pending edit on click. -->
+            <!-- The era Apply (Blizzard_SettingsPanel.xml l.52-57), 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>
@@ -5277,19 +3909,14 @@
             </Button>
         </Frames>
         <Scripts>
-            <!-- Controls is the default page; a re-opened window keeps its last selection (the
-                 era remembers too — Settings.OpenToCategory's default seat). The scale re-fits
-                 on every show — the era panel manager re-runs checkFit the same way. -->
+            <!-- Controls by default; selection persists and the scale re-fits, as the era's. -->
             <OnShow>
                 BenillaOptionsFrame_UpdateScale()
                 BenillaOptionsFrame_SelectCategory(this.selectedCategory or "Controls")
                 if UpdateMicroButtons then UpdateMicroButtons() end
             </OnShow>
-            <!-- Hiding discards pending edits (the era wipes its modified table on hide; its
-                 close-time confirm dialog is cut — SCOPE note), ends a live search (the
-                 era Flush's ClearSearchBox, SettingsPanel.lua l.187-193), and disarms a
-                 straggling bind capture — the host seam swallowing all input with no window
-                 on screen would be a lockout (KeyBindingsPage.xml, decision 1008). -->
+            <!-- Hiding ends a search (the era's ClearSearchBox), discards pending edits, and
+                 disarms a bind capture, which would otherwise swallow all input. -->
             <OnHide>
                 BenillaOptionsFrameSearchBox:SetText("")
                 OptionsPage_DiscardPending()
@@ -5299,70 +3926,16 @@
             </OnHide>
         </Scripts>
     </Frame>
-    <!-- ══ NO ALIASES LEFT, AND THIS WINDOW IS NO LONGER `OptionsFrame` (2115, 2147, 2177) ══
-         The reference has THREE options windows — `OptionsFrame` (video), `SoundOptionsFrame` and
-         `UIOptionsFrame` (interface). **All three are now the reference's own frames, loaded
-         hidden off the player's chain**, and none of them may ever be aliased onto this one.
-
-         The last of the three to arrive was the VIDEO window, and it is the one that took a name
-         off this file: the frame above was called `OptionsFrame` for its whole life, and
-         `Interface\FrameXML\OptionsFrame.xml` declares that name itself. Two frames cannot hold
-         one global — `CreateFrame` publishes into `_G` and the later one simply wins, silently —
-         and neither ordering is survivable. Ours later CLOBBERS the stock frame, and pfUI's
-         `skins/blizzard/options-video.lua` then runs `CreateBackdrop`, `EnableMovable`,
-         `HookScript(…, "OnShow", …)` and `OptionsFrameHeader:SetTexture("")` against the window the
-         player opens. Ours earlier is no better: the skin's `OptionsFrameSlider1..9` and
-         `OptionsFrameCheckButton1..18` would find the stock frame's children while its
-         `CreateBackdrop(OptionsFrame)` found ours — half a skin, on two different windows. So the
-         reference's name went back to the reference's window and this one became
-         `BenillaOptionsFrame`, the `Benilla…` convention every other frame of our own already
-         wears (`BenillaScriptLogFrame`, `BenillaScrollBarTemplate`).
-
-         **What the rename cost, and where each cost is paid.** Three things keyed on the old name
-         had to be restated rather than lost:
-         · the **panel-manager row** — `UIParent.lua:16`'s `UIPanelWindows["OptionsFrame"]`, which
-           gave this window the centre slot and the while-dead permission. Restated below, verbatim.
-         · the **ESC ladder and the micro button** — `ToggleGameMenu`, `IsOptionFrameOpen` and
-           `UpdateMicroButtons` all name the reference's three windows literally, so the whole chain
-           now reads "no" while ours is up. Three wrappers in `GameMenuFrame.xml` add the one term
-           the reference could not know about; that file is the manifest's last row, which is where
-           `UpdateMicroButtons` finally exists to wrap.
-         · the **`OptionsFrameCancel` alias** — RETIRED, and by the sharper of the two arguments.
-           It pointed the reference's name at our Close button so `ToggleGameMenu`'s
-           `OptionsFrameCancel:Click()` would discard-and-hide this window. That button is now a
-           real frame in the stock video window, and this file loads after it, so the alias would
-           not sit beside it — it would **clobber** it, and pfUI's video skin's
-           `SkinButton(OptionsFrameCancel)` would land on ours. The ESC rung it existed for is the
-           `ToggleGameMenu` wrapper's now, calling our own Close button by our own name.
-
-         Nothing of ours may `Show()` any of the three stock frames; each is `hidden="true"` in its
-         own file and that is what keeps them off the screen.
-
-         **One behaviour changed when the `UIOptionsFrame` alias went, and it is the right one.**
-         `FloatingChatFrame.lua` l.842/860 gate the chat tab and dock hover on
-         `not UIOptionsFrame:IsShown()`. That reads the hidden stock frame, so chat-tab hover
-         works while OUR options window is open. The reference's gate exists because ITS interface
-         window is `frameStrata="FULLSCREEN"` with `setAllPoints` and covers the chat; ours is a
-         panel that does not. No adapter is added for it (2115).
-         BENILLA_ALLOW_OWN_UI=1 -->
+    <!-- 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. BENILLA_ALLOW_OWN_UI=1 -->
     <Script><![CDATA[
-        -- ══ THIS WINDOW'S PANEL-MANAGER ROW ══════════════════════════════════════════════════
-        -- `UIPanelWindows` is the table `ShowUIPanel` reads to place a window: `area` picks the
-        -- slot ("center" is the native-centre one, which no side panel may push aside),
-        -- `pushable` its rank within that slot, `whileDead` whether it may open with the player
-        -- dead. A frame with NO row gets none of it — `ShowUIPanel` falls through to a bare
-        -- `Show()`, unplaced, and death closes it.
-        --
-        -- Until now this frame rode the REFERENCE's row. `UIParent.lua:16` keys one on the name
-        -- `OptionsFrame`, and that was this frame's name, so the game menu's Options button got
-        -- the centre slot and the while-dead permission for free. That name is now the stock
-        -- VIDEO options window's, so the row keyed on it is ITS row — and this window needs its
-        -- own. The three values below are the reference's own, copied verbatim from that line:
-        -- the placement our window has always had, now stated under the name it now answers to.
-        --
-        -- SAFE TO RUN HERE: `UIParent.xml` — which carries `UIParent.lua`, where `UIPanelWindows`
-        -- is created — is the manifest's 7th row (`benilla.toc` l.144) and this file is its 38th
-        -- (l.522), so the table is real by the time this executes.
+        -- 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.
         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 21407722..979c2b07 100644
--- a/crates/benilla-app/assets/ui/ScriptLogFrame.xml
+++ b/crates/benilla-app/assets/ui/ScriptLogFrame.xml
@@ -1,68 +1,31 @@
 <Ui>
     <!--
-        benilla's **script error log** (decision 1495) — the window B293 asked for, and it is
-        entirely OURS: 1.12 has no counterpart, so every name here wears the `Benilla` prefix (1254's
-        rule, `tests::reference_surface`'s gate).
-
-        ## Why it exists beside `ScriptErrors`
-
-        `BasicControls.xml`'s red `ScriptErrors` dialog is the reference's whole answer to a Lua
-        fault, transcribed and installed by 1305 — and it stays exactly as it is. It shows **one**
-        message, because `_ERRORMESSAGE` guards on `ScriptErrors:IsVisible()`, and it remembers
-        nothing. Two reporters said so within days of it shipping: Goudy, *minutes after
-        screenshotting that dialog working*, *"some kind of lua error frame probably needs to be
-        implemented, as there are a lot of addons that still doesn't work"*; nazriel_0, *"probably we
-        should start using something like Bug Grabber to report those stack traces better"*.
-
-        So: the dialog is the interrupt, this is the log. Additive, no divergence — the reference
-        simply never had this instrument.
-
-        ## Shape
-
-        `CraftFrame.xml`'s shape, which is the house idiom for "windowed panel, faux-scrolled row
-        list, detail pane that repaints on selection": 13 fixed 16px rows over a
-        `FauxScrollFrameTemplate`, and a **real** `<ScrollFrame>` detail pane below (the real kit,
-        not the faux one — a message is a `mlua` error string with its `stack traceback:` tail
-        attached, so the detail is genuinely variable-height content, which is what the real kit is
-        for; `GossipFrame.xml`'s greeting pane is the same wiring).
-
-        The window registers itself in `UIPanelWindows` (below; the table is the stock UIParent.lua's
-        since 1988), which is what seats it in the
-        left slot and gets it closed by `CloseAllWindows()` — i.e. by ESC — with no code here. Our
-        own toplevels deliberately stay OUT of `UISpecialFrames`: that table is the addons' (0544's
-        note, 1206).
-
-        ## Reading the model
-
-        Three engine reads, all from the retained log on the model
-        (`benilla_ui::script::diagnostics`): `BenillaGetNumScriptErrors()` →
-        `retained, totalEverRecorded`; `BenillaGetScriptErrorInfo(i)` → `seq, kind, message, count`
-        (1-based, oldest first, nil past the end); `BenillaClearScriptErrors()`. There is no per-frame
-        feed and nothing to keep in step — the window polls the log it is a view of.
+        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.
     -->
     <Script><![CDATA[
-        -- The slot-manager row (decision 1495): a left-area window one tier above every stock
-        -- panel's pushable, so opening a game window pushes the log aside rather than the reverse.
+        -- A left-slot window with 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. The full text is the detail pane's job; a row is an
-        -- index, and a row that wraps would break the fixed-height list the faux kit requires.
+        -- How much of a message a row shows; a wrapped row would break the faux kit's fixed rows.
         BENILLA_SCRIPTLOG_ROW_CHARS = 52
 
-        -- Which row is selected (a `seq`, not an index — indices shift when the cap evicts, and a
-        -- selection that silently slides onto a different error is worse than one that goes away).
+        -- The selected row's `seq`, not its index: indices shift when the cap evicts.
         BenillaScriptLogSelected = nil
 
-        -- The first line of a message, trimmed to a row's width. A traceback's later lines are
-        -- indented continuations; on one row they read as noise.
-        -- `strsub` is BYTE-indexed (Lua 5.0 strings are byte strings, and benilla keeps them that
-        -- way — decision 1193), so a cut that lands inside a multi-byte character leaves half of
-        -- one. Every message here is UTF-8 and ours are full of em dashes, so this was not
-        -- theoretical: the log window's own repaint raised on the first warning it was ever asked
-        -- to show (2135/2138). Back the cut up over any continuation byte (`10xxxxxx`, i.e.
-        -- 0x80..0xBF) so it lands on a character boundary.
+        -- 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.
         function BenillaScriptLog_RowText(message)
             local cut = strfind(message, "\n", 1, 1)
             local head = message
@@ -79,13 +42,10 @@
             return head
         end
 
-        -- The three kinds, coloured by CONSEQUENCE — how much of the addon is broken:
-        --   `load`  red    an addon is not running at all (the thing a player can act on)
+        -- 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 (2135)
-        -- Grey rather than a fourth bright colour because a warning is the least urgent of the
-        -- three and there are more of them: colour has to keep ranking the list, not just label
-        -- it. Colours come from the shipped tables so this window matches the rest of the UI.
+        --   `warn`  grey   a call was accepted and quietly did not do what it said
         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
@@ -95,12 +55,8 @@
         function BenillaScriptLog_Update()
             local shown, total = BenillaGetNumScriptErrors()
 
-            -- The summary line carries the one number a bug report needs and the window cannot
-            -- otherwise show: how many were DROPPED. `total` counts distinct failures ever
-            -- recorded; `shown` is what survived the cap.
-            -- "problems", not "errors": the log carries three kinds now and two of them are not
-            -- errors (2135). The window is still `/errors` and still opens on the same key —
-            -- what changed is that a count of 7 stopped meaning "7 things raised".
+            -- `total` counts distinct failures ever recorded, `shown` what the cap kept. The
+            -- summary says "problems" because two of the three kinds are not errors.
             local summary
             if total == 0 then
                 summary = "No problems this session."
@@ -126,9 +82,7 @@
                 if seq then
                     button.seq = seq
                     button.message = message
-                    -- The count rides the index, not the text: `#12 x1113` says "this is one
-                    -- failure that happened 1,113 times", which is the whole reason the log
-                    -- deduplicates instead of listing 1,113 rows.
+                    -- `#12 x1113`: one deduplicated failure that happened 1,113 times.
                     local label = "#" .. seq
                     if count > 1 then label = label .. " x" .. count end
                     button.index:SetText(label)
@@ -143,9 +97,8 @@
                 end
             end
 
-            -- The moving highlight, seated onto the selected row only when that row is on screen —
-            -- scrolling the selection away hides the glow rather than stranding it (CraftFrame's
-            -- own behaviour).
+            -- The highlight follows the selected row and hides when it scrolls away, as the
+            -- reference's CraftFrame does.
             local highlight = getglobal("BenillaScriptLogHighlightFrame")
             if selectedRow then
                 highlight:SetPoint("TOPLEFT", selectedRow:GetName(), "TOPLEFT", 0, 0)
@@ -157,8 +110,8 @@
             BenillaScriptLog_UpdateDetail()
         end
 
-        -- The detail pane: the FULL message of the selected row, traceback and all. Selection is by
-        -- `seq`, so this walks the log rather than indexing it.
+        -- The selected message in full, traceback and all; selection is a `seq`, so this walks
+        -- the log rather than indexing it.
         function BenillaScriptLog_UpdateDetail()
             local text = ""
             if BenillaScriptLogSelected then
@@ -177,18 +130,14 @@
             getglobal("BenillaScriptLogDetailText"):SetText(text)
         end
 
-        -- Frame-late by nature (the shared kit's own note): text rects resolve after Lua runs, so
-        -- the child is re-measured from OnUpdate until it stops changing, after which this is a
-        -- no-op compare per frame. OnUpdate only fires on visible frames, so a closed window costs
-        -- nothing.
+        -- 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.
         function BenillaScriptLogFrame_OnUpdate()
             BenillaScroll_ResizeChild("BenillaScriptLogDetailScroll", { "BenillaScriptLogDetailText" })
         end
 
         function BenillaScriptLogRow_OnClick(button)
             if not button.seq then return end
-            -- Clicking the selected row deselects: the detail pane is a drawer, and a list with no
-            -- way back to "nothing selected" is a small trap.
             if BenillaScriptLogSelected == button.seq then
                 BenillaScriptLogSelected = nil
             else
@@ -198,20 +147,17 @@
         end
 
         function BenillaScriptLogFrame_OnLoad(self)
-            -- The ring's icon, through the portrait verb rather than left at its `file=` — see the
-            -- texture's own note. MailFrame.xml's open-letter icon is the same fix.
+            -- Masks the square icon to the portrait ring.
             SetPortraitToTexture("BenillaScriptLogFramePortrait",
                 "Interface\\Icons\\INV_Misc_Note_01")
         end
 
-        -- The shared helper steps the faux frame's bar, whose OnValueChanged runs the kit's
-        -- offset handler and thence `updateFunc` — so the repaint is wired once, at OnLoad, and
-        -- not repeated here.
+        -- Stepping the bar repaints through the list frame's OnVerticalScroll, so no repaint here.
         function BenillaScriptLogFrame_OnMouseWheel(delta)
             BenillaFauxScrollFrame_OnMouseWheel(getglobal("BenillaScriptLogListScrollFrame"), delta)
         end
 
-        -- ── The three entry points the client and the player reach this by ────────────────────
+        -- ── Entry points ──────────────────────────────────────────────────────────────────────
 
         function BenillaScriptLog_Toggle()
             local frame = getglobal("BenillaScriptLogFrame")
@@ -222,10 +168,8 @@
             end
         end
 
-        -- `/errors clear`. Forgets the rows, keeps the numbering (the engine's own rule — a number
-        -- must never name two different failures across a screenshot). Prints a confirmation
-        -- because a command whose whole effect is "a window you may not have open is now empty"
-        -- is otherwise indistinguishable from a typo.
+        -- `/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.
         function BenillaScriptLog_Clear()
             BenillaClearScriptErrors()
             BenillaScriptLogSelected = nil
@@ -236,9 +180,8 @@
         end
     ]]></Script>
 
-    <!-- One list row: the `#N xCount` index column, then the message head. Fixed columns, 1.12's
-         own list idiom — not a width limitation: a FontString with a zero-authored axis takes its
-         measured box into the resolve (`benilla-ui` `script/layout.rs`, decision 1664). -->
+    <!-- One list row: the `#N xCount` index column, then the message head, in fixed columns as
+         1.12's lists are. -->
     <Button name="BenillaScriptLogRowTemplate" virtual="true" hidden="true">
         <Size><AbsDimension x="293" y="16"/></Size>
         <Layers>
@@ -268,18 +211,15 @@
         <Size><AbsDimension x="384" y="512"/></Size>
         <Layers>
             <Layer level="BACKGROUND">
-                <!-- The same square ITEM icon the mail window's ring holds, and it needs the same
-                     portrait verb for the same reason (`SetPortraitToTexture` in OnLoad below):
-                     `file=` alone draws it unmasked and its corners show through the ring's
-                     transparent ones. -->
+                <!-- A square item icon: OnLoad masks it with `SetPortraitToTexture`, since `file=`
+                     alone shows its corners 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 four quadrant slabs. The ClassTrainer family, all four, because it is the one
-                 UNIFORM set in the 1.12 art (CraftFrame's own note) and this window belongs to no
-                 profession — borrowing a themed half would make it look like a window it isn't. -->
+            <!-- The ClassTrainer quadrants, the one uniform set in the 1.12 art; this window
+                 belongs to no profession. -->
             <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>
@@ -288,22 +228,18 @@
                 <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, and the ONLY place the dropped-row count can be told. -->
+                <!-- 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>
             </Layer>
         </Layers>
         <Frames>
-            <!-- The top-right X: the chain's own `UIPanelCloseButton` (seated at benilla.toc's
-                 `Interface\FrameXML\UIPanelTemplates.xml`, 757 lines above this file). Its
-                 32x32, its three minimize-button state textures and its
-                 `HideUIPanel(this:GetParent())` are byte-for-byte what stood here authored. -->
             <Button name="BenillaScriptLogCloseButton" inherits="UIPanelCloseButton">
                 <Anchors><Anchor point="TOPRIGHT"><Offset><AbsDimension x="-29" y="-8"/></Offset></Anchor></Anchors>
             </Button>
 
-            <!-- Declared BEFORE the rows so row text paints over the glow (the house z-tiebreak). -->
+            <!-- Declared before the rows so their text draws over the glow. -->
             <Frame name="BenillaScriptLogHighlightFrame" hidden="true">
                 <Size><AbsDimension x="293" y="16"/></Size>
                 <Anchors><Anchor point="TOPLEFT" relativePoint="TOPLEFT"/></Anchors>
@@ -335,16 +271,14 @@
                 <Size><AbsDimension x="293" y="208"/></Size>
                 <Anchors><Anchor point="TOPLEFT" relativePoint="TOPLEFT"><Offset><AbsDimension x="22" y="-94"/></Offset></Anchor></Anchors>
                             <Scripts>
-                    <!-- The reference's kit writes `frame.offset` ONLY from here; its
-                         `updateFunc` field does not exist, so without this the bar moves and
-                         the list does not follow (1868). -->
+                    <!-- The stock kit sets the offset only from here and has no `updateFunc`, so
+                         the repaint is wired here too. -->
                     <OnVerticalScroll>FauxScrollFrame_OnVerticalScroll(BENILLA_SCRIPTLOG_ROW_HEIGHT, BenillaScriptLog_Update)</OnVerticalScroll>
                 </Scripts>
 </ScrollFrame>
 
-            <!-- The detail pane: the REAL scroll kit, because a message carries its `stack
-                 traceback:` tail and is genuinely variable-height. GossipFrame's greeting pane is
-                 the same wiring. -->
+            <!-- The detail pane, on the real-scroll kit: a message with its `stack traceback:` tail
+                 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>
@@ -367,8 +301,7 @@
                         <Anchors><Anchor point="TOPLEFT" relativePoint="TOPLEFT"/></Anchors>
                         <Layers>
                             <Layer level="ARTWORK">
-                                <!-- 270 wide so the engine wraps the traceback rather than clipping
-                                     it; the pane pans over whatever height that comes to. -->
+                                <!-- 270 wide so the traceback wraps rather than clips. -->
                                 <FontString name="BenillaScriptLogDetailText" inherits="GameFontHighlightSmall" justifyH="LEFT" justifyV="TOP" text="">
                                     <Size><AbsDimension x="270" y="0"/></Size>
                                     <Anchors><Anchor point="TOPLEFT" relativePoint="TOPLEFT"><Offset><AbsDimension x="6" y="-6"/></Offset></Anchor></Anchors>
@@ -392,18 +325,16 @@
         </Frames>
         <Scripts>
             <OnLoad>BenillaScriptLogFrame_OnLoad(self)</OnLoad>
-            <!-- The list wheel lives on the WINDOW: the engine bubbles a spin up the parent chain
-                 (CraftFrame's own note). The detail pane has its own, which wins over its own rect. -->
+            <!-- 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. -->
             <OnMouseWheel>BenillaScriptLogFrame_OnMouseWheel(arg1)</OnMouseWheel>
             <OnShow>BenillaScriptLog_Update()</OnShow>
             <OnUpdate>BenillaScriptLogFrame_OnUpdate()</OnUpdate>
         </Scripts>
     </Frame>
-    <!-- benilla's own commands over the reference's SlashCmdList (decision 1948). The stock
-         ChatEdit_ParseText walks SlashCmdList after its own built-ins, so each of benilla's commands
-         (ui_chat::commands — the dev instruments and the three additions) hands its line to
-         SubmitChatInput, where ui_chat::input's parser still owns it. This file loads after the
-         reference's ChatFrame.xml, which is what declares the table. -->
+    <!-- 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. -->
     <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 a8713c1c..00a66d3c 100644
--- a/crates/benilla-app/assets/ui/ScrollTemplates.xml
+++ b/crates/benilla-app/assets/ui/ScrollTemplates.xml
@@ -1,54 +1,30 @@
 <Ui>
     <!--
-        benilla's reusable scroll kits — TWO of them, sharing one scrollbar, one pair of arrow
-        helpers and one optional TROUGH (`BenillaScrollTroughTemplate`, at the foot: the recessed
-        channel a bar rides in — 1.12 authors that art per window, so an owner declares one beside
-        its bar and the kit shows and hides the two together).
-        The **faux-scroll** kit (this header) re-binds a fixed set of rows to a moving data
-        offset; the **real-scroll** kit (second half of the script block) pans and CLIPS a
-        variable-height child through the engine's `<ScrollFrame>` (decision 0112) — the one a gossip
-        menu of wrapped options needs, since its content height isn't known until it is laid out.
-        Only their OnValueChanged differs, and an instance overrides the template's (the loader
-        SetScripts every `<Scripts>` block in order, so the instance's handler wins).
-
-        The faux kit (decisions 0247/0250/0251): a draggable scroll bar over
-        the `Slider` primitive (0250) plus the fixed-row "faux scroll" Lua layer — the reference's
-        `FauxScrollFrame`, which never really scrolls a child: it re-binds a fixed set of row buttons to
-        a moving data offset. First customer: the class trainer's skill-line list (TrainerFrame.xml).
-        The quest log's chunk-local faux-scroll upvalue is a later migration onto this.
-
-        DESIGN — collapsed from the real client's three-part decomposition (0250: FauxScrollFrame =
-        ScrollFrame + Slider + Lua). The real `FauxScrollFrameTemplate` routes the scrollbar's value
-        through its parent `ScrollFrame` (`OnValueChanged → parent:SetVerticalScroll(v)`; the
-        ScrollFrame's `OnVerticalScroll` then derives `offset = floor(v/itemHeight + 0.5)`). That
-        ScrollFrame adds nothing to the value on its way through: 0251 believed it clamped to the
-        scroll range and called the clamp a liability, and decision 2017 read the bytes — the
-        reference's `SetVerticalScroll` stores what the bar hands it. So the relay is a pure
-        pass-through, and benilla's faux frame is a plain `<Frame>` + a `Slider`: fewer moving parts
-        and the identical on-screen result (a smooth, pixel-granularity thumb whose position maps
-        1:1 to the scroll offset). See 0251 for the full rationale + the divergence from 0250's
-        described (real-client) shape.
-
-        VALUE MODEL. The scrollbar's value is in PIXELS: `[0, (numItems − numToDisplay) * itemHeight]`,
-        `valueStep = itemHeight`. The row offset is `floor(value / itemHeight + 0.5)` — sub-pixel
-        rounding, so the thumb (drawn at the raw value fraction) and the list (drawn at the rounded
-        offset) never visibly disagree. The frame carries `frame.offset` (the top visible row, 0-based)
-        and `frame.updateFunc` (the owner's list-repaint, set by the owner's OnLoad).
+        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.
     -->
     <Script><![CDATA[
-        -- Step the bar one row (the slider's valueStep) — the sensible step for an item list (the
-        -- generic ref scrollbar steps half its height; a discrete row list wants one). Silent by
-        -- design: the ref plays UChatScrollButton only on the arrow *buttons'* OnClick, never on the
-        -- wheel (ScrollFrameTemplate_OnMouseWheel is soundless). Both the wheel and the arrows call
-        -- this, so the click lives on the arrow OnClick, keeping wheel-scroll silent.
+        -- 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.
         function BenillaScrollBar_Step(scrollBar, dir)
             local step = scrollBar:GetValueStep()
             if step <= 0 then step = 1 end
             scrollBar:SetValue(scrollBar:GetValue() + dir * step)
         end
 
-        -- Grey the up arrow at the top and the down arrow at the bottom (ref
-        -- ScrollFrame_OnScrollRangeChanged's arrow handling), from the slider's own value/range.
+        -- Greys each arrow at its end of the range (reference: ScrollFrame_OnScrollRangeChanged).
         function BenillaScrollBar_UpdateArrows(scrollBar)
             local minV, maxV = scrollBar:GetMinMaxValues()
             local val = scrollBar:GetValue()
@@ -58,29 +34,11 @@
             if val >= maxV then down:Disable() else down:Enable() end
         end
 
-        -- The scrollbar's OnValueChanged: derive the row offset from the (pixel) value and, only when
-        -- it actually moved, repaint the owner's list. The change-gate is load-bearing: the owner's
-        -- repaint calls _Update below, which SetValue()s the thumb back to offset*itemHeight — a value
-        -- that maps to the SAME offset, so this handler no-ops and the cycle stops after one hop (the
-        -- Slider's own SetValue change-gate stops the value side, decision 0250).
-        --
-        -- THE SECOND HALF IS FOR ADDONS, and it is the reference's own wiring. The ref's
-        -- `UIPanelScrollBarTemplate` routes its value through the ScrollFrame it rides
-        -- (`<OnValueChanged>this:GetParent():SetVerticalScroll(arg1)</OnValueChanged>`,
-        -- ref-UIPanelTemplates.xml l.156-158), and that frame's `<OnVerticalScroll>` is where an
-        -- addon puts `FauxScrollFrame_OnVerticalScroll(itemHeight, MyUpdate)`. Our OWN faux frames
-        -- are plain `<Frame>`s (the 0251 divergence in the header above), so they have no
-        -- SetVerticalScroll and this line never fires for them — but an addon's is declared
-        -- `<ScrollFrame ... inherits="FauxScrollFrameTemplate">`, and the instance's own tag wins
-        -- over the template's on inherit (framexml.rs `merge`), so it really is one. Duck-typed for
-        -- exactly that reason.
-        --
-        -- The engine's SetVerticalScroll takes the bar's value as given (decision 2017 — the
-        -- reference's never reads the scroll range), so an addon frame's `<OnVerticalScroll>`
-        -- fires with this very value and its `FauxScrollFrame_OnVerticalScroll` derives the offset
-        -- from it, the reference's path end to end. The offset our own kit computes above is the
-        -- same number by construction — it comes straight off the Slider, which is the whole point
-        -- of 0251.
+        -- 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).
         function BenillaFauxScrollBar_OnValueChanged(scrollBar, value)
             local frame = scrollBar:GetParent()
             local step = scrollBar:GetValueStep()
@@ -94,27 +52,10 @@
             if frame.SetVerticalScroll then frame:SetVerticalScroll(value) end
         end
 
-        -- Seat a trough ON ITS BAR. THE SOCKETS, and why this is not a free choice: the channel art
-        -- is not a plain tube — each end carries a 16-tall SOCKET that the arrow button drops into,
-        -- bounded by the frame's outer cap and an inner crossbar. Measured texel-exact off
-        -- UI-Character-ScrollBar (64x256):
-        --   top piece    (left column) : rows 0-3 CAP · rows 4-19 SOCKET · rows 20-21 crossbar
-        --   bottom piece (right column): rows 85-86 crossbar · rows 87-102 SOCKET · rows 104-106 CAP
-        -- Both pieces draw 1:1 anchored to their own end of the trough, and the arrow buttons sit 16
-        -- outside the slider's ends — so a socket lands on its arrow only when the trough OVERHANGS
-        -- the bar by 21 above and 20 below (4 rows of cap at the top against 3+1 at the bottom; that
-        -- 1 is the whole asymmetry). Those are the ref's own numbers, reached from the other side:
-        -- ReputationFrame hangs its trough at the scroll frame's TOPRIGHT (-2,+5) / BOTTOMRIGHT
-        -- (-2,-4) against a bar seated (6,-16)/(6,+16) — 21, 20, and the 8-left hang
-        -- (ref-ReputationFrame.xml l.573-599 against ref-UIPanelTemplates.xml l.166-181). Miss it by
-        -- even 4 and the arrows ride OUT of their sockets onto the caps with a sliver of bare socket
-        -- showing beside them, which is exactly what B224 reported.
-        --
-        -- Seated HERE, off the bar, rather than restated in each owner's XML: it is one law, and an
-        -- owner made to re-derive it in offsets is an owner that can get it wrong — which is how
-        -- B224 happened. So a trough carries NO anchors of its own; declare it before the bar (so it
-        -- draws beneath) and name it `<barname>Trough`, and that is the whole contract. Lazy,
-        -- because the bar is declared after the trough and does not exist at the trough's OnLoad.
+        -- 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.
         function BenillaScrollTrough_Seat(trough, scrollBar)
             if trough.seated then return end
             trough.seated = true
@@ -123,19 +64,9 @@
             trough:SetPoint("BOTTOMRIGHT", scrollBar, "BOTTOMRIGHT", 7, -20)
         end
 
-        -- Show/hide a bar TOGETHER WITH ITS TROUGH — the recessed channel it rides in, if the
-        -- owner authored one beside it (a `<barname>Trough` frame on BenillaScrollTroughTemplate
-        -- below). Every path that shows or hides a bar goes through here, so a window that fits
-        -- shows neither and one that overflows shows both — and so a trough is seated on its bar
-        -- before it can ever be visible, whichever way the first call goes.
-        --
-        -- Why the trough is OPT-IN rather than part of the bar template: 1.12 authors trough art
-        -- PER WINDOW, never in the shared scroll kit — `UIPanelScrollBarTemplate` carries only the
-        -- two arrow buttons and the knob, and the ref's FrameXML then hangs loose trough textures
-        -- beside 29 individual bars, in two different skins (UI-Character-ScrollBar for the
-        -- dialog/paperdoll family, UI-ClassTrainer-ScrollBar for the trainer family). The era's own
-        -- MinimalScrollBar went the other way and made its Track part of the bar; this pair keeps
-        -- the era's COUPLING (track lives and dies with the bar) on 1.12's per-window SKIN.
+        -- 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.
         function BenillaScrollBar_SetShown(scrollBar, shown)
             local trough = getglobal(scrollBar:GetName() .. "Trough")
             if trough then BenillaScrollTrough_Seat(trough, scrollBar) end
@@ -148,17 +79,9 @@
             end
         end
 
-        -- **Our trough, following the REFERENCE's bar.** `BenillaScrollBar_SetShown` above is the
-        -- Benilla kit's own pairing and nothing in the reference's faux kit calls it — the
-        -- reference has no trough at all, which is exactly why this template stays ours (1837's
-        -- manifest note). Since the faux frames took the chain's `FauxScrollFrameTemplate` their
-        -- bar is `UIPanelScrollBarTemplate`, so an owner that wants its trough asks for it here,
-        -- right after its `FauxScrollFrame_Update`. Seating is idempotent and the visibility
-        -- simply mirrors the bar's, which the reference's `_Update` has already decided by
-        -- showing or hiding the scroll FRAME.
-        --
-        -- Decision 1860. Named after the bar rather than the frame because the trough is declared
-        -- `<barname>Trough` — one law, stated once, exactly as BenillaScrollTrough_Seat wants it.
+        -- 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.
         function BenillaScrollTrough_Follow(scrollFrameName)
             local sf = getglobal(scrollFrameName)
             if not sf then return end
@@ -170,45 +93,30 @@
             if sf:IsShown() then trough:Show() else trough:Hide() end
         end
 
-        -- A wheel spin over the list → one row (WoW convention: +1 up, −1 down). Called from the
-        -- owner window's OnMouseWheel (the engine bubbles the spin up the parent chain, so the handler
-        -- lives on the window, not a child — TrainerFrame.xml's own note).
-        --
-        -- KEEPS the `Benilla` prefix on purpose: the reference has no faux-scroll wheel function to
-        -- take the name of. Its `ScrollFrameTemplate_OnMouseWheel` is the REAL-scroll one and moves
-        -- by half the bar's height; its faux owners each write a wheel body of their own inline.
+        -- 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).
         function BenillaFauxScrollFrame_OnMouseWheel(frame, delta)
             local scrollBar = getglobal(frame:GetName() .. "ScrollBar")
             BenillaScrollBar_Step(scrollBar, -delta)
         end
 
-        -- ══════════════════════════ The REAL-scroll kit ══════════════════════════════════════════
-        --
-        -- The other half of the file: a true `<ScrollFrame>` (engine mechanism, decision 0112) that
-        -- pans and CLIPS a variable-height child, as against the faux kit above (fixed rows re-bound
-        -- to a data offset). Windows whose content height is unknown until it is laid out — a gossip
-        -- menu of wrapped options, a quest's body text — need this one; a uniform list wants the faux.
-        --
-        -- SHAPE, from the reference `UIPanelScrollFrameTemplate` (Interface\FrameXML\
-        -- UIPanelTemplates.xml l.166-211, extracted via mpqx): the scrollbar is a SLIDER that rides
-        -- its ScrollFrame as a child, so `bar:GetParent()` IS the frame it scrolls — no name
-        -- derivation, and `$parentBar` gives SyncBar its handle. The ref's OnVerticalScroll drives
-        -- the bar's value and greys the two arrows at the ends; ours does the same through the
-        -- shared arrow helper above.
-        BENILLA_SCROLL_STEP = 20   -- px per arrow click / wheel notch
-        BENILLA_SCROLL_PAD = 20    -- breathing room under the last element in the child
+        -- ══════════════════════════ 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.
+        BENILLA_SCROLL_STEP = 20   -- px per arrow click or wheel notch
+        BENILLA_SCROLL_PAD = 20    -- px of room below the child's last element
 
-        -- The bar moved (drag, arrow, or SyncBar): pan the frame it rides. The loop this could form
-        -- (bar → scroll → OnVerticalScroll → SyncBar → bar) dead-ends in one hop — SyncBar writes the
-        -- value the bar already holds, and the Slider's SetValue change-gate (decision 0250) drops it.
+        -- 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.
         function BenillaScrollBar_OnValueChanged(bar, value)
             bar:GetParent():SetVerticalScroll(value)
             BenillaScrollBar_UpdateArrows(bar)
         end
 
-        -- Reconcile a ScrollFrame's bar to its live range (ref ScrollFrame_OnScrollRangeChanged):
-        -- the bar spans [0, range] in pixels, seats at the current scroll, and hides entirely when
-        -- the content fits. Wired to both OnScrollRangeChanged and OnVerticalScroll by the owner.
+        -- 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.
         function BenillaScroll_SyncBar(sf)
             local bar = getglobal(sf:GetName() .. "Bar")
             if not bar then return end
@@ -220,10 +128,8 @@
             BenillaScrollBar_SetShown(bar, range > 0)
         end
 
-        -- Pan by `delta` px, clamped to [0, range] HERE: the engine's SetVerticalScroll stores
-        -- what it is given (decision 2017 — the reference's never reads the range), and the
-        -- reference's own wheel handler bounds itself the same way, through its bar's [min, max]
-        -- (ScrollFrameTemplate_OnMouseWheel → scrollBar:SetValue).
+        -- 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.
         function BenillaScroll_Step(sf, delta)
             local target = sf:GetVerticalScroll() + delta
             local range = sf:GetVerticalScrollRange()
@@ -233,13 +139,12 @@
             BenillaScroll_SyncBar(sf)
         end
 
-        -- WoW wheel convention: +1 per notch up, -1 down — up lifts the content.
+        -- The wheel's delta is +1 per notch up, and up scrolls toward the top.
         function BenillaScroll_OnMouseWheel(sf, delta)
             BenillaScroll_Step(sf, -delta * BENILLA_SCROLL_STEP)
         end
 
-        -- A widget's resolved bottom edge for the content sum — nil when it isn't contributing
-        -- (hidden frame / blank FontString / not yet resolved this frame).
+        -- A widget's resolved bottom, or 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
@@ -251,19 +156,13 @@
             return w:GetBottom()
         end
 
-        -- Size a scroll child to its MEASURED content — the resolved bottom of the lowest visible
-        -- widget, plus padding — instead of a fixed budget, and tell the frame (which fires
-        -- OnScrollRangeChanged → the owner's SyncBar). Frame-late by nature: rects resolve after Lua
-        -- runs, so owners re-run this from an OnUpdate until it stops changing. Returns true when it
-        -- actually resized (only a real change writes: SetHeight invalidates layout, and an
-        -- every-frame write would fight the resolver).
+        -- 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.
         function BenillaScroll_ResizeChild(scrollName, widgets)
             local sf = getglobal(scrollName)
-            -- ASK THE FRAME, don't guess a name. This used to be
-            -- `getglobal(scrollName .. "Child")`, which only ever worked because every caller wore
-            -- a private name in that exact shape — the reference's own convention is
-            -- `<X>ScrollFrame` / `<X>ScrollChildFrame`, not a suffix, so the derivation broke the
-            -- moment QuestFrame took the reference's names. A ScrollFrame knows its own child.
+            -- The frame's own child, 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()
@@ -284,11 +183,9 @@
     ]]></Script>
 
     <!--
-        The scroll bar: a `Slider` (0250) 16px wide, its up/down step buttons pinned above/below the
-        track, and the knob thumb. The value is in pixels (see the header); the thumb draws at the
-        value fraction along the track (engine-side, decision 0250 §4), draggable (§5). The step-button
-        + knob art is the stock 1.12 scrollbar kit, each texture cropped to its centred 16px (the
-        `0.25..0.75` TexCoords the ref's `UIPanelScrollBarButton` applies).
+        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`).
     -->
     <Slider name="BenillaScrollBarTemplate" virtual="true">
         <Size><AbsDimension x="16" y="0"/></Size>
@@ -322,39 +219,24 @@
     </Slider>
 
     <!--
-        The scroll bar's TROUGH — the recessed channel the bar rides in: the "background and
-        border" a bare arrows+knob bar is missing. An owner declares one of these BESIDE its bar,
-        named `<barname>Trough` and WITH NO ANCHORS — it seats itself on the bar the first time
-        BenillaScrollBar_SetShown touches it (BenillaScrollTrough_Seat above, where the socket law
-        and the ref citations live). Declare it BEFORE the bar so it draws beneath.
-
-        THE ART, and why it is sliced this way. `Interface\PaperDollInfoFrame\UI-Character-ScrollBar`
-        is a 64x256 sheet holding TWO 31-wide channel pieces, measured texel-exact from the file —
-        rails at x 2-5 and 25-30 with a 19-wide interior between them, and each piece bearing a
-        16-tall SOCKET for its arrow button:
-          · LEFT column (u 0 .. 31/64): rows 0-3 the solid TOP cap, 4-19 the up-arrow socket,
-            20-21 the crossbar that closes it, then plain channel from row 22 to the bottom edge.
-          · RIGHT column (u 33/64 .. 1): plain channel, then rows 85-86 the crossbar, 87-102 the
-            down-arrow socket, 104-106 the solid BOTTOM cap (nothing below 107).
-        The ref composes a trough from exactly two quads — the whole left column plus the right
-        column's bottom 108 rows — which reaches 362 units and no further, and only works because
-        its scroll frames are short enough for the two to OVERLAP. Ours must span a 563-tall page,
-        so the same art is cut as a THREE-SLICE instead: the two socket ends at their natural
-        heights and a plain-channel slice stretched between them. The middle is constant down its
-        whole length, so stretching it is exact — there is no seam to find.
-
-        The black `Fill` is the ref's own trough backing, not an invention: ItemTextFrame draws a
-        0.8-alpha black quad behind its channel art for exactly this (ref-ItemTextFrame.xml's
-        `Middle`). It sits in BACKGROUND and the channel art in BORDER — two layers, because within
-        ONE layer the client re-sorts overlapping quads by texture handle and their order is not
-        ours to depend on (order.rs). The bar's own furniture stays clear above both: button state
-        textures are ARTWORK, the knob is OVERLAY.
+        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.
     -->
     <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, i.e. inset 6 from each edge. -->
+                <!-- The channel interior: x 6..24 of the 31-wide piece, inset 6 from each edge. -->
                 <Texture name="$parentFill">
                     <Anchors>
                         <Anchor point="TOPLEFT"><Offset><AbsDimension x="6" y="0"/></Offset></Anchor>
@@ -374,9 +256,7 @@
                     <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) — the mirror of the top's 23, cut to put row 107 on the
-                     trough's bottom edge exactly as ReputationFrame's own 108/0.421875 does, which
-                     is what lands the socket on the arrow (BenillaScrollTrough_Seat's law). -->
+                     (v 82/256 .. 108/256), ending on v 0.421875 as ReputationFrame's does. -->
                 <Texture name="$parentBottom" file="Interface\PaperDollInfoFrame\UI-Character-ScrollBar">
                     <Size><AbsDimension y="26"/></Size>
                     <Anchors>
@@ -386,8 +266,7 @@
                     <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 because it anchors to the two above by name, and an anchor whose
-                     target is declared later falls back to the parent (ItemTextFrame's own note). -->
+                     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"/>
@@ -399,22 +278,4 @@
         </Layers>
     </Frame>
 
-    <!-- ══ Carried here from UiPanels.xml when that file went stock (decision 1988) ══
-         The placeholder icon our UIParent.lua counterpart held and the reference's does not,
-         seated in the earliest file of ours every consumer loads after. The window tab template
-         and its settle stood here too until 1993 put them on the chain. -->
-    <Script><![CDATA[
-        -- The placeholder icon for an item/spell whose texture has not arrived yet (Craft, Quest,
-        -- QuestLog, Trainer and TradeSkill read it). Was ActionBar.xml's (stock since 1938), then
-        -- UiPanels.xml's (stock since 1988); this file is the earliest of ours every reader loads
-        -- after. A benilla name, so nothing stock reads it.
-        BENILLA_FALLBACK_ICON = "Interface\\Icons\\INV_Misc_QuestionMark"
-    ]]></Script>
-
-    <!-- `FauxScrollFrameTemplate` and the `FauxScrollFrame_*`/`ScrollFrame_*`/`ScrollingEdit_*`
-         API are the REFERENCE's, off the player's chain (`Interface\FrameXML\UIPanelTemplates`,
-         seated below this file — so its declarations win). Our transcriptions stood here dead
-         from the day that entry landed and are gone (1860). What stays is
-         `BenillaScrollBarTemplate` + `BenillaScrollTroughTemplate` and their helpers, which are
-         ours: six windows inherit the bar directly and the reference has no trough at all. -->
 </Ui>
diff --git a/crates/benilla-app/assets/ui/SpellBookAdapters.xml b/crates/benilla-app/assets/ui/SpellBookAdapters.xml
index 80dfc700..b9173803 100644
--- a/crates/benilla-app/assets/ui/SpellBookAdapters.xml
+++ b/crates/benilla-app/assets/ui/SpellBookAdapters.xml
@@ -1,27 +1,13 @@
 <Ui>
     <!--
-        BENILLA_ALLOW_OWN_UI=1 — the director's two LOOK deviations on the pet page's autocast
-        button, over the reference's own SpellBookFrame.xml (decisions 1392/1393; re-seated by 2014
-        onto the reference's own Model now that this engine renders it — 2013).
-
-        Since 2013 the `$parentAutoCast` <Model> on every SpellButton draws its own file
-        (Interface\Buttons\UI-AutoCastButton.mdx) as a tile: four bones chasing the corners of a
-        0.02-unit square, four spline emitters trailing GlowStar sparks off them, on the pane's own
-        clock. The reference declares it 36x36 at CENTER (1,1) at scale 1.22 — a 0.87x rim that
-        floats clear of the viewport edge, never clipped, washing the icon; the real 1.12 client
-        looks the same way (director-checked, 1392), so this is taste, not fidelity, and the
-        director chose the pet button's proportions instead:
-
-        · the shine pane squared on the button — 37x37 at CENTER (0,0), scale 1.48 — so the rim
-          runs ON the viewport edge (1.024x, the pet button's own ratio) and the tile's cell, the
-          widget's own scissor, halves every star; and so the glow and the brackets share a centre
-          (1393's "top and right are off" was the reference's own +1,+1);
-        · the corner brackets at 71.53 rather than the reference's 60 — the art fills 33/64 of
-          UI-AutoCastableOverlay.blp, and 71.53 = 37 x 58/30 puts the bracket square on this
-          button's corners at the pet button's 0.997x.
-
-        Reverting the widget to 1.12 exactly is: overlay 60, pane 36x36 CENTER (1,1), scale 1.22 —
-        i.e. deleting this file. Nothing else here: the reference's file is sourced unedited.
+        BENILLA_ALLOW_OWN_UI=1. 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.
     -->
     <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 5ee18e5d..0fe1a559 100644
--- a/crates/benilla-app/assets/ui/benilla.toc
+++ b/crates/benilla-app/assets/ui/benilla.toc
@@ -1,1285 +1,187 @@
-# benilla.toc — the built-in interface, as an ordinary addon manifest.
-#
-# The reference's own interface ships as `FrameXML.toc`; ours was a hand-ordered Rust array until
-# decision 1178. It is parsed by the same `.toc` parser any third-party addon will be
-# (`benilla-ui/src/toc.rs`), and that is the point: a privileged built-in UI is how addon support
-# rots. If our own interface loads through the addon path, the addon path works — it is exercised
-# by every single run. If it keeps a private door, that path is untested by construction.
-#
-# The order is LOAD order and it is load-bearing: a template must be defined before the frame that
-# inherits it, and a later file paints on top of an earlier one. Every entry's comment is why it
-# sits where it sits; those comments are knowledge, not decoration.
-#
-# The FIRST entry is the font-object registry, and the loader splits there: it alone loads at
-# startup, ahead of the glue screens that share our one glyph atlas, and everything after it
-# materializes on entering the world (decision 1051).
-#
-# ── TWO STORES, ONE LIST (decision 1751) ──────────────────────────────────────────────────────
-# A **bare filename** is a file we ship, from `assets/ui` (compiled into the binary, 1175).
-# A **path** — `Interface\FrameXML\ContainerFrame.xml` — is the reference's OWN file, executed off
-# the player's installed patch chain. Nothing of Blizzard's is copied here; the player runs the
-# file they already own, and it cannot drift from itself.
-#
-# That is the end state for this interface: the stock 1.12 FrameXML, off the player's chain, and
-# `assets/ui` is scaffolding that retires window by window. Migrating one is one line here changing
-# from ours to theirs, plus the deletion of our copy — which is why the two stores share ONE
-# ordered list instead of the reference getting a private "load everything first" pass. It could
-# not have that pass: stock `ContainerFrame.xml` inherits `ItemButtonTemplate`,
-# `CooldownFrameTemplate`, `SmallMoneyFrameTemplate` and `UIPanelCloseButton`, so it has to sit
-# after the files that declare them, exactly like any other entry.
-#
-# Order still decides every collision, in both directions. A reference file sourced ABOVE ours has
-# its colliding globals overwritten by ours (that is why `PaperDollFrame.lua` is where it is); a
-# reference file sourced AT the position of the window it replaces owns its names outright, which
-# is what migrating a window means. `ui_script::reference_ui` is the rule; this list is the order.
+# 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.
 
 ## Interface: 11200
 ## Title: benilla
 
-# The named virtual Font objects (decision 0084) — must load first so any FontString's
-# `inherits="GameFontNormal"` resolves against a registered object.
-# ══ THE FONT REGISTRY — the reference's own, off the player's chain (1751, 1888) ══
-# All 51 `<Font>` objects, name for name, plus the colour codes, `CHAT_FONT_HEIGHTS`,
-# `MATERIAL_TEXT_COLOR_TABLE`, `MATERIAL_TITLETEXT_COLOR_TABLE` and `RAID_CLASS_COLORS`.
-# Ours was a transcription differing only in formatting (it inlined `<FontHeight>`), plus one
-# addition: `ITEM_QUALITY_COLORS`, whose reference home is `UIParent.lua` and which 1888 moved
-# to our UIParent.xml so it survives this swap.
 Interface\FrameXML\Fonts.xml
 
-# ══ THE STRINGS — the reference's own first line, seated second here (1848) ══
-# **Second, not first, and that is deliberate.** Manifest entry 0 is the FONT REGISTRY:
-# `load_font_registry` takes entry 0 and `load_ingame_ui` takes the rest, so entry 0 is the boot
-# boundary itself (1051). Putting the strings there would move `Fonts.xml` across it.
-# `GlobalStrings.lua` is line 1 of the reference's `FrameXML.toc`, and it was missing from ours
-# entirely: the app loaded it out of band at Startup (`ui_script::setup_script`, "the VM's first
-# load is the real GlobalStrings.lua"), so the running client was right and the MANIFEST was not
-# self-sufficient. Every harness that loads the manifest without that pre-step got a VM with no
-# strings, which is a gap four separate windows tripped over before anyone looked at the toc.
-#
-# The stock files read these at LOAD, not just at paint: `Blizzard_MacroUI.xml`'s character tab
-# does `format(CHARACTER_SPECIFIC_MACROS, UnitName("player"))` inside its own OnLoad, and a nil
-# format string there aborts the handler.
-#
-# The app's Startup load stays where it is — the cast-fail display (0427) resolves messages before
-# the in-game UI materializes at all (1051) — so this is a second, idempotent assignment pass.
+# 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.
 Interface\FrameXML\GlobalStrings.lua
-# ══ THE LOCALE ADJUSTMENTS — the reference's own, off the player's chain (1751, window 5) ══
-# `Localize()` (which this file also CALLS at load, exactly as the reference's own two-part
-# `<Script>` does) and `LocalizeFrames()`. Nothing of ours ever shipped either, and the gap was
-# recorded in two places: `GameTime.xml` set `TwentyFourHourTime = 1` itself with a note saying the
-# reference sets it in `LocalizeFrames`, and `HelpFrame.xml` names a whole family of strings that
-# "`LocalizeFrames()`, which benilla does not ship, so it never fired here either" would have set.
-#
-# It is the reference's own slot (FrameXML.toc l.3, straight after Fonts.xml) and the order is the
-# point: `Localize` overwrites `GlobalStrings.lua` keys, and GlobalStrings is loaded ahead of this
-# whole manifest at VM setup (`ui_script/mod.rs`) — which is FrameXML.toc l.1, so the two land in
-# the reference's own order. The file it patches is the PLAYER'S, so the locale is theirs by
-# construction rather than ours to guess.
-#
-# `LocalizeFrames()` is called from `UIParent_OnEvent`'s VARIABLES_LOADED arm — the reference's own
-# caller (UIParent.lua l.230-235), added to our UIParent.xml with this window.
+# `Localize()` runs at load and overwrites GlobalStrings keys, so this follows them.
 Interface\FrameXML\Localization.xml
-# ══ THE LOCALE LOOKUP — the reference's own, off the player's chain (1751, window 19) ══
-# `GetText(token, gender, ordinal)` and its three helpers (`GetPluralIndex`/`GetPluralTag`/
-# `GetGenderTag`) plus `GenderTagInfo` / `MAX_GENDER_INDICES` / `MAX_PLURAL_INDICES`.
-#
-# It is a `.lua` entry because the reference has no XML for it: 1.12 pulls it in through
-# `<Script file="LocaleProperties.lua"/>` at the top of `UIParent.xml`, and until that window
-# migrates this is where it comes from.
-#
-# WORTH KNOWING, because it saved building the wrong thing: `GetText` LOOKS like an engine binding
-# — `reference/1.12-globals.tsv` has it, and the exe's `FrameScript_GetText 0x703bf0` is a real
-# function — but the exe's one CALLS this Lua global. So there is nothing to implement; the whole
-# selector is fifty lines of FrameXML, and sourcing them is the entire fix. It composes a suffix
-# from the gender (`_FEMALE` at 3, and five more tags 1.12 never uses in enGB) and the plural
-# (`_P1` for any ordinal that is not 1), then falls back suffix-by-suffix to the bare token.
-#
-# The reputation page is what needed it — `ReputationFrame.lua:65` reads its standing
-# words with `GetText("FACTION_STANDING_LABEL"..id, gender)` — and fourteen more call sites across
-# FriendsFrame, StaticPopup and the quest windows are waiting behind it.
+# `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.
 Interface\FrameXML\LocaleProperties.lua
-# The reference's own second file, in its own position: TEXT/message/_ERRORMESSAGE, the
-# ScriptErrors dialog, and the DialogBoxFrame + DialogButton*Texture kit it is built from.
-# Straight after Fonts.xml because those are the only things it needs (GameFontRedLarge,
-# DialogButtonNormalText/HighlightText) and everything above it in FrameXML.toc is engine.
 Interface\FrameXML\BasicControls.xml
-# **UIParent itself, and it must come before every frame that declares `parent="UIParent"`** —
-# a parent name is resolved at LOAD, and a name that does not exist yet does not error: the loader
-# warns and silently falls back to the enclosing frame (`loader/mod.rs`, "names no frame"). With
-# this file at its old position below UiPanels.xml, `StaticPopup1`/`StaticPopup2` would have taken
-# that fallback and the reparent would have been a silent half-fix.
-#
-# This is the reference's own slot: FrameXML.toc has BasicControls.xml at l.6 and UIParent.xml at
-# l.8, above MoneyFrame.xml (l.10) and StaticPopup.xml (l.23). It needs nothing from the files it
-# now precedes — it declares only UIParent and WorldFrame, inherits no template, and its scripts
-# (UIPARENT_MANAGED_FRAME_POSITIONS + UIParent_ManageFramePositions, decision 0272, the ref
-# mechanism that re-anchors the cast bar / chat over the bottom bars) are called later, applied by
-# the loader's post-load bootstrap (ui_script/manifest.rs).
-# ══ THE WORLD FRAME — the reference's own, off the player's chain (1751; decision 1983) ══
-# WorldFrame.xml + WorldFrame.lua: the <WorldFrame> singleton (the engine's own kind, mouse-enabled
-# by construction, its hits the world's), the framerate readout ToggleFramerate/TOGGLEFPS drives
-# off GetFramerate, the OnUpdate that ticks StaticPopup and MirrorTimer frames while the UI is
-# hidden, and the ScreenshotStatus child ("Screen Captured" over SCREENSHOT_SUCCEEDED/FAILED,
-# the 1.5 s GetTime fade, TakeScreenshot for the SCREENSHOT binding). Right above UIParent.xml as
-# the reference's toc has it (l.7-8). Needs Fonts.xml's SystemFont above; everything else it
-# names is call-time.
+# Before UIParent.xml, whose `LowHealthFrame` has `parent="WorldFrame"`.
 Interface\FrameXML\WorldFrame.xml
-# UIParent itself and its Lua — the reference's own file (1751; decision 1988), at the slot its
-# toc gives it (l.8, right after BasicControls). UIParent.lua is the whole of the glue this
-# engine used to carry as UIParent.xml + UiPanels.xml: the UIPanelWindows table and the slot
-# manager (Show/HideUIPanel, CloseAllWindows, ToggleGameMenu's ESC ladder), the fade/flash/pulse
-# kits (ticked from UIParent's own OnUpdate, so the three driver frames of ours retired with
-# it), the managed bottom-stack positions, the model turntable, the LoadOnDemand shims, and the
-# sixty-six globally-routed events and their arms. It sources LocaleProperties.lua itself. Its
-# OnUpdate also ticks FCF_OnUpdate, UnitPopup_OnUpdate, BattlefieldFrame_OnUpdate, the
-# battlefield-position ask (1980) and the ready-check timeout (1989) — call-time names, all of
-# them below. LowHealthFrame (parent WorldFrame, above) and OutOfControlFrame ride along —
-# created hidden and never shown: the one function that would flash them, PlayerStatus_OnUpdate,
-# has no caller in the image or the chain (wow-re, decision 1999). Dead code in 5875, kept as
-# the reference keeps it.
-# What stayed ours moved out: the placeholder icon (ScrollTemplates.xml; the window tab template
-# and its settle went with it and are the chain's since 1993), 0561's bag verbs (ContainerFrameAdapters.xml), the script log's row
-# (ScriptLogFrame.xml). The three aliases OptionsFrame.xml used to carry for the reference's three
-# options windows and its Cancel button are all gone: each of those four names is a REAL frame off
-# the chain now (2115, 2147, 2177), and the last of them — the video window's `OptionsFrame` — is
-# why our own window is `BenillaOptionsFrame`.
+# 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
-# ══ THE ITEM-SLOT BASE — the reference's own, off the player's chain (1751, window 24) ══
-# `ItemButtonTemplate` and the eight `SetItemButton*` verbs out of `ItemButtonTemplate.lua`. It
-# sits as early as it can be read: no frames, no dependencies of its own, and every window that
-# paints an item slot inherits or calls it — ours and third-party alike. Their absence is what left
-# the director's Bagnon window with a title, a gold line and no bag slots at all.
-#
-# Our copy called the reference's file "the specification" in its own header and re-implemented the
-# eight verbs against it; the specification is now the thing that runs. The template's regions and
-# size are identical either way (`$parentIconTexture` / `$parentCount` / `$parentStock` /
-# `$parentNormalTexture`, 37x37) — which is what makes this the safest of the foundational swaps
-# rather than the widest: everything that inherits it asks for the same four names.
 Interface\FrameXML\ItemButtonTemplate.xml
-# ══ THE MONEY KIT — the reference's own, off the player's chain (1751; decision 1962) ══
-# MoneyFrame.lua + MoneyFrame.xml (two rows: the .xml sources no .lua): MoneyTypeInfo, the
-# MoneyFrame_* API, MoneyFrameTemplate / SmallMoneyFrameTemplate. Needs only Fonts, and must come
-# BEFORE the dialog engine (StaticPopup's coin row inherits SmallMoneyFrameTemplate at LOAD), which
-# is the reference's own order too (FrameXML.toc l.9-10 against l.23). The money CURSOR family the
-# kit's PickupFunc/DropFunc rows drive (PickupPlayerMoney, DropCursorMoney, GetCursorMoney, the
-# trade and send-mail pairs) is this engine's now. 1190's transcription is gone.
+# Before GameTooltip.xml and StaticPopup.xml, whose money rows inherit `SmallMoneyFrameTemplate`.
 Interface\FrameXML\MoneyFrame.lua
 Interface\FrameXML\MoneyFrame.xml
-# ══ THE MONEY INPUT KIT — the reference's own, off the player's chain (1751, window 23) ══
-# `MoneyInputFrameTemplate` and the ten `MoneyInputFrame_*` verbs out of `MoneyInputFrame.lua` —
-# the three-box gold/silver/copper editor a player types an amount into. Nothing of ours ever
-# shipped it, and it declares no frames, so this is a pure addition: a template and ten globals.
-#
-# THE REFERENCE'S OWN SLOT, straight after MoneyFrame.xml (FrameXML.toc l.9-10) and for the same
-# reason ours is here — the coin art and `MONEY_ICON_WIDTH` family it lays its boxes out against.
-#
-# It is groundwork rather than a window, and the windows it is groundwork FOR are named so the
-# next session does not have to re-derive it: stock `TradeFrame.xml` and `MailFrame.xml` both build
-# their amount entry from this template and call `MoneyInputFrame_SetMode`/`_GetCopper`/
-# `_SetCopper`/`_ClearFocus`/`_SetTextColor`/`_SetOnvalueChangedFunc` — six of the names below.
-# Both windows are migrated now: `MailFrame.xml` at l.897 and `TradeFrame.xml` at l.906, the
-# latter once 1966 bound the four engine verbs it also needed (`AddTradeMoney`,
-# `GetCursorMoney`, `GetTradePlayerItemLink`, `GetTradeTargetItemLink`).
-#
-# **TWO entries, and the `.lua` was missing.** This `.xml` declares only the template and does not
-# source its `.lua`; the reference's toc lists both (l.11-12). Listing the `.xml` alone brought the
-# template and none of the ten verbs — the header above has claimed otherwise since the day it was
-# written, and a probe of a full manifest load answered `nil` for every one of them. Same shape as
-# `TextStatusBar`, found by sweeping every chain entry for it once that one bit;
-# `every_chain_xml_brings_its_own_lua` is now a gate so neither can recur.
 Interface\FrameXML\MoneyInputFrame.lua
 Interface\FrameXML\MoneyInputFrame.xml
-# ══ THE TOOLTIP — the reference's own, off the player's chain (1751; decision 1968) ══
-# GameTooltip.xml sources HealthBar.lua and GameTooltip.lua and <Include>s GameTooltipTemplate.xml:
-# the two virtual templates (GameTooltipTemplate, ShoppingTooltipTemplate — thirty declared line
-# pairs each, the status bar, the money row), the GameTooltip / ShoppingTooltip1 / ShoppingTooltip2
-# instances and SmallTextTooltip. The widget itself is this engine's (0274); every verb the file
-# calls was already bound. Its slot is the reference's own: FrameXML.toc l.13, after MoneyFrame
-# (l.9-10, `SmallMoneyFrameTemplate` resolves at load) and before the panel kit. The order
-# requirement the old header named still holds: ItemRef.xml below expands GameTooltipTemplate,
-# and so do the 27 corpus addons that name it in an XML inherits=.
-#
-# What our transcription carried that the reference does not, and where each went (1968): the
-# `$parentThicken` plate fill (a look deviation, retired — the plate is the reference's art);
-# `SHOW_NEWBIE_TIPS`'s default, which is UIOptionsFrame.lua's and sits in OptionsFrame.xml's uvar
-# block with its family; `FACTION_BAR_COLORS`' fallback table — the reference's is
-# ReputationFrame.lua's, on the chain below; `NUM_SHOPPING_TOOLTIPS` — PaperDollFrame.lua's.
 Interface\FrameXML\GameTooltip.xml
-# ══ THE DROPDOWN KIT — the reference's own, off the player's chain (1751) ══
-# UIDropDownMenuTemplate + the DropDownList frames + the whole `UIDropDownMenu_*` API — before its
-# first customers (the unit popups below, the world map's pickers, the trainer filter). The stock
-# file pulls its own `UIDropDownMenu.lua` and `<Include>`s UIDropDownMenuTemplates.xml, so this one
-# line carries all three. We also gain `DropDownList3`, which our transcription stopped short of.
-#
-# Ours (0203 phase 2, widened for 0434 phase 5) defined every stock global plus six helpers of its
-# own. Five were named nowhere outside the file. The sixth, `CloseMenus`, moved to UiPanels.xml —
-# the reference keeps it in `UIParent.lua`, not its dropdown file, and UiPanels is both where our
-# slice of UIParent.lua lives and ahead of all five of its consumers.
 Interface\FrameXML\UIDropDownMenu.xml
-# ══ THE UIMenu KIT — the reference's own, off the player's chain (1751, window 21) ══
-# `UIMenuTemplate` and `UIMenuButtonTemplate`, with `UIMenu.lua`'s `UIMenu_OnShow`/`_OnUpdate` and
-# the four `UIMenuButton_*` handlers arriving through the file's own `<Script file=>`.
-#
-# The kit was a block inside our ChatFrame.xml — a transcription that kept the reference's names
-# for the addon surface and said so, and whose own note recorded a divergence it had to make (the
-# row label authored LEFT-anchored, because the reference leans on 1.12's ButtonText default rect
-# and our lazy label slot did not reproduce it).
-#
-# **Sourcing the file retired only the XML half, and this header claimed both for months.** The ten
-# `UIMenu_*`/`UIMenuButton_*` functions stayed in ChatFrame.xml under the reference's own names, and
-# that file loads at 939 — so OURS overwrote the chain's from the day this entry landed, the reverse
-# of 1855's direction and just as silent. They are gone now; the kit is the reference's end to end
-# (1869).
-#
-# THE POSITION is the reference's own (FrameXML.toc l.12, straight after GameTooltip.xml, which it
-# needs for the tooltip backdrop its menu wears). Far above ChatFrame.xml, which is the one thing
-# that used it here — resolved at load, and now satisfied earlier rather than in the same file.
 Interface\FrameXML\UIMenu.xml
-# ══ THE UNIT MENUS — the reference's own, off the player's chain (1751; decision 1958) ══
-# UnitPopup.xml + UnitPopup.lua: UnitPopupButtons/Menus and UnitPopup_ShowMenu, the nine menus
-# and every row's facts — after the dropdown kit it drives (its own position, FrameXML.toc
-# l.16), before the unit/party frames whose DropDown children's OnLoad initialize into it. Its
-# enable pass runs from UIParent's OnUpdate line, the reference's own hook. 0434's
-# transcription is gone.
+# Before the unit frames: their dropdowns' OnLoad runs `UIDropDownMenu_Initialize`, whose
+# initializer calls `UnitPopup_ShowMenu` at once.
 Interface\FrameXML\UnitPopup.xml
-# ══ THE CHAT-LINK TOOLTIP — the reference's own, off the player's chain (1751, window 6) ══
-# `SetItemRef` (the chat-link click router) and `ItemRefTooltip` / `ItemRefCloseButton`.
-#
-# THE POSITION IS THE REQUIREMENT: `inherits="GameTooltipTemplate"` is resolved at LOAD, so this
-# sits below GameTooltip.xml. The dropdown kit and UnitPopup above it are a call-time need only,
-# but the reference's own TOC has the same shape and the order costs nothing.
-#
-# THREE THINGS OUR COPY CARRIED THAT THE REFERENCE'S DOES NOT, each moved to the reference's own
-# home rather than deleted:
-# · `FriendsFrame_ShowDropdown` + its initializer, and the `FriendsDropDown` frame they toggle.
-#   1.12 keeps all three in `FriendsFrame.lua`/`.xml`; ours had a second private copy here because
-#   nothing else called them. FriendsFrame.xml (far below) owns the one body now and publishes the
-#   reference's name over it — resolved at call time, so the order does not bind.
-# · `ValidateFramePosition`, which the sourced `ItemRef.xml`'s OnDragStop calls (l.48). It lives in
-#   `UIParent.lua` in 1.12, so it is transcribed into our UIParent.xml with this window.
-# · Two divergences in `SetItemRef` itself, both now the reference's own body: the shift-click arm
-#   fills a visible ADD_IGNORE/ADD_FRIEND/ADD_GUILDMEMBER/ADD_RAIDMEMBER popup's editbox before it
-#   considers the chat box, and falls through to `SendWho("n-"..name)`. Ours guarded both away as
-#   "the friends/who arc, deferred"; `StaticPopup_Visible` and `SendWho` both exist, so the guards
-#   were outliving their reason.
-#
-# AND ONE THING IT GAINS: the reference's tooltip is `movable` and drag-armed, so a chat-link
-# tooltip can be dragged off the middle of the screen. Ours declared "benilla has no
-# user-moved-frame affordance yet" — `StartMoving`/`StopMovingOrSizing` are bindings
-# (`script/object/movable.rs`), so that note was stale too.
 Interface\FrameXML\ItemRef.xml
-# The shared status-bar numerals machinery (decision 1082): TextStatusBar_* + the opt-in
-# template. The ref's own TOC loads TextStatusBar right before its unit frames, same seat.
-#
-# ══ THE STATUS-BAR NUMERALS — the reference's own, off the player's chain (1751) ═══════════
-# `TextStatusBar_*` + the `TextStatusBar` template. The reference's own toc loads it right
-# before its unit frames; this is the same seat.
-#
-# Nothing of ours inherits the template — it exists for the reference's windows, whose rows
-# carry `inherits="TextStatusBar"` and would have found ours. What blocked the swap was a
-# signature WE widened (`TextStatusBar_Initialize`), fixed by giving our own bars the OnLoad
-# the reference's have.
-#
-# **TWO entries, because the reference has two** (its toc l.32-33). This `.xml` declares only the
-# template and does NOT source its `.lua` — unlike most stock windows, whose `<Script file=>`
-# brings their code in. Listing the `.xml` alone loads a template whose OnLoad calls a function
-# nothing defined: every `TextStatusBar_*` name reads nil, every guarded call is a silent no-op,
-# and the numerals simply never appear. The `.lua` comes first, as it does there.
+# The `TextStatusBar` template and verbs, which the unit bars and `MainMenuExpBar` inherit.
 Interface\FrameXML\TextStatusBar.lua
 Interface\FrameXML\TextStatusBar.xml
-# ══ THE PLAYER AURA BAR — the reference's own, off the player's chain (1751) ══
-# The HUD row of buff/debuff icons under the minimap, driven by the UnitAura feed
-# (`crate::ui_aura`; decisions 0255/0257).
-#
-# FIRST OF THE KIT, which is the reference's own order (its toc: BuffFrame 40, CombatFeedback 41,
-# UnitFrame 43, PlayerFrame 44, PartyFrame 45, TargetFrame 46, PetFrame 47). It has to precede
-# PartyFrame because stock `PartyMemberFrame.lua:60` calls `RefreshBuffs` from each row's OnLoad
-# and `BuffFrame.lua` is where that lives. Ours had BuffFrame below the unit frames; that
-# inversion is gone.
+# Before PartyFrame.xml, whose rows reach `RefreshBuffs` from their OnLoad.
 Interface\FrameXML\BuffFrame.xml
-# ══ THE UNIT-FRAME KIT — the reference's own, off the player's chain (1751, window 22) ══
-# `UnitFrame.xml` declares NO frames — it is a `<Script file="UnitFrame.lua"/>` and nothing else —
-# so it is a pure addition of thirteen globals: `UnitFrame_Initialize`, `_Update`, `_OnEvent`,
-# `_OnEnter`, `_OnLeave`, `_OnUpdate`, `_UpdateManaType`, the `UnitFrameHealthBar_*` /
-# `UnitFrameManaBar_*` pairs, and `GetUnitName`. `UnitFrame_Initialize` is what stock
-# `PlayerFrame.xml`, `TargetFrame.xml`, `PartyFrame.xml` and `PetFrame.xml` each call in their
-# OnLoad.
-#
-# Until the four windows below arrived, our own UnitFrames.xml loaded underneath this and
-# redefined four of the thirteen — `_Update`, `_OnEvent`, `_OnEnter`, `_OnLeave` — so the
-# reference's bodies were dead the whole time and stock party rows would have called OUR update,
-# which indexed a `nameText` the reference's rows do not carry. That file is gone; these are live.
+# Two function-only kits: the unit windows below call `UnitFrame_Initialize` from their OnLoad,
+# and the player and pet frames `CombatFeedback_Initialize`.
 Interface\FrameXML\UnitFrame.xml
-# The same shape and the same reason. `CombatFeedback.xml` declares no frames either: three timing
-# constants plus `CombatFeedback_Initialize` / `_OnCombatEvent` / `_OnUpdate`, the floating
-# hit/miss text a unit frame's portrait carries. Two of the three used to collide with bodies our
-# UnitFrames.xml owned; with that file gone the reference's three are what run.
 Interface\FrameXML\CombatFeedback.xml
-# ── The four unit windows themselves (1751, window 22) ─────────────────────────────────────────
-# `PlayerFrame` + `PlayerStatusGlow` + `PlayerPlayTime` + `PlayerPVPIconHitArea` +
-# `PlayerFrameGroupIndicator` + the dropdown, out of `PlayerFrame.lua`.
 Interface\FrameXML\PlayerFrame.xml
-# `PartyMemberFrame1..4`, `PartyMemberBuffTooltip` and `PartyMemberBackground`, out of
-# `PartyMemberFrame.lua` (decision 0434 phase 2). Its `<Script>` list names `TextStatusBar.lua`
-# a second time, which is the reference's own doing and harmless — the file is idempotent.
-#
-# What moved out of our copy before it went: the PARTY_INVITE dialog and its driver, to
-# UiPanels.xml (StaticPopup.lua l.526, UIParent.lua), and the three raid constants, which
-# RaidFrame.xml already declared — that is the reference's home for them (RaidFrame.lua l.2-4).
 Interface\FrameXML\PartyFrame.xml
-# `TargetFrame`, its texture frame and dropdown, the sixteen debuff and five buff buttons with
-# their three templates, and the whole `TargetofTarget*` family — out of `TargetFrame.lua`, which
-# is also where `MAX_COMBO_POINTS` (l.1) and `SetRaidTargetIconTexture` live. `TargetofTarget_Update`
-# is what OptionsFrame.xml's two ToT settings drive.
 Interface\FrameXML\TargetFrame.xml
-# `PetFrame`, its health/mana bars, `PetFrameHappiness` and the dropdown, out of `PetFrame.lua`.
 Interface\FrameXML\PetFrame.xml
-# ══ THE COMBO-POINT DOTS — the reference's own, off the player's chain (1751, window 10) ══
-# `ComboFrame`, `ComboPoint1..5`, `ComboPointTemplate` and the `ComboPointsFrame_OnEvent` /
-# `ComboPointShineFade*` chain with its five duration constants, out of `ComboFrame.lua`.
-#
-# THE POSITION IS THE REQUIREMENT: `relativeTo="TargetFrame"` is resolved at LOAD, so this sits
-# below TargetFrame.xml. Its fade chain needs UiPanels.xml's `UIFrameFade` family, far above, at
-# call time. `MAX_COMBO_POINTS` comes from TargetFrame.lua now, which is where 1.12 declares it.
+# Anchors `relativeTo="TargetFrame"`.
 Interface\FrameXML\ComboFrame.xml
-# The scrolling combat text is the reference's own `Blizzard_CombatText`, a LoadOnDemand addon
-# off the chain (its toc says so), loaded by the options window when SHOW_COMBAT_TEXT is "1" —
-# at login and on the switch, the reference's own two sites. No row here (decision 1964; 0578's
-# transcription is gone).
-# ── MEASUREMENT (1938): the options window at the reference's slot (FrameXML.toc l.21, before
-#    MainMenuBar l.34) with the four rows it inherits from. ──
-# The faux-scroll kit (decisions 0247/0250/0251): BenillaScrollBarTemplate (the draggable
-# Slider scroll bar) + FauxScrollFrameTemplate + the reference's own FauxScrollFrame_*
-# API (Update/GetOffset/SetOffset/OnVerticalScroll + ScrollFrame_OnLoad) —
-# before its first customer (the trainer list) below.
+# Ours: benilla's scroll kits, for our options window and script log.
 ScrollTemplates.xml
 
-# ══ THE PANEL TEMPLATE KIT — the reference's own, off the player's chain (1751, window 31) ══
-# TWO entries, because the reference splits this kit the way it splits every other: the `.lua`
-# carries the verbs and the `.xml` the templates. Listing the `.xml` alone brings none of the verbs
-# (`every_chain_xml_brings_its_own_lua` is a gate because that already bit twice).
-#
-# ONE swap, THREE of our files, which is why it had to move as a unit and why 1837 measured it
-# before anyone executed it:
-#   * `UIPanelTemplates.xml` — DELETED. Our 18 templates were a strict SUBSET of the reference's,
-#     zero benilla-only additions, so the template half is a pure gain.
-#   * the scroll half of `ScrollTemplates.xml` — `FauxScrollFrameTemplate`, `FauxScrollFrame_*`,
-#     `ScrollFrame_*` — now the chain's. What stays there is `BenillaScrollBarTemplate` and
-#     `BenillaScrollTroughTemplate`, which are ours and which six windows still inherit.
-#   * the `PanelTemplates_*` family out of `UiPanels.xml`.
-#
-# It could not be split: `ScrollTemplates.xml` sits ABOVE this entry, so the chain's
-# `FauxScrollFrameTemplate` lands after ours and wins (registration is last-in). There is no
-# ordering that takes the templates without also taking Faux.
-#
-# GAINED: `TabButtonTemplate`, and the whole `ScrollingEdit_*` family, which we had NOWHERE — that
-# is HelpFrame's named blocker, answered as a side effect. And it unblocks MacroFrame (1835).
 Interface\FrameXML\UIPanelTemplates.lua
 
 Interface\FrameXML\UIPanelTemplates.xml
-# ══ THE STOCK VIDEO OPTIONS WINDOW — loaded, and HIDDEN, in the reference's own l.19 seat ══
-# `FrameXML.toc` l.19, whole: the file, its `<Script file="OptionsFrame.lua"/>` (l.3) and its
-# `<Include file="OptionsFrameTemplates.xml"/>` (l.4), which is why ONE row replaces the three
-# this manifest used to carry. Both of those were explicit rows here while the window itself was
-# not loaded (2115 took the `.lua` for its seven shared helpers and the templates for the kit);
-# the window brings them itself now, in its own order, so a second row for either would re-run a
-# file that has already run.
-#
-# **Why the window is here at all** (decision 2177). The same argument 2115 made for the Interface
-# window and 2147 for the Sound one, and this is the last of the three: an addon that reaches for
-# the reference's video-options names finds REAL frames and real functions, because the file is the
-# player's own. `hidden="true"` on its own main frame is the whole mechanism — nothing of ours
-# shows it, ever. pfUI's `skins/blizzard/options-video.lua` walks `OptionsFrame`,
-# `OptionsFrameHeader`, `OptionsFrameSlider1..9`, `OptionsFrameCheckButton1..18`, the three
-# dropdowns and `OptionsFrameCancel`/`Okay`/`Defaults`; `CT_Viewport` calls `GetScreenResolutions`
-# and `GetCurrentResolution`.
-#
-# **IT TOOK A NAME BACK, and that is the load-bearing part.** This file declares `OptionsFrame`,
-# which was OUR options window's name until 2177. Two frames cannot hold one global, and no load
-# order survives the collision: ours later clobbers the stock frame (pfUI's video skin then strips
-# and re-anchors the window the player opens), ours earlier leaves the skin split across two
-# windows. So our window is `BenillaOptionsFrame` now (`OptionsFrame.xml` below carries the whole
-# argument, plus the three things that were keyed on the old name and had to be restated).
-#
-# **The seat is a requirement three times over**, and it is the reference's own answer to all three:
-#   * `OptionsFrameTemplates.xml` (arriving via the `<Include>`) is a descendant of
-#     UIPanelTemplates — `OptionsCheckButtonTemplate` inherits `UICheckButtonTemplate`,
-#     `OptionsButtonTemplate` inherits `UIPanelButtonTemplate` — so it must land after the row
-#     above, and l.19 after l.17 is exactly that.
-#   * `UIOptionsFrame.xml` (l.21, below) declares `UIOptionsCheckButtonTemplate` as
-#     `inherits="OptionsCheckButtonTemplate"`, resolved at LOAD. l.19 before l.21.
-#   * this file's three dropdowns inherit `UIDropDownMenuTemplate` AND their `<OnLoad>` calls
-#     `UIDropDownMenu_Initialize`, which runs the initializer it is handed immediately
-#     (`UIDropDownMenu.lua` l.48-50). The reference seats `UIDropDownMenu.xml` at l.15 for that
-#     reason; ours is manifest row 14 (l.216), far above.
-#
-# WHAT LOADING IT COSTS, measured rather than assumed — the two `<OnLoad>` paths that run engine
-# verbs on the spot, and nothing else: the resolution dropdown's (`GetCurrentResolution`,
-# `GetScreenResolutions`) and the refresh dropdown's (`GetRefreshRates`, plus `GetCVar("gxRefresh")`
-# — unregistered, so a nil and a warn-once, which `UIDropDownMenu_SetSelectedValue` takes). The
-# multisample dropdown's third path was already answered (2163). Everything else in the file —
-# `OptionsFrame_Load`, `_Save`, `_Cancel`, `_SetDefaults` and the eighteen 2004 hardware toggles —
-# hangs off `<OnShow>` and the three buttons, which nothing of ours reaches.
-#
-# WHAT IT PUBLISHES that we do not, and why each is right:
-#   * `OptionsFrameCheckButtons` / `OptionsFrameSliders` — the video window's own two tables, with
-#     the frames behind them for the first time. `OptionsFrame.xml` below **used to overwrite the
-#     slider table** with three rows of its own and no longer does: those three WERE the
-#     reference's rows 1-3, verbatim, and our Graphics page reads them off the reference's table
-#     now (2177).
-#   * the seven shared `OptionsFrame_Enable/DisableCheckBox` / `…Slider` / `…DropDown` helpers and
-#     `PlayClickSound`, which `UIOptionsFrame.lua` calls and nothing else defines — 2115 took this
-#     `.lua` for them alone, and they arrive the same way, one seat earlier in the file.
-#   * `OPTIONS_FARCLIP_MIN`/`_MAX`, `ANISOTROPIC_VALUES`, `OPTIONS_FRAME_WIDTH` — constants we do
-#     not declare.
+# 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`.
 Interface\FrameXML\OptionsFrame.xml
-# ══ THE STOCK SOUND OPTIONS WINDOW — loaded, and HIDDEN, by 2115's own argument ══════════════
-# The reference's `FrameXML.toc` seats this file at l.20, exactly between the video window (l.19,
-# whose `.lua` is the row above) and the interface window (l.21, the row below). Ours now does too,
-# and the seat is the reference's rather than convenient: `SoundOptionsFrame.xml` inherits
-# `OptionsCheckButtonTemplate` and `OptionsSliderTemplate` from `OptionsFrameTemplates.xml` and
-# `GameMenuButtonTemplate` from `UIPanelTemplates.xml`, both already above.
-#
-# **It brings nothing else with it.** Unlike `UIOptionsFrame.xml`, which `<Include>`s
-# `CharacterFrameTemplates.xml`, this file's only dependency line is its own
-# `<Script file="SoundOptionsFrame.lua"/>`. And nothing below depends on IT — no file on this
-# manifest indexes `SoundOptionsFrameCheckButtons`, so there is no `MultiActionBars`-shaped
-# load-order edge under it the way 2115 §3 had to argue for the interface window.
-#
-# **Zero unbuilt engine verbs**, which is why this is one row and not a project: the whole surface
-# is `Get`/`SetCVar`/`GetCVarDefault`, `getglobal`, `TEXT`, `PlaySound`, `Show`/`HideUIPanel`,
-# `GetBindingKey`/`RunBinding`, `Disable_BagButtons`, `UpdateMicroButtons`, the seven
-# `OptionsFrame_*` helpers the row above already loads, and its own functions. All present.
-#
-# **All eleven CVars it names are registered**, so its `_Load` runs clean — including
-# `slider:SetValue(value.initialValue)`, the shape-A path that raised on the interface window's
-# `cameraYawMoveSpeed`. The three that were missing — `SoundListenerAtCharacter`, `EmoteSounds`,
-# `SoundZoneMusicNoDelay` — are check buttons (nil-safe either way) and were built rather than
-# listed, so this row costs no census entry at all.
-#
-# Its own `hidden="true"` (xml l.18) is the whole mechanism, exactly as for the interface window.
-# Nothing of ours may ever `Show()` it.
 Interface\FrameXML\SoundOptionsFrame.xml
-# ══ THE STOCK INTERFACE OPTIONS WINDOW — loaded, and HIDDEN (decision 2115) ══════════════════
-# **This row is not a migration, and it is the one row in this file where that has to be said.**
-# benilla's own options window is `OptionsFrame.xml` below, and it stays the window the player
-# opens — the director's call, twice (0985, and 1987's "we want to fully own that anyway"). This
-# entry loads the reference's `UIOptionsFrame.xml` **alongside** it, and the stock file's own
-# `hidden="true"` on its main frame is what keeps it off the screen. Nothing of ours may ever
-# `Show()` it.
-#
-# WHY LOAD A WINDOW NOBODY OPENS: because third-party addons reach for it BY NAME. pfUI's
-# `skins/blizzard/options-interface.lua` walks `UIOptionsFrame`, `UIOptionsFrameTab1/2`,
-# `UIOptionsFrameCheckButton1..69`, `UIOptionsFrameSlider1..4`, the four dropdowns and the
-# `BasicOptions*`/`AdvancedOptions*` boxes; its `modules/gui.lua` calls `UIOptionsFrame_Load()`
-# and `UIOptionsFrame_Save()` around a GVAR write. Answering those names with an ALIAS onto our
-# own window (which is what we did until 2115) is worse than answering nothing: the skin's
-# `SetWidth(1024)` lands on the window the player actually opens. Real frames, hidden, is the
-# honest answer — and it is free, because the file is the player's own.
-#
-# IT IS ALSO WHERE THE REFERENCE KEEPS ITS OPTIONS STATE, so loading it retires three duplications
-# our own window carried (2115): `UIOptionsFrame_Init` assigns and `RegisterForSave`s all 30
-# options uvars; `UIOptionsFrameCheckButtons` is declared here — the table stock
-# `MultiActionBars.lua:10` writes five rows into at ITS load, which is why this row must stay
-# above that one; and `UpdateNameplates` is this file's function.
-#
-# SEAT: the reference's own toc l.21, which is exactly here — after the UIPanelTemplates pair
-# (l.16/17) and the widget kit (l.19, above), before StaticPopup (l.23). Load-bearing three ways:
-# `UIOptionsCheckButtonTemplate` inherits the line above; three `GameMenuButtonTemplate` buttons
-# and one `UIPanelCloseButton` come from UIPanelTemplates.xml; and `UIOptionsFrameCheckButtons`
-# must exist before MultiActionBars.xml runs.
-#
-# IT BRINGS `CharacterFrameTemplates.xml` WITH IT, which is why that file has no row of its own
-# any more. The reference gives it no toc line either: this file `<Include>`s it at l.4 ("Need
-# the character tabs here") ahead of its own `<Script file=>`, so `CharacterFrameTabButtonTemplate`
-# — the big tab along the character, vendor and social windows' bottom edge — lands at exactly the
-# position our explicit row used to hold. Its `<OnShow>` fits each tab to its text through
-# `PanelTemplates_TabResize(0)`, which needs UIPanelTemplates.lua above and a SYNCHRONOUS
-# `GetStringWidth` (decision 1993 built that and retired our OnUpdate settle).
+# Inherits `OptionsCheckButtonTemplate`; brings CharacterFrameTemplates.xml and declares
+# `UIOptionsFrameCheckButtons`, which MultiActionBars.lua writes at load.
 Interface\FrameXML\UIOptionsFrame.xml
-# ══ THE DIALOG ENGINE — the reference's own, off the player's chain (1751; decision 1960) ══
-# StaticPopup.xml + StaticPopup.lua: StaticPopupDialogs (all 76 of the reference's entries),
-# StaticPopup_Show/Hide/Visible/Resize/OnUpdate, the four dialog instances, the edit boxes and the
-# money frame. The reference's toc has it at l.23, right after UIPanelTemplates and UIOptionsFrame;
-# here too it sits after UIPanelTemplates — the CloseButton it inherits (UIPanelCloseButton) is that
-# file's, and UIPanelTemplates cannot rise above ScrollTemplates.xml (see above). Everything that
-# registers a dialog of its own (Mail, Auction, the keybindings page) loads below this line. The
-# event arms that raise these dialogs are UIParent.xml's, the reference's own home. 0308's engine,
-# the 37 dialogs UiPanels.xml carried and the seven free-standing dialog files (Death, Duel,
-# QuestShare, EnchantConfirm, BinderConfirm, ConfirmSummon, TalentWipeConfirm) are gone.
+# StaticPopup.lua starts `StaticPopupDialogs` empty: a file that adds a dialog at load follows it.
 Interface\FrameXML\StaticPopup.xml
-# The coin pickup dialog (the reference's toc l.24, right here): shift-click a purse coin and pick
-# how many. Pure gain with the money kit — nothing of ours ever answered `OpenCoinPickupFrame`
-# (decision 1962).
 Interface\FrameXML\CoinPickupFrame.xml
 
-# The Keybindings page MODULE (decision 1008, superseding 0997's standalone window):
-# the templates + script of the Options window's Keybindings category, over the
-# engine's binding table (benilla_ui::script::keybind + crate::bindings — the 1.12
-# GetBinding/SetBinding Lua API). Needs UiPanels (popup engine) and GameTooltip (the
-# character-specific checkbox's hover); MUST load before OptionsFrame.xml, whose
-# Keybindings body inherits these templates and calls this script at OnLoad.
+# Ours: the options window's Keybindings page. Before OptionsFrame.xml, whose Keybindings page
+# inherits these templates and calls this script at OnLoad.
 KeyBindingsPage.xml
 
-# The options window (the 0985 provenance split: 0950's era structure, 0978's
-# 1.12-native art, 0981/0984's 1.14 chrome + working era search, 0989's directed
-# cuts — bare fully-live sliders, no corner X; 0992's dropdown rows + the Nameplates
-# page): the era-shaped `BenillaOptionsFrame` the game menu's Options button opens
-# (`OptionsFrame` is the stock VIDEO window's own name again since 2177). Needs
-# Fonts' objects, UiPanels' panel manager, and UIDropDownMenu's capsule template
-# (all far above); sits right before GameMenuFrame so the menu — which reaches it by
-# name at click time — stays the last, outermost layer.
+# Ours: `BenillaOptionsFrame`, the options window the game menu opens. Its rows read
+# `OptionsFrameSliders` and the option globals the stock windows above set at load.
 OptionsFrame.xml
 
-# ── The action-bar cluster, stock (1938): MainMenuBar.xml before Cooldown.xml as the reference's
-#    toc has it (l.34 → l.36); ActionBarFrame.xml + MultiActionBars.xml right after ActionButtonTemplate.xml
-#    (l.37-39); BonusActionBarFrame.xml — which also declares the shapeshift bar — after PetActionBar.xml
-#    (l.73-74). Replaces ActionBar.xml, MultiBars.xml and StanceBar.xml.
+# Declares `MainMenuBar`, `MainMenuBarArtFrame` and `MainMenuExpBar`, which later files use as a
+# parent or read at load.
 Interface\FrameXML\MainMenuBar.xml
 
-# The cooldown indicator — the reference's own file, off the player's chain (1751; decision
-# 2019): `CooldownFrameTemplate`, a <Model> playing UI-Cooldown-Indicator.mdx whose OnUpdateModel
-# scrubs the sweep and whose OnAnimFinished hides the flash (Cooldown.lua), rendered as a tile
-# (2013) with its four quadrant quads turned by the file's own texture-transform rotation tracks.
-# Before its consumers (the action, multibar, bonus and shapeshift buttons; the bag slots).
 Interface\FrameXML\Cooldown.xml
-# ══ THE ACTION-BUTTON REGIONS — the reference's own, off the player's chain (1751) ══
-# `ActionButtonTemplate`: the REGIONS-ONLY half of the reference's two-level split — icon, count,
-# hotkey, name, border, flash, cooldown and normal texture. It declares NO scripts and calls
-# nothing, so it needs no `.lua` beside it. The handler half is `ActionBarButtonTemplate`, which
-# ActionBarFrame.xml below declares over `ActionButton.lua` (stock since 1938).
-#
-# Ours was a transcription of this exact file — the eight `$parent*` child names match to the
-# letter — so the swap is a deletion.
-#
-# **It must come BEFORE ActionBarFrame.xml**, whose template inherits it by name at load.
+# `ActionButtonTemplate`, which ActionBarFrame.xml's `ActionBarButtonTemplate` inherits.
 Interface\FrameXML\ActionButtonTemplate.xml
 Interface\FrameXML\ActionBarFrame.xml
-# The four OPTIONAL extra bars (bottom left/right 61-72 / 49-60, vertical right/left
-# 25-36 / 37-48), all shipping hidden until the player ticks their row (decision 1500) — the
-# reference's own file, right after ActionBarFrame.xml as its toc has it (l.38-39): it inherits
-# ActionBarButtonTemplate, anchors to ActionButton1, and calls ActionButton_ShowGrid/_HideGrid.
-# Its OnLoad writes five rows of `UIOptionsFrameCheckButtons`, which is why OptionsFrame.xml sits
-# ABOVE this cluster (1938). UIParent.xml (far above) carries the PLAYER_ENTERING_WORLD seed
-# that fills the four SHOW_MULTI_ACTIONBAR_* globals from the server's byte; the manage pass runs
-# from the options rows' setters, as the stock options window runs it on hide.
+# The four optional bars (action slots 25-72), built on `ActionBarButtonTemplate`.
 Interface\FrameXML\MultiActionBars.xml
-# ══ THE PET ACTION BAR — the reference's own, off the player's chain (1751; decision 1953) ══
-# PetActionBarFrame.xml + PetActionBarFrame.lua: the ten buttons over `crate::ui_pet`'s feed
-# (GetPetActionInfo & co., decision 0982's engine), the slide, the grid, the hotkey pass. Right
-# after the stance bar, whose row it shares (UIParent.xml's managed "pet" delta), and after
-# Cooldown.xml, MainMenuBar.xml (its parent), GameTooltip.xml, ActionBarFrame.xml
-# (ActionButton_UpdateState) and UiPanels.xml (SetDesaturation, and where 1066's three
-# right-click dialogs — ABANDON_PET / RENAME_PET / PETRENAMECONFIRM — now live). 0982's
-# transcription is gone.
 Interface\FrameXML\PetActionBarFrame.xml
-# The micro-button row in the bar's right-hand recess — the reference's own file (1751;
-# decision 1987), which its toc seats right after MainMenuBar (l.34-35). After MainMenuBar.xml:
-# the eight buttons carry parent="MainMenuBarArtFrame", resolved by name at load (1734), and a
-# child is born one level above its parent (order.rs; SetParent 0x76ab65) — the seat our retired
-# MicroMenu.xml set by hand. BEFORE the panels it toggles: each of their OnShow/OnHide calls the
-# UpdateMicroButtons this file defines, and that function reads CharacterFrame, SpellBookFrame,
-# QuestLogFrame, GameMenuFrame, OptionsFrame, SoundOptionsFrame, UIOptionsFrame, FriendsFrame,
-# WorldMapFrame, HelpFrame and KeyRingButton UNGUARDED at call time, so every one of them is up
-# before anything can be shown. All three options windows are the reference's own frames now,
-# loaded hidden above — `OptionsFrame` (2177), `SoundOptionsFrame` (2147), `UIOptionsFrame` (2115) —
-# so all three answer, and none of them is ever visible. What that chain CANNOT see is our own
-# window: `GameMenuFrame.xml`, the manifest's last row, wraps `UpdateMicroButtons` to add it.
+# `UpdateMicroButtons` reads CharacterFrame, SpellBookFrame, QuestLogFrame, GameMenuFrame, the
+# three stock options windows, FriendsFrame, WorldMapFrame, HelpFrame and KeyRingButton
+# unguarded, so each must be on this list.
 Interface\FrameXML\MainMenuBarMicroButtons.xml
-# ══ THE BATTLEGROUND LIST + THE MINIMAP CLUSTER — the reference's own, off the player's chain
-# (1751; decision 1974) ══
-# BattlefieldFrame.xml + BattlefieldFrame.lua: the battlemaster's instance list (the "First
-# Available" row, the join and join-as-group buttons) over `crate::ui_battlefield`'s feed and
-# the engine's queue family (GetBattlefieldStatus & co.), and — defined here, consumed by the
-# minimap file below at LOAD time — the minimap queue icon's status pass and its right-click
-# dropdown. The reference's toc seats it right before Minimap.xml (l.29-30) for that reason.
-# After UIDropDownMenu.xml (the dropdown template) and UIPanelTemplates (the buttons, the faux
-# scroll frame).
+# Before Minimap.xml, whose queue dropdown's OnLoad calls `MiniMapBattlefieldDropDown_OnLoad`.
 Interface\FrameXML\BattlefieldFrame.xml
-# Minimap.xml + Minimap.lua: the cluster around the engine-rendered <Minimap> widget hole
-# (`crate::minimap` fills it), the zone text, the zoom buttons, the tracking / mail / meeting
-# stone / battlefield icons, and `MiniMapPing` — a <Model> that renders its own MinimapPing.mdx
-# since 2013; `minimap/ping.rs` keeps the pin, the click seat and the wire half, so the
-# 5 s lifetime is this file's, as the reference's is. After GameTooltip (the zone-text hover).
-# 0203's transcription is gone.
+# GameTime.xml, DurabilityFrame.xml and QuestTimerFrame.xml name `MinimapCluster` at load.
 Interface\FrameXML\Minimap.xml
-# ══ THE TIME-OF-DAY INDICATOR — the reference's own, off the player's chain (1751, window 5) ══
-# `GameTimeFrame`, `GameTimeTexture`, and `GameTime_GetTime` / `GameTimeFrame_Update` /
-# `_UpdateTooltip` / `GAMETIME_DAWN`/`_DUSK` out of `GameTime.lua`. Ours was a re-implementation of
-# the same behaviour under the same published names, and it is deleted.
-#
-# THE POSITION IS THE REQUIREMENT: `parent="MinimapCluster"` is resolved at LOAD, so this sits
-# below MinimapCluster.xml — which is also the reference's own order (its TOC loads GameTime.xml
-# right after Minimap.xml). GameTooltip above it for the hover; the clock itself is the app's
-# `GetGameTime` (`minimap::feed_game_time`), resolved at call time.
-#
-# BOTH of our recorded divergences went away rather than being carried (1751 §2). The `TEXT()`
-# wrapper the ref puts round its format strings is real here now — `BasicControls.xml` defines it.
-# And `TwentyFourHourTime = 1`, which our file set itself with a note saying the reference sets it
-# in `LocalizeFrames`, now comes from exactly there: `Interface\FrameXML\Localization.xml` is
-# sourced at the top of this manifest and `UIParent_OnEvent`'s VARIABLES_LOADED arm calls it. The
-# value is the PLAYER's locale rather than our assumption about it.
 Interface\FrameXML\GameTime.xml
-# ══ THE ZONE SPLASH — the reference's own, off the player's chain (1751, window 8) ══
-# Two files, in the reference's own order and for its own reason.
-#
-# `FadingFrame.lua`'s kit first (`FadingFrame_OnLoad`/`_Show`/`_OnUpdate` and the three
-# `_Set*Time` setters). Our copy inlined it into ZoneText.xml on the argument that
-# ZoneTextFrame/SubZoneTextFrame are its only consumers in the whole 1.12 FrameXML — true, and
-# still the wrong shape once the file could simply be sourced: an addon that wants a fading frame
-# reaches for the kit's published names, not for the splash. The reference gives it its own TOC
-# line (l.25) and so do we. It declares no frames at all — it is a `<Script file=>` and nothing
-# else — so it needs nothing above it.
+# Before ZoneText.xml, whose frames call `FadingFrame_OnLoad` in their OnLoad.
 Interface\FrameXML\FadingFrame.xml
-# …then the splash itself: `ZoneTextFrame` / `SubZoneTextFrame` / `AutoFollowStatus`, `SetZoneText`
-# and the three `Zone*Duration` constants, driven by the ZONE_CHANGED family `crate::area` fires
-# and by AUTOFOLLOW_BEGIN/END. Needs Fonts (ZoneTextFont/SubZoneTextFont) + UIParent, both far
-# above; kept by the minimap cluster, the other consumer of the zone-text host globals.
-#
-# Our copy's own header called its Lua "OURS: our own implementation of the behaviour
-# ref-ZoneText.xml specifies", with the published names and the measurements quoted. The
-# reference's file is that specification, so it replaces it whole — including the
-# `CONTESTED_TERRITORY`/`FACTION_CONTROLLED_TERRITORY`/`FREE_FOR_ALL_TERRITORY`/`AUTOFOLLOW*`
-# strings, which came from ours as `X = X or "…"` fallbacks and now come from the player's own
-# GlobalStrings.lua like every other string in this interface.
 Interface\FrameXML\ZoneText.xml
-# ══ THE COLOUR DIALOG — the reference's own, off the player's chain (1751, window 11) ══
-# `ColorPickerFrame` (a `<ColorSelect>`), `OpacitySliderFrame`, `ColorPickerOkayButton`,
-# `ColorPickerCancelButton`, and the separate `OpacityFrame` beside them. The file ships no `.lua`
-# — its whole script is inline, and the one function that drives it
-# (`UIDropDownMenuButton_OpenColorPicker`) lives in UIDropDownMenu.lua.
-#
-# Last of the "shared FrameXML surface with no benilla consumer yet" cluster that runs from
-# UIPanelTemplates.xml down, and the swap is exactly why that posture was worth holding: **86 of
-# the 218 corpus addons reach this window** (64 of those files are `Dewdrop-2.0.lua`, which drives
-# THIS one rather than rolling its own), and nothing we ship opens it — so every one of them is now
-# talking to the reference's own frames rather than to our re-expression of them.
-#
-# THE SEAT IS A REQUIREMENT, not tidiness: the Okay/Cancel buttons
-# `inherits="GameMenuButtonTemplate"`, resolved at LOAD, and that template lives in
-# UIPanelTemplates.xml far above (it moved there from GameMenuFrame.xml — the reference's own
-# file for it — precisely because GameMenuFrame.xml is deliberately LAST, which is also why this
-# entry does not follow the reference's own position below it). Everything else it needs is far
-# above: Fonts' GameFontNormal trio, and UiPanels' ShowUIPanel/HideUIPanel plus its UISpecialFrames
-# entry and the ESC rung that cancel-clicks it. UIDropDownMenu.xml sits above too, but that
-# direction is call-time only, so the two could sit either way round.
 Interface\FrameXML\ColorPickerFrame.xml
-# ══ THE WORLD MAP — the reference's own, off the player's chain (1751, migrated 1980) ══
-# The fullscreen map over the worldmap host API (`crate::ui_world_map` feeds the player, corpse,
-# party and landmark positions; `crate::ui_battlefield_positions` the battleground teammates and
-# the flag carrier); the 'M' binding (ui_script/input.rs) calls its ToggleWorldMap(). The file
-# <Include>s its own blip templates (WorldMapFrameTemplates.xml) before the frames that inherit
-# them. Its player arrow is the Create/Position/Show/UpdateWorldMapArrowFrames family
-# (`script/worldmap_arrow.rs`), an anonymous Model pane the app draws as the minimap's arrow
-# sprite; its WorldMapPing is the same MinimapPing.mdx Model pane, which draws its own file on
-# the map sheet since 2013 (closing the gap 1980 named).
 Interface\FrameXML\WorldMapFrame.xml
-# ══ THE CAST BAR — the reference's own, off the player's chain (1751) ══
-# `CastingBarFrame` + its Border/Flash/Spark/Text children, driven by the SPELLCAST_* events
-# `crate::ui_cast` fires (decision 0137 phase 1). Our `CastingBar.xml` was a transcription of this
-# very file under a different name — all five frame names identical — so the swap is a deletion.
-#
-# The file SOURCES ITS OWN LUA (`<Script file="CastingBarFrame.lua"/>` at its l.3), which is why
-# only the `.xml` is listed here and `every_chain_xml_brings_its_own_lua` is satisfied.
-#
-# It brings `CastingBarFrame_UpdatePosition`, which ours never had. Only needs Fonts before it.
 Interface\FrameXML\CastingBarFrame.xml
-# ══ THE MIRROR TIMERS — the reference's own, off the player's chain (1751, window 7) ══
-# `MirrorTimer1..3`, `MIRRORTIMER_NUMTIMERS`, `MirrorTimerColors` and the `MirrorTimer_Show` /
-# `MirrorTimerFrame_*` family out of `MirrorTimer.lua`. The breath/fatigue bars at top-centre,
-# driven by the `MIRROR_TIMER_*` events `crate::ui_mirror` fires off the wire. Needs only Fonts
-# (GameFontHighlight) before it; kept beside the cast bar, whose border art it shares.
-#
-# ALL THREE of our copy's recorded divergences resolved at the swap (1751 §2), and two of them had
-# already stopped being true:
-# · THE START DRIVER. Ours hosted `MIRROR_TIMER_START` on a hidden `MirrorTimerDriver` frame
-#   because "our UIParent.xml is script-only — it has no frame of its own to register events on".
-#   It has one now, so the registration and the `MirrorTimer_Show` call moved into
-#   `UIParent_OnEvent` where the reference keeps them (UIParent.lua l.97 + l.374-377), and the
-#   extra frame is gone.
-# · THE POOL WALK. The reference asks its two questions in two loops and bounds the SECOND by
-#   `STATICPOPUP_NUMDIALOGS` — a copy-paste from StaticPopup.lua, and its own bug. Ours folded
-#   them into one walk to avoid it. Now faithful, which forced the real fix in the right place:
-#   our `STATICPOPUP_NUMDIALOGS` was 2 against the reference's 4, so the third mirror bar could
-#   never be claimed by a new timer. UiPanels.xml grew instances 3 and 4 with this window.
-# · THE PAUSE ARG is now the reference's own bug, reproduced: `MirrorTimerFrame_OnEvent` reads
-#   `arg1` as a timer NAME and then as a number (`arg1 > 0`), so a real MIRROR_TIMER_PAUSE raises.
-#   1.12 never reaches it — vmangos refuses to send that packet and substitutes a full START,
-#   saying so in `Player::SendMirrorTimers` — and `ui_mirror.rs`'s Pause edge carries the note.
 Interface\FrameXML\MirrorTimer.xml
-# ══ THE DURABILITY ALERT — the reference's own, off the player's chain (1751, window 4) ══
-# The "armor guy" under the minimap: `DurabilityFrame`, its eleven glyph textures, and
-# `DurabilityFrame_SetAlerts` / `_OnUpdate` with `INVENTORY_ALERT_STATUS_SLOTS` and
-# `INVENTORY_ALERT_COLORS`, all from `DurabilityFrame.lua` through its own `<Script file=>`.
-#
-# Ours was a measurement-faithful transcription and it is deleted. The swap re-examined its one
-# recorded divergence (1751 §2) and made it faithful: our copy OMITTED the ref's `OnUpdate`,
-# because the whole body is an `enchantTimer` countdown and that timer is provably dead in 1.12
-# (`SetAlerts` nils it; the only line that sets it is commented out, and so are the two colours it
-# would have painted). The reference runs the handler anyway, so we do too — the cost is one call
-# per frame on one frame, and it is the reference's own behaviour rather than our judgment of it.
-#
-# THE POSITION: `parent="UIParent"` and `relativeTo="MinimapCluster"` are both resolved at LOAD, so
-# this sits below UIParent.xml and MinimapCluster.xml. It is far above the reference's own slot
-# (FrameXML.toc l.86) and that is fine — nothing else reaches it at load, and its seat is decided
-# at runtime regardless: like every managed HUD frame the authored anchor is dead on arrival, with
-# `UIParent_ManageFramePositions` re-seating it on the loader's post-load pass and on every
-# OnShow/OnHide (ref UIParent.lua l.1758-1768).
-#
-# `UpdateInventoryAlertStatus` is the one global the sourced file names that this client does not
-# bind. It is reachable only from the dead `enchantTimer` branch above, so it is left absent rather
-# than stubbed (1203) — the honest state is "nothing calls it", not "we answer it with a lie".
 Interface\FrameXML\DurabilityFrame.xml
-# ══ THE ERROR TOASTS AND THE RAID WARNING — the reference's own (1751, window 14) ══
-# `UIErrorsFrame` (the red/yellow toast strip) and `UIErrorsFrame_OnLoad`/`_OnEvent`, then
-# `RaidWarningFrame` and `RaidBossEmoteFrame` with `RaidWarningFrame_OnLoad`/`_OnEvent`. Two files,
-# in the reference's own split and its own order: the warning frame anchors `relativeTo=
-# "UIErrorsFrame"`, resolved at LOAD, so it cannot precede it.
-#
-# Our single `ErrorsFrame.xml` held both and is deleted. It declared `RaidWarningFrame` with **no
-# `<Scripts>` at all**, and the reason it gave was wrong: *"we already deliver that chat type
-# through `ui_chat::feed`, so wiring a second consumer would print every raid warning TWICE"*.
-# Checked rather than inherited — `ui_chat` fires `CHAT_MSG_RAID_WARNING` as an ordinary chat event
-# and nothing of ours consumes it for a display. So the reference's handler adds the big centre
-# text and its `PlaySound("RaidWarning")` **beside** the chat line, which is exactly what 1.12
-# does: the chat window and the warning frame are two consumers of one event there too.
-#
-# It also brings `RaidBossEmoteFrame`, which our copy withheld on the "no corpus caller, and a
-# shadowed name with no caller is building against a guess" rule (1222). That rule is about names
-# WE would invent; this one is the reference's own declaration, so there is nothing left to guess.
-#
-# `ChatTypeInfo["RAID_WARNING"]` comes from the reference's ChatFrame.xml far below — read at call time, so the
-# order does not bind.
 Interface\FrameXML\UIErrorsFrame.xml
+# Anchors `relativeTo="UIErrorsFrame"`.
 Interface\FrameXML\RaidWarning.xml
-# ══ THE BAG WINDOWS — the reference's own, off the player's chain (decision 1751, window 1) ══
-# `ContainerFrame1..12`, `ContainerFrameTemplate`, `ContainerFrameItemButtonTemplate` and the whole
-# `ToggleBag`/`ToggleBackpack`/`OpenAllBags`/`IsBagOpen`/`ToggleKeyRing` verb family — the real
-# 1.12 file, running as the file, with `ContainerFrame.lua` arriving through its own
-# `<Script file=>`. Our `BagFrame.xml` used to build five windows here; it is the bag BAR only now,
-# and the bank's six popouts (BankFrame.xml) became ContainerFrames at ids 5..10, which is what the
-# reference does.
-#
-# THE POSITION IS THE REQUIREMENT, and it is why 1751 moved sourcing into this manifest at all:
-# this file's `inherits=` are resolved at LOAD and reach four templates above it —
-# `ItemButtonTemplate`, `SmallMoneyFrameTemplate` (MoneyFrame.xml), `CooldownFrameTemplate`
-# (Cooldown.xml), `UIPanelCloseButton` (UIPanelTemplates.xml) — plus `parent="UIParent"`. It
-# cannot load "first" the way a Lua-only sourcing had to.
 Interface\FrameXML\ContainerFrame.xml
-# ══ THE CHARACTER WINDOW — the reference's own, off the player's chain (decision 1751) ══
-# `CharacterFrame` + its five-tab row and portrait/name header (CharacterFrame.xml), the paper doll
-# itself — model pane, 19 equipment slots, the ammo slot, the five attributes, the melee and ranged
-# stat blocks, the five resistances (PaperDollFrame.xml) — and the pet page over the same templates
-# (PetPaperDollFrame.xml). Our `CharacterFrame.xml` (2027 lines) and `PetPaperDollFrame.xml` (773)
-# stood here and are deleted.
-#
-# THREE FILES IN THE REFERENCE'S OWN ORDER, and every edge between them is resolved at LOAD:
-#   - CharacterFrame.xml declares `CharacterFrame`, which the other two name in `parent=` (1734).
-#   - PaperDollFrame.xml declares `StatFrameTemplate`, `AttributeFrameTemplate` and
-#     `MagicResistanceFrameTemplate`, which PetPaperDollFrame.xml inherits on 11 frames.
-#   - PaperDollFrame.xml also declares `PaperDollItemSlotButtonTemplate`, which stock
-#     `MainMenuBarBagButtons.xml` below inherits on all five bag buttons.
-#
-# THAT LAST EDGE IS WHY THE BLOCK SITS HERE rather than below the bag bar where ours did.
-# `ItemSlotButtonTemplates.xml` held a transcribed copy of that template for exactly one reason:
-# our CharacterFrame.xml loaded after the bag bar and could not declare it in time. The reference's
-# own toc has no such problem (CharacterFrame 53, PaperDollFrame 54, MainMenuBarBagButtons 59), so
-# the copy is deleted and the reference's declaration is the live one — the same retirement
-# `BagSlotButtonTemplate` took one window earlier.
-#
-# `PaperDollFrame.lua` used to be a manifest line of its own, sourced far above everything so that
-# our bodies would win its 18 collisions. It arrives through PaperDollFrame.xml's own
-# `<Script file=>` now, at this position, and the collisions went with the file that had them.
-#
-# What the block needs from above, all far up: Fonts.xml (every `inherits=` font object),
-# ItemButtonTemplate.xml (the slot template's base, and the `SetItemButton*` family),
-# Cooldown.xml (`CooldownFrameTemplate` + `CooldownFrame_SetTimer`), GameTooltip.xml,
-# CharacterFrameTemplates.xml (`CharacterFrameTabButtonTemplate`), UIParent.xml (`UIPanelWindows`),
-# UIPanelTemplates.xml (`UIPanelCloseButton`,
-# `UIPanelButtonTemplate`, and `PanelTemplates_SetNumTabs`, which `CharacterFrame_OnLoad` calls at
-# LOAD), TextStatusBar.xml (`SetTextStatusBarTextPrefix`, called at load too, plus the
-# `TextStatusBar` the pet page's XP bar inherits), UnitFrames.xml (`PlayerFrameHealthBar` /
-# `PlayerFrameManaBar`, named in that same OnLoad), MainMenuBar.xml (`MainMenuExpBar`, likewise),
-# MainMenuBarMicroButtons.xml (`MicroButtonTooltipText`, the five tab hovers) and UIParent.xml
-# (`Model_OnLoad`/`_RotateLeft`/`_RotateRight`/`_OnUpdate` — the model pane's turntable, the
-# reference's own code living in our UIParent.lua counterpart).
-#
-# Two names it writes live BELOW it, and that is fine because both are runtime rather than load:
-# `HonorLevelText` and `HonorGuildText` (HonorFrame.xml), which `PaperDollFrame_SetLevel` and
-# `_SetGuild` fill "while we're at it" — reached only from OnShow and the UNIT_* events, long after
-# that file has loaded.
+# `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.
 Interface\FrameXML\CharacterFrame.xml
 Interface\FrameXML\PaperDollFrame.xml
-# Tab 2, the reference's file as well. `PetTab_Update` shows or hides `CharacterFrameTab2` off
-# `HasPetUI()` and re-anchors tab 3 over the gap, so a classless character's row has no hole.
 Interface\FrameXML\PetPaperDollFrame.xml
-# ══ THE BAG BAR — the reference's own, off the player's chain (decision 1751, window 3) ══
-# `MainMenuBarBackpackButton`, `CharacterBag0Slot`..`CharacterBag3Slot`, `KeyRingButton`,
-# `BagSlotButtonTemplate` and the `BagSlotButton_*`/`BackpackButton_*`/`Disable_BagButtons` family
-# — the real 1.12 file, with `MainMenuBarBagButtons.lua` arriving through its own `<Script file=>`.
-# It also owns `KEYRING_CONTAINER = -2`, which is where the reference puts it (l.1).
-#
-# Our `BagFrame.xml` stood here and is deleted. Its own header named the condition it was waiting
-# on — "replaced by the reference's own file the day `PutItemInBag` / `PickupBagFromSlot` are
-# bound" — and both are bindings now (`script/cursor/bag_verbs.rs`), so the ref's own click arms
-# work: its `PutItemInBag(id)` is the equip/swap our `BenillaBagBarSlot_Place` open-coded.
-#
-# THE POSITION IS THE REQUIREMENT: `inherits="PaperDollItemSlotButtonTemplate"` on the four bag
-# slots and `inherits="ItemButtonTemplate"` on the backpack are resolved at LOAD, and so is
-# `parent="MainMenuBarArtFrame"` — so this sits below the character-window block (above, which is
-# where stock `PaperDollFrame.xml` declares that template) and below MainMenuBar.xml (which declares
-# the art frame). It sat below a transcribed copy of the template in `ItemSlotButtonTemplates.xml`
-# until the character window migrated and made that copy redundant (decision 1810). Being BELOW the sourced ContainerFrame.xml is
-# legibility, not necessity, in either direction: every verb each file calls of the other resolves
-# at call time, `KEYRING_CONTAINER` included (no top-level read of it exists in ContainerFrame.lua).
-#
-# The item-push card is the reference's own `<Model>` since 2015 (0887's Lua card is gone with
-# it): `ItemAnim_OnEvent` puts the icon on the pane and arms it, the tile renderer draws the
-# file (2013), the pane's own clock ends it. The keyring's SHOW trigger moved the other way —
-# into the main bar's file, which is exactly where the reference keeps it (MainMenuBar.xml
-# l.323-341; stock since 1938).
 Interface\FrameXML\MainMenuBarBagButtons.xml
-# The stack-split spinner (decision 0216 §6/slice 2): loaded beside the bag windows, whose slot
-# click handler (the reference's `ContainerFrameItemButton_OnClick`) calls `OpenStackSplitFrame`.
-# Order between the two doesn't matter for correctness (Lua globals resolve at call time, and
-# neither file's XML `inherits=` reaches into the other's templates) — adjacent for legibility.
 Interface\FrameXML\StackSplitFrame.xml
-# Our ADAPTERS over the reference's own container files — one wrapper, for the keyring tooltip
-# detour benilla answers differently (0765). Must load AFTER them, since it captures at load the
-# body it wraps; its own header says what it stopped needing to do when the XML became sourceable.
+# 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.
 ContainerFrameAdapters.xml
-# The Reputation tab: the same separate-top-level-file shape as the two pages around it, seated
-# BETWEEN them because that is the real client's tab order (Character 1, Pet 2, Reputation 3,
-# Skills 4 — ref CharacterFrame.xml:79-168), and the page's `id=` is that slot. Its hard
-# dependencies are all far above: CharacterFrame.xml (the anchor target it is pinned to by name,
-# and the tab row it raises tab 3 of), ScrollTemplates.xml (the faux list + its trough template),
-# UIPanelTemplates.xml (`UIPanelCloseButton`, the detail popup's X — this page is that shared
-# template's first benilla consumer), OptionsFrameTemplates.xml (`OptionsCheckButtonTemplate`, two
-# of the three detail boxes), GameTooltip.xml (the column newbie tips) and Fonts.xml. One
-# dependency runs the other way and is worth naming: the WATCH BAR half of the reference's
-# ReputationFrame is declared in this same stock file (since 1875's co-edit, below) — so `FACTION_BAR_COLORS` and
-# `ReputationWatchBar_Update` are already defined when this page paints a row or ticks the
-# "Show as Experience Bar" box.
-# ══ THE REPUTATION PANE — the reference's own, off the player's chain (1751, scoped by 1844) ══
-# One line replaces one of ours: 47 of our 48 declared names were already the reference's, and the
-# one that was not (`ReputationListScrollFrameScrollBarTrough`) is our own scroll kit's. Nothing
-# gated it — the stock file inherits its own two row templates plus `UIPanelCloseButton`, fonts and
-# `OptionsCheckButtonTemplate`, and that last came off the chain with 1841.
-#
-# THE CO-EDIT was compulsory. The reference declares the reputation WATCH BAR in this same file;
-# ours lived in `ActionBar.xml` behind a note defending the placement. Frame globals publish
-# NON-overwritingly and ActionBar.xml was manifest line 340 against this file's — so ours would have
-# kept the name and the chain's bar would have been built and unreachable, which is exactly what
-# `GroupLootFrame` did for months (1838). The bar, its update, its two text verbs,
-# `MAX_PLAYER_LEVEL` and `FACTION_BAR_COLORS` all went home with it (1875).
 Interface\FrameXML\ReputationFrame.xml
-# ══ THE SKILLS TAB — the reference's own, off the player's chain (1751; decision 1956) ══
-# SkillFrame.xml + SkillFrame.lua: CharacterFrame's fourth page (`parent="CharacterFrame"`,
-# `id="4"`), the twelve-row list over 0437's skills seam (GetNumSkillLines/GetSkillLineInfo's
-# twelve-value tuple, the expand/collapse pair, the selection), the detail bar, the unlearn
-# button (its UNLEARN_SKILL dialog lives with the other dialogs in UiPanels.xml). At the
-# reference's own slot, after ReputationFrame and before HonorFrame. 0437's transcription is gone.
 Interface\FrameXML\SkillFrame.xml
-# The Honor tab: the same separate-top-level-file shape as the three pages above it, and LAST of
-# them because it is the last of the tabs (the real client's 5, ref HonorFrame.xml:5) — which
-# CLOSES the row: the character window's five tabs are now the reference's five, in its order, at
-# its numbers, with nothing left past the end. Its hard dependencies are all far above:
-# CharacterFrame.xml (the anchor target it is pinned to by name, the tab row it raises tab 5 of,
-# and the `CharacterNameText` its level line hangs under), GameTooltip.xml
-# (`BenillaTooltip_AddNewbieTipFor`, which all five of its hovers go through) and Fonts.xml
-# (GameFontGreenSmall/GameFontRedSmall carry the honorable/dishonorable colouring, and
-# HIGHLIGHT_FONT_COLOR the tip titles).
-# It must come BEFORE InspectFrame.xml, and that order is a REQUIREMENT rather than tidiness: the
-# inspect window's own honor page inherits the five `HonorFrame*ButtonTemplate` row templates
-# declared here, and `inherits=` resolves at LOAD. The reference has the identical edge — its
-# `HonorFrameTemplates.xml` is `<Include>`d by `HonorFrame.xml` and inherited by the LoadOnDemand
-# `Blizzard_InspectUI`, which loads later still.
+# Brings HonorFrameTemplates.xml, whose row templates `Blizzard_InspectUI` inherits.
 Interface\FrameXML\HonorFrame.xml
-# ══ THE LoadOnDemand ADDONS — Inspect, Talent, Macro, Raid: NO ROW HERE (1751; 1967) ══
-# `Blizzard_InspectUI`, `Blizzard_TalentUI`, `Blizzard_MacroUI` and `Blizzard_RaidUI` are not
-# listed, exactly as the reference's own `FrameXML.toc` lists no addon: each is `LoadOnDemand: 1`
-# on the player's chain — inside patch.MPQ; the loose `Interface\AddOns\Blizzard_*\` folders on
-# disk hold one `.pub` decoy each, which is what kept these four windows on transcriptions for
-# months — and `ui_script::addons` seats every such addon as a registry row (1957) that
-# `UIParentLoadAddOn` loads the first time its opener runs. The openers are the reference's own,
-# in UIParent.xml, its home for them: `InspectUnit` → `InspectFrame_LoadUI`, `ToggleTalentFrame`
-# → `TalentFrame_LoadUI`, `ShowMacroFrame` → `MacroFrame_LoadUI`, and the stock RaidFrame.lua's
-# `RaidFrame_LoadUI` on the first roster update. 1832, 1833, 1848 and 1874 took the four off the
-# chain but listed them here with everything else, and left the LoadUI calls out rather than
-# stub them (1203); 1967 gives them the reference's load timing and the calls back.
-#
-# What those headers recorded that still holds: the inspect honor page inherits HonorFrame.xml's
-# five row templates, the macro icon chooser inherits `ClassTrainerListScrollFrameTemplate`
-# (1862) — FrameXML files listed above, so resolved long before any addon loads, which is also
-# why the reference's own toc has the same order. The gates over chain files
-# (`ui_script::reference_ui`) walk these addons' files after the manifest's entries — a reached
-# addon is part of the shipped interface, row or no row.
-# ══ THE DRESSING ROOM — the reference's own, off the player's chain (1751; decision 1969) ══
-# DressUpFrame.xml + DressUpFrame.lua: the ctrl-click item preview (1060). Its `<DressUpModel>`
-# is a real widget kind now — PlayerModel's three verbs plus its own `TryOn`/`Dress`/`Undress`
-# (table 0x84f190), queued as intents the app composes the booth's look from — and its pane draws
-# the "dressup" booth by the reference's own name (`portrait::model_pane_booth`). The rotate
-# buttons and OnUpdate drive `Model_RotateLeft/Right/OnUpdate` from UIParent.xml above, and the
-# Close/Reset buttons inherit UIPanelCloseButton/UIPanelButtonTemplate from the panel kit above.
-# Slot as before: after the windows whose slots feed it; `DressUpItemLink` resolves at call time.
 Interface\FrameXML\DressUpFrame.xml
-# ══ THE SPELLBOOK — the reference's own, off the player's chain (1751; decision 1952) ══
-# SpellBookFrame.xml + SpellBookFrame.lua: the book, the twelve page buttons, the skill-line tabs,
-# the Spell/Pet toggle tabs. Its whole engine surface was already ours (1924's UpdateSpells, 1931's
-# GetSpellTabInfo tuple); what stopped it in 1926 — MultiActionBar_ShowAllGrids/HideAllGrids on
-# show/hide — has been the reference's MultiActionBars.lua since 1938. Loaded here, after the
-# action-bar files it calls into and after MainMenuBarMicroButtons (UpdateMicroButtons on show). The 'P' binding
-# calls its own ToggleSpellBook(BOOKTYPE_SPELL). 0216's transcription is gone.
 Interface\FrameXML\SpellBookFrame.xml
-# The director's two look deviations on the pet page's autocast button (1392/1393), re-seated onto
-# the reference's own Model now that this engine renders it (2013/2014): the corner brackets at
-# 71.53 and the shine pane squared on the button at scale 1.48. BENILLA_ALLOW_OWN_UI=1.
+# 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.
 SpellBookAdapters.xml
-# ══ THE SOCIAL WINDOW — the reference's own, off the player's chain (1751; decision 1959) ══
-# FriendsFrame.xml + FriendsFrame.lua: the O-key window's four tabs — friends/ignore, who, the
-# guild roster with its control and info panes, and the raid tab whose pane is the stock
-# RaidFrame.xml right below (the reference's own file split, its toc l.71-72). Over the social
-# API (`benilla-ui/src/script/social.rs`) and `crate::ui_social`'s feed/drain, the guild seam,
-# the party roster. Its twelve dialogs live with the other dialogs in UiPanels.xml; the
-# GUILD_INVITE arms are UIParent.xml's, the reference's own home. 0668/1257/1549's transcription
-# is gone.
+# RaidFrame.xml names `parent="FriendsFrame"` and MailFrame.xml inherits `FriendsFrameTabTemplate`.
 Interface\FrameXML\FriendsFrame.xml
-# ══ THE RAID PANE — the reference's own, off the player's chain (1751, scoped by 1839) ══
-# The social window's fourth tab, in its own file because RaidFrame is a child of FriendsFrame and
-# a child cannot be declared before its parent — the reference splits it the same way and for the
-# same reason (its FrameXML.toc has RaidFrame.xml on the very next line). Decision 1549.
-#
-# The pane is the entry here; the LoadOnDemand half that carries the group frames and the
-# tear-off pullouts, `Blizzard_RaidUI`, is a registry row that the stock RaidFrame.lua loads on
-# the first roster update (the addons header far above; 1967). 1839 measured the swap — 83 of our
-# 84 frame names were
-# already the reference's, 20 of our 22 Lua functions were, and NOTHING needed building. The one
-# name that was not is `BenillaRaidDropDown`, and the reference has no raid drop-down at all: it
-# reuses `FriendsDropDown`, which FriendsFrame.xml declares four manifest lines above.
-#
-# GAINED: `RaidPulloutFrameTemplate`, `RaidPulloutButtonTemplate`, `RaidBuffButtonTemplate` and the
-# fifteen `RaidPullout*` verbs — the tear-off group pullouts we never transcribed.
 Interface\FrameXML\RaidFrame.xml
-# ══ THE GOSSIP WINDOW — the reference's own, off the player's chain (1751) ══════════════════
-# No engine verb, no widget method, no shadowed name — all three instruments clean. It was
-# deferred once on `GossipResize` reading `GetTextHeight()` in the same repaint that sets the
-# label, our measurement being a frame late; that is what the swap tests.
 Interface\FrameXML\GossipFrame.xml
-# ══ THE VENDOR WINDOW — the reference's own, off the player's chain (1751) ══════════════════
-# It took three things, in this order: `PickupMerchantItem` (the vendor cursor, 1797), the
-# `BenillaMoney_*` coin kit moving out to MoneyFrame.xml where eight other windows can reach it
-# without loading this one, and `SetMerchantCompareItem` (1802) — which the gap report could not
-# see at all until 1798 taught it to read `:Method(` sites, and which would have raised on the
-# first vendor-row hover with every check green.
-#
-# That is why the notes below say "grouping" rather than "reuses that file's helpers": the
-# windows still cluster here, but nothing depends on this file any more.
 Interface\FrameXML\MerchantFrame.xml
-# ══ THE MAIL WINDOW — the reference's own, off the player's chain (1751; decision 1970) ══
-# MailFrame.xml + MailFrame.lua: the inbox, the open letter (with the auction invoice pane and
-# the letter-copy button), the send tab with its stationery picker and recipient autocomplete,
-# over the Era mail API (`benilla-ui/src/script/mail.rs`) + `crate::ui_mail`'s feed/drain. What
-# the swap built: the stationery family (`GetNumStationeries`/`GetStationeryInfo`/
-# `SelectStationery`/`GetSelectedStationeryTexture`, wow-re `stationery-bindings.md`) and the two
-# events the stock file listens for that nothing fired — `MAIL_SEND_INFO_UPDATE` on an attachment
-# change and `CLOSE_INBOX_ITEM(index)` when a take empties a mail. Its templates are all on the
-# chain above: the panel kit, ItemButtonTemplate, MoneyFrame/MoneyInputFrame, UIRadioButtonTemplate
-# (UIPanelTemplates.xml), InvoiceTextFontNormal (Fonts.xml) and FriendsFrameTabTemplate
-# (FriendsFrame.xml, which the reference's own toc also seats before this, l.71 → l.86).
 Interface\FrameXML\MailFrame.xml
-# ══ THE TRADE WINDOW — the reference's own, off the player's chain (1751; decision 1966) ══
-# TradeFrame.xml + TradeFrame.lua: both columns' seven slots over the trade API
-# (`benilla-ui/src/script/trade.rs`) + `crate::ui_trade`'s feed/drain, the recipient's
-# SmallMoneyFrame (TARGET_TRADE) and the player's MoneyInputFrame, the accept glows. Its slot
-# tooltips are this engine's SetTradePlayerItem / SetTradeTargetItem; its per-slot events
-# (TRADE_PLAYER_ITEM_CHANGED / TRADE_TARGET_ITEM_CHANGED) the feed's. Loaded here, after
-# ItemButtonTemplate, MoneyInputFrame, the money kit and the dialog engine it inherits from.
-# 0592's transcription is gone.
 Interface\FrameXML\TradeFrame.xml
-# ══ THE ITEM-TEXT READER — the reference's own, off the player's chain (1751, window 9) ══
-# `ItemTextFrame` and its page chrome, over the `ItemTextGet*` seam
-# (`benilla-ui/src/script/item_text.rs`) and `crate::ui_item_text`'s feed/drain. Letters (mail-made
-# permanent copies) and, later, books and plaques. Right after MailFrame, the same arc; needs
-# Fonts/UiPanels/ScrollTemplates, all above.
-#
-# ONE THING OUR COPY CARRIED THAT THE REFERENCE'S DOES NOT, moved to the reference's own home:
-# `GetMaterialTextColors` and the two colour tables it reads. 1.12 keeps the function in
-# `UIParent.lua` and the tables in `Fonts.xml`, and both of ours now do the same — under the
-# reference's published names (`MATERIAL_TEXT_COLOR_TABLE` / `MATERIAL_TITLETEXT_COLOR_TABLE`)
-# rather than the `BENILLA_`-prefixed pair this file kept privately. Fonts.xml's own note said
-# those two tables would arrive "the day something does" read them; the sourced file is that day.
 Interface\FrameXML\ItemTextFrame.xml
-# ══ THE TRAINER WINDOW — the reference's own LoadOnDemand addon, off the chain (1751; decision 1957) ══
-# No row: `Blizzard_TrainerUI` is the first Blizzard addon benilla loads the way the reference
-# does — on demand, from UIParent.xml's TRAINER_SHOW arm through `ClassTrainerFrame_LoadUI` →
-# `UIParentLoadAddOn` → `LoadAddOn`, off a registry row `ui_script::addons` reads from the
-# chain (its toc, its `## SavedVariables`, its ADDON_LOADED at the end of ITS load). The timing
-# is the mechanism: the list packet resets the engine's filter mask, and the addon's
-# ADDON_LOADED arm re-pushes the saved filters after it — which eager loading cannot do. Its
-# list inherits `ClassTrainerListScrollFrameTemplate` from
-# `Interface\FrameXML\ClassTrainerFrameTemplates.xml`, far below, resolved at the addon's
-# load. 0237/0247/0251's transcription is gone.
-# ══ THE BANK WINDOW — the reference's own, off the player's chain (decision 1751, window 2) ══
-# `BankFrame`, `BankFrameItem1..24`, `BankFrameBag1..6`, `BankFramePurchaseInfo` and the
-# `BANK_CONTAINER`/`NUM_BAG_SLOTS`/`NUM_BANKGENERIC_SLOTS`/`NUM_BANKBAGSLOTS` constants — the real
-# 1.12 file, running as the file, with `BankFrame.lua` arriving through its own `<Script file=>`.
-# Our own 890-line BankFrame.xml is gone with it, and so are its six popout windows: a bank bag is
-# an ordinary `ContainerFrame` at container id 5..10, which is what the reference always did.
-#
-# THE POSITION IS THE REQUIREMENT, as it was for ContainerFrame.xml. This file's `inherits=` reach
-# four templates above it — `ItemButtonTemplate`, `UIPanelCloseButton` (UIPanelTemplates.xml),
-# `UIPanelButtonTemplate` (same), `SmallMoneyFrameTemplate` (MoneyFrame.xml) — plus
-# `parent="UIParent"`, and its `OnHide` calls `updateContainerFrameAnchors` out of
-# ContainerFrame.lua. All are loaded above.
-#
-# What it needed from this client, all built for it: `PutItemInBag`/`PickupBagFromSlot` (the two
-# verbs its bag buttons ARE), the bank-bag inventory band at live ids 64..=69 that gives those
-# verbs an item to move, `GetInventorySlotInfo("Bag1".."Bag6")` for the empty-slot art, and
-# `StaticPopupDialogs["CONFIRM_BUY_BANK_SLOT"]` re-homed into UiPanels.xml (the reference keeps it
-# in StaticPopup.lua, which this client replaces).
-#
-# One reference quirk carried rather than fixed: `BankFramePurchaseButton` is declared
-# `virtual="true"` INSIDE `<Frames>`. Only a top-level element is ever a template — nested nodes
-# are materialized regardless (`framexml.rs`) — so the button exists and works, which is what the
-# real client does too. Classic Era's Vanilla BankFrame.xml still carries the same attribute on
-# the same button, and that button works there.
-#
-# Kept in the "NPC session windows grouped" cluster beside Trainer/Taxi, and after MerchantFrame.
 Interface\FrameXML\BankFrame.xml
-# ══ THE FLIGHT MAP — the reference's own, off the player's chain (1751) ══
-# The flight-master session (decision 0484 phase 2), driven by the taxi engine seam
-# (`benilla-ui/src/script/taxi.rs`) over `crate::ui_taxi`'s feed/drain — unchanged; only the window
-# in front of it is the reference's now. Our 557-line transcription carried the same five stock
-# globals plus eight helpers of its own, none of which anything outside that file named.
-#
-# The one thing it needed was the `<TaxiRouteFrame>` widget type, which is registered now (1828) —
-# a `CSimpleFrame` and nothing else, so it is `FrameKind::Frame` and the route lines stay what the
-# reference makes them: plain `<Texture>` children rotated by an 8-argument `SetTexCoord`.
-#
-# Pulls only `TaxiFrame.lua`, and still needs only Fonts/UIParent/GameTooltip (SetTooltipMoney),
-# all loaded above — so it keeps its seat in the "NPC session windows grouped" cluster.
 Interface\FrameXML\TaxiFrame.xml
-# The stable-master window (decision 1676): the hunter's three-slot pet stable over the stable
-# API (`benilla-ui/src/script/stable.rs`) + the app's feed/drain. Kept in the "NPC session
-# windows grouped" cluster beside Trainer/Bank/Taxi. Two of its dependencies are resolved at
-# LOAD and so must sit above it: MoneyFrame (its purse and cost displays inherit
-# SmallMoneyFrameTemplate) and UIPanelTemplates (UIPanelButtonTemplate / UIPanelCloseButton).
-# A third is resolved at load too: the model pane is a `<PlayerModel>` whose own <OnLoad> calls
-# the reference's `Model_OnLoad` (UIParent.xml, far above). That used to be CharacterFrame.xml's
-# `BenillaPaperDollModel_OnLoad`, which is why this entry sat below the character window; it no
-# longer has to, and stays here only because the NPC-session cluster is where it belongs. The rest
-# (ItemButtonTemplate's SetItemButtonTexture, GameTooltip, UiPanels' ShowUIPanel/HideUIPanel,
-# UIParent's BuildListString) are resolved when the window repaints, so their order is free.
-#
-# ══ THE REFERENCE'S OWN, off the player's chain (1751) ══
-# A true 1:1 swap: our transcription and the stock file declare the SAME frame names and the SAME
-# four globals (`PetStable_OnLoad`/`_OnEvent`/`_Update`/`_NoPetsAllowed`), so nothing that names
-# either moves — `ui_stable.rs`, `names.rs` and `net/apply/npc.rs` all reach it by stock names
-# already, and `portrait`'s booth keys on `PetStableModel`, which both spell the same.
 Interface\FrameXML\PetStable.xml
-# ══ THE AUCTION HOUSE — `Blizzard_AuctionUI`, a LoadOnDemand addon: NO ROW HERE (1751; 1971) ══
-# The three-tab doublewide window is the reference's own addon off the player's chain, seated as a
-# registry row (1957) and loaded on the first AUCTION_HOUSE_SHOW through UIParent.xml's own
-# `AuctionFrame_LoadUI` arm (ref UIParent.lua l.154-156, l.575-587), exactly like the trainer,
-# inspect, talent, macro and raid addons above. Its engine surface was already whole (decision
-# 1511's auction API); what it needed loaded is on the chain above: the panel kit, MoneyFrame /
-# MoneyInputFrame, UIDropDownMenu, and the dressing-room pane it embeds — `<DressUpModel
-# name="AuctionDressUpModel">`, the 1969 widget kind, drawing the same booth as the dressing room.
-# ══ THE CRAFTING WINDOWS — `Blizzard_TradeSkillUI` and `Blizzard_CraftUI`, LoadOnDemand: NO ROW HERE (1751; 1973) ══
-# The trade skill window (Blacksmithing, Tailoring, … and Poisons) and the craft window (Enchanting,
-# Beast Training) are the reference's own addons off the player's chain, registry rows (1957) loaded
-# on the first TRADE_SKILL_SHOW / CRAFT_SHOW through UIParent.xml's `TradeSkillFrame_LoadUI` /
-# `CraftFrame_LoadUI` arms (ref UIParent.lua l.166-168, l.190-192, l.605-632). Both inherit the
-# ClassTrainerFrameTemplates.xml kit far above and register their own panel rows. What 1973 built:
-# the four item-link verbs (`GetTradeSkillItemLink`, `GetTradeSkillReagentItemLink`,
-# `GetCraftItemLink` — the `|Henchant:` link — and `GetCraftReagentItemLink`, wow-re
-# `tradeskill-craft-item-links.md`) and `SetHyperlink`'s enchant leg. 0437's transcriptions are gone.
-# ══ THE LOOT WINDOW — the reference's own, off the player's chain (1751) ════════════════════
-# It never needed an engine VERB. It needed a widget TYPE: `<LootButton>` is a real registered
-# `CreateFrame` type (decision 1799), and registering it as a plain Button would have loaded the
-# file and left every row dead — 1.12 has no Lua verb for "take slot N".
-#
-# Its ONE method, `SetSlot`, is also what the gap report's new `method=` column found from the
-# call site while wow-re was deriving it from the vtable (1798). Both columns read 0 now, and
-# every verb the stock file calls at runtime — not just at load — was checked by hand against
-# the bindings before this line changed.
 Interface\FrameXML\LootFrame.xml
-# ══ THE QUESTGIVER WINDOW — the reference's own, off the player's chain (1751, 1944) ══
-# Stock QuestFrame.xml sources QuestFrame.lua and INCLUDES QuestFrameTemplates.xml (the panel,
-# item and title-button templates the quest log below inherits too), so one row brings the
-# three-file unit 1913 measured. Its `QuestFrameItems_Update` paints all three windows' reward
-# grids — the shared function that made the quest log un-migratable alone until the money went
-# stock (1937). Needs, all above: Fonts (QuestFont/QuestTitleFont), MoneyFrame (the two
-# MoneyFrameTemplate frames, resolved at LOAD), UiPanels, UIPanelTemplates. Its two saved-variable
-# flags (QUEST_FADING_DISABLE, AUTO_QUEST_WATCH) are declared where the reference declares them —
-# the options window's init (OptionsFrame.xml, far above).
+# Brings QuestFrameTemplates.xml, whose templates the guild registrar and quest log inherit; the
+# quest log's OnLoad also calls `QuestMoneyFrame_OnLoad` from QuestFrame.lua.
 Interface\FrameXML\QuestFrame.xml
-# The two guild-charter windows (decision 1672): the guild registrar — the window the "How do I
-# form a guild?" gossip row opens — and the charter itself, the sheet nine people sign. **Both are
-# the reference's own files off the player's chain now** (1751, windows 12 and 13). Loaded here,
-# right after QuestFrame, because both wear the QuestGreeting parchment and its QuestFont /
-# QuestTitleFont objects and read as that family; they need UiPanels (the panel manager seats both,
-# and the RENAME_GUILD dialog the charter raises is registered there, where 1.12 keeps every
-# dialog), MoneyFrame (the registrar's price rides MoneyFrameTemplate, resolved at LOAD — decision
-# 1580's ordering rule) and UIPanelTemplates (the close/action buttons), all far above. The
-# registrar must come first: no load-order dependency links them, but the flow does, and the pair
-# reads in the order it is used.
 Interface\FrameXML\GuildRegistrarFrame.xml
-# ══ THE GUILD CHARTER — the reference's own, off the player's chain (1751, window 12) ══
-# `PetitionFrame` and its nine signature rows, `PetitionFrame_Update`, `MAX_PETITION_SIGNATURES`,
-# and the leader/signer button pair that share one anchor. Ours was the same window under the same
-# names (decision 1672) with a different expression of the same painter; the reference's file is
-# what that expression was written from.
-#
-# The seat is unchanged and every dependency it names is above: UiPanels (the panel manager seats
-# it, and its RENAME_GUILD dialog rides the shared popup engine), MoneyFrame, UIPanelTemplates (the
-# close/action buttons `inherits=` at LOAD), and the QuestGreeting parchment family it shares with
-# GuildRegistrarFrame directly above.
 Interface\FrameXML\PetitionFrame.xml
-# ══ THE QUEST LOG — the reference's own, off the player's chain (1751, 1944) ══
-# Stock QuestLogFrame.xml sources QuestLogFrame.lua; the 'L' binding calls its ToggleQuestLog(),
-# and its reward hovers are GameTooltip:SetQuestLogItem / SetQuestLogRewardSpell (engine, 1944).
-# After QuestFrame.xml (QuestItemTemplate, QuestMoneyFrame_OnLoad, QuestFrameItems_Update),
-# MainMenuBarMicroButtons.xml (QuestLog_OnShow calls UpdateMicroButtons unguarded) and the same kit as the
-# giver; the reference's toc has the pair at l.53-54.
 Interface\FrameXML\QuestLogFrame.xml
-# The timed-quest countdown window under the minimap (decision 1150): the reference's own
-# file split. After MinimapCluster (its anchor), UIParent (the manage pass that re-seats it,
-# and SecondsToTime), GameTooltip (its row hover), and QuestLogFrame — whose window a row
-# click opens, and whose MAX_QUESTS it shares.
 Interface\FrameXML\QuestTimerFrame.xml
-# ══ THE CHAT WINDOW — the reference's own, off the player's chain (1751; decision 1948) ══
-# ChatFrame.xml (ChatFrameEditBox, ChatMenu/EmoteMenu/LanguageMenu/VoiceMacroMenu, ChatFrameMenuButton,
-# the frame/tab/edit-box templates, ChatFrame.lua) then FloatingChatFrame.xml (ChatFrame1..7, their tabs
-# and dock regions, the tab dropdown, FloatingChatFrame.lua) — the reference's pair in its own order
-# (FrameXML.toc l.48-49). What they call and we built for them: the window record verbs and the colour
-# registry (benilla-ui script/chat_window.rs, chat_types.rs), the channel verbs (channel.rs), the
-# language walk (chat_send.rs), the slash-handler verbs (chat_misc.rs), and UpdateColorByID. Our own
-# transcription (0288's ChatFrame.xml) is gone; benilla's instrument commands (/chattest, /shot, …)
-# register through SlashCmdList from ScriptLogFrame.xml's dev block, and the app's chat feed FIRES the
-# CHAT_MSG_* events the reference's ChatFrame_OnEvent prints from — it no longer prints them itself.
+# ChatFrame.lua starts `SlashCmdList` empty: a file that registers slash commands at load follows.
 Interface\FrameXML\ChatFrame.xml
 Interface\FrameXML\FloatingChatFrame.xml
 
-# The bonus (stance-page) bar AND the shapeshift bar — one stock file declares both. The
-# reference's toc seats it at l.74, after PetActionBarFrame (the bonus buttons' Up/Down call
-# PetActionButtonUp/Down). It sits HERE, right before WorldStateFrame at the tail, because the
-# two files depend on each other through the stock UIParent_ManageFramePositions:
-# ShapeshiftBar_OnLoad shows the bar, its OnShow runs the pass, and the pass indexes
-# ReputationWatchBar, QuestTimerFrame, QuestWatchFrame, the chat frames and the rest UNGUARDED
-# (UIParent.lua l.1592-1775) — so this file follows every one of them (ours seats the quest and
-# chat files later than the reference does); and WorldStateAlwaysUpFrame's OnLoad runs the same
-# pass, whose shapeshift-appearance arm indexes ShapeshiftBarLeft/Middle/Right (l.1710-1725) —
-# so that file follows THIS one, as in the reference (l.74 then l.89). Beside the bar files this
-# raised at UIParent.lua:1618 on every login and the shelf was never seated: the shelf art sat
-# at its XML anchor until something re-ran the pass (the director's sliver above Defensive
-# Stance; decision 2001). `every_load_time_runner_of_the_managed_pass_follows_what_it_reads`
-# enforces both directions.
+# `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`).
 Interface\FrameXML\BonusActionBarFrame.xml
-# ══ THE WORLD-STATE FRAMES — the reference's own, off the player's chain (1751; decision 1972) ══
-# WorldStateFrame.xml + WorldStateFrame.lua: the always-up readout 1586 built (the tower/flag/base
-# counters at top-centre, `UPDATE_WORLD_STATES` from `crate::world_state_ui`), the capture bars,
-# and the battleground SCOREBOARD ours never had — `WorldStateScoreFrame`, over the score family
-# 1972 built (`MSG_PVP_LOG_DATA`, the eleven verbs, `UPDATE_BATTLEFIELD_SCORE`) and UIParent.xml's
-# `BattlefieldMinimap_LoadUI`. Needs Fonts, GameTooltip, the panel kit (its close button, tabs,
-# faux scroll frame) — all above. It sat beside the mirror timers until 1988: the always-up
-# frame's OnLoad runs the stock UIParent_ManageFramePositions, and that pass indexes half the
-# HUD unguarded — ReputationWatchBar, QuestTimerFrame, QuestWatchFrame (QuestLogFrame.xml),
-# MinimapCluster, DurabilityFrame, the bars and their sliding textures — and ends by calling
-# FCF_DockUpdate and re-anchoring the container frames. So this file sits after all of them,
-# which is why the reference's own toc has it at l.89, near the end (1988).
+# `WorldStateAlwaysUpFrame`'s OnLoad runs the same pass, which also reads
+# `ShapeshiftBarLeft/Middle/Right`, so this follows BonusActionBarFrame.xml.
 Interface\FrameXML\WorldStateFrame.xml
-# ══ THE MACRO WINDOW — the reference's own, off the player's chain (1751, window 32) ══
-# A LoadOnDemand addon with no row here since 1967 (the addons header far above); what stays in
-# this slot is the FrameXML file it needs loaded first.
-#
-# Nothing to build. 1835 recorded `SaveMacros` as a missing engine verb and it is not one — the
-# only occurrence in the reference's own file is COMMENTED OUT (`--SaveMacros();` in
-# `MacroFrame_OnHide`); the triage that found it was not stripping Lua comments.
-#
-# It was BLOCKED until 1846: `MacroPopupScrollFrame` inherits FrameXML's
-# `ClassTrainerListScrollFrameTemplate`, which inherits `FauxScrollFrameTemplate` — and ours was a
-# same-named `<Frame>` with a Benilla slider that shadowed the reference's `<ScrollFrame>`. With the
-# panel kit on the chain that shadow is gone, so this window went from blocked to a plain swap.
-#
-# `ShowMacroFrame` moved to UIParent.xml, the reference's own home for it — see 1848.
-#
-# **`ClassTrainerFrameTemplates.xml` is not optional, and this header used to name the dependency
-# without listing the file.** `MacroPopupScrollFrame` — the icon chooser's list — inherits its
-# `ClassTrainerListScrollFrameTemplate`, and a missing template is a loader WARNING, not an error
-# (1833): the frame is still built, just BARE, with no scroll bar and no `<OnLoad>`. So
-# `ScrollFrame_OnLoad` never ran, `this.offset` was never seeded, and the reference's
-# `FauxScrollFrame_GetOffset` (`return frame.offset`, no `or 0` — our deleted copy had that
-# fallback and was hiding this) handed `MacroPopupFrame_Update` a nil to multiply. Clicking
-# "Change Name/Icon" raised. The reference's own `FrameXML.toc` loads this at its line 92, well
-# before any addon; ours takes it here — its one consumer, `Blizzard_MacroUI`, is a LoadOnDemand
-# row now (1967) and loads after everything. Decision 1862.
+# `ClassTrainerListScrollFrameTemplate`, which the on-demand macro, trainer, trade skill and craft
+# addons inherit.
 Interface\FrameXML\ClassTrainerFrameTemplates.xml
-# The script error log (decision 1495): the window `/errors` opens — the list B293's two
-# reporters asked for, which the reference's one-message-at-a-time ScriptErrors modal cannot
-# be. Ours entirely (1.12 has no counterpart), reading the retained log on the model rather
-# than any per-frame feed. Needs ScrollTemplates (BOTH kits — the faux one for the fixed row
-# list, the real one for the traceback pane), UIPanelTemplates (the Clear/Close buttons) and
-# UiPanels (ShowUIPanel/HideUIPanel + the UIPanelWindows row that seats it and gets it closed
-# by ESC). Before GameMenuFrame, which is deliberately last.
+# Ours: the `/errors` script error log, which 1.12 lacks, and benilla's slash commands, added to
+# `SlashCmdList` at load.
 ScriptLogFrame.xml
-# The GM help window + the ticket-status toast (the HelpFrame.xml transcription): the third
-# **center**-area UIPanelWindows row, so it opens like the game menu and the options window and
-# shuts every other panel on the way in. It heads the SHELL TAIL for that reason — Help, then the
-# options pair, then the game menu last — and it goes ahead of KeyBindingsPage.xml rather than
-# between it and OptionsFrame.xml, because those two are a hard must-load-before pair and nothing
-# should be wedged into it. Every dependency is far above: UiPanels (ShowUIPanel/HideUIPanel, the
-# UIPanelWindows row, and the StaticPopup engine its three ticket dialogs register into),
-# UIPanelTemplates (UIPanelCloseButton, UIPanelButtonTemplate2, GameMenuButtonTemplate and the
-# real UIPanelScrollFrameTemplate the ticket editor is built on), ScrollTemplates (the faux kit
-# behind the GM category list, its shared trough, and the ScrollingEdit pair), GameTooltip (the
-# toast wears the tooltip backdrop colours at OnLoad) and MainMenuBarMicroButtons (whose Help button calls this
-# file's ToggleHelpFrame, and whose UpdateMicroButtons this file calls back on show/hide — both
-# resolved at call time, so that pair could sit either way round). The one seat that is a REAL
-# requirement rather than legibility is **after BuffFrame.xml**: the toast re-anchors
-# TemporaryEnchantFrame out of its own way, and that frame is declared there.
-#
-# **The reference's own since 1889.** Ours was 1017 lines against the reference's 2088 — the
-# largest shortfall of any window we shipped — so this swap is mostly ARRIVAL, not replacement.
-# The file sources its own `HelpFrame.lua` (its l.3), so only the `.xml` is listed. Its one
-# named need, `GMSurveyFrame_LoadUI`, is now in UIParent.xml where the reference declares it.
 Interface\FrameXML\HelpFrame.xml
-# The cinematic frame: the ESC that skips a fly-by, and the SCREENSHOT chord it hands back. It
-# draws NOTHING — the letterbox moved to Bevy UI nodes in `crate::cinematic` (decision 1699),
-# because the lane this frame paints into is dark for the whole shot.
-# Needs UiPanels.xml far above for ShowUIPanel/HideUIPanel and its own UIPanelWindows row; needs
-# nothing else, and nothing needs it — the engine reaches it purely by firing CINEMATIC_START.
-# Seated late because it is an outermost, screen-owning layer, like the two windows below it.
 Interface\FrameXML\CinematicFrame.xml
-# ══ THE TUTORIAL FRAME — the reference's own, off the player's chain (1751; decision 1976) ══
-# TutorialFrame.xml + TutorialFrame.lua: the alert buttons `TUTORIAL_TRIGGER` queues, the window
-# a click opens over `TUTORIAL_TITLE<n>`/`TUTORIAL<n>`, the "Display Tips" checkbox whose unticked
-# hide calls ClearTutorials, and the CINEMATIC_STOP arm that clicks the Welcome alert when the
-# intro ends. Right after CinematicFrame.xml as the reference's toc has it (l.76-80); its
-# engine — the two flag banks, the fire-once trigger, the four verbs — is `crate::tutorial`.
-# Needs UIPanelTemplates (UICheckButtonTemplate), BasicControls (the dialog button textures),
-# GameTooltip, and UiPanels' SetButtonPulse, all far above.
-# ══ THE TABARD DESIGNER — the reference's own, off the player's chain (1751; decision 1977) ══
-# TabardFrame.xml + TabardFrame.lua: the <TabardModel> pane (its ten methods are the engine's,
-# `script/tabard.rs`), the five customization rows over CycleVariation, the emblem cells the two
-# texture setters paint, Save/CanSaveTabardNow and CloseTabardCreation; opened only by the wire
-# (`crate::ui_tabard`). Right before TutorialFrame.xml as the reference's toc has it (l.79-80).
-# Needs UIPanelTemplates (UIPanelButtonTemplate, UIPanelCloseButton), MoneyFrame
-# (SmallMoneyFrameTemplate), GameTooltip and UiPanels, all far above.
 Interface\FrameXML\TabardFrame.xml
 Interface\FrameXML\TutorialFrame.xml
-# The game menu (decision 0674): the frame ESC opens. LAST on purpose — it is the outermost
-# layer of the shell, it depends on everything it touches being loaded (UiPanels' popup engine
-# + panel manager, MainMenuBarMicroButtons' UpdateMicroButtons, BagFrame's Disable_BagButtons), and nothing
-# depends on it: the ESC chain and the micro button both reach it by name at call time.
-#
-# NOT yet on the chain, and the reason is not in the gap report: the stock file's buttons reach
-# `UIOptionsFrame`, and stock `UIParent.lua:997` indexes it — so the ESC menu drags in the whole
-# options family, the same chain `MainMenuBarMicroButtons` is deferred behind. All three columns
-# read clean because the file LOADS clean; what it needs is a sibling window, not a verb.
-#
-# Its CAMP/QUIT dialogs and their event driver HAVE moved out — the dialogs to `StaticPopup.xml`,
-# the driver to `UIParent.xml`, the reference's own homes (StaticPopup.lua l.564/586 for the
-# dialogs, UIParent.lua l.304-315 for the three events), both stock since 1988. The ESC menu never
-# owned them; it was just where ours were first needed. That is one less thing to move when the options family lands.
+# 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`.
 GameMenuFrame.xml
diff --git a/crates/benilla-app/examples/addon_harness.rs b/crates/benilla-app/examples/addon_harness.rs
index a6d253eb..1d75164c 100644
--- a/crates/benilla-app/examples/addon_harness.rs
+++ b/crates/benilla-app/examples/addon_harness.rs
@@ -92,7 +92,7 @@ fn render_frames(frames: &[String]) -> String {
 /// 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`, itself generated from wow-re's live capture.
+/// 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
@@ -736,9 +736,8 @@ fn main() {
     // **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
-    // (wow-re `ui/scratch/xml-toc-path-resolution.md` §4). Nothing is subtracted from the headline
-    // — 1213 — so both readings stay available.
+    // 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.
     let own: Vec<&addon_harness::AddonReport> = reports
         .iter()
         .filter(|r| !r.absent_own_files.is_empty())
diff --git a/crates/benilla-app/src/addon_harness/mod.rs b/crates/benilla-app/src/addon_harness/mod.rs
index 1e2d0ba7..58ae5d98 100644
--- a/crates/benilla-app/src/addon_harness/mod.rs
+++ b/crates/benilla-app/src/addon_harness/mod.rs
@@ -115,10 +115,9 @@ pub struct AddonReport {
     /// 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 (wow-re
-    /// `ui/scratch/xml-toc-path-resolution.md` §4, VERIFIED). 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.
+    /// 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
@@ -144,11 +143,11 @@ pub struct AddonReport {
     ///
     /// 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 wow-re records as
-    /// **RESOLVING** in the real client (`ui/scratch/xml-toc-path-resolution.md` §5 case 2, by
-    /// name), 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.
+    /// 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.
     pub absent_foreign_files: Vec<String>,
     /// Names it calls that the VM does not have — see the module doc on what this is worth.
     pub missing_globals: Vec<String>,
@@ -1812,6 +1811,7 @@ fn seat_a_session(script: &mut UiScript) {
         script.set_quest_log(QuestLogState {
             entries: vec![header, in_progress, done],
             num_quests: 2,
+            hidden_quest_ids: Vec::new(),
         });
     }
 
@@ -2083,11 +2083,10 @@ struct FileLoad {
     ///
     /// 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 (wow-re
-    /// `ui/scratch/xml-toc-path-resolution.md` §4, VERIFIED — 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.
+    /// 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.
     raised: bool,
 }
 
@@ -2106,10 +2105,10 @@ fn load_addon_files(script: &UiScript, root: &Path, name: &str, toc: &Toc) -> Fi
         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 (wow-re `ui/scratch/xml-toc-path-resolution.md` §2), 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.
+            // 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.
             let own = path
                 .strip_prefix(base.as_str())
                 .is_some_and(|rest| rest.starts_with('/'));
@@ -4134,12 +4133,12 @@ mod dependency_tests {
     ///   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` and carries on — wow-re `ui/scratch/xml-toc-path-resolution.md` §4).
+    ///   `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 wow-re records as
-    ///   **RESOLVING** in the real client (§5 case 2, by name) because its file layer can see that
-    ///   folder inside `patch.MPQ`. That one IS ours.
+    ///   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.
@@ -4275,9 +4274,9 @@ mod dependency_tests {
         // **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
-        // (`ui/scratch/xml-toc-path-resolution.md` §4). Both halves are asserted together,
-        // because either one alone is a rule that has already been got wrong in both directions.
+        // `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.
         for r in [short, wants] {
             assert!(
                 r.loaded,
@@ -4405,6 +4404,7 @@ mod dependency_tests {
     /// was an `inherits=` in their own XML, none of which appeared in the `CreateFrame` ranking.
     #[test]
     fn the_inherits_census_counts_templates_and_not_fonts() {
+        benilla_formats::wow_data_or_skip!();
         let tmp =
             std::env::temp_dir().join(format!("benilla-harness-inherits-{}", std::process::id()));
         let _ = std::fs::remove_dir_all(&tmp);
@@ -4572,6 +4572,7 @@ mod dependency_tests {
     /// which is exactly why the old table could not see any of it.
     #[test]
     fn the_per_kind_census_finds_a_verb_wired_to_the_wrong_kind() {
+        benilla_formats::wow_data_or_skip!();
         let tmp =
             std::env::temp_dir().join(format!("benilla-harness-perkind-{}", std::process::id()));
         let _ = std::fs::remove_dir_all(&tmp);
@@ -4969,6 +4970,7 @@ mod dependency_tests {
     /// rather than a guess.
     #[test]
     fn a_published_name_carries_its_kind() {
+        benilla_formats::wow_data_or_skip!();
         let script = seated_vm();
         assert_eq!(script.widget_kind("UIErrorsFrame"), Some("MessageFrame"));
         assert_eq!(script.widget_kind("UIParent"), Some("Frame"));
@@ -5093,6 +5095,7 @@ mod dependency_tests {
     /// (see `drive_ui_probe`'s own comment), and a probe that cannot fail is not a probe.
     #[test]
     fn the_ui_probe_hovers_and_records_what_a_tooltip_hook_raises() {
+        benilla_formats::wow_data_or_skip!();
         let mut script = UiScript::new().unwrap();
         script.set_screen_size(1024.0, 768.0);
         seat_a_session(&mut script);
diff --git a/crates/benilla-app/src/addon_harness/render.rs b/crates/benilla-app/src/addon_harness/render.rs
index 8bf1e496..58a5b178 100644
--- a/crates/benilla-app/src/addon_harness/render.rs
+++ b/crates/benilla-app/src/addon_harness/render.rs
@@ -34,7 +34,7 @@
 //!
 //! - **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 (the contract §7). Over-reporting is the deliberate
+//!   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
diff --git a/crates/benilla-app/src/addon_harness/render_tests.rs b/crates/benilla-app/src/addon_harness/render_tests.rs
index fa147c27..379b5c60 100644
--- a/crates/benilla-app/src/addon_harness/render_tests.rs
+++ b/crates/benilla-app/src/addon_harness/render_tests.rs
@@ -87,6 +87,7 @@ impl Drop for Fixtures {
 /// not — and "creates a frame" is not "paints".
 #[test]
 fn the_render_column_can_fail() {
+    benilla_formats::wow_data_or_skip!();
     let fx = Fixtures::new("cannotfail");
     // Paints: a texture on a window of its own.
     fx.addon(
@@ -179,22 +180,6 @@ fn the_render_column_can_fail() {
     );
 }
 
-/// Where the corpus might be — the `ui_chat::ace_gate_tests` resolver, so a machine without the
-/// third-party corpus skips rather than reddens.
-fn corpus() -> Option<PathBuf> {
-    if let Some(over) = std::env::var_os("BENILLA_ADDON_CORPUS") {
-        let p = PathBuf::from(over);
-        if p.is_dir() {
-            return Some(p);
-        }
-    }
-    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
-    (2usize..=4)
-        .filter_map(|up| manifest.ancestors().nth(up))
-        .map(|root| root.join("wow-addons-vanilla"))
-        .find(|c| c.is_dir())
-}
-
 /// **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
@@ -209,10 +194,9 @@ fn corpus() -> Option<PathBuf> {
 /// If this test ever disagrees with the director's eyes, **the test is wrong**.
 #[test]
 fn the_directors_two_verified_addons_come_out_on_opposite_sides() {
-    let Some(corpus) = corpus() else {
-        eprintln!("skipping: no vanilla addon corpus (set $BENILLA_ADDON_CORPUS)");
-        return;
-    };
+    benilla_formats::wow_data_or_skip!();
+    // The one resolver, and 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.
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 50ffff56..7788e77e 100644
--- a/crates/benilla-app/src/addon_harness/use_probe_tests.rs
+++ b/crates/benilla-app/src/addon_harness/use_probe_tests.rs
@@ -248,22 +248,6 @@ fn the_use_column_can_fail() {
     );
 }
 
-/// Where the corpus might be — the same resolver `render_tests` uses, so a machine without the
-/// third-party corpus skips rather than reddens.
-fn corpus() -> Option<PathBuf> {
-    if let Some(over) = std::env::var_os("BENILLA_ADDON_CORPUS") {
-        let p = PathBuf::from(over);
-        if p.is_dir() {
-            return Some(p);
-        }
-    }
-    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
-    (2usize..=4)
-        .filter_map(|up| manifest.ancestors().nth(up))
-        .map(|root| root.join("wow-addons-vanilla"))
-        .find(|c| c.is_dir())
-}
-
 /// **The real oracle: the director's two verified addons.**
 ///
 /// - `!OmniCC` **works** — its countdown numbers are on their screen. It must not be reported as
@@ -278,10 +262,9 @@ fn corpus() -> Option<PathBuf> {
 ///   silently stops touching them is exactly how this instrument has been wrong four times.
 #[test]
 fn the_directors_two_verified_addons_are_reachable_and_omnicc_is_not_broken() {
-    let Some(corpus) = corpus() else {
-        eprintln!("skipping: no vanilla addon corpus (set $BENILLA_ADDON_CORPUS)");
-        return;
-    };
+    benilla_formats::wow_data_or_skip!();
+    // The one resolver, and 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"] {
         // MONKEY (volumetric fog): share the portable fixture used by the render oracle.
diff --git a/crates/benilla-app/src/area.rs b/crates/benilla-app/src/area.rs
index 756e323b..f599708b 100644
--- a/crates/benilla-app/src/area.rs
+++ b/crates/benilla-app/src/area.rs
@@ -3,8 +3,8 @@
 //! `GetMinimapZoneText`/`GetZonePVPInfo` (decision 0287; corrected to the bytes by its fold-back
 //! record).
 //!
-//! Byte-verified model (wow-re ui `zonetext-pvpinfo.md`; `0x494780` is the one updater all three
-//! zone events fire from, on the per-update area resolve):
+//! The model (`0x494780` is the one updater all three zone events fire from, on the per-update
+//! area resolve):
 //!
 //! - The client caches `(zoneId, zoneText, subzoneText)` and compares per update: **zone id
 //!   changed → `ZONE_CHANGED_NEW_AREA` fires alone**; else **either text changed →
@@ -23,10 +23,10 @@
 //!   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`] — wow-re `zonetext-indoor-bit.md`, the CGLight
-//!   node's `+0x90` bit 0): 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` (d), byte-pinned by (d-ii)): while indoors and the hit
+//!   ([`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
@@ -43,9 +43,7 @@
 //! 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. wow-re carved it as
-//! `system/ui/scratch/worldmap-selection-autosync.md`, correcting this note's own earlier source,
-//! which had dismissed the call as unrelated.
+//! than off the cache below.
 //!
 //! 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
@@ -110,9 +108,8 @@ struct ZoneCache {
     minimap_text: String,
     /// The previous update's indoor bit (`[0x868608]`).
     indoor: bool,
-    /// The previous hit group's identity (`[0x86860c]` — the client stores the group index,
-    /// (d-ii); we scope the MOGP uniqueID by WMO): same group while indoors ⇒ the whole updater
-    /// is skipped.
+    /// 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.
     wmo_id: u32,
     wmo_group: u32,
 }
@@ -181,13 +178,13 @@ fn feed_zone_events(
         leaf_row.name.clone()
     };
 
-    // The indoor naming (`0x67e670` (d)/(d-ii), module doc): dedup-skip while the hit group
+    // 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 — (d-ii)). We key the MOGP uniqueID scoped by WMO id: it changes exactly
+        // 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.
         wmo_group = k.group_area_id;
@@ -400,7 +397,7 @@ mod tests {
         );
     }
 
-    /// The indoor naming law (`0x67e670` (d)) against the REAL abbey/inn data shapes — the
+    /// 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.
     #[test]
@@ -419,7 +416,7 @@ mod tests {
             group.area_table_id, 24,
             "the leaf stays Northshire Abbey (24)"
         );
-        // The dedup rides the hit-group identity ((d-ii): the client's group index; our MOGP
+        // 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.
         let library = cat.group_row(59, 1, 1943).expect("library row");
         assert_ne!(group.id, library.id, "distinct rows exist per room");
diff --git a/crates/benilla-app/src/area_trigger.rs b/crates/benilla-app/src/area_trigger.rs
index 4e3f74f7..1ef12615 100644
--- a/crates/benilla-app/src/area_trigger.rs
+++ b/crates/benilla-app/src/area_trigger.rs
@@ -13,8 +13,7 @@
 //!
 //! ## The law, from the reference
 //!
-//! **VERIFIED** against `0x5e2110` (the per-frame check) and `0x5e22d0` (containment), wow-5875-re
-//! `object-layer/scratch/w2b1-decomp.c`; the geometry itself is
+//! 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
diff --git a/crates/benilla-app/src/aura_visual.rs b/crates/benilla-app/src/aura_visual.rs
index 693fe426..7f4c01f2 100644
--- a/crates/benilla-app/src/aura_visual.rs
+++ b/crates/benilla-app/src/aura_visual.rs
@@ -9,7 +9,7 @@
 //! kit carries no effect models and no anim at all — its entire visual is one CharProc — so the
 //! effects-only watcher resolved the kit, found an empty slot list, and dropped it on the floor.
 //!
-//! ## The mechanism (VERIFIED — wow-re `ghost-death-visuals.md` §2, `state-kit-aura-lifecycle.md`)
+//! ## The mechanism
 //!
 //! `UNIT_FIELD_AURA` slot change → the aura watcher `0x604d00` → `0x6123f0` → **`0x5ff350`
 //! PlayAuraStateVisual**: the slot's spell → `Spell.dbc` → `SpellVisual` → **field 4 = the state
@@ -21,10 +21,9 @@
 //! - **proc 14 = translucency** (`0x60d972`): the param becomes a node keyed by spell id
 //!   (`node+0x18`, value at `node+0x78`), linked at the HEAD of the unit's list `unit+0xb50`. The
 //!   unit's effective alpha is then recomputed by `0x60d180` as **`baseAlpha × the head node's
-//!   factor`** — at most one node term, never a product over the chain (wow-re
-//!   `base-render-alpha.md` §4, correcting this note's earlier `Π` gloss) — `baseAlpha` from the
+//!   factor`** — at most one node term, never a product over the chain — `baseAlpha` from the
 //!   vtbl+0x6c getter `0x60d2d0` (`CreatureDisplayInfo+0x14 × 1/255`, the SAME slot in the unit
-//!   and player vtables: "players 1.0" was the data talking, not a type fork — §6) — and handed
+//!   and player vtables: a player's 1.0 is the data talking, not a type fork) — and handed
 //!   to **`0x614f80` StartAlphaFade(target, 1000 ms)**, the same ramp block (`+0xec..0x100`) and
 //!   the same `clamp01(t)³` ease (`0x614a90`) our appear-fade already rides
 //!   ([`benilla_world::model_fade::fade_alpha`]). Per frame `model+0x180 = master × fade`
@@ -41,10 +40,10 @@
 //!
 //! The vis-flag is a decoy and must not be used here: `UNIT_FIELD_BYTES_1` byte 3's CREEP (stealth)
 //! and GHOST bits drive **no** body render at all — an exhaustive census of every `+0x213` reference
-//! found three sites, all nameplate/marker suppression (wow-re `ghost-death-visuals.md` §1). The two
-//! co-travel only because the server sets the flag and the aura from the same spell. Keying the body
-//! off the flag would be the wrong mechanism that happens to look right on stealth and then fails on
-//! every other member of the family.
+//! found three sites, all nameplate/marker suppression (`0x5ff80d`, `0x607101`, `0x60f62e`). The
+//! two co-travel only because the server sets the flag and the aura from the same spell. Keying
+//! the body off the flag would be the wrong mechanism that happens to look right on stealth and
+//! then fails on every other member of the family.
 //!
 //! ## The shipped data (read from the real 5875 `SpellVisualKit.dbc` this session —
 //! `benilla-extract charprocs` censuses it)
@@ -96,7 +95,7 @@
 //!
 //! Types 2, 7 and 13 also appear on state kits (Berserk/Bloodlust's 2, the Sap/Feign-Death 7, the
 //! "Glowy (Red)" 13) and have **no verified mechanism** — they fall through [`node_for`]'s single `_`
-//! arm, which is where each lands as one match arm the day its RE returns.
+//! arm, which is where each lands as one match arm the day its mechanism is known.
 
 use benilla_protocol::EntityKind;
 use bevy::mesh::MeshTag;
@@ -154,10 +153,9 @@ pub(crate) struct AuraNodes {
     /// driver's own again.
     rate: Vec<(u32, f32)>,
     /// `baseAlpha`: the display row's `CreatureModelAlpha / 255` — for EVERY unit, players
-    /// included; the getter `0x60d2d0` has no type fork, a normal character's row just says 255
-    /// (`base-render-alpha.md` §6, correcting the "players 1.0" gloss). Owned by
-    /// [`refresh_base_alpha`], which re-resolves it on every display-id change (a shapeshift
-    /// swaps it live) and ramps to the new value.
+    /// included; the getter `0x60d2d0` has no type fork, a normal character's row just says 255.
+    /// Owned by [`refresh_base_alpha`], which re-resolves it on every display-id change (a
+    /// shapeshift swaps it live) and ramps to the new value.
     base: f32,
     /// Where the ramp is now — what the parts actually render at.
     current: f32,
@@ -188,8 +186,8 @@ impl AuraNodes {
 
     /// The reference's `0x60d180`: `baseAlpha × the HEAD alpha node's factor` — at most ONE node
     /// term, skipped entirely when the list is empty (`0x60d195 je`), never a product over the
-    /// chain (wow-re `base-render-alpha.md` §4, correcting `ghost-death-visuals.md`'s `Π` gloss).
-    /// Nodes are linked at the head as they install, so the newest one is the term that counts.
+    /// chain. Nodes are linked at the head as they install, so the newest one is the term that
+    /// counts.
     fn target(&self) -> f32 {
         let head = self.alpha.first().map_or(1.0, |(_, f)| *f);
         (self.base * head).clamp(0.0, 1.0)
@@ -365,7 +363,7 @@ pub(crate) struct AnimRateFreeze;
 /// inherit the freeze and outlive it.
 ///
 /// **Reasserted every frame, and that is the faithful shape, not a belt-and-braces clamp.** The
-/// reference's rate lives on the bone (`+0xb0`, the factor `timebase.md` §2's clock multiplies its
+/// reference's rate lives on the bone (`+0xb0`, the factor the clock at `0x71458e` multiplies its
 /// window by) and **arming an animation does not touch it**: op4 `0x7121a0`'s success leg writes the
 /// track index and the cursors and leaves `+0xb0` alone (only its disarm leg and `SetBoneAnimSpeed
 /// 0x712910` write it). So "rate 0 until the aura is reaped" is literally the reference's state
@@ -493,7 +491,7 @@ pub(crate) fn node_for(proc: benilla_formats::CharProc) -> Option<AuraNode> {
 ///
 /// `base_alpha` here only SEEDS a node set created by an aura edge — its steady-state owner is
 /// [`refresh_base_alpha`], which re-resolves it on every display change. The getter is the same
-/// for players and creatures (the display row's `CreatureModelAlpha`; `base-render-alpha.md` §6).
+/// for players and creatures (the display row's `CreatureModelAlpha`, read by `0x60d2d0`).
 /// A unit whose display is unknown falls back to `1.0` — opaque, i.e. the aura's factor alone,
 /// which is the safe direction (the alternative would hide a unit whose row simply failed to
 /// load).
@@ -566,9 +564,8 @@ fn reap(n: &mut AuraNodes, spell_id: u32, now: f32) {
 
 /// Install one spell's nodes, replacing any it already had (an aura re-applied by a second caster
 /// holds a second slot but installs one node set — the reference's own per-spell-id keying).
-/// New nodes link **at the head** (`base-render-alpha.md` §4: the newest node is the one the
-/// recompute reads), which is why both lists insert at the front here and both readers take
-/// `.first()`.
+/// New nodes link **at the head** (the newest node is the one the recompute `0x60d180` reads),
+/// which is why both lists insert at the front here and both readers take `.first()`.
 fn install(n: &mut AuraNodes, spell_id: u32, procs: &[AuraNode], now: f32) {
     n.alpha.retain(|(s, _)| *s != spell_id);
     n.tint.retain(|(s, _)| *s != spell_id);
@@ -587,7 +584,7 @@ fn install(n: &mut AuraNodes, spell_id: u32, procs: &[AuraNode], now: f32) {
 /// the spell, the nodes it installed, and the target the ramp is now aiming at.
 ///
 /// This is how "stealth shows nothing" is *reproduced and then closed* without eyeballing a capture
-/// (`method.md` §5/§6): with the aura layer dead the trace is silent on `.cast 1784`; with it live
+/// (`docs/METHOD.md` §5/§6): with the aura layer dead the trace is silent on `.cast 1784`; with it live
 /// the same press prints `aur arm spell=1784 alpha=[0.3] -> base 1.00 target 0.30`, and the drop
 /// prints the ramp back to 1.00. It rides the shared move-trace sink so an aura edge interleaves on
 /// one timeline with the movement/anim lines — a "why did it not fade when I moved" question needs
@@ -616,10 +613,9 @@ fn trace_edge(what: &str, entity: Entity, spell_id: u32, n: &AuraNodes) {
 
 /// `baseAlpha` for a unit — the getter `0x60d2d0`: its CURRENT display row's
 /// `CreatureModelAlpha / 255`, for **every** unit kind. There is no player override — the same
-/// vtable slot in both classes, byte-identical (`base-render-alpha.md` §6); an unshifted
-/// character reads 1.0 only because its row (49, 50, …) says 255, and a shaman wearing Ghost
-/// Wolf's display 4613 reads 102/255 = 0.4 through exactly this path. No row → 1.0 (the
-/// `0x60d2e4` NULL fallback).
+/// vtable slot in both classes, byte-identical; an unshifted character reads 1.0 only because its
+/// row (49, 50, …) says 255, and a shaman wearing Ghost Wolf's display 4613 reads 102/255 = 0.4
+/// through exactly this path. No row → 1.0 (the `0x60d2e4` NULL fallback).
 fn base_alpha(
     entity: Entity,
     units: &Query<&crate::net::NetEntity>,
@@ -646,7 +642,7 @@ fn display_base_alpha(
 }
 
 /// Re-resolve every unit's base alpha when its display changes — the reference's DISPLAYID
-/// watcher path (`base-render-alpha.md` §5: `0x604990 → 0x60abe0 → 0x60afb0` caches the row →
+/// watcher path (`0x604990 → 0x60abe0 → 0x60afb0` caches the row →
 /// `0x60ad9f → 0x60d180 → StartAlphaFade(target, 1000 ms)`), self-gated on a real record change
 /// (`0x60ae10`). This is what makes a unit with `CreatureModelAlpha < 255` translucent with **no
 /// aura in play** — the shifted shaman's ghost look — and what ramps it back to opaque when the
diff --git a/crates/benilla-app/src/aura_visual/tests.rs b/crates/benilla-app/src/aura_visual/tests.rs
index 6512b1a0..faca4011 100644
--- a/crates/benilla-app/src/aura_visual/tests.rs
+++ b/crates/benilla-app/src/aura_visual/tests.rs
@@ -66,8 +66,8 @@ fn the_dispatch_names_only_the_verified_procs() {
         Some(AuraNode::Alpha(0.0)),
         "kit 5129's 0.0 is a real value, not an absent one"
     );
-    // 9222653 = 0x8CB9FD — the ghost's pale blue-white, byte-cited in wow-re as 0xFF8CB9FD after the
-    // client ORs the opaque byte on.
+    // 9222653 = 0x8CB9FD — the ghost's pale blue-white, 0xFF8CB9FD once the client ORs the opaque
+    // byte on (`0x60d8cc`).
     assert_eq!(
         node_for(proc(char_proc_type::TINT, 9_222_653.0)),
         Some(AuraNode::Tint([0x8C, 0xB9, 0xFD])),
@@ -99,10 +99,9 @@ fn the_dispatch_names_only_the_verified_procs() {
 // ── The target and the ramp ──────────────────────────────────────────────────────────────────────
 
 /// `0x60d180`: the target is `baseAlpha × the HEAD node's factor` — at most one node term, the
-/// newest (nodes link at the list head as they install), never a product over the chain (wow-re
-/// `base-render-alpha.md` §4, correcting the earlier `Π` reading). Stacking stealth (0.3) then the
-/// ghost aura (0.5) reads 0.5 — whichever landed last — and dropping the head hands the term to
-/// the next node down.
+/// newest (nodes link at the list head as they install), never a product over the chain.
+/// Stacking stealth (0.3) then the ghost aura (0.5) reads 0.5 — whichever landed last — and
+/// dropping the head hands the term to the next node down.
 #[test]
 fn the_target_is_base_times_the_newest_node() {
     let mut n = AuraNodes::new(1.0);
@@ -135,7 +134,7 @@ fn the_target_is_base_times_the_newest_node() {
 
 /// The display-swap leg ([`refresh_base_alpha`]'s retarget): a base change rides the same 1000 ms
 /// cubic ramp an aura node does — Ghost Wolf's 102/255 eases in from opaque, and swapping home
-/// eases back — never snaps (`base-render-alpha.md` §5: the fade is part of the mechanism).
+/// eases back — never snaps (the fade, `0x614f80`, is part of the mechanism).
 #[test]
 fn a_base_change_rides_the_same_ramp() {
     let wolf = 102.0 / 255.0;
diff --git a/crates/benilla-app/src/bindings.rs b/crates/benilla-app/src/bindings.rs
index 6379fd1e..ef50cf06 100644
--- a/crates/benilla-app/src/bindings.rs
+++ b/crates/benilla-app/src/bindings.rs
@@ -42,7 +42,7 @@
 //! on the confirmed switch back to general — the reference's own semantics.
 
 use bevy::input::keyboard::KeyboardInput;
-use bevy::input::mouse::AccumulatedMouseScroll;
+use bevy::input::mouse::{AccumulatedMouseScroll, MouseScrollUnit};
 use bevy::input::ButtonState;
 use bevy::prelude::*;
 
@@ -434,6 +434,51 @@ 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.
+pub(crate) fn wheel_lines(unit: MouseScrollUnit, dy: f32) -> f32 {
+    match unit {
+        MouseScrollUnit::Line => dy,
+        MouseScrollUnit::Pixel => dy / MouseScrollUnit::SCROLL_UNIT_CONVERSION_FACTOR,
+    }
+}
+
+/// **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.
+#[derive(Default, Resource)]
+pub(crate) struct WheelNotches {
+    carry: f32,
+}
+
+impl WheelNotches {
+    /// Add `lines` of travel; returns the signed whole notches it completes (usually 0 or ±1).
+    pub(crate) fn feed(&mut self, lines: f32) -> i32 {
+        if lines == 0.0 || !lines.is_finite() {
+            return 0;
+        }
+        if self.carry != 0.0 && self.carry.signum() != lines.signum() {
+            self.carry = 0.0;
+        }
+        self.carry += lines;
+        let whole = self.carry.trunc();
+        self.carry -= whole;
+        whole as i32
+    }
+}
+
 /// 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).
 fn latch_and_dispatch(
@@ -540,8 +585,7 @@ fn latch_and_dispatch(
     // 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 (wow-re `loading-screen-input-law.md`; the
-    // conflated phrasing was `rf79-autorun-cancel-set.md`'s "Chat EditBox / window focus" row).
+    // 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
@@ -681,19 +725,14 @@ 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` (wow-re `system/ui/ui.md` §3, VERIFIED) — so a `runOnUp` command
+    // `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 so the zoom consumer's
-    // feel is unchanged from when it read the scroll itself.
-    let wheel = match scroll.unit {
-        bevy::input::mouse::MouseScrollUnit::Line => scroll.delta.y,
-        bevy::input::mouse::MouseScrollUnit::Pixel => {
-            scroll.delta.y / bevy::input::mouse::MouseScrollUnit::SCROLL_UNIT_CONVERSION_FACTOR
-        }
-    };
+    // 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.
+    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
@@ -891,9 +930,10 @@ fn release(
 /// **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`, RF-0025). 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.
+/// 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.
@@ -1119,10 +1159,9 @@ mod tests {
     /// 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 §5
-    /// (`ignorearrows-alt-arrow-gate.md`) 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.
+    /// 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.
     #[test]
     fn a_flagged_editbox_lets_the_arrow_keys_through_to_their_bindings() {
         let mut app = harness();
@@ -1272,6 +1311,7 @@ mod tests {
     /// tests carry no page — between them the join was never asserted.
     #[test]
     fn a_wheel_notch_binds_through_the_real_page_and_then_dispatches() {
+        benilla_formats::wow_data_or_skip!();
         let by_name =
             |n: &str| Cmd(SPECS.iter().position(|s| s.name == n).expect("registered") as u16);
         let mut s = crate::ui_script::keybindings_tests::harness();
diff --git a/crates/benilla-app/src/bindings/chord.rs b/crates/benilla-app/src/bindings/chord.rs
index e67a43c7..7687d86b 100644
--- a/crates/benilla-app/src/bindings/chord.rs
+++ b/crates/benilla-app/src/bindings/chord.rs
@@ -176,8 +176,8 @@ pub(crate) fn key_token(k: KeyCode) -> Option<&'static str> {
         // **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"`; wow-re's
-        // `keycode-origin-law.md` settled it at the bytes.) macOS has no PrintScreen keycode at
+        // (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.
         #[cfg(target_os = "macos")]
@@ -252,10 +252,10 @@ pub(crate) fn key_token(k: KeyCode) -> Option<&'static str> {
         NumpadEqual => "NUMPADEQUALS",
         NumLock => "NUMLOCK",
         PrintScreen => "PRINTSCREEN",
-        // ScrollLock and Pause are deliberately absent: the reference's namer calls their key
-        // codes (`0x210`/`0x211`) `UNKNOWN`, so they are unbindable there (wow-re
-        // `keybinding-dispatch-law.md` §2.3), and `IsValidBindingKeyString` would refuse the
-        // names anyway — arm 4's 26-name table holds neither.
+        // 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.
         CapsLock => "CAPSLOCK",
         Minus => "-",
         Equal => "=",
diff --git a/crates/benilla-app/src/bindings/commands.rs b/crates/benilla-app/src/bindings/commands.rs
index 68ba9173..b1441b8b 100644
--- a/crates/benilla-app/src/bindings/commands.rs
+++ b/crates/benilla-app/src/bindings/commands.rs
@@ -1149,10 +1149,10 @@ const TABLE: &[Spec] = &[
     // 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` (wow-re's
-    // dispatch on this feature; 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`).
+    // 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.
@@ -2219,6 +2219,7 @@ mod tests {
     /// here as the witness for it.
     #[test]
     fn the_global_scanner_sees_both_kinds_of_definition() {
+        benilla_formats::wow_data_or_skip!();
         let defined = lua_globals_defined();
         for host in ["TargetUnit", "UseAction", "SetBinding"] {
             assert!(
@@ -2252,6 +2253,38 @@ 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.
+    #[test]
+    fn the_installs_bindings_xml_reads_as_the_parsers_header_says() {
+        let Some(binds) = install_bindings() else {
+            return;
+        };
+        assert_eq!(
+            binds.len(),
+            228,
+            "1.12.1 ships 228 live bindings — the other six are inside a comment"
+        );
+        assert!(binds.iter().all(|b| !b.name.is_empty()));
+        assert!(
+            !binds.iter().any(|b| b.name.starts_with("MOVEVIEW")),
+            "the commented-out family must not register"
+        );
+        assert_eq!(binds.iter().filter(|b| b.run_on_up).count(), 94);
+        assert_eq!(binds.iter().filter(|b| b.header.is_some()).count(), 13);
+        assert_eq!(binds.iter().filter(|b| b.hidden).count(), 12);
+        assert_eq!(
+            binds[0].header.as_deref(),
+            Some("MOVEMENT"),
+            "the file opens on the MOVEMENT section"
+        );
+    }
+
     /// The install's own `Bindings.xml`, parsed — `None` (and a skipped test) without a client.
     fn install_bindings() -> Option<Vec<benilla_ui::bindings_xml::AddonBinding>> {
         let data = benilla_formats::wow_data_or_skip!(None);
diff --git a/crates/benilla-app/src/blob_shadow.rs b/crates/benilla-app/src/blob_shadow.rs
index 27936f21..498a8bb1 100644
--- a/crates/benilla-app/src/blob_shadow.rs
+++ b/crates/benilla-app/src/blob_shadow.rs
@@ -2,8 +2,7 @@
 //! 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 byte-verified mechanism** (wow-re `unit-blob-shadow.md`, a §5 cross-check; the "cloud
-//! shadow" label on `0x6d7920` was corrected — it IS the unit shadow draw):
+//! **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
@@ -11,15 +10,12 @@
 //!   [`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` (wow-re `water-frame-straddle.md` §1 + `unit-blob-shadow.md` Q1). `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 (wow-re `decal-frame-slot.md`). That second step is **not** a gate:
-//!   both exits of the tick `0x481540` return 1, so `0x683ea5`'s `je` is dead — an earlier
-//!   reading of it as "the callback suppresses a hidden object's shadow" was wrong at the bytes
-//!   and is corrected in wow-re (2026-09-06). 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
+//!   `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
@@ -29,17 +25,17 @@
 //! - **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 an open RE item (apitrace) — here the ramp is the vertex-alpha vertical fade below.
+//!   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; wow-re `27406d9b`, Q3-ORACLE): the draw re-reads
+//!   (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 the trace oracle confirmed — 1,682 measured
+//!   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
@@ -51,7 +47,7 @@
 //!   touched at exactly three `mov ecx,ebx; call` sites (box `0x711a20`, matrix `0x710600`,
 //!   alpha `0x710ca0`), which makes that list the complete field census.
 //!
-//!   **What rides in, at the bytes** (wow-re, 2026-09-06): the 2 s appear ramp and the despawn
+//!   **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
@@ -70,7 +66,7 @@
 //! - **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 (wow-re, 2026-09-06 — the old `HANDOFF(-> object-layer)` is closed):
+//!   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
@@ -108,7 +104,7 @@ use benilla_world::particles::buffer::{begin_effect_frame, EffectVertex};
 use benilla_world::view::WorldCamera;
 use benilla_world::wmo_portal::UnitWmoRoom;
 
-/// The reference's shadow disc (`Textures\ShadowBlob.blp`, wow-re unit-blob-shadow RE): grayscale
+/// 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.
 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
@@ -183,8 +179,8 @@ fn setup_shadow_assets(mut commands: Commands, asset_server: Res<AssetServer>) {
 
 /// 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 the open RE item; this is the v1 set
-/// (see module docs).
+/// destroyed / streamed out). The registration *policy* is still open; this is the v1 set (see
+/// module docs).
 #[allow(clippy::type_complexity)] // the filtered spawn-gate query, commented inline
 fn sync_shadows(
     mut commands: Commands,
@@ -277,7 +273,7 @@ fn update_shadows(
     // 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 a wow-re shadow-consumer trace pins it.
+    // until that source is known.
     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
@@ -351,7 +347,7 @@ fn update_shadows(
             Some((mnet, manims)) => (manims, mnet.scale),
             None => (anims, 1.0),
         };
-        // The byte+pixel law (0316, wow-re 27406d9b): the box is playableAnimationLookup[0]'s
+        // 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.
@@ -521,8 +517,9 @@ fn update_shadows(
                 .map(|v| format!("({:.3},{:.3})", v.uv[0], v.uv[1]))
                 .collect();
             debug!("self shadow uvs: {}", uvs.join(" "));
-            // And the box/rect numbers: the oracle says HumanFemale's footprint is 0.77x0.74 yd
-            // nearly centred; a bigger or offset rect indicts the box math, not the projector.
+            // 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.
             debug!(
                 "self shadow box: bmin {:?} bmax {:?} rect x [{:.3}, {:.3}] z [{:.3}, {:.3}] \
                  (extent {:.3}x{:.3}, centre offset ({:.3}, {:.3}))",
diff --git a/crates/benilla-app/src/bowstring.rs b/crates/benilla-app/src/bowstring.rs
index 617a477d..ff3d0467 100644
--- a/crates/benilla-app/src/bowstring.rs
+++ b/crates/benilla-app/src/bowstring.rs
@@ -1,14 +1,13 @@
-//! The engine-drawn **bowstring** (wow-re `nocked-ammo-cancel.md` §G2, byte-verified): 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 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.
 //!
 //! 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 the round didn't decode — a dark cord is used).
+//! 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
@@ -21,7 +20,7 @@ use bevy::prelude::*;
 use crate::creature_anim::NockLatch;
 use crate::entities::BoneAttach;
 
-/// The HandArrow attach id (35 — wow-re §E2/G2): the string's middle control point while nocked,
+/// The HandArrow attach id (35 — `0x6121b8`): the string's middle control point while nocked,
 /// the same point the nocked-arrow model rides.
 const HAND_ARROW: u16 = 0x23;
 
@@ -55,7 +54,7 @@ fn draw_bowstrings(
     joints: Query<&GlobalTransform>,
     mut gizmos: Gizmos,
 ) {
-    // A dark waxed-cord tone; the ref's packed vertex color is not decoded (INFERRED, §G2).
+    // A dark waxed-cord tone, inferred: the ref'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() {
diff --git a/crates/benilla-app/src/camera_shake.rs b/crates/benilla-app/src/camera_shake.rs
index 2394a9f3..b5f56132 100644
--- a/crates/benilla-app/src/camera_shake.rs
+++ b/crates/benilla-app/src/camera_shake.rs
@@ -3,8 +3,8 @@
 //!
 //! **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, wow-re `spell/scratch/camera-shake-producers.md` §Q4: no address-dword reference to
-//! it anywhere, and no Lua, console, cinematic or quake path).
+//! xref sweep: no address-dword reference to it anywhere, and no Lua, console, cinematic or quake
+//! path).
 //!
 //! The **creature** pair names a `CameraShakes.dbc` preset **directly**:
 //!
@@ -33,7 +33,7 @@
 //! 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 (wow-re `ui/scratch/camera-shake-law.md`, §5-verified)
+//! ## 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`
@@ -171,7 +171,7 @@ 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`, wow-re `camera-shake-law.md` §6): the followed unit
+    /// (`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
@@ -221,7 +221,7 @@ impl LiveShake {
     /// 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 — per wow-re's reading of the accumulator's stored slot.
+    /// not swing with the sine — the stored slot 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 {
@@ -404,7 +404,7 @@ fn fire_shakes(
 /// 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 (the contract §3, `method.md` step 3); the reference's own numbers are
+/// 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.
 fn fire_kit_shakes(
@@ -451,14 +451,14 @@ type FollowedUnit = (
 /// **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`], RF-0057 `0x5fd19c`) — the reference re-reads
+/// 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"** (wow-re `swim-transition.md`) —
+/// **`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
diff --git a/crates/benilla-app/src/capture/depth_probe.rs b/crates/benilla-app/src/capture/depth_probe.rs
index d79689ac..3f06b9d1 100644
--- a/crates/benilla-app/src/capture/depth_probe.rs
+++ b/crates/benilla-app/src/capture/depth_probe.rs
@@ -200,7 +200,8 @@ struct QuadProbe {
     corners: [Vec2; 4],
     /// The NDC depth the corners carry. Read from the projected corners, not assumed constant —
     /// the *spread* is reported, because a billboard that is not a constant-depth plane is a
-    /// different bug wearing the same symptom (wow-re `part-flush-emitter-depth.md` §4).
+    /// different bug wearing the same symptom (`0x7b2a50`'s plain billboard gives all four
+    /// corners one depth).
     dquad: f32,
     dspread: f32,
     /// The quad centre's distance to the camera plane, yards — the unit the burial is reported in.
diff --git a/crates/benilla-app/src/capture/fixtures.rs b/crates/benilla-app/src/capture/fixtures.rs
index 0e7e1315..595a64f2 100644
--- a/crates/benilla-app/src/capture/fixtures.rs
+++ b/crates/benilla-app/src/capture/fixtures.rs
@@ -42,7 +42,9 @@ pub(super) fn seed_ui_fixture(
     mut quest: ResMut<crate::ui_quest::QuestGiver>,
     mut quest_log: ResMut<crate::ui_quest_log::QuestLog>,
     mut loot: ResMut<crate::ui_loot::LootState>,
-    mut items: ResMut<crate::items::Items>,
+    // The item store and the object index as one param (the 16-SystemParam ceiling): the item
+    // objects are entities in the index (2334), and the fixture spawns them like the wire does.
+    store: (ResMut<crate::items::Items>, ResMut<crate::net::GuidIndex>),
     mut names: ResMut<crate::names::NameCache>,
     icons: Option<Res<crate::entities::ItemDisplays>>,
     mut script: Option<NonSendMut<benilla_ui::script::UiScript>>,
@@ -57,6 +59,7 @@ pub(super) fn seed_ui_fixture(
         ResMut<crate::loading_screen::LoadingScreen>,
     ),
 ) {
+    let (mut items, mut index) = store;
     // A glue-screen capture has no world scenario, and no glue screen opens a UI fixture.
     let Some(scenario) = ctx.scenario else {
         return;
@@ -72,7 +75,7 @@ pub(super) fn seed_ui_fixture(
     // **A UI capture with no script VM is not a capture — refuse it.** Every seed below opens its
     // window by calling into the in-game UI, so with no VM they all fail the same way: a nil
     // global, one `warn!` in a log full of pipeline chatter, a valid-looking PNG of a UI-less
-    // world, and exit 0. That is the false-negative shape `method.md` §6 exists to prevent, and it
+    // world, and exit 0. That is the false-negative shape `docs/METHOD.md` §6 exists to prevent, and it
     // burned a session. `scenario_wants_ui` removed the cause (a `ui:` scenario no longer needs
     // `WOW_CAPTURE_UI=1`); this is the tripwire for whatever else could leave the VM absent, and
     // it exits non-zero the way the window-size refusal does (`video::warn_if_window_mismatch`).
@@ -326,7 +329,7 @@ pub(super) fn seed_ui_fixture(
                 (G_STONE, 94_004, 1, "Hearthstone", DISP_STONE, 1),
                 (G_BANKBAG, 94_005, 1, "Small Brown Pouch", DISP_STONE, 1),
             ] {
-                items.insert_object(guid, obj(entry, stack));
+                crate::items::spawn_item(&mut commands, &mut index, guid, obj(entry, stack), false);
                 let mut t = template(name, quality);
                 t.display_info_id = disp;
                 if guid == G_BANKBAG {
@@ -338,7 +341,9 @@ pub(super) fn seed_ui_fixture(
             // The held bank bag is a real CONTAINER object (its contents stream on the bag item —
             // decision 0604): 6 slots, one occupied, so the POPOUT window (container 5) is in the
             // shot too — its snug-fit stitch, lit bag button, and own-icon portrait.
-            items.insert_object(
+            crate::items::spawn_item(
+                &mut commands,
+                &mut index,
                 G_BANKBAG,
                 ObjectFields::from_pairs(&[
                     (3, 94_005),
@@ -346,6 +351,7 @@ pub(super) fn seed_ui_fixture(
                     (48, 6),              // CONTAINER_NUM_SLOTS
                     (50, G_JERKY as u32), // CONTAINER_SLOT_1
                 ]),
+                true,
             );
             // The self player: 4 occupied vault slots, the bank bag, TWO bought bag slots
             // (`PLAYER_BYTES_2` byte 2 — bag button 1 owned, 2 bought-but-empty, 3–6 the red
@@ -717,7 +723,7 @@ pub(super) fn seed_ui_fixture(
             // Raised through the real registry entry, not a hand-built frame: the text comes from
             // the chain's own `INVITATION` GlobalString and the two buttons from ACCEPT/DECLINE,
             // so the capture exercises the same Show path a real invite takes.
-            if let Err(e) = script.run(r#"StaticPopup_Show("PARTY_INVITE", "Thalyn")"#) {
+            if let Err(e) = script.run(r#"StaticPopup_Show("PARTY_INVITE", "Brisca")"#) {
                 warn!("capture: ui-partyinvite seed failed to raise the dialog: {e}");
             }
         }
@@ -765,8 +771,8 @@ pub(super) fn seed_ui_fixture(
                     ..Default::default()
                 },
             );
-            // The §22 SET block (real Defias Leather shape, 5 members, one equipped): gold
-            // "(1/5)" header + spacer, cream/gray member ladder, green (2)-bonus vs gray
+            // The item-SET block (`0x52b650`; real Defias Leather shape, 5 members, one equipped):
+            // gold "(1/5)" header + spacer, cream/gray member ladder, green (2)-bonus vs gray
             // (4)-bonus — the whole block's visual regression instrument.
             let mut inv: benilla_ui::script::InventorySlots = Default::default();
             inv[4] = Some(benilla_ui::script::InvSlotView {
@@ -911,10 +917,10 @@ pub(super) fn seed_ui_fixture(
             let obj = |entry: u32, stack: u32| {
                 ObjectFields::from_pairs(&[(3, entry), (14, stack)]) // OBJECT_ENTRY, STACK_COUNT
             };
-            items.insert_object(G_CHEST, obj(93_010, 1));
-            items.insert_object(G_SWORD, obj(93_011, 1));
-            items.insert_object(G_BOW, obj(93_013, 1));
-            items.insert_object(G_ARROWS, obj(93_012, 200));
+            crate::items::spawn_item(&mut commands, &mut index, G_CHEST, obj(93_010, 1), false);
+            crate::items::spawn_item(&mut commands, &mut index, G_SWORD, obj(93_011, 1), false);
+            crate::items::spawn_item(&mut commands, &mut index, G_BOW, obj(93_013, 1), false);
+            crate::items::spawn_item(&mut commands, &mut index, G_ARROWS, obj(93_012, 200), false);
             let mut chest = template("Tarnished Chainmail", 1);
             chest.display_info_id = DISP_SHIELD;
             chest.inventory_type = 5;
@@ -1181,7 +1187,13 @@ pub(super) fn seed_ui_fixture(
                 crate::net::Guid(PLAYER_GUID),
             ));
             // The equipped main-hand weapon — the auto-attack borrows its icon (decision 0230).
-            items.insert_object(G_SWORD, ObjectFields::from_pairs(&[(3, 93_011), (14, 1)]));
+            crate::items::spawn_item(
+                &mut commands,
+                &mut index,
+                G_SWORD,
+                ObjectFields::from_pairs(&[(3, 93_011), (14, 1)]),
+                false,
+            );
             let mut sword = template("Militia Shortsword", 2);
             sword.display_info_id = DISP_SWORD;
             items.insert_template(93_011, Some(sword));
diff --git a/crates/benilla-app/src/capture/fxview.rs b/crates/benilla-app/src/capture/fxview.rs
index 2d6d59cb..e02de46b 100644
--- a/crates/benilla-app/src/capture/fxview.rs
+++ b/crates/benilla-app/src/capture/fxview.rs
@@ -97,8 +97,8 @@ pub(crate) fn drive_fx_view(
                 .id();
         }
         // `WOW_FX_GO`: the GAMEOBJECT lane. A placed trap/door/chest reaches the screen through
-        // `crate::go_anim`'s §243 state machine, never through the effect pool, so this is the
-        // only lane that reproduces one. The descriptor carries the three fields the machine
+        // `crate::go_anim`'s state machine (`0x5f3cb0`), never through the effect pool, so this is
+        // the only lane that reproduces one. The descriptor carries the three fields the machine
         // reads — display, TYPE_ID (the `go_animates` gate) and STATE (the substate) — and
         // nothing else, so an unset knob renders exactly what an omitted wire field renders.
         // Always seated on the terrain: a GO stands on the ground.
diff --git a/crates/benilla-app/src/capture/mod.rs b/crates/benilla-app/src/capture/mod.rs
index 891a1d8b..51e87b91 100644
--- a/crates/benilla-app/src/capture/mod.rs
+++ b/crates/benilla-app/src/capture/mod.rs
@@ -226,12 +226,12 @@ fn glue_screen() -> Option<GlueScreen> {
 ///
 /// **`WOW_FX_GO=<GameObjectDisplayInfo id>` swaps the subject onto the GAMEOBJECT path** — the
 /// third lane, and the one a placed trap/door/chest actually takes: the wire component set a
-/// streamed GO gets, so `crate::go_anim`'s §243 state machine — not the effect pool — chooses the
-/// sequence. `WOW_FX_GO_STATE` (`GAMEOBJECT_STATE`, default 1 READY) and `WOW_FX_GO_TYPE`
-/// (`GAMEOBJECT_TYPE_ID`, default 6 TRAP) select the substate; `benilla-extract goanimscan`
-/// *predicts* what that resolves to, and this *shows* it. The lane matters because an absent
-/// `GAMEOBJECT_STATE` reads as the wire default `0` = ACTIVE, which on a model with no `Opened`
-/// sequence lands somewhere else entirely:
+/// streamed GO gets, so `crate::go_anim`'s state machine (`0x5f3cb0`) — not the effect pool —
+/// chooses the sequence. `WOW_FX_GO_STATE` (`GAMEOBJECT_STATE`, default 1 READY) and
+/// `WOW_FX_GO_TYPE` (`GAMEOBJECT_TYPE_ID`, default 6 TRAP) select the substate;
+/// `benilla-extract goanimscan` *predicts* what that resolves to, and this *shows* it. The lane
+/// matters because an absent `GAMEOBJECT_STATE` reads as the wire default `0` = ACTIVE, which on a
+/// model with no `Opened` sequence lands somewhere else entirely:
 ///
 /// ```text
 /// WOW_DATA=<Data> WOW_CAPTURE=fxview WOW_FX_GO=3073 WOW_FX_GO_STATE=1 WOW_FX_AGE=4 \
diff --git a/crates/benilla-app/src/capture/probe_auction.rs b/crates/benilla-app/src/capture/probe_auction.rs
index b8955717..2ab61641 100644
--- a/crates/benilla-app/src/capture/probe_auction.rs
+++ b/crates/benilla-app/src/capture/probe_auction.rs
@@ -14,7 +14,7 @@
 //! is the step this probe exists for. The house id is checked to be in `1..=7` because it keys the
 //! deposit rate the sell pane quotes, and a zero would silently quote a free listing.
 //!
-//! ## The auctioneer (live-DB verified this session, `/Users/sam/dev/vmangos-deploy` → `mangos`)
+//! ## The auctioneer (live-DB verified against the local vmangos, `mangos`)
 //!
 //! Auctioneer Fitch, creature entry 8719, spawn guid 12696, map 0 (Stormwind, Trade District),
 //! pos `(-8821.53, 659.886, 97.4645)`. Her `creature_template.npc_flags` is **4096** exactly —
@@ -57,8 +57,8 @@
 //! WOW_PROBE_AUCTION=1 WOW_NOSOUND=1 WOW_USER=probe5 WOW_PASS=pprobe5 WOW_CHAR=Probefive \
 //!     cargo run -p benilla
 //! ```
-//! (the slot-keyed probe identity — `pool-N` → `WOW_USER=probeN WOW_PASS=pprobeN
-//! WOW_CHAR=Probe<N-spelled>`, method.md "The local vmangos server"; this worktree is `pool-5`).
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill).
 //! Non-combat. An outer grep on `PROBE_AUCTION:` is the whole harness; the probe self-exits (the
 //! [`super::probes::ProbeExitPlugin`] pattern) once DONE.
 
@@ -161,11 +161,20 @@ struct AuctionProbe {
     baseline_money: u32,
     /// `AUCTION_OWNED_LIST_UPDATE`'s count immediately before `StartAuction` went in.
     ///
-    /// Taken THERE and not when step (6) starts, because the STARTED result queues an owner
-    /// re-query of its own: by the time (6) is reached the event may already have fired, and a
-    /// baseline taken then would be waiting for a second one that a repeated identical page will
-    /// never produce.
+    /// Taken THERE and not when step (6) starts, so that an owner re-query queued by the STARTED
+    /// result cannot fire the event before the baseline is read — a baseline taken after it would
+    /// wait for a second event that a repeated identical page will never produce. (Since 2308 that
+    /// re-query only happens for a list we already hold, and step 6 is what first asks for this
+    /// one, so the ordering is belt and braces rather than load-bearing.)
     owned_event_baseline: i64,
+    /// How many red `UI_ERROR_MESSAGE` lines the run had already raised when the auction window
+    /// opened — the login environment's own, not the arc's.
+    ///
+    /// Step (6d) asserts the arc raised **no** red line, and it used to read the whole tally: on a
+    /// `probeN` account that is never zero, because the preflight's `GM mode is ON` and
+    /// `GOD mode is ON` banners (0679) are red lines too, and they land before the greeting. The
+    /// assertion was therefore FAILING on every clean run, which is worse than not making it.
+    red_baseline: i64,
     passes: u32,
     fails: u32,
     /// Latched once [`Phase::Done`] has fired its exit (never re-fire on a later frame).
@@ -287,6 +296,13 @@ fn last_error(script: &UiScript) -> String {
 ///
 /// Compared against `getglobal("ERR_AUCTION_STARTED")` rather than against English: the string is
 /// the player's own, and this file must not carry a copy of it.
+/// Red `UI_ERROR_MESSAGE` lines raised so far, as the hook's own array counts them.
+fn red_count(script: &UiScript) -> i64 {
+    script
+        .eval::<i64>("return table.getn(ProbeAuctionErrors)")
+        .unwrap_or(-1)
+}
+
 fn started_chat_check(script: &UiScript, probe: &mut AuctionProbe) {
     let said = script
         .eval::<i64>(
@@ -298,9 +314,7 @@ fn started_chat_check(script: &UiScript, probe: &mut AuctionProbe) {
              return 0",
         )
         .unwrap_or(-2);
-    let reds = script
-        .eval::<i64>("return table.getn(ProbeAuctionErrors)")
-        .unwrap_or(-1);
+    let reds = red_count(script) - probe.red_baseline;
     match (said, reds) {
         (1, 0) => {
             info!(
@@ -317,13 +331,16 @@ fn started_chat_check(script: &UiScript, probe: &mut AuctionProbe) {
             probe.fails += 1;
         }
         (said, reds) => {
+            // The reds are listed from the baseline on, for the same reason `reds` counts from
+            // there: the login environment's own banners are not this arc's output.
             let lines = script
-                .eval::<String>(
-                    "local t = {} \
+                .eval::<String>(&format!(
+                    "local t = {{}} \
                      for i = 1, table.getn(ProbeAuctionChat) do table.insert(t, ProbeAuctionChat[i]) end \
-                     for i = 1, table.getn(ProbeAuctionErrors) do table.insert(t, \"RED:\" .. ProbeAuctionErrors[i]) end \
+                     for i = {} + 1, table.getn(ProbeAuctionErrors) do table.insert(t, \"RED:\" .. ProbeAuctionErrors[i]) end \
                      return table.concat(t, \" | \")",
-                )
+                    probe.red_baseline.max(0)
+                ))
                 .unwrap_or_default();
             error!(
                 "PROBE_AUCTION: FAIL (6d chat) — wanted the STARTED line in chat and zero red \
@@ -342,8 +359,15 @@ fn started_chat_check(script: &UiScript, probe: &mut AuctionProbe) {
 /// coin. Derived from `probe.min_bid` rather than hardcoded, because the listing price is computed
 /// from the item's own vendor value and a fixed expectation would be a lie the day the item changes.
 ///
-/// `IsShown`, not `IsVisible`: the Auctions pane is behind the Browse tab at this point in the run
-/// and the rows are painted either way — visibility would test the tab, not the coins.
+/// `IsShown`, not `IsVisible`: the coin buttons' own shown-ness is the subject, not whatever the
+/// window is doing around them.
+///
+/// The pane is the *front* tab by the time this runs, and that is load-bearing rather than
+/// incidental: the row is painted by `AuctionFrameAuctions_Update`, which cannot complete before
+/// the tab's `OnShow` has given it a `page` (decision 2308). This check read the player's purse
+/// out of the row's money frame for as long as the probe asked for the owned list without opening
+/// the tab — the frame was still on its `MoneyTypeInfo["PLAYER"]` default because nothing had ever
+/// repainted it.
 fn owner_money_check(script: &UiScript, probe: &mut AuctionProbe) {
     let (gold, silver, copper) = (
         probe.min_bid / 10_000,
@@ -601,6 +625,9 @@ fn auction_probe(
                         auction.auctioneer.unwrap_or(0)
                     );
                     probe.passes += 1;
+                    // Everything red before this instant is the login environment (the GM/GOD
+                    // banners); the arc's own tally starts here.
+                    probe.red_baseline = red_count(&script);
                 } else {
                     error!(
                         "PROBE_AUCTION: FAIL (2 greet) — the session opened, but on {:?} (we \
@@ -1151,10 +1178,27 @@ fn auction_probe(
                 probe.phase = cancel_at(now);
                 return;
             }
-            // Re-ask on a cadence: the server drops a second in-flight list request silently, and
-            // the STARTED result has already queued a refresh of its own.
+            // Re-ask on a cadence: the server drops a second in-flight list request silently.
+            //
+            // **The FIRST ask is the tab click, not the raw binding** (decision 2308). Every
+            // caller of `GetOwnerAuctionItems` in the stock files lives inside the Auctions pane —
+            // its `OnShow` and its two page turners — and the `OnShow` is also the one place that
+            // assigns `AuctionFrameAuctions.page`. Calling the binding cold puts the window in a
+            // state no click can reach, and the reply's `AUCTION_OWNED_LIST_UPDATE` then repaints
+            // a tab whose `page` is still nil: this probe raised
+            // `Blizzard_AuctionUI.lua:837: attempt to perform arithmetic on field 'page'` twice a
+            // run doing exactly that, at WARN, where nothing was looking. Clicking the tab is both
+            // the faithful drive ("exactly as a click would", this file's header) and what makes
+            // step (6c) a real assertion instead of a permanently red one.
             if last_ask == 0.0 || now - last_ask > OWNER_REASK_SECS {
-                crate::ui_script::run_or_warn(&script, "GetOwnerAuctionItems()");
+                let ask = if last_ask == 0.0 {
+                    // The tab's own OnShow issues the query, once per window session
+                    // (`AuctionFrame.gotAuctions`), and sets the page the repaint needs.
+                    "AuctionFrameTab_OnClick(3)"
+                } else {
+                    "GetOwnerAuctionItems()"
+                };
+                crate::ui_script::run_or_warn(&script, ask);
                 probe.phase = Phase::OwnerList {
                     since,
                     last_ask: now,
diff --git a/crates/benilla-app/src/capture/probe_bank.rs b/crates/benilla-app/src/capture/probe_bank.rs
index 690fa924..e9268fa3 100644
--- a/crates/benilla-app/src/capture/probe_bank.rs
+++ b/crates/benilla-app/src/capture/probe_bank.rs
@@ -9,7 +9,7 @@
 //! window is first-party, no Lua click surface to drive); the live Lua VM is only touched for the
 //! bonus refusal step's `UI_ERROR_MESSAGE` observation, the mail probe's own idiom.
 //!
-//! ## The banker (live-DB verified this session, `/Users/sam/dev/vmangos-deploy` → `characters`/
+//! ## The banker (live-DB verified against the local vmangos, `characters`/
 //! `mangos` DBs)
 //!
 //! Soleil Stonemantle, creature entry 5099, spawn guid 12629, map 0 (Ironforge, The Vault), pos
@@ -23,7 +23,7 @@
 //!
 //! vmangos `Chat.cpp`'s `modifyCommandTable` pins `.modify money` at `SEC_BASIC_ADMIN` (4,
 //! `Common.h` `AccountTypes`) — one level ABOVE `SEC_GAMEMASTER` (3), the level every probe account
-//! is provisioned at (method.md). So `.modify money` is refused server-side for a probe login,
+//! is provisioned at (docs/METHOD.md). So `.modify money` is refused server-side for a probe login,
 //! exactly the same floor [`super::probe_taxi`]'s module doc already found for the taxi fare. This
 //! probe never sends it: step (e) reads the character's live `money` field instead (DB-verified
 //! this session: `Probeone` carries 100000 copper, `bank_bag_slots` 0 — comfortably funds the
@@ -36,7 +36,8 @@
 //! WOW_DATA=WoW/Data WOW_USER=probe1 WOW_PASS=pprobe1 WOW_CHAR=Probeone \
 //!     WOW_PROBE_BANK=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — this worktree is `pool-1` → `probe1`/`pprobe1`/`Probeone`).
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill).
 //! Non-combat; GM mode is left exactly as found. An outer `timeout` + grep on `PROBE_BANK:` is the
 //! whole harness; the probe self-exits ([`super::probes::ProbeExitPlugin`]'s pattern) once DONE.
 
diff --git a/crates/benilla-app/src/capture/probe_bg.rs b/crates/benilla-app/src/capture/probe_bg.rs
index 1757b83a..42caa922 100644
--- a/crates/benilla-app/src/capture/probe_bg.rs
+++ b/crates/benilla-app/src/capture/probe_bg.rs
@@ -93,8 +93,7 @@
 //! assignment reads off it (0649, 0679).
 //!
 //! Non-combat — the probe never attacks and never stands anywhere contested; with one player in
-//! the instance there is nobody to fight. Pair with the SLOT-KEYED probe identity
-//! (`method.md`, "The local vmangos server").
+//! the instance there is nobody to fight. Pair with the checkout's probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR — the `probe` skill).
 
 use bevy::ecs::system::NonSendMut;
 use bevy::prelude::*;
@@ -263,7 +262,7 @@ const GHOST_SAMPLES: u32 = 11;
 const FLAG_SAMPLES: u32 = 5;
 
 /// `SPIRITGUIDE` — `UNIT_NPC_FLAGS` bit 6, the flag the reference's area-spirit-healer acquire
-/// scan keys on (wow-re `interact-dead-fork-and-npc-service-ladder.md` §C row 6).
+/// scan `0x4924c0` keys on.
 const NPC_FLAG_SPIRITGUIDE: u32 = 1 << 6;
 
 /// The **event tap** — a Lua frame the probe installs on entry that records every battleground
diff --git a/crates/benilla-app/src/capture/probe_bg_queue.rs b/crates/benilla-app/src/capture/probe_bg_queue.rs
index 88633915..f4181123 100644
--- a/crates/benilla-app/src/capture/probe_bg_queue.rs
+++ b/crates/benilla-app/src/capture/probe_bg_queue.rs
@@ -30,8 +30,7 @@
 //! answers `none`. A body left queued is not harmful, only surprising: every later login on that
 //! account carries an extra `SMSG_BATTLEFIELD_STATUS` in its burst.
 //!
-//! Non-combat. Pair with the SLOT-KEYED probe identity (`WOW_USER=probeN WOW_PASS=pprobeN
-//! WOW_CHAR=Probe<N-spelled>`; `method.md`, "The local vmangos server"), and `WOW_NOSOUND=1` when
+//! Non-combat. Pair with the checkout's probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR — the `probe` skill), and `WOW_NOSOUND=1` when
 //! it runs unattended. One `timeout`'d run plus a grep for `PROBE bgqueue:` is the whole harness.
 
 use bevy::prelude::*;
diff --git a/crates/benilla-app/src/capture/probe_binder.rs b/crates/benilla-app/src/capture/probe_binder.rs
index 4d0af702..1f4ab690 100644
--- a/crates/benilla-app/src/capture/probe_binder.rs
+++ b/crates/benilla-app/src/capture/probe_binder.rs
@@ -15,7 +15,7 @@
 //! visible against a real server sending real bytes, which is what this probe puts in front of
 //! them.
 //!
-//! ## The innkeeper (live-DB verified this session, `/Users/sam/dev/vmangos-deploy` → `mangos` DB)
+//! ## The innkeeper (live-DB verified against the local vmangos, `mangos` DB)
 //!
 //! Innkeeper Keldamyr — `creature_template.entry = 6736`, spawn `creature.guid = 46343`, **map 1**
 //! (Teldrassil, Dolanaar), position `(9802.21, 982.608, 1313.98)`,
@@ -77,8 +77,8 @@
 //! WOW_DATA=WoW/Data WOW_USER=probe1 WOW_PASS=pprobe1 WOW_CHAR=Probeone \
 //!     WOW_PROBE_BINDER=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — this worktree is `pool-1` → `probe1`/`pprobe1`/`Probeone`;
-//! method.md "The local vmangos server"). Non-combat, and GM mode is left exactly as found. An
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill). Non-combat, and GM mode is left exactly as found. An
 //! outer `timeout` + grep on `PROBE_BINDER:` is the whole harness; the probe self-exits once DONE.
 //!
 //! Every step SKIPs with a note rather than FAILing for an environmental problem (the NPC never
@@ -224,7 +224,7 @@ fn last_event(script: &UiScript) -> String {
 
 /// The `CHAT_MSG_SYSTEM` lines seen since the hook went in, newest last — step 6's second
 /// observation. `SMSG_PLAYERBOUND` prints `ERR_DEATHBIND_SUCCESS_S` here (`0x5e3d3f` →
-/// `DisplayError(0x138)`, chat type 238 = CHAT_MSG_SYSTEM; wow-re, decision 1335).
+/// `DisplayError(0x138)`, chat type 238 = CHAT_MSG_SYSTEM; decision 1335).
 fn system_lines(script: &UiScript) -> Vec<String> {
     script
         .eval::<Vec<String>>("return ProbeBinderSystemLines or {}")
diff --git a/crates/benilla-app/src/capture/probe_book.rs b/crates/benilla-app/src/capture/probe_book.rs
index 3100747d..61823e54 100644
--- a/crates/benilla-app/src/capture/probe_book.rs
+++ b/crates/benilla-app/src/capture/probe_book.rs
@@ -1,10 +1,9 @@
 //! The world-book live probe (`WOW_PROBE_BOOK=1`) — B240's instrument: what does having the item-
 //! text reader open actually cost per frame, on the real object the report names?
 //!
-//! Goudy, 2026-08-09 (`#bugs` `1535810645956632686`): *"page text with html text absolutely
-//! annihilates performance"* — ~50% fps drop (62 → 36 fps, 16.0 → 28.0 ms) while the *Alliance
-//! Military Ranks* plaque's reader is up, recovering the moment it closes. That is a **frame-cost
-//! A/B**, and eyeballing an fps counter is exactly the way not to settle one (method.md's
+//! The symptom: a ~50% fps drop (62 → 36 fps, 16.0 → 28.0 ms) while the *Alliance Military Ranks*
+//! plaque's HTML page is up in the reader, recovering the moment it closes. That is a **frame-cost
+//! A/B**, and eyeballing an fps counter is exactly the way not to settle one (docs/METHOD.md's
 //! "timing and feel are measured, never eyeballed"). So this probe teleports to the plaque, samples
 //! the UI pass's own per-phase meter ([`crate::ui_script::UiFrameCost`]) with the reader CLOSED,
 //! opens it on the real route, samples again, and prints the two side by side — including how many
@@ -13,7 +12,7 @@
 //!
 //! The object: `GameObject` 3011 (`gameobject_template` entry 2857, `GAMEOBJECT_TYPE_TEXT` = 9)
 //! in Stormwind's Old Town, whose `data[0]` is `page_text` 2676 — a 647-byte HTML body. The
-//! `.go xyz` below is Goudy's own reported position (his debug panel: `-8760.2 402.3 103.9`).
+//! `.go xyz` below is the reported standing position, off the debug panel: `-8760.2 402.3 103.9`.
 //!
 //! ## The run recipe
 //!
@@ -21,8 +20,8 @@
 //! WOW_NOSOUND=1 WOW_USER=probe0 WOW_PASS=pprobe0 WOW_CHAR=Probezero \
 //!     WOW_PROBE_BOOK=1 cargo run -q -p benilla --release
 //! ```
-//! (the slot-keyed probe identity — `pool-N` → `probeN`/`pprobeN`/`Probe<N-spelled>`, method.md
-//! "The local vmangos server"). An outer `timeout` + a grep on `PROBE_BOOK:` is the whole harness;
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill). An outer `timeout` + a grep on `PROBE_BOOK:` is the whole harness;
 //! the probe self-exits ([`super::probes::ProbeExitPlugin`]'s pattern) once DONE.
 
 use bevy::prelude::*;
@@ -36,8 +35,8 @@ use crate::player::Player;
 use crate::ui_item_text::ItemTextOpen;
 use crate::ui_script::{UiCostWanted, UiFrameCost};
 
-/// Goudy's own reported standing position beside the plaque (his debug panel, screenshot
-/// `1535810480424222760-1`).
+/// The reporter's own standing position beside the plaque (their debug panel, in the report's
+/// screenshot).
 const PLAQUE_AT: [f32; 3] = [-8760.2, 402.3, 103.9];
 /// `GAMEOBJECT_TYPE_TEXT` — the strategy type a book/plaque carries (decision 1105).
 const GO_TYPE_TEXT: i32 = 9;
@@ -131,7 +130,7 @@ fn reader_state(script: &UiScript) -> (bool, i64) {
 
 /// Every string the UI currently draws — the render list is the honest place to ask what the page
 /// looks like, and the only place since `ItemTextPageText` became a `SimpleHTML` (5875's has no
-/// `GetText`; wow-re `simplehtml-markup-engine.md` §5.1).
+/// `GetText` in its method table `0x87ba80`).
 fn drawn_strings(script: &UiScript) -> Vec<String> {
     use benilla_ui::script::QuadContent;
     script
@@ -146,7 +145,7 @@ fn drawn_strings(script: &UiScript) -> Vec<String> {
 }
 
 /// **B240's render half, checked where it was reported.** The page body is HTML; if the parse ever
-/// falls back, the reader draws the markup itself — which is what Goudy photographed. So: no drawn
+/// falls back, the reader draws the markup itself — the reported symptom. So: no drawn
 /// string may contain a tag, and the page's own lines must each be there as their own block.
 fn report_render(script: &UiScript) -> u32 {
     let drawn = drawn_strings(script);
diff --git a/crates/benilla-app/src/capture/probe_castcancel.rs b/crates/benilla-app/src/capture/probe_castcancel.rs
index 7a195d04..ca97c042 100644
--- a/crates/benilla-app/src/capture/probe_castcancel.rs
+++ b/crates/benilla-app/src/capture/probe_castcancel.rs
@@ -4,7 +4,7 @@
 //! started-`Casting` half of the cancel's inflight union), then 2 s into the bar inject a real
 //! `W` press into `ButtonInput<KeyCode>` — the ACTUAL controller path, so the probe drives the
 //! same move-start edge a player's key does (controller → `LocalMoveStart` →
-//! `ui_cast::local_self_cancel` → `CMSG_CANCEL_CAST`).
+//! `spell::local_self_cancel` → `CMSG_CANCEL_CAST`).
 //!
 //! The verdict is read off the run log with `WOW_CAST_TRACE=1`: the `LOCAL self-cancel` line
 //! must land beside the `SEND move StartForward` line — frames, not a server round trip, after
@@ -12,10 +12,9 @@
 //! anything (the reap already emptied the `Casting` key it tests). The probe also logs every
 //! cast-bar phase transition ([`bar_timeline`]) so the red bar's hold/burst/fade durations are
 //! measured off the timestamps, not eyeballed. Non-combat, safe unattended
-//! (method.md's rule bans unattended *combat* probes); a hearth that completes because the
+//! (docs/METHOD.md's rule bans unattended *combat* probes); a hearth that completes because the
 //! cancel FAILED just ports the probe character home — visible in the log as the missing cancel line. Pair with
-//! the slot-keyed probe identity (`WOW_USER=probeN WOW_PASS=pprobeN WOW_CHAR=Probe<N-spelled>`,
-//! method.md) + `WOW_CAST_TRACE=1 WOW_PROBE_EXIT_AT=<s>`.
+//! the checkout's probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR — the `probe` skill) + `WOW_CAST_TRACE=1 WOW_PROBE_EXIT_AT=<s>`.
 
 use bevy::prelude::*;
 
diff --git a/crates/benilla-app/src/capture/probe_charcreate.rs b/crates/benilla-app/src/capture/probe_charcreate.rs
index 29cb07f1..dec32c6d 100644
--- a/crates/benilla-app/src/capture/probe_charcreate.rs
+++ b/crates/benilla-app/src/capture/probe_charcreate.rs
@@ -8,7 +8,8 @@
 //! the `SMSG_CHAR_CREATE` result byte, and — unless `WOW_PROBE_CHARCREATE_KEEP=1` — deletes the
 //! character it just made ([`CharRequest::Delete`]) so the account isn't littered, logging that
 //! result too. Run it **without** `WOW_CHAR` (which would auto-enter the world and leave select),
-//! against the slot-keyed probe account (`WOW_USER=probeN WOW_PASS=pprobeN`, N = your pool slot — method.md "The local vmangos server"); creating/deleting characters is a
+//! against the checkout's own probe account (`.probe-identity`, or `WOW_USER`/`WOW_PASS` — the
+//! `probe` skill); creating/deleting characters is a
 //! non-combat operation, safe to run headlessly.
 
 use benilla_protocol::{messages, CharAction, CharCreateReq};
diff --git a/crates/benilla-app/src/capture/probe_charter.rs b/crates/benilla-app/src/capture/probe_charter.rs
index 5fce6ffa..99d83ec9 100644
--- a/crates/benilla-app/src/capture/probe_charter.rs
+++ b/crates/benilla-app/src/capture/probe_charter.rs
@@ -16,7 +16,7 @@
 //! fork arm whose whole evidence is "no other arm accepts a charter". Those are only visible
 //! against real bytes.
 //!
-//! ## The registrar (live-DB verified this session, `/Users/sam/dev/vmangos-deploy` → `mangos` DB)
+//! ## The registrar (live-DB verified against the local vmangos, `mangos` DB)
 //!
 //! Aldwin Laughlin, the Stormwind guild registrar — `creature_template.entry = 4974`, spawn
 //! `creature.guid = 79681`, **map 0**, position `(-8885.25, 614.395, 95.2576)`,
@@ -85,10 +85,9 @@
 //! account to sign, and #5 (`ERR_GUILD_FOUNDER_S` on a successful turn-in) needs nine of them —
 //! neither is reachable from one client, so the whole sign/offer/turn-in half of the family
 //! (`SignPetition`, `OfferPetition`, `TurnInGuildCharter`, `MSG_PETITION_DECLINE`) still has no
-//! live coverage after this probe. #3 (the two closes send nothing) is *superseded*: the wow-re
-//! carve that landed alongside this file finds that closing a charter you do NOT own can send
-//! `MSG_PETITION_DECLINE`, so this probe deliberately asserts nothing about either close rather
-//! than pinning a claim that is being rewritten.
+//! live coverage after this probe. #3 (the two closes send nothing) is *superseded*: closing a
+//! charter you do NOT own can send `MSG_PETITION_DECLINE` (`0x4f3f60`), so this probe deliberately
+//! asserts nothing about either close rather than pinning a claim that is being rewritten.
 //!
 //! ## The run recipe
 //!
@@ -96,8 +95,7 @@
 //! WOW_NOSOUND=1 WOW_USER=probe0 WOW_PASS=pprobe0 WOW_CHAR=Probezero \
 //!     WOW_PROBE_CHARTER=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — this worktree is `pool-0` → `probe0`/`pprobe0`/`Probezero`;
-//! method.md "The local vmangos server". **Never the default `one` account** — a login on it kicks
+//! (the checkout's probe identity, the `probe` skill. **Never a player's account** — a login on it kicks
 //! the director's live session.) `WOW_NOSOUND=1` because an unattended probe must not play zone
 //! music into the director's room; `caffeinate -dis` is **not** needed for a run this short — the
 //! whole sequence is a handful of round trips and finishes in well under a minute.
@@ -117,7 +115,9 @@ use benilla_ui::script::UiScript;
 
 use super::probes::ProbeClock;
 use crate::items::Items;
-use crate::net::{ChatKind, ClientCommand, Guid, NetCommands, NetEntity, ObjectStore, SelfPlayer};
+use crate::net::{
+    ChatKind, ClientCommand, Guid, NetCommands, NetEntity, ObjectStore, Objects, SelfPlayer,
+};
 use crate::player::Player;
 use crate::target::cursor_mode::npc_flags;
 use crate::ui_gossip::GossipState;
@@ -160,7 +160,7 @@ const REQUIRED_SIGNATURES: i64 = 9;
 const FRESH_SIGNATURES: i64 = 0;
 /// Copper handed to the probe body up front so the buy can never fail for funds. `.modify money`
 /// is `SEC_BASIC_ADMIN` (4) in vmangos's `Chat.cpp` command table and every `probeN` account is
-/// gmlevel **6** (method.md, decision 0651), so it lands; with no selection it targets the sender
+/// gmlevel **6** (docs/METHOD.md, decision 0651), so it lands; with no selection it targets the sender
 /// (`ChatHandler::GetSelectedPlayer`, `Chat.cpp:2601-2612`), which is why it is sent before the
 /// probe touches an NPC.
 const FUND_COPPER: u32 = 100_000;
@@ -458,6 +458,7 @@ fn charter_probe(
     mut probe: ResMut<CharterProbe>,
     gossip: Res<GossipState>,
     registrar: Res<GuildRegistrarState>,
+    objects: Objects,
     items: Res<Items>,
     script: Option<NonSendMut<UiScript>>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
@@ -797,7 +798,12 @@ fn charter_probe(
                 };
                 return;
             }
-            let found = find_item(&store.0, &items, CHARTER_ITEM_ENTRY, ItemSearch::default());
+            let found = find_item(
+                &store.0,
+                &objects,
+                CHARTER_ITEM_ENTRY,
+                ItemSearch::default(),
+            );
             // The template has to have landed too, and it is folded into the SAME `Option` as the
             // item rather than short-circuiting on its own: the click dispatcher's charter arm is
             // a **template flag** test (`ITEM_FLAG_CHARTER`), so a click made before the answer
@@ -1168,9 +1174,12 @@ fn charter_probe(
                 // destroys whatever whole stack sits at the addressed position, so a stale pair
                 // would destroy the wrong item; nothing is expected to move a charter, and that is
                 // exactly the kind of expectation a destructive send must not rest on.
-                let Some((bag_index, slot, _)) =
-                    find_item(&store.0, &items, CHARTER_ITEM_ENTRY, ItemSearch::default())
-                else {
+                let Some((bag_index, slot, _)) = find_item(
+                    &store.0,
+                    &objects,
+                    CHARTER_ITEM_ENTRY,
+                    ItemSearch::default(),
+                ) else {
                     probe.pass(
                         9,
                         "cleanup",
@@ -1197,8 +1206,12 @@ fn charter_probe(
                 };
                 return;
             }
-            let still_there =
-                find_item(&store.0, &items, CHARTER_ITEM_ENTRY, ItemSearch::default());
+            let still_there = find_item(
+                &store.0,
+                &objects,
+                CHARTER_ITEM_ENTRY,
+                ItemSearch::default(),
+            );
             if still_there.is_none() {
                 probe.pass(
                     9,
diff --git a/crates/benilla-app/src/capture/probe_chest.rs b/crates/benilla-app/src/capture/probe_chest.rs
index 275a1d2e..801b4f4f 100644
--- a/crates/benilla-app/src/capture/probe_chest.rs
+++ b/crates/benilla-app/src/capture/probe_chest.rs
@@ -1,14 +1,14 @@
 //! The chest live probe (`WOW_PROBE_CHEST=1`) — **B84's instrument**: does the player kneel at an
 //! open chest?
 //!
-//! Goudy, 2026-07-26 (`#bugs` `1530708187173359646`): *"No looting/opening animation when using a
-//! chest"*, with a benilla/reference pair at the same Mirror Lake Orchard chest — the reference
+//! The symptom: no looting animation when opening a chest. At the same Mirror Lake Orchard chest,
+//! benilla and the reference side by side show the reference
 //! gnome kneeling over the open loot window, ours standing bolt upright. Decision 0515 had shipped
 //! the kneel keyed to the `CMSG_LOOT` send alone and recorded a chest's silence as *correct*; 1471
 //! is the correction (the real client also arms the latch in `OnLootResponse 0x5eb900`, and a chest
 //! never sends `CMSG_LOOT` at all).
 //!
-//! **A kneel is a number here, not a picture** (`method.md` step 4: timing and pose questions are
+//! **A kneel is a number here, not a picture** (`docs/METHOD.md` step 4: timing and pose questions are
 //! settled with instruments). The probe reads the self unit's own
 //! [`AnimDriver::active_anim`][crate::creature_anim::AnimDriver::active_anim] — the id the base
 //! selector actually landed on — so the verdict is `50` (`Loot`) or it is not, with no screenshot
@@ -38,8 +38,8 @@
 //! WOW_NOSOUND=1 WOW_USER=probe0 WOW_PASS=pprobe0 WOW_CHAR=Probezero \
 //!     WOW_PROBE_CHEST=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — `pool-N` → `probeN`/`pprobeN`/`Probe<N-spelled>`, `method.md`
-//! "The local vmangos server"). `WOW_PROBE_CHEST=<x>,<y>,<z>[,<map>]` aims it at a different
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill). `WOW_PROBE_CHEST=<x>,<y>,<z>[,<map>]` aims it at a different
 //! object; the default is a live `Battered Chest` spawn (`gameobject.guid` 26756, template 2843) in
 //! the Mirror Lake stretch of Elwynn, the same corner of the world the report came from. A chest is
 //! a respawning spawn point: if someone emptied that one it will be missing for its respawn timer,
diff --git a/crates/benilla-app/src/capture/probe_clam.rs b/crates/benilla-app/src/capture/probe_clam.rs
index fc31c1ff..a2216f03 100644
--- a/crates/benilla-app/src/capture/probe_clam.rs
+++ b/crates/benilla-app/src/capture/probe_clam.rs
@@ -4,7 +4,7 @@
 //! The director, 2026-08-22: *"Clams don't open anymore. I right click them and they turn gray
 //! correctly but no loot window opens ever."* Both halves of that sentence are readings this probe
 //! takes separately, because they come from two different pre-send writes in the same emitter
-//! (`0x5edc80`, wow-re `loot-anim-leg.md` §5 / `inventory-change-failure-display.md` §8):
+//! (`0x5edc80`):
 //!
 //! - the **grey lock** ([`PendingItemOps`], `0x4953e0` at `0x5edcd9`) — the half that kept working;
 //! - the **loot latch** ([`LootLatch`], `0x5edcc0`) — the half decision 1477 left unmodelled, on
@@ -34,8 +34,8 @@
 //! WOW_NOSOUND=1 WOW_USER=probe0 WOW_PASS=pprobe0 WOW_CHAR=Probezero \
 //!     WOW_PROBE_CLAM=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — `pool-N` → `probeN`/`pprobeN`/`Probe<N-spelled>`, `method.md`
-//! "The local vmangos server"). `WOW_PROBE_CLAM=<entry>` aims it at a different openable template;
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill). `WOW_PROBE_CLAM=<entry>` aims it at a different openable template;
 //! the default is a Small Barnacled Clam (7973 — `Flags` LOOTABLE with `LockID = 0`, so it is
 //! openable the moment it exists: no key, no lockpicking). The probe `.additem`s its own copy and
 //! subtracts it again on the way out, so it leaves the character as it found it.
@@ -52,7 +52,7 @@ use benilla_ui::script::UiScript;
 
 use super::probes::ProbeClock;
 use crate::items::Items;
-use crate::net::{ChatKind, ClientCommand, NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{ChatKind, ClientCommand, NetCommands, ObjectStore, Objects, SelfPlayer};
 use crate::pending_item_ops::PendingItemOps;
 use crate::ui_loot::{LootConfig, LootLatch, LootState};
 
@@ -184,6 +184,7 @@ fn window_open(script: &UiScript, loot: &LootState) -> bool {
 fn find_in_backpack(
     store: &ObjectStore,
     entry: u32,
+    objects: &Objects,
     items: &Items,
     net: &NetCommands,
 ) -> Option<(u64, u32)> {
@@ -195,7 +196,7 @@ fn find_in_backpack(
                 .filter(|g| *g != 0)
                 .map(|g| (i, g))
         })
-        .find(|(_, guid)| items.object(*guid).and_then(|f| f.object_entry()) == Some(entry))?;
+        .find(|(_, guid)| objects.object(*guid).and_then(|f| f.object_entry()) == Some(entry))?;
     // `template` asks the server once on a miss and answers `None` until the reply lands, which is
     // exactly the "not stocked yet" state this returns.
     items
@@ -209,6 +210,7 @@ fn clam_probe(
     mut probe: ResMut<ClamProbe>,
     script: Option<NonSendMut<UiScript>>,
     self_store: Query<&ObjectStore, With<SelfPlayer>>,
+    objects: Objects,
     items: Res<Items>,
     mut cfg: ResMut<LootConfig>,
     loot: Res<LootState>,
@@ -240,7 +242,7 @@ fn clam_probe(
             probe.phase = Phase::Stocking { sent_at: now };
         }
         Phase::Stocking { sent_at } => {
-            if let Some((guid, slot)) = find_in_backpack(store, entry, &items, &net) {
+            if let Some((guid, slot)) = find_in_backpack(store, entry, &objects, &items, &net) {
                 info!(
                     "PROBE_CLAM: item {entry} is guid {guid:#x} in backpack slot {slot} — \
                      sampling {CONTROL_FRAMES} control frames with it UNCLICKED"
diff --git a/crates/benilla-app/src/capture/probe_crossing.rs b/crates/benilla-app/src/capture/probe_crossing.rs
index 8253091f..7c11e029 100644
--- a/crates/benilla-app/src/capture/probe_crossing.rs
+++ b/crates/benilla-app/src/capture/probe_crossing.rs
@@ -4,9 +4,8 @@
 //! report the seam: aboard → map flip (TRANSFER_PENDING / NEW_WORLD riding branch, logged by
 //! the net layer) → still riding → arrived docked on the far continent. Every phase edge prints
 //! a `PROBE crossing:` line, so an outer `timeout`d run + grep is the whole harness. Non-combat.
-//! Pair with the SLOT-KEYED probe identity (`WOW_USER=probeN WOW_PASS=pprobeN
-//! WOW_CHAR=Probe<N-spelled>` for a `pool-N` worktree — method.md "The local vmangos server";
-//! a shared account gets kicked by parallel sessions mid-ride).
+//! Pair with the checkout's own probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR
+//! — the `probe` skill; a shared account gets kicked by parallel sessions mid-ride).
 
 use bevy::prelude::*;
 
diff --git a/crates/benilla-app/src/capture/probe_env.rs b/crates/benilla-app/src/capture/probe_env.rs
index cf37ede9..7d3442a3 100644
--- a/crates/benilla-app/src/capture/probe_env.rs
+++ b/crates/benilla-app/src/capture/probe_env.rs
@@ -60,7 +60,7 @@ pub(crate) const PROBE_VARS: &[ProbeVar] = &[
         name: "WOW_PROBE_EXIT_AT",
         purpose: "<secs> — exit the app after N wall seconds; bounds any scripted live probe's lifetime",
         // Fires on `ProbeClock` at `<secs>`, and it is the one probe variable a trace-only run
-        // sets on its own (`WOW_MOVE_TRACE`/`WOW_STREAM_TRACE` legs, method.md) — 0794's
+        // sets on its own (`WOW_MOVE_TRACE`/`WOW_STREAM_TRACE` legs, docs/METHOD.md) — 0794's
         // throttled camera leg was exactly such a run.
         wall_clock: true,
     },
diff --git a/crates/benilla-app/src/capture/probe_gm_ticket.rs b/crates/benilla-app/src/capture/probe_gm_ticket.rs
index 32275449..addb794a 100644
--- a/crates/benilla-app/src/capture/probe_gm_ticket.rs
+++ b/crates/benilla-app/src/capture/probe_gm_ticket.rs
@@ -93,8 +93,8 @@
 //! WOW_NOSOUND=1 WOW_USER=probe3 WOW_PASS=pprobe3 WOW_CHAR=Probethree \
 //!     WOW_PROBE_GMTICKET=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — this worktree is `pool-3` → `probe3`/`pprobe3`/`Probethree`;
-//! method.md "The local vmangos server"). Non-combat; the probe never drives the body and sends no
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill). Non-combat; the probe never drives the body and sends no
 //! GM command, so GM mode and position are left exactly as found — but note that the body is not
 //! necessarily *still* when a run starts (see [`REST_EPS`]). An outer `timeout` + grep on
 //! `PROBE_GMTICKET:` is the whole harness; the probe self-exits once DONE. Nothing here is a
@@ -163,11 +163,11 @@ const REST_TIMEOUT_SECS: f64 = 20.0;
 /// the packet, before the db-expect line stops being trustworthy (yd, WoW space).
 const STAMP_DRIFT_EPS: f32 = 0.05;
 
-/// The operator's half of step 4, printed verbatim so it can be pasted.
-const DB_QUERY: &str = "cd /Users/sam/dev/vmangos-deploy && docker compose exec -T database \
-                        mariadb -umangos -pmangos characters -e \"SELECT ticket_id, name, \
-                        ticket_type, map, position_x, position_y, position_z, closed_by, message \
-                        FROM gm_tickets ORDER BY ticket_id DESC LIMIT 1;\"";
+/// The operator's half of step 4: the row to read back off the server's `characters` database,
+/// printed verbatim so it can be pasted into whatever reaches that database.
+const DB_QUERY: &str = "SELECT ticket_id, name, ticket_type, map, position_x, position_y, \
+                        position_z, closed_by, message FROM gm_tickets ORDER BY ticket_id DESC \
+                        LIMIT 1;";
 
 pub(crate) struct ProbeGmTicketPlugin;
 
@@ -563,7 +563,8 @@ fn gm_ticket_probe(
                 warn!(
                     "PROBE_GMTICKET: SKIP (4 db) — operator step, by design: the client never \
                      reads map/position back, so only the server's own row proves they landed. \
-                     After the run: {DB_QUERY} — and compare against the db-expect line(s)."
+                     After the run, against the server's `characters` database: {DB_QUERY} — \
+                     and compare against the db-expect line(s)."
                 );
                 let text = unique_text(" edited");
                 if !run_or_skip(
diff --git a/crates/benilla-app/src/capture/probe_goquest.rs b/crates/benilla-app/src/capture/probe_goquest.rs
index 60d3c61a..891fead3 100644
--- a/crates/benilla-app/src/capture/probe_goquest.rs
+++ b/crates/benilla-app/src/capture/probe_goquest.rs
@@ -43,8 +43,8 @@
 //! WOW_NOSOUND=1 WOW_USER=probe4 WOW_PASS=pprobe4 WOW_CHAR=Probefour \
 //!     WOW_PROBE_GOQUEST=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — `pool-N` → `probeN`/`pprobeN`/`Probe<N-spelled>`, `method.md`
-//! "The local vmangos server"). `WOW_PROBE_GOQUEST=<x>,<y>,<z>[,<map>]` aims it elsewhere; the
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill). `WOW_PROBE_GOQUEST=<x>,<y>,<z>[,<map>]` aims it elsewhere; the
 //! default is the **Goldshire wanted poster** — `gameobject.guid` 26843, template 68
 //! `Wanted Poster`, `type` 2 `GAMEOBJECT_TYPE_QUESTGIVER`, `flags` 4 `INTERACT_COND`, offering
 //! quest 176 `Wanted: "Hogger"` (`MinLevel` 5, `QuestLevel` 11). It is a single **unpooled** spawn
@@ -90,7 +90,7 @@ const NPC_FLAG_QUESTGIVER: u32 = 0x2;
 /// `CHAT`, which would need `level > QuestLevel + Quests.LowLevelHideDiff`).
 const LOW_LEVEL: u32 = 2;
 const HIGH_LEVEL: u32 = 8;
-/// `DialogStatus` ids the verdict is written in (wow-re `questgiver-marker.md` §Q1's own map).
+/// `DialogStatus` ids the verdict is written in (the keys of the status map `0x80c454`).
 const STATUS_UNAVAILABLE: u32 = 1;
 const STATUS_AVAILABLE: u32 = 5;
 
@@ -319,9 +319,9 @@ fn goquest_probe(
         Phase::Level { to, since } => {
             if level == to {
                 // Force the sweep this window depends on. A GameObject GUID reaches the wire ONLY
-                // from a sweep (wow-re §W14.8), and the level change above is one — but it is a
-                // no-op when the character already stood at this level, so the epoch bump makes
-                // the window's sweep unconditional.
+                // from a sweep (`0x5eb159`, `0x5eb456`), and the level change above is one — but it
+                // is a no-op when the character already stood at this level, so the epoch bump
+                // makes the window's sweep unconditional.
                 quest.bump_reask();
                 info!("PROBE_GOQUEST: at level {to}, swept — reading the window");
                 probe.phase = Phase::Read {
diff --git a/crates/benilla-app/src/capture/probe_guard_poi.rs b/crates/benilla-app/src/capture/probe_guard_poi.rs
index c734517f..d756b023 100644
--- a/crates/benilla-app/src/capture/probe_guard_poi.rs
+++ b/crates/benilla-app/src/capture/probe_guard_poi.rs
@@ -10,8 +10,7 @@
 //! — distance, view radius, and which of the two draws it takes — so the run says *what would be
 //! on screen*, not merely that a packet arrived.
 //!
-//! Non-combat. Pair with the SLOT-KEYED probe identity (`WOW_USER=probeN WOW_PASS=pprobeN
-//! WOW_CHAR=Probe<N-spelled>`; `method.md`, "The local vmangos server"), and `WOW_NOSOUND=1` when
+//! Non-combat. Pair with the checkout's probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR — the `probe` skill), and `WOW_NOSOUND=1` when
 //! it runs unattended. One `timeout`'d run plus a grep for `PROBE guardpoi:` is the whole harness.
 
 use bevy::prelude::*;
diff --git a/crates/benilla-app/src/capture/probe_mail.rs b/crates/benilla-app/src/capture/probe_mail.rs
index 85c747fd..67e6b96e 100644
--- a/crates/benilla-app/src/capture/probe_mail.rs
+++ b/crates/benilla-app/src/capture/probe_mail.rs
@@ -5,7 +5,7 @@
 //! `PROBE_MAIL: DONE pass=<n> fail=<m>` summary. Modeled closely on [`super::probe_taxi`] (same
 //! phase-machine shape, same trace style, same self-terminating exit).
 //!
-//! ## The GM `.send` syntax (verified `/Users/sam/wre/vmangos-src`, `Chat/Chat.cpp` +
+//! ## The GM `.send` syntax (verified against the vmangos source, `Chat/Chat.cpp` +
 //! `Commands/MiscCommands.cpp`)
 //!
 //! `sendCommandTable[]` (Chat.cpp ~l.931): `.send mail <name> "subject" "text"` is
@@ -39,9 +39,8 @@
 //! WOW_DATA=<vanilla Data dir> WOW_USER=probe2 WOW_PASS=pprobe2 WOW_CHAR=Probetwo \
 //!     WOW_PROBE_MAIL=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — `pool-N` → `WOW_USER=probeN WOW_PASS=pprobeN
-//! WOW_CHAR=Probe<N-spelled>`, method.md "The local vmangos server"; this worktree is `pool-2` →
-//! `probe2`/`pprobe2`/`Probetwo`). `WOW_CHAR` doubles as the probe's own mail-send target — read
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill). `WOW_CHAR` doubles as the probe's own mail-send target — read
 //! once at world-enter, never hardcoded. An outer `timeout` + grep on `PROBE_MAIL:` is the whole
 //! harness; the probe self-exits (the [`super::probes::ProbeExitPlugin`] pattern) once DONE.
 
@@ -359,7 +358,7 @@ fn mail_probe(
             let Some(idx) = index_of(&mail, letter_id) else {
                 return; // shouldn't happen the same frame we just found it — re-poll
             };
-            // CheckInbox() called twice, idempotently (wow-re §5's 60s client-side throttle,
+            // CheckInbox() called twice, idempotently (`0x4aeab0`'s 60s client-side throttle,
             // decision 0548 §2/0544) — proves a rapid re-call is a no-op, not a packet storm.
             if let Err(e) = script.run(&format!("CheckInbox() CheckInbox() GetInboxText({idx})")) {
                 error!("PROBE_MAIL: FAIL (b) — GetInboxText({idx}) errored: {e}");
diff --git a/crates/benilla-app/src/capture/probe_melee.rs b/crates/benilla-app/src/capture/probe_melee.rs
index 41bc4bdb..e6625d42 100644
--- a/crates/benilla-app/src/capture/probe_melee.rs
+++ b/crates/benilla-app/src/capture/probe_melee.rs
@@ -2,10 +2,10 @@
 //! once in-world, periodically fire the attack-nearest core ([`AttackNearestRequest`] — the
 //! action-bar attack's own no-selection path), so the probe character fights whatever is closest
 //! while the `benilla_assets::trace` sink (`WOW_MOVE_TRACE=<path>`) records the swing→impact→spawn combat-text
-//! timeline for pair-birth analysis. Pair with the slot-keyed probe identity (method.md) + an outer
+//! timeline for pair-birth analysis. Pair with the checkout's probe identity (the `probe` skill) + an outer
 //! `timeout`.
 //!
-//! **Do NOT run this unattended** (director's rule, 2026-07-14, `method.md` "The local vmangos
+//! **Do NOT run this unattended** (director's rule, 2026-07-14, `docs/METHOD.md` "The local vmangos
 //! server"): the probe fights back-to-back with no health awareness and the character DIES (Tri
 //! did). Combat runs are director-assisted — ask, or hand an eyeball script.
 
diff --git a/crates/benilla-app/src/capture/probe_model_camera.rs b/crates/benilla-app/src/capture/probe_model_camera.rs
index ce8f6c22..011b8dce 100644
--- a/crates/benilla-app/src/capture/probe_model_camera.rs
+++ b/crates/benilla-app/src/capture/probe_model_camera.rs
@@ -4,14 +4,14 @@
 //!
 //! ## What it asks, and why it is a probe rather than a test
 //!
-//! The unit tests in `crate::ui_models` pin the leg's arithmetic — the client's diagonal-FOV
-//! matrix against wow-re's worked numbers, and the three cancellations. What they cannot reach is
+//! The unit tests in `crate::ui_models` pin the leg's arithmetic — the client's diagonal-FOV matrix
+//! (`0x5c3cc0`) against its worked numbers, and the three cancellations. What they cannot reach is
 //! the half that only exists at run time: does the engine resolve the camera at all, does the
 //! renderer find the record, does a camera get spawned, aimed, and pointed at a real cell of a
 //! real atlas. So this probe drives the **whole live pipeline** from Lua and reads the result off
 //! the entities the renderer actually built.
 //!
-//! The measurement is numeric, not visual (method.md's rule: a capture can confirm an existence
+//! The measurement is numeric, not visual (docs/METHOD.md's rule: a capture can confirm an existence
 //! fact, it cannot measure one). Each leg projects three model-space probe points through the
 //! camera and the root the renderer placed this frame, and compares the resulting NDC against the
 //! baseline's:
@@ -19,11 +19,10 @@
 //! - `scale` — `SetModelScale(3)` must not move a pixel. The authored eye is carried through the
 //!   model's root transform, so the camera scales with the model.
 //! - `position` — `SetPosition(0.4, −0.3, 0.9)` must not move a pixel, for the same reason.
-//! - `facing` — `SetFacing(1.0)` must not move a pixel **either**. That one is the finding this
-//!   work commissioned (wow-re `modelframe-facing-cancels.md`): the up vector `0x7ac640` builds is
-//!   model-space `+Z` at `roll = 0`, which is the axis the facing turns about, so eye, target,
-//!   geometry and up all turn together. `modelframe-render-law.md` §2's "only `SetFacing` shows"
-//!   is scoped to `<PlayerModel>`'s frozen camera.
+//! - `facing` — `SetFacing(1.0)` must not move a pixel **either**: the up vector `0x7ac640` builds
+//!   is model-space `+Z` at `roll = 0`, which is the axis the facing turns about, so eye, target,
+//!   geometry and up all turn together. The rule that only `SetFacing` shows is scoped to
+//!   `<PlayerModel>`'s frozen camera (`0x7acf10`).
 //! - `ortho` — the control that must NOT hold: `SetCamera(9)` is past the file's camera count, so
 //!   the widget installs the NULL camera and falls to the orthographic leg, where a facing is a
 //!   plain roll in the screen plane. A probe whose "identical" legs all passed because nothing was
@@ -38,7 +37,7 @@
 //! WOW_USER=probe5 WOW_PASS=pprobe5 WOW_CHAR=Probefive WOW_UNATTENDED=1 WOW_NOSOUND=1 \
 //!     WOW_PROBE_MODEL_CAMERA=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — method.md "The local vmangos server"). `WOW_TILE_TRACE=1`
+//! (the checkout's probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR — the `probe` skill)). `WOW_TILE_TRACE=1`
 //! alongside it prints the leg, the record, the eye and the matrix per pane per frame.
 
 use bevy::camera::visibility::RenderLayers;
@@ -56,8 +55,8 @@ use crate::ui_models::{TilePerspectiveCamera, TileRoot, UiModelTiles};
 /// index 1 type 1 at eye `(5.5556, 0, 1.8056)` fov `0.67620`), so it exercises the raw-index
 /// selection AND has an index past the count for the orthographic control.
 const FILE: &str = r"Creature\\Wolf\\Wolf.mdx";
-/// The pane's size in FrameXML units — the pet pane's own `318×224`, whose aspect is wow-re's
-/// worked example (`camera-law.md` §12.1: `θ = 0.287938 · fov`).
+/// The pane's size in FrameXML units — the pet pane's own `318×224`, whose aspect is a worked
+/// example of the projection `0x5c3cc0` (`θ = 0.287938 · fov`).
 const PANE_W: f32 = 318.0;
 const PANE_H: f32 = 224.0;
 /// Frames to let a change settle before the numbers are read: the extract republishes the request
@@ -192,7 +191,7 @@ fn read_leg(
 
 fn shoot(commands: &mut Commands, name: &str) {
     // Every file we write goes through `local_state` — never into the WoW install, never a
-    // platform config dir (the contract's one-folder rule).
+    // platform config dir (docs/METHOD.md's one-folder rule).
     let Some(path) = crate::local_state::home().map(|d| d.join(format!("{name}.png"))) else {
         warn!("PROBE_MODEL_CAMERA: no local-state folder — skipping the {name} shot");
         return;
diff --git a/crates/benilla-app/src/capture/probe_partner.rs b/crates/benilla-app/src/capture/probe_partner.rs
index b88b6ea8..3bddef10 100644
--- a/crates/benilla-app/src/capture/probe_partner.rs
+++ b/crates/benilla-app/src/capture/probe_partner.rs
@@ -4,9 +4,9 @@
 //! leader/loot management, pings — solo, with the probe account as the other member. It also
 //! accepts **duel** challenges (decision 0637), which is what makes the duel arc's two-client
 //! questions answerable at all: whether the opponent turns hostile, whether the arbiter flag
-//! plants. Non-combat (the unattended-combat ban, `method.md` "The local vmangos server", stands
+//! plants. Non-combat (the unattended-combat ban, `docs/METHOD.md` "The local vmangos server", stands
 //! untouched: this probe answers a challenge but never swings, and a duel nobody strikes in
-//! simply times out). Pair with the slot-keyed probe identity (`WOW_USER=probeN …`, method.md).
+//! simply times out). Pair with the checkout's probe identity (the `probe` skill).
 
 use bevy::prelude::*;
 
diff --git a/crates/benilla-app/src/capture/probe_pitch.rs b/crates/benilla-app/src/capture/probe_pitch.rs
index 8957be1a..b2698619 100644
--- a/crates/benilla-app/src/capture/probe_pitch.rs
+++ b/crates/benilla-app/src/capture/probe_pitch.rs
@@ -6,17 +6,17 @@
 //! `player::controller`, gated on `mouselook` (a held right button or MOVEANDSTEER) *and* a moving
 //! OS cursor inside the viewport. An unfocused probe window has neither. So the whole observed-swim
 //! lane — the wire's pitch tail, the dead-reckon's pitched travel basis, and the body-pitch render
-//! law (decision 0464 TU-A) — was **unreachable from any script**: a benilla client could be made
-//! to swim, but only ever level. The tilt shipped in July 2026 with no test, no trace field and no
-//! way to drive it, which is why "do other swimmers tilt?" had no answer short of the director's
-//! eye, and why a two-client probe of it could not be written at all.
+//! law (`0x60a110`, decision 0464) — was **unreachable from any script**: a benilla client could be
+//! made to swim, but only ever level. The tilt shipped in July 2026 with no test, no trace field
+//! and no way to drive it, which is why "do other swimmers tilt?" had no answer short of the
+//! director's eye, and why a two-client probe of it could not be written at all.
 //!
 //! Format: `WOW_PROBE_PITCH="<deg>@<start_s>[:<deg_per_sec>][;…]"` — `deg` is nose-**up** positive,
 //! matching `Player::mover_pitch` and the wire's own sign. `"-30@22;30@40"` aims 30° down at
 //! twenty-two seconds and 30° up at forty; `"-45@20:9"` starts level-ish and sweeps at 9°/s from
 //! twenty seconds on, which is what a slow real dive looks like on the wire. The last entry whose
 //! start has passed wins, and it is re-asserted **every frame** — the reference holds an unsteered
-//! pitch rather than levelling it (TU-B(c)), so a one-shot write would be indistinguishable from a
+//! pitch rather than levelling it, so a one-shot write would be indistinguishable from a
 //! held one; re-asserting is what makes the two separable when only one of them is under test.
 //!
 //! It writes [`Player::aim_pitch`] — the field the reference's `SetPitch` (`0x7c6f70`) writes,
diff --git a/crates/benilla-app/src/capture/probe_rig.rs b/crates/benilla-app/src/capture/probe_rig.rs
index d3323213..12e96a4e 100644
--- a/crates/benilla-app/src/capture/probe_rig.rs
+++ b/crates/benilla-app/src/capture/probe_rig.rs
@@ -1,4 +1,4 @@
-//! The probe **rig** (`WOW_RIG="<spec>"`, decision 0651) — one command that puts this slot's probe
+//! The probe **rig** (`WOW_RIG="<spec>"`, decision 0651) — one command that puts this checkout's probe
 //! account into a chosen **body** and hands the session a world that is ready to test.
 //!
 //! ## Why it exists
@@ -17,7 +17,7 @@
 //! ```text
 //! WOW_RIG="tauren druid 60 gear:heal-preraid-bis spec:heal-preraid-bis at:ThunderBluff"
 //! WOW_RIG="gnome mage 39 gear:dps-39-twink gm:off"
-//! WOW_RIG="60 gear:dps-preraid-bis"          # the slot's own Probe<N>, no new character
+//! WOW_RIG="60 gear:dps-preraid-bis"          # the account's own probe body, no new character
 //! WOW_RIG="nightelf druid"                   # just a body of that shape, level 1
 //! ```
 //!
@@ -26,14 +26,15 @@
 //! **Race + class name a character, so the rig owns the pick.** vmangos has no class-change command
 //! (`.character race` exists; there is no `.character class`), so a different class *is* a different
 //! character — which makes creating one the honest primitive rather than a fallback. The name is
-//! derived, never invented: `<Race3><Class3><slot-word>[f]`, e.g. Tauren Druid on `pool-1` →
-//! `Taudruone`. Deterministic means the *next* session reuses the same body instead of littering a
-//! second one, and the pattern is what makes eviction safe (below). Omit race+class and the rig
-//! configures whatever `WOW_CHAR`/the slot default already logs in as.
+//! derived, never invented: `<Race3><Class3><word>[f]`, the word being this checkout's
+//! (`run_mode::rig_suffix`), e.g. a Tauren Druid for `Probeone` → `Taudruone`. Deterministic means
+//! the *next* session reuses the same body instead of littering a second one, and the pattern is
+//! what makes eviction safe (below). Omit race+class and the rig configures whatever `WOW_CHAR`
+//! already logs in as.
 //!
 //! **The roster is a cache with an eviction policy.** `CharactersPerRealm` is 10, and there are 40
 //! valid race/class pairs, so a busy account fills. The rig does not hardcode the limit: it tries
-//! the create, and only on `CHAR_CREATE_SERVER_LIMIT` evicts **the rig-named character on this slot
+//! the create, and only on `CHAR_CREATE_SERVER_LIMIT` evicts **the rig-named character of this checkout
 //! that is cheapest to rebuild** — lowest level first, ties broken by oldest — then retries once.
 //! Nothing outside the rig's own naming pattern is ever deleted, so `Probe<N>` and anything a human
 //! made are untouchable.
@@ -44,7 +45,7 @@
 //! It always revives a dead or ghost body, whether or not you asked — that is the 121× command, and
 //! there is no session that wants to keep testing on a corpse.
 //!
-//! ## The GM verbs behind it (all verified against `/Users/sam/wre/vmangos-src`)
+//! ## The GM verbs behind it (all verified against the vmangos source, github.com/vmangos/core)
 //!
 //! | rig token | command | needs | note |
 //! |---|---|---|---|
@@ -71,7 +72,7 @@
 //! character (give `WOW_RIG` a race+class) starts with empty bags and is the cheaper path.
 //!
 //! Non-combat throughout: the rig creates, configures, places and stops. It never fights, so the
-//! unattended-combat ban (method.md) is untouched.
+//! unattended-combat ban (docs/METHOD.md) is untouched.
 
 use benilla_protocol::{messages, CharAction, CharCreateReq};
 use bevy::prelude::*;
@@ -225,7 +226,7 @@ impl RigSpec {
     fn describe(&self) -> String {
         let body = self
             .body
-            .map_or("this slot's probe character".into(), |(r, c, g)| {
+            .map_or("the account's probe character".into(), |(r, c, g)| {
                 format!(
                     "{} {} {}",
                     if g == 1 { "female" } else { "male" },
@@ -360,13 +361,13 @@ fn drive_rig(
                 messages::CHAR_CREATE_SUCCESS => rig.phase = RigPhase::AwaitRoster,
                 messages::CHAR_CREATE_SERVER_LIMIT if !rig.evicted => {
                     rig.evicted = true;
-                    match crate::run_mode::slot_word().and_then(|slot| {
-                        evictable(&rig.roster, rig_char_name(&rig.spec).as_deref(), slot)
+                    match crate::run_mode::rig_suffix().and_then(|word| {
+                        evictable(&rig.roster, rig_char_name(&rig.spec).as_deref(), &word)
                     }) {
                         Some((guid, name)) => {
                             warn!(
                                 "rig: the account is full — evicting the cheapest rig character to rebuild, {name} \
-                                 (guid {guid}). Only rig-named characters on this slot are ever \
+                                 (guid {guid}). Only this checkout's rig-named characters are ever \
                                  deleted; Probe<N> and hand-made characters are never touched."
                             );
                             let _ = pick.0.send(CharRequest::Delete(guid));
@@ -518,7 +519,7 @@ fn build_steps(spec: &RigSpec, dead: bool) -> Vec<String> {
 /// `game_tele` name. The facing is load-bearing exactly when a motion probe walks from the
 /// pin: `W` follows the BODY's facing, and each probe character keeps whatever facing it last
 /// had — an unpinned facing sent probe0 and probe4 down different routes from the same point,
-/// which invalidated a cross-slot A/B before 1462's sitting caught it.
+/// which invalidated a cross-checkout A/B before 1462's sitting caught it.
 fn parse_point(at: &str) -> Option<(i32, f32, f32, f32, Option<f32>)> {
     let mut parts = at.split(',').map(str::trim);
     let map = parts.next()?.parse().ok()?;
@@ -536,9 +537,9 @@ fn parse_point(at: &str) -> Option<(i32, f32, f32, f32, Option<f32>)> {
 
 fn rig_char_name(spec: &RigSpec) -> Option<String> {
     let (race, class, gender) = spec.body?;
-    let slot = crate::run_mode::slot_word()?;
+    let word = crate::run_mode::rig_suffix()?;
     let name = format!(
-        "{}{}{slot}{}",
+        "{}{}{word}{}",
         race_code(race)?,
         class_code(class)?,
         if gender == 1 { "f" } else { "" }
@@ -550,45 +551,45 @@ fn rig_char_name(spec: &RigSpec) -> Option<String> {
     Some(chars.next()?.to_ascii_uppercase().to_string() + &chars.as_str().to_ascii_lowercase())
 }
 
-/// The rig-named character on this slot that costs least to lose: **lowest level first**, ties
+/// The rig-named character of this checkout that costs least to lose: **lowest level first**, ties
 /// broken by oldest (the enum is ordered by `create_time` — vmangos `HandleCharEnumOpcode` — so an
 /// earlier index *is* older). Level is the proxy for invested setup: a level-1 body is 15 seconds to
 /// rebuild, a geared 60 is a minute and a talent tree. Evicting by age alone would throw away the
 /// most valuable body on the account first, which the live fill test made obvious.
 ///
-/// Anything that is not a rig name for `slot` — `Probe<N>`, a hand-made character, another slot's
-/// leftovers — is invisible here, and that is what makes automatic deletion safe.
+/// Anything that is not a rig name for `word` — the probe body itself, a hand-made character,
+/// another checkout's leftovers — is invisible here, and that is what makes automatic deletion safe.
 ///
-/// `slot` is a **parameter, not a `slot_word()` call inside**: reading the ambient slot here made
-/// the eviction test pass only in the worktree it was written in (`pool-1`, whose rig names end
-/// `…one`) and fail in every other slot — and in the primary checkout, where `slot_word()` is
-/// `None` and nothing matches at all. A unit test's answer must not depend on which directory the
-/// build happened in.
+/// `word` is a **parameter, not a `rig_suffix()` call inside**: reading the ambient word here made
+/// the eviction test pass only in the checkout it was written in (whose rig names end `…one`) and
+/// fail in every other — and in a checkout with no declaration, where `rig_suffix()` is `None` and
+/// nothing matches at all. A unit test's answer must not depend on which directory the build
+/// happened in.
 fn evictable(
     roster: &[benilla_protocol::Character],
     want: Option<&str>,
-    slot: &str,
+    word: &str,
 ) -> Option<(u64, String)> {
     roster
         .iter()
         .enumerate()
         .filter(|(_, c)| {
-            !want.is_some_and(|w| c.name.eq_ignore_ascii_case(w)) && is_rig_name(&c.name, slot)
+            !want.is_some_and(|w| c.name.eq_ignore_ascii_case(w)) && is_rig_name(&c.name, word)
         })
         .min_by_key(|(age, c)| (c.level, *age))
         .map(|(_, c)| (c.guid, c.name.clone()))
 }
 
-/// Whether a roster name was minted by [`rig_char_name`] for this slot: a known race code, a known
-/// class code, this slot's word, and nothing but an optional `f` after it.
-fn is_rig_name(name: &str, slot: &str) -> bool {
+/// Whether a roster name was minted by [`rig_char_name`] for this checkout: a known race code, a
+/// known class code, this checkout's word, and nothing but an optional `f` after it.
+fn is_rig_name(name: &str, word: &str) -> bool {
     let lower = name.to_ascii_lowercase();
     let Some(rest) = lower.get(3..).and_then(|r| r.get(3..)) else {
         return false;
     };
     let has_codes = RACE_CODES.iter().any(|(_, c)| lower.starts_with(c))
         && CLASS_CODES.iter().any(|(_, c)| lower[3..].starts_with(c));
-    has_codes && (rest == slot || rest == format!("{slot}f"))
+    has_codes && (rest == word || rest == format!("{word}f"))
 }
 
 /// Race id → the 3-letter name code. `Nel`/`Und` rather than the DBC's own prefixes: unambiguous,
@@ -770,7 +771,7 @@ mod tests {
 
     #[test]
     fn the_derived_name_is_deterministic_and_fits_the_server_limit() {
-        // `<Race3><Class3><slot-word>[f]`, normalized the way vmangos normalizes a player name.
+        // `<Race3><Class3><word>[f]`, normalized the way vmangos normalizes a player name.
         let name = |spec: &str, slot: &str| {
             let s = RigSpec::parse(spec).unwrap();
             let (race, class, gender) = s.body.unwrap();
@@ -835,9 +836,9 @@ mod tests {
 
     #[test]
     fn eviction_spends_the_body_that_is_cheapest_to_rebuild() {
-        // The slot is passed in, never read from the ambient build directory — these names are
-        // pool-1's, and taking the slot from `slot_word()` made this test pass in pool-1 and fail
-        // in every other worktree (and in the primary checkout, where it is `None`).
+        // The word is passed in, never read from the ambient checkout — these names are one
+        // checkout's, and taking the word from `rig_suffix()` made this test pass there and fail
+        // in every other checkout (and in one with no declaration, where it is `None`).
         let slot = "one";
         // Roster order IS create order (vmangos enumerates by `create_time`).
         let roster = [
@@ -859,8 +860,8 @@ mod tests {
         );
         // Nothing rig-named on this slot ⇒ nothing to evict; the caller errors rather than guessing.
         assert_eq!(evictable(&roster[..2], None, slot), None);
-        // And another slot's leftovers are invisible: the same roster, read as pool-3, evicts
-        // nothing. This is the assertion that would have caught the ambient-slot read.
+        // And another checkout's leftovers are invisible: the same roster, read with another word,
+        // evicts nothing. This is the assertion that would have caught the ambient read.
         assert_eq!(evictable(&roster, None, "three"), None);
     }
 
diff --git a/crates/benilla-app/src/capture/probe_service.rs b/crates/benilla-app/src/capture/probe_service.rs
index eb32d358..c73fd120 100644
--- a/crates/benilla-app/src/capture/probe_service.rs
+++ b/crates/benilla-app/src/capture/probe_service.rs
@@ -3,8 +3,7 @@
 //! window instead of a gossip menu?".
 //!
 //! 1861 replaced a cursor-kind dispatch with the reference's own first-match-wins walk over
-//! `UNIT_NPC_FLAGS` ([`crate::target::click::service_arm`]; wow-re
-//! `object-layer/scratch/interact-dead-fork-and-npc-service-ladder.md` §C). **Bit 0 (GOSSIP) is
+//! `UNIT_NPC_FLAGS` ([`crate::target::click::service_arm`]; `0x5f0130`). **Bit 0 (GOSSIP) is
 //! tested first**, so the flag — not the profession — decides: a trainer or questgiver that also
 //! carries GOSSIP still opens a gossip menu, and only a flagless one opens its own window. That
 //! precedence is the whole question, and it is invisible to a unit test: the bits come off the
@@ -21,7 +20,7 @@
 //! | *any pure questgiver with an offer* | `0x02`, GOSSIP clear | Questgiver | quest frame |
 //! | Alma Jainrose (812) | `0x10` TRAINER only | Trainer | trainer frame |
 //!
-//! The flag column is live-DB verified this session (`vmangos-deploy` → `mangos`,
+//! The flag column is live-DB verified against the local vmangos (`mangos`,
 //! `SELECT entry, name, npc_flags FROM creature_template`), and reported again from the wire on
 //! every run — a template edit shows up as a note beside the reading rather than as a mystery FAIL.
 //!
@@ -48,7 +47,7 @@
 //! WOW_DATA=WoW/Data WOW_USER=probe4 WOW_PASS=pprobe4 WOW_CHAR=Probefour \
 //!     WOW_UNATTENDED=1 WOW_PROBE_SERVICE=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — method.md "The local vmangos server"). Non-combat, GM mode
+//! (the checkout's probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR — the `probe` skill)). Non-combat, GM mode
 //! left as found, nothing bought and nothing turned in: every leg opens a window and closes it
 //! client-side, which is what the reference's own close does (`ui_gossip`: there is no
 //! `CMSG_GOSSIP_CLOSE` in 1.12).
@@ -78,7 +77,7 @@ use crate::ui_trainer::TrainerOpen;
 /// This constant is the reason the questgiver leg first read as a client defect: its hop point was
 /// an invented Northshire "hub" ~29 yd from Deputy Willem, so the probe called a ladder the click
 /// would never have reached, the server dropped the packet on its own distance check, and the
-/// timeout printed a FAIL about the client (method.md §6 — prove the run before reading the
+/// timeout printed a FAIL about the client (docs/METHOD.md §6 — prove the run before reading the
 /// result). Every hop point is now an NPC's own spawn, and the scan re-checks the reach.
 const SCAN_RANGE_SQ: f32 = crate::target::SERVICE_RANGE_SQ;
 /// Let the hop land and the tile stream before the first scan.
@@ -215,7 +214,7 @@ struct ServiceProbe {
     /// NPC look identical in a SKIP line otherwise — and on a loaded machine the first is far more
     /// likely: at load 61 this probe logged `frame hitch: ~1010 ms` on repeat (the ~1 fps regime
     /// decisions 0713/0777/1355 name) and its 20-second scan window bought about twenty samples.
-    /// `leg.sh` answers the same problem with a load guard (1157); a probe that does one thing and
+    /// A leg runner answers the same problem with a load guard (1157); a probe that does one thing and
     /// exits is better served by reporting what it actually got.
     polls: u32,
     /// Latched once [`Phase::Done`] has fired its exit (never re-fire on a later frame).
@@ -355,7 +354,7 @@ fn service_probe(
     // the guid the wire addresses.
     mut merchant: ResMut<MerchantOpen>,
     script: Option<NonSendMut<UiScript>>,
-    items: Res<crate::items::Items>,
+    objects: crate::net::Objects,
     self_store: Query<&ObjectStore, With<SelfPlayer>>,
     self_player: Query<(), With<SelfPlayer>>,
     player: Res<Player>,
@@ -426,7 +425,7 @@ fn service_probe(
                             // frames a second this leg never really looked (0713/0777/1355).
                             true =>
                                 " — THE OBSERVER WAS STARVED, so this SKIP says nothing about \
-                                     the NPC. Re-run on an idle machine (`uptime`; leg.sh's guard \
+                                     the NPC. Re-run on an idle machine (`uptime`; a leg runner's guard \
                                      is load < 3).",
                             false =>
                                 " — the machine was keeping up, so the `.go` was refused, the \
@@ -759,7 +758,7 @@ fn service_probe(
             let Some(item_guid) = self_store
                 .single()
                 .ok()
-                .and_then(|s| crate::ui_items::slot_guid(&s.0, held.bag, slot0, &items))
+                .and_then(|s| crate::ui_items::slot_guid(&s.0, held.bag, slot0, &objects))
             else {
                 error!(
                     "PROBE_SERVICE: FAIL (vendor fork, held cursor) — bag {} slot {} is on the \
diff --git a/crates/benilla-app/src/capture/probe_stone.rs b/crates/benilla-app/src/capture/probe_stone.rs
index 30e15036..4feeb960 100644
--- a/crates/benilla-app/src/capture/probe_stone.rs
+++ b/crates/benilla-app/src/capture/probe_stone.rs
@@ -10,7 +10,7 @@
 //!
 //! **Why a probe and not a capture:** none of this is a picture. Every reading here is a number or
 //! a Lua truth value — the queued area id, `IsInMeetingStoneQueue()`, whether the stock minimap
-//! button is shown — so the verdict needs no eye in the loop (`method.md` step 4).
+//! button is shown — so the verdict needs no eye in the loop (`docs/METHOD.md` step 4).
 //!
 //! **Where it enters the chain, exactly.** It writes the very
 //! [`MeetingStoneUse`] the click ladder writes, so everything **downstream** of that seam runs
@@ -44,8 +44,8 @@
 //! WOW_NOSOUND=1 WOW_UNATTENDED=1 WOW_USER=probe3 WOW_PASS=pprobe3 WOW_CHAR=Probethree \
 //!     WOW_PROBE_STONE=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — `pool-N` → `probeN`/`pprobeN`/`Probe<N-spelled>`, `method.md`
-//! "The local vmangos server"). `WOW_PROBE_STONE=<x>,<y>,<z>[,<map>]` aims it elsewhere.
+//! (the checkout's probe identity — `.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR; the `probe`
+//! skill). `WOW_PROBE_STONE=<x>,<y>,<z>[,<map>]` aims it elsewhere.
 //!
 //! **It leaves the probe body at the stone's minimum level**, deliberately and without putting it
 //! back: the level is the probe's own instrument (leg 2 needs one side of the band and leg 3 the
diff --git a/crates/benilla-app/src/capture/probe_taxi.rs b/crates/benilla-app/src/capture/probe_taxi.rs
index ca7d2139..8b97d5c4 100644
--- a/crates/benilla-app/src/capture/probe_taxi.rs
+++ b/crates/benilla-app/src/capture/probe_taxi.rs
@@ -7,8 +7,7 @@
 //! arrival distance to the destination node's DBC position, and measured flight duration vs the
 //! DBC prediction `Σ path-segment length ÷ 32 yd/s` (`PLAYER_FLIGHT_SPEED`) — timing measured,
 //! never eyeballed (decision 0404). An outer `timeout`d run + grep is the whole harness.
-//! Non-combat. Pair with the SLOT-KEYED probe identity (`WOW_USER=probeN WOW_PASS=pprobeN
-//! WOW_CHAR=Probe<N-spelled>`; method.md "The local vmangos server"). Uses `.taxicheat on` so
+//! Non-combat. Pair with the checkout's probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR — the `probe` skill). Uses `.taxicheat on` so
 //! the fresh probe character can fly to an unvisited node (and so the SHOWTAXINODES mask
 //! exercises the full-network branch); the 110-copper fare is DB-seeded (see the Wait phase —
 //! `.modify money` outranks the probe account).
@@ -95,7 +94,7 @@ enum Phase {
         started_at: f64,
         last_report: f64,
         /// Latched true the first in-flight frame the anim pair reads right — rider base
-        /// Mount(91), mount child base Fly(135) (RF-0057 `0x5fd19c` + the 0441 mount pin).
+        /// Mount(91), mount child base Fly(135) (`0x5fd19c` + the 0441 mount pin).
         gait_ok: bool,
         /// The largest |flying pitch| (radians) seen on the SELF transform mid-flight — the
         /// `sample_splines` tangent-climb attitude (decisions 0501/0516). The route climbs
@@ -308,7 +307,7 @@ fn taxi_probe(
         } => {
             let wow = bevy_to_wow(player.pos);
             if player.server_riding() {
-                // The anim pair the flight must show (RF-0057 `0x5fd19c` + the 0441 mount pin):
+                // The anim pair the flight must show (`0x5fd19c` + the 0441 mount pin):
                 // rider base Mount(91), mount child base Fly(135). Latched — the first frames
                 // legitimately lag (mount attach, first selection).
                 let rider = drivers.get(self_entity).ok().map(|d| d.playing().0);
diff --git a/crates/benilla-app/src/capture/probe_vendor_swap.rs b/crates/benilla-app/src/capture/probe_vendor_swap.rs
index 6093fd07..1f81789b 100644
--- a/crates/benilla-app/src/capture/probe_vendor_swap.rs
+++ b/crates/benilla-app/src/capture/probe_vendor_swap.rs
@@ -36,7 +36,7 @@
 //! WOW_USER=probe1 WOW_PASS=pprobe1 WOW_CHAR=Probeone WOW_UNATTENDED=1 WOW_NOSOUND=1 \
 //!     WOW_PROBE_VENDOR_SWAP=1 cargo run -q -p benilla
 //! ```
-//! (the slot-keyed probe identity — method.md "The local vmangos server").
+//! (the checkout's probe identity (`.probe-identity`, or WOW_USER/WOW_PASS/WOW_CHAR — the `probe` skill)).
 
 use bevy::prelude::*;
 
diff --git a/crates/benilla-app/src/capture/probes/dress_census.rs b/crates/benilla-app/src/capture/probes/dress_census.rs
index 72e192ff..baf02bd7 100644
--- a/crates/benilla-app/src/capture/probes/dress_census.rs
+++ b/crates/benilla-app/src/capture/probes/dress_census.rs
@@ -2,8 +2,8 @@
 //! the body saying what the wire asked for, what we resolved, and what is actually hanging off the
 //! skeleton right now.
 //!
-//! It exists because those are three different things and a screenshot conflates all three. B123 —
-//! *"show helm and cloak preferences are not taken into account"* — is exactly a gap between the
+//! It exists because those are three different things and a screenshot conflates all three. A
+//! helm or cloak the player chose to hide, drawn anyway, is exactly a gap between the
 //! first and the third: the descriptor carried `PLAYER_FLAGS_HIDE_HELM`, the resolver ignored it,
 //! and a helm model hung off the head. Nothing in a picture separates that from "this character
 //! simply has a helm equipped", which is why the report needed a reader rather than an eye.
diff --git a/crates/benilla-app/src/capture/probes/ground_census.rs b/crates/benilla-app/src/capture/probes/ground_census.rs
index 6d3c677c..3e5c3cdd 100644
--- a/crates/benilla-app/src/capture/probes/ground_census.rs
+++ b/crates/benilla-app/src/capture/probes/ground_census.rs
@@ -22,7 +22,7 @@
 //! - **`terrain`** is the MCNK height under it, which is what the clamp finds when a building's own
 //!   collider has not attached yet.
 //!
-//! Pair it with the slot-keyed probe identity and a `.go` to the reported spot:
+//! Pair it with the checkout's probe identity (the `probe` skill) and a `.go` to the reported spot:
 //!
 //! ```text
 //! WOW_USER=probeN WOW_PASS=pprobeN WOW_CHAR=Probe<n> WOW_NOSOUND=1 \
diff --git a/crates/benilla-app/src/capture/probes/lift_census.rs b/crates/benilla-app/src/capture/probes/lift_census.rs
index 59fa089b..1d8c0db2 100644
--- a/crates/benilla-app/src/capture/probes/lift_census.rs
+++ b/crates/benilla-app/src/capture/probes/lift_census.rs
@@ -31,7 +31,7 @@
 //! - **`meshes`** counts render descendants (the whole subtree, not just direct children — a GO
 //!   model hangs its submeshes under an anim host).
 //!
-//! Pair it with the slot-keyed probe identity and a `.go` to the reported spot:
+//! Pair it with the checkout's probe identity (the `probe` skill) and a `.go` to the reported spot:
 //!
 //! ```text
 //! WOW_USER=probeN WOW_PASS=pprobeN WOW_CHAR=Probe<n> WOW_NOSOUND=1 \
@@ -125,9 +125,9 @@ fn fire_lift_census(
     for (guid, net, t, store, transport, anchor, seed, vis, inherited, kids, attached) in &entities
     {
         let go_type = store.0.gameobject_type_id();
-        // Every ticking GO type (the reference's own RF-0051 pair) plus anything already wearing
-        // a transport component — so a type field we misread still shows up rather than vanishing
-        // from the instrument that exists to find it.
+        // Every ticking GO type (the pair the reference's per-frame tick `0x630970` fires) plus
+        // anything already wearing a transport component — so a type field we misread still shows
+        // up rather than vanishing from the instrument that exists to find it.
         if !(net.kind == EntityKind::GameObject && matches!(go_type, 11 | 15)
             || transport.is_some()
             || anchor.is_some()
diff --git a/crates/benilla-app/src/capture/probes/live_fps.rs b/crates/benilla-app/src/capture/probes/live_fps.rs
index 55031b94..e55515a0 100644
--- a/crates/benilla-app/src/capture/probes/live_fps.rs
+++ b/crates/benilla-app/src/capture/probes/live_fps.rs
@@ -272,7 +272,7 @@ fn drive_live_fps(
                 // settle window on top — a run still worldless this far past it is stranded on a
                 // glue screen (dead server, refused login the marker arms didn't catch) and every
                 // second more is the 1371 sitting's dead wall-clock again. `FATAL` is the marker
-                // leg.sh keys on.
+                // a leg runner keys on.
                 if time.elapsed_secs() > probe.at + BOOT_DEADLINE_SECS {
                     error!(
                         "live-fps: FATAL — still not in world {:.0}s past the probe delay; a measurement run with no world is dead. exiting",
diff --git a/crates/benilla-app/src/capture/probes/particle_census.rs b/crates/benilla-app/src/capture/probes/particle_census.rs
index 72243232..7b74c2bf 100644
--- a/crates/benilla-app/src/capture/probes/particle_census.rs
+++ b/crates/benilla-app/src/capture/probes/particle_census.rs
@@ -89,7 +89,7 @@ fn fire_particle_census(
     // included — has already been discarded by the wall. Before 0678 it was routinely non-zero,
     // because `doodad_fade_alpha` admits any owner over `NEVER_FADE_RADIUS` at *every* distance
     // and nothing else bounded depth; that is precisely "all effects render at unlimited
-    // distance", and precisely the reporter's "the terrain is not even rendered that far".
+    // distance", out past the point where the terrain itself stops drawing.
     // It must now be **0**: past the wall the gate hides the emitter and freezes its pool.
     //
     // `beyond_wall` (verdict ignored) stays as the denominator — emitters *exist* out there and
diff --git a/crates/benilla-app/src/capture/probes/run.rs b/crates/benilla-app/src/capture/probes/run.rs
index c0f52e1e..80372d0d 100644
--- a/crates/benilla-app/src/capture/probes/run.rs
+++ b/crates/benilla-app/src/capture/probes/run.rs
@@ -8,7 +8,7 @@ use bevy::prelude::*;
 use super::ProbeClock;
 
 /// Keep a probe run's window **un-occludable, and out of the director's way** — the one defence
-/// against macOS's ~1 fps throttle for a fully covered window (decisions 0713/0777, method.md's
+/// against macOS's ~1 fps throttle for a fully covered window (decisions 0713/0777, docs/METHOD.md's
 /// `caffeinate` note), at the smallest footprint that still buys it.
 ///
 /// The on-top half used to live inside the FPS probe alone, which reads as "a frame-rate concern".
diff --git a/crates/benilla-app/src/capture/probes/trail_census.rs b/crates/benilla-app/src/capture/probes/trail_census.rs
index 172691c7..b3052da4 100644
--- a/crates/benilla-app/src/capture/probes/trail_census.rs
+++ b/crates/benilla-app/src/capture/probes/trail_census.rs
@@ -32,7 +32,7 @@
 //! Off a transport `deck=` reads `-` and the deck columns are the world ones, which is the control:
 //! this census must not change on the ground, where a streak *should* smear behind a moving host.
 //!
-//! Pair it with the slot-keyed probe identity and a `.go` onto the Thunder Bluff lift:
+//! Pair it with the checkout's probe identity (the `probe` skill) and a `.go` onto the Thunder Bluff lift:
 //!
 //! ```text
 //! WOW_USER=probeN WOW_PASS=pprobeN WOW_CHAR=Probe<n> WOW_NOSOUND=1 \
diff --git a/crates/benilla-app/src/capture/probes/visual_census.rs b/crates/benilla-app/src/capture/probes/visual_census.rs
index 2b91ae03..a8da49ab 100644
--- a/crates/benilla-app/src/capture/probes/visual_census.rs
+++ b/crates/benilla-app/src/capture/probes/visual_census.rs
@@ -38,7 +38,7 @@
 //!   never to be confused with one that built nothing, which is the distinction the census exists
 //!   to keep.
 //!
-//! Pair it with the slot-keyed probe identity and a `.go` to the reported spot:
+//! Pair it with the checkout's probe identity (the `probe` skill) and a `.go` to the reported spot:
 //!
 //! ```text
 //! WOW_USER=probeN WOW_PASS=pprobeN WOW_CHAR=Probe<n> WOW_NOSOUND=1 \
diff --git a/crates/benilla-app/src/capture/scenarios.rs b/crates/benilla-app/src/capture/scenarios.rs
index 3a86a536..d970a9fd 100644
--- a/crates/benilla-app/src/capture/scenarios.rs
+++ b/crates/benilla-app/src/capture/scenarios.rs
@@ -1441,7 +1441,7 @@ pub(super) const SCAR_LOOK: [f32; 3] = [-11792.7, -2647.1, 66.6];
 /// **Forgetting it did not fail.** The run brought up the world with no in-game UI, the fixture's
 /// seed hit a nil global (`ToggleQuestLog`), logged ONE `warn!` into ~100 lines of pipeline
 /// chatter, wrote a perfectly valid PNG of a UI-less world, and exited **0**. That is an
-/// instrument that manufactures a confident false negative — the shape `method.md` §6 spends a
+/// instrument that manufactures a confident false negative — the shape `docs/METHOD.md` §6 spends a
 /// paragraph on — and it cost a session a wasted build and nearly a wrong conclusion about a fix
 /// that was in fact working.
 ///
diff --git a/crates/benilla-app/src/char_create/mod.rs b/crates/benilla-app/src/char_create/mod.rs
index 820dc3fd..48e6cc10 100644
--- a/crates/benilla-app/src/char_create/mod.rs
+++ b/crates/benilla-app/src/char_create/mod.rs
@@ -326,7 +326,7 @@ impl CreateSelection {
 }
 
 /// One clickable control on the screen — a single component so one query dispatches every button.
-#[derive(Component, Clone, Copy, PartialEq, Eq)]
+#[derive(Component, Clone, Copy, PartialEq, Eq, Debug)]
 enum CreateAction {
     Race(u8),
     Gender(u8),
@@ -372,8 +372,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 — wow-re
-/// `rf82-editbox-runtime.md`, period `E+0x370` / accumulator `E+0x374`), reset on every keystroke
+/// 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
@@ -808,4 +808,118 @@ mod tests {
             "the booth look must differ by class, or the preview cannot re-dress"
         );
     }
+
+    /// **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.
+    #[test]
+    fn the_chosen_icons_are_lock_highlighted() {
+        use crate::glue::art::GlueArt;
+        use crate::glue::widgets::{icon_button, LockHighlight};
+
+        fn spawn_icons(mut commands: Commands, art: Res<GlueArt>) {
+            let font = Handle::<Font>::default();
+            commands.spawn(Node::default()).with_children(|p| {
+                for race in ALLIANCE {
+                    icon_button(
+                        p,
+                        &font,
+                        CreateAction::Race(race),
+                        None::<parts::DynIcon>,
+                        None,
+                        None::<parts::DynText>,
+                        "",
+                        &art,
+                        1.0,
+                    );
+                }
+                for sex in 0..2u8 {
+                    icon_button(
+                        p,
+                        &font,
+                        CreateAction::Gender(sex),
+                        None::<parts::DynIcon>,
+                        None,
+                        None::<parts::DynText>,
+                        "",
+                        &art,
+                        1.0,
+                    );
+                }
+                for slot in 0..8u8 {
+                    icon_button(
+                        p,
+                        &font,
+                        CreateAction::ClassSlot(slot),
+                        None::<parts::DynIcon>,
+                        None,
+                        None::<parts::DynText>,
+                        "",
+                        &art,
+                        1.0,
+                    );
+                }
+            });
+        }
+
+        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.
+            .insert_resource(CreateSelection {
+                race: 1,
+                sex: 1,
+                class: 8,
+                ..default()
+            })
+            .add_systems(Startup, spawn_icons)
+            .add_systems(Update, refresh::refresh_hover);
+        app.update();
+
+        let locked: Vec<CreateAction> = app
+            .world_mut()
+            .query::<(&CreateAction, &LockHighlight)>()
+            .iter(app.world())
+            .filter(|(_, l)| l.0)
+            .map(|(a, _)| *a)
+            .collect();
+        assert_eq!(
+            locked.len(),
+            3,
+            "exactly one race, one gender and one class icon is locked — got {locked:?}"
+        );
+        assert!(locked.contains(&CreateAction::Race(1)), "Human");
+        assert!(locked.contains(&CreateAction::Gender(1)), "female");
+        assert!(
+            locked.contains(&CreateAction::ClassSlot(6)),
+            "mage is slot 6 of [1,2,3,4,5,7,8,9,11] — and it is the mage icon the director saw \
+             unmarked"
+        );
+
+        // …and the selection moving takes the lock with it, rather than lighting a second icon.
+        app.world_mut().resource_mut::<CreateSelection>().class = 1; // warrior, slot 0
+        app.update();
+        let locked: Vec<CreateAction> = app
+            .world_mut()
+            .query::<(&CreateAction, &LockHighlight)>()
+            .iter(app.world())
+            .filter(|(_, l)| l.0)
+            .map(|(a, _)| *a)
+            .collect();
+        assert!(locked.contains(&CreateAction::ClassSlot(0)));
+        assert!(!locked.contains(&CreateAction::ClassSlot(6)));
+    }
 }
diff --git a/crates/benilla-app/src/char_create/refresh.rs b/crates/benilla-app/src/char_create/refresh.rs
index 508d0f19..c0e6bc7f 100644
--- a/crates/benilla-app/src/char_create/refresh.rs
+++ b/crates/benilla-app/src/char_create/refresh.rs
@@ -219,11 +219,17 @@ pub(super) fn refresh_dynamic(
     }
 }
 
-/// Per-frame interaction visuals the CREATE screen owns: highlight overlays (hover — and held
-/// while selected, the ref's `LockHighlight`), hover labels, 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.
+/// 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.
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_hover(
     sel: Res<CreateSelection>,
@@ -238,10 +244,10 @@ pub(super) fn refresh_hover(
             &Children,
             &mut BackgroundColor,
             Has<FallbackFace>,
-            &mut LockHighlight,
         ),
         (With<Button>, Without<crate::glue::widgets::GlueBtn>),
     >,
+    mut locks: Query<(&CreateAction, &mut LockHighlight)>,
     mut labels: Query<&mut Visibility, (With<HoverLabel>, Without<Hilight>)>,
     mut disables: Query<(&CreateAction, &mut GlueDisabled)>,
 ) {
@@ -254,14 +260,20 @@ pub(super) fn refresh_hover(
         _ => false,
     };
 
-    for (action, interaction, children, mut bg, fallback, mut locked) in &mut buttons {
+    // `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.
+    for (action, mut locked) in &mut locks {
         let is_sel = selected(action);
-        let hovered = *interaction != Interaction::None;
-        let lit = is_sel || hovered;
-        // The sheen itself is `crate::glue::glue_hilights`' — this says only which row is chosen.
         if locked.0 != is_sel {
             locked.0 = is_sel;
         }
+    }
+
+    for (action, interaction, children, mut bg, fallback) in &mut buttons {
+        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.)
         if fallback {
diff --git a/crates/benilla-app/src/char_select/addons.rs b/crates/benilla-app/src/char_select/addons.rs
index 5038798a..a6db2ce8 100644
--- a/crates/benilla-app/src/char_select/addons.rs
+++ b/crates/benilla-app/src/char_select/addons.rs
@@ -38,9 +38,12 @@
 //!
 //! 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`] instead: the same discovery, the same manifest parser,
-//! the same enable files. Two views of one folder, never two folders. With the dropdown that read
-//! happens **once per roster character at open** ([`AddonsPanel::open_for`]).
+//! [`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.
 
 use bevy::prelude::*;
 use bevy::ui_render::ui_material::MaterialNode;
@@ -224,41 +227,34 @@ impl Default for AddonsPanel {
 }
 
 impl AddonsPanel {
-    /// Open for this realm's roster, reading the folder fresh — once per character, so each
-    /// staged column is that character's own enable file applied to one shared list. The
-    /// reference's `AddonList_OnShow` also re-reads (`AddonList_Update`), so a folder that
-    /// changed under us is picked up.
+    /// 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.
     pub(super) fn open_for(&mut self, realm: String, chars: Vec<String>) {
-        self.list.clear();
+        self.list = addons::installed_rows();
         self.staged.clear();
-        if chars.is_empty() {
-            // A fresh account: no character means no enable file to key. `None` is the "nobody's
-            // file" read (everything enabled), staged into one anonymous column so the boxes
-            // still toggle; Okay has no file to write ([`Self::save_staged`] walks `chars`).
-            self.list = addons::installed(None);
-            self.staged
-                .push(self.list.iter().map(|a| a.enabled).collect());
+        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 {
-            for (c, name) in chars.iter().enumerate() {
-                let id = (realm.clone(), name.clone());
-                let rows = addons::installed(Some(&id));
-                if c == 0 {
-                    self.staged.push(rows.iter().map(|a| a.enabled).collect());
-                    self.list = rows;
-                } else {
-                    // Same folder, same deterministic discovery order, read back-to-back:
-                    // every call answers the same rows in the same order, only the `enabled` bits
-                    // differ. That is what lets ONE metadata list carry N columns. The order is
-                    // `addons::sort_by_directory_order` — NTFS's, the reference's own listing
-                    // order — and the point here is only that it is a pure function of the names.
-                    debug_assert_eq!(
-                        rows.len(),
-                        self.list.len(),
-                        "installed() must be deterministic across per-character reads"
-                    );
-                    self.staged.push(rows.iter().map(|a| a.enabled).collect());
-                }
-            }
+            chars.iter().map(|c| Some(c.as_str())).collect()
+        };
+        for character in columns {
+            self.staged.push(
+                self.list
+                    .iter()
+                    .map(|a| store.enabled_for(&a.name, a.default_state, character))
+                    .collect(),
+            );
         }
         self.baseline = self.staged.clone();
         self.realm = realm;
@@ -316,7 +312,7 @@ impl AddonsPanel {
     /// actually matters.
     pub(super) fn any_installed() -> bool {
         static ANY: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
-        *ANY.get_or_init(|| !addons::installed(None).is_empty())
+        *ANY.get_or_init(|| !addons::installed_rows().is_empty())
     }
 
     /// The rows currently visible, as `(index, addon)` — enable state is the view's to answer
@@ -392,10 +388,12 @@ 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"** — OURS
-    /// (1293): the reference feeds `AddOn_CanLoad` a NULL character there and that read's exact
-    /// semantics are un-carved, so we state the natural reading rather than guess at bytes nobody
-    /// has verified.
+    /// 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.
     fn effective_enabled(&self, i: usize) -> bool {
         self.box_state(i) != BoxState::Off
     }
@@ -606,7 +604,7 @@ pub(super) fn drive_addons_panel(
     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 (wow-re `ui.md`). Every *button*
+        // 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).
         let click = if *action == AddonsAction::ScrollBar {
             interaction.is_changed() && *interaction == Interaction::Pressed
@@ -694,7 +692,7 @@ pub(super) fn drive_addons_panel(
         }
     }
 
-    // The live `checkAddonVersion` mirror (1293 §5): read per frame like the gate's own per-query
+    // 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.
@@ -1712,7 +1710,7 @@ mod tests {
             dependencies: deps.iter().map(|d| (*d).to_string()).collect(),
             interface: iface,
             load_on_demand: false,
-            enabled: true,
+            default_state: true,
         }
     }
 
@@ -1721,7 +1719,7 @@ mod tests {
     /// `p.view = Some(c)` themselves.
     fn panel_for(chars: usize, list: Vec<InstalledAddOn>) -> AddonsPanel {
         let staged: Vec<Vec<bool>> = (0..chars.max(1))
-            .map(|_| list.iter().map(|a| a.enabled).collect())
+            .map(|_| list.iter().map(|a| a.default_state).collect())
             .collect();
         AddonsPanel {
             open: true,
@@ -1848,7 +1846,7 @@ mod tests {
         );
     }
 
-    /// The All view's gate input is OUR carve (1293): "enabled = any staged character has it on".
+    /// The All view's gate input is OUR reading (1293): "enabled = any staged character has it on".
     #[test]
     fn the_all_view_feeds_the_gate_any_character_on() {
         let mut p = panel_for(
@@ -1934,7 +1932,7 @@ mod tests {
         assert_eq!(p.staged, vec![vec![true, true]]);
         p.staged[0][0] = false;
         assert!(
-            p.list[0].enabled,
+            p.list[0].default_state,
             "the read-in list is never mutated — only `staged` is, which is what makes Cancel free"
         );
         p.close();
@@ -1982,27 +1980,151 @@ mod tests {
         p.staged[1][1] = false;
         p.save_staged();
 
-        // Read back through the same folder view the world-entry walk uses — the two views of
-        // one folder that 1197 §3 demands can never disagree.
-        let alice = ("TestRealm".to_string(), "Alice".to_string());
-        let bob = ("TestRealm".to_string(), "Bob".to_string());
-        let carol = ("TestRealm".to_string(), "Carol".to_string());
-        let read = |id: &(String, String)| -> Vec<bool> {
-            addons::installed(Some(id))
-                .iter()
-                .map(|a| a.enabled)
+        // 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.
+        let roster = ["Alice".to_string(), "Bob".to_string(), "Carol".to_string()];
+        let store = addons::EnableStore::load("TestRealm", &roster);
+        let rows = addons::installed_rows();
+        let read = |who: &str| -> Vec<bool> {
+            rows.iter()
+                .map(|a| store.enabled_for(&a.name, a.default_state, Some(who)))
                 .collect()
         };
         assert_eq!(
-            read(&alice),
+            read("Alice"),
             vec![false, true],
             "Alice's file carries HER edit"
         );
-        assert_eq!(read(&bob), vec![true, false], "Bob's carries HIS");
+        assert_eq!(read("Bob"), vec![true, false], "Bob's carries HIS");
+        let carol = ("TestRealm".to_string(), "Carol".to_string());
         assert!(
             !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).
+        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.
+    #[test]
+    fn a_new_character_inherits_the_disable_it_did_not_ask_for() {
+        let _l = crate::local_state::test_env::ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let tmp =
+            std::env::temp_dir().join(format!("benilla-charsel-newchar-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&tmp);
+        let home = tmp.join("benilla-config");
+        for name in ["Alpha", "Beta"] {
+            let dir = home.join("AddOns").join(name);
+            std::fs::create_dir_all(&dir).unwrap();
+            std::fs::write(dir.join(format!("{name}.toc")), "## Interface: 11200\n").unwrap();
+        }
+        let _c = crate::local_state::test_env::EnvGuard::unset("WOW_CAPTURE");
+        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(),
+            vec!["Onemage".into(), "Onerogue".into()],
+        );
+        p.set_all(false);
+        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.
+        p.open_for(
+            "TestRealm".into(),
+            vec!["Onemage".into(), "Onerogue".into(), "Freshling".into()],
+        );
+        assert!(p.view.is_none(), "reopens on All, the reference's default");
+        assert_eq!(p.staged.len(), 3);
+        assert_eq!(
+            p.staged[2],
+            vec![false, false],
+            "the new character inherits the unanimous disable, not a blank slate"
+        );
+        for i in 0..p.list.len() {
+            assert_eq!(
+                p.box_state(i),
+                BoxState::Off,
+                "row {i} reads OFF in the All view — Mixed here is the bug, and it paints a check"
+            );
+            assert!(!p.effective_enabled(i), "…so nothing is loadable either");
+        }
+        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".
+    #[test]
+    fn a_new_character_inherits_nothing_when_the_roster_disagrees() {
+        let _l = crate::local_state::test_env::ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let tmp =
+            std::env::temp_dir().join(format!("benilla-charsel-split-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&tmp);
+        let home = tmp.join("benilla-config");
+        for name in ["Alpha", "Beta"] {
+            let dir = home.join("AddOns").join(name);
+            std::fs::create_dir_all(&dir).unwrap();
+            std::fs::write(
+                dir.join(format!("{name}.toc")),
+                // Beta ships `## DefaultState: disabled`, so the tie-break is visible.
+                if name == "Beta" {
+                    "## Interface: 11200\n## DefaultState: disabled\n"
+                } else {
+                    "## Interface: 11200\n"
+                },
+            )
+            .unwrap();
+        }
+        let _c = crate::local_state::test_env::EnvGuard::unset("WOW_CAPTURE");
+        let _h =
+            crate::local_state::test_env::EnvGuard::set("BENILLA_HOME", home.to_str().unwrap());
+
+        let mut p = AddonsPanel::default();
+        p.open_for(
+            "TestRealm".into(),
+            vec!["Onemage".into(), "Onerogue".into()],
+        );
+        p.view = Some(0);
+        p.set_all(false); // the mage turns both off; the rogue keeps the defaults
+        p.view = Some(1);
+        p.set_all(true);
+        p.save_staged();
+        p.close();
+
+        p.open_for(
+            "TestRealm".into(),
+            vec!["Onemage".into(), "Onerogue".into(), "Freshling".into()],
+        );
+        assert_eq!(
+            p.staged[2],
+            vec![true, false],
+            "split roster → each row falls to its own `## DefaultState`"
+        );
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
@@ -2089,8 +2211,8 @@ mod tests {
     }
 
     /// A press on the TRACK — off the knob — warps the knob's centre under the cursor and drags
-    /// on from there, one gesture. Byte-verified 1.12 (wow-re `slider-mouse-law.md` §1, and the
-    /// director's own requirement in 0989); the glue bar runs the same law as every in-game one.
+    /// 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.
     #[test]
     fn a_press_on_the_bare_track_warps_the_knob_under_the_cursor() {
         let thumb_n = KNOB / BAR_H;
diff --git a/crates/benilla-app/src/char_select/mod.rs b/crates/benilla-app/src/char_select/mod.rs
index 45210095..52540a34 100644
--- a/crates/benilla-app/src/char_select/mod.rs
+++ b/crates/benilla-app/src/char_select/mod.rs
@@ -154,11 +154,14 @@ 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.
+                        delete_result,
                         // The reference's one `GlueDialog` (`crate::glue::dialog`), which on this
-                        // screen carries the refused character login. 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.
+                        // 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.
                         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).
@@ -168,7 +171,6 @@ impl Plugin for CharSelectPlugin {
                         refresh::refresh_list,
                         refresh::refresh_banner_and_buttons,
                         refresh::feed_glue_preview,
-                        delete_result,
                         debug_select_shot,
                     )
                         .chain()
@@ -210,16 +212,16 @@ pub(crate) struct Roster {
     ///
     /// 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 (wow-re
-    /// `glue/scratch/glue-preview-facing-law.md`, 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.
+    /// 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. The caller census
-    /// is wow-re `glue/scratch/select-character-caller-gate.md`: 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.
+    /// 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.
     pub(super) select_seq: u64,
     /// The guid we answered the IO thread with; `Some` = a login is requested/live.
     pub(super) pending_pick: Option<u64>,
@@ -303,9 +305,8 @@ impl Roster {
     /// 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 (verified again, three ways, in wow-re
-    /// `glue/scratch/select-character-caller-gate.md`), but the click never reaches it: the binding
-    /// has exactly one live call site, and the two handlers that lead to it both gate.
+    /// 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.
     pub(super) fn click_row(&mut self, row: usize) {
         if self.selected != Some(row) {
             self.select(Some(row));
@@ -374,7 +375,7 @@ impl Roster {
 
 // ── The remembered character (`lastCharacterIndex`, decision 1622) ───────────────────────────────
 
-/// The CVar the select screen remembers you by — a **real 1.12 CVar**, byte-verified in wow-re
+/// 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.
@@ -579,7 +580,7 @@ fn apply_roster_policy(
                     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 leg.sh greps for is written in exactly one place (1371, 1769).
+                    // marker a leg runner greps for is written in exactly one place (1371, 1769).
                     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"
@@ -668,9 +669,8 @@ fn back_on_login_refused(
 /// **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.
-/// (VERIFIED off `WoW.exe`, cross-checked — wow-5875-re
-/// `system/net/scratch/char-login-failed-law.md`. The strings are the shipped
-/// `GlueStrings.lua:158-166`, quoted here only as the graceful-absence fallback.)
+/// (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
@@ -723,19 +723,67 @@ fn back_on_logout(
     }
 }
 
-/// Surface a refused delete (the roster refresh already reflects a success — the row vanishes).
-/// A refusal is realistically unreachable on vmangos (any enumerated character deletes), so a log
-/// line honest-flags it rather than growing an error dialog nothing can trigger.
-fn delete_result(mut msgs: MessageReader<CharActionResultMessage>) {
+/// 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.
+fn delete_result(
+    mut msgs: MessageReader<CharActionResultMessage>,
+    mut dialog: ResMut<crate::glue::dialog::GlueDialog>,
+    strings: Option<Res<GlueStrings>>,
+) {
+    let empty = GlueStrings::default();
+    let strings = strings.as_deref().unwrap_or(&empty);
     for msg in msgs.read() {
-        if msg.action == CharAction::Delete
-            && msg.code != benilla_protocol::messages::CHAR_DELETE_SUCCESS
-        {
-            warn!("char select: delete refused (code {:#04x})", msg.code);
+        if msg.action != CharAction::Delete {
+            continue;
+        }
+        if let Some(text) = char_delete_refusal_text(strings, msg.code) {
+            info!(
+                "char select: delete refused (code {:#04x}) — {text}",
+                msg.code
+            );
+            dialog.open_error(text);
         }
     }
 }
 
+/// 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.
+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,
+        0x38 => ("CHAR_DELETE_IN_PROGRESS", "Deleting character"),
+        0x3B => (
+            "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.
+        _ => ("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.
@@ -1388,6 +1436,73 @@ 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.
+    #[test]
+    fn a_refused_delete_raises_the_glue_dialog() {
+        use crate::glue::dialog::{DialogKind, GlueDialog};
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins)
+            .add_message::<CharActionResultMessage>()
+            .init_resource::<GlueDialog>()
+            .add_systems(Update, delete_result);
+
+        app.world_mut().write_message(CharActionResultMessage {
+            action: CharAction::Delete,
+            code: benilla_protocol::messages::CHAR_DELETE_SUCCESS,
+        });
+        app.update();
+        assert!(
+            !app.world().resource::<GlueDialog>().is_open(),
+            "a success is answered by the roster, not a dialog"
+        );
+
+        app.world_mut().write_message(CharActionResultMessage {
+            action: CharAction::Delete,
+            code: 0x3A,
+        });
+        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.
+        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.
+    #[test]
+    fn every_delete_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);
+
+        assert_eq!(char_delete_refusal_text(&strings, 0x39), None);
+        assert_eq!(
+            char_delete_refusal_text(&strings, 0x3A),
+            Some("Character deletion failed")
+        );
+        assert_eq!(
+            char_delete_refusal_text(&strings, 0x3B),
+            Some(
+                "Your character is currently locked as part of the paid character transfer \
+                 process."
+            )
+        );
+        let map = strings.into_map();
+        for key in [
+            "CHAR_DELETE_IN_PROGRESS",
+            "CHAR_DELETE_FAILED",
+            "CHAR_DELETE_FAILED_LOCKED_FOR_TRANSFER",
+        ] {
+            assert!(map.contains_key(key), "{key} is not in the shipped table");
+        }
+    }
+
     /// 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
diff --git a/crates/benilla-app/src/chat_bubble.rs b/crates/benilla-app/src/chat_bubble.rs
index e7c21bc0..0542093f 100644
--- a/crates/benilla-app/src/chat_bubble.rs
+++ b/crates/benilla-app/src/chat_bubble.rs
@@ -1,6 +1,5 @@
-//! **Chat bubbles** — `CGChatBubbleFrame` (wow-re `object-layer/scratch/chat-bubble.md`,
-//! §5-verified 2026-07-11; 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
+//! **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`]).
 //!
 //! The pinned law, transcribed:
@@ -31,15 +30,14 @@
 //!   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`], wow-re's anchor cross-check 2026-08-17; 1406).
+//!   ([`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 — wow-re's
-//!   `chat-bubble.md` covers the spawn/geometry/anchor and never reached the manager tick.)
+//!   nothing interleaves. ([`level_z`]; benilla read the bytes for this one, 1504.)
 //!
 //! Named divergences (all deliberate):
 //! - ~~**`ChatBubblesParty` defaults ON**~~ — **no longer a divergence (1804).** It shipped `"1"`
@@ -48,8 +46,8 @@
 //!   [`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 on an OPEN wire-type remap
-//!   (chat-bubble.md §1) and contradicts the remembered reference look, so the uncontested
+//!   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,
@@ -91,9 +89,9 @@ use benilla_world::view::WorldCamera;
 /// 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"` — wow-re
-/// `object-layer/scratch/chat-bubble.md`). `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.
+/// **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.
 #[derive(Resource)]
 pub(crate) struct BubbleConfig {
     /// `ChatBubbles` — say/yell and their monster variants.
@@ -136,7 +134,7 @@ const BORDER_FRAC: f32 = 16.0 / 1024.0;
 /// 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 — wow-re `ui/scratch/draw-order-law.md` §4).
+/// every font string — `0x76fb00`).
 const Z_BG: u64 = 0;
 const Z_EDGE: u64 = 1;
 const Z_TAIL: u64 = 2;
diff --git a/crates/benilla-app/src/chr_classes.rs b/crates/benilla-app/src/chr_classes.rs
index 098754f6..c04dc721 100644
--- a/crates/benilla-app/src/chr_classes.rs
+++ b/crates/benilla-app/src/chr_classes.rs
@@ -3,7 +3,7 @@
 //!
 //! 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
+//! `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.
 //!
diff --git a/crates/benilla-app/src/cinematic.rs b/crates/benilla-app/src/cinematic.rs
index 687a09fe..e0c3bcd1 100644
--- a/crates/benilla-app/src/cinematic.rs
+++ b/crates/benilla-app/src/cinematic.rs
@@ -9,8 +9,7 @@
 //!
 //! # What the reference does, and what we match
 //!
-//! Byte-verified in wow-re (the cinematic dispatch, 2026-08-29), and the reason each piece here is
-//! shaped the way it is:
+//! 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
@@ -50,8 +49,7 @@
 //! 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 (wow-re `ui/scratch/cinematic-camera-law.md` §3.7, a CORRECTION to
-//! the earlier "deferred by a delay" reading). There is **no audio fade anywhere on this path**.
+//! 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
@@ -97,10 +95,10 @@ pub(crate) struct Cinematic {
     /// 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* (law §8.2, and §8.4: no loading cover
-    /// is raised anywhere on this path). 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.
+    /// 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
@@ -321,8 +319,7 @@ fn drive_letterbox(
     // `UiHidden` goes back to meaning only what ALT-Z means.
 
     // **The hardware cursor goes with it** — `0x58b590(0)` at StartCinematic, `(1)` at
-    // EndCinematic and at the leave-world teardown (wow-re `ui/scratch/cinematic-camera-law.md`
-    // §3.4, the complete 10-site census of the cinematic state cell). Nothing else in benilla
+    // 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.
@@ -541,8 +538,8 @@ const SETTLE_BUDGET: f32 = 8.0;
 ///
 /// **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 and read by nothing on this path (wow-re
-/// `ui/scratch/cinematic-camera-law.md`, a 24-site census; its one raw reader is reachable only
+/// `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
@@ -965,11 +962,11 @@ 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`, law
-/// §8.2) and raises no loading cover anywhere on the cinematic path (§8.4). 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 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.
 #[cfg(test)]
 mod settling_under_black {
     use super::*;
diff --git a/crates/benilla-app/src/net/apply/combat_chat.rs b/crates/benilla-app/src/combat_log/chat.rs
similarity index 98%
rename from crates/benilla-app/src/net/apply/combat_chat.rs
rename to crates/benilla-app/src/combat_log/chat.rs
index 793e8c89..1fbbf2f4 100644
--- a/crates/benilla-app/src/net/apply/combat_chat.rs
+++ b/crates/benilla-app/src/combat_log/chat.rs
@@ -1,9 +1,9 @@
-//! The combat-log **chat** arms (B297) — the second consumer of the packets
-//! [`super::combat_log`] and [`super::combat`] already read for the floating numbers.
+//! 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 (`0x625010`, the world-anchored spawn), gated by
+//! 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
 //! [`crate::ui_chat::combat`].
@@ -25,11 +25,11 @@ use benilla_protocol::messages::{
 use crate::ui_chat::combat::{self, Family, Fills, UnitClass};
 use crate::ui_chat::ChatLog;
 
-use super::super::{GuidIndex, ObjectStore, Reputations, SelfGuid};
+use crate::net::{GuidIndex, ObjectStore, Reputations, SelfGuid};
 
-/// The classification inputs every line needs, bundled so seven arms do not each grow six
-/// parameters. Assembled once per drain in [`super::apply_net_updates`].
-pub(super) struct ChatCtx<'a> {
+/// 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`].
+pub(crate) struct ChatCtx<'a> {
     pub self_guid: &'a SelfGuid,
     pub group: Option<&'a crate::ui_party::GroupState>,
     pub index: &'a GuidIndex,
@@ -69,11 +69,11 @@ impl ChatCtx<'_> {
     }
 
     /// A spell's display name, or `None` when the reference would emit **no line at all** for this
-    /// spell (§5.5 of the §5 verdict). Two gates, both of which 1571 was missing:
+    /// spell (`0x62cd80`, like every spell formatter). Two gates, both of which 1571 was missing:
     ///
     /// - **`Attributes & 0x180`** — `SPELL_ATTR_DO_NOT_DISPLAY | SPELL_ATTR_DO_NOT_LOG` (the mask
-    ///   and the `SpellRec+0x18` offset are VERIFIED; the two enum names are wow-re's INFERRED
-    ///   corroboration from vmangos). This is what keeps the invisible book-keeping spells every
+    ///   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.
@@ -93,8 +93,8 @@ impl ChatCtx<'_> {
     }
 
     /// `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
-    /// (§2.3). It reads the row, never the endpoints, which is why it lives beside
+    /// `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
@@ -149,7 +149,7 @@ pub(super) fn attacker_state(
         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` (§4.2). A dodge or a full
+        // 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.
         trailers: landed.then_some(combat::Trailers {
             absorbed: s.absorb,
@@ -260,7 +260,7 @@ pub(super) fn spell_damage_log(
         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 (§4.3).
+    // of the three tests is its own — absorb, then BLOCK, then resist (`0x62cd80`).
     let family = if s.damage == 0 && s.absorb > 0 {
         combat::SPELLLOGABSORB
     } else if s.damage == 0 && s.blocked > 0 {
@@ -325,8 +325,8 @@ pub(super) fn spell_log_miss(
     // 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**, and wow-re
-    // says so rather than guessing. We reproduce the behaviour, because an addon filtering on
+    // 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`.
@@ -1214,7 +1214,7 @@ fn power_drain_line(
     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` (§2.3 of wow-re's combat-log chat law). So a
+    // 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.
@@ -1355,7 +1355,7 @@ pub(super) fn environmental_damage_log(
 ///
 /// The wire's `reputationListId` is `Faction.dbc`'s `rep_index`, not a faction id; the name comes
 /// off the row that carries that index.
-pub(super) fn faction_standing(
+pub(crate) fn faction_standing(
     deltas: &[(u32, i32)],
     reputations: &Reputations,
     factions: Option<&crate::target::ring::Factions>,
@@ -1433,7 +1433,7 @@ 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 (§5.7).
+/// guid rides along and the drain resolves it, holding the line until it lands (`0x6294b0`).
 fn queue_named(
     log: &mut ChatLog,
     ctx: &ChatCtx,
@@ -1466,7 +1466,7 @@ fn queue_reported(
     fills: Fills,
     named: combat::Named,
 ) -> bool {
-    // **The gate is an OR over the two endpoints, not an AND** — the §5 verdict's own wording:
+    // **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.
diff --git a/crates/benilla-app/src/combat_log/mod.rs b/crates/benilla-app/src/combat_log/mod.rs
new file mode 100644
index 00000000..71576b1d
--- /dev/null
+++ b/crates/benilla-app/src/combat_log/mod.rs
@@ -0,0 +1,335 @@
+//! **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.
+//!
+//! 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.
+
+use benilla_protocol::messages::SpellOutcomeLog;
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::ecs::system::SystemParam;
+use bevy::prelude::*;
+
+use crate::combat_text::{CombatTextSpawn, DamageTextGates};
+use crate::names::NameCache;
+use crate::net::{
+    GuidIndex, NetCommands, NetHandlerApp, ObjectStore, Reputations, SelfGuid, ServerSoundMessage,
+};
+use crate::ui_chat::combat::{CombatLogRanges, LogPeriodicSpells};
+use crate::ui_chat::ChatLog;
+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`].
+#[derive(SystemParam)]
+pub(crate) struct Ctx<'w> {
+    self_guid: Res<'w, SelfGuid>,
+    group: Res<'w, crate::ui_party::GroupState>,
+    index: Res<'w, GuidIndex>,
+    factions: Option<Res<'w, crate::target::ring::Factions>>,
+    reputations: Res<'w, Reputations>,
+    spells: Option<Res<'w, crate::ui_action::Spells>>,
+    /// The eight display ranges.
+    ranges: Res<'w, CombatLogRanges>,
+    /// `CombatLogPeriodicSpells`.
+    periodic: Res<'w, LogPeriodicSpells>,
+}
+
+impl Ctx<'_> {
+    fn ctx(&self) -> chat::ChatCtx<'_> {
+        chat::ChatCtx {
+            self_guid: &self.self_guid,
+            group: Some(&self.group),
+            index: &self.index,
+            factions: self.factions.as_deref(),
+            reputations: &self.reputations,
+            spells: self.spells.as_deref(),
+            ranges: &self.ranges,
+            periodic: self.periodic.0,
+        }
+    }
+}
+
+/// 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.
+#[derive(SystemParam)]
+pub(crate) struct Sinks<'w, 's> {
+    /// `CombatDamage` + the two `Pet*` sub-gates.
+    damage_text: Res<'w, DamageTextGates>,
+    stores: Query<'w, 's, &'static mut ObjectStore>,
+    poses: Query<'w, 's, &'static mut Transform>,
+    log: ResMut<'w, ChatLog>,
+    names: Res<'w, NameCache>,
+    net: Res<'w, NetCommands>,
+    text: MessageWriter<'w, CombatTextSpawn>,
+    feedback: MessageWriter<'w, UnitCombatFeedback>,
+    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.
+pub(crate) struct CombatLogPlugin;
+
+impl Plugin for CombatLogPlugin {
+    fn build(&self, app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::AttackerState, on_attacker_state)
+            .net_handler(K::SpellDamageLog, on_spell_damage_log)
+            .net_handler(K::PeriodicAuraLog, on_periodic_aura_log)
+            .net_handler(K::SpellHealLog, on_spell_heal_log)
+            .net_handler(K::SpellEnergizeLog, on_spell_energize_log)
+            .net_handler(K::DamageShield, on_damage_shield)
+            .net_handler(K::SpellLogMiss, on_spell_log_miss)
+            .net_handler(K::PartyKillLog, on_party_kill_log)
+            .net_handler(K::SpellInstaKillLog, on_spell_insta_kill_log)
+            .net_handler(K::ProcResist, on_spell_outcome_log)
+            .net_handler(K::SpellOrDamageImmune, on_spell_outcome_log)
+            .net_handler(K::SpellDispelLog, on_spell_dispel_log)
+            .net_handler(K::DispelFailed, on_dispel_failed)
+            .net_handler(K::EnchantmentLog, on_enchantment_log)
+            .net_handler(K::SpellLogExecute, on_spell_log_execute)
+            .net_handler(K::EnvironmentalDamageLog, on_environmental_damage_log)
+            .net_handler(K::XpGain, on_xp_gain)
+            .net_handler(K::ExplorationXp, on_exploration_xp)
+            .net_handler(K::LevelUp, on_level_up)
+            .net_handler(K::PvpCredit, on_pvp_credit);
+    }
+}
+
+fn on_attacker_state(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::AttackerState(s) = ev {
+        let ctx = c.ctx();
+        chat::attacker_state(s, &ctx, &l.stores, &l.poses, &mut l.log);
+    }
+}
+
+fn on_spell_damage_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::SpellDamageLog(s) = ev {
+        let ctx = c.ctx();
+        chat::spell_damage_log(s, &ctx, &l.stores, &l.poses, &mut l.log);
+        text::spell_damage_log(
+            s,
+            &c.index,
+            &c.self_guid,
+            &l.stores,
+            c.spells.as_deref(),
+            *l.damage_text,
+            &mut l.text,
+            &mut l.feedback,
+            &mut l.center,
+        );
+    }
+}
+
+/// **`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.
+fn on_periodic_aura_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::PeriodicAuraLog(s) = ev {
+        if !c.periodic.0 {
+            return;
+        }
+        let ctx = c.ctx();
+        chat::periodic_aura_log(&s, &ctx, &l.stores, &l.poses, &mut l.log);
+        text::periodic_aura_log(
+            s,
+            &c.index,
+            &c.self_guid,
+            &l.stores,
+            c.spells.as_deref(),
+            *l.damage_text,
+            &mut l.text,
+            &mut l.feedback,
+            &mut l.center,
+            &l.names,
+            &l.net,
+        );
+    }
+}
+
+fn on_spell_heal_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::SpellHealLog(s) = ev {
+        let ctx = c.ctx();
+        chat::spell_heal_log(s, &ctx, &l.stores, &l.poses, &mut l.log);
+        text::spell_heal_log(
+            s,
+            &c.index,
+            &c.self_guid,
+            &mut l.feedback,
+            &mut l.center,
+            &l.names,
+            &l.net,
+        );
+    }
+}
+
+fn on_spell_energize_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::SpellEnergizeLog(s) = ev {
+        let ctx = c.ctx();
+        chat::spell_energize_log(s, &ctx, &l.stores, &l.poses, &mut l.log);
+        text::spell_energize_log(s, &c.self_guid, &mut l.center);
+    }
+}
+
+fn on_damage_shield(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::DamageShield(s) = ev {
+        let ctx = c.ctx();
+        chat::damage_shield(s, &ctx, &l.stores, &l.poses, &mut l.log);
+        text::damage_shield(
+            s,
+            &c.index,
+            &c.self_guid,
+            &l.stores,
+            *l.damage_text,
+            &mut l.text,
+            &mut l.feedback,
+        );
+    }
+}
+
+fn on_spell_log_miss(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::SpellLogMiss(s) = ev {
+        let ctx = c.ctx();
+        chat::spell_log_miss(&s, &ctx, &l.stores, &l.poses, &mut l.log);
+        text::spell_log_miss(
+            s,
+            &c.index,
+            &c.self_guid,
+            &l.stores,
+            c.spells.as_deref(),
+            *l.damage_text,
+            &mut l.text,
+            &mut l.feedback,
+            &mut l.center,
+        );
+    }
+}
+
+// ── 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 ──
+
+fn on_party_kill_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::PartyKillLog(k) = ev {
+        let ctx = c.ctx();
+        chat::party_kill_log(k, &ctx, &l.stores, &l.poses, &mut l.log);
+    }
+}
+
+fn on_spell_insta_kill_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::SpellInstaKillLog(k) = ev {
+        let ctx = c.ctx();
+        chat::spell_insta_kill_log(k, &ctx, &l.stores, &l.poses, &mut l.log);
+    }
+}
+
+fn on_spell_outcome_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    let (o, immune): (SpellOutcomeLog, bool) = match ev {
+        SessionEvent::ProcResist(o) => (o, false),
+        SessionEvent::SpellOrDamageImmune(o) => (o, true),
+        _ => return,
+    };
+    let ctx = c.ctx();
+    chat::spell_outcome_log(o, immune, &ctx, &l.stores, &l.poses, &mut l.log);
+}
+
+fn on_spell_dispel_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::SpellDispelLog(d) = ev {
+        let ctx = c.ctx();
+        chat::spell_dispel_log(&d, &ctx, &l.stores, &l.poses, &mut l.log);
+    }
+}
+
+fn on_dispel_failed(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::DispelFailed(d) = ev {
+        let ctx = c.ctx();
+        chat::dispel_failed(&d, &ctx, &l.stores, &l.poses, &mut l.log);
+    }
+}
+
+fn on_enchantment_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::EnchantmentLog(e) = ev {
+        let ctx = c.ctx();
+        chat::enchantment_log(e, &ctx, &l.stores, &l.poses, &mut l.log);
+    }
+}
+
+fn on_spell_log_execute(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::SpellLogExecute(x) = ev {
+        let ctx = c.ctx();
+        chat::spell_log_execute(&x, &ctx, &l.stores, &l.poses, &mut l.log);
+    }
+}
+
+fn on_environmental_damage_log(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::EnvironmentalDamageLog(e) = ev {
+        let ctx = c.ctx();
+        chat::environmental_damage_log(e, &ctx, &l.stores, &l.poses, &mut l.log);
+    }
+}
+
+fn on_xp_gain(In(ev): In<SessionEvent>, c: Ctx, mut l: Sinks) {
+    if let SessionEvent::XpGain(x) = ev {
+        text::xp_gain(x, &c.index, &c.self_guid, &mut l.text, &mut l.log);
+    }
+}
+
+fn on_exploration_xp(
+    In(ev): In<SessionEvent>,
+    c: Ctx,
+    mut l: Sinks,
+    area_table: Option<Res<crate::area::AreaTableRes>>,
+    exploration_sounds: Option<Res<crate::sound::ExplorationSounds>>,
+    mut server_sounds: MessageWriter<ServerSoundMessage>,
+) {
+    if let SessionEvent::ExplorationXp(x) = ev {
+        text::exploration_xp(
+            x,
+            area_table.as_deref(),
+            exploration_sounds.as_deref(),
+            &c.index,
+            &c.self_guid,
+            &l.stores,
+            &mut server_sounds,
+            &mut l.log,
+        );
+    }
+}
+
+fn on_level_up(In(ev): In<SessionEvent>, mut l: Sinks) {
+    if let SessionEvent::LevelUp(lv) = ev {
+        text::level_up(lv, &mut l.log);
+    }
+}
+
+/// 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.
+fn on_pvp_credit(In(ev): In<SessionEvent>, mut l: Sinks) {
+    if let SessionEvent::PvpCredit(credit) = ev {
+        l.log.push_pvp_credit(
+            credit.honor,
+            credit.victim_guid,
+            u8::try_from(credit.victim_rank).unwrap_or(0),
+        );
+        l.center.write(CombatTextEvent {
+            message_type: "HONOR_GAINED",
+            data: Some(credit.honor.to_string()),
+            extra: None,
+        });
+    }
+}
diff --git a/crates/benilla-app/src/net/apply/combat_log.rs b/crates/benilla-app/src/combat_log/text.rs
similarity index 92%
rename from crates/benilla-app/src/net/apply/combat_log.rs
rename to crates/benilla-app/src/combat_log/text.rs
index c480f5ef..6f0ee238 100644
--- a/crates/benilla-app/src/net/apply/combat_log.rs
+++ b/crates/benilla-app/src/combat_log/text.rs
@@ -1,6 +1,6 @@
-//! Combat-log SMSG arm bodies for [`super::apply_net_updates`]'s dispatch match — the floating
-//! combat-text **spawn table** (decision 0137 phase 2; wow-re `worldtext-spawn-and-law.md`). One
-//! `pub(super)` fn per arm, mirroring the client's handler → emitter structure: each classifies
+//! 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
@@ -28,7 +28,7 @@ use crate::names::NameCache;
 use crate::ui_chat::ChatLog;
 use crate::ui_unit::{CombatTextEvent, UnitCombatFeedback};
 
-use super::super::{GuidIndex, NetCommands, ObjectStore, SelfGuid};
+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).
@@ -43,7 +43,7 @@ fn gated_anchor(guid: u64, index: &GuidIndex, self_guid: &SelfGuid) -> Option<En
 /// 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).
-pub(super) fn classify_source(
+pub(crate) fn classify_source(
     guid: u64,
     index: &GuidIndex,
     self_guid: &SelfGuid,
@@ -73,8 +73,8 @@ pub(super) fn melee_styled(spells: Option<&crate::ui_action::Spells>, 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 pending the
-/// wow-re UNIT_COMBAT emission pin (decision 0576).
+/// spell miss arrives via `SMSG_SPELLLOGMISS` instead). PROVISIONAL string mapping until the
+/// reference's UNIT_COMBAT emission is pinned down (decision 0576).
 fn spell_feedback(
     damage: u32,
     absorb: u32,
@@ -92,12 +92,11 @@ fn spell_feedback(
     }
 }
 
-/// Spell packet → the center text's messageType (§5-verified against the emission law, wow-re
-/// `combat-text-update-emission-law.md`): landed damage is ALWAYS `SPELL_DAMAGE` — **a spell
+/// 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
-/// verdict pinned the melee helper-B partials; the spell emitter's partial path is unread).
+/// melee partials go through helper B `0x6268f0`; the spell emitter's partial path is unread).
 fn spell_center_text(
     damage: u32,
     absorb: u32,
@@ -114,13 +113,13 @@ fn spell_center_text(
     }
 }
 
-/// Melee packet → the center text's messageType + args (§5-verified emission shape, wow-re
-/// `combat-text-update-emission-law.md`; 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.
-pub(super) fn melee_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.
+pub(crate) fn melee_center_text(
     hit_info: u32,
     victim_state: u32,
     damage: u32,
@@ -334,9 +333,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 —
-                // §5-verified, wow-re `unit-combat-event-law.md`); the power gain reaches the
-                // center text only.
+                // NO ENERGIZE: 5875 never emits it (the string is absent binary-wide); the power
+                // gain reaches the center text only.
                 PeriodicTick::Energize { .. } | PeriodicTick::ManaLeech { .. } => continue,
             };
             feedback.write(UnitCombatFeedback {
@@ -461,8 +459,7 @@ 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 (§5-verified, wow-re `unit-combat-event-law.md`; the shipped
-/// CombatFeedback.lua ENERGIZE arm is dead code in 1.12).
+/// 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
@@ -605,8 +602,8 @@ pub(super) fn xp_gain(
 }
 
 /// `SMSG_EXPLORATION_EXPERIENCE` → the discovery announcement (decision 0828; surfaces and
-/// sound byte-verified by the 0829 RE, wow-re `system/net/net.md`). Three legs, mirroring the
-/// real handler's case body `[0x5e41d2, 0x5e42bb]`:
+/// 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)
@@ -623,7 +620,7 @@ pub(super) fn exploration_xp(
     index: &GuidIndex,
     self_guid: &SelfGuid,
     stores: &Query<&mut ObjectStore>,
-    sound_out: &mut MessageWriter<super::super::ServerSoundMessage>,
+    sound_out: &mut MessageWriter<crate::net::ServerSoundMessage>,
     chat_log: &mut ChatLog,
 ) {
     let race = self_guid
@@ -634,8 +631,8 @@ pub(super) fn exploration_xp(
         .and_then(|s| s.0.unit_race());
     let kit = race.and_then(|r| sounds.and_then(|s| s.0.kit(u32::from(r))));
     if let Some(kit) = kit {
-        sound_out.write(super::super::ServerSoundMessage {
-            kind: super::super::ServerSoundKind::Sound2d,
+        sound_out.write(crate::net::ServerSoundMessage {
+            kind: crate::net::ServerSoundKind::Sound2d,
             sound_id: kit,
             source: None,
         });
@@ -658,10 +655,9 @@ 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` (byte-verified `0x5e407c`, wow-re
-/// levelup-ding.md — 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.
+/// 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.
 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
diff --git a/crates/benilla-app/src/combat_text/law.rs b/crates/benilla-app/src/combat_text/law.rs
index 3be4afcf..f76658cc 100644
--- a/crates/benilla-app/src/combat_text/law.rs
+++ b/crates/benilla-app/src/combat_text/law.rs
@@ -118,8 +118,7 @@ pub(crate) const COLOR_PET_MELEE_ORANGE: u32 = 0xFFFF_8400;
 ///
 /// 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` (wow-re `playername/scratch/worldtext-spawn-and-law.md` §4,
-/// `combattext-color-law.md`). Both branch targets are function epilogues, so a gate that fails
+/// `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.
 ///
@@ -132,7 +131,7 @@ pub(crate) const COLOR_PET_MELEE_ORANGE: u32 = 0xFFFF_8400;
 /// **`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 on wow-re's own Open board.
+/// 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.
@@ -267,18 +266,17 @@ fn round_px(t: f64) -> 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 — the
-/// resolution the difftest ran at), 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 (wow-re
-/// `nameplate-vkey.md` §8 Q4). The round is the gx px law ([`round_px`]); constant with unit
-/// distance.
+/// `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.
 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 verified static at `0xce8804` (`{0.002, 0.002}`, init `0x6c7c20`):
-/// a **viewport fraction**, resolved per-axis and integer-rounded at draw (module doc; wow-re
-/// `worldtext-shadow-render-law.md`, TU-A — which corrected our first `× diagonal` reading: the
+/// 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).
 const SHADOW_OFFSET_FRAC: f32 = 0.002;
 
@@ -293,9 +291,9 @@ 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 (wow-re `worldtext-measured-block-wh-law.md`, §5 b2d59e6e): `0x6c81a0`
+/// 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 byte-verified dead store), width = the advance
+/// 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,
@@ -310,8 +308,8 @@ 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` — `time_alpha_fade 0x6c82e0`'s two
-/// lanes (§5-verified constants 255.0 / 127.0) composed through the store seam (module doc, the
+/// 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
@@ -342,7 +340,7 @@ pub(super) fn fade_alpha(cat: &Category, elapsed_ms: f32) -> (u8, u8) {
     (text, shadow.min(text))
 }
 
-/// The category's scale value at normalized life `t` (`keyframe_interp 0x6c80b0`): category 2 runs
+/// 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.
 pub(super) fn scale_value(category: u8, t: f32) -> f32 {
@@ -378,9 +376,9 @@ mod tests {
 
     /// 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 of the §8 Q4
-    /// re-pin: a 16:9 window sizes by ITS diagonal, not the 4:3 constant).
-    /// The claimed-box anchors from wow-re `worldtext-measured-block-wh-law.md` (b2d59e6e) at
+    /// 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.
@@ -413,18 +411,18 @@ mod tests {
         assert_eq!(text_px(scale_value(0, 0.5), ref43), 23.0);
     }
 
-    /// The shadow offset law (`worldtext-shadow-render-law.md` TU-A): a per-axis viewport
+    /// 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() {
-        // The verdict's own example: 1920×1080 → {round(3.84), round(2.16)} = {4, 2}.
+        // 1920×1080 → {round(3.84), round(2.16)} = {4, 2}.
         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 old note's
-        // "~2.6 px" diagonal read never rendered.
+        // The 4:3 reference window: {round(2.048), round(1.536)} = {2, 2} — the "~2.6 px"
+        // diagonal read never rendered.
         assert_eq!(
             shadow_offset_px(Vec2::new(1024.0, 768.0)),
             Vec2::new(2.0, 2.0)
@@ -442,9 +440,9 @@ mod tests {
         assert_eq!(CATEGORIES[5].color, 0xFFE0_CA0A);
     }
 
-    /// `time_alpha_fade 0x6c82e0` at the pinned points of row 0 (in 150 / out 760 / dur 1500),
+    /// 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 byte-verified pop-in), 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
diff --git a/crates/benilla-app/src/combat_text/mod.rs b/crates/benilla-app/src/combat_text/mod.rs
index d4cdacb9..d68816c7 100644
--- a/crates/benilla-app/src/combat_text/mod.rs
+++ b/crates/benilla-app/src/combat_text/mod.rs
@@ -1,5 +1,4 @@
-//! **Floating combat text** (decision 0137 phase 2) — the client's WORLDTEXTSTRING engine
-//! (wow-re `playername/scratch/worldtext-spawn-and-law.md`, §5-verified 2026-07-05).
+//! **Floating combat text** (decision 0137 phase 2) — the client'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
@@ -14,10 +13,9 @@
 //! 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).
 //!
-//! **The COLOR law** (wow-re `playername/scratch/combattext-color-law.md`, §5-verified
-//! 2026-07-06 — 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; the note's
-//! "+0x25 sign" byte) and `K` (the `0x5efea0` **source-ownership** class: self / owned-by-me /
+//! **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
@@ -43,14 +41,14 @@
 //! 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 render geometry** (wow-re `worldtext-geometry-law.md`, §5-verified, 9af65294 — zero free
+//! **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`; wow-re `object-layer/scratch/nameplate-offscreen-cull.md`,
-//! §5-VERIFIED 2026-08-15), never clamped to a border and never claiming a bucket-1 rect. Ours
+//! (`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
@@ -58,8 +56,8 @@
 //! 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`, wow-re `crates/font/src/screen_pixel.rs`, bit-exact
-//! difftested). At 1024×768 (diag 1280): normal number 23 px, crit settles 35 px, pop peaks ~70 px.
+//! `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
@@ -68,9 +66,8 @@
 //! 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 ALPHA + SHADOW law** (`time_alpha_fade 0x6c82e0` — wow-re
-//! `playername/scratch/worldtext-alpha-shadow-law.md`, §5 pair + the emulated bit-exact difftest,
-//! 2026-07-12; the director's "XP text less visible than ref"): the per-tick fade REPLACES the
+//! **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:
@@ -85,9 +82,9 @@
 //! black, `(al<<24)|0` → `SetShadowColor 0x5c27a0` with the static offset `0xce8804 =
 //! {0.002, 0.002}` (init `0x6c7c20`), every category, unconditionally.
 //!
-//! **The STORE seam caps the shadow** (font node `outline-bake-tint.md` §5, byte-verified):
+//! **The STORE seam caps the shadow**:
 //! `SetShadowColor`'s persistent store `0x5cd650` writes the shadow colour's alpha byte as
-//! **`min(shadowA, mainA)`** — and `time_alpha_fade` calls SetColor (text) *then* SetShadowColor
+//! **`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
@@ -96,13 +93,11 @@
 //! 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 whole as-rendered law is wow-re
-//! `playername/scratch/worldtext-shadow-render-law.md` (§5 three pairs, 2026-07-13).
+//! 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, wow-re
-//! `ui/scratch/smartscreenrect-solver-law.md`, §5 2026-07-13). Every frame each live string
+//! 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`,
@@ -187,7 +182,7 @@ pub(crate) struct WorldTexts(Vec<WorldText>);
 /// 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, as three wow-re notes had it — it
+/// **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,
@@ -341,8 +336,7 @@ pub(crate) fn float_combat_text(
     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 (wow-re `object-layer/scratch/nameplate-offscreen-cull.md`, §5-VERIFIED
-    // 2026-08-15). Collected here and reaped after the walk, since the walk holds the list.
+    // to a border. Collected here and reaped after the walk, since the walk holds the list.
     let mut culled: Vec<usize> = Vec::new();
     for i in order {
         let t = &texts.0[i];
@@ -402,7 +396,7 @@ pub(crate) fn float_combat_text(
         // 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 `string_measure_layout`'s `GxuFontCreateString` —
+        // 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
@@ -411,7 +405,7 @@ pub(crate) fn float_combat_text(
             // 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`], wow-re `worldtext-measured-block-wh-law.md`).
+            // ([`claimed_box_px`], `0x6c81a0`).
             let claim = claimed_box_px(b.width(), size_value, viewport);
             let (hw, hh) = (claim.x * 0.5, claim.y * 0.5);
             let cx = screen
@@ -663,8 +657,8 @@ mod tests {
     }
 
     /// **A travelling spell's outcome word is DEFERRED, and it is GOLD** (decision 2229) — the
-    /// arrival half of the miss text, and the case the whole round came from: a resisted Fireball
-    /// reads "Resist" in spell gold when the ball lands, not white at GO.
+    /// 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:
diff --git a/crates/benilla-app/src/console.rs b/crates/benilla-app/src/console.rs
index 00bb6a44..161b8fdc 100644
--- a/crates/benilla-app/src/console.rs
+++ b/crates/benilla-app/src/console.rs
@@ -1,6 +1,6 @@
 //! 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 (wow-re `console/console.md`, the upper band). A
+//! 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.
diff --git a/crates/benilla-app/src/crash.rs b/crates/benilla-app/src/crash.rs
index 96a5644e..a8b67d96 100644
--- a/crates/benilla-app/src/crash.rs
+++ b/crates/benilla-app/src/crash.rs
@@ -46,38 +46,10 @@ pub(crate) fn install(build: BuildId) {
     }));
 }
 
-/// `WOW_CRASH_INJECT=<at_secs>` — one deliberate main-thread panic, mid-run: the standing test
-/// affordance for this module, in the shape of `perf::stall`'s injectors and armed beside them.
-/// 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.
-pub(crate) fn arm_injector(app: &mut bevy::prelude::App) {
-    use bevy::prelude::*;
-    if let Some(at) = std::env::var("WOW_CRASH_INJECT")
-        .ok()
-        .and_then(|v| v.parse::<f32>().ok())
-    {
-        app.insert_resource(CrashInject { at });
-        app.add_systems(Update, crash_inject);
-    }
-}
-
-#[derive(bevy::prelude::Resource)]
-struct CrashInject {
-    at: f32,
-}
-
-fn crash_inject(
-    inject: bevy::prelude::Res<CrashInject>,
-    time: bevy::prelude::Res<bevy::prelude::Time<bevy::time::Real>>,
-) {
-    if time.elapsed_secs() >= inject.at {
-        bevy::log::warn!(
-            "crash-inject: panicking the main thread at {:.1} s",
-            inject.at
-        );
-        panic!("crash-inject: deliberate panic (WOW_CRASH_INJECT)");
-    }
-}
+// 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.
 
 /// 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,
diff --git a/crates/benilla-app/src/creature_anim.rs b/crates/benilla-app/src/creature_anim.rs
index fcfec173..06438e09 100644
--- a/crates/benilla-app/src/creature_anim.rs
+++ b/crates/benilla-app/src/creature_anim.rs
@@ -8,8 +8,8 @@
 //!
 //! Regimes (decisions 0049 → 0083/0087):
 //! - **Gait** — the directly-cross-faded ground/swim gaits + idle: Stand / Walk / Run / Fast-run by speed,
-//!   WalkBackwards when moving back, the swim ids when swimming (verified client selector, wow-5875-re
-//!   RF-0057). A change cross-fades to the new clip over its `blend_time` instead of snapping.
+//!   WalkBackwards when moving back, the swim ids when swimming (the client's selector `0x5fd8b0`).
+//!   A change cross-fades to the new clip over its `blend_time` instead of snapping.
 //! - **Special** — the stand-state poses (sit/sleep/kneel: down → loop → up) as one-shot-bracketed
 //!   loops, **preemptible** (decision 0055), plus the jump's enter/hang. The jump's *landing* is NOT a
 //!   bracket: [`select::Mode::Land`] is a plain pick from the input at touchdown, freely overwritten the
@@ -20,7 +20,7 @@
 //!   torso-masked overlay ([`AnimClip::upper_node`]) while the base keeps driving the legs underneath —
 //!   never dropped, never bracket-gated.
 //!
-//! The playback **rate** of a locomotion clip is `speed / sequence.moveSpeed` (wow-5875-re `0x5fe2f0`), so
+//! The playback **rate** of a locomotion clip is `speed / sequence.moveSpeed` (`0x5fe2f0`), so
 //! a unit moving faster than the clip's design speed cycles its legs proportionally faster (the fix for a
 //! backpedal that otherwise drags). Non-locomotion clips (idle, the jump/sit transitions — `moveSpeed 0`)
 //! play at 1×. Death (decoded health 0) overrides everything.
@@ -42,9 +42,9 @@ use bevy::prelude::*;
 use benilla_assets::AssetSet;
 use benilla_world::schedule::WorldStage;
 
-/// The pure animation-selection logic (RF-0057/0073 tables, movement/Special state, gait/swing/ready
-/// picks, playback-rate math) — kept in its own file as it carries the bulk of the unit-tested selector
-/// logic, separate from the Bevy driver systems in [`driver`].
+/// The pure animation-selection logic (the `0x5fd100`/0073 tables, movement/Special state,
+/// gait/swing/ready picks, playback-rate math) — kept in its own file as it carries the bulk of the
+/// unit-tested selector logic, separate from the Bevy driver systems in [`driver`].
 pub(crate) mod select;
 pub(crate) use select::{
     ease_strafe_yaw, move_flags, strafe_body_offset, swim_body_rotation, MovementState,
@@ -59,8 +59,8 @@ pub(crate) use twist::{wrap_pi, BodyTwist};
 /// The unit animation-LOD gate (decision 0448): park an off-frustum rig's per-bone pose
 /// evaluation — the clocks, the driver state machine, and the event tracks keep running, so
 /// off-screen combat stays audible (0075) and a re-appearing unit snaps to the absolute-clock
-/// pose. Shipped as a modernization; wow-re's 2026-08-13 election correction
-/// (`outdoor-object-pass-election.md`) made it the faithful direction instead — decision 1473
+/// pose. Shipped as a modernization, it is the faithful direction instead: the reference does not
+/// tick an off-frustum unit (`0x683dd0`'s second walk) — decision 1473
 /// records that, and what still diverges (parked rigs keep drawing; the reference keeps only
 /// `MORE_AUDIBLE` creatures audible off-screen).
 mod lod;
@@ -86,8 +86,8 @@ pub(crate) struct Wielded {
     /// ([`select::ranged_load_anim`], the client's `0x5fd530` LUT; decision 0099 phase 5).
     pub(crate) ranged: Option<(u8, u8)>,
     /// The mainhand/offhand items' sheath *types* (1 back-2H · 2 back-staff · 3 hip · 4 shield ·
-    /// 0 none) — each picks its arm's draw/stow one-shot independently (VERIFIED wow-re
-    /// `sheath-anim-pick.md`: `(1 << (rec[+4] & 0x1f)) & 0x88` → HipSheath 90 for types {3, 7},
+    /// 0 none) — each picks its arm's draw/stow one-shot independently (`0x611930`:
+    /// `(1 << (rec[+4] & 0x1f)) & 0x88` → HipSheath 90 for types {3, 7},
     /// Sheath 89 otherwise; the slot's own byte is the *only* input).
     pub(crate) main_sheath: u8,
     pub(crate) off_sheath: u8,
@@ -129,8 +129,7 @@ pub(crate) const UNIT_FLAG_DISARMED: u32 = 0x0020_0000;
 pub(crate) const ITEM_CLASS_WEAPON: u8 = 2;
 
 /// **The disarm ladder** — which single held slot `UNIT_FLAG_DISARMED` hides, given what each
-/// melee hand holds (decision 1863; wow-re `disarm-weapon-gate-law.md` §2, byte-verified by a
-/// trio including a cold decoder-first read, both class bodies identical).
+/// melee hand holds (decision 1863; both class bodies identical).
 ///
 /// The reference does not "empty a disarmed unit's hands". `GetWeapon(slot, visFlag = 0)` runs a
 /// **two-probe ladder with main-hand precedence**, and the off-hand probe's polarity is the
@@ -198,46 +197,44 @@ impl Wielded {
 /// **It carries that GUID**, because the reference's `[+0xc48]` is the target and not a flag, and
 /// a second reader wants the unit and not just the fact: `0x6e3480`'s melee arm resolves
 /// `[caster+0xc48]` and uses THAT unit's combat reach, which is what the spell tooltip's range
-/// cell prints while you are auto-attacking (wow-re
-/// `tooltip-damage-matrix-and-container-slots.md` §D4.2b). Every animation reader still asks only
+/// cell prints while you are auto-attacking. Every animation reader still asks only
 /// `With`/`Has`, which is unchanged by the payload.
 #[derive(Component)]
 pub(crate) struct Engaged(pub(crate) u64);
 
 /// The local player has fired an auto-repeat spell (Auto Shot / wand Shoot) — the client's
 /// `[+0xd58] & 0x200`, whose **only writer binary-wide** is the local cast-send tail (`0x6e593b`,
-/// gated `AttributesEx2 & 0x20`; byte-verified, wow-re `ranged-shot-anim.md`). While it and the
+/// gated `AttributesEx2 & 0x20`). While it and the
 /// ranged **sheath** gate (`CUR == 2`) both hold, a standing unit's base idle is the ranged
 /// weapon's Load clip ([`select::ranged_load_anim`]) — the client's resolver `0x5fd460`,
 /// which gates on exactly this bit; local-player-only by construction (remote units never run
 /// the local cast-send). A REMOTE shooter has no drawn idle at all: it plays LoadBow **once** at
-/// the volley's single `SMSG_SPELL_START` through the PrecastKit ([`CastHold`]), then the fire
-/// clip per GO over its ordinary idle (wow-re `shooter-stop-law.md` §J6 claim 2). Cleared
+/// the volley's single `SMSG_SPELL_START` through the PrecastKit ([`CastHold`], `0x6e7901`), then
+/// the fire clip per GO over its ordinary idle. Cleared
 /// only by [`cancel_auto_repeat_local`]'s callers — the client's cancel `0x6ea080` (its `0x200`
 /// clear `0x6ea113`), reached from the cast-result fail of the cached spell, the button
 /// re-press toggle, melee attack-start, target death, the wand-only new-cast handoff, and
 /// `SMSG_CANCEL_AUTO_REPEAT` — which vmangos DOES send (corrected 2026-08-05; see
-/// [`crate::net::apply::spells::cancel_auto_repeat`]), so against a live server that packet, not
-/// a local death watcher, is what ends a volley whose target dies (wow-re
-/// `nocked-ammo-cancel.md`).
+/// `crate::spell::net`'s `cancel_auto_repeat`), so against a live server that packet, not
+/// a local death watcher, is what ends a volley whose target dies.
 #[derive(Component)]
 pub(crate) struct AutoRepeatArmed;
 
 /// The weapon-visual hold — the client's `[+0xd58] & 0x400`, set for **ANY caster** (self,
 /// remote players, NPCs) whose **ranged** spell visual plays (`0x60d020`, sole caller `0x6ec2cf`
-/// inside `PlaySpellVisual`; byte-verified, wow-re `ranged-sheath-exempt-autorepeat.md` §Q4).
+/// inside `PlaySpellVisual`).
 /// Cleared like the client's id-matched `0x60d040` + its unconditional sibling `0x60fc50`: a
 /// **non-ranged** visual play by the same caster (the stale-visual cleanup `0x6ec39e`), the
-/// local cancel (`0x6ea12b`), melee attack-start, and the spline-move apply (`0x6020e8`, wow-re
-/// `shooter-stop-law.md` §J1.3). Deliberately NOT cleared on sheath change or volley end — the
+/// local cancel (`0x6ea12b`), melee attack-start, and the spline-move apply (`0x6020e8`).
+/// Deliberately NOT cleared on sheath change or volley end — the
 /// client's bit persists latent.
 ///
 /// **It gates nothing here — but no longer for the reason this doc used to give.** `0x400` is
 /// tested in exactly one place image-wide: `0x5fc3f0`'s Hold self-loop gates (`test ah,0x6` for
 /// HoldBow 109, `test ah,0x4` for 110/111/112). 0994 recorded that the dispatcher is never
-/// reached for a bow id (`shooter-stop-law.md` §J4.1) and concluded the bit is dead. **wow-re's
-/// §5 refuted that absence proof** (decision 1544): the dispatcher has a second, deferred fire
-/// site, so those gates DO execute — they are the Hold's own per-completion re-arm.
+/// reached for a bow id and concluded the bit is dead. **That absence proof is wrong**
+/// (decision 1544): the dispatcher has a second, deferred fire site (`0x7075af`), so those gates
+/// DO execute — they are the Hold's own per-completion re-arm.
 ///
 /// We still gate nothing on it, and that is now a *modelling* choice with a stated equivalence
 /// rather than a claim about the binary. Our Hold is armed once and loops until a real recompute
@@ -251,10 +248,9 @@ pub(crate) struct AutoRepeatArmed;
 pub(crate) struct RangedHold;
 
 /// A unit's displayed **nocked ammo** — the client's `[+0xd28]`/`[+0xd2c]` ammo-model pair,
-/// written only by `CGUnit::UpdateAmmoDisplay 0x60ba30` (byte-verified, wow-re
-/// `nocked-ammo-cancel.md`): the ammo's `ItemDisplayInfo` id, rendered as a model on the unit's
-/// **body** at HandArrow (35) — the ONE bone attach, bow-only (§E2; the old Special2/Special3
-/// reading is refuted — those are model-directory selectors, §E1). Set per shot from the
+/// written only by `CGUnit::UpdateAmmoDisplay 0x60ba30`: the ammo's `ItemDisplayInfo` id, rendered
+/// as a model on the unit's **body** at HandArrow (35) — the ONE bone attach, bow-only (`0x60bb19`;
+/// `0x479f40`'s 0x18/0x19 pick a model directory, not Special2/Special3). Set per shot from the
 /// `SMSG_SPELL_START` `CAST_FLAG_AMMO` tail (any caster — the only source for a remote/NPC
 /// shooter). This is the display-id CACHE; whether the arrow is visibly in the hand is the
 /// [`NockLatch`] (the `$BWP`/`$BWR` cycle). Removed by the un-nock `0x60f530` paths: the local
@@ -265,7 +261,7 @@ pub(crate) struct NockedAmmo {
     pub(crate) display_id: u32,
 }
 
-/// The client's nock latch `[+0xd58] & 0x4000` (wow-re `nocked-ammo-cancel.md` §G1/G4): SET at
+/// The client's nock latch `[+0xd58] & 0x4000` (set `0x624b70`, cleared `0x60016c`): SET at
 /// the body clip's **`$BWP`** BowPull keyframe (LoadBow 105 carries it at ~0.6 s — the visible
 /// pull-from-quiver moment, which also (re)attaches the in-hand arrow), CLEARED at **`$BWR`**
 /// BowRelease (AttackBow 46 carries it at ~0.067 s — the arrow leaves the hand as the missile
@@ -301,8 +297,8 @@ pub(crate) fn drive_nock_latch(
     }
 }
 
-/// The one local auto-repeat cancel — benilla's `0x6ea080` (byte-verified whole, wow-re
-/// `nocked-ammo-cancel.md`): clear the live key (`[0xceac30]`), drop the Load/Hold idle gates
+/// The one local auto-repeat cancel — benilla's `0x6ea080`: clear the live key (`[0xceac30]`),
+/// drop the Load/Hold idle gates
 /// (the `0x200`/`0x400` bits — [`AutoRepeatArmed`] + [`RangedHold`]), un-nock the ammo
 /// (`0x60f530` — [`NockedAmmo`]), and ack the server (`CMSG_CANCEL_AUTO_REPEAT_SPELL`, the
 /// client's sole send site `0x6ea0c6`) — **sheath untouched**: the weapon stays drawn, the idle
@@ -310,7 +306,7 @@ pub(crate) fn drive_nock_latch(
 /// live callers.
 pub(crate) fn cancel_auto_repeat_local(
     entity: Option<Entity>,
-    auto_repeat: &mut crate::ui_action::AutoRepeatActive,
+    auto_repeat: &mut crate::spell::AutoRepeatActive,
     commands: &mut Commands,
     net: &crate::net::NetCommands,
 ) {
@@ -327,15 +323,14 @@ pub(crate) fn cancel_auto_repeat_local(
     let _ = net.0.send(crate::net::ClientCommand::CancelAutoRepeat);
 }
 
-/// The one local **StopAttack** — benilla's `0x5ecac0` (wow-re §5 trio-verified,
-/// `object-layer/scratch/melee-autorepeat-exclusion.md`): player-only, a no-op unless an attack
+/// The one local **StopAttack** — benilla's `0x5ecac0`: player-only, a no-op unless an attack
 /// lock is held, then `CMSG_ATTACKSTOP` (its builder `0x624370` pushes opcode `0x142`) followed by
 /// the tail jump `0x5ecb63 → CancelQueuedCast 0x6e6f30` — which takes the **queued on-next-swing
 /// spell** down with the attack: `0x6e6f30`'s first leg tests the inflight id `[0xceca88]` for
 /// `Attributes & 0x404` and hands it to `CancelCast 0x6e4940(dl=1, reason 0x1c)`, whose casting arm
 /// sends `CMSG_CANCEL_CAST 0x12f` naming it and then pops the slot through `0x6e4ad0`.
 ///
-/// This is the un-queue [`crate::ui_cast::QueuedMeleeSpell`] names as its real clear path, and it
+/// This is the un-queue [`crate::spell::QueuedMeleeSpell`] names as its real clear path, and it
 /// is why a Raptor Strike ring goes dark the moment Auto Shot starts (the auto-repeat arm inside
 /// the cast commit calls straight into here, `0x6e5976`, guarded by nothing but "the caster is the
 /// active player").
@@ -346,12 +341,12 @@ pub(crate) fn cancel_auto_repeat_local(
 /// are deliberately unmodelled, neither with a benilla reader: `[+0xc50]` ("locally initiated, not
 /// server-confirmed") and `[+0xc54]` ("stop sent, awaiting the echo") — the latter's sole reader
 /// image-wide is `0x5eccda`, inside `Attack 0x5ecb70`, which no benilla cast path enters while
-/// engaged (see [`crate::ui_action::cast_send`]'s tail). The two ratio legs `0x5ecac0` runs before
+/// engaged (see [`crate::spell::cast_send`]'s tail). The two ratio legs `0x5ecac0` runs before
 /// the stop are `TriggerTutorial(0xa)` / `(0xb)` — the low-health / low-mana popups, not audio and
 /// not part of this seam.
 pub(crate) fn stop_attack_local(
     engaged: bool,
-    queued_melee: &mut crate::ui_cast::QueuedMeleeSpell,
+    queued_melee: &mut crate::spell::QueuedMeleeSpell,
     net: &crate::net::NetCommands,
 ) {
     if !engaged {
@@ -369,8 +364,8 @@ pub(crate) fn stop_attack_local(
     }
 }
 
-/// The one local **StartAttack** — benilla's `0x5ecb70`, [`stop_attack_local`]'s twin (wow-re §5
-/// `melee-autorepeat-exclusion.md` §5c–§5f). Two halves, and keeping them apart is the whole point:
+/// The one local **StartAttack** — benilla's `0x5ecb70`, [`stop_attack_local`]'s twin. Two halves,
+/// and keeping them apart is the whole point:
 ///
 /// - **the send** (`0x5eccfd`) is gated by the already-attacking test at `0x5eccda` — skipped when
 ///   the attack lock is held, *unless* a stop is in flight (`[+0xc54]`), which is why
@@ -395,7 +390,7 @@ pub(crate) fn start_attack_local(
     target: u64,
     engaged: bool,
     stop_in_flight: bool,
-    auto_repeat: &mut crate::ui_action::AutoRepeatActive,
+    auto_repeat: &mut crate::spell::AutoRepeatActive,
     sheath: &mut MessageWriter<SheathRequest>,
     commands: &mut Commands,
     net: &crate::net::NetCommands,
@@ -433,7 +428,7 @@ pub(crate) fn start_attack_local(
 /// pseudo-spell runs (`TryCast`'s effect-`0x4e` short-circuit at `0x6e4c7a` dispatches straight to
 /// it, ahead of every cast gate). It forks on the attack lock and nothing else: already attacking →
 /// `0x6131d9 call 0x5ecac0` [`stop_attack_local`], otherwise `0x6131ee call 0x5ecb70`
-/// [`start_attack_local`] (wow-re `melee-autorepeat-exclusion.md` §5f).
+/// [`start_attack_local`].
 ///
 /// The fork is the whole content, and it is worth a name because both halves used to be wrong here:
 /// the button never toggled melee OFF, and it cancelled a running auto-repeat on *every* press —
@@ -447,8 +442,8 @@ pub(crate) fn toggle_attack_local(
     entity: Entity,
     target: u64,
     engaged: bool,
-    queued_melee: &mut crate::ui_cast::QueuedMeleeSpell,
-    auto_repeat: &mut crate::ui_action::AutoRepeatActive,
+    queued_melee: &mut crate::spell::QueuedMeleeSpell,
+    auto_repeat: &mut crate::spell::AutoRepeatActive,
     sheath: &mut MessageWriter<SheathRequest>,
     commands: &mut Commands,
     net: &crate::net::NetCommands,
@@ -476,13 +471,13 @@ pub(crate) fn toggle_attack_local(
 /// The targeting side needs exactly this: `target::scan`'s `commit` runs the reference's
 /// stop → select → re-swing law (`SetSelection 0x493540`'s own `0x493a08 call 0x5ecac0` and
 /// `0x4938c8 call 0x5ecb70`), so every selection writer that can fire it has to carry both seams'
-/// inputs. [`crate::ui_action::cast_send::CastLadder`] already carries them field by field for the
+/// inputs. [`crate::spell::cast_send::CastLadder`] already carries them field by field for the
 /// cast path and calls the free functions directly.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct AttackSeam<'w, 's> {
     pub(crate) net: Res<'w, crate::net::NetCommands>,
-    pub(crate) queued_melee: ResMut<'w, crate::ui_cast::QueuedMeleeSpell>,
-    pub(crate) auto_repeat: ResMut<'w, crate::ui_action::AutoRepeatActive>,
+    pub(crate) queued_melee: ResMut<'w, crate::spell::QueuedMeleeSpell>,
+    pub(crate) auto_repeat: ResMut<'w, crate::spell::AutoRepeatActive>,
     pub(crate) sheath: MessageWriter<'w, SheathRequest>,
     pub(crate) ecs: Commands<'w, 's>,
     /// Our own entity — the sheath snap's and the auto-repeat cancel's subject.
@@ -530,7 +525,7 @@ pub(crate) struct Casting {
 /// The client's PlayAnimation **call order**, reconstructed. The real client has no pecking
 /// order between a swing and a spell kit's anim landing in the same frame — its handlers run
 /// synchronously in packet order and the LATER `PlayAnimation` call simply overwrites bone 0
-/// (wow-re, the Eviscerate-timing round's arm C). benilla's swing and cast pipelines are
+/// (`0x5fe2f0`). benilla's swing and cast pipelines are
 /// separate message streams, so that order must ride the messages: every emitter of an
 /// animation-bearing request ([`SwingMessage`], [`CastEvent`], [`EmoteAnim`], [`KitPush`])
 /// stamps `next()` at emission — the wire drain stamps in packet order; scene-time emitters
@@ -581,13 +576,13 @@ pub(crate) enum CastEventKind {
     Impact { weapon_visual: Option<u32> },
     /// A projectile arrived at a **ground point** instead of on a unit — the client's per-tick
     /// missile dispatch taking `0x61e1d0` → `0x61d870`, which is the **no-live-target** arm, not
-    /// a ground arm as such (a target that despawned mid-flight lands there too; wow-re
-    /// `missile-arrival-dispatch.md`). Ours is reached only by the single
+    /// a ground arm as such (a target that despawned mid-flight lands there too). Ours is reached
+    /// only by the single
     /// missile a dest-targeted GO with an empty hit list launches
     /// ([`spell_visual::MissileSpawn::ground_aim`]). `entity` is the **caster** — `0x61d870`
     /// plays the kit on it, not on anything at the point — and `pos` is the arrival position,
     /// the client's `extra` override (`0x61d8e7`: `lea edx,[esi+0x20]`). Plays `SpellVisual`
-    /// **field 13 at stage 3** (wow-re `spell-visual-lifecycle.md` §Q4).
+    /// **field 13 at stage 3**.
     GroundImpact { pos: Vec3 },
 }
 
@@ -605,8 +600,7 @@ pub(crate) struct CastHold {
     pub(crate) spell_id: u32,
     /// A ranged-slot shot's wind-up (`Attributes & 0x2` — Throw's ReadyThrown, the bow's
     /// LoadBow): the client brackets every ranged kit play with ranged snaps (`0x60f34c`
-    /// before, the outer `0x6e5930`/`0x6e78f3` after — wow-re
-    /// `ranged-sheath-exempt-autorepeat.md`), so while this hold is live the sheath
+    /// before, the outer `0x6e5930`/`0x6e78f3` after), so while this hold is live the sheath
     /// reconcile's force-stow never survives the frame ([`driver`]'s bracket override).
     pub(crate) ranged: bool,
 }
@@ -614,7 +608,7 @@ pub(crate) struct CastHold {
 /// Per-hand weapon-grip state: whether a weapon is held in the right/left hand, so that hand's fingers
 /// curl into a grip. The real client arms `HandsClosed` (AnimationData 15) on a hand's finger key-bones
 /// **purely by that hand's attach point being occupied by a weapon** — not combat, not sheath state; a
-/// forearm-mounted shield or an empty hand stays open (wow-re `hand-grip-mechanism.md`, `0x60b590` /
+/// forearm-mounted shield or an empty hand stays open (`0x60b590` /
 /// paperdoll `0x5059a0`). Written by the held-item resolver ([`crate::entities`], decision 0072) from the
 /// weapon's hand attach point; read by [`driver::drive_hand_grip`] to hold/release the finger overlay.
 #[derive(Component, Default, Clone, Copy, PartialEq, Eq)]
@@ -681,7 +675,7 @@ pub(crate) struct EmoteAnim {
 }
 
 /// A **state kit's animation id, which is a comparison and never a play** — `PlaySpellVisualKit`'s
-/// stage-2 leg (VERIFIED, wow-re `state-kit-anim-and-stun-pose.md` §1/§2; decision 2085).
+/// stage-2 leg (decision 2085).
 ///
 /// `0x60edf0`'s tail has exactly one site that hands a kit's `+0x8` to the play primitive
 /// (`0x60f3c5 call 0x5fe2f0`), and **stage 2 is diverted around it**: `0x60f387 jne` takes the
@@ -695,8 +689,8 @@ pub(crate) struct EmoteAnim {
 /// It is therefore an animation-**cutting** mechanism, and the cut is not incidental: Charge
 /// (22911) plays `Knockdown`(121) from its impact kit and then cuts it with its own state kit's
 /// `Stun`(14), because 121 ≠ 14 forces the recompute. That is also why no stun ever shows the
-/// `Stun` pose despite 23 kits naming it — the selector `0x5fd8b0` cannot produce 14 (its literal
-/// outputs are enumerated in the note), so the recompute lands on `Stand`.
+/// `Stun` pose despite 23 kits naming it — the selector `0x5fd8b0` cannot produce 14 (14 is not
+/// among its literal outputs), so the recompute lands on `Stand`.
 ///
 /// The driver holds the comparison because the armed id lives there. An aura **refresh** in place
 /// emits nothing: the watcher `0x604d00` fires neither arm when a slot is rewritten with the same
@@ -709,7 +703,7 @@ pub(crate) struct BaseAnimRecompute {
 }
 
 /// Rear up a rider's mount (decision 0441 P2): resolved to a [`EmoteAnim`] one-shot of
-/// MountSpecial(94) on the unit's MOUNT CHILD entity by [`flourish_to_anim`] — the §5-verified
+/// MountSpecial(94) on the unit's MOUNT CHILD entity by [`flourish_to_anim`] — `0x608d50`'s
 /// routing (the flourish plays on the mount model; the rider holds Mount(91) throughout).
 /// Written by the net drain (`SMSG_MOUNTSPECIAL_ANIM` — observed riders only; our own echo
 /// is dropped there) and by the self space-bar gate (`crate::player`, locally at send time).
@@ -776,15 +770,15 @@ pub(crate) struct SpellGoTargets {
     pub(crate) hits: Vec<Entity>,
     /// Units it missed, with the wire's `SpellMissInfo` code — a projectile still flies at
     /// each, and its **arrival** plays the victim's defense clip for DODGE(3)/BLOCK(5) (the
-    /// client's `Missile_C::Update 0x61ceb0` dispatch — Dodge 30 / ShieldBlock 24, never Parry;
-    /// wow-re `smsg-attackerstate-consequences.md` §Q4). No impact kit plays. The deflect
+    /// client's `Missile_C::Update 0x61ceb0` dispatch — Dodge 30 / ShieldBlock 24, never Parry).
+    /// No impact kit plays. The deflect
     /// *flight* visual (the projectile glancing off) stays a named approximation — ours ends
     /// the flight at the target.
     pub(crate) misses: Vec<(Entity, u8)>,
     /// The ground point a dest-targeted cast launched at (`TARGET_FLAG_DEST_LOCATION`), in
     /// **bevy** coords (converted at the apply seam like every scene position). A ground AOE's
     /// GO arrives with empty hit/miss lists and only this. No consumer reads it yet — the
-    /// dest-anchored launch visual is pending the dispatched wow-re read (the persistent area
+    /// dest-anchored launch visual is still an open question (the persistent area
     /// effect anchors to the DynamicObject create, not to this packet).
     pub(crate) dest: Option<Vec3>,
     /// The GO's ammo block (`castFlags & 0x20`, a ranged shot): the `ItemDisplayInfo` id of the
@@ -847,6 +841,7 @@ pub(crate) use impact::{DefenseAnim, PendingImpacts, SwingFlush, SwingImpact, Sw
 /// one-shots ([`EmoteAnim`]) and kit sounds ([`spell_visual::SpellKitSound`]).
 mod blood;
 mod env_damage;
+pub(crate) mod net;
 pub(crate) mod spell_visual;
 use blood::{blood_spurts, load_blood_tables};
 use env_damage::{hard_landing_dust, load_env_damage_table};
@@ -912,8 +907,8 @@ pub(crate) struct AnimDriver {
     /// (`0x5fe48e`, the fields' only reader), and `0x5fe2f0` is the **single** animation entry
     /// point in the image — 40 call sites, locomotion among them (`0x602c60` → `0x5fd9e0` →
     /// `0x5fd8b0` → `0x5fd100`), which is why this is not a one-shot flag: a unit that simply
-    /// starts running consumes the arm, and that is what starts Charge's trail (wow-re
-    /// `charproc8-trail-draw-state.md` §11.5/§11.6). benilla's driver is one batched system, not
+    /// starts running consumes the arm, and that is what starts Charge's trail.
+    /// benilla's driver is one batched system, not
     /// a per-play function, so the arm cannot be read at the call the way the reference reads it.
     started_anim: bool,
     /// A **masked upper-body one-shot** in flight (decision 0087): a swing/emote the live-state route
@@ -952,15 +947,15 @@ pub(crate) struct AnimDriver {
     /// the landing of a bracket-less step-off fall (which must still run the `0x602c60` land pick
     /// even though no Special drove the arc).
     was_falling: bool,
-    /// The **deferred combat one-shot** — the client's `CGUnit+0xd60` cache (wow-re
-    /// `combat-anim-fastpath.md`, decision 0406): a combat clip requested while another combat
+    /// The **deferred combat one-shot** — the client's `CGUnit+0xd60` cache (decision 0406):
+    /// a combat clip requested while another combat
     /// clip plays is NOT armed — the playing clip's rate doubles (op6 2.0f) and the request
     /// parks here, played by the driver the moment no one-shot is live (the client's
     /// base-recompute read). Any normal arm clears it (the client's `0x5fe48e` writes −1 on
     /// every non-fast-path PlayAnimation; the driver clears at its play sites).
     deferred: Option<u16>,
-    /// The armed looping arm's **replay window** (decision 0516 — wow-re `loop-replay-fidget`
-    /// §7/§7d): the variation node the loop armed + its rolled budget `R` (the client's
+    /// The armed looping arm's **replay window** (decision 0516): the variation node the loop
+    /// armed + its rolled budget `R` (the client's
     /// `block+0xbc`; the window is `R` clip-lengths wide, op4 `0x7126d8` — live for LOOPS too,
     /// correcting 0117's "loops ignore it"). The per-frame watchdog (`0x719370`'s transcription
     /// in `drive_animations`) re-arms the id when the node — still the MAIN armed animation —
@@ -1043,9 +1038,9 @@ struct Overlay {
     looping: bool,
 }
 
-/// A key-bone cross-fade in flight ([`AnimDriver::overlay_fade`], decision 0878 — wow-re
-/// `oneshot-lifecycle.md` §5.4). `out` is the **retiring** node, holding the outgoing pose the
-/// client snapshots into the bone's secondary slot (`rep movsd +0x98 → +0xc4`); it is `None` when
+/// A key-bone cross-fade in flight ([`AnimDriver::overlay_fade`], decision 0878). `out` is the
+/// **retiring** node, holding the outgoing pose the client snapshots into the bone's secondary
+/// slot (`0x7123af`: `rep movsd +0x98 → +0xc4`); it is `None` when
 /// a fresh clip fades in over the *inherited base* pose, which needs no node of its own — the base
 /// is already there. `left`/`total` are the window: the fixed 150 ms of a fade-to-rest, or the
 /// incoming clip's own blendTime on a blended re-arm.
@@ -1104,7 +1099,7 @@ impl AnimDriver {
     /// The `AnimationData.dbc` id of the clip this unit is currently playing (target gait, a Special's
     /// enter/loop/exit one-shot, or Death — which the death override records as the gait). `None` before
     /// the first selection. The mouse pick reads it for the **current animation's** bounds sphere — the
-    /// real client's broad-phase volume tracks the playing sequence (wow-re pick-volume RE).
+    /// real client's broad-phase volume tracks the playing sequence (`0x7089c0`).
     pub(crate) fn active_anim(&self) -> Option<u16> {
         match self.mode {
             Mode::Gait => self.gait,
@@ -1165,6 +1160,7 @@ pub(crate) struct CreatureAnimPlugin;
 
 impl Plugin for CreatureAnimPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         twist::plugin(app);
         lod::plugin(app);
         breath::register(app);
@@ -1229,7 +1225,7 @@ impl Plugin for CreatureAnimPlugin {
                     arm_mount_poof_fx,
                     // The aura-slot watcher: state kits persist for the aura's life (the bread).
                     arm_aura_state_fx,
-                    // The pending-morph latch (wow-re `shapeshift-morph-cloud.md`): the aura
+                    // The pending-morph latch (`0x5ff0c0` arms, `0x60abe0` replays): the aura
                     // add/remove edges arm it, and a display swap's rebuild replays the latched
                     // spell's impact kit — the shapeshift cloud, both directions. Arm before
                     // replay: the swap message crosses from last frame's teardown, and its
@@ -1314,7 +1310,7 @@ impl Plugin for CreatureAnimPlugin {
     }
 }
 
-/// Resolve `id` to the id this model actually plays (decision 0082, wow-re `anim-id-resolution.md`):
+/// Resolve `id` to the id this model actually plays (decision 0082, `0x711bf0`):
 /// [`ModelAnimations::resolve`] via `catalog` when `AnimationData.dbc` has loaded, else identity — a
 /// brief window at startup ([`load_anim_data`](sheath::load_anim_data) runs at `Startup`, so this
 /// degrade is only ever live for the first few frames, same shape as `anim_data.map_or(0, ..)`
@@ -1356,13 +1352,13 @@ mod attack_stand_tests {
         // A dead-letter net channel: the send is `let _ = …` and no packet is under test here.
         let (tx, _rx) = crossbeam_channel::unbounded();
         app.insert_resource(crate::net::NetCommands(tx));
-        app.insert_resource(crate::ui_action::AutoRepeatActive(None));
+        app.insert_resource(crate::spell::AutoRepeatActive(None));
 
         let me = app.world_mut().spawn_empty().id();
         app.add_systems(
             Update,
             move |mut commands: Commands,
-                  mut auto_repeat: ResMut<crate::ui_action::AutoRepeatActive>,
+                  mut auto_repeat: ResMut<crate::spell::AutoRepeatActive>,
                   mut sheath: MessageWriter<SheathRequest>,
                   net: Res<crate::net::NetCommands>| {
                 start_attack_local(
@@ -1397,7 +1393,7 @@ mod attack_stand_tests {
 mod nock_latch_tests {
     use super::*;
 
-    /// The `$BWP`/`$BWR` nock cycle (wow-re `nocked-ammo-cancel.md` §G1/G4): the pull keyframe
+    /// The `$BWP`/`$BWR` nock cycle (set `0x624b70`, cleared `0x60016c`): the pull keyframe
     /// latches (only a unit with a cached ammo display), the release keyframe clears — the arrow
     /// appears as she draws it and leaves the hand with the shot.
     #[test]
@@ -1452,7 +1448,7 @@ mod nock_latch_tests {
 mod disarm_tests {
     use super::*;
 
-    /// **The ladder, hand by hand** (decision 1863; wow-re `disarm-weapon-gate-law.md` §2c). The
+    /// **The ladder, hand by hand** (decision 1863; `0x5ec240`/`0x605e30`). The
     /// reference hides **exactly one weapon**, main hand first — so a disarmed dual-wielder
     /// punches with the main hand and still swings its off-hand weapon. Every selector downstream
     /// reaches its own unarmed leg by its own table; there is no disarm case in any of them.
diff --git a/crates/benilla-app/src/creature_anim/blood.rs b/crates/benilla-app/src/creature_anim/blood.rs
index 3c647eb8..71281009 100644
--- a/crates/benilla-app/src/creature_anim/blood.rs
+++ b/crates/benilla-app/src/creature_anim/blood.rs
@@ -1,5 +1,5 @@
 //! The melee **blood spurt** (decision 0137 phase 3) — the fourth element of the victim-feedback
-//! set (wow-re `melee-blood-spurt.md`, byte-verified `0x624530 → 0x625010`): a landed melee blow
+//! set (`0x624530 → 0x625010`): a landed melee blow
 //! hangs a small particle-emitter model (`Particles\BloodSpurts\*.mdx`) on the victim, front or
 //! back by where the attacker stands, sized by the crushing bit, colored by the creature's blood
 //! type. Independent of the wound flinch and the floating text; rides the 0122 kit-effect spawn
@@ -30,7 +30,7 @@ use super::{SpellKitFx, SwingImpact, SwingMessage};
 /// `cvars::REGISTERED` takes one row per knob a settings page actually wires (0137 phase 3).
 const VIOLENCE_LEVEL: usize = 2;
 
-/// The victim-model M2 attachment ids the spurt hangs on (`melee-blood-spurt.md`: CEffect at
+/// The victim-model M2 attachment ids the spurt hangs on (`0x625010`: CEffect at
 /// attach tag 0xf front / 0x10 back — present on every character and creature model checked).
 const ATTACH_FRONT: u16 = 15;
 const ATTACH_BACK: u16 = 16;
diff --git a/crates/benilla-app/src/creature_anim/breath.rs b/crates/benilla-app/src/creature_anim/breath.rs
index 41884c36..bc6ab111 100644
--- a/crates/benilla-app/src/creature_anim/breath.rs
+++ b/crates/benilla-app/src/creature_anim/breath.rs
@@ -1,6 +1,5 @@
 //! **Cold breath** — the visible vapour a unit puffs from its mouth in a cold zone (B233,
-//! decision 1149; wow-re `object-layer/scratch/cold-breath-law.md`, §5 two independent pairs +
-//! byte arbitration).
+//! decision 1149).
 //!
 //! The client hangs three mutually-exclusive puffs off one animation event, and they are the
 //! `$BTH` family: cold vapour, underwater bubbles, and the drunk's bubbles. This module owns the
@@ -41,7 +40,7 @@
 //! ## Stated divergences
 //!
 //! - **The underwater rung is not modelled** — but it is now fully specified rather than open:
-//!   what is missing is the work, not the law (`cold-breath-law.md` §4b). The test is
+//!   what is missing is the work, not the law (`0x607710`'s liquid arm). The test is
 //!
 //!   ```text
 //!   underwater ⟺ 5.0 + SCALE_X · boxHeight < liquidSurfaceZ − unitZ
diff --git a/crates/benilla-app/src/creature_anim/driver.rs b/crates/benilla-app/src/creature_anim/driver.rs
index c8d894a4..93432bc2 100644
--- a/crates/benilla-app/src/creature_anim/driver.rs
+++ b/crates/benilla-app/src/creature_anim/driver.rs
@@ -59,7 +59,7 @@ use wound::{wound_evict, wound_trigger, wound_upkeep, WoundEdge};
 /// value as the per-arm sheath ceremony's overlay weight.
 const ONESHOT_OVERLAY_WEIGHT: f32 = 8.0;
 
-/// The key-bone **fade-to-rest** window (decision 0878 — wow-re `oneshot-lifecycle.md` §5.4): a
+/// The key-bone **fade-to-rest** window (decision 0878): a
 /// finished upper-body one-shot is never stopped. The client's per-frame advance latches the
 /// completion (`0x719370`), the deferred event reaches `CGUnit::OnAnimationFinished 0x5fc920` the
 /// same frame, and that calls op4 with `param_3 = -1` (`0x5fcacb`) — which snapshots the clip's
@@ -83,7 +83,7 @@ enum OneShotReq {
 }
 
 /// The currently-armed one-shot the combat fast-path tests — the client's key-bone-else-bone-0
-/// current-id read (`0x5fe422`, wow-re `combat-anim-fastpath.md` §1): the masked overlay while
+/// current-id read (`0x5fe422`): the masked overlay while
 /// its node still plays, else the full-body [`Mode::Swing`] clip while unfinished. Gait and
 /// Special clips are never returned; their ids aren't combat, so nothing is lost at the
 /// classifier gate.
@@ -194,8 +194,7 @@ fn overlay_fade_upkeep(drv: &mut AnimDriver, player: &mut AnimationPlayer, dt: f
     }
 }
 
-/// The **TRANSPLANT** (`0x5fe919` — wow-re `oneshot-lifecycle.md` §3a, the half
-/// `anim-composition-model.md` §2 was missing; decision 0878). A base **locomotion** clip
+/// The **TRANSPLANT** (`0x5fe919`, decision 0878). A base **locomotion** clip
 /// requested while bone 0 still plays a live **CAST** or **COMBAT** one-shot does not replace it:
 /// the client copies the bone-0 descriptor — its id, its rate, and `+0x08` the clip's **live
 /// elapsed position** — onto the key-bone with `blendFlag = 0`, then hands bone 0 the request. The
@@ -319,8 +318,8 @@ pub(super) fn drive_animations(
         // …and the host's granted modes, for the same reason `unify` reads them on the rider.
         Option<&crate::net::UnitMoveModes>,
         // …and the rider's own `OBJECT_FIELD_SCALE_X`: a mount child's transform carries only its
-        // `CreatureDisplayInfo` column, and the mount renders at the PRODUCT of the two (the
-        // byte-verified mount composition, wow-re `0x613ef0`). The rate divisor wants that product
+        // `CreatureDisplayInfo` column, and the mount renders at the PRODUCT of the two
+        // (`0x613ef0`). The rate divisor wants that product
         // — the mount model's world scale — not the child's local column (decision 0903).
         &Transform,
         // …and whether the rider is US, which only the debug trace reads (decision 0906).
@@ -564,7 +563,7 @@ pub(super) fn drive_animations(
         if movement.is_none() {
             mv.stand_state = store.map_or(0, |s| s.0.unit_stand_state());
         }
-        // Mounted forces stand-state 0 on every recompute (`0x5fdf80`, wow-re sheath-policy §3):
+        // Mounted forces stand-state 0 on every recompute (`0x5fdf80`):
         // no sit/sleep/kneel pose can hold in the saddle.
         if mounted {
             mv.stand_state = 0;
@@ -578,7 +577,7 @@ pub(super) fn drive_animations(
         // mounts are mutually exclusive anyway.
         mv.stealthed = store.is_some_and(|s| s.0.unit_is_stealthed());
         let moving = mv.flags & move_flags::ANY_MOVE != 0;
-        // The airborne arc's bookkeeping (wow-re land-anim-height-gate + rf57b §2): on the arc's
+        // The airborne arc's bookkeeping (jump `0x60e480`, land `0x602c60`): on the arc's
         // FIRST airborne frame, its launch vertical speed splits a **jump** (upward — the client's
         // JumpStart/Jump bracket rides the MSG_MOVE_JUMP event) from a **step-off fall** (level or
         // downward — no bracket; the gait freezes until FALLINGFAR latches Fall 40, and an
@@ -629,7 +628,7 @@ pub(super) fn drive_animations(
         if falling && (!was_falling || launched) {
             drv.jump_arc = mv.vertical_speed > JUMP_ARC_MIN_UP;
         }
-        // The airborne-freeze's exact gate (`0x5fd8e8`, §5-arbitrated — decision 0868):
+        // The airborne-freeze's exact gate (`0x5fd8e8`, decision 0868):
         // keep-current iff `FALLING && (FALLINGFAR || vz ≠ 0)`. The vz clause pins every real
         // arc (ballistics make vz ≠ 0 from the first integrated substep); the one uncovered
         // case is a fresh walk-off's vz == 0 substep, where the client genuinely may re-pick.
@@ -638,7 +637,7 @@ pub(super) fn drive_animations(
         let airborne_frozen =
             falling && (mv.flags & move_flags::FALLING_FAR != 0 || mv.vertical_speed != 0.0);
         // The idle re-face turn-shuffle (decision 0123 — the client's facing-delta latch
-        // `0x607ed0`, wow-re `loop-replay-fidget.md` §5b): a stationary creature easing its yaw
+        // `0x607ed0`): a stationary creature easing its yaw
         // toward its target reads as *turning* to the anim layer, so the gait picks
         // ShuffleLeft/Right and each Shuffle→Stand return re-arms (and, relaxed, re-rolls) Stand
         // — the fidget's recurring trigger. Gated like the client's can-fidget gate (`0x5fce30`:
@@ -709,8 +708,7 @@ pub(super) fn drive_animations(
             continue;
         }
 
-        // **The mount transition's own bone-0 arm** (wow-re `mount-cast-anim-disposition.md` §1 +
-        // `mount-composition.md` Q4, §5 2026-08-03). Both legs of the `UNIT_FIELD_MOUNTDISPLAYID`
+        // **The mount transition's own bone-0 arm**. Both legs of the `UNIT_FIELD_MOUNTDISPLAYID`
         // watcher arm the BODY's bone 0 through op4 `0x7121a0` on the PRIMARY slot: the build
         // `0x607b44` plays **91 `Mount`** with a cross-fade, the teardown `0x607ce0` plays seq
         // **0 `Stand`** with the cross-fade **off** (decision 0931 — the two legs are the same
@@ -780,9 +778,8 @@ pub(super) fn drive_animations(
             drv.deferred = None; // a normal arm clears the fast-path cache (`0x5fe48e`)
         }
 
-        // The loot kneel's trigger (see [`select::LOOT`]; byte-verified, wow-re
-        // `loot-anim-leg.md` §5/§8 — decisions 0515 / 1471 / 1477): the leg needs **two**
-        // predicates, and both SPLIT on IsActivePlayer.
+        // The loot kneel's trigger (see [`select::LOOT`]; decisions 0515 / 1471 / 1477): the
+        // leg needs **two** predicates, and both SPLIT on IsActivePlayer.
         //
         // **Self.** Predicate A (`0x6126b0`) is "a loot session is open" — the client-local
         // loot-target latch. Predicate B (`0x612710`) is the per-object-CLASS filter: which
@@ -818,9 +815,9 @@ pub(super) fn drive_animations(
         } else {
             current_special(&mv, drv.jump_arc)
         };
-        // The loot leg outranks the standState pose resolver (the rf57 chain calls loot before
-        // standState): a looting unit kneels at the loot, never into a sit/sleep bracket. The
-        // airborne Specials keep their precedence (the chain's airborne freeze runs first).
+        // The loot leg outranks the standState pose resolver (the `0x5fd8b0` chain calls loot
+        // before standState): a looting unit kneels at the loot, never into a sit/sleep bracket.
+        // The airborne Specials keep their precedence (the chain's airborne freeze runs first).
         let special = special.filter(|s| !(looting && matches!(s, select::Special::Pose(_))));
 
         // ── Sheath state (decision 0080). The unit's rendered sheath is the **client-side
@@ -829,9 +826,9 @@ pub(super) fn drive_animations(
         // *changes* (the `0x604c70` field-apply — a remote unit's own client volunteered the
         // change; our own echo arrives already-committed and adopts as a no-op), and written by
         // the one-setter requests here + the per-animation reconcile below. Every transition
-        // **snaps by default** — byte-verified across all 24 SetSheatheState call sites (wow-re
-        // `sheath-policy.md`): only the manual toggle's request carries the ceremony, and the
-        // draw/stow sound rides the ceremony playback (no clip → no sound).
+        // **snaps by default** — across all 24 call sites of SetSheatheState `0x611cf0`: only the
+        // manual toggle's request carries the ceremony, and the draw/stow sound rides the ceremony
+        // playback (no clip → no sound).
         let sheath_frame_start = drv.sheath_cur;
         let sheath_byte = store.and_then(|s| s.0.unit_sheath_state()).unwrap_or(0);
         if drv.sheath_cur.is_none() || drv.sheath_byte != Some(sheath_byte) {
@@ -849,7 +846,7 @@ pub(super) fn drive_animations(
         // stow point). A ceremony without playable clips degrades to the snap.
         if let Some(req) = pending_sheath.get(&entity) {
             let cur = drv.sheath_cur.unwrap_or(0);
-            // Mounted is a persistent DRAW-BLOCK (wow-re `sheath-policy.md` §3: the client's
+            // Mounted is a persistent DRAW-BLOCK (the client's
             // recompute `0x5fdf80` tests the mount model FIRST and forces stowed on every
             // PlayAnimation — nothing can stay drawn on a mount). The client's composite
             // recomputes constantly (the mount's own gait plays); our rider track goes silent
@@ -917,8 +914,8 @@ pub(super) fn drive_animations(
         // (op4 `blendFlag≠0` copies the outgoing pose over `+0xc4..`). So this frame's plays are
         // tracked — full-body plays (bone 0: the base track) evict a full-body wound; masked-slot
         // plays (the key-bone) evict a masked wound. A play on the *other* bone leaves the wound
-        // decaying (the §5's inherited-swing case). Mode/gait changes proxy the mode machine's own
-        // base plays; the flags catch the same-id re-plays the proxy can't see.
+        // decaying (the kernel `0x714260`'s inherited-swing case). Mode/gait changes proxy the
+        // mode machine's own base plays; the flags catch the same-id re-plays the proxy can't see.
         // ── The **base-animation lock**'s clearer, keyed on the FINISHED id and run before
         // anything re-picks the base this frame — the reference clears at `0x5fc9c6`, above
         // `OnAnimationFinished`'s own reason branch, so completion and pre-emption both release it
@@ -947,7 +944,7 @@ pub(super) fn drive_animations(
                 return None;
             }
             // `DO_NOT_PLAY_WOUND_ANIM` takes the **parry** with the flinch (`0x60ec1f`, the bit's
-            // second and last consumer — wow-re `wound-parry-gate-and-injury-vocal.md` Q1/Q6).
+            // second and last consumer).
             // The gate is inside `0x60ec00`, which the `$CPP` ladder enters only on
             // victimState 3: DODGE/DEFLECT (30) and BLOCK (24) go straight to PlayAnimation from
             // `0x624a90`/`0x624a74` and are NOT gated — a flagged creature still dodges and still
@@ -1012,7 +1009,7 @@ pub(super) fn drive_animations(
         // hit re-parks its own request — both what the client's `0x5fe48e`/`0x5fe480` do).
         // NEVER mid-air: the read (`0x5fd392`, inside the `0x5fd360` recompute arm) sits
         // downstream of the airborne-freeze, so a park made mid-arc waits — and dies at the
-        // landing play's clear (§5-verified, decision 0868).
+        // landing play's clear (decision 0868).
         if requests.is_empty()
             && drv.deferred.is_some()
             && !airborne_frozen
@@ -1028,7 +1025,7 @@ pub(super) fn drive_animations(
             if drv.base_lock.refuses() {
                 continue;
             }
-            // The COMBAT FAST-PATH (`0x5fe43c`–`0x5fe48b`, wow-re `combat-anim-fastpath.md`,
+            // The COMBAT FAST-PATH (`0x5fe43c`–`0x5fe48b`,
             // decision 0406): a combat clip requested while another combat clip is playing is
             // NOT armed — the CURRENT clip's rate doubles (op6 2.0f re-times its remainder,
             // pose-continuous) and the request parks in the `+0xd60` cache to play afterwards.
@@ -1075,7 +1072,7 @@ pub(super) fn drive_animations(
                 }
                 continue;
             }
-            // Mounted forces the masked route (byte-verified, wow-re mount-composition B1:
+            // Mounted forces the masked route (`0x5fe2f0`'s mounted branch:
             // upper-body one-shots route to the key-bone while mounted, and the 91-force would
             // reclaim bone 0 on the next play anyway): a full-body /wave would replace the seat
             // pose with a standing wave floating over the saddle.
@@ -1097,7 +1094,7 @@ pub(super) fn drive_animations(
                 // swaps the torso in one frame. Note the full-body branch below deliberately does
                 // NOT touch the overlay: on that route the client's key-bone slot keeps its current
                 // descriptor (a dedup no-op), so a standing emote over a still-running masked swing
-                // plays legs-only underneath it (`0x5fe930`; wow-re claim 6 CONFIRMED).
+                // plays legs-only underneath it (`0x5fe930`).
                 retire_overlay(
                     &mut drv,
                     &mut player,
@@ -1119,7 +1116,7 @@ pub(super) fn drive_animations(
                 // Full-body route (standing idle / airborne non-combat), or the split-boneless
                 // masked fallback (the client's −1 key-bone sentinel arms bone 0 too): the clip
                 // replaces the base on bone 0 — **even over a Special**. The client never drops a
-                // play: one slot, last-writer-wins (decisions 0083/0087; the wow-re §3 route puts
+                // play: one slot, last-writer-wins (decisions 0083/0087; the route `0x5fe6c8` puts
                 // a jump-in-place cast/emote on bone 0, replacing the hang — decision 0864 is the
                 // ref's mid-air cast). Cutting an airborne clip freezes the outgoing node first —
                 // the pose-snapshot decay of the client's op4 blend, scoped exactly like
@@ -1186,7 +1183,7 @@ pub(super) fn drive_animations(
         if special_edge {
             drv.deferred = None;
         }
-        // The looping-variation ADVANCE (decision 0516 — wow-re `loop-replay-fidget.md` §7/§7d,
+        // The looping-variation ADVANCE (decision 0516 —
         // the per-frame watchdog `0x719370`): every looping arm installed a window `R`
         // clip-lengths wide; when the armed node — still the MAIN animation (the client checks
         // the armed block: any newer arm superseded the window) — completes its `R` passes, the
@@ -1341,7 +1338,7 @@ pub(super) fn drive_animations(
             if done {
                 // Freeze the held frame, then retire it: the client's snapshot copies an already
                 // *expired* window, so the secondary clamps to `seq.end` and the fade runs from
-                // the clip's final pose (`oneshot-lifecycle.md` §5.4).
+                // the clip's final pose (`0x7123af`).
                 if let Some(a) = player.animation_mut(ov.node) {
                     a.set_speed(0.0);
                 }
@@ -1480,18 +1477,18 @@ pub(super) fn drive_animations(
             // 1. `0x60ea9f` → `0x6125f0`: the victim's cached creature template carries
             //    `type_flags` bit `0x8`, **DO_NOT_PLAY_WOUND_ANIM** — a skeleton, a ghost, a
             //    bone golem has no flesh to recoil, and the reference refuses every flinch it
-            //    would ever take, melee and spell alike (decision 2068; wow-re
-            //    `melee-blood-spurt-suppression.md` §6). It gates the ANIMATION only: the blood
-            //    spurt is a separate system reading [`SwingImpact`] itself, and wow-re §8 Q1 is
-            //    explicit that nothing keyed on creature type suppresses it — a skeleton bleeds.
+            //    would ever take, melee and spell alike (decision 2068). It gates the ANIMATION
+            //    only: the blood spurt is a separate system reading [`SwingImpact`] itself, and
+            //    nothing keyed on creature type suppresses it (`0x624530` → `0x625010`) — a
+            //    skeleton bleeds.
             //    A record we have not received yet reads as NOT flagged, which is `0x6125f0`'s
             //    own null-record leg (`return record ? … : false`), so a creature whose query is
             //    still in flight flinches there too.
-            // 2. `0x60eaac`–`0x60eac8` (wow-re `charproc-rate-override-wound-gate.md`, decision
-            //    2063): a CharProc-11 rate-override node on the unit's effect list — the freeze
-            //    auras' node, Freezing Trap / Ice Block / petrify / web wrap — refuses EVERY
-            //    flinch for as long as it lives. The gate is the node's presence, not its rate
-            //    (kit 3071's 1.0 gates too), so it reads the node list, not the pause it applies.
+            // 2. `0x60eaac`–`0x60eac8` (decision 2063): a CharProc-11 rate-override node on the
+            //    unit's effect list — the freeze auras' node, Freezing Trap / Ice Block /
+            //    petrify / web wrap — refuses EVERY flinch for as long as it lives. The gate is
+            //    the node's presence, not its rate (kit 3071's 1.0 gates too), so it reads the
+            //    node list, not the pause it applies.
             //
             // `no_wound_anim` is read once above, where the parry pick — the flag's other
             // consumer — needs the same answer.
@@ -1535,15 +1532,15 @@ pub(super) fn drive_animations(
         // (gossip, loot, mounts) inherit the policy with zero new sheath wiring.
         // The reconcile tests the **requested** id, not the model-resolved substitute (decision
         // 0125, director-eyes falsification of 0082's resolved-id reading): the client's arm
-        // descriptor carries the id that was ASKED FOR (the cast-override §2.1 writes the kit's
-        // own anim id even on a model lacking the sequence), and `0x5fdb50` reads that
+        // descriptor carries the id that was ASKED FOR (the cast-override `0x5fde80` writes the
+        // kit's own anim id even on a model lacking the sequence), and `0x5fdb50` reads that
         // descriptor. The two differ only when a model lacks the requested clip — the ground
         // truth is GnollCaster.m2: no ReadySpellDirected(51) at all, its hold falls back to a
         // flags-less Stand for *playback*, yet the ref still stows the staff for the whole
         // windup — only 51's own `&4` row can do that. (0082's chicken rationale collapses under
         // the same lens: requested Attack2H's 0x20 vs resolved AttackUnarmed's 0x10 is
-        // unobservable on a weaponless chicken.) Byte arbitration of `0x5fdb50`'s miss path is
-        // dispatched to wow-re; the director's eyes outrank the old reading meanwhile.
+        // unobservable on a weaponless chicken.) The byte reading of `0x5fdb50`'s miss path is
+        // open; the director's eyes outrank the old reading meanwhile.
         // The reconcile must see **every play** (decision 0087 (d)): the client's `0x5fdf80` runs
         // inside `PlayAnimation` itself, so a *masked* one-shot — which never touched `mode`, so
         // `active_anim()` still reports the base gait — is reconciled all the same. A masked emote
@@ -1577,9 +1574,8 @@ pub(super) fn drive_animations(
             if let Some(forced) =
                 select::reconcile_sheath(cur, anim, flags, engaged, is_self, sheath_byte, mounted)
             {
-                // The ranged wind-up **bracket** (wow-re `ranged-sheath-exempt-autorepeat.md`,
-                // Q1's ordering law): the client surrounds every ranged kit play with ranged
-                // snaps — `0x60f34c` before the play, the outer send/START `SetSheatheState
+                // The ranged wind-up **bracket**: the client surrounds every ranged kit play with
+                // ranged snaps — `0x60f34c` before the play, the outer send/START `SetSheatheState
                 // (2,1,1)` after — so ReadyThrown 108's genuine force-stow (NOT in the `0x5fe180`
                 // exempt set) exists but never renders: the snap always wins the frame. Our
                 // frame-spread ECS can't reproduce the call-stack order, so the bracket is
@@ -1607,7 +1603,7 @@ pub(super) fn drive_animations(
             }
         }
         // Leaving the ranged sheath stance un-nocks (the client's `0x60fc72` un-nock, gated
-        // `[+0xd40] != 2`; wow-re `nocked-ammo-cancel.md`): however the state left 2 this frame
+        // `[+0xd40] != 2`): however the state left 2 this frame
         // — a stow/melee request, the reconcile, the server byte — the ammo model drops.
         // Re-drawing shows no ammo until the next `SMSG_SPELL_START` re-affirms it.
         if sheath_frame_start == Some(2) && drv.sheath_cur != Some(2) {
@@ -1617,8 +1613,7 @@ pub(super) fn drive_animations(
         }
         // …and **TRANSLATING** un-nocks too — the arrow leaves the hand and the string relaxes,
         // while the cached ammo display survives for the next pull and the weapon stays DRAWN.
-        // Byte-verified (wow-re `shooter-stop-law.md` §J1.1, which refuted our recorded "nothing
-        // in the client un-nocks on movement"): `0x60e480` is a movement-OPCODE dispatcher whose
+        // `0x60e480` is a movement-OPCODE dispatcher whose
         // jump-table arm 0 runs `0x60e4ac call 0x60f530` (un-nock) + `RecomputeBaseAnim(-1)`, and
         // arm 0 is reached by exactly MSG_MOVE_START_{FORWARD, BACKWARD, STRAFE_LEFT,
         // STRAFE_RIGHT, SWIM} (181/182/184/185/202). **Turning and stopping do NOT un-nock** —
@@ -1628,8 +1623,8 @@ pub(super) fn drive_animations(
         //
         // The reference's trigger is the START opcode (an edge); a level test is equivalent here
         // because the only thing that can re-latch is `$BWP`, authored solely in the Load clips —
-        // which a translating unit never plays. Sheath is untouched (§J1's claim-4 split: REFUTED
-        // for un-nock, CONFIRMED for stow — `[+0xd40]` has no movement-path writer).
+        // which a translating unit never plays. Sheath is untouched (`[+0xd40]` has no
+        // movement-path writer: only the ctor's `0x5fafa0` and `0x611cf0` write it).
         if mv.flags & (move_flags::ANY_MOVE | move_flags::SWIMMING) != 0 && nock_latched {
             commands.entity(entity).remove::<super::NockLatch>();
         }
diff --git a/crates/benilla-app/src/creature_anim/driver/grip.rs b/crates/benilla-app/src/creature_anim/driver/grip.rs
index b9b53152..ee3689cf 100644
--- a/crates/benilla-app/src/creature_anim/driver/grip.rs
+++ b/crates/benilla-app/src/creature_anim/driver/grip.rs
@@ -7,7 +7,7 @@ use bevy::prelude::*;
 use super::super::{HandGrip, HAND_GRIP_WEIGHT};
 
 /// Hold each hand's `HandsClosed` finger pose while that hand grips a weapon, release it when it doesn't
-/// — the persistent weapon-grip overlay (wow-re `hand-grip-mechanism.md`: the client arms the finger
+/// — the persistent weapon-grip overlay (`CloseHand 0x479660`: the client arms the finger
 /// key-bones with `HandsClosed` purely by a weapon occupying that hand's attach point). Played *over* the
 /// gait on the finger-mask nodes, so the arm keeps its animation while only the fingers curl; on release
 /// the fingers fall back to the base gait's flat Stand rest. Idempotent — plays only on the open→closed
diff --git a/crates/benilla-app/src/creature_anim/driver/mode.rs b/crates/benilla-app/src/creature_anim/driver/mode.rs
index 2cabfee6..e35210ed 100644
--- a/crates/benilla-app/src/creature_anim/driver/mode.rs
+++ b/crates/benilla-app/src/creature_anim/driver/mode.rs
@@ -91,8 +91,8 @@ pub(super) fn run(
         Mode::Entering(sp) => {
             // The swim re-latch does NOT cut the hop's kick: JumpStart PLAYS OUT over the
             // re-latch and the swim gait resumes only at its end (decision 0517 —
-            // director-corrected against the ref; the §5's static cut-at-relatch law could
-            // not reproduce the screen and is flagged wow-re-side for a live capture).
+            // director-corrected against the ref; the static byte reading, a cut where the freeze
+            // gate `0x5fd8e8` releases, could not reproduce the screen and is unconfirmed live).
             // Only the swim re-latch holds — a ground landing, a water exit, or a new
             // Special still cuts (0503's snapshot-freeze).
             let swim_relatch_hold = sp == select::Special::Jump
@@ -266,10 +266,10 @@ pub(super) fn run(
             } else if matches!(under, Some(select::Special::Jump | select::Special::Fall)) {
                 // The airborne-freeze (`0x5fd8e8` keep-current): mid-arc nothing re-picks
                 // bone 0 — a finished clip clamps and holds its last frame for the rest of
-                // the arc (the §6 clamp path), and a mid-air flag change is a keep-current
+                // the arc (the clamp at `0x7145db`), and a mid-air flag change is a keep-current
                 // no-op. The only exits are the edges above: the FALLINGFAR latch's Fall
                 // and the land pick at touchdown. This holds over Fall too: 0864's per-tick
-                // Fall(40) re-assert was §5-REFUTED (decision 0868 — Fall plays ONCE, at the
+                // Fall(40) re-assert was refuted (decision 0868 — Fall plays ONCE, at the
                 // latch edge `0x61a820@0x61a9eb`; `0x5ff030` is a wire-apply path, not a
                 // tick), so a clip that takes bone 0 after the latch holds until landing.
             } else if let Some(sp) = under {
@@ -293,10 +293,9 @@ pub(super) fn run(
                 }
             } else if oneshot_finished(player, anims, id, catalog) || mv.flags != drv.gait_flags {
                 // A finished one-shot recomputes the base — the ranged FIRE clips included
-                // (decision 1544, superseding 0994 §1). 0994 held them out on
-                // `shooter-stop-law.md` §J4's claim that the completion dispatcher `0x5fc3f0`
-                // is never reached for a bow id; wow-re's §5 refuted that as an absence proof
-                // whose census could not see its second fire site — the natural-completion path
+                // (decision 1544, superseding 0994 §1). 0994 held them out on the claim that
+                // the completion dispatcher `0x5fc3f0` is never reached for a bow id; it is,
+                // through a second fire site — the natural-completion path
                 // enqueues the callback as a plain ARGUMENT (`0x7194f5` pushes mode 0) and
                 // `0x7074b0` invokes it later as `call [esi+4]`, so a scan for
                 // `call dword ptr [reg+0x70]` misses it by construction. 46/49/107 land on the
@@ -367,7 +366,7 @@ pub(super) fn run(
                 );
                 drv.gait = None;
             } else if airborne_frozen && drv.gait.is_some_and(|g| g != DEATH) {
-                // The airborne-freeze on the STEP-OFF arc — the exact §5-verified gate
+                // The airborne-freeze on the STEP-OFF arc — the exact gate
                 // (`0x5fd8e8`: `FALLING && (FALLINGFAR || vz ≠ 0)`, decisions 0864/0868;
                 // the selector chain's leg right after death): mid-air the selector never
                 // re-picks, so the takeoff-frozen gait keeps rolling mid-cycle AND the live
@@ -461,7 +460,7 @@ pub(super) fn run(
                 // (self: the latch; remote: the flag — the `looting` predicate above) on a
                 // stationary, unmounted unit, the gait slot holds Loot 50 — over the cast
                 // pin, the Ready/ranged idles, the chair loops and the state-emote idle
-                // alike (the `0x5fd8b0` chain order, §5-verified: locomotion → LOOT →
+                // alike (the `0x5fd8b0` chain order: locomotion → LOOT →
                 // standState → combat/channel). The trigger dropping cross-fades back to
                 // whatever the slot picks next.
                 let loot_cands;
@@ -492,7 +491,7 @@ pub(super) fn run(
                 };
                 let target = cands[0];
                 // **The turn-shuffle is released by its own clip window, not by the turn ending**
-                // (decision 1655, wow-re `object-layer/scratch/turn-shuffle-lifecycle.md`).
+                // (decision 1655).
                 //
                 // The client's only per-frame poll of a standing unit's base animation is
                 // `0x607ed0`'s tail, and it *refuses* this exact transition: with the shuffle
@@ -519,7 +518,7 @@ pub(super) fn run(
                     }
                     _ => target,
                 };
-                // Each RF-0057 candidate, in priority order, resolved through the model's own
+                // Each `0x5fd8b0` candidate, in priority order, resolved through the model's own
                 // baked fallback (decision 0082) before moving to the next candidate — a model
                 // missing the exact id still plays its baked substitute rather than stepping
                 // down the selector's own list early. The state-emote idle's id (above) resolves
@@ -537,8 +536,8 @@ pub(super) fn run(
                     // sweeping every node of the id. A completed ranged Load simply clamps at
                     // full draw and stays there; nothing promotes it (0994).
                 } else if let Some(c) = clip {
-                    // **The two bypasses the reference keeps** (wow-re
-                    // `base-anim-lock-knockdown.md` §6/§7.6): the death poses and the mount attach
+                    // **The two bypasses the reference keeps** (`0x5fc563`,
+                    // `0x607b44`): the death poses and the mount attach
                     // write the arm primitive directly and are not gated by the base-anim lock. In
                     // benilla both arrive as ordinary gait targets, so they say so here — a body
                     // knocked flat and then killed must still fall dead, and mounting during a
@@ -557,8 +556,8 @@ pub(super) fn run(
                     } else {
                         // A looping base arm rolls its variation when relaxed (decision 0123 —
                         // the client's base-arm `variationIdx = −1`; a combat/cast arm keeps the
-                        // deterministic head) AND its replay budget (decision 0516 §7d — the
-                        // watchdog window). A re-armed Stand landing on its rare look-around
+                        // deterministic head) AND its replay budget (decision 0516, `0x712784`
+                        // — the watchdog window). A re-armed Stand landing on its rare look-around
                         // variations IS the idle fidget.
                         let (c, budget) = roll_loop(anims, c, relaxed, rng);
                         if traced && benilla_assets::trace::enabled() {
@@ -618,7 +617,7 @@ pub(super) fn run(
 }
 
 /// Has the base slot's armed looping clip finished its **replay window** — the client's
-/// `windowHi = windowLo + span·R` (decision 0516 §7d, wow-re `loop-replay-fidget.md` §7a)?
+/// `windowHi = windowLo + span·R` (`0x712784`, decision 0516)?
 ///
 /// `true` when there is no window to wait on at all: a slot with nothing armed, or one whose
 /// window a newer arm superseded, is not something to hold a shuffle against. The driver's own
diff --git a/crates/benilla-app/src/creature_anim/driver/play.rs b/crates/benilla-app/src/creature_anim/driver/play.rs
index 72237cd7..90cd75f0 100644
--- a/crates/benilla-app/src/creature_anim/driver/play.rs
+++ b/crates/benilla-app/src/creature_anim/driver/play.rs
@@ -14,8 +14,7 @@ use super::super::{find_resolved, AnimDriver};
 use super::select::{self, jump_land_pick, Mode, Special};
 
 /// The **base-animation lock** — the reference's `[unit+0xd58]` bits `0xc0000`, which are the whole
-/// reason a Lashed player visibly falls over (VERIFIED, wow-re `base-anim-lock-knockdown.md`;
-/// decision 2096, correcting 2085's §3).
+/// reason a Lashed player visibly falls over (decision 2096, correcting 2085's §3).
 ///
 /// `CGUnit::PlayAnimation 0x5fe2f0` opens with a guard that returns having done nothing at all:
 ///
@@ -51,7 +50,7 @@ impl BaseAnimLock {
     }
 
     /// The guard: is a play refused right now? An **unconditional early return**, not a priority
-    /// comparison and not a dedup (`base-anim-lock-knockdown.md` §7.3).
+    /// comparison and not a dedup (`0x5fe3a1`).
     pub(super) fn refuses(self) -> bool {
         self.0.is_some()
     }
@@ -66,7 +65,7 @@ impl BaseAnimLock {
     /// The clearer, keyed on the **finished** id. Called once a frame before anything re-picks the
     /// base, so completion and pre-emption both release it: an overridden clip's node still reports
     /// finished at the end of its own span, which is exactly the reference's "the base stays locked
-    /// for the rest of the clip's window" when a mount arms over a knockdown (§7.6).
+    /// for the rest of the clip's window" when a mount arms over a knockdown (`0x607b44`).
     pub(super) fn release_finished(
         &mut self,
         player: &AnimationPlayer,
@@ -80,12 +79,13 @@ impl BaseAnimLock {
         }
     }
 
-    /// Drop the lock outright — the reference's other two clearing sites (§7.5/§7.6).
+    /// Drop the lock outright — the reference's other two clearing sites.
     ///
     /// A **model rebuild** needs no call here: benilla's rebuild removes [`AnimDriver`] itself
     /// (`entities::live_display`), so the lock goes with it and the unit comes back with the base
     /// unheld — which is the reference's own outcome at `0x60adee`, reached differently. What does
-    /// call it is the pair of arms the reference never gates: the death pose and the mount attach.
+    /// call it is the pair of arms the reference never gates: the death pose (`0x5fc563`) and the
+    /// mount attach (`0x607b44`).
     pub(super) fn release(&mut self) {
         self.0 = None;
     }
@@ -191,7 +191,7 @@ pub(super) fn roll_oneshot<'a>(
 }
 
 /// Pick a looping arm's **variation** (decision 0123 — the client's base-arm `variationIdx = −1`,
-/// wow-re `loop-replay-fidget.md` §5b): a **relaxed** arm makes the weighted `_rand` walk (the
+/// `0x5fe697`): a **relaxed** arm makes the weighted `_rand` walk (the
 /// same roll as a one-shot's — this is where a re-armed Stand lands on its rare look-around
 /// variations, the fidget); a combat/cast arm is forced to the deterministic head
 /// ([`select::arm_forces_head`] decides which, at the call site). The kernel itself never
@@ -213,8 +213,8 @@ pub(super) fn pick_loop_variation<'a>(
 }
 
 /// The looping arm's two rolls in op4's order (variation `0x71249a`, then the replay budget
-/// `0x712692..` — the same two `_rand` sites as a one-shot's; decision 0516, wow-re
-/// `loop-replay-fidget.md` §7d): the budget is live for **loops** too — not as a repeat cap but
+/// `0x712692..` — the same two `_rand` sites as a one-shot's; decision 0516): the budget is live
+/// for **loops** too — not as a repeat cap but
 /// as the watchdog **window**, `R` clip-lengths wide (`windowHi = arm + span·R`). Returns the
 /// armed clip + `R` = total passes before the watchdog re-arms (`R ∈ [min, max−1]` floored to 1
 /// — `replayMax` is exclusive, and `(0,0)`/`(0,1)` both play exactly once, visibly).
diff --git a/crates/benilla-app/src/creature_anim/driver/tests.rs b/crates/benilla-app/src/creature_anim/driver/tests.rs
index 718c7c78..a626940e 100644
--- a/crates/benilla-app/src/creature_anim/driver/tests.rs
+++ b/crates/benilla-app/src/creature_anim/driver/tests.rs
@@ -246,7 +246,7 @@ fn stationary_cast_hold_stows_an_engaged_casters_weapon() {
 
 /// The committed-move route: the hold loops masked on the torso over the gait, and its stow must
 /// HOLD between plays — the reconcile is edge-triggered like the client's (`0x5fdf80` runs only
-/// inside `PlayAnimation`, wow-re `sheath-policy.md`), so the base track's flags-less Run never
+/// inside `PlayAnimation`), so the base track's flags-less Run never
 /// re-draws mid-hold on the frames where nothing plays. This was the caster staff bug's shape:
 /// the per-frame base-track re-assert yanked the weapon back out one frame after the retake.
 #[test]
@@ -380,7 +380,7 @@ fn spawn_fidgeter(app: &mut App) -> (Entity, Vec<AnimationNodeIndex>) {
     (unit, nodes)
 }
 
-/// The emergent idle fidget (decision 0123 — wow-re `loop-replay-fidget.md` §5b): a RELAXED base
+/// The emergent idle fidget (decision 0123): a RELAXED base
 /// arm rolls its variation (the client's `variationIdx = −1`), an engaged one is forced to the
 /// deterministic head, and the idle re-face turn-shuffle ([`crate::net::FacingStep`]) drives the
 /// Shuffle↔Stand churn whose every return to Stand re-rolls.
@@ -644,8 +644,8 @@ fn spell_flinch_picks_the_wound_by_engagement() {
     assert_eq!(node(idle), Some(2), "unengaged: StandWound(8)");
 }
 
-/// The wound trigger's fourth entry gate (`0x60eaac`–`0x60eac8`, wow-re
-/// `charproc-rate-override-wound-gate.md`; decision 2063): a CharProc-11 rate-override node on
+/// The wound trigger's fourth entry gate (`0x60eaac`–`0x60eac8`; decision 2063): a CharProc-11
+/// rate-override node on
 /// the unit — what a freeze aura (Ice Block, Freezing Trap, petrify, web wrap) leaves attached —
 /// refuses every flinch for its life. The gate is the node's *presence*: kit 3071's rate of 1.0
 /// (no freeze at all) closes it exactly like the family's 0.0. A unit without the node flinches.
@@ -801,7 +801,7 @@ fn whiff_slowdown_spares_a_non_swing_oneshot() {
 }
 
 /// A same-frame swing/kit-anim collision runs the client's COMBAT FAST-PATH (decision 0406,
-/// wow-re `combat-anim-fastpath.md`): the requests replay in [`PlaySeq`] wire order, the FIRST
+/// `0x5fe43c`–`0x5fe48b`): the requests replay in [`PlaySeq`] wire order, the FIRST
 /// arms, and the second — combat over combat — does NOT overwrite it: the armed clip doubles
 /// to 2× and the second parks in the deferred cache. Both wire orders keep the first arrival on
 /// the body. The director's ref ground truth this pins: the Eviscerate spin survives the
@@ -1058,8 +1058,8 @@ fn a_movement_flag_change_cuts_a_full_body_oneshot_immediately() {
 
 /// A stationary caster mouselook-turning: the chase-step TURN flag flickers at mouse-event
 /// cadence (set on delta frames, clear on quiet ones — `drive_body_heading`'s fold), but the
-/// client's cast pin tests `[9e8] & 0x20000f` — translation + swim, NEVER the turn bits (wow-re
-/// `spell-visual-apply.md` §2.1, `move_flags::CAST_PIN_MOVE`) — so the full-body hold stays
+/// client's cast pin tests `[9e8] & 0x20000f` — translation + swim, NEVER the turn bits
+/// (`0x5fde80`, `move_flags::CAST_PIN_MOVE`) — so the full-body hold stays
 /// pinned through the flap. Routing this through the one-shot mask (`0x20003f`) instead churned
 /// the gait hold↔Shuffle on every mouse-delta frame — the frostbolt right-drag jitter
 /// (decision 0491).
@@ -1415,7 +1415,7 @@ fn the_creep_vis_flag_prowls_the_body() {
     assert_eq!(gait(&app), Some(5), "broken stealth runs again");
 }
 
-/// The looping-variation ADVANCE (decision 0516 — wow-re `loop-replay-fidget.md` §7/§7d, the
+/// The looping-variation ADVANCE (decision 0516 — the
 /// watchdog `0x719370`): a relaxed looping base arm installs a replay window (here `(1,1)` → one
 /// pass exactly); each completed window re-arms the id through the weighted, MEMORYLESS variation
 /// walk. Over a dozen windows both authored Stand variations must take the main slot — the
@@ -1574,9 +1574,9 @@ fn a_jump_out_of_a_micro_detachment_still_enters_the_jump_bracket() {
 }
 
 /// The control on the launch rule: a step-off fall must stay a step-off fall for its whole arc.
-/// The gait freeze is the §5-verified behaviour (decision 0868) and the new edge must not reach
-/// into it — only a rise *past* the threshold is a launch, and a fall only ever accelerates
-/// downward.
+/// The gait freeze (`0x5fd8e8`) is the reference's behaviour (decision 0868) and the new edge
+/// must not reach into it — only a rise *past* the threshold is a launch, and a fall only ever
+/// accelerates downward.
 #[test]
 fn a_deepening_step_off_fall_never_becomes_a_jump() {
     let mut app = app();
@@ -1691,7 +1691,7 @@ fn landing_mid_cast_plays_the_land_pick() {
 
 /// The FALLINGFAR latch mid-one-shot is an edge (`Jump → Fall`): the client plays Fall(40)
 /// ONCE, on the substep it latches (`0x61a820` — the 0864-era per-tick re-assert was
-/// §5-refuted, decision 0868), replacing the clip. A fresh cast armed AFTER the latch then
+/// refuted, decision 0868), replacing the clip. A fresh cast armed AFTER the latch then
 /// holds bone 0 like any other airborne one-shot, until the landing pick cuts it.
 #[test]
 fn a_cast_over_the_fall_loop_holds_until_landing() {
@@ -2061,8 +2061,8 @@ fn the_step_off_arc_freezes_the_gait_against_live_pins() {
     app.update(); // settle: Stand
     let gait = |app: &App| app.world().entity(unit).get::<AnimDriver>().unwrap().gait;
     assert_eq!(gait(&app), Some(0));
-    // Step off a ledge (downward launch: no jump arc, no Special; vz ≠ 0 — the §5-verified
-    // freeze gate `FALLING && (FALLINGFAR || vz ≠ 0)`, decision 0868) …
+    // Step off a ledge (downward launch: no jump arc, no Special; vz ≠ 0 — the freeze gate
+    // `0x5fd8e8`, `FALLING && (FALLINGFAR || vz ≠ 0)`, decision 0868) …
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FALLING,
         vertical_speed: -3.0,
@@ -2149,7 +2149,7 @@ fn a_midair_deferred_park_survives_the_level_and_dies_at_the_landing_play() {
 }
 
 /// The deferred cache's consuming read sits DOWNSTREAM of the airborne-freeze (`0x5fd392`
-/// inside the `0x5fd360` recompute arm; §5-verified, decision 0868): a park made mid-arc is
+/// inside the `0x5fd360` recompute arm; decision 0868): a park made mid-arc is
 /// never consumed mid-air, even with the body free — it waits, and the landing edge's play
 /// clears it.
 #[test]
@@ -2194,8 +2194,8 @@ fn a_midair_park_is_not_consumed_before_landing() {
     );
 }
 
-/// **The ranged→melee handoff at every landed swing** (`0x625829`, wow-re `sheath-policy.md` §1's
-/// `0x6255b0` row) — the director's report: a bow drawn by a shot that never fired, then a melee
+/// **The ranged→melee handoff at every landed swing** (`0x625829` in
+/// `0x6255b0`) — the director's report: a bow drawn by a shot that never fired, then a melee
 /// attack, and the swings keep coming out of the bow. The reconcile provably cannot fix it, and
 /// this pins both halves: the CONTROL (a sword swing while ranged-drawn leaves the stance at 2 —
 /// the client's melee force is gated `CUR != 2`, `0x5fe0f9`/`0x5fe13b`, so the ranged stance is
@@ -2272,7 +2272,7 @@ fn a_landed_swing_snaps_its_attacker_out_of_the_ranged_stance() {
         "the reconcile alone never leaves the ranged stance — this is the bug's shape"
     );
 
-    // The packet arm's snap (what `net::apply::combat::attacker_state` now writes beside the
+    // The packet arm's snap (what `creature_anim::net::attacker_state` now writes beside the
     // swing): the sword comes out on the first landed blow.
     app.world_mut().write_message(SheathRequest {
         entity: unit,
@@ -2637,7 +2637,7 @@ fn a_scaled_creatures_walk_cycles_slower_than_an_unscaled_ones() {
 
 /// The mounted half of the same law: the client's divisor reads the MOUNT model
 /// (`[unit+0xdc] ?: [unit+0xd8]`), whose rendered scale is the rider's `OBJECT_FIELD_SCALE_X`
-/// times the mount's own `CreatureDisplayInfo` column (wow-re `0x613ef0`). Our mount child carries
+/// times the mount's own `CreatureDisplayInfo` column (`0x613ef0`). Our mount child carries
 /// only that column on its transform, so the driver must compose the host's in — a 1.5× sabre
 /// under a 2.0× rider divides by 3.0, not 1.5.
 #[test]
@@ -3075,11 +3075,11 @@ fn the_weapon_visual_hold_alone_never_puts_a_shooter_in_the_drawn_idle() {
 /// The mid-volley half of the same report ("when it's on and I'm running it keeps repeating the
 /// aim animation weirdly") — **re-derived, and inverted, by decision 1544.**
 ///
-/// 0994 read `shooter-stop-law.md` §J4 as: the completion dispatcher `0x5fc3f0` is never reached
-/// for a bow id, so a finished AttackBow recomputes nothing and clamps on its tail. wow-re's §5
-/// refuted that absence proof — the dispatcher has a SECOND, deferred fire site (`0x719370`
+/// 0994 read the reference as: the completion dispatcher `0x5fc3f0` is never reached for a bow
+/// id, so a finished AttackBow recomputes nothing and clamps on its tail. That absence proof is
+/// wrong — the dispatcher has a SECOND, deferred fire site (`0x719370`
 /// enqueues the callback as a plain argument with mode 0; `0x7074b0` invokes it later as
-/// `call [esi+4]`, which an instruction-encoding census cannot see) — and decoded its jump table:
+/// `call [esi+4]`, which an instruction-encoding census cannot see); its jump table:
 /// 46/49/107 land on slot 22, a bare `RecomputeBaseAnim(-1)`, and a finished Load lands on slot
 /// 11/12/15, which arms the Hold **unconditionally**.
 ///
@@ -3732,7 +3732,7 @@ fn a_disarmed_attacker_swings_and_stands_unarmed() {
 
 /// The other rung of the ladder: with **no weapon in the main hand** the disarm falls to the off
 /// hand, and that — not the dual-wield case — is what reaches AttackUnarmedOff(117) (decision
-/// 1863; wow-re `disarm-weapon-gate-law.md` §7's table).
+/// 1863; the swing selector `0x6246a0`).
 #[test]
 fn an_off_hand_only_fighter_is_the_case_that_punches_off_hand() {
     let mut app = app();
@@ -3970,9 +3970,8 @@ fn a_no_wound_creature_takes_no_flinch() {
 }
 
 /// The flag's **second** consumer: `DO_NOT_PLAY_WOUND_ANIM` takes the victim's **parry** with its
-/// flinch (`0x60ec1f` inside the parry pick `0x60ec00`, wow-re
-/// `wound-parry-gate-and-injury-vocal.md` Q1/Q6 — the bit has exactly two callers and this is the
-/// other one). The `$CPP` ladder enters `0x60ec00` only on victimState 3, so DODGE and BLOCK
+/// flinch (`0x60ec1f` inside the parry pick `0x60ec00` — the bit has exactly two callers and this
+/// is the other one). The `$CPP` ladder enters `0x60ec00` only on victimState 3, so DODGE and BLOCK
 /// reach `PlayAnimation` directly and are **not** gated: a flagged creature still dodges, it just
 /// never parries. Both halves are asserted here — the gate without its control is the bug this
 /// whole record is about.
@@ -4074,9 +4073,8 @@ fn the_no_wound_flag_takes_the_parry_but_not_the_dodge() {
 /// `0x602c60` → `0x5fd9e0` → `0x5fd8b0` → `0x5fd100`, and no locomotion id is in the combat set
 /// that takes its no-latch fast path — so a unit that simply starts running consumes the pending
 /// arm. That is what starts Charge's trail: kit 44's anim id is `-1`, `0x60f366 jl` skips the play
-/// block entirely, and the arm waits for the charge's own run (wow-re
-/// `charproc8-trail-draw-state.md` §11.5/§11.6). A one-shot-only edge would leave 38 Charge spells
-/// with no trail at all.
+/// block entirely, and the arm waits for the charge's own run. A one-shot-only edge would leave 38
+/// Charge spells with no trail at all.
 ///
 /// The other half matters as much: there is **no per-frame animation recompute** in the reference
 /// (`0x5fd8b0` has one caller and `0x5fd9e0`'s 38 sites are all event-driven), so a unit standing
@@ -4127,8 +4125,7 @@ fn a_gait_change_raises_the_anim_edge_and_a_steady_frame_does_not() {
     assert!(edge(&app), "and so does a one-shot");
 }
 
-/// **The combat fast path must NOT raise the anim edge** (decision 2076, wow-re
-/// `format7-lighting-term.md`'s second question).
+/// **The combat fast path must NOT raise the anim edge** (decision 2076).
 ///
 /// `0x5fe43c` returns at `0x5fe48b` — *before* `0x5fe48e`, the weapon-trail latch's only read —
 /// when the unit is already playing a combat animation and requests another one. So a pending
@@ -4192,7 +4189,7 @@ fn a_combat_over_combat_fast_path_does_not_raise_the_anim_edge() {
     );
 }
 
-/// The **base-animation lock** (decision 2096, VERIFIED wow-re `base-anim-lock-knockdown.md`) —
+/// The **base-animation lock** (decision 2096) —
 /// the reason a Lashed player visibly falls over, and the correction to 2085's reading.
 ///
 /// A stun's root recomputes the base unconditionally and the selector resolves `Stand(0)`; what
diff --git a/crates/benilla-app/src/creature_anim/driver/wound.rs b/crates/benilla-app/src/creature_anim/driver/wound.rs
index b19b7df4..086ab0fb 100644
--- a/crates/benilla-app/src/creature_anim/driver/wound.rs
+++ b/crates/benilla-app/src/creature_anim/driver/wound.rs
@@ -65,7 +65,8 @@ pub(super) fn wound_upkeep(entity: Entity, drv: &mut AnimDriver, player: &mut An
 /// the slot). So this frame's full-body plays (bone 0: a swing on the base, a gait/mode
 /// change) evict a FULL-BODY wound, and masked-slot plays (the key-bone: a masked swing,
 /// the cast-hold retake) evict a MASKED wound — while the *other* bone's plays leave the
-/// wound decaying (§3's inherited-swing case: a full-body swing under a masked wound).
+/// wound decaying (the kernel `0x714260`'s inherited-swing case: a full-body swing under a
+/// masked wound).
 /// This is exactly why the real client's flinch never smothers the next attack: the swing
 /// reclaims the slot the instant it starts. Mode/gait changes proxy the mode machine's
 /// plays — a change with no play (Land's re-pick) merely evicts one frame before the play
@@ -99,12 +100,12 @@ pub(super) fn wound_evict(
     }
 }
 
-/// The victim wound flinch (decision 0111 — the §5 verdict, rebuilt from bytes after
+/// The victim wound flinch (decision 0111 — rebuilt from bytes after
 /// the first routing was director-falsified): a landed hit lays the wound clip into this
 /// unit's **secondary slot** (`0x60ea70` → op4 `linkFlag=0`) — a decaying 0.75-amplitude
 /// blend overlay over whatever plays. It never touches the base track or the one-shot
 /// slot: the victim's own in-flight swing keeps running underneath (there is NO mid-swing
-/// gate — both §5 trigger agents refuted that hypothesis), and the upkeep above blends it
+/// gate), and the upkeep above blends it
 /// out and self-releases — until a same-bone re-arm evicts it (the block above; a wound
 /// triggered here is this frame's *last* write, matching the client's packet order).
 /// The trigger's own entry gates live in the caller ([`super::drive_animations`]): the victim's
diff --git a/crates/benilla-app/src/creature_anim/emote_anim.rs b/crates/benilla-app/src/creature_anim/emote_anim.rs
index 99686147..6824f2fc 100644
--- a/crates/benilla-app/src/creature_anim/emote_anim.rs
+++ b/crates/benilla-app/src/creature_anim/emote_anim.rs
@@ -3,7 +3,7 @@
 //! catalog ([`EmoteSounds`], promoted from `crate::sound`, decision 0070 slice 4) and hand off —
 //! after the **receive-side posture gate** ([`receive_eligible`]).
 //!
-//! **Verified against vmangos** (`/Users/sam/wre/vmangos-src/src/game/Handlers/ChatHandler.cpp`
+//! **Verified against vmangos** (vmangos `src/game/Handlers/ChatHandler.cpp`
 //! `HandleTextEmoteOpcode` + `src/game/Unit.cpp` `Unit::HandleEmote`/`HandleEmoteCommand`,
 //! 2026-07-03): a one-shot text emote (`/wave`, `Emotes.dbc EmoteType == 0`) sends **both**
 //! `SMSG_TEXT_EMOTE` (the chat line + voice — `EmoteKind::Text`) and `SMSG_EMOTE`
@@ -17,10 +17,10 @@
 //! `SMSG_EMOTE` at all — so they never reach this consumer; they're the state-emote idle in the
 //! gait layer instead ([`super::select::is_bare_stand`]).
 //!
-//! **The receive-side gate is `EmoteFlags`-BLIND** (wow-re `object-layer/scratch/emote-posture-
-//! gate.md`, commit `f9584b45`, §2): the real client's `SMSG_EMOTE` handler (`0x5e66b0`) never
-//! reads the `Emotes.dbc` record at all — it suppresses only on the performer's own state, **stand-
-//! state == 3 (SLEEP)** or the **swim move-flag**, and nothing else (no sit check, no flags check).
+//! **The receive-side gate is `EmoteFlags`-BLIND**: the real client's `SMSG_EMOTE` handler
+//! (`0x5e66b0`) never reads the `Emotes.dbc` record at all — it suppresses only on the performer's
+//! own state, **stand-state == 3 (SLEEP)** or the **swim move-flag**, and nothing else (no sit
+//! check, no flags check).
 //! This is why a *seated* `/clap` still plays for observers though a seated `/bow` never even sent
 //! the packet (the send-side gate in `crate::ui_chat` stopped it there): the two gates are different
 //! and independent. [`receive_eligible`] mirrors exactly this predicate — do not add an EmoteFlags
@@ -95,12 +95,13 @@ pub(super) fn receive_eligible(stand_state: u8, swimming: bool) -> bool {
 }
 
 /// The **shared player's** half of the gate — the client's `0x5fcd20`, the single function both
-/// emote producers tail into (wow-re `chat-talk-gesture.md` §4.2/§8, gates 10 and 12). Beyond the
-/// posture pair it refuses to play while the unit is **channeling** or **in combat**.
+/// emote producers tail into. Beyond the posture pair it refuses to play while the unit is
+/// **channeling** (`0x5fcd83`) or **in combat** (`0x5fcd9d`).
 ///
 /// Two of `0x5fcd20`'s own tests are not repeated here because benilla already enforces them
-/// downstream or cannot see them: the *already-armed* test (gate 9) is the anim driver's same-id
-/// dedup, and `[+0xd58] & 0x400` (gate 11) is an internal anim-state bit with no benilla equivalent.
+/// downstream or cannot see them: the *already-armed* test (`0x5fcd5d`) is the anim driver's
+/// same-id dedup, and `[+0xd58] & 0x400` (`0x5fcd8e`) is an internal anim-state bit with no
+/// benilla equivalent.
 fn player_eligible(channeling: bool, in_combat: bool) -> bool {
     !channeling && !in_combat
 }
@@ -176,7 +177,7 @@ mod tests {
     }
 
     /// The shared player refuses while channeling or in combat — the two `0x5fcd20` tests benilla
-    /// was missing on BOTH producers, not just the new one (wow-re `chat-talk-gesture.md` §9 claim 2).
+    /// was missing on BOTH producers, not just the new one.
     #[test]
     fn channeling_or_combat_suppresses_the_play() {
         assert!(
diff --git a/crates/benilla-app/src/creature_anim/env_damage.rs b/crates/benilla-app/src/creature_anim/env_damage.rs
index 0d603427..eab176a1 100644
--- a/crates/benilla-app/src/creature_anim/env_damage.rs
+++ b/crates/benilla-app/src/creature_anim/env_damage.rs
@@ -1,6 +1,5 @@
-//! Environmental-damage feedback — the fall-landing dust puff and pain grunt (decision 0412,
-//! byte-verified wow-re `object-layer/scratch/smsg-environmentaldamage.md`). Two independent
-//! sources fire it, matching the reference's own double-fire:
+//! Environmental-damage feedback — the fall-landing dust puff and pain grunt (decision 0412).
+//! Two independent sources fire it, matching the reference's own double-fire:
 //!
 //! 1. **The wire arm** (`net/apply`): `SMSG_ENVIRONMENTALDAMAGELOG` → [`EnvDamageTable`] maps the
 //!    damage type (0 exhausted · 1 drowning · 2 fall · 3 lava · 4 slime · 5 fire) to a
diff --git a/crates/benilla-app/src/creature_anim/events.rs b/crates/benilla-app/src/creature_anim/events.rs
index aa907f2d..ecb6256d 100644
--- a/crates/benilla-app/src/creature_anim/events.rs
+++ b/crates/benilla-app/src/creature_anim/events.rs
@@ -34,7 +34,7 @@ pub(crate) struct AnimSoundEvent {
     /// event.position)`, resolved here at the fire and carried by value exactly as the M2 event
     /// kernel `0x719370` snapshots it into the deferred callback record that every dispatcher
     /// (`0x5ffbd0` units, `0x5f3e20` GameObjects, `0x6951e0` placed models) then reads (decision
-    /// 1904; wow-re `spell/scratch/camera-shake-producers.md` §5).
+    /// 1904).
     ///
     /// It is emphatically not the object's origin: corpus-wide 149 of 244 `$DSL` records sit off
     /// it, out to **67.6 yd** on `Maraudon_Waterfall01.m2`, and the six `$CSD` records every
@@ -69,8 +69,7 @@ impl EventFrame<'_> {
 }
 
 /// A footfall is **two independent channels**, and a tag belongs to exactly one of them — the
-/// client's event dispatcher `0x5ffbd0` routes them to two different handlers (wow-re
-/// `footprint-decals.md` §1, §5 4-agent round, byte-arbitrated):
+/// client's event dispatcher `0x5ffbd0` routes them to two different handlers:
 ///
 /// - **`$FSD` → `0x623390`: the footstep SOUND**, and nothing else — it never reaches the decal
 ///   path ([`is_footstep_sound`]).
@@ -95,8 +94,7 @@ pub(crate) fn is_footstep_sound(ident: &[u8; 4]) -> bool {
 /// origin (decision 1856).
 ///
 /// **Measured from the CAMERA EYE, not the local player.** `FUN_004818f0()` returns
-/// `[[0xb4b2bc]+0x65b8]` — the *active camera* — and its `+0x8/+0xc/+0x10` is the eye; wow-re
-/// corrected that mislabel in `dist2-gate.md` (2026-08-22, with the camera-dtor proof).
+/// `[[0xb4b2bc]+0x65b8]` — the *active camera* — and its `+0x8/+0xc/+0x10` is the eye.
 ///
 /// **Unconditional** — the local player's own feet are gated like anyone else's. The reference's
 /// `GUID == local player` compare (`0x5fc042`–`0x5fc06b`) is the decal call's fifth argument, the
@@ -117,8 +115,7 @@ const FOOTFALL_RADIUS_SQ: f32 = 2500.0;
 /// bit product is exact, and the sum of three ≤50-bit values is exact — which also makes the
 /// reference's `(dz² + dy²) + dx²` summation order unobservable here, so this does not pretend to
 /// map its axis names onto ours. Round once on the way out and the f32 handed to the compare is
-/// bit-identical (wow-re `dist2-gate.md`, the shared kernel + its `fstp`-round-trip exception
-/// list; `footfall-camera-distance-gate.md` for this call site).
+/// bit-identical.
 ///
 /// The compare is **strict** — bail iff `> FOOTFALL_RADIUS_SQ`, so exactly 50 yd passes, and so
 /// does a NaN: `test ah,0x41; je` reads ZF and takes the unordered result as "keep", which Rust's
@@ -171,7 +168,7 @@ pub(crate) type TrackMemory = bevy::ecs::entity::EntityHashMap<TrackSeek>;
 /// [`super::driver::drive_animations`] so the clip/seek state is this frame's. Per unit we
 /// remember the playing node and its seek ([`TrackSeek`]); a loop wrap fires the tail
 /// `(prev, duration]` then the head `[0, cur]` — a `t = 0` key really does re-fire on every wrap,
-/// in the reference too (wow-re `m2-event-track-walker.md` §2), which is why a held turn-in-place
+/// in the reference too (the walker `0x719370`), which is why a held turn-in-place
 /// lays a footprint pair twice a second there as well.
 ///
 /// Arming is [`advance_track`]'s: an arm frame fires nothing, the frame after it opens the clip's
@@ -535,8 +532,8 @@ mod tests {
 
     /// The turn-in-place cadence, which this change deliberately leaves alone: HumanMale's
     /// ShuffleLeft (anim 11) is a **0.500 s loop** whose only keys are `$SL0` and `$SR0`, both at
-    /// `t = 0.000`, and the reference re-fires a `t = 0` key on **every wrap** (wow-re
-    /// `m2-event-track-walker.md` §2, byte-traced) — so a held turn lays a print pair twice a
+    /// `t = 0.000`, and the reference re-fires a `t = 0` key on **every wrap** (the walker
+    /// `0x719370`) — so a held turn lays a print pair twice a
     /// second in the real client too.
     #[test]
     fn a_loop_wrap_refires_the_head_keys() {
diff --git a/crates/benilla-app/src/creature_anim/gesture.rs b/crates/benilla-app/src/creature_anim/gesture.rs
index eb642f7e..a417f4fa 100644
--- a/crates/benilla-app/src/creature_anim/gesture.rs
+++ b/crates/benilla-app/src/creature_anim/gesture.rs
@@ -11,8 +11,6 @@
 //!
 //! The same dispatcher has a second caller — the **NPC-interact** path, always with code 0 (talk) —
 //! which is why [`crate::target::click`] pushes through here too instead of writing a raw AnimID.
-//!
-//! Byte-exact spec: wow-re `object-layer/scratch/chat-talk-gesture.md`.
 
 use bevy::prelude::*;
 
@@ -165,7 +163,7 @@ mod tests {
     use benilla_protocol::messages as m;
 
     /// A stand-in `LAUGH_WORDn` list. The words are **invented on purpose**: the shipped ones are
-    /// the install's own `GlobalStrings.lua` content, which never enters this repo (the contract), and
+    /// the install's own `GlobalStrings.lua` content, which never enters this repo (docs/METHOD.md), and
     /// the mechanism under test is the enumeration, not the vocabulary. A test that passes with
     /// nonsense words is a test that proves the list is not baked into the code.
     fn words(n: u32) -> Option<String> {
diff --git a/crates/benilla-app/src/creature_anim/impact.rs b/crates/benilla-app/src/creature_anim/impact.rs
index 83ddeb85..a8612080 100644
--- a/crates/benilla-app/src/creature_anim/impact.rs
+++ b/crates/benilla-app/src/creature_anim/impact.rs
@@ -1,6 +1,5 @@
-//! The melee **impact-frame deferral** — the client's swing-hit timing, §5-verified end to end
-//! (wow-re `object-layer/scratch/melee-impact-timing.md`, f86e665a; the victim-consequence table
-//! `smsg-attackerstate-consequences.md`, ffd0b016): at SMSG receive, a locally resolved attacker
+//! The melee **impact-frame deferral** — the client's swing-hit timing: at SMSG receive, a locally
+//! resolved attacker
 //! caches the swing record (`attacker+0xd70`), plays the swing clip (rate 1.0, `0x5fe2f0`), and
 //! does **not** dispatch the victim. When the clip's playhead crosses an authored **`$AH0–3` or
 //! `$CAH`** event keyframe (rel ~300–670 ms in every shipped attack clip; the `$AH` digit picks a
@@ -41,8 +40,7 @@ use super::SwingMessage;
 use crate::net::ObjectStore;
 
 /// **The LOOTABLE front gate on the victim dispatcher** (`0x624552 test byte
-/// [[victim+0x110]+0x224],1` / `0x62455a jne 0x624689` — `UNIT_DYNAMIC_FLAGS` bit `0x1`; wow-re
-/// `melee-impact-timing.md`, byte-census landed 2026-09-07).
+/// [[victim+0x110]+0x224],1` / `0x62455a jne 0x624689` — `UNIT_DYNAMIC_FLAGS` bit `0x1`).
 ///
 /// `0x624530` bails **before every consequence it owns** — blood, wound flinch, impact sounds and
 /// the floating damage number alike (`0x624689` is the bare epilogue, and the number's call at
@@ -75,13 +73,13 @@ pub(crate) struct SwingImpact {
     pub(crate) text_only: bool,
     /// The `$AH0`–`$AH3` digit when a creature natural-weapon tag fired this dispatch — it
     /// selects the attacker's `CreatureSoundData.CustomAttack` sound column and latches
-    /// `SWINGNOHITSOUND`, replacing the generic weapon-impact sound (`0x6247d0` §f, decision
+    /// `SWINGNOHITSOUND`, replacing the generic weapon-impact sound (`0x6247d0`, decision
     /// 0525). `None` for `$CAH` (character attack-hit), the receive-time unresolved-attacker
     /// fallback, and flushes.
     pub(crate) natural: Option<u8>,
     /// **The world point of the tag that fired this dispatch** — the reference's `edi =
     /// [ebx+0x10]`, carried from `0x624862` through both weapon-sound legs and pushed at
-    /// `0x6248ef`/`0x624950` (wow-re `anim-event-position-law.md` §3). `None` for a flush and for
+    /// `0x6248ef`/`0x624950`. `None` for a flush and for
     /// the receive-time fallback, where no tag fired at all and the reference has only the unit.
     pub(crate) pos: Option<Vec3>,
 }
diff --git a/crates/benilla-app/src/creature_anim/lod.rs b/crates/benilla-app/src/creature_anim/lod.rs
index 856fe94f..56d4cf2d 100644
--- a/crates/benilla-app/src/creature_anim/lod.rs
+++ b/crates/benilla-app/src/creature_anim/lod.rs
@@ -5,7 +5,7 @@
 //! sampling off-view).
 //!
 //! 0448 shipped this as a modernization against a reference that "has NO view cull on unit
-//! skeletons" — a verdict wow-re REFUTED on 2026-08-13 (`outdoor-object-pass-election.md`: every
+//! skeletons" — a verdict that is wrong (`0x683dd0`: every
 //! scene object, units included, is frustum/horizon/room-elected each frame, and a pass-2 unit
 //! is neither drawn, nor animated, nor event-ticked — except creatures flagged `MORE_AUDIBLE`,
 //! re-linked for tick only). So this gate turned out to be the *faithful* direction, not a
@@ -393,9 +393,9 @@ mod tests {
 
     /// The gate laws in one flow (0448, events re-lawed by 1482): an off-frustum rig parks
     /// (joints repointed at the park entity, bones frozen) while its seek clock keeps advancing —
-    /// and its event keyframes FALL SILENT, because the reference's pass-2 walk never ticks an
-    /// unflagged model (the 0448 "off-screen swings must not go silent" law rested on the verdict
-    /// wow-re refuted on 2026-08-13; the flagged exception is the next test's). A woken rig and a
+    /// and its event keyframes FALL SILENT, because the reference's pass-2 walk (`0x683dd0`) never
+    /// ticks an unflagged model (the 0448 "off-screen swings must not go silent" law rested on the
+    /// wrong "no view cull" verdict; the flagged exception is the next test's). A woken rig and a
     /// never-parked twin sample the SAME pose — the absolute-clock snap, not resume-from-freeze.
     #[test]
     fn parked_rig_keeps_its_clock_falls_silent_and_wakes_to_the_absolute_pose() {
diff --git a/crates/benilla-app/src/creature_anim/net.rs b/crates/benilla-app/src/creature_anim/net.rs
new file mode 100644
index 00000000..4734d960
--- /dev/null
+++ b/crates/benilla-app/src/creature_anim/net.rs
@@ -0,0 +1,469 @@
+//! The animation layer's packet handlers (in the net handler table since 2322, moved out of the
+//! drain's combat, anim and mount arm files) — the server packets whose whole content is *a thing
+//! to play on a streamed unit*: the melee engagement brackets, the aggro/alert flare, the swing
+//! refusals, the two emote relays, the spell-visual kit push (decision 0280), a rider's flourish.
+//! Each resolves the guid through the index and writes one message; the animation law itself
+//! lives in [`super`]. Two kinds here have a second handler: the completed-swing record
+//! ([`attacker_state`], with its client-side full-block synthesis) and the environmental-damage
+//! kit ([`environmental_damage_log`]) also feed [`crate::combat_log`]'s chat line, which is
+//! registered ahead of these and so runs first, as the drain's match ran them.
+
+use benilla_protocol::messages::{AttackSwingError, AttackerState, EnvironmentalDamageLog};
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::{
+    Engaged, EnvDamageTable, KitPush, MountFlourish, PlaySeq, RangedHold, SheathRequest,
+    SwingFlush, SwingImpact, SwingMessage,
+};
+use crate::net::{AiReactionMessage, EmoteKind, EmoteMessage, GuidIndex, NetHandlerApp, SelfGuid};
+use crate::swing_refusal::SwingRefusalEdge;
+use crate::ui_action::{UiError, UiErrorKeys};
+use crate::ui_unit::CombatTextEvent;
+
+/// Register the layer's handlers — called from [`super::CreatureAnimPlugin`].
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::AttackStart, on_attack_start)
+        .net_handler(K::AttackStop, on_attack_stop)
+        .net_handler(K::AiReaction, on_ai_reaction)
+        .net_handler(K::AttackSwingError, on_swing_refusal)
+        .net_handler(K::CancelCombat, on_swing_refusal)
+        .net_handler(K::FeignDeathResisted, on_feign_death_resisted)
+        .net_handler(K::MountSpecial, on_mount_special)
+        .net_handler(K::TextEmote, on_text_emote)
+        .net_handler(K::Emote, on_emote)
+        .net_handler(K::PlaySpellVisual, on_play_spell_visual)
+        .net_handler(K::AttackerState, on_attacker_state)
+        .net_handler(K::EnvironmentalDamageLog, on_environmental_damage_log);
+}
+
+fn on_attack_start(In(ev): In<SessionEvent>, mut commands: Commands, index: Res<GuidIndex>) {
+    if let SessionEvent::AttackStart { attacker, victim } = ev {
+        attack_start(attacker, victim, &mut commands, &index);
+    }
+}
+
+fn on_attack_stop(
+    In(ev): In<SessionEvent>,
+    mut commands: Commands,
+    index: Res<GuidIndex>,
+    mut flushes: MessageWriter<SwingFlush>,
+) {
+    if let SessionEvent::AttackStop { attacker, victim } = ev {
+        attack_stop(attacker, victim, &mut commands, &index, &mut flushes);
+    }
+}
+
+fn on_ai_reaction(
+    In(ev): In<SessionEvent>,
+    index: Res<GuidIndex>,
+    mut reactions: MessageWriter<AiReactionMessage>,
+) {
+    if let SessionEvent::AiReaction { unit, reaction } = ev {
+        ai_reaction(unit, reaction, &index, &mut reactions);
+    }
+}
+
+fn on_swing_refusal(In(ev): In<SessionEvent>, mut edges: MessageWriter<SwingRefusalEdge>) {
+    match ev {
+        SessionEvent::AttackSwingError(e) => attack_swing_error(e, &mut edges),
+        SessionEvent::CancelCombat => cancel_combat(&mut edges),
+        _ => {}
+    }
+}
+
+fn on_feign_death_resisted(In(ev): In<SessionEvent>, mut errors: ResMut<UiErrorKeys>) {
+    if let SessionEvent::FeignDeathResisted = ev {
+        feign_death_resisted(&mut errors);
+    }
+}
+
+fn on_mount_special(
+    In(ev): In<SessionEvent>,
+    self_guid: Res<SelfGuid>,
+    index: Res<GuidIndex>,
+    mut out: MessageWriter<MountFlourish>,
+) {
+    if let SessionEvent::MountSpecial { guid } = ev {
+        mount_special(guid, &self_guid, &index, &mut out);
+    }
+}
+
+fn on_text_emote(
+    In(ev): In<SessionEvent>,
+    index: Res<GuidIndex>,
+    mut out: MessageWriter<EmoteMessage>,
+    mut chat_log: ResMut<crate::ui_chat::ChatLog>,
+) {
+    if let SessionEvent::TextEmote {
+        guid,
+        text_emote,
+        target_name,
+    } = ev
+    {
+        self::text_emote(
+            guid,
+            text_emote,
+            target_name,
+            &index,
+            &mut out,
+            &mut chat_log,
+        );
+    }
+}
+
+fn on_emote(In(ev): In<SessionEvent>, index: Res<GuidIndex>, mut out: MessageWriter<EmoteMessage>) {
+    if let SessionEvent::Emote { guid, emote_id } = ev {
+        emote(guid, emote_id, &index, &mut out);
+    }
+}
+
+fn on_attacker_state(
+    In(ev): In<SessionEvent>,
+    index: Res<GuidIndex>,
+    self_guid: Res<SelfGuid>,
+    mut swings: MessageWriter<SwingMessage>,
+    mut impacts: MessageWriter<SwingImpact>,
+    mut center: MessageWriter<CombatTextEvent>,
+    mut sheaths: MessageWriter<SheathRequest>,
+    mut edges: MessageWriter<SwingRefusalEdge>,
+    stores: Query<&mut crate::net::ObjectStore>,
+    mut play_seq: ResMut<PlaySeq>,
+) {
+    if let SessionEvent::AttackerState(s) = ev {
+        attacker_state(
+            s,
+            &index,
+            &self_guid,
+            &mut swings,
+            &mut impacts,
+            &mut center,
+            &mut sheaths,
+            &mut edges,
+            &stores,
+            play_seq.next(),
+        );
+    }
+}
+
+fn on_environmental_damage_log(
+    In(ev): In<SessionEvent>,
+    index: Res<GuidIndex>,
+    table: Option<Res<EnvDamageTable>>,
+    mut play_seq: ResMut<PlaySeq>,
+    mut out: MessageWriter<KitPush>,
+) {
+    if let SessionEvent::EnvironmentalDamageLog(e) = ev {
+        environmental_damage_log(e, &index, table.as_deref(), &mut play_seq, &mut out);
+    }
+}
+
+fn on_play_spell_visual(
+    In(ev): In<SessionEvent>,
+    index: Res<GuidIndex>,
+    mut play_seq: ResMut<PlaySeq>,
+    mut out: MessageWriter<KitPush>,
+) {
+    if let SessionEvent::PlaySpellVisual { unit, kit_id } = ev {
+        play_spell_visual(unit, kit_id, &index, &mut play_seq, &mut out);
+    }
+}
+
+/// A unit began melee auto-attack (`SMSG_ATTACKSTART`, including our own echo).
+fn attack_start(attacker: u64, victim: u64, commands: &mut Commands, index: &GuidIndex) {
+    // Engagement brackets (decision 0073): the standing Ready idle rides this window —
+    // the client's gate is the auto-attack-target GUID being set, mirrored here as a
+    // marker component on the attacker (including our own echo).
+    debug!("net: attack start {attacker:#x} → {victim:#x}");
+    if let Some(&e) = index.0.get(&attacker) {
+        // Melee-start drops the `0x400` weapon-visual hold unconditionally (the client's
+        // `0x60fc50` sibling clear) — a shooter that closes to melee leaves the drawn idle.
+        // The LOCAL player's melee paths additionally run the full cancel funnel at send.
+        commands
+            .entity(e)
+            .insert(Engaged(victim))
+            .remove::<RangedHold>();
+    }
+}
+
+/// A unit stopped melee auto-attack (`SMSG_ATTACKSTOP`).
+fn attack_stop(
+    attacker: u64,
+    victim: u64,
+    commands: &mut Commands,
+    index: &GuidIndex,
+    flushes: &mut MessageWriter<SwingFlush>,
+) {
+    debug!("net: attack stop {attacker:#x} → {victim:#x}");
+    if let Some(&e) = index.0.get(&attacker) {
+        commands.entity(e).remove::<Engaged>();
+        // The client's `0x624e40` (death/stun arrive as this packet too): a pending
+        // swing record flushes text-only and clears.
+        flushes.write(SwingFlush(e));
+    }
+}
+
+/// The server refused our melee swing (`SMSG_ATTACKSWING_NOTINRANGE`/`_BADFACING`/`_DEADTARGET`/
+/// `_CANT_ATTACK`) — forwarded verbatim to [`crate::swing_refusal`], which owns the latch, the 4 s
+/// repeat, and arm 4's silent StopAttack. Nothing is decided here: the arms differ only in what
+/// that module does with them, and it holds the write set for all three.
+fn attack_swing_error(error: AttackSwingError, edges: &mut MessageWriter<SwingRefusalEdge>) {
+    edges.write(SwingRefusalEdge::Refused(error));
+}
+
+/// `SMSG_CANCEL_COMBAT` — the server forced our attack to stop. The swing family's fourth arm,
+/// and the same act as `0x148`/`0x149`: the reference's handler `0x5e7dd0` is arm 4's body
+/// verbatim.
+fn cancel_combat(edges: &mut MessageWriter<SwingRefusalEdge>) {
+    edges.write(SwingRefusalEdge::CombatCancelled);
+}
+
+/// `SMSG_FEIGN_DEATH_RESISTED` — the target shrugged off our Feign Death.
+///
+/// One red line and nothing else: the reference's handler `0x6e9800` is `push 0x1a5; call
+/// 0x496720`, a bare `DisplayError(421)` with no latch, no cooldown and no state — the opposite of
+/// its sibling above, and the reason the two do not share a path. Catalog row 421 is
+/// `ERR_FEIGN_DEATH_RESISTED`, whose 1.12 string is the single word "Resisted".
+///
+/// It lives beside the swing arms because vmangos sends it in the same breath as
+/// `SMSG_CANCEL_COMBAT` (`Objects/Unit.cpp:9445-9451`: a resisted feign death cancels the attack
+/// and says so), and finding one without the other is how this family stayed half-built.
+fn feign_death_resisted(errors: &mut UiErrorKeys) {
+    debug!("net: feign death resisted");
+    errors.0.push(UiError::key("ERR_FEIGN_DEATH_RESISTED"));
+}
+
+/// A creature flared aggro or a stealth pre-aggro alert (`SMSG_AI_REACTION`).
+fn ai_reaction(
+    unit: u64,
+    reaction: u32,
+    index: &GuidIndex,
+    reactions: &mut MessageWriter<AiReactionMessage>,
+) {
+    // Aggro (2 HOSTILE) / stealth alert (0 ALERT) flare — pure audio, byte-verified
+    // (`0x6056e0` is an exact two-way branch; any other value no-ops, and neither leg
+    // touches animation/nameplate/UI — decision 0280). Vocals: `sound::creature`.
+    debug!("net: ai reaction {reaction} on {unit:#x}");
+    if matches!(reaction, 0 | 2) {
+        if let Some(&e) = index.0.get(&unit) {
+            reactions.write(AiReactionMessage {
+                unit: e,
+                hostile: reaction == 2,
+            });
+        }
+    }
+}
+
+/// One completed melee swing (`SMSG_ATTACKERSTATEUPDATE`, decision 0073): the attacker's swing
+/// anim starts NOW; the victim feedback (blood/flinch/text/impact sounds) defers to the swing
+/// clip's attack-hit keyframe (`creature_anim::impact`, the client's `0x6247d0` router) — EXCEPT
+/// the center combat text, which the client fires **synchronously at packet parse**
+/// (`0x6255b0 → 0x629d30 → 0x703f50`, one call stack; decision 0580's fold-back).
+fn attacker_state(
+    mut s: AttackerState,
+    index: &GuidIndex,
+    self_guid: &SelfGuid,
+    swings: &mut MessageWriter<SwingMessage>,
+    impacts: &mut MessageWriter<SwingImpact>,
+    center: &mut MessageWriter<CombatTextEvent>,
+    sheaths: &mut MessageWriter<SheathRequest>,
+    edges: &mut MessageWriter<SwingRefusalEdge>,
+    stores: &Query<&mut crate::net::ObjectStore>,
+    seq: u64,
+) {
+    let victim = index.0.get(&s.victim).copied();
+    // Arm 5's `0x6259b6 call 0x5ea800`, whose first act is the swing-refusal latch clear
+    // (`0x5ecdb0(0)`) — gated exactly as the reference gates it: the attacker IS the active player
+    // (`0x5fa6d0`, a guid compare) and the victim resolves as a streamed unit. Written from here
+    // rather than computed downstream because this is the only place holding both guids, and it
+    // keeps the clear in packet order with the refusals (`crate::swing_refusal`).
+    if self_guid.0 == Some(s.attacker) && victim.is_some() {
+        edges.write(SwingRefusalEdge::Landed);
+    }
+    if benilla_assets::trace::enabled() {
+        benilla_assets::trace::line(
+            "fct",
+            &format!(
+                "recv swing atk={:#x} victim={:#x} dmg={} vstate={} hit={:#x}",
+                s.attacker, s.victim, s.damage, s.victim_state, s.hit_info
+            ),
+        );
+    }
+    // The client-side FULL-BLOCK synthesis (`0x625e20`, decision 0279): a resolvable
+    // victim + zero damage + a nonzero blocked amount rewrites the state to BLOCKS(5)
+    // before any consumer sees the record — the only thing the wire's blocked_amount
+    // ever does (a PARTIAL block stays state 1, indistinguishable from a plain hit).
+    if victim.is_some() && s.damage == 0 && s.blocked != 0 {
+        s.victim_state = 5;
+    }
+    // The center combat text (decision 0578/0580): self victim, at receive, AFTER the full-block
+    // synthesis (so a full block reads BLOCK, not MISS) — the packet's absorb/resist/blocked
+    // sums feed the confirmed helper-B partial trailers.
+    if self_guid.0 == Some(s.victim) {
+        if let Some((message_type, data, extra)) = crate::combat_log::text::melee_center_text(
+            s.hit_info,
+            s.victim_state,
+            s.damage,
+            s.absorb,
+            s.resist,
+            s.blocked,
+        ) {
+            center.write(CombatTextEvent {
+                message_type,
+                data,
+                extra,
+            });
+        }
+    }
+    let swing = SwingMessage {
+        attacker: Entity::PLACEHOLDER, // filled per branch below
+        victim,
+        hit_info: s.hit_info,
+        victim_state: s.victim_state,
+        damage: s.damage,
+        displayed: s.displayed(),
+        seq,
+    };
+    if let Some(&e) = index.0.get(&s.attacker) {
+        // The **observed attacker auto-draws melee** — the ref's SECOND melee draw, independent
+        // of the attack-start one, and the reason a swing is never delivered in the wrong stance:
+        // `0x625829 cmp [attacker+0xd40],1; jne` → `SetSheatheState(1, bInstant=1, bFireEvent=1)`
+        // at `0x62583a`, byte-read here. It sits
+        // immediately after the attacker resolve and **before** any hit-info handling, so even a
+        // swing whose animation is suppressed (`HitInfo & 0x10000`) still draws. Nothing else in
+        // the policy can do this job: the per-animation reconcile's melee force is gated to
+        // `CUR != 2` (`0x5fe0f9`/`0x5fe13b`), so a unit swinging with a bow drawn — a ranged
+        // stance a shot left behind — would otherwise keep swinging with the bow forever. The
+        // setter's own idempotency is the `cmp`: a request equal to the committed state is
+        // refused there, so this is free on every swing after the first.
+        sheaths.write(SheathRequest {
+            entity: e,
+            state: 1,
+            ceremony: false,
+        });
+        swings.write(SwingMessage {
+            attacker: e,
+            ..swing
+        });
+    } else if swing.victim.is_some_and(|v| {
+        // The receive-time arm goes THROUGH the gated dispatcher — `0x625823 je 0x625a3e` takes
+        // the unresolved-attacker leg, which resolves the victim and calls `0x625a6d call
+        // 0x624530`, so the LOOTABLE front gate applies here exactly as it does to the tag path
+        // (`creature_anim::impact::lootable_victim`). It calls no consequence directly.
+        !stores.get(v).is_ok_and(|s| s.0.unit_lootable())
+    }) {
+        // The client's SMSG-arm fallback: an attacker we can't resolve (out of range)
+        // can't animate a swing — its victim feedback fires immediately and in FULL
+        // (`0x625a6d`, the only receive-time victim dispatch). The PLACEHOLDER
+        // attacker resolves nowhere downstream (blood defaults front).
+        impacts.write(SwingImpact {
+            swing,
+            text_only: false,
+            natural: None,
+            // The receive-time arm: no tag fired, so the reference has no event point either —
+            // the consumer falls back to the victim, the only anchor the packet leaves us.
+            pos: None,
+        });
+    }
+}
+
+/// `SMSG_TEXT_EMOTE` — someone performed a `/`-emote (the TextEmote.dbc id; the anim, if any, is
+/// the emote row's).
+///
+/// **Two consequences, and they are independent** (decision 1274): the anim + voice ride the
+/// [`EmoteMessage`] and need the performer *streamed*; the chat sentence is queued for
+/// [`crate::ui_chat`]'s composer and needs only the performer's *name*. An emote from someone
+/// off-screen therefore still prints its line, which is the reference's shape — `0x49dbe0`
+/// resolves a name and never touches the object manager.
+fn text_emote(
+    guid: u64,
+    text_emote: u32,
+    target_name: String,
+    index: &GuidIndex,
+    out: &mut MessageWriter<EmoteMessage>,
+    chat_log: &mut crate::ui_chat::ChatLog,
+) {
+    out.write(EmoteMessage {
+        source: index.0.get(&guid).copied(),
+        kind: EmoteKind::Text(text_emote),
+    });
+    chat_log.push_text_emote(guid, text_emote, target_name);
+}
+
+/// `SMSG_EMOTE` — a bare Emotes.dbc anim id on a unit (the server-driven one-shot: NPC scripts,
+/// the `/`-emote's own anim leg).
+fn emote(guid: u64, emote_id: u32, index: &GuidIndex, out: &mut MessageWriter<EmoteMessage>) {
+    out.write(EmoteMessage {
+        source: index.0.get(&guid).copied(),
+        kind: EmoteKind::Anim(emote_id),
+    });
+}
+
+/// `SMSG_PLAY_SPELL_VISUAL` — the kit-push opcode (decision 0280): a stage-0 play on the unit, the
+/// eat/drink kit cadence and mid-channel swaps. Consumer: `creature_anim::spell_visual`. The
+/// [`PlaySeq`] stamp is taken only when the unit is streamed in, so an unstreamed guid never
+/// advances the call-order counter.
+fn play_spell_visual(
+    unit: u64,
+    kit_id: u32,
+    index: &GuidIndex,
+    play_seq: &mut PlaySeq,
+    out: &mut MessageWriter<KitPush>,
+) {
+    if let Some(&e) = index.0.get(&unit) {
+        out.write(KitPush {
+            entity: e,
+            kit_id,
+            seq: play_seq.next(),
+        });
+    }
+}
+
+/// `SMSG_ENVIRONMENTALDAMAGELOG`'s consequence (reader
+/// `0x624fcc` inside `0x624f30`): the EnvironmentalDamage.dbc 6-slot table picks the damage type's
+/// SpellVisualKit — fall's is the DustCloud_Land puff — played on the victim through the ordinary
+/// discrete kit play (`0x60edf0`), the same leg the kit-push opcode rides. The pain vocal's exact
+/// trigger is open — it folds in as its own edge once pinned.
+fn environmental_damage_log(
+    e: EnvironmentalDamageLog,
+    index: &GuidIndex,
+    table: Option<&EnvDamageTable>,
+    play_seq: &mut PlaySeq,
+    out: &mut MessageWriter<KitPush>,
+) {
+    if let Some(&ent) = index.0.get(&e.victim) {
+        if let Some(kit_id) = table.and_then(|t| t.0.kit_id(e.damage_type)) {
+            debug!(
+                "net: environmental damage on {:#x} (type {}, {} dmg) → kit {kit_id}",
+                e.victim, e.damage_type, e.damage
+            );
+            out.write(KitPush {
+                entity: ent,
+                kit_id,
+                seq: play_seq.next(),
+            });
+        }
+    }
+}
+
+/// `SMSG_MOUNTSPECIAL_ANIM` — a nearby rider's flourish: rear their mount (MountSpecial 94 on the
+/// mount child; the hop happens in `creature_anim::flourish_to_anim`).
+///
+/// Our OWN guid is dropped: we played it locally at send time, and whether the sender gets the
+/// SMSG echoed back is a server-config detail (LIVE-VERIFIED 2026-07-17, double-flourish probe:
+/// vmangos's `SendMovementMessageToSet(.., false)` only cheat-logs on the flag — the
+/// non-broadcaster delivery hardcodes self=true, so our deployment echoes; the optional per-player
+/// broadcaster honors it and would not). Self-suppression on receive is correct under both configs.
+fn mount_special(
+    guid: u64,
+    self_guid: &SelfGuid,
+    index: &GuidIndex,
+    out: &mut MessageWriter<MountFlourish>,
+) {
+    if self_guid.0 != Some(guid) {
+        if let Some(&e) = index.0.get(&guid) {
+            out.write(MountFlourish { unit: e });
+        }
+    }
+}
diff --git a/crates/benilla-app/src/creature_anim/select.rs b/crates/benilla-app/src/creature_anim/select.rs
index cc429e62..a7d3e051 100644
--- a/crates/benilla-app/src/creature_anim/select.rs
+++ b/crates/benilla-app/src/creature_anim/select.rs
@@ -1,6 +1,7 @@
-//! The pure animation-selection logic (RF-0057/0073 tables, movement/Special state, gait/swing/ready
-//! picks, playback-rate math) — kept in its own file as it carries the bulk of the unit-tested selector
-//! logic, separate from the Bevy driver systems in [`super::driver`].
+//! The pure animation-selection logic (the `0x5fd8b0` selector's and decision 0073's tables,
+//! movement/Special state, gait/swing/ready picks, playback-rate math) — kept in its own file as it
+//! carries the bulk of the unit-tested selector logic, separate from the Bevy driver systems in
+//! [`super::driver`].
 
 use benilla_assets::AnimClip;
 use bevy::prelude::*;
@@ -8,11 +9,11 @@ use bevy::prelude::*;
 use crate::net::{RemoteMotion, Spline};
 
 /// Fallback walk speed (yd/s) for a unit whose movement block didn't carry one — vanilla's default
-/// creature walk speed. The run boundary is 2× this (`RecomputeBaseAnim`, RF-0057).
+/// creature walk speed. The run boundary is 2× this (`RecomputeBaseAnim`, the `0x5fd224` compare).
 pub(super) const DEFAULT_WALK_SPEED: f32 = 2.5;
 
 /// Fast-run cutoff (yd/s): at or above it the unit plays the sprint animation (id 143) ahead of Run
-/// (`[0x80c484]` in the real selector, RF-0057).
+/// (`[0x80c484]` in the real selector).
 const FAST_RUN_SPEED: f32 = 11.0;
 
 /// Below this ground speed (yd/s) a streamed mover counts as standing still — guards a near-zero residual.
@@ -25,29 +26,27 @@ pub(super) const DEATH: u16 = 1;
 /// ShuffleLeft (11) / ShuffleRight (12) — the **turn-in-place foot-shuffle**, picked below when
 /// the unit turns without translating. Named because their *lifecycle* is unlike any other gait:
 /// once armed they are held to their own clip window rather than released when the turn ends
-/// (decision 1655, wow-re `object-layer/scratch/turn-shuffle-lifecycle.md`), and the driver has
-/// to be able to say so.
+/// (decision 1655; the clip-end watchdog `0x719370`), and the driver has to be able to say so.
 pub(super) const SHUFFLE_LEFT: u16 = 11;
 /// See [`SHUFFLE_LEFT`].
 pub(super) const SHUFFLE_RIGHT: u16 = 12;
 
 /// StealthWalk (119) — the **prowl creep**, and with [`STEALTH_STAND`] the entire difference
-/// stealth makes to a body's *pose*. Byte-verified (wow-re `rf57-movement-anim-select.md`, the
-/// 2026-07-18 §5): both ids are gated by the same descriptor bit — `[[unit+0x110]+0x213] & 2`,
-/// `UNIT_FIELD_BYTES_1` byte 3's CREEP flag ([`crate::net::ObjectStore`]'s `unit_is_stealthed`) —
-/// 119 from the core cascade at `0x5fd1d3`, tested **after** the backward branch and **before the
-/// whole speed tail**, so a prowling unit never plays Run or Sprint however fast it travels.
+/// stealth makes to a body's *pose*. Both ids are gated by the same descriptor bit —
+/// `[[unit+0x110]+0x213] & 2`, `UNIT_FIELD_BYTES_1` byte 3's CREEP flag
+/// ([`crate::net::ObjectStore`]'s `unit_is_stealthed`) — 119 from the core cascade at `0x5fd1d3`,
+/// tested **after** the backward branch and **before the whole speed tail**, so a prowling unit
+/// never plays Run or Sprint however fast it travels.
 ///
 /// No aura, no visual kit, no spell id is involved. Stealth's *translucency* is its aura state
 /// kit's CharProc-14 (decision 0806) and its *pose* is this flag: two independent mechanisms off
 /// one server byte, which is exactly why the body could go translucent and still stand bolt
-/// upright. (The same flag's other three read sites are nameplate/marker suppression — it drives
-/// no body render at all; wow-re `ghost-death-visuals.md`.)
+/// upright. (The same flag's other three read sites are nameplate/marker suppression, among them
+/// `0x6070a0` and `0x60f600` — it drives no body render at all.)
 ///
 /// **119 is NOT rate-scaled.** The client's locomotion-rate whitelist `0x5fee80` is exactly
-/// `{4,5,11,12,13,37,38,39,42,43,44,45,135,143,187}` (byte-verified, §5-agreed; wow-re
-/// `rf57b-rate-jump-standstate.md`) and 119 is absent — the creep cycle plays at 1× whatever the
-/// live speed, so [`playback_rate`] leaves it alone.
+/// `{4,5,11,12,13,37,38,39,42,43,44,45,135,143,187}` and 119 is absent — the creep cycle plays at
+/// 1× whatever the live speed, so [`playback_rate`] leaves it alone.
 pub(super) const STEALTH_WALK: u16 = 119;
 
 /// StealthStand (120) — the prowl idle, from the **last** resolver in the chain (the fallback idle
@@ -56,17 +55,16 @@ pub(super) const STEALTH_WALK: u16 = 119;
 /// shuffle, the combat Ready idle, loot — outranks it. See [`STEALTH_WALK`] for the shared gate.
 pub(super) const STEALTH_STAND: u16 = 120;
 
-/// Mount (91) — the rider's seated pose while a mount model is attached (decision 0441;
-/// byte-verified, wow-re `mount-composition.md` B1): held **unconditionally** — moving, turning,
-/// airborne. The client arms it outside the base selector (once at attach by `0x607a00`, then
-/// re-forced on every `PlayAnimation` by `0x5fe2f0`'s mounted branch — there is NO mount leg in
-/// the `0x5fd8b0` chain); benilla pins the gait slot instead, the same rendered result. The
-/// locomotion the selector would pick plays on the mount model (same `0x5fd100` thresholds),
-/// via the mount child's own driver pass. Variations roll as any base loop (HumanMale authors 3).
+/// Mount (91) — the rider's seated pose while a mount model is attached (decision 0441): held
+/// **unconditionally** — moving, turning, airborne. The client arms it outside the base selector
+/// (once at attach by `0x607a00`, then re-forced on every `PlayAnimation` by `0x5fe2f0`'s mounted
+/// branch — there is NO mount leg in the `0x5fd8b0` chain); benilla pins the gait slot instead, the
+/// same rendered result. The locomotion the selector would pick plays on the mount model (same
+/// `0x5fd100` thresholds), via the mount child's own driver pass. Variations roll as any base loop
+/// (HumanMale authors 3).
 pub(super) const MOUNT: u16 = 91;
 
-/// Loot (50) — the kneel-and-rummage held while a unit's loot window is open. Byte-verified end
-/// to end (wow-re `loot-anim-leg.md`, the 2026-07-18 §5 + the 08-21 §5 trio; decisions 0515 /
+/// Loot (50) — the kneel-and-rummage held while a unit's loot window is open (decisions 0515 /
 /// 1471 / 1477): the `0x5fd8b0` chain's loot leg `0x5fd260` → 0x32 = 50, chain order locomotion →
 /// **LOOT** → standState → combat/channel (movement outranks by position — the leg itself reads no
 /// movement state), leg gates `[+0xdc]==0` (never mounted) + the `[+0xd58]&0x40` enable.
@@ -96,22 +94,22 @@ pub(super) const LOOT: u16 = 50;
 pub(super) const UNIT_FLAG_LOOTING: u32 = 0x400;
 
 /// `UNIT_FIELD_FLAGS` bit `0x1000_0000` — must be CLEAR for a remote unit's loot kneel
-/// (`0x612710`, byte-verified; the §5's one INFERRED residue is this bit's Blizzard *name*, not
+/// (`0x612710`; its one inferred residue is this bit's Blizzard *name*, not
 /// its role). vmangos never sets it on players, so the gate is inert on our wire — carried for
 /// the faithful predicate shape.
 pub(super) const UNIT_FLAG_LOOT_SUPPRESS: u32 = 0x1000_0000;
 
 /// MountSpecial (94) — the mounted flourish (the horse rears; decision 0441 P2). Plays on the
-/// MOUNT model as a one-shot (§5-verified, wow-re `mount-composition.md`: MountSpecial routes to
-/// the mount via the same `0x5fe2f0` op4 target as its locomotion), never on the rider — the
-/// rider holds [`MOUNT`] throughout. Fired by the space-bar gate (self, locally at send time)
-/// and by `SMSG_MOUNTSPECIAL_ANIM` (observed riders; our own echo is dropped in the net drain).
+/// MOUNT model as a one-shot (MountSpecial routes to the mount via the same `0x5fe2f0` op4 target
+/// as its locomotion), never on the rider — the rider holds [`MOUNT`] throughout. Fired by the
+/// space-bar gate (self, locally at send time) and by `SMSG_MOUNTSPECIAL_ANIM` (observed riders;
+/// our own echo is dropped in the net drain).
 pub(crate) const MOUNT_SPECIAL: u16 = 94;
 
 /// The three ids whose arm takes the **base-animation lock** — `0x5fdba0`'s tail keyed on the id
-/// actually armed, byte table `0x5fdd90` (wow-re `base-anim-lock-knockdown.md` §2). While one of
-/// these holds bone 0, `PlayAnimation` refuses every base request outright, which is what lets a
-/// stunned victim's `Knockdown` play out over the root's own `Stand` recompute.
+/// actually armed, byte table `0x5fdd90`. While one of these holds bone 0, `PlayAnimation` refuses
+/// every base request outright, which is what lets a stunned victim's `Knockdown` play out over the
+/// root's own `Stand` recompute.
 ///
 /// They are the clips with a definite start and end pose — the ones a re-pick mid-flight would
 /// leave the body wrong: knocked flat, or halfway off the ground.
@@ -122,8 +120,8 @@ pub(crate) const LIFT_OFF: u16 = 192;
 pub(crate) const LAND: u16 = 200;
 
 /// Movement direction/mode flag bits, matching the client's CMovement `MOVEMENTFLAGS` (cached at
-/// `unit+0x9e8`; VERIFIED wow-5875-re RF-0057 + the jump §5 cross-check). The selector tests these
-/// exactly as the binary does, so a streamed unit can eventually drop the server's raw `u32` straight in.
+/// `unit+0x9e8`). The selector tests these exactly as the binary does, so a streamed unit can
+/// eventually drop the server's raw `u32` straight in.
 pub(crate) mod move_flags {
     pub const FORWARD: u32 = 0x1;
     pub const BACKWARD: u32 = 0x2;
@@ -139,9 +137,8 @@ pub(crate) mod move_flags {
     pub const WALK_MODE: u32 = 0x100;
     /// MOVEFLAG_LEVITATING — **the free-flight bit, and it works by SUPPRESSION.** It is the very
     /// first test in the client's per-frame swim decision `0x6030c0` (`0x6030d2 test ah,4` → bail to
-    /// `0x6031fa`; VERIFIED, wow-re `collision/scratch/swim-transition.md`): set, and the whole
-    /// water/depth decision is skipped — neither the ENTER arm nor the STOP arm runs, so liquid can
-    /// no longer latch *or unlatch* [`SWIMMING`].
+    /// `0x6031fa`): set, and the whole water/depth decision is skipped — neither the ENTER arm nor
+    /// the STOP arm runs, so liquid can no longer latch *or unlatch* [`SWIMMING`].
     ///
     /// That suppression is the entirety of GM flight. vmangos's `.cheat fly` sends
     /// `LEVITATING | SWIMMING | MOVED | FLYING` (`Player::SetFly`): `SWIMMING` puts the mover in the
@@ -152,13 +149,13 @@ pub(crate) mod move_flags {
     pub const LEVITATING: u32 = 0x400;
     /// JUMPING/FALLING — set for the whole airborne arc; drives the jump Special state.
     pub const FALLING: u32 = 0x2000;
-    /// MOVEFLAG_FALLINGFAR — the arc has become a **far fall** (`0x633220`/`0x633240`; wow-re
-    /// `land-anim-height-gate.md`, legs corrected by decision 0179): a *jump* (launch vz ≠ 0)
-    /// latches once it descends 1/9 yd below its launch height; a *step-off fall* (launch vz = 0)
-    /// latches at 500 ms airborne (≈ 2.41 yd of free fall — a fence hop never latches, a
-    /// wagon-height drop latches just before the floor). Cleared only with FALLING at StopFalling
-    /// (`0x7c6290`). Mid-air it swaps the pose to Fall(40) and it opens the landing-anim gate; a
-    /// flat jump never descends below its takeoff, so its hang stays Jump(38).
+    /// MOVEFLAG_FALLINGFAR — the arc has become a **far fall** (`0x633220`/`0x633240`; legs
+    /// corrected by decision 0179): a *jump* (launch vz ≠ 0) latches once it descends 1/9 yd below
+    /// its launch height; a *step-off fall* (launch vz = 0) latches at 500 ms airborne (≈ 2.41 yd
+    /// of free fall — a fence hop never latches, a wagon-height drop latches just before the
+    /// floor). Cleared only with FALLING at StopFalling (`0x7c6290`). Mid-air it swaps the pose to
+    /// Fall(40) and it opens the landing-anim gate; a flat jump never descends below its takeoff,
+    /// so its hang stays Jump(38).
     pub const FALLING_FAR: u32 = 0x4000;
     /// MOVEFLAG_ROOT — the server rooted this mover (death, until release). The controller MUST
     /// carry it in the root-apply ack's MovementInfo (vmangos `HandleMoveRootAck:715` KICKS a
@@ -178,19 +175,18 @@ pub(crate) mod move_flags {
     /// MOVEFLAG_SAFE_FALL — **feather fall** (Slow Fall, Levitate; decision 0866). It has exactly
     /// one effect: the fall-velocity query `0x7c5d20` picks its terminal clamp on this bit
     /// (`0x7c5d23 test [ecx+0x40],0x20000000`) — 7.0 yd/s `[0x87d898]` instead of the ordinary
-    /// 60.148 `[0x87d894]`. wow-re's ledger labels it "in-water; selects swim gravity", which is the
-    /// bit's *shape* read without the server-side name: vmangos sets it only from
+    /// 60.148 `[0x87d894]`. A bytes-only reading labels it "in-water; selects swim gravity", which
+    /// is the bit's *shape* read without the server-side name: vmangos sets it only from
     /// `SPELL_AURA_FEATHER_FALL`, and swimming is the separate [`SWIMMING`] (0x200000).
     pub const SAFE_FALL: u32 = 0x2000_0000;
-    /// MOVEFLAG_HOVER — the body rests 1.0 yd above the ground (Levitate; decision 0866). VERIFIED
-    /// as hover rather than a wade bit in wow-re `system/collision/collision.md`: the WALK resolver
-    /// `0x6367b0` gates a `[0x7ff9d8]` = +1.0-yd surface offset on it, and the step-down reach
-    /// widens by the same yard (`0x633e35`).
+    /// MOVEFLAG_HOVER — the body rests 1.0 yd above the ground (Levitate; decision 0866). Hover
+    /// rather than a wade bit: the WALK resolver `0x6367b0` gates a `[0x7ff9d8]` = +1.0-yd surface
+    /// offset on it, and the step-down reach widens by the same yard (`0x633e35`).
     pub const HOVER: u32 = 0x4000_0000;
 
     /// The bits a **server-authored move packet owns**, and the only ones it may write — the
-    /// reference's flag *merge* mask, VERIFIED at `0x618c30 @0x618deb`
-    /// (`new = old ^ ((old ^ wire) & 0x75a07dff)`; wow-re `self-addressed-move.md`, decision 0725).
+    /// reference's flag *merge* mask, at `0x618c30 @0x618deb`
+    /// (`new = old ^ ((old ^ wire) & 0x75a07dff)`; decision 0725).
     /// Applying a `MSG_MOVE_*` is not an assignment: bits outside this mask are kept from local
     /// state, because they are the client's own (`0x618c30` also holds a second mask,
     /// `0x75a01dff`, for a caller arm that passes a non-zero 4th arg — the plain state family
@@ -209,7 +205,7 @@ pub(crate) mod move_flags {
     /// assignment. One law, both movers: our own (`player::wire_in`'s self-addressed pose) and every
     /// watched one (`net::motion::remote::apply_move`), because the reference runs this merge inside
     /// the one scheduler both go through and the mask is arm-invariant across all thirty relay
-    /// opcodes (wow-re `collision/scratch/movement-relay-family-map.md`, decision 2064).
+    /// opcodes (`0x618f20` always takes the wide arm; decision 2064).
     ///
     /// The omission that bites is pinned by test on the self lane: [`ON_TRANSPORT`] sits **outside**
     /// the mask, so a server-authored pose can relocate a rider but never board or deboard them.
@@ -224,11 +220,9 @@ pub(crate) mod move_flags {
     /// must pass before any physics runs on it. `CMovement::Update 0x616de0` opens its substep loop
     /// with `0x616e20 test dword [esi+0x40],0x20ff; je 0x616f49` (none set ⇒ finalize, having
     /// integrated nothing), and the movement manager tests the same mask before it ever calls the
-    /// integrator (`0x6166f5`) — the "idle gate" decision 0059 named by address. wow-re states the
-    /// consequence for a watched player outright: *"for a **STANDING remote** the integrator does
-    /// NOT run … a flag-less unit is not even in the mover list"*
-    /// (`collision/scratch/remote-air-facing.md` §A4; the loop gate is in `collision/collision.md`
-    /// and `scratch/spec-driver-A.md`/`-B.md`).
+    /// integrator (`0x6166f5`) — the "idle gate" decision 0059 named by address. The consequence
+    /// for a watched player: for a **STANDING remote** the integrator does NOT run, and a flag-less
+    /// unit is not even in the mover list (`0x618940`).
     ///
     /// So a mover with none of these bits keeps the pose its last packet wrote, verbatim, until a
     /// packet or a flag moves it — which is what decision 1545 makes benilla do. The bits: the four
@@ -248,13 +242,13 @@ pub(crate) mod move_flags {
         FORWARD | BACKWARD | STRAFE_LEFT | STRAFE_RIGHT | TURN_LEFT | TURN_RIGHT | SWIMMING;
 
     /// The stationary-cast pin's "moving" test — the client's `[9e8] & 0x20000f` in the `0x5fde80`
-    /// cast-override gate (wow-re `spell-visual-apply.md` §2.1, VERIFIED): the direction bits plus
-    /// swim, and NOTHING else. The turn bits are absent — a caster turning in place (keys or a
-    /// mouselook body-step) keeps the full-body pin. Distinct from [`ROUTE_COMMITTED_MOVE`]'s
-    /// `0x20003f` (the one-shot route test at `0x5fe6dc` — a different byte site, a different
-    /// mask); using that mask here made the pin flap at mouse-event cadence — the transient
-    /// chase-step TURN flags demoted the hold to shuffle+overlay on every mouse-delta frame and
-    /// re-pinned on every quiet one (decision 0491, the frostbolt right-drag jitter).
+    /// cast-override gate: the direction bits plus swim, and NOTHING else. The turn bits are absent
+    /// — a caster turning in place (keys or a mouselook body-step) keeps the full-body pin.
+    /// Distinct from [`ROUTE_COMMITTED_MOVE`]'s `0x20003f` (the one-shot route test at `0x5fe6dc` —
+    /// a different byte site, a different mask); using that mask here made the pin flap at
+    /// mouse-event cadence — the transient chase-step TURN flags demoted the hold to
+    /// shuffle+overlay on every mouse-delta frame and re-pinned on every quiet one (decision 0491,
+    /// the frostbolt right-drag jitter).
     pub const CAST_PIN_MOVE: u32 = ANY_MOVE | SWIMMING;
 }
 
@@ -279,14 +273,13 @@ pub(crate) fn ease_strafe_yaw(current_yaw: f32, aim: f32, offset: f32, dt: f32)
 }
 
 /// The strafe **body-heading offset** (radians) a unit's rendered root yaw sits from its aim — the
-/// client's display-facing strafe blend (wow-5875-re `body-facing-pipeline.md` §3, `0x607ed0` tail):
-/// ±π/2 for a pure strafe, ±π/4 when forward/back is also held (`flags & 3`). Yaw is left-positive
-/// (WoW orientation and our Bevy yaw alike), so strafe-left is `+` — **mirrored while backpedaling**
-/// (the client's sign fold `((flags>>1)&2) == (flags&2)`): a back-left diagonal faces the body
-/// forward-right and backpedals along the movement line, legs never crossing. `0` when not strafing
-/// (both strafe bits set cancel — no lateral motion results, unlike the client's left-bit-only fold,
-/// an unobservable edge). The [`super::twist::BodyTwist`] counter-twist then walks the upper body
-/// back toward the aim.
+/// client's display-facing strafe blend (`0x607ed0` tail): ±π/2 for a pure strafe, ±π/4 when
+/// forward/back is also held (`flags & 3`). Yaw is left-positive (WoW orientation and our Bevy yaw
+/// alike), so strafe-left is `+` — **mirrored while backpedaling** (the client's sign fold
+/// `((flags>>1)&2) == (flags&2)`): a back-left diagonal faces the body forward-right and backpedals
+/// along the movement line, legs never crossing. `0` when not strafing (both strafe bits set cancel
+/// — no lateral motion results, unlike the client's left-bit-only fold, an unobservable edge). The
+/// [`super::twist::BodyTwist`] counter-twist then walks the upper body back toward the aim.
 pub(crate) fn strafe_body_offset(flags: u32) -> f32 {
     use std::f32::consts::{FRAC_PI_2, FRAC_PI_4};
     let left = flags & move_flags::STRAFE_LEFT != 0;
@@ -305,7 +298,7 @@ pub(crate) fn strafe_body_offset(flags: u32) -> f32 {
 }
 
 /// The **swim body pitch** — the one render law, for every mover that has a reported pitch
-/// (TU-A, decision 0464 §1; `0x60a110`→`0x710620`, the Euler-ZYX builder).
+/// (decision 0464 §1; `0x60a110`→`0x710620`, the Euler-ZYX builder).
 ///
 /// The reference composes `T·S·Rz(facing)·Ry(2π − pitch)`: yaw about WoW +Z, pitch about WoW +Y
 /// from `CMovement+0x20`, +pitch = nose up. That is this expression, worked through the basis
@@ -317,21 +310,19 @@ pub(crate) fn strafe_body_offset(flags: u32) -> f32 {
 ///
 /// The facing it reads is `+0xc94`, the **render** facing rather than the raw movement one
 /// (`+0x1c`); for a swimmer the two coincide, because SWIMMING is on the display-facing SNAP list
-/// (`mov [esi+0xc94],[esi+0xc98]`, wow-re `body-facing-pipeline.md`) — the same gate our callers
+/// (`mov [esi+0xc94],[esi+0xc98]` in the `0x607ed0` tail) — the same gate our callers
 /// apply before handing a yaw in.
 ///
 /// The gate is `SWIMMING` **and** a forward/back bit: strafe-only, idle, and grounded all render
 /// **level** (the ground path). It is `CMovement+0x40 & 3`, read at `0x60857d` off the very word
 /// the create-block apply and every relayed `MSG_MOVE_*` merge into under `0x75a07dff` — **not**
 /// a `CM2Model+0x3c & 3` dirty gate, which is what an earlier reading of this law named and which
-/// a wow-re §5 has since scanned for exhaustively and found does not exist (`0x710620` is an
-/// unconditional 16-dword copy). Recorded in wow-re
-/// `system/collision/scratch/create-block-swim-pitch.md`.
+/// does not exist (`0x710620` is an unconditional 16-dword copy).
 ///
 /// One function rather than one per pose owner: the law has three consumers — our own avatar
 /// ([`crate::player::body_pose`]), an observed relay mover
 /// ([`crate::net::motion::extrapolate_remote_units`]), and the create-block seed
-/// ([`crate::net::apply::objects`]) — and TU-A is explicit that all of them present the *same*
+/// ([`crate::net::objects`]) — and in the reference all of them present the *same*
 /// pitch. Held apart, they drift: the remote lane shipped in July 2026 with no test and no trace
 /// of its own, so "does an observed swimmer tilt?" had no answer short of the director's eye.
 pub(crate) fn swim_body_rotation(yaw: f32, flags: u32, pitch: f32) -> Quat {
@@ -344,8 +335,9 @@ pub(crate) fn swim_body_rotation(yaw: f32, flags: u32, pitch: f32) -> Quat {
     }
 }
 
-/// The per-frame movement descriptor that drives a unit's animation (wow-5875-re RF-0057). The player
-/// controller fills it for our avatar from input; a streamed unit's is derived from its [`Spline`].
+/// The per-frame movement descriptor that drives a unit's animation (what the selector `0x5fd8b0`
+/// reads). The player controller fills it for our avatar from input; a streamed unit's is derived
+/// from its [`Spline`].
 #[derive(Component, Clone, Copy, Default)]
 pub(crate) struct MovementState {
     /// Live movement speed (yd/s) — `0` while standing. The rate-scaler's numerator and the
@@ -371,27 +363,25 @@ pub(crate) struct MovementState {
     pub(crate) stealthed: bool,
     /// Riding a **flying** server spline (the taxi flight): the client's selector reads the active
     /// CMovement's spline flags (`[[unit+0x118]+0xa4]+0x18`) and plays Fly 135 when the wire Flying
-    /// bit (0x200) is set — RF-0057 `0x5fd19c`. Stamped by [`unify`] from the entity's live
+    /// bit (0x200) is set — `0x5fd19c`. Stamped by [`unify`] from the entity's live
     /// [`Spline`] each frame (the same read-through the client does); the controller's stored
     /// component leaves it `false`.
     pub(crate) flying: bool,
 }
 
 /// A transition-bracketed animation state — a one-shot **enter** → **loop** → one-shot **exit**, as
-/// opposed to the directly-cross-faded gaits. The ids are from the verified selector + the HumanMale.m2
-/// sequence table (wow-5875-re; decisions 0047/0049).
+/// opposed to the directly-cross-faded gaits. The ids are from the reference selector + the
+/// HumanMale.m2 sequence table (decisions 0047/0049).
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum Special {
     /// Airborne from a **jump** (the arc launched upward): JumpStart(37) → Jump(38) hang.
-    /// **VERIFIED** (the swim-hop §5, wow-re `swim-jump-anim-law.md`): `0x60e480` case 0xbb
-    /// (MSG_MOVE_JUMP) arms **37 directly**, local and observed alike, and 38 follows only by
-    /// 37's own 833 ms window elapsing — a short arc (the ~0.24 s deep swim hop) never shows
-    /// 38, which the Entering→`oneshot_finished` machine reproduces. (rf57b's dispatcher
-    /// divergence is settled: `0x5fc3f0`'s events 0x25/0x26 → 38 is the separate
-    /// emote/anim-event dispatcher, not the jump path.) FALLINGFAR
-    /// latching mid-arc hands off to [`Special::Fall`]; the landing is [`jump_land_pick`]. A
-    /// **step-off fall** never enters here — its gait freezes (the base selector's keep-current,
-    /// via the takeoff-frozen flags/speed) until FALLINGFAR latches.
+    /// `0x60e480` case 0xbb (MSG_MOVE_JUMP) arms **37 directly**, local and observed alike, and 38
+    /// follows only by 37's own 833 ms window elapsing — a short arc (the ~0.24 s deep swim hop)
+    /// never shows 38, which the Entering→`oneshot_finished` machine reproduces. (`0x5fc3f0`'s
+    /// events 0x25/0x26 → 38 is the separate emote/anim-event dispatcher, not the jump path.)
+    /// FALLINGFAR latching mid-arc hands off to [`Special::Fall`]; the landing is
+    /// [`jump_land_pick`]. A **step-off fall** never enters here — its gait freezes (the base
+    /// selector's keep-current, via the takeoff-frozen flags/speed) until FALLINGFAR latches.
     Jump,
     /// Airborne and **fallen far** (FALLINGFAR latched): the Fall(40) loop, entered *directly* —
     /// the client plays 40 the tick the flag latches (`0x602c40`), no enter one-shot — so
@@ -449,13 +439,13 @@ impl Special {
     }
 }
 
-/// The jump-landing one-shot, from the flags at touchdown — the client's land dispatcher `0x602c60`
-/// (wow-5875-re rf57b §2), transcribed: swimming → no landing anim (the recompute picks the swim
-/// gait); stopped (`flags & 0xf == 0`) → JumpEnd **39**; moving — unless BACKWARD (`0x2`) or
-/// WALK-mode (`0x100`) — → JumpLandRun **187**; a **backpedaling or walking** landing plays **no
-/// one-shot at all**, dropping straight into the gait (the reference backpedals the instant it
-/// touches down; 187 is a forward-run footplant and never plays backward — the "forward run flash
-/// after a jump-then-hold-S" bug). `None` = no landing clip, go straight to `Mode::Gait`.
+/// The jump-landing one-shot, from the flags at touchdown — the client's land dispatcher
+/// `0x602c60`, transcribed: swimming → no landing anim (the recompute picks the swim gait); stopped
+/// (`flags & 0xf == 0`) → JumpEnd **39**; moving — unless BACKWARD (`0x2`) or WALK-mode (`0x100`) —
+/// → JumpLandRun **187**; a **backpedaling or walking** landing plays **no one-shot at all**,
+/// dropping straight into the gait (the reference backpedals the instant it touches down; 187 is a
+/// forward-run footplant and never plays backward — the "forward run flash after a
+/// jump-then-hold-S" bug). `None` = no landing clip, go straight to `Mode::Gait`.
 ///
 /// **A ROOTED arc end is not a landing** (decision 0880). A root or a stun caught mid-air ends the
 /// fall where the body hangs — `SetRoot 0x7c7340`'s `StopFalling` clears FALLING with no ground
@@ -505,7 +495,7 @@ pub(super) enum Mode {
     /// While `under` is airborne the one-shot obeys the client's airborne-freeze: a finished clip
     /// clamps and holds its last frame, flag changes are keep-current no-ops, and only a Special
     /// *edge* exits — the FALLINGFAR latch's Fall (played ONCE, at the latch edge
-    /// `0x61a820` — 0864's per-tick re-assert was §5-refuted, decision 0868; a clip armed
+    /// `0x61a820` — 0864's per-tick re-assert was refuted, decision 0868; a clip armed
     /// after the latch holds like any other) and the `0x602c60` land pick at touchdown. Grounded
     /// (`under == None`) it returns to Gait when it finishes; a new one restarts it — and any
     /// movement-flag change since the **base** was last armed
@@ -520,11 +510,11 @@ pub(super) enum Mode {
 }
 
 /// The gait an idle/moving unit should play in [`Mode::Gait`], most-specific id first with fallbacks so a
-/// model lacking the ideal clip steps down rather than snapping (RF-0057 core, minus the Special states —
-/// jump and the sit/sleep/kneel poses are handled by the state machine). `walk_speed` is the unit's own
-/// walk speed (the run boundary is 2× it). `ready` is the engaged combat idle (decision 0073), played
-/// only when standing on the ground — locomotion outranks it, and a swimming engaged unit treads
-/// water (the client's own gate order).
+/// model lacking the ideal clip steps down rather than snapping (the `0x5fd8b0` chain's core, minus
+/// the Special states — jump and the sit/sleep/kneel poses are handled by the state machine).
+/// `walk_speed` is the unit's own walk speed (the run boundary is 2× it). `ready` is the engaged
+/// combat idle (decision 0073), played only when standing on the ground — locomotion outranks it,
+/// and a swimming engaged unit treads water (the client's own gate order).
 pub(super) fn gait_candidates(
     state: &MovementState,
     walk_speed: f32,
@@ -533,11 +523,11 @@ pub(super) fn gait_candidates(
 ) -> &'static [u16] {
     use move_flags::*;
     let f = state.flags;
-    // Swimming (RF-0057 core, `[9e8] & 0x200000`) — the VERIFIED `0x5fd100` cascade (the swim §5's
-    // TU-E, wow-re `swim-mechanism.md`): **TURN > STRAFE > BACKWARD > FORWARD**, ids turn→41,
-    // strafeL(0x4)→43 / strafeR(0x8)→44 (SwimLeft/SwimRight — names byte-read from
-    // AnimationData.dbc), back→45, fwd→42, idle→41. So a turning swimmer treads water whatever its
-    // travel bits, and a strafe diagonal (fwd+strafe, back+strafe) plays the side-stroke, not 42/45.
+    // Swimming (`[9e8] & 0x200000`) — the `0x5fd100` cascade: **TURN > STRAFE > BACKWARD >
+    // FORWARD**, ids turn→41, strafeL(0x4)→43 / strafeR(0x8)→44 (SwimLeft/SwimRight — names
+    // byte-read from AnimationData.dbc), back→45, fwd→42, idle→41. So a turning swimmer treads
+    // water whatever its travel bits, and a strafe diagonal (fwd+strafe, back+strafe) plays the
+    // side-stroke, not 42/45.
     if f & SWIMMING != 0 {
         return if f & (TURN_LEFT | TURN_RIGHT) != 0 {
             &[41, 0]
@@ -553,7 +543,7 @@ pub(super) fn gait_candidates(
             &[41, 0]
         };
     }
-    // A flying server spline — the taxi ride (RF-0057 `0x5fd19c`, between the swim block and the
+    // A flying server spline — the taxi ride (`0x5fd19c`, between the swim block and the
     // backward test in the byte cascade): the spline's wire Flying bit selects Fly 135 outright,
     // before the backward and speed branches — a 32 yd/s taxi plays Fly, never Sprint 143. The
     // one-step fallback mirrors AnimationData (Fly → 0 Stand); every shipped taxi mount authors
@@ -561,11 +551,11 @@ pub(super) fn gait_candidates(
     if state.flying {
         return &[135, 0];
     }
-    // Backward dominates strafe (RF-0057 `[9e8] & 2` → WalkBackwards 13).
+    // Backward dominates strafe (`0x5fd1bc`, `[9e8] & 2` → WalkBackwards 13).
     if f & BACKWARD != 0 {
         return &[13, 4, 0];
     }
-    // Stealthed and moving — the prowl (RF-0057 `0x5fd1d3`, sitting between the backward branch and
+    // Stealthed and moving — the prowl (`0x5fd1d3`, sitting between the backward branch and
     // the speed tail; [`STEALTH_WALK`]). The gate outranks the ENTIRE speed tail, so a stealthed
     // unit creeps at any speed, while a *backpedaling* one plays WalkBackwards — backward is tested
     // first. The Walk 4 fallback is `AnimationData.dbc`'s own Fallback for row 119, which is also
@@ -575,8 +565,8 @@ pub(super) fn gait_candidates(
     if state.stealthed && f & ANY_MOVE != 0 {
         return &[STEALTH_WALK, 4, 0];
     }
-    // Ground gaits by live speed (RF-0057 core): fast-run ≥ 11, run > 2× walk, else walk.
-    // (Strafe currently routes here to Run/Walk; the dedicated-shuffle question is under §5 verification.)
+    // Ground gaits by live speed (`0x5fd202`/`0x5fd224`): fast-run ≥ 11, run > 2× walk, else walk.
+    // (Strafe currently routes here to Run/Walk; whether it has a dedicated shuffle is open.)
     if f & ANY_MOVE != 0 {
         let s = state.speed;
         return if s >= FAST_RUN_SPEED {
@@ -587,7 +577,7 @@ pub(super) fn gait_candidates(
             &[4, 0]
         };
     }
-    // Turning in place (the turn keys with no translation): the foot-shuffle (RF-0057 `0x5fd3f0` →
+    // Turning in place (the turn keys with no translation): the foot-shuffle (`0x5fd3f0` →
     // ShuffleLeft 11 / ShuffleRight 12). Only reached when not moving — moving with a turn curves the
     // run path and plays the gait above.
     if f & TURN_LEFT != 0 {
@@ -615,10 +605,10 @@ pub(super) fn gait_candidates(
         // The Hold twins 109/110 ARE reachable (decision 1544): `0x5fd460`'s own jump table writes
         // only 105/106/111/112, but a finished Load is promoted to its Hold by the completion
         // dispatch (`0x5fc3f0` slot 11/12/15), and the caller passes whichever of the pair
-        // currently owns the pose. 0994 left them out on §J4.1's absence proof — that the
-        // dispatcher is never reached for a bow id — which wow-re's §5 has since refuted.
-        // Each Hold falls back to its own Load first: a model that authors the pull but not the
-        // hold should freeze at full draw, not drop to ReadyUnarmed.
+        // currently owns the pose. 0994 left them out on an absence proof — that the dispatcher is
+        // never reached for a bow id — which is false: the completion dispatcher has a second,
+        // deferred fire site (`0x7075af`). Each Hold falls back to its own Load first: a model that
+        // authors the pull but not the hold should freeze at full draw, not drop to ReadyUnarmed.
         return match l {
             105 => &[105, 25, 0],
             106 => &[106, 25, 0],
@@ -645,18 +635,17 @@ pub(super) fn gait_candidates(
     }
 }
 
-/// The local auto-repeat **standing idle** id — the client's `0x5fd460` → LUT `0x5fd530`
-/// (byte-verified, wow-re `ranged-shot-anim.md`): the RANGED-slot item's subclass picks a held
-/// Load/Hold clip — Bow → LoadBow 105 · Gun/Crossbow → LoadRifle 106 · Thrown → LoadThrown 112 ·
-/// Wand → HoldThrown 111 · anything else → ReadyUnarmed 25. **Not** ReadyBow/AttackBow: no code
-/// in the client plays those rows.
+/// The local auto-repeat **standing idle** id — the client's `0x5fd460` → LUT `0x5fd530`: the
+/// RANGED-slot item's subclass picks a held Load/Hold clip — Bow → LoadBow 105 · Gun/Crossbow →
+/// LoadRifle 106 · Thrown → LoadThrown 112 · Wand → HoldThrown 111 · anything else →
+/// ReadyUnarmed 25. **Not** ReadyBow/AttackBow: no code in the client plays those rows.
 ///
-/// (This doc used to carry `ranged-shot-anim.md` §(a)'s "the per-shot caster fire animation is a
-/// verified NEGATIVE — the shot shows only the missile". That was REFUTED twice over: by the
-/// weapon-visual merge, which plays the fire clip off the weapon's own substitute visual
-/// (decision 0370/0986), and by the completion dispatch below (decision 1544). It is gone rather
-/// than hedged — a stale negative in a doc is how a session concludes the missing animation is
-/// correct, which is exactly what happened to bug B307.)
+/// (This doc used to carry the claim "the per-shot caster fire animation is a verified NEGATIVE —
+/// the shot shows only the missile". That was REFUTED twice over: by the weapon-visual merge, which
+/// plays the fire clip off the weapon's own substitute visual (decision 0370/0986), and by the
+/// completion dispatch below (decision 1544). It is gone rather than hedged — a stale negative in a
+/// doc is how a session concludes the missing animation is correct, which is exactly what happened
+/// to bug B307.)
 pub(super) fn ranged_load_anim(ranged: Option<(u8, u8)>) -> u16 {
     match ranged {
         Some((2, 2)) => 105,           // Bow → LoadBow
@@ -679,7 +668,7 @@ pub(super) fn is_ranged_load(id: u16) -> bool {
 /// → HoldThrown 111. The wand's HoldThrown 111 is already the hold and re-arms itself, and
 /// anything else (ReadyUnarmed 25) holds nothing and stays put.
 ///
-/// **The promotion is UNCONDITIONAL** (wow-re §5, decision 1544): the `[+0xd24]` ranged-prop and
+/// **The promotion is UNCONDITIONAL** (decision 1544): the `[+0xd24]` ranged-prop and
 /// `[+0xd58] & 0x600` test at `0x5fc5bc` belongs to slot **13** — the Hold's own re-arm — not to
 /// the Load's slot 11, which is the bare `mov eax,0x6d ; push eax ; call 0x5fe2f0` at `0x5fc5e9`.
 /// Reading that gate onto the Load is the mistake that would leave a shooter frozen at full draw.
@@ -696,8 +685,7 @@ pub(super) fn ranged_hold_anim(load: u16) -> u16 {
     }
 }
 
-/// Does the drawn ranged Load idle own this unit's standing pose? Byte-verified, wow-re
-/// `shooter-stop-law.md` §J6 claim 1 (§5, four independent pairs + byte arbitration):
+/// Does the drawn ranged Load idle own this unit's standing pose?
 ///
 /// `0x5fd460` — tier 9 of `ComputeAnimation 0x5fd8b0`, and the **only** writer of 105/106/111/112
 /// image-wide — claims on exactly two tests and nothing else:
@@ -710,15 +698,15 @@ pub(super) fn ranged_hold_anim(load: u16) -> u16 {
 /// `0x200`'s only writer image-wide is the LOCAL cast-send `0x6e593b`, gated `AttributesEx2 &
 /// 0x20` — so entry means *this client's player is actively auto-repeating*. **`0x400`
 /// ([`super::RangedHold`]) is never tested in this function.** It appears only in `0x5fc3f0`'s
-/// sustain gates (`test ah,0x6` for 109, `test ah,0x4` for 110/111/112), which §J4 shows never
+/// sustain gates (`test ah,0x6` for 109, `test ah,0x4` for 110/111/112), which never
 /// run. Folding it into this gate is what let one Serpent Sting / Multi-Shot — any ranged-slot
 /// spell whose visual sets the hold bit — leave the shooter aiming a drawn bow with nothing able
 /// to clear it (director-reported 2026-08-05).
 ///
 /// A REMOTE shooter never runs the local cast-send, so it never enters here. It is not simply
-/// Stand, though (§J6 claim 2, CORRECTED): it plays **LoadBow(105) once** at the volley's single
-/// `SMSG_SPELL_START`, through the PrecastKit — our [`super::CastHold`] path — then AttackBow per
-/// GO over its ordinary idle. Never a sustained aim pose.
+/// Stand, though: it plays **LoadBow(105) once** at the volley's single `SMSG_SPELL_START`
+/// (`0x6e7901`), through the PrecastKit — our [`super::CastHold`] path — then AttackBow per GO over
+/// its ordinary idle. Never a sustained aim pose.
 ///
 /// The caller applies the tier order: locomotion (tier 4) outranks tier 9, so a moving unit is
 /// never in the idle whatever these bits say.
@@ -754,7 +742,7 @@ pub(super) fn defense_anim(victim_state: u32, main: Option<(u8, u8)>) -> Option<
 
 /// The **play-time unarmed-special substitution** — the third weapon substitution in the client,
 /// and the only one that lives inside `PlayAnimation` itself rather than in a selector
-/// (`0x5fe2f0` @ `0x5fe3cc`–`0x5fe3e9`, byte-verified: wow-re `disarm-weapon-gate-law.md` §7).
+/// (`0x5fe2f0` @ `0x5fe3cc`–`0x5fe3e9`).
 /// A requested **Special1H(57) / Special2H(58)** — the weapon-remapped spin a spell kit asks for,
 /// Eviscerate's among them — becomes **SpecialUnarmed(118)** when `GetWeapon(0, 0)` *and*
 /// `GetWeapon(1, 0)` are both NULL, i.e. both hands are empty to the combat reading.
@@ -777,8 +765,7 @@ pub(super) fn is_swing_id(id: u16) -> bool {
     matches!(id, 16..=19 | 85 | 87 | 88 | 117)
 }
 
-/// The client's COMBAT-anim classifier (`0x5fcc10` — wow-re `combat-anim-fastpath.md` §3, the
-/// exhaustive byte-decoded table, cross-confirmed against `anim-composition-model.md`): the gate
+/// The client's COMBAT-anim classifier (`0x5fcc10` — the exhaustive byte-decoded table): the gate
 /// on `PlayAnimation`'s combat fast-path (decision 0406). A combat clip requested while another
 /// combat clip is playing is NOT armed — the current clip's rate doubles and the request defers.
 /// Members: the swings (16–19 main, 85/86 dagger, 87/88/117 off), the specials (57/58/118 —
@@ -789,13 +776,12 @@ pub(super) fn is_combat_anim(id: u16) -> bool {
     matches!(id, 10 | 16..=24 | 30 | 36 | 57..=59 | 85..=88 | 95 | 117 | 118)
 }
 
-/// The client's **CAST** classifier (`0x5fcbb0` — byte-decoded in wow-re `oneshot-lifecycle.md`
-/// §7, previously unlabelled): the spell-cast release anims `{2, 32, 33, 53, 54}`. Together with
-/// [`is_combat_anim`] it is what the **transplant** predicate (`0x5feae0`) tests on the *currently
-/// armed bone-0 clip*: a locomotion request over one of these does not replace it — the clip moves
-/// up onto the key-bone at its live play position ([`OneShotRoute`]'s two slots, decision 0878).
-/// NOT the ReadySpell holds (51/52) — those are their own set (`0x5fde40`), and a jump over a
-/// standing hold really does take the whole body.
+/// The client's **CAST** classifier (`0x5fcbb0`): the spell-cast release anims
+/// `{2, 32, 33, 53, 54}`. Together with [`is_combat_anim`] it is what the **transplant** predicate
+/// (`0x5feae0`) tests on the *currently armed bone-0 clip*: a locomotion request over one of these
+/// does not replace it — the clip moves up onto the key-bone at its live play position
+/// ([`OneShotRoute`]'s two slots, decision 0878). NOT the ReadySpell holds (51/52) — those are
+/// their own set (`0x5fde40`), and a jump over a standing hold really does take the whole body.
 pub(super) fn is_cast_anim(id: u16) -> bool {
     matches!(id, 2 | 32 | 33 | 53 | 54)
 }
@@ -854,8 +840,8 @@ pub(super) fn swing_anim_off(wielded: Option<(u8, u8)>) -> u16 {
     }
 }
 
-/// The draw/stow clip for one weapon slot, by the item's **sheathe-type** byte — the byte-verified
-/// pick (wow-re `sheath-anim-pick.md`, 8 sites, byte-identical): `(1 << (type & 0x1f)) & 0x88` →
+/// The draw/stow clip for one weapon slot, by the item's **sheathe-type** byte — the client's
+/// pick (8 byte-identical sites, `0x611930`–`0x611cc6`): `(1 << (type & 0x1f)) & 0x88` →
 /// HipSheath(90) for types {3, 7}, Sheath(89) for everything else (back-mounts, shields, staves).
 /// The slot's own byte is the *only* input — mainhand, offhand, shield and ranged all run the same
 /// test, each on its own record.
@@ -867,8 +853,7 @@ pub(super) fn sheath_clip(sheath_type: u8) -> u16 {
     }
 }
 
-/// The ranged-handling anims exempt from the `&0x10` force-stow while ranged-drawn —
-/// **byte-verified** (wow-re `ranged-sheath-exempt-autorepeat.md`, the 2026-07-15 §5): the
+/// The ranged-handling anims exempt from the `&0x10` force-stow while ranged-drawn — the
 /// exemption is the predicate `0x5fe180` (sole caller `0x5fe04c`, the **CUR==2 path only**;
 /// index table `0x5fe1a8`, targets `0x5fe1a0`), returning true for exactly these nine ids —
 /// the ranged Load/Hold/Attack family. **ReadyThrown 108 is NOT exempt** and genuinely stows;
@@ -885,8 +870,7 @@ const SHEATH_RANGED_EXEMPT: [u16; 9] = [46, 49, 105, 106, 107, 109, 110, 111, 11
 /// 1. flag `&4` → stow (casts, swim, mount, sit-chair, loot);
 /// 2. mounted → stow — the persistent mounted draw-block (`0x5fdfd9`: the reconcile forces
 ///    state 0 on every recompute while a mount model is attached, so weapons sit at their sheath
-///    points and the manual toggle can never stick — wow-re `sheath-policy.md` §3, VERIFIED;
-///    dismount does NOT restore the pre-mount state);
+///    points and the manual toggle can never stick; dismount does NOT restore the pre-mount state);
 /// 3. flag `&0x10` → stow (emotes, unarmed attacks, sit-ground/kneel, bow/rifle/thrown shots) —
 ///    except the three ranged-handling anims while ranged-drawn;
 /// 4. engaged **or** flag `&0x20` → draw melee (armed attacks, the Ready idles, fishing) — only
@@ -927,20 +911,19 @@ pub(super) fn reconcile_sheath(
 }
 
 /// Whether a **looping base arm** keeps the deterministic HEAD variation instead of rolling a
-/// fresh one — the client's re-zero gate on the arm helper (`0x5fdba0`, wow-re
-/// `loop-replay-fidget.md` §5b): every base (re-)arm carries `variationIdx = −1` (a weighted
-/// roll) **unless** the unit has an auto-attack target, is holding a cast/channel, or the
-/// *outgoing* clip was a combat/cast/ready id — then it is forced to `0` (the head). This is why
-/// a relaxed unit "looks around" on each Stand re-arm while a fighting one holds one steady idle.
-/// The outgoing-id families here approximate the client's four classifier calls
-/// (`0x5fcc10`/`0x5fcbb0`/`0x5fde40`/`0x5fde60`, exact id sets unpinned): the melee swings
-/// (16–19), the ready stances (25–29, the 0111-cited set), and the spell ready/cast poses
-/// (51–54) — engagement and the cast hold carry the main weight regardless (decision 0123).
+/// fresh one — the client's re-zero gate on the arm helper (`0x5fdba0`): every base (re-)arm
+/// carries `variationIdx = −1` (a weighted roll) **unless** the unit has an auto-attack target, is
+/// holding a cast/channel, or the *outgoing* clip was a combat/cast/ready id — then it is forced to
+/// `0` (the head). This is why a relaxed unit "looks around" on each Stand re-arm while a fighting
+/// one holds one steady idle. The outgoing-id families here approximate the client's four
+/// classifier calls (`0x5fcc10`/`0x5fcbb0`/`0x5fde40`/`0x5fde60`, exact id sets unpinned): the
+/// melee swings (16–19), the ready stances (25–29, the 0111-cited set), and the spell ready/cast
+/// poses (51–54) — engagement and the cast hold carry the main weight regardless (decision 0123).
 pub(super) fn arm_forces_head(engaged: bool, casting: bool, outgoing: u16) -> bool {
     engaged || casting || matches!(outgoing, 16..=19 | 25..=29 | 51..=54)
 }
 
-/// The victim wound-flinch id (`0x60ea70`, decision 0111 §5.3 — byte-verified): decided **solely**
+/// The victim wound-flinch id (`0x60ea70`, decision 0111 — byte-verified): decided **solely**
 /// by `(severity, engaged)`. Crit (`HitInfo & 0x80`) → CombatCritical; the victim engaged in
 /// melee (its auto-attack-target GUID set, `[unit+0xc48]`) → CombatWound; else StandWound.
 pub(super) fn wound_anim(hit_info: u32, engaged: bool) -> u16 {
@@ -955,7 +938,7 @@ pub(super) fn wound_anim(hit_info: u32, engaged: bool) -> u16 {
 
 /// Whether the wound overlay covers the **full body** (the client forces op4's key-bone to `-1` =
 /// bone 0) or stays **masked** to the upper-body subtree — the two byte-decoded mechanisms
-/// (decision 0111 §5.2, `0x60eae8` / `0x60eb9a`):
+/// (decision 0111, `0x60eae8` / `0x60eb9a`):
 ///
 /// - **(A), all ids:** the victim's current bone-0 pose is a combat-ready stance {25–29} — a
 ///   weapon-drawn victim standing between its own swings flinches full-body. `base_anim` is the
@@ -963,9 +946,9 @@ pub(super) fn wound_anim(hit_info: u32, engaged: bool) -> u16 {
 ///   `[block0+0xf8]`), so mid-swing the base is the swing — not ready — and the flinch masks.
 /// - **(B), StandWound(8) only:** genuinely stationary — the client's `[+0x118]+0x40 & 0x20200f`
 ///   (move/jump/swim; note the keyboard-turn bits `0x30` are **not** in the mask) — **and not
-///   mounted** (the secondary-blend note's `[unit+0xdc]==0` companion clause; a mounted rider's
-///   flinch never replaces the seat pose, decision 0441). The transport-substate companion is
-///   still a state benilla doesn't model.
+///   mounted** (`[unit+0xdc]==0`, `0x60eb9a`→`0x60ebea`; a mounted rider's flinch never replaces
+///   the seat pose, decision 0441). The transport-substate companion is still a state benilla
+///   doesn't model.
 ///
 /// Everything else is masked: the legs keep the base animation untouched.
 pub(super) fn wound_full_body(id: u16, base_anim: u16, flags: u32, mounted: bool) -> bool {
@@ -1019,12 +1002,12 @@ pub(super) fn ready_anim(main: Option<(u8, u8)>) -> u16 {
     }
 }
 
-/// The Special state a unit is in this frame, if any. Airborne splits three ways (wow-re
-/// `land-anim-height-gate.md` + rf57b §2): FALLINGFAR latched → **Fall** (the 40 loop); else a
-/// **jump** arc (launched upward, `jump_arc`) → Jump (the 37/38 bracket); else a **step-off fall**
-/// → `None` — the base selector's keep-current freeze: the gait keeps playing off the
-/// takeoff-frozen flags/speed until FALLINGFAR latches or the unit lands. Standing with a
-/// transition-able stand-state (sit/sleep/kneel) → Pose; movement suppresses a pose.
+/// The Special state a unit is in this frame, if any. Airborne splits three ways: FALLINGFAR
+/// latched → **Fall** (the 40 loop, `0x602c40`); else a **jump** arc (launched upward, `jump_arc`)
+/// → Jump (the 37/38 bracket); else a **step-off fall** → `None` — the base selector's keep-current
+/// freeze (`0x5fd8e8`): the gait keeps playing off the takeoff-frozen flags/speed until FALLINGFAR
+/// latches or the unit lands. Standing with a transition-able stand-state (sit/sleep/kneel) → Pose;
+/// movement suppresses a pose.
 pub(super) fn current_special(mv: &MovementState, jump_arc: bool) -> Option<Special> {
     if mv.flags & move_flags::FALLING != 0 {
         if mv.flags & move_flags::FALLING_FAR != 0 {
@@ -1041,8 +1024,8 @@ pub(super) fn current_special(mv: &MovementState, jump_arc: bool) -> Option<Spec
     }
 }
 
-/// Where a requested one-shot (a swing or an emote) is routed this play (decision 0087, wow-re
-/// `anim-composition-model.md` §3/§5 at `923ac7bc`).
+/// Where a requested one-shot (a swing or an emote) is routed this play (decision 0087; the route
+/// flag `esi`, `0x5fe6c8..0x5fe74d`).
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum OneShotRoute {
     /// Onto the SpineLow-subtree **masked overlay** ([`AnimClip::upper_node`]): the torso plays the
@@ -1054,18 +1037,18 @@ pub(super) enum OneShotRoute {
     FullBody,
 }
 
-/// The **CLASS_A** membership (wow-re `0x5fed90`) — the maskable-eligible set that gates the whole
+/// The **CLASS_A** membership (`0x5fed90`) — the maskable-eligible set that gates the whole
 /// state-route block; a non-CLASS_A id is always full-body. The load-bearing memberships were
 /// byte-decoded (17/66/68/80 ∈; the 37–45 jump/swim/locomotion band excluded); the patchy interior of
-/// the wide ranges is INFERRED (wow-re note §3 Open) but never load-bearing here — the only ids that
-/// reach [`route_oneshot`] are swings, emotes, and the spell-kit cast anims (32/33/51–54 — wow-re's
-/// own CLASS_A gloss: "swings, emotes, casts"), all squarely inside these ranges.
+/// the wide ranges is inferred and still open, but never load-bearing here — the only ids that
+/// reach [`route_oneshot`] are swings, emotes, and the spell-kit cast anims (32/33/51–54 — CLASS_A
+/// covers swings, emotes and casts), all squarely inside these ranges.
 fn is_class_a(id: u16) -> bool {
     matches!(id,
         2 | 8..=10 | 14..=36 | 46..=49 | 51..=90 | 105..=113 | 117..=118 | 122..=138 | 185..=186 | 195)
 }
 
-/// The **COMBAT** membership (wow-re `0x5fcc10`) — the set whose airborne test can route to the mask
+/// The **COMBAT** membership (`0x5fcc10`) — the set whose airborne test can route to the mask
 /// (a mid-jump swing). Byte-decoded memberships: **17 ∈**, and **66/68/80 ∉** (the emotes never mask
 /// on airborne alone). Every swing id (16–19/85/87/88/117) is in it; no emote id is — and no CAST id
 /// (32/33/51–54) either, which is why a jump-in-place cast routes FULL-BODY and replaces the hang
@@ -1074,7 +1057,7 @@ fn is_combat(id: u16) -> bool {
     matches!(id, 10 | 16..=24 | 30 | 36 | 57..=59 | 85..=88 | 95 | 117 | 118)
 }
 
-/// The **forced-full-body** carve-outs (wow-re §3): Death-class `{1,6,131,132}` (`0x5fda90`) and the
+/// The **forced-full-body** carve-outs: Death-class `{1,6,131,132}` (`0x5fda90`) and the
 /// sit-transition ids `{57,58,118}` (`0x5fec60`) route to bone 0 regardless of state. Kept faithful
 /// though benilla never feeds these through the one-shot path.
 fn is_forced_full_body(id: u16) -> bool {
@@ -1082,7 +1065,7 @@ fn is_forced_full_body(id: u16) -> bool {
 }
 
 /// Route a requested one-shot (swing/emote id) by the unit's **live state**, per play — the client's
-/// `esi` decision `0x5fe6c8..0x5fe74d` (decision 0087, wow-re §3/§5): masked onto the SpineLow overlay
+/// `esi` decision `0x5fe6c8..0x5fe74d` (decision 0087): masked onto the SpineLow overlay
 /// when the lower body is committed — **moving/turning/swimming** (`[9e8] & 0x20003f`), a **non-Stand
 /// stand-state** (seated/sleep/kneel/chair, `standState ≠ 0`), or a **combat** id while **airborne**
 /// (`activeCMovement+0x40 & 0x2000`); **full-body** on bone 0 when standing idle (none of those). The
@@ -1102,14 +1085,14 @@ pub(super) fn route_oneshot(id: u16, flags: u32, stand_state: u8) -> OneShotRout
     }
 }
 
-/// `AnimationData` ids whose playback rate the client scales by movement speed (wow-5875-re `0x5fee80`):
+/// `AnimationData` ids whose playback rate the client scales by movement speed (`0x5fee80`):
 /// the locomotion gaits. An id outside this set plays at rate 1×. The **same** table is the
 /// LOCOMOTION membership the transplant predicates key on ([`is_locomotion`]).
 const RATE_SCALED: &[u16] = &[4, 5, 11, 12, 13, 37, 38, 39, 42, 43, 44, 45, 135, 143, 187];
 
 /// The client's **LOCOMOTION** membership (`0x5fee80` — the very table the rate scaler uses):
 /// what the transplant predicates test as "the clip being *requested* is a base locomotion clip"
-/// (`0x5feae0`/`0x5fe912`, wow-re `oneshot-lifecycle.md` §3a). Note Fall(40) and SwimIdle(41) are
+/// (`0x5feae0`/`0x5fe912`). Note Fall(40) and SwimIdle(41) are
 /// **not** members — a FALLINGFAR latch mid-cast replaces the cast on bone 0 rather than
 /// transplanting it, exactly as the bytes order it.
 pub(super) fn is_locomotion(id: u16) -> bool {
@@ -1136,8 +1119,7 @@ pub(super) fn gait_is_locomotion(state: &MovementState, walk_speed: f32) -> bool
 }
 
 /// The playback rate for a clip given the unit's live speed and its rendered model scale — the
-/// client's `0x5fe2f0` divide, VERIFIED byte-for-byte and §5 cross-checked (wow-5875-re
-/// `anim-rate-divisor.md`, the canonical note; `0x5fe4be..0x5fe550`):
+/// client's `0x5fe2f0` divide (`0x5fe4be..0x5fe550`):
 ///
 /// ```text
 /// 5fe508  call 0x711a20   ; DIVISOR = ‖row0(M+0xbc)‖ · M2Sequence[reqId].moveSpeed
@@ -1162,7 +1144,7 @@ pub(super) fn gait_is_locomotion(state: &MovementState, walk_speed: f32) -> bool
 /// folded the DBC scale in — `entities::attach`), and `+0x9c` is a mount's own
 /// `CreatureDisplayInfo` column, composed under the rider's. Our unit transform and mount-child
 /// transform carry exactly those, so `transform.scale.x × host` reproduces the product (decision
-/// 0910). Two exactness notes from the cross-check:
+/// 0910). Two exactness notes:
 ///
 /// - The client takes the **L2 length of row 0** of the model's world matrix, not an `abs()`. For a
 ///   *uniform* scale — which every unit of ours is (`Vec3::splat`) — the two are identical at any
@@ -1225,7 +1207,7 @@ pub(super) fn unify(
     modes: Option<&crate::net::UnitMoveModes>,
 ) -> MovementState {
     // The flying-spline fact is read through to the live `Spline` on EVERY leg — the client's
-    // selector reads the active CMovement's spline flags at select time (RF-0057 `0x5fd19c`),
+    // selector reads the active CMovement's spline flags at select time (`0x5fd19c`),
     // so a self ride (MovementState leg) and a remote taxi (spline leg) both fly.
     let flying = spline.is_some_and(|s| !s.grounded);
     if let Some(m) = movement {
diff --git a/crates/benilla-app/src/creature_anim/select/tests.rs b/crates/benilla-app/src/creature_anim/select/tests.rs
index 0b88eab4..e0179fc5 100644
--- a/crates/benilla-app/src/creature_anim/select/tests.rs
+++ b/crates/benilla-app/src/creature_anim/select/tests.rs
@@ -126,9 +126,9 @@ fn backward_is_walkbackwards() {
 
 #[test]
 fn swimming_back_forward_strafe_and_idle() {
-    // The RF-0057 swim row (`0x5fd137`…): fwd/back/turn/strafe → 42/45/41/43-44. SwimLeft 43 /
+    // The swim row (`0x5fd137`…): fwd/back/turn/strafe → 42/45/41/43-44. SwimLeft 43 /
     // SwimRight 44 byte-read from AnimationData.dbc; the combined-bit cascade below is the
-    // VERIFIED TU-E order (wow-re `swim-mechanism.md`).
+    // `0x5fd100` order.
     let back = MovementState {
         speed: 4.0,
         flags: move_flags::SWIMMING | move_flags::BACKWARD,
@@ -153,7 +153,7 @@ fn swimming_back_forward_strafe_and_idle() {
         ..Default::default()
     };
     assert_eq!(gait_candidates(&right, 2.5, None, None), &[44, 42, 41, 0]);
-    // The VERIFIED `0x5fd100` cascade (TU-E): TURN > STRAFE > BACKWARD > FORWARD. A strafe
+    // The `0x5fd100` cascade: TURN > STRAFE > BACKWARD > FORWARD. A strafe
     // diagonal plays the side-stroke — strafe outranks both fwd and back…
     let diag = MovementState {
         speed: 4.0,
@@ -198,9 +198,9 @@ fn swimming_back_forward_strafe_and_idle() {
 
 #[test]
 fn airborne_splits_jump_fall_and_gait_freeze() {
-    // The three-way airborne split (wow-re land-anim-height-gate): a jump arc plays the 37/38
-    // bracket; FALLINGFAR latched → the Fall(40) loop (whatever the arc's origin); a step-off
-    // fall below the latch is NO special — the gait freezes through it (keep-current).
+    // The three-way airborne split: a jump arc plays the 37/38 bracket; FALLINGFAR latched → the
+    // Fall(40) loop (`0x602c40`, whatever the arc's origin); a step-off fall below the latch is NO
+    // special — the gait freezes through it (keep-current).
     let s = MovementState {
         flags: move_flags::FORWARD | move_flags::FALLING,
         ..Default::default()
@@ -234,14 +234,14 @@ fn a_pose_yields_to_movement_but_a_jump_landing_plays_out() {
 
 #[test]
 fn jump_sequence_ids() {
-    // The §5/asset-verified sequence: JumpStart 37 → Jump 38 → the landing pick (below).
+    // The asset-verified sequence: JumpStart 37 (`0x60e480`) → Jump 38 → the landing pick (below).
     assert_eq!(Special::Jump.enter(), 37);
     assert_eq!(Special::Jump.loop_id(), 38);
 }
 
 #[test]
 fn jump_land_pick_is_the_0x602c60_rule() {
-    // The land dispatcher `0x602c60` (wow-re rf57b §2): stopped → JumpEnd 39; moving forward or
+    // The land dispatcher `0x602c60`: stopped → JumpEnd 39; moving forward or
     // strafing → JumpLandRun 187; backpedaling or walk-mode → NO landing clip (the recompute drops
     // straight into the gait — a jump-then-hold-S backpedals the instant it touches down, never
     // flashing the forward-run footplant); swimming → no clip (the swim gait takes over).
@@ -388,7 +388,7 @@ fn reconcile_priority_is_stow_over_draw() {
 
 #[test]
 fn reconcile_mounted_is_a_persistent_draw_block() {
-    // Mounted forces stow on every recompute (decision 0441, wow-re sheath-policy §3): it beats
+    // Mounted forces stow on every recompute (decision 0441, `0x5fdfd9`): it beats
     // the engaged draw, the &0x20 draw, and the remote server-byte pull-through alike — a
     // volunteered drawn byte can never re-arm a rider.
     assert_eq!(reconcile_sheath(1, 0, 0, true, true, 1, true), Some(0));
@@ -466,7 +466,7 @@ fn a_degenerate_model_scale_falls_through_to_unit_rate() {
 }
 
 /// The SIGN of `moveSpeed` is load-bearing, and the `abs()` belongs to the scale ALONE (decision
-/// 0912, §5-verified). A backwards gait is authored negative — `RidingKodo.m2` seq 14 is
+/// 0912). A backwards gait is authored negative — `RidingKodo.m2` seq 14 is
 /// WalkBackwards at **−2.5**, byte-read here with `benilla-extract m2seq` — and Guard A is a strict
 /// `divisor > 0`, so the reference leaves that clip at a flat 1×. A model authoring NO
 /// WalkBackwards falls back to forward Walk (+2.5) and *is* speed-scaled. Pinned because
@@ -514,13 +514,13 @@ fn ranged_load_idle_selects_by_weapon_and_ranks_below_ready() {
     )));
 }
 
-/// The drawn ranged idle is claimed by **two tests and no others** ([`ranged_idle_gate`],
-/// byte-verified — wow-re `shooter-stop-law.md` §J6 claim 1): `0x5fd460` reads the ranged sheath
-/// (`cmp [+0xd40],2`) and the local auto-repeat bit (`test ah,0x2` = `0x200`). The any-caster
-/// weapon-visual hold `0x400` is **never tested in that function**; it appears only in
-/// `0x5fc3f0`'s Hold self-loop gates, which are never reached for a bow id. Admitting it here is
-/// the defect the director reported on 2026-08-05 ("they keep aiming like they are going to shoot
-/// at something"): one Serpent Sting sets `0x400`, and no volley end ever clears it.
+/// The drawn ranged idle is claimed by **two tests and no others** ([`ranged_idle_gate`]):
+/// `0x5fd460` reads the ranged sheath (`cmp [+0xd40],2`) and the local auto-repeat bit
+/// (`test ah,0x2` = `0x200`). The any-caster weapon-visual hold `0x400` is **never tested in that
+/// function**; it appears only in `0x5fc3f0`'s Hold self-loop gates, which are never reached for a
+/// bow id. Admitting it here is the defect the director reported on 2026-08-05 ("they keep aiming
+/// like they are going to shoot at something"): one Serpent Sting sets `0x400`, and no volley end
+/// ever clears it.
 #[test]
 fn the_ranged_idle_is_entered_by_the_auto_repeat_bit_and_the_ranged_sheath_alone() {
     // The whole claim of `0x5fd460`: the local `0x200`, with the ranged sheath.
@@ -540,8 +540,8 @@ fn the_ranged_idle_is_entered_by_the_auto_repeat_bit_and_the_ranged_sheath_alone
 /// in the cycle authored as a LOOP and therefore the one that can sit between shots.
 ///
 /// This replaces 0994's `is_ranged_fire` law test, which asserted the opposite mechanism: that a
-/// fire clip's completion must NOT recompute the base. wow-re's §5 refuted the absence proof it
-/// rested on — the completion dispatcher has a second, deferred fire site — so the fire clips
+/// fire clip's completion must NOT recompute the base. The absence proof it rested on is false —
+/// the completion dispatcher has a second, deferred fire site (`0x7075af`) — so the fire clips
 /// recompute like every other one-shot and the promotion below is what holds the pose instead.
 #[test]
 fn each_ranged_load_promotes_to_its_weapon_familys_hold() {
@@ -680,8 +680,8 @@ fn route_land_row8_picks_land_clip_from_touchdown_input() {
 
 #[test]
 fn route_classifier_memberships_are_the_decoded_bytes() {
-    // The load-bearing byte-decoded memberships (wow-re §3): 17 ∈ COMBAT, 66/68/80 ∉ COMBAT;
-    // 17/66/68/80 ∈ CLASS_A. All swing ids are COMBAT; no emote id is.
+    // The load-bearing byte-decoded memberships (`0x5fcc10`, `0x5fed90`): 17 ∈ COMBAT, 66/68/80 ∉
+    // COMBAT; 17/66/68/80 ∈ CLASS_A. All swing ids are COMBAT; no emote id is.
     assert!(is_combat(17));
     for id in [66, 68, 80] {
         assert!(!is_combat(id), "emote {id} must not be COMBAT");
@@ -789,7 +789,7 @@ fn base_arm_head_force_is_the_combat_carveout() {
 
 #[test]
 fn wound_id_by_severity_then_engagement() {
-    // Decision 0111 §5.3: crit outranks engagement; engagement decides 9 vs 8.
+    // Decision 0111: crit outranks engagement; engagement decides 9 vs 8.
     assert_eq!(wound_anim(0x2 | 0x80, false), 10);
     assert_eq!(wound_anim(0x2 | 0x80, true), 10);
     assert_eq!(wound_anim(0x2, true), 9);
@@ -864,7 +864,7 @@ fn swing_ids_cover_both_hands() {
 
 #[test]
 fn a_flying_spline_is_fly_before_backward_and_speed() {
-    // RF-0057 `0x5fd19c`: the fly branch sits between the swim block and the backward test —
+    // `0x5fd19c`: the fly branch sits between the swim block and the backward test —
     // a 32 yd/s taxi plays Fly 135, never Sprint 143 (the ≥11 branch) and never WalkBackwards.
     let fly = MovementState {
         flying: true,
@@ -971,7 +971,7 @@ fn the_granted_modes_fold_into_the_flags_word_on_every_leg_but_our_own() {
     );
 }
 
-/// The prowl creep outranks the WHOLE speed tail (RF-0057 `0x5fd1d3` precedes `0x5fd202`): a
+/// The prowl creep outranks the WHOLE speed tail (`0x5fd1d3` precedes `0x5fd202`): a
 /// stealthed unit plays 119 at a dead crawl and at sprint speed alike — never Walk, Run or Sprint.
 #[test]
 fn the_prowl_creeps_at_every_speed() {
diff --git a/crates/benilla-app/src/creature_anim/sheath.rs b/crates/benilla-app/src/creature_anim/sheath.rs
index 1161911f..def1aa47 100644
--- a/crates/benilla-app/src/creature_anim/sheath.rs
+++ b/crates/benilla-app/src/creature_anim/sheath.rs
@@ -97,9 +97,8 @@ const SHEATH_OVERLAY_WEIGHT: f32 = 8.0;
 /// sender), the attack-start auto-draw, the stand-state stow rider — and `drive_animations` is
 /// the sole executor: the idempotency refusal, the commit to the client-side cache, the
 /// `CMSG_SETSHEATHED` volunteer for the local player (`bFireEvent = 1`), and the ceremony-vs-snap
-/// visual all live in that one place. Byte-verified across all 24 client call sites (wow-re
-/// `sheath-policy.md`): **only the manual `ToggleSheath` passes `bInstant = 0`** — every reactive
-/// trigger and the server-field apply snap.
+/// visual all live in that one place. Across all 24 client call sites, **only the manual
+/// `ToggleSheath` passes `bInstant = 0`** — every reactive trigger and the server-field apply snap.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct SheathRequest {
     pub(crate) entity: Entity,
@@ -111,8 +110,8 @@ pub(crate) struct SheathRequest {
 
 /// The manual `ToggleSheath` **cycle** — the state a Z press asks for next, or `None` where the
 /// ref makes no `SetSheatheState` call at all. Byte-read off `0x5eb642`–`0x5eb6a8` (the four
-/// ToggleSheath call sites tabulated in wow-re `sheath-policy.md` §1; the dispatch is a
-/// `sub 0; je` / `dec; je` / `dec; jne` walk over the committed state `[unit+0xd40]`):
+/// ToggleSheath call sites; the dispatch is a `sub 0; je` / `dec; je` / `dec; jne` walk over the
+/// committed state `[unit+0xd40]`):
 ///
 /// ```text
 /// CUR 0   mainhand or offhand worn -> 1 melee      (0x5eb6a0: push 1, 0, 1)
diff --git a/crates/benilla-app/src/creature_anim/spell_visual.rs b/crates/benilla-app/src/creature_anim/spell_visual.rs
index 26197d15..9da64e24 100644
--- a/crates/benilla-app/src/creature_anim/spell_visual.rs
+++ b/crates/benilla-app/src/creature_anim/spell_visual.rs
@@ -18,7 +18,7 @@ use benilla_protocol::EntityKind;
 
 use crate::aura_visual::AuraProc;
 use crate::entities::ItemDisplays;
-use crate::items::Items;
+use crate::items::{ItemObject, Items};
 use crate::net::{FieldChanged, NetCommands, NetEntity, ObjectStore};
 use benilla_assets::{LockRecover, WorldAssets};
 
@@ -32,8 +32,8 @@ const ERROR_CUBE: &str = "Spells\\ErrorCube.mdx";
 
 /// The reserved [`SpellKitFx`] reap key for the lootable-corpse effect — NOT a spell id (no 5875
 /// spell id is anywhere near `u32::MAX`; the client keys these nodes by attach tag + node flag
-/// instead of a spell, wow-re `loot-corpse-effect.md`). One key suffices: a unit carries at most
-/// one loot effect (the client's flag8 dedup), which [`arm_loot_fx`]'s edge cache guarantees.
+/// instead of a spell — `0x61fa10`). One key suffices: a unit carries at most one loot effect (the
+/// client's flag8 dedup), which [`arm_loot_fx`]'s edge cache guarantees.
 const LOOT_FX_KEY: u32 = u32::MAX;
 
 /// The M2 attachment the three engine-spawned effects we ship hang from — the loot sparkle, the
@@ -41,25 +41,25 @@ const LOOT_FX_KEY: u32 = u32::MAX;
 /// fallback, so a model lacking the point lands on the unit base — exactly the reference's
 /// root fallback (`0x61fb4f`–`0x61fb5f`: `HasAttachment(tag)` on `[unit+0xd8]`, else `0x13`).
 ///
-/// **It is a table value, not an engine-wide constant** (wow-re `mount-composition.md` Q4b.1, §5
-/// 2026-08-03 — the 14-entry `DAT_0080c968`, dumped and joined to the `0x8617b8` name table). It
-/// happens to be `0x13` for indices **4** Loot Art, **5** Unit Level Up and **6** Mount Poof —
-/// our three — and for the PetLoyalty/Meeting-Stone/Reputation rows; it is `0x11` for the two
-/// breath effects and Inebriated Bubbles, and the sentinel `0x25` (spawn refused outright) for
-/// the two footstep sprays. A fourth consumer must read the table row, not reuse this.
+/// **It is a table value, not an engine-wide constant** (the 14-entry `DAT_0080c968`, dumped and
+/// joined to the `0x8617b8` name table). It happens to be `0x13` for indices **4** Loot Art, **5**
+/// Unit Level Up and **6** Mount Poof — our three — and for the PetLoyalty/Meeting-Stone/Reputation
+/// rows; it is `0x11` for the two breath effects and Inebriated Bubbles, and the sentinel `0x25`
+/// (spawn refused outright) for the two footstep sprays. A fourth consumer must read the table row,
+/// not reuse this.
 const HARDCODED_FX_ATTACH: u16 = 0x13;
 
 /// The engine-spawned level-up effect's baked lookup name (the client's string `0x8618e0`,
-/// matched by the boot name-resolve `0x61f5b0`; wow-re `levelup-ding.md` — decision 0305).
+/// matched by the boot name-resolve `0x61f5b0`; decision 0305).
 const LEVEL_UP_EFFECT: &str = "HARDCODED Unit Level Up";
 
 /// The mount transition's cloud — hardcoded index **6**, shipped as `SpellVisualEffectName` row
-/// 1185 → `Spells\DruidMorph_Impact_Base.mdx`, i.e. literally the druid-morph puff (wow-re
-/// `mount-composition.md` Q4b, decision 0927).
+/// 1185 → `Spells\DruidMorph_Impact_Base.mdx`, i.e. literally the druid-morph puff (`0x5ffa50`
+/// pushes index 6 to `0x61fae0`; decision 0927).
 const MOUNT_POOF_EFFECT: &str = "HARDCODED Mount Poof";
 /// The meeting-stone join — hardcoded index **0xc** (`0x861808`), spawned on the local player by
-/// the `SMSG 0x295` status-1 arm with the same `Effect_C` shape as the mount poof (wow-re
-/// `meeting-stone-status.md` §8; decision 1974).
+/// the `SMSG 0x295` status-1 arm `0x4ca2c7` with the same `Effect_C` shape as the mount poof
+/// (decision 1974).
 const MEETING_STONE_JOIN_EFFECT: &str = "HARDCODED Meeting Stone Join";
 
 /// The meeting-stone join visual for `entity`, or `None` without client data or the row —
@@ -102,17 +102,17 @@ pub(crate) enum SpellKitSound {
     /// unit's tracked hold loop, if any (the client kills the effect's sound at `0x614150`).
     StopHold { entity: Entity },
     /// Ring this kit at a bare **world point**, with no owning unit — the kit-sound leg's
-    /// `extra`-override arm (wow-re `kit-sound-leg.md`: "position = `extra` if non-NULL else the
-    /// unit's own position", `60f49e`–`60f4bc`). Its one caller is the missile's ground arrival,
-    /// where `0x61d870` passes the landing point: the bomb's boom belongs where it landed, not at
-    /// the thrower. Always a one-shot — a LOOPING sound here would need a tracked node with an
-    /// owner, and none of the six shipped ground-arrival kits carries one (census below).
+    /// `extra`-override arm (position = `extra` if non-NULL else the unit's own position,
+    /// `60f49e`–`60f4bc`). Its one caller is the missile's ground arrival, where `0x61d870` passes
+    /// the landing point: the bomb's boom belongs where it landed, not at the thrower. Always a
+    /// one-shot — a LOOPING sound here would need a tracked node with an owner, and none of the six
+    /// shipped ground-arrival kits carries one (census below).
     PlayAt { pos: Vec3, kit_sound: u32 },
     /// Stop exactly `kit_sound`'s channels on this unit — the aura-drop reap of a LOOPING
-    /// **state**-kit sound (wow-re `kit-sound-leg.md`: a looping kit sound rides a tracked,
-    /// spell-id-tagged CEffect on the unit's list, and `0x614150` stops it with a 0.15 s fade
-    /// when the aura leaves). Kit-scoped so an unrelated hold loop on the same unit survives;
-    /// a one-shot kit is never tracked, so for it this is a no-op.
+    /// **state**-kit sound (a looping kit sound rides a tracked, spell-id-tagged CEffect on the
+    /// unit's list, and `0x614150` stops it with a 0.15 s fade when the aura leaves). Kit-scoped so
+    /// an unrelated hold loop on the same unit survives; a one-shot kit is never tracked, so for it
+    /// this is a no-op.
     StopKit { entity: Entity, kit_sound: u32 },
 }
 
@@ -121,13 +121,12 @@ pub(crate) enum SpellKitSound {
 /// [`SpellKitSound`]'s two play arms: the reference reaches both through the same leg of the same
 /// one-time node arm pass, one field apart.
 ///
-/// **Exactly once per `PlaySpellVisualKit` call, and always** (wow-re
-/// `spell/scratch/camera-shake-producers.md`, §5 2026-09-02). The primary site is `0x620e11`,
-/// inside the first-created effect node's one-time arm pass `0x620be0`, gated on that node's
-/// flags snapshot carrying bit `0x10` — which `0x60edf0` sets iff `kit+0x38 != 0` and every later
-/// spawner clears via `(flags & ~0x11) | 0x400`, so exactly the FIRST node carries it. `0x60f4e6`
-/// in the kit tail is the **no-node fallback**, gated on "nothing was created" rather than on a
-/// flag. There is no stage gate and no cancel path: a shake outlives its source and plays out.
+/// **Exactly once per `PlaySpellVisualKit` call, and always**. The primary site is `0x620e11`,
+/// inside the first-created effect node's one-time arm pass `0x620be0`, gated on that node's flags
+/// snapshot carrying bit `0x10` — which `0x60edf0` sets iff `kit+0x38 != 0` and every later spawner
+/// clears via `(flags & ~0x11) | 0x400`, so exactly the FIRST node carries it. `0x60f4e6` in the
+/// kit tail is the **no-node fallback**, gated on "nothing was created" rather than on a flag.
+/// There is no stage gate and no cancel path: a shake outlives its source and plays out.
 #[derive(Message, Clone, Copy, Debug)]
 pub(crate) enum SpellKitShake {
     /// Shake at the playing unit's own world position — the ordinary kit play.
@@ -139,12 +138,11 @@ pub(crate) enum SpellKitShake {
 }
 
 /// A persistent effect instance's **lifetime class** — which owner's reap can kill it.
-/// Byte-verified (wow-re `state-kit-aura-lifecycle.md`, §5 2026-07-14): the client's reap walk
-/// `0x614150(spellId, force)` discriminates by node flags — every SPELL_GO / SPELL_FAILED reap
-/// passes `force=0`, which **spares** stage-2 nodes (flag `0x1000`); only the aura-remove path
-/// (`0x612320 → 0x5ff290`) passes `force=1` and takes them. So a cast's GO releasing its precast
-/// never sweeps the same spell's aura-state models (re-eat while the food buff holds: the GO
-/// must not take the bread with it). This enum is that discriminator, named.
+/// The client's reap walk `0x614150(spellId, force)` discriminates by node flags — every SPELL_GO /
+/// SPELL_FAILED reap passes `force=0`, which **spares** stage-2 nodes (flag `0x1000`); only the
+/// aura-remove path (`0x612320 → 0x5ff290`) passes `force=1` and takes them. So a cast's GO
+/// releasing its precast never sweeps the same spell's aura-state models (re-eat while the food
+/// buff holds: the GO must not take the bread with it). This enum is that discriminator, named.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum FxClass {
     /// Cast-lifecycle instances: precast/channel holds (and every self-terminating flash, whose
@@ -157,13 +155,13 @@ pub(crate) enum FxClass {
 
 /// Which of the reference's five kit **stages** an instance's model runs its *animation lifecycle*
 /// as — the discriminator behind `PlaySpellVisualKit`'s per-stage completion-callback table
-/// (`0x60edf0`'s jump table `0x60f4f8`; wow-re `ceffect-anim-lifecycle.md` §2, §5 trio 2026-08-02).
+/// (`0x60edf0`'s jump table `0x60f4f8`).
 ///
 /// Distinct from [`FxClass`], which answers a different question — *whose reap can kill this* (the
 /// `0x614150` force census). The two are not derivable from each other: a channel kit and an
 /// aura-state kit are both stage 2 but reaped by different owners, while a precast and a channel
 /// are both [`FxClass::Hold`] and run *different* animation lifecycles. So the stage rides its own
-/// field, set at each writer from the caller table (`spell-visual-apply.md` §1.6).
+/// field, set at each writer from the stage its caller passes to `0x60edf0`.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum FxStage {
     /// Stages 0/1 (kit push, cast release, impact) — callback `0x5fbf50`: destroy at the first
@@ -186,9 +184,8 @@ pub(crate) enum FxStage {
 /// The id is not decoration. It is half the reference's **same-slot replace** key: every
 /// `CEffect::AddEffect` (`0x61fdd0`) first calls `0x6208e0(owner, rec, tag)`, which walks the
 /// owner's `+0xb4` list and **destroys** every node carrying the same record id at the same tag
-/// (wow-re `kit30-effect-slot.md` §4, VERIFIED `[0x6208e0, 0x62092c]`; decision 2057). Keying on
-/// the path instead would be a different rule — two `SpellVisualEffectName` rows may name one
-/// `.mdx`, and the reference lets those coexist.
+/// (`[0x6208e0, 0x62092c]`; decision 2057). Keying on the path instead would be a different rule —
+/// two `SpellVisualEffectName` rows may name one `.mdx`, and the reference lets those coexist.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub(crate) struct FxSlot {
     /// The M2 attachment id to hang from ([`benilla_formats::KIT_SLOT_TAGS`]), or
@@ -202,9 +199,9 @@ pub(crate) struct FxSlot {
 }
 
 /// A spell-visual kit's attach-point **effect model** edge (kit fields 3–11 →
-/// `SpellVisualEffectName` `.mdx` — decision 0099 phase 3; slot loop byte-pinned in wow-re
-/// `spell-visual-apply.md` §1.3). Written here, consumed by `crate::entities::spell_fx` (the
-/// bone-rider home). One message type so the consumer sees edges **in emission order** — a GO's
+/// `SpellVisualEffectName` `.mdx` — decision 0099 phase 3; the slot loop's tag pushes
+/// `0x60f00d`–`0x60f309`). Written here, consumed by `crate::entities::spell_fx` (the bone-rider
+/// home). One message type so the consumer sees edges **in emission order** — a GO's
 /// reap-then-begin never races.
 #[derive(Message, Clone)]
 pub(crate) enum SpellKitFx {
@@ -283,12 +280,12 @@ pub(crate) struct MissileSpawn {
     /// point, exactly ONE projectile flies at it instead (the client's `0x6e8a50` empty-hit-array
     /// arm — `0x6e8aa2 test al,0x60; setne cl` latches "SOURCE or DEST location present",
     /// `0x6e8bd4` then calls the spawner once, `0x60a5b6`–`0x60a5c9` copies `targets+0x3c` into
-    /// the aim point and `0x60a5ec` forces the owning unit slot to −1; wow-re
-    /// `spell-go-dest-effect.md` §3). This is what a pure ground cast — Flare, a bomb thrown at
-    /// empty dirt — actually shows travelling. Its arrival is [`super::CastEventKind::GroundImpact`],
-    /// never the unit hand-off. Named divergence: the reference latches on `flags & 0x60` and then
-    /// reads the DEST vector regardless, so a SOURCE-only cast aims at whatever the zero-initialised
-    /// DEST slot holds; we carry only a real DEST (`flags & 0x40`) and launch nothing without one.
+    /// the aim point and `0x60a5ec` forces the owning unit slot to −1). This is what a pure ground
+    /// cast — Flare, a bomb thrown at empty dirt — actually shows travelling. Its arrival is
+    /// [`super::CastEventKind::GroundImpact`], never the unit hand-off. Named divergence: the
+    /// reference latches on `flags & 0x60` and then reads the DEST vector regardless, so a
+    /// SOURCE-only cast aims at whatever the zero-initialised DEST slot holds; we carry only a real
+    /// DEST (`flags & 0x40`) and launch nothing without one.
     pub(crate) ground_aim: Option<Vec3>,
     /// The caster's ranged-weapon fallback `SpellVisual` id, resolved at GO time — rides the
     /// flight and returns in [`super::CastEventKind::Impact`] so a basic shot's impact kit
@@ -330,13 +327,15 @@ pub(super) fn load_spell_visuals(mut commands: Commands, assets: Option<Res<Worl
 
 /// The lookup bundle behind the client's `0x60d450` ranged fallback: caster →
 /// equipped-ranged-weapon display → `ItemDisplayInfo` col 10 substitute `SpellVisual` id
-/// (wow-re `throw-ranged-attack-anim.md`, decision 0370).
+/// (decision 0370).
 #[derive(bevy::ecs::system::SystemParam)]
 pub(super) struct WeaponVisualSrc<'w, 's> {
     displays: Option<Res<'w, ItemDisplays>>,
     items: Option<Res<'w, Items>>,
     net: Option<Res<'w, NetCommands>>,
-    units: Query<'w, 's, (Option<&'static NetEntity>, &'static ObjectStore)>,
+    // `Without<ItemObject>`: an item is an object in the index too (2334), and its block's
+    // dwords overlap the unit's indices — a unit read of an item store answers item fields.
+    units: Query<'w, 's, (Option<&'static NetEntity>, &'static ObjectStore), Without<ItemObject>>,
 }
 
 impl WeaponVisualSrc<'_, '_> {
@@ -483,10 +482,10 @@ fn resolve_kit_traced(
 /// The in-flight cast's **strike sound** for the `$TRD` anim event (`0x62faa0`): the handler
 /// resolves the spell's visual to its 16-dword `SpellVisual.dbc` row (`0x60d450` →
 /// `DAT_00c0d738[visualId]`) and plays that row's **dword 14** (`[row+0x38]`) positioned at the
-/// unit — wow-re `sound/scratch/gather-sound-anim-events.md`, decision 0562. Mining's visual 93
-/// carries 1143 "Mining Impact" here (the pick clang — client-side complete, no server state);
-/// the smithing crafts' 395 the same hammer; Herb's 91 carries 1142 but its anim never fires
-/// `$TRD`. No ranged-weapon fallback (`$TRD` rides work/craft anims, never a ranged shot's).
+/// unit (decision 0562). Mining's visual 93 carries 1143 "Mining Impact" here (the pick clang —
+/// client-side complete, no server state); the smithing crafts' 395 the same hammer; Herb's 91
+/// carries 1142 but its anim never fires `$TRD`. No ranged-weapon fallback (`$TRD` rides work/craft
+/// anims, never a ranged shot's).
 pub(crate) fn held_strike_sound(
     spells: &crate::ui_action::Spells,
     visuals: &SpellVisualCatalog,
@@ -566,10 +565,10 @@ struct KitOut<'a, 'w1, 'w2, 'w3, 'w4, 'w5, 'w6, 'w7, 'w8> {
 /// - `effects`: whether the models spawn here at all. `false` for the impact hand-off's STATE
 ///   stage — its models belong to the aura's life and [`arm_aura_state_fx`] owns them.
 /// - `sound`: whether the kit's sound rings — **ungated and positional at the unit, every
-///   stage** (wow-re `kit-sound-leg.md`, decision 0852: `0x60edf0`'s sound leg carries no self
-///   test; the old "state sound is self-only" reading was `0x5ff43e`'s gate on a *different*
-///   aura-apply cue, and `0x5fa6d0` appears nowhere in the kit play). The flag exists for
-///   plays that deliberately hand the sound to another owner (none today).
+///   stage** (decision 0852: `0x60edf0`'s sound leg carries no self test; the old "state sound is
+///   self-only" reading was `0x5ff43e`'s gate on a *different* aura-apply cue, and `0x5fa6d0`
+///   appears nowhere in the kit play). The flag exists for plays that deliberately hand the sound
+///   to another owner (none today).
 #[derive(Clone, Copy)]
 struct KitPlay {
     persistent: bool,
@@ -583,10 +582,9 @@ struct KitPlay {
     ///
     /// Stage 2 is **foreclosed from the play site**: `0x60f387 jne` diverts it around the sole
     /// `0x60f3c5 call 0x5fe2f0` that ever hands a kit's `AnimID` to the animation primitive, and
-    /// its leg leaves the block with `jmp 0x60f3ca` (VERIFIED, wow-re
-    /// `state-kit-anim-and-stun-pose.md` §1). So a state kit neither plays its anim nor reaches
-    /// the `[8,10]` wound test (the half decision 2063 already had): the id is only ever the
-    /// right-hand side of a comparison against what the unit is already playing, and a mismatch
+    /// its leg leaves the block with `jmp 0x60f3ca`. So a state kit neither plays its anim nor
+    /// reaches the `[8,10]` wound test (the half decision 2063 already had): the id is only ever
+    /// the right-hand side of a comparison against what the unit is already playing, and a mismatch
     /// spends itself on a base recompute ([`BaseAnimRecompute`]).
     ///
     /// The other exclusion at `0x60f3a0` — stage 4 with a zero cast time — never reaches this
@@ -696,13 +694,12 @@ struct ImpactPlay {
 /// kit plays its anim + sound only: its **effect models live for the aura's life**, owned by
 /// [`arm_aura_state_fx`]'s slot watcher (a single instance, begun when the aura lands in the
 /// slots and reaped when it leaves — the same packet burst as the GO, so there is no visible
-/// gap). The state sound rings **ungated and positional** (wow-re `kit-sound-leg.md`, decision
-/// 0852: `0x60edf0`'s sound leg has no self test — the old self-only reading belonged to a
-/// different aura-apply cue); the same-frame duplicate against the aura watcher's ADD-edge play
-/// collapses in the sound router. Named approximation: the client's small stage-2 gate
-/// `0x61dc20` (37 B, content unpinned) is not modeled. `weapon_visual` = the CASTER's ranged
-/// fallback visual (already resolved — the caster may be gone by a missile arrival), through
-/// which a basic shot's impact kit resolves.
+/// gap). The state sound rings **ungated and positional** (decision 0852: `0x60edf0`'s sound leg
+/// has no self test — the old self-only reading belonged to a different aura-apply cue); the
+/// same-frame duplicate against the aura watcher's ADD-edge play collapses in the sound router.
+/// Named approximation: the client's small stage-2 gate `0x61dc20` (37 B, content unpinned) is not
+/// modeled. `weapon_visual` = the CASTER's ranged fallback visual (already resolved — the caster
+/// may be gone by a missile arrival), through which a basic shot's impact kit resolves.
 ///
 /// [`ImpactPlay::flinch`] is the **spell impact body twitch** (decision 2058): the client lays
 /// the victim's wound flinch at `severity = 0` beside the impact kit — the instant-hit loop
@@ -779,7 +776,7 @@ pub(super) fn route_cast_visuals(
     visuals: Option<Res<SpellVisuals>>,
     spells: Option<Res<crate::ui_action::Spells>>,
     mut weapon_src: WeaponVisualSrc,
-    units: Query<(Entity, &ObjectStore)>,
+    units: Query<(Entity, &ObjectStore), Without<ItemObject>>,
     holds: Query<&CastHold>,
     mut channel_cache: Local<EntityHashMap<u32>>,
 ) {
@@ -896,14 +893,12 @@ pub(super) fn route_cast_visuals(
                     |s| s.precast,
                     || weapon_src.caster(ev.entity),
                 ) {
-                    // The `0x400` weapon-visual hold, ANY caster (wow-re
-                    // `ranged-sheath-exempt-autorepeat.md` §Q4): a RANGED spell's visual play
-                    // sets it (`0x60d020`, sole caller inside PlaySpellVisual); any other
-                    // visual play clears it (the stale-visual cleanup `0x6ec39e` — re-set only
-                    // when the new visual is ranged). It is what keeps a REMOTE shooter (an NPC
-                    // archer, another hunter) in the drawn Load/Hold idle between shots — the
-                    // local `0x200` ([`super::AutoRepeatArmed`]) never exists off the local
-                    // cast-send.
+                    // The `0x400` weapon-visual hold, ANY caster: a RANGED spell's visual play sets
+                    // it (`0x60d020`, sole caller inside PlaySpellVisual); any other visual play
+                    // clears it (the stale-visual cleanup `0x6ec39e` — re-set only when the new
+                    // visual is ranged). It is what keeps a REMOTE shooter (an NPC archer, another
+                    // hunter) in the drawn Load/Hold idle between shots — the local `0x200`
+                    // ([`super::AutoRepeatArmed`]) never exists off the local cast-send.
                     let ranged = spells
                         .catalog
                         .get(ev.spell_id)
@@ -968,9 +963,9 @@ pub(super) fn route_cast_visuals(
                 });
                 // A ranged-slot spell's GO **re-draws ranged before its cast-kit play** — the
                 // kit-play path's internal snap (`0x60f34c`, gate `Attributes & 0x2`, stages
-                // {0, 4} — wow-re `ranged-sheath-exempt-autorepeat.md` Q3): SPELL_GO makes no
-                // direct SetSheatheState call, but every auto-repeat shot re-snaps state 2
-                // through its play. This is what re-draws a bow an emote lowered mid-volley.
+                // {0, 4}): SPELL_GO makes no direct SetSheatheState call, but every auto-repeat
+                // shot re-snaps state 2 through its play. This is what re-draws a bow an emote
+                // lowered mid-volley.
                 if spells
                     .catalog
                     .get(ev.spell_id)
@@ -984,8 +979,8 @@ pub(super) fn route_cast_visuals(
                 }
                 // The cast kit (the release flash) — a discrete play, effects self-terminating
                 // after their model's own clip span (the client's stage-0/1 completion callback).
-                // For a basic shot this is the fire clip itself (the ranged fallback: Throw's
-                // AttackThrown, Auto Shot's AttackBow — wow-re `throw-ranged-attack-anim.md`).
+                // For a basic shot this is the fire clip itself (the ranged fallback `0x60d450`:
+                // Throw's AttackThrown, Auto Shot's AttackBow).
                 if let Some(kit) = resolve_kit_traced(
                     "cast",
                     ev.entity,
@@ -1104,7 +1099,7 @@ pub(super) fn route_cast_visuals(
         // gate `field 6 == 0` (no missile owns the arrival) ∧ `field 12 ≠ 0`. NOT gated on the
         // hit list (a pure ground cast's lists are empty and the burst still plays — the
         // captured Flamestrike shape); fired here at the GO, never waiting on the dynobj
-        // create (wow-re trap #6: the burst precedes the object).
+        // create (the burst precedes the object).
         if let Some(dest) = go.dest {
             if let Some(stages) = stages {
                 if stages.missile_gate == 0 && stages.area_effect != 0 {
@@ -1295,17 +1290,16 @@ pub(super) fn route_cast_visuals(
 /// still plays the state kit as its short impact-time flash (the client's `0x61dc50` order —
 /// impact, then state), which simply overlaps the persistent instance this watcher owns.
 ///
-/// The trigger and reap are byte-verified (wow-re `state-kit-aura-lifecycle.md`, §5 2026-07-14):
-/// the aura watcher `0x604d00 → 0x6123f0 → 0x5ff350` reads `SpellVisual` field 4 and plays the
-/// kit at stage 2 (`0x5ff4c2: push 2`); the remove path `0x612320 → 0x5ff290` reaps with
-/// `0x614150(spellId, force=1)`. The ADD edge's kit sound rings **ungated and positional** (wow-re
-/// `kit-sound-leg.md`, decision 0852 — its §5 corrected the earlier "SELF-gated" reading: the
-/// `0x5fa6d0` gate at `0x5ff43e` covers only a separate spellRec-driven aura-apply cue, and both
-/// branches fall through to the ungated kit play at `0x5ff4c6`); a looping kit sound is tracked
-/// and stops with the aura ([`SpellKitSound::StopKit`]). The body anim is NOT code-suppressed
-/// (`0x60edf0`'s tail plays `kit+0x08` unconditionally) — this watcher plays effects + sound,
-/// with a **named residual** for a state kit carrying a real anim: that ADD-edge replay isn't
-/// built (no live kit demonstrates it; build it from the verdict when one shows).
+/// The trigger and reap: the aura watcher `0x604d00 → 0x6123f0 → 0x5ff350` reads `SpellVisual`
+/// field 4 and plays the kit at stage 2 (`0x5ff4c2: push 2`); the remove path `0x612320 → 0x5ff290`
+/// reaps with `0x614150(spellId, force=1)`. The ADD edge's kit sound rings **ungated and
+/// positional** (decision 0852 — not SELF-gated: the `0x5fa6d0` gate at `0x5ff43e` covers only a
+/// separate spellRec-driven aura-apply cue, and both branches fall through to the ungated kit play
+/// at `0x5ff4c6`); a looping kit sound is tracked and stops with the aura
+/// ([`SpellKitSound::StopKit`]). The body anim is NOT code-suppressed (`0x60edf0`'s tail plays
+/// `kit+0x08` unconditionally) — this watcher plays effects + sound, with a **named residual** for
+/// a state kit carrying a real anim: that ADD-edge replay isn't built (no live kit demonstrates it;
+/// build it from the reference when one shows).
 ///
 /// `armed` tracks exactly the (unit, spell) pairs this watcher began, so the REMOVE edge never
 /// reaps another owner's persistent instances (a channel hold whose spell also rides an aura).
@@ -1323,8 +1317,8 @@ pub(super) fn route_cast_visuals(
 /// visual is one proc-14 CharProc), so an effects-only test dropped it and the character showed
 /// nothing.
 /// The reference's one aura watch: `UNIT_FIELD_AURA` + `UNIT_FIELD_AURAFLAGS` as a single
-/// registration — `0x604d00`, registered `604226 mov edx,0xa4` / `604221 push 0xd8` for class 3
-/// (wow-re `object-layer.md`): field offset `0xa4` = dword 41 past the 6 OBJECT fields =
+/// registration — `0x604d00`, registered `604226 mov edx,0xa4` / `604221 push 0xd8` for class 3:
+/// field offset `0xa4` = dword 41 past the 6 OBJECT fields =
 /// `FIELD_UNIT_AURA`, length `0xd8` bytes = 54 dwords = the 48 slot ids and the 6 packed flag words.
 const AURA_WATCH_BASE: u16 = benilla_protocol::field::FIELD_UNIT_AURA;
 const AURA_WATCH_SPAN: u16 = 54;
@@ -1337,8 +1331,8 @@ pub(crate) fn arm_aura_state_fx(
     // sight, because a standing aura is a STATE the streamed-in unit wears, not an edge. The
     // unfiltered twin runs exactly once per DBC-resource arrival: a unit that streamed in before
     // `SpellVisuals`/`Spells` landed carries standing auras no edge will re-announce.
-    units: Query<(Entity, &ObjectStore)>,
-    arrived: Query<Entity, Added<ObjectStore>>,
+    units: Query<(Entity, &ObjectStore), Without<ItemObject>>,
+    arrived: Query<Entity, (Added<ObjectStore>, Without<ItemObject>)>,
     mut edges: MessageReader<FieldChanged>,
     visuals: Option<Res<SpellVisuals>>,
     spells: Option<Res<crate::ui_action::Spells>>,
@@ -1456,10 +1450,9 @@ pub(crate) fn arm_aura_state_fx(
     armed.retain(|e, _| units.contains(*e));
 }
 
-/// Arm/reap the **lootable sparkle** on both things that can wear it (wow-re
-/// `loot-corpse-effect.md` + `corpse-decal-and-loot-sparkle.md` §Q2, both §5 cross-checked):
-/// a DEAD unit carrying `UNIT_DYNFLAG_LOOTABLE`, **and a corpse object carrying
-/// `CORPSE_FIELD_DYNAMIC_FLAGS` bit 0** (decision 1723 — a battleground body's insignia). Each
+/// Arm/reap the **lootable sparkle** on both things that can wear it: a DEAD unit carrying
+/// `UNIT_DYNFLAG_LOOTABLE`, **and a corpse object carrying `CORPSE_FIELD_DYNAMIC_FLAGS` bit 0**
+/// (watcher `0x5d6de0`; decision 1723 — a battleground body's insignia). Each
 /// wears the `SpellVisualEffectName` row named
 /// `"HARDCODED Loot Art"` (5875: `Particles\LootFX.mdl` — a golden flare + three star-twinkle
 /// emitters; cadence/size/color/blend all authored in the asset, the client sets none of them)
@@ -1481,7 +1474,7 @@ pub(super) fn arm_loot_fx(
     // `CORPSE_FIELD_DYNAMIC_FLAGS` bit 0 (decision 1723) — different fields at different indices,
     // and a corpse descriptor has no UNIT block to ask at all; the edge's `kind` keeps them apart.
     units: Query<(Entity, &ObjectStore, &crate::net::NetEntity)>,
-    arrived: Query<Entity, Added<ObjectStore>>,
+    arrived: Query<Entity, (Added<ObjectStore>, Without<ItemObject>)>,
     mut edges: MessageReader<FieldChanged>,
     visuals: Option<Res<SpellVisuals>>,
     mut fx: MessageWriter<SpellKitFx>,
@@ -1515,10 +1508,10 @@ pub(super) fn arm_loot_fx(
         due.into_iter().filter_map(|e| units.get(e).ok()).collect()
     };
     for (entity, store, net) in scan {
-        // The **corpse object**'s own sparkle (wow-re `corpse-decal-and-loot-sparkle.md` §Q2, §5
-        // cross-checked): `0x5d6de0` watches `CORPSE_FIELD_DYNAMIC_FLAGS`, and bit 0 rising calls
-        // `0x5d6e30` → the same `"HARDCODED Loot Art"` row at the same attachment `0x13`. Same
-        // asset, same tag — so it shares this body rather than growing a second one.
+        // The **corpse object**'s own sparkle: `0x5d6de0` watches `CORPSE_FIELD_DYNAMIC_FLAGS`, and
+        // bit 0 rising calls `0x5d6e30` → the same `"HARDCODED Loot Art"` row at the same
+        // attachment `0x13`. Same asset, same tag — so it shares this body rather than growing a
+        // second one.
         let lootable = if net.kind == benilla_protocol::EntityKind::Corpse {
             store.0.corpse_lootable()
         } else {
@@ -1537,8 +1530,8 @@ pub(super) fn arm_loot_fx(
                 persistent: true,
                 class: FxClass::Hold,
                 // Not a kit stage at all (this is `SpawnHardcodedEffect`, not
-                // `PlaySpellVisualKit`), but wow-re `loot-corpse-effect.md`'s recorded law for the
-                // loot art is "its own first sequence, LOOPING" — which is precisely what
+                // `PlaySpellVisualKit`), but the reference's law for the loot art is "its own first
+                // sequence, LOOPING" (the `0x600640` re-arm) — which is precisely what
                 // [`FxStage::Relive`] renders, and unlike a bare loop-flag arm it holds even if the
                 // art model's sequence were clamp-flagged.
                 // **The one place the two paths differ, and it is a real divergence.** The unit's
@@ -1573,7 +1566,7 @@ pub(super) fn arm_loot_fx(
     armed.retain(|e| units.contains(*e));
 }
 
-/// The engine-spawned **ding** (decision 0305, byte-verified — wow-re `levelup-ding.md`): a
+/// The engine-spawned **ding** (decision 0305): a
 /// `UNIT_FIELD_LEVEL` **change** on any streamed unit (the client's descriptor change-watcher
 /// `CMirrorHandler 0x6045b0` → `SpawnHardcodedEffect(5)`) spawns [`LEVEL_UP_EFFECT`]
 /// (`Spells\LevelUp\LevelUp.mdl`) at the base attach — the ding visual is DECOUPLED from
@@ -1629,9 +1622,9 @@ pub(super) fn arm_level_up_fx(
 /// boot name-match table to `"HARDCODED Mount Poof"` → row 1185 → `Spells\DruidMorph_Impact_Base`
 /// — the druid-morph cloud, which is exactly the "cloud shapeshift animation" of the report.
 /// Byte-for-byte the same spawn shape as [`arm_level_up_fx`]'s index 5, so it is the same edge
-/// here (wow-re `mount-composition.md` Q4b, §5 2026-08-03; decision 0927).
+/// here (decision 0927).
 ///
-/// The three properties that decide the shape of this arm, all VERIFIED there:
+/// The three properties that decide the shape of this arm:
 /// - **Mount side only.** The build *and the entire allocation* sit behind `5ffa87 je 0x5ffade`
 ///   on the **NEW** field value. `N→0` jumps clean past it: **no poof on dismount.** `0→N` and
 ///   `N→N′` both spawn one.
@@ -1687,15 +1680,15 @@ pub(super) fn arm_mount_poof_fx(
     }
 }
 
-/// The one-slot **pending-morph latch** — the reference's `[unit+0xd54]`, a `SpellRec*` (wow-re
-/// `shapeshift-morph-cloud.md`, §5 trio 2026-08-21): armed by `0x5ff0c0` on every aura **add
-/// AND remove** whose spell passes [`is_morph_spell`]; consumed and cleared by the DISPLAYID
+/// The one-slot **pending-morph latch** — the reference's `[unit+0xd54]`, a `SpellRec*`: armed by
+/// `0x5ff0c0` on every aura **add AND remove** whose spell passes [`is_morph_spell`]; consumed and
+/// cleared by the DISPLAYID
 /// rebuild `0x60abe0`, which — after draining every attached effect and rebuilding the model —
 /// **replays the latched spell's IMPACT kit** (stage 1, `0x6ec1e0` → `[SpellVisual+0xc]` →
 /// `0x60edf0` at `0x60ad67`, cleared at `0x60ad6c`). That replay IS the druid-morph cloud the
 /// player sees, both directions: shift-in's SPELL_GO impact instance dies in the drain and the
 /// replay restores it in sync with the swap; shift-out has no GO at all (the cancel is
-/// client-side, `shapeshift-plaincast-toggle.md`) — the aura-REMOVE handler's last call
+/// client-side, `CancelAura 0x6e7040`) — the aura-REMOVE handler's last call
 /// (`0x6123ad`) re-arms the latch, and the aura fields precede DISPLAYID in the applier's
 /// ascending field order, so the demorph revert replays the same kit. A swap with no latch — a
 /// GM morph, a revive — plays nothing. One entry per unit (a one-slot field); entries die with
@@ -1754,8 +1747,8 @@ pub(super) fn arm_morph_latch(
     latch.0.retain(|e, _| units.contains(*e));
 }
 
-/// The rebuild's **impact-kit replay** — the tail of the reference's `0x60abe0` (wow-re
-/// `shapeshift-morph-cloud.md`): a display swap that finds the latch armed plays the latched
+/// The rebuild's **impact-kit replay** — the tail of the reference's `0x60abe0`: a display swap
+/// that finds the latch armed plays the latched
 /// spell's impact kit as an ordinary discrete kit play ([`KitPlay::DISCRETE`] — full
 /// `PlaySpellVisualKit`: effects, sound, anim, CharProcs) and clears the latch; a swap with no
 /// latch plays nothing. Runs off [`crate::entities::DisplaySwapped`], which the swap writes as
diff --git a/crates/benilla-app/src/creature_anim/spell_visual/tests.rs b/crates/benilla-app/src/creature_anim/spell_visual/tests.rs
index b8aec7fd..e24f1ed9 100644
--- a/crates/benilla-app/src/creature_anim/spell_visual/tests.rs
+++ b/crates/benilla-app/src/creature_anim/spell_visual/tests.rs
@@ -847,12 +847,11 @@ fn missile_spawn_defers_iff_the_cast_kit_animates() {
     );
 }
 
-/// The **location fallback** and its arrival, end to end through the router (wow-re
-/// `spell-go-dest-effect.md` §3 + `spell-visual-lifecycle.md` §Q4): a Speed>0 GO whose hit and
-/// miss lists are empty but which carries a ground point spawns one projectile aimed at the
-/// point — the flight a pure ground cast (Flare, a bomb thrown at empty dirt) shows — and that
-/// projectile's ground arrival rings `SpellVisual` field 13's kit sound **at the landing point**,
-/// not at the caster.
+/// The **location fallback** and its arrival, end to end through the router (`0x6e8a50`'s empty-hit
+/// arm, then the arrival `0x61d870`): a Speed>0 GO whose hit and miss lists are empty but which
+/// carries a ground point spawns one projectile aimed at the point — the flight a pure ground cast
+/// (Flare, a bomb thrown at empty dirt) shows — and that projectile's ground arrival rings
+/// `SpellVisual` field 13's kit sound **at the landing point**, not at the caster.
 #[test]
 fn a_targetless_dest_go_spawns_a_ground_missile_whose_arrival_sounds_at_the_point() {
     const GROUND: u32 = 1543; // Flare's shape: speed>0, dest-targeted, empty hit list
@@ -1009,10 +1008,9 @@ fn a_despawned_subject_never_panics_the_router() {
     }
 }
 
-/// The `0x400` weapon-visual hold (wow-re `ranged-sheath-exempt-autorepeat.md` §Q4): a RANGED
-/// spell's visual play inserts [`RangedHold`] on ANY caster — what keeps a remote shooter in
-/// the drawn Load/Hold idle between shots — and a non-ranged visual play clears it (the
-/// client's stale-visual cleanup `0x6ec39e`).
+/// The `0x400` weapon-visual hold (set by `0x60d020`): a RANGED spell's visual play inserts
+/// [`RangedHold`] on ANY caster — what keeps a remote shooter in the drawn Load/Hold idle between
+/// shots — and a non-ranged visual play clears it (the client's stale-visual cleanup `0x6ec39e`).
 #[test]
 fn ranged_visual_play_arms_the_any_caster_hold_and_a_non_ranged_play_clears_it() {
     let mut app = app();
@@ -1266,8 +1264,8 @@ fn a_kit_with_a_chain_char_proc_asks_for_a_beam_from_both_dispatcher_sites() {
 
 // ── The real-chain shooter pin (bug B307) ────────────────────────────────────────────────────
 //
-// Reported 2026-08-22: "characters don't use reload anim when using autoshot with any ranged
-// weapons (bows/crossbows/guns)" — the shooter fires from a still pose. Every link above this
+// The symptom: on Auto Shot, with any ranged weapon (bow, crossbow, gun), a shooter plays no
+// reload animation and fires from a still pose. Every link above this
 // point is tested on SYNTHETIC tables, and every router test spawns a bare unit with no
 // `NetEntity`/`ObjectStore` — so [`super::WeaponVisualSrc::caster`], the one lookup that turns a
 // PLAYER's equipped ranged weapon into the substitute visual the whole merge hangs on, returns
@@ -1487,8 +1485,8 @@ fn a_real_gun_or_crossbow_shooters_auto_shot_go_plays_attackrifle() {
     }
 }
 
-/// The START arm of the same chain — the **pull**, which is what the report calls the "reload
-/// anim": `SMSG_SPELL_START` for Auto Shot arms `CastHold { anim_id: 105 }` (LoadBow) on a bow
+/// The START arm of the same chain — the **pull**, the reload animation itself:
+/// `SMSG_SPELL_START` for Auto Shot arms `CastHold { anim_id: 105 }` (LoadBow) on a bow
 /// shooter, plus the ranged-slot marks the driver reads ([`RangedHold`], the sheath snap). One
 /// START per auto-repeat activation, so this is the clip that opens a volley.
 #[test]
@@ -1564,12 +1562,12 @@ fn a_shooter_with_no_ranged_weapon_resolves_no_clip_at_all() {
     );
 }
 
-/// **A state kit's animation id is a comparison, never a play** (decision 2085; VERIFIED wow-re
-/// `state-kit-anim-and-stun-pose.md` §1): `0x60edf0`'s tail has exactly one site that hands a
-/// kit's `AnimID` to the animation primitive (`0x60f3c5 call 0x5fe2f0`) and `0x60f387 jne`
-/// diverts stage 2 around it. Both `SpellVisual` field-4 consumers hardcode stage 2 — the aura
-/// watcher and this one, the impact hand-off `0x61dced` — so the state kit's id is only ever the
-/// right-hand side of `0x60f390`'s compare, spent on a base recompute.
+/// **A state kit's animation id is a comparison, never a play** (decision 2085): `0x60edf0`'s tail
+/// has exactly one site that hands a kit's `AnimID` to the animation primitive
+/// (`0x60f3c5 call 0x5fe2f0`) and `0x60f387 jne` diverts stage 2 around it. Both `SpellVisual`
+/// field-4 consumers hardcode stage 2 — the aura watcher and this one, the impact hand-off
+/// `0x61dced` — so the state kit's id is only ever the right-hand side of `0x60f390`'s compare,
+/// spent on a base recompute.
 ///
 /// The subject is the real Silithus chain: a Dredge Striker's **Charge** (22911 → visual 3783)
 /// plays `Knockdown`(121) from impact kit 348, and state kit 349 names `Stun`(14). Before this,
diff --git a/crates/benilla-app/src/creature_anim/twist.rs b/crates/benilla-app/src/creature_anim/twist.rs
index b2397622..c6d8666f 100644
--- a/crates/benilla-app/src/creature_anim/twist.rs
+++ b/crates/benilla-app/src/creature_anim/twist.rs
@@ -1,5 +1,5 @@
-//! The **display-facing counter-twist** — the client's strafe/look body pose (wow-5875-re
-//! `body-facing-pipeline.md` §3, the `0x607ed0` tail → the `0x711f10` bone channels).
+//! The **display-facing counter-twist** — the client's strafe/look body pose (the `0x607ed0` tail →
+//! the `0x711f10` bone channels).
 //!
 //! A unit's rendered root yaw can sit *offset* from its aim — a strafe turns the root toward the
 //! slide (±90° pure, ±45° diagonal) while the aim (camera, server orientation) holds. The client
@@ -71,7 +71,7 @@ pub(crate) fn wrap_pi(angle: f32) -> f32 {
 ///
 /// The binary carries a full-share branch too (`0x6103a0`: local player AND a live click-to-move
 /// action), but `[0xc4d888]` is the click-to-move action type and `0xc` = disabled is its normal
-/// in-world value (VERIFIED, wow-re `b947e5aa`) — so half is the effective share for everyone in
+/// in-world value — so half is the effective share for everyone in
 /// ordinary play, exactly as the director's reference eye called it when the full-share variant
 /// was tried and rejected (decision 0104). Full share would fire only during click-to-move, which
 /// benilla doesn't have.
@@ -84,8 +84,8 @@ fn twist_shares(gap: f32) -> (f32, f32) {
 
 /// The shares actually ARMED on a unit — [`twist_shares`] with the **mounted spine gate** applied.
 ///
-/// The SpineLow channel is armed only on an UNMOUNTED unit: `CGUnit+0xdc == 0` (wow-re
-/// `body-facing-pipeline.md` Q3, alongside the per-model capability bit `+0xd58 & 0x80` we model as
+/// The SpineLow channel is armed only on an UNMOUNTED unit: `CGUnit+0xdc == 0` (in the `0x607ed0`
+/// tail, alongside the per-model capability bit `+0xd58 & 0x80` we model as
 /// "the skeleton authors the key bone"). `+0xdc` is the **mount model** pointer — the same field
 /// `0x614cd0` passes to `0x7106c0` as "model `[+0xd8]` or mount `[+0xdc]`". The HEAD channel
 /// (`+0xd58 & 0x100`) carries no mount gate. So a strafing rider counter-twists its head alone
@@ -98,7 +98,7 @@ fn twist_shares(gap: f32) -> (f32, f32) {
 /// back to its animated base, which is the reference's disarm (`0x711f10(4, 0, 0x80)`); skipping
 /// would freeze our last twist into any frame the clip does not re-key.
 ///
-/// (`+0xdc`'s semantics are flagged INFERRED in that note. It is taken here because the mechanism
+/// (`+0xdc`'s semantics are inferred. It is taken here because the mechanism
 /// PREDICTS the reference: the director reported the mounted over-wobble before this gate was
 /// found, and it is the gate that accounts for it.)
 fn armed_shares(gap: f32, mounted: bool) -> (f32, f32) {
diff --git a/crates/benilla-app/src/cursor.rs b/crates/benilla-app/src/cursor.rs
index 57617f70..6c385139 100644
--- a/crates/benilla-app/src/cursor.rs
+++ b/crates/benilla-app/src/cursor.rs
@@ -1,10 +1,11 @@
 //! 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 wow-re cursor RE's decision tree): 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.
+//! ([`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.
 //!
 //! 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
@@ -16,11 +17,11 @@
 //! 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, wow-re cursor-system.md §1 VERIFIED): 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 and uploads it via the same `SetHardwareCursor` path the mode
-//! art uses. Both platform `drive` fns below check the held payload FIRST, each frame, and fall
+//! **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
@@ -105,8 +106,8 @@ fn box_downsample_32(w: u32, h: u32, rgba: &[u8]) -> Vec<u8> {
 
 /// 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
-/// (byte-verified, wow-re cursor-dragdrop-payload.md: 64×64 → 2×2 box filter → 32×32, alpha
-/// written 0xFF; folded back by 0218). `None` on a missing/undecodable icon.
+/// (`0x523840`: 64×64 → 2×2 box filter → 32×32, alpha written 0xFF; folded back by 0218). `None`
+/// on a missing/undecodable icon.
 fn decode_payload_cursor_rgba(
     assets: &mut benilla_assets::WorldAssets,
     path: &str,
@@ -145,8 +146,8 @@ const CURSOR_STEMS: &[&str] = &[
     "Skin",
     "UnableSkin",
     "Repair", // the repair-mode base cursor (never grayed — the shipped UnableRepair is unreachable)
-    // The data-driven GameObject cursors (decision 0236, wow-re cursor-system §4): a mailbox's Mail,
-    // a lock's Mine / GatherHerbs (grayed out of reach), a picked lock's PickLock (never grayed).
+    // 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).
     "Mail",
     "UnableMail",
     "Mine",
@@ -154,7 +155,7 @@ const CURSOR_STEMS: &[&str] = &[
     "GatherHerbs",
     "UnableGatherHerbs",
     "PickLock",
-    // The spell-targeting pair (wow-re cursor-system.md §5): Cast(2) / UnableCast(22). Cast is
+    // 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).
     "Cast",
@@ -166,9 +167,9 @@ fn cursor_path(stem: &str) -> String {
     format!("Interface\\Cursor\\{stem}.blp")
 }
 
-/// The **displayed** cursor — the client's single sticky mode global `0xbe2c2c` (wow-re
-/// cursor-system.md §1/§7). 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 single sticky mode global `0xbe2c2c`. Read by the
+/// platform drivers instead of [`crate::target::WorldCursor`], which is only ever *one* of its two
+/// writers.
 #[derive(Resource, Clone, Copy, PartialEq, Eq, Debug, Default)]
 pub(crate) struct DisplayedCursor(pub(crate) crate::target::WorldCursor);
 
@@ -197,7 +198,7 @@ pub(crate) struct DisplayedCursor(pub(crate) crate::target::WorldCursor);
 fn drive_displayed_cursor(
     world: Res<crate::target::WorldCursor>,
     over_ui: Res<crate::ui_script::PointerOverUi>,
-    targeting: Res<crate::ui_action::targeting::SpellTargeting>,
+    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.
@@ -229,10 +230,10 @@ fn drive_displayed_cursor(
         return;
     }
 
-    // **The BASE mode is not a constant** (`0xbe2c4c`, wow-re cursor-system.md §7: *"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.
+    // **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
@@ -250,8 +251,8 @@ fn drive_displayed_cursor(
     // reference.
     let repair = script.as_ref().is_some_and(|s| s.repair_mode());
     let base = if repair {
-        // `ShowRepairCursor` parks the base at Repair for as long as it holds (wow-re
-        // repair-machinery.md); it is the explicit modal, so it wins the cell.
+        // `ShowRepairCursor 0x4fbcc0` parks the base at Repair for as long as it holds; it is the
+        // explicit modal, so it wins the cell.
         WorldCursor {
             kind: CursorKind::Repair,
             unable: false,
@@ -614,8 +615,7 @@ 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 (wow-re
-        // `ui/scratch/cinematic-camera-law.md` §3.4). `crate::cinematic` writes
+        // 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
@@ -773,10 +773,10 @@ mod tests {
         app.insert_resource(world);
         app.insert_resource(crate::ui_script::PointerOverUi(over_ui));
         app.insert_resource(DisplayedCursor(standing));
-        let mut targeting = crate::ui_action::SpellTargeting::default();
+        let mut targeting = crate::spell::SpellTargeting::default();
         if armed {
             // Feed Pet's own bare ITEM word.
-            targeting.enter(6991, crate::ui_action::CastCommit::Spell, 0x0010);
+            targeting.enter(6991, crate::spell::CastCommit::Spell, 0x0010);
         }
         app.insert_resource(targeting);
         app.world_mut()
@@ -814,9 +814,9 @@ mod tests {
         );
     }
 
-    /// **The base mode is Cast while a spell awaits its click** (wow-re cursor-system.md §7: 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.
+    /// **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
@@ -913,8 +913,8 @@ mod tests {
         app.insert_resource(CAST_GREY);
         app.insert_resource(crate::ui_script::PointerOverUi(true));
         app.insert_resource(DisplayedCursor(CAST_GREY));
-        let mut targeting = crate::ui_action::SpellTargeting::default();
-        targeting.enter(6991, crate::ui_action::CastCommit::Spell, 0x0010);
+        let mut targeting = crate::spell::SpellTargeting::default();
+        targeting.enter(6991, crate::spell::CastCommit::Spell, 0x0010);
         app.insert_resource(targeting);
         app.world_mut()
             .run_system_once(drive_displayed_cursor)
diff --git a/crates/benilla-app/src/cvars.rs b/crates/benilla-app/src/cvars.rs
index 9ed05053..31a7eced 100644
--- a/crates/benilla-app/src/cvars.rs
+++ b/crates/benilla-app/src/cvars.rs
@@ -15,11 +15,9 @@
 //!   **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.
 //!
-//!   **The reference column has one source**: wow-re's
-//!   `system/cvar/scratch/registered-defaults-census.md` and the regenerable manifest beside it,
-//!   `re/cvar/cvar-register-sites.tsv` — 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 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
@@ -29,9 +27,9 @@
 //!   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`] — which is
-//!   the reference's `CVar::Update 0x63e060`, called for the `gx*` rows from inside `RestartGx`
-//!   (the video window's Okay). A staged value that is never committed is dropped at exit, as
+//!   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
@@ -85,8 +83,8 @@ pub(crate) struct Registered {
     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 `re/cvar/cvar-register-sites.tsv`'s `flags` column
-    /// (2 or 3); a test pins the set.
+    /// ([`Cvars::commit_latched`]). Read off each register site's `flags` argument (2 or 3); a test
+    /// pins the set.
     pub(crate) latched: bool,
 }
 
@@ -110,8 +108,7 @@ impl Registered {
 ///
 /// - **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* (wow-re
-///   `cvar/scratch/graphics-cost-cvar-census.md` §10 — the trap it exists to close).
+///   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
@@ -210,9 +207,16 @@ pub(crate) fn registered_pairs() -> impl Iterator<Item = (&'static str, &'static
 /// 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`]).
+///
+/// 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.
 pub(crate) const REGISTERED: &[Registered] = &[
-    // The realm the session is on — a REAL 1.12 CVar (`0x83f2d0`, persisted, wow-re
-    // `savedvariables-protocol.md`: the client builds its SavedVariables path from it), and a live
+    // 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.
@@ -220,14 +224,14 @@ pub(crate) const REGISTERED: &[Registered] = &[
     //
     // 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. wow-re records a string
+    // 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.
     same("realmName", ""),
-    // The address of the logon server — the reference's own CVar, byte-verified in `WoW.exe`
-    // (the registration's string neighbours are `realmlist.wtf`, "Address of realm list server"
-    // and `us.logon.worldofwarcraft.com:3724`; wow-re `mpq/scratch/startup-order-A.md` row 62).
+    // 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`.
     deviates(
@@ -239,8 +243,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     ),
     // 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; wow-re
-    // `ui/scratch/afk-dnd-command-law.md` §10). Registered default `"1"`.
+    // `[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
@@ -251,7 +255,7 @@ pub(crate) const REGISTERED: &[Registered] = &[
     same("SoundVolume", "1"),
     same("MusicVolume", "0.4"),
     same("AmbienceVolume", "0.6"),
-    // The three 1.12 sound enables (registrar defaults all "1", wow-re B10):
+    // 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.
@@ -259,13 +263,13 @@ pub(crate) const REGISTERED: &[Registered] = &[
     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"`; wow-re
-    // `re/cvar/cvar-register-sites.tsv` row 54) and a real 1.12 checkbox: SoundOptionsFrame.lua's
-    // `ENABLE_ERROR_SPEECH`, index 4, which the master enable greys along with Ambience.
+    // (`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.
     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` sites names it
-    // (`re/cvar/cvar-register-sites.tsv`), and `SoundOptionsFrame.lua` declares seven checkboxes
+    // 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
@@ -275,10 +279,9 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // **`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 (wow-re
-    // `sound/scratch/focus-mute-law.md`, VERIFIED). "0" IS the reference's own behaviour. The knob
-    // is `SoundConfig::background_sound`, which carries the mechanism and the one disclosed
-    // divergence.
+    // `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.
     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
@@ -342,8 +345,7 @@ pub(crate) const REGISTERED: &[Registered] = &[
     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]` (wow-re
-    // `re/cvar/cvar-register-sites.tsv` row 187).
+    // "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
@@ -354,11 +356,10 @@ pub(crate) const REGISTERED: &[Registered] = &[
     //
     // **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 (wow-re
-    // `cvar/scratch/graphics-cost-cvar-census.md` §8 lists `nearclip` among the eleven dead knobs
-    // for exactly that). The camera does not read that global; it reads the record. So the ctor's
+    // 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 the contract §4 names as the classic trap.
+    // 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
@@ -383,8 +384,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // name and there was nothing for it to toggle (decision 1745).
     //
     // Register site `0x6e731d`, default string `"0"`, record `[0xceac34]`, one reader at
-    // `0x6e53d7` (wow-re `cvar/scratch/registered-defaults-census.md`, 1804's §5 round). **This
-    // row used to cite `0x870dc0` as the record; that is the NAME string** — corrected there.
+    // `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
@@ -476,8 +477,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     ),
     // 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 (wow-re
-    // `object-layer/scratch/overhead-name.md`, name string / default string per row, folded into
+    // 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
@@ -491,13 +492,12 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // 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` (wow-re `object-layer/scratch/overhead-name.md`
-    // Q4 point 3 + the registrar table). 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.
+    // `"\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.
     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 (wow-re, VERIFIED — the bitmask is a plain runtime
+    // 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
@@ -530,8 +530,7 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // 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 (wow-re
-    // `cvar/scratch/registered-defaults-census.md`, the §5 round 1804 dispatched).
+    // 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
@@ -543,8 +542,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     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]` (wow-re
-    // `re/cvar/cvar-register-sites.tsv` row 185). The value is **cells visited per chunk**: the
+    // 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
@@ -582,9 +581,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     //
     // 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 (wow-re `object-layer/scratch/combat-log-chat-law.md`
-    // §5.2). They read as the CVar record's **float** (`+0x24`), unlike the periodic gate below,
-    // which reads the int.
+    // 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
@@ -641,9 +639,9 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // `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
-    // the one wow-re had to correct against itself — its first pass read `"3"` off the *next*
-    // registration's default (`minimapZoom`), the `mov ds:` adjacency trap — so it is worth saying
-    // plainly here: stock `/assist` selects and does not swing.
+    // 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.
     same("assistAttack", "0"),
     // ── Mouse-look, per axis: the two CVars whose absence RAISED in the stock window ────────────
     //
@@ -677,26 +675,25 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // **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`, wow-re `cvar/cvar.md`), and so do we (the registry and
+    // 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** (wow-re
-    // `cvar/scratch/registered-defaults-census.md` §, 1804). The reference's default is not a
+    // **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 has **zero readers**: the
-    // slider drives the *operating system's* pointer speed through `SPI_SETMOUSESPEED` (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.
+    // 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.
     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** (wow-re `ui/scratch/follow-camera.md`: "cameraDistanceMax 15.0,
-    // cameraDistanceMaxFactor 1.0") — 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.
+    // 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.
     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
@@ -720,12 +717,11 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // **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 (`re/cvar/cvar-register-sites.tsv`), and two of them are **"1"** — which is
-    // why building them was not cosmetic: benilla was the divergence on those, not the reference.
+    // 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: wow-re
-    // `ui/scratch/camera-cvar-gates.md` §3 (gate `0x510690`, routing `0x50fee0`, release
-    // `0x5107f0`); ours is `player::camera_dynamics::SmartPivot`.
+    // `cameraPivot` `[0xbe10a4]` "1" (`0x50bda3`) — smart pivot. Mechanism: 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
@@ -752,8 +748,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     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:
-    // wow-re `camera-cvar-kernels.md` §2 (the ahead-probe and the five-step staircase) and
-    // `camera-smooth-style.md` §9 (the arm); ours is `player::camera_dynamics::TerrainTilt`.
+    // the ahead-probe and the five-step staircase (`0x50d900`) and the 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
@@ -762,8 +758,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     same("cameraTerrainTiltTimeMin", "3"),
     same("cameraTerrainTiltTimeMax", "10"),
     // `cameraBobbing` `[0xbe10c0]` **"0"** (`0x50b76d`) — head bob, the fourth of the four and the
-    // second that ships OFF. Mechanism: wow-re `camera-cvar-kernels.md` §4 and
-    // `camera-cvar-gates.md` §2; ours is `player::camera_dynamics::HeadBob`.
+    // second that ships OFF. Mechanism: the kernel `0x511920` and its 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
@@ -781,9 +777,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     //
     // **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 (wow-re
-    // `cvar/scratch/registered-defaults-census.md`). It used to concede "behaviour-derived, not
-    // byte-read"; that hedge is retired.
+    // 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.
     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
@@ -797,13 +792,13 @@ pub(crate) const REGISTERED: &[Registered] = &[
     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` — wow-re `object-layer/scratch/chat-bubble.md`:
+    // 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.
     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, which is what the wow-re §5 round behind `text-filter-law.md` settled.
+    // 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.
@@ -818,8 +813,7 @@ pub(crate) const REGISTERED: &[Registered] = &[
     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;
-    // wow-re `system/loadingscreen/scratch/game-tip-of-the-day.md`).
+    // `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"`
@@ -830,8 +824,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     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**: wow-re's census of `0xb4e2bc`
-    // (`lootroll-chat-and-lifecycle.md` §4) has the register site at `0x48fd1c`, name `0x8430a0`,
+    // 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.
@@ -840,23 +834,23 @@ pub(crate) const REGISTERED: &[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"
-    // (§5, wow-re `system/object-layer/scratch/guild-signon-cvar-gate.md`). A stock 1.12 client 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::apply::event`.
+    // condition live on `ui_guild::net::event`.
     same("guildMemberNotify", "0"),
-    // The minimap's two zoom indices (1131). Byte-verified 1.12 CVars, both registered `"3"`
-    // (wow-re, at the `RegisterCVar 0x63db90` argument slot). No options row drives these — the
+    // 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.
     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 —
-    // byte-verified (wow-re `addon-version-gate.md` §1.1: the key appears in Config.wtf exactly
+    // 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.
@@ -867,8 +861,7 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // 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 (wow-re states this from a dozen nodes; `models/scratch/part-additive-combine.md`
-    // §"the gxApi selector" is the decoded compare).
+    // 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
@@ -900,8 +893,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // 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 not
-    // pinned in wow-re, and "1" is what benilla actually ships — the primary window is born at
+    // 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
@@ -1210,9 +1203,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // 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` register `"1"` on zhCN,
-    // `AutoInteract` `"1"` on koKR (wow-re `cvar/scratch/registered-defaults-census.md`, which
-    // caught its own instrument publishing a single arm mid-round). benilla is enUS-only, so `"0"`
+    // 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.
     same("gxWindow", "0").latched(),
@@ -1270,8 +1262,7 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // 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. (wow-re §5 cross-check,
-    // 2026-08-26, `system/console/scratch/gxmultisample-default.md`; decision 1629.)
+    // 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
@@ -1347,8 +1338,8 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // 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`) — wow-re `cvar/scratch/graphics-cost-cvar-census.md` §4, whose §10 table also
-    // lists this row among the twelve the reference install's `Config.wtf` moves off its default.
+    // `0x8685ac`), and this row is among the twelve the reference install's `Config.wtf` moves off
+    // its default.
     deviates(
         "weatherDensity",
         "3",
@@ -1369,15 +1360,15 @@ pub(crate) const REGISTERED: &[Registered] = &[
     // (`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. wow-re `ffxeffects/scratch/whole-frame-grade-verdict.md` §(a) for the
-    // curve and `ui/scratch/video-options-verbs.md` §3 for the verbs.
+    // 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`, whose `SStrPrintf(buf, 0x10, "%f", …)` is
-    // six decimals — so the row that Restore Defaults produces is `"1.000000"`, and a default
+    // 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
@@ -1728,14 +1719,26 @@ impl Cvars {
         true
     }
 
-    /// **The latch boundary** — the reference's `CVar::Update 0x63e060`: every staged value
-    /// becomes the applied one, fires, persists, and reaches the mirror. Returns how many moved.
-    /// Called for the `gx*` rows from `RestartGx` ([`crate::video`]); a row nothing ever commits
-    /// (`SoundBufferSize`, `gxApi`) holds its stage until exit, and loses it there, as the
-    /// reference does.
+    /// **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.
+    ///
+    /// **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.
     pub(crate) fn commit_latched(&mut self) -> usize {
         let mut moved = 0;
         for row in &mut self.rows {
+            if !row.name.starts_with("gx") {
+                continue;
+            }
             let Some(staged) = row.pending.take() else {
                 continue;
             };
@@ -2773,7 +2776,7 @@ mod tests {
             d["showLootSpam"] != 0.0,
             LootConfig::default().show_loot_spam
         );
-        // …and the one row that ships a feature OFF, byte-read at `0x5e24c7` (§5).
+        // …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
@@ -3674,7 +3677,7 @@ mod tests {
             .init_resource::<PaneRate>()
             .init_resource::<crate::ui_guild::GuildMemberNotify>()
             .init_resource::<crate::ui_trade::BlockTrades>()
-            .init_resource::<crate::ui_action::AutoSelfCast>()
+            .init_resource::<crate::spell::AutoSelfCast>()
             .init_resource::<crate::perf::FpsJournalSetting>()
             .init_resource::<crate::text_filter::TextFilterSwitches>()
             .init_resource::<crate::game_tip::GameTipSetting>()
@@ -3709,7 +3712,7 @@ mod tests {
             app.add_observer(crate::target::on_cvar);
         },
         |app| {
-            app.add_observer(crate::ui_action::on_cvar);
+            app.add_observer(crate::spell::cast_target::on_cvar);
         },
         |app| {
             app.add_observer(crate::combat_text::on_cvar);
@@ -3958,7 +3961,7 @@ mod tests {
     ///
     /// **`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. wow-re records `"Last realm connected to"` beside the registration, but
+    /// 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.
@@ -4076,6 +4079,15 @@ mod tests {
         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).
+        assert_eq!(cvars.set("SoundBufferSize", "200"), SetOutcome::Staged);
+        assert_eq!(cvars.commit_latched(), 0);
+        assert_eq!(cvars.get("SoundBufferSize"), Some("100"));
+        assert_eq!(
+            cvars.row("SoundBufferSize").unwrap().pending.as_deref(),
+            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"));
@@ -4311,10 +4323,10 @@ mod tests {
         }
     }
 
-    /// The eight rows the reference latches that benilla registers, and no other — read off
-    /// `re/cvar/cvar-register-sites.tsv` (`flags` 2 or 3): the sound-init row, and the `gx*`
-    /// block `RestartGx` commits. `trilinear`/`anisotropic`/`farclip` register with `flags = 1`
-    /// there and apply live, so they are deliberately not here.
+    /// 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.
     #[test]
     fn the_latched_rows_are_the_references_own() {
         let mut latched: Vec<&str> = REGISTERED
diff --git a/crates/benilla-app/src/death.rs b/crates/benilla-app/src/death/mod.rs
similarity index 84%
rename from crates/benilla-app/src/death.rs
rename to crates/benilla-app/src/death/mod.rs
index 91d16481..62fcf1d1 100644
--- a/crates/benilla-app/src/death.rs
+++ b/crates/benilla-app/src/death/mod.rs
@@ -14,10 +14,12 @@ use bevy::prelude::*;
 use benilla_assets::coords::wow_to_bevy;
 use benilla_ui::script::{DeathAction, DeathUiState, ScriptValue, UiScript};
 
-use crate::net::{ClientCommand, GuidIndex, NetCommands, ObjectStore, SelfGuid, SelfPlayer};
+use crate::net::{ClientCommand, NetCommands, ObjectStore, Objects, SelfGuid, SelfPlayer};
 use crate::ui_action::Spells;
 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.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub(crate) struct CorpsePoint {
@@ -63,6 +65,12 @@ pub(crate) struct DeathNet {
     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.
+    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 —
@@ -89,9 +97,9 @@ impl DeathNet {
     /// 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 (wow-re
-    /// `interact-dead-fork-and-npc-service-ladder.md` §C). vmangos also *pushes* the question as
-    /// `SMSG_SPIRIT_HEALER_CONFIRM` off its gossip route, and benilla honours both roads in.
+    /// (`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).
@@ -104,8 +112,8 @@ impl DeathNet {
 /// 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 (wow-re
-/// death-ui.md §1), so a `ReloadUI` neither re-arms the release window nor loses it, while the
+/// 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.
@@ -115,8 +123,8 @@ struct DeathFeedState {
     /// arms and clears the release window. `None` before a world session's first snapshot.
     mirror: Option<(u64, bool, bool)>,
     /// **World-scoped.** `Time::elapsed_secs_f64` at the death edge — the anchor of the
-    /// client-side release window (byte-VERIFIED, wow-re death-ui.md §1: the wire carries only
-    /// the PLAYER_FIELD_BYTES timer BIT; the client arms `now + 360000 ms` at its own
+    /// 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.
@@ -136,12 +144,12 @@ struct DeathAnnounced {
     /// CORPSE_IN_RANGE / CORPSE_OUT_OF_RANGE / CORPSE_IN_INSTANCE edge memory (decision 0308 §5).
     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, death-ui.md §4), so the
+    /// range events through the latch (the client's own re-announce, `0x4962d0`), so the
     /// RECOVER_CORPSE popup re-shows with the new delay.
     reclaim_generation: u32,
-    /// The pending resurrect offer has been announced to the UI (`RESURRECT_REQUEST` fired) —
-    /// held back while a player-caster's name is still resolving through the name cache.
-    offer_announced: bool,
+    /// 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.
+    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
@@ -163,14 +171,14 @@ enum CorpseRange {
 /// mirror both sides know; never on the wire.
 const RELEASE_WINDOW_SECS: f64 = 360.0;
 
-/// The corpse-range dialog radius — byte-VERIFIED **40.0 yd, inclusive** (wow-re death-ui.md §3:
-/// the client compares d² ≤ `[0xb4e2ac]` = 1600.0 per frame against the corpse-QUERY cache, never
+/// 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.
 const CORPSE_RANGE_SQ: f32 = 40.0 * 40.0;
 
-/// The spirit-healer dialog range — byte-VERIFIED (wow-re death-ui.md §7: CheckSpiritHealerDist
+/// The spirit-healer dialog range (CheckSpiritHealerDist
 /// compares d² ≤ `[0xc4c28c]` = 30.864 = 5.5556², the service interaction range). Squared yards.
 const SPIRIT_HEALER_RANGE_SQ: f32 = 5.5556 * 5.5556;
 
@@ -189,7 +197,9 @@ fn feed_death(
     mut feed: ResMut<DeathFeedState>,
     names: Res<crate::names::NameCache>,
     net: Res<NetCommands>,
-    index: Res<GuidIndex>,
+    // 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>>,
     status: Res<crate::net::NetStatus>,
@@ -231,10 +241,9 @@ fn feed_death(
         .reclaim_at
         .map_or(0.0, |at| (at - now).max(0.0) as f32);
     let spirit_healer_in_range = death_net.spirit_healer.is_some_and(|npc| {
-        index
-            .0
-            .get(&npc)
-            .and_then(|&e| transforms.get(e).ok())
+        objects
+            .entity(npc)
+            .and_then(|e| transforms.get(e).ok())
             .is_some_and(|t| {
                 t.translation.distance_squared(self_t.translation) <= SPIRIT_HEALER_RANGE_SQ
             })
@@ -259,7 +268,7 @@ fn feed_death(
         // `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.
-        self_res_label: resolve_self_res(&store.0, &items, spells.as_deref(), &net)
+        self_res_label: resolve_self_res(&store.0, &objects, &items, spells.as_deref(), &net)
             .map(|r| r.label().to_owned()),
     });
 
@@ -288,7 +297,7 @@ fn feed_death(
             // 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 (wow-re death-ui.md §5's watcher), and post-res the player→corpse
+            // 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.
             let _ = net.0.send(ClientCommand::CorpseQuery);
@@ -321,22 +330,16 @@ fn feed_death(
     }
 
     // ── The offer/confirm announcements (edge-fired, name-gated) ───────────────────────────────
-    match &death_net.resurrect {
-        Some(offer) if !memo.offer_announced => {
-            // 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").
-            let name = if offer.name.is_empty() {
-                names.resolve(offer.caster, &net).map(str::to_owned)
-            } else {
-                Some(offer.name.clone())
-            };
-            if let Some(name) = name {
-                memo.offer_announced = true;
-                script.fire_event("RESURRECT_REQUEST", vec![ScriptValue::Str(name)]);
-            }
+    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").
+        if offer.name.is_empty() {
+            names.resolve(offer.caster, &net).map(str::to_owned)
+        } else {
+            Some(offer.name.clone())
         }
-        None => memo.offer_announced = false,
-        _ => {}
+    }) {
+        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.
@@ -375,7 +378,7 @@ fn feed_death(
     // coord transform, so the Bevy-space compare is the yard compare.
     let range = if ghost {
         death_net.corpse.map(|cp| {
-            // The client's own law (death-ui.md §3-4): within 40 yd (inclusive) of the QUERY
+            // 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).
             let on_display_map = map
@@ -417,7 +420,7 @@ fn feed_death(
 const SPELL_EFFECT_SELF_RESURRECT: u32 = 94;
 
 /// What a `UseSoulstone()` would spend right now — the client's own two-legged fork
-/// (`Script::UseSoulstone 0x48ad70`, wow-re death-ui.md §10.4), resolved app-side because neither
+/// (`Script::UseSoulstone 0x48ad70`), resolved app-side because neither
 /// leg's inputs (the spell catalog, the item cache) are bound in the script VM.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) enum SelfRes {
@@ -448,7 +451,7 @@ impl SelfRes {
 }
 
 /// **`HasSoulstone()`'s whole answer**, and `UseSoulstone()`'s routing — one resolver, because the
-/// binary is one predicate the two bindings share (wow-re death-ui.md §10.1/§10.4).
+/// binary is one predicate the two bindings share (`0x48ac80`, `0x48ad70`).
 ///
 /// Three gates in the client's own order, and the order is the performance story as much as the
 /// fidelity one:
@@ -470,6 +473,7 @@ impl SelfRes {
 /// the lookup fires answers within a frame or two and the next resolve sees it.
 fn resolve_self_res(
     store: &benilla_protocol::ObjectFields,
+    objects: &Objects,
     items: &crate::items::Items,
     spells: Option<&Spells>,
     commands: &NetCommands,
@@ -483,12 +487,15 @@ fn resolve_self_res(
             .map_or_else(|| "UNKNOWN".to_owned(), |d| d.name.clone());
         return Some(SelfRes::Spell { spell, label });
     }
-    // Collected first, then judged: the template lookup needs `items` mutably (it is ask-once,
-    // so a miss fires the query) while the walk holds it immutably — `has_key`'s own idiom.
-    let slots =
-        crate::ui_items::collect_inventory(store, items, crate::ui_items::InventoryScope::DEFAULT);
+    // 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,
+        crate::ui_items::InventoryScope::DEFAULT,
+    );
     slots.into_iter().find_map(|(bag_index, slot, guid)| {
-        let entry = items.object(guid)?.object_entry()?;
+        let entry = objects.object(guid)?.object_entry()?;
         let t = items.template(entry, guid, commands)?;
         let self_res = t.spells.iter().any(|sp| {
             sp.trigger == 0
@@ -516,9 +523,9 @@ fn resolve_self_res(
 /// `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` (wow-re `ui/scratch/death-ui.md` §9). 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.
+/// `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
@@ -538,9 +545,9 @@ fn sickness_duration(level: u32, get: &dyn Fn(&str) -> Option<String>) -> Option
     ))
 }
 
-/// Drive the ghost-world look (decision 0308 §7, all byte-VERIFIED): the FFXDeath screen pass
-/// gates on `PLAYER_FLAGS_GHOST` — instant on release, instant off at resurrect (wow-re
-/// death-pass.md: the flag's CMirrorHandler watcher is the single driver of the FFX pass swap,
+/// 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).
 fn drive_death_look(
@@ -580,11 +587,11 @@ fn drain_death(
     script: Option<NonSendMut<UiScript>>,
     mut death_net: ResMut<DeathNet>,
     net: Res<NetCommands>,
-    targeting: crate::ui_action::cast_target::CastTargeting,
-    mut ladder: crate::ui_action::CastLadder,
+    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's own census (wow-re
-    // `bind-confirm-law.md`: 290 ← UseSoulstone · UseInventoryItem · UseAction · UseContainerItem),
+    // 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.
     mut gate: crate::ui_bind_confirm::BindGate,
 ) {
@@ -628,6 +635,7 @@ fn drain_death(
                 match store.as_ref().and_then(|store| {
                     resolve_self_res(
                         store,
+                        &ladder.objects,
                         &ladder.items,
                         ladder.spells.as_deref(),
                         &ladder.commands,
@@ -713,6 +721,7 @@ pub(crate) struct DeathPlugin;
 
 impl Plugin for DeathPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<DeathNet>()
             .init_resource::<DeathFeedState>()
             .add_systems(
@@ -729,11 +738,86 @@ impl Plugin for DeathPlugin {
     }
 }
 
+/// 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.
+fn offer_announcement(
+    memo: &mut DeathAnnounced,
+    death_net: &DeathNet,
+    dead_or_ghost: bool,
+    name_of: impl FnOnce(&ResurrectOffer) -> Option<String>,
+) -> Option<String> {
+    if !dead_or_ghost || memo.offer_generation == death_net.resurrect_generation {
+        return None;
+    }
+    let name = name_of(death_net.resurrect.as_ref()?)?;
+    memo.offer_generation = death_net.resurrect_generation;
+    Some(name)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use bevy::ecs::system::RunSystemOnce;
 
+    fn offer(caster: u64, name: &str) -> ResurrectOffer {
+        ResurrectOffer {
+            caster,
+            name: name.into(),
+            sickness: false,
+            has_timer: true,
+        }
+    }
+
+    /// **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).
+    #[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_generation += 1;
+        assert_eq!(
+            offer_announcement(&mut memo, &net, true, name).as_deref(),
+            Some("Pone")
+        );
+        assert_eq!(
+            offer_announcement(&mut memo, &net, true, name),
+            None,
+            "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.
+        let mut reloaded = DeathAnnounced::default();
+        assert_eq!(offer_announcement(&mut reloaded, &net, false, name), None);
+
+        // Dead again, a new priest offers.
+        net.resurrect = Some(offer(2, "Ptwo"));
+        net.resurrect_generation += 1;
+        assert_eq!(
+            offer_announcement(&mut memo, &net, true, name).as_deref(),
+            Some("Ptwo"),
+            "the second offer announces"
+        );
+
+        // A name still resolving holds the announcement without consuming it.
+        net.resurrect_generation += 1;
+        assert_eq!(offer_announcement(&mut memo, &net, true, |_| None), None);
+        assert_eq!(
+            offer_announcement(&mut memo, &net, true, name).as_deref(),
+            Some("Ptwo")
+        );
+    }
+
     /// **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
@@ -829,7 +913,7 @@ mod self_res_tests {
         }
     }
 
-    /// **The dead gate comes first** (wow-re death-ui.md §10.1): `HasSoulstone` reads
+    /// **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
@@ -838,6 +922,9 @@ mod self_res_tests {
     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).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let spells = catalog([(REINCARNATION, named("Reincarnation", [94, 0, 0]))]);
 
         let alive = ObjectFields::from_pairs(&[
@@ -846,7 +933,7 @@ mod self_res_tests {
             (F_SELF_RES, REINCARNATION),
         ]);
         assert_eq!(
-            resolve_self_res(&alive, &items, Some(&spells), &net),
+            resolve_self_res(&alive, &objects, &items, Some(&spells), &net),
             None,
             "alive with a self-res owed: nil"
         );
@@ -859,7 +946,7 @@ mod self_res_tests {
             (F_SELF_RES, REINCARNATION),
         ]);
         assert_eq!(
-            resolve_self_res(&ghost, &items, Some(&spells), &net),
+            resolve_self_res(&ghost, &objects, &items, Some(&spells), &net),
             None,
             "a released ghost still holds the field, and still answers nil"
         );
@@ -870,7 +957,7 @@ mod self_res_tests {
             (F_SELF_RES, REINCARNATION),
         ]);
         assert_eq!(
-            resolve_self_res(&dead, &items, Some(&spells), &net),
+            resolve_self_res(&dead, &objects, &items, Some(&spells), &net),
             Some(SelfRes::Spell {
                 spell: REINCARNATION,
                 label: "Reincarnation".into(),
@@ -878,17 +965,19 @@ mod self_res_tests {
         );
     }
 
-    /// An id the catalog cannot resolve is **"UNKNOWN"**, not nil (§10.1's fourth exit). Hiding
+    /// 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.
     #[test]
     fn an_unresolvable_spell_id_reads_unknown_not_nil() {
         let (net, _rx) = commands();
         let items = Items::default();
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let dead =
             ObjectFields::from_pairs(&[(F_MAXHEALTH, 4000), (F_HEALTH, 0), (F_SELF_RES, 999_999)]);
         for spells in [None, Some(catalog([]))] {
             assert_eq!(
-                resolve_self_res(&dead, &items, spells.as_ref(), &net),
+                resolve_self_res(&dead, &objects, &items, spells.as_ref(), &net),
                 Some(SelfRes::Spell {
                     spell: 999_999,
                     label: "UNKNOWN".into(),
@@ -898,7 +987,7 @@ mod self_res_tests {
         }
     }
 
-    /// **A zero field is not the nil path** (§10.3): the client falls through to the carried
+    /// **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),
@@ -907,6 +996,7 @@ mod self_res_tests {
     fn a_zero_field_falls_through_to_a_carried_item() {
         let (net, _rx) = commands();
         let mut items = Items::default();
+        let mut objs = crate::ui_items::TestObjects::new();
 
         let item = |name: &str, spells: Vec<ItemSpellEntry>| ItemInfo {
             spells,
@@ -929,8 +1019,9 @@ mod self_res_tests {
             Some(item("Ankh of Reincarnation", vec![block(3026, 0)])),
         );
         for (guid, entry) in [(0xA0_u64, 10_u32), (0xA1, 11), (0xA2, 12)] {
-            items.insert_object(guid, ObjectFields::from_pairs(&[(3, entry)]));
+            objs.spawn(guid, ObjectFields::from_pairs(&[(3, entry)]));
         }
+        let objects = objs.get();
         let spells = catalog([
             (
                 3026,
@@ -948,7 +1039,7 @@ mod self_res_tests {
         }
         let dead = ObjectFields::from_pairs(&pairs);
 
-        match resolve_self_res(&dead, &items, Some(&spells), &net) {
+        match resolve_self_res(&dead, &objects, &items, Some(&spells), &net) {
             Some(SelfRes::Item { entry, label, .. }) => {
                 assert_eq!(
                     entry, 12,
@@ -961,6 +1052,9 @@ mod self_res_tests {
 
         // Take it away and the answer is nil again — not "UNKNOWN", which is the spell leg's.
         let bare = ObjectFields::from_pairs(&[(F_MAXHEALTH, 4000), (F_HEALTH, 0)]);
-        assert_eq!(resolve_self_res(&bare, &items, Some(&spells), &net), None);
+        assert_eq!(
+            resolve_self_res(&bare, &objects, &items, Some(&spells), &net),
+            None
+        );
     }
 }
diff --git a/crates/benilla-app/src/net/apply/death.rs b/crates/benilla-app/src/death/net.rs
similarity index 61%
rename from crates/benilla-app/src/net/apply/death.rs
rename to crates/benilla-app/src/death/net.rs
index dffb184f..09d7fd33 100644
--- a/crates/benilla-app/src/net/apply/death.rs
+++ b/crates/benilla-app/src/death/net.rs
@@ -1,24 +1,114 @@
-//! Death-arc arm bodies for [`super::apply_net_updates`]'s dispatch match (decision 0308) — 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. Each `pub(super)` fn here is
-//! exactly one arm's body — except the two corpse-guid latches, which ride the object-lifecycle
-//! arms; the match at the call site stays the dispatcher, one call per arm.
+//! 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.
 
-use benilla_protocol::{EntityKind, MoveMode, ObjectFields};
+use benilla_protocol::{EntityKind, MoveMode, ObjectFields, SessionEvent, SessionEventKind};
 use bevy::prelude::*;
 
-use crate::death::{CorpsePoint, DeathNet, ResurrectOffer};
-use crate::net::MoveModeMessage;
+use super::{CorpsePoint, DeathNet, ResurrectOffer};
+use crate::net::{MoveModeMessage, NetHandlerApp, SelfGuid};
 
-use super::super::SelfGuid;
+/// Register the death handlers — called from [`super::DeathPlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::CorpseQuery, on_corpse_query)
+        .net_handler(K::CorpseReclaimDelay, on_corpse_reclaim_delay)
+        .net_handler(K::ResurrectRequest, on_resurrect_request)
+        .net_handler(K::SpiritHealerConfirm, on_spirit_healer_confirm)
+        .net_handler(K::DurabilityDamageDeath, on_durability_damage_death)
+        .net_handler(K::MoveMode, on_move_mode)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_corpse_query(In(ev): In<SessionEvent>, mut death_net: ResMut<DeathNet>) {
+    if let SessionEvent::CorpseQuery {
+        found,
+        display_map,
+        position,
+        corpse_map,
+    } = ev
+    {
+        corpse_query(found, display_map, position, corpse_map, &mut death_net);
+    }
+}
+
+fn on_corpse_reclaim_delay(
+    In(ev): In<SessionEvent>,
+    mut death_net: ResMut<DeathNet>,
+    real_clock: Res<Time<Real>>,
+) {
+    if let SessionEvent::CorpseReclaimDelay { delay_ms } = ev {
+        corpse_reclaim_delay(delay_ms, real_clock.elapsed_secs_f64(), &mut death_net);
+    }
+}
+
+fn on_resurrect_request(In(ev): In<SessionEvent>, mut death_net: ResMut<DeathNet>) {
+    if let SessionEvent::ResurrectRequest {
+        caster,
+        name,
+        sickness,
+        has_timer,
+    } = ev
+    {
+        resurrect_request(caster, name, sickness, has_timer, &mut death_net);
+    }
+}
+
+fn on_spirit_healer_confirm(In(ev): In<SessionEvent>, mut death_net: ResMut<DeathNet>) {
+    if let SessionEvent::SpiritHealerConfirm { npc } = ev {
+        spirit_healer_confirm(npc, &mut death_net);
+    }
+}
+
+fn on_durability_damage_death(In(ev): In<SessionEvent>, mut log: ResMut<crate::ui_chat::ChatLog>) {
+    if let SessionEvent::DurabilityDamageDeath = ev {
+        durability_damage_death(&mut log);
+    }
+}
+
+fn on_move_mode(
+    In(ev): In<SessionEvent>,
+    self_guid: Res<SelfGuid>,
+    mut death_net: ResMut<DeathNet>,
+    mut out: MessageWriter<MoveModeMessage>,
+) {
+    if let SessionEvent::MoveMode {
+        guid,
+        counter,
+        mode,
+        apply,
+    } = ev
+    {
+        move_mode(
+            guid,
+            counter,
+            mode,
+            apply,
+            &self_guid,
+            &mut death_net,
+            &mut out,
+        );
+    }
+}
+
+/// 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).
+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** (wow-re `corpse-click-and-reclaim.md`, §5 cross-checked): the reference's
+/// **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
@@ -26,7 +116,7 @@ use super::super::SelfGuid;
 /// 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.
-pub(super) fn note_corpse(
+pub(crate) fn note_corpse(
     guid: u64,
     kind: EntityKind,
     fields: &ObjectFields,
@@ -49,7 +139,7 @@ pub(super) fn note_corpse(
 /// 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.
-pub(super) fn recheck_corpse(
+pub(crate) fn recheck_corpse(
     guid: u64,
     fields: &ObjectFields,
     self_guid: &SelfGuid,
@@ -77,7 +167,7 @@ pub(super) 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.
-pub(super) fn forget_corpse(guid: u64, death_net: &mut DeathNet) {
+pub(crate) fn forget_corpse(guid: u64, death_net: &mut DeathNet) {
     if death_net.corpse_guid == Some(guid) {
         death_net.corpse_guid = None;
     }
@@ -85,7 +175,7 @@ pub(super) fn forget_corpse(guid: u64, death_net: &mut DeathNet) {
 
 /// `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.
-pub(super) fn corpse_query(
+fn corpse_query(
     found: bool,
     display_map: i32,
     position: [f32; 3],
@@ -101,15 +191,15 @@ pub(super) 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 (wow-re death-ui.md §4), so the feed re-announces on the
+/// corpse-range events through its latch (`0x4962d0`), so the feed re-announces on the
 /// generation bump.
-pub(super) fn corpse_reclaim_delay(delay_ms: u32, now_secs: f64, death_net: &mut DeathNet) {
+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.
-pub(super) fn resurrect_request(
+fn resurrect_request(
     caster: u64,
     name: String,
     sickness: bool,
@@ -122,13 +212,14 @@ pub(super) fn resurrect_request(
         sickness,
         has_timer,
     });
+    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.
-pub(super) fn spirit_healer_confirm(npc: u64, death_net: &mut DeathNet) {
+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).
@@ -143,7 +234,7 @@ pub(super) fn spirit_healer_confirm(npc: u64, death_net: &mut DeathNet) {
 /// 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.
-pub(super) fn durability_damage_death(log: &mut crate::ui_chat::ChatLog) {
+fn durability_damage_death(log: &mut crate::ui_chat::ChatLog) {
     log.push_combat(crate::ui_chat::combat::PendingCombat {
         kind: crate::ui_chat::ChatEventKind::CombatMiscInfo,
         family: crate::ui_chat::combat::DURABILITYDAMAGE_DEATH,
@@ -161,7 +252,7 @@ pub(super) fn durability_damage_death(log: &mut crate::ui_chat::ChatLog) {
 /// 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`]).
-pub(super) fn move_mode(
+fn move_mode(
     guid: u64,
     counter: u32,
     mode: MoveMode,
diff --git a/crates/benilla-app/src/debug_panel/inspect.rs b/crates/benilla-app/src/debug_panel/inspect.rs
index 41a3b096..07c62921 100644
--- a/crates/benilla-app/src/debug_panel/inspect.rs
+++ b/crates/benilla-app/src/debug_panel/inspect.rs
@@ -166,10 +166,11 @@ pub(super) struct InspectStores<'w, 's> {
     /// 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).
     hovered_go: Res<'w, crate::target::HoveredObject>,
-    /// The GameObject **animation** readout (decision 1151) — what the §243 arm 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.
+    /// 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.
     go_anims: Query<
         'w,
         's,
@@ -353,7 +354,7 @@ pub(super) fn inspect_ui(
     // (the same ask-once path the unit frames use).
     let name_line = net_entity
         .and_then(|p| guids.get(p).ok())
-        .and_then(|g| names.resolve(g.0, &net_commands))
+        .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
@@ -405,7 +406,7 @@ pub(super) fn inspect_ui(
             } else {
                 format!(" [{}]", named.join("|"))
             };
-            // The **interact gate**, stated rather than inferred (wow-re cursor-system §4a): the
+            // 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
@@ -702,10 +703,11 @@ pub(super) fn inspect_ui(
         }
     });
     // 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 §243 arm is playing,
-    // whether it is a transient one (a transition motion / a Custom block — something the §2d
-    // completion advance 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.
+    // `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.
     let anim_line = anim_line.or_else(|| {
         let (id, transient, repeat) = net_entity
             .and_then(|p| go_anims.get(p).ok())
diff --git a/crates/benilla-app/src/debug_panel/mod.rs b/crates/benilla-app/src/debug_panel/mod.rs
index 3b991233..15c68877 100644
--- a/crates/benilla-app/src/debug_panel/mod.rs
+++ b/crates/benilla-app/src/debug_panel/mod.rs
@@ -487,8 +487,8 @@ fn debug_panel_ui(
                             // UVs (phase 3 — waterfalls).
                             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`, wow-re
-                            // `m2-alpha-combine-cull`). Non-zero as soon as a voidwalker/banshee/
+                            // 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
@@ -517,7 +517,19 @@ fn debug_panel_ui(
                             // room vanishes, click, and the exact seed evidence + per-portal verdicts land
                             // in a file.
                             if ui.button("dump WMO cull trace").clicked() {
-                                cull_probe.dump_requested = true;
+                                // 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.
+                                match crate::local_state::diagnostics_dir() {
+                                    Some(dir) => {
+                                        cull_probe.dump_to = Some(dir.join("wmo-cull-trace.txt"));
+                                    }
+                                    None => bevy::log::warn!(
+                                        "wmo cull trace: no benilla-config folder to write into \
+                                         (hermetic run) — set WOW_CULLDUMP=<path> to name one"
+                                    ),
+                                }
                             }
                         });
 
diff --git a/crates/benilla-app/src/doodad_events.rs b/crates/benilla-app/src/doodad_events.rs
index ea8c4bd3..ed4cc502 100644
--- a/crates/benilla-app/src/doodad_events.rs
+++ b/crates/benilla-app/src/doodad_events.rs
@@ -17,7 +17,7 @@
 //! 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 (wow-re `doodad-anim-host.md` §1/§4a/§5b — see the gate below). So
+//! 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.
 //!
@@ -29,9 +29,7 @@
 //! 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** (wow-re
-//! `terrain/scratch/doodad-emitter-drawset-gate.md` §1b/§1c/§2b, `animation/scratch/
-//! doodad-anim-host.md` §5b, `object-layer/scratch/unit-anim-visibility-gate.md` §4).
+//! fires and it never takes one of the emitter pool's 32 entries**.
 //!
 //! 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
@@ -45,12 +43,11 @@
 //!
 //! **"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 (`sound/scratch/doodad-sound-emitters.md`
-//! §9): turning away stops the *marker firing*, never the entry. The prose this module and
+//! 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 `doodad-anim-host.md` §5b's *linkage* as "loaded" when the note 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 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
@@ -62,12 +59,12 @@
 //! `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`
-//! (wow-re `doodad-sound-emitters.md` §3, corrected 2026-09-07 by the §5 round 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.
+//! (`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.
 
 use bevy::prelude::*;
 
diff --git a/crates/benilla-app/src/entities.rs b/crates/benilla-app/src/entities.rs
index 8fe30a91..598ececc 100644
--- a/crates/benilla-app/src/entities.rs
+++ b/crates/benilla-app/src/entities.rs
@@ -148,17 +148,16 @@ pub(crate) use equipment::ItemModelKind;
 pub(crate) const ATTACH_OVERHEAD: u16 = 18;
 
 /// Its mounted twin (`PlayerNameMounted`, id 29) — preferred while a mount model is attached
-/// (VERIFIED wow-re `questgiver-marker.md`/`nameplate-vkey.md`; decision 0441 P2), authored on
-/// the RIDER's own model (character models seat it higher so overhead content clears the
-/// mount's bulk). A rider model without it falls back to 18 like the client.
+/// (`0x6074c0`, `0x608640`; decision 0441 P2), authored on the RIDER's own model (character
+/// models seat it higher so overhead content clears the mount's bulk). A rider model without it
+/// falls back to 18 like the client.
 pub(crate) const ATTACH_OVERHEAD_MOUNTED: u16 = 29;
 
 /// The overhead attachment slot to use for a unit **right now** — the reference's own pick inside
-/// the marker attach `0x6074c0` (VERIFIED, wow-re object-layer `questgiver-marker.md` Q2), always
-/// queried on the unit's *body* model: slot **29** when a mount MODEL exists (`unit+0xdc != 0` —
-/// our [`mount::MountChild`]) *and* the body authors 29, else slot **18**; `None` when the body
-/// authors neither, which is the reference's "marker created but never parented" (invisible) and
-/// this file's bbox fallback for the overhead readers.
+/// the marker attach `0x6074c0`, always queried on the unit's *body* model: slot **29** when a
+/// mount MODEL exists (`unit+0xdc != 0` — our [`mount::MountChild`]) *and* the body authors 29,
+/// else slot **18**; `None` when the body authors neither, which is the reference's "marker
+/// created but never parented" (invisible) and this file's bbox fallback for the overhead readers.
 ///
 /// **The pick is LIVE, not a bake.** `0x6074c0`'s five call sites include `0x5ffae7` inside
 /// `0x5ffa50` — the `UNIT_FIELD_MOUNTDISPLAYID` field-watch handler (`0x604330 mov edx,0x1fc; mov
@@ -186,12 +185,11 @@ const OVERHEAD_FALLBACK_FACTOR: f32 = 1.25;
 /// The reference's two overhead heights are two different mechanisms, and benilla had recorded them
 /// as one. The overhead NAME (and the floating combat text, and the V-plate) takes `0x608640`: the
 /// live posed PlayerName attachment, which tracks the pose. The chat bubble takes `0x711a20`, which
-/// wow-re's cross-check followed into the model layer and found reading the **MD20 header image** —
-/// file bytes, no bone matrix in the call tree — returning the Stand sequence CAaBox's Z extent,
-/// and the client caches it in the bubble at `+0x354` on a parity guard so it is queried **once per
-/// chat line**. The recorded claim that the two calls were equivalent ("both are the head-region
-/// attachment height, model-scaled", INFERRED) is refuted: they differ precisely on
-/// animated-vs-static.
+/// reads the **MD20 header image** — file bytes, no bone matrix in the call tree — returning the
+/// Stand sequence CAaBox's Z extent, and the client caches it in the bubble at `+0x354` on a parity
+/// guard so it is queried **once per chat line**. The recorded claim that the two calls were
+/// equivalent ("both are the head-region attachment height, model-scaled", INFERRED) is refuted:
+/// they differ precisely on animated-vs-static.
 ///
 /// So this is a constant per display, stamped at attach and never re-read — which is also why the
 /// bubble's height cannot acquire a pose-clock bug of the kind 1398 had to remove from the anchor.
@@ -233,8 +231,7 @@ pub(crate) struct OverheadFallback(pub(crate) f32);
 /// the UI glue), so its global IS its local. A `PostUpdate` caller ([`crate::nameplates`], which
 /// moved there for this very lag) is unaffected: after propagation the two are the same value.
 /// The client's **per-attachment z-bias** fallback table, `[0x862708]` — 37 floats, attachment
-/// ids `0..=0x24`, read as `[0x862708 + 4·id]` under a `0 ≤ id < 0x25` guard (wow-re
-/// `object-layer/scratch/anim-event-position-law.md` §4, §5-cross-checked). It is consulted only
+/// ids `0..=0x24`, read as `[0x862708 + 4·id]` under a `0 ≤ id < 0x25` guard. It is consulted only
 /// when the model does **not** carry the attachment the caller asked for: the sound then plays at
 /// the unit's own position raised by this much, which is how a headless or attachment-less model
 /// still puts a mouth sound somewhere plausible instead of at its feet.
@@ -256,9 +253,8 @@ const ATTACH_Z_BIAS: [f32; 37] = [
 /// Two anim-event arms reach it and they are the reason this exists as a named function rather
 /// than inline at either: the emote voice `$CSD` asks for **17** (`0x623c3a push 0x11`), and a
 /// **whiffed** melee swing's `$CSS` asks for **1** (`0x624bdd`). Both are emphatically *not* the
-/// fired event's own point, which is what makes them the exceptions in
-/// `anim-event-position-law.md` §3's table — a player model's six head-mounted `$CSD` records do
-/// not decide where that sound plays.
+/// fired event's own point, which is what makes them the exceptions among the unit's anim-event
+/// arms — a player model's six head-mounted `$CSD` records do not decide where that sound plays.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct AttachPoints<'w, 's> {
     anchors: Query<'w, 's, &'static BoneAttach>,
@@ -430,13 +426,13 @@ impl Creatures {
     }
 
     /// A built display's booth framing — the model's own **authored cameras**, which is what both
-    /// booth families frame through: `camera` for the round portrait (`cameraLookup[0]`, wow-re
-    /// portrait-render §4) and `pane_camera` for a `<PlayerModel>` body pane (raw index 1, wow-re
-    /// `modelframe-camera-law.md`). Each carries the fallback data its own path needs when the model
-    /// has no such camera: the heuristic anchors (head bone / neck height / footprint) for the
-    /// portrait, the bbox centre for the pane's fixed camera. All model-local pre-scale. `None`
-    /// while the display's model is still loading (the booth's part source — the attach-spawned
-    /// children — won't exist yet either).
+    /// booth families frame through: `camera` for the round portrait (`cameraLookup[0]`,
+    /// `0x713540`) and `pane_camera` for a `<PlayerModel>` body pane (raw index 1, `0x505890`).
+    /// Each carries the fallback data its own path needs when the model has no such camera: the
+    /// heuristic anchors (head bone / neck height / footprint) for the portrait, the bbox centre
+    /// for the pane's fixed camera. All model-local pre-scale. `None` while the display's model is
+    /// still loading (the booth's part source — the attach-spawned children — won't exist yet
+    /// either).
     pub(crate) fn display_anchors(
         &self,
         display_id: u32,
@@ -499,10 +495,10 @@ impl Creatures {
     }
 
     /// A built display's **booth rig** — what the portrait booth needs to pose a fresh instance at
-    /// Stand like the ref bake (wow-re portrait-render §4 D2: a throwaway instance armed to
-    /// Stand/seq-0, not the unit's live world pose): the rest skeleton, the shared inverse bind
-    /// poses, and the animation surface. `None` while the model is still loading; a boneless /
-    /// WMO-display model yields an empty skeleton (the booth then bakes the static bind pose).
+    /// Stand like the ref bake (`0x524f60`: a throwaway instance armed to Stand/seq-0, not the
+    /// unit's live world pose): the rest skeleton, the shared inverse bind poses, and the animation
+    /// surface. `None` while the model is still loading; a boneless / WMO-display model yields an
+    /// empty skeleton (the booth then bakes the static bind pose).
     pub(crate) fn display_rig(&self, display_id: u32) -> Option<DisplayRig<'_>> {
         let dm = self.models.get(&display_id)?;
         dm.parts.as_ref()?; // not yet built
@@ -824,7 +820,7 @@ impl Plugin for EntitiesPlugin {
         .add_message::<live_display::DisplaySwapped>()
         .add_systems(Startup, setup_entities.after(AssetSet::Open))
         // The map-scope teardown (`world_map::MapChange`): drop every display/material dedup
-        // so a map's assets actually die with it — the #bugs teleport leak.
+        // so a map's assets actually die with it — the teleport leak.
         .add_systems(Update, (evict_display_caches, scope_entity_art))
         // Every streamed unit's collision height, the frame after `apply_net_updates` spawns it
         // (that stage's Commands are what create the entity, so this cannot be earlier). Its
@@ -959,7 +955,7 @@ impl Plugin for EntitiesPlugin {
                 .after(benilla_world::rig_anim::finalize_rig_worlds)
                 .after(benilla_world::particles::buffer::begin_effect_frame),
         )
-        // Terrain conform (decisions 0482/0486, the byte law of wow-re `terrain-tilt.md`):
+        // Terrain conform (decisions 0482/0486, the byte law of `0x614cd0` → `0x7106c0`):
         // reads each flagged unit's Update-final transform, writes its conform node's
         // local rotation — before propagation so the composite's globals carry this
         // frame's stance.
@@ -1021,7 +1017,7 @@ impl Plugin for EntitiesPlugin {
             Update,
             (
                 // The display's own base alpha first (the reference's DISPLAYID-watcher leg
-                // of the same recompute, `base-render-alpha.md` §5 — no aura needed), so a
+                // `0x604990` of the same recompute `0x60d180` — no aura needed), so a
                 // same-frame aura edge retargets from the already-updated base.
                 crate::aura_visual::refresh_base_alpha,
                 crate::aura_visual::drain_aura_procs,
@@ -1261,7 +1257,7 @@ fn update_display_models(
     // its model builds with no wire entity (the screens run pre-world, where no NetEntity carries it).
     glue_preview: Option<Res<crate::portrait::GluePreview>>,
     char_create: Option<Res<CharCreate>>,
-    // The stable pane's want (wow-re `stable-master-window.md` §7.1): a stabled pet is a row in the
+    // The stable pane's want (`SetPetStablePaperdoll` `0x4cb870`): a stabled pet is a row in the
     // server's character-pet cache and a `CreatureDisplayInfo` id — there is no wire entity to
     // carry it, so the booth's own selection is the want.
     stable_booth: Option<Res<crate::portrait::StableBooth>>,
@@ -1507,10 +1503,10 @@ fn update_display_models(
 }
 
 /// Compose a unit part's **animated material alpha** into the render-alpha `MeshTag` field — the
-/// unit-lane half of the verified per-batch combine `A = instanceAlpha × colourAlpha × weight`
-/// (wow-re `m2-alpha-combine-cull.md`). The `A ≤ 0` *cull* is already the single `Visibility`
-/// authority's (`debug_panel::apply_model_visibility` ANDs `mat_factor > 0`); this is the partial
-/// factor, the dimming half, which only a `MeshTag` write can express.
+/// unit-lane half of the per-batch combine `A = instanceAlpha × colourAlpha × weight`
+/// (`0x707680`). The `A ≤ 0` *cull* is already the single `Visibility` authority's
+/// (`debug_panel::apply_model_visibility` ANDs `mat_factor > 0`); this is the partial factor, the
+/// dimming half, which only a `MeshTag` write can express.
 ///
 /// A fourth alpha writer is exactly what decision 0066's protocol forbids, so this is not one: it
 /// writes **only** the alpha field, through [`benilla_world::mesh_tag::with_alpha`] (the probe slot,
@@ -1776,7 +1772,7 @@ mod overhead_slot_tests {
     }
 
     /// `0x6074c0`'s pick and only it: 29 is *preferred*, never required, and never taken by an
-    /// unmounted unit. So a character body — which authors both (wow-re's table: HumanMale 18 at
+    /// unmounted unit. So a character body — which authors both (the shipped HumanMale: 18 at
     /// z 2.2123, 29 at z 1.4029) — moves 18 ↔ 29 across a mount, a creature that authors only 18
     /// (AncientOfLore, Kobold) stays at 18 whether or not it is mounted, and a body authoring
     /// neither anchors nothing: the reference creates the marker and never parents it.
@@ -1813,8 +1809,7 @@ mod overhead_slot_tests {
 mod attach_bias_tests {
     use super::*;
 
-    /// The z-bias fallback table `[0x862708]`, verbatim (wow-re
-    /// `object-layer/scratch/anim-event-position-law.md` §4). It is 37 f32 for attachment ids
+    /// The z-bias fallback table `[0x862708]`, verbatim. It is 37 f32 for attachment ids
     /// `0..=0x24`, and the two ids that actually reach it through an animation event are the
     /// emote voice's **17** and a whiffed swing's **1** — so those two are what a drift here
     /// would move, on exactly the models that lack the attachment.
diff --git a/crates/benilla-app/src/entities/attach/char_skin.rs b/crates/benilla-app/src/entities/attach/char_skin.rs
index 7f88c80d..face5511 100644
--- a/crates/benilla-app/src/entities/attach/char_skin.rs
+++ b/crates/benilla-app/src/entities/attach/char_skin.rs
@@ -60,8 +60,8 @@ pub(super) fn resolve_char_look(
     // swaps a Player-kind entity can wear any display — a druid's bear form is a plain creature
     // model (no look; Monster skins instead), and a GM-morphed player wearing a humanoid NPC
     // display wears ITS CreatureDisplayInfoExtra appearance. The reference's own race/gender
-    // getters answer from the display's cached row with the descriptor as fallback (wow-re
-    // `w2d2.md`, the `0x60c690` getter family) — exactly this order: display appearance first,
+    // getters answer from the display's cached row with the descriptor as fallback (the
+    // `0x60c690` getter family) — exactly this order: display appearance first,
     // wire appearance only for a character body that carries none.
     let d = dm?;
     if let Some(npc) = d.npc_appearance.as_ref() {
@@ -194,7 +194,7 @@ pub(super) fn resolve_worn_equip(
 }
 
 /// The worn geoset selectors for a set of equipment display ids (decisions 0074/1864's B1–B8
-/// branches + the cloak group + the helm's RF-0083 hide-mask row pair): each non-zero display
+/// branches + the cloak group + the helm's `0x4799a0` hide-mask row pair): each non-zero display
 /// resolves its ItemDisplayInfo row's geoset columns, and B3's forearm gate comes off the same
 /// composite plan the atlas blits. One helper for the world attach path and the glue-preview
 /// builder — the selection law can't fork (decision 0465).
diff --git a/crates/benilla-app/src/entities/attach/dress.rs b/crates/benilla-app/src/entities/attach/dress.rs
index 93a7399f..9626d034 100644
--- a/crates/benilla-app/src/entities/attach/dress.rs
+++ b/crates/benilla-app/src/entities/attach/dress.rs
@@ -5,10 +5,10 @@
 //! The reference never rebuilds a character to change what it is wearing: the composite atlas is
 //! re-blitted into the component's own 256² target and the geosets are re-selected on the SAME
 //! `CM2Model` (its per-instance visibility array `+0x98`, whose only writer is the character
-//! compositor — wow-re `charactermodel.md` "Assembly orchestration" + `models.md`
-//! §"geoset-visibility-default"). Its attachments — held items, the helm, the shoulders and
-//! everything hanging off them — are never touched by that path at all. This module is the half of
-//! that law that concerns one part: which materials it draws through, and how it is born.
+//! compositor `0x477520`, through `0x7110d0`). Its attachments — held items, the helm, the
+//! shoulders and everything hanging off them — are never touched by that path at all. This module
+//! is the half of that law that concerns one part: which materials it draws through, and how it is
+//! born.
 
 use benilla_formats::CharSkinSlot;
 use bevy::camera::primitives::Aabb;
@@ -391,9 +391,9 @@ pub(super) fn spawn_part(
             blend: part.blend,
         },
         // The portrait booth mirrors this part ([`crate::portrait`]): both mesh twins — the booth
-        // poses the skinned twin at Stand on its own throwaway skeleton (the ref bake, wow-re §4
-        // D2), falling back to the static bind-pose twin for a boneless model — + the steady
-        // exterior material (not the appear-fade/interior variant the child may wear now).
+        // poses the skinned twin at Stand on its own throwaway skeleton (the ref bake `0x524f60`),
+        // falling back to the static bind-pose twin for a boneless model — + the steady exterior
+        // material (not the appear-fade/interior variant the child may wear now).
         crate::portrait::PortraitPart {
             static_mesh: part.mesh.clone(),
             skinned_mesh: part.skinned_mesh.clone(),
@@ -432,11 +432,11 @@ pub(super) fn spawn_part(
         // object, never per batch, so the view cull belongs to the body ROOT's election
         // (`exterior_cull`, 1270) and `NoFrustumCulling` keeps Bevy's per-part test out of its
         // way. (0648 originally justified the marker as "the reference never view-culls entities
-        // at all", off a ≈1e7 render-bounds reading; wow-re's `outdoor-object-pass-election.md`
-        // refuted that 2026-08-13 — those fields are a position cache, and units ARE
-        // frustum/horizon/room-elected per frame. Decision 1473 records the correction and owns
-        // the outdoor half of the election.) Bevy's bind-pose `Aabb` is the wrong stand-in for
-        // picking (the duel flag plants itself 9 yd below it) and is stomped anyway by
+        // at all", off a ≈1e7 render-bounds reading, but those fields are a position cache
+        // (`0x6717d0`), and units ARE frustum/horizon/room-elected per frame (`0x683340`).
+        // Decision 1473 records the correction and owns the outdoor half of the election.)
+        // Bevy's bind-pose `Aabb` is the wrong stand-in for picking (the duel flag plants itself
+        // 9 yd below it) and is stomped anyway by
         // `calculate_bounds` on any `Mesh3d` change. So the `Aabb` beside the marker serves ONE
         // master: the mouseover picker (`target/hover.rs`) — the armed idle's authored CAaBox
         // when it has one, else the bind box, read from the part's build-time bound (decision
@@ -456,8 +456,8 @@ pub(super) fn spawn_part(
     }
     // M2 parts can light off a WMO room they stand in: a `MeshTag` + the classifier pick the law by
     // location (0354). Anchored at the unit root so every part shares the root's verdict, and the
-    // indoor LAW is one for every entity M2 — the footprint-MOCV bake (wow-re
-    // `unit-m2-shader-light.md`), with the matte ×1.0 as the bake's miss fallback.
+    // indoor LAW is one for every entity M2 — the footprint-MOCV bake (`0x69e4c0`, `0x6a7300`),
+    // with the matte ×1.0 as the bake's miss fallback.
     if let Some(lit) = part_interior_lit(
         mats.steady,
         mats.interior,
@@ -467,10 +467,10 @@ pub(super) fn spawn_part(
     ) {
         child.insert(lit);
     }
-    // The batch's **animated material alpha** (the verified combine's runtime half, wow-re
-    // `m2-alpha-combine-cull.md`): a creature's colour-alpha/transparency tracks are authored PER
-    // SEQUENCE, so which of its batches draw is a function of what it is playing. Sampling follows
-    // the unit's own `AnimationPlayer`, so the alpha stays in phase with the pose.
+    // The batch's **animated material alpha** (the combine's runtime half, `0x707680`): a
+    // creature's colour-alpha/transparency tracks are authored PER SEQUENCE, so which of its
+    // batches draw is a function of what it is playing. Sampling follows the unit's own
+    // `AnimationPlayer`, so the alpha stays in phase with the pose.
     if let Some(anim) = &part.alpha_anim {
         child.insert(benilla_world::doodad_anim::MatAnim::following(
             anim.clone(),
diff --git a/crates/benilla-app/src/entities/attach/mod.rs b/crates/benilla-app/src/entities/attach/mod.rs
index 29898d73..604c5022 100644
--- a/crates/benilla-app/src/entities/attach/mod.rs
+++ b/crates/benilla-app/src/entities/attach/mod.rs
@@ -212,13 +212,12 @@ fn arm_sequence_clock(
 ) {
     // **Every** GameObject instance gets the loader-idle seed, state machine or not — the
     // reference's `0x70ebd0` tail arms bone 0 the moment the M2 goes LIVE and has exactly two
-    // callers, so no M2 instance in the client ever exists with nothing armed (wow-re
-    // `gameobject-anim-arm.md` §1/§2e). For a door/chest the object-layer arm lands *after* it
-    // and overrides it (§2, "because it lands after the loader seed, it is the effective arm");
-    // seeding first is what stops the one-frame BIND POSE our state GOs used to render on their
-    // first displayed frame, before `go_anim` had a chance to run — the "explodes for a split
-    // second" report. The seed is played THROUGH the transitions object so that first arm
-    // cleanly fades out of it; playing it bare on the player would leave two clips live at once.
+    // callers, so no M2 instance in the client ever exists with nothing armed. For a door/chest
+    // the object-layer arm (`0x5f3930`) lands *after* it and overrides it; seeding first is what
+    // stops the one-frame BIND POSE our state GOs used to render on their first displayed frame,
+    // before `go_anim` had a chance to run, which reads as a one-frame explosion. The seed
+    // is played THROUGH the transitions object so that first arm cleanly fades out of it;
+    // playing it bare on the player would leave two clips live at once.
     let mut player = AnimationPlayer::default();
     let mut transitions = AnimationTransitions::new();
     if kind == EntityKind::GameObject {
@@ -228,9 +227,9 @@ fn arm_sequence_clock(
         // emitters ended up reading file slot 0 at t = 0 for ever (0941).
         if let Some(clip) = anims.idle_clip() {
             // Loop iff the sequence says so (`M2Sequence.flags & 1 == 0`) — the kernel's own
-            // end-of-band law (wow-re `gameobject-anim-arm.md` §2, byte-verified at
-            // `0x714585`): bit0 clear loops on the modulo wrap, bit0 set plays the window and
-            // then FREEZES at `end_ms`. An unconditional repeat replayed one-shot idles.
+            // end-of-band law (`0x714585`): bit0 clear loops on the modulo wrap, bit0 set plays
+            // the window and then FREEZES at `end_ms`. An unconditional repeat replayed one-shot
+            // idles.
             let active = transitions.play(&mut player, clip.node, std::time::Duration::ZERO);
             if clip.looping {
                 active.repeat();
@@ -451,7 +450,7 @@ pub(super) fn attach_entity_visuals(
         // carry a *transparent* placeholder M2, and invisible **trigger creatures** an empty or
         // constant-zero-alpha one: the real client's mesh gate is **type-independent** — it draws
         // any loaded model and the per-batch zero-alpha cull skips the transparent geometry
-        // (decision 0024, superseding 0023's wrong marker-type gate; verified wow-re go-render-gate).
+        // (decision 0024, superseding 0023's wrong marker-type gate; zero-alpha cull `0x707b3a`).
         // Our M2 alpha cull already reduces those models to zero submeshes, so `parts` below is
         // EMPTY for them: the spawn loop draws nothing, and `named_a_model` is what keeps the unit
         // arm's debug cube off them (1403).
@@ -523,9 +522,9 @@ pub(super) fn attach_entity_visuals(
                 .insert_if_new(benilla_world::entity_shade::GroundShade::default());
             // The root's canonical fold reference: held items share the root's interior verdict
             // (one light node per unit — the reference aliases the wearer's collector into each
-            // equipped item, wow-re `unit-light-combine-storm.md`), and their classifier fold must
-            // reference the BODY's centre, not the carried position. Plain `insert`: a display-id
-            // change re-derives it with the new body model.
+            // equipped item, `0x718960`), and their classifier fold must reference the BODY's
+            // centre, not the carried position. Plain `insert`: a display-id change re-derives it
+            // with the new body model.
             commands
                 .entity(entity)
                 .insert(benilla_world::interior::BodyBakeCenter(bake_center));
@@ -561,8 +560,8 @@ pub(super) fn attach_entity_visuals(
             // mesh did). Truly static props keep the static mesh. `skin` is `Some((joints,
             // inverse_bindposes, palette_slot))` when instanced (decision 0720; slot 0 = palette
             // full, parts fall back to the static mesh).
-            // Does this entity run the GameObject open/close state machine (the byte-verified
-            // TYPE_ID census)? Read once — it picks both the rig flavour below and the clock's
+            // Does this entity run the GameObject open/close state machine (the type dispatch at
+            // `0x5f76cc`)? Read once — it picks both the rig flavour below and the clock's
             // driver, and those two must never disagree about the same object.
             let go_state_machine = net.kind == EntityKind::GameObject
                 && stores
@@ -632,10 +631,10 @@ pub(super) fn attach_entity_visuals(
                 // skinned twin like a creature. Two flavours share the rig: a door/button/chest
                 // (`go_animates`) runs the open/close state machine off GAMEOBJECT_STATE (decision
                 // 0242); ANY other animated GO — a mailbox's wind-swung flags, a banner, a windmill —
-                // loops its first sequence as the reference's universal loader-idle seed (wow-re
-                // `doodad-anim-host.md`: a non-transport CGGameObject animates identically to a placed
-                // doodad). The content gate for the non-state flavour is the doodad classifier's: a GO
-                // whose first sequence is a constant pose and which has no global sequences
+                // loops its first sequence as the reference's universal loader-idle seed
+                // (`0x70ebd0`: a non-transport CGGameObject animates identically to a placed
+                // doodad). The content gate for the non-state flavour is the doodad classifier's:
+                // a GO whose first sequence is a constant pose and which has no global sequences
                 // (`DoodadAnimTier::Static`) has nothing to loop, so it keeps the static mesh.
                 (EntityKind::GameObject, Some(d))
                     if !d.skeleton.joints.is_empty() && d.animations.is_some() =>
@@ -730,7 +729,7 @@ pub(super) fn attach_entity_visuals(
             let look = resolve_char_look(net, dm, entity, &stores);
             // The worn geoset selectors (decisions 0074/1864, the B1–B8 branches): a player's from the
             // resolved equipment display rows; an NPC / naked default otherwise.
-            // (The helm's hide-mask row pair, RF-0083: hair/facial/ears tuck under it. For a
+            // (The helm's hide-mask row pair, `0x4799a0`: hair/facial/ears tuck under it. For a
             // character-model NPC the helm id is its CreatureDisplayInfoExtra head column.)
             let equip_geosets = equip_geosets(
                 displays.as_deref(),
@@ -913,8 +912,8 @@ pub(super) fn attach_entity_visuals(
             // Final size = the server's per-object scale (`OBJECT_FIELD_SCALE_X`) alone. The server
             // already folds the unit's DBC scale (`CreatureModelData.modelScale ×
             // CreatureDisplayInfo.scale`, or an explicit per-spawn override) into this field, and the
-            // real client renders units at the field alone (verified: wow-re `world_model_scale`
-            // `0x613ef0`, vmangos `Unit::GetScaleForDisplayId`). Multiplying our own DBC scale on top
+            // real client renders units at the field alone (`0x613ef0`, vmangos
+            // `Unit::GetScaleForDisplayId`). Multiplying our own DBC scale on top
             // double-applies it — `native²`, worst for the sub-1.0 starting-zone scales. A GameObject's
             // display scale was always 1.0, so this is unchanged for it.
             let placement = if let Ok(mut t) = transforms.get_mut(entity) {
@@ -1093,7 +1092,7 @@ pub(super) fn attach_entity_visuals(
             // A display that DID name a model renders exactly what that model built — including
             // nothing (decision 1403, bug B13). The reference's mesh gate is type-independent: it
             // draws any loaded model and the per-batch zero-alpha cull skips what is transparent
-            // (decision 0024, verified wow-re `go-render-gate`), so a model with no surviving batch
+            // (decision 0024, zero-alpha cull `0x707b3a`), so a model with no surviving batch
             // submits no geometry and the unit is invisible. Byte-exact, folded back at 1407: the
             // batch loop's TRIP COUNT is the selected ModelView's texUnit count (`0x707a72`), so a
             // view with none skips the whole loop — and the unit lane reaches that same loop, on
diff --git a/crates/benilla-app/src/entities/attach/preview.rs b/crates/benilla-app/src/entities/attach/preview.rs
index f7f1e4fe..af7415db 100644
--- a/crates/benilla-app/src/entities/attach/preview.rs
+++ b/crates/benilla-app/src/entities/attach/preview.rs
@@ -21,8 +21,8 @@
 //! The assembly is the world's own way — displayId → the shared [`Creatures`] display cache →
 //! geoset filter → the composited body over a hand-built [`CharLook`] — plus the armor-region
 //! composite + real equipment geosets, the cloak, and the attach riders: helm (per-race/sex model,
-//! hide-helm honored), shoulders, and the weapons **held in the hands** (the byte-verified select
-//! build — wow-re `glue-select-model.md`, folded back over 0465's sheathed INTERIM). The portrait
+//! hide-helm honored), shoulders, and the weapons **held in the hands** (the select build
+//! `0x472950` → `0x47a0c0`, folded back over 0465's sheathed INTERIM). The portrait
 //! module's `sync_glue_booth` / `sync_dressup_booth` then re-light and bake them (they own the
 //! *booth*; this owns the *assembly*). A glue body's displayId is added to
 //! `update_display_models`'s want-list (in [`super::super`]) so its model builds with no wire
@@ -64,7 +64,7 @@ const ENUM_HELD: [usize; 3] = [15, 16, 17];
 /// Map an item's `InventoryType` to its equipment-slot index in the enum-shaped `[_; 19]` array
 /// (`EQUIPMENT_SLOT_*`), so a CharStartOutfit item (decision 0527) lands where the Select pipeline
 /// reads it — the render slots the compositor paints (helm 0 · shoulder 2 · shirt 3 · chest 4 ·
-/// waist 5 · legs 6 · feet 7 · wrist 8 · hands 9 · back 14 · tabard 18, wow-re `glue-select-model.md`)
+/// waist 5 · legs 6 · feet 7 · wrist 8 · hands 9 · back 14 · tabard 18, `0x478cb0`)
 /// plus the held triple (main 15 · off 16 · ranged 17). `None` for a non-worn / non-rendered type
 /// (bags, ammo, quiver, relic, and NON_EQUIP consumables — the outfit's food + hearthstone).
 pub(crate) fn equip_slot(inv_type: u8) -> Option<usize> {
@@ -175,10 +175,10 @@ pub(in crate::entities) fn build_glue_preview(
     mut skin_composites: ResMut<SkinComposites>,
     asset_server: Res<AssetServer>,
     mut mats: benilla_world::model_render::M2BatchMaterials,
-    // The ghost kit (wow-re `glue-select-model.md` §A2): the `SpellVisualKit` catalog the row is
-    // read from, and the path-keyed spell-effect model cache its attached models load through —
-    // the same one the world's kit plays use, so `Spells\Ghost_state.mdx` is loaded once per
-    // session whichever screen wants it first.
+    // The ghost kit (`0x47280f`): the `SpellVisualKit` catalog the row is read from, and the
+    // path-keyed spell-effect model cache its attached models load through — the same one the
+    // world's kit plays use, so `Spells\Ghost_state.mdx` is loaded once per session whichever
+    // screen wants it first.
     visuals: Option<Res<crate::creature_anim::SpellVisuals>>,
     mut fx: Option<ResMut<super::super::spell_fx::SpellFx>>,
     // Change tracking: the look we last emitted a bake for, and whether that bake succeeded (so a
@@ -462,11 +462,11 @@ pub(in crate::entities) fn build_dressup_preview(
 /// A caller must treat that as "retry next frame" and leave its bake untouched, never as an empty
 /// look — a geared character popping in piecewise would flicker on every change.
 /// The `SpellVisualKit` row the character-select ghost is, **hard-coded exactly as the reference
-/// hard-codes it**: `0x47280f` loads `idmap[989]` behind the guard `0x4727f6 cmp ds:0xc0d750,0x3dd`
-/// (wow-re `glue-select-model.md` §A2). The id is the constant; every value behind it is DBC data,
+/// hard-codes it**: `0x47280f` loads `idmap[989]` behind the guard
+/// `0x4727f6 cmp ds:0xc0d750,0x3dd`. The id is the constant; every value behind it is DBC data,
 /// read below. 989 is `SpellVisual` 886's state kit — the visual of spell 8326 "Ghost", which is
-/// also what a released ghost in the WORLD rides, so the two paths share one row by construction
-/// (wow-re `ghost-death-visuals.md` §5a).
+/// also what a released ghost in the WORLD rides (`0x5ff350`), so the two paths share one row by
+/// construction.
 const GLUE_GHOST_KIT: u32 = 989;
 
 /// What the ghost kit contributes to a select bake: the body's own render properties, plus the
@@ -623,9 +623,9 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
     };
     let mut held = held_wants(&equipment, helm, race, sex, spec.ranged_in_hand);
     // Per-hand grip `[right, left]`: a hand whose attach point holds a weapon curls into `HandsClosed`
-    // (wow-re `hand-grip-mechanism.md` — the ref's paperdoll rule `0x5059a0`: attach-point occupancy, per
-    // hand). Resolved here because the flat rider list drops each held item's attach id. A shield sits on
-    // the forearm (Shield attach, id 0), never a hand point, so its hand stays open.
+    // (the ref's paperdoll rule `0x5059a0`: attach-point occupancy, per hand). Resolved here
+    // because the flat rider list drops each held item's attach id. A shield sits on the forearm
+    // (Shield attach, id 0), never a hand point, so its hand stays open.
     let grip = [
         held.iter().any(|w| w.attach == attach_id::HAND_RIGHT),
         held.iter().any(|w| w.attach == attach_id::HAND_LEFT),
@@ -674,7 +674,7 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
     }
 
     // The dressed geoset set: the worn armor's geoset groups + the cloak + the helm's hide-masks
-    // (RF-0083), exactly the world path's selection (the shared helper).
+    // (`0x4799a0`), exactly the world path's selection (the shared helper).
     let eg = equip_geosets(ctx.displays.as_deref(), &bodyslots, cloak, helm, false);
     let visible = ctx.characters.map(|c| {
         c.0.visible_geosets(race, sex, char_look.hair_style, char_look.facial_hair, &eg)
@@ -753,7 +753,7 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
     // An item model is not just meshes, and for a while this loop treated it as if it were — it kept
     // the batches with no billboard flag and dropped everything else on the floor, so at character
     // select a worn item's own **effects** (its emitters, its camera-facing batches) simply did not
-    // exist. That is `#bugs` B118 as nazriel filed it: the R14 PVP shoulders' sparkle is the item
+    // exist. The R14 PVP shoulders' sparkle is the item
     // model's own emitters (decision 0813), and no part of it reached the booth. So each want
     // contributes up to four things at one seat: plain meshes ([`PreviewRider`]), camera-facing
     // batches ([`PreviewBillboard`]), its emitters ([`PreviewEffects`]), and — held weapons only —
@@ -803,7 +803,7 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
                 }
             }
             // The item model's OWN particle emitters — the R14 PVP pauldron's `SPARKLE` twinkle
-            // (`#bugs` B118, decision 0813), the held torch's flame. 95 `Item\` models hang one on a
+            // (decision 0813), the held torch's flame. 95 `Item\` models hang one on a
             // billboard bone alone; the booth spawns them off a host at the attach point, each
             // billboard-chain emitter through a booth-camera frame.
             if !item.emitters.is_empty() {
@@ -897,15 +897,14 @@ struct HeldWant {
 }
 
 /// The select character's attach-model wants from its enum record: helm + the shoulder pair, and
-/// the weapons **held in the hands** — the byte-verified select build (wow-re
-/// `glue-select-model.md` TU-A, folding back decision 0465's sheathed INTERIM): the builder
-/// forces SheatheType 0 (`0x472c8c`), so the sheath resolver never yields a stow point and the
-/// hand code runs — mainhand to HandRight (attach 1), an off-hand weapon to HandLeft (2), a
-/// shield to the Shield point (0) — and the RANGED slot is skipped outright (`0x472bfe`).
-/// [`placement`]'s melee-drawn arm (`unit_sheath = 1`) is exactly that law, ranged-skip included
-/// (its ranged arm only yields while ranged-drawn). A held off-hand frill (INVTYPE_HOLDABLE)
-/// rides the same hand law — the verdict enumerates weapons/shields only, and the world's held
-/// placement is the natural reading for the rest.
+/// the weapons **held in the hands** — the select build (folding back decision 0465's sheathed
+/// INTERIM): the builder forces SheatheType 0 (`0x472c8c`), so the sheath resolver never yields a
+/// stow point and the hand code runs — mainhand to HandRight (attach 1), an off-hand weapon to
+/// HandLeft (2), a shield to the Shield point (0) — and the RANGED slot is skipped outright
+/// (`0x472bfe`). [`placement`]'s melee-drawn arm (`unit_sheath = 1`) is exactly that law,
+/// ranged-skip included (its ranged arm only yields while ranged-drawn). A held off-hand frill
+/// (INVTYPE_HOLDABLE) rides the same hand law — the reference confirms it at `0x47a0c0` for
+/// weapons/shields only, and the world's held placement is the natural reading for the rest.
 ///
 /// **`ranged_in_hand` is the dressing room's departure from that** (decision 1076): the dress-up
 /// widget does *not* skip the ranged slot, and installs it at a hand. That is the same mapping
@@ -1133,9 +1132,9 @@ fn assemble_pet(
                 material: p.material.clone(),
                 alpha_anim: p.alpha_anim.clone(),
                 // The pet is its own CM2 instance, chained to the SCENE (attachment 1), never to
-                // the character (wow-re `glue-select-model.md` §B1) — so it composes onto nothing
-                // and is never ghosted with its owner. The twins ride anyway, for the same reason
-                // the body's do: they are a property of the batch.
+                // the character (`0x47306e`) — so it composes onto nothing and is never ghosted
+                // with its owner. The twins ride anyway, for the same reason the body's do: they
+                // are a property of the batch.
                 twins: BoothTwins {
                     blend: p.fade_blend.clone(),
                     zfill: p.zfill.clone(),
@@ -1206,17 +1205,15 @@ mod tests {
     /// hard-codes for the character-select ghost, decoded through the same dispatch point the world
     /// aura uses.
     ///
-    /// Every number here is byte-VERIFIED in wow-re at the record itself
-    /// (`ghost-death-visuals.md` §5a: row 989's `+0x3c` reads
-    /// `01 00 00 00  0e 00 00 00  ff ff ff ff  ff ff ff ff  fd b9 0c 4b  00 00 00 3f`), and the
-    /// note records a §5 derivation that got `0x4B0CB53D → (140,181,61)` and was refuted at those
-    /// bytes. That is exactly the failure this test exists to catch: a tint transcribed one nibble
-    /// wrong is still a plausible pale blue, and nothing but the shipped row can tell them apart.
+    /// Every number here is read at the record itself (row 989's `+0x3c` reads
+    /// `01 00 00 00  0e 00 00 00  ff ff ff ff  ff ff ff ff  fd b9 0c 4b  00 00 00 3f`), and
+    /// `0x4B0CB53D → (140,181,61)` is a misreading of those bytes. That is exactly the failure
+    /// this test exists to catch: a tint transcribed one nibble wrong is still a plausible pale
+    /// blue, and nothing but the shipped row can tell them apart.
     ///
     /// It also pins the *shape* the select path depends on — one populated effect slot, at
-    /// attachment `0x13` (Base) — because "nine ghost sub-models" was this note's own earlier
-    /// reading (benilla decision 0469 §6 carried it), corrected 2026-08-21 when `0x472780`'s
-    /// `test esi,esi; jl` was seen rejecting the eight `-1`s.
+    /// attachment `0x13` (Base) — because "nine ghost sub-models" was an earlier reading (benilla
+    /// decision 0469 §6 carried it), and `0x472780`'s `test esi,esi; jl` rejects the eight `-1`s.
     #[test]
     fn the_shipped_ghost_kit_decodes_to_the_verified_row() {
         let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-app/src/entities/attach/redress.rs b/crates/benilla-app/src/entities/attach/redress.rs
index 664127df..9fe2aec1 100644
--- a/crates/benilla-app/src/entities/attach/redress.rs
+++ b/crates/benilla-app/src/entities/attach/redress.rs
@@ -13,11 +13,9 @@
 //! The reference re-dresses on the SAME `CM2Model`. Its character compositor re-blits the dirty
 //! region groups into the component's own 256² target and re-runs the geoset selection `0x477520`,
 //! whose only reach into the model is the per-instance visibility array `+0x98` — a range filter
-//! writing ordinals, nothing more (wow-re `charactermodel.md` "Assembly orchestration";
-//! `models.md` §"geoset-visibility-default", where the writer census proves the character compositor
-//! is the *only* thing in the binary that can hide a submesh). Attachments are installed through a
-//! different mechanism entirely (`0x712f70 CM2Model::attachChild`) and the compositor never touches
-//! them.
+//! writing ordinals (`0x7110d0`), nothing more; the character compositor is the *only* thing in
+//! the binary that can hide a submesh. Attachments are installed through a different mechanism
+//! entirely (`0x712f70 CM2Model::attachChild`) and the compositor never touches them.
 //!
 //! So this system is that law, and only that law:
 //!
diff --git a/crates/benilla-app/src/entities/carried_light.rs b/crates/benilla-app/src/entities/carried_light.rs
index 59d0dd3a..2c078343 100644
--- a/crates/benilla-app/src/entities/carried_light.rs
+++ b/crates/benilla-app/src/entities/carried_light.rs
@@ -965,7 +965,7 @@ mod tests {
     }
 
     /// GOLDEN — the carried-light spawn law. Only a **casting** light spawns (`type==1`, not held
-    /// dark by a static `0` visibility key — wow-re `m2-dynamic-lights.md` §9.4, the shape 11 of
+    /// dark by a static `0` visibility key — the gather gates in `0x718960`, the shape 11 of
     /// the corpus's 85 point lights actually ship), it lands as a CHILD of its host bone's joint
     /// so the animation carries it, and its offset is the def position rebased into that bone's
     /// frame (`position − bone_pivot`, wow→bevy). Colour × intensity survives the `PointLight`
diff --git a/crates/benilla-app/src/entities/chain_beam.rs b/crates/benilla-app/src/entities/chain_beam.rs
index 08bc9462..9cc1b51b 100644
--- a/crates/benilla-app/src/entities/chain_beam.rs
+++ b/crates/benilla-app/src/entities/chain_beam.rs
@@ -4,9 +4,7 @@
 //! A kit whose `CharProc` decodes to a chain ([`benilla_formats::ChainProc`]) draws a **polyline of
 //! hops** — `caster → t1 → t2 → t3` — with one ribbon per hop, each subdivided, jittered per frame
 //! and scrolled. The data half (the DBC row, the sentinel fix, the wire) is slice 1; this module is
-//! the client's `LightningObject` (`0x6ec460`) + `CLightning` (`0x7af9b0`/`0x7afcb0`) pair, whose
-//! every load-bearing number is byte-VERIFIED in wow-re `system/spell/scratch/chain-beam-law.md`
-//! (their `31715619`).
+//! the client's `LightningObject` (`0x6ec460`) + `CLightning` (`0x7af9b0`/`0x7afcb0`) pair.
 //!
 //! ## What the reference does, and what this transcribes
 //!
@@ -58,7 +56,7 @@
 //!   `phase = fmod(phase + dt, period)`; a **negative** period reverses the scroll, which is what
 //!   flows the four drain textures back toward the caster.
 //!
-//! **Render state** (`0x7afcb0`, decoded against wow-re's own verified `EGxRs` map): additive
+//! **Render state** (`0x7afcb0`, decoded against the `EGxRs` applicator `0x59d350`): additive
 //! `SRC_ALPHA/ONE`, emissive white — a beam is **never tinted** — two-sided, depth-write off, fog
 //! **off**. It rides the shared effect-quad stream ([`benilla_world::particles::buffer::EffectQuads`]) like
 //! every other dynamic effect; `benilla_world::ribbons` is the structural model (same strip-as-quads
@@ -69,7 +67,7 @@
 //! byte-identical arguments and they diverge *only* through their interleaved draws on the shared
 //! PRNG, which is a shared-generator detail we do not reproduce, so ours diverge by construction
 //! instead. (b) The `SMSG_SPELL_GO` producer leg is gated in the reference on `0x6e4870`'s return, a
-//! predicate the §5 could not settle; we fill unconditionally — the superset, harmless because
+//! predicate that is not settled; we fill unconditionally — the superset, harmless because
 //! consumption still requires a chain proc, and because every producer clears before it fills.
 //! (c) A channel re-enters the dispatcher every tick (`0x612b18`) where we hold one beam for the
 //! channel's life; the observable — a steady beam that ends with the channel — is the same.
@@ -124,7 +122,7 @@ const MAX_SUBDIVISIONS: usize = 256;
 /// (`{capacity, count, data, quantum}`; the guid list, in wire order, with the caster's own guid
 /// dropped as it fills, `0x6057bf`/`0x6057c9`).
 ///
-/// Two producers write it (`crate::net::apply::spells`: the `SMSG_SPELL_GO` hit list and
+/// Two producers write it (`crate::spell::net`: the `SMSG_SPELL_GO` hit list and
 /// `SMSG_SPELL_UPDATE_CHAIN_TARGETS`), each **clearing before it fills**; [`spawn_chain_beams`]
 /// consumes it **once** and removes it, exactly as `0x60db72` zeroes the count on every exit —
 /// including the paths that draw nothing. Targets not streamed to us drop out as they resolve: an
@@ -569,10 +567,10 @@ pub(crate) fn simulate_chain_beams(
     }
 }
 
-/// The beam's arithmetic, against the numbers wow-re read out of the binary — the subdivision floor,
+/// The beam's arithmetic, against the numbers read out of the binary — the subdivision floor,
 /// the spindle taper, the view-plane cross-section and its degenerate regime, and the signed
 /// scroll. Each of these is a value that would go straight into pixels, and two of the four columns
-/// they read were mis-named in the community schemas until the §5 (decision 0955).
+/// they read are mis-named in the community schemas (decision 0955).
 #[cfg(test)]
 mod tests {
     use std::collections::HashMap;
@@ -679,8 +677,8 @@ mod tests {
     }
 
     /// `n = trunc(len / avgSegLen + 2.0)`, `n+1` points — a **floor of two**, so even a hop shorter
-    /// than one segment still bends (`0x7af713`, the `2.0f` at `0x801628`). The 30-yard case is the
-    /// §5's own worked example: 30 / 2.78 + 2 → 12 segments, 13 points.
+    /// than one segment still bends (`0x7af713`, the `2.0f` at `0x801628`). The 30-yard case:
+    /// 30 / 2.78 + 2 → 12 segments, 13 points.
     #[test]
     fn subdivision_carries_the_plus_two_floor() {
         let (e, mut rng, mut out) = (lightning(), 1u32, Vec::new());
diff --git a/crates/benilla-app/src/entities/collision_height.rs b/crates/benilla-app/src/entities/collision_height.rs
index c789761c..a389518e 100644
--- a/crates/benilla-app/src/entities/collision_height.rs
+++ b/crates/benilla-app/src/entities/collision_height.rs
@@ -14,29 +14,29 @@ use super::Creatures;
 /// A unit's **collision height** in world yards — the reference's `CMovement+0xb4`, and the `h`
 /// that every depth line in the client is a fraction of: swim enters and rests at `0.75·h`, the
 /// splash fires at `0.4·h`, wading ends where swimming begins (`0.75·h`), and the foam gate is
-/// `max(2·h, 1.0)`. Each of those *fractions* is byte-verified against the real client (wow-re
-/// `swim-transition.md`, `swim-mechanism.md`, `water-ripple-decal.md`); until decision 0645 the
-/// `h` they multiplied was a **constant** — [`crate::player::DEFAULT_COLLISION_HEIGHT`], the
-/// client's own empty-world ctor default — so all five lines were right for a human male (2.031,
-/// within 2 mm of it) and wrong for every other race. A gnome female stands 1.15 yd and was held
-/// 1.52 yd under: she could not reach the surface, which is how the defect finally showed (B76).
+/// `max(2·h, 1.0)`. Each of those *fractions* is the real client's (`0x6030c0`, `0x5fa760`);
+/// until decision 0645 the `h` they multiplied was a **constant** —
+/// [`crate::player::DEFAULT_COLLISION_HEIGHT`], the client's own empty-world ctor default — so all
+/// five lines were right for a human male (2.031, within 2 mm of it) and wrong for every other
+/// race. A gnome female stands 1.15 yd and was held 1.52 yd under: she could not reach the
+/// surface, which is how the defect finally showed (B76).
 ///
 /// `CreatureModelData.collisionHeight × k`. The column is the model's own MD20 collision-box Z
 /// extent in raw model units — machine-pinned against the shipped client (`benilla_formats`
 /// `collision_height_is_the_m2_collision_box`), which is what settles that it scales with the
 /// geometry it bounds.
 ///
-/// **`k = max(OBJECT_FIELD_SCALE_X, CreatureDisplayInfo.creatureModelScale)`** — VERIFIED byte law
-/// (wow-re `collision/scratch/mover-collision-scalars.md`): `0x60b270` fetches `SCALE_X` through
-/// vtable slot `+0x1c` (`0x469f10`), compares it against the display row's own column at
-/// `0x60b312` (`CreatureDisplayInfo+0x10`), and hands the **larger** to `0x6174b0`, which stores
-/// `CollisionHeight · k` into `CMovement+0xb4` at `0x617501`. Its two callers include the unit
-/// model (re)build `0x5fb9dd` with `force = 1`, so every unit gets it, not just the mover.
+/// **`k = max(OBJECT_FIELD_SCALE_X, CreatureDisplayInfo.creatureModelScale)`** — the byte law:
+/// `0x60b270` fetches `SCALE_X` through vtable slot `+0x1c` (`0x469f10`), compares it against the
+/// display row's own column at `0x60b312` (`CreatureDisplayInfo+0x10`), and hands the **larger** to
+/// `0x6174b0`, which stores `CollisionHeight · k` into `CMovement+0xb4` at `0x617501`. Its two
+/// callers include the unit model (re)build `0x5fb9dd` with `force = 1`, so every unit gets it,
+/// not just the mover.
 ///
 /// The `max` is a **floor, never a second multiplier**. The *render* scale is [`NetEntity::scale`]
 /// = `OBJECT_FIELD_SCALE_X` alone, which the server has already folded the DBC scales into
 /// (`CreatureModelData.modelScale × CreatureDisplayInfo.scale`, vmangos `Unit::GetScaleForDisplayId`
-/// — and wow-re `object-layer.md`'s render-scale CORRECTION says in as many words that a client
+/// — and the reference's render scale (`0x613fc9`) has no display-column term, so a client
 /// multiplying the display column in again would *square* it). So the collision box and the drawn
 /// body still cannot disagree; the floor only stops the box shrinking below the display's own size.
 ///
@@ -52,8 +52,7 @@ use super::Creatures;
 /// `[unit+0x110]+0x1f8` (index 132), while its sibling `0x60ae10` reads `+0x1f4` (index 131 =
 /// `UNIT_FIELD_DISPLAYID`) off the same array; the cached-row arm is taken only when the two
 /// fields are equal (`[unit+0xc58] & 0x100` = "not transformed", set from their equality at
-/// `0x60b166`), so **every arm yields the native model's row**. VERIFIED — wow-re
-/// `mover-collision-scalars.md` and `remote-swim-decision.md` §4.
+/// `0x60b166`), so **every arm yields the native model's row**.
 ///
 /// So **a transform does not resize the collision prism**: a druid in bear form keeps the druid's
 /// swim, splash, foam and wade lines; a GM `.modify morph` into a gnome keeps the human's. That is
diff --git a/crates/benilla-app/src/entities/conform.rs b/crates/benilla-app/src/entities/conform.rs
index abaf1f44..acc6d845 100644
--- a/crates/benilla-app/src/entities/conform.rs
+++ b/crates/benilla-app/src/entities/conform.rs
@@ -1,4 +1,4 @@
-//! Terrain conform — **fidelity** (decisions 0482/0486; wow-re `terrain-tilt.md` §5): the
+//! Terrain conform — **fidelity** (decisions 0482/0486; `0x7106c0`): the
 //! reference tilts every model whose M2 authors `GlobalModelFlags & 3 ∈ {1,3}` — all 152 mounts
 //! + quadrupeds pitch (flag 1), the 74 low-wide models (kodo/basilisk/crab/crocodile/spider)
 //! pitch AND roll (flag 3) — wild or mounted alike: the gate is the model flag, not mountedness.
@@ -52,7 +52,7 @@ fn tilt_target(sampled: Option<Vec3>) -> Option<Vec3> {
 }
 
 /// The conform rotation for a smoothed up-vector in the unit's LOCAL frame (yaw already applied
-/// by the parent) — the `0x7106c0` flag dispatch, byte-exact (wow-re `terrain-tilt.md`):
+/// by the parent) — the `0x7106c0` flag dispatch, byte-exact:
 ///
 /// - **flag 1 (pitch only, `0x710769`)**: left is forced horizontal (`row1.z` a hard literal 0),
 ///   forward = left × up — which reduces in the local frame to a pure rotation about local X by
@@ -127,7 +127,7 @@ pub(super) fn conform_units(
         // a flagged NPC body over a mount field — and double-stepping would square the decay).
         if seen.insert(node.unit) {
             // A unit riding a FLYING spline settles to level here: the flying attitude (pitch,
-            // bank pending its §5) is the spline-follow's, applied to the UNIT transform by
+            // bank still open) is the spline-follow's, applied to the UNIT transform by
             // `sample_splines` — the client's `0x7c5490` mover-matrix law, model-flags-
             // independent (decision 0501 corrects 0496's conform-side placement, which never
             // rendered: the taxi gryphon authors `GlobalModelFlags = 0`, so it built no
diff --git a/crates/benilla-app/src/entities/corpse.rs b/crates/benilla-app/src/entities/corpse.rs
index 88852e69..44eae27e 100644
--- a/crates/benilla-app/src/entities/corpse.rs
+++ b/crates/benilla-app/src/entities/corpse.rs
@@ -28,7 +28,7 @@
 //! Three slots are carved out of the dress loop, and none of them is a "skip if empty":
 //! `0x5d6465`/`0x5d6470` skip slot 0 (head) and slot 0xe (back) when this corpse's own
 //! `CORPSE_FLAG_HIDE_HELM 0x08` / `HIDE_CLOAK 0x10` are set — its own bits on its own field, and the
-//! opposite instruction polarity to the player lane (wow-re `helm-cloak-hide.md` §2b) — and
+//! opposite instruction polarity to the player lane (`0x5ed700`) — and
 //! `0x5d644e` skips slot 0x11 (ranged) unconditionally.
 //!
 //! ## What a corpse deliberately does NOT wear
@@ -55,7 +55,7 @@
 //! call.) Mouseover is a different slot — `+0x54` = `0x5d76d0`, which a corpse *does* pass — and
 //! that is the highlight/cursor/tooltip route we ship, not a ring.
 //!
-//! **The divergence to know about** (flagged open by wow-re's §5, not settled at the bytes): the
+//! **The divergence to know about** (still open, not settled at the bytes): the
 //! reference computes the drowned verdict *inside* the create, from the scene node's cached liquid
 //! probe — and its own `[node+0x90] & 0x20` gate means an un-probed node falls through to `Dead`.
 //! Whether the node is already probed that early is a byte question nobody has closed. Ours asks
@@ -66,11 +66,10 @@
 //! ## The pose
 //!
 //! `0x5d63de`/`0x5d6402` arm bone 0 through the shared M2 arm `0x7121a0` with **AnimationData id 6
-//! (`Dead`)**, or **132 (`Drowned`)** when `0x5d6540` says so — all of it byte-VERIFIED by wow-re's
-//! §5 round (`object-layer/scratch/corpse-drowned-pose.md`, 2026-08-29, commissioned by this work).
-//! That predicate is a **liquid** query: `0x670630` reads the corpse scene node's cached probe,
-//! whose `[node+0x98]` is named at its *writer* (`0x69e280` → terrain's own bit-exact
-//! `liquid_status`) as the **liquid surface height**. The comparison is
+//! (`Dead`)**, or **132 (`Drowned`)** when `0x5d6540` says so. That predicate is a **liquid**
+//! query: `0x670630` reads the corpse scene node's cached probe, whose `[node+0x98]` is named at
+//! its *writer* (`0x69e280` → the terrain liquid query `0x69b6d0`) as the **liquid surface
+//! height**. The comparison is
 //!
 //! ```text
 //! liquidSurfaceZ − CORPSE_FIELD_POS_Z > [0x80abfc]        // 0x3f2aaaab = 0.66666669
diff --git a/crates/benilla-app/src/entities/dest_fx.rs b/crates/benilla-app/src/entities/dest_fx.rs
index 78fe1f59..709515f2 100644
--- a/crates/benilla-app/src/entities/dest_fx.rs
+++ b/crates/benilla-app/src/entities/dest_fx.rs
@@ -3,8 +3,8 @@
 //!
 //! - **The DynamicObject machine** ([`arm_ground_effects`]): a TYPEID-6 create is the anchor a
 //!   persistent area effect hangs on (Blizzard's storm, Flamestrike's burn). The reference
-//!   builds **two disjoint visuals** (wow-re `dynobject-visual-machine.md` — never through the
-//!   unit-kit pipeline; all 15 `PlaySpellVisualKit` call sites censused, none on this class):
+//!   builds **two disjoint visuals**, never through the unit-kit pipeline (none of the 15
+//!   `PlaySpellVisualKit` `0x60edf0` call sites is on this class):
 //!   - **Visual A** — the object's own `.mdx`: SPELLID → `Spell.dbc` SpellVisual →
 //!     `SpellVisual` field 11 ≠ 0 gate → field 12 → `SpellVisualEffectName` field 2 path
 //!     (`0x5d57c0`), instanced at the object's position **verbatim** (no terrain projection),
@@ -21,9 +21,9 @@
 //!   `SMSG_SPELL_GO` itself plays the field-12 model ONCE at the packet's dest point when
 //!   `SpellVisual` field 6 == 0 (no missile owns the arrival) — `0x6e8088`–`0x6e8143`, a
 //!   self-terminating CEffect. Flamestrike's initial burst; it fires **before** the dynobj
-//!   create arrives and must not wait for it (wow-re trap #6).
+//!   create arrives and must not wait for it (a trap).
 //!
-//! **Teardown is a tail, not a snap** (trap #3): `SMSG_DESTROY_OBJECT` despawns the anchor —
+//! **Teardown is a tail, not a snap** (a trap): `SMSG_DESTROY_OBJECT` despawns the anchor —
 //! visual A and the emitter die with it (the ref zeroes the emit rate at `0x6ecf20`) — but the
 //! already-emitted shards are FREE entities that run out their own one-pass lifetimes, exactly
 //! the ref's "spawned particles finish". The looping sound dies via the sound module's
@@ -44,8 +44,8 @@ use benilla_protocol::EntityKind;
 
 use super::spell_fx::{attach_effect_visuals, ensure_model, FxMaterials, SpellFx};
 
-/// The client's hardcoded shard-model table (`0x870e24`, 7 entries — wow-re
-/// `dynobject-visual-machine.md` Q-A1). `CharParamZero`'s decoded small int indexes it.
+/// The client's hardcoded shard-model table (`0x870e24`, 7 entries). `CharParamZero`'s decoded
+/// small int indexes it.
 const SHARD_MODELS: [&str; 7] = [
     "Spells\\Blizzard_Impact_Base.mdx",
     "Spells\\RainOfFire_Impact_Base.mdx",
@@ -64,8 +64,8 @@ const PROC_TYPE_SHARD_EMITTER: i32 = 9;
 /// The exact small-int decode the client applies to `CharParamZero`
 /// ([`benilla_formats::char_proc_small_int`] — the one idiom every integer-in-a-float-column proc
 /// uses, the chain proc included; decision 0955 lifted it into the format crate) — clamped into
-/// [`SHARD_MODELS`] because the client itself has **no bounds check** (`mov cl,al` — data ≥ 7
-/// reads past the table; wow-re trap #2).
+/// [`SHARD_MODELS`] because the client itself has **no bounds check** (`mov cl,al` in `0x5d55c0`
+/// — data ≥ 7 reads past the table; a trap).
 fn shard_model_index(param0: f32) -> usize {
     let idx = benilla_formats::char_proc_small_int(param0) as usize;
     idx.min(SHARD_MODELS.len() - 1)
@@ -246,7 +246,7 @@ pub(super) fn arm_ground_effects(
 }
 
 /// Spawn the router's GO dest one-shots — free entities at the packet's point, one sequence
-/// pass, then gone. Fired at the GO, never waiting on the dynobj create (trap #6).
+/// pass, then gone. Fired at the GO, never waiting on the dynobj create (a trap).
 pub(super) fn spawn_ground_bursts(
     mut commands: Commands,
     mut bursts: MessageReader<GroundBurst>,
@@ -467,8 +467,8 @@ mod tests {
 
     /// The `0x5d55c0` decode: `bits(f32(param0 + 512.0)) >> 14 & 0xff` recovers the small int
     /// exactly (the real rows carry 0.0 → Blizzard, 1.0 → Rain of Fire), and out-of-table data
-    /// clamps instead of reading past the 7 entries (the client's own missing bounds check —
-    /// wow-re trap #2).
+    /// clamps instead of reading past the 7 entries (the client's own missing bounds check — a
+    /// trap).
     #[test]
     fn shard_model_index_decodes_and_clamps() {
         assert_eq!(shard_model_index(0.0), 0);
diff --git a/crates/benilla-app/src/entities/display.rs b/crates/benilla-app/src/entities/display.rs
index dd39efca..dc019880 100644
--- a/crates/benilla-app/src/entities/display.rs
+++ b/crates/benilla-app/src/entities/display.rs
@@ -57,8 +57,8 @@ pub(super) struct EntityPart {
     /// The interior BAKE variant (every M2 part): the material in interior-PROP mode, whose
     /// `MeshTag` payload the shader reads as an SH-probe slot — the footprint-MOCV law. Units and
     /// GameObjects alike consume it: the reference registers EVERY entity M2 with the same
-    /// entity-node fill (`Node::SetModel`), so one law lights them all indoors (wow-re
-    /// `unit-m2-shader-light.md`, superseding the 0315 unit/GO split). `None` for WMO parts.
+    /// entity-node fill (`Node::SetModel` `0x6716f0`), so one law lights them all indoors
+    /// (`0x6a7300`, superseding the 0315 unit/GO split). `None` for WMO parts.
     pub(super) material_interior_bake: Option<Handle<WowModelMaterial>>,
     /// The bake variant's own `AlphaMode::Blend` twin — a fade (the self-avatar zoom feather, a
     /// despawn ramp) on a bake-classified part rides THIS, keeping the probe light through the
@@ -69,7 +69,7 @@ pub(super) struct EntityPart {
     /// (creatures + M2 GameObjects, the CGObjects that appear-fade); `None` for WMO-display parts.
     pub(super) fade_blend: Option<Handle<WowModelMaterial>>,
     /// The **depth-prime twin** material ([`benilla_world::model_render::zfill_material`] — the reference's
-    /// `M2UseZFill` clone, wow-re `m2-blend-promotion-zfill.md` §4). While the part draws
+    /// `M2UseZFill` clone, `0x707f7d`–`0x708072`). While the part draws
     /// translucent, `model_fade::sync_zfill_twins` spawns a child mesh on this: colour-masked,
     /// blend-off, z-writing, sorted before the colour parts — one blended layer everywhere, no
     /// self-overlap darkening on a stealthed or fading body. `None` when the batch's material
@@ -96,10 +96,10 @@ pub(super) struct EntityPart {
     /// Plenty of them do not: 101 creature models author several (`Creature\Banshee` carries `0`
     /// and `402`). They still draw whole, because the reference's per-model visibility array is
     /// allocated **filled with `1`** — all visible — and the only writer is the character
-    /// compositor, which a creature never reaches (VERIFIED, wow-re `models.md` §"M2 geoset
-    /// visibility": the `CCharacterComponent` is created on exactly two guarded paths and a
-    /// creature fails both). That array is indexed by **submesh ordinal**, not by this id — the
-    /// client never decomposes a `group*100 + variant` id anywhere in its render band.
+    /// compositor, which a creature never reaches (`0x5fb200`: the `CCharacterComponent` is
+    /// created on exactly two guarded paths and a creature fails both). That array is indexed by
+    /// **submesh ordinal**, not by this id — the client never decomposes a `group*100 + variant` id
+    /// anywhere in its render band.
     pub(super) geoset_id: u16,
     /// The character runtime texture slot this part carries (M2 type 1 = body, type 6 = hair). For a
     /// player the per-entity attach swaps its material to one carrying that per-appearance texture
@@ -134,7 +134,7 @@ pub(super) struct EntityPart {
     /// only ever seed white: the hunter's Freezing Trap glow card is the class (decision 2295).
     pub(super) rgb_seq: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 3]>>>,
     /// The part's **texture-transform (UV) loop** — the translation track that scrolls this
-    /// batch's stage UVs (decision 0130 phase 3, wow-re `m2-texanim-uv`). The **effect lane**
+    /// batch's stage UVs (decision 0130 phase 3, `0x70b740`). The **effect lane**
     /// ([`super::spell_fx`]) samples it per instance on its own clip clock, through a material
     /// clone (decision 2282); the unit/GameObject lane runs it on the shared, deduped material
     /// (decision 2295). `None` for the ~98.6% of batches with no texture transform, and for all
@@ -238,7 +238,7 @@ pub(crate) struct DisplayModel {
     pub(crate) first_seq_span: Option<f32>,
     /// Camera framing-pivot height in **model-local yards, pre-scale** — `0.9 × bbox_z_extent` from the
     /// M2 authored bounds, captured in [`build_parts`]. Stamped onto each instance as [`CameraPivot`] so
-    /// the third-person camera targets ~neck height rather than a fixed offset (wow-re `follow-camera`).
+    /// the third-person camera targets ~neck height rather than a fixed offset (`0x50cbc0`).
     /// `0.0` for a bounds-less / WMO / model-less display (→ the camera floors it).
     pub(super) pivot_height_local: f32,
     /// How far that framing pivot drops while this body **swims**, model-local yards, pre-scale —
@@ -251,25 +251,25 @@ pub(crate) struct DisplayModel {
     pub(super) swim_pivot_drop_local: f32,
     /// The target selection-ring radius in **model-local yards, pre-scale**: the Stand-animation footprint
     /// `sqrt(0.5 · sqrt(dx² + dy²))` ([`M2Bounds::ring_footprint`]). The ring's world radius is this × the
-    /// unit's `OBJECT_FIELD_SCALE_X` (wow-re selection-ring RE, `0x608e00`/`0x60aee0`, emulated to the
+    /// unit's `OBJECT_FIELD_SCALE_X` (`0x608e00`/`0x60aee0`, emulated to the
     /// reference pixels). `0.0` for a bounds-less / WMO / model-less display (the ring then uses a fallback).
     pub(super) ground_radius_local: f32,
-    /// The model's authored **portrait camera** (wow-re portrait-render §4), captured with `parts` on
+    /// The model's authored **portrait camera** (`0x713540`), captured with `parts` on
     /// load — the exact rig the portrait booth frames through. `None` for WMO / model-less / the few
     /// camera-less M2s (the booth then falls back to heuristic framing).
     pub(super) portrait_camera: Option<benilla_assets::PortraitCamera>,
     /// The model's **model-frame pane camera** — raw camera-table index 1, the rig a 1.12
-    /// `<PlayerModel>` widget renders through (wow-re `ui/scratch/modelframe-camera-law.md`;
+    /// `<PlayerModel>` widget renders through (`0x505890`;
     /// [`benilla_assets::M2Model::pane_camera`]). Captured with `parts` on load. `None` for WMO /
     /// model-less / a model with fewer than two cameras — the body booth then uses the client's own
     /// FIXED fallback camera instead.
     pub(super) pane_camera: Option<benilla_assets::PortraitCamera>,
-    /// A bow display's `$WTT`/`$WTB` bowstring anchors (wow-re `nocked-ammo-cancel.md` §G2),
+    /// A bow display's `$WTT`/`$WTB` bowstring anchors (`0x611ff0`),
     /// captured with `parts`: `[top, bottom]` as `(bone, model-local Bevy position)`. The held-item
     /// attach marks the prop root with them so the string drawer can span the tips. `None` for
     /// every non-bow model.
     pub(super) string_anchors: Option<[(u16, Vec3); 2]>,
-    /// The fishing pole's `$CCH` line anchor (wow-re `fishing-line.md`), mesh-frame Bevy space,
+    /// The fishing pole's `$CCH` line anchor (`0x61f780`), mesh-frame Bevy space,
     /// captured with `parts`. The held-item attach marks the mainhand prop with it so the line
     /// drawer can span rod tip → bobber. `None` for every model that doesn't author it.
     pub(super) cch_marker: Option<Vec3>,
@@ -278,7 +278,7 @@ pub(crate) struct DisplayModel {
     /// text at `feet + scale × this × 1.25`). `0.0` for a bounds-less display.
     pub(super) bbox_z_local: f32,
     /// The **Stand animation** box's z-extent (model-local yards, pre-scale) — the CHAT BUBBLE's
-    /// anchor height (`0x711a20`, wow-re 2026-08-17; 1406). Distinct from `bbox_z_local` above,
+    /// anchor height (`0x711a20`; 1406). Distinct from `bbox_z_local` above,
     /// which is the all-animation vertex box, and from the posed PlayerName attachment the overhead
     /// NAME uses: this one is a file constant, queried once and cached, so the bubble's height
     /// cannot move with the pose. `0.0` for a bounds-less display.
@@ -287,16 +287,15 @@ pub(crate) struct DisplayModel {
     /// reference point for a GameObject's footprint bake (the byte-cited `[def+0x5c]` anchor
     /// family; `benilla_world::interior`). `Vec3::ZERO` for a bounds-less / WMO / model-less display.
     pub(super) bake_center_local: Vec3,
-    /// The model's terrain-conform gate — MD20 `GlobalModelFlags & 3` (wow-re `terrain-tilt.md`,
-    /// §5): `1` = pitch to slope, `3` = pitch+roll, else level. Captured with `parts` on load;
+    /// The model's terrain-conform gate — MD20 `GlobalModelFlags & 3` (`0x7106c0`): `1` = pitch to
+    /// slope, `3` = pitch+roll, else level. Captured with `parts` on load;
     /// `0` for WMO / model-less / still-loading displays.
     pub(super) terrain_tilt: u8,
     /// Whether this display resolves to a **character body** (a `Character\…` model path) — the
     /// gate for the char-customization pipeline (geoset filter + skin composite). The look follows
     /// the DISPLAY, not the entity kind (decision 0695): a druid in bear form is a Player-kind
     /// entity wearing a plain creature model, and the reference's own race/gender getters answer
-    /// from the display's cached row, not the unit's descriptor (wow-re `w2d2.md`'s `0x60c690`
-    /// getter family).
+    /// from the display's cached row, not the unit's descriptor (the `0x60c690` getter family).
     pub(super) is_character_body: bool,
 }
 
@@ -476,13 +475,13 @@ pub(super) fn build_parts(
             // Target selection-ring radius (model-local, pre-scale): the **Stand-animation footprint**
             // `sqrt(0.5 × sqrt(dx² + dy²))` ([`M2Bounds::ring_footprint`], dx/dy = the Stand sequence
             // box's horizontal extents). This is the exact model-local input the real client's living-unit
-            // ring uses (wow-re selection-ring RE, `0x608e00`/`0x60aee0` — byte-verified + emulated to the
+            // ring uses (`0x608e00`/`0x60aee0`, emulated to the
             // reference pixels); the ring's world radius = this × OBJECT_FIELD_SCALE_X. NOT the render
             // sphere (`0xCC`) — that is the *corpse* decal's source (`0x5d6fe0`); the nested-sqrt footprint
             // is why the sphere never fit (it over-sized tall humans, under-sized the squat chicken).
             ground_radius_local = model.bounds.map_or(0.0, |b| b.ring_footprint);
             // Camera framing-pivot height (model-local, pre-scale), the reference's follow-camera target
-            // (`0x50cbc0`, wow-re `follow-camera`): **attachment id 17's Z + 0.0972** when present (every
+            // (`0x50cbc0`): **attachment id 17's Z + 0.0972** when present (every
             // character model has it → ~neck height, e.g. 1.90 human / 0.88 gnome), else the fallback
             // `0.9 × vertex-box Z-extent` for a non-character model. The vertex box alone is the WRONG
             // source for characters — it's the all-animation extent (a human's is ~3.8, way over the
diff --git a/crates/benilla-app/src/entities/equipment/mod.rs b/crates/benilla-app/src/entities/equipment/mod.rs
index 82ed4e7f..1921ab37 100644
--- a/crates/benilla-app/src/entities/equipment/mod.rs
+++ b/crates/benilla-app/src/entities/equipment/mod.rs
@@ -14,7 +14,7 @@
 //! - **Attach** ([`attach_held_items`]) — spawn each resolved item's model as a child of the body's
 //!   **attach-point joint entity** (via [`BoneAttach`], inserted by the visual attach), so it rides the
 //!   hand/hip/back bone through every animation — the modern analogue of the client's attach-transform
-//!   install (`0x47a380`, wow-re charactermodel). The item model itself is a static mesh: its origin
+//!   install (`0x47a380`). The item model itself is a static mesh: its origin
 //!   *is* the grip, aligned by the attach bone's animated frame.
 //!
 //! Item models cache per **item display id** in [`ItemDisplays`] (a [`DisplayModel`] like creatures/
@@ -79,13 +79,13 @@ pub(crate) mod attach_id {
     pub(crate) const HIP_MAIN: u16 = 32;
     pub(crate) const HIP_OFF: u16 = 33;
     /// HandArrow (35, bone 126 — flag-0x04 ignore-parent-rotation) — the in-hand nocked arrow's
-    /// ONE body-bone attach (wow-re `nocked-ammo-cancel.md` §E2: `0x712f70(body, 0x23)` from
-    /// `0x60ba30`/the `$BWP` BowPull handler; bow/wand only). The old Special2/Special3 (0x18/
-    /// 0x19) reading is REFUTED — those are the `0x479f40` model-DIRECTORY selectors
-    /// (`Item\ObjectComponents\Ammo\` vs `…\Weapon\`), never attach ids (§E1).
+    /// ONE body-bone attach (`0x712f70(body, 0x23)` from `0x60ba30`/the `$BWP` BowPull handler;
+    /// bow/wand only). The old Special2/Special3 (0x18/0x19) reading is REFUTED — those are the
+    /// `0x479f40` model-DIRECTORY selectors (`Item\ObjectComponents\Ammo\` vs `…\Weapon\`), never
+    /// attach ids.
     pub(crate) const HAND_ARROW: u16 = 0x23;
-    /// The quiver-on-back attach (wow-re §H2, byte-verified 3×): the worn ammo container's
-    /// model parents at M2 attachment id 26 — the same point the stowed two-hander family uses.
+    /// The quiver-on-back attach (`0x479c50`): the worn ammo container's model parents at M2
+    /// attachment id 26 — the same point the stowed two-hander family uses.
     pub(crate) const QUIVER: u16 = 26;
 }
 
@@ -126,7 +126,7 @@ pub(crate) struct Equipment {
     /// The back slot's display id (0 = no cloak) — a geoset + runtime cape texture, no body region.
     pub(crate) cloak: u32,
     /// The head slot's display id (0 = no helm) — an attach sub-model, plus the HelmetGeosetVisData
-    /// hide-masks that tuck hair/facial/ears under it (wow-re RF-0083).
+    /// hide-masks that tuck hair/facial/ears under it (`0x4799a0`).
     pub(crate) helm: u32,
     /// The wearer's guild tabard (decision 1704) — the emblem five, joined off their own PUBLIC
     /// `PLAYER_GUILDID` against the guild identity cache. `None` for a guildless player **and**
@@ -137,7 +137,7 @@ pub(crate) struct Equipment {
     /// wears*: the composite key includes it, so the re-dress diff below is the one place a change
     /// of guild, of tabard, and a late-arriving identity all converge — no second latch.
     pub(crate) emblem: Option<benilla_formats::GuildEmblem>,
-    /// The tabard designer's preview (decision 1977, wow-re RF-0089 §7c `[cc+0xc]`): set on the
+    /// The tabard designer's preview (decision 1977, `[cc+0xc]` via `0x5e07d0`): set on the
     /// LOCAL player's body while the designer is open, so the body wears the tabard geoset over an
     /// empty slot and the composite paints `emblem` (the design under preview) onto it.
     pub(crate) tabard_preview: bool,
@@ -183,13 +183,13 @@ pub(super) struct HeldItems {
 }
 
 /// Total attach sub-model slots: the 3 held + helm + shoulder L/R + the nocked ammo + the
-/// worn quiver (self-only, ranged-drawn — wow-re `nocked-ammo-cancel.md` §H).
+/// worn quiver (self-only, ranged-drawn — `0x611e10`).
 pub(super) const ATTACH_SLOTS: usize = 8;
 
-/// **What the disarm reflex left attached** (decision 1863; wow-re `disarm-weapon-gate-law.md`
-/// §6, byte-verified). The reference's attachment state is built by *events*, not recomputed from
-/// the descriptor, and disarm is where that difference becomes visible — so this is the one piece
-/// of latched attachment state the equipment layer keeps.
+/// **What the disarm reflex left attached** (decision 1863). The reference's attachment state is
+/// built by *events*, not recomputed from the descriptor, and disarm is where that difference
+/// becomes visible — so this is the one piece of latched attachment state the equipment layer
+/// keeps.
 ///
 /// `UNIT_FIELD_FLAGS`' change reflex `0x5ff580` runs when the DISARM bit **changes**
 /// (`0x5ff619 test edi,eax`), for observed remote units as well as our own body, and when the bit
@@ -279,7 +279,7 @@ pub(crate) enum ItemModelKind {
     /// rule (its module docs): a display with `model[0]` is a thrown weapon in `Weapon\`; one
     /// with only `model[1]` is an arrow/bullet in `Ammo\`.
     Ammo,
-    /// The worn ammo container on the back (wow-re §H2): `Quiver\model[0]` + its own
+    /// The worn ammo container on the back (`0x479c50`): `Quiver\model[0]` + its own
     /// `model_texture[0]` skin, parented at attachment 26 while the ranged weapon is drawn.
     Quiver,
 }
diff --git a/crates/benilla-app/src/entities/equipment/resolve.rs b/crates/benilla-app/src/entities/equipment/resolve.rs
index 236d00ae..17061b20 100644
--- a/crates/benilla-app/src/entities/equipment/resolve.rs
+++ b/crates/benilla-app/src/entities/equipment/resolve.rs
@@ -27,12 +27,11 @@ use super::{
 /// Drawn: the unit's sheath state (`UNIT_FIELD_BYTES_2` byte 0: 0 stowed · 1 melee · 2 ranged) draws
 /// the matching slots into the hands (shield → forearm). Stowed: the **item's** sheath type picks the
 /// body point — 1 two-hander → back · 2 staff → lower back · 3 one-hander → hip · 4 shield → centre
-/// back (mainhand takes the `K−1` side of each pair — byte-verified: `0x47a070`'s `dl != 0` is the
-/// mainhand bodyslot `0xf`, wow-re `ranged-sheath-display.md`, decision 0370). A sheathed ranged
-/// weapon renders **nothing** — the client detaches it rather than re-pointing it to a body bone
-/// (byte-verified `0x7130a0`: a pure unlink/release, uniform across bow/gun/crossbow/thrown/wand;
-/// wow-re `ranged-sheath-display.md`). Drawn ranged splits by inventory type: a **bow** rides the
-/// left hand, gun/crossbow/wand/thrown the right (`0x611e10`'s invType test, same note).
+/// back (mainhand takes the `K−1` side of each pair — `0x47a070`'s `dl != 0` is the mainhand
+/// bodyslot `0xf`, decision 0370). A sheathed ranged weapon renders **nothing** — the client
+/// detaches it rather than re-pointing it to a body bone (`0x7130a0`: a pure unlink/release,
+/// uniform across bow/gun/crossbow/thrown/wand). Drawn ranged splits by inventory type: a **bow**
+/// rides the left hand, gun/crossbow/wand/thrown the right (`0x611e10`'s invType test).
 pub(in crate::entities) fn placement(
     slot: usize,
     inv_type: u32,
@@ -88,10 +87,10 @@ fn enchant_fold(
         .fold(0i32, |acc, e| acc.wrapping_mul(31).wrapping_add(e as i32))
 }
 
-/// The nocked ammo's attach point (wow-re `nocked-ammo-cancel.md` §E2/E5, byte-verified): the
-/// ONE body-bone attach in the whole mechanism is HandArrow (35), fired for a **bow** once its
-/// BowPull event latches `[+0xd58]&0x4000` — `nock_latched` is [`NockLatch`], driven by the real
-/// `$BWP`/`$BWR` listener (`drive_nock_latch`, decision 0408). Everything else shows NO nocked
+/// The nocked ammo's attach point (`0x60ba30`): the ONE body-bone attach in the whole mechanism is
+/// HandArrow (35), fired for a **bow** once its BowPull event latches `[+0xd58]&0x4000` —
+/// `nock_latched` is [`NockLatch`], driven by the real `$BWP`/`$BWR` listener
+/// (`drive_nock_latch`, decision 0408). Everything else shows NO nocked
 /// model: gun/crossbow hit the client's `gunXbow` early return, thrown resolves the `0x19`
 /// *directory* (its own weapon-model copy) but fails the `==0x18` attach gate, and a wand's
 /// Shoot has no ammo item.
@@ -139,7 +138,7 @@ pub(in crate::entities) struct ResolveKey {
 
 /// The **dress** half of the same resolve — [`ResolveKey`]'s complement, and the reason it is a
 /// separate component: a model widget's duplicate is re-taken on a *dress* change and not on a
-/// *placement* one (wow-re `ui/scratch/paperdoll-liveness-law.md`; `crate::portrait::SnapKey`).
+/// *placement* one (`0x5dee30`; `crate::portrait::SnapKey`).
 ///
 /// Everything here is read **before** [`placement`], which is the whole point. The three weapon
 /// slots are the only ones whose very *presence* a sheath state can decide — a stowed ranged
@@ -203,11 +202,14 @@ pub(in crate::entities) fn resolve_equipment(
     // The enchant column rides its own resource (decision 0915) — shared with the tooltip lane.
     glows: Option<ResMut<ItemGlows>>,
     enchants: Option<Res<crate::items::Enchants>>,
-    // The [`Items`] epochs as of the last run — the skip gate's global half. Deliberately the
-    // explicit counters and never resource change ticks: `templates` is `ResMut` in this very
-    // system (ask-once misses write it), so a tick gate would read its own writes and never
-    // close.
-    mut last_epochs: Local<Option<(u64, u64, u64)>>,
+    // The [`Items`] template epoch as of the last run — the skip gate's global half. Deliberately
+    // the explicit counter and never the resource's change tick: `templates` is `ResMut` in this
+    // very system (ask-once misses write it), so a tick gate would read its own writes and never
+    // close. The item *objects* are entities since 2334, watched through `item_changes`.
+    mut last_epochs: Local<Option<(u64, u64)>>,
+    // The object lookup the equipped guids resolve through and the item entities' change watch,
+    // as one param (the 16-SystemParam ceiling).
+    item_objects: (crate::net::Objects, crate::items::ItemChanges),
     // The guild identity cache (decision 1257) — `ResMut` because it is LAZY: the miss below is
     // what sends the `CMSG_GUILD_QUERY` whose answer paints the tabard. `Option` for the same
     // reason `creatures` is: a harness without the UI plugins still resolves equipment.
@@ -222,11 +224,14 @@ pub(in crate::entities) fn resolve_equipment(
     // a `CMSG_GUILD_QUERY` answered three frames after a player spawned changes what that player's
     // tabard paints, and nothing about their descriptor or the item cache moves to say so.
     let epochs = (
-        templates.object_epoch(),
         templates.template_epoch(),
         guilds.as_ref().map_or(0, |g| g.identity_generation()),
     );
+    // The watch is drained whether or not the gate is read (`moved` reads the removals).
+    let (objects, mut item_changes) = item_objects;
+    let items_moved = item_changes.moved();
     let caches_moved = last_epochs.replace(epochs) != Some(epochs)
+        || items_moved
         || creatures.as_ref().is_some_and(|c| c.is_changed())
         || enchants.as_ref().is_some_and(|e| e.is_changed())
         || tabard_design.as_ref().is_some_and(|d| d.is_changed());
@@ -282,12 +287,12 @@ pub(in crate::entities) fn resolve_equipment(
         // The suppression is a **display id of zero**, applied below to every place the piece is
         // resolved — which is the same thing "no helm equipped" means everywhere else in this
         // module, so the whole downstream chain follows for free: the helm's attach sub-model is not
-        // requested, its RF-0083 HelmetGeosetVisData hide-masks are not applied (hair, facial hair
-        // and ears come back), the cloak's geoset group is not selected and its cape texture is not
-        // resolved. It is also the shape the glue lane has honoured since 0465 (`attach::preview`
-        // zeroes the same two slots off the char-enum record's `CHARACTER_FLAG_HIDE_*`, which
-        // vmangos round-trips into these very bits at login) — the world was the half that never
-        // consumed it.
+        // requested, its `0x4799a0` HelmetGeosetVisData hide-masks are not applied (hair, facial
+        // hair and ears come back), the cloak's geoset group is not selected and its cape texture
+        // is not resolved. It is also the shape the glue lane has honoured since 0465
+        // (`attach::preview` zeroes the same two slots off the char-enum record's
+        // `CHARACTER_FLAG_HIDE_*`, which vmangos round-trips into these very bits at login) — the
+        // world was the half that never consumed it.
         let (hide_helm, hide_cloak) = (s.player_hides_helm(), s.player_hides_cloak());
         // Worn armor (players; decision 0074): resolve the composite slots' entries → display ids.
         // `settled` only once every non-empty entry has an answer, so the first attach composites the
@@ -317,8 +322,9 @@ pub(in crate::entities) fn resolve_equipment(
                     None => eq.settled = false,
                 }
             }
-            // The helm (equipment slot 0): attach model + the RF-0083 hide-masks (its geoset effect
-            // — a hair/facial/ears change — rides the Equipment diff, so donning one re-attaches).
+            // The helm (equipment slot 0): attach model + the `0x4799a0` hide-masks (its geoset
+            // effect — a hair/facial/ears change — rides the Equipment diff, so donning one
+            // re-attaches).
             if let Some(entry) = s.player_visible_item_entry(0).filter(|e| *e != 0) {
                 match templates.held(entry, &net) {
                     Some(t) => eq.helm = t.display_info_id,
@@ -363,7 +369,7 @@ pub(in crate::entities) fn resolve_equipment(
         };
         // A player wearing a NON-character display (druid form, GM morph — decision 0695)
         // attaches no equipment sub-models at all: the reference's held/helm/shoulder attach
-        // lives on the CCharacterComponent (`0x47a0c0`, wow-re charactermodel node), which only
+        // lives on the CCharacterComponent (`0x47a0c0`), which only
         // a character body builds — a bear-form druid shows no weapon by construction, not by a
         // hide flag. [`Wielded`] (the anim-class pair) still resolves below: what's IN the hand
         // is independent of whether its model is displayed. The creature virtual-item path (a
@@ -552,8 +558,7 @@ pub(in crate::entities) fn resolve_equipment(
         if current_dress != Some(&dress) {
             commands.entity(entity).insert(dress);
         }
-        // The nocked ammo (byte-verified `0x60ba30` + the Q-E round, wow-re
-        // `nocked-ammo-cancel.md` §E2/E5): the ONE body-bone attach in the whole mechanism is
+        // The nocked ammo (`0x60ba30`): the ONE body-bone attach in the whole mechanism is
         // HandArrow (35), **bow-only** — gun/crossbow (`gunXbow` early return) and thrown
         // (directory selector `0x19`, never an attach id) show NO nocked model. The [`NockedAmmo`]
         // display is written per shot from `SMSG_SPELL_START`, any caster; the attach follows the
@@ -588,13 +593,13 @@ pub(in crate::entities) fn resolve_equipment(
                 visual,
             });
         }
-        // The quiver on the back (wow-re `nocked-ammo-cancel.md` §H, byte-verified): while the
-        // RANGED weapon is drawn — the same `0x611e10` ranged-draw transition, cleared on every
-        // other ranged state — the client scans the player's OWN inventory for an ItemClass-11
-        // container (Quiver/Ammo Pouch) and parents its display model at attachment 26 (no
-        // transform override; no cloak conflict). Self-only by construction, exactly like the
-        // client: bag slots are never replicated in 1.12, so a remote player's scan finds
-        // nothing (§H1 — a two-client capture would be the clean confirmation).
+        // The quiver on the back: while the RANGED weapon is drawn — the same `0x611e10`
+        // ranged-draw transition, cleared on every other ranged state — the client scans the
+        // player's OWN inventory for an ItemClass-11 container (Quiver/Ammo Pouch) and parents its
+        // display model at attachment 26 (no transform override; no cloak conflict). Self-only by
+        // construction, exactly like the client: bag slots are never replicated in 1.12, so a
+        // remote player's scan finds nothing (a two-client capture would be the clean
+        // confirmation).
         // Timed off the RANGED slot's own visual state, so the quiver arrives with the bow it
         // feeds. (Named deviation: the ref attaches it at the *start* of the ranged draw — the
         // `0x611e10(1)` call inside each drawer — where ours waits for that clip's $SHL. Same
@@ -607,7 +612,7 @@ pub(in crate::entities) fn resolve_equipment(
             for bag in 19u8..23 {
                 let entry = s
                     .player_inv_slot(bag)
-                    .and_then(|g| templates.object(g))
+                    .and_then(|g| objects.object(g))
                     .and_then(|o| o.object_entry());
                 let Some(t) = entry.and_then(|e| templates.held(e, &net)) else {
                     continue;
@@ -686,9 +691,9 @@ pub(in crate::entities) fn resolve_equipment(
             }
         }
         let next = HeldItems { slots };
-        // Per-hand grip: a weapon in a hand's attach point curls that hand's fingers (wow-re
-        // `hand-grip-mechanism.md`) — mainhand → right (id 1), non-shield offhand → left (id 2); a
-        // forearm shield (id 0) or an empty hand stays open. Drives [`HandGrip`]'s finger overlay.
+        // Per-hand grip: a weapon in a hand's attach point curls that hand's fingers (`0x60b590`)
+        // — mainhand → right (id 1), non-shield offhand → left (id 2); a forearm shield (id 0) or
+        // an empty hand stays open. Drives [`HandGrip`]'s finger overlay.
         let grip = HandGrip {
             right: next
                 .slots
@@ -734,10 +739,9 @@ pub(in crate::entities) fn resolve_equipment(
 /// **Three slots never dress**, and the two shapes are different:
 /// - slot 0 (head) when this corpse's own `CORPSE_FLAG_HIDE_HELM 0x08` is set, and slot 14 (back)
 ///   when `HIDE_CLOAK 0x10` is (`0x5d6465`/`0x5d6470` — its own bits on its own field, snapshotted
-///   from `PLAYER_FLAGS` at death; wow-re `helm-cloak-hide.md` §2b). Suppression is a display id of
-///   **zero**, the same shape the player lane uses (decision 1472), so the whole downstream chain —
-///   the helm's attach model, its RF-0083 hide-masks, the cloak's geoset and cape texture — follows
-///   for free.
+///   from `PLAYER_FLAGS` at death). Suppression is a display id of **zero**, the same shape the
+///   player lane uses (decision 1472), so the whole downstream chain — the helm's attach model, its
+///   `0x4799a0` hide-masks, the cloak's geoset and cape texture — follows for free.
 /// - slots 15/16/17 (mainhand, offhand, ranged) — **always**. Ranged is skipped outright
 ///   (`0x5d644e`); the two weapon slots take a branch that looks up the packed item word as an
 ///   *object guid* (`0x5d649b` → `0x468460`, typemask 2) and can therefore never resolve. A corpse
@@ -796,7 +800,7 @@ pub(in crate::entities) fn resolve_corpse_equipment(
             // The guild tabard crest, from the corpse's OWN `CORPSE_FIELD_GUILD` snapshot — the
             // reference's `0x5d6ec0`, reached from the dress loop at the tabard slot (`ebx == 0x12`
             // with that display's `ItemDisplayInfo` flag bit 0) and resolved through the same
-            // name cache a living body's is (wow-re `corpse-decal-and-loot-sparkle.md` §6b). A
+            // name cache a living body's is (`0x6d6d20`). A
             // bone pile builds no character component, so it never reaches this leg — which is
             // exactly where this sits.
             eq.emblem = guilds
@@ -990,8 +994,8 @@ mod tests {
         assert_eq!(placement(0, 21, 3, 1), Some(attach_id::HAND_RIGHT));
     }
 
-    /// The nocked-ammo attach law (`0x60ba30`, wow-re `nocked-ammo-cancel.md` §E2, decision
-    /// 0408): HandArrow (35) is the ONE attach, bow-only, gated on the `$BWP` nock latch.
+    /// The nocked-ammo attach law (`0x60ba30`, decision 0408): HandArrow (35) is the ONE attach,
+    /// bow-only, gated on the `$BWP` nock latch.
     /// Gun/crossbow/thrown never attach a nocked model.
     #[test]
     fn ammo_attach_hands_the_volleying_bow_arrow_and_nothing_else() {
@@ -1039,6 +1043,8 @@ mod tests {
         items.insert_template(300, Some(worn(700, 5))); // INVTYPE_CHEST
         let (tx, rx) = crossbeam_channel::unbounded::<ClientCommand>();
         app.insert_resource(items);
+        // The one object index `Objects` reads (2334); empty, like the map these tests never seeded.
+        app.init_resource::<crate::net::GuidIndex>();
         app.insert_resource(NetCommands(tx));
         app.insert_resource(ItemDisplays::icons_for_tests(
             benilla_formats::ItemDisplayCatalog::from_displays(std::collections::HashMap::new()),
@@ -1068,7 +1074,7 @@ mod tests {
     /// **B123** (decision 1472): the two equipment-display preferences are consumed on the WORLD
     /// body, not only on the character-select one. `PLAYER_FLAGS_HIDE_HELM 0x400` /
     /// `HIDE_CLOAK 0x800` zero the resolved display id, which is what makes every downstream
-    /// consumer follow — no cape geoset, no cape texture, no helm attach model, and no RF-0083
+    /// consumer follow — no cape geoset, no cape texture, no helm attach model, and no `0x4799a0`
     /// hide-mask stripping the hair.
     #[test]
     fn the_hide_preferences_undress_the_helm_and_cloak_on_a_world_body() {
@@ -1119,6 +1125,8 @@ mod tests {
         items.insert_template(101, Some(worn(901, 1))); // the swap target
         let (tx, rx) = crossbeam_channel::unbounded::<ClientCommand>();
         app.insert_resource(items);
+        // The one object index `Objects` reads (2334); empty, like the map these tests never seeded.
+        app.init_resource::<crate::net::GuidIndex>();
         app.insert_resource(NetCommands(tx));
         app.insert_resource(ItemDisplays::icons_for_tests(
             benilla_formats::ItemDisplayCatalog::from_displays(std::collections::HashMap::new()),
@@ -1167,13 +1175,12 @@ mod tests {
         drop(rx);
     }
 
-    /// **What a disarm does to the weapon MODEL** (decision 1863; wow-re
-    /// `disarm-weapon-gate-law.md` §6). The reference's attachment state is built by events, and
-    /// `UNIT_FIELD_FLAGS`' change reflex `0x5ff580` is one of them: when the DISARM bit goes up it
-    /// calls `0x47a310(model, 0xf, 0, 0)` — an unlink of the main-hand attachment — **but only
-    /// while the weapon is drawn**, and afterwards every attach site declines because its
-    /// `GetWeapon(slot, 0)` reads NULL. So the weapon does NOT stay in the fist (the older note
-    /// said it did, from a partial read of `0x60b590`), and it does NOT vanish off the back
+    /// **What a disarm does to the weapon MODEL** (decision 1863). The reference's attachment
+    /// state is built by events, and `UNIT_FIELD_FLAGS`' change reflex `0x5ff580` is one of them:
+    /// when the DISARM bit goes up it calls `0x47a310(model, 0xf, 0, 0)` — an unlink of the
+    /// main-hand attachment — **but only while the weapon is drawn**, and afterwards every attach
+    /// site declines because its `GetWeapon(slot, 0)` reads NULL. So the weapon does NOT stay in
+    /// the fist (as `0x60b590` read alone would suggest), and it does NOT vanish off the back
     /// either. Three cases, one body each.
     #[test]
     fn a_disarm_takes_a_drawn_weapon_off_the_hand_and_leaves_a_stowed_one() {
@@ -1216,6 +1223,8 @@ mod tests {
             );
             let (tx, rx) = crossbeam_channel::unbounded::<ClientCommand>();
             app.insert_resource(items);
+            // The one object index `Objects` reads (2334); empty, like the map these tests never seeded.
+            app.init_resource::<crate::net::GuidIndex>();
             app.insert_resource(NetCommands(tx));
             app.insert_resource(ItemDisplays::icons_for_tests(
                 benilla_formats::ItemDisplayCatalog::from_displays(
@@ -1333,6 +1342,8 @@ mod tests {
         );
         let (tx, rx) = crossbeam_channel::unbounded::<ClientCommand>();
         app.insert_resource(items);
+        // The one object index `Objects` reads (2334); empty, like the map these tests never seeded.
+        app.init_resource::<crate::net::GuidIndex>();
         app.insert_resource(NetCommands(tx));
         app.insert_resource(ItemDisplays::icons_for_tests(
             benilla_formats::ItemDisplayCatalog::from_displays(std::collections::HashMap::new()),
diff --git a/crates/benilla-app/src/entities/equipment/spawn.rs b/crates/benilla-app/src/entities/equipment/spawn.rs
index acf79447..2160744f 100644
--- a/crates/benilla-app/src/entities/equipment/spawn.rs
+++ b/crates/benilla-app/src/entities/equipment/spawn.rs
@@ -117,13 +117,13 @@ impl SeatWriters<'_, '_> {
 /// popping in opaque (decision 0032 read as a per-unit property).
 ///
 /// **The diff is per SLOT, and an attach-point change is a MOVE** (decision 0826). The reference's
-/// sheath paths touch only the weapon/quiver attach ids (`0x611770`, wow-re `sheath-policy.md` /
-/// `ranged-sheath-display.md`) and stow a melee weapon by detaching the sub-model and **re-parenting
-/// it** at the sheath point (`0x60b590` → `0x712f70`) — the model instance, and everything riding
-/// it, survives the swap. Rebuilding a unit's whole kit on any change did neither: drawing a sword
-/// respawned the shoulders' and helm's emitters too, and every orphaned pool then lived out its
-/// lifespan FROZEN in world space (`particles::sim`'s drain) — the sparkle cloud that hung behind
-/// the character on every weapon draw and every step of the login gear cascade.
+/// sheath paths touch only the weapon/quiver attach ids (`0x611770`) and stow a melee weapon by
+/// detaching the sub-model and **re-parenting it** at the sheath point (`0x60b590` → `0x712f70`) —
+/// the model instance, and everything riding it, survives the swap. Rebuilding a unit's whole kit
+/// on any change did neither: drawing a sword respawned the shoulders' and helm's emitters too, and
+/// every orphaned pool then lived out its lifespan FROZEN in world space (`particles::sim`'s drain)
+/// — the sparkle cloud that hung behind the character on every weapon draw and every step of the
+/// login gear cascade.
 #[allow(clippy::type_complexity)]
 pub(in crate::entities) fn attach_held_items(
     mut commands: Commands,
@@ -345,7 +345,7 @@ fn spawn_slot(
     // left-hand fork (a bow is the one ranged weapon placed in HAND_LEFT; the client
     // registers the string callback bow-only, from the ranged-draw path). The `$WTT`/
     // `$WTB` anchors alone are NOT the gate — they are generic weapon-TRAIL begin/end
-    // markers (wow-re w2d2: `WTBT`/`WTTT`, the swing-trail vertex build) that melee
+    // markers (`WTBT`/`WTTT`, the swing-trail vertex build `0x6c67f0`) that melee
     // weapons author too; keying on their presence drew a phantom "bowstring" chord
     // across the Whirlwind Axe's blade tips (decision 0531).
     if slot_idx == 2 && hs.attach == attach_id::HAND_LEFT {
@@ -358,7 +358,7 @@ fn spawn_slot(
             });
         }
     }
-    // The **weapon swing trail's** object (wow-re `charproc8-weapon-trail.md` §9, decision 2076)
+    // The **weapon swing trail's** object (decision 2076)
     // — the reference's `WTOBJECT`, built per weapon HAND by `0x608d60` on the model it finds at
     // that hand's attachment and freed with it. This is the first-class consumer decision 0531
     // named and deferred: the `$WTB`/`$WTT` pair is a *trail* marker, and the bowstring above is
@@ -371,7 +371,7 @@ fn spawn_slot(
                 .insert(crate::weapon_trail::WeaponTrail::new(top.1, bottom.1));
         }
     }
-    // The fishing line's near anchor (wow-re `fishing-line.md`, decision 1099): a MAINHAND prop
+    // The fishing line's near anchor (`0x61f780`, decision 1099): a MAINHAND prop
     // whose model authors `$CCH` is the pole (the reference gates on ItemCache {class 2, subclass
     // 20} + the marker's presence; exactly one weapon model in the chain authors the marker, so
     // presence alone is data-equivalent — unlike the bow's trail-marker trap above, which is why
@@ -404,13 +404,13 @@ fn spawn_slot(
     // attach model runs a joint palette. 0847 pulled it believing a spherical billboard swept the
     // spikes through the plate; that was wrong (0853: the spikes run ALONG their bone, worst vertex
     // 12° off axis, so the arc never existed), and the byte answer is that the reference billboards
-    // an attached model exactly as it does a standalone one (wow-re `billboard-bone-law.md` §6).
+    // an attached model exactly as it does a standalone one (`0x718657`–`0x71876f`).
     // A
     // display whose geometry is WELDED to a billboard bone (`welds_billboard`: the R14 pauldron's
     // two spikes, whose root rings are 50/50 with the plate) has no correct rigid placement at all;
     // 0839 stopped tearing it into a card, which left it whole and *still*. The reference bends it
-    // by blending the billboard bone's camera-replaced palette row per vertex (`m2_vertex_skin`,
-    // `0x71a460`) — so we build exactly that: the joint hierarchy, a palette slot, and the
+    // by blending the billboard bone's camera-replaced palette row per vertex (`0x71a460`) — so
+    // we build exactly that: the joint hierarchy, a palette slot, and the
     // [`benilla_world::billboard::BillboardJointRig`] that rewrites the billboard joints' world rotations.
     //
     // Nothing else about the item lane's "rests at bind pose" law moves: no `AnimationPlayer`, no
@@ -595,10 +595,9 @@ fn spawn_slot(
             // yields via its own `Without<RenderFade>`/`Without<PendingAppearFade>` filter, same
             // as a body part.
             // Anchored at the WEARER's root: an equipped item M2 aliases its wearer's
-            // light collector by pointer (`[item+0x3b8]=[wearer+0x3b8]`, `0x718960` —
-            // wow-re `unit-light-combine-storm.md`), so it never runs its own
-            // classify/footprint at the carried position. The animating hand joint
-            // once anchored these, and a swing alone could trip the resample gate and
+            // light collector by pointer (`[item+0x3b8]=[wearer+0x3b8]`, `0x718960`), so it
+            // never runs its own classify/footprint at the carried position. The animating hand
+            // joint once anchored these, and a swing alone could trip the resample gate and
             // split the shield's light from the body's (director-caught, 2026-07-13).
             // The fold reference is the wearer's BODY centre for the same reason.
             //
@@ -627,11 +626,11 @@ fn spawn_slot(
             ) {
                 child.insert(lit);
             }
-            // The batch's authored **material alpha** — the verified combine's `colourAlpha ×
-            // weight` (wow-re `m2-alpha-combine-cull.md`). An attach model spawns no rig of its
-            // own and rests in its file's first sequence, so its loops are PINNED there (the
-            // doodad lane's clock) while the tag compose stays the unit lane's, ordered against
-            // the appear-fade and the interior classifier exactly like the wearer's own batches.
+            // The batch's authored **material alpha** — the combine's `colourAlpha × weight`
+            // (`0x707680`). An attach model spawns no rig of its own and rests in its file's first
+            // sequence, so its loops are PINNED there (the doodad lane's clock) while the tag
+            // compose stays the unit lane's, ordered against the appear-fade and the interior
+            // classifier exactly like the wearer's own batches.
             // Skipping this drew every one of the 321 item models that dim a batch at full
             // strength — the Hungering Cold's five glow cards blaze at 1.0 where the file says
             // 0.30 (decision 0836).
@@ -747,7 +746,7 @@ fn spawn_slot(
     // The booth mirror for those same emitters (decision 0822): they spawn as FREE entities
     // below (the owner contract), never unit descendants, so a booth that mirrors the dressed
     // tree cannot see them — which is why the R14 pauldron's sparkle was absent from the paper
-    // doll exactly as it was from the select screen (`#bugs` B118). One marker per item, on
+    // doll exactly as it was from the select screen. One marker per item, on
     // the root that already reaps with it.
     if !dm.emitters.is_empty() {
         commands
@@ -1177,8 +1176,7 @@ mod tests {
     ///
     /// 0847 withdrew this and pinned the withdrawal with the mirror of this test; both are gone
     /// again. The withdrawal's premise — a spherical billboard sweeping the spikes through the
-    /// plate — was refuted at the geometry (0853) and at the bytes (wow-re
-    /// `billboard-bone-law.md` §6), and
+    /// plate — was refuted at the geometry (0853) and at the bytes (`0x718657`–`0x71876f`), and
     /// [`benilla_world::billboard::tests::a_spike_along_its_bone_axis_points_screen_down_from_every_angle`]
     /// is the standing guard that the arc stays absent in our own basis.
     #[test]
@@ -1411,7 +1409,7 @@ mod tests {
         );
     }
 
-    /// **What a booth can see of an equipped item** (decision 0822, `#bugs` B118's paper-doll half).
+    /// **What a booth can see of an equipped item** (decision 0822, the paper-doll half).
     /// An item model's camera-facing batch spawns as a world-ROOT card and its emitters as free
     /// owner-followed entities — neither is a unit descendant, so the portrait / paper-doll booths,
     /// which mirror the dressed tree, could not see either one and a worn item's effects were absent
diff --git a/crates/benilla-app/src/entities/item_glow.rs b/crates/benilla-app/src/entities/item_glow.rs
index 246e6a32..93719fd8 100644
--- a/crates/benilla-app/src/entities/item_glow.rs
+++ b/crates/benilla-app/src/entities/item_glow.rs
@@ -7,8 +7,7 @@
 //! `ItemDisplayInfo` col 22 → `ItemVisuals` → 5 × `ItemVisualEffects` → a glow `.mdx` per slot
 //! ([`benilla_formats::ItemVisualCatalog`], whose module doc owns the table shapes and the
 //! reference's per-slot skip rules). Two sources feed the id, and the reference resolves exactly
-//! one of them per item (wow-re `object-layer/scratch/item-visual-enchant.md`, byte-verified;
-//! the call sites below were read at the bytes for decision 0805):
+//! one of them per item (the call sites below were read at the bytes for decision 0805):
 //!
 //! - **Intrinsic** — the display's own id, passed by the character's held-item attach:
 //!   `0x47a200: mov edx,[esi+0x58]` → `0x4798c0(…, itemVisualsId)`, which calls the attach
diff --git a/crates/benilla-app/src/entities/live_display.rs b/crates/benilla-app/src/entities/live_display.rs
index f86c37f4..848410a0 100644
--- a/crates/benilla-app/src/entities/live_display.rs
+++ b/crates/benilla-app/src/entities/live_display.rs
@@ -10,8 +10,7 @@
 //! from the new display (`0x60afb0 ResolveDisplayInfo`), and re-selects the stand/ride animation
 //! (`0x60ce70`) — an **instant** swap, no morph transition (the ghost→alive revive swap rides the
 //! same path; a shapeshift's green flash is the spell visual kit, a separate system). The SCALE_X
-//! handler instead **eases the render scale over 2 s with a cosine smoothstep** (byte-verified,
-//! `0x614bbf`). All wow-re: `questgiver-marker.md` §W6, `w2d2.md` §2.x, `object-layer.md`.
+//! handler instead **eases the render scale over 2 s with a cosine smoothstep** (`0x614bbf`).
 //!
 //! Our shape is a diff-and-rebuild: the visual was BUILT with [`AppliedDisplay`], the live truth
 //! is the descriptor store, and a difference tears the visual down for `attach_entity_visuals` to
@@ -47,7 +46,7 @@ pub(super) struct AppliedDisplay(pub(super) Option<u32>);
 
 /// A live display-id swap happened on this entity — the visual was torn down and will rebuild.
 /// The reference's rebuild `0x60abe0` ends by REPLAYING the pending-morph latch's impact kit
-/// (wow-re `shapeshift-morph-cloud.md`); this edge is what carries "the rebuild ran" to that
+/// (`0x60ad67`); this edge is what carries "the rebuild ran" to that
 /// replay (`crate::creature_anim`'s morph-latch watcher), which owns the latch and the kit
 /// resolve. Written only when the rebuild actually fires (the diff branch — our `0x60ae10`).
 #[derive(Message, Clone, Copy)]
diff --git a/crates/benilla-app/src/entities/missile.rs b/crates/benilla-app/src/entities/missile.rs
index e8bc8851..4bfa7aee 100644
--- a/crates/benilla-app/src/entities/missile.rs
+++ b/crates/benilla-app/src/entities/missile.rs
@@ -21,7 +21,7 @@
 //! arrives on the spot — at melee range there is no visible flight or trail at all, just the
 //! impact on the target, exactly the reference's close-range look.
 //!
-//! In flight, the client's **arrive-on-time** mover (`0x61ceb0`/`0x61e2a0`, wow-re `w2f1.md`):
+//! In flight, the client's **arrive-on-time** mover (`0x61ceb0`/`0x61e2a0`):
 //! one entity per target, model parts + particle emitters from the shared [`SpellFx`] path-keyed
 //! cache (the same held-items pattern as the attach-point effects); each frame the missile covers
 //! `remaining distance / remaining time · dt` toward the target's **destination attach point** —
@@ -30,10 +30,9 @@
 //! hand-off `0x61dc50`); arrival on a missed target plays the victim's dodge/block defense clip
 //! instead ([`miss_defense_state`]) and floats the outcome WORD ([`MissileMiss`], decision 2229).
 //!
-//! **`0x61e1d0` picks between THREE arms, and the selector is not the one an earlier reading
-//! recorded** (wow-re `missile-arrival-dispatch.md`; it is not ground-vs-unit): first whether the
-//! missile's target guid still resolves to a live object, then a **HIT bit** — `[missile+0x38] &
-//! 1`, written once image-wide at the spawn `0x60a4e8` from an explicit argument.
+//! **`0x61e1d0` picks between THREE arms, and the selector is not ground-vs-unit**: first whether
+//! the missile's target guid still resolves to a live object, then a **HIT bit** —
+//! `[missile+0x38] & 1`, written once image-wide at the spawn `0x60a4e8` from an explicit argument.
 //!
 //! | arm | reached when | what it does | ours |
 //! |---|---|---|---|
@@ -72,14 +71,14 @@
 //! despawn in every case.//!
 //! A GO with **no unit targets at all** but a point on the wire flies **one** projectile at the
 //! point — the client's location fallback (`0x6e8a50`'s empty-hit-array arm → `0x60a3d0` once,
-//! owning unit slot −1; wow-re `spell-go-dest-effect.md` §3). That is the whole visible flight of
+//! owning unit slot −1). That is the whole visible flight of
 //! a pure ground cast: the hunter's Flare arcing out to where it was placed, a bomb thrown at
 //! empty dirt. Such a missile homes to nothing — its aim is a fixed world point ([`Aim::Ground`])
 //! — and it arrives as [`CastEventKind::GroundImpact`] on the CASTER (`0x61d870`, the
 //! no-live-target arm — see the dispatch table above), never through the unit hand-off. Named approximation: it flies the same straight
 //! arrive-on-time line a unit missile does; the reference's trajectory *class* comes from
-//! `CMissile+0x48` through `0x61d720`'s remap table, whose wire origin wow-re traced to
-//! consumption only — so a lobbed shot reads as a straight glide here.
+//! `CMissile+0x48` through `0x61d720`'s remap table, whose wire origin is still open — so a lobbed
+//! shot reads as a straight glide here.
 
 use bevy::animation::transition::AnimationTransitions;
 use bevy::ecs::entity::EntityHashMap;
@@ -124,7 +123,7 @@ const DEST_FALLBACKS: [u16; 2] = [0xf, 0x13];
 const INFLIGHT_ANIM: u16 = 144;
 
 /// The missile's orientation for flight direction `f` (Bevy space) — the client's exact frame
-/// build (`0x61e2a0`, wow-re `w2f1.md`): model **+X = the flight direction**, side = up × dir,
+/// build (`0x61e2a0`): model **+X = the flight direction**, side = up × dir,
 /// up re-orthogonalized as dir × side — i.e. NO roll, model-up stays world-up-ish however the
 /// flight pitches. (A shortest-arc rotation rolls on pitched flight, which would tilt the trail
 /// ribbons' authored + cross.) In Bevy terms: local −Z (the wow_to_bevy image of wow +X) → `f`,
@@ -141,7 +140,7 @@ fn missile_facing(f: Vec3) -> Quat {
     Quat::from_mat3(&Mat3::from_cols(f.cross(up), up, -f))
 }
 
-/// The projectile's in-flight LOOP sound (`SpellVisual` field 10, wow-re `w2f1.md`'s
+/// The projectile's in-flight LOOP sound (`SpellVisual` field 10, the reference's
 /// `CMissile+0x44` loop handle): a channel tracked to the missile entity — it follows the
 /// projectile as it flies and is reaped when the projectile arrives or streams out. Written by
 /// [`spawn_missiles`]/[`move_missiles`]; consumed by `crate::sound::missile`.
@@ -173,7 +172,7 @@ enum Aim {
         /// `None` — the spell landed: arrival plays the impact hand-off. `Some(code)` — the wire's
         /// `SpellMissInfo` miss: arrival instead plays the victim's defense clip for DODGE(3)/
         /// BLOCK(5) (the client's `Missile_C::Update 0x61ceb0` dispatch — Dodge 30 / ShieldBlock
-        /// 24, never Parry; wow-re `smsg-attackerstate-consequences.md` §Q4) and no impact kit.
+        /// 24, never Parry) and no impact kit.
         miss: Option<u8>,
     },
     /// A fixed world point — the GO's dest, with no unit to home to and nothing that can make the
@@ -294,12 +293,11 @@ struct QueuedGo {
 /// Every caster's pending queue (the client's per-unit `+0xac` list heads). A caster that
 /// streams out drops its queue with it.
 ///
-/// **It is also a GATE, not only a queue** (decision 2288, wow-re
-/// `missile-queue-gates-the-release-event.md`). `[CGUnit+0xac]` holds `CMissile` nodes — the
-/// binary names them itself (`Missile_C.cpp`) — inserted by the missile spawner `0x60a3d0` and
-/// drained by the release event, and the `$BWR` handler reads it *before* draining it
-/// (`0x600182 mov eax,[esi+0xac]; test eax,eax; je 0x600299`). Everything between those two points
-/// — the ranged prop's own re-anim and the cast-sound reposition — happens **only when a
+/// **It is also a GATE, not only a queue** (decision 2288). `[CGUnit+0xac]` holds `CMissile`
+/// nodes — the binary names them itself (`Missile_C.cpp`) — inserted by the missile spawner
+/// `0x60a3d0` and drained by the release event, and the `$BWR` handler reads it *before* draining
+/// it (`0x600182 mov eax,[esi+0xac]; test eax,eax; je 0x600299`). Everything between those two
+/// points — the ranged prop's own re-anim and the cast-sound reposition — happens **only when a
 /// projectile is actually waiting to be released**. So a shot's flex and its launch are two
 /// effects of one act, and a consumer that arms the prop without asking this has half a mechanism.
 #[derive(Resource, Default)]
@@ -422,8 +420,8 @@ fn launch_outcome_code(code: u8) -> u8 {
 /// `select::defense_anim`): DODGE(3) → the dodge state (Dodge 30), BLOCK(5) → the block state
 /// (ShieldBlock 24). Every other code — miss/resist/evade/immune/deflect — plays nothing, and
 /// PARRY(4) can never reach here at all: [`launch_outcome_code`] has already rewritten it to
-/// DEFLECT(9), which is the mechanism behind the recorded negative that a ranged arrival never
-/// parries (wow-re `smsg-attackerstate-consequences.md` §Q4).
+/// DEFLECT(9), which is the mechanism behind the negative that a ranged arrival never parries
+/// (`0x61ceb0`).
 fn miss_defense_state(code: u8) -> Option<u32> {
     match code {
         3 => Some(2), // SPELL_MISS_DODGE → the dispatch's DODGES state
@@ -436,7 +434,7 @@ fn miss_defense_state(code: u8) -> Option<u32> {
 /// Bevy's 16-`SystemParam` ceiling, and these three are one concern anyway: everything a
 /// projectile emits at the moment it lands — the router's impact/ground event, the victim's
 /// defense clip, and the deferred outcome word. Bundled for the same reason
-/// [`crate::ui_chat::combat::CombatFeedbackCvars`] is, so the call sites read `out.words` rather
+/// the combat log's CVar context ([`crate::combat_log::Ctx`]) is, so the call sites read `out.words` rather
 /// than a positional tuple field.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(super) struct ArrivalOut<'w> {
diff --git a/crates/benilla-app/src/entities/mount.rs b/crates/benilla-app/src/entities/mount.rs
index 237c4205..9355e936 100644
--- a/crates/benilla-app/src/entities/mount.rs
+++ b/crates/benilla-app/src/entities/mount.rs
@@ -8,14 +8,14 @@
 //!
 //! ## The transition is a RE-SEAT, not a rebuild (B199)
 //!
-//! **VERIFIED** — wow-re `mount-composition.md` Q3/Q4, byte-cited: the change handler `0x5ffa50`
-//! runs *teardown old, then build new*, and neither half touches the rider's own model.
+//! The change handler `0x5ffa50` runs *teardown old, then build new*, and neither half touches the
+//! rider's own model.
 //!
 //! - **Mount up, `0x607a00`:** load the mount M2 → `0x613d80 SetMountModel` into `CGUnit+0xdc` →
 //!   `0x712f70 CM2Model::attachChild(this = BODY [+0xd8], parent = MOUNT, slot 0)`, which sets
 //!   `body+0x1cc = mount` and links the body into the mount's child list. The **body model is
 //!   re-parented, not re-created**; its world matrix is recomposed each frame from the mount's live
-//!   posed attachment-0 bone (`m2_animate`'s child recursion `0x718657`–`0x71876f`).
+//!   posed attachment-0 bone (the animate kernel's child recursion `0x718657`–`0x71876f`).
 //! - **Dismount, `0x607ce0`:** `0x713020` **detaches** the body, `0x613d80(0)` destroys the mount
 //!   model, the body goes to op4 seq 0 (Stand). Instant, no transition anim — and again the body
 //!   model itself is untouched.
@@ -65,8 +65,7 @@ pub(super) struct AppliedMount(pub(super) u32);
 /// Spawn a unit's mount child — the client's `0x607a00` model creation. Its `NetEntity` registers
 /// the display want (`update_display_models` scans every `NetEntity`) and `attach_entity_visuals`
 /// builds it as an ordinary creature; `scale` is the **CDI `creatureModelScale` column alone**
-/// (byte law, wow-re `mount-composition.md` Q3/Q4 — the unit root's `SCALE_X` composes through the
-/// hierarchy).
+/// (byte law, `0x607a75` — the unit root's `SCALE_X` composes through the hierarchy).
 ///
 /// `fade_skip` suppresses the appear-fade: a mount blinking into existence under its rider is what
 /// the teardown-era transition rendered (every rebuilt child carried `Reattached`), and it is what
@@ -100,9 +99,9 @@ pub(super) fn spawn_mount_child(
 }
 
 /// The seat anchor — the rider's model frame while mounted: a child of the mount's attachment-0
-/// joint at the authored offset, counter-scaled so the rider keeps its own size (byte-verified:
-/// the client's body carries a compensating own/mount base ratio, `0x607b49 fld [esi+0x98]; fdiv
-/// [esi+0x9c]` → `0x710620` — wow-re `mount-composition.md` Q3).
+/// joint at the authored offset, counter-scaled so the rider keeps its own size (the client's body
+/// carries a compensating own/mount base ratio, `0x607b49 fld [esi+0x98]; fdiv [esi+0x9c]` →
+/// `0x710620`).
 ///
 /// [`benilla_world::rig_anim::RigFrame`] marks it as `rider`'s model frame so the world pass cascades
 /// a re-seat into the rider's palette (decision 0724).
@@ -166,7 +165,7 @@ pub(super) fn seat_or_spawn_mount(
     mount_display: u32,
     fade_skip: bool,
 ) -> Seat {
-    // The mount scale law (byte-verified, wow-re `mount-composition.md` Q3/Q4): rendered =
+    // The mount scale law (`0x607a75`): rendered =
     // `SCALE_X × CreatureDisplayInfo.creatureModelScale` — the CDI column ALONE (no
     // CreatureModelData.modelScale).
     let mount_scale = creatures
diff --git a/crates/benilla-app/src/entities/mount/tests.rs b/crates/benilla-app/src/entities/mount/tests.rs
index 7820872b..fe6c1ffa 100644
--- a/crates/benilla-app/src/entities/mount/tests.rs
+++ b/crates/benilla-app/src/entities/mount/tests.rs
@@ -1,7 +1,7 @@
 //! The mount transition's law: **nothing on the rider is destroyed by mounting**.
 //!
-//! B199 (Frostshake, 08-03) is the report these pin: "mounting removes Ice Barrier's shield visual
-//! from the character — and dismounting does not bring it back". The old transition
+//! The case these pin: Ice Barrier's shield visual stays on the character through a mount, and is
+//! still there after the dismount. The old transition
 //! `despawn_related::<Children>()`'d the whole rider; the aura's persistent kit instance died with
 //! it and, because `FxAttached` lives on the *unit* and kept a dangling root while the aura never
 //! left its slot, nothing ever noticed. So these fixtures hang the two things that matter off a
diff --git a/crates/benilla-app/src/entities/spell_fx/lifecycle.rs b/crates/benilla-app/src/entities/spell_fx/lifecycle.rs
index c27e54b3..3f4fbbfa 100644
--- a/crates/benilla-app/src/entities/spell_fx/lifecycle.rs
+++ b/crates/benilla-app/src/entities/spell_fx/lifecycle.rs
@@ -1,8 +1,7 @@
 //! The effect-model **animation lifecycle**: `Stand` → `Hold` → `Decay`, the state machine a
-//! spell-visual `CEffect`'s attached model runs for as long as it lives (VERIFIED — wow-re
-//! `ceffect-anim-lifecycle.md`, §5 trio + corpus census 2026-08-02). Split from [`super`] along the
-//! concern seam: that file owns the *instances* (the model cache, the attach cascade, the reap, the
-//! world plants); this one owns *what they play*.
+//! spell-visual `CEffect`'s attached model runs for as long as it lives. Split from [`super`] along
+//! the concern seam: that file owns the *instances* (the model cache, the attach cascade, the reap,
+//! the world plants); this one owns *what they play*.
 //!
 //! ## The mechanism
 //!
@@ -30,8 +29,7 @@
 //! Reap ([`FxDecay`]) is the same shape from the other end (`0x614150` → `0x6141c0`): if the model
 //! authors **`Decay` (159)**, arm it and the instance **keeps rendering for that sequence's
 //! authored span** before it despawns; otherwise it goes immediately. `0x6203e0` — the destructor —
-//! plays nothing itself (its `0x4` bit is owner-attachment teardown, not a decay-out; wow-re §8
-//! corrects `ceffect-selfterm.md` on exactly this).
+//! plays nothing itself (its `0x4` bit is owner-attachment teardown, not a decay-out).
 //!
 //! ## What this replaces, and how wrong it was
 //!
@@ -185,7 +183,7 @@ pub(crate) fn advance_fx_anim(
 /// the `kit spawn` / `kit expire` lines the instance lane already writes.
 ///
 /// This is how "the Ice Barrier shield is frozen" is *closed by measurement* rather than by eye
-/// (method.md §4/§5): with the lifecycle dead the trace shows `kit spawn` and nothing after; with it
+/// (docs/METHOD.md §4/§5): with the lifecycle dead the trace shows `kit spawn` and nothing after; with it
 /// live the same cast prints `fx leg hold e=… anim=158` one birth-span (0.70 s) later, and the aura
 /// drop prints `fx leg decay` followed by the `kit expire` a further 1.10 s on. A duration question
 /// is answered from timestamps, never from watching.
@@ -213,8 +211,8 @@ fn arm_decay(player: &mut AnimationPlayer, armed: AnimationNodeIndex, anims: &Mo
 }
 
 /// The authored span of a model's `Decay` sequence — how long a reaped instance keeps rendering
-/// before it despawns (wow-re §8: the node is *not* torn down synchronously). `None` when the model
-/// authors no `Decay`, which is the reference's immediate-destroy gate.
+/// before it despawns (`0x6141f0`: the node is *not* torn down synchronously). `None` when the
+/// model authors no `Decay`, which is the reference's immediate-destroy gate.
 pub(crate) fn decay_span(anims: Option<&ModelAnimations>) -> Option<f32> {
     anims?.find(ANIM_DECAY).map(|c| c.duration)
 }
diff --git a/crates/benilla-app/src/entities/spell_fx/mod.rs b/crates/benilla-app/src/entities/spell_fx/mod.rs
index 14f02ddf..b24bc80b 100644
--- a/crates/benilla-app/src/entities/spell_fx/mod.rs
+++ b/crates/benilla-app/src/entities/spell_fx/mod.rs
@@ -9,8 +9,8 @@
 //! the render side: a path-keyed [`DisplayModel`] cache (the held-items pattern — entries created
 //! here, parts built by `super::update_display_models` once the M2 loads), and per-unit effect
 //! instances spawned under the unit's [`BoneAttach`] joints so they ride the animating bone —
-//! exactly the client's `CEffect` bone attach, re-resolved per frame off the live bone matrix
-//! (wow-re `spell-visual-apply.md` §1.5/§5; riding the joint entity gives us the same for free).
+//! exactly the client's `CEffect` bone attach (`0x620be0`), re-resolved per frame off the live
+//! bone matrix (riding the joint entity gives us the same for free).
 //!
 //! Lifetime is the client's stage policy (decision 0107 verdict 2): a **persistent** instance
 //! (precast/channel) lives until its spell-id-keyed [`SpellKitFx::Reap`] (the client's
@@ -26,10 +26,8 @@
 //!
 //! **The attach cascade below is mis-attributed and is a known divergence** (named in 2057, not
 //! yet fixed): `tag → 0xf → 0x13 → the unit's base` is `CMissile`'s (`0x61ceb0`,
-//! `Missile_C.cpp`), not `AddEffect`'s. wow-re corrected this on 2026-09-02
-//! (`spell-visual-apply.md`, from `melee-blood-spurt-suppression.md` §1/§7): `0x61fdd0` has no
-//! attachment test at all, so on a model lacking the tag the reference drops the effect
-//! permanently and invisibly where we relocate it.
+//! `Missile_C.cpp`), not `AddEffect`'s: `0x61fdd0` has no attachment test at all, so on a model
+//! lacking the tag the reference drops the effect permanently and invisibly where we relocate it.
 //!
 //! Effect models run their **bone rigs** ([`arm_effect_rig`] — the birth clip + global sequences
 //! pose the joints that meshes skin to and emitters/ribbons/cards ride), advance them through the
@@ -91,9 +89,8 @@ pub(crate) use lifecycle::{
 };
 use lifecycle::{decay_span, FxAnimLife, FxDecay};
 
-/// The client's attach fallback cascade when a model lacks the requested point (wow-re
-/// `spell-visual-apply.md` §5, `0x61ceb0`/`0x61fae0`): retry `0xf`, then `0x13`, then the unit's
-/// base position.
+/// The client's attach fallback cascade when a model lacks the requested point
+/// (`0x61ceb0`/`0x61fae0`): retry `0xf`, then `0x13`, then the unit's base position.
 const ATTACH_FALLBACKS: [u16; 2] = [0xf, 0x13];
 
 /// The self-termination span when an effect model has no sequence table at all (the cube
@@ -530,10 +527,11 @@ pub(crate) fn attach_effect_visuals(
             },
             // The emitters' rate/enabled windows ride the played sequence: a `CEffect` ADVANCES
             // (`Stand` → `Hold` → `Decay`), so it reads the live one off its own player like a
-            // unit's do — the reference's `m2_animate` phase samples the CURRENT sequence record
-            // either way. A lane that never advances (a missile, whose InFlight is not the model's
-            // Stand) keeps its slot pinned on the spawn clock. gseq loops ride the instance's own
-            // spawn age in both (0856/0858 — an effect instance is fresh per play).
+            // unit's do — the phase in the reference's animate kernel `0x714260` samples the
+            // CURRENT sequence record either way. A lane that never advances (a missile, whose
+            // InFlight is not the model's Stand) keeps its slot pinned on the spawn clock. gseq
+            // loops ride the instance's own spawn age in both (0856/0858 — an effect instance is
+            // fresh per play).
             match seq_host {
                 Some(h) => particles::EmitClock::Host(h),
                 None => particles::EmitClock::Effect(played_seq),
@@ -669,8 +667,8 @@ struct FxInstance {
     /// The self-termination deadline (`time.elapsed_secs()` clock), set at spawn for a
     /// non-persistent instance — and, for a reaped persistent one, the end of its `Decay` span.
     expires: Option<f32>,
-    /// Reaped, and playing its `Decay` out (wow-re `ceffect-anim-lifecycle.md` §8: the node is not
-    /// torn down synchronously — it keeps rendering for that sequence's authored duration). Such an
+    /// Reaped, and playing its `Decay` out (`0x614150`/`0x6141f0`: the node is not torn down
+    /// synchronously — it keeps rendering for that sequence's authored duration). Such an
     /// instance is already dying, so it no longer answers a reap or a replacing `Begin`: the
     /// reference's walk can't reach it either, having moved it to the pending-destroy list.
     decaying: bool,
@@ -684,10 +682,10 @@ pub(super) struct FxAttached {
 
 /// A **world-planted** kit instance root (the field-12 slot, decisions 0848/0850): a free world
 /// entity, NOT a scene child of its owner — so [`tend_world_plants`] owns the two jobs the tree
-/// would otherwise do. Byte law (wow-re `kit30-effect-slot.md`): planted once at the owner's
-/// position × yaw × scale; a **root-aura** spell's plant (`EffectApplyAuraName` 26 anywhere in
-/// the spell — the client's flag 0x4000) re-plants when the owner is displaced (knockback,
-/// blink), re-baking facing and scale.
+/// would otherwise do. The reference plants it once at the owner's position × yaw × scale
+/// (`0x620a90`); a **root-aura** spell's plant (`EffectApplyAuraName` 26 anywhere in the spell —
+/// the client's flag 0x4000) re-plants when the owner is displaced (knockback, blink;
+/// `0x620580`), re-baking facing and scale.
 #[derive(Component)]
 pub(super) struct WorldPlantFx {
     /// The unit the instance belongs to — despawn tracking (the client's node dies with its
@@ -715,8 +713,8 @@ fn world_plant_transform(owner: &GlobalTransform) -> Transform {
 }
 
 /// Whether any of the spell's three `EffectApplyAuraName` slots is `SPELL_AURA_MOD_ROOT` (26) —
-/// the client's `spellRec+0x16c[0..2] == 0x1a` scan that arms the re-plant flag 0x4000 (wow-re
-/// `kit30-effect-slot.md`; the column *name* is INFERRED there, the byte behaviour VERIFIED).
+/// the client's `spellRec+0x16c[0..2] == 0x1a` scan that arms the re-plant flag 0x4000
+/// (`0x60f081`; only the column *name* is inferred).
 /// Exactly the field-12 state family: Frost Nova, Net, Web, Entangling Roots, Frostbite.
 fn spell_has_root_aura(spells: Option<&crate::ui_action::Spells>, spell_id: u32) -> bool {
     const SPELL_AURA_MOD_ROOT: u32 = 26;
@@ -855,8 +853,7 @@ pub(super) fn resolve_spell_fx(
 }
 
 /// **Hand an ending instance's emitters to the drain** — the half of the reference's teardown
-/// `0x6203e0` that is not a despawn (wow-re `ceffect-particle-drain.md`, §4a byte-settled
-/// 2026-09-07).
+/// `0x6203e0` that is not a despawn.
 ///
 /// An ending `CEffect` is *hidden*, not freed: emission stops, the already-emitted particles keep
 /// drawing and age out one at a time, and the node is released only on the frame the last one dies
@@ -883,11 +880,10 @@ fn drain_instance_emitters(
     }
 }
 
-/// **The same-slot replace walk** (`0x6208e0`, VERIFIED `[0x6208e0, 0x62092c]` — wow-re
-/// `kit30-effect-slot.md` §4; decision 2057): every `CEffect::AddEffect` (`0x61fdd0`) opens by
-/// walking the owner's `+0xb4` list and **destroying** (`0x6203e0`) each node carrying the same
-/// `SpellVisualEffectName` record at the same attach tag, so a re-play *replaces* a still-live
-/// same-model-same-slot emitter instead of stacking on it.
+/// **The same-slot replace walk** (`0x6208e0`, `[0x6208e0, 0x62092c]`; decision 2057): every
+/// `CEffect::AddEffect` (`0x61fdd0`) opens by walking the owner's `+0xb4` list and **destroying**
+/// (`0x6203e0`) each node carrying the same `SpellVisualEffectName` record at the same attach tag,
+/// so a re-play *replaces* a still-live same-model-same-slot emitter instead of stacking on it.
 ///
 /// This is the whole reason a busy fight does not brighten without bound in the reference: five
 /// mobs' blood spurts on one flank of one body are one instance there, not five, and the count is
@@ -915,8 +911,8 @@ fn replace_same_slot(
         }
         if let Some(root) = i.root {
             // The replaced node's particles finish — the replace bounds the number of EMITTING
-            // nodes, not the number of live particles (`ceffect-particle-drain.md` §1's note on
-            // the shared teardown).
+            // nodes, not the number of live particles (it ends the node through the shared
+            // teardown `0x6203e0`).
             drain_instance_emitters(emitters, root);
             commands.entity(root).despawn();
         }
@@ -982,6 +978,8 @@ pub(super) fn attach_spell_fx(
         // pose (`RigPose::anchor_for`, decision 1355).
         Option<&mut benilla_world::rig_anim::RigPose>,
         &GlobalTransform,
+        // The body is built (model or fallback cube) — see the wait below.
+        Has<crate::entities::VisualAttached>,
     )>,
     fx: Option<ResMut<SpellFx>>,
     asset_server: Res<AssetServer>,
@@ -999,7 +997,7 @@ pub(super) fn attach_spell_fx(
         return;
     };
     let now = time.elapsed_secs();
-    for (unit, mut att, bones, mut pose, unit_gt) in &mut units {
+    for (unit, mut att, bones, mut pose, unit_gt, body_built) in &mut units {
         att.instances.retain_mut(|inst| {
             // Self-termination (the cast-release flash ran its span).
             if let Some(expires) = inst.expires {
@@ -1027,8 +1025,7 @@ pub(super) fn attach_spell_fx(
             // dangling entity, and this gate's `root.is_some()` then means it is never rebuilt.
             // The reference's rebuild `0x60abe0` DRAINS the whole `+0xb4` list unconditionally
             // and then RE-CREATES what must persist — the aura-state re-arm `0x5ff130`, the
-            // channel re-arm `0x612a30` (wow-re `shapeshift-morph-cloud.md`, which REFUTED the
-            // earlier survives-the-rebuild reading). Our edge-driven aura watcher cannot notice
+            // channel re-arm `0x612a30`. Our edge-driven aura watcher cannot notice
             // (the aura never left the slots), so re-arming the PERSISTENT instance here IS that
             // re-create leg, in the one place that sees the drain. A one-shot goes, exactly as
             // the reference's drained Mount Poof does — the shapeshift cloud is NOT survival:
@@ -1080,6 +1077,18 @@ pub(super) fn attach_spell_fx(
             // A root-aura spell's plant additionally re-plants on owner displacement
             // ([`tend_world_plants`] — the client's 0x4000 flag leg).
             let planted = inst.tag == benilla_formats::WORLD_EFFECT_TAG;
+            // **A bone-riding effect waits for the body.** The cascade below reads the unit's
+            // attach points, and before the body is built (a display swap still loading the new
+            // model, a player still settling its equipment) there are none — so it fell through
+            // to the unit root, ground-anchored, and a persistent instance is never re-seated
+            // after that: an Ice Barrier or a Power Word: Shield sat decaled at the feet for the
+            // aura's whole life. The reference re-arms the persistent kits after the rebuild has
+            // set the new model (`0x60abe0` → `0x5ff130`);
+            // `VisualAttached` is that "the model is set" — the cube fallback carries it too, so
+            // a unit whose model never loads still gets its effect at the root.
+            if !planted && !body_built {
+                return true;
+            }
             // Ground-anchored: a world plant sits at the feet by construction; otherwise the
             // cascade landed on the model's BASE point (`0x13`) or fell through to the unit
             // root — the feet-level anchors. A hand/head/chest-anchored instance keeps its flat
@@ -1320,8 +1329,8 @@ mod tests {
             .collect()
     }
 
-    /// **The drain-then-recreate law** (0835's named-open item closed; the reference byte-read
-    /// in wow-re `shapeshift-morph-cloud.md`): the rebuild drains EVERY effect node and then
+    /// **The drain-then-recreate law** (0835's named-open item closed; the reference's rebuild
+    /// `0x60abe0`): the rebuild drains EVERY effect node and then
     /// re-creates what must persist. A teardown of the unit's visual leaves each instance
     /// holding a dangling root; the persistent instance re-arms (our re-create leg — the
     /// edge-driven aura watcher cannot notice, the aura never left the slots), the one-shot
@@ -1343,6 +1352,38 @@ mod tests {
         );
     }
 
+    /// **The re-create waits for the new body.** A display swap tears the visual down and the
+    /// new model may still be loading when the effect model is already cached: re-arming then
+    /// found no attach points and parked a chest shield at the feet, ground-decaled, for the
+    /// aura's whole life (nothing re-seats a live root). It waits until the body is built.
+    #[test]
+    fn a_re_armed_instance_waits_for_the_body_before_it_spawns() {
+        let (mut app, unit, roots) = standing(&[true]);
+        app.world_mut().entity_mut(roots[0]).despawn();
+        app.world_mut().resource_mut::<SpellFx>().models.insert(
+            "Spells\\IceShield_State.mdx".into(),
+            DisplayModel {
+                parts: Some(Vec::new()),
+                ..crate::entities::display::empty_shell()
+            },
+        );
+        app.update();
+        app.update();
+        assert_eq!(
+            instances_of(&app, unit),
+            vec![(true, None)],
+            "no body yet: the instance holds, it does not spawn at the root"
+        );
+        app.world_mut()
+            .entity_mut(unit)
+            .insert(crate::entities::VisualAttached);
+        app.update();
+        assert!(
+            matches!(instances_of(&app, unit)[..], [(true, Some(_))]),
+            "the body is built: the instance spawns"
+        );
+    }
+
     /// A decaying persistent instance was already ending — the drain takes it too (a re-spawn
     /// would replay its death rattle from nothing on the new body).
     #[test]
diff --git a/crates/benilla-app/src/fishing_line.rs b/crates/benilla-app/src/fishing_line.rs
index 06665cb2..984c0789 100644
--- a/crates/benilla-app/src/fishing_line.rs
+++ b/crates/benilla-app/src/fishing_line.rs
@@ -1,5 +1,4 @@
-//! The engine-drawn **fishing line** (wow-re `object-layer/scratch/fishing-line.md`, §5
-//! byte-verified, their `aed458c7`): rod tip → bobber while a unit channels Fishing.
+//! The engine-drawn **fishing line**: rod tip → 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`
@@ -9,7 +8,7 @@
 //! 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 geometry (`0x61f780`, bit-proven `PRIMITIVE:effect_beam_trail`): **65 vertices**, straight
+//! 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
diff --git a/crates/benilla-app/src/footprints.rs b/crates/benilla-app/src/footprints.rs
index c57ca982..92b3f120 100644
--- a/crates/benilla-app/src/footprints.rs
+++ b/crates/benilla-app/src/footprints.rs
@@ -5,11 +5,11 @@
 //! 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).
 //!
-//! **The mechanism — wow-re §5 cross-checked** (`footprint-decals.md`, folded back in 1012):
+//! **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 (wow-re `wmo-footstep-surface.md` F3), so
+//!   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`]
@@ -24,8 +24,7 @@
 //!   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`], byte-diffed
-//!   `PRIMITIVE:footprint_alpha` @`0x69a3e0`).
+//!   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 —
@@ -39,9 +38,9 @@
 //!   are always-on until a settings page wires the knob (the cvar-policy line, like the blob
 //!   shadow's `shadowLOD`).
 //!
-//! Draw state per the RE: 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 there (none
-//! load-bearing, note §13): the forward-axis sign convention inside the shared UV basis, the
+//! 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).
@@ -63,8 +62,8 @@ 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 (byte-verified, wow-re
-/// `footprint-decals.md`: `t = 1 − age/6000`, die at `t < 0`).
+/// Print lifetime, spawn to gone — the reference's 6000 ms (`0x69a3e0`: `t = 1 − age/6000`, die
+/// at `t < 0`).
 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.
@@ -166,7 +165,7 @@ fn spawn_footprints(
     // are the MOUNT child's tags, whose local Transform is the seat-relative ~origin.
     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 — RE-corrected), and the state gates all read the root.
+    // rider's SCALE_X, `0x469f10`), and the state gates all read the root.
     parents: Query<&ChildOf>,
     roots: Query<RootState>,
     camera: Query<&GlobalTransform, With<WorldCamera>>,
@@ -200,7 +199,8 @@ fn spawn_footprints(
             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 RE's split.
+        // scale and every state gate from the ROOT unit (the rider) — the reference's split
+        // (`0x607920`).
         let Some(params) = net.display_id.and_then(|d| creatures.footprint(d)) else {
             continue;
         };
@@ -236,7 +236,7 @@ fn spawn_footprints(
         }
         // 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 (wow-re `wmo-footstep-surface.md` F3). So this reads the UNIT's surface,
+        // 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.
         let terrain = world.terrain_type(
@@ -249,15 +249,15 @@ fn spawn_footprints(
         }
         // 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 the RE's open §13 item — a
-        // backwards-pointing print flips one sign here).
+        // is the toe end (the absolute sign convention is still open — a backwards-pointing
+        // 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 (RE: the
-        // print scale is SCALE_X alone — display scales never multiply in).
+        // 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 {
@@ -320,7 +320,7 @@ fn spawn_footprints(
     }
 }
 
-/// The reference's fade at age seconds (byte-diffed `PRIMITIVE:footprint_alpha` @`0x69a3e0`):
+/// 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`].
 fn fade(age: f32) -> f32 {
diff --git a/crates/benilla-app/src/game_plugins.rs b/crates/benilla-app/src/game_plugins.rs
index 5491eeac..adda66ec 100644
--- a/crates/benilla-app/src/game_plugins.rs
+++ b/crates/benilla-app/src/game_plugins.rs
@@ -131,6 +131,9 @@ impl PluginGroup for GamePlugins {
             // 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.
+            .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 (the byte-verified law — wow-re unit-blob-shadow RE), on the same
@@ -282,11 +285,6 @@ impl PluginGroup for GamePlugins {
             // `_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)
-            // The talent spell-modifier tables (`SMSG_SET_FLAT_/PCT_SPELL_MODIFIER`): the wire
-            // fills them, world-enter clears them, and `usable::power_cost` reads op 14 out of
-            // them. Beside the swing refusal because both are the same shape — a small wire-fed
-            // store with a world-entry reset — and neither has a feed of its own.
-            .add(crate::spell_mods::SpellModsPlugin)
             // 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.
@@ -336,6 +334,11 @@ impl PluginGroup for GamePlugins {
             // 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.
+            .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).
@@ -361,10 +364,11 @@ impl PluginGroup for GamePlugins {
             // 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 (wow-re shapeshift-bar-api.md): builds the form list from
-            // PlayerActions.spells per the byte-verified admission/order, drives the stock shapeshift bar through
-            // the engine's shapeshift seam, and drains its clicks (cancel-if-active else cast). After
-            // UiActionPlugin (shares `Spells`, the `usable` walk, and the cast tail).
+            // 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).
             .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
@@ -558,14 +562,37 @@ 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.
+    #[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.
+        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.
+        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.
-    pub(crate) fn census(app: &mut App, label: impl ScheduleLabel) -> Census {
+    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| {
             schedule.set_build_settings(ScheduleBuildSettings {
                 ambiguity_detection: LogLevel::Warn,
+                auto_insert_apply_deferred: sync == SyncPoints::Built,
                 ..default()
             });
             // The systems' access is filled by `initialize`, which the build below would run
@@ -745,13 +772,13 @@ pub(crate) mod schedule_tests {
     ///   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.)
-    /// - **An exclusive edge** — a pair bevy reports with NO component list: one side is a
-    ///   build-inserted `ApplyDeferred` sync point or an exclusive system, which conflicts on
-    ///   `World` itself. Its order against a system it shares nothing with is immaterial by
-    ///   construction (the build already placed the barrier after the commands it flushes and
-    ///   before their dependents), and there is nothing to declare it against. Until 2304 an
-    ///   empty list read as "VM only" vacuously, so that class rose and fell with the barrier
-    ///   count; now it is named.
+    /// - **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
@@ -846,8 +873,10 @@ pub(crate) mod schedule_tests {
 
         /// 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).
             if what.is_empty() {
-                return Some("exclusive");
+                return None;
             }
             if !what.iter().all(|id| self.explains(*id)) {
                 return None;
@@ -884,7 +913,8 @@ pub(crate) mod schedule_tests {
 
     /// `PostUpdate`, 181 systems: `GlobalTransform` and the particle `EffectQuads` are most of it.
     ///
-    /// **375 (MONKEY, the dynamic light and shadow system)** — upstream's own number is 351; this
+    /// **395 (MONKEY, the dynamic light and shadow system)** — upstream's own number is 371 (decision
+    /// 2337, the re-measured declared-graph count); this
     /// branch adds **+24**, and the pairs were READ off the dump rather than reasoned about (the
     /// lesson the `UPDATE_ACTIONABLE_CEILING` paragraphs paid for). `WOW_AMBIGUITY_DUMP_POST=1`
     /// on this test prints them; three systems carry every one:
@@ -914,7 +944,17 @@ pub(crate) mod schedule_tests {
     /// animation, particle and celestial-follow systems to buy a one-frame-fresher transform that
     /// nothing can see — a real serialisation cost for no observable difference. Raised, with the
     /// reason, as the failure message offers.
-    const POST_UPDATE_CEILING: usize = 375;
+    ///
+    /// **466, re-measured after the upstream census change (decision 2337) with the water module
+    /// and volumetric fog in.** By family (`WOW_AMBIGUITY_DUMP_POST=1`): the swim bob
+    /// (`water_fx::bob::{apply,clear}_swim_bob`, 21 pairs) against the rig composer, billboards,
+    /// particles and the sky followers; `classify_light_lanes` (14) and `track_carried_light_motion`
+    /// (14) as above; the shadow rig (`shadow_core`, 12); `lava_light::{reconcile,lane_census}` (6);
+    /// the rest are upstream families that now meet our water_fx/liquid additions. All are over
+    /// `GlobalTransform`/`Transform`/`Mesh3d` and level-triggered. KNOWN FOLLOW-UP: the swim bob
+    /// WRITES a rig's visual offset without an order against `rig_anim::compose`, so the bob can
+    /// land a frame late on a swimmer - worth an explicit `.after(...)` when it is next touched.
+    const POST_UPDATE_CEILING: usize = 466;
     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
@@ -998,10 +1038,48 @@ pub(crate) mod schedule_tests {
     /// 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`].
-    const UPDATE_ACTIONABLE_CEILING: usize = 2_975;
+    /// **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.
+    const UPDATE_ACTIONABLE_CEILING: usize = 5_554;
     const UPDATE_ACTIONABLE_SLACK: usize = 40;
 
     fn ratchet(what: &str, n: usize, ceiling: usize, slack: usize) {
@@ -1026,8 +1104,10 @@ pub(crate) mod schedule_tests {
     #[test]
     fn the_schedules_have_no_more_undeclared_orders_than_the_ceilings_say() {
         let mut app = headless_client();
-        let update = census(&mut app, Update);
-        let post = census(&mut app, PostUpdate);
+        // 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`]).
+        let update = census(&mut app, Update, SyncPoints::Declared);
+        let post = census(&mut app, PostUpdate, SyncPoints::Declared);
         let mut explained: BTreeMap<&str, usize> = BTreeMap::new();
         let mut actionable = Vec::new();
         for (a, b, what) in &update.conflicts {
@@ -1056,10 +1136,17 @@ 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.
+                    let (x, y) = if update.name(*a) <= update.name(*b) {
+                        (*a, *b)
+                    } else {
+                        (*b, *a)
+                    };
                     format!(
                         "  {}  <->  {}\n      on {}",
-                        update.name(*a),
-                        update.name(*b),
+                        update.name(x),
+                        update.name(y),
                         what.iter()
                             .map(|id| update.component(*id))
                             .collect::<Vec<_>>()
@@ -1076,7 +1163,7 @@ pub(crate) mod schedule_tests {
         // lever had no equivalent of — and without which `POST_UPDATE_CEILING` could only ever be
         // raised by reasoning about what the new pairs must be, the exact mistake the ceiling's
         // own comments record. Its own env var, not `WOW_AMBIGUITY_DUMP`, because `PostUpdate`
-        // prints every pair (there is no `Classes` pass over it) and 375 rows would bury the
+        // prints every pair (there is no `Classes` pass over it) and 466 rows would bury the
         // actionable `Update` list this test is usually run for.
         if std::env::var_os("WOW_AMBIGUITY_DUMP_POST").is_some() {
             let mut rows: Vec<String> = post
@@ -1218,10 +1305,15 @@ pub(crate) mod schedule_tests {
     /// 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.
     #[test]
+    #[ignore = "instrument: run by hand (2265 §A3's executor census) — cargo test -p benilla-app --lib concurrency_census -- --ignored --nocapture"]
     fn concurrency_census() {
         let mut app = headless_client();
-        let c = census(&mut app, Update);
+        let c = census(&mut app, Update, SyncPoints::Built);
         let holds = |k: SystemKey, pick: &dyn Fn(ComponentId) -> bool| {
             c.conflicts
                 .iter()
@@ -1312,7 +1404,7 @@ pub(crate) mod schedule_tests {
     #[test]
     fn every_vm_holder_in_update_declares_its_side_of_the_tick() {
         let mut app = headless_client();
-        let c = census(&mut app, Update);
+        let c = census(&mut app, Update, SyncPoints::Built);
         if !type_names_available(&c) {
             eprintln!(
                 "skipped: this build carries no type names (bevy/debug rides with dev, 1451)"
@@ -1456,7 +1548,7 @@ pub(crate) mod schedule_tests {
          "`seen_generation` is a `VmMemo`: a new VM reads `None`, rebuilds and re-fires UPDATE_BINDINGS"),
         ("capture/probe_bg.rs", "bg_probe", Because::SelfHealing,
          "the battleground probe: dev-only (`WOW_PROBE_BG`, `cfg(feature = \"dev\")`) so it is not in a player build at all, and its `mem::take` is of its OWN pending-events string, not a queue anything else fills. Its one real VM dependency is the Lua event tap, which self-heals: `EVENT_DRAIN` returns a `<tap-gone>` sentinel when the tap's globals are missing — the case this window causes, since a tap installed in the boot VM is discarded when `mint_entry_vm` builds the interface — and the probe re-installs on the next frame"),
-        ("death.rs", "feed_death", Because::MemoLatched,
+        ("death/mod.rs", "feed_death", Because::MemoLatched,
          "`feed.vm: VmMemo<DeathAnnounced>`: a fresh memo makes the first snapshot an edge and re-announces a held offer, confirm and corpse range"),
         ("screenshot.rs", "ask_for_captures", Because::FilledByVm,
          "`pending` holds only the VM's own `Screenshot()` asks, and the take spawns a capture, publishing nothing"),
@@ -1468,7 +1560,7 @@ pub(crate) mod schedule_tests {
          "filled only by a world right-click on a GameObject; the drain sends casts to the wire (2232's own bucket)"),
         ("ui_auction/mod.rs", "drain_auction", Because::FilledByVm,
          "VM verbs; the refresh flags act only under an open window and become wire re-asks"),
-        ("ui_bank.rs", "feed_bank", Because::PlayerRoundTrip,
+        ("ui_bank/mod.rs", "feed_bank", Because::PlayerRoundTrip,
          "`BankErrors` answers a `BuyBankSlot` click; the OPENED edge rides `VmMemo`s"),
         ("ui_battlefield.rs", "feed_battlefield", Because::SelfHealing,
          "`reset_on_world_enter` runs before it, clears the session and re-sends `BattlefieldStatusRequest`"),
@@ -1500,7 +1592,7 @@ pub(crate) mod schedule_tests {
          "`take_container_uses` and `take_container_repairs` are Lua intents held by the VM"),
         ("ui_logout.rs", "feed_logout", Because::PlayerRoundTrip,
          "both packets answer the `CMSG_LOGOUT_REQUEST`/cancel the game menu sent"),
-        ("ui_loot.rs", "drain_loot", Because::Deliberate,
+        ("ui_loot/mod.rs", "drain_loot", Because::Deliberate,
          "the pre-VM take of `LootMoveStart` is documented at the line and publishes nothing to the VM; the event-firing takes are Lua's queues"),
         ("ui_loot_roll.rs", "drain_loot_rolls", Because::FilledByVm,
          "only a Need/Greed/Pass click queues a confirm or vote, held in the VM"),
@@ -1512,7 +1604,7 @@ pub(crate) mod schedule_tests {
          "`take_macros_dirty` is raised only by the macro window's Lua"),
         ("ui_mail/mod.rs", "feed_mail", Because::SelfHealing,
          "the window queues are mailbox-click replies; the one server push (`SMSG_RECEIVED_MAIL`) is re-asked by `send_query_next_mail_time_on_enter`, whose reply sets `notify` unconditionally"),
-        ("ui_merchant.rs", "feed_merchant", Because::PlayerRoundTrip,
+        ("ui_merchant/mod.rs", "feed_merchant", Because::PlayerRoundTrip,
          "a buy/sell refusal answers a click on an open merchant; show/update ride `VmMemo`s"),
         ("ui_petition/feed.rs", "feed_petition", Because::PlayerRoundTrip,
          "every line answers a charter action of ours; the window edges ride the `fed` memo"),
@@ -1522,7 +1614,7 @@ pub(crate) mod schedule_tests {
          "per-frame paint and cost state, not a queue (2232)"),
         ("ui_social/feed.rs", "feed_social", Because::MemoLatched,
          "the login-burst lists are re-announced to a new VM by `fed.seeded` (`VmMemo<FedSocial>`); the show flag is Lua's; a status line waits on the name resolve"),
-        ("ui_stable.rs", "feed_stable", Because::PlayerRoundTrip,
+        ("ui_stable/mod.rs", "feed_stable", Because::PlayerRoundTrip,
          "both packets follow a stable master's gossip and a click in its window"),
         ("ui_summon.rs", "feed_summon", Because::PlayerRoundTrip,
          "only another player's Ritual of Summoning latches the ask (2232's duel shape; coincidence-only residual)"),
@@ -1582,14 +1674,14 @@ pub(crate) mod schedule_tests {
             }
         }
         let mut app = headless_client();
-        let update = census(&mut app, Update);
+        let update = census(&mut app, Update, SyncPoints::Built);
         if !type_names_available(&update) {
             eprintln!(
                 "skipped: this build carries no type names (bevy/debug rides with dev, 1451)"
             );
             return;
         }
-        let post = census(&mut app, PostUpdate);
+        let post = census(&mut app, PostUpdate, SyncPoints::Built);
         let by_name: HashMap<&str, &SystemInfo> = update
             .systems
             .values()
diff --git a/crates/benilla-app/src/game_tip.rs b/crates/benilla-app/src/game_tip.rs
index 358ce6da..3172491f 100644
--- a/crates/benilla-app/src/game_tip.rs
+++ b/crates/benilla-app/src/game_tip.rs
@@ -1,5 +1,4 @@
-//! The loading screen's **tip of the day** (decision 2077; wow-re
-//! `system/loadingscreen/scratch/game-tip-of-the-day.md`).
+//! The loading screen's **tip of the day** (decision 2077).
 //!
 //! `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
diff --git a/crates/benilla-app/src/glue/backdrop.rs b/crates/benilla-app/src/glue/backdrop.rs
index d69c2b91..659a88f4 100644
--- a/crates/benilla-app/src/glue/backdrop.rs
+++ b/crates/benilla-app/src/glue/backdrop.rs
@@ -1,5 +1,5 @@
-//! WoW `Backdrop`s, at the geometry the client itself uses (wow-re `backdrop-mechanism.md`,
-//! byte-verified; decision 0543): the `edgeFile` strip split into its eight upright pieces
+//! 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
@@ -29,8 +29,8 @@ pub(crate) struct BackdropEdges {
 
 /// 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
-/// (wow-re `backdrop-mechanism.md` §3, byte-verified from the client's UV constants; independently
-/// confirmed here by reading the shapes out of `Glue-Tooltip-Border`'s pixels).
+/// (read from the client's UV constants in `0x77e8d0`/`0x77f0c0`; independently confirmed here
+/// by reading the shapes out of `Glue-Tooltip-Border`'s pixels).
 ///
 /// 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
@@ -90,10 +90,10 @@ pub(super) fn backdrop_edges(
     })
 }
 
-/// A `Backdrop`'s border, at the geometry the client itself uses (wow-re `backdrop-mechanism.md`
-/// §2, byte-verified): 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
+/// 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.
@@ -259,7 +259,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 (wow-re `backdrop-mechanism.md` §3): an e=2 strip with
+    // 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.
     #[test]
     fn backdrop_split_follows_the_edgefile_law() {
diff --git a/crates/benilla-app/src/glue/mod.rs b/crates/benilla-app/src/glue/mod.rs
index 1c221f99..1f05c1d2 100644
--- a/crates/benilla-app/src/glue/mod.rs
+++ b/crates/benilla-app/src/glue/mod.rs
@@ -88,11 +88,11 @@ impl GlueClicks {
 /// 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.
 ///
-/// VERIFIED against the real 1.12.1 client (wow-re `ui.md`, the `OnDoubleClick`/`RegisterForClicks`
-/// byte law): `CSimpleButton`'s ctor default click mask `[+0x330] = 0x100` 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`
+/// 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
@@ -161,8 +161,8 @@ pub(crate) const ROTATION_PER_UI_UNIT: f32 = 0.6 * std::f32::consts::PI / 180.0;
 /// `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
-/// (wow-re `glue/scratch/glue-preview-facing-law.md`, 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.
+/// (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.
@@ -173,7 +173,7 @@ pub(crate) fn drag_yaw(delta_px: f32, window: Option<&Window>) -> f32 {
 
 /// 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 (`method.md` step 3: the
+/// 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).
 pub(crate) const ROTATE_RATE: f32 = 120.0 * std::f32::consts::PI / 180.0;
 
@@ -203,11 +203,11 @@ pub(crate) fn screen_scale(window: Option<&Window>) -> f32 {
 /// 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 (Henhouse's 3440×1440 report). 1619 wrote that residue down and left it; this is the
+/// 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 the reporter's own 1.12 shots are: a 16:9 client, centred by the monitor, everything
-/// inside it.
+/// 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
diff --git a/crates/benilla-app/src/glue/widgets.rs b/crates/benilla-app/src/glue/widgets.rs
index 0a05c9b0..444bb9b3 100644
--- a/crates/benilla-app/src/glue/widgets.rs
+++ b/crates/benilla-app/src/glue/widgets.rs
@@ -67,8 +67,8 @@ pub(crate) struct ArtSwap {
 /// DEVICE pixel by [`super::seat_outline_copies`].
 ///
 /// 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** (wow-re
-/// `font/scratch/outline-bake-tint.md` §3, byte-verified) — and the glyph rasterizes at final
+/// 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
@@ -186,7 +186,7 @@ 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 byte-verified grammar ([`benilla_ui::markup`], RF-0087) instead of drawn literally.
+/// the reference's grammar ([`benilla_ui::markup`]) instead of drawn literally.
 ///
 /// **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
@@ -353,6 +353,13 @@ fn outlined_spans<W: Bundle, T: Bundle>(
 /// 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.
+///
+/// **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.
 pub(crate) fn icon_button<A: Component, I: Bundle, L: Bundle>(
     parent: &mut ChildSpawnerCommands,
     font: &Handle<Font>,
@@ -368,6 +375,7 @@ pub(crate) fn icon_button<A: Component, I: Bundle, L: Bundle>(
     let mut b = parent.spawn((
         action,
         Button,
+        LockHighlight::default(),
         Node {
             width: px(48.0),
             height: px(48.0),
@@ -546,11 +554,11 @@ 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 (wow-re `system/ui/scratch/rf85-editbox-caret.md`).
+/// it from here.
 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 (wow-re
-/// `rf85-editbox-caret.md`, §5-verified; the cursor flush `0x77da80` fires `OnCursorChanged` with
+/// 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.
 ///
@@ -579,8 +587,8 @@ const CARET_W: f32 = 4.0;
 ///
 /// 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 (wow-re
-/// `rf85-editbox-caret.md` §1, §8, both §5-VERIFIED). A quad anchored *over* the line cannot
+/// `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.
 pub(crate) fn caret_bar<C: Bundle>(
@@ -662,8 +670,7 @@ pub(crate) fn paint_glue_field<'a>(
     // (`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 (wow-re `editbox-selection-focus-law.md` §1-§3,
-    // §5-VERIFIED, asked because this asymmetry looked wrong). An unfocused box that still holds a
+    // `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).
     let display = field.display();
diff --git a/crates/benilla-app/src/go_anim.rs b/crates/benilla-app/src/go_anim.rs
index d1e92739..2f72db46 100644
--- a/crates/benilla-app/src/go_anim.rs
+++ b/crates/benilla-app/src/go_anim.rs
@@ -1,11 +1,11 @@
 //! GameObject open/close animation (decision 0242; chest lid folded in by 2271) — a **client-side**
 //! `GAMEOBJECT_STATE` drives a skeletal M2 sequence, so a **door** swings, a **button** depresses, and a
-//! **chest lid** opens/closes on its §243 state machine.
+//! **chest lid** opens/closes on its state machine.
 //!
-//! **The model (2271, §5-VERIFIED):** the real client keeps *one* stored state per GameObject (the
-//! binary's `go+0x27c`) and *one* `SetGoState` that all callers funnel through; a change of that state
-//! plays the §243 transition. benilla mirrors that exactly — [`GoAnim::state`] is the single source of
-//! truth, written by the **three callers** the RE census pinned:
+//! **The model (2271):** the real client keeps *one* stored state per GameObject (the binary's
+//! `go+0x27c`) and *one* `SetGoState` (`0x5f8bd0`) that all callers funnel through; a change of
+//! that state plays the transition. benilla mirrors that exactly — [`GoAnim::state`] is the single
+//! source of truth, written by the **three callers** of that setter:
 //!
 //! 1. **the wire** ([`sync_wire_go_state`]) — a `GAMEOBJECT_STATE` UpdateField change. This is the
 //!    door/button driver (the server flips their state over the wire) and the first-sight rest-pose seed.
@@ -17,15 +17,15 @@
 //!    state to READY, closing the lid, with no server round-trip (the client's loot-frame close handler).
 //!
 //! This supersedes 0244's "chests aren't animated": 0244 was right that the *wire* state never changes on
-//! loot, but wrong to conclude the chest is off the machine — it runs §243 identically, just fed from
+//! loot, but wrong to conclude the chest is off the machine — it runs identically, just fed from
 //! loot events instead of the wire. Wiring a chest to the *wire* watch alone gave it a state that never
 //! changed — the "instant open" glitch; feeding it from the loot events is the fix.
 //!
-//! The mechanism (wow-re `object-layer.md` §243 + `scratch/go-anim-state-machine.md`, §5-VERIFIED): the
+//! The mechanism (`0x5f3c30`, `0x5f3cb0`): the
 //! `GAMEOBJECT_STATE` value maps — **with no inversion**, the same polarity the sound path uses — to a
 //! held rest pose, and a *change* of state plays a one-shot transition motion that settles onto the new
 //! rest pose. The client keys the played sequence by its **AnimationData.dbc id** (the door-machine's
-//! internal index and the debug state-name strings at `0x860850` are both stale/off-by-one — the RE's
+//! internal index and the debug state-name strings at `0x860850` are both stale/off-by-one — the
 //! central trap; we key by id):
 //!
 //! | wire state | rest pose (held)      | entered by motion (one-shot) |
@@ -40,8 +40,8 @@
 //! Clips are keyed by AnimationData.dbc id, so a resolved id becomes a clip by a scan of
 //! [`ModelAnimations::clips`], exactly as `creature_anim` does.
 //!
-//! **A transition motion is a TRANSIENT substate, and the settle is explicit** (decision 1151,
-//! wow-re `gameobject-anim-arm.md` §2d/§3). The kernel's `flags` bit 0 says nothing about how long
+//! **A transition motion is a TRANSIENT substate, and the settle is explicit** (decision 1151).
+//! The kernel's `flags` bit 0 (`0x714585`) says nothing about how long
 //! a transition lasts: bit 0 clear means the *pose* wraps its band for ever, and the whole
 //! door family (`G_Crate01`, every `World\Goober\` prop, the books) authors Close/Open/Destroy
 //! that way. What ends a swing is the **object layer**: the model's completion callback fires once
@@ -54,14 +54,15 @@
 //! instead is a chest lid that springs open and slams shut ~1.5×/s for ever, which is the report
 //! this record closes.
 //!
-//! The §243 **missing-sequence fallback** is no longer deferred: [`remap_missing`] implements the
-//! four-way remap, including the two legs that freeze a *motion* clip at frame 0 to stand in for an
-//! absent rest pose. It is not a corner case — the Ahn'Qiraj gate's roots (`AHN_QIRAJ_DOORROOTS`,
-//! Stand + Open only) took the "play nothing" path and rendered its 42-bone tangle at bind pose.
+//! The **missing-sequence fallback** (`0x5f3930`) is no longer deferred: [`remap_missing`]
+//! implements the four-way remap, including the two legs that freeze a *motion* clip at frame 0 to
+//! stand in for an absent rest pose. It is not a corner case — the Ahn'Qiraj gate's roots
+//! (`AHN_QIRAJ_DOORROOTS`, Stand + Open only) took the "play nothing" path and rendered its 42-bone
+//! tangle at bind pose.
 //!
 //! Still deferred (noted, not this slice): the **ANIMPROGRESS** half — the field selects the *motion*
 //! substate rather than the rest one at spawn, and seeks the clip to `duration × progress / 100`
-//! (wow-re `gameobject-anim-arm.md` §2b, `go-anim-state-machine.md`'s seek section); benilla reads
+//! (`0x5f3c30`, `0x5f3ac5`); benilla reads
 //! only `GAMEOBJECT_STATE` and always plays from frame 0. And the mid-flight **reverse blend**
 //! (interrupting a half-open door).
 
@@ -74,7 +75,6 @@ use std::time::Duration;
 
 use crate::creature_anim::{advance_track, scan_events, AnimSoundEvent};
 use crate::net::{GuidIndex, ObjectStore};
-use benilla_world::model_fade::DespawnFade;
 use benilla_world::schedule::WorldStage;
 
 /// `GO_STATE_ACTIVE` (vmangos `GOState`) — the **open** state (door swung, chest lid up). Passable.
@@ -84,7 +84,7 @@ const GO_STATE_ACTIVE: u32 = 0;
 const GO_STATE_READY: u32 = 1;
 
 /// `AnimationData.dbc` **157 Despawn** — the id the one-shot channel's code 6 resolves to
-/// (wow-re `gameobject-anim-arm.md` §2c: `0x80b0e0[6]` = substate 12, `0x8607e4[12]` = 157). The
+/// (`0x80b0e0[6]` = substate 12, `0x8607e4[12]` = 157). The
 /// object plays this once and *then* goes away; see [`DespawnAnimAnnounced`].
 const ANIM_DESPAWN: u16 = 157;
 
@@ -94,7 +94,7 @@ const ANIM_DESPAWN: u16 = 157;
 #[derive(Component, Default)]
 pub(crate) struct GoAnim {
     /// Client-authoritative `GAMEOBJECT_STATE` (the binary's stored `go+0x27c`) — the single source of
-    /// truth for the §243 animation + collision. Written by the three "SetGoState callers": the wire
+    /// truth for the animation + collision. Written by the three "SetGoState callers": the wire
     /// sync, the open-lock spell-go, and the loot-release. `None` until first sight.
     state: Option<u32>,
     /// The state we last *animated* to — resolves which transition motion to play next. Distinct from
@@ -103,7 +103,7 @@ pub(crate) struct GoAnim {
     /// must not replay its swing).
     shown: Option<u32>,
     /// A pending **one-shot** play, as an `AnimationData.dbc` id — the second, disjoint arm
-    /// channel of wow-re `gameobject-anim-arm.md` §2c, never the §243 lid family. The reference
+    /// channel, never the lid family. The reference
     /// has ONE such slot fed by ONE entry point (`0x5f8c50(GO, code)` → slot 15), whose 7-entry
     /// code table `0x80b0e0` is the whole channel:
     ///
@@ -116,25 +116,25 @@ pub(crate) struct GoAnim {
     /// Written by [`queue_custom_anim`] / [`arm_despawn_anim`], consumed by [`drive_go_anim`]
     /// AFTER the state arm, so the bobber's same-frame pair (the forced `READY → ACTIVE` flip +
     /// the splash) resolves with the splash on top (decision 1086). Slot 15 pre-gates on the model
-    /// OWNING the resolved id, so this channel takes no §2c remap (decisions 1086/1404).
+    /// OWNING the resolved id, so this channel takes no remap (decisions 1086/1404).
     one_shot: Option<u16>,
     /// The clip armed for the current **TRANSIENT substate**, if any — the completion-retire's
-    /// watch (decisions 1100/1151, wow-re `gameobject-anim-arm.md` §2d + `go-display-sound-events.md`
-    /// §6-8). The reference keeps exactly one current substate in `[handler+0x10]`, and its
+    /// watch (decisions 1100/1151). The reference keeps exactly one current substate in
+    /// `[handler+0x10]`, and its
     /// per-model completion callback fires ONCE at the arm's baked window end (span × replay, the
     /// loop bit ignored); slot 14 `0x5f4120` then advances a transient substate onto its rest one
     /// and arms that pose over the transient clip. **Two families reach it, and they share this
-    /// one slot exactly as the reference's does**: the §243 transition motions (2 Open / 4 Close /
+    /// one slot exactly as the reference's does**: the transition motions (2 Open / 4 Close /
     /// 5 Destroy / 7 Rebuild) and the Custom0..3 block (8..11). [`retire_transient_anim`] models
     /// the advance for both; without it a bit-0-clear clip runs for ever — the bobber's splash
     /// looping ~1.3 s (1100's 2-3 audible splashes) and the crate lid never settling shut (1151).
     transient: Option<Transient>,
     /// The **rest** pose's armed clip node, when that pose is on the re-arm cycle below. Distinct
     /// from [`Self::transient`], which is the reference's ONE transient-substate slot
-    /// (`[handler+0x10]`) and drives the §2d *advance*: a rest pose never advances, it re-arms
+    /// (`[handler+0x10]`) and drives the *advance*: a rest pose never advances, it re-arms
     /// **itself**. `None` while a transient owns the model, on the rate-0 frozen leg (which never
-    /// completes), and once the §2c already-playing check has refused the re-arm and the pose has
-    /// settled for good.
+    /// completes), and once the already-playing check (`0x5f39fa`) has refused the re-arm and the
+    /// pose has settled for good.
     rest_window: Option<AnimationNodeIndex>,
     /// The state the machine last **dispatched** — the reference's `0x5f3cb0(old, new)` entry,
     /// distinct from [`Self::shown`] because the completion retire clears `shown` to force a
@@ -145,7 +145,7 @@ pub(crate) struct GoAnim {
     /// display-sound loop registration ([`GoStateDispatch`]).
     dispatched: Option<u32>,
     /// The **requested** animation id currently armed — the reference's `[block0+0xf8]`, written by
-    /// op4 (`0x71252f`) and read back by `0x712090(model, -1)`. The §2c *remap* legs consult it
+    /// op4 (`0x71252f`) and read back by `0x712090(model, -1)`. The *remap* legs consult it
     /// (`0x5f39fa: cmp esi,eax; je 0x5f3b32`) and refuse an arm that would request what is already
     /// playing; the model-owns-it leg (`0x5f396c jne`) and the collapse-to-Stand leg
     /// (`0x5f3a54 jmp 0x5f3a0b`, past the check) do not. That asymmetry is the whole difference
@@ -155,7 +155,7 @@ pub(crate) struct GoAnim {
 
 /// The GameObject **state-machine dispatch** ran on this entity — the reference's `0x5f3cb0`,
 /// whose first act is `0x5f3cc8 call 0x5f40c0`: **release whatever display-sound loop the object
-/// holds** (wow-re `go-display-sound-events.md` §2/§6c). Consumed by
+/// holds**. Consumed by
 /// [`crate::sound::gameobject`], which owns that registration; the animation half of the dispatch
 /// is [`drive_go_anim`]'s own work and needs no message.
 ///
@@ -193,7 +193,7 @@ struct Transient {
 }
 
 /// The GameObject's **stored** state — the binary's `go+0x27c`, which is what every consumer reads
-/// (the §243 animation, `usable`'s state pre-gate, and the lock chain's per-slot Action gate,
+/// (the animation, `usable`'s state pre-gate, and the lock chain's per-slot Action gate,
 /// decision 0752). [`GoAnim::state`] when the object is on the animation machine (it carries the
 /// client-side predictions the wire never sends — a chest's lid), else the wire field, else the
 /// wire default `0` = ACTIVE for a field vmangos omitted because it was zero.
@@ -203,10 +203,10 @@ pub(crate) fn go_state(anim: Option<&GoAnim>, store: &ObjectStore) -> u32 {
         .unwrap_or(GO_STATE_ACTIVE)
 }
 
-/// The inspector's GameObject **animation** readout (decision 1151): which sequence the §243 arm
+/// The inspector's GameObject **animation** readout (decision 1151): which sequence the state arm
 /// is actually playing on the object under the cursor — its `AnimationData` id, whether it is the
 /// state's held **rest** pose or a **transient** one (a transition motion, or a Custom block, which
-/// [`retire_transient_anim`]'s §2d advance ends at its window end), and the repeat the player is
+/// [`retire_transient_anim`]'s advance ends at its window end), and the repeat the player is
 /// running it under. `None` when the object renders as a static mesh, or nothing is armed yet.
 ///
 /// The line that closes the loop on this whole class of report. "The crate is stuck open/closing"
@@ -234,8 +234,8 @@ pub(crate) fn armed_anim(
     ))
 }
 
-/// Which GameObject types get the state-driven **animated** instance (skinned lid/door + §243
-/// sequences) — **the byte-verified type census**, not a guess (wow-re `gameobject-anim-arm.md` §2f).
+/// Which GameObject types get the state-driven **animated** instance (skinned lid/door + state
+/// sequences) — **read off the binary's type dispatch**, not a guess.
 ///
 /// `CGGameObject::LoadBaseObject` dispatches on the wire TYPE_ID through the 31-entry jump table at
 /// `0x5f76cc` (`cmp ecx,0x1e` + *unsigned* `ja`, so 0..30) and allocates a per-type strategy handler
@@ -243,7 +243,7 @@ pub(crate) fn armed_anim(
 /// **allocation size**: every type whose handler is `0x1c` bytes gets a 36-slot vtable carrying the
 /// real `0x5f3c30`/`0x5f3b50` arm; every other size gets a 34-slot vtable whose corresponding slots
 /// are the abstract base's do-nothing bodies — and whose `+0x88` doesn't even exist (reading it walks
-/// into the next vtable, which is what made an earlier census report plausible nonsense).
+/// into the next vtable, which is what makes a naive census of `+0x88` report plausible nonsense).
 ///
 /// So the machine is **20 of the 31 types**, not the three we had:
 ///
@@ -337,10 +337,9 @@ impl Play {
     }
 }
 
-/// The §2c **missing-sequence remap** — what the arm actually requests when the model doesn't author
-/// the state's animation id. Byte-verified twice over (wow-re `gameobject-anim-arm.md` §2c's
-/// `0x5f3972` jump table `0x5f3b40`, and `go-anim-state-machine.md`'s independent read of the same
-/// switch), it is a four-way table keyed on the id, consulted only after the ownership test
+/// The **missing-sequence remap** — what the arm actually requests when the model doesn't author
+/// the state's animation id. Read off `0x5f3972`'s jump table `0x5f3b40`, it is a four-way table
+/// keyed on the id, consulted only after the ownership test
 /// [`ModelAnimations::owns`] (the reference's `0x711960`) says no:
 ///
 /// | missing    | condition         | requests instead           |
@@ -387,7 +386,8 @@ fn remap_missing(anims: &ModelAnimations, id: u16) -> (u16, bool) {
     }
 }
 
-/// The held rest-pose animation-id for a wire `GAMEOBJECT_STATE` (§243). `None` for an unmapped state.
+/// The held rest-pose animation-id for a wire `GAMEOBJECT_STATE` (`0x5f3c30`). `None` for an
+/// unmapped state.
 fn rest_anim(state: u32) -> Option<u16> {
     match state {
         0 => Some(0x95), // ACTIVE  → Opened (held open)
@@ -397,10 +397,10 @@ fn rest_anim(state: u32) -> Option<u16> {
     }
 }
 
-/// The transition-motion animation-id for a `prev → cur` state change (§243), i.e. the swing. `None`
+/// The transition-motion animation-id for a `prev → cur` state change, i.e. the swing. `None`
 /// when the pair has no distinct motion (falls back to snapping the rest pose).
 ///
-/// The reference (`0x5f3cb0`, byte-verified in wow-re `go-anim-state-machine.md`) dispatches on the
+/// The reference (`0x5f3cb0`) dispatches on the
 /// **NEW** state and lets OLD pick transient-vs-rest: NEW 0 takes the Open motion from OLD 1 (else
 /// rests Opened), NEW 1 takes Close from OLD 0 / Rebuild from OLD 2 (else rests Closed), NEW 2 takes
 /// Destroy from OLD 1 (else rests Destroyed). Our `(_, 2)` wildcard got that last row wrong: an
@@ -431,7 +431,8 @@ fn resolve(prev: Option<u32>, cur: u32) -> Option<Play> {
     }
 }
 
-/// Caller 1 (the wire, §243): track each animated GO's `GAMEOBJECT_STATE` from the wire, acting only on a
+/// Caller 1 (the wire, `0x5f89e0`): track each animated GO's `GAMEOBJECT_STATE` from the wire,
+/// acting only on a
 /// *genuine* wire change. This is the door/button driver (the server flips their state over the wire) and
 /// the first-sight rest-pose seed for every animated GO (a chest streams in closed). Two inputs, both
 /// exact (decision 2297): the seed (`Added<GoAnim>`, when attach tags the entity — read off the store),
@@ -496,7 +497,7 @@ fn open_go_lid(
 }
 
 /// Caller 4 (the custom-anim opcode, decision 1086): queue the one-shot Custom play. This is the
-/// **disjoint** arm channel of wow-re `gameobject-anim-arm.md` §step 8 — it never touches
+/// **disjoint** arm channel (`0x5f8c50`) — it never touches
 /// [`GoAnim::state`] (the lid family), rejects `anim_id >= 4` exactly as the reference handler
 /// does, and maps the index to its AnimationData id (`153 + n`, Custom0..3). Ownership is judged
 /// at play time by [`drive_go_anim`] (the model components live there); a guid with no [`GoAnim`]
@@ -509,7 +510,7 @@ fn queue_custom_anim(
 ) {
     for GoCustomAnim { go_guid, anim_id } in plays.read().copied() {
         let Some(id) = custom_anim_id(anim_id) else {
-            continue; // the reference handler's own reject (step 8)
+            continue; // the reference handler's own reject (`0x5f8971`)
         };
         let Some(&e) = index.0.get(&go_guid) else {
             continue;
@@ -521,8 +522,8 @@ fn queue_custom_anim(
 }
 
 /// The wire Custom index → its AnimationData id (`153 + n`, Custom0..3), or `None` for the
-/// reference handler's reject (`anim_id >= 4` — wow-re `gameobject-anim-arm.md` step 8's
-/// "opcode `0xb3` byte `b` (reject `b >= 4`), substate `8+b`").
+/// reference handler's reject (`anim_id >= 4` — `0x5f8971`: opcode `0xb3` byte `b`, reject
+/// `b >= 4`, substate `8+b`).
 fn custom_anim_id(anim_id: u32) -> Option<u16> {
     (anim_id < 4).then(|| 153 + anim_id as u16)
 }
@@ -542,8 +543,8 @@ fn custom_anim_id(anim_id: u32) -> Option<u16> {
 pub(crate) struct DespawnAnimAnnounced;
 
 /// The reference's **pending-destroy mark** — `[GO+0xe4]` bit `0x10`, set by the object-manager
-/// destroy `0x464920` when it finds the object still pinned (wow-re
-/// `go-display-sound-events.md` §6d, §5-VERIFIED). The arm takes the pin whenever the armed
+/// destroy `0x464920` when it finds the object still pinned.
+/// The arm takes the pin whenever the armed
 /// substate is not a resting one (`0x5f3b27 call 0x4683e0` → refcount `[obj+0xe8]`), slot 14's
 /// footer releases it at the window end (`0x468410`), and only then does the deferred destroy run
 /// (`0x46844a call 0x464920`) — which is how an object gets to finish its own despawn animation
@@ -597,8 +598,11 @@ fn arm_despawn_anim(mut gos: Query<&mut GoAnim, Changed<DespawnAnimAnnounced>>)
 /// scheduler `0x672df0` on its way out — so the object stops existing while its model keeps
 /// drawing and ramps to zero. A looted chest whose static model authors no `Despawn` sequence is
 /// exactly this path with no animation in front of it, and popping it was the report that found
-/// the missing hop. [`DespawnFade`] is that hand-off; it arms once and drives itself, so the pin
-/// comes off with it and this query stops matching.
+/// the missing hop. [`DespawnFade`](benilla_world::model_fade::DespawnFade) is that hand-off; it
+/// arms once and drives itself, so the pin comes off with it and this query stops matching. The
+/// hand-off is [`crate::net::tear_down`], the same one both wire routes take, so the object's
+/// identity ends here too — a pinned object is still an object while it plays, and stops being
+/// one when the pin drops.
 fn release_despawn_pin(
     mut commands: Commands,
     pinned: Query<(Entity, Option<&GoAnim>), With<PendingDestroy>>,
@@ -610,7 +614,7 @@ fn release_despawn_pin(
         commands
             .entity(e)
             .try_remove::<PendingDestroy>()
-            .try_insert(DespawnFade::default());
+            .queue_silenced(crate::net::tear_down);
     }
 }
 
@@ -639,9 +643,9 @@ fn close_go_lid(
     *last_source = current;
 }
 
-/// The **completion-driven retire** of the current TRANSIENT substate — the §2d advance
-/// (decisions 1100/1151; wow-re `gameobject-anim-arm.md` §2d/§3 + `go-display-sound-events.md`
-/// §6-8, §5-verified). The reference registers a per-model completion callback at GO model attach
+/// The **completion-driven retire** of the current TRANSIENT substate — the substate advance
+/// (decisions 1100/1151).
+/// The reference registers a per-model completion callback at GO model attach
 /// (`0x5f7d43` → `[M2+0x70]`) which the driver `0x719370` fires ONCE when the armed sequence
 /// reaches its baked window end — span × replay-count, the **loop bit ignored** — and slot 14
 /// `0x5f4120` dispatches on the current substate:
@@ -665,12 +669,10 @@ fn close_go_lid(
 /// **The last row is not "nothing", and 1151 read it as such.** `0x5f4167` is byte-for-byte slot
 /// 34's own selection and calls `0x5f3930` **directly**, bypassing slot 34's change guard on an
 /// unchanged `[handler+0x10]` — so a resting substate re-issues its own op4, and with it a fresh
-/// `variationIdx = -1` roll, every `span × R` ms for ever (wow-re `gameobject-anim-arm.md` §6c/§6d,
-/// §5-arbitrated). The completion that drives it ignores the loop bit (`0x719503` tests it only
-/// after the notify block), so a bit-0-CLEAR pose completes too. That is why Onyxia's lava traps
-/// spurt *continuously* rather than once at stream-in, and it is the same law `loop-replay-fidget.md`
-/// §7 and `doodad-anim-host.md` §5 already carried for units and placed doodads — the GameObject
-/// note was the outlier.
+/// `variationIdx = -1` roll, every `span × R` ms for ever. The completion that drives it ignores
+/// the loop bit (`0x719503` tests it only after the notify block), so a bit-0-CLEAR pose completes
+/// too. That is why Onyxia's lava traps spurt *continuously* rather than once at stream-in, and it
+/// is the same law units and placed doodads follow.
 ///
 /// Benilla therefore arms EVERY clip `Never`-repeat (one window, the same endpoint), so "the
 /// window ended" is the player's finished flag; the retire then clears `shown`, which makes the
@@ -722,7 +724,7 @@ fn retire_transient_anim(
 }
 
 /// **The GameObject arm's instrument** (`WOW_MOVE_TRACE_TAGS=goa`) — one line per arm, carrying
-/// everything the roll decided: the requested `AnimationData.dbc` id, what the §2c remap turned it
+/// everything the roll decided: the requested `AnimationData.dbc` id, what the remap turned it
 /// into, the `_rand` draw itself, and the **file sequence slot** the weighted walk landed on.
 ///
 /// That last column is the one this exists for. A GameObject's variation chain is not cosmetic:
@@ -758,7 +760,7 @@ fn trace_arm(
     );
 }
 
-/// Play the §243 sequence for a change of the client-side [`GoAnim::state`] (written by any of the three
+/// Play the sequence for a change of the client-side [`GoAnim::state`] (written by any of the three
 /// callers). Mirrors the state-transition detection of [`crate::sound::gameobject`] (first sight silent),
 /// but points it at the model instead of the mixer — one system owns the visual, the other the audio.
 fn drive_go_anim(
@@ -773,12 +775,12 @@ fn drive_go_anim(
         Changed<GoAnim>,
     >,
     mut dispatch: MessageWriter<GoStateDispatch>,
-    // The client's single `_rand` stream (wow-re `rf36-rand-stub.md`), as `creature_anim` keeps
+    // The client's single `_rand` stream (`0x7400e5`), as `creature_anim` keeps
     // one: op4's variation roll draws from it on every GameObject arm below.
     mut rng: ResMut<benilla_assets::AnimRng>,
 ) {
     for (entity, mut go, mut player, mut tr, anims) in &mut gos {
-        // ── The §243 state arm ─────────────────────────────────────────────────────────────────
+        // ── The state arm ──────────────────────────────────────────────────────────────────────
         if let Some(state) = go.state {
             if go.shown != Some(state) {
                 let prev = go.shown;
@@ -798,11 +800,11 @@ fn drive_go_anim(
                 go.rest_window = None;
                 if let Some(play) = resolve(prev, state) {
                     // Resolve the id to this model's clip (keyed by AnimationData.dbc id, as
-                    // `creature_anim` does), through the §2c remap for a model that doesn't author
+                    // `creature_anim` does), through the remap for a model that doesn't author
                     // it — that is what keeps a lidless model on a real pose instead of bind.
                     let (want, frozen) = remap_missing(anims, play.anim_id());
-                    // **`variationIdx = -1` — the arm ROLLS a variation** (wow-re
-                    // `gameobject-anim-arm.md` §2c, `0x5f3aee: push -1`), unlike the §1 loader seed
+                    // **`variationIdx = -1` — the arm ROLLS a variation** (`0x5f3aee: push -1`),
+                    // unlike the loader seed
                     // beneath it, which passes an explicit `0` (`0x710189`). Where a model authors
                     // one sequence per id the two are the same clip and nothing changes; where it
                     // authors a chain they are not, and taking the head is a whole authored
@@ -812,7 +814,7 @@ fn drive_go_anim(
                     // the 300/s `LAVALUMP2` burst, the lava spurting out of the floor. Every one of
                     // the 208 trap GameObjects in the lair took the head, so the chamber's whole
                     // ember field was missing.
-                    // **The §2c already-playing skip, and it decides settle-vs-cycle.** Three
+                    // **The already-playing skip, and it decides settle-vs-cycle.** Three
                     // edges reach the arm (`0x5f3a0b`): the model OWNS the table id
                     // (`0x5f396c jne`), the model is not live, and the 147-absent collapse to
                     // Stand (`0x5f3a52 xor esi,esi; 0x5f3a54 jmp 0x5f3a0b` — a backwards jump
@@ -852,8 +854,7 @@ fn drive_go_anim(
                             // parked at rate 0 (the same Open clip serves both) would stay stuck.
                             active.set_speed(1.0);
                             // **ONE baked window, rest pose included** (decision 1151 for the
-                            // motions; wow-re
-                            // `gameobject-anim-arm.md` §6, correcting 1151's "nothing advances off
+                            // motions; correcting 1151's "nothing advances off
                             // a held pose"). The completion notification `0x719370` fires at
                             // `span × R` **without consulting the loop bit** (`0x719503` tests it
                             // only afterwards), so a bit-0-CLEAR rest clip completes too — and
@@ -866,10 +867,9 @@ fn drive_go_anim(
                             // a 10 % weight, and with a 5 s ember life that leaves **47 % of them
                             // holding a live plume at any instant** (measured, `WOW_PARTICLE_CENSUS`
                             // in the lair: 49 of 104), instead of one flurry at stream-in. The
-                            // period, the re-roll and `R = 1` from a `(0,0)` replay pair are all
-                            // byte-converged across two independent §5 rounds; what is *not*
-                            // settled is which per-frame advance list a GameObject's model rides
-                            // (wow-re `gameobject-anim-arm.md` §6's named residual).
+                            // period (`0x7126d8`), the re-roll and `R = 1` from a `(0,0)` replay
+                            // pair (`0x7126c3`) are all settled in the binary; what is *not*
+                            // settled is which per-frame advance list a GameObject's model rides.
                             active.set_repeat(RepeatAnimation::Never);
                             match play {
                                 Play::Motion(_) => {
@@ -884,9 +884,9 @@ fn drive_go_anim(
                 }
             }
         }
-        // ── The one-shot Custom channel (step 8, decision 1086) — AFTER the state arm, so the
+        // ── The one-shot Custom channel (`0x5f8c50`, decision 1086) — AFTER the state arm, so the
         // bobber's same-frame pair (forced READY→ACTIVE flip + splash) lands splash-on-top.
-        // Gated on the model OWNING the id; no §2c remap on this channel — an unowned Custom
+        // Gated on the model OWNING the id; no remap on this channel — an unowned Custom
         // plays nothing. Armed for ONE window regardless of the sequence's loop flag (decision
         // 1099, correcting 1090's loop-forever): the kernel does loop a bit0-clear clip and
         // re-fires its events per pass, but the reference's COMPLETION callback fires at window
@@ -899,8 +899,8 @@ fn drive_go_anim(
         if go.one_shot.is_some() {
             let id = go.one_shot.take().expect("checked is_some");
             if anims.owns(id) {
-                // Slot 15 funnels through the same slot-34 → `0x5f3930` arm as the state channel
-                // (§2c), so it rolls a variation for the same reason — a Custom0 with two authored
+                // Slot 15 funnels through the same slot-34 → `0x5f3930` arm as the state channel,
+                // so it rolls a variation for the same reason — a Custom0 with two authored
                 // takes alternates them.
                 let roll = rng.draw();
                 if let Some(clip) = anims.pick_variation(id, roll) {
@@ -981,8 +981,8 @@ fn drive_go_collision(
 /// registrar pair. The consumer is a single instruction, `0x5f85f6 test ah,ah` inside `0x5f85f0` —
 /// `CGGameObject_C`'s collision-candidacy virtual at primary-vtable slot `+0x50` — which reads the
 /// bit through the sign flag and answers *no candidate* for a GameObject whose
-/// `GAMEOBJECT_TYPE_ID` is `0`, DOOR. Nothing else about a ghost's collision differs (wow-re
-/// `collision/scratch/ghost-door-tracemask.md`, decision 1767).
+/// `GAMEOBJECT_TYPE_ID` is `0`, DOOR. Nothing else about a ghost's collision differs
+/// (decision 1767).
 ///
 /// **Off the MOVER's descriptor, not ours.** The producer tests the object being traced, so a
 /// possessed creature is not a player and never sets the bit; `player_is_ghost` reading a field a
@@ -1040,8 +1040,8 @@ type ScannedGo = (
 );
 
 /// Fire the event keyframes an animated GameObject's playing clip crossed this frame — the GO
-/// half of the M2 event-kernel surface (wow-re `go-display-sound-events.md`, the 1086 fold-back
-/// record): the reference registers an event callback per **family-A** GO at create
+/// half of the M2 event-kernel surface (decision 1086): the reference registers an event callback
+/// per **family-A** GO at create
 /// (`0x5f7d1f` → vtable `+0x30` → dispatcher `0x5f3e20`), which is exactly the [`GoAnim`]
 /// population — a loader-idle family-B GO has no dispatcher and stays silent. The events flow
 /// into the same [`AnimSoundEvent`] stream the creature scanner feeds: the generic `$SND`/`$DSO`/
@@ -1132,6 +1132,7 @@ pub(crate) fn plugin(app: &mut App) {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use benilla_world::model_fade::DespawnFade;
 
     /// **A ghost's mover drops DOOR GameObjects — and nothing else** (decision 1767).
     ///
@@ -1200,7 +1201,7 @@ mod tests {
         assert!(matches!(resolve(Some(2), 1), Some(Play::Motion(0x98))));
     }
 
-    /// The custom-anim channel's wire mapping (step 8, decision 1086): indices 0..3 arm
+    /// The custom-anim channel's wire mapping (`0x5f8930`, decision 1086): indices 0..3 arm
     /// Custom0..3 (AnimationData 153..156); anything else is the reference handler's reject.
     /// The fishing bobber's bite is index 0 → 153 — exactly the second sequence
     /// `G_FishingBobber.m2` authors.
@@ -1383,7 +1384,7 @@ mod tests {
     ///
     /// The whole door family is `flags` bit 0 clear, so a driver that arms a transition by the
     /// clip's loop bit arms Close on `Forever`: the lid jumps back to 75° every 667 ms. What ends
-    /// a transition in the reference is the object layer's §2d advance (slot 14 `0x5f4120`:
+    /// a transition in the reference is the object layer's advance (slot 14 `0x5f4120`:
     /// substate 4 Close → 1 Closed), driven by the completion callback at the arm's baked window
     /// — the loop bit ignored. This runs the whole click-to-settle cycle through the real systems
     /// and real clips, and then keeps running: two seconds past the swing, three Close windows
@@ -1402,7 +1403,7 @@ mod tests {
         // Streamed in closed: the rest pose, snapped. It is ONE baked window like everything else
         // — `0x5f4167` re-arms a resting substate through `0x5f3930` at its own completion, so the
         // pose repeats by re-arming (and re-rolling its variation), not by the kernel's loop bit
-        // (wow-re `gameobject-anim-arm.md` §6; this corrects 1151's "nothing advances off a held
+        // (this corrects 1151's "nothing advances off a held
         // pose"). What must hold across those windows is the armed ID, asserted below.
         app.update();
         assert_eq!(armed(&app, go), Some((0x93, RepeatAnimation::Never)));
@@ -1451,8 +1452,8 @@ mod tests {
         }
     }
 
-    /// **The arm rolls a VARIATION** — `variationIdx = -1` (wow-re `gameobject-anim-arm.md` §2c,
-    /// `0x5f3aee: push -1`), not the id's head. The §1 loader seed under it takes an explicit
+    /// **The arm rolls a VARIATION** — `variationIdx = -1` (`0x5f3aee: push -1`), not the id's
+    /// head. The loader seed under it takes an explicit
     /// variation 0 (`0x710189`), so a model's second and later takes are reachable ONLY through
     /// this arm; resolving the id with `find()` made them unreachable everywhere.
     ///
@@ -1524,7 +1525,7 @@ mod tests {
     }
 
     /// **A rest pose is ONE window, and its completion re-arms it — with a FRESH roll, for ever**
-    /// (wow-re `gameobject-anim-arm.md` §6c/§6d, correcting 1151's "nothing advances off a held
+    /// (correcting 1151's "nothing advances off a held
     /// pose"). `0x719370` fires the completion at `span × R` without consulting the loop bit
     /// (`0x719503` tests it only afterwards), and slot 14's resting row `0x5f4167` calls
     /// `0x5f3930` directly — past slot 34's change guard — on an unchanged substate.
@@ -1563,12 +1564,12 @@ mod tests {
             "over 300 windows the pose showed takes {seen:?} — a rest pose that never re-armed \
              would show exactly one, and Onyxia's floor would spurt once and go quiet"
         );
-        // The pose itself never wanders off Closed: re-arming is not the §2d substate advance.
+        // The pose itself never wanders off Closed: re-arming is not the substate advance.
         assert!(matches!(armed(&app, go), Some((0x93, _))));
     }
 
-    /// **The state dispatch is an EDGE, and a rest pose re-arming itself is not one** (wow-re
-    /// `go-display-sound-events.md` §6c: slot 14 sends a resting substate to `0x5f4167`, which
+    /// **The state dispatch is an EDGE, and a rest pose re-arming itself is not one** (slot 14
+    /// sends a resting substate to `0x5f4167`, which
     /// calls `0x5f3930` directly and never re-enters `0x5f3cb0`). That is the whole reason a
     /// brazier's `TorchLoop` — a looping display-slot kit registered by a `$GO2` on the Opened
     /// rest pose — hums continuously instead of being released and restarted every band pass,
@@ -1677,9 +1678,11 @@ mod tests {
         assert_eq!(armed(&app, go), Some((0x93, RepeatAnimation::Never)));
 
         // The wire pair, in the order vmangos sends it and Commands apply it.
-        app.world_mut()
-            .entity_mut(go)
-            .insert((DespawnAnimAnnounced, PendingDestroy));
+        app.world_mut().entity_mut(go).insert((
+            crate::net::Guid(0xF110_0000_0000_0E66),
+            DespawnAnimAnnounced,
+            PendingDestroy,
+        ));
         app.update();
         assert_eq!(
             armed(&app, go),
@@ -1687,8 +1690,8 @@ mod tests {
             "the announcement arms 157 Despawn for ONE window"
         );
         assert!(
-            app.world().get_entity(go).is_ok(),
-            "the pin holds the object alive across its own destroy"
+            app.world().get::<crate::net::Guid>(go).is_some(),
+            "the pin holds the OBJECT alive across its own destroy, not just its model"
         );
 
         advance(&mut app, 2700);
@@ -1697,6 +1700,10 @@ mod tests {
             app.world().get::<DespawnFade>(go).is_some(),
             "the window ended — the pin drops and the deferred destroy hands the model to the fade"
         );
+        assert!(
+            app.world().get::<crate::net::Guid>(go).is_none(),
+            "…and the deferred destroy is the teardown: the object ends as the fade begins"
+        );
         assert!(
             app.world().get::<PendingDestroy>(go).is_none(),
             "and the pin comes off with it, so the release stops re-arming the fade"
diff --git a/crates/benilla-app/src/go_templates.rs b/crates/benilla-app/src/go_templates.rs
index 2491a658..798920c7 100644
--- a/crates/benilla-app/src/go_templates.rs
+++ b/crates/benilla-app/src/go_templates.rs
@@ -74,8 +74,7 @@ pub(crate) struct GoTemplate {
     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`, wow-re
-    /// quest-material-reward-spell-bindings.md §1).
+    /// (10) reads `data[9]`, every other type answers none (`0x5f5950`).
     pub(crate) quest_material: Option<u32>,
 }
 
@@ -241,8 +240,7 @@ mod tests {
     }
 
     /// The quest-giver material arm — by type: QUESTGIVER (2) and GOOBER (9) read `data[2]`,
-    /// CHEST (10) reads `data[9]`, anything else none (`0x5f5950`, wow-re
-    /// quest-material-reward-spell-bindings.md §1).
+    /// CHEST (10) reads `data[9]`, anything else none (`0x5f5950`).
     #[test]
     fn insert_captures_the_quest_material_by_type() {
         let mut t = GameObjectTemplates::default();
diff --git a/crates/benilla-app/src/hover_log.rs b/crates/benilla-app/src/hover_log.rs
index af3cd490..75113601 100644
--- a/crates/benilla-app/src/hover_log.rs
+++ b/crates/benilla-app/src/hover_log.rs
@@ -28,13 +28,25 @@ use benilla_ui::script::UiScript;
 /// 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` ⇒ the default path, anything else ⇒
-/// that path.
+/// 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.
 fn log_path() -> Option<String> {
     match std::env::var("WOW_HOVER_LOG") {
         Err(_) => None,
         Ok(v) if v.is_empty() || v == "0" => None,
-        Ok(v) if v == "1" => Some("target/hover-log.csv".to_string()),
+        Ok(v) if v == "1" => match crate::local_state::diagnostics_dir() {
+            Some(dir) => Some(dir.join("hover-log.csv").to_string_lossy().into_owned()),
+            None => {
+                warn!(
+                    "hover log: no benilla-config folder to write into (hermetic run) — set \
+                     WOW_HOVER_LOG=<path> to name one. Not recording."
+                );
+                None
+            }
+        },
         Ok(v) => Some(v),
     }
 }
diff --git a/crates/benilla-app/src/items.rs b/crates/benilla-app/src/items.rs
index 985f4601..e30d9ba5 100644
--- a/crates/benilla-app/src/items.rs
+++ b/crates/benilla-app/src/items.rs
@@ -1,14 +1,17 @@
 //! The item layer — decision 0068's T2 (containers) groundwork.
 //!
-//! The wire splits item knowledge in two, so this module holds two stores:
+//! 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). Keyed by guid,
-//!   holding the merged descriptor fields — entry, stack count, a bag's slot guids. 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; this store resolves those guids to actual items. Fed by
-//!   the net bridge (create seed → `Values` merges → destroy), cleared whole on disconnect (the
-//!   server re-streams inventory at login; stale bags are worse than empty ones).
+//!   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
@@ -17,15 +20,227 @@
 //!   reports "not yet". Negative answers are cached — a bad entry never becomes a query loop.
 //!   Templates survive disconnect: item definitions are stable across sessions.
 
-use std::collections::HashMap;
+use std::time::{Duration, Instant};
 
 use bevy::prelude::*;
 
 use benilla_protocol::{ItemInfo, ObjectFields};
 
-use crate::net::{ClientCommand, NetCommands, ObjectStore};
+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.
+#[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.
+    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.
+pub(crate) fn spawn_item(
+    commands: &mut Commands,
+    index: &mut GuidIndex,
+    guid: u64,
+    fields: ObjectFields,
+    container: bool,
+) -> Entity {
+    let e = commands
+        .spawn((
+            Guid(guid),
+            ObjectStore(fields),
+            ItemObject { container },
+            Countdowns::default(),
+        ))
+        .id();
+    index.0.insert(guid, e);
+    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`.
+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.
+#[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`.
+fn deadline(seconds: u32) -> Option<Instant> {
+    ((seconds as i32) > 0).then(|| Instant::now() + Duration::from_secs(u64::from(seconds)))
+}
+
+/// A cell's time left: `None` when unset, `Some(0)` once elapsed (`0x5d9d00`'s `max(0, …)`).
+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).
+fn remaining_ms(cell: Option<Instant>) -> Option<u64> {
+    left(cell)
+        .filter(|l| !l.is_zero())
+        .map(|l| l.as_millis() as 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.
+    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;
+        };
+        *cell = deadline(seconds);
+        true
+    }
+
+    /// `SMSG_ITEM_TIME_UPDATE`'s setter `0x5d9c00`.
+    pub(crate) fn set_lifetime(&mut self, seconds: u32) {
+        self.lifetime = deadline(seconds);
+    }
+
+    fn enchant(&self, slot: u32) -> Option<Instant> {
+        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).
+    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`).
+    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.
+    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.
+    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.
+    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.
+    fn steps(&self, now: Instant) -> u64 {
+        std::iter::once(self.lifetime)
+            .chain(self.enchants)
+            .flatten()
+            .map(|at| {
+                let left = at.saturating_duration_since(now);
+                if left.is_zero() {
+                    0
+                } else {
+                    left.as_secs() + 1
+                }
+            })
+            .sum()
+    }
+}
+
+/// An item entity whose fields or countdown cells were written since the reader last ran.
+type ItemMoved = (
+    With<ItemObject>,
+    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.
+#[derive(SystemParam)]
+pub(crate) struct ItemChanges<'w, 's> {
+    changed: Query<'w, 's, (), ItemMoved>,
+    removed: RemovedComponents<'w, 's, ItemObject>,
+    countdowns: Query<'w, 's, &'static Countdowns>,
+}
+
+impl ItemChanges<'_, '_> {
+    /// Drains the removal reader, so call it once per run.
+    pub(crate) fn moved(&mut self) -> bool {
+        let removed = self.removed.read().count() > 0;
+        !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.
+    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.
+#[derive(SystemParam)]
+pub(crate) struct Inventory<'w, 's> {
+    pub(crate) self_store: Query<'w, 's, &'static ObjectStore, With<crate::net::SelfPlayer>>,
+    pub(crate) self_changed:
+        Query<'w, 's, (), (With<crate::net::SelfPlayer>, Changed<ObjectStore>)>,
+    pub(crate) objects: Objects<'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`]).
@@ -56,17 +271,16 @@ 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 (wow-re §E3 — `abs(id)` names the DBC row either way).
+/// line's colour and nothing else (`0x52c9f9` — `abs(id)` names the DBC row either way).
 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, byte-verified (wow-re
-/// `ui/scratch/tooltip-content-law.md` §E3): `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.
+/// 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
@@ -98,7 +312,7 @@ pub(crate) fn enchant_lines(
 ///
 /// 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 §6 **Soulbound** override (B310). They must agree: an item the cursor considers
+/// 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
@@ -118,7 +332,7 @@ pub(crate) fn already_bound(fields: &ObjectFields, cat: Option<&Enchants>) -> bo
 /// `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`], wow-re §E3).
+/// off `abs(id)` and keeps the sign only for the colour ([`enchant_lines`], `0x52c9f9`).
 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)
@@ -169,7 +383,7 @@ fn enchant_lines_quiet(
 /// `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 §E5 suffix-row copy).
+/// 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.
@@ -200,11 +414,11 @@ 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 §E5 mechanism, 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.
+/// 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.
@@ -291,7 +505,6 @@ impl RollCatalogs<'_> {
 /// Filled by the net bridge; read by the container APIs (`GetContainerItemInfo` and kin).
 #[derive(Resource, Default)]
 pub(crate) struct Items {
-    objects: HashMap<u64, ObjectFields>,
     /// 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.
     templates: QueryCache<u32, ItemInfo>,
@@ -299,206 +512,38 @@ pub(crate) struct Items {
     /// 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).
     fresh: Vec<u32>,
-    /// [`Self::template_epoch`]'s twin for the INSTANCE side (decision 1439): bumped by every
-    /// object create/merge/destroy and every enchant-deadline write — everything wire-driven
-    /// that can change what a bag/equipment view reads. The pair was born because `is_changed`
-    /// on this resource said nothing while the feeds' lazy `template()` resolves took `&mut
-    /// self` every frame; 2288 made those reads `&self`, and the counters stay as the finer
-    /// signal (a view keyed on one side does not rebuild for the other).
-    object_epoch: u64,
-    /// The **temporary-enchant deadlines**, keyed `(item guid, enchant slot)` — the reference's
-    /// per-item `[obj + slot*4 + 0x324]` array (wow-re `tooltip-content-law.md` §E3), whose only
-    /// feed is `SMSG_ITEM_ENCHANT_TIME_UPDATE`. NOT derived from `ITEM_FIELD_ENCHANTMENT`'s
-    /// duration field, which the reference's tooltip never reads. Session state, so it clears with
-    /// the objects (decision 0920).
-    enchant_deadlines: HashMap<(u64, u32), std::time::Instant>,
-    /// The **item-lifetime deadlines**, keyed by item guid — a duration-limited instance's
-    /// remaining life (a conjured stone, a holiday gift, a timed quest item). Its only feed is
-    /// `SMSG_ITEM_TIME_UPDATE`; the instance's own `ITEM_FIELD_DURATION` carries the same number
-    /// and is sent to the owner, but vmangos's writer says in as many words that the field is not
-    /// what the client displays from (`Item::SendTimeUpdate`, `Objects/Item.cpp:1094`). Same shape
-    /// as [`Self::enchant_deadlines`] one field up, for the same reason (decision 1933).
-    duration_deadlines: HashMap<u64, std::time::Instant>,
+    /// **`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.
+    pending_enchant_times: Vec<(u64, u32, u32)>,
 }
 
 impl Items {
-    /// Seed an item object from its create block. A re-create for a guid we already hold overlays
-    /// the fresh snapshot onto the existing store (same rule as the scene's `ObjectStore`).
-    pub(crate) fn insert_object(&mut self, guid: u64, fields: ObjectFields) {
-        match self.objects.entry(guid) {
-            std::collections::hash_map::Entry::Occupied(mut e) => e.get_mut().merge(fields),
-            std::collections::hash_map::Entry::Vacant(e) => {
-                e.insert(fields);
+    /// `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.
+    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.
+    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)| {
+            let hit = g == guid;
+            if hit {
+                taken.push((slot, seconds));
             }
-        }
-        self.object_epoch = self.object_epoch.wrapping_add(1);
-    }
-
-    /// Merge a `Values` delta into a tracked item; `false` when the guid isn't ours to track (a
-    /// delta for an item we never saw created — dropped, same as the scene path's unknown guids).
-    pub(crate) fn merge_object(&mut self, guid: u64, fields: ObjectFields) -> bool {
-        if let Some(store) = self.objects.get_mut(&guid) {
-            store.merge(fields);
-            self.object_epoch = self.object_epoch.wrapping_add(1);
-            true
-        } else {
-            false
-        }
-    }
-
-    /// The item ceased to exist (`SMSG_DESTROY_OBJECT` — consumed, sold, destroyed).
-    pub(crate) fn remove_object(&mut self, guid: u64) {
-        if self.objects.remove(&guid).is_some() {
-            self.object_epoch = self.object_epoch.wrapping_add(1);
-        }
-        self.enchant_deadlines.retain(|&(g, _), _| g != guid);
-        self.duration_deadlines.remove(&guid);
-    }
-
-    /// The instance-side broadcast counter — see the [`Self::object_epoch`] field.
-    pub(crate) fn object_epoch(&self) -> u64 {
-        self.object_epoch
-    }
-
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE` landed: park the absolute deadline for that item's enchant
-    /// slot. `seconds == 0` is the reference's own "no timer" store (`0x5d9cc0`'s `<= 0` arm), so
-    /// it REMOVES the entry rather than parking an already-expired one.
-    pub(crate) fn set_enchant_deadline(&mut self, guid: u64, slot: u32, seconds: u32) {
-        match seconds {
-            0 => {
-                if self.enchant_deadlines.remove(&(guid, slot)).is_some() {
-                    self.object_epoch = self.object_epoch.wrapping_add(1);
-                }
-            }
-            n => {
-                let at = std::time::Instant::now() + std::time::Duration::from_secs(u64::from(n));
-                self.enchant_deadlines.insert((guid, slot), at);
-                self.object_epoch = self.object_epoch.wrapping_add(1);
-                debug!("enchant timer: item {guid:#x} slot {slot} → {n}s");
-            }
-        }
-    }
-
-    /// Milliseconds left on an item's temporary enchant, 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).
-    pub(crate) fn enchant_remaining_ms(&self, guid: u64, slot: u32) -> Option<u64> {
-        let at = self.enchant_deadlines.get(&(guid, slot))?;
-        let left = at.saturating_duration_since(std::time::Instant::now());
-        (!left.is_zero()).then_some(left.as_millis() as u64)
-    }
-
-    /// [`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`).
-    pub(crate) fn enchant_remaining_display_ms(&self, guid: u64, slot: u32) -> Option<u64> {
-        self.enchant_remaining_ms(guid, slot)
-            .map(|ms| ms - ms % 1000)
-    }
-
-    /// The counter a gated feed watches instead of holding its gate open per-frame: moves exactly
-    /// when some displayable countdown can — [`Self::enchant_remaining_display_ms`] or
-    /// [`Self::duration_remaining_display_ms`], the two per-second timers a bag/equipment
-    /// snapshot renders. Each live deadline contributes `floor(seconds left) + 1` — the `+1`
-    /// makes the final `Some(0) → None` collapse (the tooltip reverting to the plain enchant
-    /// name, the duration line vanishing) its own step, one frame after the deadline elapses.
-    /// Landings and removals move [`Self::object_epoch`] on their own. Empty — the overwhelmingly
-    /// common case — costs two empty iterations.
-    pub(crate) fn countdown_display_epoch(&self) -> u64 {
-        let now = std::time::Instant::now();
-        let step = |at: &std::time::Instant| {
-            let left = at.saturating_duration_since(now);
-            if left.is_zero() {
-                0
-            } else {
-                left.as_secs() + 1
-            }
-        };
-        self.enchant_deadlines
-            .values()
-            .chain(self.duration_deadlines.values())
-            .map(step)
-            .sum()
-    }
-
-    /// 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 — VERIFIED wow-re `system/ui/scratch/weapon-enchant-info.md`), 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 wire carries **seconds** and this returns **milliseconds**, which is the
-    /// conversion `set_enchant_deadline` already performs.
-    pub(crate) fn enchant_deadline_ms(&self, guid: u64, slot: u32) -> Option<u64> {
-        let at = self.enchant_deadlines.get(&(guid, slot))?;
-        Some(
-            at.saturating_duration_since(std::time::Instant::now())
-                .as_millis() as u64,
-        )
-    }
-
-    /// `SMSG_ITEM_TIME_UPDATE` landed: park the absolute deadline for that item instance's
-    /// remaining lifetime. Same store shape as the enchant path one field up
-    /// ([`Self::set_enchant_deadline`]) — byte-confirmed as such, not assumed (decision 1933's
-    /// fold-back).
-    ///
-    /// Three rules, each the reference's:
-    ///
-    /// - **A non-POSITIVE duration clears.** `0x5d9c0c` tests the wire value **signed** (`jle`),
-    ///   so `0` and anything with the top bit set both zero the cell rather than parking a
-    ///   68-year deadline. An expired countdown is an absent line, not a line reading `0`.
-    /// - **An item we do not hold is DROPPED — no queue, no retry.** `0x1EA`'s arm resolves the
-    ///   guid and returns on a miss. This is the load-bearing asymmetry with its sibling: the
-    ///   `0x1EB` enchant arm *does* enqueue an unresolved update and replays it when the item
-    ///   appears (`0x5ebd40` → `0x5ebde0`); this one does not. Following the sibling would also
-    ///   grow this map without bound for items that never arrive.
-    /// - The cell dies with the object, so a relog or a zone destroy loses it; the server re-sends
-    ///   for everything carried on world enter (`Player::SendItemDurations`).
-    pub(crate) fn set_item_duration(&mut self, guid: u64, seconds: u32) {
-        if !self.objects.contains_key(&guid) {
-            debug!("item duration: {guid:#x} names an item we do not hold — dropped");
-            return;
-        }
-        if seconds == 0 || seconds as i32 <= 0 {
-            if self.duration_deadlines.remove(&guid).is_some() {
-                self.object_epoch = self.object_epoch.wrapping_add(1);
-            }
-            return;
-        }
-        let at = std::time::Instant::now() + std::time::Duration::from_secs(u64::from(seconds));
-        self.duration_deadlines.insert(guid, at);
-        self.object_epoch = self.object_epoch.wrapping_add(1);
-        debug!("item duration: item {guid:#x} → {seconds}s");
-    }
-
-    /// Milliseconds left on an item instance's lifetime, or `None` when it carries no timer —
-    /// including an elapsed one. Recomputed on read from the parked deadline, never ticked (the
-    /// enchant path's `0x5d9d00` shape).
-    pub(crate) fn duration_remaining_ms(&self, guid: u64) -> Option<u64> {
-        let at = self.duration_deadlines.get(&guid)?;
-        let left = at.saturating_duration_since(std::time::Instant::now());
-        (!left.is_zero()).then_some(left.as_millis() as u64)
-    }
-
-    /// [`Self::duration_remaining_ms`] at **display granularity** — floored to the whole second,
-    /// for the same reason [`Self::enchant_remaining_display_ms`] is: a raw per-ms read makes
-    /// every snapshot differ every frame and fires the inventory feeds at frame rate.
-    pub(crate) fn duration_remaining_display_ms(&self, guid: u64) -> Option<u64> {
-        self.duration_remaining_ms(guid).map(|ms| ms - ms % 1000)
-    }
-
-    /// A tracked item object's merged descriptor fields.
-    pub(crate) fn object(&self, guid: u64) -> Option<&ObjectFields> {
-        self.objects.get(&guid)
+            !hit
+        });
+        taken
     }
 
     /// The template for `entry`, if known. On a miss, asks the server (once per entry per
@@ -602,11 +647,12 @@ impl Items {
         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.
     pub(crate) fn clear_session(&mut self) {
-        self.objects.clear();
-        self.enchant_deadlines.clear();
+        self.pending_enchant_times.clear();
         self.templates.clear_pending();
-        self.object_epoch = self.object_epoch.wrapping_add(1);
     }
 }
 
@@ -629,6 +675,9 @@ impl crate::query_cache::AskOnce for Items {
 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`].
+    pub(crate) world: World,
     rx: crossbeam_channel::Receiver<ClientCommand>,
 }
 
@@ -636,13 +685,33 @@ pub(crate) struct TestDeps {
 impl TestDeps {
     pub(crate) fn new() -> Self {
         let (tx, rx) = crossbeam_channel::unbounded();
+        let mut world = World::new();
+        world.init_resource::<GuidIndex>();
         TestDeps {
             items: Items::default(),
             commands: NetCommands(tx),
+            world,
             rx,
         }
     }
 
+    /// An item object in the index — what the wire's `ItemCreate` spawns.
+    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.
+    pub(crate) fn with_objects<R>(
+        &mut self,
+        f: impl FnOnce(&Objects, &Items, &NetCommands) -> R,
+    ) -> R {
+        let (world, items, commands) = (&mut self.world, &self.items, &self.commands);
+        let mut state = bevy::ecs::system::SystemState::<Objects>::new(world);
+        let objects = state.get(world);
+        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`.
     pub(crate) fn queried_entries(&self) -> Vec<u32> {
@@ -656,6 +725,22 @@ 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`.
+#[cfg(test)]
+pub(crate) fn test_spawn_item(
+    world: &mut World,
+    guid: u64,
+    fields: ObjectFields,
+    container: bool,
+) -> Entity {
+    let e = world
+        .spawn((Guid(guid), ObjectStore(fields), ItemObject { container }))
+        .id();
+    world.resource_mut::<GuidIndex>().0.insert(guid, e);
+    e
+}
+
 /// Equipment slots 15/16 — `EQUIPMENT_SLOT_MAINHAND` / `_OFFHAND` (vmangos `EquipmentSlots`).
 pub(crate) const EQUIPMENT_SLOT_MAINHAND: u8 = 15;
 pub(crate) const EQUIPMENT_SLOT_OFFHAND: u8 = 16;
@@ -664,12 +749,13 @@ pub(crate) const EQUIPMENT_SLOT_OFFHAND: u8 = 16;
 /// slot or a template still in flight.
 fn equipped_class(
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
     slot: u8,
 ) -> Option<u8> {
     let guid = store.0.player_inv_slot(slot).filter(|&g| g != 0)?;
-    let entry = items.object(guid).and_then(|o| o.object_entry())?;
+    let entry = objects.object(guid).and_then(|o| o.object_entry())?;
     Some(items.template(entry, guid, commands)?.class as u8)
 }
 
@@ -685,25 +771,30 @@ fn equipped_class(
 /// was once missing from all three of its call sites.
 pub(crate) fn disarmed_equipment_slot(
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
 ) -> Option<u8> {
     if store.0.unit_flags() & crate::creature_anim::UNIT_FLAG_DISARMED == 0 {
         return None;
     }
-    let main = equipped_class(store, items, commands, EQUIPMENT_SLOT_MAINHAND);
-    let off = equipped_class(store, items, commands, EQUIPMENT_SLOT_OFFHAND);
+    let main = equipped_class(store, objects, items, commands, EQUIPMENT_SLOT_MAINHAND);
+    let off = equipped_class(store, objects, items, commands, EQUIPMENT_SLOT_OFFHAND);
     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).
-pub(crate) fn disarmed_equipment_slot_cached(store: &ObjectStore, items: &Items) -> Option<u8> {
+pub(crate) fn disarmed_equipment_slot_cached(
+    store: &ObjectStore,
+    objects: &Objects,
+    items: &Items,
+) -> Option<u8> {
     if store.0.unit_flags() & crate::creature_anim::UNIT_FLAG_DISARMED == 0 {
         return None;
     }
     let class_of = |slot: u8| -> Option<u8> {
         let guid = store.0.player_inv_slot(slot).filter(|&g| g != 0)?;
-        let entry = items.object(guid).and_then(|o| o.object_entry())?;
+        let entry = objects.object(guid).and_then(|o| o.object_entry())?;
         Some(items.template_cached(entry)?.class as u8)
     };
     crate::creature_anim::disarmed_hand(
@@ -813,133 +904,103 @@ mod tests {
         );
     }
 
-    /// The gated feeds' instance-side counter (1439): every object mutation moves it, a
-    /// template landing moves ONLY the template epoch, and a lazy `template()` miss — the
-    /// per-frame read that poisons `is_changed` — moves neither.
+    /// 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_object_epoch_counts_instances_and_asks_count_nothing() {
+    fn the_template_epoch_counts_landings_and_asks_count_nothing() {
         let (cmds, _rx) = commands();
         let mut items = Items::default();
-        let e0 = items.object_epoch();
+        let t0 = items.template_epoch();
 
         assert!(items.template(117, 0x42, &cmds).is_none());
-        assert_eq!(items.object_epoch(), e0, "an ask-once miss is not a change");
-        let t0 = items.template_epoch();
+        assert_eq!(
+            items.template_epoch(),
+            t0,
+            "an ask-once miss is not a change"
+        );
         items.insert_template(117, Some(info("Tough Jerky")));
-        assert_eq!(
-            items.object_epoch(),
-            e0,
-            "a landed template is the OTHER epoch's edge"
-        );
-        assert_ne!(items.template_epoch(), t0);
-
-        items.insert_object(0x42, ObjectFields::from_pairs(&[(3, 117)]));
-        let created = items.object_epoch();
-        assert_ne!(e0, created, "a create moves it");
-        items.merge_object(0x42, ObjectFields::from_pairs(&[(14, 5)]));
-        let merged = items.object_epoch();
-        assert_ne!(created, merged, "a delta moves it");
-        items.merge_object(0x99, ObjectFields::from_pairs(&[(14, 5)]));
-        assert_eq!(
-            items.object_epoch(),
-            merged,
-            "an untracked guid's delta is dropped, not counted"
-        );
-        items.remove_object(0x42);
-        assert_ne!(items.object_epoch(), merged, "a destroy moves it");
-        let removed = items.object_epoch();
-        items.remove_object(0x42);
-        assert_eq!(
-            items.object_epoch(),
-            removed,
-            "removing the already-removed is silent"
-        );
+        assert_ne!(items.template_epoch(), t0, "a landing is");
     }
 
-    /// The display epoch/quantize pair: 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 deadline zeroes the epoch (the `Some(0) → None`
-    /// collapse is the term's own last step).
+    /// 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).
     #[test]
-    fn the_countdown_display_epoch_steps_by_displayable_seconds() {
-        let mut items = Items::default();
-        assert_eq!(items.countdown_display_epoch(), 0, "no deadlines, no epoch");
+    fn countdown_steps_move_by_displayable_seconds() {
+        let now = Instant::now();
+        let mut c = Countdowns::default();
+        assert_eq!(c.steps(now), 0, "no deadlines, no steps");
 
-        items.set_enchant_deadline(0x42, 1, 90);
-        let epoch = items.countdown_display_epoch();
+        assert!(c.set_enchant(1, 90));
+        let steps = c.steps(Instant::now());
         assert!(
-            (90..=91).contains(&epoch),
-            "a 90 s deadline contributes floor(secs)+1, got {epoch}"
+            (90..=91).contains(&steps),
+            "a 90 s deadline contributes floor(secs)+1, got {steps}"
         );
-        let shown = items.enchant_remaining_display_ms(0x42, 1).unwrap();
+        let shown = c.enchant_remaining_display_ms(1).unwrap();
         assert_eq!(shown % 1000, 0, "the display read is second-floored");
         assert!(shown <= 90_000);
 
-        items.set_enchant_deadline(0x42, 1, 0);
-        assert_eq!(
-            items.countdown_display_epoch(),
-            0,
-            "cleared deadline, term gone"
+        // 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);
+        assert!(shown <= 1_800_000);
+        let steps = c.steps(Instant::now());
+        assert!(
+            (1890..=1892).contains(&steps),
+            "both cells step, got {steps}"
         );
-        assert_eq!(items.enchant_remaining_display_ms(0x42, 1), None);
+
+        assert!(c.set_enchant(1, 0));
+        c.set_lifetime(0);
+        assert_eq!(c.steps(Instant::now()), 0, "cleared cells, terms gone");
+        assert_eq!(c.enchant_remaining_display_ms(1), None);
+        assert_eq!(c.lifetime_remaining_ms(), None);
     }
 
-    /// The item-lifetime store (decision 1933) — the enchant timer's shape, one key narrower:
-    /// `seconds == 0` stores ABSENCE, the read is second-floored, the deadline joins the shared
-    /// display epoch, and destroying the item takes its timer with it.
+    /// 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 an_item_duration_parks_a_deadline_and_dies_with_the_item() {
-        let mut items = Items::default();
+    fn the_setters_clear_on_signed_non_positive_and_refuse_a_slot_past_the_array() {
+        let mut c = Countdowns::default();
+        c.set_lifetime(600);
+        assert!(c.lifetime_remaining_ms().is_some());
+        c.set_lifetime(0x8000_0000);
         assert_eq!(
-            items.duration_remaining_ms(0x42),
-            None,
-            "no timer by default"
-        );
-
-        items.insert_object(0x42, ObjectFields::default());
-        items.set_item_duration(0x42, 1800);
-        let shown = items.duration_remaining_display_ms(0x42).expect("parked");
-        assert_eq!(shown % 1000, 0, "the display read is second-floored");
-        assert!(shown <= 1_800_000);
-        let epoch = items.countdown_display_epoch();
-        assert!(
-            (1800..=1801).contains(&epoch),
-            "the lifetime deadline joins the same per-second epoch as the enchant one, got {epoch}"
-        );
-
-        // `0` is the wire's "no timer", never a zero-second timer — the same store the enchant
-        // path takes for the same reason (an expired countdown is an absent line).
-        items.set_item_duration(0x42, 0);
-        assert_eq!(items.duration_remaining_ms(0x42), None);
-        assert_eq!(items.countdown_display_epoch(), 0);
-
-        // A destroyed item takes its timer with it: the guid can be reissued by the server, and a
-        // stale deadline would print a countdown on whatever lands there next.
-        items.insert_object(0x99, ObjectFields::default());
-        items.set_item_duration(0x99, 600);
-        items.remove_object(0x99);
-        assert_eq!(items.duration_remaining_ms(0x99), None);
-
-        // **An item we do not hold is dropped outright** — no queue, no retry, and nothing
-        // parked. `0x1EA`'s arm resolves the guid and returns on a miss; its enchant sibling
-        // `0x1EB` is the one that enqueues and replays, and copying that here would grow the map
-        // without bound for guids that never arrive.
-        items.set_item_duration(0xdead, 600);
-        assert_eq!(items.duration_remaining_ms(0xdead), None);
-        assert_eq!(items.countdown_display_epoch(), 0);
-
-        // **A non-POSITIVE duration clears** — the reference's test is SIGNED (`0x5d9c0c jle`),
-        // so a wire value with the top bit set zeroes the cell instead of parking a 68-year
-        // deadline.
-        items.insert_object(0x7, ObjectFields::default());
-        items.set_item_duration(0x7, 600);
-        assert!(items.duration_remaining_ms(0x7).is_some());
-        items.set_item_duration(0x7, 0x8000_0000);
-        assert_eq!(
-            items.duration_remaining_ms(0x7),
+            c.lifetime_remaining_ms(),
             None,
             "a negative-as-signed duration clears, it does not park a far future"
         );
+
+        assert!(c.set_enchant(1, 600));
+        assert!(c.enchant_remaining_ms(1).is_some());
+        assert!(c.set_enchant(1, 0xffff_fff0));
+        assert_eq!(
+            c.enchant_remaining_ms(1),
+            None,
+            "the enchant setter's test is the same signed `jle`"
+        );
+
+        assert!(c.set_enchant(6, 30), "the seventh slot is the last cell");
+        let before = c.clone();
+        assert!(!c.set_enchant(7, 30), "the eighth is past the array");
+        assert!(!c.set_enchant(u32::MAX, 30));
+        assert_eq!(c, before, "a refused slot writes nothing");
+
+        assert_eq!(c.enchant_deadline_ms(0), None, "never set");
+        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
@@ -1011,28 +1072,104 @@ 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 objects_track_create_merge_destroy_and_session_clear() {
-        let mut items = Items::default();
-
-        items.insert_object(0x42, ObjectFields::default());
-        assert!(items.object(0x42).is_some());
-        assert!(items.merge_object(0x42, ObjectFields::default()));
+    fn an_item_is_an_object_in_the_index_and_its_changes_are_watched() {
+        use bevy::ecs::system::RunSystemOnce;
+        const GUID: u64 = 0x4000_0000_0000_0042;
+        let mut world = World::new();
+        world.init_resource::<GuidIndex>();
+        world
+            .run_system_once(|mut commands: Commands, mut index: ResMut<GuidIndex>| {
+                spawn_item(
+                    &mut commands,
+                    &mut index,
+                    GUID,
+                    ObjectFields::from_pairs(&[(3, 117), (14, 5)]),
+                    false,
+                );
+            })
+            .unwrap();
+        // A registered system keeps its change ticks between runs (a one-shot would read every
+        // store as new every time).
+        let read = world.register_system(
+            |objects: Objects, mut changes: ItemChanges| -> (Option<u32>, Option<u32>, bool) {
+                let o = objects.object(GUID);
+                (
+                    o.and_then(|o| o.object_entry()),
+                    o.and_then(|o| o.item_stack_count()),
+                    changes.moved(),
+                )
+            },
+        );
+        assert_eq!(
+            world.run_system(read).unwrap(),
+            (Some(117), Some(5), true),
+            "the spawn is a change"
+        );
+        assert_eq!(
+            world.run_system(read).unwrap(),
+            (Some(117), Some(5), false),
+            "nothing moved since"
+        );
+        // A values delta lands in the store and moves the watch once.
+        let e = world.resource::<GuidIndex>().0[&GUID];
+        world
+            .get_mut::<ObjectStore>(e)
+            .unwrap()
+            .0
+            .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.
+        world
+            .get_mut::<Countdowns>(e)
+            .expect("every item carries its cells")
+            .set_enchant(1, 90);
         assert!(
-            !items.merge_object(0x99, ObjectFields::default()),
-            "a delta for an unseen guid is not tracked"
+            world.run_system(read).unwrap().2,
+            "a landing moves the watch"
+        );
+        let steps = world
+            .run_system_once(|c: ItemChanges| c.countdown_steps())
+            .unwrap();
+        assert!((90..=91).contains(&steps), "got {steps}");
+        // The destroy: the index drops the guid, the entity goes, the watch moves once more.
+        world.resource_mut::<GuidIndex>().0.remove(&GUID);
+        world.despawn(e);
+        assert_eq!(world.run_system(read).unwrap(), (None, None, true));
+        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();
+        items.queue_enchant_time(0x42, 1, 30);
+        items.queue_enchant_time(0x43, 1, 60);
+        items.queue_enchant_time(0x42, 1, 45);
+        assert_eq!(
+            items.take_enchant_times(0x42),
+            vec![(1, 30), (1, 45)],
+            "arrival order — the later record is applied last and wins"
+        );
+        assert!(
+            items.take_enchant_times(0x42).is_empty(),
+            "unlinked once replayed"
         );
 
-        items.remove_object(0x42);
-        assert!(items.object(0x42).is_none());
-
-        // A disconnect clears instances + in-flight asks, keeps templates.
+        // A disconnect drops the records for items that never arrived and the in-flight asks,
+        // and keeps the templates.
         let (cmds, rx) = commands();
-        items.insert_object(0x43, ObjectFields::default());
         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.object(0x43).is_none());
+        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.
         let _ = rx.try_recv();
@@ -1045,8 +1182,8 @@ 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 carve's sign rule — **`abs(id)` names the row,
-    /// the sign only travels** (wow-re §E3), which is why a negative id resolves at all.
+    /// 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.
     #[test]
     fn enchant_lines_join_named_ids_in_slot_order() {
         let cat = Enchants(benilla_formats::EnchantCatalog::from_rows(
diff --git a/crates/benilla-app/src/lib.rs b/crates/benilla-app/src/lib.rs
index 879bd541..a7f9ac23 100644
--- a/crates/benilla-app/src/lib.rs
+++ b/crates/benilla-app/src/lib.rs
@@ -3,8 +3,8 @@
 //! 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
-//! `$WOW_TILE_RADIUS` — their splat-blended ground (tiling `$WOW_TEX_TILES`), doodads/WMOs, water, and
-//! ground clutter — plus the avian colliders the character controller walks on. Lit by a time-of-day WoW
+//! 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.
 //!
@@ -57,9 +57,9 @@ mod char_select;
 mod chat_bubble;
 mod chr_classes;
 mod cinematic;
+mod combat_log;
 mod combat_text;
 mod console;
-mod cooldowns;
 mod crash;
 mod creature_anim;
 mod cursor;
@@ -128,7 +128,7 @@ mod smart_rect;
 mod sound;
 /// The two talent spell-modifier tables (`SMSG_SET_FLAT_/PCT_SPELL_MODIFIER`) and the read that
 /// puts them on a number.
-mod spell_mods;
+mod spell;
 /// The melee swing refusal's latch + 4 s repeat (`SMSG_ATTACKSWING_*`).
 mod swing_refusal;
 mod target;
diff --git a/crates/benilla-app/src/loading_screen.rs b/crates/benilla-app/src/loading_screen.rs
index b08d3d48..048191f5 100644
--- a/crates/benilla-app/src/loading_screen.rs
+++ b/crates/benilla-app/src/loading_screen.rs
@@ -13,7 +13,7 @@
 //!
 //! **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"; the wow-re round behind decision 1990 says
+//! 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) —
@@ -329,7 +329,7 @@ impl LoadingScreen {
     /// 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`, `re/net/opcode-handlers.tsv`), and *neither touches the screen*:
+    /// (`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
diff --git a/crates/benilla-app/src/loading_screen/input.rs b/crates/benilla-app/src/loading_screen/input.rs
index dd114b15..3863cf22 100644
--- a/crates/benilla-app/src/loading_screen/input.rs
+++ b/crates/benilla-app/src/loading_screen/input.rs
@@ -6,7 +6,7 @@
 //! ## The reference does this too, and it does it at the source
 //!
 //! This file was written on the assumption that the reference simply blocks inside its world load,
-//! so the question never arises there. The wow-re round behind decision 1990 says otherwise, and
+//! 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.**
 //!
diff --git a/crates/benilla-app/src/local_state.rs b/crates/benilla-app/src/local_state.rs
index e1b82c01..9b833cc5 100644
--- a/crates/benilla-app/src/local_state.rs
+++ b/crates/benilla-app/src/local_state.rs
@@ -26,7 +26,7 @@
 //! 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
-//!    worktree pool keep one predictable place. Gated for the same reason the install resolver's
+//!    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
@@ -80,11 +80,12 @@ pub(crate) fn home() -> Option<PathBuf> {
 /// 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 pool slot symlinks `WoW` to the same install — so there has
-/// always been exactly ONE settings folder no matter which of the eight slots built the binary.
-/// Resolving to `CARGO_MANIFEST_DIR` instead would give eight, and the director's keybinds, macros
-/// and camera pose would appear to reset whenever a session happened to claim a different slot.
-/// That is a silent, recurring surprise, and it is not what "one predictable place" meant.
+/// 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
@@ -252,7 +253,7 @@ pub(crate) fn layout_character_path(realm: &str, character: &str) -> Option<Path
 ///
 /// 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, the contract's hard rule), so ours lives here like every other thing we persist.
+/// 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.
 ///
@@ -286,7 +287,7 @@ pub(crate) fn shots_path() -> Option<PathBuf> {
 ///
 /// **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 the sibling RE repo on this machine, and a client that
+/// 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.
@@ -327,13 +328,22 @@ 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 outside
-/// `[A-Za-z0-9_]` becomes `_`, so a realm called `Hydraxian Waterlords` or one with a slash cannot
+/// 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.
 fn file_token(s: &str) -> String {
     let t: String = s
         .chars()
-        .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
+        .map(|c| if c.is_alphanumeric() { c } else { '_' })
         .collect();
     if t.is_empty() {
         "unknown".into()
@@ -346,13 +356,19 @@ fn file_token(s: &str) -> String {
 /// a crash mid-write leaves the old file intact, never a truncated one. The one write path for
 /// every resident of the folder.
 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.
+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)?;
     }
     let tmp = path.with_extension("tmp");
     {
         let mut f = std::fs::File::create(&tmp)?;
-        f.write_all(contents.as_bytes())?;
+        f.write_all(contents)?;
         f.sync_all()?;
     }
     std::fs::rename(&tmp, path)
@@ -394,6 +410,28 @@ 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.
+    #[test]
+    fn distinct_names_never_share_a_token() {
+        assert_ne!(file_token("Вася"), file_token("Петя"));
+        assert_ne!(file_token("Zoë"), file_token("Zoé"));
+        assert_eq!(file_token("Zoë"), "Zoë");
+        assert_eq!(file_token("Onehunter"), "Onehunter");
+        assert_eq!(file_token("Hydraxian Waterlords"), "Hydraxian_Waterlords");
+        assert_eq!(
+            file_token("a/b\\c:d"),
+            "a_b_c_d",
+            "separators never survive"
+        );
+        assert_eq!(
+            file_token("realm-name"),
+            "realm_name",
+            "the key's own `-` stays unforgeable"
+        );
+    }
+
     /// 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
@@ -519,7 +557,7 @@ mod tests {
     /// 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 the eight pool slots keep sharing a single settings folder — exactly as they did when it
+    /// 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.
@@ -549,7 +587,7 @@ mod tests {
             assert_ne!(
                 h,
                 here.join(STATE_DIR),
-                "a linked worktree must not get its own settings folder — the pool shares one"
+                "a linked worktree must not get its own settings folder — the worktrees share one"
             );
             assert!(
                 h.parent().unwrap().join(".git").is_dir(),
diff --git a/crates/benilla-app/src/login/mod.rs b/crates/benilla-app/src/login/mod.rs
index 234f5019..640d6d8d 100644
--- a/crates/benilla-app/src/login/mod.rs
+++ b/crates/benilla-app/src/login/mod.rs
@@ -4,7 +4,7 @@
 //! Cinematics/TOS side of the reference screen is deliberately cut (the director's call).
 //!
 //! This module owns the **credential policy** — the 0193 §3 mirror for the IO thread's pre-logon
-//! park: the env fast path (any of `WOW_USER`/`WOW_PASS`/`WOW_CHAR` explicitly set auto-submits
+//! park: the env fast path (`WOW_USER` and `WOW_PASS` both set auto-submits
 //! with the old `one`/`pone` defaults, 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
@@ -268,8 +268,8 @@ fn fail_text(
 
 /// **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, decompiled in wow-re
-/// `system/net/scratch/w2b-pack.c` — each case loads exactly the `GlueStrings` key named below,
+/// 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.
 ///
@@ -371,13 +371,12 @@ fn without_dead_url(text: &str) -> std::borrow::Cow<'_, str> {
 /// password showed the terse `AUTH_UNKNOWN_ACCOUNT` ("Unknown account") — a real reference string,
 /// in the wrong slot.
 ///
-/// VERIFIED (wow-re `system/glue/scratch/login-failure-dialogs.md`, §5 cross-checked): 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`.
+/// 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:
 ///
@@ -470,7 +469,7 @@ fn drive_policy(
     // 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
-    // leg.sh keys on (decision 1371).
+    // 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
@@ -479,20 +478,20 @@ fn drive_policy(
     let empty = GlueStrings::default();
     let strings = strings.as_deref().unwrap_or(&empty);
 
-    // The env fast path, once (decision 0539 §3): any of WOW_USER/WOW_PASS/WOW_CHAR explicitly
-    // set → auto-submit env-with-defaults, so every probe/smoke/harness invocation keeps working.
+    // 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.
     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_else(|_| "one".into());
-            let pass = std::env::var("WOW_PASS").unwrap_or_else(|_| "pone".into());
+            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 from a pool slot must not authenticate as the director's `one`
-            // or a neighbouring slot's probe. Only the *automated* path is gated — a typed login
-            // is the director's own and is never second-guessed.
+            // 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.
             match crate::run_mode::account_guard(&user) {
                 Ok(()) => {
                     info!("login: env fast path — auto-submitting as {user}");
@@ -726,15 +725,14 @@ impl LoginForm {
     /// Give `field` the keyboard **and select everything already in it** — dropping the selection
     /// on the box being left.
     ///
-    /// **A knowing divergence** (director's call, 2026-08-28), and the reference half of it is now
-    /// byte-settled rather than inferred (wow-re `editbox-selection-focus-law.md` §4/§5, §5-VERIFIED,
-    /// dispatched from this work). 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).
+    /// **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
@@ -832,18 +830,18 @@ fn login_input(
     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
-    // (wow-re `ui.md`) — 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).
+    // 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 (wow-re `ui.md`) — 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.
+        // 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.
         if interaction.is_changed() && *interaction == Interaction::Pressed {
             match action {
                 // A click takes the focus the same way TAB does — the solid caret, and the
@@ -1716,7 +1714,7 @@ mod tests {
     }
 
     /// The code→string map quotes the client's own strings for the vmangos-verified rows.
-    /// The realmd map, against the byte-verified table (wow-re `login-failure-dialogs.md`).
+    /// 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
@@ -1768,7 +1766,7 @@ mod tests {
         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 (`w2b-pack.c`), transcribed.
+        // Every world row is the client's own dispatch (`0x5aa960`), transcribed.
         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");
diff --git a/crates/benilla-app/src/login/queue.rs b/crates/benilla-app/src/login/queue.rs
index d3d67f92..812ef297 100644
--- a/crates/benilla-app/src/login/queue.rs
+++ b/crates/benilla-app/src/login/queue.rs
@@ -6,11 +6,11 @@
 //! 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 (VERIFIED, wow-re
-//! `system/glue/scratch/login-failure-dialogs.md` §Q3). 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.
+//! 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
diff --git a/crates/benilla-app/src/minimap/blips/dots.rs b/crates/benilla-app/src/minimap/blips/dots.rs
index b139a7ef..265b36b5 100644
--- a/crates/benilla-app/src/minimap/blips/dots.rs
+++ b/crates/benilla-app/src/minimap/blips/dots.rs
@@ -28,19 +28,18 @@ 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).
 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; wow-re §B2).
+/// passing the resource-tracking predicate (Find Herbs/Minerals; `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/…; wow-re §B2).
+/// creature-tracking predicate (Track Beasts/Humanoids/…; `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).
 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; wow-re
-/// `track-predicates.md`, the 0564 fold-back) — also the `<= 0` fallback of the shapeshift
-/// override.
+/// 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.
 const CREATURE_TYPE_HUMANOID: u32 = 7;
 
 /// `ObjectIcons.blp` cell for a DIALOG_STATUS — **status 7 only** (`cmp [obj+0xcb8],7` at
@@ -50,11 +49,10 @@ fn quest_dot_cell(status: u32) -> Option<[f32; 4]> {
 }
 
 /// The three preconditions `0x4eaa90` applies to a **UNIT or PLAYER** before either dot category
-/// is even chosen — byte-pinned in wow-re `questgiver-marker.md` §W15 Q2, 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.
+/// 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
@@ -105,7 +103,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 never reaches the `== 7` compare (§W14.9)
+            continue; // the GameObject leg (`0x4eab43`) never reaches the `== 7` compare
         }
         let Some(cell) = statuses.get(&npc).copied().and_then(quest_dot_cell) else {
             continue;
@@ -173,11 +171,10 @@ pub(in crate::minimap) struct SelfTracking {
     pub(in crate::minimap) stealthed: bool,
 }
 
-/// The creature-tracking predicate — byte-carved `0x5ed210` (wow-re `track-predicates.md`,
-/// 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
+/// 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).
 fn tracked_creature(
     tracking: SelfTracking,
@@ -196,7 +193,7 @@ 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` (byte-carved 3-way, the 0564
+/// 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
@@ -287,11 +284,11 @@ pub(in crate::minimap) fn emit_tracking_dots(
     // **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, wow-re `minimap-poi-questdot.md` via
-    // `questgiver-marker.md` §W14.9): 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, §W14.1).
+    // 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).
     if tracking.resources != 0 {
         if let Some(locks) = locks {
             for (guid, net, tf, _) in candidates.iter() {
@@ -313,7 +310,7 @@ pub(in crate::minimap) fn emit_tracking_dots(
             continue;
         }
         // The same three preconditions the quest dot passes — they are upstream of the branch
-        // that chooses between the two categories, so neither category outruns them (§W15 Q2b).
+        // that chooses between the two categories (`0x4eac31`), so neither category outruns them.
         if !unit_dot_eligible(store, self_guid) {
             continue;
         }
@@ -349,10 +346,10 @@ enum DotName {
     Known(String),
 }
 
-/// The party **dots** — the in-range half of `place_party_raid_blips`: 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 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).
 pub(in crate::minimap) fn emit_party_dots(
     ctx: &BlipCtx,
     group: &crate::ui_party::GroupState,
@@ -387,10 +384,10 @@ pub(in crate::minimap) fn emit_party_dots(
 mod tests {
     use super::*;
 
-    /// **The three preconditions upstream of BOTH dot categories** (decision 1906, wow-re
-    /// `questgiver-marker.md` §W15 Q2). 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 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.
@@ -541,7 +538,7 @@ mod tests {
             !tracked_creature(beasts, None, 0, false),
             "type not cached yet — no dot"
         );
-        // The always-show pair (the `0x5ed210` carve): Hunter's Mark forces the dot with no
+        // 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.
         assert!(tracked_creature(
diff --git a/crates/benilla-app/src/minimap/blips/mod.rs b/crates/benilla-app/src/minimap/blips/mod.rs
index 50f5ad61..0ec5af3d 100644
--- a/crates/benilla-app/src/minimap/blips/mod.rs
+++ b/crates/benilla-app/src/minimap/blips/mod.rs
@@ -1,9 +1,7 @@
-//! The minimap **blip layer** (decision 0203 phase 3; the byte law per the wow-re fold-back,
+//! The minimap **blip layer** (decision 0203 phase 3; the byte law per the fold-back,
 //! decision 0337): AreaPOI landmarks + quest dots + the hover tooltip.
 //!
-//! **Landmarks** — byte-verified end to end (`wow-5875-re` `system/ui/scratch/
-//! minimap-poi-questdot.md`, §5 four-pair cross-check; selection `0x6d9a90`, candidates
-//! `0x6d8e10`, draw `0x4ed148`/`0x4ee170`):
+//! **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
@@ -25,9 +23,8 @@
 //! LAST — above every arrow.
 //!
 //! **Tracking dots** (decisions 0560/0564) — the classifier's fall-through for objects NOT
-//! at quest status 7, **byte-carved end to end** (wow-re `minimap-poi-questdot.md` §B2 +
-//! `track-predicates.md`, the §5 trio): a GameObject passing `0x5ed2b0` draws the gold
-//! **cell 0** (Find Herbs/Minerals), a unit passing `0x5ed210` the red **cell 1**. The
+//! 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
@@ -36,7 +33,7 @@
 //! `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.
 //!
-//! **Sizes are byte-pinned** (wow-re §SIZE, the 0342 fold-back): every blip constant is
+//! **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
@@ -49,20 +46,20 @@
 //! 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`]).
 //!
-//! Remaining residue: one gate the landmark selection here does NOT implement, found by the 1516
-//! §5 and belonging to the DBC rows rather than the marker — a `WorldStateID` gate at `0x6d9b27`.
+//! 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 the 1525 §5, all recorded rather than built (each is a visible change to a
+//! 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 wow-re's two findings conflict**: `0x4ed7b7` has the
+//!   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 note
-//!   settles, and guessing would move a look on a coin flip. Needs its own scoped pin.
+//!   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
@@ -72,8 +69,8 @@
 //! 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 pending its
-//! scoped pin; the tooltip anchor beside the map is an eyeball (the engine handler `0x4eb0c0`
+//! 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).
 
 mod dots;
@@ -107,7 +104,7 @@ const FLAG_CANDIDATE: u32 = 0x1;
 /// tower class in 5875 data.
 const FLAG_IN_RANGE_ICON: u32 = 0x2;
 /// The frozen basis the client bakes every blip-size constant against: the CGMinimapFrame
-/// ctor (`0x4edbc0`, wow-re §SIZE) computes them ONCE from the stock 140-XML-unit widget —
+/// 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.
@@ -141,10 +138,9 @@ const ARROW_QUAD_PX: f32 = 38.4;
 /// `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)` (wow-re `modelframe-animation-clock.md`) — an
-/// `AnimationData.dbc` id chosen off the output record's `+0x48`, and `0x4ee170` arms the 5 party
-/// frames with `0xa5`. Both wow-re notes that carry those ids call the argument a "model id" and
-/// gloss it as four `.mdx` variants; it is a sequence id, and there is one model.
+/// → `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
@@ -159,9 +155,8 @@ const ARROW_QUAD_PX: f32 = 38.4;
 /// the real file.
 ///
 /// `AnimationData.dbc` names the four rows outright — 165 `GroupArrow`, 166 `Arrow`, 167
-/// `CorpseArrow`, 168 `GuideArrow` (1525's §5, which derived the whole table independently and
-/// agreed). Four arbitrary-looking ids landing on four names that describe their callers exactly is
-/// why this is settled rather than merely likely.
+/// `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
@@ -351,7 +346,7 @@ pub(super) struct LandmarkSelection<'a> {
 /// 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 — wow-re `gossip-poi-marker.md`).
+/// candidate `0x6d9cc2` spares).
 pub(super) fn select_landmarks<'a>(
     pois: impl Iterator<Item = &'a AreaPoi>,
     marker: Option<&'a AreaPoi>,
@@ -505,8 +500,8 @@ 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 `place_party_raid_blips`
-/// (`0x6dad10`, VERIFIED): `d = √(dx²+dy²)`; over `0.8·radius` the member rides the 0.8 rim,
+/// 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.
@@ -514,7 +509,7 @@ pub(crate) fn party_member_pos(
 /// **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 by 1525's §5.
+/// [`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
@@ -522,8 +517,7 @@ pub(crate) fn party_member_pos(
 /// `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 older wow-re note's "4 members + own corpse" is wrong the same way its "3
-/// static slots" account was. The corpse reaches the minimap **only** as static blip slot 2 on the
+/// 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
diff --git a/crates/benilla-app/src/minimap/composite.rs b/crates/benilla-app/src/minimap/composite.rs
index 616d8b8b..7a8640db 100644
--- a/crates/benilla-app/src/minimap/composite.rs
+++ b/crates/benilla-app/src/minimap/composite.rs
@@ -1,5 +1,5 @@
 //! The WMO-interior minimap's **offscreen composite** — the client's own compositing pipeline
-//! (decision 1466, from wow-re `system/minimap/scratch/wmo-interior-minimap-composite.md`).
+//! (decision 1466).
 //!
 //! 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
diff --git a/crates/benilla-app/src/minimap/interior.rs b/crates/benilla-app/src/minimap/interior.rs
index 9e5205fc..90240a06 100644
--- a/crates/benilla-app/src/minimap/interior.rs
+++ b/crates/benilla-app/src/minimap/interior.rs
@@ -8,13 +8,14 @@ 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 and `& 0x88` at the emit level (wow-re Sub-Q4b).
+/// client skips `& 0x8` at the flood level (`0x6a5020`) and `& 0x88` at the emit level
+/// (`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 (verified: `wow-5875-re` minimap node, name builder `0x6da330`), e.g.
+/// 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`.
@@ -25,10 +26,10 @@ pub(super) fn wmo_minimap_stem(wmo_path: &str) -> Option<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 byte-verified client mechanism (wow-re minimap node
-/// `wmo-interior-minimap.md` Sub-Q4b). 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.
+/// 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.
 ///
 /// 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
@@ -36,12 +37,12 @@ pub(super) fn wmo_minimap_stem(wmo_path: &str) -> Option<String> {
 /// 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** (wow-re Q3, VERIFIED): 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.
+/// 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.
 pub(super) fn interior_group_selection(
     model: &WmoModel,
     world_from_local: &Affine3A,
@@ -107,10 +108,10 @@ pub(super) fn interior_group_selection(
             continue; // an outdoor shell group — not part of the interior flood
         }
         let (lo, hi) = world_aabb(gn.bbox_min, gn.bbox_max);
-        // XY-OVERLAP GATE (wow-re Q3, VERIFIED): 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).
+        // 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).
         if !xy_overlap(lo, hi) {
             continue;
         }
@@ -156,8 +157,9 @@ mod tests {
     ///   `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 wow-re Q3 correction (the XY gate blocks emit *and* recursion). `behind`'s
-    /// own bbox does overlap the box, so it would draw if recursion had leaked through `far`.
+    /// 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`.
     #[test]
     fn interior_flood_fill_gates_on_xy_and_blocks_recursion_through_a_missed_group() {
         use super::interior_group_selection;
@@ -188,8 +190,10 @@ mod tests {
         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 Q3 behaviour under test (a box-outside portal would pass this test
-                                                // even with the pre-correction emit-only gate, and so would prove nothing).
+                                                // — 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));
         let info = |start: u16| WmoPortalInfo {
             start_vertex: start,
@@ -259,7 +263,7 @@ mod tests {
         );
         assert!(
             !drawable[3],
-            "the XY gate that rejected g2 must also block flooding THROUGH it (wow-re Q3)"
+            "the XY gate that rejected g2 must also block flooding THROUGH it (`0x6a51f4`)"
         );
     }
 
diff --git a/crates/benilla-app/src/minimap/mod.rs b/crates/benilla-app/src/minimap/mod.rs
index 989e04a0..55a82c94 100644
--- a/crates/benilla-app/src/minimap/mod.rs
+++ b/crates/benilla-app/src/minimap/mod.rs
@@ -8,12 +8,12 @@
 //! the widget (border art, buttons, zone text — `MinimapCluster.xml`) draw above per the normal
 //! z order.
 //!
-//! Mechanism per wow-re's T3 minimap node (byte-verified there, transcribed here):
+//! 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** (`zoom_to_scale` 0x6da9b0): the client keeps **two** zoom indices,
+//! - **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
@@ -64,8 +64,8 @@ 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 (wow-re minimap node, `0x8116d0`): view **diameter** in chunks per
-/// zoom index; half-extent = `chunks · 0.5 · 33.333` yd (`zoom_to_scale` 0x6da9b0's unlocked leg).
+/// 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.
 const ZOOM_CHUNKS: [f32; 6] = [14.0, 12.0, 10.0, 8.0, 6.0, 4.0];
 
@@ -75,15 +75,15 @@ const ZOOM_CHUNKS: [f32; 6] = [14.0, 12.0, 10.0, 8.0, 6.0, 4.0];
 /// 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).
 ///
-/// On-screen radius is exactly this value (wow-re `wmo-interior-minimap.md` finding 2 **Q7
-/// CORRECTION**, VERIFIED: the client composites the interior to an offscreen target at `1.5·c` and
-/// blits its middle two-thirds, netting `1.0·c`). The **same `c`** sizes the tile-selection query box
-/// (Sub-Q4b), so selection and draw stay coherent.
+/// 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 an earlier reading of this same node claimed the interior scale was a compile-time constant
-/// (`10.0f` ⇒ a fixed 15 yd, zoom-independent). That was WRONG — it measured the *static
-/// initializer*, missing the per-frame write `mov [esi+0xc], radiusTable[indoorZoom]` that reaches
-/// the field through a computed pointer. Superseded in wow-re; do not "restore" a constant here.
+/// 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.
 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
@@ -105,8 +105,7 @@ fn view_radius_yd(zoom: u8, inside_zoom: u8, inside: bool) -> f32 {
 /// 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 — wow-re
-/// `system/minimap/scratch/wmo-interior-no-adt-underlay.md` §8.
+/// to the reference's captured quads with zero error.
 const EDGE_BLEED_YD: f32 = 1.0;
 
 /// The client's half-texel UV inset, as the quad scale that reproduces it: a tile spanning
@@ -126,7 +125,7 @@ fn texel_stretch(extent_yd: f32) -> f32 {
 /// `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` (wow-re `system/minimap/scratch/wmo-interior-minimap-composite.md`, VERIFIED).
+/// 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.
 pub(crate) const INTERIOR_TILE_ALPHA_REF: f32 = f32::from_bits(0x3F60_E0E2);
@@ -137,7 +136,7 @@ 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 (`wow-5875-re` minimap node, tile draw `0x4eccdd`–`0x4ecd69`): from the two global
+/// 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]`):
 ///
@@ -222,8 +221,8 @@ pub(crate) struct MinimapWidget(pub(crate) Option<MinimapSlot>);
 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 (wow-re,
-/// VERIFIED at the `RegisterCVar 0x63db90` argument slot). The *live* indices are the widget's
+/// `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
@@ -374,8 +373,7 @@ fn setup_minimap(
 /// 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` — wow-re `wmo-interior-minimap-composite.md`, which
-/// CORRECTED the old note's "containment resolves to a group with `0x10` set": that `0x10` is a
+/// 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
@@ -513,7 +511,7 @@ fn emit_minimap(
         // 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 (`wow-5875-re` minimap node Sub-Q6). Cached by `(group, col, row)`.
+        // world AABBs (one orientation basis, `0x6da180`). Cached by `(group, col, row)`.
         if cache.interior_stem.as_deref() != Some(stem.as_str()) {
             cache.interior.clear();
             cache.interior_stem = Some(stem.clone());
@@ -521,7 +519,7 @@ fn emit_minimap(
         // 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 (wow-re finding 2 Q7 CORRECTION).
+        // 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;
@@ -548,17 +546,17 @@ fn emit_minimap(
         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 (wow-re
-        // `wmo-interior-minimap.md` Sub-Q4b, byte-verified) — NOT draw-every-group. Only the groups
+        // 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 (Sub-Q4b) — 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 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.
         let drawable =
             interior_group_selection(model, &world_from_local, player.pos, radius, in_group);
-        // Draw ORDER (wow-re finding 2 Q2, VERIFIED): the composite is Z-sorted ascending by
+        // 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
@@ -587,10 +585,9 @@ fn emit_minimap(
                     // 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`; wow-re `wmo-interior-no-adt-underlay.md` §8, 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`.
+                    // `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
@@ -652,7 +649,7 @@ 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-re `wmo-interior-no-adt-underlay.md`).
+        // this is here to be compared against.
         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!(
@@ -745,7 +742,7 @@ fn emit_minimap(
     // Our own descriptor's tracking state (PRIVATE fields — only ever 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 (§W15 Q2d).
+    // own pet and minions never take a dot (`0x4eac0d`).
     let self_guid = me.map(|(_, g)| g.0);
     let tracking = me
         .map(|(s, _)| blips::SelfTracking {
@@ -816,8 +813,8 @@ fn emit_minimap(
                 &mut quads,
                 &mut hover,
             );
-            // The party/corpse rim arrows (0434 phase 6b, `place_party_raid_blips`' out-of-range
-            // half) draw with the POI arrows — before the player arrow, per the client's order.
+            // 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.
             let corpse = death_net
                 .corpse
                 .filter(|cp| cp.display_map == map.0 as i32)
@@ -900,7 +897,7 @@ fn emit_minimap(
     // 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 `place_party_raid_blips` slot — the rotating
+    // 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).
@@ -1075,6 +1072,7 @@ pub(crate) struct MinimapPlugin;
 
 impl Plugin for MinimapPlugin {
     fn build(&self, app: &mut App) {
+        ping::register(app);
         app.add_observer(on_cvar);
         app.init_resource::<MinimapWidget>()
             .init_resource::<MinimapZoom>()
diff --git a/crates/benilla-app/src/minimap/ping.rs b/crates/benilla-app/src/minimap/ping.rs
index 50a71981..6e63b7ed 100644
--- a/crates/benilla-app/src/minimap/ping.rs
+++ b/crates/benilla-app/src/minimap/ping.rs
@@ -26,13 +26,13 @@
 //!   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 byte-verified relay `0x4ee330` hands Lua (`(−dy·k, dx·k)`, `k = 1/(2·radius)` —
-//!   wow-re `party-group-wire.md` §TU-D). `Minimap:GetPingPosition()` reads the live value back.
+//!   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** (wow-re `minimap-ping-law.md` §3 — six instructions touch those cells
+//! **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)`
@@ -47,8 +47,8 @@
 //!
 //! 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 (wow-re `party-group-wire.md` §TU-D
-//! corrects it explicitly). Walking to your own ping used to delete it mid-hold.
+//! marker** — a different feature in a different slot (`0x6d99aa`–`0x6d9a4c`). Walking to your
+//! own ping used to delete it mid-hold.
 
 use bevy::prelude::*;
 
@@ -207,6 +207,26 @@ pub(super) fn drive_minimap_ping(
     );
 }
 
+/// Register the ping's packet handler — called from [`super::MinimapPlugin`] (in the net handler
+/// table since 2313).
+pub(super) fn register(app: &mut App) {
+    use crate::net::NetHandlerApp;
+    app.net_handler(
+        benilla_protocol::SessionEventKind::MinimapPing,
+        on_minimap_ping,
+    );
+}
+
+/// 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.
+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);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -303,10 +323,10 @@ 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; wow-re `party-group-wire.md` §TU-D shows that
-    /// clear belongs to the `SMSG_GOSSIP_POI` marker, and that `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.
+    /// `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.
     #[test]
     fn reaching_the_ping_does_not_clear_it() {
         let mut c = ctx();
diff --git a/crates/benilla-app/src/name_persist.rs b/crates/benilla-app/src/name_persist.rs
index 8f395f90..4718eeb5 100644
--- a/crates/benilla-app/src/name_persist.rs
+++ b/crates/benilla-app/src/name_persist.rs
@@ -9,20 +9,19 @@
 //! **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
-//! carve 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`]).
+//! 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`]).
 //!
 //! 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 carve
+//! ## The law, from the reference
 //!
-//! wow-re carved the whole `DBCache.cpp` machine (`system/dbcache/dbcache.md`, T3 — all 12 record
-//! decoders diffed bit-exact). Two of its contracts are the ones a re-implementation must honour,
-//! and both are about what the cache does *not* do:
+//! 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
@@ -34,7 +33,7 @@
 //! ## Where it lives, and the one place we deviate
 //!
 //! The reference writes `WDB/` **inside the install**, which is precisely where benilla may not
-//! write (the contract's read-only rule). Ours goes to `benilla-config/cache/<realm>.tsv` through
+//! 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
@@ -263,7 +262,7 @@ mod tests {
         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::apply::session::connected` does a moment after the pick goes out.
+        // `net::session::connected` does a moment after the pick goes out.
         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 30227b49..49d43d91 100644
--- a/crates/benilla-app/src/nameplates.rs
+++ b/crates/benilla-app/src/nameplates.rs
@@ -1,6 +1,5 @@
-//! **Overhead unit names** — the 1.12.1 overhead-name system, three §5 verdicts deep (wow-re
-//! `object-layer/scratch/overhead-name.md` + `playername/scratch/name-render-geometry-law.md`,
-//! incl. the `ee2ea7af` color/occlusion corrections the director's reference A/B forced):
+//! **Overhead unit names** — the 1.12.1 overhead-name system, incl. the color/occlusion corrections
+//! the director's reference A/B forced:
 //!
 //! - **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
@@ -27,10 +26,10 @@
 //! - **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, §5-verified after the director's "names too low"
+//! - **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` (`string_layout_lines 0x5cdc20` rotated branch: line 0
+//!   `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
@@ -41,20 +40,20 @@
 //!   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*, pinned by the
-//!   combat-flash RE; 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 a flagged pin); players → `UnitNamePlayer` (default ON); NPCs → `UnitNameNPC`
+//!   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`];
-//!   byte-verified, wow-re Q4a). The trio is unique to the overhead name binary-wide
+//!   `<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).
 //!
 //!   **The guild line is a5 and the subname line is a6, and the two can never both appear** —
-//!   wow-re Q4's *branch exclusivity*, VERIFIED: the player branch emits a1–3 · a4 · a5 · a8 and
+//!   *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
@@ -93,8 +92,7 @@ const SCALE_RATE: f32 = 1.5; // [0x8112ac]
 /// these gates (the Options window's Nameplates page, through the 0954 store — the arms live in
 /// [`crate::cvars`]).
 ///
-/// **The defaults are the reference's, byte-verified** (wow-re
-/// `object-layer/scratch/overhead-name.md`, the `0x6c7470` registrar: `UnitNamePlayer` `"1"`,
+/// **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
@@ -123,7 +121,7 @@ impl Default for NameConfig {
 }
 
 /// The player name-line flag decorations — the a1–a3 prefix slots of the line-stack law
-/// (`0x608f50`), byte-VERIFIED (wow-re `overhead-name.md` Q4a, commit `4a75d9be`): the CGPlayer
+/// (`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
@@ -183,7 +181,7 @@ fn lines_current(
 }
 
 /// The name's world scale for a unit whose overhead anchor sits `d` world units above its feet.
-/// Shared with the raid-target marker ([`crate::raid_marks`]) — §6 of the same geometry law.
+/// Shared with the raid-target marker ([`crate::raid_marks`]), which it raises (`0x6c70d8`).
 pub(crate) fn height_scale(d: f32) -> f32 {
     if d > SCALE_KNEE {
         (d / SCALE_KNEE) * SCALE_RATE * SCALE_FLOOR
@@ -251,14 +249,14 @@ pub(crate) struct Nameplates {
 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 (wow-re `questgiver-marker.md` Q4: `0x6076c0` checks `0x6c7950`).
+    /// (anim 190) bob off this (`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 (§6: the marker sits one pitch above the block when the name
-    /// shows, at the bare anchor otherwise).
+    /// marker's seat law reads it (`0x6c70d8`: the marker sits one pitch above the block when the
+    /// name shows, at the bare anchor otherwise).
     pub(crate) fn line_count(&self, unit: Entity) -> Option<usize> {
         self.live.get(&unit).map(|(_, lines, _)| lines.len())
     }
@@ -287,7 +285,7 @@ const ROCK_SNAP: f32 = 1.0;
 /// 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`, size `0.99f` with string flag `0x80` — wow-re `system/font`, so its
+/// 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`].
 const BAKE_PX: f32 = 36.0;
@@ -296,7 +294,7 @@ const BAKE_PX: f32 = 36.0;
 /// 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 §5 world-mode seat; the old
+/// `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
@@ -505,8 +503,8 @@ pub(crate) fn drive_nameplates(
         // 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 (wow-re `overhead-name.md` §Q5 + `playername.md`,
-        // both VERIFIED). A far name just gets small: it is a world billboard, apparent size ∝
+        // 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
@@ -514,19 +512,18 @@ pub(crate) fn drive_nameplates(
         // 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, wow-re `nameplate-vkey.md`),
-        // and neither does one carrying a live chat bubble (`+0xe64` — the same gate's other
-        // handle read, wow-re `chat-bubble.md` §0).
+        // 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 on the pin list — flagged interim.
+        // the exact ShouldShowName leg is unconfirmed in the binary — flagged interim.
         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 (byte-VERIFIED, wow-re
-            // ghost-death-visuals.md): overhead-name/plate suppression — the create-gate and the
-            // per-tick gate 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 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.
             false
         } else if is_self {
             // The own-unit cvar leg, before the rescue (faithful order: self-targeting still
@@ -556,10 +553,10 @@ pub(crate) fn drive_nameplates(
         // 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).
-        if names.resolve(guid.0, &net_commands).is_none() {
+        if names.resolve_unit(guid.0, store, &net_commands).is_none() {
             continue;
         }
-        let Some(name) = names.peek(guid.0) else {
+        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.
@@ -568,8 +565,7 @@ pub(crate) fn drive_nameplates(
         } else {
             0
         };
-        // **The own-player AFK override** (2088; wow-re `afk-dnd-command-law.md` §8, which settled
-        // what `overhead-name.md` had only INFERRED). The AFK slot `0x5ec9e0` — and only that slot
+        // **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`).
@@ -586,7 +582,7 @@ pub(crate) fn drive_nameplates(
         };
         // 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, wow-re Q4, VERIFIED). a5 is the only one of the two that a CVar
+        // branch exclusivity). a5 is the only one of the two that a CVar
         // gates: mask bit `0x10` at `0x609085`.
         let bracketed = match net.kind {
             EntityKind::Unit => benilla_protocol::guid::entry(guid.0)
@@ -908,7 +904,7 @@ mod tests {
         assert!(height_scale(4.1) > 0.2, "past the knee: the jump is real");
     }
 
-    /// The flag decorations against the byte-verified slot law (wow-re Q4a): bare concatenation
+    /// 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.
     #[test]
diff --git a/crates/benilla-app/src/names.rs b/crates/benilla-app/src/names.rs
index 84e9ed3d..2dfc3464 100644
--- a/crates/benilla-app/src/names.rs
+++ b/crates/benilla-app/src/names.rs
@@ -1,11 +1,13 @@
 //! Unit-name resolution — the query-cache seam of decision 0068 §3.
 //!
 //! 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*
-//! embedded in its guid, shared by every spawn of that template — exactly how the real client
-//! recovers it). This module owns the cache and the **ask-once** discipline: a consumer calls
-//! [`NameCache::resolve`], 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
+//! (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).
 //!
@@ -50,15 +52,15 @@ use crate::query_cache::QueryCache;
 /// | `0x40` | `0x60d840` | SPELL_ATTACKABLE / no harmful vertex colouring |
 /// | `0x80` | `0x613230` = `CanInteractWhileDead` | INTERACT_WHILE_DEAD |
 ///
-/// (wow-re `object-layer/scratch/melee-blood-spurt-suppression.md` §6, bit numbering VERIFIED at
-/// each reader; the names corroborated by vmangos `CreatureDefines.h:146-152`.)
+/// (bit numbering per the readers above; the names corroborated by 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
-    /// (wow-re §8 Q1: "no blood-, creature-type- or display-record-keyed mechanism exists" —
-    /// a skeleton bleeds), and so is the floating combat text. Decision 2068.
+    /// (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.
     pub(crate) const DO_NOT_PLAY_WOUND_ANIM: u32 = 0x8;
 
     /// `0x10` — **NO_FACTION_TOOLTIP**: the unit tooltip drops its faction-name line
@@ -66,8 +68,7 @@ pub(crate) mod type_flags {
     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 — wow-re
-    /// `outdoor-object-pass-election.md` §4, decision 1482).
+    /// tick-only so its combat stays audible (`0x607da0`'s `0x623b70` arm, decision 1482).
     pub(crate) const MORE_AUDIBLE: u32 = 0x20;
 }
 
@@ -82,7 +83,7 @@ pub(crate) struct NameCache {
     /// 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 (`questtext-macro-expander.md` §1), so without them `$R`/`$C`/`$G` against an
+    /// 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
@@ -171,29 +172,96 @@ pub(crate) fn gated_rank(rec: Option<&CreatureRecord>, store: Option<&ObjectStor
     }
 }
 
-impl NameCache {
-    /// The name for `guid`, if known. On a miss, sends the right query (once per guid/entry 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.
-    pub(crate) fn resolve(&self, guid_val: u64, commands: &NetCommands) -> Option<&str> {
+/// 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.
+#[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.
+    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`).
+    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.
+    fn of(guid_val: u64, unit: Option<&ObjectStore>) -> Option<Self> {
         if guid::is_player(guid_val) {
-            self.players
+            return Some(Self::Player(guid_val));
+        }
+        if !guid::is_creature_or_pet(guid_val) {
+            return None;
+        }
+        match unit {
+            Some(unit) => match unit.0.unit_pet_number() {
+                0 => unit
+                    .0
+                    .object_entry()
+                    .filter(|&e| e != 0)
+                    .or_else(|| guid::entry(guid_val))
+                    .map(Self::Creature),
+                n => Some(Self::Pet(n)),
+            },
+            None => guid::pet_number(guid_val)
+                .map(Self::Pet)
+                .or_else(|| guid::entry(guid_val).map(Self::Creature)),
+        }
+    }
+}
+
+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`]).
+    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.
+    pub(crate) fn resolve_unit(
+        &self,
+        guid_val: u64,
+        unit: Option<&ObjectStore>,
+        commands: &NetCommands,
+    ) -> Option<&str> {
+        match NameKey::of(guid_val, unit)? {
+            NameKey::Player(guid_val) => self
+                .players
                 .get_or_ask(guid_val, || {
                     debug!("names: asking player name (guid {guid_val})");
                     let _ = commands.0.send(ClientCommand::NameQuery { guid: guid_val });
                 })
-                .map(String::as_str)
-        } else if let Some(pet_number) = guid::pet_number(guid_val) {
-            // A pet is a `TYPEID_UNIT` like any creature, but it carries a pet number where a
-            // creature carries its template entry, so it has its own query. Asking the creature
-            // query for that number is what left every summoned pet nameless.
-            self.resolve_pet(pet_number, guid_val, commands)
-        } else if guid::is_creature_or_pet(guid_val) {
-            let entry = guid::entry(guid_val)?;
-            self.resolve_creature(entry, guid_val, commands)
-        } else {
-            None
+                .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),
         }
     }
 
@@ -237,18 +305,19 @@ impl NameCache {
     }
 
     /// 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).
+    /// [`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.
     pub(crate) fn peek(&self, guid_val: u64) -> Option<&str> {
-        if guid::is_player(guid_val) {
-            self.players.get(guid_val).map(String::as_str)
-        } else if let Some(pet_number) = guid::pet_number(guid_val) {
-            self.pets.get(pet_number).map(String::as_str)
-        } else if guid::is_creature_or_pet(guid_val) {
-            self.creatures
-                .get(guid::entry(guid_val)?)
-                .map(|r| r.name.as_str())
-        } else {
-            None
+        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.
+    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),
+            NameKey::Pet(pet_number) => self.pets.get(pet_number).map(String::as_str),
+            NameKey::Creature(entry) => self.creatures.get(entry).map(|r| r.name.as_str()),
         }
     }
 
@@ -309,7 +378,7 @@ impl NameCache {
     /// 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::apply::session::connected`) lands in the same neighbourhood, and whichever arrives
+    /// `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
@@ -422,10 +491,10 @@ impl crate::query_cache::AskOnce for NameCache {
 /// 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** (wow-re `system/dbcache/dbcache.md`, Contracts). 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.
+/// 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.
 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
@@ -537,8 +606,7 @@ impl NameCache {
     }
 
     /// Drop a player's cached name (`SMSG_INVALIDATE_PLAYER`) so the next resolve re-asks — the
-    /// reference's remove-by-key (`0x556ff0`, wow-re `dbcache.md` Contracts: eviction is
-    /// **explicit only**, there is no TTL).
+    /// 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
@@ -556,6 +624,144 @@ impl NameCache {
     }
 }
 
+/// 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.
+pub(crate) mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::{CreatureRecord, NameCache};
+    use crate::net::NetHandlerApp;
+
+    /// Register the four handlers.
+    pub(crate) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::PlayerName, on_player_name)
+            .net_handler(K::PetName, on_pet_name)
+            .net_handler(K::CreatureName, on_creature_name)
+            .net_handler(K::InvalidatePlayer, on_invalidate_player);
+    }
+
+    fn on_player_name(In(ev): In<SessionEvent>, mut names: ResMut<NameCache>) {
+        if let SessionEvent::PlayerName {
+            guid,
+            name,
+            race,
+            class,
+            gender,
+        } = ev
+        {
+            player_name(guid, name, race, class, gender, &mut names);
+        }
+    }
+
+    fn on_pet_name(In(ev): In<SessionEvent>, mut names: ResMut<NameCache>) {
+        if let SessionEvent::PetName { pet_number, name } = ev {
+            pet_name(pet_number, name, &mut names);
+        }
+    }
+
+    fn on_creature_name(In(ev): In<SessionEvent>, mut names: ResMut<NameCache>) {
+        if let SessionEvent::CreatureName {
+            entry,
+            name,
+            subname,
+            creature_type,
+            pet_family,
+            rank,
+            type_flags,
+            display_id,
+            civilian,
+            racial_leader,
+        } = ev
+        {
+            creature_name(
+                entry,
+                name,
+                subname,
+                creature_type,
+                pet_family,
+                rank,
+                type_flags,
+                civilian,
+                racial_leader,
+                display_id,
+                &mut names,
+            );
+        }
+    }
+
+    fn on_invalidate_player(In(ev): In<SessionEvent>, mut names: ResMut<NameCache>) {
+        if let SessionEvent::InvalidatePlayer { guid } = ev {
+            invalidate_player(guid, &mut names);
+        }
+    }
+
+    /// `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`]).
+    fn player_name(
+        guid: u64,
+        name: String,
+        race: u32,
+        class: u32,
+        gender: u32,
+        names: &mut NameCache,
+    ) {
+        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.
+    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.
+    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.
+    fn creature_name(
+        entry: u32,
+        name: Option<String>,
+        subname: Option<String>,
+        creature_type: Option<u32>,
+        pet_family: u32,
+        rank: u32,
+        type_flags: u32,
+        civilian: bool,
+        racial_leader: bool,
+        display_id: u32,
+        names: &mut NameCache,
+    ) {
+        names.insert_creature(
+            entry,
+            name.map(|n| CreatureRecord {
+                name: n,
+                subname,
+                creature_type: creature_type.unwrap_or(0),
+                pet_family,
+                rank,
+                type_flags,
+                civilian,
+                racial_leader,
+                display_id,
+            }),
+        );
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -962,4 +1168,108 @@ mod tests {
             Ok(ClientCommand::CreatureQuery { entry: 100, .. })
         ));
     }
+
+    /// `OBJECT_FIELD_ENTRY` and `UNIT_FIELD_PETNUMBER`, absolute descriptor indices.
+    const ENTRY: u16 = 3;
+    const PETNUMBER: u16 = 139;
+
+    fn unit(fields: &[(u16, u32)]) -> ObjectStore {
+        ObjectStore(benilla_protocol::ObjectFields::from_pairs(fields))
+    }
+
+    fn record(name: &str) -> CreatureRecord {
+        CreatureRecord {
+            name: name.into(),
+            subname: None,
+            creature_type: 0,
+            pet_family: 0,
+            rank: 0,
+            type_flags: 0,
+            civilian: false,
+            racial_leader: false,
+            display_id: 0,
+        }
+    }
+
+    /// **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`.
+    #[test]
+    fn a_companion_pet_is_named_by_its_descriptor_entry() {
+        let (cmds, rx) = commands();
+        let mut cache = NameCache::default();
+        let squirrel = compose(guid::HIGH_PET, 5_021, 3);
+        let store = unit(&[(ENTRY, 2_671), (PETNUMBER, 0)]);
+        cache.insert_creature(2_671, Some(record("Mechanical Squirrel")));
+
+        assert_eq!(
+            cache.resolve_unit(squirrel, Some(&store), &cmds),
+            Some("Mechanical Squirrel")
+        );
+        assert_eq!(
+            cache.peek_unit(squirrel, Some(&store)),
+            Some("Mechanical Squirrel")
+        );
+        assert!(
+            matches!(rx.try_recv(), Err(TryRecvError::Empty)),
+            "no pet-name query for a unit whose PETNUMBER is 0"
+        );
+    }
+
+    /// 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();
+        let cache = NameCache::default();
+        let squirrel = compose(guid::HIGH_PET, 5_021, 3);
+        let store = unit(&[(ENTRY, 2_671)]);
+
+        assert_eq!(cache.resolve_unit(squirrel, Some(&store), &cmds), None);
+        assert!(matches!(
+            rx.try_recv(),
+            Ok(ClientCommand::CreatureQuery { entry: 2_671, guid }) if guid == squirrel
+        ));
+        assert_eq!(cache.resolve_unit(squirrel, Some(&store), &cmds), None);
+        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();
+        let mut cache = NameCache::default();
+        let rex = compose(guid::HIGH_PET, 7, 42);
+        let store = unit(&[(ENTRY, 3_122), (PETNUMBER, 7)]);
+        cache.insert_creature(3_122, Some(record("Bloodtalon Taillasher")));
+
+        assert_eq!(cache.resolve_unit(rex, Some(&store), &cmds), None);
+        assert!(matches!(
+            rx.try_recv(),
+            Ok(ClientCommand::PetNameQuery { pet_number: 7, guid }) if guid == rex
+        ));
+        cache.insert_pet(7, "Rex".into());
+        assert_eq!(cache.resolve_unit(rex, Some(&store), &cmds), Some("Rex"));
+        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.
+    #[test]
+    fn a_charmed_creature_is_named_by_its_pet_number() {
+        let (cmds, rx) = commands();
+        let cache = NameCache::default();
+        let ogre = compose(guid::HIGH_UNIT, 1_000, 9);
+        let store = unit(&[(ENTRY, 1_000), (PETNUMBER, 55)]);
+
+        assert_eq!(cache.resolve_unit(ogre, Some(&store), &cmds), None);
+        assert!(matches!(
+            rx.try_recv(),
+            Ok(ClientCommand::PetNameQuery { pet_number: 55, .. })
+        ));
+    }
 }
diff --git a/crates/benilla-app/src/net.rs b/crates/benilla-app/src/net.rs
index b4b8b961..9e270a82 100644
--- a/crates/benilla-app/src/net.rs
+++ b/crates/benilla-app/src/net.rs
@@ -21,6 +21,7 @@ use benilla_protocol::{
     messages::WhoRequest, EntityKind, JumpInfo, MoveMode, MoveSpeeds, ObjectFields, SessionEvent,
     SpeedKind, TransportPose,
 };
+use bevy::ecs::system::SystemParam;
 use bevy::prelude::*;
 use crossbeam_channel::{Receiver, Sender};
 
@@ -30,6 +31,10 @@ mod apply;
 pub(crate) mod handlers;
 pub(crate) mod io;
 mod motion;
+mod objects;
+pub(crate) use objects::tear_down;
+mod session;
+mod world;
 
 pub(crate) use apply::apply_net_updates;
 use apply::tag_self_player;
@@ -95,6 +100,12 @@ impl Plugin for NetPlugin {
             Update,
             publish_world_time.in_set(benilla_world::schedule::WorldStage::Net),
         );
+        // The bridge's own handlers (decision 2325): the world feed it forwards, the name cache it
+        // initialises.
+        world::register(app);
+        session::register(app);
+        objects::register(app);
+        crate::names::net::register(app);
         app.insert_resource(NetEvents(handles.events))
             .insert_resource(NetCommands(handles.commands))
             .insert_resource(CharPick(handles.pick))
@@ -225,7 +236,7 @@ pub(crate) struct NetEntity {
 
 /// A unit's movement speeds (yd/s), decoded from its `LIVING` movement block. The creature animation
 /// selector ([`crate::creature_anim`]) keys its walk-vs-run boundary on `walk` (run above 2× walk —
-/// RF-0057); [`extrapolate_remote_units`] integrates a remote mover between packets at `run` /
+/// `0x5fd224`); [`extrapolate_remote_units`] integrates a remote mover between packets at `run` /
 /// `run_back` / `swim` and turns it in place at `turn_rate`. Present only on units (GameObjects don't
 /// move under their own power).
 #[derive(Component, Clone, Copy)]
@@ -233,8 +244,7 @@ pub(crate) struct UnitSpeeds(pub(crate) MoveSpeeds);
 
 /// **`CMovement::GetCurrentSpeed 0x7c4c90`** — the one place a mover's move-flags become a
 /// yards/second, for our own body and for every remote one. It is a *cascade*, and its ORDER is
-/// the whole of it (VERIFIED bytes, wow-re `collision/scratch/airborne-steerability.md` §2.4 +
-/// `object-layer/scratch/swim-mechanism.md` TU-H):
+/// the whole of it:
 ///
 /// 1. `0x7c4c99 test dl,0xf` — **no direction bit at all → 0.0** (`[0x7ffd74]`), never a stale
 ///    speed. A standing mover is standing however its speed fields read.
@@ -254,13 +264,12 @@ pub(crate) struct UnitSpeeds(pub(crate) MoveSpeeds);
 /// **There is no zero-`walk` fallback here, and that is a settled question rather than an
 /// oversight** (decision 1759). The ctor does zero all six speed fields (`0x7c48e8`–`0x7c4906`),
 /// and 1752 guarded against a mover reaching this with `walk == 0` by falling back to the run arm.
-/// The wow-re §5 then reported that the local player's create skips the speed-block apply, so the
-/// zero was live after every world port — and then **retracted it**: the guard it found
-/// (`0x5ff070`) has two callers, and the post-create `0x5fad50` passes 0, so the block is applied
-/// for our own unit exactly as for a remote one (`0x5fad98 xor edi,edi`, unwritten to the push at
-/// `0x5fb131`). The self-skip belongs to the *redundant*-create path `0x466350`, reached only when
-/// the object-manager lookup HIT. The ctor's zero is a transient inside one call and is never
-/// observable, so this is the plain minimum the bytes are.
+/// The local player's create does **not** skip the speed-block apply, so the zero is not live
+/// after a world port: the guard `0x5ff070` has two callers, and the post-create `0x5fad50` passes
+/// 0, so the block is applied for our own unit exactly as for a remote one (`0x5fad98 xor edi,edi`,
+/// unwritten to the push at `0x5fb131`). The self-skip belongs to the *redundant*-create path
+/// `0x466350`, reached only when the object-manager lookup HIT. The ctor's zero is a transient
+/// inside one call and is never observable, so this is the plain minimum the bytes are.
 pub(crate) fn current_speed(s: &MoveSpeeds, flags: u32) -> f32 {
     use crate::creature_anim::move_flags as f;
     if flags & f::ANY_MOVE == 0 {
@@ -295,9 +304,9 @@ pub(crate) struct ObjectStore(pub(crate) ObjectFields);
 /// **One descriptor dword moved on a streamed object** — the reference's `CMirrorHandler` edge
 /// (decision 2297). The real client keeps a shadow copy of every object's field array, and the
 /// values-apply notifier (`0x465330`) memcmps live against shadow over each registered span and
-/// calls the watcher with the OLD value (`0x465570` hands the mirror pointer as `param3` —
-/// wow-re `object-layer.md`); a first CREATE passes a notify-suppress flag and fires nothing, an
-/// in-place re-create of a live guid goes down the values path and fires like any delta.
+/// calls the watcher with the OLD value (`0x465570` hands the mirror pointer as `param3`); a
+/// first CREATE passes a notify-suppress flag and fires nothing, an in-place re-create of a live
+/// guid goes down the values path and fires like any delta.
 ///
 /// benilla emits the same edge once, from the drain's merge, which is the one place that holds
 /// both sides: every consumer that used to poll `Changed<ObjectStore>` and re-derive "did THIS
@@ -420,8 +429,7 @@ pub(crate) struct SelfPlayer;
 /// **The body this client is attached to** — where the camera is, whose feet make the footsteps,
 /// whose height the water lines are measured against, whose server-authored spline is ours to ride.
 /// The reference's **camera anchor** (`camera+0x88`), which has exactly three writers — the
-/// constructor and `SetTarget 0x50d0f0`'s two legs — and is *not* touched by a control update
-/// (wow-re `control-loss-and-restore.md` §3).
+/// constructor and `SetTarget 0x50d0f0`'s two legs — and is *not* touched by a control update.
 ///
 /// Normally our own body, so it rides alongside [`SelfPlayer`]. While we hold somebody else's reins
 /// — mind-controlling a creature, an Eye of Kilrogg — it moves to *that* entity and our own body
@@ -449,8 +457,8 @@ pub(crate) struct Embodied;
 /// own: `0x5fa600` **zeroes the mover globals** when a control update forbids the unit they name,
 /// and with them zero the input applier (`0x514640` skips the whole tick when the mover does not
 /// resolve) and every plain movement report — `0x600860`'s mover check kills the lot, heartbeat
-/// included (wow-re `control-loss-and-restore.md` §2/§6). There is no separate "may not move" flag
-/// in the movement path; the zeroed global *is* the immobility.
+/// included. There is no separate "may not move" flag in the movement path; the zeroed global *is*
+/// the immobility.
 ///
 /// Here it also answers the ECS's version of that question — *may the ordinary server-replay path
 /// move this unit?* A body we are attached to but may not move must answer **yes**, which is how a
@@ -539,12 +547,49 @@ pub(crate) struct LoginSubmit(pub(crate) Sender<io::LoginRequest>);
 #[derive(Resource)]
 pub(crate) struct LoginAbandon(pub(crate) std::sync::Arc<std::sync::atomic::AtomicU64>);
 
-/// guid → spawned ECS entity, for O(1) lookup on move/remove. Maintained solely by
-/// [`apply_net_updates`]; read-only to everyone else (the merchant range-close resolves its vendor
-/// through it).
+/// guid → spawned ECS entity, for O(1) lookup on move/remove — every kind, items and containers
+/// included since decision 2334 (the reference's one `ClntObjMgr` index). Maintained solely by
+/// the object layer's handlers (`net::objects`); read-only to everyone else, through [`Objects`]
+/// or directly.
 #[derive(Resource, Default)]
 pub(crate) struct GuidIndex(pub(crate) HashMap<u64, Entity>);
 
+/// **The object manager's guid lookup** — `ClntObjMgrObjectPtr 0x468460`'s shape: a guid to its
+/// descriptor store, whatever the kind. The one read-only parameter a helper that resolves guids
+/// takes (the inventory walkers resolve item guids off the player's slot arrays through it,
+/// decision 2334), and an item's countdown cells beside its fields (2340); the handlers write
+/// both through their own mutable queries.
+#[derive(SystemParam)]
+pub(crate) struct Objects<'w, 's> {
+    index: Res<'w, GuidIndex>,
+    stores: Query<'w, 's, &'static ObjectStore>,
+    countdowns: Query<'w, 's, &'static crate::items::Countdowns>,
+}
+
+impl Objects<'_, '_> {
+    /// The entity behind a guid, if streamed.
+    pub(crate) fn entity(&self, guid: u64) -> Option<Entity> {
+        self.index.0.get(&guid).copied()
+    }
+
+    /// A streamed object's merged descriptor fields.
+    pub(crate) fn object(&self, guid: u64) -> Option<&ObjectFields> {
+        self.index
+            .0
+            .get(&guid)
+            .and_then(|&e| self.stores.get(e).ok())
+            .map(|s| &s.0)
+    }
+
+    /// An item object's countdown cells — `None` for a guid that is not a held item.
+    pub(crate) fn countdowns(&self, guid: u64) -> Option<&crate::items::Countdowns> {
+        self.index
+            .0
+            .get(&guid)
+            .and_then(|&e| self.countdowns.get(e).ok())
+    }
+}
+
 /// Our own player's guid, once the IO thread reports we're in the world. Used to tag
 /// [`SelfPlayer`], and read by the combat-text emitters' source-ownership classifier
 /// (`crate::combat_text::melee_impact_text` — the "mine" test against Summoned/CreatedBy).
@@ -658,7 +703,7 @@ impl ServerWallClock {
 }
 
 /// How long a wall-clock sample stands before the client asks again — the reference's own hour
-/// (wow-re: the resync site `0x4de836` is gated on `now > [0xbb749c]`, armed `= now + 0xe10` at
+/// (the resync site `0x4de836` is gated on `now > [0xbb749c]`, armed `= now + 0xe10` at
 /// `0x4def11`; decision 1154).
 const RESYNC_AFTER: Duration = Duration::from_secs(3600);
 
@@ -836,8 +881,7 @@ impl MoveKind {
 }
 
 /// The wire `ChatMsg` type byte an addon broadcast rides (decision 1235) — the client's own
-/// four-lane whitelist at `0x49fa3f`-`0x49fa4e`, VERIFIED in `WoW.exe` (5875), wow-re
-/// `system/ui/scratch/addon-chat-law.md` §5.
+/// four-lane whitelist at `0x49fa3f`-`0x49fa4e`.
 ///
 /// A **total** map from a closed enum, and a named function rather than an inline `match` in
 /// [`io`]'s dispatch so that it is assertable: this is the one place a distribution becomes a wire
@@ -1082,7 +1126,7 @@ pub(crate) enum ClientCommand {
     },
     /// Load ammo into the ammo slot (`CMSG_SET_AMMO`) — the equip drains' fork when the clicked/
     /// dropped item is ammo-class (INVTYPE_AMMO), mirroring the real client's own auto-equip fork
-    /// (wow-re `cursor-dragdrop-slots.md`). Addressed by item `entry`, not a bag slot: the stack
+    /// (`0x5e1480`). Addressed by item `entry`, not a bag slot: the stack
     /// stays in the bag and `PLAYER_AMMO_ID` starts referencing it. A wrong/absent ranged weapon
     /// refuses via `InventoryFailure`. Decision 0526.
     SetAmmo {
@@ -1109,8 +1153,8 @@ pub(crate) enum ClientCommand {
         src_slot: u8,
     },
     /// Auto-store an item into a bag (`CMSG_AUTOSTORE_BAG_ITEM`): take `(src_bag, src_slot)` and
-    /// put it anywhere inside `dst_bag` — **the client names no destination slot** (wow-re
-    /// `bag-verbs-law.md`: AUTOSTORE carries none). Sent by `PutItemInBag`'s third leg (an
+    /// put it anywhere inside `dst_bag` — **the client names no destination slot** (`0x5e12e0`:
+    /// AUTOSTORE carries none). Sent by `PutItemInBag`'s third leg (an
     /// ordinary item dropped on an occupied bag button) and by all of `PutItemInBackpack`.
     /// Refusals surface as `InventoryFailure` events.
     AutoStoreBagItem {
@@ -1181,7 +1225,7 @@ pub(crate) enum ClientCommand {
         packed: u32,
     },
     /// Post the four extra bars' visibility byte (`CMSG_SET_ACTIONBAR_TOGGLES`, `PLAYER_FIELD_BYTES`
-    /// byte 2 — wow-re `system/ui/scratch/action-bar-toggles.md`). Sent by the toggle drain, one
+    /// byte 2 — read at `0x4e768c`, sent by `0x4e76e0`). Sent by the toggle drain, one
     /// per `SetActionBarToggles` call: the binding gates nothing, so two calls in a frame are two
     /// packets.
     ///
@@ -1200,7 +1244,7 @@ pub(crate) enum ClientCommand {
     /// Press one pet bar slot (`CMSG_PET_ACTION`, decisions 0982/0988). `packed` is the slot's OWN
     /// word as the server last sent it — command, reaction and spell all ride this one command,
     /// because the server dispatches on the type byte inside the word. `target_guid` is the
-    /// player's current selection, which is what the client always sends (wow-re §10.1).
+    /// player's current selection, which is what the client always sends (`0x4bd212`).
     ///
     /// **Nothing answers it.** Unlike [`Self::SetActionButton`], whose silence is because the
     /// state is ours, this one is silent because the *server* simply does not reply — so the
@@ -1254,8 +1298,8 @@ pub(crate) enum ClientCommand {
     /// **Abandon**, and only that row.
     ///
     /// **Its Dismiss is not this**, however alike they read: `PetDismiss 0x4be4d0` opens no packet
-    /// and goes down the pet bar's ordinary [`Self::PetAction`] path with the word `0x07000003`
-    /// (wow-re §11c). Both would have worked against vmangos, which is why it is written here.
+    /// and goes down the pet bar's ordinary [`Self::PetAction`] path with the word `0x07000003`.
+    /// Both would have worked against vmangos, which is why it is written here.
     ///
     /// No reply: the answer is `SMSG_PET_SPELLS` with a zero guid, and the pet object leaving.
     PetAbandon {
@@ -1280,13 +1324,13 @@ pub(crate) enum ClientCommand {
     AttackStop,
     /// Stop our ranged auto-repeat (`CMSG_CANCEL_AUTO_REPEAT_SPELL`, empty body) — the ack every
     /// local cancel sends (the client's sole send site `0x6ea0c6`, inside the cancel routine
-    /// `0x6ea080`; wow-re `nocked-ammo-cancel.md`). vmangos interrupts the held auto-repeat
-    /// spell; idempotent when the server already cancelled it first (the cast-result path).
+    /// `0x6ea080`). vmangos interrupts the held auto-repeat spell; idempotent when the server
+    /// already cancelled it first (the cast-result path).
     CancelAutoRepeat,
     /// Cancel a named in-flight cast (`CMSG_CANCEL_CAST`, one `u32` spell id). Sent by the
-    /// wand-only auto-repeat handoff before its local cancel (`0x6095b8`, wow-re
-    /// `nocked-ammo-cancel.md` §Q-B-5) and by the cast bar's local self-cancel (movement/Esc
-    /// mid-cast — `ui_cast`'s mirror of the client's `AbortCast 0x6e4940` send leg).
+    /// wand-only auto-repeat handoff before its local cancel (`0x6095b8`) and by the cast bar's
+    /// local self-cancel (movement/Esc mid-cast — `ui_cast`'s mirror of the client's
+    /// `AbortCast 0x6e4940` send leg).
     CancelCast {
         spell_id: u32,
     },
@@ -1863,13 +1907,12 @@ pub(crate) enum ClientCommand {
     //    several refusals (a zero bid/duration, an unaffordable bid, a cancel whose cut can't be
     //    paid, a list request while one is in flight) come back as NO packet at all. ──────────
     //
-    //    Each variant carries `#[allow(dead_code)]`: decision 1511 P0 is the WIRE, and the
-    //    auction window that will construct these is a later phase. The allow is per-variant
-    //    rather than on the enum so a genuinely dead command elsewhere still surfaces, and each
-    //    one comes off the moment its caller lands.
+    //    Every one of these is constructed by `crate::ui_auction`. 1511 P0 landed the wire
+    //    first, under a per-variant `#[allow(dead_code)]` that was to come off the moment its
+    //    caller landed; the window came and the allows stayed, so rustc could no longer judge
+    //    them. A stale allow is a lie the compiler cannot catch — none here, by design.
     /// Greet an auctioneer (`MSG_AUCTION_HELLO`, one guid) — the two-way opcode whose *reply*
     /// (an `AuctionHello` event, carrying the `AuctionHouse.dbc` house id) opens the window.
-    #[allow(dead_code)]
     AuctionHello {
         auctioneer: u64,
     },
@@ -1877,7 +1920,6 @@ pub(crate) enum ClientCommand {
     /// reads them, with `benilla_protocol::messages::auction_filter`'s sentinels for the unset
     /// ones. **No sort rides the wire** — sorting the page is ours. `list_from` pages by 50.
     /// Answered by `SMSG_AUCTION_LIST_RESULT` (an `AuctionListResult` event).
-    #[allow(dead_code)]
     AuctionListItems {
         auctioneer: u64,
         list_from: u32,
@@ -1891,7 +1933,6 @@ pub(crate) enum ClientCommand {
         usable: u8,
     },
     /// Ask the Auctions tab page (`CMSG_AUCTION_LIST_OWNER_ITEMS`) — our own listings.
-    #[allow(dead_code)]
     AuctionListOwnerItems {
         auctioneer: u64,
         list_from: u32,
@@ -1899,7 +1940,6 @@ pub(crate) enum ClientCommand {
     /// Ask the Bid tab page (`CMSG_AUCTION_LIST_BIDDER_ITEMS`). `auction_ids` is a **refresh
     /// set**, not a filter: those rows are emitted first, then every auction we currently hold the
     /// bid on. Empty for a plain page.
-    #[allow(dead_code)]
     AuctionListBidderItems {
         auctioneer: u64,
         list_from: u32,
@@ -1907,7 +1947,6 @@ pub(crate) enum ClientCommand {
     },
     /// List an item for auction (`CMSG_AUCTION_SELL_ITEM`) — the Create Auction pane.
     /// `etime_minutes` must be 120, 480 or 1440; the deposit leaves the purse immediately.
-    #[allow(dead_code)]
     AuctionSellItem {
         auctioneer: u64,
         item_guid: u64,
@@ -1917,7 +1956,6 @@ pub(crate) enum ClientCommand {
     },
     /// Bid on — or buy out — an auction (`CMSG_AUCTION_PLACE_BID`). One verb for both: a `price`
     /// at or above a nonzero buyout *is* the buyout, inferred server-side.
-    #[allow(dead_code)]
     AuctionPlaceBid {
         auctioneer: u64,
         auction_id: u32,
@@ -1925,7 +1963,6 @@ pub(crate) enum ClientCommand {
     },
     /// Cancel one of our own auctions (`CMSG_AUCTION_REMOVE_ITEM`). The deposit is forfeit, and a
     /// cancel on an auction that already has a bid costs the 5% cut out of pocket.
-    #[allow(dead_code)]
     AuctionRemoveItem {
         auctioneer: u64,
         auction_id: u32,
@@ -2182,11 +2219,11 @@ pub(crate) enum ClientCommand {
     /// Ask the server for one party/raid member's whole stat block
     /// (`CMSG_REQUEST_PARTY_MEMBER_STATS`; answered by `SMSG_PARTY_MEMBER_STATS_FULL`).
     ///
-    /// **Sent from exactly two edges, both the reference's** (decision 1640, wow-re
-    /// `ui/scratch/party-oor-stats-and-portrait-law.md` §2): the moment a member's object leaves
-    /// the object manager (`net::apply::group::member_deactivated`), and the GROUP_LIST seat of a
-    /// member new to the roster whose object we do not hold (`seat_new_records`). There is no
-    /// timer and no Lua binding — a periodic poll would be ours, not the client's.
+    /// **Sent from exactly two edges, both the reference's** (decision 1640, `0x4e8646` and
+    /// `0x4e83f1`): the moment a member's object leaves the object manager
+    /// (`ui_party::net::member_deactivated`), and the GROUP_LIST seat of a member new to the roster
+    /// whose object we do not hold (`seat_new_records`). There is no timer and no Lua binding — a
+    /// periodic poll would be ours, not the client's.
     RequestPartyMemberStats {
         guid: u64,
     },
@@ -2409,7 +2446,6 @@ pub(crate) enum ClientCommand {
     //    be treated as applied at the send.
     /// Ask a petitioner NPC for its charter list (`CMSG_PETITION_SHOWLIST`). The gossip row pushes
     /// the same answer unasked, so this is the direct re-open, not the only way in.
-    #[allow(dead_code)]
     PetitionShowList {
         npc: u64,
     },
@@ -2689,10 +2725,9 @@ pub(crate) struct TeleportMessage {
 ///
 /// **The real client applies these** — its inbound move path has no mover-guid gate at all, and the
 /// local player sits in the object manager under its own guid, so a self-addressed packet resolves
-/// and applies exactly like a remote's (wow-re `system/collision/scratch/self-addressed-move.md`;
-/// decision 0725, which corrects the drop this used to take). Our avatar's motion source is the
-/// controller rather than the `RemoteMotion` lane, so the pose crosses as this message and lands in
-/// `player::wire_in`.
+/// and applies exactly like a remote's (`0x603bb0`; decision 0725, which corrects the drop this
+/// used to take). Our avatar's motion source is the controller rather than the `RemoteMotion`
+/// lane, so the pose crosses as this message and lands in `player::wire_in`.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct SelfMoveMessage {
     pub(crate) position: [f32; 3],
@@ -3074,10 +3109,10 @@ mod tests {
     ///
     /// The bottom of the cascade has **no** guard, and decision 1759 is why: 1752 shipped a
     /// zero-`walk` fallback to the run arm, on the reading that a mover could reach here before
-    /// its speed block landed. The wow-re §5 retracted the basis for it — the local player's
-    /// create applies the speed block like anyone else's — so the fallback is gone. The zero is
-    /// asserted rather than merely no longer asserted against, so that re-adding the guard is a
-    /// deliberate act with a record to argue against, not a plausible-looking tidy-up.
+    /// its speed block landed. It cannot — the local player's create applies the speed block like
+    /// anyone else's (`0x5fad50`) — so the fallback is gone. The zero is asserted rather than
+    /// merely no longer asserted against, so that re-adding the guard is a deliberate act with a
+    /// record to argue against, not a plausible-looking tidy-up.
     #[test]
     fn a_mode_is_not_a_motion_and_a_zero_walk_speed_is_a_zero() {
         use crate::creature_anim::move_flags as f;
diff --git a/crates/benilla-app/src/net/apply.rs b/crates/benilla-app/src/net/apply.rs
index 252cecb9..ad1e5a7e 100644
--- a/crates/benilla-app/src/net/apply.rs
+++ b/crates/benilla-app/src/net/apply.rs
@@ -1,1944 +1,28 @@
 //! The per-frame wire→ECS bridge systems: [`apply_net_updates`] drains the inbound
-//! [`SessionEvent`] channel into real entities (spawn/move/despawn, descriptor merges, splines,
-//! teleports, clock), and [`tag_self_player`] marks our own streamed entity. The parent module
-//! owns the channel/type surface; this module owns the event application.
+//! [`SessionEvent`] channel through the handler table, and [`tag_self_player`] marks our own
+//! streamed entity. The parent module owns the channel/type surface and, since 2327, every
+//! packet's handler is a subsystem's own or the bridge's own ([`super::session`],
+//! [`super::objects`], [`super::world`]); nothing is applied here.
 
-use std::collections::HashMap;
-
-use benilla_protocol::{ObjectFields, SessionEvent};
+use benilla_protocol::SessionEvent;
 use bevy::prelude::*;
 
-use super::{
-    Guid, GuidIndex, NetCommands, NetEvents, NetStatus, ObjectStore, Reputations, SelfGuid,
-    SelfPlayer,
-};
+use super::{Guid, NetEvents, SelfGuid, SelfPlayer};
 
-mod anim;
-mod chat;
-mod combat;
-mod combat_chat;
-mod combat_log;
-mod death;
-mod group;
-mod loot;
-mod mail;
-mod mount;
-mod names;
-mod npc;
-mod objects;
-mod params;
-mod pet;
-mod quests;
-mod session;
-mod spells;
-mod trade;
-mod world;
-
-use params::{ActionStores, AnimWriters, Catalogs, Clocks, ObjectQueries, Session, WindowStores};
-
-// The arm families, split out of the dispatch match below (each `pub(super)` fn is one arm's
-// body; the match stays the dispatcher, one call per arm — see the child modules).
-use loot::{
-    inventory_failure, item_push_result, item_template, loot_all_passed, loot_clear_money,
-    loot_error, loot_master_list, loot_money_notify, loot_release_response, loot_removed,
-    loot_response, loot_roll, loot_roll_won, loot_start_roll,
-};
-use quests::{
-    quest_complete, quest_confirm_accept, quest_detail, quest_failed, quest_giver_failed,
-    quest_giver_invalid, quest_giver_status, quest_greeting, quest_log_full, quest_objective_item,
-    quest_objective_kill, quest_objectives_complete, quest_offer, quest_progress,
-    quest_push_result, quest_template,
-};
-use spells::{
-    action_buttons, aura_duration, cancel_auto_repeat, cast_result, channel_start, channel_update,
-    clear_cooldown, cooldown_cheat, cooldown_event, item_cooldown, learned_spell, removed_spell,
-    set_spell_modifier, spell_book, spell_chain_targets, spell_cooldowns, spell_delayed,
-    spell_failed_other, spell_go, spell_start, superceded_spell,
-};
-
-/// Which unit's cooldown store a wire cooldown packet addresses (decision 0982).
-///
-/// All four of them (`SMSG_SPELL_COOLDOWN`, `_COOLDOWN_EVENT`, `_CLEAR_COOLDOWN`,
-/// `_COOLDOWN_CHEAT`) carry a caster guid, and until the pet bar existed all four answered it the
-/// same way: "is it us? then apply, else drop" — four copies of a self-only assumption, each
-/// inside its own arm. Since the server sends a pet's cooldowns on the pet's guid, that
-/// assumption silently discarded every one of them. Resolving the guid ONCE, here, is what let the
-/// pet bar sweep for real without a second copy of any arm; it also matches the reference, whose
-/// `SMSG_COOLDOWN_CHEAT` handler wipes "the self/pet cooldown list" off exactly this test.
-///
-/// `None` = a guid we hold no store for (another player's pet, a stale packet): dropped, as the
-/// client drops an unknown guid.
-fn addressed_store<'a>(
-    caster: u64,
-    self_guid: &SelfGuid,
-    player: &'a mut crate::cooldowns::Cooldowns,
-    pet: &'a mut crate::ui_pet::PetBar,
-) -> Option<&'a mut crate::cooldowns::Cooldowns> {
-    if self_guid.0 == Some(caster) {
-        Some(player)
-    } else if pet.has_bar() && pet.spells.pet_guid == caster {
-        Some(&mut pet.cooldowns)
-    } else {
-        None
-    }
-}
+#[cfg(test)]
+mod seam_tests;
 
 // ── The per-frame bridge systems ─────────────────────────────────────────────────────────────────
 
-/// The drain: take this frame's events off the channel and run them, **in packet order**, through
-/// the two halves of the dispatch (decision 2305) — first the kinds the `match` below still owns,
-/// through [`apply_unpeeled`], then the kinds a subsystem has claimed in the handler table
-/// ([`super::handlers`]), each handler a one-shot system over this exclusive world. One frame,
-/// packet order, before anything else in [`benilla_world::schedule::WorldStage::Net`] runs: the
-/// property 0006 built and 2265 said every split must keep.
+/// The drain: take this frame's events off the channel and run each through the handler table
+/// ([`super::handlers`]) **in wire order**, one after another, each handler a one-shot system
+/// over this exclusive world with its commands applied before the next (decisions 2305, 2306,
+/// 2327). One frame, packet order, before anything else in
+/// [`benilla_world::schedule::WorldStage::Net`] runs: the property 0006 built and 2265 said
+/// every split must keep.
 pub(crate) fn apply_net_updates(world: &mut World) {
     let events: Vec<SessionEvent> = world.resource::<NetEvents>().0.try_iter().collect();
-    super::handlers::dispatch(world, events, |world, unclaimed| {
-        if let Err(e) = world.run_system_cached_with(apply_unpeeled, unclaimed) {
-            panic!("the drain's dispatch match did not run: {e}");
-        }
-    });
-}
-
-/// The dispatch `match` — every kind no subsystem has claimed yet (2305's migration runs one
-/// window family at a time out of here into its own module's handlers). Mutates real ECS
-/// entities: spawn on create, move existing, despawn on remove, attach/clear movement splines,
-/// and surface teleport/worldport/clock changes; parks the rest into window state.
-fn apply_unpeeled(
-    In(events): In<Vec<SessionEvent>>,
-    mut commands: Commands,
-    net_commands: Res<NetCommands>,
-    mut index: ResMut<GuidIndex>,
-    mut self_guid: ResMut<SelfGuid>,
-    mut status: ResMut<NetStatus>,
-    mut reputations: ResMut<Reputations>,
-    // The families, by name (`params`): the drain destructures each one below so every arm
-    // reads a plain local.
-    clocks: Clocks,
-    objects: ObjectQueries,
-    session: Session,
-    windows: WindowStores,
-    actions: ActionStores,
-    anim: AnimWriters,
-    catalogs: Catalogs,
-) {
-    let Clocks {
-        mut server_time,
-        mut wall_clock,
-        real: real_clock,
-    } = clocks;
-    let ObjectQueries {
-        mut transforms,
-        mut stores,
-        remote: mut remote_motion,
-        modes: mut unit_modes,
-        mut riders,
-        speeds: unit_speeds,
-        transports,
-        casting: casting_units,
-        engaged_self,
-        mut field_changes,
-    } = objects;
-    let ActionStores {
-        mut player_actions,
-        mut cast_errors,
-        mut mount_errors,
-        mut chain_casts,
-        mut pet_tame_failures,
-        mut learned_in_tab,
-        mut equip_errors,
-        mut merchant_errors,
-        mut cast_bar,
-        mut pending_item_ops,
-        mut lock_transitions,
-        mut trainer_errors,
-        mut stable_errors,
-        mut pending_cast,
-        cooldowns: mut cooldown_store,
-        mut auto_repeat,
-        mut active_channel,
-        mut ui_error_texts,
-        mut queued_melee,
-        mut aura_durations,
-        mut spell_mods,
-    } = actions;
-    let AnimWriters {
-        mut server_sounds,
-        weather: mut weather_msgs,
-        mut emotes,
-        mut swings,
-        mut cast_events,
-        mut spell_go_targets,
-        combat_text: mut combat_text_spawns,
-        mut swing_impacts,
-        mut swing_flushes,
-        go_lid_open: mut go_lid_opens,
-        mut ai_reactions,
-        mut kit_pushes,
-        mut hard_landings,
-        mut mount_flourishes,
-        unit_combat: mut unit_combat_feedback,
-        mut combat_text_events,
-        mut sheath_requests,
-        go_custom_anim: mut go_custom_anims,
-        pet_talk: mut pet_talks,
-        pet_dismiss: mut pet_dismiss_sounds,
-        swing_refusals: mut swing_refusal_edges,
-        mut play_seq,
-    } = anim;
-    let Catalogs {
-        factions: faction_catalog,
-        spells: spell_catalog,
-        combat_cvars,
-        env_damage: env_damage_table,
-        area_table,
-        exploration_sounds,
-        current_map,
-        guild_notify,
-    } = catalogs;
-    // A `&mut` to the counter itself (deref-coerced through the `ResMut`), so the arms that stamp
-    // it *conditionally* can take it by reference and only advance it when they emit.
-    let play_seq: &mut crate::creature_anim::PlaySeq = &mut play_seq;
-    let WindowStores {
-        mut names,
-        mut items,
-        mut gossip,
-        mut merchant,
-        mut trainer_open,
-        mut stable_open,
-        mut loot,
-        mut loot_latch,
-        mut loot_rolls,
-        mut chat_log,
-        mut quest,
-        mut quest_log,
-        mut quest_share,
-        mut go_templates,
-        mut home_bind,
-        mut proficiencies,
-        mut dropped,
-        mut death_net,
-        mut group,
-        mut taxi,
-        mut mail_open,
-        mut mail_pending,
-        mut trade_session,
-        mut bank_open,
-        mut bank_errors,
-        mut world_states,
-        mut duel,
-        mut social,
-        mut logout,
-        mut mirror_timers,
-        mut pet_bar,
-        mut ui_error_keys,
-        mut page_texts,
-        mut played_time_answer,
-        mut guild,
-        mut binder,
-        mut talent_wipe,
-        mut pet_unlearn,
-        mut instance_boot,
-        mut area_spirit,
-        mut battlefield_queue,
-        mut meeting_stone,
-        mut battlefield_scoreboard,
-        mut battlefield,
-        mut tutorials,
-        mut battlefield_positions,
-        mut tabard,
-        mut poi_marker,
-        mut inspect_honor,
-        mut ping,
-        mut gm_ticket,
-        mut registrar,
-        mut petition,
-        mut summon,
-        mut instances,
-    } = windows;
-    let Session {
-        mut teleports,
-        mut worldports,
-        mut char_lists,
-        mut realm_lists,
-        mut char_actions,
-        mut char_login_failures,
-        mut entered_world,
-        mut addon_reply,
-        mut logged_out,
-        mut speed_changes,
-        mut move_modes,
-        mut knockbacks,
-        mut login_stages,
-        mut login_queued,
-        mut login_failures,
-        mut disconnects,
-        mut server_said,
-        mut self_moves,
-        mut client_control,
-        mut cinematics,
-        transfer: mut pending_transfer,
-    } = session;
-    // Descriptor seeds/deltas for objects created *earlier in this same drain* can't land on their
-    // entities yet (the spawn `Command` hasn't run), so they accumulate here and flush once at the end.
-    // This also removes a latent clobber: a plain per-delta `insert` on a not-yet-spawned entity would
-    // overwrite an earlier partial rather than merge it (decision 0061).
-    let mut pending: HashMap<u64, ObjectFields> = HashMap::new();
-    // The drain's staged [`UnitMoveModes`] grants — see [`objects::StagedModes`]. A grant and the
-    // `SMSG_MONSTER_MOVE` it refuses can land in the same drain, and the refusal has to see it.
-    let mut staged_modes = objects::StagedModes::new();
-    // The same deferral trap for movers' speeds, and the one B213 fell into: a create's
-    // `UnitSpeeds` insert is a Command, so a `SMSG_FORCE_*_SPEED_CHANGE` arriving later in this
-    // same drain could not land on top of it. Both stage here in packet order (decision 1478).
-    let mut speed_stage = objects::SpeedStage::default();
-    // The combat log's classification inputs (B297). Built per use rather than once: the arms
-    // around these ones take `&mut` to `index`, `group` and `reputations`, so a borrow held across
-    // the whole drain would not compile. `macro_rules!` here is hygienic against the locals it
-    // names because it is defined after them, so this is one expression in seven call sites rather
-    // than seven copies of six fields.
-    macro_rules! chat_ctx {
-        () => {
-            combat_chat::ChatCtx {
-                self_guid: &self_guid,
-                group: Some(&group),
-                index: &index,
-                factions: faction_catalog.as_deref(),
-                reputations: &reputations,
-                spells: spell_catalog.as_deref(),
-                ranges: &combat_cvars.ranges,
-                periodic: combat_cvars.periodic.0,
-            }
-        };
-    }
-    for ev in events {
-        match ev {
-            SessionEvent::LoginStage { stage } => session::login_stage(stage, &mut login_stages),
-            SessionEvent::LoginQueued { position, realm } => {
-                login_queued.write(crate::net::LoginQueuedMessage { position, realm });
-            }
-            SessionEvent::LoginFailed {
-                refusal,
-                reason,
-                terminal,
-                dial,
-            } => session::login_failed(refusal, reason, terminal, dial, &mut login_failures),
-            SessionEvent::RealmList { realms } => {
-                realm_lists.write(crate::net::RealmListMessage { realms });
-            }
-            SessionEvent::CharacterList { characters, realm } => {
-                session::character_list(characters, realm, &mut status, &mut char_lists)
-            }
-            SessionEvent::CharActionResult { action, code } => {
-                session::char_action_result(action, code, &mut char_actions)
-            }
-            SessionEvent::CharacterLoginFailed { result } => {
-                session::character_login_failed(result, &mut char_login_failures)
-            }
-            SessionEvent::CinematicTriggered { cinematic_id } => {
-                session::cinematic_triggered(cinematic_id, &mut cinematics)
-            }
-            SessionEvent::Connected {
-                self_guid: guid,
-                name,
-                billing_time_rested,
-                tutorial_flags,
-                addon_info,
-            } => session::connected(
-                guid,
-                name,
-                billing_time_rested,
-                tutorial_flags,
-                addon_info,
-                &mut addon_reply,
-                &mut self_guid,
-                &mut status,
-                &mut names,
-                &mut entered_world,
-            ),
-            SessionEvent::LoggedOut => {
-                session::logged_out(&mut commands, &mut index, &mut self_guid, &mut logged_out)
-            }
-            // The logout arc's two narration packets (decision 0674) — `crate::ui_logout` owns the
-            // decision table; this is only the hand-off.
-            SessionEvent::LogoutResponse { reason, instant } => {
-                logout.apply_response(reason, instant)
-            }
-            SessionEvent::LogoutCancelled => logout.apply_cancelled(),
-            SessionEvent::Disconnected { reason, end } => {
-                session::disconnected(
-                    reason,
-                    end,
-                    &mut commands,
-                    &mut index,
-                    &mut self_guid,
-                    &mut status,
-                    &mut names,
-                    &mut items,
-                    &mut gossip,
-                    &mut merchant,
-                    &mut trainer_open,
-                    &mut loot,
-                    &mut loot_latch,
-                    &mut loot_rolls,
-                    &mut chat_log,
-                    &mut quest,
-                    &mut quest_log,
-                    &mut quest_share,
-                    &mut death_net,
-                    &mut group,
-                    &mut taxi,
-                    &mut mail_open,
-                    &mut mail_pending,
-                    &mut trade_session,
-                    &mut bank_open,
-                    &mut duel,
-                    &mut social,
-                    &mut guild,
-                    &mut gm_ticket,
-                    &mut cooldown_store,
-                    &mut pending_transfer,
-                    &mut disconnects,
-                );
-            }
-            SessionEvent::ObjectCreate {
-                guid,
-                kind,
-                display_id,
-                position,
-                orientation,
-                scale,
-                speeds,
-                mover,
-                transport_progress,
-                transport,
-                spline,
-                fields,
-            } => {
-                death::note_corpse(guid, kind, &fields, &self_guid, &mut death_net);
-                objects::object_create(
-                    guid,
-                    kind,
-                    display_id,
-                    position,
-                    orientation,
-                    scale,
-                    speeds,
-                    mover,
-                    transport_progress,
-                    transport,
-                    spline,
-                    fields,
-                    &mut commands,
-                    &mut index,
-                    &mut transforms,
-                    &mut stores,
-                    &mut pending,
-                    &mut field_changes,
-                    &mut speed_stage,
-                    &names,
-                    &go_templates,
-                    &net_commands,
-                )
-            }
-            SessionEvent::ItemCreate {
-                guid,
-                container,
-                fields,
-            } => objects::item_create(guid, container, fields, &mut items),
-            SessionEvent::ObjectMove {
-                guid,
-                position,
-                orientation,
-            } => objects::object_move(
-                guid,
-                position,
-                orientation,
-                &mut commands,
-                &index,
-                &mut transforms,
-            ),
-            // **An observed mover skipped time** (decision 1935). No pose moved — only that
-            // unit's clock ran on — so this touches its relay chain and nothing else, which is
-            // the whole of what the reference's handler does (`0x603b40` → `0x61ab90`:
-            // `[CMovement+0xac] += lag`). A guid we do not hold is dropped, faithfully: the
-            // reference resolves under `TYPEMASK_UNIT` and returns on a miss.
-            SessionEvent::MoveTimeSkipped { guid, lag_ms } => {
-                if let Some(mut m) = index
-                    .0
-                    .get(&guid)
-                    .and_then(|&e| remote_motion.get_mut(e).ok())
-                {
-                    m.relay.skip_time(lag_ms);
-                }
-            }
-            SessionEvent::UnitMove {
-                guid,
-                position,
-                orientation,
-                flags,
-                pitch,
-                time,
-                verb,
-                fall_time,
-                jump,
-                transport,
-            } => {
-                // The scheduled-replay law (decisions 0601/0615): `unit_move` runs the mover's own
-                // replay chain over this packet's wire stamp to get its client fire-time, then
-                // applies it now if due, else queues it on the unit for `drain_pending_moves`.
-                let now_ms = real_clock.elapsed_secs_f64() * 1000.0;
-                objects::unit_move(
-                    guid,
-                    crate::net::motion::RelayMove {
-                        wire_ms: time,
-                        position,
-                        orientation,
-                        flags,
-                        pitch,
-                        fall_time,
-                        jump,
-                        transport,
-                        verb,
-                    },
-                    now_ms,
-                    &mut commands,
-                    &index,
-                    &self_guid,
-                    &mut remote_motion,
-                    &mut transforms,
-                    &mut hard_landings,
-                    &mut self_moves,
-                );
-            }
-            SessionEvent::ObjectValues { guid, fields } => {
-                // Our corpse's own `CORPSE_FIELD_FLAGS` can flip to BONES under a live guid; the
-                // reclaim latch is re-asked on that edge, as the reference's `FLAGS` mirror
-                // handler `0x5d6d60` does (1729).
-                death::recheck_corpse(guid, &fields, &self_guid, &mut death_net);
-                objects::object_values(
-                    guid,
-                    fields,
-                    &index,
-                    &mut stores,
-                    &mut pending,
-                    &mut field_changes,
-                    &mut items,
-                )
-            }
-            SessionEvent::ObjectDestroyed(guid) => {
-                death::forget_corpse(guid, &mut death_net);
-                // The party hook runs FIRST and on the same edge the reference takes it: the
-                // deactivate virtual reads the descriptor that is about to go (decision 1640).
-                let store = index.0.get(&guid).and_then(|e| stores.get(*e).ok());
-                group::member_deactivated(guid, &mut group, store, &net_commands);
-                objects::object_destroyed(guid, &mut commands, &mut index, &mut items)
-            }
-            SessionEvent::ObjectsRemoved(guids) => {
-                // OUT_OF_RANGE and DESTROY take the same virtual in the reference — so the
-                // snapshot + `CMSG_REQUEST_PARTY_MEMBER_STATS` fire here too, which is the edge
-                // report B334 is actually about: a member walking over the hill.
-                for guid in &guids {
-                    let store = index.0.get(guid).and_then(|e| stores.get(*e).ok());
-                    group::member_deactivated(*guid, &mut group, store, &net_commands);
-                }
-                objects::objects_removed(guids, &mut commands, &mut index)
-            }
-            SessionEvent::MonsterMove {
-                guid,
-                transport,
-                start,
-                spline_id,
-                path,
-                facing,
-                stop,
-                duration_ms,
-                flying,
-                run_mode,
-            } => objects::monster_move(
-                guid,
-                transport,
-                start,
-                spline_id,
-                path,
-                facing,
-                stop,
-                duration_ms,
-                flying,
-                run_mode,
-                objects::modes_of(guid, &index, &unit_modes, &staged_modes).rooted(),
-                &mut commands,
-                &index,
-                &mut transforms,
-                &mut riders,
-            ),
-            SessionEvent::Teleport {
-                guid,
-                counter,
-                position,
-                orientation,
-            } => session::teleport(
-                guid,
-                counter,
-                position,
-                orientation,
-                &self_guid,
-                &mut teleports,
-            ),
-            SessionEvent::Worldport {
-                map_id,
-                position,
-                orientation,
-                needs_ack,
-            } => {
-                // Every streamed roster member's object is about to be purged — the same
-                // deactivation the reference runs one object at a time (decision 1640).
-                group::roster_deactivated(&mut group, &index, &stores, &net_commands);
-                session::worldport(
-                    map_id,
-                    position,
-                    orientation,
-                    needs_ack,
-                    &mut commands,
-                    &mut index,
-                    &mut pending_transfer,
-                    &transports,
-                    &mut worldports,
-                )
-            }
-            SessionEvent::TransferPending {
-                map_id,
-                transport_entry,
-            } => session::transfer_pending(map_id, transport_entry, &mut pending_transfer),
-            SessionEvent::TransferAborted { reason } => {
-                session::transfer_aborted(reason, &mut pending_transfer)
-            }
-            SessionEvent::TimeSpeed {
-                hours,
-                minutes,
-                day_serial,
-                timescale,
-            } => session::time_speed(hours, minutes, day_serial, timescale, &mut server_time),
-            SessionEvent::ServerUnixTime { unix_time } => {
-                session::server_unix_time(unix_time, &mut wall_clock)
-            }
-            SessionEvent::Reputations { standings } => {
-                session::reputations(standings, &mut reputations)
-            }
-            SessionEvent::ReputationDelta { standings } => {
-                // The chat line reads the deltas against the store, so it runs BEFORE the
-                // overwrite — after it, every delta is zero.
-                combat_chat::faction_standing(
-                    &standings,
-                    &reputations,
-                    faction_catalog.as_deref(),
-                    &mut chat_log,
-                );
-                session::reputation_delta(standings, &mut reputations, &mut quest)
-            }
-            SessionEvent::ReputationVisible { list_id } => {
-                session::reputation_visible(list_id, &mut reputations)
-            }
-            SessionEvent::BindPoint { area } => home_bind.0 = Some(area),
-            // The honor arc's two inbound messages (decision 1512).
-            //
-            // The inspect reply REPLACES whatever is held, including for a different player: the
-            // reference's latch is a single slot, and a pane still showing the last target's
-            // kills is the failure keeping the old one produces.
-            SessionEvent::InspectHonorStats(stats) => inspect_honor.0 = Some(stats),
-            // An honor award: 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.
-            SessionEvent::PvpCredit(credit) => {
-                chat_log.push_pvp_credit(
-                    credit.honor,
-                    credit.victim_guid,
-                    u8::try_from(credit.victim_rank).unwrap_or(0),
-                );
-                combat_text_events.write(crate::ui_unit::CombatTextEvent {
-                    message_type: "HONOR_GAINED",
-                    data: Some(credit.honor.to_string()),
-                    extra: None,
-                });
-            }
-            SessionEvent::BinderConfirm { binder: npc } => binder.ask(npc),
-            // Someone is asking to pull us to them (decision 1747). The reference gates this in
-            // the HANDLER, not the dialog: a dead or ghost player's request is dropped before the
-            // latch, so it cannot disturb a live question either (`0x5e6194`). The predicate is
-            // `0x605f30` — **health ≤ 0 OR (is-player AND `PLAYER_FLAGS` ghost bit)**, which is
-            // both of these accessors and not the one `unit_is_dead` alone would give (a ghost's
-            // wire health is 1). A self object we have not streamed yet reads as alive: the
-            // reference's own default (`0x5e6189` sends a NULL object through to the latch).
-            SessionEvent::SummonRequest {
-                summoner,
-                zone,
-                delay_ms,
-            } => {
-                let dead_or_ghost = self_guid
-                    .0
-                    .and_then(|g| index.0.get(&g))
-                    .and_then(|e| stores.get(*e).ok())
-                    .is_some_and(|s| s.0.unit_is_dead() || s.0.player_is_ghost());
-                crate::ui_summon::apply::request(
-                    summoner,
-                    zone,
-                    delay_ms,
-                    dead_or_ghost,
-                    real_clock.elapsed_secs_f64(),
-                    &mut summon,
-                );
-            }
-            // The GM ticket answers (decision 1673). The GETTICKET arm takes EVERY answer,
-            // including `None` ("you have no ticket") and including an unsolicited one pushed by a
-            // GM's `.ticket view`/`escalate`/`complete` — they are indistinguishable on the wire
-            // and want identical handling.
-            SessionEvent::GmTicket { ticket } => gm_ticket.answer(ticket),
-            SessionEvent::GmTicketSystemStatus { status } => gm_ticket.answer_queue(status),
-            // A GM touched the ticket. Value 1 makes the reference re-ask (`0x5e7932`), the same
-            // leg the create/update success codes take; 2 (closed) and 3 (survey offered) are
-            // recorded and not acted on — 3 is the survey trigger and that window is deferred.
-            // vmangos never sends this packet at all, so on our server the arm is dead; cmangos
-            // makes it the whole notification model, which is why it is parsed rather than dropped.
-            SessionEvent::GmTicketStatusUpdate { status } => {
-                crate::ui_gm_ticket::apply::status_update(status, &mut gm_ticket)
-            }
-            // The three response codes have no consumer in the shipped 1.12 UI — no event, no
-            // handler. Logged so a refusal is visible in a session log rather than silent; the
-            // `ERR_TICKET_*` display path is still unpinned (see `ui_gm_ticket::apply`).
-            // Create-ok (2) and update-ok (4) make the ENGINE re-ask for the ticket — the
-            // reference's own `0x5e4479` arm, and the reason the shipped UI needs no handler for
-            // either opcode. Without it a filed ticket goes unseen until the 10-minute poll.
-            SessionEvent::GmTicketCreated { response } => {
-                crate::ui_gm_ticket::apply::write_response("create", response, 2, &mut gm_ticket)
-            }
-            SessionEvent::GmTicketUpdated { response } => {
-                crate::ui_gm_ticket::apply::write_response("update", response, 4, &mut gm_ticket)
-            }
-            SessionEvent::GmTicketDeleted { response } => {
-                crate::ui_gm_ticket::apply::response("delete", response)
-            }
-            // A zero trainer guid is vmangos's "you have no talents to reset" refusal, not a
-            // question — there is nothing to ask about, so nothing goes on screen (decision 1580;
-            // `crate::ui_talent_wipe`'s header carries why the reference instead re-sends here).
-            SessionEvent::TalentWipeConfirm { trainer, cost } => {
-                if trainer == 0 {
-                    debug!("net: talent wipe refused (no talents to reset) — no dialog");
-                } else {
-                    debug!("net: trainer {trainer:#x} asks to wipe talents for {cost} copper");
-                    talent_wipe.ask(trainer, cost);
-                }
-            }
-            // The pet trainer's question (decision 1963) — the talent-wipe twin above; a zero
-            // guid is the reference's own `ERR_TALENT_WIPE_ERROR` leg, carried over as observed.
-            SessionEvent::PetUnlearnConfirm { trainer, cost } => {
-                if trainer == 0 {
-                    debug!("net: pet unlearn refused (zero trainer) — no dialog");
-                    ui_error_keys
-                        .0
-                        .push(crate::ui_action::UiError::key("ERR_TALENT_WIPE_ERROR"));
-                } else {
-                    debug!("net: trainer {trainer:#x} asks to unlearn the pet for {cost} copper");
-                    pet_unlearn.ask(trainer, cost);
-                }
-            }
-            SessionEvent::RaidGroupOnly { delay_ms, reason } => {
-                instance_boot.apply(delay_ms, reason, std::time::Instant::now());
-            }
-            SessionEvent::AreaSpiritHealerTime { healer, ms } => {
-                area_spirit.on_time(healer, ms, std::time::Instant::now());
-            }
-            SessionEvent::BattlefieldStatus(status) => battlefield_queue.apply(status),
-            SessionEvent::PvpLogData(data) => battlefield_scoreboard.apply(data),
-            SessionEvent::BattlefieldList(list) => battlefield.apply_list(list),
-            SessionEvent::GroupJoinedBattleground { result } => battlefield.apply_verdict(result),
-            SessionEvent::BattlegroundPlayer { guid, joined } => {
-                battlefield.apply_player(guid, joined);
-            }
-            SessionEvent::MeetingStoneSetQueue { area, status } => {
-                meeting_stone.apply(area, status);
-            }
-            SessionEvent::MeetingStoneNotice(notice) => meeting_stone.apply_notice(notice),
-            SessionEvent::TutorialFlags(bytes) => tutorials.apply_flags(&bytes),
-            SessionEvent::BattlefieldPositions(packet) => battlefield_positions.apply(packet),
-            SessionEvent::TabardVendorActivate(vendor) => tabard.open(vendor),
-            // A saved emblem evicts our guild's cached record (`0x5e715f`): the next query
-            // anywhere re-fetches it — no event, no packet.
-            SessionEvent::SaveGuildEmblemResult(result) => {
-                if tabard.apply_result(result) {
-                    guild.evict_own_identity();
-                }
-            }
-            SessionEvent::PlayerBound { binder: npc, area } => {
-                debug!("net: bound to area {area} by {npc:#x}");
-                crate::ui_binder::apply::bound(
-                    area,
-                    &mut binder,
-                    &mut ui_error_keys,
-                    area_table.as_deref(),
-                    &mut server_sounds,
-                )
-            }
-            SessionEvent::Proficiency {
-                item_class,
-                subclass_mask,
-            } => {
-                proficiencies.0.insert(item_class, subclass_mask);
-            }
-            SessionEvent::PlayerName {
-                guid,
-                name,
-                race,
-                class,
-                gender,
-            } => names::player_name(guid, name, race, class, gender, &mut names),
-            SessionEvent::PetName { pet_number, name } => {
-                names::pet_name(pet_number, name, &mut names)
-            }
-            SessionEvent::CreatureName {
-                entry,
-                name,
-                subname,
-                creature_type,
-                pet_family,
-                rank,
-                type_flags,
-                display_id,
-                civilian,
-                racial_leader,
-            } => names::creature_name(
-                entry,
-                name,
-                subname,
-                creature_type,
-                pet_family,
-                rank,
-                type_flags,
-                civilian,
-                racial_leader,
-                display_id,
-                &mut names,
-            ),
-            SessionEvent::GameObjectInfo {
-                entry,
-                type_id,
-                display_id,
-                name,
-                data,
-            } => {
-                objects::gameobject_info(entry, type_id, display_id, name, &data, &mut go_templates)
-            }
-            SessionEvent::GameObjectCustomAnim { guid, anim_id } => {
-                objects::gameobject_custom_anim(guid, anim_id, &mut go_custom_anims)
-            }
-            SessionEvent::GameObjectDespawnAnim { guid } => {
-                objects::gameobject_despawn_anim(guid, &mut commands, &index)
-            }
-            SessionEvent::FishNotHooked => loot::fish_verdict(false, &mut ui_error_keys),
-            SessionEvent::FishEscaped => loot::fish_verdict(true, &mut ui_error_keys),
-            SessionEvent::PlaySound { sound_id } => world::play_sound(sound_id, &mut server_sounds),
-            SessionEvent::PlayMusic { music_id } => world::play_music(music_id, &mut server_sounds),
-            SessionEvent::PlayObjectSound { sound_id, guid } => {
-                world::play_object_sound(sound_id, guid, &index, &mut server_sounds)
-            }
-            SessionEvent::Weather {
-                weather_type,
-                grade,
-                sound_id,
-                instant,
-            } => world::weather(weather_type, grade, sound_id, instant, &mut weather_msgs),
-            SessionEvent::TextEmote {
-                guid,
-                text_emote,
-                target_name,
-            } => anim::text_emote(
-                guid,
-                text_emote,
-                target_name,
-                &index,
-                &mut emotes,
-                &mut chat_log,
-            ),
-            SessionEvent::Emote { guid, emote_id } => {
-                anim::emote(guid, emote_id, &index, &mut emotes)
-            }
-            // The spell-book/action-bar pair → the action store the UI feed reads
-            // (`crate::ui_action`), sent once at login (and the bar again on server-side edits).
-            SessionEvent::SpellBook {
-                spell_ids,
-                cooldowns,
-            } => spell_book(
-                spell_ids,
-                cooldowns,
-                &mut player_actions,
-                &mut cooldown_store,
-            ),
-            SessionEvent::ActionButtons { buttons } => action_buttons(buttons, &mut player_actions),
-            SessionEvent::SpellLearned { spell_id } => learned_spell(
-                spell_id,
-                &mut player_actions,
-                spell_catalog.as_deref(),
-                &mut ui_error_keys,
-                &mut learned_in_tab,
-            ),
-            SessionEvent::SpellRemoved { spell_id } => removed_spell(
-                spell_id,
-                &mut player_actions,
-                spell_catalog.as_deref(),
-                &mut ui_error_keys,
-            ),
-            SessionEvent::SpellSuperceded {
-                old_spell_id,
-                new_spell_id,
-            } => superceded_spell(
-                old_spell_id,
-                new_spell_id,
-                &mut player_actions,
-                spell_catalog.as_deref(),
-                &mut ui_error_keys,
-                &mut learned_in_tab,
-            ),
-            SessionEvent::CastResult {
-                spell_id,
-                success,
-                reason,
-                arg,
-            } => cast_result(
-                spell_id,
-                success,
-                reason,
-                arg,
-                &mut commands,
-                &self_guid,
-                &index,
-                &mut cast_errors,
-                &casting_units,
-                &mut cast_events,
-                &mut cast_bar,
-                &mut pending_cast,
-                &mut queued_melee,
-                &mut cooldown_store,
-                &mut auto_repeat,
-                spell_catalog.as_deref(),
-                &net_commands,
-                &mut chain_casts,
-                play_seq.next(),
-            ),
-            SessionEvent::InventoryFailure {
-                reason,
-                required_level,
-                item_guid,
-                bag_slot,
-            } => inventory_failure(
-                reason,
-                required_level,
-                item_guid,
-                bag_slot,
-                &mut equip_errors,
-                &mut pending_item_ops,
-                &mut lock_transitions,
-                &mut loot_latch,
-            ),
-            SessionEvent::Chat(m) => {
-                chat::chat(m, &mut chat_log, &social, &net_commands, &mut server_said)
-            }
-            SessionEvent::ChannelNotify {
-                notice,
-                channel,
-                tail,
-            } => chat_log.push_channel_notice(notice, channel, &tail),
-            SessionEvent::ChannelList {
-                channel, members, ..
-            } => chat::channel_list(channel, &members, &mut chat_log),
-            SessionEvent::ChatPlayerNotFound { name } => {
-                chat::chat_player_not_found(&name, &mut ui_error_keys)
-            }
-            SessionEvent::ChatWrongFaction => chat::chat_wrong_faction(&mut ui_error_keys),
-            // The four world broadcasts — parked for `ui_chat::broadcast`'s resolve pass, which
-            // owns the AreaTable/ServerMessages lookups and the joined-defense-channel walk.
-            SessionEvent::ZoneUnderAttack { area_id } => chat::broadcast(
-                crate::ui_chat::Broadcast::ZoneUnderAttack { area_id },
-                &mut chat_log,
-            ),
-            SessionEvent::DefenseMessage { zone_id, text } => chat::broadcast(
-                crate::ui_chat::Broadcast::Defense { zone_id, text },
-                &mut chat_log,
-            ),
-            SessionEvent::ServerMessage { message_type, text } => chat::broadcast(
-                crate::ui_chat::Broadcast::Server { message_type, text },
-                &mut chat_log,
-            ),
-            SessionEvent::ChatRestricted => {
-                chat::broadcast(crate::ui_chat::Broadcast::ChatRestricted, &mut chat_log)
-            }
-            SessionEvent::Notification { text } => chat::notification(text, &mut ui_error_texts),
-            SessionEvent::AreaTriggerMessage { text } => {
-                chat::area_trigger_message(text, &mut ui_error_texts)
-            }
-            SessionEvent::PlayedTime { total, level } => {
-                // BOTH halves, and they are not redundant. The chat breakdown is our stand-in for
-                // the reference's `ChatFrame_DisplayTimePlayed`, which we do not ship; the mailbox
-                // is what becomes `TIME_PLAYED_MSG(total, level)` for an addon that asked.
-                played_time_answer.0 = Some((total, level));
-                chat::played_time(total, level, &mut chat_log)
-            }
-            SessionEvent::RandomRoll {
-                min,
-                max,
-                roll,
-                guid,
-            } => chat_log.push_roll(min, max, roll, guid),
-            // ── The group/party family (decision 0434 §D2, superseded by 0440) — arm bodies in
-            // `group` ──
-            SessionEvent::GroupInvite { inviter } => {
-                group::invited(&mut group, &mut ui_error_keys, &inviter)
-            }
-            SessionEvent::GroupDecline { name } => {
-                group::declined(&mut group, &mut ui_error_keys, &name)
-            }
-            SessionEvent::GroupUninvited => group::uninvited(&mut group, &mut ui_error_keys),
-            SessionEvent::GroupLeaderChanged { name } => group::leader_changed(
-                &mut group,
-                &mut ui_error_keys,
-                &name,
-                &self_guid,
-                &names,
-                &net_commands,
-            ),
-            SessionEvent::GroupDestroyed => group::destroyed(&mut group, &mut ui_error_keys),
-            SessionEvent::GroupList {
-                group_type,
-                own_flags,
-                members,
-                leader,
-                loot,
-            } => group::list(
-                &mut group,
-                &mut ui_error_keys,
-                &mut quest,
-                group_type,
-                own_flags,
-                members,
-                leader,
-                loot,
-                &names,
-                &index,
-                &net_commands,
-            ),
-            SessionEvent::PartyCommandResult {
-                operation,
-                member,
-                result,
-            } => group::command_result(&mut group, &mut ui_error_keys, operation, &member, result),
-            SessionEvent::PartyMemberStats { guid, full, info } => {
-                group.apply_stats(guid, full, *info)
-            }
-            SessionEvent::RaidTargetSet { icon, guid } => group.apply_raid_target(icon, guid),
-            SessionEvent::RaidTargetList { entries } => group.apply_raid_target_list(&entries),
-            // The ready check (decision 1549, completed by 1989): the open form takes the
-            // leader arm or the popup arm by our guid; the ANSWER form — forwarded to the leader
-            // alone — is logged for the engine's flags, which the timeout tick sums up after 30 s
-            // (1.12 has no per-member answer surface, only the AFK summary line).
-            SessionEvent::ReadyCheckRequest => {
-                group::ready_check_request(&mut group, &mut ui_error_keys, &self_guid)
-            }
-            SessionEvent::RaidInstanceInfo { entries } => group.apply_raid_instance_info(entries),
-            // 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. `map` is the map we are standing on: 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.
-            SessionEvent::MinimapPing { guid, x, y } => {
-                ping.seat((x, y), guid);
-            }
-            SessionEvent::ReadyCheckAnswer { guid, ready } => {
-                group.apply_ready_check_answer(guid, ready != 0)
-            }
-            // ── The duel family (decision 0633): the session mirror + the two DisplayError
-            // lines the handlers emit inline; the Era events fire off the mirror's edges in
-            // `ui_duel::feed_duel`, and the countdown ticks in its own system ──
-            SessionEvent::DuelRequested {
-                arbiter,
-                challenger,
-            } => crate::ui_duel::apply::requested(
-                &mut duel,
-                &mut ui_error_keys,
-                &net_commands,
-                arbiter,
-                challenger,
-                self_guid.0,
-                social.is_ignored(challenger),
-            ),
-            // ── The instance/raid lockout family (decision 1748): four lines the client
-            // composes itself out of GlobalStrings, and the two-packet latch behind the SELF
-            // menu's reset row. The lines are QUEUED — resolving them needs the VM, which this
-            // drain has no access to (decision 0669's split) ──
-            SessionEvent::RaidInstanceMessage { message } => {
-                crate::ui_instance::apply::raid_instance_message(&mut instances, message);
-            }
-            SessionEvent::InstanceSaveCreated { flag } => {
-                crate::ui_instance::apply::instance_save_created(&mut instances, flag);
-            }
-            SessionEvent::InstanceReset { map } => {
-                crate::ui_instance::apply::instance_reset(&mut instances, map);
-            }
-            SessionEvent::InstanceResetFailed { failure } => {
-                crate::ui_instance::apply::instance_reset_failed(&mut instances, failure);
-            }
-            SessionEvent::UpdateLastInstance { map } => {
-                crate::ui_instance::apply::update_last_instance(&mut instances, map);
-            }
-            SessionEvent::UpdateInstanceOwnership { owns } => {
-                crate::ui_instance::apply::update_instance_ownership(&mut instances, owns);
-            }
-            SessionEvent::DuelOutOfBounds => crate::ui_duel::apply::bounds(&mut duel, true),
-            SessionEvent::DuelInBounds => crate::ui_duel::apply::bounds(&mut duel, false),
-            SessionEvent::DuelComplete { started } => {
-                crate::ui_duel::apply::complete(&mut duel, &mut ui_error_keys, started);
-            }
-            SessionEvent::DuelWinner {
-                fled,
-                winner,
-                loser,
-            } => crate::ui_duel::apply::winner(&mut duel, fled, &winner, &loser),
-            SessionEvent::DuelCountdown { seconds } => {
-                crate::ui_duel::apply::countdown(&mut duel, seconds);
-            }
-            // ── The mirror timers (decision 0874): breath / fatigue / feign-death. Pure queue
-            // arms — every meaning (which bar, what colour, what caption, how fast it drains)
-            // is resolved at the UI seam in `ui_mirror`, and the countdown itself is the
-            // FrameXML's own OnUpdate integration ──────────────────────────────────────────────
-            SessionEvent::MirrorTimerStart(start) => mirror_timers
-                .0
-                .push(crate::ui_mirror::MirrorTimerEdge::Start(start)),
-            SessionEvent::MirrorTimerPause { kind, paused } => mirror_timers
-                .0
-                .push(crate::ui_mirror::MirrorTimerEdge::Pause { kind, paused }),
-            SessionEvent::MirrorTimerStop { kind } => mirror_timers
-                .0
-                .push(crate::ui_mirror::MirrorTimerEdge::Stop { kind }),
-            // ── The social family (decision 0668): the friend/ignore lists, the `/who`
-            // answer, and the result codes that print their own chat lines. The lines and the
-            // Era events fire off the mirror in `ui_social::feed_social` — every one of them
-            // needs a NAME the drain has no cache handle for.
-            SessionEvent::FriendList { friends } => {
-                crate::ui_social::apply::friend_list(&mut social, friends)
-            }
-            SessionEvent::IgnoreList { guids } => {
-                crate::ui_social::apply::ignore_list(&mut social, guids)
-            }
-            SessionEvent::FriendStatus(update) => {
-                crate::ui_social::apply::friend_status(&mut social, update)
-            }
-            SessionEvent::WhoResults(results) => crate::ui_social::apply::who(&mut social, results),
-            // ── The guild family (decision 1257): the identity cache, the roster, and the
-            // `ERR_GUILD_*` lines the engine composes. Every arm's law lives in
-            // `ui_guild::apply` beside the state it drives; the guild EVENTS fire off the mirror
-            // in `ui_guild::feed_guild`, on their edges.
-            SessionEvent::GuildQueryResponse(response) => {
-                crate::ui_guild::apply::query_response(&mut guild, response)
-            }
-            SessionEvent::GuildRoster(roster) => crate::ui_guild::apply::roster(&mut guild, roster),
-            // The sign-on/sign-off pair's trailing guid exists for exactly one purpose — the
-            // four-conjunct display condition on their line — which is why this arm reads
-            // `social`, the notify knob and our own guid (decision 1589; the condition and its
-            // byte addresses are on `ui_guild::apply::event`).
-            SessionEvent::GuildEvent(notice) => crate::ui_guild::apply::event(
-                &mut guild,
-                &mut ui_error_keys,
-                &social,
-                &guild_notify,
-                self_guid.0,
-                notice,
-            ),
-            SessionEvent::GuildCommandResult(result) => {
-                crate::ui_guild::apply::command_result(&mut guild, &mut ui_error_keys, result)
-            }
-            SessionEvent::GuildInvite { inviter, guild: g } => {
-                crate::ui_guild::apply::invite(&mut guild, &mut ui_error_keys, inviter, g)
-            }
-            SessionEvent::GuildDecline { name } => {
-                crate::ui_guild::apply::decline(&mut ui_error_keys, &name)
-            }
-            SessionEvent::GuildInfo(info) => crate::ui_guild::apply::info(&mut guild, info),
-            // ── The petition family (decision 1672): founding a guild. The registrar half is an
-            // NPC window, the charter half is item-bound, and they are two resources for that
-            // reason — see `ui_petition`'s module doc.
-            SessionEvent::PetitionShowList(list) => {
-                // The registrar's two `UNIT_NPC_FLAGS` gates are on LIVE NPC state rather than on
-                // the packet, so the flags are read here — this pass holds the store. An unstreamed
-                // guid reads `None` and fails the gate, as the client's own resolve does.
-                let flags = index
-                    .0
-                    .get(&list.npc)
-                    .and_then(|e| stores.get(*e).ok())
-                    .map(|s| s.0.unit_npc_flags());
-                crate::ui_petition::apply::show_list(&mut registrar, list, flags)
-            }
-            SessionEvent::PetitionShowSignatures(sigs) => {
-                // An ignored owner suppresses the ENTIRE update — no record fetch, no list, no
-                // event, no error line (`0x5eeefe`). Consulted before anything else happens.
-                let ignored = social.is_ignored(sigs.owner);
-                crate::ui_petition::apply::show_signatures(
-                    &mut petition,
-                    sigs,
-                    ignored,
-                    &net_commands,
-                )
-            }
-            SessionEvent::PetitionQueryResponse(response) => {
-                crate::ui_petition::apply::query_response(&mut petition, response)
-            }
-            SessionEvent::PetitionSignResults(results) => crate::ui_petition::apply::sign_results(
-                &mut petition,
-                &names,
-                self_guid.0.unwrap_or(0),
-                results,
-                &net_commands,
-            ),
-            SessionEvent::TurnInPetitionResults { result } => {
-                crate::ui_petition::apply::turn_in_results(&mut petition, &mut registrar, result)
-            }
-            SessionEvent::PetitionDeclined { player } => {
-                crate::ui_petition::apply::declined(&mut petition, &names, player)
-            }
-            SessionEvent::PetitionRenamed(rename) => {
-                crate::ui_petition::apply::renamed(&mut petition, rename)
-            }
-            SessionEvent::LootResponse {
-                guid,
-                loot_type,
-                gold,
-                items,
-            } => loot_response(
-                guid,
-                loot_type,
-                gold,
-                items,
-                &mut loot,
-                &mut loot_latch,
-                &net_commands,
-            ),
-            SessionEvent::LootError { guid, error } => {
-                loot_error(guid, error, &mut ui_error_keys, &mut loot_latch)
-            }
-            SessionEvent::LootRemoved { slot } => loot_removed(slot, &mut loot),
-            SessionEvent::LootMoneyNotify { amount } => loot_money_notify(amount),
-            SessionEvent::LootClearMoney => loot_clear_money(&mut loot),
-            SessionEvent::LootReleaseResponse { guid } => {
-                loot_release_response(guid, &mut loot, &mut loot_latch)
-            }
-            SessionEvent::ItemPushResult(p) => {
-                item_push_result(p, &self_guid, &mut loot, &mut tutorials)
-            }
-            // ── The group-loot roll family (decision 0591) — the GroupLootFrame feed ───────────
-            SessionEvent::LootStartRoll(p) => loot_start_roll(p, &mut loot_rolls),
-            SessionEvent::LootRoll(p) => loot_roll(p, &mut loot_rolls),
-            SessionEvent::LootRollWon(p) => loot_roll_won(p, &mut loot_rolls),
-            SessionEvent::LootAllPassed(p) => loot_all_passed(p, &mut loot_rolls),
-            // ── Master loot (decision 1675) — the candidate list, ahead of its LootResponse ───
-            SessionEvent::LootMasterList { candidates } => loot_master_list(candidates, &mut loot),
-            // ── The death arc (decision 0308) — arm bodies in `death` ─────────────────────────
-            SessionEvent::CorpseQuery {
-                found,
-                display_map,
-                position,
-                corpse_map,
-            } => death::corpse_query(found, display_map, position, corpse_map, &mut death_net),
-            SessionEvent::CorpseReclaimDelay { delay_ms } => {
-                death::corpse_reclaim_delay(delay_ms, real_clock.elapsed_secs_f64(), &mut death_net)
-            }
-            SessionEvent::ResurrectRequest {
-                caster,
-                name,
-                sickness,
-                has_timer,
-            } => death::resurrect_request(caster, name, sickness, has_timer, &mut death_net),
-            SessionEvent::SpiritHealerConfirm { npc } => {
-                death::spirit_healer_confirm(npc, &mut death_net)
-            }
-            SessionEvent::DurabilityDamageDeath => death::durability_damage_death(&mut chat_log),
-            SessionEvent::MoveMode {
-                guid,
-                counter,
-                mode,
-                apply,
-            } => death::move_mode(
-                guid,
-                counter,
-                mode,
-                apply,
-                &self_guid,
-                &mut death_net,
-                &mut move_modes,
-            ),
-            // ── The observer movement-mode family (decision 1780) — the same modes, on a body
-            //    somebody else is driving. No ack, so this arm ends the packet.
-            SessionEvent::SplineMoveMode { guid, mode, apply } => objects::spline_move_mode(
-                guid,
-                mode,
-                apply,
-                &mut commands,
-                &index,
-                &mut unit_modes,
-                &mut remote_motion,
-                &mut staged_modes,
-            ),
-            SessionEvent::KnockBack {
-                guid,
-                counter,
-                launch,
-            } => session::knock_back(guid, counter, launch, &self_guid, &mut knockbacks),
-            SessionEvent::ItemTemplate { entry, info } => {
-                item_template(entry, info.map(|b| *b), &mut items)
-            }
-            SessionEvent::AttackStart { attacker, victim } => {
-                combat::attack_start(attacker, victim, &mut commands, &index)
-            }
-            SessionEvent::AttackStop { attacker, victim } => {
-                combat::attack_stop(attacker, victim, &mut commands, &index, &mut swing_flushes)
-            }
-            SessionEvent::AiReaction { unit, reaction } => {
-                combat::ai_reaction(unit, reaction, &index, &mut ai_reactions)
-            }
-            SessionEvent::AttackerState(s) => {
-                combat_chat::attacker_state(s, &chat_ctx!(), &stores, &transforms, &mut chat_log);
-                combat::attacker_state(
-                    s,
-                    &index,
-                    &self_guid,
-                    &mut swings,
-                    &mut swing_impacts,
-                    &mut combat_text_events,
-                    &mut sheath_requests,
-                    &mut swing_refusal_edges,
-                    &stores,
-                    play_seq.next(),
-                )
-            }
-            SessionEvent::AttackSwingError(e) => {
-                combat::attack_swing_error(e, &mut swing_refusal_edges)
-            }
-            SessionEvent::CancelCombat => combat::cancel_combat(&mut swing_refusal_edges),
-            SessionEvent::FeignDeathResisted => combat::feign_death_resisted(&mut ui_error_keys),
-            SessionEvent::SpellDamageLog(s) => {
-                combat_chat::spell_damage_log(s, &chat_ctx!(), &stores, &transforms, &mut chat_log);
-                combat_log::spell_damage_log(
-                    s,
-                    &index,
-                    &self_guid,
-                    &stores,
-                    spell_catalog.as_deref(),
-                    *combat_cvars.damage_text,
-                    &mut combat_text_spawns,
-                    &mut unit_combat_feedback,
-                    &mut combat_text_events,
-                )
-            }
-            SessionEvent::PeriodicAuraLog(s) => {
-                // **`CombatLogPeriodicSpells` gates the WHOLE packet body, and this arm 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 half below would model it as two filters; it is one gate over both.
-                if !combat_cvars.periodic.0 {
-                    continue;
-                }
-                combat_chat::periodic_aura_log(
-                    &s,
-                    &chat_ctx!(),
-                    &stores,
-                    &transforms,
-                    &mut chat_log,
-                );
-                combat_log::periodic_aura_log(
-                    s,
-                    &index,
-                    &self_guid,
-                    &stores,
-                    spell_catalog.as_deref(),
-                    *combat_cvars.damage_text,
-                    &mut combat_text_spawns,
-                    &mut unit_combat_feedback,
-                    &mut combat_text_events,
-                    &names,
-                    &net_commands,
-                )
-            }
-            SessionEvent::SpellHealLog(s) => {
-                combat_chat::spell_heal_log(s, &chat_ctx!(), &stores, &transforms, &mut chat_log);
-                combat_log::spell_heal_log(
-                    s,
-                    &index,
-                    &self_guid,
-                    &mut unit_combat_feedback,
-                    &mut combat_text_events,
-                    &names,
-                    &net_commands,
-                )
-            }
-            SessionEvent::SpellEnergizeLog(s) => {
-                combat_chat::spell_energize_log(
-                    s,
-                    &chat_ctx!(),
-                    &stores,
-                    &transforms,
-                    &mut chat_log,
-                );
-                combat_log::spell_energize_log(s, &self_guid, &mut combat_text_events)
-            }
-            SessionEvent::DamageShield(s) => {
-                combat_chat::damage_shield(s, &chat_ctx!(), &stores, &transforms, &mut chat_log);
-                combat_log::damage_shield(
-                    s,
-                    &index,
-                    &self_guid,
-                    &stores,
-                    *combat_cvars.damage_text,
-                    &mut combat_text_spawns,
-                    &mut unit_combat_feedback,
-                )
-            }
-            SessionEvent::SpellLogMiss(s) => {
-                combat_chat::spell_log_miss(&s, &chat_ctx!(), &stores, &transforms, &mut chat_log);
-                combat_log::spell_log_miss(
-                    s,
-                    &index,
-                    &self_guid,
-                    &stores,
-                    spell_catalog.as_deref(),
-                    *combat_cvars.damage_text,
-                    &mut combat_text_spawns,
-                    &mut unit_combat_feedback,
-                    &mut combat_text_events,
-                )
-            }
-            // ── 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 twin to call.
-            SessionEvent::PartyKillLog(k) => {
-                combat_chat::party_kill_log(k, &chat_ctx!(), &stores, &transforms, &mut chat_log)
-            }
-            SessionEvent::SpellInstaKillLog(k) => combat_chat::spell_insta_kill_log(
-                k,
-                &chat_ctx!(),
-                &stores,
-                &transforms,
-                &mut chat_log,
-            ),
-            SessionEvent::ProcResist(o) => combat_chat::spell_outcome_log(
-                o,
-                false,
-                &chat_ctx!(),
-                &stores,
-                &transforms,
-                &mut chat_log,
-            ),
-            SessionEvent::SpellOrDamageImmune(o) => combat_chat::spell_outcome_log(
-                o,
-                true,
-                &chat_ctx!(),
-                &stores,
-                &transforms,
-                &mut chat_log,
-            ),
-            SessionEvent::SpellDispelLog(d) => {
-                combat_chat::spell_dispel_log(&d, &chat_ctx!(), &stores, &transforms, &mut chat_log)
-            }
-            SessionEvent::DispelFailed(d) => {
-                combat_chat::dispel_failed(&d, &chat_ctx!(), &stores, &transforms, &mut chat_log)
-            }
-            SessionEvent::EnchantmentLog(e) => {
-                combat_chat::enchantment_log(e, &chat_ctx!(), &stores, &transforms, &mut chat_log)
-            }
-            SessionEvent::SpellLogExecute(x) => combat_chat::spell_log_execute(
-                &x,
-                &chat_ctx!(),
-                &stores,
-                &transforms,
-                &mut chat_log,
-            ),
-            SessionEvent::XpGain(x) => combat_log::xp_gain(
-                x,
-                &index,
-                &self_guid,
-                &mut combat_text_spawns,
-                &mut chat_log,
-            ),
-            SessionEvent::ExplorationXp(x) => combat_log::exploration_xp(
-                x,
-                area_table.as_deref(),
-                exploration_sounds.as_deref(),
-                &index,
-                &self_guid,
-                &stores,
-                &mut server_sounds,
-                &mut chat_log,
-            ),
-            SessionEvent::LevelUp(l) => combat_log::level_up(l, &mut chat_log),
-            SessionEvent::SpellStart {
-                caster,
-                spell_id,
-                cast_flags,
-                cast_time_ms,
-                target,
-                ammo_display_id,
-            } => spell_start(
-                caster,
-                spell_id,
-                cast_flags,
-                cast_time_ms,
-                target,
-                ammo_display_id,
-                &mut commands,
-                &index,
-                &mut cast_events,
-                &self_guid,
-                &mut cast_bar,
-                &mut pending_cast,
-                spell_catalog.as_deref(),
-                play_seq.next(),
-            ),
-            SessionEvent::SpellGo {
-                caster,
-                spell_id,
-                cast_flags,
-                hits,
-                misses,
-                target,
-                go_target,
-                dest,
-                ammo_display_id,
-                item_caster,
-            } => spell_go(
-                caster,
-                spell_id,
-                cast_flags,
-                hits,
-                misses,
-                target,
-                go_target,
-                dest,
-                ammo_display_id,
-                item_caster,
-                &mut commands,
-                &index,
-                &casting_units,
-                &mut cast_events,
-                &mut spell_go_targets,
-                &self_guid,
-                &stores,
-                &mut cast_bar,
-                &mut pending_cast,
-                &mut queued_melee,
-                &mut combat_text_spawns,
-                *combat_cvars.damage_text,
-                &mut go_lid_opens,
-                &mut loot_latch,
-                (
-                    &mut cooldown_store,
-                    spell_catalog.as_deref(),
-                    &mut items,
-                    &net_commands,
-                    &mut pet_bar,
-                ),
-                (
-                    &mut auto_repeat,
-                    &mut sheath_requests,
-                    !engaged_self.is_empty(),
-                ),
-                play_seq.next(),
-            ),
-            SessionEvent::SpellChainTargets {
-                caster,
-                spell_id,
-                targets,
-            } => spell_chain_targets(caster, spell_id, targets, &mut commands, &index),
-            SessionEvent::SpellFailedOther { caster, spell_id } => spell_failed_other(
-                caster,
-                spell_id,
-                &mut commands,
-                &index,
-                &casting_units,
-                &mut cast_events,
-                &self_guid,
-                &mut cast_bar,
-                &mut pending_cast,
-                &mut queued_melee,
-                play_seq.next(),
-            ),
-            SessionEvent::SpellDelayed { caster, delay_ms } => spell_delayed(
-                caster,
-                delay_ms,
-                &self_guid,
-                &mut cast_bar,
-                &mut pending_cast,
-            ),
-            SessionEvent::CancelAutoRepeat => cancel_auto_repeat(
-                &mut auto_repeat,
-                &self_guid,
-                &index,
-                &mut commands,
-                &net_commands,
-            ),
-            SessionEvent::SpellCooldowns { caster, cooldowns } => {
-                if let Some(store) =
-                    addressed_store(caster, &self_guid, &mut cooldown_store, &mut pet_bar)
-                {
-                    spell_cooldowns(caster, cooldowns, spell_catalog.as_deref(), store);
-                }
-            }
-            SessionEvent::ItemCooldown {
-                item_guid,
-                spell_id,
-            } => item_cooldown(item_guid, spell_id, &items, &mut cooldown_store),
-            // The item-lifetime countdown's ONLY feed (decision 1933): park the deadline on the
-            // item store, exactly as the enchant timer below does — vmangos's own writer says the
-            // `ITEM_FIELD_DURATION` field the client also holds is not what it displays from.
-            SessionEvent::ItemTime { item_guid, seconds } => {
-                items.set_item_duration(item_guid, seconds)
-            }
-            // The temporary-enchant countdown's ONLY feed (decision 0920): park the deadline on the
-            // item store, which every tooltip surface reads back through `enchant_remaining_ms`.
-            SessionEvent::ItemEnchantTime {
-                item_guid,
-                slot,
-                seconds,
-            } => items.set_enchant_deadline(item_guid, slot, seconds),
-            SessionEvent::CooldownEvent { spell_id, caster } => {
-                if let Some(store) =
-                    addressed_store(caster, &self_guid, &mut cooldown_store, &mut pet_bar)
-                {
-                    cooldown_event(spell_id, caster, store);
-                }
-            }
-            SessionEvent::ClearCooldown { spell_id, caster } => {
-                if let Some(store) =
-                    addressed_store(caster, &self_guid, &mut cooldown_store, &mut pet_bar)
-                {
-                    clear_cooldown(spell_id, caster, store);
-                }
-            }
-            SessionEvent::CooldownCheat { caster } => {
-                if let Some(store) =
-                    addressed_store(caster, &self_guid, &mut cooldown_store, &mut pet_bar)
-                {
-                    cooldown_cheat(caster, store);
-                }
-            }
-            // The pet action bar (decision 0982) — server-authoritative, so PET_SPELLS is a
-            // wholesale replace and its zero-guid form is the teardown.
-            SessionEvent::PetSpells(spells) => {
-                pet::pet_spells(*spells, spell_catalog.as_deref(), &mut pet_bar)
-            }
-            SessionEvent::PetMode(mode) => pet::pet_mode(mode, &mut pet_bar),
-            SessionEvent::PetActionFeedback { reason } => {
-                pet::pet_action_feedback(reason, &mut ui_error_keys)
-            }
-            SessionEvent::PetCastFailed { spell_id, reason } => {
-                pet::pet_cast_failed(spell_id, reason, &mut cast_errors)
-            }
-            // The three pet-feedback arms and the pet's voice (decision 2039). Each was
-            // name-table-only until then; each is something the reference visibly does.
-            SessionEvent::PetTameFailure { reason } => {
-                pet::pet_tame_failure(reason, &mut pet_tame_failures)
-            }
-            SessionEvent::PetNameInvalid => pet::pet_name_invalid(&mut ui_error_keys),
-            SessionEvent::PetBroken => pet::pet_broken(&mut ui_error_keys),
-            SessionEvent::PetActionSound { pet_guid, talk } => {
-                pet::pet_action_sound(pet_guid, talk, &index, &mut pet_talks)
-            }
-            SessionEvent::PetDismissSound { model_id, position } => {
-                pet::pet_dismiss_sound(model_id, position, &mut pet_dismiss_sounds)
-            }
-            SessionEvent::ChannelStart {
-                spell_id,
-                duration_ms,
-            } => channel_start(spell_id, duration_ms, &mut active_channel, &mut cast_bar),
-            SessionEvent::ChannelUpdate { remaining_ms } => {
-                channel_update(remaining_ms, &mut active_channel, &mut cast_bar)
-            }
-            SessionEvent::AuraDuration { slot, remaining_ms } => aura_duration(
-                slot,
-                remaining_ms,
-                &mut aura_durations,
-                real_clock.elapsed_secs_f64(),
-            ),
-            SessionEvent::SpellModifier {
-                flat,
-                mask_bit,
-                op,
-                value,
-            } => set_spell_modifier(flat, mask_bit, op, value, &mut spell_mods),
-            SessionEvent::PlaySpellVisual { unit, kit_id } => {
-                anim::play_spell_visual(unit, kit_id, &index, play_seq, &mut kit_pushes)
-            }
-            SessionEvent::EnvironmentalDamageLog(e) => {
-                combat_chat::environmental_damage_log(
-                    e,
-                    &chat_ctx!(),
-                    &stores,
-                    &transforms,
-                    &mut chat_log,
-                );
-                anim::environmental_damage_log(
-                    e,
-                    &index,
-                    env_damage_table.as_deref(),
-                    play_seq,
-                    &mut kit_pushes,
-                )
-            }
-            // The gossip/vendor/trainer NPC-interaction family — arm bodies in `npc`.
-            SessionEvent::GossipMenu {
-                npc,
-                text_id,
-                options,
-                quests,
-            } => npc::gossip_menu(
-                npc,
-                text_id,
-                options,
-                quests,
-                &mut gossip,
-                &net_commands,
-                &index,
-                &stores,
-            ),
-            SessionEvent::NpcGreeting { text_id, blocks } => {
-                npc::npc_greeting(text_id, blocks, &mut gossip, &index, &stores)
-            }
-            SessionEvent::GossipComplete => npc::gossip_complete(&mut gossip, &mut quest),
-            SessionEvent::GossipPoi(poi) => npc::gossip_poi(
-                &poi,
-                &mut poi_marker,
-                current_map.as_ref().map_or(0, |m| m.0),
-                real_clock.elapsed_secs_f64(),
-            ),
-            // Questgiver panels (decision 0088): fill the `QuestGiver` the quest feed
-            // (`crate::ui_quest`) reads. Each panel packet replaces the open view; the greeting/gossip
-            // quest-row clicks and the panel buttons flow back out through the quest/gossip drains.
-            SessionEvent::QuestGiverStatus { npc, status } => {
-                quest_giver_status(npc, status, &mut quest)
-            }
-            SessionEvent::QuestGreeting(list) => quest_greeting(list, &mut quest),
-            SessionEvent::QuestDetail(d) => quest_detail(d, &mut quest, &net_commands),
-            SessionEvent::QuestProgress(p) => quest_progress(p, &mut quest),
-            SessionEvent::QuestOffer(o) => quest_offer(o, &mut quest),
-            SessionEvent::QuestComplete(c) => quest_complete(c, &mut quest),
-            // Quest log (decision 0088's deferred second slice): the full template feeds the log
-            // window's ask-once detail cache; the `SMSG_QUESTUPDATE_*` toasts have no dedicated
-            // window of their own on this server (no ErrorsFrame-style transient panel yet), so they
-            // route through the chat window's system-line seam ([`crate::ui_chat::ChatLog`]) — the
-            // same seam the loot feed's refusal/receive lines use — colored SYSTEM yellow, the
-            // GM-feedback color.
-            SessionEvent::QuestTemplate(t) => quest_template(t, &mut quest_log),
-            SessionEvent::QuestObjectiveKill {
-                quest_id: _,
-                entry,
-                count,
-                required,
-            } => quest_objective_kill(entry, count, required, &mut quest),
-            SessionEvent::QuestObjectiveItem { item_id, count } => {
-                quest_objective_item(item_id, count, &mut quest)
-            }
-            SessionEvent::QuestObjectivesComplete { quest_id } => {
-                quest_objectives_complete(quest_id, &mut quest)
-            }
-            SessionEvent::QuestFailed { quest_id, timed } => {
-                quest_failed(quest_id, timed, &mut quest_log, &net_commands, &mut quest)
-            }
-            SessionEvent::QuestLogFull => quest_log_full(&mut quest),
-            // The party quest-share (decision 1733): one member's verdict on a quest we pushed,
-            // and the escort-quest confirm. Both park in `QuestShare` for `crate::ui_quest_share`
-            // to name and raise — the guid needs a name query the apply pass has no VM to await.
-            SessionEvent::QuestPushResult { member, msg } => {
-                quest_push_result(member, msg, &mut quest_share)
-            }
-            SessionEvent::QuestConfirmAccept(c) => quest_confirm_accept(c, &mut quest_share),
-            SessionEvent::QuestGiverInvalid { reason } => quest_giver_invalid(reason, &mut quest),
-            SessionEvent::QuestGiverFailed { quest_id, reason } => {
-                quest_giver_failed(quest_id, reason, &mut quest, &mut quest_log, &net_commands)
-            }
-            SessionEvent::VendorInventory { vendor, items } => {
-                npc::vendor_inventory(vendor, items, &mut merchant)
-            }
-            SessionEvent::ShowBank { banker } => {
-                npc::show_bank(banker, &mut bank_open, &mut gossip, &mut quest)
-            }
-            SessionEvent::BuyBankSlotResult { result } => {
-                npc::bank_buy_slot_result(result, &mut bank_errors)
-            }
-            SessionEvent::TrainerList {
-                trainer,
-                trainer_type,
-                services,
-                greeting,
-            } => npc::trainer_list(trainer, trainer_type, services, greeting, &mut trainer_open),
-            SessionEvent::TrainerBuySucceeded { trainer, spell_id } => {
-                npc::trainer_buy_succeeded(trainer, spell_id, &mut trainer_open, &net_commands)
-            }
-            SessionEvent::TrainerBuyFailed { error, .. } => {
-                npc::trainer_buy_failed(error, &mut trainer_errors)
-            }
-            SessionEvent::InvalidatePlayer { guid } => names::invalidate_player(guid, &mut names),
-            SessionEvent::ListStabledPets {
-                npc,
-                num_stable_slots,
-                pets,
-            } => npc::list_stabled_pets(npc, num_stable_slots, pets, &mut stable_open, &mut names),
-            SessionEvent::StableResult { result } => {
-                npc::stable_result(result, &mut stable_open, &mut stable_errors, &net_commands)
-            }
-            SessionEvent::TaxiNodesShown {
-                flightmaster,
-                nearest_node,
-                known_mask,
-            } => npc::taxi_nodes_shown(flightmaster, nearest_node, known_mask, &mut taxi),
-            SessionEvent::TaxiNodeStatus { guid, known } => {
-                npc::taxi_node_status(guid, known, &mut commands, &index)
-            }
-            SessionEvent::ActivateTaxiReply { code } => npc::taxi_activate_reply(code, &mut taxi),
-            SessionEvent::NewTaxiPath => npc::taxi_new_path(&mut taxi),
-            SessionEvent::VendorBuyResult {
-                vendor,
-                slot,
-                new_count,
-                ..
-            } => npc::vendor_buy_result(vendor, slot, new_count, &mut merchant),
-            SessionEvent::VendorBuyFailed {
-                vendor,
-                item_entry,
-                reason,
-            } => npc::vendor_buy_failed(
-                vendor,
-                item_entry,
-                reason,
-                &mut merchant,
-                &mut merchant_errors,
-            ),
-            SessionEvent::VendorSellFailed { reason, .. } => {
-                npc::vendor_sell_failed(reason, &mut merchant_errors)
-            }
-            SessionEvent::ForceSpeedChange {
-                guid,
-                kind,
-                counter,
-                speed,
-            } => objects::force_speed_change(
-                guid,
-                kind,
-                counter,
-                speed,
-                &index,
-                &unit_speeds,
-                &mut speed_stage,
-                &self_guid,
-                &mut speed_changes,
-            ),
-            SessionEvent::SpeedChanged { guid, kind, speed } => {
-                objects::speed_changed(guid, kind, speed, &index, &unit_speeds, &mut speed_stage)
-            }
-            // ── The mount arc (decision 0441) — arm bodies in `mount` ─────────────────────────
-            SessionEvent::MountResult { mount, code } => {
-                mount::mount_result(mount, code, &mut mount_errors)
-            }
-            SessionEvent::MountSpecial { guid } => {
-                mount::mount_special(guid, &self_guid, &index, &mut mount_flourishes)
-            }
-            // Possession's control half (B211). Forwarded whole and unjudged: the guid may name us
-            // (a revoke) or somebody else (a grant), and only the controller can act on either —
-            // it owns the pose to park and the mover claim to send.
-            SessionEvent::ClientControl { mover, allow_move } => {
-                client_control.write(super::ClientControlMessage { mover, allow_move });
-            }
-            // **The pong never gets here** — the read thread measures it against the ping clock
-            // the instant it lands and stops it, the way the reference's `OnData 0x537b10` hands
-            // `SMSG_PONG` to `HandlePong 0x537d60` inline instead of queueing it (`net::io`).
-            // Reaching this arm means that bypass was undone and every latency reading is a
-            // client frame too slow again, which is B346 exactly — so it says so out loud rather
-            // than measuring here and hiding it.
-            SessionEvent::Pong { sequence } => {
-                warn!("net: pong seq={sequence} reached the drain — the read thread's RTT bypass is gone (B346)");
-            }
-            SessionEvent::PacketDropped {
-                opcode,
-                unparseable,
-            } => session::packet_dropped(opcode, unparseable, &mut dropped),
-            // The mail arc (decision 0544 P1/P2/P3): the inbox/body/send-result arms fill the
-            // mailbox session the feed reads (`crate::ui_mail`); the arrival pair feeds
-            // `MailPending` (`HasNewMail()`/the minimap icon).
-            SessionEvent::MailList { mails } => {
-                mail::mail_list(mails, &mut mail_open, &net_commands)
-            }
-            SessionEvent::SendMailResult {
-                mail_id,
-                action,
-                error,
-                equip_error,
-                item,
-            } => mail::send_mail_result(
-                mail_id,
-                action,
-                error,
-                equip_error,
-                item,
-                &mut mail_open,
-                &net_commands,
-                &mut equip_errors,
-            ),
-            SessionEvent::MailItemText { text_id, text } => {
-                mail::mail_item_text(text_id, text, &mut mail_open)
-            }
-            // The book-page cache (decision 1105) — one page per packet, the whole chain in
-            // answer to the first ask; the reader repaints off it on the next feed.
-            SessionEvent::PageText {
-                page_id,
-                text,
-                next_page_id,
-            } => page_texts.insert(page_id, text, next_page_id),
-            SessionEvent::ReceivedMail { seconds } => {
-                mail::received_mail(seconds, &mut mail_pending, &mail_open, &net_commands)
-            }
-            SessionEvent::NextMailTime { seconds } => {
-                mail::next_mail_time(seconds, &mut mail_pending)
-            }
-            // The player-trade arc (decision 0592 P1): the status packet drives the open/accept/close
-            // state machine, the extended snapshot replaces one side's item/gold — both into the
-            // `TradeSession` the trade feed (`crate::ui_trade`) reads.
-            SessionEvent::TradeStatus { status } => trade::trade_status(
-                status,
-                &mut trade_session,
-                &mut ui_error_keys,
-                &net_commands,
-            ),
-            SessionEvent::TradeStatusExtended { state } => {
-                trade::trade_status_extended(&state, &mut trade_session)
-            }
-            SessionEvent::WorldStates { scope, states } => {
-                world::world_states(scope, states, &mut world_states)
-            }
-            // A kind with no arm here is one a subsystem has claimed in the handler table
-            // (decision 2305) — routed there by the drain, so it never reaches this match — or a
-            // new kind nobody handles, which `every_session_event_kind_has_one_owner` names at
-            // test time and this names at run time: the reference discards an unregistered
-            // opcode in silence; this client says so.
-            other => error!(
-                "net: {:?} reached the dispatch match with no arm — neither peeled nor handled",
-                benilla_protocol::SessionEventKind::from(&other)
-            ),
-        }
-    }
-    // Flush the staged descriptor seeds/deltas onto the entities born this drain (now spawned by the
-    // above Commands) — one insert each, fully merged, so no partial delta clobbers another.
-    for (guid, fields) in pending {
-        if let Some(&e) = index.0.get(&guid) {
-            commands.entity(e).insert(ObjectStore(fields));
-        }
-    }
-    // And the movers' speed sets, for the same reason (decision 1478) — one insert each, carrying
-    // the create block and every force-change this drain saw, folded in the order they arrived.
-    speed_stage.flush(&mut commands, &index);
+    super::handlers::dispatch(world, events);
 }
 
 /// Tag our own player's streamed entity with [`SelfPlayer`] once we know our guid — by matching the
diff --git a/crates/benilla-app/src/net/apply/anim.rs b/crates/benilla-app/src/net/apply/anim.rs
deleted file mode 100644
index 705b0027..00000000
--- a/crates/benilla-app/src/net/apply/anim.rs
+++ /dev/null
@@ -1,98 +0,0 @@
-//! "Play this on that unit" arm bodies for [`super::apply_net_updates`]'s dispatch match — the
-//! server packets whose whole content is *an animation to run on a streamed unit*: the two emote
-//! relays, the spell-visual kit push (decision 0280), and the environmental-damage kit (the
-//! fall-landing dust puff). Each resolves the guid through the index and writes one message; the
-//! animation law itself lives in [`crate::creature_anim`]. Each `pub(super)` fn here is exactly one
-//! arm's body; the match at the call site stays the dispatcher, one call per arm.
-
-use benilla_protocol::messages::EnvironmentalDamageLog;
-use bevy::prelude::*;
-
-use crate::creature_anim::{EnvDamageTable, KitPush, PlaySeq};
-
-use super::super::{EmoteKind, EmoteMessage, GuidIndex};
-
-/// `SMSG_TEXT_EMOTE` — someone performed a `/`-emote (the TextEmote.dbc id; the anim, if any, is
-/// the emote row's).
-///
-/// **Two consequences, and they are independent** (decision 1274): the anim + voice ride the
-/// [`EmoteMessage`] and need the performer *streamed*; the chat sentence is queued for
-/// [`crate::ui_chat`]'s composer and needs only the performer's *name*. An emote from someone
-/// off-screen therefore still prints its line, which is the reference's shape — `0x49dbe0`
-/// resolves a name and never touches the object manager.
-pub(super) fn text_emote(
-    guid: u64,
-    text_emote: u32,
-    target_name: String,
-    index: &GuidIndex,
-    out: &mut MessageWriter<EmoteMessage>,
-    chat_log: &mut crate::ui_chat::ChatLog,
-) {
-    out.write(EmoteMessage {
-        source: index.0.get(&guid).copied(),
-        kind: EmoteKind::Text(text_emote),
-    });
-    chat_log.push_text_emote(guid, text_emote, target_name);
-}
-
-/// `SMSG_EMOTE` — a bare Emotes.dbc anim id on a unit (the server-driven one-shot: NPC scripts,
-/// the `/`-emote's own anim leg).
-pub(super) fn emote(
-    guid: u64,
-    emote_id: u32,
-    index: &GuidIndex,
-    out: &mut MessageWriter<EmoteMessage>,
-) {
-    out.write(EmoteMessage {
-        source: index.0.get(&guid).copied(),
-        kind: EmoteKind::Anim(emote_id),
-    });
-}
-
-/// `SMSG_PLAY_SPELL_VISUAL` — the kit-push opcode (decision 0280): a stage-0 play on the unit, the
-/// eat/drink kit cadence and mid-channel swaps. Consumer: `creature_anim::spell_visual`. The
-/// [`PlaySeq`] stamp is taken only when the unit is streamed in, so an unstreamed guid never
-/// advances the call-order counter.
-pub(super) fn play_spell_visual(
-    unit: u64,
-    kit_id: u32,
-    index: &GuidIndex,
-    play_seq: &mut PlaySeq,
-    out: &mut MessageWriter<KitPush>,
-) {
-    if let Some(&e) = index.0.get(&unit) {
-        out.write(KitPush {
-            entity: e,
-            kit_id,
-            seq: play_seq.next(),
-        });
-    }
-}
-
-/// `SMSG_ENVIRONMENTALDAMAGELOG`'s consequence (wow-re `sound/scratch/uisound-tables.md`: reader
-/// `0x624fcc` inside `0x624f30`): the EnvironmentalDamage.dbc 6-slot table picks the damage type's
-/// SpellVisualKit — fall's is the DustCloud_Land puff — played on the victim through the ordinary
-/// discrete kit play (`0x60edf0`), the same leg the kit-push opcode rides. The pain vocal's exact
-/// trigger is a dispatched wow-re §5 (in flight) — it folds in as its own edge when the verdict
-/// lands.
-pub(super) fn environmental_damage_log(
-    e: EnvironmentalDamageLog,
-    index: &GuidIndex,
-    table: Option<&EnvDamageTable>,
-    play_seq: &mut PlaySeq,
-    out: &mut MessageWriter<KitPush>,
-) {
-    if let Some(&ent) = index.0.get(&e.victim) {
-        if let Some(kit_id) = table.and_then(|t| t.0.kit_id(e.damage_type)) {
-            debug!(
-                "net: environmental damage on {:#x} (type {}, {} dmg) → kit {kit_id}",
-                e.victim, e.damage_type, e.damage
-            );
-            out.write(KitPush {
-                entity: ent,
-                kit_id,
-                seq: play_seq.next(),
-            });
-        }
-    }
-}
diff --git a/crates/benilla-app/src/net/apply/combat.rs b/crates/benilla-app/src/net/apply/combat.rs
deleted file mode 100644
index 14648ace..00000000
--- a/crates/benilla-app/src/net/apply/combat.rs
+++ /dev/null
@@ -1,218 +0,0 @@
-//! Melee-engagement arm bodies for [`super::apply_net_updates`]'s dispatch match — the attack
-//! start/stop brackets, the aggro/alert flare, and the completed-swing record with its client-side
-//! full-block synthesis. Each `pub(super)` fn here is exactly one arm's body; the match at the
-//! call site stays the dispatcher, one call per arm.
-
-use benilla_protocol::messages::{AttackSwingError, AttackerState};
-use bevy::prelude::*;
-
-use crate::creature_anim::{
-    Engaged, RangedHold, SheathRequest, SwingFlush, SwingImpact, SwingMessage,
-};
-use crate::swing_refusal::SwingRefusalEdge;
-use crate::ui_action::{UiError, UiErrorKeys};
-use crate::ui_unit::CombatTextEvent;
-
-use super::super::{AiReactionMessage, GuidIndex, SelfGuid};
-
-/// A unit began melee auto-attack (`SMSG_ATTACKSTART`, including our own echo).
-pub(super) fn attack_start(attacker: u64, victim: u64, commands: &mut Commands, index: &GuidIndex) {
-    // Engagement brackets (decision 0073): the standing Ready idle rides this window —
-    // the client's gate is the auto-attack-target GUID being set, mirrored here as a
-    // marker component on the attacker (including our own echo).
-    debug!("net: attack start {attacker:#x} → {victim:#x}");
-    if let Some(&e) = index.0.get(&attacker) {
-        // Melee-start drops the `0x400` weapon-visual hold unconditionally (the client's
-        // `0x60fc50` sibling clear) — a shooter that closes to melee leaves the drawn idle.
-        // The LOCAL player's melee paths additionally run the full cancel funnel at send.
-        commands
-            .entity(e)
-            .insert(Engaged(victim))
-            .remove::<RangedHold>();
-    }
-}
-
-/// A unit stopped melee auto-attack (`SMSG_ATTACKSTOP`).
-pub(super) fn attack_stop(
-    attacker: u64,
-    victim: u64,
-    commands: &mut Commands,
-    index: &GuidIndex,
-    flushes: &mut MessageWriter<SwingFlush>,
-) {
-    debug!("net: attack stop {attacker:#x} → {victim:#x}");
-    if let Some(&e) = index.0.get(&attacker) {
-        commands.entity(e).remove::<Engaged>();
-        // The client's `0x624e40` (death/stun arrive as this packet too): a pending
-        // swing record flushes text-only and clears.
-        flushes.write(SwingFlush(e));
-    }
-}
-
-/// The server refused our melee swing (`SMSG_ATTACKSWING_NOTINRANGE`/`_BADFACING`/`_DEADTARGET`/
-/// `_CANT_ATTACK`) — forwarded verbatim to [`crate::swing_refusal`], which owns the latch, the 4 s
-/// repeat, and arm 4's silent StopAttack. Nothing is decided here: the arms differ only in what
-/// that module does with them, and it holds the write set for all three.
-pub(super) fn attack_swing_error(
-    error: AttackSwingError,
-    edges: &mut MessageWriter<SwingRefusalEdge>,
-) {
-    edges.write(SwingRefusalEdge::Refused(error));
-}
-
-/// `SMSG_CANCEL_COMBAT` — the server forced our attack to stop. The swing family's fourth arm,
-/// and the same act as `0x148`/`0x149`: the reference's handler `0x5e7dd0` is arm 4's body
-/// verbatim.
-pub(super) fn cancel_combat(edges: &mut MessageWriter<SwingRefusalEdge>) {
-    edges.write(SwingRefusalEdge::CombatCancelled);
-}
-
-/// `SMSG_FEIGN_DEATH_RESISTED` — the target shrugged off our Feign Death.
-///
-/// One red line and nothing else: the reference's handler `0x6e9800` is `push 0x1a5; call
-/// 0x496720`, a bare `DisplayError(421)` with no latch, no cooldown and no state — the opposite of
-/// its sibling above, and the reason the two do not share a path. Catalog row 421 is
-/// `ERR_FEIGN_DEATH_RESISTED`, whose 1.12 string is the single word "Resisted".
-///
-/// It lives beside the swing arms because vmangos sends it in the same breath as
-/// `SMSG_CANCEL_COMBAT` (`Objects/Unit.cpp:9445-9451`: a resisted feign death cancels the attack
-/// and says so), and finding one without the other is how this family stayed half-built.
-pub(super) fn feign_death_resisted(errors: &mut UiErrorKeys) {
-    debug!("net: feign death resisted");
-    errors.0.push(UiError::key("ERR_FEIGN_DEATH_RESISTED"));
-}
-
-/// A creature flared aggro or a stealth pre-aggro alert (`SMSG_AI_REACTION`).
-pub(super) fn ai_reaction(
-    unit: u64,
-    reaction: u32,
-    index: &GuidIndex,
-    reactions: &mut MessageWriter<AiReactionMessage>,
-) {
-    // Aggro (2 HOSTILE) / stealth alert (0 ALERT) flare — pure audio, byte-verified
-    // (`0x6056e0` is an exact two-way branch; any other value no-ops, and neither leg
-    // touches animation/nameplate/UI — decision 0280). Vocals: `sound::creature`.
-    debug!("net: ai reaction {reaction} on {unit:#x}");
-    if matches!(reaction, 0 | 2) {
-        if let Some(&e) = index.0.get(&unit) {
-            reactions.write(AiReactionMessage {
-                unit: e,
-                hostile: reaction == 2,
-            });
-        }
-    }
-}
-
-/// One completed melee swing (`SMSG_ATTACKERSTATEUPDATE`, decision 0073): the attacker's swing
-/// anim starts NOW; the victim feedback (blood/flinch/text/impact sounds) defers to the swing
-/// clip's attack-hit keyframe (`creature_anim::impact`, the client's `0x6247d0` router) — EXCEPT
-/// the center combat text, which the client fires **synchronously at packet parse**
-/// (`0x6255b0 → 0x629d30 → 0x703f50`, one call stack — §5-verified, wow-re
-/// `combat-text-update-emission-law.md`; decision 0580's fold-back).
-pub(super) fn attacker_state(
-    mut s: AttackerState,
-    index: &GuidIndex,
-    self_guid: &SelfGuid,
-    swings: &mut MessageWriter<SwingMessage>,
-    impacts: &mut MessageWriter<SwingImpact>,
-    center: &mut MessageWriter<CombatTextEvent>,
-    sheaths: &mut MessageWriter<SheathRequest>,
-    edges: &mut MessageWriter<SwingRefusalEdge>,
-    stores: &Query<&mut crate::net::ObjectStore>,
-    seq: u64,
-) {
-    let victim = index.0.get(&s.victim).copied();
-    // Arm 5's `0x6259b6 call 0x5ea800`, whose first act is the swing-refusal latch clear
-    // (`0x5ecdb0(0)`) — gated exactly as the reference gates it: the attacker IS the active player
-    // (`0x5fa6d0`, a guid compare) and the victim resolves as a streamed unit. Written from here
-    // rather than computed downstream because this is the only place holding both guids, and it
-    // keeps the clear in packet order with the refusals (`crate::swing_refusal`).
-    if self_guid.0 == Some(s.attacker) && victim.is_some() {
-        edges.write(SwingRefusalEdge::Landed);
-    }
-    if benilla_assets::trace::enabled() {
-        benilla_assets::trace::line(
-            "fct",
-            &format!(
-                "recv swing atk={:#x} victim={:#x} dmg={} vstate={} hit={:#x}",
-                s.attacker, s.victim, s.damage, s.victim_state, s.hit_info
-            ),
-        );
-    }
-    // The client-side FULL-BLOCK synthesis (`0x625e20`, decision 0279): a resolvable
-    // victim + zero damage + a nonzero blocked amount rewrites the state to BLOCKS(5)
-    // before any consumer sees the record — the only thing the wire's blocked_amount
-    // ever does (a PARTIAL block stays state 1, indistinguishable from a plain hit).
-    if victim.is_some() && s.damage == 0 && s.blocked != 0 {
-        s.victim_state = 5;
-    }
-    // The center combat text (decision 0578/0580): self victim, at receive, AFTER the full-block
-    // synthesis (so a full block reads BLOCK, not MISS) — the packet's absorb/resist/blocked
-    // sums feed the confirmed helper-B partial trailers.
-    if self_guid.0 == Some(s.victim) {
-        if let Some((message_type, data, extra)) = super::combat_log::melee_center_text(
-            s.hit_info,
-            s.victim_state,
-            s.damage,
-            s.absorb,
-            s.resist,
-            s.blocked,
-        ) {
-            center.write(CombatTextEvent {
-                message_type,
-                data,
-                extra,
-            });
-        }
-    }
-    let swing = SwingMessage {
-        attacker: Entity::PLACEHOLDER, // filled per branch below
-        victim,
-        hit_info: s.hit_info,
-        victim_state: s.victim_state,
-        damage: s.damage,
-        displayed: s.displayed(),
-        seq,
-    };
-    if let Some(&e) = index.0.get(&s.attacker) {
-        // The **observed attacker auto-draws melee** — the ref's SECOND melee draw, independent
-        // of the attack-start one, and the reason a swing is never delivered in the wrong stance:
-        // `0x625829 cmp [attacker+0xd40],1; jne` → `SetSheatheState(1, bInstant=1, bFireEvent=1)`
-        // at `0x62583a`, byte-read here, tabulated in wow-re `sheath-policy.md` §1. It sits
-        // immediately after the attacker resolve and **before** any hit-info handling, so even a
-        // swing whose animation is suppressed (`HitInfo & 0x10000`) still draws. Nothing else in
-        // the policy can do this job: the per-animation reconcile's melee force is gated to
-        // `CUR != 2` (`0x5fe0f9`/`0x5fe13b`), so a unit swinging with a bow drawn — a ranged
-        // stance a shot left behind — would otherwise keep swinging with the bow forever. The
-        // setter's own idempotency is the `cmp`: a request equal to the committed state is
-        // refused there, so this is free on every swing after the first.
-        sheaths.write(SheathRequest {
-            entity: e,
-            state: 1,
-            ceremony: false,
-        });
-        swings.write(SwingMessage {
-            attacker: e,
-            ..swing
-        });
-    } else if swing.victim.is_some_and(|v| {
-        // The receive-time arm goes THROUGH the gated dispatcher — `0x625823 je 0x625a3e` takes
-        // the unresolved-attacker leg, which resolves the victim and calls `0x625a6d call
-        // 0x624530`, so the LOOTABLE front gate applies here exactly as it does to the tag path
-        // (`creature_anim::impact::lootable_victim`). It calls no consequence directly.
-        !stores.get(v).is_ok_and(|s| s.0.unit_lootable())
-    }) {
-        // The client's SMSG-arm fallback: an attacker we can't resolve (out of range)
-        // can't animate a swing — its victim feedback fires immediately and in FULL
-        // (`0x625a6d`, the only receive-time victim dispatch). The PLACEHOLDER
-        // attacker resolves nowhere downstream (blood defaults front).
-        impacts.write(SwingImpact {
-            swing,
-            text_only: false,
-            natural: None,
-            // The receive-time arm: no tag fired, so the reference has no event point either —
-            // the consumer falls back to the victim, the only anchor the packet leaves us.
-            pos: None,
-        });
-    }
-}
diff --git a/crates/benilla-app/src/net/apply/mount.rs b/crates/benilla-app/src/net/apply/mount.rs
deleted file mode 100644
index 77936eae..00000000
--- a/crates/benilla-app/src/net/apply/mount.rs
+++ /dev/null
@@ -1,46 +0,0 @@
-//! The mount arc's arm bodies for [`super::apply_net_updates`]'s dispatch match (decision 0441) —
-//! the (dis)mount attempt's result code (P1) and a nearby rider's flourish (P2). Each `pub(super)`
-//! fn here is exactly one arm's body; the match at the call site stays the dispatcher, one call per
-//! arm.
-
-use bevy::prelude::*;
-
-use crate::creature_anim::MountFlourish;
-use crate::ui_action::MountErrors;
-
-use super::super::{GuidIndex, SelfGuid};
-
-/// `SMSG_MOUNTRESULT`/`SMSG_DISMOUNTRESULT` — OK is silent in the reference (10 mounting,
-/// 3 dismounting); a failure queues the red error line (`ui_action::mount_result_key` — resolved
-/// against the VM's GlobalStrings at drain).
-pub(super) fn mount_result(mount: bool, code: u32, errors: &mut MountErrors) {
-    let ok = if mount { code == 10 } else { code == 3 };
-    if !ok {
-        info!(
-            "net: {}mount refused (code {code})",
-            if mount { "" } else { "dis" }
-        );
-        errors.0.push((mount, code));
-    }
-}
-
-/// `SMSG_MOUNTSPECIAL_ANIM` — a nearby rider's flourish: rear their mount (MountSpecial 94 on the
-/// mount child; the hop happens in `creature_anim::flourish_to_anim`).
-///
-/// Our OWN guid is dropped: we played it locally at send time, and whether the sender gets the
-/// SMSG echoed back is a server-config detail (LIVE-VERIFIED 2026-07-17, double-flourish probe:
-/// vmangos's `SendMovementMessageToSet(.., false)` only cheat-logs on the flag — the
-/// non-broadcaster delivery hardcodes self=true, so our deployment echoes; the optional per-player
-/// broadcaster honors it and would not). Self-suppression on receive is correct under both configs.
-pub(super) fn mount_special(
-    guid: u64,
-    self_guid: &SelfGuid,
-    index: &GuidIndex,
-    out: &mut MessageWriter<MountFlourish>,
-) {
-    if self_guid.0 != Some(guid) {
-        if let Some(&e) = index.0.get(&guid) {
-            out.write(MountFlourish { unit: e });
-        }
-    }
-}
diff --git a/crates/benilla-app/src/net/apply/names.rs b/crates/benilla-app/src/net/apply/names.rs
deleted file mode 100644
index a3f76b56..00000000
--- a/crates/benilla-app/src/net/apply/names.rs
+++ /dev/null
@@ -1,70 +0,0 @@
-//! Name-query answer arm bodies for [`super::apply_net_updates`]'s dispatch match — the three
-//! `*_QUERY_RESPONSE` packets that fill the ask-once [`NameCache`] (`NameCache::resolve` is what
-//! asked for them). Each `pub(super)` fn here is exactly one arm's body; the match at the call site
-//! stays the dispatcher, one call per arm.
-
-use bevy::prelude::debug;
-
-use crate::names::{CreatureRecord, NameCache};
-
-/// `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`]).
-pub(super) fn player_name(
-    guid: u64,
-    name: String,
-    race: u32,
-    class: u32,
-    gender: u32,
-    names: &mut NameCache,
-) {
-    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.
-pub(super) 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** (wow-re `dbcache.md`: eviction is explicit only), 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.
-pub(super) 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.
-pub(super) fn creature_name(
-    entry: u32,
-    name: Option<String>,
-    subname: Option<String>,
-    creature_type: Option<u32>,
-    pet_family: u32,
-    rank: u32,
-    type_flags: u32,
-    civilian: bool,
-    racial_leader: bool,
-    display_id: u32,
-    names: &mut NameCache,
-) {
-    names.insert_creature(
-        entry,
-        name.map(|n| CreatureRecord {
-            name: n,
-            subname,
-            creature_type: creature_type.unwrap_or(0),
-            pet_family,
-            rank,
-            type_flags,
-            civilian,
-            racial_leader,
-            display_id,
-        }),
-    );
-}
diff --git a/crates/benilla-app/src/net/apply/npc.rs b/crates/benilla-app/src/net/apply/npc.rs
deleted file mode 100644
index 8dc12da2..00000000
--- a/crates/benilla-app/src/net/apply/npc.rs
+++ /dev/null
@@ -1,420 +0,0 @@
-//! NPC-interaction arm bodies for [`super::apply_net_updates`]'s dispatch match — the gossip
-//! window (decision 0081 phase 3), the vendor window (phase 4), the trainer window (decision
-//! 0237), and the taxi-map session (decision 0484 phase 1). Each `pub(super)` fn here is exactly
-//! one arm's body; the match at the call site stays the dispatcher, one call per arm.
-
-use benilla_protocol::messages::{
-    GossipOption, NpcTextBlock, StabledPet, TaxiMask, TrainerSpell, VendorItem,
-};
-use bevy::prelude::*;
-
-use crate::names::NameCache;
-use crate::ui_bank::{BankErrors, BankOpen};
-use crate::ui_gossip::GossipState;
-use crate::ui_merchant::{MerchantErrors, MerchantOpen, MerchantRefusal};
-use crate::ui_quest::QuestGiver;
-use crate::ui_stable::{StableErrors, StableOpen};
-use crate::ui_taxi::TaxiState;
-use crate::ui_trainer::{TrainerErrors, TrainerOpen};
-
-use super::super::{ClientCommand, GuidIndex, NetCommands, ObjectStore};
-
-/// A streamed unit's gender (`UNIT_FIELD_BYTES_0` byte 2) by guid — the gossip greeting's column
-/// selector (wow-re `gossip-npctext-law.md`: tested `== 1` for female, so genderless `2` reads as
-/// male). `0` when the guid isn't streamed in or carries no descriptor yet, which is the same
-/// column the reference takes for a gossip target that isn't a unit at all.
-fn npc_gender(guid: u64, index: &GuidIndex, stores: &Query<&mut ObjectStore>) -> u8 {
-    index
-        .0
-        .get(&guid)
-        .and_then(|&e| stores.get(e).ok())
-        .and_then(|s| s.0.unit_gender())
-        .unwrap_or(0)
-}
-
-/// A gossip menu opened (`SMSG_GOSSIP_MESSAGE`): fill the [`GossipState`] the gossip feed
-/// (`crate::ui_gossip`) reads. A first visit to the text id sends the ask-once
-/// `CMSG_NPC_TEXT_QUERY` and **the feed fires nothing until [`npc_greeting`] answers it** — a
-/// hidden frame stays hidden, an open one keeps its previous menu painted (B292's hold and
-/// 1994's no-event edge; the mechanics and the reference law live on
-/// [`GossipState::open_menu`]); a revisit serves from the cache and repaints right away.
-/// [`gossip_complete`] closes it.
-///
-/// The greeting is **drawn here**, not at the packet — this is the reference's own moment for it
-/// (`0x4e2010`), and the draw needs both this NPC's gender ([`npc_gender`]) and a fresh roll.
-pub(super) fn gossip_menu(
-    npc: u64,
-    text_id: u32,
-    options: Vec<GossipOption>,
-    quests: Vec<(u32, u32, u32, String)>,
-    gossip: &mut GossipState,
-    net_commands: &NetCommands,
-    index: &GuidIndex,
-    stores: &Query<&mut ObjectStore>,
-) {
-    let npc_gender = npc_gender(npc, index, stores);
-    debug!(
-        "net: gossip menu on {npc:#x} — {} options, {} quests",
-        options.len(),
-        quests.len()
-    );
-    if gossip.open_menu(npc, text_id, options, quests, npc_gender) {
-        let _ = net_commands
-            .0
-            .send(ClientCommand::NpcTextQuery { text_id, guid: npc });
-    }
-}
-
-/// The NPC-text answer (`SMSG_NPC_TEXT_UPDATE`) — seed the cache with the whole record, and open
-/// the menu still waiting on it (a late answer for a menu we already closed or switched just
-/// seeds the cache; the next open draws its own line).
-///
-/// The record answers a query we sent for the waiting menu, so its NPC is the one whose gender
-/// picks the column (decision 0081's ask-once flow).
-pub(super) fn npc_greeting(
-    text_id: u32,
-    blocks: Vec<NpcTextBlock>,
-    gossip: &mut GossipState,
-    index: &GuidIndex,
-    stores: &Query<&mut ObjectStore>,
-) {
-    let npc_gender = gossip.npc.map_or(0, |npc| npc_gender(npc, index, stores));
-    gossip.text_arrived(text_id, blocks, npc_gender);
-}
-
-/// `SMSG_GOSSIP_COMPLETE` ends the whole interaction (e.g. right after a quest accept), so the
-/// quest window closes with the gossip menu (decision 0088).
-pub(super) fn gossip_complete(gossip: &mut GossipState, quest: &mut QuestGiver) {
-    debug!("net: gossip complete — closing the menu");
-    gossip.clear();
-    quest.clear();
-}
-
-/// 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 ([`crate::poi_marker`]); it
-/// is the same real clock the corpse reclaim delay is stamped against (decision 0846).
-pub(super) fn gossip_poi(
-    poi: &benilla_protocol::messages::GossipPoi,
-    marker: &mut crate::poi_marker::PoiMarker,
-    map_id: u32,
-    now_secs: f64,
-) {
-    debug!(
-        "net: directions to \"{}\" at ({:.1}, {:.1}) — icon {}, flags {:#x}",
-        poi.name, poi.pos[0], poi.pos[1], poi.icon, poi.flags
-    );
-    marker.set(poi, map_id, now_secs);
-}
-
-/// A vendor's stock (`SMSG_LIST_INVENTORY`): fill the [`MerchantOpen`] the merchant feed
-/// (`crate::ui_merchant`) reads. A successful buy updates the stock display via
-/// [`vendor_buy_result`] (the item itself lands via item-create); a successful sell is silent
-/// (never a packet here — only the error path is).
-pub(super) fn vendor_inventory(vendor: u64, items: Vec<VendorItem>, merchant: &mut MerchantOpen) {
-    debug!("net: vendor {vendor:#x} listed {} items", items.len());
-    merchant.open(vendor, items);
-}
-
-/// The bank opened (`SMSG_SHOW_BANK`): point the [`BankOpen`] session the bank feed
-/// (`crate::ui_bank`) reads at the banker. Sent for our own `CMSG_BANKER_ACTIVATE` *and*
-/// volunteered by the server for the gossip menu's bank option (`GOSSIP_OPTION_BANKER` →
-/// `SendShowBank`, decision 0604) — so this never assumes we asked. The vault's contents are
-/// descriptor fields already streamed; the window renders from local state.
-///
-/// Opening the bank ends any open gossip interaction (the [`gossip_complete`] clear): vmangos
-/// sends no `SMSG_GOSSIP_COMPLETE` for the gossip menu's bank option (VERIFIED
-/// `Player::OnGossipSelect` — BANKER only calls `SendShowBank`), and the panel slots alone can't
-/// close the menu — the bank's `pushable = 6` sends it to the *center* slot beside a pushable-0
-/// gossip instead of replacing it, so the menu would linger beside the vault
-/// (director-observed). The real client ends the old NPC interaction when the new one starts
-/// (INFERRED — the exact C++ `GOSSIP_CLOSED` fire isn't RE'd; the observable is vanilla's: the
-/// menu is gone once the vault is up).
-pub(super) fn show_bank(
-    banker: u64,
-    bank: &mut BankOpen,
-    gossip: &mut GossipState,
-    quest: &mut QuestGiver,
-) {
-    debug!("net: bank opened at {banker:#x}");
-    if gossip.npc.is_some() {
-        gossip_complete(gossip, quest);
-    }
-    bank.open(banker);
-}
-
-/// A bank-slot purchase refusal (`SMSG_BUY_BANK_SLOT_RESULT` — vmangos sends it only on failure;
-/// success is the PLAYER_BYTES_2 delta): queue it for the bank feed's red error line.
-pub(super) fn bank_buy_slot_result(result: u32, errors: &mut BankErrors) {
-    debug!("net: bank slot purchase refused (code {result})");
-    errors.0.push(result);
-}
-
-/// A trainer's service list (`SMSG_TRAINER_LIST`): fill the [`TrainerOpen`] the trainer feed
-/// (`crate::ui_trainer`) reads.
-pub(super) fn trainer_list(
-    trainer: u64,
-    trainer_type: u32,
-    services: Vec<TrainerSpell>,
-    greeting: String,
-    trainer_open: &mut TrainerOpen,
-) {
-    debug!(
-        "net: trainer {trainer:#x} (type {trainer_type}) listed {} services",
-        services.len()
-    );
-    trainer_open.open(trainer, trainer_type, services, greeting);
-}
-
-/// A trainer taught a service — confirmation only; the spell already landed via
-/// `SMSG_LEARNED_SPELL`. Re-request the list to repaint the bought row green→gray (and unlock
-/// any next rank); the server never auto-resends on a buy (VERIFIED vmangos
-/// `HandleTrainerBuySpellOpcode`). Guard on the window still being open for this trainer so a
-/// late reply for a closed/switched window doesn't re-open it.
-///
-/// This re-request is **benilla's**, not the reference's — the reference repaints a purchase by
-/// re-deriving every service's state client-side (`0x4d7d40`, decision 1128 §4.2) and receives no
-/// packet at all. So the answering list is marked as a *refresh* ([`TrainerOpen::refresh_pending`]):
-/// it repaints the open window, and must not carry the reference's per-packet filter/collapse reset,
-/// which is what dropped the player's "Available only" choice the moment they learned a spell
-/// (B256).
-pub(super) fn trainer_buy_succeeded(
-    trainer: u64,
-    spell_id: u32,
-    trainer_open: &mut TrainerOpen,
-    net_commands: &NetCommands,
-) {
-    debug!("net: trainer {trainer:#x} taught spell {spell_id} — re-listing");
-    if trainer_open.trainer == Some(trainer) {
-        trainer_open.refresh_pending = true;
-        let _ = net_commands.0.send(ClientCommand::TrainerList { trainer });
-    }
-}
-
-/// A stable master's pet list (`MSG_LIST_STABLED_PETS`): fill the [`StableOpen`] the stable feed
-/// (`crate::ui_stable`) reads. Arrives unprompted off the gossip stable option — that is how the
-/// window opens — and again in answer to our own refresh send.
-pub(super) fn list_stabled_pets(
-    npc: u64,
-    num_stable_slots: u8,
-    pets: Vec<StabledPet>,
-    stable_open: &mut StableOpen,
-    names: &mut NameCache,
-) {
-    debug!(
-        "net: stable master {npc:#x} listed {} pets ({num_stable_slots} slots bought)",
-        pets.len()
-    );
-    // **Seed the pet-name cache from the list** (decision 1688). Every row carries the pet's own
-    // number and the name its owner gave it — the exact `(pet_number, name)` pair
-    // `SMSG_PET_NAME_QUERY_RESPONSE` would answer with — so the pet a player unstables has a
-    // resolvable `UnitName("pet")` the moment it is summoned, instead of after a round trip.
-    //
-    // The window this closes is a real one the director hit: `PetStable_Update` sets the current
-    // pet's button tooltip to a bare `UnitName("pet")` (`PetStable.lua:161`, transcribed
-    // unguarded because the reference is unguarded), and hands it to `GameTooltip:SetText`, whose
-    // byte-pinned signature REQUIRES a string (`0x531b90`) and raises otherwise. Nil name ⇒ Lua
-    // error dialog, once per unstable.
-    //
-    // Why the reference does not trip over its own unguarded line: its pet-name cache is
-    // `petnamecache.wdb`, which **persists across sessions**, so a pet you have owned before is
-    // already warm before the packet arrives. benilla has no such file, so a window the reference
-    // has practically closed is wide open for us. Seeding is not a workaround for the missing
-    // cache — it is using the answer the server has already sent us in this very packet.
-    for pet in &pets {
-        if !pet.name.is_empty() {
-            names.insert_pet(pet.pet_number, pet.name.clone());
-        }
-    }
-    stable_open.open(npc, num_stable_slots, pets);
-}
-
-/// The answer to a stable verb (`SMSG_STABLE_RESULT`) — one byte, and the client's whole response
-/// to it is a five-way jump table (wow-re `system/ui/scratch/stable-master-window.md` §5, VERIFIED
-/// off the raw remap/jump bytes at `0x4cadac`/`0x4cad98`; decision 1677):
-///
-/// | code | what the client does |
-/// |---|---|
-/// | 1 | `DisplayError(0x25)` = **`ERR_NOT_ENOUGH_MONEY`** — the only code that says anything |
-/// | 2–7 | **absolutely nothing** — vmangos's catch-all `STABLE_ERR_STABLE = 6` included |
-/// | 8, 9 | re-request the list |
-/// | 10 | **`inc` the local purchased-slot count**, then re-request |
-/// | 11 | fire `PET_STABLE_UPDATE` (no vmangos counterpart — nothing in 1.12 sends it) |
-/// | 0, ≥12 | nothing |
-///
-/// The re-request is not a benilla convenience: no success carries an updated list, so without it
-/// the window would go on showing the pre-action arrangement.
-///
-/// **Code 10's local increment happens BEFORE the guid test**, so a buy-slot success arriving with
-/// no stable master open still bumps the count without refreshing. That ordering is reproduced
-/// deliberately — it is what makes the purchase row correct if the window is reopened, and the
-/// alternative would be to invent a tidier client than the one being reimplemented.
-pub(super) fn stable_result(
-    result: u8,
-    stable_open: &mut StableOpen,
-    errors: &mut StableErrors,
-    net_commands: &NetCommands,
-) {
-    use benilla_protocol::messages::stable_result as code;
-    // Ahead of the guid test, exactly as `0x4cacf3` sits ahead of `0x4cad05`.
-    if result == code::SUCCESS_BUY_SLOT {
-        stable_open.num_stable_slots = stable_open.num_stable_slots.saturating_add(1);
-    }
-    match result {
-        // The one code that speaks. Its text is the reference's own `GlobalStrings` value for
-        // `ERR_NOT_ENOUGH_MONEY`, reached through `DisplayError` row 0x25.
-        code::ERR_MONEY => {
-            debug!("net: stable purchase refused — not enough money");
-            errors.0.push("ERR_NOT_ENOUGH_MONEY");
-        }
-        code::SUCCESS_STABLE | code::SUCCESS_UNSTABLE | code::SUCCESS_BUY_SLOT => {
-            let Some(npc) = stable_open.npc else {
-                debug!("net: stable success {result} with no open stable — no re-list");
-                return;
-            };
-            debug!("net: stable action succeeded (code {result}) — re-listing");
-            let _ = net_commands.0.send(ClientCommand::ListStabledPets { npc });
-        }
-        // Codes 2–7 (the generic ERR_STABLE among them), 0 and ≥12: the client shows NOTHING.
-        // Not an omission — the catch-all is one code for six causes, and the reference declines to
-        // guess which.
-        _ => debug!("net: stable result {result} — no client-visible effect"),
-    }
-}
-
-/// A trainer refused a purchase — the trainer window's error line.
-pub(super) fn trainer_buy_failed(error: u32, errors: &mut TrainerErrors) {
-    debug!("net: trainer buy failed (code {error})");
-    errors.0.push(error);
-}
-
-/// A purchase updated the vendor's stock (`SMSG_BUY_ITEM`). Only touch stock for the open
-/// vendor (a late answer for a closed window is stale).
-pub(super) fn vendor_buy_result(
-    vendor: u64,
-    slot: u32,
-    new_count: u32,
-    merchant: &mut MerchantOpen,
-) {
-    if merchant.vendor == Some(vendor) {
-        merchant.update_stock(slot, new_count);
-    }
-}
-
-/// A purchase was refused (`SMSG_BUY_FAILED`) — the merchant window's error line, and for the
-/// out-of-stock code the refusing row's own count.
-///
-/// **`ITEM_ALREADY_SOLD` zeroes the row** (`0x5dcda7`..`0x5dcdd6`, decision 1821): the reference
-/// walks its 128-row vendor cache, writes 0 into the matching row's count word and repaints —
-/// gated, as every other stale-answer path here is, on the packet naming the vendor still open.
-///
-/// **NAMED DIVERGENCE in the key.** The reference matches the row's `+0x00`, the vendor *slot* —
-/// the same word `SMSG_BUY_ITEM` keys its stock update by. vmangos puts the item *entry* in that
-/// field (`Player::SendBuyError`, `Player.cpp:11637`: `packet->itemEntry = item`), so matching by
-/// slot would find nothing on the server we actually talk to; matching by entry is the same row.
-/// vmangos raises this code from exactly the condition the zeroing models —
-/// `GetVendorItemCurrentCount(crItem) < totalCount` under `crItem->maxcount != 0`
-/// (`Player.cpp:18508`).
-pub(super) fn vendor_buy_failed(
-    vendor: u64,
-    item_entry: u32,
-    reason: u8,
-    merchant: &mut MerchantOpen,
-    errors: &mut MerchantErrors,
-) {
-    debug!("net: buy failed (entry {item_entry}, reason {reason})");
-    if reason == benilla_protocol::messages::buy_result::ITEM_ALREADY_SOLD
-        && merchant.vendor == Some(vendor)
-    {
-        merchant.sold_out(item_entry);
-    }
-    errors.0.push(MerchantRefusal::Buy(reason));
-}
-
-/// A sell was refused (`SMSG_SELL_ITEM`'s error path) — the merchant window's error line.
-pub(super) fn vendor_sell_failed(reason: u8, errors: &mut MerchantErrors) {
-    debug!("net: sell failed (reason {reason})");
-    errors.0.push(MerchantRefusal::Sell(reason));
-}
-
-/// The taxi map (`SMSG_SHOWTAXINODES`): fill the [`TaxiState`] phase 2's feed will read — the
-/// [`trainer_list`] shape.
-pub(super) fn taxi_nodes_shown(
-    flightmaster: u64,
-    nearest_node: u32,
-    known_mask: TaxiMask,
-    taxi: &mut TaxiState,
-) {
-    debug!("net: taxi map on {flightmaster:#x} — nearest node {nearest_node}");
-    taxi.open(flightmaster, nearest_node, known_mask);
-}
-
-/// A taxi node's known status (`SMSG_TAXINODE_STATUS`) — answers `CMSG_TAXINODE_STATUS_QUERY`
-/// ([`crate::ui_taxi`]'s per-flight-master ask), and also rides the first-visit learn pair
-/// alongside `SMSG_NEW_TAXI_PATH` ([`taxi_new_path`] carries that signal into `discovered`; the
-/// paired `known = true` here is what clears the icon live on a learn). Upserts
-/// [`crate::ui_taxi::FlightMasterStatus`] on the flight master: `known = false` shows the green
-/// `TalkToMeGreen` overhead icon — the client's `0x5ecdd0` handler → `0x607480` marker swap
-/// (resource table `0xc4d9d8` index 4; the 0497 §5). The client also gates the reply on the
-/// unit's NPC_FLAGS bit 3 — moot here: only flight masters are ever queried or answered.
-pub(super) fn taxi_node_status(
-    guid: u64,
-    known: bool,
-    commands: &mut Commands,
-    index: &crate::net::GuidIndex,
-) {
-    debug!("net: taxi node status — {guid:#x} known={known}");
-    if let Some(&e) = index.0.get(&guid) {
-        commands
-            .entity(e)
-            .insert(crate::ui_taxi::FlightMasterStatus { known });
-    }
-}
-
-/// The activate verdict (`SMSG_ACTIVATETAXIREPLY`) — staged for phase 2's window to surface as
-/// the red error line and clear (the trainer/merchant error-line pattern, folded into
-/// `TaxiState.reply` since there's no other consumer yet).
-pub(super) fn taxi_activate_reply(code: u32, taxi: &mut TaxiState) {
-    debug!("net: activate taxi reply — code {code}");
-    taxi.reply = Some(code);
-}
-
-/// A first-visit "learn" landed (`SMSG_NEW_TAXI_PATH`, empty body) — vmangos's only send site
-/// (`SendLearnNewTaxiNode`) always pairs this with a `SMSG_TAXINODE_STATUS(known=true)` for the
-/// same flight master, so the empty body alone is the discovery signal; phase 2's presentation
-/// reads the flag.
-pub(super) fn taxi_new_path(taxi: &mut TaxiState) {
-    debug!("net: taxi — first-visit node learned (SMSG_NEW_TAXI_PATH)");
-    taxi.discovered = true;
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// `SMSG_SHOW_BANK` ends an open gossip interaction (the gossip menu's bank option arrives
-    /// with no `SMSG_GOSSIP_COMPLETE` — `show_bank`'s doc): the gossip/quest sessions clear and
-    /// the bank session opens. A direct right-click (no gossip open) just opens the bank.
-    #[test]
-    fn show_bank_ends_the_gossip_interaction() {
-        let mut bank = BankOpen::default();
-        let mut gossip = GossipState::default();
-        let mut quest = QuestGiver::default();
-        gossip.npc = Some(0x42);
-
-        show_bank(0x42, &mut bank, &mut gossip, &mut quest);
-        assert_eq!(bank.banker, Some(0x42));
-        assert_eq!(gossip.npc, None, "the gossip session ended with the menu");
-
-        // No gossip open: a plain open, nothing else touched.
-        bank.clear();
-        show_bank(0x43, &mut bank, &mut gossip, &mut quest);
-        assert_eq!(bank.banker, Some(0x43));
-    }
-}
diff --git a/crates/benilla-app/src/net/apply/params.rs b/crates/benilla-app/src/net/apply/params.rs
deleted file mode 100644
index 0396037d..00000000
--- a/crates/benilla-app/src/net/apply/params.rs
+++ /dev/null
@@ -1,375 +0,0 @@
-//! **The drain's parameters, by name** (decision 2279, 2265 §A1a).
-//!
-//! [`super::apply_net_updates`] takes every resource the 273 arms write, and Bevy caps a system
-//! at sixteen parameters (`bevy_ecs` `system_param.rs`, `all_tuples!(…, 0, 16)`). From day one
-//! (0006) the escape was tuples nested up to six deep, addressed by coordinate — `audio.15 .6`,
-//! `ui_actions.1 .5` — with fifty comments across the tree explaining that a thing rides where it
-//! rides "because this is where the ceiling left room". The `SystemParam` derive emits a named
-//! struct with no field cap, so each family below is a struct: the body destructures it by field
-//! name, every use site reads as what it is, and a new resource joins the family it belongs to
-//! rather than the tuple with a slot free.
-//!
-//! **Grouping is by what the arms do with a thing**, not by what it is: a session-lifecycle edge,
-//! a window's parked state, the action bar's queues, an animation-bearing message, a read-only
-//! catalog. Two families the tuples had mis-homed for want of room moved to where they belong
-//! (the catalogs, and the queries); one parameter the tuples carried nobody read
-//! (`PingShared` — the drain stopped clearing it with B346) is gone. Nothing else changed: the
-//! same set of resources, the same access, one system.
-//!
-//! Splitting the drain itself — each family owning a reader system of its own — is 2265 §A1(b),
-//! and starts from these names.
-
-use bevy::ecs::system::SystemParam;
-use bevy::prelude::*;
-
-use super::super::{
-    AiReactionMessage, CharActionResultMessage, CharListMessage, EmoteMessage, EnteredWorldMessage,
-    LoggedOutMessage, ObjectStore, PendingTransfer, PetDismissSoundMessage, PetTalkMessage,
-    RemoteMotion, SelfPlayer, ServerSoundMessage, ServerTime, ServerWallClock, TeleportMessage,
-    UnitMoveModes, WorldportMessage,
-};
-use benilla_world::weather::WeatherMessage;
-
-/// The clocks: the server's two, and our real one.
-#[derive(SystemParam)]
-pub(crate) struct Clocks<'w> {
-    /// The in-game day/night clock the lighting reads (`SMSG_LOGIN_SETTIMESPEED`).
-    pub server_time: ResMut<'w, ServerTime>,
-    /// The wall clock the absolute descriptor stamps are dated in (decision 1150). A different
-    /// quantity from the one above, from the same handler file.
-    pub wall_clock: ResMut<'w, ServerWallClock>,
-    /// `Time<Real>`, NOT the default virtual one, and every reader here is the reason: a span
-    /// the SERVER sends us (an aura's remaining duration, the corpse-reclaim delay, a relayed
-    /// mover's fire-time) counts down in real seconds, so it must be stamped and read on a real
-    /// clock. `Time<Virtual>` clamps at 250 ms per frame (`max_delta`), which is right for
-    /// simulation — a 2 s hitch must not teleport animations — and wrong here: every long frame
-    /// would quietly ADD that much to every buff timer, so an aura would vanish with seconds
-    /// still showing on its clock. Measured on a hitchy run: the virtual clock lost 20 s against
-    /// real in 33 s (decision 0846). The relayed-move replay (0601/0615) reads the same clock in
-    /// `drain_pending_moves`/`extrapolate_remote_units`.
-    pub real: Res<'w, Time<Real>>,
-}
-
-/// Every entity query the drain holds — what it reads or writes on streamed objects.
-#[derive(SystemParam)]
-pub(crate) struct ObjectQueries<'w, 's> {
-    pub transforms: Query<'w, 's, &'static mut Transform>,
-    pub stores: Query<'w, 's, &'static mut ObjectStore>,
-    /// A relayed player's dead-reckon.
-    pub remote: Query<'w, 's, &'static mut RemoteMotion>,
-    /// Any unit's server-granted movement modes (decision 1780).
-    pub modes: Query<'w, 's, &'static mut UnitMoveModes>,
-    /// The deck a unit is standing on and its pose there (decision 1936).
-    pub riders: Query<'w, 's, &'static mut crate::transport::TransportRider>,
-    /// READ-only: every write to a mover's speed set goes through the drain's
-    /// `objects::SpeedStage` and lands in one flush at the end (decision 1478).
-    pub speeds: Query<'w, 's, &'static super::super::UnitSpeeds>,
-    /// The armed-transport lens for the worldport's spare predicate (decision 0455: a boat whose
-    /// path touches the destination map survives the purge).
-    pub transports: Query<'w, 's, &'static crate::transport::Transport>,
-    /// The cast-state read the spell-id-keyed `Casting` reap needs (decision 0107).
-    pub casting: Query<'w, 's, &'static crate::creature_anim::Casting>,
-    /// Are *we* already swinging? The ref's `[player+0xc48]`, mirrored by the server-echoed
-    /// [`crate::creature_anim::Engaged`] — read by the GO handler's deferred auto-attack start
-    /// (`0x6e83e7`, decision 1593). Filter-only, so it conflicts with nothing else in the drain.
-    pub engaged_self: Query<'w, 's, (), (With<crate::creature_anim::Engaged>, With<SelfPlayer>)>,
-    /// The per-field descriptor edges the merge reports (decision 2297) — the reference's
-    /// `CMirrorHandler` notify pass, emitted from the one write that holds both sides.
-    pub field_changes: MessageWriter<'w, super::super::FieldChanged>,
-}
-
-/// The session lifecycle: the glue-screen edges, the player's own teleports and mover
-/// handshakes, and the entry/transfer state those edges write (decision 0193).
-#[derive(SystemParam)]
-pub(crate) struct Session<'w> {
-    pub teleports: MessageWriter<'w, TeleportMessage>,
-    pub worldports: MessageWriter<'w, WorldportMessage>,
-    /// The two park publications: the realm list and the character roster are the same thing
-    /// one park apart, each published so the app's policy can answer it.
-    pub char_lists: MessageWriter<'w, CharListMessage>,
-    pub realm_lists: MessageWriter<'w, crate::net::RealmListMessage>,
-    /// The pick park's two verdicts: what a create/delete came back with, and the refusal of the
-    /// pick itself.
-    pub char_actions: MessageWriter<'w, CharActionResultMessage>,
-    pub char_login_failures: MessageWriter<'w, super::super::CharacterLoginFailedMessage>,
-    /// The world-entry pair, one edge: the entry message, and the `SMSG_ADDON_INFO` verdict that
-    /// the entry's own UI load reads before the first addon's file-scope code asks
-    /// `GetNumAddOns()` (2175).
-    pub entered_world: MessageWriter<'w, EnteredWorldMessage>,
-    pub addon_reply: ResMut<'w, crate::net::AddonInfoReply>,
-    pub logged_out: MessageWriter<'w, LoggedOutMessage>,
-    pub speed_changes: MessageWriter<'w, super::super::SpeedChangeMessage>,
-    /// The two server-authored mover edges the controller both *applies* and *answers*: a
-    /// granted mode (decisions 0308, 0866) and a knockback launch (decision 1702) are the same
-    /// handshake, an edge the server may not act on until our own live pose comes back.
-    pub move_modes: MessageWriter<'w, super::super::MoveModeMessage>,
-    pub knockbacks: MessageWriter<'w, super::super::KnockBackMessage>,
-    /// The login screen's dialog + reconnect-policy feed (decision 0539).
-    pub login_stages: MessageWriter<'w, super::super::LoginStageMessage>,
-    /// The login queue's position feed (decision 1681).
-    pub login_queued: MessageWriter<'w, super::super::LoginQueuedMessage>,
-    pub login_failures: MessageWriter<'w, super::super::LoginFailedMessage>,
-    pub disconnects: MessageWriter<'w, super::super::DisconnectedMessage>,
-    /// The server's own answer to a GM dot-command, readable rather than only logged — the probe
-    /// shield's confirmation channel (decision 0677).
-    pub server_said: MessageWriter<'w, super::super::ServerSaidMessage>,
-    /// A `MSG_MOVE_*` the server addressed to OUR mover (decision 0725): a pose it wrote, with no
-    /// handshake — the controller applies it in `player::wire_in`.
-    pub self_moves: MessageWriter<'w, super::super::SelfMoveMessage>,
-    /// The possession handoff (`SMSG_CLIENT_CONTROL_UPDATE`): control of a unit granted or
-    /// revoked. Forwarded verbatim — only the controller knows the pose it would have to park.
-    pub client_control: MessageWriter<'w, super::super::ClientControlMessage>,
-    /// A cinematic to play (`SMSG_TRIGGER_CINEMATIC`) — `crate::cinematic` owns both the playback
-    /// and the ack that has to answer it (decision 0196).
-    pub cinematics: MessageWriter<'w, super::super::CinematicTriggeredMessage>,
-    /// The far-teleport latch (decision 0455): `SMSG_TRANSFER_PENDING`'s transport block routes
-    /// `NEW_WORLD`'s coordinates; cleared on disconnect.
-    pub transfer: ResMut<'w, PendingTransfer>,
-}
-
-/// The windows' parked state: the ask-once caches and every `*Open`/`*State`/`*Session` a
-/// `feed_*` pushes into the VM later (decision 0081). Where 195 of the 273 arms land.
-#[derive(SystemParam)]
-pub(crate) struct WindowStores<'w> {
-    pub names: ResMut<'w, crate::names::NameCache>,
-    pub items: ResMut<'w, crate::items::Items>,
-    pub gossip: ResMut<'w, crate::ui_gossip::GossipState>,
-    pub merchant: ResMut<'w, crate::ui_merchant::MerchantOpen>,
-    /// The two gossip-reached NPC service sessions whose state is a whole open window.
-    pub trainer_open: ResMut<'w, crate::ui_trainer::TrainerOpen>,
-    pub stable_open: ResMut<'w, crate::ui_stable::StableOpen>,
-    /// The loot window state, the client-local loot-target latch (the kneel's self trigger,
-    /// decision 0515), and the open group-loot rolls (decision 0591).
-    pub loot: ResMut<'w, crate::ui_loot::LootState>,
-    pub loot_latch: ResMut<'w, crate::ui_loot::LootLatch>,
-    pub loot_rolls: ResMut<'w, crate::ui_loot_roll::LootRolls>,
-    pub chat_log: ResMut<'w, crate::ui_chat::ChatLog>,
-    pub quest: ResMut<'w, crate::ui_quest::QuestGiver>,
-    /// The quest-log template cache, and the party quest-share state (decision 1733) — the
-    /// verdicts on a quest we pushed and the escort confirm: a share is a quest-log verb.
-    pub quest_log: ResMut<'w, crate::ui_quest_log::QuestLog>,
-    pub quest_share: ResMut<'w, crate::ui_quest_share::QuestShare>,
-    pub go_templates: ResMut<'w, crate::go_templates::GameObjectTemplates>,
-    pub home_bind: ResMut<'w, crate::net::HomeBind>,
-    pub proficiencies: ResMut<'w, crate::net::Proficiencies>,
-    pub dropped: ResMut<'w, crate::net::DroppedOpcodes>,
-    /// The death arc's wire-fed store (decision 0308): reclaim expiry, corpse location, resurrect
-    /// offer, the spirit-healer confirm.
-    pub death_net: ResMut<'w, crate::death::DeathNet>,
-    /// The party/raid roster mirror + its composed system lines (decision 0434).
-    pub group: ResMut<'w, crate::ui_party::GroupState>,
-    /// The taxi-map session (decision 0484 phase 1).
-    pub taxi: ResMut<'w, crate::ui_taxi::TaxiState>,
-    /// The mailbox session + its login-scoped arrival countdown (decision 0544).
-    pub mail_open: ResMut<'w, crate::ui_mail::MailOpen>,
-    pub mail_pending: ResMut<'w, crate::ui_mail::MailPending>,
-    /// The player-trade session (decision 0592).
-    pub trade_session: ResMut<'w, crate::ui_trade::TradeSession>,
-    /// The bank session and its purchase-refusal queue (decision 0604).
-    pub bank_open: ResMut<'w, crate::ui_bank::BankOpen>,
-    pub bank_errors: ResMut<'w, crate::ui_bank::BankErrors>,
-    /// The world-state table the NPC-text `$<n>w` tokens read.
-    pub world_states: ResMut<'w, crate::world_state::WorldStates>,
-    /// The duel session (decision 0633).
-    pub duel: ResMut<'w, crate::ui_duel::DuelState>,
-    pub social: ResMut<'w, crate::ui_social::SocialState>,
-    /// The pending logout/quit (decision 0674): the server's response and cancel-ack land here,
-    /// and `crate::ui_logout` turns them into the countdown dialog.
-    pub logout: ResMut<'w, crate::ui_logout::LogoutState>,
-    /// The mirror-timer queue (decision 0874): the breath/fatigue START/PAUSE/STOP edges, drained
-    /// into the FrameXML bars by `crate::ui_mirror`.
-    pub mirror_timers: ResMut<'w, crate::ui_mirror::MirrorTimerFeed>,
-    /// The pet action bar's server-authoritative state + its own cooldown store (decision 0982),
-    /// replaced wholesale on every `SMSG_PET_SPELLS`.
-    pub pet_bar: ResMut<'w, crate::ui_pet::PetBar>,
-    /// The by-key red error queue the pet bar's refused-order feedback rides (the `DisplayError`
-    /// route, resolved through the VM's own GlobalStrings by `ui_action::feed_actions`).
-    pub ui_error_keys: ResMut<'w, crate::ui_action::UiErrorKeys>,
-    /// The ask-once book-page cache (decision 1105) — every readable's text, keyed by `PageText`
-    /// id; the reader session repaints off it.
-    pub page_texts: ResMut<'w, crate::ui_item_text::PageTexts>,
-    pub played_time_answer: ResMut<'w, crate::net::PlayedTimeAnswer>,
-    /// The guild session (decision 1257) — the identity/roster mirror the seven
-    /// `SessionEvent::Guild*` arms drive.
-    pub guild: ResMut<'w, crate::ui_guild::GuildState>,
-    /// The innkeeper's pending bind question (decision 1331) — `SMSG_BINDER_CONFIRM` parks the
-    /// innkeeper's guid here and `crate::ui_binder` turns it into the CONFIRM_BINDER dialog,
-    /// whose Accept is the only thing that binds anything.
-    pub binder: ResMut<'w, crate::ui_binder::BinderState>,
-    /// The class trainer's pending respec question (decision 1580) — the inbound
-    /// `MSG_TALENT_WIPE_CONFIRM` parks the trainer's guid + cost here and
-    /// `crate::ui_talent_wipe` turns it into the CONFIRM_TALENT_WIPE dialog, whose Accept is the
-    /// only thing that unlearns anything. The binder's twin.
-    pub talent_wipe: ResMut<'w, crate::ui_talent_wipe::TalentWipeState>,
-    /// The dialog engine's verbs (decision 1963): the pet trainer's latch, the instance-boot
-    /// clock, the area spirit healer, the battleground queue and the meeting-stone queue — each
-    /// a feed for a stock dialog.
-    pub pet_unlearn: ResMut<'w, crate::ui_dialog_verbs::PetUnlearnState>,
-    pub instance_boot: ResMut<'w, crate::ui_dialog_verbs::InstanceBoot>,
-    pub area_spirit: ResMut<'w, crate::ui_dialog_verbs::AreaSpiritHealer>,
-    pub battlefield_queue: ResMut<'w, crate::ui_dialog_verbs::BattlefieldQueue>,
-    pub meeting_stone: ResMut<'w, crate::ui_dialog_verbs::MeetingStone>,
-    pub battlefield_scoreboard: ResMut<'w, crate::ui_battlefield_score::BattlefieldScoreboard>,
-    pub battlefield: ResMut<'w, crate::ui_battlefield::Battlefield>,
-    pub tutorials: ResMut<'w, crate::tutorial::Tutorials>,
-    pub battlefield_positions: ResMut<'w, crate::ui_battlefield_positions::BattlefieldPositions>,
-    pub tabard: ResMut<'w, crate::ui_tabard::TabardOpen>,
-    /// The guard's directions marker (`SMSG_GOSSIP_POI`) — the wire carries no map field, so
-    /// "where you were standing when the guard told you" is the client's to remember
-    /// (`crate::poi_marker`).
-    pub poi_marker: ResMut<'w, crate::poi_marker::PoiMarker>,
-    /// The inspect-honor reply (decision 1512) — `MSG_INSPECT_HONOR_STATS` is the only source of
-    /// another player's honor numbers, so the reply parks here and `crate::ui_honor` pushes it
-    /// into the pane and fires `INSPECT_HONOR_UPDATE`.
-    pub inspect_honor: ResMut<'w, crate::ui_honor::InspectHonor>,
-    /// The minimap ping (decision 1596) — a group member's `MSG_MINIMAP_PING` seats the world
-    /// point here and the minimap renderer derives everything else from it.
-    pub ping: ResMut<'w, crate::minimap::MinimapPing>,
-    /// The GM ticket (decision 1673) — `SMSG_GMTICKET_GETTICKET` replaces the held ticket here
-    /// and BUMPS AN ANSWER COUNTER, which is what `crate::ui_gm_ticket` diffs on: the Help window
-    /// re-polls every 10 minutes and an unchanged answer still has to re-fire `UPDATE_TICKET`.
-    pub gm_ticket: ResMut<'w, crate::ui_gm_ticket::GmTicketState>,
-    /// The guild-charter session (decision 1672) — two resources because only the registrar
-    /// half is NPC-bound: `SMSG_PETITION_SHOWLIST` opens the registrar, and
-    /// `SMSG_PETITION_SHOW_SIGNATURES` opens the item-bound charter window, which must survive
-    /// walking away from the registrar.
-    pub registrar: ResMut<'w, crate::ui_petition::GuildRegistrarState>,
-    pub petition: ResMut<'w, crate::ui_petition::PetitionState>,
-    /// The pending summon question (decision 1747) — `SMSG_SUMMON_REQUEST` parks the summoner's
-    /// guid, zone and expiry here and `crate::ui_summon` turns it into the CONFIRM_SUMMON dialog,
-    /// whose Accept is the only packet in the flow.
-    pub summon: ResMut<'w, crate::ui_summon::SummonState>,
-    /// The instance-lockout bookkeeping (decision 1748) — four of its six packets queue a
-    /// GlobalStrings-templated chat line here for `crate::ui_instance` to resolve against the
-    /// VM, and two write the latch behind `CanShowResetInstances()`.
-    pub instances: ResMut<'w, crate::ui_instance::InstanceState>,
-}
-
-/// The action bar's family: the cast/cooldown state and every error queue the red line drains
-/// (decision 0137), plus the item-lock bookkeeping the inventory-failure arm also drives
-/// (decision 0216 §4 / 0218 §3 — the drain has no `UiScript` to fire `ITEM_LOCK_CHANGED`
-/// through, so the transitioned slots queue in `LockTransitions` for the container feed).
-#[derive(SystemParam)]
-pub(crate) struct ActionStores<'w> {
-    pub player_actions: ResMut<'w, crate::ui_action::PlayerActions>,
-    /// The cast + mount error queues, both drained into the red error line by
-    /// `ui_action::feed_actions`.
-    pub cast_errors: ResMut<'w, crate::ui_action::CastErrors>,
-    pub mount_errors: ResMut<'w, crate::ui_action::MountErrors>,
-    /// The `modalNextSpell` chain's outbox (1597) — `cast_result` fills it, the ui_action drain
-    /// sends it through the one cast path.
-    pub chain_casts: ResMut<'w, crate::ui_action::ChainCasts>,
-    /// The taming-refusal queue (decision 2039) — `SMSG_PET_TAME_FAILURE`'s reason byte. Its own
-    /// queue rather than `UiErrorKeys` because its message needs TWO GlobalStrings lookups, and
-    /// the inner one is only reachable at the drain (see the resource's doc).
-    pub pet_tame_failures: ResMut<'w, crate::ui_action::PetTameFailures>,
-    /// Spells learned mid-session, awaiting `LEARNED_SPELL_IN_TAB` (2252). A queue for the same
-    /// reason the reference sorts before it fires: the tab index is only correct against the
-    /// rebuilt tab list, which is the spellbook feed's, not this apply's.
-    pub learned_in_tab: ResMut<'w, crate::ui_spellbook::LearnedInTab>,
-    pub equip_errors: ResMut<'w, crate::ui_items::EquipErrors>,
-    pub merchant_errors: ResMut<'w, crate::ui_merchant::MerchantErrors>,
-    pub cast_bar: ResMut<'w, crate::ui_cast::CastBarFeed>,
-    pub pending_item_ops: ResMut<'w, crate::pending_item_ops::PendingItemOps>,
-    pub lock_transitions: ResMut<'w, crate::pending_item_ops::LockTransitions>,
-    /// The two NPC-service windows' error queues, each drained onto its window's red line by its
-    /// own feed.
-    pub trainer_errors: ResMut<'w, crate::ui_trainer::TrainerErrors>,
-    pub stable_errors: ResMut<'w, crate::ui_stable::StableErrors>,
-    pub pending_cast: ResMut<'w, crate::ui_cast::PendingCast>,
-    /// The player's cooldown store (decision 0137 phase 4); the pet's is in its bar, and
-    /// `addressed_store` picks between them.
-    pub cooldowns: ResMut<'w, crate::cooldowns::Cooldowns>,
-    /// The live auto-repeat state the bar's flash rides (decision 0137 phase 4).
-    pub auto_repeat: ResMut<'w, crate::ui_action::AutoRepeatActive>,
-    /// Our own running channel (the IsCurrentAction channel leg, decision 0137 phase 4).
-    pub active_channel: ResMut<'w, crate::ui_cast::ActiveChannel>,
-    /// Pre-formatted UIErrorsFrame lines — text the wire already resolved, so there is no
-    /// GlobalStrings key to look up: the death durability notice, `SMSG_NOTIFICATION`, and
-    /// `SMSG_AREA_TRIGGER_MESSAGE`. Drained by `ui_action::feed_actions` beside `UiErrorKeys`.
-    pub ui_error_texts: ResMut<'w, crate::ui_action::UiErrorTexts>,
-    /// The queued on-next-swing strike (the melee-slot half of the cast tracking) — the wire
-    /// resolves it here: GO fires it, a failing result/interrupt kills it.
-    pub queued_melee: ResMut<'w, crate::ui_cast::QueuedMeleeSpell>,
-    /// The aura feed's duration side-table (decisions 0255/0257): the self-only
-    /// `SMSG_UPDATE_AURA_DURATION` lands here keyed by raw slot, timestamped on
-    /// [`Clocks::real`] for the `ui_aura` slot-join.
-    pub aura_durations: ResMut<'w, crate::ui_aura::AuraDurations>,
-    /// The two talent spell-modifier tables (`crate::spell_mods`) — one wire packet is one
-    /// absolute cell, and this is its only writer.
-    pub spell_mods: ResMut<'w, crate::spell_mods::SpellModifiers>,
-}
-
-/// Every animation-bearing or audible message the drain emits, in packet order, plus the
-/// PlayAnimation call-order counter they stamp (decisions 0107, 0137 phase 2, 0280).
-#[derive(SystemParam)]
-pub(crate) struct AnimWriters<'w> {
-    pub server_sounds: MessageWriter<'w, ServerSoundMessage>,
-    pub weather: MessageWriter<'w, WeatherMessage>,
-    pub emotes: MessageWriter<'w, EmoteMessage>,
-    pub swings: MessageWriter<'w, crate::creature_anim::SwingMessage>,
-    pub cast_events: MessageWriter<'w, crate::creature_anim::CastEvent>,
-    pub spell_go_targets: MessageWriter<'w, crate::creature_anim::SpellGoTargets>,
-    /// The floating combat-text feed (decision 0137 phase 2).
-    pub combat_text: MessageWriter<'w, crate::combat_text::CombatTextSpawn>,
-    pub swing_impacts: MessageWriter<'w, crate::creature_anim::SwingImpact>,
-    pub swing_flushes: MessageWriter<'w, crate::creature_anim::SwingFlush>,
-    pub go_lid_open: MessageWriter<'w, crate::go_anim::GoLidOpen>,
-    /// The aggro/alert vocal flare + the pushed-kit play (decision 0280).
-    pub ai_reactions: MessageWriter<'w, AiReactionMessage>,
-    pub kit_pushes: MessageWriter<'w, crate::creature_anim::KitPush>,
-    /// The remote landing predictor's report (decision 0415): a relayed FALL_LAND fires the grunt
-    /// + dust puff for an observed mover, the way the self controller does for us.
-    pub hard_landings: MessageWriter<'w, crate::creature_anim::HardLanding>,
-    /// An observed rider's flourish (`SMSG_MOUNTSPECIAL_ANIM`, decision 0441 P2) — the unit →
-    /// mount-child hop happens in `creature_anim::flourish_to_anim`.
-    pub mount_flourishes: MessageWriter<'w, crate::creature_anim::MountFlourish>,
-    /// The UNIT_COMBAT event feed (the portrait hit indicator, decision 0576) + the
-    /// COMBAT_TEXT_UPDATE feed (the center combat text, decision 0578) — the spell arms'
-    /// self-facing twins of the floating-text spawn.
-    pub unit_combat: MessageWriter<'w, crate::ui_unit::UnitCombatFeedback>,
-    pub combat_text_events: MessageWriter<'w, crate::ui_unit::CombatTextEvent>,
-    /// The sheath setter's queue, which the ATTACKERSTATEUPDATE arm's melee auto-draw writes.
-    pub sheath_requests: MessageWriter<'w, crate::creature_anim::SheathRequest>,
-    /// The GO one-shot Custom play (`SMSG_GAMEOBJECT_CUSTOM_ANIM` — the bobber's bite splash,
-    /// decision 1086), the step-8 sibling of `go_lid_open`.
-    pub go_custom_anim: MessageWriter<'w, crate::go_anim::GoCustomAnim>,
-    /// The pet's bark (`SMSG_PET_ACTION_SOUND`, decision 2039) — `ai_reactions`' sibling: both
-    /// are pure audio that resolves a guid and hands the sound layer a state for the SAME
-    /// `0x623a40` dispatcher.
-    pub pet_talk: MessageWriter<'w, PetTalkMessage>,
-    pub pet_dismiss: MessageWriter<'w, PetDismissSoundMessage>,
-    /// The swing-refusal seam's two edges (`crate::swing_refusal`, decision 2037): the four
-    /// `SMSG_ATTACKSWING_*` refusals, and our own landed swing, which clears their latch. ONE
-    /// writer for both so the drain hands them on in packet order.
-    pub swing_refusals: MessageWriter<'w, crate::swing_refusal::SwingRefusalEdge>,
-    /// The PlayAnimation call-order counter (`creature_anim::PlaySeq`): every animation-bearing
-    /// message this drain emits stamps `next()`, in packet order.
-    pub play_seq: ResMut<'w, crate::creature_anim::PlaySeq>,
-}
-
-/// The read-only reference tables the arms resolve against. Each DBC-backed one is `Option`:
-/// absent if its table failed to load, and every reader degrades rather than drops.
-#[derive(SystemParam)]
-pub(crate) struct Catalogs<'w> {
-    /// The FactionTemplate catalog the combat log's friend/foe split reads (B297). Absent, an
-    /// unresolved unit lands on the friendly side of the classifier rather than losing its lines.
-    pub factions: Option<Res<'w, crate::target::ring::Factions>>,
-    /// The Spell.dbc catalog the cooldown/cast wire laws read.
-    pub spells: Option<Res<'w, crate::ui_action::Spells>>,
-    /// The combat-feedback CVars — the eight display ranges, `CombatLogPeriodicSpells`, and the
-    /// three floating-text gates.
-    pub combat_cvars: crate::ui_chat::combat::CombatFeedbackCvars<'w>,
-    /// The EnvironmentalDamage.dbc 6-slot table (damage type → SpellVisualKit) the
-    /// `SMSG_ENVIRONMENTALDAMAGELOG` arm reads — the fall-landing dust puff.
-    pub env_damage: Option<Res<'w, crate::creature_anim::EnvDamageTable>>,
-    /// The shared AreaTable catalog — the exploration arm's area-id → name resolve (decision
-    /// 0828) — and the race-keyed discovery-jingle catalog (decision 0829).
-    pub area_table: Option<Res<'w, crate::area::AreaTableRes>>,
-    pub exploration_sounds: Option<Res<'w, crate::sound::ExplorationSounds>>,
-    /// The map the guard's directions marker is stamped with.
-    pub current_map: Option<Res<'w, benilla_world::world_map::CurrentMap>>,
-    /// Guild Member Alert (decision 1589) — the CVar knob the sign-on/sign-off pair's display
-    /// condition reads; see `ui_guild::apply::event` for the four conjuncts.
-    pub guild_notify: Res<'w, crate::ui_guild::GuildMemberNotify>,
-}
diff --git a/crates/benilla-app/src/net/apply/seam_tests.rs b/crates/benilla-app/src/net/apply/seam_tests.rs
new file mode 100644
index 00000000..bb34fbef
--- /dev/null
+++ b/crates/benilla-app/src/net/apply/seam_tests.rs
@@ -0,0 +1,266 @@
+//! **Every packet's handler sees what the packets before it did** — the property 2306 measured
+//! across the migration's seam (a run boundary was a command flush mid-frame) and the one the
+//! whole dispatch rests on now that every packet is its own handler with its commands applied
+//! before the next (decision 2327). The first test drives the real drain on the built client
+//! over one frame two ways and compares; the rest are 1478's speed-staging laws, which used to
+//! be unit tests over a staging map and are now the same laws over consecutive packets.
+
+use benilla_protocol::field::{FIELD_UNIT_HEALTH, FIELD_UNIT_LEVEL, FIELD_UNIT_MAXHEALTH};
+use benilla_protocol::messages::{ObjectType, SpeedKind, SplineMode};
+use benilla_protocol::{EntityKind, MoveSpeeds, ObjectFields, SessionEvent};
+use bevy::prelude::*;
+
+use crate::net::{GuidIndex, NetEvents, ObjectStore, UnitMoveModes, UnitSpeeds};
+
+const GUID: u64 = 0xF130_0000_1234_0001;
+
+fn create() -> SessionEvent {
+    SessionEvent::ObjectCreate {
+        guid: GUID,
+        kind: EntityKind::Unit,
+        display_id: None,
+        position: [1.0, 2.0, 3.0],
+        orientation: 0.0,
+        scale: 1.0,
+        speeds: Some(MoveSpeeds {
+            walk: 2.5,
+            run: 7.0,
+            run_back: 4.5,
+            swim: 4.7,
+            swim_back: 2.5,
+            turn_rate: std::f32::consts::PI,
+        }),
+        mover: None,
+        transport_progress: None,
+        transport: None,
+        spline: None,
+        fields: ObjectFields::from_pairs(&[
+            (FIELD_UNIT_HEALTH, 100),
+            (FIELD_UNIT_MAXHEALTH, 100),
+            (FIELD_UNIT_LEVEL, 9),
+        ])
+        .into_created(ObjectType::Unit),
+    }
+}
+
+/// What the object layer does to a unit born this frame: a values delta, a speed change, a
+/// granted mode, a second delta.
+fn updates() -> Vec<SessionEvent> {
+    vec![
+        SessionEvent::ObjectValues {
+            guid: GUID,
+            fields: ObjectFields::from_pairs(&[(FIELD_UNIT_HEALTH, 60)]),
+        },
+        SessionEvent::SpeedChanged {
+            guid: GUID,
+            kind: SpeedKind::Run,
+            speed: 14.0,
+        },
+        SessionEvent::SplineMoveMode {
+            guid: GUID,
+            mode: SplineMode::Root,
+            apply: true,
+        },
+        SessionEvent::ObjectValues {
+            guid: GUID,
+            fields: ObjectFields::from_pairs(&[(FIELD_UNIT_LEVEL, 10)]),
+        },
+    ]
+}
+
+/// A packet of another subsystem's — any would do; the mailbox's needs no open window.
+fn claimed() -> SessionEvent {
+    SessionEvent::NextMailTime { seconds: -86400.0 }
+}
+
+/// One frame of the real drain over `events`; what the unit ended up as.
+fn drained(events: Vec<SessionEvent>) -> (Vec<(u16, u32)>, MoveSpeeds, UnitMoveModes) {
+    let mut app = crate::game_plugins::schedule_tests::headless_client();
+    let (tx, rx) = crossbeam_channel::unbounded();
+    app.insert_resource(NetEvents(rx));
+    for ev in events {
+        tx.send(ev).unwrap();
+    }
+    let world = app.world_mut();
+    super::apply_net_updates(world);
+    let e = *world
+        .resource::<GuidIndex>()
+        .0
+        .get(&GUID)
+        .expect("the create indexed the unit");
+    let fields = world
+        .get::<ObjectStore>(e)
+        .expect("the store landed")
+        .0
+        .raw_fields()
+        .collect();
+    let speeds = world.get::<UnitSpeeds>(e).expect("the speeds landed").0;
+    let modes = *world.get::<UnitMoveModes>(e).expect("the modes landed");
+    (fields, speeds, modes)
+}
+
+#[test]
+fn a_foreign_packet_between_a_create_and_its_updates_changes_nothing() {
+    // The create and everything after it back to back, the mailbox's packet last.
+    let mut one_run = vec![create()];
+    one_run.extend(updates());
+    one_run.push(claimed());
+    // A foreign packet after the create and between every update.
+    let mut split = vec![create()];
+    for ev in updates() {
+        split.push(claimed());
+        split.push(ev);
+    }
+
+    let (fields, speeds, modes) = drained(one_run);
+    let (split_fields, split_speeds, split_modes) = drained(split);
+
+    // The frame's own meaning, so the comparison below cannot pass on two empty results.
+    assert!(fields.contains(&(FIELD_UNIT_HEALTH, 60)), "{fields:?}");
+    assert!(fields.contains(&(FIELD_UNIT_LEVEL, 10)), "{fields:?}");
+    assert!(fields.contains(&(FIELD_UNIT_MAXHEALTH, 100)), "{fields:?}");
+    assert_eq!(speeds.run, 14.0);
+    assert_eq!(speeds.walk, 2.5);
+    assert!(modes.rooted());
+
+    assert_eq!(split_fields, fields);
+    assert_eq!(split_speeds.run, speeds.run);
+    assert_eq!(split_speeds.walk, speeds.walk);
+    assert_eq!(split_modes, modes);
+}
+
+/// A create block with this run speed, or none.
+fn create_with_speeds(speeds: Option<MoveSpeeds>) -> SessionEvent {
+    match create() {
+        SessionEvent::ObjectCreate {
+            guid,
+            kind,
+            display_id,
+            position,
+            orientation,
+            scale,
+            mover,
+            transport_progress,
+            transport,
+            spline,
+            fields,
+            ..
+        } => SessionEvent::ObjectCreate {
+            guid,
+            kind,
+            display_id,
+            position,
+            orientation,
+            scale,
+            speeds,
+            mover,
+            transport_progress,
+            transport,
+            spline,
+            fields,
+        },
+        _ => unreachable!(),
+    }
+}
+
+fn force_run(speed: f32) -> SessionEvent {
+    SessionEvent::ForceSpeedChange {
+        guid: GUID,
+        kind: SpeedKind::Run,
+        counter: 1,
+        speed,
+    }
+}
+
+/// One frame of the real drain; the unit's live speed set, if any.
+fn speeds_after(events: Vec<SessionEvent>) -> Option<MoveSpeeds> {
+    let mut app = crate::game_plugins::schedule_tests::headless_client();
+    let (tx, rx) = crossbeam_channel::unbounded();
+    app.insert_resource(NetEvents(rx));
+    for ev in events {
+        tx.send(ev).unwrap();
+    }
+    let world = app.world_mut();
+    super::apply_net_updates(world);
+    let e = *world.resource::<GuidIndex>().0.get(&GUID)?;
+    world.get::<UnitSpeeds>(e).map(|s| s.0)
+}
+
+/// **B213, pinned at the drain.** vmangos's `HandleMoveWorldportAckOpcode` sends the self create
+/// block (`Map::Add` → `SendInitSelf`, still carrying the mount's 11.2 yd/s) and then, three
+/// statements later, strips the mount because the destination map forbids one — so
+/// `SMSG_FORCE_RUN_SPEED_CHANGE` 7.0 rides the same tick. In wire order the change wins; before
+/// 1478 the create's *deferred* `UnitSpeeds` insert landed last and `.tele` into BWL left the
+/// avatar running at mount speed on foot. Under a handler per packet the create's insert has
+/// landed before the change's handler runs, and the change edits the live component.
+#[test]
+fn a_force_change_beats_a_create_from_the_same_frame() {
+    let mounted = MoveSpeeds {
+        run: 11.2,
+        ..MoveSpeeds {
+            walk: 2.5,
+            run: 7.0,
+            run_back: 4.5,
+            swim: 4.7,
+            swim_back: 2.5,
+            turn_rate: std::f32::consts::PI,
+        }
+    };
+    let s = speeds_after(vec![create_with_speeds(Some(mounted)), force_run(7.0)])
+        .expect("the create landed a speed set");
+    assert_eq!(s.run, 7.0, "the dismount is the newer packet");
+    assert_eq!(
+        s.walk, 2.5,
+        "the other slots still come from the create block"
+    );
+}
+
+/// The reverse order is just as much the wire's order: a create block is the server's newest
+/// snapshot of the mover, so one arriving *after* a change replaces it whole.
+#[test]
+fn a_create_after_a_change_replaces_it() {
+    let on_foot = MoveSpeeds {
+        walk: 2.5,
+        run: 7.0,
+        run_back: 4.5,
+        swim: 4.7,
+        swim_back: 2.5,
+        turn_rate: std::f32::consts::PI,
+    };
+    let mounted = MoveSpeeds {
+        run: 11.2,
+        ..on_foot
+    };
+    let s = speeds_after(vec![
+        create_with_speeds(Some(on_foot)),
+        force_run(9.0),
+        create_with_speeds(Some(mounted)),
+    ])
+    .expect("the create landed a speed set");
+    assert_eq!(s.run, 11.2);
+}
+
+/// A one-slot change on a mover that already exists keeps every other slot it isn't addressing.
+#[test]
+fn a_change_on_a_live_mover_keeps_its_other_slots() {
+    let on_foot = MoveSpeeds {
+        walk: 2.5,
+        run: 7.0,
+        run_back: 4.5,
+        swim: 4.7,
+        swim_back: 2.5,
+        turn_rate: std::f32::consts::PI,
+    };
+    let s = speeds_after(vec![create_with_speeds(Some(on_foot)), force_run(11.2)])
+        .expect("the create landed a speed set");
+    assert_eq!(s.run, 11.2);
+    assert_eq!(s.run_back, on_foot.run_back);
+    assert_eq!(s.turn_rate, on_foot.turn_rate);
+}
+
+/// A change with nowhere to land — a mover whose create carried no movement block — invents no
+/// speed set: nothing is inserted for a set that never existed.
+#[test]
+fn a_change_with_no_speed_set_invents_none() {
+    assert!(speeds_after(vec![create_with_speeds(None), force_run(7.0)]).is_none());
+}
diff --git a/crates/benilla-app/src/net/apply/world.rs b/crates/benilla-app/src/net/apply/world.rs
deleted file mode 100644
index 846e8806..00000000
--- a/crates/benilla-app/src/net/apply/world.rs
+++ /dev/null
@@ -1,83 +0,0 @@
-//! World-feed arm bodies for [`super::apply_net_updates`]'s dispatch match — what the server
-//! pushes about the *world* rather than about an entity's own state: the three ambient audio
-//! triggers, the weather change, and the world-state table the UI's `$<n>w` tokens read. Each
-//! `pub(super)` fn here is exactly one arm's body; the match at the call site stays the dispatcher,
-//! one call per arm.
-
-use bevy::prelude::*;
-
-use crate::world_state::WorldStates;
-
-use super::super::{GuidIndex, ServerSoundKind, ServerSoundMessage};
-use benilla_world::weather::WeatherMessage;
-
-/// `SMSG_PLAY_SOUND` — a 2D (non-positional) one-shot.
-pub(super) fn play_sound(sound_id: u32, out: &mut MessageWriter<ServerSoundMessage>) {
-    out.write(ServerSoundMessage {
-        kind: ServerSoundKind::Sound2d,
-        sound_id,
-        source: None,
-    });
-}
-
-/// `SMSG_PLAY_MUSIC` — the zone/event music track.
-pub(super) fn play_music(music_id: u32, out: &mut MessageWriter<ServerSoundMessage>) {
-    out.write(ServerSoundMessage {
-        kind: ServerSoundKind::Music,
-        sound_id: music_id,
-        source: None,
-    });
-}
-
-/// `SMSG_PLAY_OBJECT_SOUND` — a one-shot anchored to a streamed object (silent while its guid
-/// isn't streamed in: the mixer has nowhere to place it).
-pub(super) fn play_object_sound(
-    sound_id: u32,
-    guid: u64,
-    index: &GuidIndex,
-    out: &mut MessageWriter<ServerSoundMessage>,
-) {
-    out.write(ServerSoundMessage {
-        kind: ServerSoundKind::ObjectSound,
-        sound_id,
-        source: index.0.get(&guid).copied(),
-    });
-}
-
-/// `SMSG_WEATHER` — the zone's weather change (`instant` on zone entry, a ramp otherwise).
-pub(super) fn weather(
-    weather_type: u32,
-    grade: f32,
-    sound_id: u32,
-    instant: bool,
-    out: &mut MessageWriter<WeatherMessage>,
-) {
-    out.write(WeatherMessage {
-        weather_type,
-        grade,
-        sound_id,
-        instant,
-    });
-}
-
-/// `SMSG_INIT_WORLD_STATES` / `SMSG_UPDATE_WORLD_STATE` — both wires funnel into the one setter,
-/// as the reference's own handler does.
-///
-/// An **init clears the table first** and records its `(map, zone)` as the world-state UI's display
-/// filter — the reference's `0x4c5650`, which runs before the pair loop (wow-re
-/// `system/ui/scratch/worldstate-ui-law.md`; rationale on [`crate::world_state`]). The order below
-/// is that handler's: clear + scope, then the packet's pairs.
-pub(super) fn world_states(
-    scope: Option<(u32, u32)>,
-    states: Vec<(u32, u32)>,
-    world_states: &mut WorldStates,
-) {
-    if let Some((map, zone)) = scope {
-        debug!(
-            "world states: map {map} zone {zone}, {} entries",
-            states.len()
-        );
-        world_states.init_scope(map, zone);
-    }
-    world_states.write(&states);
-}
diff --git a/crates/benilla-app/src/net/handlers.rs b/crates/benilla-app/src/net/handlers.rs
index 96b54742..b1426a5e 100644
--- a/crates/benilla-app/src/net/handlers.rs
+++ b/crates/benilla-app/src/net/handlers.rs
@@ -2,7 +2,7 @@
 //! arrival side, and the cut 2265 §A1 asked for between the net bridge and the game windows.
 //!
 //! The real client keeps an opcode → handler table inside `NetClient` (`+0x74`, 828 slots; 387
-//! registrations by 37 subsystem clusters — wow-re `net.md`) and its dispatcher `0x537aa0` knows
+//! registrations by 37 subsystem clusters) and its dispatcher `0x537aa0` knows
 //! none of them: it looks the opcode up and calls what it finds, **in packet order**, discarding an
 //! unregistered opcode in silence. Here the table is [`NetHandlers`]: a [`SessionEventKind`] →
 //! handlers map that every subsystem fills for itself through [`NetHandlerApp::net_handler`], and
@@ -16,14 +16,9 @@
 //! that arrived in one drain would swap. The table keeps the one property 2265 said must survive
 //! any split: one frame, packet order, before anything else runs.
 //!
-//! **The migration.** The dispatch `match` in `apply.rs` still owns every kind no subsystem has
-//! claimed. One drain runs in two halves: the unclaimed events through the match first, in packet
-//! order, then the claimed ones through the table, in packet order — so a window handler always
-//! sees this frame's object updates, whatever the interleaving. A kind is owned by exactly one of
-//! the two, checked on the built app by `every_session_event_kind_has_one_owner`; the one
-//! exception is [`BROADCAST`], a session-end the match still handles and peeled windows also listen
-//! to, which reaches both. When the last family leaves the match, the match, the halves and the
-//! broadcast list go with it.
+//! **The table is the whole dispatch** (since 2327). Every kind has at least one handler, read
+//! off the built client by `every_session_event_kind_has_one_owner`; the drain's own match, the
+//! runs it took across the seam and the broadcast list (2305, 2306, 2326) are gone.
 
 use std::collections::HashMap;
 
@@ -40,17 +35,7 @@ pub(crate) struct NetHandlers {
     by_kind: HashMap<SessionEventKind, Vec<Handler>>,
 }
 
-/// The kinds the dispatch match still owns **and** peeled subsystems listen to — a session end,
-/// which every window that dies with the socket answers for itself. Cloned to the table after the
-/// match has run. Empty once the session family itself is peeled.
-pub(crate) const BROADCAST: &[SessionEventKind] = &[SessionEventKind::Disconnected];
-
 impl NetHandlers {
-    /// Is there at least one handler for this kind?
-    pub(crate) fn handles(&self, kind: SessionEventKind) -> bool {
-        self.by_kind.contains_key(&kind)
-    }
-
     /// Every kind with a handler, with the handlers' names in registration order — the owner
     /// test's view of the table.
     #[cfg(test)]
@@ -61,6 +46,24 @@ impl NetHandlers {
             .collect()
     }
 
+    /// Run **every** registered handler once with `ev` — whatever kind it registered for — and
+    /// name the ones that could not run. A handler matches on its own kind and ignores the rest,
+    /// so what this exercises is the part a wrong-kind event still reaches: the system's
+    /// parameters being fetched from this world.
+    #[cfg(test)]
+    pub(crate) fn probe(&self, world: &mut World, ev: &SessionEvent) -> Vec<String> {
+        let mut failed = Vec::new();
+        for (kind, list) in &self.by_kind {
+            for (id, name) in list {
+                if let Err(e) = world.run_system_with(*id, ev.clone()) {
+                    failed.push(format!("{kind:?}: `{name}` — {e}"));
+                }
+            }
+        }
+        failed.sort();
+        failed
+    }
+
     fn push(&mut self, kind: SessionEventKind, handler: Handler) {
         self.by_kind.entry(kind).or_default().push(handler);
     }
@@ -115,30 +118,11 @@ impl NetHandlerApp for App {
     }
 }
 
-/// One drain's dispatch: the events the table does not own go through `unclaimed` first — the
-/// dispatch match, in packet order — then the owned ones run through the table, in packet order.
-/// A [`BROADCAST`] kind reaches both.
-pub(crate) fn dispatch(
-    world: &mut World,
-    events: Vec<SessionEvent>,
-    unclaimed: impl FnOnce(&mut World, Vec<SessionEvent>),
-) {
+/// One drain's dispatch, **in wire order**: every event runs its handlers in place, each
+/// handler's commands applied before the next event's.
+pub(crate) fn dispatch(world: &mut World, events: Vec<SessionEvent>) {
     let handlers = world.remove_resource::<NetHandlers>().unwrap_or_default();
-    let mut to_match = Vec::with_capacity(events.len());
-    let mut to_table = Vec::new();
     for ev in events {
-        let kind = SessionEventKind::from(&ev);
-        if !handlers.handles(kind) {
-            to_match.push(ev);
-        } else if BROADCAST.contains(&kind) {
-            to_table.push(ev.clone());
-            to_match.push(ev);
-        } else {
-            to_table.push(ev);
-        }
-    }
-    unclaimed(world, to_match);
-    for ev in to_table {
         handlers.run(world, ev);
     }
     world.insert_resource(handlers);
@@ -168,13 +152,6 @@ mod tests {
         log.0.push("logged_out_too".into());
     }
 
-    fn on_disconnected(In(ev): In<SessionEvent>, mut log: ResMut<Log>) {
-        let SessionEvent::Disconnected { reason, .. } = ev else {
-            panic!("the table routes by kind");
-        };
-        log.0.push(format!("disconnected:{reason}"));
-    }
-
     fn app() -> App {
         let mut app = App::new();
         app.add_plugins(MinimalPlugins).init_resource::<Log>();
@@ -189,36 +166,29 @@ mod tests {
     }
 
     fn run(app: &mut App, events: Vec<SessionEvent>) -> Vec<String> {
-        dispatch(app.world_mut(), events, |world, unclaimed| {
-            let mut log = world.resource_mut::<Log>();
-            for ev in unclaimed {
-                log.0
-                    .push(format!("match:{:?}", SessionEventKind::from(&ev)));
-            }
-        });
+        dispatch(app.world_mut(), events);
         std::mem::take(&mut app.world_mut().resource_mut::<Log>().0)
     }
 
     #[test]
-    fn owned_kinds_run_in_packet_order_after_the_match_has_run_the_rest() {
+    fn events_run_in_wire_order_and_an_unhandled_kind_is_skipped() {
         let mut app = app();
         app.net_handler(SessionEventKind::LoginQueued, on_queued)
             .net_handler(SessionEventKind::LoggedOut, on_logged_out);
+        let stage = || SessionEvent::LoginStage {
+            stage: benilla_protocol::LoginStage::Connecting,
+        };
         let log = run(
             &mut app,
             vec![
                 queued(1),
-                SessionEvent::LoginStage {
-                    stage: benilla_protocol::LoginStage::Connecting,
-                },
+                stage(),
                 SessionEvent::LoggedOut,
                 queued(2),
+                stage(),
             ],
         );
-        assert_eq!(
-            log,
-            vec!["match:LoginStage", "queued:1", "logged_out", "queued:2"]
-        );
+        assert_eq!(log, vec!["queued:1", "logged_out", "queued:2"]);
     }
 
     #[test]
@@ -234,88 +204,159 @@ mod tests {
         );
     }
 
-    #[test]
-    fn a_broadcast_kind_reaches_the_match_and_the_table() {
-        let mut app = app();
-        app.net_handler(SessionEventKind::Disconnected, on_disconnected);
-        let log = run(
-            &mut app,
-            vec![SessionEvent::Disconnected {
-                reason: "socket".into(),
-                end: benilla_protocol::SessionEnd::Lost,
-            }],
-        );
-        assert_eq!(log, vec!["match:Disconnected", "disconnected:socket"]);
-    }
-
-    #[test]
-    fn with_no_table_at_all_everything_goes_to_the_match() {
-        let mut app = app();
-        let log = run(&mut app, vec![SessionEvent::LoggedOut, queued(0)]);
-        assert_eq!(log, vec!["match:LoggedOut", "match:LoginQueued"]);
-        assert!(app.world().resource::<NetHandlers>().census().is_empty());
-    }
-
-    /// **Every kind has exactly one owner** — the dispatch match in `net/apply.rs` or the table,
-    /// read off the built client — and the [`BROADCAST`] rows are the only kinds in both. A kind
-    /// neither owns is a packet the client decodes and then drops on the floor.
+    /// **Every kind has a handler**, read off the built client. A kind with none is a packet the
+    /// client decodes and then drops on the floor — the reference discards an unregistered
+    /// opcode in silence; this says so at test time.
     #[test]
     fn every_session_event_kind_has_one_owner() {
-        use std::collections::BTreeSet;
-        let source = std::fs::read_to_string(
-            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/net/apply.rs"),
-        )
-        .expect("the drain's source");
-        let stripped = regex_lite_strip_comments(&source);
-        let by_name: HashMap<String, SessionEventKind> = SessionEventKind::all()
-            .map(|k| (format!("{k:?}"), k))
-            .collect();
-        let mut in_match: BTreeSet<SessionEventKind> = BTreeSet::new();
-        for token in stripped.split("SessionEvent::").skip(1) {
-            let name: String = token
-                .chars()
-                .take_while(|c| c.is_ascii_alphanumeric() || *c == '_')
-                .collect();
-            if let Some(k) = by_name.get(&name) {
-                in_match.insert(*k);
-            }
-        }
         let mut app = crate::game_plugins::schedule_tests::headless_client();
         let table = app.world_mut().resource::<NetHandlers>().census();
-        let in_table: BTreeSet<SessionEventKind> = table.keys().copied().collect();
-        let mut problems = Vec::new();
-        for kind in SessionEventKind::all() {
-            let m = in_match.contains(&kind);
-            let t = in_table.contains(&kind);
-            let b = BROADCAST.contains(&kind);
-            match (m, t, b) {
-                (true, true, true) | (true, false, false) | (false, true, false) => {}
-                (true, true, false) => problems.push(format!(
-                    "{kind:?}: owned by the match AND handled by {:?} — a peeled kind leaves the match (or is a BROADCAST row)",
-                    table[&kind]
-                )),
-                (true, false, true) => problems.push(format!(
-                    "{kind:?}: a BROADCAST row nobody listens to — drop the row"
-                )),
-                (false, true, true) => problems.push(format!(
-                    "{kind:?}: a BROADCAST row the match no longer owns — drop the row"
-                )),
-                (false, false, _) => problems.push(format!(
-                    "{kind:?}: decoded and dropped — no arm in the match, no handler in the table"
-                )),
+        let unowned: Vec<String> = SessionEventKind::all()
+            .filter(|k| !table.contains_key(k))
+            .map(|k| format!("{k:?}: decoded and dropped — no handler in the table"))
+            .collect();
+        eprintln!(
+            "session event kinds: {} — {} in the handler table ({} handlers)",
+            SessionEventKind::all().count(),
+            table.len(),
+            table.values().map(Vec::len).sum::<usize>(),
+        );
+        assert!(unowned.is_empty(), "{}", unowned.join("\n"));
+    }
+
+    /// **Every registered handler can run on the built client.** The dispatch match's parameters
+    /// were fetched every frame from the first, so a resource nobody inserted failed at boot; a
+    /// handler's are fetched when its packet arrives, which for a rare packet is never in a
+    /// smoke run. This fetches them all, once, on the headless client — every plugin built and
+    /// finished — by running each handler with an event of a kind it ignores.
+    #[test]
+    fn every_registered_handler_can_run_on_the_built_client() {
+        let mut app = crate::game_plugins::schedule_tests::headless_client();
+        let world = app.world_mut();
+        let handlers = world
+            .remove_resource::<NetHandlers>()
+            .expect("the built client registers handlers");
+        let failed = handlers.probe(world, &SessionEvent::LoggedOut);
+        let count: usize = handlers.census().values().map(Vec::len).sum();
+        eprintln!(
+            "net handlers probed on the built client: {count}, {} failed",
+            failed.len()
+        );
+        assert!(failed.is_empty(), "{}", failed.join("\n"));
+    }
+
+    /// **A handler matches the kind it registered for.** `net_handler(K::X, on_y)` routes X to
+    /// `on_y`, and `on_y` opens with `if let SessionEvent::X` — two spellings of one kind, which
+    /// nothing else ties together: a handler registered under the wrong kind compiles, runs, and
+    /// silently ignores its packet. Read off the source: every registration's handler names its
+    /// kind in its body. A session-end listener takes `In(_)` and is exempt.
+    #[test]
+    fn every_handler_names_the_kind_it_registered_for() {
+        let src = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
+        let mut files = Vec::new();
+        let mut dirs = vec![src];
+        while let Some(dir) = dirs.pop() {
+            for entry in std::fs::read_dir(dir).expect("src") {
+                let path = entry.expect("entry").path();
+                if path.is_dir() {
+                    dirs.push(path);
+                } else if path.extension().is_some_and(|e| e == "rs") {
+                    files.push(path);
+                }
             }
         }
-        eprintln!(
-            "session event kinds: {} — {} in the dispatch match, {} in the handler table ({} handlers), {} broadcast",
-            SessionEventKind::all().count(),
-            in_match.len(),
-            in_table.len(),
-            table.values().map(Vec::len).sum::<usize>(),
-            BROADCAST.len()
+        let (mut seen, mut problems) = (0, Vec::new());
+        for path in files {
+            if path.ends_with("net/handlers.rs") {
+                continue; // this file's own fixtures and prose
+            }
+            let text = regex_lite_strip_comments(&std::fs::read_to_string(&path).expect("source"));
+            for call in text.split("net_handler(").skip(1) {
+                let Some((args, _)) = call.split_once(')') else {
+                    continue;
+                };
+                let Some((kind, handler)) = args.split_once(',') else {
+                    continue;
+                };
+                let kind = kind.trim().rsplit("::").next().unwrap_or_default();
+                // rustfmt breaks a long call one argument a line, with a trailing comma.
+                let handler = handler.trim().trim_end_matches(',').trim_end();
+                seen += 1;
+                if kind == "Disconnected" {
+                    continue;
+                }
+                let Some(at) = text.find(&format!("fn {handler}(")) else {
+                    problems.push(format!(
+                        "{}: `{handler}` is not in the file that registers it",
+                        path.display()
+                    ));
+                    continue;
+                };
+                // The handler's own lines: from its `fn` to the next item's.
+                let body: Vec<&str> = text[at..]
+                    .lines()
+                    .enumerate()
+                    .take_while(|(i, l)| {
+                        let l = l.trim_start();
+                        *i == 0
+                            || !(l.starts_with("fn ")
+                                || l.starts_with("pub")
+                                || l.starts_with("#["))
+                    })
+                    .map(|(_, l)| l)
+                    .collect();
+                // The whole variant name, not a prefix of one: `SessionEvent::Chat` is the head
+                // of `ChatPlayerNotFound` too, so a bare `contains` let a handler registered for
+                // `Chat` pass by matching a cousin (six kinds are prefixes of others).
+                let names_kind = {
+                    let body = body.join("\n");
+                    let needle = format!("SessionEvent::{kind}");
+                    body.match_indices(&needle).any(|(at, hit)| {
+                        !body[at + hit.len()..]
+                            .starts_with(|c: char| c.is_alphanumeric() || c == '_')
+                    })
+                };
+                if !names_kind {
+                    problems.push(format!(
+                        "{}: `{handler}` is registered for {kind} and never names it",
+                        path.display()
+                    ));
+                }
+            }
+        }
+        let registered: usize = crate::game_plugins::schedule_tests::headless_client()
+            .world()
+            .resource::<NetHandlers>()
+            .census()
+            .values()
+            .map(Vec::len)
+            .sum();
+        assert_eq!(
+            seen, registered,
+            "a registration this scan cannot read — spell it `net_handler(K::Kind, handler)`"
         );
         assert!(problems.is_empty(), "{}", problems.join("\n"));
     }
 
+    #[derive(Resource)]
+    struct Absent;
+
+    fn needs_what_nobody_inserted(In(_): In<SessionEvent>, _absent: Res<Absent>) {}
+
+    #[test]
+    fn the_probe_names_a_handler_whose_resource_is_missing() {
+        let mut app = app();
+        app.net_handler(SessionEventKind::LoggedOut, on_logged_out)
+            .net_handler(SessionEventKind::LoginQueued, needs_what_nobody_inserted);
+        let handlers = app.world_mut().remove_resource::<NetHandlers>().unwrap();
+        let failed = handlers.probe(app.world_mut(), &SessionEvent::LoggedOut);
+        assert_eq!(failed.len(), 1, "{failed:?}");
+        assert!(
+            failed[0].contains("needs_what_nobody_inserted"),
+            "{failed:?}"
+        );
+    }
+
     /// `//` comments out, so a variant named in prose does not count as an arm.
     fn regex_lite_strip_comments(s: &str) -> String {
         s.lines()
diff --git a/crates/benilla-app/src/net/io.rs b/crates/benilla-app/src/net/io.rs
index 41baf964..6df900a3 100644
--- a/crates/benilla-app/src/net/io.rs
+++ b/crates/benilla-app/src/net/io.rs
@@ -114,16 +114,16 @@ pub(super) struct Parks {
 /// beat rather than the screen.
 const REALM_REFRESH_TIMEOUT: Duration = Duration::from_secs(5);
 
-/// The keepalive cadence — the real client's 30 000 ms ping timer (VERIFIED wow-re net W1,
-/// `0x537ff0`: the connection drain arms the next ping 30 s out). vmangos *kicks* a player socket
+/// The keepalive cadence — the real client's 30 000 ms ping timer (`0x537ff0`: the connection
+/// drain arms the next ping 30 s out). vmangos *kicks* a player socket
 /// whose pings repeat faster than 27 s apart more than twice (`WorldSocket::_HandlePing`), so this
 /// must never shrink below that.
 const PING_INTERVAL: Duration = Duration::from_secs(30);
 
 /// How many round trips [`PingClock`] keeps — **fifteen**, which is the reference's *usable*
-/// depth even though its array holds sixteen (VERIFIED, wow-re `system/net`, 4-agent §5).
+/// depth even though its array holds sixteen.
 ///
-/// `conn+0x1a6c` is 16 u32 slots, and W1's shorthand "head/tail wrap 16" is about that array. But
+/// `conn+0x1a6c` is 16 u32 slots, and its head/tail indices wrap at 16. But
 /// the averager treats `read == write` as its **empty** sentinel (`0x537fa8`), so `HandlePong`'s
 /// conditional read-index advance (`0x537de8`) makes the full state unreachable: the 16th sample
 /// pushes the oldest out of view as it lands, and every reading from then on is over 15. Our
@@ -133,7 +133,7 @@ const RTT_RING: usize = 15;
 
 /// **The connection's ping/RTT stats** — the reference's own per-connection stats block
 /// (`conn+0x1a6c` ring, `+0x1aac/+0x1ab0` head/tail, `+0x1a64` send stamp, `+0x1a68` expected
-/// sequence; wow-re net W1), behind the same one lock it guards them with (`conn+0x1ac0`'s
+/// sequence), behind the same one lock it guards them with (`conn+0x1ac0`'s
 /// critical section, taken by both `HandlePong 0x537d60` and the `GetNetStats` math at
 /// `0x537f20`).
 ///
@@ -1025,8 +1025,8 @@ fn writer_loop(
 ) {
     let mut writer: Option<WorldWriter> = None;
     let mut warned = 0u32;
-    // **Armed by the connection, re-armed by each send — never free-running** (wow-re net,
-    // `0x537ff0`: `now - lastSent - 30000 >= 0`, evaluated at the connection's own drain tail,
+    // **Armed by the connection, re-armed by each send — never free-running** (`0x537ff0`:
+    // `now - lastSent - 30000 >= 0`, evaluated at the connection's own drain tail,
     // and `0x537bcf` stamps `lastSent` with the current tick at connect). It was a process-
     // lifetime `tick`, which is a different clock in two ways that both showed: the first ping of
     // a session landed anywhere in the 30 s after entering the world rather than at the end of it
diff --git a/crates/benilla-app/src/net/motion.rs b/crates/benilla-app/src/net/motion.rs
index 2dc7465e..6acdfd4f 100644
--- a/crates/benilla-app/src/net/motion.rs
+++ b/crates/benilla-app/src/net/motion.rs
@@ -60,9 +60,8 @@ pub(super) fn wire_yaw(orientation: f32) -> Quat {
 ///
 /// The reference builds a GO's render matrix from that quaternion — `0x5f7910` (the every-frame
 /// slot-13 Animate) composes `GetPosition` → gx-rotate by the 4 floats at GO-fields `+0x10` →
-/// gx-scale, and the same 4×4 (`obj+0x218`) is what its collision reads (wow-re
-/// `object-layer/scratch/w2c1.md` §Q2/§Q3). `GAMEOBJECT_FACING` is a *separate* accessor
-/// (`0x5f9fb0`) that the placement never consults.
+/// gx-scale, and the same 4×4 (`obj+0x218`) is what its collision reads. `GAMEOBJECT_FACING` is a
+/// *separate* accessor (`0x5f9fb0`) that the placement never consults.
 ///
 /// A yaw is the special case here, not a simplification of it: vmangos copies `rotation0/1` from the
 /// spawn row verbatim and fills `rotation2/3` from the facing when the row leaves them zero
diff --git a/crates/benilla-app/src/net/motion/facing.rs b/crates/benilla-app/src/net/motion/facing.rs
index 44ffa0ed..f7f58b04 100644
--- a/crates/benilla-app/src/net/motion/facing.rs
+++ b/crates/benilla-app/src/net/motion/facing.rs
@@ -3,8 +3,7 @@
 //! its `+0xc98` box filter — with the [`FacingStep`] latch the anim layer's turn-shuffle reads
 //! (decision 0123).
 //!
-//! **A unit has two facings and only one of them is the wire's** (wow-re
-//! `object-layer/scratch/interaction-facing.md`, `body-facing-pipeline.md`'s 2026-07-04 CORRECTION).
+//! **A unit has two facings and only one of them is the wire's**.
 //! The raw movement facing `CMovement+0x1c` is what the server put there; the *rendered character
 //! body root* is the smoothed display facing `CGUnit+0xc94`, and the client turns that one
 //! client-side, every frame, toward a goal it picks from an ordered chain. Two of that chain's goals
@@ -60,8 +59,8 @@ const UNIT_FLAG_STUNNED: u32 = 0x0004_0000;
 
 /// The `Emotes.dbc` `EmoteFlags` bit that **permits** the target/interaction facing while a looping
 /// state emote is active (`600d95`/`600d98 test ch,0x20`). A valid emote-state record *without* this
-/// bit suppresses the whole chain and pins the unit to its raw facing; the bit's *name* is INFERRED
-/// (wow-re `interaction-facing.md` §2) — the byte fact is the condition tested.
+/// bit suppresses the whole chain and pins the unit to its raw facing; the bit's *name* is
+/// inferred — the byte fact is the condition tested.
 const EMOTE_PERMITS_FACING: u32 = 0x2000;
 
 /// A stationary unit's display-facing state — the client's `CGUnit+0xc98` goal plus its
@@ -80,8 +79,8 @@ pub(crate) struct DisplayFacing {
 
 /// A stationary unit's display facing **moved this frame**: the signed yaw the pump applied (WoW
 /// yaw, positive = counterclockwise = turning left). The anim layer folds it into the unit's turn
-/// view — the client's facing-delta shuffle latch (`0x607ed0` bits `0x800`/`0x1000`, wow-re
-/// `loop-replay-fidget.md` §5b; decision 0123) — so a squaring-up creature foot-shuffles instead of
+/// view — the client's facing-delta shuffle latch (`0x607ed0` bits `0x800`/`0x1000`;
+/// decision 0123) — so a squaring-up creature foot-shuffles instead of
 /// pivoting frozen, and each shuffle's return to Stand re-rolls the idle variation.
 ///
 /// **The applied step, not the remaining gap** (decision 1655): the client's latch reads
@@ -199,8 +198,7 @@ fn filter_step(cur: f32, goal: f32, hist: &mut [f32; 4]) -> f32 {
 /// Turn every **stationary, client-governed** unit toward the goal the client's `0x600cd0` chain
 /// picks for it, through the one smoother that chain feeds ([`filter_step`]).
 ///
-/// The chain, in the client's exact branch order (wow-re `interaction-facing.md` §2) — the ordering
-/// *is* the behaviour:
+/// The chain, in the client's exact branch order — the ordering *is* the behaviour:
 ///
 /// | row | test | goal |
 /// |---|---|---|
diff --git a/crates/benilla-app/src/net/motion/modes.rs b/crates/benilla-app/src/net/motion/modes.rs
index c800c8e6..db0cce72 100644
--- a/crates/benilla-app/src/net/motion/modes.rs
+++ b/crates/benilla-app/src/net/motion/modes.rs
@@ -18,14 +18,14 @@ use crate::creature_anim::move_flags;
 ///
 /// **One word per unit is the reference's own shape**, not a convenience: `CMovement` is embedded at
 /// `CGUnit+0x9a8` and its `+0x40` MOVEMENTFLAGS dword is *the* per-unit movement state, written by
-/// the relay merge, the create block, the spline installer and this opcode family alike (wow-re
-/// `collision/scratch/moveflag-family.md` §5.2). We keep the granted-mode half separate from
+/// the relay merge, the create block, the spline installer and this opcode family alike. We keep
+/// the granted-mode half separate from
 /// [`super::RemoteMotion::flags`] for one reason: the relay merge re-authors that word wholesale
 /// from every pose, and a creature has no poses to be re-authored from.
 ///
 /// Absent component ⇒ no modes granted, which is the overwhelming majority of units; it is inserted
 /// on the first `SMSG_SPLINE_MOVE_*` that names the unit and lives as long as the entity, exactly as
-/// the reference's word lives as long as the `CGUnit` (`walk-mode-law.md` §1: `CMovement` is
+/// the reference's word lives as long as the `CGUnit` (`0x7c4850`: `CMovement` is
 /// constructed once per unit and nothing else clears it).
 #[derive(Component, Default, Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) struct UnitMoveModes(pub(crate) u32);
@@ -42,8 +42,8 @@ impl UnitMoveModes {
     }
 
     /// Rooted (`MOVEFLAG_ROOT`) — this unit **cannot be splined**: the reference's server-position
-    /// apply `0x6187a0` refuses outright while the bit is set (`0x6187c2 test ah,0x10`; wow-re
-    /// `moveflag-family.md` §5.3/§5.4, *"cannot translate, cannot jump, cannot be splined"*).
+    /// apply `0x6187a0` refuses outright while the bit is set (`0x6187c2 test ah,0x10`). A rooted
+    /// unit cannot translate, cannot jump, cannot be splined.
     pub(crate) fn rooted(self) -> bool {
         self.0 & move_flags::ROOT != 0
     }
@@ -70,8 +70,7 @@ impl UnitMoveModes {
 
 /// **What `SetRoot 0x7c7340` wipes from the flags word at apply**, as a mask to AND with: the four
 /// direction bits, the two keyboard turn bits and the two pitch bits (`0xff`), the `0x8000` latch,
-/// and the five deferred-input latches (`0x1f0000`) — `and dword ptr [esi+0x40], 0xffe07f00`,
-/// read byte-for-byte in wow-re `moveflag-family.md` §1.
+/// and the five deferred-input latches (`0x1f0000`) — `and dword ptr [esi+0x40], 0xffe07f00`.
 ///
 /// It is a **one-shot wipe at apply**, not a standing gate, and it is the whole reason a rooted
 /// mover stops rather than coasting: with the direction bits gone the unit fails the client's
diff --git a/crates/benilla-app/src/net/motion/relay.rs b/crates/benilla-app/src/net/motion/relay.rs
index 553b9087..47ec0d02 100644
--- a/crates/benilla-app/src/net/motion/relay.rs
+++ b/crates/benilla-app/src/net/motion/relay.rs
@@ -3,7 +3,7 @@
 //!
 //! A remote's inbound `MSG_MOVE_*` is not applied at arrival: it is given a client **fire-time** and
 //! waits in the unit's queue until the clock reaches it, the dead-reckon covering the mover's own
-//! timeline in between (decision 0601, wow-re `remote-apply-timing.md`). The law that picks that
+//! timeline in between (decision 0601). The law that picks that
 //! fire-time lives in `0x618c30` + its window helper `0x618b50`, and it is **per unit** — five cells
 //! on the unit's own CMovement, no manager cursor:
 //!
diff --git a/crates/benilla-app/src/net/motion/remote.rs b/crates/benilla-app/src/net/motion/remote.rs
index 13f1afa9..1c392347 100644
--- a/crates/benilla-app/src/net/motion/remote.rs
+++ b/crates/benilla-app/src/net/motion/remote.rs
@@ -60,7 +60,7 @@ pub(crate) struct RemoteMotion {
     pub(crate) fall_start_z: Option<f32>,
     /// Not-yet-due relayed moves, fire-time ascending — the reference's per-unit move-event queue
     /// (`CMovement+0x150`): a remote's packet is **scheduled**, not applied at arrival (decision
-    /// 0601; wow-re `remote-apply-timing.md`). [`drain_pending_moves`] applies each head when the
+    /// 0601). [`drain_pending_moves`] applies each head when the
     /// clock reaches its [`PendingMove::fire_ms`]; until then the dead-reckon covers the mover's
     /// own timeline, so the residual at apply time is structurally small.
     pub(crate) pending: std::collections::VecDeque<PendingMove>,
@@ -196,7 +196,7 @@ const REMOTE_TRACE_MS: f64 = 500.0;
 /// The pair is the whole point. A reported pitch with a zero tilt is the gate refusing (idle or
 /// strafe-only swim, or not swimming at all); a zero on *both* is a mover whose client never sent
 /// a pitch. Before this, neither number appeared anywhere — the observed-swimmer tilt landed in
-/// July 2026 (decision 0464 TU-A) with no trace and no test, so "do other swimmers tilt?" was a
+/// July 2026 (decision 0464) with no trace and no test, so "do other swimmers tilt?" was a
 /// question only the director's eye could answer.
 fn rendered_pitch(rm: &RemoteMotion) -> f32 {
     let (_, x, _) = crate::creature_anim::swim_body_rotation(0.0, rm.flags, rm.pitch)
@@ -291,7 +291,7 @@ fn idle_gate_disabled() -> bool {
 
 /// The reconcile-arm tolerance (squared yards): predicted-vs-event disagreement below this needs
 /// no correction. The reference's `0x80c744` = 7.716e-4 ≈ (0.0278 yd)², compared in 2D — Z joins
-/// only while SWIMMING (`0x619090`, wow-re `spec-driver-A.md`).
+/// only while SWIMMING (`0x619090`).
 const RECONCILE_TOL_SQ: f32 = 7.716e-4;
 
 /// One frame of the pre-fire reconcile (the reference's `0x619090` arm + `0x6191c0` lerp): if
@@ -330,8 +330,8 @@ const FACING_DEAD_ZONE: f32 = 9.5367e-7;
 
 /// One frame of the pre-fire facing interp — the reference's remote facing smoothing
 /// (`0x618f80` shortest-arc ω into `+0x144`, integrated by `0x7c4f30`: the **only** smoothed
-/// facing path a remote unit has — wow-re `body-facing-pipeline.md` §4; every other facing write
-/// is a snap). Rotate `orientation` along the shortest arc toward the queued event's `target`,
+/// facing path a remote unit has; every other facing write is a snap).
+/// Rotate `orientation` along the shortest arc toward the queued event's `target`,
 /// linear in time so it lands exactly as the clock reaches the fire-time; the apply then snaps
 /// the (structurally zero) remainder and clears the interp, as `0x617e90` zeroes `+0x148`. The
 /// ±π fold picks the short way around; the dead-zone skips a negligible turn.
@@ -586,9 +586,8 @@ pub(in crate::net) fn extrapolate_remote_units(
         let afloat = rm.flags & move_flags::SWIMMING != 0;
         // …and **a flag-still mover is not integrated at all** (decision 1545) — the reference's
         // own gate, [`move_flags::INTEGRATED`] = `0x20ff`: `CMovement::Update`'s substep loop
-        // (`0x616e20`) and the manager's per-mover tick (`0x6166f5`) both bail on it, and wow-re
-        // records that such a unit "is not even in the mover list". Its pose is the last packet's,
-        // verbatim.
+        // (`0x616e20`) and the manager's per-mover tick (`0x6166f5`) both bail on it: such a unit
+        // is not even in the mover list. Its pose is the last packet's, verbatim.
         //
         // That is not merely faithful, it is the only safe answer, because **our world can be
         // missing a floor the server has**: the WMO's collider attaches structurally later than the
@@ -600,8 +599,8 @@ pub(in crate::net) fn extrapolate_remote_units(
         // open-loop for a remote, which has no fall election at all. So the resolve walked a
         // watched player through the floor at 1/36 yd a frame — 1.67 yd/s at 60 fps, 3.3 at 120 —
         // onto the terrain below, where the (now deleted) settled memo froze them for the session.
-        // A standing player sends no packets, so nothing ever re-seated them: B197's fourth site,
-        // and nazriel_0's "until I move around, then it pops up back to normal".
+        // A standing player sends no packets, so nothing ever re-seated them: they stayed sunk
+        // until they moved, and then popped back up.
         //
         // Deleting the memo with the gate is the point, not a side effect: it existed only to skip
         // this resolve for a flag-still mover whose answer was proven identical (1473 §3), and the
@@ -641,7 +640,7 @@ pub(in crate::net) fn extrapolate_remote_units(
                 // ours has to be handed because liquid is queried rather than swept.
                 //
                 // `swimming` is read off the same word — the water plane is **not** floor while
-                // swimming (`moveflag-family.md` §2.2: the arm is taken only when the swim bit is
+                // swimming (`0x631617`: the arm is taken only when the swim bit is
                 // clear), which is what keeps a water-walker who is already in deep water from
                 // being popped onto the surface. The pitch gate the local mover applies is the
                 // *aim* pitch of a diving player and has no meaning for an observed one, so it is
@@ -786,7 +785,7 @@ pub(in crate::net) fn extrapolate_remote_units(
         // offset space (a left↔right flip swings around the front, never the 180°-tie back path),
         // with the SpineLow/Head counter-twist walking the upper body back onto its aim.
         // SWIMMING snaps the display facing to the aim instead — no strafe offset, no ease (the
-        // client's facing SNAP list: dead or swimming, wow-re `body-facing-pipeline.md`
+        // client's facing SNAP list: dead or swimming, `0x607ed0`'s
         // `mov [esi+0xc94],[esi+0xc98]`) — same gate the local controller applies.
         let swimming = rm.flags & move_flags::SWIMMING != 0;
         let offset = if swimming {
@@ -800,8 +799,9 @@ pub(in crate::net) fn extrapolate_remote_units(
             orientation
         };
         // The swim body pitch — [`crate::creature_anim::swim_body_rotation`], the same law our own
-        // avatar's pose owner calls, on the pitch this mover reported. TU-A is explicit that the
-        // observed mover takes the *reported* pitch here, exactly as the local one takes its own.
+        // avatar's pose owner calls, on the pitch this mover reported. The reference's render law
+        // (`0x60a110`) takes the observed mover's *reported* pitch here, exactly as the local one
+        // takes its own.
         let rotation = crate::creature_anim::swim_body_rotation(yaw, rm.flags, rm.pitch);
         if t.rotation != rotation {
             t.rotation = rotation;
diff --git a/crates/benilla-app/src/net/motion/spline.rs b/crates/benilla-app/src/net/motion/spline.rs
index 26574270..52840a53 100644
--- a/crates/benilla-app/src/net/motion/spline.rs
+++ b/crates/benilla-app/src/net/motion/spline.rs
@@ -36,7 +36,7 @@ pub(crate) struct Spline {
     /// `0x7c6a50` feeds this bit to `CMovement::SetRunMode 0x7c71c0` (`0x7c6ac2 and edi,0x100`;
     /// `0x7c6acb call`), whose argument is *run*, so **a spline without RUNMODE sets
     /// `MOVEFLAG_WALK_MODE` on the unit it moves.** Every incoming spline re-authors the bit
-    /// (wow-re `collision/scratch/walk-mode-law.md` §5.2; decision 1758).
+    /// (decision 1758).
     ///
     /// Only the body **we drive** reads it ([`crate::player::server_ride`]) — a creature's own
     /// gait is derived from [`Spline::speed`], the path's arc length over its duration, so its
@@ -104,16 +104,14 @@ impl Spline {
     /// swimming-creature body pitch (its consumer gates on [`CreatureSwimming`], so a ground
     /// walker's slope never tilts it).
     ///
-    /// A **ground** path evaluates each segment as a straight lerp (the byte-verified
-    /// `linear_pos_diff` follow — wow-re curvemath RF-0048). A **flying** path (`!grounded` — the
-    /// wire's `Flying`/`Mask_CatmullRom` bit) evaluates a uniform **Catmull-Rom** through the same
-    /// waypoints, neighbours phantom-duplicated at the ends per the client's CCurve commit
-    /// (RF-0052) — smooth arcs, no corners on a taxi flight. **Byte-VERIFIED** (decision 0496
-    /// folds back 0484 I3): the flying commit writes curve mode 1 (`0x7c6a50` →
-    /// `[movInfo+0x54]`), and the point-at-t evaluator `0x4541b0` is itself the mode dispatcher —
-    /// mode 1 calls the Horner-basis Catmull-Rom cubic (`0x453580`), mode 0 the 2-point lerp
-    /// (wow-re `system/curvemath/scratch/taxi-flying-curve-mode.md`). Segment *location* stays
-    /// chord-length parameterised in both modes (RF-0052 fills per-segment chord + total
+    /// A **ground** path evaluates each segment as a straight lerp. A **flying** path (`!grounded`
+    /// — the wire's `Flying`/`Mask_CatmullRom` bit) evaluates a uniform **Catmull-Rom** through the
+    /// same waypoints, neighbours phantom-duplicated at the ends per the client's CCurve commit
+    /// (`0x601d30`/`0x601e66`) — smooth arcs, no corners on a taxi flight. Decision 0496 folds back
+    /// 0484 I3: the flying commit writes curve mode 1 (`0x7c6a50` → `[movInfo+0x54]`), and the
+    /// point-at-t evaluator `0x4541b0` is itself the mode dispatcher — mode 1 calls the
+    /// Horner-basis Catmull-Rom cubic (`0x453580`), mode 0 the 2-point lerp. Segment *location*
+    /// stays chord-length parameterised in both modes (`0x4532e0` fills per-segment chord + total
     /// arc-length).
     pub(crate) fn sample(&self, now: Instant) -> ([f32; 3], Option<f32>, f32) {
         let pts = self.points.as_slice();
@@ -167,9 +165,8 @@ impl Spline {
         (*pts.last().unwrap(), None, 0.0)
     }
 
-    /// The **flying attitude** `(pitch, bank)` in radians — the byte law (wow-re `taxi-system.md`
-    /// §TU-4, `0x7c5490`'s flying branch decomposed at §5 grade; decision 0516, correcting 0501's
-    /// INTERIM look-ahead *pitch*):
+    /// The **flying attitude** `(pitch, bank)` in radians — the byte law (`0x7c5490`'s flying
+    /// branch; decision 0516, correcting 0501's INTERIM look-ahead *pitch*):
     ///
     /// - **Pitch** is the instantaneous tangent's own climb — [`Spline::sample`]'s travel pitch,
     ///   `asin(t̂z)` — not a look-ahead difference: the client orients the mover's forward along
@@ -213,10 +210,10 @@ impl Spline {
 
 /// Uniform Catmull-Rom position + travel direction on the polyline segment `pts[i] → pts[i+1]` at
 /// local parameter `u ∈ [0,1]`, with the neighbour control points phantom-duplicated at the path
-/// ends — the real client's CCurve commit stores `[first, first, …, last, last]` (wow-re curvemath
-/// RF-0052), which makes the curve pass through every waypoint and start/end tangent to the end
-/// segments. Returns `(position, d/du tangent)`; the tangent's scale is meaningless to callers
-/// (they normalize or `atan2` it), only its direction matters.
+/// ends — the real client's CCurve commit stores `[first, first, …, last, last]`
+/// (`0x601d30`/`0x601e66`), which makes the curve pass through every waypoint and start/end
+/// tangent to the end segments. Returns `(position, d/du tangent)`; the tangent's scale is
+/// meaningless to callers (they normalize or `atan2` it), only its direction matters.
 fn catmull_rom(pts: &[[f32; 3]], i: usize, u: f32) -> ([f32; 3], [f32; 3]) {
     let p0 = pts[i.saturating_sub(1)];
     let p1 = pts[i];
@@ -240,8 +237,8 @@ fn catmull_rom(pts: &[[f32; 3]], i: usize, u: f32) -> ([f32; 3], [f32; 3]) {
 /// Build the [`Spline`] implied by one `SMSG_MONSTER_MOVE`: the unit rides `path` — the full travel-order
 /// polyline `[start, …waypoints…, endpoint]` the protocol decoded — at constant (arc-length) speed over
 /// `duration_ms`. [`Spline::sample`] interpolates a ground path piecewise-linearly, which is faithful: the
-/// real client's ground creature-follow evaluates the path with `linear_pos_diff` (a segment lerp),
-/// arc-length parameterised, through every waypoint (wow-re curvemath RF-0048/RF-0052); a **flying** path
+/// real client's ground creature-follow evaluates the path with a segment lerp (`0x4541b0`),
+/// arc-length parameterised, through every waypoint; a **flying** path
 /// takes the Catmull-Rom family instead (the taxi/flight look — see [`Spline::sample`]'s INTERIM note).
 /// Returns `None` — "stationary, clear any path" — for a `Stop`, a zero duration, or a path with fewer
 /// than two points (nothing to travel along).
@@ -462,7 +459,7 @@ pub(in crate::net) fn sample_splines(
         let was = tick.then(|| bevy_to_wow(t.translation));
         t.translation = wow_to_bevy(wow_pos);
         if let Some(f) = facing {
-            // The swim body pitch (TU-A's render law, applied to the spline movers): a swimming
+            // The swim body pitch (render law `0x60a110`, applied to the spline movers): a swimming
             // creature moving along its path renders its root pitched to the segment's travel
             // pitch, nose-up positive about the body's local X; ground walkers render level. A
             // FLYING spline (the taxi) takes the full attitude — the tangent's climb plus the
@@ -545,14 +542,12 @@ fn trace_ride(guid: u64, spline: &Spline, pos: [f32; 3], was: [f32; 3], now: Ins
 /// Both used to ask `kind == Unit`, and **kind is the wrong question**. The reference has no such
 /// test: `SMSG_MONSTER_MOVE`'s apply `0x6187a0` splices *whatever unit the packet named* into the
 /// movement manager's list (`0x618801` installs the spline, `0x618808 call 0x619ca0` links it; its
-/// only early-out is `6187bf test ah,0x10`, ROOT — wow-re `remote-swim-decision.md` §1.2, VERIFIED),
-/// the per-frame walk `0x615b10 → 0x616620` then runs **once per frame for every registered
-/// CMovement** (§1.1), and the vertical-zero gate inside it reads only that CMovement's own flag
-/// word — `MI.flags & 0x4`, `MI.flags & 0x200` (the spline's FLYING bit), `[CMovement+0x40] &
-/// 0x200800`, else `Δz := 0` (`0x616cec`-`0x616d03`, wow-re `collision/scratch/spec-driver-B.md`
-/// K3). Not one of those bytes asks what kind of object it is holding: `mover-is-a-creature.md`
-/// says it in one line — *"nothing in the movement system is 'the player's' any more … every
-/// scalar, every flag, every packet is the MOVER's"*.
+/// only early-out is `6187bf test ah,0x10`, ROOT), the per-frame walk `0x615b10 → 0x616620` then
+/// runs **once per frame for every registered CMovement**, and the vertical-zero gate inside it
+/// reads only that CMovement's own flag word — `MI.flags & 0x4`, `MI.flags & 0x200` (the spline's
+/// FLYING bit), `[CMovement+0x40] & 0x200800`, else `Δz := 0` (`0x616cec`-`0x616d03`). Not one of
+/// those bytes asks what kind of object it is holding: nothing in the movement system is the
+/// player's — every scalar, every flag, every packet is the mover's.
 ///
 /// So a **Player the server moves along a ground spline has its Z re-derived from the terrain
 /// exactly like a creature's**. cmangos's Playerbots drives its bots that way — they are Player
@@ -566,8 +561,8 @@ fn trace_ride(guid: u64, spline: &Spline, pos: [f32; 3], was: [f32; 3], now: Ins
 ///   what `splined || derived_before` says: a bot enters on its first path and never leaves (it
 ///   sends no `MSG_MOVE_*`, so nothing ever hands it back), while a remote player yanked by a
 ///   Charge, a knockback or a fear is derived for the ride and returns to [`RemoteMotion`] on their
-///   next packet. Sticky is the *reference's* shape too — `0x619ca0` splices, and nothing in the
-///   recorded notes unlinks — and it is what keeps a bot grounded in the frames between paths,
+///   next packet. Sticky is the *reference's* shape too — `0x619ca0` splices, and no unlink of it
+///   is known — and it is what keeps a bot grounded in the frames between paths,
 ///   including the one where [`sample_splines`] has just dropped the finished [`Spline`].
 /// - **Never the body we steer** ([`crate::net::Embodied`]) — *whatever kind it is*, which is the
 ///   half decision 1927 corrected. Our own avatar is a Player and was already out; a **possessed
@@ -607,7 +602,7 @@ pub(crate) fn ground_derived(
 }
 
 /// How far **above the seat** an idle unit's settle probe starts (yd): the reference's own
-/// backface band. The swept-prism TOI (`0x632830`, wow-re `resolve_clip.rs::polygon_toi`) still
+/// backface band. The swept-prism TOI (`0x632830`) still
 /// counts a face the prism has already passed as a hit at `t = 0` when it is within `1/36` yd
 /// (`[0x7ff9c8]`) behind the probe, so a floor a hair above the feet supports the body; anything
 /// further above is simply not there. **Not** a lift: this clamp once started 2.5 yd above the seat
@@ -663,7 +658,7 @@ pub(crate) fn grounded_y(
 /// doesn't trust the wire Z for a walking unit: the grounded fork zeroes the spline Z-delta and the
 /// WALK resolver reads Z off the world trace (byte-verified, decision 0059); an idle unit reads
 /// grounded against the reference too (the exact idle path isn't byte-pinned yet — 0059's open
-/// follow-up, dispatched again under decision 2018).
+/// follow-up, reopened in decision 2018).
 ///
 /// **The probe geometry is the reference's, and it starts at the body** (decision 2018). A walker
 /// continuing its path runs the shared swept step ([`crate::player::mover::grounded_step`]) from
@@ -833,8 +828,8 @@ pub(in crate::net) fn ground_clamp_creatures(
             }
         }
         // The water-walker's floor, and **only** for a creature the swim mark already let through:
-        // the reference takes this arm only when the swim bit is clear (wow-re
-        // `moveflag-family.md` §2.2), and a swimming creature `continue`d above. The plane is the
+        // the reference takes this arm only when the swim bit is clear (`0x631617`), and a
+        // swimming creature `continue`d above. The plane is the
         // liquid surface in Bevy Y, which both answers below read the same way.
         //
         // The reference's second, rate-limited hover pass (`0x636fa1`, climbing back toward the
@@ -1136,8 +1131,8 @@ const CREATURE_SWIM_EXIT_BAND: f32 = 1.0 / 36.0;
 /// nothing arrives for it, and it is derived here for the same reason (B357, decision 1921). The
 /// gate below admits it: bit 3 PLAYER_CONTROLLED is set on every player object, so
 /// [`crate::player::may_swim`] is true. The real client runs its own depth decision `0x6030c0` on **remote
-/// units and creatures too**, not only on the body it steers — VERIFIED, wow-re
-/// `collision/scratch/remote-swim-decision.md` §1. `0x6030c0` has exactly one caller and it reaches
+/// units and creatures too**, not only on the body it steers.
+/// `0x6030c0` has exactly one caller and it reaches
 /// per-unit three ways: a **per-frame registry walk** (`0x616800`, a registered frame callback →
 /// `0x615b10` over the movement manager's intrusive CMovement list → `0x616620` per node, whose own
 /// active-mover GUID compare gates only the `0xee` heartbeat), the inbound move-message apply
@@ -1234,7 +1229,7 @@ impl GroundClamped {
 
 /// The reference's `0x6030c0` decision for one creature, as a pure function of everything it
 /// reads — [`CreatureSwimming`]'s law in one place, so both asymmetries are assertable without a
-/// world. Byte-VERIFIED whole (wow-re `collision/scratch/remote-swim-decision.md` §2/§3):
+/// world:
 ///
 /// ```text
 /// enter iff  flags ∧ depth >  0.75·h              (0x603106 test ah,0x41 + jne — a ZF test, STRICT)
diff --git a/crates/benilla-app/src/net/motion/tests.rs b/crates/benilla-app/src/net/motion/tests.rs
index 4fdeb2b8..e84680c2 100644
--- a/crates/benilla-app/src/net/motion/tests.rs
+++ b/crates/benilla-app/src/net/motion/tests.rs
@@ -67,9 +67,9 @@ fn motion(flags: u32, orientation: f32) -> RemoteMotion {
     }
 }
 
-/// **The observed swimmer's body actually tilts** — the render half of TU-A (decision 0464 §1),
-/// which shipped in July 2026 with no test of its own and no trace field, so the only instrument
-/// that could contradict it was the director's eye.
+/// **The observed swimmer's body actually tilts** — the swim body-pitch render law (`0x60a110`,
+/// decision 0464 §1), which shipped in July 2026 with no test of its own and no trace field, so the
+/// only instrument that could contradict it was the director's eye.
 ///
 /// The law is [`crate::creature_anim::swim_body_rotation`] and it is now *one* function: this
 /// asserts the observed lane end to end — a relayed `MSG_MOVE_*` carrying `SWIMMING | FORWARD`
@@ -295,7 +295,7 @@ fn a_walking_remote_backpedals_at_walk_speed_not_run_back() {
 
 #[test]
 fn remote_motion_swim_backpedal_takes_min_of_the_swim_pair() {
-    // The byte law (`0x7c4c90`'s backward arms, swim-feel §5 TU-H): backward speed is
+    // The byte law (`0x7c4c90`'s backward arms): backward speed is
     // `min(back, forward)` for both pairs — the plain back speed whenever it's the slower
     // (always, at vanilla values), clamped if a server force-sets it above the forward speed.
     let mut s = speeds();
@@ -1092,7 +1092,7 @@ fn a_gameobject_without_a_usable_quaternion_falls_back_to_its_facing() {
 /// **A flag-still remote is not integrated at all** (decision 1545) — the reference's own gate,
 /// `0x20ff` ([`move_flags::INTEGRATED`]): `CMovement::Update`'s substep loop (`0x616e20`) and the
 /// manager's per-mover tick (`0x6166f5`) both bail on a mover with no move/jump/fall bit, and
-/// wow-re records that such a unit "is not even in the mover list". So its pose is the last
+/// such a unit is not even in the mover list. So its pose is the last
 /// packet's, verbatim — and the per-frame depenetration + down-cast the settled memo used to claw
 /// back (1490 item 2 / 1473 §3) does not run at all, for a stated reason rather than a proof that
 /// its answer was identical.
diff --git a/crates/benilla-app/src/net/apply/objects.rs b/crates/benilla-app/src/net/objects.rs
similarity index 63%
rename from crates/benilla-app/src/net/apply/objects.rs
rename to crates/benilla-app/src/net/objects.rs
index 084a32d4..d9284d93 100644
--- a/crates/benilla-app/src/net/apply/objects.rs
+++ b/crates/benilla-app/src/net/objects.rs
@@ -1,15 +1,17 @@
-//! Object-stream arm bodies for [`super::apply_net_updates`]'s dispatch match — the streamed
-//! world's lifecycle (create / values-merge / destroy / stream-out), the relayed player movement,
-//! and the creature path packet. Each `pub(super)` fn here is exactly one arm's body; the match at
-//! the call site stays the dispatcher, one call per arm.
-
-use std::collections::hash_map::Entry;
-use std::collections::HashMap;
-
+//! The bridge's own object layer (in the net handler table since 2327 — the last family out of
+//! the drain's dispatch match, which went with it): the streamed world's creates, deltas, moves
+//! and destroys, the movers' speeds and granted modes, the GameObject templates and anims, and
+//! the item store's three kinds. Each packet is one handler over [`Scene`]; a handler's commands
+//! are applied before the next packet's handler runs (decision 2306), which is why the three
+//! intra-drain staging maps the match kept (0061's `pending`, 1478's `SpeedStage`, 1780's
+//! `StagedModes`) are gone: a create inserts its store and speeds at spawn, and the next packet
+//! reads the live component. Registered from [`super::NetPlugin`].
 use benilla_assets::coords::bevy_to_wow;
 use benilla_protocol::{
     guid, EntityKind, MonsterMoveFacing, MoveSpeeds, ObjectFields, SpeedKind, SplineMode,
 };
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::ecs::system::SystemParam;
 use bevy::prelude::*;
 
 use crate::go_templates::GameObjectTemplates;
@@ -18,20 +20,20 @@ use crate::names::NameCache;
 use benilla_world::model_fade::DespawnFade;
 use benilla_world::vis_chain::VisChainOnly;
 
-use super::super::motion::{
+use super::motion::{
     create_spline, gameobject_rotation, monster_move_spline, pose_transform, resolve_facing,
     trace_create_spline, trace_move_snap, wire_yaw, write_pose, SplineStopped, ROOT_APPLY_WIPE,
 };
-use super::super::{
-    merge_store_fields, FieldChanged, Guid, GuidIndex, NetCommands, NetEntity, ObjectStore,
-    RemoteMotion, SelfGuid, SpeedChangeMessage, Spline, UnitMoveModes, UnitSpeeds,
+use super::{
+    merge_store_fields, FieldChanged, Guid, GuidIndex, NetCommands, NetEntity, NetHandlerApp,
+    ObjectStore, RemoteMotion, SelfGuid, SpeedChangeMessage, Spline, UnitMoveModes, UnitSpeeds,
 };
 
 /// A GameObject plays its one-shot **Custom** animation (`SMSG_GAMEOBJECT_CUSTOM_ANIM`, decision
 /// 1086) — bridged to the GO animation machine ([`crate::go_anim`]), which owns the reject
 /// (`anim_id >= 4`), the id mapping (153..156) and the model-ownership gate. The load-bearing
 /// sender: the fishing bobber's bite splash (`anim_id 0`).
-pub(super) fn gameobject_custom_anim(
+fn gameobject_custom_anim(
     guid: u64,
     anim_id: u32,
     plays: &mut MessageWriter<crate::go_anim::GoCustomAnim>,
@@ -44,7 +46,7 @@ pub(super) fn gameobject_custom_anim(
 }
 
 /// An object plays its one-shot **Despawn** animation (`SMSG_GAMEOBJECT_DESPAWN_ANIM`, decision
-/// 1404) — the other half of wow-re `gameobject-anim-arm.md` §2c's channel, AnimationData id 157.
+/// 1404) — the other half of the one-shot channel `0x5f8c50`, AnimationData id 157.
 ///
 /// This marks the entity **immediately**, with a component rather than a message, because vmangos
 /// sends `SMSG_DESTROY_OBJECT` for the same object in the same server tick: the mark has to be on
@@ -52,7 +54,7 @@ pub(super) fn gameobject_custom_anim(
 /// Commands apply in the order they were queued, so an insert queued here is visible to the
 /// closure the destroy queues below. The arm itself, and the model-ownership gate, are
 /// [`crate::go_anim`]'s.
-pub(super) fn gameobject_despawn_anim(guid: u64, commands: &mut Commands, index: &GuidIndex) {
+fn gameobject_despawn_anim(guid: u64, commands: &mut Commands, index: &GuidIndex) {
     debug!("net: gameobject {guid:#x} despawn anim");
     if let Some(&e) = index.0.get(&guid) {
         commands
@@ -61,9 +63,403 @@ pub(super) fn gameobject_despawn_anim(guid: u64, commands: &mut Commands, index:
     }
 }
 
+/// Register the object layer's handlers — called from [`super::NetPlugin`].
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::ObjectCreate, on_object_create)
+        .net_handler(K::ItemCreate, on_item)
+        .net_handler(K::ItemTemplate, on_item)
+        .net_handler(K::ItemTime, on_item)
+        .net_handler(K::ItemEnchantTime, on_item)
+        .net_handler(K::ObjectMove, on_object_move)
+        .net_handler(K::MoveTimeSkipped, on_move_time_skipped)
+        .net_handler(K::UnitMove, on_unit_move)
+        .net_handler(K::ObjectValues, on_object_values)
+        .net_handler(K::ObjectDestroyed, on_object_destroyed)
+        .net_handler(K::ObjectsRemoved, on_objects_removed)
+        .net_handler(K::MonsterMove, on_monster_move)
+        .net_handler(K::GameObjectInfo, on_gameobject_info)
+        .net_handler(K::GameObjectCustomAnim, on_gameobject_anim)
+        .net_handler(K::GameObjectDespawnAnim, on_gameobject_anim)
+        .net_handler(K::SplineMoveMode, on_spline_move_mode)
+        .net_handler(K::ForceSpeedChange, on_speed)
+        .net_handler(K::SpeedChanged, on_speed);
+}
+
+/// The streamed world as one parameter: the entities and their components the packets write,
+/// the caches they warm, the hooks other subsystems keep on the object lifecycle (the reclaim
+/// latch's, the roster's), and the edges they publish.
+#[derive(SystemParam)]
+pub(crate) struct Scene<'w, 's> {
+    commands: Commands<'w, 's>,
+    net: Res<'w, NetCommands>,
+    index: ResMut<'w, GuidIndex>,
+    self_guid: Res<'w, SelfGuid>,
+    real: Res<'w, Time<Real>>,
+    transforms: Query<'w, 's, &'static mut Transform>,
+    stores: Query<'w, 's, &'static mut ObjectStore>,
+    countdowns: Query<'w, 's, &'static mut crate::items::Countdowns>,
+    remote: Query<'w, 's, &'static mut RemoteMotion>,
+    modes: Query<'w, 's, &'static mut UnitMoveModes>,
+    riders: Query<'w, 's, &'static mut crate::transport::TransportRider>,
+    speeds: Query<'w, 's, &'static mut UnitSpeeds>,
+    field_changes: MessageWriter<'w, FieldChanged>,
+    speed_changes: MessageWriter<'w, SpeedChangeMessage>,
+    self_moves: MessageWriter<'w, super::SelfMoveMessage>,
+    hard_landings: MessageWriter<'w, crate::creature_anim::HardLanding>,
+    go_custom_anims: MessageWriter<'w, crate::go_anim::GoCustomAnim>,
+    names: Res<'w, NameCache>,
+    items: ResMut<'w, Items>,
+    go_templates: ResMut<'w, GameObjectTemplates>,
+    death_net: ResMut<'w, crate::death::DeathNet>,
+    group: ResMut<'w, crate::ui_party::GroupState>,
+}
+
+fn on_object_create(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::ObjectCreate {
+        guid,
+        kind,
+        display_id,
+        position,
+        orientation,
+        scale,
+        speeds,
+        mover,
+        transport_progress,
+        transport,
+        spline,
+        fields,
+    } = ev
+    {
+        crate::death::net::note_corpse(guid, kind, &fields, &sc.self_guid, &mut sc.death_net);
+        object_create(
+            guid,
+            kind,
+            display_id,
+            position,
+            orientation,
+            scale,
+            speeds,
+            mover,
+            transport_progress,
+            transport,
+            spline,
+            fields,
+            &mut sc.commands,
+            &mut sc.index,
+            &mut sc.transforms,
+            &mut sc.stores,
+            &mut sc.field_changes,
+            &sc.names,
+            &sc.go_templates,
+            &sc.net,
+        );
+    }
+}
+
+/// The item store's kinds: a descriptor-only create, the template's display head
+/// (`SMSG_ITEM_QUERY_SINGLE_RESPONSE`, answering our `CMSG_ITEM_QUERY_SINGLE` — the ask-once
+/// cache, decisions 0068/0072; a server miss records `None` so the entry is never re-asked), the
+/// item-lifetime countdown's only feed (decision 1933) and the temporary-enchant countdown's
+/// (decision 0920) — both written into the item's own [`crate::items::Countdowns`] (decision
+/// 2340), which every tooltip surface reads back.
+fn on_item(In(ev): In<SessionEvent>, mut sc: Scene) {
+    match ev {
+        SessionEvent::ItemCreate {
+            guid,
+            container,
+            fields,
+        } => item_create(
+            guid,
+            container,
+            fields,
+            &mut sc.commands,
+            &mut sc.index,
+            &mut sc.stores,
+            &mut sc.field_changes,
+            &mut sc.items,
+        ),
+        SessionEvent::ItemTemplate { entry, info } => {
+            let info = info.map(|b| *b);
+            debug!("net: item template {entry} → {info:?}");
+            sc.items.insert_template(entry, info);
+        }
+        // `0x5e4f30`'s two arms share the item lookup (`0x468460`, `TYPEMASK_ITEM`) — here the
+        // index plus the item's own cells — and part company on a miss.
+        SessionEvent::ItemTime { item_guid, seconds } => {
+            // **An item we do not hold drops the update — no queue, no retry** (`0x1EA`'s arm
+            // returns on the miss). The login re-send (`Player::SendItemDurations`) goes out the
+            // moment the player is added to the map, so an item whose create has not landed yet
+            // shows no lifetime until the server's next update, as in the reference.
+            match sc.index.0.get(&item_guid).copied() {
+                Some(e) if sc.countdowns.contains(e) => {
+                    if let Ok(mut c) = sc.countdowns.get_mut(e) {
+                        c.set_lifetime(seconds);
+                    }
+                    debug!("item duration: item {item_guid:#x} → {seconds}s");
+                }
+                _ => debug!("item duration: {item_guid:#x} names an item we do not hold — dropped"),
+            }
+        }
+        SessionEvent::ItemEnchantTime {
+            item_guid,
+            slot,
+            seconds,
+        } => match sc.index.0.get(&item_guid).copied() {
+            Some(e) if sc.countdowns.contains(e) => {
+                if let Ok(mut c) = sc.countdowns.get_mut(e) {
+                    if c.set_enchant(slot, seconds) {
+                        debug!("enchant timer: item {item_guid:#x} slot {slot} → {seconds}s");
+                    } else {
+                        debug!("enchant timer: item {item_guid:#x} slot {slot} is past the seventh — refused");
+                    }
+                }
+            }
+            // `0x1EB`'s miss arm: the record goes onto a resolving player's pending list
+            // (`0x5ebd40`) — the packet's own player guid first, the active player second — and
+            // only the active player's list is ever replayed (`0x5d8440` → `0x5ebde0`). vmangos
+            // names the owner, which is us (`SendItemEnchantTimeUpdate(GetObjectGuid(), ..)`,
+            // `Player.cpp:11807`/`:12001`), so both lookups land on the active player.
+            _ if sc.self_guid.0.is_some_and(|g| sc.index.0.contains_key(&g)) => {
+                sc.items.queue_enchant_time(item_guid, slot, seconds)
+            }
+            _ => debug!("enchant timer: {item_guid:#x} unheld and no player to queue on — dropped"),
+        },
+        _ => {}
+    }
+}
+
+fn on_object_move(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::ObjectMove {
+        guid,
+        position,
+        orientation,
+    } = ev
+    {
+        object_move(
+            guid,
+            position,
+            orientation,
+            &mut sc.commands,
+            &sc.index,
+            &mut sc.transforms,
+        );
+    }
+}
+
+/// **An observed mover skipped time** (decision 1935). No pose moved — only that unit's clock
+/// ran on — so this touches its relay chain and nothing else, which is the whole of what the
+/// reference's handler does (`0x603b40` → `0x61ab90`: `[CMovement+0xac] += lag`). A guid we do
+/// not hold is dropped, faithfully: the reference resolves under `TYPEMASK_UNIT` and returns on
+/// a miss.
+fn on_move_time_skipped(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::MoveTimeSkipped { guid, lag_ms } = ev {
+        if let Some(mut m) = sc
+            .index
+            .0
+            .get(&guid)
+            .and_then(|&e| sc.remote.get_mut(e).ok())
+        {
+            m.relay.skip_time(lag_ms);
+        }
+    }
+}
+
+/// The scheduled-replay law (decisions 0601/0615): `unit_move` runs the mover's own replay chain
+/// over this packet's wire stamp to get its client fire-time, then applies it now if due, else
+/// queues it on the unit for `drain_pending_moves`.
+fn on_unit_move(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::UnitMove {
+        guid,
+        position,
+        orientation,
+        flags,
+        pitch,
+        time,
+        verb,
+        fall_time,
+        jump,
+        transport,
+    } = ev
+    {
+        let now_ms = sc.real.elapsed_secs_f64() * 1000.0;
+        unit_move(
+            guid,
+            crate::net::motion::RelayMove {
+                wire_ms: time,
+                position,
+                orientation,
+                flags,
+                pitch,
+                fall_time,
+                jump,
+                transport,
+                verb,
+            },
+            now_ms,
+            &mut sc.commands,
+            &sc.index,
+            &sc.self_guid,
+            &mut sc.remote,
+            &mut sc.transforms,
+            &mut sc.hard_landings,
+            &mut sc.self_moves,
+        );
+    }
+}
+
+/// Our corpse's own `CORPSE_FIELD_FLAGS` can flip to BONES under a live guid; the reclaim latch
+/// is re-asked on that edge, as the reference's `FLAGS` mirror handler `0x5d6d60` does (1729).
+fn on_object_values(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::ObjectValues { guid, fields } = ev {
+        crate::death::net::recheck_corpse(guid, &fields, &sc.self_guid, &mut sc.death_net);
+        object_values(
+            guid,
+            fields,
+            &mut sc.commands,
+            &sc.index,
+            &mut sc.stores,
+            &mut sc.field_changes,
+        );
+    }
+}
+
+/// The party hook runs FIRST and on the same edge the reference takes it: the deactivate
+/// virtual reads the descriptor that is about to go (decision 1640).
+fn on_object_destroyed(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::ObjectDestroyed(guid) = ev {
+        crate::death::net::forget_corpse(guid, &mut sc.death_net);
+        let store = sc.index.0.get(&guid).and_then(|e| sc.stores.get(*e).ok());
+        crate::ui_party::net::member_deactivated(guid, &mut sc.group, store, &sc.net);
+        object_destroyed(guid, &mut sc.commands, &mut sc.index);
+    }
+}
+
+/// OUT_OF_RANGE and DESTROY take the same virtual in the reference — so the snapshot +
+/// `CMSG_REQUEST_PARTY_MEMBER_STATS` fire here too, which is the edge report B334 is actually
+/// about: a member walking over the hill.
+fn on_objects_removed(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::ObjectsRemoved(guids) = ev {
+        for guid in &guids {
+            let store = sc.index.0.get(guid).and_then(|e| sc.stores.get(*e).ok());
+            crate::ui_party::net::member_deactivated(*guid, &mut sc.group, store, &sc.net);
+        }
+        objects_removed(guids, &mut sc.commands, &mut sc.index);
+    }
+}
+
+fn on_monster_move(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::MonsterMove {
+        guid,
+        transport,
+        start,
+        spline_id,
+        path,
+        facing,
+        stop,
+        duration_ms,
+        flying,
+        run_mode,
+    } = ev
+    {
+        let rooted = modes_of(guid, &sc.index, &sc.modes).rooted();
+        monster_move(
+            guid,
+            transport,
+            start,
+            spline_id,
+            path,
+            facing,
+            stop,
+            duration_ms,
+            flying,
+            run_mode,
+            rooted,
+            &mut sc.commands,
+            &sc.index,
+            &mut sc.transforms,
+            &mut sc.riders,
+        );
+    }
+}
+
+fn on_gameobject_info(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::GameObjectInfo {
+        entry,
+        type_id,
+        display_id,
+        name,
+        data,
+    } = ev
+    {
+        gameobject_info(
+            entry,
+            type_id,
+            display_id,
+            name,
+            &data,
+            &mut sc.go_templates,
+        );
+    }
+}
+
+fn on_gameobject_anim(In(ev): In<SessionEvent>, mut sc: Scene) {
+    match ev {
+        SessionEvent::GameObjectCustomAnim { guid, anim_id } => {
+            gameobject_custom_anim(guid, anim_id, &mut sc.go_custom_anims)
+        }
+        SessionEvent::GameObjectDespawnAnim { guid } => {
+            gameobject_despawn_anim(guid, &mut sc.commands, &sc.index)
+        }
+        _ => {}
+    }
+}
+
+/// The observer movement-mode family (decision 1780) — the same modes, on a body somebody else
+/// is driving. No ack, so the handler ends the packet.
+fn on_spline_move_mode(In(ev): In<SessionEvent>, mut sc: Scene) {
+    if let SessionEvent::SplineMoveMode { guid, mode, apply } = ev {
+        spline_move_mode(
+            guid,
+            mode,
+            apply,
+            &mut sc.commands,
+            &sc.index,
+            &mut sc.modes,
+            &mut sc.remote,
+        );
+    }
+}
+
+fn on_speed(In(ev): In<SessionEvent>, mut sc: Scene) {
+    match ev {
+        SessionEvent::ForceSpeedChange {
+            guid,
+            kind,
+            counter,
+            speed,
+        } => force_speed_change(
+            guid,
+            kind,
+            counter,
+            speed,
+            &sc.index,
+            &mut sc.speeds,
+            &sc.self_guid,
+            &mut sc.speed_changes,
+        ),
+        SessionEvent::SpeedChanged { guid, kind, speed } => {
+            speed_changed(guid, kind, speed, &sc.index, &mut sc.speeds)
+        }
+        _ => {}
+    }
+}
+
 /// An object entered range / was created (`SMSG_UPDATE_OBJECT` create block): spawn or refresh the
-/// entity, warm the ask-once caches, and seed its descriptor store via the per-drain `pending` map.
-pub(super) fn object_create(
+/// entity, warm the ask-once caches, and seed its descriptor store. A handler's commands are
+/// applied before the next packet's handler runs (decision 2306), so the store and the speeds
+/// are components at spawn and the next packet reads them live.
+fn object_create(
     guid: u64,
     kind: EntityKind,
     display_id: Option<u32>,
@@ -80,9 +476,7 @@ pub(super) fn object_create(
     index: &mut GuidIndex,
     transforms: &mut Query<&mut Transform>,
     stores: &mut Query<&mut ObjectStore>,
-    pending: &mut HashMap<u64, ObjectFields>,
     edges: &mut MessageWriter<FieldChanged>,
-    speed_stage: &mut SpeedStage,
     names: &NameCache,
     go_templates: &GameObjectTemplates,
     net_commands: &NetCommands,
@@ -95,9 +489,10 @@ pub(super) fn object_create(
     // A transport's cycle anchor (decision 0438): the create block's `UPDATE_FLAG_TRANSPORT`
     // u32 + the local instant it landed. Re-creates re-anchor (the server re-sends the create at
     // map transitions and mid-course update frames precisely so clients can correct drift). The
-    // transport tick owns it from here (`crate::transport`). Both ticking GO types (the client's
-    // RF-0051 pair): 15 (boats — vmangos sends its path-progress clock) and 11 (elevators/lifts
-    // — the same flag, `GameObject.cpp:246`, a `time-since-create % period` clock).
+    // transport tick owns it from here (`crate::transport`). Both ticking GO types (the only two
+    // the client's per-frame tick `0x630970` runs): 15 (boats — vmangos sends its path-progress
+    // clock) and 11 (elevators/lifts — the same flag, `GameObject.cpp:246`, a
+    // `time-since-create % period` clock).
     let go_type = (kind == EntityKind::GameObject).then(|| fields.gameobject_type_id());
     let transport_anchor = matches!(go_type, Some(11 | 15))
         .then_some(transport_progress)
@@ -134,8 +529,7 @@ pub(super) fn object_create(
     // `0x75a07dff` merge, the pitch through the pose commit `0x7c6420`'s unconditional
     // `fst [ecx+0x20]` — and it does so *before* `0x613e10` builds the model or registers the
     // per-frame render callback that reads them, so the tilt is in force on the unit's **first
-    // drawn frame** (byte-VERIFIED; wow-5875-re
-    // `system/collision/scratch/create-block-swim-pitch.md`). A player who swims into view
+    // drawn frame**. A player who swims into view
     // nose-down renders nose-down, not level: [`crate::creature_anim::swim_body_rotation`], the
     // same one law our own avatar and the relay extrapolator call. Without the block's flags +
     // pitch — which we parsed and threw away until now — every observed swimmer entered the world
@@ -191,7 +585,7 @@ pub(super) fn object_create(
         // Where and how big, the moment it streams in — the readout that answers "is this prop in
         // the wrong place, or the wrong size, or just drawn wrong" without a guess (decision 0637:
         // the duel flag read as huge and mislocated, and nothing in the client could say which).
-        // `RUST_LOG=benilla_app::net::apply::objects=debug`.
+        // `RUST_LOG=benilla_app::net::objects=debug`.
         debug!(
             "gameobject spawn: entry {:?} display {display_id:?} type {go_type:?} \
              pos [{:.2}, {:.2}, {:.2}] scale {scale}",
@@ -210,11 +604,15 @@ pub(super) fn object_create(
         // Re-create of a tracked guid: refresh identity + pose. A create is a fresh server snapshot, so
         // any in-flight extrapolation is stale too — clear it.
         commands.entity(e).insert(net).remove::<RemoteMotion>();
-        // Speeds go through the drain's stage, never straight onto the entity — a
-        // `SMSG_FORCE_*_SPEED_CHANGE` riding the same tick as this create has to be able to land
-        // on top of it (decision 1478, B213).
+        // Speeds land straight on the entity (decision 2327 — the drain's staging maps are gone):
+        // a fresh create inserts them as a component at spawn, a re-create replaces them whole
+        // (below). A `SMSG_FORCE_*_SPEED_CHANGE` riding the same tick as this create still lands
+        // on top of it, because each handler's commands are applied before the next packet's
+        // runs — 1478's law unchanged (B213, `apply::seam_tests`).
         if let Some(s) = speeds {
-            speed_stage.seed(guid, s);
+            // A create is the server's newest snapshot of the mover: it replaces the set whole
+            // (decision 1478), and lands before the next packet's handler reads it.
+            commands.entity(e).insert(UnitSpeeds(s));
         }
         if let Some(anchor) = transport_anchor {
             commands.entity(e).insert(anchor);
@@ -245,7 +643,7 @@ pub(super) fn object_create(
         write_pose(commands, transforms, e, position, placement);
         // Overlay the fresh snapshot's descriptor fields onto the existing store — the reference's
         // in-place refresh of a live guid, which notifies its field watchers like any delta.
-        merge_fields(stores, pending, edges, e, guid, fields);
+        merge_fields(commands, stores, edges, e, guid, fields);
     } else {
         // A transport spawns hidden: its create pose is the *stationary* spawn point (or worse,
         // the origin), not where the boat is in its cycle — the transport tick unhides it at the
@@ -266,7 +664,7 @@ pub(super) fn object_create(
         // root's `Visibility` through `Mut` writes, which don't re-add the sweep row.
         entity.vis_chain_only();
         if let Some(s) = speeds {
-            speed_stage.seed(guid, s); // staged, like the re-create arm above (1478)
+            entity.insert(UnitSpeeds(s));
         }
         if let Some(anchor) = transport_anchor {
             entity.insert(anchor);
@@ -280,22 +678,50 @@ pub(super) fn object_create(
         if let Some(s) = walk {
             entity.insert(s);
         }
+        // The seed itself is never merged, which is the reference's create-time notify-suppress
+        // (decision 2297).
+        entity.insert(ObjectStore(fields));
         index.0.insert(guid, entity.id());
-        // Seed the store via the pending flush — the entity isn't spawned until the sync point.
-        pending.insert(guid, fields);
     }
 }
 
-/// An item or container entered our view (`SMSG_UPDATE_OBJECT` descriptor-only create) — no scene
-/// entity; the item store owns it.
-pub(super) fn item_create(guid: u64, container: bool, fields: ObjectFields, items: &mut Items) {
+/// An item or container entered our view (`SMSG_UPDATE_OBJECT` descriptor-only create): an
+/// object like any other (decision 2334) — an entity in the index carrying its store, with no
+/// pose and no model. A re-create of a live guid overlays the snapshot through the values path,
+/// which notifies the field watchers like any delta (the scene create's own rule).
+fn item_create(
+    guid: u64,
+    container: bool,
+    fields: ObjectFields,
+    commands: &mut Commands,
+    index: &mut GuidIndex,
+    stores: &mut Query<&mut ObjectStore>,
+    edges: &mut MessageWriter<FieldChanged>,
+    items: &mut Items,
+) {
     debug!("net: item create {guid:#x} (container: {container})");
-    items.insert_object(guid, fields);
+    if let Some(&e) = index.0.get(&guid) {
+        merge_fields(commands, stores, edges, e, guid, fields);
+    } else {
+        let e = crate::items::spawn_item(commands, index, guid, fields, container);
+        // The item arrived: replay the enchant times queued for it while it was not held
+        // (`0x5ebde0`, decision 2340), each through the setter as of now.
+        let queued = items.take_enchant_times(guid);
+        if !queued.is_empty() {
+            let mut countdowns = crate::items::Countdowns::default();
+            for (slot, seconds) in queued {
+                if !countdowns.set_enchant(slot, seconds) {
+                    debug!("enchant timer: queued slot {slot} for {guid:#x} is past the seventh — refused");
+                }
+            }
+            commands.entity(e).insert(countdowns);
+        }
+    }
 }
 
 /// An existing object moved to a new authoritative pose (an `SMSG_UPDATE_OBJECT` movement block) —
 /// a one-off correction/relocation that supersedes any active path.
-pub(super) fn object_move(
+fn object_move(
     guid: u64,
     position: [f32; 3],
     orientation: f32,
@@ -312,13 +738,13 @@ pub(super) fn object_move(
 }
 
 /// A relayed player movement packet (`MSG_MOVE_*`): the mover's authoritative pose + live move
-/// flags. The reference SCHEDULES a remote's apply (decision 0601, wow-re
-/// `remote-apply-timing.md`): the mover's own replay chain gives the packet a client fire-time
+/// flags. The reference SCHEDULES a remote's apply (`0x618c30`, decision 0601): the mover's own
+/// replay chain gives the packet a client fire-time
 /// (decision 0615, [`crate::net::motion::RelayMove`] → `RelayChain::schedule`); an already-due move
 /// applies now, a future one queues on the unit and fires in `drain_pending_moves` — the dead-reckon
 /// covering the mover's own timeline in between, which is what kills the arrival-jitter snap.
 /// `WOW_REMOTE_SNAP=1` restores raw apply-at-arrival for an A/B.
-pub(super) fn unit_move(
+fn unit_move(
     guid: u64,
     mv: crate::net::motion::RelayMove,
     now_ms: f64,
@@ -334,7 +760,7 @@ pub(super) fn unit_move(
     // Addressed to US: the server writing our own pose, never an echo of ours (every one is
     // `SetAsServerSide`, `ctime = 0`). The reference APPLIES it — there is no mover-guid gate
     // anywhere on its inbound move path, and the local player resolves through the same object
-    // lookup as anyone else (decision 0725; wow-re `self-addressed-move.md`). What is ours is only
+    // lookup as anyone else (`0x603bb0`; decision 0725). What is ours is only
     // *where it goes*: our avatar's motion source is the controller, not [`RemoteMotion`], so the
     // pose crosses to `player::wire_in` instead of down this lane.
     if self_guid.0 == Some(guid) {
@@ -433,32 +859,24 @@ pub(super) fn unit_move(
     }
 }
 
-/// A descriptor delta (`SMSG_UPDATE_OBJECT` values block): merge into the object's store — a scene
-/// object's in place (or into the pending seed), an item's into the item store. An unknown guid —
-/// a `Values` with no create seen — is dropped, as before.
-pub(super) fn object_values(
+/// A descriptor delta (`SMSG_UPDATE_OBJECT` values block): merge into the object's store in place
+/// — a unit's, a GameObject's, an item's (decision 2334), one path. An unknown guid — a `Values`
+/// with no create seen — is dropped, as before.
+fn object_values(
     guid: u64,
     fields: ObjectFields,
+    commands: &mut Commands,
     index: &GuidIndex,
     stores: &mut Query<&mut ObjectStore>,
-    pending: &mut HashMap<u64, ObjectFields>,
     edges: &mut MessageWriter<FieldChanged>,
-    items: &mut Items,
 ) {
     if let Some(&e) = index.0.get(&guid) {
-        merge_fields(stores, pending, edges, e, guid, fields);
-    } else if guid::is_item(guid) {
-        items.merge_object(guid, fields);
+        merge_fields(commands, stores, edges, e, guid, fields);
     }
 }
 
 /// The object ceased to exist (`SMSG_DESTROY_OBJECT` — corpse decay ahead of respawn, a despawn).
-pub(super) fn object_destroyed(
-    guid: u64,
-    commands: &mut Commands,
-    index: &mut GuidIndex,
-    items: &mut Items,
-) {
+fn object_destroyed(guid: u64, commands: &mut Commands, index: &mut GuidIndex) {
     // **The object goes away by the same fade its stream-out takes** — `DespawnFade`, not a raw
     // despawn (decision 2198). The reference's object-manager destroy hands the object's *model*
     // to the `SWModelFadeout` scheduler on the way out: the base OnDeactivate `0x6145e0` (vtable
@@ -473,18 +891,28 @@ pub(super) fn object_destroyed(
     // fade is not the animation; it is what every teardown does underneath it.
     //
     // The guid leaves the index either way — to the server it no longer exists, and a respawn
-    // streams in as a fresh entity that fades in over the top. If it was the target, the ring's
-    // gone-entity branch clears the selection next frame, the same as the reference's teardown
-    // (which sends the same `CMSG_SET_SELECTION 0`).
+    // streams in as a fresh entity that fades in over the top. **The object ends here, not when
+    // its model finishes fading** ([`tear_down`]): the entity sheds its [`Guid`] in this same
+    // handler's command flush, so every consumer that means "a live object" stops seeing it at
+    // once — and if it was the target, the ring's gone-object branch clears the selection and
+    // sends `CMSG_SET_SELECTION 0` on its next pass, this frame, as the reference's OnDeactivate
+    // does at the teardown itself (`0x5fbb60` → `0x493910`).
     //
     // …*unless the object is pinned* — `0x464920` on a still-pinned object only sets the
-    // pending-destroy bit and returns, and the real free waits for the last pin to drop (wow-re
-    // `go-display-sound-events.md` §6d). The one pin benilla takes is the despawn animation
+    // pending-destroy bit and returns, and the real free waits for the last pin to drop
+    // (`0x468410`). The one pin benilla takes is the despawn animation
     // announced a moment earlier by `SMSG_GAMEOBJECT_DESPAWN_ANIM`, which is the whole of how an
     // object gets to play its own despawn after the server says it is gone (decision 1404); the
-    // fade then follows the animation, where the deferred destroy runs
-    // ([`crate::go_anim::release_despawn_pin`]).
+    // fade then follows the animation, where the deferred destroy — and so the teardown — runs
+    // ([`crate::go_anim::release_despawn_pin`]). A pinned object is still an object until then.
     if let Some(e) = index.0.remove(&guid) {
+        // An item has no model to hand the fadeout, so it goes now (decision 2334) — what the
+        // scheduler does with a modelless entity anyway, one frame later — and its countdown
+        // cells go with it (2340).
+        if guid::is_item(guid) {
+            commands.entity(e).despawn();
+            return;
+        }
         commands.queue(move |world: &mut bevy::ecs::world::World| {
             if world
                 .get::<crate::go_anim::DespawnAnimAnnounced>(e)
@@ -493,32 +921,56 @@ pub(super) fn object_destroyed(
                 if let Ok(mut ent) = world.get_entity_mut(e) {
                     ent.insert(crate::go_anim::PendingDestroy);
                 }
-            } else if let Ok(mut ent) = world.get_entity_mut(e) {
-                ent.insert(DespawnFade::default());
+            } else if let Ok(ent) = world.get_entity_mut(e) {
+                tear_down(ent);
             }
         });
     }
-    // An item destroy (consumed, sold) never had a scene entity — clear the item store.
-    items.remove_object(guid);
 }
 
 /// Stream-out (out-of-range, the update-object `OutOfRange` block): the unit still exists, we just
 /// left its range.
-pub(super) fn objects_removed(guids: Vec<u64>, commands: &mut Commands, index: &mut GuidIndex) {
+fn objects_removed(guids: Vec<u64>, commands: &mut Commands, index: &mut GuidIndex) {
     // Don't pop the entity, fade it out, then despawn (`apply_despawn_fade` drives the ramp; an
     // entity with no fadeable geometry pops straight out there). Director-verified look: on the
     // reference, distant mobs fade out, never blink out (0067's open question, settled by their
     // eyes). The mechanism behind it is the same one [`object_destroyed`] above now takes — the
     // OUT_OF_RANGE block and DESTROY reach `0x464920` alike, and its OnDeactivate hands the model
     // to the `SWModelFadeout` scheduler either way ([`DespawnFade`], decision 2198). That the two
-    // routes agree is not a convenience here; it is the reference's own shape.
+    // routes agree is not a convenience here; it is the reference's own shape — and so is the
+    // object ending at the stream-out rather than when the fade does ([`tear_down`]): a unit that
+    // walks out of range, vanishes or stealths stops being targetable, TAB-able and hoverable now.
     for g in guids {
         if let Some(e) = index.0.remove(&g) {
-            commands.entity(e).insert(DespawnFade::default());
+            commands.entity(e).queue(tear_down);
         }
     }
 }
 
+/// **An object's teardown** — the reference's `0x464920`, which both `SMSG_DESTROY_OBJECT` and
+/// the OUT_OF_RANGE block reach: the OBJECT is freed on the spot, and only its detached MODEL
+/// survives, handed to the `SWModelFadeout` scheduler to ramp out ([`DespawnFade`], decision
+/// 2198). The OnDeactivate on the way (`0x5fbb60` → `0x493910`) clears the selection if it was
+/// this unit and sends `CMSG_SET_SELECTION 0` — at the teardown, not two seconds later.
+///
+/// benilla keeps the model on the same entity rather than re-parenting it onto a fresh one, so
+/// "the object is gone" is said by taking away the one component that makes an entity an object:
+/// its [`Guid`], the server identity every object consumer keys on — the TAB scan, `/target`,
+/// the mouseover pick, the name and nameplate walks, the minimap blips, the quest markers, the
+/// chat bubbles, the selection ring's gone-object branch, the unit feed's "left the manager"
+/// gate. What the model needs to finish drawing stays: the [`NetEntity`] the renderer reads, and
+/// the [`ObjectStore`] the animation driver reads — a corpse that decays keeps lying dead while
+/// it fades instead of reading as alive and standing up. The guid has already left the
+/// [`GuidIndex`] (the caller's job), so a same-tick re-create of it (corpse → respawn) spawns a
+/// fresh object beside the fading model, and nothing ever sees two objects with one guid.
+///
+/// Every teardown goes through here: both wire routes, and a pinned object's deferred destroy
+/// ([`crate::go_anim::release_despawn_pin`]).
+pub(crate) fn tear_down(mut ent: EntityWorldMut) {
+    ent.remove::<Guid>();
+    ent.insert(DespawnFade::default());
+}
+
 /// A creature path packet (`SMSG_MONSTER_MOVE`, or its deck twin `SMSG_MONSTER_MOVE_TRANSPORT`):
 /// settle the unit's transport membership, apply the dictated facing snap, then attach or clear
 /// the travel spline.
@@ -529,7 +981,7 @@ pub(super) fn objects_removed(guids: Vec<u64>, commands: &mut Commands, index: &
 /// rider's local pose for `transport::compose_riders` to carry out to the world. When it is `None`
 /// on a unit we had riding, the unit has *left* the deck — vmangos drops it from the transport on
 /// exactly this edge (`MoveSplineInit::Launch`, `spline/MoveSplineInit.cpp:156-159`).
-pub(super) fn monster_move(
+fn monster_move(
     guid: u64,
     transport: Option<u64>,
     start: [f32; 3],
@@ -572,9 +1024,9 @@ pub(super) fn monster_move(
         // bearing and are rebased here by the deck's own yaw.
         //
         // **Above the root gate deliberately.** The gate below refuses the *path*, which is what
-        // wow-re establishes; membership is not a path. A rooted body on a deck that was left
-        // unattached would be abandoned in the sea as the boat sails out from under it, which is
-        // a worse failure than carrying a pinned body along with the deck it is standing on.
+        // the reference establishes; membership is not a path. A rooted body on a deck that was
+        // left unattached would be abandoned in the sea as the boat sails out from under it, which
+        // is a worse failure than carrying a pinned body along with the deck it is standing on.
         let deck_yaw = |t: u64| {
             index
                 .0
@@ -633,8 +1085,8 @@ pub(super) fn monster_move(
         // that moved, the display smoother's state goes with it: the unit re-seeds from this
         // pose instead of swinging back to the heading it was snapped off. When a real path
         // follows, `sample_splines` overwrites the rotation with the travel direction each
-        // frame (faithful — the client's spline-follow snaps the mesh yaw to the path tangent;
-        // wow-re body-facing §4). The receipt snap thus only sticks for a path-less move (a
+        // frame (faithful — the client's spline-follow snaps the mesh yaw to the path tangent,
+        // `0x7c5490`). The receipt snap thus only sticks for a path-less move (a
         // `Stop`/in-place re-face); a moving unit ends on its last tangent.
         // The world-space facing snap — for a deck packet the rider's `local_orientation` above is
         // the one that counts, and `compose_riders` writes the rotation from it.
@@ -658,9 +1110,8 @@ pub(super) fn monster_move(
         // A spline move **un-nocks and drops the weapon-visual hold**, unconditionally:
         // `0x6018f0` (this packet's handler, via `0x603f00` registered on opcodes 0xDD/0x2AE) has
         // exactly one `ret`, and its shared tail runs `0x6020e8 call 0x60d040` (clear `0x400`) →
-        // `0x6020ef call 0x60f530` (un-nock) → `RecomputeBaseAnim(-1)` on every path through it
-        // (wow-re `shooter-stop-law.md` §J1.2/§J1.3, byte-verified over the whole extent). So an
-        // archer NPC yanked along a path, or a player charged/knocked back, loses the arrow —
+        // `0x6020ef call 0x60f530` (un-nock) → `RecomputeBaseAnim(-1)` on every path through it.
+        // So an archer NPC yanked along a path, or a player charged/knocked back, loses the arrow —
         // the ranged sheath is untouched, exactly like the locomotion un-nock.
         commands.entity(e).remove::<(
             crate::creature_anim::NockLatch,
@@ -669,16 +1120,14 @@ pub(super) fn monster_move(
         // **A rooted unit cannot be splined** (decision 1780). `0x6187a0` — the *server
         // position/spline apply*, and the sole path from this packet's parse chain into
         // `CMovement`'s spline installer `0x7c6a50` — opens with `0x6187c2 test ah,0x10` and
-        // returns on ROOT (wow-re `moveflag-family.md` §5.3, and §5.4's verdict in as many words:
-        // *"cannot translate, cannot jump, cannot be splined"*).
+        // returns on ROOT: a rooted unit cannot translate, cannot jump, cannot be splined.
         //
-        // **Scoped to the path deliberately.** What is byte-verified is that the *position/spline*
+        // **Scoped to the path deliberately.** What is settled is that the *position/spline*
         // apply is refused; whether the rest of `0x6018f0` still runs for a rooted unit is not
-        // recorded, and the one part of it we do know — the un-nock tail — is verified to run on
-        // **every** path through the handler (`shooter-stop-law.md` §J1.2/§J1.3), so it stays above
-        // this gate. The facing snap is left running for the same reason: refusing more than the
-        // note establishes would be inventing a behaviour, and refusing the path is what keeps the
-        // body still.
+        // known, and the one part of it we do know — the un-nock tail — runs on **every** path
+        // through the handler (`0x6020ef`), so it stays above this gate. The facing snap is left
+        // running for the same reason: refusing more than the reference establishes would be
+        // inventing a behaviour, and refusing the path is what keeps the body still.
         //
         // On vmangos this is a race rather than the common case — `Unit::SetRooted(true)` calls
         // `StopMoving()` before the root goes out, so an already-walking creature is normally
@@ -719,26 +1168,15 @@ pub(super) fn monster_move(
     }
 }
 
-/// **Per-drain staging for [`UnitMoveModes`]** — the same shape (and the same reason) as
-/// [`merge_fields`]' `pending`: a component this drain inserted through `Commands` is not queryable
-/// until the sync point, so a grant and the packet it changes the meaning of can arrive in one drain
-/// and the second must see the first. Seeded lazily from the live component; never read after the
-/// drain.
-pub(super) type StagedModes = HashMap<u64, UnitMoveModes>;
-
-/// This unit's granted modes as of *now within the drain* — the staged word if it was granted this
-/// drain, else the live component, else none. The reference's word lives as long as the `CGUnit`, so
-/// "no component" and "all bits clear" are the same answer and both are [`UnitMoveModes::default`].
-pub(super) fn modes_of(
-    guid: u64,
-    index: &GuidIndex,
-    modes: &Query<&mut UnitMoveModes>,
-    staged: &StagedModes,
-) -> UnitMoveModes {
-    staged
+/// This unit's granted modes as of now — the live component, else none. A grant lands before
+/// the next packet's handler reads it (decision 2306). The reference's word lives as long as the
+/// `CGUnit`, so "no component" and "all bits clear" are the same answer and both are
+/// [`UnitMoveModes::default`].
+fn modes_of(guid: u64, index: &GuidIndex, modes: &Query<&mut UnitMoveModes>) -> UnitMoveModes {
+    index
+        .0
         .get(&guid)
-        .copied()
-        .or_else(|| index.0.get(&guid).and_then(|&e| modes.get(e).ok().copied()))
+        .and_then(|&e| modes.get(e).ok().copied())
         .unwrap_or_default()
 }
 
@@ -754,7 +1192,7 @@ pub(super) fn modes_of(
 /// the reference applies to whatever it finds — so we do too. It is inert on the avatar either way:
 /// the animation selector's `unify` gives the controller's own `MovementState` precedence, and our
 /// mover's modes are the handshake family's ([`crate::player::state::MoveModes`]).
-pub(super) fn spline_move_mode(
+fn spline_move_mode(
     guid: u64,
     mode: SplineMode,
     apply: bool,
@@ -762,14 +1200,12 @@ pub(super) fn spline_move_mode(
     index: &GuidIndex,
     modes: &mut Query<&mut UnitMoveModes>,
     remote: &mut Query<&mut RemoteMotion>,
-    staged: &mut StagedModes,
 ) {
     let Some(&e) = index.0.get(&guid) else {
         return; // no such unit — the reference drops it too
     };
-    let mut word = modes_of(guid, index, modes, staged);
+    let mut word = modes_of(guid, index, modes);
     word.set(mode, apply);
-    staged.insert(guid, word);
     if let Ok(mut live) = modes.get_mut(e) {
         *live = word;
     } else {
@@ -801,7 +1237,7 @@ pub(super) fn spline_move_mode(
 /// The ask-once GameObject template (`SMSG_GAMEOBJECT_QUERY_RESPONSE`, decision 0239): cache it and
 /// resolve the lockId from the type-specific `data[]` slot — the interact routing reads it to choose
 /// use-vs-cast; the hover tooltip reads the name (decision 0276's GO law).
-pub(super) fn gameobject_info(
+fn gameobject_info(
     entry: u32,
     type_id: u32,
     display_id: u32,
@@ -813,115 +1249,63 @@ pub(super) fn gameobject_info(
     go_templates.insert(entry, type_id, name, data);
 }
 
-/// Merge a descriptor delta into an object's store: into the per-drain `pending` seed when the entity was
-/// created earlier this same drain (its spawn `Command` hasn't run, so it isn't queryable yet), else in
-/// place on the live component. The final `else` — in the index but neither live nor pending — should not
-/// happen (a create always seeds `pending` first), but seeds defensively rather than drop the delta.
+/// Merge a descriptor delta into an object's live store. The `else` — in the index but with no
+/// store — should not happen (a create inserts the store at spawn, and lands before the next
+/// packet's handler), but seeds defensively rather than drop the delta.
 ///
-/// Every merge reports its field edges ([`FieldChanged`], decision 2297) — into the pending seed
-/// too: a create and a values delta for the same guid in one drain are two wire blocks, and the
-/// reference notifies on the second. The seed itself is never merged, which is the reference's
-/// create-time notify-suppress.
+/// Every merge reports its field edges ([`FieldChanged`], decision 2297): a create and a values
+/// delta for the same guid are two wire blocks, and the reference notifies on the second.
 fn merge_fields(
+    commands: &mut Commands,
     stores: &mut Query<&mut ObjectStore>,
-    pending: &mut HashMap<u64, ObjectFields>,
     edges: &mut MessageWriter<FieldChanged>,
     entity: Entity,
     guid: u64,
     delta: ObjectFields,
 ) {
-    if let Some(f) = pending.get_mut(&guid) {
-        merge_store_fields(f, delta, entity, guid, |e| {
-            edges.write(e);
-        });
-    } else if let Ok(mut s) = stores.get_mut(entity) {
+    if let Ok(mut s) = stores.get_mut(entity) {
         merge_store_fields(&mut s.0, delta, entity, guid, |e| {
             edges.write(e);
         });
     } else {
-        pending.insert(guid, delta);
+        warn!(
+            "net: values delta for {guid:#x} found no store on its entity — seeding from the delta"
+        );
+        commands.entity(entity).insert(ObjectStore(delta));
     }
 }
 
-/// Per-drain staging for every mover's [`UnitSpeeds`] — the drain's single speed writer
-/// (decision 1478).
+/// Write one speed-kind slot of a mover's live [`UnitSpeeds`]. `false` means there is nowhere to
+/// write — an untracked guid, or a mover whose create carried no movement block — and the change
+/// is reported unapplied rather than silently dropped.
 ///
-/// The two speed sources used to disagree about *when* they land. [`object_create`] inserts a whole
-/// speed set through `Commands`, which is deferred to the drain's sync point; a
-/// `SMSG_FORCE_*_SPEED_CHANGE` edited one slot of the live component immediately. Mixed in one
-/// drain, the **later packet loses** either way: on an entity born this drain the component isn't
-/// there yet so the query miss was silent, and on one that already existed the create's deferred
-/// insert landed afterwards and overwrote it.
-///
-/// vmangos puts exactly those two packets back to back on purpose. `HandleMoveWorldportAckOpcode`
-/// sends the self create block inside `Map::Add` → `SendInitSelf` (carrying the speeds the player
-/// still has) and then, three statements later, strips the mount on a map that forbids one
-/// (`if (!mEntry->IsMountAllowed()) RemoveSpellsCausingAura(SPELL_AURA_MOUNTED)`) — whose
-/// `SMSG_FORCE_RUN_SPEED_CHANGE` therefore rides the same tick, and so the same drain. That is
-/// B213: `.tele` into BWL/LBRS on a mount auto-dismounted you and left the mount's run speed on
-/// foot, because the create's 11.2 yd/s landed last.
-///
-/// So both sources stage here instead, **in packet order**, and the drain flushes once at the end —
-/// the `pending: HashMap<u64, ObjectFields>` pattern (decision 0061) applied to speeds. Nothing
-/// writes the component directly any more, which is what makes the order the wire's order.
-#[derive(Default)]
-pub(super) struct SpeedStage(HashMap<u64, MoveSpeeds>);
-
-impl SpeedStage {
-    /// A create block's whole speed set. A create is the server's newest snapshot of the mover, so
-    /// it **replaces** anything staged for that guid rather than merging into it.
-    fn seed(&mut self, guid: u64, speeds: MoveSpeeds) {
-        self.0.insert(guid, speeds);
+/// The two speed sources used to disagree about *when* they land (decision 1478, B213): a
+/// create's whole set was inserted through `Commands`, deferred to the drain's sync point, while
+/// a `SMSG_FORCE_*_SPEED_CHANGE` edited the live component at once — so the later packet lost
+/// either way when vmangos put the two back to back (`HandleMoveWorldportAckOpcode`'s self create
+/// and the mount strip three statements later). Under a handler per packet the create's insert
+/// lands before the change's handler runs (decision 2306), so both write the component and the
+/// wire's order is the order.
+fn set_speed(
+    guid: u64,
+    kind: SpeedKind,
+    speed: f32,
+    index: &GuidIndex,
+    speeds: &mut Query<&mut UnitSpeeds>,
+) -> bool {
+    let Some(mut s) = index.0.get(&guid).and_then(|&e| speeds.get_mut(e).ok()) else {
+        return false;
+    };
+    let s = &mut s.0;
+    match kind {
+        SpeedKind::Walk => s.walk = speed,
+        SpeedKind::Run => s.run = speed,
+        SpeedKind::RunBack => s.run_back = speed,
+        SpeedKind::Swim => s.swim = speed,
+        SpeedKind::SwimBack => s.swim_back = speed,
+        SpeedKind::TurnRate => s.turn_rate = speed,
     }
-
-    /// Write one speed-kind slot, seeding the staged set from the live component on first touch.
-    /// `live` is only called when nothing is staged yet; `None` from it means there is nowhere to
-    /// write — an untracked guid, or a mover whose create carried no movement block — and the
-    /// change is reported unapplied rather than silently dropped.
-    fn set(
-        &mut self,
-        guid: u64,
-        kind: SpeedKind,
-        speed: f32,
-        live: impl FnOnce() -> Option<MoveSpeeds>,
-    ) -> bool {
-        let s = match self.0.entry(guid) {
-            Entry::Occupied(o) => o.into_mut(),
-            Entry::Vacant(v) => match live() {
-                Some(s) => v.insert(s),
-                None => return false,
-            },
-        };
-        match kind {
-            SpeedKind::Walk => s.walk = speed,
-            SpeedKind::Run => s.run = speed,
-            SpeedKind::RunBack => s.run_back = speed,
-            SpeedKind::Swim => s.swim = speed,
-            SpeedKind::SwimBack => s.swim_back = speed,
-            SpeedKind::TurnRate => s.turn_rate = speed,
-        }
-        true
-    }
-
-    /// Land every staged set on its entity, now that this drain's spawn `Command`s have run.
-    /// `try_insert`: the same drain may have queued a despawn for it (a stream-out, the worldport
-    /// purge), and a guid the purge dropped from the index resolves to nothing at all.
-    pub(super) fn flush(self, commands: &mut Commands, index: &GuidIndex) {
-        for (guid, speeds) in self.0 {
-            if let Some(&e) = index.0.get(&guid) {
-                commands.entity(e).try_insert(UnitSpeeds(speeds));
-            }
-        }
-    }
-}
-
-/// Read a mover's live speed set — [`SpeedStage::set`]'s seed for a mover that already exists.
-fn live_speeds(index: &GuidIndex, speeds: &Query<&UnitSpeeds>, guid: u64) -> Option<MoveSpeeds> {
-    index
-        .0
-        .get(&guid)
-        .and_then(|&e| speeds.get(e).ok())
-        .map(|s| s.0)
+    true
 }
 
 /// A forced speed change on a mover (aura/mount/GM `.modify speed`): stage the new value onto the
@@ -929,18 +1313,17 @@ fn live_speeds(index: &GuidIndex, speeds: &Query<&UnitSpeeds>, guid: u64) -> Opt
 /// answers the mandatory ack with its live pose (the TeleportMessage pattern). An unknown guid
 /// still acks if it's ours-by-guid; a foreign mover (we never control others) is only applied,
 /// never acked — acking a unit we don't control is the server's error path.
-pub(super) fn force_speed_change(
+fn force_speed_change(
     guid: u64,
     kind: SpeedKind,
     counter: u32,
     speed: f32,
     index: &GuidIndex,
-    speeds: &Query<&UnitSpeeds>,
-    stage: &mut SpeedStage,
+    speeds: &mut Query<&mut UnitSpeeds>,
     self_guid: &SelfGuid,
     speed_changes: &mut MessageWriter<SpeedChangeMessage>,
 ) {
-    let applied = stage.set(guid, kind, speed, || live_speeds(index, speeds, guid));
+    let applied = set_speed(guid, kind, speed, index, speeds);
     if self_guid.0 == Some(guid) {
         info!("net: force {kind:?} speed change -> {speed} yd/s (counter {counter})");
         // Our own mover having no speed set to write is B213's failure shape, and it was silent
@@ -949,7 +1332,7 @@ pub(super) fn force_speed_change(
         if !applied {
             warn!(
                 "net: force {kind:?} speed change for OUR mover {guid:#x} landed nowhere \
-                 (no speed set staged or live) — we still ack, so the server and we now disagree"
+                 (no live speed set) — we still ack, so the server and we now disagree"
             );
         }
         speed_changes.write(SpeedChangeMessage {
@@ -966,15 +1349,14 @@ pub(super) fn force_speed_change(
 /// An observed unit's speed changed (the SPLINE_SET / MOVE_SET families — another player
 /// mounting up, a hastened creature): stage it onto that unit's speed set, nothing to ack
 /// (decision 0441). The MOVE_SET flavour's pose already arrived as its own UnitMove.
-pub(super) fn speed_changed(
+fn speed_changed(
     guid: u64,
     kind: SpeedKind,
     speed: f32,
     index: &GuidIndex,
-    speeds: &Query<&UnitSpeeds>,
-    stage: &mut SpeedStage,
+    speeds: &mut Query<&mut UnitSpeeds>,
 ) {
-    if !stage.set(guid, kind, speed, || live_speeds(index, speeds, guid)) {
+    if !set_speed(guid, kind, speed, index, speeds) {
         // Ordinary: a unit's speed broadcast can outrun its create block. Nothing to ack and the
         // create that follows carries the same set, so this self-heals.
         debug!("net: {kind:?} speed change for untracked mover {guid:#x} — nothing to write");
@@ -985,7 +1367,104 @@ pub(super) fn speed_changed(
 mod tests {
     use super::*;
 
-    const ME: u64 = 0x0000_0000_0000_002A;
+    /// **An item's countdowns are its own cells** (decision 2340), end to end through the real
+    /// registration on the built client: `0x1EB` for an item not yet held waits on the active
+    /// player and is replayed into the item's cells when its create lands, `0x1EA` for one not
+    /// held is dropped for good, a refused slot writes nothing, and the destroy takes the cells
+    /// with the object. Without an active player to queue on, the enchant update is dropped too.
+    #[test]
+    fn item_countdowns_live_on_the_item_and_a_queued_enchant_waits_for_it() {
+        use crate::items::Countdowns;
+        const ME: u64 = 0x0000_0000_0000_0007;
+        const SWORD: u64 = 0x4000_0000_0000_0042;
+        const STONE: u64 = 0x4000_0000_0000_0043;
+        let mut app = crate::game_plugins::schedule_tests::headless_client();
+        let world = app.world_mut();
+        let create = |guid| SessionEvent::ItemCreate {
+            guid,
+            container: false,
+            fields: ObjectFields::from_pairs(&[(3, 117)]),
+        };
+        let cells = |world: &World, guid: u64| -> Option<Countdowns> {
+            let e = *world.resource::<GuidIndex>().0.get(&guid)?;
+            world.get::<Countdowns>(e).cloned()
+        };
+
+        // No active player: the enchant update has nowhere to wait.
+        super::super::handlers::dispatch(
+            world,
+            vec![
+                SessionEvent::ItemEnchantTime {
+                    item_guid: STONE,
+                    slot: 1,
+                    seconds: 60,
+                },
+                create(STONE),
+            ],
+        );
+        assert_eq!(
+            cells(world, STONE),
+            Some(Countdowns::default()),
+            "dropped, not queued"
+        );
+
+        // With the active player resolving, it waits for the item — and the lifetime does not.
+        let me = world.spawn_empty().id();
+        world.resource_mut::<GuidIndex>().0.insert(ME, me);
+        world.resource_mut::<SelfGuid>().0 = Some(ME);
+        super::super::handlers::dispatch(
+            world,
+            vec![
+                SessionEvent::ItemEnchantTime {
+                    item_guid: SWORD,
+                    slot: 1,
+                    seconds: 90,
+                },
+                SessionEvent::ItemTime {
+                    item_guid: SWORD,
+                    seconds: 600,
+                },
+            ],
+        );
+        assert_eq!(cells(world, SWORD), None, "nothing held yet");
+        super::super::handlers::dispatch(world, vec![create(SWORD)]);
+        let c = cells(world, SWORD).expect("the create spawned the item with its cells");
+        assert!(
+            c.enchant_remaining_ms(1)
+                .is_some_and(|ms| (89_000..=90_000).contains(&ms)),
+            "the queued enchant replayed as of the create"
+        );
+        assert_eq!(
+            c.lifetime_remaining_ms(),
+            None,
+            "`0x1EA` for an unheld item has no queue"
+        );
+
+        // Held now: both arms write the cells directly; a slot past the array writes nothing.
+        super::super::handlers::dispatch(
+            world,
+            vec![
+                SessionEvent::ItemTime {
+                    item_guid: SWORD,
+                    seconds: 600,
+                },
+                SessionEvent::ItemEnchantTime {
+                    item_guid: SWORD,
+                    slot: 9,
+                    seconds: 30,
+                },
+            ],
+        );
+        let c = cells(world, SWORD).unwrap();
+        assert!(c.lifetime_remaining_ms().is_some());
+        assert!(c.enchant_remaining_ms(1).is_some());
+
+        // The destroy takes the object and its cells with it.
+        let e = world.resource::<GuidIndex>().0[&SWORD];
+        super::super::handlers::dispatch(world, vec![SessionEvent::ObjectDestroyed(SWORD)]);
+        assert!(!world.resource::<GuidIndex>().0.contains_key(&SWORD));
+        assert!(world.get_entity(e).is_err(), "the cells died with the item");
+    }
 
     /// The observer movement-mode family's own harness (decision 1780): one indexed unit, and a
     /// `World` small enough that the only thing that can move it is the code under test.
@@ -1034,7 +1513,6 @@ mod tests {
                       index: Res<GuidIndex>,
                       mut modes: Query<&mut UnitMoveModes>,
                       mut remote: Query<&mut RemoteMotion>| {
-                    let mut staged = StagedModes::new();
                     spline_move_mode(
                         MOB,
                         mode,
@@ -1043,7 +1521,6 @@ mod tests {
                         &index,
                         &mut modes,
                         &mut remote,
-                        &mut staged,
                     );
                 },
             )
@@ -1147,7 +1624,6 @@ mod tests {
                  index: Res<GuidIndex>,
                  mut modes: Query<&mut UnitMoveModes>,
                  mut remote: Query<&mut RemoteMotion>| {
-                    let mut staged = StagedModes::new();
                     spline_move_mode(
                         0xDEAD_BEEF,
                         SplineMode::Root,
@@ -1156,11 +1632,6 @@ mod tests {
                         &index,
                         &mut modes,
                         &mut remote,
-                        &mut staged,
-                    );
-                    assert!(
-                        staged.is_empty(),
-                        "nothing staged for a unit we do not have"
                     );
                 },
             )
@@ -1172,10 +1643,10 @@ mod tests {
         /// opens `0x6187c2 test ah,0x10` and returns. So a path the server queued before it pinned
         /// the body does not move it.
         ///
-        /// The gate is scoped to the *path*, not to the packet: what wow-re establishes is that
-        /// the position/spline apply is refused, and the one other thing the handler is known to do
-        /// (the un-nock tail) is verified to run on every path through it. The assertion below is
-        /// therefore about the `Spline` and nothing else.
+        /// The gate is scoped to the *path*, not to the packet: what the reference establishes is
+        /// that the position/spline apply is refused, and the one other thing the handler is known
+        /// to do (the un-nock tail, `0x6020ef`) runs on every path through it. The assertion below
+        /// is therefore about the `Spline` and nothing else.
         #[test]
         fn a_rooted_unit_refuses_the_path_the_server_queued() {
             let mut w = World::new();
@@ -1338,115 +1809,4 @@ mod tests {
             assert_eq!(w.entity(e).get::<Spline>().expect("a path").deck, None);
         }
     }
-
-    /// A dismounted human's set — 1.12.1's base run 7.0 (the `--speed` probe's own golden).
-    fn on_foot() -> MoveSpeeds {
-        MoveSpeeds {
-            walk: 2.5,
-            run: 7.0,
-            run_back: 4.5,
-            swim: 4.722_222,
-            swim_back: 2.5,
-            turn_rate: std::f32::consts::PI,
-        }
-    }
-
-    /// The same set with a 60% mount's run speed on it — what `SendInitSelf` puts in the create
-    /// block of a worldport that is *about* to strip the mount.
-    fn mounted() -> MoveSpeeds {
-        MoveSpeeds {
-            run: 11.2,
-            ..on_foot()
-        }
-    }
-
-    /// **B213, pinned.** vmangos's `HandleMoveWorldportAckOpcode` sends the self create block
-    /// (`Map::Add` → `SendInitSelf`, still carrying the mount's 11.2 yd/s) and then, three
-    /// statements later, strips the mount because the destination map forbids one — so
-    /// `SMSG_FORCE_RUN_SPEED_CHANGE` 7.0 rides the same tick and lands in the same drain.
-    /// Staged in packet order the change wins; before 1478 the create's *deferred* `UnitSpeeds`
-    /// insert landed last and `.tele` into BWL left the avatar running at mount speed on foot.
-    #[test]
-    fn a_force_change_beats_a_create_from_the_same_drain() {
-        let mut stage = SpeedStage::default();
-        stage.seed(ME, mounted());
-        assert!(stage.set(ME, SpeedKind::Run, 7.0, || panic!(
-            "the create staged a set this drain — the live component must not be consulted"
-        )));
-        stage.flush_into(|guid, s| {
-            assert_eq!(guid, ME);
-            assert_eq!(s.run, 7.0, "the dismount is the newer packet");
-            assert_eq!(
-                s.walk, 2.5,
-                "the other slots still come from the create block"
-            );
-        });
-    }
-
-    /// The reverse order is just as much the wire's order: a create block is the server's newest
-    /// snapshot of the mover, so one arriving *after* a change replaces it whole rather than
-    /// merging under it.
-    #[test]
-    fn a_create_after_a_change_replaces_it() {
-        let mut stage = SpeedStage::default();
-        assert!(stage.set(ME, SpeedKind::Run, 7.0, || Some(mounted())));
-        stage.seed(ME, mounted());
-        stage.flush_into(|_, s| assert_eq!(s.run, 11.2));
-    }
-
-    /// Nothing staged yet (an entity that has existed since an earlier drain): the live component
-    /// seeds the cell, so a one-slot change keeps every other slot it isn't addressing.
-    #[test]
-    fn a_change_on_a_live_mover_seeds_from_the_component() {
-        let mut stage = SpeedStage::default();
-        assert!(stage.set(ME, SpeedKind::Run, 11.2, || Some(on_foot())));
-        stage.flush_into(|_, s| {
-            assert_eq!(s.run, 11.2);
-            assert_eq!(s.run_back, on_foot().run_back);
-            assert_eq!(s.turn_rate, on_foot().turn_rate);
-        });
-    }
-
-    /// A change with nowhere to land — an untracked guid, or a mover whose create carried no
-    /// movement block — reports itself unapplied rather than vanishing. It stages nothing, so a
-    /// later create can't inherit a slot invented for a set that never existed.
-    #[test]
-    fn a_change_with_no_speed_set_is_reported_not_swallowed() {
-        let mut stage = SpeedStage::default();
-        assert!(!stage.set(ME, SpeedKind::Run, 7.0, || None));
-        let mut flushed = 0;
-        stage.flush_into(|_, _| flushed += 1);
-        assert_eq!(flushed, 0);
-    }
-
-    /// The trap itself, machine-checked rather than asserted in prose: a component inserted
-    /// through this drain's `Commands` is **not** visible to a query in the same drain — the spawn
-    /// only runs at the sync point. That is why staging is the fix and why a live-component write
-    /// could never have been the fix: the force-change arm had nothing to write onto.
-    #[test]
-    fn a_component_this_drain_queued_is_invisible_until_the_sync_point() {
-        use bevy::ecs::system::RunSystemOnce;
-        let mut world = World::new();
-        let missed = world
-            .run_system_once(|mut commands: Commands, live: Query<&UnitSpeeds>| {
-                let e = commands.spawn(UnitSpeeds(mounted())).id();
-                live.get(e).is_err()
-            })
-            .expect("the probe system runs");
-        assert!(
-            missed,
-            "a create's UnitSpeeds must be unreadable later in the same drain — if this ever \
-             passes, `Commands` stopped being deferred and 1478's staging can be reconsidered"
-        );
-    }
-
-    impl SpeedStage {
-        /// [`SpeedStage::flush`] without the ECS half — the staged sets in the shape the flush
-        /// would insert them, so the ordering rules above are testable as the pure thing they are.
-        fn flush_into(self, mut f: impl FnMut(u64, MoveSpeeds)) {
-            for (guid, speeds) in self.0 {
-                f(guid, speeds);
-            }
-        }
-    }
 }
diff --git a/crates/benilla-app/src/net/apply/session.rs b/crates/benilla-app/src/net/session.rs
similarity index 57%
rename from crates/benilla-app/src/net/apply/session.rs
rename to crates/benilla-app/src/net/session.rs
index 1544b7f6..e7ecb911 100644
--- a/crates/benilla-app/src/net/apply/session.rs
+++ b/crates/benilla-app/src/net/session.rs
@@ -1,8 +1,10 @@
-//! Session-lifecycle arm bodies for [`super::apply_net_updates`]'s dispatch match — the connection
-//! edges (the login stages, character select, entering the world, logout, the disconnect
-//! teardown), our own teleport/worldport snaps, the server clock, and the login reputation store.
-//! Each `pub(super)` fn here is exactly one arm's body; the match at the call site stays the
-//! dispatcher, one call per arm.
+//! The bridge's own session handlers (in the net handler table since 2326, moved out of the
+//! drain's session arm file) — the connection edges (the login stages, character select,
+//! entering the world, logout, the disconnect teardown), our own teleport/worldport snaps and
+//! control edges, the server clock, the login reputation store, and the player's login-scoped
+//! stores the bridge defines (the home bind, the proficiencies). Registered from
+//! [`super::NetPlugin`], ahead of every window plugin, so the teardown runs before the windows'
+//! session-end listeners — each a second handler on `Disconnected`.
 
 use benilla_protocol::messages::Character;
 use benilla_protocol::JumpInfo;
@@ -10,35 +12,345 @@ use bevy::prelude::*;
 
 use crate::items::Items;
 use crate::names::NameCache;
-use crate::ui_chat::ChatLog;
-use crate::ui_gossip::GossipState;
-use crate::ui_loot::LootState;
-use crate::ui_mail::MailOpen;
-use crate::ui_merchant::MerchantOpen;
 use crate::ui_quest::QuestGiver;
-use crate::ui_quest_log::QuestLog;
-use crate::ui_taxi::TaxiState;
-use crate::ui_trainer::TrainerOpen;
 
-use super::super::{
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::ecs::system::SystemParam;
+
+use super::{
     CharActionResultMessage, CharListMessage, CharacterLoginFailedMessage,
-    CinematicTriggeredMessage, DisconnectedMessage, DroppedOpcodes, EnteredWorldMessage, GameTime,
-    GuidIndex, KnockBackMessage, LoggedOutMessage, LoginFailedMessage, LoginStageMessage,
-    NetStatus, PendingTransfer, Reputations, SelfGuid, ServerTime, ServerWallClock,
-    TeleportMessage, WorldportMessage,
+    CinematicTriggeredMessage, ClientControlMessage, DisconnectedMessage, DroppedOpcodes,
+    EnteredWorldMessage, GameTime, GuidIndex, HomeBind, KnockBackMessage, LoggedOutMessage,
+    LoginFailedMessage, LoginQueuedMessage, LoginStageMessage, NetCommands, NetHandlerApp,
+    NetStatus, ObjectStore, PendingTransfer, Proficiencies, RealmListMessage, Reputations,
+    SelfGuid, ServerTime, ServerWallClock, TeleportMessage, WorldportMessage,
 };
 
-/// The pre-logon handshake reached a new stage (decision 0539) — the login screen's dialog reads it.
-pub(super) fn login_stage(
-    stage: benilla_protocol::LoginStage,
-    out: &mut MessageWriter<LoginStageMessage>,
+/// Register the session handlers — called from [`super::NetPlugin`].
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::LoginStage, on_login_edge)
+        .net_handler(K::LoginQueued, on_login_edge)
+        .net_handler(K::LoginFailed, on_login_edge)
+        .net_handler(K::RealmList, on_login_edge)
+        .net_handler(K::CharacterList, on_character_list)
+        .net_handler(K::CharActionResult, on_login_edge)
+        .net_handler(K::CharacterLoginFailed, on_login_edge)
+        .net_handler(K::CinematicTriggered, on_login_edge)
+        .net_handler(K::Connected, on_connected)
+        .net_handler(K::LoggedOut, on_logged_out)
+        .net_handler(K::Disconnected, on_disconnected)
+        .net_handler(K::Teleport, on_mover_edge)
+        .net_handler(K::KnockBack, on_mover_edge)
+        .net_handler(K::ClientControl, on_mover_edge)
+        .net_handler(K::Worldport, on_worldport)
+        .net_handler(K::TransferPending, on_transfer)
+        .net_handler(K::TransferAborted, on_transfer)
+        .net_handler(K::TimeSpeed, on_clock)
+        .net_handler(K::ServerUnixTime, on_clock)
+        .net_handler(K::Reputations, on_reputations)
+        .net_handler(K::ReputationDelta, on_reputation_delta)
+        .net_handler(K::ReputationVisible, on_reputations)
+        .net_handler(K::BindPoint, on_player_store)
+        .net_handler(K::Proficiency, on_player_store)
+        .net_handler(K::PacketDropped, on_packet_dropped)
+        .net_handler(K::Pong, on_pong);
+}
+
+/// The edges the bridge publishes as messages — the login screen's, the character screen's,
+/// the controller's — and the two resources they park in.
+#[derive(SystemParam)]
+pub(crate) struct Edges<'w> {
+    teleports: MessageWriter<'w, TeleportMessage>,
+    worldports: MessageWriter<'w, WorldportMessage>,
+    char_lists: MessageWriter<'w, CharListMessage>,
+    realm_lists: MessageWriter<'w, RealmListMessage>,
+    char_actions: MessageWriter<'w, CharActionResultMessage>,
+    char_login_failures: MessageWriter<'w, CharacterLoginFailedMessage>,
+    entered_world: MessageWriter<'w, EnteredWorldMessage>,
+    addon_reply: ResMut<'w, super::AddonInfoReply>,
+    logged_out: MessageWriter<'w, LoggedOutMessage>,
+    knockbacks: MessageWriter<'w, KnockBackMessage>,
+    login_stages: MessageWriter<'w, LoginStageMessage>,
+    login_queued: MessageWriter<'w, LoginQueuedMessage>,
+    login_failures: MessageWriter<'w, LoginFailedMessage>,
+    disconnects: MessageWriter<'w, DisconnectedMessage>,
+    client_control: MessageWriter<'w, ClientControlMessage>,
+    cinematics: MessageWriter<'w, CinematicTriggeredMessage>,
+    transfer: ResMut<'w, PendingTransfer>,
+}
+
+/// The bridge's own state the session edges write: the guid index and our guid, the status,
+/// the ask-once caches the teardown clears, the clocks, the reputations and the player's stores.
+#[derive(SystemParam)]
+pub(crate) struct Bridge<'w, 's> {
+    commands: Commands<'w, 's>,
+    index: ResMut<'w, GuidIndex>,
+    self_guid: ResMut<'w, SelfGuid>,
+    status: ResMut<'w, NetStatus>,
+    names: ResMut<'w, NameCache>,
+    items: ResMut<'w, Items>,
+    cooldowns: ResMut<'w, crate::spell::Cooldowns>,
+    reputations: ResMut<'w, Reputations>,
+    server_time: ResMut<'w, ServerTime>,
+    wall_clock: ResMut<'w, ServerWallClock>,
+    home_bind: ResMut<'w, HomeBind>,
+    proficiencies: ResMut<'w, Proficiencies>,
+    dropped: ResMut<'w, DroppedOpcodes>,
+    net: Res<'w, NetCommands>,
+    stores: Query<'w, 's, &'static mut ObjectStore>,
+    transports: Query<'w, 's, &'static crate::transport::Transport>,
+}
+
+fn on_login_edge(In(ev): In<SessionEvent>, mut e: Edges) {
+    match ev {
+        SessionEvent::LoginStage { stage } => login_stage(stage, &mut e.login_stages),
+        SessionEvent::LoginQueued { position, realm } => {
+            e.login_queued.write(LoginQueuedMessage { position, realm });
+        }
+        SessionEvent::LoginFailed {
+            refusal,
+            reason,
+            terminal,
+            dial,
+        } => login_failed(refusal, reason, terminal, dial, &mut e.login_failures),
+        SessionEvent::RealmList { realms } => {
+            e.realm_lists.write(RealmListMessage { realms });
+        }
+        SessionEvent::CharActionResult { action, code } => {
+            char_action_result(action, code, &mut e.char_actions)
+        }
+        SessionEvent::CharacterLoginFailed { result } => {
+            character_login_failed(result, &mut e.char_login_failures)
+        }
+        SessionEvent::CinematicTriggered { cinematic_id } => {
+            cinematic_triggered(cinematic_id, &mut e.cinematics)
+        }
+        _ => {}
+    }
+}
+
+fn on_character_list(In(ev): In<SessionEvent>, mut e: Edges, mut b: Bridge) {
+    if let SessionEvent::CharacterList { characters, realm } = ev {
+        character_list(characters, realm, &mut b.status, &mut e.char_lists);
+    }
+}
+
+fn on_connected(In(ev): In<SessionEvent>, mut e: Edges, mut b: Bridge) {
+    if let SessionEvent::Connected {
+        self_guid: guid,
+        name,
+        billing_time_rested,
+        tutorial_flags,
+        addon_info,
+    } = ev
+    {
+        connected(
+            guid,
+            name,
+            billing_time_rested,
+            tutorial_flags,
+            addon_info,
+            &mut e.addon_reply,
+            &mut b.self_guid,
+            &mut b.status,
+            &mut b.names,
+            &mut e.entered_world,
+        );
+    }
+}
+
+fn on_logged_out(In(ev): In<SessionEvent>, mut e: Edges, mut b: Bridge) {
+    if let SessionEvent::LoggedOut = ev {
+        logged_out(
+            &mut b.commands,
+            &mut b.index,
+            &mut b.self_guid,
+            &mut e.logged_out,
+        );
+    }
+}
+
+/// The teardown — the bridge's own half of the session end. Every window that dies with the
+/// socket has its own listener on this kind, registered after this one and so run after it.
+fn on_disconnected(In(ev): In<SessionEvent>, mut e: Edges, mut b: Bridge) {
+    if let SessionEvent::Disconnected { reason, end } = ev {
+        disconnected(
+            reason,
+            end,
+            &mut b.commands,
+            &mut b.index,
+            &mut b.self_guid,
+            &mut b.status,
+            &mut b.names,
+            &mut b.items,
+            &mut b.cooldowns,
+            &mut e.transfer,
+            &mut e.disconnects,
+        );
+    }
+}
+
+/// The three server-authored mover edges the controller both *applies* and *answers*: a
+/// teleport snap, a knockback launch (decision 1702) and possession's control half (B211),
+/// forwarded whole and unjudged — only the controller can act on them.
+fn on_mover_edge(In(ev): In<SessionEvent>, mut e: Edges, b: Bridge) {
+    match ev {
+        SessionEvent::Teleport {
+            guid,
+            counter,
+            position,
+            orientation,
+        } => teleport(
+            guid,
+            counter,
+            position,
+            orientation,
+            &b.self_guid,
+            &mut e.teleports,
+        ),
+        SessionEvent::KnockBack {
+            guid,
+            counter,
+            launch,
+        } => knock_back(guid, counter, launch, &b.self_guid, &mut e.knockbacks),
+        SessionEvent::ClientControl { mover, allow_move } => {
+            e.client_control
+                .write(ClientControlMessage { mover, allow_move });
+        }
+        _ => {}
+    }
+}
+
+fn on_worldport(
+    In(ev): In<SessionEvent>,
+    mut e: Edges,
+    mut b: Bridge,
+    mut group: ResMut<crate::ui_party::GroupState>,
 ) {
+    if let SessionEvent::Worldport {
+        map_id,
+        position,
+        orientation,
+        needs_ack,
+    } = ev
+    {
+        // Every streamed roster member's object is about to be purged — the same deactivation
+        // the reference runs one object at a time (decision 1640).
+        crate::ui_party::net::roster_deactivated(&mut group, &b.index, &b.stores, &b.net);
+        worldport(
+            map_id,
+            position,
+            orientation,
+            needs_ack,
+            &mut b.commands,
+            &mut b.index,
+            &mut e.transfer,
+            &b.transports,
+            &mut e.worldports,
+        );
+    }
+}
+
+fn on_transfer(In(ev): In<SessionEvent>, mut e: Edges) {
+    match ev {
+        SessionEvent::TransferPending {
+            map_id,
+            transport_entry,
+        } => transfer_pending(map_id, transport_entry, &mut e.transfer),
+        SessionEvent::TransferAborted { reason } => transfer_aborted(reason, &mut e.transfer),
+        _ => {}
+    }
+}
+
+fn on_clock(In(ev): In<SessionEvent>, mut b: Bridge) {
+    match ev {
+        SessionEvent::TimeSpeed {
+            hours,
+            minutes,
+            day_serial,
+            timescale,
+        } => time_speed(hours, minutes, day_serial, timescale, &mut b.server_time),
+        SessionEvent::ServerUnixTime { unix_time } => {
+            server_unix_time(unix_time, &mut b.wall_clock)
+        }
+        _ => {}
+    }
+}
+
+fn on_reputations(In(ev): In<SessionEvent>, mut b: Bridge) {
+    match ev {
+        SessionEvent::Reputations { standings } => reputations(standings, &mut b.reputations),
+        SessionEvent::ReputationVisible { list_id } => {
+            reputation_visible(list_id, &mut b.reputations)
+        }
+        _ => {}
+    }
+}
+
+/// The chat line reads the deltas against the store, so it runs BEFORE the overwrite — after
+/// it, every delta is zero. One handler for both legs, for that order.
+fn on_reputation_delta(
+    In(ev): In<SessionEvent>,
+    mut b: Bridge,
+    factions: Option<Res<crate::target::ring::Factions>>,
+    mut chat_log: ResMut<crate::ui_chat::ChatLog>,
+    mut quest: ResMut<QuestGiver>,
+) {
+    if let SessionEvent::ReputationDelta { standings } = ev {
+        crate::combat_log::chat::faction_standing(
+            &standings,
+            &b.reputations,
+            factions.as_deref(),
+            &mut chat_log,
+        );
+        reputation_delta(standings, &mut b.reputations, &mut quest);
+    }
+}
+
+/// The player's login-scoped stores the bridge defines.
+fn on_player_store(In(ev): In<SessionEvent>, mut b: Bridge) {
+    match ev {
+        SessionEvent::BindPoint { area } => b.home_bind.0 = Some(area),
+        SessionEvent::Proficiency {
+            item_class,
+            subclass_mask,
+        } => {
+            b.proficiencies.0.insert(item_class, subclass_mask);
+        }
+        _ => {}
+    }
+}
+
+fn on_packet_dropped(In(ev): In<SessionEvent>, mut b: Bridge) {
+    if let SessionEvent::PacketDropped {
+        opcode,
+        unparseable,
+    } = ev
+    {
+        packet_dropped(opcode, unparseable, &mut b.dropped);
+    }
+}
+
+/// **The pong never gets here** — the read thread measures it against the ping clock the
+/// instant it lands and stops it, the way the reference's `OnData 0x537b10` hands `SMSG_PONG`
+/// to `HandlePong 0x537d60` inline instead of queueing it (`net::io`). Reaching this handler
+/// means that bypass was undone and every latency reading is a client frame too slow again,
+/// which is B346 exactly — so it says so out loud rather than measuring here and hiding it.
+fn on_pong(In(ev): In<SessionEvent>) {
+    if let SessionEvent::Pong { sequence } = ev {
+        warn!("net: pong seq={sequence} reached the drain — the read thread's RTT bypass is gone (B346)");
+    }
+}
+
+/// The pre-logon handshake reached a new stage (decision 0539) — the login screen's dialog reads it.
+fn login_stage(stage: benilla_protocol::LoginStage, out: &mut MessageWriter<LoginStageMessage>) {
     out.write(LoginStageMessage { stage });
 }
 
 /// A login attempt failed before the roster (decision 0539): the IO thread is back at its pre-logon
 /// park, and [`crate::login`]'s policy decides what happens next.
-pub(super) fn login_failed(
+fn login_failed(
     refusal: Option<benilla_protocol::LoginRefusal>,
     reason: String,
     terminal: bool,
@@ -55,7 +367,7 @@ pub(super) fn login_failed(
 
 /// The verdict on a character create/delete (`SMSG_CHAR_CREATE`/`SMSG_CHAR_DELETE`) — the glue
 /// screen turns the code into its own refusal string.
-pub(super) fn char_action_result(
+fn char_action_result(
     action: benilla_protocol::CharAction,
     code: u8,
     out: &mut MessageWriter<CharActionResultMessage>,
@@ -65,7 +377,7 @@ pub(super) fn char_action_result(
 
 /// The account's character roster (`SMSG_CHAR_ENUM`): the world socket is authenticated and parked
 /// at character select — surface the list (+ the connected realm's identity) to the glue screen.
-pub(super) fn character_list(
+fn character_list(
     characters: Vec<Character>,
     realm: Option<benilla_protocol::RealmInfo>,
     status: &mut NetStatus,
@@ -85,10 +397,7 @@ pub(super) fn character_list(
 
 /// The server refused the character we picked (`SMSG_CHARACTER_LOGIN_FAILED`) — the entry
 /// announced a moment ago is void. `crate::char_select` takes the screen back and says why.
-pub(super) fn character_login_failed(
-    result: u8,
-    out: &mut MessageWriter<CharacterLoginFailedMessage>,
-) {
+fn character_login_failed(result: u8, out: &mut MessageWriter<CharacterLoginFailedMessage>) {
     warn!("net: character login refused (result {result:#04x})");
     out.write(CharacterLoginFailedMessage { result });
 }
@@ -102,7 +411,7 @@ pub(super) fn character_login_failed(
 /// — so the ack must still happen, at the *end* of playback rather than instantly. The cinematic
 /// plugin sends it on a natural end, on an ESC skip, and immediately for a trigger it cannot
 /// resolve to a shot, so no path drops it.
-pub(super) fn cinematic_triggered(
+fn cinematic_triggered(
     cinematic_id: u32,
     triggered: &mut MessageWriter<CinematicTriggeredMessage>,
 ) {
@@ -112,7 +421,7 @@ pub(super) fn cinematic_triggered(
 
 /// We are in the world (the IO thread's first in-world event): record our guid, flip the status,
 /// and seed the name cache with our own name.
-pub(super) fn connected(
+fn connected(
     guid: u64,
     name: String,
     billing_time_rested: u32,
@@ -147,7 +456,7 @@ pub(super) fn connected(
 }
 
 /// The server confirmed our logout (`SMSG_LOGOUT_COMPLETE`) — back to character select.
-pub(super) fn logged_out(
+fn logged_out(
     commands: &mut Commands,
     index: &mut GuidIndex,
     self_guid: &mut SelfGuid,
@@ -169,7 +478,7 @@ pub(super) fn logged_out(
 
 /// The session ended (socket closed / handshake failure): tear down the streamed world and clear
 /// every session-scoped cache.
-pub(super) fn disconnected(
+fn disconnected(
     reason: String,
     end: benilla_protocol::SessionEnd,
     commands: &mut Commands,
@@ -178,28 +487,7 @@ pub(super) fn disconnected(
     status: &mut NetStatus,
     names: &mut NameCache,
     items: &mut Items,
-    gossip: &mut GossipState,
-    merchant: &mut MerchantOpen,
-    trainer_open: &mut TrainerOpen,
-    loot: &mut LootState,
-    loot_latch: &mut crate::ui_loot::LootLatch,
-    loot_rolls: &mut crate::ui_loot_roll::LootRolls,
-    chat_log: &mut ChatLog,
-    quest: &mut QuestGiver,
-    quest_log: &mut QuestLog,
-    quest_share: &mut crate::ui_quest_share::QuestShare,
-    death_net: &mut crate::death::DeathNet,
-    group: &mut crate::ui_party::GroupState,
-    taxi: &mut TaxiState,
-    mail: &mut MailOpen,
-    mail_pending: &mut crate::ui_mail::MailPending,
-    trade: &mut crate::ui_trade::TradeSession,
-    bank: &mut crate::ui_bank::BankOpen,
-    duel: &mut crate::ui_duel::DuelState,
-    social: &mut crate::ui_social::SocialState,
-    guild: &mut crate::ui_guild::GuildState,
-    gm_ticket: &mut crate::ui_gm_ticket::GmTicketState,
-    cooldowns: &mut crate::cooldowns::Cooldowns,
+    cooldowns: &mut crate::spell::Cooldowns,
     pending_transfer: &mut PendingTransfer,
     disconnects: &mut MessageWriter<DisconnectedMessage>,
 ) {
@@ -244,65 +532,18 @@ pub(super) fn disconnected(
     // In-flight name queries died with the socket; let the next resolve re-ask.
     names.clear_pending();
     items.clear_session();
-    gossip.clear_session();
-    merchant.clear_session();
-    trainer_open.clear_session();
-    loot.clear_session();
-    loot_latch.0 = None; // the kneel latch dies with the socket (unconditional here)
-    loot_rolls.clear(); // open group rolls die with the socket (decision 0591)
-    chat_log.clear_session();
-    quest.clear_session();
-    quest_log.clear_session();
-    // A verdict on a share nobody is listening for any more, and a confirm whose server-side
-    // latch died with the socket (decision 1733).
-    quest_share.clear_session();
-    group.clear_session();
-    taxi.clear_session();
-    mail.clear_session();
-    // The arrival countdown is login-scoped (decision 0544 P3): a fresh login re-queries
-    // `MSG_QUERY_NEXT_MAIL_TIME` at world-enter, so nothing carries over across a reconnect.
-    *mail_pending = crate::ui_mail::MailPending::default();
-    // An open trade dies with the socket too (decision 0592) — the reconnect starts with no trade.
-    trade.clear_session();
-    // The bank window dies with the socket (decision 0604) — a reconnect re-opens via the banker.
-    bank.clear_session();
-    // A pending challenge, a running duel, and its countdown all die with the socket
-    // (decision 0633) — the server drops the duel too (`Player::DuelComplete(DUEL_FLED)` on
-    // logout), and a stale arbiter guid would make the next AcceptDuel echo a dead object.
-    *duel = crate::ui_duel::DuelState::default();
-    // The friend/ignore lists and the last `/who` are session state too (decision 0668): the
-    // server re-pushes both lists at the next login, and a stale ignore list would silence the
-    // wrong guids after a reconnect renumbers nothing but re-streams everything. The `/who` sort
-    // chain is the one thing that survives — it is per-PROCESS in the reference, not per-login
-    // (decision 2030), which is why this is a `clear_session` and not a `default()`.
-    social.clear_session();
-    // The guild session is login-scoped the same way (decision 1257) — and more strictly, because
-    // the next login may be a *different character*, whose guild id, rank, rights and roster share
-    // nothing with this one's. The identity cache goes too: it is keyed by guild id, so it would
-    // survive correctly, but the reference's own is backed by `guildcache.wdb` and re-primed
-    // lazily, and keeping a cache alive across a socket only to save one query is not worth the
-    // one wrong name a renamed guild would show.
-    *guild = crate::ui_guild::GuildState::default();
-    // The GM ticket is login-scoped too (decision 1673), and for a sharper reason than most: the
-    // ticket belongs to the CHARACTER, and the next login may be a different one. Its answer
-    // counters go with it, so the first `SMSG_GMTICKET_GETTICKET` of the new session re-fires
-    // `UPDATE_TICKET` rather than being diffed away against the old character's answer count.
-    gm_ticket.clear_session();
-    // The cooldown list is session-scoped for the same reason and had been missing from this
-    // sweep since it was built (decision 2116). `SMSG_INITIAL_SPELLS` carries every cooldown
+    // The cooldown list is session-scoped — the next login may be a different character — and
+    // had been missing from this sweep since it was built (decision 2116). `SMSG_INITIAL_SPELLS` carries every cooldown
     // still running at every world entry and `seed_initial` APPENDS, so a list that outlives the
     // socket answers the old session's records: a second login on the same character reads its
     // own stale copy over the wire's fresh remainder, and a login on a different character
     // inherits cooldowns that were never theirs.
     cooldowns.clear_session();
-    // The death stores are session-scoped too: a reclaim expiry, resurrect offer, or corpse
-    // marker must not survive the socket (the reconnect re-sends the reclaim delay when dead).
-    *death_net = crate::death::DeathNet::default();
 }
 
 /// A teleport ack request (`MSG_MOVE_TELEPORT_ACK`) — only our own matters (the ack resumes our
 /// movement); the controller consumes the message.
-pub(super) fn teleport(
+fn teleport(
     guid: u64,
     counter: u32,
     position: [f32; 3],
@@ -327,10 +568,9 @@ pub(super) fn teleport(
 ///
 /// The guid guard is the same one every self-addressed movement edge here carries. The reference
 /// registers this opcode for the **controller** only; the observer's knockback arrives on a
-/// different opcode with a different handler (`MSG_MOVE_KNOCK_BACK`, wow-re
-/// `system/collision/scratch/knockback-law.md`), so a knockback naming somebody else is not ours to
-/// fly.
-pub(super) fn knock_back(
+/// different opcode with a different handler (`MSG_MOVE_KNOCK_BACK`, `0x603bb0` rather than
+/// `0x603f90`), so a knockback naming somebody else is not ours to fly.
+fn knock_back(
     guid: u64,
     counter: u32,
     launch: JumpInfo,
@@ -348,11 +588,7 @@ pub(super) fn knock_back(
 
 /// The far-teleport preamble (`SMSG_TRANSFER_PENDING`): latch it for the coming worldport —
 /// its transport block decides whether NEW_WORLD's coordinates are boat-local (decision 0455).
-pub(super) fn transfer_pending(
-    map_id: u32,
-    transport_entry: Option<u32>,
-    pending: &mut PendingTransfer,
-) {
+fn transfer_pending(map_id: u32, transport_entry: Option<u32>, pending: &mut PendingTransfer) {
     match transport_entry {
         Some(entry) => info!("net: transfer pending → map {map_id} riding transport {entry}"),
         None => info!("net: transfer pending → map {map_id}"),
@@ -364,7 +600,7 @@ pub(super) fn transfer_pending(
 }
 
 /// `SMSG_TRANSFER_ABORTED`: the announced transfer won't happen — clear the latch.
-pub(super) fn transfer_aborted(reason: u8, pending: &mut PendingTransfer) {
+fn transfer_aborted(reason: u8, pending: &mut PendingTransfer) {
     warn!("net: transfer aborted (reason {reason})");
     pending.0 = None;
 }
@@ -378,7 +614,7 @@ pub(super) fn transfer_aborted(reason: u8, pending: &mut PendingTransfer) {
 /// the seam (the `CurrentMap` flip itself flips which legs render), keeping the ride attachment
 /// and the deck collider valid the whole way; the server's post-ack re-create then refreshes its
 /// anchor in place. Boats whose paths never reach the new map despawn like everything else.
-pub(super) fn worldport(
+fn worldport(
     map_id: u32,
     position: [f32; 3],
     orientation: f32,
@@ -421,7 +657,7 @@ pub(super) fn worldport(
 }
 
 /// The server game clock (`SMSG_LOGIN_SETTIMESPEED`) — drives the day/night lighting.
-pub(super) fn time_speed(
+fn time_speed(
     hours: u8,
     minutes: u8,
     day_serial: u32,
@@ -441,7 +677,7 @@ pub(super) fn time_speed(
 ///
 /// Logged once per session at info, with the skew against our own clock: that number is exactly
 /// what a "the countdown is wrong by a constant" report would be about, and it costs one line.
-pub(super) fn server_unix_time(unix_time: u32, clock: &mut ServerWallClock) {
+fn server_unix_time(unix_time: u32, clock: &mut ServerWallClock) {
     if clock.0.is_none() {
         let local = std::time::SystemTime::now()
             .duration_since(std::time::UNIX_EPOCH)
@@ -456,7 +692,7 @@ pub(super) fn server_unix_time(unix_time: u32, clock: &mut ServerWallClock) {
 }
 
 /// The login reputation store (`SMSG_INITIALIZE_FACTIONS`).
-pub(super) fn reputations(standings: Vec<(u8, i32)>, reputations: &mut Reputations) {
+fn reputations(standings: Vec<(u8, i32)>, reputations: &mut Reputations) {
     info!("net: reputation store ({} slots)", standings.len());
     reputations.0 = standings;
 }
@@ -465,13 +701,13 @@ pub(super) fn reputations(standings: Vec<(u8, i32)>, reputations: &mut Reputatio
 /// growing the store for a list id past the login snapshot (flags default 0 — the delta carries
 /// none), and **auto-reveal** each one.
 ///
-/// The auto-reveal is the client's own (wow-5875-re `reputation-panel-law.md`, the `0x124` handler):
+/// The auto-reveal is the client's own (the `0x124` handler `0x4d5760`):
 /// gaining reputation with a faction makes it visible, unless the slot carries `HIDDEN` — which is
 /// exactly what that bit is for, and is why it is not a list gate. The server pushes an
 /// `SMSG_SET_FACTION_VISIBLE` for the same slot in most cases (vmangos `SetOneFactionReputation`
 /// calls `SetVisible`), so this is usually belt to that braces; it matters when the reveal and the
 /// standing arrive in the other order, and it is what the client does regardless.
-pub(super) fn reputation_delta(
+fn reputation_delta(
     standings: Vec<(u32, i32)>,
     reputations: &mut Reputations,
     quest: &mut QuestGiver,
@@ -501,7 +737,7 @@ pub(super) fn reputation_delta(
 /// standing** — the slot's standing was already correct and stays untouched. Dropping it is the
 /// silent failure it exists to prevent: the pane keys row membership off this bit, so a faction met
 /// mid-session would keep accruing reputation the player could never see.
-pub(super) fn reputation_visible(list_id: u32, reputations: &mut Reputations) {
+fn reputation_visible(list_id: u32, reputations: &mut Reputations) {
     let Some(i) = reputation_slot(list_id, "SMSG_SET_FACTION_VISIBLE") else {
         return;
     };
@@ -531,7 +767,7 @@ fn reputation_slot(list_id: u32, opcode: &str) -> Option<usize> {
 /// The dropped-packet tally (the wire-coverage instrument): count it, and announce each opcode's
 /// FIRST drop at info — visible in any log without the panel open, and one line per opcode per
 /// run, so it can never flood.
-pub(super) fn packet_dropped(opcode: u16, unparseable: bool, dropped: &mut DroppedOpcodes) {
+fn packet_dropped(opcode: u16, unparseable: bool, dropped: &mut DroppedOpcodes) {
     let tally = dropped.0.entry(opcode).or_default();
     if tally.unknown + tally.unparseable == 0 {
         info!(
diff --git a/crates/benilla-app/src/net/world.rs b/crates/benilla-app/src/net/world.rs
new file mode 100644
index 00000000..6b121d12
--- /dev/null
+++ b/crates/benilla-app/src/net/world.rs
@@ -0,0 +1,80 @@
+//! The bridge's own world feed (in the net handler table since 2325, moved out of the drain's
+//! world arm file) — what the server pushes about the *world* rather than about an entity or a
+//! window, forwarded by the bridge because what receives it is not an app subsystem: the weather
+//! change goes to the world crate's weather as a [`WeatherMessage`], and the world-state table the
+//! UI's `$<n>w` tokens read is a cache the bridge initialises ([`WorldStates`]). Registered from
+//! [`super::NetPlugin`].
+
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use benilla_world::weather::WeatherMessage;
+use bevy::prelude::*;
+
+use super::NetHandlerApp;
+use crate::world_state::WorldStates;
+
+/// Register the two handlers — called from [`super::NetPlugin`].
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::Weather, on_weather)
+        .net_handler(K::WorldStates, on_world_states);
+}
+
+fn on_weather(In(ev): In<SessionEvent>, mut out: MessageWriter<WeatherMessage>) {
+    if let SessionEvent::Weather {
+        weather_type,
+        grade,
+        sound_id,
+        instant,
+    } = ev
+    {
+        weather(weather_type, grade, sound_id, instant, &mut out);
+    }
+}
+
+fn on_world_states(In(ev): In<SessionEvent>, mut states: ResMut<WorldStates>) {
+    if let SessionEvent::WorldStates {
+        scope,
+        states: pairs,
+    } = ev
+    {
+        world_states(scope, pairs, &mut states);
+    }
+}
+
+/// `SMSG_WEATHER` — the zone's weather change (`instant` on zone entry, a ramp otherwise).
+fn weather(
+    weather_type: u32,
+    grade: f32,
+    sound_id: u32,
+    instant: bool,
+    out: &mut MessageWriter<WeatherMessage>,
+) {
+    out.write(WeatherMessage {
+        weather_type,
+        grade,
+        sound_id,
+        instant,
+    });
+}
+
+/// `SMSG_INIT_WORLD_STATES` / `SMSG_UPDATE_WORLD_STATE` — both wires funnel into the one setter,
+/// as the reference's own handler does.
+///
+/// An **init clears the table first** and records its `(map, zone)` as the world-state UI's display
+/// filter — the reference's `0x4c5650`, which runs before the pair loop (rationale on
+/// [`crate::world_state`]). The order below
+/// is that handler's: clear + scope, then the packet's pairs.
+fn world_states(
+    scope: Option<(u32, u32)>,
+    states: Vec<(u32, u32)>,
+    world_states: &mut WorldStates,
+) {
+    if let Some((map, zone)) = scope {
+        debug!(
+            "world states: map {map} zone {zone}, {} entries",
+            states.len()
+        );
+        world_states.init_scope(map, zone);
+    }
+    world_states.write(&states);
+}
diff --git a/crates/benilla-app/src/npc_text.rs b/crates/benilla-app/src/npc_text.rs
index e81bb3f0..9f7e7750 100644
--- a/crates/benilla-app/src/npc_text.rs
+++ b/crates/benilla-app/src/npc_text.rs
@@ -5,8 +5,8 @@
 //! 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 grammar is the reference's, carved at the bytes (wow-re `QuestTextParser.cpp`, driver
-//! `0x506f70` → token handler `0x5070a0`):
+//! The grammar is the reference's (`QuestTextParser.cpp`, driver `0x506f70` → token handler
+//! `0x5070a0`):
 //!
 //! - 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;
@@ -224,7 +224,7 @@ 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 (`questtext-macro-expander.md` §1): look the guid up in the
+/// 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
@@ -239,8 +239,9 @@ pub(crate) fn subject_for_guid(
     if guid == 0 {
         return None;
     }
-    let name = names.resolve(guid, commands)?.to_string();
-    if let Some(store) = index.0.get(&guid).and_then(|e| stores.get(*e).ok()) {
+    let store = index.0.get(&guid).and_then(|e| stores.get(*e).ok());
+    let name = names.resolve_unit(guid, store, commands)?.to_string();
+    if let Some(store) = store {
         return Some(Subject {
             name,
             race: store.0.unit_race().unwrap_or(0),
@@ -250,7 +251,7 @@ pub(crate) fn subject_for_guid(
     }
     // 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 (§3, orchestrator ruling).
+    // race/class for `$R`/`$C` either; it emits the unit's name instead (`0x50716b`/`0x5071f7`).
     let (race, class, gender) = names.player_traits(guid).unwrap_or((0, 0, 0));
     Some(Subject {
         name,
diff --git a/crates/benilla-app/src/pending_item_ops.rs b/crates/benilla-app/src/pending_item_ops.rs
index 5687cc06..97ff1448 100644
--- a/crates/benilla-app/src/pending_item_ops.rs
+++ b/crates/benilla-app/src/pending_item_ops.rs
@@ -118,7 +118,21 @@ impl PendingItemOps {
         if !matched {
             return self.clear_all();
         }
+        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.
+    pub(crate) fn clear_by_guid(&mut self, item_guid: u64) -> Vec<(i64, u32)> {
         let mut unlocked = Vec::new();
+        if item_guid == 0 {
+            return unlocked;
+        }
         self.entries.retain(|entry| {
             let hit = entry.iter().any(|&(_, (guid, _))| guid == item_guid);
             if hit {
@@ -134,6 +148,16 @@ 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.
+    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.
     fn clear_all(&mut self) -> Vec<(i64, u32)> {
@@ -151,9 +175,10 @@ impl PendingItemOps {
     }
 }
 
-/// `(bag, slot)` pairs whose app-lock cleared this frame, from EITHER clear: the server failure
-/// (`net/apply/loot.rs::inventory_failure`, which owns the wire event but has no `UiScript` to
-/// fire `ITEM_LOCK_CHANGED` through) and the resolving field-update watch
+/// `(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.
@@ -253,6 +278,24 @@ 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();
+        p.add([(0, 3, 100, 1)]); // the opened lockbox
+        p.add([(1, 2, 200, 1)]); // an unrelated move
+
+        assert!(p.clear_by_guid(999).is_empty(), "an unrecorded guid");
+        assert!(p.clear_by_guid(0).is_empty(), "the zero guid fires nothing");
+        assert!(p.contains(0, 3) && p.contains(1, 2));
+
+        let epoch = p.epoch();
+        assert_eq!(p.clear_by_guid(100), vec![(0, 3)]);
+        assert!(!p.contains(0, 3) && p.contains(1, 2));
+        assert!(p.epoch() > epoch, "the feed's gate sees the lock set move");
+    }
+
     #[test]
     fn clear_by_failure_clears_everything_on_zero_or_unmatched_guid() {
         let mut p = PendingItemOps::default();
diff --git a/crates/benilla-app/src/perf/clock.rs b/crates/benilla-app/src/perf/clock.rs
index 40502d7a..7a8ebe53 100644
--- a/crates/benilla-app/src/perf/clock.rs
+++ b/crates/benilla-app/src/perf/clock.rs
@@ -10,7 +10,7 @@
 /// (`getrusage(RUSAGE_SELF)`).
 ///
 /// The perf probes report wall-clock frame time, which on this machine is not a usable regression
-/// instrument: parallel session worktrees build on the same 14 cores, and two identical probe runs
+/// 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
diff --git a/crates/benilla-app/src/perf/crash_inject.rs b/crates/benilla-app/src/perf/crash_inject.rs
new file mode 100644
index 00000000..eb9647ea
--- /dev/null
+++ b/crates/benilla-app/src/perf/crash_inject.rs
@@ -0,0 +1,40 @@
+//! `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.
+//!
+//! **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.
+
+use bevy::prelude::*;
+
+/// Arm the injector when the switch is set; register nothing otherwise.
+pub(super) fn arm(app: &mut App) {
+    if let Some(at) = std::env::var("WOW_CRASH_INJECT")
+        .ok()
+        .and_then(|v| v.parse::<f32>().ok())
+    {
+        app.insert_resource(CrashInject { at });
+        app.add_systems(Update, crash_inject);
+    }
+}
+
+#[derive(Resource)]
+struct CrashInject {
+    at: f32,
+}
+
+fn crash_inject(inject: Res<CrashInject>, time: Res<Time<bevy::time::Real>>) {
+    if time.elapsed_secs() >= inject.at {
+        warn!(
+            "crash-inject: panicking the main thread at {:.1} s",
+            inject.at
+        );
+        panic!("crash-inject: deliberate panic (WOW_CRASH_INJECT)");
+    }
+}
diff --git a/crates/benilla-app/src/perf/hud.rs b/crates/benilla-app/src/perf/hud.rs
index 5290ad0f..5ec91e3d 100644
--- a/crates/benilla-app/src/perf/hud.rs
+++ b/crates/benilla-app/src/perf/hud.rs
@@ -69,7 +69,7 @@ const HUD_REFRESH_SECS: f32 = 0.25;
 /// 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 (`scripts/leg.sh`), so the constant baked into
+/// 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.
@@ -352,6 +352,7 @@ mod tests {
     /// it drives stays the shipped one.
     #[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
diff --git a/crates/benilla-app/src/perf/mod.rs b/crates/benilla-app/src/perf/mod.rs
index 7b198905..4345ad72 100644
--- a/crates/benilla-app/src/perf/mod.rs
+++ b/crates/benilla-app/src/perf/mod.rs
@@ -56,6 +56,8 @@ mod blend_check;
 mod census;
 mod clock;
 #[cfg(feature = "dev")]
+mod crash_inject;
+#[cfg(feature = "dev")]
 mod gpu;
 #[cfg(feature = "dev")]
 mod hud;
@@ -196,6 +198,10 @@ impl Plugin for PerfPlugin {
             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.
+        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).
diff --git a/crates/benilla-app/src/perf/stall.rs b/crates/benilla-app/src/perf/stall.rs
index aeb6cac5..756d02a8 100644
--- a/crates/benilla-app/src/perf/stall.rs
+++ b/crates/benilla-app/src/perf/stall.rs
@@ -135,10 +135,9 @@ fn arm_injectors(app: &mut App) {
             app.insert_resource(TeardownWedge(ms));
         }
     }
-    // The third injector lives with the instrument it exercises — `crash::arm_injector`, a
-    // deliberate main-thread panic — and is armed from here so all three standing injectors
-    // are named in one place.
-    crate::crash::arm_injector(app);
+    // 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).
 }
 
 fn watchdog(dir: Option<std::path::PathBuf>) {
diff --git a/crates/benilla-app/src/player.rs b/crates/benilla-app/src/player.rs
index 77160706..3f69801e 100644
--- a/crates/benilla-app/src/player.rs
+++ b/crates/benilla-app/src/player.rs
@@ -41,11 +41,12 @@ use benilla_world::interact::{WorldClick, WorldRightClick, WorldRightPress};
 use benilla_world::schedule::WorldStage;
 
 mod arc;
+mod net;
 // Writing the frame onto the body we drive — pose, MovementState, the counter-twist gap.
 mod body_pose;
 pub(crate) mod camera;
-// The one smoothed-scalar channel the reference instantiates four times (wow-re
-// `camera-cvar-gates.md` §8) — pitch, pitch-bias, ground tilt and the pivot height, one template.
+// The one smoothed-scalar channel the reference instantiates four times (all stepped by
+// `0x50f160`) — pitch, pitch-bias, ground tilt and the pivot height, one template.
 mod camera_channel;
 // The four 1.12 camera option toggles and the mechanisms behind them (decision 2149).
 pub(crate) mod camera_dynamics;
@@ -157,10 +158,8 @@ pub(crate) use view_subject::ViewSubject;
 /// the gate: re-read at the bytes, those two addresses are inside **`ToggleSheath 0x5eb480`** and
 /// **`CanLootNow 0x5ec110`**, and **no site in the whole `0x40000` census touches animation
 /// selection**. What stops the idle twitch under a stun is the animation clock being stopped
-/// (0889's proc-11 freeze), not this flag. The claim came in quoted verbatim from wow-re
-/// `object-layer/scratch/unit-flags-movement-gates.md` §2/§3, which is being corrected there too —
-/// a stale line in one repo re-entering the other is exactly the failure mode both contracts warn
-/// about, and it survived here for a fortnight because a doc comment is not a gate.
+/// (0889's proc-11 freeze), not this flag. The claim survived here for a fortnight because a doc
+/// comment is not a gate.
 ///
 /// The census's other movement-relevant consumers are real and stay: the two relayed
 /// `MSG_MOVE_*` wrappers that refuse outright (`0x602b20` StartTurn, `0x602b80` StartPitch — the
@@ -171,8 +170,7 @@ pub(crate) const UNIT_FLAG_STUNNED: u32 = 0x0004_0000;
 /// **`IsSelfControlled`** — the reference's `0x5fa550` (`5fa566 a9 04 00 c0 00 test eax, 0xc00004`):
 /// is this unit acting under its *own* control? False while `DISABLE_MOVE` (`0x4`), `CONFUSED`
 /// (`0x400000`) or `FLEEING` (`0x800000`) — and note what is **absent**: `UNIT_FLAG_STUNNED` is
-/// not in the mask (it has its own, separate gate), and neither is the taxi bit. wow-re
-/// `object-layer/scratch/unit-flags-movement-gates.md` §4.
+/// not in the mask (it has its own, separate gate), and neither is the taxi bit.
 ///
 /// Its consumers in the reference are the movement/collision layer and `DoEmote` — and the
 /// polarity is the trap: it returns **1 for an ordinary player**, so a gate written on it fires
@@ -197,19 +195,19 @@ pub(crate) fn self_controlled(unit_flags: u32) -> bool {
 /// constant lives here beside its neighbour rather than being declared a fourth time: three
 /// private copies of one bit is how a mask silently drifts.
 ///
-/// **There is no player-specific combat latch to pair it with.** wow-re censused the
-/// `shr reg,0x13` + `test rl,1` idiom image-wide (7 hits, 6 on this field+bit) and found the two
-/// hardcoded *local-player* readers going through this same flag; `UnitAffectingCombat("player")`
-/// takes a GUID fast path and lands on the identical word.
+/// **There is no player-specific combat latch to pair it with.** A census of the
+/// `shr reg,0x13` + `test rl,1` idiom image-wide (7 hits, 6 on this field+bit) finds the two
+/// hardcoded *local-player* readers (`0x482f70`, `0x4d6038`) going through this same flag;
+/// `UnitAffectingCombat("player")` takes a GUID fast path and lands on the identical word.
 pub(crate) const UNIT_FLAG_IN_COMBAT: u32 = 0x0008_0000;
 
 /// `UNIT_FLAG_TAXI_FLIGHT` — the same `UNIT_FIELD_FLAGS` word, **bit 20** (vmangos
-/// `UnitDefines.h:511`; the client reads it as `shr reg,0x14; test rl,1` — wow-re counted 20
-/// independent sites of that idiom with no shared gate, `unit-flags-movement-gates.md` §4).
+/// `UnitDefines.h:511`; the client reads it as `shr reg,0x14; test rl,1` — 20 independent sites
+/// of that idiom with no shared gate).
 ///
-/// Beside its neighbour for the same reason that one is here: two readers today that have nothing
-/// to do with each other — `SetStandState`'s own guard #3 and the idle handler's auto-AFK gate —
-/// and a bit that is spelled out twice is a bit that eventually drifts.
+/// Beside its neighbour for the same reason that one is here: readers that have nothing to do with
+/// each other — `SetStandState`'s own guard #3, the idle handler's auto-AFK gate and `UnitOnTaxi`
+/// — and a bit that is spelled out more than once is a bit that eventually drifts.
 pub(crate) const UNIT_FLAG_TAXI_FLIGHT: u32 = 0x0010_0000;
 
 /// Ask for a **stand state** — the client's `SetStandState(newState)` (`0x5ed430`: send
@@ -219,8 +217,8 @@ pub(crate) const UNIT_FLAG_TAXI_FLIGHT: u32 = 0x0010_0000;
 ///
 /// Two senders today: the `X` key reads the toggle inline in [`posture`], and the **posture emotes**
 /// (`/sit`, `/sleep`, `/kneel`, `/stand`, `/lay`) send this — `DoEmote`'s `EmoteSpecProc == 1`
-/// branch calls the same `0x5ed430` the key does (wow-re `object-layer/scratch/emote-posture-
-/// gate.md` §1, decision 0881). Routing them here is what makes `/sit` sit at all: the *server*
+/// branch calls the same `0x5ed430` the key does (decision 0881).
+/// Routing them here is what makes `/sit` sit at all: the *server*
 /// does nothing for a STATE text emote (vmangos `HandleTextEmoteOpcode` breaks out of the switch
 /// for SIT/SLEEP/KNEEL), so the posture is the client's own to set.
 ///
@@ -230,6 +228,15 @@ pub(crate) struct StandStateRequest {
     pub(crate) state: u8,
 }
 
+/// The server's own stand state for OUR body (`SMSG_STANDSTATE_UPDATE` — the eat/drink sit, the
+/// stand on damage; decision 2339). Applied by [`posture`] through the same local setter the
+/// volunteered change uses, with no refusal gate and no packet back — the reference's `0x603e50`
+/// → `0x6127b0`. Written by [`net`], read in `control`.
+#[derive(bevy::ecs::message::Message, Clone, Copy, Debug)]
+pub(crate) struct ServerStandState {
+    pub(crate) state: u8,
+}
+
 /// **The body in our hands** — normally our own streamed avatar, and a possessed creature while we
 /// hold its reins (decision 1277). The controller reads its server pose to take control, then
 /// drives its transform (feet position + facing) and feeds its movement to the animation selector
@@ -301,6 +308,7 @@ pub(crate) struct PlayerPlugin;
 
 impl Plugin for PlayerPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         follow::plugin(app);
         camera_saved::plugin(app);
         camera_view::plugin(app);
@@ -379,6 +387,8 @@ impl Plugin for PlayerPlugin {
         // The posture setter's queue (the `/sit` family — decision 0881; `control` is the sole
         // executor, like the sheath queue).
         .add_message::<StandStateRequest>()
+        // The server's own stand state for our body (decision 2339), written by [`net`].
+        .add_message::<ServerStandState>()
         // Land-here ([`land`]): the ask, and the re-attach when the server's teleport lands.
         // Before `control` so the frame that applies the teleport is the frame that takes
         // third-person control back — `control` reads `detached` after this has cleared it.
diff --git a/crates/benilla-app/src/player/camera.rs b/crates/benilla-app/src/player/camera.rs
index 6995bce7..32a78a99 100644
--- a/crates/benilla-app/src/player/camera.rs
+++ b/crates/benilla-app/src/player/camera.rs
@@ -21,16 +21,15 @@ use benilla_world::model_fade::{
 };
 
 /// The reference's up-edge click predicate, in **camera degrees and milliseconds** — the whole
-/// orbit-vs-select law (decision 1122; wow-re `world-click-drag-arbitration.md`, §5 fan-out
-/// 2026-08-08). Verbatim, from `0x514ae0`, which returns 1 = suppress / 0 = dispatch:
+/// orbit-vs-select law (decision 1122). Verbatim, from `0x514ae0`, which returns
+/// 1 = suppress / 0 = dispatch:
 ///
 /// ```text
 /// isClick = elapsed < 200ms
 ///        || (elapsed < 800ms && yaw_travel < 2.25° && pitch_travel < 2.0°)
 /// ```
 ///
-/// **The `ms` on those two numbers is now VERIFIED, where 1122 could only infer it** (wow-re
-/// `ui/scratch/button-doubleclick-law.md`, 2026-08-11, a side effect of the `OnDoubleClick` §5):
+/// **The `ms` on those two numbers is now settled, where 1122 could only infer it**:
 /// the clock both constants are compared against is `0x42c010` → `0x42b790`, whose counter is the
 /// `KERNEL32!GetTickCount` import at `[0x7ff310]` and whose scale is stored as `1.0/freq × 1000.0`
 /// — milliseconds in either counter mode. Nothing here changes; the units simply stopped being a
@@ -93,8 +92,8 @@ impl PressGesture {
     }
 }
 
-/// Third-person orbit-distance limits (yards). **VERIFIED from `WoW.exe` 5875** (`FUN_005112d0` +
-/// the camera CVars, wow-re `follow-camera`): max orbit = `cameraDistanceMax × cameraDistanceMaxFactor`,
+/// Third-person orbit-distance limits (yards), from `FUN_005112d0` + the camera CVars:
+/// max orbit = `cameraDistanceMax × cameraDistanceMaxFactor`,
 /// **hard-capped at 50**; the low clamp is **0** — zoom-to-first-person (at distance 0 the eye sits at
 /// the framing pivot, inside the head, and the avatar fades to invisible — see
 /// [`benilla_world::model_fade::self_model_fade_alpha`]). The out-of-box max is **15** (`15 × 1`) —
@@ -102,8 +101,8 @@ impl PressGesture {
 /// the day it was written — a taste call ("a wider view") that nobody had weighed against the
 /// client it imitates. The slider is still there and still reaches 30; it just is not where a
 /// fresh install starts. Our starting zoom
-/// is 15 — the reference's own shipped `cameraDistance` is 5.55 (wow-re
-/// `camera-settings-persistence.md` §2), a divergence this file has always carried in its own words
+/// is 15 — the reference's own shipped `cameraDistance` is 5.55 (`0x84f488`), a divergence
+/// this file has always carried in its own words
 /// ("pulled back a bit further than vanilla's own default for a wider view") and one 1804 leaves
 /// alone: it is the camera's *initial state*, not a settings row, and it is the director's look.
 pub(super) const CAM_DIST_MIN: f32 = 0.0;
@@ -122,8 +121,8 @@ pub(super) const CAM_DIST_DEFAULT: f32 = 15.0;
 /// The max-orbit knob (decision 1140) — 1.12's `cameraDistanceMaxFactor` over the base above.
 /// A fourth frozen constant made reachable: [`CAM_DIST_MAX`] was the only zoom ceiling there was.
 ///
-/// **The default is the reference's 1.0** — `15 yd`, byte-pinned (wow-re
-/// `ui/scratch/follow-camera.md`: "cameraDistanceMax 15.0, cameraDistanceMaxFactor 1.0"). It was
+/// **The default is the reference's 1.0** — `15 yd` (`cameraDistanceMax` defaults to `"15.0"`,
+/// `0x84fbd0`, and `cameraDistanceMaxFactor` to `"1.0"`, `0x82e92c`). It was
 /// 2.0 from 1140 until 1804, which is the whole reason that record exists: the raised factor was a
 /// reasonable taste call on its day and it was never weighed as a *default*, so benilla shipped a
 /// camera that started 15 yd further out than the client it imitates. Raising the slider re-clamps
@@ -225,7 +224,7 @@ pub(crate) fn on_cvar(
 
 /// **The mouse-look rate law, and the one place benilla's units are not the reference's.**
 ///
-/// The reference's own law is byte-VERIFIED (wow-re `world-click-drag-arbitration.md` §3.3):
+/// The reference's own law (`0x50fee0`):
 ///
 /// ```text
 ///   Δyaw_deg   = cameraYawMoveSpeed   × Δx / 800
@@ -237,8 +236,8 @@ pub(crate) fn on_cvar(
 /// full screen height is horizon-to-zenith. That is what makes the two divisors and the two
 /// defaults one design rather than four constants.
 ///
-/// **What does NOT transfer is the unit.** The reference has *no DirectInput import at all*
-/// (wow-re `idle-timer-input-stamp-law.md`): it integrates `WM_MOUSEMOVE`, so its `Δ` is a
+/// **What does NOT transfer is the unit.** The reference has *no DirectInput import at all*: it
+/// integrates `WM_MOUSEMOVE` (`0x42d31c`), so its `Δ` is a
 /// **screen pixel after Windows pointer acceleration** — which is exactly why its `mousespeed`
 /// slider works by calling `SPI_SETMOUSESPEED` on the OS rather than scaling anything in-engine.
 /// benilla's `Δ` is `AccumulatedMouseMotion`, i.e. winit's `DeviceEvent::MouseMotion`: **raw,
@@ -341,8 +340,8 @@ const FOLLOW_EPS: f32 = 1.0e-3;
 /// orbit offset simply persisted, a director's call) — this is the setting that gives it back, at
 /// the reference's own default: **Smart**.
 ///
-/// **The enum is the ENGINE's, `0 = Never · 1 = Smart · 2 = Always`** — byte-verified twice over
-/// (wow-re `ui/scratch/camera-smooth-style.md` §2: the registration loop walks
+/// **The enum is the ENGINE's, `0 = Never · 1 = Smart · 2 = Always`** — twice over (the
+/// registration loop in `0x50b6f0` walks
 /// `{"Never","Smart","Always"}` filling three blocks in order, and both consumers index by
 /// `style × stride`). 1.12's own *dropdown* writes `1/2/3` instead (`UIOptionsFrameCameraDropDown`
 /// — Smart 1, Always 2, Never **3**), and 3 is not a style at all: the validator accepts it
@@ -391,8 +390,8 @@ impl FollowStyle {
         }
     }
 
-    /// The `cameraSmooth<Style><State>{Delay,Factor}` row — family A at `[0xbe0e70]`, dumped at
-    /// its defaults in wow-re `camera-smooth-style.md` §3. Factor `0` means *cancel*: the armed
+    /// The `cameraSmooth<Style><State>{Delay,Factor}` row — family A at `[0xbe0e70]`, at its
+    /// defaults. Factor `0` means *cancel*: the armed
     /// transition is dropped and the camera keeps the offset it has.
     ///
     /// Family B (`cameraSmoothViewData<Style>Yaw{Delay,Factor}`) multiplies in: its Yaw factor is
@@ -416,8 +415,8 @@ impl FollowStyle {
     }
 }
 
-/// The seven arming states of 1.12's auto-return classifier (`0x510960`, wow-re
-/// `camera-smooth-style.md` §6.2), **in the reference's own priority order — highest first**. The
+/// The seven arming states of 1.12's auto-return classifier (`0x510960`),
+/// **in the reference's own priority order — highest first**. The
 /// winner is the highest-priority bit set, and the states are read off the *camera's* input
 /// command word, not off the character's velocity: right-mouse alone is a `Turn`, a turn key
 /// under right-mouse is a `Strafe`, and both mouse buttons are a `Move`.
@@ -438,8 +437,8 @@ pub(super) enum FollowState {
     Idle,
 }
 
-/// The camera's input command word — 1.12's `[InputControl+0x4]` bit for bit (wow-re
-/// `camera-smooth-style.md` §6.1), because the state classifier and the *edge* that arms a
+/// The camera's input command word — 1.12's `[InputControl+0x4]` bit for bit,
+/// because the state classifier and the *edge* that arms a
 /// transition are both defined on it. benilla has no PitchUp/PitchDown bindings, so those two bits
 /// are simply never set.
 pub(super) mod follow_cmd {
@@ -572,8 +571,8 @@ pub(super) struct FollowRig {
 impl FollowRig {
     /// Run the auto-follow for a frame and return the camera yaw it wants, if it wants one.
     ///
-    /// The shape is the reference's, and the shape is the point (wow-re `camera-smooth-style.md`
-    /// §6/§8): a transition is **armed on an input edge**, from a snapshot taken at that instant,
+    /// The shape is the reference's, and the shape is the point (`0x510960`, `0x50f160`): a
+    /// transition is **armed on an input edge**, from a snapshot taken at that instant,
     /// and then plays out unattended — it is *not* a per-frame chase of a moving target. That is
     /// why "drag the camera aside, then press W" swings you back over one smooth arc, while
     /// holding W changes nothing at all.
@@ -674,8 +673,8 @@ impl FollowRig {
     }
 }
 
-/// Camera pitch clamp (radians) — **VERIFIED ±89.00°** (`WoW.exe` `0x8089d8`/`0x8089dc` =
-/// 1.5533430576 rad; the pitch integrate `FUN_00510120`, wow-re `follow-camera`). A single uniform
+/// Camera pitch clamp (radians) — **±89.00°** (`WoW.exe` `0x8089d8`/`0x8089dc` =
+/// 1.5533430576 rad; the pitch integrate `FUN_00510120`). A single uniform
 /// clamp at every zoom level — the reference has **no** distinct first-person look-down limit.
 pub(super) const CAM_PITCH_LIMIT: f32 = 89.0 * std::f32::consts::PI / 180.0;
 /// How fast the camera glides back out to the player's chosen zoom once an obstruction clears (1/s).
@@ -683,9 +682,9 @@ pub(super) const CAM_PITCH_LIMIT: f32 = 89.0 * std::f32::consts::PI / 180.0;
 /// push-*out* eases — the vanilla feel of the camera snapping close past an obstacle and easing back.
 const CAM_RETURN_RATE: f32 = 6.0;
 /// The camera framing pivot — the point the boom looks at + seats behind, and the first-person eye at
-/// zoom 0 — sits at `feet + H` where **H is model-derived** (not a fixed height): VERIFIED
-/// `H = (attach17.z + 0.0972) × scale` from **M2 attachment id 17** (`WoW.exe` `0x50cbc0`, wow-re
-/// `follow-camera`) — ~neck height on every character (1.90 human / 0.88 gnome), with a `0.9 × vertex-box`
+/// zoom 0 — sits at `feet + H` where **H is model-derived** (not a fixed height):
+/// `H = (attach17.z + 0.0972) × scale` from **M2 attachment id 17** (`WoW.exe` `0x50cbc0`) —
+/// ~neck height on every character (1.90 human / 0.88 gnome), with a `0.9 × vertex-box`
 /// fallback only for models lacking that attachment. Floored at [`CAM_PIVOT_FLOOR`]. The per-model
 /// pre-scale height rides on [`CameraPivot`], stamped at attach; `control` multiplies the live scale and
 /// floors. The collision sweep still starts from the *head* (not the pivot), so a jump in a low room
@@ -737,10 +736,10 @@ pub(super) fn model_pivot_height(pivot: &CameraPivot, scale: f32, swimming: bool
 /// World head height above a modeled unit's feet — [`model_pivot_height`], or the neck-height
 /// [`CAM_PIVOT_FALLBACK`] when the body has no model yet. The single definition shared by the things
 /// that sit at the character's head: the framing-pivot *target*, the far-sight subject's pivot, and
-/// the 3D-audio listener (the client's `SoundListenerAtCharacter=1` default, wow-re benilla-pins B14).
+/// the 3D-audio listener (the client's `SoundListenerAtCharacter=1` default, `0x457890`).
 ///
-/// **Which `scale` to pass is a fidelity question with a verified answer** (wow-re
-/// `pivot-height-glide.md`, C3): the reference's pivot preset multiplies the **raw**
+/// **Which `scale` to pass is a fidelity question with a verified answer**: the reference's pivot
+/// preset multiplies the **raw**
 /// `OBJECT_FIELD_SCALE_X` descriptor (vtable slot 7 = `0x469f10`, `fld [descriptors+0x10]`), *not*
 /// the 2 s-eased render scale — the two are deliberately split in the binary (`0x4833d3` folds the
 /// eased one in for a selection-ring consumer, and only there). So the camera passes
@@ -767,10 +766,9 @@ const CAM_PIVOT_SMOOTH_SPEED: f32 = 1.2;
 /// the model-derived target with a cosine smoothstep instead of taking it raw.
 ///
 /// The reference's live `cam+0xfc` chasing target `cam+0x1c8`: armed by `0x5126b0` → `0x512790`,
-/// stepped by `0x50f160`'s `[0x50f36a, 0x50f417)` block (wow-re `pivot-height-glide.md`, §5 round)
-/// — the **fourth instantiation** of the channel template [`SmoothChannel`] holds (wow-re
-/// `camera-cvar-gates.md` §8), which is why nothing of the tween lives here any more. What is left
-/// is the two things this instantiation does that its three siblings do not.
+/// stepped by `0x50f160`'s `[0x50f36a, 0x50f417)` block — the **fourth instantiation** of the
+/// channel template [`SmoothChannel`] holds, which is why nothing of the tween lives here any more.
+/// What is left is the two things this instantiation does that its three siblings do not.
 /// **This is why a druid shapeshift does not snap the reference's camera**, and it glides in *both*
 /// directions: the solver's `max(target, live)` (`0x50e5a9`) is only the collision-corridor seed, and
 /// the far chain clamps the result back down to the live value (`0x50e767`), so an unobstructed pivot
@@ -906,7 +904,7 @@ impl CameraControl {
 
     /// The self-avatar's render alpha this frame (`1.0` third-person → `0.0` first-person). The
     /// blob shadow multiplies it in for the self unit — the reference's shadow diffuse rides the
-    /// same model fade slot the body does (`[model+0x180]`, wow-re unit-blob-shadow RE).
+    /// same model fade slot the body does (`[model+0x180]`).
     pub(crate) fn self_fade(&self) -> f32 {
         self.self_fade_alpha
     }
@@ -1003,8 +1001,8 @@ pub(super) fn latch_world_mouse(
     //
     // 2159 read it the other way and excepted plates here, on an inference from the other end:
     // entering freelook disables plate mouse input (`0x60f830`, from `0x483e80`), "a toggle that
-    // would have nothing to do if a press on a plate could not reach freelook". The wow-re round
-    // this session dispatched refuted that: `0x60f830` has plenty to do for a press that starts on
+    // would have nothing to do if a press on a plate could not reach freelook". The reference
+    // refutes that: `0x60f830` has plenty to do for a press that starts on
     // the **world** and then drags the pointer across a plate mid-turn. The press itself never gets
     // there. `0x7662c0` delivers a mouse-down to exactly ONE frame — `[root+0x80]` else
     // `[root+0x7c]` — sets the capture at `0x7663e9`, calls `[vt+0x68]`, and returns 0, stopping
@@ -1058,7 +1056,7 @@ impl FlyCam {
 
 /// The per-model camera-pivot height in **model-local yards, pre-scale** — `attach17.z + 0.0972` (M2
 /// attachment id 17) for a character, else `0.9 × vertex-box Z-extent`; the reference's camera-target
-/// height (`0x50cbc0`, wow-re `follow-camera`). Stamped on every modeled unit at attach
+/// height (`0x50cbc0`). Stamped on every modeled unit at attach
 /// ([`crate::entities`]); `control` reads it off the [`Embodied`], multiplies that body's live scale,
 /// and floors at [`CAM_PIVOT_FLOOR`] to get the world pivot the third-person camera looks at (and the
 /// first-person eye). `0.0` for a bounds-less display (→ floor).
@@ -1314,8 +1312,8 @@ pub(super) fn seat_on_subject(
     };
     // The framing height is the **channel's**, not this frame's target: it eases there over
     // `|Δh| / 1.2` s with a cosine profile, so a shapeshift, a mount, a growth aura or a far-sight
-    // switch move the camera smoothly instead of teleporting it ([`PivotGlide`]; wow-re
-    // `pivot-height-glide.md`). A far-sight subject supplies the target the same way the body
+    // switch move the camera smoothly instead of teleporting it ([`PivotGlide`], `0x50f160`). A
+    // far-sight subject supplies the target the same way the body
     // does — one channel, whatever it is looking at.
     let live_pivot = rig
         .pivot
@@ -1325,8 +1323,8 @@ pub(super) fn seat_on_subject(
     // the why; this is only the wiring.
     //
     // Classified against the channel's **target** (`[cam+0x1c8]`), never its live value — the
-    // polarity three of wow-re's seven cold workers inverted, arbitrated at the bytes. Banding
-    // against a continuously-eased quantity chatters on its own, independently of the corridor.
+    // polarity is easy to invert, and byte-exact. Banding against a continuously-eased quantity
+    // chatters on its own, independently of the corridor.
     //
     // `headroom` is `1.0`: the reference scales the reach by the hit fraction of a vertical
     // head-room probe at `0x50e6bd` that this client has never had. Absent and named, not stubbed
@@ -1402,7 +1400,7 @@ pub(super) fn seat_on_subject(
         &dynamics.options,
         dt,
     );
-    // **The mouse-look hand-off** (`0x50d500` push / `0x50d520` pop; wow-re's §5 re-audit, Q-C).
+    // **The mouse-look hand-off** (`0x50d500` push / `0x50d520` pop).
     // Run after the channel has stepped, so an edge hands off the value this frame is about to
     // compose. The reference fires it from the input handler instead; the two differ by at most one
     // frame of channel motion, which at `cameraGroundSmoothSpeed` is a fortieth of a degree.
@@ -1471,9 +1469,9 @@ pub(super) fn seat_camera(
     // for the same reason — a held drag owns the camera, hand on it. It is NOT a per-frame chase:
     // an input edge arms a cosine-smoothstep return to directly-behind and that transition then
     // plays out unattended ([`FollowRig::advance`]). It writes an absolute yaw because our camera
-    // stores one; the reference stores the *offset* and re-adds the facing at render time, which
-    // is the same picture and a different mechanism (wow-re `camera-smooth-style.md` §10 — and
-    // the reason Never must not, and here does not, touch the rigid carry above).
+    // stores one; the reference stores the *offset* and re-adds the facing at render time
+    // (`0x50f7f2`), which is the same picture and a different mechanism (and the reason Never
+    // must not, and here does not, touch the rigid carry above).
     let look_held = rig.look.is_some();
     if !look_held {
         cam.yaw += turn_delta;
@@ -1503,13 +1501,13 @@ pub(super) fn seat_camera(
     // **The ground tilt IS part of the arm's pitch**, unlike the bias: `0x50f710` composes
     // `[cam+0xf4] + [cam+0x108]` and clamps the SUM to ±89° before the basis is built, and the eye
     // is then seated from that basis. So a followed terrain moves the camera; a smart pivot does
-    // not (wow-re `camera-cvar-kernels.md` §1).
+    // not.
     let arm_pitch = (cam.pitch + rig.terrain_tilt.pitch()).clamp(-CAM_PITCH_LIMIT, CAM_PITCH_LIMIT);
     let arm_rotation = Quat::from_euler(EulerRot::YXZ, cam.yaw, arm_pitch, 0.0);
     // **The composite is deliberately NOT re-clamped to ±89°.** The reference's clamp at
     // `0x50f710` binds `[cam+0xf4] + [cam+0x108]` — the pitch channel plus the ground tilt — and
-    // the bias is composed **after** it, at `0x50ee58`, so the rendered pitch is not bounded by it
-    // (wow-re `camera-cvar-kernels.md` §1). The bound that does apply to the bias is the one-sided
+    // the bias is composed **after** it, at `0x50ee58`, so the rendered pitch is not bounded by it.
+    // The bound that does apply to the bias is the one-sided
     // one on its own accumulate ([`SmartPivot::route_pitch`]), and the ±89° on the body hand-off
     // (`0x5103e0`), which is where `mover_pitch` takes it.
     let rotation = if bias == 0.0 {
@@ -1577,8 +1575,8 @@ pub(super) fn seat_camera(
         }
     }
     // No waterline handling here — deliberately. The reference NEVER moves the eye for liquid
-    // (verified negative, wow-re `water-frame-straddle` §4a: zero liquid-height queries in the
-    // camera TU); the no-straddle experience is the *submersion probe's* — the frame flips
+    // (zero liquid-height queries in the camera TU `[0x7ac640, 0x7ae010)`); the no-straddle
+    // experience is the *submersion probe's* — the frame flips
     // submerged the moment the lowest near-plane corner reaches the surface
     // (`liquid::detect_submersion`, the corner-min probe), and with the near plane at the
     // `nearclip` CVar's registered 0.1 the whole crossing band is a few inches tall (2163 — it
@@ -1991,8 +1989,7 @@ mod tests {
     /// *glides* the camera to the new body's height; ours snapped there and then drifted. The
     /// channel's whole job is that this is one smooth move, in **both** directions — the solver's
     /// `max(target, live)` is only a collision seed, and the far chain clamps back to the live
-    /// value (`0x50e767`), so nothing about a *rising* target arrives early (wow-re
-    /// `pivot-height-glide.md`, C2).
+    /// value (`0x50e767`), so nothing about a *rising* target arrives early.
     #[test]
     fn a_shapeshift_glides_the_pivot_both_ways_and_never_snaps() {
         // Tauren → cat: the heights measured off a live probe run.
@@ -2081,9 +2078,8 @@ mod tests {
 
     /// **The swim preset** — the reference's `cam+0x124`, selected by `0x50f880` on
     /// MOVEFLAG_SWIMMING and built at `0x50ccf6` as the standing height less
-    /// `StandSeq.max.z − SwimSeq.max.z`. The numbers are the shipped Human Male's, as wow-re
-    /// measured them off the binary (`water-band-discontinuity.md` §7): standing 1.9002692,
-    /// swimming 1.5120120.
+    /// `StandSeq.max.z − SwimSeq.max.z`. The numbers are the shipped Human Male's, measured off
+    /// the binary: standing 1.9002692, swimming 1.5120120.
     #[test]
     fn swimming_takes_the_lower_pivot_preset() {
         let human = CameraPivot {
@@ -2221,7 +2217,7 @@ mod tests {
 
     /// **The auto-follow** (decisions 1493/1502) — 1.12's `cameraSmoothStyle`, the setting benilla
     /// spent its whole life behaving as "Never". The properties that a re-derivation gets wrong,
-    /// and that the byte-verified mechanism (wow-re `camera-smooth-style.md`) turns on:
+    /// and that the reference's mechanism (`0x510960`, `0x50f160`) turns on:
     /// it is armed by an input **edge** and then plays out unattended (not a per-frame chase of a
     /// moving target), the profile is a **cosine** smoothstep, the duration is `|Δ| / rate ×
     /// factor` **clamped to [0.1 s, 2.0 s]**, and Smart's `Idle`/`Stop` rows are a *cancel* — which
@@ -2380,7 +2376,7 @@ mod tests {
         );
     }
 
-    /// **B364** (MarcusAga): right-clicking a row of the Who list swung the camera round to
+    /// Right-clicking a row of the Who list must not swing the camera round to
     /// behind the character — over ~180°, on a body that never turned. The click itself was the
     /// UI's (1816's no-fall-through hit test opened the dropdown); only the camera's command word
     /// saw it, because the word's two mouse bits were built from `ButtonInput` with no UI term.
@@ -2483,7 +2479,7 @@ mod tests {
         assert!(!rig.world_mouse.held(LookButton::Left));
     }
 
-    /// The state classifier's three vanilla input rules (wow-re `camera-smooth-style.md` §6.2) —
+    /// The state classifier's three vanilla input rules (`0x510960`) —
     /// the ones a client that keys off character *velocity* cannot reproduce, because they are
     /// read off the camera's own command word: right-mouse alone is a `Turn`, a turn key held
     /// **under** right-mouse is a `Strafe`, and both mouse buttons together are a `Move`. Plus the
diff --git a/crates/benilla-app/src/player/camera_channel.rs b/crates/benilla-app/src/player/camera_channel.rs
index c1805441..c59e90aa 100644
--- a/crates/benilla-app/src/player/camera_channel.rs
+++ b/crates/benilla-app/src/player/camera_channel.rs
@@ -1,7 +1,7 @@
 //! **The camera's smoothed-scalar channel** — the one template the reference instantiates four
 //! times, in one place instead of four.
 //!
-//! wow-re `ui/scratch/camera-cvar-gates.md` §8 is the finding this module exists to honour: the
+//! The finding this module exists to honour: the
 //! camera's pitch, pitch-bias and ground-tilt channels (`0x512830`/`0x512980`,
 //! `0x512a50`/`0x512ba0`, `0x512490`/`0x5125e0`) are **one compiler-emitted template** at three
 //! sets of field offsets, and `0x5126b0`/`0x512790` — the pivot **height** channel this client
diff --git a/crates/benilla-app/src/player/camera_dynamics.rs b/crates/benilla-app/src/player/camera_dynamics.rs
index 6ce7c063..c4ad7913 100644
--- a/crates/benilla-app/src/player/camera_dynamics.rs
+++ b/crates/benilla-app/src/player/camera_dynamics.rs
@@ -3,12 +3,10 @@
 //!
 //! Each is a CVar the reference registers and this client ticked at nothing: the census in
 //! `ui_script::options_tests` had all four on its unbacked list with a byte-level spec and no
-//! feature. wow-re's `ui/scratch/camera-cvar-gates.md` (the §5 nine-worker round this work
-//! dispatched, 2026-09-09) carries the gates; `camera-smooth-style.md` §9 and `camera-shake-law.md`
-//! carry the kernels they gate.
+//! feature.
 //!
 //! **The sign convention is the one thing to keep straight.** The reference's pitch is positive
-//! **downward** (`follow-camera.md` Q3: `row 0 = (cos y·cos p, sin y·cos p, −sin p)`, `eye =
+//! **downward** (`0x511f40`: `row 0 = (cos y·cos p, sin y·cos p, −sin p)`, `0x50de00`: `eye =
 //! pivot − dist·forward`, so `+89°` is the eye above the target looking down). benilla's
 //! [`super::camera::FlyCam::pitch`] is a Bevy `EulerRot::YXZ` X-rotation with `forward = rot ·
 //! −Z`, so **positive is upward** — the exact negation. Every reference predicate below is
@@ -155,7 +153,7 @@ impl Default for CameraOptions {
 pub(super) struct DynamicsInput {
     pub(super) options: CameraOptions,
     /// `cameraSmoothStyle` **raw** — the terrain-tilt matrix indexes the un-remapped value
-    /// (`camera-smooth-style.md` §2b), so this is the knob and not the auto-follow's own
+    /// (`0x50dbc0`), so this is the knob and not the auto-follow's own
     /// far-sight-adjusted copy.
     pub(super) smooth_style: super::camera::FollowStyle,
     /// `cameraSmoothTrackingStyle` — read by exactly one thing here, [`SmartPivot::advance`]'s
@@ -229,16 +227,14 @@ use crate::creature_anim::move_flags as mf;
 /// **`cameraPivot` — "smart pivot"**: the camera the collision solver has pinned against geometry
 /// tilts its *view* instead of swinging its *arm*.
 ///
-/// The whole feature is one extra pitch channel, `[cam+0x104]`, and where it is applied. wow-re
-/// `camera-cvar-gates.md` §3, VERIFIED:
+/// The whole feature is one extra pitch channel, `[cam+0x104]`, and where it is applied:
 ///
 /// - **The gate `0x510690`** is `obj != 0 ∧ typemask bit 0x8 ∧ cameraPivot ∧ ¬translating ∧
 ///   [cam+0xf4] ≤ 0`, returning the solver's own clip flags `[cam+0x90] & 0x30000` — which nothing
 ///   but `0x50e570` writes (it builds them from its two sweep hits and the driver ORs the return
 ///   in at `0x50ed6a`). So **the verdict is nonzero only in a frame the camera was actually
 ///   clipped**, which is what makes this "smart": an unobstructed camera never pivots.
-///   `[cam+0xf4] ≤ 0` is the eye at or below the target looking level-or-**up** — the direction
-///   word `pivot-height-glide.md` §1 had inverted, corrected by the same round.
+///   `[cam+0xf4] ≤ 0` is the eye at or below the target looking level-or-**up**.
 /// - **The routing `0x50fee0`.** A true verdict *plus* a mostly-vertical drag
 ///   (`|dPitch| > cameraPivotDYMin ∧ |dYaw| < cameraPivotDXMax`) — or a bias already displaced
 ///   past `0.001` with the ease not armed — accumulates the pitch delta into `+0x104` instead of
@@ -384,8 +380,7 @@ impl SmartPivot {
 /// Registered `"0"`, so this one is OFF out of the box — building it changes nothing until a player
 /// ticks the box, which is exactly why it could sit unbuilt with a full byte-level spec.
 ///
-/// Three pieces, all VERIFIED (wow-re `camera-cvar-kernels.md` §2 + `camera-smooth-style.md` §9,
-/// the two rounds this work dispatched and the one that preceded it):
+/// Three pieces:
 ///
 /// **The probe (`0x50d900`), which does not look under the character at all.** It samples the
 /// ground **ahead**: a horizontal ray `10/3` yd along the unit's facing from `feet + 5/3` up, its
@@ -416,7 +411,7 @@ impl SmartPivot {
 /// suspension.
 ///
 /// The sink is the third additive pitch: `0x50f810` folds `+0x108` into the view pitch, and unlike
-/// the pivot bias it sits INSIDE the ±89° clamp (`camera-cvar-kernels.md` §1).
+/// the pivot bias it sits INSIDE the ±89° clamp.
 pub(super) struct TerrainTilt {
     /// The ground channel `+0x108` — angular, rate `cameraGroundSmoothSpeed`.
     ground: SmoothChannel,
@@ -448,8 +443,8 @@ impl Default for TerrainTilt {
 /// **A code table, not ninety CVar rows**, following exactly what 1502 did for its sibling family
 /// `cameraSmooth<Style><State>{Delay,Factor}` ([`super::camera::FollowStyle::row`]): the reference
 /// registers these through a loop nest that a per-name row here would only obscure, and the matrix
-/// is a *law*, not a setting anybody tunes. The values are the full byte-read dump in wow-re
-/// `camera-smooth-style.md` §3C.
+/// is a *law*, not a setting anybody tunes. The values are the full byte-read dump of its
+/// default-string table `0x84f620`.
 type TiltRow = (f32, f32, f32);
 
 /// The ten movement states `0x50dbc0` classifies into, in the reference's own index order (the
@@ -457,7 +452,7 @@ type TiltRow = (f32, f32, f32);
 ///
 /// **`Jump` (3) is unreachable in the reference** and is unreachable here: `0x50dc28` and
 /// `0x50dc35` test the same bit of the same reloaded dword, so the second `je` is unconditional and
-/// the block that would emit state 3 is dead (bytes verified, `camera-smooth-style.md` §2). Its row
+/// the block that would emit state 3 is dead. Its row
 /// carries the disable sentinel at every style anyway, so nothing observable rides on it — it is
 /// kept in the enum because the *matrix* keeps it, and dropping it would silently re-index the
 /// other nine.
@@ -546,8 +541,8 @@ impl TerrainTilt {
     /// So crossing a slope change mid-drag leaves a step of exactly the difference between the
     /// lean at press and at release. That is the reference's behaviour, not a defect of this
     /// transcription: the reference eases that step through the pitch channel at
-    /// `cameraPitchSmoothSpeed`, and benilla's pitch is an immediate write (the §5 verdict on
-    /// `0x510120`), so here it lands in one frame. Named, not smoothed over.
+    /// `cameraPitchSmoothSpeed`, and benilla's pitch is an immediate write (`0x510120`), so here
+    /// it lands in one frame. Named, not smoothed over.
     pub(super) fn hand_off(&mut self, freelook: bool) -> f32 {
         if freelook == self.handed_off {
             return 0.0;
@@ -647,12 +642,11 @@ pub(super) const PROBE_DROP: f32 = 64.0 / 9.0;
 /// **`cameraBobbing` — head bob**: the eye's small figure-of-eight while you walk, in first person
 /// only.
 ///
-/// Registered `"0"`, so this ships OFF like Follow Terrain. wow-re `camera-cvar-kernels.md` §4 and
-/// `camera-cvar-gates.md` §2 (the two rounds this work dispatched), VERIFIED:
+/// Registered `"0"`, so this ships OFF like Follow Terrain.
 ///
 /// **The gate `0x5105e0` has ten conjuncts, and the first one is the surprise.** `[cam+0xec] <= 1/6`
-/// is a compare on the **zoom distance**, inclusive — so head bob is *first person only*, which
-/// nothing before that round had said. The rest: a non-null UNIT-or-PLAYER subject, not the
+/// is a compare on the **zoom distance**, inclusive — so head bob is *first person only*.
+/// The rest: a non-null UNIT-or-PLAYER subject, not the
 /// aura-76 FOV lock, `cameraBobbing`, not SWIMMING, not FALLING, `MOUNTDISPLAYID <= 0`, not on a
 /// taxi — and, as its tenth, the **return mask itself**: `0x510675 and eax,0x200`, so the whole
 /// predicate is false unless a bobbing *session* is armed. (`0x51063d`–`0x510653` is dead code — a
@@ -1205,8 +1199,8 @@ mod tests {
     }
 
     /// The ten conjuncts, one removed at a time from a case that otherwise bobs — including the
-    /// first-person one, which is the round's own finding and the easiest to get wrong (it is the
-    /// ZOOM distance, inclusive at 1/6).
+    /// first-person one, which is the easiest to get wrong (it is the ZOOM distance, inclusive at
+    /// 1/6).
     #[test]
     fn head_bob_is_first_person_only_and_every_conjunct_can_stop_it() {
         use super::super::camera::follow_cmd as c;
@@ -1530,7 +1524,7 @@ mod tests {
         assert_bounded_step((3.9, 6.0), DT, amplitude * 0.5, &mut step);
     }
 
-    /// **The mouse-look hand-off** (`0x50d500` push / `0x50d520` pop; wow-re's §5 re-audit Q-C).
+    /// **The mouse-look hand-off** (`0x50d500` push / `0x50d520` pop).
     ///
     /// The lean moves *into* the pitch for the duration of a drag and comes back out on release,
     /// so the view does not move at either edge — and a slope change crossed mid-drag leaves
diff --git a/crates/benilla-app/src/player/camera_saved.rs b/crates/benilla-app/src/player/camera_saved.rs
index c535160d..bd86687a 100644
--- a/crates/benilla-app/src/player/camera_saved.rs
+++ b/crates/benilla-app/src/player/camera_saved.rs
@@ -34,9 +34,11 @@
 //! back (1138). benilla has no UI reload, so there is no edge here to miss; when one lands it joins
 //! this list.
 //!
-//! **Read once**, when the roster names the character we are entering the world as — the macro/
-//! binding load's own seam ([`crate::ui_macro::identity`]). Absent file = the shipped defaults, which
-//! is the normal first run.
+//! **Read once per session**, when the roster names the character we are entering the world as —
+//! the macro/binding load's own seam ([`crate::ui_macro::identity`]). Absent file = the shipped
+//! defaults, which is the normal first run: the rig is re-seated at them first, so a fresh alt does
+//! not open at the zoom of whoever played last. The pitch reaches the camera through the login
+//! seize ([`super::Player::login_pitch`]), which is the one place the opening pitch is seated.
 
 use std::path::PathBuf;
 
@@ -44,7 +46,10 @@ use bevy::prelude::*;
 
 use crate::char_select::{ClientState, InWorldGated};
 
-use super::camera::{CameraControl, FlyCam, CAM_DIST_MAX, CAM_DIST_MIN, CAM_PITCH_LIMIT};
+use super::camera::{
+    CameraControl, FlyCam, CAM_DIST_DEFAULT, CAM_DIST_MAX, CAM_DIST_MIN, CAM_PITCH_LIMIT,
+};
+use super::Player;
 use benilla_world::view::WorldCamera;
 
 /// The persisted pose's file keys — the reference's own spellings, in the reference's own order.
@@ -144,6 +149,7 @@ fn load_camera_pose(
     mut file: ResMut<CameraPoseFile>,
     mut rig: ResMut<CameraControl>,
     mut cam: Query<&mut FlyCam, With<WorldCamera>>,
+    mut player: ResMut<Player>,
 ) {
     let Some(id) = crate::ui_macro::identity(&roster) else {
         return;
@@ -156,6 +162,11 @@ fn load_camera_pose(
     };
     file.path = crate::local_state::camera_character_path(&id.0, &id.1);
     file.identity = Some(id);
+    // This character's pose starts from the shipped defaults, not from the last one's.
+    rig.distance = CAM_DIST_DEFAULT;
+    rig.target_distance = CAM_DIST_DEFAULT;
+    rig.collision_distance = CAM_DIST_DEFAULT;
+    player.login_pitch = None;
 
     let Some(path) = file.path.clone() else {
         return; // hermetic capture, or no install — session-only, defaults stand
@@ -177,6 +188,7 @@ fn load_camera_pose(
     }
     if let Some(p) = pitch {
         cam.pitch = p;
+        player.login_pitch = Some(p);
     }
     info!("camera pose: restored from {}", path.display());
 }
@@ -198,13 +210,19 @@ fn save(file: &CameraPoseFile, rig: &CameraControl, pitch: f32) {
 
 /// `OnExit(InWorld)`: `/logout` back to the glue, or a disconnect.
 fn save_on_session_end(
-    file: Res<CameraPoseFile>,
+    mut file: ResMut<CameraPoseFile>,
     rig: Res<CameraControl>,
     cam: Query<&FlyCam, With<WorldCamera>>,
 ) {
     if let Ok(cam) = cam.single() {
         save(&file, &rig, cam.pitch);
     }
+    // The next login reads the file again, whoever it is — a reconnect or a relog of this same
+    // character included, whose seize would otherwise open at the shipped pitch. The path goes
+    // too: a quit from the character screen after this has no character's pose to write, and
+    // would otherwise save the glue camera's pitch over this one's.
+    file.identity = None;
+    file.path = None;
 }
 
 /// `AppExit`: quitting the client. Reads the message rather than a state edge because a quit from
@@ -245,8 +263,8 @@ mod tests {
     use super::*;
 
     /// The file we write is byte-for-byte the reference's shape: its two keys, its order, its six
-    /// decimals, LF, trailing newline — checked against a real `camera-settings.txt` from the RE
-    /// tree (`Account/ONE/VMaNGOS/One`, `16.068569` / `13.449968`).
+    /// decimals, LF, trailing newline — checked against a real `camera-settings.txt` the reference
+    /// client wrote (`16.068569` / `13.449968`).
     #[test]
     fn the_rendered_file_matches_the_references_shape() {
         let text = render(16.068_57, pitch_from_file(13.449_968));
@@ -296,3 +314,97 @@ mod tests {
         assert!((p.unwrap() - pitch_from_file(10.0)).abs() < 1e-6);
     }
 }
+
+#[cfg(test)]
+mod login_tests {
+    use bevy::ecs::system::RunSystemOnce;
+
+    use super::*;
+    use crate::char_select::Roster;
+    use crate::local_state::test_env::{EnvGuard, ENV_LOCK};
+
+    fn roster(name: &str, guid: u64) -> Roster {
+        Roster::with_pending_pick(
+            vec![benilla_protocol::Character {
+                guid,
+                name: name.into(),
+                race: 1,
+                class: 1,
+                gender: 0,
+                skin: 0,
+                face: 0,
+                hair_style: 0,
+                hair_color: 0,
+                facial_hair: 0,
+                level: 1,
+                zone: 0,
+                map: 0,
+                position: benilla_protocol::wire::Vector3d {
+                    x: 0.0,
+                    y: 0.0,
+                    z: 0.0,
+                },
+                flags: 0,
+                equipment: [benilla_protocol::CharEnumItem::default(); 19],
+                pet_display_id: 0,
+                pet_level: 0,
+                pet_family: 0,
+            }],
+            guid,
+        )
+    }
+
+    /// **The restored pitch reaches the login seize, and an alt starts from the defaults.** The
+    /// seize seated its own constant over the pitch this load had just restored, so only the
+    /// distance half of the remembered pose ever survived a login; and a character with no file
+    /// kept whatever zoom the previous one had left in the rig.
+    #[test]
+    fn the_saved_pitch_is_the_login_pitch_and_a_fresh_alt_gets_the_defaults() {
+        let _l = ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let tmp = std::env::temp_dir().join(format!("benilla-cam-{}", std::process::id()));
+        std::fs::remove_dir_all(&tmp).ok();
+        let _c = EnvGuard::unset("WOW_CAPTURE");
+        let _h = EnvGuard::set("BENILLA_HOME", tmp.to_str().unwrap());
+        let path = crate::local_state::camera_character_path("Realm", "Tank").unwrap();
+        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+        std::fs::write(&path, render(8.0, -0.3)).unwrap();
+
+        let mut app = App::new();
+        app.init_resource::<CameraPoseFile>()
+            .init_resource::<CameraControl>()
+            .init_resource::<Player>()
+            .insert_resource(roster("Tank", 7));
+        app.world_mut().spawn((
+            FlyCam {
+                yaw: 0.0,
+                pitch: 0.0,
+                speed: 1.0,
+            },
+            WorldCamera,
+        ));
+        app.world_mut().run_system_once(load_camera_pose).unwrap();
+        let restored = app.world().resource::<Player>().login_pitch;
+        assert!(
+            restored.is_some_and(|p| (p + 0.3).abs() < 1e-3),
+            "the file's pitch is what the seize will seat: {restored:?}"
+        );
+        assert_eq!(app.world().resource::<CameraControl>().target_distance, 8.0);
+
+        // The session ends; an alt with no file logs in.
+        app.world_mut()
+            .run_system_once(save_on_session_end)
+            .unwrap();
+        *app.world_mut().resource_mut::<Player>() = Player::default();
+        app.insert_resource(roster("Healer", 8));
+        app.world_mut().run_system_once(load_camera_pose).unwrap();
+        assert_eq!(app.world().resource::<Player>().login_pitch, None);
+        assert_eq!(
+            app.world().resource::<CameraControl>().target_distance,
+            CAM_DIST_DEFAULT,
+            "a fresh alt opens at the shipped zoom, not the tank's"
+        );
+        std::fs::remove_dir_all(&tmp).ok();
+    }
+}
diff --git a/crates/benilla-app/src/player/camera_water.rs b/crates/benilla-app/src/player/camera_water.rs
index 5d324c75..ad69f025 100644
--- a/crates/benilla-app/src/player/camera_water.rs
+++ b/crates/benilla-app/src/player/camera_water.rs
@@ -15,12 +15,10 @@
 //! The floor is what lifts the sweep origin clear — to `surface + 2/9` — so the boom never starts
 //! near the plane. Neither half is optional; see [`corridor`].
 //!
-//! Transcribed from wow-re `ui/scratch/camera-water-corridor-spec.md` §1–§4 and §7 (a two-round §5:
-//! seven cold workers, byte arbitration on the `(live, target)` polarity, and a rate sweep of the
-//! verified loop). Constants: `[0x8089cc] = 5/6`, `[0x8089d0] = 2/9`, `[0x8089d4] = 5/9`,
-//! `[0x808a04] = 1/9`.
+//! Transcribed from the reference. Constants: `[0x8089cc] = 5/6`, `[0x8089d0] = 2/9`,
+//! `[0x8089d4] = 5/9`, `[0x808a04] = 1/9`.
 //!
-//! **§5 · The two catch-up blocks, named and NOT built** (`camera-catchup-blocks.md`).
+//! **The two catch-up blocks, named and NOT built.**
 //!
 //! `0x50eeb0` (pivot height) and `0x50ee5d` (distance) are a matched pair that pull a live channel
 //! down when it has drifted more than `1/9` above what the solver just produced:
@@ -65,7 +63,7 @@ const SURFACE_BAND: f32 = 2.0 / 9.0;
 /// 1.036/0.293 instead of 1.0556/0.2778.
 const SUBMERGE_EDGE: f32 = 5.0 / 9.0;
 /// `[0x808a04]` — the minimum head-room the pivot keeps above the corridor floor, and the offset
-/// the catch-up blocks of §5 would pin their live field to.
+/// the catch-up blocks `0x50eeb0`/`0x50ee5d` would pin their live field to.
 const MIN_HEADROOM: f32 = 1.0 / 9.0;
 
 /// **Which liquid band the camera target is in** — the two bits `0x511ad0` writes into `[cam+0x90]`
@@ -98,9 +96,9 @@ pub(super) enum WaterBand {
 /// An invalid or null liquid object makes `0x511ad0` return `+0.0` with both bits cleared — hence
 /// `surface_y: None` mapping to [`WaterBand::Clear`] and `d = 0.0`, not to a panic or a probe.
 ///
-/// **The comparison is against the pivot TARGET, not its live value** — the asymmetry that three of
-/// seven cold workers inverted and that was arbitrated at the bytes: `[cam+0x1c8]` is the target and
-/// `[cam+0xfc]` the live value (the only directional store is `0x50f3e7 call 0x5b7bb0 →
+/// **The comparison is against the pivot TARGET, not its live value** — an asymmetry that's easy
+/// to invert, but byte-exact: `[cam+0x1c8]` is the target and `[cam+0xfc]` the live value (the
+/// only directional store is `0x50f3e7 call 0x5b7bb0 →
 /// 0x50f3ec fstp [esi+0xfc]`; `0x50f3ff`'s `[0x1c8] := [0xfc]` is a settle guarded by
 /// `|Δ| < 2⁻²²`). The classifier reads the target; the corridor seeds its cap from the live value.
 /// Getting this backwards bands against a continuously-eased quantity and chatters on its own,
@@ -292,9 +290,9 @@ mod tests {
     }
 
     /// The upper edge — `+5/18`. **This is also what this client ships**, because the reference's
-    /// two catch-up blocks are absent (module §5): with them, leaving the submerge band steps
-    /// `+1/9` at most and can go negative on a fast ascent. `+0.278` yd where the reference gives
-    /// at most `+0.111`, once, on surfacing — smaller than the dive step above it, which is
+    /// two catch-up blocks (`0x50eeb0`/`0x50ee5d`) are absent: with them, leaving the submerge band
+    /// steps `+1/9` at most and can go negative on a fast ascent. `+0.278` yd where the reference
+    /// gives at most `+0.111`, once, on surfacing — smaller than the dive step above it, which is
     /// intended and four times larger.
     #[test]
     fn leaving_the_submerge_band_with_the_live_pivot_held_is_the_closed_forms_five_eighteenths() {
diff --git a/crates/benilla-app/src/player/controller.rs b/crates/benilla-app/src/player/controller.rs
index 361dd2f8..44818cb2 100644
--- a/crates/benilla-app/src/player/controller.rs
+++ b/crates/benilla-app/src/player/controller.rs
@@ -60,7 +60,7 @@ pub(super) fn control(
         MessageWriter<crate::creature_anim::HardLanding>,
         // The cast bar's local self-cancel trigger (decision 0256 open item 2): the controller
         // reports the move edges the real client's movement machine hands `AbortCast 0x6e4940`.
-        ResMut<crate::ui_cast::LocalMoveStart>,
+        ResMut<crate::spell::LocalMoveStart>,
         // The mounted space-bar flourish (decision 0441 P2): our own MountSpecial(94) plays
         // locally at send time; the net drain self-suppresses any broadcast echo.
         MessageWriter<crate::creature_anim::MountFlourish>,
@@ -83,6 +83,9 @@ pub(super) fn control(
         // The loot window's move-start close (decision 2097): the reference's movement-START
         // guard `0x60e990`, reported here beside the cast bar's edge and consumed by `ui_loot`.
         ResMut<crate::ui_loot::LootMoveStart>,
+        // The server's own stand state for our body (decision 2339): `SMSG_STANDSTATE_UPDATE`,
+        // applied through the posture setter's local half — ungated, nothing sent back.
+        MessageReader<super::ServerStandState>,
     ),
     // Nested into one param to stay within Bevy's 16-element system-param tuple limit (see `mouse`).
     speed_capsule: (
@@ -302,7 +305,7 @@ pub(super) fn control(
     // **resolved** subject and not the raw `PLAYER_FARSIGHT` field, because `0x5ee290` sets the
     // latch only on its post-resolve ENGAGE leg; the active-player half is `foreign_mover.is_none()`,
     // and it is what keeps Mind Control working — possession sets the very same field, so without
-    // it the victim would be frozen (wow-re §6.2 and `farsight-and-client-control.md` §2.1).
+    // it the victim would be frozen.
     let mover = state::MoverInput {
         dead,
         view_is_out: state::view_is_out(
@@ -393,7 +396,7 @@ pub(super) fn control(
     // further down, `0x5151b0` (yaw) and `0x515250` (pitch), carry their own health tests as well,
     // and a closed census of all nine call sites of the facing setters `0x60de30`/`0x60de70` finds
     // every route health-gated. So the mouse and the keys do NOT share `0x514755`; they share
-    // `0x5144e0`, and `may_turn` is where that term lives on our side (wow-re §6.4).
+    // `0x5144e0`, and `may_turn` is where that term lives on our side.
     //
     // That is the line this file was missing: benilla modelled the server's root on death (0308),
     // and a root deliberately leaves turning live (0872), so a right-drag went on spinning the body
@@ -557,6 +560,8 @@ pub(super) fn control(
             if !player.server_riding {
                 movement_net::park_mover(&net.0 .0, &mut player);
             }
+            // After the park, so a fear's ack carries the stopped word the park just reported.
+            movement_net::ack_speeds_undriven(&net.0 .0, &player, &speed_acks);
             return;
         }
         // This frame's netted movement axes, the mouselook/turn modes they imply, and the autorun
@@ -672,9 +677,8 @@ pub(super) fn control(
         // the same way) — one of the movement inputs that stands a seated avatar back up.
         //
         // **A mouse turn is deliberately not in this set** (decision 1766). It was, on the strength
-        // of a director observation that a right-drag stands you, which wow-re could not reproduce
-        // statically and carried as an open anomaly for weeks. The round that closed it found the
-        // observation right and the attribution wrong: the body-facing commit is refused for a
+        // of a director observation that a right-drag stands you. The observation is right and the
+        // attribution wrong: the body-facing commit is refused for a
         // seated player by two independent gates (`0x5145e0` @`0x51460c` on the prediction cache,
         // `0x5151b0` @`0x51520a` on the raw descriptor byte), and `0x514f50` skips its stand arm
         // outright while the RMB bit is held (`0x514f6d test al,1; jne`). What stands you is the
@@ -699,6 +703,7 @@ pub(super) fn control(
             &net.0,
             &mut net.3,
             &mut net.10,
+            &mut net.15,
             moving,
             turned,
         );
@@ -753,7 +758,7 @@ pub(super) fn control(
         // what 1753 first shipped on the reading that `0x513cee`'s `test ch,0x12` was the whole
         // gate. `Jump 0x513bd0` inlines *both* `0x5144e0` and `0x514560`: a health test at
         // `0x513cbc` (`jle 0x513d43`), a second at `0x513cde`, the root mask, and stand state
-        // `!= 7` at `0x513cf3` — which is `may_translate`, term for term (wow-re §6.7).
+        // `!= 7` at `0x513cf3` — which is `may_translate`, term for term.
         let mut want_jump = binds.fired(crate::bindings::cmd::JUMP) && may_translate;
 
         // Swim vs walk: the water over our feet decides. Hysteresis-latched (`update_swimming`,
@@ -770,9 +775,9 @@ pub(super) fn control(
         // Space while swimming = the ref's Jump routing (decision 0487, superseding 0479),
         // fired on the PRESS EDGE only — one hop per press, a held key does not re-fire
         // (decision 0498, director-verified on the ref; 0487's held-chaining was our
-        // over-extension of TU-F, and near the surface its re-latch→re-fire loop bounced the
-        // avatar under the waterline — the "invisible wall"). VERIFIED TU-F/TU-G (`0x7c6230`):
-        // the routing has no depth gate and no swim re-route — at the surface the press
+        // over-extension of the swim Jump routing, and near the surface its re-latch→re-fire loop
+        // bounced the avatar under the waterline — the "invisible wall"). The routing
+        // (`0x7c6230`) has no depth gate and no swim re-route — at the surface the press
         // breaches out; submerged it's the ~1.6-yd dolphin-hop, re-latching into swim once the
         // launch velocity halves (`0x7c5de0`). The smooth way UP is aiming up in mouselook and
         // swimming forward (the 0492 pitch law). The breach exits the water mode INSIDE this
@@ -782,8 +787,8 @@ pub(super) fn control(
         // HOVER refuses the breach too: `0x7c623a`'s test sits AHEAD of the SWIMMING take-off
         // select (`0x7c6261` only picks the seed velocity, it gates nothing), and hover does not
         // suppress swim entry — `0x6030c0` tests only LEVITATING (`0x400`) — so a hovering
-        // swimmer is a real state and their Space does nothing at all (wow-re
-        // `fall-steep-response.md` §10). The land leg's refusal lives in [`mover::step`],
+        // swimmer is a real state and their Space does nothing at all. The land leg's refusal
+        // lives in [`mover::step`],
         // the same handler's grounded arm.
         // **The wire's jump** — the `Jump(force = 0)` a `SetHover(true)` owes
         // ([`Player::hover_launch`], decision 1620). It differs from Space in exactly one gate and
@@ -824,8 +829,8 @@ pub(super) fn control(
             (0.0, 0.0)
         };
 
-        // The mounted space-bar flourish (decision 0441 P2). The gate is byte-VERIFIED — the
-        // client's jump-key handler `0x60dea0` (wow-re `mount-composition.md` Q3): mounted +
+        // The mounted space-bar flourish (decision 0441 P2). The gate is the
+        // client's jump-key handler `0x60dea0`: mounted +
         // no translational move + not turning + grounded → play MountSpecial(94) locally FIRST,
         // then send `CMSG_MOUNTSPECIAL_ANIM` (the receive side self-suppresses the echo, see
         // `net/apply.rs`); translational move → a real jump, the unmounted path; **turn-only
@@ -834,7 +839,7 @@ pub(super) fn control(
         // our airborne arc stands in — an airborne press falls through and the mover ignores
         // it, the same net silence). Swim disposition is INFERRED-moot (you can't be mounted
         // while swimming in 1.12); a swimming Space is the jump-exit above — and only that
-        // (TU-F: Space is the Jump command; it is NOT a pitch or ascend input) — and never
+        // (Space is the Jump command `0x513bd0`; it is NOT a pitch or ascend input) — and never
         // reaches this walk-side gate.
         if want_jump && !moving && !swimming && player.airborne_since.is_none() {
             if let Ok((e, .., store, _, _, _, _, _)) = body.single() {
@@ -854,10 +859,9 @@ pub(super) fn control(
         // source — the pose and the stream can't disagree); the tail only serializes with the
         // SWIMMING flag, so the walking value is inert.
         // **The mover pitch, set — in every mode, not just the swim one** ([`Player::mover_pitch`]
-        // = `CMovement+0x20`). HELD when unsteered (VERIFIED TU-B(c) — an idle floater keeps its
-        // pitch, never auto-levels), and steered by mouselook as a DIRECT set of the camera aim —
-        // **VERIFIED** (the camera-pitch §5, wow-re `swim-camera-pitch.md`, decision 0492, closing
-        // 0488's INTERIM and refuting the earlier no-camera-coupling census): the ref's mouse-move
+        // = `CMovement+0x20`). HELD when unsteered (`0x7c4f80` — an idle floater keeps its
+        // pitch, never auto-levels), and steered by mouselook as a DIRECT set of the camera aim
+        // (decision 0492, closing 0488's INTERIM): the ref's mouse-move
         // chain ends in `SetPitch 0x7c6f70`, an unconditional store — no integrator, no rate limit
         // — clamped ±89° ([`MOUSELOOK_PITCH_CLAMP`], the byte constant; the ±π/2 clamp belongs to
         // the unbound pitch-KEY integrator), with the velocity basis rebuilt in-call: the aim
@@ -869,8 +873,7 @@ pub(super) fn control(
         // It lived inside the swimming branch until decision 1616 (B322). Nothing on the ref's
         // write path is swim-gated — not the mouse handler `0x514400`, not the applier `0x5103e0`,
         // not the relay `0x515330`, not the enqueuer `0x6198a0`, and not `SetPitch`'s own store at
-        // `0x7c6f91`, which precedes the `test [esi+0x40],0x200000` that splits the two arms
-        // (`swim-camera-pitch.md` §7: "the mouse-look pitch push is swim-agnostic … on land too").
+        // `0x7c6f91`, which precedes the `test [esi+0x40],0x200000` that splits the two arms.
         // Swimming gates only the *readers* — the travel basis, the body pose, the wire tail — and
         // on land the field has two more, both water walking's: the trace-mask arm's third gate
         // below, and `SetPitch`'s own dive-through complement.
@@ -903,8 +906,8 @@ pub(super) fn control(
             air_nudged,
             ground,
         } = if breach {
-            // Jump while swimming (**VERIFIED**, wow-re `swim-mechanism.md` TU-B(f)+TU-F,
-            // `0x7c6230`): clears SWIMMING and enters the FALLING lifecycle *unconditionally* —
+            // Jump while swimming (`0x7c6230`): clears SWIMMING and enters the FALLING lifecycle
+            // *unconditionally* —
             // no swim re-route, no surface-proximity gate — seeding a take-off ~14% over a land
             // jump. At the surface this is the jump-out hop (the leap clears the water and can
             // carry onto a low bank); deep, it's the ~1.6-yd dolphin-hop — swim re-latches once
@@ -1126,11 +1129,11 @@ pub(super) fn control(
             &dynamics,
         );
 
-        // The cast bar's local self-cancel trigger (`ui_cast::local_self_cancel`): a fresh
+        // The cast bar's local self-cancel trigger (`spell::local_self_cancel`): a fresh
         // *directional* start (the same wire-axis edge the stream below turns into a
         // MSG_MOVE_START_*; diffed against the pre-stream `player.move_flags`) or a jump launch.
-        // Turn-in-place and pitch deliberately absent — VERIFIED (wow-re `move-selfcancel.md`,
-        // 0445): the client's interrupt mask `0x10f0` is {fwd, back, strafe L/R, autorun};
+        // Turn-in-place and pitch deliberately absent (0445): the client's interrupt mask `0x10f0`
+        // (`0x5150ce`) is {fwd, back, strafe L/R, autorun};
         // turn/pitch flags sit outside it and never cancel.
         // `autorun_armed` is 0445's dormant fifth mask member waking up — the `0x1000` bit IS in the
         // verified `0x10f0` interrupt mask, but **only on the ON edge**: `ToggleAutoRun` computes its
@@ -1138,8 +1141,8 @@ pub(super) fn control(
         // clear edge (`0x5150c8`) *before* the mask is tested. So arming autorun kills a cast;
         // disarming it does not. It needs its own term because the flag-delta test above can't see it —
         // toggling autorun on with W already held raises no new direction bit (VERIFIED wire-silence),
-        // yet the reference still cancels. (0445's row says "YES" unqualified; wow-re RF-0079 §5
-        // corrects it to the ON edge.)
+        // yet the reference still cancels. (0445's row says "YES" unqualified; only the ON edge
+        // cancels.)
         //
         // **And it is a fact about our own character, not about whatever we are steering**
         // (decision 1281). The whole point of Mind Control is walking the victim around while the
@@ -1178,22 +1181,8 @@ pub(super) fn control(
         // jump/fall lifecycle, and a ~500 ms heartbeat, each carrying the live `MovementInfo` (decisions
         // 0052 + 0053). vmangos relays it to nearby players, who extrapolate from the flags. See the
         // [`movement_net`] module (the outbound mirror of `net::motion`'s remote integration).
-        // The rider's local pose for the wire's ON_TRANSPORT tail: `bevy_to_wow` is a pure basis
-        // rotation, so the boat-local Bevy vector converts directly, and the local orientation is
-        // `face_yaw − boat_yaw` (the GetAbsoluteFacing law in reverse), normalized like any wire
-        // orientation.
-        let wire_transport = player.ride.as_ref().map(|r| {
-            let local = benilla_assets::coords::bevy_to_wow(r.local_pos);
-            benilla_protocol::TransportPose {
-                guid: r.guid,
-                pos: benilla_protocol::wire::Vector3d {
-                    x: local[0],
-                    y: local[1],
-                    z: local[2],
-                },
-                orientation: (player.face_yaw - r.boat_yaw).rem_euclid(std::f32::consts::TAU),
-            }
-        });
+        // The rider's local pose for the wire's ON_TRANSPORT tail.
+        let wire_transport = movement_net::wire_transport(&player);
         // The skipped-time clock (decision 1935): a held frame is a frame of movement simulation
         // we advanced through without integrating, and the mover we name is the one we are
         // actually driving — a possessed unit while we hold its reins. Read out before the call
diff --git a/crates/benilla-app/src/player/drunk.rs b/crates/benilla-app/src/player/drunk.rs
index ec3ef1d4..8b0d7bc6 100644
--- a/crates/benilla-app/src/player/drunk.rs
+++ b/crates/benilla-app/src/player/drunk.rs
@@ -2,9 +2,9 @@
 //!
 //! The server streams a drunk value in `PLAYER_BYTES_3` byte 1
 //! ([`benilla_protocol::messages::ObjectFields::player_drunk_byte`]); the reference client turns
-//! it into a fraction `min(byte, 100) × 0.01` (`0x5e2a90`, wow-re PRIMITIVE
-//! `drunk_fraction_5e2a90`) and, per frame for the **active player while moving**
-//! (`flags & 0xf`, the caller band `0x60a984–0x60ab14`), staggers the walk by a wobble angle:
+//! it into a fraction `min(byte, 100) × 0.01` (`0x5e2a90`) and, per frame for the **active
+//! player while moving** (`flags & 0xf`, the caller band `0x60a984–0x60ab14`), staggers the walk
+//! by a wobble angle:
 //!
 //! - **facing** `+= pulse(now, fraction)` every frame, 2π-wrapped, committed through the normal
 //!   facing pipeline (`0x60de30`) — the sign of the pulse oscillates slowly, so the character
@@ -13,8 +13,8 @@
 //! - **swim pitch** `+= pulse × 4.0` (`_DAT_0080306c`), clamped, while the swim flag is up
 //!   (`0x200000`) — a drunk swimmer porpoises.
 //!
-//! The pulse itself (`0x60ab20`, wow-re PRIMITIVE `cosine_pulse`, diffed bit-exact against the
-//! binary) is a 3-harmonic cosine blend whose **amplitude and frequencies both scale with the
+//! The pulse itself (`0x60ab20`) is a 3-harmonic cosine blend whose **amplitude and frequencies
+//! both scale with the
 //! fraction**: `p = now_ms·(π/180)·f`, `pulse = mean(cos(p·0.093), cos(p·0.154), cos(p·0.195))
 //! · (π/240)·f`. At full drunk (fraction 1.0) that is a veer rate peaking near ±0.75°/frame with
 //! beat periods of a few seconds; tipsy values scale both the swing and how fast it meanders.
@@ -37,7 +37,7 @@ const PULSE_F2: f32 = f32::from_bits(0x3e1d_b22d); // 0.154
 /// See [`PULSE_F1`].
 const PULSE_F3: f32 = f32::from_bits(0x3e47_ae14); // 0.195
 /// `_DAT_0080c5d4` — 1/3 (bits `0x3eaaaa9f`): the pulse mean. (Not exactly 1.0/3.0 — the
-/// binary's constant is one ULP low, and the difftest is bit-exact against *it*.)
+/// binary's constant is one ULP low, and this is that exact bit pattern.)
 const PULSE_MEAN: f32 = f32::from_bits(0x3eaa_aa9f);
 /// `_DAT_0080c4bc` — π/240 (bits `0x3c567750`): the pulse amplitude-vs-fraction scale.
 const PULSE_AMP: f32 = f32::from_bits(0x3c56_7750);
@@ -52,9 +52,8 @@ pub(super) fn fraction(byte: u8) -> f32 {
 }
 
 /// The per-frame wobble angle (radians): the reference's 3-harmonic cosine pulse `0x60ab20`
-/// with `n` = the frame's time in milliseconds and `t` = the drunk fraction. Port of wow-re's
-/// bit-exact `cosine_pulse` transcription (`crates/object-layer/src/unit_fp.rs`) — see the
-/// module doc for the formula and the x87 rounding subtlety.
+/// with `n` = the frame's time in milliseconds and `t` = the drunk fraction. Port of the
+/// reference's pulse — see the module doc for the formula and the x87 rounding subtlety.
 pub(super) fn wobble(now_ms: u32, fraction: f32) -> f32 {
     if fraction == 0.0 {
         return 0.0;
@@ -72,14 +71,14 @@ pub(super) fn wobble(now_ms: u32, fraction: f32) -> f32 {
 }
 
 // The binary also holds a drunk FOV lane (camera channel `+0x10c`, setter `0x511250`, target
-// `(179° − 90°)·fraction` into the projection — wow-re `drunk-camera-fov.md`), which benilla
+// `(179° − 90°)·fraction` into the projection), which benilla
 // briefly shipped as a fisheye. The director's ref observation — the real client shows NO fov
 // change at any drunk value in normal play — held: the lane's ease rate is the CVar
 // `cameraFoVSmoothSpeed` (default 0.5°/s → a 178 s full swing whose zero-slope cosine onset
-// restarts on every drunk-byte tick, creeping <1° before each reset — §5-verified, wow-re
-// drunk-camera-fov.md §5). Effectively invisible in ordinary play, so benilla renders none
-// (decision 1018). The one visible corner — entering world already drunk SNAPs the full
-// fisheye instantly (camera-acquisition path) — is recorded there, deliberately unbuilt.
+// restarts on every drunk-byte tick, creeping <1° before each reset). Effectively invisible in
+// ordinary play, so benilla renders none (decision 1018). The one visible corner — entering
+// world already drunk SNAPs the full fisheye instantly (camera-acquisition path, `0x50d0f0`) —
+// is deliberately unbuilt.
 
 #[cfg(test)]
 mod tests {
diff --git a/crates/benilla-app/src/player/embody.rs b/crates/benilla-app/src/player/embody.rs
index 6e61ae8d..272f934d 100644
--- a/crates/benilla-app/src/player/embody.rs
+++ b/crates/benilla-app/src/player/embody.rs
@@ -6,8 +6,7 @@
 //! 0x6006e0`), which the input applier `0x514640` resolves at the top of every tick and *skips the
 //! whole tick* when it does not resolve. The three are genuinely independent stores there — the
 //! camera never consults the mover to pick its anchor, and neither of them touches "the active
-//! player" (`ds:0xb41414`), which is invariant under both far sight and possession (VERIFIED,
-//! wow-re `object-layer/scratch/farsight-and-client-control.md` §9).
+//! player" (`ds:0xb41414`), which is invariant under both far sight and possession.
 //!
 //! So benilla splits the *markers*, not the identity. [`SelfPlayer`] keeps meaning **my character**
 //! — bags, auras, quest log, paper doll, the name over the head — and never moves. [`Embodied`]
@@ -22,8 +21,8 @@
 //! - **Attached is not allowed to move** (decision 1281). A control update that forbids a body does
 //!   not detach us from it: [`Embodied`] stays and only [`ActiveMover`] comes off. That is the
 //!   reference's own shape — `0x5fa600` zeroes the mover globals and never touches the camera
-//!   anchor, so the camera goes on following your feared body, merely smoothed (wow-re
-//!   `object-layer/scratch/control-loss-and-restore.md` §2/§3). Collapsing the two cost more than
+//!   anchor, so the camera goes on following your feared body, merely smoothed (`0x50d810`).
+//!   Collapsing the two cost more than
 //!   the camera: the self-spline ride hangs off attachment, and with it the
 //!   `CMSG_MOVE_SPLINE_DONE` vmangos arms a wait for at every spline launch for a
 //!   player-or-player-possessed unit (`MoveSplineInit::Launch`), dropping **every** movement packet
diff --git a/crates/benilla-app/src/player/flags.rs b/crates/benilla-app/src/player/flags.rs
index 689901d0..5d689afa 100644
--- a/crates/benilla-app/src/player/flags.rs
+++ b/crates/benilla-app/src/player/flags.rs
@@ -82,11 +82,11 @@ pub(super) fn this_frame(
     let landed;
     if let Some((swim_fwd, swim_side)) = swim {
         // Swimming: `MOVEFLAG_SWIMMING` (the swim-pitch tail rides with it) plus the travel-direction
-        // bits the swim gait selector cascades on (TU-E: turn→41, strafe→43/44, back→45, fwd→42,
-        // idle→41). The bits mirror the NET swim amounts that actually drive the mover — one
-        // source, so a rooted or key-cancelled swimmer can't stream a phantom direction
+        // bits the swim gait selector cascades on (`0x5fd100`: turn→41, strafe→43/44, back→45,
+        // fwd→42, idle→41). The bits mirror the NET swim amounts that actually drive the mover —
+        // one source, so a rooted or key-cancelled swimmer can't stream a phantom direction
         // (decision 0056). Space sets nothing here — its whole swim role is the jump-exit,
-        // which runs the breach arm (TU-F). No FALLING, no airborne bookkeeping: the
+        // which runs the breach arm (`0x7c6230`). No FALLING, no airborne bookkeeping: the
         // arc state is cleared so leaving the water starts a clean walk/fall from rest.
         move_flags_now |= move_flags::SWIMMING;
         if swim_fwd < 0.0 {
@@ -204,7 +204,7 @@ pub(super) fn this_frame(
 
     // The animation/body-pose view of the flags: airborne it keeps the TAKEOFF-FROZEN direction
     // bits — the reference's anim layer plays the step-off gait off the takeoff-frozen
-    // flags/speed until FALLINGFAR latches or the unit lands (wow-re `land-anim-height-gate.md`),
+    // flags/speed until FALLINGFAR latches (`0x602c40`) or the unit lands,
     // and a mid-air Q press must not twist the body or animate a strafe. The *wire* flags above
     // stay live (the sniff-verified send law); only the pose reads the freeze.
     let pose_flags = if airborne {
diff --git a/crates/benilla-app/src/player/follow.rs b/crates/benilla-app/src/player/follow.rs
index 6c77a07b..d6eacb42 100644
--- a/crates/benilla-app/src/player/follow.rs
+++ b/crates/benilla-app/src/player/follow.rs
@@ -31,8 +31,8 @@
 //! *release* never does, and neither does the follow's own synthesized input.
 //!
 //! The mechanism sits two layers below the keybinding stubs, which is why reading the handlers
-//! answers "nothing cancels follow" and is wrong about the behaviour — the same failure mode
-//! wow-re's RF-0079 hit on autorun. Every movement START emitter calls **`0x60e990`**, which
+//! answers "nothing cancels follow" and is wrong about the behaviour. Every movement START
+//! emitter calls **`0x60e990`**, which
 //! cancels at `0x60e9b5` unless the re-entrancy bracket `ds:0xc4da48` **bit 0** is set — and
 //! follow's own four emitters (`0x60e790`, `0x60e7f0`, `0x60e8a0`, `0x60e940`) set that bracket
 //! around their calls. A real key press never sets it. **That asymmetry is the entire mechanism.**
@@ -298,8 +298,8 @@ impl FollowInput<'_, '_> {
     /// follow and fires `AUTOFOLLOW_END` ([`super::state::MoverInput::torn_down`])? Not an input, but the
     /// member of the cancel set that is a *state*, and the one benilla had wrong in both directions.
     ///
-    /// `rf86-autofollow-cancel-set.md` §5 named the mechanism as the health test at `0x5144f8`, and
-    /// this file passed the **root** instead. wow-re's §6.3 sharpens it: `0x5146d6 call 0x60fb60`
+    /// The mechanism runs through the health test at `0x5144f8`, and this file passed the **root**
+    /// instead. More exactly, `0x5146d6 call 0x60fb60`
     /// is reached only when *both* predicates are down (`0x5146c3` and `0x5146ce` both not taken),
     /// so a pure ROOT — which benilla cancelled on — does **not** end a follow in the reference, and
     /// death — which benilla did not cancel on, so a follow taken into death kept steering the
@@ -359,8 +359,8 @@ pub(super) fn steer_follow(
         input.rig.look == Some(LookButton::Right),
         // The input tick on its teardown leg, or the body handed to a server spline. The ride term
         // is benilla's own and predates this: it is not one of `0x5144e0`'s conjuncts (conjunct 4 is
-        // the Knockdown lockout, not a taxi test — wow-re §6.2), and nothing in this round bears on
-        // it either way, so it is left exactly as it stood.
+        // the Knockdown lockout, not a taxi test), and nothing known bears on it either way, so it
+        // is left exactly as it stood.
         input.input_torn_down(player.modes.rooted, player.foreign_mover.is_none())
             || player.server_riding(),
     ) {
diff --git a/crates/benilla-app/src/player/gait.rs b/crates/benilla-app/src/player/gait.rs
index dd47d62f..704da400 100644
--- a/crates/benilla-app/src/player/gait.rs
+++ b/crates/benilla-app/src/player/gait.rs
@@ -1,5 +1,5 @@
 //! The rendered **body heading** + the animation's view of the flags — the client's display-facing
-//! pose (wow-re `body-facing-pipeline.md` §3, the `0x607ed0` tail; supersedes 0051's
+//! pose (the `0x607ed0` tail; supersedes 0051's
 //! ease-toward-velocity), beside its concern like `mover`/`swim`/`arc`. [`super::control`] calls
 //! [`drive_body_heading`] once per controlled frame, after this frame's move flags are final.
 
@@ -17,7 +17,7 @@ use super::{Player, STATIONARY_CHASE_RATE};
 ///    body back so the head keeps looking at the aim.
 ///  · **moving fwd/back or airborne** — snap to the aim (the client's `flags & 0x2003` snap;
 ///    a backpedal keeps facing forward and plays WalkBackwards).
-///  · **standing** — the FROZEN chase (byte rule, wow-re `b947e5aa`): while the aim is being
+///  · **standing** — the FROZEN chase (`0x6081bf`): while the aim is being
 ///    steered (A/D turn keys or mouse-look) the catch-up is off and only the 90° ceiling
 ///    applies — the camera/aim and the head-twist lead while the body holds, then the body
 ///    follows the turn lagging exactly 90°; once the steering stops it sweeps back onto the
@@ -25,7 +25,7 @@ use super::{Player, STATIONARY_CHASE_RATE};
 ///    rate — the client stamps its chase clock every non-steering frame.
 ///  · **swimming** ignores the ground display-facing pose (no strafe body-offset, no standing
 ///    chase): the body SNAPs to the aim (the client's facing snap list — dead or swimming) and
-///    the swim *pitch* tilts it in `control`'s transform write (TU-A's render law).
+///    the swim *pitch* tilts it in `control`'s transform write (the render law `0x60a110`).
 ///
 /// The turn-in-place foot-shuffle rides the BODY's actual rotation (the client's chase-step bits
 /// `0x800/0x1000`, cleared each frame after the anim layer reads them) — NOT the turn keys: while
diff --git a/crates/benilla-app/src/player/input.rs b/crates/benilla-app/src/player/input.rs
index 0d3f4bb1..12afb6ba 100644
--- a/crates/benilla-app/src/player/input.rs
+++ b/crates/benilla-app/src/player/input.rs
@@ -171,7 +171,7 @@ pub(super) fn move_axes(
     }
     // ── The cancel set ── autorun is NOT simply "held forward" — the thing that makes it its own
     // mode is what *destroys* it. Six writers clear the bit in the reference; these are the ones
-    // with a benilla analog (VERIFIED, wow-re `rf79-autorun-cancel-set.md`):
+    // with a benilla analog:
     //
     // - **A W or S key-DOWN** — unconditional, and the subtle one: the directional handlers look
     //   pure (each pushes only its own bit), but they tail into the shared SET helper `0x514840`,
@@ -189,10 +189,10 @@ pub(super) fn move_axes(
     //   the term passed here was the root alone, so dying with autorun latched kept the bit. It is
     //   [`state::may_translate`] now — the gate itself.
     //
-    //   **This list used to say "a taxi/charge hand-off", on rf79 §4's parked reading that
-    //   `0x60f5b0` is an on-taxi predicate. It is not** — wow-re §6.2 reads it as
-    //   `AnimationData.dbc` column 3 bit `0x80`, set on exactly one of 208 shipped rows, id 121
-    //   `Knockdown`. The ride term below is benilla's own and is kept on its own merits.
+    //   **This list used to say "a taxi/charge hand-off", on a reading of `0x60f5b0` as an
+    //   on-taxi predicate. It is not** — it reads `AnimationData.dbc` column 3 bit `0x80`, set
+    //   on exactly one of 208 shipped rows, id 121 `Knockdown`. The ride term below is benilla's
+    //   own and is kept on its own merits.
     //
     // Deliberately absent, each VERIFIED as a *survivor*: a jump, a chat EditBox taking focus, and
     // a zone change. Mounting is genuinely unsettled in the reference and left alone here.
@@ -232,7 +232,7 @@ pub(super) fn move_axes(
         both_buttons,
         autorun,
     );
-    // Vanilla turn/strafe control model (decision 0050, VERIFIED wow-5875-re `0x7c5360`): W/S move
+    // Vanilla turn/strafe control model (decision 0050, `0x7c5360`): W/S move
     // forward/back in the facing; **A/D turn the character** (rotate the facing at the turn rate) so
     // the body faces where it runs — UNLESS right-mouse is held (mouse-look), where A/D strafe and
     // the facing tracks the camera; **Q/E always strafe**. Movement basis is the *character* facing,
diff --git a/crates/benilla-app/src/player/move_trace.rs b/crates/benilla-app/src/player/move_trace.rs
index 7077bf3d..8749ea1a 100644
--- a/crates/benilla-app/src/player/move_trace.rs
+++ b/crates/benilla-app/src/player/move_trace.rs
@@ -24,7 +24,7 @@
 //!   `SET_WALK_MODE`/`SET_RUN_MODE` that went out), but a **refused** press is silent by design —
 //!   indistinguishable from a key that isn't bound, or from a binding whose dispatch never fired.
 //!   The chain also has an open byte (`0x1200`'s second bit, decision 1752 §6), so a live run is
-//!   how the §5's answer gets checked against a real refusal instead of re-reasoned.
+//!   how any answer about it gets checked against a real refusal instead of re-reasoned.
 //! - **`knb`** — one line per **knockback** ([`knockback`]): the launch quad the server aimed and
 //!   whether the mover flew it. The one mover edge with no observable of its own — its ack is not a
 //!   `MSG_MOVE_*` so `snd` misses it, its refusal is silent by design, and a wrong ack's whole
@@ -51,7 +51,7 @@ pub(super) struct Frame {
     /// Horizontal distance covered this frame (yd). Paired with the vertical it gives the frame's
     /// **descent slope**, which is the whole question behind "we dive over the edge instead of
     /// stepping down it": the reference bounds a step-down to the foot cone's own
-    /// [`super::STEP_SLOPE_RATIO`] per unit of horizontal travel (wow-re `step-off-recourse.md`), so
+    /// [`super::STEP_SLOPE_RATIO`] per unit of horizontal travel (`0x636dda`), so
     /// a walk-off that reads far steeper — or worse, flat-then-plummet across two frames — is the
     /// mover leaving the surface instead of following it down.
     pub dx: f32,
diff --git a/crates/benilla-app/src/player/movement_net.rs b/crates/benilla-app/src/player/movement_net.rs
index 93756e30..c0ec0fc1 100644
--- a/crates/benilla-app/src/player/movement_net.rs
+++ b/crates/benilla-app/src/player/movement_net.rs
@@ -35,10 +35,10 @@ use crate::net::{ClientCommand, MoveKind};
 
 use super::Player;
 
-/// How often (s) we send a `MSG_MOVE_HEARTBEAT` while moving. **VERIFIED** against wow-5875-re
-/// (collision node, "the move-send cadence"): the local-player send-deadline `mgr+0x130` is armed to
-/// `clientTime + 500 ms` (`0x615b80`) — the wire report is the per-transition broadcast plus this
-/// ~500 ms-paced heartbeat, independent of the 250 ms physics substeps.
+/// How often (s) we send a `MSG_MOVE_HEARTBEAT` while moving: the local-player send-deadline
+/// `mgr+0x130` is armed to `clientTime + 500 ms` (`0x615b80`) — the wire report is the
+/// per-transition broadcast plus this ~500 ms-paced heartbeat, independent of the 250 ms physics
+/// substeps.
 const HEARTBEAT_INTERVAL: f32 = 0.5;
 /// The move-flag bits we put on the wire — the base directional / turn / walk set **plus `FALLING`**
 /// (= `MOVEFLAG_JUMPING` 0x2000): we serialize the jump tail (`zspeed, cos, sin, xyspeed`) whenever it's
@@ -129,7 +129,7 @@ pub(super) struct ArcEdges {
 /// Stream this frame's movement to the server the way the real client does: a `MSG_MOVE_*` per movement-
 /// *axis* transition (start/stop forward-back, strafe, turn), a JUMP on take-off, a SET_FACING every
 /// frame the facing changes off the turn axis, and a HEARTBEAT every ~500 ms while moving — each
-/// carrying the current `MovementInfo`. **VERIFIED** against wow-5875-re (collision "move-send cadence"):
+/// carrying the current `MovementInfo`:
 /// the move-state-change broadcaster `0x61a820` selects the wire opcode *from the flag delta*
 /// (`0x619f00`), and the flag report is exactly "per-transition broadcast + ~500 ms heartbeat" — with
 /// the *facing* report its own independent emitter alongside it (decision 0617: in the 1.12.1 sniff
@@ -301,7 +301,7 @@ pub(super) fn stream_self_movement(
     // not a carve-out: the wire mirrors actual motion (0056). The reference's airborne silence is a
     // real flags-side mechanism — while FALLING, `StartMove 0x7c6ae0` defers a new press into an inert
     // latch (`0x20000`/`0x40000`) instead of flipping the direction bit, "**unless nothing is
-    // currently moving**" (wow-re `hvel-fall-arc.md` Q3, VERIFIED bytes) — and the broadcaster
+    // currently moving**" — and the broadcaster
     // `0x61a820` picks its opcode from the *flag delta*, so a deferred press produces no delta and
     // no packet. In the one non-deferred case the bit really flips, so the transition really
     // broadcasts. That case is exactly our nudge (`mover::step`: airborne, nothing moving, a
@@ -317,7 +317,7 @@ pub(super) fn stream_self_movement(
     //
     // **A fall that had no jump opens with NOTHING** — decision 1464, and the third of 0053's
     // inventions to be retired by the bytes. We used to push an immediate heartbeat here "so
-    // observers start the arc promptly"; wow-re's §5 refuted it three ways: the move-state
+    // observers start the arc promptly"; the reference refutes it three ways: the move-state
     // broadcaster `0x61a820` gates every send on the *locomotion nibble* (`61a99d test al,0xf`)
     // and FALLING/`0x2000` lives in `ah`, so a flags change that is only the fall bit never
     // broadcasts at all; every non-jump `StartFalling 0x7c61f0` site seeds `+0xa0 = 0.0f` while
@@ -347,10 +347,9 @@ pub(super) fn stream_self_movement(
         send_move!(MoveKind::FallLand);
     }
     // Swim transition: the real client announces entering/leaving the water with a dedicated
-    // MSG_MOVE_START_SWIM (0xca) / STOP_SWIM (0xcb) the frame the `SWIMMING` bit flips (VERIFIED, wow-re
-    // swim-transition — the local `0x6030c0` decision enqueues it), rather than letting the flag ride
-    // the next heartbeat. Airborne and swimming are mutually exclusive, so this never races the arc
-    // lifecycle above.
+    // MSG_MOVE_START_SWIM (0xca) / STOP_SWIM (0xcb) the frame the `SWIMMING` bit flips (the local
+    // `0x6030c0` decision enqueues it), rather than letting the flag ride the next heartbeat.
+    // Airborne and swimming are mutually exclusive, so this never races the arc lifecycle above.
     if added & move_flags::SWIMMING != 0 {
         send_move!(MoveKind::StartSwim);
     } else if removed & move_flags::SWIMMING != 0 {
@@ -406,7 +405,7 @@ pub(super) fn stream_self_movement(
     // SET_FACING — more than every other movement opcode combined — streamed at *frame* cadence (median
     // 41 ms between them, p25 23 ms, minimum 17 ms) and, decisively, **while moving**: 116 of the 179
     // carry a direction bit (`Forward` ×68, `StrafeRight` ×12, `Forward+StrafeRight` ×9, `Backward` ×12,
-    // `Forward+Falling` ×4, …). There is no rate limit and no angular epsilon — wow-re's `0x617100`
+    // `Forward+Falling` ×4, …). There is no rate limit and no angular epsilon — `0x617100`
     // (SetFacing-then-send) reports whenever `0x617170`'s **exact-equality** change detector says the
     // facing differs at all, so a frame that didn't move the mouse sends nothing and a frame that did
     // sends one packet. (Our own `face_yaw` is likewise only written by real input, so the exact
@@ -437,7 +436,7 @@ pub(super) fn stream_self_movement(
     //
     // **And it runs while FALLING too** (decision 1464). This arm used to carry `&& !falling`,
     // defended as "the real client sends a normal-length jump with no mid-air packet at all
-    // (sniff-verified)" — which wow-re's §5 refuted on both halves against the same 1.12.1 capture.
+    // (sniff-verified)" — which the same 1.12.1 capture refutes on both halves.
     // `MSG_MOVE_JUMP` is the **44-byte** form (the jump quad is present, `vz = -7.955547`, matching
     // the `.text` constant `0xc0fe93d8` bit for bit), and mid-air packets are routine: heartbeats
     // and a mid-air SET_FACING, all 44 B. The "untraced trigger" behind the sniff's sparse mid-air
@@ -496,8 +495,7 @@ pub(super) fn stream_self_movement(
 /// (decision 1935). Accumulate while the mover holds; report the total once, on the release edge.
 ///
 /// **The law is "time the movement simulation advanced through without integrating"** — not "a
-/// long frame", which is what this packet is usually described as. wow-re's carve
-/// (`collision/scratch/move-time-skipped-law.md`, §5-verified, landed 2026-09-03) found **four**
+/// long frame", which is what this packet is usually described as. The reference has **four**
 /// emission sites feeding one builder `0x600be0`, and the long-frame one (`0x616642 cmp esi,0xfa`
 /// → send `dt − 250`) is only one of them and not the common one. The two that dominate real
 /// traffic are the **no-geometry** pair: the resolve entry's swept query returning nothing
@@ -525,9 +523,9 @@ pub(super) fn stream_self_movement(
 /// The other two sites are deliberately unbuilt. The long-frame one has no meaning here: benilla
 /// has no 250 ms substep clamp — it integrates the whole frame — so a long frame is time we
 /// *spent*, not time we skipped, and reporting it would be a lie about our own simulation. The
-/// `[CMovement+0x40] & 0x8000000` free-advance bit's own setter is not modelled at all. wow-re's
-/// own verdict on the build order says as much: a client implementing cases 1–3 matches every
-/// packet in the shipped captures.
+/// `[CMovement+0x40] & 0x8000000` free-advance bit's own setter is not modelled at all, and need
+/// not be: a client implementing the other three sites matches every packet in the shipped
+/// captures.
 fn stream_skipped_time(sender: &Sender<ClientCommand>, player: &mut Player, skip: SkipClock) {
     if skip.held {
         player.skipped_ms += skip.dt * 1000.0;
@@ -580,6 +578,64 @@ pub(super) fn park_mover(sender: &Sender<ClientCommand>, player: &mut Player) {
     player.last_facing = facing;
 }
 
+/// The rider's boat-local pose for the wire's `ON_TRANSPORT` tail, or `None` off a deck.
+/// `bevy_to_wow` is a pure basis rotation, so the boat-local Bevy vector converts directly, and the
+/// local orientation is `face_yaw − boat_yaw` (the GetAbsoluteFacing law in reverse), normalized
+/// like any wire orientation.
+pub(super) fn wire_transport(player: &Player) -> Option<TransportPose> {
+    player.ride.as_ref().map(|r| {
+        let local = bevy_to_wow(r.local_pos);
+        TransportPose {
+            guid: r.guid,
+            pos: benilla_protocol::wire::Vector3d {
+                x: local[0],
+                y: local[1],
+                z: local[2],
+            },
+            orientation: (player.face_yaw - r.boat_yaw).rem_euclid(std::f32::consts::TAU),
+        }
+    })
+}
+
+/// **The forced-speed acks owed on a frame the controller does not drive** — a server spline
+/// (`server_riding`), a fear (`control_lost`) or a mover hand-off (`reseat`). Those frames return
+/// before [`stream_self_movement`], which is where a controlled frame's acks go out, so until this
+/// the change was applied locally and never answered: vmangos holds an unacked change for
+/// `PendingAckResponseTime` (4 s) before enforcing it, counts it in `OnFailedToAckChange` (a kick
+/// under the default anticheat penalty) and blocks the graveyard repop while one is pending. The
+/// reference acks from its per-mover drain whoever is driving (`0x616142`/`0x61812d`).
+///
+/// The payload is the honest state we last reported: our streamed flags (a ride's deliberate
+/// FORWARD included) with the transport tail when we are on a deck, minus the airborne pair — no
+/// arc is being integrated on these frames, so there is no jump tail to send with them.
+pub(super) fn ack_speeds_undriven(
+    sender: &Sender<ClientCommand>,
+    player: &Player,
+    acks: &[crate::net::SpeedChangeMessage],
+) {
+    let transport = wire_transport(player);
+    let mut flags =
+        player.move_flags & OUTBOUND_FLAG_MASK & !(move_flags::FALLING | move_flags::FALLING_FAR);
+    if transport.is_none() {
+        flags &= !move_flags::ON_TRANSPORT; // flag and tail travel together
+    }
+    for ack in acks {
+        let _ = sender.send(ClientCommand::ForceSpeedAck {
+            kind: ack.kind,
+            guid: ack.guid,
+            counter: ack.counter,
+            speed: ack.speed,
+            flags,
+            pos: bevy_to_wow(player.pos),
+            orientation: player.face_yaw.rem_euclid(std::f32::consts::TAU),
+            pitch: 0.0,
+            fall_time: 0,
+            jump: None,
+            transport: transport.filter(|_| flags & move_flags::ON_TRANSPORT != 0),
+        });
+    }
+}
+
 #[cfg(test)]
 mod tests {
     /// A frame that integrated everything it was given — the skipped-time report's no-op input,
@@ -937,8 +993,8 @@ mod tests {
     }
 
     /// **A fall that had no jump opens with nothing, and then heartbeats on the ordinary deadline**
-    /// — decision 1464, replacing two 0053-era inventions with the law wow-re's §5 read off the
-    /// broadcaster and reproduced in the 1.12.1 capture: `echo → heartbeats every 500 ms while the
+    /// — decision 1464, replacing two 0053-era inventions with the law read off the broadcaster
+    /// `0x61a820` and reproduced in the 1.12.1 capture: `echo → heartbeats every 500 ms while the
     /// fall lasts → FALL_LAND`, the parenthesis empty for any fall shorter than the deadline.
     ///
     /// The opener is the load-bearing half. It is the only packet that could put `MOVEFLAG_JUMPING`
@@ -1440,6 +1496,73 @@ mod tests {
         assert_eq!(player.move_flags, 0, "bookkeeping is zeroed after parking");
     }
 
+    /// **A forced speed change is acked on a frame nobody is driving** — a fear, a server spline,
+    /// a mover hand-off. Those frames return before the stream, which is where a controlled
+    /// frame's acks go out, so the change was applied and never answered (vmangos enforces it 4 s
+    /// late, counts the miss toward its anticheat kick, and blocks the graveyard repop meanwhile).
+    /// The payload is the honest reported word: the ride's FORWARD kept, the airborne pair dropped
+    /// (no arc tail exists here), and `ON_TRANSPORT` only with the tail that must travel with it.
+    #[test]
+    fn a_speed_change_is_acked_while_not_driving() {
+        let (tx, rx) = crossbeam_channel::unbounded();
+        let ack = crate::net::SpeedChangeMessage {
+            guid: 7,
+            kind: benilla_protocol::SpeedKind::Run,
+            counter: 3,
+            speed: 3.5,
+        };
+
+        // A spline ride reporting FORWARD, off any deck, with a stale ON_TRANSPORT bit.
+        let player = Player {
+            move_flags: move_flags::FORWARD | move_flags::FALLING | move_flags::ON_TRANSPORT,
+            face_yaw: -1.0,
+            ..Default::default()
+        };
+        ack_speeds_undriven(&tx, &player, &[ack]);
+        let Ok(ClientCommand::ForceSpeedAck {
+            counter,
+            speed,
+            flags,
+            orientation,
+            transport,
+            jump,
+            ..
+        }) = rx.try_recv()
+        else {
+            panic!("the change is acked");
+        };
+        assert_eq!((counter, speed), (3, 3.5), "the ack echoes the change");
+        assert_eq!(
+            flags,
+            move_flags::FORWARD,
+            "FORWARD kept; FALLING and a tailless ON_TRANSPORT dropped"
+        );
+        assert!(transport.is_none() && jump.is_none());
+        assert!((0.0..TAU).contains(&orientation));
+        assert!(rx.try_recv().is_err(), "one ack per change");
+
+        // On a deck: the transport bit rides with its tail.
+        let player = Player {
+            move_flags: move_flags::ON_TRANSPORT,
+            ride: Some(super::super::state::PlayerRide {
+                entity: bevy::ecs::entity::Entity::PLACEHOLDER,
+                guid: 0x1F,
+                local_pos: bevy::math::Vec3::ZERO,
+                boat_yaw: 0.0,
+            }),
+            ..Default::default()
+        };
+        ack_speeds_undriven(&tx, &player, &[ack]);
+        let Ok(ClientCommand::ForceSpeedAck {
+            flags, transport, ..
+        }) = rx.try_recv()
+        else {
+            panic!("the change is acked");
+        };
+        assert_eq!(flags, move_flags::ON_TRANSPORT);
+        assert_eq!(transport.map(|t| t.guid), Some(0x1F));
+    }
+
     /// **A knockback launch acks, and sends no `MSG_MOVE_JUMP`** (decision 1702).
     ///
     /// Two laws in one frame, and they are the same law read from both ends. `MSG_MOVE_JUMP` has a
diff --git a/crates/benilla-app/src/player/mover.rs b/crates/benilla-app/src/player/mover.rs
index b8ba8078..5788a3ed 100644
--- a/crates/benilla-app/src/player/mover.rs
+++ b/crates/benilla-app/src/player/mover.rs
@@ -50,14 +50,13 @@ use super::{
 /// - **`water_walking`** — `0x631610 test eax,0x10000000`, the granted bit. Setting it ORs the two
 ///   ADT liquid layers into the walk trace's *class mask* (`0x63162e or edi,0x30000`), which is the
 ///   whole of what the flag does: the surface becomes ordinary swept geometry and the resolver
-///   stands on it at its raw Z. `0x6367b0` contains **zero** references to the bit
-///   (wow-re `moveflag-family.md` §2.1/§2.2).
+///   stands on it at its raw Z. `0x6367b0` contains **zero** references to the bit.
 /// - **`!swimming`** — `0x631617 test eax,0x200000; jne`. Granting *this* bit to a submerged caster
 ///   does **not** eject them, and that is the reference's behaviour too, not a gap of ours
 ///   (decision 1616): the swim path traces the same two liquid layers into a *different* container
 ///   with the plane **negated** (`0x6320fe fchs`) — a bound above, not a floor below — so the two
 ///   are mutually exclusive by construction and the same triangles can never enter the solver twice
-///   with opposite orientation (§2.4). A swimmer surfaces onto the water on the way *out*, when the
+///   with opposite orientation. A swimmer surfaces onto the water on the way *out*, when the
 ///   depth compare `0x6030c0` drops SWIMMING in water shallower than `0.75·h − 1/36`.
 ///
 ///   **Do not read that as "casting Levitate while swimming does nothing" — 1616 did, and it was
@@ -93,7 +92,7 @@ pub(super) struct Outcome {
     /// This frame's take-off was a **server-aimed knockback**, not a jump (decision 1702). Implies
     /// [`Self::jumped`] — the arc bookkeeping cannot tell them apart and must not — but the wire can:
     /// `MSG_MOVE_JUMP` has exactly one emission site in the reference image, the move-command drain's
-    /// jump arm (wow-re, decision 1464), so a knockback's launch announces itself with
+    /// jump arm (`0x615ed1`, decision 1464), so a knockback's launch announces itself with
     /// `CMSG_MOVE_KNOCK_BACK_ACK` and nothing else. Sending a JUMP for it would also be an
     /// instant `CHEAT_TYPE_OVERSPEED_JUMP` — the one jump check vmangos does *not* exempt during a
     /// knockback (`MovementAnticheat.cpp:650`), and a knockback's horizontal speed is well over run
@@ -161,7 +160,7 @@ pub(super) fn step(
     // **Water walking: the liquid surface is GROUND, and the classify above has to see it**
     // (decision 1611, correcting 0866). In the reference the surface is not a special case at all
     // — `MOVEFLAG_WATERWALKING` ORs the two ADT liquid layers into the walk trace's *class mask*
-    // (`0x63162e or edi, 0x30000`, wow-re `moveflag-family.md` §2.2), so the same swept query that
+    // (`0x63162e or edi, 0x30000`), so the same swept query that
     // finds terrain finds the water, and the walk resolver stands on it at its raw Z with no
     // water-specific code anywhere (`0x6367b0` contains zero references to the bit).
     //
@@ -221,8 +220,7 @@ pub(super) fn step(
     // and why the drop resumes only on release: `ClearRoot 0x7c7370` calls `0x7c61c0` StartFalling,
     // and `0x7c61c0` is precisely the entry that refuses while rooted
     // (`0x7c61d6 test dword ptr [ecx+0x40], 0x203800` — SWIMMING|FALLING|ROOT|FIXED_Z), so no fall
-    // can begin under a root by any path. (wow-re `moveflag-family.md` §1/§5.3,
-    // `step-vs-fall-election.md`.)
+    // can begin under a root by any path.
     let anchored = !held && player.modes.rooted;
     // A body part-way up a foot cone is standing (decision 1123). The probe above looks straight
     // down and finds only the steep riser it is riding, so on its own it would call a mid-ride frame
@@ -288,9 +286,8 @@ pub(super) fn step(
     } else if grounded {
         player.vel_y = 0.0;
         // **HOVER refuses the jump** — the FIRST test in `CMovement::Jump 0x7c6230`
-        // (`0x7c623a test [ecx+0x40], 0x40000000`; wow-re `fall-steep-response.md` §10). The
-        // keyboard jump IS the forced jump (`moveflag-family.md` §4.2, CORRECTED 2026-08-08:
-        // the queued command's replay pushes force=1 at `0x615eba`; the sole force=0 caller is
+        // (`0x7c623a test [ecx+0x40], 0x40000000`). The keyboard jump IS the forced jump (the
+        // queued command's replay pushes force=1 at `0x615eba`; the sole force=0 caller is
         // the wire's SetHover(0) path, which exists so a server move can jump a hovering unit).
         // The refusal is SILENT, byte-for-byte: the caller drops it at `0x615ec5` — no
         // MSG_MOVE_JUMP (its only emission site sits behind this very test), no toast, no retry
@@ -364,7 +361,7 @@ pub(super) fn step(
         // direction *really* moves us, so it re-seeds the frozen airborne direction flags.
         //
         // **The guard is a velocity proxy for a flag test, and the reference's is the flag**
-        // (decision 1736, wow-re `airborne-steerability.md`). `0x7c5a20`/`0x7c5c20` do not bail on
+        // (decision 1736). `0x7c5a20`/`0x7c5c20` do not bail on
         // FALLING — they bail on `FALLING && arg == 0`, and the two openers that pass `arg = 1`
         // sit behind `0x7c6afc test al,0xf`: the door opens exactly while the **direction nibble
         // `+0x40 & 0xf` is clear**. That is why a moving jump is locked, and it is a different
@@ -756,7 +753,7 @@ pub(crate) fn grounded_step(
             );
         }
     }
-    // **Which regime** (decisions 1123/1126, wow-re `climb-vs-slide.md` §2/§4/§6). The certification
+    // **Which regime** (decisions 1123/1126; `0x631be0`, `0x635c00`). The certification
     // above settles *whether* the obstacle can be cleared; the height of the **blocking edge** — the
     // face the look-ahead is pressed against, measured from the feet — settles *how*. The real
     // client's solid is a cone below [`FOOT_CONE_HEIGHT`] and a vertical box above it, so a low edge
@@ -792,7 +789,7 @@ pub(crate) fn grounded_step(
     // of travel in one frame, at ten times walking speed. That lurch, not the height, is what the
     // director reported as Goldshire's tables feeling teleporty.
     //
-    // The reference does none of it (wow-re `ret2-commit-law.md`, a §5 trio):
+    // The reference does none of it:
     //   - `max(H·tan50°, r+1/720)` = 1.1917536 is **only ever a sweep distance**. `ebx` @`0x636193`
     //     has exactly two uses, both the length argument to `0x632ba0`. It is never added to `pos`.
     //   - the resolver holds `L / t_remaining` invariant across hits, deflections and misses, so the
@@ -847,20 +844,20 @@ pub(crate) fn grounded_step(
     );
     let mut slid = out.position;
     // Snap onto the surface so we follow downhill slopes + steps down — the client's step-vs-fall
-    // election (`0x6367b0`, wow-re `step-vs-fall-election.md`): the probe reaches
+    // election (`0x6367b0`): the probe reaches
     // [`STEP_SLOPE_RATIO`]·travel + [`STEP_SNAP_SLACK`], and snaps only onto a *walkable* floor
     // (≤50°, the election's own `cos50°` = [`GROUND_COS`]).
     //
     // **The reach is the cone's own slope, and nothing else, on an ordinary walking frame**
     // (decision 1129). It used to carry a flat `+`[`CAPSULE_HEIGHT`] — 2.028 yd of unconditional
     // extra depth — on the reading that `0x617430` returned a collision height. Both halves of that
-    // were wrong (decision 1125, wow-re `mover-collision-scalars.md` + `step-off-recourse.md`):
-    // `0x617430` is `[unit+0xb8]`, the dimensionless scale ratio `max(SCALE_X / CreatureModelScale,
-    // 1)`, so `H` is **1.0** for a player and not 2.028; and the reference adds it only while
-    // `0x4000000` is set — "the current support is a certified STEEP contact, not a walkable
-    // floor", which is [`Support::steep`]. So the deep reach belongs to the step-down *recourse*,
-    // where a body already following a steep face down needs to see the walkable ground waiting at
-    // its foot; the ordinary walking frame reaches exactly as far as the foot cone could rest.
+    // were wrong (decision 1125): `0x617430` is `[unit+0xb8]`, the dimensionless scale ratio
+    // `max(SCALE_X / CreatureModelScale, 1)`, so `H` is **1.0** for a player and not 2.028; and the
+    // reference adds it only while `0x4000000` is set (`0x636dfc`) — "the current support is a
+    // certified STEEP contact, not a walkable floor", which is [`Support::steep`]. So the deep
+    // reach belongs to the step-down *recourse*, where a body already following a steep face down
+    // needs to see the walkable ground waiting at its foot; the ordinary walking frame reaches
+    // exactly as far as the foot cone could rest.
     //
     // What that costs is real and intended: a drop deeper than the cone is NOT absorbed. No snap,
     // the next frame's ground probe misses, and the gap becomes a fall (the client's
@@ -929,8 +926,8 @@ pub(crate) fn grounded_step(
     // **The step-down follows the surface; it does not leave it** (decision 1127). The reference's
     // finalize writes `pos.z -= min(clearance, d_h·1.8493990)` *before* it classifies anything, and a
     // steep landing is answered by the multipass rather than by a fall — a `ret 2` continues,
-    // grounded, with the "my support is a certified steep contact" bit set (wow-re
-    // `step-off-recourse.md`; the bit's meaning is decision 1125's).
+    // grounded, with the "my support is a certified steep contact" bit set (`0x636f21`; the
+    // bit's meaning is decision 1125's).
     //
     // We refused every hit under 50° outright, so walking off a kerb the probe found only the ~61°
     // riser, declined it, and the body kept its full height while its forward speed carried it out
@@ -940,7 +937,7 @@ pub(crate) fn grounded_step(
     //
     // **The reach is how far we can SEE; the descent is how far we may GO — and for a capsule those
     // are not the same number** (decision 1132). Byte-exact the finalize is one line
-    // (`0x636e45`–`0x636e52`, wow-re `step-off-recourse.md` §1): sweep down by `L`, write
+    // (`0x636e45`–`0x636e52`): sweep down by `L`, write
     // `pos.z -= achieved`, *then* classify. `achieved` is the sweep's own output, so on the reference
     // the descent is bounded only by `L` — no second, smaller cap exists anywhere on that path.
     //
@@ -1041,7 +1038,7 @@ pub(crate) fn grounded_step(
 /// `mean · dt` is the closed form `v₀·dt − ½g·dt²`, not an approximation of it. That matters
 /// because the reference does not integrate at all: it evaluates a closed form anchored at the
 /// launch every substep (`+0x7c − D(+0x78)` via `0x7c5e70`), so its arc is frame-rate independent
-/// and cannot drift (decision 1740, wow-re `airborne-steerability.md`). Stepping at either
+/// and cannot drift (decision 1740). Stepping at either
 /// endpoint's velocity instead of the mean loses `½·g·dt²` per frame — and both of ours did, in
 /// opposite directions:
 ///
@@ -1117,7 +1114,7 @@ fn is_steep_face(ny: f32) -> bool {
 /// The even-speed ramp ride: a walkable slope never slows or deflects the grounded walk. The
 /// real client's walk step is two-dimensional — the resolver takes speed·dt as a *horizontal*
 /// distance and a normalized 2D direction, and Z follows purely through the snap/step machinery
-/// (`0x6367b0`'s own signature, wow-re `step-vs-fall-election.md`) — so on every walkable
+/// (`0x6367b0`'s own signature) — so on every walkable
 /// (< 50°) surface the horizontal speed is exactly the run speed. Collide-and-slide's
 /// true-plane clip breaks that invariant: `v' = v − (v·n)n` shortens the horizontal part to
 /// `h·cos²θ` (half speed at 45°) and bends a diagonal approach off the input line. When the
@@ -1141,13 +1138,12 @@ fn walkable_ride_velocity(n: Vec3, v: Vec3) -> Option<Vec3> {
 ///
 /// The real client's movement solid is a **cone below the waist**: the k-DOP build at `0x631440`
 /// emits four bevels running from a point at the foot out to the full radius at
-/// `foot + radius·1.8493990`, and only above that height is it a vertical box (wow-re
-/// `climb-vs-slide.md` §2 — the `n.z < 0` sign on those planes is the tell that the cone narrows
-/// *downward*, so it is a foot cone and not a top-rim chamfer). A low edge therefore never presents
-/// the mover a wall to be lifted over: it presents the slanted skirt, and the resolver's own slide
-/// runs the body up it.
+/// `foot + radius·1.8493990`, and only above that height is it a vertical box (the `n.z < 0` sign
+/// on those planes is the tell that the cone narrows *downward*, so it is a foot cone and not a
+/// top-rim chamfer). A low edge therefore never presents the mover a wall to be lifted over: it
+/// presents the slanted skirt, and the resolver's own slide runs the body up it.
 ///
-/// The gain is the note's `T` at §4 — `1.8494 · cosθ · len`, where `θ` is how squarely the approach
+/// The gain is `0x635c00`'s `T` — `1.8494 · cosθ · len`, where `θ` is how squarely the approach
 /// meets the face — and that is exactly this projection: the closing horizontal speed (the dot
 /// product supplies `cosθ`) times [`STEP_SLOPE_RATIO`], the cone's own surface slope. Horizontal
 /// speed is untouched, as it is on every walkable ride ([`walkable_ride_velocity`]); the grounded
@@ -1173,8 +1169,7 @@ fn foot_cone_ride(n: Vec3, v: Vec3) -> Option<Vec3> {
 
 /// The steep-contact response: **the descent is never touched, and the push-out is horizontal.**
 ///
-/// VERIFIED against the reference (wow-re `system/collision/scratch/fall-steep-response.md`, the
-/// dispatch this decided): `0x635090` writes **exactly two floats** — an x/y push-out along the
+/// The reference's `0x635090` writes **exactly two floats** — an x/y push-out along the
 /// horizontal projection of the contact normal — and `0x635600` adds them to `Δx`/`Δy` only, while
 /// `Δz = dir.z · remaining` passes through **with no addend at all**. The normal's vertical is
 /// annihilated in the response's own denominator (`0x635166 fmul [0x7ffd74]`, and that constant is
@@ -1729,8 +1724,8 @@ mod tests {
     fn a_step_up_never_outruns_the_frame_it_happens_in() {
         // **The pin on decision 1130.** The reference holds `L / t_remaining` invariant across every
         // hit, deflection and miss in the walk resolver, so a frame's total horizontal displacement
-        // is bounded by its own substep budget — `dx = 1.19` where a walking frame is 0.117 "cannot
-        // arise from this path" (wow-re `ret2-commit-law.md`, claim 2). 0209 committed the probe's
+        // is bounded by its own substep budget — `dx = 1.19` where a walking frame is 0.117 cannot
+        // arise from this path (`0x6367b0`). 0209 committed the probe's
         // full advance as motion, which put exactly that lurch in every single step-up.
         //
         // **A Goldshire table, profiled from the director's own capture** — the shape they reported
@@ -1974,7 +1969,7 @@ mod tests {
 
     #[test]
     fn the_cone_ride_gains_the_reference_slope() {
-        // wow-re `climb-vs-slide.md` §4: `T = 1.8494 · cosθ · len`. Head-on, the gain is the cone's
+        // The reference's `T = 1.8494 · cosθ · len` (`0x635c00`). Head-on, the gain is the cone's
         // own surface slope times the speed…
         let head_on = foot_cone_ride(Vec3::new(-1.0, 0.0, 0.0), Vec3::X * 7.0).unwrap();
         assert!(
@@ -2489,11 +2484,10 @@ mod tests {
     #[test]
     fn a_hovering_mover_refuses_the_jump_and_leaves_no_trace() {
         // `0x7c623a` — HOVER is the FIRST test in `CMovement::Jump 0x7c6230`, and the keyboard
-        // jump is the forced jump it applies to (wow-re `fall-steep-response.md` §10;
-        // `moveflag-family.md` §4.2 CORRECTED 2026-08-08 — every player-side call site pushes
-        // force=1). Refused means NOTHING happens: no take-off velocity, `jumped` false (the
-        // wire's MSG_MOVE_JUMP rides that bit), no latch. The same press with hover off is the
-        // control that proves this fixture can jump at all.
+        // jump is the forced jump it applies to (every player-side call site pushes force=1, the
+        // keyboard's at `0x615eba`). Refused means NOTHING happens: no take-off velocity, `jumped`
+        // false (the wire's MSG_MOVE_JUMP rides that bit), no latch. The same press with hover off
+        // is the control that proves this fixture can jump at all.
         let flat: [(f32, f32); 2] = [(-3.0, 0.0), (3.0, 0.0)];
         let rows = world_from_profile(&flat)
             .world_mut()
@@ -2673,7 +2667,7 @@ mod tests {
     }
 
     /// **A knockback is unsteerable because its launch plants a direction bit — not because it is
-    /// fast** (decision 1740, wow-re `airborne-steerability.md`).
+    /// fast** (decision 1740).
     ///
     /// This is the case the old gate got wrong, and it is the reason the gate changed. Air control
     /// opens on the reference exactly while the direction nibble `[CMovement+0x40] & 0xf` is clear
diff --git a/crates/benilla-app/src/player/net.rs b/crates/benilla-app/src/player/net.rs
new file mode 100644
index 00000000..605c0351
--- /dev/null
+++ b/crates/benilla-app/src/player/net.rs
@@ -0,0 +1,21 @@
+//! The player's packet handlers (the net handler table, decision 2327) — today one: the server's
+//! own stand state for our body (`SMSG_STANDSTATE_UPDATE`, decision 2339), handed to
+//! [`super::posture`] as a [`ServerStandState`] message because the apply wants the frame's body
+//! query and sheath queue, which live in `control`.
+
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::ServerStandState;
+use crate::net::NetHandlerApp;
+
+/// Register the handler — called from [`super::PlayerPlugin`].
+pub(super) fn register(app: &mut App) {
+    app.net_handler(SessionEventKind::StandStateUpdate, on_stand_state_update);
+}
+
+fn on_stand_state_update(In(ev): In<SessionEvent>, mut out: MessageWriter<ServerStandState>) {
+    if let SessionEvent::StandStateUpdate { state } = ev {
+        out.write(ServerStandState { state });
+    }
+}
diff --git a/crates/benilla-app/src/player/posture.rs b/crates/benilla-app/src/player/posture.rs
index d874f478..faf33272 100644
--- a/crates/benilla-app/src/player/posture.rs
+++ b/crates/benilla-app/src/player/posture.rs
@@ -24,15 +24,17 @@ pub(super) fn update(
     net: &NetCommands,
     sheath: &mut MessageWriter<crate::creature_anim::SheathRequest>,
     asks: &mut MessageReader<StandStateRequest>,
+    server: &mut MessageReader<super::ServerStandState>,
     moving: bool,
     turned: bool,
 ) -> u8 {
     // Stand state (decision 0080c) — a real field, not a local bool: X volunteers
     // `CMSG_STANDSTATECHANGE` (sit 1 ↔ stand 0) and movement input stands us up; the
     // server's echo into `UNIT_FIELD_BYTES_1` drives the pose — ours *and* every
-    // observer's. `stand_pending` is the local commit (the client's `SetStandState`
-    // applies immediately and sends, one setter — `0x6127b0`), overlaid on the echoed
-    // byte until it lands so the pose never waits on the round-trip.
+    // observer's. `stand_pending` is the local commit — the client's `SetStandState 0x5ed430`
+    // sends, then applies through the setter's local half `0x6127b0` ([`apply_locally`]), the
+    // same half the server's own `SMSG_STANDSTATE_UPDATE` reaches (2339) — overlaid on the
+    // echoed byte until it lands so the pose never waits on the round-trip.
     let (stand_byte, reads_dead) = body
         .single()
         .ok()
@@ -40,7 +42,7 @@ pub(super) fn update(
             // `SetStandState`'s own first two guards, read together with the byte they gate:
             // health ≤ 0, **or** `UNIT_DYNAMIC_FLAGS & 0x20` — a feigner, whose health never moved.
             // Deliberately NOT `unit_reads_dead`, which folds in stand state 7 as a third term the
-            // setter does not test (wow-re `local-move-input-gate.md` §6.7; decision 1753).
+            // setter does not test (`0x5ed4a9`–`0x5ed4bd`; decision 1753).
             store.map(|s| {
                 (
                     s.0.unit_stand_state(),
@@ -52,6 +54,15 @@ pub(super) fn update(
     if player.stand_pending == Some(stand_byte) {
         player.stand_pending = None; // the echo landed
     }
+    // The server's own stand state first (decision 2339): `SMSG_STANDSTATE_UPDATE` reaches the
+    // setter's local half directly — no refusal gate, no `CMSG_STANDSTATECHANGE` back — so the
+    // volunteered logic below sees the state the server just put us in. The last packet wins,
+    // as it does in the reference's handler order.
+    if let Some(s) = server.read().last().map(|m| m.state) {
+        let stand_now = player.stand_pending.unwrap_or(stand_byte);
+        move_trace::posture("server", s, stand_now, player.move_flags());
+        apply_locally(player, s, stand_now, body, sheath);
+    }
     let stand_state = player.stand_pending.unwrap_or(stand_byte);
     // The queued asks first (the `/sit` family — decision 0881), then the X key, which is the
     // reference's own precedence: a queued `SetStandState` ran during the frame's message pass,
@@ -63,13 +74,13 @@ pub(super) fn update(
     }
     // Any movement input stands the avatar back up (the client volunteers the stand — the
     // server never auto-stands a moving player; verified vmangos MovementHandler). The input
-    // set is byte-pinned (wow-re `standstate-movement-trigger.md`, §5 2026-07-14): the net
+    // set is byte-pinned: the net
     // input axes (translation), keyboard turn, and jump all reach the guarded stand wrapper
     // `0x60be30(0)`; a left-drag camera orbit provably does not; sit(1)/chair(2)/sleep(3)
     // all stand identically (the value-agnostic `GetStandState() != 0` gate).
     //
-    // **The MOUSE turn is not in this set, and that corner is now closed** (decision 1766; the
-    // note's B3, which stood open for weeks). A deliberate right-drag turn cannot stand a seated
+    // **The MOUSE turn is not in this set, and that corner is now closed** (decision 1766).
+    // A deliberate right-drag turn cannot stand a seated
     // player — two independent gates refuse the body-facing commit for a seated body, and
     // `0x514f50` skips its stand arm outright while the RMB bit is held. The director's
     // observation was right and this file's attribution was wrong: what stands you is the
@@ -112,24 +123,12 @@ pub(super) fn update(
     }
     if let Some(s) = request_stand.filter(|&s| s != stand_state) {
         move_trace::posture("commit", s, stand_state, player.move_flags());
-        player.stand_pending = Some(s);
+        // The reference's order: `0x5ed430` sends at `0x5ed501`, then calls the local half at
+        // `0x5ed53f` — the packet is the volunteer path's, never the setter's (2339).
         let _ = net.0.send(ClientCommand::StandStateChange {
             state: u32::from(s),
         });
-        // The sit-stow rider (the client's SetStandState → SetSheatheState(0, SNAP) —
-        // wow-re `sheath-policy.md` §4): entering any stand-state ∉ {0 STAND, 2 SIT_CHAIR}
-        // force-stows drawn weapons, through the anim layer's one setter.
-        if s != 0 && s != 2 {
-            if let Ok((e, _, _, _, drv, _, _, _, _, _, _)) = body.single() {
-                if drv.and_then(|d| d.sheath_state()).unwrap_or(0) != 0 {
-                    sheath.write(crate::creature_anim::SheathRequest {
-                        entity: e,
-                        state: 0,
-                        ceremony: false,
-                    });
-                }
-            }
-        }
+        apply_locally(player, s, stand_state, body, sheath);
     }
     let stand_now = player.stand_pending.unwrap_or(stand_byte);
     // Sheath toggle (Z) — vanilla's draw/stow, through the anim layer's ONE setter
@@ -137,9 +136,8 @@ pub(super) fn update(
     // client-side state (the setter cache — attacking auto-draws and the anim reconcile
     // force-stows, which a local bool or the raw echo byte would drift from), commit + send
     // `CMSG_SETSHEATHED` there, and play the ceremony — the manual toggle is the ONLY path
-    // in the whole client that plays it (`bInstant = 0` at the 4 ToggleSheath sites — wow-re
-    // `sheath-policy.md`). No body model yet (no driver) drops the toggle, the client's own
-    // refusal.
+    // in the whole client that plays it (`bInstant = 0` at the 4 ToggleSheath `0x5eb480` sites).
+    // No body model yet (no driver) drops the toggle, the client's own refusal.
     if binds.fired(crate::bindings::cmd::TOGGLE_SHEATH) {
         if let Ok((e, _, _, _, Some(drv), store, engaged, _, _, wielded, _)) = body.single() {
             // The manual toggle's guard chain (decision 0080d) — the guards of the client's
@@ -147,7 +145,7 @@ pub(super) fn update(
             // today: dead · engaged in combat · not standing (`GetStandState() != 0` —
             // chairs block the toggle too, unlike the *stow rider's* {0, 2} exemption) ·
             // mid-ceremony (the 89/90 clip still playing) · MOUNTED (chain check 4,
-            // `UNIT_FIELD_MOUNTDISPLAYID > 0` — wow-re `sheath-policy.md` §2, wired with
+            // `UNIT_FIELD_MOUNTDISPLAYID > 0`, wired with
             // 0441's mounts). Stunned / channeling join when those states exist. A refused
             // press is simply dropped — no message, like the client.
             let dead = store.is_some_and(|s| s.0.unit_is_dead());
@@ -187,3 +185,69 @@ pub(super) fn update(
 
     stand_now
 }
+
+/// The stand-state setter's **local half** — the reference's `0x6127b0`, reached by the
+/// volunteered change (`0x5ed430`, after it has sent `CMSG_STANDSTATECHANGE`) and by the server's
+/// own `SMSG_STANDSTATE_UPDATE` (`0x603e50`) alike; it sends no `CMSG_STANDSTATECHANGE` itself —
+/// its four callers image-wide hold none of the five send sites (decision 2339).
+///
+/// On a CHANGE it writes the predicted state (`[player+0x1d68]`, our `stand_pending`), which the
+/// pose reads until the `UNIT_FIELD_BYTES_1` echo lands ([`predict`]). Whether or not the state
+/// changed, a drawn weapon meeting a state outside {0 STAND, 2 SIT_CHAIR} is stowed through the
+/// anim layer's one setter — `0x6127cc`'s gate is the sheath state, not the same-state compare.
+///
+/// What the reference's local half also does on a change, and this does not yet: release an open
+/// loot window and stop a running attack when sitting down (`0x5f0790` → `0x48f200`, `0x5ecac0`),
+/// re-run the movement input when standing up, and on EVERY call re-acquire the follow camera
+/// behind the body's facing (`0x48ec90`, the stand-state-keyed pivot presets). 2339 names them.
+fn apply_locally(
+    player: &mut Player,
+    s: u8,
+    stand_now: u8,
+    body: &BodyQuery,
+    sheath: &mut MessageWriter<crate::creature_anim::SheathRequest>,
+) {
+    predict(&mut player.stand_pending, s, stand_now);
+    if s != 0 && s != 2 {
+        if let Ok((e, _, _, _, drv, _, _, _, _, _, _)) = body.single() {
+            if drv.and_then(|d| d.sheath_state()).unwrap_or(0) != 0 {
+                sheath.write(crate::creature_anim::SheathRequest {
+                    entity: e,
+                    state: 0,
+                    ceremony: false,
+                });
+            }
+        }
+    }
+}
+
+/// `0x5f0790`'s first line: the predicted stand state is written only when it changes
+/// (`0x5f0799 cmp [esi+0x1d68], eax; je ret`). Returns whether it did.
+fn predict(pending: &mut Option<u8>, s: u8, stand_now: u8) -> bool {
+    if s == stand_now {
+        return false;
+    }
+    *pending = Some(s);
+    true
+}
+
+#[cfg(test)]
+mod setter_tests {
+    use super::predict;
+
+    #[test]
+    fn the_local_half_writes_the_prediction_only_on_a_change() {
+        // Seated by the server (a drink) while the echo still says standing: predicted.
+        let mut pending = None;
+        assert!(predict(&mut pending, 1, 0));
+        assert_eq!(pending, Some(1));
+        // vmangos's same-state re-send (its camera re-acquire): nothing written.
+        let mut pending = None;
+        assert!(!predict(&mut pending, 0, 0));
+        assert_eq!(pending, None);
+        // A stand from the server while we predicted a sit: the newer state wins.
+        let mut pending = Some(1);
+        assert!(predict(&mut pending, 0, 1));
+        assert_eq!(pending, Some(0));
+    }
+}
diff --git a/crates/benilla-app/src/player/scoped_view.rs b/crates/benilla-app/src/player/scoped_view.rs
index 575c8cfd..4ef170b1 100644
--- a/crates/benilla-app/src/player/scoped_view.rs
+++ b/crates/benilla-app/src/player/scoped_view.rs
@@ -7,8 +7,7 @@
 //! **client-local camera override** and never touches that field — which is why the server appears
 //! to do nothing for the spyglass, and why chasing it on the wire finds no packet to handle.
 //!
-//! **VERIFIED against the 5875 binary** (wow-re `object-layer/scratch/farsight-and-client-control.md`,
-//! §5 cross-checked): the aura watcher `0x604d00` routes to `0x5ff350` (add) / `0x612320` (remove);
+//! The reference's aura watcher `0x604d00` routes to `0x5ff350` (add) / `0x612320` (remove);
 //! both, **for the local player only** (`0x5fa6d0`), walk the spell's three effects comparing
 //! `EffectApplyAuraName[i]` (`SpellRec+0x16c`) against `0x4c` = 76 and call
 //! `0x50d320(camera, EffectMiscValue[i])`. That function forces **first person**, sets a camera flag
diff --git a/crates/benilla-app/src/player/server_ride.rs b/crates/benilla-app/src/player/server_ride.rs
index 84f07798..c197e54c 100644
--- a/crates/benilla-app/src/player/server_ride.rs
+++ b/crates/benilla-app/src/player/server_ride.rs
@@ -47,10 +47,9 @@ fn ride_ground(world: &benilla_world::collision::WorldCollision, pos: Vec3) -> O
 ///
 /// The reference's integrate loop makes no distinction between the body it steers and any other
 /// mover here: `0x616de0`'s path-select produces a displacement from *either* the physics path or
-/// the spline path and hands **both** to `0x616cb0` (wow-re `collision/scratch/spec-driver-B.md`
-/// K5/K3), which zeroes the vertical component and lets `0x634040`'s swept resolve read Z off the
-/// surface. Keeping the chord instead is what B357 fixed for a Playerbot; this is the same wire Z,
-/// on the one body that had it left.
+/// the spline path and hands **both** to `0x616cb0`, which zeroes the vertical component and lets
+/// `0x634040`'s swept resolve read Z off the surface. Keeping the chord instead is what B357 fixed
+/// for a Playerbot; this is the same wire Z, on the one body that had it left.
 ///
 /// **The keeps are the reference's own fork**, `0x616cec`-`0x616d03`:
 /// - a **flying spline** (`MI.flags & 0x200`) — the taxi owns its altitude, and its sampled Z is
@@ -171,7 +170,7 @@ pub(super) fn drive_self_ride(
                     spline.duration.as_millis(),
                 );
                 // **A spline re-authors the walk gait, and its RUNMODE bit is inverted** (decision
-                // 1758, wow-re `walk-mode-law.md` §5.2). The reference's `SMSG_MONSTER_MOVE` commit
+                // 1758). The reference's `SMSG_MONSTER_MOVE` commit
                 // `0x7c6a50` does this unconditionally for every incoming spline: `0x7c6ac2 and
                 // edi,0x100` takes the path's own `SPLINEFLAG_RUNMODE` and `0x7c6acb` hands it to
                 // `CMovement::SetRunMode 0x7c71c0`, whose argument is *run* — so a path the server
diff --git a/crates/benilla-app/src/player/state.rs b/crates/benilla-app/src/player/state.rs
index 685377ce..26547cc2 100644
--- a/crates/benilla-app/src/player/state.rs
+++ b/crates/benilla-app/src/player/state.rs
@@ -9,10 +9,10 @@ use bevy::prelude::*;
 
 /// Backpedal speed as a fraction of run: vanilla `MOVE_RUN_BACK` 4.5 / `MOVE_RUN` 7.0. Moving backward
 /// (the `0x2` backward move-flag) selects the backward speed over run, **dominating strafe** —
-/// binary-VERIFIED 1v1 (`backward-speed-{a,b}.md`; the speed getter `FUN_007c4c90` tests only bit `0x2`
-/// on the forward/back axis, never the forward/strafe bits) — and the backward arm is a
-/// **`min(runBack, run)`**, not a plain select (`0x7c4d1d`, the swim-feel §5's TU-H; identical in
-/// template to the swim pair's `min(swimBack, swim)`). runBack is server-seeded (the ctor zeroes it;
+/// the speed getter `FUN_007c4c90` tests only bit `0x2` on the forward/back axis, never the
+/// forward/strafe bits — and the backward arm is a **`min(runBack, run)`**, not a plain select
+/// (`0x7c4d1d`; identical in template to the swim pair's `min(swimBack, swim)`). runBack is
+/// server-seeded (the ctor zeroes it;
 /// standard vanilla 4.5), so we keep it as a ratio of the configured run speed → a `$WOW_MOVE_SPEED`
 /// override / Ctrl sprint scales backpedal too. A backward *jump* inherits this automatically: takeoff
 /// freezes the current horizontal speed (`FUN_007c61f0` never rewrites it), so a backward jump lands
@@ -35,7 +35,7 @@ pub(super) const WALK_RATIO: f32 = 2.5 / 7.0;
 /// `CMSG_FORCE_TURN_RATE_CHANGE_ACK`, `0x2df`) and read for held turns by `GetYawRate 0x7c5c50`.
 /// The base ctor `0x7c4850` *zeroes* all six, so the client keeps no default of its own — π is the
 /// vanilla server's value, and this constant stands in only for frames before a create block lands.
-/// VERIFIED wow-5875-re (`0x7c4f30` heading integrate; the speed block, decision 1278).
+/// (`0x7c4f30` heading integrate; the speed block, decision 1278).
 ///
 /// Because it lives on the mover, a possessed creature turns at **its** rate, not ours. Reduced to
 /// [`TURN_RATE_MOVING`] while translating **or falling** (`flags & 0x200f`), and the same cell is
@@ -43,8 +43,8 @@ pub(super) const WALK_RATIO: f32 = 2.5 / 7.0;
 /// Decision 0050.
 pub(super) const TURN_RATE: f32 = std::f32::consts::PI;
 
-/// The mouselook swim-pitch clamp (radians) — **VERIFIED** ±89.0° = 1.5533431 (`0x8089d8` =
-/// `0x3fc6d3f2`, the camera→SetPitch path's clamp; wow-re `swim-camera-pitch.md`, decision
+/// The mouselook swim-pitch clamp (radians) — ±89.0° = 1.5533431 (`0x8089d8` =
+/// `0x3fc6d3f2`, the camera→SetPitch path's clamp; decision
 /// 0492). NOT ±π/2 — that clamp belongs to the separate, rate-limited pitch-KEY integrator
 /// (`0x7c4f80`), whose keys are default-unbound and which we don't bind.
 pub(super) const MOUSELOOK_PITCH_CLAMP: f32 = 1.553_343;
@@ -73,8 +73,8 @@ pub(super) const TURN_RATE_MOVING: f32 = 0.75;
 /// The stationary body catch-up: once steering input stops, the rendered body closes on the aim at
 /// `turnRate × 8` rad/s, gap-clamped (the client's chase, `0x607ed0` tail — its clock is stamped
 /// every non-steering frame, so elapsed ≈ one frame). While steering, the catch-up is FROZEN and
-/// only the 90° ceiling moves the body — the head-leads-then-body-follows turn-in-place (wow-re
-/// `b947e5aa`, decision 0106).
+/// only the 90° ceiling moves the body — the head-leads-then-body-follows turn-in-place
+/// (`0x60818a`–`0x6081bf`, decision 0106).
 pub(super) const STATIONARY_CHASE_RATE: f32 = 8.0;
 
 // ── Character-controller feel knobs (decision 0009) ──────────────────────────────────────────────
@@ -88,9 +88,9 @@ pub(super) const STATIONARY_CHASE_RATE: f32 = 8.0;
 /// Known since to be the ctor **placeholder**, not the real mover's radius: `0x6174b0` overwrites
 /// `+0xb0`/`+0xb4` from `CreatureModelData` on every model build (`0x5fb880` → `0x5fb9dd` passes
 /// `force = 1`, which skips the only refusal path), so the live extents are per-model — human male
-/// radius **0.30555**, human female **0.20835** (VERIFIED, wow-re `mover-collision-scalars.md`;
-/// decision 1125). Adopting them is the same movement-fidelity question [`CAPSULE_HEIGHT`] describes
-/// below, and this radius is its other half.
+/// radius **0.30555**, human female **0.20835** (decision 1125). Adopting them is the same
+/// movement-fidelity question [`CAPSULE_HEIGHT`] describes below, and this radius is its other
+/// half.
 pub(crate) const CAPSULE_RADIUS: f32 = 1.0 / 3.0;
 /// Player capsule total height (yd) — the **movement** capsule avian sweeps, deliberately a
 /// constant. Numerically the vanilla ctor-default collision height it was derived from
@@ -104,7 +104,7 @@ pub(crate) const CAPSULE_RADIUS: f32 = 1.0 / 3.0;
 pub(crate) const CAPSULE_HEIGHT: f32 = 2.027_777_7;
 
 /// The client's own **empty-world collision height** (yd) — the `CMovement` ctor's immediate
-/// `0x4001c71c` at `0x616fd8` (VERIFIED, wow-re `collision.md` "the collision volume"), which the
+/// `0x4001c71c` at `0x616fd8`, which the
 /// per-unit param setter `0x6174b0` overwrites from the unit's model. This is the fallback every
 /// depth line takes for a unit whose display id doesn't resolve to a `CreatureModelData` row — the
 /// same role it plays in the reference, and what vmangos falls back to as well (its `2.f`).
@@ -123,8 +123,7 @@ pub(crate) const TERMINAL_VELOCITY: f32 = 60.148_003;
 /// **Terminal fall speed under feather fall** (yd/s) — the *whole* of what Slow Fall does. The
 /// reference's fall-velocity query `0x7c5d20` picks its clamp from one flag test
 /// (`0x7c5d23 test [ecx+0x40], 0x20000000`): the ordinary cap `[0x87d894]` = 60.148, or this one
-/// `[0x87d898]` when `MOVEFLAG_SAFE_FALL` is set. VERIFIED — wow-re `system/collision/ledger.tsv`
-/// (`0x7c5d20`, sweep2 §5) and `scratch/spec-ground.md`'s terminal-vel select.
+/// `[0x87d898]` when `MOVEFLAG_SAFE_FALL` is set. `0x7c5f50` makes the same select as `0x7c5d20`.
 ///
 /// The same 7.0 shows up on the server: vmangos raises its anticheat's expected jump speed to
 /// `max(current, 7.0f)` on receiving a feather-fall ack (`HandleMovementFlagChangeToggleAck:576`) —
@@ -132,9 +131,8 @@ pub(crate) const TERMINAL_VELOCITY: f32 = 60.148_003;
 pub(crate) const FEATHER_TERMINAL_VELOCITY: f32 = 7.0;
 /// **How far above the ground a hovering body rests** (yd) — the whole of what Hover does. The
 /// reference extends the walk resolver's down-probe by `[0x7ff9d8]` = 1.0 (`0x636dd2`) and then
-/// subtracts it back out of the snap, landing the body exactly a yard clear. VERIFIED — wow-re
-/// `scratch/moveflag-family.md` §4, which settled it as a **direct write to `CMovement.pos.z`**
-/// rather than a probe widening, closing `step-vs-fall-election.md`'s open bit-identity handoff.
+/// subtracts it back out of the snap, landing the body exactly a yard clear: a **direct write to
+/// `CMovement.pos.z`** (`0x636e81`–`0x636ea9`) rather than a probe widening.
 pub(crate) const HOVER_HEIGHT: f32 = 1.0;
 /// **How fast a hovering body rises to that clearance** (yd/s). The snap itself can only *lower* the
 /// body — `pos.z −= max(L − 1.0, 0)` (`0x636e52`–`0x636ea9`) skips its write entirely when the floor
@@ -148,7 +146,7 @@ pub(super) const GROUND_COS: f32 = 0.642_788;
 /// Downward probe distance (yd) to decide whether we're standing on ground.
 pub(super) const GROUND_PROBE: f32 = 0.2;
 /// The post-move downward snap's **slope ratio** — the client's step-vs-fall election
-/// (`0x6367b0`, constant `[0x80c740]` = 1.8493990; wow-re `step-vs-fall-election.md`): the snap
+/// (`0x6367b0`, constant `[0x80c740]` = 1.8493990): the snap
 /// probe reaches `d_h · ratio + slack + collision height` below the post-move position, where
 /// `d_h` is the frame's achieved horizontal travel. Scaling by the travel makes the absorbed
 /// *slope* the constant (atan 1.8494 ≈ 61.6°, comfortably above the 50° walkable limit),
@@ -160,7 +158,7 @@ pub(super) const GROUND_PROBE: f32 = 0.2;
 /// The ratio itself is confirmed to be one constant with two jobs, exactly as we use it: `0x80c740`
 /// has four references image-wide, and they are the foot cone's waist ring (`0x631c0b`) and this
 /// step-down term (`0x636dda`, inside `0x6367b0`) among them — the same 61.6° serving the climb and
-/// the descent (wow-re `mover-collision-scalars.md`).
+/// the descent.
 pub(super) const STEP_SLOPE_RATIO: f32 = 1.849_399;
 /// The election's fixed slack (yd) added to the travel-scaled snap reach — `[0x7ff9d0]` = 1/36 yd.
 pub(super) const STEP_SNAP_SLACK: f32 = 0.027_777_8;
@@ -181,8 +179,8 @@ pub(super) const STEP_SNAP_SLACK: f32 = 0.027_777_8;
 /// flat top) and 1121's deferred 1.04 yd ledge.
 pub(crate) const STEP_UP_HEIGHT: f32 = 1.0;
 /// The rise budget of a body the reference does **not** treat as player-controlled — a creature, a
-/// pet, a charmed/possessed/feared/confused/rooted player (decision 1125, wow-re
-/// `mover-collision-scalars.md`): `0x617430` takes `0x5fa550`'s FALSE leg and returns the constant
+/// pet, a charmed/possessed/feared/confused/rooted player (decision 1125): `0x617430` takes
+/// `0x5fa550`'s FALSE leg and returns the constant
 /// `2.0` at `[0x801628]`, where a player's is its own `[CMovement+0xb8]` = 1.0. So a creature steps
 /// twice as high as we do, and its certify advance (`H·tan50°`) reaches twice as far; the creature
 /// clamp's walker step ([`crate::net::motion::spline::ground_clamp_creatures`]) is the consumer.
@@ -217,8 +215,8 @@ pub(crate) const CREATURE_STEP_UP_HEIGHT: f32 = 2.0;
 /// at one radius is still over the face and reads it as a steep floor.
 pub(super) const STEP_UP_ADVANCE: f32 = 1.191_753_6;
 /// The certify reach **per yard of rise budget** — `tan 50°`, since the reference's reach is
-/// `max(H·tan50°, r + 1/720)` with `H` the mover's own budget (`0x636147`–`0x636190`, wow-re
-/// `ret2-commit-law.md`). [`STEP_UP_ADVANCE`] is this at the player's `H` of 1.0; a creature's 2.0
+/// `max(H·tan50°, r + 1/720)` with `H` the mover's own budget (`0x636147`–`0x636190`).
+/// [`STEP_UP_ADVANCE`] is this at the player's `H` of 1.0; a creature's 2.0
 /// (`CREATURE_STEP_UP_HEIGHT`) reaches 2.38 yd through the same law.
 pub(super) const STEP_UP_ADVANCE_PER_YARD: f32 = STEP_UP_ADVANCE / STEP_UP_HEIGHT;
 /// The **foot cone's height** (yd): how far above the feet the reference's movement solid is still
@@ -229,11 +227,11 @@ pub(super) const STEP_UP_ADVANCE_PER_YARD: f32 = STEP_UP_ADVANCE / STEP_UP_HEIGH
 /// at `0x631440` emits 9 planes — 4 vertical box sides at `center.xy ± radius`, and 4 bevels running
 /// from a point at the foot out to `(pos.xy ± radius, pos.z + r')` with `r' = radius · 1.8493990`
 /// (`[0x80c740]` — our [`STEP_SLOPE_RATIO`]), above which it is a plain vertical box. There is no
-/// −Z plane: the solid is open at the bottom (wow-re `climb-vs-slide.md` §2).
+/// −Z plane: the solid is open at the bottom.
 ///
 /// So a *low* edge never meets a wall — it meets the slanted skirt, and the resolver's ordinary
 /// slide carries the body up it at the cone's own surface slope, atan 1.8494 ≈ 61.6°, gaining
-/// `1.8494 · cosθ · len` per step (the note's `T` at §4). Only an edge **above** this height meets
+/// `1.8494 · cosθ · len` per step (`0x635c00`'s `T`). Only an edge **above** this height meets
 /// the vertical box square, and that is the case the instant step-up ([`STEP_UP_HEIGHT`]) exists
 /// for. One solid, two behaviours, selected by the edge's height above the feet.
 ///
@@ -282,7 +280,7 @@ pub(super) const WEDGE_MIN_FALL: f32 = 1.0;
 pub(super) const AIR_NUDGE_SPEED: f32 = 2.5;
 /// The FALLINGFAR **distance leg** (yd): a *jump* arc (launch vz ≠ 0) latches MOVEFLAG_FALLINGFAR
 /// once it descends this far below its launch height — the fall resolver's `0x633240`, constant
-/// `[0x80dff8]` = 1/9 yd (wow-re `land-anim-height-gate.md`). Latched, the arc is a **far fall**:
+/// `[0x80dff8]` = 1/9 yd. Latched, the arc is a **far fall**:
 /// the anim layer swaps to Fall(40) mid-air. A flat jump never descends below its takeoff, so it
 /// never latches — its hang stays Jump(38). The legs are exclusive on the launch vz: step-off
 /// falls take [`FALL_FAR_TIME`] instead (decision 0179).
@@ -476,20 +474,19 @@ impl MoveModes {
 
 /// **The precondition both movement-input predicates evaluate first** — the reference's
 /// `0x5144e0`, called at the head of `0x514560` (at `0x514568`) and of `0x5145b0` (at `0x5145b8`).
-/// It answers *"is there a mover, and is it in a state where input means anything at all"*. Quoted
-/// in full and re-derived in wow-re `ui/scratch/local-move-input-gate.md` **§6.2**, its five
-/// conjuncts are:
+/// It answers *"is there a mover, and is it in a state where input means anything at all"*.
+/// Its five conjuncts are:
 ///
 /// 1. the mover object resolves (`0x5144e7`);
 /// 2. **`[[mover+0x110]+0x40] > 0` — UNIT_FIELD_HEALTH**, signed i32, strictly greater, the `jg` at
-///    `0x5144fd`. (The field identity is **VERIFIED** three independent ways in §6.1 — the
+///    `0x5144fd`. (The field identity is established three independent ways — the
 ///    descriptor-base arithmetic, the `UnitHealth` registrar pair `.data 0x850510 → 0x5174d0`, and
-///    the low-health warning's `fild [eax+0x40]; fidiv [eax+0x58]`. `rf79`'s INFERRED label is
-///    retired.) — the [`MoverInput::dead`] field;
+///    the low-health warning's `fild [eax+0x40]; fidiv [eax+0x58]` at `0x5ecafd`.) — the
+///    [`MoverInput::dead`] field;
 /// 3. the CMovement-aux gate `[[mover+0x118]+0xa4]` null-or-`&4` (`0x514516`);
 /// 4. `!0x60f5b0(obj)` — the **KNOCKDOWN animation lockout**, and *not* an on-taxi predicate: it
 ///    returns `AnimationData.dbc` column 3 bit `0x80`, which the shipped table sets on exactly one
-///    of 208 rows, id 121 `Knockdown` (§6.2's census). It contributes nothing while dead;
+///    of 208 rows, id 121 `Knockdown`. It contributes nothing while dead;
 /// 5. `!(IsActivePlayer(mover) && [mover+0x1c70] & 1)` — the **far-sight ENGAGED latch**, the
 ///    [`MoverInput::view_is_out`] field.
 ///
@@ -517,15 +514,14 @@ pub(crate) struct MoverInput {
     /// (0308 §the release), so `0x5144fd`'s `jg` is taken and the ghost gets every input back.
     /// Nothing in the input path, the emitters or the send gates reads the ghost bit at all — a
     /// band census finds **zero** `PLAYER`-block reads across the whole InputControl and CMovement
-    /// ranges (§6.6). The ghost bit *is* read in the collision layer, where it adds trace mask bit
-    /// `0x8000` (`0x631658`) — a separate finding, and not this one.
+    /// ranges (`0x513000`–`0x516000`, `0x7c4000`–`0x7c8000`). The ghost bit *is* read in the
+    /// collision layer, where it adds trace mask bit `0x8000` (`0x631658`) — a separate finding,
+    /// and not this one.
     pub(crate) dead: bool,
     /// **Conjunct 5, the far-sight term** — `!(IsActivePlayer(mover) && [mover+0x1c70] & 1)`, held
     /// here in the affirmative: *my view is out on a far-sight object, and the body I would be
     /// driving is my own*. While that holds the reference refuses **both** predicates — you may
-    /// neither walk nor turn your own body while you are looking through Mind Vision. (wow-re
-    /// §6.2. Both of this conjunct's labels were CORRECTED on 2026-08-31: they previously read
-    /// "charmed", and had never been derived.)
+    /// neither walk nor turn your own body while you are looking through Mind Vision.
     ///
     /// **Both halves are load-bearing, and `IsActivePlayer` is the one that would be easy to
     /// drop.** `0x514537 call 0x5fa6d0` tests the *mover* against the active player and returns the
@@ -539,8 +535,8 @@ pub(crate) struct MoverInput {
     /// **Engaged means the subject RESOLVED, not merely that the field arrived.** The far-sight
     /// machine `0x5ee290` sets the latch only on its ENGAGE leg (`0x5ee3f6 or ecx,1`), reached
     /// after `0x5ee2ef` resolves the guid; the *field non-zero but object unresolved* leg falls
-    /// through to `0x5ee32d` — camera home, pending cast cancelled, `return 0` — and sets nothing
-    /// (wow-re `object-layer/scratch/farsight-and-client-control.md` §2.1). So the benilla analog
+    /// through to `0x5ee32d` — camera home, pending cast cancelled, `return 0` — and sets nothing.
+    /// So the benilla analog
     /// is the **resolved** [`super::view_subject::ViewSubject`] subject, not the raw
     /// `PLAYER_FARSIGHT` field: through the ~400 ms vmangos defers the set by, the body is still
     /// ours to drive.
@@ -585,14 +581,14 @@ impl MoverInput {
     /// outright *and* force-stops either already in flight. Each emitter has exactly one caller,
     /// immediately behind that gate, and no data or vtable reference anywhere in the image — so
     /// while this predicate is false **no keyboard or mouse turn can reach `CMovement::StartTurn
-    /// 0x7c6d90` by any route** (VERIFIED, wow-re `local-move-input-gate.md` §4).
+    /// 0x7c6d90` by any route**.
     ///
     /// Its own term past the shared precondition is `UNIT_FIELD_FLAGS & 0x40000` — a descriptor
     /// read, not an aura and not a movement flag (decision 0872). **And because the precondition is
     /// shared, a dead body is "stunned" as far as this predicate is concerned**: that single fact is
     /// why the reference refuses to turn a corpse.
     ///
-    /// **The MOUSE turn reaches the same answer down a different path** (§6.4, and this corrects
+    /// **The MOUSE turn reaches the same answer down a different path** (this corrects
     /// what 1753 first wrote). The right-drag handler is `0x514400`, called from the mouse-MOVE
     /// handler `0x492c00`; its body hand-off `0x51447b call 0x5103e0` is gated at `0x514474` by a
     /// *third* predicate, **`0x5145e0`**, whose first act is to call this one — so the health term
@@ -619,8 +615,7 @@ impl MoverInput {
     /// caller's here), and **`GetStandState() == 0`** (`0x51460c call [eax+0xa4]` → the CGPlayer
     /// override `0x5ed570`, the client-predicted cache `[player+0x1d68]`; `0x514612 neg; sbb; inc`).
     /// The commit is refused a second, independent time downstream: `0x5151b0` re-tests the raw
-    /// descriptor byte at `0x51520a` (wow-re `local-move-input-gate.md` §6.4,
-    /// `standstate-movement-trigger.md` §4.1, both VERIFIED).
+    /// descriptor byte at `0x51520a`.
     ///
     /// So a right-drag while **seated** — sitting, in a chair (2, and the server-driven 4/5/6),
     /// asleep — turns the camera and leaves the body exactly where it is, and puts nothing on the
@@ -640,12 +635,11 @@ impl MoverInput {
     /// click-to-move and `/follow` and fires `AUTOFOLLOW_END` (event `0x170`).
     ///
     /// It is reached only when **BOTH** predicates are down: `0x5146c3 jne` not taken (`bl == 0`)
-    /// *and* `0x5146ce jne` not taken (`[ebp+0xf] == 0`). That is the correction wow-re's §6.3 makes
-    /// to `rf86-autofollow-cancel-set.md` §5, which named the health test alone — necessary, but not
-    /// enough to name the leg. **A pure ROOT does not cancel a follow** (translate down, turn still
-    /// up), and neither does a pure stun; **death does**, because it takes both. Ice Block, which
-    /// grants root and stun together, does too. So does the far-sight term, for the same reason
-    /// death does — it is the other conjunct of the shared precondition.
+    /// *and* `0x5146ce jne` not taken (`[ebp+0xf] == 0`). The health test alone is necessary, but
+    /// not enough to name the leg. **A pure ROOT does not cancel a follow** (translate down, turn
+    /// still up), and neither does a pure stun; **death does**, because it takes both. Ice Block,
+    /// which grants root and stun together, does too. So does the far-sight term, for the same
+    /// reason death does — it is the other conjunct of the shared precondition.
     ///
     /// benilla had the root alone in this position and so cancelled on a Frost Nova, which the
     /// reference does not (decision 1753).
@@ -678,7 +672,7 @@ impl MoverInput {
 ///
 /// They are keyed on different state on purpose, exactly as the reference has them: a pure root
 /// (Frost Nova, Entangling Roots) still pivots — turn is on the allow-list *deliberately* — and only
-/// `UNIT_FLAG_STUNNED` takes the pivot away (wow-re `unit-flags-movement-gates.md` §5). Nothing else
+/// `UNIT_FLAG_STUNNED` takes the pivot away. Nothing else
 /// is touched: the granted modes ride on (drop one and the server forgets it), SWIMMING survives a
 /// root exactly as `0xffe07f00` preserves `0x200000`, and FALLING is already gone by the time we get
 /// here — the root ended the arc ([`super::mover`]'s anchor).
@@ -716,8 +710,7 @@ pub(crate) struct Player {
     pub(super) modes: MoveModes,
     /// **Autorun** latched on — the reference's input bit `0x1000` in the local mover's input word
     /// `[MOVE+4]`, flipped by `ToggleAutoRun 0x513de0` (a read+invert: the command family's only
-    /// *toggle*, where every directional command is a set/clear pair). VERIFIED, wow-re
-    /// `rf78-movement-command-handlers.md`.
+    /// *toggle*, where every directional command is a set/clear pair).
     ///
     /// It is not a movement of its own. The axis emitter `0x514da0` folds the bit into the
     /// **forward axis** (`test ah,0x10`), so autorun *is* held-forward: it nets against a held S
@@ -836,9 +829,11 @@ pub(crate) struct Player {
     /// right-drag — into a mid-cast "you moved". Decision 0907; the reconcile lives in
     /// [`super::movement_net::stream_self_movement`].
     pub(super) last_pos: [f32; 3],
-    /// The stand state we last volunteered (`CMSG_STANDSTATECHANGE`) whose echo into our
-    /// `UNIT_FIELD_BYTES_1` hasn't landed yet — the local commit (the client's `SetStandState`
-    /// `0x6127b0` applies immediately *and* sends; decision 0080c). `None` = at the echoed value.
+    /// The stand state we last committed locally — volunteered (`CMSG_STANDSTATECHANGE`) or the
+    /// server's own (`SMSG_STANDSTATE_UPDATE`, 2339) — whose echo into our `UNIT_FIELD_BYTES_1`
+    /// hasn't landed yet: the reference's predicted cache `[player+0x1d68]`, written by the
+    /// setter's local half `0x6127b0`, which sends nothing itself (the volunteer path `0x5ed430`
+    /// sends first, then calls it; decisions 0080c, 2339). `None` = at the echoed value.
     pub(super) stand_pending: Option<u8>,
     /// **Settling after a teleport/summon/login**: the streamed world (terrain *and* its WMO
     /// buildings + colliders) arrives over several frames, so the collision under the destination
@@ -874,6 +869,11 @@ pub(crate) struct Player {
     /// judgement and pushes [`Player::settle_deadline`] forward, so the timeout budget measures
     /// time waiting for the *destination's* world (decisions 0710 + 0737).
     pub(crate) world_stale: bool,
+    /// The pitch the login seize seats the camera at — the saved pose's `cameraPitch` when
+    /// [`super::camera_saved`] restored one for this session, else the shipped opening pitch. Set
+    /// by the pose load, read once by the seize: the seize used to seat its own constant over the
+    /// restored value, so the pitch half of the remembered pose never survived a login.
+    pub(super) login_pitch: Option<f32>,
     /// A same-map teleport landed: the server relocated the mover, so any in-progress self
     /// server-ride (charge/taxi) is **void** — vmangos teleports at ITS flight end (its own spline
     /// finishes ~latency before ours) and its spline-done handler ignores acks while the teleport
@@ -883,7 +883,7 @@ pub(crate) struct Player {
     pub(super) ride_abort: bool,
     /// **A `MSG_MOVE_WORLDPORT_ACK` is owed, payable at the settle release** (decision 1340).
     /// The real client sends the worldport ack as the LAST act of its blocking destination load
-    /// (wow-re: `0x401bc0` sends `0xDC` at `0x401cae` only after `0x66fbe0`'s load returns) — our
+    /// (`0x401bc0` sends `0xDC` at `0x401cae` only after `0x66fbe0`'s load returns) — our
     /// async re-expression of "after the load" is the release. Safe to defer: vmangos has no load
     /// timeout, drops every packet we'd send meanwhile (the player is out-of-world for the whole
     /// window), and force-acks at logout. Set by the non-riding worldport snap; a riding crossing
@@ -931,7 +931,7 @@ pub(crate) struct Player {
     ///
     /// `force == 0` is what makes it a *different* jump from the player's: it skips
     /// `0x7c623a`'s `test [ecx+0x40], 0x40000000` hover refusal — the wire path exists precisely to
-    /// be able to jump a unit that is already hovering (wow-re `moveflag-family.md` §4.2). It still
+    /// be able to jump a unit that is already hovering. It still
     /// takes the ROOT|FALLING refusal at `0x7c625c`, and it still reads SWIMMING at `0x7c6261` to
     /// pick the take-off seed. So this is a latch and not a direct write: the reference commits the
     /// jump inside the handler because `MOVEFLAG_FALLING` then keeps its resolver off the body,
@@ -1026,15 +1026,14 @@ pub(crate) struct Player {
     /// ([`super::camera_water::classify`]) therefore reads *this*, one frame behind, which is the
     /// same lag the reference's own camera runs at — and it is load-bearing, not incidental: a
     /// depth that is piecewise constant is what keeps `d - target` from grazing a band edge while
-    /// swimming (2173, and `camera-water-corridor-spec.md` §7).
+    /// swimming (2173).
     pub(crate) liquid_surface: Option<f32>,
     /// The **mover pitch** (radians, +up) — the client's persistent per-unit pitch
-    /// (`CMovement+0x20`, the swim §5's TU-B): **held** when unsteered (an idle floater keeps its
+    /// (`CMovement+0x20`): **held** when unsteered (an idle floater keeps its
     /// pitch — never auto-leveled; the only zeroing writer `0x7c6e80` fires from
     /// stop-swim/teleport, not mouse release). ActiveMover by mouselook as a **DIRECT set** of the
-    /// camera aim pitch, clamped [`MOUSELOOK_PITCH_CLAMP`] (±89°) — **VERIFIED** (the camera-pitch
-    /// §5, wow-re `swim-camera-pitch.md`, decision 0492, refuting the earlier no-camera-coupling
-    /// census): the ref's mouse-move event chain lands in `SetPitch 0x7c6f70`, an unconditional
+    /// camera aim pitch, clamped [`MOUSELOOK_PITCH_CLAMP`] (±89°; decision 0492): the ref's
+    /// mouse-move event chain lands in `SetPitch 0x7c6f70`, an unconditional
     /// store with no integrator and no rate limit, and the basis rebuild re-aims travel in-call —
     /// hence zero lag. The `0x7c4f80` 0.75·turnRate integrator (clamp ±π/2) belongs to the
     /// PitchUp/Down keys, default-unbound in 1.12, which we don't bind. A left-drag camera
@@ -1044,23 +1043,22 @@ pub(crate) struct Player {
     /// **It is not the *swim* pitch, and the name it used to carry was the bug** (decision 1616,
     /// B322): `+0x20` is one field, live in every mode. The mouse path that writes it —
     /// `0x514400 → 0x5103e0 → 0x515330 → 0x60de70 → 0x6198a0` — carries **no swim test** at any
-    /// link (`swim-camera-pitch.md` §5/§7: the unit gate `0x5145e0` is controllability only), and
+    /// link (the unit gate `0x5145e0` is controllability only), and
     /// `SetPitch`'s own store at `0x7c6f91` precedes its `test [esi+0x40],0x200000`. Swimming gates
     /// only what *reads* it: the travel basis, the body pose, the wire tail. On land it has two
     /// other readers, and both are water walking's — the trace-mask arm's third gate
     /// (`0x63161e`, pitch > −37°) and `SetPitch`'s own dive-through (`0x7c6fb3`). Steering it only
     /// inside the swim branch left both unbuildable, which is why 1611 could only name them.
     /// Streamed on the wire's swim tail; the body renders pitched by it while swimming fwd/back
-    /// (TU-A's `Ry` law, see the render block in [`super::control`]).
+    /// (the `Ry` law of `0x60a110`, see the render block in [`super::control`]).
     pub(super) mover_pitch: f32,
     /// The camera pitch the **last pitch event** carried — the aim value we most recently pushed
     /// into [`Player::mover_pitch`]. Not state of the avatar's; state of the *input*, and it is
     /// here because the reference's pitch push is **event-driven, not per-frame**: `SetPitch` is
     /// called from the mouse-MOTION handler `0x514400` (input event `0x400500cb`, gated on a held
-    /// drag button), so a mouse that does not move enqueues nothing at all
-    /// (`swim-camera-pitch.md`, CADENCE). Our control system has only the already-accumulated
-    /// camera angle, so "the mouse moved" is spelled here as "the camera aim differs from the one
-    /// the last push carried".
+    /// drag button), so a mouse that does not move enqueues nothing at all. Our control system has
+    /// only the already-accumulated camera angle, so "the mouse moved" is spelled here as "the
+    /// camera aim differs from the one the last push carried".
     ///
     /// Which is load-bearing rather than pedantic (decision 1616): the other writers of the pitch —
     /// the drunk wobble, and StopSwim's zeroing at `0x7c6e80` — are only real if a still mouse
@@ -1070,7 +1068,7 @@ pub(crate) struct Player {
     pub(super) aim_pitch_seen: f32,
     /// This frame's **flag-scalar swim travel speed** (yd/s) — the directional swim/swimBack
     /// speed when any swim translation input is live, else 0. The swim stroke's playback-rate
-    /// numerator — **VERIFIED** (the swim-feel §5's TU-I): `0x5fe2f0` divides `GetCurrentSpeed`
+    /// numerator: `0x5fe2f0` divides `GetCurrentSpeed`
     /// (flags + static speed fields only, never a velocity/pitch projection) by the clip's
     /// moveSpeed, so a vertically pitched stroke plays at full rate. Written by the controller's
     /// swim arm; read at the `MovementState` fill; stale while not swimming.
@@ -1193,7 +1191,7 @@ impl Player {
     /// `controller`, which needs a real held mouse button (`mouselook`) and a moving OS cursor
     /// inside the viewport. Neither is available to an unfocused probe window, so before this
     /// there was **no way to make a benilla client swim nose-up or nose-down without a human on
-    /// the mouse** — which is why the observed-swimmer tilt (decision 0464 TU-A) could ship, and
+    /// the mouse** — which is why the observed-swimmer tilt (decision 0464) could ship, and
     /// sit for weeks, with nothing but the director's eye able to say whether it worked.
     ///
     /// Writes the same field `SetPitch 0x7c6f70` writes, under the same ±89°
@@ -1202,8 +1200,8 @@ impl Player {
     /// one value.
     ///
     /// Not a *byte* copy of `SetPitch`, and deliberately: that store is epsilon-gated — it commits
-    /// iff `|new − old| >= [0x8026bc] = 2^-20`, the `==` case included (a parity test, wow-re
-    /// `system/collision/scratch/create-block-swim-pitch.md`). Reproducing a 1e-6 rad deadband in
+    /// iff `|new − old| >= [0x8026bc] = 2^-20`, the `==` case included (a parity test).
+    /// Reproducing a 1e-6 rad deadband in
     /// an instrument would buy nothing and would make a slow scripted sweep stutter; the gate is
     /// gameplay's to model on the mouse-look push if it ever matters, which at that magnitude it
     /// cannot.
@@ -1222,8 +1220,7 @@ impl Player {
     /// The character's *facing* (Bevy yaw, radians) — the aim, kept in sync with the camera by
     /// right-drag/movement. This is the unit's orientation as sent to the server, distinct from the
     /// rendered body heading (`model_yaw`, which a strafe rotates). The 3D-audio listener panning
-    /// tracks this (wow-re benilla-pins B14: the listener forward is the character facing, not the
-    /// camera).
+    /// tracks this (the listener forward is the character facing, not the camera: `0x483430`).
     pub(crate) fn facing(&self) -> f32 {
         self.face_yaw
     }
@@ -1240,7 +1237,7 @@ impl Player {
 
     /// The avatar's current CMovement move-flags as last streamed (directional + turn bits — see
     /// [`crate::creature_anim::move_flags`]). The water-foam selector reads the same two bit-tests as
-    /// the reference (`& 0xf` translating, `& 0x30` turning; wow-re CWater0Ripple driver `0x5fa760`).
+    /// the reference (`& 0xf` translating, `& 0x30` turning; the CWater0Ripple driver `0x5fa760`).
     pub(crate) fn move_flags(&self) -> u32 {
         self.move_flags
     }
@@ -1296,7 +1293,7 @@ impl Player {
     /// So it is **exactly zero with no direction key held** — not a measured velocity that decays,
     /// and not the weather wind's 149 ms positional average (`0x67c150`): it is live, and tracks a
     /// speed change on the same frame. The precipitation spawn slab's tilt keys on it through
-    /// `mgr+0x7c` (wow-re `wx-snow-placement-law.md` §9), which is why the distinction earns an
+    /// `mgr+0x7c` (`0x67bf8b`), which is why the distinction earns an
     /// accessor: an averaged stand-in would leave the slab leaning for 150 ms after a stop, and a
     /// raw `horiz_vel` would keep it leaning through an entire fall on take-off momentum.
     pub(crate) fn planar_speed(&self) -> f32 {
@@ -1321,15 +1318,15 @@ impl Player {
     }
 
     /// A server-authored spline currently owns the avatar (Charge/knockback/taxi — the
-    /// [`super::server_ride`] state). For instruments (the taxi probe watches the flight run) and
-    /// the UI's `UnitOnTaxi` feed.
+    /// [`super::server_ride`] state). For instruments (the taxi probe watches the flight run).
+    /// **Not** `UnitOnTaxi` — a fear or a charge is a server ride too; that verb reads
+    /// [`crate::player::UNIT_FLAG_TAXI_FLIGHT`] off the descriptor (`0x517a86`).
     pub(crate) fn server_riding(&self) -> bool {
         self.server_riding
     }
 }
 
-/// The **forward/back axis** — a net accumulation, byte-verified at the reference's emitter
-/// `0x514da0` (wow-re `rf79-autorun-cancel-set.md` §3):
+/// The **forward/back axis** — a net accumulation, at the reference's emitter `0x514da0`:
 /// `autorun(+1) + forward(+1) + both-buttons(+1) − backward(−1)`, then one START in `sign(axis)`,
 /// or a genuine STOP at zero. A pure function so the state table it encodes can be pinned by test —
 /// the controller reads it for the direction vector, the backpedal speed, the swim amounts, and the
@@ -1343,13 +1340,14 @@ pub(super) fn forward_axis(
     i32::from(forward) + i32::from(both_buttons) + i32::from(autorun) - i32::from(backward)
 }
 
-/// Does this frame's input **destroy** autorun? The cancel set (wow-re `rf79-autorun-cancel-set.md`
-/// §1 — six writers clear the reference's `0x1000`; these are the four with a benilla analog).
+/// Does this frame's input **destroy** autorun? The cancel set (six writers clear the reference's
+/// `0x1000`; these are the four with a benilla analog).
 ///
 /// `fwd_down`/`back_down` are **key-DOWN edges, not held state**: the clear lives in the shared SET
 /// helper (`0x514a5a`, gated `test cl,0x30`), and the release path restores nothing. `both_engaged`
 /// is the transition *into* both-buttons-held (`0x514a73`). `lost_mover` is death / root / stun / a
-/// taxi hand-off, where the emitter's gate drops and writer #4 clears the bit — a level, not an edge.
+/// taxi hand-off, where the emitter's gate drops and `0x514748` clears the bit — a level, not an
+/// edge.
 ///
 /// A jump, a chat EditBox taking focus, and a zone change are each VERIFIED *survivors* and are
 /// deliberately absent. Mounting is unsettled in the reference and is treated as a survivor here.
@@ -1372,8 +1370,7 @@ pub(super) fn autorun_cancelled(
 /// Standing up is the asymmetry: `newState == 0` jumps straight to the send and never consults the
 /// word at all, so movement can always stand you.
 ///
-/// Byte-for-byte (`0x5ed4d8`–`0x5ed501`; wow-re `object-layer/scratch/standstate-movement-trigger.md`
-/// §5.1, a §5 trio carve, decisions 1581/1582):
+/// Byte-for-byte (`0x5ed4d8`–`0x5ed501`; decisions 1581/1582):
 ///
 /// ```c
 /// if (newState != 0) {
@@ -1384,8 +1381,7 @@ pub(super) fn autorun_cancelled(
 ///
 /// **SLEEP takes BOTH tests, not a different one.** `0x5ed4ec eb 04` is an unconditional `jmp`
 /// *into* the second test, not around it — an either/or would have jumped to the send at
-/// `0x5ed501`. 1581 shipped it as an alternative, off a clause §1 had recorded in passing; §5
-/// carved the block for its own sake and corrected it. The `newState == 3` test is a plain
+/// `0x5ed501`. 1581 shipped it as an alternative. The `newState == 3` test is a plain
 /// equality: `2` (SIT_CHAIR) and `8` (KNEEL) take the shared leg exactly like `1` (SIT).
 ///
 /// | target state | effective mask | refused while |
@@ -1403,8 +1399,8 @@ pub(super) fn autorun_cancelled(
 /// **absent** from both — pitch, walk-mode, ROOT, and `FALLING` (`0x2000`): a standing jump does
 /// not block a sit, while a running one does, through `FORWARD` rather than through the jump.
 ///
-/// Because the refusal lives in the **one setter**, it covers every caller at once. wow-re's caller
-/// census closed that exhaustively (§5.2: six `e8` callers, no tail-jumps, no dword reference
+/// Because the refusal lives in the **one setter**, it covers every caller at once. Its caller
+/// census is exhaustive (six `e8` callers, no tail-jumps, no dword reference
 /// anywhere in the image, in no vtable) — the `X` keybind (`SitOrStand`, Lua `0x48b920`), the
 /// posture emotes through `DoEmote`'s `EmoteSpecProc == 1` leg, `StartAttack`, the movement-input
 /// wrapper `0x60be30`, and the five-minute AFK auto-sit in `WorldFrame::Render`.
@@ -1420,8 +1416,8 @@ pub(super) fn stand_state_refused(reads_dead: bool, move_flags: u32, new_state:
     // **A body that reads dead is refused outright, in EITHER direction** — the same setter's first
     // two guards, ahead of the stand-up asymmetry below and of the movement word: `0x5ed4a9 cmp
     // [eax+0x40],ebx` / `0x5ed4ac jle 0x5ed566` (UNIT_FIELD_HEALTH ≤ 0), then `0x5ed4b2`–`0x5ed4bd`
-    // on `UNIT_DYNAMIC_FLAGS & 0x20` — so a **feigner** is refused too, at unchanged health (wow-re
-    // `local-move-input-gate.md` §6.7; decision 1753). A corpse cannot sit, and it cannot stand up
+    // on `UNIT_DYNAMIC_FLAGS & 0x20` — so a **feigner** is refused too, at unchanged health
+    // (decision 1753). A corpse cannot sit, and it cannot stand up
     // either, which is why this sits above the `new_state == 0` exit rather than beside it.
     if reads_dead {
         return true;
@@ -1445,7 +1441,7 @@ mod stand_state_tests {
     /// **A body that reads dead is refused in EITHER direction** — `SetStandState`'s first two
     /// guards, ahead of the stand-up asymmetry and of the movement word: health ≤ 0 at `0x5ed4ac`,
     /// and `UNIT_DYNAMIC_FLAGS & 0x20` at `0x5ed4b2`–`0x5ed4bd`, which catches a **feigner** whose
-    /// health never moved (decision 1753, wow-re §6.7).
+    /// health never moved (decision 1753).
     #[test]
     fn a_body_that_reads_dead_can_neither_sit_nor_stand() {
         for state in [0u8, 1, 2, 3, 8] {
@@ -1562,7 +1558,7 @@ mod stand_state_tests {
 mod autorun_tests {
     use super::{autorun_cancelled, forward_axis};
 
-    /// The four states of wow-re RF-0079 §3's table, in its own terms.
+    /// The four states of the reference's axis table (`0x514da0`), in its own terms.
     #[test]
     fn the_axis_reproduces_the_verified_state_table() {
         // autorun, nothing held → +1, runs forward.
@@ -1963,9 +1959,8 @@ mod move_mode_tests {
         );
     }
 
-    /// **The teardown leg needs BOTH predicates down** (`0x5146d6 call 0x60fb60`) — wow-re §6.3,
-    /// which sharpens `rf86-autofollow-cancel-set.md` §5. benilla had the root in this position and
-    /// so ended a follow on a Frost Nova, which the reference does not.
+    /// **The teardown leg needs BOTH predicates down** (`0x5146d6 call 0x60fb60`). benilla had the
+    /// root in this position and so ended a follow on a Frost Nova, which the reference does not.
     #[test]
     fn only_both_predicates_down_tears_the_follow_down() {
         assert!(
diff --git a/crates/benilla-app/src/player/swim.rs b/crates/benilla-app/src/player/swim.rs
index 5ce30573..1b77fa6a 100644
--- a/crates/benilla-app/src/player/swim.rs
+++ b/crates/benilla-app/src/player/swim.rs
@@ -4,36 +4,34 @@
 //! the swim gaits ([`crate::creature_anim`] ids 41–45) for the local player and streams
 //! `MOVEFLAG_SWIMMING` (+ the pitch tail) on the wire (the decision-0052 swim follow-up).
 //!
-//! The enter/exit boundary is **VERIFIED** against the real client (wow-re
-//! `collision/scratch/swim-transition.md`, resolving benilla-pins **B7**): the per-frame local decision
+//! The enter/exit boundary is the real client's: the per-frame local decision
 //! `0x6030c0` fires `MOVEFLAG_SWIMMING 0x00200000` off `depth = liquidSurface − feetZ` vs a fraction of
 //! the unit's collision height, with a genuine 1/36-yd hysteresis band (see [`swim_enter_depth`]).
 //! There is **no** separate wade/water movement flag (`0x40000000` is HOVER — wading is just the
 //! implicit in-liquid-below-threshold state).
 //!
-//! The **vertical law is VERIFIED** (the swim §5's TU-B, wow-re `swim-mechanism.md`, superseding the
+//! The **vertical law** (superseding the
 //! earlier surface-follow reading): while SWIMMING the mover routes through the client's *floating*
 //! resolver, which **bypasses gravity entirely** — an idle swimmer's depth is **frozen** (no sink, no
 //! rise, no ease), the vertical comes only from the pitched travel velocity, and the one constraint is
 //! a **hard top-cap at `surface − 0.75·collisionHeight`** (`0x632ba0` ×0.75): the feet can never be
 //! shallower than the resting waterline, so a surfacing swimmer stops ~three-quarters submerged, head
-//! out. That cap constrains the **position, both ways** — wow-re's Q5 states it as "feet cannot come
-//! shallower than `surface − 0.75·collisionHeight`", a hard clamp re-tested each active substep — and
+//! out. That cap constrains the **position, both ways** — feet cannot come shallower than
+//! `surface − 0.75·collisionHeight`, a hard clamp re-tested each active substep — and
 //! what leaves a *stroking* swimmer above the line is usually not a rise but the surface **descending**
 //! under them, which is why the constraint has to be re-satisfied and not merely guarded against
 //! ([`settle_to_rest`], decision 0644). It is still no spring and no resting *seek* — the old
 //! `REST_SUBMERSION`/`BUOYANCY_RATE` ease is gone, and a swimmer *below* the line is never pulled up.
 //! Reaching the cap does NOT bleed the stroke off: the capped rise redirects **level, at full
 //! speed** — surface swimming — and the presented pitch levels with it ([`cap_redirect`],
-//! decisions 0499+0505). This is a **named divergence**: the §5 (wow-re
-//! `swim-topcap-velocity.md`) found the exe's own-input resolver GRINDS a steep aim at the
-//! cap (`0x634640` tangential re-sweep, no renormalization) — which contradicts the
-//! director-confirmed ref behavior — and its only leveling regime (travel-derived
-//! `asin(dir.z)` pitch) belongs to spline/CTM movers and would be overwritten per-frame by
-//! the 0492 mouselook direct-set. The redirect is benilla's construction reproducing the
-//! validated feel, kept until wow-re's live capture pins the real surface law (0505).
+//! decisions 0499+0505). This is a **named divergence**: the exe's own-input resolver GRINDS a
+//! steep aim at the cap (`0x634640` tangential re-sweep, no renormalization) — which contradicts
+//! the director-confirmed ref behavior — and its only leveling regime (travel-derived `asin(dir.z)`
+//! pitch) belongs to spline/CTM movers and would be overwritten per-frame by the 0492 mouselook
+//! direct-set. The redirect is benilla's construction reproducing the validated feel, kept until a
+//! live capture of the reference pins the real surface law (0505).
 //!
-//! The one way OUT through the top is the **swim jump** ([`breach_step`], TU-B(f)+TU-F
+//! The one way OUT through the top is the **swim jump** ([`breach_step`],
 //! `0x7c6230`): jump clears SWIMMING unconditionally and launches the walk mover's FALLING arc at
 //! [`SWIM_JUMP_SPEED`] — the breach hop. Re-entry is the same depth check plus the verified fall
 //! gate `0x7c5de0` — swim re-latches once the upward velocity has decayed to half the launch
@@ -43,9 +41,8 @@
 //! 0487 + 0498): a swimming press fires the jump-exit wherever it happens — at the surface it
 //! breaches out; submerged it's the ~1.6-yd dolphin-hop — and a held key does NOT re-fire
 //! after the re-latch (director-verified on the ref; the byte gate behind that is an open
-//! wow-re question, see 0498). The way to RISE is aiming up with the right mouse and swimming
-//! forward — the ref's own mouselook→SetPitch mechanism, **VERIFIED** (wow-re
-//! `swim-camera-pitch.md`, decision 0492).
+//! question, see 0498). The way to RISE is aiming up with the right mouse and swimming
+//! forward — the ref's own mouselook→SetPitch mechanism (`0x7c6f70`, decision 0492).
 
 use avian3d::prelude::*;
 use bevy::prelude::*;
@@ -64,7 +61,7 @@ pub(super) const SWIM_SPEED: f32 = 4.722_222;
 
 /// Backward swim speed (yd/s) — vanilla's default `MOVE_SWIM_BACK` (vmangos `baseMoveSpeed[4]` =
 /// 2.5), the fallback when the server's `SpeedInfo` hasn't streamed. A net-backward swim takes
-/// `min(swimBack, swim)` — **VERIFIED** (`0x7c4c90`'s swim arm, the swim-feel §5's TU-H): the
+/// `min(swimBack, swim)` (`0x7c4c90`'s swim arm): the
 /// backward bit `0x2` selects a min byte-identical in template to the run arm's
 /// `min(runBack, run)`; strafe-only swims at the forward [`SWIM_SPEED`].
 pub(super) const SWIM_BACK_SPEED: f32 = 2.5;
@@ -81,9 +78,8 @@ const SWIM_DEPTH_FRAC: f32 = 0.75;
 /// `0.75·h`, leave against `0.75·h − 1/36`, so between them the swim state holds (`0x603100`/`0x6031c0`).
 const SWIM_HYSTERESIS: f32 = 1.0 / 36.0;
 
-/// The `UNIT_FIELD_FLAGS` bits that decide whether a unit **may be locally SWIMMING at all** —
-/// **VERIFIED** in the shipped 5875 image (wow-re `collision/scratch/remote-swim-decision.md`, §5
-/// trio). `0x6030c0` tests them on **both** legs of its decision, with **opposite sense**:
+/// The `UNIT_FIELD_FLAGS` bits that decide whether a unit **may be locally SWIMMING at all**.
+/// `0x6030c0` tests them on **both** legs of its decision, with **opposite sense**:
 ///
 /// ```text
 /// ENTER (after depth > 0.75·R):
@@ -102,8 +98,7 @@ const SWIM_HYSTERESIS: f32 = 1.0 / 36.0;
 ///
 /// So the three bits are **one predicate**, not an entry permit: false blocks entry *and* forces an
 /// exit however deep the water. (Decision 1568 shipped this as enter-only, on the reading that the
-/// exit leg was flag-free — `wmo-liquid-scoping.md` §4.6 had never re-derived it. The §5 that
-/// re-derived it cold says otherwise; corrected in 1572.)
+/// exit leg was flag-free; corrected in 1572.)
 ///
 /// What each bit is:
 ///
@@ -152,8 +147,8 @@ pub(crate) fn swim_enter_depth(h: f32) -> f32 {
 }
 /// Submersion depth (yd) below which swimming **stops** — VERIFIED `0.75·h − 1/36` (the lower edge
 /// of the hysteresis band); also stops the instant there's no liquid over the feet. The band itself
-/// is an absolute `1/36` yd, independent of `h` (wow-re: "the band is exactly 1/36 yd … independent
-/// of `h`") — so it is subtracted, never scaled.
+/// is an absolute `1/36` yd, independent of `h` (`0x6030f2` subtracts `[0x7ff9d0]` from `0.75·h`) —
+/// so it is subtracted, never scaled.
 pub(super) fn swim_exit_depth(h: f32) -> f32 {
     swim_enter_depth(h) - SWIM_HYSTERESIS
 }
@@ -187,8 +182,8 @@ pub(super) fn surface_over_feet(world: &WorldPoint, feet: Vec3) -> Option<f32> {
 /// binary's `inLiquid == 0 → STOP`). Enter is a strict `depth > 0.75·h`; leave is `depth < 0.75·h − 1/36`
 /// (i.e. swimming holds while `depth ≥` the leave threshold), matching the two byte compares.
 ///
-/// The enter arm carries the **fall re-entry gate** — **VERIFIED** `0x7c5de0`, called from
-/// `0x6030c0`'s ENTER branch (the Space-§5's TU-G): a fresh launch is not re-latched into swim
+/// The enter arm carries the **fall re-entry gate** — `0x7c5de0`, called from
+/// `0x6030c0`'s ENTER branch: a fresh launch is not re-latched into swim
 /// until its **upward velocity has decayed to HALF the launch value** — blocked iff
 /// `FALLING ∧ v_up > 0 ∧ t_airborne < v_launch/(2g)` (≈0.236 s for a swim jump). Note the release
 /// happens *while still rising*: the dolphin-hop tops out ≈1.6 yd up, then swim re-latches and the
@@ -202,7 +197,7 @@ pub(super) fn surface_over_feet(world: &WorldPoint, feet: Vec3) -> Option<f32> {
 /// only the walk mover ran).
 pub(super) fn update_swimming(player: &mut Player, surface_y: Option<f32>, now: f32) -> bool {
     // **LEVITATING bails the whole decision** — the reference's very first instruction here
-    // (`0x6030d2 test ah,4` → `0x6031fa`; VERIFIED, wow-re `swim-transition.md`): neither the ENTER
+    // (`0x6030d2 test ah,4` → `0x6031fa`): neither the ENTER
     // arm nor the STOP arm runs, so the latch is left exactly as it stands. Not an optimisation —
     // it IS the mechanism of GM flight (decision 0726). The server sets SWIMMING and LEVITATING in
     // one packet, and the second is what stops the dry ground under us clearing the first on the
@@ -234,7 +229,7 @@ pub(super) fn update_swimming(player: &mut Player, surface_y: Option<f32>, now:
 /// **StopSwim zeroes the mover pitch** — `0x7c6e80` (`and [esi+0x40],0xffdfff3f`, then `+0x54` and
 /// `+0x20` to zero), the swim-clear the depth-driven stop reaches through
 /// `0x6031eb → 0x60dff0 → 0x61a070` → queue opcode `0x13` → the dispatcher arm `0x61601d`. It is
-/// the *only* zeroing writer of [`Player::mover_pitch`] (`swim-camera-pitch.md` (b)): mouse release
+/// the *only* zeroing writer of [`Player::mover_pitch`]: mouse release
 /// never levels it, and neither does anything on land.
 ///
 /// Which matters now that the pitch is land-live and water walking reads it (decision 1616): swim
@@ -252,8 +247,8 @@ fn stop_pitch(player: &mut Player, was: bool) {
     }
 }
 
-/// The **jump out of the water** — the takeoff frame of a jump while swimming (**VERIFIED**
-/// mechanism, wow-re `swim-mechanism.md` TU-B(f)+TU-F, `0x7c6230`): SWIMMING selects the take-off
+/// The **jump out of the water** — the takeoff frame of a jump while swimming (`0x7c6230`):
+/// SWIMMING selects the take-off
 /// [`SWIM_JUMP_SPEED`] over the land 7.9555, then the handler clears SWIMMING and sets FALLING.
 /// The Jump command routes here at *any* depth (no swim re-route, no surface-proximity gate —
 /// the deep press is the dolphin-hop; decision 0487 restored the ref routing after 0479's
@@ -314,7 +309,7 @@ pub(super) struct SwimOutcome {
 /// it off: reaching the surface flips a pitched-up swim into full-speed *surface swimming*
 /// (director-verified on the ref, 2026-07-18; decisions 0499+0505). A plain slide against the
 /// top-cap plane leaves only `cos(pitch)·speed` — ~0 at a steep aim — pinning the swimmer
-/// under the waterline (the "invisible wall"), and per the §5 that grind IS what the exe's
+/// under the waterline (the "invisible wall"), and that grind IS what the exe's
 /// own-input resolver computes (`0x634640`) — contradicting the confirmed ref behavior, so
 /// this redirect stands as benilla's own construction (the 0505 named divergence). The
 /// stroke's SPEED is preserved: the upward component is clamped to `cap` (how much rise
@@ -363,7 +358,7 @@ pub(super) fn rest_line(player: &Player, surface_y: Option<f32>) -> Option<f32>
 }
 
 /// Advance the avatar one swim frame: the pitched travel velocity through the client's *floating*
-/// physics (VERIFIED, TU-B — gravity bypassed: an idle swimmer's depth is **frozen**, the vertical
+/// physics (`0x634640`, gravity bypassed: an idle swimmer's depth is **frozen**, the vertical
 /// comes only from `input_vel`), a collide-and-slide against the lakebed/banks, and the hard
 /// [`rest_cap`] line — where a rise doesn't stop dead but **redirects level into full-speed
 /// surface swimming** ([`cap_redirect`], decision 0499), and where a stroke that ends up *above*
@@ -443,7 +438,7 @@ pub(super) fn swim_step(
     //
     // Gated on a stroke, matching the resolver's own outer gate (`0x634100 test [esi+0x40],0x200f`
     // — translation or falling, never idle): an idle floater is not resolved at all, so its depth
-    // stays frozen (TU-B(c)).
+    // stays frozen.
     //
     // …and gated on **`surface_y.is_some()` — the very same rest line the cap above reads**, which
     // is the whole of B128 (decision 0882). The rest line has two arms — refuse the rise, satisfy
@@ -452,9 +447,9 @@ pub(super) fn swim_step(
     // `Some(own feet Y)` at the caller, never `None`). 0644 added this second arm *after* 0726 and
     // read the liquid straight from `surface_at` instead, so the exemption covered the cap and not
     // the settle: flying over a lake, `excess` is the entire altitude, the down-cast through open
-    // air hits nothing, and one frame teleports the avatar onto the waterline. That is both
-    // reporters' wording exactly — "from any height", and "*when moving* from land to water", the
-    // `input_vel != ZERO` gate right here.
+    // air hits nothing, and one frame teleports the avatar onto the waterline. That is the symptom
+    // exactly: from any height, and only when moving from land to water, the `input_vel != ZERO`
+    // gate right here.
     if surface_y.is_some() && input_vel != Vec3::ZERO {
         if let Some(surface_now) = surface_at(c - half_h) {
             let excess = settle_to_rest(c.y - half_h.y, surface_now, player.collision_height.0);
@@ -533,7 +528,7 @@ pub(super) fn drive_step(
     // Whether the water owns our vertical at all this frame, and where its line sits — the
     // one source both arms of the constraint read ([`rest_line`]; `None` is GM flight).
     let rest_line = rest_line(player, surface_y);
-    // Directional swim speed — **VERIFIED** (`0x7c4c90`'s swim arm, the §5's TU-H):
+    // Directional swim speed (`0x7c4c90`'s swim arm):
     // forward or strafe-only → swim; the backward bit `0x2` → `min(swimBack, swim)` —
     // byte-identical in template to the run arm's `min(runBack, run)`. Vanilla defaults
     // 4.722/2.5 (vmangos `baseMoveSpeed`).
@@ -549,7 +544,7 @@ pub(super) fn drive_step(
     // The stroke's playback-rate numerator is the FLAG-scalar speed — the full
     // directional speed regardless of pitch, 0 with no translation input — never a
     // horizontal projection, which would starve a pitched stroke toward a freeze.
-    // **VERIFIED** (TU-I): `0x5fe2f0` divides GetCurrentSpeed (flags + static speed
+    // `0x5fe2f0` divides GetCurrentSpeed (flags + static speed
     // fields only) by the clip's moveSpeed, the same path for local and observed units.
     player.swim_stroke_speed = if dir3 == Vec3::ZERO { 0.0 } else { dir_speed };
     let out = swim_step(
@@ -706,7 +701,7 @@ mod tests {
 
     /// Swim mode latches with the verified 1/36-yd hysteresis: enter is a strict `depth > 0.75·h`, leave
     /// is `depth < 0.75·h − 1/36`, so a depth inside the band holds whatever state we were in — wading
-    /// the boundary can't flicker the physics regime frame to frame (wow-re swim-transition `0x6030c0`).
+    /// the boundary can't flicker the physics regime frame to frame (`0x6030c0`).
     #[test]
     fn swim_entry_and_exit_hysteresis() {
         // The band is exactly 1/36 yd, independent of height — so it holds at every race's line.
diff --git a/crates/benilla-app/src/player/walk.rs b/crates/benilla-app/src/player/walk.rs
index 2622f545..fe2a6e58 100644
--- a/crates/benilla-app/src/player/walk.rs
+++ b/crates/benilla-app/src/player/walk.rs
@@ -6,8 +6,7 @@
 //! `0x100` out onto every packet, the speed cascade ([`crate::net::current_speed`]) turns it into
 //! `min(MOVE_WALK, MOVE_RUN)`, and the animation selector needs nothing at all — it picks Walk(4)
 //! over Run(5) purely on `speed > 2 × walkSpeed`, so a correct speed *is* the correct clip and a
-//! correct playback rate (wow-re `rf57-movement-anim-select.md`: "Walk-vs-run is SPEED-driven,
-//! NOT the WALK-mode bit").
+//! correct playback rate (`0x5fd224`: walk-vs-run is speed-driven, not the walk-mode bit).
 //!
 //! **The one thing the toggle owns that the differ does not**: nothing else in the client would
 //! ever announce this. The reference's own move-state broadcaster gates every send on the
@@ -41,16 +40,15 @@ use super::{BodyQuery, Player};
 /// so a corpse run may be walked, and the corpse it is running to may not toggle anything.
 ///
 /// The spline gate reads the other way round from how it looks: bit `0x4` of the spline flags is
-/// the **finalize / `MOVE_SPLINE_DONE` latch** (wow-re `rf57-movement-anim-select.md`, the FLY
-/// gate's `(flags & 0x204) == 0x200`), so "the latch must be set" means *the spline is finished* —
+/// the **finalize / `MOVE_SPLINE_DONE` latch** (`0x619de0` sets it; the FLY gate reads
+/// `(flags & 0x204) == 0x200`), so "the latch must be set" means *the spline is finished* —
 /// i.e. **a mover on a live server spline is refused**. Ours is [`Player::server_riding`]: the
 /// taxi flight and the charge/knock hand-offs are the states where a spline is actually flying.
 ///
 /// `0x1200` is two bits and only one of them is settled: `0x1000` is `MOVEFLAG_ROOT`
-/// (VERIFIED — `SetRoot 0x7c7340` writes it, wow-re `moveflag-family.md`), and `0x200` is a bit
-/// benilla does not model at all. The same pair gates the autorun emitter `0x514560`, where
-/// [`super::input`] records the identical caveat, and a wow-re §5 is pinning it; until it lands
-/// the modelled half is the whole of what we can refuse on.
+/// (`SetRoot 0x7c7340` writes it), and `0x200` is a bit benilla does not model at all. The same
+/// pair gates the autorun emitter `0x514560`, where [`super::input`] records the identical caveat;
+/// until `0x200` is identified, the modelled half is the whole of what we can refuse on.
 pub(super) fn toggle_refused(dead: bool, rooted: bool, on_spline: bool) -> bool {
     dead || rooted || on_spline
 }
diff --git a/crates/benilla-app/src/player/wire_in.rs b/crates/benilla-app/src/player/wire_in.rs
index efe10d09..8d4c7678 100644
--- a/crates/benilla-app/src/player/wire_in.rs
+++ b/crates/benilla-app/src/player/wire_in.rs
@@ -72,6 +72,9 @@ enum ControlVerdict {
 ///
 /// Skipped while a server-authored spline owns the body: the reference returns early on that edge
 /// (`0x619d50`), and vmangos would discard it anyway (`HasPendingSplineDone`).
+/// The pitch a login opens at when no saved camera pose names one.
+const LOGIN_PITCH: f32 = -0.45;
+
 fn yield_own_body(net_cmds: &NetCommands, player: &mut Player, self_guid: Option<u64>) {
     movement_net::park_mover(&net_cmds.0, player);
     let Some(me) = self_guid else { return };
@@ -299,25 +302,9 @@ pub(super) fn apply_server_moves(
     // Same-map teleport (the bridge only emits ours). Snap + echo the ack — without it the server
     // freezes our movement until relog.
     for t in teleports.read() {
-        player.pos = wow_to_bevy(t.position);
-        player.face_yaw = t.orientation;
-        cam.yaw = t.orientation;
-        // Stop any in-progress walk — server now sees us at the new spot.
-        player.move_flags = 0;
-        player.airborne_since = None; // a snap ends any in-progress jump arc (no phantom FALL_LAND)
-        player.settling = true; // hold (gravity off) until the destination's ground/buildings load
-        player.settle_since = time.elapsed_secs();
-        player.settle_deadline = time.elapsed_secs() + SETTLE_TIMEOUT;
-        // A far same-map teleport relocates us over ground that has not streamed either — the
-        // tiles we were standing on are still the resident ones. See [`Player::world_stale`].
-        player.world_stale = true;
-        // The relocation voids any in-progress self server-ride (the taxi flight-end teleport
-        // beats our own spline end by ~latency): `drive_self_ride` takes this flag next frame
-        // and drops the ride instead of mirroring the stale flight pose back over this snap
-        // (decision 0501 — the 4-yd hover + full-6s settle at every taxi landing).
-        player.ride_abort = true;
+        snap_near_teleport(player, &mut cam.yaw, t, time.elapsed_secs());
         // The echo goes now, and it is the WHOLE near-teleport handshake (decision 1340). The
-        // real client echoes on the very next movement tick (wow-re: the 0xC7 drain applies the
+        // real client echoes on the very next movement tick (the 0xC7 drain applies the
         // snap, then `0x60e0a0` sends guid+counter+time) and sends nothing else — no
         // `MSG_MOVE_STOP` exists anywhere in its chain. vmangos holds us at the OLD position
         // until the echo lands; processing it runs the full relocation + visibility refresh
@@ -468,7 +455,7 @@ pub(super) fn apply_server_moves(
                                            // orientation on a fresh login) — adopt it whole, camera seated behind, like
                                            // the reference. Zeroing here made every login face due north regardless.
                 cam.yaw = yaw;
-                cam.pitch = -0.45;
+                cam.pitch = player.login_pitch.unwrap_or(LOGIN_PITCH);
             }
             // The camera is deliberately NOT re-seated on a mover change: it is already on the new
             // body (Mind Control sets `PLAYER_FARSIGHT` to the victim alongside the handoff, so
@@ -523,6 +510,34 @@ pub(super) fn apply_server_moves(
     speed_acks
 }
 
+/// **Apply one same-map teleport's snap** (`MSG_MOVE_TELEPORT_ACK` inbound) — everything but the
+/// echo, which the caller sends. `cam_yaw` is the fly-cam's yaw, carried to the new facing.
+fn snap_near_teleport(player: &mut Player, cam_yaw: &mut f32, t: &TeleportMessage, now: f32) {
+    // A near teleport always arrives detached: vmangos takes this path only with no `m_transport`
+    // (`Player::TeleportTo`, after `RemovePassenger`), and the reference's apply (`0x6186b0`)
+    // re-parents to the packet's transport guid — zero here. A ride left standing let this same
+    // frame's `ride::carry` compose the old deck pose back over the snap, and the airborne settle
+    // kept it attached, so a hearth from a zeppelin or a lift landed us back on the deck.
+    player.ride = None;
+    player.pos = wow_to_bevy(t.position);
+    player.face_yaw = t.orientation;
+    *cam_yaw = t.orientation;
+    // Stop any in-progress walk — server now sees us at the new spot.
+    player.move_flags = 0;
+    player.airborne_since = None; // a snap ends any in-progress jump arc (no phantom FALL_LAND)
+    player.settling = true; // hold (gravity off) until the destination's ground/buildings load
+    player.settle_since = now;
+    player.settle_deadline = now + SETTLE_TIMEOUT;
+    // A far same-map teleport relocates us over ground that has not streamed either — the tiles we
+    // were standing on are still the resident ones. See [`Player::world_stale`].
+    player.world_stale = true;
+    // The relocation voids any in-progress self server-ride (the taxi flight-end teleport beats our
+    // own spline end by ~latency): `drive_self_ride` takes this flag next frame and drops the ride
+    // instead of mirroring the stale flight pose back over this snap (decision 0501 — the 4-yd
+    // hover + full-6s settle at every taxi landing).
+    player.ride_abort = true;
+}
+
 /// Merge a server-authored packet's `MOVEMENTFLAGS` into our own — the reference's masked merge
 /// (`0x618c30 @0x618deb`: `new = old ^ ((old ^ wire) & 0x75a07dff)`), not an assignment. Pure, so
 /// the omission that actually bites is pinned by test: `ON_TRANSPORT` sits **outside** the mask, so
@@ -533,7 +548,7 @@ pub(super) fn merge_server_flags(local: u32, wire: u32) -> u32 {
 }
 
 /// Apply one bare self-addressed `MSG_MOVE_*` — a pose the *server* wrote for our own mover, with
-/// no handshake (decision 0725; wow-re `self-addressed-move.md`). `.go forward`/`up`/`relative`,
+/// no handshake (decision 0725). `.go forward`/`up`/`relative`,
 /// `.cheat fly`/`fixedz` and the movement anticheat's snap-back all land here.
 ///
 /// **A hard snap, and nothing goes back.** The reference writes the wire pose into both its live
@@ -579,8 +594,8 @@ fn apply_self_move(
     // bit parked there alone would be gone before the mover ever read it; the modes live as fields,
     // the way `rooted` does. The reference needs no such step — it has one `[cmov+0x40]` that is both
     // the state and the wire word — and it has the matching apply anyway: the same inbound merge also
-    // runs `0x61a1af → 0x61a230 → SetSwim` (wow-re `swim-transition.md`, "the local unit's server
-    // echo"). This pair is GM flight: `.cheat fly` sends SWIMMING + LEVITATING together.
+    // runs `0x61a1af → 0x61a230 → SetSwim`, the local unit's server echo included. This pair is
+    // GM flight: `.cheat fly` sends SWIMMING + LEVITATING together.
     player.swimming = player.move_flags & move_flags::SWIMMING != 0;
     // …and the walk gait rides out on the same lift (decision 1752). `0x100` is inside the
     // `SERVER_AUTHORED` mask like the modes above, so a move the server authors for our mover
@@ -682,7 +697,7 @@ fn apply_self_move(
 /// controller driving nothing, which is the shape of the free camera this arc is about.
 ///
 /// **Everything on this resource belonged to the mover that just ended, so all of it dies here**
-/// (decision 1542, B306 — reported and diagnosed by Liho). It used to clear a hand-picked six
+/// (decision 1542). It used to clear a hand-picked six
 /// fields, and the field it did not name was `modes`: `/logout` has vmangos root us for the
 /// countdown (`MiscHandler.cpp` `SetRooted(true)`), we ack the grant, and the next session never
 /// hears an unroot — the fresh server-side `Player` was never rooted, so there is nothing for it
@@ -693,8 +708,8 @@ fn apply_self_move(
 /// a field added tomorrow is mover state by default, which is the safe direction.
 ///
 /// It is also what the reference does, by construction rather than by list: the server's logout
-/// confirm runs `ShutdownGame 0x491180` (wow-re `ui/scratch/lua-state-lifecycle.md` §3.3 —
-/// `0x5aaeb0` → `0x401ee0` → `0x402039`, ~35 subsystem shutdowns, the Lua VM replaced twice), so
+/// confirm runs `ShutdownGame 0x491180` (`0x5aaeb0` → `0x401ee0` → `0x402039`, ~35 subsystem
+/// shutdowns, the Lua VM replaced twice), so
 /// the real client has no per-mover state left to carry across a character-select round trip. Ours
 /// is a long-lived resource; this is where it pays that back.
 pub(super) fn release_on_session_end(
@@ -758,7 +773,7 @@ mod session_end_tests {
         p.wedged = true;
     }
 
-    /// **B306, at its own edge** (decision 1542; reported and diagnosed by Liho). `/logout` has
+    /// **B306, at its own edge** (decision 1542). `/logout` has
     /// vmangos root the player for the countdown (`MiscHandler.cpp:329 SetRooted(true)`), which
     /// reaches us as the ack'd `SMSG_FORCE_MOVE_ROOT` above; the next login gets no unroot, because
     /// server-side the fresh `Player` was never rooted (`SendInitialPacketsBeforeAddToMap` re-sends
@@ -983,3 +998,38 @@ mod control_tests {
         assert_eq!(control_verdict(ME, true, None), ControlVerdict::Granted(ME));
     }
 }
+
+#[cfg(test)]
+mod teleport_tests {
+    use super::*;
+
+    /// **A near teleport lands us where the server says, not back on the deck.** Hearthing off a
+    /// zeppelin or a lift is a same-map teleport, and vmangos removes the passenger before it
+    /// takes that path; the snap has to drop the ride too, or the same frame's platform carry
+    /// recomposes the old deck pose over it.
+    #[test]
+    fn a_near_teleport_leaves_the_transport() {
+        let mut player = Player {
+            active: true,
+            ride: Some(super::super::state::PlayerRide {
+                entity: Entity::PLACEHOLDER,
+                guid: 0x1F,
+                local_pos: Vec3::new(1.0, 0.0, 2.0),
+                boat_yaw: 0.5,
+            }),
+            ..Default::default()
+        };
+        let mut cam_yaw = 0.0;
+        let t = TeleportMessage {
+            guid: 0x45,
+            counter: 1,
+            position: [-8_913.0, -136.0, 81.0],
+            orientation: 1.25,
+        };
+        snap_near_teleport(&mut player, &mut cam_yaw, &t, 10.0);
+        assert!(player.ride.is_none(), "the snap deboards");
+        assert_eq!(player.pos, wow_to_bevy(t.position));
+        assert_eq!((player.face_yaw, cam_yaw), (1.25, 1.25));
+        assert!(player.settling && player.ride_abort && player.world_stale);
+    }
+}
diff --git a/crates/benilla-app/src/poi_marker.rs b/crates/benilla-app/src/poi_marker.rs
index c147136e..5e1d4b5f 100644
--- a/crates/benilla-app/src/poi_marker.rs
+++ b/crates/benilla-app/src/poi_marker.rs
@@ -8,18 +8,17 @@
 //!
 //! **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:
-//! `wow-5875-re` `system/ui/scratch/gossip-poi-marker.md` (the §5 for this feature, folded back as 1516) — handler
-//! `0x4e2840`, `set_blip 0x6dac10` writing static slot **1** at `0xcea7d4`, and
-//! `minimap-poi-questdot.md` §A3's candidate array, which appends the static slots
-//! *unconditionally*, bypassing the DBC scan's `ContinentID`/`Flags & 1` gate. So it is a landmark
+//! 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 lifetime is four ways to lose it, whichever comes first** (all VERIFIED, §5):
+//! **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).
@@ -45,9 +44,8 @@ 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.
 const ARRIVE_CLEAR_YD_SQ: f32 = 100.0;
-/// How long a set of directions lasts before it drops itself: `time() + 480` **seconds**, VERIFIED
-/// (`set_blip 0x6dac10`'s deadline stamp; the §5 corrected the unit — 480 ms would be a marker you
-/// could never walk to).
+/// 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).
 const MARKER_TTL_SECS: f64 = 480.0;
 
 /// The one point of interest a guard's directions left on the map — a synthetic `AreaPOI` record,
@@ -79,8 +77,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` — the §5's P4 correction (1516); we had guessed a constant
-            // `0`). Shipped server data sends `0` in every row, which lands the marker in the
+            // 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.
             importance: wire.data,
@@ -138,11 +136,57 @@ 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>,
+    current_map: Option<Res<benilla_world::world_map::CurrentMap>>,
+    real_clock: Res<Time<Real>>,
+) {
+    if let benilla_protocol::SessionEvent::GossipPoi(poi) = ev {
+        gossip_poi(
+            &poi,
+            &mut marker,
+            current_map.as_ref().map_or(0, |m| m.0),
+            real_clock.elapsed_secs_f64(),
+        );
+    }
+}
+
+/// 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).
+fn gossip_poi(
+    poi: &benilla_protocol::messages::GossipPoi,
+    marker: &mut PoiMarker,
+    map_id: u32,
+    now_secs: f64,
+) {
+    debug!(
+        "net: directions to \"{}\" at ({:.1}, {:.1}) — icon {}, flags {:#x}",
+        poi.name, poi.pos[0], poi.pos[1], poi.icon, poi.flags
+    );
+    marker.set(poi, map_id, now_secs);
+}
+
 /// The guard's directions marker — see the module doc.
 pub(crate) struct PoiMarkerPlugin;
 
 impl Plugin for PoiMarkerPlugin {
     fn build(&self, app: &mut App) {
+        {
+            use crate::net::NetHandlerApp;
+            use benilla_protocol::SessionEventKind as K;
+            app.net_handler(K::GossipPoi, on_gossip_poi);
+        }
         app.init_resource::<PoiMarker>()
             .add_systems(Update, (expire_marker, clear_on_world_entry));
     }
@@ -192,7 +236,7 @@ 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 (§5 P4).
+    /// 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);
@@ -215,8 +259,8 @@ mod tests {
         assert_eq!(m.expires_at, 100.0 + MARKER_TTL_SECS);
     }
 
-    /// The deadline is 480 **seconds** — long enough to walk across a capital, which is the whole
-    /// point of the §5's unit correction.
+    /// 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();
diff --git a/crates/benilla-app/src/portrait/booth.rs b/crates/benilla-app/src/portrait/booth.rs
index 22c5f472..ca1dcc3b 100644
--- a/crates/benilla-app/src/portrait/booth.rs
+++ b/crates/benilla-app/src/portrait/booth.rs
@@ -1,7 +1,7 @@
 //! The booth **bake spawn** — how a mirrored look becomes the posed throwaway instance the
-//! camera shoots (the ref mechanism, wow-re portrait-render §4 D2). [`spawn_booth_model`] is the
-//! whole surface; the sync systems in [`super`] build [`BoothPart`]/[`BoothRider`] lists from the
-//! unit's mirrored children and hand them here.
+//! camera shoots (the ref mechanism: instance `0x707400`, pose `0x7121a0`). [`spawn_booth_model`]
+//! is the whole surface; the sync systems in [`super`] build [`BoothPart`]/[`BoothRider`] lists
+//! from the unit's mirrored children and hand them here.
 //!
 //! Since decision 1443 the bake rides the **collapsed rig lane** (0724/1365): the skeleton is a
 //! [`RigPose`](benilla_world::rig_anim::RigPose) buffer on the booth root — no joint entities,
@@ -47,8 +47,8 @@ pub(super) struct BoothPart {
     /// `false` for every booth but the **glue create / main-menu scene**. A portrait or
     /// dressing-room bake is a still by design (0130's bake law — it photographs one instant);
     /// the create screen is a live render, and the reference animates a texture transform inside
-    /// the per-model-per-frame animate kernel (`0x715f25`-`0x7163bc` over `md+0x74`, wow-re
-    /// `modelframe-texanim-and-sequence-law.md` §3.1), which is not a lane a host opts into.
+    /// the per-model-per-frame animate kernel (`0x715f25`-`0x7163bc` over `md+0x74`), which is not
+    /// a lane a host opts into.
     pub(super) mat_anim: bool,
 }
 
@@ -150,8 +150,8 @@ impl BoothInstance {
 ///
 /// Being out of that query means being out of **both** halves of what it does, and the booth owes
 /// its parts both: the alpha field *and* the `mat_factor > 0.0` term in its `desired` verdict — the
-/// reference's `A <= 0` cull, which fires before the blend mode is ever read (wow-re
-/// `m2-alpha-combine-cull.md`). Marking the marker is therefore also a claim of sole `Visibility`
+/// reference's `A <= 0` cull, which fires before the blend mode is ever read
+/// (`0x707b3a`–`0x707b5c`). Marking the marker is therefore also a claim of sole `Visibility`
 /// authority over the parts that carry it; nothing else in the booth writes theirs.
 #[derive(Component)]
 pub(super) struct BoothMatAlpha;
@@ -205,8 +205,8 @@ impl BoothBillboard {
     /// — not a second mechanism. Today's caller is the glue booth's equipment riders
     /// ([`super::glue_booth`]): an item model spawns no rig, so nothing else would apply the
     /// replacement to a particle emitter hanging under its billboard bone, and the reference folds
-    /// the emitter's record position through exactly this matrix (wow-re
-    /// `part-anchoring-live-bone.md` §1 row 3).
+    /// the emitter's record position through exactly this matrix (`0x7190a9`–`0x71910c`, in
+    /// `0x718960`).
     ///
     /// The caller owns the frame's **translation** (the billboard bone's pivot in its parent's
     /// frame); [`face_booth_billboards`] writes only the rotation.
@@ -222,7 +222,7 @@ impl BoothBillboard {
 ///
 /// The two lanes that feed it are the two lanes that mirror a dressed look — a live unit's
 /// [`crate::portrait::PortraitEffects`] markers, and the glue bake's [`super::PreviewEffects`] —
-/// and both mean the same two things: an equipped item's own emitters (decision 0813, `#bugs` B118)
+/// and both mean the same two things: an equipped item's own emitters (decision 0813)
 /// and the `ItemVisuals` glow a held weapon hangs on its own attachment points (decision 0805).
 pub(super) struct BoothEffects {
     pub(super) bone: u16,
@@ -308,7 +308,7 @@ pub(super) fn clear_booth_rig(commands: &mut Commands, root: Entity) {
 /// stages every frame (`0x76d680`, decision 0638) — the same widget family as the animating glue
 /// preview (decision 0423). The round unit-frame portraits are not: `SetPortraitTexture` bakes a
 /// fresh instance in ONE draw and caches the texture by GUID/displayId, returning it with no
-/// re-render (wow-re `portrait-render.md` §2). A one-frame draw of a freshly-born particle pool
+/// re-render (`0x524f60`). A one-frame draw of a freshly-born particle pool
 /// yields nothing, so emitters have no place in a portrait — and a booth that owns emitters must
 /// keep its camera awake ([`crate::portrait::Booth::live`]), which is exactly what a still should
 /// never need to do.
@@ -507,8 +507,9 @@ pub(super) enum BoothMotion {
     Loop,
 }
 
-/// Spawn a booth bake under `root` on the booth's layer — the ref mechanism (wow-re §4 D2): a
-/// **fresh throwaway instance posed at Stand**, never the unit's live world pose.
+/// Spawn a booth bake under `root` on the booth's layer — the ref mechanism (instance `0x707400`,
+/// pose `0x7121a0`): a **fresh throwaway instance posed at Stand**, never the unit's live world
+/// pose.
 ///
 /// With a rig (skeleton + inverse bindposes; every M2 display), the booth builds a collapsed
 /// [`RigPose`](benilla_world::rig_anim::RigPose) buffer (decision 1443 — no joint entities),
@@ -516,10 +517,9 @@ pub(super) enum BoothMotion {
 /// anchor, and arms the model's own Stand (anim id 0 through its baked resolution — the ref's
 /// loader-idle seed): `motion` decides whether that Stand is **frozen at t = 0** (a portrait
 /// still) or **looping** (the live glue scenes/preview — decisions 0423 + 0539). (The ref's own
-/// sampling clock is the one unsettled INFERRED point of the verdict — t≈0 vs live phase; a
-/// frozen t=0 is inside its envelope either way.) Without a rig (boneless / WMO-display / rig
-/// not built), the static bind-pose bake: parts at identity, riders dropped (no bones to seat
-/// them on).
+/// sampling clock is the one unsettled, inferred point — t≈0 vs live phase; a frozen t=0 is
+/// inside its envelope either way.) Without a rig (boneless / WMO-display / rig not built), the
+/// static bind-pose bake: parts at identity, riders dropped (no bones to seat them on).
 ///
 /// Returns the [`BoothRig`] handle — seat any remaining consumers on it (the effect hosts, the
 /// glue scene's emitters), then `finish()` it.
@@ -538,7 +538,7 @@ pub(super) fn spawn_booth_model(
     catalog: Option<&benilla_formats::AnimDataCatalog>,
     motion: BoothMotion,
     // Per-hand weapon grip `[right, left]` — hold that hand's `HandsClosed` finger pose because a weapon
-    // occupies its attach point (the paperdoll rule, wow-re `hand-grip-mechanism.md` §4c). The glue
+    // occupies its attach point (the paperdoll rule, `0x5059a0`). The glue
     // preview and the body panes both resolve it from **attachment occupancy**, which is the whole
     // rule (`crate::portrait::hand_grip`); the round portraits pass `[false, false]` because the
     // reference's portrait bake never arms a grip at all, not because they sheath anything.
@@ -823,7 +823,7 @@ const SHUFFLE_LEFT: u16 = 11;
 const SHUFFLE_RIGHT: u16 = 12;
 
 /// **Which sequence a facing change arms** — the reference's own direction test, stated once
-/// (`0x505bb0`, wow-re `modelframe-camera-law.md` **§13**).
+/// (`0x505bb0`).
 ///
 /// The `fcomp` at `0x505bce` compares the **current** facing (in ST(0)) against the argument, and
 /// the two branches read out as: current **<** angle ⇒ `0xc` **ShuffleRight**, current **>** angle
@@ -831,9 +831,8 @@ const SHUFFLE_RIGHT: u16 = 12;
 /// that is an *active* play, not a no-op: it is why `Model:SetSequence` cannot stick on one of
 /// these panes.
 ///
-/// **§6's prose had this pair inverted**, and this port was built on it before wow-re's §13
-/// re-derived the compare instruction by instruction. The direction was wrong in exactly the way
-/// nothing local can catch — the doll still stepped, just into its turn instead of with it.
+/// **This port was first built with this pair inverted.** The direction was wrong in exactly the
+/// way nothing local can catch — the doll still stepped, just into its turn instead of with it.
 ///
 /// It runs on the **Lua-facing scalar** — the very value the reference hands `SetRotation` — so
 /// the branch transfers with no sign work, and no reasoning about which way a Bevy `+Y` spin goes
@@ -853,7 +852,7 @@ pub(super) fn turn_shuffle(faced: f32, angle: f32) -> u16 {
 /// timer.
 ///
 /// The arm is **unconditional** — every one of `0x505bb0`'s three early exits jumps to `0x505c28`,
-/// where the flag and the deadline are written, so no path through it skips them (wow-re §13.1).
+/// where the flag and the deadline are written, so no path through it skips them.
 /// A held rotate arrow rewrites the facing every frame (the pane's `OnUpdate`,
 /// `ROTATIONS_PER_SECOND`), so the deadline is pushed forward every frame and the doll steps
 /// continuously until the button comes up. Taking `spun` before the expiry check below reproduces
@@ -870,8 +869,8 @@ fn fade_frac(fade: &super::Fade, now: f64) -> f32 {
 }
 
 /// Arm one `AnimationData` id on a booth root the way the reference's turn does — every one of its
-/// plays is `0x7121a0(bone -1, id, variation -1, offset 0, rate 1.0f, blend 1, primary 1)`
-/// (wow-re `modelframe-camera-law.md` §13.4), and all three of those trailing arguments show:
+/// plays is `0x7121a0(bone -1, id, variation -1, offset 0, rate 1.0f, blend 1, primary 1)`, and
+/// all three of those trailing arguments show:
 ///
 /// - **variation `-1`** — a freshly *rolled* frequency-weighted variation, not the head. HumanMale
 ///   authors four Stands (frequencies 14199 / 2184 / 2184 / 14199), and the reference re-rolls on
@@ -1059,7 +1058,7 @@ fn step_turn(
                 *until = now + SHUFFLE_HOLD_SECS;
             }
         } else if arm_turn(player, anims, catalog, rng, turn, want, now) {
-            // Equal facings — and NaN — arm Stand outright (wow-re §13.2), which is an *active*
+            // Equal facings — and NaN — arm Stand outright (`0x505c23`), which is an *active*
             // play, not a no-op; nothing is stepping after it, so it schedules no expiry.
             turn.shuffle = (want != STAND).then_some((want, now + SHUFFLE_HOLD_SECS));
         }
@@ -1252,7 +1251,7 @@ mod tests {
 
     /// The `A <= 0` cull — the half the booth twin was missing, and the reason the Voidwalker
     /// stood in the char-select booth with two shoulder props hung in the air. The reference culls
-    /// the batch before it reads the blend mode (wow-re `m2-alpha-combine-cull.md`), and the world
+    /// the batch before it reads the blend mode (`0x707b3a`–`0x707b5c`), and the world
     /// lane says so as `mat_factor > 0.0` in its `desired` verdict
     /// (`model_render::visibility`); a tag write alone cannot express it, because an Opaque draw
     /// never looks at the blend source the tag alpha feeds. Both directions, in one run: a zeroed
@@ -1301,7 +1300,7 @@ mod tests {
     }
 
     /// **The booth twin of the equipped-item emitter's billboard frame** (decision 0813, carried to
-    /// the select screen for `#bugs` B118). Same real numbers as
+    /// the select screen). Same real numbers as
     /// `billboard::tests::an_item_emitters_billboard_frame_puts_it_behind_the_pivot`
     /// (`LShoulder_Mail_PVPAlliance_C_01`: billboard bone 1 pivot `(-0.012, 0.162, -0.060)`, sparkle
     /// emitter `(-0.252, 0.178, -0.046)`, raw WoW model space), but through THIS system — and here the
@@ -1555,11 +1554,10 @@ mod tests {
     }
 
     /// **The rotate arrows arm the shuffle the model turns toward** (1559, B313), and the pair is
-    /// the one wow-re §13.2 read off the `fcomp` at `0x505bce` — *not* the pair §6's prose
-    /// carried, which was inverted and which this port was first built on. Current facing **<**
-    /// the new angle ⇒ `0xc` ShuffleRight; **>** ⇒ `0xb` ShuffleLeft; equal (and NaN, which the
-    /// compare's unordered flags send the same way) ⇒ `0` Stand, an active arm rather than a
-    /// no-op.
+    /// the one read off the `fcomp` at `0x505bce` — *not* the inverted pair this port was first
+    /// built on. Current facing **<** the new angle ⇒ `0xc` ShuffleRight; **>** ⇒ `0xb`
+    /// ShuffleLeft; equal (and NaN, which the compare's unordered flags send the same way) ⇒ `0`
+    /// Stand, an active arm rather than a no-op.
     ///
     /// The pane's own Lua is what makes the mapping checkable end to end, and it is why an
     /// inversion cannot be caught by reading either side alone: the reference uses **opposite
diff --git a/crates/benilla-app/src/portrait/dressup.rs b/crates/benilla-app/src/portrait/dressup.rs
index 8969dc05..8369898f 100644
--- a/crates/benilla-app/src/portrait/dressup.rs
+++ b/crates/benilla-app/src/portrait/dressup.rs
@@ -12,7 +12,7 @@
 //!
 //! The spec's equipment is the player's own visible items with the tried-on ones substituted in
 //! ([`crate::ui_dressup`] composes it). One consequence worth naming: the preview dresses by the
-//! **select-screen** law (weapons drawn in the hands, wow-re `glue-select-model.md`), not by the
+//! **select-screen** law (weapons drawn in the hands, `0x47a0c0`), not by the
 //! world's sheath state — the reference's `DressUpModel` is a `<PlayerModel>` subclass showing the
 //! character posed for inspection, and that is the pose the shared assembly produces.
 //!
@@ -183,7 +183,7 @@ pub(super) fn spawn_dressup_booth(
 /// fresh instance, seat the riders and effects, frame it full-body, arm the wake window. What
 /// differs from the paper doll is only where the parts come from (a bake resource, not a live
 /// unit's children) and the hand grip — the assembly holds the weapons, so the hands close on them
-/// (wow-re `hand-grip-mechanism.md`).
+/// (`CloseHand 0x479660`).
 pub(super) fn sync_dressup_booth(
     mut commands: Commands,
     preview: Res<DressUpPreview>,
diff --git a/crates/benilla-app/src/portrait/framing.rs b/crates/benilla-app/src/portrait/framing.rs
index 37a6acf6..1162ece2 100644
--- a/crates/benilla-app/src/portrait/framing.rs
+++ b/crates/benilla-app/src/portrait/framing.rs
@@ -3,11 +3,11 @@
 //! Both booth families frame through the model's **own authored camera**, and neither fits anything
 //! (the mechanism — see the module docs in [`super`]):
 //!
-//! - [`frame`] — a ROUND portrait: `cameraLookup[0]`, verbatim (wow-re portrait-render §4). Its
+//! - [`frame`] — a ROUND portrait: `cameraLookup[0]`, verbatim (`0x713540`). Its
 //!   fallback for a camera-less model is a heuristic head closeup, anchored by the bind-pose bone
 //!   walk [`head_anchor`] (which the posed booth also uses to seat riders on real joints).
 //! - [`body_frame`] — a `<PlayerModel>` body PANE: raw `cameras[1]`, verbatim, else the client's own
-//!   synthesized *fixed* rig (wow-re `modelframe-camera-law.md`, decision 1089). No fit, no
+//!   synthesized *fixed* rig (`0x505890`, decision 1089). No fit, no
 //!   normalization, no bone anchor anywhere on this path.
 
 use bevy::camera::{CameraProjection, PerspectiveProjection, Projection, SubCameraView};
@@ -49,7 +49,7 @@ pub(super) fn diag_to_vert(fov: f32, aspect: f32) -> f32 {
 /// The **authored aspect** of every 1.12 glue composition: `4/3`.
 ///
 /// It is the client's own reference frame, not a guess. The Lua screen is `768a × 768`
-/// (wow-re `ui/scratch/modelframe-camera-law.md` §12.1), so at the era's default `a = 4/3` the
+/// (`GetScreenWidth 0x48b480`, `GetScreenHeight 0x48b4d0`), so at the era's default `a = 4/3` the
 /// design space is exactly `1024×768` — the resolution every `UI_<Race>` diorama and its camera-0
 /// framing were authored against. One definition, in the crate that also measures the art
 /// against it ([`benilla_formats::glue_art_extent`]).
@@ -59,7 +59,7 @@ pub(super) use benilla_formats::{ArtExtent, GLUE_AUTHORED_ASPECT};
 ///
 /// The reference law and why we do not ship it: a glue screen's `<ModelFFX>` is `setAllPoints` to
 /// `GlueParent`, which is `setAllPoints` to the screen, so the pane rect *is* the window and
-/// `0x5c3cc0`'s single `aspect` is the display's own (wow-re §12.1: `aspect = (W/H)·(a/a_screen)`,
+/// `0x5c3cc0`'s single `aspect` is the display's own (`0x76d42d`: `aspect = (W/H)·(a/a_screen)`,
 /// which is `a` for a full-screen pane — the `gxResolution`/`widescreen` CVar pair, normally the
 /// live mode). Feeding that straight into [`diag_to_vert`] makes the *diagonal* angle the invariant,
 /// so every pixel of extra width is paid for out of height: `0.600·fov` at 4:3, `0.492·fov` at 16:9,
@@ -326,7 +326,7 @@ impl CameraProjection for WowPortraitProjection {
 
 /// The framing the entities cache hands the booth for a display id
 /// ([`Creatures::display_anchors`]). All **model-local at scale 1** (the ref bakes with root scale
-/// reset, RE `0x47a230`), matching the booth's identity-transform parts.
+/// reset, `0x47a230`), matching the booth's identity-transform parts.
 pub(crate) struct PortraitAnchors {
     /// The model's **authored portrait camera** — the real client's exact framing rig for a ROUND
     /// portrait (`cameraLookup[0]`, module docs). `None` for a camera-less model → the heuristic
@@ -465,7 +465,7 @@ pub(super) fn frame(a: &PortraitAnchors) -> (Transform, Projection) {
 ///
 /// `a` is the **`gxResolution` CVar's width/height**, gated by the `widescreen` CVar (registered at
 /// `0x63a74f` with default `"1"` — on by default); with `widescreen = 0` the client uses `4/3` on
-/// any monitor. (wow-re `ui/scratch/modelframe-camera-law.md` §11.)
+/// any monitor (`0x46ab40`).
 ///
 /// **It applies to exactly one path, and this is the subtle part.** The widget's model root is
 /// `T(pos)·R(facing)·S(s)`, and `0x71439b` composes the *camera's* publish through that same root
@@ -482,9 +482,9 @@ pub(super) fn pane_model_scale(display_aspect: f32) -> f32 {
 }
 
 /// The client's **synthesized fallback camera** for a model frame whose model carries fewer than two
-/// cameras — a *fixed* rig, not a fit (wow-re `ui/scratch/modelframe-camera-law.md`, VERIFIED
-/// `0x505890`): eye at a constant point in WoW model space, look-at the MD20 header bbox centre, and
-/// its own fov/near/far. The only model-derived quantity anywhere in it is the target.
+/// cameras — a *fixed* rig, not a fit (`0x505890`): eye at a constant point in WoW model space,
+/// look-at the MD20 header bbox centre, and its own fov/near/far. The only model-derived quantity
+/// anywhere in it is the target.
 ///
 /// A small model therefore renders *small* in the pane and a large one overflows it — there is no
 /// normalization step. Both of the numbers here are literals in the binary.
@@ -499,7 +499,7 @@ const PANE_FIXED_NEAR: f32 = 1.0 / 36.0;
 const PANE_FIXED_FAR: f32 = 5000.0;
 
 /// The **body pane** booth camera rig — a 1.12 `<PlayerModel>` widget's own camera, verbatim
-/// (decision 1089; wow-re `ui/scratch/modelframe-camera-law.md`).
+/// (decision 1089; `0x505890`).
 ///
 /// **There is no fit.** The widget renders through a frozen snapshot of the model's *authored*
 /// camera at **raw table index 1** — the `type == 1` "characterinfo" camera — and when the model has
@@ -567,13 +567,13 @@ pub(super) fn pane_camera(a: &PortraitAnchors) -> benilla_assets::PortraitCamera
 /// squeeze and the diagonal→vertical crop, because the client renders straight into the pane rect.
 /// See [`WowPortraitProjection::aspect`].
 ///
-/// **1543's cancellation does NOT reach here, and this was checked, not assumed** (wow-re
-/// `bcd1f2c2`, a §5 round run blind to decision 1089). Both paths build through the same
-/// `0x7ada40`/`0x7ac640`, so the question is only what each caller puts in the aspect rect: the
-/// *bake* constructs `{0, 0, 1.0, D}` whose only size terms are its fixed 64/64, which is why its
-/// screen terms cancel to `1.0`; the *widget* (`0x76d42d`) hands over the frame's **raw cached
-/// layout rect** verbatim (`0x768320`, a 4-dword copy of `[layoutFrame+0x40]`), so the same
-/// cancellation removes only the screen terms and the pane's own shape survives —
+/// **1543's cancellation does NOT reach here, and this was checked, not assumed.** Both paths
+/// build through the same `0x7ada40`/`0x7ac640`, so the question is only what each caller puts in
+/// the aspect rect: the *bake* constructs `{0, 0, 1.0, D}` whose only size terms are its fixed
+/// 64/64, which is why its screen terms cancel to `1.0`; the *widget* (`0x76d42d`) hands over the
+/// frame's **raw cached layout rect** verbatim (`0x768320`, a 4-dword copy of
+/// `[layoutFrame+0x40]`), so the same cancellation removes only the screen terms and the pane's
+/// own shape survives —
 /// `aspect = (W/H)·(a/a_screen)` = `W/H` whenever the configured and actual display aspects agree,
 /// which 1543's `widescreen` census showed is every state the client can reach. The `0x41ade0`
 /// unscales on this path (`0x76d45b`/`0x76d46e`) run *after* the camera build and serve the
@@ -609,7 +609,8 @@ mod tests {
         ndc(transform, proj, p).y
     }
 
-    /// The M2 `cameras[1]` records the RE reports, in Bevy space — `wow_to_bevy` is `(-y, z, -x)`.
+    /// The M2 `cameras[1]` records measured off the shipped files, in Bevy space — `wow_to_bevy`
+    /// is `(-y, z, -x)`.
     fn cam(eye_wow: [f32; 3], target_wow: [f32; 3], fov: f32) -> benilla_assets::PortraitCamera {
         benilla_assets::PortraitCamera {
             eye: benilla_assets::coords::wow_to_bevy(eye_wow),
@@ -647,7 +648,7 @@ mod tests {
     /// derived from the model's size.
     #[test]
     fn a_pane_takes_the_models_own_camera_untouched() {
-        // HumanMale's `cameras[1]`, per the RE.
+        // HumanMale's `cameras[1]`, measured off the shipped file.
         let human = cam([3.6585, 0.0338, 0.9227], [-0.3644, 0.0291, 0.9873], 0.97991);
         for &aspect in &[1.0_f32, 318.0 / 224.0, 233.0 / 224.0, 316.0 / 351.0] {
             let (transform, projection) =
@@ -768,7 +769,7 @@ mod tests {
         );
     }
 
-    /// The **renormalize-to-4:3** model-root factor, against the values the RE reports —
+    /// The **renormalize-to-4:3** model-root factor, against the reference's values —
     /// `√((4/3)²+1)/√(a²+1)`, which is `G48·(5/3)` with `G48 = 1/√(a²+1)`.
     #[test]
     fn the_model_root_renormalizes_to_four_thirds() {
diff --git a/crates/benilla-app/src/portrait/glue_booth.rs b/crates/benilla-app/src/portrait/glue_booth.rs
index fe45ec9d..b4448ed5 100644
--- a/crates/benilla-app/src/portrait/glue_booth.rs
+++ b/crates/benilla-app/src/portrait/glue_booth.rs
@@ -47,7 +47,7 @@ const GLUE_SIZE: u32 = 1024;
 /// dials (decisions 0423 + 0527): the create body dressed in the (race, class, sex) level-1 starting
 /// outfit (CharStartOutfit), the ref's create preview. Class is load-bearing here — a different
 /// class wears different starting gear, and the ref re-applies equipment on class change
-/// (`SelectClass` → `cc_apply_sections`, wow-re `wave-preview.md`).
+/// (`SelectClass 0x470f50` → `cc_apply_sections 0x470800`).
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) struct CreateLook {
     pub(crate) race: u8,
@@ -213,9 +213,8 @@ pub(crate) struct CreateScene {
     /// roster selection moved between races.
     viewport_aspect: Option<f32>,
     /// The character's stage spot — scene attachment 0 (Bevy model space), `ZERO` with no scene.
-    /// (Verified for select too: the body seats on attachment **0**, `0x473039` — attachment 1 is
-    /// the enum's secondary model, wow-re `glue-select-model.md` TU-B; 0429's attachment-1
-    /// presumption is dead.)
+    /// (At select too: the body seats on attachment **0**, `0x473039` — attachment 1 is the
+    /// enum's secondary model, `0x47306b`; 0429's attachment-1 presumption is dead.)
     char_spot: Vec3,
     /// The stage's **authored frame** — attachment 0's bone matrix ([`stage_frame`]): the rotation
     /// and uniform scale the scene author parked on that bone. Identity/1.0 with no scene;
@@ -252,7 +251,7 @@ pub(crate) struct CreateScene {
     /// law (see [`SceneRig`]: directionals → ambient + SH probe slot 0, points → the per-vertex
     /// point table) plus the ref's per-race fog (`CharModelFogInfo`) — **create only**: at select
     /// the client overwrites the background's fog callback with the light callback, so the select
-    /// scene renders unfogged (wow-re `glue-select-model.md` TU-C, byte-verified `0x472110`) —
+    /// scene renders unfogged (`0x472110`) —
     /// rewritten on each scene swap. The character re-lights onto it too — the ref's create character is scene-lit (the
     /// NightElf/Scourge characters are lit almost entirely by stage-local point lights).
     light: Option<bevy::render::render_resource::Buffer>,
@@ -339,7 +338,7 @@ fn may_swap(standing: bool, art_ready: bool, body_ready: bool, waited: f32) -> b
 }
 
 /// A glue scene's authored M2 light rig, folded for the booth's light buffer under the
-/// byte-verified world law (wow-re `m2-dynamic-lights.md`): **directional** lights accumulate —
+/// world law (the gather `0x718960`): **directional** lights accumulate —
 /// ambient tracks summed into one ambient term, each diffuse×intensity an SH lobe with its *own*
 /// direction (the `Model2.bls` fold, [`benilla_world::lighting::prop_probe_coeffs`]) — and **point**
 /// lights become per-vertex lights on the buffer's point table, evaluated with the engine's fixed
@@ -363,9 +362,9 @@ const SCENE_POINT_RANGE: f32 = 1.0e6;
 
 /// Fold the scene model's light table into a [`SceneRig`] (see there for the law). A directional
 /// light's **to-light direction is its bone's local +Z axis** (`M2Light::bone_z` — the gather
-/// reads row 2 of the light bone's pose matrix, never the def position; byte-verified in wow-re
-/// `glue/scratch/glue-model-lighting.md §3`, on-surface to-light = `normalize(Bz·BM_rot)`); the
-/// model rotation `BM_rot` is identity here (the scene root never rotates).
+/// reads row 2 of the light bone's pose matrix at `0x718a76`, never the def position; on-surface
+/// to-light = `normalize(Bz·BM_rot)`); the model rotation `BM_rot` is identity here (the scene
+/// root never rotates).
 fn scene_rig(lights: &[benilla_assets::ModelLight]) -> SceneRig {
     let mut ambient = [0.0f32; 3];
     let mut lobes: Vec<(Vec3, [f32; 3])> = Vec::new();
@@ -377,8 +376,7 @@ fn scene_rig(lights: &[benilla_assets::ModelLight]) -> SceneRig {
         let color = l.diffuse_color.map(|c| c * l.diffuse_intensity);
         if l.is_point() {
             // `LightBlob::point` applies the same RAW commit the world table does (the `0x71ca80`
-            // encode is undone by the `0x593040` decode — wow-re
-            // trace-forensics-overgamut-point-commit-d3d): a glue scene is just another CM2Scene,
+            // encode is undone by the `0x593040` decode): a glue scene is just another CM2Scene,
             // and the GL commit is shared. One law covers both tables, not two by coincidence.
             points.push((benilla_assets::coords::wow_to_bevy(l.position), color));
         } else {
@@ -394,8 +392,7 @@ fn scene_rig(lights: &[benilla_assets::ModelLight]) -> SceneRig {
 }
 
 /// **The GHOST select screen's hardcoded sun** — the one directional the reference injects when the
-/// selected roster record carries `CHARSELECT+0xfc & 0x2000`, replacing the authored rig entirely
-/// (wow-re `glue-select-model.md` §C1–C4 + `glue-select-ghost-treatment.md`, VERIFIED).
+/// selected roster record carries `CHARSELECT+0xfc & 0x2000`, replacing the authored rig entirely.
 ///
 /// `0x472150` is a per-model per-frame **fill callback** (`[model+0x3bc]`, registered by `0x7134b0`)
 /// whose *entire body* is gated on that bit (`47218e mov ecx,[record+0xfc]; 472194 test ch,0x20;
@@ -562,7 +559,7 @@ pub(crate) struct PreviewBillboard {
 /// Two sources produce these, and the booth treats them identically:
 ///
 /// - **An equipped item's own emitters** — the R14 PVP pauldron's `SPARKLE` twinkle, the held
-///   torch's flame (decision 0813; `#bugs` B118 is *this* case, and the select screen showed
+///   torch's flame (decision 0813; the select screen showed
 ///   nothing at all until it was carried here). Seat = the body's attach point for that slot.
 /// - **An item glow** (decision 0805) — the `Spells\Enchantments\*.mdx` effect a held weapon's
 ///   `ItemVisuals` id hangs on the weapon's own attachment point; all but three of the 35 shipped
@@ -577,13 +574,13 @@ pub(crate) struct PreviewEffects {
 
 /// The select screen's **ghost** treatment on the character body — what the reference's
 /// `0x4727f0` applies when the selected roster record carries `CHARSELECT+0xfc & 0x2000`
-/// (wow-re `glue-select-model.md` §A2, VERIFIED; the row text is the same bit, `refresh.rs`).
+/// (the row text is the same bit, `refresh.rs`).
 ///
 /// **It is one hard-coded `SpellVisualKit` row, and we read it from the DBC exactly as the
 /// reference does.** `0x47280f` loads `idmap[989]` behind the guard `0x4727f6 cmp ds:0xc0d750,0x3dd`
 /// — the *id* is the constant, the values are data — and 989 is the state kit of `SpellVisual` 886,
 /// which is the visual of spell 8326 "Ghost", the very aura the WORLD ghost rides
-/// (`crate::aura_visual`, wow-re `ghost-death-visuals.md` §2/§5a). So the select mannequin and a
+/// (`crate::aura_visual`, `0x5ff350`). So the select mannequin and a
 /// released ghost in the world are the same kit reaching the same three render properties by two
 /// different code paths, and benilla resolves both through the one dispatch point
 /// ([`crate::aura_visual::node_for`]) rather than transcribing constants twice.
@@ -626,7 +623,7 @@ pub(crate) struct GluePreviewBake {
     /// [`PreviewBillboard`].
     pub(crate) billboards: Vec<PreviewBillboard>,
     /// Per-hand weapon grip `[right, left]` — a hand whose attach point holds a weapon closes into the
-    /// `HandsClosed` finger pose (wow-re `hand-grip-mechanism.md`). The builder knows the held items'
+    /// `HandsClosed` finger pose (`CloseHand 0x479660`). The builder knows the held items'
     /// attach ids (which the flat rider list drops), so it resolves the grip here for the booth spawn.
     pub(crate) grip: [bool; 2],
     /// The selected character's **ghost** kit, or `None` for a living selection — see [`GhostKit`].
@@ -797,7 +794,7 @@ pub(super) fn spawn_glue_booth(
 /// which pass the glue pair has installed, and what `LightParams.glow` is pinned to.
 ///
 /// One writer for all three glue screens, because the reference's three writers are all reached
-/// through the same widget and the same build (wow-re `glue-select-ghost-treatment.md`):
+/// through the same widget and the same build:
 ///
 /// | look | reference | pass | glow |
 /// |---|---|---|---|
@@ -938,14 +935,14 @@ pub(super) fn sync_glue_scene(
     let token = scene_token(which);
     // The fog law forks on the scene kind (decision 0539 §5): the main menu is ALWAYS fogged with
     // its authored XML fog; for a race stage it is per-SCREEN — create keeps `CharModelFogInfo`,
-    // select renders the same scene unfogged (`0x472110` overwrites the background's fog callback —
-    // wow-re `glue-select-model.md` TU-C). The screen is told by the look's flavor (every create
+    // select renders the same scene unfogged (`0x472110` overwrites the background's fog
+    // callback). The screen is told by the look's flavor (every create
     // writer sets a Create look with the scene; select feeds Select or, on an empty account, None).
     let fog = match which {
         GlueScene::MainMenu => true,
         GlueScene::Race(_) => matches!(preview.look, Some(GlueLook::Create(_))),
     };
-    // The GHOST light fork (wow-re `glue-select-model.md` §C1, and [`ghost_rig`]): the selected
+    // The GHOST light fork (`0x472150`, and [`ghost_rig`]): the selected
     // roster record's `CHARSELECT+0xfc & 0x2000`, which reaches the background scene, the character
     // and the pet through one `[0x83856c]`-keyed read in the reference and through one light buffer
     // here — all three of ours bind it.
@@ -1134,10 +1131,9 @@ pub(super) fn sync_glue_scene(
                 // Not a bake question, which is why it is decided here rather than deferred to
                 // 0130's bake law: a create/main-menu screen is a LIVE render, and the reference
                 // runs the texture transform inside the per-model-per-frame animate kernel
-                // (`0x715f25`-`0x7163bc` over the MD20 `+0x74` table, wow-re
-                // `modelframe-texanim-and-sequence-law.md` §3.1) — it is what an animated CM2Model
-                // does, not a lane a host opts into. The portrait and dressing-room bakes are the
-                // opposite case and stay still (`BoothPart::mat_anim`).
+                // (`0x715f25`-`0x7163bc` over the MD20 `+0x74` table) — it is what an animated
+                // CM2Model does, not a lane a host opts into. The portrait and dressing-room bakes
+                // are the opposite case and stay still (`BoothPart::mat_anim`).
                 //
                 // **Shared lane only, and that is measured, not assumed** (`benilla-extract
                 // uvslotscan interface\glues`): 13 models, 261 batches, **15 live UV loops over 6
@@ -1393,7 +1389,7 @@ fn resize_target(images: &mut Assets<Image>, target: &Handle<Image>, w: u32, h:
 /// screen's live yaw (drag / rotate — cheap, no re-bake). Mirrors [`super::sync_paperdoll`]: the
 /// parts + riders come pre-assembled from the entities builder, so here we only re-light them —
 /// onto the **scene's authored rig** while a scene is up (the ref's glue character is scene-lit;
-/// the select screen's hardcoded weather-sun is the in-flight §5's to settle, decision 0465 §5),
+/// the select screen's hardcoded weather-sun is not yet settled, decision 0465 §5),
 /// the studio buffer otherwise — pose a fresh Stand-**looping** instance with the riders on its
 /// joints, and frame it full-body.
 pub(super) fn sync_glue_booth(
@@ -1497,7 +1493,7 @@ pub(super) fn sync_glue_booth(
             }
         };
         // The bake's instance-level render properties — the ghost kit's alpha, or opaque
-        // (`GhostKit`, wow-re `glue-select-model.md` §A2). It reaches every batch of the bake, the
+        // (`GhostKit`, `0x4727f0`). It reaches every batch of the bake, the
         // riders and cards included: the reference has ONE instance alpha per CM2 and every model
         // attached to it composes onto that (`0x714000`).
         let instance = BoothInstance {
@@ -1612,7 +1608,7 @@ pub(super) fn sync_glue_booth(
             },
         );
         // The worn items' effects: an equipped item model's OWN emitters (decision 0813 — the R14
-        // pauldron's sparkle, the torch's flame; `#bugs` B118) and the held weapons' `ItemVisuals`
+        // pauldron's sparkle, the torch's flame) and the held weapons' `ItemVisuals`
         // glows (decision 0805). One host per effect model at its seat, emitters owned by it — the
         // scene-brazier recipe (0539 §5), so they draw against THIS camera and fog on the scene's own
         // light. Children of the booth root through their joint, so the next re-bake's
@@ -1704,8 +1700,7 @@ pub(super) fn sync_glue_booth(
 }
 
 /// Stand the select screen's **pet** on scene attachment 1 — the hunter/warlock companion beside
-/// the selected character (the reference's secondary model `record+0x114`, wow-re
-/// `glue-select-model.md` §A4/§B1).
+/// the selected character (the reference's secondary model `record+0x114`, `0x47306b`).
 ///
 /// The booth twin of [`sync_glue_booth`], and deliberately the simpler one: a pet is an ordinary
 /// creature display, so its parts come straight off the shared display cache with no compositor,
@@ -1891,7 +1886,7 @@ fn apply_yaw(
 /// A stage is an M2 *attachment*, and an attachment carries a frame, not just a point. The
 /// reference composes the whole thing: `child+0xfc = child+0xbc × (T(att.pos) · parentBone[att.bone])`
 /// (`MatrixMultiply` at `0x71439b`, inside `0x714260`) — **rotation and scale go in, not only the
-/// translation** (wow-re `glue/scratch/glue-preview-facing-law.md`, §the attachment leg).
+/// translation**.
 /// Five of the six shipped `UI_*` scenes leave that bone unrotated,
 /// because their camera is authored looking straight down the stage's +X and a WoW model's default
 /// facing already looks that way (measured on the files: Orc +0.02°, Dwarf +0.62°, NightElf
@@ -2159,18 +2154,16 @@ mod tests {
         }
     }
 
-    /// GOLDEN — the ghost select screen's hardcoded sun, every number byte-VERIFIED (wow-re
-    /// `glue-select-ghost-treatment.md`; see [`ghost_rig`] for the citations).
+    /// GOLDEN — the ghost select screen's hardcoded sun (see [`ghost_rig`] for the citations).
     ///
-    /// The **sign** is the assertion that matters. wow-re's earlier §C4 was internally
-    /// contradictory about it — it called `CGLight+0x24` a to-light vector with no sign flip in the
-    /// SH chain, then concluded "lit from directly overhead" via the fixed-function commit, which
-    /// negates. Those differ by 180°: a character lit from above versus from below. The round that
-    /// settled it found `0x71bce0` negating all three components (`0x71be7c`/`0x71be81`/`0x71be86`)
-    /// before it accumulates, so both lanes agree on `(0,0,+1)`. The trap it also found is why this
-    /// is pinned rather than trusted to a comment: an AUTHORED M2 light already carries one
-    /// negation (`0x718960` stores `-Bz`, which is why [`scene_rig`] feeds `+bone_z`), so reusing
-    /// the authored convention here double-negates and lights the ghost from underneath.
+    /// The **sign** is the assertion that matters: a wrong sign is 180° off, a character lit from
+    /// above versus from below. `CGLight+0x24` is a from-light vector, not a to-light one:
+    /// `0x71bce0` negates all three components (`0x71be7c`/`0x71be81`/`0x71be86`) before it
+    /// accumulates, and the fixed-function commit negates too, so both lanes agree on `(0,0,+1)`.
+    /// The trap is why this is pinned rather than trusted to a comment: an AUTHORED M2 light
+    /// already carries one negation (`0x718960` stores `-Bz`, which is why [`scene_rig`] feeds
+    /// `+bone_z`), so reusing the authored convention here double-negates and lights the ghost from
+    /// underneath.
     #[test]
     fn the_ghost_sun_is_one_overhead_directional_over_a_wiped_gather() {
         let rig = ghost_rig();
@@ -2194,11 +2187,11 @@ mod tests {
         assert_eq!(rig.ambient.map(byte), [26, 56, 85], "…and sub 1");
     }
 
-    /// GOLDEN — the rig fold's classification law (wow-re `m2-dynamic-lights.md` +
-    /// `glue-model-lighting.md`): directionals accumulate (ambient tracks summed; diffuse×intensity
-    /// as per-light SH lobes whose to-light is the **bone's +Z axis**, never the def position),
-    /// points land on the point table verbatim (colour × intensity, position wow→bevy) — never
-    /// folded into the sun, and their dead authored attenuation radii never scale anything.
+    /// GOLDEN — the rig fold's classification law (the gather `0x718960`): directionals
+    /// accumulate (ambient tracks summed; diffuse×intensity as per-light SH lobes whose to-light is
+    /// the **bone's +Z axis**, never the def position), points land on the point table verbatim
+    /// (colour × intensity, position wow→bevy) — never folded into the sun, and their dead authored
+    /// attenuation radii never scale anything.
     #[test]
     fn rig_fold_classifies_directional_vs_point() {
         let lights = [
diff --git a/crates/benilla-app/src/portrait/light.rs b/crates/benilla-app/src/portrait/light.rs
index bd242606..d99c434a 100644
--- a/crates/benilla-app/src/portrait/light.rs
+++ b/crates/benilla-app/src/portrait/light.rs
@@ -98,7 +98,7 @@ pub(super) struct BoothLight {
 /// Reap the booth twins whose world source material died (`AssetEvent::Removed` — e.g. the
 /// map-scope teardown, `world_map::MapChange`). A twin is its own asset pinned only by this
 /// cache, so without the reap every world material ever baked through a booth would survive
-/// the teardown forever (the #bugs teleport leak, multiplied per rig). A live bake keeps its
+/// the teardown forever (the teleport leak, multiplied per rig). A live bake keeps its
 /// twin through its own `MeshMaterial3d` clone; only the dedup entry drops.
 pub(super) fn reap_dead_variants(
     mut events: MessageReader<AssetEvent<WowModelMaterial>>,
@@ -121,14 +121,14 @@ pub(crate) enum VariantLane {
     World,
     /// The scene's authored M2 light rig ([`benilla_world::model_render::ShadeSel::Rig`] — the
     /// probe-slot SH eval + the buffer's point table, decisions 0429/0435) **with fog forced
-    /// OFF**: the glue CHARACTER model takes no fog in the reference (its fill callback stages
-    /// none, its collector's fog stays zeroed — wow-re `glue-model-lighting.md` §5), and so does
-    /// a `<Model>` pane that never armed any.
+    /// OFF**: the glue CHARACTER model takes no fog in the reference (its fill callback
+    /// `0x470ce0` stages none, its collector's fog stays zeroed), and so does a `<Model>` pane
+    /// that never armed any.
     RigUnfogged,
     /// The rig lane with the batch's **authored** fog policy kept — a `<Model>` pane whose Lua
     /// armed fog (decision 2027). The per-material UNFOGGED bit (`0x02`) then does its own work,
     /// which is the reference's own per-batch fork: a fogged pane still draws its UNFOGGED
-    /// materials unfogged (render law §5.6). The glue background scene takes this lane too.
+    /// materials unfogged (`0x70bb24`). The glue background scene takes this lane too.
     RigFogged,
 }
 
@@ -184,19 +184,20 @@ pub(crate) fn material_variant(
 /// - That ctor configures the widget's embedded `CGLight` at `+0x324`: **directional**
 ///   (`0x71b620(light, 0)` @`0x5056c9`), **direction `(0, 1, 0)` — the direction the light
 ///   PROPAGATES** (`0x71b6a0` @`0x505761` writes `CGLight+0x24`, which `0x71bce0` negates — three
-///   `fchs` at `71be7c`/`71be81`/`71be86` — before building the SH basis, wow-re
-///   `modelframe-facing-cancels.md` Q4; 0638 read the field as a to-light vector, 2034 corrects
-///   it — it overwrites an earlier `(0, −0.7071, −0.7071)` set at `0x5056e9`, dead code), **diffuse
+///   `fchs` at `71be7c`/`71be81`/`71be86` — before building the SH basis; 0638 read the field as
+///   a to-light vector, 2034 corrects it — it overwrites an earlier `(0, −0.7071, −0.7071)` set at
+///   `0x5056e9`, dead code), **diffuse
 ///   `(0.8, 0.8, 0.64)`** (`+0x3c`, @`0x505702`), **ambient `(0.7, 0.7, 0.7)`** (`+0x30`,
 ///   @`0x50572e`), then **enables** it (`0x71b780(light, 1)` @`0x50576a`).
 /// - It is the widget's ONLY light: the per-frame fill callback `0x76d680` (registered on the
 ///   model at `[model+0x3bc]` by `0x76cd30`) stages exactly this one, gated on its enable flag; the
 ///   widget's private scene container holds no others (a paper doll has no background scene M2
-///   authoring lights, unlike the glue screens — wow-re `glue-model-lighting.md §0`), and
-///   `CSimpleModel::SetLight` (`0x76cf30`) has exactly one caller in the whole binary — the Lua
-///   `Model:SetLight` binding, which no 1.12 FrameXML file ever calls.
-/// - No `×2.5` exterior-intensity node on this path (widgets carry no lighting node —
-///   `glue-model-lighting.md §4`), so row 19's dial stays at the studio's `0.4` = intensity 1.0.
+///   authoring lights, unlike the glue screens — create's `SetCharCustomizeBackground 0x4707b0`
+///   loads one), and `CSimpleModel::SetLight` (`0x76cf30`) has exactly one caller in the whole
+///   binary — the Lua `Model:SetLight` binding, which no 1.12 FrameXML file ever calls.
+/// - No `×2.5` exterior-intensity node on this path (widgets carry no lighting node, and the ×2.5
+///   node-apply `0x6a7300` is world-only), so row 19's dial stays at the studio's `0.4` =
+///   intensity 1.0.
 ///
 /// **Why this reads so much darker than the studio light, and why that is the point.** The
 /// reference's light is a pure SIDE light: it travels toward WoW `(0, 1, 0)`, the model's own left
diff --git a/crates/benilla-app/src/portrait/mod.rs b/crates/benilla-app/src/portrait/mod.rs
index ca5e38ab..f9c3f424 100644
--- a/crates/benilla-app/src/portrait/mod.rs
+++ b/crates/benilla-app/src/portrait/mod.rs
@@ -2,7 +2,7 @@
 //!
 //! The real 1.12 client renders a unit's model **once** into a tiny (64²) off-screen texture and
 //! freezes it (re-baked only on model change), then stamps a round alpha stencil into it; the low
-//! resolution is a 2004 shortcut, not a look (wow-re `system/ui/scratch/portrait-render.md`, §5-verified).
+//! resolution is a 2004 shortcut, not a look (`0x524f60`).
 //! benilla keeps the *idea* — a flat 2D face in the ring — but bakes it properly: a **high-resolution**
 //! off-screen render of the unit's real model, so the still is crisp. No live 3D widget sits in the UI;
 //! what lands in the circle is a plain rendered image (director's call).
@@ -24,30 +24,28 @@
 //! mesh twin + steady exterior material. Mirroring the children (not the shared display cache) means
 //! the portrait can never drift from what's standing in the world, and gear/appearance rebuilds
 //! re-bake automatically (the parts key changes). While a live unit's model is still loading, the
-//! slot shows the ref's own 2D stand-in (`TemporaryPortrait-{Sex}-{Race}` / `-Monster`, RE C5) via
-//! [`PortraitSource::File`].
+//! slot shows the ref's own 2D stand-in (`TemporaryPortrait-{Sex}-{Race}` / `-Monster`,
+//! `0x525ba0`) via [`PortraitSource::File`].
 //!
 //! ## Framing: the model's own authored camera
 //!
 //! The framing is the model's **authored portrait camera** — the MD20 camera `cameraLookup[0]`
-//! selects (VERIFIED, wow-re `system/ui/scratch/portrait-render.md` §4 + corrected verdict
-//! `aa186e79`): the real bake builds `lookAt(eye, target, up-from-roll)` + the gxumath
+//! selects (`0x713540`): the real bake builds `lookAt(eye, target, up-from-roll)` + the gxumath
 //! *diagonal-FOV* perspective at the portrait path's aspect, which is **1.0 on every screen** —
 //! net vertical half-angle `fov/(2√2)`, isotropic (`framing::WowPortraitProjection`, decision
 //! 1543) — and **no** engine-side yaw or normalization on top. Every artist calibrated camera 0 to their
 //! own model — that is the whole mechanism behind the ref's uniformly tight, consistently-angled
-//! face crops across humans, wolves, and rabbits. It supersedes the first RE verdict's C4 ("framing
-//! is not model data"), corrected on the wow-re record. A camera-less model (a few creatures,
+//! face crops across humans, wolves, and rabbits. A camera-less model (a few creatures,
 //! props) falls back to [`frame`]'s heuristic head-anchor framing.
 //!
 //! ## Pose: a fresh instance at Stand
 //!
-//! The bake is **posed like the ref's** (wow-re §4 D2): a fresh throwaway instance — the booth's
-//! own joint hierarchy + the parts' skinned twins — armed to the model's Stand (anim id 0 through
-//! its own baked resolution, the ref's loader-idle seed) and frozen, never the unit's live world
-//! pose. Bone riders (helm/shoulder armor, held items) ride their bone's joint, so they sit in
-//! the Stand pose exactly like the world instance ([`PortraitRider`]; the ref resets the attach
-//! *sockets* the same way, RE C3). See [`spawn_booth_model`].
+//! The bake is **posed like the ref's** (instance `0x707400`, pose `0x7121a0`): a fresh throwaway
+//! instance — the booth's own joint hierarchy + the parts' skinned twins — armed to the model's
+//! Stand (anim id 0 through its own baked resolution, the ref's loader-idle seed) and frozen, never
+//! the unit's live world pose. Bone riders (helm/shoulder armor, held items) ride their bone's
+//! joint, so they sit in the Stand pose exactly like the world instance ([`PortraitRider`]; the ref
+//! resets the attach *sockets* the same way, `0x47a230`). See [`spawn_booth_model`].
 //!
 //! ## Deviations from the ref (deliberate) and what's still coarse
 //!
@@ -55,7 +53,7 @@
 //! ambient state — the *body* panes instead carry the reference's own `<PlayerModel>` light, see
 //! [`model_pane_light`]), continuous
 //! booth render vs dirty-byte bake, and the frozen Stand *phase* is t=0 (the ref's sampling clock
-//! is the verdict's one unsettled INFERRED point — t≈0 vs live phase; both are Stand, and t=0
+//! is the one unsettled, inferred point — t≈0 vs live phase; both are Stand, and t=0
 //! reproduces the ref wolf's open mouth). The creature *loading* stand-in is `-Monster` (our
 //! pick — the ref's `-Pet` belongs to its pet-frame delegate).
 //! `WOW_PORTRAIT_TEST=<Model\Path.mdx>` (+ `WOW_PORTRAIT_TEST_SKIN=<blp>`) bakes that model into
@@ -137,7 +135,7 @@ const INSPECT_SLOT: &str = "inspect";
 /// rather than sharing the `"pet"` portrait slot because that one is a 256² *bust* for the pet unit
 /// frame — different subject framing, different resolution, and a yaw the portrait must never have.
 const PETDOLL_SLOT: &str = "petdoll";
-/// The **stable window**'s model pane (wow-re `ui/scratch/stable-master-window.md` §7.1) — the
+/// The **stable window**'s model pane (`0x4cb870`) — the
 /// fourth body pane, and the only one whose subject may have no world object at all.
 /// `SetPetStablePaperdoll` forks on the selection: `-1` (the summoned pet) resolves the live pet by
 /// GUID and takes its model, anything else maps the petNumber back to a slot and goes through the
@@ -288,10 +286,10 @@ const PORTRAIT_SIZE: u32 = 256;
 const PAPERDOLL_SIZE: u32 = 512;
 /// Stamped on every spawned unit-model part child by the attach path ([`crate::entities`]): the
 /// part's two mesh twins — the booth poses the **skinned** twin at Stand on its own throwaway
-/// skeleton (the ref bake, wow-re §4 D2), the **static** bind-pose twin serving the boneless
-/// fallback — and its **steady exterior material** (the child may currently wear the appear-fade
-/// blend or interior variant; a portrait always wants the steady look). The booth mirrors a unit's
-/// `PortraitPart` children — the exact dressed look standing in the world.
+/// skeleton (the ref bake: instance `0x707400`, pose `0x7121a0`), the **static** bind-pose twin
+/// serving the boneless fallback — and its **steady exterior material** (the child may currently
+/// wear the appear-fade blend or interior variant; a portrait always wants the steady look). The
+/// booth mirrors a unit's `PortraitPart` children — the exact dressed look standing in the world.
 #[derive(Component)]
 pub(crate) struct PortraitPart {
     pub(crate) static_mesh: Handle<Mesh>,
@@ -304,7 +302,8 @@ pub(crate) struct PortraitPart {
 /// [`crate::entities::equipment`]): the mesh + steady material like [`PortraitPart`], plus where it
 /// sits — the body bone it rides and the attach-point offset under that bone. The posed booth
 /// seats the rider under its throwaway skeleton's joint (so it rides the Stand pose exactly like
-/// the world instance rides its gait); the ref resets the attach *sockets* the same way (RE C3).
+/// the world instance rides its gait); the ref resets the attach *sockets* the same way
+/// (`0x47a230`).
 ///
 /// It also rides a **mirror-only carrier** — a marker child that draws nothing — where the world
 /// geometry it names is not a unit descendant we can stamp: an item glow's own render batches, which
@@ -385,8 +384,8 @@ impl PortraitSeat {
 }
 
 /// Stamped on an **effect-bearing model** riding a unit — the equipped item whose own emitters are
-/// its whole look (the R14 PVP pauldron's `SPARKLE` twinkle, the held torch's flame — decision 0813,
-/// `#bugs` B118) and the `ItemVisuals` glow a held weapon hangs on its own attachment points
+/// its whole look (the R14 PVP pauldron's `SPARKLE` twinkle, the held torch's flame — decision
+/// 0813) and the `ItemVisuals` glow a held weapon hangs on its own attachment points
 /// (decision 0805). The world emitters are *free* entities the owner contract walks
 /// ([`benilla_world::particles::spawn_emitter`]), never unit descendants, so — like [`PortraitBillboard`] —
 /// this marker is how a booth learns they exist at all: the mirror carries the emitter records plus
@@ -428,7 +427,7 @@ pub(crate) struct PortraitEffects {
 pub(crate) struct PortraitStandIn(pub(crate) u32);
 
 /// What a portrait slot currently shows — the booth's live bake, or the ref's 2D stand-in file
-/// while a unit's model is still streaming in (RE C5).
+/// while a unit's model is still streaming in (`0x525ba0`).
 #[derive(Clone, PartialEq)]
 pub(crate) enum PortraitSource {
     /// The slot's off-screen render target (the model bake).
@@ -438,8 +437,7 @@ pub(crate) enum PortraitSource {
     File(String),
 }
 
-/// **The GUID-keyed bake cache** — `0xc0ce7c` (decision 1640; wow-re
-/// `ui/scratch/party-oor-stats-and-portrait-law.md` §4/§5, report B334).
+/// **The GUID-keyed bake cache** — `0xc0ce7c` (decision 1640; report B334).
 ///
 /// `SetPortraitTexture` on a player GUID whose object the client does not hold does **not** go
 /// straight to the 2D stand-in: it probes this cache by guid and, on a hit with a live handle,
@@ -556,7 +554,7 @@ impl Default for PetDollBooth {
     }
 }
 
-/// The stable window's model pane input (wow-re `stable-master-window.md` §7.1) — the
+/// The stable window's model pane input — the
 /// [`PetDollBooth`] shape plus the one thing no other body pane needs: a **subject with no world
 /// object**.
 ///
@@ -584,11 +582,10 @@ impl Default for PetDollBooth {
 /// (`0x4cb870`) writes no scale on either arm; `0x505cb0` only stores the pointer into
 /// `[widget+0x3f0]` and clears `[+0x3e0]`/`[+0x3e4]`; and the record→model build it defers to
 /// (`0x505a70`) walks `CreatureDisplayInfo` → `CreatureModelData` → the model path and calls
-/// `0x4797b0`, which wow-re's `charactermodel` ledger records as the creature **texture-variation**
-/// applier — there is no `fmul` of a scale anywhere on the path. The pane is unnormalized by
-/// construction anyway ([`framing::body_frame`]: a `<PlayerModel>` renders through the model's own
-/// authored camera or a fixed rig, never a bounds fit), so "small model draws small" is already the
-/// law here.
+/// `0x4797b0`, the creature **texture-variation** applier — there is no `fmul` of a scale anywhere
+/// on the path. The pane is unnormalized by construction anyway ([`framing::body_frame`]: a
+/// `<PlayerModel>` renders through the model's own authored camera or a fixed rig, never a bounds
+/// fit), so "small model draws small" is already the law here.
 ///
 /// The second reason is internal, and it is the stronger one: the live arm goes through
 /// [`sync_body_booth`] like every other body pane, which applies only [`framing::pane_root_scale`].
@@ -709,8 +706,8 @@ struct Booth {
     /// **skipped** — silently, with no error and no missing asset ([`PipeWatch::compiling`] has
     /// the byte references). A live view redraws it a few frames later and nobody ever sees it.
     /// A one-shot portrait bake does not: [`BOOTH_SETTLE_FRAMES`] elapse, the camera sleeps, and
-    /// the still keeps the hole for the rest of the session — which is exactly the report
-    /// ("*sometimes hair missing, sometimes face, totally random*"): hair is the alpha-key
+    /// the still keeps the hole for the rest of the session — which is exactly the symptom (the
+    /// hair missing one time, the face the next, at random): hair is the alpha-key
     /// pipeline, the body the opaque one, the eye-glow card the additive one, and which of the
     /// three had landed by the fourth frame is a race. It is invisible on macOS, where the same
     /// compile `block_on`s the render thread instead: the whole class exists on the reporters'
@@ -747,7 +744,7 @@ struct Booth {
 /// A body pane's **turn animation** state — the half of the reference's `SetRotation` that is not
 /// the facing write (decision 1559, director report B313).
 ///
-/// `PlayerModel:SetRotation(angle)` (`0x505bb0`, wow-re `modelframe-camera-law.md` §6) does two
+/// `PlayerModel:SetRotation(angle)` (`0x505bb0`) does two
 /// things: it picks a turn-in-place shuffle by direction, queues it and arms a 100 ms expiry, and
 /// *then* writes the facing field `SetFacing` writes. Ours only ever did the second — the doll
 /// spun on the spot while the reference's steps its feet round, which is what a held arrow looks
@@ -802,7 +799,7 @@ impl Turn {
 /// slot, seeded by every arm the turn makes (decision 1565, director report B321).
 ///
 /// `0x7121a0`'s sixth argument is `1` at both of the turn's call sites (`0x505c23` the rotation,
-/// `0x505c98` the 100 ms expiry — wow-re `modelframe-camera-law.md` §13.4). A non-zero there is
+/// `0x505c98` the 100 ms expiry). A non-zero there is
 /// `0x7125d6`: `rep movsd` copies the live primary track into the secondary sub-record `[blk+0xc4]`
 /// — the outgoing clip, **still on its own clock**, not a frozen pose — then writes the window end
 /// `[blk+0x100]`, the rate `[blk+0x104] = 1/blendTime` and the amplitude `[blk+0x108] = 1.0f`. The
@@ -877,7 +874,7 @@ fn log_bake(
 ) {
     if booth_log() {
         // The **attach ids** the bake is dressed at, sorted and de-duplicated. Counts alone could
-        // not answer the question `#bugs` B324 asked — *what is hanging on this doll?* — and the
+        // not answer the question — *what is hanging on this doll?* — and the
         // answer is one line: a hunter mid-shot read `at=[2,35]` (bow at HandLeft, arrow at
         // HandArrow) where the reference can only ever show `[2]`. It is also the retest readout
         // for the reference's attach reset ([`attach_reset`]): no id in the cut family may appear.
@@ -912,7 +909,7 @@ fn log_bake(
 /// Both bake sites used to paper over that with `unwrap_or(PortraitAnchors { .., pivot_height: 0.0,
 /// .. })`. That is not a neutral default: the retired body fit floored the head signal at `0.1` for
 /// "a hypothetical bounds-less display", so zero anchors aimed the camera at a 0.1-unit-tall
-/// subject — the paper doll "zoomed into the max" and the wrong-size portrait of `#bugs` B106. (1089
+/// subject — the paper doll zoomed all the way in, and a portrait at the wrong size. (1089
 /// retired that fit, and zero anchors are no longer a *zoom* — but they are still the wrong camera:
 /// an unbuilt display has no `cameras[1]` to read, so the pane would latch the fixed fallback rig
 /// aimed at a zero bbox centre.) And it latches: the camera is aimed once per bake, and the parts
@@ -1161,7 +1158,7 @@ fn feed_gx_aspect(
 /// 1607.** 1444 shipped it on; 1559 turned it off on the director's look-call (a full-rate doll
 /// reads as smoother); the 08-25 weak-GPU perf reports (B329) then measured what that costs — a
 /// body-pane booth's off-screen pass every frame, ~1.6 ms at 1600×900 and **7.6 ms at 4K**
-/// (`sess/perfregress` A/B), paid on exactly the weak GPUs that reported. The director retested
+/// (an A/B leg), paid on exactly the weak GPUs that reported. The director retested
 /// the 30 fps doll and it reads fine, so the cheaper default is back. Full-rate is one
 /// `/script SetCVar("boothHalfRate", 0)` away for anyone who wants the smoother cadence.
 ///
@@ -1326,8 +1323,8 @@ pub(crate) fn new_target_image_sized(width: u32, height: u32) -> Image {
         // FLOAT, not `Rgba8Unorm`, is B126 (decision 0804). Quantizing *un-encoded* values to 8 bits
         // is a precision collapse exactly where the eye is most sensitive: the only display levels
         // reachable below display byte 100 are `srgb(k/255)` = 0, 13, 22, 28, 34, 38, … — ~25 steps
-        // where the 8-bit gamma backbuffer this feeds has 100. That is the reported "colors are 16
-        // bit instead of 32" banding on the glue screens' trees and skybox, measured on the
+        // where the 8-bit gamma backbuffer this feeds has 100. That is the banding that reads as
+        // 16-bit colour on the glue screens' trees and skybox, measured on the
         // histogram of a char-select capture (15 of 16 predicted ladder values hit). The pipeline's
         // *semantics* are unchanged by this — same values, same single encode downstream, just not
         // rounded to a 256-step linear grid on the way through.
@@ -1504,7 +1501,7 @@ fn setup_booths(
 
     // The four **body** booths — the character window's paper doll (decision 0208 §5), the
     // inspect window's pane (decision 0631 §4), the pet paper doll's (decision 1057) and the
-    // stable window's (wow-re `stable-master-window.md` §7.1). Same off-screen pipeline as the
+    // stable window's (`SetPetStablePaperdoll 0x4cb870`). Same off-screen pipeline as the
     // portrait slots (transparent target, HDR + the FFXGlow node, negative order so the bake is
     // ready before the world/UI cameras), but their own 512² targets, their own layers, and a
     // body-framing projection (aimed per-bake by `sync_body_booth`). Kept a separate spawn from
@@ -1607,7 +1604,6 @@ fn test_mode(cached: &mut Option<bool>) -> bool {
 ///   one Lua round-trip later. Every *snap* sheath change — the combat auto-draw, the stand-state
 ///   stow, the descriptor apply — takes `bInstant != 0` and reaches the queue only through the
 ///   enchant-gated `0x5eed50`, which is why drawing a bow on a mob does **not** move the doll.
-///   That split is `#bugs` B324.
 /// - **An item's glow instances landing** — ours, not the reference's. Its widget duplicates a
 ///   model the world had already finished building; our `ItemVisuals` models stream in, and a key
 ///   blind to their arrival would leave a permanently-glowing weapon glowing nothing in the
@@ -1641,11 +1637,11 @@ fn bump_model_revision(
 /// The attach ids the **sheath lane owns** — the hand points a weapon is drawn into, the forearm a
 /// shield takes, and the six sheath points plus the shield's back slot it is stowed at. A draw or
 /// a stow moves an item among these, and for two kinds of item makes it vanish outright: a
-/// **ranged** weapon renders nothing while stowed (`0x611770` detaches it and never re-attaches —
-/// `ranged-sheath-display.md`), and so does a melee weapon whose `SheatheType` is 0. The worn
+/// **ranged** weapon renders nothing while stowed (`0x611770` detaches it and never
+/// re-attaches), and so does a melee weapon whose `SheatheType` is 0. The worn
 /// quiver rides `0x1a` on the same gate.
 ///
-/// [`SnapKey`] is blind to every one of them, which is the whole mechanism of `#bugs` B324: a
+/// [`SnapKey`] is blind to every one of them, which is the whole mechanism: a
 /// widget's duplicate must not notice that the world drew a weapon.
 fn sheath_lane(attach: Option<u16>) -> bool {
     matches!(attach, Some(0..=2 | 26..=28 | 30..=33))
@@ -1656,7 +1652,7 @@ fn sheath_lane(attach: Option<u16>) -> bool {
 /// A `<PlayerModel>` does not mirror the unit: it **duplicates** the unit's `CM2Model` once and
 /// renders the copy (`0x5059a0` → `0x707400`), and the copy is dead to everything the world does
 /// afterwards — `[dup+0x34]` holds the source only long enough to build, and is Released and
-/// nulled inside `0x707400` itself (wow-re `ui/scratch/paperdoll-liveness-law.md`, §5 verified).
+/// nulled inside `0x707400` itself.
 /// Ours mirrored the live tree every frame, so a bow drawn in combat walked straight onto the
 /// character sheet.
 ///
@@ -1759,8 +1755,7 @@ impl SnapKey {
 /// Every widget that shows a live unit builds its model by *duplicating* the unit's own
 /// `CM2Model`, attachment tree and all (`0x707400`/`0x70ea00` deep-copy the children at the same
 /// attach ids), and then runs this partial reset on the copy — the `<PlayerModel>` paper doll via
-/// `0x5059a0 → 0x47a230`, the round unit portrait via `0x525261` (wow-re
-/// `ui/scratch/dressup-model-equipment.md` §1, `ui/scratch/portrait-render.md` §4, both VERIFIED).
+/// `0x5059a0 → 0x47a230`, the round unit portrait via `0x525261`.
 ///
 /// It detaches fifteen ids — `0xf` (twice), `0x10`, `0x11`, `0x12`, `0x13`–`0x19`, `0x1d`, `0x22`,
 /// `0x23` — and pointedly **keeps** the three hand points `0`/`1`/`2`, the sheath family
@@ -1769,7 +1764,7 @@ impl SnapKey {
 /// breath, the two nameplates, Base, Head, the two spell hands, Special1–3, Chest — and
 /// **HandArrow (`0x23`)**, the nocked arrow. Equipment survives; effects do not.
 ///
-/// `0x23` is the one that shows up in a bug report (`#bugs` B324): our booths mirrored the
+/// `0x23` is the one that shows up in a bug report: our booths mirrored the
 /// nocked arrow onto the character-window doll, where the reference can never draw one.
 fn attach_reset(attach: Option<u16>) -> bool {
     matches!(attach, Some(0xf..=0x19 | 0x1d | 0x22 | 0x23))
@@ -1777,9 +1772,8 @@ fn attach_reset(attach: Option<u16>) -> bool {
 
 /// The reference's **hand grip** for a widget's duplicate, from attachment occupancy alone
 /// (`0x5059a0` at `505a34`/`505a4d`: `GetAttachment(model, 2)` non-null → `CloseHand(1)`,
-/// `GetAttachment(model, 1)` non-null → `CloseHand(0)` — wow-re
-/// `animation/scratch/hand-grip-mechanism.md` §4c, which names this the cleanest expression of the
-/// rule and the one benilla should implement).
+/// `GetAttachment(model, 1)` non-null → `CloseHand(0)` — the cleanest expression of the rule and
+/// the one benilla should implement).
 ///
 /// Returns [`booth::spawn_booth_model`]'s `[right, left]`. **Occupancy, not sheath state and not
 /// combat**: a hand holding anything closes; the shield's forearm point (`0`) closes nothing. The
@@ -1908,7 +1902,7 @@ impl DressedLook<'_, '_> {
 /// Each frame: for every slot, mirror the unit's **live dressed look** — its attach-spawned
 /// [`PortraitPart`] children — into the booth whenever that look changes (new unit, gear swap,
 /// appearance refresh), re-framing the camera from the display's anchors. A live unit whose model
-/// hasn't attached yet shows the ref's 2D `TemporaryPortrait` stand-in instead (RE C5).
+/// hasn't attached yet shows the ref's 2D `TemporaryPortrait` stand-in instead (`0x525ba0`).
 fn sync_portraits(
     mut commands: Commands,
     mut booths: ResMut<Booths>,
@@ -1933,10 +1927,10 @@ fn sync_portraits(
     for token in SLOTS {
         // A token can name a unit the object manager does not hold: a party member outside the
         // local area, a pet whose object hasn't streamed yet. The reference does NOT leave that
-        // circle empty — RE C5 (`portrait-render.md`, CONFIRMED taxonomy) is explicit that a unit
-        // not held as a live UNIT object draws the 2D stand-in, and only "model/subsystem not
-        // ready" draws the blank. `unseen` carries that art for exactly those tokens; a token that
-        // names nobody at all leaves it `None` and the booth empties as before (report B315).
+        // circle empty — a unit not held as a live UNIT object draws the 2D stand-in (`0x525ba0`),
+        // and only "model/subsystem not ready" draws the blank (`0x519fcc`). `unseen` carries that
+        // art for exactly those tokens; a token that names nobody at all leaves it `None` and the
+        // booth empties as before (report B315).
         let mut unseen: Option<String> = None;
         // The guid this slot names, when the slot is one that retains a bake (decision 1640).
         let mut occupant: Option<u64> = None;
@@ -1986,7 +1980,7 @@ fn sync_portraits(
             // A party member's slot bakes only while the member is streamed (in range). Out of
             // range there is no model to pose — and no descriptor either, so the stand-in's
             // race/sex come from the name cache's `SMSG_NAME_QUERY_RESPONSE` triple, warmed for
-            // every roster entry by `net::apply::group::list`.
+            // every roster entry by `ui_party::net::list`.
             tok => {
                 let member = tok
                     .strip_prefix("party")
@@ -2080,9 +2074,9 @@ fn sync_portraits(
         // while the model is still loading / cube-fallback.
         let (parts, riders, billboards, effects) = look.collect(unit);
         if parts.is_empty() {
-            // Model not attached yet → the ref's own 2D stand-in (RE C5): sex/race for a player
-            // body, the Monster art for a creature (our pick — the ref's `-Pet` file belongs to
-            // its pet delegate). Keeps the booth's last bake around; only the bridge flips.
+            // Model not attached yet → the ref's own 2D stand-in (`0x525ba0`): sex/race for a
+            // player body, the Monster art for a creature (our pick — the ref's `-Pet` file belongs
+            // to its pet delegate). Keeps the booth's last bake around; only the bridge flips.
             let file = temporary_portrait(ent_q.get(unit).ok(), stores_q.get(unit).ok());
             let src = PortraitSource::File(file);
             if portraits.0.get(token) != Some(&src) {
@@ -2202,7 +2196,7 @@ fn sync_portraits(
             // **No emitters here, and that is the reference's own answer** (decision 0822): the
             // round portrait is a ONE-SHOT bake — a fresh M2 scene + instance, one `0x707680` draw,
             // the texture cached by GUID/displayId and returned with *no re-render* on a hit, nothing
-            // persisting between bakes (wow-re `portrait-render.md` §2, byte-verified). A particle
+            // persisting between bakes (`0x524f60`). A particle
             // emitter contributes nothing to a single frame of a freshly-born pool, so the ref's
             // portrait shows none — and a booth that spawned them would either freeze a cloud
             // mid-birth into the still or have to render forever for a 256² face. The batches above
@@ -2249,7 +2243,7 @@ fn sync_portraits(
 /// The key is **not** the mirrored geometry. A `<PlayerModel>` duplicates the unit's model once and
 /// renders a copy the world can no longer reach, and it re-takes that copy on four things — the
 /// pane showing, a change of dress, an explicit model event, a resize. Mirroring live put a bow
-/// drawn in combat straight onto the character sheet (`#bugs` B324); [`SnapKey`] carries the whole
+/// drawn in combat straight onto the character sheet; [`SnapKey`] carries the whole
 /// law and its byte provenance.
 fn sync_paperdoll(
     mut commands: Commands,
@@ -2410,7 +2404,7 @@ fn sync_stable_standin(
 ) {
     // **The live pet wins.** With a world body to mirror there is nothing for a stand-in to do, and
     // the reference agrees: `SetPetStablePaperdoll` reaches the creature cache only after the
-    // live-pet-by-GUID resolve has failed (§7.1's fall-through at `0x4cb9bc`).
+    // live-pet-by-GUID resolve has failed (the fall-through at `0x4cb9bc`).
     let want = stable.unit.is_none().then_some(stable.display_id).flatten();
     if state.display != want {
         if let Some(old) = state.entity.take() {
@@ -2510,8 +2504,8 @@ fn sync_stable_booth(
 
 /// Bake `unit`'s full-body dressed look into the `slot` booth at `yaw` — the shared body of all
 /// four body booths (decision 0208 §5 for the paper doll, 0631 §4 for inspect, 1057 for the pet
-/// doll, wow-re `stable-master-window.md` §7.1 for the stable pane). `unit` is `None` when there is
-/// nothing to show, which empties the booth.
+/// doll, `0x4cb870` for the stable pane). `unit` is `None` when there is nothing to show, which
+/// empties the booth.
 ///
 /// `unit` is a **subject**, not necessarily a world unit: a [`PortraitStandIn`] mirrors the same
 /// way and carries its own display id, which is how the stable pane draws a pet that has no object
@@ -2622,7 +2616,7 @@ fn sync_body_booth(
         .map_or(1.0, |a| framing::pane_root_scale(a, display_aspect));
     // A changed pane aspect re-runs the same path: the camera's projection depends on it, and it
     // only ever moves once — the first frame the window is drawn.
-    // **The snapshot compare** — the whole of `#bugs` B324. This used to be `LookKey`, the
+    // **The snapshot compare.** This used to be `LookKey`, the
     // mirrored geometry, which moved the instant the world drew a weapon. It is now the
     // reference's own re-`SetUnit` set, and a draw is not in it.
     let parts_changed = booth.snap.as_ref() != Some(&key);
@@ -2672,8 +2666,8 @@ fn sync_body_booth(
                 twins: BoothTwins::default(),
             })
             .collect();
-        // The worn items' effects (decision 0822) — an equipped item's own emitters (0813, `#bugs`
-        // B118) and a held weapon's `ItemVisuals` glow (0805). Collected BEFORE the teardown for the
+        // The worn items' effects (decision 0822) — an equipped item's own emitters (0813) and a
+        // held weapon's `ItemVisuals` glow (0805). Collected BEFORE the teardown for the
         // same reason as everything else here; spawned after the model, which is what hands us the
         // joints they seat on.
         let booth_effects: Vec<BoothEffects> = effects
@@ -3031,7 +3025,7 @@ fn gate_booth_cameras(
 /// The stand-in art's folder + stem, shared by the three arms below.
 const TEMPORARY_PORTRAIT: &str = "Interface\\CharacterFrame\\TemporaryPortrait";
 
-/// The ref's 2D portrait stand-in for a not-yet-renderable unit (RE C5):
+/// The ref's 2D portrait stand-in for a not-yet-renderable unit (`0x525ba0`):
 /// `TemporaryPortrait-{Male|Female}-{Race}` for a player body, `-Monster` otherwise.
 fn temporary_portrait(net: Option<&NetEntity>, store: Option<&crate::net::ObjectStore>) -> String {
     use benilla_protocol::EntityKind;
@@ -3361,7 +3355,7 @@ mod tests {
         )
     }
 
-    /// **`#bugs` B324, the half that removes the bow.** In combat the auto-draw is a *snap*
+    /// **The half that removes the bow.** In combat the auto-draw is a *snap*
     /// (`SetSheatheState(…, bInstant != 0)`), which reaches `UNIT_MODEL_CHANGED`'s one fire site
     /// only through the enchant-gated `0x5eed50` — so the reference's doll never hears about it.
     /// Ours re-baked on the mirrored geometry, and a drawn bow IS mirrored geometry.
@@ -3454,7 +3448,7 @@ mod tests {
         assert!(bare != helmed);
     }
 
-    /// **`#bugs` B324 — the nocked arrow reached the character-window doll.** A hunter shooting in
+    /// **The nocked arrow never reaches the character-window doll.** A hunter shooting in
     /// combat has a bow at HandLeft(2) and an arrow at HandArrow(0x23); our booths mirrored both,
     /// and the reference's doll can never draw the arrow: every model widget duplicates the unit's
     /// attachment tree and then detaches `0x23` with fourteen other transient ids
@@ -3514,8 +3508,7 @@ mod tests {
 
     /// **The grip is occupancy, not sheath state — and a shield never closes a hand.** The
     /// forearm point (`0`) is the shield's, and `0x479700`/`0x5059a0` fork on ids `1`/`2` alone
-    /// (wow-re `hand-grip-mechanism.md` §4a/§4b: "a shield in the offhand NEVER closes the hand,
-    /// in any stance").
+    /// (`0x60b678`: a shield in the offhand NEVER closes the hand, in any stance).
     #[test]
     fn a_shield_on_the_forearm_closes_no_hand() {
         use crate::entities::attach_id::{HAND_RIGHT, SHIELD};
@@ -3579,7 +3572,7 @@ mod tests {
         assert!(LookKey::build(&parts, &riders, &[], &[&glow]) == after);
     }
 
-    /// RE C5's player arm (`portrait-render.md`, CONFIRMED taxonomy): a unit the object manager
+    /// The 2D stand-in's player arm (`0x525ba0`): a unit the object manager
     /// does not hold draws `TemporaryPortrait-{Sex}-{Race}`. The out-of-area party member reaches
     /// it through the name cache's triple rather than a descriptor — same art, other source
     /// (report B315).
@@ -3607,8 +3600,8 @@ mod tests {
     }
 
     /// **A still is never committed while the render world is still building pipelines** —
-    /// report B331, the player's own portrait baking with the face (or the hair, or the shoulder)
-    /// simply absent, "totally random", on the reporter's Windows machine.
+    /// the symptom: the player's own portrait baking with the face (or the hair, or the shoulder)
+    /// simply absent, at random, on Windows.
     ///
     /// The mechanism is not a missing asset and never shows up as one: off macOS Bevy builds each
     /// pipeline variant on the async pool, and `SetItemPipeline` answers a not-yet-built variant
diff --git a/crates/benilla-app/src/preflight.rs b/crates/benilla-app/src/preflight.rs
index b1d42ca4..3b94e6c0 100644
--- a/crates/benilla-app/src/preflight.rs
+++ b/crates/benilla-app/src/preflight.rs
@@ -48,8 +48,8 @@
 //! 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 session
-//! running inside a worktree pool slot from logging in as somebody else's account — lives in
+//! 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.
 
@@ -76,13 +76,11 @@ const PLAYER_FLAGS_GM: u32 = 0x0000_0008;
 /// **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 wow-re's
-/// `object-layer/scratch/unit-flags-movement-gates.md` is where each row's mechanism lives —
-/// 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, and the taxi bit shares
-/// no gate with any of them.
+/// [`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.
 const MOVE_BLOCKERS: &[(u32, &str)] = &[
     (0x0004_0000, "STUNNED (no turning, no pitch)"),
     (
@@ -108,7 +106,7 @@ 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 (method.md). The bit itself is declared once
+/// the accident the unattended-combat ban exists for (docs/METHOD.md). The bit itself is declared once
 /// ([`crate::player`]).
 use crate::player::UNIT_FLAG_IN_COMBAT;
 
@@ -170,7 +168,7 @@ fn offline_notice(net: Option<Res<crate::net::NetOffline>>) {
     warn!(
         "preflight: NET OFF — no IO thread this run, so the drain gets no packets and NOTHING on \
          the wire path executes (net::apply, the movement stream, every MSG_MOVE_*). Fine for a \
-         visual capture; NOT evidence for a change to any of it. method.md's gate is a clean run \
+         visual capture; NOT evidence for a change to any of it. docs/METHOD.md's gate is a clean run \
          of the AFFECTED path — for wire work that means a live server run."
     );
 }
@@ -435,7 +433,7 @@ fn findings(
                 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 — the director's own account, or a bystander. `WOW_GM` would be
+                // 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`
@@ -478,7 +476,7 @@ fn findings(
     if unit_flags & UNIT_FLAG_IN_COMBAT != 0 {
         out.push(
             "IN COMBAT on arrival — something is already fighting this character. Do not leave it \
-             unattended (method.md's unattended-combat ban): break the fight or move it out."
+             unattended (docs/METHOD.md's unattended-combat ban): break the fight or move it out."
                 .into(),
         );
     }
diff --git a/crates/benilla-app/src/probe_shield.rs b/crates/benilla-app/src/probe_shield.rs
index c98c5e6a..a98b267c 100644
--- a/crates/benilla-app/src/probe_shield.rs
+++ b/crates/benilla-app/src/probe_shield.rs
@@ -159,9 +159,9 @@ impl ProbeShield {
     }
 }
 
-/// Whether `user` is a probe account — `probe` followed by digits, the slot-keyed identity every
-/// unattended session logs in with (method.md "The local vmangos server"). Nothing else is ours to
-/// modify: `one` is the director's, and a bystander test account is not a probe.
+/// Whether `user` is a probe account — `probe` followed by digits, the identity every unattended
+/// run logs in with (the `probe` skill). Nothing else is ours to
+/// modify: a player's account is theirs, and a plain test account is not a probe.
 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).
     let Some((prefix, digits)) = user.as_bytes().split_at_checked(5) else {
@@ -405,7 +405,7 @@ mod tests {
         for user in ["probe0", "probe7", "PROBE12"] {
             assert!(is_probe_account(user), "{user} is a probe account");
         }
-        // The director's account, and bystanders: never touched.
+        // 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");
         }
diff --git a/crates/benilla-app/src/query_cache.rs b/crates/benilla-app/src/query_cache.rs
index d984c4b8..8143705e 100644
--- a/crates/benilla-app/src/query_cache.rs
+++ b/crates/benilla-app/src/query_cache.rs
@@ -1,6 +1,6 @@
 //! **`QueryCache<K, V>` — the one ask-once cache** (decision 2288; 2265 §A4).
 //!
-//! The reference has one `DBCache<T>` (wow-re `system/dbcache/dbcache.md`): a consumer's miss
+//! 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
diff --git a/crates/benilla-app/src/quest_markers/mod.rs b/crates/benilla-app/src/quest_markers/mod.rs
index 0af139af..6f73ac9b 100644
--- a/crates/benilla-app/src/quest_markers/mod.rs
+++ b/crates/benilla-app/src/quest_markers/mod.rs
@@ -10,7 +10,7 @@
 //! own concern and lives in [`query`] (decisions 0650/0654). Answers land in [`QuestGiver`]'s
 //! per-guid status map (`net/apply`); THIS module is the render half: attach, scale, animate.
 //!
-//! The render law is byte-verified (wow-re object-layer `questgiver-marker.md`):
+//! The render law:
 //! - **Attach** (`0x6074c0`): the marker is a CHILD of the unit's own body M2 at attachment slot
 //!   **18** (0x12), or **29** (`PlayerNameMounted`) when a mount model exists and the body authors
 //!   it — [`overhead_slot`], one definition shared with the overhead name/plate/FCT readers. No
@@ -24,8 +24,8 @@
 //! - **Scale** (`0x607570`): `1 / |attach-bone basis|`, computed once at attach and baked into the
 //!   marker's base matrix (`marker+0xbc`). Not distance-based, not unit scale, no clamp or floor.
 //!
-//!   **The `1/L` is a SNAPSHOT, not an invariant** (wow-re AMENDED §Q3/§Q3c, 2026-08-22, four-worker
-//!   §5 + oracle execution of `0x607570` under the difftest harness). The arithmetic is confirmed —
+//!   **The `1/L` is a SNAPSHOT, not an invariant** (`0x607570` executed on the reference's own
+//!   bytes, not only read). The arithmetic is confirmed —
 //!   `L = ‖row0‖` of the attach point's WORLD matrix, so the compensation cancels the whole attach
 //!   basis (`s` and any bone-chain scale alike). What was wrong is the *published consequence*: the
 //!   old sentence here — "a constant world size regardless of the NPC's model scale, a gnome and an
@@ -55,7 +55,7 @@
 //!   real, and the change is one line — which is exactly why this paragraph exists.
 //!
 //!   One correction worth carrying: the post-multiply operand is `CM2Scene+0xdc` = **inverse(view)**,
-//!   not "the model's world transform" (`CM2Shared+0xdc`) as the note used to say. The bone matrices
+//!   not "the model's world transform" (`CM2Shared+0xdc`). The bone matrices
 //!   live in VIEW space and already carry `model+0xbc`; the final compose is
 //!   `marker+0xfc = marker+0xbc × parentAttachMatrix` at `0x71439b`.
 //! - **Animation** (`0x6076c0`): the marker's own M2 animation is armed looping — anim **0**
@@ -119,9 +119,9 @@ fn seq_loop(info: &BillboardInfo, anim_id: u16) -> Option<BoneScaleAnim> {
         .map(|(_, l)| l.clone())
 }
 
-/// The marker M2 per dialog status — the client's own dispatch, byte-verified (wow-re
-/// object-layer `questgiver-marker.md`: file table `0xc4d9d8` × status map `0x80c454` =
-/// `{0,3,0,2,7,1,6,6}`; the binary ships `.mdx` names, the loader maps them to `.m2`):
+/// The marker M2 per dialog status — the client's own dispatch (file table `0xc4d9d8` × status
+/// map `0x80c454` = `{0,3,0,2,7,1,6,6}`; the binary ships `.mdx` names, the loader maps them to
+/// `.m2`):
 /// UNAVAILABLE(1) → grey `!`, INCOMPLETE(3) → grey `?`, REWARD_REP(4) → light-blue `?`,
 /// AVAILABLE(5) → gold `!`, REWARD_OLD/REWARD2(6/7) → gold `?`; NONE(0)/CHAT(2) → nothing.
 /// (The Green/Blue `!` variants are driven by sibling handlers off NPC_FLAGS, not this status
@@ -195,7 +195,7 @@ fn despawn_marker(commands: &mut Commands, roots: &Query<&QuestMarkerRoot>, root
 
 /// Reconcile the marker set with the per-guid statuses: spawn/swap/despawn marker roots. Two
 /// sources feed the one overhead slot: the questgiver dialog status (this module's own wire),
-/// and the flight-master node status ([`crate::ui_taxi::FlightMasterStatus`], the 0497 §5 —
+/// and the flight-master node status ([`crate::ui_taxi::FlightMasterStatus`], decision 0497 —
 /// `known = false` shows `TalkToMeGreen`, the client's `0x607480` with resource index 4). The
 /// client's two handlers race last-write-wins on the same attach slot; we compose
 /// deterministically instead — a quest marker, when the status yields one, outranks the green
@@ -511,12 +511,11 @@ fn build_markers(
 /// (WoW z +0.427..+0.517 vs anim 0's −0.089..0), lifting the marker clear of the name text.
 /// Benilla raises for the floating name ([`Nameplates::shows`]) OR a live V-plate
 /// ([`VPlates`](crate::vplates::VPlates)) — the plate leg is a **director-pinned deviation**
-/// (2275): the reference arms anim 0 under a live plate (byte-verified, wow-re
-/// `questgiver-marker.md` Q4a — ShouldShowName's plate suppression destroys the rendered name
-/// and nulls the `desc+0x8` handle the selector `0x6c7950` tests), leaving its marker low
-/// behind the plate; the director rejected that overlap on sight. The re-arm law is settled
-/// faithful: the reference arms at attach AND re-arms on the frame the name shown-state flips
-/// (an edge inside `0x6c6e90`, never per-frame) — exactly our re-arm-on-flip.
+/// (2275): the reference arms anim 0 under a live plate (ShouldShowName's plate suppression
+/// destroys the rendered name and nulls the `desc+0x8` handle the selector `0x6c7950` tests),
+/// leaving its marker low behind the plate; the director rejected that overlap on sight. The
+/// re-arm law is settled faithful: the reference arms at attach AND re-arms on the frame the name
+/// shown-state flips (an edge inside `0x6c6e90`, never per-frame) — exactly our re-arm-on-flip.
 #[allow(clippy::type_complexity)] // a Bevy system: each param is one resource, the app's convention
 fn pose_markers(
     plates: Res<Nameplates>,
diff --git a/crates/benilla-app/src/quest_markers/query.rs b/crates/benilla-app/src/quest_markers/query.rs
index 20ac58f6..23e53bf8 100644
--- a/crates/benilla-app/src/quest_markers/query.rs
+++ b/crates/benilla-app/src/quest_markers/query.rs
@@ -9,13 +9,13 @@
 //! bit 3. One slot cannot have two lifetimes, so one system owns both asks; `ui_taxi` keeps the
 //! resulting fact ([`crate::ui_taxi::FlightMasterStatus`]) and nothing else.
 //!
-//! **A GameObject is queried and never rendered** (decision 1872, wow-re `questgiver-marker.md`
-//! §W14). The reference sends `CMSG_QUESTGIVER_STATUS_QUERY` for a quest-flagged GameObject from
-//! both object sweeps, but its answer handler `0x5dc9f0` resolves the GUID with typemask **8**
-//! (`0x468460` is a bitmask AND against `OBJECT_FIELD_TYPE`), so a GameObject's `0x21` returns NULL
-//! and the packet dies at `0x5dca2f` — and even if it did not, a GameObject has no `+0xcb8` status
-//! slot, no `+0xb2c` marker slot, and (11 models out of ~1600, none of them a poster) no
-//! attachment 18 to hang a marker from. So: **send the query, drop the answer, render nothing.**
+//! **A GameObject is queried and never rendered** (decision 1872). The reference sends
+//! `CMSG_QUESTGIVER_STATUS_QUERY` for a quest-flagged GameObject from both object sweeps, but its
+//! answer handler `0x5dc9f0` resolves the GUID with typemask **8** (`0x468460` is a bitmask AND
+//! against `OBJECT_FIELD_TYPE`), so a GameObject's `0x21` returns NULL and the packet dies at
+//! `0x5dca2f` — and even if it did not, a GameObject has no `+0xcb8` status slot, no `+0xb2c`
+//! marker slot, and (11 models out of ~1600, none of them a poster) no attachment 18 to hang a
+//! marker from. So: **send the query, drop the answer, render nothing.**
 //!
 //! The server only ever *answers* `CMSG_QUESTGIVER_STATUS_QUERY` (vmangos `QuestHandler.cpp`) — it
 //! never pushes — so every refresh point is the client's own to trigger, and a status that is never
@@ -42,8 +42,8 @@ const NPC_FLAG_FLIGHTMASTER: u32 = 0x8;
 /// `GAMEOBJECT_FLAGS` bit **2** (mask `0x4`) — the whole of the sweep's GameObject gate, and the
 /// one place a GameObject GUID can reach this opcode at all.
 ///
-/// Byte-pinned (wow-re `questgiver-marker.md` §W14.6): `0x5eb0ef mov eax,[edx+0xc];
-/// 0x5eb0f2 shr eax,0x2; 0x5eb0f5 test al,1` — shift **2**, so mask `0x4`, not the `0x2` the unit
+/// Byte-pinned: `0x5eb0ef mov eax,[edx+0xc]; 0x5eb0f2 shr eax,0x2;
+/// 0x5eb0f5 test al,1` — shift **2**, so mask `0x4`, not the `0x2` the unit
 /// leg tests 25 bytes later. `[<GO block>+0xc]` is absolute field index 9 = `GAMEOBJECT_FLAGS`,
 /// named from the binary's own UpdateField name table (`0x83b8a8` → the string at `0x83be84`).
 /// The *name* `GO_FLAG_INTERACT_COND` is vmangos's, not the image's — but the bit is settled from
@@ -60,9 +60,9 @@ const GO_FLAG_INTERACT_COND: u32 = 0x4;
 /// The reference's refresh law is a **descriptor field watch**, not a hand-picked event list: it
 /// registers handlers on specific self-player fields through `0x468070`, and the handler sweeps
 /// every visible object (`0x5eb070` → `0x468380`, one query per object passing the questgiver
-/// gate). Byte-pinned in wow-re `questgiver-marker.md` §W1–W12; the benilla side, and the
-/// still-open gaps, are decision 0650 (the byte-level trigger set, superseding 0647's wrong
-/// "level is a deviation") and decision 0654 (what benilla implements of it).
+/// gate). The benilla side, and the still-open gaps, are decision 0650 (the byte-level trigger
+/// set, superseding 0647's wrong "level is a deviation") and decision 0654 (what benilla
+/// implements of it).
 ///
 /// **The sweep** — every visible questgiver is re-asked when any *self* input to the server's
 /// answer moves. The reference gets this from six descriptor watches plus four packet handlers;
@@ -85,8 +85,8 @@ const GO_FLAG_INTERACT_COND: u32 = 0x4;
 /// The wire corpus shows it happening in 20 of 62 real sessions.
 ///
 /// But there is **no bring-up query for a GameObject** — the contrast with units is exact and it
-/// is the point (wow-re §W14.8, a closed caller census: a GameObject GUID can reach this opcode
-/// through exactly two instructions in the whole image and both are inside a sweep callback; the
+/// is the point (a GameObject GUID can reach this opcode through exactly two instructions in the
+/// whole image and both are inside a sweep callback; the
 /// `CGGameObject_C` ctor and its vtable slot 3 call no sender, where `CGUnit_C`'s slot 3 does). So
 /// a GameObject is asked about only when a sweep happens to run while it is in view, and a player
 /// who completes a quest elsewhere and then walks up to the turn-in object never asks about it at
@@ -96,7 +96,7 @@ const GO_FLAG_INTERACT_COND: u32 = 0x4;
 /// ([`crate::net::apply`]'s own typemask gate), which is decision 1872's whole point.
 ///
 /// **The teardown legs — and there are two of them, neither the one this file used to claim**
-/// (decision 1906, wow-re §W15). `0x5eb0a0` is a **2×2 on (questgiver bit × reaction)**, and its
+/// (decision 1906). `0x5eb0a0` is a **2×2 on (questgiver bit × reaction)**, and its
 /// `0x5eb134` is a *convergent* block — reached both when the bit is clear (`0x5eb125 je`) and when
 /// the bit is set but the reaction failed (`0x5eb132 jg` not taken). That convergence is why three
 /// incompatible readings of this callback were live at once. The table:
@@ -165,7 +165,7 @@ pub(super) fn query_statuses(
     let generation = state.fields ^ (u64::from(quest.reask_epoch()) << 32);
     // **The FULL re-query sweep's own two triggers** (`0x5eb3c0`, both self-gated on
     // `IsLocalPlayer`): your **revive** — the `≤0 → >0` crossing that `0x6046f0` sends down the
-    // sibling branch of §W13's death edge — and a change to **your own record's** reaction inputs
+    // sibling branch of its death edge — and a change to **your own record's** reaction inputs
     // (`0x606e20` → `0x606eef`). Everything else in the trigger set reaches the *light* sweep
     // `0x5eb070`, which does not tear anything down. Tracked as edges rather than folded into the
     // generation because the direction is the whole point: the death edge is a light sweep and the
@@ -184,8 +184,8 @@ pub(super) fn query_statuses(
     // **This frame IS a sweep.** A sweep walks every object in the manager once, synchronously,
     // when one of the reference's local-player state changes fires it; a changed generation is that
     // moment. The GameObject leg below fires only on it, because that is the only way a GameObject
-    // GUID ever reaches the wire (§W14.8) — and a full sweep is a sweep too, even when it arrives
-    // through an edge the generation does not carry.
+    // GUID ever reaches the wire (`0x5eb159`, `0x5eb456`) — and a full sweep is a sweep too, even
+    // when it arrives through an edge the generation does not carry.
     let swept = state.generation != generation || full;
     state.generation = generation;
     // Object lifetime is the other half of the cache key: a guid that left the world drops both
@@ -228,7 +228,7 @@ pub(super) fn query_statuses(
             EntityKind::Unit => {
                 // `0x6061e0(ecx = the swept unit, arg = the player)` — the unit's reaction toward
                 // **us**, which is the direction both `call` sites in the callback use
-                // (`0x5eb12a`/`0x5eb137`, both `ecx = esi`; §W15 Q1b) and the direction
+                // (`0x5eb12a`/`0x5eb137`, both `ecx = esi`) and the direction
                 // [`ring_reaction`] resolves. `<= 1` is Hated/Hostile and nothing else: Unfriendly
                 // and Neutral both pass. It reads Neutral when anything is missing, so a cold
                 // catalog can never blank a marker.
@@ -286,7 +286,7 @@ pub(super) fn query_statuses(
                 }
             }
             // `0x5eb0da shr ecx,5; test cl,1` — typemask bit 5, `TYPEMASK_GAMEOBJECT`. Sweep-only,
-            // no asked-set, no teardown: see this function's doc and §W14.8.
+            // no asked-set, no teardown: see this function's doc.
             EntityKind::GameObject if swept => {
                 if obj.0.gameobject_flags() & GO_FLAG_INTERACT_COND == 0 {
                     continue;
@@ -338,7 +338,7 @@ fn self_generation(fields: &benilla_protocol::ObjectFields) -> u64 {
     };
     fold(u64::from(fields.unit_level().unwrap_or(0)));
     // Health enters as the ALIVE/DEAD bit, not the raw value — and that is the PINNED reading now,
-    // not a conservative guess (wow-re `questgiver-marker.md` §W13). The `UNIT_FIELD_HEALTH` watch
+    // not a conservative guess. The `UNIT_FIELD_HEALTH` watch
     // gates on the zero CROSSING, in `0x6046f0`, one level above where the handler chain suggested:
     // `0x604774 jg` / `0x604778 jle` require `old > 0 && new <= 0` = **death** before the sweep is
     // reached, and `0x6047f0`/`0x6047f4` take `old <= 0 && new > 0` = **resurrect** down the sibling
@@ -349,7 +349,7 @@ fn self_generation(fields: &benilla_protocol::ObjectFields) -> u64 {
     //
     // Our bit flips on BOTH crossings, and that is now known to be exactly right — the note this
     // comment used to carry ("one named over-refresh... the reference sweeps GameObject questgivers
-    // there") was wrong on both halves and is CORRECTED by wow-re §W14.5/§W14.11. `0x5eb3c0` is not
+    // there") was wrong on both halves. `0x5eb3c0` is not
     // a GameObject sweep: `0x468380` applies no type filter at all, so it walks **every** object in
     // the manager — it is the FULL re-query sweep, and its creature arm is the heavier one
     // (`0x607380`: an unconditional marker teardown plus two queries, questgiver `0x182` and taxi
@@ -617,8 +617,8 @@ mod tests {
         );
     }
 
-    /// **The light sweep re-asks; only the FULL sweep tears down first** (decision 1906,
-    /// wow-re §W15 Q1d). The two sweeps are not interchangeable and this is the difference:
+    /// **The light sweep re-asks; only the FULL sweep tears down first** (decision 1906).
+    /// The two sweeps are not interchangeable and this is the difference:
     /// `0x5eb0a0` (11 callers — level, money, the quest log, a skill, `PLAYER_FLAGS`, an item, your
     /// **death**, reputation, the group roster, the quest packets) sends and never tears down,
     /// while `0x5eb3f0` (2 callers — your **revive**, and your own record's reaction inputs) goes
@@ -704,7 +704,7 @@ mod tests {
         assert_eq!(asked(&mut app), 1, "a light sweep re-asks");
         assert_eq!(held(&app), Some(5), "…and does NOT tear the marker down");
 
-        // Your DEATH — the `>0 → ≤0` edge, which §W13 pins to the light sweep. Same rule.
+        // Your DEATH — the `>0 → ≤0` edge, which `0x6046f0` routes to the light sweep. Same rule.
         set_self(
             &mut app,
             &[(FIELD_LEVEL, 5), (FIELD_HEALTH, 0), (FIELD_FACTION, 1)],
@@ -735,8 +735,8 @@ mod tests {
         assert_eq!(held(&app), None, "…fully");
     }
 
-    /// **The sweep tears down on HOSTILITY, never on the questgiver flag** (decision 1906, wow-re
-    /// §W15 Q1a). `0x5eb0a0`'s `0x5eb134` is a convergent block, so the reaction test runs for
+    /// **The sweep tears down on HOSTILITY, never on the questgiver flag** (decision 1906).
+    /// `0x5eb0a0`'s `0x5eb134` is a convergent block, so the reaction test runs for
     /// every creature and `0x5eb143` is the callback's only teardown; the flag decides the *send*
     /// alone. On the real `FactionTemplate.dbc`, because a reaction gate that never resolves a real
     /// faction is not a gate.
@@ -846,7 +846,7 @@ mod tests {
     }
 
     /// **The flight master's green `!` shares one slot with the gold one, so it shares its
-    /// lifetime** (decision 1918, wow-re §W16). Three things, and the middle one is the asymmetry
+    /// lifetime** (decision 1918). Three things, and the middle one is the asymmetry
     /// a re-implementer gets wrong:
     ///
     /// - `CMSG_TAXINODE_STATUS_QUERY` has **one** live sender site image-wide, `0x607380`
@@ -1003,9 +1003,9 @@ mod tests {
         );
     }
 
-    /// **A GameObject is asked about on a SWEEP, and only on a sweep** (decision 1872, wow-re
-    /// `questgiver-marker.md` §W14.6/§W14.8). Three things are being pinned here, and the third is
-    /// the one a client "improves" without noticing:
+    /// **A GameObject is asked about on a SWEEP, and only on a sweep** (decision 1872; its only
+    /// send sites, `0x5eb159` and `0x5eb456`, sit in sweep callbacks). Three things are being
+    /// pinned here, and the third is the one a client "improves" without noticing:
     ///
     /// - the gate is `GAMEOBJECT_FLAGS` bit 2 (mask `0x4`) — `0x5eb0ef shr eax,0x2; test al,1` —
     ///   and a quest-less GameObject beside it is never asked about at all;
@@ -1101,7 +1101,7 @@ mod tests {
             asked(&mut app),
             vec![NPC],
             "first sight: the creature is asked from its own create path, the poster is NOT — \
-             the GameObject class has no bring-up query (§W14.8)"
+             the GameObject class has no bring-up query"
         );
         assert!(
             asked(&mut app).is_empty(),
diff --git a/crates/benilla-app/src/raid_marks.rs b/crates/benilla-app/src/raid_marks.rs
index d27e3328..d998dc35 100644
--- a/crates/benilla-app/src/raid_marks.rs
+++ b/crates/benilla-app/src/raid_marks.rs
@@ -1,18 +1,18 @@
-//! Raid-target marker **overhead billboards** — wow-re `name-render-geometry-law.md` §6
-//! (VERIFIED): for each unit holding a mark on the 8-slot board (decision 0434 §6,
+//! 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}`.
 //!
-//! Seat (§6): 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`;
+//! 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).
 //!
-//! Size (VERIFIED, wow-re `name-render-geometry-law.md` §6, commit 5e78ea75): the marker is a
+//! 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
@@ -35,7 +35,7 @@ use benilla_world::view::WorldCamera;
 /// rows and the plate child slice.
 const MARK_TEXTURE: &str = "mpq://interface/targetingframe/ui-raidtargetingicons.blp";
 
-/// The marker's world size (VERIFIED, wow-re §6 / commit 5e78ea75): a **fixed** world unit,
+/// 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).
@@ -61,8 +61,8 @@ pub(crate) struct RaidMarks {
 #[derive(Component)]
 struct RaidMarkBillboard;
 
-/// The §6 quad 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 positions (local X ∈ [−.5, .5],
+/// Y ∈ [0, 1], bottom anchored), the atlas cell UVs, the ref's own index list.
 fn mark_mesh(icon: u32) -> Mesh {
     use bevy::asset::RenderAssetUsages;
     use bevy::mesh::{Indices, PrimitiveTopology};
@@ -95,7 +95,7 @@ fn mark_mesh(icon: u32) -> Mesh {
     mesh
 }
 
-/// The marker's world transform for `unit` this frame — the §6 seat over the shared
+/// 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).
 fn mark_place<F: bevy::ecs::query::QueryFilter>(
@@ -111,8 +111,8 @@ fn mark_place<F: bevy::ecs::query::QueryFilter>(
 ) -> 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 (§6:
-    // `scale` never enters the marker geometry), not `scale`-scaled.
+    // 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.
     let scale = height_scale(anchor.y - tf.translation.y);
     let lift = match plates.line_count(unit) {
         Some(lines) => (lines as f32 + 1.0) * scale,
@@ -289,9 +289,9 @@ impl Plugin for RaidMarksPlugin {
 mod tests {
     use super::*;
 
-    /// The §6 quad against the verified 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.
+    /// 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.
     #[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 f32ad69e..572973de 100644
--- a/crates/benilla-app/src/ranged_flex.rs
+++ b/crates/benilla-app/src/ranged_flex.rs
@@ -32,18 +32,13 @@
 //! **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 and why a
-//! wow-re round briefly published the opposite reading.
+//! that has never once been switched on; that false negative is why this shipped broken.
 //!
-//! **wow-re recorded the opposite**, flagged INFERRED: `ranged-shot-anim.md` read the mechanism as
-//! "bow-only by asset … gun/crossbow/thrown/wand have **no** analogous prop re-anim call anywhere
-//! (exhaustive search)". The rifle arm is in the same function as the bow arm, eleven instructions
-//! apart. The §5 correction round landed as wow-re `ranged-prop-reanim-two-arm.md`: the fork is
-//! CONFIRMED in every detail, and its census finds **exactly four** sites that arm `[+0xd24]` —
-//! `0x624e31` (160), `0x600209` (0), `0x600273` (161) and `0x60f59d` (0, the reset below). The
-//! surviving, precise form of "no analog" is **thrown and wand**: 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.
+//! **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
@@ -139,15 +134,15 @@ pub(crate) fn flex_ranged_props(
         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** (wow-re
-        // `ranged-prop-reanim-two-arm.md`, claim B). `$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 there: 571/571 resolve). So a rifle-family body
-        // holding a model without 161 re-arms Stand, it does not leave the prop alone.
+        // **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.
         let want = if want == BOW_PULL {
             if !anims.owns(BOW_PULL) {
                 continue;
@@ -169,7 +164,7 @@ pub(crate) fn flex_ranged_props(
         // builds from the block's window. Everything else plays at the literal 1.0 both `$BWR`
         // arms push (`0x3f800000`).
         let speed = if want == BOW_PULL {
-            // **`n <= 0` is NO FLEX THAT SHOT, not a flex at 1.0** (`0x624d91 jle`, claim C): the
+            // **`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.
             let Some(left) = wearers
                 .get(ev.entity)
@@ -217,9 +212,8 @@ pub(crate) fn flex_ranged_props(
     }
 }
 
-/// **The un-nock's reset — `0x60f59d`, and its condition is INVERTED from what wow-re's prose
-/// said.** `ranged-shot-anim.md` read it as "re-arms the prop to Stand(0) **after** release"; the
-/// bytes say **UNLESS** it is releasing:
+/// **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:
 ///
 /// ```text
 /// 60f578  push -1 ; call 0x712090   ; the prop's CURRENT requested animation id
@@ -231,7 +225,7 @@ pub(crate) fn flex_ranged_props(
 /// `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 (wow-re `ranged-prop-reanim-two-arm.md`, claim D).
+/// 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
@@ -538,10 +532,10 @@ mod tests {
         );
     }
 
-    /// **The reset's guard, which is what the round corrected** (`0x60f584 je`): the un-nock
-    /// re-arms Stand **unless** the prop is releasing. Taken the other way round — "reset after
-    /// release", which is how wow-re's prose read — 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 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.
     #[test]
     fn the_unnock_resets_a_drawn_prop_but_never_a_releasing_one() {
         fn unnock(prop_anims: ModelAnimations, armed: u16) -> Option<AnimationNodeIndex> {
diff --git a/crates/benilla-app/src/realm_select/input.rs b/crates/benilla-app/src/realm_select/input.rs
index b7fafcb9..a7a51c36 100644
--- a/crates/benilla-app/src/realm_select/input.rs
+++ b/crates/benilla-app/src/realm_select/input.rs
@@ -9,6 +9,7 @@
 use bevy::input::mouse::MouseWheel;
 use bevy::prelude::*;
 
+use crate::bindings::WheelNotches;
 use crate::net::{RealmChoice, RealmRequest};
 use crate::sound::GlueSound;
 
@@ -72,7 +73,7 @@ pub(super) fn clicks(
 /// `RealmList_OnKeyDown` (ESCAPE / ENTER), plus arrow-key row cycling and the wheel.
 pub(super) fn keys(
     keys: Res<ButtonInput<KeyCode>>,
-    mut wheel: MessageReader<MouseWheel>,
+    (mut wheel, mut wheel_carry): (MessageReader<MouseWheel>, Local<WheelNotches>),
     mut realms: ResMut<Realms>,
     choice: Res<RealmChoice>,
     mut sounds: MessageWriter<GlueSound>,
@@ -111,10 +112,7 @@ pub(super) fn keys(
     // 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).
-    let mut notches = 0i32;
-    for ev in wheel.read() {
-        notches -= ev.y.signum() as i32;
-    }
+    let notches = wheel_rows(&mut wheel_carry, wheel.read());
     if notches != 0 {
         let max = rows.len().saturating_sub(MAX_ROWS);
         let next_off = (realms.offset as i32 + notches).clamp(0, max as i32) as usize;
@@ -122,6 +120,20 @@ 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.
+fn wheel_rows<'a>(
+    carry: &mut WheelNotches,
+    wheel: impl IntoIterator<Item = &'a MouseWheel>,
+) -> i32 {
+    wheel
+        .into_iter()
+        .map(|ev| -carry.feed(crate::bindings::wheel_lines(ev.unit, ev.y)))
+        .sum()
+}
+
 /// The realm on a given **screen** row, honouring the scroll offset.
 fn realm_at(realms: &Realms, row: usize) -> Option<String> {
     let rows = realms.rows();
@@ -193,3 +205,49 @@ fn try_enter(realms: &mut Realms, choice: &RealmChoice, sounds: &mut MessageWrit
     realms.hide();
     realms.enter(choice, name);
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use bevy::input::mouse::MouseScrollUnit;
+
+    fn ev(unit: MouseScrollUnit, y: f32) -> MouseWheel {
+        MouseWheel {
+            unit,
+            x: 0.0,
+            y,
+            window: Entity::PLACEHOLDER,
+        }
+    }
+
+    /// **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.
+    #[test]
+    fn a_trackpad_trickle_scrolls_only_the_rows_it_adds_up_to() {
+        let mut carry = WheelNotches::default();
+        let step = MouseScrollUnit::SCROLL_UNIT_CONVERSION_FACTOR / 10.0;
+        let trickle: Vec<MouseWheel> = (0..10).map(|_| ev(MouseScrollUnit::Pixel, -step)).collect();
+        let rows: i32 = trickle
+            .iter()
+            .map(|e| wheel_rows(&mut carry, std::iter::once(e)))
+            .sum();
+        assert!(
+            (0..=1).contains(&rows),
+            "one line of travel moved {rows} rows"
+        );
+    }
+
+    /// A mouse wheel's notch is one `Line` message and one row, as it always was.
+    #[test]
+    fn a_line_notch_scrolls_one_row() {
+        let mut carry = WheelNotches::default();
+        assert_eq!(
+            wheel_rows(&mut carry, &[ev(MouseScrollUnit::Line, -1.0)]),
+            1
+        );
+        assert_eq!(
+            wheel_rows(&mut carry, &[ev(MouseScrollUnit::Line, 1.0)]),
+            -1
+        );
+    }
+}
diff --git a/crates/benilla-app/src/realm_select/load.rs b/crates/benilla-app/src/realm_select/load.rs
index b94cb5cc..75307376 100644
--- a/crates/benilla-app/src/realm_select/load.rs
+++ b/crates/benilla-app/src/realm_select/load.rs
@@ -14,9 +14,9 @@
 //! 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 wow-re's byte-exact
-//! `crates/glue/src/realm.rs` (`CGlue::RealmLoadStats` `0x46e510` and `CGlue::RealmLoadClassify`
-//! `0x46ec60`), including their x87 rounding behaviour — the accumulators round to `f32` every
+//! [`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.
@@ -161,8 +161,7 @@ pub(super) fn type_column(realm_type: u32) -> (&'static str, Color) {
 /// **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; wow-re's earlier band sweep had attributed the
-/// type to `[+0x130]`, which is really `numCharacters`.)
+/// `[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
@@ -173,8 +172,6 @@ pub(super) fn type_column(realm_type: u32) -> (&'static str, Color) {
 /// 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.
-///
-/// VERIFIED, wow-re `system/glue/scratch/realm-list-bindings.md` §3.
 pub(crate) fn pvp_rp(realm_type: u32) -> (bool, bool) {
     match realm_type {
         // RealmType → (PlayerKillingAllowed, RoleplayingRealm)
diff --git a/crates/benilla-app/src/realm_select/mod.rs b/crates/benilla-app/src/realm_select/mod.rs
index 592b3894..c9b1cbeb 100644
--- a/crates/benilla-app/src/realm_select/mod.rs
+++ b/crates/benilla-app/src/realm_select/mod.rs
@@ -60,7 +60,7 @@
 //! 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 (VERIFIED, wow-re):
+//! 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*,
@@ -82,9 +82,8 @@ 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 from it, wow-re `savedvariables-protocol.md`), already registered
-/// by [`crate::cvars`] and pushed into the VM at world entry by
-/// `benilla_ui::script::UiScript::set_realm_name`.
+/// 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.
@@ -120,9 +119,9 @@ pub(crate) struct Realms {
     /// 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** (VERIFIED, wow-re:
-    /// `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
+    /// **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
@@ -262,9 +261,7 @@ impl Realms {
     /// 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. (VERIFIED, wow-re
-    /// `system/glue/scratch/realm-list-bindings.md` §5 — which corrected wow-re's own doc comment
-    /// in the same pass.)
+    /// switching tabs does not move any row's 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)
diff --git a/crates/benilla-app/src/realmlist.rs b/crates/benilla-app/src/realmlist.rs
index d54e592f..590ee82b 100644
--- a/crates/benilla-app/src/realmlist.rs
+++ b/crates/benilla-app/src/realmlist.rs
@@ -5,9 +5,9 @@
 //! 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; wow-re `mpq/scratch/startup-order-A.md`
-//! row 62 records the same registration.) benilla keeps the **name, the `host[:port]` shape and
-//! the help string**, and replaces the text editor with a control on the login screen.
+//! 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.
 //!
 //! **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
diff --git a/crates/benilla-app/src/run_mode.rs b/crates/benilla-app/src/run_mode.rs
index 6244f737..53790811 100644
--- a/crates/benilla-app/src/run_mode.rs
+++ b/crates/benilla-app/src/run_mode.rs
@@ -69,21 +69,19 @@ pub(crate) fn capture_ui_opted_in() -> bool {
     false
 }
 
-/// **Do the credentials come from the environment?** (`$WOW_USER` / `$WOW_PASS` / `$WOW_CHAR` —
-/// the login screen's env fast path.)
+/// **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 none of these set the client opens at
-/// the login screen and waits for somebody to type. Setting any of them 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.
-///
-/// One environment fact, several readers, no shared symbol — the module doc's pattern, same as
-/// [`scenario_active`], and the reason the roster's `WOW_CHAR` fast path asks here instead of
-/// re-reading the three names.
+/// 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.
 pub(crate) fn env_login() -> bool {
-    ["WOW_USER", "WOW_PASS", "WOW_CHAR"]
+    ["WOW_USER", "WOW_PASS"]
         .iter()
-        .any(|k| std::env::var_os(k).is_some())
+        .all(|k| std::env::var_os(k).is_some())
 }
 
 /// **Is there nobody here?** (`$WOW_UNATTENDED`, or the two runs that are automated by
@@ -107,8 +105,8 @@ pub(crate) fn env_login() -> bool {
 ///
 /// `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/leg.sh`, `smoke.sh`, `cine.sh`,
-/// `summon-live.sh` and the ad-hoc probe recipe in `method.md` all pass `WOW_UNATTENDED=1`.
+/// cannot forget to. Everything else declares — `scripts/smoke.sh`, `cine.sh`, `summon-live.sh`
+/// and the ad-hoc probe recipe in the `probe` skill 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
@@ -124,14 +122,14 @@ pub(crate) fn unattended() -> bool {
 /// (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 `scripts/leg.sh` keys on, rather than parking a driverless run on a dialog for
+/// 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 `leg.sh` greps for.
+/// apart on either the verdict or the marker a leg runner greps for.
 pub(crate) fn fatal_when_driverless(why: &str) -> bool {
     if unattended() {
         error!("login: FATAL — {why}; exiting");
@@ -248,108 +246,101 @@ 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 build lives in a worktree pool slot and
-/// the fast path is about to authenticate as an account that belongs to somebody else — the
-/// director's `one` (a login KICKS their live session mid-play) or another slot's `probeN` (the
-/// kicked client's 0065 teardown despawns every net entity, so a parallel session's probe reads a
-/// unit-less world and prints garbage; it happened, method.md records it).
+/// ([`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.
 ///
-/// Slot identity comes from the compiled-in manifest path, because that is what the pool guarantees
-/// is unique per session: every slot has its own checkout and its own `target/`. Outside a pool slot
-/// (the primary checkout, which is the director's) 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`
+/// 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.
 pub(crate) fn account_guard(user: &str) -> Result<(), String> {
-    guard_for(compiled_slot(), user)
+    guard_for(declared_identity().as_ref(), user)
 }
 
-/// The pool slot this binary was *compiled* in, or `None`.
-///
-/// A player build is never in a pool slot, so 1174 read `env!("CARGO_MANIFEST_DIR")`
-/// unconditionally on the grounds that the ladder collapses to `Ok(())` anyway. It does — but the
-/// path is still a **string in the shipped binary**, naming the build machine's home directory,
-/// which is the one thing decision 1175 exists to end (its falsifier is literally
-/// `strings <player binary> | grep -c '/Users/…'`). It costs one `cfg` to not ship it, and it is
-/// what makes that falsifier readable: after this, the only source-tree paths left in a player
-/// binary are debuginfo and panic metadata, never data the program acts on.
+/// 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.
+#[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.
 #[cfg(feature = "dev")]
-fn compiled_slot() -> Option<u32> {
-    pool_slot(env!("CARGO_MANIFEST_DIR"))
+pub(crate) fn declared_identity() -> Option<DeclaredIdentity> {
+    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .ancestors()
+        .nth(2)?;
+    parse_identity(&std::fs::read_to_string(root.join(".probe-identity")).ok()?)
 }
 
 #[cfg(not(feature = "dev"))]
-fn compiled_slot() -> Option<u32> {
+pub(crate) fn declared_identity() -> Option<DeclaredIdentity> {
     None
 }
 
-/// [`account_guard`]'s decision, with the slot passed in so the ladder is testable from any
-/// checkout (the real one reads a compile-time path that differs per worktree).
-fn guard_for(slot: Option<u32>, user: &str) -> Result<(), String> {
-    let Some(slot) = slot else {
+/// 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).
+#[cfg_attr(not(feature = "dev"), allow(dead_code))]
+fn parse_identity(text: &str) -> Option<DeclaredIdentity> {
+    let field = |key: &str| {
+        text.lines()
+            .filter_map(|l| l.trim().strip_prefix(key)?.strip_prefix('='))
+            .map(|v| v.trim().trim_matches('"').to_string())
+            .find(|v| !v.is_empty())
+    };
+    Some(DeclaredIdentity {
+        user: field("WOW_USER")?,
+        character: field("WOW_CHAR")?,
+    })
+}
+
+/// [`account_guard`]'s decision, with the declaration passed in so it is testable without a file.
+fn guard_for(declared: Option<&DeclaredIdentity>, user: &str) -> Result<(), String> {
+    let Some(id) = declared else {
         return Ok(());
     };
-    let mine = format!("probe{slot}");
-    let user_lc = user.to_ascii_lowercase();
-    if user_lc == mine {
+    if user.eq_ignore_ascii_case(&id.user) {
         return Ok(());
     }
-    let whose = if user_lc == "one" {
-        "the DIRECTOR's account — logging in on it kicks them out of their live session mid-play"
-    } else if user_lc.starts_with("probe") && user_lc[5..].chars().all(|c| c.is_ascii_digit()) {
-        "ANOTHER worktree slot's probe account — logging in on it kicks that session's probe out \
-         of the world, and its next sample reads a unit-less world"
-    } else {
-        return Ok(()); // a bystander account (`two`, a fresh test account): not ours to police
-    };
     Err(format!(
-        "the env fast path is about to log in as `{user}` from pool-{slot}, and that is {whose}. \
-         This slot's identity is WOW_USER=probe{slot} WOW_PASS=pprobe{slot} \
-         WOW_CHAR=Probe{spelled} (method.md \"The local vmangos server\").",
-        spelled = spell_digit(slot)
+        "the env fast path is about to log in as `{user}`, and this checkout's .probe-identity \
+         declares `{}` (WOW_CHAR={}). A login kicks whoever holds `{user}` — a player mid-session, \
+         or another checkout's probe.",
+        id.user, id.character
     ))
 }
 
-/// This slot's index as the word the probe identity spells it with (`pool-4` → `"four"`), or `None`
-/// outside a pool slot. The one place anything else should ask "which session am I?" — the rig keys
-/// its derived character names off it, and the preflight banner names it.
-pub(crate) fn slot_word() -> Option<&'static str> {
-    compiled_slot().map(spell_digit)
+/// 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.
+pub(crate) fn rig_suffix() -> Option<String> {
+    Some(suffix_of(&declared_identity()?.character))
 }
 
-/// The pool slot index in a `…/benilla-wt/pool-<N>/…` manifest path; `None` for the primary
-/// checkout and any non-pool worktree. Dev-only, because [`compiled_slot`] is its only caller and
-/// a player build must not name a manifest path at all (1175).
-#[cfg(any(feature = "dev", test))]
-fn pool_slot(manifest_dir: &str) -> Option<u32> {
-    let mut parts = manifest_dir.split('/');
-    while let Some(part) = parts.next() {
-        if part == "benilla-wt" {
-            return parts.next()?.strip_prefix("pool-")?.parse().ok();
-        }
-    }
-    None
-}
-
-/// The probe character's name suffix for slot `n` — vmangos names carry no digits, so the pool
-/// index is spelled (`pool-4` → `Probefour`).
-fn spell_digit(n: u32) -> &'static str {
-    match n {
-        0 => "zero",
-        1 => "one",
-        2 => "two",
-        3 => "three",
-        4 => "four",
-        5 => "five",
-        6 => "six",
-        7 => "seven",
-        8 => "eight",
-        9 => "nine",
-        _ => "<n>",
-    }
+fn suffix_of(character: &str) -> String {
+    let name = character.to_ascii_lowercase();
+    let word = name
+        .strip_prefix("probe")
+        .filter(|w| !w.is_empty())
+        .unwrap_or(&name);
+    word.chars()
+        .filter(char::is_ascii_alphabetic)
+        .take(6)
+        .collect()
 }
 
 #[cfg(test)]
@@ -479,44 +470,45 @@ mod tests {
     }
 
     #[test]
-    fn the_guard_only_polices_accounts_that_belong_to_someone() {
-        // Our own slot's probe: the whole point of the identity.
-        assert!(guard_for(Some(4), "probe4").is_ok());
-        assert!(guard_for(Some(4), "PROBE4").is_ok()); // vmangos accounts are case-insensitive
-                                                       // The director's account, and a neighbouring slot's probe: both kick a live session.
-        let director = guard_for(Some(4), "one").unwrap_err();
-        assert!(director.contains("DIRECTOR") && director.contains("WOW_USER=probe4"));
+    fn the_fast_path_is_the_declared_account_or_refused() {
+        let id = parse_identity("WOW_USER=probe4\nWOW_PASS=pprobe4\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.
+        let player = guard_for(Some(&id), "one").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!(!director.contains("WOW_ALLOW_ACCOUNT"));
-        assert!(guard_for(Some(4), "probe7")
-            .unwrap_err()
-            .contains("ANOTHER worktree slot"));
-        // A bystander account is nobody's to police, and outside a pool slot we have no standing.
-        assert!(guard_for(Some(4), "two").is_ok());
+        assert!(!player.contains("WOW_ALLOW_ACCOUNT"));
+        assert!(guard_for(Some(&id), "probe7").is_err());
+        // No declaration, no standing.
         assert!(guard_for(None, "one").is_ok());
     }
 
     #[test]
-    fn the_probe_character_name_spells_the_slot() {
-        // vmangos player names carry no digits, so `Probe4` cannot exist — the pool index is spelled.
-        assert!(guard_for(Some(0), "one")
-            .unwrap_err()
-            .contains("WOW_CHAR=Probezero"));
-        assert!(guard_for(Some(9), "one")
-            .unwrap_err()
-            .contains("WOW_CHAR=Probenine"));
+    fn the_declaration_needs_the_account_and_the_character() {
+        assert_eq!(
+            parse_identity("WOW_USER=probe4\nWOW_PASS=x\nWOW_CHAR=\"Probefour\"\n"),
+            Some(DeclaredIdentity {
+                user: "probe4".into(),
+                character: "Probefour".into()
+            })
+        );
+        assert!(parse_identity("WOW_USER=probe4\nWOW_PASS=x\n").is_none());
+        assert!(parse_identity("WOW_USER=\nWOW_CHAR=Probefour\n").is_none());
+        assert!(parse_identity("").is_none());
     }
 
     #[test]
-    fn the_slot_is_read_off_the_manifest_path() {
-        assert_eq!(
-            pool_slot("/Users/sam/dev/benilla-wt/pool-7/crates/benilla"),
-            Some(7)
-        );
-        assert_eq!(pool_slot("/Users/sam/dev/benilla-wow/crates/benilla"), None);
-        assert_eq!(
-            pool_slot("/Users/sam/dev/benilla-wow/.claude/worktrees/x/crates/benilla"),
-            None
-        );
+    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.
+        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.
+        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 e0b6fab5..bd526f0c 100644
--- a/crates/benilla-app/src/screen_fade.rs
+++ b/crates/benilla-app/src/screen_fade.rs
@@ -12,9 +12,7 @@
 //! 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. See `wow-5875-re`
-//! `system/ui/scratch/cinematic-camera-law.md` §3.7, which verified this as a correction to an
-//! earlier reading that had it as a delay.
+//! 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
@@ -162,7 +160,7 @@ fn spawn_cover(mut commands: Commands) {
         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 (law §8.4). A fade below the cover could not
+        // 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.
diff --git a/crates/benilla-app/src/screenshot.rs b/crates/benilla-app/src/screenshot.rs
index 35eb57a6..3dbe75c7 100644
--- a/crates/benilla-app/src/screenshot.rs
+++ b/crates/benilla-app/src/screenshot.rs
@@ -37,9 +37,8 @@
 //! **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. This is the "mandatory unfaithful
-//!     change" the report came in with; the mechanism, the folder and the naming are otherwise the
-//!     reference's.
+//!     ~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.
 //!
diff --git a/crates/benilla-app/src/shaders/ui_add.wgsl b/crates/benilla-app/src/shaders/ui_add.wgsl
index 66c26f59..7d8e77ac 100644
--- a/crates/benilla-app/src/shaders/ui_add.wgsl
+++ b/crates/benilla-app/src/shaders/ui_add.wgsl
@@ -1,21 +1,15 @@
-// WoW `alphaMode="ADD"` for Bevy UI — the glue highlight overlays (`ButtonHilight-Square`, the
-// arrow/panel/scroll `Highlight`s, `UI-Common-MouseHilight`) draw with a TRUE additive blend
-// state (set Rust-side in `AddUiMaterial::specialize`); this fragment only samples the authored
-// sub-rect (uv min/max — the sheets store the button region in a corner/quarter).
-//
-// On the UI gamma composite lane (decision 0254) like its siblings `ui_node_gamma.wgsl` /
-// `ui_slice_gamma.wgsl`: the texel goes back to the client's byte space, so the `SrcAlpha/One`
-// blend state resolves to the reference's byte add `dst + texel·α` (EGxBlend 3 =
-// `glBlendFunc(GL_SRC_ALPHA, GL_ONE)`; wow-re `system/gx/gx.md`). Emitting the linear texel instead
-// would let the hardware add a linearised glow, landing every highlight's dim skirt at a different
-// weight than the reference's — the same error 0160 caught for the world's additive sources.
+// 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)`).
 #import bevy_ui::ui_vertex_output::UiVertexOutput
 
 @group(1) @binding(0) var texture: texture_2d<f32>;
 @group(1) @binding(1) var texture_sampler: sampler;
 @group(1) @binding(2) var<uniform> rect: vec4<f32>;
 
-// Linear → sRGB (IEC 61966-2-1) — the exact inverse of the sampler's sRGB decode.
+// Linear to sRGB (IEC 61966-2-1), the exact inverse of the sampler's sRGB decode.
 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;
diff --git a/crates/benilla-app/src/shaders/ui_gamma.wgsl b/crates/benilla-app/src/shaders/ui_gamma.wgsl
index 854dfb82..cfc1243d 100644
--- a/crates/benilla-app/src/shaders/ui_gamma.wgsl
+++ b/crates/benilla-app/src/shaders/ui_gamma.wgsl
@@ -1,23 +1,17 @@
-// The UI gamma lane's ONE decode (decision 0254) — the twin of `ffx_glow.wgsl`'s combine, which owns
-// the world lane's single decode (0161) — and the client's display-gamma ramp (2182), which rides in
-// front of it because the value this pass samples is exactly the byte the RAMDAC would have read.
-//
-// `ui_quad.wgsl` composites the whole UI in gamma bytes, like the reference's fixed-function
-// backbuffer. The UI camera's target is `Rgba8UnormSrgb`, so a stored byte round-trips through the
-// hardware's encode/decode and the sampler hands this pass back the gamma value the UI pass wrote.
-// Emitting `srgb_to_linear` of it re-encodes on write to the exact client byte — written straight
-// into the swapchain (decision 2206: the camera's output mode is `Skip`, so no blit follows).
-//
-// RGB is premultiplied by coverage; alpha is coverage and carries no gamma, so it passes through.
+// 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.
 
 #import bevy_core_pipeline::fullscreen_vertex_shader::FullscreenVertexOutput
 
 @group(0) @binding(0) var screen_texture: texture_2d<f32>;
 @group(0) @binding(1) var screen_sampler: sampler;
-// `.x` = the `gamma` CVar. The rest is padding — a uniform struct is 16-byte aligned.
+// `.x` = the `gamma` CVar; the rest is padding (a uniform is 16-byte aligned).
 @group(0) @binding(2) var<uniform> ramp: vec4<f32>;
 
-// sRGB → linear (IEC 61966-2-1), the exact inverse of `ui_quad.wgsl`'s `linear_to_srgb`.
+// sRGB to linear (IEC 61966-2-1), the exact inverse of `ui_quad.wgsl`'s `linear_to_srgb`.
 fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
     let higher = pow((max(c, vec3<f32>(0.0)) + vec3<f32>(0.055)) / 1.055, vec3<f32>(2.4));
     let lower = c / 12.92;
@@ -28,13 +22,9 @@ 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 `ramp[i] = pow(i/255, gamma)` (`0x591680`), in its continuous
-    // form: `i/255` IS `rgb` here, so this is the same curve over the same values.
-    //
-    // **The branch is not an optimisation.** It is uniform across the draw, so it costs nothing —
-    // and at the registered default the pass has to be the exact identity it was before this
-    // existed, which `pow` is not: `pow(x, 1.0)` compiles to `exp2(log2(x))` and `log2(0)` is
-    // undefined. The floor inside the taken arm is the same guard for a non-default gamma.
+    // 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.
     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 a215e482..9f8fa095 100644
--- a/crates/benilla-app/src/shaders/ui_node_gamma.wgsl
+++ b/crates/benilla-app/src/shaders/ui_node_gamma.wgsl
@@ -1,23 +1,12 @@
-// The glue screens' Bevy-UI node shader, on the UI **gamma composite lane** (decision 0254).
+// 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.
 //
-// VENDORED from `bevy_ui_render` 0.18.1 `src/ui.wgsl`. Everything below is that file verbatim —
-// the rounded-box SDF, the border/AA math, the vertex stage — EXCEPT the fragment's colour
-// computation, which is moved into the client's byte space (marked THE ONE CHANGE below). Bevy UI
-// exposes no colour-space hook, and its pipeline takes one shader handle for both stages, so the
-// whole file has to come along. Re-diff against upstream on every Bevy upgrade: a structural change
-// (vertex attributes, bind groups) fails loudly at pipeline validation, but a fragment-side tweak
-// would drift silently. `bevy = "0.18.1"` is pinned in Cargo.toml.
-//
-// Why: the reference draws its glue screens through a fixed-function device into an 8-bit
-// backbuffer, so every UI multiply AND every UI blend is arithmetic on GAMMA BYTES. Bevy UI
-// composites in linear, which over the login scene's bright sky washed the edit boxes from the
-// reference's byte ~77 to ~138 — the director's "input and button are too faint", measured. This
-// fragment hands the pipeline a RAW GAMMA value; the target is `Rgba8UnormSrgb`, so the hardware
-// blend reads back exactly what was written and the `(SrcAlpha, OneMinusSrcAlpha)` blend runs on
-// gamma values — the reference's byte arithmetic. `ui_gamma.wgsl` then owns the frame's ONE decode.
-//
-// The `#define_import_path` line of the original is deliberately dropped: two modules claiming
-// `bevy_ui::ui_node` would collide.
+// 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.
 
 #import bevy_render::view::View
 
@@ -35,9 +24,8 @@ fn enabled(flags: u32, mask: u32) -> bool {
     return (flags & mask) != 0u;
 }
 
-// Linear → sRGB (the exact IEC 61966-2-1 curve the hardware's sRGB store uses, so this inverts the
-// sampler's decode bit-for-bit in f32). Alpha carries no gamma and never passes through here.
-// Identical to `ui_quad.wgsl`'s — the player-UI lane's twin of this conversion.
+// 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.
 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;
@@ -242,16 +230,10 @@ fn draw_uinode_background(
 fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
     let texture_color = textureSample(sprite_texture, sprite_sampler, in.uv);
 
-    // ── THE ONE CHANGE from the vendored original ────────────────────────────────────────────────
-    // Upstream computes `select(in.color, in.color * texture_color, TEXTURED)` — a LINEAR product
-    // handed to a linear blend. Both factors go back to the client's byte space FIRST, and the
-    // multiply happens there: `in.color` is a linearised authored sRGB colour (FrameXML `<Color>`,
-    // the glue palette) and the sampler already decoded the sRGB art, so encoding each factor
-    // recovers exactly the two authored bytes the reference's FFP multiplies. Encoding each factor
-    // separately — rather than the product — matters: sRGB's linear toe makes `encode(a*b)` and
-    // `encode(a)*encode(b)` diverge in the darks, which is precisely where the edit-box fills live
-    // (byte 13 vs byte 7 for the `DEFAULT_TOOLTIP_COLOR` fill).
-    // Alpha is coverage, carries no gamma, and multiplies unchanged.
+    // ── 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.
     let textured = enabled(in.flags, TEXTURED);
     let tint = linear_to_srgb(in.color.rgb);
     let texel = linear_to_srgb(texture_color.rgb);
@@ -259,7 +241,7 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
         select(tint, tint * texel, textured),
         select(in.color.a, in.color.a * texture_color.a, textured),
     );
-    // ── end of the change; the rest is upstream verbatim ─────────────────────────────────────────
+    // ── end of the change ──
 
     if enabled(in.flags, BORDER_ANY) {
         return draw_uinode_border(color, in.point, in.size, in.radius, in.border, in.flags);
diff --git a/crates/benilla-app/src/shaders/ui_quad.wgsl b/crates/benilla-app/src/shaders/ui_quad.wgsl
index a28df927..8ba8af8e 100644
--- a/crates/benilla-app/src/shaders/ui_quad.wgsl
+++ b/crates/benilla-app/src/shaders/ui_quad.wgsl
@@ -1,33 +1,24 @@
-// The player-UI quad material (decision 0068 §2's sorted-quad pass), on the UI **gamma composite
-// lane** (decision 0254 — the UI sibling of 0161's world lane).
-//
-// The reference draws the whole UI through its fixed-function device into an 8-bit backbuffer, so
-// every UI multiply AND every UI blend is arithmetic on GAMMA BYTES. We reproduce that here: the
-// fragment puts its texel back into the client's byte space, does the tint/premultiply there, and
-// hands the pipeline a RAW GAMMA value. Under the `(One, OneMinusSrcAlpha)` blend state the
-// hardware then composes in gamma, and (because the target is 8-bit unorm) clamps at every write,
-// exactly like the reference's byte buffer:
+// 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:
 //   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 without splitting the pipeline. The frame's single
-// gamma→linear decode happens once afterwards, in `ui_gamma.wgsl` — the twin of the FFXGlow
-// combine owning the world lane's one decode.
+// so a per-material flag picks the mode on one pipeline. The frame's one gamma-to-linear decode
+// is `ui_gamma.wgsl`.
 //
-// Why the encode below, rather than uploading UI art as raw `Rgba8Unorm`: our BLPs load as
-// `Rgba8UnormSrgb`, so the sampler hands us a LINEARIZED texel. `linear_to_srgb` puts the authored
-// byte back (exact in f32: encode ∘ decode = identity), and it is the rule for every texture the
-// pass samples — sRGB art, the sRGB glyph atlas, and the portrait booth's `Rgba8Unorm` bake (which
-// stores linear bytes) — EXCEPT a texture that says otherwise: a SKIP_DECODE upload (`gamma_texel`
-// below — the minimap tiles) already holds the authored byte, and encoding it again is the
-// double-gamma that washed the outdoor minimap bright. Uploading everything raw would be cheaper
-// and would also move bilinear filtering into gamma (as the reference filters), but it forces the
-// booth to emit gamma — a contained follow-up, not a look change.
+// 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.
+// Deviation: bilinear filtering runs on the decoded texel, not on the gamma byte the reference
+// filters, because the booth bake stores linear bytes.
 
 #import bevy_sprite::mesh2d_functions as mesh_functions
 
-// The mesh's own vertex layout, at bevy's fixed Mesh2d locations (`Mesh2dPipeline::specialize`
-// binds POSITION at 0, UV_0 at 2, COLOR at 4 and defines `VERTEX_UVS` / `VERTEX_COLORS` for the
-// attributes the mesh actually carries — the minimap's composite tile quad has no colours).
+// The mesh vertex at bevy's fixed Mesh2d locations (`Mesh2dPipeline::specialize`: POSITION 0, UV_0
+// 2, COLOR 4); `VERTEX_UVS`/`VERTEX_COLORS` are defined only for attributes the mesh carries.
 struct Vertex {
     @builtin(instance_index) instance_index: u32,
     @location(0) position: vec3<f32>,
@@ -40,28 +31,17 @@ struct Vertex {
 }
 
 struct VertexOutput {
-    // Clip position out of the vertex stage, the FRAGMENT COORDINATE (physical px) into the
-    // fragment — the screen mask below compares against it.
+    // Clip position out; in the fragment, the pixel coordinate (physical px) the screen mask uses.
     @builtin(position) position: vec4<f32>,
     @location(0) uv: vec2<f32>,
 #ifdef VERTEX_COLORS
     @location(1) color: vec4<f32>,
 #endif
-    // The instance's whole-run colour, read off bevy's per-instance mesh TAG (`MeshTag`, a u32 the
-    // mesh uniform carries for every Mesh2d entity, re-uploaded with its transform each frame).
-    // A run with one colour draws WHITE vertices and carries that colour here — so a colour
-    // pulse is one component write on the batch entity: not an `Assets<Mesh>` write (which arms
-    // bevy's asset-changed probes over every `Mesh3d` row in the scene, 1982) and not a material
-    // write (which re-creates the material's bind group and uniform buffers on the render thread,
-    // 2–3 of them a frame at a parked pin costing ~9 ms on Intel's DX12 driver, 2236).
-    //
-    // Packed as the reference packs a vertex colour: one BYTE per channel — `CImVector`, the
-    // client's `SetVertexColor` quantising `×255 + 0.5` and folding the frame's alpha in bytes
-    // (wow-re `system/ui/scratch/texture-color-composition.md`) — so this carries exactly the
-    // precision the real client draws with. Stored COMPLEMENTED (`!packed`): an entity with no
-    // `MeshTag` reads 0 from bevy, and the complement makes that opaque white, i.e. untinted,
-    // rather than transparent black — every Mesh2d that draws with this material and never
-    // asked for a tint (the minimap's interior tiles) is right by default.
+    // 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.
     @location(2) @interpolate(flat) tint: vec4<f32>,
 }
 
@@ -90,110 +70,61 @@ 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 — the live unit PORTRAIT: the real client stamps a round
-// alpha stencil into its 64² bake; ours cuts the same circle at draw time, so the opaque booth
-// backdrop never pokes past the frame ring's thin band. UV-space, so it holds at any quad size.
+// 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.
 @group(2) @binding(3) var<uniform> circular: u32;
-// The screen-anchored alpha mask (the MINIMAP's MinimapMask.blp circle, decision 0203): the mask
-// spans mask_rect (physical framebuffer px: min.xy, max.xy; z <= x disables), and the fragment's
-// alpha multiplies by the mask's ALPHA channel there (MinimapMask.blp is DXT3 — white color, the
-// circle ramp authored in its 8-bit alpha; header-verified this session after a mis-read as
-// palettized cost a debug cycle). Screen-anchored — not quad UV space — so world-anchored tile
-// quads pan under a fixed window. Outside the rect drops. Sampled at level 0 (a branch on
-// per-fragment coords would break the uniform control flow implicit derivatives need).
+// 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.
 @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 greyed-out icon (decisions 1327, 1330). This is the verb every
-// disabled affordance in the reference is built on: a bag icon under the game menu, an unusable pet
-// action, a disconnected party portrait — and the unavailable talent B162 reported.
-//
-// It is not a tint and not a stage flag: `+0x128` on the texture object is a `CGxShader*`, and the
-// one shader the UI ever loads is `Shaders\Pixel\Desaturate.bls` (wow-re
-// `system/ui/scratch/texture-desaturate-law.md`, VERIFIED at the asset's own bytes). Its whole body
-// is four instructions, and the two that matter are reproduced exactly below:
-//
+// `Texture:SetDesaturated(1)`: the texture object's `+0x128` `CGxShader*` binds
+// `Shaders\Pixel\Desaturate.bls`, whose two working instructions are
 //     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)
-//
-// **The vertex colour's RGB is DISCARDED, not modulated in.** A bound fragment program supersedes
-// the fixed-function stage chain entirely, so the `MODULATE(TEXTURE, DIFFUSE)` law that governs
-// every other UI quad simply does not run here — there is no desaturate-then-tint or
-// tint-then-desaturate, the tint is *absent*. FrameXML walks straight into this:
-// `SetItemButtonDesaturated(button, 1, 0.65, 0.65, 0.65)` still SETS that 0.65, and on
-// shader-capable hardware it has no effect on colour. Only its ALPHA survives, which is why the
-// alpha multiply below is shared with the ordinary path rather than special-cased — dropping it
-// would make every desaturated icon ignore `SetAlpha` and its frame's alpha.
-//
-// The fold runs on the GAMMA byte (after `linear_to_srgb`) because the reference's UI is 8-bit
-// arithmetic end to end; greying a linearized texel would land a different byte than the client's.
+// 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`.
 @group(2) @binding(7) var<uniform> desaturate: u32;
-// The sampled texture is already PREMULTIPLIED — a portrait/paper-doll/dressing-room booth bake,
-// and nothing else (see `UiQuad::premultiplied`).
-//
-// Every other texture this pass samples is authored STRAIGHT (a BLP's rgb means nothing where its
-// alpha is 0), so the premultiply below has to happen here. A booth render target is the opposite
-// by construction: its opaque geometry wrote `a = 1`, its alpha batches blended over that, and its
-// ADDITIVE particles added light while contributing NO coverage (`wow_effect.wgsl` returns
-// `(rgb·a, 0)`). Colour is emitted light, alpha is coverage — premultiplied. Weighting it by its own
-// alpha again multiplies exactly the emitted light that sits over EMPTY pane space by zero, which is
-// how a transparent-clear pane lost the R14 pauldrons' fire entirely and kept a weapon glow only
-// where it overlapped the model's own opaque pixels.
+// 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.
 @group(2) @binding(8) var<uniform> premultiplied: u32;
-// **Alpha TEST** reference — `<= 0` disables. The WMO-interior minimap tiles, and nothing else so
-// far: the reference draws them under EGxBlend **1**, whose applicator `glDisable`s blending
-// outright, with the `SetRenderState` id-7→id-8 cascade arming `glAlphaFunc(GL_GEQUAL,
-// 0.87843144)` — `.data 0x85ad20[1] = 224`, times the f32 reciprocal of 255 (wow-re
-// `system/minimap/scratch/wmo-interior-minimap-composite.md`). So a tile fragment either writes
-// FULLY OPAQUE or is discarded; partial coverage does not exist on that path, and two overlapping
-// group tiles can never leave the clear colour showing between them. Blending them the ordinary
-// way leaves `(1−a)(1−b)` of the black clear at every boundary — B141's "odd black lines".
-//
-// The tested value is `texel.a × colour.a`, the client's MODULATE of the texel against the
-// stride-0 vertex dword `(frameAlpha << 24) | 0xFFFFFF`. The SCREEN MASK is deliberately NOT in
-// it: the reference alpha-tests each tile into an offscreen and cuts the round mask at the BLIT,
-// so folding the mask ramp into the test would saw the disc's soft rim into a hard, undersized
-// circle.
+// 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.
 @group(2) @binding(9) var<uniform> alpha_ref: f32;
-// The bound texture was uploaded UNDECODED — `BlpVariant::MapTile`'s `GL_SKIP_DECODE_EXT`, the
-// minimap tiles — so the sampler hands back the authored GAMMA byte itself and the ordinary arm's
-// `linear_to_srgb` has no decode to undo: the texel passes through as-is. The alpha-test arm
-// ignores this flag — its target is the un-encoded composite, so it decodes explicitly instead.
+// 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.
 @group(2) @binding(10) var<uniform> gamma_texel: u32;
-// The **UV window this quad may sample** — `(u_min, v_min, u_max, v_max)`, already inset by half a
-// texel by the producer; an axis whose `min > max` is left unclamped. The atlas-cell guard,
-// decision 1608.
-//
-// `CLAMP_TO_EDGE` clamps at the IMAGE's edge, not at a `SetTexCoord` crop's, so a magnified atlas
-// cell's outermost destination pixels sample half a texel past the crop and linear-filter in the
-// NEIGHBOURING cell. `POIIcons` cell 15 (the generic zone landmark) is fully transparent and the
-// cell above it is a coffin whose bottom row is opaque black: the world map drew a ~24%-black
-// hairline along the top edge of every zone POI. Clamping here makes a cell sample exactly what a
-// standalone clamped texture of it would. Producers leave it off for UVs that run past `[0,1]` —
-// that is the backdrop's tiling idiom, not a cell.
+// 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.
 @group(2) @binding(11) var<uniform> uv_clamp: vec4<f32>;
 
-// ITU-R BT.601 luma — the `PARAM c[0]` of that shader, read as raw f32 words: `0x3E991687`,
-// `0x3F1645A2`, `0x3DE978D5`. Not `(0.3, 0.3, 0.3)`, not `(0.3, 0.59, 0.11)` (this file's own first
-// guess, corrected by the carve), not BT.709.
-//
-// **Do not normalise these and do not compute them in f64.** They sum to 1.0000000074505806, so a
-// white texel evaluates just above 1.0 and relies on the output clamp; the ARB text and the D3D
-// blob round-trip to the same three f32 words, so the backend cannot change a bit and neither may
-// we.
+// 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.
 const LUMA: vec3<f32> = vec3<f32>(0.299, 0.587, 0.114);
 
-// Linear → sRGB (the exact IEC 61966-2-1 curve the hardware's sRGB store uses, so this inverts the
-// sampler's decode bit-for-bit in f32). Alpha carries no gamma and never passes through here.
+// 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.
 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 → linear — the inverse of `linear_to_srgb`, for a texture uploaded UNDECODED so the hardware
-// filters its authored bytes (the minimap tiles' `GL_SKIP_DECODE_EXT`). The conversion happens here,
-// after the filter, which is exactly the order the reference's fixed-function pipe uses.
+// 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.
 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;
@@ -202,38 +133,34 @@ 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 (implicit derivatives), and the
-    // bounds are sorted before `clamp` so a DISABLED (`min > max`) axis never forms an
-    // ill-ordered range — `select` evaluates both arms.
+    // 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.
     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);
     let t = textureSample(quad_texture, quad_sampler, uv);
-    // The quad's colour: its vertex colour (white for a one-colour run) times the run's tint off
-    // the instance tag (see `VertexOutput::tint`) — a mesh without colours is the tint alone.
 #ifdef VERTEX_COLORS
     let c = in.color * in.tint;
 #else
     let c = in.tint;
 #endif
-    // Back to the client's byte space, then tint there: `UiQuad.color` is already a client-space
-    // sRGB value (FrameXML's `<Color>`, `|cff…`, quality colors), so this multiply IS the FFP's
-    // gamma-space `tint × texel`. A SKIP_DECODE texture (`gamma_texel`) is already IN byte space —
-    // re-encoding it is the double-gamma that washed the outdoor minimap bright.
+    // 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.
     let texel = select(linear_to_srgb(t.rgb), t.rgb, gamma_texel != 0u);
-    // The desaturated arm REPLACES the modulate — see the `desaturate` binding above. `c.rgb` is
-    // deliberately unread here; only `c.a` carries into the alpha below, as it does on both paths.
+    // 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 itself imposes — the vertex colour's alpha (`SetAlpha`, the frame's
-    // inherited alpha) and the two masks. It is kept apart from the texel's OWN alpha `t.a` because
-    // the two premultiply differently: `k` scales a premultiplied source's colour and alpha alike,
-    // while `t.a` must weight the colour only when the source is straight.
+    // `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.
     var k = c.a;
     if circular != 0u {
-        // Soft ~2%-of-width edge: reads as the ref's stencil at portrait size, no jaggies.
+        // A soft edge 2% of the width wide, 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 {
@@ -242,29 +169,20 @@ 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 (see `alpha_ref`): pass ⇒ fully opaque, fail ⇒ nothing.
-    //
-    // It returns the **un-encoded** texel, not `rgb`: this arm draws only into the minimap's own
-    // 256² composite target, which is un-encoded float like the portrait booths' (decisions
-    // 0254/0804 — the UI arc does its one sRGB encode at the end, so a target that pre-encoded
-    // would land a second one downstream). The blit quad that samples that target is an ordinary
-    // quad and takes the `linear_to_srgb` above, which is where the authored byte comes back.
-    // Nothing is lost by skipping it here: the composite does no colour arithmetic at all — no
-    // blend, no day-night tint, a white vertex colour — so this path is a pure copy, and there is
-    // no gamma-space multiply to preserve.
+    // 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.
     if alpha_ref > 0.0 {
         if t.a * c.a < alpha_ref {
             discard;
         }
-        // The tile arrived as gamma bytes (SKIP_DECODE) and the composite target is un-encoded, so
-        // the conversion the sampler did not do happens HERE — after the filter, which is the point.
         return vec4<f32>(srgb_to_linear(t.rgb) * c.rgb, 1.0);
     }
     let a = t.a * k;
-    // Premultiply in GAMMA (decision 0160's lesson, here for the UI): the hardware `SrcAlpha` factor
-    // would weight a linearized colour and inflate every soft edge and every dim additive skirt.
-    // An already-premultiplied source (a booth bake) takes `k` alone — folding in `t.a` a second
-    // time is the double multiply that erased the panes' effects.
+    // 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.
     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 de024dc6..af7d76a3 100644
--- a/crates/benilla-app/src/shaders/ui_slice_gamma.wgsl
+++ b/crates/benilla-app/src/shaders/ui_slice_gamma.wgsl
@@ -1,11 +1,6 @@
-// The glue screens' Bevy-UI nine-patch / tiled shader, on the UI **gamma composite lane**
-// (decision 0254) — the sibling of `ui_node_gamma.wgsl`, which carries the same rationale.
-//
-// VENDORED from `bevy_ui_render` 0.18.1 `src/ui_texture_slice.wgsl`, verbatim except the fragment's
-// final colour (marked THE ONE CHANGE). This is the pipeline every glue `Backdrop` draws through —
-// the `Glue-Tooltip-Border` edge nine-patch and the tiled `UI-Tooltip-Background` fill — so it is
-// exactly where the edit boxes' washed-out fill and their bevel's vanished dark ramp came from.
-// Re-diff against upstream on every Bevy upgrade.
+// 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.
 
 #import bevy_render::view::View;
 #import bevy_render::globals::Globals;
@@ -18,8 +13,7 @@ var<uniform> globals: Globals;
 @group(1) @binding(0) var sprite_texture: texture_2d<f32>;
 @group(1) @binding(1) var sprite_sampler: sampler;
 
-// Linear → sRGB (IEC 61966-2-1) — the exact inverse of the sampler's decode. See
-// `ui_node_gamma.wgsl` for why each factor is encoded before the multiply.
+// Linear to sRGB (IEC 61966-2-1), the exact inverse of the sampler's decode.
 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;
@@ -140,10 +134,9 @@ fn fragment(in: UiVertexOutput) -> @location(0) vec4<f32> {
     // map the slice coords to texture coords
     let atlas_uv = in.atlas_rect.xy + uv * (in.atlas_rect.zw - in.atlas_rect.xy);
 
-    // ── THE ONE CHANGE from the vendored original ────────────────────────────────────────────────
-    // Upstream returns `in.color * textureSample(...)` — a linear product for a linear blend. Both
-    // factors return to the client's byte space before the multiply, so the tint IS the reference's
-    // gamma-space `SetBackdropColor` multiply and the blend that follows is byte arithmetic.
+    // ── 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.
     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/smart_rect.rs b/crates/benilla-app/src/smart_rect.rs
index adb33d4e..0fc1359d 100644
--- a/crates/benilla-app/src/smart_rect.rs
+++ b/crates/benilla-app/src/smart_rect.rs
@@ -1,6 +1,5 @@
 //! **SmartScreenRect** — the client's shared draw-time anti-overlap placement solver
-//! (`UIUtil\SmartScreenRect`, wow-re `ui/scratch/smartscreenrect-solver-law.md`, §5-verified
-//! 2026-07-13, a7825131). Every frame each participant submits its desired screen rect; the
+//! (`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
@@ -220,8 +219,8 @@ fn clamp_to_bands(r: Rect, viewport: Vec2) -> (Rect, u8) {
 }
 
 /// The 3×3 region index — the exact `0x509d80` decision tree, byte-read for all 16 flag words
-/// (this refines the law note's "row 8 catch-all" phrasing, which is imprecise for the
-/// degenerate multi-flag combos): **bit0 (off left) dominates and ignores bit1 beneath it;
+/// (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.
@@ -424,8 +423,8 @@ 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 the law
-    /// note's 9 listed rows).
+    /// The full 16-word `0x509d80` tree — every combination, byte-derived (not just 9 rows, one
+    /// per region).
     #[test]
     fn region_index_table() {
         let expected = [0, 4, 3, 4, 2, 8, 7, 8, 1, 6, 5, 6, 2, 8, 7, 8];
diff --git a/crates/benilla-app/src/sound/anim_events.rs b/crates/benilla-app/src/sound/anim_events.rs
index 61c2b0e4..61d7cee9 100644
--- a/crates/benilla-app/src/sound/anim_events.rs
+++ b/crates/benilla-app/src/sound/anim_events.rs
@@ -8,9 +8,8 @@
 //! `$CSD 6923` = the SoundEntries kit literally named `HumanMaleEmoteLaugh`; Cry 77 → 6921,
 //! Chicken 78 → 6919, Applaud 80 → 4× `ClapSounds` 6576 — probe-verified on the real 5875 M2 +
 //! SoundEntries; the client's `$CSD` handler `0x623c10` → `0x459230` plays the event payload as
-//! a literal SoundEntries id, byte-confirming the routing — wow-re
-//! `sound/scratch/gather-sound-anim-events.md`) — and the **gathering/work pair** (decision
-//! 0562, same wow-re note):
+//! a literal SoundEntries id, byte-confirming the routing) — and the **gathering/work pair**
+//! (decision 0562):
 //!
 //! - **`$TRD`** (`0x62faa0`): the in-flight spell's `SpellVisual` **field-14 strike sound**,
 //!   positioned — **the mining pick clang** (visual 93 → 1143 "Mining Impact") and the crafting
@@ -24,7 +23,7 @@
 //!   which no vmangos path ever sets for a player — verified at its source).
 //!
 //! `$CST`/`$CSL`/`$CSR` are still NOT routed, but **the reason we gave was wrong** and is
-//! corrected here (wow-re `anim-event-position-law.md` §5). The handler `0x60c940` does only
+//! corrected here. The handler `0x60c940` does only
 //! 3D-**reposition** the already-playing cast handle — that part held — but it repositions it to
 //! the **event's own point** (`0x600143 mov edx,[ebx+0x10]` → `0x60c960`/`0x60c990` → `0x61ceb0`),
 //! i.e. to the casting hand, not to the caster. benilla's kit player tracks a looping cast sound
@@ -126,12 +125,11 @@ pub(super) fn route_anim_events(
     };
     for ev in events.read() {
         match &ev.ident {
-            // `$DSL` — the DOODAD SOUND **LOOP** (`0x69521d`), VERIFIED (wow-re
-            // `sound/scratch/doodad-sound-emitters.md`, §5). A persistent handle with a lifecycle,
-            // one per doodad (`[CMapDoodadDef+0x168]`): crossing the marker again **repositions**
-            // the existing registration (`0x462000`) and never restarts it; a DIFFERENT id
-            // releases the old one (`0x461f80`) and registers the new (`0x461d80`). So there is no
-            // wrap retrigger at all — which the shipped audio already implied, since
+            // `$DSL` — the DOODAD SOUND **LOOP** (`0x69521d`). A persistent handle with a
+            // lifecycle, one per doodad (`[CMapDoodadDef+0x168]`): crossing the marker again
+            // **repositions** the existing registration (`0x462000`) and never restarts it; a
+            // DIFFERENT id releases the old one (`0x461f80`) and registers the new (`0x461d80`). So
+            // there is no wrap retrigger at all — which the shipped audio already implied, since
             // `NightElfStreetLampLoop` is 4.000 s on a 3.333 s sequence and `CampFireSmallLoop` is
             // 2.967 s on the same, mismatched in both directions.
             //
@@ -146,8 +144,7 @@ pub(super) fn route_anim_events(
             // correlation was authoring practice — you do not detune a sustained hum.) `force_loop`
             // here is therefore the faithful shape, not a workaround: 25 of the 60 kits a `$DSL`
             // names omit 0x200 and every one of them loops in the real client.
-            // `$DSL` — the DOODAD SOUND **LOOP** (`0x69521d`), VERIFIED (wow-re
-            // `sound/scratch/doodad-sound-emitters.md`). It does not start a sound. It
+            // `$DSL` — the DOODAD SOUND **LOOP** (`0x69521d`). It does not start a sound. It
             // **registers this doodad's position** as one emitter of its SoundEntries id in the
             // pool at `0xb06dd8` (`0x461d80`), and re-crossing the marker only *repositions* that
             // registration (`0x462000`) — which is why there is no wrap retrigger, and why
@@ -167,14 +164,14 @@ pub(super) fn route_anim_events(
                     .pos
                     .or_else(|| transforms.get(ev.entity).ok().map(|t| t.translation()))
                 {
-                    // **The two lanes' `$DSL` arms differ, and only here** (wow-re
-                    // `doodad-sound-emitters.md` §13). The placed-M2 handler `0x6951e0` compares
-                    // the id and swaps; the GameObject dispatcher's arm `0x5f3fe5` does **not
-                    // compare it at all** — a live handle is only repositioned, whatever id the
-                    // marker names. Onyxia's lava trap is the case that makes it observable:
-                    // `ONYZIASLAIRLAVATRAP.M2` (208 spawns in the lair) authors `$DSL(8681)` on
-                    // its chained Stand variation and `$DSL(8682)` on Custom0, so on the
-                    // GameObject lane the Custom0 hum never displaces the Stand one.
+                    // **The two lanes' `$DSL` arms differ, and only here**. The placed-M2 handler
+                    // `0x6951e0` compares the id and swaps; the GameObject dispatcher's arm
+                    // `0x5f3fe5` does **not compare it at all** — a live handle is only
+                    // repositioned, whatever id the marker names. Onyxia's lava trap is the case
+                    // that makes it observable: `ONYZIASLAIRLAVATRAP.M2` (208 spawns in the lair)
+                    // authors `$DSL(8681)` on its chained Stand variation and `$DSL(8682)` on
+                    // Custom0, so on the GameObject lane the Custom0 hum never displaces the
+                    // Stand one.
                     if go_lane.contains(ev.entity) {
                         super::emitter_pool::register_keeping_first(
                             &mut pool, ev.entity, ev.data, at, listener,
@@ -184,8 +181,8 @@ pub(super) fn route_anim_events(
                     }
                 }
             }
-            // `$DSE` — the doodad sound **STOP** token (`0x45534424`), VERIFIED in the same note:
-            // it releases the doodad's registration (`0x461f80`), and its `data` is 0 on all 16
+            // `$DSE` — the doodad sound **STOP** token (`0x45534424`): it releases the doodad's
+            // registration (`0x461f80`), and its `data` is 0 on all 16
             // shipped models. Without it a `$DSL` started at a keyframe never ends — which is
             // exactly the elevator and machinery family (`GnomereganElevatorLoop`, `SubwayLoop`,
             // the Undercity and Thunder Bluff lifts, the zeppelin), where the loop is authored to
@@ -208,7 +205,7 @@ pub(super) fn route_anim_events(
             // **`$CSD` is deliberately still at the model root.** It has no arm on either of those
             // dispatchers: it is the CGUnit lane's (`0x623c10` → `0x459230`), and whether *that*
             // dispatcher's arms take the event point or the unit's own is the one piece of this
-            // mechanism wow-re has not recorded — dispatched, not assumed. It matters: every player
+            // mechanism not yet read from the binary — open, not assumed. It matters: every player
             // model authors six `$CSD` records, all on the head.
             b"$SND" | b"$DSO" if ev.data != 0 => {
                 ring(&mut kits, &mut out, ev.data, ev, &mut complained);
@@ -246,8 +243,7 @@ pub(super) fn route_anim_events(
                     .flatten()
                 {
                     // **EVENT POINT** — `0x5fff5a` pushes the dispatcher's point and `0x623a1e`
-                    // hands it straight to `0x458870`. (This also corrected wow-re's own
-                    // `gather-sound-anim-events.md`, which had glossed that `edx` as the payload.)
+                    // hands it straight to `0x458870` (that `edx` is the point, not the payload).
                     ring(&mut kits, &mut out, kit, ev, &mut complained);
                 }
             }
diff --git a/crates/benilla-app/src/sound/cinematic.rs b/crates/benilla-app/src/sound/cinematic.rs
index a11e72a7..ebf43556 100644
--- a/crates/benilla-app/src/sound/cinematic.rs
+++ b/crates/benilla-app/src/sound/cinematic.rs
@@ -31,8 +31,7 @@ use super::mixer::{self, StreamingSoundHandle};
 use super::{kit::SoundKits, SoundOutput};
 use crate::cinematic::Cinematic;
 
-/// A cut-off narration is **cut**, with no fade at all — wow-re
-/// `sound/scratch/cinematic-audio-law.md` (VERIFIED): every release on this path
+/// A cut-off narration is **cut**, with no fade at all: every release on this path
 /// (`0x48efef` shot-advance, `0x48f055` stop/ESC, `0x490b8d` local abort) is a plain release of
 /// `[0xb4e274]`, and there is **no audio fade anywhere in the cinematic** — the 0.25 s fade the
 /// reference schedules at both edges (`0x4c0d10`, `[0x804550]`) is a *screen* fade, which is what
@@ -149,8 +148,8 @@ fn narrate(
             return;
         }
     };
-    // **No category slider applies to this channel at all** (wow-re `cinematic-audio-law.md`,
-    // VERIFIED). The narration is opened at `0x48ef29` → `0x458a40` → `0x45ce60` with behaviour
+    // **No category slider applies to this channel at all**. The narration is opened at
+    // `0x48ef29` → `0x458a40` → `0x45ce60` with behaviour
     // flags `0x15`: `or eax,4` (`0x45ce9e`) and `or eax,0x10` (`0x45cea8`), while the music bit
     // `or eax,2` at `0x45ceb2` is **skipped**. Bit `0x10` is read at `0x7a5dc0`
     // (`test al,0x10; jne 0x7a5e1a`) and takes the channel around the category multiply entirely —
diff --git a/crates/benilla-app/src/sound/combat.rs b/crates/benilla-app/src/sound/combat.rs
index ca505c25..ae12224a 100644
--- a/crates/benilla-app/src/sound/combat.rs
+++ b/crates/benilla-app/src/sound/combat.rs
@@ -7,7 +7,7 @@
 //!
 //! - **`$CSS`** — the swing whoosh, in **both** of its forms. Nothing contacted (miss/dodge/
 //!   evade) gets kits 7080/7081 `Combat Miss 1H/2H` by weapon handedness — exactly the two ids
-//!   the client caches by name at startup (wow-re `0x4575b0`, `_DONOTRENAME_` kits). Anything
+//!   the client caches by name at startup (`0x4575b0`, `_DONOTRENAME_` kits). Anything
 //!   else gets the *connecting* swing's `WeaponSwingSounds2` whoosh by weapon weight; see "The
 //!   connecting swing" below.
 //! - **`$CAH`** — **not** the attacker's exertion, which is what this module used to think.
@@ -40,7 +40,7 @@
 //!
 //! 1. `0x6247d0`'s own weapon-sound block, at the attacker — a **natural-weapon** swing
 //!    (`$AHn` fired the dispatch) plays the attacker's `CreatureSoundData.CustomAttack[n]`
-//!    column INSTEAD of the generic weapon impact (the `SWINGNOHITSOUND` latch, `0x6247d0` §f);
+//!    column INSTEAD of the generic weapon impact (the `SWINGNOHITSOUND` latch, `0x6247d0`);
 //!    otherwise a landed hit plays the `WeaponImpactSounds` impact/crit slot for the victim's
 //!    material (`CreatureImpactType`).
 //! 2. `0x624530`'s **victimState-keyed clang**, at the victim — parry (`0x6245bb` →
@@ -117,7 +117,7 @@
 //! One more byte detail: the clang alone is emitted two yards up (`0x457e29`); the generic weapon
 //! impact beside it passes its position straight through.
 //!
-//! INTERIM readings (flagged for a wow-re pass): a defended outcome suppresses block 1's generic weapon impact
+//! INTERIM readings: a defended outcome suppresses block 1's generic weapon impact
 //! (the tail's latch test `0x624936` carries no victimState gate in the trace, so whether it
 //! also plays under a clang is unpinned);
 //! the natural-weapon column is gated on
@@ -161,7 +161,7 @@ const VICTIM_DEFLECT: u32 = 8;
 /// asks that hand for its item.
 const HITINFO_LEFTSWING: u32 = 0x4;
 
-/// The two `_DONOTRENAME_` whoosh kits the client caches by name at startup (wow-re `0x4575b0`);
+/// The two `_DONOTRENAME_` whoosh kits the client caches by name at startup (`0x4575b0`);
 /// byte-verified ids in the 5875 SoundEntries dump.
 const COMBAT_MISS_1H: u32 = 7080;
 const COMBAT_MISS_2H: u32 = 7081;
@@ -465,6 +465,7 @@ fn combat_sounds(
     units: Query<CombatUnit>,
     tables: MeleeTables,
     attach: crate::entities::AttachPoints,
+    objects: crate::net::Objects,
     mut items: Option<ResMut<crate::items::Items>>,
     net_commands: Res<crate::net::NetCommands>,
     kits: Option<ResMut<SoundKits>>,
@@ -666,8 +667,8 @@ fn combat_sounds(
         let attacker = units.get(swing.attacker).ok();
         let victim = swing.victim.and_then(|v| units.get(v).ok());
         // **The fired tag's own point** (`edi = [ebx+0x10]`, pushed at `0x6248ef` for the
-        // CustomAttack column and `0x624950` for the generic weapon impact — wow-re
-        // `anim-event-position-law.md` §3). A big creature's `$AH1` sits 4.7 yd out on the jaw
+        // CustomAttack column and `0x624950` for the generic weapon impact). A big creature's
+        // `$AH1` sits 4.7 yd out on the jaw
         // (`trex.m2`) and Thunderaan's `$CAH` 26.4 yd out; the attacker's origin was standing in
         // for both. The receive-time fallback carries no point — no tag fired — so it keeps the
         // attacker, then the victim, which is the only anchor that packet leaves us.
@@ -724,7 +725,7 @@ fn combat_sounds(
                             items
                                 .as_mut()
                                 .and_then(|it| {
-                                    super::worn_chest_material(vstore, it, &net_commands)
+                                    super::worn_chest_material(vstore, &objects, it, &net_commands)
                                 })
                                 .map_or(impact_slot::FLESH, |m| mats.armor_impact_slot(m) as usize)
                         }
@@ -753,9 +754,9 @@ fn combat_sounds(
             // `0x624530`'s victimState-keyed clang (`0x6245bb` parry → `0x623640(sel=0)`,
             // `0x6245d8` block → `sel=1`), emitted at the VICTIM (`vtable+0x14` on `this`).
             // Reached on EVERY impact tag — the `$AHn` digit block "has zero effect on the
-            // victim dispatch" (wow-re `melee-impact-timing.md` §f): a wolf's bite and the
-            // parry clang both sound. Decision 0899 — 0525 wrongly let the natural column
-            // swallow this, so every beast you parried was silent.
+            // victim dispatch" (every digit reaches it through the shared tail, `0x6249bb`): a
+            // wolf's bite and the parry clang both sound. Decision 0899 — 0525 wrongly let the
+            // natural column swallow this, so every beast you parried was silent.
             // `0x625400(sel)` on the victim, then `0x457dc0`'s class+material slot pick. No
             // defending item means no clang — the reference bails before the play — and that is
             // a `None` here rather than a `continue`, because the wound vocal below still has to
@@ -867,8 +868,7 @@ fn combat_sounds(
                 // the row pointer dies at `0x6234e4`, so neither the bus pick `0x623b10` (which
                 // takes the category) nor the play `0x458890` (bus, kit, &pos) ever sees the row
                 // to re-read a column from. The CGPlayer twin `0x62f880` is identical
-                // (`0x62f8be`/`0x62f8c3`). wow-re
-                // `object-layer/scratch/wound-parry-gate-and-injury-vocal.md` §13.
+                // (`0x62f8be`/`0x62f8c3`).
                 let vocal = net
                     .display_id
                     .and_then(|d| voices.0.for_display(d))
diff --git a/crates/benilla-app/src/sound/creature.rs b/crates/benilla-app/src/sound/creature.rs
index 7f94e13a..ac9fe3be 100644
--- a/crates/benilla-app/src/sound/creature.rs
+++ b/crates/benilla-app/src/sound/creature.rs
@@ -7,7 +7,7 @@
 //! natural-weapon impact, not free-standing anim vocals); the
 //! aggro/alert flares land here ([`ai_reaction_vocals`], decision 0280), and so does the ambient
 //! body loop ([`creature_body_loops`] — the `loop_sound` column, `0x623800`'s alive-gate). Still
-//! untriggered — data in the catalog, triggers INFERRED (0280's §5): stun/jump_start/jump_end
+//! untriggered — data in the catalog, triggers INFERRED (0280): stun/jump_start/jump_end
 //! (offsets verified, live triggers likely M2 tags — unpinned).
 
 use bevy::ecs::entity::EntityHashMap;
@@ -203,8 +203,8 @@ fn death_vocals(
 /// the aggro bark (CreatureSoundData col 10), ALERT → the alert bark (col 13) — pure audio, like
 /// the client (`0x6056e0` plays no animation/UI on either leg).
 ///
-/// **HOSTILE rides the unit's one-shot voice channel, and that is not a nicety** (decision 1399,
-/// wow-re `object-layer/scratch/smsg-ai-reaction.md`): the bark goes out through `0x623a40(0)`,
+/// **HOSTILE rides the unit's one-shot voice channel, and that is not a nicety** (decision 1399):
+/// the bark goes out through `0x623a40(0)`,
 /// which stores its channel in `[unit+0xb20]` with category 0 latched in `[unit+0xb24]` —
 /// **the lowest category in the table, so it never interrupts a playing bark and a repeat is
 /// dropped while one is live** ([`unit_voice_playing`]). The wire does not send this packet
@@ -219,15 +219,14 @@ fn death_vocals(
 ///
 /// **ALERT is a different route, and is faithfully unconditional** — pinned since, decision 1401.
 /// It reaches `vtable+0x88(8,0)` → `0x623490` → col 13, and it *is* rolled, but the class-8
-/// threshold is **100** and the compare is inclusive, so `P = 1`. (wow-re's `smsg-ai-reaction.md`
-/// calling ALERT "probabilistic" was too strong, and has been corrected at the table.) Its one
+/// threshold is **100** and the compare is inclusive, so `P = 1`. Its one
 /// real gate is a mute while a **server-pushed** object sound is live on the unit — the
 /// `SMSG_PLAY_OBJECT_SOUND` (opcode `0x278`) registry. ALERT stores no latch and stays off the
 /// slot.
 ///
 /// **That gate is now in.** 1401 recorded the opcode as one "benilla does not implement at all",
 /// which was wrong when it was written — benilla has parsed, decoded and played
-/// `SMSG_PLAY_OBJECT_SOUND` since well before it (`net::apply::world::play_object_sound` →
+/// `SMSG_PLAY_OBJECT_SOUND` since well before it (`sound::net::play_object_sound` →
 /// `ServerSoundKind::ObjectSound` → `sound::zone::server_sounds`, which even resolves the source
 /// entity to position the kit at it). What was missing was the **per-GUID registry** the gates
 /// consult (`0x4591f0`, tested by `0x623a40`'s gate (i) and by `0x623490`'s gate 3 for classes 0,
@@ -262,8 +261,8 @@ fn ai_reaction_vocals(
         let Ok((net, transform, mount_child)) = units.get(r.unit) else {
             continue;
         };
-        // The mounted redirect (byte-verified `0x60c480` — `+0xb44 ?: +0xb40`, wow-re
-        // `mount-composition.md` Q4; 0441 fold-back): ALERT reads through the mount-preferred
+        // The mounted redirect (`0x60c480` — `+0xb44 ?: +0xb40`; 0441 fold-back): ALERT reads
+        // through the mount-preferred
         // getter — a mounted unit alerts with its MOUNT's voice — while HOSTILE (like DEATH)
         // reads the base row directly and stays the rider's own bark.
         let display = if r.hostile {
@@ -367,7 +366,7 @@ fn pet_talk_vocals(
         }
         // The pet's OWN voice row, not a mount-preferred one: `0x6040c0` resolves the packet's
         // guid and hands that object straight to `0x623a40`, which reads `[unit+0xb40]` — the
-        // base row (`mount-composition.md` Q4's `+0xb44` redirect belongs to `0x60c480`, which is
+        // base row (the `+0xb44` redirect belongs to `0x60c480`, which is
         // not on this path).
         let Some(voice) = net.display_id.and_then(|d| voices.0.for_display(d)) else {
             continue;
@@ -396,8 +395,7 @@ fn pet_talk_vocals(
 /// It cannot be otherwise: there is no unit left to hang any of those on.
 ///
 /// That fresh, inlined resolve is also why column 29 was believed dead — a census over the
-/// consumers of the *cached* `[unit+0xb40]` row can never reach it (wow-re
-/// `object-layer/scratch/pet-feedback-opcodes.md`).
+/// consumers of the *cached* `[unit+0xb40]` row can never reach it.
 ///
 /// **vmangos never sends this packet**, so nothing here fires against our server today. It is
 /// built because the reference is the spec, and because it is what makes loading column 29 a
@@ -444,8 +442,8 @@ fn pet_dismiss_sounds(
 
 /// The ambient body loop (`loop_sound`, CreatureSoundData col 23): a creature whose body
 /// inherently sounds — an elemental's rumble, a slime's gurgle, a shredder's engine — hums
-/// continuously while alive. The client's `0x623800` gate, byte-verified (wow-re
-/// `smsg-ai-reaction.md` §5): health > 0, `UNIT_DYNAMIC_FLAGS` DEAD (`0x20`, the feign-death
+/// continuously while alive. The client's `0x623800` gate: health > 0, `UNIT_DYNAMIC_FLAGS` DEAD
+/// (`0x20`, the feign-death
 /// visual) clear, the column nonzero, and a "not already playing" latch — here the tracked
 /// channel's own liveness, reconciled every frame. That reconcile shape covers the client's
 /// field-delta watchers (death stops it, resurrection restarts it) *and* doubles as the restart
@@ -481,8 +479,8 @@ fn creature_body_loops(
         if !matches!(net.kind, EntityKind::Unit | EntityKind::Player) {
             continue;
         }
-        // The mounted redirect (byte-verified `0x60c480` — `+0xb44 ?: +0xb40`, wow-re
-        // `mount-composition.md` Q4; 0441 fold-back): the loop column reads the mount-preferred
+        // The mounted redirect (`0x60c480` — `+0xb44 ?: +0xb40`; 0441 fold-back): the loop
+        // column reads the mount-preferred
         // row — a mounted mechanostrider's engine hums; dismounting swaps back to the rider's.
         let display = mount_child
             .and_then(|mc| mounts.get(mc.0).ok())
@@ -540,11 +538,10 @@ fn creature_body_loops(
 /// 0525.)
 /// A mounted unit's fidgets are the MOUNT model's own tags, fired by the mount CHILD entity
 /// carrying the mount's display — so they already resolve the mount's voice row, the split-
-/// entity shape of the client's mounted redirect (`0x60c480`: `+0xb44 ?: +0xb40` — wow-re
-/// `mount-composition.md` Q4, 0441 fold-back).
+/// entity shape of the client's mounted redirect (`0x60c480`: `+0xb44 ?: +0xb40` — 0441
+/// fold-back).
 ///
-/// **The three tag families gate differently, and the difference is byte-exact** (wow-re
-/// `sound/scratch/creature-vocal-gates.md`, decision 1401):
+/// **The three tag families gate differently, and the difference is byte-exact** (decision 1401):
 ///
 /// - **`$FD1..$FD4` → fidget 1..4, ungated.** `0x6232c0` → `0x623440` → `0x6230a0` reads
 ///   `row[+0x38 + 4*(n-1)]` literally and touches no gate at all. A zero slot bails silently, with
@@ -641,8 +638,7 @@ fn creature_anim_vocals(
 
 /// Registration hook for [`super::SoundPlugin`].
 /// The **fall-landing wound vocal** — the client-side hard-landing predictor's sound leg
-/// (`0x602d00 → call [vtable+0x88] class 2` at `0x602d84`, byte-verified wow-re
-/// `object-layer/scratch/smsg-environmentaldamage.md`; decision 0412): a landing past the HARD
+/// (`0x602d00 → call [vtable+0x88] class 2` at `0x602d84`; decision 0412): a landing past the HARD
 /// threshold plays the unit's ordinary CreatureSoundData **wound vocal, normal row** (class 2 →
 /// column `+0xc` = `injury[0]` — the same row a landed melee hit voices; the crit/crushing rows
 /// are unused here). NOT wire-driven: the server's `SMSG_ENVIRONMENTALDAMAGELOG` set plays no
diff --git a/crates/benilla-app/src/sound/death_thud.rs b/crates/benilla-app/src/sound/death_thud.rs
index 44c2db7a..871e8408 100644
--- a/crates/benilla-app/src/sound/death_thud.rs
+++ b/crates/benilla-app/src/sound/death_thud.rs
@@ -6,7 +6,7 @@
 //! a `$DTH` (`benilla-extract thudcensus`; 430 rows collapse to 410 distinct paths, 407 of which
 //! ship), and only the *sample* scales with the body. **Players included** — every character model keys one,
 //! and `[unit+0xb34]` is filled from `UNIT_FIELD_DISPLAYID` for a player exactly as for a creature
-//! (wow-re `base-render-alpha.md` §3), so your own body lands audibly too.
+//! (`0x60afb0`), so your own body lands audibly too.
 //!
 //! ```text
 //! $DTH → sizeClass = CreatureDisplayInfo.SizeClass ?? CreatureModelData.SizeClass
@@ -57,7 +57,7 @@
 //! with no depth test of its own, so a body lying on a beach beside a lake would splash. benilla
 //! asks the question the footstep splash already asks: is the surface **above the feet**
 //! (`depth > 0`). Same answer wherever the reference is right, and the shore case is the one
-//! place they differ. (`0x670630`'s own semantics are out at the RE; if the node flag turns out
+//! place they differ. (`0x670630`'s own semantics are still open; if the node flag turns out
 //! to already mean "submerged", the two collapse into one.)
 //!
 //! The play is `0x458870` — **bus 0, uncapped** (`0x458880 xor ecx,ecx`; cap `0x7FFFFFFF`), 3D at
@@ -85,9 +85,8 @@ use super::kit::{play_kit_ext, KitRef, PlayExtras, SoundCategory, SoundKits};
 use super::{AudioListener, SoundConfig, SoundOutput};
 
 /// **The depth that silences the thud** — `0x62372a fcomp [0x801628]`, the float `2.0`. Read as
-/// `surfaceZ − feetZ`, the same depth the swim decision measures (wow-re
-/// `collision/scratch/swim-transition.md`), so this is "two yards of water over the body's feet",
-/// not two yards of body under the surface.
+/// `surfaceZ − feetZ`, the same depth the swim decision (`0x6030c0`) measures, so this is "two
+/// yards of water over the body's feet", not two yards of body under the surface.
 const DROWNED_DEPTH: f32 = 2.0;
 
 /// **The whole decision**, given what the world has already answered: the drowned gate, the
diff --git a/crates/benilla-app/src/sound/emitter_pool.rs b/crates/benilla-app/src/sound/emitter_pool.rs
index d30a128f..0b4de11a 100644
--- a/crates/benilla-app/src/sound/emitter_pool.rs
+++ b/crates/benilla-app/src/sound/emitter_pool.rs
@@ -1,5 +1,5 @@
 //! The **ambient emitter pool** — the reference's registration table at `0xb06dd8` and its
-//! per-frame pump `0x461990` (wow-re `sound/scratch/doodad-sound-emitters.md`, §7/§8/§17).
+//! per-frame pump `0x461990`.
 //!
 //! **Two tenants share it, because the reference's one pool has two registrars** (decision 1867).
 //! A *placed doodad* registers through its `$DSL` marker (`0x6951e0`, handle in
@@ -39,7 +39,7 @@
 //! crossing, and with **nothing whatever** bounding the number of *distinct* ambiences, so a
 //! torch-and-campfire cluster could take a third of the 12-voice ceiling away from the sounds a
 //! player is actually listening for. Applying 0x20 here was itself wrong: it is the **one-shot**
-//! lane's suppressor (§15), and this lane is now exempt from it
+//! lane's suppressor (`0x458f40` → `0x7a66a0`), and this lane is now exempt from it
 //! ([`super::kit::PlayExtras::dedupe_exempt`]).
 //!
 //! **What the pool is not.** It is not a cache and not an optimisation — it is the mechanism that
@@ -67,7 +67,7 @@ use super::{math, AudioListener, SoundConfig, SoundOutput};
 
 /// `0x461eac cmp ecx,0x1c200` over the entry stride `0xe10` — **32** entries, one per distinct
 /// SoundEntries id. A 33rd distinct id finds no match and no free entry, `0x461d80` returns handle
-/// 0, and that doodad is simply untracked until an entry frees (§17).
+/// 0, and that doodad is simply untracked until an entry frees.
 const POOL_ENTRIES: usize = 32;
 
 /// `[entry+0xC00..+0xCFF]` — **256** emitter records per entry.
@@ -213,16 +213,16 @@ impl AmbientEmitterPool {
             .position(|x| x.id == id)
             .or_else(|| self.entries.iter().position(|x| x.id == 0))
         else {
-            return; // all 32 entries hold other ids — untracked until one frees (§17)
+            return; // all 32 entries hold other ids — untracked until one frees
         };
         if self.entries[e].id == 0 {
             self.entries[e].id = id;
             self.entries[e].failed = false;
         }
         if self.entries[e].records.len() >= RECORDS_PER_ENTRY {
-            // `0x461a60` — the sound ledger's `first_slot_farther_than_query`: evict the FIRST
-            // record farther from the listener than the newcomer, and reject the newcomer when
-            // none is. Not an LRU and not an argmax: first-farther, in claim order.
+            // `0x461a60` — evict the FIRST record farther from the listener than the newcomer,
+            // and reject the newcomer when none is. Not an LRU and not an argmax: first-farther,
+            // in claim order.
             let d = math::dist_sq(listener, pos);
             let Some(victim) = self.entries[e]
                 .records
@@ -240,8 +240,7 @@ impl AmbientEmitterPool {
 
     /// The **GameObject** lane's `$DSL` arm (`0x5f3fe5`): register when the object holds no
     /// registration at all, else only *reposition* the one it holds. **It never compares the id,
-    /// so it never swaps** — the one place the two registrars actually differ (wow-re
-    /// `doodad-sound-emitters.md` §13, which corrects the GO note's own table).
+    /// so it never swaps** — the one place the two registrars actually differ.
     ///
     /// It is not a curiosity: Onyxia's lava trap (`ONYZIASLAIRLAVATRAP.M2`, 208 spawns in the
     /// lair) and Stratholme's spore trap author **two** ids — `$DSL(8681)` on the chained Stand
@@ -277,9 +276,9 @@ impl AmbientEmitterPool {
     /// Reached from a placed doodad's `$DSE` (the authored stop token — the elevator and machinery
     /// family, where the loop runs for one leg of the animation), from a GameObject's state-machine
     /// dispatch (`0x5f3cc8 call 0x5f40c0`, [`super::gameobject`]) and from the host's despawn (the
-    /// owner's own teardown, §9). There is deliberately **no** map-change reset: the reference has
-    /// none either (`0x461a20`'s only caller is the process-shutdown chain), and a streamed-out
-    /// tile releases its doodads one by one, which is the same thing done honestly.
+    /// owner's own teardown, `0x6a0840`). There is deliberately **no** map-change reset: the
+    /// reference has none either (`0x461a20`'s only caller is the process-shutdown chain), and a
+    /// streamed-out tile releases its doodads one by one, which is the same thing done honestly.
     fn release(&mut self, owner: Entity) {
         let Some(e) = self.handles.remove(&owner) else {
             return;
@@ -351,7 +350,6 @@ enum CapStep {
 /// failed. The one exception is byte-derived too: a kit whose `DistanceCutoff` is **0** is never
 /// registered into the cull list (`0x7a5cca jnp`), so it holds a slot at any distance — which our
 /// `play_kit_ext` reproduces, since its own cutoff gate is `cutoff > 0.0 && !audible`.
-/// (wow-re `sound/scratch/doodad-sound-emitters.md` §8, §5 round + byte arbitration.)
 ///
 /// This is not a detail. At the director's Stratholme pin all four channels were held by
 /// `UndeadCampfireSmall` / `CauldronLoop` / `TorchLoop` / `SlimeWaterfall`, **every one past its
@@ -518,7 +516,7 @@ fn pump_emitters(
                 // Looping is an entry-point constant on this lane, not a flag: `0x7a54d0` builds
                 // mode `0x1002` (`HW3D|LOOP_NORMAL`) and calls `SetLoopCount(-1)`, against
                 // `0x7a5490`'s `0x1000` for the one-shot path. Every `$DSL` loops; no `$DSO` does;
-                // `SoundEntries.Flags` is consulted for neither (§16).
+                // `SoundEntries.Flags` is consulted for neither.
                 force_loop: true,
                 // The per-id suppressors are the one-shot lane's; this lane dedupes structurally
                 // (one entry per id) and must not be blocked by its own fading predecessor.
@@ -618,7 +616,7 @@ pub(super) fn release(pool: &mut AmbientEmitterPool, owner: Entity) {
 }
 
 /// Release the emitters of owners that have gone — a placed doodad's host (`0x7133a0`'s teardown
-/// leg, §9) or a GameObject (whose registration lives on the type handler that goes with it).
+/// leg) or a GameObject (whose registration lives on the type handler that goes with it).
 ///
 /// This replaces B345's channel-scoped reaper. An owner no longer *owns* a channel, so stopping
 /// "its" channel is the wrong verb: what a despawn retires is one **record**, and the sound only
@@ -783,8 +781,9 @@ mod tests {
         assert!(pool.handles.is_empty());
     }
 
-    /// §17: a 33rd distinct id is UNTRACKED — the registration fails outright rather than evicting
-    /// an incumbent. `$DSL` re-fires every cycle, so it takes an entry the moment one frees.
+    /// `0x461e60`: a 33rd distinct id is UNTRACKED — the registration fails outright rather than
+    /// evicting an incumbent. `$DSL` re-fires every cycle, so it takes an entry the moment one
+    /// frees.
     #[test]
     fn a_thirty_third_distinct_id_is_untracked_until_an_entry_frees() {
         let mut pool = AmbientEmitterPool::default();
@@ -905,9 +904,8 @@ mod tests {
     /// The falsifiable half: distance does NOT arbitrate **among entries that are all audible**.
     /// A fifth id right on top of the listener stays silent behind four claimed earlier — but
     /// only while those four are inside their own cutoffs, which is the qualifier 2065 added
-    /// (wow-re rewrote its own live A/B for the same reason: with far incumbents the prediction
-    /// is the opposite, and reading it without the qualifier would have torn up a correct
-    /// mechanism).
+    /// (with far incumbents the prediction is the opposite, and reading it without the qualifier
+    /// would tear up a correct mechanism).
     #[test]
     fn distance_never_promotes_a_fifth_entry_over_an_earlier_audible_one() {
         let mut pool = AmbientEmitterPool::default();
diff --git a/crates/benilla-app/src/sound/emote.rs b/crates/benilla-app/src/sound/emote.rs
index 4db6aa84..4e39f960 100644
--- a/crates/benilla-app/src/sound/emote.rs
+++ b/crates/benilla-app/src/sound/emote.rs
@@ -6,7 +6,7 @@
 //! The catalog also serves the **send** side: `/wave`-style chat lines resolve their EmotesText
 //! id through [`EmoteSounds::text_id`] (`crate::ui_chat`), go out as `CMSG_TEXT_EMOTE` — gated first
 //! by [`EmoteSounds::text_emote`] + [`EmoteSounds::emote_flags`] (the posture-eligibility gate,
-//! wow-re `object-layer/scratch/emote-posture-gate.md`) — and the server echo plays our own emote
+//! `0x47db40`) — and the server echo plays our own emote
 //! through this same receive path — vanilla's actual loop.
 //!
 //! [`EmoteSounds::anim`] promotes the catalog's `Emotes.dbc` → `AnimID` column for
@@ -53,23 +53,22 @@ impl EmoteSounds {
     }
 
     /// An `Emotes.dbc` id's raw `EmoteFlags` bits — promoted for `crate::ui_chat`'s send-side
-    /// posture-eligibility gate (wow-re `object-layer/scratch/emote-posture-gate.md`, `0x47db40`).
+    /// posture-eligibility gate (`0x47db40`).
     pub(crate) fn emote_flags(&self, emote_id: u32) -> Option<u32> {
         self.0.emote_flags(emote_id)
     }
 
     /// The **stand state** this emote sets, if it is a posture emote (`EmoteSpecProc == 1`) —
-    /// `DoEmote`'s state branch (wow-re `object-layer/scratch/emote-posture-gate.md` §1). Promoted
-    /// for `crate::ui_chat`: it is what makes `/sit` actually sit.
+    /// `DoEmote`'s state branch (`0x5ef560` → `0x5ed430`). Promoted for `crate::ui_chat`: it is
+    /// what makes `/sit` actually sit.
     pub(crate) fn posture_state(&self, emote_id: u32) -> Option<u32> {
         self.0.posture_state(emote_id)
     }
 
     /// The `$ESD` anim event's kit for a unit in this looping state emote: the row's
     /// `EventSoundID`, gated on `EmoteSpecProc == 2` — the client's `row[+0x10] == 2` test in the
-    /// `$ESD` handler `0x6239f0` before it reads `row[+0x18]` (wow-re
-    /// `sound/scratch/gather-sound-anim-events.md`, decision 0562). A one-shot emote id parked in
-    /// the state field stays silent, exactly like the reference.
+    /// `$ESD` handler `0x6239f0` before it reads `row[+0x18]` (decision 0562). A one-shot emote id
+    /// parked in the state field stays silent, exactly like the reference.
     pub(crate) fn state_event_sound(&self, emote_id: u32) -> Option<u32> {
         (self.0.spec_proc(emote_id) == Some(2))
             .then(|| self.0.event_sound(emote_id))
diff --git a/crates/benilla-app/src/sound/footsteps.rs b/crates/benilla-app/src/sound/footsteps.rs
index a759013a..b51377ca 100644
--- a/crates/benilla-app/src/sound/footsteps.rs
+++ b/crates/benilla-app/src/sound/footsteps.rs
@@ -11,8 +11,8 @@
 //! **Trigger: `$FSD` and nothing else** (decision 1080). A footfall is two disjoint channels in
 //! the client's event dispatcher `0x5ffbd0` — `$FSD → 0x623390` is the *sound*, the per-foot side
 //! tags (`$FL/$FR/$RL/$RR/$SL/$SR/$BL/$BR/$WL/$WR`) `→ 0x5fbf70` are the *visual* footfall (the
-//! decal + spray, [`crate::footprints`]) and play nothing (wow-re `footprint-decals.md` §1, §5
-//! byte-arbitrated). Reading both as steps rang **every gait at double rate** — HumanMale's Walk
+//! decal + spray, [`crate::footprints`]) and play nothing. Reading both as steps rang **every gait
+//! at double rate** — HumanMale's Walk
 //! keys `$FR0 · $FSD · $FL0 · $FSD`, a horse's gallop four of each per 0.8 s cycle — and made the
 //! turn-in-place shuffle, whose *only* keys are `$SL0 $SR0` at `t = 0.000`, clatter where the
 //! reference is silent ([`crate::creature_anim::is_footstep_sound`]).
@@ -42,8 +42,8 @@
 //! The unit's class comes from its voice row (`CreatureSoundData.FootstepID`) through the
 //! generic display→sound chain incl. the model fallback (`benilla_formats::creature_sound` —
 //! characters reach class 7 as *data*). **Class 0, or no row at all, = no footstep sounds**:
-//! the client's `$FSD` handler bails on a zero class before any lookup (`0x6233ec`, wow-re
-//! `benilla-pins.md` B11, byte-confirmed); the lookup's class-0 rows are the Ancient
+//! the client's `$FSD` handler bails on a zero class before any lookup (`0x6233ec`); the lookup's
+//! class-0 rows are the Ancient
 //! Protector's stomps (kit 661), reached only by that model's own nonzero class.
 //!
 //! Ahead of the class, `0x623390` opens on the same three state gates the visual handler does,
@@ -110,16 +110,17 @@ fn footstep_sounds(
     units: Query<(&NetEntity, &GlobalTransform, Option<&CollisionHeight>)>,
     // The handler's state gates read the ROOT unit — a mount child's `$FSD` is the rider's
     // footfall, and it is the RIDER's stealth/hover/ghost the client tests (`0x623390`'s `this`
-    // is the unit the mount model's event stream is registered against, wow-re
-    // `footprint-decals.md` §1 "Mounted"). Same walk-to-root the footprint spawner does.
+    // is the unit the mount model's event stream is registered against, `0x607a00`). Same
+    // walk-to-root the footprint spawner does.
     parents: Query<&ChildOf>,
     root_state: Query<(Option<&ObjectStore>, Option<&MovementState>)>,
     footsteps: Option<Res<Footsteps>>,
-    // The foley half: the material table, the creature catalog that answers a unit's material,
-    // and the item store that answers a player's (a chest template ask rides the same
-    // once-per-entry discipline every other consumer uses).
-    materials: Option<Res<super::Materials>>,
-    creatures: Option<Res<Creatures>>,
+    // The foley half: the material table and the creature catalog that answers a unit's
+    // material, as ONE param (the 16-SystemParam ceiling this signature sits at), plus the item
+    // store that answers a player's (a chest template ask rides the same once-per-entry
+    // discipline every other consumer uses) and the object index its guid resolves through.
+    foley: (Option<Res<super::Materials>>, Option<Res<Creatures>>),
+    objects: crate::net::Objects,
     mut items: Option<ResMut<Items>>,
     net_commands: Res<NetCommands>,
     voices: Option<Res<CreatureVoices>>,
@@ -133,6 +134,7 @@ fn footstep_sounds(
     if events.is_empty() {
         return;
     }
+    let (materials, creatures) = foley;
     let (Some(footsteps), Some(voices), Some(mut kits), Some(assets)) =
         (footsteps, voices, kits, assets)
     else {
@@ -168,7 +170,9 @@ fn footstep_sounds(
                 // The player override (`0x62fa30`) reads the chest through the *private*
                 // inv-slot array, so this resolves for you and no one else — the reference's
                 // own reach, not a restriction added here.
-                EntityKind::Player => super::worn_chest_material(store, it, &net_commands),
+                EntityKind::Player => {
+                    super::worn_chest_material(store, &objects, it, &net_commands)
+                }
                 _ => net
                     .display_id
                     .and_then(|d| creatures.as_deref()?.foley_material(d)),
@@ -194,7 +198,7 @@ fn footstep_sounds(
             }
         }
         // The unit's footstep class (module docs): the voice row's class verbatim; zero or no
-        // row = silent (the client's class-0 gate — no code default exists, B11).
+        // row = silent (the client's class-0 gate `0x6233ec` — no code default exists).
         let class = match net.display_id.and_then(|d| voices.0.for_display(d)) {
             Some(v) if v.footstep_class != 0 => v.footstep_class,
             _ => continue,
@@ -245,7 +249,7 @@ fn footstep_sounds(
             listener,
             KitRef::Id(kit),
             // **The terrain footstep is at the EVENT's point, the foley above is not** — one arm,
-            // two sounds, two positions (wow-re `anim-event-position-law.md` §3, §5-verified).
+            // two sounds, two positions.
             // `0x623390` hands its `pos` argument to `0x458380`, where it is *both* the
             // audibility-radius reference and the 3D play position (`0x458434`); the foley leg
             // `0x6233d9 call [vt+0x8c]` is argument-less and re-derives `GetPosition + 2.0 z`
diff --git a/crates/benilla-app/src/sound/gameobject.rs b/crates/benilla-app/src/sound/gameobject.rs
index 022be03b..8699136d 100644
--- a/crates/benilla-app/src/sound/gameobject.rs
+++ b/crates/benilla-app/src/sound/gameobject.rs
@@ -9,13 +9,12 @@
 //! exactly benilla's [`crate::go_anim::GoAnim`] population. `$GO0..5` address slots 0..5
 //! (Stand/Open/Loop/Close/Destroy/Opened), `$GC0..3` the four Custom slots 6..9. So a display slot
 //! is audible only when the object's own model authors the matching event keyframe *and* the clip
-//! carrying it is playing: **there is no state-transition sound path** (wow-re
-//! `object-layer/scratch/go-display-sound-events.md`, §5-cross-checked; benilla decisions
+//! carrying it is playing: **there is no state-transition sound path** (benilla decisions
 //! 1090/1867).
 //!
 //! **The kit's `SoundEntries` flag `0x200` picks the lane** — `0x5f4051 call 0x458830`, whose only
-//! other consumer image-wide is a spell-visual path (wow-re `sound/scratch/doodad-sound-emitters.md`
-//! §11's flag table). Clear ⇒ a positioned **one-shot** (`0x458870`). Set ⇒ the **ambient emitter
+//! other consumer image-wide is a spell-visual path (`0x60edf0`). Clear ⇒ a positioned
+//! **one-shot** (`0x458870`). Set ⇒ the **ambient emitter
 //! pool** (`0x461d80`), the same 32-entry table placed doodads' `$DSL` registers into, with the
 //! handle cached in `[handler+0x18]` — one per object, shared with that object's own `$DSL` arm.
 //! The loop is dropped again by `0x5f40c0`, called from the state-machine dispatch `0x5f3cb0`
@@ -64,7 +63,7 @@ fn load_go_sounds(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
 }
 
 /// The GO display-slot an M2 animation-event tag addresses — the reference's GO event dispatcher
-/// `0x5f3e20` (wow-re `go-display-sound-events.md`, byte-verified; the 1086 fold-back): `$GO0..5`
+/// `0x5f3e20` (the 1086 fold-back): `$GO0..5`
 /// → `Sound[0..5]`, `$GC0..3` → the Custom slots `Sound[6..9]`. Every other tag is not this
 /// channel's (`$SND`/`$DSO`/`$DSL` carry a literal kit id and ride the generic
 /// [`crate::sound::anim_events`] arms; `$SHK` is camera shake, no audio).
@@ -194,7 +193,7 @@ pub(super) fn plugin(app: &mut App) {
 mod tests {
     use super::go_event_slot;
 
-    /// The dispatcher's slot table (wow-re `go-display-sound-events.md`): `$GO0..5` are the
+    /// The dispatcher's slot table (`0x5f3e20`): `$GO0..5` are the
     /// first six display slots, `$GC0..3` the four Custom slots 6..9 — the bobber's splash is
     /// `$GC0` → slot 6. Out-of-range digits and other families are not this channel.
     #[test]
diff --git a/crates/benilla-app/src/sound/glue.rs b/crates/benilla-app/src/sound/glue.rs
index 03775eff..648f20b6 100644
--- a/crates/benilla-app/src/sound/glue.rs
+++ b/crates/benilla-app/src/sound/glue.rs
@@ -7,9 +7,9 @@
 //! - **Music**: the glue title theme (`GlueParent.lua`'s `CurrentGlueMusic`,
 //!   `Sound\Music\GlueScreenMusic\wow_main_theme.mp3`), streamed from the login screen on
 //!   (decision 0539) and kept across the glue screens (the ref keeps it through select ⇄ create).
-//!   **The click into the world does not end it** (1550/1553, wow-re §5): it plays unbroken through
-//!   the whole map load, and the stop is armed by the *load draining* — a 3.0 s fade, still behind
-//!   the loading screen. Re-entering the glue after a logout starts it again.
+//!   **The click into the world does not end it** (1550/1553, `0x46c258`): it plays unbroken
+//!   through the whole map load, and the stop is armed by the *load draining* — a 3.0 s fade, still
+//!   behind the loading screen. Re-entering the glue after a logout starts it again.
 
 use bevy::prelude::*;
 
@@ -24,14 +24,14 @@ const GLUE_MUSIC: &str = "Sound\\Music\\GlueScreenMusic\\wow_main_theme.mp3";
 
 /// The theme's own volume, under the Music slider: **0.8** — `0x45aeb0` starts the glue stream at
 /// `0x3f4ccccd` on both its arms, where the city-intro playlist and the in-world Lua `PlayMusic`
-/// use 1.0f (wow-re §5 `glue-music-world-entry.md` §5c). It is a plain scalar on the MusicVolume
+/// use 1.0f. It is a plain scalar on the MusicVolume
 /// category (the stream's flag word is 2, bit `0x2` = `[0x87cef8]`), exactly like a zone track's
 /// kit volume, so it multiplies rather than replaces the slider.
 const GLUE_MUSIC_VOLUME: f32 = 0.8;
 
 /// The stop-fade armed when the world's load drains: **3.0 s**, `[0x803248]` in `.rdata`
 /// (`0x40400000`) — the constant `0x45aeb0`'s NULL arm hands `0x45b050`, and the fade is **linear
-/// in amplitude**, not in dB (`0x7a5a50` ramps FMOD's 0–255 level; §5 §2). Not 1.0 s: that is
+/// in amplitude**, not in dB (`0x7a5a50` ramps FMOD's 0–255 level). Not 1.0 s: that is
 /// `StopGlueMusic`'s literal, and `StopGlueMusic` is a `"movie"`-screen call the world entry never
 /// makes.
 const GLUE_MUSIC_FADE_OUT_MS: u64 = 3000;
@@ -189,7 +189,7 @@ fn watch_glue_music(
     config: Res<SoundConfig>,
 ) {
     let music = &mut *music;
-    // The Music slider is live on this stream, as it is on the world's (wow-re §5 §5c: the
+    // The Music slider is live on this stream, as it is on the world's (the
     // `MusicVolume` handler's re-apply walker `0x7a6660(ecx=2)` matches the glue wrapper, so moving
     // the slider rescales the playing theme in place — mid-loading-screen included). Stand off
     // while the stop-fade runs; see [`GlueMusic::fading`].
diff --git a/crates/benilla-app/src/sound/greeting.rs b/crates/benilla-app/src/sound/greeting.rs
index c075c399..b87af8ad 100644
--- a/crates/benilla-app/src/sound/greeting.rs
+++ b/crates/benilla-app/src/sound/greeting.rs
@@ -1,6 +1,5 @@
-//! NPC vocal lines — the two byte-verified systems an NPC greets/farewells with, corrected against
-//! the director's observations and the wow-re §5 re-derivation (`wow-5875-re/system/sound/scratch/
-//! npc-greeting.md`, commit `95e360f0`; every address below carries a proof there).
+//! NPC vocal lines — the two systems an NPC greets/farewells with, corrected against the
+//! director's observations and the reference.
 //!
 //! Both systems share only the **data chain** (`NetEntity.display_id` →
 //! `CreatureDisplayInfo.field[11]` NPCSoundID → `NPCSounds {hello +0x4, goodbye +0x8, pissed +0xc}`
diff --git a/crates/benilla-app/src/sound/kit.rs b/crates/benilla-app/src/sound/kit.rs
index 618861c8..e7c28018 100644
--- a/crates/benilla-app/src/sound/kit.rs
+++ b/crates/benilla-app/src/sound/kit.rs
@@ -8,10 +8,10 @@
 //! distance-cull, recompute `category · v · rolloff · near_field` and feed the channel volume —
 //! the `0x7a4ad0`/`0x7a5000`/`0x7a5dc0` loop).
 //!
-//! Pinned by the 2026-07-03 wow-re dispatch (`benilla-pins.md`, decision 0079): variation gates
-//! are separate DBC bits (0x400 pitch / 0x800 volume — raw-copied flag word, B2), the draw is
-//! the mulhi scale [`math::variation_draw`] (B1), and **no Type→category table exists** (B3) —
-//! the client's volume category is set by which play driver was invoked, so [`play_kit`] takes
+//! Pinned 2026-07-03 (decision 0079): variation gates are separate DBC bits (0x400 pitch / 0x800
+//! volume — raw-copied flag word, `0x45c080`), the draw is the mulhi scale [`math::variation_draw`]
+//! (`0x455c70`), and **no Type→category table exists** — the client's volume category is set by
+//! which play driver was invoked (`0x45ce60`/`0x45cf00`), so [`play_kit`] takes
 //! the category from its caller (SFX for world/UI triggers, ambience/music for the scheduler
 //! drivers). Remaining INTERIM: out-of-range looping channels stop (audible again = restart by
 //! the trigger) rather than pause/resume-virtualize.
@@ -33,8 +33,8 @@ use super::{AudioListener, SoundConfig, SoundOutput};
 
 /// Which config slider scales a channel — the WoW volume categories (master is global, on the
 /// main track). A property of the **call site** (which play driver fired — channel flag bits
-/// 0x2 SFX / 0x8 ambience / fallback music, set by caller booleans; wow-re `benilla-pins.md`
-/// B3), never derived from the kit's `SoundType`.
+/// 0x2 SFX / 0x8 ambience / fallback music, set by caller booleans, `0x45ce60`/`0x45cf00`), never
+/// derived from the kit's `SoundType`.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum SoundCategory {
     Sfx,
@@ -94,8 +94,8 @@ impl SoundKits {
 pub(crate) struct ActiveChannel {
     pub(crate) kit: u32,
     /// The world entity this channel voices, when the trigger is entity-latched (the NPC
-    /// greeting's per-unit live-handle latch `[unit+0xb1c]` — wow-re `sound/scratch/
-    /// npc-greeting.md`). `None` for every other play. A tagged channel's liveness IS the
+    /// greeting's per-unit live-handle latch `[unit+0xb1c]`, `0x60c28c`/`0x60c40a`). `None` for
+    /// every other play. A tagged channel's liveness IS the
     /// latch: the pump reaps it when the sound stops, which is exactly the handle release.
     source: Option<Entity>,
     /// A source-tagged **looping** channel rides its unit (the client's tracked play `0x61fec0`):
@@ -159,8 +159,7 @@ pub(super) enum Latch {
     /// line still sounding refuses a new one.
     Greeting,
     /// The one-shot creature bark's `[unit+0xb20]` — the per-unit slot of the reference's bark
-    /// dispatch `0x623a40` (5-way jump table `0x623afc`; wow-re
-    /// `object-layer/scratch/smsg-ai-reaction.md`, `feign-death-dyndead.md` §11).
+    /// dispatch `0x623a40` (5-way jump table `0x623afc`).
     ///
     /// **The payload is the reference's `[unit+0xb24]` — the latched bark STATE**, which is the
     /// interrupt rule's whole input: `0x623a82`/`0x623a88` abort a new bark whose state is `<=`
@@ -197,13 +196,13 @@ pub(super) enum Latch {
     ObjectSound,
 }
 
-/// The **class-bark chance roll** (wow-re `sound/scratch/creature-vocal-gates.md`, §5): the
+/// The **class-bark chance roll** (`0x623520`): the
 /// reference draws `r = MulHi32(101, rand32) ∈ [0, 100]` and admits the bark iff
 /// `threshold >= r` — inclusive, so `P = (threshold + 1) / 101`.
 ///
 /// The client's generator is its own shared lagged generator (`0x882664`/`0x882668` over the
 /// `.rdata` table `0x802700`), **not** the MSVCRT LCG the animation variation walk uses, and it is
-/// reseeded from the millisecond tick at `0x402802`. The note's own guidance follows from that:
+/// reseeded from the millisecond tick at `0x402802`. The rule follows from that:
 /// **reproduce the probability, never the sequence.** So this takes any 32-bit draw — ours is the
 /// kit player's own xorshift ([`SoundKits::roll`]) — and only the arithmetic is faithful.
 pub(super) fn bark_chance_pass(threshold: u32, roll: u32) -> bool {
@@ -252,8 +251,7 @@ pub(super) const EXERTION_CHANCE_PLAYER: u32 = 35;
 ///
 /// The route that reaches these was the "still unpinned" clause above: `0x624530`'s tail →
 /// `[vtable+0x88]` → the roll `0x623520` / `0x62f940` → the 13-way column selector `0x623020`
-/// (`+0x0c/+0x10/+0x14` = DBC columns 3/4/5). wow-re
-/// `object-layer/scratch/wound-parry-gate-and-injury-vocal.md`.
+/// (`+0x0c/+0x10/+0x14` = DBC columns 3/4/5).
 pub(super) const INJURY_CHANCE_CREATURE: u32 = 60;
 /// The player twin of [`INJURY_CHANCE_CREATURE`] — `0x86424c[2] = 30`.
 pub(super) const INJURY_CHANCE_PLAYER: u32 = 30;
@@ -266,8 +264,7 @@ pub(super) const INJURY_CHANCE_PLAYER: u32 = 30;
 pub(super) const STAND_COOLDOWN: std::time::Duration = std::time::Duration::from_secs(10);
 
 /// A **voice bus** — the reference's per-bus concurrency domain, and the index into its
-/// compile-time cap table (wow-re `sound/scratch/voice-cap-and-headroom.md`, and
-/// `creature-vocal-gates.md` §3.1/§5.3).
+/// compile-time cap table (`0x87ce60`).
 ///
 /// This is **not** the volume category ([`SoundCategory`]) — VERIFIED orthogonal: the bus lives at
 /// `[chan+0x84]` and takes 0..12, while the category is flag bits `0x2`/`0x8`/`0x10` in
@@ -370,15 +367,14 @@ fn same_kit_cap_blocks(dedupe_exempt: bool, live_same_kit: usize) -> bool {
 
 /// The reference's **global voice ceiling** — the number this whole hunt came down to.
 ///
-/// `FSOUND_Init(44100, 12, 0x82)` (wow-re `sound/scratch/voice-cap-and-headroom.md` §5, VERIFIED
-/// on the binary at `0x7a492b`; the `SoundSoftwareChannels` CVar's own default is `"12"`).
-/// Hardware voices are a second bank of up to 12, but `FSOUND_SetMaxHardwareChannels` is **forced
-/// to 0** whenever `FSOUND_GetDriverCaps` reports no hardware mixing — which is every host this
-/// decade — so the note's conclusion is "exactly 12 on any host".
+/// `FSOUND_Init(44100, 12, 0x82)` (`0x7a492b`; the `SoundSoftwareChannels` CVar's own default is
+/// `"12"`). Hardware voices are a second bank of up to 12, but `FSOUND_SetMaxHardwareChannels` is
+/// **forced to 0** whenever `FSOUND_GetDriverCaps` reports no hardware mixing — which is every
+/// host this decade — so the ceiling is exactly 12 on any host.
 ///
-/// **This ceiling is what actually bounds the reference's mix, and we never had it.** The same
-/// note says of the mass-buff case that it plays "with no cap and no dedupe — what bounds it is
-/// the device ceiling, and nothing else". A probe capture measured benilla at **42 simultaneous
+/// **This ceiling is what actually bounds the reference's mix, and we never had it.** The
+/// mass-buff case plays through `0x458870` with no cap and no dedupe — what bounds it is the
+/// device ceiling, and nothing else. A probe capture measured benilla at **42 simultaneous
 /// voices**, over 12 for 23 % of the run, which is what made the summed mix ask for +13.4 dBFS
 /// and the limiter (1551) pull the whole mix down by up to 13.5 dB a quarter of the time. The
 /// clipping became pumping; the director heard no improvement, correctly. Decision 1557.
@@ -532,7 +528,7 @@ pub(super) struct PlayExtras {
     /// bit 0x20 into the FMOD flags word, consumed by `0x7a66a0`), and a caller that already
     /// guarantees one channel per kit by construction must not be held to it a second time. The
     /// ambient emitter pool ([`super::emitter_pool`]) is that caller: it dedupes **structurally**,
-    /// one entry per SoundEntries id (wow-re `doodad-sound-emitters.md` §15), and its opens go
+    /// one entry per SoundEntries id (`0x461e60`), and its opens go
     /// through `0x7a5680` → `0x7a54d0`, which never reaches that gate at all.
     ///
     /// It is not a nicety. `NightElfStreetLampLoop` is Flags **0x220**, so with the gate applied a
@@ -683,11 +679,11 @@ pub(super) fn play_kit_ext(
         return Ok(false);
     }
 
-    // Duplicate suppression — byte-verified (wow-re uisound-tables.md, corrected §5): the FMOD
-    // pre-play gate 0x7a66a0 drops a play when kit flag 0x20 is set AND a same-kit instance is
-    // still audible (0x458f40 lifts SoundEntries +0x7c bit 0x20 into the FMOD flags word). The
-    // gate's OTHER arm — an always-on per-category concurrent cap (count[0xcf553c] >=
-    // limit[0x87ce60], 13 categories) — stays a deferral until that limit table is read out.
+    // Duplicate suppression: the FMOD pre-play gate 0x7a66a0 drops a play when kit flag 0x20 is
+    // set AND a same-kit instance is still audible (0x458f40 lifts SoundEntries +0x7c bit 0x20
+    // into the FMOD flags word). The gate's OTHER arm — an always-on per-category concurrent cap
+    // (count[0xcf553c] >= limit[0x87ce60], 13 categories) — stays a deferral until that limit
+    // table is read out.
     let live_same_kit = out.channels.iter().filter(|c| c.kit == id).count();
     if no_duplicates_blocks(dedupe_exempt, flags, live_same_kit) {
         return Ok(false);
@@ -729,8 +725,9 @@ pub(super) fn play_kit_ext(
     // Decode (cached).
     let data = kits.sfx(assets, &path)?;
 
-    // Per-shot variation — separate DBC gates (B2): 0x800 volume, 0x400 pitch (no 5875 kit
-    // sets 0x800, so volume variation is dormant in this build's data — the gate is faithful).
+    // Per-shot variation — separate DBC gates: 0x800 volume (`0x458c60`), 0x400 pitch (`0x458da0`)
+    // (no 5875 kit sets 0x800, so volume variation is dormant in this build's data — the gate is
+    // faithful).
     let v = if flags & sound_kit_flags::VARY_VOLUME != 0 {
         let draw = math::variation_draw(kits.rng.next());
         math::variation_volume(Some(draw), volume, mult)
@@ -826,7 +823,7 @@ pub(super) fn play_kit_ext(
 }
 
 /// Does `unit` hold a **live one-shot voice channel** — the reference's `[unit+0xb20]` handle,
-/// nonzero-gated (wow-re `object-layer/scratch/smsg-ai-reaction.md`) — and if so, at which
+/// nonzero-gated — and if so, at which
 /// **state**? `Some(state)` is the pair `[0xb20]` live + `[0xb24]`; `None` is a free slot, which
 /// is `0x623a74`/`0x623a7d`'s "allowed, no comparison" path.
 ///
@@ -1033,7 +1030,7 @@ fn near_field(d_sq: f32, cutoff: f32) -> f32 {
 impl SoundKits {
     /// Resolve a SoundEntries kit id by its `PlaySoundByName` key — the client's name-hash
     /// registry lookup (`0x458030` family). The ghost ambience/music tracks are named entries
-    /// ("Ghost"/"GhostMusic" — wow-re zone-music-ambience + the 0308 death dispatch).
+    /// ("Ghost"/"GhostMusic" — the reference's zone music/ambience + the 0308 death dispatch).
     pub(crate) fn id_by_name(&self, name: &str) -> Option<u32> {
         self.catalog.by_name(name).map(|k| k.id)
     }
@@ -1104,10 +1101,11 @@ impl SoundKits {
         if let Some(d) = self.cache.get(&key) {
             return Ok(d.clone());
         }
+        // **Two stores, one rule** — the chain, then an addon's own loose file
+        // ([`benilla_assets::read_chain_or_loose`], decision 1322's resolver): `PlaySoundFile` is
+        // a by-path verb, and the audio an addon ships lives on disk, never in an MPQ.
         let bytes = assets
-            .chain
-            .lock_recover()
-            .read_file(path)
+            .read_file_or_loose(path)
             .with_context(|| format!("reading {path}"))?;
         let data = mixer::sfx_from_bytes(bytes)?;
         self.cache.insert(key, data.clone());
@@ -1294,7 +1292,7 @@ fn stop_all_channels(mut out: NonSendMut<SoundOutput>) {
 
 /// Drop the decoded-SFX cache on a cross-map transition (`world_map::MapChange` — see its doc):
 /// kit variations are decoded on demand, so a new map's soundscape rebuilds its own working set
-/// while the old map's decodes stop occupying RAM forever (the #bugs teleport leak). Playing
+/// while the old map's decodes stop occupying RAM forever (the teleport leak). Playing
 /// channels own their frames (`StaticSoundData` clones share them), so nothing audible cuts.
 fn evict_kit_cache(
     mut changes: MessageReader<benilla_world::world_map::MapChange>,
@@ -1510,7 +1508,7 @@ mod tests {
     }
 
     /// The ceiling is the reference's, not a number we liked: `FSOUND_Init(44100, 12, 0x82)`,
-    /// verified on the binary at `0x7a492b` (wow-re `voice-cap-and-headroom.md` §5), with the
+    /// verified on the binary at `0x7a492b`, with the
     /// hardware bank forced to 0 on any host without hardware mixing. Pinned so a later "let's
     /// raise it a bit" has to argue with the byte-fact rather than drift past it.
     #[test]
@@ -1639,9 +1637,8 @@ mod tests {
     }
 
     /// **The lane split.** Both suppressors are the ONE-SHOT lane's (`0x458f40` → `0x7a66a0`);
-    /// the ambient emitter pool's opens go through `0x7a5680` → `0x7a54d0` and never reach them
-    /// (wow-re `doodad-sound-emitters.md` §15), because that lane already guarantees one channel
-    /// per SoundEntries id structurally.
+    /// the ambient emitter pool's opens go through `0x7a5680` → `0x7a54d0` and never reach them,
+    /// because that lane already guarantees one channel per SoundEntries id structurally.
     ///
     /// `NightElfStreetLampLoop` is the case that proves it matters rather than tidies: Flags
     /// **0x220**, so an un-exempt pool entry could not replace its own 3.0 s fade-out — the lamp's
diff --git a/crates/benilla-app/src/sound/limiter.rs b/crates/benilla-app/src/sound/limiter.rs
index 826c303c..1117f85f 100644
--- a/crates/benilla-app/src/sound/limiter.rs
+++ b/crates/benilla-app/src/sound/limiter.rs
@@ -45,8 +45,8 @@
 //! untouched, and the thing being replaced is not a reference behaviour but *kira's* hard clamp.
 //!
 //! **The reference has no headroom mechanism at all — on either side of its API boundary.** That
-//! is now read, not assumed: wow-re's §6 proved no constant factor exists anywhere in `WoW.exe`
-//! (a close-up 1.0 kit reaches `FSOUND_SetVolume(255)` with the SFX master also 255), and
+//! is now read, not assumed: no constant factor exists anywhere in `WoW.exe` (a close-up 1.0 kit
+//! reaches `FSOUND_SetVolume(255)` through `0x7a5dc0` with the SFX master also 255), and
 //! decision 1563 opened `fmod.dll` itself and found the other half — a complete multiply census
 //! over all three software mixers turns up per-channel volume, `1/255`, `1/256`, `2⁻³¹` and a
 //! mix-rate-derived ramp constant, and **nothing that depends on how many voices are live**. The
@@ -56,7 +56,7 @@
 //!
 //! Two things it does have are often mistaken for headroom and are neither: the 12-voice device
 //! ceiling with the 13 per-bus caps (ported — 1555, 1557), which bounds the *count*; and the SFX
-//! auto-duck (`0x457960`), which wow-re §10 corrected — it is a **sidechain for server-pushed
+//! auto-duck (`0x457960`) — it is a **sidechain for server-pushed
 //! unit voice lines** (`SMSG_PLAY_OBJECT_SOUND`), armed only by that one packet's pool, with the
 //! arming sound itself exempt. Footsteps, spell impacts, weapon hits, UI sounds, creature barks,
 //! music and ambience never arm it. It is not a bus limiter and would not have saved the mass
diff --git a/crates/benilla-app/src/sound/liquid_loop.rs b/crates/benilla-app/src/sound/liquid_loop.rs
index 47de19c5..a1b934b7 100644
--- a/crates/benilla-app/src/sound/liquid_loop.rs
+++ b/crates/benilla-app/src/sound/liquid_loop.rs
@@ -1,8 +1,7 @@
 //! The **above-water liquid ambient loops** — the continuous ocean / river / lava / slime beds
-//! the client plays near liquid (wow-re `liquid-ambience-loop.md`, §5-verified; decision 0506).
-//! The Booty Bay ocean wash is this system. A distinct layer from the submerged UnderWaterLoop
-//! swap ([`super::zone`], B6): these are **3D-positioned loops LAYERED over the zone-ambience
-//! bed**, not a replacement of it.
+//! the client plays near liquid (decision 0506). The Booty Bay ocean wash is this system. A
+//! distinct layer from the submerged UnderWaterLoop swap ([`super::zone`], `0x460af0`): these are
+//! **3D-positioned loops LAYERED over the zone-ambience bed**, not a replacement of it.
 //!
 //! The verified law (driver `0x462b50`, groups `0xb230b8`):
 //! - **Trigger:** liquid of a class within **9.0 yd of the PLAYER** (not the camera) arms that
@@ -136,9 +135,9 @@ fn drive_liquid_loops(
     let player_pos = player_tf.translation;
     let player_wow = bevy_to_wow(player_pos);
 
-    // Scan: the nearest wet point per class within the radius (the ref's `nearest_liquid` walk;
-    // AABB-clamp approximation, module docs). The walk is the world's; the priority order, the
-    // voice cap and the slew below are ours.
+    // Scan: the nearest wet point per class within the radius (the ref's nearest-liquid walk
+    // `0x6723f0`; AABB-clamp approximation, module docs). The walk is the world's; the priority
+    // order, the voice cap and the slew below are ours.
     let best = world.nearest_liquid_per_class(player_wow, TRIGGER_RADIUS);
 
     // Priority River > Ocean > Magma > Slime, cap 2: the class indices ARE the priority order.
diff --git a/crates/benilla-app/src/sound/math.rs b/crates/benilla-app/src/sound/math.rs
index fc4310d3..7e7dce1d 100644
--- a/crates/benilla-app/src/sound/math.rs
+++ b/crates/benilla-app/src/sound/math.rs
@@ -1,5 +1,5 @@
-//! WoW's owned audio math — behavioral ports of the bit-exact wow-re transcriptions
-//! (`wow-5875-re/crates/sound`, T3; decision 0070 "the audible fingerprint").
+//! WoW's owned audio math — behavioral ports of the reference's own functions (decision 0070
+//! "the audible fingerprint").
 //!
 //! Ports are **behavioral**, not bit-exact: the originals reproduce x87 PC_53 double-rounding
 //! spill-for-spill; here the formulas run in plain f32/f64 (differences are below audibility and
@@ -19,7 +19,7 @@ pub(crate) fn variation_volume(draw: Option<i32>, base: f32, mult: f32) -> f32 {
     };
     let v = v * mult as f64;
     // `!(v > 0.0)` is deliberate, NOT `v <= 0.0`: NaN must land in the zero arm (the binary's
-    // unordered `fcom` branch) — the same suppressed-lint idiom as the wow-re transcription.
+    // unordered `fcom` branch).
     #[allow(clippy::neg_cmp_op_on_partial_ord)]
     if !(v > 0.0) {
         0.0
@@ -30,7 +30,7 @@ pub(crate) fn variation_volume(draw: Option<i32>, base: f32, mult: f32) -> f32 {
     }
 }
 
-/// Per-shot pitch variation — `0x458da0` `variation_pitch`: the playback frequency in Hz handed
+/// Per-shot pitch variation — `0x458da0`: the playback frequency in Hz handed
 /// to `FSOUND_SetFrequency` when the kit varies pitch: `freq = (22050 · (draw + 0x55)) / 100`
 /// (32-bit wrapping mul, truncating division — exactly the binary's integer path). The backend
 /// consumes a *rate*, so callers divide by the file's sample rate: a 22050 Hz WAV at draw 15
@@ -42,7 +42,7 @@ pub(crate) fn variation_pitch_freq(draw: i32) -> i32 {
 
 /// The variation draw: raw PRNG word → `{0..30}` via **multiply-high scale-to-range**
 /// (`mulhi(31, raw)` — `mov ecx,0x1f` @ `0x458d35`/`0x458e85` through the `0x455c70` mul-high
-/// helper; wow-re `benilla-pins.md` B1, VERIFIED). NOT a modulo: `floor(31·raw / 2³²)`, uniform
+/// helper). NOT a modulo: `floor(31·raw / 2³²)`, uniform
 /// over 31 values given a uniform word. Volume spans ±0.15 about base, pitch ×0.85..×1.15.
 pub(crate) fn variation_draw(raw: u32) -> i32 {
     ((u64::from(raw) * 31) >> 32) as i32
@@ -53,15 +53,15 @@ pub(crate) fn dist_sq(a: bevy::math::Vec3, b: bevy::math::Vec3) -> f32 {
     a.distance_squared(b)
 }
 
-/// Selection-time audibility — `0x45cdf0` `sound_audible_distance`: play iff `maxdist² > d²`
+/// Selection-time audibility — `0x45cdf0`: play iff `maxdist² > d²`
 /// (strict; equal/NaN inaudible). `maxdist` is the kit's `DistanceCutoff`; `0` means
 /// non-positional (callers skip the gate — the `0x7a5ca0` sentinel).
 pub(crate) fn audible(d_sq: f32, maxdist: f32) -> bool {
     maxdist * maxdist > d_sq
 }
 
-/// The near-field attenuation WoW layers ON TOP of the backend's rolloff — `0x7a5000`
-/// `channel_dist_update`, the per-frame value at channel `+0x78`:
+/// The near-field attenuation WoW layers ON TOP of the backend's rolloff — `0x7a5000`, the
+/// per-frame value at channel `+0x78`:
 /// `atten = 1 − clamp(√d² − maxdist·0.9, 0, maxdist·0.1) / (maxdist·0.1)` — full volume inside
 /// 90% of `maxdist`, a linear 1→0 ramp across the last 10%. Callers virtualize the channel
 /// beyond `maxdist` instead of calling this.
@@ -76,14 +76,13 @@ pub(crate) fn near_field_atten(d_sq: f32, maxdist: f32) -> f32 {
 }
 
 // NOTE: `0x457960` is deliberately NOT ported here. benilla once modelled it as a music
-// "transition crossfade" (`music_volume_fade`); the wow-re §5 (`benilla-pins.md` B15) corrected
-// that: it is the SFX-bus auto-duck (the SoundVolume category dips to 50 % while SFX one-shots
-// play, restoring over 3 s), unrelated to music transitions, which benilla does not model.
+// "transition crossfade"; it is the SFX-bus auto-duck (the SoundVolume category dips to 50 %
+// while SFX one-shots play, restoring over 3 s), unrelated to music transitions, which benilla
+// does not model.
 // The real music transition is a 4.0 s backend fade-stop (see `sound::zone`). Decision 0100.
 
 /// The global 3D rolloff factor — `FSOUND_3D_SetRolloffFactor(4.0)` at device init
-/// (`0x7a47b1`, prefill `0x7a495a` = 4.0f; `SoundRolloffFactor` CVar default "4" round-trips it
-/// — wow-re `benilla-pins.md` B12, VERIFIED).
+/// (`0x7a47b1`, prefill `0x7a495a` = 4.0f; `SoundRolloffFactor` CVar default "4" round-trips it).
 pub(crate) const ROLLOFF_FACTOR: f32 = 4.0;
 
 /// The distance rolloff FMOD computed between the kit's `MinDistance` and the far plane —
diff --git a/crates/benilla-app/src/sound/missile.rs b/crates/benilla-app/src/sound/missile.rs
index 7da4f859..f191405d 100644
--- a/crates/benilla-app/src/sound/missile.rs
+++ b/crates/benilla-app/src/sound/missile.rs
@@ -1,6 +1,6 @@
 //! Projectile **flight sound** (`SpellVisual` field 10): the loop a missile carries while it
 //! travels — the thrown weapon's `WeaponLoop`, the fireball's `FireMissileLoop`. The client keeps
-//! a per-missile loop handle (`CMissile+0x44`, wow-re `w2f1.md`) started at launch and killed at
+//! a per-missile loop handle (`CMissile+0x44`) started at launch and killed at
 //! arrival; ours is a channel **tracked to the missile entity** (the tracked-loop follow in
 //! [`super::kit::pump_channels`] rides it along the flight) begun on [`MissileSound::Start`] and
 //! reaped on [`MissileSound::Stop`], which `crate::entities::missile` writes at launch/arrival.
diff --git a/crates/benilla-app/src/sound/mix_tap.rs b/crates/benilla-app/src/sound/mix_tap.rs
index a929b952..416111c7 100644
--- a/crates/benilla-app/src/sound/mix_tap.rs
+++ b/crates/benilla-app/src/sound/mix_tap.rs
@@ -21,6 +21,9 @@
 //! The audio-thread half never allocates or blocks (a fixed ring push per sample; overflow is
 //! counted, not waited on). The ring holds [`RING_SECONDS`] of stereo audio — the writer wakes
 //! every [`FLUSH_EVERY`] and would have to stall ~50× past its cadence before a sample drops.
+//!
+//! Read a capture back with `scripts/mixsum.py <path.wav>`: what the mix was doing, when, in
+//! numbers (clipping, level, silence, steps).
 
 use bevy::prelude::*;
 use kira::effect::{Effect, EffectBuilder};
diff --git a/crates/benilla-app/src/sound/mixer.rs b/crates/benilla-app/src/sound/mixer.rs
index 13dd1fff..ffb03a07 100644
--- a/crates/benilla-app/src/sound/mixer.rs
+++ b/crates/benilla-app/src/sound/mixer.rs
@@ -2,7 +2,7 @@
 //!
 //! The real client delegates the entire audible mix to FMOD 3.x — spatialization/pan, min/max
 //! distance rolloff, doppler, reverb, decode, streaming — and owns only the parameters it feeds
-//! (wow-re `system/sound`, T3, pinned by the import-table byte-fact: no `FSOUND_SetPan`, no
+//! (pinned by the import-table byte-fact: no `FSOUND_SetPan`, no
 //! `FSOUND_PlaySound`). This module is that delegation seam in benilla: everything above it (the
 //! kit player, the schedulers) computes WoW's owned parameter math; everything below is the
 //! backend's. Keep this surface shaped like the FMOD import contract — play/stop, per-channel
@@ -49,7 +49,7 @@ pub(crate) use kira::track::SpatialTrackHandle;
 /// An immediate (zero-duration) parameter change. kira requires a tween on every setter; the
 /// WoW-side ramps (volume rates, crossfades) are our own math updated per frame, so the backend
 /// must not add smoothing of its own on top. Use this for a change that is genuinely a *step* —
-/// a reverb preset switch (verified instant, `benilla-pins.md` A2), an initial value. For the
+/// a reverb preset switch (instant, `0x45a720`), an initial value. For the
 /// **per-frame volume feed** use [`glide`]: a step there is an audible click, not fidelity.
 pub(crate) fn snap() -> Tween {
     Tween {
@@ -110,7 +110,7 @@ pub(crate) fn fade(ms: u64) -> Tween {
 }
 
 /// Linear amplitude `[0,1]` → the backend's decibel volume. WoW's owned pipeline produces linear
-/// amplitudes (the category mix `cat·v·atten`, wow-re `0x7a5dc0`); FMOD consumed them as 0..255
+/// amplitudes (the category mix `cat·v·atten`, `0x7a5dc0`); FMOD consumed them as 0..255
 /// levels. kira consumes dB, so the seam converts: `20·log10(amp)`, with kira's `SILENCE` floor
 /// (−60 dB) for amp ≤ 10⁻³ (which is below one 1/255 FMOD step anyway).
 pub(crate) fn amp_to_db(amp: f32) -> Decibels {
@@ -123,8 +123,8 @@ pub(crate) fn amp_to_db(amp: f32) -> Decibels {
 
 /// The one open audio device + its listener. `Mixer` methods are the only place kira's manager is
 /// touched; everything above computes parameters. There is deliberately **no master filter**:
-/// the real client applies no DSP beyond FMOD's reverb (53 FSOUND imports, zero `FSOUND_FX_*` —
-/// wow-re `benilla-pins.md` B6); underwater is the reverb preset + the ambience swap, both
+/// the real client applies no DSP beyond FMOD's reverb (53 FSOUND imports, zero `FSOUND_FX_*` in
+/// the import table); underwater is the reverb preset + the ambience swap, both
 /// upstream of this seam.
 pub(crate) struct Mixer {
     manager: AudioManager<OutputBackend>,
@@ -241,9 +241,9 @@ impl Mixer {
 
     /// Apply a zone reverb preset — the seam mirror of `FSOUND_Reverb_SetProperties` (the real
     /// client marshals the `SoundProviderPreferences` row into EAX listener properties and hands
-    /// them to FMOD; wow-re `0x45a790`/`0x7a5fa0`). `None` = no preset → wet to silence (the
-    /// client's silenced-GENERIC default, `0x45a830`). The switch is **instant** — verified, the
-    /// client applies the new properties with no ramp (`benilla-pins.md` A2).
+    /// them to FMOD; `0x45a790`/`0x7a5fa0`). `None` = no preset → wet to silence (the
+    /// client's silenced-GENERIC default, `0x45a830`). The switch is **instant** — the
+    /// client applies the new properties with no ramp (`0x45a720`).
     ///
     /// The EAX→Freeverb projection is this backend's own lossy mapping (decision 0078):
     /// - `feedback = 10^(−0.108 / DecayTime)`, from Freeverb's RT60 relation at its ~36 ms mean
diff --git a/crates/benilla-app/src/sound/mod.rs b/crates/benilla-app/src/sound/mod.rs
index 13012951..3e83a372 100644
--- a/crates/benilla-app/src/sound/mod.rs
+++ b/crates/benilla-app/src/sound/mod.rs
@@ -37,6 +37,7 @@ mod mix_tap;
 mod mixer;
 mod money;
 mod mount;
+mod net;
 // Crate-visible for one reader: the dev-only stall watchdog asks `output::device_open` before
 // it suspends the process (decision 1857). Dev may see anything; nothing here knows dev exists.
 pub(crate) mod output;
@@ -67,14 +68,14 @@ pub(crate) use zone::ExplorationSounds;
 /// Player-facing audio config — always-on, player-faithful defaults (decision 0026: no
 /// gameplay→dev coupling; the debug panel edits this, it doesn't own it).
 ///
-/// Defaults are the client's CVar registration defaults (wow-re `benilla-pins.md` B10,
-/// VERIFIED): `MasterVolume` 1.0, `SoundVolume` 1.0, **`MusicVolume` 0.4**,
+/// Defaults are the client's CVar registration defaults (`0x456fe0`, `0x460a60`):
+/// `MasterVolume` 1.0, `SoundVolume` 1.0, **`MusicVolume` 0.4**,
 /// **`AmbienceVolume` 0.6** — a fresh 1.12 install is NOT uniform full volume.
 #[derive(Resource)]
 pub(crate) struct SoundConfig {
     /// Master enable — 1.12's `MasterSoundEffects` CVar, the Sound options "Enable All Sound"
-    /// checkbox (SoundOptionsFrame.lua index 1; registrar default "1", B10). In the binary its
-    /// callback sets the engine-wide pause flag (`0x457500` → `0x7a6570` → `DAT_0087cf00`);
+    /// checkbox (SoundOptionsFrame.lua index 1; registrar default "1", `0x45737a`). In the binary
+    /// its callback sets the engine-wide pause flag (`0x457500` → `0x7a6570` → `DAT_0087cf00`);
     /// benilla zeroes every category through [`Self::category_amp`] instead — channels keep
     /// running silently (the `muted` posture), same audible truth.
     pub enabled: bool,
@@ -96,11 +97,12 @@ pub(crate) struct SoundConfig {
     pub music: f32,
     pub ambience: f32,
     /// The per-category enable checkboxes — 1.12's own `EnableMusic` / `EnableAmbience` CVars
-    /// (registrar defaults "1", wow-re B10; 1.12 has NO SFX-only toggle — `MasterSoundEffects`
-    /// above is the master). Gated in [`Self::category_amp`], so a disable silences the category
-    /// everywhere at once. Divergence, disclosed: the reference's `EnableMusic` callback
-    /// stops/re-selects the music stream (`0x457490` → `0x45b050`/`0x45aeb0`) — benilla keeps
-    /// the stream alive at zero, so re-enabling resumes mid-track where the reference re-picks.
+    /// (registrar defaults "1", `0x45739b`/`0x460a9d`; 1.12 has NO SFX-only toggle —
+    /// `MasterSoundEffects` above is the master). Gated in [`Self::category_amp`], so a disable
+    /// silences the category everywhere at once. Divergence, disclosed: the reference's
+    /// `EnableMusic` callback stops/re-selects the music stream (`0x457490` →
+    /// `0x45b050`/`0x45aeb0`) — benilla keeps the stream alive at zero, so re-enabling resumes
+    /// mid-track where the reference re-picks.
     pub music_enabled: bool,
     pub ambience_enabled: bool,
     /// **Error speech** — 1.12's `EnableErrorSpeech` CVar (`CVar::Register` at `0x457877`,
@@ -114,8 +116,7 @@ pub(crate) struct SoundConfig {
     /// (decision 1847). `false` = the reference's own behaviour: alt-tab away and the client goes
     /// quiet; come back and it returns.
     ///
-    /// The reference's mechanism, VERIFIED end to end in wow-re
-    /// `sound/scratch/focus-mute-law.md` (§5 round, 2026-09-02, dispatched from here): **`WM_ACTIVATE`
+    /// The reference's mechanism: **`WM_ACTIVATE`
     /// and nothing else** — `WM_ACTIVATEAPP`, `WM_SETFOCUS` and `WM_KILLFOCUS` all fall through the
     /// WndProc's remap table to `DefWindowProcA` — normalised to a 0/1 flag at `0x42d080`, enqueued
     /// as OS-event tag 6 (`0x42d0cb`, the only tag-6 producer image-wide), raised as event-bus
@@ -147,8 +148,8 @@ pub(crate) struct SoundConfig {
     ///
     /// There is **no 1.12 CVar and no 1.12 checkbox** for this — `SoundOptionsFrame.lua` declares
     /// seven checkboxes (indices 1, 2, 4–8) and four sliders, none of them this, and none of the
-    /// reference's 214 `CVar::Register` sites names it (wow-re `re/cvar/cvar-register-sites.tsv`;
-    /// `Register` is the only creation path, so `Config.wtf` can hold no such key either). So the
+    /// reference's 214 `CVar::Register` (`0x63db90`) sites names it (`Register` is the only
+    /// creation path, so `Config.wtf` can hold no such key either). So the
     /// row is the `autoLootDefault` posture: benilla's persistence is the CVar store (0954), and a
     /// setting with no 1.12 CVar takes the later-era engine's spelling rather than an invented one.
     pub background_sound: bool,
@@ -187,8 +188,7 @@ pub(crate) struct SoundConfig {
     pub world_hold: bool,
     /// **The cinematic's music stop** — NOT a CVar, a per-frame live bit fed from
     /// [`crate::cinematic::Cinematic`] by [`feed_music_suppression`], and the exact runtime
-    /// counterpart of the reference's `[0xb06cc8]` (wow-re `sound/scratch/cinematic-audio-law.md`,
-    /// §5, VERIFIED).
+    /// counterpart of the reference's `[0xb06cc8]`.
     ///
     /// A cinematic asserts precisely what `/console EnableMusic 0` asserts: both reach the same
     /// setter `0x4603b0` — the CVar handler at `0x4574a4`, the cinematic's own start at `0x48ed83`
@@ -217,7 +217,7 @@ pub(crate) struct SoundConfig {
     /// The **output limiter** — benilla's own `SoundOutputLimiter` CVar (decision 1551), default
     /// **on**. Not a 1.12 CVar: the reference has no such DSP and does not need one, because it
     /// hands its whole audible mix to FMOD 3 and carries its headroom elsewhere (the SFX-bus
-    /// auto-duck, wow-re `benilla-pins.md` B15). benilla sums into f32 and kira answers an
+    /// auto-duck, `0x457960`). benilla sums into f32 and kira answers an
     /// over-scale sum with a hard clamp, which is audible distortion the moment two full-scale
     /// kits overlap — see [`limiter`] for the measured arithmetic. This exists so the fix can be
     /// A/B'd against what it fixed: `/run SetCVar("SoundOutputLimiter", 0)` applies live.
@@ -231,8 +231,8 @@ pub(crate) struct SoundConfig {
     /// per-frame driver `0x482ea0`. The sink `FSOUND_3D_Listener_SetAttributes` has exactly one
     /// call site image-wide (`0x483218`), so this one branch decides the whole listener.
     ///
-    /// **It selects position AND orientation together, never one alone** (wow-re
-    /// `sound/scratch/benilla-pins.md` §B14, VERIFIED): `1` puts the listener on the active
+    /// **It selects position AND orientation together, never one alone**: `1` puts the listener on
+    /// the active
     /// mover with the character's *facing* about world-up — so volume and pan never change with
     /// zoom or camera orbit — and `0` puts it at the camera eye with the camera's own basis.
     /// Velocity is NULL either way, so the listener contributes no doppler in either mode.
@@ -250,21 +250,20 @@ pub(crate) struct SoundConfig {
     /// **It does NOT gate:** creature reaction barks, NPC greetings, `$ESD` emote-state sounds, or
     /// FrameXML `PlaySound()` — those are the other per-unit channels.
     ///
-    /// **One thing wow-re does not settle**, and it is recorded rather than guessed: two of its
-    /// notes place the lookup in `0x623c80` (received text-emote only), a third places it on the
+    /// **One thing is not settled**, and it is recorded rather than guessed: one reading places the
+    /// lookup in `0x623c80` (received text-emote only), another places it on the
     /// shared leg `0x623c10`, which the `$CSD` M2 anim-event also enters — and if it is really
-    /// `0x623c10`, this CVar silences those too. Nothing records whether the *outgoing* local
-    /// `DoEmote` vocal is gated at all. We take the narrower, twice-recorded reading: the received
-    /// path. Widening it later is one more call site, not a redesign.
+    /// `0x623c10`, this CVar silences those too. Whether the *outgoing* local `DoEmote` vocal is
+    /// gated at all is open. We take the narrower, better-attested reading: the received path.
+    /// Widening it later is one more call site, not a redesign.
     pub emote_sounds: bool,
     /// **Zone music with no silence gap** — 1.12's `SoundZoneMusicNoDelay` (`0x4578b3`, registrar
     /// default `"0"`; the stock Sound panel's check button 6, labelled *Loop Music*). Read by
     /// [`zone::next_track_time`], which is the reference's `0x4601f0` — and its sole caller there
     /// is the natural end-of-track reap, which is exactly ours.
     ///
-    /// **It removes the intra-zone loop-restart gap, not the zone-change transition** (wow-re
-    /// `sound/scratch/zone-music-ambience-transition.md` Q1/Q2, which corrects that note's own
-    /// earlier framing): the thing it deletes is the randomised `ZoneMusic.dbc`
+    /// **It removes the intra-zone loop-restart gap, not the zone-change transition**: the thing it
+    /// deletes is the randomised `ZoneMusic.dbc`
     /// SilenceIntervalMin/Max wait between successive plays of the *same* zone's track, whose
     /// length is data rather than a constant. A zone CHANGE is already immediate and always was —
     /// the incoming track starts on the next tick while the outgoing fades over 4 s, an overlap
@@ -431,7 +430,7 @@ impl SoundOutput {
 /// Bevy space. Computed once by [`update_audio_listener`]; consumed by the mixer feed, the channel
 /// pump's distance/rolloff math, and each trigger's selection-time audibility gate.
 ///
-/// The client's `SoundListenerAtCharacter` default is `"1"` (wow-re benilla-pins B14): the listener
+/// The client's `SoundListenerAtCharacter` default is `"1"` (`0x457890`): the listener
 /// sits at the **character**, not the camera — so 3D volume and pan are independent of zoom and
 /// camera orbit. `pos` = the self-avatar's head (feet + [`head_height`]); `rot` = the character's
 /// *facing* about world-up (`Quat::from_rotation_y(face_yaw)`), so panning tracks where the body
@@ -478,13 +477,14 @@ fn load_materials(mut commands: Commands, assets: Option<Res<benilla_assets::Wor
 /// object not streamed, and a template still in flight (asked once, answered next frame).
 pub(super) fn worn_chest_material(
     store: Option<&crate::net::ObjectStore>,
+    objects: &crate::net::Objects,
     items: &crate::items::Items,
     net: &crate::net::NetCommands,
 ) -> Option<u32> {
     /// Index 4 of the inv-slot array — `0x62fa50`/`0x62fb86` read the fifth 8-byte guid.
     const EQUIPMENT_SLOT_CHEST: u8 = 4;
     let guid = store?.0.player_inv_slot(EQUIPMENT_SLOT_CHEST)?;
-    let entry = items.object(guid)?.object_entry()?;
+    let entry = objects.object(guid)?.object_entry()?;
     Some(items.held(entry, net)?.material)
 }
 
@@ -551,12 +551,13 @@ pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut sound: ResMut<Sound
 
 impl Plugin for SoundPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.add_observer(on_cvar);
         // Who gets sound: a run a human launched, and only that. The default posture is audible
         // (decision 1026 — `SoundConfig::muted` starts false), so the silence has to be opt-in by
         // the *automated* callers, both of which are unattended by construction:
         //   $WOW_NOSOUND — an agent opening the client to check something (the dispatch recipe in
-        //                  `method.md` sets it; nobody is listening, and a background window that
+        //                  `docs/METHOD.md` sets it; nobody is listening, and a background window that
         //                  starts playing zone music is pure noise in a shared room).
         //   $WOW_CAPTURE — the visual harness. A screenshot has no audio track; opening a device
         //                  per capture is cost and racket for nothing.
@@ -675,9 +676,8 @@ fn update_audio_listener(
     self_av: Query<(&Transform, Option<&CameraPivot>), With<Embodied>>,
     cam: Query<&Transform, (With<WorldCamera>, Without<Embodied>)>,
 ) {
-    // **A cinematic takes the listener to the camera, and it OVERRIDES the CVar** — wow-re
-    // `sound/scratch/cinematic-audio-law.md` (VERIFIED; it also promoted `benilla-pins.md` B14's
-    // `camera+0x50` label from INFERRED to VERIFIED). `0x483112 jne 0x4831f0` takes the camera
+    // **A cinematic takes the listener to the camera, and it OVERRIDES the CVar**:
+    // `0x483112 jne 0x4831f0` takes the camera
     // branch whenever `camera+0x50 != 0`, ahead of and regardless of `SoundListenerAtCharacter`;
     // the flag is armed from the cinematic's own start path (`0x48ee55` → `0x50c870` → `0x50c9f2`
     // → `0x50c740`) and cleared only by `0x50ca50` at the stop.
diff --git a/crates/benilla-app/src/sound/money.rs b/crates/benilla-app/src/sound/money.rs
index 8a7a0757..8079c4a2 100644
--- a/crates/benilla-app/src/sound/money.rs
+++ b/crates/benilla-app/src/sound/money.rs
@@ -2,7 +2,7 @@
 //!
 //! The real 1.12 client has **no dedicated money kit**: every coinage change plays
 //! `LOOTWINDOWCOINSOUND` (SoundEntries kit 895) from a `CMirrorHandler` callback registered on
-//! `PLAYER_FIELD_COINAGE` (`0x5ddf30`, wow-re `system/sound/scratch/acquire-spend-sounds.md`) — the
+//! `PLAYER_FIELD_COINAGE` (`0x5ddf30`) — the
 //! same watcher that also fires the `PLAYER_MONEY` UI event. So one rule reproduces the coin for
 //! **buy** (spend), **sell** (gain), and **loot money** — all three move `PLAYER_FIELD_COINAGE` on
 //! the wire — plus any other purse change (quest reward, mail, trade), exactly as the client does.
@@ -10,11 +10,12 @@
 //! [`super::ui`].)
 //!
 //! benilla plays it 2D on the SFX bucket when the mirrored coinage moves. The **first** observation
-//! after login/reconnect is a seed, not a change — it never plays for the initial populate (the one
-//! INFERRED point in the wow-re note; suppressing it is the correct-feeling choice and avoids a coin
-//! on every zone-in). The real client double-plays loot money (an optimistic play at the click plus
-//! this watcher); benilla keeps the single watcher-driven play — one clean coin on the confirmed
-//! change, imperceptibly latent on localhost.
+//! after login/reconnect is a seed, not a change — it never plays for the initial populate (whether
+//! the reference's watcher fires on the first coinage set at login is inferred, unconfirmed in the
+//! binary; suppressing it is the correct-feeling choice and avoids a coin on every zone-in). The
+//! real client double-plays loot money (an optimistic play at the click plus this watcher); benilla
+//! keeps the single watcher-driven play — one clean coin on the confirmed change, imperceptibly
+//! latent on localhost.
 
 use bevy::prelude::*;
 
@@ -24,8 +25,8 @@ use benilla_assets::WorldAssets;
 use super::kit::{self, KitRef, SoundKits};
 use super::{SoundConfig, SoundOutput};
 
-/// The SoundEntries name the client plays on any coinage change (kit 895; wow-re
-/// `acquire-spend-sounds.md`). Played by name through the same registry as every interface sound.
+/// The SoundEntries name the client plays on any coinage change (kit 895; `0x5ddf30`). Played by
+/// name through the same registry as every interface sound.
 const COIN_SOUND: &str = "LOOTWINDOWCOINSOUND";
 
 /// Play the coin whenever the self-player's `PLAYER_FIELD_COINAGE` changes. The previous value is a
diff --git a/crates/benilla-app/src/sound/mount.rs b/crates/benilla-app/src/sound/mount.rs
index 8bb63fe9..ef226172 100644
--- a/crates/benilla-app/src/sound/mount.rs
+++ b/crates/benilla-app/src/sound/mount.rs
@@ -1,5 +1,5 @@
 //! The dismount sound — the ONE genuine mount-transition sound the client plays (decision 0441
-//! fold-back; byte-verified wow-re `mount-composition.md` Q4): the dismount handler `0x607ce0`
+//! fold-back): the dismount handler `0x607ce0`
 //! unconditionally tail-plays a FIXED global SoundEntries kit, resolved once at startup by
 //! name-match — `"SpiritWolf_DONOTRENAME"` (`0x623110` → `0x8627bc`) — positioned at the
 //! dismounting unit. It is NOT CreatureSoundData: no mount/dismount column exists, and the
@@ -21,8 +21,8 @@ use super::{AudioListener, SoundConfig, SoundOutput};
 /// startup by name-match — the kit predates mounts as a spirit-wolf sound, hence the odd name;
 /// the mechanism is byte-verified, its in-game character is the director's to judge on a live
 /// dismount). This literal is the 5875 DBC's exact `Name` column value (one row, extracted
-/// through the patch chain this session); the wow-re report transcribed the client's constant
-/// as `SpiritWolf_DONOTRENAME` — a transcription-level difference, the row is unambiguous.
+/// through the patch chain this session), and the client's constant at `0x8627bc` reads the same;
+/// `SpiritWolf_DONOTRENAME` is a transcription-level difference, the row is unambiguous.
 const DISMOUNT_KIT: &str = "SpiritWolf (DONOTRENAME)";
 
 /// Play the fixed dismount kit on a live mounted→unmounted transition of any streamed unit —
diff --git a/crates/benilla-app/src/sound/net.rs b/crates/benilla-app/src/sound/net.rs
new file mode 100644
index 00000000..1df4a2f5
--- /dev/null
+++ b/crates/benilla-app/src/sound/net.rs
@@ -0,0 +1,64 @@
+//! The sound layer's packet handlers (in the net handler table since 2325, moved out of the
+//! drain's world arm file) — the three ambient audio triggers, each a [`ServerSoundMessage`] the
+//! zone mixer ([`super::zone`]) plays.
+
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use crate::net::{GuidIndex, NetHandlerApp, ServerSoundKind, ServerSoundMessage};
+
+/// Register the handlers — called from [`super::SoundPlugin`].
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::PlaySound, on_play)
+        .net_handler(K::PlayMusic, on_play)
+        .net_handler(K::PlayObjectSound, on_play);
+}
+
+fn on_play(
+    In(ev): In<SessionEvent>,
+    index: Res<GuidIndex>,
+    mut out: MessageWriter<ServerSoundMessage>,
+) {
+    match ev {
+        SessionEvent::PlaySound { sound_id } => play_sound(sound_id, &mut out),
+        SessionEvent::PlayMusic { music_id } => play_music(music_id, &mut out),
+        SessionEvent::PlayObjectSound { sound_id, guid } => {
+            play_object_sound(sound_id, guid, &index, &mut out)
+        }
+        _ => {}
+    }
+}
+
+/// `SMSG_PLAY_SOUND` — a 2D (non-positional) one-shot.
+fn play_sound(sound_id: u32, out: &mut MessageWriter<ServerSoundMessage>) {
+    out.write(ServerSoundMessage {
+        kind: ServerSoundKind::Sound2d,
+        sound_id,
+        source: None,
+    });
+}
+
+/// `SMSG_PLAY_MUSIC` — the zone/event music track.
+fn play_music(music_id: u32, out: &mut MessageWriter<ServerSoundMessage>) {
+    out.write(ServerSoundMessage {
+        kind: ServerSoundKind::Music,
+        sound_id: music_id,
+        source: None,
+    });
+}
+
+/// `SMSG_PLAY_OBJECT_SOUND` — a one-shot anchored to a streamed object (silent while its guid
+/// isn't streamed in: the mixer has nowhere to place it).
+fn play_object_sound(
+    sound_id: u32,
+    guid: u64,
+    index: &GuidIndex,
+    out: &mut MessageWriter<ServerSoundMessage>,
+) {
+    out.write(ServerSoundMessage {
+        kind: ServerSoundKind::ObjectSound,
+        sound_id,
+        source: index.0.get(&guid).copied(),
+    });
+}
diff --git a/crates/benilla-app/src/sound/output/mod.rs b/crates/benilla-app/src/sound/output/mod.rs
index db7be143..90c4f302 100644
--- a/crates/benilla-app/src/sound/output/mod.rs
+++ b/crates/benilla-app/src/sound/output/mod.rs
@@ -801,7 +801,7 @@ mod tests {
     /// and nothing above it is, so a failure names the platform file and nothing else.
     ///
     /// It is the whole verification story off macOS, where the gates never compile this code at
-    /// all: `scripts/crosscheck.sh` type-checks Linux and Windows, and this runs the result.
+    /// all: a cross-platform compile type-checks Linux and Windows, and this runs the result.
     ///
     ///     WOW_AUDIO_LIVE=1 cargo test -p benilla-app --lib sound::output:: -- --nocapture
     ///
diff --git a/crates/benilla-app/src/sound/probe.rs b/crates/benilla-app/src/sound/probe.rs
index 0a2ea157..1c968dfc 100644
--- a/crates/benilla-app/src/sound/probe.rs
+++ b/crates/benilla-app/src/sound/probe.rs
@@ -1,4 +1,6 @@
 //! **Measuring mode** — `$WOW_SOUND_PROBE`: record a session so a sound report becomes evidence.
+//! `scripts/soundprobe.sh` starts the client in it (the `play` profile, with the banner that says
+//! when to press the mark key); `scripts/soundprobe.py` reads the capture back.
 //!
 //! ## Why this exists
 //!
diff --git a/crates/benilla-app/src/sound/reverb.rs b/crates/benilla-app/src/sound/reverb.rs
index af89c71d..5102c2a7 100644
--- a/crates/benilla-app/src/sound/reverb.rs
+++ b/crates/benilla-app/src/sound/reverb.rs
@@ -2,14 +2,14 @@
 //! mixer's reverb send.
 //!
 //! The data chain: [`CurrentArea`] → `AreaTable` cols 5/6 (`SoundProviderPref` /
-//! `...Underwater`, parent-inherited — the client's caller `0x67e7f0` walks the same fallback,
-//! wow-re `reverb-pipeline.md` A2, VERIFIED) → `SoundProviderPreferences.dbc` (the EAX listener
-//! properties, consumed RAW — no clamps on this path, A1) → [`Mixer::set_reverb`]'s Freeverb
-//! projection, applied **instantly** on change (A2). Submerged, the underwater
+//! `...Underwater`, parent-inherited — the client's caller `0x67e7f0` walks the same fallback)
+//! → `SoundProviderPreferences.dbc` (the EAX listener properties, consumed RAW — no clamps on
+//! this path, `0x45a790`) → [`Mixer::set_reverb`]'s Freeverb projection, applied **instantly**
+//! on change (`0x45a720`). Submerged, the underwater
 //! column wins — pref 11 on 568 areas; dry land uses the dry column (8 dungeon floors in 1.12).
 //!
 //! Which sounds the wet signal reaches is **not** this module's business and is not "every 3D
-//! sound": 3D-open (channel flag bit 27, A3) is necessary but not sufficient — the kit's
+//! sound": 3D-open (channel flag bit 27, `0x7a5bf0`) is necessary but not sufficient — the kit's
 //! `SoundEntries.EAXDef` decides, and `0` means a NULL `SoundSamplePreferences` slot and a
 //! permanently dry channel (decision 1155; the gate lives at [`Mixer::play_3d`]). 2D/UI/music/
 //! ambience are structurally dry on top of that. `WMOAreaTable` carries the big interior payload
diff --git a/crates/benilla-app/src/sound/ui.rs b/crates/benilla-app/src/sound/ui.rs
index 36f4fab9..4f721043 100644
--- a/crates/benilla-app/src/sound/ui.rs
+++ b/crates/benilla-app/src/sound/ui.rs
@@ -1,5 +1,5 @@
 //! UI sounds — the app side of the Lua `PlaySound` seam (decision 0070 §4, the one deliberate
-//! UI-crate overlap cut from the sound worktree), plus the **per-item item-gesture sounds**
+//! UI-crate overlap cut when the sound crate was split), plus the **per-item item-gesture sounds**
 //! (decision 0091): the bag-drag pickup/put-down, and the loot-window pickup.
 //!
 //! Three triggers, all 2D SFX plays, all after the UI input pass so a click's sound plays the
@@ -11,19 +11,19 @@
 //!   from `SetCursorItem 0x494c4a`/`ClearCursor 0x49520a`, engine-side — never FrameXML):
 //!   [`play_item_gesture_sounds`] watches [`UiScript::cursor_payload`] (decision 0216's typed
 //!   `CursorPayload`, any arm) each frame. An **Item** arm resolves its kit through the
-//!   byte-verified chain `ItemGroupSounds[ItemDisplayInfo[displayId].group_sounds].kit[gesture]`
-//!   ([`play_item_gesture`]; wow-re `system/sound/scratch/item-pickup-place-sound.md`). A
+//!   chain `ItemGroupSounds[ItemDisplayInfo[displayId].group_sounds].kit[gesture]`
+//!   ([`play_item_gesture`]; `0x457ff0`). A
 //!   **Spell**/**Action** arm (no producer yet — the spellbook/action-bar slices) plays the
 //!   generic `INTERFACESOUND_CURSORGRABOBJECT`/`DROPOBJECT` pair (kits 902/903) instead — 0091's
 //!   crux: the two are mutually exclusive per transition, never both. A bag swap plays ONE sound
 //!   (the held item's put-down): the place branch never calls `SetCursorItem` — the Item→Item hop
-//!   0216 §2 shipped is byte-refuted (decision 0218; wow-re cursor-dragdrop-slots.md), so that
+//!   0216 §2 shipped is byte-refuted (decision 0218; `0x5e0c40`), so that
 //!   transition no longer occurs. The Some→Some loss-then-gain pair below stays live for the
 //!   ACTION hop (the bar is client-authoritative and its displaced action DOES land on the
 //!   cursor, verified at `PlaceAction 0x4e62e0`) when the action-bar slice arrives.
 //! - Taking a loot-window row plays that item's **pickup** kit (gesture 0) — the same per-item
 //!   resolution, fired at the loot-slot click before the CMSG send (the real client's loot-list
-//!   pickup site, wow-re `system/sound/scratch/acquire-spend-sounds.md`). [`crate::ui_loot`] emits
+//!   pickup site, `0x4c2790`). [`crate::ui_loot`] emits
 //!   a [`LootPickupSound`] with the row's display id; [`play_loot_pickup_sounds`] plays it. (The
 //!   loot *money* coin and the buy/sell coin are the coinage-change watcher instead — [`super::money`]
 //!   — because acquiring an item on loot is the only one of the four that plays a per-item sound.)
@@ -123,10 +123,9 @@ fn load_item_sounds(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
 }
 
 /// `INTERFACESOUND_CURSORGRABOBJECT`/`DROPOBJECT` — the generic non-item cursor-payload gesture
-/// pair (sound-kit ids, not `SOUNDKIT.xml` names; VERIFIED wow-re
-/// `system/sound/scratch/item-pickup-place-sound.md`, 0091's crux). Plays for a Spell/Action
-/// payload transition (decision 0216) — an Item transition always plays its own per-item kit
-/// instead, never this pair.
+/// pair (sound-kit ids, not `SOUNDKIT.xml` names; `0x495190`, 0091's crux). Plays for a
+/// Spell/Action payload transition (decision 0216) — an Item transition always plays its own
+/// per-item kit instead, never this pair.
 const INTERFACESOUND_CURSORGRABOBJECT: u32 = 902;
 /// `LOOTWINDOWCOINSOUND` — SoundEntries kit 895, the coin clink the money pickup names (1962).
 const LOOTWINDOWCOINSOUND: u32 = 895;
@@ -218,7 +217,7 @@ fn play_item_gesture_sounds(
         // Everything that is not a live item shares the generic grab/drop kit — the reference's
         // own `0x494f60`/`0x494f80` grab path for a macro (mode 8) reaches the same
         // `INTERFACESOUND_CURSOR*` pair the spell and bar-action modes do, and the pet-action
-        // builder `0x494e20` names `INTERFACESOUND_CURSORGRABOBJECT` outright (wow-re §10.3).
+        // builder `0x494e20` names `INTERFACESOUND_CURSORGRABOBJECT` outright.
         CursorPayload::Spell(_)
         | CursorPayload::Action(_)
         | CursorPayload::Macro(_)
@@ -228,7 +227,7 @@ fn play_item_gesture_sounds(
         | CursorPayload::StablePet(_)
         // Mode 2 (1962, 1965): the money pickup AND drop both play `LOOTWINDOWCOINSOUND` — the
         // same kit 895 the purse plays on a change (`sound/money.rs`) — and never the generic drop
-        // kit (wow-re `money-cursor-law.md` §2).
+        // kit (`0x494cfe`/`0x49523a`).
         | CursorPayload::Money(_) => {
             let kit_id = match (&payload, gesture) {
                 (CursorPayload::Money(_), _) => LOOTWINDOWCOINSOUND,
@@ -300,7 +299,7 @@ fn play_item_gesture(
 /// Request to play an item's **loot pickup** sound — written by [`crate::ui_loot::drain_loot`] when
 /// the player takes a loot-window row (carrying that row's display id). The real client plays the
 /// per-item `ItemGroupSounds` **pickup** kit (gesture 0) client-side at the loot-slot click, before
-/// the CMSG send (wow-re `system/sound/scratch/acquire-spend-sounds.md`): looting an item plays its
+/// the CMSG send (`0x4c2790`): looting an item plays its
 /// pickup sound, while the `SMSG_ITEM_PUSH` acquire itself is silent — so buying, which also pushes
 /// an item, plays no pickup sound (only the coin, via [`super::money`]).
 #[derive(Message, Clone, Copy)]
@@ -345,8 +344,8 @@ fn play_loot_pickup_sounds(
 /// Request to play the **auto-equip** gesture pair for an item — written by [`crate::ui_items`]
 /// when a right-click auto-equips a bag item (the `CMSG_AUTOEQUIP_ITEM` fork of `UseContainerItem`).
 /// The real client implements the right-click shortcut as a *synthetic* `SetCursorItem` →
-/// `ClearCursor` (wow-re `system/sound/scratch/auto-equip-sound.md`, byte-traced through
-/// `Script::UseContainerItem 0x4fa0e0` → the pickup play at `0x494c4a` then the place play at
+/// `ClearCursor` (`Script::UseContainerItem 0x4fa0e0` → the pickup play at `0x494c4a` then the
+/// place play at
 /// `0x49520a`), so it plays the item's `ItemGroupSounds` **pickup** kit[0] THEN its **place**
 /// kit[1] — the same two sounds a drag-equip makes. A drag *already* plays them via the
 /// cursor-payload transitions ([`play_item_gesture_sounds`]); the right-click path never touches
diff --git a/crates/benilla-app/src/sound/water.rs b/crates/benilla-app/src/sound/water.rs
index b5702b2a..48a6c2b3 100644
--- a/crates/benilla-app/src/sound/water.rs
+++ b/crates/benilla-app/src/sound/water.rs
@@ -1,9 +1,8 @@
 //! Water audio (decision 0070 slice 4): the water splash. (The wading **footstep** splash
 //! lives in [`super::footsteps`]; the submerged ambience swap lives in [`super::zone`] — the
-//! client swaps the one background-ambience slot to the underwater loop, B6.)
+//! client swaps the one background-ambience slot to the underwater loop, `0x460af0`.)
 //!
-//! **The splash trigger is a symmetric depth edge** — VERIFIED (the swim §5's TU-D, wow-re
-//! `swim-mechanism.md`, resolving benilla-pins B7/B8's trigger half): a dedicated detector inside
+//! **The splash trigger is a symmetric depth edge**: a dedicated detector inside
 //! the per-frame water decision `0x6030c0` (`0x60314a`) compares `depth = surface − feet` against
 //! **`0.4·collisionHeight`** and fires a positioned unit sound on crossing in **either direction**
 //! — entering fires it, and so does surfacing back past the line (exit is NOT silent). It is
@@ -11,7 +10,7 @@
 //! mode starts. Walking the shallows below the line makes only per-step wading splashes
 //! (director-verified against the ref, 2026-07-03).
 //!
-//! What stays INTERIM (same dispatch, still open): the **size class** — the client routes the
+//! What stays INTERIM (still open): the **size class** — the client routes the
 //! play through the unit's own sound emitter (`[CGUnit+0xb18]`) where Small/Medium/Large
 //! resolves; that selector is not pinned, so kit 1096 Medium plays for everyone. The per-unit
 //! **collision height** the line scales by is no longer interim: 0464's named
diff --git a/crates/benilla-app/src/sound/weather.rs b/crates/benilla-app/src/sound/weather.rs
index df543f46..26967e76 100644
--- a/crates/benilla-app/src/sound/weather.rs
+++ b/crates/benilla-app/src/sound/weather.rs
@@ -4,10 +4,9 @@
 //! runs ONE ambience channel: its selector (`0x460bd0`) returns the raw weather SoundEntries while
 //! the **zonetext indoor bit is clear**, and the area's own `AmbienceID` row while it is set — the
 //! keep-flag `[0xb06d44]`, written `dl=1` by the indoor area feeder (`0x67e7d4`) and `dl=0` by the
-//! outdoor one (`0x67e919`); every swap rides the standard **5.0 s crossfade** (wow-re
-//! `rf-weather-emission-timeline` ROUND 5, Q-C). That content REPLACE — never a volume duck — is
-//! why rain goes quiet inside the Goldshire inn. The packet's `grade` drives **rendering only**
-//! (wow-re `benilla-pins.md` B9: grade never reaches a volume call).
+//! outdoor one (`0x67e919`); every swap rides the standard **5.0 s crossfade** (`0x460b00`). That
+//! content REPLACE — never a volume duck — is why rain goes quiet inside the Goldshire inn. The
+//! packet's `grade` drives **rendering only** (`0x67baf0`: grade never reaches a volume call).
 //!
 //! This module only publishes the current wire kit ([`WeatherAmbience`]); the channel — selection,
 //! crossfades, volumes — is `super::zone`'s ambience machine, the benilla twin of `0x460b00`.
diff --git a/crates/benilla-app/src/sound/zone.rs b/crates/benilla-app/src/sound/zone.rs
index 79d5e1e8..d3e9a05e 100644
--- a/crates/benilla-app/src/sound/zone.rs
+++ b/crates/benilla-app/src/sound/zone.rs
@@ -4,7 +4,7 @@
 //! `ZoneMusic`/`SoundAmbience`/`ZoneIntroMusicTable` (parent-inherited, `benilla_formats::
 //! AreaSoundCatalog::resolve`) → SoundEntries kits → streamed MP3/WAV.
 //!
-//! **Music transport** (wow-re `0x460040`–`0x460ca0`, `benilla-pins.md` **B15/B16**). Within one
+//! **Music transport** (`0x460040`–`0x460ca0`). Within one
 //! zone, tracks are separated by a uniform random **silence interval** per day/night phase. On a
 //! zone-music-id CHANGE the outgoing track fades to silence over **4.0 s** then stops (byte-exact:
 //! `0x4602e0` → `0x7a5a10(0x40800000 = 4.0f)`) and the incoming track starts **immediately** — the
@@ -16,12 +16,13 @@
 //! `DAT_00836400 = -1` at `0x45ffdb`), so the session's FIRST track is immediate too. `0x4601f0`'s
 //! `== 0 → now + 6000 ms` branch is reachable only from the natural-end reap `0x4600b6` and only
 //! ever *replaces* the −1, so it cannot fire on an entry — the 6 s wait benilla used to serve there
-//! was that branch misapplied (wow-re §5 `glue-music-world-entry.md` §9, decision 1553). The incoming track starts at **full** volume, **no fade-in** — faithful (`0x460240` →
-//! `0x7a5dc0`; §5 B16 refuted every music-slot fade-in primitive, and the director confirmed by ear
-//! there is none). The reference's *perceived* slightly-soft onset is the delegated audio engine
-//! priming the stream to full amplitude over ~a moment (FMOD there, kira's own stream-buffering
-//! here), which leaves the 4.0 s fade audible — NOT owned gain math, flagged in wow-re for a live
-//! capture if benilla's onset reads too abrupt. (The transition is **not** `0x457960` — that is the
+//! was that branch misapplied (decision 1553). The incoming track starts at **full** volume,
+//! **no fade-in** — faithful (`0x460240` → `0x7a5dc0`; neither fade-in primitive, `0x7a57b0` or
+//! `0x7a5730`, is ever called on a music slot, and the director confirmed by ear there is none).
+//! The reference's *perceived* slightly-soft onset is the delegated audio engine priming the
+//! stream to full amplitude over ~a moment (FMOD there, kira's own stream-buffering here), which
+//! leaves the 4.0 s fade audible — NOT owned gain math, open for a live capture of the reference
+//! if benilla's onset reads too abrupt. (The transition is **not** `0x457960` — that is the
 //! SFX-bus auto-duck, decision 0100.) Intro music (`ZoneIntroMusicTable`) plays at full on zone
 //! entry, throttled by its per-entry minute delay;
 //! higher `Priority` wins when nested areas compete (we resolve one row).
@@ -40,18 +41,18 @@
 //! → return); when the track *does* end, the next push restarts it, which is what makes the loop.
 //! Any other push takes the slot the way a zone-music change does (outgoing 4.0 s fade, incoming at
 //! full) — inferred from the slot's one transition idiom, as the `SMSG_PLAY_MUSIC` handler itself
-//! is not pinned in wow-re.
+//! is not traced in the binary.
 //!
-//! **Ambience transport** (`0x460b00`, the separate ambience updater; §5 B16). An area / interior /
+//! **Ambience transport** (`0x460b00`, the separate ambience updater). An area / interior /
 //! day↔night / ghost ambience-id change is a **5.0 s crossfade**: the old bed fades out over 5.0 s
 //! then stops (`0x7a5a10(0x40a00000 = 5.0f)`) while the new bed starts at volume 0 and fades in over
 //! 5.0 s (`0x7a5dc0(0)` → `0x7a57b0(5.0f, kit vol)`). The **submerge/emerge** swap is the exception:
 //! it takes `0x460b00`'s **instant** no-fade branch (`0x458650` → `0x460af0(param = 1)`) — correcting
-//! both the old "250 ms area swap" INTERIM and B6's "5 s underwater fade".
+//! the old "250 ms area swap" INTERIM.
 //!
 //! The day/night boundary is the server-synced game clock's hard step — **day iff
 //! 05:30 ≤ t < 21:00** (minutes 330..1259), re-evaluated per tick, no fade (`0x4578c0` via the
-//! `0x642710` range check; wow-re `benilla-pins.md` B4, VERIFIED).
+//! `0x642710` range check).
 
 use bevy::prelude::*;
 
@@ -77,7 +78,7 @@ pub(crate) struct AreaSounds(pub(crate) AreaSoundCatalog);
 #[derive(Resource)]
 pub(crate) struct ExplorationSounds(pub(crate) benilla_formats::ExplorationSoundCatalog);
 
-/// Day iff 05:30 ≤ clock < 21:00 (module docs — the client's hard step, B4-verified).
+/// Day iff 05:30 ≤ clock < 21:00 (module docs — the client's hard step, `0x4578c0`).
 /// Index into the `[day, night]` DBC pairs.
 /// How long after a cinematic ends before the zone track comes back — the reference's
 /// `[0x836400] = tick + 0xbb8` at `0x4603b0(0)`, i.e. **3.000 s**. Its own number: not the `-1`
@@ -93,27 +94,48 @@ fn phase(clock: &GameClock) -> usize {
 }
 
 /// SoundEntries 4123 `UnderWaterLoop` — the submerged ambience bed the client swaps the
-/// ambience slot to (the swap is instant on submerge/emerge — §5 B16).
+/// ambience slot to (the swap is instant on submerge/emerge — `0x458650` → `0x460af0`).
 const UNDERWATER_LOOP_KIT: u32 = 4123;
 
 /// The zone-music transition fade: on a zone-music-id change the outgoing track fades linearly to
-/// silence over 4.0 s then stops, byte-exact (`0x4602e0` → `0x7a5a10(0x40800000 = 4.0f)`; wow-re §5
-/// **B16**, decision 0100). Both directions. The incoming track starts immediately at FULL volume —
-/// the client has no music fade-in (§5 B16, director-confirmed by ear), so this is the only fade on
-/// the music slot. It rides the backend fade-stop — drop the handle, the ramp finishes on kira's
-/// thread (verified device-free by `mixer::tests::stop_fade_ramps_after_handle_drop`).
+/// silence over 4.0 s then stops, byte-exact (`0x4602e0` → `0x7a5a10(0x40800000 = 4.0f)`;
+/// decision 0100). Both directions. The incoming track starts immediately at FULL volume — the
+/// client has no music fade-in (`0x460240` → `0x7a5dc0`, director-confirmed by ear), so this is
+/// the only fade on the music slot. It rides the backend fade-stop — drop the handle, the ramp
+/// finishes on kira's thread (verified device-free by
+/// `mixer::tests::stop_fade_ramps_after_handle_drop`).
 const MUSIC_FADE_OUT_MS: u64 = 4000;
 
+/// The Lua `PlayMusic` slot's own base volume: **1.0**, set instantly. `0x460450` puts it through
+/// `0x7a5dc0` with no fade and at 1.0f — where the glue theme uses 0.8f (`0x45aeb0`) — as a plain
+/// scalar under the MusicVolume slider, exactly like a kit's volume, so the slider still rescales
+/// it live.
+const LUA_MUSIC_VOLUME: f32 = 1.0;
+
+/// What **either** Lua music verb leaves on the zone pump's clock: **now + 6.000 s**
+/// (`0x46049b`, `[0x836400] = 0x42c010() + 0x1770`).
+///
+/// A fourth number beside the three the zone slot already has, and the only one written by a verb
+/// rather than by the soundscape: not the `-1` "start now" a zone change and a world entry arm,
+/// not the cinematic's 3.000 s ([`CINEMATIC_MUSIC_RESUME_SECS`]), and not `0x4601f0`'s randomized
+/// `SilenceInterval` (whose only caller is the natural-end reap, unreachable from here).
+///
+/// **Unconditional, on both verbs, even from cold** — the write sits between `0x460499`'s
+/// `test esi,esi` and its `je`, ahead of the NULL branch — so `StopMusic()` with nothing playing
+/// still moves the pump's next start, and can push out a deadline that was already due. That is
+/// the side effect a re-implementation drops, and it is why it has a name here.
+const LUA_MUSIC_SCHEDULE_SECS: f64 = 6.0;
+
 /// The zone-ambience crossfade: **5.0 s** for an area / interior / day↔night / ghost swap —
 /// `0x460b00` fades the old bed out over 5.0 s (`0x7a5a10(0x40a00000 = 5.0f)`) and fades the new
-/// bed in from silence over the same 5.0 s (`0x7a5dc0(0)` → `0x7a57b0(5.0f, kit vol)`). Byte-exact
-/// (wow-re §5 B16). The submerge/emerge swap is NOT this — it is instant (see the reconcile).
+/// bed in from silence over the same 5.0 s (`0x7a5dc0(0)` → `0x7a57b0(5.0f, kit vol)`). Byte-exact.
+/// The submerge/emerge swap is NOT this — it is instant (see the reconcile).
 const AMBIENCE_TRANSITION_FADE_MS: u64 = 5000;
 
 /// A linear fade-in envelope for a freshly-started ambience bed: gain ramps 0→1 over `dur_secs`
 /// from `start_secs` (`Time::elapsed_secs_f64`). benilla drives the incoming leg of the ambience
 /// crossfade itself, per frame — the per-frame volume sync would otherwise snap the new bed
-/// straight to full. (Music has no fade-in — §5 B16 — so only ambience uses this.)
+/// straight to full. (Music has no fade-in — `0x460240` → `0x7a5dc0` — so only ambience uses this.)
 #[derive(Clone, Copy)]
 struct FadeIn {
     start: f64,
@@ -166,6 +188,21 @@ pub(super) struct ZoneAudio {
     music_kit: u32,
     /// The playing track's kit base volume (multiplied under the category slider + fade).
     music_kit_vol: f32,
+    /// **The Lua `PlayMusic` slot** — the reference's `[0xb06ccc]`, a *second* music stream beside
+    /// the zone track's `[0xb06cc4]` (`0x460450` opens it at `0x4604a7`, stores the handle at
+    /// `0x4604b8`), driven by the `PlayMusic`/`StopMusic` pair and nothing else. Held rather than
+    /// dropped: a dropped kira handle keeps playing, and the loop below has to be able to see it.
+    lua_music: Option<StreamingSoundHandle<kira::sound::FromFileError>>,
+    /// The file on that slot, kept because the stream **loops forever**: the reference opens it
+    /// through `0x7a5620`'s `a1 != 1` arm, whose `SetLoopCount(-1)` (`0x7a5592`, one call site
+    /// image-wide) makes this and the glue theme the client's only two infinite streams. kira
+    /// cannot loop a decode-stream (`mixer::loop_from_bytes` docs: an mp3's *estimated* duration
+    /// puts `loop_region` past EOF and the stream dies mid-file), so the loop is a restart at the
+    /// natural end — the same shape [`super::glue`] gives the theme.
+    lua_music_path: Option<String>,
+    /// Starvation watch over that slot (decision 1109), like the zone track's — it is a streamed
+    /// track of exactly the same class, and an addon's music is the one nothing else reports on.
+    lua_music_watch: mixer::StreamWatch,
     /// When the next zone track starts (Time::elapsed_secs_f64; None = a track is playing or
     /// no music in this zone).
     next_track_at: Option<f64>,
@@ -185,7 +222,7 @@ pub(super) struct ZoneAudio {
     /// The last WMO interior acted on (change detection — the override layer, decision 0076).
     interior: Option<super::interior::InteriorAudio>,
     /// Last submersion state — a flip makes the ambience swap INSTANT (the underwater no-fade
-    /// branch, wow-re §5 B16), vs the 5.0 s crossfade every other swap gets.
+    /// branch, `0x458650` → `0x460af0`), vs the 5.0 s crossfade every other swap gets.
     was_underwater: bool,
     rng: u32,
 }
@@ -198,6 +235,9 @@ impl Default for ZoneAudio {
             music_watch: mixer::StreamWatch::new("zone music"),
             music_kit: 0,
             music_kit_vol: 1.0,
+            lua_music: None,
+            lua_music_path: None,
+            lua_music_watch: mixer::StreamWatch::new("Lua music"),
             next_track_at: None,
             music_suppressed: false,
             ambience_kit: 0,
@@ -223,6 +263,14 @@ impl ZoneAudio {
         x
     }
 
+    /// Whether a **Lua `PlayMusic` track is on the override slot** — the reference's
+    /// `mov ecx,[0xb06ccc]; test` (`0x4603d6`), asked of the slot's *record* rather than of the
+    /// live handle so it is also true across the restart gap between a stream's natural end and
+    /// its reopen: that gap is still the caller's track.
+    fn lua_slot_live(&self) -> bool {
+        self.lua_music_path.is_some()
+    }
+
     /// Uniform silence interval (ms) in `[min, max]` for the phase.
     fn silence_ms(&mut self, min: u32, max: u32) -> u32 {
         if max > min {
@@ -290,7 +338,7 @@ fn zone_audio(
     let phase = phase(&clock);
     let zone = &mut *zone;
 
-    // ---- the cinematic's music stop (wow-re `sound/scratch/cinematic-audio-law.md`, VERIFIED) ----
+    // ---- the cinematic's music stop ----
     // The flag itself is [`SoundConfig::music_suppressed`], whose doc carries the mechanism. Here
     // are its two edges, and both are byte-shaped rather than chosen:
     //
@@ -395,8 +443,8 @@ fn zone_audio(
     // ---- ambience reconciliation. The desired-bed priority is the client's own selector
     // (`FUN_00460bd0`, byte-verified): GHOST > submerged > weather-gated zone day/night. The
     // ghost bed is the named "Ghost" SoundEntries kit, resolved through the name registry like
-    // the client's literal; its enter/leave swap rides the standard 5.0 s crossfade (the ghost
-    // row of the trigger table — zone-music-ambience-transition.md). ----
+    // the client's literal; its enter/leave swap rides the standard 5.0 s crossfade (`0x458680` →
+    // `0x460c20`). ----
     let ghost = self_store
         .single()
         .is_ok_and(|store| store.0.player_is_ghost());
@@ -405,8 +453,8 @@ fn zone_audio(
     } else if world.submersion().is_water() {
         UNDERWATER_LOOP_KIT
     } else if weather.0 != 0 && world.area_interior().is_none() {
-        // The selector's weather branch (`0x460bd0`, 0x460bf7–0x460c17; wow-re
-        // `rf-weather-emission-timeline` ROUND 5 Q-C): while the **zonetext indoor bit** is clear
+        // The selector's weather branch (`0x460bd0`, 0x460bf7–0x460c17): while the
+        // **zonetext indoor bit** is clear
         // (the keep-flag `[0xb06d44]`, dl=0 from the outdoor area feeder) the raw weather
         // SoundEntries IS the ambience bed; the indoor feeder (dl=1) makes the selector ignore
         // the weather id entirely — the area/interior row below plays instead. Both directions
@@ -428,9 +476,8 @@ fn zone_audio(
     };
     if desired != zone.ambience_kit {
         // The submerge/emerge swap is INSTANT — the underwater caller takes `0x460b00`'s no-fade
-        // branch (`0x458650` → `0x460af0(param=1)`, wow-re §5 B16, correcting the old "5 s
-        // underwater" of B6). Every other ambience swap — interior, area, day↔night — is the one
-        // 5.0 s crossfade (`0x460b00`'s fade branch).
+        // branch (`0x458650` → `0x460af0(param=1)`). Every other ambience swap — interior, area,
+        // day↔night — is the one 5.0 s crossfade (`0x460b00`'s fade branch).
         let fade_ms = if world.submersion().is_water() != zone.was_underwater {
             0
         } else {
@@ -452,10 +499,17 @@ fn zone_audio(
                 next_track_time(zone, &areas.0, zm, phase, now, config.zone_music_no_delay);
         }
     }
-    // Silence elapsed → start the next track (same-zone cycle, the cold-start first track, or the
-    // 3.0 s resume after a cinematic). The pump is dead while suppressed, which is the reference's
-    // own shape — `0x460040` bails at its first instruction on the flag, so no track is selected,
-    // opened or scheduled for the duration.
+    // Silence elapsed → start the next track (same-zone cycle, the cold-start first track, the
+    // 3.0 s resume after a cinematic, or the 6.0 s one a Lua music verb left). The pump is dead
+    // while suppressed, which is the reference's own shape — `0x460040` bails at its first
+    // instruction on the flag, so no track is selected, opened or scheduled for the duration.
+    //
+    // It bails at its SECOND test on a live Lua override slot (`0x460057`), i.e. without reading
+    // the deadline at all, where this block reads it, clears it and is then refused at the slot
+    // by [`start_music_stream`]. The audible outcome is the same and cannot come apart, because
+    // the only thing that ends an override is the verb itself and the verb always rewrites the
+    // deadline on its way through ([`LUA_MUSIC_SCHEDULE_SECS`]): whatever this block consumed
+    // meanwhile, zone music comes back 6.0 s after the `StopMusic`.
     if zone.next_track_at.is_some_and(|t| now >= t) && zone.music.is_none() {
         zone.next_track_at = None;
         if let Some(m) = zone_music_row(&areas.0, zone.zone_music) {
@@ -506,6 +560,24 @@ fn apply_music_suppression(zone: &mut ZoneAudio, suppressed: bool, now: f64) {
         return;
     }
     zone.music_suppressed = suppressed;
+    // **A live Lua `PlayMusic` track is PAUSED and RESUMED, and nothing else happens on either
+    // edge.** `0x4603b0` writes the disabled flag first (`0x4603ba`, so the pump dies here too),
+    // then reads the Lua slot at `0x4603d6` and — finding it live — hands the stream `0x7a5ac0`
+    // with that same flag and **returns** (`0x4603e0`): the zone stream is not stopped, the intro
+    // layer is not killed, and `[0x836400]` is never rearmed, on the way in or out. A cinematic
+    // borrows the caller's track; it does not take it.
+    if zone.lua_slot_live() {
+        if let Some(h) = zone.lua_music.as_mut() {
+            if suppressed {
+                h.pause(mixer::declick());
+                info!("Lua music: paused for a cinematic");
+            } else {
+                h.resume(mixer::declick());
+                info!("Lua music: resumed");
+            }
+        }
+        return;
+    }
     if suppressed {
         if let Some(mut h) = zone.music.take() {
             h.stop(mixer::fade(0));
@@ -537,8 +609,7 @@ fn zone_music_row(cat: &AreaSoundCatalog, _id: u32) -> Option<&benilla_formats::
 /// label (*Loop Music*) suggests: it deletes the randomised `ZoneMusic.dbc` SilenceIntervalMin/Max
 /// wait between successive plays of the SAME zone's track. A zone CHANGE is immediate either way —
 /// the incoming track starts on the next tick while the outgoing fades over 4 s, an overlap rather
-/// than a gap (wow-re `zone-music-ambience-transition.md` Q1/Q2, which corrects an earlier framing
-/// of exactly this).
+/// than a gap (`0x4602e0` arms the −1 "start now" at `0x460346`).
 ///
 /// **Not a cold start** — `0x4601f0`'s `== 0 → now + 6000 ms` arm needs a *cleared* currently-playing
 /// row, which end-of-track flow never presents, and an entry never reaches this function at all
@@ -577,8 +648,8 @@ fn slot_holds(music_kit: u32, kit_id: u32, slot: Option<kira::sound::PlaybackSta
 
 /// Open a music kit as a stream on the music slot (a zone track, an intro, or a server-pushed
 /// track), replacing whatever is on it. The stream starts at **full** kit × category volume for
-/// every start — the client has no music fade-in (§5 B16); the slot's only fade is the outgoing
-/// 4.0 s fade-stop. Returns whether a stream actually started.
+/// every start — the client has no music fade-in (`0x460240` → `0x7a5dc0`); the slot's only fade
+/// is the outgoing 4.0 s fade-stop. Returns whether a stream actually started.
 fn start_music_stream(
     zone: &mut ZoneAudio,
     out: &mut SoundOutput,
@@ -600,6 +671,19 @@ fn start_music_stream(
     if config.music_suppressed {
         return false;
     }
+    // **And nothing opens it while a Lua `PlayMusic` track holds the override slot** — the
+    // reference gates on the slot ITSELF, not on a schedule, in five separate places: the pump's
+    // own second test (`0x460050 mov eax,[0xb06ccc]; test eax,eax; jne 0x4600f8`), the
+    // zone-music change `0x4602e0`, the music-enable toggle `0x460420`, the play-by-id
+    // `0x460520` (which is where a server push lands there) and `0x4603b0`'s pause leg. Five
+    // gates on one condition is the same argument the cinematic gate above makes: the refusal
+    // belongs at the slot, whatever asked for it — and here that covers all four of this
+    // function's callers, the zone change, the intro fanfare, the silence-timer pump and
+    // `SMSG_PLAY_MUSIC`. With loop count `-1` the override is indefinite: it ends when the
+    // caller ends it.
+    if zone.lua_slot_live() {
+        return false;
+    }
     let Some(mixer_ref) = out.mixer.as_mut() else {
         return false;
     };
@@ -639,7 +723,156 @@ fn start_music_stream(
     }
 }
 
-/// Crossfade the looping ambience bed to a new kit (0 = stop), over `fade_ms`: the old bed fades
+/// **The Lua music verb — `PlayMusic(name)` and `StopMusic()` are ONE function with one branch.**
+///
+/// `StopMusic 0x458770` is four instructions, three of which are `0x460450(NULL)` — the very
+/// function `PlayMusic 0x458720` calls. So *stopping is playing a NULL name*, and this is that
+/// function (B391; `0x460450` has two callers image-wide and no address-takes, so nothing else
+/// in the client can start or stop this slot). The order below is its order:
+///
+/// 1. **[`take_lua_music_slot`]** — the shared head, which is also the whole of the NULL arm.
+/// 2. `0x4604a0` — the branch. A stop is done; everything after this is the name arm.
+/// 3. **[`open_lua_music`]** — the stream, looping, at full volume.
+/// 4. `0x4604d4`–`0x4604e8` — **if the stream opened**, the zone track fades out over 4.0 s and
+///    its slot is cleared. The incoming stream is already at full (the client has no music
+///    fade-in), so this is an overlap, not a gap — the same 4.0 s overlap a zone-music change
+///    makes.
+///
+/// **A name that does not resolve stops at step 3**, and that is a confirmed branch rather than a
+/// reading: `0x4604bd je 0x460517` returns the moment `0x7a5620` answers NULL, above the volume
+/// set and everything after it. What makes it look linear from a distance is that the handle
+/// *store* (`0x4604b8`) IS unconditional — it is wedged between `test eax,eax` and that `jcc`. So
+/// a mistyped `PlayMusic` still ends whatever the caller had playing and still pushes the pump out
+/// 6 s, because both of those are in the head; it leaves a live zone track exactly where it was.
+///
+/// `assets`/`path` are both `None` for the NULL arm. A *name* arm the caller cannot serve — no
+/// store, or the loading cover up — is dropped before it gets here ([`lua_music`]), because a
+/// start held behind a cover would arrive in the zone after the one that asked for it.
+fn set_lua_music(
+    zone: &mut ZoneAudio,
+    out: &mut SoundOutput,
+    assets: Option<&WorldAssets>,
+    config: &SoundConfig,
+    path: Option<&str>,
+    now: f64,
+) {
+    take_lua_music_slot(zone, now);
+    let (Some(path), Some(assets)) = (path, assets) else {
+        return;
+    };
+    // Only a stream that actually opened takes the zone track down (`0x4604bd`'s return — the
+    // doc above), and the reference then re-reads its own slot (`0x4604cb`/`0x4604d2`) and the
+    // zone's (`0x4604da`) before the call, which is what this pair of conditions is.
+    if open_lua_music(zone, out, assets, config, path) {
+        // The zone track's own 4.0 s fade-stop — handed to the backend, handle dropped, exactly
+        // as a zone-music change arms it (`0x7a5a10(4.0f)` there and here are the same call).
+        if let Some(mut h) = zone.music.take() {
+            h.stop(mixer::fade(MUSIC_FADE_OUT_MS));
+            info!("zone music: faded out under a Lua PlayMusic");
+        }
+    }
+}
+
+/// `0x460450`'s **shared head**, which is also the whole of its NULL arm: fade this slot's own
+/// stream out over **4.0 s** (`0x460480` — a fade, never the `0x7a5700` hard cut, so a second
+/// `PlayMusic` crossfades), clear the slot (`0x460485`), and rearm the zone pump
+/// ([`LUA_MUSIC_SCHEDULE_SECS`]).
+///
+/// Split out for the reason [`apply_music_suppression`] is: its two numbers are byte-shaped and
+/// this way they can be asserted without standing up a device.
+///
+/// **It does not touch the zone track.** `[0xb06cc4]`'s only mentions in the reference's function
+/// sit *past* the NULL branch, so `StopMusic` ends a `PlayMusic` track and never the zone's own
+/// music.
+fn take_lua_music_slot(zone: &mut ZoneAudio, now: f64) {
+    if let Some(mut h) = zone.lua_music.take() {
+        h.stop(mixer::fade(MUSIC_FADE_OUT_MS));
+        info!("Lua music: stopped");
+    }
+    zone.lua_music_path = None;
+    zone.lua_music_watch.reset();
+    zone.next_track_at = Some(now + LUA_MUSIC_SCHEDULE_SECS);
+}
+
+/// Open a Lua music stream on the override slot — by path, not by kit, and looping.
+///
+/// `0x4604a7`–`0x4604bf`: the stream through `0x7a5620`'s looping arm, the handle stored
+/// unconditionally, volume **1.0f** recorded instantly (an immediate in `.text`, not a `.data`
+/// cell) on the MusicVolume category. Also the **loop**: the reference's `SetLoopCount(-1)` makes
+/// the natural end unreachable, so [`lua_music`] reopens here instead.
+///
+/// **Opened paused under a cinematic.** With music disabled the reference still opens the file,
+/// stores the handle and records the volume — only the deferred `_FSOUND_Stream_PlayEx` is gated
+/// (`0x4604f2`/`0x4604f9`), and the stream starts the moment music comes back, mid-nothing rather
+/// than from the top. A paused stream is that, and the falling edge in
+/// [`apply_music_suppression`] is what resumes it. (The `EnableMusic` CVar's own half of that byte
+/// needs nothing here: benilla zeroes the category instead of pausing the stream, the divergence
+/// [`SoundConfig::music_enabled`] already discloses — and for *this* slot that divergence is the
+/// faithful behaviour, because the reference resumes this very stream too.)
+fn open_lua_music(
+    zone: &mut ZoneAudio,
+    out: &mut SoundOutput,
+    assets: &WorldAssets,
+    config: &SoundConfig,
+    path: &str,
+) -> bool {
+    let Some(mixer_ref) = out.mixer.as_mut() else {
+        return false;
+    };
+    // The chain, then the addon folder — an addon that ships its own track names it by a virtual
+    // `Interface\AddOns\…` path no MPQ carries ([`benilla_assets::read_chain_or_loose`]).
+    let Some(bytes) = assets.read_file_or_loose(path) else {
+        // A file that does not resolve is the client's own silent nothing: the binding has already
+        // returned, so there is nobody left to raise at, and the name went to the file layer
+        // verbatim (no extension appended, no normalisation — `0x458720` does neither).
+        debug!("Lua music: {path} — not in the patch chain or the AddOns folder");
+        return false;
+    };
+    let data = match mixer::stream_from_bytes(bytes) {
+        Ok(d) => d,
+        Err(e) => {
+            debug!("Lua music: {path} — {e:#}");
+            return false;
+        }
+    };
+    let start_amp = config.category_amp(SoundCategory::Music) * LUA_MUSIC_VOLUME;
+    match mixer_ref.play_stream(data.volume(mixer::amp_to_db(start_amp))) {
+        Ok(mut h) => {
+            info!("Lua music: {path}");
+            if config.music_suppressed {
+                h.pause(mixer::fade(0));
+                info!("Lua music: held — a cinematic has music disabled");
+            }
+            // One stream per slot. The verb has already faded the outgoing one, so this only
+            // catches the loop's own reopen — and a dropped kira handle keeps playing, so it can
+            // never just be overwritten.
+            if let Some(mut outgoing) = zone.lua_music.replace(h) {
+                outgoing.stop(mixer::declick());
+            }
+            zone.lua_music_path = Some(path.to_owned());
+            zone.lua_music_watch.reset();
+            true
+        }
+        Err(e) => {
+            warn!("Lua music: {path} — {e:#}");
+            false
+        }
+    }
+}
+
+/// Drop the Lua stream on a **teardown** — the world's audio dying, not the verb. A short declick
+/// rather than the verb's 4.0 s musical fade (the same distinction
+/// [`stop_world_soundscape`] draws for the zone slot), and no schedule rearm: nothing is coming
+/// back. Idempotent.
+fn drop_lua_music(zone: &mut ZoneAudio) {
+    if let Some(mut h) = zone.lua_music.take() {
+        h.stop(mixer::fade(250));
+    }
+    zone.lua_music_path = None;
+    zone.lua_music_watch.reset();
+}
+
+/// Crossfade the looping ambience bed to a new kit (0 = stop), over `fade_ms`:/// Crossfade the looping ambience bed to a new kit (0 = stop), over `fade_ms`: the old bed fades
 /// out on the backend (drop the handle — the ramp finishes on kira's thread) while the new bed
 /// starts silent and fades in under the per-frame envelope. This mirrors the client's `0x460b00`
 /// (a 5.0 s crossfade — out `0x7a5a10(5.0f)`, in `0x7a5dc0(0)` → `0x7a57b0(5.0f)`).
@@ -701,6 +934,82 @@ fn swap_ambience(
     }
 }
 
+/// **The Lua music slot, start to finish** — the `PlayMusic`/`StopMusic` intents the VM queued
+/// this frame ([`MusicRequest`]), then the slot's own upkeep: the infinite loop, the live slider,
+/// the starvation watch.
+///
+/// Unconditional, unlike the zone scheduler beside it, and that is the slot's nature rather than a
+/// convenience: this stream belongs to the *caller*, not to the world's soundscape. It is a second
+/// handle in the reference too (`[0xb06ccc]`, not `[0xb06cc4]`), it is not what a zone change,
+/// an area's silence interval or the day/night phase acts on, and the one thing the reference is
+/// recorded doing to it — a cinematic pausing and resuming it (`0x4603b0`'s `0x7a5ac0` early
+/// return) — is precisely *not* what that edge does to the zone track, which it stops and
+/// reschedules. So it rides its own system, on no run condition but the VM existing.
+fn lua_music(
+    script: Option<NonSendMut<benilla_ui::script::UiScript>>,
+    mut zone: NonSendMut<ZoneAudio>,
+    mut out: NonSendMut<SoundOutput>,
+    assets: Option<Res<WorldAssets>>,
+    config: Res<SoundConfig>,
+    // The zone scheduler's own clock — the verb writes `next_track_at`, so it must be the same
+    // clock [`zone_audio`] reads it against.
+    time: Res<Time>,
+    // WALL time, not the paced virtual clock — the watch compares elapsed time against the
+    // stream's own position (the reason spelled out on [`zone_audio`]'s own `real` parameter).
+    real: Res<Time<bevy::time::Real>>,
+) {
+    let zone = &mut *zone;
+    let now = time.elapsed_secs_f64();
+    let requests = script.map(|mut s| s.take_music()).unwrap_or_default();
+    for req in requests {
+        match req {
+            // The NULL arm. It always lands: it needs no file, no device and no catalog — and it
+            // is *not* a no-op even from cold, because the pump's clock moves either way.
+            benilla_ui::script::MusicRequest::Stop => {
+                set_lua_music(zone, &mut out, None, &config, None, now)
+            }
+            benilla_ui::script::MusicRequest::Play(path) => {
+                // Under the loading cover a start is DROPPED, not deferred — the same posture as
+                // a server push ([`server_sounds`]) and as the kit player's own gate: the
+                // reference's blocking load plays nothing, and a track queued behind the cover
+                // would arrive in the destination zone instead of the one that asked for it.
+                let Some(assets) = assets.as_deref().filter(|_| !config.world_hold) else {
+                    debug!("Lua music: {path} dropped — no assets, or the loading cover is up");
+                    continue;
+                };
+                set_lua_music(zone, &mut out, Some(assets), &config, Some(&path), now);
+            }
+        }
+    }
+
+    // **The loop.** The reference opens this slot with `SetLoopCount(-1)`, so the natural end is a
+    // restart from the top rather than a stop; kira cannot loop a decode-stream, so the restart is
+    // explicit (the field's own docs, and the same shape [`super::glue`] gives the theme).
+    if zone
+        .lua_music
+        .as_ref()
+        .is_some_and(|h| h.state() == kira::sound::PlaybackState::Stopped)
+    {
+        zone.lua_music = None;
+        if let (Some(path), Some(assets)) = (zone.lua_music_path.clone(), assets.as_deref()) {
+            open_lua_music(zone, &mut out, assets, &config, &path);
+        }
+    }
+
+    // The Music slider is live on this stream, as it is on every other music stream in the client
+    // (`0x7a6660(ecx=2)`, the MusicVolume re-apply walker) — and `glide`, not a snap, for the same
+    // reason the zone track's feed glides (decision 1026).
+    if let Some(h) = zone.lua_music.as_mut() {
+        h.set_volume(
+            mixer::amp_to_db(config.category_amp(SoundCategory::Music) * LUA_MUSIC_VOLUME),
+            mixer::glide(),
+        );
+    }
+    if let Some(h) = zone.lua_music.as_ref() {
+        zone.lua_music_watch.feed(h, f64::from(real.delta_secs()));
+    }
+}
+
 /// Server-pushed sounds (`SMSG_PLAY_SOUND`/`PLAY_MUSIC`/`PLAY_OBJECT_SOUND`, bridged by
 /// `net::apply_net_updates`): 2D kits and object-positioned 3D kits go through the kit player;
 /// music takes the zone music slot (interrupting the current track — the zone scheduler resumes
@@ -796,6 +1105,10 @@ fn server_sounds(
 /// statics, not per-session state (the intro throttle survives a relog).
 fn leave_world(mut zone: NonSendMut<ZoneAudio>) {
     stop_world_soundscape(&mut zone, "left world");
+    // The Lua slot too — and only here, not under the loading cover: an addon's track is the
+    // caller's, not the world's (see [`lua_music`]), so a teleport's cover leaves it playing,
+    // while a logout takes the VM that owns it with it.
+    drop_lua_music(&mut zone);
 }
 
 /// Stop the beds and reset the scheduler to cold — shared by the two edges where the world's
@@ -847,6 +1160,7 @@ fn stop_world_soundscape(zone: &mut ZoneAudio, reason: &str) {
 fn report_stream_voices(zone: NonSend<ZoneAudio>, mut out: NonSendMut<super::SoundOutput>) {
     let live = |s: kira::sound::PlaybackState| s != kira::sound::PlaybackState::Stopped;
     out.zone_streams = usize::from(zone.music.as_ref().is_some_and(|h| live(h.state())))
+        + usize::from(zone.lua_music.as_ref().is_some_and(|h| live(h.state())))
         + usize::from(zone.ambience.as_ref().is_some_and(|h| live(h.state())));
 }
 
@@ -860,6 +1174,23 @@ pub(super) fn plugin(app: &mut App) {
                 .run_if(super::world_audio_live)
                 .in_set(WorldStage::Present),
         )
+        // Before them, and unconditional — the reasons are on [`lua_music`]. Ordered first so the
+        // slot this frame's `PlayMusic` takes is already taken when the zone scheduler runs, and
+        // **after the tick** because that is the side of it this system is on: it drains what the
+        // VM produced this frame, exactly as [`super::ui`]'s `PlaySound` drain does (2304's rule
+        // for a VM holder — `.after(UiInput)` for a drain, `UiFeed` for a push).
+        .add_systems(
+            Update,
+            lua_music
+                .before(server_sounds)
+                .after(crate::ui_script::UiInput)
+                // And after the dev mute chord, for the reason `apply_master_volume` already
+                // declares that same order: this system's per-frame gain feed reads
+                // `SoundConfig`, so reading it after the flip is what makes the chord audible on
+                // the frame it is pressed instead of the next one.
+                .after(super::toggle_mute)
+                .in_set(WorldStage::Present),
+        )
         // Unconditional: the budget must fall back to zero when the soundscape stops, and a
         // system gated on `world_audio_live` would freeze the last count instead.
         .add_systems(Update, report_stream_voices)
@@ -871,10 +1202,13 @@ pub(super) fn plugin(app: &mut App) {
 
 #[cfg(test)]
 mod tests {
-    use super::{apply_music_suppression, slot_holds, ZoneAudio, CINEMATIC_MUSIC_RESUME_SECS};
+    use super::{
+        apply_music_suppression, slot_holds, take_lua_music_slot, ZoneAudio,
+        CINEMATIC_MUSIC_RESUME_SECS, LUA_MUSIC_SCHEDULE_SECS,
+    };
     use kira::sound::PlaybackState;
 
-    /// **The cinematic's music stop, both edges** — wow-re `cinematic-audio-law.md`, VERIFIED.
+    /// **The cinematic's music stop, both edges**.
     /// Down is a CUT: `0x7a5700` is stop-and-destroy and takes no duration argument, so there is
     /// nothing to fade with — not the 4.0 s zone-change fade, not the 250 ms teardown declick.
     /// Up is `[0x836400] = tick + 0xbb8` = **3.000 s**, which is a third number, neither the `-1`
@@ -908,6 +1242,46 @@ mod tests {
         assert_eq!(zone.zone_music, 42);
     }
 
+    /// **A cinematic BORROWS a Lua `PlayMusic` track** — the one thing the reference is recorded
+    /// doing to this slot. `0x4603b0` writes
+    /// the disabled flag, sees the slot live at `0x4603d6`, pauses the stream and returns: the
+    /// pump still dies (that flag is written *before* the early return) and nothing else moves —
+    /// no stop, no clear, and `[0x836400]` never rearmed on the way back out. The zone track's own
+    /// edges (a cut, then +3.000 s) are the test above; these are those same two edges with a
+    /// caller's track on the slot, and they must do neither of those things.
+    #[test]
+    fn a_cinematic_borrows_a_lua_music_track_and_leaves_the_schedule_alone() {
+        let mut zone = ZoneAudio {
+            zone_music: 42,
+            next_track_at: Some(100.0),
+            lua_music_path: Some("Sound\\Music\\x.mp3".into()),
+            ..ZoneAudio::default()
+        };
+
+        apply_music_suppression(&mut zone, true, 10.0);
+        assert!(
+            zone.music_suppressed,
+            "the flag is written before the early return, so the pump dies either way"
+        );
+        assert_eq!(
+            zone.next_track_at,
+            Some(100.0),
+            "the zone schedule is neither cleared nor rearmed"
+        );
+
+        apply_music_suppression(&mut zone, false, 112.5);
+        assert!(!zone.music_suppressed);
+        assert_eq!(
+            zone.next_track_at,
+            Some(100.0),
+            "the +3.000 s resume belongs to the other edge — `[0x836400]` is never rearmed here"
+        );
+        assert!(
+            zone.lua_slot_live(),
+            "and the track is still the caller's, across both edges"
+        );
+    }
+
     /// The resume is its own number and must not be confused with the two neighbours it sits
     /// between — a zone change's immediate start, and the natural-end silence interval.
     #[test]
@@ -915,6 +1289,59 @@ mod tests {
         assert!((CINEMATIC_MUSIC_RESUME_SECS - 3.0).abs() < f64::EPSILON);
     }
 
+    /// **`StopMusic()` is `PlayMusic(NULL)`, and this is the whole of it** (B391). `0x458770` is
+    /// four instructions, three of which are `0x460450(NULL)`, and that shared head does exactly
+    /// three things before the branch: fade this slot over 4.0 s (`0x460480`), clear it
+    /// (`0x460485`), and write the zone pump's next start (`0x46049b`).
+    ///
+    /// Two claims worth a test each, because both are the kind that gets dropped:
+    ///
+    /// * **The pump write is unconditional** — it sits between `0x460499`'s `test` and its `je`,
+    ///   ahead of the NULL branch — so a stop from **cold** still moves the clock, and pushes out
+    ///   a start that was already due.
+    /// * **The zone track is not what it stops.** `[0xb06cc4]` is mentioned only past that
+    ///   branch: the zone's own music plays on through a `StopMusic`, which is the half a
+    ///   "stop the music" verb would most naturally get wrong.
+    #[test]
+    fn the_lua_music_verb_rearms_the_zone_pump_at_six_seconds_even_from_cold() {
+        // Its own number, and neither of the two it sits between: not the cinematic's 3.000 s,
+        // and not the randomized `SilenceInterval` the natural-end reap draws. The second is a
+        // `const` assertion because it compares two constants — it holds at compile time, which
+        // is the right time for "these are two numbers, not one".
+        assert!((LUA_MUSIC_SCHEDULE_SECS - 6.0).abs() < f64::EPSILON);
+        const { assert!(LUA_MUSIC_SCHEDULE_SECS != CINEMATIC_MUSIC_RESUME_SECS) };
+
+        // From cold: nothing on the slot, a zone track due this very tick.
+        let mut zone = ZoneAudio {
+            zone_music: 42,
+            next_track_at: Some(10.0),
+            ..ZoneAudio::default()
+        };
+        take_lua_music_slot(&mut zone, 10.0);
+        assert_eq!(
+            zone.next_track_at,
+            Some(16.0),
+            "a stop from cold still moves the pump — and clobbers a start that was due now"
+        );
+        assert!(!zone.lua_slot_live());
+
+        // With a track on the slot: the slot is cleared, the zone's own state is not.
+        let mut zone = ZoneAudio {
+            zone_music: 42,
+            music_kit: 8440,
+            lua_music_path: Some("Sound\\Music\\x.mp3".into()),
+            ..ZoneAudio::default()
+        };
+        take_lua_music_slot(&mut zone, 100.0);
+        assert!(!zone.lua_slot_live(), "the caller's track is over");
+        assert_eq!(zone.next_track_at, Some(106.0));
+        assert_eq!(
+            (zone.music_kit, zone.zone_music),
+            (8440, 42),
+            "zone music is not what this verb stops"
+        );
+    }
+
     /// The repeat-push guard. The server keeps an event track looping by re-pushing its id every
     /// few seconds (the Darkmoon Faire emitter: `SMSG_PLAY_MUSIC` 8440 every 5 s), so a push for
     /// the track *currently playing* must do nothing — without this the faire stacked a new
diff --git a/crates/benilla-app/src/ui_action/cast_send.rs b/crates/benilla-app/src/spell/cast_send.rs
similarity index 89%
rename from crates/benilla-app/src/ui_action/cast_send.rs
rename to crates/benilla-app/src/spell/cast_send.rs
index 39bacc0f..4daa7e27 100644
--- a/crates/benilla-app/src/ui_action/cast_send.rs
+++ b/crates/benilla-app/src/spell/cast_send.rs
@@ -4,8 +4,8 @@
 //! the trade-skill window and the craft window all funnel here too. That is the point: the client's
 //! `TryCast 0x6e4b60` → commit `0x6e54f0` is *one* function with a long ladder of local gates and a
 //! post-send tail, and duplicating any part of it per caller is how the two paths drift. The ladder
-//! below is that function's order, gate for gate (re-pinned end to end by the 0948 §5,
-//! `gcd-power-gate.md`) — profession intercept, auto-repeat toggle, targeting abort, in-flight,
+//! below is that function's order, gate for gate (re-pinned end to end in 0948) — profession
+//! intercept, auto-repeat toggle, targeting abort, in-flight,
 //! reagents/totems, target binding + range, then the validator `0x6094f0`'s opening rungs
 //! (not-ready/GCD, power), mounted, moving, form, the deferred cast-arm refusal and
 //! targeting-cursor entry — followed
@@ -22,8 +22,8 @@
 //! computes a display flag and does *not* skip the IsCasting gate below it, and at `6e4f33`, where
 //! it is forwarded to the requirement validator `0x6094f0`. Every rung between entry and the
 //! commit is therefore the same code for a spell and for an item, which is why [`CastCommit`] is a
-//! *parameter* of this function and not a second path. Three rungs fork on it, and only three
-//! (`gcd-power-gate.md` §1): the validator's first rung (`60952b`: item → the item cooldown query
+//! *parameter* of this function and not a second path. Three rungs fork on it, and only three:
+//! the validator's first rung (`60952b`: item → the item cooldown query
 //! `0x6e2ed0` on the (use-spell, ENTRY) pair and error **0x28** "Item is not ready yet."; no item
 //! → `0x6e2ea0` and **0x3c** "Spell is not ready yet."), the power gate (`0x60962c` — an item
 //! press's clear-query jump lands PAST it: items are never power-gated), and the commit's opcode
@@ -36,15 +36,15 @@ use bevy::ecs::system::SystemParam;
 use bevy::prelude::*;
 
 use crate::items::Items;
-use crate::net::{ClientCommand, NetCommands, SelfPlayer};
+use crate::net::{ClientCommand, NetCommands, Objects, SelfPlayer};
 
-use super::{cast_target, reagent_totem_refusal, state, AutoRepeatActive, CastErrors, Spells};
+use super::{cast_target, validator, AutoRepeatActive};
+use crate::ui_action::{reagent_totem_refusal, CastErrors, Spells};
 
 /// **What the commit writes** — `SendCast 0x6e54f0`'s one branch on item-present. The sender
 /// discriminates on whether the pending-cast block's guid (`0xceac48`, filled at `6e4f8d`–`6e4fa6`
 /// from the ITEM's guid when TryCast was handed one, else the caster's) is the caster's, and the
-/// item arm falls through to `0x6e57d8 push 0xab` = `CMSG_USE_ITEM` (wow-re `action-item-slot.md`
-/// §8, `cursor-system.md` §8.4a — both byte-read).
+/// item arm falls through to `0x6e57d8 push 0xab` = `CMSG_USE_ITEM`.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum CastCommit {
     /// `CMSG_CAST_SPELL 0x12e` — no item bound.
@@ -94,17 +94,19 @@ pub(crate) struct CastLadder<'w, 's> {
     pub(crate) self_player:
         Query<'w, 's, (Entity, Has<crate::creature_anim::Engaged>), With<SelfPlayer>>,
     pub(crate) spells: Option<Res<'w, Spells>>,
-    /// The item cache — the pre-send totem/reagent check reads it (decision 0552), and the item
-    /// arms resolve templates through it.
+    /// The item cache — the item arms resolve templates through it.
     pub(crate) items: Res<'w, Items>,
+    /// The one object index (decision 2334) — the pre-send totem/reagent check walks the bags
+    /// through it, and the item arms resolve an instance guid to its fields here.
+    pub(crate) objects: Objects<'w, 's>,
     pub(crate) sheath: MessageWriter<'w, crate::creature_anim::SheathRequest>,
     pub(crate) ecs: Commands<'w, 's>,
-    pub(crate) pending: ResMut<'w, crate::ui_cast::PendingCast>,
-    pub(crate) queued_melee: ResMut<'w, crate::ui_cast::QueuedMeleeSpell>,
-    pub(crate) cooldowns: ResMut<'w, crate::cooldowns::Cooldowns>,
+    pub(crate) pending: ResMut<'w, crate::spell::PendingCast>,
+    pub(crate) queued_melee: ResMut<'w, crate::spell::QueuedMeleeSpell>,
+    pub(crate) cooldowns: ResMut<'w, crate::spell::Cooldowns>,
     /// The talent spell-modifier tables — rung 2's cost goes through them
     /// ([`super::usable::power_cost`]).
-    pub(crate) spell_mods: Res<'w, crate::spell_mods::SpellModifiers>,
+    pub(crate) spell_mods: Res<'w, crate::spell::SpellModifiers>,
     pub(crate) cast_errors: ResMut<'w, CastErrors>,
     pub(crate) auto_repeat: ResMut<'w, AutoRepeatActive>,
     pub(crate) trade_skill_opens: ResMut<'w, crate::ui_tradeskill::TradeSkillOpens>,
@@ -239,6 +241,7 @@ impl CastLadder<'_, '_> {
             &self.commands,
             &self.self_player,
             self.spells.as_deref(),
+            &self.objects,
             &self.items,
             &mut self.sheath,
             &mut self.ecs,
@@ -259,13 +262,13 @@ impl CastLadder<'_, '_> {
 /// (`0x6e5930`'s `SetSheatheState(2,1,1)` — the echo START re-requests it, idempotent), an
 /// auto-repeat spell sets the sticky armed state (`0x6e593b`'s `|= 0x200`, the standing Load/Hold
 /// idle's gate — decision 0099 phase 5), and the resolved `CMSG_CAST_SPELL` goes out. Shared by
-/// [`super::drain::drain_action_uses`] (a SPELL-kind action button) and
+/// `ui_action`'s `drain_action_uses` (a SPELL-kind action button) and
 /// `ui_spellbook::drain_spell_casts` (a spellbook cast, decision 0216 §8) — ONE cast-send path, so
 /// the follow-through can't drift between the two spell sources (the root-cause rule: never
 /// duplicate a send path).
 ///
-/// The `pending` guard is the client's optimistic in-flight refusal (wow-re `wave-cast.md`
-/// `TryCast` IsCasting gate; see [`crate::ui_cast::PendingCast`]): a normal cast is dropped at the
+/// The `pending` guard is the client's optimistic in-flight refusal (`TryCast`'s IsCasting gate,
+/// `6e4d97`; see [`crate::spell::PendingCast`]): a normal cast is dropped at the
 /// source while one is already in flight, so mashing a key can no longer fire a duplicate
 /// `CMSG_CAST_SPELL` the server bounces back as a spurious cast-bar cancel. Ranged/auto-repeat
 /// shots keep their own lifecycle — they never arm the guard and are never blocked by it.
@@ -280,13 +283,14 @@ fn send_spell_cast(
     commands: &NetCommands,
     self_player: &Query<(Entity, Has<crate::creature_anim::Engaged>), With<SelfPlayer>>,
     spells: Option<&Spells>,
+    objects: &Objects,
     items: &Items,
     sheath: &mut MessageWriter<crate::creature_anim::SheathRequest>,
     ecs: &mut Commands,
-    pending: &mut crate::ui_cast::PendingCast,
-    queued_melee: &mut crate::ui_cast::QueuedMeleeSpell,
-    cooldowns: &mut crate::cooldowns::Cooldowns,
-    spell_mods: &crate::spell_mods::SpellModifiers,
+    pending: &mut crate::spell::PendingCast,
+    queued_melee: &mut crate::spell::QueuedMeleeSpell,
+    cooldowns: &mut crate::spell::Cooldowns,
+    spell_mods: &crate::spell::SpellModifiers,
     cast_errors: &mut CastErrors,
     auto_repeat: &mut AutoRepeatActive,
     trade_skill_opens: &mut crate::ui_tradeskill::TradeSkillOpens,
@@ -295,7 +299,7 @@ fn send_spell_cast(
     let now = Instant::now();
     let def = spells.and_then(|s| s.catalog.get(spell_id));
     // The profession-window intercept (decision 0437): `Spell_C::TryCast 0x6e4b60`'s own first
-    // special branch (wow-re `wave-cast.md`, VERIFIED) — an `Effect[0] == SPELL_EFFECT_TRADE_SKILL`
+    // special branch — an `Effect[0] == SPELL_EFFECT_TRADE_SKILL`
     // cast NEVER reaches the wire; the crafting book opens client-side instead. Before the
     // cooldown ladder, exactly where the client dispatches it (`6e4bce`, ahead of every gate).
     if def.is_some_and(|d| d.effects[0] == benilla_formats::SPELL_EFFECT_TRADE_SKILL) {
@@ -303,7 +307,7 @@ fn send_spell_cast(
         trade_skill_opens.0.push(spell_id);
         return;
     }
-    // The button re-press toggle (`0x4e60da`, wow-re `nocked-ammo-cancel.md` §Q-B-2):
+    // The button re-press toggle (`0x4e60da`):
     // re-invoking the spell that IS the running auto-repeat cancels it instead of re-casting —
     // the classic press-again-to-stop. Checked before the cooldown ladder, like the client's
     // action-button handler (which never reaches TryCast for the toggle-off).
@@ -322,11 +326,12 @@ fn send_spell_cast(
         ground.clear();
     }
     // The cast classes at this seam. A ranged/auto-repeat shot (Auto Shot, wand Shoot, Throw) is
-    // not a cast-bar cast — it runs the ranged-stance / `AutoRepeatArmed` path, outside the
-    // in-flight guard. An on-next-swing spell (`Attributes & 0x404` — Heroic Strike, Cleave)
-    // queues on the server's melee slot: it arms [`crate::ui_cast::QueuedMeleeSpell`], never the
+    // not a cast-bar cast — it runs the ranged-stance / `AutoRepeatArmed` path, and its own
+    // record does not guard (1601), though it is refused like any press while a guarding cast
+    // holds. An on-next-swing spell (`Attributes & 0x404` — Heroic Strike, Cleave)
+    // queues on the server's melee slot: it arms [`crate::spell::QueuedMeleeSpell`], never the
     // in-flight guard, so a queued strike cannot block the next cast (the ref's `6e4d97`
-    // exemption on the inflight rec's 0x404 bits — wow-re `wave-cast.md`).
+    // exemption on the inflight rec's 0x404 bits).
     let on_next_swing = def.is_some_and(|d| d.on_next_swing());
     let normal_cast = !def.is_some_and(|d| d.ranged_attack()) && !on_next_swing;
     // Re-pressing the queued strike is the ref's silent same-spell bail (`6e4d43`) — no cancel,
@@ -335,11 +340,15 @@ fn send_spell_cast(
         debug!("ui_action: cast {spell_id} suppressed — already queued on next swing");
         return;
     }
-    if (normal_cast || on_next_swing) && pending.in_flight(now) {
+    if pending.in_flight(now) {
         // The ref's already-casting refusal: the same spell bails silently (`6e4d43`); a
         // different one errors reason 0x61 "Another action is in progress" (`6e4d97` →
-        // `HandleCastFailed`) — the inflight rec here is always an ordinary cast, so even an
-        // on-next-swing press is refused while it holds.
+        // `HandleCastFailed`). The gate tests the **inflight** rec's `Attributes & 0x404`, never
+        // the pressed spell's, and a
+        // guarding record here is always an ordinary cast or an item use — so EVERY press class
+        // is refused while it holds: an on-next-swing strike, and a ranged/auto-repeat shot too.
+        // Exempting the shot let it commit and its non-guarding arm overwrite the running cast's
+        // record, leaving that cast unguarded once the server refused the shot.
         if pending.current(now) != Some(spell_id) {
             cast_errors.push_local(spell_id, 0x61);
         }
@@ -350,10 +359,10 @@ fn send_spell_cast(
     // `0x6e4ded` — decision 0552): a missing tool (Mining Pick) or a short reagent refuses HERE
     // with the client's own 0x78/0x5c red line and NEVER sends. The gate must be local: vmangos
     // answers a sent pickless cast with the wrong code (`ITEM_GONE` "Item is gone"), so without
-    // it the real message can't appear. Position pinned by the 0948 §5: TryCast runs it BEFORE
+    // it the real message can't appear. Position pinned by 0948: TryCast runs it BEFORE
     // the validator (`0x6e4ded` precedes the `0x6e4f3b` call), so an on-cooldown press with
     // missing reagents shows the reagent error, never "not ready".
-    if reagent_totem_refusal(spell_id, def, ctx.rel.self_store, items, cast_errors) {
+    if reagent_totem_refusal(spell_id, def, ctx.rel.self_store, objects, cast_errors) {
         return;
     }
     // **TryCast rung 7** (`0x6e4e03`, decision 1925) — the equipped-item requirement, which the
@@ -366,7 +375,7 @@ fn send_spell_cast(
     // player who is both stunned and missing the required weapon is told about **the weapon**.
     if let Some(d) = def {
         if let Some(store) = ctx.rel.self_store {
-            if !super::usable::equipped_item_fits_cached(d, store, items) {
+            if !super::usable::equipped_item_fits_cached(d, store, objects, items) {
                 let reason = super::usable::equipped_item_reason(d);
                 debug!("ui_action: cast {spell_id} refused locally — equipped item ({reason:#x})");
                 cast_errors.push_local(spell_id, reason);
@@ -391,12 +400,12 @@ fn send_spell_cast(
         selection: ctx.selection_guid,
         caster: ctx.self_guid,
         // The ref resolves its candidate guid through `0x468460(typemask 1)` (`6e53bc`) before
-        // handing it to the binder: a guid naming no live object binds nothing. Ours is the item
-        // cache — an equipped item whose object has not streamed yet is exactly that miss, and
-        // falls to the cursor rather than shipping a guid the server would reject.
+        // handing it to the binder: a guid naming no live object binds nothing. Ours is the one
+        // object index — an equipped item whose object has not streamed yet is exactly that miss,
+        // and falls to the cursor rather than shipping a guid the server would reject.
         main_hand_item: ctx
             .main_hand_item
-            .filter(|guid| items.object(*guid).is_some()),
+            .filter(|guid| objects.object(*guid).is_some()),
     };
     let target = match explicit_object {
         Some(_) => None,
@@ -460,7 +469,7 @@ fn send_spell_cast(
                 .self_pos
                 .zip(ctx.range.target_pos)
                 .map(|(a, b)| a.distance_squared(b));
-            if let Some(reason) = state::cast_range_refusal(
+            if let Some(reason) = validator::cast_range_refusal(
                 d,
                 row,
                 ctx.range.self_reach,
@@ -473,11 +482,10 @@ fn send_spell_cast(
             }
         }
     }
-    // ── The validator `0x6094f0`'s opening rungs (wow-re `gcd-power-gate.md`, the §5 that
-    // closed 0379's INTERIM; decision 0948) — after IsCasting, reagents and the range test,
-    // exactly where the ref calls the validator. ──
+    // ── The validator `0x6094f0`'s opening rungs (decision 0948, which closed 0379's INTERIM) —
+    // after IsCasting, reagents and the range test, exactly where the ref calls the validator. ──
     //
-    // Rung 1 — not-ready: ONE getter query ([`crate::cooldowns::Cooldowns::not_ready`] =
+    // Rung 1 — not-ready: ONE getter query ([`crate::spell::Cooldowns::not_ready`] =
     // `GetCooldownInfo != 0`), forked by the commit at `0x60952b`: an item press queries the
     // (use-spell, item ENTRY) pair and refuses **0x28** — and per the byte law is never
     // power-gated; a spell press queries (spell, 0) and refuses **0x3c**. The GCD lock rides
@@ -536,7 +544,7 @@ fn send_spell_cast(
     // three arms to the reference's six by 1925), which sits ABOVE its mounted block below — so a
     // stunned mounted caster reads the stun.
     let self_fields = ctx.rel.self_store.map(|s| &s.0);
-    if let Some(reason) = state::cast_cc_refusal(
+    if let Some(reason) = validator::cast_cc_refusal(
         self_fields.map_or(0, |f| f.unit_flags()),
         self_fields.and_then(|f| f.unit_health()),
         // The charm arm asks whether somebody ELSE holds the reins (`60994d`'s active-player
@@ -576,7 +584,7 @@ fn send_spell_cast(
         }
         return;
     }
-    // The client-side mounted gate (decision 0481; wow-re `mounted-action-gate.md` §5:
+    // The client-side mounted gate (decision 0481;
     // TryCast's requirement validator `0x6094f0`, mounted block `0x609c6c` — a live
     // `UNIT_FIELD_MOUNTDISPLAYID` refuses a non-exempt cast with reason 0x39 "You are
     // mounted" BEFORE the cast-arm's target binding, which is why a targetless mounted click
@@ -585,7 +593,7 @@ fn send_spell_cast(
     // caster instead of erroring, so without this check the message can never appear. (0948
     // resolved 0481's named micro-divergence: the range gate now runs before this one, the
     // ref's own order — mounted∧out-of-range reads "Out of range." on both.)
-    if state::cast_mounted_refusal(
+    if validator::cast_mounted_refusal(
         ctx.rel
             .self_store
             .is_some_and(|s| s.0.unit_mount_display_id() > 0),
@@ -601,19 +609,19 @@ fn send_spell_cast(
     // while swimming" for the mount/Travel-Form/food set, 0x58 "Can only use while swimming" for
     // Aquatic Form. The gate must be local: vmangos's CheckCast has no shapeshift or food water
     // arm at all, so without this the server grants a druid aquatic form standing on dry land
-    // (ledger B176) and lets you eat mid-swim (B155's eating half). The condition is [`state`]'s.
-    if let Some(reason) = state::cast_water_refusal(ctx.self_move_flags, def) {
+    // (ledger B176) and lets you eat mid-swim (B155's eating half). The condition is [`validator`]'s.
+    if let Some(reason) = validator::cast_water_refusal(ctx.self_move_flags, def) {
         debug!("ui_action: cast {spell_id} refused locally — water side ({reason:#x})");
         cast_errors.push_local(spell_id, reason);
         return;
     }
     // The moving leg of the SAME requirement validator (`0x609de3`, after the mounted/posture/
-    // environment blocks, before the form leg — wow-re `moving-cast-gate.md`, decision 0862): a
+    // environment blocks, before the form leg — decision 0862): a
     // cast-time (or movement-sensitive) press while already moving refuses locally with the
     // client's own reason 0x2e "Can't do that while moving" and NEVER sends. The gate must be
     // local: vmangos accepts the sent cast (its CheckCast moving-reject covers only
     // autorepeat/sit-still spells) and then its movement interrupt cancels it mid-bar — the
-    // start-then-die cast bar this gate removes. The full condition is [`state`]'s.
+    // start-then-die cast bar this gate removes. The full condition is [`validator`]'s.
     if let Some(d) = def {
         let caster_level = ctx
             .rel
@@ -621,15 +629,14 @@ fn send_spell_cast(
             .and_then(|s| s.0.unit_level())
             .unwrap_or(0);
         let cast_time_ms = spells.map_or(0, |s| s.cast_time_ms(d, caster_level));
-        if state::cast_moving_refusal(ctx.self_move_flags, cast_time_ms, def) {
+        if validator::cast_moving_refusal(ctx.self_move_flags, cast_time_ms, def) {
             debug!("ui_action: cast {spell_id} refused locally — moving (0x2e)");
             cast_errors.push_local(spell_id, 0x2e);
             return;
         }
     }
     // The shapeshift-form leg of the SAME requirement validator (`0x6094f0` at `0x609e49` →
-    // the form gate `0x612480`; wow-re `shapeshift-plaincast-toggle.md` §Q3, which corrected
-    // `mounted-action-gate.md`'s `0x609ca2` gloss — that address is the POSTURE gate, reason
+    // the form gate `0x612480`, not `0x609ca2` — that address is the POSTURE gate, reason
     // 0x3e NOT_STANDING; vmangos corroborates the reason split,
     // `SpellEntry::GetErrorAtShapeshiftedCast`): a form-blocked press refuses locally with the
     // gate's own red line — 0x3d "Can't do that while shapeshifted" / 0x56 needs-a-form — and
@@ -668,7 +675,7 @@ fn send_spell_cast(
         return;
     }
     // The wand-only auto-repeat handoff (the client's `0x60959e` inside TryCast's `0x6094f0`
-    // step, wow-re `nocked-ammo-cancel.md` §Q-B-5): a NEW cast cancels the running auto-repeat
+    // step): a NEW cast cancels the running auto-repeat
     // iff the CACHED spell carries `AttributesEx3 & 0x400000` — wand Shoot 5019 alone in the
     // 1.12 data. Auto Shot survives by construction: hunter shot-weaving. The client first
     // sends `CMSG_CANCEL_CAST` naming the cached wand spell (`0x6095b8`), then runs the local
@@ -751,7 +758,7 @@ fn send_spell_cast(
     // **One inflight id, every cast source** (`0xceca88`, written at `0x6e5026` for every commit).
     // The item arm's provisional is shorter because `CMSG_USE_ITEM` has legs vmangos answers with
     // `SMSG_INVENTORY_CHANGE_FAILURE` and no cast result at all —
-    // [`crate::ui_cast::PendingCast`]'s own doc, decision 0908.
+    // [`crate::spell::PendingCast`]'s own doc, decision 0908.
     //
     // **Every** class is recorded; only `normal_cast` and the item arm *guard* (1601). This used
     // to be one thing: the record was armed only for the classes that refuse on it, so a ranged
@@ -765,14 +772,13 @@ fn send_spell_cast(
     if on_next_swing {
         queued_melee.arm(spell_id);
     }
-    // TryCast's post-send tail (`6e51b5`) — byte-verified whole by the 2026-07-14 wow-re §5
-    // (`combat-feel-law.md` @ c445713b): a committed send whose rec passes
+    // TryCast's post-send tail (`6e51b5`): a committed send whose rec passes
     // [`SpellDisplay::initiates_auto_attack`] (on-next-swing `0x404` or `AttributesEx & 0x200`,
     // and not the GO-deferred Ex2-bit20; Charge carries none) starts the melee auto-attack at
     // the cast's bound unit target, unless one is already running (`0x60ecb0` over
     // `[player+0xc48]`; our mirror is the wire-echoed `Engaged`). The start is the attack path's
     // own pair (`0x6131a0` → `0x5ecb70`): melee-sheath SNAP + `CMSG_ATTACKSWING` — the same two
-    // edges as the Attack button's arm in [`super::drain::drain_action_uses`]. Path-independent
+    // edges as the Attack button's arm in `ui_action`'s `drain_action_uses`. Path-independent
     // in the ref (button/spellbook/CastSpellByName share the one tail) — matching our one send
     // seam.
     if let (Some(d), Some(guid)) = (def, target) {
@@ -784,9 +790,8 @@ fn send_spell_cast(
                 // the tail at `0x5ecd78` whose `0x5ecd8c` cancels the auto-repeat — but a cast
                 // press never reaches that jump. TryCast's tail gates the CALL: `6e51cb call
                 // 0x60ecb0; 6e51d2 jne` skips `0x6131a0` outright when an attack is already
-                // running (wow-re `combat-feel-law.md` §A1, and `melee-autorepeat-exclusion.md`
-                // §0a, which states the consequence outright: a strike pressed while already
-                // engaged does nothing to a running auto-repeat). So the whole block is gated,
+                // running: a strike pressed while already engaged does nothing to a running
+                // auto-repeat. So the whole block is gated,
                 // and the exclusion holds from the other end instead — the commit's StopAttack
                 // above means an auto-repeat can't be running while we swing in the first place.
                 if !engaged {
@@ -862,14 +867,16 @@ mod tests {
         let mut world = World::new();
         world.insert_resource(NetCommands(tx));
         world.init_resource::<Items>();
-        world.init_resource::<crate::ui_cast::PendingCast>();
-        world.init_resource::<crate::ui_cast::QueuedMeleeSpell>();
-        world.init_resource::<crate::cooldowns::Cooldowns>();
-        world.init_resource::<crate::spell_mods::SpellModifiers>();
+        // The one object index the ladder's item arms resolve an instance guid through (2334).
+        world.init_resource::<crate::net::GuidIndex>();
+        world.init_resource::<crate::spell::PendingCast>();
+        world.init_resource::<crate::spell::QueuedMeleeSpell>();
+        world.init_resource::<crate::spell::Cooldowns>();
+        world.init_resource::<crate::spell::SpellModifiers>();
         world.init_resource::<CastErrors>();
         world.init_resource::<AutoRepeatActive>();
         world.init_resource::<crate::ui_tradeskill::TradeSkillOpens>();
-        world.init_resource::<super::super::targeting::SpellTargeting>();
+        world.init_resource::<crate::spell::SpellTargeting>();
         // The sheath request the commit tail writes for a ranged spell — a bare World has no
         // message storage until it is asked for.
         world.init_resource::<Messages<crate::creature_anim::SheathRequest>>();
@@ -1007,7 +1014,7 @@ mod tests {
         let (mut world, _rx) = combat_world(false);
         send_at(&mut world, SERPENT_STING, MOB);
         let now = Instant::now();
-        let pending = world.resource::<crate::ui_cast::PendingCast>();
+        let pending = world.resource::<crate::spell::PendingCast>();
         assert_eq!(
             pending.committed(now),
             Some(SERPENT_STING),
@@ -1026,7 +1033,7 @@ mod tests {
         // An ordinary cast still does both, unchanged.
         let (mut world, _rx) = combat_world(false);
         send_at(&mut world, RAPTOR_STRIKE, MOB);
-        let pending = world.resource::<crate::ui_cast::PendingCast>();
+        let pending = world.resource::<crate::spell::PendingCast>();
         assert_eq!(
             pending.committed(Instant::now()),
             Some(RAPTOR_STRIKE),
@@ -1052,7 +1059,7 @@ mod tests {
             matches!(rx.try_recv(), Ok(ClientCommand::CastSpell { spell_id, .. }) if spell_id == SERPENT_STING),
             "the sting goes out first"
         );
-        // What `cast_result` would queue, handed to the one send path the drain uses.
+        // What `cast_result` returns, and `on_cast_result` hands to the ladder (2330).
         send_at(&mut world, AUTO_SHOT, MOB);
         assert!(
             matches!(rx.try_recv(), Ok(ClientCommand::CastSpell { spell_id, .. }) if spell_id == AUTO_SHOT),
@@ -1065,6 +1072,43 @@ mod tests {
         );
     }
 
+    /// **A shot pressed mid-cast is refused, and the cast keeps its guard.** The reference's
+    /// already-casting gate (`6e4d97`)
+    /// tests the **inflight** rec's `Attributes & 0x404`, never the pressed spell's — so a wand
+    /// Shoot / Auto Shot pressed during a Frostbolt meets the same `0x61` as any other press.
+    /// Ours exempted the ranged class at the gate, so the shot went out, its non-guarding arm
+    /// overwrote the Frostbolt's record, vmangos refused the shot `SPELL_IN_PROGRESS`, and the
+    /// still-running Frostbolt was left unguarded for the next mashed key.
+    #[test]
+    fn a_shot_pressed_mid_cast_is_refused_and_the_cast_keeps_its_guard() {
+        const FROSTBOLT: u32 = 116;
+        let (mut world, rx) = combat_world(false);
+        world
+            .resource_mut::<crate::spell::PendingCast>()
+            .arm(FROSTBOLT, Instant::now(), true);
+
+        send_at(&mut world, AUTO_SHOT, MOB);
+
+        assert!(rx.try_recv().is_err(), "nothing goes out on the wire");
+        assert_eq!(
+            world.resource::<CastErrors>().0,
+            vec![CastFail::local(AUTO_SHOT, 0x61)],
+            "a different spell mid-cast is \"Another action is in progress\", whatever its class"
+        );
+        assert_eq!(
+            world
+                .resource::<crate::spell::PendingCast>()
+                .current(Instant::now()),
+            Some(FROSTBOLT),
+            "the Frostbolt still holds the guard"
+        );
+        assert_eq!(
+            world.resource::<AutoRepeatActive>().0,
+            None,
+            "and the refused shot armed no repeat"
+        );
+    }
+
     /// [`world`] plus the catalog and the self player the commit tail needs — `engaged` is our
     /// server-echoed mirror of the ref's attack lock `[+0xc48]`.
     fn combat_world(engaged: bool) -> (World, Receiver<ClientCommand>) {
@@ -1098,7 +1142,7 @@ mod tests {
     fn an_auto_repeat_press_stops_the_attack_and_takes_the_queued_strike_with_it() {
         let (mut world, rx) = combat_world(true);
         world
-            .resource_mut::<crate::ui_cast::QueuedMeleeSpell>()
+            .resource_mut::<crate::spell::QueuedMeleeSpell>()
             .arm(RAPTOR_STRIKE);
 
         send_at(&mut world, AUTO_SHOT, MOB);
@@ -1116,9 +1160,7 @@ mod tests {
             "and then the shot itself commits"
         );
         assert_eq!(
-            world
-                .resource::<crate::ui_cast::QueuedMeleeSpell>()
-                .current(),
+            world.resource::<crate::spell::QueuedMeleeSpell>().current(),
             None,
             "the queue is empty — the strike's checked ring goes dark"
         );
@@ -1131,7 +1173,7 @@ mod tests {
     fn an_auto_repeat_press_with_no_swing_running_stops_nothing() {
         let (mut world, rx) = combat_world(false);
         world
-            .resource_mut::<crate::ui_cast::QueuedMeleeSpell>()
+            .resource_mut::<crate::spell::QueuedMeleeSpell>()
             .arm(RAPTOR_STRIKE);
 
         send_at(&mut world, AUTO_SHOT, MOB);
@@ -1142,15 +1184,12 @@ mod tests {
         );
         assert!(rx.try_recv().is_err(), "no ATTACKSTOP, no CANCEL_CAST");
         assert_eq!(
-            world
-                .resource::<crate::ui_cast::QueuedMeleeSpell>()
-                .current(),
+            world.resource::<crate::spell::QueuedMeleeSpell>().current(),
             Some(RAPTOR_STRIKE)
         );
     }
 
-    /// **The other direction, and the correction decision 1028 needed** (wow-re §5,
-    /// `melee-autorepeat-exclusion.md` §0a + `combat-feel-law.md` §A1). `Attack 0x5ecb70`'s tail
+    /// **The other direction, and the correction decision 1028 needed**. `Attack 0x5ecb70`'s tail
     /// really does cancel the auto-repeat on a path that skipped the swing send — but a cast press
     /// never reaches it while engaged: TryCast's tail gates the CALL, `6e51cb call 0x60ecb0;
     /// 6e51d2 jne`, so `0x6131a0` is not invoked at all. A strike pressed mid-swing therefore does
@@ -1179,9 +1218,7 @@ mod tests {
             "the repeat survives: the reference cancels it via the attack it STARTS, and it started none"
         );
         assert_eq!(
-            world
-                .resource::<crate::ui_cast::QueuedMeleeSpell>()
-                .current(),
+            world.resource::<crate::spell::QueuedMeleeSpell>().current(),
             Some(RAPTOR_STRIKE),
             "the strike still queues — only the attack-start was skipped"
         );
@@ -1189,7 +1226,7 @@ mod tests {
 
     /// The same press from the state that *is* reachable: not yet swinging. Here the tail fires,
     /// `0x6131a0` → `0x5ecb70` runs, and its `0x5ecd8c` kills the repeat on the way to the swing —
-    /// the transitive route all three §5 workers missed by censusing StartAttack's direct callers.
+    /// a transitive route that a census of StartAttack's direct callers misses.
     #[test]
     fn a_strike_pressed_before_the_swing_starts_kills_the_auto_repeat() {
         let (mut world, rx) = combat_world(false);
@@ -1263,9 +1300,12 @@ mod tests {
             category: 0,
             category_cooldown_ms: 0,
         };
-        world
-            .resource_mut::<crate::cooldowns::Cooldowns>()
-            .start_item(6948, &use_spell, None, Instant::now());
+        world.resource_mut::<crate::spell::Cooldowns>().start_item(
+            6948,
+            &use_spell,
+            None,
+            Instant::now(),
+        );
 
         send(&mut world, HEARTHSTONE, HEARTH_COMMIT);
         assert!(rx.try_recv().is_err(), "an item on cooldown never sends");
@@ -1274,12 +1314,12 @@ mod tests {
             vec![CastFail::local(HEARTHSTONE, 0x28)]
         );
 
-        // The byte law's other half (0948, correcting this test's pre-§5 shape): the record is
+        // The byte law's other half (0948, correcting this test's earlier shape): the record is
         // keyed (use-spell, item ENTRY), and a bare SPELL press queries (spell, 0) — the item
         // record does NOT match it, so the press passes the rung and commits. (One store, two
         // KEYS — no longer "one store keyed by spell id for both".)
         world.resource_mut::<CastErrors>().0.clear();
-        world.insert_resource(crate::ui_cast::PendingCast::default());
+        world.insert_resource(crate::spell::PendingCast::default());
         send(&mut world, HEARTHSTONE, CastCommit::Spell);
         assert!(
             matches!(rx.try_recv(), Ok(ClientCommand::CastSpell { .. })),
@@ -1308,7 +1348,7 @@ mod tests {
 
         // `init_resource` would keep the armed guard — the point here is the commit, not the
         // in-flight rung the test above owns.
-        world.insert_resource(crate::ui_cast::PendingCast::default());
+        world.insert_resource(crate::spell::PendingCast::default());
         send(&mut world, HEARTHSTONE, HEARTH_COMMIT);
         assert!(matches!(
             rx.try_recv(),
@@ -1320,7 +1360,7 @@ mod tests {
             })
         ));
 
-        world.insert_resource(crate::ui_cast::PendingCast::default());
+        world.insert_resource(crate::spell::PendingCast::default());
         send(
             &mut world,
             HEARTHSTONE,
@@ -1342,7 +1382,7 @@ mod tests {
         ));
     }
 
-    /// The validator's power gate (0948, `gcd-power-gate.md` §1.4): a SPELL press the caster
+    /// The validator's power gate (0948, `0x60962c`): a SPELL press the caster
     /// cannot afford refuses locally with 0x4d and never wires — the gate vmangos cannot supply
     /// (it ACCEPTS the doomed cast, and its NO_POWER fail would clear a running GCD: the
     /// phantom pie-blink on rage-starved spam). An ITEM press skips the gate entirely (the item
@@ -1363,7 +1403,7 @@ mod tests {
                 ..Default::default()
             },
         );
-        let mut spells = super::super::Spells::empty_for_tests();
+        let mut spells = crate::ui_action::Spells::empty_for_tests();
         spells.catalog = benilla_formats::SpellCatalog::from_displays(displays);
         world.insert_resource(spells);
         // A caster holding 100 mana (field 23 = UNIT_FIELD_POWER1). Leaked: the one-shot
@@ -1427,9 +1467,12 @@ mod tests {
             category: 0,
             category_cooldown_ms: 0,
         };
-        world
-            .resource_mut::<crate::cooldowns::Cooldowns>()
-            .start_item(0, &use_spell, None, Instant::now());
+        world.resource_mut::<crate::spell::Cooldowns>().start_item(
+            0,
+            &use_spell,
+            None,
+            Instant::now(),
+        );
         // …and a DIFFERENT cast in flight.
         send(&mut world, HEARTHSTONE, CastCommit::Spell);
         assert!(matches!(rx.try_recv(), Ok(ClientCommand::CastSpell { .. })));
@@ -1457,9 +1500,9 @@ mod tests {
         const GO: u64 = 0xF110_000C_1F00_A3B2;
         let (mut world, rx) = world();
         let commit = |world: &mut World, commit: CastCommit, bound: TargetedBind| {
-            world.insert_resource(crate::ui_cast::PendingCast::default());
+            world.insert_resource(crate::spell::PendingCast::default());
             world
-                .resource_mut::<super::super::targeting::SpellTargeting>()
+                .resource_mut::<crate::spell::SpellTargeting>()
                 // The lock word — the one that answers both the bag and the world seam.
                 .enter(HEARTHSTONE, commit, 0x4800);
             world
@@ -1475,14 +1518,12 @@ mod tests {
             Ok(ClientCommand::CastSpellAtDest { dest: DEST, .. })
         ));
         assert!(
-            !world
-                .resource::<super::super::targeting::SpellTargeting>()
-                .active(),
+            !world.resource::<crate::spell::SpellTargeting>().active(),
             "the commit clears the one word"
         );
         assert!(
             world
-                .resource::<crate::ui_cast::PendingCast>()
+                .resource::<crate::spell::PendingCast>()
                 .in_flight(Instant::now()),
             "and arms the in-flight guard the click owes"
         );
diff --git a/crates/benilla-app/src/ui_action/cast_target.rs b/crates/benilla-app/src/spell/cast_target.rs
similarity index 97%
rename from crates/benilla-app/src/ui_action/cast_target.rs
rename to crates/benilla-app/src/spell/cast_target.rs
index b6f744e4..32a542c0 100644
--- a/crates/benilla-app/src/ui_action/cast_target.rs
+++ b/crates/benilla-app/src/spell/cast_target.rs
@@ -1,7 +1,7 @@
 //! The cast-arm's **target resolution** — what actually goes in `CMSG_CAST_SPELL`'s target block.
 //!
-//! Transcribes `Spell_C::ArmCast 0x6e5250` + `BindTarget 0x6e5b40` (wow-re `wave-cast.md`, both
-//! byte-verified): the client seeds a targeting flag_word from `Spell.dbc Targets` (`SpellRec+0x34`),
+//! Transcribes `Spell_C::ArmCast 0x6e5250` + `BindTarget 0x6e5b40`: the client seeds a targeting
+//! flag_word from `Spell.dbc Targets` (`SpellRec+0x34`),
 //! adjusts it with the implicit-target switch (`SpellRec+0x148`, jump-table `0x6e5484`), and then
 //!
 //! - **flag_word == 0** ⇒ the cast needs no target at all — commit immediately, wire mask
@@ -50,8 +50,8 @@ use bevy::prelude::*;
 use crate::net::{ObjectStore, Reputations, SelfGuid, SelfPlayer};
 use crate::target::{can_attack, ring_reaction, Factions, Selection};
 
-/// `TARGET_FLAG_*` bits of the targeting flag_word (`0xcecac0`), per the byte-verified bit table
-/// (`wave-cast.md` "flag_word bits"). Only the bits the resolver consumes are named.
+/// `TARGET_FLAG_*` bits of the targeting flag_word (`0xcecac0`), as `ArmCast 0x6e5250` sets them
+/// and `BindTarget 0x6e5b40` consumes them. Only the bits the resolver consumes are named.
 const TF_UNIT: u16 = 0x0002;
 const TF_UNIT_RAID: u16 = 0x0004;
 const TF_UNIT_PARTY: u16 = 0x0008;
@@ -240,7 +240,11 @@ pub(crate) struct CastTargeting<'w, 's> {
     reputations: Res<'w, Reputations>,
     self_transform: Query<'w, 's, &'static Transform, With<SelfPlayer>>,
     transforms: Query<'w, 's, &'static Transform>,
-    player: Res<'w, crate::player::Player>,
+    /// `Option`: the body exists only in world, and `HandleCastResult` is a one-shot handler
+    /// that must fetch its parameters on any built client (decision 2330 — the reply casts the
+    /// `modalNextSpell` chain through the ladder). No body, no movement: the moving gate passes
+    /// and the server stays the net, as for every other untestable input.
+    player: Option<Res<'w, crate::player::Player>>,
 }
 
 impl CastTargeting<'_, '_> {
@@ -277,7 +281,7 @@ impl CastTargeting<'_, '_> {
                 .next()
                 .and_then(|s| s.0.player_inv_slot(EQUIPMENT_SLOT_MAINHAND))
                 .filter(|&g| g != 0),
-            self_move_flags: self.player.move_flags(),
+            self_move_flags: self.player.as_deref().map_or(0, |p| p.move_flags()),
         }
     }
 }
@@ -293,6 +297,13 @@ const EQUIPMENT_SLOT_MAINHAND: u8 = 15;
 #[derive(bevy::prelude::Resource)]
 pub(crate) struct AutoSelfCast(pub(crate) bool);
 
+/// `autoSelfCast`'s change callback (decision 2303): a flag.
+pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut auto: ResMut<AutoSelfCast>) {
+    if ev.is("autoSelfCast") {
+        auto.0 = ev.flag();
+    }
+}
+
 impl Default for AutoSelfCast {
     fn default() -> Self {
         Self(true)
@@ -300,8 +311,8 @@ impl Default for AutoSelfCast {
 }
 
 /// The cast-arm's flag_word seed + implicit-target switch (`0x6e5250` @ `6e525a`–`6e52ef`):
-/// `flag_word = Targets`, then one arm keyed on `EffectImplicitTargetA[0]`. The full arm map,
-/// byte-verified (`wave-cast.md`): 1→clr bit10, 5→clr bit15, 6/53→set bit7, 16→ground-target,
+/// `flag_word = Targets`, then one arm keyed on `EffectImplicitTargetA[0]`. The full arm map:
+/// 1→clr bit10, 5→clr bit15, 6/53→set bit7, 16→ground-target,
 /// 21/45→set bit8, 23→set bit11, 25/63→set bit1, 26→set bit14, 35→set bit3, 57/61→set bit2;
 /// every other enum is the default no-op arm.
 pub(crate) fn cast_target_mask(def: &SpellDisplay) -> u16 {
@@ -329,8 +340,8 @@ pub(crate) fn cast_target_mask(def: &SpellDisplay) -> u16 {
 /// commits only on a fully-cleared word.
 ///
 /// Relation stand-ins, named: assist (`CanAssist 0x6066f0`) is approximated as reaction rank ≥ 4
-/// (friendly) — the same `UnitReaction` core the ring and `can_attack` share — pending the §5 pin
-/// in flight; party/raid (`0x606c20`/`0x606d20`) accept only the player himself until groups
+/// (friendly) — the same `UnitReaction` core the ring and `can_attack` share — until CanAssist
+/// is pinned; party/raid (`0x606c20`/`0x606d20`) accept only the player himself until groups
 /// exist; the corpse predicate (`0x6067d0`) is "assistable and health 0".
 fn clear_satisfied_bits(word: u16, is_self: bool, rel: &TargetRelations) -> u16 {
     let mut word = word;
diff --git a/crates/benilla-app/src/cooldowns.rs b/crates/benilla-app/src/spell/cooldowns.rs
similarity index 96%
rename from crates/benilla-app/src/cooldowns.rs
rename to crates/benilla-app/src/spell/cooldowns.rs
index 0400e5d7..dd38ed60 100644
--- a/crates/benilla-app/src/cooldowns.rs
+++ b/crates/benilla-app/src/spell/cooldowns.rs
@@ -1,6 +1,6 @@
 //! The player's cooldown store — a mirror of the client's `SpellHistory` list (decision 0137
-//! phase 4). Every law here is the byte-verified mechanism from wow-re `wave-cooldown.md` /
-//! `wave-handlers.md` (the SPELLHISTORY node ops `0x6e12c0`/`0x6e13e0`/`0x6e1630`/`0x6e1790`,
+//! phase 4). Every law here is the client's own mechanism (the SPELLHISTORY node ops
+//! `0x6e12c0`/`0x6e13e0`/`0x6e1630`/`0x6e1790`,
 //! `StartCooldown 0x6e2c60`, `StartGlobalCooldown 0x6e2de0`, and the SMSG handlers
 //! `0x6e9460`/`0x6e95d0`/`0x6e9670`/`0x6e9730`), transcribed onto `Instant`/`Duration`:
 //!
@@ -12,8 +12,7 @@
 //!   queried spell against all three: nodes matching its id (+ cast item), nodes matching its
 //!   category, and nodes whose GCD category matches its `startRecoveryCategory` — the mechanism
 //!   that spreads one cast's GCD onto every other button. The longest remaining wins.
-//! - **Who starts what** (byte-VERIFIED, the 2026-07-10 wow-re §5 + follow-up,
-//!   `action-button-state-api.md` §7 / `wave-handlers.md` ADDENDUM): the GCD starts locally at
+//! - **Who starts what**: the GCD starts locally at
 //!   cast-send (`0x6e58fb`); the spell's own recovery is client-computed from `Spell.dbc` and
 //!   inserted when **our own `SMSG_SPELL_GO`** arrives (`HandleSpellGo`'s self-insert tail
 //!   `0x6e8498`/`0x6e8566`, anchored at the receive-time, onHold from Attributes bit 25);
@@ -53,7 +52,7 @@ impl Timer {
     }
 }
 
-/// One SPELLHISTORY record (wow-re `wave-cooldown.md` `0x6e12c0`'s node, byte-for-byte in
+/// One SPELLHISTORY record (`0x6e12c0`'s node, byte-for-byte in
 /// spirit: spellID/itemID/recovery pair/category+pair/onHold/GCD pair).
 #[derive(Clone, Debug)]
 struct Record {
@@ -168,7 +167,7 @@ impl Cooldowns {
     /// The insert primitive (`AddCooldown 0x6e12c0`): nothing to track → no-op; else **append a
     /// new record**. The client never matches-by-id here — its "reuse" scan is free-list node
     /// recycling, an allocator detail (no `[node+8]==spellId` compare anywhere in `0x6e12c0`'s
-    /// body, wow-re `wave-cooldown.md`), where every other op in the family explicitly walks
+    /// body), where every other op in the family explicitly walks
     /// "each node matching id". So one spell can hold SEVERAL records at once — and must: the
     /// cast-send GCD arm (`StartGlobalCooldown`, a gcd-only node) and the GO self-insert
     /// (`StartCooldown`, which passes `gcd=0,0`) are separate nodes. The find-and-replace this
@@ -232,8 +231,8 @@ impl Cooldowns {
     /// No GCD here — that's [`Self::start_gcd`]'s separate insert.
     ///
     /// `ranged_attack_time_ms` is the ranged-shot pad (the category scaler `0x6e2b60`'s
-    /// `add [categoryRecoveryTime], [player+0x110]+0x1e8`, byte-verified — wow-re
-    /// `ranged-cooldown-sweep.md`, decision 0378): the caster's live `UNIT_FIELD_RANGEDATTACKTIME`
+    /// `add [categoryRecoveryTime], [player+0x110]+0x1e8`, decision 0378): the caster's live
+    /// `UNIT_FIELD_RANGEDATTACKTIME`
     /// when [`SpellDisplay::ranged_speed_cooldown`], else 0. It folds into the CATEGORY timer —
     /// the Throw/wand-Shoot sweep with all-zero DBC recovery — and rides the insert even for
     /// category 0 (Auto Shot), where no read surfaces it (the client's SpellCategory[0]-is-NULL
@@ -404,7 +403,7 @@ impl Cooldowns {
 
     /// **The list belongs to the world session, not to the process** (decision 2116) — the
     /// session-end clear every other net-backed store already had
-    /// ([`crate::net::apply::session::disconnected`]).
+    /// ([`crate::net::session::disconnected`]).
     ///
     /// `SMSG_INITIAL_SPELLS` carries the WHOLE set of cooldowns still running, at every world
     /// entry, and [`Self::seed_initial`] appends (the reference's `AddCooldown 0x6e12c0` never
@@ -562,14 +561,14 @@ impl Cooldowns {
     }
 
     /// The client's `IsSpellOnCooldown 0x6e1690` — an **"has an on-hold (not-yet-started)
-    /// record"** predicate, NOT a general on-cooldown test (the corrected decode, wow-re
-    /// `gcd-power-gate.md` §3: both legs return 1 only when the matched node's onHold byte is
+    /// record"** predicate, NOT a general on-cooldown test (both legs return 1 only when the
+    /// matched node's onHold byte is
     /// set; `+0x28`/`+0x2c` are never referenced and no time source is called). Its reference
     /// consumers are all bit25/cooldown-on-event gates: the usable walk's grey-while-parked leg
     /// (`0x6e3fb1`) — ours — and the cast-fail on-hold revert.
     ///
-    /// **It is item-keyed, and that is not cosmetic** (wow-re `action-button-state-api.md` §2c.4,
-    /// 2026-09-13). The node walk's spell-id leg is `node+0x08 == spellId && node+0x0c == itemId`
+    /// **It is item-keyed, and that is not cosmetic**. The node walk's spell-id leg is
+    /// `node+0x08 == spellId && node+0x0c == itemId`
     /// (`6e173f`/`6e1744`), and `0x6e2fc0` — the action bar's ITEM gate, and the **sole** consumer
     /// of the item-keyed form image-wide — passes the item ENTRY as that second argument
     /// (`6e3037 push esi`). Every other caller passes `0` (`0x6e2fa0`'s `push 0` at `6e2fa9`).
@@ -593,8 +592,8 @@ impl Cooldowns {
 
     /// The cast validator's FIRST rung (`0x6094f0` @ `0x609565` → `0x6e2ea0` → the getter): a
     /// press is refused "not ready" iff [`Self::info`] reads ANY remaining — the spell's own
-    /// pair, a category match, or the GCD leg, one query (wow-re `gcd-power-gate.md` §1.3/§2,
-    /// the §5 that closed 0379's INTERIM). The GCD refusal predicate is therefore the GETTER's:
+    /// pair, a category match, or the GCD leg, one query (decision 0948, which closed 0379's
+    /// INTERIM). The GCD refusal predicate is therefore the GETTER's:
     /// `pressed.startRecoveryCategory == node.startRecoveryCategory && node.time != 0` — the
     /// pressed spell's own `startRecoveryTime` is never consulted (a `{cat≠0, time=0}` press —
     /// the scroll spells — IS refused during the GCD), and Attack / profession presses can never
@@ -613,8 +612,8 @@ impl Cooldowns {
         self.info(spell_id, item_entry, spell, now).remaining_ms > 0
     }
 
-    /// The per-spell read (`GetCooldownInfo 0x6e13e0`, the complete §5 match law — wow-re
-    /// `gcd-power-gate.md` §2): resolve `spell_id` (as cast from `item_entry`, `0` for a plain
+    /// The per-spell read (`GetCooldownInfo 0x6e13e0`, the complete match law): resolve
+    /// `spell_id` (as cast from `item_entry`, `0` for a plain
     /// spell) against EVERY record, three legs each, **longest remaining wins**:
     ///
     /// - **head exclusion**: `Effect[0] ∈ {ATTACK, TRADE_SKILL}` reads cold unconditionally
@@ -736,7 +735,7 @@ mod tests {
         let ch = cds.info(100, 0, Some(&charge()), mid);
         assert_eq!(ch.remaining_ms, 0, "no startRecoveryCategory — no GCD read");
 
-        // …and the press gate reads it — the ONE getter is the refusal (0948's §5 closed
+        // …and the press gate reads it — the ONE getter is the refusal (0948 closed
         // 0379's INTERIM: there is no separate GCD site); the corrected `0x6e1690` on-hold
         // predicate stays false (no parked record).
         assert!(cds.not_ready(133, 0, Some(&fireball()), mid));
@@ -896,7 +895,7 @@ mod tests {
         );
     }
 
-    /// **`0x6e1690`'s item-keyed form** (wow-re `action-button-state-api.md` §2c.4). The node
+    /// **`0x6e1690`'s item-keyed form**. The node
     /// walk's spell-id leg is `node+0x08 == spellId && node+0x0c == itemId`, and the action bar's
     /// ITEM gate `0x6e2fc0` is the sole caller image-wide that passes a **non-zero** `itemId` —
     /// the item ENTRY, at `6e3037 push esi`. Our store keys an item's record `(use_spell, entry)`
@@ -1081,10 +1080,10 @@ mod tests {
         assert_eq!(read1, read2, "the projected start IS the settled start");
     }
 
-    /// The GCD refusal predicate, corrected by the 0948 §5 (`gcd-power-gate.md` §2.1): a press
+    /// The GCD refusal predicate, corrected by 0948 (the getter's GCD leg `6e15cc`): a press
     /// is refused iff its `startRecoveryCategory` EQUALS the armed node's (node time ≠ 0) — the
     /// pressed spell's own `startRecoveryTime` is never consulted. So a `{133, 0}` press (the
-    /// scroll spells) IS refused during the GCD (the pre-§5 predicate passed it), a `{0, 0}`
+    /// scroll spells) IS refused during the GCD (the old predicate passed it), a `{0, 0}`
     /// press (Attack shape, Charge) flows, and the lock lifts at expiry.
     #[test]
     fn a_running_gcd_locks_presses_by_category_equality_alone() {
@@ -1102,7 +1101,7 @@ mod tests {
             "the spam press 200 ms later is locked — refused, never sent, the GCD lives"
         );
         // A {133, 0} press — Scroll of Armor's shape — is REFUSED: the node's category matches
-        // and only the NODE's time matters (the §5's corrected divergence).
+        // and only the NODE's time matters (the corrected divergence).
         let scroll = spell(0, 0, 0, (133, 0), 0x10000);
         assert!(
             cds.not_ready(8091, 0, Some(&scroll), mid),
@@ -1173,7 +1172,7 @@ mod tests {
         assert_eq!(cds.info(133, 0, Some(&fireball()), t0).remaining_ms, 0);
     }
 
-    /// The ranged-shot pad (decision 0378, wow-re `ranged-cooldown-sweep.md`): a Throw-shaped
+    /// The ranged-shot pad (decision 0378, `0x6e2b60`): a Throw-shaped
     /// spell (category 76, all-zero DBC recovery) sweeps the weapon's attack time via its
     /// CATEGORY timer, and refuses a recast within it.
     #[test]
diff --git a/crates/benilla-app/src/spell/inflight.rs b/crates/benilla-app/src/spell/inflight.rs
new file mode 100644
index 00000000..9af50e06
--- /dev/null
+++ b/crates/benilla-app/src/spell/inflight.rs
@@ -0,0 +1,1205 @@
+//! **The in-flight slot** — the spell's own cast state, in the reference's terms: the pending
+//! cast request (`SPELLCAST` @`0xceac48` + the inflight id `0xceca88` → [`PendingCast`]), the
+//! queued on-next-swing strike ([`QueuedMeleeSpell`], our second slot for what the reference
+//! keeps in the one id — [`Inflight`] re-joins them), the running channel (`0xceac58` →
+//! [`ActiveChannel`]), the auto-repeat key (`0xceac30` → [`AutoRepeatActive`]) — and the local
+//! abort that ends a cast the same tick a move, a jump or Esc lands (`AbortCast 0x6e4940` →
+//! [`local_self_cancel`]).
+//!
+//! Written by the spell's packet handlers ([`super::net`]), the one cast path
+//! ([`super::CastLadder`]) and the attack seams; read by the feeds — the cast bar
+//! (`crate::ui_cast`), the action state, the target chain. Until decision 2328 this lived in
+//! `ui_cast` and `ui_action`; it is the state 2265 §A7 named as having no owner.
+
+use std::time::{Duration, Instant};
+
+use bevy::prelude::*;
+
+use benilla_ui::script::UiScript;
+
+use crate::creature_anim::{CastEvent, CastEventKind, Casting, PlaySeq};
+use crate::net::{ClientCommand, GuidIndex, NetCommands, SelfGuid};
+use crate::ui_action::Spells;
+use crate::ui_cast::{CastBarEdge, CastBarFeed};
+
+/// Provisional in-flight window armed at send, before `SMSG_SPELL_START` names the real cast time.
+/// It only has to outlast the send→START round trip; an instant, whose `SMSG_SPELL_GO` clears the
+/// guard first, never reaches it. Generous on purpose — the resolution packets do the real clearing.
+const SEND_PROVISIONAL: Duration = Duration::from_secs(5);
+
+/// The same provisional for an **item** use's cast ([`PendingCast::arm_item`]) — deliberately much
+/// tighter, because the two arms have different worst cases *on this wire*. Every
+/// `CMSG_CAST_SPELL` vmangos accepts is answered (`Spell::SendCastResult` on any rejection,
+/// `SMSG_SPELL_START`/`GO` otherwise), so a spell's guard is always cleared by a packet and
+/// [`SEND_PROVISIONAL`] never actually governs. `CMSG_USE_ITEM` has legs that answer with
+/// `SMSG_INVENTORY_CHANGE_FAILURE` and **no cast result at all** — `HandleUseItemOpcode`'s
+/// equip-error gates (`CanUseItem`, the in-combat non-combat-spell refusal, item-not-found) —
+/// and there the provisional IS the safety net, so it has to be short enough that a silently
+/// refused use cannot lock casting out for long. It only ever covers the send→`SMSG_SPELL_START`
+/// window anyway: [`PendingCast::refine`] stretches the guard to the server's real cast time the
+/// moment START names it, so a use that *does* become a cast is guarded for its whole length.
+const ITEM_SEND_PROVISIONAL: Duration = Duration::from_millis(1_500);
+
+/// Pushback slack added to the server's cast time at `SMSG_SPELL_START`, so a cast the server
+/// delays (`SMSG_SPELL_DELAYED`) still guards past its stretched end.
+const CAST_SLACK: Duration = Duration::from_secs(2);
+
+/// Our own outstanding cast — the client's optimistic in-flight guard, and the fix for the
+/// spam-cancel bug. `TryCast 0x6e4b60` refuses to send a second
+/// `CMSG_CAST_SPELL` while `IsCasting 0x6e3d30` (the inflight-spell-id `0xceca88`) is set — the
+/// same-spell press bails **silently** at `6e4d43`; a different spell hits the
+/// `[SpellRec+0x18] & 0x404` gate at `6e4d97`: when the *inflight* rec lacks those bits (an
+/// ordinary cast — Fireball is `0x10000`), it errors 0x61 without sending; when the inflight IS
+/// on-next-swing (a queued Heroic Strike), the new cast passes and nests around it (exactly
+/// `0x404`, on the inflight rec, no channel leg: Slam mid-cast blocks Battle Shout). In our
+/// model the on-next-swing class never occupies this guard at all — it arms [`QueuedMeleeSpell`]
+/// instead — so this guard only ever holds ordinary casts and the gate needs no attribute test.
+/// Ours was server-driven: every mashed key fired a *duplicate* cast, the
+/// server rejected the dupe with `SMSG_CAST_RESULT` failure, and that turned the running cast's bar
+/// red while the original completed later. This marker drops the duplicate at the source, exactly
+/// as the client does.
+///
+/// It is **optimistic** — armed the instant we send, not when the server's `SMSG_SPELL_START`
+/// echoes back — because the spam lands during that round trip. Cleared by the cast's resolution
+/// (`SMSG_SPELL_GO` / a failing `SMSG_CAST_RESULT` / `SMSG_SPELL_FAILED_OTHER`), spell-id-keyed like
+/// the `Casting` reap — and by the local self-cancel directly ([`local_self_cancel`], the
+/// client's `AbortCast 0x6e4940` mirrored since 0444). `deadline` is the safety net for a
+/// resolution that goes missing on the wire: armed generously and tightened to the real cast
+/// time once `SMSG_SPELL_START` names it.
+#[derive(Resource, Default)]
+pub(crate) struct PendingCast(Option<PendingCastState>);
+
+struct PendingCastState {
+    spell_id: u32,
+    deadline: Instant,
+    /// Does this record **guard** — i.e. does it refuse the next press, light the in-flight ring,
+    /// and gate the by-name walk? True for the classes benilla lets occupy the guard: ordinary
+    /// casts and item uses.
+    ///
+    /// The reference has no such flag, because it has no such split: `[0xceca88]` is written for
+    /// **every** committed cast (`0x6e5026 call 0x6e4ad0` inside TryCast) and the *gate* does the
+    /// discriminating instead, on the inflight rec's `Attributes & 0x404` at `6e4d97`. Ours grew
+    /// up the other way round — the guard is armed only for the classes it refuses on, so a
+    /// ranged shot was never recorded as committed **at all**.
+    ///
+    /// That gap is what shipped B280 broken twice: the `modalNextSpell` chain
+    /// (`super::net`'s `cast_result`) has to answer the reference's `0x6e7408 cmp
+    /// ecx,[0xceca88]` — "is this reply for the cast I just sent?" — and every hunter shot is
+    /// `Attributes & 0x2` ranged, so the answer was always no and the chain never fired in play.
+    /// The flag closes it without touching the three consumers that were right: the record is now
+    /// armed for every commit ([`PendingCast::committed`] reads it), and `guards` keeps
+    /// [`PendingCast::in_flight`] / [`PendingCast::current`] answering exactly what they did.
+    guards: bool,
+}
+
+impl PendingCast {
+    /// Whether a **guarding** cast we sent is still outstanding (unresolved and inside its safety
+    /// deadline) — the refusal's own question. A ranged shot is committed but does not guard.
+    pub(crate) fn in_flight(&self, now: Instant) -> bool {
+        self.0
+            .as_ref()
+            .is_some_and(|p| p.guards && now < p.deadline)
+    }
+
+    /// **The reference's `[0xceca88]` proper** — the id of the cast we last committed and have not
+    /// yet had a resolution for, whatever its class. This is what `HandleCastResult 0x6e7330`
+    /// tests at `0x6e7408` before it reads `modalNextSpell`, and the only read that must see a
+    /// ranged shot. Everything else about the record is unchanged; see [`PendingCastState::guards`]
+    /// for why the two questions are separate fields here and one global there.
+    pub(crate) fn committed(&self, now: Instant) -> Option<u32> {
+        self.0
+            .as_ref()
+            .filter(|p| now < p.deadline)
+            .map(|p| p.spell_id)
+    }
+
+    /// The outstanding cast's spell id, if one is in flight — the app-side mirror of the client's
+    /// current-cast read (`0xceca88`), which `IsCurrentAction`'s checked state keys on (decision
+    /// 0137 phase 4).
+    pub(crate) fn current(&self, now: Instant) -> Option<u32> {
+        self.0
+            .as_ref()
+            .filter(|p| p.guards && now < p.deadline)
+            .map(|p| p.spell_id)
+    }
+
+    /// Arm on a fresh send — the optimistic `0xceca88` write at the client's cast-send. `guards`
+    /// says whether this class also occupies the refusal ([`PendingCastState::guards`]): ordinary
+    /// casts do, a ranged shot is recorded and does not.
+    pub(crate) fn arm(&mut self, spell_id: u32, now: Instant, guards: bool) {
+        self.0 = Some(PendingCastState {
+            spell_id,
+            deadline: now + SEND_PROVISIONAL,
+            guards,
+        });
+    }
+
+    /// Arm the guard on an **item** use's send. The reference has no separate item-cast slot: the
+    /// item-use dispatcher's cast tail (`CGItem::Use 0x5d8d00` @ `0x5d9258`) calls `0x6e5a90`,
+    /// whose entire 54-byte body is `call 0x6e4b60` — `TryCast` itself (the action bar's SPELL
+    /// route takes the same `0x6e5a90` → `CastSpell 0x6e4b60`). So an item use writes
+    /// the SAME inflight id (`0xceca88`) and is refused by the same IsCasting gate — which is why
+    /// [`crate::ui_items::send_item_use`] runs both. Differs from [`PendingCast::arm`] only in the
+    /// deadline ([`ITEM_SEND_PROVISIONAL`], whose doc is the why).
+    pub(crate) fn arm_item(&mut self, spell_id: u32, now: Instant) {
+        self.0 = Some(PendingCastState {
+            spell_id,
+            deadline: now + ITEM_SEND_PROVISIONAL,
+            guards: true,
+        });
+    }
+
+    /// Tighten the deadline to the server's real cast time once `SMSG_SPELL_START` names it.
+    pub(crate) fn refine(&mut self, cast_time_ms: u32, now: Instant) {
+        if let Some(p) = &mut self.0 {
+            p.deadline = now + Duration::from_millis(u64::from(cast_time_ms)) + CAST_SLACK;
+        }
+    }
+
+    /// Push the deadline out by a pushback (`SMSG_SPELL_DELAYED`), so the guard keeps holding past
+    /// the stretched cast end. Extends from whichever is later (the current deadline or now), so a
+    /// deadline already lapsed from an under-estimate still re-arms.
+    pub(crate) fn delay(&mut self, delay_ms: u32, now: Instant) {
+        if let Some(p) = &mut self.0 {
+            p.deadline = p.deadline.max(now) + Duration::from_millis(u64::from(delay_ms));
+        }
+    }
+
+    /// Clear the guard when the resolving spell is our outstanding one (spell-id-keyed, like the
+    /// `Casting` reap — a triggered proc's `SMSG_SPELL_GO` mid-cast must not open the gate early).
+    pub(crate) fn clear_if(&mut self, spell_id: u32) {
+        if self.0.as_ref().is_some_and(|p| p.spell_id == spell_id) {
+            self.0 = None;
+        }
+    }
+}
+
+/// Our own queued **on-next-swing** spell (Heroic Strike, Cleave — `Attributes & 0x404`) — the
+/// melee-slot half of the client's cast tracking. In the reference the queued spell *occupies*
+/// the inflight id (`0xceca88`) until the swing fires it, and the already-casting refusal at
+/// `6e4d97` exempts new casts because the inflight rec has the `0x404` bits — so a queued Heroic
+/// Strike never blocks Rend, and the new cast nests around it (`PushPopNestedCast 0x6e4ad0`
+/// restores the queued id when the nested cast resolves). We model the
+/// same observable with a second slot instead of the push/pop pair: [`PendingCast`] keeps
+/// ordinary casts, this keeps the melee queue, and the checked ring reads both (the ref's
+/// `IsCurrentAction 0x4e53a0` leg — spell == inflight — holds through the nesting either way, minus
+/// the ref's one-RTT un-check blink while the nested cast displaces the slot).
+///
+/// **Deadline-less, wire-cleared** — like the ref's inflight id, which no timer touches. The
+/// clear set is deliberately wider than the ref's: the ref clears inflight/saved ONLY on a
+/// matching `SMSG_CAST_RESULT` (`0x6e7330`;
+/// the GO handler never touches `0xceca88`) — but vmangos never sends an OK `CAST_RESULT` at
+/// all, so on our wire the resolution is `SMSG_SPELL_GO` when the swing fires the strike, and a
+/// failing `CAST_RESULT` + `SPELL_FAILED_OTHER` when it dies (vmangos `Spell::cancel` on the
+/// PREPARING melee slot sends both — target death, manual cancel, replacement). We clear on any
+/// of the three, id-keyed: identical observable where `0x130` does arrive, correct where it
+/// never does. Re-arming replaces silently: the server holds a single `CURRENT_MELEE_SPELL`
+/// slot. Re-pressing the queued spell itself is the ref's silent same-spell bail
+/// (`6e4d43`: debug-log, `xor al,al`, no CMSG, no error): 1.12 has no re-press-to-unqueue. The
+/// real un-queue is the StopAttack chain (`0x5ecac0` → `CancelQueuedCast 0x6e6f30`, sending
+/// `CMSG_ATTACKSTOP` + `CMSG_CANCEL_CAST`), reached by /stopattack, the Attack-button toggle,
+/// **an auto-repeat press** (`0x6e5976`), target change/death, mount, interact — never movement.
+/// That chain is [`crate::creature_anim::stop_attack_local`], and the auto-repeat arm inside
+/// [`crate::spell::cast_send`]'s commit runs it whole: starting Auto Shot un-queues the
+/// strike, which is what darkens its checked ring. Every attack edge reaches that seam since
+/// 1044 — the Attack toggle, a target switch, a click-off, the ring's death teardown.
+///
+/// **Escape is the other route, and it is not that chain at all** (1049). In the reference a
+/// queued strike simply *is* the inflight spell, so `Script::SpellStopCasting 0x6e6e80`'s plain
+/// `IsCasting 0x6e3d30` branch cancels it like any cast — no melee-specific code anywhere in it.
+/// [`Inflight`] is where our two slots are re-joined for that reader.
+#[derive(Resource, Default)]
+pub(crate) struct QueuedMeleeSpell(Option<u32>);
+
+impl QueuedMeleeSpell {
+    /// The queued spell's id, if one is waiting on the next swing — what the checked ring and
+    /// the re-press bail read.
+    pub(crate) fn current(&self) -> Option<u32> {
+        self.0
+    }
+
+    /// Queue a fresh on-next-swing send (replacing any prior queue — the server's single slot).
+    pub(crate) fn arm(&mut self, spell_id: u32) {
+        self.0 = Some(spell_id);
+    }
+
+    /// Clear on the wire resolution (`SMSG_SPELL_GO` / a failing `SMSG_CAST_RESULT` /
+    /// `SMSG_SPELL_FAILED_OTHER`), spell-id-keyed like every reap.
+    pub(crate) fn clear_if(&mut self, spell_id: u32) {
+        if self.0 == Some(spell_id) {
+            self.0 = None;
+        }
+    }
+}
+
+/// What the reference's single inflight spell id (`0xceca88`) holds — as our **two** slots see it.
+///
+/// The client has one slot, with one save beneath it for the nesting. An ordinary cast and a
+/// queued on-next-swing strike both live in `0xceca88`, which is exactly why `IsCasting 0x6e3d30`
+/// — a bare `ceca88 != 0` — answers true for either, and why `AbortCast 0x6e4940` cancels
+/// whichever is there without ever asking which kind it was. [`PendingCast`] and
+/// [`QueuedMeleeSpell`] split that one slot in two (its doc says why), which leaves every reader
+/// of *"what is in flight"* to re-join them — and the one reader that forgot was the Esc ladder,
+/// which is the bug decision 1049 fixes. So the join gets a name, once, here.
+///
+/// **The order is the reference's nesting, not a preference.** An ordinary cast started over a
+/// queued strike is allowed through `TryCast`'s already-casting refusal precisely because the
+/// inflight rec has `Attributes & 0x404` (`0x6e4d97`/`0x6e4dbe`), and it *pushes*
+/// (`PushPopNestedCast 0x6e4ad0` @ `0x6e5026`): the cast becomes `0xceca88`, the strike the save
+/// in `0xcecaa8`. `AbortCast` cancels the cast and pops the strike back up — so the cast dies on
+/// the first Esc and the strike on the second. Reading `PendingCast` first reproduces that
+/// without our needing the push/pop pair.
+///
+/// One knowing divergence there, weighed in decision 1058: the ref's pop (`0x6e4b2c`–`0x6e4b4e`)
+/// *reads* `0xcecaa8` and never writes it, so a
+/// second Esc re-asserts the same strike locally and only the server echo converges it. We have
+/// no separate save slot to go stale, so ours clears. The two agree everywhere it shows: in the
+/// un-nested case the ref's pop reads a zero save and clears too, and in the nested case vmangos
+/// drops the melee slot on press **1** regardless (`HandleCancelCastOpcode` is spellId-blind
+/// about `CURRENT_MELEE_SPELL`), so both clients converge off that echo. Reproducing the
+/// re-assert would mean modelling `0xcecaa8` as a third slot to hold a value that is stale by
+/// construction, for a window one localhost round trip wide.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum Inflight {
+    /// An ordinary cast — ours to send-guard, to paint a bar for, and to reap.
+    Cast(u32),
+    /// A queued on-next-swing strike waiting for the swing. No bar ever opened for it and it
+    /// holds no [`Casting`], so cancelling it is the wire message and the slot, nothing else.
+    Strike(u32),
+}
+
+impl Inflight {
+    /// The spell id in the slot — what a cancel names on the wire, either way.
+    pub(crate) fn spell_id(self) -> u32 {
+        match self {
+            Self::Cast(id) | Self::Strike(id) => id,
+        }
+    }
+}
+
+/// Resolve the reference's inflight slot from our two — see [`Inflight`] for the order and the
+/// why. `started` is the self [`Casting`] spell id, which covers a cast that never armed the send
+/// guard (an item use) exactly as the ref's one id covers it.
+pub(crate) fn inflight(
+    pending: &PendingCast,
+    queued_melee: &QueuedMeleeSpell,
+    started: Option<u32>,
+    now: Instant,
+) -> Option<Inflight> {
+    pending
+        .current(now)
+        .or(started)
+        .map(Inflight::Cast)
+        .or_else(|| queued_melee.current().map(Inflight::Strike))
+}
+
+/// Slack past the server-named channel end, so a lost/late `MSG_CHANNEL_UPDATE(0)` can't pin the
+/// checked ring on forever — the natural end clears through the deadline instead.
+const CHANNEL_SLACK: Duration = Duration::from_secs(2);
+
+/// Our own running channel — the app-side mirror of the client's current-channel id (`0xceac58`,
+/// read live-gated by the channeling word: `IsCurrentAction 0x4e53a0`'s channel leg — a
+/// channeled spell's button stays checked while its channel
+/// runs). Set at `MSG_CHANNEL_START`, refreshed by nonzero `MSG_CHANNEL_UPDATE`s, cleared by the
+/// `UPDATE(0)` that ends both the natural finish and the interrupt.
+#[derive(Resource, Default)]
+pub(crate) struct ActiveChannel(Option<(u32, Instant)>);
+
+impl ActiveChannel {
+    /// The running channel's spell id, if one is live.
+    pub(crate) fn current(&self, now: Instant) -> Option<u32> {
+        self.0
+            .filter(|&(_, until)| now < until)
+            .map(|(spell, _)| spell)
+    }
+
+    /// `MSG_CHANNEL_START`: open the window for the named duration (+ slack).
+    pub(crate) fn start(&mut self, spell_id: u32, duration_ms: u32, now: Instant) {
+        self.0 = Some((
+            spell_id,
+            now + Duration::from_millis(u64::from(duration_ms)) + CHANNEL_SLACK,
+        ));
+    }
+
+    /// `MSG_CHANNEL_UPDATE`: `0` ends the channel; anything else re-times the window (pushback
+    /// shortens a channel, so the deadline moves in as well as out).
+    pub(crate) fn update(&mut self, remaining_ms: u32, now: Instant) {
+        if remaining_ms == 0 {
+            self.0 = None;
+        } else if let Some((_, until)) = &mut self.0 {
+            *until = now + Duration::from_millis(u64::from(remaining_ms)) + CHANNEL_SLACK;
+        }
+    }
+}
+
+/// The live auto-repeat spell — the client's autorepeat key `0xceac30` (written at the local
+/// cast-send `0x6e54f0` for `AttributesEx2 & 0x20` spells, cleared by
+/// `SMSG_CANCEL_AUTO_REPEAT`'s `0x6ea080` and by a matching cast-fail). Distinct from the sticky
+/// `creature_anim::AutoRepeatArmed` (the Load/Hold idle gate, never cleared): THIS one is what
+/// `IsAutoRepeatAction` and the button flash read, and it goes out when the shooting stops.
+#[derive(Resource, Default)]
+pub(crate) struct AutoRepeatActive(pub Option<u32>);
+
+/// ── The local self-cancel (decisions 0256 open item 2 / 0444 / 0445): move/jump/Esc mid-cast
+/// ends the cast **locally**, the same client tick — the app-side mirror of `AbortCast
+/// 0x6e4940`. The whole trigger chain: the `Script::Move*` keybind handlers funnel into the
+/// shared dispatcher
+/// `0x515090`, whose interrupt mask `0x10f0` = {forward, backward, strafe L/R, autorun-toggle}
+/// — turn (`0x100/0x200`) and pitch (`0x400/0x800`) are OUTSIDE the mask and never cancel —
+/// and `Script::Jump 0x513bd0` inlines the same gate. Both call `AbortCast(cl=0, dl=1,
+/// reason=0x1c)`: event **0x152 SPELLCAST_STOP** (the silent close — `cl=0` selects it;
+/// `0x153/0x154` need `cl!=0`) + `CMSG_CANCEL_CAST`. The server stays the safety net: vmangos's
+/// own movement interrupt (`Spell::update`'s 0.5-yd position delta) still kills anything we
+/// miss. The per-spell gates, byte-verified at the call sites (`f6 46 54 01` @`0x51511e`,
+/// `f6 42 5c 08` @`0x515175`; identities corroborated by vmangos `SpellDefines.h`):
+/// (Also the entry test of the cast-INITIATION moving gate — `ui_action::state`'s
+/// `cast_moving_refusal`, decision 0862 — which is a different mechanism from this self-cancel.)
+pub(crate) const SPELL_INTERRUPT_MOVEMENT: u32 = 0x1; // SpellRec+0x54 InterruptFlags (SPELL_INTERRUPT_FLAG_MOVEMENT)
+const CHANNEL_INTERRUPT_MOVING: u32 = 0x8; // SpellRec+0x5c ChannelInterruptFlags (AURA_INTERRUPT_MOVING_CANCELS)
+
+/// The controller's report that a cancel-worthy local move edge happened this frame — a
+/// *directional* start (forward/back/strafe: our wire-axis mirror of the verified `0x10f0`
+/// mask's flags) or a jump takeoff. The mask's fifth member, the autorun toggle, is dormant
+/// until benilla grows an autorun (0445). Written by `player::control` at the same spot the
+/// wire-axis transitions are computed, consumed (and cleared) by [`local_self_cancel`] next
+/// frame — one engine frame (~16 ms) from key to bar-kill, vs the server round trip (~150 ms+:
+/// the 0.5-yd delta has to accumulate before vmangos even notices).
+#[derive(Resource, Default)]
+pub(crate) struct LocalMoveStart(pub(crate) bool);
+
+/// Move/jump/Esc mid-cast: run the client's local cancel. One system for both triggers so the
+/// resolution can't drift between them:
+///
+/// - **the auto-repeat half (Esc only)** — the ref's branch order inside
+///   `Script::SpellStopCasting 0x6e6e80`: a
+///   running auto-repeat dies FIRST — [`crate::creature_anim::cancel_auto_repeat_local`], the
+///   client's `0x6ea080` (key + idle gates + nocked ammo + `CMSG_CANCEL_AUTO_REPEAT_SPELL`)
+///   — and SPENDS the press: one press stops one thing, the cast survives to the next.
+///   Movement never touches auto-repeat.
+/// - **the cast half** — clear [`PendingCast`], ship `CMSG_CANCEL_CAST`, reap the self
+///   `Casting` state + fire the `Fail` cast event (the anim/visual teardown `AbortCast` does via
+///   its stop-cast-anim tail), and push the **`Stop` + `Interrupted`** bar edges — the ref's
+///   own two-step (its local STOP, then the echo's red repaint) at RTT→0: red "Interrupted",
+///   held 1 s, the armed flash bursting white, then the fade (the transcribed `CastingBar.xml`
+///   machinery runs the rest). Esc bypasses the movement flags gate (the ref's
+///   `SpellStopCasting → AbortCast` has no `InterruptFlags` test — the gate belongs to the
+///   movement path alone).
+/// - **the channel half — MOVEMENT-ONLY** — ship `CMSG_CANCEL_CHANNELLING` and NOTHING else:
+///   the verified asymmetry (0445). Esc never reaches a channel — `0x6e6e80`'s whole callee
+///   closure never calls the channel canceler `0x6e9b70`, and its inflight gate (`0xceca88`)
+///   is already 0 mid-channel (the launch `CAST_RESULT(OKAY)` clears it at `0x6e7408`): the
+///   vanilla "/stopcasting can't stop a channel" quirk, kept faithfully (0454). The ref's
+///   `0x6e9b70` fires no FrameScript event and clears no
+///   local state — the channel bar closes on the server's `SMSG_CHANNEL_UPDATE(0)`
+///   (`0x6e75f0`), which also clears [`ActiveChannel`] through the normal wire path (its slack
+///   deadline self-heals a lost packet).
+///
+/// Why `Interrupted` when the client's own event is VERIFIED as the silent `0x152` STOP (every
+/// self-cancel caller passes `cl=0`)? Because the REF'S NET OBSERVABLE is the red bar — the
+/// director's falsifier, decision 0449, now pinned end to end (0454): vmangos `Spell::cancel`
+/// answers the cancel with `SMSG_SPELL_FAILED_OTHER` and then a failing `SMSG_CAST_RESULT`
+/// reason 0x23 (`SPELL_FAILED_INTERRUPTED`, counted against the 1.12.1 build guards), the
+/// client routes a failing result through `HandleCastFailed 0x6e1a00`, and reasons
+/// {0x23,0x24} select FrameScript **0x154 SPELLCAST_INTERRUPTED** — red, "Interrupted"
+/// (GlobalStrings-exact), `holdTime = now + 1 s`. Our bar-edge producers are KEYED to the
+/// self `Casting` (the 0137/0256 law that stops a proc's failure repainting the bar), and
+/// this cancel's reap removes it — so the echo can't do the repainting here. The local
+/// `Stop` + `Interrupted` pair replays the ref's exact sequence at RTT→0 through our keyed
+/// architecture; the reap then keeps the echo idempotent (re-clears open guards, shows the
+/// red error line, touches no bar). On-screen: the 1 s hold + ~25 bar ticks of flash+fade —
+/// ~1.9 s in the reference bottle (whose `Config.wtf` caps `maxfps` at 30, and the ref steps
+/// alpha PER TICK), the director's observed "2–3 s"; our transcription normalizes those steps
+/// to the same 30 Hz reference tick so the tail matches at any render rate (`CastingBar.xml`).
+pub(super) fn local_self_cancel(
+    script: Option<NonSendMut<UiScript>>,
+    mut moved: ResMut<LocalMoveStart>,
+    mut pending: ResMut<PendingCast>,
+    mut queued_melee: ResMut<QueuedMeleeSpell>,
+    channel: Res<ActiveChannel>,
+    mut auto_repeat: ResMut<AutoRepeatActive>,
+    mut feed: ResMut<CastBarFeed>,
+    spells: Option<Res<Spells>>,
+    net: Res<NetCommands>,
+    self_guid: Res<SelfGuid>,
+    index: Res<GuidIndex>,
+    casting: Query<&Casting>,
+    mut cast_events: MessageWriter<CastEvent>,
+    mut play_seq: ResMut<PlaySeq>,
+    mut ecs: Commands,
+) {
+    let esc = match script {
+        Some(mut s) => s.take_spell_stop(),
+        None => false,
+    };
+    let moved = std::mem::take(&mut moved.0);
+    if !esc && !moved {
+        return;
+    }
+    let now = Instant::now();
+    let self_e = self_guid.0.as_ref().and_then(|g| index.0.get(g)).copied();
+    // The Esc press stops ONE thing, auto-repeat first — the ref's branch order (`0x6e6e80`).
+    let esc = if esc && auto_repeat.0.is_some() {
+        if *crate::net::CAST_TRACE {
+            info!("cast-trace: LOCAL auto-repeat self-cancel (esc), CMSG_CANCEL_AUTO_REPEAT_SPELL");
+        }
+        crate::creature_anim::cancel_auto_repeat_local(self_e, &mut auto_repeat, &mut ecs, &net);
+        false // the press is spent
+    } else {
+        esc
+    };
+    if !esc && !moved {
+        return;
+    }
+    let flags_open = |pick: fn(&benilla_formats::SpellDisplay) -> bool, spell_id: u32| {
+        // An uncataloged spell cancels: the gate exists to spare the rare cast-while-moving
+        // spell, and failing open matches the server's own verdict for everything ordinary.
+        spells
+            .as_ref()
+            .and_then(|s| s.catalog.get(spell_id))
+            .is_none_or(pick)
+    };
+    // The cast half — the ref's ONE inflight slot ([`Inflight`]), which is an ordinary cast or a
+    // queued on-next-swing strike. `AbortCast` doesn't distinguish, so neither does the send or
+    // the movement gate; only the local teardown differs, because only a cast ever had a bar.
+    let started = self_e.and_then(|e| casting.get(e).ok()).map(|c| c.spell_id);
+    if let Some(slot) = inflight(&pending, &queued_melee, started, now) {
+        let spell_id = slot.spell_id();
+        // Esc bypasses the flags gate; movement consults the slot's own `InterruptFlags`, which
+        // is what spares a queued strike (Heroic Strike 78, Cleave 845, Raptor Strike 2973 all
+        // ship `InterruptFlags = 0x0` — verified against Spell.dbc, vs Fireball's `0xf`). So
+        // charging in with a strike queued keeps it queued, and only Esc takes it.
+        if esc
+            || flags_open(
+                |d| d.interrupt_flags & SPELL_INTERRUPT_MOVEMENT != 0,
+                spell_id,
+            )
+        {
+            if *crate::net::CAST_TRACE {
+                info!(
+                    "cast-trace: LOCAL self-cancel — {slot:?} ({}), CMSG_CANCEL_CAST",
+                    if esc { "esc" } else { "moved" }
+                );
+            }
+            let _ = net.0.send(ClientCommand::CancelCast { spell_id });
+            match slot {
+                Inflight::Cast(_) => {
+                    pending.clear_if(spell_id);
+                    // The ref's two-step at RTT→0: STOP arms the bar's flash overlay, the echo's
+                    // INTERRUPTED repaints it red and starts the hold — so after the hold the
+                    // flash BURSTS white over the red bar, then the fade runs. One edge alone
+                    // misses the burst (which the enemy-interrupt path — no prior STOP —
+                    // correctly lacks).
+                    feed.0.push(CastBarEdge::Stop);
+                    feed.0.push(CastBarEdge::Interrupted);
+                    // The reap — `spell_failed_other`'s self arm, run early so the echo finds it
+                    // done.
+                    if let Some(e) = self_e {
+                        if casting.get(e).is_ok_and(|c| c.spell_id == spell_id) {
+                            ecs.entity(e).remove::<Casting>();
+                        }
+                        cast_events.write(CastEvent {
+                            entity: e,
+                            spell_id,
+                            kind: CastEventKind::Fail,
+                            seq: play_seq.next(),
+                        });
+                    }
+                }
+                Inflight::Strike(_) => {
+                    // Clearing the slot IS the un-toggle: the checked ring reads it
+                    // (`ui_action::state`), so the button darkens this frame instead of waiting
+                    // for vmangos's FAILED_OTHER + CAST_RESULT echo (which then finds the slot
+                    // already open and is idempotent). `AbortCast` fires its `0x152`
+                    // SPELLCAST_STOP here too — inert on a bar that never opened
+                    // (`CastingBar.xml` guards every arm on `IsShown`), so it is fired for
+                    // fidelity, not effect. No red INTERRUPTED: there is nothing to repaint.
+                    queued_melee.clear_if(spell_id);
+                    feed.0.push(CastBarEdge::Stop);
+                }
+            }
+        }
+    }
+    // The channel half — MOVEMENT-ONLY (Esc can't stop a channel: the doc above / 0454), and
+    // the send and nothing else (the verified asymmetry: the ref's `0x6e9b70` fires no event
+    // and clears no state; the bar and [`ActiveChannel`] both close on the server's
+    // `SMSG_CHANNEL_UPDATE(0)`, ~one localhost frame later).
+    if moved {
+        if let Some(spell_id) = channel.current(now) {
+            if flags_open(
+                |d| d.channel_interrupt_flags & CHANNEL_INTERRUPT_MOVING != 0,
+                spell_id,
+            ) {
+                if *crate::net::CAST_TRACE {
+                    info!("cast-trace: LOCAL channel self-cancel — spell {spell_id}, CMSG_CANCEL_CHANNELLING");
+                }
+                let _ = net.0.send(ClientCommand::CancelChannelling { spell_id });
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const FIREBALL: u32 = 133;
+
+    /// The suppressed channel still arms [`ActiveChannel`], so its action button stays lit: the
+    /// reference's channel mirror is `SPELLCAST+0x10` (`0xceac58`), written at the cast SEND
+    /// (`0x6e4f88`) and never touched by `0x6e7550`. That is why all four of the handler's gates
+    /// live in the DRAIN and none of them in `super::net`'s `channel_start`, which arms this.
+    #[test]
+    fn suppressing_the_channel_bar_does_not_clear_the_channel_mirror() {
+        let t0 = Instant::now();
+        // What `MSG_CHANNEL_START` does for Blood Siphon 24322 — the suppressed row.
+        let mut channel = ActiveChannel::default();
+        channel.start(24322, 8_000, t0);
+        assert_eq!(
+            channel.current(t0 + Duration::from_secs(1)),
+            Some(24322),
+            "the wire edge arms the mirror regardless of what the bar does with it"
+        );
+    }
+
+    #[test]
+    fn a_fresh_guard_is_open() {
+        let g = PendingCast::default();
+        assert!(
+            !g.in_flight(Instant::now()),
+            "nothing sent yet — casting allowed"
+        );
+    }
+
+    #[test]
+    fn arming_closes_the_guard_and_a_matching_resolution_opens_it() {
+        let t0 = Instant::now();
+        let mut g = PendingCast::default();
+        g.arm(FIREBALL, t0, true);
+        assert!(
+            g.in_flight(t0),
+            "a cast is in flight — a second one is refused"
+        );
+        g.clear_if(FIREBALL); // SMSG_SPELL_GO / a failing SMSG_CAST_RESULT for our cast
+        assert!(
+            !g.in_flight(t0),
+            "our cast resolved — casting allowed again"
+        );
+    }
+
+    #[test]
+    fn a_different_spells_resolution_leaves_the_guard_closed() {
+        let t0 = Instant::now();
+        let mut g = PendingCast::default();
+        g.arm(FIREBALL, t0, true);
+        g.clear_if(FIREBALL + 1); // a triggered proc's GO for some other spell mid-cast
+        assert!(
+            g.in_flight(t0),
+            "a different spell's resolution must not open the guard on our cast"
+        );
+    }
+
+    #[test]
+    fn the_guard_opens_when_its_safety_deadline_lapses() {
+        // The net that saves us if a cast resolves with no packet (a local move-cancel we don't
+        // model): the guard cannot wedge casting shut forever.
+        let t0 = Instant::now();
+        let mut g = PendingCast::default();
+        g.arm(FIREBALL, t0, true);
+        assert!(g.in_flight(t0 + SEND_PROVISIONAL - Duration::from_secs(1)));
+        assert!(!g.in_flight(t0 + SEND_PROVISIONAL + Duration::from_secs(1)));
+    }
+
+    #[test]
+    fn a_pushback_extends_the_guard_so_it_holds_past_the_stretched_cast() {
+        let t0 = Instant::now();
+        let mut g = PendingCast::default();
+        g.arm(FIREBALL, t0, true);
+        g.refine(1_000, t0); // a 1 s cast: deadline t0 + 1s + 2s slack = t0 + 3s
+        g.delay(500, t0); // a hit at t0 pushes it +0.5s ⇒ t0 + 3.5s
+        assert!(
+            g.in_flight(t0 + Duration::from_millis(3_200)),
+            "the pushback kept the guard shut past the original refined deadline"
+        );
+    }
+
+    #[test]
+    fn spell_start_tightens_the_deadline_to_the_real_cast_time() {
+        let t0 = Instant::now();
+        let mut g = PendingCast::default();
+        g.arm(FIREBALL, t0, true); // provisional 5s window
+        g.refine(1_500, t0); // SMSG_SPELL_START: a 1.5s cast (+ 2s pushback slack ⇒ 3.5s)
+        let at_four = t0 + Duration::from_secs(4);
+        assert!(
+            !g.in_flight(at_four),
+            "refined to 1.5s + slack, the guard has opened by t+4s (it would still be shut at the \
+             5s provisional)"
+        );
+    }
+
+    /// The queued on-next-swing slot: deadline-less (no clock in its API at all), keyed clears
+    /// only, and a re-arm replaces — the server's single `CURRENT_MELEE_SPELL` slot.
+    #[test]
+    fn queued_melee_spell_is_wire_cleared_and_single_slot() {
+        const HEROIC_STRIKE: u32 = 78;
+        const CLEAVE: u32 = 845;
+        let mut q = QueuedMeleeSpell::default();
+        assert_eq!(q.current(), None);
+
+        q.arm(HEROIC_STRIKE);
+        assert_eq!(q.current(), Some(HEROIC_STRIKE), "queued and checked");
+
+        // A different spell's resolution (Rend's GO while HS waits) must not open the queue.
+        q.clear_if(772);
+        assert_eq!(q.current(), Some(HEROIC_STRIKE));
+
+        // A second on-next-swing cast replaces the queue (vmangos holds ONE melee slot).
+        q.arm(CLEAVE);
+        assert_eq!(q.current(), Some(CLEAVE));
+
+        // The swing fired it (SPELL_GO) — or the slot died (failing CAST_RESULT /
+        // SPELL_FAILED_OTHER): the matching id clears.
+        q.clear_if(CLEAVE);
+        assert_eq!(q.current(), None, "the wire resolution opened the queue");
+    }
+
+    /// The local self-cancel harness: a mini-App with the real [`local_self_cancel`] system, a
+    /// self player mid-cast/mid-channel, and the net channel's receive half to assert the wire.
+    /// The harness registers no `UiScript`, so the ESC trigger reads `false` by default; the
+    /// ESC-leg tests insert a real VM and drive the actual `SpellStopCasting()` binding (the
+    /// ladder's 1/nil semantics are pinned Lua-side in `ui_script::escape_tests`).
+    mod local_cancel {
+        use super::*;
+        use crate::creature_anim::PlaySeq;
+        use crate::net::{Guid, GuidIndex, NetCommands, SelfGuid, SelfPlayer};
+        use crate::ui_cast::feed_cast_bar;
+        use benilla_formats::{SpellCatalog, SpellDisplay};
+        use bevy::ecs::system::RunSystemOnce;
+        use std::collections::HashMap;
+
+        const ARCANE_MISSILES: u32 = 5143;
+        const HEROIC_STRIKE: u32 = 78;
+
+        fn harness(
+            displays: HashMap<u32, SpellDisplay>,
+        ) -> (App, crossbeam_channel::Receiver<crate::net::ClientCommand>) {
+            let (tx, rx) = crossbeam_channel::unbounded();
+            let mut app = App::new();
+            app.add_message::<CastEvent>()
+                .init_resource::<CastBarFeed>()
+                .init_resource::<PendingCast>()
+                .init_resource::<QueuedMeleeSpell>()
+                .init_resource::<ActiveChannel>()
+                .init_resource::<AutoRepeatActive>()
+                .init_resource::<LocalMoveStart>()
+                .init_resource::<GuidIndex>()
+                .init_resource::<SelfGuid>()
+                .init_resource::<PlaySeq>()
+                .insert_resource(NetCommands(tx))
+                .insert_resource(crate::ui_action::Spells {
+                    catalog: SpellCatalog::from_displays(displays),
+                    ..crate::ui_action::Spells::empty_for_tests()
+                });
+            let self_e = app.world_mut().spawn((Guid(10), SelfPlayer)).id();
+            app.world_mut()
+                .resource_mut::<GuidIndex>()
+                .0
+                .insert(10, self_e);
+            app.world_mut().resource_mut::<SelfGuid>().0 = Some(10);
+            (app, rx)
+        }
+
+        /// Mark the self player mid-cast on `spell_id` (the `SMSG_SPELL_START` echo's `Casting`).
+        fn mark_casting(app: &mut App, spell_id: u32) {
+            let self_e = app.world().resource::<GuidIndex>().0[&10];
+            app.world_mut().entity_mut(self_e).insert(Casting {
+                spell_id,
+                until: None,
+            });
+        }
+
+        fn run(app: &mut App, moved: bool) {
+            app.world_mut().resource_mut::<LocalMoveStart>().0 = moved;
+            app.world_mut().run_system_once(local_self_cancel).unwrap();
+        }
+
+        /// The headline feel fix: a directional start / jump mid-cast kills the cast locally —
+        /// wire cancel out, guard open, the STOP + INTERRUPTED bar-edge pair (the ref's own
+        /// two-step: its silent 0x152 STOP arms the flash, the server echo's repaint holds the
+        /// red "Interrupted"; our keyed reap suppresses the real echo, so the local pair
+        /// replays the sequence at RTT→0 — decisions 0449/0454), `Casting` reaped — instead of
+        /// waiting ~150 ms+ for the server's 0.5-yd position-delta interrupt.
+        #[test]
+        fn a_move_edge_mid_cast_cancels_locally() {
+            let (mut app, rx) = harness(HashMap::from([(
+                FIREBALL,
+                SpellDisplay {
+                    interrupt_flags: 0xf, // the ordinary timed-cast mask (movement bit set)
+                    ..Default::default()
+                },
+            )]));
+            app.world_mut()
+                .resource_mut::<PendingCast>()
+                .arm(FIREBALL, Instant::now(), true);
+            mark_casting(&mut app, FIREBALL);
+
+            run(&mut app, true);
+
+            assert!(
+                matches!(
+                    rx.try_recv(),
+                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
+                ),
+                "the move edge ships CMSG_CANCEL_CAST for the in-flight cast"
+            );
+            assert!(
+                !app.world()
+                    .resource::<PendingCast>()
+                    .in_flight(Instant::now()),
+                "the in-flight guard opens with the local cancel"
+            );
+            let feed = &app.world().resource::<CastBarFeed>().0;
+            assert_eq!(feed.len(), 2);
+            assert!(
+                matches!(
+                    (&feed[0], &feed[1]),
+                    (CastBarEdge::Stop, CastBarEdge::Interrupted)
+                ),
+                "the bar edges are the ref's own two-step at RTT→0 — STOP (arms the flash \
+                 overlay) then the red INTERRUPTED (the echo's repaint: hold, burst, fade); \
+                 the keyed reap silences the real echo (0449/0454)"
+            );
+            let self_e = app.world().resource::<GuidIndex>().0[&10];
+            assert!(
+                app.world().entity(self_e).get::<Casting>().is_none(),
+                "the self `Casting` state is reaped, so the server's echo (FAILED_OTHER + \
+                 CAST_RESULT) finds nothing to repaint"
+            );
+            assert!(
+                !app.world().resource::<LocalMoveStart>().0,
+                "the edge is consumed"
+            );
+        }
+
+        /// The per-spell gate (VERIFIED — `test [SpellRec+0x54],1` at both call sites): a spell
+        /// whose `InterruptFlags` lacks the movement bit keeps casting while we move — no wire
+        /// cancel, no bar edge.
+        #[test]
+        fn the_interrupt_flags_gate_spares_a_movement_castable_spell() {
+            let (mut app, rx) = harness(HashMap::from([(
+                FIREBALL,
+                SpellDisplay {
+                    interrupt_flags: 0xe, // movement bit CLEAR (pushback/stun/combat only)
+                    ..Default::default()
+                },
+            )]));
+            app.world_mut()
+                .resource_mut::<PendingCast>()
+                .arm(FIREBALL, Instant::now(), true);
+
+            run(&mut app, true);
+
+            assert!(rx.try_recv().is_err(), "no wire cancel for a spared spell");
+            assert!(
+                app.world()
+                    .resource::<PendingCast>()
+                    .in_flight(Instant::now()),
+                "the guard keeps holding — the cast runs on"
+            );
+            assert!(app.world().resource::<CastBarFeed>().0.is_empty());
+        }
+
+        /// A spell the catalog doesn't know fails OPEN (cancels): the gate exists to spare the
+        /// rare cast-while-moving spell, and the server's own verdict for everything ordinary is
+        /// to interrupt.
+        #[test]
+        fn an_uncataloged_spell_fails_open() {
+            let (mut app, rx) = harness(HashMap::new());
+            app.world_mut()
+                .resource_mut::<PendingCast>()
+                .arm(FIREBALL, Instant::now(), true);
+
+            run(&mut app, true);
+
+            assert!(
+                matches!(
+                    rx.try_recv(),
+                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
+                ),
+                "an unknown spell's cast still cancels on movement"
+            );
+        }
+
+        /// The union's other half: an ITEM use's cast (a hearthstone) never arms the send
+        /// guard — the started self `Casting` (the `SMSG_SPELL_START` echo) alone makes it
+        /// move-cancelable, mirroring the ref's ONE inflight id (`0xceca88`), which item casts
+        /// set like any spell cast.
+        #[test]
+        fn a_started_item_cast_cancels_without_the_send_guard() {
+            let (mut app, rx) = harness(HashMap::from([(
+                FIREBALL,
+                SpellDisplay {
+                    interrupt_flags: 0xf,
+                    ..Default::default()
+                },
+            )]));
+            mark_casting(&mut app, FIREBALL); // PendingCast stays empty — item casts never arm it
+
+            run(&mut app, true);
+
+            assert!(
+                matches!(
+                    rx.try_recv(),
+                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
+                ),
+                "the started cast cancels through the `Casting` half of the union"
+            );
+            let self_e = app.world().resource::<GuidIndex>().0[&10];
+            assert!(app.world().entity(self_e).get::<Casting>().is_none());
+        }
+
+        /// No move edge, cast in flight: nothing happens — the system is edge-triggered, never
+        /// level-triggered (holding W through a whole cast is one cancel at the start, not one
+        /// per frame; and standing still cancels nothing).
+        #[test]
+        fn no_edge_means_no_cancel() {
+            let (mut app, rx) = harness(HashMap::from([(
+                FIREBALL,
+                SpellDisplay {
+                    interrupt_flags: 0xf,
+                    ..Default::default()
+                },
+            )]));
+            app.world_mut()
+                .resource_mut::<PendingCast>()
+                .arm(FIREBALL, Instant::now(), true);
+
+            run(&mut app, false);
+
+            assert!(rx.try_recv().is_err());
+            assert!(app
+                .world()
+                .resource::<PendingCast>()
+                .in_flight(Instant::now()));
+            assert!(app.world().resource::<CastBarFeed>().0.is_empty());
+        }
+
+        /// Esc CANNOT stop a channel — `0x6e6e80` never reaches the channel
+        /// canceler `0x6e9b70`, and its inflight gate is already 0 mid-channel (0454): the
+        /// mirror answers `SpellStopCasting()` nil (the
+        /// ladder falls through to the next rung) and the drain ships nothing.
+        #[test]
+        fn esc_cannot_stop_a_channel() {
+            let (mut app, rx) = harness(HashMap::new());
+            app.insert_non_send_resource(UiScript::new().unwrap());
+            let now = Instant::now();
+            app.world_mut()
+                .resource_mut::<ActiveChannel>()
+                .start(ARCANE_MISSILES, 5_000, now);
+
+            app.world_mut().run_system_once(feed_cast_bar).unwrap();
+            assert_eq!(
+                app.world()
+                    .non_send_resource::<UiScript>()
+                    .eval::<Option<i64>>("return SpellStopCasting()")
+                    .unwrap(),
+                None,
+                "mid-channel the binding answers nil — the vanilla /stopcasting quirk"
+            );
+            app.world_mut().run_system_once(local_self_cancel).unwrap();
+            assert!(
+                rx.try_recv().is_err(),
+                "no wire cancel — channels break only on the movement path"
+            );
+            assert_eq!(
+                app.world().resource::<ActiveChannel>().current(now),
+                Some(ARCANE_MISSILES)
+            );
+        }
+
+        /// The ref's branch order inside `SpellStopCasting` (`0x6e6e80`): a running auto-repeat
+        /// dies FIRST — `CMSG_CANCEL_AUTO_REPEAT_SPELL`, no bar edge — and SPENDS the press;
+        /// the in-flight cast survives to the next one. One press stops one thing.
+        #[test]
+        fn esc_cancels_the_auto_repeat_first_and_the_cast_on_the_next_press() {
+            const AUTO_SHOT: u32 = 75;
+            let (mut app, rx) = harness(HashMap::new());
+            app.insert_non_send_resource(UiScript::new().unwrap());
+            app.world_mut().resource_mut::<AutoRepeatActive>().0 = Some(AUTO_SHOT);
+            app.world_mut()
+                .resource_mut::<PendingCast>()
+                .arm(FIREBALL, Instant::now(), true);
+            mark_casting(&mut app, FIREBALL);
+
+            // Press 1: truthy mirror (auto-repeat ∪ cast) → trigger queued → the drain stops
+            // the auto-repeat ONLY.
+            app.world_mut().run_system_once(feed_cast_bar).unwrap();
+            assert_eq!(
+                app.world()
+                    .non_send_resource::<UiScript>()
+                    .eval::<Option<i64>>("return SpellStopCasting()")
+                    .unwrap(),
+                Some(1)
+            );
+            app.world_mut().run_system_once(local_self_cancel).unwrap();
+            assert!(
+                matches!(
+                    rx.try_recv(),
+                    Ok(crate::net::ClientCommand::CancelAutoRepeat)
+                ),
+                "the auto-repeat cancel ships first — the ref's priority branch"
+            );
+            assert!(rx.try_recv().is_err(), "the cast survives the first press");
+            assert!(app.world().resource::<AutoRepeatActive>().0.is_none());
+            assert!(
+                app.world()
+                    .resource::<PendingCast>()
+                    .in_flight(Instant::now()),
+                "the send guard still holds — one press stopped one thing"
+            );
+            assert!(
+                app.world().resource::<CastBarFeed>().0.is_empty(),
+                "an auto-repeat cancel paints no bar edge"
+            );
+
+            // Press 2: the auto-repeat is gone — now the cast dies, the ordinary Esc cancel.
+            app.world_mut().run_system_once(feed_cast_bar).unwrap();
+            assert_eq!(
+                app.world()
+                    .non_send_resource::<UiScript>()
+                    .eval::<Option<i64>>("return SpellStopCasting()")
+                    .unwrap(),
+                Some(1)
+            );
+            app.world_mut().run_system_once(local_self_cancel).unwrap();
+            assert!(
+                matches!(
+                    rx.try_recv(),
+                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
+                ),
+                "the second press reaches the cast half"
+            );
+        }
+
+        /// **The director's report, decision 1049: Esc with Heroic Strike queued un-toggles the
+        /// STRIKE and keeps the target.** In the reference a queued on-next-swing spell simply
+        /// *is* the inflight spell (`0xceca88`), so `SpellStopCasting 0x6e6e80` takes its plain
+        /// `IsCasting 0x6e3d30` branch — `AbortCast` → `CMSG_CANCEL_CAST` — and returns `1`,
+        /// which EATS the press so `ToggleGameMenu`'s ladder never reaches `ClearTarget()`. We
+        /// split that one slot in two and the Esc reader saw only the cast half, so the binding
+        /// answered nil: the strike stayed lit *and* the target dropped, both from one cause.
+        #[test]
+        fn esc_unqueues_a_strike_and_eats_the_press() {
+            let (mut app, rx) = harness(HashMap::from([(
+                HEROIC_STRIKE,
+                SpellDisplay {
+                    attributes: 0x5_0014, // the shipped row: on-next-swing (`& 0x404`)
+                    interrupt_flags: 0,   // …and no movement bit, also shipped
+                    ..Default::default()
+                },
+            )]));
+            app.insert_non_send_resource(UiScript::new().unwrap());
+            app.world_mut()
+                .resource_mut::<QueuedMeleeSpell>()
+                .arm(HEROIC_STRIKE);
+
+            app.world_mut().run_system_once(feed_cast_bar).unwrap();
+            assert_eq!(
+                app.world()
+                    .non_send_resource::<UiScript>()
+                    .eval::<Option<i64>>("return SpellStopCasting()")
+                    .unwrap(),
+                Some(1),
+                "the queued strike makes IsCasting true, so the binding EATS the press — which \
+                 is what spares the target three rungs further down the ladder"
+            );
+            app.world_mut().run_system_once(local_self_cancel).unwrap();
+            assert!(
+                matches!(
+                    rx.try_recv(),
+                    Ok(crate::net::ClientCommand::CancelCast {
+                        spell_id: HEROIC_STRIKE
+                    })
+                ),
+                "AbortCast names the queued strike on the wire, exactly as it would a cast"
+            );
+            assert_eq!(
+                app.world().resource::<QueuedMeleeSpell>().current(),
+                None,
+                "the slot opens locally — the checked ring darkens this frame, not one RTT later"
+            );
+            assert!(
+                matches!(
+                    app.world().resource::<CastBarFeed>().0[..],
+                    [CastBarEdge::Stop]
+                ),
+                "the ref's `0x152` STOP and nothing else: no red INTERRUPTED for a spell that \
+                 never opened a bar"
+            );
+        }
+
+        /// …but MOVEMENT does not take it. The movement path consults the inflight spell's own
+        /// `InterruptFlags`, and Heroic Strike 78 / Cleave 845 / Raptor Strike 2973 all ship
+        /// `InterruptFlags = 0x0` (read off the shipped `Spell.dbc`; Fireball is `0xf`). So
+        /// charging in with a strike queued keeps it queued — Esc is the only local taker.
+        #[test]
+        fn a_move_edge_leaves_a_queued_strike_queued() {
+            let (mut app, rx) = harness(HashMap::from([(
+                HEROIC_STRIKE,
+                SpellDisplay {
+                    interrupt_flags: 0,
+                    ..Default::default()
+                },
+            )]));
+            app.world_mut()
+                .resource_mut::<QueuedMeleeSpell>()
+                .arm(HEROIC_STRIKE);
+
+            run(&mut app, true);
+
+            assert!(rx.try_recv().is_err(), "running at the mob cancels nothing");
+            assert_eq!(
+                app.world().resource::<QueuedMeleeSpell>().current(),
+                Some(HEROIC_STRIKE)
+            );
+        }
+
+        /// The nesting order (`Inflight`'s doc): an ordinary cast started over a queued strike
+        /// pushes it down (`PushPopNestedCast 0x6e4ad0`), so `0xceca88` holds the CAST. One Esc
+        /// takes the cast; `AbortCast`'s pop restores the strike, and the next Esc takes that.
+        /// One press, one thing — the ladder's law all the way down.
+        ///
+        /// This is the **local** law, which is all a harness with no server can show, and it is
+        /// the ref's local law too — with the one knowing
+        /// difference `Inflight`'s doc names: the ref's press 2 re-asserts the strike instead of
+        /// clearing it. On a live wire neither client gets this far, because vmangos drops the
+        /// melee slot on press **1** regardless of the id in the packet, and both converge off
+        /// that echo. So what this pins is the ordering, not a two-press ritual a player sees.
+        #[test]
+        fn esc_takes_the_cast_first_and_the_strike_on_the_next_press() {
+            let (mut app, rx) = harness(HashMap::new());
+            app.insert_non_send_resource(UiScript::new().unwrap());
+            app.world_mut()
+                .resource_mut::<QueuedMeleeSpell>()
+                .arm(HEROIC_STRIKE);
+            app.world_mut()
+                .resource_mut::<PendingCast>()
+                .arm(FIREBALL, Instant::now(), true);
+            mark_casting(&mut app, FIREBALL);
+
+            app.world_mut().run_system_once(feed_cast_bar).unwrap();
+            assert_eq!(
+                app.world()
+                    .non_send_resource::<UiScript>()
+                    .eval::<Option<i64>>("return SpellStopCasting()")
+                    .unwrap(),
+                Some(1)
+            );
+            app.world_mut().run_system_once(local_self_cancel).unwrap();
+            assert!(
+                matches!(
+                    rx.try_recv(),
+                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
+                ),
+                "the nested cast is what sits in the inflight slot — it dies first"
+            );
+            assert!(rx.try_recv().is_err());
+            assert_eq!(
+                app.world().resource::<QueuedMeleeSpell>().current(),
+                Some(HEROIC_STRIKE),
+                "the strike is the SAVE underneath, untouched by the first press"
+            );
+
+            // Press 2 — the pop put the strike back in the slot.
+            app.world_mut().run_system_once(feed_cast_bar).unwrap();
+            assert_eq!(
+                app.world()
+                    .non_send_resource::<UiScript>()
+                    .eval::<Option<i64>>("return SpellStopCasting()")
+                    .unwrap(),
+                Some(1),
+                "still stoppable — so this press is eaten too, and the target still survives"
+            );
+            app.world_mut().run_system_once(local_self_cancel).unwrap();
+            assert!(matches!(
+                rx.try_recv(),
+                Ok(crate::net::ClientCommand::CancelCast {
+                    spell_id: HEROIC_STRIKE
+                })
+            ));
+            assert_eq!(app.world().resource::<QueuedMeleeSpell>().current(), None);
+        }
+
+        /// The channel half is the SEND and nothing else — the verified asymmetry (0445): the
+        /// ref's `0x6e9b70` ships CMSG_CANCEL_CHANNELLING but fires no FrameScript event and
+        /// clears no state; the channel bar and the mirror both close on the server's
+        /// `SMSG_CHANNEL_UPDATE(0)` through the normal wire path.
+        #[test]
+        fn a_move_edge_mid_channel_sends_the_cancel_and_touches_nothing_local() {
+            let (mut app, rx) = harness(HashMap::from([(
+                ARCANE_MISSILES,
+                SpellDisplay {
+                    channel_interrupt_flags: 0x7c0c, // the real 5143 mask (moving bit 0x8 set)
+                    ..Default::default()
+                },
+            )]));
+            let now = Instant::now();
+            app.world_mut()
+                .resource_mut::<ActiveChannel>()
+                .start(ARCANE_MISSILES, 5_000, now);
+
+            run(&mut app, true);
+
+            assert!(
+                matches!(
+                    rx.try_recv(),
+                    Ok(crate::net::ClientCommand::CancelChannelling {
+                        spell_id: ARCANE_MISSILES
+                    })
+                ),
+                "the move edge ships CMSG_CANCEL_CHANNELLING"
+            );
+            assert_eq!(
+                app.world().resource::<ActiveChannel>().current(now),
+                Some(ARCANE_MISSILES),
+                "the mirror stays live — the server's UPDATE(0) is what clears it"
+            );
+            assert!(
+                app.world().resource::<CastBarFeed>().0.is_empty(),
+                "no local bar edge — the bar closes on the wire's SPELLCAST_CHANNEL_STOP"
+            );
+        }
+    }
+
+    /// The channel mirror's lifecycle: START opens the window for the whole duration, a nonzero
+    /// UPDATE re-times it (pushback shortens channels), UPDATE(0) ends it — and the slack deadline
+    /// self-clears a channel whose closing packet never arrived.
+    #[test]
+    fn active_channel_tracks_the_wire_lifecycle() {
+        let t0 = Instant::now();
+        let mut ch = ActiveChannel::default();
+        assert_eq!(ch.current(t0), None);
+
+        ch.start(10, 5_000, t0); // Arcane Missiles-shaped: 5 s channel
+        assert_eq!(ch.current(t0), Some(10));
+        assert_eq!(
+            ch.current(t0 + Duration::from_secs(4)),
+            Some(10),
+            "still live near the end"
+        );
+        assert_eq!(
+            ch.current(t0 + Duration::from_secs(8)),
+            None,
+            "the slack deadline self-clears a lost UPDATE(0)"
+        );
+
+        // Pushback: an update naming LESS time moves the deadline in.
+        ch.start(10, 5_000, t0);
+        ch.update(1_000, t0);
+        assert_eq!(ch.current(t0 + Duration::from_secs(4)), None);
+
+        // The closing update ends it immediately.
+        ch.start(10, 5_000, t0);
+        ch.update(0, t0);
+        assert_eq!(ch.current(t0), None);
+    }
+}
diff --git a/crates/benilla-app/src/spell/mod.rs b/crates/benilla-app/src/spell/mod.rs
new file mode 100644
index 00000000..6484ac40
--- /dev/null
+++ b/crates/benilla-app/src/spell/mod.rs
@@ -0,0 +1,97 @@
+//! **The spell** — `Spell_C`, the reference's cast unit: the
+//! cast ladder and its commit ([`cast_send`] — `TryCast 0x6e4b60` → `SendCast 0x6e54f0`), the
+//! target bind ([`cast_target`] — `ArmCast 0x6e5250` / `BindTarget 0x6e5b40`), the requirement
+//! validator's rungs ([`validator`] — `0x6094f0`), the usable walk ([`usable`] —
+//! `IsSpellUsableNow 0x6e3d60`), the targeting cursor and its flag_word ([`targeting`] —
+//! `0xcecac0`), the in-flight slot ([`inflight`]), the cooldown store ([`cooldowns`]), the
+//! talent modifier tables ([`mods`]) and the packet handlers that fold into them ([`net`]).
+//!
+//! What the reference delegates stays out, with its owner: the spell table
+//! (`crate::ui_action::Spells`, the DBC's), the action store and the error text
+//! (`crate::ui_action` — the `ui` boundary), the aura durations (`crate::ui_aura`), the pet bar
+//! (`crate::ui_pet`), the cast bar's feed (`crate::ui_cast`). Decisions 2328 (the state) and 2330
+//! (the ladder).
+
+use bevy::prelude::*;
+
+use crate::char_select::ClientState;
+use crate::ui_script::UiInput;
+use crate::ui_unit::UnitFeed;
+use benilla_world::schedule::WorldStage;
+
+mod cast_send;
+pub(crate) mod cast_target;
+pub(crate) mod cooldowns;
+mod inflight;
+mod mods;
+pub(crate) mod net;
+pub(crate) mod targeting;
+pub(crate) mod usable;
+pub(crate) mod validator;
+
+// The one cast path, and the only way in: every caster surface takes [`CastLadder`] as a single
+// SystemParam and commits through [`CastCommit`] — `send_spell_cast` itself is private to
+// `cast_send`, so a second send path cannot be written by accident (decision 0914).
+pub(crate) use cast_send::{CastCommit, CastLadder, TargetedBind};
+pub(crate) use cast_target::AutoSelfCast;
+pub(crate) use cooldowns::Cooldowns;
+pub(crate) use inflight::{
+    inflight, ActiveChannel, AutoRepeatActive, LocalMoveStart, PendingCast, QueuedMeleeSpell,
+    SPELL_INTERRUPT_MOVEMENT,
+};
+pub(crate) use mods::{SpellModifiers, OP_COST};
+// The target chain registers the cursor pre-empt + the click commits, and the spellbook/stance/
+// craft drains thread the mode through the one cast-send path (decision 0792). `TargetingWants`
+// travels with it because the chain also holds a *seam-specific* consumer — the ground reticle,
+// which draws for the location word alone (decision 0943).
+pub(crate) use targeting::{ground_cast_radius, SpellTargeting, TargetingWants};
+
+/// The local self-cancel's slot in the frame: anything that reads the in-flight state after a
+/// move/jump/Esc may have ended the cast this tick orders `.after(LocalCancel)` — the cast-bar
+/// feed does, so the bar drops the same frame the cast does (2328).
+#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+pub(crate) struct LocalCancel;
+
+pub(crate) struct SpellPlugin;
+
+impl Plugin for SpellPlugin {
+    fn build(&self, app: &mut App) {
+        app.init_resource::<PendingCast>()
+            .init_resource::<QueuedMeleeSpell>()
+            .init_resource::<ActiveChannel>()
+            .init_resource::<LocalMoveStart>()
+            .init_resource::<AutoRepeatActive>()
+            .init_resource::<Cooldowns>()
+            .init_resource::<SpellModifiers>()
+            .init_resource::<AutoSelfCast>()
+            .init_resource::<SpellTargeting>()
+            .init_resource::<targeting::EnchantConfirmItem>()
+            .add_observer(cast_target::on_cvar)
+            .add_systems(
+                Update,
+                (
+                    inflight::local_self_cancel
+                        .in_set(UnitFeed)
+                        .in_set(LocalCancel),
+                    mods::track_class_family
+                        .after(WorldStage::Net)
+                        .before(UnitFeed),
+                    // The targeting mode's ESC-chain halves (decision 0792): the state push
+                    // rides the feeds (before the input pass runs `ToggleGameMenu`), the
+                    // trigger drain follows it — same frame, so an ESC's cancel lands before
+                    // the next frame's cursor drive reads the mode. The cursor pre-empt, the
+                    // right-press cancel, and the click commits register in the TARGET chain
+                    // (ordering against the classifier and the select click is theirs to own).
+                    targeting::feed_targeting_to_vm.in_set(UnitFeed),
+                    targeting::drain_stop_targeting.after(UiInput),
+                    // The item half's commit (decision 0923) — the bag / paper-doll click seam's
+                    // `0x495d60`. A UI drain like the others: after the input pass, so a click
+                    // this frame binds this frame. It is deliberately NOT in the target chain —
+                    // the clicks it consumes never reach the world.
+                    targeting::commit_item_cast_on_pick.after(UiInput),
+                ),
+            )
+            .add_systems(OnEnter(ClientState::InWorld), mods::clear_on_world_enter);
+        net::register(app);
+    }
+}
diff --git a/crates/benilla-app/src/spell_mods.rs b/crates/benilla-app/src/spell/mods.rs
similarity index 93%
rename from crates/benilla-app/src/spell_mods.rs
rename to crates/benilla-app/src/spell/mods.rs
index cfb2cede..5961782a 100644
--- a/crates/benilla-app/src/spell_mods.rs
+++ b/crates/benilla-app/src/spell/mods.rs
@@ -4,9 +4,8 @@
 //! Two `i32[64][29]` tables (`SPELLMOD_FLAT 0xcead60`, `SPELLMOD_PCT 0xcecb30`), one handler that
 //! fills them (`Spell_C::HandleSetSpellModifier 0x6e9950`, registered for both
 //! `SMSG_SET_FLAT_SPELL_MODIFIER` and `SMSG_SET_PCT_SPELL_MODIFIER` by `Spell_C::SystemInitialize
-//! 0x6e7150`), and one reader that answers them (`GetSpellModifiers 0x6e6b30`). Every law here is
-//! byte-VERIFIED in wow-re `system/spell/scratch/spellmod-table-law.md`; this module is that note
-//! turned into the one place benilla asks "does a talent change this number?".
+//! 0x6e7150`), and one reader that answers them (`GetSpellModifiers 0x6e6b30`). This module is
+//! that machinery turned into the one place benilla asks "does a talent change this number?".
 //!
 //! **The index is `mask_bit * 29 + op`, in both directions, and it is the thing to get right.**
 //! The writer multiplies its FIRST wire byte (`6e9993: imul eax,eax,0x1d`); the reader
@@ -14,9 +13,8 @@
 //! `cmp eax,0x40`, which forces the first factor to be the 0..63 `SpellFamilyFlags` **bit index**
 //! and the second the 0..28 SpellModOp. The transposed form addresses 47% of the array
 //! (`29*28 + 63 = 875` against 1856 cells) and makes writer and reader touch systematically
-//! disjoint cells — every modifier silently dropped, nothing to see in a log. wow-re's own
-//! `wave-handlers.md` carried the transposed form, `verified`, for months. [`index`] is the single
-//! expression both sides here go through, so they cannot drift apart.
+//! disjoint cells — every modifier silently dropped, nothing to see in a log. [`index`] is the
+//! single expression both sides here go through, so they cannot drift apart.
 //!
 //! The server agrees, independently and in source: vmangos `Player::SendSpellMod`
 //! (`Objects/Player.cpp:17815`) loops `for (int eff = 0; eff < 64; ++eff)` over the modifier's own
@@ -68,7 +66,7 @@
 //! | 11 | COOLDOWN | — |
 //! | 12 | SPEED | — |
 //! | 13 | *(no enumerator)* | never read |
-//! | **14** | **COST** | [`OP_COST`] — `ui_action::usable::power_cost` |
+//! | **14** | **COST** | [`OP_COST`] — `spell::usable::power_cost` |
 //! | 15 | CRIT_DAMAGE_BONUS | never read |
 //! | 16 | RESIST_MISS_CHANCE | never read |
 //! | 17 | JUMP_TARGETS | — |
@@ -101,7 +99,6 @@ use bevy::prelude::*;
 
 use benilla_formats::SpellDisplay;
 
-use crate::char_select::ClientState;
 use crate::chr_classes::ChrClassTable;
 use crate::net::{ObjectStore, SelfPlayer};
 
@@ -115,7 +112,7 @@ const BITS: usize = 64;
 /// discriminators that settle the index's factor roles.
 const CELLS: usize = BITS * OPS;
 
-/// `SPELLMOD_COST` — the one op benilla reads today ([`crate::ui_action::usable::power_cost`], the
+/// `SPELLMOD_COST` — the one op benilla reads today ([`crate::spell::usable::power_cost`], the
 /// reference's `GetPowerCost 0x6e31b0` @ `6e32e3`). The module header's table names the other 28.
 pub(crate) const OP_COST: u8 = 14;
 
@@ -171,7 +168,7 @@ impl SpellMod {
 /// The two tables and the class family the gate compares against — benilla's `0xcead60` /
 /// `0xcecb30` / `0xcecaac`.
 ///
-/// Filled only by the wire (`net::apply::spells::set_spell_modifier`), cleared only at world-enter
+/// Filled only by the wire (`spell::net::set_spell_modifier`), cleared only at world-enter
 /// ([`clear_on_world_enter`]), and read live at every call site: like the reference, there is no
 /// derived cache to invalidate.
 #[derive(Resource)]
@@ -280,13 +277,13 @@ impl SpellModifiers {
 }
 
 /// Entering the world drops both tables and the class family — `Spell_C::SystemInitialize
-/// 0x6e7150`'s two `rep stosd`s and its `[0xcecaac] = 0`, which the §5 walked to
-/// `CGlueMgr::Update 0x46b930` and pinned to **once per world entry**, not once per process.
+/// 0x6e7150`'s two `rep stosd`s and its `[0xcecaac] = 0`, reached from
+/// `CGlueMgr::Update 0x46b930` **once per world entry**, not once per process.
 ///
 /// There is deliberately nothing else: no talent-change clear (the server re-sends absolute cells),
 /// and no world-LEAVE clear (the reference's own teardown `0x6e99e0` never touches them, and the
 /// next entry is what zeroes them).
-fn clear_on_world_enter(mut mods: ResMut<SpellModifiers>) {
+pub(super) fn clear_on_world_enter(mut mods: ResMut<SpellModifiers>) {
     mods.clear();
 }
 
@@ -299,7 +296,7 @@ fn clear_on_world_enter(mut mods: ResMut<SpellModifiers>) {
 /// the coupling it replaces. And it **never writes 0 back** — an absent avatar leaves the last
 /// value standing, because a cross-map worldport drops the entity mid-session while everything the
 /// server told us stays true (decision 0900's shape). Only the world-enter clear zeroes it.
-fn track_class_family(
+pub(super) fn track_class_family(
     mut mods: ResMut<SpellModifiers>,
     classes: Option<Res<ChrClassTable>>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
@@ -316,27 +313,10 @@ fn track_class_family(
     }
 }
 
-pub(crate) struct SpellModsPlugin;
-
-impl Plugin for SpellModsPlugin {
-    fn build(&self, app: &mut App) {
-        app.init_resource::<SpellModifiers>()
-            .add_systems(
-                Update,
-                // After the net stage that merges the avatar's descriptor, and before the feeds
-                // that read a cost through it — so the family is this frame's, never last
-                // frame's, on the frame the avatar first resolves.
-                track_class_family
-                    .after(benilla_world::schedule::WorldStage::Net)
-                    .before(crate::ui_unit::UnitFeed),
-            )
-            .add_systems(OnEnter(ClientState::InWorld), clear_on_world_enter);
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::char_select::ClientState;
 
     /// A mage spell (family 3) with the given bits set, against a mage player.
     fn mage(bits: &[u8]) -> SpellDisplay {
@@ -493,12 +473,13 @@ mod tests {
     /// is.
     #[test]
     fn world_enter_clears_both_tables_and_the_family() {
-        // A bare app: the plugin's only Update system takes both of its inputs as an `Option`/an
-        // empty query, so the state machine the clear hangs off is all this needs.
+        // A bare app with the world-enter clear alone: the state machine it hangs off is
+        // all this needs.
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, bevy::state::app::StatesPlugin))
             .insert_state(ClientState::Login)
-            .add_plugins(SpellModsPlugin);
+            .init_resource::<SpellModifiers>()
+            .add_systems(OnEnter(ClientState::InWorld), clear_on_world_enter);
 
         {
             let mut mods = app.world_mut().resource_mut::<SpellModifiers>();
diff --git a/crates/benilla-app/src/net/apply/spells.rs b/crates/benilla-app/src/spell/net.rs
similarity index 85%
rename from crates/benilla-app/src/net/apply/spells.rs
rename to crates/benilla-app/src/spell/net.rs
index a2a6a15c..90765c98 100644
--- a/crates/benilla-app/src/net/apply/spells.rs
+++ b/crates/benilla-app/src/spell/net.rs
@@ -1,7 +1,9 @@
-//! Spell-book/action-bar + cast-lifecycle arm bodies for [`super::apply_net_updates`]'s dispatch
-//! match — one of the largest arm families, split out on its own (the decision 0099/0107 precast →
-//! resolve pipeline). Each `pub(super)` fn here is exactly one arm's body; the match at the call
-//! site stays the dispatcher, one call per arm.
+//! The spell's packet handlers (in the net handler table since 2324, moved out of the drain's
+//! spells arm file) — the spell book and the action bar, the cast lifecycle (the decision
+//! 0099/0107 precast → resolve pipeline), the cooldowns, the channels, the aura durations and the
+//! spell modifiers. The lifecycle *state* these fold into is this module's since decision
+//! 2328 ([`super::inflight`], [`super::cooldowns`], [`super::mods`]); the handlers reach it,
+//! and the windows' stores they also touch, through [`Lifecycle`] and [`Scene`].
 
 use std::time::{Duration, Instant};
 
@@ -9,19 +11,466 @@ use benilla_formats::LearnAnnouncement;
 use benilla_protocol::messages::{ActionButton, SpellCooldown};
 use bevy::prelude::*;
 
-use crate::cooldowns::Cooldowns;
+use super::cast_target::CastTargeting;
+use super::{
+    ActiveChannel, AutoRepeatActive, CastCommit, CastLadder, Cooldowns, PendingCast,
+    QueuedMeleeSpell,
+};
 use crate::creature_anim::{CastEvent, CastEventKind, Casting, SpellGoTargets};
-use crate::ui_action::{AutoRepeatActive, CastErrors, PlayerActions, Spells, UiError, UiErrorKeys};
+use crate::ui_action::{CastErrors, PlayerActions, Spells, UiError, UiErrorKeys};
 use crate::ui_aura::AuraDurations;
-use crate::ui_cast::{ActiveChannel, CastBarEdge, CastBarFeed, PendingCast, QueuedMeleeSpell};
+use crate::ui_cast::{CastBarEdge, CastBarFeed};
 use crate::ui_spellbook::LearnedInTab;
 
-use super::super::{GuidIndex, ObjectStore, SelfGuid};
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::ecs::system::SystemParam;
+
+use crate::net::{GuidIndex, NetCommands, NetHandlerApp, ObjectStore, SelfGuid, SelfPlayer};
+
+/// Register the spell's handlers — called from [`super::SpellPlugin`].
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::SpellBook, on_spell_book)
+        .net_handler(K::ActionButtons, on_action_buttons)
+        .net_handler(K::SpellLearned, on_spell_learned)
+        .net_handler(K::SpellRemoved, on_spell_removed)
+        .net_handler(K::SpellSuperceded, on_spell_superceded)
+        .net_handler(K::CastResult, on_cast_result)
+        .net_handler(K::SpellStart, on_spell_start)
+        .net_handler(K::SpellGo, on_spell_go)
+        .net_handler(K::SpellChainTargets, on_spell_chain_targets)
+        .net_handler(K::SpellFailedOther, on_spell_failed_other)
+        .net_handler(K::SpellDelayed, on_spell_delayed)
+        .net_handler(K::CancelAutoRepeat, on_cancel_auto_repeat)
+        .net_handler(K::SpellCooldowns, on_cooldown_packet)
+        .net_handler(K::CooldownEvent, on_cooldown_packet)
+        .net_handler(K::ClearCooldown, on_cooldown_packet)
+        .net_handler(K::CooldownCheat, on_cooldown_packet)
+        .net_handler(K::ItemCooldown, on_item_cooldown)
+        .net_handler(K::ChannelStart, on_channel)
+        .net_handler(K::ChannelUpdate, on_channel)
+        .net_handler(K::AuraDuration, on_aura_duration)
+        .net_handler(K::SpellModifier, on_spell_modifier);
+}
+
+/// The cast lifecycle's state and catalogs, as one parameter — what every handler here folds
+/// its packet into. The in-flight slot, the cooldowns and the modifiers are the spell's own
+/// (2328); the action store, the spellbook's learned-tab list, the aura durations and the pet
+/// bar are their windows', written here because the packet is the spell's. The cast reply's
+/// handler is the exception — it casts, so it takes the ladder instead ([`on_cast_result`]).
+#[derive(SystemParam)]
+pub(crate) struct Lifecycle<'w> {
+    self_guid: Res<'w, SelfGuid>,
+    index: Res<'w, GuidIndex>,
+    spells: Option<Res<'w, Spells>>,
+    net: Res<'w, NetCommands>,
+    actions: ResMut<'w, PlayerActions>,
+    learned_in_tab: ResMut<'w, LearnedInTab>,
+    cast_bar: ResMut<'w, CastBarFeed>,
+    pending: ResMut<'w, PendingCast>,
+    queued_melee: ResMut<'w, QueuedMeleeSpell>,
+    cooldowns: ResMut<'w, Cooldowns>,
+    auto_repeat: ResMut<'w, AutoRepeatActive>,
+    channel: ResMut<'w, ActiveChannel>,
+    aura_durations: ResMut<'w, AuraDurations>,
+    spell_mods: ResMut<'w, crate::spell::SpellModifiers>,
+    pet_bar: ResMut<'w, crate::ui_pet::PetBar>,
+    /// The PlayAnimation call-order counter: every animation-bearing message stamps `next()`,
+    /// in packet order.
+    play_seq: ResMut<'w, crate::creature_anim::PlaySeq>,
+}
+
+/// The scene a cast lands in — the streamed units, the item store, and the animation, text and
+/// loot sinks a resolve writes.
+#[derive(SystemParam)]
+pub(crate) struct Scene<'w, 's> {
+    commands: Commands<'w, 's>,
+    casting: Query<'w, 's, &'static Casting>,
+    engaged_self: Query<'w, 's, (), (With<crate::creature_anim::Engaged>, With<SelfPlayer>)>,
+    stores: Query<'w, 's, &'static mut ObjectStore>,
+    items: ResMut<'w, crate::items::Items>,
+    loot_latch: ResMut<'w, crate::ui_loot::LootLatch>,
+    damage_text: Res<'w, crate::combat_text::DamageTextGates>,
+    cast_events: MessageWriter<'w, CastEvent>,
+    go_targets: MessageWriter<'w, SpellGoTargets>,
+    text: MessageWriter<'w, crate::combat_text::CombatTextSpawn>,
+    go_lid: MessageWriter<'w, crate::go_anim::GoLidOpen>,
+    sheaths: MessageWriter<'w, crate::creature_anim::SheathRequest>,
+}
+
+/// The spell-book/action-bar pair → the action store the UI feed reads (`crate::ui_action`),
+/// sent once at login (and the bar again on server-side edits).
+fn on_spell_book(In(ev): In<SessionEvent>, mut l: Lifecycle) {
+    if let SessionEvent::SpellBook {
+        spell_ids,
+        cooldowns,
+    } = ev
+    {
+        spell_book(spell_ids, cooldowns, &mut l.actions, &mut l.cooldowns);
+    }
+}
+
+fn on_action_buttons(In(ev): In<SessionEvent>, mut l: Lifecycle) {
+    if let SessionEvent::ActionButtons { buttons } = ev {
+        action_buttons(buttons, &mut l.actions);
+    }
+}
+
+fn on_spell_learned(In(ev): In<SessionEvent>, mut l: Lifecycle, mut errors: ResMut<UiErrorKeys>) {
+    if let SessionEvent::SpellLearned { spell_id } = ev {
+        learned_spell(
+            spell_id,
+            &mut l.actions,
+            l.spells.as_deref(),
+            &mut errors,
+            &mut l.learned_in_tab,
+        );
+    }
+}
+
+fn on_spell_removed(In(ev): In<SessionEvent>, mut l: Lifecycle, mut errors: ResMut<UiErrorKeys>) {
+    if let SessionEvent::SpellRemoved { spell_id } = ev {
+        removed_spell(spell_id, &mut l.actions, l.spells.as_deref(), &mut errors);
+    }
+}
+
+fn on_spell_superceded(
+    In(ev): In<SessionEvent>,
+    mut l: Lifecycle,
+    mut errors: ResMut<UiErrorKeys>,
+) {
+    if let SessionEvent::SpellSuperceded {
+        old_spell_id,
+        new_spell_id,
+    } = ev
+    {
+        superceded_spell(
+            old_spell_id,
+            new_spell_id,
+            &mut l.actions,
+            l.spells.as_deref(),
+            &mut errors,
+            &mut l.learned_in_tab,
+        );
+    }
+}
+
+/// What `HandleCastResult` reaches beyond the ladder — the reply's own scene.
+#[derive(SystemParam)]
+pub(crate) struct Reply<'w, 's> {
+    self_guid: Res<'w, SelfGuid>,
+    index: Res<'w, GuidIndex>,
+    cast_bar: ResMut<'w, CastBarFeed>,
+    casting: Query<'w, 's, &'static Casting>,
+    cast_events: MessageWriter<'w, CastEvent>,
+    play_seq: ResMut<'w, crate::creature_anim::PlaySeq>,
+}
+
+/// `HandleCastResult 0x6e7330` — the one handler that *casts*. A reply whose spell names a
+/// `modalNextSpell` (column 38) chains it through the ladder in the same call, the reference's
+/// `0x6e74aa call 0x6e5a90` → `TryCast` (decision 2330): so this handler takes [`CastLadder`]
+/// and [`CastTargeting`] where the others take [`Lifecycle`] — the five spell-state fields the
+/// two would share are the ladder's — and reaches the rest through [`Reply`]. Before 2330 the
+/// chain was an outbox a `ui_action` drain emptied after the input pass; now the chained cast
+/// arms the in-flight slot before the next packet is handled, as in the reference.
+///
+/// The chained cast goes out at the **null target guid** — `0x6e74a6 push ebx; push ebx` with
+/// `ebx = 0` — so it binds through the ordinary target walk (`ArmCast 0x6e5250`: main-hand item
+/// bit, then the explicit guid, then the current selection), which is what
+/// [`CastTargeting::context`] hands the ladder when no guid is passed. And it takes **every
+/// rung**: the reference chains through `0x6e5a90` → `TryCast 0x6e4b60`, the same entry a button
+/// press uses, so a chained Auto Shot is range-checked, form-checked and GCD-checked exactly like
+/// a pressed one, and refuses with the same red line.
+fn on_cast_result(
+    In(ev): In<SessionEvent>,
+    mut ladder: CastLadder,
+    targeting: CastTargeting,
+    mut r: Reply,
+) {
+    if let SessionEvent::CastResult {
+        spell_id,
+        success,
+        reason,
+        arg,
+    } = ev
+    {
+        let chained = cast_result(
+            spell_id,
+            success,
+            reason,
+            arg,
+            &mut ladder.ecs,
+            &r.self_guid,
+            &r.index,
+            &mut ladder.cast_errors,
+            &r.casting,
+            &mut r.cast_events,
+            &mut r.cast_bar,
+            &mut ladder.pending,
+            &mut ladder.queued_melee,
+            &mut ladder.cooldowns,
+            &mut ladder.auto_repeat,
+            ladder.spells.as_deref(),
+            &ladder.commands,
+            r.play_seq.next(),
+        );
+        if let Some(next) = chained {
+            let ctx = targeting.context();
+            ladder.send(next, &ctx, CastCommit::Spell);
+        }
+    }
+}
+
+fn on_spell_start(In(ev): In<SessionEvent>, mut l: Lifecycle, mut sc: Scene) {
+    if let SessionEvent::SpellStart {
+        caster,
+        spell_id,
+        cast_flags,
+        cast_time_ms,
+        target,
+        ammo_display_id,
+    } = ev
+    {
+        spell_start(
+            caster,
+            spell_id,
+            cast_flags,
+            cast_time_ms,
+            target,
+            ammo_display_id,
+            &mut sc.commands,
+            &l.index,
+            &mut sc.cast_events,
+            &l.self_guid,
+            &mut l.cast_bar,
+            &mut l.pending,
+            l.spells.as_deref(),
+            l.play_seq.next(),
+        );
+    }
+}
+
+fn on_spell_go(In(ev): In<SessionEvent>, mut l: Lifecycle, mut sc: Scene) {
+    if let SessionEvent::SpellGo {
+        caster,
+        spell_id,
+        cast_flags,
+        hits,
+        misses,
+        target,
+        go_target,
+        dest,
+        ammo_display_id,
+        item_caster,
+    } = ev
+    {
+        let engaged = !sc.engaged_self.is_empty();
+        spell_go(
+            caster,
+            spell_id,
+            cast_flags,
+            hits,
+            misses,
+            target,
+            go_target,
+            dest,
+            ammo_display_id,
+            item_caster,
+            &mut sc.commands,
+            &l.index,
+            &sc.casting,
+            &mut sc.cast_events,
+            &mut sc.go_targets,
+            &l.self_guid,
+            &sc.stores,
+            &mut l.cast_bar,
+            &mut l.pending,
+            &mut l.queued_melee,
+            &mut sc.text,
+            *sc.damage_text,
+            &mut sc.go_lid,
+            &mut sc.loot_latch,
+            (
+                &mut l.cooldowns,
+                l.spells.as_deref(),
+                &mut sc.items,
+                &l.net,
+                &mut l.pet_bar,
+            ),
+            (&mut l.auto_repeat, &mut sc.sheaths, engaged),
+            l.play_seq.next(),
+        );
+    }
+}
+
+fn on_spell_chain_targets(In(ev): In<SessionEvent>, l: Lifecycle, mut sc: Scene) {
+    if let SessionEvent::SpellChainTargets {
+        caster,
+        spell_id,
+        targets,
+    } = ev
+    {
+        spell_chain_targets(caster, spell_id, targets, &mut sc.commands, &l.index);
+    }
+}
+
+fn on_spell_failed_other(In(ev): In<SessionEvent>, mut l: Lifecycle, mut sc: Scene) {
+    if let SessionEvent::SpellFailedOther { caster, spell_id } = ev {
+        spell_failed_other(
+            caster,
+            spell_id,
+            &mut sc.commands,
+            &l.index,
+            &sc.casting,
+            &mut sc.cast_events,
+            &l.self_guid,
+            &mut l.cast_bar,
+            &mut l.pending,
+            &mut l.queued_melee,
+            l.play_seq.next(),
+        );
+    }
+}
+
+fn on_spell_delayed(In(ev): In<SessionEvent>, mut l: Lifecycle) {
+    if let SessionEvent::SpellDelayed { caster, delay_ms } = ev {
+        spell_delayed(
+            caster,
+            delay_ms,
+            &l.self_guid,
+            &mut l.cast_bar,
+            &mut l.pending,
+        );
+    }
+}
+
+fn on_cancel_auto_repeat(In(ev): In<SessionEvent>, mut l: Lifecycle, mut sc: Scene) {
+    if let SessionEvent::CancelAutoRepeat = ev {
+        cancel_auto_repeat(
+            &mut l.auto_repeat,
+            &l.self_guid,
+            &l.index,
+            &mut sc.commands,
+            &l.net,
+        );
+    }
+}
+
+/// The four cooldown packets, each resolved once through [`addressed_store`] — ours or the
+/// pet's, by the caster guid.
+fn on_cooldown_packet(In(ev): In<SessionEvent>, mut l: Lifecycle) {
+    let Lifecycle {
+        self_guid,
+        spells,
+        cooldowns,
+        pet_bar,
+        ..
+    } = &mut l;
+    match ev {
+        SessionEvent::SpellCooldowns {
+            caster,
+            cooldowns: pairs,
+        } => {
+            if let Some(store) = addressed_store(caster, self_guid, cooldowns, pet_bar) {
+                spell_cooldowns(caster, pairs, spells.as_deref(), store);
+            }
+        }
+        SessionEvent::CooldownEvent { spell_id, caster } => {
+            if let Some(store) = addressed_store(caster, self_guid, cooldowns, pet_bar) {
+                cooldown_event(spell_id, caster, store);
+            }
+        }
+        SessionEvent::ClearCooldown { spell_id, caster } => {
+            if let Some(store) = addressed_store(caster, self_guid, cooldowns, pet_bar) {
+                clear_cooldown(spell_id, caster, store);
+            }
+        }
+        SessionEvent::CooldownCheat { caster } => {
+            if let Some(store) = addressed_store(caster, self_guid, cooldowns, pet_bar) {
+                cooldown_cheat(caster, store);
+            }
+        }
+        _ => {}
+    }
+}
+
+fn on_item_cooldown(In(ev): In<SessionEvent>, mut l: Lifecycle, sc: Scene) {
+    if let SessionEvent::ItemCooldown {
+        item_guid,
+        spell_id,
+    } = ev
+    {
+        item_cooldown(item_guid, spell_id, &l.index, &sc.stores, &mut l.cooldowns);
+    }
+}
+
+fn on_channel(In(ev): In<SessionEvent>, mut l: Lifecycle) {
+    match ev {
+        SessionEvent::ChannelStart {
+            spell_id,
+            duration_ms,
+        } => channel_start(spell_id, duration_ms, &mut l.channel, &mut l.cast_bar),
+        SessionEvent::ChannelUpdate { remaining_ms } => {
+            channel_update(remaining_ms, &mut l.channel, &mut l.cast_bar)
+        }
+        _ => {}
+    }
+}
+
+fn on_aura_duration(In(ev): In<SessionEvent>, mut l: Lifecycle, real_clock: Res<Time<Real>>) {
+    if let SessionEvent::AuraDuration { slot, remaining_ms } = ev {
+        aura_duration(
+            slot,
+            remaining_ms,
+            &mut l.aura_durations,
+            real_clock.elapsed_secs_f64(),
+        );
+    }
+}
+
+fn on_spell_modifier(In(ev): In<SessionEvent>, mut l: Lifecycle) {
+    if let SessionEvent::SpellModifier {
+        flat,
+        mask_bit,
+        op,
+        value,
+    } = ev
+    {
+        set_spell_modifier(flat, mask_bit, op, value, &mut l.spell_mods);
+    }
+}
+
+/// Which unit's cooldown store a wire cooldown packet addresses (decision 0982).
+///
+/// All four of them (`SMSG_SPELL_COOLDOWN`, `_COOLDOWN_EVENT`, `_CLEAR_COOLDOWN`,
+/// `_COOLDOWN_CHEAT`) carry a caster guid, and until the pet bar existed all four answered it the
+/// same way: "is it us? then apply, else drop" — four copies of a self-only assumption, each
+/// inside its own arm. Since the server sends a pet's cooldowns on the pet's guid, that
+/// assumption silently discarded every one of them. Resolving the guid ONCE, here, is what let the
+/// pet bar sweep for real without a second copy of any arm; it also matches the reference, whose
+/// `SMSG_COOLDOWN_CHEAT` handler wipes "the self/pet cooldown list" off exactly this test.
+///
+/// `None` = a guid we hold no store for (another player's pet, a stale packet): dropped, as the
+/// client drops an unknown guid.
+fn addressed_store<'a>(
+    caster: u64,
+    self_guid: &SelfGuid,
+    player: &'a mut crate::spell::Cooldowns,
+    pet: &'a mut crate::ui_pet::PetBar,
+) -> Option<&'a mut crate::spell::Cooldowns> {
+    if self_guid.0 == Some(caster) {
+        Some(player)
+    } else if pet.has_bar() && pet.spells.pet_guid == caster {
+        Some(&mut pet.cooldowns)
+    } else {
+        None
+    }
+}
 
 /// The player's spell book (`SMSG_INITIAL_SPELLS`, once at login) → the action store the UI feed
 /// reads (`crate::ui_action`), plus the active-cooldown list → the cooldown store (the wire
 /// carries *remaining* ms — [`Cooldowns::seed_initial`]'s law).
-pub(super) fn spell_book(
+fn spell_book(
     spell_ids: Vec<u32>,
     initial_cooldowns: Vec<SpellCooldown>,
     actions: &mut PlayerActions,
@@ -42,7 +491,7 @@ pub(super) fn spell_book(
 
 /// The player's saved action bar (`SMSG_ACTION_BUTTONS`, once at login, and again on server-side
 /// edits) → the action store the UI feed reads.
-pub(super) fn action_buttons(buttons: Vec<ActionButton>, actions: &mut PlayerActions) {
+fn action_buttons(buttons: Vec<ActionButton>, actions: &mut PlayerActions) {
     debug!("net: action bar — {} occupied slots", buttons.len());
     actions.buttons = buttons.into_iter().map(|b| (b.slot, b)).collect();
     actions.dirty = true;
@@ -56,7 +505,7 @@ pub(super) fn action_buttons(buttons: Vec<ActionButton>, actions: &mut PlayerAct
 /// It also **announces the learn in chat**, which is the reference's own tail on this packet and
 /// not a nicety: `0x5e61c0` -> `AddSpell(id, slot, 1, 1)` -> the registrar `0x4b25b0` with its
 /// announce flag set (decision 2243, [`announce_learn`]).
-pub(super) fn learned_spell(
+fn learned_spell(
     spell_id: u32,
     actions: &mut PlayerActions,
     spells: Option<&Spells>,
@@ -120,7 +569,7 @@ fn announce_learn(spell_id: u32, spells: Option<&Spells>, errors: &mut UiErrorKe
 /// [`crate::ui_action::LearnedAbilities`] re-derives off the same change (the reference's own
 /// unlearn write site, `0x4b2c50`). What happens to a **bar button** still pointing at the removed
 /// spell is a separate law this arm deliberately does not invent — see 1584's scope note.
-pub(super) fn removed_spell(
+fn removed_spell(
     spell_id: u32,
     actions: &mut PlayerActions,
     spells: Option<&Spells>,
@@ -159,7 +608,7 @@ fn announce_unlearn(spell_id: u32, spells: Option<&Spells>, errors: &mut UiError
 /// *here* as well would be a second, weaker copy of that law — weaker because this packet doesn't
 /// arrive at all when the rank was gained while the character was loading (vmangos suppresses it
 /// with `IsInWorld()`), which is exactly the case that shipped a dead rank-1 button.
-pub(super) fn superceded_spell(
+fn superceded_spell(
     old_spell_id: u32,
     new_spell_id: u32,
     actions: &mut PlayerActions,
@@ -181,7 +630,7 @@ pub(super) fn superceded_spell(
 }
 
 /// The server's verdict on our cast (`SMSG_CAST_RESULT`).
-pub(super) fn cast_result(
+fn cast_result(
     spell_id: u32,
     success: bool,
     reason: Option<u8>,
@@ -199,10 +648,8 @@ pub(super) fn cast_result(
     auto_repeat: &mut AutoRepeatActive,
     spells: Option<&Spells>,
     net: &crate::net::NetCommands,
-    // The `modalNextSpell` chain's outbox (`0x6e74aa`) — filled here, sent by the one cast path.
-    chain: &mut crate::ui_action::ChainCasts,
     seq: u64,
-) {
+) -> Option<u32> {
     debug!("net: cast result — spell {spell_id} success={success} reason={reason:?}");
     // **Is this the reply to the cast we have outstanding?** (`0x6e7408 cmp ecx,[0xceca88]`.) Read
     // BEFORE either arm touches the guard, because both the failure arm's clear below and the
@@ -210,13 +657,13 @@ pub(super) fn cast_result(
     // is finished on either outcome, and only then is column 38 read.
     let in_flight = pending.committed(Instant::now()) == Some(spell_id);
     if !success {
-        // The cast-fail cooldown edges (the client's `HandleCastFailed 0x6e1a00`, wow-re
-        // `wave-cooldown.md` + the 2026-07-10 §5): a plain interactive-cast failure clears ONLY
+        // The cast-fail cooldown edges (the client's `HandleCastFailed 0x6e1a00`): a plain
+        // interactive-cast failure clears ONLY
         // the GCD armed at send (`0x6e1d83 → 0x6e1630`) — the spell's own recovery was never
         // started pre-launch (it lands at SPELL_GO / SMSG_SPELL_COOLDOWN, which a failed cast
         // never reaches), so there is nothing else to revert — and a failing auto-repeat spell
-        // runs the FULL local cancel (byte-verified `0x6e1cd9`–`0x6e1cea`, wow-re
-        // `nocked-ammo-cancel.md`): iff the failing spellId == the cached auto-repeat spell AND
+        // runs the FULL local cancel (`0x6e1cd9`–`0x6e1cea`): iff the failing spellId == the
+        // cached auto-repeat spell AND
         // reason ≠ 0x17, the handler jumps into `0x6ea080` — the SAME routine the
         // SMSG_CANCEL_AUTO_REPEAT handler runs — clearing the key, the shooting-idle bits, and
         // the nocked ammo. A deselect/interrupt surfaces as this CAST_RESULT failure
@@ -298,7 +745,7 @@ pub(super) fn cast_result(
         }
     }
     // **The `modalNextSpell` chain — how a hunter starts shooting** (`HandleCastResult 0x6e7330`
-    // @ `0x6e7408`–`0x6e74aa`; wow-re `spell/scratch/modalnext-chain-cast.md`, decision 1597).
+    // @ `0x6e7408`–`0x6e74aa`; decision 1597).
     //
     // The reply to our in-flight cast finishes that cast's slot and then reads **column 38** of
     // the spell it names. Non-zero, and not already the running repeat ⇒ the client casts it,
@@ -320,6 +767,10 @@ pub(super) fn cast_result(
     //   sting while Auto Shot is already running must NOT re-cast it, or every special shot would
     //   restart the repeat and reset its swing timer. We have no pending-record to refresh, so the
     //   equal branch is simply "send nothing" — the same observable.
+    //
+    // The chained spell is this function's **return**: `on_cast_result` hands it to the ladder
+    // in the same call (`0x6e74aa call 0x6e5a90`), so the chained cast takes every rung a press
+    // takes and arms the in-flight slot before the next packet is handled (decision 2330).
     if in_flight {
         pending.clear_if(spell_id);
         if let Some(next) = spells
@@ -328,14 +779,15 @@ pub(super) fn cast_result(
             .filter(|&next| next != 0 && Some(next) != auto_repeat.0)
         {
             debug!("net: cast result {spell_id} chains modalNextSpell {next}");
-            chain.0.push(next);
+            return Some(next);
         }
     }
+    None
 }
 
 /// A unit began a non-triggered cast (`SMSG_SPELL_START`), instants included (`cast_time_ms == 0`)
 /// — the precast trigger the phase-2 casting animation loop builds on (decision 0099 phase 1).
-pub(super) fn spell_start(
+fn spell_start(
     caster: u64,
     spell_id: u32,
     cast_flags: u16,
@@ -361,7 +813,7 @@ pub(super) fn spell_start(
     );
     // The nocked-ammo refresh (the client's `0x60ba30` @ `0x6e78b6`, gated `SpellRec+0x20&0x20 OR
     // +0x18&0x2` at `0x6e78a1`, on the packet-resolved caster BEFORE the self/other split — any
-    // unit; wow-re `nocked-ammo-cancel.md`): a ranged spell's START either affirms the wire's
+    // unit): a ranged spell's START either affirms the wire's
     // ammo display id or, with the flag clear / id 0, detaches. The model persists through
     // Load/Hold and the fire clip — `SPELL_GO` never touches it.
     if spells
@@ -445,7 +897,7 @@ const GO_TYPE_CHEST: i32 = 3;
 /// nothing about missile travel rides this packet; the client (and we) rebuild the flight
 /// visually from the same Speed column (decision 0099 phase 4: the target lists go out as
 /// [`SpellGoTargets`] for the router's instant-impact/missile branch).
-pub(super) fn spell_go(
+fn spell_go(
     caster: u64,
     spell_id: u32,
     cast_flags: u16,
@@ -471,7 +923,7 @@ pub(super) fn spell_go(
     // gate the miss words below exactly as they gate a damage number (decision 2229).
     text_gates: crate::combat_text::DamageTextGates,
     go_lid: &mut MessageWriter<crate::go_anim::GoLidOpen>,
-    // The client-local loot-target latch — armed here for a chest (decision 1477, §6 above).
+    // The client-local loot-target latch — armed here for a chest (decision 1477, `0x6e831b`).
     loot_latch: &mut crate::ui_loot::LootLatch,
     // The cooldown store + what its start laws read (grouped: one arm-body concern). The last
     // member is the PET's store — the reference inserts into two banks from this one handler
@@ -486,7 +938,7 @@ pub(super) fn spell_go(
     // The GO-deferred melee auto-attack start's write set (`0x6e83c0`, the arm below), plus the
     // attack lock it gates on: our server-echoed `Engaged`, the ref's `[player+0xc48]`.
     attack_ctx: (
-        &mut crate::ui_action::AutoRepeatActive,
+        &mut crate::spell::AutoRepeatActive,
         &mut MessageWriter<crate::creature_anim::SheathRequest>,
         bool,
     ),
@@ -528,7 +980,7 @@ pub(super) fn spell_go(
     let (auto_repeat, sheath, engaged) = attack_ctx;
     let now = Instant::now();
     let display = spells.and_then(|s| s.catalog.get(spell_id));
-    // **A chest's loot-target arm** (wow-re `loot-anim-leg.md` §6, byte-verified §5 trio; decision
+    // **A chest's loot-target arm** (decision
     // 1477). `Spell_C::HandleSpellGo 0x6e7a70` reaches `0x6e831b call SetLootTarget 0x5ed5f0`,
     // which writes `[player+0x1d28]` and force-plays Loot 50 — so **this packet, not the loot
     // response, is when the reference starts kneeling at a chest**. Its gates, transcribed:
@@ -584,9 +1036,9 @@ pub(super) fn spell_go(
         // ring) opens exactly here, like the ref's inflight finish on the matching GO.
         queued_melee.clear_if(spell_id);
 
-        // **The GO-deferred melee auto-attack start** (`HandleSpellGo 0x6e7a70` @ `0x6e83c0`,
-        // wow-re `combat-feel-law.md` §A3; bytes re-read for decision 1593). This is the exact
-        // complement of the send-time tail in [`crate::ui_action::cast_send`]: a spell carrying
+        // **The GO-deferred melee auto-attack start** (`HandleSpellGo 0x6e7a70` @ `0x6e83c0`;
+        // bytes re-read for decision 1593). This is the exact
+        // complement of the send-time tail in [`crate::spell::cast_send`]: a spell carrying
         // `AttributesEx2 & 0x100000` has its optimistic start *suppressed* there and armed here
         // instead, so the swing begins only once the server confirms the strike landed. That is
         // the whole 5875 stealth-opener class — Backstab, Garrote, Ambush, Cheap Shot, Shred,
@@ -622,8 +1074,7 @@ pub(super) fn spell_go(
             }
         }
 
-        // Our own launch starts the cast's cooldown locally, at the GO — byte-VERIFIED (the
-        // 2026-07-10 wow-re follow-up, `wave-handlers.md` ADDENDUM): `HandleSpellGo 0x6e7a70`'s
+        // Our own launch starts the cast's cooldown locally, at the GO: `HandleSpellGo 0x6e7a70`'s
         // self-insert tail forks on the packet guid pair — itemCaster == caster ⇒ the NO-ITEM
         // spell leg (`0x6e8498`: SpellRec RecoveryTime/Category/CategoryRecoveryTime, onHold from
         // Attributes bit 25, start = the GO receive-time); an item cast takes the item leg
@@ -632,8 +1083,8 @@ pub(super) fn spell_go(
         // normal source — this insert is how a Charge sweep appears on vmangos, which sends no
         // cooldown packet for a plain cast. A pre-launch failure never reaches here, so nothing
         // needs reverting.
-        // The ranged-shot pad (the category scaler `0x6e2b60`, byte-verified — wow-re
-        // `ranged-cooldown-sweep.md`, decision 0378): a ranged-slot cast folds our live
+        // The ranged-shot pad (the category scaler `0x6e2b60`, decision 0378): a ranged-slot cast
+        // folds our live
         // `UNIT_FIELD_RANGEDATTACKTIME` (haste-scaled, server-written) into the category
         // recovery — the Throw/wand-Shoot button sweep, no server packet involved.
         let ranged_ms = display
@@ -643,7 +1094,8 @@ pub(super) fn spell_go(
                 stores.get(*e).ok()?.0.unit_ranged_attack_time()
             })
             .unwrap_or(0);
-        match item_caster.and_then(|g| items.object(g)?.object_entry()) {
+        // The item's entry off its own store — an item is an object in the index (2334).
+        match item_caster.and_then(|g| stores.get(*index.0.get(&g)?).ok()?.0.object_entry()) {
             Some(entry) => {
                 let use_spell = items
                     .template(entry, 0, net_commands)
@@ -705,7 +1157,7 @@ pub(super) fn spell_go(
     // Gate A applies to whichever unit the word lands over. Source-classified first (the color
     // law's K, inside every emitter): another caster's misses draw nothing.
     //
-    // **Two laws phase 2 left open, both closed by the 2229 §5.**
+    // **Two laws phase 2 left open, both closed by 2229.**
     //
     // *Timing* — `0x6e7d4e fld [SpellRec+0x94]; fcomp 0.0; test ah,0x44; jp 0x6e7e71` skips this
     // inline emit whenever `Spell.dbc` Speed is nonzero. A TRAVELLING spell's word is floated by
@@ -718,15 +1170,16 @@ pub(super) fn spell_go(
     // is spell-GOLD. The three CVar gates come with it — they are read inside `0x607140`, which
     // every word path calls, so `CombatDamage 0` silences these words too.
     if !misses.is_empty() && display.is_none_or(|d| d.speed == 0.0) {
-        if let Some(color) = super::combat_log::classify_source(caster, index, self_guid, stores)
-            .and_then(|source| {
-                crate::combat_text::damage_color(
-                    text_gates,
-                    source,
-                    crate::combat_text::melee_styled(display),
-                )
-            })
-        {
+        if let Some(color) = crate::combat_log::text::classify_source(
+            caster, index, self_guid, stores,
+        )
+        .and_then(|source| {
+            crate::combat_text::damage_color(
+                text_gates,
+                source,
+                crate::combat_text::melee_styled(display),
+            )
+        }) {
             for &(guid, code) in &misses {
                 let anchor_guid = if code == 11 { caster } else { guid };
                 if self_guid.0 == Some(anchor_guid) {
@@ -746,9 +1199,8 @@ pub(super) fn spell_go(
             }
         }
     }
-    // Keyed by spell id, like the client's reap `0x614150(spellId, 0)` (wow-re
-    // `spell-visual-lifecycle.md`): a triggered proc's GO landing mid-cast must not
-    // clear a *different* spell's precast state.
+    // Keyed by spell id, like the client's reap `0x614150(spellId, 0)`: a triggered proc's GO
+    // landing mid-cast must not clear a *different* spell's precast state.
     if let Some(&e) = index.0.get(&caster) {
         if casting.get(e).is_ok_and(|c| c.spell_id == spell_id) {
             commands.entity(e).remove::<Casting>();
@@ -757,7 +1209,7 @@ pub(super) fn spell_go(
         // producer of `unit+0xd44`, and the one that makes a non-channelled chain spell draw at
         // all. It must precede the CastEvent below: the router plays the cast kit off that event,
         // and the kit's chain proc consumes this array the same frame. Named approximation: the
-        // reference gates this leg on `0x6e4870`'s return, a predicate the §5 could not settle —
+        // reference gates this leg on `0x6e4870`'s return, a predicate still unsettled —
         // we fill unconditionally, which is harmless because consumption still needs a chain proc
         // and because every producer clears before it fills.
         fill_chain_hops(caster, e, &hits, commands, index);
@@ -799,7 +1251,7 @@ pub(super) fn spell_go(
 
 /// An observed cast was interrupted/cancelled (`SMSG_SPELL_FAILED_OTHER`) — ends the caster's
 /// `Casting` state seam the same as [`spell_go`].
-pub(super) fn spell_failed_other(
+fn spell_failed_other(
     caster: u64,
     spell_id: u32,
     commands: &mut Commands,
@@ -851,7 +1303,7 @@ pub(super) fn spell_failed_other(
 /// `startTime`/`maxValue` shift — the spark jumps back and the bar keeps running), so a hit no
 /// longer lets the bar finish early while the real cast runs on (decision 0256). Self-only on the
 /// wire, but the caster guid is on the packet — gate on it like every other own-cast edge.
-pub(super) fn spell_delayed(
+fn spell_delayed(
     caster: u64,
     delay_ms: u32,
     self_guid: &SelfGuid,
@@ -869,20 +1321,19 @@ pub(super) fn spell_delayed(
     }
 }
 
-/// `SMSG_CANCEL_AUTO_REPEAT` — the client's handler (`0x6e99d0` → `0x6ea080`, wow-re
-/// `wave-handlers.md`) clears the autorepeat key `0xceac30`, which is exactly what the action
+/// `SMSG_CANCEL_AUTO_REPEAT` — the client's handler (`0x6e99d0` → `0x6ea080`) clears the
+/// autorepeat key `0xceac30`, which is exactly what the action
 /// bar's flash/checked state reads — so the button's auto-repeat highlight goes out
 /// (`STOP_AUTOREPEAT_SPELL` fires off this edge in the UI feed). The shots themselves were
 /// always wire-paced (decision 0099 phase 5: every shot is its own `SPELL_GO`), and nothing
 /// stows (sheath-policy's "nothing sheathes on combat-end").
 ///
-/// **INTERIM (decision 0400 §2's dispatch, Q5):** the cancel also disarms the standing
+/// **INTERIM (decision 0400 §2):** the cancel also disarms the standing
 /// Load/Hold idle ([`crate::creature_anim::AutoRepeatArmed`] off) — the director's report: on
 /// the reference the shooting visibly STOPS when the server cancels (target too close), while
 /// our sticky arm kept the nock idle looping forever. Whether the real handler clears the
 /// `[+0xd58] & 0x200` idle bit (0131 recorded "no clearing writer") or the hold-pose layer
-/// merely makes the ref look still is the dispatched question; the verdict corrects this
-/// if the mechanism differs.
+/// merely makes the ref look still is open; this is corrected if the mechanism differs.
 ///
 /// **Live against vmangos, not dormant (corrected 2026-08-05).** The prior note here — "vmangos
 /// never sends this" — was wrong: `SpellCaster::InterruptSpell` (`SpellCaster.cpp:1826`) sends it
@@ -891,7 +1342,7 @@ pub(super) fn spell_delayed(
 /// `InterruptSpell(CURRENT_AUTOREPEAT_SPELL)` → `SendAutoRepeatCancel`). Movement does NOT
 /// (`_UpdateAutoRepeatSpell` interrupts only Category 351, the wand, when moving) — Auto Shot
 /// stays armed across a run, exactly like vanilla.
-pub(super) fn cancel_auto_repeat(
+fn cancel_auto_repeat(
     auto_repeat: &mut AutoRepeatActive,
     self_guid: &SelfGuid,
     index: &GuidIndex,
@@ -957,7 +1408,7 @@ fn pet_go_cooldown(
 /// own list). **Which unit's store** it lands in is the caller's decision
 /// ([`super::addressed_store`]): the four cooldown packets all carry a caster guid, and resolving
 /// it in one place is what let the pet bar have real cooldowns without a second copy of this arm.
-pub(super) fn spell_cooldowns(
+fn spell_cooldowns(
     caster: u64,
     pairs: Vec<(u32, u32)>,
     spells: Option<&Spells>,
@@ -976,27 +1427,33 @@ pub(super) fn spell_cooldowns(
 
 /// `SMSG_ITEM_COOLDOWN` (`0x6e95d0`) — the fixed 30 s use cooldown, keyed on the item instance's
 /// template entry (the client resolves the guid to its item record the same way).
-pub(super) fn item_cooldown(
+fn item_cooldown(
     item_guid: u64,
     spell_id: u32,
-    items: &crate::items::Items,
+    index: &GuidIndex,
+    stores: &Query<&mut ObjectStore>,
     cooldowns: &mut Cooldowns,
 ) {
     debug!("net: item cooldown — item {item_guid:#x} spell {spell_id}");
-    if let Some(entry) = items.object(item_guid).and_then(|o| o.object_entry()) {
+    let entry = index
+        .0
+        .get(&item_guid)
+        .and_then(|&e| stores.get(e).ok())
+        .and_then(|s| s.0.object_entry());
+    if let Some(entry) = entry {
         cooldowns.apply_wire_item_cooldown(entry, spell_id, Instant::now());
     }
 }
 
 /// `SMSG_COOLDOWN_EVENT` (`0x6e9670` → `0x6e3050(force=0)`) — start an on-hold cooldown's parked
 /// timers now (Stealth ends, Feign Death drops). Store chosen by [`super::addressed_store`].
-pub(super) fn cooldown_event(spell_id: u32, caster: u64, cooldowns: &mut Cooldowns) {
+fn cooldown_event(spell_id: u32, caster: u64, cooldowns: &mut Cooldowns) {
     debug!("net: cooldown event — spell {spell_id} on {caster:#x}");
     cooldowns.cooldown_event(spell_id, Instant::now());
 }
 
 /// `SMSG_CLEAR_COOLDOWN` (`0x6e9670` → `0x6e3050(force=1)`) — remove the spell's record outright.
-pub(super) fn clear_cooldown(spell_id: u32, caster: u64, cooldowns: &mut Cooldowns) {
+fn clear_cooldown(spell_id: u32, caster: u64, cooldowns: &mut Cooldowns) {
     debug!("net: clear cooldown — spell {spell_id} on {caster:#x}");
     cooldowns.clear_spell(spell_id);
 }
@@ -1004,14 +1461,14 @@ pub(super) fn clear_cooldown(spell_id: u32, caster: u64, cooldowns: &mut Cooldow
 /// `SMSG_COOLDOWN_CHEAT` (`0x6e9730` → `0x6e9700`) — the GM reset wipes the whole list. The
 /// reference's own handler wipes "the self/pet cooldown list" on a guid match, which is exactly
 /// what routing through [`super::addressed_store`] now reproduces.
-pub(super) fn cooldown_cheat(caster: u64, cooldowns: &mut Cooldowns) {
+fn cooldown_cheat(caster: u64, cooldowns: &mut Cooldowns) {
     debug!("net: cooldown cheat (wipe) for {caster:#x}");
     cooldowns.wipe();
 }
 
 /// `MSG_CHANNEL_START` — self-only on the wire (no guid), so it goes straight to the cast bar; the
 /// channel *animation* state rides the unit-field pair instead (decision 0137).
-pub(super) fn channel_start(
+fn channel_start(
     spell_id: u32,
     duration_ms: u32,
     channel: &mut ActiveChannel,
@@ -1025,11 +1482,7 @@ pub(super) fn channel_start(
 }
 
 /// `MSG_CHANNEL_UPDATE` — the running channel's remaining time (`0` is its stop edge).
-pub(super) fn channel_update(
-    remaining_ms: u32,
-    channel: &mut ActiveChannel,
-    feed: &mut CastBarFeed,
-) {
+fn channel_update(remaining_ms: u32, channel: &mut ActiveChannel, feed: &mut CastBarFeed) {
     channel.update(remaining_ms, Instant::now());
     feed.0.push(CastBarEdge::ChannelUpdate { remaining_ms });
 }
@@ -1037,12 +1490,7 @@ pub(super) fn channel_update(
 /// `SMSG_UPDATE_AURA_DURATION` — one of our own auras' remaining time (decisions 0255/0257), keyed
 /// by raw slot and stamped with the receive time. The `ui_aura` feed joins it to the aura in that
 /// slot by arrival order; it arrives *before* the descriptor delta that names the slot.
-pub(super) fn aura_duration(
-    slot: u8,
-    remaining_ms: u32,
-    durations: &mut AuraDurations,
-    now_secs: f64,
-) {
+fn aura_duration(slot: u8, remaining_ms: u32, durations: &mut AuraDurations, now_secs: f64) {
     durations.set(slot, remaining_ms, now_secs);
 }
 
@@ -1051,14 +1499,14 @@ pub(super) fn aura_duration(
 /// single store: the server sends the absolute value of that `(family bit, op)` pair, never a
 /// delta, so there is nothing to accumulate and nothing to invalidate.
 ///
-/// The out-of-range refusal lives on the store ([`crate::spell_mods::SpellModifiers::set`], which
+/// The out-of-range refusal lives on the store ([`crate::spell::SpellModifiers::set`], which
 /// documents why it is ours and not the reference's).
-pub(super) fn set_spell_modifier(
+fn set_spell_modifier(
     flat: bool,
     mask_bit: u8,
     op: u8,
     value: i32,
-    mods: &mut crate::spell_mods::SpellModifiers,
+    mods: &mut crate::spell::SpellModifiers,
 ) {
     mods.set(flat, mask_bit, op, value);
 }
@@ -1097,7 +1545,7 @@ fn fill_chain_hops(
 /// its GO handler), which is how a non-channeled chain spell draws at all. vmangos sends this one
 /// only for channelled spells (`Spell::SendChannelStart`), so on this server it is the drains'
 /// and Mind Flay's producer, and the GO leg is every other chain spell's.
-pub(super) fn spell_chain_targets(
+fn spell_chain_targets(
     caster: u64,
     spell_id: u32,
     targets: Vec<u64>,
@@ -1382,7 +1830,7 @@ mod tests {
             .init_resource::<PendingCast>()
             .init_resource::<QueuedMeleeSpell>()
             .init_resource::<Cooldowns>()
-            .init_resource::<crate::spell_mods::SpellModifiers>()
+            .init_resource::<crate::spell::SpellModifiers>()
             .init_resource::<crate::ui_pet::PetBar>()
             .init_resource::<crate::items::Items>();
 
@@ -1461,7 +1909,7 @@ mod tests {
                                 &mut pet_bar,
                             ),
                             (
-                                &mut crate::ui_action::AutoRepeatActive::default(),
+                                &mut crate::spell::AutoRepeatActive::default(),
                                 &mut sheath,
                                 false,
                             ),
@@ -1512,7 +1960,7 @@ mod tests {
     ///   display interrupted message even if they are interrupted";
     /// - the reference's own `SMSG_SPELL_FAILED_OTHER` handler (`0x6e8e40`, opcode `0x2a6`) fires
     ///   **no FrameScript event at all** — its whole body is `0x60d040` + `0x614150`, the *unit's*
-    ///   cast state, and wow-re's boundary line for it lists no `-> ui` edge;
+    ///   cast state, and it makes no call into the UI;
     /// - and stock `CastingBarFrame.lua` guards its red arm with `not this.channeling`.
     ///
     /// Ours lands on the same behaviour by a **fourth** route, which is the one worth pinning:
@@ -1612,7 +2060,7 @@ mod tests {
 
     /// **The GO's inline miss word: gold, gated, and only for an INSTANT spell** (decision 2229).
     ///
-    /// Phase 2 shipped this emit unconditional and hardcoded white. The §5 closed both halves:
+    /// Phase 2 shipped this emit unconditional and hardcoded white. The binary closes both halves:
     /// - `0x6e7d4e fld [SpellRec+0x94]; fcomp 0.0; test ah,0x44; jp 0x6e7e71` — a spell with a
     ///   **travel Speed** prints nothing here; its word rides the projectile's arrival instead
     ///   ([`crate::entities::MissileMiss`]). Sinister Strike (Speed 0) prints now; Fireball
@@ -1675,7 +2123,7 @@ mod tests {
                 .init_resource::<PendingCast>()
                 .init_resource::<QueuedMeleeSpell>()
                 .init_resource::<Cooldowns>()
-                .init_resource::<crate::spell_mods::SpellModifiers>()
+                .init_resource::<crate::spell::SpellModifiers>()
                 .init_resource::<crate::ui_pet::PetBar>()
                 .init_resource::<crate::items::Items>();
             let self_e = app
@@ -1751,7 +2199,7 @@ mod tests {
                                 &mut pet_bar,
                             ),
                             (
-                                &mut crate::ui_action::AutoRepeatActive::default(),
+                                &mut crate::spell::AutoRepeatActive::default(),
                                 &mut sheath,
                                 false,
                             ),
@@ -1844,7 +2292,7 @@ mod tests {
                 .init_resource::<PendingCast>()
                 .init_resource::<QueuedMeleeSpell>()
                 .init_resource::<Cooldowns>()
-                .init_resource::<crate::spell_mods::SpellModifiers>()
+                .init_resource::<crate::spell::SpellModifiers>()
                 .init_resource::<crate::ui_pet::PetBar>()
                 .init_resource::<crate::items::Items>();
             let self_e = app
@@ -1913,7 +2361,7 @@ mod tests {
                                 &mut pet_bar,
                             ),
                             (
-                                &mut crate::ui_action::AutoRepeatActive::default(),
+                                &mut crate::spell::AutoRepeatActive::default(),
                                 &mut sheath,
                                 false,
                             ),
@@ -1979,7 +2427,7 @@ mod tests {
             .init_resource::<PendingCast>()
             .init_resource::<QueuedMeleeSpell>()
             .init_resource::<Cooldowns>()
-            .init_resource::<crate::spell_mods::SpellModifiers>()
+            .init_resource::<crate::spell::SpellModifiers>()
             .init_resource::<crate::ui_pet::PetBar>()
             .init_resource::<crate::items::Items>();
 
@@ -2059,7 +2507,7 @@ mod tests {
                             &mut pet_bar,
                         ),
                         (
-                            &mut crate::ui_action::AutoRepeatActive::default(),
+                            &mut crate::spell::AutoRepeatActive::default(),
                             &mut sheath,
                             false,
                         ),
@@ -2110,7 +2558,7 @@ mod tests {
             .init_resource::<PendingCast>()
             .init_resource::<QueuedMeleeSpell>()
             .init_resource::<Cooldowns>()
-            .init_resource::<crate::spell_mods::SpellModifiers>()
+            .init_resource::<crate::spell::SpellModifiers>()
             .init_resource::<AutoRepeatActive>();
 
         let self_e = app
@@ -2164,7 +2612,6 @@ mod tests {
                             &mut auto_repeat,
                             None,
                             &net,
-                            &mut crate::ui_action::ChainCasts::default(),
                             1,
                         );
                     },
@@ -2329,7 +2776,7 @@ mod tests {
         assert!(errors.0.is_empty(), "…but the unlearn block does");
     }
     /// **The GO-deferred auto-attack start** (`HandleSpellGo` @ `0x6e83c0`, decision 1593) — the
-    /// half of `combat-feel-law.md` §A3 benilla shipped without, because ten hand-picked warrior
+    /// half of the auto-attack-on-cast law benilla shipped without, because ten hand-picked warrior
     /// rows were read as a census of `AttributesEx2 & 0x100000`. The real file carries the bit on
     /// 36, so the class that never started an auto-attack here is every stealth opener and
     /// positional strike: Backstab, Garrote, Ambush, Cheap Shot, Shred, Ravage, Pounce, Judgement.
@@ -2392,7 +2839,7 @@ mod tests {
                 .init_resource::<PendingCast>()
                 .init_resource::<QueuedMeleeSpell>()
                 .init_resource::<Cooldowns>()
-                .init_resource::<crate::spell_mods::SpellModifiers>()
+                .init_resource::<crate::spell::SpellModifiers>()
                 .init_resource::<crate::ui_pet::PetBar>()
                 .init_resource::<crate::items::Items>();
             let self_e = app
@@ -2469,7 +2916,7 @@ mod tests {
                                 &mut pet_bar,
                             ),
                             (
-                                &mut crate::ui_action::AutoRepeatActive::default(),
+                                &mut crate::spell::AutoRepeatActive::default(),
                                 &mut sheath,
                                 engaged,
                             ),
@@ -2569,7 +3016,8 @@ mod tests {
         };
 
         // One CAST_RESULT for `spell_id`, with `in_flight` armed as the outstanding cast and
-        // `running` as the live auto-repeat. Returns (what got queued, is the guard still armed).
+        // `running` as the live auto-repeat. Returns (what the reply chains, is the guard still
+        // armed).
         let fire = |spell_id: u32, success: bool, in_flight: Option<u32>, running: Option<u32>| {
             let mut app = App::new();
             app.add_message::<CastEvent>()
@@ -2582,9 +3030,8 @@ mod tests {
                 .init_resource::<PendingCast>()
                 .init_resource::<QueuedMeleeSpell>()
                 .init_resource::<Cooldowns>()
-                .init_resource::<crate::spell_mods::SpellModifiers>()
-                .init_resource::<AutoRepeatActive>()
-                .init_resource::<crate::ui_action::ChainCasts>();
+                .init_resource::<crate::spell::SpellModifiers>()
+                .init_resource::<AutoRepeatActive>();
             let self_e = app.world_mut().spawn((Guid(10), SelfPlayer)).id();
             app.world_mut()
                 .resource_mut::<GuidIndex>()
@@ -2602,7 +3049,8 @@ mod tests {
             }
             let (tx, _rx) = crossbeam_channel::unbounded();
             let cat = spells();
-            app.world_mut()
+            let chained = app
+                .world_mut()
                 .run_system_once(
                     move |mut commands: Commands,
                           self_guid: Res<SelfGuid>,
@@ -2614,8 +3062,7 @@ mod tests {
                           mut pending: ResMut<PendingCast>,
                           mut queued_melee: ResMut<QueuedMeleeSpell>,
                           mut cooldowns: ResMut<Cooldowns>,
-                          mut auto_repeat: ResMut<AutoRepeatActive>,
-                          mut chain: ResMut<crate::ui_action::ChainCasts>| {
+                          mut auto_repeat: ResMut<AutoRepeatActive>| {
                         let net = crate::net::NetCommands(tx.clone());
                         cast_result(
                             spell_id,
@@ -2635,52 +3082,46 @@ mod tests {
                             &mut auto_repeat,
                             Some(&cat),
                             &net,
-                            &mut chain,
                             1,
-                        );
+                        )
                     },
                 )
                 .unwrap();
-            let queued = app
-                .world()
-                .resource::<crate::ui_action::ChainCasts>()
-                .0
-                .clone();
             let still_armed = app
                 .world()
                 .resource::<PendingCast>()
                 .in_flight(Instant::now());
-            (queued, still_armed)
+            (chained, still_armed)
         };
 
         // The ordinary case: the sting lands, and Auto Shot follows by itself.
         assert_eq!(
             fire(SERPENT_STING, true, Some(SERPENT_STING), None),
-            (vec![AUTO_SHOT], false),
+            (Some(AUTO_SHOT), false),
             "a successful sting chains Auto Shot, and clears the in-flight guard first"
         );
         // And a failed one does too — both results converge on the same block.
         assert_eq!(
             fire(SERPENT_STING, false, Some(SERPENT_STING), None).0,
-            vec![AUTO_SHOT],
+            Some(AUTO_SHOT),
             "a FAILED sting chains it as well (`0x6e735a jne` → the same `0x6e73eb`)"
         );
         // Already shooting: re-arm, never re-cast.
         assert_eq!(
             fire(SERPENT_STING, true, Some(SERPENT_STING), Some(AUTO_SHOT)).0,
-            Vec::<u32>::new(),
+            None,
             "Auto Shot already running: the equal branch sends nothing"
         );
         // Auto Shot's own replies terminate the chain.
         assert_eq!(
             fire(AUTO_SHOT, true, Some(AUTO_SHOT), Some(AUTO_SHOT)).0,
-            Vec::<u32>::new(),
+            None,
             "Auto Shot's own column 38 is 0 — no second hop"
         );
         // Not our in-flight cast (a proc's result, a stale reply): not ours to chain from.
         assert_eq!(
             fire(SERPENT_STING, true, Some(133), None).0,
-            Vec::<u32>::new(),
+            None,
             "a reply for a spell we do not have in flight chains nothing"
         );
     }
diff --git a/crates/benilla-app/src/ui_action/targeting/cursor.rs b/crates/benilla-app/src/spell/targeting/cursor.rs
similarity index 96%
rename from crates/benilla-app/src/ui_action/targeting/cursor.rs
rename to crates/benilla-app/src/spell/targeting/cursor.rs
index 24f06b1b..f262ce33 100644
--- a/crates/benilla-app/src/ui_action/targeting/cursor.rs
+++ b/crates/benilla-app/src/spell/targeting/cursor.rs
@@ -1,6 +1,6 @@
 //! What the player *sees* while a cast waits for its click — the two classifier pre-empts and the
 //! numbers they compute: the ground point's range verdict (`CheckGroundPointInRange 0x6e6810`,
-//! inside `0x4820f0` — wow-re `cursor-system.md` §5), the hovered object's validity
+//! inside `0x4820f0`), the hovered object's validity
 //! (`0x6e6460`, inside `0x4828d0` — decision 0949), and the reticle's radius
 //! (`GetCurrentCastRadius 0x6e6350`).
 //!
@@ -21,7 +21,7 @@ use super::{SpellTargeting, TargetingWants};
 
 /// `CheckGroundPointInRange 0x6e6810` — min²/max² from the spell's `SpellRange` row against the
 /// squared caster↔point distance. Its ONE caller binary-wide is the hover-cursor classifier
-/// (`0x4820f0` — wow-re `world-click-targeting.md` Q1's caller census): the verdict colours
+/// (`0x4820f0`): the verdict colours
 /// Cast/UnableCast and nothing else. The click never consults it, so neither does ours. No row
 /// (a failed DBC, an unknown spell) is permissive — the server validates every send anyway.
 fn ground_point_in_range(row: Option<&SpellRange>, self_pos: Vec3, point: Vec3) -> bool {
@@ -41,12 +41,12 @@ fn range_row(spells: Option<&Spells>, spell_id: u32) -> Option<&SpellRange> {
     spells.ranges.get(spells.catalog.get(spell_id)?.range_index)
 }
 
-/// `GetCurrentCastRadius 0x6e6350` (wow-re `ground-target-reticle.md` B2) — the reticle's
+/// `GetCurrentCastRadius 0x6e6350` — the reticle's
 /// radius: per-effect `radius + casterLevel × perLevel` over **EffectRadiusIndex[0] and [1]
 /// only** (slot 2 is never read by the client), the max with candidate 1 winning ties/NaN,
 /// clamped to 20.0 (`0x4820f0`'s `[0x804478]` literal — `min`, NaN → 20). `0.0` = no radius
 /// rows; the reticle then draws at its literal default size. Spell-mod op 6 (SPELLMOD_RADIUS) is
-/// not read here — the tables are live ([`crate::spell_mods`]), this consumer is not wired to
+/// not read here — the tables are live (`crate::spell::mods`), this consumer is not wired to
 /// them (the 0792 residual, same as the range gate).
 pub(crate) fn ground_cast_radius(spells: Option<&Spells>, spell_id: u32, level: u32) -> f32 {
     let Some(spells) = spells else { return 0.0 };
@@ -69,7 +69,7 @@ pub(crate) fn ground_cast_radius(spells: Option<&Spells>, spell_id: u32, level:
     r.min(20.0)
 }
 
-/// While targeting, the world cursor is the classifier's pre-empt (cursor-system §5). Runs right
+/// While targeting, the world cursor is the classifier's pre-empt (`0x4820f0`). Runs right
 /// after [`crate::target`]'s classifier in the target chain and overwrites its verdict.
 ///
 /// **That pre-emption is the WORLD's, and only the world's** (decisions 1055, 1061). This computes
@@ -126,7 +126,7 @@ pub(crate) fn drive_targeting_cursor(
         &Transform,
     )>,
     // Read-only here: the ask-once template request is made at object stream-in
-    // (`net::apply::objects`), never by this hover path, so a cold cache is a one-frame transient
+    // (`net::objects`), never by this hover path, so a cold cache is a one-frame transient
     // and not a permanent grey.
     lock_inputs: crate::target::lock::GoLockInputs,
     mut cursor: ResMut<WorldCursor>,
@@ -336,6 +336,7 @@ mod tests {
             world.init_resource::<crate::target::HoveredObject>();
             world.init_resource::<crate::go_templates::GameObjectTemplates>();
             world.init_resource::<crate::items::Items>();
+            world.init_resource::<crate::net::GuidIndex>();
             world.insert_resource(PickOcclusion {
                 distance: 10.0,
                 point,
@@ -351,7 +352,7 @@ mod tests {
             world.spawn((SelfPlayer, Transform::default()));
             world.resource_mut::<SpellTargeting>().enter(
                 2120,
-                crate::ui_action::CastCommit::Spell,
+                crate::spell::CastCommit::Spell,
                 word,
             );
             world
diff --git a/crates/benilla-app/src/ui_action/targeting/item.rs b/crates/benilla-app/src/spell/targeting/item.rs
similarity index 96%
rename from crates/benilla-app/src/ui_action/targeting/item.rs
rename to crates/benilla-app/src/spell/targeting/item.rs
index 6045513f..ccd201ce 100644
--- a/crates/benilla-app/src/ui_action/targeting/item.rs
+++ b/crates/benilla-app/src/spell/targeting/item.rs
@@ -117,14 +117,14 @@ pub(crate) fn item_bind_verdict(
         let sub_ok =
             item.subclass < 32 && def.equipped_item_subclass_mask & (1u32 << item.subclass) != 0;
         if !(class_ok && sub_ok) {
-            return ItemBind::Refuse(crate::ui_action::cast_target::ERR_INVALID_TARGET);
+            return ItemBind::Refuse(crate::spell::cast_target::ERR_INVALID_TARGET);
         }
     }
     if def.equipped_item_inventory_type_mask != 0
         && !(item.inventory_type < 32
             && def.equipped_item_inventory_type_mask & (1u32 << item.inventory_type) != 0)
     {
-        return ItemBind::Refuse(crate::ui_action::cast_target::ERR_INVALID_TARGET);
+        return ItemBind::Refuse(crate::spell::cast_target::ERR_INVALID_TARGET);
     }
     if let Some(new) = new {
         if new.binds && !item.already_bound && !confirmed && item.inventory_type != 0 {
@@ -164,7 +164,7 @@ pub(crate) fn commit_item_cast_on_pick(
     self_q: Query<&crate::net::ObjectStore, With<SelfPlayer>>,
     enchants: Option<Res<crate::items::Enchants>>,
     mut parked: ResMut<EnchantConfirmItem>,
-    mut ladder: crate::ui_action::CastLadder,
+    mut ladder: crate::spell::CastLadder,
 ) {
     let Some(mut script) = script else {
         return;
@@ -179,7 +179,7 @@ pub(crate) fn commit_item_cast_on_pick(
         match self_q
             .iter()
             .next()
-            .and_then(|store| crate::ui_items::slot_guid(&store.0, bag, slot0, &ladder.items))
+            .and_then(|store| crate::ui_items::slot_guid(&store.0, bag, slot0, &ladder.objects))
         {
             Some(guid) => asks.push((guid, false)),
             None => {
@@ -203,7 +203,7 @@ pub(crate) fn commit_item_cast_on_pick(
         // the bag needed it for the icon) binds ungated and lets the server judge, the same
         // permissive shape the rest of the click law uses.
         let entry = ladder
-            .items
+            .objects
             .object(item_guid)
             .and_then(|o| o.object_entry());
         let clicked = match entry {
@@ -222,18 +222,18 @@ pub(crate) fn commit_item_cast_on_pick(
             ladder.commit_targeted(
                 spell_id,
                 commit,
-                crate::ui_action::cast_send::TargetedBind::Item(item_guid),
+                crate::spell::cast_send::TargetedBind::Item(item_guid),
             );
             continue;
         };
         let cat = enchants.as_deref();
-        let fields = ladder.items.object(item_guid);
+        let fields = ladder.objects.object(item_guid);
         let item = ClickedItem {
             class,
             subclass,
             inventory_type,
             // `0x5da2c0`: already soulbound, or already carrying an enchant that binds. The
-            // item tooltip's §6 Soulbound override reads the SAME predicate — see
+            // item tooltip's Soulbound override reads the SAME predicate — see
             // [`crate::items::already_bound`].
             already_bound: fields.is_some_and(|f| crate::items::already_bound(f, cat)),
             existing_enchant: [0u8, 1]
@@ -284,7 +284,7 @@ pub(crate) fn commit_item_cast_on_pick(
                 ladder.commit_targeted(
                     spell_id,
                     commit,
-                    crate::ui_action::cast_send::TargetedBind::Item(item_guid),
+                    crate::spell::cast_send::TargetedBind::Item(item_guid),
                 );
             }
         }
@@ -300,7 +300,7 @@ pub(crate) fn commit_item_cast_on_pick(
         ladder.commit_targeted(
             spell_id,
             commit,
-            crate::ui_action::cast_send::TargetedBind::Item(item_guid),
+            crate::spell::cast_send::TargetedBind::Item(item_guid),
         );
     }
 }
@@ -354,12 +354,12 @@ mod tests {
         );
         assert_eq!(
             item_target_refusal(&bracer, CLASS_ARMOR, 1, INVTYPE_CHEST),
-            Some(crate::ui_action::cast_target::ERR_INVALID_TARGET),
+            Some(crate::spell::cast_target::ERR_INVALID_TARGET),
             "the inventory-type leg (495e4d) refuses a chestpiece"
         );
         assert_eq!(
             item_target_refusal(&bracer, CLASS_WEAPON, 1, INVTYPE_WRIST),
-            Some(crate::ui_action::cast_target::ERR_INVALID_TARGET),
+            Some(crate::spell::cast_target::ERR_INVALID_TARGET),
             "the class leg (495e10) refuses a weapon"
         );
 
@@ -383,7 +383,7 @@ mod tests {
         );
         assert_eq!(
             item_target_refusal(&poison, CLASS_ARMOR, SUB_SHIELD, 14),
-            Some(crate::ui_action::cast_target::ERR_INVALID_TARGET),
+            Some(crate::spell::cast_target::ERR_INVALID_TARGET),
             "a shield is armor — the class leg alone stops it"
         );
 
@@ -408,7 +408,7 @@ mod tests {
         // nonsense, so the gate refuses instead of wrapping.
         assert_eq!(
             item_target_refusal(&poison, CLASS_WEAPON, 40, 13),
-            Some(crate::ui_action::cast_target::ERR_INVALID_TARGET)
+            Some(crate::spell::cast_target::ERR_INVALID_TARGET)
         );
     }
 
@@ -549,7 +549,7 @@ mod tests {
         };
         assert_eq!(
             item_bind_verdict(&bracer_only, &enchanted, binder, false),
-            ItemBind::Refuse(crate::ui_action::cast_target::ERR_INVALID_TARGET)
+            ItemBind::Refuse(crate::spell::cast_target::ERR_INVALID_TARGET)
         );
     }
 }
diff --git a/crates/benilla-app/src/ui_action/targeting/mod.rs b/crates/benilla-app/src/spell/targeting/mod.rs
similarity index 95%
rename from crates/benilla-app/src/ui_action/targeting/mod.rs
rename to crates/benilla-app/src/spell/targeting/mod.rs
index 9914b4f7..13c5c4e9 100644
--- a/crates/benilla-app/src/ui_action/targeting/mod.rs
+++ b/crates/benilla-app/src/spell/targeting/mod.rs
@@ -11,8 +11,7 @@
 //! bag click and the world click at once.
 //!
 //! This file is the **state and the input plumbing**; the three seams and the cursor live beside
-//! it, each transcribing a byte-verified piece (wow-re `wave-cast.md` + `cursor-system.md` §5 +
-//! `world-click-targeting.md`, plus 0923's own read of the two pickup seams):
+//! it, each transcribing a piece of the reference (the two pickup seams from 0923's own read):
 //!
 //! - [`cursor`] — while targeting, the world classifier is pre-empted (the ref's dispatcher step 2
 //!   runs before any object resolve), and the verdict is **per-seam** (decision 0949): the pick
@@ -33,7 +32,7 @@
 //!   ([`EnchantConfirmItem`], the ref's `0xb4e3c0`) and return with the word still standing; their
 //!   Yes re-enters that same drain.
 //!
-//! All three end in **one commit tail** ([`crate::ui_action::CastLadder::commit_targeted`]): the
+//! All three end in **one commit tail** ([`crate::spell::CastLadder::commit_targeted`]): the
 //! packet (`SendCast 0x6e54f0`'s same block, two opcodes), the pending arm, the GCD, and the word
 //! cleared.
 //!
@@ -44,12 +43,12 @@
 //! mode clears the word and sends **nothing**.
 //!
 //! Entry and the two press-cancel shapes live in the cast path itself: the resolver yields
-//! [`crate::ui_action::cast_target::CastWireTarget::Targeting`] carrying the word, the one
+//! [`crate::spell::cast_target::CastWireTarget::Targeting`] carrying the word, the one
 //! cast-send path enters the mode here, a NEW spell's press aborts-and-proceeds (`TryCast
 //! 6e4d62`), and the action bar's re-press of the SAME spell toggles the mode off (`UseAction
 //! 0x4e5ee0`'s `GetTargetingSpellId`+`StopTargeting` — [`crate::ui_action::drain`]).
 //!
-//! The click path is byte-pinned by wow-re's `world-click-targeting.md`: the terrain-leg commit
+//! The reference's click path: the terrain-leg commit
 //! `0x492580` has **no range gate and no error path** — it binds and sends regardless, and the
 //! server judges range (`CheckGroundPointInRange 0x6e6810` has exactly ONE caller binary-wide, the
 //! hover classifier `0x4820f0`: its verdict colours the cursor and nothing else). The object leg
@@ -196,7 +195,7 @@ impl SpellTargeting {
 
     /// `BindLocation 0x6e60f0`'s own fork, as one read: which of the two location slots the
     /// terrain click binds this point to. Bit 5 (SOURCE) is tested **before** bit 6 (DEST) and
-    /// the arms are exclusive (wow-re `wave-cast.md` §0x6e60f0 + its caller census — a word
+    /// the arms are exclusive (`0x6e60f0` commits only once the word is 0 — a word
     /// carrying both takes two clicks and sends on the second; no 5875 spell carries both, so
     /// only the precedence is transcribed here, not the two-click walk). Decision 2218.
     fn location_bind(&self, point: [f32; 3]) -> Option<super::cast_send::TargetedBind> {
@@ -218,16 +217,16 @@ impl SpellTargeting {
 /// Right-click cancels targeting — on the **DOWN edge**, the reference's WorldFrame
 /// `OnMouseDown 0x483c40` → `0x492c20`: right button ∧ `IsTargeting` → `StopTargeting
 /// 0x6e4900`, no packet — and the handler returns 0, so the press keeps doing everything else
-/// it did (the turn-drag, the release's context click; we consume nothing either). Byte-pinned
-/// by wow-re `world-click-targeting.md` Q3, whose caller census is complete: this and the
+/// it did (the turn-drag, the release's context click; we consume nothing either). Of
+/// `StopTargeting`'s callers, this and the
 /// ESC/UseAction/TryCast paths are the ONLY input-band cancels — no keyboard caller exists.
 ///
 /// Two qualifications, transcribed: a held cursor payload pre-empts the cancel (`0x492b50`
 /// clears the payload and returns before the WorldFrame virtuals dispatch — our payload keeps
 /// its own clean-click clear in [`crate::target::click::world_right_click_payload`]); and a
 /// press over a UI frame never reaches the WorldFrame — [`WorldRightPress`]'s world gate
-/// transcribes the certain half of wow-re's one DEFERRED (whether a UI-frame right-click also
-/// cancels is unpinned there). The `0x51`-effect placement-rotate skip (`[0xceca90]`) is
+/// transcribes the certain half of the one open question (whether a UI-frame right-click also
+/// cancels is unsettled). The `0x51`-effect placement-rotate skip (`[0xceca90]`) is
 /// unmodelled along with the flag itself (named residual, 0792).
 pub(crate) fn cancel_targeting_on_right_press(
     mut presses: MessageReader<WorldRightPress>,
diff --git a/crates/benilla-app/src/ui_action/targeting/world.rs b/crates/benilla-app/src/spell/targeting/world.rs
similarity index 94%
rename from crates/benilla-app/src/ui_action/targeting/world.rs
rename to crates/benilla-app/src/spell/targeting/world.rs
index 32aa41df..c907e39c 100644
--- a/crates/benilla-app/src/ui_action/targeting/world.rs
+++ b/crates/benilla-app/src/spell/targeting/world.rs
@@ -1,6 +1,6 @@
 //! The **world** click's two commits — the two legs of the reference's click dispatcher
 //! `0x492ce0`, which while targeting are chosen by the *pending spell's word*, not by the scene
-//! (wow-re `world-click-targeting.md` §2: the pick flags `0x481050` builds come only from
+//! (the pick flags `0x481050` builds come only from
 //! `0xcecac0` when `IsTargeting`).
 //!
 //! - **terrain leg** (`0x492c90` → `0x492580` → `BindLocation 0x6e60f0`) — [`commit_ground_cast_on_click`]
@@ -14,17 +14,17 @@
 //!
 //! Neither leg gates on range, validity or the lock. `0x492580`'s complete callee set contains no
 //! range call and no error emitter, and the object leg's `BindTarget` arm reads nothing but the
-//! clicked object's typemask and the word (wow-re C2 REFUTED). The server judges; its refusing
+//! clicked object's typemask and the word. The server judges; its refusing
 //! `SMSG_CAST_RESULT` is the red line.
 
 use bevy::prelude::*;
 
 use benilla_assets::coords::bevy_to_wow;
 
+use crate::spell::cast_send::TargetedBind;
 use crate::target::go_is_nearest;
 #[cfg(test)]
 use crate::target::{Hovered, HoveredObject};
-use crate::ui_action::cast_send::TargetedBind;
 use benilla_world::interact::WorldClick;
 
 use super::TargetingWants;
@@ -33,7 +33,7 @@ use super::TargetingWants;
 /// anything else the click could mean; [`crate::target::click::select_on_click`] holds its gate
 /// while this mode is active, so the click neither selects nor deselects). Binds the frame's
 /// pick-occlusion point and sends **unconditionally** — the leg's complete callee set has no
-/// range check and no error path (wow-re `world-click-targeting.md` Q1; C2 REFUTED: the click
+/// range check and no error path (the click
 /// never gates on range, the server judges it, and its refusing `SMSG_CAST_RESULT` is the red
 /// line) — `CMSG_CAST_SPELL` mask `0x40` + the point (WoW coords), arming the pending cast +
 /// the GCD (the `SendCast 0x6e54f0` tail's two live pieces for a ground cast); the mode ends
@@ -46,7 +46,7 @@ pub(crate) fn commit_ground_cast_on_click(
     // The point the PRESS ray hit, not this frame's — the reference's `+0x360`, written by the one
     // down-edge pick and read unchanged at the release (decision 1122).
     press: Res<crate::target::PressPick>,
-    mut ladder: crate::ui_action::CastLadder,
+    mut ladder: crate::spell::CastLadder,
 ) {
     let occlusion = press.occlusion;
     if !ladder.ground.active() {
@@ -122,7 +122,7 @@ pub(crate) fn commit_object_cast_on_click(
     // The press's pick, as in the terrain leg — the object a gesture binds is the one it started
     // on, whatever the mouse did after (decision 1122).
     press: Res<crate::target::PressPick>,
-    mut ladder: crate::ui_action::CastLadder,
+    mut ladder: crate::spell::CastLadder,
 ) {
     let (hovered, hovered_object) = (press.hovered, press.object);
     if !ladder.ground.active() {
@@ -174,13 +174,14 @@ mod tests {
         let mut world = World::new();
         world.insert_resource(NetCommands(tx));
         world.init_resource::<crate::items::Items>();
-        world.init_resource::<crate::ui_cast::PendingCast>();
-        world.init_resource::<crate::ui_cast::QueuedMeleeSpell>();
-        world.init_resource::<crate::cooldowns::Cooldowns>();
-        world.init_resource::<crate::spell_mods::SpellModifiers>();
+        world.init_resource::<crate::net::GuidIndex>();
+        world.init_resource::<crate::spell::PendingCast>();
+        world.init_resource::<crate::spell::QueuedMeleeSpell>();
+        world.init_resource::<crate::spell::Cooldowns>();
+        world.init_resource::<crate::spell::SpellModifiers>();
         world.init_resource::<crate::ui_action::CastErrors>();
         world.init_resource::<crate::ui_action::UiErrorKeys>();
-        world.init_resource::<crate::ui_action::AutoRepeatActive>();
+        world.init_resource::<crate::spell::AutoRepeatActive>();
         world.init_resource::<crate::ui_tradeskill::TradeSkillOpens>();
         world.init_resource::<super::super::SpellTargeting>();
         world.init_resource::<Messages<crate::creature_anim::SheathRequest>>();
@@ -220,7 +221,7 @@ mod tests {
     fn the_terrain_click_binds_source_or_dest_by_the_standing_word() {
         const BLIZZARD: u32 = 10;
         const AREA_DEATH: u32 = 265;
-        let commit = crate::ui_action::cast_send::CastCommit::Spell;
+        let commit = crate::spell::cast_send::CastCommit::Spell;
 
         let ground = |world: &mut World| {
             world.resource_mut::<crate::target::PressPick>().occlusion =
@@ -299,7 +300,7 @@ mod tests {
         let (mut world, rx, id) = fixture();
         world.resource_mut::<super::super::SpellTargeting>().enter(
             OPENING,
-            crate::ui_action::cast_send::CastCommit::Spell,
+            crate::spell::cast_send::CastCommit::Spell,
             LOCK_WORD,
         );
         hover_go(&mut world, 5.0);
@@ -322,7 +323,7 @@ mod tests {
     /// difference between a dead click and a wrong packet.
     #[test]
     fn the_object_commit_holds_its_fire() {
-        let commit = crate::ui_action::cast_send::CastCommit::Spell;
+        let commit = crate::spell::cast_send::CastCommit::Spell;
 
         // (a) Nothing armed: the click is not ours at all, and the reader is drained so it cannot
         // replay as a commit the frame the mode turns on.
diff --git a/crates/benilla-app/src/ui_action/usable.rs b/crates/benilla-app/src/spell/usable.rs
similarity index 93%
rename from crates/benilla-app/src/ui_action/usable.rs
rename to crates/benilla-app/src/spell/usable.rs
index c6889b16..357cba8b 100644
--- a/crates/benilla-app/src/ui_action/usable.rs
+++ b/crates/benilla-app/src/spell/usable.rs
@@ -1,14 +1,13 @@
-//! The plain-spell **usable walk** — `Spell_C::IsSpellUsableNow 0x6e3d60` (wow-re
-//! `action-button-state-api.md` §2a, byte-verified 2026-07-10), the compute behind
-//! `IsUsableAction`'s grey tint beyond the power gate. The §2a ordered gate table, transcribed;
+//! The plain-spell **usable walk** — `Spell_C::IsSpellUsableNow 0x6e3d60`, the compute behind
+//! `IsUsableAction`'s grey tint beyond the power gate. Its ordered gate table, transcribed;
 //! any tripped gate answers `(usable=false, oom=false)`, and ONLY the power leg (the last) sets
-//! `notEnoughMana` — the §5's B2, re-confirmed.
+//! `notEnoughMana`.
 //!
 //! Modeled legs: the TRADE_SKILL early-out · dead (leg 1) · reagents/totems (leg 3) · required
 //! equipped item (leg 4) · the combo-point gate (leg 5) · the shapeshift-form gate (leg 6,
 //! [`SpellDisplay::usable_in_form`]) · only-stealthed (leg 7) · not-in-combat (leg 8) ·
 //! CasterAuraState (leg 9) · TargetAuraState + its CanAttack/CanAssist fork (legs 10/10b — the
-//! ONE target-dependent pair, §5-proven: the current-target GUID globals `0xb4e2d8/dc` appear
+//! ONE target-dependent pair: the current-target GUID globals `0xb4e2d8/dc` appear
 //! nowhere earlier in the whole function, 0879; our per-frame diff-push recomputes it on target
 //! change for free, where the ref re-runs its cache on events) · the bit-25 cooldown fold
 //! (leg 11) · power (leg 12).
@@ -26,13 +25,13 @@ use benilla_formats::{
     SPELL_EFFECT_TRADE_SKILL,
 };
 
-use crate::cooldowns::Cooldowns;
 use crate::items::Items;
-use crate::net::{NetCommands, ObjectStore, Reputations};
-use crate::spell_mods::{SpellModifiers, OP_COST};
+use crate::net::{NetCommands, ObjectStore, Objects, Reputations};
+use crate::spell::Cooldowns;
+use crate::spell::{SpellModifiers, OP_COST};
 use crate::target::{can_attack, ring_reaction, Factions};
 
-use super::Spells;
+use crate::ui_action::Spells;
 
 /// Leg 8's caster unit-flag test — the shared bit, declared once ([`crate::player`]).
 use crate::player::UNIT_FLAG_IN_COMBAT;
@@ -99,6 +98,7 @@ fn hand_mask(d: &SpellDisplay) -> u32 {
 pub(crate) fn equipped_item_fits_cached(
     d: &SpellDisplay,
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
 ) -> bool {
     if d.equipped_item_class < 0
@@ -108,7 +108,7 @@ pub(crate) fn equipped_item_fits_cached(
         return true;
     }
     let mut mask = hand_mask(d);
-    if let Some(hidden) = crate::items::disarmed_equipment_slot_cached(store, items) {
+    if let Some(hidden) = crate::items::disarmed_equipment_slot_cached(store, objects, items) {
         mask &= !(1u32 << hidden);
     }
     equipped_slots_match(
@@ -117,7 +117,7 @@ pub(crate) fn equipped_item_fits_cached(
         d.equipped_item_class as u32,
         d.equipped_item_subclass_mask,
         |guid| {
-            let obj = items.object(guid)?;
+            let obj = objects.object(guid)?;
             let t = items.template_cached(obj.object_entry()?)?;
             Some(WornItem {
                 class: t.class,
@@ -161,6 +161,7 @@ pub(crate) fn equipped_item_reason(d: &SpellDisplay) -> u8 {
 pub(crate) fn equipped_item_fits(
     d: &SpellDisplay,
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
 ) -> bool {
@@ -194,11 +195,11 @@ pub(crate) fn equipped_item_fits(
     // probes and a mask edit, NOT by `GetWeapon` returning NULL — same ladder, same outcome, one
     // hand only). A disarmed warrior's Heroic Strike greys out and its tooltip requirement line
     // turns red; a disarmed dual-wielder's off-hand weapon still satisfies a hand-agnostic one.
-    if let Some(hidden) = crate::items::disarmed_equipment_slot(store, items, commands) {
+    if let Some(hidden) = crate::items::disarmed_equipment_slot(store, objects, items, commands) {
         mask &= !(1u32 << hidden);
     }
     equipped_slots_match(store, mask, class, d.equipped_item_subclass_mask, |guid| {
-        let (entry, durability, max_durability) = items.object(guid).and_then(|o| {
+        let (entry, durability, max_durability) = objects.object(guid).and_then(|o| {
             Some((
                 o.object_entry()?,
                 o.item_durability(),
@@ -282,15 +283,14 @@ fn equipped_slots_match(
 ///    ON_USE block — `rec+0x11c[i] > 0 && rec+0x130[i] == 0`, `6e3006`–`6e3023`, the same scan
 ///    behind [`benilla_protocol::messages::ItemInfo::use_spell`] — and asks
 ///    `0x6e1690(spellId, itemId = the item ENTRY)`. That predicate is the **on-hold-record** test,
-///    NOT a general on-cooldown one (wow-re `spell/scratch/gcd-power-gate.md` §3, which corrects
-///    `wave-cooldown.md`'s published gloss): it reads neither a running timed cooldown nor the
+///    NOT a general on-cooldown one: it reads neither a running timed cooldown nor the
 ///    GCD. So a potion mid-cooldown keeps its colour under its own sweep, and nothing on the bar
 ///    greys for the global cooldown. **The entry is the key**, not `0`: `0x6e2fc0` is the sole
 ///    consumer of `0x6e1690`'s item-keyed form image-wide (`6e3037 push esi`), every other caller
 ///    passing `0` — so querying leg 11's `(spell, 0)` form here would never find an item's own
 ///    parked record, which is how our cooldown store keys it (`(use_spell, entry)`).
 /// 3. **the plain-spell walk.** The resolver `0x4e5a50`'s ITEM arm hands that same first ON_USE
-///    spell back with `*outType = 0` **hard-written** (wow-re `action-button-state-api.md` §0), so
+///    spell back with `*outType = 0` **hard-written**, so
 ///    `4e51ab`/`4e51b0 je 0x4e521d` is taken and the button runs the entire
 ///    `Spell_C::IsSpellUsableNow 0x6e3d60` gate walk — [`spell_usable`] — exactly as a spell slot
 ///    does. **This is where food greys in combat**: every `Food`/`Drink` row in the shipped
@@ -298,8 +298,8 @@ fn equipped_slots_match(
 ///    `Attributes = 0x18000100`, bit 28 among them — [`ATTR_NOT_IN_COMBAT`], the walk's leg 8. It
 ///    is not a food rule: 453 of the shipped rows carry that bit (bandages, mounts, disguises).
 /// 4. an item with **no** on-use spell resolves 0 and falls into the resolver-0 leg, whose ITEM-tag
-///    test answers `usable = 1` outright (`4e5127`–`4e5135`; §2b.3's consequence iv, "once the
-///    item-count and item-cooldown checks of §2 pass"). An equipped sword on the bar is
+///    test answers `usable = 1` outright (`4e5127`–`4e5135`, once the item-count and item-cooldown
+///    checks pass). An equipped sword on the bar is
 ///    full-colour, not grey — and so is an item whose template is still in flight, which is what
 ///    keeps a freshly-seen slot from flickering grey for a frame.
 ///
@@ -312,6 +312,7 @@ pub(crate) fn item_usable(
     held: bool,
     ctx: &UsableCtx,
     spells: Option<&Spells>,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
 ) -> (bool, bool) {
@@ -325,7 +326,7 @@ pub(crate) fn item_usable(
     let spell_id = use_spell.spell_id;
     let d = spells.and_then(|s| s.catalog.get(spell_id));
     // Gate 2, keyed as `0x6e2fc0` keys it: the item ENTRY as `0x6e1690`'s `itemId`, and the
-    // item's own resolved category where it has one (the `spellcategory[5]` override, §2c.4).
+    // item's own resolved category where it has one (the `spellcategory[5]` override, `6e171b`).
     let category = match use_spell.category {
         0 => d.map_or(0, |d| d.category),
         c => c,
@@ -336,7 +337,7 @@ pub(crate) fn item_usable(
     let (Some(d), Some(spells)) = (d, spells) else {
         return (false, false);
     };
-    spell_usable(spell_id, d, spells, ctx, items, commands)
+    spell_usable(spell_id, d, spells, ctx, objects, items, commands)
 }
 
 /// The walk. Returns `(usable, not_enough_mana)` — the `IsUsableAction` pair.
@@ -345,6 +346,7 @@ pub(crate) fn spell_usable(
     d: &SpellDisplay,
     spells: &Spells,
     ctx: &UsableCtx,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
 ) -> (bool, bool) {
@@ -369,10 +371,10 @@ pub(crate) fn spell_usable(
         }
     }
     // Leg 4 (`0x6e40e0`): some worn item must match the class + subclass mask.
-    if !equipped_item_fits(d, ctx.store, items, commands) {
+    if !equipped_item_fits(d, ctx.store, objects, items, commands) {
         return (false, false);
     }
-    // Leg 5 (`0x6e3e7a`–`0x6e3eb2`): the combo-point gate, §5-VERIFIED end to end (0879). A
+    // Leg 5 (`0x6e3e7a`–`0x6e3eb2`): the combo-point gate (0879). A
     // `test [SpellRec+0x1c], 0x500000` selects finishing moves — ONE any-of test with one jcc, so
     // `AttributesEx` b20 and b22 never fork — and then `mov al,[ecx+0x1029]; test al,al` fails the
     // leg when the caster's combo-point byte is 0. That is `PLAYER_FIELD_BYTES` byte 1 off the
@@ -419,7 +421,7 @@ pub(crate) fn spell_usable(
     {
         return (false, false);
     }
-    // Legs 10/10b: the target's aura state — the walk's ONE target-dependent pair (§2a B1).
+    // Legs 10/10b: the target's aura state — the walk's ONE target-dependent pair (`0x6e3f58`).
     // No current target ⇒ unusable; then the aura-state bit; then the relation fork.
     if d.target_aura_state != 0 {
         let Some(target) = ctx.target_store else {
@@ -445,14 +447,14 @@ pub(crate) fn spell_usable(
             _ => {}
         }
     }
-    // Leg 11: ONLY a cooldown-on-event spell folds its cooldown into usable (B3) — and the
-    // predicate is the corrected `0x6e1690` (an on-hold-record test, wow-re `gcd-power-gate.md`
-    // §3): Stealth greys while its record is PARKED; once the event starts the clocks — and for
+    // Leg 11: ONLY a cooldown-on-event spell folds its cooldown into usable (`0x6e3fb8`) — and the
+    // predicate is the corrected `0x6e1690` (an on-hold-record test): Stealth greys while its
+    // record is PARKED; once the event starts the clocks — and for
     // every ordinary cooldown — the button never greys from here.
     if d.cooldown_on_event() && ctx.cooldowns.has_on_hold_record(spell_id, 0, d.category) {
         return (false, false);
     }
-    // Leg 12 (`0x6e3fba`–`0x6e3feb`): the power gate — the SOLE notEnoughMana writer (B2).
+    // Leg 12 (`0x6e3fba`–`0x6e3feb`): the power gate — the SOLE notEnoughMana writer.
     if !can_afford(d, ctx.store, ctx.spell_mods) {
         return (false, true);
     }
@@ -466,7 +468,7 @@ pub(crate) fn spell_usable(
 /// 0948 chose per type (base mana for mana spells — the vmangos basis — max pool otherwise,
 /// health included for negative types) — and then the talent cost cut, `SPELLMOD_COST` (op 14),
 /// which `0x6e31b0` applies inside itself at `6e32e3` through the integer applier `0x6e6af0`
-/// ([`crate::spell_mods`]). One law, every consumer: the usable walk's leg 12, the press-path
+/// (`crate::spell::mods`). One law, every consumer: the usable walk's leg 12, the press-path
 /// power gate (0948), and the tooltip's cost cell (1074) — mirroring the byte fn's own caller
 /// set (`0x609657`/`0x60968d`/`0x4e5201`/`0x6e3fdb`/`0x52e8ad`/`0x507de3`). The reference's
 /// per-school unit mods are still not modeled — what remains of 0948's standing gap.
@@ -559,8 +561,7 @@ mod tests {
             for (i, (field, guid)) in hands.iter().enumerate() {
                 pairs.push((*field, *guid as u32));
                 let entry = 500 + i as u32;
-                deps.items
-                    .insert_object(*guid, ObjectFields::from_pairs(&[(3, entry)]));
+                deps.spawn_item(*guid, ObjectFields::from_pairs(&[(3, entry)]));
                 deps.items.insert_template(
                     entry,
                     Some(benilla_protocol::messages::ItemInfo {
@@ -571,7 +572,9 @@ mod tests {
                 );
             }
             let store = ObjectStore(ObjectFields::from_pairs(&pairs));
-            equipped_item_fits(&needs_a_weapon, &store, &deps.items, &deps.commands)
+            deps.with_objects(|objects, items, commands| {
+                equipped_item_fits(&needs_a_weapon, &store, objects, items, commands)
+            })
         };
 
         // CONTROL — armed, the sword satisfies it.
@@ -615,7 +618,7 @@ mod tests {
             for (i, (field, guid, flags, max_dur, dur)) in hands.iter().enumerate() {
                 pairs.push((*field, *guid as u32));
                 let entry = 500 + i as u32;
-                deps.items.insert_object(
+                deps.spawn_item(
                     *guid,
                     ObjectFields::from_pairs(&[
                         (3, entry),
@@ -634,7 +637,9 @@ mod tests {
                 );
             }
             let store = ObjectStore(ObjectFields::from_pairs(&pairs));
-            equipped_item_fits(d, &store, &deps.items, &deps.commands)
+            deps.with_objects(|objects, items, commands| {
+                equipped_item_fits(d, &store, objects, items, commands)
+            })
         };
 
         let sound = |field| (field, 0x2au64, 0u32, 0u32, 0u32);
@@ -687,8 +692,7 @@ mod tests {
                 let guid = 0x2a + i as u64;
                 pairs.push((*field, guid as u32));
                 let entry = 500 + i as u32;
-                deps.items
-                    .insert_object(guid, ObjectFields::from_pairs(&[(3, entry)]));
+                deps.spawn_item(guid, ObjectFields::from_pairs(&[(3, entry)]));
                 deps.items.insert_template(
                     entry,
                     Some(benilla_protocol::messages::ItemInfo {
@@ -699,17 +703,20 @@ mod tests {
                 );
             }
             let store = ObjectStore(ObjectFields::from_pairs(&pairs));
-            equipped_item_fits(
-                &SpellDisplay {
-                    equipped_item_class: 2,
-                    equipped_item_subclass_mask: 1 << 7, // Sword1H
-                    attributes_ex3: ex3,
-                    ..Default::default()
-                },
-                &store,
-                &deps.items,
-                &deps.commands,
-            )
+            deps.with_objects(|objects, items, commands| {
+                equipped_item_fits(
+                    &SpellDisplay {
+                        equipped_item_class: 2,
+                        equipped_item_subclass_mask: 1 << 7, // Sword1H
+                        attributes_ex3: ex3,
+                        ..Default::default()
+                    },
+                    &store,
+                    objects,
+                    items,
+                    commands,
+                )
+            })
         };
 
         // Dual-wielding, armed: both abilities are usable.
@@ -748,20 +755,23 @@ mod tests {
         let items = Items::default();
         let (tx, _rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
-        let carried = crate::ui_items::carried_counts(&store.0, &items);
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
+        let carried = crate::ui_items::carried_counts(&store.0, &objects);
         let spell_mods = SpellModifiers::default();
         spell_usable(
             1,
             d,
             &spells,
             &ctx(store, &cooldowns, &reputations, &carried, &spell_mods),
+            &objects,
             &items,
             &commands,
         )
     }
 
     /// **The behavioural half of the spell-modifier system, and the reason op 14 is the first op
-    /// wired** (wow-re `spellmod-table-law.md` §9): the press-path gate compares the caster's
+    /// wired**: the press-path gate compares the caster's
     /// power against [`power_cost`] and, when short, refuses locally and sends **no**
     /// `CMSG_CAST_SPELL` at all (`0x609657`'s fall-through failure block). With the tables unread,
     /// a talent-discounted spell the server would happily accept is refused by the client.
@@ -807,7 +817,7 @@ mod tests {
         assert_eq!(power_cost(&other_class, &store, &mods), 100);
     }
 
-    /// Each modeled gate trips alone, and only the power leg raises notEnoughMana (B2).
+    /// Each modeled gate trips alone, and only the power leg raises notEnoughMana (`0x6e3feb`).
     #[test]
     fn gates_trip_independently_and_only_power_sets_oom() {
         let alive = player(&[]);
@@ -933,7 +943,9 @@ mod tests {
 
         let healthy = ObjectStore(ObjectFields::from_pairs(&[(22, 100), (125, 0)]));
         let low = ObjectStore(ObjectFields::from_pairs(&[(22, 10), (125, 0x2)]));
-        let carried = crate::ui_items::carried_counts(&me.0, &items);
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
+        let carried = crate::ui_items::carried_counts(&me.0, &objects);
         for (target, expect) in [(&healthy, false), (&low, true)] {
             let ctx = UsableCtx {
                 store: &me,
@@ -945,7 +957,7 @@ mod tests {
                 spell_mods: &SpellModifiers::default(),
             };
             assert_eq!(
-                spell_usable(5308, &execute, &spells, &ctx, &items, &commands),
+                spell_usable(5308, &execute, &spells, &ctx, &objects, &items, &commands),
                 (expect, false)
             );
         }
diff --git a/crates/benilla-app/src/spell/validator.rs b/crates/benilla-app/src/spell/validator.rs
new file mode 100644
index 00000000..63abd0a0
--- /dev/null
+++ b/crates/benilla-app/src/spell/validator.rs
@@ -0,0 +1,853 @@
+//! **The requirement validator's rungs** — `Spell_C`'s `0x6094f0`, the press-time gates
+//! `TryCast 0x6e4b60` runs between the target bind and the commit, plus the range compare
+//! `IsTargetInRange 0x6e47b0` that `CanTargetUnit 0x6e4440` runs just before it. Pure
+//! predicates over the caster's fields and the spell record, each answering the reference's own
+//! reason code; [`super::cast_send`]'s ladder calls them in the reference's order, and the two
+//! casts still outside the ladder (the world click's skin cast and the corpse insignia,
+//! `crate::target::click`) ask the mounted one directly.
+//!
+//! Until decision 2330 these sat in `ui_action`'s dynamic-state feed, beside the `IsUsableAction`
+//! family they are not part of: the feed greys a button, the validator refuses a press, and the
+//! reference keeps them apart (`0x6094f0` is reached only from `TryCast`, never from the greying
+//! predicate `0x6e3d60`). Now they are the spell's, with the ladder.
+
+use benilla_formats::{SpellDisplay, SpellRange};
+
+/// The client's cast-fail reasons for the two range refusals ("Out of range." / "Target too
+/// close" in `crate::ui_action`'s cast-fail table) — what `CanTargetUnit 0x6e4440` emits when
+/// `IsTargetInRange 0x6e47b0` fails on its max² / min² compare.
+pub(super) const ERR_OUT_OF_RANGE: u8 = 0x59;
+pub(super) const ERR_TOO_CLOSE: u8 = 0x76;
+
+/// The **pre-send** range refusal — the client's `TryCast` ladder runs `CanTargetUnit 0x6e4440`
+/// → `IsTargetInRange 0x6e47b0` BEFORE `ArmCast`/`SendCast`, so
+/// an out-of-range or too-close press fails locally and the commit tail — the ranged sheath
+/// snap `0x6e5930` included — never runs. This is why a too-close Throw/Auto Shot must NOT draw
+/// the ranged weapon. Squared 3D distance against [`benilla_formats::min_max_range`]'s {min, max}: beyond max² →
+/// [`ERR_OUT_OF_RANGE`], inside a nonzero min² → [`ERR_TOO_CLOSE`]. Untestable inputs (no range
+/// row, unknown distance) pass — the server still judges the cast.
+pub(super) fn cast_range_refusal(
+    spell: &SpellDisplay,
+    row: Option<&SpellRange>,
+    self_reach: f32,
+    target_reach: Option<f32>,
+    dist_sq: Option<f32>,
+) -> Option<u8> {
+    let (min, max) = benilla_formats::min_max_range(spell, row, self_reach, target_reach)?;
+    let d2 = dist_sq?;
+    if d2 > max * max {
+        return Some(ERR_OUT_OF_RANGE);
+    }
+    if min > 0.0 && d2 < min * min {
+        return Some(ERR_TOO_CLOSE);
+    }
+    None
+}
+
+/// `PreventionType` values (`Spell.dbc` column 165): which crowd-control flag can refuse this
+/// spell locally. `0` = neither.
+const PREVENTION_SILENCE: u32 = 1;
+const PREVENTION_PACIFY: u32 = 2;
+
+/// The **crowd-control leg** of the same requirement validator `0x6094f0`, sitting **above** its
+/// mounted block (`0x609c6c`) — so a stunned mounted caster is told about the stun (decision
+/// 1904). It refuses before any packet,
+/// which is why it must be local.
+///
+/// **Six arms, in the reference's order, first match wins** — 1863's fold-back recorded four:
+///
+/// | # | arm | gate | reason |
+/// |---|---|---|---|
+/// | 1 | CHARMED | `UNIT_FIELD_CHARMEDBY != 0` and the charmer is not us | `0x14` |
+/// | 2 | STUNNED | bit 18 — **no per-spell gate, every spell** | `0x64` |
+/// | 3 | SILENCED | bit 13 **and** `PreventionType == 1` | `0x60` |
+/// | 4 | PACIFIED | bit 17 **and** `PreventionType == 2` | `0x5a` |
+/// | 5 | FLEEING | bit 23 | `0x1e` |
+/// | 6 | CONFUSED | bit 22 | `0x16` |
+///
+/// The asymmetry is the finding: STUNNED, FLEEING, CHARMED and CONFUSED carry no per-spell gate at
+/// all, while SILENCED and PACIFIED run only where the spell's own `PreventionType` names them —
+/// so a silence stops casts and leaves melee abilities alone, and a pacify does the reverse.
+/// Reading `UNIT_FLAG_SILENCED` as "no casting" is the mistake this replaces.
+///
+/// **A dead caster skips all six** (`0x60980d`, a `jle` on `UNIT_FIELD_HEALTH`).
+///
+/// This ladder is **TryCast-only** — one caller, no address-takes — so a button does **not** grey
+/// while stunned, silenced or pacified: it refuses on the press. (Fear, confuse and charm *are*
+/// greyed, by a second copy of the same helpers inside `0x6e3d60`; that copy is not built here.)
+///
+/// Its byte-shape is a trap for a binary scan: SILENCED's read is `f6 c4 20 test ah,0x20`, a
+/// sub-register byte-lane form with no dword immediate, invisible to an immediate scan.
+///
+/// **The exemption scan is built** (decision 1946, closing 1925's deferral): each arm first asks
+/// whether any of the caster's own auras grants immunity to what is blocking it — a scan of
+/// `UNIT_FIELD_AURA[0..47]`'s raw spell ids for an aura of the arm's own type, then
+/// [`benilla_formats::grants_immunity`] on each match. A hit **lifts** the refusal; a rejection
+/// names the blocking mechanic and turns the arm's own reason into `0x8d`. Each arm scans for a
+/// different set of aura types — charm `{6, 177, 2}`, stun `{12}`, silence `{27, 12, 60}`, pacify
+/// `{25, 12, 60}`, fear `{7}`, confuse `{5}` — and those sets are the reference's, not a family
+/// resemblance.
+pub(crate) fn cast_cc_refusal(
+    unit_flags: u32,
+    health: Option<u32>,
+    charmed_by_other: bool,
+    spell: Option<&SpellDisplay>,
+    exempt: &mut impl FnMut(&[u32]) -> benilla_formats::CcExemption,
+) -> Option<(u8, Option<u32>)> {
+    use crate::player::UNIT_FLAG_STUNNED;
+    /// `UNIT_FIELD_FLAGS` bits 13/17/22/23 (vmangos `UnitDefines.h`).
+    const UNIT_FLAG_SILENCED: u32 = 0x0000_2000;
+    const UNIT_FLAG_PACIFIED: u32 = 0x0002_0000;
+    const UNIT_FLAG_CONFUSED: u32 = 0x0040_0000;
+    const UNIT_FLAG_FLEEING: u32 = 0x0080_0000;
+
+    // The dead caster's skip (`0x60980d`): a corpse is refused by an earlier rung, not this one.
+    if health == Some(0) {
+        return None;
+    }
+    let prevention = spell.map_or(0, |d| d.prevention_type);
+    // One arm: ask its exemption scan first, and let its answer pick between silence and one of
+    // two messages. `exempt` returning `exempt: true` means one of the caster's own auras grants
+    // immunity to whatever is blocking — the arm is SKIPPED and the cast proceeds. Otherwise the
+    // refusal is `0x8d` "Can't do that while %s" when the scan named a mechanic, and the arm's own
+    // reason when it did not (decision 1946).
+    let mut arm = |aura_types: &[u32], own_reason: u8| -> Option<(u8, Option<u32>)> {
+        let scan = exempt(aura_types);
+        if scan.exempt {
+            return None;
+        }
+        Some(if scan.mechanic != 0 {
+            // The mechanic rides along as the message's `%s` — the one client-LOCAL refusal that
+            // carries an argument word (decision 1948).
+            (REASON_PREVENTED_BY_MECHANIC, Some(scan.mechanic))
+        } else {
+            (own_reason, None)
+        })
+    };
+
+    if charmed_by_other {
+        if let Some(r) = arm(&[6, 177, 2], 0x14) {
+            return Some(r);
+        }
+    }
+    if unit_flags & UNIT_FLAG_STUNNED != 0 {
+        if let Some(r) = arm(&[12], 0x64) {
+            return Some(r);
+        }
+    }
+    if unit_flags & UNIT_FLAG_SILENCED != 0 && prevention == PREVENTION_SILENCE {
+        if let Some(r) = arm(&[27, 12, 60], 0x60) {
+            return Some(r);
+        }
+    }
+    if unit_flags & UNIT_FLAG_PACIFIED != 0 && prevention == PREVENTION_PACIFY {
+        if let Some(r) = arm(&[25, 12, 60], 0x5a) {
+            return Some(r);
+        }
+    }
+    if unit_flags & UNIT_FLAG_FLEEING != 0 {
+        if let Some(r) = arm(&[7], 0x1e) {
+            return Some(r);
+        }
+    }
+    if unit_flags & UNIT_FLAG_CONFUSED != 0 {
+        if let Some(r) = arm(&[5], 0x16) {
+            return Some(r);
+        }
+    }
+    None
+}
+
+/// `SPELL_FAILED_PREVENTED_BY_MECHANIC` — "Can't do that while %s", `%s` being the blocking aura's
+/// `SpellMechanic.dbc` name. Every crowd-control arm carries this **as well as** its own reason,
+/// and which one appears is decided by whether the exemption scan named a mechanic.
+const REASON_PREVENTED_BY_MECHANIC: u8 = 0x8d;
+
+/// The **pre-send** mounted refusal (decision 0481) — the requirement validator `0x6094f0`'s
+/// mounted block (`0x609c6c`): a live
+/// `UNIT_FIELD_MOUNTDISPLAYID` refuses the cast with reason `0x39` ("You are mounted") unless
+/// the spell carries Attributes bit 24 (`0x01000000`, castable-while-mounted — the exemption
+/// test at `0x609c6f`, the exact vmangos `SPELL_ATTR_ALLOW_WHILE_MOUNTED` mirror). A spell
+/// with no loaded record has no exemption to claim — the gate holds (the ref always has the
+/// record; refusing without data errs toward the ref's visible behavior). The sibling
+/// mount-REQUIRED gate (reason 0x53, `0x609c05`) is recorded but unbuilt — no 1.12 player spell
+/// exercises it. It is **two-armed** like the water pair below, not the single `+0x5c & 0x40`
+/// read this comment used to claim: arm A is `AuraInterruptFlags & 0x40` (the `cl` at
+/// `0x609c05` is the untouched low byte of `ecx = [esi+0x58]`, loaded 0x104 bytes earlier for
+/// the unsheathed leg), arm B is `ChannelInterruptFlags & 0x40` at `0x609c3a` — corrected
+/// in 1063. Note the plain mounted gate above is NOT in
+/// that family: it is single-armed on `Attributes`.
+pub(crate) fn cast_mounted_refusal(mounted: bool, spell: Option<&SpellDisplay>) -> bool {
+    mounted && spell.is_none_or(|d| d.attributes & 0x0100_0000 == 0)
+}
+
+/// The interrupt-flag water pair — the two bits that say *which side of the surface this aura
+/// can live on*: `0x80` cancels it on ENTERING water, `0x100` on LEAVING it (vmangos
+/// `AURA_INTERRUPT_UNDER_WATER_CANCELS` / `AURA_INTERRUPT_ABOVE_WATER_CANCELS`, bits 7/8). The
+/// requirement validator reads the same pair to refuse the *cast* whose aura could not survive
+/// the caster's current side.
+const INTERRUPT_UNDER_WATER: u32 = 0x80;
+const INTERRUPT_ABOVE_WATER: u32 = 0x100;
+
+/// `AttributesEx & (IS_CHANNELED 0x4 | IS_SELF_CHANNELED 0x40)` — the gate on **arm B** of every
+/// leg in this family (byte-verified `0x609d6a`/`0x609db1`). A channeled spell's requirement
+/// bits live in its CHANNEL column, so the validator reads that column too — but only for a
+/// spell that actually channels, which is what keeps Summon Baby Shark 25849 (`Channel 0x100`,
+/// `AttributesEx 0`) out of the gate.
+const ATTR_EX_CHANNELED: u32 = 0x44;
+
+/// `SPELL_FAILED_ONLY_ABOVEWATER` — "Cannot use while swimming".
+pub(super) const ERR_ONLY_ABOVEWATER: u8 = 0x50;
+/// `SPELL_FAILED_ONLY_UNDERWATER` — "Can only use while swimming".
+pub(super) const ERR_ONLY_UNDERWATER: u8 = 0x58;
+
+/// The **pre-send** water refusal (decisions 1056 + 1063) — the requirement validator
+/// `0x6094f0`'s environment block `0x609d33–0x609de2`. It sits after the mounted/posture/day/night
+/// legs and before the moving gate (`0x609de3`), which is where the ladder runs it — so a druid
+/// standing on land is refused **before** the form gate `0x612480` ever evaluates.
+///
+/// One gate, two faces, and each face has **two arms** reading the same bit in two columns:
+///
+/// | reason | bit | arm A — `AuraInterruptFlags` (+0x58) | arm B — `ChannelInterruptFlags` (+0x5c), if channeled |
+/// |---|---|---|---|
+/// | [`ERR_ONLY_UNDERWATER`] `0x58` | `0x100` | `0x609d36` / swim `0x609d46` | `0x609d6f` / swim `0x609d7b` |
+/// | [`ERR_ONLY_ABOVEWATER`] `0x50` | `0x80` | `0x609da4` / swim `0x609dac` | `0x609db5` / swim `0x609dc2` |
+///
+/// The swimming state is `[[caster+0x118]+0x40] & 0x200000` — the same wire-layout movement word
+/// the moving gate reads, four times over, twice in each face.
+///
+/// **Arm B is not dead code, and leaving it out is visibly wrong**: Fishing rank 1 (7620)
+/// carries `AuraInterruptFlags 0x80`, but ranks 2–4 (7731/7732/18248) carry **zero** and reach
+/// the gate only through their `ChannelInterruptFlags 0x3cac`. Arm A alone would refuse rank 1
+/// mid-swim and let its own upgrades through.
+///
+/// What the two bits actually select in the 5875 data: `0x80` is 245 rows — every mount, Travel
+/// Form, the campfires, all of Food/Drink (`0x40080`), Fishing — and `0x100` is exactly five:
+/// Aquatic Form 1066, the Lava/Slime swim auras 16455/16456, Master Angler 24346/24347.
+///
+/// **No exemption skips this block** (every jump into the run was enumerated) — unlike the
+/// mounted gate's `Attributes` bit 24. And the gate must be LOCAL: vmangos's `CheckCast` gates
+/// water only on `SPELL_AURA_MOUNTED` (`Spell.cpp:6379`), so it happily grants a druid aquatic
+/// form on dry cobblestone (ledger B176, with the screenshot to prove it). An uncataloged spell
+/// passes, like every other data-driven rung on this ladder.
+///
+/// The legs are evaluated `0x58` before `0x50`, the binary's own order; they are mutually
+/// exclusive on the swim bit, so the order is fidelity, not behaviour.
+pub(super) fn cast_water_refusal(move_flags_word: u32, spell: Option<&SpellDisplay>) -> Option<u8> {
+    let d = spell?;
+    let swimming = move_flags_word & crate::creature_anim::move_flags::SWIMMING != 0;
+    // Arm A always; arm B only for a spell that actually channels.
+    let requires = |bit: u32| {
+        d.aura_interrupt_flags & bit != 0
+            || (d.attributes_ex & ATTR_EX_CHANNELED != 0 && d.channel_interrupt_flags & bit != 0)
+    };
+    if !swimming && requires(INTERRUPT_ABOVE_WATER) {
+        return Some(ERR_ONLY_UNDERWATER);
+    }
+    if swimming && requires(INTERRUPT_UNDER_WATER) {
+        return Some(ERR_ONLY_ABOVEWATER);
+    }
+    None
+}
+
+/// The AuraInterruptFlags-space MOVING|TURNING pair (`0x18`) — the moving gate's
+/// "movement would matter anyway" arms test it on BOTH `AuraInterruptFlags` (+0x58) and
+/// `ChannelInterruptFlags` (+0x5c), byte-verified at `0x609e0e`/`0x609e1c`.
+const AURA_INTERRUPT_MOVING_TURNING: u32 = 0x18;
+
+/// The **pre-send** moving refusal (decision 0862) — the requirement validator `0x6094f0`'s
+/// moving block (`0x609de3–0x609e48`; the sole client-local emitter of reason `0x2e` "Can't do
+/// that while moving"): a press while the
+/// caster's live CMovement flags carry any of {forward, backward, strafe L/R, JUMPING} refuses
+/// locally — no packet, no cast bar, no GCD. Without it, vmangos *accepts* the cast (its
+/// CheckCast moving-reject covers only autorepeat/sit-still spells, `Spell.cpp:5432`) and then
+/// `Spell::update`'s 0.5-yd movement interrupt kills it — the start-then-cancel grief this gate
+/// exists to prevent. The full reject condition, gate for gate:
+///
+/// - **entry**: `InterruptFlags & 0x1` (movement-interruptible — instants without it pass);
+/// - **the movement word**: the WIRE `MovementFlags` layout (`[unit+0x9a8]+0x40`), mask
+///   `0x200f` = forward|backward|strafe + JUMPING — turning and pitch are outside it, and so is
+///   FALLINGFAR (`0x4000`; the client has NO falling/Stuck exemption — that's vmangos-only);
+/// - **exemption**: an auto-repeat spell (`AttributesEx2 & 0x20` — Auto Shot, Shoot) never
+///   refuses, whatever else it carries;
+/// - **would movement matter**: a nonzero resolved cast time ([`super::Spells::cast_time_ms`]),
+///   OR the [`AURA_INTERRUPT_MOVING_TURNING`] bits on the aura/channel interrupt columns — the
+///   OR-arms are how a zero-cast-time *channel* is still refused at initiation.
+///
+/// An uncataloged spell passes (every record-read above needs the row; the ladder's other
+/// data-driven legs — cooldown, GCD, range — share the disposition, and the server's own
+/// interrupt stays the safety net). In the validator's order this sits after the mounted block
+/// and before the shapeshift-form leg (`0x609e50`), which is where [`super::cast_send`]'s ladder
+/// runs it.
+pub(super) fn cast_moving_refusal(
+    move_flags_word: u32,
+    cast_time_ms: u32,
+    spell: Option<&SpellDisplay>,
+) -> bool {
+    use crate::creature_anim::move_flags;
+    // The verified 0x200f: ANY_MOVE (0xf) | FALLING (0x2000), in our identical wire layout.
+    const MOVING_MASK: u32 = move_flags::ANY_MOVE | move_flags::FALLING;
+    let Some(d) = spell else { return false };
+    d.interrupt_flags & crate::spell::SPELL_INTERRUPT_MOVEMENT != 0
+        && move_flags_word & MOVING_MASK != 0
+        && !d.auto_repeat()
+        && (cast_time_ms != 0
+            || d.aura_interrupt_flags & AURA_INTERRUPT_MOVING_TURNING != 0
+            || d.channel_interrupt_flags & AURA_INTERRUPT_MOVING_TURNING != 0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn spell_with_range(range_index: u32, attributes: u32) -> SpellDisplay {
+        SpellDisplay {
+            range_index,
+            attributes,
+            ..Default::default()
+        }
+    }
+
+    /// The pre-send refusal (`IsTargetInRange 0x6e47b0`'s two compares over the resolved
+    /// bounds): Auto Shot's {8, 35} row + the unit reach pad — a point-blank target refuses
+    /// TOO_CLOSE, a distant one OUT_OF_RANGE, the sweet spot passes; untestable inputs pass.
+    #[test]
+    fn cast_range_refusal_follows_the_two_compares() {
+        let d = spell_with_range(114, 0);
+        let auto_shot = SpellRange {
+            min: 8.0,
+            max: 35.0,
+            flags: 0,
+        };
+        let reach = Some(1.5);
+        // Both bounds carry the bare reach pad (self 1.5 + target 1.5): min = 11, max = 38.
+        let refuse = |d2: f32| cast_range_refusal(&d, Some(&auto_shot), 1.5, reach, Some(d2));
+        assert_eq!(refuse(3.0 * 3.0), Some(ERR_TOO_CLOSE));
+        assert_eq!(refuse(20.0 * 20.0), None);
+        assert_eq!(refuse(60.0 * 60.0), Some(ERR_OUT_OF_RANGE));
+
+        // The regression: a min-0 ranged row (Fireball/Shadow Bolt) must pass point-blank —
+        // its min never grows a reach pad — while the max compare still holds.
+        let fireball = SpellRange {
+            min: 0.0,
+            max: 35.0,
+            flags: 0,
+        };
+        let refuse = |d2: f32| cast_range_refusal(&d, Some(&fireball), 1.5, reach, Some(d2));
+        assert_eq!(refuse(0.1), None);
+        assert_eq!(refuse(60.0 * 60.0), Some(ERR_OUT_OF_RANGE));
+
+        // A melee-family row has min 0 — never TOO_CLOSE, still OUT_OF_RANGE beyond reach.
+        let melee = SpellRange {
+            min: 0.0,
+            max: 5.0,
+            flags: 1,
+        };
+        let melee_spell = spell_with_range(2, 0);
+        assert_eq!(
+            cast_range_refusal(&melee_spell, Some(&melee), 1.5, reach, Some(0.1)),
+            None
+        );
+        assert_eq!(
+            cast_range_refusal(&melee_spell, Some(&melee), 1.5, reach, Some(15.0 * 15.0)),
+            Some(ERR_OUT_OF_RANGE)
+        );
+
+        // No row / no distance: nothing to test locally — pass (the server judges).
+        assert_eq!(cast_range_refusal(&d, None, 1.5, reach, Some(1.0)), None);
+        assert_eq!(
+            cast_range_refusal(&d, Some(&auto_shot), 1.5, reach, None),
+            None
+        );
+    }
+
+    /// The mounted refusal (`0x609c6c`): a live mount blocks unless Attributes carries the
+    /// bit-24 exemption (`0x609c6f`); unmounted always passes; a missing record can claim no
+    /// exemption, so the gate holds.
+    #[test]
+    fn cast_mounted_refusal_honors_the_bit24_exemption() {
+        let plain = SpellDisplay::default();
+        let exempt = SpellDisplay {
+            attributes: 0x0100_0000,
+            ..Default::default()
+        };
+        assert!(cast_mounted_refusal(true, Some(&plain)));
+        assert!(!cast_mounted_refusal(true, Some(&exempt)));
+        assert!(!cast_mounted_refusal(false, Some(&plain)));
+        assert!(!cast_mounted_refusal(false, None));
+        assert!(cast_mounted_refusal(true, None), "no record, no exemption");
+    }
+
+    /// The water refusal (`0x609d33–0x609de2`) — both faces of the environment gate and both
+    /// arms of each face, on the real 5875 columns: Aquatic Form's `0x100` needs the SWIMMING
+    /// bit set, the mount/Travel-Form/food `0x80` needs it clear, Fishing's ranks reach it
+    /// through the CHANNEL column, and a spell carrying neither bit passes on both sides.
+    #[test]
+    fn cast_water_refusal_reads_both_sides_of_the_surface() {
+        use crate::creature_anim::move_flags as mf;
+        // Aquatic Form 1066: AuraInterruptFlags 0x100 — above-water cancels it, so the cast
+        // needs water. This is ledger B176: on land it must refuse, and it must not send.
+        let aquatic = SpellDisplay {
+            aura_interrupt_flags: 0x100,
+            ..Default::default()
+        };
+        assert_eq!(
+            cast_water_refusal(0, Some(&aquatic)),
+            Some(ERR_ONLY_UNDERWATER)
+        );
+        assert_eq!(cast_water_refusal(mf::SWIMMING, Some(&aquatic)), None);
+        // Travel Form 783 / every mount: 0x80 — entering water cancels it, so it refuses the
+        // other way round.
+        let travel = SpellDisplay {
+            aura_interrupt_flags: 0x80,
+            ..Default::default()
+        };
+        assert_eq!(
+            cast_water_refusal(mf::SWIMMING, Some(&travel)),
+            Some(ERR_ONLY_ABOVEWATER)
+        );
+        assert_eq!(cast_water_refusal(0, Some(&travel)), None);
+        // Food 433's shape (0x40080 = STANDING_CANCELS | UNDER_WATER_CANCELS) — the eating half
+        // of ledger B155 rides the same 0x80 arm.
+        let food = SpellDisplay {
+            aura_interrupt_flags: 0x4_0080,
+            ..Default::default()
+        };
+        assert_eq!(
+            cast_water_refusal(mf::SWIMMING, Some(&food)),
+            Some(ERR_ONLY_ABOVEWATER)
+        );
+        assert_eq!(cast_water_refusal(0, Some(&food)), None);
+        // ARM B (decision 1063): a CHANNELED spell's requirement bits live in its channel
+        // column. Fishing ranks 2–4's shape — AuraInterruptFlags zero, ChannelInterruptFlags
+        // 0x3cac (which carries 0x80), AttributesEx 0x21004004 (IS_CHANNELED).
+        let fishing_r2 = SpellDisplay {
+            aura_interrupt_flags: 0,
+            channel_interrupt_flags: 0x3cac,
+            attributes_ex: 0x2100_4004,
+            ..Default::default()
+        };
+        assert_eq!(
+            cast_water_refusal(mf::SWIMMING, Some(&fishing_r2)),
+            Some(ERR_ONLY_ABOVEWATER),
+            "arm A is empty here — only the channel column refuses it"
+        );
+        assert_eq!(cast_water_refusal(0, Some(&fishing_r2)), None);
+        // …and the `AttributesEx & 0x44` gate on arm B is load-bearing: Summon Baby Shark
+        // 25849's shape carries the channel bit but does not channel, so it is NOT gated.
+        let not_channeled = SpellDisplay {
+            channel_interrupt_flags: 0x100,
+            attributes_ex: 0,
+            ..Default::default()
+        };
+        assert_eq!(cast_water_refusal(0, Some(&not_channeled)), None);
+        assert_eq!(cast_water_refusal(mf::SWIMMING, Some(&not_channeled)), None);
+        // Cat Form 768 / Bear Form 5487 carry neither bit: usable on both sides, always.
+        let cat = SpellDisplay::default();
+        assert_eq!(cast_water_refusal(0, Some(&cat)), None);
+        assert_eq!(cast_water_refusal(mf::SWIMMING, Some(&cat)), None);
+        // No record, nothing to read — the press passes, like every other data-driven rung.
+        assert_eq!(cast_water_refusal(0, None), None);
+        assert_eq!(cast_water_refusal(mf::SWIMMING, None), None);
+    }
+
+    /// The water gate against the **real 5875 Spell.dbc** — the census the whole gate rests on.
+    /// The leg↔bit assignment is not a naming choice we could get backwards: exactly five rows
+    /// in the shipped data carry the water-REQUIRED bit, and Aquatic Form is one of them, while
+    /// the water-FORBIDDEN bit is a broad set led by the mounts, Travel Form and food/drink.
+    /// Skips without client data.
+    #[test]
+    fn the_water_bits_split_the_5875_data_the_way_the_gate_assumes() {
+        let data = benilla_formats::wow_data_or_skip!();
+        let mut chain = benilla_formats::open_chain(&data).expect("open chain");
+        let catalog = benilla_formats::load_spell_catalog(&mut chain).expect("Spell.dbc");
+
+        // Every spell the client would refuse OUT of water, by id.
+        let mut needs_water: Vec<u32> = catalog
+            .iter()
+            .filter(|(_, d)| d.aura_interrupt_flags & INTERRUPT_ABOVE_WATER != 0)
+            .map(|(id, _)| id)
+            .collect();
+        needs_water.sort_unstable();
+        assert_eq!(
+            needs_water,
+            vec![1066, 16455, 16456, 24346, 24347],
+            "the water-required set: Aquatic Form, the Lava/Slime swim auras, Master Angler"
+        );
+
+        // The other face: broad, and led by exactly the things you cannot do mid-swim.
+        let forbids_water = |id: u32| {
+            catalog
+                .get(id)
+                .is_some_and(|d| d.aura_interrupt_flags & INTERRUPT_UNDER_WATER != 0)
+        };
+        assert!(forbids_water(783), "Travel Form");
+        assert!(forbids_water(458), "Brown Horse");
+        assert!(forbids_water(433), "Food");
+        assert!(forbids_water(430), "Drink");
+        assert!(forbids_water(818), "Basic Campfire");
+
+        // ARM B's reason to exist, on the real rows (decision 1063). Fishing rank 1 carries the
+        // bit in the AURA column; its own upgrades carry NOTHING there and reach the gate only
+        // through the CHANNEL column. Arm A alone would refuse rank 1 mid-swim and let 2–4 fish.
+        let swim = crate::creature_anim::move_flags::SWIMMING;
+        assert!(forbids_water(7620), "Fishing rank 1 — arm A");
+        for rank in [7731, 7732, 18248] {
+            let d = catalog
+                .get(rank)
+                .unwrap_or_else(|| panic!("Fishing {rank} missing"));
+            assert_eq!(d.aura_interrupt_flags, 0, "Fishing {rank}: arm A is empty");
+            assert!(d.attributes_ex & ATTR_EX_CHANNELED != 0, "and it channels");
+            assert_eq!(
+                cast_water_refusal(swim, Some(d)),
+                Some(ERR_ONLY_ABOVEWATER),
+                "Fishing {rank} still refuses mid-swim, through the channel column"
+            );
+            assert_eq!(cast_water_refusal(0, Some(d)), None, "and fishes on shore");
+        }
+
+        // The forms that carry neither bit — usable on both sides, and the control that says the
+        // gate is reading a real per-spell column and not a class-wide accident.
+        for (id, name) in [(768, "Cat Form"), (5487, "Bear Form"), (2645, "Ghost Wolf")] {
+            let d = catalog.get(id).unwrap_or_else(|| panic!("{name} missing"));
+            assert_eq!(d.aura_interrupt_flags & 0x180, 0, "{name} is side-agnostic");
+            assert_eq!(cast_water_refusal(0, Some(d)), None, "{name} on land");
+            assert_eq!(cast_water_refusal(swim, Some(d)), None, "{name} swimming");
+        }
+
+        // And end to end, on the real rows: B176's exact press.
+        let aquatic = catalog.get(1066).expect("Aquatic Form");
+        assert_eq!(
+            cast_water_refusal(0, Some(aquatic)),
+            Some(ERR_ONLY_UNDERWATER),
+            "on land, Aquatic Form refuses — the B176 report"
+        );
+        assert_eq!(
+            cast_water_refusal(crate::creature_anim::move_flags::SWIMMING, Some(aquatic)),
+            None,
+            "swimming, it goes through"
+        );
+    }
+
+    /// The moving refusal (`0x609de3`) — every leg of the byte-verified condition: the
+    /// `InterruptFlags & 0x1` entry, the `0x200f` wire mask (turn/FALLINGFAR outside it,
+    /// JUMPING inside), the auto-repeat exemption, and the "would movement matter" arms (cast
+    /// time / aura / channel `0x18` bits).
+    #[test]
+    fn cast_moving_refusal_follows_the_validator_condition() {
+        use crate::creature_anim::move_flags as mf;
+        // Fireball's shape: ordinary timed cast (interrupt 0xf, nonzero cast time).
+        let timed = SpellDisplay {
+            interrupt_flags: 0xf,
+            ..Default::default()
+        };
+        // Moving forward refuses; standing still doesn't.
+        assert!(cast_moving_refusal(mf::FORWARD, 1500, Some(&timed)));
+        assert!(!cast_moving_refusal(0, 1500, Some(&timed)));
+        // Strafe and JUMPING are in the mask; turn and FALLING_FAR are not (`0x200f`).
+        assert!(cast_moving_refusal(mf::STRAFE_LEFT, 1500, Some(&timed)));
+        assert!(cast_moving_refusal(mf::FALLING, 1500, Some(&timed)));
+        assert!(!cast_moving_refusal(mf::TURN_LEFT, 1500, Some(&timed)));
+        assert!(!cast_moving_refusal(mf::FALLING_FAR, 1500, Some(&timed)));
+        // An instant WITHOUT the movement interrupt bit passes (Fire Blast's shape)…
+        let instant = SpellDisplay {
+            interrupt_flags: 0xe,
+            ..Default::default()
+        };
+        assert!(!cast_moving_refusal(mf::FORWARD, 0, Some(&instant)));
+        // …and even WITH it, a zero cast time passes unless an 0x18 arm bites.
+        assert!(!cast_moving_refusal(mf::FORWARD, 0, Some(&timed)));
+        // Arcane Missiles' shape: zero cast time, but the channel column's moving bits refuse
+        // at initiation (the OR-arm; 0x7c0c & 0x18 != 0).
+        let channel = SpellDisplay {
+            interrupt_flags: 0xf,
+            channel_interrupt_flags: 0x7c0c,
+            ..Default::default()
+        };
+        assert!(cast_moving_refusal(mf::FORWARD, 0, Some(&channel)));
+        // The aura-column arm (food/drink sit-still bits).
+        let sit_still = SpellDisplay {
+            interrupt_flags: 0x1,
+            aura_interrupt_flags: 0x18,
+            ..Default::default()
+        };
+        assert!(cast_moving_refusal(mf::FORWARD, 0, Some(&sit_still)));
+        // Auto-repeat (AttributesEx2 & 0x20) is unconditionally exempt — Auto Shot fires on
+        // the run whatever its columns say.
+        let auto_shot = SpellDisplay {
+            interrupt_flags: 0x1,
+            attributes_ex2: 0x20,
+            aura_interrupt_flags: 0x18,
+            ..Default::default()
+        };
+        assert!(!cast_moving_refusal(mf::FORWARD, 0, Some(&auto_shot)));
+        // No record: nothing to read, the press passes (the server stays the net).
+        assert!(!cast_moving_refusal(mf::FORWARD, 1500, None));
+    }
+}
+
+#[cfg(test)]
+mod cc_refusal_tests {
+    use super::*;
+
+    const STUNNED: u32 = 0x0004_0000;
+    const SILENCED: u32 = 0x0000_2000;
+    const PACIFIED: u32 = 0x0002_0000;
+    const CONFUSED: u32 = 0x0040_0000;
+    const FLEEING: u32 = 0x0080_0000;
+
+    fn spell(prevention_type: u32) -> SpellDisplay {
+        SpellDisplay {
+            prevention_type,
+            ..Default::default()
+        }
+    }
+
+    /// A scan that finds no aura at all — `exempt: false, mechanic: 0`, so every arm falls to its
+    /// OWN reason. This is the ordinary case: the exemption only ever fires for a caster wearing
+    /// an immunity.
+    fn no_auras() -> impl FnMut(&[u32]) -> benilla_formats::CcExemption {
+        |_: &[u32]| benilla_formats::CcExemption::default()
+    }
+
+    /// The reason alone, dropping the mechanic — most of these tests are about which arm fires.
+    fn reason_of(v: Option<(u8, Option<u32>)>) -> Option<u8> {
+        v.map(|(r, _)| r)
+    }
+
+    /// A live caster, nobody else at the reins, no auras.
+    fn cc(flags: u32, d: &SpellDisplay) -> Option<u8> {
+        cast_cc_refusal(flags, Some(100), false, Some(d), &mut no_auras()).map(|(r, _)| r)
+    }
+
+    /// **The arms are not symmetric** (decision 1904, widened by 1925): stun, fear, charm and
+    /// confuse refuse EVERY spell; silence and pacify only the rows whose `PreventionType` names
+    /// them. Reading `UNIT_FLAG_SILENCED` as "no casting at all" — which our own preflight banner
+    /// used to say — is the mistake this pins.
+    #[test]
+    fn crowd_control_refuses_by_prevention_type_except_the_unconditional_arms() {
+        // Fireball-shaped (silence-preventable), Heroic-Strike-shaped (pacify-preventable), and
+        // the auto-attack's neither — the three real values, pinned in `spell_catalog`.
+        let cast = spell(1);
+        let melee = spell(2);
+        let neither = spell(0);
+
+        // The four arms with NO per-spell gate: every row refuses.
+        for (flags, reason) in [(STUNNED, 0x64), (FLEEING, 0x1e), (CONFUSED, 0x16)] {
+            for d in [&cast, &melee, &neither] {
+                assert_eq!(cc(flags, d), Some(reason), "flags {flags:#x}");
+            }
+        }
+        // …and charm, which is not a flag at all but "somebody else holds the reins".
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                0,
+                Some(100),
+                true,
+                Some(&neither),
+                &mut no_auras()
+            )),
+            Some(0x14)
+        );
+
+        // SILENCED takes the casts and leaves the rest alone.
+        assert_eq!(cc(SILENCED, &cast), Some(0x60));
+        assert_eq!(cc(SILENCED, &melee), None);
+        assert_eq!(cc(SILENCED, &neither), None);
+
+        // PACIFIED is the mirror.
+        assert_eq!(cc(PACIFIED, &melee), Some(0x5a));
+        assert_eq!(cc(PACIFIED, &cast), None);
+
+        // Nothing up, nothing refused; and no record claims no prevention.
+        assert_eq!(cc(0, &cast), None);
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                SILENCED,
+                Some(100),
+                false,
+                None,
+                &mut no_auras()
+            )),
+            None
+        );
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED,
+                Some(100),
+                false,
+                None,
+                &mut no_auras()
+            )),
+            Some(0x64),
+            "the stun needs no record"
+        );
+    }
+
+    /// **The order is the reference's, first match wins** — charm outranks the stun, the stun
+    /// outranks everything below it. When several hold at once the player sees exactly one line,
+    /// and which one is not arbitrary.
+    #[test]
+    fn the_arms_are_tried_in_the_references_order() {
+        let cast = spell(1);
+        // Charm is arm 1: it beats a simultaneous stun.
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED | SILENCED,
+                Some(100),
+                true,
+                Some(&cast),
+                &mut no_auras()
+            )),
+            Some(0x14)
+        );
+        // Stun is arm 2: it beats silence, pacify, fear and confuse.
+        assert_eq!(
+            cc(STUNNED | SILENCED | PACIFIED | FLEEING | CONFUSED, &cast),
+            Some(0x64)
+        );
+        // Silence (3) beats fear (5) and confuse (6).
+        assert_eq!(cc(SILENCED | FLEEING | CONFUSED, &cast), Some(0x60));
+        // With the spell out of silence's reach, fear takes it before confuse.
+        assert_eq!(cc(SILENCED | FLEEING | CONFUSED, &spell(0)), Some(0x1e));
+    }
+
+    /// **What the exemption does to an arm** (decision 1946) — the three outcomes, at the arm.
+    #[test]
+    fn the_exemption_skips_an_arm_or_renames_its_refusal() {
+        let cast = spell(1);
+        let scan = |exempt: bool, mechanic: u32| {
+            move |_: &[u32]| benilla_formats::CcExemption { exempt, mechanic }
+        };
+
+        // No aura of the arm's type: the arm's OWN reason, as everywhere else.
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED,
+                Some(100),
+                false,
+                Some(&cast),
+                &mut scan(false, 0)
+            )),
+            Some(0x64)
+        );
+        // A blocking aura the cast does NOT counter: the refusal survives but is renamed to
+        // `0x8d` "Can't do that while %s", the mechanic naming the aura.
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED,
+                Some(100),
+                false,
+                Some(&cast),
+                &mut scan(false, 12)
+            )),
+            Some(0x8d)
+        );
+        // The cast grants immunity: the arm is SKIPPED and the cast goes out. This is the whole
+        // point — Ice Block cast while stunned.
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED,
+                Some(100),
+                false,
+                Some(&cast),
+                &mut scan(true, 0)
+            )),
+            None
+        );
+        // …and skipping one arm does not skip the ladder: a silenced-and-stunned caster whose
+        // spell counters only the stun still refuses on silence below it.
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED | SILENCED,
+                Some(100),
+                false,
+                Some(&cast),
+                &mut |types: &[u32]| {
+                    // Exempt from the stun arm `{12}` only; the silence arm `{27, 12, 60}` is not.
+                    benilla_formats::CcExemption {
+                        exempt: types == [12],
+                        mechanic: 0,
+                    }
+                }
+            )),
+            Some(0x60)
+        );
+    }
+
+    /// **The mechanic rides out with the refusal** (decision 1948) — the half that turns
+    /// "Can't do that while %s" into a sentence. It is the ONE client-local refusal that carries
+    /// an argument word, and it is `None` for every arm that fell to its own reason.
+    #[test]
+    fn the_renamed_refusal_carries_the_mechanic_and_the_others_carry_nothing() {
+        let cast = spell(1);
+        let scan = |exempt: bool, mechanic: u32| {
+            move |_: &[u32]| benilla_formats::CcExemption { exempt, mechanic }
+        };
+
+        // Rejected by a blocking aura: reason `0x8d` AND the mechanic that names it.
+        assert_eq!(
+            cast_cc_refusal(STUNNED, Some(100), false, Some(&cast), &mut scan(false, 12)),
+            Some((0x8d, Some(12)))
+        );
+        // No aura: the arm's own reason, and NO argument — the message has no `%s` to fill.
+        assert_eq!(
+            cast_cc_refusal(STUNNED, Some(100), false, Some(&cast), &mut scan(false, 0)),
+            Some((0x64, None))
+        );
+        // Exempt: nothing at all.
+        assert_eq!(
+            cast_cc_refusal(STUNNED, Some(100), false, Some(&cast), &mut scan(true, 0)),
+            None
+        );
+    }
+
+    /// **A dead caster skips all six** (`0x60980d`'s `jle` on `UNIT_FIELD_HEALTH`) — a corpse is
+    /// refused by an earlier rung, and reporting a stun over it would be the wrong line.
+    #[test]
+    fn a_dead_caster_takes_no_crowd_control_refusal() {
+        let cast = spell(1);
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED,
+                Some(0),
+                false,
+                Some(&cast),
+                &mut no_auras()
+            )),
+            None
+        );
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                0,
+                Some(0),
+                true,
+                Some(&cast),
+                &mut no_auras()
+            )),
+            None
+        );
+        // Alive again, and the arm is back.
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED,
+                Some(1),
+                false,
+                Some(&cast),
+                &mut no_auras()
+            )),
+            Some(0x64)
+        );
+        // No health field at all is not death — the descriptor simply has not landed.
+        assert_eq!(
+            reason_of(cast_cc_refusal(
+                STUNNED,
+                None,
+                false,
+                Some(&cast),
+                &mut no_auras()
+            )),
+            Some(0x64)
+        );
+    }
+}
diff --git a/crates/benilla-app/src/swing_refusal.rs b/crates/benilla-app/src/swing_refusal.rs
index 4aa0c861..3681eb47 100644
--- a/crates/benilla-app/src/swing_refusal.rs
+++ b/crates/benilla-app/src/swing_refusal.rs
@@ -64,8 +64,7 @@
 //! [`benilla_protocol::messages::opcode`]: the reference never registers it, and vmangos never
 //! sends it (`Player::SendAttackSwingNotStanding` has zero callers).
 //!
-//! Whole seam §5-verified in wow-re `object-layer/scratch/attackswing-refusal-law.md` (decision
-//! 2037), which corrected three prior glosses of these same addresses.
+//! Decision 2037.
 
 use std::time::Duration;
 
@@ -95,11 +94,8 @@ pub(crate) enum SwingRefusalEdge {
     /// 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 §5's first pass glossed B away ("any
-    /// ATTACKERSTATEUPDATE with the local player as attacker"); the disassembly it quoted did not,
-    /// and a re-derivation confirmed the reading and corrected the note (wow-re `fc385895`, which
-    /// also proved the leg is entered by fall-through alone — 0 branches into `[0x6259ac,
-    /// 0x6259b7]`, 1 rel32 caller of `0x5ea800`, 0 address-takes).
+    /// (`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
@@ -120,7 +116,7 @@ pub(crate) enum SwingRefusalEdge {
 /// 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.
 ///
-/// The §5 warns a re-implementation modelling this as `(Option<Code>, Instant)` not to assume the
+/// 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
@@ -233,7 +229,7 @@ fn show_swing_refusal(
 }
 
 /// **Entering** the world drops the latch — the reference's `0x5e2510`, reached from
-/// `ClientInitializeGame 0x401570` (`0x401648` → `0x5e253a`), which the §5 pinned to **once per
+/// `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
diff --git a/crates/benilla-app/src/target/by_name.rs b/crates/benilla-app/src/target/by_name.rs
index d0d18a2c..c5e7da08 100644
--- a/crates/benilla-app/src/target/by_name.rs
+++ b/crates/benilla-app/src/target/by_name.rs
@@ -1,8 +1,7 @@
 //! Selection **by name** — the shared resolver behind `/target` and `/assist` (decision 0886).
 //!
 //! The reference has ONE resolver, `0x493aa0`, parameterised per caller; `/target`, `/assist` and
-//! `/follow` are the same search with different arguments (wow-re
-//! `object-layer/scratch/targeting-by-name.md`, §5-cross-checked):
+//! `/follow` are the same search with different arguments:
 //!
 //! | binding | typemask | filter mode | exact-only |
 //! |---|---|---|---|
@@ -48,8 +47,8 @@
 //!
 //! [`Rank::beats`] is instead a **total order** — exact beats any prefix, then longer prefix, then
 //! strictly nearest — which is deterministic and picks the nearest of several same-named kobolds.
-//! wow-re's note calls the reference behaviour here "the single behaviour most likely to look like a
-//! bug in a reimplementation". Reproducing it is now *possible* (stamp each net entity with a
+//! The reference behaviour here is the single behaviour most likely to look like a bug in a
+//! reimplementation. Reproducing it is now *possible* (stamp each net entity with a
 //! monotonic link sequence, re-stamped on stream-in, and order the walk by it); it is not done
 //! because nearest is the better answer, not because the order is unknown. This is the one place to
 //! change if that judgement is ever reversed.
@@ -283,7 +282,7 @@ impl ByNameScan<'_, '_> {
     }
 
     /// The reference's mode-2 arm (`0x493eca`): `CanAssist` — the reaction ladder at **≥ 4**
-    /// (friendly; wow-re `w2d1` `CanAssist_Unit 0x6066f0`), the mirror of [`scan::can_attack`]'s
+    /// (friendly; `CanAssist_Unit 0x6066f0`), the mirror of [`scan::can_attack`]'s
     /// `≤ 3` — **and** alive.
     fn assistable_alive(&self, store: Option<&ObjectStore>) -> bool {
         if store.is_some_and(|s| s.0.unit_is_dead()) {
@@ -400,7 +399,7 @@ impl ByNameScan<'_, '_> {
 /// A miss leaves the current target **untouched** — verified: neither failure edge in `0x489db4`
 /// calls `SetSelection`, so `/target nosuchname` never clears what you had. The reference does emit
 /// a game message there (ids `0x127` name-not-found / `0xb8` empty name), but the id→string table is
-/// runtime-populated BSS and wow-re could not statically recover the text, so we say nothing rather
+/// runtime-populated BSS and its text is not statically recoverable, so we say nothing rather
 /// than invent a line. That silence is the known deviation on this path.
 pub(super) fn target_by_name_requests(
     mut requests: MessageReader<TargetByNameRequest>,
@@ -463,8 +462,8 @@ pub(super) fn script_target_by_name_requests(
 }
 
 /// Drain `/assist [name]`: find the **basis** unit, read its `UNIT_FIELD_TARGET` (+0x28 off the unit
-/// block — wow-re proved the offset arithmetic against HEALTH and DYNAMIC_FLAGS on the same line),
-/// and select whatever it is pointing at.
+/// block, read by the shared tail `0x489bb2`; the offset arithmetic holds against HEALTH and
+/// DYNAMIC_FLAGS on the same line), and select whatever it is pointing at.
 ///
 /// The bare form is `AssistUnit("target")` in the reference — assist whoever you have selected,
 /// creature or player. The named form resolves **players only**. A basis with no target is a
@@ -521,7 +520,7 @@ pub(super) fn follow_requests(
     group: Res<crate::ui_party::GroupState>,
     index: Res<GuidIndex>,
     stores: Query<&ObjectStore>,
-    cast: Res<crate::ui_cast::PendingCast>,
+    cast: Res<crate::spell::PendingCast>,
     mut errors: ResMut<crate::ui_action::UiErrorKeys>,
     mut follow: ResMut<crate::player::FollowState>,
 ) {
diff --git a/crates/benilla-app/src/target/click.rs b/crates/benilla-app/src/target/click.rs
index 89fce85e..8c784f85 100644
--- a/crates/benilla-app/src/target/click.rs
+++ b/crates/benilla-app/src/target/click.rs
@@ -12,10 +12,9 @@ use super::lock::GoLockInputs;
 use super::*;
 
 /// The **right-click cursor-payload leg** — the reference's WorldFrame click router (`0x481f60`
-/// → object leg `0x492ce0` / terrain leg `0x492c90` / nothing leg `0x492d30`; decision 0571,
-/// §5-cross-checked as wow-re cursor-dragdrop-payload.md §11 / decision 0574), transcribed onto
-/// the camera arbiter's clean-click message (a drag/turn never routes here, exactly the ref's
-/// click-not-drag gate `0x514ae0`):
+/// → object leg `0x492ce0` / terrain leg `0x492c90` / nothing leg `0x492d30`; decision 0571 /
+/// decision 0574), transcribed onto the camera arbiter's clean-click message (a drag/turn never
+/// routes here, exactly the ref's click-not-drag gate `0x514ae0`):
 ///
 /// - a **right-click over empty world** (terrain OR nothing): ANY payload clears silently — no
 ///   popup, no packet (both legs' action-4 arm: `ClearCursor(1,1)` unconditionally). This is
@@ -73,7 +72,7 @@ pub(super) fn world_right_click_payload(
 pub(super) fn select_on_plate_click(
     mut plate: ResMut<crate::vplates::PlateClicks>,
     press: Res<PressPick>,
-    ground: Res<crate::ui_action::SpellTargeting>,
+    ground: Res<crate::spell::SpellTargeting>,
     mut selection: ResMut<Selection>,
     mut seam: crate::creature_anim::AttackSeam,
     self_q: Query<(&Guid, Has<Engaged>), With<SelfPlayer>>,
@@ -140,7 +139,7 @@ pub(super) fn select_on_click(
     self_q: Query<(&Guid, Has<Engaged>), With<SelfPlayer>>,
     payload_held: Res<crate::ui_script::CursorPayloadHeld>,
     mut greeting: MessageWriter<crate::sound::NpcGreetingRequest>,
-    ground: Res<crate::ui_action::SpellTargeting>,
+    ground: Res<crate::spell::SpellTargeting>,
     click_cfg: Res<ClickConfig>,
     // The clicked unit's descriptor — `0x493540`'s `IsSelectable` gate reads it inside
     // [`scan::commit`]. Read live rather than latched with the press pick: the reference resolves
@@ -166,8 +165,8 @@ pub(super) fn select_on_click(
         .unwrap_or((None, false));
     match (hovered.target, hovered.guid) {
         (Some(entity), Some(guid)) => {
-            // The NPC greets us on the SELECT gesture — the byte-verified trigger (wow-re
-            // `npc-greeting.md`: the variation-cycling greeter `0x60c270` fires "before SetTarget",
+            // The NPC greets us on the SELECT gesture — the reference's trigger (the
+            // variation-cycling greeter `0x60c270` fires before SetTarget,
             // i.e. on the left-click select, NOT the right-click interact — director-confirmed:
             // left-click greets and repeat left-clicks cycle, right-click does nothing). Fired on
             // EVERY select click on a unit (not gated on a selection change) so re-clicking the
@@ -223,8 +222,7 @@ pub(super) fn select_on_click(
 ///
 /// Three of the reference's fourteen arms need something other than "send this opcode": bit 1
 /// reads the target's cached questgiver status as its second conjunct, and bits 5 and 7 raise a
-/// client-side CONFIRM dialog and send nothing at all (wow-re
-/// `object-layer/scratch/interact-dead-fork-and-npc-service-ladder.md` §C).
+/// client-side CONFIRM dialog and send nothing at all (`0x5f0130`'s ladder).
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct ServiceArms<'w> {
     /// `[unit+0xcb8]`'s mirror — the last `SMSG_QUESTGIVER_STATUS` per guid, which the bit-1 arm's
@@ -264,10 +262,10 @@ pub(crate) struct ServiceArms<'w> {
 /// So **right-clicking the NPC whose window is already open does nothing at all**: no packet, no
 /// error, and no talk gesture — the gesture lives at the tail of each arm, and no arm runs.
 ///
-/// `[0xb4e2d0]` is the `"npc"` UnitID token (wow-re `ui/scratch/unit-token-grammar.md` §4.1 row 9),
-/// and the timing is what makes this safe to transcribe: an image-wide census of the two write
-/// sites — the arm at `0x493114` inside `SetInteractionNPC 0x4930d0`, and `0x49334b`'s clear inside
-/// `0x493310` — finds **fourteen callers of the setter, none of them on the click path**. Every one
+/// `[0xb4e2d0]` is the `"npc"` UnitID token, and the timing is what makes this safe to transcribe:
+/// an image-wide census of the two write sites — the arm at `0x493114` inside
+/// `SetInteractionNPC 0x4930d0`, and `0x49334b`'s clear inside `0x493310` — finds
+/// **fourteen callers of the setter, none of them on the click path**. Every one
 /// is a window *opener*, armed when the server's reply lands. The first click therefore always gets
 /// through (nothing is open yet); only a re-click while the window stands is eaten. That is exactly
 /// the set [`crate::ui_session::feed_interact_npc`] collapses, which is why this reads that
@@ -278,8 +276,8 @@ fn interaction_already_open_on(target: u64, interact: &crate::ui_session::Intera
 }
 
 /// On a clean right-*click* (vanilla's context action — [`WorldRightClick`], never a turn-drag):
-/// select the hovered unit, then act by the same classification the cursor used (wow-re
-/// cursor-system.md §6). Three branches (decision 0081):
+/// select the hovered unit, then act by the same classification the cursor used (the INTERACT
+/// leg `0x492820`). Three branches (decision 0081):
 /// - **Attack** (alive + reaction ≤ neutral): auto-draw and start melee auto-attack, exactly the
 ///   action-bar attack's path (decision 0073's verified attack-start: SETSHEATHED then ATTACKSWING).
 /// - **Loot** (dead + `UNIT_DYNFLAG_LOOTABLE` — the state, not the Pickup cursor kind, which a
@@ -366,7 +364,7 @@ pub(super) fn act_on_right_click(
     let (hovered, hovered_object, cursor) = (&press.hovered, &press.object, &press.cursor);
     // ── The interact family's ACTOR gate: am I in the saddle? ────────────────────────────────
     // One predicate, the reference's own — the PLAYER's `UNIT_FIELD_MOUNTDISPLAYID` (decision
-    // 0481's "one mounted predicate"; wow-re `mounted-action-gate.md`: no aura, no taxi
+    // 0481's "one mounted predicate": no aura, no taxi
     // distinction, this field and nothing else). 0481 built the gate for the two action families
     // the director reported then — casts (`0x6094f0`'s reason `0x39` "You are mounted") and
     // attack-start (`0x612df0`'s `ERR_ATTACK_MOUNTED`) — and wrote interaction explicitly out of
@@ -381,15 +379,15 @@ pub(super) fn act_on_right_click(
     // A GameObject is the nearest thing under the cursor → use it (decision 0236), and never fall
     // through to unit handling: a GO is not selectable, and a right-click on it acts on the GO or
     // does nothing. The reference's `OnUse 0x5f8660` gates on the same two predicates the cursor
-    // computes (§4a/§8.7): **highlightable** first — false is a silent no-op, which for us is
+    // computes: **highlightable** first — false is a silent no-op, which for us is
     // `cursor.kind == Point` — then **usable**, whose failure toasts an error and sends nothing.
     //
     // `usable`'s two arms we model land in different places, so the routing is split accordingly
     // (decision 0752): the **lock** arm comes back out of [`resolve_go_action`] as
-    // `GoAction::Refuse`, which carries §8.8's toast; the **range** arm is `cursor.unable`, which
-    // suppresses the send with no toast (the reference auto-walks there instead — `0x610300`, also
-    // no packet). The lock arm runs first in `0x5f3130`, and it does here too: a `Refuse` toasts
-    // even when we are also out of range.
+    // `GoAction::Refuse`, which carries the lock-fail toast routing (`0x5f3427..`); the **range**
+    // arm is `cursor.unable`, which suppresses the send with no toast (the reference auto-walks
+    // there instead — `0x610300`, also no packet). The lock arm runs first in `0x5f3130`, and it
+    // does here too: a `Refuse` toasts even when we are also out of range.
     if go_is_nearest(hovered, hovered_object) {
         // **The interact chain's first link** (tag `use`). "I clicked it and nothing happened" spans
         // three systems — this decision, the `CMSG_GAMEOBJ_USE` it sends, and the `SMSG_SPELL_GO`
@@ -424,8 +422,7 @@ pub(super) fn act_on_right_click(
                 // `0x5f31a8`: errorId `0x19f` `ERR_NOT_WHILE_MOUNTED`, then `0x5f31d6 xor al,al`,
                 // so `0x5f86b0` never reaches the opener it would invoke at `0x5f86eb`. No
                 // `CMSG_GAMEOBJ_USE`, no cast, no state write — the gate returns before the
-                // opener, not merely before the message (wow-re `mounted-interaction-gate.md`
-                // §5.1, the §5 this session dispatched).
+                // opener, not merely before the message.
                 //
                 // **It applies only to LOCK-LESS objects.** The gate sits behind
                 // `0x5f3195 call 0x5f8180` / `0x5f319c jne 0x5f3231`, which resolves the object's
@@ -433,15 +430,14 @@ pub(super) fn act_on_right_click(
                 // herb or a locked chest bypasses this and is refused further down by its opener
                 // CAST's own mounted block — loudly, "You are mounted" — while a spellcaster, a
                 // chair, a `lockId 0` quest goober and a readable sign are refused HERE, in
-                // silence. What buys the bypass is a **lock**, not a spell; the round's first
-                // draft had that backwards and its own cross-check caught it.
+                // silence. What buys the bypass is a **lock**, not a spell.
                 //
                 // The test is pure **row existence**: `0x5f819c` tests the row *pointer*, and
                 // nothing reads `Type[]`/`Index[]`/`Skill[]` until `0x5f83d0`. So it is
                 // deliberately NOT [`benilla_formats::LockCatalog::is_locked`], which also demands
                 // a non-empty slot — an all-empty Lock row is "no lock" to our opener resolver and
                 // "a lock" to this gate, and the reference lets that object be used from the
-                // saddle. Collapsing the two is the one divergence the RE explicitly warned about.
+                // saddle. Collapsing the two diverges from the reference on exactly that object.
                 //
                 // **MAILBOX (type 19) is the only exemption**, and it lives inside the gate on the
                 // mounted arm alone (`0x5f31bb` → `0x47cff0`: a sixteen-byte `type == 0x13`
@@ -454,7 +450,7 @@ pub(super) fn act_on_right_click(
                 // side-effect branches skip for this row (`[row+0xc] == 0x44` takes the no-sound
                 // jump; `[row+0x8]` is the literal `"NONE"`), so nothing is shown, sounded or
                 // fired. Whether that leaves any visible artifact at all is the one thing the
-                // round could not settle from the binary — it wants one mounted click on a sign.
+                // binary could not settle — it wants one mounted click on a sign.
                 let lock_id = go_inputs.templates.get(guid).map_or(0, |t| t.lock_id);
                 let has_lock_row = lock_id != 0
                     && go_inputs
@@ -469,8 +465,8 @@ pub(super) fn act_on_right_click(
                     return;
                 }
                 // Mailbox (GO type 19): open the mail window client-side (decision 0544), BEFORE the
-                // lock fork (a mailbox is never locked). The wow-re §5 confirms the MAILBOX use
-                // handler overrides the shared use-sender to a LOCAL open — it sends NO packet (no
+                // lock fork (a mailbox is never locked). The MAILBOX use handler `0x5f6820`
+                // overrides the shared use-sender to a LOCAL open — it sends NO packet (no
                 // CMSG_GAMEOBJ_USE); the window's own MAIL_SHOW → CheckInbox drives the first
                 // CMSG_GET_MAIL_LIST. Re-clicking just re-shows (the session is already set).
                 if go.is_some_and(|(s, _)| s.0.gameobject_type_id() == cursor_mode::GO_TYPE_MAILBOX)
@@ -485,7 +481,7 @@ pub(super) fn act_on_right_click(
                 // fork (a readable is never locked). Its strategy overrides the use-slot the same
                 // way the mailbox does — `0x5f58c0` calls the local page-text opener
                 // `0x4e32e0(goGuid, 0)` and never the shared `CMSG_GAMEOBJ_USE` sender (decision
-                // 1105; wow-re cursor-system §4's "TEXT type 9 — its own handler"). Sending USE
+                // 1105). Sending USE
                 // instead is what left every world book dead: vmangos' `GameObject::Use` has no
                 // type-9 case at all, so the packet is answered with silence.
                 //
@@ -506,8 +502,8 @@ pub(super) fn act_on_right_click(
                 }
                 // MEETINGSTONE (GO type 23): **not** the shared use-sender. `[0x80bf40+0x1c]`
                 // is `0x5f69d0`, this type's own validator — four client-side refusals and then
-                // `CMSG 0x292 {u64 goGuid}` from `0x4c9ff0` (decision 2283; wow-re's §5 round on
-                // that function). The shared sender `0x5f33e0` is **unreachable** from here: it
+                // `CMSG 0x292 {u64 goGuid}` from `0x4c9ff0` (decision 2283). The shared sender
+                // `0x5f33e0` is **unreachable** from here: it
                 // has zero direct callers and 29 `.rdata` refs, every one at some vtable's
                 // `+0x1c`, and `0x80bf5c` is not among them — so a meeting stone cannot emit
                 // `CMSG_GAMEOBJ_USE` in the reference at all. Sending `0xB1` anyway is what left
@@ -515,9 +511,8 @@ pub(super) fn act_on_right_click(
                 // type-23 arm that does nothing ("Should never be called for this type of
                 // object", `GameObject.cpp:1836`), so the packet was answered with silence.
                 //
-                // Four types override `+0x1c`, not one — 9 TEXT, 19 MAILBOX, 23 and 28 — which
-                // corrects the wow-re sentence this file used to rest on (`+0x1c` is `0x5f33e0`
-                // "for every type but MAILBOX"); the round landed that correction too.
+                // Four types override `+0x1c`, not one — 9 TEXT, 19 MAILBOX, 23 and 28; every
+                // other strategy's `+0x1c` is `0x5f33e0`.
                 //
                 // Unlike those two it is NOT a local open — it is a real send, and it therefore
                 // sits *below* the mounted gate above (a stone is lock-less, and only MAILBOX is
@@ -539,7 +534,7 @@ pub(super) fn act_on_right_click(
                 // ON_USE) at it; an unopenable lock shows the client-local red toast — "The door is
                 // locked.", "Requires Herbalism", "Requires Mining 100", "Requires <key item>" —
                 // and sends nothing (the ref's validate/error block `0x5f3427..` fires
-                // `DisplayError` with no packet; wow-re cursor-system.md §8.4/§8.8).
+                // `DisplayError` with no packet).
                 match resolve_go_action(
                     guid,
                     &mut go_inputs,
@@ -562,7 +557,7 @@ pub(super) fn act_on_right_click(
                     }
                     // **Both opener arms queue for the one cast path** (decision 2199) — they
                     // do not send. The reference reaches `TryCast 0x6e4b60` from the GameObject
-                    // strategy's use-sender (`0x5f35c0 → 0x6e5a90 → 0x6e4b60`, §8.4) exactly as it
+                    // strategy's use-sender (`0x5f35c0 → 0x6e5a90 → 0x6e4b60`) exactly as it
                     // does from a button press, so an opener owes the whole ladder — the in-flight
                     // refusal above all, which is what keeps a mashed right-click from shipping a
                     // duplicate the server answers "Another action is in progress" while red-fading
@@ -681,7 +676,7 @@ pub(super) fn act_on_right_click(
                         .spells
                         .as_ref()
                         .and_then(|s| s.catalog.get(spell_id));
-                    if crate::ui_action::cast_mounted_refusal(self_mounted, def) {
+                    if crate::spell::validator::cast_mounted_refusal(self_mounted, def) {
                         debug!("right-click corpse insignia: refused locally — mounted (0x39)");
                         cast_errors.push_local(spell_id, 0x39);
                     } else {
@@ -703,8 +698,8 @@ pub(super) fn act_on_right_click(
     let target = stores.get(entity).ok().map(|(s, _)| s);
     // ── The dead-target fork of the reference's unit interact dispatcher `0x60bea0` ──────────
     // Loot routes by the same CLASSIFICATION the cursor used — dead + `UNIT_DYNFLAG_LOOTABLE` —
-    // not by the cursor kind (wow-re cursor-system.md §6: the right-click "routes the same hovered
-    // object by the same classification"; its dead-unit row sends CMSG_LOOT). The loot cursor's
+    // not by the cursor kind (the right-click routes the same hovered object by the same
+    // classification; its dead-unit row sends CMSG_LOOT). The loot cursor's
     // base mode is Pickup(8), which a live vendor also shows, so the kind alone can't name loot.
     //
     // **The fork's first test is the rider**, and we never carried it (decision 1851): `0x60bf98`
@@ -771,8 +766,8 @@ pub(super) fn act_on_right_click(
             // and the melee auto-draw and swing still never happen; what changed is that no red
             // `ERR_ATTACK_*` line shows any more.
             //
-            // 0481 attached `0x612df0`'s Phase A ladder to this path. The §5 this session dispatched
-            // found that validator has exactly three callers image-wide — pet-attack `0x4bd40d`, the
+            // 0481 attached `0x612df0`'s Phase A ladder to this path. That validator has exactly
+            // three callers image-wide — pet-attack `0x4bd40d`, the
             // Attack action/keybind `0x6131aa`, and TryCast `0x6e4efb` — and the world right-click is
             // none of them: it runs `0x60c247 call 0x5ecb70`, an extent containing no `DisplayError`
             // at all. So all eight of those red lines belong to the bar and the pet command, never to
@@ -841,7 +836,7 @@ pub(super) fn act_on_right_click(
                         .spells
                         .as_ref()
                         .and_then(|s| s.catalog.get(spell_id));
-                    if crate::ui_action::cast_mounted_refusal(self_mounted, def) {
+                    if crate::spell::validator::cast_mounted_refusal(self_mounted, def) {
                         debug!("right-click skin: refused locally — mounted (0x39)");
                         cast_errors.push_local(spell_id, 0x39);
                     } else {
@@ -910,7 +905,7 @@ pub(super) fn act_on_right_click(
                 .and_then(|item| {
                     let slot0 = u8::try_from(item.slot.saturating_sub(1)).unwrap_or(0);
                     self_store.and_then(|s| {
-                        crate::ui_items::slot_guid(&s.0, item.bag, slot0, &go_inputs.items)
+                        crate::ui_items::slot_guid(&s.0, item.bag, slot0, &go_inputs.objects)
                     })
                 });
             let Some(arm) = service_arm(npc_flags, service.quest.status(guid)) else {
@@ -998,16 +993,18 @@ pub(crate) enum GoAction {
     OpenLock(u32),
     /// A lock whose **KEY** slot we satisfy: *use the key at the object* — `CMSG_USE_ITEM` with the
     /// key's wire position and `TARGET_FLAG_GAMEOBJECT`, NOT a bare cast of the key's spell
-    /// (decision 0769; wow-re `cursor-system.md` §8.4 — "the client never sends a bare
-    /// CMSG_CAST_SPELL for a key lock"). The distinction is the whole ballgame: `Spell::CanOpenLock`
-    /// honours a `Lock.dbc` KEY slot only when `m_CastItem` is set, which only USE_ITEM supplies.
+    /// (decision 0769; the client never sends a bare CMSG_CAST_SPELL for a key lock: the cast
+    /// sender `0x6e54f0` takes its item arm). The distinction is the whole ballgame:
+    /// `Spell::CanOpenLock` honours a `Lock.dbc` KEY slot only when `m_CastItem` is set, which only
+    /// USE_ITEM supplies.
     ///
     /// Carried as a whole [`crate::ui_items::ItemUse`] (decision 2199) because the reference's
     /// lock chain calls `CGItem::Use` with the lock's guid — the one item-use fork every surface
     /// takes — rather than building a packet of its own. `on_object` is that guid.
     OpenByKey(crate::ui_items::ItemUse),
-    /// A lock present that we cannot open — the client-local refusal (§8.4: `DisplayError`, **no
-    /// packet**). `Some` = the red toast to queue; `None` = the ref is silent for this case too.
+    /// A lock present that we cannot open — the client-local refusal (`0x5f3427..`:
+    /// `DisplayError`, **no packet**). `Some` = the red toast to queue; `None` = the ref is silent
+    /// for this case too.
     Refuse(Option<crate::ui_action::UiError>),
 }
 
@@ -1015,8 +1012,8 @@ pub(crate) enum GoAction {
 enum KeyFact {
     /// Not held; the item template names it ("Requires Shadowforge Key").
     Named(String),
-    /// Not held and the template isn't cached yet — the ref's `GetRecord` miss is silent (§8.8
-    /// `0xde`); our ask-once query is away, so a later click names it.
+    /// Not held and the template isn't cached yet — the ref's `GetRecord` miss is silent (the
+    /// `0xde` arm's `0x5f3562 je`); our ask-once query is away, so a later click names it.
     Unknown,
 }
 
@@ -1028,18 +1025,18 @@ enum KeyFact {
 /// chest whose template is still in flight.
 ///
 /// The satisfaction decision itself lives in [`super::lock::resolve_lock`] so the cursor's `usable`
-/// asks exactly the same question (§4a/§8.7 — the icon and the click agree by construction). Here
-/// we only turn its answer into a packet, and the lock split has **three** arms, not two (wow-re
-/// `cursor-system.md` §8.4, VERIFIED): lockless → `CMSG_GAMEOBJ_USE`; a satisfied **skill** slot →
+/// asks exactly the same question (the resolver `0x5f83d0` — the icon and the click agree by
+/// construction). Here we only turn its answer into a packet, and the lock split has **three**
+/// arms, not two: lockless → `CMSG_GAMEOBJ_USE`; a satisfied **skill** slot →
 /// `CMSG_CAST_SPELL` of the matched opener; a satisfied **key** slot → `CMSG_USE_ITEM` carrying the
 /// key's position and the GO as its cast target ([`GoAction::OpenByKey`]). An unmet lock takes
-/// §8.8's toast routing and sends nothing.
+/// the toast routing of `0x5f3427..` and sends nothing.
 ///
 /// The key arm sent a bare cast until decision 0769, which is why keys never opened anything: the
 /// server honours a KEY slot only when the cast carries `m_CastItem` (`Spell::CanOpenLock`,
 /// `Spell.cpp:7892`), and only `CMSG_USE_ITEM` supplies it. That was recorded here as the server's
-/// gap; it was ours, and wow-re's note says so in the same breath — "the client never sends a bare
-/// CMSG_CAST_SPELL for a key lock".
+/// gap; it was ours: the client never sends a bare CMSG_CAST_SPELL for a key lock (the cast sender
+/// `0x6e54f0` takes its item arm).
 pub(crate) fn resolve_go_action(
     guid: u64,
     inputs: &mut GoLockInputs,
@@ -1055,7 +1052,7 @@ pub(crate) fn resolve_go_action(
         return GoAction::Use;
     };
     // A lockId whose row is missing is "no lock" — the ref resolver's `0x5f8180` null → FALSE with
-    // spell 0 → `CMSG_GAMEOBJ_USE` (§8.4 C6).
+    // spell 0 → `CMSG_GAMEOBJ_USE`.
     let Some(slots) = locks.0.slots(tmpl.lock_id).filter(|_| tmpl.lock_id != 0) else {
         return GoAction::Use;
     };
@@ -1067,7 +1064,7 @@ pub(crate) fn resolve_go_action(
         inputs.spells.as_deref(),
         inputs.skill_lines.as_ref().map(|s| &s.catalog),
         me_store,
-        &inputs.items,
+        &inputs.objects,
         facts,
         &mut matched,
     );
@@ -1083,8 +1080,8 @@ pub(crate) fn resolve_go_action(
         }
         super::lock::LockOutcome::OpenByKey(entry) => entry,
         super::lock::LockOutcome::Unmet => {
-            // Unopenable — §8.8's routing, which keys off Lock.dbc **slot 0** regardless of which
-            // slot the resolver walked.
+            // Unopenable — the toast routing of `0x5f3427..`, which keys off Lock.dbc **slot 0**
+            // regardless of which slot the resolver walked.
             let slot0 = slots[0];
             let key = if slot0.key_type == benilla_formats::LOCK_KEY_ITEM {
                 match inputs.items.template(slot0.index, 0, net) {
@@ -1118,7 +1115,7 @@ pub(crate) fn resolve_go_action(
     };
     let Some((bag_index, slot, key_guid)) = crate::ui_items::find_item(
         &store.0,
-        &inputs.items,
+        &inputs.objects,
         key_entry,
         crate::ui_items::ItemSearch::default(),
     ) else {
@@ -1147,8 +1144,8 @@ pub(crate) fn resolve_go_action(
     })
 }
 
-/// The client-local toast for an unopenable lock — the ref's routing, transcribed (wow-re
-/// cursor-system.md §8.8; decision 0545). Two layers, exactly as the binary orders them:
+/// The client-local toast for an unopenable lock — the ref's routing (`0x5f3427..`), transcribed
+/// (decision 0545). Two layers, exactly as the binary orders them:
 ///
 /// 1. **`GO_FLAG_LOCKED` set** (a padlocked chest/door — gather nodes never set it): the `usable`
 ///    gate refuses with the strategy default `[strat+8]` before the rich routing ever runs —
@@ -1187,7 +1184,7 @@ fn route_lock_refusal(
             let name = lock_type_name.unwrap_or("UNKNOWN").to_string();
             if opener_known {
                 let required = super::lock::required_skill(slot0, go_level).max(0) as u32;
-                // String-then-Integer, the template's own order (cursor-system.md §8.8).
+                // String-then-Integer, the template's own order.
                 Some(UiError::args(
                     "ERR_USE_LOCKED_WITH_SPELL_KNOWN_SI",
                     vec![FillArg::S(name), FillArg::D(i64::from(required))],
@@ -1301,9 +1298,7 @@ fn unit_branch(attack: bool, dead_fork: bool, leg: DeadUnitLeg) -> UnitBranch {
 }
 
 /// **The reference's own NPC-service ladder** — `0x5f0130`'s first-match-wins walk over
-/// `UNIT_NPC_FLAGS`, low bit to high (wow-re
-/// `object-layer/scratch/interact-dead-fork-and-npc-service-ladder.md` §C, every arm byte-verified
-/// from its `shr`/`test` to its `push <opcode>`). The winning bit, **not** a cursor kind.
+/// `UNIT_NPC_FLAGS`, low bit to high. The winning bit, **not** a cursor kind.
 ///
 /// The cursor classifier `0x482200` runs a second, structurally identical ladder over the same
 /// field in the same order, which is why keying the send on the classified kind looked right for
@@ -1528,8 +1523,7 @@ pub(crate) struct DeselectGuid(pub(crate) u64);
 ///
 /// One drain for the three because the reference has one function for them: `TargetUnit
 /// 0x4899d0`, `AssistUnit 0x489b80`, `TargetLastEnemy` and `TargetLastTarget` all reach selection
-/// through the "select if it resolves" helper `0x489a40` (wow-re
-/// `object-layer/scratch/selection-attack-seam.md` §1), whose three arms — resolves → commit;
+/// through the "select if it resolves" helper `0x489a40`, whose three arms — resolves → commit;
 /// doesn't resolve but is on the roster → commit anyway; **neither, including guid 0 → a bare
 /// `ret`** — are the same for every caller. That third arm is the one worth naming: a token,
 /// basis or remembered guid that does not resolve is a **no-op, not a deselect**. Draining them
@@ -1581,7 +1575,7 @@ pub(super) fn selection_requests(
             }
             // `0x489ba9 call 0x515940(token)` — the same token grammar, then the shared tail. An
             // unresolvable token is silent here: the reference emits game-message `0xb8`, whose
-            // id→string table is runtime-populated BSS wow-re could not statically recover — the
+            // id→string table is runtime-populated BSS with no statically recoverable text — the
             // known deviation `TargetByName` already carries on this path.
             SelectionRequest::Assist(token) => match tokens.resolve(&token, &commit.selection) {
                 Some((basis, _)) => commit.assist(basis, "AssistUnit"),
@@ -1593,10 +1587,9 @@ pub(super) fn selection_requests(
                 assist_by_name.write(super::by_name::AssistRequest { name: Some(name) });
             }
             // `0x489b45` reads the last-attackable pair and hands it to the same `0x489a40`.
-            // **Empty memory is a no-op, and that is derived now**: the shim `0x489b40` is
-            // thirteen bytes with no emptiness test at all, where `TargetLastTarget 0x489b00`
-            // really does reach `0x493540(0,0)` and deselect. The two shims differ exactly here
-            // (wow-re `targeting-friend-and-lastenemy.md`, §5 trio — dispatched from this work).
+            // **Empty memory is a no-op**: the shim `0x489b40` is thirteen bytes with no
+            // emptiness test at all, where `TargetLastTarget 0x489b00` really does reach
+            // `0x493540(0,0)` and deselect. The two shims differ exactly here.
             SelectionRequest::LastEnemy => {
                 let Some(guid) = last_enemy.0 else {
                     info!("TargetLastEnemy: nothing hostile has been targeted yet; no-op");
@@ -1640,9 +1633,9 @@ pub(super) fn clear(
 mod tests {
     use super::*;
 
-    /// The §8.8 toast routing, case by case (decision 0545). The slot/flag/type combinations
-    /// mirror real data: Peacebloom (lock 29: skill slot, LockType 2, Skill 0), a rank-155 vein
-    /// (lock 42: LockType 3, Skill 155), a keyed door, a padlocked chest.
+    /// The `0x5f3427..` toast routing, case by case (decision 0545). The slot/flag/type
+    /// combinations mirror real data: Peacebloom (lock 29: skill slot, LockType 2, Skill 0), a
+    /// rank-155 vein (lock 42: LockType 3, Skill 155), a keyed door, a padlocked chest.
     #[test]
     fn lock_refusals_route_like_the_reference() {
         use benilla_formats::{LockSlot, LOCK_KEY_ITEM, LOCK_KEY_SKILL};
@@ -1736,8 +1729,8 @@ mod tests {
         assert!(
             route_lock_refusal(&key_slot, false, false, 0, 0, None, KeyFact::Unknown).is_none()
         );
-        // GO_FLAG_LOCKED set → the strategy default REPLACES the rich routing (§8.8's usable
-        // gate): door 0xdc, button 0xdd, chest/else 0xdb — even on a skill lock.
+        // GO_FLAG_LOCKED set → the strategy default REPLACES the rich routing (`usable`'s lock
+        // check, `0x5f32a6`): door 0xdc, button 0xdd, chest/else 0xdb — even on a skill lock.
         for (go_type, key) in [
             (0, "ERR_DOOR_LOCKED"),
             (1, "ERR_BUTTON_LOCKED"),
@@ -2175,10 +2168,10 @@ mod tests {
             let mut world = World::new();
             world.insert_resource(NetCommands(tx));
             world.init_resource::<InspectMode>();
-            world.init_resource::<crate::ui_cast::QueuedMeleeSpell>();
-            world.init_resource::<crate::ui_action::AutoRepeatActive>();
+            world.init_resource::<crate::spell::QueuedMeleeSpell>();
+            world.init_resource::<crate::spell::AutoRepeatActive>();
             world.init_resource::<crate::ui_script::CursorPayloadHeld>();
-            world.init_resource::<crate::ui_action::SpellTargeting>();
+            world.init_resource::<crate::spell::SpellTargeting>();
             world.init_resource::<ClickConfig>();
             world.init_resource::<Messages<crate::creature_anim::SheathRequest>>();
             world.init_resource::<Messages<crate::player::StandStateRequest>>();
@@ -2261,8 +2254,8 @@ mod tests {
         let (tx, _rx) = crossbeam_channel::unbounded();
         let mut world = World::new();
         world.insert_resource(NetCommands(tx));
-        world.init_resource::<crate::ui_cast::QueuedMeleeSpell>();
-        world.init_resource::<crate::ui_action::AutoRepeatActive>();
+        world.init_resource::<crate::spell::QueuedMeleeSpell>();
+        world.init_resource::<crate::spell::AutoRepeatActive>();
         world.init_resource::<Messages<crate::creature_anim::SheathRequest>>();
         world.init_resource::<crate::ui_party::GroupState>();
         world.init_resource::<crate::net::GuidIndex>();
@@ -2352,13 +2345,14 @@ mod tests {
         world.init_resource::<Messages<WorldRightClick>>();
         world.init_resource::<PressPick>();
         world.init_resource::<Selection>();
-        world.init_resource::<crate::ui_cast::QueuedMeleeSpell>();
-        world.init_resource::<crate::ui_action::AutoRepeatActive>();
+        world.init_resource::<crate::spell::QueuedMeleeSpell>();
+        world.init_resource::<crate::spell::AutoRepeatActive>();
         world.init_resource::<Messages<crate::creature_anim::SheathRequest>>();
         world.init_resource::<Messages<crate::player::StandStateRequest>>();
         world.init_resource::<crate::creature_anim::GestureQueue>();
         world.init_resource::<crate::go_templates::GameObjectTemplates>();
         world.init_resource::<crate::items::Items>();
+        world.init_resource::<crate::net::GuidIndex>();
         world.init_resource::<crate::ui_action::PlayerActions>();
         world.init_resource::<crate::ui_action::LearnedAbilities>();
         world.init_resource::<crate::ui_quest::QuestGiver>();
diff --git a/crates/benilla-app/src/target/cursor_mode.rs b/crates/benilla-app/src/target/cursor_mode.rs
index d0901757..7b3b6dc4 100644
--- a/crates/benilla-app/src/target/cursor_mode.rs
+++ b/crates/benilla-app/src/target/cursor_mode.rs
@@ -1,5 +1,4 @@
-//! The context-sensitive **world cursor** — the classifier half (wow-re cursor RE, note
-//! `ui/scratch/cursor-system.md`, §3 per-bit service table + §5 gates, all byte-verified).
+//! The context-sensitive **world cursor** — the classifier half.
 //!
 //! Each frame, the hovered unit resolves to a [`CursorKind`] the way the real client's
 //! `CGWorldFrame` classifier does (`0x4828d0` → unit branch `0x482200`):
@@ -59,31 +58,31 @@ pub(crate) enum CursorKind {
     /// innkeeper service.
     Interact,
     Buy,
-    /// Inspect(7) — the magnifier. The UI's Ctrl-hover cursor (`ShowInspectCursor`, wow-re
-    /// cursor-system.md §7, overlaid by [`crate::cursor`]) **and** the world cursor over a
-    /// readable TEXT(9) GameObject plaque (§4).
+    /// Inspect(7) — the magnifier. The UI's Ctrl-hover cursor (`ShowInspectCursor 0x48ac60`,
+    /// overlaid by [`crate::cursor`]) **and** the world cursor over a
+    /// readable TEXT(9) GameObject plaque (`0x5f5890`).
     Inspect,
     Trainer,
     Taxi,
     Skin,
     /// Repair(17) — never set by the world classifier (the ladder skips the REPAIR bit); it is
-    /// the UI's repair-mode base cursor (`ShowRepairCursor`'s locked mode, wow-re
-    /// repair-machinery.md), overlaid by [`crate::cursor`].
+    /// the UI's repair-mode base cursor (`ShowRepairCursor 0x4fbcc0`'s locked mode), overlaid by
+    /// [`crate::cursor`].
     Repair,
-    /// Mail(15) — a MAILBOX(19) / RITUAL(18) / type-28 GameObject (wow-re cursor-system.md §4:
-    /// the shared `0x5f6840`/`0x5f6e30` behavior). The mailbox's own cursor, not the gear.
+    /// Mail(15) — a MAILBOX(19) / RITUAL(18) / type-28 GameObject (the shared
+    /// `0x5f6840`/`0x5f6e30` behavior). The mailbox's own cursor, not the gear.
     Mail,
     /// Mine(11) — a GameObject whose lock's first `LockType` is Mining (3). A LockType.dbc
-    /// data-named cursor (§4), resolved off the GO's lock, not a fixed type.
+    /// data-named cursor (`0x5f3070`), resolved off the GO's lock, not a fixed type.
     Mine,
     /// GatherHerbs(13) — a GameObject whose lock's first `LockType` is Herbalism (2). Also a
     /// LockType.dbc data-named cursor.
     GatherHerbs,
     /// PickLock(14) — a GameObject whose lock's first `LockType` is Pick Lock (`LockType.Id == 1`).
-    /// The one data-named GO cursor that is **never grayed** (§4: `LockType.Id == 1` skips the
-    /// usable gate), since any rogue can attempt the lock.
+    /// The one data-named GO cursor that is **never grayed** (`0x5f3070`: `LockType.Id == 1` skips
+    /// the usable gate), since any rogue can attempt the lock.
     PickLock,
-    /// Cast(2) — the spell-targeting cursor (wow-re cursor-system.md §5, VERIFIED law): while a
+    /// Cast(2) — the spell-targeting cursor (`0x4820f0`): while a
     /// spell awaits a target, dispatcher step 2 pre-empts the WHOLE object classifier with
     /// Cast/UnableCast. Never set by the classifier here — it is [`crate::cursor`]'s
     /// armed-enchant-pick overlay (the one spell-targeting state benilla ships).
@@ -191,14 +190,14 @@ const MELEE_FLOOR: f32 = 5.0;
 /// The same `max(rA + rB + 1.333, 5.0)` shape as [`MELEE_FLOOR`] above, evaluated for a corpse:
 /// a corpse descriptor carries no `UNIT_FIELD_COMBATREACH` at all, so the sum can never clear the
 /// floor and the gate is the floor. Two independent byte facts agree on the number — the cursor
-/// leg's `CanLootNow 0x5ec110`, and the `CMSG_LOOT` sender `0x5df130`, whose owned bit-exact
-/// difftest (`loot_range_5df130_difftest`) compares `dist²` against a literal `25.0`. Written as
-/// the constant rather than the formula because the formula's other term does not exist here.
+/// leg's `CanLootNow 0x5ec110`, and the `CMSG_LOOT` sender `0x5df130`, which compares `dist²`
+/// against a literal `25.0`. Written as the constant rather than the formula because the formula's
+/// other term does not exist here.
 /// Boundary-inclusive, center-to-center, like every other reach gate in this file.
 const CORPSE_INTERACT_RANGE_SQ: f32 = 25.0;
 
 /// `GAMEOBJECT_TYPE_GENERIC` (vmangos `SharedDefines.h`) — world decoration whose highlightable
-/// predicate is constant-false, so it never shows an interact cursor (wow-re cursor-system §4a).
+/// predicate is constant-false, so it never shows an interact cursor (`0x5f47f0`).
 pub(crate) const GO_TYPE_GENERIC: i32 = 5;
 /// The transport family — TRANSPORT(11), MAP_OBJECT(14), MO_TRANSPORT(15): their strategy vtables'
 /// highlightable slot (+0x14) is constant-false too (`32 c0 c3` — vtable dump from the 5875 binary:
@@ -210,9 +209,8 @@ const GO_TYPE_MO_TRANSPORT: i32 = 15;
 /// The **marker set** — SPELL_FOCUS(8), DUEL_ARBITER(16), FISHINGHOLE(25), AURA_GENERATOR(30).
 /// Their strategy vtables are the mirror image of the transports': `+0xc` (mouseover eligibility) is
 /// a constant `b0 01 c3` = `mov al,1; ret` and `+0x14` (**highlightable**) a constant
-/// `32 c0 c3` = `xor al,al; ret` (wow-re `object-layer/scratch/go-render-gate.md`, "the per-type
-/// handler vtables": vtables `0x80b8a8`/`0x80bb68`/`0x80bbf8`/`0x80c2a0`, `+0xc` targets
-/// `0x5f57e0`/`0x5f65f0`/`0x5f6660`/`0x5f6ea0`, `+0x14` targets
+/// `32 c0 c3` = `xor al,al; ret` (vtables `0x80b8a8`/`0x80bb68`/`0x80bbf8`/`0x80c2a0`, `+0xc`
+/// targets `0x5f57e0`/`0x5f65f0`/`0x5f6660`/`0x5f6ea0`, `+0x14` targets
 /// `0x5f57f0`/`0x5f6600`/`0x5f6670`/`0x5f6eb0` — const bytes read for all four).
 ///
 /// So they hover but never *interact*: the anvil, the forge, the campfire, the duel flag, the fishing
@@ -228,7 +226,7 @@ const GO_TYPE_AURA_GENERATOR: i32 = 30;
 /// The highest GAMEOBJECT_TYPE_ID the type factory has a `case` for. The jump table `0x5f76cc`
 /// covers 0..=30; **21 GUARDPOST has no case of its own** and falls to `default:` with everything
 /// out of range — the arms' `__LINE__` pushes step three apart across the 30 real types with none
-/// for 21 (wow-re `animation/scratch/gameobject-anim-arm.md`, the per-type arm table).
+/// for 21.
 const GO_TYPE_MAX: i32 = 30;
 /// `GAMEOBJECT_TYPE_GUARDPOST` (21) — see [`strategy_is_default`].
 const GO_TYPE_GUARDPOST: i32 = 21;
@@ -240,21 +238,19 @@ const GO_TYPE_GUARDPOST: i32 = 21;
 /// That vtable's `+0x14` is `0x5f36f0` = `xor al,al`, and its `+0xc` forwards to it — so a
 /// default-strategy object is neither highlightable nor mouseover-eligible: it shows nothing at all.
 ///
-/// Byte-cited in wow-re `animation/scratch/gameobject-anim-arm.md` (the arm bytes, the initializer,
-/// and the `BADBASEGAMEOBJECT` string) and corroborated independently by
-/// `object-layer/scratch/w2c1.md` ("case 0x15 falls to `default`"). Unobservable on this server —
-/// vanilla ships no type-21 template and a 1.12 server sends nothing out of range — but modelled
-/// rather than left to the flag predicate, which would answer `true` for an all-zero descriptor.
+/// Unobservable on this server — vanilla ships no type-21 template and a 1.12 server sends nothing
+/// out of range — but modelled rather than left to the flag predicate, which would answer `true`
+/// for an all-zero descriptor.
 fn strategy_is_default(type_id: i32) -> bool {
     type_id == GO_TYPE_GUARDPOST || !(0..=GO_TYPE_MAX).contains(&type_id)
 }
 /// `GAMEOBJECT_TYPE_TEXT` (9) — a readable book/plaque/sign; its per-type behavior shows the
-/// **Inspect** magnifier (wow-re cursor-system §4, `0x5f5890`), not the gear. `pub(super)` so the
+/// **Inspect** magnifier (`0x5f5890`), not the gear. `pub(super)` so the
 /// right-click dispatch ([`super::act_on_right_click`]) routes it to the client-side reader off the
 /// one type constant (decision 1105), the same shape as the mailbox — and `pub(crate)` beyond that
 /// so the inspector's GO card can report the readable head against the same constant.
 pub(crate) const GO_TYPE_TEXT: i32 = 9;
-/// The three GameObject types that show the **Mail** cursor (wow-re cursor-system §4): RITUAL(18)
+/// The three GameObject types that show the **Mail** cursor: RITUAL(18)
 /// and MAILBOX(19) share one behavior (`0x5f6840`), and type 28 (`0x5f6e30`) resolves to Mail too.
 /// Type 28 has no live 1.12 data but is included for byte-fidelity with the factory switch.
 const GO_TYPE_RITUAL: i32 = 18;
@@ -265,18 +261,17 @@ const GO_TYPE_28: i32 = 28;
 /// Interim GameObject interact-range gray (decision 0236): reuse the ~5.56 yd service reach until the
 /// size-dependent GO interact distance is byte-pinned. Squared, boundary-inclusive like the unit gates.
 const GO_INTERACT_RANGE_SQ: f32 = SERVICE_RANGE_SQ;
-/// `GAMEOBJECT_TYPE_FISHINGNODE` (17) — the fishing bobber. Its strategy (vtable `0x80bc80`, wow-re
-/// `fishing-bobber-interaction.md`) overrides exactly one consumed slot: highlightable is the
-/// channel-ownership gate ([`highlightable_flags`]'s type-17 arm); everything else is the shared base.
+/// `GAMEOBJECT_TYPE_FISHINGNODE` (17) — the fishing bobber. Its strategy (vtable `0x80bc80`)
+/// overrides exactly one consumed slot: highlightable is the channel-ownership gate
+/// ([`highlightable_flags`]'s type-17 arm); everything else is the shared base.
 pub(crate) const GO_TYPE_FISHINGNODE: i32 = 17;
 /// The per-type interact range the shared `usable 0x5f3130` compares — the strategy ctor's
-/// `[strat+0xc]` constant, **squared at the compare**, boundary-inclusive (wow-re
-/// `fishing-bobber-interaction.md` §3). FISHINGNODE's ctor sets **100.0 yd** (`0x5f66b0`,
-/// `[0x80b0b0]`) — the bobber is effectively un-range-gated for any real cast, never the ~5.56 yd
-/// reach. Other types stay on the 0236 interim (the base default is 5.0 and several per-type ctors
-/// override it — 5.5556/10.0/…; their population is a later byte-pin).
-/// `GAMEOBJECT_TYPE_CHAIR` (7) — the byte-pinned second member of the per-type table (decision
-/// 1464, wow-re's chair §5). Its `+0x18` predicate is its own `0x5f5670`, which reports **3.0 yd**
+/// `[strat+0xc]` constant, **squared at the compare**, boundary-inclusive. FISHINGNODE's ctor sets
+/// **100.0 yd** (`0x5f66b0`, `[0x80b0b0]`) — the bobber is effectively un-range-gated for any real
+/// cast, never the ~5.56 yd reach. Other types stay on the 0236 interim (the base default is 5.0
+/// and several per-type ctors override it — 5.5556/10.0/…; their population is a later byte-pin).
+/// `GAMEOBJECT_TYPE_CHAIR` (7) — the second member of the per-type table (decision 1464). Its
+/// `+0x18` predicate is its own `0x5f5670`, which reports **3.0 yd**
 /// and accepts on `dist² < 9.0` against `[0xc4d808]` — whose only writer image-wide is the static
 /// initializer `0x5f98b0` squaring that same 3.0. Chair-exclusive, and it independently reproduces
 /// vmangos's `MAX_SITCHAIRUSE_DISTANCE`, which is why it is safe to hold as *client* law rather
@@ -302,7 +297,7 @@ fn go_interact_range_sq(type_id: i32) -> f32 {
         _ => GO_INTERACT_RANGE_SQ,
     }
 }
-/// `GameObjectFlags` bits consulted by the highlightable gate (decision 0243, wow-re cursor-system §4a):
+/// `GameObjectFlags` bits consulted by the highlightable gate `0x5f2f80` (decision 0243):
 /// `0x1` IN_USE (busy) and `0x10` NO_INTERACT both suppress interaction; their union is the fast reject.
 const GO_FLAG_IN_USE_OR_NO_INTERACT: u32 = 0x11;
 /// `GO_FLAG_INTERACT_COND` (`0x4`) — the object is usable **only** when its per-player activate dyn-flag
@@ -315,10 +310,9 @@ const GO_DYNFLAG_ACTIVATE: u32 = 0x1;
 /// The GameObject types whose strategy vtable **overrides** the highlightable slot (`+0x14`) with a
 /// constant `xor al,al` — so `0x5f2f80` is never reached for them and they are never highlightable,
 /// whatever their flags, faction or activate bit say. **Eleven of the thirty-one types**, byte-read
-/// off the 5875 vtables (wow-re `object-layer/scratch/go-strategy-vtable-table.md`, the complete
-/// 31-row table): GENERIC(5) `0x5f47f0` · the transports 11/14/15 · the marker set 8/16/25/30 ·
-/// AUCTIONHOUSE(20) `0x5f68a0` · CAPTURE_POINT(29) `0x5f6d40` · and the default strategy
-/// ([`strategy_is_default`]) `0x5f36f0`.
+/// off the 5875 vtables: GENERIC(5) `0x5f47f0` · the transports 11/14/15 · the marker set
+/// 8/16/25/30 · AUCTIONHOUSE(20) `0x5f68a0` · CAPTURE_POINT(29) `0x5f6d40` · and the default
+/// strategy ([`strategy_is_default`]) `0x5f36f0`.
 ///
 /// This is the whole per-type half of the predicate, kept as one named list because the reference
 /// keeps it as one vtable slot: adding a type here removes its cursor, its brighten, its right-click
@@ -376,7 +370,7 @@ pub(crate) struct GoOverrides {
 /// `template.data[2] (areaID) != [0xb72038]` — see [`highlightable_flags`]'s `meeting_stone_queued`.
 pub(super) const GO_TYPE_MEETINGSTONE: i32 = 23;
 
-/// The client's GameObject **highlightable** predicate (decision 0243, wow-re cursor-system §4a,
+/// The client's GameObject **highlightable** predicate (decision 0243,
 /// `0x5f2f80`) over its wire flags: whether the object shows an interact cursor / is clickable at all.
 /// The types whose vtable constant-falses the slot never get here at all
 /// ([`strategy_never_highlightable`]); of the rest, a busy (IN_USE) or NO_INTERACT object isn't
@@ -386,15 +380,15 @@ pub(super) const GO_TYPE_MEETINGSTONE: i32 = 23;
 /// its (zero) activate bit. `usable` (lock / range / player-state → the grayed twin) rides on top and
 /// is a later refinement.
 ///
-/// `channel_owned` is the FISHINGNODE override's one input (`0x5f6710`, wow-re
-/// `fishing-bobber-interaction.md` §2): whether the active player's `UNIT_FIELD_CHANNEL_OBJECT`
+/// `channel_owned` is the FISHINGNODE override's one input (`0x5f6710`): whether the active
+/// player's `UNIT_FIELD_CHANNEL_OBJECT`
 /// equals **this** GO's guid. The bobber is highlightable only to the player currently channeling
 /// at exactly it — NOT a `CREATED_BY` compare — then tail-jumps into this shared gate. Someone
 /// else's bobber (or yours after the channel drops) produces nothing at all: no cursor, no
 /// tooltip/brighten (the `+0xc` thunk), and a silent dead right-click. Ignored for every other type.
 ///
-/// `meeting_stone_queued` is MEETINGSTONE(23)'s override (`0x5f6990`, wow-re
-/// `go-strategy-vtable-table.md`): the slot is `template.data[2] (areaID) != [0xb72038]`, and
+/// `meeting_stone_queued` is MEETINGSTONE(23)'s override (`0x5f6990`): the slot is
+/// `template.data[2] (areaID) != [0xb72038]`, and
 /// `0xb72038` is the area the player is currently queued at — zero-initialized at `0x4c9eec`,
 /// written only by the meeting-stone server-message handler `0x4ca230`, and read back by the Lua
 /// binding `IsInMeetingStoneQueue`. So a stone is highlightable **unless it is the stone you are
@@ -475,10 +469,9 @@ pub(crate) fn go_reaction(
 }
 
 /// The **mouseover-eligibility** virtual `[obj->vtbl+0x54]` — the gate that decides whether a picked
-/// object becomes the mouseover **at all** (wow-re `tooltip-content-law.md` §2-GAMEOBJECT, rewritten
-/// 2026-07-29; decision 0762).
+/// object becomes the mouseover **at all** (decision 0762).
 ///
-/// This sits one level above everything the tooltip law used to be reasoned from. The per-frame
+/// This sits one level above everything the GO tooltip used to be reasoned from. The per-frame
 /// classifier `CGWorldFrame::UpdateMouseoverCursor 0x4828d0` calls it on the picked object and, when
 /// it answers false, publishes the **null** mouseover GUID (`0x482985 test eax,eax; je 0x4829ed` →
 /// `0x482090(0,0)` + `ResetCursor 0x523d30`). The publisher `0x492890`, the tooltip builder
@@ -501,8 +494,8 @@ pub(crate) fn go_reaction(
 /// brighten, no USE). Eligibility is never a stand-in for [`highlightable_flags`], and neither is
 /// its negation.
 ///
-/// **This refutes the old "the tooltip is not gated by highlightable" reading** — that note verified
-/// the publisher correctly and then generalised **GENERIC's** behaviour to all 31 types. The
+/// **This refutes the old "the tooltip is not gated by highlightable" reading**, which generalised
+/// **GENERIC's** behaviour to all 31 types. The
 /// signpost half survives (GENERIC really does answer from `data[1]`, and 1387 of 1870 shipped
 /// type-5 templates carry `data1 = 1`); the chest / IN_USE / INTERACT_COND half is wrong, and this
 /// is why a pre-quest Stone of Binding or a Stratholme portcullis shows nothing in the reference.
@@ -587,7 +580,7 @@ pub(crate) fn fishing_channel_owned(
 }
 
 /// A `LockType.dbc` **CursorName** stem → the [`CursorKind`] it names — the client's
-/// `CursorModeFromName` step (wow-re cursor-system.md §4, `0x523d40`) over the only three cursor-
+/// `CursorModeFromName` step (`0x523d40`) over the only three cursor-
 /// bearing lock kinds in 5875. An unknown/empty name resolves to `None`, which the base GO path
 /// reads as "the generic Interact gear."
 fn cursor_kind_from_lock_name(name: &str) -> Option<CursorKind> {
@@ -599,7 +592,7 @@ fn cursor_kind_from_lock_name(name: &str) -> Option<CursorKind> {
     }
 }
 
-/// The **data-named** cursor for a base-type GameObject's lock (wow-re cursor-system.md §4): the GO
+/// The **data-named** cursor for a base-type GameObject's lock (the base `0x5f3070`): the GO
 /// template's `lockId` → the `Lock.dbc` row → its **first** requirement slot's index (the client
 /// reads `[lockRow+0x24]` = `Index[0]` unconditionally, no scan) → the `LockType.dbc` **CursorName**.
 /// `None` when there's no lock, no client data, or the LockType has no distinct cursor — the caller
@@ -620,7 +613,7 @@ fn go_lock_cursor(
     cursor_kind_from_lock_name(name)
 }
 
-/// The GameObject cursor kind (wow-re cursor-system.md §4), given a **highlightable** GO's type and
+/// The GameObject cursor kind (`GetCursorMode 0x5f8760`), given a **highlightable** GO's type and
 /// its resolved lock cursor. The per-type behaviors that override the base gear: TEXT(9) → the
 /// Inspect magnifier; RITUAL(18)/MAILBOX(19)/type-28 → Mail. Every other type is the base behavior:
 /// its data-named lock cursor (Mine/GatherHerbs/PickLock) if it has one, else the generic Interact.
@@ -633,10 +626,9 @@ fn go_cursor_kind(type_id: i32, lock_cursor: Option<CursorKind>) -> CursorKind {
 }
 
 /// The QUESTGIVER leg's own gate — the bit alone is not enough. The ladder calls `0x5df490(unit)`,
-/// which is `NPC_FLAGS bit 1` **AND** the cached quest status `[unit+0xcb8] ∉ {0, 1}` (wow-re
-/// `ui/scratch/cursor-system.md` §3, byte-verified row; `object-layer/scratch/questgiver-marker.md`
-/// independently pins `+0xcb8` as the `SMSG_QUESTGIVER_STATUS` cache, written by `0x607440` and with
-/// only three writers repo-wide). So NONE(0) and UNAVAILABLE(1) do **not** make a unit talkable;
+/// which is `NPC_FLAGS bit 1` **AND** the cached quest status `[unit+0xcb8] ∉ {0, 1}` (`+0xcb8`
+/// is the `SMSG_QUESTGIVER_STATUS` cache, written by `0x607440` and with
+/// only three writers image-wide). So NONE(0) and UNAVAILABLE(1) do **not** make a unit talkable;
 /// every other status does.
 ///
 /// This is what keeps a questgiver-flagged NPC with nothing to offer from being clickable at all —
@@ -655,8 +647,8 @@ pub(crate) fn questgiver_has_quest(quest_status: Option<u32>) -> bool {
     !matches!(quest_status, None | Some(NONE) | Some(UNAVAILABLE))
 }
 
-/// The per-bit service ladder (`0x482336..0x4824e3`, statically unrolled — every row byte-verified
-/// in the RE note's §3 table): lowest set bit wins. `None` = no *consulted* bit set — the unit
+/// The per-bit service ladder (`0x482336..0x4824e3`, statically unrolled): lowest set bit wins.
+/// `None` = no *consulted* bit set — the unit
 /// falls through to the attack/clear leg (this is where repair-only units land: bit 14 is never
 /// tested in the binary).
 ///
@@ -705,8 +697,7 @@ fn loot_cursor(auto_loot: bool, shift_held: bool) -> CursorKind {
 }
 
 /// Is this corpse **moused over at all** — the reference's `[CGCorpse_C vtbl+0x54]` = `0x5d76d0`,
-/// asked at `0x482982` by the mouseover publisher (wow-re `corpse-click-and-reclaim.md` Q6, §5
-/// cross-checked).
+/// asked at `0x482982` by the mouseover publisher.
 ///
 /// A **real body** (BONES clear) qualifies **unconditionally — owner irrelevant**, so your own
 /// corpse is moused over like anyone else's. Only a **bone pile with nothing to take** is dropped;
@@ -720,8 +711,8 @@ pub(crate) fn corpse_mouseover_eligible(store: &ObjectStore) -> bool {
     !store.0.corpse_is_bones() || store.0.corpse_lootable()
 }
 
-/// What a hovered **corpse object** classifies to — the reference's corpse classifier `0x482740`
-/// (wow-re `cursor-system.md` §3, VERIFIED), as a pure decision so it can be tested the way the
+/// What a hovered **corpse object** classifies to — the reference's corpse classifier `0x482740`,
+/// as a pure decision so it can be tested the way the
 /// service ladder is. `esi` = player, `edi` = corpse, `d2` = centre-to-centre distance².
 ///
 /// Two legs, and there is **no third** — in particular no own-corpse leg. Your own body carries
@@ -788,7 +779,7 @@ pub(super) fn classify_cursor(
         Option<&crate::go_anim::GoAnim>,
     )>,
     self_q: Query<(&Transform, &ObjectStore), With<SelfPlayer>>,
-    // The GameObject cursor is data-driven (decision 0236, wow-re cursor-system §4): the ask-once
+    // The GameObject cursor is data-driven (decision 0236, `0x5f8760`): the ask-once
     // template (its `lockId`) + Lock.dbc + LockType.dbc name the cursor. All absent without client
     // data or before a hovered GO's template answers — a lock-bearing GO then reads as the gear.
     // The same param carries the lock chain `usable` consults (decision 0752) — one
@@ -812,7 +803,7 @@ pub(super) fn classify_cursor(
     // as the reference's zero-initialized global, i.e. not queued.
     stone: Option<Res<crate::ui_dialog_verbs::MeetingStone>>,
 ) {
-    // A **highlightable** GameObject shows its **data-driven** cursor (wow-re cursor-system §4): a
+    // A **highlightable** GameObject shows its **data-driven** cursor (`0x5f8760`): a
     // mailbox's Mail, a plaque's Inspect, a vein's Mine / herb's GatherHerbs / picked lock's PickLock
     // (off its LockType), else the generic Interact gear — each grayed out of interact range (except
     // PickLock, never grayed). A non-highlightable GO yields no cursor, like the reference handler's
@@ -854,10 +845,10 @@ pub(super) fn classify_cursor(
         let dist_sq = go_tf.translation.distance_squared(self_tf.translation);
         // `usable 0x5f3130`, the two arms we model — the LOCK arm first, as the binary orders
         // them (`0x5f32a6` before the range check at `0x5f330c`), then the interim range gray.
-        // The lock arm runs **only when `GO_FLAG_LOCKED` is set** (§8.8): that is why an
+        // The lock arm runs **only when `GO_FLAG_LOCKED` is set**: that is why an
         // ungatherable herb node keeps its lit GatherHerbs cursor and only refuses on the click,
-        // while a padlocked door grays. `PickLock` never grays (§4: `LockType.Id == 1` skips the
-        // usable gate), so the rogue's affordance still reads as available.
+        // while a padlocked door grays. `PickLock` never grays (`0x5f3070`: `LockType.Id == 1`
+        // skips the usable gate), so the rogue's affordance still reads as available.
         let facts = super::lock::go_facts(Some((store, crate::go_anim::go_state(anim, store))));
         let lock_unmet = go_inputs
             .locks
@@ -870,7 +861,7 @@ pub(super) fn classify_cursor(
                     go_inputs.spells.as_deref(),
                     go_inputs.skill_lines.as_ref().map(|s| &s.catalog),
                     Some(self_store),
-                    &go_inputs.items,
+                    &go_inputs.objects,
                     facts,
                     &mut None,
                 )
@@ -903,9 +894,9 @@ pub(super) fn classify_cursor(
                 let shift = keys.pressed(KeyCode::ShiftLeft) || keys.pressed(KeyCode::ShiftRight);
                 return Some((loot_cursor(loot_cfg.auto_loot, shift), !in_melee));
             }
-            // The skin leg's SECOND precondition, byte-verified: the flag alone is not enough —
+            // The skin leg's SECOND precondition: the flag alone is not enough —
             // the reference also requires the learn-time latch `[0xb700e4 + 4×isPlayerTarget]` to
-            // be non-null (wow-re cursor-system.md §3, `0x482589`), i.e. **the player must have
+            // be non-null (`0x482589`), i.e. **the player must have
             // learned a Skinning spell**. A non-skinner gets no knife on a skinnable corpse; the
             // corpse falls through to Point like any other unlootable one (decision 0752).
             if store.0.unit_flags() & UNIT_FLAG_SKINNABLE != 0 && learned.skinning.is_some() {
@@ -1486,7 +1477,7 @@ mod tests {
 
     #[test]
     fn the_bobber_is_channel_gated_and_reaches_a_hundred_yards() {
-        // The FISHINGNODE highlightable override (`0x5f6710`, wow-re fishing-bobber-interaction.md):
+        // The FISHINGNODE highlightable override (`0x5f6710`):
         // only the player whose UNIT_FIELD_CHANNEL_OBJECT names exactly this GO passes — someone
         // else's bobber (or yours after the channel drops) shows nothing at all.
         assert!(highlightable_flags(
@@ -1570,7 +1561,7 @@ mod tests {
         // A quest to offer, so the QUESTGIVER row behaves like the rest of the ladder here; the
         // gate itself is `questgiver_flag_alone_is_not_talkable`.
         let has = Some(dialog_status::AVAILABLE);
-        // The rows the RE table pins per byte address.
+        // The rows the reference pins per byte address.
         assert_eq!(service_cursor(GOSSIP, None), Some(CursorKind::Speak));
         assert_eq!(service_cursor(QUESTGIVER, has), Some(CursorKind::Speak));
         assert_eq!(service_cursor(VENDOR, None), Some(CursorKind::Pickup));
diff --git a/crates/benilla-app/src/target/flash.rs b/crates/benilla-app/src/target/flash.rs
index 2854444e..75a99f86 100644
--- a/crates/benilla-app/src/target/flash.rs
+++ b/crates/benilla-app/src/target/flash.rs
@@ -1,6 +1,5 @@
 //! The melee combat flash — the pulsing **red ↔ orange** tint on the current target's selection
-//! ring and overhead name while the local player is auto-attacking it (wow-re object-layer
-//! `combat-flash.md`, §5-verified 2026-07-06).
+//! ring and overhead name while the local player is auto-attacking it.
 //!
 //! The flag law: `[unit+0xc58]` bit 0x10 is **recomputed every frame** in CGUnit's OnUpdate
 //! (`0x607f60` set / `0x607fe2` clear; whole-binary census — no packet touches it). Set iff the
diff --git a/crates/benilla-app/src/target/highlight.rs b/crates/benilla-app/src/target/highlight.rs
index 231b1d84..f7e8e83b 100644
--- a/crates/benilla-app/src/target/highlight.rs
+++ b/crates/benilla-app/src/target/highlight.rs
@@ -1,16 +1,15 @@
-//! The mouseover / target **model brighten** — the real client's per-model highlight emissive
-//! (wow-re `object-layer/scratch/selection-circle.md` PART 2, §5 cross-checked).
+//! The mouseover / target **model brighten** — the real client's per-model highlight emissive.
 //!
 //! The reference pushes it on hover/target *change*, never a per-frame compare: the mouseover
 //! publisher and the target setter call `SetHighlight 0x614550` / `ClearHighlight 0x6144f0` with a
 //! per-object reason bitmask (bit 0 = target, bit 1 = mouseover — hover + target **stack**, and the
-//! glow drops only when the last reason clears). `SetHighlight` writes the config RGB — shipped
-//! default `0xff404040` ⇒ **+64/255 per channel** — into the model, and the animate kernel adds it
-//! to the material emissive (`glMaterialfv(GL_EMISSION)`): a flat additive lift inside the GL
-//! lighting sum, pre-texture-modulate, riding every lit material of the model *and* its attachments.
+//! glow drops only when the last reason clears). `SetHighlight` samples the scene's committed
+//! ambient (`[0xce9cd8]`, read at `0x614576`-`0x6145bd`) into the model and holds it until the last
+//! reason clears; each batch adds it to its colour before the final clamp (`c29`), lit or unlit,
+//! the model's attachments included. `0xff404040` is only the fallback before a map's light loads.
 //!
 //! benilla carries the flag in **bit 31 of the per-instance `MeshTag`** (the convention home is
-//! `benilla_world::mesh_tag`); `wow_model.wgsl` adds the 64/255 lift to its lighting factor when set. This
+//! `benilla_world::mesh_tag`); `wow_model.wgsl` adds the scene ambient when it is set. This
 //! system is the bit's only writer: each frame (PostUpdate — after every Update payload writer, so
 //! their whole-`u32` overwrites can't strand the bit) it ORs the flag onto every part of the
 //! hovered + selected roots and clears it on roots that left the set. The reason bitmask collapses
diff --git a/crates/benilla-app/src/target/hover.rs b/crates/benilla-app/src/target/hover.rs
index 37f441dc..3bd27050 100644
--- a/crates/benilla-app/src/target/hover.rs
+++ b/crates/benilla-app/src/target/hover.rs
@@ -1,6 +1,6 @@
 //! The mouseover pick — which unit is under the cursor, recomputed each frame into
-//! [`super::Hovered`] the way the real client finds it (wow-re pick-volume RE `bd630be` +
-//! `31562f1d`): a **broad phase** ray-vs-sphere on the current animation's bounds, then a
+//! [`super::Hovered`] the way the real client finds it (`CGWorldFrame` pick `0x481190` →
+//! `0x7089c0`): a **broad phase** ray-vs-sphere on the current animation's bounds, then a
 //! **narrow phase** ray-vs-triangle against the unit's **posed render mesh**, with the
 //! reference's generous +1-model-unit halo retry when nothing hits exactly. The selection /
 //! interaction story that consumes the verdict lives in the [`super`] module doc.
@@ -28,7 +28,7 @@ use benilla_world::view::WorldCamera;
 use super::{Hovered, HoveredObject, PickOcclusion};
 
 /// Trace this frame's **world-occlusion distance** (the reference's `CWorld::Intersect` leg of the
-/// scene trace `0x480df0` — wow-re selection-circle PART 3, §5-cross-checked 2026-07-20): one
+/// scene trace `0x480df0`): one
 /// physics ray from the cursor through the [`PickOccluder`] set (terrain, the WMO walk-bake faces
 /// ≈ the byte-decoded `0x84` reject-mask, static doodad hulls). Both object picks below run
 /// **unbounded** and post-compare against it — the reference discards the object hit iff the world
@@ -76,8 +76,7 @@ pub(super) fn update_pick_occlusion(
 /// object's CM2 **attachment tree** — `[model+0x1dc]` list head → `[+0x1e4]` sibling, the same two
 /// fields the dress and paperdoll lanes walk — and calling the registrar `0x713cb0` on *each* model
 /// it finds, all under one candidate node. So the ray tests the held axe's own triangles and the
-/// hit comes back as the unit holding it (wow-re `object-layer/scratch/selection-circle.md` §3 +
-/// `ui/scratch/paperdoll-liveness-law.md`).
+/// hit comes back as the unit holding it.
 ///
 /// Takes the worn roots as a plain slice rather than the `HeldAttached` that supplies them, so the
 /// rule is testable without building one. `pub(crate)` for the **census**
@@ -109,8 +108,8 @@ pub(super) struct PickPose<'w, 's> {
     rigs: Query<'w, 's, &'static benilla_world::rig_palette::RigSkin>,
 }
 
-/// Recompute the unit under the cursor each frame — the real client's two-phase pick (wow-re
-/// pick-volume RE `bd630be` + `31562f1d`): **broad** = the cursor ray vs the *current animation's*
+/// Recompute the unit under the cursor each frame — the real client's two-phase pick (the
+/// resolve `0x7089c0`): **broad** = the cursor ray vs the *current animation's*
 /// bounds sphere (world-placed + world-scaled, no pad); **pass 1** = the ray vs the unit's **posed
 /// render mesh** (each drawn vertex skinned through the live joint pose, per-triangle), nearest
 /// world-distance hit wins; **pass 2, only when pass 1 hit nothing anywhere** (the mouse pick's
@@ -264,8 +263,7 @@ pub(super) fn update_hover(
         // attachment tree (`[model+0x1dc]` list head → `[+0x1e4]` sibling — the same two fields
         // the dress and paperdoll lanes walk) and registers each child model into the pick scene
         // under the SAME candidate node, so a ray that strikes the axe resolves to the unit
-        // holding it (wow-re `object-layer/scratch/selection-circle.md` §3 +
-        // `ui/scratch/paperdoll-liveness-law.md`; decision 1658). Ours tested the body alone,
+        // holding it (decision 1658). Ours tested the body alone,
         // which is why a Naxxramas weapon mob — an `InvisibleStalker` body that draws nothing,
         // whose entire visible self is the weapon in its hand — could only be targeted through
         // its name plate.
@@ -311,8 +309,7 @@ pub(super) fn update_hover(
                     pose.palettes.world_palette(rig.slot, rig.bones() as usize)
                 })
             };
-        // The halo ladder (alive 3 / dead 2), with the corpse rung now **byte-verified** rather
-        // than guessed (wow-re `corpse-click-and-reclaim.md` Q6, folding back into 1723's open
+        // The halo ladder (alive 3 / dead 2), with the corpse rung no longer guessed (1723's open
         // question): `0x480c90`'s arm at `0x480cec` scores a corpse **2 when
         // `CORPSE_DYNFLAG_LOOTABLE`, else 0** — the same rung as a dead unit when there is
         // something to take, and the floor otherwise. 1723 guessed a flat 1; this replaces it.
@@ -496,7 +493,7 @@ pub(super) fn update_hover(
 /// ungraded state by anything that forgot to order after `TargetUpdate` — a one-frame tooltip pop
 /// for a unit that must never have one. Written once, already graded, that state does not exist.
 ///
-/// wow-re `object-layer/scratch/not-selectable-mouse-refusal.md`; decision 2060.
+/// Decision 2060.
 #[allow(clippy::type_complexity)] // the picker's own root query, borrowed as-is
 fn selectable_pick(
     entity: Entity,
@@ -531,7 +528,7 @@ fn selectable_pick(
 /// handful of GO parts on screen are in the pick set.
 ///
 /// **Two passes, like the unit pick** (decision 1071 — GameObjects are the same type-1 candidates
-/// as units in the reference's resolve `0x7089c0`, wow-re object-layer mouse-pick): **pass 1** =
+/// as units in the reference's resolve `0x7089c0`): **pass 1** =
 /// the exact resident mesh, pure nearest-wins; **pass 2, only when pass 1 hit nothing anywhere**
 /// (the mouse pick's generous retry): the same geometry with every vertex displaced +1 model-unit
 /// along its authored normal — a ~1-yd halo, which is what makes a wispy herb clickable *around*
@@ -590,8 +587,8 @@ const NET_WALK_HOPS: usize = 64;
 /// card swallowed nearly every ray and only the sliver of bowl around it ever answered.
 ///
 /// The reference has no such split to reconcile: the resolve `0x7089c0`'s narrow phase walks the
-/// ONE model's render batches — *"the actual visible RENDER MESH, posed to the current animation"*,
-/// billboard batch included, skinned through the live bone matrices (wow-re `object-layer.md`) — so
+/// ONE model's render batches — the actual visible RENDER MESH, posed to the current animation,
+/// billboard batch included, skinned through the live bone matrices — so
 /// a hit on the shaft **is** a hit on the GameObject, which is what this restores.
 fn net_entity_of(
     e: Entity,
diff --git a/crates/benilla-app/src/target/lock.rs b/crates/benilla-app/src/target/lock.rs
index 403eabda..b9322c50 100644
--- a/crates/benilla-app/src/target/lock.rs
+++ b/crates/benilla-app/src/target/lock.rs
@@ -1,11 +1,11 @@
 //! The GameObject **lock chain** — the client's resolver `0x5f83d0`, its per-slot **Action** gate
-//! (`0x5f81d0`), and the §8.8 refusal-toast routing (decisions 0239 / 0545 / **0752**).
+//! (`0x5f81d0`), and the refusal-toast routing (`0x5f3427..`; decisions 0239 / 0545 / **0752**).
 //!
 //! **One chain, two consumers — exactly as the reference.** `CGGameObject`'s per-type strategy
 //! calls the same resolver twice: from **`usable` `0x5f3130`** (which decides the cursor's grayed
-//! twin *and* whether the right-click is sent at all — §4a/§8.7), and from the **USE sender
+//! twin *and* whether the right-click is sent at all), and from the **USE sender
 //! `0x5f33e0`** (which picks between `CMSG_GAMEOBJ_USE`, an `OPEN_LOCK` cast, and a client-local
-//! toast — §8.4). That is why it lives here rather than inside either caller: the icon and the
+//! toast). That is why it lives here rather than inside either caller: the icon and the
 //! click agree by construction only if they ask the same question.
 //!
 //! ## The Action gate — the piece that was missing (0752)
@@ -24,9 +24,8 @@
 //! `0x5f850f` compares the matched spell's own OPEN_LOCK **effect value**
 //! ([`benilla_formats::SpellDisplay::open_lock_skill`]) against the slot's requirement — which is
 //! `Skill[i]`, or **`GAMEOBJECT_LEVEL × 5`** when `Skill[i]` is zero (`0x5f84be`). The sentence
-//! that used to stand here — "it never reads the skill block" — was `cursor-system.md` §8.8's
-//! absolute, and wow-re REFUTED it at the bytes (`openlock-spell-store-order.md` §4a,
-//! 2026-08-14): the value's level term routes through the CGPlayer vtable (`0x6e384d → 0x6e3130
+//! that used to stand here — "it never reads the skill block" — is wrong at the bytes: the
+//! value's level term routes through the CGPlayer vtable (`0x6e384d → 0x6e3130
 //! → [vtbl+0xa8] = 0x5ea690`) into `PLAYER_SKILL_INFO` for the spell's own SkillLineAbility
 //! line ([`spell_skill_value`]). At skill cap the two readings coincide (`skill/5 == level`),
 //! which is how the old one survived every at-cap cross-check while a level-60 with 1 Mining
@@ -44,7 +43,7 @@ use crate::net::ObjectStore;
 /// item-template cache (key-item names for the "Requires \<key\>" toast, and the key's own ON_USE
 /// spell). The `Option` members are absent without client data.
 #[derive(bevy::ecs::system::SystemParam)]
-pub(crate) struct GoLockInputs<'w> {
+pub(crate) struct GoLockInputs<'w, 's> {
     // Shared: the tooltip arm's ask-once template request on a miss marks itself through
     // `&self` (decision 2288), so neither arm needs the store exclusively.
     pub(crate) templates: Res<'w, crate::go_templates::GameObjectTemplates>,
@@ -55,6 +54,8 @@ pub(crate) struct GoLockInputs<'w> {
     /// ([`spell_skill_value`]). Absent without client data, which reads as skill 0 (fail-closed).
     pub(crate) skill_lines: Option<Res<'w, crate::ui_spellbook::SkillLines>>,
     pub(crate) items: Res<'w, crate::items::Items>,
+    /// The one object index (2334) — the key-item scan walks the player's bags through it.
+    pub(crate) objects: crate::net::Objects<'w, 's>,
 }
 
 /// The GameObject facts the Action gate and the requirement fallback read off the wire — gathered
@@ -116,7 +117,7 @@ pub(crate) fn go_facts(go: Option<(&ObjectStore, u32)>) -> GoFacts {
 }
 
 /// `GO_FLAG_LOCKED` (vmangos `GameObjectFlags`) — the wire bit that both selects the Action-1
-/// ("unlock") slots and arms `usable`'s lock check (§8.8, `0x5f32a6`).
+/// ("unlock") slots and arms `usable`'s lock check (`0x5f32a6`).
 pub(crate) const GO_FLAG_LOCKED: u32 = 0x2;
 
 /// The client's lock resolver **`0x5f83d0`**, transcribed (decision 0752).
@@ -125,8 +126,8 @@ pub(crate) const GO_FLAG_LOCKED: u32 = 0x2;
 /// - **SKILL (2)** — gate on [`LockSlot::available`], then linear-scan the player's known spells
 ///   for one whose `SPELL_EFFECT_OPEN_LOCK` `EffectMiscValue` equals the slot's `Index`; the first
 ///   such match sets `matched_spell` unconditionally (`0x5f84f8`, *before* the rank test — that
-///   nonzero-ness is §8.8's `0xdf`-vs-`0xe0` discriminator), then the spell's effect value is
-///   compared against the requirement (`0x5f850f`). Sufficient → satisfied.
+///   nonzero-ness is the toast routing's `0xdf`-vs-`0xe0` discriminator), then the spell's effect
+///   value is compared against the requirement (`0x5f850f`). Sufficient → satisfied.
 /// - **KEY (1)** — gate the same way, then look for the key item in our bags/keyring.
 /// - **NONE (0)** — skipped without marking the lock real.
 ///
@@ -154,7 +155,7 @@ pub(crate) fn resolve_lock(
     spells: Option<&crate::ui_action::Spells>,
     skill_lines: Option<&benilla_formats::SkillLineCatalog>,
     me: Option<&ObjectStore>,
-    items: &crate::items::Items,
+    objects: &crate::net::Objects,
     go: GoFacts,
     matched_spell: &mut Option<u32>,
 ) -> LockOutcome {
@@ -189,7 +190,7 @@ pub(crate) fn resolve_lock(
                 if !slot.available(go.state, go.flag_locked) {
                     continue;
                 }
-                if me.is_some_and(|s| holds_item(&s.0, items, slot.index)) {
+                if me.is_some_and(|s| holds_item(&s.0, objects, slot.index)) {
                     return LockOutcome::OpenByKey(slot.index);
                 }
             }
@@ -203,8 +204,8 @@ pub(crate) fn resolve_lock(
     }
 }
 
-/// The player's skill value for `spell_id`'s own line — the opener-value level term's source
-/// (wow-re `openlock-spell-store-order.md` §4a): `0x5ea690` hops spell → SkillLineAbility line
+/// The player's skill value for `spell_id`'s own line — the opener-value level term's source:
+/// `0x5ea690` hops spell → SkillLineAbility line
 /// (`0x6de040`, `[+4]`), then `0x5ea520` scans `PLAYER_SKILL_INFO` (`PLAYER_SKILL_INFO_1_1 +
 /// 3·slot`) and returns value **plus both bonus halves** (`0x5ea56d`/`0x5ea578`/`0x5ea580`).
 /// Every absent leg is fail-closed like the reference's null paths: no catalog, no store, no
@@ -306,11 +307,16 @@ pub(crate) fn required_skill(slot: &LockSlot, go_level: u32) -> i32 {
 /// `CMSG_USE_ITEM` (decision 0769).
 fn holds_item(
     store: &benilla_protocol::messages::ObjectFields,
-    items: &crate::items::Items,
+    objects: &crate::net::Objects,
     entry: u32,
 ) -> bool {
-    crate::ui_items::find_item(store, items, entry, crate::ui_items::ItemSearch::default())
-        .is_some()
+    crate::ui_items::find_item(
+        store,
+        objects,
+        entry,
+        crate::ui_items::ItemSearch::default(),
+    )
+    .is_some()
 }
 
 #[cfg(test)]
@@ -417,7 +423,7 @@ mod tests {
         assert_eq!(required_skill(&skill_slot(1, 280, 1), 60), 280);
     }
 
-    /// **The 1320 bug, fixed** (wow-re `openlock-spell-store-order.md` §4a): the opener's level
+    /// **The 1320 bug, fixed**: the opener's level
     /// term is the player's SKILL in the spell's own line, never their character level — so a
     /// level-60 with 1 Mining is refused by a 250-skill vein the old caster-level reading handed
     /// them. Also pins the two fail-closed legs (`0x623b70`-style: absent data reads skill 0)
@@ -445,7 +451,10 @@ mod tests {
         // Spell → line: Mining is SkillLine 186.
         let lines = SkillLineCatalog::from_spell_lines([(2575, 186)]);
         let known = BTreeSet::from([2575]);
-        let items = crate::items::Items::default();
+        // Nothing streamed: no case here holds a key, and the key branch is only reached
+        // with a store, which these pass as `None` (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         // A 250-skill vein, available (Action 0, READY, not flagged).
         let mut vein = [LockSlot::default(); 8];
         vein[0] = skill_slot(3, 250, 0);
@@ -471,7 +480,7 @@ mod tests {
                 Some(&spells),
                 lines,
                 store,
-                &items,
+                &objects,
                 facts,
                 &mut None,
             )
@@ -509,7 +518,10 @@ mod tests {
             skill_slot(10, 0, 0), // Quick Open — Action 0, gated out on a flagged-locked door
             LockSlot::default(),
         ];
-        let items = crate::items::Items::default();
+        // Nothing streamed: no case here holds a key, and the key branch is only reached
+        // with a store, which these pass as `None` (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let mut matched = None;
         let out = resolve_lock(
             &slots,
@@ -517,7 +529,7 @@ mod tests {
             None,
             None,
             None,
-            &items,
+            &objects,
             GoFacts {
                 state: GO_STATE_READY,
                 flag_locked: true,
@@ -588,7 +600,10 @@ mod tests {
             ),
             ..crate::ui_action::Spells::empty_for_tests()
         };
-        let items = crate::items::Items::default();
+        // Nothing streamed: no case here holds a key, and the key branch is only reached
+        // with a store, which these pass as `None` (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let locked_shut = GoFacts {
             state: GO_STATE_READY,
             flag_locked: true,
@@ -604,7 +619,7 @@ mod tests {
                 Some(&spells),
                 None,
                 None,
-                &items,
+                &objects,
                 locked_shut,
                 &mut matched,
             ),
@@ -624,7 +639,7 @@ mod tests {
                 Some(&spells),
                 None,
                 None,
-                &items,
+                &objects,
                 GoFacts {
                     flag_locked: false,
                     ..locked_shut
@@ -636,8 +651,8 @@ mod tests {
 
         // Pick Lock sits on an Action 1 slot, so the flag *selects* it — but with no store and no
         // skill-line catalog the skill reads 0 (the fail-closed leg), Pick Lock provides its flat
-        // 5, and 5 < 280 refuses. The out-param is still written, which is §8.8's
-        // `0xdf`-vs-`0xe0` discriminator. (The satisfied-by-skill path is
+        // 5, and 5 < 280 refuses. The out-param is still written (`0x5f84f8`), which is the toast
+        // routing's `0xdf`-vs-`0xe0` discriminator. (The satisfied-by-skill path is
         // `the_lock_value_tracks_the_players_skill_not_their_level` below.)
         let mut matched = None;
         assert_eq!(
@@ -647,7 +662,7 @@ mod tests {
                 Some(&spells),
                 None,
                 None,
-                &items,
+                &objects,
                 locked_shut,
                 &mut matched,
             ),
@@ -676,7 +691,7 @@ mod tests {
                 Some(&spells),
                 None,
                 None,
-                &items,
+                &objects,
                 locked_shut,
                 &mut None,
             ),
@@ -708,7 +723,7 @@ mod tests {
                 Some(&with_mining),
                 None,
                 None,
-                &items,
+                &objects,
                 GoFacts {
                     state: GO_STATE_READY,
                     flag_locked: false,
@@ -758,7 +773,10 @@ mod tests {
             ),
             ..crate::ui_action::Spells::empty_for_tests()
         };
-        let items = crate::items::Items::default();
+        // Nothing streamed: no case here holds a key, and the key branch is only reached
+        // with a store, which these pass as `None` (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let unlocked = GoFacts {
             state: GO_STATE_READY,
             flag_locked: false,
@@ -773,7 +791,7 @@ mod tests {
                 Some(&spells),
                 None,
                 None,
-                &items,
+                &objects,
                 unlocked,
                 &mut matched,
             ),
@@ -791,7 +809,7 @@ mod tests {
                 Some(&spells),
                 None,
                 None,
-                &items,
+                &objects,
                 unlocked,
                 &mut matched,
             ),
@@ -803,7 +821,10 @@ mod tests {
     #[test]
     fn an_empty_row_is_unlocked() {
         let slots = [LockSlot::default(); 8];
-        let items = crate::items::Items::default();
+        // Nothing streamed: no case here holds a key, and the key branch is only reached
+        // with a store, which these pass as `None` (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let mut matched = None;
         assert_eq!(
             resolve_lock(
@@ -812,7 +833,7 @@ mod tests {
                 None,
                 None,
                 None,
-                &items,
+                &objects,
                 GoFacts {
                     state: GO_STATE_ACTIVE,
                     flag_locked: false,
diff --git a/crates/benilla-app/src/target/mod.rs b/crates/benilla-app/src/target/mod.rs
index d0280f41..bd8e6bcb 100644
--- a/crates/benilla-app/src/target/mod.rs
+++ b/crates/benilla-app/src/target/mod.rs
@@ -9,7 +9,7 @@
 //!   server round-trip). Sending [`ClientCommand::SetSelection`] just informs the server, which records
 //!   it in our `UNIT_FIELD_TARGET` and relays it to observers.
 //! - **Hover** ([`hover::update_hover`]) — each frame, the unit under the cursor, found the way the real
-//!   client finds it (wow-re pick-volume RE `bd630be`, §5-verified: `CGWorldFrame` pick `0x481190` →
+//!   client finds it (`CGWorldFrame` pick `0x481190` →
 //!   `0x7089c0`): a **broad phase** ray-vs-sphere on the *current animation sequence's* bounds
 //!   (world-placed + scaled, no pad), then a **narrow phase** ray-vs-triangle against the unit's
 //!   **posed render mesh** — the drawn vertices skinned through the live joint pose. Clickable =
@@ -29,8 +29,7 @@
 //! dispatch that would have chosen a cursor never runs. It is the **same predicate** the selection
 //! commit runs (`0x60be60`, reached there through the `+0x58` thunk), not a second rule: no
 //! tooltip, no cursor, no brighten, no click. The pick itself reads no unit field — the flagged
-//! unit is a candidate and wins — which is why this is a grader and not a filter (wow-re
-//! `object-layer/scratch/not-selectable-mouse-refusal.md`; decision 2060).
+//! unit is a candidate and wins — which is why this is a grader and not a filter (decision 2060).
 //!
 //! The mouseover/target "light-up" has two consumers: the per-model **emissive lift**
 //! ([`highlight`], the byte-verified additive term) and the V-plate's reaction-tinted **glow**
@@ -213,7 +212,7 @@ pub(crate) struct HoveredObject {
 /// This frame's **world-occlusion distance** for the mouse pick: the distance along the cursor ray
 /// to the nearest [`benilla_world::collision::PickOccluder`] hit (terrain, the WMO walk-bake ≈ `0x84`
 /// reject-mask faces, static doodad hulls), or `f32::INFINITY` with no hit. The reference's scene
-/// trace (`0x480df0`, wow-re selection-circle PART 3, §5-cross-checked) traces objects unbounded
+/// trace (`0x480df0`) traces objects unbounded
 /// and discards the object hit iff the world hit is *strictly* nearer — a unit or GameObject
 /// behind a wall is not hoverable. Written by [`hover::update_pick_occlusion`] at the head of the
 /// target chain; both picks post-compare their final hit against it.
@@ -238,7 +237,7 @@ impl Default for PickOcclusion {
 /// **The pick latched on the button DOWN edge** — what a world click acts on, frozen at the press.
 ///
 /// The reference picks **exactly once per press** and never again for that gesture: `0x481f00` has
-/// one caller image-wide, on the down edge (wow-re `world-click-drag-arbitration.md` §2), and it
+/// one caller image-wide, on the down edge, and it
 /// writes the whole result into the WorldFrame — pick state `+0x350`, guid `+0x358`, hit point
 /// `+0x360`, distance `+0x36c`. Nothing re-picks on move or on release, so the release acts on what
 /// the **press** was over. That single fact is what lets one gesture orbit the camera *and* select:
@@ -338,8 +337,8 @@ pub(crate) fn go_is_nearest(character: &Hovered, go: &HoveredObject) -> bool {
 
 /// A unit's model-local selection radius — the **Stand-animation footprint** `sqrt(0.5 · sqrt(dx² + dy²))`
 /// (dx/dy = the Stand sequence box's horizontal extents), the exact model-local input the real client's
-/// living-unit ring uses, scaled by `OBJECT_FIELD_SCALE_X` (wow-re selection-ring RE, `0x608e00`/`0x60aee0`,
-/// byte-verified + emulated to the reference pixels). Stamped at attach ([`crate::entities`]); the ring's
+/// living-unit ring uses, scaled by `OBJECT_FIELD_SCALE_X` (`0x608e00`/`0x60aee0`, emulated to the
+/// reference pixels). Stamped at attach ([`crate::entities`]); the ring's
 /// world radius is this × the unit's transform scale (which is SCALE_X). Absent on model-less (cube) units,
 /// which fall back to the ring's fallback radius.
 #[derive(Component, Clone, Copy)]
@@ -383,9 +382,9 @@ impl Default for ClickConfig {
 /// the two shared assist tails. `CanAssist 0x6066f0` is *not* on this path (verified negative over
 /// all 25 of its call sites).
 ///
-/// **Registered default `"0"`, so nothing changes until a player asks for it.** That number cost
-/// wow-re a correction it records against itself: its first pass read `"3"` off the *next*
-/// registration's default (`minimapZoom`), the `mov ds:` adjacency trap.
+/// **Registered default `"0"`, so nothing changes until a player asks for it** (`0x48fc50`).
+/// Reading `"3"` for it is the `mov ds:` adjacency trap: that is the *next* registration's
+/// default (`minimapZoom`).
 #[derive(Resource, Default)]
 pub(crate) struct AssistAttack(pub(crate) bool);
 
@@ -450,11 +449,11 @@ impl Plugin for TargetPlugin {
                     // The right button's down-edge cancel first (the ref's OnMouseDown hook,
                     // 0792): the frame the press lands, the cursor drive below already reads
                     // the mode cleared and the classifier's verdict stands.
-                    crate::ui_action::targeting::cancel_targeting_on_right_press,
+                    crate::spell::targeting::cancel_targeting_on_right_press,
                     // The ground-targeting pre-empt (decision 0792): overwrites the classifier's
                     // verdict while the targeting cursor is up — the ref's dispatcher runs this
                     // branch before the object classifier; last-writer-wins reads the same.
-                    crate::ui_action::targeting::drive_targeting_cursor,
+                    crate::spell::targeting::drive_targeting_cursor,
                     // The AoE reticle reads that verdict (`WorldCursor.unable` IS the frame's
                     // range state — the ref's one CheckGroundPointInRange caller feeds both).
                     reticle::update_reticle,
@@ -467,8 +466,8 @@ impl Plugin for TargetPlugin {
                     // world legs are siblings, not a fallback chain — the pending spell's word
                     // decides which of them a click can even feed (decision 0939), so their order
                     // relative to each other never matters.
-                    crate::ui_action::targeting::commit_ground_cast_on_click,
-                    crate::ui_action::targeting::commit_object_cast_on_click,
+                    crate::spell::targeting::commit_ground_cast_on_click,
+                    crate::spell::targeting::commit_object_cast_on_click,
                     click::act_on_right_click,
                     click::clear_target_requests,
                     // The two unit-token drains, grouped as one element (the outer chain is at
diff --git a/crates/benilla-app/src/target/relations.rs b/crates/benilla-app/src/target/relations.rs
index 22be0110..7757e1e3 100644
--- a/crates/benilla-app/src/target/relations.rs
+++ b/crates/benilla-app/src/target/relations.rs
@@ -42,8 +42,7 @@ fn is_player_object(store: Option<&ObjectStore>) -> bool {
 /// (`0x48269a`), the combat flash's gate, the TAB scan's filter 3, `UnitCanAttack`, and hostile
 /// spell targeting all ask this one question.
 ///
-/// **This forwards to the byte-verified complete function** ([`super::ring::can_attack_from_player`],
-/// wow-re `object-layer/scratch/nameplate-category-gate.md` §3, §5 cross-checked 2026-08-22) — a
+/// **This forwards to the complete function** ([`super::ring::can_attack_from_player`]) — a
 /// ghost gate, five `UNIT_FIELD_FLAGS` refusal bits on the target, four cross-flag immunity legs,
 /// then three terminal arms selected by `UNIT_FLAG_PVP_ATTACKABLE` on both parties.
 ///
@@ -111,10 +110,8 @@ const UNIT_FLAG_NOT_SELECTABLE: u32 = 1 << 25;
 /// a store whose `OBJECT_FIELD_TYPE` has not streamed is read the same permissive way rather than
 /// refusing a selection over an absent field.
 ///
-/// Byte-verified in wow-re: `ui/scratch/unitisvisible-object-presence.md` §5 (the function body and
-/// the three corroborating consumers of the same bit) and
-/// `object-layer/scratch/selection-attack-seam.md` §3.1 (the `SetSelection 0x493540` early-out at
-/// `0x4935ee`/`0x4935f3`, §5 trio + orchestrator byte-arbitration).
+/// `SetSelection 0x493540` makes this call at `0x4935ee` and returns on a false answer at
+/// `0x4935f3`; three further consumers test the same bit (`0x6066f0`, `0x606829`, `0x60f600`).
 pub(crate) fn is_selectable(store: Option<&ObjectStore>, self_guid: Option<u64>) -> bool {
     let Some(store) = store else {
         return true; // no resolved object — the reference never makes the call (`0x4935c8`)
@@ -138,8 +135,7 @@ const UNIT_FLAG_PVP: u32 = 0x1000;
 const UNIT_FLAG_PLAYER_CONTROLLED: u32 = 0x8;
 
 /// `CanAssist 0x6066f0` — "may I help this unit?", the predicate `UnitBuff`'s unit-level gate runs
-/// (see [`crate::ui_aura::buffs_visible_on`]). Byte-derived in wow-re's
-/// `ui/scratch/aura-display-pipeline.md` §9b; named by its own Lua registrar pair
+/// (see [`crate::ui_aura::buffs_visible_on`]). Named by its own Lua registrar pair
 /// (`.data 0x8504c8 = {"UnitCanAssist", 0x516bb0}`), not by resemblance.
 ///
 /// Three clauses: `UNIT_FLAG_NOT_SELECTABLE` clear, `UnitReaction ≥ 4`, and — for a unit that is
@@ -149,7 +145,7 @@ const UNIT_FLAG_PLAYER_CONTROLLED: u32 = 0x8;
 /// rank, so the comparison is against 4 directly — **neutral fails**.
 ///
 /// The player-controlled arm (`0x60673e`–`0x60679f`) keys on an `[obj+0xe68]` record whose fields
-/// wow-re did **not** name, so it is deliberately NOT modelled: a player-controlled unit takes the
+/// are **not** named, so it is deliberately NOT modelled: a player-controlled unit takes the
 /// permissive answer here. That is conservative in the only direction that matters (it shows what
 /// we already showed) and it keeps the un-derived arm out of the one place it could silently blank
 /// a player's or a pet's buffs.
diff --git a/crates/benilla-app/src/target/reticle.rs b/crates/benilla-app/src/target/reticle.rs
index 7a834077..e595c509 100644
--- a/crates/benilla-app/src/target/reticle.rs
+++ b/crates/benilla-app/src/target/reticle.rs
@@ -1,8 +1,7 @@
 //! The **ground-targeting AoE reticle** — the terrain-projected decal a **location** cast's
-//! cursor drags across the world (decisions 0797 / 0943; byte-pinned in wow-re
-//! `ground-target-reticle.md`). Only a word that passes `TargetingWantsLocation`'s `& 0x60` has
-//! one: the other two seams (a bag click, a world GameObject click) arm the same cursor and draw
-//! no decal at all — see [`update_reticle`]'s guard.
+//! cursor drags across the world (decisions 0797 / 0943). Only a word that passes
+//! `TargetingWantsLocation`'s `& 0x60` has one: the other two seams (a bag click, a world
+//! GameObject click) arm the same cursor and draw no decal at all — see [`update_reticle`]'s guard.
 //!
 //! For every ordinary area spell (Blizzard, Flamestrike — no object-placement effect), the
 //! reference draws a **projected decal**, not a model: box = the picked ground point ± r in the
@@ -19,24 +18,25 @@
 //! (slot 2 is never read), max with candidate-1 winning ties/NaN. **Out of range forces the
 //! radius to 0.0** — the decal shrinks to the 1.3888889 default *and* turns red. `r == 0` (no
 //! radius rows — a dest spell with no area) also draws at the default. Spell-mod op 6
-//! (SPELLMOD_RADIUS) is not folded in: the tables are live ([`crate::spell_mods`]), this consumer
+//! (SPELLMOD_RADIUS) is not folded in: the tables are live (`crate::spell::mods`), this consumer
 //! is not wired to them (the same residual as the range gate, 0792).
 //!
 //! **States**: in range → Acceptable at `r`; out of range → Unacceptable at the default size;
 //! cursor over sky / no world hit → **nothing is drawn** (the ref resets its draw state every
 //! hover pass before the pick — the "frozen at the last point" reading was refuted at the
 //! bytes). Over a unit the decal draws on the ground behind it (the pick can't see units while
-//! a dest-only word is up — `world-click-targeting.md` Q2).
+//! a dest-only word is up — its flags skip the object trace at `0x480e7b`).
 //!
-//! Named gap (shared with the blob shadow): the ref's second projection pass takes **liquid**
-//! surfaces (flags `0x0f0000`) — our [`GroundDecalSurface`] set has no liquid yet, so the
-//! reticle vanishes over water instead of floating on it (wow-re trap #8, half-carried).
+//! Named gap (shared with the blob shadow): the ref's second projection pass (`0x483727`) takes
+//! **liquid** surfaces (flags `0x0f0000`) — our [`GroundDecalSurface`] set has no liquid yet, so
+//! the reticle vanishes over water instead of floating on it.
 
 use bevy::prelude::*;
 
 use crate::net::{ObjectStore, SelfPlayer};
+use crate::spell::{ground_cast_radius, SpellTargeting, TargetingWants};
 use crate::target::{PickOcclusion, WorldCursor};
-use crate::ui_action::{ground_cast_radius, SpellTargeting, Spells, TargetingWants};
+use crate::ui_action::Spells;
 use benilla_world::decal::{DecalFrame, WorldDecal};
 use benilla_world::particles::buffer::EffectVertex;
 use benilla_world::view::WorldCamera;
@@ -211,7 +211,7 @@ pub(super) fn push_reticle(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::ui_action::CastCommit;
+    use crate::spell::CastCommit;
     use avian3d::prelude::Collider;
     use benilla_world::collision::GroundDecalSurface;
     use bevy::ecs::system::RunSystemOnce;
diff --git a/crates/benilla-app/src/target/ring.rs b/crates/benilla-app/src/target/ring.rs
index 595a0458..875ac64d 100644
--- a/crates/benilla-app/src/target/ring.rs
+++ b/crates/benilla-app/src/target/ring.rs
@@ -1,7 +1,7 @@
 //! The ground selection ring — a projected decal under the current target, reaction-coloured.
 //!
-//! **Geometry: the reference's own mechanism** ([`project_ring`], wow-re selection-circle RE — the
-//! collector is byte-verified terrain + WMO, flags `0x200122`, no walkability test): the actual
+//! **Geometry: the reference's own mechanism** ([`project_ring`] — the collector `0x6723b0` is
+//! terrain + WMO, flags `0x200122`, no walkability test): the actual
 //! surface triangles inside the ring's box — terrain tiles + WMO faces
 //! ([`GroundDecalSurface`]), **never** doodads/GameObjects — clipped to the box and textured
 //! top-down, so the ring is pixel-coplanar with the visible ground, drapes down steps/ledges like
@@ -23,13 +23,13 @@
 //! standing with them), else the faction-template comparator
 //! ([`benilla_formats::FactionTemplate::reaction_toward`], the byte-exact `0x606640`), evaluated as
 //! the **unit's** reaction toward the local player (byte-verified direction). Death **clears the
-//! target** on the alive→dead transition — the reference's own mechanism, byte-verified (wow-re
-//! selection-death-clear RE): the health mirror's death edge fires the CGUnit death handler
+//! target** on the alive→dead transition — the reference's own mechanism: the health mirror's
+//! death edge fires the CGUnit death handler
 //! (`0x605860`), which clears a matching selection and sends `CMSG_SET_SELECTION 0`.
 //!
 //! Still *interim*: the vertical fade profile on stretched (wall/ledge) pieces is capture-matched —
-//! the reference's edge-fade grid (`0x6147f0`) is byte-located but its ramp is underived (open RE
-//! item). The ring appears at full brightness the instant of selection — director-verified and
+//! the reference's edge-fade grid (`0x6147f0`) is byte-located but its ramp is underived (an open
+//! question). The ring appears at full brightness the instant of selection — director-verified and
 //! byte-confirmed (the retracted "2 s selection fade-in" note was a misread of the *scale-change*
 //! easing, see [`crate::net::NetEntity`]; no fade arms on any selection path). The selector's
 //! **first-priority branch** — the melee combat flash (`[unit+0xc58]` bit 0x10, the red↔orange
@@ -42,7 +42,7 @@ use benilla_formats::{load_faction_catalog, reputation_rank, FactionCatalog, Rea
 use benilla_protocol::EntityKind;
 use bevy::prelude::*;
 
-use crate::net::{NetEntity, ObjectStore, Reputations, SelfPlayer};
+use crate::net::{Guid, NetEntity, ObjectStore, Reputations, SelfPlayer};
 use benilla_assets::{LockRecover, WorldAssets};
 use benilla_world::decal::{DecalFrame, WorldDecal};
 use benilla_world::particles::buffer::EffectVertex;
@@ -80,15 +80,15 @@ pub(super) struct RingAssets {
     texture: Handle<Image>,
 }
 
-/// The reference's ground selection-circle texture (`Textures\UnitSelectTexture.blp`, wow-re
-/// selection-circle RE) — a white ring, sampled top-down, tinted + additively blended below.
+/// The reference's ground selection-circle texture (`Textures\UnitSelectTexture.blp`, loaded at
+/// `0x6146d0`) — a white ring, sampled top-down, tinted + additively blended below.
 const RING_TEXTURE: &str = "mpq://textures/unitselecttexture.blp";
 /// Model-local ring radius for a unit with **no model at all** (a cube fallback), since it has no M2
 /// footprint to measure. The reference's own degenerate-box constant (decision 1658) rather than a
 /// number of ours: a body whose box measures zero and a body with no box are the same question, and
 /// `0x60aee0` answers it with 1.2.
 const RING_FALLBACK_RADIUS: f32 = benilla_formats::DEGENERATE_RING_FOOTPRINT;
-/// The ring's own palette — **trace + byte verified end-to-end** (wow-re selection-circle §5, the
+/// The ring's own palette (the
 /// `CGUnit::GetSelectionCircleColor` selector `0x605960`, per-object vtable `+0x2c`; the dword is
 /// written verbatim as every decal vertex's diffuse, alpha 255 — no tint global, no tex-env
 /// constant). The ring does **not** use the nameplate palette: player-blue is the pale
@@ -256,8 +256,9 @@ pub(super) fn load_factions(mut commands: Commands, world_assets: Option<Res<Wor
 /// (`OBJECT_FIELD_SCALE_X`). Colour = the target's
 /// reaction rank ([`ring_reaction`]), re-resolved each frame (faction can change live — the store
 /// merges `Values` deltas), the handle swapped only on change. No pulse — the reference's unit ring
-/// is steady. If the target's entity is gone (destroyed / streamed out) the selection clears and the
-/// server is told — the reference's teardown clear sends `CMSG_SET_SELECTION 0` on both paths.
+/// is steady. If the target is no longer an object (destroyed / streamed out — torn down, even while
+/// its model fades) the selection clears and the server is told — the reference's teardown clear
+/// sends `CMSG_SET_SELECTION 0` on both paths.
 #[allow(clippy::type_complexity)]
 pub(super) fn update_ring(
     mut selection: ResMut<Selection>,
@@ -282,19 +283,27 @@ pub(super) fn update_ring(
     // (net motion ran in `WorldStage::Net`), avoiding the 1-frame lag a `GlobalTransform` read
     // would add. Tupled into one param (the 16-param ceiling): `.0` the target's own components;
     // `.1` the mounted footprint source — while a mount model is attached, the ring reads the
-    // MOUNT's Stand-box footprint at the mount's rendered scale (VERIFIED wow-re
-    // `mount-composition.md`: the `+0xcf0` ring cache recomputes from the mount model's Stand
-    // box, `0x60ce70` tail → `0x60aee0`; the scale law is B3 —
+    // MOUNT's Stand-box footprint at the mount's rendered scale (the `+0xcf0` ring cache
+    // recomputes from the mount model's Stand
+    // box, `0x60ce70` tail → `0x60aee0`; the rendered scale is
     // `SCALE_X × CreatureDisplayInfo.creatureModelScale`, and the child's `NetEntity.scale`
     // carries exactly the CDI column).
+    //
+    // `.0` is filtered on [`Guid`] — **a live object**, not merely a drawn model: a torn-down
+    // unit keeps its model (and its `Transform`) for the two-second fadeout, but sheds its guid
+    // at the teardown ([`crate::net::tear_down`]), so it lands in the gone-object branch below on
+    // the teardown's own frame rather than when the fade despawns it.
     targets: (
-        Query<(
-            &Transform,
-            Option<&SelectionRadius>,
-            Option<&ObjectStore>,
-            Option<&NetEntity>,
-            Option<&crate::entities::mount::MountChild>,
-        )>,
+        Query<
+            (
+                &Transform,
+                Option<&SelectionRadius>,
+                Option<&ObjectStore>,
+                Option<&NetEntity>,
+                Option<&crate::entities::mount::MountChild>,
+            ),
+            With<Guid>,
+        >,
         Query<(&NetEntity, Option<&SelectionRadius>), With<crate::entities::mount::MountBody>>,
         // The party roster — the selector's 4-slot guid table (the party ring colours).
         Res<crate::ui_party::GroupState>,
@@ -366,7 +375,7 @@ pub(super) fn update_ring(
                 // already-dead corpse reads dead on stream-in.
                 let is_dead = store.is_some_and(|s| s.0.unit_is_dead());
                 // Death clears the target on the alive→dead *transition* — the reference's own
-                // mechanism, byte-verified (wow-re selection-death-clear RE): the health mirror-
+                // mechanism: the health mirror-
                 // handler's death edge (`0x6046f0`, new ≤ 0 while old > 0) fires the CGUnit death
                 // handler `0x605860`, which clears a matching selection via SetSelection(0) and
                 // sends `CMSG_SET_SELECTION 0` — exactly what `clear` does. Edge-only, like the
@@ -414,10 +423,11 @@ pub(super) fn update_ring(
                 // own no-ground gate (`0x6d74b5`: the whole draw is skipped).
                 !projected
             }
-            // The target entity no longer exists (destroyed or streamed out): clear, informing the
-            // server — the reference's teardown does exactly this for both removal paths (object
-            // deactivate → the selection clear + `CMSG_SET_SELECTION 0`, byte-verified — wow-re
-            // selection-death-clear RE; this is also what drops a selected corpse at respawn, when
+            // The target is no longer an object (destroyed or streamed out — torn down, its model
+            // perhaps still fading; or despawned outright): clear, informing the server — the
+            // reference's teardown does exactly this for both removal paths (object deactivate →
+            // the selection clear + `CMSG_SET_SELECTION 0`, `0x5fbb60` → `0x493910`; this is also
+            // what drops a selected corpse at respawn, when
             // the server destroys it ahead of the fresh create).
             Err(_) => {
                 clear(&mut selection, &mut seam, !engaged.is_empty());
@@ -452,20 +462,20 @@ fn ring_fade_angle(camera: &Query<&GlobalTransform, With<WorldCamera>>) -> Optio
     Some(-std::f32::consts::FRAC_PI_2 - flat.z.atan2(flat.x))
 }
 
-/// Rebuild the ring mesh as a **projected decal** — the reference's actual mechanism (wow-re
-/// selection-circle RE §2: clip world geometry to the projection box, texture it top-down), via
+/// Rebuild the ring mesh as a **projected decal** — the reference's actual mechanism (clip world
+/// geometry to the projection box, texture it top-down), via
 /// the shared projector ([`benilla_world::decal::WorldDecal::project`] — the blob shadow rides the same emit
 /// chain, `0x6d7330 → 0x6d6fa0 → 0x6d7480`). The ring's box: the *rotated* texture square
 /// (half-extent `s` = radius, yawed by the camera fade angle — the clip frame is exactly the
-/// texture frame, so UVs stay in `[0,1]`) × the byte-verified vertical half-range **2s** (the
-/// unit ring's box corners are `center±s` horizontal, `center±2s` vertical — wow-re `0x608e00`).
+/// texture frame, so UVs stay in `[0,1]`) × the vertical half-range **2s** (the
+/// unit ring's box corners are `center±s` horizontal, `center±2s` vertical — `0x608e00`).
 /// Vertex alpha is the vertical trapezoid fade: full within ±0.5s of the feet, ramping to 0 at
 /// the box's ±2s — so a smear up a wall / down a ledge dims with height the way the director's
 /// reference capture shows, instead of ending in a hard clip line. *Interim profile*: the
 /// reference's edge-fade alpha grid is byte-located (`0x6147f0`) but its exact ramp is unrecorded
-/// (open RE item). Runs every shown frame (target moves, camera yaws); the per-surface BVH makes
-/// the gather O(log n + k). Returns `false` when nothing was gathered (no ground in the box) —
-/// the caller hides the ring, the reference's no-ground gate.
+/// (an open question). Runs every shown frame (target moves, camera yaws); the per-surface BVH
+/// makes the gather O(log n + k). Returns `false` when nothing was gathered (no ground in the box)
+/// — the caller hides the ring, the reference's no-ground gate.
 fn project_ring(
     out: &mut Vec<EffectVertex>,
     decals: &WorldDecal<'_, '_>,
@@ -643,9 +653,8 @@ fn ffa_reaction(
 }
 
 /// `UNIT_FIELD_FLAGS` bits `CanAttack` (`0x606980`) tests on its TARGET, any one of which refuses
-/// the attack outright — byte-verified at `0x6069b7`–`0x6069ff` (wow-re
-/// `object-layer/scratch/nameplate-category-gate.md` §3b). **The bit NUMBERS are VERIFIED; the
-/// vanilla names are not** (three wow-re workers hunted for a labelled consumer of bit 9 and found
+/// the attack outright — at `0x6069b7`–`0x6069ff`. **The bit NUMBERS are the binary's; the
+/// vanilla names are inferred, not confirmed** (a hunt for a labelled consumer of bit 9 found
 /// none), so nothing here is written in terms of a name — 1 `0x2`, 7 `0x80`, 16 `0x10000`,
 /// 20 `0x100000`, 25 `0x2000000`.
 const CANNOT_BE_ATTACKED: u32 = 0x2 | 0x80 | 0x1_0000 | 0x10_0000 | 0x200_0000;
@@ -657,8 +666,7 @@ const IMMUNE_TO_UNCONTROLLED: u32 = 0x200;
 /// on its target (`0x606b5c`).
 const UNIT_FLAG_PVP: u32 = 0x1000;
 
-/// The **local player's** reaction toward a unit — `0x6061e0(this = localPlayer, arg = unit)`,
-/// byte-verified (wow-re `nameplate-category-gate.md` §5 leg 3 + §8a, §5 cross-checked 2026-08-22).
+/// The **local player's** reaction toward a unit — `0x6061e0(this = localPlayer, arg = unit)`.
 ///
 /// **This is NOT [`ring_reaction`] with the arguments swapped, and that is the whole point.** The
 /// two directions take genuinely different code inside `0x6061e0`, and the client uses both:
@@ -736,9 +744,9 @@ pub(crate) fn at_war_with(
     )
 }
 
-/// `CGUnit::CanInteract(this = the local player → arg = unit)` — `0x6067f0`, byte-verified
-/// complete (disassembly read at `0x6067f0`–`0x606871`; wow-re `ui/scratch/cursor-system.md` §3 +
-/// `cursor-decomp`, and the register set-up confirmed at every call: `0x4822f2 push esi(unit); mov
+/// `CGUnit::CanInteract(this = the local player → arg = unit)` — `0x6067f0`, complete
+/// (disassembly read at `0x6067f0`–`0x606871`, and the register set-up confirmed at every
+/// call: `0x4822f2 push esi(unit); mov
 /// ecx,edi(player); call 0x606880`, then `0x60691d push esi(unit); mov ecx,edi(player); call
 /// 0x6067f0`).
 ///
@@ -783,13 +791,12 @@ pub(crate) fn can_interact_from_player(
         && reaction_from_player(factions, reputations, target_store, self_store) >= NEUTRAL
 }
 
-/// `CGUnit::CanAttack(this = the local player → arg = unit)` — `0x606980`, byte-verified complete
-/// (wow-re `nameplate-category-gate.md` §3, §5 cross-checked 2026-08-22). Every leg, in the
-/// binary's order.
+/// `CGUnit::CanAttack(this = the local player → arg = unit)` — `0x606980`, complete. Every leg, in
+/// the binary's order.
 ///
 /// This is the predicate the V-plate category actually turns on (see [`plate_is_friendly`]), and
-/// it is deliberately **not** a reaction threshold: §3b lists six shipped ways it disagrees with
-/// one, including an unflagged opposite-faction player on a PvE realm (hostile reaction, cannot be
+/// it is deliberately **not** a reaction threshold: it disagrees with one in six shipped ways,
+/// including an unflagged opposite-faction player on a PvE realm (hostile reaction, cannot be
 /// attacked → friendly plate) and a same-faction duel opponent (friendly reaction, can be attacked
 /// → enemy plate).
 pub(crate) fn can_attack_from_player(
@@ -870,11 +877,10 @@ pub(crate) fn faction_group_mask(
     )
 }
 
-/// `CanCooperate(this = the local player → arg = unit)` — `0x606ba0`, byte-verified (wow-re
-/// `nameplate-category-gate.md` §2a): the two `FactionTemplate` rows' **faction-group masks**
+/// `CanCooperate(this = the local player → arg = unit)` — `0x606ba0`: the two `FactionTemplate`
+/// rows' **faction-group masks**
 /// (`row + 0xc`) being equal, with neither side mind-controlled and the two not being the same
-/// unit. It reads no party or raid state — a committed wow-re note called it a party/raid predicate
-/// and was corrected by the same round.
+/// unit. It reads no party or raid state.
 pub(crate) fn can_cooperate_with_player(
     factions: Option<&Factions>,
     target_store: Option<&ObjectStore>,
@@ -904,8 +910,8 @@ pub(crate) fn can_cooperate_with_player(
     resolved.unwrap_or(false)
 }
 
-/// **The V-plate category** — `0x60f6b7`–`0x60f6f1`, byte-verified (wow-re
-/// `nameplate-category-gate.md` §2). `true` = the FRIENDLY bucket (Shift-V's bit `0x8`), `false` =
+/// **The V-plate category** — `0x60f6b7`–`0x60f6f1`. `true` = the FRIENDLY bucket (Shift-V's bit
+/// `0x8`), `false` =
 /// the ENEMY bucket (V's bit `0x1`). There is no reaction rank anywhere in this expression.
 ///
 /// > A unit lands in the FRIENDLY category iff — for a non-player subject —
@@ -1103,7 +1109,7 @@ mod tests {
              directions, and this disagreement is the reference's own"
         );
 
-        // **The discriminating population** (wow-re §7: 36 shipped templates where the at-war leg
+        // **The discriminating population** (36 shipped templates where the at-war leg
         // and the mask comparison disagree). Booty Bay's mask answer is 3 — so if this read as
         // enemy-category we would be back on the comparator, and the at-war leg would be fiction.
         let goblin = unit(120);
@@ -1128,8 +1134,8 @@ mod tests {
     /// **Cenarion Circle** NPC with no gossip drew the ATTACK sword at neutral standing, with the
     /// faction not set to war.
     ///
-    /// Cenarion Circle is faction 609, reputation slot 36 — one of the 36 templates wow-re's §7
-    /// measured as decided entirely by the at-war bit, and one 1530 named while correcting the
+    /// Cenarion Circle is faction 609, reputation slot 36 — one of the 36 shipped templates
+    /// decided entirely by the at-war bit, and one 1530 named while correcting the
     /// plate category alone. The cursor and `relations::can_attack` kept the reaction *threshold*,
     /// which reads the OTHER direction (the standing, 0 → neutral → "≤ 3 is attackable"), so the
     /// sword came back for every one of those factions.
@@ -1223,9 +1229,9 @@ mod tests {
     /// **The PLAYER subject** — the arm 1530 landed and left unpinned, on the real DBC.
     ///
     /// A player is friendly-category only if `CanCooperate` ALSO says yes, and that predicate is
-    /// pure `FactionTemplate` faction-group-mask equality (§2a). So the arm turns entirely on one
-    /// number — `group_mask` 3 for every Alliance race template, 5 for every Horde one — and the
-    /// interesting population is the templates that carry NEITHER.
+    /// pure `FactionTemplate` faction-group-mask equality (`0x606ba0`). So the arm turns entirely
+    /// on one number — `group_mask` 3 for every Alliance race template, 5 for every Horde one — and
+    /// the interesting population is the templates that carry NEITHER.
     ///
     /// **`35` is that template, and it is what a vmangos test realm hands you**: `.gm on` calls
     /// `Player::SetGameMaster(true)` → `SetFactionTemplateId(35)` (vmangos `Player.cpp:2656`), whose
@@ -1293,7 +1299,7 @@ mod tests {
         assert!(npc_category(&npc(12), &gm), "the guard keeps his bucket");
         assert!(!npc_category(&npc(14), &gm), "and the mob keeps his");
 
-        // The predicate's first leg (§2a `606ba6`): nobody cooperates with themselves.
+        // The predicate's first leg (`606ba6`): nobody cooperates with themselves.
         assert!(!can_cooperate_with_player(
             Some(&factions),
             Some(&me),
@@ -1302,7 +1308,8 @@ mod tests {
     }
 
     /// `CanAttack`'s flag disqualifiers put a unit in the FRIENDLY bucket **at any reaction** — the
-    /// class of case a rank threshold gets wrong in the other direction (wow-re §3b). Asserted on
+    /// class of case a rank threshold gets wrong in the other direction (`0x6069b7`–`0x6069ff`).
+    /// Asserted on
     /// the mask path (a Monster-faction template, hostile by reaction) so the reaction is
     /// unambiguously hostile and only the flag can be doing the work.
     #[test]
@@ -1345,4 +1352,186 @@ mod tests {
             false
         ));
     }
+
+    /// **A torn-down object stops being an object at the teardown, not when its model is done
+    /// fading.** The reference's two teardown routes (`SMSG_DESTROY_OBJECT`, the OUT_OF_RANGE
+    /// block) both reach `0x464920` → OnDeactivate `0x5fbb60` → `0x493910`, which clears a
+    /// matching selection and sends `CMSG_SET_SELECTION 0` on the spot; only the detached model
+    /// survives into the `SWModelFadeout` scheduler (decision 2198). Driven through the real
+    /// handler table on the built client, then the real
+    /// ring and the real nearest-enemy scan, one pass each — no fade time elapses.
+    mod teardown {
+        use benilla_protocol::field::{
+            FIELD_UNIT_FLAGS, FIELD_UNIT_HEALTH, FIELD_UNIT_LEVEL, FIELD_UNIT_MAXHEALTH,
+        };
+        use benilla_protocol::messages::ObjectType;
+        use benilla_protocol::{EntityKind, ObjectFields, SessionEvent};
+        use bevy::ecs::system::RunSystemOnce;
+        use bevy::prelude::*;
+        use crossbeam_channel::Receiver;
+
+        use crate::net::{ClientCommand, Guid, GuidIndex, NetCommands, ObjectStore, SelfPlayer};
+        use crate::target::{attack_order_target, Selection, TargetScan};
+        use benilla_world::model_fade::DespawnFade;
+
+        const ME: u64 = 0x0000_0000_0000_0007;
+        const MOB: u64 = 0xF130_0000_1234_0001;
+
+        fn create(guid: u64) -> SessionEvent {
+            SessionEvent::ObjectCreate {
+                guid,
+                kind: EntityKind::Unit,
+                display_id: None,
+                position: [3.0, 0.0, 0.0],
+                orientation: 0.0,
+                scale: 1.0,
+                speeds: None,
+                mover: None,
+                transport_progress: None,
+                transport: None,
+                spline: None,
+                fields: ObjectFields::from_pairs(&[
+                    (FIELD_UNIT_HEALTH, 100),
+                    (FIELD_UNIT_MAXHEALTH, 100),
+                    (FIELD_UNIT_LEVEL, 9),
+                ])
+                .into_created(ObjectType::Unit),
+            }
+        }
+
+        /// The built client with our own avatar and one live mob in the index, the mob
+        /// selected, and the write channel captured.
+        fn client_with_selected_mob() -> (App, Entity, Receiver<ClientCommand>) {
+            let mut app = crate::game_plugins::schedule_tests::headless_client();
+            let (tx, rx) = crossbeam_channel::unbounded();
+            app.insert_resource(NetCommands(tx));
+            let world = app.world_mut();
+            // Inserted by a Startup system on a real boot; no schedule runs here.
+            world.init_resource::<super::super::RingState>();
+            let me = world
+                .spawn((
+                    SelfPlayer,
+                    Guid(ME),
+                    Transform::default(),
+                    ObjectStore(
+                        // Player-controlled (`UNIT_FLAG_PVP_ATTACKABLE`), so a neutral mob is
+                        // attackable with no faction catalog loaded — the scan's control half.
+                        ObjectFields::from_pairs(&[
+                            (FIELD_UNIT_HEALTH, 100),
+                            (FIELD_UNIT_MAXHEALTH, 100),
+                            (FIELD_UNIT_FLAGS, 0x8),
+                        ])
+                        .into_created(ObjectType::Player),
+                    ),
+                ))
+                .id();
+            world.resource_mut::<GuidIndex>().0.insert(ME, me);
+            crate::net::handlers::dispatch(world, vec![create(MOB)]);
+            let mob = world.resource::<GuidIndex>().0[&MOB];
+            *world.resource_mut::<Selection>() = Selection {
+                target: Some(mob),
+                guid: Some(MOB),
+            };
+            // The control: a live selected unit keeps its selection through a ring pass.
+            world
+                .run_system_once(super::super::update_ring)
+                .expect("the ring runs on the built client");
+            assert_eq!(world.resource::<Selection>().guid, Some(MOB));
+            // (The create's own name query is on the channel; only a selection send matters.)
+            assert!(
+                !rx.try_iter()
+                    .any(|c| matches!(c, ClientCommand::SetSelection { .. })),
+                "a live target is not deselected"
+            );
+            (app, mob, rx)
+        }
+
+        fn selection_cleared_at(teardown: SessionEvent) {
+            let (mut app, mob, rx) = client_with_selected_mob();
+            let world = app.world_mut();
+            crate::net::handlers::dispatch(world, vec![teardown]);
+            // The model is still there, fading — the scheduler's half of the teardown.
+            assert!(
+                world.get_entity(mob).is_ok(),
+                "the model outlives the object"
+            );
+            assert!(world.get::<DespawnFade>(mob).is_some(), "…and fades");
+            world
+                .run_system_once(super::super::update_ring)
+                .expect("the ring runs on the built client");
+            let sel = world.resource::<Selection>();
+            assert_eq!(
+                (sel.target, sel.guid),
+                (None, None),
+                "the selection ends with the object, not 2 s later with its model"
+            );
+            let sent: Vec<_> = rx.try_iter().collect();
+            assert!(
+                sent.iter()
+                    .any(|c| matches!(c, ClientCommand::SetSelection { guid: 0 })),
+                "the server is told at the teardown: {sent:?}"
+            );
+        }
+
+        #[test]
+        fn a_destroyed_target_clears_the_selection_at_the_destroy() {
+            selection_cleared_at(SessionEvent::ObjectDestroyed(MOB));
+        }
+
+        #[test]
+        fn a_streamed_out_target_clears_the_selection_at_the_stream_out() {
+            selection_cleared_at(SessionEvent::ObjectsRemoved(vec![MOB]));
+        }
+
+        /// The nearest-enemy acquire (the TAB core) cannot pick a fading model: it is not an
+        /// object any more. The control half proves the scan does find the mob while it lives.
+        #[test]
+        fn the_nearest_enemy_scan_never_picks_a_torn_down_object() {
+            let (mut app, _mob, _rx) = client_with_selected_mob();
+            let world = app.world_mut();
+            let acquire = |world: &mut World| {
+                *world.resource_mut::<Selection>() = Selection::default();
+                world
+                    .run_system_once(
+                        |scan: TargetScan,
+                         mut sel: ResMut<Selection>,
+                         mut seam: crate::creature_anim::AttackSeam,
+                         mut errors: ResMut<crate::ui_action::UiErrorKeys>| {
+                            attack_order_target(&scan, &mut sel, &mut seam, &mut errors)
+                        },
+                    )
+                    .expect("the scan runs on the built client")
+            };
+            assert_eq!(
+                acquire(world),
+                Some(MOB),
+                "control: the live mob is acquired"
+            );
+            crate::net::handlers::dispatch(world, vec![SessionEvent::ObjectsRemoved(vec![MOB])]);
+            assert_eq!(acquire(world), None, "the fading model is not a candidate");
+        }
+
+        /// The corpse → respawn shape: the server destroys the old object and creates the same
+        /// guid again in one tick. The fresh create is a new live object, and the old model
+        /// fading beside it no longer answers to the guid.
+        #[test]
+        fn a_same_tick_recreate_is_a_fresh_object_and_the_old_model_is_nobody() {
+            let (mut app, old, _rx) = client_with_selected_mob();
+            let world = app.world_mut();
+            crate::net::handlers::dispatch(
+                world,
+                vec![SessionEvent::ObjectDestroyed(MOB), create(MOB)],
+            );
+            let fresh = world.resource::<GuidIndex>().0[&MOB];
+            assert_ne!(fresh, old, "a fresh entity for the fresh object");
+            assert!(world.get::<DespawnFade>(fresh).is_none());
+            let answering: Vec<Entity> = world
+                .query::<(Entity, &Guid)>()
+                .iter(world)
+                .filter(|(_, g)| g.0 == MOB)
+                .map(|(e, _)| e)
+                .collect();
+            assert_eq!(answering, [fresh], "one object answers to the guid");
+        }
+    }
 }
diff --git a/crates/benilla-app/src/target/scan.rs b/crates/benilla-app/src/target/scan.rs
index 9260fbf3..f05bd579 100644
--- a/crates/benilla-app/src/target/scan.rs
+++ b/crates/benilla-app/src/target/scan.rs
@@ -2,8 +2,7 @@
 //! (decision 0567) over the 1.12 wire laws.
 //!
 //! The 1.12 byte algorithm (±30° cone about the *character's* facing, cone-first-then-nearest
-//! sort, 10-yd out-of-cone bubble, snapshot list + cursor cycling — wow-re
-//! `object-layer/scratch/targeting-nearest-and-autoacquire.md`, §5-verified twice) was
+//! sort, 10-yd out-of-cone bubble, snapshot list + cursor cycling — the TAB core `0x493f60`) was
 //! implemented faithfully, live-reproduced, and then **replaced at the director's call**: the
 //! authentic law skips a close mob that fills your screen (at 2 yd the cone is ~±1 yd wide, and
 //! the camera sits ~9 yd behind — "right in front of my cam" is routinely 40°+ off the
@@ -108,9 +107,7 @@ fn tab_trace_on() -> bool {
 /// place: `0x493e40`'s jump table (`0x493f50 = {0x493e73, 0x493eca, 0x493eed, 0x493f15}`). The
 /// enumeration, the creature-type table, the range cvars, the scene-attach gate, the scorer
 /// `0x494200`, the comparator `0x494450` and the commit `0x493540` are literally the same
-/// instructions for both sides — so this is a parameter on the one scan, never a second scanner
-/// (wow-re `object-layer/scratch/targeting-nearest-and-autoacquire.md` PART A;
-/// `object-layer/scratch/targeting-by-name.md` "the mode filter").
+/// instructions for both sides — so this is a parameter on the one scan, never a second scanner.
 ///
 /// Modes 3 and 4 (party / raid) are not built: they need the roster-only candidate set, and the
 /// two commands that drive them stay in the binding registry's absent table until they are.
@@ -227,9 +224,8 @@ fn combat_with_me(store: &ObjectStore, me: Option<u64>) -> bool {
 /// critter filtering, like the missing-catalog fallbacks elsewhere.
 ///
 /// **Critter alone** — the flag column is 1 for CreatureType 8 and for nothing else in the shipped
-/// 5875 DBC (Totem reads 0, and 1.12 has no non-combat-pet row). This prose said "critter/totem",
-/// copying a wow-re gloss that its own `targeting-friend-and-lastenemy.md` has since closed
-/// against the file; the code was always reading the flag rather than a type list, so only the
+/// 5875 DBC (Totem reads 0, and 1.12 has no non-combat-pet row). This prose said "critter/totem";
+/// the code was always reading the flag rather than a type list, so only the
 /// words were wrong.
 #[derive(Resource)]
 pub(crate) struct CreatureTypes(CreatureTypeFlags);
@@ -261,15 +257,14 @@ pub(super) fn load_creature_types(mut commands: Commands, world_assets: Option<R
 /// the player: `CanAssist(P, P)` is true (`0x6061e0` returns 4 when A == B) and the cone test
 /// `0x47f220(p, p)` returns exactly π/2, so the self entry is in-cone whenever your facing falls
 /// in (π/3, 2π/3) and — at distance² 0 — sorts first. Plain TAB is spared only because
-/// `CanAttack(P, P)` is false. (wow-re `targeting-friend-and-lastenemy.md`, verified
-/// exhaustively; its own write-up asks a re-implementation to add the player to both candidate
+/// `CanAttack(P, P)` is false. (A faithful re-implementation adds the player to both candidate
 /// sets.)
 ///
 /// We do not, and the reason is 0567: that behaviour is an artifact of the ±30° facing cone, and
 /// 0567 replaced the cone with screen-space priority. Under our scoring the player is at distance
 /// 0 and screen-centre *unconditionally*, so porting the byte-level rule would make `CTRL-TAB`
 /// self-target on **every** press rather than facing-dependently — faithful to the bytes,
-/// unfaithful to the behaviour, which is the trade `CLAUDE.md` §7 hands to the director rather
+/// unfaithful to the behaviour, which is the trade `docs/METHOD.md` §7 hands to the director rather
 /// than to this file. Recorded here so it is a known divergence and not a gap (decision 1745).
 #[derive(SystemParam)]
 #[allow(clippy::type_complexity)] // one bundled system param — the app's convention for big query sets
@@ -283,7 +278,6 @@ pub(crate) struct TargetScan<'w, 's> {
             &'static Guid,
             &'static Transform,
             Option<&'static ObjectStore>,
-            Option<&'static Visibility>,
         ),
         Without<SelfPlayer>,
     >,
@@ -410,8 +404,8 @@ impl TargetScan<'_, '_> {
         let self_store = self.self_store();
         self.units
             .iter()
-            .find(|(_, _, g, _, _, _)| g.0 == guid)
-            .is_some_and(|(_, _, _, _, store, _)| {
+            .find(|(_, _, g, _, _)| g.0 == guid)
+            .is_some_and(|(_, _, _, _, store)| {
                 reaction_from_player(
                     self.factions.as_deref(),
                     &self.reputations,
@@ -425,8 +419,8 @@ impl TargetScan<'_, '_> {
     fn unit_by_guid(&self, guid: u64) -> Option<(Entity, Option<&ObjectStore>)> {
         self.units
             .iter()
-            .find(|(_, _, g, _, _, _)| g.0 == guid)
-            .map(|(e, _, _, _, store, _)| (e, store))
+            .find(|(_, _, g, _, _)| g.0 == guid)
+            .map(|(e, _, _, _, store)| (e, store))
     }
 
     /// The full build: walk every known unit, filter (the kept 1.12 legality laws), project
@@ -441,7 +435,7 @@ impl TargetScan<'_, '_> {
     /// deliberate divergence, because the reference's enumeration walks ClntObjMgr table #1 —
     /// which holds the player's own object — and no self-compare has been derived on the mode-2
     /// path. Self sits at dist² 0 dead-centre, so a faithful `TargetNearestFriend` would appear to
-    /// always self-target; we refuse to ship that on an underived gate. RE dispatched.
+    /// always self-target; we refuse to ship that on an underived gate.
     fn build(&self, side: ScanSide) -> Vec<Candidate> {
         let Ok((self_tf, self_store, self_guid)) = self.self_q.single() else {
             return Vec::new();
@@ -478,7 +472,7 @@ impl TargetScan<'_, '_> {
             );
         };
         let mut out = Vec::new();
-        for (entity, net, guid_c, tf, store, vis) in &self.units {
+        for (entity, net, guid_c, tf, store) in &self.units {
             if !matches!(net.kind, EntityKind::Unit | EntityKind::Player) {
                 continue;
             }
@@ -507,11 +501,12 @@ impl TargetScan<'_, '_> {
                     }
                 }
             }
-            // The scene-attach/hide notion (kept): an explicitly hidden root is out.
-            if vis == Some(&Visibility::Hidden) {
-                trace_unit(guid_c.0, tf, "REJECT hidden");
-                continue;
-            }
+            // **No scene-attach gate.** The reference rejects a not-currently-rendered object
+            // here (`0x6704c0`), and this scan kept that while nothing hid a unit root. Since the
+            // outdoor draw election (1270/1475) hides every body outside the frustum, reading its
+            // `Visibility` would be the frustum by another name — and would empty the off-screen
+            // tier the Classic design (0567) keeps as the fallback. Tiering by the camera is the
+            // `project` step below; stealth and the like leave through the server's out-of-range.
             let dist = (tf.translation - self_tf.translation).length();
             if dist > TAB_RANGE {
                 trace_unit(guid_c.0, tf, "REJECT range (41 yd)");
@@ -608,7 +603,7 @@ pub(super) struct CommitOutcome {
 
 /// Commit a target through the SetSelection path (`0x493540`), byte-complete: dedup, then — on a
 /// switch while auto-attacking — the **stop → select → re-swing** law read directly from the
-/// binary (wow-re disasm, 2026-07-14):
+/// binary:
 ///
 /// 1. `0x493637–0x4936ac` latches "attacking AND the old target is still a live attackable unit"
 ///    into `[ebp-1]` before anything changes;
@@ -646,7 +641,7 @@ pub(super) fn commit(
     new_attackable: bool,
 ) -> CommitOutcome {
     // **`IsSelectable`, and it comes BEFORE the dedup** — `0x4935ec`–`0x4935f3`, the third of
-    // `0x493540`'s early-outs (wow-re `object-layer/scratch/selection-attack-seam.md` §3.1): the
+    // `0x493540`'s early-outs: the
     // resolved object's slot-`+0x58` vcall answering 0 is a bare RETURN, so a non-selectable unit
     // is a **complete** no-op — no stop, no `CMSG_SET_SELECTION`, no `PLAYER_TARGET_CHANGED`, no
     // re-swing, and the target you already had is left exactly where it was.
@@ -677,8 +672,7 @@ pub(super) fn commit(
     if swung {
         // `0x4938c8 call 0x5ecb70` with a stop in flight (`[+0xc54]`, set by the call above), so
         // the swing goes out despite the still-set lock. Its tail cancels a running auto-repeat —
-        // wow-re `melee-autorepeat-exclusion.md` §6 REFUTES `nocked-ammo-cancel.md`'s
-        // direct-callers-only census, which had this chain never reaching `0x6ea080`.
+        // this chain does reach `0x6ea080`, which a direct-callers-only census misses.
         seam.start(guid, engaged, true);
     }
     CommitOutcome {
@@ -1072,8 +1066,8 @@ pub(super) fn acquire_and_attack(
 /// The reference keeps two guid pairs beside the current selection, both written inside
 /// `SetSelection 0x493540`: `[0xb4e2e0]/[0xb4e2e4]`, the plain outgoing target (`TargetLastTarget`
 /// reads it, `0x493622`/`0x493628` write it), and `[0xb4e2e8]/[0xb4e2ec]`, the last **attackable**
-/// one (`TargetLastEnemy` reads it at `0x489b45`, `0x49377d` writes it) — wow-re
-/// `object-layer/scratch/selection-attack-seam.md` §3.1. So the memory belongs at the **selection
+/// one (`TargetLastEnemy` reads it at `0x489b45`, `0x49377d` writes it). So the memory belongs at
+/// the **selection
 /// commit**, which is where this puts it, and it is deliberately not a second thing to remember at
 /// each of [`commit`]'s six call sites: [`remember_last_enemy`] reads the frame's settled
 /// selection instead, so a selection writer added later cannot forget to stamp.
@@ -1099,8 +1093,7 @@ pub(crate) struct LastEnemy(pub(crate) Option<u64>);
 /// `TargetLastEnemy` back onto a corpse is faithful, and it is what you want a second after a kill.
 ///
 /// **The whole gate, not just the attackability leg.** `0x49372f`–`0x493778` is five conjuncts and
-/// this shipped with one of them (wow-re `targeting-friend-and-lastenemy.md`, §5 trio — the note
-/// was dispatched from this work and landed after it): the player object resolves, **the player is
+/// this shipped with one of them: the player object resolves, **the player is
 /// not dead or a ghost**, **the player is not mounted**, the new target reads
 /// `HEALTH > 0 || UNIT_DYNFLAG_DEAD`, and `CanAttack(player, new)`. Without the middle three we
 /// remembered in three states the reference does not — targeting a hostile while mounted, while
@@ -1243,8 +1236,8 @@ mod tests {
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut world = World::new();
         world.insert_resource(NetCommands(tx));
-        world.init_resource::<crate::ui_cast::QueuedMeleeSpell>();
-        world.init_resource::<crate::ui_action::AutoRepeatActive>();
+        world.init_resource::<crate::spell::QueuedMeleeSpell>();
+        world.init_resource::<crate::spell::AutoRepeatActive>();
         world.init_resource::<Messages<crate::creature_anim::SheathRequest>>();
         world.init_resource::<Messages<crate::player::StandStateRequest>>();
         world.init_resource::<Selection>();
@@ -1312,9 +1305,9 @@ mod tests {
         // engaged switch onto an attackable unit: the stop un-queues the strike, the re-swing
         // kills the repeat.
         world
-            .resource_mut::<crate::ui_cast::QueuedMeleeSpell>()
+            .resource_mut::<crate::spell::QueuedMeleeSpell>()
             .arm(78);
-        world.resource_mut::<crate::ui_action::AutoRepeatActive>().0 = Some(75);
+        world.resource_mut::<crate::spell::AutoRepeatActive>().0 = Some(75);
         let out = go(&mut world, 0xF, true, Some(1), true);
         assert!(out.changed && out.swung);
         assert_eq!(
@@ -1322,14 +1315,12 @@ mod tests {
             ["stop", "cancel-cast", "select", "swing", "cancel-repeat"]
         );
         assert_eq!(
-            world
-                .resource::<crate::ui_cast::QueuedMeleeSpell>()
-                .current(),
+            world.resource::<crate::spell::QueuedMeleeSpell>().current(),
             None,
             "the switch un-queued Heroic Strike"
         );
         assert_eq!(
-            world.resource::<crate::ui_action::AutoRepeatActive>().0,
+            world.resource::<crate::spell::AutoRepeatActive>().0,
             None,
             "and the re-swing killed Auto Shot"
         );
@@ -1701,6 +1692,53 @@ mod tests {
         assert_eq!(pool(&mut world, ScanSide::Friend), [ALLY, ALLY_FEIGN]);
     }
 
+    /// **A unit the draw election culled is still a TAB candidate.** The outdoor election
+    /// (decisions 1270/1475) writes `Visibility::Hidden` on every body root outside the camera
+    /// frustum, every frame — so a scan gate on `Hidden` emptied the off-screen tier 0567 keeps
+    /// as the fallback, and TAB / attack-with-no-target / pet Attack could never reach a mob
+    /// hitting you from behind while nothing was on screen.
+    #[test]
+    fn a_body_the_draw_election_culled_is_still_a_candidate() {
+        use bevy::ecs::system::RunSystemOnce;
+
+        const MOB: u64 = 0xBEEF;
+        let mut world = World::new();
+        world.init_resource::<Reputations>();
+        world.init_resource::<NameCache>();
+        world.spawn((
+            SelfPlayer,
+            Transform::default(),
+            Guid(1),
+            store(&[
+                (F_TYPE, TYPE_PLAYER),
+                (F_FLAGS, CONTROLLED),
+                (F_HEALTH, 100),
+                (F_MAXHEALTH, 100),
+            ]),
+        ));
+        world.spawn((
+            NetEntity {
+                kind: EntityKind::Unit,
+                display_id: None,
+                scale: 1.0,
+            },
+            Guid(MOB),
+            Transform::from_xyz(0.0, 0.0, 5.0),
+            store(&[(F_HEALTH, 100), (F_MAXHEALTH, 100)]),
+            // The election's out-of-view verdict (`exterior_cull`'s body leg).
+            Visibility::Hidden,
+        ));
+        let pool = world
+            .run_system_once(|scan: TargetScan| {
+                scan.build(ScanSide::Enemy)
+                    .iter()
+                    .map(|c| c.guid)
+                    .collect::<Vec<_>>()
+            })
+            .expect("the scan runs as a one-shot system");
+        assert_eq!(pool, [MOB]);
+    }
+
     /// [`LastEnemy`] tracks the last **attackable** selection and nothing else — `TargetLastEnemy`'s
     /// whole memory (`[0xb4e2e8]/[0xb4e2ec]`, `0x49377d`).
     ///
diff --git a/crates/benilla-app/src/text_filter.rs b/crates/benilla-app/src/text_filter.rs
index 279fa3e0..f8f0bd31 100644
--- a/crates/benilla-app/src/text_filter.rs
+++ b/crates/benilla-app/src/text_filter.rs
@@ -1,6 +1,5 @@
 //! The two 1.12 text filters — `profanityFilter`'s **masker** and `spamFilter`'s **predicate**
-//! (decision 2077; wow-re `system/ui/scratch/text-filter-law.md`, a §5 round of seven workers with
-//! an emulated run of the binary's own compile/exec over the shipped lists).
+//! (decision 2077; an emulated run of the binary's own compile/exec over the shipped lists).
 //!
 //! 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
@@ -49,9 +48,8 @@
 //! - **`\<` 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`. wow-re settled this twice — at the table,
-//!   and by running the binary's own compiler on a reversal control (`\>twat\<` behaves exactly
-//!   like `\<twat\>`).
+//!   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
@@ -352,9 +350,9 @@ mod tests {
             .collect()
     }
 
-    /// `\<` and `\>` are **word boundaries**, and non-directional — wow-re's reversal control,
-    /// 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 **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.
     #[test]
     fn the_angle_escapes_are_non_directional_word_boundaries() {
         for spelling in [r"\<twat\>", r"\>twat\<", r"\btwat\b"] {
@@ -373,8 +371,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 wow-re's oracle transcript, run
-    /// against the binary's own bytes, reproduced pattern for 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
@@ -528,9 +526,8 @@ impl ChatTextFilter<'_> {
     ///
     /// **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`.
-    /// (wow-re settled that at the bytes after the note first said "bypassing both arms"; the
-    /// reductio is that the wrong reading would make `spamFilter = 0` disable profanity masking
-    /// too.)
+    /// (Reading it as "bypassing both arms" is wrong: it would make `spamFilter = 0` disable
+    /// profanity masking too.)
     pub(crate) fn should_drop(
         &self,
         chat_type: u8,
diff --git a/crates/benilla-app/src/text_reshape.rs b/crates/benilla-app/src/text_reshape.rs
index c29ccde7..31c7a498 100644
--- a/crates/benilla-app/src/text_reshape.rs
+++ b/crates/benilla-app/src/text_reshape.rs
@@ -1,7 +1,7 @@
 //! **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; bug B383, Goudy: *"if you enter world in window mode and then
-//! maximize window on linux, the client will crash"*).
+//! none of our code (decision 2212). The way in: enter the world in window mode, then maximize the
+//! window on Linux.
 //!
 //! ## The hole
 //!
@@ -291,7 +291,7 @@ mod tests {
         );
     }
 
-    /// **The crash itself.** The same sequence with the net taken out is the client Goudy ran:
+    /// **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
diff --git a/crates/benilla-app/src/textinput/clipboard.rs b/crates/benilla-app/src/textinput/clipboard.rs
index 9979e887..d1021296 100644
--- a/crates/benilla-app/src/textinput/clipboard.rs
+++ b/crates/benilla-app/src/textinput/clipboard.rs
@@ -1,8 +1,8 @@
 //! 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 (RF-0082's stated gap), 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`.
+//! 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
diff --git a/crates/benilla-app/src/textinput/keymap.rs b/crates/benilla-app/src/textinput/keymap.rs
index d6118949..20026db0 100644
--- a/crates/benilla-app/src/textinput/keymap.rs
+++ b/crates/benilla-app/src/textinput/keymap.rs
@@ -5,10 +5,10 @@
 //! 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
-//! (RF-0082 §4: 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.
+//! (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
@@ -119,7 +119,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
-/// (RF-0082 §4), plus the modern Ctrl word-deletes.
+/// (`0x77b160`), plus the modern Ctrl word-deletes.
 fn chord_pc(key: KeyCode, m: Mods) -> Option<Chord> {
     use EditUnit::{Char, Edge, Word};
     let mv = |unit, back| {
@@ -131,7 +131,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 (RF-0082 §4).
+        // Ctrl picks the word-granular helper — the ref's own fork on its Ctrl test `0x41f8f0(1)`.
         KeyCode::ArrowLeft | KeyCode::ArrowRight => {
             let back = key == KeyCode::ArrowLeft;
             if m.ctrl {
@@ -150,7 +150,7 @@ fn chord_pc(key: KeyCode, m: Mods) -> Option<Chord> {
         // 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 (RF-0082 §4) — else the
+        // Shift+Delete = Cut — the CUA mirror the ref itself honors (`0x77b160`) — else the
         // modern Ctrl word-delete, else one char.
         KeyCode::Backspace => {
             if m.ctrl {
diff --git a/crates/benilla-app/src/transport.rs b/crates/benilla-app/src/transport.rs
index 668dcd2e..b4e54a57 100644
--- a/crates/benilla-app/src/transport.rs
+++ b/crates/benilla-app/src/transport.rs
@@ -11,8 +11,8 @@
 //! - **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 `gameobject_path_eval`, byte-verified
-//!   in wow-re; vmangos `ElevatorTransport::Update` is the same math server-side).
+//!   ([`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.
@@ -419,8 +419,8 @@ fn arm_transports(
             .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
-                    // (bit-exact against all nine server-sniff periods — the 2026-07-17 wow-re
-                    // §5 verdict), so the period on the label IS the server's.
+                    // (`0x5f4cc0`, bit-exact against all nine server-sniff periods), so the
+                    // period on the label IS the server's.
                     let t = TransportTimetable::build(path, mo.move_speed, mo.accel_rate)?;
                     info!(
                         "transport: path {} timetable built — period {} ms",
@@ -454,7 +454,7 @@ fn arm_transports(
 }
 
 /// The per-frame transport tick — the client's own `(progress + anchor) % period` leg walk
-/// (wow-re `0x5f50a0`, decision 0438): sample the timetable, write the pose. Translation +
+/// (`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.
@@ -769,7 +769,7 @@ fn compose_riders(
 /// **Re-ground a deck-splined rider onto the deck it is walking on** (decision 1936's correction).
 ///
 /// 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 what wow-re's carve refuted. The
+/// 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
@@ -847,7 +847,8 @@ fn ground_deck_riders(
 /// **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 `m2_animate`).
+/// 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
diff --git a/crates/benilla-app/src/tutorial.rs b/crates/benilla-app/src/tutorial.rs
index 9f54ab19..cd86f53c 100644
--- a/crates/benilla-app/src/tutorial.rs
+++ b/crates/benilla-app/src/tutorial.rs
@@ -1,9 +1,9 @@
-//! The tutorial system (decision 1976; wow-re `system/ui/scratch/tutorial-flags.md`): the two
+//! 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`.
 //!
-//! ## Two banks, not one (§1, §2)
+//! ## Two banks, not one (`0xb711b8`, `0xb711e4`)
 //!
 //! 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,
@@ -13,14 +13,14 @@
 //! `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.
 //!
-//! ## The trigger (§3)
+//! ## 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 (§4, §5)
+//! ## 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
@@ -74,7 +74,7 @@ pub(crate) mod id {
     pub(crate) const KEYRINGS: u32 = 0x31;
 }
 
-/// The level-gated arm of the `SMSG_LEVELUP_INFO` handler (§4): in the handler's own order,
+/// The level-gated arm of the `SMSG_LEVELUP_INFO` handler (`0x5e38c0`): in the handler's own order,
 /// each fires when the new level is at least its threshold.
 const LEVEL_TRIGGERS: [(u32, u32); 8] = [
     (3, 0x16),  // Chatting
@@ -90,9 +90,9 @@ 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 (§4's row reads the stamp getter,
-/// not its meaning).
+/// 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).
 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.
@@ -169,7 +169,7 @@ impl Tutorials {
         self.timers.clear();
     }
 
-    /// `TriggerTutorial(id, delayMs)` (§3).
+    /// `TriggerTutorial(id, delayMs)` (`0x4b5390`).
     pub(crate) fn trigger(&mut self, id: u32, delay_ms: u32, now: Instant) {
         let Some(bank) = self.fire_once.as_mut() else {
             return; // no bank yet: silent
@@ -186,7 +186,7 @@ impl Tutorials {
         }
     }
 
-    /// `SetTutorialFlag(id)` (`0x4b54c0`, §5): bank B's bit gates; both banks set; the id's timer
+    /// `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.
     pub(crate) fn acknowledge(&mut self, id: u32) {
@@ -254,7 +254,7 @@ impl Tutorials {
     }
 }
 
-/// The self descriptor's last-seen fields, for the edge-triggered sites (§4): the level-up
+/// The self descriptor's last-seen fields, for the edge-triggered `0x4b5390` sites: the level-up
 /// arm, the ghost flag, the resting flag, the PvP flag, the rest state.
 #[derive(Default)]
 struct SelfWatch {
@@ -297,9 +297,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 is not carved bit by bit); Hearthstones by entry; Ranged
-    // Weapons for a ranged type on a non-hunter; Keyrings by the slot band.
+    // 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.
     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 {
@@ -346,8 +346,8 @@ fn feed_tutorials(
     }
 }
 
-/// The self descriptor's edge sites (§4): 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
+/// 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.
 fn watch_self(
@@ -488,7 +488,7 @@ fn run_world_enter_cascade(
     }
 }
 
-/// The world-input sites (`0x514840`, §4/§5), bundled for the controller: a movement input
+/// The world-input sites (`0x514840`), bundled for the controller: a movement input
 /// acknowledges Movement and arms the 10 s Targeting popup; a mouse-look acknowledges Cameras.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct InputHooks<'w> {
@@ -570,6 +570,7 @@ pub(crate) struct TutorialPlugin;
 
 impl Plugin for TutorialPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<Tutorials>()
             .init_resource::<WorldEnterCascade>()
             .add_message::<TutorialEvent>()
@@ -608,6 +609,26 @@ impl Plugin for TutorialPlugin {
     }
 }
 
+/// The tutorial flags' packet handler (in the net handler table since 2326).
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::Tutorials;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handler — called from [`super::TutorialPlugin`].
+    pub(super) fn register(app: &mut App) {
+        app.net_handler(SessionEventKind::TutorialFlags, on_flags);
+    }
+
+    fn on_flags(In(ev): In<SessionEvent>, mut tutorials: ResMut<Tutorials>) {
+        if let SessionEvent::TutorialFlags(bytes) = ev {
+            tutorials.apply_flags(&bytes);
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/benilla-app/src/ui_action/cast_fail.rs b/crates/benilla-app/src/ui_action/cast_fail.rs
index 8949295f..7b1bd801 100644
--- a/crates/benilla-app/src/ui_action/cast_fail.rs
+++ b/crates/benilla-app/src/ui_action/cast_fail.rs
@@ -1,5 +1,4 @@
-//! Cast-failure display strings — the reference's **two-layer** pipeline, byte-verified and
-//! §5 cross-checked (wow-re `system/spell/scratch/cast-fail-strings.md`; decision 0427):
+//! Cast-failure display strings — the reference's **two-layer** pipeline (decision 0427):
 //!
 //! 1. `HandleCastFailed 0x6e1a00` resolves the wire reason through the name-identity table
 //!    `0x6e23e0` (wire order = the vmangos `SpellCastResult` enum) into
@@ -58,8 +57,8 @@
 //!
 //! Stripping is a **deliberate divergence**, now byte-confirmed as one: on a
 //! bad id or an absent word the reference jumps to the default arm with the pointer still on the
-//! *unfilled* template, so it displays a literal `Requires %s` (wow-re §WIRE-ARGS C3 — the fill
-//! path's own buffer swap sits after the printf and is skipped). We show the bare stem instead:
+//! *unfilled* template, so it displays a literal `Requires %s` (the fill path's own buffer swap
+//! `0x6e21d2` sits after the printf and is skipped). We show the bare stem instead:
 //! "Requires" reads as terse, "Requires %s" reads as broken software (§7 — judge by the result).
 //! **`0x56` is the exception, and it is the reference's own** ([`Fill::Nothing`]): its three
 //! failure exits land on the function epilogue, not on that default arm, so an unfillable
@@ -297,8 +296,7 @@ impl FailArgs<'_> {
     /// The `%s` fill for the argument-formatted reasons this module owns, or `None` to leave the
     /// template to the strip fallback.
     ///
-    /// Both arms are byte-verified and §5 cross-checked (wow-re `cast-fail-strings.md`
-    /// §WIRE-ARGS): each reads the **wire's** first argument word — `[ebx+8]`, the handler's own
+    /// Each of the two arms reads the **wire's** first argument word — `[ebx+8]`, the handler's own
     /// stack slot, never a re-read of `Spell.dbc` — indexes its DBC store, and `SStrPrintf`s the
     /// reason's `SPELL_FAILED_*` template. The errorId stays the default `0x2c` (`"%s"`) for both,
     /// so what the player reads IS the filled template. A single-`%s` template is what makes a
@@ -1113,7 +1111,7 @@ mod tests {
         }
     }
 
-    /// The table's byte-verified anchors (wow-re cast-fail-strings.md).
+    /// The `0x6e23e0` table's anchors.
     #[test]
     fn the_key_table_holds_the_verified_anchors() {
         assert_eq!(CAST_FAIL_KEYS.len(), 146);
diff --git a/crates/benilla-app/src/ui_action/drain.rs b/crates/benilla-app/src/ui_action/drain.rs
index a8d6a5b7..804102f7 100644
--- a/crates/benilla-app/src/ui_action/drain.rs
+++ b/crates/benilla-app/src/ui_action/drain.rs
@@ -1,7 +1,7 @@
 //! **Outward** — the two action-bar drains, and the law that decides what a click *does*.
 //!
 //! - **Use** ([`drain_action_uses`]): a queued `UseAction(n)` becomes wire. A SPELL action goes
-//!   through the one cast-send path ([`super::cast_send::send_spell_cast`]); the auto-attack action
+//!   through the one cast-send path ([`crate::spell::CastLadder::send`]); the auto-attack action
 //!   (6603) sends `CMSG_ATTACKSWING` at the selection, or acquires the nearest enemy when there is
 //!   none; an ITEM action names an *entry*, not a position, so it must first find a copy and then
 //!   decide equip-vs-use — [`item_action_route`], the byte-verified two-stage law of decision 0666.
@@ -23,8 +23,9 @@ use benilla_ui::script::UiScript;
 
 use crate::net::{ClientCommand, NetCommands};
 
-use super::cast_send::{CastCommit, CastLadder};
-use super::{attack_actor_refusal, cast_target, PlayerActions, UiErrorKeys, SPELL_ATTACK};
+use crate::spell::{cast_target, CastCommit, CastLadder};
+
+use super::{attack_actor_refusal, PlayerActions, UiErrorKeys, SPELL_ATTACK};
 
 /// What clicking an ITEM action does, and to which copy — [`item_action_route`]'s verdict.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -38,9 +39,8 @@ pub(super) enum ItemRoute {
     Nowhere,
 }
 
-/// The reference's **two-stage** equip-vs-use decision for an ITEM action, byte-verified (wow-re
-/// `action-item-slot.md` §8.1, `0x4e5fdd`–`0x4e5ff7`; decision 0666, which supersedes 0216 §7's
-/// guessed one):
+/// The reference's **two-stage** equip-vs-use decision for an ITEM action (`0x4e5fdd`–`0x4e5ff7`;
+/// decision 0666, which supersedes 0216 §7's guessed one):
 ///
 /// ```text
 /// InventoryType == 0            → USE          (a consumable is never equipped)
@@ -135,39 +135,11 @@ pub(super) fn attack_target_binding(
     }
 }
 
-/// **The `modalNextSpell` chain** — `HandleCastResult 0x6e7330`'s tail (`0x6e7447`–`0x6e74aa`),
-/// the client casting a spell at itself with no user input. `cast_result` decides *whether*
-/// (the column read, the in-flight test, the already-running test — all of it is the packet
-/// handler's, so it stays there); this only carries the decision to the one send path.
-///
-/// The cast goes out at the **null target guid** — `0x6e74a6 push ebx; push ebx` with `ebx = 0`
-/// — so the chained Auto Shot binds through the ordinary target walk (`ArmCast 0x6e5250`:
-/// main-hand item bit, then the explicit guid, then the current selection), which is what
-/// [`cast_target::CastTargeting::context`] hands the ladder when no guid is passed.
-///
-/// And it takes **every rung**: the reference chains through `0x6e5a90` → `TryCast 0x6e4b60`, the
-/// same entry a button press uses, so a chained Auto Shot is range-checked, form-checked and
-/// GCD-checked exactly like a pressed one, and refuses with the same red line.
-pub(super) fn drain_chain_casts(
-    mut queue: ResMut<crate::ui_action::ChainCasts>,
-    targeting: cast_target::CastTargeting,
-    mut ladder: CastLadder,
-) {
-    if queue.0.is_empty() {
-        return;
-    }
-    let ctx = targeting.context();
-    for spell_id in std::mem::take(&mut queue.0) {
-        debug!("ui_action: modalNextSpell chain casts {spell_id}");
-        ladder.send(spell_id, &ctx, CastCommit::Spell);
-    }
-}
-
 /// **The world right-click's GameObject opener**, run through the one cast path (decision 2199) —
 /// the seam [`crate::ui_action::GoOpenerCasts`] exists for.
 ///
 /// The reference reaches TryCast from the GameObject strategy's use-sender exactly as it does from
-/// a button press (`0x5f35c0 → 0x6e5a90 → 0x6e4b60`, wow-re `cursor-system.md` §8.4), so an opener
+/// a button press (`0x5f35c0 → 0x6e5a90 → 0x6e4b60`), so an opener
 /// takes **every rung** — in-flight, cooldown/GCD, power, crowd control, mounted, water, moving,
 /// form, reagents — and not the two the click used to check on its own. The rung that matters for
 /// the report this closes is the in-flight one: the second right-click on a chest whose Opening
@@ -275,7 +247,7 @@ pub(super) fn drain_action_uses(
                 // The attack-start validator's Phase A ([`attack_actor_refusal`]) — for a melee
                 // swing the actor is US. It refuses BEFORE the with-target swing and before the
                 // nearest-enemy scan (every Phase A gate precedes `0x6130b5`), so both arms gate
-                // here. Widened from mounted-only when wow-re carved the rest of `0x612df0`:
+                // here. Widened from mounted-only to the rest of `0x612df0`:
                 // stunned, pacified, fleeing, confused, charmed by somebody else, and dead now
                 // refuse the swing too, each with its own red line.
                 if attack_actor_refusal(
@@ -291,7 +263,7 @@ pub(super) fn drain_action_uses(
                         // pseudo-spell reaches through `TryCast`'s effect-0x4e short-circuit
                         // (`0x6e4c7a`), forks on `0x60ecb0`: already attacking →
                         // `0x6131d9 call 0x5ecac0` **StopAttack**, else `0x6131ee call 0x5ecb70`
-                        // **StartAttack** (wow-re `melee-autorepeat-exclusion.md` §5f).
+                        // **StartAttack**.
                         //
                         // Both halves were wrong here. There was no toggle-off at all, and the
                         // press cancelled a running auto-repeat *unconditionally* — but only the
@@ -338,9 +310,9 @@ pub(super) fn drain_action_uses(
                     ladder.ground.clear();
                     continue;
                 }
-                // The active-action toggle (`0x4e55f0` → the `0x4e60c1` cancel; wow-re
-                // `shapeshift-plaincast-toggle.md`): a live ActiveIconID spell re-pressed on
-                // its button cancels its own aura — Ghost Wolf, the druid forms, Stealth. The
+                // The active-action toggle (`0x4e55f0` → the `0x4e60c1` cancel): a live
+                // ActiveIconID spell re-pressed on its button cancels its own aura — Ghost Wolf,
+                // the druid forms, Stealth. The
                 // form-match toggle is deliberately NOT here (the ref's `UseAction` has no such
                 // leg — the `CastSpell` dispatcher alone carries it; keep the asymmetry).
                 if let Some(d) = ladder.spells.as_ref().and_then(|s| s.catalog.get(b.action)) {
@@ -390,7 +362,7 @@ pub(super) fn drain_action_uses(
                     continue;
                 };
                 let route = item_action_route(&template, |s| {
-                    crate::ui_items::find_item(&store.0, &ladder.items, b.action, s)
+                    crate::ui_items::find_item(&store.0, &ladder.objects, b.action, s)
                 });
                 let ((bag_index, slot0, guid), equip) = match route {
                     ItemRoute::Use(pos) => (pos, false),
@@ -416,6 +388,7 @@ pub(super) fn drain_action_uses(
                     crate::ui_items::send_auto_equip(
                         &mut script,
                         &mut gate,
+                        &ladder.objects,
                         &ladder.items,
                         &ladder.commands,
                         bag_index,
@@ -459,11 +432,10 @@ pub(super) fn drain_action_uses(
                     );
                 }
             }
-            // The MACRO arm (`0x4e5ee0`'s `and ecx,0xbfffffff; call 0x4f1460` fork, wow-re
-            // `action-item-slot.md` §8): run the macro's body. Every line goes onto the chat-input
-            // queue — the door a typed line comes through — so `/cast`, `/target`, `/script`, the
-            // chat types and the 225 emotes all work in a macro by construction
-            // (`crate::ui_macro::run`'s module doc).
+            // The MACRO arm (`0x4e5ee0`'s `and ecx,0xbfffffff; call 0x4f1460` fork): run the
+            // macro's body. Every line goes onto the chat-input queue — the door a typed line
+            // comes through — so `/cast`, `/target`, `/script`, the chat types and the 225 emotes
+            // all work in a macro by construction (`crate::ui_macro::run`'s module doc).
             Some(b) if b.kind == ACTION_KIND_MACRO => {
                 if !crate::ui_macro::run_macro(&mut script, b.action) {
                     debug!(
diff --git a/crates/benilla-app/src/ui_action/drop_item.rs b/crates/benilla-app/src/ui_action/drop_item.rs
index f60ca8b1..f6315860 100644
--- a/crates/benilla-app/src/ui_action/drop_item.rs
+++ b/crates/benilla-app/src/ui_action/drop_item.rs
@@ -1,6 +1,5 @@
 //! **`DropItemOnUnit 0x48d960`** — the cursor's held item dropped onto a unit, which in 1.12 is
-//! how you feed your pet (decision 1055; wow-re `ui/scratch/item-target-cursor-and-dropitemonunit.md`,
-//! VERIFIED).
+//! how you feed your pet (decision 1055).
 //!
 //! The reference's binding forks on which unit it was given:
 //!
@@ -30,7 +29,7 @@ use bevy::prelude::*;
 
 use benilla_ui::script::{CursorPayload, UiScript};
 
-use super::cast_send::{CastCommit, TargetedBind};
+use crate::spell::{CastCommit, TargetedBind};
 
 /// `0x6ea1e0` — is this unit a pet *I* can feed? All three gates, in the reference's order. Any
 /// miss is a silent refusal (see the module docs), so this returns a plain bool rather than a
@@ -74,7 +73,7 @@ pub(crate) fn drop_item_on_unit(
     learned: Res<super::LearnedAbilities>,
     press: Res<crate::target::PressPick>,
     mut clicks: MessageReader<benilla_world::interact::WorldClick>,
-    mut ladder: super::CastLadder,
+    mut ladder: crate::spell::CastLadder,
 ) {
     let Some(mut script) = script else {
         clicks.clear();
@@ -127,7 +126,7 @@ pub(crate) fn drop_item_on_unit(
         };
         let slot0 = u8::try_from(held.slot.saturating_sub(1)).unwrap_or(0);
         let Some(item_guid) =
-            crate::ui_items::slot_guid(&self_store.0, held.bag, slot0, &ladder.items)
+            crate::ui_items::slot_guid(&self_store.0, held.bag, slot0, &ladder.objects)
         else {
             continue; // the slot emptied under us — silent, as every refusal here is
         };
diff --git a/crates/benilla-app/src/ui_action/errors.rs b/crates/benilla-app/src/ui_action/errors.rs
index f04cd745..9ea6bbc2 100644
--- a/crates/benilla-app/src/ui_action/errors.rs
+++ b/crates/benilla-app/src/ui_action/errors.rs
@@ -184,7 +184,7 @@ pub(crate) use benilla_ui::messages::MsgKind;
 /// One argument in a message's **argText list**.
 ///
 /// Heterogeneous and ordered because the template's specifiers are: the lock-refusal toast
-/// `ERR_USE_LOCKED_WITH_SPELL_KNOWN_SI` is String-then-Integer (wow-re cursor-system.md §8.8,
+/// `ERR_USE_LOCKED_WITH_SPELL_KNOWN_SI` is String-then-Integer (its arm `0x5f34a9`,
 /// decision 0545), and a list of strings beside a separate number cannot express that.
 #[derive(Debug, PartialEq, Eq)]
 pub(crate) enum FillArg {
@@ -198,10 +198,9 @@ pub(crate) enum FillArg {
 /// refusals carry their chat lines in it too (decision 0669).
 ///
 /// **`0x496720` is variadic** — cdecl, the catalog id first and the argText after it, `add esp,4`
-/// at a bare call site and `add esp,8` at a one-string one (wow-re
-/// `system/ui/scratch/staticpopup-dialog-bindings.md`; `guild-api-carve.md` §5's "22 of 22" arity
-/// control). Three strings is the most any call site pushes: `SMSG_GUILD_EVENT`'s shared emitter
-/// tail `0x5e745f` passes **1, 2 or 3** of them off the packet's `strCount`, feeding
+/// at a bare call site and `add esp,8` at a one-string one (22 of 22 in the guild command-result
+/// handler `0x5e7520`). Three strings is the most any call site pushes: `SMSG_GUILD_EVENT`'s
+/// shared emitter tail `0x5e745f` passes **1, 2 or 3** of them off the packet's `strCount`, feeding
 /// `ERR_GUILD_PROMOTE_SSS`. This field was a single `fill_s` until decision 2054, which is why
 /// the guild lines could not use this route at all and composed their own English instead.
 ///
@@ -281,9 +280,9 @@ pub(crate) struct UiErrorKeys(pub Vec<UiError>);
 /// `mov edx,1; call 0x4945b0` → `UI_ERROR_MESSAGE`) and `SMSG_AREA_TRIGGER_MESSAGE` (`0x2b8`, the
 /// shared handler `0x48f690`'s arm at `0x48f8ff` — `xor edx,edx; call 0x4945b0` →
 /// `UI_INFO_MESSAGE`). `0x4945b0(text, flag)` is the whole sink: null/empty guard, then
-/// `neg edx; sbb edx,edx; add edx,0xe1` = event `0xe1` when the flag is 0 and `0xe0` when it is 1
-/// (wow-re `system/ui/ui.md` l.2459). The handler's own choice of flag is what the [`MsgKind`]
-/// here carries — the same two surfaces the catalog names, reached by a different road.
+/// `neg edx; sbb edx,edx; add edx,0xe1` = event `0xe1` when the flag is 0 and `0xe0` when it is 1.
+/// The handler's own choice of flag is what the [`MsgKind`] here carries — the same two surfaces
+/// the catalog names, reached by a different road.
 #[derive(Resource, Default)]
 pub(crate) struct UiErrorTexts(pub Vec<(String, MsgKind)>);
 
@@ -300,7 +299,7 @@ impl UiErrorTexts {
 }
 
 /// Resolve one [`UiError`] to its displayed text — `GetText(key)` + the `%s`/`%d` argText
-/// substitution ("Requires %s" + "Herbalism" → "Requires Herbalism", cursor-system.md §8.8).
+/// substitution ("Requires %s" + "Herbalism" → "Requires Herbalism").
 /// `None` (the key resolves to nothing, or the filled text is empty) = show nothing — a
 /// **NAMED DIVERGENCE**, corrected from a false citation this doc carried until 2246.
 ///
@@ -481,13 +480,12 @@ pub(crate) struct MessageSink<'w> {
 }
 
 /// `UNIT_FIELD_FLAGS` bits the attack-start validator refuses on, paired with the message each
-/// raises — read at `0x612eec`+ in the binary's own test order (wow-re
-/// `object-layer/scratch/pet-command-validators.md` §2). All four are crowd control: the actor is
-/// not refusing, it is unable.
+/// raises — read at `0x612eec`+ in the binary's own test order. All four are crowd control: the
+/// actor is not refusing, it is unable.
 ///
 /// Each has a second face in the reference — errorId `0xa9`
 /// `ERR_ATTACK_PREVENTED_BY_MECHANIC_S`, which substitutes a resolved mechanic name — chosen by
-/// five `0x6e9…` resolvers whose bodies wow-re records as **not carved**. We raise the plain form
+/// five `0x6e9…` resolvers whose bodies are **not yet decoded**. We raise the plain form
 /// only; the fill is a strictly better message for the same refusal, never a different one.
 const ATTACK_FLAG_REFUSALS: [(u32, &str); 4] = [
     (0x0004_0000, "ERR_ATTACK_STUNNED"),
@@ -497,8 +495,8 @@ const ATTACK_FLAG_REFUSALS: [(u32, &str); 4] = [
 ];
 
 /// Phase A of the shared attack-start validator `0x612df0` — **the actor's own eligibility**
-/// (wow-re `object-layer/scratch/pet-command-validators.md` §2, carved 2026-08-05; it supersedes
-/// the mounted-only fragment decision 0481 built from the one gate that was known then).
+/// (it supersedes the mounted-only fragment decision 0481 built from the one gate that was known
+/// then).
 ///
 /// `0x612df0(ecx = actor, &outGuid)` is ONE function with three call sites, and **the actor is
 /// whoever the caller passes in `ecx`** — the player for the melee attack-start router `0x6131aa`,
@@ -516,7 +514,7 @@ const ATTACK_FLAG_REFUSALS: [(u32, &str); 4] = [
 /// `dead` is `0x605f30(actor)`, which for any non-player actor — a pet never carries the player
 /// typemask bit — degenerates to exactly `health <= 0`. Its further leg for a *player* actor
 /// (`[[obj+0xe68]+8]` bit 4, reached only when health is positive, so plainly the ghost state) is
-/// byte-read but unnamed in wow-re's note, so it is left to the caller: pass `dead` yourself when
+/// byte-read but its name is unconfirmed, so it is left to the caller: pass `dead` yourself when
 /// you know more than the health field does.
 pub(crate) fn attack_actor_refusal(
     actor: Option<&ObjectStore>,
@@ -533,7 +531,7 @@ pub(crate) fn attack_actor_refusal(
 
 /// The same ladder **without the message** — which condition blocks the swing, or `None`.
 ///
-/// It exists because `0x612df0` is not on every attack-start path, and 1851's §5 pinned which:
+/// It exists because `0x612df0` is not on every attack-start path, and decision 1851 pinned which:
 /// its three callers image-wide are the pet-attack command (`0x4bd40d`), the Attack
 /// action/keybind (`0x6131aa`) and TryCast (`0x6e4efb`) — and **not** the world right-click.
 /// That click runs `0x60bea0` → `0x60c247 call 0x5ecb70`, whose whole extent
@@ -576,8 +574,8 @@ pub(crate) fn attack_actor_blocked(
     Some(key)
 }
 
-/// The ref's pre-send totem/reagent possession check — `CheckReagentsAndTotems 0x6e4000`,
-/// byte-verified (decision 0552; wow-re `cast-fail-strings.md` "Loose end 2"): TryCast runs it
+/// The ref's pre-send totem/reagent possession check — `CheckReagentsAndTotems 0x6e4000`
+/// (decision 0552): TryCast runs it
 /// for EVERY cast path (action bar, Lua, the GameObject-use opener) **before any packet is
 /// built**. Totems first (2 slots, a bag **presence** test — the Mining Pick / Skinning Knife /
 /// Thieves' Tools tools), then reagents (8 slots, a bag **count** test). The first failing slot
@@ -591,16 +589,16 @@ pub(crate) fn reagent_totem_refusal(
     spell_id: u32,
     def: Option<&benilla_formats::SpellDisplay>,
     self_store: Option<&ObjectStore>,
-    items: &crate::items::Items,
+    objects: &crate::net::Objects,
     errors: &mut CastErrors,
 ) -> bool {
     let (Some(d), Some(store)) = (def, self_store) else {
         return false;
     };
     // Totems before reagents — the ref's in-function loop order.
-    let reason = if first_missing_totem(d, store, items).is_some() {
+    let reason = if first_missing_totem(d, store, objects).is_some() {
         0x78
-    } else if first_short_reagent(d, store, items).is_some() {
+    } else if first_short_reagent(d, store, objects).is_some() {
         0x5c
     } else {
         return false;
@@ -615,13 +613,13 @@ pub(crate) fn reagent_totem_refusal(
 pub(super) fn first_missing_totem(
     d: &benilla_formats::SpellDisplay,
     store: &ObjectStore,
-    items: &crate::items::Items,
+    objects: &crate::net::Objects,
 ) -> Option<u32> {
     d.totems
         .iter()
         .copied()
         .filter(|&t| t != 0)
-        .find(|&t| count_of(&store.0, items, t, InventoryScope::CARRIED) == 0)
+        .find(|&t| count_of(&store.0, objects, t, InventoryScope::CARRIED) == 0)
 }
 
 /// The first reagent slot whose owned count falls short — the `0x6e4000` reagent loop's failing
@@ -629,13 +627,13 @@ pub(super) fn first_missing_totem(
 pub(super) fn first_short_reagent(
     d: &benilla_formats::SpellDisplay,
     store: &ObjectStore,
-    items: &crate::items::Items,
+    objects: &crate::net::Objects,
 ) -> Option<u32> {
     d.reagents
         .iter()
         .copied()
         .filter(|&(id, _)| id != 0)
-        .find(|&(id, n)| count_of(&store.0, items, id, InventoryScope::CARRIED) < n)
+        .find(|&(id, n)| count_of(&store.0, objects, id, InventoryScope::CARRIED) < n)
         .map(|(id, _)| id)
 }
 
@@ -817,7 +815,7 @@ mod ui_error_tests {
     }
 
     /// The RUNTIME leg on the real data (the `cast_fail`/mount pattern): every GlobalStrings
-    /// key the lock-refusal toasts (decision 0545, wow-re cursor-system.md §8.8) and the totem
+    /// key the lock-refusal toasts (decision 0545, the USE sender `0x5f33e0`) and the totem
     /// fill can emit resolves in the shipped 1.12 `GlobalStrings.lua`, with the exact ref-quoted
     /// formats — the guard against a typo'd key silently swallowing the red line. Skips without
     /// client data.
@@ -994,7 +992,7 @@ mod attack_actor_tests {
         ] {
             assert!(!g(key).unwrap_or_default().is_empty(), "{key} missing");
         }
-        // The one wow-re quotes from the file, as a spot check that the ids line up with the keys.
+        // One key's text quoted from the file, as a spot check that the ids line up with the keys.
         assert_eq!(g("ERR_ATTACK_DEAD").unwrap(), "Can't attack while dead.");
     }
 }
@@ -1010,6 +1008,12 @@ mod totem_reagent_tests {
         ObjectStore(ObjectFields::default())
     }
 
+    /// The object index the count walks read — nothing streamed, which is the empty-bags pole
+    /// every case here is graded at (2334).
+    fn objects() -> crate::ui_items::TestObjects {
+        crate::ui_items::TestObjects::new()
+    }
+
     fn spell(totems: [u32; 2], reagents: [(u32, u32); 8]) -> SpellDisplay {
         SpellDisplay {
             totems,
@@ -1024,7 +1028,7 @@ mod totem_reagent_tests {
     /// `IsActivePlayer` gate) — the cast then goes out for the server to judge.
     #[test]
     fn missing_materials_refuse_with_the_refs_reasons() {
-        let items = crate::items::Items::default();
+        let mut objs = objects();
         let st = store();
         let mining = spell([2901, 0], [(0, 0); 8]);
         let mut errors = CastErrors::default();
@@ -1032,7 +1036,7 @@ mod totem_reagent_tests {
             2575,
             Some(&mining),
             Some(&st),
-            &items,
+            &objs.get(),
             &mut errors
         ));
         assert_eq!(errors.0.as_slice(), &[CastFail::local(2575, 0x78)]);
@@ -1045,7 +1049,7 @@ mod totem_reagent_tests {
             130,
             Some(&slow_fall),
             Some(&st),
-            &items,
+            &objs.get(),
             &mut errors
         ));
         assert_eq!(errors.0.as_slice(), &[CastFail::local(130, 0x5c)]);
@@ -1056,7 +1060,7 @@ mod totem_reagent_tests {
             1,
             Some(&both),
             Some(&st),
-            &items,
+            &objs.get(),
             &mut errors
         ));
         assert_eq!(errors.0.as_slice(), &[CastFail::local(1, 0x78)]);
@@ -1067,21 +1071,21 @@ mod totem_reagent_tests {
             133,
             Some(&plain),
             Some(&st),
-            &items,
+            &objs.get(),
             &mut errors
         ));
         assert!(!reagent_totem_refusal(
             2575,
             None,
             Some(&st),
-            &items,
+            &objs.get(),
             &mut errors
         ));
         assert!(!reagent_totem_refusal(
             2575,
             Some(&mining),
             None,
-            &items,
+            &objs.get(),
             &mut errors
         ));
         assert!(errors.0.is_empty());
@@ -1091,15 +1095,15 @@ mod totem_reagent_tests {
     /// reagent (against empty bags, the first nonzero of each).
     #[test]
     fn first_failing_slot_is_named() {
-        let items = crate::items::Items::default();
+        let mut objs = objects();
         let st = store();
         let mut reagents = [(0, 0); 8];
         reagents[1] = (17056, 1);
         let d = spell([0, 7005], reagents);
-        assert_eq!(first_missing_totem(&d, &st, &items), Some(7005));
-        assert_eq!(first_short_reagent(&d, &st, &items), Some(17056));
+        assert_eq!(first_missing_totem(&d, &st, &objs.get()), Some(7005));
+        assert_eq!(first_short_reagent(&d, &st, &objs.get()), Some(17056));
         let none = spell([0, 0], [(0, 0); 8]);
-        assert_eq!(first_missing_totem(&none, &st, &items), None);
-        assert_eq!(first_short_reagent(&none, &st, &items), None);
+        assert_eq!(first_missing_totem(&none, &st, &objs.get()), None);
+        assert_eq!(first_short_reagent(&none, &st, &objs.get()), None);
     }
 }
diff --git a/crates/benilla-app/src/ui_action/feed.rs b/crates/benilla-app/src/ui_action/feed.rs
index 55113e79..64564b79 100644
--- a/crates/benilla-app/src/ui_action/feed.rs
+++ b/crates/benilla-app/src/ui_action/feed.rs
@@ -21,8 +21,8 @@
 //! instead — and [`UiErrorTexts`], the lines that arrive already resolved) into
 //! `UI_ERROR_MESSAGE`, or `UI_INFO_MESSAGE` for the yellow arm; and the stance page
 //! (`GetBonusBarOffset`) — our descriptor's
-//! shapeshift-form byte indexed into `SpellShapeshiftForm.dbc`'s BonusActionBar column, wow-re
-//! byte-verified, firing `UPDATE_BONUS_ACTIONBAR` on change.
+//! shapeshift-form byte indexed into `SpellShapeshiftForm.dbc`'s BonusActionBar column
+//! (`0x4e4fc0`), firing `UPDATE_BONUS_ACTIONBAR` on change.
 
 use crate::ui_items::{count_of, InventoryScope};
 use std::collections::{HashMap, HashSet};
@@ -44,8 +44,8 @@ use super::{
 };
 
 /// What an ITEM action shows when its icon cannot be resolved — the reference's own hardcoded
-/// literal at `0x847fe4`, returned by the item-icon resolver's failure block `0x5d8927` (wow-re
-/// `action-item-slot.md` §1/§4: exactly two engine sites binary-wide, zero Lua). Reached two ways:
+/// literal at `0x847fe4`, returned by the item-icon resolver's failure block `0x5d8927` (exactly
+/// two engine sites binary-wide, zero Lua). Reached two ways:
 /// the template hasn't answered yet (displayId 0 — the login window decision 0660 closes), or the
 /// displayId has no `ItemDisplayInfo` row at all.
 pub(super) const MISSING_ITEM_ICON: &str = "Interface\\Icons\\INV_Misc_QuestionMark";
@@ -110,10 +110,15 @@ pub(super) fn feed_actions(
     mut cast_errors: ResMut<CastErrors>,
     mut mount_errors: ResMut<MountErrors>,
     mut pet_tame_failures: ResMut<PetTameFailures>,
-    mut ui_error_keys: ResMut<UiErrorKeys>,
-    mut ui_error_texts: ResMut<UiErrorTexts>,
+    // The two client-local refusal queues as one param (the 16-SystemParam ceiling this
+    // signature already sits at): the by-KEY route (`DisplayError`) and the already-resolved
+    // TEXT route, both drained onto the same red line below.
+    ui_errors: (ResMut<UiErrorKeys>, ResMut<UiErrorTexts>),
     spells: Option<Res<Spells>>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
+    // The inventory read (2334): every count, reagent and totem question below walks the bags
+    // through it, and the weapon-icon arms resolve the equipped instance here.
+    objects: crate::net::Objects,
     items: Res<Items>,
     icons: Option<Res<ItemDisplays>>,
     sub_classes: Option<Res<crate::ui_items::ItemSubClasses>>,
@@ -127,6 +132,7 @@ pub(super) fn feed_actions(
     let Some(mut script) = script else {
         return;
     };
+    let (mut ui_error_keys, mut ui_error_texts) = ui_errors;
     let memory = memory.get(&script);
 
     // Rejected casts surface as the client's red error line (UI_ERROR_MESSAGE → the errors
@@ -170,8 +176,8 @@ pub(super) fn feed_actions(
                 // through `0x6e2380`): "Must have a **Wand** equipped", the SINGULAR DisplayName,
                 // where the spell tooltip's own requirement line takes the verbose plural. Purely a
                 // DBC read, so no query/redisplay round trip. A multi-bit mask resolves too — through
-                // ItemSubClassMask.dbc's group name, else the FIRST matching subclass (law
-                // §3-EQUIPITEM; the tooltip's twin joins instead).
+                // ItemSubClassMask.dbc's group name, else the FIRST matching subclass (the
+                // tooltip's twin at `0x52eea7` joins instead).
                 if let (0x19..=0x1b, Some(d), Some(subs)) = (reason, d, sub_classes.as_deref()) {
                     if let Some(name) = (d.equipped_item_class >= 0)
                         .then(|| {
@@ -230,12 +236,12 @@ pub(super) fn feed_actions(
                     let d = d?;
                     let failing = if reason == 0x78 {
                         self_store
-                            .and_then(|s| first_missing_totem(d, s, &items))
+                            .and_then(|s| first_missing_totem(d, s, &objects))
                             // No store to test against (a race): name the first tool at all.
                             .or_else(|| d.totems.iter().copied().find(|&t| t != 0))
                     } else {
                         self_store
-                            .and_then(|s| first_short_reagent(d, s, &items))
+                            .and_then(|s| first_short_reagent(d, s, &objects))
                             .or_else(|| d.reagents.iter().map(|&(id, _)| id).find(|&id| id != 0))
                     }?;
                     let cached = items
@@ -490,6 +496,7 @@ pub(super) fn feed_actions(
                             d,
                             sp,
                             store,
+                            &objects,
                             &items,
                             icons.as_deref(),
                             &commands,
@@ -512,7 +519,7 @@ pub(super) fn feed_actions(
                         .and_then(|t| icons.as_ref()?.catalog.get(t.display_info_id)?.icon.clone())
                         .unwrap_or_else(|| MISSING_ITEM_ICON.to_string());
                     let count = store
-                        .map(|s| count_of(&s.0, &items, button.action, InventoryScope::CARRIED))
+                        .map(|s| count_of(&s.0, &objects, button.action, InventoryScope::CARRIED))
                         .unwrap_or(0);
                     // The Count fontstring's gate — `IsConsumableAction 0x4e5250`: ammo/thrown by
                     // InventoryType, or an ON_USE block with NEGATIVE charges
@@ -525,11 +532,11 @@ pub(super) fn feed_actions(
                     (Some(texture), count, consumable)
                 }
                 // A MACRO slot serves **the macro's own icon, never its bound spell's** — the one
-                // asymmetry in the icon resolver, byte-verified: `0x4e6a50`'s macro arm
-                // (`0x4e6bf9`) validates the slot and calls `0x4f0fd0(idx, buf, 0x104)`, the macro
-                // record's own icon-path builder, without ever touching `[rec+0x564]` (wow-re
-                // `action-spell-icon-apis.md` §3.7). Its dynamic state DOES go through the bound
-                // spell — that split is the whole design (`state`'s macro arm, decision 0983).
+                // asymmetry in the icon resolver: `0x4e6a50`'s macro arm (`0x4e6bf9`) validates the
+                // slot and calls `0x4f0fd0(idx, buf, 0x104)`, the macro record's own icon-path
+                // builder, without ever touching `[rec+0x564]`. Its dynamic state DOES go
+                // through the bound spell — that split is the whole design (`state`'s macro
+                // arm, decision 0983).
                 ACTION_KIND_MACRO => (
                     macros
                         .get(button.action as usize)
@@ -593,7 +600,7 @@ pub(super) fn feed_actions(
         for (&action, slot) in memory.pushed.iter_mut() {
             let changed = match slot.kind {
                 ACTION_KIND_ITEM => {
-                    let fresh = count_of(&store.0, &items, slot.action, InventoryScope::CARRIED);
+                    let fresh = count_of(&store.0, &objects, slot.action, InventoryScope::CARRIED);
                     let changed = fresh != slot.count;
                     if changed {
                         slot.count = fresh;
@@ -618,6 +625,7 @@ pub(super) fn feed_actions(
                                 d,
                                 sp,
                                 Some(store),
+                                &objects,
                                 &items,
                                 icons.as_deref(),
                                 &commands,
@@ -648,8 +656,8 @@ pub(super) fn feed_actions(
     }
 }
 
-/// The whole SPELL-slot icon rule — the reference's `GetActionTexture` resolver `0x4e6a50`
-/// (wow-re `action-spell-icon-apis.md` §3, §5-verified), arms in its execution order:
+/// The whole SPELL-slot icon rule — the reference's `GetActionTexture` resolver `0x4e6a50`, arms
+/// in its execution order:
 ///
 /// 1. The **pre-emptive arms** ([`auto_attack_icon`]): Attack serves the current form's face /
 ///    the main-hand weapon (`0x4e6870`), an auto-repeat shot the ranged weapon (`0x4e6990`) —
@@ -661,18 +669,19 @@ pub(super) fn feed_actions(
 /// 3. The spell's own `SpellIconID` face.
 ///
 /// The spellbook's `GetSpellTexture` (`0x4b3f50`) deliberately runs ONLY arms 1 and 3 — it never
-/// serves `ActiveIconID` (proof by exhaustion in the note). `ui_spellbook` keeps that asymmetry;
-/// do not "fix" it to match the bar.
+/// serves `ActiveIconID` (proof by exhaustion of its return paths). `ui_spellbook` keeps that
+/// asymmetry; do not "fix" it to match the bar.
 fn spell_action_icon(
     spell_id: u32,
     d: &benilla_formats::SpellDisplay,
     spells: &super::Spells,
     store: Option<&crate::net::ObjectStore>,
+    objects: &crate::net::Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     commands: &NetCommands,
 ) -> Option<String> {
-    auto_attack_icon(d, store, &spells.forms, items, icons, commands)
+    auto_attack_icon(d, store, &spells.forms, objects, items, icons, commands)
         .or_else(|| {
             store
                 .filter(|s| super::toggle::active_action_toggle(spell_id, d, s))
diff --git a/crates/benilla-app/src/ui_action/feed_tests.rs b/crates/benilla-app/src/ui_action/feed_tests.rs
index 3d953600..282a0788 100644
--- a/crates/benilla-app/src/ui_action/feed_tests.rs
+++ b/crates/benilla-app/src/ui_action/feed_tests.rs
@@ -58,6 +58,7 @@ fn app_with_food_on_the_bar() -> (App, crossbeam_channel::Receiver<ClientCommand
 
     app.insert_resource(actions)
         .init_resource::<Items>()
+        .init_resource::<crate::net::GuidIndex>()
         .init_resource::<CastErrors>()
         .init_resource::<MountErrors>()
         .init_resource::<PetTameFailures>()
@@ -283,9 +284,9 @@ fn an_unknown_entry_answers_once_and_settles() {
 /// A MACRO slot serves **the macro's own icon**, and follows an EDIT of that macro without any
 /// bar-table change at all (decision 0983).
 ///
-/// Two things are pinned. The icon rule is byte-verified: `GetActionTexture`'s macro arm
-/// (`0x4e6bf9`) builds the macro record's own icon path and never touches the bound spell
-/// (`action-spell-icon-apis.md` §3.7). And the *trigger* is the macro-table generation — the third
+/// Two things are pinned. The icon rule: `GetActionTexture`'s macro arm (`0x4e6bf9`) builds the
+/// macro record's own icon path and never touches the bound spell. And the *trigger* is the
+/// macro-table generation — the third
 /// input beside `dirty` and the item-template epoch — because renaming or re-iconing a macro moves
 /// neither of those, and gating on them alone leaves a stale icon on the bar until some unrelated
 /// edit happens to re-dirty the feed (exactly decision 0660's bug, one seam over).
@@ -310,6 +311,7 @@ fn a_macro_slot_shows_the_macros_own_icon_and_follows_an_edit() {
     actions.dirty = true;
     app.insert_resource(actions)
         .init_resource::<Items>()
+        .init_resource::<crate::net::GuidIndex>()
         .init_resource::<CastErrors>()
         .init_resource::<MountErrors>()
         .init_resource::<PetTameFailures>()
@@ -415,6 +417,7 @@ fn a_macro_slot_shows_the_macros_own_icon_and_follows_an_edit() {
 /// notice belongs here, red — and its `SMSG_AREA_TRIGGER_MESSAGE` sibling here, yellow.
 #[test]
 fn pre_resolved_lines_land_on_the_errors_frame_in_the_arms_colour() {
+    benilla_formats::wow_data_or_skip!();
     let (mut app, _rx) = app_with_food_on_the_bar();
     {
         let mut script = app.world_mut().non_send_resource_mut::<UiScript>();
@@ -523,6 +526,7 @@ fn a_pets_refused_cast_writes_no_combat_log_line() {
             ..Spells::empty_for_tests()
         })
         .init_resource::<Items>()
+        .init_resource::<crate::net::GuidIndex>()
         .init_resource::<MountErrors>()
         .init_resource::<PetTameFailures>()
         .init_resource::<UiErrorKeys>()
diff --git a/crates/benilla-app/src/ui_action/mod.rs b/crates/benilla-app/src/ui_action/mod.rs
index 256dd71e..97ca9c49 100644
--- a/crates/benilla-app/src/ui_action/mod.rs
+++ b/crates/benilla-app/src/ui_action/mod.rs
@@ -12,15 +12,16 @@
 //!   checked/flash — the per-frame half, fed after the identity half so a fresh slot's first state
 //!   push lands the same frame.
 //! - **Outward — use** ([`drain::drain_action_uses`]): a queued `UseAction(n)` becomes wire — a
-//!   spell through the one cast-send path ([`cast_send`]), the auto-attack through
+//!   spell through the one cast-send path ([`crate::spell::CastLadder`]), the auto-attack through
 //!   `CMSG_ATTACKSWING`, an item through the two-stage equip-vs-use law ([`drain::item_action_route`],
 //!   decision 0666).
 //! - **Outward — set** ([`drain::drain_action_sets`]): the cursor seam's `PickupAction`/
 //!   `PlaceAction` mutations become `CMSG_SET_ACTION_BUTTON` sends, one per queued entry.
 //!
-//! The supporting law sits alongside: [`cast_target`] (which unit a cast binds), [`cast_fail`] +
-//! [`errors`] (the red error line's two layers), [`usable`] (the castability walk the stance bar
-//! shares), [`weapon_icon`] (the auto-attack's borrowed weapon icon).
+//! The supporting law sits alongside: [`cast_fail`] + [`errors`] (the red error line's two
+//! layers) and [`weapon_icon`] (the auto-attack's borrowed weapon icon). The cast ladder itself —
+//! the target bind, the validator's rungs, the usable walk, the targeting cursor — is the spell's
+//! ([`crate::spell`], decision 2330); this module is one of its callers.
 
 use std::collections::{BTreeSet, HashMap};
 
@@ -34,8 +35,6 @@ use crate::ui_unit::UnitFeed;
 use benilla_assets::{AssetSet, LockRecover, WorldAssets};
 
 mod cast_fail;
-mod cast_send;
-pub(crate) mod cast_target;
 mod drain;
 #[cfg(test)]
 mod drain_tests;
@@ -44,9 +43,9 @@ mod errors;
 mod feed;
 #[cfg(test)]
 mod feed_tests;
+mod net;
 mod ranks;
 mod state;
-pub(crate) mod targeting;
 pub(crate) mod toggle;
 mod weapon_icon;
 
@@ -60,43 +59,14 @@ mod weapon_icon;
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct CooldownEvents;
 
-// The one cast path, and the only way in: every caster surface takes [`CastLadder`] as a single
-// SystemParam and commits through [`CastCommit`] — `send_spell_cast` itself is private to
-// `cast_send`, so a second send path cannot be written by accident (decision 0914).
-pub(crate) use cast_send::{CastCommit, CastLadder};
-pub(crate) use cast_target::AutoSelfCast;
-
-/// `autoSelfCast`'s change callback (decision 2303): a flag.
-pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut auto: ResMut<AutoSelfCast>) {
-    if ev.is("autoSelfCast") {
-        auto.0 = ev.flag();
-    }
-}
 pub(crate) use errors::{
     attack_actor_blocked, attack_actor_refusal, keyed_line, keyed_line_s, reagent_totem_refusal,
     show_messages, ui_error_text, CastErrors, CastFail, Caster, FillArg, MessageSink, MountErrors,
     PetTameFailures, Shown, UiError, UiErrorKeys, UiErrorTexts,
 };
-// `pub(crate)`: the requirement validator's mounted block is ONE gate in the reference
-// (`0x6094f0` @ `0x609c6c`) sitting under the ONE cast entry `TryCast 0x6e4b60` — but benilla still
-// has cast sends outside [`CastLadder`]: the world click's skin cast, the corpse insignia cast and
-// the GameObject opener (decisions 0552/0914). Each of them reaches TryCast in the reference
-// (`0x5f05e0 → 0x6e5a90 → 0x6e4b60`; `0x5f35c0 → 0x6e5a90 → 0x6e4b60`), so each of them must ask
-// this question — the same reason `reagent_totem_refusal` above is already exported. Exporting the
-// predicate is the honest interim; the ladder refactor that would retire it is 0914's, not 1851's.
-pub(crate) use state::cast_mounted_refusal;
-// `pub(crate)`: the target chain registers the cursor pre-empt + the click commit, and the
-// spellbook/stance/craft drains thread the mode through the one cast-send path (decision 0792).
-// `TargetingWants` travels with it because the chain also holds a *seam-specific* consumer — the
-// ground reticle, which draws for the location word alone (decision 0943).
-pub(crate) use targeting::{ground_cast_radius, SpellTargeting, TargetingWants};
 // `pub(crate)`: the spellbook shows the same borrowed weapon icon its bar buttons do, pre-resolved
 // once per page (decisions 0230/0231).
 pub(crate) use weapon_icon::{melee_auto_attack_icon, ranged_weapon_icon};
-// `pub(crate)`: the stance bar's `isCastable` IS this walk (`GetShapeshiftFormInfo`'s fourth
-// return runs `0x6e3d60`, wow-re shapeshift-bar-api.md) — `crate::ui_shapeshift` calls it with
-// the same ctx shape the state feed builds.
-pub(crate) mod usable;
 
 /// The auto-attack pseudo-spell (`Attack`, every character's slot-1 default): not a cast — it
 /// toggles melee via the attack-swing pair. The USE path (`CMSG_ATTACKSWING`) keys on this id; the
@@ -135,32 +105,11 @@ pub(crate) struct PlayerActions {
     pub dirty: bool,
 }
 
-/// The live auto-repeat spell — the client's autorepeat key `0xceac30` (wow-re `wave-cast.md`:
-/// written at the local cast-send for `AttributesEx2 & 0x20` spells, cleared by
-/// `SMSG_CANCEL_AUTO_REPEAT`'s `0x6ea080` and by a matching cast-fail). Distinct from the sticky
-/// `creature_anim::AutoRepeatArmed` (the Load/Hold idle gate, never cleared): THIS one is what
-/// `IsAutoRepeatAction` and the button flash read, and it goes out when the shooting stops.
-#[derive(Resource, Default)]
-pub(crate) struct AutoRepeatActive(pub Option<u32>);
-
-/// **The `modalNextSpell` chain's queue** — spells the *client* casts on its own, one per
-/// `SMSG_CAST_RESULT` that names a spell with a non-zero `Spell.dbc` column 38
-/// ([`benilla_formats::SpellDisplay::modal_next_spell`]). Written by the net drain's
-/// `cast_result`, drained through the one cast path by [`drain::drain_chain_casts`].
-///
-/// It exists because the reference's chain runs *inside* `HandleCastResult 0x6e7330`
-/// (`0x6e74aa call 0x6e5a90` → `TryCast`) and ours cannot: the net-apply drain and
-/// [`CastLadder`] want the same half-dozen resources, so a direct call is a Bevy param conflict.
-/// A one-frame queue is the seam — and it keeps the rule that nothing sends a cast except the
-/// ladder.
-#[derive(Resource, Default)]
-pub(crate) struct ChainCasts(pub(crate) Vec<u32>);
-
 /// **The world right-click's GameObject-opener queue** — the lock chain's resolved action, carried
 /// one frame to the one cast path (decision 2199).
 ///
-/// It exists for exactly the reason [`ChainCasts`] does, and no other: the right-click system
-/// ([`crate::target::click::act_on_right_click`]) and [`CastLadder`] want the same half-dozen
+/// It exists because the right-click system ([`crate::target::click::act_on_right_click`]) and
+/// [`crate::spell::CastLadder`] want the same half-dozen
 /// resources, so the click cannot call the ladder in place — a resource reachable twice from one
 /// system is a `B0002` panic on the first live frame. A one-frame queue is the seam, and it keeps
 /// the rule that **nothing sends a cast except the ladder**.
@@ -197,7 +146,7 @@ pub(crate) enum GoOpener {
 pub(crate) struct Spells {
     pub(crate) catalog: SpellCatalog,
     /// Form id → the `SpellShapeshiftForm.dbc` row: **BonusActionBar** (the client's own paging
-    /// map, wow-re byte-verified: `GetBonusBarOffset` reads a cached copy of exactly this
+    /// map: `GetBonusBarOffset 0x4e7620` reads a cached copy of exactly this
     /// lookup) + **flags1** (the form gate's stance bit, [`state`]'s usable walk; the
     /// toggle-cancel block bit, `crate::ui_shapeshift`'s drain).
     pub(crate) forms: std::collections::HashMap<u32, benilla_formats::ShapeshiftForm>,
@@ -214,13 +163,12 @@ pub(crate) struct Spells {
 }
 
 impl Spells {
-    /// The resolved cast time, ms — `GetCastTime 0x6e3340`'s level-scaled walk (wow-re
-    /// `wave-cooldown.md`/`moving-cast-gate.md`, byte-verified): `CastingTimeIndex` resolves the
-    /// [`Self::cast_times`] row, `base + perLevel·(casterLevel − baseLevel)` floors to the
-    /// row's minimum (row 1, the all-zero instant sentinel, resolves 0). The level term keys on
+    /// The resolved cast time, ms — `GetCastTime 0x6e3340`'s level-scaled walk: `CastingTimeIndex`
+    /// resolves the [`Self::cast_times`] row, `base + perLevel·(casterLevel − baseLevel)` floors to
+    /// the row's minimum (row 1, the all-zero instant sentinel, resolves 0). The level term keys on
     /// the `SpellRec+0x70` column ([`SpellDisplay::base_level`]). Spell-mod op `0xa`
     /// (SPELLMOD_CASTING_TIME) is still unread here — the tables themselves are live
-    /// ([`crate::spell_mods`]), only this consumer is not wired to them, so a talent-shortened
+    /// (`crate::spell::mods`), only this consumer is not wired to them, so a talent-shortened
     /// cast still shows its untalented length.
     /// A missing row reads 0 (instant), like a failed catalog load everywhere else.
     pub(crate) fn cast_time_ms(
@@ -257,9 +205,8 @@ impl Spells {
 /// `[0xb700e8]` — and the unlearn path `0x4b2c50` zeroes whichever global named that spell.
 ///
 /// The world cursor's skin leg then reads `[0xb700e4 + 4×isPlayerTarget]` as a hard precondition
-/// (wow-re `cursor-system.md` §3, the skin/insignia row): **a corpse flagged `UNIT_FLAG_SKINNABLE`
-/// shows no skin cursor at all to a player who never learned Skinning.** Without it the ladder
-/// offers the knife to everyone, which is what the channel reported.
+/// (`0x482589`): **a corpse flagged `UNIT_FLAG_SKINNABLE` shows no skin cursor at all to a player
+/// who never learned Skinning.** Without it the ladder offers the knife to everyone.
 #[derive(Resource, Default)]
 pub(crate) struct LearnedAbilities {
     /// `[0xb700e4]` — our known `SPELL_EFFECT_SKINNING` spell (creature skinning), `None` if we
@@ -282,7 +229,7 @@ pub(crate) struct LearnedAbilities {
 const SPELL_EFFECT_SKIN_PLAYER_CORPSE: u32 = 0x74;
 
 /// `SpellEffects` value `0x65` (101) — `SPELL_EFFECT_FEED_PET`, the effect the reference tests at
-/// learn time to latch `[0xcecad8]` (wow-re `ui/scratch/item-target-cursor-and-dropitemonunit.md`).
+/// learn time to latch `[0xcecad8]` (`0x5e9e42`).
 /// Feed Pet 6991 is the only shipped row carrying it.
 const SPELL_EFFECT_FEED_PET: u32 = 0x65;
 
@@ -364,7 +311,7 @@ pub(crate) struct UiActionPlugin;
 
 impl Plugin for UiActionPlugin {
     fn build(&self, app: &mut App) {
-        app.add_observer(on_cvar);
+        net::register(app);
         app.init_resource::<PlayerActions>()
             .init_resource::<LearnedAbilities>()
             .init_resource::<CastErrors>()
@@ -372,13 +319,7 @@ impl Plugin for UiActionPlugin {
             .init_resource::<PetTameFailures>()
             .init_resource::<UiErrorKeys>()
             .init_resource::<UiErrorTexts>()
-            .init_resource::<crate::cooldowns::Cooldowns>()
-            .init_resource::<AutoRepeatActive>()
-            .init_resource::<ChainCasts>()
             .init_resource::<GoOpenerCasts>()
-            .init_resource::<cast_target::AutoSelfCast>()
-            .init_resource::<targeting::SpellTargeting>()
-            .init_resource::<targeting::EnchantConfirmItem>()
             .add_systems(Startup, load_spells.after(AssetSet::Open))
             .add_systems(Startup, load_spell_mechanics.after(AssetSet::Open))
             .add_systems(
@@ -407,11 +348,6 @@ impl Plugin for UiActionPlugin {
                     // The T binding (0997): the attack arm's twin door, after the dispatch wrote
                     // this frame's fires.
                     drain::attack_target_binding.after(UiInput),
-                    // The `modalNextSpell` chain (1597): a hunter shot's CAST_RESULT queues
-                    // Auto Shot, and it goes out through the same ladder every other caster
-                    // takes. After the input pass like the other drains — the queue is filled by
-                    // the net drain, which runs earlier in the frame.
-                    drain::drain_chain_casts.after(UiInput),
                     // The world right-click's opener (2199), beside the chain cast and for the
                     // same reason: the click resolved it, the ladder sends it. After the input
                     // pass like the other drains — the queue is filled by the target chain,
@@ -423,19 +359,6 @@ impl Plugin for UiActionPlugin {
                     track_learned_abilities
                         .in_set(UnitFeed)
                         .after(feed::feed_actions),
-                    // The targeting mode's ESC-chain halves (decision 0792): the state push
-                    // rides the feeds (before the input pass runs `ToggleGameMenu`), the
-                    // trigger drain follows it — same frame, so an ESC's cancel lands before
-                    // the next frame's cursor drive reads the mode. The cursor pre-empt, the
-                    // right-press cancel, and the click commit register in the TARGET chain
-                    // (ordering against the classifier and the select click is theirs to own).
-                    targeting::feed_targeting_to_vm.in_set(UnitFeed),
-                    targeting::drain_stop_targeting.after(UiInput),
-                    // The item half's commit (decision 0923) — the bag / paper-doll click seam's
-                    // `0x495d60`. A UI drain like the others: after the input pass, so a click
-                    // this frame binds this frame. It is deliberately NOT in the target chain —
-                    // the clicks it consumes never reach the world.
-                    targeting::commit_item_cast_on_pick.after(UiInput),
                 ),
             );
     }
diff --git a/crates/benilla-app/src/ui_action/net.rs b/crates/benilla-app/src/ui_action/net.rs
new file mode 100644
index 00000000..24b1e6c1
--- /dev/null
+++ b/crates/benilla-app/src/ui_action/net.rs
@@ -0,0 +1,34 @@
+//! The action bar's packet handler (in the net handler table since 2322, moved out of the drain's
+//! mount arm file) — the (dis)mount attempt's result code (decision 0441 P1) onto the mount error
+//! line. The flourish half of that arc is [`crate::creature_anim::net`]'s.
+
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::MountErrors;
+use crate::net::NetHandlerApp;
+
+/// Register the handler — called from [`super::UiActionPlugin`].
+pub(super) fn register(app: &mut App) {
+    app.net_handler(SessionEventKind::MountResult, on_mount_result);
+}
+
+fn on_mount_result(In(ev): In<SessionEvent>, mut errors: ResMut<MountErrors>) {
+    if let SessionEvent::MountResult { mount, code } = ev {
+        mount_result(mount, code, &mut errors);
+    }
+}
+
+/// `SMSG_MOUNTRESULT`/`SMSG_DISMOUNTRESULT` — OK is silent in the reference (10 mounting,
+/// 3 dismounting); a failure queues the red error line (`ui_action::mount_result_key` — resolved
+/// against the VM's GlobalStrings at drain).
+fn mount_result(mount: bool, code: u32, errors: &mut MountErrors) {
+    let ok = if mount { code == 10 } else { code == 3 };
+    if !ok {
+        info!(
+            "net: {}mount refused (code {code})",
+            if mount { "" } else { "dis" }
+        );
+        errors.0.push((mount, code));
+    }
+}
diff --git a/crates/benilla-app/src/ui_action/state.rs b/crates/benilla-app/src/ui_action/state.rs
index 088f7d33..7d7e0e42 100644
--- a/crates/benilla-app/src/ui_action/state.rs
+++ b/crates/benilla-app/src/ui_action/state.rs
@@ -1,8 +1,7 @@
 //! The per-action **dynamic-state feed** (decision 0137 phase 4) — the app-side computation
 //! behind the engine's `IsUsableAction`/`IsActionInRange`/`IsCurrentAction`/`GetActionCooldown`
 //! family: each occupied action slot's [`ActionState`], recomputed per frame, diff-pushed into
-//! the VM, with the reference client's own event edges fired on the transitions the 2026-07-10
-//! wow-re §5 byte-mapped (`system/ui/scratch/action-button-state-api.md`):
+//! the VM, with the reference client's own event edges fired on these transitions:
 //!
 //! - a cooldown-store change → `ACTIONBAR_UPDATE_COOLDOWN` + `SPELL_UPDATE_COOLDOWN` +
 //!   `BAG_UPDATE_COOLDOWN` (the `0x4b31b0`/`0x4f93d0` flush pair the SMSG handlers call);
@@ -15,13 +14,12 @@
 //! - the live autorepeat key's edges → `START_AUTOREPEAT_SPELL` (`0x6e5952`, at cast-send) /
 //!   `STOP_AUTOREPEAT_SPELL` (`0x6ea170`).
 //!
-//! The per-flag semantics are the §5's confirmed laws (C1–C5): `notEnoughMana` is strictly the
-//! power-cost verdict, `IsCurrentAction` keys on the engaged attack GUID / the in-flight cast id,
+//! The per-flag semantics are the reference's: `notEnoughMana` is strictly the power-cost verdict,
+//! `IsCurrentAction` (`0x4e53a0`) keys on the engaged attack GUID / the in-flight cast id,
 //! `IsAutoRepeatAction` on the `0xceac30` key, and the range test is squared distance against the
-//! byte-verified `GetMinMaxRange 0x6e3480` (its constants transcribed below). The usable pair
-//! itself is the full `IsSpellUsableNow 0x6e3d60` gate walk — [`super::usable`], the 2026-07-10
-//! §2a fold-back: reagents, forms, stealth, aura states (the Execute-family target dependence),
-//! the works.
+//! `GetMinMaxRange 0x6e3480` (its constants transcribed below). The usable pair itself is the full
+//! `IsSpellUsableNow 0x6e3d60` gate walk — [`crate::spell::usable`]: reagents, forms, stealth,
+//! aura states (the Execute-family target dependence), the works.
 
 use crate::ui_items::carried_counts;
 use std::collections::HashMap;
@@ -29,17 +27,18 @@ use std::time::Instant;
 
 use bevy::prelude::*;
 
-use benilla_formats::{SpellDisplay, SpellRange};
 use benilla_protocol::messages::{ACTION_KIND_ITEM, ACTION_KIND_MACRO, ACTION_KIND_SPELL};
 use benilla_ui::script::{ActionState, UiScript};
 
-use crate::cooldowns::Cooldowns;
 use crate::creature_anim::{Casting, Engaged};
 use crate::items::Items;
-use crate::net::{GuidIndex, NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{NetCommands, ObjectStore, SelfPlayer};
+use crate::spell::Cooldowns;
 use crate::target::Selection;
 
-use super::{usable, AutoRepeatActive, PlayerActions, Spells};
+use super::{PlayerActions, Spells};
+use crate::spell::usable;
+use crate::spell::AutoRepeatActive;
 
 /// The feed's memory: what was last pushed, and the edge detectors.
 #[derive(Default)]
@@ -52,290 +51,6 @@ pub(super) struct StateMemory {
     last_cd_trace: Option<Instant>,
 }
 
-/// The client's cast-fail reasons for the two range refusals ("Out of range." / "Target too
-/// close" in `super::cast_error_text`'s table) — what `CanTargetUnit 0x6e4440` emits when
-/// `IsTargetInRange 0x6e47b0` fails on its max² / min² compare.
-pub(super) const ERR_OUT_OF_RANGE: u8 = 0x59;
-pub(super) const ERR_TOO_CLOSE: u8 = 0x76;
-
-/// The **pre-send** range refusal — the client's `TryCast` ladder runs `CanTargetUnit 0x6e4440`
-/// → `IsTargetInRange 0x6e47b0` BEFORE `ArmCast`/`SendCast` (`wave-cast.md`, byte-verified), so
-/// an out-of-range or too-close press fails locally and the commit tail — the ranged sheath
-/// snap `0x6e5930` included — never runs. This is why a too-close Throw/Auto Shot must NOT draw
-/// the ranged weapon. Squared 3D distance against [`benilla_formats::min_max_range`]'s {min, max}: beyond max² →
-/// [`ERR_OUT_OF_RANGE`], inside a nonzero min² → [`ERR_TOO_CLOSE`]. Untestable inputs (no range
-/// row, unknown distance) pass — the server still judges the cast.
-pub(super) fn cast_range_refusal(
-    spell: &SpellDisplay,
-    row: Option<&SpellRange>,
-    self_reach: f32,
-    target_reach: Option<f32>,
-    dist_sq: Option<f32>,
-) -> Option<u8> {
-    let (min, max) = benilla_formats::min_max_range(spell, row, self_reach, target_reach)?;
-    let d2 = dist_sq?;
-    if d2 > max * max {
-        return Some(ERR_OUT_OF_RANGE);
-    }
-    if min > 0.0 && d2 < min * min {
-        return Some(ERR_TOO_CLOSE);
-    }
-    None
-}
-
-/// `PreventionType` values (`Spell.dbc` column 165): which crowd-control flag can refuse this
-/// spell locally. `0` = neither.
-const PREVENTION_SILENCE: u32 = 1;
-const PREVENTION_PACIFY: u32 = 2;
-
-/// The **crowd-control leg** of the same requirement validator `0x6094f0`, sitting **above** its
-/// mounted block (`0x609c6c`) — so a stunned mounted caster is told about the stun (decision 1904;
-/// wow-re `equipped-item-and-cc-cast-gates.md` §2.1, byte-verified). It refuses before any packet,
-/// which is why it must be local.
-///
-/// **Six arms, in the reference's order, first match wins** — 1863's fold-back recorded four:
-///
-/// | # | arm | gate | reason |
-/// |---|---|---|---|
-/// | 1 | CHARMED | `UNIT_FIELD_CHARMEDBY != 0` and the charmer is not us | `0x14` |
-/// | 2 | STUNNED | bit 18 — **no per-spell gate, every spell** | `0x64` |
-/// | 3 | SILENCED | bit 13 **and** `PreventionType == 1` | `0x60` |
-/// | 4 | PACIFIED | bit 17 **and** `PreventionType == 2` | `0x5a` |
-/// | 5 | FLEEING | bit 23 | `0x1e` |
-/// | 6 | CONFUSED | bit 22 | `0x16` |
-///
-/// The asymmetry is the finding: STUNNED, FLEEING, CHARMED and CONFUSED carry no per-spell gate at
-/// all, while SILENCED and PACIFIED run only where the spell's own `PreventionType` names them —
-/// so a silence stops casts and leaves melee abilities alone, and a pacify does the reverse.
-/// Reading `UNIT_FLAG_SILENCED` as "no casting" is the mistake this replaces.
-///
-/// **A dead caster skips all six** (`0x60980d`, a `jle` on `UNIT_FIELD_HEALTH`).
-///
-/// This ladder is **TryCast-only** — one caller, no address-takes — so a button does **not** grey
-/// while stunned, silenced or pacified: it refuses on the press. (Fear, confuse and charm *are*
-/// greyed, by a second copy of the same helpers inside `0x6e3d60`; that copy is not built here.)
-///
-/// Its byte-shape was nearly missed by a census twice: SILENCED's read is `f6 c4 20 test ah,0x20`,
-/// a sub-register byte-lane form with no dword immediate, invisible to an immediate scan.
-///
-/// **The exemption scan is built** (decision 1946, closing 1925's deferral): each arm first asks
-/// whether any of the caster's own auras grants immunity to what is blocking it — a scan of
-/// `UNIT_FIELD_AURA[0..47]`'s raw spell ids for an aura of the arm's own type, then
-/// [`benilla_formats::grants_immunity`] on each match. A hit **lifts** the refusal; a rejection
-/// names the blocking mechanic and turns the arm's own reason into `0x8d`. Each arm scans for a
-/// different set of aura types — charm `{6, 177, 2}`, stun `{12}`, silence `{27, 12, 60}`, pacify
-/// `{25, 12, 60}`, fear `{7}`, confuse `{5}` — and those sets are the reference's, not a family
-/// resemblance.
-pub(crate) fn cast_cc_refusal(
-    unit_flags: u32,
-    health: Option<u32>,
-    charmed_by_other: bool,
-    spell: Option<&SpellDisplay>,
-    exempt: &mut impl FnMut(&[u32]) -> benilla_formats::CcExemption,
-) -> Option<(u8, Option<u32>)> {
-    use crate::player::UNIT_FLAG_STUNNED;
-    /// `UNIT_FIELD_FLAGS` bits 13/17/22/23 (vmangos `UnitDefines.h`).
-    const UNIT_FLAG_SILENCED: u32 = 0x0000_2000;
-    const UNIT_FLAG_PACIFIED: u32 = 0x0002_0000;
-    const UNIT_FLAG_CONFUSED: u32 = 0x0040_0000;
-    const UNIT_FLAG_FLEEING: u32 = 0x0080_0000;
-
-    // The dead caster's skip (`0x60980d`): a corpse is refused by an earlier rung, not this one.
-    if health == Some(0) {
-        return None;
-    }
-    let prevention = spell.map_or(0, |d| d.prevention_type);
-    // One arm: ask its exemption scan first, and let its answer pick between silence and one of
-    // two messages. `exempt` returning `exempt: true` means one of the caster's own auras grants
-    // immunity to whatever is blocking — the arm is SKIPPED and the cast proceeds. Otherwise the
-    // refusal is `0x8d` "Can't do that while %s" when the scan named a mechanic, and the arm's own
-    // reason when it did not (decision 1946).
-    let mut arm = |aura_types: &[u32], own_reason: u8| -> Option<(u8, Option<u32>)> {
-        let scan = exempt(aura_types);
-        if scan.exempt {
-            return None;
-        }
-        Some(if scan.mechanic != 0 {
-            // The mechanic rides along as the message's `%s` — the one client-LOCAL refusal that
-            // carries an argument word (decision 1948).
-            (REASON_PREVENTED_BY_MECHANIC, Some(scan.mechanic))
-        } else {
-            (own_reason, None)
-        })
-    };
-
-    if charmed_by_other {
-        if let Some(r) = arm(&[6, 177, 2], 0x14) {
-            return Some(r);
-        }
-    }
-    if unit_flags & UNIT_FLAG_STUNNED != 0 {
-        if let Some(r) = arm(&[12], 0x64) {
-            return Some(r);
-        }
-    }
-    if unit_flags & UNIT_FLAG_SILENCED != 0 && prevention == PREVENTION_SILENCE {
-        if let Some(r) = arm(&[27, 12, 60], 0x60) {
-            return Some(r);
-        }
-    }
-    if unit_flags & UNIT_FLAG_PACIFIED != 0 && prevention == PREVENTION_PACIFY {
-        if let Some(r) = arm(&[25, 12, 60], 0x5a) {
-            return Some(r);
-        }
-    }
-    if unit_flags & UNIT_FLAG_FLEEING != 0 {
-        if let Some(r) = arm(&[7], 0x1e) {
-            return Some(r);
-        }
-    }
-    if unit_flags & UNIT_FLAG_CONFUSED != 0 {
-        if let Some(r) = arm(&[5], 0x16) {
-            return Some(r);
-        }
-    }
-    None
-}
-
-/// `SPELL_FAILED_PREVENTED_BY_MECHANIC` — "Can't do that while %s", `%s` being the blocking aura's
-/// `SpellMechanic.dbc` name. Every crowd-control arm carries this **as well as** its own reason,
-/// and which one appears is decided by whether the exemption scan named a mechanic.
-const REASON_PREVENTED_BY_MECHANIC: u8 = 0x8d;
-
-/// The **pre-send** mounted refusal (decision 0481) — the requirement validator `0x6094f0`'s
-/// mounted block (`0x609c6c`, wow-re `mounted-action-gate.md` §5): a live
-/// `UNIT_FIELD_MOUNTDISPLAYID` refuses the cast with reason `0x39` ("You are mounted") unless
-/// the spell carries Attributes bit 24 (`0x01000000`, castable-while-mounted — the exemption
-/// test at `0x609c6f`, the exact vmangos `SPELL_ATTR_ALLOW_WHILE_MOUNTED` mirror). A spell
-/// with no loaded record has no exemption to claim — the gate holds (the ref always has the
-/// record; refusing without data errs toward the ref's visible behavior). The sibling
-/// mount-REQUIRED gate (reason 0x53, `0x609c05`) is recorded but unbuilt — no 1.12 player spell
-/// exercises it. It is **two-armed** like the water pair below, not the single `+0x5c & 0x40`
-/// read this comment used to claim: arm A is `AuraInterruptFlags & 0x40` (the `cl` at
-/// `0x609c05` is the untouched low byte of `ecx = [esi+0x58]`, loaded 0x104 bytes earlier for
-/// the unsheathed leg), arm B is `ChannelInterruptFlags & 0x40` at `0x609c3a` — corrected by
-/// the 1063 §5 in wow-re `mounted-action-gate.md`. Note the plain mounted gate above is NOT in
-/// that family: it is single-armed on `Attributes`.
-pub(crate) fn cast_mounted_refusal(mounted: bool, spell: Option<&SpellDisplay>) -> bool {
-    mounted && spell.is_none_or(|d| d.attributes & 0x0100_0000 == 0)
-}
-
-/// The interrupt-flag water pair — the two bits that say *which side of the surface this aura
-/// can live on*: `0x80` cancels it on ENTERING water, `0x100` on LEAVING it (vmangos
-/// `AURA_INTERRUPT_UNDER_WATER_CANCELS` / `AURA_INTERRUPT_ABOVE_WATER_CANCELS`, bits 7/8). The
-/// requirement validator reads the same pair to refuse the *cast* whose aura could not survive
-/// the caster's current side.
-const INTERRUPT_UNDER_WATER: u32 = 0x80;
-const INTERRUPT_ABOVE_WATER: u32 = 0x100;
-
-/// `AttributesEx & (IS_CHANNELED 0x4 | IS_SELF_CHANNELED 0x40)` — the gate on **arm B** of every
-/// leg in this family (byte-verified `0x609d6a`/`0x609db1`). A channeled spell's requirement
-/// bits live in its CHANNEL column, so the validator reads that column too — but only for a
-/// spell that actually channels, which is what keeps Summon Baby Shark 25849 (`Channel 0x100`,
-/// `AttributesEx 0`) out of the gate.
-const ATTR_EX_CHANNELED: u32 = 0x44;
-
-/// `SPELL_FAILED_ONLY_ABOVEWATER` — "Cannot use while swimming".
-pub(super) const ERR_ONLY_ABOVEWATER: u8 = 0x50;
-/// `SPELL_FAILED_ONLY_UNDERWATER` — "Can only use while swimming".
-pub(super) const ERR_ONLY_UNDERWATER: u8 = 0x58;
-
-/// The **pre-send** water refusal (decisions 1056 + 1063) — the requirement validator
-/// `0x6094f0`'s environment block `0x609d33–0x609de2`, byte-carved by the wow-re §5 trio
-/// (`system/spell/scratch/water-cast-gate.md`). It sits after the mounted/posture/day/night
-/// legs and before the moving gate (`0x609de3`), which is where the ladder runs it — so a druid
-/// standing on land is refused **before** the form gate `0x612480` ever evaluates.
-///
-/// One gate, two faces, and each face has **two arms** reading the same bit in two columns:
-///
-/// | reason | bit | arm A — `AuraInterruptFlags` (+0x58) | arm B — `ChannelInterruptFlags` (+0x5c), if channeled |
-/// |---|---|---|---|
-/// | [`ERR_ONLY_UNDERWATER`] `0x58` | `0x100` | `0x609d36` / swim `0x609d46` | `0x609d6f` / swim `0x609d7b` |
-/// | [`ERR_ONLY_ABOVEWATER`] `0x50` | `0x80` | `0x609da4` / swim `0x609dac` | `0x609db5` / swim `0x609dc2` |
-///
-/// The swimming state is `[[caster+0x118]+0x40] & 0x200000` — the same wire-layout movement word
-/// the moving gate reads, four times over, twice in each face.
-///
-/// **Arm B is not dead code, and leaving it out is visibly wrong**: Fishing rank 1 (7620)
-/// carries `AuraInterruptFlags 0x80`, but ranks 2–4 (7731/7732/18248) carry **zero** and reach
-/// the gate only through their `ChannelInterruptFlags 0x3cac`. Arm A alone would refuse rank 1
-/// mid-swim and let its own upgrades through.
-///
-/// What the two bits actually select in the 5875 data: `0x80` is 245 rows — every mount, Travel
-/// Form, the campfires, all of Food/Drink (`0x40080`), Fishing — and `0x100` is exactly five:
-/// Aquatic Form 1066, the Lava/Slime swim auras 16455/16456, Master Angler 24346/24347.
-///
-/// **No exemption skips this block** (every jump into the run was enumerated) — unlike the
-/// mounted gate's `Attributes` bit 24. And the gate must be LOCAL: vmangos's `CheckCast` gates
-/// water only on `SPELL_AURA_MOUNTED` (`Spell.cpp:6379`), so it happily grants a druid aquatic
-/// form on dry cobblestone (ledger B176, with the screenshot to prove it). An uncataloged spell
-/// passes, like every other data-driven rung on this ladder.
-///
-/// The legs are evaluated `0x58` before `0x50`, the binary's own order; they are mutually
-/// exclusive on the swim bit, so the order is fidelity, not behaviour.
-pub(super) fn cast_water_refusal(move_flags_word: u32, spell: Option<&SpellDisplay>) -> Option<u8> {
-    let d = spell?;
-    let swimming = move_flags_word & crate::creature_anim::move_flags::SWIMMING != 0;
-    // Arm A always; arm B only for a spell that actually channels.
-    let requires = |bit: u32| {
-        d.aura_interrupt_flags & bit != 0
-            || (d.attributes_ex & ATTR_EX_CHANNELED != 0 && d.channel_interrupt_flags & bit != 0)
-    };
-    if !swimming && requires(INTERRUPT_ABOVE_WATER) {
-        return Some(ERR_ONLY_UNDERWATER);
-    }
-    if swimming && requires(INTERRUPT_UNDER_WATER) {
-        return Some(ERR_ONLY_ABOVEWATER);
-    }
-    None
-}
-
-/// The AuraInterruptFlags-space MOVING|TURNING pair (`0x18`) — the moving gate's
-/// "movement would matter anyway" arms test it on BOTH `AuraInterruptFlags` (+0x58) and
-/// `ChannelInterruptFlags` (+0x5c), byte-verified at `0x609e0e`/`0x609e1c`.
-const AURA_INTERRUPT_MOVING_TURNING: u32 = 0x18;
-
-/// The **pre-send** moving refusal (decision 0862) — the requirement validator `0x6094f0`'s
-/// moving block (`0x609de3–0x609e48`; the sole client-local emitter of reason `0x2e` "Can't do
-/// that while moving". wow-re `moving-cast-gate.md`, §5 byte-verified): a press while the
-/// caster's live CMovement flags carry any of {forward, backward, strafe L/R, JUMPING} refuses
-/// locally — no packet, no cast bar, no GCD. Without it, vmangos *accepts* the cast (its
-/// CheckCast moving-reject covers only autorepeat/sit-still spells, `Spell.cpp:5432`) and then
-/// `Spell::update`'s 0.5-yd movement interrupt kills it — the start-then-cancel grief this gate
-/// exists to prevent. The full reject condition, gate for gate:
-///
-/// - **entry**: `InterruptFlags & 0x1` (movement-interruptible — instants without it pass);
-/// - **the movement word**: the WIRE `MovementFlags` layout (`[unit+0x9a8]+0x40`), mask
-///   `0x200f` = forward|backward|strafe + JUMPING — turning and pitch are outside it, and so is
-///   FALLINGFAR (`0x4000`; the client has NO falling/Stuck exemption — that's vmangos-only);
-/// - **exemption**: an auto-repeat spell (`AttributesEx2 & 0x20` — Auto Shot, Shoot) never
-///   refuses, whatever else it carries;
-/// - **would movement matter**: a nonzero resolved cast time ([`super::Spells::cast_time_ms`]),
-///   OR the [`AURA_INTERRUPT_MOVING_TURNING`] bits on the aura/channel interrupt columns — the
-///   OR-arms are how a zero-cast-time *channel* is still refused at initiation.
-///
-/// An uncataloged spell passes (every record-read above needs the row; the ladder's other
-/// data-driven legs — cooldown, GCD, range — share the disposition, and the server's own
-/// interrupt stays the safety net). In the validator's order this sits after the mounted block
-/// and before the shapeshift-form leg (`0x609e50`), which is where [`super::send_spell_cast`]
-/// runs it.
-pub(super) fn cast_moving_refusal(
-    move_flags_word: u32,
-    cast_time_ms: u32,
-    spell: Option<&SpellDisplay>,
-) -> bool {
-    use crate::creature_anim::move_flags;
-    // The verified 0x200f: ANY_MOVE (0xf) | FALLING (0x2000), in our identical wire layout.
-    const MOVING_MASK: u32 = move_flags::ANY_MOVE | move_flags::FALLING;
-    let Some(d) = spell else { return false };
-    d.interrupt_flags & crate::ui_cast::SPELL_INTERRUPT_MOVEMENT != 0
-        && move_flags_word & MOVING_MASK != 0
-        && !d.auto_repeat()
-        && (cast_time_ms != 0
-            || d.aura_interrupt_flags & AURA_INTERRUPT_MOVING_TURNING != 0
-            || d.channel_interrupt_flags & AURA_INTERRUPT_MOVING_TURNING != 0)
-}
-
 /// What a slot *is* once the MACRO indirection is applied — the reference's slot→spell resolver
 /// `0x4e5a50` plus the leg of the usable compute `0x4e5050` that reads its zero (decision 1636).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -359,9 +74,9 @@ enum SlotResolve {
 ///
 /// Every `Is*Action`/`GetActionCooldown` binding routes through the one slot→spell resolver
 /// `0x4e5a50`, whose MACRO arm resolves the macro record and returns `[rec+0x564]` as the slot's
-/// spell id (wow-re `action-spell-icon-apis.md` §2, VERIFIED). So from here down, a macro that
-/// casts Fireball simply *is* the Fireball slot. `GetActionTexture` is the deliberate exception —
-/// its macro arm keeps the macro's own icon (`super::feed`).
+/// spell id. So from here down, a macro that casts Fireball simply *is* the Fireball slot.
+/// `GetActionTexture` is the deliberate exception — its macro arm keeps the macro's own icon
+/// (`super::feed`).
 ///
 /// The zero is NOT "nothing to report" (0983's reading — B340's grey `.spawn` macro): the field
 /// is three-valued and the usable compute reads each value differently, which [`SlotResolve`]
@@ -398,16 +113,19 @@ pub(super) fn feed_action_state(
     // (decision 0983) and the talent spell-modifier tables that leg 12's cost reads through,
     // both of which ride here for the same ceiling reason.
     cast_state: (
-        Res<crate::ui_cast::PendingCast>,
-        Res<crate::ui_cast::QueuedMeleeSpell>,
-        Res<crate::ui_cast::ActiveChannel>,
-        Res<super::SpellTargeting>,
+        Res<crate::spell::PendingCast>,
+        Res<crate::spell::QueuedMeleeSpell>,
+        Res<crate::spell::ActiveChannel>,
+        Res<crate::spell::SpellTargeting>,
         Res<crate::ui_macro::MacroBoundSpells>,
-        Res<crate::spell_mods::SpellModifiers>,
+        Res<crate::spell::SpellModifiers>,
     ),
     self_q: Query<(&ObjectStore, &Transform, Has<Engaged>, Option<&Casting>), With<SelfPlayer>>,
     selection: Res<Selection>,
-    index: Res<GuidIndex>,
+    // The object lookup (2334) — the guid index this system already resolved its selection
+    // through, plus the item-store read the ITEM arms need. One param, not two: this signature
+    // sits at Bevy's 16-SystemParam ceiling.
+    objects: crate::net::Objects,
     units: Query<(&ObjectStore, &Transform), Without<SelfPlayer>>,
     factions: Option<Res<crate::target::Factions>>,
     reputations: Res<crate::net::Reputations>,
@@ -442,7 +160,7 @@ pub(super) fn feed_action_state(
     // reads this table. It used to be one whole walk per question — per reagent per spell slot,
     // per item slot — for the same bags each time (1697 item 13).
     let carried = me
-        .map(|(s, _, _, _)| carried_counts(&s.0, &items))
+        .map(|(s, _, _, _)| carried_counts(&s.0, &objects))
         .unwrap_or_default();
     let engaged = me.is_some_and(|(_, _, e, _)| e);
     let form_byte = me
@@ -455,8 +173,8 @@ pub(super) fn feed_action_state(
     // The current target's reach + squared distance (the client tests dx²+dy²+dz² — 0x6e47b0).
     let target = selection
         .guid
-        .and_then(|g| index.0.get(&g))
-        .and_then(|&e| units.get(e).ok());
+        .and_then(|g| objects.entity(g))
+        .and_then(|e| units.get(e).ok());
     let target_reach = target.map(|(s, _)| s.0.unit_combat_reach());
     let dist_sq = match (self_pos, target) {
         (Some(a), Some((_, t))) => Some(a.distance_squared(t.translation)),
@@ -473,8 +191,8 @@ pub(super) fn feed_action_state(
                 // The spell-less leg of `0x4e5050`: the macro exists, so the slot is usable —
                 // full colour on the bar — and there is no other state to compute (1636). The
                 // leg's one gate benilla does not model is `[0xb4b3e4]`, the player-control
-                // flag (wow-re `right-click-open.md` §3.1: 1 from boot, 0 only across a control
-                // loss — taxi/fear/charm); for that span the reference greys every spell-less
+                // flag (1 from boot, `0x48f626`; 0 only across a control loss — taxi/fear/charm —
+                // through `0x4958e0`); for that span the reference greys every spell-less
                 // macro and item.
                 st.usable = true;
                 fresh.insert(action, st);
@@ -498,17 +216,16 @@ pub(super) fn feed_action_state(
                     continue;
                 };
                 st.is_attack = d.is_melee_auto_attack();
-                // C2: the Attack action is "current" while auto-attack is engaged; a castable
+                // The Attack action is "current" while auto-attack is engaged; a castable
                 // spell while it is our in-flight cast OR our queued on-next-swing strike OR our
                 // running channel (the ref reads one inflight id `0xceca88` — which a queued
                 // Heroic Strike *occupies* until the swing fires it — plus the channel id
                 // `0xceac58`; our model splits the queue into its own slot, same observable) —
-                // OR the shapeshift arm (`IsCurrentAction`'s predicate `0x4e53a0` @ `0x4e5556`,
-                // wow-re `action-spell-icon-apis.md` §5): a MOD_SHAPESHIFT spell whose form ==
-                // the player's form byte reads checked. Deliberately NOT the icon's aura-scan
-                // predicate — the two are different functions in the binary and the asymmetry
-                // is load-bearing (a form granted by a different spell lights the check without
-                // swapping the icon).
+                // OR the shapeshift arm (`IsCurrentAction`'s predicate `0x4e53a0` @ `0x4e5556`):
+                // a MOD_SHAPESHIFT spell whose form == the player's form byte reads checked.
+                // Deliberately NOT the icon's aura-scan predicate — the two are different
+                // functions in the binary and the asymmetry is load-bearing (a form granted by a
+                // different spell lights the check without swapping the icon).
                 st.current = if st.is_attack {
                     engaged
                 } else {
@@ -521,7 +238,7 @@ pub(super) fn feed_action_state(
                         || (form_byte != 0 && d.shapeshift_form == Some(u32::from(form_byte)))
                 };
                 st.auto_repeat = auto_repeat.0 == Some(button.action);
-                // The full usable walk (`0x6e3d60` §2a — [`super::usable`]): reagents, combo
+                // The full usable walk (`0x6e3d60` — [`super::usable`]): reagents, combo
                 // points, forms, stealth, aura states, the bit-25 cooldown fold, and the power
                 // gate (the sole notEnoughMana writer). Target-dependent for the Execute family
                 // only. `spells` is necessarily Some here — `d` came out of it.
@@ -535,14 +252,21 @@ pub(super) fn feed_action_state(
                         carried: &carried,
                         spell_mods,
                     };
-                    let (u, oom) =
-                        usable::spell_usable(button.action, d, sp, &ctx, &items, &commands);
+                    let (u, oom) = usable::spell_usable(
+                        button.action,
+                        d,
+                        sp,
+                        &ctx,
+                        &objects,
+                        &items,
+                        &commands,
+                    );
                     st.usable = u;
                     st.not_enough_mana = oom;
                 } else {
                     st.usable = true;
                 }
-                // C4: the range verdict vs the current target; nil without one.
+                // The range verdict vs the current target (`0x4e56f0`); nil without one.
                 let row = spells.as_ref().and_then(|s| s.ranges.get(d.range_index));
                 let resolved = benilla_formats::min_max_range(d, row, self_reach, target_reach);
                 st.has_range = resolved
@@ -581,7 +305,7 @@ pub(super) fn feed_action_state(
                 st.equipped = me.is_some_and(|(s, _, _, _)| {
                     (0..19).any(|i| {
                         s.0.player_inv_slot(i)
-                            .and_then(|g| items.object(g))
+                            .and_then(|g| objects.object(g))
                             .and_then(|o| o.object_entry())
                             == Some(button.action)
                     })
@@ -590,7 +314,7 @@ pub(super) fn feed_action_state(
                 // the item's on-use spell run through the SAME `0x6e3d60` walk a spell slot
                 // takes ([`super::usable::item_usable`]). Food greys in combat from leg 8 there.
                 // No active player and the reference answers (0,0) before resolving anything
-                // (§2a P0) — which is `ActionState::default()`'s `usable`.
+                // (`0x4e5080`) — which is `ActionState::default()`'s `usable`.
                 if let Some((store, _, _, _)) = me {
                     let ctx = usable::UsableCtx {
                         store,
@@ -607,6 +331,7 @@ pub(super) fn feed_action_state(
                         count > 0 || st.equipped,
                         &ctx,
                         spells.as_deref(),
+                        &objects,
                         &items,
                         &commands,
                     );
@@ -707,67 +432,7 @@ pub(super) fn feed_action_state(
 #[cfg(test)]
 mod tests {
     use super::*;
-
-    fn spell_with_range(range_index: u32, attributes: u32) -> SpellDisplay {
-        SpellDisplay {
-            range_index,
-            attributes,
-            ..Default::default()
-        }
-    }
-
-    /// The pre-send refusal (`IsTargetInRange 0x6e47b0`'s two compares over the resolved
-    /// bounds): Auto Shot's {8, 35} row + the unit reach pad — a point-blank target refuses
-    /// TOO_CLOSE, a distant one OUT_OF_RANGE, the sweet spot passes; untestable inputs pass.
-    #[test]
-    fn cast_range_refusal_follows_the_two_compares() {
-        let d = spell_with_range(114, 0);
-        let auto_shot = SpellRange {
-            min: 8.0,
-            max: 35.0,
-            flags: 0,
-        };
-        let reach = Some(1.5);
-        // Both bounds carry the bare reach pad (self 1.5 + target 1.5): min = 11, max = 38.
-        let refuse = |d2: f32| cast_range_refusal(&d, Some(&auto_shot), 1.5, reach, Some(d2));
-        assert_eq!(refuse(3.0 * 3.0), Some(ERR_TOO_CLOSE));
-        assert_eq!(refuse(20.0 * 20.0), None);
-        assert_eq!(refuse(60.0 * 60.0), Some(ERR_OUT_OF_RANGE));
-
-        // The regression: a min-0 ranged row (Fireball/Shadow Bolt) must pass point-blank —
-        // its min never grows a reach pad — while the max compare still holds.
-        let fireball = SpellRange {
-            min: 0.0,
-            max: 35.0,
-            flags: 0,
-        };
-        let refuse = |d2: f32| cast_range_refusal(&d, Some(&fireball), 1.5, reach, Some(d2));
-        assert_eq!(refuse(0.1), None);
-        assert_eq!(refuse(60.0 * 60.0), Some(ERR_OUT_OF_RANGE));
-
-        // A melee-family row has min 0 — never TOO_CLOSE, still OUT_OF_RANGE beyond reach.
-        let melee = SpellRange {
-            min: 0.0,
-            max: 5.0,
-            flags: 1,
-        };
-        let melee_spell = spell_with_range(2, 0);
-        assert_eq!(
-            cast_range_refusal(&melee_spell, Some(&melee), 1.5, reach, Some(0.1)),
-            None
-        );
-        assert_eq!(
-            cast_range_refusal(&melee_spell, Some(&melee), 1.5, reach, Some(15.0 * 15.0)),
-            Some(ERR_OUT_OF_RANGE)
-        );
-
-        // No row / no distance: nothing to test locally — pass (the server judges).
-        assert_eq!(cast_range_refusal(&d, None, 1.5, reach, Some(1.0)), None);
-        assert_eq!(
-            cast_range_refusal(&d, Some(&auto_shot), 1.5, reach, None),
-            None
-        );
-    }
+    use benilla_formats::SpellDisplay;
 
     /// A MACRO slot resolves through its bound spell for EVERY dynamic read (decision 0983) —
     /// the `0x4e5a50` law — and the three values of `[rec+0x564]` split three ways at the usable
@@ -846,15 +511,15 @@ mod tests {
         app.insert_resource(actions)
             .insert_resource(bound)
             .init_resource::<Cooldowns>()
-            .init_resource::<crate::spell_mods::SpellModifiers>()
+            .init_resource::<crate::spell::SpellModifiers>()
             .init_resource::<crate::ui_script::UiClock>()
             .init_resource::<AutoRepeatActive>()
-            .init_resource::<crate::ui_cast::PendingCast>()
-            .init_resource::<crate::ui_cast::QueuedMeleeSpell>()
-            .init_resource::<crate::ui_cast::ActiveChannel>()
-            .init_resource::<crate::ui_action::SpellTargeting>()
+            .init_resource::<crate::spell::PendingCast>()
+            .init_resource::<crate::spell::QueuedMeleeSpell>()
+            .init_resource::<crate::spell::ActiveChannel>()
+            .init_resource::<crate::spell::SpellTargeting>()
             .init_resource::<Selection>()
-            .init_resource::<GuidIndex>()
+            .init_resource::<crate::net::GuidIndex>()
             .init_resource::<crate::net::Reputations>()
             .init_resource::<Items>()
             .insert_resource(NetCommands(tx));
@@ -918,10 +583,6 @@ mod tests {
                 },
             );
             let mut items = Items::default();
-            items.insert_object(
-                0xF0,
-                ObjectFields::from_pairs(&[(3, FOOD_ITEM), (STACK, 10)]),
-            );
             items.insert_template(
                 FOOD_ITEM,
                 Some(benilla_protocol::messages::ItemInfo {
@@ -951,18 +612,25 @@ mod tests {
                     radii: Default::default(),
                 })
                 .init_resource::<Cooldowns>()
-                .init_resource::<crate::spell_mods::SpellModifiers>()
+                .init_resource::<crate::spell::SpellModifiers>()
                 .init_resource::<crate::ui_script::UiClock>()
                 .init_resource::<AutoRepeatActive>()
-                .init_resource::<crate::ui_cast::PendingCast>()
-                .init_resource::<crate::ui_cast::QueuedMeleeSpell>()
-                .init_resource::<crate::ui_cast::ActiveChannel>()
-                .init_resource::<crate::ui_action::SpellTargeting>()
+                .init_resource::<crate::spell::PendingCast>()
+                .init_resource::<crate::spell::QueuedMeleeSpell>()
+                .init_resource::<crate::spell::ActiveChannel>()
+                .init_resource::<crate::spell::SpellTargeting>()
                 .init_resource::<Selection>()
-                .init_resource::<GuidIndex>()
+                .init_resource::<crate::net::GuidIndex>()
                 .init_resource::<crate::net::Reputations>()
                 .insert_resource(items)
                 .insert_resource(NetCommands(tx));
+            // The ten muffins, as the one index's own item entity (2334).
+            crate::items::test_spawn_item(
+                app.world_mut(),
+                0xF0,
+                ObjectFields::from_pairs(&[(3, FOOD_ITEM), (STACK, 10)]),
+                false,
+            );
             // The player: alive, with the ten muffins in backpack slot 1.
             let flags = (1u32 << 3)
                 | if in_combat {
@@ -995,494 +663,4 @@ mod tests {
             "in combat the food's on-use spell fails leg 8 and the button greys"
         );
     }
-
-    /// The mounted refusal (`0x609c6c`): a live mount blocks unless Attributes carries the
-    /// bit-24 exemption (`0x609c6f`); unmounted always passes; a missing record can claim no
-    /// exemption, so the gate holds.
-    #[test]
-    fn cast_mounted_refusal_honors_the_bit24_exemption() {
-        let plain = SpellDisplay::default();
-        let exempt = SpellDisplay {
-            attributes: 0x0100_0000,
-            ..Default::default()
-        };
-        assert!(cast_mounted_refusal(true, Some(&plain)));
-        assert!(!cast_mounted_refusal(true, Some(&exempt)));
-        assert!(!cast_mounted_refusal(false, Some(&plain)));
-        assert!(!cast_mounted_refusal(false, None));
-        assert!(cast_mounted_refusal(true, None), "no record, no exemption");
-    }
-
-    /// The water refusal (`0x609d33–0x609de2`) — both faces of the environment gate and both
-    /// arms of each face, on the real 5875 columns: Aquatic Form's `0x100` needs the SWIMMING
-    /// bit set, the mount/Travel-Form/food `0x80` needs it clear, Fishing's ranks reach it
-    /// through the CHANNEL column, and a spell carrying neither bit passes on both sides.
-    #[test]
-    fn cast_water_refusal_reads_both_sides_of_the_surface() {
-        use crate::creature_anim::move_flags as mf;
-        // Aquatic Form 1066: AuraInterruptFlags 0x100 — above-water cancels it, so the cast
-        // needs water. This is ledger B176: on land it must refuse, and it must not send.
-        let aquatic = SpellDisplay {
-            aura_interrupt_flags: 0x100,
-            ..Default::default()
-        };
-        assert_eq!(
-            cast_water_refusal(0, Some(&aquatic)),
-            Some(ERR_ONLY_UNDERWATER)
-        );
-        assert_eq!(cast_water_refusal(mf::SWIMMING, Some(&aquatic)), None);
-        // Travel Form 783 / every mount: 0x80 — entering water cancels it, so it refuses the
-        // other way round.
-        let travel = SpellDisplay {
-            aura_interrupt_flags: 0x80,
-            ..Default::default()
-        };
-        assert_eq!(
-            cast_water_refusal(mf::SWIMMING, Some(&travel)),
-            Some(ERR_ONLY_ABOVEWATER)
-        );
-        assert_eq!(cast_water_refusal(0, Some(&travel)), None);
-        // Food 433's shape (0x40080 = STANDING_CANCELS | UNDER_WATER_CANCELS) — the eating half
-        // of ledger B155 rides the same 0x80 arm.
-        let food = SpellDisplay {
-            aura_interrupt_flags: 0x4_0080,
-            ..Default::default()
-        };
-        assert_eq!(
-            cast_water_refusal(mf::SWIMMING, Some(&food)),
-            Some(ERR_ONLY_ABOVEWATER)
-        );
-        assert_eq!(cast_water_refusal(0, Some(&food)), None);
-        // ARM B (decision 1063): a CHANNELED spell's requirement bits live in its channel
-        // column. Fishing ranks 2–4's shape — AuraInterruptFlags zero, ChannelInterruptFlags
-        // 0x3cac (which carries 0x80), AttributesEx 0x21004004 (IS_CHANNELED).
-        let fishing_r2 = SpellDisplay {
-            aura_interrupt_flags: 0,
-            channel_interrupt_flags: 0x3cac,
-            attributes_ex: 0x2100_4004,
-            ..Default::default()
-        };
-        assert_eq!(
-            cast_water_refusal(mf::SWIMMING, Some(&fishing_r2)),
-            Some(ERR_ONLY_ABOVEWATER),
-            "arm A is empty here — only the channel column refuses it"
-        );
-        assert_eq!(cast_water_refusal(0, Some(&fishing_r2)), None);
-        // …and the `AttributesEx & 0x44` gate on arm B is load-bearing: Summon Baby Shark
-        // 25849's shape carries the channel bit but does not channel, so it is NOT gated.
-        let not_channeled = SpellDisplay {
-            channel_interrupt_flags: 0x100,
-            attributes_ex: 0,
-            ..Default::default()
-        };
-        assert_eq!(cast_water_refusal(0, Some(&not_channeled)), None);
-        assert_eq!(cast_water_refusal(mf::SWIMMING, Some(&not_channeled)), None);
-        // Cat Form 768 / Bear Form 5487 carry neither bit: usable on both sides, always.
-        let cat = SpellDisplay::default();
-        assert_eq!(cast_water_refusal(0, Some(&cat)), None);
-        assert_eq!(cast_water_refusal(mf::SWIMMING, Some(&cat)), None);
-        // No record, nothing to read — the press passes, like every other data-driven rung.
-        assert_eq!(cast_water_refusal(0, None), None);
-        assert_eq!(cast_water_refusal(mf::SWIMMING, None), None);
-    }
-
-    /// The water gate against the **real 5875 Spell.dbc** — the census the whole gate rests on.
-    /// The leg↔bit assignment is not a naming choice we could get backwards: exactly five rows
-    /// in the shipped data carry the water-REQUIRED bit, and Aquatic Form is one of them, while
-    /// the water-FORBIDDEN bit is a broad set led by the mounts, Travel Form and food/drink.
-    /// Skips without client data.
-    #[test]
-    fn the_water_bits_split_the_5875_data_the_way_the_gate_assumes() {
-        let data = benilla_formats::wow_data_or_skip!();
-        let mut chain = benilla_formats::open_chain(&data).expect("open chain");
-        let catalog = benilla_formats::load_spell_catalog(&mut chain).expect("Spell.dbc");
-
-        // Every spell the client would refuse OUT of water, by id.
-        let mut needs_water: Vec<u32> = catalog
-            .iter()
-            .filter(|(_, d)| d.aura_interrupt_flags & INTERRUPT_ABOVE_WATER != 0)
-            .map(|(id, _)| id)
-            .collect();
-        needs_water.sort_unstable();
-        assert_eq!(
-            needs_water,
-            vec![1066, 16455, 16456, 24346, 24347],
-            "the water-required set: Aquatic Form, the Lava/Slime swim auras, Master Angler"
-        );
-
-        // The other face: broad, and led by exactly the things you cannot do mid-swim.
-        let forbids_water = |id: u32| {
-            catalog
-                .get(id)
-                .is_some_and(|d| d.aura_interrupt_flags & INTERRUPT_UNDER_WATER != 0)
-        };
-        assert!(forbids_water(783), "Travel Form");
-        assert!(forbids_water(458), "Brown Horse");
-        assert!(forbids_water(433), "Food");
-        assert!(forbids_water(430), "Drink");
-        assert!(forbids_water(818), "Basic Campfire");
-
-        // ARM B's reason to exist, on the real rows (decision 1063). Fishing rank 1 carries the
-        // bit in the AURA column; its own upgrades carry NOTHING there and reach the gate only
-        // through the CHANNEL column. Arm A alone would refuse rank 1 mid-swim and let 2–4 fish.
-        let swim = crate::creature_anim::move_flags::SWIMMING;
-        assert!(forbids_water(7620), "Fishing rank 1 — arm A");
-        for rank in [7731, 7732, 18248] {
-            let d = catalog
-                .get(rank)
-                .unwrap_or_else(|| panic!("Fishing {rank} missing"));
-            assert_eq!(d.aura_interrupt_flags, 0, "Fishing {rank}: arm A is empty");
-            assert!(d.attributes_ex & ATTR_EX_CHANNELED != 0, "and it channels");
-            assert_eq!(
-                cast_water_refusal(swim, Some(d)),
-                Some(ERR_ONLY_ABOVEWATER),
-                "Fishing {rank} still refuses mid-swim, through the channel column"
-            );
-            assert_eq!(cast_water_refusal(0, Some(d)), None, "and fishes on shore");
-        }
-
-        // The forms that carry neither bit — usable on both sides, and the control that says the
-        // gate is reading a real per-spell column and not a class-wide accident.
-        for (id, name) in [(768, "Cat Form"), (5487, "Bear Form"), (2645, "Ghost Wolf")] {
-            let d = catalog.get(id).unwrap_or_else(|| panic!("{name} missing"));
-            assert_eq!(d.aura_interrupt_flags & 0x180, 0, "{name} is side-agnostic");
-            assert_eq!(cast_water_refusal(0, Some(d)), None, "{name} on land");
-            assert_eq!(cast_water_refusal(swim, Some(d)), None, "{name} swimming");
-        }
-
-        // And end to end, on the real rows: B176's exact press.
-        let aquatic = catalog.get(1066).expect("Aquatic Form");
-        assert_eq!(
-            cast_water_refusal(0, Some(aquatic)),
-            Some(ERR_ONLY_UNDERWATER),
-            "on land, Aquatic Form refuses — the B176 report"
-        );
-        assert_eq!(
-            cast_water_refusal(crate::creature_anim::move_flags::SWIMMING, Some(aquatic)),
-            None,
-            "swimming, it goes through"
-        );
-    }
-
-    /// The moving refusal (`0x609de3`) — every leg of the byte-verified condition: the
-    /// `InterruptFlags & 0x1` entry, the `0x200f` wire mask (turn/FALLINGFAR outside it,
-    /// JUMPING inside), the auto-repeat exemption, and the "would movement matter" arms (cast
-    /// time / aura / channel `0x18` bits).
-    #[test]
-    fn cast_moving_refusal_follows_the_validator_condition() {
-        use crate::creature_anim::move_flags as mf;
-        // Fireball's shape: ordinary timed cast (interrupt 0xf, nonzero cast time).
-        let timed = SpellDisplay {
-            interrupt_flags: 0xf,
-            ..Default::default()
-        };
-        // Moving forward refuses; standing still doesn't.
-        assert!(cast_moving_refusal(mf::FORWARD, 1500, Some(&timed)));
-        assert!(!cast_moving_refusal(0, 1500, Some(&timed)));
-        // Strafe and JUMPING are in the mask; turn and FALLING_FAR are not (`0x200f`).
-        assert!(cast_moving_refusal(mf::STRAFE_LEFT, 1500, Some(&timed)));
-        assert!(cast_moving_refusal(mf::FALLING, 1500, Some(&timed)));
-        assert!(!cast_moving_refusal(mf::TURN_LEFT, 1500, Some(&timed)));
-        assert!(!cast_moving_refusal(mf::FALLING_FAR, 1500, Some(&timed)));
-        // An instant WITHOUT the movement interrupt bit passes (Fire Blast's shape)…
-        let instant = SpellDisplay {
-            interrupt_flags: 0xe,
-            ..Default::default()
-        };
-        assert!(!cast_moving_refusal(mf::FORWARD, 0, Some(&instant)));
-        // …and even WITH it, a zero cast time passes unless an 0x18 arm bites.
-        assert!(!cast_moving_refusal(mf::FORWARD, 0, Some(&timed)));
-        // Arcane Missiles' shape: zero cast time, but the channel column's moving bits refuse
-        // at initiation (the OR-arm; 0x7c0c & 0x18 != 0).
-        let channel = SpellDisplay {
-            interrupt_flags: 0xf,
-            channel_interrupt_flags: 0x7c0c,
-            ..Default::default()
-        };
-        assert!(cast_moving_refusal(mf::FORWARD, 0, Some(&channel)));
-        // The aura-column arm (food/drink sit-still bits).
-        let sit_still = SpellDisplay {
-            interrupt_flags: 0x1,
-            aura_interrupt_flags: 0x18,
-            ..Default::default()
-        };
-        assert!(cast_moving_refusal(mf::FORWARD, 0, Some(&sit_still)));
-        // Auto-repeat (AttributesEx2 & 0x20) is unconditionally exempt — Auto Shot fires on
-        // the run whatever its columns say.
-        let auto_shot = SpellDisplay {
-            interrupt_flags: 0x1,
-            attributes_ex2: 0x20,
-            aura_interrupt_flags: 0x18,
-            ..Default::default()
-        };
-        assert!(!cast_moving_refusal(mf::FORWARD, 0, Some(&auto_shot)));
-        // No record: nothing to read, the press passes (the server stays the net).
-        assert!(!cast_moving_refusal(mf::FORWARD, 1500, None));
-    }
-}
-
-#[cfg(test)]
-mod cc_refusal_tests {
-    use super::*;
-
-    const STUNNED: u32 = 0x0004_0000;
-    const SILENCED: u32 = 0x0000_2000;
-    const PACIFIED: u32 = 0x0002_0000;
-    const CONFUSED: u32 = 0x0040_0000;
-    const FLEEING: u32 = 0x0080_0000;
-
-    fn spell(prevention_type: u32) -> SpellDisplay {
-        SpellDisplay {
-            prevention_type,
-            ..Default::default()
-        }
-    }
-
-    /// A scan that finds no aura at all — `exempt: false, mechanic: 0`, so every arm falls to its
-    /// OWN reason. This is the ordinary case: the exemption only ever fires for a caster wearing
-    /// an immunity.
-    fn no_auras() -> impl FnMut(&[u32]) -> benilla_formats::CcExemption {
-        |_: &[u32]| benilla_formats::CcExemption::default()
-    }
-
-    /// The reason alone, dropping the mechanic — most of these tests are about which arm fires.
-    fn reason_of(v: Option<(u8, Option<u32>)>) -> Option<u8> {
-        v.map(|(r, _)| r)
-    }
-
-    /// A live caster, nobody else at the reins, no auras.
-    fn cc(flags: u32, d: &SpellDisplay) -> Option<u8> {
-        cast_cc_refusal(flags, Some(100), false, Some(d), &mut no_auras()).map(|(r, _)| r)
-    }
-
-    /// **The arms are not symmetric** (decision 1904, widened by 1925): stun, fear, charm and
-    /// confuse refuse EVERY spell; silence and pacify only the rows whose `PreventionType` names
-    /// them. Reading `UNIT_FLAG_SILENCED` as "no casting at all" — which our own preflight banner
-    /// used to say — is the mistake this pins.
-    #[test]
-    fn crowd_control_refuses_by_prevention_type_except_the_unconditional_arms() {
-        // Fireball-shaped (silence-preventable), Heroic-Strike-shaped (pacify-preventable), and
-        // the auto-attack's neither — the three real values, pinned in `spell_catalog`.
-        let cast = spell(1);
-        let melee = spell(2);
-        let neither = spell(0);
-
-        // The four arms with NO per-spell gate: every row refuses.
-        for (flags, reason) in [(STUNNED, 0x64), (FLEEING, 0x1e), (CONFUSED, 0x16)] {
-            for d in [&cast, &melee, &neither] {
-                assert_eq!(cc(flags, d), Some(reason), "flags {flags:#x}");
-            }
-        }
-        // …and charm, which is not a flag at all but "somebody else holds the reins".
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                0,
-                Some(100),
-                true,
-                Some(&neither),
-                &mut no_auras()
-            )),
-            Some(0x14)
-        );
-
-        // SILENCED takes the casts and leaves the rest alone.
-        assert_eq!(cc(SILENCED, &cast), Some(0x60));
-        assert_eq!(cc(SILENCED, &melee), None);
-        assert_eq!(cc(SILENCED, &neither), None);
-
-        // PACIFIED is the mirror.
-        assert_eq!(cc(PACIFIED, &melee), Some(0x5a));
-        assert_eq!(cc(PACIFIED, &cast), None);
-
-        // Nothing up, nothing refused; and no record claims no prevention.
-        assert_eq!(cc(0, &cast), None);
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                SILENCED,
-                Some(100),
-                false,
-                None,
-                &mut no_auras()
-            )),
-            None
-        );
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED,
-                Some(100),
-                false,
-                None,
-                &mut no_auras()
-            )),
-            Some(0x64),
-            "the stun needs no record"
-        );
-    }
-
-    /// **The order is the reference's, first match wins** — charm outranks the stun, the stun
-    /// outranks everything below it. When several hold at once the player sees exactly one line,
-    /// and which one is not arbitrary.
-    #[test]
-    fn the_arms_are_tried_in_the_references_order() {
-        let cast = spell(1);
-        // Charm is arm 1: it beats a simultaneous stun.
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED | SILENCED,
-                Some(100),
-                true,
-                Some(&cast),
-                &mut no_auras()
-            )),
-            Some(0x14)
-        );
-        // Stun is arm 2: it beats silence, pacify, fear and confuse.
-        assert_eq!(
-            cc(STUNNED | SILENCED | PACIFIED | FLEEING | CONFUSED, &cast),
-            Some(0x64)
-        );
-        // Silence (3) beats fear (5) and confuse (6).
-        assert_eq!(cc(SILENCED | FLEEING | CONFUSED, &cast), Some(0x60));
-        // With the spell out of silence's reach, fear takes it before confuse.
-        assert_eq!(cc(SILENCED | FLEEING | CONFUSED, &spell(0)), Some(0x1e));
-    }
-
-    /// **What the exemption does to an arm** (decision 1946) — the three outcomes, at the arm.
-    #[test]
-    fn the_exemption_skips_an_arm_or_renames_its_refusal() {
-        let cast = spell(1);
-        let scan = |exempt: bool, mechanic: u32| {
-            move |_: &[u32]| benilla_formats::CcExemption { exempt, mechanic }
-        };
-
-        // No aura of the arm's type: the arm's OWN reason, as everywhere else.
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED,
-                Some(100),
-                false,
-                Some(&cast),
-                &mut scan(false, 0)
-            )),
-            Some(0x64)
-        );
-        // A blocking aura the cast does NOT counter: the refusal survives but is renamed to
-        // `0x8d` "Can't do that while %s", the mechanic naming the aura.
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED,
-                Some(100),
-                false,
-                Some(&cast),
-                &mut scan(false, 12)
-            )),
-            Some(0x8d)
-        );
-        // The cast grants immunity: the arm is SKIPPED and the cast goes out. This is the whole
-        // point — Ice Block cast while stunned.
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED,
-                Some(100),
-                false,
-                Some(&cast),
-                &mut scan(true, 0)
-            )),
-            None
-        );
-        // …and skipping one arm does not skip the ladder: a silenced-and-stunned caster whose
-        // spell counters only the stun still refuses on silence below it.
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED | SILENCED,
-                Some(100),
-                false,
-                Some(&cast),
-                &mut |types: &[u32]| {
-                    // Exempt from the stun arm `{12}` only; the silence arm `{27, 12, 60}` is not.
-                    benilla_formats::CcExemption {
-                        exempt: types == [12],
-                        mechanic: 0,
-                    }
-                }
-            )),
-            Some(0x60)
-        );
-    }
-
-    /// **The mechanic rides out with the refusal** (decision 1948) — the half that turns
-    /// "Can't do that while %s" into a sentence. It is the ONE client-local refusal that carries
-    /// an argument word, and it is `None` for every arm that fell to its own reason.
-    #[test]
-    fn the_renamed_refusal_carries_the_mechanic_and_the_others_carry_nothing() {
-        let cast = spell(1);
-        let scan = |exempt: bool, mechanic: u32| {
-            move |_: &[u32]| benilla_formats::CcExemption { exempt, mechanic }
-        };
-
-        // Rejected by a blocking aura: reason `0x8d` AND the mechanic that names it.
-        assert_eq!(
-            cast_cc_refusal(STUNNED, Some(100), false, Some(&cast), &mut scan(false, 12)),
-            Some((0x8d, Some(12)))
-        );
-        // No aura: the arm's own reason, and NO argument — the message has no `%s` to fill.
-        assert_eq!(
-            cast_cc_refusal(STUNNED, Some(100), false, Some(&cast), &mut scan(false, 0)),
-            Some((0x64, None))
-        );
-        // Exempt: nothing at all.
-        assert_eq!(
-            cast_cc_refusal(STUNNED, Some(100), false, Some(&cast), &mut scan(true, 0)),
-            None
-        );
-    }
-
-    /// **A dead caster skips all six** (`0x60980d`'s `jle` on `UNIT_FIELD_HEALTH`) — a corpse is
-    /// refused by an earlier rung, and reporting a stun over it would be the wrong line.
-    #[test]
-    fn a_dead_caster_takes_no_crowd_control_refusal() {
-        let cast = spell(1);
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED,
-                Some(0),
-                false,
-                Some(&cast),
-                &mut no_auras()
-            )),
-            None
-        );
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                0,
-                Some(0),
-                true,
-                Some(&cast),
-                &mut no_auras()
-            )),
-            None
-        );
-        // Alive again, and the arm is back.
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED,
-                Some(1),
-                false,
-                Some(&cast),
-                &mut no_auras()
-            )),
-            Some(0x64)
-        );
-        // No health field at all is not death — the descriptor simply has not landed.
-        assert_eq!(
-            reason_of(cast_cc_refusal(
-                STUNNED,
-                None,
-                false,
-                Some(&cast),
-                &mut no_auras()
-            )),
-            Some(0x64)
-        );
-    }
 }
diff --git a/crates/benilla-app/src/ui_action/toggle.rs b/crates/benilla-app/src/ui_action/toggle.rs
index 87b1f495..ed63e664 100644
--- a/crates/benilla-app/src/ui_action/toggle.rs
+++ b/crates/benilla-app/src/ui_action/toggle.rs
@@ -1,7 +1,6 @@
-//! The plain-path **press-again-to-cancel** toggles — wow-re `shapeshift-plaincast-toggle.md`
-//! (§5 cross-checked 2026-07-31). The reference client cancels an active toggle spell in its
-//! DISPATCHERS, above `TryCast 0x6e4b60` (which itself has no cancel branch), and the two plain
-//! paths are deliberately asymmetric:
+//! The plain-path **press-again-to-cancel** toggles. The reference client cancels an active
+//! toggle spell in its DISPATCHERS, above `TryCast 0x6e4b60` (which itself has no cancel branch),
+//! and the two plain paths are deliberately asymmetric:
 //!
 //! - **Active-action toggle** ([`active_action_toggle`], predicate `0x4e55f0` and its byte-twin
 //!   `0x4b36f0`) — on BOTH `UseAction 0x4e5ee0` (cancel `0x4e60c1`) and the `CastSpell`/
diff --git a/crates/benilla-app/src/ui_action/weapon_icon.rs b/crates/benilla-app/src/ui_action/weapon_icon.rs
index 9e841e72..a51e4d36 100644
--- a/crates/benilla-app/src/ui_action/weapon_icon.rs
+++ b/crates/benilla-app/src/ui_action/weapon_icon.rs
@@ -1,5 +1,5 @@
 //! **Weapon-icon substitution** — the handful of spells that show an *equipped weapon's* icon
-//! instead of their own (decisions 0230 + 0231; wow-re `attack-icon-substitution.md`).
+//! instead of their own (decisions 0230 + 0231; `0x4e6870` melee, `0x4e6990` ranged).
 //!
 //! Two spells' worth of law, but it is character-level rather than spell-level: the melee
 //! auto-attack borrows the main hand's icon (or `Spell-Reset` when unarmed), a ranged auto-repeat
@@ -13,22 +13,22 @@ use benilla_formats::SpellDisplay;
 use crate::creature_anim::UNIT_FLAG_DISARMED;
 use crate::entities::ItemDisplays;
 use crate::items::Items;
-use crate::net::{NetCommands, ObjectStore};
+use crate::net::{NetCommands, ObjectStore, Objects};
 
 /// Equipment slot 15 = `EQUIPMENT_SLOT_MAINHAND` (vmangos `EquipmentSlots`).
 const EQUIPMENT_SLOT_MAINHAND: u8 = 15;
 
 /// Equipment slot 17 = `EQUIPMENT_SLOT_RANGED` — the ranged helper `0x4e6990`'s read
-/// (`[ecx+0x88]`, `0x88 = 17×8`; wow-re `attack-icon-substitution.md` §5).
+/// (`[ecx+0x88]`, `0x88 = 17×8`).
 const EQUIPMENT_SLOT_RANGED: u8 = 17;
 
 /// Weapon subclass 16 = thrown — the ranged icon helper's skip (`0x4e6990`'s `0x5d9f90 == 0x10`
 /// test): a thrown weapon never substitutes its icon, so Throw keeps the spell's own face.
 const ITEM_SUBCLASS_THROWN: u32 = 16;
 
-/// The client's unarmed/disarmed auto-attack icon (wow-re `attack-icon-substitution.md`, the
-/// hardcoded string at `0x84bf58`) — what the melee auto-attack shows when there is no main-hand
-/// weapon to borrow from, instead of spell 6603's `Temp` placeholder (decision 0231).
+/// The client's unarmed/disarmed auto-attack icon (the hardcoded string at `0x84bf58`) — what the
+/// melee auto-attack shows when there is no main-hand weapon to borrow from, instead of spell
+/// 6603's `Temp` placeholder (decision 0231).
 const SPELL_RESET_ICON: &str = "Interface\\Buttons\\Spell-Reset";
 
 /// `ItemClass` 2 — **WEAPON**: what the disarmed guard tests on the hand it just fetched
@@ -43,12 +43,13 @@ const ITEM_CLASS_WEAPON: u32 = 2;
 /// item whose icon would otherwise be shown.
 fn main_hand_item(
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     commands: &NetCommands,
 ) -> Option<(u32, Option<String>)> {
     let guid = store.0.player_inv_slot(EQUIPMENT_SLOT_MAINHAND)?;
-    let entry = items.object(guid)?.object_entry()?;
+    let entry = objects.object(guid)?.object_entry()?;
     let template = items.template(entry, guid, commands)?;
     let (class, display) = (template.class, template.display_info_id);
     let icon = icons
@@ -58,11 +59,11 @@ fn main_hand_item(
 }
 
 /// The character's melee auto-attack icon (decision 0231; the client's melee helper `0x4e6870`).
-/// The helper's four steps, in order (wow-re `attack-icon-substitution.md` §7):
+/// The helper's four steps, in order:
 ///
 /// 1. the **current shapeshift form's own attack face** when its `SpellShapeshiftForm` row carries
 ///    one (the `+0x34` AttackIconID read, `0x4e68af`–`0x4e68da` — a cat's paw, a bear's swipe;
-///    wow-re `action-spell-icon-apis.md` §3.3, closing decision 0231's deferred form case);
+///    closing decision 0231's deferred form case);
 /// 2. the **disarmed guard** (`0x4e68df`) → [`SPELL_RESET_ICON`], weapon equipped or not
 ///    (decision 1863, closing 0231's other deferred case);
 /// 3. the equipped main-hand weapon's icon;
@@ -73,6 +74,7 @@ fn main_hand_item(
 pub(crate) fn melee_auto_attack_icon(
     store: &ObjectStore,
     forms: &std::collections::HashMap<u32, benilla_formats::ShapeshiftForm>,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     commands: &NetCommands,
@@ -86,7 +88,7 @@ pub(crate) fn melee_auto_attack_icon(
             return icon;
         }
     }
-    let main = main_hand_item(store, items, icons, commands);
+    let main = main_hand_item(store, objects, items, icons, commands);
     // Precedence step 2 — the **disarmed guard** (`0x4e68df`: `test dword ptr [ecx+0xa0],
     // 0x200000`, then `GetWeapon(0, 1)` and a `== 2` on the returned class byte): while the
     // character is disarmed, a weapon in the main hand shows `Spell-Reset` exactly as an empty
@@ -104,19 +106,19 @@ pub(crate) fn melee_auto_attack_icon(
 }
 
 /// The equipped ranged weapon's inventory icon (slot 17 → `ItemDisplayInfo`), for the ranged
-/// icon substitution (`0x4e6990`, decision 0231's deferred case — wow-re
-/// `attack-icon-substitution.md` §5): a **thrown** weapon is skipped (the helper's
-/// `0x5d9f90 == 0x10` test), and `None` — missing weapon, thrown, or an unstreamed item — falls
-/// back to the spell's OWN icon at the caller, never `Spell-Reset` (the helper's `0x4e6a44` null
-/// return hands over to the normal SpellIconID path).
+/// icon substitution (`0x4e6990`, decision 0231's deferred case): a **thrown** weapon is skipped
+/// (the helper's `0x5d9f90 == 0x10` test), and `None` — missing weapon, thrown, or an unstreamed
+/// item — falls back to the spell's OWN icon at the caller, never `Spell-Reset` (the helper's
+/// `0x4e6a44` null return hands over to the normal SpellIconID path).
 pub(crate) fn ranged_weapon_icon(
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     commands: &NetCommands,
 ) -> Option<String> {
     let guid = store.0.player_inv_slot(EQUIPMENT_SLOT_RANGED)?;
-    let entry = items.object(guid)?.object_entry()?;
+    let entry = objects.object(guid)?.object_entry()?;
     let template = items.template(entry, guid, commands)?;
     if template.subclass == ITEM_SUBCLASS_THROWN {
         return None;
@@ -143,16 +145,19 @@ pub(super) fn auto_attack_icon(
     spell: &SpellDisplay,
     store: Option<&ObjectStore>,
     forms: &std::collections::HashMap<u32, benilla_formats::ShapeshiftForm>,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     commands: &NetCommands,
 ) -> Option<String> {
     let store = store?;
     if spell.is_melee_auto_attack() {
-        return Some(melee_auto_attack_icon(store, forms, items, icons, commands));
+        return Some(melee_auto_attack_icon(
+            store, forms, objects, items, icons, commands,
+        ));
     }
     if spell.ranged_icon_substitution() {
-        return ranged_weapon_icon(store, items, icons, commands);
+        return ranged_weapon_icon(store, objects, items, icons, commands);
     }
     None
 }
@@ -187,8 +192,7 @@ mod tests {
         let mut pairs = vec![(UNIT_FLAGS, flags), (UNIT_BYTES_1, u32::from(form) << 16)];
         if let Some(class) = hand {
             pairs.push((INV_SLOT_MAINHAND, 0x2a));
-            deps.items
-                .insert_object(0x2a, ObjectFields::from_pairs(&[(3, 500)]));
+            deps.spawn_item(0x2a, ObjectFields::from_pairs(&[(3, 500)]));
             deps.items.insert_template(
                 500,
                 Some(ItemInfo {
@@ -216,7 +220,9 @@ mod tests {
                 ..Default::default()
             },
         )]);
-        melee_auto_attack_icon(&store, &forms, &deps.items, Some(&icons), &deps.commands)
+        deps.with_objects(|objects, items, commands| {
+            melee_auto_attack_icon(&store, &forms, objects, items, Some(&icons), commands)
+        })
     }
 
     /// **The disarmed guard on the Attack button** (`0x4e68df`, decision 1863 closing 0231's
@@ -238,8 +244,8 @@ mod tests {
         assert_eq!(icon(DISARMED, None, 0), SPELL_RESET_ICON);
     }
 
-    /// The precedence the helper reads in (§7 of the wow-re note): the **form** override is step
-    /// 1 and the disarmed guard step 2, so a disarmed bear still swipes with its own paw.
+    /// The precedence the helper `0x4e6870` reads in: the **form** override is step 1 and the
+    /// disarmed guard step 2, so a disarmed bear still swipes with its own paw.
     #[test]
     fn the_form_icon_outranks_the_disarmed_guard() {
         assert_eq!(icon(DISARMED, Some(2), 1), BEAR_ICON);
diff --git a/crates/benilla-app/src/ui_auction/mod.rs b/crates/benilla-app/src/ui_auction/mod.rs
index f72e8add..aaa7c52e 100644
--- a/crates/benilla-app/src/ui_auction/mod.rs
+++ b/crates/benilla-app/src/ui_auction/mod.rs
@@ -5,14 +5,20 @@
 //! **The window is opened by the server, not by the click.** A right-click on an auctioneer
 //! ([`crate::target`]) sends `MSG_AUCTION_HELLO` and nothing else happens; the *reply* — the same
 //! opcode coming back with the auctioneer guid and an `AuctionHouse.dbc` house id — is what opens
-//! the session here (wow-re: the window's opener calls `SetInteractNPC` and fires
+//! the session here (the window's opener `0x4cd570` calls `SetInteractNPC` and fires
 //! `AUCTION_HOUSE_SHOW` from inside the hello handler). That house id is load-bearing rather than
 //! decorative: it keys the deposit rate the sell pane displays, and the six faction houses charge
 //! 5% where the neutral goblin house charges 25%.
 //!
-//! **Three lists, one session.** Browse (`"list"`), Bids (`"bidder"`) and Auctions (`"owner"`) are
-//! three independent server queries into one window. Each holds at most one 50-row page — the
-//! server's own cap — plus the pre-cap match count the pager needs, plus its own sort stack.
+//! **Three lists, one session — and three separate events.** Browse (`"list"`), Bids (`"bidder"`)
+//! and Auctions (`"owner"`) are three independent server queries into one window. Each holds at
+//! most one 50-row page — the server's own cap — plus the pre-cap match count the pager needs,
+//! plus its own sort stack, plus its own update event. The reference keeps them just as far apart
+//! (three arrays allocated by `0x4cc0f0`, three counts, three sort stacks, and every
+//! `AUCTION_*_LIST_UPDATE` fired by whatever just touched *its* array).
+//! So a list-update event here is a statement about **one** list; firing the other two runs the
+//! stock addon's other tabs over state they were never given, and the Auctions tab answers that
+//! by crashing (decision 2308).
 //!
 //! **Sorting is ours and paging is the server's**, which is the split that shapes this module: a
 //! header click re-orders rows we already hold and sends nothing ([`sort`]), while a page turn
@@ -22,7 +28,7 @@
 //! of the last one and *drops it with no failure event*, which is why the Search button polls
 //! [`benilla_ui::script::UiScript::set_auction_can_query`] every frame instead of reacting to a
 //! refusal. The window opening clears the gate, so the first search is always allowed. (INTERIM,
-//! decision 1511 — pinned to the in-flight §5's TU-2.)
+//! decision 1511.)
 //!
 //! The packet handlers ([`net`], in the net handler table — decision 2305) fill [`AuctionOpen`]
 //! from the wire. Each frame
@@ -32,7 +38,7 @@
 //! fires the events the reference Lua drives. [`drain_auction`] pulls the Lua intents back out
 //! into the auction `CMSG`s. The standardized NPC-session range guard ([`crate::ui_session`])
 //! client-side-closes the window when the player walks away from the auctioneer. That radius is
-//! **VERIFIED** rather than borrowed (wow-re §5 TU-6): the auction window's own interaction cell
+//! the auction window's own rather than borrowed: its interaction cell `[0xb72410]`
 //! holds `30.864194869995117` — a radius of `5.5555553` yd — which is exactly the service gate
 //! the cursor already greys at, so the guard's existing constant is the right one. The close
 //! sends no packet, also byte-confirmed.
@@ -48,7 +54,7 @@ use benilla_ui::script::{
 use crate::entities::ItemDisplays;
 use crate::items::Items;
 use crate::names::NameCache;
-use crate::net::{ClientCommand, NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{ClientCommand, NetCommands, ObjectStore, Objects, SelfPlayer};
 use crate::ui_action::{show_messages, ui_error_text, MessageSink, Shown, UiError};
 use crate::ui_script::{UiFeed, UiInput};
 use crate::ui_session::{close_npc_session_out_of_range, NpcSession};
@@ -59,14 +65,14 @@ use sort::SortStack;
 
 mod net;
 
-/// The browse query rate limit, in seconds. **VERIFIED** (wow-re §5 TU-2): the reference arms the
+/// The browse query rate limit, in seconds (`QueryAuctionItems 0x4ce980`): the reference arms the
 /// gate with `tick + 0x1388` *after* the packet goes out, re-checks it inside the query itself,
 /// and its refusal path fires **nothing at all** — no event, no error. That silence is why the
 /// Search button polls the gate every frame instead of waiting to be told no.
 const QUERY_THROTTLE_SECS: f64 = 5.0;
 
 /// The time-left buckets, in milliseconds — the thresholds the reference's four
-/// `AUCTION_TIME_LEFT` strings key off. **VERIFIED** (wow-re §5 TU-3: the table at `0x8072a8`).
+/// `AUCTION_TIME_LEFT` strings key off (the table at `0x8072a8`).
 const TIME_LEFT_SHORT_MS: u32 = 30 * 60 * 1000;
 const TIME_LEFT_MEDIUM_MS: u32 = 2 * 60 * 60 * 1000;
 const TIME_LEFT_LONG_MS: u32 = 8 * 60 * 60 * 1000;
@@ -84,7 +90,7 @@ const TIME_LEFT_IMPLAUSIBLE_MS: u32 = 7 * 24 * 60 * 60 * 1000;
 /// house's category filter.
 ///
 /// Read directly off the shipped table when the polarity was still ambiguous, and since
-/// **independently confirmed at the bytes** (wow-re §5 TU-4). Guessing it backwards would have
+/// **independently confirmed at the bytes** (`0x4cf9c0`). Guessing it backwards would have
 /// emptied the filter instead of trimming it: every row carrying the bit is an obsolete or unused subclass —
 /// Spear, Buckler(OBSOLETE), the OBSOLETE quivers, bolts and wands, Engineering Bag — and every
 /// subclass a player can actually buy (Cloth, Leather, Mail, Plate, Shield, Arrow, Bullet, the
@@ -98,19 +104,27 @@ const SUBCLASS_HIDDEN_FROM_AUCTIONS: u32 = 0x2;
 /// real `ItemClass.dbc` row. **Every string the filter displays comes from the player's own DBC**,
 /// which is what keeps this feature clear of decisions 1234/1260 — we ship the structure, the
 /// install supplies the words.
-const AUCTION_CLASSES: [u32; 10] = [
-    2,  // Weapon
-    4,  // Armor
-    1,  // Container
-    0,  // Consumable
-    7,  // Trade Goods
-    6,  // Projectile
-    11, // Quiver
-    9,  // Recipe
-    5,  // Reagent
-    15, // Miscellaneous
+///
+/// Each entry is the reference's `0x807060` row `{itemClassId, hasSubclassFilter}`: a class whose
+/// flag is 0 offers no subclass rows and no inventory-slot rows.
+const AUCTION_CLASSES: [(u32, bool); 10] = [
+    (2, true),   // Weapon
+    (4, true),   // Armor
+    (1, true),   // Container
+    (0, false),  // Consumable
+    (7, false),  // Trade Goods
+    (6, true),   // Projectile
+    (11, true),  // Quiver
+    (9, true),   // Recipe
+    (5, false),  // Reagent
+    (15, false), // Miscellaneous
 ];
 
+/// `ItemSubClass.Flags` bit `0x200`: the subclass offers the fourteen inventory-slot rows beneath
+/// it (`GetAuctionInvTypes`, `0x4cfb63 test ah,2`). In the shipped file it is set on exactly Armor
+/// 0..4 (Miscellaneous, Cloth, Leather, Mail, Plate) — not on Shield, Libram, Idol or Totem.
+const SUBCLASS_OFFERS_INV_TYPES: u32 = 0x200;
+
 /// The `AuctionHouse.dbc` catalog, loaded with the other item DBCs ([`crate::ui_items`]). Optional
 /// resource — absent, the sell pane shows no deposit rather than inventing one.
 #[derive(Resource)]
@@ -164,6 +178,11 @@ pub(crate) struct AuctionListSlot {
     pub(crate) entries: Vec<AuctionListEntry>,
     /// `totalCount` — the pre-cap match count, which is what tells the pager there is a page 2.
     pub(crate) total: u32,
+    /// A result for **this** list has landed since the window opened — the interface asked for it
+    /// and the server answered. `false` is "we hold no such list", which is *not* "the list is
+    /// empty": an empty page still arrives, and still counts. It is what the server-driven
+    /// refreshes gate on (decision 2308).
+    received: bool,
     sort: SortStack,
 }
 
@@ -176,11 +195,11 @@ pub(crate) struct AuctionListSlot {
 /// - a list result carrying **zero rows** changes nothing [`feed_auction`] can diff, so "the
 ///   auction house is empty" and "the query never came back" look identical from the snapshot;
 /// - a *successful* `SMSG_AUCTION_COMMAND_RESULT` is consumed straight into a re-query
-///   (`crate::net::apply::auction`) and leaves no record — only a *failed* one surfaces, and only
+///   (`crate::ui_auction::net`) and leaves no record — only a *failed* one surfaces, and only
 ///   as an error line;
-/// - a browse query the throttle refuses is dropped with **no event at all** (the §5-verified
-///   silence this module's header describes), so "refused" and "sent" differ only in what went
-///   out on the wire.
+/// - a browse query the throttle refuses is dropped with **no event at all** (the silence this
+///   module's header describes), so "refused" and "sent" differ only in what went out on the
+///   wire.
 ///
 /// Nothing in the client needs any of it: the window reacts to the *effects*. It therefore lives
 /// in one clearly-named block that the client never reads, rather than being smeared through the
@@ -196,7 +215,7 @@ pub(crate) struct AuctionWireLog {
     pub(crate) last_command: Option<(u32, u32, u32)>,
 }
 
-/// The open auctioneer session, filled by the net bridge ([`crate::net::apply::auction`]) and read
+/// The open auctioneer session, filled by the net bridge ([`crate::ui_auction::net`]) and read
 /// by [`feed_auction`]. Cleared on a client-side close, on walking away, and on disconnect.
 #[derive(Resource, Default)]
 pub(crate) struct AuctionOpen {
@@ -209,15 +228,23 @@ pub(crate) struct AuctionOpen {
     show_requested: bool,
     /// Fire `NEW_AUCTION_UPDATE` next feed — the sell slot changed.
     sell_slot_dirty: bool,
-    /// A list result landed, so the list events are owed **whether or not the snapshot changed**.
+    /// A list result landed **for that list**, so *its* event is owed whether or not the snapshot
+    /// changed. Indexed [`LIST`]/[`BIDDER`]/[`OWNER`].
     ///
     /// Diffing the snapshot is not enough and the live probe is what proved it: an empty auction
     /// house, or re-running the same search, produces a result identical to what we already hold.
     /// The window's Browse pane clears its "Searching…" state only on `AUCTION_ITEM_LIST_UPDATE`,
-    /// so on an empty server a search animated its dots forever and never reported a result. The
-    /// reference has no diff here at all — one routine invalidates all three lists and fires all
-    /// three events.
-    list_result_landed: bool,
+    /// so on an empty server a search animated its dots forever and never reported a result.
+    ///
+    /// **Per list — that is the whole point** (decision 2308). This was one flag driving all three
+    /// fires, on 1511's reading that "one routine invalidates all three lists". The reference has
+    /// no such routine: three arrays, three counts, three sort stacks, **three separate events**,
+    /// each fired by whatever just touched *its* array. Firing the other two crashed the stock
+    /// `Blizzard_AuctionUI` outright — `AuctionFrameAuctions_Update` multiplies by
+    /// `AuctionFrameAuctions.page`, which the addon initialises only in that tab's `OnShow`, so a
+    /// browse result arriving while the player had never opened the Auctions tab raised
+    /// `attempt to perform arithmetic on field 'page' (a nil value)`.
+    list_result_landed: [bool; 3],
     /// Empty the sell slot next feed — a listing was accepted, so the staged item is *gone*.
     ///
     /// Also from the probe: without this the pane kept painting a phantom stack after a successful
@@ -304,10 +331,11 @@ impl AuctionOpen {
         self.show_requested = true;
     }
 
-    /// Replace one list's page. Always owes the list events, even for an identical page.
+    /// Replace one list's page. Always owes **that list's** event, even for an identical page.
     pub(crate) fn set_list(&mut self, which: usize, entries: Vec<AuctionListEntry>, total: u32) {
-        self.list_result_landed = true;
+        self.list_result_landed[which] = true;
         let slot = &mut self.lists[which];
+        slot.received = true;
         slot.entries = entries;
         // A server that reports fewer total matches than it just sent us is not a case worth
         // trusting over our own eyes; the pager reads the larger of the two.
@@ -329,13 +357,20 @@ impl AuctionOpen {
     }
 
     /// Mark our own listings stale — the drain re-queries next frame.
+    ///
+    /// **Only a list we hold can be stale** (decision 2308). A notification says "the page you are
+    /// showing is now wrong"; if the interface has never asked for the owned list, there is no
+    /// such page, and re-asking would *introduce* one — landing an `AUCTION_OWNED_LIST_UPDATE` on
+    /// a tab whose `page` field the stock addon has not initialised yet. The reference cannot
+    /// reach that state at all: its notification handlers patch the cached row in place, so an
+    /// array it never fetched has nothing to patch and announces nothing.
     pub(crate) fn refresh_owner(&mut self) {
-        self.pending_owner_refresh = true;
+        self.pending_owner_refresh |= self.lists[OWNER].received;
     }
 
-    /// Mark the bids we hold stale.
+    /// Mark the bids we hold stale — under the same rule as [`Self::refresh_owner`].
     pub(crate) fn refresh_bidder(&mut self) {
-        self.pending_bidder_refresh = true;
+        self.pending_bidder_refresh |= self.lists[BIDDER].received;
     }
 
     /// Close the window (a client-side close — vanilla sends nothing).
@@ -348,7 +383,7 @@ impl AuctionOpen {
         self.query_gate = None;
         self.pending_owner_refresh = false;
         self.pending_bidder_refresh = false;
-        self.list_result_landed = false;
+        self.list_result_landed = [false; 3];
         self.sell_slot_taken = false;
     }
 
@@ -487,7 +522,7 @@ pub(crate) fn categories(
     };
     AUCTION_CLASSES
         .iter()
-        .filter_map(|&class_id| {
+        .filter_map(|&(class_id, has_subclass_filter)| {
             let name = classes.0.name(class_id)?.to_string();
             let subs = subclasses
                 .0
@@ -500,18 +535,16 @@ pub(crate) fn categories(
                     Some(AuctionSubCategory {
                         sub_id: sub,
                         name: subclasses.0.name(class_id, sub)?.to_string(),
-                        // INTERIM (decision 1511, §5 TU-4): which class/subclass pairs offer the
-                        // fourteen inventory-slot rows is not yet derived from the binary. Armor
-                        // is the one the reference visibly offers them under, and it is the only
-                        // class where an equip slot narrows anything. Data, not logic — a
-                        // correction is this line.
-                        has_inv_types: class_id == 4,
+                        has_inv_types: subclasses.0.flags(class_id, sub)
+                            & SUBCLASS_OFFERS_INV_TYPES
+                            != 0,
                     })
                 })
                 .collect();
             Some(AuctionCategory {
                 class_id,
                 name,
+                has_subclass_filter,
                 subclasses: subs,
             })
         })
@@ -680,8 +713,16 @@ fn feed_auction(
     let opened = last_open.is_none() && auction.auctioneer.is_some();
     let closed = last_open.is_some() && auction.auctioneer.is_none();
     let show_requested = std::mem::take(&mut auction.show_requested);
-    let result_landed = std::mem::take(&mut auction.list_result_landed);
+    let landed = std::mem::take(&mut auction.list_result_landed);
     let changed = fresh != *last;
+    // **Which events are owed, per list.** A landed result owes its own list's event outright; a
+    // changed list owes it because an async name or template just filled one of its rows in. The
+    // diff is per list rather than over the whole snapshot for the same reason the fires are
+    // (2308): an event names one list, and firing the other two runs the stock Lua's other tabs
+    // over state they were never given.
+    let owed: [bool; 3] = std::array::from_fn(|i| {
+        landed[i] || fresh.as_ref().map(|s| &s.lists[i]) != last.as_ref().map(|s| &s.lists[i])
+    });
     if changed {
         script.set_auction(fresh.clone());
     }
@@ -694,19 +735,18 @@ fn feed_auction(
         if show_requested {
             script.fire_event("AUCTION_HOUSE_SHOW", vec![]);
         }
-        // A landed result owes the events outright; a change owes them because an async name or
-        // template just filled a row in. Diffing ALONE was the bug: an empty house and a repeated
-        // search both produce a result identical to what we hold, and the Browse pane waits on
-        // this event to stop saying "Searching…".
-        if changed || result_landed {
-            // One routine invalidates all three lists in the reference too — the three events fire
-            // together rather than being diffed apart, and each tab's handler repaints only if it
-            // is the visible one.
-            // Three literal fires, not a loop over names: the producer tripwire
-            // (`reference_ui::every_event_a_chain_file_registers_has_a_producer`) reads fire
-            // sites by their literal, and the stock addon registers all three (1971).
+        // Three literal fires, not a loop over names: the producer tripwire
+        // (`reference_ui::every_event_a_chain_file_registers_has_a_producer`) reads fire sites by
+        // their literal, and the stock addon registers all three (1971). Browse first, then Bids,
+        // then Auctions — the array's own order; the reference never fires two in one pass either,
+        // so nothing rests on it.
+        if owed[LIST] {
             script.fire_event("AUCTION_ITEM_LIST_UPDATE", vec![]);
+        }
+        if owed[BIDDER] {
             script.fire_event("AUCTION_BIDDER_LIST_UPDATE", vec![]);
+        }
+        if owed[OWNER] {
             script.fire_event("AUCTION_OWNED_LIST_UPDATE", vec![]);
         }
     }
@@ -741,6 +781,7 @@ fn drain_auction(
     mut auction: ResMut<AuctionOpen>,
     commands: Res<NetCommands>,
     time: Res<Time>,
+    objects: Objects,
     items: Res<Items>,
     icons: Option<Res<ItemDisplays>>,
     names: Res<NameCache>,
@@ -785,6 +826,7 @@ fn drain_auction(
                 level_min: u8::try_from(q.min_level).unwrap_or(u8::MAX),
                 level_max: u8::try_from(q.max_level).unwrap_or(u8::MAX),
                 slot_id: q.inv_type.unwrap_or(auction_filter::ANY),
+                // Already ids — the binding maps menu positions the way `0x4ce980` does.
                 main_category: q.class.unwrap_or(auction_filter::ANY),
                 sub_category: q.sub_class.unwrap_or(auction_filter::ANY),
                 quality: q.quality.unwrap_or(auction_filter::ANY),
@@ -876,7 +918,7 @@ fn drain_auction(
             .auction_sell_item()
             .and_then(|(bag, slot)| {
                 self_q.iter().next().and_then(|(store, _)| {
-                    crate::ui_items::slot_guid(&store.0, bag, (slot.max(1) - 1) as u8, &items)
+                    crate::ui_items::slot_guid(&store.0, bag, (slot.max(1) - 1) as u8, &objects)
                 })
             })
             .unwrap_or(0);
@@ -909,6 +951,54 @@ fn drain_auction(
 mod tests {
     use super::*;
 
+    /// The tree off the player's own DBCs carries the reference's two gates: the `0x807060` class
+    /// flag, and `ItemSubClass.Flags & 0x200` (`0x4cfb63`) for the inventory-slot rows — which
+    /// Shield does NOT carry, though it is Armor.
+    #[test]
+    fn the_tree_carries_the_reference_gates() {
+        let data = benilla_formats::wow_data_or_skip!();
+        let mut chain = benilla_formats::open_chain(&data).unwrap();
+        let classes =
+            crate::ui_items::ItemClasses(benilla_formats::load_item_classes(&mut chain).unwrap());
+        let subclasses = crate::ui_items::ItemSubClasses(
+            benilla_formats::load_item_sub_classes(&mut chain).unwrap(),
+        );
+        let tree = categories(Some(&classes), Some(&subclasses));
+        let ids: Vec<(u32, bool)> = tree
+            .iter()
+            .map(|c| (c.class_id, c.has_subclass_filter))
+            .collect();
+        assert_eq!(ids, AUCTION_CLASSES.to_vec());
+
+        let weapon = &tree[0];
+        assert_eq!(weapon.subclasses[0].sub_id, 0, "Axe leads, in file order");
+        assert!(
+            !weapon
+                .subclasses
+                .iter()
+                .any(|s| [9, 11, 12, 17].contains(&s.sub_id)),
+            "the excluded weapon rows are not offered"
+        );
+        assert!(weapon.subclasses.iter().all(|s| !s.has_inv_types));
+
+        let armor = &tree[1];
+        let offering: Vec<u32> = armor
+            .subclasses
+            .iter()
+            .filter(|s| s.has_inv_types)
+            .map(|s| s.sub_id)
+            .collect();
+        assert_eq!(
+            offering,
+            vec![0, 1, 2, 3, 4],
+            "not Shield, Libram, Idol, Totem"
+        );
+
+        // Consumable's flag is 0, yet its subclass list stays for the query's own scan.
+        assert!(!tree[3].has_subclass_filter);
+        assert!(!tree[3].subclasses.is_empty());
+    }
+
     /// The four buckets, and the one that matters: an expired auction the server has not swept yet
     /// arrives as an underflowed u32 and must read as Short, never as "Very Long".
     #[test]
@@ -926,7 +1016,7 @@ mod tests {
         );
     }
 
-    /// An identical list result still owes its events. Diffing the snapshot was the bug: an empty
+    /// An identical list result still owes its event. Diffing the snapshot was the bug: an empty
     /// auction house and a repeated search both produce a page identical to the one we hold, and
     /// the Browse pane clears its "Searching…" state only when the event arrives — so on an empty
     /// server a search animated forever and never reported a result. Found by the live probe,
@@ -937,19 +1027,84 @@ mod tests {
         open.open(0x1234, 1);
 
         open.set_list(LIST, Vec::new(), 0);
-        assert!(open.list_result_landed, "the first empty page");
+        assert!(open.list_result_landed[LIST], "the first empty page");
 
         // The feed consumes the flag when it fires.
-        open.list_result_landed = false;
+        open.list_result_landed = [false; 3];
 
         // The very same empty page again — nothing to diff, and still owed.
         open.set_list(LIST, Vec::new(), 0);
         assert!(
-            open.list_result_landed,
+            open.list_result_landed[LIST],
             "an identical page owes the event too — this is the whole bug"
         );
     }
 
+    /// **A result owes its OWN list's event and no other** (decision 2308).
+    ///
+    /// The regression this guards is a crash, not a repaint: the stock `Blizzard_AuctionUI`'s
+    /// `AuctionFrameAuctions_Update` multiplies by `AuctionFrameAuctions.page`, and that field is
+    /// initialised only in the Auctions tab's `OnShow`. A browse result that also fired
+    /// `AUCTION_OWNED_LIST_UPDATE` therefore ran that tab's repaint before it had ever been
+    /// shown — `attempt to perform arithmetic on field 'page' (a nil value)`, on screen, on the
+    /// first search of the session. `auction_frame.rs` holds the Lua half of this.
+    #[test]
+    fn a_result_owes_only_its_own_lists_event() {
+        let mut open = AuctionOpen::default();
+        open.open(0x1234, 1);
+
+        open.set_list(LIST, Vec::new(), 0);
+        assert_eq!(
+            open.list_result_landed,
+            [true, false, false],
+            "a browse result is not news about the player's bids or listings"
+        );
+
+        open.list_result_landed = [false; 3];
+        open.set_list(OWNER, Vec::new(), 0);
+        assert_eq!(open.list_result_landed, [false, false, true]);
+
+        open.list_result_landed = [false; 3];
+        open.set_list(BIDDER, Vec::new(), 0);
+        assert_eq!(open.list_result_landed, [false, true, false]);
+    }
+
+    /// **A refresh can only re-ask for a list we hold** (decision 2308) — the other half of the
+    /// same crash.
+    ///
+    /// "Your auction sold" arrives whenever the server feels like it, including while the player
+    /// is standing on the Browse tab having never opened the Auctions one. Turning that into a
+    /// fresh owner query would land an `AUCTION_OWNED_LIST_UPDATE` on that never-shown tab — the
+    /// nil `page` again, by a slower road. The reference cannot get there: its notification
+    /// handlers patch the cached row, and an array it never fetched has no row to patch.
+    #[test]
+    fn a_refresh_never_introduces_a_list_the_interface_never_asked_for() {
+        let mut open = AuctionOpen::default();
+        open.open(0x1234, 1);
+
+        open.refresh_owner();
+        open.refresh_bidder();
+        assert!(
+            !open.pending_owner_refresh && !open.pending_bidder_refresh,
+            "we hold neither list, so neither can have gone stale"
+        );
+
+        // The Auctions tab has now been shown once and the server answered — even with nothing in
+        // it. From here a sale really does invalidate what the player is looking at.
+        open.set_list(OWNER, Vec::new(), 0);
+        open.refresh_owner();
+        assert!(open.pending_owner_refresh, "a list we hold can go stale");
+        assert!(
+            !open.pending_bidder_refresh,
+            "and the other one still cannot"
+        );
+
+        // Closing forgets all of it — a notice landing after the window is gone re-asks nothing.
+        open.clear();
+        open.refresh_owner();
+        assert!(!open.pending_owner_refresh);
+    }
+
     /// An accepted listing releases the sell slot. Without it the pane kept painting a phantom
     /// stack, Create Auction stayed enabled, and a second click re-resolved the remembered
     /// (bag, slot) at send time — auctioning whatever had since landed in that slot.
diff --git a/crates/benilla-app/src/ui_auction/net.rs b/crates/benilla-app/src/ui_auction/net.rs
index 52dff545..dc99cc3a 100644
--- a/crates/benilla-app/src/ui_auction/net.rs
+++ b/crates/benilla-app/src/ui_auction/net.rs
@@ -101,14 +101,14 @@ fn on_removed_notification(In(ev): In<SessionEvent>, mut auction: ResMut<Auction
 
 /// An open auction house dies with the socket (decision 1511): every auction command
 /// re-validates the auctioneer server-side, so a session that survived a reconnect would be a
-/// window whose every button silently failed. A listener on the session end, which the drain's
-/// dispatch match still owns ([`crate::net::handlers::BROADCAST`]).
+/// window whose every button silently failed. A listener on the session end (a second handler
+/// on `Disconnected`, after the bridge's own teardown, `net::session::on_disconnected`).
 fn on_session_end(In(_): In<SessionEvent>, mut auction: ResMut<AuctionOpen>) {
     auction.clear_session();
 }
 
-/// `MSG_AUCTION_HELLO`'s reply — **this**, not our send, is what opens the window (wow-re: the
-/// window's opener runs inside the hello handler). The house id keys the deposit rate.
+/// `MSG_AUCTION_HELLO`'s reply — **this**, not our send, is what opens the window (the window's
+/// opener runs inside the hello handler `0x4cc420`). The house id keys the deposit rate.
 fn auction_hello(auctioneer: u64, house_id: u32, auction: &mut AuctionOpen) {
     auction.open(auctioneer, house_id);
 }
@@ -183,11 +183,32 @@ fn auction_command_result(
     // tell "the server said STARTED/OK" from "the server said nothing at all".
     auction.wire.last_command = Some((auction_id, action, error));
     if error == auction_error::OK {
-        // A successful sell/cancel/bid changes a list we are showing. The reference re-queries
-        // rather than patching its local copy, and so do we — the server is the only thing that
-        // knows what the page looks like now. Each also says so, in **chat** — the success arm
-        // shows `0x178`/`0x179`/`0x17f` keyed on the action field, with zero varargs
-        // (wow-re §11.2/§11.3).
+        // A successful sell/cancel/bid changes a list we are showing, so we re-ask: the server is
+        // the only thing that knows what the page looks like now, and the result carries an
+        // auction id, not a row.
+        //
+        // **The reference re-asks on two of these three, and neither ask is page 0** (both list
+        // senders have exactly two callers each and zero address-takes; decision 2308):
+        //
+        // - `STARTED` — `[0xb7263c] = 1`, then `0x4cc4e0 call 0x4cd680` = `CMSG 0x259` at the
+        //   **saved page offset** `[0xb72650]`. No row patch, no event of its own.
+        // - `BID_PLACED` — drops the id from the outbid list, `[0xb72640] = 1`, then
+        //   `0x4cc528 call 0x4cd720` = `CMSG 0x264` at `[0xb72654]` — and *then* patches the
+        //   browse row optimistically (bid ← the amount we sent, high bidder ← our own guid,
+        //   deadline ← `max(deadline, now + 90 s)`) and fires 424.
+        // - `REMOVED` — **no query at all**: `0x4cc658 call 0x4cdfe0` deletes the id from all
+        //   three arrays locally, each list firing only if it actually lost a row.
+        //
+        // We re-ask on all three, always at page 0, and patch nothing. Two live differences fall
+        // out: a player on page 2 of their own auctions is thrown back to page 1 by a sale, and
+        // their own bid does not appear on the row until the next result lands. Both belong to the
+        // freshness-model slice 2308 leaves open, not to this arm. What 2308 *does* enforce here
+        // is that a re-ask may never **introduce** a list the interface never asked for — the
+        // reference cannot, because its notification handlers patch instead of asking
+        // (`AuctionOpen::refresh_owner`).
+        //
+        // Each success also says so, in **chat** — the success arm `0x4cc4be` shows
+        // `0x178`/`0x179`/`0x17f` keyed on the action field, with zero varargs.
         match action {
             auction_action::STARTED => {
                 // The item is gone from the bag; the sell slot must stop claiming to hold it.
@@ -216,7 +237,7 @@ fn auction_command_result(
     // **HIGHER_BID says nothing here.** Its arm (`0x4cc672`) reads two extra fields and takes the
     // live *outbid update* path — it patches the row rather than raising a message, and the line
     // the player actually sees is `ERR_AUCTION_OUTBID_S`, off the bidder notification. Printing a
-    // refusal here would double it (wow-re §11.2).
+    // refusal here would double it.
     if error == auction_error::HIGHER_BID {
         auction.refresh_bidder();
         return;
@@ -229,13 +250,13 @@ fn auction_command_result(
 /// The failed command's GlobalStrings key — resolved to text in the feed against the player's own
 /// table, never carried as English here (decisions 0669 / 1190).
 ///
-/// **INTERIM on three arms.** wow-re §11.2 reads the dispatch as: code 1 computes its id from the
-/// packet's own second field through the *inventory*-result formatter (`0x622630`) — a different
-/// message family, whose keys are not carved; code 4 raises `0x17`; code 13 raises `0x1be`. Those
-/// three ids are outside the `ERR_AUCTION_*` block and their GlobalStrings names are not recorded
-/// yet, so they fall to the catch-all here rather than being invented. Everything else is the
-/// dispatch table verbatim, including that `2, 6, 8, 9, 11, 12` and anything above 13 are the
-/// reference's own `ja` default.
+/// **INTERIM on three arms.** In the reference's dispatch (`0x4cc460`), code 1 computes its id from
+/// the packet's own second field through the *inventory*-result formatter (`0x622630`) — a
+/// different message family, whose keys are not yet decoded; code 4 raises `0x17`; code 13 raises
+/// `0x1be`. Those three ids are outside the `ERR_AUCTION_*` block and their GlobalStrings names are
+/// not recorded yet, so they fall to the catch-all here rather than being invented. Everything else
+/// is the dispatch table verbatim, including that `2, 6, 8, 9, 11, 12` and anything above 13 are
+/// the reference's own `ja` default.
 fn command_error_key(error: u32) -> Option<&'static str> {
     Some(match error {
         auction_error::NOT_ENOUGH_MONEY => "ERR_NOT_ENOUGH_MONEY", // `0x25`, the shared id
@@ -267,7 +288,7 @@ fn auction_bidder_notification(notice: &AuctionBidderNotification, auction: &mut
 /// `SMSG_AUCTION_OWNER_NOTIFICATION` — one of ours sold, or took a bid. An all-zero bidder guid is
 /// the "sold" signal (the server zeroes it on a sale).
 fn auction_owner_notification(notice: &AuctionOwnerNotification, auction: &mut AuctionOpen) {
-    // **Two stages, and the first one decides whether anything is said at all** (wow-re §11.4).
+    // **Two stages, and the first one decides whether anything is said at all** (`0x4cd1f0`).
     // A NON-zero bidder guid is "somebody bid on your auction": the row updates and the client says
     // nothing — `[0x4cd25f, 0x4cd3bd)` holds no display call. Only a zeroed guid reaches the message
     // path, and there the *bid* picks the line: non-zero sold, zero expired.
@@ -286,8 +307,8 @@ fn auction_owner_notification(notice: &AuctionOwnerNotification, auction: &mut A
 
 /// `SMSG_AUCTION_REMOVED_NOTIFICATION` — an auction we had bid on was cancelled by its seller.
 ///
-/// One id, unconditionally (wow-re §11.4: `0x4cd480` has exactly one `call 0x496720` and no branch
-/// selecting an id).
+/// One id, unconditionally (`0x4cd480` has exactly one `call 0x496720` and no branch selecting
+/// an id).
 fn auction_removed_notification(item_entry: u32, auction: &mut AuctionOpen) {
     auction.messages.push(AuctionMessage::chat_item(
         "ERR_AUCTION_REMOVED_S",
@@ -308,22 +329,12 @@ mod tests {
         app.add_plugins(MinimalPlugins)
             .init_resource::<AuctionOpen>();
         register(&mut app);
-        let through_the_match = |_: &mut World, unclaimed: Vec<SessionEvent>| {
-            let kinds: Vec<SessionEventKind> =
-                unclaimed.iter().map(SessionEventKind::from).collect();
-            assert_eq!(
-                kinds,
-                vec![SessionEventKind::Disconnected],
-                "the broadcast reaches the match too"
-            );
-        };
         crate::net::handlers::dispatch(
             app.world_mut(),
             vec![SessionEvent::AuctionHello {
                 auctioneer: 0x10,
                 house_id: 1,
             }],
-            |_, unclaimed| assert!(unclaimed.is_empty()),
         );
         assert_eq!(app.world().resource::<AuctionOpen>().auctioneer, Some(0x10));
         crate::net::handlers::dispatch(
@@ -332,7 +343,6 @@ mod tests {
                 reason: "socket".into(),
                 end: benilla_protocol::SessionEnd::Lost,
             }],
-            through_the_match,
         );
         assert_eq!(app.world().resource::<AuctionOpen>().auctioneer, None);
     }
@@ -368,7 +378,7 @@ mod tests {
         }
     }
 
-    /// The owner notification's **two-stage** discrimination (wow-re §11.4), and the first stage is
+    /// The owner notification's **two-stage** discrimination (`0x4cd1f0`), and the first stage is
     /// the one a re-implementation gets wrong: a NON-zero bidder guid means "somebody bid on your
     /// auction", and the client says **nothing at all** — the row updates and that is the whole
     /// response. Only a zeroed guid reaches the message path, and there the *bid* picks the line.
diff --git a/crates/benilla-app/src/ui_auction/sort.rs b/crates/benilla-app/src/ui_auction/sort.rs
index df07d107..8050d153 100644
--- a/crates/benilla-app/src/ui_auction/sort.rs
+++ b/crates/benilla-app/src/ui_auction/sort.rs
@@ -9,11 +9,10 @@
 //! flipped arrow, and the sort is *stable across keys* — dropping "quality" to second place still
 //! breaks ties by it.
 //!
-//! **VERIFIED** (wow-re §5, TU-5, `system/ui/scratch/auction-house.md`): `0x4cd940` *is* the
-//! auction comparator, the sort *is* an 8-key MRU cascade, and each list owns its own `{col,dir}`
-//! stack. The per-key directions below are that verdict's, not our guess — three of them were
-//! wrong when this file first landed, and all three were ones a shopping UI makes the "obvious"
-//! way round.
+//! `0x4cd940` *is* the auction comparator, the sort *is* an 8-key MRU cascade, and each list owns
+//! its own `{col,dir}` stack. The per-key directions below are the reference's, not our guess —
+//! three of them were wrong when this file first landed, and all three were ones a shopping UI
+//! makes the "obvious" way round.
 
 use std::cmp::Ordering;
 
@@ -77,8 +76,8 @@ impl SortStack {
     }
 }
 
-/// One key's comparison, in the direction a *first* click on that column produces (wow-re §5
-/// TU-5, stated there as "which row appears first").
+/// One key's comparison, in the direction a *first* click on that column produces (`0x4cd940`'s
+/// arms, read as "which row appears first").
 ///
 /// Three of these run the opposite way to the intuition, and each is intuitive once you know what
 /// the column is for: **quality** opens with the epics, **buyout** opens with the most expensive
@@ -198,7 +197,7 @@ mod tests {
         assert_eq!(got, vec!["Charlie", "Alpha", "Bravo"], "level, then bid");
     }
 
-    /// Buyout opens HIGHEST-first (wow-re §5 TU-5) — and a buyout of `0` means "none", not
+    /// Buyout opens HIGHEST-first (`0x4cdaf2`) — and a buyout of `0` means "none", not
     /// "free", so descending puts it last with no special case.
     #[test]
     fn buyout_opens_highest_first_and_no_buyout_sinks() {
@@ -215,7 +214,7 @@ mod tests {
     }
 
     /// The three columns that run opposite to the intuition, pinned together so a future "fix"
-    /// has to argue with the §5 rather than with a hunch.
+    /// has to argue with the comparator `0x4cd940` rather than with a hunch.
     #[test]
     fn quality_and_status_open_highest_and_mine_first() {
         let mut rows = vec![
diff --git a/crates/benilla-app/src/ui_aura.rs b/crates/benilla-app/src/ui_aura.rs
index f822355d..39d92d65 100644
--- a/crates/benilla-app/src/ui_aura.rs
+++ b/crates/benilla-app/src/ui_aura.rs
@@ -34,7 +34,7 @@
 //! wire carries none for anyone but yourself). It **does** carry the display filter, though: an aura
 //! whose spell is flagged never-display (`NO_AURA_ICON`/`DO_NOT_DISPLAY` — a warrior stance) is
 //! hidden on *every* aura display, target rows included, not just the player's own bar (decision
-//! 0417, correcting 0268's scope note and wow-re §9 — the director watched the reference hide a
+//! 0417, correcting 0268's scope note — the director watched the reference hide a
 //! target's Battle Stance, which the "other-unit reads straight" reading can't explain: `NO_AURA_ICON`
 //! means exactly that, everywhere). A self-target is the one exception in *ordering*: decision 0257 §2
 //! resolves the Era API's single `UnitAura` toward the player-bar law under every token, so targeting
@@ -372,7 +372,7 @@ fn other_unit_auras(
 }
 
 /// **`UnitBuff 0x519500`'s unit-level gate** — may this unit's *buffs* be enumerated at all?
-/// (Decision 1035; byte-derived in wow-re `ui/scratch/aura-display-pipeline.md` §9b.)
+/// (Decision 1035.)
 ///
 /// This sits **before** the per-slot walk and outranks it: when it fails, `UnitBuff` pushes a
 /// single nil for **every** index without examining one slot, so the unit shows *no buffs*
@@ -471,19 +471,18 @@ fn until_cancelled(
 /// The reference's aura display filter (decisions 0268 + 0417): an aura is shown iff its spell is
 /// *not* flagged never-display (`SPELL_ATTR_DO_NOT_DISPLAY` / `SPELL_ATTR_EX_NO_AURA_ICON`, via
 /// `SpellDisplay::hidden_from_aura_bar`) **and** is not a tracking spell
-/// (`SpellDisplay::tracking_aura` — the `{0x2c,0x2d,0x97}` effect exclusion both byte-verified
-/// filters carry: the player-cache rebuild skips a tracking aura *before* the insert, diverting it
-/// to the tracking global instead, and `IsAuraDisplayable 0x519860` hides it from other units'
-/// rows the same way; wow-re `aura-display-pipeline.md` §3/§9a). This holds on **every** aura
-/// display — the player's own bar and any other unit's rows alike (the director watched the
-/// reference hide a target's Battle Stance; 0417 corrects 0268's player-only scope note and
-/// wow-re §9). A spell the catalog can't resolve stays visible — fail-open, like every other
-/// catalog miss in the feed.
+/// (`SpellDisplay::tracking_aura` — the `{0x2c,0x2d,0x97}` effect exclusion both filters carry:
+/// the player-cache rebuild `PlayerAuras_Update 0x4e4170` skips a tracking aura *before* the
+/// insert, diverting it to the tracking global instead, and `IsAuraDisplayable 0x519860` hides it
+/// from other units' rows the same way). This holds on **every** aura display — the player's own
+/// bar and any other unit's rows alike (the director watched the reference hide a target's Battle
+/// Stance; 0417 corrects 0268's player-only scope note). A spell the catalog can't resolve stays
+/// visible — fail-open, like every other catalog miss in the feed.
 ///
 /// **That fail-open is ours, not the reference's, on this path** — the parenthetical that used to
 /// justify it here ("like the reference's own no-SpellRec path, which inserts") was true of the
-/// *player cache* (§3) and is FALSE of the non-player walk: `UnitBuff`/`UnitDebuff` **skip** a slot
-/// whose id has no `Spell.dbc` row (`id > [0xc0d78c]` or a null row; wow-re §9c, decision 1035).
+/// *player cache* and is FALSE of the non-player walk: `UnitBuff`/`UnitDebuff` **skip** a slot
+/// whose id has no `Spell.dbc` row (`id > [0xc0d78c]` or a null row; decision 1035).
 /// Kept as fail-open deliberately: every id on the wire is a real spell, so the two behaviours are
 /// indistinguishable in practice, and failing *closed* would let a catalog load hiccup silently
 /// blank every aura on every frame. A knowing divergence, recorded — not a comment asserting
@@ -494,8 +493,8 @@ fn shown_in_aura_ui(catalog: Option<&SpellCatalog>, spell_id: u32) -> bool {
         .is_none_or(|d| !d.hidden_from_aura_bar() && !d.tracking_aura())
 }
 
-/// The player's active tracking aura — the reference's tracking global (`DAT_00bc6378`, wow-re
-/// `aura-display-pipeline.md` §3): the cache rebuild walks the raw slots **ascending** and each
+/// The player's active tracking aura — the reference's tracking global (`DAT_00bc6378`): the
+/// cache rebuild walks the raw slots **ascending** and each
 /// visible tracking-effect aura overwrites it, so the LAST one wins. The attribute clauses are
 /// tested *first* in the reference (the `goto` skips the effect loop), so an attribute-hidden
 /// tracking spell never lands here; a catalog miss can't be identified as tracking and lands in
@@ -735,7 +734,7 @@ fn feed_auras(
         .and_then(|&e| stores.get(e).ok())
         // **The pet keeps the ungated read, deliberately** (decision 1035). A pet is
         // PLAYER_CONTROLLED, which sends `CanAssist` down an arm (`0x60673e`-`0x60679f`, keyed on
-        // an `[obj+0xe68]` record) wow-re did NOT name — so the gate is not known here, and
+        // an `[obj+0xe68]` record) not yet named — so the gate is not known here, and
         // guessing it is the one mistake that could blank a working pet frame. `true` is the
         // status quo; the pet frame draws only debuffs today anyway (0990), so nothing observable
         // rides on it until that arm is derived.
@@ -1044,8 +1043,8 @@ mod tests {
         assert!(shown_in_aura_ui(Some(&catalog), 0xffff_fffe));
     }
 
-    /// The tracking half of the display filter (the Pass-2 law, wow-re `aura-display-pipeline.md`
-    /// §3: the `{0x2c,0x2d,0x97}` effect exclusion + the tracking global), against the REAL 5875
+    /// The tracking half of the display filter (Pass 2 of `PlayerAuras_Update 0x4e4170`: the
+    /// `{0x2c,0x2d,0x97}` effect exclusion + the tracking global), against the REAL 5875
     /// `Spell.dbc`: a tracking aura rides a visible `UNIT_FIELD_AURA` slot but never reaches any
     /// bar — it is diverted to the tracking state instead, and the ascending walk's LAST tracking
     /// aura wins the global. Skips without client data.
diff --git a/crates/benilla-app/src/ui_bank.rs b/crates/benilla-app/src/ui_bank/mod.rs
similarity index 99%
rename from crates/benilla-app/src/ui_bank.rs
rename to crates/benilla-app/src/ui_bank/mod.rs
index 42d1c045..9d6e5103 100644
--- a/crates/benilla-app/src/ui_bank.rs
+++ b/crates/benilla-app/src/ui_bank/mod.rs
@@ -83,10 +83,13 @@ impl NpcSession for BankOpen {
 #[derive(Resource, Default)]
 pub(crate) struct BankErrors(pub Vec<u32>);
 
+mod net;
+
 pub(crate) struct UiBankPlugin;
 
 impl Plugin for UiBankPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<BankOpen>()
             .init_resource::<BankErrors>()
             .add_systems(
diff --git a/crates/benilla-app/src/ui_bank/net.rs b/crates/benilla-app/src/ui_bank/net.rs
new file mode 100644
index 00000000..d73cb6e2
--- /dev/null
+++ b/crates/benilla-app/src/ui_bank/net.rs
@@ -0,0 +1,97 @@
+//! The bank's packet handlers (decision 0604; in the net handler table since 2318, moved out of
+//! the drain's npc arm file) — the [`BankOpen`] session and the [`BankErrors`] line queue the bank
+//! feed ([`super`]) reads.
+
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::{BankErrors, BankOpen};
+use crate::net::NetHandlerApp;
+use crate::ui_gossip::GossipState;
+use crate::ui_quest::QuestGiver;
+
+/// Register the bank handlers — called from [`super::UiBankPlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::ShowBank, on_show_bank)
+        .net_handler(K::BuyBankSlotResult, on_buy_slot_result)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_show_bank(
+    In(ev): In<SessionEvent>,
+    mut bank: ResMut<BankOpen>,
+    mut gossip: ResMut<GossipState>,
+    mut quest: ResMut<QuestGiver>,
+) {
+    if let SessionEvent::ShowBank { banker } = ev {
+        show_bank(banker, &mut bank, &mut gossip, &mut quest);
+    }
+}
+
+fn on_buy_slot_result(In(ev): In<SessionEvent>, mut errors: ResMut<BankErrors>) {
+    if let SessionEvent::BuyBankSlotResult { result } = ev {
+        bank_buy_slot_result(result, &mut errors);
+    }
+}
+
+/// The bank window dies with the socket (decision 0604) — a reconnect re-opens via the banker.
+/// A listener on the session end (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut bank: ResMut<BankOpen>) {
+    bank.clear_session();
+}
+
+/// The bank opened (`SMSG_SHOW_BANK`): point the [`BankOpen`] session the bank feed
+/// ([`super`]) reads at the banker. Sent for our own `CMSG_BANKER_ACTIVATE` *and*
+/// volunteered by the server for the gossip menu's bank option (`GOSSIP_OPTION_BANKER` →
+/// `SendShowBank`, decision 0604) — so this never assumes we asked. The vault's contents are
+/// descriptor fields already streamed; the window renders from local state.
+///
+/// Opening the bank ends any open gossip interaction (the `SMSG_GOSSIP_COMPLETE` clear): vmangos
+/// sends no `SMSG_GOSSIP_COMPLETE` for the gossip menu's bank option (VERIFIED
+/// `Player::OnGossipSelect` — BANKER only calls `SendShowBank`), and the panel slots alone can't
+/// close the menu — the bank's `pushable = 6` sends it to the *center* slot beside a pushable-0
+/// gossip instead of replacing it, so the menu would linger beside the vault
+/// (director-observed). The real client ends the old NPC interaction when the new one starts
+/// (INFERRED — the exact C++ `GOSSIP_CLOSED` fire isn't RE'd; the observable is vanilla's: the
+/// menu is gone once the vault is up).
+fn show_bank(banker: u64, bank: &mut BankOpen, gossip: &mut GossipState, quest: &mut QuestGiver) {
+    debug!("net: bank opened at {banker:#x}");
+    if gossip.npc.is_some() {
+        crate::ui_gossip::end_interaction(gossip, quest);
+    }
+    bank.open(banker);
+}
+
+/// A bank-slot purchase refusal (`SMSG_BUY_BANK_SLOT_RESULT` — vmangos sends it only on failure;
+/// success is the PLAYER_BYTES_2 delta): queue it for the bank feed's red error line.
+fn bank_buy_slot_result(result: u32, errors: &mut BankErrors) {
+    debug!("net: bank slot purchase refused (code {result})");
+    errors.0.push(result);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// `SMSG_SHOW_BANK` ends an open gossip interaction (the gossip menu's bank option arrives
+    /// with no `SMSG_GOSSIP_COMPLETE` — `show_bank`'s doc): the gossip/quest sessions clear and
+    /// the bank session opens. A direct right-click (no gossip open) just opens the bank.
+    #[test]
+    fn show_bank_ends_the_gossip_interaction() {
+        let mut bank = BankOpen::default();
+        let mut gossip = GossipState::default();
+        let mut quest = QuestGiver::default();
+        gossip.npc = Some(0x42);
+
+        show_bank(0x42, &mut bank, &mut gossip, &mut quest);
+        assert_eq!(bank.banker, Some(0x42));
+        assert_eq!(gossip.npc, None, "the gossip session ended with the menu");
+
+        // No gossip open: a plain open, nothing else touched.
+        bank.clear();
+        show_bank(0x43, &mut bank, &mut gossip, &mut quest);
+        assert_eq!(bank.banker, Some(0x43));
+    }
+}
diff --git a/crates/benilla-app/src/ui_battlefield.rs b/crates/benilla-app/src/ui_battlefield.rs
index c1dbd71e..73611d74 100644
--- a/crates/benilla-app/src/ui_battlefield.rs
+++ b/crates/benilla-app/src/ui_battlefield.rs
@@ -1,28 +1,28 @@
-//! The battleground **list window**'s app half (decision 1974; wow-re
-//! `system/ui/scratch/battlefield-verb-family.md` §2.1, §4.1, §4.4, §4.5, §5.2, §7.1, §8): what
+//! The battleground **list window**'s app half (decision 1974): what
 //! the stock `BattlefieldFrame.lua` and the minimap's queue icon need from the wire, the clock and
 //! the Map.dbc rows. The verbs themselves are `benilla_ui::script::battlefield_queue`'s; the
 //! queue slots live in [`BattlefieldQueue`]; the scoreboard is [`crate::ui_battlefield_score`]'s.
 //!
-//! - **The list** (`SMSG_BATTLEFIELD_LIST`, §4.1) is the battlemaster's guid, the map, the bracket
-//!   index and the instance ids. The handler derives the bracket's level pair off the map row
-//!   (`bracket · span + minLevel`, max clamped at 60), fires `BATTLEFIELDS_SHOW`, and only THEN
+//! - **The list** (`SMSG_BATTLEFIELD_LIST`, `0x4aa6c0`) is the battlemaster's guid, the map, the
+//!   bracket index and the instance ids. The handler derives the bracket's level pair off the map
+//!   row (`bracket · span + minLevel`, max clamped at 60), fires `BATTLEFIELDS_SHOW`, and only THEN
 //!   anchors the player's position — the leash below measures from it.
-//! - **The leash** (§7.1): a world tick fires `BATTLEFIELDS_CLOSED` once the player is strictly
-//!   more than 5.5556 yd from where the list was opened, and zeroes the anchor first. The stock
-//!   window hides itself on the event; there is no other closer.
+//! - **The leash** (`0x4aa090`): a world tick fires `BATTLEFIELDS_CLOSED` once the player is
+//!   strictly more than 5.5556 yd from where the list was opened, and zeroes the anchor first. The
+//!   stock window hides itself on the event; there is no other closer.
 //! - **The queue view**: every frame the three slots go to the VM with their clock-shaped fields
 //!   reduced — the port deadline, the raw estimated wait, the time waited — and the map names
 //!   resolved (map 0 included: the reference looks a cleared slot's id up like any other).
-//! - **The join** (§5.2): `JoinBattlefield`'s instance and group flag come back from the VM; the
-//!   group leg is refused client-side with message 442 when the map's `MaxPlayers` is below
+//! - **The join** (`0x4a9f60`): `JoinBattlefield`'s instance and group flag come back from the VM;
+//!   the group leg is refused client-side with message 442 when the map's `MaxPlayers` is below
 //!   either the party count or the raid count, and the opcode is chosen by the cached
 //!   battlemaster guid — `CMSG_BATTLEMASTER_JOIN` with it, `CMSG_BATTLEFIELD_JOIN` without.
-//! - **The three speaking handlers** (§4.4/§4.5) print and store nothing: the group verdict
-//!   (deserters / joined `%s` / failed) and the joined-or-left player lines, the latter once the
-//!   name cache answers — the reference's fallback callback, in the shape this app already uses.
-//! - **World enter** (§8) clears the list scalars and the selection (not the queue slots) and
-//!   sends the bodyless `CMSG_BATTLEFIELD_STATUS`, which the server answers slot by slot.
+//! - **The three speaking handlers** (`0x4aacc0`/`0x4aae10`) print and store nothing: the group
+//!   verdict (deserters / joined `%s` / failed) and the joined-or-left player lines, the latter
+//!   once the name cache answers — the reference's fallback callback, in the shape this app
+//!   already uses.
+//! - **World enter** (`0x4a9db0`) clears the list scalars and the selection (not the queue slots)
+//!   and sends the bodyless `CMSG_BATTLEFIELD_STATUS`, which the server answers slot by slot.
 
 use std::time::Instant;
 
@@ -41,14 +41,14 @@ use crate::ui_party::GroupState;
 use crate::ui_script::{UiFeed, UiInput};
 
 /// The leash radius, squared: the CRT initialiser's `fld [0x806574]; fmul` of the `.rdata` f32
-/// `5.55555534362793` (§7.1).
+/// `5.55555534362793`.
 const LEASH_RADIUS_YD: f32 = 5.555_555_3;
 
 /// The leash's degenerate-anchor refusal (`fcomp [0x8029d4]`, `2.384185791015625e-07`): an
 /// anchor this close to the origin is "no list open", never a place to measure from.
 const DEGENERATE_ANCHOR: f32 = 2.384_185_8e-7;
 
-/// `SMSG_GROUP_JOINED_BATTLEGROUND`'s deserters sentinel (`cmp eax,-2`, §4.4).
+/// `SMSG_GROUP_JOINED_BATTLEGROUND`'s deserters sentinel (`cmp eax,-2` in `0x4aacc0`).
 const GROUP_JOIN_DESERTERS: u32 = 0xFFFF_FFFE;
 
 /// The list window's state: the last list, the leash anchor, and what the speaking handlers
@@ -88,7 +88,8 @@ impl Battlefield {
         self.players.push((guid, joined));
     }
 
-    /// The world-enter reset (§8): the list scalars and the anchor go; the queue slots do not.
+    /// The world-enter reset (`0x4a9db0`): the list scalars and the anchor go; the queue slots do
+    /// not.
     fn clear_session(&mut self) {
         self.list = None;
         self.show = false;
@@ -131,7 +132,7 @@ fn list_view(
         .zip(row)
         .map(|(name, r)| BattlefieldMapInfo {
             name: name.to_string(),
-            // The faction-group index (§3.4): 0 for the mask-bit-4 side, 1 for bit 2 — Horde
+            // The faction-group index (`0x5efe00`): 0 for the mask-bit-4 side, 1 for bit 2 — Horde
             // and Alliance in the emulator's naming; the shipped rows carry one text in both.
             description: match faction {
                 Some("Horde") => Some(r.descriptions[0].clone()),
@@ -156,8 +157,8 @@ fn list_view(
     }
 }
 
-/// One slot's VM view at `now`: the three clock-shaped getters reduced (§3.3), the map name
-/// resolved, the bracket pair derived (§4.2).
+/// One slot's VM view at `now`: the three clock-shaped getters reduced (`0x4ab620`, `0x4ab790`,
+/// `0x4ab820`), the map name resolved, the bracket pair derived (`0x4aa850`).
 fn slot_view(
     slot: Option<&(BattlefieldStatus, Instant)>,
     catalog: Option<&MapCatalog>,
@@ -192,7 +193,7 @@ fn slot_view(
     view
 }
 
-/// The as-group refusal (§5.2): the map's `MaxPlayers` must be at least the party count (the
+/// The as-group refusal (`0x4a9f60`): the map's `MaxPlayers` must be at least the party count (the
 /// populated party slots, 0..4 — the members besides us) and the raid roster count. Which
 /// members the reference's raid roster counts is INFERRED here as the wire list's members in a
 /// raid and none in a party; the party count is VERIFIED.
@@ -232,7 +233,7 @@ fn feed_battlefield(
     let now = Instant::now();
 
     if std::mem::take(&mut state.dirty) {
-        // The description's side is the local player's faction group (`0x5efe00(player)`, §3.4)
+        // The description's side is the local player's faction group (`0x5efe00(player)`)
         // — the same answer `UnitFactionGroup("player")` gives, read where it already lives.
         let faction = script
             .eval::<Option<String>>(r#"return (UnitFactionGroup("player"))"#)
@@ -251,11 +252,12 @@ fn feed_battlefield(
 
     if std::mem::take(&mut state.show) {
         script.fire_event("BATTLEFIELDS_SHOW", vec![]);
-        // §4.1 step 7: the anchor is written AFTER the event, from the live player position.
+        // `0x4aa6c0` writes the anchor AFTER the event, from the live player position.
         state.anchor = Some(player.pos);
     }
 
-    // §7.1: strictly farther than the leash from where the list opened → the event, anchor first.
+    // `0x4aa090`: strictly farther than the leash from where the list opened → the event, anchor
+    // first.
     if let Some(anchor) = state.anchor {
         if anchor.length_squared() > DEGENERATE_ANCHOR
             && player.pos.distance_squared(anchor) > LEASH_RADIUS_YD * LEASH_RADIUS_YD
@@ -340,7 +342,7 @@ fn drain_battlefield(
     }
 }
 
-/// The world-enter reset (§8): the list scalars, the selection and the anchor cleared, the
+/// The world-enter reset (`0x4a9db0`): the list scalars, the selection and the anchor cleared, the
 /// queue slots kept, and the bodyless status request sent.
 fn reset_on_world_enter(
     mut entered: MessageReader<EnteredWorldMessage>,
@@ -358,10 +360,40 @@ fn reset_on_world_enter(
     let _ = commands.0.send(ClientCommand::BattlefieldStatusRequest);
 }
 
+/// The battlemaster window's packet handlers (in the net handler table since 2313).
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::Battlefield;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handlers — called from [`super::BattlefieldPlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::BattlefieldList, on_packet)
+            .net_handler(K::GroupJoinedBattleground, on_packet)
+            .net_handler(K::BattlegroundPlayer, on_packet);
+    }
+
+    /// One handler for the three: each is a one-line fold into the same state.
+    fn on_packet(In(ev): In<SessionEvent>, mut battlefield: ResMut<Battlefield>) {
+        match ev {
+            SessionEvent::BattlefieldList(list) => battlefield.apply_list(list),
+            SessionEvent::GroupJoinedBattleground { result } => battlefield.apply_verdict(result),
+            SessionEvent::BattlegroundPlayer { guid, joined } => {
+                battlefield.apply_player(guid, joined)
+            }
+            _ => {}
+        }
+    }
+}
+
 pub(crate) struct BattlefieldPlugin;
 
 impl Plugin for BattlefieldPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<Battlefield>().add_systems(
             Update,
             (
diff --git a/crates/benilla-app/src/ui_battlefield_positions.rs b/crates/benilla-app/src/ui_battlefield_positions.rs
index 0b8aa1c1..115c0332 100644
--- a/crates/benilla-app/src/ui_battlefield_positions.rs
+++ b/crates/benilla-app/src/ui_battlefield_positions.rs
@@ -1,5 +1,5 @@
-//! The battleground **teammate and flag positions** on the world map (decision 1980; wow-re
-//! `worldmap-arrow-and-positions.md` §3): `MSG_BATTLEGROUND_PLAYER_POSITIONS` both ways, resolved
+//! The battleground **teammate and flag positions** on the world map (decision 1980):
+//! `MSG_BATTLEGROUND_PLAYER_POSITIONS` both ways, resolved
 //! into the engine's `GetBattlefieldPosition` / `GetBattlefieldFlagPosition` /
 //! `GetBattlefieldMapIconScale` backing the stock `WorldMapFrame.lua` and
 //! `Blizzard_BattlefieldMinimap.lua` poll every update.
@@ -223,10 +223,31 @@ fn reset_on_world_enter(
     state.last_request = None;
 }
 
+/// The battlefield map's packet handler (in the net handler table since 2313).
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::BattlefieldPositions;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handler — called from [`super::BattlefieldPositionsPlugin`].
+    pub(super) fn register(app: &mut App) {
+        app.net_handler(SessionEventKind::BattlefieldPositions, on_positions);
+    }
+
+    fn on_positions(In(ev): In<SessionEvent>, mut positions: ResMut<BattlefieldPositions>) {
+        if let SessionEvent::BattlefieldPositions(packet) = ev {
+            positions.apply(packet);
+        }
+    }
+}
+
 pub(crate) struct BattlefieldPositionsPlugin;
 
 impl Plugin for BattlefieldPositionsPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<BattlefieldPositions>().add_systems(
             Update,
             (
diff --git a/crates/benilla-app/src/ui_battlefield_score.rs b/crates/benilla-app/src/ui_battlefield_score.rs
index d058da2d..a267a42a 100644
--- a/crates/benilla-app/src/ui_battlefield_score.rs
+++ b/crates/benilla-app/src/ui_battlefield_score.rs
@@ -1,20 +1,22 @@
-//! The battleground **scoreboard** feed (decision 1972; wow-re `battlefield-verb-family.md`):
+//! The battleground **scoreboard** feed (decision 1972):
 //! the app's half of the stock `WorldStateFrame.lua` score frame — the name-resolution barrier,
 //! the team derivation, the column headers, the request throttle and the leave.
 //!
 //! - **The board arrives raw** (`MSG_PVP_LOG_DATA`, GUIDs and numbers, wire order) and the
-//!   reference does nothing with it until EVERY row's name has resolved (§6.1: the last name
-//!   arrival is what rebuilds and fires). Ours asks the name cache for each row every frame it
-//!   is unresolved and pushes the board the frame the last one lands.
-//! - **Team is derived, never wire data** (§6.2): race → faction; `0` Horde, `1` Alliance, `-1`
-//!   for a race the tables do not carry. Race and class strings come off the same traits the
+//!   reference does nothing with it until EVERY row's name has resolved (`0x4aa580` → `0x4aa200`:
+//!   the last name arrival is what rebuilds and fires). Ours asks the name cache for each row every
+//!   frame it is unresolved and pushes the board the frame the last one lands.
+//! - **Team is derived, never wire data** (`0x4aa200`): race → faction; `0` Horde, `1` Alliance,
+//!   `-1` for a race the tables do not carry. Race and class strings come off the same traits the
 //!   name query answered with.
-//! - **Columns are `WorldStateUI.dbc` rows** (`worldstate-ui-law.md`, the `0x2D4` status-3 arm):
+//! - **Columns are `WorldStateUI.dbc` rows** (the `0x2D4` status-3 arm, `0x4aa9c3`–`0x4aaa17`):
 //!   in table order, the first contiguous run of rows whose `MapID` is the battleground's map or
 //!   `-1` and whose `Type` is 2; the text raw, the icon, the tooltip.
 //! - **`UPDATE_BATTLEFIELD_SCORE`** fires here — on a pushed board, and on the status-3 arrival
-//!   the queue flags — BEFORE the queue feed fires `UPDATE_BATTLEFIELD_STATUS` (§4.2's order).
-//! - **The request is throttled to 5000 ms** (§5.1) and the leave carries the active map (§5.3).
+//!   the queue flags — BEFORE the queue feed fires `UPDATE_BATTLEFIELD_STATUS` (`0x4aaa5a` before
+//!   `0x4aab05`).
+//! - **The request is throttled to 5000 ms** (`0x4aa170`) and the leave carries the active map
+//!   (`LeaveBattlefield 0x4abe60`).
 
 use std::time::{Duration, Instant};
 
@@ -32,7 +34,8 @@ use crate::world_state_ui::WorldStateUiRes;
 /// `RequestBattlefieldScoreData`'s throttle — `0x4aa170`: `now + 0x1388`.
 const REQUEST_THROTTLE: Duration = Duration::from_millis(5000);
 
-/// The last `MSG_PVP_LOG_DATA`, and the request stamp.
+/// The last `MSG_PVP_LOG_DATA`, and the request stamp. Both die with the session
+/// (`net::on_session_end`).
 #[derive(Resource, Default)]
 pub(crate) struct BattlefieldScoreboard {
     log: Option<PvpLogData>,
@@ -171,10 +174,39 @@ fn drain_battlefield_score(
     }
 }
 
+/// The scoreboard's packet handler (in the net handler table since 2313).
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::BattlefieldScoreboard;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handler — called from [`super::BattlefieldScorePlugin`].
+    pub(super) fn register(app: &mut App) {
+        app.net_handler(SessionEventKind::PvpLogData, on_pvp_log_data)
+            .net_handler(SessionEventKind::Disconnected, on_session_end);
+    }
+
+    /// The board and the request stamp are zeroed at every login (module init `0x4a9c40` zeroes
+    /// the score scalars) — a listener on the session end (a second handler on the kind, after the
+    /// bridge's own teardown).
+    fn on_session_end(In(_): In<SessionEvent>, mut board: ResMut<BattlefieldScoreboard>) {
+        *board = BattlefieldScoreboard::default();
+    }
+
+    fn on_pvp_log_data(In(ev): In<SessionEvent>, mut board: ResMut<BattlefieldScoreboard>) {
+        if let SessionEvent::PvpLogData(data) = ev {
+            board.apply(data);
+        }
+    }
+}
+
 pub(crate) struct BattlefieldScorePlugin;
 
 impl Plugin for BattlefieldScorePlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<BattlefieldScoreboard>().add_systems(
             Update,
             (
@@ -234,4 +266,36 @@ mod tests {
             .collect();
         assert_eq!(cols, ["Flags Returned"]);
     }
+
+    /// **The board is zeroed at every login** (module
+    /// init `0x4a9c40`, from `InitializeGame`, zeroes the score scalars) — the last session's
+    /// `MSG_PVP_LOG_DATA` must not come back as the next character's scoreboard, and its request
+    /// stamp must not throttle that character's first ask.
+    #[test]
+    fn the_session_end_zeroes_the_scoreboard() {
+        let mut app = App::new();
+        app.init_resource::<BattlefieldScoreboard>();
+        net::register(&mut app);
+        {
+            let mut board = app.world_mut().resource_mut::<BattlefieldScoreboard>();
+            board.apply(PvpLogData {
+                ended: true,
+                winner: Some(1),
+                rows: Vec::new(),
+            });
+            board.last_request = Some(Instant::now());
+        }
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![benilla_protocol::SessionEvent::Disconnected {
+                reason: "socket".into(),
+                end: benilla_protocol::SessionEnd::Lost,
+            }],
+        );
+
+        let board = app.world().resource::<BattlefieldScoreboard>();
+        assert!(board.log.is_none());
+        assert!(board.last_request.is_none());
+    }
 }
diff --git a/crates/benilla-app/src/ui_bind_confirm.rs b/crates/benilla-app/src/ui_bind_confirm.rs
index d0fd018c..b03133f3 100644
--- a/crates/benilla-app/src/ui_bind_confirm.rs
+++ b/crates/benilla-app/src/ui_bind_confirm.rs
@@ -4,8 +4,8 @@
 //!
 //! ## The three predicates are three different predicates
 //!
-//! VERIFIED at the 1.12.1 bytes (wow-re `system/object-layer/scratch/bind-confirm-law.md`), one
-//! `item_template + 0x194` compare per arm and **no `+0x1c` (quality) read in any of the three**:
+//! In the 1.12.1 client, one `item_template + 0x194` compare per arm and **no `+0x1c` (quality)
+//! read in any of the three**:
 //!
 //! | arm | event | fires from | predicate | site |
 //! |---|---|---|---|---|
@@ -16,8 +16,8 @@
 //!
 //! Carrying the loot arm's `quality >= 2` across would have been wrong twice over: it would have
 //! silenced the confirm on a white BoE, and it would have asked about the wrong `bonding` value
-//! entirely. (This was benilla's working assumption until the RE refuted it; that is why the table
-//! is here and not a sentence.)
+//! entirely. (This was benilla's working assumption until the reference refuted it; that is why the
+//! table is here and not a sentence.)
 //!
 //! ## The other conjuncts, and where benilla already had them
 //!
@@ -48,8 +48,8 @@
 //!
 //! ## The index space is the reference's own
 //!
-//! `arg1` is a **0-based index into the pending array**, not a slot (wow-re corrected benilla's
-//! assumption here). It is opaque on both sides — the event hands it out, `dialog.data` carries it,
+//! `arg1` is a **0-based index into the pending array**, not a slot (allocated by `0x5e1110`).
+//! It is opaque on both sides — the event hands it out, `dialog.data` carries it,
 //! and the two verbs hand it straight back — so unlike the loot arm's row number (1744, translated
 //! into benilla's display space) there is nothing to gain by re-basing it, and it is kept as-is.
 
@@ -59,6 +59,7 @@ use bevy::prelude::*;
 use benilla_ui::script::{ScriptValue, UiScript};
 
 use crate::items::{Enchants, Items};
+use crate::net::Objects;
 
 /// `item_template.bonding` — the values the three arms compare against (vmangos
 /// `ItemPrototype.h`'s `ItemBondingType`; the client reads the same field at `+0x194`).
@@ -147,7 +148,7 @@ pub(crate) struct PendingBindOnUse(pub(crate) Option<PendingUse>);
 pub(crate) type PendingUse = crate::ui_items::ItemUse;
 
 /// The three resources the deferral needs, bundled so a drain can take them in one parameter
-/// (the shape `crate::ui_action::CastLadder` established). [`Items`] is deliberately NOT in here:
+/// (the shape `crate::spell::CastLadder` established). [`Items`] is deliberately NOT in here:
 /// every caller already holds it, and a second `ResMut<Items>` in one system is a conflict.
 #[derive(SystemParam)]
 pub(crate) struct BindGate<'w> {
@@ -169,17 +170,18 @@ impl BindGate<'_> {
     pub(crate) fn equip_binds(
         &self,
         script: &UiScript,
+        objects: &Objects,
         items: &Items,
         commands: &crate::net::NetCommands,
         item_guid: u64,
     ) -> bool {
-        let Some(fields) = items.object(item_guid) else {
+        let Some(fields) = objects.object(item_guid) else {
             return false;
         };
         if crate::items::already_bound(fields, self.enchants.as_deref()) {
             return false;
         }
-        let Some(entry) = items.object(item_guid).and_then(|o| o.object_entry()) else {
+        let Some(entry) = objects.object(item_guid).and_then(|o| o.object_entry()) else {
             return false;
         };
         let Some(t) = items.template(entry, item_guid, commands) else {
@@ -198,17 +200,18 @@ impl BindGate<'_> {
     /// the fire site is reached the item has already passed it.
     pub(crate) fn use_binds(
         &self,
+        objects: &Objects,
         items: &Items,
         commands: &crate::net::NetCommands,
         item_guid: u64,
     ) -> bool {
-        let Some(fields) = items.object(item_guid) else {
+        let Some(fields) = objects.object(item_guid) else {
             return false;
         };
         if crate::items::already_bound(fields, self.enchants.as_deref()) {
             return false;
         }
-        let Some(entry) = items.object(item_guid).and_then(|o| o.object_entry()) else {
+        let Some(entry) = objects.object(item_guid).and_then(|o| o.object_entry()) else {
             return false;
         };
         items
diff --git a/crates/benilla-app/src/ui_binder.rs b/crates/benilla-app/src/ui_binder.rs
index 22a0feec..ee5bd47d 100644
--- a/crates/benilla-app/src/ui_binder.rs
+++ b/crates/benilla-app/src/ui_binder.rs
@@ -18,9 +18,8 @@
 //!   frame it goes false.
 //!
 //! Both halves are now **byte-pinned** against the reference's own handler `0x5dfdc0` and its
-//! `SMSG_BINDER_CONFIRM` arm `0x5e4aa2` (wow-re
-//! `system/ui/scratch/gossip-icon-and-binder-flow.md`; folded back by decision 1335, which
-//! promotes what decision 1331 had to leave INFERRED):
+//! `SMSG_BINDER_CONFIRM` arm `0x5e4aa2` (folded back by decision 1335, which promotes what
+//! decision 1331 had to leave INFERRED):
 //!
 //! 1. **`arg1` is an AREA name, never the NPC's** — the handler never looks a name up. It resolves
 //!    the player's own **sub-area** through `AreaTable.dbc`, falls back to the **parent zone** when
@@ -148,8 +147,8 @@ fn area_name(
 /// [`area_name`]'s chain over a bare leaf id — split out so the three legs are testable against the
 /// real `AreaTable` without standing up a world.
 ///
-/// The tail is the `HOME_INN` GlobalString (`GetBindLocation` uses the identical fallback, which is
-/// how wow-re cross-checked the order), read off the player's own table rather than re-typed
+/// The tail is the `HOME_INN` GlobalString (`GetBindLocation 0x48dae0` uses the identical
+/// fallback), read off the player's own table rather than re-typed
 /// (decision 2045); an install that does not carry it yields the empty string, which is the
 /// reference's data-suppression face and still fires the question.
 fn area_name_of(
@@ -207,14 +206,49 @@ fn drain_binder(
 /// silent but still audible, which is the reference's own ordering rather than an accident of ours.
 const SOUND_PLAYERBOUND: u32 = 1141;
 
-/// The net drain's `SessionEvent::PlayerBound` arm, factored here so the wire law lives beside the
-/// state it drives.
-pub(crate) mod apply {
+/// The innkeeper's packet handlers (in the net handler table since 2312), beside the state they
+/// drive.
+pub(crate) mod net {
     use super::*;
 
     use bevy::ecs::message::MessageWriter;
 
     use crate::net::{ServerSoundKind, ServerSoundMessage};
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+
+    use crate::net::NetHandlerApp;
+
+    /// Register the binder's handlers — called from [`UiBinderPlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::BinderConfirm, on_confirm)
+            .net_handler(K::PlayerBound, on_bound);
+    }
+
+    fn on_confirm(In(ev): In<SessionEvent>, mut binder: ResMut<BinderState>) {
+        if let SessionEvent::BinderConfirm { binder: npc } = ev {
+            binder.ask(npc);
+        }
+    }
+
+    fn on_bound(
+        In(ev): In<SessionEvent>,
+        mut binder: ResMut<BinderState>,
+        mut errors: ResMut<crate::ui_action::UiErrorKeys>,
+        areas: Option<Res<AreaTableRes>>,
+        mut sounds: MessageWriter<ServerSoundMessage>,
+    ) {
+        if let SessionEvent::PlayerBound { binder: npc, area } = ev {
+            debug!("net: bound to area {area} by {npc:#x}");
+            bound(
+                area,
+                &mut binder,
+                &mut errors,
+                areas.as_deref(),
+                &mut sounds,
+            );
+        }
+    }
 
     /// `SMSG_PLAYERBOUND` — the bind took. Retract the question, play the sound, and queue
     /// `DisplayError(0x138)` = `ERR_DEATHBIND_SUCCESS_S` (catalog row 312, `kind 0` — a system
@@ -260,6 +294,7 @@ pub(crate) struct UiBinderPlugin;
 
 impl Plugin for UiBinderPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<BinderState>().add_systems(
             Update,
             (
diff --git a/crates/benilla-app/src/ui_cast.rs b/crates/benilla-app/src/ui_cast.rs
index c8b30405..ec72b56d 100644
--- a/crates/benilla-app/src/ui_cast.rs
+++ b/crates/benilla-app/src/ui_cast.rs
@@ -1,20 +1,26 @@
-//! The cast-bar feed: our own cast lifecycle, wire → FrameXML events (decision 0137 phase 1).
+//! The cast-bar feed: the wire's cast edges → FrameXML events (decision 0137 phase 1).
 //!
-//! The net bridge queues [`CastBarEdge`]s (self-casts only — the producers filter on the self
-//! guid; the channel pair is self-only *on the wire*), and the drain fires the reference
-//! client's FrameScript events into the script VM — `SPELLCAST_START` and family, the exact
-//! contract stock `Interface\FrameXML\CastingBarFrame.xml` registers for.
+//! The spell's packet handlers and its local cancel (`crate::spell`) queue [`CastBarEdge`]s
+//! (self-casts only — the producers filter on the self guid; the channel pair is self-only *on
+//! the wire*), and the drain fires the reference client's FrameScript events into the script VM
+//! — `SPELLCAST_START` and family, the exact contract stock
+//! `Interface\FrameXML\CastingBarFrame.xml` registers for — and pushes the VM's casting flag.
 //! The spell name rides the event (resolved here from the `Spell.dbc` catalog — the script VM
 //! has no spell-catalog binding, deliberately: one lookup face, decision 0107).
+//!
+//! This is a feed and nothing else. The lifecycle it reads — the pending cast, the queued
+//! strike, the running channel, the auto-repeat key — is the spell's (`crate::spell`, decision
+//! 2328).
 
-use std::time::{Duration, Instant};
+use std::time::Instant;
 
 use bevy::prelude::*;
 
 use benilla_ui::script::{ScriptValue, UiScript};
 
-use crate::creature_anim::{CastEvent, CastEventKind, Casting, PlaySeq};
-use crate::net::{ClientCommand, GuidIndex, NetCommands, SelfGuid};
+use crate::creature_anim::Casting;
+use crate::net::{GuidIndex, SelfGuid};
+use crate::spell::{inflight, PendingCast, QueuedMeleeSpell};
 use crate::ui_action::Spells;
 use crate::ui_unit::UnitFeed;
 
@@ -44,519 +50,8 @@ pub(crate) enum CastBarEdge {
 #[derive(Resource, Default)]
 pub(crate) struct CastBarFeed(pub(crate) Vec<CastBarEdge>);
 
-/// Provisional in-flight window armed at send, before `SMSG_SPELL_START` names the real cast time.
-/// It only has to outlast the send→START round trip; an instant, whose `SMSG_SPELL_GO` clears the
-/// guard first, never reaches it. Generous on purpose — the resolution packets do the real clearing.
-const SEND_PROVISIONAL: Duration = Duration::from_secs(5);
-
-/// The same provisional for an **item** use's cast ([`PendingCast::arm_item`]) — deliberately much
-/// tighter, because the two arms have different worst cases *on this wire*. Every
-/// `CMSG_CAST_SPELL` vmangos accepts is answered (`Spell::SendCastResult` on any rejection,
-/// `SMSG_SPELL_START`/`GO` otherwise), so a spell's guard is always cleared by a packet and
-/// [`SEND_PROVISIONAL`] never actually governs. `CMSG_USE_ITEM` has legs that answer with
-/// `SMSG_INVENTORY_CHANGE_FAILURE` and **no cast result at all** — `HandleUseItemOpcode`'s
-/// equip-error gates (`CanUseItem`, the in-combat non-combat-spell refusal, item-not-found) —
-/// and there the provisional IS the safety net, so it has to be short enough that a silently
-/// refused use cannot lock casting out for long. It only ever covers the send→`SMSG_SPELL_START`
-/// window anyway: [`PendingCast::refine`] stretches the guard to the server's real cast time the
-/// moment START names it, so a use that *does* become a cast is guarded for its whole length.
-const ITEM_SEND_PROVISIONAL: Duration = Duration::from_millis(1_500);
-
-/// Pushback slack added to the server's cast time at `SMSG_SPELL_START`, so a cast the server
-/// delays (`SMSG_SPELL_DELAYED`) still guards past its stretched end.
-const CAST_SLACK: Duration = Duration::from_secs(2);
-
-/// Our own outstanding cast — the client's optimistic in-flight guard, and the fix for the
-/// spam-cancel bug. wow-re `wave-cast.md`: `TryCast 0x6e4b60` refuses to send a second
-/// `CMSG_CAST_SPELL` while `IsCasting 0x6e3d30` (the inflight-spell-id `0xceca88`) is set — the
-/// same-spell press bails **silently** at `6e4d43`; a different spell hits the
-/// `[SpellRec+0x18] & 0x404` gate at `6e4d97`: when the *inflight* rec lacks those bits (an
-/// ordinary cast — Fireball is `0x10000`), it errors 0x61 without sending; when the inflight IS
-/// on-next-swing (a queued Heroic Strike), the new cast passes and nests around it (mask and
-/// operand §5-confirmed byte-exact, wow-re `combat-feel-law.md` @ c445713b — exactly `0x404`, on
-/// the inflight rec, no channel leg: Slam mid-cast blocks Battle Shout). In our model
-/// the on-next-swing class never occupies this guard at all — it arms [`QueuedMeleeSpell`]
-/// instead — so this guard only ever holds ordinary casts and the gate needs no attribute test.
-/// Ours was server-driven: every mashed key fired a *duplicate* cast, the
-/// server rejected the dupe with `SMSG_CAST_RESULT` failure, and that turned the running cast's bar
-/// red while the original completed later. This marker drops the duplicate at the source, exactly
-/// as the client does.
-///
-/// It is **optimistic** — armed the instant we send, not when the server's `SMSG_SPELL_START`
-/// echoes back — because the spam lands during that round trip. Cleared by the cast's resolution
-/// (`SMSG_SPELL_GO` / a failing `SMSG_CAST_RESULT` / `SMSG_SPELL_FAILED_OTHER`), spell-id-keyed like
-/// the `Casting` reap — and by the local self-cancel directly ([`local_self_cancel`], the
-/// client's `AbortCast 0x6e4940` mirrored since 0444). `deadline` is the safety net for a
-/// resolution that goes missing on the wire: armed generously and tightened to the real cast
-/// time once `SMSG_SPELL_START` names it.
-#[derive(Resource, Default)]
-pub(crate) struct PendingCast(Option<PendingCastState>);
-
-struct PendingCastState {
-    spell_id: u32,
-    deadline: Instant,
-    /// Does this record **guard** — i.e. does it refuse the next press, light the in-flight ring,
-    /// and gate the by-name walk? True for the classes benilla lets occupy the guard: ordinary
-    /// casts and item uses.
-    ///
-    /// The reference has no such flag, because it has no such split: `[0xceca88]` is written for
-    /// **every** committed cast (`0x6e5026 call 0x6e4ad0` inside TryCast) and the *gate* does the
-    /// discriminating instead, on the inflight rec's `Attributes & 0x404` at `6e4d97`. Ours grew
-    /// up the other way round — the guard is armed only for the classes it refuses on, so a
-    /// ranged shot was never recorded as committed **at all**.
-    ///
-    /// That gap is what shipped B280 broken twice: the `modalNextSpell` chain
-    /// (`crate::net::apply::spells::cast_result`) has to answer the reference's `0x6e7408 cmp
-    /// ecx,[0xceca88]` — "is this reply for the cast I just sent?" — and every hunter shot is
-    /// `Attributes & 0x2` ranged, so the answer was always no and the chain never fired in play.
-    /// The flag closes it without touching the three consumers that were right: the record is now
-    /// armed for every commit ([`PendingCast::committed`] reads it), and `guards` keeps
-    /// [`PendingCast::in_flight`] / [`PendingCast::current`] answering exactly what they did.
-    guards: bool,
-}
-
-impl PendingCast {
-    /// Whether a **guarding** cast we sent is still outstanding (unresolved and inside its safety
-    /// deadline) — the refusal's own question. A ranged shot is committed but does not guard.
-    pub(crate) fn in_flight(&self, now: Instant) -> bool {
-        self.0
-            .as_ref()
-            .is_some_and(|p| p.guards && now < p.deadline)
-    }
-
-    /// **The reference's `[0xceca88]` proper** — the id of the cast we last committed and have not
-    /// yet had a resolution for, whatever its class. This is what `HandleCastResult 0x6e7330`
-    /// tests at `0x6e7408` before it reads `modalNextSpell`, and the only read that must see a
-    /// ranged shot. Everything else about the record is unchanged; see [`PendingCastState::guards`]
-    /// for why the two questions are separate fields here and one global there.
-    pub(crate) fn committed(&self, now: Instant) -> Option<u32> {
-        self.0
-            .as_ref()
-            .filter(|p| now < p.deadline)
-            .map(|p| p.spell_id)
-    }
-
-    /// The outstanding cast's spell id, if one is in flight — the app-side mirror of the client's
-    /// current-cast read (`0xceca88`), which `IsCurrentAction`'s checked state keys on (decision
-    /// 0137 phase 4).
-    pub(crate) fn current(&self, now: Instant) -> Option<u32> {
-        self.0
-            .as_ref()
-            .filter(|p| p.guards && now < p.deadline)
-            .map(|p| p.spell_id)
-    }
-
-    /// Arm on a fresh send — the optimistic `0xceca88` write at the client's cast-send. `guards`
-    /// says whether this class also occupies the refusal ([`PendingCastState::guards`]): ordinary
-    /// casts do, a ranged shot is recorded and does not.
-    pub(crate) fn arm(&mut self, spell_id: u32, now: Instant, guards: bool) {
-        self.0 = Some(PendingCastState {
-            spell_id,
-            deadline: now + SEND_PROVISIONAL,
-            guards,
-        });
-    }
-
-    /// Arm the guard on an **item** use's send. The reference has no separate item-cast slot: the
-    /// item-use dispatcher's cast tail (`CGItem::Use 0x5d8d00` @ `0x5d9258`) calls `0x6e5a90`,
-    /// whose entire 54-byte body is `call 0x6e4b60` — `TryCast` itself (VERIFIED at the bytes,
-    /// wow-re `disasm-full.txt`; corroborated by its `action-button-state-api.md` §"dispatcher
-    /// `0x6e5a90` (→ `CastSpell 0x6e4b60`)" and `cursor-system.md` §536). So an item use writes
-    /// the SAME inflight id (`0xceca88`) and is refused by the same IsCasting gate — which is why
-    /// [`crate::ui_items::send_item_use`] runs both. Differs from [`PendingCast::arm`] only in the
-    /// deadline ([`ITEM_SEND_PROVISIONAL`], whose doc is the why).
-    pub(crate) fn arm_item(&mut self, spell_id: u32, now: Instant) {
-        self.0 = Some(PendingCastState {
-            spell_id,
-            deadline: now + ITEM_SEND_PROVISIONAL,
-            guards: true,
-        });
-    }
-
-    /// Tighten the deadline to the server's real cast time once `SMSG_SPELL_START` names it.
-    pub(crate) fn refine(&mut self, cast_time_ms: u32, now: Instant) {
-        if let Some(p) = &mut self.0 {
-            p.deadline = now + Duration::from_millis(u64::from(cast_time_ms)) + CAST_SLACK;
-        }
-    }
-
-    /// Push the deadline out by a pushback (`SMSG_SPELL_DELAYED`), so the guard keeps holding past
-    /// the stretched cast end. Extends from whichever is later (the current deadline or now), so a
-    /// deadline already lapsed from an under-estimate still re-arms.
-    pub(crate) fn delay(&mut self, delay_ms: u32, now: Instant) {
-        if let Some(p) = &mut self.0 {
-            p.deadline = p.deadline.max(now) + Duration::from_millis(u64::from(delay_ms));
-        }
-    }
-
-    /// Clear the guard when the resolving spell is our outstanding one (spell-id-keyed, like the
-    /// `Casting` reap — a triggered proc's `SMSG_SPELL_GO` mid-cast must not open the gate early).
-    pub(crate) fn clear_if(&mut self, spell_id: u32) {
-        if self.0.as_ref().is_some_and(|p| p.spell_id == spell_id) {
-            self.0 = None;
-        }
-    }
-}
-
-/// Our own queued **on-next-swing** spell (Heroic Strike, Cleave — `Attributes & 0x404`) — the
-/// melee-slot half of the client's cast tracking. In the reference the queued spell *occupies*
-/// the inflight id (`0xceca88`) until the swing fires it, and the already-casting refusal at
-/// `6e4d97` exempts new casts because the inflight rec has the `0x404` bits — so a queued Heroic
-/// Strike never blocks Rend, and the new cast nests around it (`PushPopNestedCast 0x6e4ad0`
-/// restores the queued id when the nested cast resolves; wow-re `wave-cast.md`). We model the
-/// same observable with a second slot instead of the push/pop pair: [`PendingCast`] keeps
-/// ordinary casts, this keeps the melee queue, and the checked ring reads both (the ref's
-/// `IsCurrentAction` C2 leg — spell == inflight — holds through the nesting either way, minus
-/// the ref's one-RTT un-check blink while the nested cast displaces the slot).
-///
-/// **Deadline-less, wire-cleared** — like the ref's inflight id, which no timer touches. The
-/// clear set is deliberately wider than the ref's: the §5 (`combat-feel-law.md` @ c445713b)
-/// pinned that the ref clears inflight/saved ONLY on a matching `SMSG_CAST_RESULT` (`0x6e7330`;
-/// the GO handler never touches `0xceca88`) — but vmangos never sends an OK `CAST_RESULT` at
-/// all, so on our wire the resolution is `SMSG_SPELL_GO` when the swing fires the strike, and a
-/// failing `CAST_RESULT` + `SPELL_FAILED_OTHER` when it dies (vmangos `Spell::cancel` on the
-/// PREPARING melee slot sends both — target death, manual cancel, replacement). We clear on any
-/// of the three, id-keyed: identical observable where `0x130` does arrive, correct where it
-/// never does. Re-arming replaces silently: the server holds a single `CURRENT_MELEE_SPELL`
-/// slot. Re-pressing the queued spell itself is the ref's silent same-spell bail — §5-CONFIRMED
-/// (`6e4d43`: debug-log, `xor al,al`, no CMSG, no error): 1.12 has no re-press-to-unqueue. The
-/// real un-queue is the StopAttack chain (`0x5ecac0` → `CancelQueuedCast 0x6e6f30`, sending
-/// `CMSG_ATTACKSTOP` + `CMSG_CANCEL_CAST`), reached by /stopattack, the Attack-button toggle,
-/// **an auto-repeat press** (`0x6e5976`), target change/death, mount, interact — never movement.
-/// That chain is [`crate::creature_anim::stop_attack_local`], and the auto-repeat arm inside
-/// [`crate::ui_action::cast_send`]'s commit runs it whole: starting Auto Shot un-queues the
-/// strike, which is what darkens its checked ring. Every attack edge reaches that seam since
-/// 1044 — the Attack toggle, a target switch, a click-off, the ring's death teardown.
-///
-/// **Escape is the other route, and it is not that chain at all** (1049). In the reference a
-/// queued strike simply *is* the inflight spell, so `Script::SpellStopCasting 0x6e6e80`'s plain
-/// `IsCasting 0x6e3d30` branch cancels it like any cast — no melee-specific code anywhere in it.
-/// [`Inflight`] is where our two slots are re-joined for that reader.
-#[derive(Resource, Default)]
-pub(crate) struct QueuedMeleeSpell(Option<u32>);
-
-impl QueuedMeleeSpell {
-    /// The queued spell's id, if one is waiting on the next swing — what the checked ring and
-    /// the re-press bail read.
-    pub(crate) fn current(&self) -> Option<u32> {
-        self.0
-    }
-
-    /// Queue a fresh on-next-swing send (replacing any prior queue — the server's single slot).
-    pub(crate) fn arm(&mut self, spell_id: u32) {
-        self.0 = Some(spell_id);
-    }
-
-    /// Clear on the wire resolution (`SMSG_SPELL_GO` / a failing `SMSG_CAST_RESULT` /
-    /// `SMSG_SPELL_FAILED_OTHER`), spell-id-keyed like every reap.
-    pub(crate) fn clear_if(&mut self, spell_id: u32) {
-        if self.0 == Some(spell_id) {
-            self.0 = None;
-        }
-    }
-}
-
-/// What the reference's single inflight spell id (`0xceca88`) holds — as our **two** slots see it.
-///
-/// The client has one slot, with one save beneath it for the nesting. An ordinary cast and a
-/// queued on-next-swing strike both live in `0xceca88`, which is exactly why `IsCasting 0x6e3d30`
-/// — a bare `ceca88 != 0` — answers true for either, and why `AbortCast 0x6e4940` cancels
-/// whichever is there without ever asking which kind it was. [`PendingCast`] and
-/// [`QueuedMeleeSpell`] split that one slot in two (its doc says why), which leaves every reader
-/// of *"what is in flight"* to re-join them — and the one reader that forgot was the Esc ladder,
-/// which is the bug decision 1049 fixes. So the join gets a name, once, here.
-///
-/// **The order is the reference's nesting, not a preference.** An ordinary cast started over a
-/// queued strike is allowed through `TryCast`'s already-casting refusal precisely because the
-/// inflight rec has `Attributes & 0x404` (`0x6e4d97`/`0x6e4dbe`), and it *pushes*
-/// (`PushPopNestedCast 0x6e4ad0` @ `0x6e5026`): the cast becomes `0xceca88`, the strike the save
-/// in `0xcecaa8`. `AbortCast` cancels the cast and pops the strike back up — so the cast dies on
-/// the first Esc and the strike on the second. Reading `PendingCast` first reproduces that
-/// without our needing the push/pop pair.
-///
-/// One knowing divergence there, pinned by wow-re's `spell/scratch/esc-queued-strike.md` §Q(c)
-/// and weighed in decision 1058: the ref's pop *reads* `0xcecaa8` and never writes it, so a
-/// second Esc re-asserts the same strike locally and only the server echo converges it. We have
-/// no separate save slot to go stale, so ours clears. The two agree everywhere it shows: in the
-/// un-nested case the ref's pop reads a zero save and clears too, and in the nested case vmangos
-/// drops the melee slot on press **1** regardless (`HandleCancelCastOpcode` is spellId-blind
-/// about `CURRENT_MELEE_SPELL`), so both clients converge off that echo. Reproducing the
-/// re-assert would mean modelling `0xcecaa8` as a third slot to hold a value that is stale by
-/// construction, for a window one localhost round trip wide.
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub(crate) enum Inflight {
-    /// An ordinary cast — ours to send-guard, to paint a bar for, and to reap.
-    Cast(u32),
-    /// A queued on-next-swing strike waiting for the swing. No bar ever opened for it and it
-    /// holds no [`Casting`], so cancelling it is the wire message and the slot, nothing else.
-    Strike(u32),
-}
-
-impl Inflight {
-    /// The spell id in the slot — what a cancel names on the wire, either way.
-    pub(crate) fn spell_id(self) -> u32 {
-        match self {
-            Self::Cast(id) | Self::Strike(id) => id,
-        }
-    }
-}
-
-/// Resolve the reference's inflight slot from our two — see [`Inflight`] for the order and the
-/// why. `started` is the self [`Casting`] spell id, which covers a cast that never armed the send
-/// guard (an item use) exactly as the ref's one id covers it.
-pub(crate) fn inflight(
-    pending: &PendingCast,
-    queued_melee: &QueuedMeleeSpell,
-    started: Option<u32>,
-    now: Instant,
-) -> Option<Inflight> {
-    pending
-        .current(now)
-        .or(started)
-        .map(Inflight::Cast)
-        .or_else(|| queued_melee.current().map(Inflight::Strike))
-}
-
-/// Slack past the server-named channel end, so a lost/late `MSG_CHANNEL_UPDATE(0)` can't pin the
-/// checked ring on forever — the natural end clears through the deadline instead.
-const CHANNEL_SLACK: Duration = Duration::from_secs(2);
-
-/// Our own running channel — the app-side mirror of the client's current-channel id (`0xceac58`,
-/// read live-gated by the channeling word: the §5's `IsCurrentAction` channel leg,
-/// `action-button-state-api.md` §3 — a channeled spell's button stays checked while its channel
-/// runs). Set at `MSG_CHANNEL_START`, refreshed by nonzero `MSG_CHANNEL_UPDATE`s, cleared by the
-/// `UPDATE(0)` that ends both the natural finish and the interrupt.
-#[derive(Resource, Default)]
-pub(crate) struct ActiveChannel(Option<(u32, Instant)>);
-
-impl ActiveChannel {
-    /// The running channel's spell id, if one is live.
-    pub(crate) fn current(&self, now: Instant) -> Option<u32> {
-        self.0
-            .filter(|&(_, until)| now < until)
-            .map(|(spell, _)| spell)
-    }
-
-    /// `MSG_CHANNEL_START`: open the window for the named duration (+ slack).
-    pub(crate) fn start(&mut self, spell_id: u32, duration_ms: u32, now: Instant) {
-        self.0 = Some((
-            spell_id,
-            now + Duration::from_millis(u64::from(duration_ms)) + CHANNEL_SLACK,
-        ));
-    }
-
-    /// `MSG_CHANNEL_UPDATE`: `0` ends the channel; anything else re-times the window (pushback
-    /// shortens a channel, so the deadline moves in as well as out).
-    pub(crate) fn update(&mut self, remaining_ms: u32, now: Instant) {
-        if remaining_ms == 0 {
-            self.0 = None;
-        } else if let Some((_, until)) = &mut self.0 {
-            *until = now + Duration::from_millis(u64::from(remaining_ms)) + CHANNEL_SLACK;
-        }
-    }
-}
-
-/// ── The local self-cancel (decisions 0256 open item 2 / 0444 / 0445): move/jump/Esc mid-cast
-/// ends the cast **locally**, the same client tick — the app-side mirror of `AbortCast
-/// 0x6e4940`. The whole trigger chain is **VERIFIED** (wow-re `move-selfcancel.md`, the
-/// 2026-07-17 §5): the `Script::Move*` keybind handlers funnel into the shared dispatcher
-/// `0x515090`, whose interrupt mask `0x10f0` = {forward, backward, strafe L/R, autorun-toggle}
-/// — turn (`0x100/0x200`) and pitch (`0x400/0x800`) are OUTSIDE the mask and never cancel —
-/// and `Script::Jump 0x513bd0` inlines the same gate. Both call `AbortCast(cl=0, dl=1,
-/// reason=0x1c)`: event **0x152 SPELLCAST_STOP** (the silent close — `cl=0` selects it;
-/// `0x153/0x154` need `cl!=0`) + `CMSG_CANCEL_CAST`. The server stays the safety net: vmangos's
-/// own movement interrupt (`Spell::update`'s 0.5-yd position delta) still kills anything we
-/// miss. The per-spell gates, byte-verified at the call sites (`f6 46 54 01` @`0x51511e`,
-/// `f6 42 5c 08` @`0x515175`; identities corroborated by vmangos `SpellDefines.h`):
-/// (Also the entry test of the cast-INITIATION moving gate — `ui_action::state`'s
-/// `cast_moving_refusal`, decision 0862 — which is a different mechanism from this self-cancel.)
-pub(crate) const SPELL_INTERRUPT_MOVEMENT: u32 = 0x1; // SpellRec+0x54 InterruptFlags (SPELL_INTERRUPT_FLAG_MOVEMENT)
-const CHANNEL_INTERRUPT_MOVING: u32 = 0x8; // SpellRec+0x5c ChannelInterruptFlags (AURA_INTERRUPT_MOVING_CANCELS)
-
-/// The controller's report that a cancel-worthy local move edge happened this frame — a
-/// *directional* start (forward/back/strafe: our wire-axis mirror of the verified `0x10f0`
-/// mask's flags) or a jump takeoff. The mask's fifth member, the autorun toggle, is dormant
-/// until benilla grows an autorun (0445). Written by `player::control` at the same spot the
-/// wire-axis transitions are computed, consumed (and cleared) by [`local_self_cancel`] next
-/// frame — one engine frame (~16 ms) from key to bar-kill, vs the server round trip (~150 ms+:
-/// the 0.5-yd delta has to accumulate before vmangos even notices).
-#[derive(Resource, Default)]
-pub(crate) struct LocalMoveStart(pub(crate) bool);
-
-/// Move/jump/Esc mid-cast: run the client's local cancel. One system for both triggers so the
-/// resolution can't drift between them:
-///
-/// - **the auto-repeat half (Esc only)** — the ref's branch order inside
-///   `Script::SpellStopCasting 0x6e6e80` (§5-verified whole, wow-re `esc-stopcasting.md`): a
-///   running auto-repeat dies FIRST — [`crate::creature_anim::cancel_auto_repeat_local`], the
-///   byte-verified `0x6ea080` (key + idle gates + nocked ammo + `CMSG_CANCEL_AUTO_REPEAT_SPELL`)
-///   — and SPENDS the press: one press stops one thing, the cast survives to the next.
-///   Movement never touches auto-repeat.
-/// - **the cast half** — clear [`PendingCast`], ship `CMSG_CANCEL_CAST`, reap the self
-///   `Casting` state + fire the `Fail` cast event (the anim/visual teardown `AbortCast` does via
-///   its stop-cast-anim tail), and push the **`Stop` + `Interrupted`** bar edges — the ref's
-///   own two-step (its local STOP, then the echo's red repaint) at RTT→0: red "Interrupted",
-///   held 1 s, the armed flash bursting white, then the fade (the transcribed `CastingBar.xml`
-///   machinery runs the rest). Esc bypasses the movement flags gate (the ref's
-///   `SpellStopCasting → AbortCast` has no `InterruptFlags` test — the gate belongs to the
-///   movement path alone).
-/// - **the channel half — MOVEMENT-ONLY** — ship `CMSG_CANCEL_CHANNELLING` and NOTHING else:
-///   the verified asymmetry (0445). Esc never reaches a channel — `0x6e6e80`'s whole callee
-///   closure never calls the channel canceler `0x6e9b70`, and its inflight gate (`0xceca88`)
-///   is already 0 mid-channel (the launch `CAST_RESULT(OKAY)` clears it at `0x6e7408`): the
-///   vanilla "/stopcasting can't stop a channel" quirk, kept faithfully (0454; wow-re
-///   `esc-stopcasting.md`). The ref's `0x6e9b70` fires no FrameScript event and clears no
-///   local state — the channel bar closes on the server's `SMSG_CHANNEL_UPDATE(0)`
-///   (`0x6e75f0`), which also clears [`ActiveChannel`] through the normal wire path (its slack
-///   deadline self-heals a lost packet).
-///
-/// Why `Interrupted` when the client's own event is VERIFIED as the silent `0x152` STOP (every
-/// self-cancel caller passes `cl=0`)? Because the REF'S NET OBSERVABLE is the red bar — the
-/// director's falsifier, decision 0449, now pinned end to end (0454): vmangos `Spell::cancel`
-/// answers the cancel with `SMSG_SPELL_FAILED_OTHER` and then a failing `SMSG_CAST_RESULT`
-/// reason 0x23 (`SPELL_FAILED_INTERRUPTED`, counted against the 1.12.1 build guards), the
-/// client routes a failing result through `HandleCastFailed 0x6e1a00`, and reasons
-/// {0x23,0x24} select FrameScript **0x154 SPELLCAST_INTERRUPTED** — red, "Interrupted"
-/// (GlobalStrings-exact), `holdTime = now + 1 s`. Our bar-edge producers are KEYED to the
-/// self `Casting` (the 0137/0256 law that stops a proc's failure repainting the bar), and
-/// this cancel's reap removes it — so the echo can't do the repainting here. The local
-/// `Stop` + `Interrupted` pair replays the ref's exact sequence at RTT→0 through our keyed
-/// architecture; the reap then keeps the echo idempotent (re-clears open guards, shows the
-/// red error line, touches no bar). On-screen: the 1 s hold + ~25 bar ticks of flash+fade —
-/// ~1.9 s in the reference bottle (whose `Config.wtf` caps `maxfps` at 30, and the ref steps
-/// alpha PER TICK), the director's observed "2–3 s"; our transcription normalizes those steps
-/// to the same 30 Hz reference tick so the tail matches at any render rate (`CastingBar.xml`).
-fn local_self_cancel(
-    script: Option<NonSendMut<UiScript>>,
-    mut moved: ResMut<LocalMoveStart>,
-    mut pending: ResMut<PendingCast>,
-    mut queued_melee: ResMut<QueuedMeleeSpell>,
-    channel: Res<ActiveChannel>,
-    mut auto_repeat: ResMut<crate::ui_action::AutoRepeatActive>,
-    mut feed: ResMut<CastBarFeed>,
-    spells: Option<Res<Spells>>,
-    net: Res<NetCommands>,
-    self_guid: Res<SelfGuid>,
-    index: Res<GuidIndex>,
-    casting: Query<&Casting>,
-    mut cast_events: MessageWriter<CastEvent>,
-    mut play_seq: ResMut<PlaySeq>,
-    mut ecs: Commands,
-) {
-    let esc = match script {
-        Some(mut s) => s.take_spell_stop(),
-        None => false,
-    };
-    let moved = std::mem::take(&mut moved.0);
-    if !esc && !moved {
-        return;
-    }
-    let now = Instant::now();
-    let self_e = self_guid.0.as_ref().and_then(|g| index.0.get(g)).copied();
-    // The Esc press stops ONE thing, auto-repeat first — the ref's branch order (`0x6e6e80`).
-    let esc = if esc && auto_repeat.0.is_some() {
-        if *crate::net::CAST_TRACE {
-            info!("cast-trace: LOCAL auto-repeat self-cancel (esc), CMSG_CANCEL_AUTO_REPEAT_SPELL");
-        }
-        crate::creature_anim::cancel_auto_repeat_local(self_e, &mut auto_repeat, &mut ecs, &net);
-        false // the press is spent
-    } else {
-        esc
-    };
-    if !esc && !moved {
-        return;
-    }
-    let flags_open = |pick: fn(&benilla_formats::SpellDisplay) -> bool, spell_id: u32| {
-        // An uncataloged spell cancels: the gate exists to spare the rare cast-while-moving
-        // spell, and failing open matches the server's own verdict for everything ordinary.
-        spells
-            .as_ref()
-            .and_then(|s| s.catalog.get(spell_id))
-            .is_none_or(pick)
-    };
-    // The cast half — the ref's ONE inflight slot ([`Inflight`]), which is an ordinary cast or a
-    // queued on-next-swing strike. `AbortCast` doesn't distinguish, so neither does the send or
-    // the movement gate; only the local teardown differs, because only a cast ever had a bar.
-    let started = self_e.and_then(|e| casting.get(e).ok()).map(|c| c.spell_id);
-    if let Some(slot) = inflight(&pending, &queued_melee, started, now) {
-        let spell_id = slot.spell_id();
-        // Esc bypasses the flags gate; movement consults the slot's own `InterruptFlags`, which
-        // is what spares a queued strike (Heroic Strike 78, Cleave 845, Raptor Strike 2973 all
-        // ship `InterruptFlags = 0x0` — verified against Spell.dbc, vs Fireball's `0xf`). So
-        // charging in with a strike queued keeps it queued, and only Esc takes it.
-        if esc
-            || flags_open(
-                |d| d.interrupt_flags & SPELL_INTERRUPT_MOVEMENT != 0,
-                spell_id,
-            )
-        {
-            if *crate::net::CAST_TRACE {
-                info!(
-                    "cast-trace: LOCAL self-cancel — {slot:?} ({}), CMSG_CANCEL_CAST",
-                    if esc { "esc" } else { "moved" }
-                );
-            }
-            let _ = net.0.send(ClientCommand::CancelCast { spell_id });
-            match slot {
-                Inflight::Cast(_) => {
-                    pending.clear_if(spell_id);
-                    // The ref's two-step at RTT→0: STOP arms the bar's flash overlay, the echo's
-                    // INTERRUPTED repaints it red and starts the hold — so after the hold the
-                    // flash BURSTS white over the red bar, then the fade runs. One edge alone
-                    // misses the burst (which the enemy-interrupt path — no prior STOP —
-                    // correctly lacks).
-                    feed.0.push(CastBarEdge::Stop);
-                    feed.0.push(CastBarEdge::Interrupted);
-                    // The reap — `spell_failed_other`'s self arm, run early so the echo finds it
-                    // done.
-                    if let Some(e) = self_e {
-                        if casting.get(e).is_ok_and(|c| c.spell_id == spell_id) {
-                            ecs.entity(e).remove::<Casting>();
-                        }
-                        cast_events.write(CastEvent {
-                            entity: e,
-                            spell_id,
-                            kind: CastEventKind::Fail,
-                            seq: play_seq.next(),
-                        });
-                    }
-                }
-                Inflight::Strike(_) => {
-                    // Clearing the slot IS the un-toggle: the checked ring reads it
-                    // (`ui_action::state`), so the button darkens this frame instead of waiting
-                    // for vmangos's FAILED_OTHER + CAST_RESULT echo (which then finds the slot
-                    // already open and is idempotent). `AbortCast` fires its `0x152`
-                    // SPELLCAST_STOP here too — inert on a bar that never opened
-                    // (`CastingBar.xml` guards every arm on `IsShown`), so it is fired for
-                    // fidelity, not effect. No red INTERRUPTED: there is nothing to repaint.
-                    queued_melee.clear_if(spell_id);
-                    feed.0.push(CastBarEdge::Stop);
-                }
-            }
-        }
-    }
-    // The channel half — MOVEMENT-ONLY (Esc can't stop a channel: the doc above / 0454), and
-    // the send and nothing else (the verified asymmetry: the ref's `0x6e9b70` fires no event
-    // and clears no state; the bar and [`ActiveChannel`] both close on the server's
-    // `SMSG_CHANNEL_UPDATE(0)`, ~one localhost frame later).
-    if moved {
-        if let Some(spell_id) = channel.current(now) {
-            if flags_open(
-                |d| d.channel_interrupt_flags & CHANNEL_INTERRUPT_MOVING != 0,
-                spell_id,
-            ) {
-                if *crate::net::CAST_TRACE {
-                    info!("cast-trace: LOCAL channel self-cancel — spell {spell_id}, CMSG_CANCEL_CHANNELLING");
-                }
-                let _ = net.0.send(ClientCommand::CancelChannelling { spell_id });
-            }
-        }
-    }
-}
-
 /// `SPELLCAST_START`'s **name argument** — what the reference `CastingBarFrame` puts straight into
-/// `CastingBarText:SetText(...)` for a *cast*. Byte-verified at `0x6e7a2d`–`0x6e7a47` (wow-re
-/// `spell/scratch/wave-cast.md`, "The casting-bar TEXT law", §5 cross-checked): the handler tests
+/// `CastingBarText:SetText(...)` for a *cast*. At `0x6e7a2d`–`0x6e7a47` the handler tests
 /// `AttributesEx3 & 0x4` and pushes **the empty string `0x882748`** when set, `Name[locale]` when
 /// clear — the event still fires either way, carrying its duration, so the bar is a normal
 /// full-length *untitled* bar rather than a hidden one.
@@ -589,7 +84,7 @@ fn cast_bar_label(spells: Option<&crate::ui_action::Spells>, id: u32) -> String
 /// all** and the bar never appears.
 ///
 /// The handler is 147 bytes and every one of its gates is here, in its order (decomp
-/// `FUN_006e7550`; disassembly quoted in wow-re `system/spell/scratch/wave-cast.md` §0x6e7550):
+/// `FUN_006e7550`; the disassembly of `0x6e7550`):
 ///
 /// ```text
 /// 6e7571  test eax,eax / jle 6e75d8      ; (1) duration <= 0            -> NO EVENT
@@ -663,7 +158,7 @@ fn channel_start_args(
 /// conditions under which `0x6e7550` returns without firing, and the bar then never appears.
 ///
 /// Also pushes the frame's stoppable mirror (running auto-repeat OR the [`Inflight`] slot — NOT
-/// a channel, which `SpellStopCasting()` answers nil for: wow-re `esc-stopcasting.md`) into the
+/// a channel, which `SpellStopCasting 0x6e6e80` answers nil for) into the
 /// VM **after** [`local_self_cancel`] resolved, so the ESC chain's `SpellStopCasting()` reads
 /// post-cancel truth when `UiInput` runs later this frame.
 ///
@@ -671,13 +166,13 @@ fn channel_start_args(
 /// queued strike makes `IsCasting` true in the reference, so `SpellStopCasting()` returns `1` and
 /// `ToggleGameMenu`'s ladder never reaches `ClearTarget()` (`UIParent.lua` l.1489 vs l.1492).
 /// Reading only the ordinary-cast half here is what dropped the target on the first Esc.
-fn feed_cast_bar(
+pub(crate) fn feed_cast_bar(
     script: Option<NonSendMut<UiScript>>,
     mut feed: ResMut<CastBarFeed>,
     spells: Option<Res<Spells>>,
     pending: Res<PendingCast>,
     queued_melee: Res<QueuedMeleeSpell>,
-    auto_repeat: Res<crate::ui_action::AutoRepeatActive>,
+    auto_repeat: Res<crate::spell::AutoRepeatActive>,
     self_guid: Res<SelfGuid>,
     index: Res<GuidIndex>,
     casting: Query<&Casting>,
@@ -723,7 +218,7 @@ fn feed_cast_bar(
             } => {
                 let args = channel_start_args(&script, spells.as_deref(), spell_id, duration_ms);
                 // The channel half of the cast trace. The other five edges are traced at RECV
-                // (`net::apply::spells`); these two are traced HERE because the decision that
+                // (`spell::net`); these two are traced HERE because the decision that
                 // wants watching — which of `0x6e7550`'s legs the spell took — is made here,
                 // and the drain runs the same frame the packet lands.
                 if *crate::net::CAST_TRACE {
@@ -773,19 +268,19 @@ fn feed_cast_bar(
 /// OnUpdate land the same frame), and the local self-cancel resolved just ahead of the drain —
 /// a controller move edge or an ESC `SpellStopCasting()` from the previous frame kills the bar
 /// on this frame's VM tick (one engine frame from input to bar-death).
+/// The feed only — the state it reads is `crate::spell`'s (decision 2328).
 pub(crate) struct UiCastPlugin;
 
 impl Plugin for UiCastPlugin {
     fn build(&self, app: &mut App) {
-        app.init_resource::<CastBarFeed>()
-            .init_resource::<PendingCast>()
-            .init_resource::<QueuedMeleeSpell>()
-            .init_resource::<ActiveChannel>()
-            .init_resource::<LocalMoveStart>()
-            .add_systems(
-                Update,
-                (local_self_cancel, feed_cast_bar).chain().in_set(UnitFeed),
-            );
+        app.init_resource::<CastBarFeed>().add_systems(
+            Update,
+            // After the spell's local cancel, whose edges this drains the same frame — the
+            // `(local_self_cancel, feed_cast_bar).chain()` this plugin held until 2328.
+            feed_cast_bar
+                .in_set(UnitFeed)
+                .after(crate::spell::LocalCancel),
+        );
     }
 }
 
@@ -793,8 +288,6 @@ impl Plugin for UiCastPlugin {
 mod tests {
     use super::*;
 
-    const FIREBALL: u32 = 133;
-
     /// **B247** (decision 1312): the bar's label honours `SPELL_ATTR_EX3_NO_CASTING_BAR_TEXT`.
     /// Spell 22810's Spell.dbc name — "Opening - No Text" — is Blizzard's own annotation of the
     /// attribute, and it reached a player's screen because we printed the name regardless.
@@ -933,668 +426,4 @@ mod tests {
             ScriptValue::Str("Channeling".into()),
         );
     }
-
-    /// The suppressed channel still arms [`ActiveChannel`], so its action button stays lit: the
-    /// reference's channel mirror is `SPELLCAST+0x10` (`0xceac58`), written at the cast SEND
-    /// (`0x6e4f88`) and never touched by `0x6e7550`. That is why all four of the handler's gates
-    /// live in the DRAIN and none of them in `net::apply::spells::channel_start`, which arms this.
-    #[test]
-    fn suppressing_the_channel_bar_does_not_clear_the_channel_mirror() {
-        let t0 = Instant::now();
-        // What `MSG_CHANNEL_START` does for Blood Siphon 24322 — the suppressed row.
-        let mut channel = ActiveChannel::default();
-        channel.start(24322, 8_000, t0);
-        assert_eq!(
-            channel.current(t0 + Duration::from_secs(1)),
-            Some(24322),
-            "the wire edge arms the mirror regardless of what the bar does with it"
-        );
-    }
-
-    #[test]
-    fn a_fresh_guard_is_open() {
-        let g = PendingCast::default();
-        assert!(
-            !g.in_flight(Instant::now()),
-            "nothing sent yet — casting allowed"
-        );
-    }
-
-    #[test]
-    fn arming_closes_the_guard_and_a_matching_resolution_opens_it() {
-        let t0 = Instant::now();
-        let mut g = PendingCast::default();
-        g.arm(FIREBALL, t0, true);
-        assert!(
-            g.in_flight(t0),
-            "a cast is in flight — a second one is refused"
-        );
-        g.clear_if(FIREBALL); // SMSG_SPELL_GO / a failing SMSG_CAST_RESULT for our cast
-        assert!(
-            !g.in_flight(t0),
-            "our cast resolved — casting allowed again"
-        );
-    }
-
-    #[test]
-    fn a_different_spells_resolution_leaves_the_guard_closed() {
-        let t0 = Instant::now();
-        let mut g = PendingCast::default();
-        g.arm(FIREBALL, t0, true);
-        g.clear_if(FIREBALL + 1); // a triggered proc's GO for some other spell mid-cast
-        assert!(
-            g.in_flight(t0),
-            "a different spell's resolution must not open the guard on our cast"
-        );
-    }
-
-    #[test]
-    fn the_guard_opens_when_its_safety_deadline_lapses() {
-        // The net that saves us if a cast resolves with no packet (a local move-cancel we don't
-        // model): the guard cannot wedge casting shut forever.
-        let t0 = Instant::now();
-        let mut g = PendingCast::default();
-        g.arm(FIREBALL, t0, true);
-        assert!(g.in_flight(t0 + SEND_PROVISIONAL - Duration::from_secs(1)));
-        assert!(!g.in_flight(t0 + SEND_PROVISIONAL + Duration::from_secs(1)));
-    }
-
-    #[test]
-    fn a_pushback_extends_the_guard_so_it_holds_past_the_stretched_cast() {
-        let t0 = Instant::now();
-        let mut g = PendingCast::default();
-        g.arm(FIREBALL, t0, true);
-        g.refine(1_000, t0); // a 1 s cast: deadline t0 + 1s + 2s slack = t0 + 3s
-        g.delay(500, t0); // a hit at t0 pushes it +0.5s ⇒ t0 + 3.5s
-        assert!(
-            g.in_flight(t0 + Duration::from_millis(3_200)),
-            "the pushback kept the guard shut past the original refined deadline"
-        );
-    }
-
-    #[test]
-    fn spell_start_tightens_the_deadline_to_the_real_cast_time() {
-        let t0 = Instant::now();
-        let mut g = PendingCast::default();
-        g.arm(FIREBALL, t0, true); // provisional 5s window
-        g.refine(1_500, t0); // SMSG_SPELL_START: a 1.5s cast (+ 2s pushback slack ⇒ 3.5s)
-        let at_four = t0 + Duration::from_secs(4);
-        assert!(
-            !g.in_flight(at_four),
-            "refined to 1.5s + slack, the guard has opened by t+4s (it would still be shut at the \
-             5s provisional)"
-        );
-    }
-
-    /// The queued on-next-swing slot: deadline-less (no clock in its API at all), keyed clears
-    /// only, and a re-arm replaces — the server's single `CURRENT_MELEE_SPELL` slot.
-    #[test]
-    fn queued_melee_spell_is_wire_cleared_and_single_slot() {
-        const HEROIC_STRIKE: u32 = 78;
-        const CLEAVE: u32 = 845;
-        let mut q = QueuedMeleeSpell::default();
-        assert_eq!(q.current(), None);
-
-        q.arm(HEROIC_STRIKE);
-        assert_eq!(q.current(), Some(HEROIC_STRIKE), "queued and checked");
-
-        // A different spell's resolution (Rend's GO while HS waits) must not open the queue.
-        q.clear_if(772);
-        assert_eq!(q.current(), Some(HEROIC_STRIKE));
-
-        // A second on-next-swing cast replaces the queue (vmangos holds ONE melee slot).
-        q.arm(CLEAVE);
-        assert_eq!(q.current(), Some(CLEAVE));
-
-        // The swing fired it (SPELL_GO) — or the slot died (failing CAST_RESULT /
-        // SPELL_FAILED_OTHER): the matching id clears.
-        q.clear_if(CLEAVE);
-        assert_eq!(q.current(), None, "the wire resolution opened the queue");
-    }
-
-    /// The local self-cancel harness: a mini-App with the real [`local_self_cancel`] system, a
-    /// self player mid-cast/mid-channel, and the net channel's receive half to assert the wire.
-    /// The harness registers no `UiScript`, so the ESC trigger reads `false` by default; the
-    /// ESC-leg tests insert a real VM and drive the actual `SpellStopCasting()` binding (the
-    /// ladder's 1/nil semantics are pinned Lua-side in `ui_script::escape_tests`).
-    mod local_cancel {
-        use super::*;
-        use crate::creature_anim::PlaySeq;
-        use crate::net::{Guid, GuidIndex, NetCommands, SelfGuid, SelfPlayer};
-        use benilla_formats::{SpellCatalog, SpellDisplay};
-        use bevy::ecs::system::RunSystemOnce;
-        use std::collections::HashMap;
-
-        const ARCANE_MISSILES: u32 = 5143;
-        const HEROIC_STRIKE: u32 = 78;
-
-        fn harness(
-            displays: HashMap<u32, SpellDisplay>,
-        ) -> (App, crossbeam_channel::Receiver<crate::net::ClientCommand>) {
-            let (tx, rx) = crossbeam_channel::unbounded();
-            let mut app = App::new();
-            app.add_message::<CastEvent>()
-                .init_resource::<CastBarFeed>()
-                .init_resource::<PendingCast>()
-                .init_resource::<QueuedMeleeSpell>()
-                .init_resource::<ActiveChannel>()
-                .init_resource::<crate::ui_action::AutoRepeatActive>()
-                .init_resource::<LocalMoveStart>()
-                .init_resource::<GuidIndex>()
-                .init_resource::<SelfGuid>()
-                .init_resource::<PlaySeq>()
-                .insert_resource(NetCommands(tx))
-                .insert_resource(crate::ui_action::Spells {
-                    catalog: SpellCatalog::from_displays(displays),
-                    ..crate::ui_action::Spells::empty_for_tests()
-                });
-            let self_e = app.world_mut().spawn((Guid(10), SelfPlayer)).id();
-            app.world_mut()
-                .resource_mut::<GuidIndex>()
-                .0
-                .insert(10, self_e);
-            app.world_mut().resource_mut::<SelfGuid>().0 = Some(10);
-            (app, rx)
-        }
-
-        /// Mark the self player mid-cast on `spell_id` (the `SMSG_SPELL_START` echo's `Casting`).
-        fn mark_casting(app: &mut App, spell_id: u32) {
-            let self_e = app.world().resource::<GuidIndex>().0[&10];
-            app.world_mut().entity_mut(self_e).insert(Casting {
-                spell_id,
-                until: None,
-            });
-        }
-
-        fn run(app: &mut App, moved: bool) {
-            app.world_mut().resource_mut::<LocalMoveStart>().0 = moved;
-            app.world_mut().run_system_once(local_self_cancel).unwrap();
-        }
-
-        /// The headline feel fix: a directional start / jump mid-cast kills the cast locally —
-        /// wire cancel out, guard open, the STOP + INTERRUPTED bar-edge pair (the ref's own
-        /// two-step: its silent 0x152 STOP arms the flash, the server echo's repaint holds the
-        /// red "Interrupted"; our keyed reap suppresses the real echo, so the local pair
-        /// replays the sequence at RTT→0 — decisions 0449/0454), `Casting` reaped — instead of
-        /// waiting ~150 ms+ for the server's 0.5-yd position-delta interrupt.
-        #[test]
-        fn a_move_edge_mid_cast_cancels_locally() {
-            let (mut app, rx) = harness(HashMap::from([(
-                FIREBALL,
-                SpellDisplay {
-                    interrupt_flags: 0xf, // the ordinary timed-cast mask (movement bit set)
-                    ..Default::default()
-                },
-            )]));
-            app.world_mut()
-                .resource_mut::<PendingCast>()
-                .arm(FIREBALL, Instant::now(), true);
-            mark_casting(&mut app, FIREBALL);
-
-            run(&mut app, true);
-
-            assert!(
-                matches!(
-                    rx.try_recv(),
-                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
-                ),
-                "the move edge ships CMSG_CANCEL_CAST for the in-flight cast"
-            );
-            assert!(
-                !app.world()
-                    .resource::<PendingCast>()
-                    .in_flight(Instant::now()),
-                "the in-flight guard opens with the local cancel"
-            );
-            let feed = &app.world().resource::<CastBarFeed>().0;
-            assert_eq!(feed.len(), 2);
-            assert!(
-                matches!(
-                    (&feed[0], &feed[1]),
-                    (CastBarEdge::Stop, CastBarEdge::Interrupted)
-                ),
-                "the bar edges are the ref's own two-step at RTT→0 — STOP (arms the flash \
-                 overlay) then the red INTERRUPTED (the echo's repaint: hold, burst, fade); \
-                 the keyed reap silences the real echo (0449/0454)"
-            );
-            let self_e = app.world().resource::<GuidIndex>().0[&10];
-            assert!(
-                app.world().entity(self_e).get::<Casting>().is_none(),
-                "the self `Casting` state is reaped, so the server's echo (FAILED_OTHER + \
-                 CAST_RESULT) finds nothing to repaint"
-            );
-            assert!(
-                !app.world().resource::<LocalMoveStart>().0,
-                "the edge is consumed"
-            );
-        }
-
-        /// The per-spell gate (VERIFIED — `test [SpellRec+0x54],1` at both call sites): a spell
-        /// whose `InterruptFlags` lacks the movement bit keeps casting while we move — no wire
-        /// cancel, no bar edge.
-        #[test]
-        fn the_interrupt_flags_gate_spares_a_movement_castable_spell() {
-            let (mut app, rx) = harness(HashMap::from([(
-                FIREBALL,
-                SpellDisplay {
-                    interrupt_flags: 0xe, // movement bit CLEAR (pushback/stun/combat only)
-                    ..Default::default()
-                },
-            )]));
-            app.world_mut()
-                .resource_mut::<PendingCast>()
-                .arm(FIREBALL, Instant::now(), true);
-
-            run(&mut app, true);
-
-            assert!(rx.try_recv().is_err(), "no wire cancel for a spared spell");
-            assert!(
-                app.world()
-                    .resource::<PendingCast>()
-                    .in_flight(Instant::now()),
-                "the guard keeps holding — the cast runs on"
-            );
-            assert!(app.world().resource::<CastBarFeed>().0.is_empty());
-        }
-
-        /// A spell the catalog doesn't know fails OPEN (cancels): the gate exists to spare the
-        /// rare cast-while-moving spell, and the server's own verdict for everything ordinary is
-        /// to interrupt.
-        #[test]
-        fn an_uncataloged_spell_fails_open() {
-            let (mut app, rx) = harness(HashMap::new());
-            app.world_mut()
-                .resource_mut::<PendingCast>()
-                .arm(FIREBALL, Instant::now(), true);
-
-            run(&mut app, true);
-
-            assert!(
-                matches!(
-                    rx.try_recv(),
-                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
-                ),
-                "an unknown spell's cast still cancels on movement"
-            );
-        }
-
-        /// The union's other half: an ITEM use's cast (a hearthstone) never arms the send
-        /// guard — the started self `Casting` (the `SMSG_SPELL_START` echo) alone makes it
-        /// move-cancelable, mirroring the ref's ONE inflight id (`0xceca88`), which item casts
-        /// set like any spell cast.
-        #[test]
-        fn a_started_item_cast_cancels_without_the_send_guard() {
-            let (mut app, rx) = harness(HashMap::from([(
-                FIREBALL,
-                SpellDisplay {
-                    interrupt_flags: 0xf,
-                    ..Default::default()
-                },
-            )]));
-            mark_casting(&mut app, FIREBALL); // PendingCast stays empty — item casts never arm it
-
-            run(&mut app, true);
-
-            assert!(
-                matches!(
-                    rx.try_recv(),
-                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
-                ),
-                "the started cast cancels through the `Casting` half of the union"
-            );
-            let self_e = app.world().resource::<GuidIndex>().0[&10];
-            assert!(app.world().entity(self_e).get::<Casting>().is_none());
-        }
-
-        /// No move edge, cast in flight: nothing happens — the system is edge-triggered, never
-        /// level-triggered (holding W through a whole cast is one cancel at the start, not one
-        /// per frame; and standing still cancels nothing).
-        #[test]
-        fn no_edge_means_no_cancel() {
-            let (mut app, rx) = harness(HashMap::from([(
-                FIREBALL,
-                SpellDisplay {
-                    interrupt_flags: 0xf,
-                    ..Default::default()
-                },
-            )]));
-            app.world_mut()
-                .resource_mut::<PendingCast>()
-                .arm(FIREBALL, Instant::now(), true);
-
-            run(&mut app, false);
-
-            assert!(rx.try_recv().is_err());
-            assert!(app
-                .world()
-                .resource::<PendingCast>()
-                .in_flight(Instant::now()));
-            assert!(app.world().resource::<CastBarFeed>().0.is_empty());
-        }
-
-        /// Esc CANNOT stop a channel — the §5-verified `0x6e6e80` never reaches the channel
-        /// canceler `0x6e9b70`, and its inflight gate is already 0 mid-channel (wow-re
-        /// `esc-stopcasting.md`, 0454): the mirror answers `SpellStopCasting()` nil (the
-        /// ladder falls through to the next rung) and the drain ships nothing.
-        #[test]
-        fn esc_cannot_stop_a_channel() {
-            let (mut app, rx) = harness(HashMap::new());
-            app.insert_non_send_resource(UiScript::new().unwrap());
-            let now = Instant::now();
-            app.world_mut()
-                .resource_mut::<ActiveChannel>()
-                .start(ARCANE_MISSILES, 5_000, now);
-
-            app.world_mut().run_system_once(feed_cast_bar).unwrap();
-            assert_eq!(
-                app.world()
-                    .non_send_resource::<UiScript>()
-                    .eval::<Option<i64>>("return SpellStopCasting()")
-                    .unwrap(),
-                None,
-                "mid-channel the binding answers nil — the vanilla /stopcasting quirk"
-            );
-            app.world_mut().run_system_once(local_self_cancel).unwrap();
-            assert!(
-                rx.try_recv().is_err(),
-                "no wire cancel — channels break only on the movement path"
-            );
-            assert_eq!(
-                app.world().resource::<ActiveChannel>().current(now),
-                Some(ARCANE_MISSILES)
-            );
-        }
-
-        /// The ref's branch order inside `SpellStopCasting` (`0x6e6e80`): a running auto-repeat
-        /// dies FIRST — `CMSG_CANCEL_AUTO_REPEAT_SPELL`, no bar edge — and SPENDS the press;
-        /// the in-flight cast survives to the next one. One press stops one thing.
-        #[test]
-        fn esc_cancels_the_auto_repeat_first_and_the_cast_on_the_next_press() {
-            const AUTO_SHOT: u32 = 75;
-            let (mut app, rx) = harness(HashMap::new());
-            app.insert_non_send_resource(UiScript::new().unwrap());
-            app.world_mut()
-                .resource_mut::<crate::ui_action::AutoRepeatActive>()
-                .0 = Some(AUTO_SHOT);
-            app.world_mut()
-                .resource_mut::<PendingCast>()
-                .arm(FIREBALL, Instant::now(), true);
-            mark_casting(&mut app, FIREBALL);
-
-            // Press 1: truthy mirror (auto-repeat ∪ cast) → trigger queued → the drain stops
-            // the auto-repeat ONLY.
-            app.world_mut().run_system_once(feed_cast_bar).unwrap();
-            assert_eq!(
-                app.world()
-                    .non_send_resource::<UiScript>()
-                    .eval::<Option<i64>>("return SpellStopCasting()")
-                    .unwrap(),
-                Some(1)
-            );
-            app.world_mut().run_system_once(local_self_cancel).unwrap();
-            assert!(
-                matches!(
-                    rx.try_recv(),
-                    Ok(crate::net::ClientCommand::CancelAutoRepeat)
-                ),
-                "the auto-repeat cancel ships first — the ref's priority branch"
-            );
-            assert!(rx.try_recv().is_err(), "the cast survives the first press");
-            assert!(app
-                .world()
-                .resource::<crate::ui_action::AutoRepeatActive>()
-                .0
-                .is_none());
-            assert!(
-                app.world()
-                    .resource::<PendingCast>()
-                    .in_flight(Instant::now()),
-                "the send guard still holds — one press stopped one thing"
-            );
-            assert!(
-                app.world().resource::<CastBarFeed>().0.is_empty(),
-                "an auto-repeat cancel paints no bar edge"
-            );
-
-            // Press 2: the auto-repeat is gone — now the cast dies, the ordinary Esc cancel.
-            app.world_mut().run_system_once(feed_cast_bar).unwrap();
-            assert_eq!(
-                app.world()
-                    .non_send_resource::<UiScript>()
-                    .eval::<Option<i64>>("return SpellStopCasting()")
-                    .unwrap(),
-                Some(1)
-            );
-            app.world_mut().run_system_once(local_self_cancel).unwrap();
-            assert!(
-                matches!(
-                    rx.try_recv(),
-                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
-                ),
-                "the second press reaches the cast half"
-            );
-        }
-
-        /// **The director's report, decision 1049: Esc with Heroic Strike queued un-toggles the
-        /// STRIKE and keeps the target.** In the reference a queued on-next-swing spell simply
-        /// *is* the inflight spell (`0xceca88`), so `SpellStopCasting 0x6e6e80` takes its plain
-        /// `IsCasting 0x6e3d30` branch — `AbortCast` → `CMSG_CANCEL_CAST` — and returns `1`,
-        /// which EATS the press so `ToggleGameMenu`'s ladder never reaches `ClearTarget()`. We
-        /// split that one slot in two and the Esc reader saw only the cast half, so the binding
-        /// answered nil: the strike stayed lit *and* the target dropped, both from one cause.
-        #[test]
-        fn esc_unqueues_a_strike_and_eats_the_press() {
-            let (mut app, rx) = harness(HashMap::from([(
-                HEROIC_STRIKE,
-                SpellDisplay {
-                    attributes: 0x5_0014, // the shipped row: on-next-swing (`& 0x404`)
-                    interrupt_flags: 0,   // …and no movement bit, also shipped
-                    ..Default::default()
-                },
-            )]));
-            app.insert_non_send_resource(UiScript::new().unwrap());
-            app.world_mut()
-                .resource_mut::<QueuedMeleeSpell>()
-                .arm(HEROIC_STRIKE);
-
-            app.world_mut().run_system_once(feed_cast_bar).unwrap();
-            assert_eq!(
-                app.world()
-                    .non_send_resource::<UiScript>()
-                    .eval::<Option<i64>>("return SpellStopCasting()")
-                    .unwrap(),
-                Some(1),
-                "the queued strike makes IsCasting true, so the binding EATS the press — which \
-                 is what spares the target three rungs further down the ladder"
-            );
-            app.world_mut().run_system_once(local_self_cancel).unwrap();
-            assert!(
-                matches!(
-                    rx.try_recv(),
-                    Ok(crate::net::ClientCommand::CancelCast {
-                        spell_id: HEROIC_STRIKE
-                    })
-                ),
-                "AbortCast names the queued strike on the wire, exactly as it would a cast"
-            );
-            assert_eq!(
-                app.world().resource::<QueuedMeleeSpell>().current(),
-                None,
-                "the slot opens locally — the checked ring darkens this frame, not one RTT later"
-            );
-            assert!(
-                matches!(
-                    app.world().resource::<CastBarFeed>().0[..],
-                    [CastBarEdge::Stop]
-                ),
-                "the ref's `0x152` STOP and nothing else: no red INTERRUPTED for a spell that \
-                 never opened a bar"
-            );
-        }
-
-        /// …but MOVEMENT does not take it. The movement path consults the inflight spell's own
-        /// `InterruptFlags`, and Heroic Strike 78 / Cleave 845 / Raptor Strike 2973 all ship
-        /// `InterruptFlags = 0x0` (read off the shipped `Spell.dbc`; Fireball is `0xf`). So
-        /// charging in with a strike queued keeps it queued — Esc is the only local taker.
-        #[test]
-        fn a_move_edge_leaves_a_queued_strike_queued() {
-            let (mut app, rx) = harness(HashMap::from([(
-                HEROIC_STRIKE,
-                SpellDisplay {
-                    interrupt_flags: 0,
-                    ..Default::default()
-                },
-            )]));
-            app.world_mut()
-                .resource_mut::<QueuedMeleeSpell>()
-                .arm(HEROIC_STRIKE);
-
-            run(&mut app, true);
-
-            assert!(rx.try_recv().is_err(), "running at the mob cancels nothing");
-            assert_eq!(
-                app.world().resource::<QueuedMeleeSpell>().current(),
-                Some(HEROIC_STRIKE)
-            );
-        }
-
-        /// The nesting order (`Inflight`'s doc): an ordinary cast started over a queued strike
-        /// pushes it down (`PushPopNestedCast 0x6e4ad0`), so `0xceca88` holds the CAST. One Esc
-        /// takes the cast; `AbortCast`'s pop restores the strike, and the next Esc takes that.
-        /// One press, one thing — the ladder's law all the way down.
-        ///
-        /// This is the **local** law, which is all a harness with no server can show, and it is
-        /// the ref's local law too (wow-re `esc-queued-strike.md` §Q(c)) — with the one knowing
-        /// difference `Inflight`'s doc names: the ref's press 2 re-asserts the strike instead of
-        /// clearing it. On a live wire neither client gets this far, because vmangos drops the
-        /// melee slot on press **1** regardless of the id in the packet, and both converge off
-        /// that echo. So what this pins is the ordering, not a two-press ritual a player sees.
-        #[test]
-        fn esc_takes_the_cast_first_and_the_strike_on_the_next_press() {
-            let (mut app, rx) = harness(HashMap::new());
-            app.insert_non_send_resource(UiScript::new().unwrap());
-            app.world_mut()
-                .resource_mut::<QueuedMeleeSpell>()
-                .arm(HEROIC_STRIKE);
-            app.world_mut()
-                .resource_mut::<PendingCast>()
-                .arm(FIREBALL, Instant::now(), true);
-            mark_casting(&mut app, FIREBALL);
-
-            app.world_mut().run_system_once(feed_cast_bar).unwrap();
-            assert_eq!(
-                app.world()
-                    .non_send_resource::<UiScript>()
-                    .eval::<Option<i64>>("return SpellStopCasting()")
-                    .unwrap(),
-                Some(1)
-            );
-            app.world_mut().run_system_once(local_self_cancel).unwrap();
-            assert!(
-                matches!(
-                    rx.try_recv(),
-                    Ok(crate::net::ClientCommand::CancelCast { spell_id: FIREBALL })
-                ),
-                "the nested cast is what sits in the inflight slot — it dies first"
-            );
-            assert!(rx.try_recv().is_err());
-            assert_eq!(
-                app.world().resource::<QueuedMeleeSpell>().current(),
-                Some(HEROIC_STRIKE),
-                "the strike is the SAVE underneath, untouched by the first press"
-            );
-
-            // Press 2 — the pop put the strike back in the slot.
-            app.world_mut().run_system_once(feed_cast_bar).unwrap();
-            assert_eq!(
-                app.world()
-                    .non_send_resource::<UiScript>()
-                    .eval::<Option<i64>>("return SpellStopCasting()")
-                    .unwrap(),
-                Some(1),
-                "still stoppable — so this press is eaten too, and the target still survives"
-            );
-            app.world_mut().run_system_once(local_self_cancel).unwrap();
-            assert!(matches!(
-                rx.try_recv(),
-                Ok(crate::net::ClientCommand::CancelCast {
-                    spell_id: HEROIC_STRIKE
-                })
-            ));
-            assert_eq!(app.world().resource::<QueuedMeleeSpell>().current(), None);
-        }
-
-        /// The channel half is the SEND and nothing else — the verified asymmetry (0445): the
-        /// ref's `0x6e9b70` ships CMSG_CANCEL_CHANNELLING but fires no FrameScript event and
-        /// clears no state; the channel bar and the mirror both close on the server's
-        /// `SMSG_CHANNEL_UPDATE(0)` through the normal wire path.
-        #[test]
-        fn a_move_edge_mid_channel_sends_the_cancel_and_touches_nothing_local() {
-            let (mut app, rx) = harness(HashMap::from([(
-                ARCANE_MISSILES,
-                SpellDisplay {
-                    channel_interrupt_flags: 0x7c0c, // the real 5143 mask (moving bit 0x8 set)
-                    ..Default::default()
-                },
-            )]));
-            let now = Instant::now();
-            app.world_mut()
-                .resource_mut::<ActiveChannel>()
-                .start(ARCANE_MISSILES, 5_000, now);
-
-            run(&mut app, true);
-
-            assert!(
-                matches!(
-                    rx.try_recv(),
-                    Ok(crate::net::ClientCommand::CancelChannelling {
-                        spell_id: ARCANE_MISSILES
-                    })
-                ),
-                "the move edge ships CMSG_CANCEL_CHANNELLING"
-            );
-            assert_eq!(
-                app.world().resource::<ActiveChannel>().current(now),
-                Some(ARCANE_MISSILES),
-                "the mirror stays live — the server's UPDATE(0) is what clears it"
-            );
-            assert!(
-                app.world().resource::<CastBarFeed>().0.is_empty(),
-                "no local bar edge — the bar closes on the wire's SPELLCAST_CHANNEL_STOP"
-            );
-        }
-    }
-
-    /// The channel mirror's lifecycle: START opens the window for the whole duration, a nonzero
-    /// UPDATE re-times it (pushback shortens channels), UPDATE(0) ends it — and the slack deadline
-    /// self-clears a channel whose closing packet never arrived.
-    #[test]
-    fn active_channel_tracks_the_wire_lifecycle() {
-        let t0 = Instant::now();
-        let mut ch = ActiveChannel::default();
-        assert_eq!(ch.current(t0), None);
-
-        ch.start(10, 5_000, t0); // Arcane Missiles-shaped: 5 s channel
-        assert_eq!(ch.current(t0), Some(10));
-        assert_eq!(
-            ch.current(t0 + Duration::from_secs(4)),
-            Some(10),
-            "still live near the end"
-        );
-        assert_eq!(
-            ch.current(t0 + Duration::from_secs(8)),
-            None,
-            "the slack deadline self-clears a lost UPDATE(0)"
-        );
-
-        // Pushback: an update naming LESS time moves the deadline in.
-        ch.start(10, 5_000, t0);
-        ch.update(1_000, t0);
-        assert_eq!(ch.current(t0 + Duration::from_secs(4)), None);
-
-        // The closing update ends it immediately.
-        ch.start(10, 5_000, t0);
-        ch.update(0, t0);
-        assert_eq!(ch.current(t0), None);
-    }
 }
diff --git a/crates/benilla-app/src/ui_char.rs b/crates/benilla-app/src/ui_char.rs
index cb544a0e..afc34ab0 100644
--- a/crates/benilla-app/src/ui_char.rs
+++ b/crates/benilla-app/src/ui_char.rs
@@ -51,7 +51,7 @@ use benilla_ui::strings::Arg;
 
 use crate::entities::ItemDisplays;
 use crate::items::Items;
-use crate::net::{ClientCommand, NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{ClientCommand, NetCommands, ObjectStore, Objects, SelfPlayer};
 use crate::pending_item_ops::PendingItemOps;
 use crate::portrait::PaperDollBooth;
 use crate::ui_items::{find_equip_slot, item_link};
@@ -99,12 +99,14 @@ struct CharFeedMemo {
     /// (decision 2140).
     last_bank_bag_guids: [u64; BANK_BAG_SLOT_COUNT],
     /// The gate's counter memories (1439) — the stores whose lazy resolves poison `is_changed`
-    /// for this feed (the equipment templates' ask-once, the enchant-name creator lookups).
-    items_objects: gate::Watch,
+    /// for this feed (the equipment templates' ask-once, the enchant-name creator lookups). The
+    /// item OBJECTS are not among them since 2334: an instance is an entity, so its edges arrive
+    /// on the ordinary `Changed`/removal watch ([`crate::items::ItemChanges`]).
     items_templates: gate::Watch,
     names_generation: gate::Watch,
-    /// `Items::countdown_display_epoch` — one step per displayable countdown change (the slot
-    /// views read second-floored countdowns), including the last elapse's collapsing push.
+    /// `ItemChanges::countdown_steps` — one step per displayable countdown change (the slot
+    /// views read second-floored countdowns), including the last elapse's collapsing push; a
+    /// landing is the item's own change tick (decision 2340).
     enchant_deadlines: gate::Watch,
     /// `PendingItemOps::epoch` — one step per change to the in-flight lock set. Watched BESIDE
     /// `!is_empty()` and not instead of it: `is_empty()` holds the gate open *while* an op is in
@@ -151,10 +153,10 @@ type SkillBlock = Option<(u64, std::collections::HashMap<u16, u16>)>;
 /// `PLAYER_SKILL_INFO` descriptor deltas (verified at the vmangos source: no chat send anywhere
 /// in `UpdateSkill*`/`SetSkill`) — so the client diff-watches its own skill block exactly as the
 /// real one does (the rank-field UpdateField watcher `0x5de180` → message facility `0x496720`,
-/// tokens `ERR_SKILL_UP_SI` / `ERR_SKILL_GAINED_S` — wow-re tradeskill TU-E, correcting 0437's
-/// "SKILL_RANK_UP" token guess), prints the GlobalStrings lines on the Skill chat channel, and
-/// fires `SKILL_LINES_CHANGED` on ANY block change (the skills pane's repaint event; TU-E: the
-/// real client fires it from a separate skill-manager TU on add/remove only — ours riding the
+/// tokens `ERR_SKILL_UP_SI` / `ERR_SKILL_GAINED_S` — correcting 0437's "SKILL_RANK_UP" token
+/// guess), prints the GlobalStrings lines on the Skill chat channel, and fires
+/// `SKILL_LINES_CHANGED` on ANY block change (the skills pane's repaint event; the real client
+/// fires it from a separate skill-manager TU (`0x4d2fec`) on add/remove only — ours riding the
 /// same watcher is a benign coarsening, the pane just repaints). **The message gate** (B19/B245,
 /// decisions 1309/1314): both lines are skipped when the line's `SkillRaceClassInfo.flags`
 /// carries `0x402` (`SkillRaceClass::skill_up_silent`) — the class spec lines, racials,
@@ -164,7 +166,7 @@ type SkillBlock = Option<(u64, std::collections::HashMap<u16, u16>)>;
 /// skill-ups still print. The
 /// login fill (empty → populated) and a character switch (self guid change) re-seed silently —
 /// the event fires, the lines don't. Still open: the exact chat channel of the real emitter
-/// (TU-E left `0x496720`'s routing untraced; Skill is the `ChatTypeInfo` family's own key).
+/// (`0x496720`'s routing is untraced; Skill is the `ChatTypeInfo` family's own key).
 /// One skill-watcher line: resolve the key off the player's own `GlobalStrings.lua`, fill it, and
 /// push it as `CHAT_MSG_SKILL`.
 ///
@@ -281,8 +283,8 @@ fn watch_skill_ups(
                         }
                     }
                     // A NEW line: the ERR_SKILL_GAINED_S line (GlobalStrings.lua:1837) — the
-                    // fold-back's second token (wow-re `tradeskill` TU-E: the watcher emits
-                    // both, first-gain vs rank-up).
+                    // fold-back's second token (the watcher `0x5de180` emits both, first-gain vs
+                    // rank-up).
                     None => {
                         if let Some(name) = name() {
                             if announces() {
@@ -314,8 +316,8 @@ fn watch_skill_ups(
 /// off the line's `categoryId` × `SkillLineCategory.dbc` (name + displayOrder) — pushed via
 /// `set_skills` on change; the ENGINE groups/sorts/folds.
 ///
-/// The inclusion predicate is the client's own list build (`0x4d2cb0`, wow-re
-/// `system/tradeskill/scratch/skillframe-display-list.md`), transcribed in its order: a line needs
+/// The inclusion predicate is the client's own list build (`0x4d2cb0`), transcribed in its
+/// order: a line needs
 /// a `SkillLine.dbc` row, an admitting `SkillRaceClassInfo` row and a real `SkillLineCategory` row;
 /// `flags & 0x2` drops it outright; and a line held at **rank 0** appears only if its flags admit
 /// it at this player's level. Note what is NOT a filter: the `Not Displayed` category (12). We used
@@ -433,15 +435,21 @@ fn drain_skill_abandons(script: Option<NonSendMut<UiScript>>, commands: Res<NetC
 
 /// Resolve one equipped slot's item template entry (`None` = empty slot, or the item object /
 /// template hasn't streamed yet).
-fn slot_entry(store: &ObjectStore, items: &Items, slot0: u8) -> Option<u32> {
+fn slot_entry(store: &ObjectStore, objects: &Objects, slot0: u8) -> Option<u32> {
     let guid = store.0.player_inv_slot(slot0)?;
-    items.object(guid)?.object_entry()
+    objects.object(guid)?.object_entry()
 }
 
 /// The equipped item's weapon-skill line id: the vmangos `Item.cpp` subclass table for a class-2
 /// item, unarmed (162) for an empty hand or a non-weapon / unmapped subclass.
-fn weapon_skill_id(store: &ObjectStore, items: &Items, commands: &NetCommands, slot0: u8) -> u32 {
-    let Some(entry) = slot_entry(store, items, slot0) else {
+fn weapon_skill_id(
+    store: &ObjectStore,
+    objects: &Objects,
+    items: &Items,
+    commands: &NetCommands,
+    slot0: u8,
+) -> u32 {
+    let Some(entry) = slot_entry(store, objects, slot0) else {
         return SKILL_UNARMED;
     };
     let Some(t) = items.template(entry, 0, commands) else {
@@ -459,15 +467,13 @@ fn weapon_skill_id(store: &ObjectStore, items: &Items, commands: &NetCommands, s
 /// **The split is not `(value, temp + perm)`, which is what this returned until decision 1812.**
 /// The reader every skill-shaped binding goes through is `0x5ea460`, and it writes
 /// `*out1 = value + permBonus` / `*out2 = tempBonus` — the permanent half folds into the BASE and
-/// only the temporary half is the modifier (VERIFIED, wow-re
-/// `ui/scratch/unitrangedattack-skill-pair.md` §3; the field reads are `+0x84C` `movzx` value,
+/// only the temporary half is the modifier (the field reads are `+0x84C` `movzx` value,
 /// `+0x850` `movsx` temp — the block's only sign-extended read — and `+0x852` `movzx` perm).
 ///
 /// The old shape had the right TOTAL and the wrong halves, which is why nothing caught it: the
 /// paper doll's Attack row prints `base` and colours `base + mod`, so a 300-value line with a +5
 /// talent and a +10 aura read "300" with a green +15 where the reference reads "305" with a green
-/// +10. wow-re's own `object-layer/scratch/w2b2.md` had the two inverted as well, and that is
-/// where ours came from; the same round corrected it there.
+/// +10.
 ///
 /// **The perm add is skipped when the value is 0** (`0x5ea4b4 jle`), so an unknown line stays a
 /// flat 0 rather than reading back a bare talent bonus.
@@ -584,20 +590,25 @@ pub(crate) fn unit_combat_stats(store: &ObjectStore) -> UnitCombatStats {
 
 /// The player's snapshot: [`unit_combat_stats`] plus the half only *we* have — the two values that
 /// need the equipped items' templates, and the three `PLAYER_SKILL_INFO` pairs.
-fn combat_stats(store: &ObjectStore, items: &Items, commands: &NetCommands) -> UnitCombatStats {
+fn combat_stats(
+    store: &ObjectStore,
+    objects: &Objects,
+    items: &Items,
+    commands: &NetCommands,
+) -> UnitCombatStats {
     // The offhand-speed gate is an offhand *weapon* (a shield doesn't swing); the wand check is
     // the ranged item's subclass. Both read the equipped item's template (ask-once in flight →
     // false this frame, refined when it lands).
-    let has_offhand = slot_entry(store, items, SLOT_OFF_HAND)
+    let has_offhand = slot_entry(store, objects, SLOT_OFF_HAND)
         .and_then(|e| items.template(e, 0, commands))
         .is_some_and(|t| t.class == ITEM_CLASS_WEAPON);
-    let has_wand = slot_entry(store, items, SLOT_RANGED)
+    let has_wand = slot_entry(store, objects, SLOT_RANGED)
         .and_then(|e| items.template(e, 0, commands))
         .is_some_and(|t| t.class == ITEM_CLASS_WEAPON && t.subclass == SUBCLASS_WAND);
 
-    let main_skill = weapon_skill_id(store, items, commands, SLOT_MAIN_HAND);
-    let offhand_skill = weapon_skill_id(store, items, commands, SLOT_OFF_HAND);
-    let ranged_skill_id = slot_entry(store, items, SLOT_RANGED)
+    let main_skill = weapon_skill_id(store, objects, items, commands, SLOT_MAIN_HAND);
+    let offhand_skill = weapon_skill_id(store, objects, items, commands, SLOT_OFF_HAND);
+    let ranged_skill_id = slot_entry(store, objects, SLOT_RANGED)
         .and_then(|e| items.template(e, 0, commands))
         .filter(|t| t.class == ITEM_CLASS_WEAPON)
         .and_then(|t| weapon_subclass_skill(t.subclass));
@@ -638,6 +649,7 @@ fn combat_stats(store: &ObjectStore, items: &Items, commands: &NetCommands) -> U
 /// 64..=69). Everything past the guid — template, enchants, durability, the pending lock — is
 /// identical for both, which is the whole reason there is one function here and not two.
 fn slot_view(
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     rolls: crate::items::RollCatalogs,
@@ -653,13 +665,12 @@ fn slot_view(
     guid: u64,
     live_id: u32,
 ) -> Option<InvSlotView> {
-    // The temp-enchant countdowns, read before the object borrow (both live on `Items`) — the bag
-    // feed's twin.
-    let enchant_ms: [Option<u64>; 7] =
-        std::array::from_fn(|s| items.enchant_remaining_display_ms(guid, s as u32));
-    // The item's own expiry countdown — the bag feed's twin (decision 1933).
-    let duration_ms = items.duration_remaining_display_ms(guid);
-    let obj = items.object(guid)?;
+    // The item's own countdown cells — the bag feed's twin (decisions 1933, 2340).
+    let countdowns = objects.countdowns(guid);
+    let enchant_ms: [Option<u64>; crate::items::ENCHANT_SLOTS] =
+        std::array::from_fn(|s| countdowns.and_then(|c| c.enchant_remaining_display_ms(s as u32)));
+    let duration_ms = countdowns.and_then(|c| c.lifetime_remaining_display_ms());
+    let obj = objects.object(guid)?;
     let entry = obj.object_entry()?;
     let count = obj.item_stack_count().unwrap_or(1).max(1);
     // `OBJECT_FIELD_TYPE & TYPEMASK_CONTAINER` — the fork `GetInventoryItemCount` takes first
@@ -679,7 +690,7 @@ fn slot_view(
         .filter(|&(_, max)| max > 0);
     // ITEM_FIELD_FLAGS — the broken/alert laws' wrapped (0x08) and force-red (0x10) bits.
     let flags = obj.item_flags().unwrap_or(0);
-    // `0x5da2c0` — soulbound, or carrying a binding enchant: the equipped tooltip's §6 Soulbound
+    // `0x5da2c0` — soulbound, or carrying a binding enchant: the equipped tooltip's Soulbound
     // override (B310 — the doll is exactly where it was reported). Read off the raw descriptor,
     // never off the enchant LINES below.
     let already_bound = crate::items::already_bound(obj, rolls.enchants);
@@ -739,7 +750,7 @@ fn slot_view(
         if counts_contents {
             content_guids
                 .iter()
-                .filter_map(|&g| items.object(g))
+                .filter_map(|&g| objects.object(g))
                 .map(|o| o.item_stack_count().unwrap_or(1).max(1))
                 .sum()
         } else {
@@ -772,10 +783,10 @@ fn slot_view(
 /// Total carried ammo matching `ammo_id`: the backpack's 16 slots + the four equipped bags'
 /// contents (`GetInventoryItemCount("player", ammo)` counts what you can actually shoot — bank
 /// and buyback never join).
-fn ammo_count(store: &ObjectStore, items: &Items, ammo_id: u32) -> u32 {
+fn ammo_count(store: &ObjectStore, objects: &Objects, ammo_id: u32) -> u32 {
     let mut n = 0;
     let mut add = |guid: Option<u64>| {
-        if let Some(o) = guid.and_then(|g| items.object(g)) {
+        if let Some(o) = guid.and_then(|g| objects.object(g)) {
             if o.object_entry() == Some(ammo_id) {
                 n += o.item_stack_count().unwrap_or(1);
             }
@@ -785,10 +796,10 @@ fn ammo_count(store: &ObjectStore, items: &Items, ammo_id: u32) -> u32 {
         add(store.0.player_pack_slot(i));
     }
     for b in 19..23u8 {
-        if let Some(bag) = store.0.player_inv_slot(b).and_then(|g| items.object(g)) {
+        if let Some(bag) = store.0.player_inv_slot(b).and_then(|g| objects.object(g)) {
             let slots = bag.container_num_slots().unwrap_or(0).min(36) as u8;
             for s in 0..slots {
-                if let Some(o) = bag.container_slot(s).and_then(|g| items.object(g)) {
+                if let Some(o) = bag.container_slot(s).and_then(|g| objects.object(g)) {
                     if o.object_entry() == Some(ammo_id) {
                         n += o.item_stack_count().unwrap_or(1);
                     }
@@ -805,6 +816,7 @@ fn ammo_count(store: &ObjectStore, items: &Items, ammo_id: u32) -> u32 {
 /// 0-based inv-slot array.
 fn inventory_slots(
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     rolls: crate::items::RollCatalogs,
@@ -844,7 +856,7 @@ fn inventory_slots(
             already_bound: false,
             item_id: ammo_id,
             icon,
-            count: ammo_count(store, items, ammo_id),
+            count: ammo_count(store, objects, ammo_id),
             // Ammo is not a container — slot 0 is `GetInventoryItemCount`'s own `PLAYER_AMMO_ID`
             // leg, which never reaches the TYPEMASK fork.
             contents_count: None,
@@ -875,6 +887,7 @@ fn inventory_slots(
             continue;
         };
         inv[live as usize] = slot_view(
+            objects,
             items,
             icons,
             rolls,
@@ -900,6 +913,7 @@ fn inventory_slots(
 /// doll snapshot, rather than the `BankState` the bank window pushes.
 fn bank_bag_slots(
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     rolls: crate::items::RollCatalogs,
@@ -914,6 +928,7 @@ fn bank_bag_slots(
             continue;
         };
         *bag = slot_view(
+            objects,
             items,
             icons,
             rolls,
@@ -1044,8 +1059,9 @@ pub(crate) fn feed_char(
     // (1803). Absent client data reads every class as an ordinary ranged wielder.
     classes: Option<Res<crate::chr_classes::ChrClassTable>>,
     script: Option<NonSendMut<UiScript>>,
-    self_q: Query<&ObjectStore, With<SelfPlayer>>,
-    changed_self: Query<(), (With<SelfPlayer>, Changed<ObjectStore>)>,
+    // The inventory read (2334): the self store, its change tick, the object lookup and the item
+    // entities' change watch.
+    mut inv: crate::items::Inventory,
     items: Res<Items>,
     icons: Option<Res<ItemDisplays>>,
     // `SpellItemEnchantment`'s name column — the equipped tooltip's enchant lines (decision 0915).
@@ -1078,7 +1094,7 @@ pub(crate) fn feed_char(
     // snapshots below re-push and their events re-fire for it.
     let (memo, vm_reset) = feed.vm.get_reset(&script);
 
-    let Some(store) = self_q.iter().next() else {
+    let Some(store) = inv.self_store.iter().next() else {
         // The self store's absence is NO DATA, never "the player has nothing equipped". The one
         // window this branch runs with a previously-fed VM is the logout despawn frames —
         // `SMSG_LOGOUT_COMPLETE` despawns the entity a full Update before `OnExit(InWorld)` runs
@@ -1099,16 +1115,18 @@ pub(crate) fn feed_char(
     // `UNIT_INVENTORY_CHANGED` on every tick. The reference recomputes it per call for exactly
     // the same reason (`0x5d9d00`). Hoisted above the gate (it used to sit last): the push is
     // order-free of the two snapshots, and a handler they fire reads the fresher value this way.
+    // Bound before the snapshot build below shadows `inv` with the pushed slot array.
+    let objects = &inv.objects;
     script.set_weapon_enchants(
-        weapon_enchant(store, &items, EQUIPMENT_SLOT_MAINHAND),
-        weapon_enchant(store, &items, EQUIPMENT_SLOT_OFFHAND),
+        weapon_enchant(store, objects, EQUIPMENT_SLOT_MAINHAND),
+        weapon_enchant(store, objects, EQUIPMENT_SLOT_OFFHAND),
     );
 
     // The gate (1439), around the two snapshot builds only: the self descriptor (equipment
     // slots, every stat field), the item stores behind the equipped templates and enchant
     // names, the two catalogs, and the pending-op locks (held open while in flight; the
     // resolving frame's own field update moves the object epoch).
-    let objects_moved = memo.items_objects.moved(items.object_epoch());
+    let objects_moved = inv.changes.moved();
     let templates_moved = memo.items_templates.moved(items.template_epoch());
     let names_moved = memo.names_generation.moved(names.generation());
     // The DISPLAY epoch, not a per-frame hold-open: the snapshot reads second-floored countdowns
@@ -1116,10 +1134,8 @@ pub(crate) fn feed_char(
     // second per ticking enchant, plus one final step at the elapse. Holding the gate open on
     // `live_enchant_deadlines() > 0` (the first 1439 shape) rebuilt both snapshots and fired
     // `UNIT_INVENTORY_CHANGED` at frame rate for the whole life of a poison.
-    let deadlines_moved = memo
-        .enchant_deadlines
-        .moved(items.countdown_display_epoch());
-    let self_changed = !changed_self.is_empty();
+    let deadlines_moved = memo.enchant_deadlines.moved(inv.changes.countdown_steps());
+    let self_changed = !inv.self_changed.is_empty();
     // `is_added` for the icon catalog: the feeds read only its load-once icon column;
     // its model-cache half churns every frame (the containers gate's own note).
     let icons_added = icons.as_ref().is_some_and(|r| r.is_added());
@@ -1159,7 +1175,7 @@ pub(crate) fn feed_char(
         return;
     }
 
-    let stats = combat_stats(store, &items, &commands);
+    let stats = combat_stats(store, objects, &items, &commands);
     if memo.last_stats.as_ref() != Some(&stats) {
         gate.audit("feed_char", "the combat-stats snapshot");
         // PUSH before firing: event dispatch runs the Lua handlers synchronously, so the snapshot
@@ -1173,6 +1189,7 @@ pub(crate) fn feed_char(
 
     let inv = inventory_slots(
         store,
+        objects,
         &items,
         icons.as_deref(),
         crate::items::RollCatalogs {
@@ -1187,6 +1204,7 @@ pub(crate) fn feed_char(
     );
     let bank_bags = bank_bag_slots(
         store,
+        objects,
         &items,
         icons.as_deref(),
         crate::items::RollCatalogs {
@@ -1204,7 +1222,7 @@ pub(crate) fn feed_char(
     // `PLAYERBANKSLOTS_CHANGED`'s two producers, planned off the OLD memo before the push
     // replaces it. `false` = P1, the player-descriptor path (`0x5ddd6e`, no arguments — a bag
     // arriving, leaving or exchanged); `true` = P2, the item-object path (`0x4c728d`,
-    // `arg1 = "player"` — the same bag, its own fields changed). The full carve and why the guid
+    // `arg1 = "player"` — the same bag, its own fields changed). The full account and why the guid
     // is the only sound discriminator are at `ui_items::feed`'s vault twin; decision 2140.
     let bank_bag_guids: [u64; BANK_BAG_SLOT_COUNT] =
         std::array::from_fn(|i| store.0.player_bank_bag_slot(i as u8).unwrap_or(0));
@@ -1239,9 +1257,8 @@ pub(crate) fn feed_char(
         // announces the band whose data it owns, and `feed_char` is ordered first, so both fire
         // after their own push.
         //
-        // **Which arguments it carries depends on WHICH producer fired** (CARVED — wow-re
-        // `system/object-layer/scratch/bank-slot-event-law.md` §3/§4, folded back in 2140). The
-        // descriptor watcher `0x5ddd6e` calls `FrameScript_SignalEvent 0x703e50`, an
+        // **Which arguments it carries depends on WHICH producer fired** (folded back in 2140).
+        // The descriptor watcher `0x5ddd6e` calls `FrameScript_SignalEvent 0x703e50`, an
         // `__fastcall(ecx = id)` with a plain `ret` and no vararg push — zero Lua values; the
         // item-object notifier `0x4c728d` goes through `SignalEvent2` and pushes the literal
         // string `"player"`. benilla fired the argless one for both until 2140. An event is fired
@@ -1301,14 +1318,15 @@ const TEMP_ENCHANTMENT_SLOT: u8 = 1;
 /// else, and `item_enchant` already answers `None` for a zero id.
 fn weapon_enchant(
     store: &ObjectStore,
-    items: &Items,
+    objects: &Objects,
     slot0: u8,
 ) -> Option<benilla_ui::script::WeaponEnchant> {
     let guid = store.0.player_inv_slot(slot0)?;
-    // Before the object borrow — the deadlines and the objects both live on `Items`. The
-    // *deadline* read, not the tooltip's: an elapsed timer must answer 0, not "no timer".
-    let remaining_ms = items.enchant_deadline_ms(guid, u32::from(TEMP_ENCHANTMENT_SLOT));
-    let obj = items.object(guid)?;
+    // The *deadline* read, not the tooltip's: an elapsed timer must answer 0, not "no timer".
+    let remaining_ms = objects
+        .countdowns(guid)
+        .and_then(|c| c.enchant_deadline_ms(u32::from(TEMP_ENCHANTMENT_SLOT)));
+    let obj = objects.object(guid)?;
     obj.item_enchant(TEMP_ENCHANTMENT_SLOT)?;
     Some(benilla_ui::script::WeaponEnchant {
         remaining_ms,
@@ -1323,8 +1341,7 @@ mod tests {
     use bevy::ecs::system::RunSystemOnce;
 
     /// **The skill pair splits `(value + PERM, TEMP)`, not `(value, temp + perm)`** — the reader
-    /// every skill-shaped binding goes through (`0x5ea460`, VERIFIED: wow-re
-    /// `ui/scratch/unitrangedattack-skill-pair.md` §3).
+    /// every skill-shaped binding goes through (`0x5ea460`).
     ///
     /// It reported the right TOTAL and the wrong halves until decision 1812, which is exactly why
     /// nothing caught it: `UnitAttackBothHands`'s caller prints the base and colours `base + mod`,
@@ -1383,6 +1400,20 @@ mod tests {
     const BAG_ENTRY: u32 = 4500;
     const BAG: u64 = 0x4000_0000_0000_0abc;
 
+    /// Re-stream one live item object's fields — the wire's values delta, which is what moves
+    /// the item entity's own change tick (2334); the create-time spawn is
+    /// [`crate::items::test_spawn_item`].
+    fn restream(app: &mut App, guid: u64, fields: ObjectFields) {
+        let entity = app
+            .world()
+            .resource::<crate::net::GuidIndex>()
+            .0
+            .get(&guid)
+            .copied()
+            .expect("the item was streamed");
+        *app.world_mut().get_mut::<ObjectStore>(entity).unwrap() = ObjectStore(fields);
+    }
+
     /// A world with the player carrying `bag` (or nothing) in the FIRST bank bag slot, and a
     /// recorder frame registered for the two events the reference's bank bag buttons repaint on.
     fn world_with_bank_bag(bag: Option<u64>) -> App {
@@ -1392,6 +1423,7 @@ mod tests {
             .init_resource::<PaperDollBooth>()
             .init_resource::<PendingItemOps>()
             .init_resource::<Items>()
+            .init_resource::<crate::net::GuidIndex>()
             .init_resource::<crate::names::NameCache>()
             .insert_resource(NetCommands(tx));
         let fields = match bag {
@@ -1403,9 +1435,14 @@ mod tests {
         };
         app.world_mut().spawn((SelfPlayer, ObjectStore(fields)));
         if let Some(g) = bag {
-            let mut items = app.world_mut().resource_mut::<Items>();
-            items.insert_object(g, ObjectFields::from_pairs(&[(F_OBJECT_ENTRY, BAG_ENTRY)]));
-            items.insert_template(
+            // The bag is an object in the one index (2334), its template still on `Items`.
+            crate::items::test_spawn_item(
+                app.world_mut(),
+                g,
+                ObjectFields::from_pairs(&[(F_OBJECT_ENTRY, BAG_ENTRY)]),
+                true,
+            );
+            app.world_mut().resource_mut::<Items>().insert_template(
                 BAG_ENTRY,
                 Some(crate::items::test_template("Traveler's Backpack")),
             );
@@ -1467,8 +1504,10 @@ mod tests {
         app.world_mut().run_system_once(feed_char).unwrap();
         assert!(seen(&mut app).contains(&"PLAYERBANKSLOTS_CHANGED nil".to_string()));
 
-        // The SAME bag guid, restacked. Only the item object moved.
-        app.world_mut().resource_mut::<Items>().insert_object(
+        // The SAME bag guid, restacked. Only the item object moved — a values update on the
+        // live item entity, which is what the wire's own delta is (2334).
+        restream(
+            &mut app,
             BAG,
             ObjectFields::from_pairs(&[(F_OBJECT_ENTRY, BAG_ENTRY), (F_ITEM_STACK_COUNT, 3)]),
         );
@@ -1504,9 +1543,11 @@ mod tests {
             ]));
         };
         set_slots(&mut app, BAG, BAG2);
-        app.world_mut().resource_mut::<Items>().insert_object(
+        crate::items::test_spawn_item(
+            app.world_mut(),
             BAG2,
             ObjectFields::from_pairs(&[(F_OBJECT_ENTRY, BAG_ENTRY)]),
+            true,
         );
         app.world_mut().run_system_once(feed_char).unwrap();
         let _ = seen(&mut app);
diff --git a/crates/benilla-app/src/ui_chat.rs b/crates/benilla-app/src/ui_chat.rs
index 141fd711..ab1456a0 100644
--- a/crates/benilla-app/src/ui_chat.rs
+++ b/crates/benilla-app/src/ui_chat.rs
@@ -40,6 +40,7 @@ mod input;
 mod language;
 /// `LoggingChat`/`LoggingCombat` — the two log files `/chatlog` and `/combatlog` toggle.
 mod logging;
+mod net;
 /// The `AUTO_JOIN_GUILD_CHANNEL` cascade (decision 2144) — the one place the client joins or
 /// leaves `GuildRecruitment - City` on its own.
 mod recruitment;
@@ -75,6 +76,7 @@ pub(crate) struct UiChatPlugin;
 
 impl Plugin for UiChatPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.add_observer(combat::on_cvar);
         app.init_resource::<ChatLog>()
             .init_resource::<away::AfkMirror>()
@@ -163,7 +165,7 @@ impl Plugin for UiChatPlugin {
             // the queue for the frames after it, and this is what holds it for that one.
             //
             // **…and after the world-enter cascade, because that is the reference's own order**
-            // (decision 2221, carved in wow-5875-re for this — their `ca5f7d38`). The real client does not print
+            // (decision 2221). The real client does not print
             // login chat when it arrives either: `[0x8435fc]` is a latch that ships statically
             // `1`, so every `SMSG_MESSAGECHAT` in the login burst is queued into
             // `__AUPENDINGCHAT__` (`0x49db5c`/`0x49db62` → `0x49cae0`) instead of displayed. It is
@@ -172,7 +174,7 @@ impl Plugin for UiChatPlugin {
             // call drains the queue. `SMSG_GUILD_EVENT` 0x02 has no such latch: it fires
             // `GUILD_MOTD` synchronously in its own handler (`0x5e7288`). So the reference paints
             // the guild line FIRST and the realm's welcome lines after it, inverting the wire
-            // order — and that is what the report asked for ("before server messages").
+            // order.
             //
             // Our held `ChatLog` queue IS that latch: the early return above `mem::take` is what
             // keeps the login burst waiting. This says when it drains. Without these two edges
@@ -280,7 +282,7 @@ impl Plugin for UiChatPlugin {
 /// **The chat module's session end** — what the reference gets for free by destroying its Lua
 /// state, and we have to do by hand until that teardown lands (1288).
 ///
-/// `shutdown_ui_state`'s own doc carves the reference's logout tail: `PLAYER_LEAVING_WORLD` →
+/// `shutdown_ui_state`'s own doc records the reference's logout tail: `PLAYER_LEAVING_WORLD` →
 /// `PLAYER_LOGOUT` → the saved files → **destroy the Lua state**. That last step is the one
 /// `crate::ui_script::IngameUiLoaded` exists to stand in for; while it does, every window in the
 /// VM keeps its contents across a character switch. The director saw it as the previous
diff --git a/crates/benilla-app/src/ui_chat/ace_gate_tests.rs b/crates/benilla-app/src/ui_chat/ace_gate_tests.rs
index ab843a42..375d20cb 100644
--- a/crates/benilla-app/src/ui_chat/ace_gate_tests.rs
+++ b/crates/benilla-app/src/ui_chat/ace_gate_tests.rs
@@ -32,53 +32,17 @@
 //! **Nothing from the corpus is committed**, and the tests skip cleanly on a machine without it
 //! (see [`corpus`]) — a checkout with no addon folder must never go red here.
 
-use std::path::{Path, PathBuf};
+use std::path::Path;
 
 use benilla_ui::script::UiScript;
 
 use super::event::{ChatEvent, ChatEventKind as K};
 use super::frames::{route, ChatWindows};
 
-/// Where the vanilla addon corpus might be, in order. `$BENILLA_ADDON_CORPUS` first so a machine
-/// that keeps it elsewhere needs no patch; then the sibling checkout, resolved from this crate's
-/// manifest rather than the cwd (a pool worktree's cwd is not stable across tool calls, and
-/// `CARGO_MANIFEST_DIR` is).
-fn corpus_candidates() -> Vec<PathBuf> {
-    let mut out = Vec::new();
-    if let Some(over) = std::env::var_os("BENILLA_ADDON_CORPUS") {
-        out.push(PathBuf::from(over));
-    }
-    // …/<checkout>/crates/benilla-app → up to the checkout, then to its parent(s). A pool slot
-    // lives one level deeper than the primary checkout, so both hops are tried.
-    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
-    for up in [2usize, 3, 4] {
-        if let Some(root) = manifest.ancestors().nth(up) {
-            out.push(root.join("wow-addons-vanilla"));
-        }
-    }
-    out
-}
-
-/// The corpus root, or `None`. **`None` is a skip, never a failure**: the corpus is third-party
-/// content that is deliberately not in this repo, so a machine without it must still be green.
-fn corpus() -> Option<PathBuf> {
-    corpus_candidates().into_iter().find(|c| c.is_dir())
-}
-
-macro_rules! corpus_or_skip {
-    () => {
-        match corpus() {
-            Some(root) => root,
-            None => {
-                eprintln!(
-                    "skipping: no vanilla addon corpus — looked in {:?} (set $BENILLA_ADDON_CORPUS)",
-                    corpus_candidates()
-                );
-                return;
-            }
-        }
-    };
-}
+/// The corpus, or a skip — `benilla_formats::addon_corpus_or_skip!`, the one resolver (its doc
+/// carries the incident: five copies of a ladder that looked beside the checkout, and thirty
+/// tests that skipped at every land once the pool moved).
+use benilla_formats::addon_corpus_or_skip as corpus_or_skip;
 
 /// FuBar's `.toc` load order for the four files the gate lives in (`FuBar/FuBar.toc:16-19`).
 /// AceEvent is last because it needs all three under it — AceLibrary to register into, Compost for
@@ -128,6 +92,7 @@ fn gate_open(s: &UiScript) -> bool {
 /// end to end — not a hand-rolled `fire_event`.
 #[test]
 fn a_you_joined_notice_opens_ace2s_initialisation_gate() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = ace_vm(&root);
     let mut windows = ChatWindows::default();
@@ -186,6 +151,7 @@ fn a_you_joined_notice_opens_ace2s_initialisation_gate() {
 /// gate and the headline is measuring the wrong thing.
 #[test]
 fn without_the_notice_the_gate_stays_shut() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = ace_vm(&root);
     for _ in 0..40 {
@@ -210,7 +176,7 @@ fn the_auto_join_walk_names_the_channels_the_server_resolves() {
 
     // The city word is DBC data, so read it the way the walk does rather than spelling it here —
     // that this resolves to "City" at all is the finding (`AreaTable.dbc` row 3459,
-    // `Flags & 0x200`; wow-re `zone-chat-channel-autojoin.md` §3).
+    // `Flags & 0x200`, the row `0xb4e4f0` caches).
     let areas = benilla_formats::load_area_table_catalog(&mut chain).expect("AreaTable.dbc");
     let city = super::channels::city_word(&areas);
     assert_eq!(
diff --git a/crates/benilla-app/src/ui_chat/away.rs b/crates/benilla-app/src/ui_chat/away.rs
index 196f1d32..9cf3240c 100644
--- a/crates/benilla-app/src/ui_chat/away.rs
+++ b/crates/benilla-app/src/ui_chat/away.rs
@@ -1,6 +1,4 @@
-//! **`/afk` and `/dnd` — the client-side command law** (decision 2088; wow-re
-//! `ui/scratch/afk-dnd-command-law.md`, a §5 trio incl. one cold derivation + orchestrator
-//! arbitration).
+//! **`/afk` and `/dnd` — the client-side command law** (decision 2088).
 //!
 //! The two commands look like a pair and are not one. `SendChatMessage 0x49f1e0` handles them
 //! **asymmetrically**, and the reference's own string pool shows why: the DND keys live in the chat
@@ -12,7 +10,7 @@
 //!   descriptor bit — and returns, delegating to `CGPlayer_C::SetAFK 0x5eb740` /
 //!   `ClearAFK 0x5eb830`, which build their own packets.
 //!
-//! **The echo is OPTIMISTIC, never descriptor-driven** (§8): the print and the mirror write are
+//! **The echo is OPTIMISTIC, never descriptor-driven**: the print and the mirror write are
 //! straight-line before the send. `0x5ee990`'s `test al,0xe` arm — the `PLAYER_FLAGS` delta arm
 //! that carries AFK/DND/GM — calls only `0x6c78f0` (name invalidation) and `0x468550` between
 //! `0x5ee9c0` and `0x5ee9f8`: no string resolve, no chat sink. So a client that waited for the
@@ -34,17 +32,17 @@ use super::feed::ChatLog;
 /// bit**, reconciled by the descriptor. Authoritative for the client's own toggle decision, never
 /// for anyone else's state.
 ///
-/// Its full 11-site census is wow-re `afk-dnd-command-law.md` §8. Written optimistically at command
-/// time (`SetAFK 0x5eb7ae` ← 1, `ClearAFK 0x5eb885` ← 0), reconciled from the descriptor on every
-/// local `PLAYER_FLAGS` delta (`0x5ee9f2`), re-seeded at world enter (`0x4989c0`, §9 — which is
-/// **not** the `/afk` toggle, a correction that round made to `overhead-name.md`). Consumed by the
-/// overhead-name AFK tag as the own-player override, and by the `/afk` toggle itself.
+/// Eleven sites in the image reference it. Written optimistically at command time
+/// (`SetAFK 0x5eb7ae` ← 1, `ClearAFK 0x5eb885` ← 0), reconciled from the descriptor on every local
+/// `PLAYER_FLAGS` delta (`0x5ee9f2`), re-seeded at world enter (`0x4989c0`, which is **not** the
+/// `/afk` toggle). Consumed by the overhead-name AFK tag as the own-player override, and by the
+/// `/afk` toggle itself.
 ///
 /// **`u32`, not `bool`, and never compared against 1.** The five writers store **three** truthy
 /// values — `1` (`0x4989eb`, `0x5eb7ae`), `0` (`0x4989f7`, `0x5eb885`) and **`2`** (`0x5ee9f2`
 /// stores `PLAYER_FLAGS & 2`). All six readers are pure non-zero tests, so the reference never
 /// notices; a re-implementation that types this `bool` or tests `== 1` diverges at the first
-/// descriptor-driven set. That is a stated hazard in §8, and this type is the answer to it.
+/// descriptor-driven set. That is the hazard, and this type is the answer to it.
 ///
 /// **There is no DND mirror** — no global is written on the DND path, which is why [`dnd_line`]
 /// takes the live descriptor bit and [`afk_line`] takes this. The observable asymmetry is real and
@@ -79,7 +77,7 @@ pub(crate) struct AwayOutcome {
     pub(crate) body: String,
 }
 
-/// Resolve `/afk <msg>` against the mirror — wow-re §3/§4/§5 and the §12 truth table.
+/// Resolve `/afk <msg>` against the mirror — the AFK arm `0x49f4f3`-`0x49f562`.
 ///
 /// | `msg` | mirror before | line | mirror after |
 /// |---|---|---|---|
@@ -88,7 +86,7 @@ pub(crate) struct AwayOutcome {
 /// | `M` | clear | `MARKED_AFK_MESSAGE` % `M` | 1 |
 /// | `M` | set | *(nothing)* | unchanged |
 ///
-/// **The default text is the CLIENT's and is substituted BEFORE the send** (§2): the server
+/// **The default text is the CLIENT's and is substituted BEFORE the send** (`0x49f512`): the server
 /// receives the literal `"Away from Keyboard"`, never an empty body, so vmangos stores that as the
 /// auto-reply. `SetAFK` substitutes again for a NULL message (`0x5eb761`) — belt and braces in the
 /// reference, one substitution here.
@@ -136,7 +134,8 @@ pub(crate) fn afk_line(
     }
 }
 
-/// Resolve `/dnd <msg>` against the **live** `PLAYER_FLAGS` bit `0x4` — wow-re §6 and §12.
+/// Resolve `/dnd <msg>` against the **live** `PLAYER_FLAGS` bit `0x4` — the DND arm
+/// `0x49f3de`-`0x49f591`.
 ///
 /// | `msg` | DND before | line |
 /// |---|---|---|
@@ -182,8 +181,7 @@ pub(crate) fn dnd_line(
 /// zeroes the mirror, then goes on to send the message's own packet.
 ///
 /// **It runs before the refusal arms, not after** — `0x49f3c7`/`0x49f3d6` sit above `0x49f592`, so
-/// a ghost typing `/say` clears AFK and *then* gets `ERR_CHAT_WHILE_DEAD`. (One worker in the §5
-/// round put this the other way round; the orchestrator's byte arbitration rejected it — §13.)
+/// a ghost typing `/say` clears AFK and *then* gets `ERR_CHAT_WHILE_DEAD`.
 pub(crate) fn auto_clear_line(
     mirror: AfkMirror,
     auto_clear_afk: bool,
@@ -240,12 +238,11 @@ pub(crate) struct AfkMirrorMemo(Option<u32>);
 /// writes `PLAYER_FLAGS & 2` (`0x5ee9ef`/`0x5ee9f2`). A reconcile that instead wrote on *any*
 /// flags delta would clobber the optimistic `1` back to `0` the first time an unrelated bit moved
 /// — walk into an inn while AFK and the resting bit alone would drop your `<AFK>` a round trip
-/// early. The whole point of the mirror is that it is allowed to lead the descriptor (§8: "the
-/// mirror can lead the descriptor for exactly one round trip"), and this gate is what protects
-/// that window.
+/// early. The whole point of the mirror is that it is allowed to lead the descriptor (for exactly
+/// one round trip), and this gate is what protects that window.
 ///
 /// The value written is `flags & 0x2` — so **`2`, not `1`** — which is exactly why [`AfkMirror`]
-/// is a `u32` tested for non-zero and never compared against `1` (§8's stated encoding hazard).
+/// is a `u32` tested for non-zero and never compared against `1`.
 pub(crate) fn reconcile_afk_mirror(
     self_q: Query<&crate::net::ObjectStore, With<crate::net::SelfPlayer>>,
     mut mirror: ResMut<AfkMirror>,
@@ -267,7 +264,7 @@ pub(crate) fn reconcile_afk_mirror(
     }
 }
 
-/// The **four movement clears** — `autoClearAFK`'s other call sites (wow-re §10):
+/// The **four movement clears** — `autoClearAFK`'s other call sites:
 /// `Jump 0x513d36`, forward/back `0x514e23`, strafe `0x514f0b`, keyboard-turn `0x514fca`. All four
 /// share one idiom — `if (OBJECT_FIELD_TYPE & TYPEMASK_PLAYER) ClearAFK(obj, 0)` sitting right
 /// after the same function's stand-up call — so they are one rule here, not four.
@@ -343,7 +340,7 @@ mod tests {
         )
     }
 
-    /// **wow-re `afk-dnd-command-law.md` §12, transcribed.** Every row, including the three that a
+    /// **The reference's truth table, transcribed.** Every row, including the three that a
     /// re-implementer gets wrong by symmetry.
     #[test]
     fn the_truth_table_row_for_row() {
@@ -417,7 +414,7 @@ mod tests {
         );
         // **The asymmetry.** `/dnd M` while DND RE-PRINTS, where `/afk M` while AFK is silent.
         // Not a bug on either side: AFK reads its optimistic mirror, DND reads the live descriptor
-        // bit and has no mirror at all (§8).
+        // bit and has no mirror at all (`0x49f3f0`).
         assert_eq!(
             dnd("busy", true),
             AwayOutcome {
@@ -432,8 +429,8 @@ mod tests {
     /// **The director's capture, reproduced: THREE lines from TWO commands.**
     ///
     /// `/afk` then `/dnd` prints the mark, then the implicit AFK clear, then the DND mark — because
-    /// `/dnd` is chat type `0x15` and the auto-clear skips only `0x14` (§10). Anyone reading the
-    /// reference screenshot as three typed commands would build the wrong thing.
+    /// `/dnd` is chat type `0x15` and the auto-clear skips only `0x14` (`0x49f4f6`). Anyone reading
+    /// the reference screenshot as three typed commands would build the wrong thing.
     #[test]
     fn afk_then_dnd_prints_three_lines() {
         let mut mirror = AfkMirror::default();
@@ -476,7 +473,7 @@ mod tests {
             "not afk"
         );
         assert!(auto_clear_line(AfkMirror(1), true, &strings).is_some());
-        // **The descriptor-driven value is 2, not 1** (§8's encoding hazard): the reconcile stores
+        // **The descriptor-driven value is 2, not 1** (`0x5ee9f2`): the reconcile stores
         // `PLAYER_FLAGS & 2`. A mirror typed `bool`, or tested `== 1`, would answer "not AFK" here
         // and silently stop clearing after the server's first confirmation.
         assert!(
diff --git a/crates/benilla-app/src/ui_chat/broadcast.rs b/crates/benilla-app/src/ui_chat/broadcast.rs
index d77c5f91..0ed9e9b9 100644
--- a/crates/benilla-app/src/ui_chat/broadcast.rs
+++ b/crates/benilla-app/src/ui_chat/broadcast.rs
@@ -13,7 +13,7 @@
 //! This is the part a reimplementation gets wrong, and the reference is unambiguous about it. Both
 //! handlers (`0x49dcc0` for ZONE_UNDER_ATTACK, `0x49de30` for DEFENSE_MESSAGE) end in the same
 //! loop over the client's own joined-channel array (`[0xb4fe04]`, count `[0xb4fe00]`, stride
-//! `0xa0` — wow-re `system/ui/scratch/chat-msg-event-args.md` §7 owns that record), delivering the
+//! `0xa0`), delivering the
 //! text once per surviving channel as chat type **`0xE` = `CHAT_MSG_CHANNEL`** with a NULL sender
 //! and language `0`. `0x49de04` and `0x49df4c` are the **only two sites in the whole image** that
 //! hand the composer a literal chat type `0xE`: engine-composed channel chat exists for these two
@@ -248,8 +248,8 @@ pub(super) fn feed_broadcasts(
                 // An absent key shows nothing — this crate's uniform GlobalStrings stance, and a
                 // deliberate half-step short of the reference: `0x496720` suppresses on the message
                 // record's own key field being NULL or empty (`0x4967c5`), but `FrameScript_GetText`
-                // returns `""` rather than NULL for a missing global (VERIFIED, wow-re
-                // `world-broadcast-opcodes.md` §5), so a broken `GlobalStrings.lua` would make the
+                // returns `""` rather than NULL for a missing global (`0x703c02` seeds it), so a
+                // broken `GlobalStrings.lua` would make the
                 // reference print an EMPTY line here rather than none. Showing nothing is what every
                 // other tenant of this route does; diverging in one module would be the
                 // inconsistency.
@@ -427,6 +427,7 @@ mod tests {
     /// divergence.
     #[test]
     fn a_defense_line_renders_with_the_references_bare_colon() {
+        benilla_formats::wow_data_or_skip!();
         let event = ChatEvent {
             kind: Some(ChatEventKind::Channel),
             text: "|cffffff00Sentinel Hill is under attack!|r".into(),
diff --git a/crates/benilla-app/src/ui_chat/channels.rs b/crates/benilla-app/src/ui_chat/channels.rs
index f87ac012..549dbe58 100644
--- a/crates/benilla-app/src/ui_chat/channels.rs
+++ b/crates/benilla-app/src/ui_chat/channels.rs
@@ -15,9 +15,8 @@
 //! name *inside* the channel name, so crossing a border is genuinely leaving one channel and
 //! joining another — LEAVE(old) then JOIN(new), interleaved per slot.
 //!
-//! The mechanism is byte-verified in wow-re's `system/ui/scratch/zone-chat-channel-autojoin.md`
-//! (the whole thing is one function, `ZoneChannelRefresh 0x49a210`); each part below cites the
-//! section it comes from.
+//! The whole mechanism is one function of the reference, `ZoneChannelRefresh 0x49a210`; each part
+//! below cites the address it comes from.
 //!
 //! ## Why this is worth more than three channel names
 //!
@@ -53,11 +52,10 @@ const AREA_FLAG_TRADE_CHANNEL: u32 = 0x08;
 /// word** the Trade channel is named after.
 ///
 /// Not a geographic area at all: the client scans the table once at load for this bit and keeps
-/// the row's name at `0xb4e4f0` (single writer `0x4985fd`), then splices it into `Trade - %s`
-/// (wow-re `system/ui/scratch/zone-chat-channel-autojoin.md` §3, VERIFIED). Exactly one row in the
-/// shipped 5875 table carries it — **id 3459, `AreaName[enUS] = "City"`** — which is the whole
-/// reason the word appears nowhere in `WoW.exe`. Reading it here rather than hardcoding `"City"`
-/// is what keeps a localized install localized.
+/// the row's name at `0xb4e4f0` (single writer `0x4985fd`), then splices it into `Trade - %s`.
+/// Exactly one row in the shipped 5875 table carries it — **id 3459, `AreaName[enUS] = "City"`** —
+/// which is the whole reason the word appears nowhere in `WoW.exe`. Reading it here rather than
+/// hardcoding `"City"` is what keeps a localized install localized.
 const AREA_FLAG_CITY_NAME_ROW: u32 = 0x200;
 
 /// The shared city word, scanned out of `AreaTable.dbc` — the client's own load-time scan
@@ -236,7 +234,7 @@ pub(super) fn load_chat_channels(
 ///
 /// The client has no such guard — its capital arm null-checks the DBC row pointer but not the
 /// string, so a locale with the sentinel row's name blank would compose exactly `"Trade - "`
-/// (wow-re `zone-chat-channel-autojoin.md`, branch caveat). We decline instead: joining the wrong
+/// (`0x49a2d0`–`0x49a2f6`). We decline instead: joining the wrong
 /// channel name is invisible and permanent, and joining none is neither.
 fn compose(
     row: &benilla_formats::ChatChannelRow,
@@ -259,10 +257,10 @@ fn compose(
 /// [`plan_walk`]'s pass 2 — the walk itself plans over the slot array.
 ///
 /// The reference registers the slot (`0x49b980`) *before* it asks whether the row is eligible:
-/// `0x49a50d` precedes the city gate at `0x49a512` (wow-re `zone-chat-channel-autojoin.md` §7 pass
-/// 2, §11). So a character standing outside a capital still holds a `Trade - City` slot — created,
-/// never joined, state 3 — and it still occupies **number 2**, because the `N.` a channel line
-/// carries is `slot[+0x00]`, the client-local index, never the `ChatChannels.dbc` ChannelID.
+/// `0x49a50d` precedes the city gate at `0x49a512`. So a character standing outside a capital
+/// still holds a `Trade - City` slot — created, never joined, state 3 — and it still occupies
+/// **number 2**, because the `N.` a channel line carries is `slot[+0x00]`, the client-local index,
+/// never the `ChatChannels.dbc` ChannelID.
 #[cfg(test)]
 pub(crate) fn tracked_channels(
     catalog: &ChatChannelsCatalog,
@@ -323,8 +321,7 @@ pub(crate) enum WalkStep {
 }
 
 /// **The walk, as a plan** — `ZoneChannelRefresh 0x49a210`'s two passes over the current slot
-/// array and the mask, for a player standing in `zone_name` (wow-re
-/// `zone-chat-channel-autojoin.md` §7, VERIFIED).
+/// array and the mask, for a player standing in `zone_name`.
 ///
 /// **Pass 1 — the slots already held**, in slot order (`0x49a284`), each one whose name resolves
 /// to a `ChatChannels.dbc` row. The row's name is composed for this zone, **whatever the mask
@@ -336,7 +333,8 @@ pub(crate) enum WalkStep {
 ///   changed; not eligible ⇒ nothing.
 /// - **name unchanged, otherwise** ⇒ nothing, unless the row stopped being eligible: then
 ///   `Leave` (only if server-confirmed) and `Suspend` — walking out of the city; the LEAVE goes
-///   out *before* the gate suspends the slot because it sits earlier in the same iteration (§5).
+///   out *before* the gate (`0x49a3b8`) suspends the slot because it sits earlier in the same
+///   iteration.
 /// - **name moved** ⇒ `Leave(old)` if server-confirmed (`0x49a35e`), then the gate: eligible ⇒
 ///   `Rename` + `Join(new)`; not eligible ⇒ `Suspend(old)`.
 /// - **the row no longer composes here** (no city word for a city-named row) ⇒ treated as not
@@ -351,7 +349,7 @@ pub(crate) enum WalkStep {
 /// a `/join General` confirms and sets the bit back.
 ///
 /// LEAVE strictly precedes JOIN per slot, interleaved across slots — never a batch of leaves then
-/// a batch of joins. The retail 1.8.1 Winterspring sniff shows exactly this shape (§7).
+/// a batch of joins. The retail 1.8.1 Winterspring sniff shows exactly this shape.
 pub(crate) fn plan_walk(
     channels: &ChannelState,
     zone_name: &str,
@@ -493,10 +491,10 @@ fn zone_is_settled(player: Option<&crate::player::Player>) -> bool {
 /// display text. That is not a preference: the client composes from `GetRealZoneText`'s own cache
 /// (`0xb4b404`, written from the parent zone's `AreaName_lang`), and the indoor/WMO name override
 /// `0x67e670` rewrites only the slot feeding `GetZoneText`, never the one that becomes a channel
-/// name (wow-re `zone-chat-channel-autojoin.md` §3). So a building never renames your channel.
+/// name. So a building never renames your channel.
 ///
-/// **Timing:** the client re-walks inside `UpdateZoneText 0x494780` on every zone change (`§1`,
-/// callsite `0x494931`), immediately *before* it fires `ZONE_CHANGED_NEW_AREA`, plus once at world
+/// **Timing:** the client re-walks inside `UpdateZoneText 0x494780` on every zone change (callsite
+/// `0x494931`), immediately *before* it fires `ZONE_CHANGED_NEW_AREA`, plus once at world
 /// entry. This polls the same two inputs each frame and early-outs when they have not moved, which
 /// reaches the same states; it is a poll rather than a hook because the zone is already derived
 /// here, not published as an event payload.
@@ -551,7 +549,7 @@ pub(super) fn auto_join_zone_channels(
     // sites that read the reference's cinematic-state cell exist for exactly this — `0x49491e`
     // (the zone-text update) and `0x5ff566` (a `UPDATEFLAGS` reflex) both skip
     // `ZoneChannelRefresh` (`0x49a210`) while one runs, and `EndCinematic` calls it once at
-    // `0x48f1d0` (wow-re `ui/scratch/cinematic-camera-law.md` §3.3, the complete 10-site census).
+    // `0x48f1d0` (the cell is `[0xb4e310]`; the ten sites are its complete census).
     //
     // The walk stays armed and only its *zone* goes unknown, so "rejoin once at the end" is what
     // the first frame after the shot already does — there is nothing to re-arm. It matters because
@@ -593,9 +591,9 @@ pub(super) fn auto_join_zone_channels(
     //
     // Fed zone-less, every zone-dependent row carries `resolved: None`, which is the reference's
     // own "matched a row but there is no zone text yet" leg: `AddChatWindowChannel` stores nothing
-    // and answers nil, `JoinChannelByName` returns nil and sends nothing (chat-cache-grammar.md §5,
-    // decision 1908). Right answer instead of a wrong one, and the walk re-feeds the moment a zone
-    // lands.
+    // and answers nil (`0x4a10d9`), `JoinChannelByName` returns nil and sends nothing
+    // (`0x49ece5`, decision 1908). Right answer instead of a wrong one, and the walk re-feeds the
+    // moment a zone lands.
     let mut script = script;
     if !channels.channels.is_empty() {
         if let Some(script) = script.as_mut() {
@@ -667,11 +665,11 @@ pub(crate) fn seed_zone_channel_catalog(
     script.set_zone_channel_catalog(zone_channel_catalog(&channels.channels, "", false, city));
 }
 
-/// Every `ChatChannels.dbc` row as the VM needs it (decision 1908; wow-re chat-cache-grammar.md
-/// §5-6): the id, the Shortcut the verbs compare a typed name against, the name composed for
-/// `zone_name` — `None` when the composition has nothing to substitute (a zone-dependent row with
-/// no zone, a city row with no city word), which is the verbs' nil leg — and whether
-/// `EnumerateServerChannels` lists it here (a city-only row, `flags & 0x10`, only in a city).
+/// Every `ChatChannels.dbc` row as the VM needs it (decision 1908): the id, the Shortcut the verbs
+/// compare a typed name against (`0x4a10b2`), the name composed for `zone_name` — `None` when the
+/// composition has nothing to substitute (a zone-dependent row with no zone, a city row with no
+/// city word), which is the verbs' nil leg — and whether `EnumerateServerChannels 0x4a1790` lists
+/// it here (a city-only row, `flags & 0x10`, only in a city).
 pub(crate) fn zone_channel_catalog(
     catalog: &ChatChannelsCatalog,
     zone_name: &str,
@@ -723,7 +721,7 @@ mod tests {
     /// sentinel — see [`city_word`]).
     const CITY: Option<&str> = Some("City");
 
-    /// A fresh character's mask: the DBC's three `INITIAL` rows, `0x200003` (§3).
+    /// A fresh character's mask: the DBC's three `INITIAL` rows, `0x200003` (seeded at `0x4997fc`).
     const SEED: u32 = 0x0020_0003;
     /// `1 << (25 - 1)` — `GuildRecruitment`'s bit, which the cascade's confirmed join adds.
     const GUILD_RECRUITMENT_BIT: u32 = 1 << 24;
@@ -948,7 +946,7 @@ mod tests {
     }
 
     /// **A border crossing is LEAVE(old) → rename → JOIN(new), per slot, interleaved, in slot
-    /// order** — pass 1 over the slot array (§7; the retail 1.8.1 Winterspring sniff is the
+    /// order** — pass 1 over the slot array (`0x49a284`; the retail 1.8.1 Winterspring sniff is the
     /// control). The suspended Trade slot in the middle is walked too and does nothing: its
     /// name never moves and it is not eligible here.
     #[test]
@@ -1236,9 +1234,9 @@ mod tests {
         );
     }
 
-    /// The numeric leg of leave-by-name ([`ChannelState::leave_target`], contract §3): a non-zero
-    /// leading integer names a **confirmed** slot or makes the call a no-op; anything else is
-    /// already the wire name, composed by the VM or passed through.
+    /// The numeric leg of leave-by-name ([`ChannelState::leave_target`], `0x49ee70` step 1): a
+    /// non-zero leading integer names a **confirmed** slot or makes the call a no-op; anything else
+    /// is already the wire name, composed by the VM or passed through.
     #[test]
     fn leave_target_resolves_a_number_to_a_confirmed_slot_or_to_nothing() {
         let mut c = state(SEED);
@@ -1278,7 +1276,7 @@ mod tests {
         );
         assert_eq!(c.leave_target("mychan").as_deref(), Some("mychan"));
 
-        // …and the mask clear needs a slot carrying the wire name (contract §8).
+        // …and the mask clear needs a slot carrying the wire name (`0x49f0f4`).
         c.note_zone_channel_left("General - Nowhere");
         assert_eq!(c.zone_mask, Some(SEED), "no slot carries it: no clear");
         c.note_zone_channel_left("General - Elwynn Forest");
@@ -1309,7 +1307,7 @@ mod tests {
     /// `JoinChannelByName` returns `(0, nil)` — the custom leg — and **sends
     /// `CMSG_JOIN_CHANNEL("General")`**. Fed zone-less instead, every zone-dependent row is present
     /// but carries `resolved: None`, which is the reference's own "matched a row, no zone text yet"
-    /// leg: store nothing, answer nil, send nothing (chat-cache-grammar.md §5).
+    /// leg: store nothing, answer nil, send nothing (`0x4a10d9`, `0x49ece5`).
     ///
     /// That gap is what wrote `CHANNELS / General / LocalDefense` into the director's `Onewarrior`
     /// window block with the zone bits stripped, and it was open on every login until the world
diff --git a/crates/benilla-app/src/ui_chat/combat.rs b/crates/benilla-app/src/ui_chat/combat.rs
index 3342719a..a86a5e2d 100644
--- a/crates/benilla-app/src/ui_chat/combat.rs
+++ b/crates/benilla-app/src/ui_chat/combat.rs
@@ -4,8 +4,8 @@
 //! the floating numbers, the portrait indicator and the center text, and produced **no chat at
 //! all**, which is why a damage meter or Quiver's TranqAnnouncer sees nothing to parse.
 //!
-//! This module is the reference's `UnitCombatLog_C` TU (`~0x625000-0x62e7xx`, wow-re
-//! `object-layer/scratch/w2f2.md`), the presentation half: it owns **no** arithmetic, only the
+//! This module is the reference's `UnitCombatLog_C` TU (`~0x625000-0x62e7xx`), the presentation
+//! half: it owns **no** arithmetic, only the
 //! composition — classify both endpoints, pick a chat type, pick a GlobalString *key*, fill it.
 //! The reference's own chain is four hops and we take the same four:
 //!
@@ -123,14 +123,14 @@ pub(crate) fn in_range(
 /// `0x8629e0` plus the one range CVar that sits outside it, `CombatDeathLogRange`.
 ///
 /// The reference registers all eight in one place (`0x626d00`, a loop over `0x8629e0` skipping the
-/// NULL/empty names, then one unrolled call — wow-re `combat-log-chat-law.md` §5.2), stores **no
+/// NULL/empty names, then one unrolled call), stores **no
 /// handle for any of them**, and looks each up by name at every use. We keep the resolved numbers
 /// instead: the lookup-by-name is the reference's way of not caching, not a behaviour, and
 /// `crate::cvars` already owns the string table.
 ///
 /// **Yards, and read as the CVar's FLOAT field.** The record carries both `+0x24` float and `+0x28`
-/// int, written from the same string at registration; the range gate reads the float and the
-/// periodic gates read the int (§5.1). `0` is a real value and means *silence this class* —
+/// int, written from the same string at registration; the range gate reads the float (`0x626810`)
+/// and the periodic gates read the int. `0` is a real value and means *silence this class* —
 /// `dist² < 0` is never true — which is why nothing here clamps to a floor.
 #[derive(Resource, Clone, Copy)]
 pub(crate) struct CombatLogRanges {
@@ -232,8 +232,8 @@ pub(crate) fn on_cvar(
 /// packet's periodic byte is set).
 ///
 /// Read as the CVar record's **int** `+0x28`, unlike [`CombatLogRanges`] which reads the float —
-/// both fields are written from the same string at registration (wow-re
-/// `object-layer/scratch/combat-log-chat-law.md` §5.1/§5.4).
+/// both fields are written from the same string at registration (`0x63e127` the int, `0x63e135`
+/// the float).
 ///
 /// A **missing record counts as OFF** in the reference, because the gate is
 /// `cvar == NULL || cvar->int == 0`. That cannot happen here — the row is registered at startup —
@@ -251,22 +251,6 @@ impl Default for LogPeriodicSpells {
 /// `CombatLogPeriodicSpells`' registered name.
 pub(crate) const LOG_PERIODIC_CVAR: &str = "CombatLogPeriodicSpells";
 
-/// **The combat-feedback CVars, as one system parameter** — what a packet handler needs to know
-/// about the player's settings before it emits a line or a floating number.
-///
-/// Bundled because they are one concern — the reference reads all three inside the same
-/// combat-log/world-text translation unit — and read by the net drain as the combat-feedback
-/// member of its catalogs (`net::apply::params::Catalogs`).
-#[derive(bevy::ecs::system::SystemParam)]
-pub(crate) struct CombatFeedbackCvars<'w> {
-    /// The eight display ranges.
-    pub ranges: Res<'w, CombatLogRanges>,
-    /// `CombatLogPeriodicSpells`.
-    pub periodic: Res<'w, LogPeriodicSpells>,
-    /// `CombatDamage` + the two `Pet*` sub-gates.
-    pub damage_text: Res<'w, crate::combat_text::DamageTextGates>,
-}
-
 /// `CombatDeathLogRange`'s registered name and default — `0x626d5f`, default string `"60"`
 /// (`0x862e14`).
 pub(crate) const DEATH_LOG_RANGE_CVAR: &str = "CombatDeathLogRange";
@@ -375,9 +359,8 @@ impl UnitClass {
 
 /// Classify one guid against the active player — the reference's `0x5efea0(ecx = GUID*)`.
 ///
-/// **The rule is now VERIFIED**, not inferred: the wow-re §5 this arc dispatched settled it
-/// (`system/object-layer/scratch/combat-log-chat-law.md` §2), and it corrected 1571's first cut on
-/// three points, each of which changed behaviour:
+/// **The rule is settled at the bytes**, not inferred, and settling it corrected 1571's first cut
+/// on three points, each of which changed behaviour:
 ///
 /// - **The owner field is `UNIT_FIELD_CHARMEDBY`, then `UNIT_FIELD_CREATEDBY`.** We read
 ///   `SUMMONEDBY` first, copying the floating text's source classifier — a different field, and a
@@ -415,8 +398,8 @@ pub(crate) fn classify(
     let Some(store) = stores.store(entity) else {
         return UnitClass::Unknown;
     };
-    // The owner: CHARMEDBY first, then CREATEDBY (§2). A pet/guardian/totem/charmed unit is
-    // classified by WHOSE it is, one rung above its own faction.
+    // The owner: CHARMEDBY first, then CREATEDBY (`0x5f000c`/`0x5f0019`). A
+    // pet/guardian/totem/charmed unit is classified by WHOSE it is, one rung above its own faction.
     let owner = store
         .0
         .unit_charmed_by()
@@ -445,8 +428,9 @@ pub(crate) fn classify(
         return UnitClass::PartyPet;
     }
 
-    // Friend or foe — `CanAttack`, judged on **this unit**, never on its owner (§2). The owner
-    // hop was ours and it was wrong: the reference asks the pet itself.
+    // Friend or foe — `CanAttack`, judged on **this unit**, never on its owner
+    // (`0x5f00e3`/`0x5f00f2`). The owner hop was ours and it was wrong: the reference asks the pet
+    // itself.
     let hostile = {
         let me_store = index.0.get(&me).copied().and_then(|e| stores.store(e));
         crate::target::ring::can_attack_from_player(
@@ -483,11 +467,11 @@ pub(crate) fn classify(
 /// reference returns `0x5e` (94, one past the end of the 94-entry type table = "no type", checked
 /// at the emit `0x626850`).
 ///
-/// Read off the decompiled selectors and cross-checked against wow-re's byte-verified 94-entry
-/// default colour table (`system/ui/scratch/chat-color-table.md`, whose index column is the 1-based
-/// `GetChatTypeIndex` value — so the `0x1b` the selector returns is that table's row 28,
-/// `COMBAT_SELF_HITS`). `miss` picks the odd twin: every HITS type is immediately followed by its
-/// MISSES type, which is why the reference's two selectors differ only by `+1`.
+/// Read off the decompiled selectors and cross-checked against the reference's 94-entry default
+/// colour table (`0x804710`, whose rows `GetChatTypeIndex` numbers from 1 — so the `0x1b` the
+/// selector returns is that table's row 28, `COMBAT_SELF_HITS`). `miss` picks the odd twin: every
+/// HITS type is immediately followed by its MISSES type, which is why the reference's two selectors
+/// differ only by `+1`.
 ///
 /// **The two reclassifying arms are real and they are the duel/PvP case.** A *party* player (2) or
 /// a *friendly* player (4) whose victim is you, your pet, or a party member is reported in the
@@ -586,8 +570,8 @@ pub(crate) fn periodic_kind(subject: UnitClass, buff: bool) -> Option<ChatEventK
 
 /// `0x628980` — the death pair's selector, and it takes the **victim's** class alone.
 ///
-/// The comparison is SIGNED (`jl` then `cmp ecx,5; jle`), which is why the note spells the negative
-/// arm out: `0 <= c <= 5` is FRIENDLY_DEATH, everything else — a hostile player, their pet, any
+/// The comparison is SIGNED (`jl` then `cmp ecx,5; jle`), which is why the negative arm is spelled
+/// out: `0 <= c <= 5` is FRIENDLY_DEATH, everything else — a hostile player, their pet, any
 /// creature, an unresolvable unit — is HOSTILE_DEATH. Our `UnitClass` cannot be negative, so the
 /// sign only matters as a statement of what the arm is.
 pub(crate) fn death_kind(victim: UnitClass) -> ChatEventKind {
@@ -602,8 +586,8 @@ pub(crate) fn death_kind(victim: UnitClass) -> ChatEventKind {
 /// ten: `{0,1}` SELF · `{2,3}` PARTY · everything else OTHER.
 ///
 /// The arrival is not this selector's — an aura landing rides the two PERIODIC selectors instead
-/// (harmful → [`periodic_kind`]'s damage row, helpful → its buff row), which is the asymmetry §4.4
-/// records and not a simplification of ours.
+/// (harmful → [`periodic_kind`]'s damage row, helpful → its buff row), which is the reference's own
+/// asymmetry (`0x62b480`) and not a simplification of ours.
 pub(crate) fn aura_gone_kind(bearer: UnitClass) -> ChatEventKind {
     use ChatEventKind as K;
     use UnitClass as C;
@@ -618,7 +602,7 @@ pub(crate) fn aura_gone_kind(bearer: UnitClass) -> ChatEventKind {
 ///
 /// It has **two** users, which is the surprising half: the shield formatter itself, and *every*
 /// `SMSG_SPELLLOGMISS` line (`0x5e7f31 push 1` routes `0x62bab0` here instead of the eight-row
-/// spell matrix — §4.4, a byte fact wow-re states without claiming to know whether it is deliberate).
+/// spell matrix — a byte fact; whether it is deliberate is not derivable from the binary).
 pub(crate) fn damage_shield_kind(subject: UnitClass) -> ChatEventKind {
     if matches!(subject, UnitClass::Me | UnitClass::MyPet) {
         ChatEventKind::SpellDamageShieldsOnSelf
@@ -668,9 +652,9 @@ fn buff_twin(damage: ChatEventKind) -> ChatEventKind {
 // ──────────────────────────── the format-string selectors ─────────────────────────────
 
 /// Which of a family's four templates applies — the reference's 45 `char*(self, other, *out)`
-/// selectors (wow-re `w2f2.md` §G7), whose two arguments are booleans ("the subject is not me",
-/// "the object is not me") and whose `*out` variant code `0..3` is what tells the caller how many
-/// names to push.
+/// selectors (`0x629f90`, `0x62a290`, …), whose two arguments are booleans ("the subject is not
+/// me", "the object is not me") and whose `*out` variant code `0..3` is what tells the caller how
+/// many names to push.
 ///
 /// `SelfSelf` is the code-`0` case for most families: the selector returns NULL and **no line is
 /// produced**. Some families do define the key (`SPELLLOGSELFSELF`, `HEALEDSELFSELF`,
@@ -840,7 +824,7 @@ impl Family {
 /// locale that ships one blank simply loses that clause.
 ///
 /// Only four call sites can grow one, and what each can show differs because it passes zeroes for
-/// the fields it has no wire source for (§4.2): melee `COMBATHIT*` is the only family that can ever
+/// the fields it has no wire source for: melee `COMBATHIT*` is the only family that can ever
 /// show GLANCING/CRUSHING/BLOCK; `SPELLLOG*` can show RESIST/VULNERABLE/BLOCK/ABSORB;
 /// `PERIODICAURADAMAGE*` and `VSENVIRONMENTALDAMAGE_*` RESIST/VULNERABLE/ABSORB.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
@@ -1023,7 +1007,7 @@ pub(crate) fn global_string(script: &benilla_ui::script::UiScript, key: &str) ->
 ///
 /// The reference does not read a GlobalString here at all: `0x6264b0(schoolIndex)` indexes
 /// `Resistances.dbc` (row array `[0xc0d9a4]`, 7 rows of 0x30 bytes, localized name at
-/// `row + 0xc + locale*4`) — wow-re `combat-log-chat-law.md` §4.5 — and those seven rows are
+/// `row + 0xc + locale*4`) — and those seven rows are
 /// `Physical · Holy · Fire · Nature · Frost · Shadow · Arcane`. `SPELL_SCHOOL<n>_NAME` is a
 /// *different* table in GlobalStrings.lua and holds the same seven words **lowercased**
 /// (`GlobalStrings.lua:4102-4114`), which is what this used to return: "12 nature damage" where
@@ -1057,7 +1041,7 @@ pub(crate) fn school_word(script: &benilla_ui::script::UiScript, school: u8) ->
 ///
 /// What happiness really lacks is a **`COMBAT_TEXT_UPDATE`** tag: `0x627520`/`0x627930`'s four
 /// `0x64a4c0` compares match only the other four nouns, so it produces the chat line and no
-/// floating text (§4.6). That is a different table, further down, after the emit.
+/// floating text. That is a different table, further down, after the emit.
 fn power_key(power: u32) -> Option<&'static str> {
     match power {
         0 => Some("MANA_POINTS"),
@@ -1088,13 +1072,22 @@ pub(crate) fn power_word(script: &benilla_ui::script::UiScript, power: u32) -> O
 /// same ask-once name cache every other client-composed chat line waits on. `None` = not yet
 /// answered; the caller re-tries next frame, exactly as the reference's deferred-name queue
 /// (`DAT_00c4e208`, drained by the name-ready callback `0x6294b0`) replays its message.
-pub(crate) fn object_name(guid: u64, names: &NameCache, commands: &NetCommands) -> Option<String> {
+///
+/// `unit` is the endpoint's descriptor when it is streamed: `0x6264e0` looks the guid up in the
+/// object manager first and, for a unit, calls `GetUnitName` (`0x609210`) — which keys a pet's or a
+/// companion's name off its descriptor, not its guid ([`NameCache::resolve_unit`]).
+pub(crate) fn object_name(
+    guid: u64,
+    unit: Option<&ObjectStore>,
+    names: &NameCache,
+    commands: &NetCommands,
+) -> Option<String> {
     // Guid 0 = "the name is already in the fills" — no wire endpoint is ever guid 0, so the
     // sentinel costs nothing and is what lets `/chattest` drive the real drain with literal names.
     if guid == 0 {
         return None;
     }
-    names.resolve(guid, commands).map(str::to_owned)
+    names.resolve_unit(guid, unit, commands).map(str::to_owned)
 }
 
 // ────────────────────────────────── the families ──────────────────────────────────────
@@ -1441,8 +1434,8 @@ duo!(
     "OTHER",
     [Spell, Attacker],
     "`\"%s fades from you.\"` (:113) / `\"%s fades from %s.\"` (:112) — AURA first, which is the \
-     other way round from `AURAADDED*`. The flip is the reference's own (§4.4) and is exactly the \
-     kind of thing a single ordered slot list per family exists to pin."
+     other way round from `AURAADDED*`. The flip is the reference's own (`0x62b480`) and is \
+     exactly the kind of thing a single ordered slot list per family exists to pin."
 );
 duo!(
     AURADISPEL,
@@ -1821,7 +1814,7 @@ pub(crate) fn miss_family(miss_info: u8) -> Family {
 /// **The last arm can decline.** `0x62a710` is gated twice before it words anything: the 10-entry
 /// flag table `0x8628f8` = `[0,0,1,1,0,1,1,1,1,0]` indexed by VictimState (`0x62a720`), then
 /// `add eax,-2; cmp eax,6; ja` into the jump table `0x62a8ec` — so VictimState **0, 1, 4 and 9
-/// emit no line at all** (§4.1 row 6). This used to answer `MISSED` for them and call that "the
+/// emit no line at all**. This used to answer `MISSED` for them and call that "the
 /// reference's own fall-through", which it is not: the reference stays silent, and a `MISSED`
 /// there is a sentence the real client never prints.
 ///
@@ -1912,8 +1905,8 @@ pub(crate) struct PendingCombat {
 ///
 /// The reference has both hops and keeps them apart for the same reason: an item name comes from
 /// the **item cache** (`0x55ba30`), whose miss parks the whole formatter on the deferred queue and
-/// re-runs it when the server answers (§5.7); a unit name comes from `GetObjectName` (`0x6264e0`),
-/// the same resolve the two endpoint slots already use.
+/// re-runs it when the server answers (`0x6294b0`); a unit name comes from `GetObjectName`
+/// (`0x6264e0`), the same resolve the two endpoint slots already use.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum Named {
     /// Nothing to do — the arm already put the text in [`Fills::named`], or the family has no
@@ -1940,7 +1933,7 @@ pub(crate) fn queue(
 ) -> Option<PendingCombat> {
     // **A class-9 endpoint alone does NOT drop the line**, and 1571 had this wrong. Its range of
     // `0.0` means it can never satisfy *its own half* of the gate — but the gate is an OR over the
-    // two endpoints (§4/§5.2), so a resolvable one at the other end still carries the line. What
+    // two endpoints (`0x626630`), so a resolvable one at the other end still carries the line. What
     // drops here is only the case the reference's own resolve step fails on: neither endpoint
     // resolvable at all.
     if subject.1 == UnitClass::Unknown && object.1 == UnitClass::Unknown {
diff --git a/crates/benilla-app/src/ui_chat/combat/tests.rs b/crates/benilla-app/src/ui_chat/combat/tests.rs
index 11218721..26a08ee9 100644
--- a/crates/benilla-app/src/ui_chat/combat/tests.rs
+++ b/crates/benilla-app/src/ui_chat/combat/tests.rs
@@ -325,8 +325,8 @@ fn the_silent_victim_states_emit_no_melee_line() {
     assert_eq!(melee_family(0, 5, 0, 0).map(|f| f.stem), Some("VSBLOCK"));
 }
 
-/// The melee msgType matrix, against `0x62a0d0`/`0x62a2e0` as decompiled and against wow-re's
-/// byte-verified 94-entry type table (whose 1-based index is one more than the selector's return).
+/// The melee msgType matrix, against `0x62a0d0`/`0x62a2e0` as decompiled and against the 94-entry
+/// type table `.rdata 0x804710` (whose 1-based index is one more than the selector's return).
 #[test]
 fn the_melee_matrix_is_the_reference_selector() {
     use ChatEventKind as K;
diff --git a/crates/benilla-app/src/ui_chat/combat/watch.rs b/crates/benilla-app/src/ui_chat/combat/watch.rs
index 6ae5fa85..ac4e6a38 100644
--- a/crates/benilla-app/src/ui_chat/combat/watch.rs
+++ b/crates/benilla-app/src/ui_chat/combat/watch.rs
@@ -1,5 +1,5 @@
-//! The combat-log lines that are **not packet-driven at all** — the two families §3 of wow-re's
-//! `combat-log-chat-law.md` singles out, plus the pet-loyalty leaf.
+//! The combat-log lines that are **not packet-driven at all** — the reference's two families of
+//! them, death and aura, plus the pet-loyalty leaf.
 //!
 //! Everything else in [`super`] hangs off an SMSG arm. These three hang off *descriptor changes*,
 //! exactly as the reference does:
@@ -27,7 +27,7 @@ use crate::ui_chat::{ChatEventKind, ChatLog};
 use crate::ui_party::GroupState;
 
 /// The classification inputs all three watchers share — the same six facts
-/// [`crate::net::apply::combat_chat::ChatCtx`] carries, as a `SystemParam` so a watcher's own
+/// [`crate::combat_log::chat::ChatCtx`] carries, as a `SystemParam` so a watcher's own
 /// parameter list stays about *its* diff.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct WatchCtx<'w> {
@@ -54,7 +54,7 @@ impl WatchCtx<'_> {
         )
     }
 
-    /// [`crate::net::apply::combat_chat::ChatCtx::spell_name`]'s law, shared: the per-spell gates
+    /// [`crate::combat_log::chat::ChatCtx::spell_name`]'s law, shared: the per-spell gates
     /// (`Attributes & 0x180`, an empty localized name) apply to every spell-driven line, and an
     /// aura line is one.
     fn spell_name(&self, spell_id: u32) -> Option<String> {
@@ -69,7 +69,7 @@ impl WatchCtx<'_> {
     }
 
     /// The reference's ONE-SIDED range test — the shape 15 formatters run instead of the two-ended
-    /// gate (§5.2), the death and aura lines among them. One participant, one distance.
+    /// gate `0x626630`, the death and aura lines among them. One participant, one distance.
     ///
     /// **`range` is the caller's**, because the death line does not use the class table: its
     /// formatter `0x62c160` reads `CombatDeathLogRange` first (`0x62c19c`) and only falls back to
@@ -123,8 +123,8 @@ const DESTROYED_EFFECTS: [u32; 10] = [50, 74, 87, 88, 89, 90, 104, 105, 106, 107
 ///
 /// **The XP-award suppression is deliberately not modelled**, and is named rather than dropped:
 /// `[CGUnit+0xc58] bit 3`, set only in the `SMSG_LOG_XPGAIN` chain, makes the death reflex emit the
-/// award line *instead of* the plain death line (§5.9). wow-re found no clearing site for the bit,
-/// so whether it survives a second death is UNSETTLED there — and modelling an unsettled latch is
+/// award line *instead of* the plain death line (`0x62c23e`). No clearing site for the bit is
+/// known, so whether it survives a second death is UNSETTLED — and modelling an unsettled latch is
 /// how you get a line that silently stops appearing. The visible consequence today is one extra
 /// "%s dies." beside the XP line on a kill that awards experience.
 pub(crate) fn death_lines(
@@ -190,9 +190,9 @@ pub(crate) fn death_lines(
 ///   fresh slot's count is not a rise (its `AURA` dword moved in the same block, so its byte is
 ///   skipped here).
 ///
-/// **HARMFUL is the SLOT INDEX, not a flag** (§4.4, three byte sites): slots `0x20`–`0x2f` are
-/// harmful, every other slot helpful. `UNIT_FIELD_AURAFLAGS` is only an occupancy predicate — using
-/// it here would be the wrong mechanism that happens to agree most of the time.
+/// **HARMFUL is the SLOT INDEX, not a flag** (three byte sites, e.g. `0x61238e`): slots
+/// `0x20`–`0x2f` are harmful, every other slot helpful. `UNIT_FIELD_AURAFLAGS` is only an occupancy
+/// predicate — using it here would be the wrong mechanism that happens to agree most of the time.
 pub(crate) fn aura_lines(
     ctx: WatchCtx,
     stores: Query<(Entity, &ObjectStore)>,
@@ -201,7 +201,7 @@ pub(crate) fn aura_lines(
     mut log: ResMut<ChatLog>,
 ) {
     use benilla_protocol::field::{FIELD_UNIT_AURA, FIELD_UNIT_AURAAPPLICATIONS};
-    /// The first harmful aura slot — `0x20`. Slots below it are helpful (§4.4).
+    /// The first harmful aura slot — `0x20`. Slots below it are helpful (`0x61238e`).
     const FIRST_HARMFUL_SLOT: u16 = 0x20;
     const SLOTS: u16 = benilla_protocol::messages::UNIT_AURA_SLOTS as u16;
     let harmful = |slot: u16| slot >= FIRST_HARMFUL_SLOT;
diff --git a/crates/benilla-app/src/ui_chat/edit.rs b/crates/benilla-app/src/ui_chat/edit.rs
index d0cd0d4a..0e1ddd80 100644
--- a/crates/benilla-app/src/ui_chat/edit.rs
+++ b/crates/benilla-app/src/ui_chat/edit.rs
@@ -14,8 +14,6 @@ use crate::net::ChatKind;
 /// The sendable chat types — `ChatTypeInfo`'s sendable keys, as the wire kind an addon's
 /// `SendChatMessage` token maps to. `Whisper`/`Channel` carry their target in the call.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
-#[allow(dead_code)] // RaidLeader/BgLeader have no slash of their own (server-promoted sends);
-                    // Channel is the P6 wiring's target — the enum is the full sendable law.
 pub(crate) enum SendType {
     Say,
     Yell,
@@ -103,7 +101,7 @@ impl SendType {
 
 /// How many channels the client can hold at once — its allocator refuses the eleventh
 /// (`0x49b9c0: cmp ecx,0xa`), and the ten boot-seeded `CHANNEL1`…`CHANNEL10` color rows are the
-/// same ten (wow-re `chat-color-table.md`).
+/// same ten (seeded by `0x4982c0`).
 pub(crate) const MAX_CHANNELS: usize = 10;
 
 /// The channels this session has joined — the CLIENT-side number law (`GetChannelName(n)`): `/1`
@@ -144,8 +142,7 @@ pub(crate) struct ChannelState {
     /// "no zone channels, arg7 always 0" rather than to an error.
     pub channels: benilla_formats::ChatChannelsCatalog,
     /// **The `ZONECHANNELS` mask** — the reference's `DWORD ds:0xb6e5e0`, bit `1 << (ChannelID-1)`
-    /// (decision 2120; wow-re `system/ui/scratch/zone-chat-channel-autojoin.md` §3 carries the
-    /// complete 8-site census of that global).
+    /// (decision 2120; the global's complete census is eight sites).
     ///
     /// **It is durable state, not a view of [`Self::joined`].** The reference seeds it once — from
     /// the chat cache's header line (`0x498d83`, an overwrite) or, with no usable file, from every
@@ -178,6 +175,24 @@ pub(crate) struct ChannelState {
     /// drift from it; the saver refuses to compose a file from `None` for the same reason
     /// (writing `ZONECHANNELS 0` is the damage 2120 repaired).
     pub zone_mask: Option<u32>,
+    /// **The custom channels the character is in** — the chat cache header's `CHANNELS` list, the
+    /// names the next login re-joins. Durable state, for exactly [`Self::zone_mask`]'s reason: the
+    /// reference writes that list from its live slot array (`0x499b90`-`0x499bb1`: every slot
+    /// with a number, state 0 and no DBC id) at the chat teardown, when its slots are still
+    /// there — ours are cleared by the session end *before* the flush (the
+    /// `Disconnected{LoggedOut}` twin runs in `Update`, a frame ahead of `OnExit(InWorld)`), so a
+    /// list read off [`Self::joined`] at write time was empty on every logout and no custom
+    /// channel was ever re-joined (2184 §6).
+    ///
+    /// So it moves where the slot array's custom half moves, minus the session end: seated from
+    /// the file by `restore_chat_looks` (an overwrite, like the mask), grown on a
+    /// server-confirmed join of a channel with no DBC id ([`Self::note_custom_channel_joined`]),
+    /// shrunk on an explicit leave ([`Self::note_custom_channel_left`]), and nothing else.
+    ///
+    /// **Named divergence:** a channel whose re-join the server refuses (a ban, a changed
+    /// password) or that the player is kicked from never takes a confirmed slot in the reference
+    /// and so drops out of its file; here it stays listed until the player `/leave`s it.
+    pub custom: Vec<String>,
 }
 
 /// One joined-channel record — the reference's `[0xb4fe04] + n*0xa0` slot, in the fields this
@@ -195,7 +210,7 @@ pub(crate) struct ChannelSlot {
 /// differs — because the token is what the stock `ChatFrame_OnEvent` branches on, and one of those
 /// branches deletes the window's channel registration.
 ///
-/// The complete writer census is wow-re `zone-chat-channel-autojoin.md` §6.
+/// Its complete writer census is six sites.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub(crate) enum SlotState {
     /// `0` (server-confirmed) and `1` (join not yet acknowledged), which we cannot tell apart and
@@ -210,13 +225,13 @@ pub(crate) enum SlotState {
     /// *"Changed Channel: [%s]"*, a line the reference has and we never printed.
     Renamed,
     /// `3` — **locally suspended**: the row lost its eligibility, which in the 1.12 data means
-    /// exactly one thing, walking out of a capital with `Trade` joined (§5/§6). `0x49bcf0` sets it
+    /// exactly one thing, walking out of a capital with `Trade` joined. `0x49bcf0` sets it
     /// and sends nothing; the LEAVE has already gone out earlier in the same iteration.
     ///
     /// The record and its number survive, and the arriving `YOU_LEFT` carries the `SUSPENDED`
     /// token instead (`0x49c0e0`) — same rendered text, different arg1, which is exactly what stops
     /// `ChatFrame_OnEvent` from deleting the registration. Walking back into a city then re-joins
-    /// through the state-3 bypass (§7 pass 1 step 2), where the name has not changed and the
+    /// through the state-3 bypass (`0x49a31c`), where the name has not changed and the
     /// comparison would otherwise say there was nothing to do.
     Suspended,
 }
@@ -265,7 +280,7 @@ impl ChannelState {
     /// `0x49ee70`, and only there. The zone walk's LEAVE goes out on a different path and leaves
     /// the mask alone: crossing a border is not "I left this channel".
     ///
-    /// Keyed the way the reference keys it (wow-re `leavechannelbyname-contract.md` §8): the slot
+    /// Keyed the way the reference keys it (`0x49f0f4`): the slot
     /// found by the **wire name**, and its own DBC id — so a name no slot carries clears nothing,
     /// whatever row it would resolve to.
     pub(crate) fn note_zone_channel_left(&mut self, name: &str) {
@@ -277,15 +292,33 @@ impl ChannelState {
         }
     }
 
+    /// A server-confirmed join of a **custom** channel (no `ChatChannels.dbc` id) enters the
+    /// durable re-join list ([`Self::custom`]) — the slot the reference's writer would list at
+    /// teardown. A zone channel is a no-op here; it travels as its mask bit instead.
+    pub(crate) fn note_custom_channel_joined(&mut self, name: &str) {
+        if self.channels.zone_channel_id(name) != 0
+            || self.custom.iter().any(|c| c.eq_ignore_ascii_case(name))
+        {
+            return;
+        }
+        self.custom.push(name.to_string());
+    }
+
+    /// An **explicit** leave drops a custom channel from the re-join list — the one thing
+    /// besides the file that shrinks it ([`Self::custom`]). Case-insensitive, as the server's
+    /// channel names are.
+    pub(crate) fn note_custom_channel_left(&mut self, name: &str) {
+        self.custom.retain(|c| !c.eq_ignore_ascii_case(name));
+    }
+
     /// Does the mask carry `id`'s bit — is this `ChatChannels.dbc` row one the walk joins? The
     /// reference's live predicate `0x49a494` (decision 2144). `None` (not seated) answers false.
     pub(crate) fn zone_row_wanted(&self, id: u32) -> bool {
         self.zone_mask.is_some_and(|mask| mask & zone_bit(id) != 0)
     }
 
-    /// **The numeric leg of leave-by-name** — `0x49ee70` step 1 (wow-re
-    /// `leavechannelbyname-contract.md` §3, VERIFIED): a `SStrToInt` of the argument that is not
-    /// zero names joined slot `n`, and only a **server-confirmed** one (`slot+0x9c == 0`,
+    /// **The numeric leg of leave-by-name** — `0x49ee70` step 1: a `SStrToInt` of the argument that
+    /// is not zero names joined slot `n`, and only a **server-confirmed** one (`slot+0x9c == 0`,
     /// `0x49be50`); a hole, an out-of-range number or a suspended slot make the whole call a
     /// no-op — no packet, no mask change. `None` is that no-op. Anything else is already the wire
     /// name: the VM's `LeaveChannelByName` composed a shortcut or passed a custom name through.
@@ -317,10 +350,10 @@ impl ChannelState {
 
     /// **Rename a slot in place — the zone walk crossing a border** (decision 2130).
     ///
-    /// The reference's `0x49bc50(oldName, newName)`, called from `ZoneChannelRefresh`'s pass 1
-    /// step 6 (wow-re `zone-chat-channel-autojoin.md` §7, VERIFIED): it copies the new name into
-    /// the slot and moves its state to "re-join pending" — **at send time**, before the server has
-    /// answered the `CMSG_LEAVE_CHANNEL` that went out a moment earlier.
+    /// The reference's `0x49bc50(oldName, newName)`, called from `ZoneChannelRefresh`'s pass 1 at
+    /// `0x49a3dc`: it copies the new name into the slot and moves its state to "re-join pending" —
+    /// **at send time**, before the server has answered the `CMSG_LEAVE_CHANNEL` that went out a
+    /// moment earlier.
     ///
     /// That ordering is the whole point, and it is not bookkeeping. When the server's `YOU_LEFT`
     /// for the *old* name arrives, no slot carries that name any more — `0x49be90` is a pure name
@@ -337,8 +370,8 @@ impl ChannelState {
     ///
     /// Nothing in stock FrameXML ever re-adds one on a join, and **nothing in the engine does
     /// either**: a closed census of event 395 (`0x18b`) leaves five fire sites in the image, none of
-    /// them reachable from a zone change, for guilded and unguilded players alike (wow-re §11.1,
-    /// VERIFIED). The rename is not one repopulation mechanism among several — it is the only thing
+    /// them reachable from a zone change, for guilded and unguilded players alike (`0x49a6a4`).
+    /// The rename is not one repopulation mechanism among several — it is the only thing
     /// standing between a border crossing and a dead channel.
     ///
     /// So without it, one crossing costs the window General and LocalDefense **for the rest of the
@@ -468,14 +501,14 @@ impl ChannelState {
     /// client's local channel record — `slot+0x00`, `+0x04`, `+0x94`, `+0x98` — so a name that is
     /// *not* in the local list has no record to read and every one of them is empty: arg4 falls
     /// back to the bare incoming name and arg7/arg8/arg9/arg10 are `0/0/""/0` together. They are
-    /// never independently populated. (wow-re `system/ui/scratch/chat-msg-event-args.md` §§4, 7-10,
-    /// VERIFIED; the `"%d. %s"` prefix at `0x8445c8` is applied on the hit leg `0x49aa48`, and
-    /// `0x49aa86` is the bare-name miss leg.)
+    /// never independently populated. (`0x49b12f` installs the empty defaults together; the
+    /// `"%d. %s"` prefix at `0x8445c8` is applied on the hit leg `0x49aa48`, and `0x49aa86` is the
+    /// bare-name miss leg.)
     ///
     /// So: on entry `event.channel` holds the name as the wire gave it ("General - Elwynn Forest").
     /// If we are in that channel, on exit arg4 is the numbered display form, arg9 the stored name
-    /// **with its " - Zone" tail intact** (§9: the DBC name column *is* the format string the
-    /// client built the stored name with), arg8 the 1-based local slot and arg7 the
+    /// **with its " - Zone" tail intact** (`0x49a4ea`: the DBC name column *is* the format string
+    /// the client built the stored name with), arg8 the 1-based local slot and arg7 the
     /// `ChatChannels.dbc` ChannelID — 0 for a custom channel. If we are not, nothing is stamped.
     ///
     /// arg7 is resolved from the name against `ChatChannels.dbc` rather than remembered per join.
diff --git a/crates/benilla-app/src/ui_chat/event.rs b/crates/benilla-app/src/ui_chat/event.rs
index 4fc36bc0..3fb0cd96 100644
--- a/crates/benilla-app/src/ui_chat/event.rs
+++ b/crates/benilla-app/src/ui_chat/event.rs
@@ -9,7 +9,7 @@
 //! `SPELL_*` block is the combat-log content arc, deliberately out — 0288 §3, except
 //! `COMBAT_XP_GAIN`, pulled in by the ding arc 0304: the XP line is part of leveling feedback);
 //! the group tables are `ChatTypeGroup` transcribed; the colors are the complete shipped default
-//! table (the ref client's own `chat-cache.txt` COLORS block ≡ wow-re's byte-verified
+//! table (the ref client's own `chat-cache.txt` COLORS block ≡ the
 //! `.rdata 0x804710` table, double-sourced in 0288's pin).
 //!
 //! This module also carries the **Lua face** of that currency: [`event_name`]
@@ -333,8 +333,7 @@ impl ChatEventKind {
 /// **The arg list is TEN wide, and its shape is byte-pinned.** The client's per-type fire helper
 /// `0x49b0b0` (reached from the chat chokepoint `0x49a870` at `0x49ac9a`) calls
 /// `FrameScript_SignalEvent 0x703f50` with the format string `"%s%s%s%s%s%s%d%d%s%d"`
-/// (`.rdata 0x844608`) — wow-re `system/ui/scratch/rested-xp-bindings.md` §9, VERIFIED there in
-/// the course of the rest-state RE. So **arg1..arg6 are strings, arg7 and arg8 are numbers, arg9
+/// (`.rdata 0x844608`). So **arg1..arg6 are strings, arg7 and arg8 are numbers, arg9
 /// is a string, arg10 is a number**, and not one of them is ever `nil`: `ChatFrame_OnEvent`
 /// compares `arg7 > 0` and `arg10 > 0` bare, which under Lua 5.0 errors on a nil. Every slot is
 /// always passed — zero or empty when unused.
@@ -386,11 +385,10 @@ impl ChatEventKind {
 ///
 /// **Corrections on record.** This comment previously listed args 1-6, 8 and 9 only — arg7 and
 /// arg10 were absent, and arg7 is a real slot the reference's own channel routing turns on. The
-/// omission was ours. The whole map is now byte-verified end to end in wow-re
-/// `system/ui/scratch/chat-msg-event-args.md` (T2), which also **refutes** 0288's standing lead
-/// that rf77 had traced this marshaller: rf77's trace was opcode `0x92` = SMSG_GUILD_EVENT,
-/// misfiled. Real `SMSG_MESSAGECHAT` is `0x96` → `0x49d560` and matches vmangos branch for branch,
-/// which is what benilla's decode already did.
+/// omission was ours. The whole map is now read end to end off `0x49b0b0`, which also **refutes**
+/// 0288's standing lead that an earlier trace had covered this marshaller: that trace was opcode
+/// `0x92` = SMSG_GUILD_EVENT, misfiled. Real `SMSG_MESSAGECHAT` is `0x96` → `0x49d560` and matches
+/// vmangos branch for branch, which is what benilla's decode already did.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct ChatEvent {
     pub kind: Option<ChatEventKind>,
@@ -574,9 +572,8 @@ pub(crate) fn event_name(kind: ChatEventKind) -> &'static str {
 /// are asserted against each other rather than left to drift
 /// (`ui_chat::tests::every_rendered_notice_has_a_token`).
 ///
-/// Byte-for-byte identical to the client's own jump table (`0x49c60c`, 32 direct arms), verified
-/// arm by arm in wow-re `chat-msg-event-args.md` §9 — checked against that table after the fact,
-/// not derived from it.
+/// Byte-for-byte identical to the client's own jump table (`0x49c60c`, 32 direct arms) — checked
+/// against that table after the fact, not derived from it.
 ///
 /// `None` = a byte the reference passes no token for: `0x00`/`0x01` are the CHANNEL_JOIN /
 /// CHANNEL_LEAVE member lines (their arg1 is the empty string, not a token), `0x0C` MODE_CHANGE
@@ -586,8 +583,7 @@ pub(crate) fn event_name(kind: ChatEventKind) -> &'static str {
 ///
 /// **Two of the arms are state-dependent** (decision 2130): the client answers `"YOU_CHANGED"` for
 /// `0x02` and `"SUSPENDED"` for `0x03` when its own channel record is in the matching state
-/// (`rec+0x9c == 2` at `0x49c087` / `== 3` at `0x49c0e0`; wow-re
-/// `zone-chat-channel-autojoin.md` §11.3, VERIFIED), and both alternates are real
+/// (`rec+0x9c == 2` at `0x49c087` / `== 3` at `0x49c0e0`), and both alternates are real
 /// `CHAT_<X>_NOTICE` strings —
 /// *"Changed Channel: [%s]"* and *"Left Channel: [%s]"*. We modelled neither until the zone walk's
 /// registration loss made it matter: `arg1` is what the stock `ChatFrame_OnEvent` branches on, and
@@ -645,7 +641,7 @@ pub(crate) fn notice_token(
 /// The kind's row in the shipped colour table — what the chat bubble and the edit box's header
 /// tint with. The window's own line colour is `ChatTypeInfo`'s, in the reference's Lua (1948).
 ///
-/// The complete shipped table (chat-cache COLORS ≡ wow-re `chat-color-table.md`, both quoted in
+/// The complete shipped table (chat-cache COLORS ≡ `.rdata 0x804710`, both quoted in
 /// 0288's pin; entries this kind set carries).
 pub(crate) fn default_color(kind: ChatEventKind) -> [u8; 3] {
     use ChatEventKind as K;
diff --git a/crates/benilla-app/src/ui_chat/feed.rs b/crates/benilla-app/src/ui_chat/feed.rs
index af366b4d..d712e68d 100644
--- a/crates/benilla-app/src/ui_chat/feed.rs
+++ b/crates/benilla-app/src/ui_chat/feed.rs
@@ -65,9 +65,9 @@ enum Pending {
         tries: u16,
     },
     /// An inbound addon line awaiting its SENDER's name — `CHAT_MSG_ADDON` (event 227, fired at
-    /// `0x49a95f`). Parked here rather than fired at decode for the reason wow-re records: the
-    /// reference fires it *downstream* of the name resolve, from the `CMSG_NAME_QUERY` callback
-    /// (`0x49ccc0`), so `sender` is a NAME and never a guid.
+    /// `0x49a95f`). Parked here rather than fired at decode because the reference fires it
+    /// *downstream* of the name resolve, from the `CMSG_NAME_QUERY` callback (`0x49ccc0`), so
+    /// `sender` is a NAME and never a guid.
     Addon {
         prefix: String,
         message: String,
@@ -139,7 +139,7 @@ enum Pending {
 ///
 /// Split out of the drain so the shape that reaches Lua is testable without standing up
 /// `feed_chat`'s dozen resources — the scaffolding is not what can be wrong here; the argument
-/// ORDER is. wow-re carves it as `SignalEvent2(227, "%s%s%s%s", prefix, message, distribution,
+/// ORDER is. The reference fires `SignalEvent2(227, "%s%s%s%s", prefix, message, distribution,
 /// sender)` (`0x49a95f`), and `BigWigs` independently self-delivers
 /// `self:CHAT_MSG_ADDON("BigWigs", msg, "RAID", playerName)` — a 2006 addon author and the binary
 /// agreeing.
@@ -487,7 +487,7 @@ fn keyed(
 /// reference does not keep in GlobalStrings: 1.12 ships no `EXHAUSTION_STATE*` key, so it comes
 /// out of the client's own table and stays a literal here, with the same INTERIM it always had.
 /// "Rested" is the only state the live server produces (the beta tired/exhausted penalties are
-/// dead data); the client's table is the in-flight 0304 §5's to pin.
+/// dead data); the client's table is the in-flight 0304's to pin.
 pub(super) fn xp_gain_line(
     victim: Option<&str>,
     total: u32,
@@ -526,10 +526,9 @@ const RESTED_STATE: &str = "Rested";
 /// The honor line an `SMSG_PVP_CREDIT` becomes — the three GlobalStrings forms (COMBATLOG_HONORAWARD
 /// :786, COMBATLOG_HONORGAIN :787, COMBATLOG_DISHONORGAIN :785), decision 1512.
 ///
-/// **The fork is byte-VERIFIED** (wow-re `system/ui/scratch/honor-panel-law.md`, formatter
-/// `0x625270`), and it is three-way, not two: no victim guid → AWARD; victim and `honor > 0` →
-/// GAIN; victim and **`honor <= 0`** → DISHONOR. The boundary is `<=`, not `<` — a zero-honor kill
-/// takes the dishonorable arm, which the pre-verdict reading had on the honorable side.
+/// **The fork** (formatter `0x625270`) is three-way, not two: no victim guid → AWARD; victim and
+/// `honor > 0` → GAIN; victim and **`honor <= 0`** → DISHONOR. The boundary is `<=`, not `<` — a
+/// zero-honor kill takes the dishonorable arm, which the earlier reading had on the honorable side.
 ///
 /// An absent `rank_title` fills an EMPTY rank slot rather than dropping the clause. That is the
 /// reference's own shape — it is precisely the emptiness vmangos floors a rankless victim's rank at
@@ -596,7 +595,7 @@ pub(super) fn notice_event(
     a: Option<String>,
     b: Option<String>,
 ) -> Option<ChatEvent> {
-    // The display type per notice byte — wow-re `chat-msg-event-args.md`'s notice table, read
+    // The display type per notice byte — the `0x49c60c` jump table, read
     // off each arm's `mov edi`: 0x00/0x01 are the join/leave lines, MODE_CHANGE (0x0c) fires no
     // chat event at all, a byte past THROTTLED fires SYSTEM with an empty token, and the rest
     // split between CHANNEL_NOTICE (0x12) and CHANNEL_NOTICE_USER (0x13) exactly as listed.
@@ -704,6 +703,9 @@ pub(super) fn deliver(
         // (decision 2120). Outside the slot claim below because it is not about slots — a
         // re-confirmation of a channel we already number still owns the bit.
         channels.note_zone_channel_joined(&event.channel);
+        // …and a custom channel's confirmed join is what enters the durable re-join list the
+        // chat cache writes (`ChannelState::custom`), the same "server agreed" edge.
+        channels.note_custom_channel_joined(&event.channel);
         // …and the slot the walk RENAMED is already numbered, so the claim below skips it — but
         // its state still has to come back to `Joined`, or the next notice on that row reads as
         // another rename. A no-op for a channel we hold no slot for, which is the claim's case.
@@ -895,7 +897,7 @@ pub(super) fn feed_chat(
                     None
                 };
                 let plain = expanded.unwrap_or_else(|| msg.text.clone());
-                // **The language gate** (B262, wow-re `chat-language-scramble.md`). The wire always
+                // **The language gate** (B262). The wire always
                 // carries plaintext; whether this character can read it is entirely ours to decide,
                 // and the answer is one rewritten buffer that EVERY consumer below shares — the
                 // chat line, the Lua `arg1`, the bubble, the gesture. That is the reference's own
@@ -924,8 +926,8 @@ pub(super) fn feed_chat(
                     // NOT built, and named rather than faked: the whisper leg. A dropped
                     // `CHAT_MSG_WHISPER` with a non-zero report guid also sends `CMSG_CHAT_FILTERED`
                     // (`0x331`) before returning — still firing no event, so the player sees the
-                    // same nothing either way. The packet's BODY is not settled (wow-re parked
-                    // `0x508680`'s send-path verdict as a DEFERRED), vmangos has no handler for the
+                    // same nothing either way. The packet's BODY is not settled (`0x508680`'s
+                    // send-path verdict is still open), vmangos has no handler for the
                     // opcode, and inventing a body to send a server that ignores it would be worse
                     // than the honest gap.
                     debug!(
@@ -973,8 +975,7 @@ pub(super) fn feed_chat(
                 // expanded text, and takes its laugh words off the player's own FrameXML globals —
                 // the enumeration is the mechanism, the words are content (decision 1469).
                 //
-                // **It reads `plain`, NOT the garbled text, and that is byte-verified rather than
-                // reasoned** (wow-re `chat-language-scramble.md` §10.1). The selector is not on
+                // **It reads `plain`, NOT the garbled text.** The selector is not on
                 // this display path at all: it lives in the *parser* `0x49d560` at
                 // `0x49d820`-`0x49d8ae`, and the slot it matches against — `[ebp-0x10]` — is the
                 // very buffer `0x49dbc2` then hands to `0x49a870` as its `src`. The garbled buffer
@@ -982,7 +983,7 @@ pub(super) fn feed_chat(
                 //
                 // So the gesture is **language-independent**: a Horde player yelling `lol` laughs
                 // for every observer, Alliance included. We had this wired to the garbled text on
-                // an inference from §10's consumer census — that census was complete for
+                // an inference from the consumer census — that census was complete for
                 // `0x49a870` and could never have found a consumer reading the pre-garble value in
                 // the *caller's* frame.
                 if let Some(gesture) =
@@ -1163,9 +1164,9 @@ pub(super) fn feed_chat(
                 // **The side is the VICTIM's and the gender is OURS**, and that asymmetry is the
                 // reference's own (`0x625270`): the team digit is computed inline over the victim's
                 // faction template, while the gendered GlobalString resolve runs against the local
-                // player. It reads like a bug in the real client and it is what the bytes do; both
-                // halves are wow-re-VERIFIED. The victim's side rides the same name-query record we
-                // just resolved the name from; ours rides our own.
+                // player. It reads like a bug in the real client and it is what the bytes do. The
+                // victim's side rides the same name-query record we just resolved the name from;
+                // ours rides our own.
                 //
                 // A victim with no record is a creature — a racial leader is the only one the
                 // server ranks, at 19, and "Leader" is the same word on both sides — or an
@@ -1257,7 +1258,12 @@ pub(super) fn feed_chat(
                     if guid == 0 {
                         continue;
                     }
-                    match super::combat::object_name(guid, &names, &commands) {
+                    match super::combat::object_name(
+                        guid,
+                        guids.0.get(&guid).and_then(|e| stores.get(*e).ok()),
+                        &names,
+                        &commands,
+                    ) {
                         Some(name) if slot == 0 => line.fills.attacker = name,
                         Some(name) => line.fills.victim = name,
                         None => wait = true,
@@ -1278,7 +1284,12 @@ pub(super) fn feed_chat(
                         }
                     }
                     super::combat::Named::Unit(guid) => {
-                        match super::combat::object_name(guid, &names, &commands) {
+                        match super::combat::object_name(
+                            guid,
+                            guids.0.get(&guid).and_then(|e| stores.get(*e).ok()),
+                            &names,
+                            &commands,
+                        ) {
                             Some(name) => line.fills.named = name,
                             None => wait = true,
                         }
@@ -1365,7 +1376,7 @@ fn needs_name(chat_type: u8) -> bool {
 /// the net apply pass fills, and it is delivered as the event rather than a return value, because
 /// that is how the API answers — `RequestTimePlayed()` itself returns nothing.
 ///
-/// **This does NOT replace the chat breakdown beside it.** `net::apply::chat::played_time` prints
+/// **This does NOT replace the chat breakdown beside it.** `ui_chat::net::played_time` prints
 /// the TIME_PLAYED_TOTAL/LEVEL lines because we do not ship `ChatFrame_DisplayTimePlayed`, which is
 /// what the reference's own `TIME_PLAYED_MSG` handler does. The two are the reference's two
 /// consumers of one packet, not a doubling: an addon that registers the event does its own thing
diff --git a/crates/benilla-app/src/ui_chat/frames.rs b/crates/benilla-app/src/ui_chat/frames.rs
index 861310c4..8dc37dc2 100644
--- a/crates/benilla-app/src/ui_chat/frames.rs
+++ b/crates/benilla-app/src/ui_chat/frames.rs
@@ -156,9 +156,8 @@ pub(crate) fn compose(
             // the code was not, which cost every Horde character a `[Orcish]` tag on ordinary
             // faction chat and stripped the tag from Common. The reference's test is
             // `arg3 ~= this.defaultLanguage` and `GetDefaultLanguage()` answers the **faction**
-            // tongue, so it reads Orcish for a Horde body (wow-re
-            // `system/ui/scratch/chat-language-scramble.md` §10/§12: the tag is FrameXML's and its
-            // condition is about the *default* language, never about whether the language is
+            // tongue, so it reads Orcish for a Horde body (`0x5ec890`; the tag is FrameXML's and
+            // its condition is about the *default* language, never about whether the language is
             // understood — a character who knows both Common and Dwarvish still sees `[Dwarvish]`
             // on a line they read perfectly).
             //
diff --git a/crates/benilla-app/src/ui_chat/idle.rs b/crates/benilla-app/src/ui_chat/idle.rs
index 09c6c221..8429b8d7 100644
--- a/crates/benilla-app/src/ui_chat/idle.rs
+++ b/crates/benilla-app/src/ui_chat/idle.rs
@@ -1,7 +1,6 @@
 //! **The idle handler** — `WorldFrame::Render 0x482ea0`, the one reference function that watches
 //! how long it has been since the player last touched anything and does three unrelated-looking
-//! things about it (wow-re `object-layer/scratch/standstate-movement-trigger.md` §5.4 and
-//! `ui/scratch/afk-dnd-command-law.md` §10/§12).
+//! things about it.
 //!
 //! One module because it is **one timer**, read once per frame against one global stamp, with a
 //! three-way branch hung off it:
@@ -16,7 +15,7 @@
 //! `0x482ede add eax,0xffe488c0` is `-1 800 000`.
 //!
 //! **The 30-minute leg is a CAMP, not a kick.** `0x5ab000` is `ClientServices::SendLogout(flag,
-//! force)` (wow-re `system/net/ledger.tsv`) — the *same* function the game menu's Logout button
+//! force)` — the *same* function the game menu's Logout button
 //! reaches through `Logout 0x489390`, sending `CMSG_LOGOUT_REQUEST 0x4B`. So the server decides:
 //! it refuses outright in combat, logs you out instantly in an inn, and otherwise runs the
 //! twenty-second countdown that [`crate::ui_logout`] already narrates as the CAMP dialog. A
@@ -86,14 +85,12 @@ const AUTO_AFK_AFTER: Duration = Duration::from_millis(300_000);
 ///
 /// **Absolute, not five-plus-thirty.** The subtraction above it writes `ecx`, so `eax` still holds
 /// the raw elapsed when this one runs. Reading the pair as two chained deductions gives 35 minutes
-/// and is the natural misreading of the two-instruction sequence; the §5 round caught itself
-/// making it.
+/// and is the natural misreading of the two-instruction sequence.
 const AUTO_LOGOUT_AFTER: Duration = Duration::from_millis(1_800_000);
 
 /// Stamp the clock — the **seven** writers of `[0xcf0bc8]`, all registered on the one input ring
 /// at priority `1.0f` (`0x765c04`–`0x765cfe` via `0x41fca0`), all storing the same ring field
-/// `payload[3]` (wow-re `ui/scratch/idle-timer-input-stamp-law.md`, a §5 with four independent
-/// reproductions and a closed image-wide census of the dword: 37 occurrences, 7 W / 30 R).
+/// `payload[3]` (a closed image-wide census of the dword: 37 occurrences, 7 W / 30 R).
 ///
 /// | writer | bus category | what the player did |
 /// |---|---|---|
@@ -111,9 +108,9 @@ const AUTO_LOGOUT_AFTER: Duration = Duration::from_millis(1_800_000);
 /// - **Auto-repeat.** `0x424810` promotes category 8 to 0xa at `0x4248b3` when the key is already
 ///   held, and `0x766070` (category 0xa) has no store. So **holding a key is idle** — running with
 ///   W held, or on autorun, reaches the five-minute auto-AFK. This is the single most surprising
-///   thing the round found and it is deliberate here, not an omission.
+///   thing the reference does and it is deliberate here, not an omission.
 /// - Zero-motion moves and the pump's synthetic hover re-pick (`0x7660d0`'s `0x766122`–`0x766140`
-///   filter), which is the bypass `hover-hide-and-tooltip-owner-law.md` recorded without pinning.
+///   filter, and its `0x766120` bypass).
 /// - Double-clicks, `WM_MOUSEHWHEEL`, `WM_CHAR`, the joystick, and any VK outside `0x42d800`'s
 ///   table.
 /// - Mouse **movement and left-button-up during an OS window drag** — a title-bar drag or border
@@ -123,8 +120,7 @@ const AUTO_LOGOUT_AFTER: Duration = Duration::from_millis(1_800_000);
 /// **Mouselook is NOT an exclusion** — it is `[0x884e5c]`, a different global entirely, and all it
 /// picks is which arm enqueues (absolute → category 0xc, delta → category 0xd, both stamping). A
 /// player turning the camera with the right button held is *not* idle. This module briefly recorded
-/// the opposite, off a mislabelled global, before the second round pinned `[0x884e64]`'s writers to
-/// `SetCapture`.
+/// the opposite, off a mislabelled global; `[0x884e64]`'s writers are `SetCapture`'s.
 ///
 /// **The store sits on the raw input bus, ahead of dispatch**, so a keystroke a frame *consumes*
 /// still stamps: typing into the chat edit box is input, and so is a click that only moves a
@@ -288,7 +284,7 @@ pub(crate) fn idle_handler(
     let strings = |key: &str| crate::ui_chat::combat::global_string(&script, key);
     if action.afk {
         // `SetAFK(NULL)` is `/afk` with an empty message and the mirror clear — the one row of the
-        // §12 truth table this can reach, which is why it goes through the same function rather
+        // `/afk` truth table this can reach, which is why it goes through the same function rather
         // than composing its own line: same `MARKED_AFK_MESSAGE % DEFAULT_AFK_MESSAGE` echo, the
         // same client-side default substitution reaching the wire, the same optimistic mirror.
         let out = afk_line("", *mirror, &strings);
@@ -606,7 +602,7 @@ mod tests {
         // **The one that is not an omission.** `0x424810` promotes a held key from bus category 8
         // to 0xa, and `0x766070` — category 0xa's handler — has no store. So running with W held,
         // or sitting on autorun, walks straight into the five-minute auto-AFK. It is the single
-        // most surprising thing the §5 found, four workers agreed on it, and a re-implementation
+        // most surprising thing the reference does, and a re-implementation
         // that "fixed" it would diverge from the reference in a way a player would notice.
         assert_eq!(
             stamped(&|app| {
diff --git a/crates/benilla-app/src/ui_chat/input/mod.rs b/crates/benilla-app/src/ui_chat/input/mod.rs
index 2348cddd..cf32c966 100644
--- a/crates/benilla-app/src/ui_chat/input/mod.rs
+++ b/crates/benilla-app/src/ui_chat/input/mod.rs
@@ -110,8 +110,7 @@ pub(super) struct ChatProbes<'w, 's> {
 ///
 /// - `stand`/`sheath` — the two setters `DoEmote` drives besides the packet: the **posture**
 ///   (`EmoteSpecProc == 1` → `SetStandState`) and the **stow** (`SetSheatheState(0, SNAP)`,
-///   unconditional on every emote that passes the gates — wow-re `sheath-policy.md` §1, site
-///   `0x5ef630`).
+///   unconditional on every emote that passes the gates — site `0x5ef630`).
 /// - `target`/`assist` — the by-name selection asks (decision 0886), answered by
 ///   [`crate::target`]'s shared resolver so they commit through the same SetSelection path a click
 ///   does. Chat never writes [`Selection`] itself.
@@ -182,9 +181,9 @@ fn engine_verbs(
 /// **A manual join or leave of `GuildRecruitment` turns the auto-join option off** — the
 /// reference's `0x49ed3d` (join) and `0x49ef8f` (leave), each `call 0x49ea70(0)` gated on the
 /// matched `ChatChannels.dbc` row carrying `flags & 0x20000` and on the caller's own flag, which
-/// the Lua bindings pass and the cascade's internal calls do not (wow-re
-/// `guild-recruitment-mode.md` §3; decision 2144). The player has taken manual control, and an
-/// option left checked would silently re-join or re-leave behind them.
+/// the Lua bindings pass and the cascade's internal calls do not (decision 2144). The player has
+/// taken manual control, and an option left checked would silently re-join or re-leave behind
+/// them.
 fn manual_join_or_leave(
     channels: &super::edit::ChannelState,
     script: &mut benilla_ui::script::UiScript,
@@ -776,9 +775,8 @@ pub(super) fn drain_chat_input(
                     }
                 }
             }
-            // `DoEmote` (`0x5ef560`) end to end — wow-re `object-layer/scratch/emote-posture-
-            // gate.md` §1. The gates in the client's own order, then the two things it DOES: set a
-            // posture (the `/sit` family) and send the packet.
+            // `DoEmote` (`0x5ef560`) end to end. The gates in the client's own order, then the two
+            // things it DOES: set a posture (the `/sit` family) and send the packet.
             ParsedChat::TextEmote(text_id) => {
                 let (stand_state, flags) = self_player
                     .single()
@@ -989,12 +987,13 @@ pub(super) fn drain_chat_input(
                         // `LeaveChannelByName` (`0x4a0000` → `0x49ee70`): the VM composed a
                         // shortcut or passed a custom name; a number names a confirmed slot here
                         // or the call is a no-op. The mask clear is this path's and no other's
-                        // (decisions 2120, 2144).
+                        // (decisions 2120, 2144), and so is the custom re-join list's.
                         let Some(name) = channels.leave_target(&name) else {
                             continue;
                         };
                         manual_join_or_leave(&channels, &mut script, &name);
                         channels.note_zone_channel_left(&name);
+                        channels.note_custom_channel_left(&name);
                         ClientCommand::LeaveChannel { name }
                     }
                     C::List { name } => ClientCommand::ChannelList { name },
@@ -1447,13 +1446,12 @@ fn combat_log_battery(log: &mut super::feed::ChatLog, get: &dyn Fn(&str) -> Opti
     }
 }
 
-/// The send-side emote **posture-eligibility gate** (wow-re `object-layer/scratch/emote-posture-
-/// gate.md`, commit `f9584b45`, §0): the real client's `CheckEmoteEligible` (`0x47db40`), the *only*
-/// site that reads an `Emotes.dbc` `EmoteFlags` — called from `DoEmote` (`0x5ef560`) *before*
-/// `CMSG_TEXT_EMOTE` is built, so a suppressed emote sends no packet and plays no local anim at all
-/// (a seated `/bow` self-censors; the server round-trip never happens). Byte-verified predicate,
-/// exactly these four tests in the note's site order. `true` = eligible (send + play); `false` =
-/// suppress both.
+/// The send-side emote **posture-eligibility gate**: the real client's `CheckEmoteEligible`
+/// (`0x47db40`), the *only* site that reads an `Emotes.dbc` `EmoteFlags` — called from `DoEmote`
+/// (`0x5ef560`) *before* `CMSG_TEXT_EMOTE` is built, so a suppressed emote sends no packet and
+/// plays no local anim at all (a seated `/bow` self-censors; the server round-trip never happens).
+/// The predicate is exactly these four tests, in the client's own order. `true` = eligible (send +
+/// play); `false` = suppress both.
 ///
 /// # The fifth flag, `0x4000` — NOT built, and the reason recorded here was WRONG
 ///
@@ -1474,9 +1472,8 @@ pub(super) enum EmoteGate {
 }
 
 /// This doc used to say `0x4000` ("requires standing still") *"only sets an out param the client
-/// acts on while fear/confuse-controlled, which benilla doesn't model"*. A §5 trio carve of the
-/// neighbouring stand-state gate re-read the leg and **inverted that polarity**
-/// (wow-re `standstate-movement-trigger.md` §5.6, 2026-08-23; decision 1582). The bytes:
+/// acts on while fear/confuse-controlled, which benilla doesn't model"*. The polarity is the
+/// **inverse** (2026-08-23; decision 1582). The bytes:
 ///
 /// - `0x47dbab` tests `EmoteFlags & 0x4000`, and if set, `0x47dbb3` tests the live `CMovement`
 ///   word against **`0x20ff`** — the four direction bits, the two turn bits, the two pitch bits and
@@ -1534,11 +1531,10 @@ pub(super) fn emote_send_eligible(
 
 /// `PLAYER_FLAGS_DND` (`0x4`) off our own live descriptor — the DND arm's state test.
 ///
-/// **Live, not mirrored, and that asymmetry is the reference's** (wow-re
-/// `afk-dnd-command-law.md` §8): the AFK path keeps an optimistic global and the DND path keeps
-/// nothing, so a second `/dnd` typed before the server's `PLAYER_FLAGS` update lands still reads
-/// DND clear and re-marks, where a second `/afk` in the same window clears. Do not "fix" this into
-/// a symmetric pair.
+/// **Live, not mirrored, and that asymmetry is the reference's** (`0x49f3f0`): the AFK path keeps
+/// an optimistic global and the DND path keeps nothing, so a second `/dnd` typed before the
+/// server's `PLAYER_FLAGS` update lands still reads DND clear and re-marks, where a second `/afk`
+/// in the same window clears. Do not "fix" this into a symmetric pair.
 fn is_dnd(self_q: &Query<&crate::net::ObjectStore, With<crate::net::SelfPlayer>>) -> bool {
     self_q
         .iter()
@@ -1606,7 +1602,7 @@ pub(super) fn drain_addon_chat_sends(
         // `SendChatMessage 0x49f1e0` is not a uniform dispatcher: AFK and DND each carry their own
         // arm ahead of the generic send, and EVERY other type first clears a standing AFK. The
         // whole law — the four `CHAT_MSG_SYSTEM` lines, the client-side default substitution, the
-        // optimistic mirror — is `super::away`, off wow-re's `afk-dnd-command-law.md` §12 table.
+        // optimistic mirror — is `super::away`, off the reference's truth table.
         let strings = |key: &str| crate::ui_chat::combat::global_string(&script, key);
         let wire = kind.wire();
         let text = match wire {
@@ -1621,8 +1617,8 @@ pub(super) fn drain_addon_chat_sends(
                 out.body
             }
             crate::net::ChatKind::Dnd => {
-                // The live descriptor bit, not a mirror: DND has none (§8), which is what makes a
-                // repeated `/dnd` re-mark where a repeated `/afk` clears.
+                // The live descriptor bit, not a mirror: DND has none (`0x49f3f0`), which is what
+                // makes a repeated `/dnd` re-mark where a repeated `/afk` clears.
                 let out = super::away::dnd_line(&send.text, is_dnd(&self_q), &strings);
                 if let Some(line) = out.line {
                     super::away::push_system(&mut chat_log, line);
@@ -1673,8 +1669,8 @@ pub(super) fn drain_addon_chat_sends(
 /// **The lane is traced in both directions, under one tag.** An addon channel is invisible by
 /// construction — it never reaches a chat frame, which is the entire point of `LANG_ADDON` — so
 /// without a line here a broadcast that went out and one that never happened look identical from
-/// our own logs, which is exactly how a silently-discarded wire body survives (method.md's rule
-/// that new wire bodies are proved, not assumed). `net::apply::chat` already writes inbound addon
+/// our own logs, which is exactly how a silently-discarded wire body survives (docs/METHOD.md's rule
+/// that new wire bodies are proved, not assumed). `ui_chat::net` already writes inbound addon
 /// traffic to the `addon` trace tag; this writes the outbound half to the same tag, so
 /// `WOW_MOVE_TRACE=<path> WOW_MOVE_TRACE_TAGS=addon` on a live run is the whole conversation in
 /// one file, in order.
diff --git a/crates/benilla-app/src/ui_chat/input/parse.rs b/crates/benilla-app/src/ui_chat/input/parse.rs
index 96a66ea3..bd1c22fe 100644
--- a/crates/benilla-app/src/ui_chat/input/parse.rs
+++ b/crates/benilla-app/src/ui_chat/input/parse.rs
@@ -237,7 +237,7 @@ pub(in crate::ui_chat) fn parse_line(table: &SlashCommands, line: &str) -> Parse
 /// 0x700010` routes `=` to its default arm as ordinary content, the `[` arm at `0x6ff771` makes
 /// exactly one comparison (`cmp eax,0x5b`), and a `[=` therefore leaves the lexer holding the
 /// single-character token `[`, which `prefixexp 0x6fde40` refuses with ``unexpected symbol near
-/// `['`` (wow-5875-re `lua-dialect.md` §9.2, verified and executed).
+/// `['`` (measured on the reference client's own Lua loader).
 ///
 /// 2101 removed the three 5.1 grammar additions the corpus probes and left the levelled long
 /// bracket standing, on a measurement of **zero occurrences** across FrameXML, GlueXML,
diff --git a/crates/benilla-app/src/ui_chat/language.rs b/crates/benilla-app/src/ui_chat/language.rs
index fa90bf71..82621c0e 100644
--- a/crates/benilla-app/src/ui_chat/language.rs
+++ b/crates/benilla-app/src/ui_chat/language.rs
@@ -3,7 +3,7 @@
 //! module is `0x49a870`'s share of the work: the exemptions, and the "how well does this character
 //! know that language" answer the routine takes as its second argument.
 //!
-//! Byte-verified in wow-re `system/ui/scratch/chat-language-scramble.md` §8. The chain is entirely
+//! That answer is `0x5ec720`'s. The chain is entirely
 //! client-side over server-synced skill data — **nothing is pushed as a "language list"**:
 //!
 //! ```text
diff --git a/crates/benilla-app/src/net/apply/chat.rs b/crates/benilla-app/src/ui_chat/net.rs
similarity index 77%
rename from crates/benilla-app/src/net/apply/chat.rs
rename to crates/benilla-app/src/ui_chat/net.rs
index 9c9d20db..888866e0 100644
--- a/crates/benilla-app/src/net/apply/chat.rs
+++ b/crates/benilla-app/src/ui_chat/net.rs
@@ -1,23 +1,137 @@
-//! Chat-window arm bodies for [`super::apply_net_updates`]'s dispatch match — the spoken line
-//! itself, plus the server notices and query answers that render as chat lines (the channel
-//! roster, whisper refusals, `/played`). Each `pub(super)` fn here is exactly one arm's body; the
-//! match at the call site stays the dispatcher, one call per arm.
+//! The chat window's packet handlers (in the net handler table since 2323, moved out of the
+//! drain's chat arm file) — the spoken line itself, plus the server notices and query answers
+//! that render as chat lines (the channel roster, whisper refusals, `/played`).
 //!
-//! Two arms here do NOT render as chat: `SMSG_NOTIFICATION` and `SMSG_AREA_TRIGGER_MESSAGE` are
-//! the reference's UIErrorsFrame toasts, and queue onto [`UiErrorTexts`]. They live in this file
-//! because they are text-carrying server notices, not because they share a sink.
+//! Two handlers here do NOT render as chat: `SMSG_NOTIFICATION` and `SMSG_AREA_TRIGGER_MESSAGE`
+//! are the reference's UIErrorsFrame toasts, and queue onto [`UiErrorTexts`]. They live in this
+//! file because they are text-carrying server notices, not because they share a sink.
 
 use benilla_protocol::messages::{ChatMessage, CHAT_MSG_WHISPER};
+use benilla_protocol::{SessionEvent, SessionEventKind};
 use bevy::prelude::*;
 
-use crate::ui_action::UiErrorTexts;
-use crate::ui_chat::{Broadcast, ChatEvent, ChatEventKind, ChatLog};
+use super::{Broadcast, ChatEvent, ChatEventKind, ChatLog};
+use crate::net::{ClientCommand, NetCommands, NetHandlerApp, PlayedTimeAnswer, ServerSaidMessage};
+use crate::ui_action::{UiErrorKeys, UiErrorTexts};
 use crate::ui_social::SocialState;
 
-use super::super::{ClientCommand, NetCommands, ServerSaidMessage};
+/// Register the chat window's handlers — called from [`super::UiChatPlugin`]. One per kind
+/// (the four world broadcasts share one), plus the session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::Chat, on_chat)
+        .net_handler(K::ChannelList, on_channel_list)
+        .net_handler(K::ChatPlayerNotFound, on_whisper_refusal)
+        .net_handler(K::ChatWrongFaction, on_whisper_refusal)
+        .net_handler(K::ZoneUnderAttack, on_broadcast)
+        .net_handler(K::DefenseMessage, on_broadcast)
+        .net_handler(K::ServerMessage, on_broadcast)
+        .net_handler(K::ChatRestricted, on_broadcast)
+        .net_handler(K::Notification, on_toast)
+        .net_handler(K::AreaTriggerMessage, on_toast)
+        .net_handler(K::PlayedTime, on_played_time)
+        .net_handler(K::ChannelNotify, on_channel_notify)
+        .net_handler(K::RandomRoll, on_random_roll)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_chat(
+    In(ev): In<SessionEvent>,
+    mut chat_log: ResMut<ChatLog>,
+    social: Res<SocialState>,
+    commands: Res<NetCommands>,
+    mut server_said: MessageWriter<ServerSaidMessage>,
+) {
+    if let SessionEvent::Chat(m) = ev {
+        chat(m, &mut chat_log, &social, &commands, &mut server_said);
+    }
+}
+
+fn on_channel_list(In(ev): In<SessionEvent>, mut chat_log: ResMut<ChatLog>) {
+    if let SessionEvent::ChannelList {
+        channel, members, ..
+    } = ev
+    {
+        channel_list(channel, &members, &mut chat_log);
+    }
+}
+
+fn on_whisper_refusal(In(ev): In<SessionEvent>, mut errors: ResMut<UiErrorKeys>) {
+    match ev {
+        SessionEvent::ChatPlayerNotFound { name } => chat_player_not_found(&name, &mut errors),
+        SessionEvent::ChatWrongFaction => chat_wrong_faction(&mut errors),
+        _ => {}
+    }
+}
+
+/// The four world broadcasts — parked for [`super::broadcast`]'s resolve pass, which owns the
+/// AreaTable/ServerMessages lookups and the joined-defense-channel walk.
+fn on_broadcast(In(ev): In<SessionEvent>, mut chat_log: ResMut<ChatLog>) {
+    let b = match ev {
+        SessionEvent::ZoneUnderAttack { area_id } => Broadcast::ZoneUnderAttack { area_id },
+        SessionEvent::DefenseMessage { zone_id, text } => Broadcast::Defense { zone_id, text },
+        SessionEvent::ServerMessage { message_type, text } => {
+            Broadcast::Server { message_type, text }
+        }
+        SessionEvent::ChatRestricted => Broadcast::ChatRestricted,
+        _ => return,
+    };
+    broadcast(b, &mut chat_log);
+}
+
+fn on_toast(In(ev): In<SessionEvent>, mut errors: ResMut<UiErrorTexts>) {
+    match ev {
+        SessionEvent::Notification { text } => notification(text, &mut errors),
+        SessionEvent::AreaTriggerMessage { text } => area_trigger_message(text, &mut errors),
+        _ => {}
+    }
+}
+
+/// BOTH halves, and they are not redundant. The chat breakdown is our stand-in for the
+/// reference's `ChatFrame_DisplayTimePlayed`, which we do not ship; the mailbox is what becomes
+/// `TIME_PLAYED_MSG(total, level)` for an addon that asked.
+fn on_played_time(
+    In(ev): In<SessionEvent>,
+    mut answer: ResMut<PlayedTimeAnswer>,
+    mut chat_log: ResMut<ChatLog>,
+) {
+    if let SessionEvent::PlayedTime { total, level } = ev {
+        answer.0 = Some((total, level));
+        played_time(total, level, &mut chat_log);
+    }
+}
+
+fn on_channel_notify(In(ev): In<SessionEvent>, mut chat_log: ResMut<ChatLog>) {
+    if let SessionEvent::ChannelNotify {
+        notice,
+        channel,
+        tail,
+    } = ev
+    {
+        chat_log.push_channel_notice(notice, channel, &tail);
+    }
+}
+
+fn on_random_roll(In(ev): In<SessionEvent>, mut chat_log: ResMut<ChatLog>) {
+    if let SessionEvent::RandomRoll {
+        min,
+        max,
+        roll,
+        guid,
+    } = ev
+    {
+        chat_log.push_roll(min, max, roll, guid);
+    }
+}
+
+/// The chat log's session state dies with the socket. A listener on the session end
+/// (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut chat_log: ResMut<ChatLog>) {
+    chat_log.clear_session();
+}
 
 /// A spoken line (`SMSG_MESSAGECHAT`) — the chat window's own feed (decision 0084):
-/// [`crate::ui_chat`] formats + colors per type, resolves the sender name ask-once, and
+/// [`super`] formats + colors per type, resolves the sender name ask-once, and
 /// AddMessages it into ChatFrame1.
 ///
 /// System lines (`CHAT_MSG_SYSTEM` 0x0A, vmangos `SharedDefines.h`) are the SERVER'S ANSWER to a GM
@@ -27,7 +141,7 @@ use super::super::{ClientCommand, NetCommands, ServerSaidMessage};
 /// invisible at the default level, and a refused command read exactly like an applied one
 /// (decision 0651 — the rig's whole batch silently no-op'd on a too-low GM level and nothing said
 /// so). Ordinary chat stays at `debug!`: conversation, not diagnosis, and high volume.
-pub(super) fn chat(
+fn chat(
     m: ChatMessage,
     chat_log: &mut ChatLog,
     social: &SocialState,
@@ -41,7 +155,7 @@ pub(super) fn chat(
     // `[Party] [Soreen]: Quiver VERSION:3.1.4` version ping as ordinary party chat, and a
     // mixed-client party makes that constant background noise.
     //
-    // VERIFIED in `WoW.exe` (5875) — wow-re `system/ui/scratch/addon-chat-law.md`: the test is
+    // In `WoW.exe` (5875) the test is
     // `0x49a89b`/`0x49a89e cmp edi,-0x1`, in the DISPLAY function `0x49a870`, and every branch of
     // the addon arm `[0x49a8a7, 0x49a96d)` jumps below the normal render path at `0x49a970` — the
     // chat frame is unreachable for such a line by construction. The **language field is the whole
@@ -77,10 +191,8 @@ pub(super) fn chat(
     //     no tab the whole text is the *prefix* and the message is `""`, not the other way round.
     //   - `distribution` is the remap table `0x49aff4` → jump table `0x49afe0`: only
     //     PARTY/RAID/GUILD/BATTLEGROUND get names, every other type byte reports `"UNKNOWN"`.
-    //   - the *fire* must move downstream of the name resolve so `sender` is a name, not a guid.
-    //     The drop can stay here; the fire cannot.
-    //
-    // All four are recorded byte-exact in wow-re `system/ui/scratch/addon-chat-law.md` §3/§4/§6.
+    //   - the *fire* must move downstream of the name resolve (`0x49ccc0`) so `sender` is a name,
+    //     not a guid. The drop can stay here; the fire cannot.
     //
     // The payload rides `debug!` and its own `addon` trace tag rather than vanishing, so
     // mixed-client traffic stays diagnosable: invisible in chat, never invisible to us.
@@ -134,8 +246,8 @@ pub(super) fn chat(
         );
     }
     // The ignore gate (decision 0668): an ignored speaker is dropped SILENTLY — no line at all —
-    // which is the client's own `FriendList::IsIgnored 0x5ae5a0` check, VERIFIED for the sibling
-    // text-emote path (wow-re `system/ui/scratch/text-emote-composition.md`). A dropped WHISPER
+    // which is the client's own `FriendList::IsIgnored 0x5ae5a0` check, read on the sibling
+    // text-emote path (`0x49dbe0`). A dropped WHISPER
     // additionally tells the server, so the sender gets the "is ignoring you" answer: that is what
     // `CMSG_CHAT_IGNORED` is for, and only the client can send it.
     if social.is_ignored(m.sender_guid) {
@@ -152,7 +264,7 @@ pub(super) fn chat(
 /// The `/chatlist` roster (`SMSG_CHANNEL_LIST`) — CHAT_CHANNEL_LIST_GET "[%s] " + the roster.
 /// Names arrive as guids; v1 renders the count (the per-member resolve fan-out lands with the
 /// P6 channel wiring — /chatlist is rare enough that a count is honest, never wrong).
-pub(super) fn channel_list(channel: String, members: &[(u64, u8)], chat_log: &mut ChatLog) {
+fn channel_list(channel: String, members: &[(u64, u8)], chat_log: &mut ChatLog) {
     let mut ev = ChatEvent::text_only(
         ChatEventKind::ChannelList,
         format!("{} member(s)", members.len()),
@@ -168,7 +280,7 @@ pub(super) fn channel_list(channel: String, members: &[(u64, u8)], chat_log: &mu
 /// there is no VM here, so `ui_action`'s drain is what resolves it against the player's own
 /// `GlobalStrings.lua` — and the row, not this call site, is what says the line goes to chat
 /// (`kind 0`) and makes no sound.
-pub(super) fn chat_player_not_found(name: &str, errors: &mut crate::ui_action::UiErrorKeys) {
+fn chat_player_not_found(name: &str, errors: &mut crate::ui_action::UiErrorKeys) {
     errors.0.push(crate::ui_action::UiError::s(
         "ERR_CHAT_PLAYER_NOT_FOUND_S",
         name,
@@ -177,7 +289,7 @@ pub(super) fn chat_player_not_found(name: &str, errors: &mut crate::ui_action::U
 
 /// A cross-faction whisper was refused — `ERR_CHAT_WRONG_FACTION`, catalog row 240. Same route and
 /// the same reason as [`chat_player_not_found`], with no argument to fill.
-pub(super) fn chat_wrong_faction(errors: &mut crate::ui_action::UiErrorKeys) {
+fn chat_wrong_faction(errors: &mut crate::ui_action::UiErrorKeys) {
     errors
         .0
         .push(crate::ui_action::UiError::key("ERR_CHAT_WRONG_FACTION"));
@@ -188,8 +300,8 @@ pub(super) fn chat_wrong_faction(errors: &mut crate::ui_action::UiErrorKeys) {
 /// Byte-verified in the reference: opcode `0x1cb`'s handler is `0x401800` (registered at
 /// `0x40172f`, torn down at `0x401f09`), whose whole body is "read the cstring, then
 /// `mov edx,1; lea ecx,[buf]; call 0x4945b0`" plus a console log (`0x63cd00(…, 3, buf)` — our
-/// `info!` below). `0x4945b0(text, 1)` fires FrameScript event `0xe0` = `UI_ERROR_MESSAGE`
-/// (wow-re `system/ui/ui.md` l.2459). Nothing on this path touches the chat composer.
+/// `info!` below). `0x4945b0(text, 1)` fires FrameScript event `0xe0` = `UI_ERROR_MESSAGE`.
+/// Nothing on this path touches the chat composer.
 ///
 /// **This used to push into the chat feed**, as a stand-in from before benilla had an errors
 /// frame. It has had a real one for a long time — the ref `UIErrorsFrame`, a genuine
@@ -198,7 +310,7 @@ pub(super) fn chat_wrong_faction(errors: &mut crate::ui_action::UiErrorKeys) {
 /// `Player::SetGameMaster` answers `.gm on|off` with **both** `SendSysMessage` and
 /// `SendNotification` (`Objects/Player.cpp:2676-2677`/`2701-2702`), so a client that sinks the
 /// notification into chat prints "GM mode is ON" **twice** where the reference prints it once.
-pub(super) fn notification(text: String, errors: &mut UiErrorTexts) {
+fn notification(text: String, errors: &mut UiErrorTexts) {
     // The handler's own console leg, and the same reason 0651 logs the dot-command answers: a
     // toast that flashed for five seconds and one that never arrived look identical afterwards.
     info!("net: notification — {text}");
@@ -212,7 +324,7 @@ pub(super) fn notification(text: String, errors: &mut UiErrorTexts) {
 /// comment here called it the same sink as the notification and left it at that; the sink is the
 /// same, the arm is not.) Without it, a refused portal is silent, which reads exactly like a
 /// portal that is still broken.
-pub(super) fn area_trigger_message(text: String, errors: &mut UiErrorTexts) {
+fn area_trigger_message(text: String, errors: &mut UiErrorTexts) {
     // Logged for the same reason 0651 logs the server's dot-command answers: a trigger that
     // refused and a trigger the client never noticed look identical from outside.
     info!("net: area-trigger message — {text}");
@@ -220,7 +332,7 @@ pub(super) fn area_trigger_message(text: String, errors: &mut UiErrorTexts) {
 }
 
 /// The four **world broadcasts** — parked on [`ChatLog`]'s broadcast queue for
-/// [`crate::ui_chat`]'s resolve pass, which holds the AreaTable/ServerMessages catalogs and the
+/// [`super`]'s resolve pass, which holds the AreaTable/ServerMessages catalogs and the
 /// joined-channel walk this site does not (`ui_chat::broadcast` carries the whole mechanism).
 ///
 /// Only the parking happens here, deliberately: half-resolving at the packet — naming the area
@@ -231,7 +343,7 @@ pub(super) fn area_trigger_message(text: String, errors: &mut UiErrorTexts) {
 /// arrived" have to be distinguishable in a log afterwards. A defense broadcast that reaches a
 /// character in neither defense channel prints nothing on screen and is faithful in doing so — the
 /// log line is the only trace it happened at all.
-pub(super) fn broadcast(b: Broadcast, chat_log: &mut ChatLog) {
+fn broadcast(b: Broadcast, chat_log: &mut ChatLog) {
     info!("net: world broadcast — {b:?}");
     chat_log.push_broadcast(b);
 }
@@ -239,7 +351,7 @@ pub(super) fn broadcast(b: Broadcast, chat_log: &mut ChatLog) {
 /// The `/played` answer (`SMSG_PLAYED_TIME`) — TIME_PLAYED_TOTAL/LEVEL over
 /// TIME_DAYHOURMINUTESECOND (GlobalStrings:4243-4247; the ref's
 /// ChatFrame_DisplayTimePlayed breakdown).
-pub(super) fn played_time(total: u32, level: u32, chat_log: &mut ChatLog) {
+fn played_time(total: u32, level: u32, chat_log: &mut ChatLog) {
     for (label, secs) in [
         ("Total time played", total),
         ("Time played this level", level),
diff --git a/crates/benilla-app/src/ui_chat/recruitment.rs b/crates/benilla-app/src/ui_chat/recruitment.rs
index d934c6d8..647ac81c 100644
--- a/crates/benilla-app/src/ui_chat/recruitment.rs
+++ b/crates/benilla-app/src/ui_chat/recruitment.rs
@@ -1,8 +1,6 @@
 //! The `AUTO_JOIN_GUILD_CHANNEL` cascade — the reference's `0x49ea90`, the thing
 //! `SetGuildRecruitmentMode(1)` tail-jumps into and the one place the client joins or leaves
-//! `GuildRecruitment - City` on its own (decision 2144; every byte fact below is wow-re
-//! `system/ui/scratch/guild-recruitment-mode.md`, a §5 round, and its callers' census in
-//! `zone-chat-channel-autojoin.md` §11.5).
+//! `GuildRecruitment - City` on its own (decision 2144).
 //!
 //! **What it is for.** `GuildRecruitment` is the channel *unguilded* players sit in to be found.
 //! Its `ChatChannels.dbc` row carries no `INITIAL` bit, so the zone walk never seeds it; instead
@@ -10,8 +8,9 @@
 //! the local player's own `PLAYER_GUILDID` and acts on the wire:
 //!
 //! - **guilded** ⇒ leave-by-name `"GuildRecruitment - City"` (`0x49eb17` → `0x49ee70`):
-//!   `CMSG_LEAVE_CHANNEL`, the channel stripped from every chat window's list, its `ZONECHANNELS`
-//!   bit cleared, then `UPDATE_CHAT_WINDOWS`. **No already-a-member check.**
+//!   `CMSG_LEAVE_CHANNEL` and its `ZONECHANNELS` bit cleared, then `UPDATE_CHAT_WINDOWS`. **No
+//!   already-a-member check.** The window entry the join registered **stays**: the leave's strip
+//!   key is the full name, which no window carries (`0x49f017`).
 //! - **unguilded, in a capital** (`AreaTable Flags & 0x100`) ⇒ join `"GuildRecruitment"`
 //!   (`0x49eb55` → `0x49eb70`): a slot, the composed name into chat window 1's list,
 //!   `CMSG_JOIN_CHANNEL`, then `UPDATE_CHAT_WINDOWS`. **No already-joined check.**
@@ -24,7 +23,7 @@
 //! gate, suspended outside a capital, re-joined on the way back in through the state-3 bypass
 //! ([`super::channels::plan_walk`]). The cascade is the *entry*, not the upkeep.
 //!
-//! **Triggers** (`0x49ea90`'s closed caller census, §4.2): `SetGuildRecruitmentMode(1)`; the
+//! **Triggers** (`0x49ea90`'s closed caller census): `SetGuildRecruitmentMode(1)`; the
 //! chat-cache loader seating `AUTO`; the local player's `PLAYER_GUILDID` field-change watcher
 //! (`0x5e2770`); and every `CGPlayer` create (`0x5dec1e`) — which includes the local player's own
 //! at login. Ours: the Lua verb's ask, and a watcher over the local player's guild id whose first
@@ -54,7 +53,7 @@ use super::edit::ChannelState;
 /// `AreaTable.dbc` `Flags & 0x100` — vmangos `AREA_FLAG_CAPITAL`. The cascade's own capital test
 /// (`0x49eb2e test ch,1`): a *different* bit from the walk's eligibility gate (`0x8`), read here
 /// as its own flag because the client reads it as one. In the 1.12.1 data both sit on exactly the
-/// same six rows (autojoin §5).
+/// same six rows.
 const AREA_FLAG_CAPITAL: u32 = 0x100;
 
 /// The cascade's own state: whether a run is owed, and the guild id its watcher last saw.
@@ -193,13 +192,7 @@ pub(super) fn guild_recruitment_cascade(
     match action {
         Cascade::Leave => {
             info!("chat: guild recruitment cascade — guilded, leaving {name:?}");
-            let _ = commands
-                .0
-                .send(ClientCommand::LeaveChannel { name: name.clone() });
-            // `0x49ee70`'s other two halves: the strip from all ten windows, keyed on the
-            // Shortcut (§6), and the mask bit (`0x49f10a`/`0x49f11a`).
-            script.strip_chat_window_channel(&row.shortcut);
-            channels.note_zone_channel_left(&name);
+            cascade_leave(&mut channels, &commands, name);
         }
         Cascade::Join => {
             info!("chat: guild recruitment cascade — unguilded in a capital, joining {name:?}");
@@ -229,6 +222,21 @@ pub(super) fn guild_recruitment_cascade(
     state.pending = false;
 }
 
+/// The cascade's LEAVE arm — leave-by-name `0x49ee70` over the composed name
+/// `"GuildRecruitment - City"`: the packet and the mask bit (`0x49f10a`/`0x49f11a`).
+///
+/// **No window strip.** `0x49ee70` does strip every window's list, but keyed on the DBC Shortcut
+/// only when its *argument* matched a shortcut — else on the argument verbatim (`0x49eff6` /
+/// `0x49f017`). The full name matches no shortcut, and the join arm registered window 1's entry
+/// under the Shortcut `"GuildRecruitment"`, so the scan misses in every window and the entry
+/// survives. Stripping by the Shortcut here removed an entry the reference keeps.
+fn cascade_leave(channels: &mut ChannelState, commands: &NetCommands, name: String) {
+    let _ = commands
+        .0
+        .send(ClientCommand::LeaveChannel { name: name.clone() });
+    channels.note_zone_channel_left(&name);
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -252,6 +260,49 @@ mod tests {
         assert_eq!(cascade(true, 0, false), Some(Cascade::Deferred));
     }
 
+    /// **The cascade's own leave cannot strip its window entry** (`0x49f017`).
+    /// The join arm registered window 1's entry
+    /// under the Shortcut `"GuildRecruitment"`; the leave's strip key is its argument, the full
+    /// `"GuildRecruitment - City"`, which matches no DBC shortcut and so is used verbatim — and
+    /// equals no window entry. The packet goes out and the mask bit clears; the entry stays.
+    #[test]
+    fn the_cascades_leave_keeps_the_windows_entry() {
+        const GUILD_RECRUITMENT: u32 = 25;
+        let mut script = UiScript::new().expect("a VM");
+        assert!(script.register_chat_window_channel(0, "GuildRecruitment", GUILD_RECRUITMENT));
+        let mut channels = ChannelState {
+            channels: benilla_formats::ChatChannelsCatalog::from_rows(vec![
+                benilla_formats::ChatChannelRow {
+                    id: GUILD_RECRUITMENT,
+                    flags: 0x32,
+                    pattern: "GuildRecruitment - %s".into(),
+                    shortcut: "GuildRecruitment".into(),
+                },
+            ]),
+            zone_mask: Some(1 << (GUILD_RECRUITMENT - 1)),
+            ..Default::default()
+        };
+        channels.claim_slot("GuildRecruitment - City");
+        let (tx, rx) = crossbeam_channel::unbounded();
+
+        cascade_leave(
+            &mut channels,
+            &NetCommands(tx),
+            "GuildRecruitment - City".into(),
+        );
+
+        assert!(
+            matches!(rx.try_recv(), Ok(ClientCommand::LeaveChannel { name }) if name == "GuildRecruitment - City"),
+            "the CMSG_LEAVE_CHANNEL goes out"
+        );
+        assert_eq!(channels.zone_mask, Some(0), "the mask bit clears");
+        assert_eq!(
+            script.chat_window_looks()[0].channels,
+            vec![("GuildRecruitment".to_string(), GUILD_RECRUITMENT)],
+            "window 1 still carries the entry the join registered"
+        );
+    }
+
     /// The watcher: the first sight of the guild id is a change (the player-create trigger), a
     /// repeat is not, a move is, and the session end forgets — so the next login's first sight is
     /// a change again.
diff --git a/crates/benilla-app/src/ui_chat/settings.rs b/crates/benilla-app/src/ui_chat/settings.rs
index b495232f..b148c135 100644
--- a/crates/benilla-app/src/ui_chat/settings.rs
+++ b/crates/benilla-app/src/ui_chat/settings.rs
@@ -12,8 +12,7 @@
 //! ## The grammar is the reference's
 //!
 //! 1.12 keeps these in `WTF/Account/<ACC>/<REALM>/<CHAR>/chat-cache.txt`, written whole by
-//! `0x499a80` and read by `0x498a60` (wow-re `system/ui/scratch/chat-cache-grammar.md`, §1 and
-//! §3 — every line below is that note's):
+//! `0x499a80` and read by `0x498a60` (every line below is the reference's):
 //!
 //! ```text
 //! VERSION 2
@@ -71,10 +70,10 @@
 //! ## The login events
 //!
 //! The loader fires `UPDATE_CHAT_WINDOWS` once and then `UPDATE_CHAT_COLOR` for **every** registry
-//! entry — file or no file (§8). The first is what `FloatingChatFrame_Update` docks, hides and
-//! colours the windows from; the second is how a saved colour reaches `ChatTypeInfo` and repaints
-//! the lines already in the window (`ChatFrame_OnEvent`'s arm). So does ours, once per character
-//! per VM.
+//! entry — file or no file (`0x4996b9`, `0x499934`). The first is what `FloatingChatFrame_Update`
+//! docks, hides and colours the windows from; the second is how a saved colour reaches
+//! `ChatTypeInfo` and repaints the lines already in the window (`ChatFrame_OnEvent`'s arm). So does
+//! ours, once per character per VM.
 //!
 //! ## Why per character, and not a CVar
 //!
@@ -110,8 +109,8 @@ const SAVE_QUIET: std::time::Duration = std::time::Duration::from_secs(1);
 /// The file's header — where these values come from and where the law lives. Comment lines; the
 /// reference's reader has none, ours skips them.
 const HEADER: &str = "\
-# benilla chat cache (decisions 1589, 1948) — the reference's chat-cache.txt grammar (wow-re
-# chat-cache-grammar.md): the custom channels to re-join, the joined zone channels as bits, the
+# benilla chat cache (decisions 1589, 1948) — the reference's chat-cache.txt grammar (written by
+# 0x499a80, read by 0x498a60): the custom channels to re-join, the joined zone channels as bits, the
 # per-type COLORS table, then one WINDOW block per chat frame — NAME (when one was set), SIZE,
 # COLOR r g b a as bytes, LOCKED, DOCKED, SHOWN, the MESSAGES … END list of the groups the window
 # shows, its CHANNELS … END list of custom channels, and its zone channels as ZONECHANNELS bits.
@@ -168,7 +167,7 @@ pub(super) struct Parsed {
     pub(super) zone_mask: Option<u32>,
     /// `OPTION_GUILD_RECRUITMENT_CHANNEL` — the auto-join latch `GetGuildRecruitmentMode` returns
     /// (decision 2115). `STANDARD` is 0 and **anything else, a missing word included, is 1**: that
-    /// is the reference's own reading (wow-re `chat-cache-grammar.md` — `"STANDARD"` takes the
+    /// is the reference's own reading (`"STANDARD"` takes the
     /// `0x49ea70(ecx=0)` leg and every other word takes `ecx=1`), and it is why a file with no such
     /// line at all reads as AUTO here, exactly as it does there.
     pub(super) guild_recruitment_auto: bool,
@@ -189,22 +188,23 @@ impl Default for Parsed {
     }
 }
 
-/// Render the file exactly as the writer does (§1), window order.
+/// Render the file exactly as the writer does (`0x499a80`), window order.
 ///
-/// `joined` is the client's current channel roster and supplies the header's `CHANNELS` names —
-/// **the custom ones only** (`id == 0`): a zone channel is never written as a name, it travels as
-/// its bit (wow-re `chat-cache-grammar.md` §1.1, which is why all 34 stock files have an empty
-/// per-window `CHANNELS` block beside a non-zero `ZONECHANNELS`).
+/// `custom` is [`super::edit::ChannelState::custom`] and supplies the header's `CHANNELS` names —
+/// **the custom channels only**: a zone channel is never written as a name, it travels as its bit
+/// (`0x499ba1`, which is why all 34 stock files have an empty per-window
+/// `CHANNELS` block beside a non-zero `ZONECHANNELS`). Durable, not the live roster, for the
+/// mask's own reason: the session end clears the roster before the flush reads it.
 ///
 /// `zone_mask` is [`super::edit::ChannelState::zone_mask`], written raw into the header
 /// (`0x499c19`) and ANDed with each window's own bits for its block (`0x49a133`/`0x49a138`). It is
-/// **passed in rather than derived from `joined`** — decision 2120, and the whole bug: derived, it
+/// **passed in rather than derived from the live roster** — decision 2120, and the whole bug: derived, it
 /// was 0 on any save taken while the roster was empty, and `window AND 0` erased the window's
 /// channel list for good.
 fn render(
     looks: &[ChatWindowLook],
     colors: &[ChatTypeColor],
-    joined: &[(String, u32)],
+    custom: &[String],
     zone_mask: u32,
     guild_recruitment_auto: bool,
 ) -> String {
@@ -222,11 +222,9 @@ fn render(
     out.push_str(&format!(
         "\nVERSION 2\n\nADDEDVERSION 2\n\nOPTION_GUILD_RECRUITMENT_CHANNEL {recruitment}\n\nCHANNELS\n"
     ));
-    for (name, id) in joined {
-        if *id == 0 {
-            out.push_str(name);
-            out.push('\n');
-        }
+    for name in custom {
+        out.push_str(name);
+        out.push('\n');
     }
     out.push_str(&format!("END\n\nZONECHANNELS {zone_mask}\n\nCOLORS\n"));
     for c in colors {
@@ -341,8 +339,8 @@ fn parse(text: &str, rows: &[(u32, String)]) -> Parsed {
                     // its id and this restores it (decision 2130).
                     //
                     // Not a heuristic: the reference's engine resolves every name through the
-                    // shortcut walk before it stores one (`AddChatWindowChannel 0x4a1000`,
-                    // chat-cache-grammar.md §5), so a *custom* entry can never be spelled exactly
+                    // shortcut walk before it stores one (`AddChatWindowChannel 0x4a1000`),
+                    // so a *custom* entry can never be spelled exactly
                     // like a built-in shortcut — all 34 stock files carry an empty per-window
                     // `CHANNELS` block beside a non-zero `ZONECHANNELS`. Ours could, because the
                     // VM's catalog was still empty when the window was written, and `General` came
@@ -415,9 +413,9 @@ fn parse(text: &str, rows: &[(u32, String)]) -> Parsed {
         }
     }
     flush(&mut current, &mut out);
-    // The loader's EOF back-fill (§3): a file older than the groups added since gets them, into
-    // window 1 for the first ten groups and window 2 otherwise — the two `addedVersion` rows are
-    // both window 2's.
+    // The loader's EOF back-fill (`0x49967c`): a file older than the groups added since gets them,
+    // into window 1 for the first ten groups and window 2 otherwise — the two `addedVersion` rows
+    // are both window 2's.
     if added_version < 2 {
         for (i, (name, on, ver)) in MESSAGE_GROUPS.iter().enumerate() {
             if *on && *ver > added_version {
@@ -494,15 +492,6 @@ fn shortcut_rows(channels: &super::edit::ChannelState) -> Vec<(u32, String)> {
         .collect()
 }
 
-/// The client's channel roster as `(name, zone id)` — what the writer's header and masks are made
-/// of.
-fn roster(channels: &super::edit::ChannelState) -> Vec<(String, u32)> {
-    channels
-        .iter_names()
-        .map(|name| (name.to_string(), channels.channels.zone_channel_id(name)))
-        .collect()
-}
-
 /// Restore the file into a fresh VM — once per character per VM — and fire the loader's two
 /// events, file or no file.
 ///
@@ -585,7 +574,7 @@ pub(crate) fn restore_chat_looks(world: &mut World, script: &mut UiScript) {
             .is_some_and(|t| !t.contains(WRITER_GENERATION));
         parsed = text.map(|t| parse(&t, &rows)).unwrap_or_default();
         if !had_file {
-            // The loader's no-file path (§3, `0x4997ad`): the mask is seeded from those rows, and
+            // The loader's no-file path (`0x4997ad`): the mask is seeded from those rows, and
             // window 1's channel slots get each of them as `(Shortcut, id)` — the rows
             // `ChatFrame_RegisterForChannels` will match zone speech against by id. The rest of the
             // record is the boot init the VM already holds.
@@ -632,12 +621,15 @@ pub(crate) fn restore_chat_looks(world: &mut World, script: &mut UiScript) {
         // `Some` is the reference's "chat system ready" flag (`0x499a18`): the walk and the
         // guild-recruitment cascade both hold until this line has run (decision 2144).
         channels.zone_mask = Some(mask);
+        // The custom re-join list is durable on the same terms: seated from the file here, then
+        // moved only by a confirmed join and an explicit leave (`ChannelState::custom`).
+        channels.custom = parsed.joined.clone();
     }
     script.set_guild_recruitment_mode(u8::from(parsed.guild_recruitment_auto));
     script.set_chat_colors(parsed.colors);
     script.set_chat_window_looks(parsed.looks);
-    // §8: UPDATE_CHAT_WINDOWS once, then UPDATE_CHAT_COLOR for every registry entry, on the file
-    // path and the no-file path alike.
+    // UPDATE_CHAT_WINDOWS once, then UPDATE_CHAT_COLOR for every registry entry, on the file
+    // path and the no-file path alike (`0x4996b9`, `0x499934`).
     script.fire_event("UPDATE_CHAT_WINDOWS", vec![]);
     let renorm = |b: u8| f64::from(b as f32 * (1.0f32 / 255.0f32));
     for entry in script.chat_colors() {
@@ -691,7 +683,7 @@ fn write(script: &UiScript, channels: &super::edit::ChannelState, path: &std::pa
     let body = render(
         &script.chat_window_looks(),
         &script.chat_colors(),
-        &roster(channels),
+        &channels.custom,
         zone_mask,
         script.guild_recruitment_mode() != 0,
     );
@@ -705,7 +697,7 @@ fn write(script: &UiScript, channels: &super::edit::ChannelState, path: &std::pa
 /// - **A flush** (`exiting`) — the session end or the window close — writes **unconditionally**,
 ///   provided this VM restored the character's file (`restored`): the reference rewrites the
 ///   whole file at chat teardown (`0x499a80` from `0x490c55`) with no dirty flag in the way
-///   (`[0xb6e5c4]` has three writers and no reader; wow-re `guild-recruitment-mode.md` §6). The
+///   (`[0xb6e5c4]` has three writers and no reader). The
 ///   `ZONECHANNELS` word and the guild-recruitment latch are host state that no Lua write ever
 ///   dirties — gating the flush on `dirty` is how a `/leave General` was persisted only when the
 ///   player also happened to drag a window, and 2120's "durable state" was durable on paper.
@@ -886,14 +878,9 @@ mod tests {
             named,
         ];
         let colors = colors(&[("SAY", [1, 2, 3]), ("CHANNEL7", [4, 5, 6])]);
-        let joined = vec![
-            ("General - Elwynn Forest".to_string(), 1),
-            ("Trade - City".to_string(), 2),
-            ("MyChan".to_string(), 0),
-        ];
-        // The mask is the character's durable one now (2120), passed in rather than derived —
-        // here, the two zone channels the roster holds.
-        let text = render(&looks, &colors, &joined, 0b11, true);
+        // The mask and the custom list are the character's durable state (2120), passed in rather
+        // than derived from the live roster.
+        let text = render(&looks, &colors, &["MyChan".to_string()], 0b11, true);
         assert!(
             text.contains("\nCHANNELS\nMyChan\nEND\n\nZONECHANNELS 3\n"),
             "{text}"
@@ -966,13 +953,7 @@ mod tests {
         w.channels = vec![("General".into(), 1), ("Trade".into(), 2)];
         // The mask holds General alone — Trade was explicitly left, so the window's own Trade
         // bit is ANDed away on the way out.
-        let text = render(
-            &[w],
-            &[],
-            &[("General - Elwynn Forest".to_string(), 1)],
-            1,
-            true,
-        );
+        let text = render(&[w], &[], &[], 1, true);
         let windows: Vec<&str> = text.split("WINDOW 1").collect();
         assert!(windows[1].contains("ZONECHANNELS 1\n"), "{text}");
     }
@@ -1062,7 +1043,7 @@ mod tests {
         state.note_zone_channel_joined("MyChan");
         assert_eq!(state.zone_mask, Some(0b11), "a custom channel has no bit");
         // The clear is keyed on the SLOT the wire name finds, and its own id (decision 2144,
-        // wow-re `leavechannelbyname-contract.md` §8) — a name we hold no slot for clears nothing.
+        // `0x49f0f4`–`0x49f11a`) — a name we hold no slot for clears nothing.
         state.note_zone_channel_left("Trade - City");
         assert_eq!(state.zone_mask, Some(0b11), "no slot carries it yet");
         state.claim_slot("Trade - City");
@@ -1074,6 +1055,30 @@ mod tests {
         );
     }
 
+    /// The custom re-join list moves on the same two edges as the mask — a confirmed join of a
+    /// channel with no DBC id, and an explicit leave — and a zone channel never enters it.
+    #[test]
+    fn the_custom_list_moves_on_join_and_explicit_leave_only() {
+        let mut state = super::super::edit::ChannelState {
+            channels: benilla_formats::ChatChannelsCatalog::from_rows(vec![
+                benilla_formats::ChatChannelRow {
+                    id: 1,
+                    flags: 0x11,
+                    pattern: "General - %s".into(),
+                    shortcut: "General".into(),
+                },
+            ]),
+            ..Default::default()
+        };
+        state.note_custom_channel_joined("General - Elwynn Forest");
+        assert!(state.custom.is_empty(), "a zone channel travels as its bit");
+        state.note_custom_channel_joined("MyChan");
+        state.note_custom_channel_joined("mychan");
+        assert_eq!(state.custom, vec!["MyChan".to_string()], "once, by name");
+        state.note_custom_channel_left("MYCHAN");
+        assert!(state.custom.is_empty(), "an explicit leave drops it");
+    }
+
     /// **The teardown write is unconditional; only the debounce reads the dirty flag** (decision
     /// 2144). A `/leave General` moves host state alone — the mask — and the reference persists
     /// it because its teardown saver has no dirty flag; ours gated the same write on a Lua-side
@@ -1272,34 +1277,7 @@ mod tests {
         world.init_resource::<super::super::edit::ChannelState>();
         world.init_resource::<ChatWindowFile>();
         crate::ui_script::setup_script(&mut world);
-        world.insert_resource(crate::char_select::Roster::with_pending_pick(
-            vec![benilla_protocol::Character {
-                guid: 1,
-                name: "Reloadprobe".into(),
-                race: 1,  // Human → Alliance
-                class: 1, // Warrior
-                gender: 0,
-                level: 60,
-                skin: 0,
-                face: 0,
-                hair_style: 0,
-                hair_color: 0,
-                facial_hair: 0,
-                zone: 0,
-                map: 0,
-                position: benilla_protocol::wire::Vector3d {
-                    x: 0.0,
-                    y: 0.0,
-                    z: 0.0,
-                },
-                flags: 0,
-                equipment: [benilla_protocol::CharEnumItem::default(); 19],
-                pet_display_id: 0,
-                pet_level: 0,
-                pet_family: 0,
-            }],
-            1,
-        ));
+        world.insert_resource(probe_roster("Reloadprobe"));
         crate::ui_script::load_ingame_ui_on_world_entry(&mut world);
 
         let path = world
@@ -1346,4 +1324,130 @@ mod tests {
         drop(world);
         let _ = std::fs::remove_dir_all(&tmp);
     }
+
+    /// A roster with one character picked — what `load_ingame_ui_on_world_entry` keys the
+    /// character's chat cache path on.
+    fn probe_roster(name: &str) -> crate::char_select::Roster {
+        crate::char_select::Roster::with_pending_pick(
+            vec![benilla_protocol::Character {
+                guid: 1,
+                name: name.into(),
+                race: 1,  // Human → Alliance
+                class: 1, // Warrior
+                gender: 0,
+                level: 60,
+                skin: 0,
+                face: 0,
+                hair_style: 0,
+                hair_color: 0,
+                facial_hair: 0,
+                zone: 0,
+                map: 0,
+                position: benilla_protocol::wire::Vector3d {
+                    x: 0.0,
+                    y: 0.0,
+                    z: 0.0,
+                },
+                flags: 0,
+                equipment: [benilla_protocol::CharEnumItem::default(); 19],
+                pet_display_id: 0,
+                pet_level: 0,
+                pet_family: 0,
+            }],
+            1,
+        )
+    }
+
+    /// **A custom channel survives `/logout`** (2184 §6, the question it left open). The header's
+    /// `CHANNELS` list is the character's custom channels to re-join at the next login. It was
+    /// composed from the live roster, and the logout clears that roster first: the
+    /// `Disconnected{LoggedOut}` that arrives in the same net drain as the logout runs
+    /// `end_session_channels_on_disconnect` in `Update`, a frame before `OnExit(InWorld)` reaches
+    /// `end_ui_session`'s flush. So the file was written with an empty list and the channel was
+    /// never re-joined. The same order is driven here, by the same functions.
+    #[test]
+    fn a_custom_channel_survives_a_logout() {
+        use bevy::ecs::system::RunSystemOnce;
+
+        let _l = crate::local_state::test_env::ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let tmp = std::env::temp_dir().join(format!("benilla-chat-custom-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&tmp);
+        std::fs::create_dir_all(tmp.join("benilla-config")).expect("hermetic home");
+        let _capture = crate::local_state::test_env::EnvGuard::unset("WOW_CAPTURE");
+        let _home = crate::local_state::test_env::EnvGuard::set(
+            "BENILLA_HOME",
+            tmp.join("benilla-config")
+                .to_str()
+                .expect("utf-8 temp path"),
+        );
+
+        let roster = probe_roster("Channelprobe");
+        let id = crate::ui_macro::identity(&roster).expect("a picked character");
+        let path = crate::local_state::chat_character_path(&id.0, &id.1).expect("a cache path");
+        std::fs::create_dir_all(path.parent().expect("a parent")).expect("the character dir");
+        // A file this writer made (the marker), listing one custom channel in the header.
+        let file = format!(
+            "{WRITER_GENERATION}\nVERSION 2\n\nCHANNELS\nMyChan\nEND\n\nZONECHANNELS 3\n\n\
+             COLORS\nEND\n\nWINDOW 1\nSIZE 0\n\nMESSAGES\nSAY\nEND\n\nCHANNELS\nEND\n\n\
+             ZONECHANNELS 3\n\nEND\n"
+        );
+        std::fs::write(&path, file).expect("seed the file");
+
+        let mut world = World::new();
+        world.init_resource::<crate::ui_script::AddOnIdentity>();
+        world.init_resource::<crate::minimap::MinimapZoom>();
+        world.init_resource::<crate::ui_script::ReloadUiPending>();
+        world.init_resource::<super::super::edit::ChannelState>();
+        world.init_resource::<super::super::channels::ZoneChannelWalk>();
+        world.init_resource::<super::super::recruitment::GuildRecruitmentCascade>();
+        world.init_resource::<Messages<crate::net::DisconnectedMessage>>();
+        world.init_resource::<ChatWindowFile>();
+        crate::ui_script::setup_script(&mut world);
+        world.insert_resource(roster);
+        crate::ui_script::load_ingame_ui_on_world_entry(&mut world);
+
+        // The login's re-join is confirmed: the server's YOU_JOINED, through the real feed arm.
+        world.resource_scope(
+            |world, mut channels: Mut<super::super::edit::ChannelState>| {
+                let mut script = world.non_send_resource_mut::<UiScript>();
+                let mut windows = super::super::frames::ChatWindows::default();
+                let mut e = super::super::event::ChatEvent::text_only(
+                    super::super::event::ChatEventKind::ChannelNotice,
+                    String::new(),
+                );
+                e.channel = "MyChan".into();
+                e.notice = "2".into(); // YOU_JOINED
+                super::super::feed::deliver(&mut script, &mut windows, &mut channels, &mut e);
+            },
+        );
+        assert_eq!(
+            world
+                .resource::<super::super::edit::ChannelState>()
+                .number_of("MyChan"),
+            Some(1),
+            "precondition: the channel is joined and numbered"
+        );
+
+        // `/logout`: the disconnect lands in `Update` first…
+        world.write_message(crate::net::DisconnectedMessage::new(
+            "logged out".into(),
+            benilla_protocol::SessionEnd::LoggedOut,
+        ));
+        world
+            .run_system_once(super::super::channels::end_session_channels_on_disconnect)
+            .expect("the disconnect twin runs");
+        // …and `OnExit(InWorld)` flushes the dying VM's cache a frame later.
+        crate::ui_script::end_ui_session(&mut world);
+
+        let on_disk = std::fs::read_to_string(&path).expect("the flush wrote the file");
+        assert!(
+            on_disk.contains("\nCHANNELS\nMyChan\nEND\n\nZONECHANNELS"),
+            "the custom channel is still in the header's re-join list; file was:\n{on_disk}"
+        );
+
+        drop(world);
+        let _ = std::fs::remove_dir_all(&tmp);
+    }
 }
diff --git a/crates/benilla-app/src/ui_chat/tests.rs b/crates/benilla-app/src/ui_chat/tests.rs
index 873a76ef..573dafc2 100644
--- a/crates/benilla-app/src/ui_chat/tests.rs
+++ b/crates/benilla-app/src/ui_chat/tests.rs
@@ -639,9 +639,9 @@ fn a_channel_notice_fires_its_token_and_the_reference_reads_arg7_and_arg10_bare(
 /// **MODE_CHANGE produces no chat event at all** — not a silent one.
 ///
 /// This test replaced an earlier one that asserted the opposite (that a notice the UI renders
-/// silently still reaches Lua, using MODE_CHANGE as the example). The byte-level carve settled it
+/// silently still reaches Lua, using MODE_CHANGE as the example). The bytes settle it
 /// the other way: `0x49c24d`, the `0x0C` arm of the notice jump table, calls `0x49e910` and
-/// **returns** — it never reaches the fire (wow-re `chat-msg-event-args.md` §9). So the right
+/// **returns** — it never reaches the fire. So the right
 /// behaviour is what our feed already does: drop it before it becomes an event, which is what this
 /// now asserts.
 #[test]
@@ -677,7 +677,7 @@ fn a_mode_change_notice_never_becomes_an_event() {
 
 /// A channel line whose channel we are **not** in leaves all four channel slots empty — arg4 falls
 /// back to the bare name and arg7/arg8/arg9 stay `0/0/""`. They are one record in the reference
-/// (`slot+0x00/+0x04/+0x94/+0x98`), so they are one record here (`chat-msg-event-args.md` §§4, 7-10).
+/// (`slot+0x00/+0x04/+0x94/+0x98`, defaulted together at `0x49b12f`), so they are one record here.
 #[test]
 fn a_channel_we_are_not_in_fires_the_bare_name_and_zeroes() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -781,7 +781,7 @@ fn a_channel_notice_renders_in_the_channels_color_not_the_notice_row() {
 /// **Crossing a zone border must not deregister the channel it renames** (decision 2130).
 ///
 /// The walk sends `LEAVE(General - Elwynn Forest)` then `JOIN(General - Westfall)` — one DBC row,
-/// renamed, and the retail sniff in wow-re `zone-chat-channel-autojoin.md` §7 shows exactly that
+/// renamed, and the retail 1.8.1 Winterspring sniff shows exactly that
 /// pair on the wire. The server answers each with a notice, and the stock `ChatFrame_OnEvent`'s
 /// `YOU_LEFT` arm **deletes the window's registration for whatever it matched**
 /// (`ChatFrame.lua` l.1382-1384):
@@ -910,7 +910,7 @@ fn a_zone_change_must_not_deregister_the_channel_it_renames() {
 /// **Walking out of a capital SUSPENDS Trade — it does not free it** (decision 2130).
 ///
 /// The zone walk's other leave: a row that stops applying entirely, which in the 1.12 data means
-/// exactly `Trade` when you step out of a city (wow-re `zone-chat-channel-autojoin.md` §5). The
+/// exactly `Trade` when you step out of a city (the city gate `0x49a3b8`). The
 /// `CMSG_LEAVE_CHANNEL` still goes out, but the client marks its own slot state 3 (`0x49bcf0`) and
 /// keeps the record — so the notice comes back as the `SUSPENDED` token, the stock handler's
 /// `YOU_LEFT` arm never runs, and the window keeps its registration. Walking back in re-joins
@@ -1797,7 +1797,7 @@ fn self_controlled_is_true_for_an_ordinary_player() {
 }
 
 // ── The send-side posture-eligibility gate (`emote_send_eligible`) — the director-verified rows
-// from wow-re `emote-posture-gate.md` §3, real `Emotes.dbc` `EmoteFlags` values.
+// against `CheckEmoteEligible 0x47db40`, real `Emotes.dbc` `EmoteFlags` values.
 const BOW: u32 = 0x4801;
 const RUDE: u32 = 0x0001;
 const APPLAUD: u32 = 0x0000;
@@ -1864,8 +1864,8 @@ fn unconditional_and_sleep_dead_rules() {
 ///
 /// `CHAT_MSG_ADDON` (event 227) carries `(prefix, message, distribution, sender)`. The text divides
 /// on its **FIRST** tab (`0x49a8d0`) — and with **no tab at all the whole text is the PREFIX** with
-/// an empty message, not the reverse. wow-re records that direction explicitly because it is the
-/// counter-intuitive one; this test is where it is pinned.
+/// an empty message, not the reverse. That direction is the counter-intuitive one; this test is
+/// where it is pinned.
 ///
 /// `distribution` is the remap at `0x49aff4`: only the four lanes have names, and anything else
 /// reports `"UNKNOWN"` rather than being dropped — the reference hands the addon a string it can
@@ -1917,7 +1917,7 @@ fn an_inbound_addon_line_splits_on_the_first_tab_only() {
 /// silently wrong — an addon reading `arg3` as the sender instead of the distribution gets a string
 /// either way and misbehaves without erroring.
 ///
-/// wow-re carves the shape as `SignalEvent2(227, "%s%s%s%s", prefix, message, distribution, sender)`
+/// The reference fires `SignalEvent2(227, "%s%s%s%s", prefix, message, distribution, sender)`
 /// (`0x49a95f`); `BigWigs` self-delivers the identical order by hand. The handler below records all
 /// four positionally, so a reordering fails on the values rather than on a count.
 #[test]
@@ -2019,7 +2019,7 @@ fn an_addon_message_survives_its_own_send_and_receive() {
 ///
 /// `ChatFrame.lua`'s test is `strlen(arg3) > 0 and arg3 ~= "Universal" and arg3 ~= this.defaultLanguage`,
 /// and `GetDefaultLanguage()` answers the **faction** language — Common for every Alliance race,
-/// Orcish for every Horde one (wow-re `chat-language-scramble.md` §12, and benilla's own
+/// Orcish for every Horde one (`0x5ec890`, and benilla's own
 /// `ChrRaces` field-8 join). The composer hardcoded `"Common"`, which is right for half the game
 /// and exactly backwards for the other half: a Horde character saw `[Orcish]` on every ordinary
 /// line of their own faction's chat, and no tag at all on the Common they cannot read.
@@ -2083,8 +2083,7 @@ fn the_language_header_suppresses_only_the_frames_own_default_tongue() {
 /// language-independent, and a Horde player yelling `lol` laughs for every observer, Alliance
 /// included.
 ///
-/// This is byte-verified rather than reasoned (wow-re `chat-language-scramble.md` §10.1), and it
-/// corrects an inference we had already wired: the §5's consumer census of the display path
+/// This corrects an inference we had already wired: the consumer census of the display path
 /// `0x49a870` found the chat line, the Lua `arg1` and the bubble all sharing the rewritten buffer,
 /// and we concluded the gesture did too. It does not — the selector is not on that path at all. It
 /// lives in the **parser** `0x49d560` at `0x49d820`-`0x49d8ae`, matching against `[ebp-0x10]`, which
@@ -2798,8 +2797,8 @@ fn the_chat_cache_restore_is_finished_before_player_login() {
         "ChatFrame1 must carry the SYSTEM message group at PLAYER_LOGIN, not {:?}",
         read("ChatOrderProbe.loginRegistered")
     );
-    // The reference's own login order, byte-derived (wow-re `login-chat-colour-pipeline.md`;
-    // decision 2125): addons and their `ADDON_LOADED` (`0x4900a3`), then `VARIABLES_LOADED`
+    // The reference's own login order (decision 2125): addons and their `ADDON_LOADED`
+    // (`0x4900a3`), then `VARIABLES_LOADED`
     // (`0x4900b2`), then the chat-cache reader's burst (`0x4900d6`), then `PLAYER_LOGIN`
     // (`0x490959`). 2119 put the burst ahead of `VARIABLES_LOADED`, one step too early.
     assert_eq!(
diff --git a/crates/benilla-app/src/ui_craft.rs b/crates/benilla-app/src/ui_craft.rs
index 7c3de858..7a6f0ee4 100644
--- a/crates/benilla-app/src/ui_craft.rs
+++ b/crates/benilla-app/src/ui_craft.rs
@@ -9,7 +9,7 @@
 //! item-targeted cast (`SPELL_EFFECT_ENCHANT_ITEM`/`_TEMPORARY`, `Targets = 0x10`). Since
 //! decision 0923 this window owns none of that machinery — `DoCraft` goes down the ONE cast
 //! ladder like every other caster surface, and the resolver's item arm raises the ONE targeting
-//! cursor, which the bag and paper-doll click seams complete ([`crate::ui_action::targeting`]).
+//! cursor, which the bag and paper-doll click seams complete ([`crate::spell::targeting`]).
 //! The private `PendingItemCast` this file used to carry — a second targeting state with its own
 //! arm, its own bag-click completion and its own cursor overlay, bypassing every ladder rung
 //! including the reagent check an enchant most needs — is gone.
@@ -24,12 +24,14 @@ use benilla_formats::{
     SPELL_EFFECT_ENCHANT_ITEM_TEMPORARY, SPELL_EFFECT_LEARN_SPELL,
 };
 use benilla_protocol::messages::PLAYER_SKILL_SLOTS;
+use benilla_protocol::{SessionEvent, SessionEventKind};
 use benilla_ui::script::{CraftReagent, CraftRecipe, CraftState, CraftTooltip, UiScript};
 
 use crate::entities::ItemDisplays;
 use crate::items::Items;
-use crate::net::{NetCommands, ObjectStore, SelfPlayer};
-use crate::ui_action::{cast_target, CastCommit, CastLadder, PlayerActions, Spells};
+use crate::net::{NetCommands, NetHandlerApp, ObjectStore, Objects, SelfPlayer};
+use crate::spell::{cast_target, CastCommit, CastLadder};
+use crate::ui_action::{PlayerActions, Spells};
 use crate::ui_items::{count_of, item_icon, InventoryScope};
 use crate::ui_script::UiInput;
 use crate::ui_spellbook::SkillLines;
@@ -39,14 +41,16 @@ use crate::ui_unit::UnitFeed;
 // NOTE on the admission filter below: Craft recipes (enchants, the rod crafts) do NOT carry
 // `SPELL_ATTR_IS_TRADESKILL` — they carry **`castUI != 0`** instead (pinned on the live 5875 data:
 // 7418/7421 castUI=3, attributes bare 0x10000; exactly the spellbook add-gate's third exclusion
-// leg). INTERIM admission pending a wow-re detail pass: a known spell joins the craft list when its
+// leg). INTERIM admission, unconfirmed in the binary: a known spell joins the craft list when its
 // SLA line matches AND (`castUI != 0` OR the tradeskill bit) and it is not an opener.
 
 /// The open Craft window: the skill line whose recipes it lists (`None` = closed) and the **craft
-/// type** that opened it. Routed here by the opener's `EffectMiscValue[0] != 0` (byte-VERIFIED —
-/// wow-re `tradeskill` TU-A); that same misc value *is* the craft type (1 Beast Training ·
+/// type** that opened it. Routed here by the opener's `EffectMiscValue[0] != 0`
+/// (`Spell_C::TryCast 0x6e4b60`); that same misc value *is* the craft type (1 Beast Training ·
 /// 3 Enchanting), which the client keeps at `ds:0xbdcfb8` and reads for both the window's admission
-/// filter and its row comparator (decision 1124). Client-local state, no wire.
+/// filter and its row comparator (decision 1124). Client-local state, no wire. Cleared by the Lua
+/// close and by the session end ([`on_session_end`]) — a logout's fresh VM never runs the old one's
+/// `OnHide`, so the close alone would carry the window into the next login.
 #[derive(Resource, Default)]
 pub(crate) struct CraftOpen {
     pub(crate) line: Option<u32>,
@@ -57,6 +61,7 @@ pub(crate) struct UiCraftPlugin;
 
 impl Plugin for UiCraftPlugin {
     fn build(&self, app: &mut App) {
+        app.net_handler(SessionEventKind::Disconnected, on_session_end);
         app.init_resource::<CraftOpen>().add_systems(
             Update,
             (feed_craft.in_set(UnitFeed), drain_craft.after(UiInput)),
@@ -64,9 +69,15 @@ impl Plugin for UiCraftPlugin {
     }
 }
 
+/// The Craft window dies with the session — a listener on the session end (a second handler on
+/// the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut open: ResMut<CraftOpen>) {
+    *open = CraftOpen::default();
+}
+
 /// The line's `(rank, max, bonus)` off the skill block — the Craft window bands difficulty on
-/// the EFFECTIVE skill (rank + bonuses), byte-VERIFIED unlike the TradeSkill window's raw rank
-/// (wow-re `tradeskill` TU-C).
+/// the EFFECTIVE skill (rank + bonuses, `0x5ea520` in the Craft build `0x4f60c0`), unlike the
+/// TradeSkill window's raw rank.
 fn skill_rank(store: &ObjectStore, skill_id: u32) -> (u32, u32, i32) {
     for i in 0..PLAYER_SKILL_SLOTS {
         if let Some(s) = store.0.player_skill(i) {
@@ -82,9 +93,8 @@ fn skill_rank(store: &ObjectStore, skill_id: u32) -> (u32, u32, i32) {
     (0, 0, 0)
 }
 
-/// **Law D** — the Craft window's row icon, transcribing `GetCraftIcon 0x4f7160` (byte-VERIFIED;
-/// wow-re `ui/scratch/spell-icon-substitution-law.md` §2, folded back by decision 1107): **always**
-/// this recipe's own `SpellIconID`, straight off `Spell.dbc`.
+/// **Law D** — the Craft window's row icon, transcribing `GetCraftIcon 0x4f7160` (decision 1107):
+/// **always** this recipe's own `SpellIconID`, straight off `Spell.dbc`.
 ///
 /// The one-liner is the point, and it is not an oversight to be "improved". The Craft window and
 /// the TradeSkill window are two translation units of the *same* node, and their icon laws are
@@ -97,10 +107,9 @@ fn craft_icon(d: &benilla_formats::SpellDisplay) -> Option<String> {
     d.icon.clone()
 }
 
-/// The Craft window's **tooltip law** — `SetCraftSpell 0x533e90`, byte-verified in wow-re
-/// (`ui/scratch/trainer-service-tooltip-law.md` §4.1). Like the trainer's, the binding is a
-/// selector into the two shared builders and emits no line of its own; unlike the trainer's, it
-/// reads the **recipe's own** effect columns:
+/// The Craft window's **tooltip law** — `SetCraftSpell 0x533e90`. Like the trainer's, the binding
+/// is a selector into the two shared builders and emits no line of its own; unlike the trainer's,
+/// it reads the **recipe's own** effect columns:
 ///
 /// ```text
 /// for i in 0..3:
@@ -137,6 +146,7 @@ fn feed_craft(
     focus: Option<Res<SpellFocus>>,
     icons: Option<Res<ItemDisplays>>,
     self_store: Query<&ObjectStore, With<SelfPlayer>>,
+    objects: Objects,
     items: Res<Items>,
     commands: Res<NetCommands>,
     mut last: Local<crate::ui_script::VmMemo<Option<CraftState>>>,
@@ -191,9 +201,9 @@ fn feed_craft(
                 let mut reagents = Vec::new();
                 let mut num_available = u32::MAX;
                 for &(entry, need) in d.reagents.iter().filter(|&&(e, n)| e != 0 && n != 0) {
-                    let have = count_of(&store.0, &items, entry, InventoryScope::CARRIED);
+                    let have = count_of(&store.0, &objects, entry, InventoryScope::CARRIED);
                     // A reagent is an ITEM row, so it terminates in the one genuinely shared chain
-                    // (wow-re §5): ItemTemplate → ItemDisplayInfo → icon. Unlike the *recipe* icon
+                    // (`0x5d88b0`): ItemTemplate → ItemDisplayInfo → icon. Unlike the *recipe* icon
                     // above, there is nothing per-binding about this one.
                     let (name, icon) = match items.template(entry, 0, &commands) {
                         Some(t) => (
@@ -215,10 +225,9 @@ fn feed_craft(
                     num_available = 0;
                 }
                 // **Focus first, then the totems** — `0x4ff980`'s own push order, and
-                // `GetCraftSpellFocus 0x4f78b0` returns the very same pair list despite its name
-                // (wow-re `tradeskill-tools-and-spell-focus.md`). The focus's flag is the literal
-                // `1.0` with no predicate: the reference never reddens it. See
-                // [`crate::ui_tradeskill`]'s twin, where the law is written out.
+                // `GetCraftSpellFocus 0x4f78b0` returns the very same pair list despite its name.
+                // The focus's flag is the literal `1.0` with no predicate: the reference never
+                // reddens it. See [`crate::ui_tradeskill`]'s twin, where the law is written out.
                 let mut tools = Vec::new();
                 if d.requires_spell_focus != 0 {
                     if let Some(n) = focus
@@ -229,7 +238,7 @@ fn feed_craft(
                     }
                 }
                 for &t in d.totems.iter().filter(|&&t| t != 0) {
-                    let have = count_of(&store.0, &items, t, InventoryScope::CARRIED) > 0;
+                    let have = count_of(&store.0, &objects, t, InventoryScope::CARRIED) > 0;
                     if let Some(info) = items.template(t, 0, &commands) {
                         tools.push((info.name.clone(), have));
                     }
@@ -309,7 +318,7 @@ fn feed_craft(
 
 /// Drain the Lua intents: every `DoCraft` goes down the ONE cast ladder, and the resolver decides
 /// what happens next — an enchant's `Targets = 0x10` word arms the targeting cursor's item half
-/// (decision 0923; the bag / paper-doll click completes it, in `ui_action::targeting`), a rod
+/// (decision 0923; the bag / paper-doll click completes it, in `spell::targeting`), a rod
 /// craft's zero word commits immediately. `CloseCraft` closes the window; a pick armed by it is
 /// the one targeting word, cancelled the ordinary ways (ESC, right-click, a new cast).
 ///
@@ -400,4 +409,29 @@ mod tests {
         teacher.effect_trigger_spell[1] = 999_999;
         assert_eq!(craft_tooltip(5149, &teacher), CraftTooltip::Spell(999_999));
     }
+
+    /// **The Craft window dies with the session** — the TradeSkill book's twin: only `CloseCraft`
+    /// cleared it, and a logout's fresh VM never runs the old one's `OnHide`, so the next login
+    /// fired `CRAFT_SHOW` into the new character's UI.
+    #[test]
+    fn the_session_end_closes_the_craft_window() {
+        let mut app = App::new();
+        app.add_plugins(UiCraftPlugin);
+        {
+            let mut open = app.world_mut().resource_mut::<CraftOpen>();
+            open.line = Some(333);
+            open.craft_type = 3;
+        }
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![benilla_protocol::SessionEvent::Disconnected {
+                reason: "socket".into(),
+                end: benilla_protocol::SessionEnd::Lost,
+            }],
+        );
+
+        let open = app.world().resource::<CraftOpen>();
+        assert_eq!((open.line, open.craft_type), (None, 0));
+    }
 }
diff --git a/crates/benilla-app/src/ui_dialog_verbs.rs b/crates/benilla-app/src/ui_dialog_verbs.rs
index 214a64bb..4295e556 100644
--- a/crates/benilla-app/src/ui_dialog_verbs.rs
+++ b/crates/benilla-app/src/ui_dialog_verbs.rs
@@ -1,6 +1,6 @@
 //! The dialog engine's verbs, app half (decision 1963): the feeds behind the stock
 //! `StaticPopup.lua` dialogs benilla never raised and the drains behind their buttons, each to
-//! wow-re's `staticpopup-dialog-bindings.md` (VERIFIED at the bytes unless a line says INFERRED).
+//! the reference's bytes unless a line says INFERRED.
 //!
 //! * **Pet trainer** — `SMSG_PET_UNLEARN_CONFIRM {guid, cost}` latches both and owes
 //!   `CONFIRM_PET_UNLEARN(cost)`; `ConfirmPetUnlearn()` answers with `CMSG_PET_UNLEARN {guid}` unless
@@ -22,10 +22,10 @@
 //! * **Battlefield queue** — `SMSG_BATTLEFIELD_STATUS` fills one of three slots and fires
 //!   `UPDATE_BATTLEFIELD_STATUS`; `AcceptBattlefieldPort(index, accept)` sends the slot's map id
 //!   with the answer as one byte.
-//! * **Meeting stone** (wow-re `meeting-stone-status.md`, 1974) — two globals: the queued area
+//! * **Meeting stone** (1974) — two globals: the queued area
 //!   (`[0xb72038]`) and the cached status text (`[0xb7203c]`). `SMSG 0x295 {areaId, status}`
 //!   latches the old area, stores the new one unconditionally, prints one of five chat lines by
-//!   the status byte (with the two asymmetries §8 records: status 0 names the OLD area and is
+//!   the status byte (with `0x4ca230`'s two asymmetries: status 0 names the OLD area and is
 //!   silent when it has no row; status 1 is skipped entirely when the area did not change, names
 //!   the NEW one with an `UNKNOWN` fallback, and plays the `HARDCODED Meeting Stone Join` visual
 //!   on the player), then — on EVERY path, an out-of-range status included — rebuilds the text
@@ -124,7 +124,7 @@ impl InstanceBoot {
 }
 
 /// `SPIRITGUIDE` — `UNIT_NPC_FLAGS` bit 6, the flag the acquire callback `0x4924c0` tests at
-/// `0x4924fc shr eax,0x6; test al,1` (wow-re `interact-dead-fork-and-npc-service-ladder.md` §C).
+/// `0x4924fc shr eax,0x6; test al,1`.
 const NPC_FLAG_SPIRITGUIDE: u32 = 1 << 6;
 
 /// The area spirit healer's aura, `0xA18` = 2584 — the one spell `0x4921c0`'s cancel leg and
@@ -158,11 +158,9 @@ pub(crate) struct SetHealerOutcome {
 /// The current-area spirit healer (`[0xb4e330/334]`) and its wave clock (`[0xb4e338]`).
 ///
 /// **The writer is [`Self::set_healer`], and it is the reference's `0x4921c0` to the branch.**
-/// 1963 shipped this resource with the note "no writer yet" because the acquire side was thought
-/// to be uncarved; it is not — wow-re recorded the whole trio, in two different nodes, before that
-/// record landed (`ui/scratch/staticpopup-dialog-bindings.md` §6 for the setter and the poll's
-/// radii, `object-layer/scratch/interact-dead-fork-and-npc-service-ladder.md` §C row 6 for the
-/// click arm). Both roads in are built here.
+/// 1963 shipped this resource with the note "no writer yet"; the reference has the whole acquire
+/// trio: the setter, the poll `0x4923b0` with its radii, and the click arm `0x5df950`. Both roads
+/// in are built here.
 #[derive(Resource, Default)]
 pub(crate) struct AreaSpiritHealer {
     /// The cached healer (`[0xb4e330/334]`), written only by [`Self::set_healer`].
@@ -243,22 +241,24 @@ impl AreaSpiritHealer {
 }
 
 /// The three battleground queue slots (`0xb6e9d0`, stride `0x20`), each with the moment its
-/// status landed — the clock every stamp in the slot is relative to.
+/// status landed — the clock every stamp in the slot is relative to. Kept across an in-session
+/// world enter (`0x4a9db0`); zeroed whole at the session end, as the reference's module init
+/// zeroes it at every login (`net::on_session_end`).
 #[derive(Resource, Default)]
 pub(crate) struct BattlefieldQueue {
     slots: [Option<(BattlefieldStatus, Instant)>; 3],
     changed: bool,
     /// The slot the player is IN (`[0x8457cc]`, the status-3 arm) and its map.
     active: Option<(usize, u32)>,
-    /// The instance's two clocks (`[0xb6ebbc]`/`[0xb6ebb8]`, wow-re `battlefield-verb-family.md`
-    /// §4.2): the run-time stamp `now − Δ₂` and the expiration `now + Δ₁`, set by a status-3
-    /// message and zeroed by ANY non-clearing message of another status — whatever slot it is
-    /// about (§10's anomaly 4, reproduced: 1972 zeroed them only for the active slot; 1974
-    /// corrects it to the handler's unconditional clear).
+    /// The instance's two clocks (`[0xb6ebbc]`/`[0xb6ebb8]`): the run-time stamp `now − Δ₂` and
+    /// the expiration `now + Δ₁`, set by a status-3 message and zeroed by ANY non-clearing message
+    /// of another status — whatever slot it is about (an anomaly of the handler `0x4aa850`,
+    /// reproduced: 1972 zeroed them only for the active slot; 1974 corrects it to the handler's
+    /// unconditional clear).
     run_started: Option<Instant>,
     instance_expiration: Option<Instant>,
     /// The status-3 arm rebuilds the scoreboard and fires `UPDATE_BATTLEFIELD_SCORE` before
-    /// `UPDATE_BATTLEFIELD_STATUS` (§4.2's ordering) — the score feed reads this first.
+    /// `UPDATE_BATTLEFIELD_STATUS` (`0x4aaa5a`, then `0x4aab05`) — the score feed reads this first.
     score_dirty: bool,
     /// The handler's two tutorial arms (`0x2f` on queued, `0x30` on confirm; 1976), owed to the
     /// tutorial system on the next feed.
@@ -266,8 +266,8 @@ pub(crate) struct BattlefieldQueue {
 }
 
 impl BattlefieldQueue {
-    /// `SMSG_BATTLEFIELD_STATUS` (§4.2): an out-of-range slot abandons the message; a zero map
-    /// takes the clear arm (the slot emptied, the instance clocks zeroed only when this was the
+    /// `SMSG_BATTLEFIELD_STATUS` (`0x4aa850`): an out-of-range slot abandons the message; a zero
+    /// map takes the clear arm (the slot emptied, the instance clocks zeroed only when this was the
     /// active slot — and the active index itself left alone, as the handler leaves `[0x8457cc]`);
     /// status 3 stamps the instance clocks and names the slot active; every other status zeroes
     /// the instance clocks unconditionally and un-names the slot if it was the active one.
@@ -451,9 +451,9 @@ fn build_stone_text(script: &UiScript, areas: Option<&AreaTableRes>, area: u32)
     text
 }
 
-/// The `0x295` handler's five-way table (§8), as the line it prints for `(old, new, status)` —
-/// `None` where the reference prints nothing: status 0 with no row for the OLD area, status 1
-/// with an unchanged area, and any status past 4.
+/// The `0x295` handler's five-way table (`0x4ca3a4`), as the line it prints for
+/// `(old, new, status)` — `None` where the reference prints nothing: status 0 with no row for the
+/// OLD area, status 1 with an unchanged area, and any status past 4.
 fn stone_line(
     script: &UiScript,
     areas: Option<&AreaTableRes>,
@@ -616,7 +616,7 @@ fn feed_meeting_stone(
 /// round trip during which the icon is genuinely absent is faithful, not a defect: the reference
 /// has the same gap, because only the server's reply fires the event.
 ///
-/// The queued area itself is untouched here, matching `[0xb72038]`, which the RE round found is
+/// The queued area itself is untouched here, matching `[0xb72038]`, which is
 /// referenced six times image-wide and by nothing in either reload closure — it survives, and
 /// [`MeetingStone::enter_world`]'s `dirty` is what re-pushes it to the fresh VM.
 fn meeting_stone_enter_world(
@@ -664,9 +664,7 @@ pub(crate) enum StoneJoin {
 }
 
 /// The four client-side refusals inside MEETINGSTONE(23)'s own use slot (`0x5f69d0`, whose tail
-/// `0x5f6af6` is the sole caller of the `CMSG 0x292` builder `0x4c9ff0`) — **VERIFIED at the
-/// bytes** by wow-re's §5 round on that function (four cold workers plus the orchestrator's own
-/// derivation, arbitrated; `system/object-layer/scratch/meeting-stone-use-validator.md` §4).
+/// `0x5f6af6` is the sole caller of the `CMSG 0x292` builder `0x4c9ff0`).
 ///
 /// Two gates run before any of them. `0x5f69f8`: no local player ⇒ [`StoneJoin::Silent`].
 /// `0x5f6a10 je 0x5f6a65`: **not in a group ⇒ both group refusals are skipped**, and a solo player
@@ -1078,10 +1076,90 @@ fn poll_area_spirit_healer(
     }
 }
 
+/// The dialog verbs' packet handlers (in the net handler table since 2313) — each parks a
+/// question or a countdown on its own store for the feed to turn into a StaticPopup.
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::{AreaSpiritHealer, BattlefieldQueue, InstanceBoot, MeetingStone, PetUnlearnState};
+    use crate::net::NetHandlerApp;
+
+    /// Register the handlers — called from [`super::UiDialogVerbsPlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::PetUnlearnConfirm, on_pet_unlearn_confirm)
+            .net_handler(K::RaidGroupOnly, on_raid_group_only)
+            .net_handler(K::AreaSpiritHealerTime, on_area_spirit_healer_time)
+            .net_handler(K::BattlefieldStatus, on_battlefield_status)
+            .net_handler(K::MeetingStoneSetQueue, on_meeting_stone)
+            .net_handler(K::MeetingStoneNotice, on_meeting_stone)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    /// The battleground queue is zeroed at every login (module init `0x4a9c40`, from
+    /// `InitializeGame` — the three slots, `[0x8457cc] = -1`, the
+    /// scalars), and vmangos never sends a clear for the queue of a player who logged out. A
+    /// listener on the session end (a second handler on the kind, after the bridge's own
+    /// teardown). The in-session world enter (`0x4a9db0`) is a different edge that KEEPS the slots,
+    /// and it does not come through here.
+    fn on_session_end(In(_): In<SessionEvent>, mut queue: ResMut<BattlefieldQueue>) {
+        *queue = BattlefieldQueue::default();
+    }
+
+    /// The pet trainer's question (decision 1963) — the talent wipe's twin
+    /// ([`crate::ui_talent_wipe`]); a zero guid is the reference's own `ERR_TALENT_WIPE_ERROR`
+    /// leg, carried over as observed.
+    fn on_pet_unlearn_confirm(
+        In(ev): In<SessionEvent>,
+        mut unlearn: ResMut<PetUnlearnState>,
+        mut errors: ResMut<crate::ui_action::UiErrorKeys>,
+    ) {
+        if let SessionEvent::PetUnlearnConfirm { trainer, cost } = ev {
+            if trainer == 0 {
+                debug!("net: pet unlearn refused (zero trainer) — no dialog");
+                errors
+                    .0
+                    .push(crate::ui_action::UiError::key("ERR_TALENT_WIPE_ERROR"));
+            } else {
+                debug!("net: trainer {trainer:#x} asks to unlearn the pet for {cost} copper");
+                unlearn.ask(trainer, cost);
+            }
+        }
+    }
+
+    fn on_raid_group_only(In(ev): In<SessionEvent>, mut boot: ResMut<InstanceBoot>) {
+        if let SessionEvent::RaidGroupOnly { delay_ms, reason } = ev {
+            boot.apply(delay_ms, reason, std::time::Instant::now());
+        }
+    }
+
+    fn on_area_spirit_healer_time(In(ev): In<SessionEvent>, mut spirit: ResMut<AreaSpiritHealer>) {
+        if let SessionEvent::AreaSpiritHealerTime { healer, ms } = ev {
+            spirit.on_time(healer, ms, std::time::Instant::now());
+        }
+    }
+
+    fn on_battlefield_status(In(ev): In<SessionEvent>, mut queue: ResMut<BattlefieldQueue>) {
+        if let SessionEvent::BattlefieldStatus(status) = ev {
+            queue.apply(status);
+        }
+    }
+
+    fn on_meeting_stone(In(ev): In<SessionEvent>, mut stone: ResMut<MeetingStone>) {
+        match ev {
+            SessionEvent::MeetingStoneSetQueue { area, status } => stone.apply(area, status),
+            SessionEvent::MeetingStoneNotice(notice) => stone.apply_notice(notice),
+            _ => {}
+        }
+    }
+}
+
 pub(crate) struct UiDialogVerbsPlugin;
 
 impl Plugin for UiDialogVerbsPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<PetUnlearnState>()
             .init_resource::<InstanceBoot>()
             .init_resource::<AreaSpiritHealer>()
@@ -1187,8 +1265,8 @@ impl Plugin for UiDialogVerbsPlugin {
 #[cfg(test)]
 const AREA_SPIRIT_HEALER_SPELL: u32 = AREA_SPIRIT_HEALER_AURA;
 
-/// The generic cancel-aura routine's refusal (`0x6e7040`, wow-re `staticpopup-dialog-bindings.md`
-/// §6): it returns without sending when the spell's `AttributesEx` has bit 13 set and bit 2
+/// The generic cancel-aura routine's refusal (`0x6e7040`): it returns without sending when the
+/// spell's `AttributesEx` has bit 13 set and bit 2
 /// clear **and** `0x5ee290(player)` holds. Whether the third leg ever matters for spell 2584 is
 /// decided by the first two, read off the shipped Spell.dbc in [`tests::spell_2584_never_trips_the_cancel_gate`].
 #[cfg(test)]
@@ -1593,7 +1671,7 @@ mod tests {
         // **An unanswered template refuses**, because `0x5f8150` reads `0/0` off an uncached
         // object and every level >= 1 is outside `0..=0`. The permissive "skip the term while the
         // query is in flight" default the highlight column takes is not this slot's — the first
-        // cut of this code had it, and the §5 round is what corrected it.
+        // cut of this code had it.
         assert_eq!(
             meeting_stone_join_refusal(None, Some(ME), Some(5), None),
             StoneJoin::Refuse("ERR_MEETING_STONE_INVALID_LEVEL")
@@ -1697,17 +1775,12 @@ mod tests {
     /// **The `/reload` re-query** — the meeting-stone half of 1290's class, and the reference's
     /// own behaviour rather than an invention of ours.
     ///
-    /// wow-re's §5 trio (3/3 unanimous, every byte re-decoded from the raw image) settled that
-    /// the run-once byte `[0xb4b424]` is cleared by the UI teardown at `0x490a8d` and that
+    /// The run-once byte `[0xb4b424]` is cleared by the UI teardown at `0x490a8d`, and
     /// `UI_Init` re-runs the bring-up and re-sends `CMSG 0x296`. So the gate is once per **VM**,
     /// not once per world session — and against the old `MessageReader<EnteredWorldMessage>`
     /// shape this fails on the second VM, which is exactly the reported symptom: the queued
     /// player's minimap icon never comes back after a `/reload`.
     ///
-    /// It also corrects wow-re's own `meeting-stone-status.md` §6, which asserted the query "is
-    /// sent exactly once per world session … has no other trigger" — true of the entry points it
-    /// enumerated, but it never asked who *clears* the byte.
-    ///
     /// **A registered schedule, not `run_system_once`**: the gate is a `Local<VmMemo<bool>>`, and
     /// `run_system_once` builds a fresh system — and so a fresh `Local` — on every call, which
     /// would make the claim look unclaimed every frame (the same trap `ui_loot`'s tests name).
@@ -1774,7 +1847,7 @@ mod tests {
             .expect("spell 2584 in Spell.dbc");
         assert!(
             !cancel_gate_could_apply(ex),
-            "spell 2584 AttributesEx = {ex:#x}: the gate's third leg would decide, and it is uncarved"
+            "spell 2584 AttributesEx = {ex:#x}: the gate's third leg would decide, and it is open"
         );
     }
 
@@ -1838,8 +1911,8 @@ mod tests {
         assert_eq!(q.map_id(2), None, "a zero map clears the slot");
     }
 
-    /// The instance clocks (§4.2): stamped by status 3, zeroed by any other status of ANY slot,
-    /// and by a clear of the active slot only — which leaves the active index alone.
+    /// The instance clocks (`0x4aa850`): stamped by status 3, zeroed by any other status of ANY
+    /// slot, and by a clear of the active slot only — which leaves the active index alone.
     #[test]
     fn the_instance_clocks_follow_the_status_handler() {
         let mut q = BattlefieldQueue::default();
@@ -1991,4 +2064,65 @@ mod tests {
         assert_eq!(pet.pending(), None);
         assert_eq!(pet.cost, 0);
     }
+
+    /// **The queue is zeroed at every login, not kept across it**: module init `0x4a9c40`, run
+    /// from `InitializeGame`, zeroes the three slots, the active index (`[0x8457cc] = -1`) and the
+    /// scalars, and vmangos never sends a clear for a queue whose player logged out. So a slot,
+    /// the active map and the instance clocks from the last session must not reach the next —
+    /// only an in-session world enter (`0x4a9db0`) keeps the slots, and that is
+    /// `ui_battlefield`'s, untouched here.
+    #[test]
+    fn the_session_end_zeroes_the_battlefield_queue() {
+        let mut app = App::new();
+        app.init_resource::<BattlefieldQueue>();
+        net::register(&mut app);
+        let now = Instant::now();
+        {
+            let mut q = app.world_mut().resource_mut::<BattlefieldQueue>();
+            q.apply_at(
+                BattlefieldStatus {
+                    slot: 0,
+                    map_id: 489,
+                    bracket: 0,
+                    instance_id: 3,
+                    status: 3,
+                    time_ms: None,
+                    in_progress: Some((90_000, 30_000)),
+                    queued: None,
+                },
+                now,
+            );
+            q.apply_at(
+                BattlefieldStatus {
+                    slot: 1,
+                    map_id: 30,
+                    bracket: 0,
+                    instance_id: 0,
+                    status: 1,
+                    time_ms: Some(0),
+                    in_progress: None,
+                    queued: None,
+                },
+                now,
+            );
+        }
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![benilla_protocol::SessionEvent::Disconnected {
+                reason: "logged out".into(),
+                end: benilla_protocol::SessionEnd::LoggedOut,
+            }],
+        );
+
+        let mut q = app.world_mut().resource_mut::<BattlefieldQueue>();
+        assert!(
+            q.slots().iter().all(Option::is_none),
+            "all three slots empty"
+        );
+        assert_eq!(q.active_map(), None);
+        assert_eq!(q.run_time_ms(now), 0);
+        assert_eq!(q.instance_expiration_ms(now), 0);
+        assert!(!q.take_score_dirty());
+    }
 }
diff --git a/crates/benilla-app/src/ui_dressup.rs b/crates/benilla-app/src/ui_dressup.rs
index 796a8303..c1787a71 100644
--- a/crates/benilla-app/src/ui_dressup.rs
+++ b/crates/benilla-app/src/ui_dressup.rs
@@ -48,7 +48,7 @@ const LOOK_SLOTS: [u8; 14] = [0, 2, 3, 4, 5, 6, 7, 8, 9, 14, 15, 16, 17, 18];
 const HELD_SLOTS: [usize; 3] = [15, 16, 17];
 
 /// **The dress-up widget has two held lanes, and a ranged weapon takes one of them** (decision
-/// 1076; wow-re `ui/scratch/dressup-model-equipment.md`).
+/// 1076).
 ///
 /// `DressUpModel::TryOn 0x504d90` installs into lane `0x0f` (→ HandRight) or lane `0x10` (→
 /// HandLeft, or the Shield point for a shield) — never a third. `INVTYPE_RANGED` (15, bows) lands
@@ -126,7 +126,7 @@ fn held_lanes(equipment: &mut [CharEnumItem; 19], room: &DressUpRoom) {
 /// evicts.
 ///
 /// **The dual-wield arm is taken as permitted, and that is a stated assumption.** The binary gates
-/// it on a global (`0xc4d770`) whose source wow-re could not identify, and we have no dual-wield
+/// it on a global (`0xc4d770`) whose source is unidentified, and we have no dual-wield
 /// capability streamed to read. Permitted is the conservative direction here: it evicts strictly
 /// less than the alternative, so it can only ever leave the pre-1076 behaviour in place for a
 /// melee pair — while the ranged evictions this record is actually about are unconditional in the
@@ -143,7 +143,7 @@ pub(crate) struct DressUpRoom {
     open: bool,
     /// `Undress()` has stripped the body: the player's own worn pieces are not part of the look
     /// until the next `Dress`. The hands are untouched — the widget clears components bodyslots
-    /// `0..0xb` and no hand lane (wow-re `dressup-model-equipment.md` §5).
+    /// `0..0xb` (`0x504490`) and no hand lane.
     bare: bool,
     /// Resolved substitutions by equipment slot — `(display id, inventory type)`, the same pair the
     /// enum-shaped array carries.
@@ -320,8 +320,7 @@ fn player_look(
         // hidden in the dressing room.** A TRY-ON gates on nothing and previews the helm or cloak
         // regardless — which is the branch above, and the reason this test sits *below* it — and
         // `Dress()` (the Reset button) drops the substitutions and so re-clones back to hidden.
-        // (wow-re `object-layer/scratch/helm-cloak-hide.md` §8, byte-verified; this replaced an
-        // INFERRED guess that the mannequin was unconditional.)
+        // (This replaced an INFERRED guess that the mannequin was unconditional.)
         if (idx == 0 && s.player_hides_helm()) || (idx == 14 && s.player_hides_cloak()) {
             continue;
         }
@@ -470,7 +469,7 @@ mod tests {
     }
 
     /// `DressUpModel:Undress()` strips every worn piece — the player's own and a tried-on one —
-    /// and no hand lane (bodyslots `0..0xb` only, wow-re §5); a later try-on lands on the bare
+    /// and no hand lane (bodyslots `0..0xb` only, `0x504490`); a later try-on lands on the bare
     /// body, and `Dress()` puts the player's own gear back.
     #[test]
     fn undress_strips_the_body_but_not_the_hands_and_a_try_on_lands_on_the_bare_body() {
@@ -727,10 +726,10 @@ mod tests {
     }
 
     /// **The dressing room inherits the equipment-display preferences, and a try-on overrides
-    /// them** (decision 1472; wow-re `object-layer/scratch/helm-cloak-hide.md` §8, byte-verified
-    /// off `DressUpModel::SetUnit 0x476cb0`'s verbatim clone of the live player's display
-    /// pointers). Hidden helm + hidden cloak, so the player's own two pieces are absent from the
-    /// look — and then a tried-on helm shows anyway, because previewing it is the whole feature.
+    /// them** (decision 1472; `DressUpModel::SetUnit 0x476cb0`'s verbatim clone of the live
+    /// player's display pointers). Hidden helm + hidden cloak, so the player's own two pieces are
+    /// absent from the look — and then a tried-on helm shows anyway, because previewing it is the
+    /// whole feature.
     #[test]
     fn a_hidden_helm_stays_hidden_on_the_mannequin_until_one_is_tried_on() {
         let (cmds, _rx) = commands();
diff --git a/crates/benilla-app/src/ui_duel.rs b/crates/benilla-app/src/ui_duel.rs
index 9553505a..0f23e212 100644
--- a/crates/benilla-app/src/ui_duel.rs
+++ b/crates/benilla-app/src/ui_duel.rs
@@ -184,10 +184,96 @@ fn owed_text(line: &OwedLine, get: &dyn Fn(&str) -> Option<String>) -> Option<St
     (!text.is_empty()).then_some(text)
 }
 
-/// The net drain's `SessionEvent::Duel*` arms, factored here so the wire laws live beside the
-/// state they drive. `own` is our own guid.
-pub(crate) mod apply {
+/// The duel's packet handlers (decision 0633; in the net handler table since 2312), beside the
+/// state they drive: the session mirror + the two `DisplayError` lines the handlers emit inline;
+/// the Era events fire off the mirror's edges in [`feed_duel`], and the countdown ticks in its own
+/// system. `own` is our own guid.
+pub(crate) mod net {
     use super::*;
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+
+    use crate::net::NetHandlerApp;
+
+    /// Register the duel's handlers — called from [`UiDuelPlugin`]. One per kind, plus the
+    /// session-end listener.
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::DuelRequested, on_requested)
+            .net_handler(K::DuelOutOfBounds, on_bounds)
+            .net_handler(K::DuelInBounds, on_bounds)
+            .net_handler(K::DuelComplete, on_complete)
+            .net_handler(K::DuelWinner, on_winner)
+            .net_handler(K::DuelCountdown, on_countdown)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    fn on_requested(
+        In(ev): In<SessionEvent>,
+        mut duel: ResMut<DuelState>,
+        mut errors: ResMut<crate::ui_action::UiErrorKeys>,
+        commands: Res<NetCommands>,
+        self_guid: Res<crate::net::SelfGuid>,
+        social: Res<crate::ui_social::SocialState>,
+    ) {
+        if let SessionEvent::DuelRequested {
+            arbiter,
+            challenger,
+        } = ev
+        {
+            requested(
+                &mut duel,
+                &mut errors,
+                &commands,
+                arbiter,
+                challenger,
+                self_guid.0,
+                social.is_ignored(challenger),
+            );
+        }
+    }
+
+    fn on_bounds(In(ev): In<SessionEvent>, mut duel: ResMut<DuelState>) {
+        match ev {
+            SessionEvent::DuelOutOfBounds => bounds(&mut duel, true),
+            SessionEvent::DuelInBounds => bounds(&mut duel, false),
+            _ => {}
+        }
+    }
+
+    fn on_complete(
+        In(ev): In<SessionEvent>,
+        mut duel: ResMut<DuelState>,
+        mut errors: ResMut<crate::ui_action::UiErrorKeys>,
+    ) {
+        if let SessionEvent::DuelComplete { started } = ev {
+            complete(&mut duel, &mut errors, started);
+        }
+    }
+
+    fn on_winner(In(ev): In<SessionEvent>, mut duel: ResMut<DuelState>) {
+        if let SessionEvent::DuelWinner {
+            fled,
+            winner: won,
+            loser,
+        } = ev
+        {
+            winner(&mut duel, fled, &won, &loser);
+        }
+    }
+
+    fn on_countdown(In(ev): In<SessionEvent>, mut duel: ResMut<DuelState>) {
+        if let SessionEvent::DuelCountdown { seconds } = ev {
+            countdown(&mut duel, seconds);
+        }
+    }
+
+    /// A pending challenge, a running duel, and its countdown all die with the socket (decision
+    /// 0633) — the server drops the duel too (`Player::DuelComplete(DUEL_FLED)` on logout), and a
+    /// stale arbiter guid would make the next AcceptDuel echo a dead object. A listener on the
+    /// session end (a second handler on the kind, after the bridge's own teardown).
+    fn on_session_end(In(_): In<SessionEvent>, mut duel: ResMut<DuelState>) {
+        *duel = DuelState::default();
+    }
 
     /// `SMSG_DUEL_REQUESTED` — store the arbiter, and either own the challenge (error line +
     /// immediate accept) or hand the popup to the feed.
@@ -461,6 +547,7 @@ pub(crate) struct UiDuelPlugin;
 
 impl Plugin for UiDuelPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<DuelState>().add_systems(
             Update,
             (
diff --git a/crates/benilla-app/src/ui_gamma.rs b/crates/benilla-app/src/ui_gamma.rs
index 34a7839c..175a7377 100644
--- a/crates/benilla-app/src/ui_gamma.rs
+++ b/crates/benilla-app/src/ui_gamma.rs
@@ -4,8 +4,8 @@
 //! [`ui_quad.wgsl`](shaders/ui_quad.wgsl) composites the UI in gamma bytes, the way the
 //! reference's fixed-function device composites into its 8-bit backbuffer: every tint is a gamma
 //! multiply, every blend is gamma arithmetic clamped at each write, and `alphaMode="ADD"` is the
-//! byte add `dst + texel·α` (EGxBlend 3 = `glBlendFunc(GL_SRC_ALPHA, GL_ONE)`; wow-re
-//! `system/gx/gx.md`, factor tables `0x85c1f8`/`0x85c224`). This node converts that finished gamma
+//! byte add `dst + texel·α` (EGxBlend 3 = `glBlendFunc(GL_SRC_ALPHA, GL_ONE)`;
+//! factor tables `0x85c1f8`/`0x85c224`). This node converts that finished gamma
 //! image to linear ONCE, rendering straight into the swapchain — the camera's output mode is
 //! `Skip`, so there is no output blit (decision 2206, [`benilla_world::final_pass`]) — whose sRGB
 //! write re-encodes it to the exact client byte.
@@ -64,8 +64,7 @@ impl Default for UiGammaLane {
 ///
 /// The reference applies it as an OS **hardware gamma ramp**: its change callback `0x4034d0`
 /// builds `ramp[i] = __ftol(pow(i · 1/255, gamma) · 65535)` at `0x591680` and hands the 3×256 words
-/// to `GDI32!SetDeviceGammaRamp` (wow-re `ffxeffects/scratch/whole-frame-grade-verdict.md` §(a);
-/// the same note proves there is no other whole-frame grade in the client, and that
+/// to `GDI32!SetDeviceGammaRamp` (there is no other whole-frame grade in the client, and
 /// `Brightness`/`Contrast` CVars do not exist in the binary at all). That upload is **skipped
 /// windowed** — `byte[dev+0x20b]` is `CGxFormat +0x07`, which is `gxWindow` — and windowed is every
 /// mode benilla has (1627), so copying the mechanism byte for byte would ship a slider that never
@@ -84,7 +83,7 @@ pub(crate) struct DisplayGamma(pub(crate) f32);
 pub(crate) const DEFAULT_GAMMA: f32 = 1.0;
 
 /// **The clamp is ours, and the reference has none** — `SetGamma(5)` writes `gamma = "-4.000000"`
-/// there with no arm anywhere to catch it (wow-re `ui/scratch/video-options-verbs.md` §3, with
+/// there with no arm anywhere to catch it (`SetGamma 0x4891f0`, with
 /// `baseMip`'s validating callback `0x689090` as the positive control). The reference can afford
 /// that because its ramp is a fullscreen-only OS call a player can escape by alt-tabbing; ours is
 /// the image itself, and `pow(x, 12)` is a black screen with the panel that undoes it somewhere
diff --git a/crates/benilla-app/src/ui_gm_ticket.rs b/crates/benilla-app/src/ui_gm_ticket.rs
index a7fddcf6..070d12af 100644
--- a/crates/benilla-app/src/ui_gm_ticket.rs
+++ b/crates/benilla-app/src/ui_gm_ticket.rs
@@ -34,7 +34,7 @@
 //!
 //! ## What vmangos actually does, and what that costs us
 //!
-//! Verified against `/Users/sam/wre/vmangos-src` (`Handlers/GMTicketHandler.cpp`, `GMTicketMgr.cpp`,
+//! Verified against the vmangos source (`Handlers/GMTicketHandler.cpp`, `GMTicketMgr.cpp`,
 //! `Commands/TicketCommands.cpp`) — four behaviours a client author has to design around:
 //!
 //! 1. **Silence is a legal answer.** Create returns with no packet at all when the queue is off,
@@ -97,8 +97,8 @@ pub(crate) struct GmTicketState {
     /// The last queue status the server reported, and its own answer counter — same idiom, because
     /// `GetGMStatus()` is asked on every window open and the answer is usually unchanged.
     ///
-    /// **`i32`, not `u32`, and that is byte-verified rather than a preference** (wow-re §5, this
-    /// session): the reference copies the field off the wire verbatim at `0x418e95` with no
+    /// **`i32`, not `u32`, and that is byte-exact rather than a preference**: the reference
+    /// copies the field off the wire verbatim at `0x418e95` with no
     /// extension, pushes it unmodified at `0x5e467b`, and hands it to Lua through
     /// `0x704fa6 fild dword` — a **signed** load, with no `cmp`, `test`, clamp or mapping anywhere
     /// between the wire and the event. So `HelpFrame`'s `arg1 == -1` arm is reachable exactly when
@@ -120,11 +120,11 @@ impl GmTicketState {
     /// **The client re-asks for its own ticket whenever a write lands** — the mechanism that makes
     /// the shipped UI's total silence on the three response opcodes correct rather than a gap.
     ///
-    /// Byte-verified in wow-re (§5, this session): `CMSG_GMTICKET_GETTICKET` (`0x211`) has three
-    /// callers, and two of them are *engine* legs reacting to a server push — the `0x206`/`0x208`
-    /// arm on response codes 2 (create-ok) and 4 (update-ok) at `0x5e4479`, and the `0x328` handler
-    /// on body value 1 at `0x5e7932`. **Neither carries an idempotence guard**, so it is one resend
-    /// per qualifying push, which is what this counter models.
+    /// `CMSG_GMTICKET_GETTICKET` (`0x211`) has three callers, and two of them are *engine* legs
+    /// reacting to a server push — the `0x206`/`0x208` arm on response codes 2 (create-ok) and 4
+    /// (update-ok) at `0x5e4479`, and the `0x328` handler on body value 1 at `0x5e7932`. **Neither
+    /// carries an idempotence guard**, so it is one resend per qualifying push, which is what this
+    /// counter models.
     ///
     /// Without it the window would not learn its own ticket exists until the 10-minute poll came
     /// round: file a ticket, and the toast stays dark and the form stays a form for up to ten
@@ -377,10 +377,88 @@ fn load_gm_ticket_dbc(
     }
 }
 
-/// The net drain's arms, beside the state they drive.
-pub(crate) mod apply {
+/// The GM ticket's packet handlers (decision 1673; in the net handler table since 2312), beside
+/// the state they drive.
+pub(crate) mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
     use bevy::prelude::*;
 
+    use crate::net::NetHandlerApp;
+
+    use super::GmTicketState;
+
+    /// Register the ticket's handlers — called from [`super::UiGmTicketPlugin`]. One per kind,
+    /// plus the session-end listener.
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::GmTicket, on_ticket)
+            .net_handler(K::GmTicketSystemStatus, on_system_status)
+            .net_handler(K::GmTicketStatusUpdate, on_status_update)
+            .net_handler(K::GmTicketCreated, on_written)
+            .net_handler(K::GmTicketUpdated, on_written)
+            .net_handler(K::GmTicketDeleted, on_deleted)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    /// The GETTICKET answer — EVERY one, including `None` ("you have no ticket") and including
+    /// an unsolicited one pushed by a GM's `.ticket view`/`escalate`/`complete`: they are
+    /// indistinguishable on the wire and want identical handling.
+    fn on_ticket(In(ev): In<SessionEvent>, mut ticket: ResMut<GmTicketState>) {
+        if let SessionEvent::GmTicket { ticket: answer } = ev {
+            ticket.answer(answer);
+        }
+    }
+
+    fn on_system_status(In(ev): In<SessionEvent>, mut ticket: ResMut<GmTicketState>) {
+        if let SessionEvent::GmTicketSystemStatus { status } = ev {
+            ticket.answer_queue(status);
+        }
+    }
+
+    /// A GM touched the ticket. Value 1 makes the reference re-ask (`0x5e7932`), the same leg
+    /// the create/update success codes take; 2 (closed) and 3 (survey offered) are recorded and
+    /// not acted on — 3 is the survey trigger and that window is deferred. vmangos never sends
+    /// this packet at all, so on our server the handler is dead; cmangos makes it the whole
+    /// notification model, which is why it is parsed rather than dropped.
+    fn on_status_update(In(ev): In<SessionEvent>, mut ticket: ResMut<GmTicketState>) {
+        if let SessionEvent::GmTicketStatusUpdate { status } = ev {
+            status_update(status, &mut ticket);
+        }
+    }
+
+    /// The three response codes have no consumer in the shipped 1.12 UI — no event, no handler.
+    /// Logged so a refusal is visible in a session log rather than silent; the `ERR_TICKET_*`
+    /// display path is still unpinned. Create-ok (2) and update-ok (4) make the ENGINE re-ask
+    /// for the ticket — the reference's own `0x5e4479` arm, and the reason the shipped UI needs
+    /// no handler for either opcode. Without it a filed ticket goes unseen until the 10-minute
+    /// poll.
+    fn on_written(In(ev): In<SessionEvent>, mut ticket: ResMut<GmTicketState>) {
+        match ev {
+            SessionEvent::GmTicketCreated { response } => {
+                write_response("create", response, 2, &mut ticket)
+            }
+            SessionEvent::GmTicketUpdated { response } => {
+                write_response("update", response, 4, &mut ticket)
+            }
+            _ => {}
+        }
+    }
+
+    fn on_deleted(In(ev): In<SessionEvent>) {
+        if let SessionEvent::GmTicketDeleted { response: code } = ev {
+            response("delete", code);
+        }
+    }
+
+    /// The GM ticket is login-scoped (decision 1673), and for a sharper reason than most: the
+    /// ticket belongs to the CHARACTER, and the next login may be a different one. Its answer
+    /// counters go with it, so the first `SMSG_GMTICKET_GETTICKET` of the new session re-fires
+    /// `UPDATE_TICKET` rather than being diffed away against the old character's answer count.
+    /// A listener on the session end (a second handler on the kind, after the bridge's own teardown).
+    fn on_session_end(In(_): In<SessionEvent>, mut ticket: ResMut<GmTicketState>) {
+        ticket.clear_session();
+    }
+
     /// `SMSG_GMTICKET_CREATE` (2 = created) and `SMSG_GMTICKET_UPDATETEXT` (4 = saved) — the two
     /// codes the reference engine answers by **re-asking for the ticket**, at `0x5e4479`.
     ///
@@ -440,6 +518,7 @@ pub(crate) struct UiGmTicketPlugin;
 
 impl Plugin for UiGmTicketPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<GmTicketState>()
             .init_resource::<GmTicketFeedState>()
             .add_systems(
@@ -535,13 +614,13 @@ mod tests {
     #[test]
     fn a_landed_write_makes_the_engine_reask_and_a_refused_one_does_not() {
         let mut state = GmTicketState::default();
-        apply::write_response("create", 2, 2, &mut state);
-        apply::write_response("update", 4, 4, &mut state);
+        net::write_response("create", 2, 2, &mut state);
+        net::write_response("update", 4, 4, &mut state);
         assert_eq!(state.take_reasks(), 2, "one re-ask per landed write");
         assert_eq!(state.take_reasks(), 0, "drained means drained");
 
-        apply::write_response("create", 3, 2, &mut state); // CREATE_ERROR
-        apply::write_response("update", 5, 4, &mut state); // UPDATE_ERROR
+        net::write_response("create", 3, 2, &mut state); // CREATE_ERROR
+        net::write_response("update", 5, 4, &mut state); // UPDATE_ERROR
         assert_eq!(state.take_reasks(), 0, "a refusal has nothing to fetch");
     }
 
diff --git a/crates/benilla-app/src/ui_gossip.rs b/crates/benilla-app/src/ui_gossip/mod.rs
similarity index 96%
rename from crates/benilla-app/src/ui_gossip.rs
rename to crates/benilla-app/src/ui_gossip/mod.rs
index 32c7e830..39ded12a 100644
--- a/crates/benilla-app/src/ui_gossip.rs
+++ b/crates/benilla-app/src/ui_gossip/mod.rs
@@ -15,14 +15,13 @@
 //! to a text id keeps the frame exactly as it was for the query round trip: hidden if it was
 //! hidden (never options over an empty page — B292, decision 1508), and **still painted with the
 //! previous menu if it was open** (a sub-menu's first visit repaints in place when its text lands,
-//! never hides and re-shows the window — decision 1994). Both are the reference's own law,
-//! VERIFIED at the bytes (wow-re `gossip-npctext-law.md` §1/§4): on a cache miss `0x4e2010` sets
-//! its select latch and returns — no greeting write, no event — and its greeting write and
-//! `GOSSIP_SHOW` are adjacent and unconditional on the one success path, so "gossip frame open
-//! with a blank greeting" is not a reachable state, and neither is "gossip frame hidden by a
-//! pending reply". [`GossipState::text_pending`] is the latch; [`feed_gossip`] fires nothing
-//! while it holds; [`GossipState::open_menu`]/[`GossipState::text_arrived`] are the two wire
-//! edges that set and resolve it.
+//! never hides and re-shows the window — decision 1994). Both are the reference's own law: on a
+//! cache miss `0x4e2010` sets its select latch and returns — no greeting write, no event — and its
+//! greeting write and `GOSSIP_SHOW` are adjacent and unconditional on the one success path, so
+//! "gossip frame open with a blank greeting" is not a reachable state, and neither is "gossip frame
+//! hidden by a pending reply". [`GossipState::text_pending`] is the latch; [`feed_gossip`] fires
+//! nothing while it holds; [`GossipState::open_menu`]/[`GossipState::text_arrived`] are the two
+//! wire edges that set and resolve it.
 
 use std::collections::HashMap;
 
@@ -92,7 +91,7 @@ impl GossipState {
         select_greeting(blocks, npc_gender, greeting_roll()).map(str::to_string)
     }
 
-    /// The reference's text-pending latch (`[0xbbb670]`, wow-re `gossip-npctext-law.md` §1): a
+    /// The reference's text-pending latch (`[0xbbb670]`): a
     /// session is latched but its greeting has not resolved — its `CMSG_NPC_TEXT_QUERY` is in
     /// flight, or (`text_id == 0`) was never sent. While it holds, [`feed_gossip`] fires nothing
     /// and both drains refuse every select (decisions 1508, 1994).
@@ -147,7 +146,7 @@ impl GossipState {
     /// Draw the open menu's greeting from its (present) record — or, when the record names no
     /// line for this NPC's gender column, end the interaction: the reference's `missing` path
     /// logs "Missing gossip text!" and fires `GOSSIP_CLOSED` instead of ever opening the frame
-    /// (wow-re `gossip-npctext-law.md` §2). Ours never opened either, so the clear is the whole
+    /// (`0x4e216e`). Ours never opened either, so the clear is the whole
     /// close.
     fn resolve_greeting(&mut self, npc_gender: u8) {
         match self.draw_greeting(self.text_id, npc_gender) {
@@ -189,11 +188,15 @@ impl GossipState {
     }
 }
 
+mod net;
+pub(crate) use net::gossip_complete as end_interaction;
+
 /// The gossip window's feed + drain (decision 0081), cloned from [`crate::ui_items::UiItemsPlugin`].
 pub(crate) struct UiGossipPlugin;
 
 impl Plugin for UiGossipPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<GossipState>().add_systems(
             Update,
             (
@@ -225,8 +228,7 @@ impl NpcSession for GossipState {
 /// the XML resolves to a `Interface\GossipFrame\<Type>GossipIcon` texture.
 ///
 /// **The byte is a bare index into [`GOSSIP_ICON_TYPES`], with no bounds check anywhere on the
-/// client's path** — VERIFIED at the bytes (wow-re `system/ui/scratch/gossip-icon-and-binder-flow.md`,
-/// decision 1335): `GetGossipOptions 0x4e28d0` reads the stored byte and does
+/// client's path** (decision 1335): `GetGossipOptions 0x4e28d0` reads the stored byte and does
 /// `mov edx,[eax*4 + 0x84b7ac]` straight into a 14-entry pointer table, then `lua_pushstring`s it.
 ///
 /// The old map read the byte through **vmangos's `GossipDef.h` enum *names*** (`INTERACT_1`,
@@ -235,7 +237,7 @@ impl NpcSession for GossipState {
 /// entry at all and fell through to the chat bubble, which is the icon half of B249 (decision 1331).
 ///
 /// Two of the reference's out-of-range behaviours we deliberately do **not** reproduce, because
-/// both are its missing guard rather than its design (wow-re's note says so in as many words):
+/// both are its missing guard rather than its design:
 /// index **14** is a NULL in the table, so the reference pushes `nil` as the option's type and the
 /// row draws whatever the XML's own fallback gives it — the chat bubble, which is what we return
 /// directly. Index **≥15** walks off the end into the gossip Lua *binding* table, pushing API-name
@@ -337,7 +339,7 @@ fn feed_gossip(
         .and_then(|g| names.resolve(g, &commands).map(str::to_string));
     // **The hold fires nothing** (decision 1994). While the greeting query is in flight the
     // reference's handler has set its select latch and RETURNED — no greeting write, no event
-    // (wow-re `gossip-npctext-law.md` §1/§4) — so its frame keeps whatever it last painted:
+    // (`0x4e2010`, exit `0x4e2068`) — so its frame keeps whatever it last painted:
     // hidden if it was hidden, the previous menu if it was open, clicks refused (`drain_gossip`).
     // A pending menu is therefore NOT a closed one: the VM keeps its last snapshot, `last` keeps
     // its memory, and the text landing is a plain in-place `GOSSIP_SHOW` below. Reading the hold
@@ -409,8 +411,7 @@ fn drain_gossip(
         let Some(npc) = state.npc else { continue };
         // While the greeting query is in flight — the frame may still show the previous menu
         // (1994) — refuse the select, as the reference does: its `SelectGossipOption` (`0x4e2320`)
-        // is silently refused while the text-pending latch `0xbbb670` is set (wow-re
-        // `gossip-npctext-law.md` §1).
+        // is silently refused while the text-pending latch `0xbbb670` is set.
         if state.text_pending() {
             debug!(
                 "ui_gossip: SelectGossipOption({pos}) while the text query is in flight — refused"
@@ -499,7 +500,7 @@ mod tests {
 
     /// B292's hold: a first visit (record not cached) keeps the menu CLOSED for the query round
     /// trip — options never render over an empty page — and the text arriving opens it complete.
-    /// The reference's law, from the bytes (wow-re `gossip-npctext-law.md` §4): the greeting write
+    /// The reference's law (`0x4e229a`/`0x4e22b0`): the greeting write
     /// and `GOSSIP_SHOW` are adjacent and unconditional on one success path; every other exit
     /// fires no event.
     #[test]
@@ -617,7 +618,7 @@ mod tests {
     /// the feed read that as a close) and the landing fired `GOSSIP_SHOW`: `HideUIPanel` then
     /// `ShowUIPanel` across a server round trip — the flash. First click only, because the record
     /// cache serves the second visit with no hold. The reference fires nothing at the pending
-    /// step (wow-re `gossip-npctext-law.md` §1/§4): its frame keeps the previous menu painted,
+    /// step (`0x4e2010`, exit `0x4e2068`): its frame keeps the previous menu painted,
     /// selects refused, until the text answers — then one in-place repaint.
     #[test]
     fn the_hold_fires_nothing_a_pending_submenu_keeps_the_frame_painted() {
@@ -780,8 +781,8 @@ mod tests {
         );
     }
 
-    /// A revisit (record cached) opens immediately with no query — the half of B292 the reporter
-    /// saw as "never seen this before": the empty frame is a first-visit-only state.
+    /// A revisit (record cached) opens immediately with no query: the empty frame is a
+    /// first-visit-only state.
     #[test]
     fn revisit_opens_immediately_from_the_cache() {
         let mut state = GossipState::default();
diff --git a/crates/benilla-app/src/ui_gossip/net.rs b/crates/benilla-app/src/ui_gossip/net.rs
new file mode 100644
index 00000000..56792fd0
--- /dev/null
+++ b/crates/benilla-app/src/ui_gossip/net.rs
@@ -0,0 +1,146 @@
+//! The gossip window's packet handlers (decision 0081 phase 3; in the net handler table since
+//! 2318, moved out of the drain's npc arm file) — each fills the [`GossipState`] the gossip feed
+//! ([`super`]) reads; nothing here touches the VM.
+
+use benilla_protocol::messages::{GossipOption, NpcTextBlock};
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::GossipState;
+use crate::net::{ClientCommand, GuidIndex, NetCommands, NetHandlerApp, ObjectStore};
+use crate::ui_quest::QuestGiver;
+
+/// Register the gossip handlers — called from [`super::UiGossipPlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::GossipMenu, on_gossip_menu)
+        .net_handler(K::NpcGreeting, on_npc_greeting)
+        .net_handler(K::GossipComplete, on_gossip_complete)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_gossip_menu(
+    In(ev): In<SessionEvent>,
+    mut gossip: ResMut<GossipState>,
+    commands: Res<NetCommands>,
+    index: Res<GuidIndex>,
+    stores: Query<&ObjectStore>,
+) {
+    if let SessionEvent::GossipMenu {
+        npc,
+        text_id,
+        options,
+        quests,
+    } = ev
+    {
+        gossip_menu(
+            npc,
+            text_id,
+            options,
+            quests,
+            &mut gossip,
+            &commands,
+            &index,
+            &stores,
+        );
+    }
+}
+
+fn on_npc_greeting(
+    In(ev): In<SessionEvent>,
+    mut gossip: ResMut<GossipState>,
+    index: Res<GuidIndex>,
+    stores: Query<&ObjectStore>,
+) {
+    if let SessionEvent::NpcGreeting { text_id, blocks } = ev {
+        npc_greeting(text_id, blocks, &mut gossip, &index, &stores);
+    }
+}
+
+fn on_gossip_complete(
+    In(ev): In<SessionEvent>,
+    mut gossip: ResMut<GossipState>,
+    mut quest: ResMut<QuestGiver>,
+) {
+    if let SessionEvent::GossipComplete = ev {
+        gossip_complete(&mut gossip, &mut quest);
+    }
+}
+
+/// An open gossip menu dies with the socket. A listener on the session end
+/// (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut gossip: ResMut<GossipState>) {
+    gossip.clear_session();
+}
+
+/// A streamed unit's gender (`UNIT_FIELD_BYTES_0` byte 2) by guid — the gossip greeting's column
+/// selector (`0x4e20c1`: tested `== 1` for female, so genderless `2` reads as
+/// male). `0` when the guid isn't streamed in or carries no descriptor yet, which is the same
+/// column the reference takes for a gossip target that isn't a unit at all.
+fn npc_gender(guid: u64, index: &GuidIndex, stores: &Query<&ObjectStore>) -> u8 {
+    index
+        .0
+        .get(&guid)
+        .and_then(|&e| stores.get(e).ok())
+        .and_then(|s| s.0.unit_gender())
+        .unwrap_or(0)
+}
+
+/// A gossip menu opened (`SMSG_GOSSIP_MESSAGE`): fill the [`GossipState`] the gossip feed
+/// ([`super`]) reads. A first visit to the text id sends the ask-once
+/// `CMSG_NPC_TEXT_QUERY` and **the feed fires nothing until [`npc_greeting`] answers it** — a
+/// hidden frame stays hidden, an open one keeps its previous menu painted (B292's hold and
+/// 1994's no-event edge; the mechanics and the reference law live on
+/// [`GossipState::open_menu`]); a revisit serves from the cache and repaints right away.
+/// [`gossip_complete`] closes it.
+///
+/// The greeting is **drawn here**, not at the packet — this is the reference's own moment for it
+/// (`0x4e2010`), and the draw needs both this NPC's gender ([`npc_gender`]) and a fresh roll.
+fn gossip_menu(
+    npc: u64,
+    text_id: u32,
+    options: Vec<GossipOption>,
+    quests: Vec<(u32, u32, u32, String)>,
+    gossip: &mut GossipState,
+    net_commands: &NetCommands,
+    index: &GuidIndex,
+    stores: &Query<&ObjectStore>,
+) {
+    let npc_gender = npc_gender(npc, index, stores);
+    debug!(
+        "net: gossip menu on {npc:#x} — {} options, {} quests",
+        options.len(),
+        quests.len()
+    );
+    if gossip.open_menu(npc, text_id, options, quests, npc_gender) {
+        let _ = net_commands
+            .0
+            .send(ClientCommand::NpcTextQuery { text_id, guid: npc });
+    }
+}
+
+/// The NPC-text answer (`SMSG_NPC_TEXT_UPDATE`) — seed the cache with the whole record, and open
+/// the menu still waiting on it (a late answer for a menu we already closed or switched just
+/// seeds the cache; the next open draws its own line).
+///
+/// The record answers a query we sent for the waiting menu, so its NPC is the one whose gender
+/// picks the column (decision 0081's ask-once flow).
+fn npc_greeting(
+    text_id: u32,
+    blocks: Vec<NpcTextBlock>,
+    gossip: &mut GossipState,
+    index: &GuidIndex,
+    stores: &Query<&ObjectStore>,
+) {
+    let npc_gender = gossip.npc.map_or(0, |npc| npc_gender(npc, index, stores));
+    gossip.text_arrived(text_id, blocks, npc_gender);
+}
+
+/// `SMSG_GOSSIP_COMPLETE` ends the whole interaction (e.g. right after a quest accept), so the
+/// quest window closes with the gossip menu (decision 0088).
+pub(crate) fn gossip_complete(gossip: &mut GossipState, quest: &mut QuestGiver) {
+    debug!("net: gossip complete — closing the menu");
+    gossip.clear();
+    quest.clear();
+}
diff --git a/crates/benilla-app/src/ui_guild/feed.rs b/crates/benilla-app/src/ui_guild/feed.rs
index 0aa041fb..c6e29573 100644
--- a/crates/benilla-app/src/ui_guild/feed.rs
+++ b/crates/benilla-app/src/ui_guild/feed.rs
@@ -148,7 +148,7 @@ pub(super) fn feed_guild(
     // 1.12's FrameXML has — `InGuildCheck` and the paper doll both read `GetGuildInfo("player")`
     // and ignore the argument. The per-token broadcast for OTHER units is deliberately not built:
     // it has no consumer here, and the broadcaster's per-token walk is the one part of that path
-    // wow-re flags INFERRED, so it is not something to build on yet.
+    // that is inferred, unconfirmed in the binary, so it is not something to build on yet.
     if id_changed {
         script.fire_event(
             "PLAYER_GUILD_UPDATE",
diff --git a/crates/benilla-app/src/ui_guild/lines.rs b/crates/benilla-app/src/ui_guild/lines.rs
index a71d2162..4446f999 100644
--- a/crates/benilla-app/src/ui_guild/lines.rs
+++ b/crates/benilla-app/src/ui_guild/lines.rs
@@ -27,9 +27,8 @@
 //! passing a message record. A route with no record has no `kind` and no sound to read, so it is
 //! resolved where the VM is — [`super::feed`] — rather than queued as a message.
 //!
-//! The id → key mapping is **wow-re `system/ui/scratch/guild-api-carve.md` §5's own table**, §5
-//! cross-checked with the case-arm bytes quoted per row (`0x5e720a`→0x59 … `0x5e745a`→0x69), and
-//! the keys are matched against benilla's generated catalog rather than by name.
+//! The id → key mapping is **the handler's own case arms** (`0x5e720a`→0x59 … `0x5e745a`→0x69),
+//! and the keys are matched against benilla's generated catalog rather than by name.
 
 use benilla_protocol::messages::{
     guild_command, guild_command_error, guild_event, GuildCommandResult, GuildEventNotice,
@@ -39,8 +38,8 @@ use crate::ui_action::UiError;
 
 /// The strings `SMSG_GUILD_EVENT`'s shared emitter tail passes to `0x496720`.
 ///
-/// **`strCount == 0` and `strCount >= 4` both pass ZERO strings** (`0x5e745f`, wow-re
-/// `guild-api-carve.md` §5) — the tail has three arms for 1, 2 and 3 and no other. That is not the
+/// **`strCount == 0` and `strCount >= 4` both pass ZERO strings** (`0x5e745f`) — the tail has
+/// three arms for 1, 2 and 3 and no other. That is not the
 /// same as padding the missing slots with empties, which is what this module did before: a template
 /// whose specifier runs out of arguments has the specifier **copied through verbatim**
 /// (`SStrPrintf`, and [`benilla_ui::strings::fill`] implements it), so a two-string promotion reads
@@ -64,13 +63,13 @@ fn emitted_params(notice: &GuildEventNotice) -> Vec<&str> {
 /// the pair is the only place in this table with a condition at all, and that the guid those two
 /// arms carry exists to answer it.
 ///
-/// **This argument used to be `ignored`, and that was a mislabel** (corrected 1589, from a wow-re
-/// §5 dispatched for exactly this): `0x5ae810` is `FriendList::FindFriendSlot`, a **friends-list**
+/// **This argument used to be `ignored`, and that was a mislabel** (corrected 1589):
+/// `0x5ae810` is `FriendList::FindFriendSlot`, a **friends-list**
 /// membership test — base `this+8`, stride `0x20`, bound `0x32` — not the ignore-list check at
 /// `this+0x650`. Reading it as "ignore" got the behaviour backwards on both sides: an *ignored*
 /// guildmate was silenced where the reference announces them, and a guildmate who is also a
 /// *friend* was announced twice, because `SMSG_FRIEND_STATUS` says the same thing with no gate of
-/// its own. The repo's own `system/net` ledger had `0x5ae810` right the whole time.
+/// its own. `0x5ae810` has exactly two callers image-wide, these two arms.
 pub(super) fn event_line(notice: &GuildEventNotice, announce_signon: bool) -> Option<UiError> {
     let args = emitted_params(notice);
     let shared = |key: &'static str| Some(UiError::strings(key, &args));
@@ -109,8 +108,8 @@ pub(super) fn event_line(notice: &GuildEventNotice, announce_signon: bool) -> Op
         guild_event::SIGNED_ON | guild_event::SIGNED_OFF => None,
         // **`0x09` and everything past `0x0d` fall to the SAME arm**, and it is not silence:
         // `0x5e745a` pushes `0x69` = `ERR_GUILD_INTERNAL` and jumps into the shared tail like the
-        // rest (guild-api-carve.md §5). This module used to return `None` here under a comment
-        // saying the key "is not settled" — it is settled, in wow-re's table and in benilla's own
+        // rest. This module used to return `None` here under a comment
+        // saying the key "is not settled" — it is settled, in the reference and in benilla's own
         // generated catalog, and `TABARD_CHANGE` was silent for the same reason.
         _ => shared("ERR_GUILD_INTERNAL"),
     }
@@ -123,7 +122,7 @@ pub(super) fn event_line(notice: &GuildEventNotice, announce_signon: bool) -> Op
 /// except for `0x08`, whose two meanings are told apart by that same tag.
 ///
 /// **Every `_S` key here is called with the name and every other with nothing** — the reference's
-/// `add esp,8` / `add esp,4` split, 22 of 22 (guild-api-carve.md §5's own internal control). That
+/// `add esp,8` / `add esp,4` split, 22 of 22 (`0x5e7520`). That
 /// is a property a test can check against the key names, and one does.
 pub(super) fn command_line(result: &GuildCommandResult) -> Option<UiError> {
     let name = result.name.as_str();
@@ -331,7 +330,7 @@ mod tests {
     }
 
     /// **The `_S` arity control, 22 of 22** — the reference's `add esp,8` at every `_S` key and
-    /// `add esp,4` at every other (guild-api-carve.md §5). It is checkable here because the key
+    /// `add esp,4` at every other (`0x5e7520`). It is checkable here because the key
     /// name carries the arity, and it is the one thing about this table that a wrong key cannot
     /// pass silently.
     #[test]
diff --git a/crates/benilla-app/src/ui_guild/mod.rs b/crates/benilla-app/src/ui_guild/mod.rs
index cf1e5b56..abd6f4a5 100644
--- a/crates/benilla-app/src/ui_guild/mod.rs
+++ b/crates/benilla-app/src/ui_guild/mod.rs
@@ -4,8 +4,7 @@
 //! [`GuildState`] mirrors the wire the way [`crate::ui_social`]'s `SocialState` does: the seven
 //! server packets replace it or patch it, and the feed ([`feed`]) turns it into the display-ready
 //! snapshot `benilla_ui::script::guild` reads. The laws below are the ones that are *not* what the
-//! obvious design would do, each verified at the reference's bytes (wow-re
-//! `system/ui/scratch/guild-api-carve.md`, `guild-roster-wire.md`, RF-0077):
+//! obvious design would do, each as the reference does it:
 //!
 //! - **Identity and roster are two caches with two lifetimes.** `SMSG_GUILD_ROSTER` carries the
 //!   MOTD, the info text, the rank *rights* and the members; it carries neither the guild's name
@@ -142,8 +141,8 @@ impl RosterUpdate {
 /// GuildState is cleared on disconnect, and a CVar must not be.
 ///
 /// **Off by default, and that is byte-read, not a guess**: the register site `0x5e24c7` pushes
-/// `0x82e570` = `"0"` (§5, wow-re `system/object-layer/scratch/guild-signon-cvar-gate.md`). A
-/// stock 1.12 client prints nothing when a guildmate logs in, and neither do we.
+/// `0x82e570` = `"0"`. A stock 1.12 client prints nothing when a guildmate logs in, and
+/// neither do we.
 #[derive(Resource, Default)]
 pub(crate) struct GuildMemberNotify(pub(crate) bool);
 
@@ -362,8 +361,8 @@ impl GuildState {
         self.motd = roster.motd;
         self.info_text = roster.info;
         // The reference's own rank-rights loop has no bound check and overruns its ten-slot array
-        // into the member array's control block on a hostile `rankCount >= 12` (wow-re
-        // `guild-api-carve.md` §2). We clamp: a memory-safety divergence, deliberately.
+        // into the member array's control block on a hostile `rankCount >= 12` (`0x4d0bb0`). We
+        // clamp: a memory-safety divergence, deliberately.
         self.rank_rights = roster.rank_rights;
         self.rank_rights.truncate(GUILD_RANKS_MAX_COUNT);
         self.members = roster.members;
@@ -577,7 +576,7 @@ pub(crate) fn unit_guild(
 /// `0x860f9c`), which the reference resolves through the very same guild-identity cache this
 /// serves `GetGuildInfo` from: `0x609085` tests the render mask's bit `0x10`
 /// (`UnitNamePlayerGuild`) and then reads `0x5e09f0` off the unit's own `[CGUnit+0xe68]+0x8/0xc`
-/// guild GUID (wow-re `object-layer/scratch/overhead-name.md` Q4 point 3).
+/// guild GUID.
 ///
 /// [`unit_guild`] without the rank — and, deliberately, **without its two `String` clones**: this
 /// is read once per shown player per frame by [`crate::nameplates::drive_nameplates`], whose whole
@@ -601,8 +600,7 @@ pub(crate) fn unit_guild_name<'a>(
 /// it, exactly like [`unit_guild`].
 ///
 /// `None` — no crest painted, so a Guild Tabard keeps its own `Tabard_A_05Default` art — covers
-/// **four** cases, and the reference reaches the same nil on all four (wow-re
-/// `rf89-guild-tabard-emblem-install.md` §Q1/§Q6):
+/// **four** cases, and the reference reaches the same nil on all four:
 ///
 /// 1. a guildless wearer — `0x560e30` returns NULL at `0x560e3f` before it even queries;
 /// 2. a creature, which has no player block at all;
@@ -628,7 +626,7 @@ pub(crate) fn unit_guild_emblem(
 /// The same crest for a **corpse**, whose guild id is its own snapshot
 /// ([`ObjectFields::corpse_guild`]) rather than the living `PLAYER_GUILDID` — the reference reads
 /// `CORPSE_FIELD_GUILD` at `0x5d6edf` and runs the identical name-cache lookup before installing
-/// the emblem (`0x5d6ec0`; wow-re `corpse-decal-and-loot-sparkle.md` §6b). All four `None` cases
+/// the emblem (`0x5d6ec0`). All four `None` cases
 /// above hold unchanged: a guildless owner, a query still in flight, an undesigned crest.
 pub(crate) fn corpse_guild_emblem(
     fields: &ObjectFields,
@@ -648,14 +646,112 @@ fn guild_emblem(
     emblem.is_designed().then_some(emblem)
 }
 
-/// The net drain's `SessionEvent::Guild*` arms, factored here so the wire laws live beside the
-/// state they drive ([`crate::ui_social::apply`]'s shape). The ones that owe a line queue the
-/// **message id** [`lines`] named, the way `crate::net::apply`'s group shims do — the surface and
-/// the sound come off the catalog at the drain, not from here (decision 2054).
-pub(crate) mod apply {
+/// The guild family's packet handlers (decision 1257; in the net handler table since 2312),
+/// beside the state they drive ([`crate::ui_social::net`]'s shape): the identity cache, the
+/// roster, and the `ERR_GUILD_*` lines the engine composes; the guild EVENTS fire off the mirror
+/// in [`feed_guild`], on their edges. The ones that owe a line queue the **message id** [`lines`]
+/// named, the way `crate::net::apply`'s group shims do — the surface and the sound come off the
+/// catalog at the error frame's drain, not from here (decision 2054).
+pub(crate) mod net {
     use super::*;
     use crate::ui_action::{UiError, UiErrorKeys};
     use crate::ui_social::SocialState;
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+
+    use crate::net::NetHandlerApp;
+
+    /// Register the family's handlers — called from [`UiGuildPlugin`]. One per kind, plus the
+    /// session-end listener.
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::GuildQueryResponse, on_query_response)
+            .net_handler(K::GuildRoster, on_roster)
+            .net_handler(K::GuildEvent, on_event)
+            .net_handler(K::GuildCommandResult, on_command_result)
+            .net_handler(K::GuildInvite, on_invite)
+            .net_handler(K::GuildDecline, on_decline)
+            .net_handler(K::GuildInfo, on_info)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    fn on_query_response(In(ev): In<SessionEvent>, mut guild: ResMut<GuildState>) {
+        if let SessionEvent::GuildQueryResponse(response) = ev {
+            query_response(&mut guild, response);
+        }
+    }
+
+    fn on_roster(In(ev): In<SessionEvent>, mut guild: ResMut<GuildState>) {
+        if let SessionEvent::GuildRoster(r) = ev {
+            roster(&mut guild, r);
+        }
+    }
+
+    /// The sign-on/sign-off pair's trailing guid exists for exactly one purpose — the
+    /// four-conjunct display condition on their line — which is why this handler reads the
+    /// social lists, the notify knob and our own guid (decision 1589; the condition and its byte
+    /// addresses are on [`event`]).
+    fn on_event(
+        In(ev): In<SessionEvent>,
+        mut guild: ResMut<GuildState>,
+        mut errors: ResMut<UiErrorKeys>,
+        social: Res<SocialState>,
+        notify: Res<GuildMemberNotify>,
+        self_guid: Res<crate::net::SelfGuid>,
+    ) {
+        if let SessionEvent::GuildEvent(notice) = ev {
+            event(
+                &mut guild,
+                &mut errors,
+                &social,
+                &notify,
+                self_guid.0,
+                notice,
+            );
+        }
+    }
+
+    fn on_command_result(
+        In(ev): In<SessionEvent>,
+        mut guild: ResMut<GuildState>,
+        mut errors: ResMut<UiErrorKeys>,
+    ) {
+        if let SessionEvent::GuildCommandResult(result) = ev {
+            command_result(&mut guild, &mut errors, result);
+        }
+    }
+
+    fn on_invite(
+        In(ev): In<SessionEvent>,
+        mut guild: ResMut<GuildState>,
+        mut errors: ResMut<UiErrorKeys>,
+    ) {
+        if let SessionEvent::GuildInvite { inviter, guild: g } = ev {
+            invite(&mut guild, &mut errors, inviter, g);
+        }
+    }
+
+    fn on_decline(In(ev): In<SessionEvent>, mut errors: ResMut<UiErrorKeys>) {
+        if let SessionEvent::GuildDecline { name } = ev {
+            decline(&mut errors, &name);
+        }
+    }
+
+    fn on_info(In(ev): In<SessionEvent>, mut guild: ResMut<GuildState>) {
+        if let SessionEvent::GuildInfo(i) = ev {
+            info(&mut guild, i);
+        }
+    }
+
+    /// The guild session is login-scoped (decision 1257) — and strictly, because the next login
+    /// may be a *different character*, whose guild id, rank, rights and roster share nothing
+    /// with this one's. The identity cache goes too: it is keyed by guild id, so it would
+    /// survive correctly, but the reference's own is backed by `guildcache.wdb` and re-primed
+    /// lazily, and keeping a cache alive across a socket only to save one query is not worth the
+    /// one wrong name a renamed guild would show. A listener on the session end
+    /// (a second handler on the kind, after the bridge's own teardown).
+    fn on_session_end(In(_): In<SessionEvent>, mut guild: ResMut<GuildState>) {
+        *guild = GuildState::default();
+    }
 
     /// Queue what [`lines`] named. The key IS the lookup and the catalog row behind it names the
     /// surface and the sound, so nothing here decides either — which is the difference decision
@@ -678,9 +774,7 @@ pub(crate) mod apply {
     /// `SMSG_GUILD_EVENT`. The trailing guid rides only on the sign-on/sign-off pair, and it is
     /// there to answer that pair's **display condition** — which the reference builds out of
     /// **four conjuncts**, all of them in the handler's `0x0c`/`0x0d` arms, each branching to the
-    /// same silent exit `0x5e74c9` (wow-re `system/object-layer/scratch/guild-signon-cvar-gate.md`,
-    /// the §5 dispatched for decision 1589; it corrects `guild-api-carve.md` §5, which recorded
-    /// these arms with only one of the four):
+    /// same silent exit `0x5e74c9` (decision 1589):
     ///
     /// 1. **there is a local player object.** Ours is "we know our own guid" — the same fact, and
     ///    it is what conjunct 3 needs anyway.
@@ -790,6 +884,7 @@ pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut notify: ResMut<Guil
 
 impl Plugin for UiGuildPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.add_observer(on_cvar);
         crate::query_cache::register::<GuildState>(app);
         app.init_resource::<GuildState>()
@@ -846,44 +941,44 @@ mod tests {
         }
     }
 
-    /// The sign-on/sign-off line's **four-conjunct** display condition (decision 1589, from the
-    /// wow-re §5 dispatched for it). Every conjunct gets its own case, because the two that were
+    /// The sign-on/sign-off line's **four-conjunct** display condition (decision 1589). Every
+    /// conjunct gets its own case, because the two that were
     /// wrong were wrong in *opposite* directions and a single happy-path assertion would have
     /// caught neither.
     #[test]
     fn the_signon_condition_is_all_four_conjuncts() {
         let mut social = SocialState::default();
-        crate::ui_social::apply::friend_list(
+        crate::ui_social::net::friend_list(
             &mut social,
             vec![benilla_protocol::messages::FriendEntry {
                 guid: 7,
                 ..Default::default()
             }],
         );
-        crate::ui_social::apply::ignore_list(&mut social, vec![9]);
+        crate::ui_social::net::ignore_list(&mut social, vec![9]);
         let on = GuildMemberNotify(true);
         let off = GuildMemberNotify(false);
         let me = Some(1);
 
         // 2 · the CVar, which ships OFF — so the default client says nothing at all.
         assert!(
-            !apply::announce_signon(&social, &off, me, Some(5)),
+            !net::announce_signon(&social, &off, me, Some(5)),
             "guildMemberNotify off silences the whole family"
         );
-        assert!(apply::announce_signon(&social, &on, me, Some(5)));
+        assert!(net::announce_signon(&social, &on, me, Some(5)));
 
         // 3 · not you. vmangos broadcasts the sign-on to EVERY member including the signer
         // (`Guild::BroadcastPacket`, Guild.cpp:651-656), so without this you announce yourself at
         // every login.
         assert!(
-            !apply::announce_signon(&social, &on, me, Some(1)),
+            !net::announce_signon(&social, &on, me, Some(1)),
             "your own sign-on is not announced to you"
         );
 
         // 4 · not a friend — de-duplication against SMSG_FRIEND_STATUS, which says the same thing
         // with no CVar gate of its own. THIS is the conjunct benilla read as an ignore check.
         assert!(
-            !apply::announce_signon(&social, &on, me, Some(7)),
+            !net::announce_signon(&social, &on, me, Some(7)),
             "a guildmate who is also a friend is announced by the friend path, not twice"
         );
 
@@ -894,14 +989,14 @@ mod tests {
             "the fixture's ignore really is an ignore"
         );
         assert!(
-            apply::announce_signon(&social, &on, me, Some(9)),
+            net::announce_signon(&social, &on, me, Some(9)),
             "the reference announces an ignored guildmate — 0x5ae810 is not the ignore check"
         );
 
         // 1 · a local player, and the pair's own guid: either missing leaves the condition
         // unanswerable, and the reference's silent exit is the answer.
-        assert!(!apply::announce_signon(&social, &on, None, Some(5)));
-        assert!(!apply::announce_signon(&social, &on, me, None));
+        assert!(!net::announce_signon(&social, &on, None, Some(5)));
+        assert!(!net::announce_signon(&social, &on, me, None));
     }
 
     /// `show_offline` changes what `GetNumGuildMembers` counts and how the rows are ordered —
diff --git a/crates/benilla-app/src/ui_guild/sort.rs b/crates/benilla-app/src/ui_guild/sort.rs
index 02e07c26..1aa8cf82 100644
--- a/crates/benilla-app/src/ui_guild/sort.rs
+++ b/crates/benilla-app/src/ui_guild/sort.rs
@@ -1,5 +1,4 @@
-//! The guild roster's **view** — sorted, never filtered (wow-re
-//! `system/ui/scratch/guild-api-carve.md` §3).
+//! The guild roster's **view** — sorted, never filtered (the comparator `0x4d0d50`).
 //!
 //! Two things about it are the opposite of the obvious design, and both are verified at the bytes:
 //!
diff --git a/crates/benilla-app/src/ui_honor.rs b/crates/benilla-app/src/ui_honor.rs
index 813631ac..3c003b28 100644
--- a/crates/benilla-app/src/ui_honor.rs
+++ b/crates/benilla-app/src/ui_honor.rs
@@ -16,8 +16,8 @@
 //! ## 2 · The two events are a field diff, and the reference watches **exactly three fields**
 //!
 //! The pane repaints on `PLAYER_PVP_KILLS_CHANGED` and `PLAYER_PVP_RANK_CHANGED`, which the real
-//! engine fires from field watches. wow-re carved the watch table (`0x467e70`, callback
-//! `0x5de4b0` carrying the event id) and there are **three registrations and no more**:
+//! engine fires from field watches. In the watch table (`0x467e70`, callback
+//! `0x5de4b0` carrying the event id) there are **three registrations and no more**:
 //!
 //! | watched | fires |
 //! |---|---|
@@ -29,7 +29,7 @@
 //! nothing watches `+0x102b` (the highest-lifetime rank).** That is not an omission in the client;
 //! it is *why* `HonorFrame.lua` refreshes those rows on `PLAYER_ENTERING_WORLD` alone. The two
 //! facts are one fact, and a feed that fired `KILLS_CHANGED` on a lifetime total — which this one
-//! did until the verdict landed — would be firing an event the real client has no source for.
+//! once did — would be firing an event the real client has no source for.
 //!
 //! One divergence, stated: the reference watches the **whole `PLAYER_BYTES_3` dword**, so a
 //! drunkenness change fires `PLAYER_PVP_RANK_CHANGED` there too. We watch byte 3 alone. The
@@ -84,10 +84,36 @@ struct HonorFeedMemo {
     last_inspect: Option<u64>,
 }
 
+/// The honor pane's packet handler (decision 1512; in the net handler table since 2313). The
+/// honor arc's other inbound message, the award (`PvpCredit`), is a chat line and a floating
+/// number and stays with the chat family.
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::InspectHonor;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handler — called from [`super::UiHonorPlugin`].
+    pub(super) fn register(app: &mut App) {
+        app.net_handler(SessionEventKind::InspectHonorStats, on_inspect_stats);
+    }
+
+    /// The inspect reply REPLACES whatever is held, including for a different player: the
+    /// reference's latch is a single slot, and a pane still showing the last target's kills is
+    /// the failure keeping the old one produces.
+    fn on_inspect_stats(In(ev): In<SessionEvent>, mut inspect: ResMut<InspectHonor>) {
+        if let SessionEvent::InspectHonorStats(stats) = ev {
+            inspect.0 = Some(stats);
+        }
+    }
+}
+
 pub(crate) struct UiHonorPlugin;
 
 impl Plugin for UiHonorPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<InspectHonor>()
             .init_resource::<HonorFeedState>()
             .add_systems(Update, feed_honor.in_set(UiFeed));
@@ -100,11 +126,11 @@ impl Plugin for UiHonorPlugin {
 /// flaw in it.** This doc used to say the reference "paints a player whose fields have not arrived
 /// as blank, not as zero". It does not: `0x51a4b0`–`0x51a7c0`'s "absent → 0.0" tails are about the
 /// absent player OBJECT, and once the object exists every one of those bindings reads a
-/// descriptor array that is allocated and zeroed, so a field the server never sent reads `0`
-/// (wow-re `honor-panel-law.md` §3.1–3.5). Our bindings answer the same zeros —
-/// `honor(lua).unwrap_or_default()` — so what the gate actually decides is only *when the first
-/// snapshot is pushed*, and with it when `PLAYER_PVP_KILLS_CHANGED`/`PLAYER_PVP_RANK_CHANGED`
-/// first fire. It cannot make a row differ from the reference.
+/// descriptor array that is allocated and zeroed, so a field the server never sent reads `0`.
+/// Our bindings answer the same zeros — `honor(lua).unwrap_or_default()` — so what the gate
+/// actually decides is only *when the first snapshot is pushed*, and with it when
+/// `PLAYER_PVP_KILLS_CHANGED`/`PLAYER_PVP_RANK_CHANGED` first fire. It cannot make a row differ
+/// from the reference.
 ///
 /// That is worth stating because this gate was the other candidate cause of report B378, and it
 /// is ruled out by exactly this: a missing snapshot and a zeroed one paint the same pane. The
@@ -149,7 +175,7 @@ fn honor_snapshot(store: &ObjectStore) -> Option<HonorState> {
 /// **Most of `HonorState` fires nothing at all.** The weekly figures, the two lifetime totals and
 /// the highest-lifetime rank are unwatched in the real client, so they ride the pane's world-entry
 /// repaint and move here in silence. Listing the watched fields positively — rather than
-/// "everything that is not a rank byte", which is what this did before the RE verdict — is what
+/// "everything that is not a rank byte", which is what this did before — is what
 /// keeps a field added later from inventing an event for itself.
 fn events_for(before: Option<&HonorState>, after: &HonorState) -> (bool, bool) {
     let Some(b) = before else {
@@ -203,8 +229,8 @@ fn feed_honor(
     // data and inspecting a SECOND player repaints the FIRST one's kills, with no request ever
     // sent and nothing on screen to say so.
     //
-    // **The real client's latch is invalidated by exactly one thing, and it is not this one**
-    // (wow-re `honor-panel-law.md`): the slot is a single un-keyed store, and `0x4c6f70` — reached
+    // **The real client's latch is invalidated by exactly one thing, and it is not this one**:
+    // the slot is a single un-keyed store, and `0x4c6f70` — reached
     // from `NotifyInspect` — is its only GUID writer *and* its only invalidator. A `NotifyInspect`
     // naming a different player zeroes both flags; the same player is a no-op; there is no timeout;
     // and `ClearInspectPlayer` (the stock `InspectFrame_OnHide`) clears it outright.
@@ -320,9 +346,9 @@ mod tests {
         assert_eq!(events_for(Some(&base), &barred), (false, true));
 
         // The unwatched half: a weekly figure, a lifetime total and the highest-lifetime rank all
-        // move in silence, because the real client registers no watch on any of them (wow-re's
-        // carve of `0x467e70` — the module doc's table). This is the assertion the pre-verdict
-        // implementation failed: it fired `KILLS_CHANGED` for all three.
+        // move in silence, because the real client registers no watch on any of them (`0x467e70` —
+        // the module doc's table). This is the assertion the earlier implementation failed: it
+        // fired `KILLS_CHANGED` for all three.
         for mutate in [
             (|h: &mut HonorState| h.last_week_standing = 42) as fn(&mut HonorState),
             |h: &mut HonorState| h.lifetime_hk = 5_000,
diff --git a/crates/benilla-app/src/ui_inspect.rs b/crates/benilla-app/src/ui_inspect.rs
index 2bbf48bc..33a8eab8 100644
--- a/crates/benilla-app/src/ui_inspect.rs
+++ b/crates/benilla-app/src/ui_inspect.rs
@@ -141,8 +141,8 @@ fn inspect_slot_view(
         // not the instance's bound state.
         already_bound: false,
         // All 7 slots, exactly as the reference's own inspect leg copies and renders them
-        // (§E7) — a 1.12 server happens to fill only PERM and TEMP. No item object here, so no
-        // charges and no `SMSG_ITEM_ENCHANT_TIME_UPDATE` countdown: the reference's inspect
+        // (`0x533354`) — a 1.12 server happens to fill only PERM and TEMP. No item object here, so
+        // no charges and no `SMSG_ITEM_ENCHANT_TIME_UPDATE` countdown: the reference's inspect
         // tooltip has neither either.
         enchants: crate::items::enchant_lines(
             (0..7).map(|j| {
diff --git a/crates/benilla-app/src/ui_instance.rs b/crates/benilla-app/src/ui_instance.rs
index 49cf12ca..3af80296 100644
--- a/crates/benilla-app/src/ui_instance.rs
+++ b/crates/benilla-app/src/ui_instance.rs
@@ -97,7 +97,7 @@
 //! maps it ever names are raids, and a raid is `InstanceType == 2`, which `0x495d33`'s
 //! `cmp [rec+8],1` rejects. (1) is the only live writer here, which is why it is also the one
 //! that answers term 1. (1) is [`track_instance_state`]'s `CurrentMap` flip; (2) is
-//! [`apply::update_last_instance`]'s queue, drained through the same helper so the two cannot
+//! [`net::update_last_instance`]'s queue, drained through the same helper so the two cannot
 //! drift — [`LatchWriter`] is which of them is speaking.
 //!
 //! **(2) is therefore unreachable on our server by construction, and no live probe can cover it**
@@ -382,11 +382,48 @@ fn raid_instance_line(message: &RaidInstanceMessage) -> Option<LockoutLine> {
     })
 }
 
-/// The net drain's six arms, factored here so the wire law lives beside the state it drives.
-pub(crate) mod apply {
+/// The instance/raid lockout family's six packet handlers (decision 1748; in the net handler
+/// table since 2312), beside the state they drive: four lines the client composes itself out of
+/// GlobalStrings, and the two-packet latch behind the SELF menu's reset row. The lines are
+/// QUEUED — resolving them needs the VM, which a packet handler leaves to the feed (decision
+/// 0669's split).
+pub(crate) mod net {
     use super::*;
 
     use benilla_protocol::messages::InstanceResetFailed;
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+
+    use crate::net::NetHandlerApp;
+
+    /// Register the six handlers — called from [`UiInstancePlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::RaidInstanceMessage, on_packet)
+            .net_handler(K::InstanceSaveCreated, on_packet)
+            .net_handler(K::InstanceReset, on_packet)
+            .net_handler(K::InstanceResetFailed, on_packet)
+            .net_handler(K::UpdateLastInstance, on_packet)
+            .net_handler(K::UpdateInstanceOwnership, on_packet);
+    }
+
+    /// One handler for the six: each is a one-line fold into the same state.
+    fn on_packet(In(ev): In<SessionEvent>, mut state: ResMut<InstanceState>) {
+        match ev {
+            SessionEvent::RaidInstanceMessage { message } => {
+                raid_instance_message(&mut state, message)
+            }
+            SessionEvent::InstanceSaveCreated { flag } => instance_save_created(&mut state, flag),
+            SessionEvent::InstanceReset { map } => instance_reset(&mut state, map),
+            SessionEvent::InstanceResetFailed { failure } => {
+                instance_reset_failed(&mut state, failure)
+            }
+            SessionEvent::UpdateLastInstance { map } => update_last_instance(&mut state, map),
+            SessionEvent::UpdateInstanceOwnership { owns } => {
+                update_instance_ownership(&mut state, owns)
+            }
+            _ => {}
+        }
+    }
 
     /// `SMSG_RAID_INSTANCE_MESSAGE` — one of four `RAID_INSTANCE_*` lines (`0x49e1c0`).
     pub(crate) fn raid_instance_message(state: &mut InstanceState, message: RaidInstanceMessage) {
@@ -583,6 +620,7 @@ pub(crate) struct UiInstancePlugin;
 
 impl Plugin for UiInstancePlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<InstanceState>().add_systems(
             Update,
             (
@@ -723,7 +761,7 @@ mod tests {
     #[test]
     fn reset_lines_fill_the_map_name() {
         let mut state = InstanceState::default();
-        apply::instance_reset(&mut state, 36);
+        net::instance_reset(&mut state, 36);
         let lines = state.take_lines();
         assert_eq!(lines.len(), 1);
         assert_eq!(
@@ -747,7 +785,7 @@ mod tests {
             ),
         ] {
             let mut state = InstanceState::default();
-            apply::instance_reset_failed(
+            net::instance_reset_failed(
                 &mut state,
                 benilla_protocol::messages::InstanceResetFailed { reason, map: 36 },
             );
@@ -762,7 +800,7 @@ mod tests {
         // INSTANCERESET_FAIL_SILENTLY and above: no line, rather than the reference's
         // uninitialized-buffer print.
         let mut state = InstanceState::default();
-        apply::instance_reset_failed(
+        net::instance_reset_failed(
             &mut state,
             benilla_protocol::messages::InstanceResetFailed { reason: 3, map: 36 },
         );
@@ -774,21 +812,21 @@ mod tests {
     #[test]
     fn save_created_has_three_arms() {
         let mut state = InstanceState::default();
-        apply::instance_save_created(&mut state, 0);
+        net::instance_save_created(&mut state, 0);
         let lines = state.take_lines();
         assert_eq!(
             line_text(&lines[0], None).as_deref(),
             Some("You are now saved to this instance")
         );
 
-        apply::instance_save_created(&mut state, 1);
+        net::instance_save_created(&mut state, 1);
         let lines = state.take_lines();
         assert_eq!(
             line_text(&lines[0], None).as_deref(),
             Some("(Debug-Only Lock Notice) You are now saved to this instance")
         );
 
-        apply::instance_save_created(&mut state, 2);
+        net::instance_save_created(&mut state, 2);
         assert!(state.take_lines().is_empty());
     }
 
@@ -976,7 +1014,7 @@ mod tests {
             (s.last_dungeon, s.saw_own_dungeon)
         };
         let queue = |app: &mut App, map: u32| {
-            apply::update_last_instance(&mut app.world_mut().resource_mut::<InstanceState>(), map);
+            net::update_last_instance(&mut app.world_mut().resource_mut::<InstanceState>(), map);
         };
 
         // Writer 1 — we walk out of the Deadmines ourselves. The first tick only OBSERVES map 36
@@ -1131,7 +1169,7 @@ mod tests {
             Some("Welcome to Molten Core. This raid instance is scheduled to reset in 3d 2h 5m.")
         );
         let mut state = InstanceState::default();
-        apply::instance_reset_failed(
+        net::instance_reset_failed(
             &mut state,
             benilla_protocol::messages::InstanceResetFailed { reason: 0, map: 36 },
         );
diff --git a/crates/benilla-app/src/ui_item_text.rs b/crates/benilla-app/src/ui_item_text.rs
index bfb0caff..dd680647 100644
--- a/crates/benilla-app/src/ui_item_text.rs
+++ b/crates/benilla-app/src/ui_item_text.rs
@@ -35,7 +35,7 @@ use benilla_ui::script::{ItemTextState, UiScript};
 use crate::go_templates::GameObjectTemplates;
 use crate::items::Items;
 use crate::names::NameCache;
-use crate::net::{ClientCommand, NetCommands};
+use crate::net::{ClientCommand, NetCommands, Objects};
 use crate::query_cache::QueryCache;
 use crate::ui_mail::MailOpen;
 use crate::ui_script::{UiFeed, UiInput};
@@ -178,10 +178,38 @@ impl ItemTextOpen {
     }
 }
 
+/// The book reader's packet handler (decision 1105; in the net handler table since 2313).
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::PageTexts;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handler — called from [`super::UiItemTextPlugin`].
+    pub(super) fn register(app: &mut App) {
+        app.net_handler(SessionEventKind::PageText, on_page_text);
+    }
+
+    /// The book-page cache — one page per packet, the whole chain in answer to the first ask;
+    /// the reader repaints off it on the next feed.
+    fn on_page_text(In(ev): In<SessionEvent>, mut pages: ResMut<PageTexts>) {
+        if let SessionEvent::PageText {
+            page_id,
+            text,
+            next_page_id,
+        } = ev
+        {
+            pages.insert(page_id, text, next_page_id);
+        }
+    }
+}
+
 pub(crate) struct UiItemTextPlugin;
 
 impl Plugin for UiItemTextPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         crate::query_cache::register::<PageTexts>(app);
         app.init_resource::<ItemTextOpen>()
             .init_resource::<PageTexts>()
@@ -217,6 +245,7 @@ struct Readable {
 /// is FrameXML's "Parchment". A GameObject whose template is not cached yet is asked for.
 pub(crate) fn object_material(
     guid: u64,
+    objects: &Objects,
     items: &Items,
     go_templates: &GameObjectTemplates,
     materials: Option<&PageMaterials>,
@@ -232,7 +261,7 @@ pub(crate) fn object_material(
             }
         };
     }
-    let entry = items.object(guid)?.object_entry()?;
+    let entry = objects.object(guid)?.object_entry()?;
     let t = items.template(entry, guid, commands)?;
     name(t.page_material)
 }
@@ -242,6 +271,7 @@ pub(crate) fn object_material(
 /// single resolve serves both sources.
 fn readable(
     guid: u64,
+    objects: &Objects,
     items: &Items,
     go_templates: &GameObjectTemplates,
     materials: Option<&PageMaterials>,
@@ -255,7 +285,7 @@ fn readable(
             page_head: go.text_page.map_or(0, |p| p.page_id),
         });
     }
-    let entry = items.object(guid)?.object_entry()?;
+    let entry = objects.object(guid)?.object_entry()?;
     let t = items.template(entry, guid, commands)?;
     Some(Readable {
         title: t.name.clone(),
@@ -275,6 +305,7 @@ fn feed_item_text(
     mut open: ResMut<ItemTextOpen>,
     mail: Res<MailOpen>,
     pages: Res<PageTexts>,
+    objects: Objects,
     items: Res<Items>,
     names: Res<NameCache>,
     go_templates: Res<GameObjectTemplates>,
@@ -301,6 +332,7 @@ fn feed_item_text(
     }
     let Some(readable) = readable(
         sess.object_guid,
+        &objects,
         &items,
         &go_templates,
         materials.as_deref(),
@@ -337,7 +369,7 @@ fn feed_item_text(
         ReadSource::Letter { text_id } => {
             // The creator line: `ITEM_FIELD_CREATOR` → name cache (ask-once). `None` guid =
             // authorless.
-            let creator_guid = items
+            let creator_guid = objects
                 .object(sess.object_guid)
                 .and_then(|o| o.item_creator());
             let creator = match creator_guid {
@@ -544,6 +576,9 @@ mod quest_material_tests {
     #[test]
     fn a_quest_sourced_from_an_object_paints_the_objects_material() {
         let items = Items::default();
+        // No item source in this case — every one of these is a GameObject or a creature (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let mut gos = GameObjectTemplates::default();
         let (tx, rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
@@ -558,24 +593,47 @@ mod quest_material_tests {
         gos.insert(100, 2, "Wanted Poster".into(), &data);
         gos.insert(102, 10, "Chest".into(), &data);
         assert_eq!(
-            object_material(go_guid(100), &items, &gos, Some(&catalog), &commands).as_deref(),
+            object_material(
+                go_guid(100),
+                &objects,
+                &items,
+                &gos,
+                Some(&catalog),
+                &commands
+            )
+            .as_deref(),
             Some("Stone")
         );
         assert_eq!(
-            object_material(go_guid(102), &items, &gos, Some(&catalog), &commands).as_deref(),
+            object_material(
+                go_guid(102),
+                &objects,
+                &items,
+                &gos,
+                Some(&catalog),
+                &commands
+            )
+            .as_deref(),
             Some("Marble"),
             "a chest reads data[9]"
         );
         // A creature quest-giver: neither template, nothing asked.
         let creature = (u64::from(benilla_protocol::guid::HIGH_UNIT) << 48) | (6 << 24) | 1;
         assert_eq!(
-            object_material(creature, &items, &gos, Some(&catalog), &commands),
+            object_material(creature, &objects, &items, &gos, Some(&catalog), &commands),
             None
         );
         assert!(rx.try_recv().is_err(), "a creature source asks for nothing");
         // An uncached object: nothing yet, and the template is asked for.
         assert_eq!(
-            object_material(go_guid(777), &items, &gos, Some(&catalog), &commands),
+            object_material(
+                go_guid(777),
+                &objects,
+                &items,
+                &gos,
+                Some(&catalog),
+                &commands
+            ),
             None
         );
         assert!(
diff --git a/crates/benilla-app/src/ui_items/drain.rs b/crates/benilla-app/src/ui_items/drain.rs
index 9d949ae6..cc2a8a8e 100644
--- a/crates/benilla-app/src/ui_items/drain.rs
+++ b/crates/benilla-app/src/ui_items/drain.rs
@@ -9,7 +9,7 @@ use benilla_protocol::messages::BAG_PLAYER_INVENTORY;
 use benilla_ui::script::{UiScript, EQUIPMENT_BAG};
 
 use crate::items::Items;
-use crate::net::{ClientCommand, NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{ClientCommand, NetCommands, ObjectStore, Objects, SelfPlayer};
 use crate::pending_item_ops::PendingItemOps;
 
 use super::{slot_guid, slot_guid_count, wire_pos, INVTYPE_AMMO};
@@ -22,7 +22,7 @@ use super::{slot_guid, slot_guid_count, wire_pos, INVTYPE_AMMO};
 /// Takes the WIRE position and the item's guid, and answers whether the send happened. The two
 /// forks it owns:
 ///
-/// - **ammo** (`cursor-dragdrop-slots.md`): an ammo-class item loads by entry with `CMSG_SET_AMMO`
+/// - **ammo**: an ammo-class item loads by entry with `CMSG_SET_AMMO`
 ///   rather than the equip wire — the stack stays in the bag and `PLAYER_AMMO_ID` references it
 ///   (decision 0526). A missing template falls back to `CMSG_AUTOEQUIP_ITEM`, whose refusal is at
 ///   least visible.
@@ -33,6 +33,7 @@ use super::{slot_guid, slot_guid_count, wire_pos, INVTYPE_AMMO};
 pub(crate) fn send_auto_equip(
     script: &mut UiScript,
     gate: &mut crate::ui_bind_confirm::BindGate,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
     bag_index: u8,
@@ -42,7 +43,7 @@ pub(crate) fn send_auto_equip(
 ) -> bool {
     if !suppress {
         if let Some(guid) = guid {
-            if gate.equip_binds(script, items, commands, guid) {
+            if gate.equip_binds(script, objects, items, commands, guid) {
                 gate.defer_equip(
                     script,
                     crate::ui_bind_confirm::PendingEquip::AutoEquip {
@@ -56,7 +57,7 @@ pub(crate) fn send_auto_equip(
         }
     }
     let ammo_entry = guid.and_then(|guid| {
-        let entry = items.object(guid)?.object_entry()?;
+        let entry = objects.object(guid)?.object_entry()?;
         let t = items.template(entry, guid, commands)?;
         (t.inventory_type == INVTYPE_AMMO).then_some(entry)
     });
@@ -77,8 +78,8 @@ pub(crate) fn send_auto_equip(
 /// contract (`cursor::doll::auto_equip_cursor_item`) already guarantees only a whole-stack,
 /// CONTAINER-sourced Item payload (`bag >= 0`) ever reaches this queue.
 ///
-/// The same ammo sub-fork as [`drain_container_uses`] (wow-re `cursor-dragdrop-slots.md`: the one
-/// auto-equip sender forks ammo-class → `CMSG_SET_AMMO`): a dropped ammo-class item loads by entry
+/// The same ammo sub-fork as [`drain_container_uses`] (the one auto-equip sender `0x5e1480`
+/// forks ammo-class → `CMSG_SET_AMMO`): a dropped ammo-class item loads by entry
 /// instead, which is also the wire for the ammo slot's own drop (the XML routes it here via
 /// `AutoEquipCursorItem` — decision 0526).
 ///
@@ -90,6 +91,7 @@ pub(crate) fn send_auto_equip(
 pub(super) fn drain_container_autoequips(
     script: Option<NonSendMut<UiScript>>,
     items: Res<Items>,
+    objects: Objects,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
     commands: Res<NetCommands>,
     mut gate: crate::ui_bind_confirm::BindGate,
@@ -109,10 +111,11 @@ pub(super) fn drain_container_autoequips(
         let guid = self_q
             .iter()
             .next()
-            .and_then(|store| slot_guid(&store.0, bag, slot0, &items));
+            .and_then(|store| slot_guid(&store.0, bag, slot0, &objects));
         send_auto_equip(
             &mut script,
             &mut gate,
+            &objects,
             &items,
             &commands,
             bag_index,
@@ -127,7 +130,7 @@ pub(super) fn drain_container_autoequips(
 /// `cursor::bag_verbs`) and send them on the wire.
 ///
 /// **The destination is a BAG, not a slot** — that is the finding this drain exists to carry
-/// (wow-re `bag-verbs-law.md`): `CMSG_AUTOSTORE_BAG_ITEM` names `(srcbag, srcslot, dstbag)` and
+/// (`0x4c7c00` → `0x5e12e0`): `CMSG_AUTOSTORE_BAG_ITEM` names `(srcbag, srcslot, dstbag)` and
 /// the server picks where inside it the item lands, which is why an ordinary item dropped on a
 /// bag BUTTON goes in the bag rather than swapping with it. The destination bag byte is
 /// [`wire_pos`]'s own answer for that container's first slot (255 for the backpack, the bag's
@@ -197,8 +200,8 @@ pub(super) fn drain_bag_autostores(
 pub(super) fn drain_inventory_uses(
     script: Option<NonSendMut<UiScript>>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
-    targeting: crate::ui_action::cast_target::CastTargeting,
-    mut ladder: crate::ui_action::CastLadder,
+    targeting: crate::spell::cast_target::CastTargeting,
+    mut ladder: crate::spell::CastLadder,
     mut ui_errors: ResMut<crate::ui_action::UiErrorKeys>,
     mut gate: crate::ui_bind_confirm::BindGate,
 ) {
@@ -216,9 +219,9 @@ pub(super) fn drain_inventory_uses(
         let (guid, start_quest, spell_index, use_spell, entry, is_charter) = self_q
             .iter()
             .next()
-            .and_then(|store| slot_guid(&store.0, EQUIPMENT_BAG, slot, &ladder.items))
+            .and_then(|store| slot_guid(&store.0, EQUIPMENT_BAG, slot, &ladder.objects))
             .and_then(|guid| {
-                let entry = ladder.items.object(guid)?.object_entry()?;
+                let entry = ladder.objects.object(guid)?.object_entry()?;
                 let t = ladder.items.template(entry, guid, &ladder.commands)?;
                 // The wire's spell byte is a template BLOCK ordinal (decision 0666) — the
                 // template is already in hand here for `start_quest`, so name the real one.
@@ -262,13 +265,13 @@ pub(super) fn drain_container_uses(
     bank: Res<crate::ui_bank::BankOpen>,
     mut equip_sound: MessageWriter<crate::sound::AutoEquipSound>,
     mut item_text: ResMut<crate::ui_item_text::ItemTextOpen>,
-    targeting: crate::ui_action::cast_target::CastTargeting,
+    targeting: crate::spell::cast_target::CastTargeting,
     // The client-side pending ("gray") lock — the right-click-open arm arms it (decision 0916).
     mut pending_items: ResMut<PendingItemOps>,
     // The loot-target latch — the right-click-open arm is one of its five arm sites, and the one
     // that lets `SMSG_LOOT_RESPONSE`'s admission gate recognise an item loot (decision 1531).
     mut loot_latch: ResMut<crate::ui_loot::LootLatch>,
-    mut ladder: crate::ui_action::CastLadder,
+    mut ladder: crate::spell::CastLadder,
     mut ui_errors: ResMut<crate::ui_action::UiErrorKeys>,
     mut gate: crate::ui_bind_confirm::BindGate,
 ) {
@@ -286,7 +289,7 @@ pub(super) fn drain_container_uses(
         let item_guid = self_q
             .iter()
             .next()
-            .and_then(|store| slot_guid(&store.0, bag, slot0, &ladder.items));
+            .and_then(|store| slot_guid(&store.0, bag, slot0, &ladder.objects));
         match item_guid {
             Some(guid) => {
                 debug!("ui_items: repair lua bag {bag} slot {slot} (item {guid:#x})");
@@ -320,7 +323,7 @@ pub(super) fn drain_container_uses(
             let item_guid = self_q
                 .iter()
                 .next()
-                .and_then(|store| slot_guid(&store.0, bag, slot0.unwrap_or(0), &ladder.items));
+                .and_then(|store| slot_guid(&store.0, bag, slot0.unwrap_or(0), &ladder.objects));
             match item_guid {
                 Some(guid) => {
                     debug!("ui_items: sell lua bag {bag} slot {slot} (item {guid:#x})");
@@ -370,9 +373,9 @@ pub(super) fn drain_container_uses(
         let clicked = self_q
             .iter()
             .next()
-            .and_then(|store| slot_guid(&store.0, bag, slot0.unwrap_or(0), &ladder.items))
+            .and_then(|store| slot_guid(&store.0, bag, slot0.unwrap_or(0), &ladder.objects))
             .and_then(|guid| {
-                let obj = ladder.items.object(guid)?;
+                let obj = ladder.objects.object(guid)?;
                 let inst_flags = obj.item_flags().unwrap_or(0);
                 let item_text_id = obj.item_text_id().unwrap_or(0);
                 let entry = obj.object_entry()?;
@@ -396,20 +399,20 @@ pub(super) fn drain_container_uses(
                 })
             });
 
-        // The reference's equip-vs-use fork (`0x4fa3b9`/`0x4fa3bd`, wow-re `right-click-open.md`
-        // §2), with the ammo sub-fork `cursor-dragdrop-slots.md` pins: the auto-equip sender
-        // `0x5e1480` sends `CMSG_SET_AMMO` (the item entry) for an ammo-class item,
-        // `CMSG_AUTOEQUIP_ITEM` for any other equippable (inventoryType != 0 — weapons, armor,
-        // bags). display_id feeds the synthetic pickup→place auto-equip sound (this path never
-        // moves the cursor; a drag already gets that pair via the cursor-payload transitions).
+        // The reference's equip-vs-use fork (`0x4fa3b9`/`0x4fa3bd`), with the ammo sub-fork: the
+        // auto-equip sender `0x5e1480` sends `CMSG_SET_AMMO` (the item entry) for an ammo-class
+        // item, `CMSG_AUTOEQUIP_ITEM` for any other equippable (inventoryType != 0 — weapons,
+        // armor, bags). display_id feeds the synthetic pickup→place auto-equip sound (this path
+        // never moves the cursor; a drag already gets that pair via the cursor-payload
+        // transitions).
         //
         // The arm carries the reference's own **quest guard** (`0x4fa3bd`–`0x4fa3cc`, decision
         // 0664): it equips only when `StartQuest` (`[rec+0x1a8]`) is 0, so a quest-starter falls
         // through *whatever* its inventoryType — the five equippable ones (Pendant of Myzrael,
         // Arena Master, …) offer their quest on a right-click, they don't put themselves on.
         //
-        // **Everything below this fork is `0x5d8d00`, the USE dispatcher, in ITS OWN order**
-        // (wow-re `right-click-open.md` §3) — an equippable item never reaches any of it.
+        // **Everything below this fork is `0x5d8d00`, the USE dispatcher, in ITS OWN order** — an
+        // equippable item never reaches any of it.
         if let Some(c) = clicked.filter(|c| c.start_quest == 0 && c.inventory_type != 0) {
             // Through the one sender (decision 1750): it owns the ammo fork AND the soulbind
             // deferral. A deferred equip plays no sound — the reference's own equip kit rides the
@@ -417,6 +420,7 @@ pub(super) fn drain_container_uses(
             if send_auto_equip(
                 &mut script,
                 &mut gate,
+                &ladder.objects,
                 &ladder.items,
                 &ladder.commands,
                 bag_index,
@@ -544,7 +548,7 @@ pub(super) fn drain_container_uses(
             );
             // **The loot latch, armed before the send** — arm site four of five (`0x5edcc0`, in
             // this same emitter `0x5edc80`, immediately ahead of the lock setter and the
-            // `0x5edce5 push 0xac`; wow-re `loot-anim-leg.md` §5, byte-verified). The latch is
+            // `0x5edce5 push 0xac`). The latch is
             // the **item's own guid** (`[[edi+8]+0]`) because that is what the answer names:
             // vmangos' `HandleOpenItemOpcode` ends in `SendLoot(pItem->GetObjectGuid(),
             // LOOT_CORPSE)`, so `SMSG_LOOT_RESPONSE` comes back on the item guid with wire type
@@ -557,11 +561,12 @@ pub(super) fn drain_container_uses(
             loot_latch.0 = Some(c.guid);
             // **The gray lock, armed before the send** — the reference's emitter `0x5edc80` calls
             // the lock setter `0x4953e0` at `0x5edcd9` and only then ships `CMSG_OPEN_ITEM`
-            // (wow-re `inventory-change-failure-display.md` §8, decision 0916). So a clam,
+            // (decision 0916). So a clam,
             // lockbox or loot bag greys the instant you right-click it and stays grey until the
-            // server answers — the loot landing (a resolving field update) or a refusal
-            // (`EQUIP_ERR_ITEM_LOCKED` on a still-locked junkbox), both of which
-            // `PendingItemOps` already clears on.
+            // open resolves — the emptied item vanishing (a resolving field update), a refusal
+            // (`EQUIP_ERR_ITEM_LOCKED` on a still-locked junkbox), or the window closed with loot
+            // left, whose `SMSG_LOOT_RELEASE_RESPONSE` unlocks it by guid (`ui_loot::net`'s
+            // `loot_release_response`, the reference's `UnlockItem` at `48f299`).
             //
             // Deliberately NOT armed on the gift-unwrap arm above, which sends the same opcode:
             // its emitter `0x5edd60` contains neither call — no lock setter and no latch write.
@@ -569,7 +574,7 @@ pub(super) fn drain_container_uses(
             let (guid, count) = self_q
                 .iter()
                 .next()
-                .map(|store| slot_guid_count(Some(store), bag, slot, &ladder.items))
+                .map(|store| slot_guid_count(Some(store), bag, slot, &ladder.objects))
                 .unwrap_or((0, 0));
             pending_items.add([(bag, slot, guid, count)]);
             script.fire_event("ITEM_LOCK_CHANGED", Vec::new());
@@ -662,6 +667,7 @@ pub(super) fn drain_container_moves(
     script: Option<NonSendMut<UiScript>>,
     commands: Res<NetCommands>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
+    objects: Objects,
     items: Res<Items>,
     mut pending: ResMut<PendingItemOps>,
     mut gate: crate::ui_bind_confirm::BindGate,
@@ -699,6 +705,7 @@ pub(super) fn drain_container_moves(
         send_container_move(
             &mut script,
             &mut gate,
+            &objects,
             &items,
             &commands,
             store,
@@ -727,6 +734,7 @@ fn is_equip_position(bag_index: u8, slot: u8) -> bool {
 pub(crate) fn send_container_move(
     script: &mut UiScript,
     gate: &mut crate::ui_bind_confirm::BindGate,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
     store: Option<&ObjectStore>,
@@ -758,9 +766,9 @@ pub(crate) fn send_container_move(
                 (mv.dst_bag, mv.dst_slot)
             };
             let slot0 = u8::try_from(item_slot.saturating_sub(1)).unwrap_or(0);
-            let guid = store.and_then(|s| slot_guid(&s.0, item_bag, slot0, items));
+            let guid = store.and_then(|s| slot_guid(&s.0, item_bag, slot0, objects));
             if let Some(guid) = guid {
-                if gate.equip_binds(script, items, commands, guid) {
+                if gate.equip_binds(script, objects, items, commands, guid) {
                     gate.defer_equip(
                         script,
                         crate::ui_bind_confirm::PendingEquip::Swap {
@@ -819,8 +827,8 @@ pub(crate) fn send_container_move(
         // The pending lock: both ends, baselined on their CURRENT (guid, count) — the resolving
         // clear then watches for either to move (an empty destination baselines (0, 0) and watches
         // for an item to land there).
-        let (src_guid, src_count) = slot_guid_count(store, mv.src_bag, mv.src_slot, items);
-        let (dst_guid, dst_count) = slot_guid_count(store, mv.dst_bag, mv.dst_slot, items);
+        let (src_guid, src_count) = slot_guid_count(store, mv.src_bag, mv.src_slot, objects);
+        let (dst_guid, dst_count) = slot_guid_count(store, mv.dst_bag, mv.dst_slot, objects);
         pending.add([
             (mv.src_bag, mv.src_slot, src_guid, src_count),
             (mv.dst_bag, mv.dst_slot, dst_guid, dst_count),
@@ -845,7 +853,7 @@ pub(super) fn drain_container_destroys(
     script: Option<NonSendMut<UiScript>>,
     commands: Res<NetCommands>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
-    items: Res<Items>,
+    objects: Objects,
     mut pending: ResMut<PendingItemOps>,
 ) {
     let Some(mut script) = script else {
@@ -864,7 +872,7 @@ pub(super) fn drain_container_destroys(
             slot: wire_slot,
             count,
         });
-        let (guid, stack) = slot_guid_count(store, bag, slot, &items);
+        let (guid, stack) = slot_guid_count(store, bag, slot, &objects);
         pending.add([(bag, slot, guid, stack)]);
         script.fire_event("ITEM_LOCK_CHANGED", Vec::new());
     }
@@ -900,19 +908,20 @@ mod tests {
             .init_resource::<crate::ui_loot::LootLatch>()
             .init_resource::<crate::target::Selection>()
             .init_resource::<crate::net::SelfGuid>()
-            .init_resource::<crate::ui_action::cast_target::AutoSelfCast>()
+            .init_resource::<crate::spell::cast_target::AutoSelfCast>()
             .init_resource::<crate::net::Reputations>()
             .init_resource::<crate::player::Player>()
-            .init_resource::<crate::ui_cast::PendingCast>()
-            .init_resource::<crate::ui_cast::QueuedMeleeSpell>()
-            .init_resource::<crate::cooldowns::Cooldowns>()
-            .init_resource::<crate::spell_mods::SpellModifiers>()
+            .init_resource::<crate::spell::PendingCast>()
+            .init_resource::<crate::spell::QueuedMeleeSpell>()
+            .init_resource::<crate::spell::Cooldowns>()
+            .init_resource::<crate::spell::SpellModifiers>()
             .init_resource::<crate::ui_action::CastErrors>()
             .init_resource::<crate::ui_action::UiErrorKeys>()
-            .init_resource::<crate::ui_action::AutoRepeatActive>()
+            .init_resource::<crate::spell::AutoRepeatActive>()
             .init_resource::<crate::ui_tradeskill::TradeSkillOpens>()
-            .init_resource::<crate::ui_action::targeting::SpellTargeting>()
+            .init_resource::<crate::spell::targeting::SpellTargeting>()
             .init_resource::<Items>()
+            .init_resource::<crate::net::GuidIndex>()
             .insert_resource(NetCommands(tx));
 
         // The player, holding the clam in backpack slot 1.
@@ -923,13 +932,15 @@ mod tests {
                 (F_PACK_SLOT_1 + 1, (CLAM >> 32) as u32),
             ])),
         ));
-        // The item object and its landed template — LOOTABLE, so the dispatcher's open arm claims
-        // the click (`ItemInfo::opens_loot`).
-        let mut items = app.world_mut().resource_mut::<Items>();
-        items.insert_object(
+        // The item object (an entity in the one index, 2334) and its landed template —
+        // LOOTABLE, so the dispatcher's open arm claims the click (`ItemInfo::opens_loot`).
+        crate::items::test_spawn_item(
+            app.world_mut(),
             CLAM,
             ObjectFields::from_pairs(&[(F_OBJECT_ENTRY, CLAM_ENTRY)]),
+            false,
         );
+        let mut items = app.world_mut().resource_mut::<Items>();
         items.insert_template(
             CLAM_ENTRY,
             Some(ItemInfo {
@@ -948,7 +959,7 @@ mod tests {
     }
 
     /// **The clam regression (decision 1531).** Arm site four of five: the `CMSG_OPEN_ITEM` send
-    /// latches the ITEM's own guid (`0x5edcc0`, wow-re `loot-anim-leg.md` §5). It is not cosmetic
+    /// latches the ITEM's own guid (`0x5edcc0`). It is not cosmetic
     /// and it is not about the pose — vmangos answers this opcode with `SendLoot(item guid,
     /// LOOT_CORPSE)`, i.e. `SMSG_LOOT_RESPONSE` type **1** on that same guid (live-verified by
     /// `benilla-world --open-item`), and 1477's admission gate *refuses* a type-1 answer against a
@@ -980,8 +991,8 @@ mod tests {
     }
 
     /// **Right-clicking wrapping paper arms the wrap and sends NOTHING** (decision 1934) — the
-    /// same dispatcher arm the wrapped-gift unwrap takes, on its other side. This is the bug the
-    /// carve found: benilla fell through to `CMSG_USE_ITEM`, which casts a spell the paper does
+    /// same dispatcher arm the wrapped-gift unwrap takes, on its other side. This is the bug:
+    /// benilla fell through to `CMSG_USE_ITEM`, which casts a spell the paper does
     /// not have.
     #[test]
     fn a_wrapper_right_click_arms_the_cursor_and_ships_no_packet() {
@@ -1041,6 +1052,7 @@ pub(super) fn drain_bind_confirm_answers(
     script: Option<NonSendMut<UiScript>>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
     mut pending: ResMut<PendingItemOps>,
+    objects: Objects,
     items: Res<Items>,
     commands: Res<NetCommands>,
     mut gate: crate::ui_bind_confirm::BindGate,
@@ -1073,6 +1085,7 @@ pub(super) fn drain_bind_confirm_answers(
                 send_container_move(
                     &mut script,
                     &mut gate,
+                    &objects,
                     &items,
                     &commands,
                     store,
@@ -1095,6 +1108,7 @@ pub(super) fn drain_bind_confirm_answers(
                 send_auto_equip(
                     &mut script,
                     &mut gate,
+                    &objects,
                     &items,
                     &commands,
                     bag_index,
@@ -1114,8 +1128,8 @@ pub(super) fn drain_bind_confirm_answers(
 /// taken on the first, so a doubled accept re-uses nothing.
 pub(super) fn drain_bind_on_use_confirms(
     script: Option<NonSendMut<UiScript>>,
-    targeting: crate::ui_action::cast_target::CastTargeting,
-    mut ladder: crate::ui_action::CastLadder,
+    targeting: crate::spell::cast_target::CastTargeting,
+    mut ladder: crate::spell::CastLadder,
     mut ui_errors: ResMut<crate::ui_action::UiErrorKeys>,
     mut gate: crate::ui_bind_confirm::BindGate,
 ) {
@@ -1235,6 +1249,7 @@ mod bind_confirm_tests {
             .init_resource::<crate::ui_bind_confirm::PendingEquips>()
             .init_resource::<crate::ui_bind_confirm::PendingBindOnUse>()
             .init_resource::<Items>()
+            .init_resource::<crate::net::GuidIndex>()
             .insert_resource(NetCommands(tx));
 
         app.world_mut().spawn((
@@ -1244,14 +1259,16 @@ mod bind_confirm_tests {
                 (F_PACK_SLOT_1 + 1, (AXE_GUID >> 32) as u32),
             ])),
         ));
-        let mut items = app.world_mut().resource_mut::<Items>();
-        items.insert_object(
+        crate::items::test_spawn_item(
+            app.world_mut(),
             AXE_GUID,
             ObjectFields::from_pairs(&[
                 (F_OBJECT_ENTRY, FLURRY_AXE),
                 (F_ITEM_FLAGS, u32::from(already_bound)),
             ]),
+            false,
         );
+        let mut items = app.world_mut().resource_mut::<Items>();
         items.insert_template(
             FLURRY_AXE,
             Some(ItemInfo {
@@ -1297,6 +1314,7 @@ mod bind_confirm_tests {
     /// that fed it, where the reference defers inside the call that consumed the cursor.
     #[test]
     fn placing_a_boe_on_the_doll_asks_and_survives_its_own_cursor_update() {
+        benilla_formats::wow_data_or_skip!();
         let (mut app, rx) = place_the_axe_on_the_doll();
         assert!(
             rx.try_iter().next().is_none(),
@@ -1362,6 +1380,7 @@ mod bind_confirm_tests {
     /// would be unanswerable.
     #[test]
     fn accepting_re_issues_the_place_and_does_not_ask_again() {
+        benilla_formats::wow_data_or_skip!();
         let (mut app, rx) = place_the_axe_on_the_doll();
         app.world_mut()
             .non_send_resource_mut::<UiScript>()
@@ -1410,6 +1429,7 @@ mod bind_confirm_tests {
     /// the second call finds the element already free.
     #[test]
     fn cancelling_sends_nothing_and_the_doubled_cancel_is_harmless() {
+        benilla_formats::wow_data_or_skip!();
         let (mut app, rx) = place_the_axe_on_the_doll();
         app.world_mut()
             .non_send_resource_mut::<UiScript>()
@@ -1434,10 +1454,11 @@ mod bind_confirm_tests {
     }
 
     /// The equip predicate is `bonding == 2` and **nothing else about the item** — no quality leg
-    /// at all, which is the half wow-re refuted (benilla was about to carry the loot arm's
+    /// at all (`0x5e0e54`; benilla was about to carry the loot arm's
     /// `quality >= 2` across). Every other bonding value places straight through.
     #[test]
     fn only_bind_on_equip_defers_the_place() {
+        benilla_formats::wow_data_or_skip!();
         for (bonding, why) in [
             (0u32, "no bind"),
             (1, "bind on PICKUP is the loot arm's value, not this one"),
@@ -1463,6 +1484,7 @@ mod bind_confirm_tests {
     /// (The loot arm's `quality >= 2` would have silenced exactly this case.)
     #[test]
     fn a_white_bind_on_equip_item_still_asks() {
+        benilla_formats::wow_data_or_skip!();
         let (mut app, rx) = place_the_axe_with(2, 1, false);
         app.world_mut()
             .non_send_resource_mut::<UiScript>()
@@ -1478,6 +1500,7 @@ mod bind_confirm_tests {
     /// cursor and the tooltip's Soulbound override use (decisions 0928, 1562).
     #[test]
     fn an_already_bound_item_places_without_asking() {
+        benilla_formats::wow_data_or_skip!();
         let (mut app, rx) = place_the_axe_with(2, 4, true);
         app.world_mut()
             .non_send_resource_mut::<UiScript>()
@@ -1495,12 +1518,14 @@ mod bind_confirm_tests {
     /// this gate could exist in a single place.
     #[test]
     fn auto_equipping_a_boe_asks_and_the_accept_re_issues() {
+        benilla_formats::wow_data_or_skip!();
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut app = App::new();
         app.init_resource::<PendingItemOps>()
             .init_resource::<crate::ui_bind_confirm::PendingEquips>()
             .init_resource::<crate::ui_bind_confirm::PendingBindOnUse>()
             .init_resource::<Items>()
+            .init_resource::<crate::net::GuidIndex>()
             .insert_resource(NetCommands(tx));
         app.world_mut().spawn((
             SelfPlayer,
@@ -1509,11 +1534,13 @@ mod bind_confirm_tests {
                 (F_PACK_SLOT_1 + 1, (AXE_GUID >> 32) as u32),
             ])),
         ));
-        let mut items = app.world_mut().resource_mut::<Items>();
-        items.insert_object(
+        crate::items::test_spawn_item(
+            app.world_mut(),
             AXE_GUID,
             ObjectFields::from_pairs(&[(F_OBJECT_ENTRY, FLURRY_AXE)]),
+            false,
         );
+        let mut items = app.world_mut().resource_mut::<Items>();
         items.insert_template(
             FLURRY_AXE,
             Some(ItemInfo {
@@ -1580,6 +1607,7 @@ mod bind_confirm_tests {
     /// level above the player's, the gate's first leg.
     #[test]
     fn an_unusable_item_is_never_asked_about() {
+        benilla_formats::wow_data_or_skip!();
         let (mut app, rx) = place_the_axe_with(2, 4, false);
         // Re-push the player's requirement state and a template the level leg refuses. (The
         // fixture's own push leaves `level == 0`, the "decline to judge" state, so this test has
@@ -1625,7 +1653,7 @@ mod bind_confirm_tests {
         );
     }
 
-    /// **The USE arm** (`0x5d8d00`, event 290) end to end, and the correction wow-re's follow-up
+    /// **The USE arm** (`0x5d8d00`, event 290) end to end, and the correction the reference
     /// forced. Right-clicking a bind-on-**use** item in a bag raises `USE_BIND` and sends nothing;
     /// `ConfirmBindOnUse()` re-issues the use with `suppress` set.
     ///
@@ -1649,19 +1677,20 @@ mod bind_confirm_tests {
             .init_resource::<crate::ui_loot::LootLatch>()
             .init_resource::<crate::target::Selection>()
             .init_resource::<crate::net::SelfGuid>()
-            .init_resource::<crate::ui_action::cast_target::AutoSelfCast>()
+            .init_resource::<crate::spell::cast_target::AutoSelfCast>()
             .init_resource::<crate::net::Reputations>()
             .init_resource::<crate::player::Player>()
-            .init_resource::<crate::ui_cast::PendingCast>()
-            .init_resource::<crate::ui_cast::QueuedMeleeSpell>()
-            .init_resource::<crate::cooldowns::Cooldowns>()
-            .init_resource::<crate::spell_mods::SpellModifiers>()
+            .init_resource::<crate::spell::PendingCast>()
+            .init_resource::<crate::spell::QueuedMeleeSpell>()
+            .init_resource::<crate::spell::Cooldowns>()
+            .init_resource::<crate::spell::SpellModifiers>()
             .init_resource::<crate::ui_action::CastErrors>()
             .init_resource::<crate::ui_action::UiErrorKeys>()
-            .init_resource::<crate::ui_action::AutoRepeatActive>()
+            .init_resource::<crate::spell::AutoRepeatActive>()
             .init_resource::<crate::ui_tradeskill::TradeSkillOpens>()
-            .init_resource::<crate::ui_action::targeting::SpellTargeting>()
+            .init_resource::<crate::spell::targeting::SpellTargeting>()
             .init_resource::<Items>()
+            .init_resource::<crate::net::GuidIndex>()
             .insert_resource(NetCommands(tx));
         app.world_mut().spawn((
             SelfPlayer,
@@ -1670,11 +1699,13 @@ mod bind_confirm_tests {
                 (F_PACK_SLOT_1 + 1, (AXE_GUID >> 32) as u32),
             ])),
         ));
-        let mut items = app.world_mut().resource_mut::<Items>();
-        items.insert_object(
+        crate::items::test_spawn_item(
+            app.world_mut(),
             AXE_GUID,
             ObjectFields::from_pairs(&[(F_OBJECT_ENTRY, FLURRY_AXE)]),
+            false,
         );
+        let mut items = app.world_mut().resource_mut::<Items>();
         let mut template = crate::items::test_template("A Bind-On-Use Thing");
         template.bonding = 3;
         template.quality = 3;
@@ -1712,6 +1743,7 @@ mod bind_confirm_tests {
 
     #[test]
     fn right_clicking_a_bind_on_use_item_asks_before_using_it() {
+        benilla_formats::wow_data_or_skip!();
         let (mut app, rx) = right_click_a_bind_on_use_item(false);
         assert!(
             rx.try_iter().next().is_none(),
@@ -1746,10 +1778,12 @@ mod bind_confirm_tests {
         );
     }
 
-    /// The RE's correction, pinned: an item with **no usable on-use spell** still raises the bind
-    /// question. Under the first placement (inside the plain-cast route only) this asked nothing.
+    /// The correction, pinned (`0x5d91d3`): an item with **no usable on-use spell** still raises
+    /// the bind question. Under the first placement (inside the plain-cast route only) this asked
+    /// nothing.
     #[test]
     fn a_bind_on_use_item_with_no_on_use_spell_still_asks() {
+        benilla_formats::wow_data_or_skip!();
         let (mut app, rx) = right_click_a_bind_on_use_item(true);
         app.world_mut()
             .non_send_resource_mut::<UiScript>()
diff --git a/crates/benilla-app/src/ui_items/equip_error.rs b/crates/benilla-app/src/ui_items/equip_error.rs
index b286a667..cd211b0a 100644
--- a/crates/benilla-app/src/ui_items/equip_error.rs
+++ b/crates/benilla-app/src/ui_items/equip_error.rs
@@ -12,8 +12,7 @@
 //! shapeshifted mount press answers 59 **and** `SPELL_FAILED_NO_ITEMS_WHILE_SHAPESHIFTED` — so
 //! anything printed for it doubles the refusal (director's report B198).
 //!
-//! The reference silences it **through the data, not through control flow** (wow-re
-//! `system/ui/scratch/inventory-change-failure-display.md`, §5 trio, dde90376). Handler
+//! The reference silences it **through the data, not through control flow**. Handler
 //! `0x5e3991` maps the reason through the 67-wide errorId jump table `0x622794` into the error
 //! registry `0xb4b498` and calls `CGGameUI::DisplayError 0x496720` unconditionally. 59's slot is
 //! populated and non-null — errorId 362, key `ERR_CANT_BE_DISENCHANTED` — but that key is simply
@@ -28,8 +27,8 @@
 /// own loaded `GlobalStrings.lua` at the drain. **Total** — every reason has a key, because the
 /// reference's own lookup is (see the module doc); a key with no string displays nothing.
 ///
-/// The FULL build-5875 set, VERIFIED key-by-key against the binary's errorId table `0x622794`
-/// (wow-re, above) — which agreed with the vmangos `ItemDefines.h` tag comments on 66 of 67
+/// The FULL build-5875 set, read key by key off the binary's errorId table `0x622794` — which
+/// agreed with the vmangos `ItemDefines.h` tag comments on 66 of 67
 /// entries. Positions come from that enum (sequential with every `#if` band ≤ 5875 included:
 /// stunned=37, dead=38, INVENTORY_FULL=50; an earlier table had the TBC-era 39/40 for
 /// stunned/dead — on this wire those are CANT_DO_RIGHT_NOW / INT_BAG_ERROR). Reason 1's string
diff --git a/crates/benilla-app/src/ui_items/feed.rs b/crates/benilla-app/src/ui_items/feed.rs
index 31ba0cba..b679ec53 100644
--- a/crates/benilla-app/src/ui_items/feed.rs
+++ b/crates/benilla-app/src/ui_items/feed.rs
@@ -11,7 +11,7 @@ use benilla_ui::script::{ContainerSlot, ContainerState, ScriptValue, UiScript};
 
 use crate::entities::ItemDisplays;
 use crate::items::Items;
-use crate::net::{NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{NetCommands, ObjectStore, Objects, SelfPlayer};
 use crate::pending_item_ops::{LockTransitions, PendingItemOps};
 use crate::ui_script::gate;
 
@@ -31,9 +31,10 @@ pub(crate) struct FeedMemory {
     /// every frame. It is the gate the entire keyring UI hangs off, and "the keyring never
     /// appeared" is otherwise indistinguishable from "the button is mis-anchored".
     had_key: bool,
-    /// The gate's counter memories (1439) — the four stores whose lazy `&mut` resolves poison
-    /// `is_changed` for this feed, watched by their explicit counters instead.
-    items_objects: gate::Watch,
+    /// The gate's counter memories (1439) — the stores whose lazy `&mut` resolves poison
+    /// `is_changed` for this feed, watched by their explicit counters instead. The item OBJECTS
+    /// left this list with 2334: an instance is an entity, so its edges come off the ordinary
+    /// `Changed`/removal watch ([`crate::items::ItemChanges`]).
     items_templates: gate::Watch,
     cooldown_epoch: gate::Watch,
     names_generation: gate::Watch,
@@ -41,8 +42,9 @@ pub(crate) struct FeedMemory {
     /// what a charter slot's tooltip lines are built from. Lazy, so its arrival moves nothing else
     /// here (the same reason `names_generation` exists one line up).
     petition_records: gate::Watch,
-    /// `Items::countdown_display_epoch` — one step per displayable countdown change (the slot
-    /// views read second-floored countdowns), including the last elapse's collapsing push.
+    /// `ItemChanges::countdown_steps` — one step per displayable countdown change (the slot
+    /// views read second-floored countdowns), including the last elapse's collapsing push; a
+    /// landing is the item's own change tick (decision 2340).
     enchant_deadlines: gate::Watch,
     /// The item guid **of the bag itself** in each of the ten bag slots — container ids 1..=10
     /// (the four equipped, then the six bank bags), indexed `id − 1`. Diffed frame to frame for
@@ -137,7 +139,7 @@ fn charges_count(spells: &[benilla_protocol::messages::ItemSpellEntry]) -> i32 {
 ///
 /// Keys rather than an eight-string table (decision 2045): the bare tokens, not the `_FEMALE`
 /// twins, which is the spelling the reference itself uses wherever it builds a standing label
-/// (`FACTION_STANDING_LABEL%d` `0x84b5dc`, wow-re `ui/scratch/quest-leaderboard-law.md` §5).
+/// (`FACTION_STANDING_LABEL%d` `0x84b5dc`).
 /// `None` for an install that does not carry the row — the line then names no standing.
 fn standing_label(rank: u32, get: &dyn Fn(&str) -> Option<String>) -> Option<String> {
     get(&format!("FACTION_STANDING_LABEL{}", rank.min(7) + 1))
@@ -228,8 +230,7 @@ fn template_view(
         required_honor_rank: t.required_honor_rank,
         required_city_rank: t.required_city_rank,
         // `ITEM_REQ_REPUTATION` ("%s - %s" after its own "Requires ") — `0x854b8c`, the key the
-        // reference's own item tooltip builds this line with (wow-re
-        // `ui/scratch/tooltip-content-law.md` §"required-spell / honor-rank"). Both holes are
+        // reference's own item tooltip builds this line with. Both holes are
         // filled in the template's order; an install missing either key shows no line.
         required_rep_line: (t.required_rep_faction != 0)
             .then(|| {
@@ -262,7 +263,7 @@ fn template_view(
     }
 }
 
-/// The §22 SET-block feed: answer the engine's ask-once set ids from ItemSet.dbc, joining
+/// The item SET-block feed: answer the engine's ask-once set ids from ItemSet.dbc, joining
 /// member NAMES from the template cache (each miss fires its own `CMSG_ITEM_QUERY` through
 /// [`Items::template`], like the real client querying set members) and bonus TEXT from the
 /// spell catalog's `$`-engine. A set with members still in flight stays pending and re-pushes
@@ -606,11 +607,12 @@ pub(super) fn feed_player_req(
 /// exists before its query answers.
 fn resolve_slot(
     guid: u64,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     rolls: crate::items::RollCatalogs,
     commands: &NetCommands,
-    cooldowns: &crate::cooldowns::Cooldowns,
+    cooldowns: &crate::spell::Cooldowns,
     spells: Option<&benilla_formats::SpellCatalog>,
     names: &crate::names::NameCache,
     // The petition record cache, for a charter slot's tooltip lines — a LAZY fill, so it is taken
@@ -626,15 +628,15 @@ fn resolve_slot(
     if guid == 0 {
         return None;
     }
-    // The temporary-enchant countdowns, read off the deadline store BEFORE the object borrow below
-    // (both live on `Items`): one `Option<ms>` per enchant slot.
-    let enchant_ms: [Option<u64>; 7] =
-        std::array::from_fn(|s| items.enchant_remaining_display_ms(guid, s as u32));
-    // The item's own expiry countdown, read off the same deadline store and floored the same way
-    // — `SMSG_ITEM_TIME_UPDATE`'s only surface (decision 1933).
-    let duration_ms = items.duration_remaining_display_ms(guid);
+    // The item's own countdown cells (decision 2340): one `Option<ms>` per temporary-enchant
+    // slot, and its lifetime — `SMSG_ITEM_TIME_UPDATE`'s only surface (decision 1933) — both
+    // second-floored for the snapshot.
+    let countdowns = objects.countdowns(guid);
+    let enchant_ms: [Option<u64>; crate::items::ENCHANT_SLOTS] =
+        std::array::from_fn(|s| countdowns.and_then(|c| c.enchant_remaining_display_ms(s as u32)));
+    let duration_ms = countdowns.and_then(|c| c.lifetime_remaining_display_ms());
     let (entry, count, durability, readable, creator, flags, already_bound, roll, enchant_lines) =
-        match items.object(guid) {
+        match objects.object(guid) {
             Some(fields) => (
                 fields.object_entry().unwrap_or(0),
                 fields.item_stack_count().unwrap_or(1),
@@ -657,7 +659,7 @@ fn resolve_slot(
                     .and_then(|g| names.resolve(g, commands).map(str::to_string)),
                 // `ITEM_FIELD_FLAGS` — the tooltip's UNLOCKED (0x4) / WRAPPED (0x8) sub-gates.
                 fields.item_flags().unwrap_or(0),
-                // `0x5da2c0` — soulbound, or carrying a binding enchant: the §6 Soulbound
+                // `0x5da2c0` — soulbound, or carrying a binding enchant: the Soulbound
                 // override (B310). Read off the raw descriptor, not off the enchant LINES below.
                 crate::items::already_bound(fields, rolls.enchants),
                 // `ITEM_FIELD_RANDOM_PROPERTIES_ID` — the roll behind the NAME's "of the Bear"
@@ -716,7 +718,7 @@ fn resolve_slot(
         // rule.
         petition: (t.flags & benilla_protocol::messages::ITEM_FLAG_CHARTER != 0)
             .then(|| {
-                let id = items
+                let id = objects
                     .object(guid)
                     .and_then(|f| f.item_enchant(0))
                     .unwrap_or(0);
@@ -775,13 +777,14 @@ fn resolve_slot(
 /// than naming the quiver's own type (`benilla_formats::itembagfamily`, and the DBC read there).
 ///
 /// The bank-bag leg (63..=68) is ours by symmetry rather than byte-pinned: the reference bounds
-/// this on `[player+0x1d38]`, whose value wow-re did not resolve, so whether a bank bag reaches
+/// this on `[player+0x1d38]`, whose value is unresolved, so whether a bank bag reaches
 /// the substitution or falls to the generic line is unverified. Both outcomes are ordinary
 /// sentences; resolving it is the strictly more useful one, and it is flagged here rather than
 /// silently assumed.
 fn bag_family_name(
     player: Option<&ObjectStore>,
     bag_slot: u8,
+    objects: &Objects,
     items: &Items,
     families: Option<&benilla_formats::ItemBagFamilyCatalog>,
     commands: &NetCommands,
@@ -799,7 +802,7 @@ fn bag_family_name(
         _ => None,
     }
     .filter(|&g| g != 0)?;
-    let entry = items.object(guid)?.object_entry().filter(|&e| e != 0)?;
+    let entry = objects.object(guid)?.object_entry().filter(|&e| e != 0)?;
     let family = items.template(entry, guid, commands)?.bag_family;
     families.name(family).map(str::to_string)
 }
@@ -820,7 +823,7 @@ fn bag_family_name(
 /// feeds because neither of them owns the clear any more.
 pub(crate) fn resolve_item_locks(
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
-    items: Res<Items>,
+    objects: Objects,
     mut pending: ResMut<PendingItemOps>,
     mut transitions: ResMut<LockTransitions>,
 ) {
@@ -833,7 +836,7 @@ pub(crate) fn resolve_item_locks(
     }
     transitions
         .0
-        .extend(pending.resolve(|bag, slot1| slot_guid_count(player, bag, slot1, &items)));
+        .extend(pending.resolve(|bag, slot1| slot_guid_count(player, bag, slot1, &objects)));
 }
 
 #[allow(clippy::type_complexity)] // the param list IS the input set
@@ -850,14 +853,12 @@ pub(crate) fn feed_containers(
         Option<Res<crate::items::Enchants>>,
         Option<Res<crate::items::RandomProperties>>,
     ),
-    // The two self-descriptor legs in one param (the 16-SystemParam ceiling): the store the
-    // slot arrays read, and its change tick — the gate's cheapest input (1439).
-    self_q: (
-        Query<&ObjectStore, With<SelfPlayer>>,
-        Query<(), (With<SelfPlayer>, Changed<ObjectStore>)>,
-    ),
+    // The inventory read (2334): the self store the slot arrays come off and its change tick —
+    // the gate's cheapest input (1439) — the object lookup the guids resolve through, and the
+    // item entities' own change watch.
+    mut inv: crate::items::Inventory,
     commands: Res<NetCommands>,
-    cooldowns: Res<crate::cooldowns::Cooldowns>,
+    cooldowns: Res<crate::spell::Cooldowns>,
     spells: Option<Res<crate::ui_action::Spells>>,
     // The refusals and where they land, as one param (the 16-SystemParam ceiling this signature
     // already sits at): the queue, and `show_messages`' chat + sound sinks (1815).
@@ -865,7 +866,9 @@ pub(crate) fn feed_containers(
     // Reason 16's `%s` source (decision 0916); absent = every 16 keeps the generic line.
     bag_families: Option<Res<crate::ui_items::ItemBagFamilies>>,
     pending: Res<PendingItemOps>,
-    mut lock_cleared: ResMut<LockTransitions>,
+    // The two handler-fed queues this feed fires for (the 16-SystemParam ceiling): the lock
+    // transitions (`ITEM_LOCK_CHANGED`) and the server-opened containers (`BAG_OPEN`, 2339).
+    queues: (ResMut<LockTransitions>, ResMut<super::net::BagOpens>),
     names: Res<crate::names::NameCache>,
     // Paired into one param (the 16-SystemParam ceiling this signature already sits at): the UI
     // clock, and the petition record cache a charter slot's tooltip lines read — `ResMut` because
@@ -881,6 +884,7 @@ pub(crate) fn feed_containers(
     };
     let (clock, mut petitions) = clock_and_petitions;
     let (mut equip_errors, mut sink) = equip;
+    let (mut lock_cleared, mut opens) = queues;
     let (memory, vm_reset) = memory.get_reset(&script);
     // The gate (1439): the snapshot below is a function of the self descriptor's slot arrays,
     // the item stores (both epochs — `is_changed` on `Items`/`NameCache`/`Cooldowns` is
@@ -890,7 +894,7 @@ pub(crate) fn feed_containers(
     // is deliberately NOT an input: the pushed cooldown triple carries the ABSOLUTE start
     // (frame-stable, the memory struct's own doc), and natural expiry moves the store's
     // `feed_epoch` through the prune.
-    let objects_moved = memory.items_objects.moved(items.object_epoch());
+    let objects_moved = inv.changes.moved();
     let templates_moved = memory.items_templates.moved(items.template_epoch());
     let cooldowns_moved = memory.cooldown_epoch.moved(cooldowns.feed_epoch());
     let names_moved = memory.names_generation.moved(names.generation());
@@ -900,10 +904,10 @@ pub(crate) fn feed_containers(
     // that rebuilt every bag snapshot for the whole life of a ticking enchant.
     let deadlines_moved = memory
         .enchant_deadlines
-        .moved(items.countdown_display_epoch());
+        .moved(inv.changes.countdown_steps());
     // Bound as `let`s (not a bare OR-chain) so the gate trace below can name each input.
     let sweep = cooldowns.sweep_pending(clock.anchor);
-    let self_changed = !self_q.1.is_empty();
+    let self_changed = !inv.self_changed.is_empty();
     // `is_added`, NOT `is_changed`: the feeds read only the load-once icon CATALOG off this
     // resource (its struct doc says so verbatim); the world's held-model cache half is
     // get-or-insert every frame, so `is_changed` reads true forever — 1439's gate-trace found
@@ -915,7 +919,7 @@ pub(crate) fn feed_containers(
     let spells_changed = spells.as_ref().is_some_and(|r| r.is_changed());
     let families_changed = bag_families.as_ref().is_some_and(|r| r.is_changed());
     let errors_held = !equip_errors.0.is_empty();
-    let locks_held = !lock_cleared.0.is_empty() || !pending.is_empty();
+    let locks_held = !lock_cleared.0.is_empty() || !pending.is_empty() || !opens.0.is_empty();
     gate::trace(
         "feed_containers",
         &[
@@ -986,7 +990,7 @@ pub(crate) fn feed_containers(
     // `ui_action::cast_fail` already runs. No hex debug line on the player's screen: a code we
     // failed to map can't reach here (the table is total), and a key we typo'd is caught by
     // `equip_error`'s resolution test against the real `GlobalStrings.lua`, not at runtime.
-    let player = self_q.0.iter().next();
+    let player = inv.self_store.iter().next();
     let mut refusals = Vec::new();
     for e in equip_errors.0.drain(..) {
         // Reason 16's substitution — the ONE reason whose text is chosen by the app rather than
@@ -1000,6 +1004,7 @@ pub(crate) fn feed_containers(
                 bag_family_name(
                     player,
                     e.bag_slot,
+                    &inv.objects,
                     &items,
                     bag_families.as_deref().map(|c| &c.0),
                     &commands,
@@ -1045,6 +1050,9 @@ pub(crate) fn feed_containers(
     // sees the unlocked slot, not stale data — and after `feed_char`'s own push, for the same
     // reason on the doll and bank-bag bands (1771).
     let transitioned: Vec<(i64, u32)> = std::mem::take(&mut lock_cleared.0);
+    // The containers the server opened this frame (`SMSG_OPEN_CONTAINER`, decision 2339) — the
+    // packet handler queued them; they fire as `BAG_OPEN(id)` after the push below, like the locks.
+    let opened: Vec<i64> = std::mem::take(&mut opens.0);
 
     let mut fresh: HashMap<i64, ContainerState> = HashMap::new();
     // The player's own relic flag, resolved once. `find_equip_slot` reads it for INVSLOT 17 and
@@ -1064,6 +1072,7 @@ pub(crate) fn feed_containers(
             let guid = store.0.player_pack_slot(i).unwrap_or(0);
             if let Some(mut slot) = resolve_slot(
                 guid,
+                &inv.objects,
                 &items,
                 icons.as_deref(),
                 rolls,
@@ -1098,7 +1107,7 @@ pub(crate) fn feed_containers(
             if bag_guid == 0 {
                 continue; // no bag equipped → absent → GetContainerNumSlots = 0
             }
-            let (entry, num_slots, slot_guids) = match items.object(bag_guid) {
+            let (entry, num_slots, slot_guids) = match inv.objects.object(bag_guid) {
                 Some(f) => {
                     let n = f.container_num_slots().unwrap_or(0);
                     let guids: Vec<u64> = (0..n.min(36) as u8)
@@ -1119,6 +1128,7 @@ pub(crate) fn feed_containers(
             for (j, &guid) in slot_guids.iter().enumerate() {
                 if let Some(mut slot) = resolve_slot(
                     guid,
+                    &inv.objects,
                     &items,
                     icons.as_deref(),
                     rolls,
@@ -1154,6 +1164,7 @@ pub(crate) fn feed_containers(
             let guid = store.0.player_bank_slot(i).unwrap_or(0);
             if let Some(mut slot) = resolve_slot(
                 guid,
+                &inv.objects,
                 &items,
                 icons.as_deref(),
                 rolls,
@@ -1184,7 +1195,7 @@ pub(crate) fn feed_containers(
             if bag_guid == 0 {
                 continue; // no bag in the slot → absent → GetContainerNumSlots = 0
             }
-            let (entry, num_slots, slot_guids) = match items.object(bag_guid) {
+            let (entry, num_slots, slot_guids) = match inv.objects.object(bag_guid) {
                 Some(f) => {
                     let n = f.container_num_slots().unwrap_or(0);
                     let guids: Vec<u64> = (0..n.min(36) as u8)
@@ -1205,6 +1216,7 @@ pub(crate) fn feed_containers(
             for (j, &guid) in slot_guids.iter().enumerate() {
                 if let Some(mut slot) = resolve_slot(
                     guid,
+                    &inv.objects,
                     &items,
                     icons.as_deref(),
                     rolls,
@@ -1244,6 +1256,7 @@ pub(crate) fn feed_containers(
             let guid = store.0.player_keyring_slot(i).unwrap_or(0);
             if let Some(mut slot) = resolve_slot(
                 guid,
+                &inv.objects,
                 &items,
                 icons.as_deref(),
                 rolls,
@@ -1272,7 +1285,7 @@ pub(crate) fn feed_containers(
         // `HasKey()` — the gate that decides whether the keyring exists in the UI at all. Pushed
         // beside the containers because it is the same knowledge (item templates) read over the
         // same slot arrays, and it must be fresh on exactly the frames a BAG_UPDATE fires.
-        let key = has_key(&store.0, &items, &commands);
+        let key = has_key(&store.0, &inv.objects, &items, &commands);
         if key != memory.had_key {
             gate.audit("feed_containers", "the HasKey() flip");
             debug!(
@@ -1308,8 +1321,12 @@ pub(crate) fn feed_containers(
             vault: std::array::from_fn(|i| player.map_or(0, |s| vault_slot_guid(s, i as u8))),
         },
         transitioned,
+        opened,
     ) {
-        gate.audit("feed_containers", "a bag diff or a lock event");
+        gate.audit(
+            "feed_containers",
+            "a bag diff, a lock event or a server-opened bag",
+        );
     }
 }
 
@@ -1342,6 +1359,7 @@ pub(crate) fn apply_container_source(
     // is the logout despawn window — see this function's own note).
     guids: SlotGuids,
     transitioned: Vec<(i64, u32)>,
+    opened: Vec<i64>,
 ) -> bool {
     // Diff whole bags; push + fire BAG_UPDATE per transition, one BAG_UPDATE_DELAYED per batch. A
     // pending-lock transition always flips a slot's `.locked` (part of `ContainerSlot`'s equality),
@@ -1364,6 +1382,14 @@ pub(crate) fn apply_container_source(
     for _ in transitioned {
         script.fire_event("ITEM_LOCK_CHANGED", Vec::new());
     }
+    // `SMSG_OPEN_CONTAINER` → `BAG_OPEN(containerId)` (decision 2339). The reference's arm
+    // `0x5e3b35` fires it from the packet handler; ours reaches the VM here — after this frame's
+    // `BAG_UPDATE`s, so the frame the stock `ContainerFrame_OnEvent` shows paints the bag as it now
+    // is. The id is the reference's own: 0 backpack, 1..4 equipped, 5..10 bank.
+    pushed |= !opened.is_empty();
+    for bag in opened {
+        script.fire_event("BAG_OPEN", vec![ScriptValue::Int(bag)]);
+    }
     // Whether anything went into the VM — the caller's gate audit reads it (1439).
     pushed
 }
@@ -1398,12 +1424,11 @@ fn diff_and_push(
     fresh: HashMap<i64, ContainerState>,
     guids: SlotGuids,
 ) -> bool {
-    // **`BAG_CLOSED` — the only thing in the image that hides an open bag window** (CARVED, wow-re
-    // `system/ui/scratch/equipped-bag-slot-events.md`: one fire site, `0x4f92b5`, and
-    // `ContainerFrame_OnEvent`'s `this:Hide()` is its one consumer; `CloseBag`/`CloseAllBags` are
-    // not even strings in `WoW.exe`). Its condition is **not** "the bag went away" — it is
-    // `new != old && old != 0` (`0x4f923d je` unchanged, `0x4f9247 je` old-was-empty), so a bag
-    // SWAPPED for another fires `BAG_CLOSED(n)` and then `BAG_UPDATE(n)`.
+    // **`BAG_CLOSED` — the only thing in the image that hides an open bag window** (one fire site,
+    // `0x4f92b5`, and `ContainerFrame_OnEvent`'s `this:Hide()` is its one consumer;
+    // `CloseBag`/`CloseAllBags` are not even strings in `WoW.exe`). Its condition is **not** "the
+    // bag went away" — it is `new != old && old != 0` (`0x4f923d je` unchanged, `0x4f9247 je`
+    // old-was-empty), so a bag SWAPPED for another fires `BAG_CLOSED(n)` and then `BAG_UPDATE(n)`.
     //
     // Diffed on the BAG's own guid rather than on the pushed `ContainerState` below, because it is
     // a fact about the bag and not about its contents: two identical empty bags exchanged between
@@ -1418,7 +1443,7 @@ fn diff_and_push(
         })
         .collect();
     // The other half of the same branch: a bag REMOVED fires `BAG_CLOSED` and no `BAG_UPDATE`
-    // (the unequip row of the carve's event table). Every other transition still announces.
+    // (`0x4f92cc`). Every other transition still announces.
     let emptied: Vec<i64> = closed
         .iter()
         .copied()
@@ -1429,9 +1454,8 @@ fn diff_and_push(
         script.fire_event("BAG_CLOSED", vec![ScriptValue::Int(*id)]);
     }
     // **`PLAYERBANKSLOTS_CHANGED` has TWO producers in the reference, and they carry different
-    // arguments** (CARVED — wow-re `system/object-layer/scratch/bank-slot-event-law.md` §3/§4;
-    // decision 2140). benilla had one fire for both, so half of them were argless where the
-    // reference pushes a string:
+    // arguments** (decision 2140). benilla had one fire for both, so half of them were argless
+    // where the reference pushes a string:
     //
     // * **P1, the player-descriptor path** — `0x5ddcf0`'s watcher sees the slot's own GUID field
     //   change and fires `0x5ddd6e`, `FrameScript_SignalEvent 0x703e50`, `__fastcall(ecx = id)`
@@ -1532,12 +1556,12 @@ fn diff_and_push(
         );
         for &bag in &changed {
             // The vault fires the reference's own event, once per changed slot and **with no
-            // arguments** (CARVED — `0x5ddd6e` calls `FrameScript_SignalEvent 0x703e50`, an
-            // `__fastcall(ecx = id)` with a plain `ret` and no vararg push; wow-re
-            // `system/object-layer/scratch/bank-slot-event-law.md`). It is a broadcast: every bank
-            // button repaints from its own `GetInventorySlot()`, which is why no slot id is needed
-            // and why the bank BAG band's copy of this event — fired by `ui_char::feed_char`, the
-            // feed that owns that band — is indistinguishable from this one.
+            // arguments** (`0x5ddd6e` calls `FrameScript_SignalEvent 0x703e50`, an
+            // `__fastcall(ecx = id)` with a plain `ret` and no vararg push). It is a broadcast:
+            // every bank button repaints from its own `GetInventorySlot()`, which is why no slot id
+            // is needed and why the bank BAG band's copy of this event — fired by
+            // `ui_char::feed_char`, the feed that owns that band — is indistinguishable from this
+            // one.
             //
             // Everything else — backpack, equipped bags, AND bank bags (ordinary container frames
             // in the reference) — fires BAG_UPDATE(bagID). The vault is the one band that fires
@@ -1581,16 +1605,56 @@ mod tests {
     };
 
     /// **`PLAYERBANKSLOTS_CHANGED` has two producers and they carry different arguments**
-    /// (decision 2140; CARVED, wow-re `object-layer/scratch/bank-slot-event-law.md` §3/§4).
+    /// (decision 2140).
     ///
     /// benilla fired the argless one for every transition, which is right for half of them and
     /// wrong for the other half — and the half it got wrong is the one a view diff cannot even
-    /// see. The three arms below are the three the carve distinguishes:
+    /// see. The three arms below are the three the reference distinguishes:
     ///
     ///  · a slot's item GUID changes (arrive / leave / exchange) → `0x5ddd6e`, **no arguments**;
     ///  · the same item's own fields change (a restack) → `0x4c728d`, **`arg1 = "player"`**;
     ///  · two IDENTICAL items exchanged between two slots → the pushed views are equal, so the
     ///    container diff sees nothing at all, and the reference fires the argless one **twice**.
+    /// `SMSG_OPEN_CONTAINER` → `BAG_OPEN(containerId)` (decision 2339): the ids the handler
+    /// resolved reach the VM in order, after the frame's container push, and the stock
+    /// `ContainerFrame_OnEvent` sees the id as `arg1` — the reference's own event shape.
+    #[test]
+    fn a_server_opened_bag_fires_bag_open_with_its_container_id() {
+        let mut s = UiScript::new().unwrap();
+        s.run(
+            "SEEN = {} \
+             local f = CreateFrame('Frame') \
+             f:RegisterEvent('BAG_OPEN') \
+             f:RegisterEvent('BAG_UPDATE') \
+             f:SetScript('OnEvent', function() \
+                 table.insert(SEEN, event .. ' ' .. tostring(arg1)) end)",
+        )
+        .unwrap();
+        let mut memory = FeedMemory::default();
+        // A bag equipped into the second bag slot, and nothing else changed this frame.
+        assert!(apply_container_source(
+            &mut s,
+            &mut memory,
+            None,
+            NO_BAGS,
+            Vec::new(),
+            vec![2]
+        ));
+        let seen = s.eval::<Vec<String>>("return SEEN").unwrap();
+        assert_eq!(seen, vec!["BAG_OPEN 2"]);
+        // Nothing queued: nothing fired, and the push reports nothing went in.
+        s.run("SEEN = {}").unwrap();
+        assert!(!apply_container_source(
+            &mut s,
+            &mut memory,
+            None,
+            NO_BAGS,
+            Vec::new(),
+            Vec::new()
+        ));
+        assert!(s.eval::<Vec<String>>("return SEEN").unwrap().is_empty());
+    }
+
     #[test]
     fn playerbankslots_changed_names_its_producer_by_the_slot_guid() {
         let mut s = UiScript::new().unwrap();
@@ -1630,16 +1694,37 @@ mod tests {
 
         // An item ARRIVES in vault slot 1 — the descriptor path, no arguments.
         guids.vault[0] = 0xF00D;
-        apply_container_source(&mut s, &mut memory, Some(vault(1, 5)), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(vault(1, 5)),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(seen(&mut s), vec!["PLAYERBANKSLOTS_CHANGED nil"]);
 
         // The SAME item restacks — its own `ITEM_FIELD_STACK_COUNT` moved, which is the item
         // watcher's path, and the reference pushes the unit token there.
-        apply_container_source(&mut s, &mut memory, Some(vault(1, 9)), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(vault(1, 9)),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(seen(&mut s), vec!["PLAYERBANKSLOTS_CHANGED player"]);
 
         // Nothing moved at all.
-        apply_container_source(&mut s, &mut memory, Some(vault(1, 9)), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(vault(1, 9)),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert!(seen(&mut s).is_empty(), "an unchanged vault says nothing");
 
         // Two IDENTICAL stacks exchanged between slots 1 and 2. Both slot views are equal before
@@ -1673,10 +1758,24 @@ mod tests {
             )])
         };
         guids.vault[1] = 0xBEEF;
-        apply_container_source(&mut s, &mut memory, Some(two()), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(two()),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(seen(&mut s), vec!["PLAYERBANKSLOTS_CHANGED nil"]);
         guids.vault.swap(0, 1);
-        let pushed = apply_container_source(&mut s, &mut memory, Some(two()), guids, Vec::new());
+        let pushed = apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(two()),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(
             seen(&mut s),
             vec![
@@ -1689,7 +1788,7 @@ mod tests {
     }
 
     /// **`BAG_CLOSED`, the only thing that hides an open bag window** — and the three ways to get
-    /// its condition wrong (CARVED, wow-re `system/ui/scratch/equipped-bag-slot-events.md`).
+    /// its condition wrong (`0x4f92b5`).
     ///
     /// benilla never fired this event at all, so a `ContainerFrame` outlived the bag it belonged
     /// to: `ContainerFrame_OnEvent`'s `this:Hide()` arm is its one consumer in all of FrameXML,
@@ -1735,12 +1834,26 @@ mod tests {
         // Equip a bag into the first equipped bag slot: BAG_UPDATE, and no BAG_CLOSED — the slot
         // was empty, which is the `0x4f9247 je` arm.
         guids.bags[0] = 0xAAAA;
-        apply_container_source(&mut s, &mut memory, Some(pouch(6)), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(pouch(6)),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(seen(&mut s), vec!["BAG_UPDATE 1"]);
 
         // Its contents change: the bag guid stands, so neither the close nor its suppression
         // applies and the ordinary announce runs.
-        apply_container_source(&mut s, &mut memory, Some(pouch(6)), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(pouch(6)),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert!(
             seen(&mut s).is_empty(),
             "an unchanged container says nothing"
@@ -1749,12 +1862,26 @@ mod tests {
         // SWAP for a different bag: closed FIRST, then updated. This is the arm a "the bag went
         // away" reading gets wrong — the slot is still occupied.
         guids.bags[0] = 0xBBBB;
-        apply_container_source(&mut s, &mut memory, Some(pouch(10)), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(pouch(10)),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(seen(&mut s), vec!["BAG_CLOSED 1", "BAG_UPDATE 1"]);
 
         // UNEQUIP: closed, and **no** BAG_UPDATE.
         guids.bags[0] = 0;
-        apply_container_source(&mut s, &mut memory, Some(HashMap::new()), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(HashMap::new()),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(seen(&mut s), vec!["BAG_CLOSED 1"]);
 
         // Two IDENTICAL empty bags exchanged between bank bag slots 5 and 6. Every container
@@ -1784,10 +1911,24 @@ mod tests {
         let mut guids = NO_BAGS;
         guids.bags[4] = 0x1111;
         guids.bags[5] = 0x2222;
-        apply_container_source(&mut s, &mut memory, Some(two()), guids, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(two()),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         let _ = seen(&mut s);
         guids.bags.swap(4, 5);
-        let pushed = apply_container_source(&mut s, &mut memory, Some(two()), guids, Vec::new());
+        let pushed = apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(two()),
+            guids,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(seen(&mut s), vec!["BAG_CLOSED 5", "BAG_CLOSED 6"]);
         assert!(
             pushed,
@@ -1830,13 +1971,14 @@ mod tests {
             Some(HashMap::from([(0, bag0)])),
             NO_BAGS,
             Vec::new(),
+            Vec::new(),
         );
         assert_eq!(s.eval::<i64>("return GetContainerNumSlots(0)").unwrap(), 16);
         assert_eq!(s.eval::<i64>("return BAG_EVENTS").unwrap(), 1);
 
         // The logout despawn frame: no store. The VM keeps its last-pushed bags and no event
         // fires — an addon reading its bags out of the PLAYER_LOGOUT edge sees them intact.
-        apply_container_source(&mut s, &mut memory, None, NO_BAGS, Vec::new());
+        apply_container_source(&mut s, &mut memory, None, NO_BAGS, Vec::new(), Vec::new());
         assert_eq!(
             s.eval::<i64>("return GetContainerNumSlots(0)").unwrap(),
             16,
@@ -1855,6 +1997,7 @@ mod tests {
             Some(HashMap::new()),
             NO_BAGS,
             Vec::new(),
+            Vec::new(),
         );
         assert_eq!(s.eval::<i64>("return GetContainerNumSlots(0)").unwrap(), 0);
         assert_eq!(s.eval::<i64>("return BAG_EVENTS").unwrap(), 2);
@@ -1912,6 +2055,7 @@ mod tests {
             Some(bag(arrows(200))),
             NO_BAGS,
             Vec::new(),
+            Vec::new(),
         );
         assert_eq!(
             s.eval::<String>("return table.concat(ORDER, ' ')").unwrap(),
@@ -1927,6 +2071,7 @@ mod tests {
             Some(bag(arrows(199))),
             NO_BAGS,
             Vec::new(),
+            Vec::new(),
         );
         assert_eq!(
             s.eval::<String>("return table.concat(ORDER, ' ')").unwrap(),
@@ -1942,7 +2087,14 @@ mod tests {
         s.run("ORDER = {}").unwrap();
         let mut other = arrows(20);
         other.item_id = 3033; // Razor Arrow
-        apply_container_source(&mut s, &mut memory, Some(bag(other)), NO_BAGS, Vec::new());
+        apply_container_source(
+            &mut s,
+            &mut memory,
+            Some(bag(other)),
+            NO_BAGS,
+            Vec::new(),
+            Vec::new(),
+        );
         assert_eq!(
             s.eval::<String>("return table.concat(ORDER, ' ')").unwrap(),
             "BAG_UPDATE:0,nil",
diff --git a/crates/benilla-app/src/ui_items/mod.rs b/crates/benilla-app/src/ui_items/mod.rs
index 1e38fd77..cea7f7d9 100644
--- a/crates/benilla-app/src/ui_items/mod.rs
+++ b/crates/benilla-app/src/ui_items/mod.rs
@@ -4,8 +4,9 @@
 //! Each frame, the player's own descriptor names the bag layout (the PRIVATE `PACK_SLOT` array =
 //! the backpack; `INV_SLOT` 19–22 = the equipped bags, each a container object with its own
 //! `CONTAINER_FIELD_SLOT` array; `KEYRING_SLOT` 81.. = the keyring, decision 0765 — a container
-//! with no container *object*, exactly like the bank), the item store ([`crate::items::Items`]) resolves slot guids to
-//! instances (entry, stack count), the template cache resolves entries to name/quality (ask-once
+//! with no container *object*, exactly like the bank), the object index ([`crate::net::Objects`])
+//! resolves slot guids to instances (entry, stack count), the template cache resolves entries to
+//! name/quality (ask-once
 //! `ITEM_QUERY_SINGLE` — a slot whose answer is in flight shows as an unresolved occupied slot and
 //! fills in when it lands), and `ItemDisplayInfo.dbc` turns the template's display id into the
 //! icon. The assembled per-bag [`ContainerState`](benilla_ui::script::ContainerState)s are diffed
@@ -42,7 +43,7 @@ use benilla_ui::script::EQUIPMENT_BAG;
 use bevy::prelude::*;
 
 use crate::items::Items;
-use crate::net::{NetCommands, ObjectStore};
+use crate::net::{NetCommands, ObjectStore, Objects};
 use crate::pending_item_ops::{LockTransitions, PendingItemOps};
 use crate::ui_script::UiInput;
 use crate::ui_unit::UnitFeed;
@@ -50,6 +51,7 @@ use crate::ui_unit::UnitFeed;
 mod drain;
 mod equip_error;
 pub(crate) mod feed;
+mod net;
 
 pub(crate) use drain::send_auto_equip;
 use drain::{
@@ -63,7 +65,7 @@ use feed::{
 /// The backpack's fixed capacity (`PLAYER_FIELD_PACK_SLOT_1..` — 16 slots on the 1.12 wire).
 pub(super) const PACK_SLOTS: u8 = 16;
 /// The worn-equipment slots (`INV_SLOT` 0..18 — head through tabard, vmangos `PlayerSlots`), the
-/// first region of the reference's inventory walk (wow-re `action-item-slot.md` §8.2).
+/// first region of the reference's inventory walk (the walker `0x622420`).
 pub(super) const EQUIPMENT_SLOTS: u8 = 19;
 /// The first equipped-bag inventory slot (`INV_SLOT` 19..22 hold bags 1..4).
 pub(super) const BAG_SLOT_FIRST: u8 = 19;
@@ -190,14 +192,19 @@ pub(crate) struct EquipErrors(pub Vec<EquipError>);
 /// object's own slot array, or — [`EQUIPMENT_BAG`], decision 0208 phase 1b — the player
 /// descriptor's own `INV_SLOT` array directly (`slot0` is already the wire `EQUIPMENT_SLOT_*`
 /// id, [`wire_pos`]'s own convention). The same resolution the feed does.
-pub(crate) fn slot_guid(store: &ObjectFields, bag: i64, slot0: u8, items: &Items) -> Option<u64> {
+pub(crate) fn slot_guid(
+    store: &ObjectFields,
+    bag: i64,
+    slot0: u8,
+    objects: &Objects,
+) -> Option<u64> {
     match bag {
         0 => store.player_pack_slot(slot0).filter(|g| *g != 0),
         1..=4 => {
             let bag_guid = store
                 .player_inv_slot(BAG_SLOT_FIRST + bag as u8 - 1)
                 .filter(|g| *g != 0)?;
-            items
+            objects
                 .object(bag_guid)?
                 .container_slot(slot0)
                 .filter(|g| *g != 0)
@@ -208,7 +215,7 @@ pub(crate) fn slot_guid(store: &ObjectFields, bag: i64, slot0: u8, items: &Items
             let bag_guid = store
                 .player_bank_bag_slot((bag - BANK_BAG_ID_FIRST) as u8)
                 .filter(|g| *g != 0)?;
-            items
+            objects
                 .object(bag_guid)?
                 .container_slot(slot0)
                 .filter(|g| *g != 0)
@@ -235,15 +242,15 @@ pub(crate) fn slot_guid_count(
     store: Option<&ObjectStore>,
     bag: i64,
     slot1: u32,
-    items: &Items,
+    objects: &Objects,
 ) -> (u64, u32) {
     let Some(store) = store else {
         return (0, 0);
     };
     let slot0 = slot1.saturating_sub(1) as u8;
-    match slot_guid(&store.0, bag, slot0, items) {
+    match slot_guid(&store.0, bag, slot0, objects) {
         Some(guid) => {
-            let count = items
+            let count = objects
                 .object(guid)
                 .and_then(|f| f.item_stack_count())
                 .unwrap_or(1);
@@ -257,11 +264,10 @@ pub(crate) fn slot_guid_count(
 /// [`ItemDisplays`] catalog the equipment feed already loads).
 ///
 /// This is the **one** thing the client's spell-icon surfaces genuinely share. The *laws* do not:
-/// wow-re's `system/ui/scratch/spell-icon-substitution-law.md` settled that there is no shared
-/// spell-icon resolver at all — six Lua getters, six laws inlined per binding, disagreeing even
-/// between the TradeSkill and Craft windows. But every arm that ends at an item ends *here*, at the
-/// same `ItemTemplate+0x18 → 0x5d88b0 → rec+0x14` chain (§5 of that note). So the join lives once,
-/// and each window keeps its own law above it.
+/// the reference has no shared spell-icon resolver at all — six Lua getters, six laws inlined per
+/// binding, disagreeing even between the TradeSkill and Craft windows. But every arm that ends at
+/// an item ends *here*, at the same `ItemTemplate+0x18 → 0x5d88b0 → rec+0x14` chain. So the join
+/// lives once, and each window keeps its own law above it.
 pub(crate) fn item_icon(
     icons: Option<&crate::entities::ItemDisplays>,
     display_info_id: u32,
@@ -272,11 +278,10 @@ pub(crate) fn item_icon(
 }
 
 /// Which sections of the player's flat slot array a walk visits — the reference walker's own
-/// **section mask** (`0x622420`'s `ebx`; wow-re `ui/scratch/quest-leaderboard-law.md` §3.1 and
-/// `action-item-slot.md` §8.2). The reference has ONE walker over one contiguous 113-guid slot
-/// space (`PLAYER_FIELD_INV_SLOT_HEAD` through the end of the keyring) and parameterises it here;
-/// benilla had grown two hand-rolled walks that had already drifted apart, which is what decision
-/// 1158 collapsed back into [`walk_inventory`].
+/// **section mask** (`0x622420`'s `ebx`). The reference has ONE walker over one contiguous 113-guid
+/// slot space (`PLAYER_FIELD_INV_SLOT_HEAD` through the end of the keyring) and parameterises it
+/// here; benilla had grown two hand-rolled walks that had already drifted apart, which is what
+/// decision 1158 collapsed back into [`walk_inventory`].
 ///
 /// A container met in an ENABLED section is always recursed into — the reference gates sections
 /// only at the player's own root descriptor ("inside a recursed container every slot is visited
@@ -318,11 +323,10 @@ impl InventoryScope {
         keyring: false,
     };
     /// `0x4F` — [`Self::DEFAULT`] **plus the bank**, the mask the quest surfaces pass (`8`, which
-    /// the rewrite turns into `0x4F`). wow-re's call-site census of `0x622130` finds six such
-    /// sites and every one is a quest surface: `GetQuestLogLeaderBoard` (`0x4e0579`/`0x4e0592`),
-    /// the ADD_ITEM toast (`0x5dd0f5`), the whole-quest turn-in predicate (`0x4df778`), and
-    /// `GetAbandonQuestItems` (`0x4dfc8a`). **Quest item objectives count banked copies; nothing
-    /// else does.**
+    /// the rewrite turns into `0x4F`). `0x622130` has six such call sites and every one is a quest
+    /// surface: `GetQuestLogLeaderBoard` (`0x4e0579`/`0x4e0592`), the ADD_ITEM toast (`0x5dd0f5`),
+    /// the whole-quest turn-in predicate (`0x4df778`), and `GetAbandonQuestItems` (`0x4dfc8a`).
+    /// **Quest item objectives count banked copies; nothing else does.**
     pub(crate) const QUEST_ITEMS: Self = Self {
         bank: true,
         ..Self::DEFAULT
@@ -354,7 +358,7 @@ impl InventoryScope {
 /// come before the backpack.
 fn walk_inventory<T>(
     store: &ObjectFields,
-    items: &Items,
+    objects: &Objects,
     scope: InventoryScope,
     mut visit: impl FnMut(u8, u8, u64) -> Option<T>,
 ) -> Option<T> {
@@ -362,7 +366,7 @@ fn walk_inventory<T>(
     // (true for equipped bags and bank bags alike — `BANK_BAG_SLOT_FIRST`'s note).
     let contents =
         |bag_slot: u8, bag_guid: u64, visit: &mut dyn FnMut(u8, u8, u64) -> Option<T>| {
-            let bag_fields = items.object(bag_guid)?;
+            let bag_fields = objects.object(bag_guid)?;
             let num_slots = bag_fields.container_num_slots().unwrap_or(0).min(36) as u8;
             (0..num_slots).find_map(|j| {
                 let guid = bag_fields.container_slot(j).unwrap_or(0);
@@ -457,13 +461,13 @@ fn walk_inventory<T>(
 /// and the feed reruns.
 pub(crate) fn count_of(
     store: &ObjectFields,
-    items: &Items,
+    objects: &Objects,
     entry: u32,
     scope: InventoryScope,
 ) -> u32 {
     let mut total = 0u32;
-    walk_inventory::<()>(store, items, scope, |_, _, guid| {
-        if let Some(fields) = items.object(guid) {
+    walk_inventory::<()>(store, objects, scope, |_, _, guid| {
+        if let Some(fields) = objects.object(guid) {
             if fields.object_entry() == Some(entry) {
                 total += fields.item_stack_count().unwrap_or(1);
             }
@@ -479,11 +483,11 @@ pub(crate) fn count_of(
 /// the per-entry question becomes a lookup. Same scope, same per-copy stack sum.
 pub(crate) fn carried_counts(
     store: &ObjectFields,
-    items: &Items,
+    objects: &Objects,
 ) -> std::collections::HashMap<u32, u32> {
     let mut counts = std::collections::HashMap::new();
-    walk_inventory::<()>(store, items, InventoryScope::CARRIED, |_, _, guid| {
-        if let Some(fields) = items.object(guid) {
+    walk_inventory::<()>(store, objects, InventoryScope::CARRIED, |_, _, guid| {
+        if let Some(fields) = objects.object(guid) {
             if let Some(entry) = fields.object_entry() {
                 *counts.entry(entry).or_insert(0) += fields.item_stack_count().unwrap_or(1);
             }
@@ -494,7 +498,7 @@ pub(crate) fn carried_counts(
 }
 
 /// How far [`find_item`] looks, and which copies count — the two mode bits the reference's own
-/// callers pass into the inventory walker `0x622420` (wow-re `action-item-slot.md` §8.2).
+/// callers pass into the inventory walker `0x622420`.
 #[derive(Clone, Copy, Default)]
 pub(crate) struct ItemSearch {
     /// Mode `1` alone: the **equipment slots only** (0–18), no expansion. The equip-vs-use fork's
@@ -508,13 +512,13 @@ pub(crate) struct ItemSearch {
 
 /// Where a copy of item `entry` is: the wire `(bag_index, 0-based slot)` pair ([`wire_pos`]'s own
 /// output shape) plus the **instance guid** that occupies it, since the use fork needs it
-/// ([`item_use_command`]). This is the reference's inventory search, byte-verified (wow-re
-/// `action-item-slot.md` §8.2: the walker `0x622420` over `PLAYER_FIELD_INV_SLOT_HEAD`, predicate
-/// `OBJECT_FIELD_ENTRY` equality) — the first hit of [`walk_inventory`], whose doc carries the
-/// order and why it is load-bearing (decision 0666; bank and buyback are not in this scope).
+/// ([`item_use_command`]). This is the reference's inventory search (the walker `0x622420` over
+/// `PLAYER_FIELD_INV_SLOT_HEAD`, predicate `OBJECT_FIELD_ENTRY` equality) — the first hit of
+/// [`walk_inventory`], whose doc carries the order and why it is load-bearing (decision 0666; bank
+/// and buyback are not in this scope).
 pub(crate) fn find_item(
     store: &ObjectFields,
-    items: &Items,
+    objects: &Objects,
     entry: u32,
     search: ItemSearch,
 ) -> Option<(u8, u8, u64)> {
@@ -523,8 +527,8 @@ pub(crate) fn find_item(
     } else {
         InventoryScope::DEFAULT
     };
-    walk_inventory(store, items, scope, |bag, slot, guid| {
-        let f = items.object(guid)?;
+    walk_inventory(store, objects, scope, |bag, slot, guid| {
+        let f = objects.object(guid)?;
         if f.object_entry() != Some(entry) {
             return None;
         }
@@ -549,12 +553,12 @@ pub(crate) fn find_item(
 /// its load-bearing order (decisions 0666/1158) and just defers the judging by one step.
 pub(crate) fn collect_inventory(
     store: &ObjectFields,
-    items: &Items,
+    objects: &Objects,
     scope: InventoryScope,
 ) -> Vec<(u8, u8, u64)> {
     let mut out = Vec::new();
     // `None` throughout — the walk is never stopped, so every slot in scope lands in `out`.
-    walk_inventory(store, items, scope, |bag, slot, guid| {
+    walk_inventory(store, objects, scope, |bag, slot, guid| {
         out.push((bag, slot, guid));
         None::<()>
     });
@@ -575,12 +579,17 @@ pub(crate) fn collect_inventory(
 ///
 /// A slot whose item template is still in flight can't be judged and reads as "not a key"; the
 /// answer lands within a frame or two and the feed re-pushes.
-pub(crate) fn has_key(store: &ObjectFields, items: &Items, commands: &NetCommands) -> bool {
+pub(crate) fn has_key(
+    store: &ObjectFields,
+    objects: &Objects,
+    items: &Items,
+    commands: &NetCommands,
+) -> bool {
     // Every guid mode 0x4f reaches, in the walker's own order — a container is recursed into as it
     // is passed (the depth-first rule), which is why each bag's contents follow its own slot.
     // Collected first, then judged: the template lookup needs `items` mutably (the ask-once query).
-    fn contents(bag_guid: u64, items: &Items, out: &mut Vec<u64>) {
-        let Some(f) = items.object(bag_guid) else {
+    fn contents(bag_guid: u64, objects: &Objects, out: &mut Vec<u64>) {
+        let Some(f) = objects.object(bag_guid) else {
             return;
         };
         let n = f.container_num_slots().unwrap_or(0).min(36) as u8;
@@ -593,7 +602,7 @@ pub(crate) fn has_key(store: &ObjectFields, items: &Items, commands: &NetCommand
     for bag in 0..BAGS {
         let bag_guid = store.player_inv_slot(BAG_SLOT_FIRST + bag).unwrap_or(0);
         guids.push(bag_guid);
-        contents(bag_guid, items, &mut guids);
+        contents(bag_guid, objects, &mut guids);
     }
     for i in 0..PACK_SLOTS {
         guids.push(store.player_pack_slot(i).unwrap_or(0));
@@ -604,7 +613,7 @@ pub(crate) fn has_key(store: &ObjectFields, items: &Items, commands: &NetCommand
     for bag in 0..BANK_BAGS {
         let bag_guid = store.player_bank_bag_slot(bag).unwrap_or(0);
         guids.push(bag_guid);
-        contents(bag_guid, items, &mut guids);
+        contents(bag_guid, objects, &mut guids);
     }
     for i in 0..KEYRING_SLOTS {
         guids.push(store.player_keyring_slot(i).unwrap_or(0));
@@ -613,7 +622,7 @@ pub(crate) fn has_key(store: &ObjectFields, items: &Items, commands: &NetCommand
         if guid == 0 {
             return false;
         }
-        let Some(entry) = items.object(guid).and_then(|f| f.object_entry()) else {
+        let Some(entry) = objects.object(guid).and_then(|f| f.object_entry()) else {
             return false;
         };
         items
@@ -621,6 +630,44 @@ pub(crate) fn has_key(store: &ObjectFields, items: &Items, commands: &NetCommand
             .is_some_and(|t| t.bag_family == BAG_FAMILY_KEYS)
     })
 }
+/// **The object index a test resolves item guids through** (decision 2334) — the half of the
+/// seam [`crate::items::TestDeps`] does not cover, for a test that holds no `TestDeps`: a world to
+/// seed with item entities, and the [`Objects`] lookup over it. The two live together because the
+/// lookup borrows the world it reads, so a test cannot hold one without the other.
+///
+/// Seed first, then read: `objects.get()` borrows the world for as long as its answer lives, so
+/// the idiom at a call site is `&objs.get()` inline.
+#[cfg(test)]
+pub(crate) struct TestObjects {
+    world: World,
+    state: bevy::ecs::system::SystemState<Objects<'static, 'static>>,
+}
+
+#[cfg(test)]
+impl TestObjects {
+    pub(crate) fn new() -> Self {
+        let mut world = World::new();
+        world.init_resource::<crate::net::GuidIndex>();
+        let state = bevy::ecs::system::SystemState::new(&mut world);
+        Self { world, state }
+    }
+
+    /// One item instance in the index — the wire's `ItemCreate`.
+    pub(crate) fn spawn(&mut self, guid: u64, fields: ObjectFields) {
+        crate::items::test_spawn_item(&mut self.world, guid, fields, false);
+    }
+
+    /// The same for a CONTAINER instance (`TYPEMASK_CONTAINER`).
+    pub(crate) fn spawn_container(&mut self, guid: u64, fields: ObjectFields) {
+        crate::items::test_spawn_item(&mut self.world, guid, fields, true);
+    }
+
+    /// The lookup itself.
+    pub(crate) fn get(&mut self) -> Objects<'_, '_> {
+        self.state.get(&self.world)
+    }
+}
+
 /// The wire's "player array" bag index — `INVENTORY_SLOT_BAG_0`. With it, [`ItemUse::slot`] IS the
 /// equipment index (0–18 worn, 19–22 the equipped bags).
 pub(crate) const PLAYER_ARRAY: u8 = 255;
@@ -700,12 +747,12 @@ pub(crate) enum ItemUseRoute {
     /// `CMSG_PETITION_SHOW_SIGNATURES` for the instance, not `CMSG_USE_ITEM`.
     ///
     /// **VERIFIED** (2026-09-03, correcting 1672's INFERRED reading — which reasoned it out and
-    /// got the opcode, the payload and the gate right, but placed the arm wrongly). wow-re HAD
-    /// carved this branch; the note simply was not found. Two records carry it:
+    /// got the opcode, the payload and the gate right, but placed the arm wrongly). Two addresses
+    /// carry it:
     ///
-    /// - `ui/scratch/right-click-open.md` §3 row **#9**: gate `0x5d8f95 test ah,0x20` on the
+    /// - `CGItem::Use`'s rung **#9**: gate `0x5d8f95 test ah,0x20` on the
     ///   template's `Flags & 0x2000` (SIGNABLE / petition) → `0x5eef40`.
-    /// - `object-layer/ledger.tsv`'s row for `0x5eef40`: the **`CMSG_PETITION_SHOW_SIGNATURES`
+    /// - `0x5eef40`: the **`CMSG_PETITION_SHOW_SIGNATURES`
     ///   (`0x1BE`)** sender, `ret 8` — `Put32(0x1BE)` @ `0x5eef79`, `Put64(guid)` @ `0x5eef83`,
     ///   send @ `0x5eef8e`, and **that is the whole packet: one uint64**. It returns immediately
     ///   if both guid dwords are zero, and its **sole caller image-wide is `0x5d8fa6`** — this
@@ -719,11 +766,11 @@ pub(crate) enum ItemUseRoute {
     /// what changes is that this is now read rather than reasoned, and a reader is not sent
     /// looking for a byte read that already exists.
     ShowPetition { item: u64 },
-    /// **The disarmed refusal** — `CGItem::Use`'s rung **15 of 20** (decision 1903; wow-re
-    /// `disarm-followups-law.md` §2, byte-verified): using the very weapon a disarm has taken
-    /// raises `ERR_CANT_USE_DISARMED` (`0x16b` = 363) at `0x5d926d call 0x496720` and sends
-    /// **nothing**. This is the client refusing on its own — unlike `ERR_NOT_WHILE_DISARMED`
-    /// (61), which is a server `SMSG_INVENTORY_CHANGE_FAILURE` reason we only render.
+    /// **The disarmed refusal** — `CGItem::Use`'s rung **15 of 20** (decision 1903): using the very
+    /// weapon a disarm has taken raises `ERR_CANT_USE_DISARMED` (`0x16b` = 363) at
+    /// `0x5d926d call 0x496720` and sends **nothing**. This is the client refusing on its own —
+    /// unlike `ERR_NOT_WHILE_DISARMED` (61), which is a server `SMSG_INVENTORY_CHANGE_FAILURE`
+    /// reason we only render.
     ///
     /// The condition is narrow, and none of it is about the clicked item's own class: the item
     /// must be **worn in equipment slot 15 or 16**, the flag must be up, and *that hand* must be
@@ -788,9 +835,8 @@ pub(crate) fn item_use_route(
 /// IsCasting check, and `6e4f33` forwards the item to the requirement validator `0x6094f0`. The
 /// commit `SendCast 0x6e54f0` then picks the opcode from it (`0x6e57d8 push 0xab`). So an item
 /// use takes the whole ladder — cooldown, GCD, in-flight, mounted, moving, form, reagents, target
-/// bind, range — and [`crate::ui_action::CastLadder::send`] is where all of that lives (decision
-/// 0914; verified at the bytes in wow-re's `system/ui/scratch/disasm-full.txt`, corroborated by
-/// its `action-item-slot.md` §8 and `cursor-system.md` §8.4a).
+/// bind, range — and [`crate::spell::CastLadder::send`] is where all of that lives (decision
+/// 0914).
 ///
 /// Decision 0908 put only the in-flight rung here — the fix for the director's B200, where
 /// double-clicking a mount shipped a second `CMSG_USE_ITEM`, vmangos answered it
@@ -816,14 +862,14 @@ pub(crate) fn item_use_route(
 ///
 /// It is the identical predicate to `0x4e55f0` — [`crate::ui_action::toggle::active_action_toggle`]
 /// — just reached with the *item's* spell instead of the slot's, so the one predicate serves both
-/// (wow-re `shapeshift-plaincast-toggle.md`'s own `0x6e7040` call-site census lists `0x5d9237`
-/// under `0x5d8d00` as "action button, container-**item** branch").
+/// (`0x6e7040`'s call site `0x5d9237` sits under `0x5d8d00`, on the action button's
+/// container-**item** branch).
 ///
 /// Returns whether anything left for the server — `false` for the reference's silent no-op.
 pub(crate) fn send_item_use(
     it: ItemUse,
-    ctx: &crate::ui_action::cast_target::CastContext,
-    ladder: &mut crate::ui_action::CastLadder,
+    ctx: &crate::spell::cast_target::CastContext,
+    ladder: &mut crate::spell::CastLadder,
     script: &mut benilla_ui::script::UiScript,
     gate: &mut crate::ui_bind_confirm::BindGate,
     suppress: bool,
@@ -843,7 +889,12 @@ pub(crate) fn send_item_use(
     };
     // The disarm ladder, asked of the caster's own inventory (decision 1903).
     let disarmed_hand = ctx.rel.self_store.and_then(|store| {
-        crate::items::disarmed_equipment_slot(store, &ladder.items, &ladder.commands)
+        crate::items::disarmed_equipment_slot(
+            store,
+            &ladder.objects,
+            &ladder.items,
+            &ladder.commands,
+        )
     });
     match item_use_route(it, aura_cancels, disarmed_hand) {
         ItemUseRoute::CantUseDisarmed => {
@@ -889,12 +940,12 @@ pub(crate) fn send_item_use(
         // id < 0, `5d916e` id past the table, `5d917a` no Spell.dbc row, `5d9184` no ActiveIconID);
         // the reference asks the bind question even when the item has no usable on-use spell at
         // all. Gating this on `Cast(spell)` alone — which is where it was first written — would be
-        // narrower than the reference, and wow-re said so in as many words.
+        // narrower than the reference.
         ItemUseRoute::Nothing | ItemUseRoute::Cast(_)
             if !suppress
-                && it
-                    .guid
-                    .is_some_and(|g| gate.use_binds(&ladder.items, &ladder.commands, g)) =>
+                && it.guid.is_some_and(|g| {
+                    gate.use_binds(&ladder.objects, &ladder.items, &ladder.commands, g)
+                }) =>
         {
             gate.defer_use(script, it);
             false
@@ -910,7 +961,7 @@ pub(crate) fn send_item_use(
             ladder.send(
                 spell,
                 ctx,
-                crate::ui_action::CastCommit::Item {
+                crate::spell::CastCommit::Item {
                     bag_index: it.bag_index,
                     slot: it.slot,
                     entry: it.entry,
@@ -1143,6 +1194,7 @@ pub(crate) struct UiItemsPlugin;
 
 impl Plugin for UiItemsPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         // The icon source — `ItemDisplayInfo.dbc` — is the `ItemDisplays` resource the equipment
         // renderer already loads (one parse serves the world and the bags).
         app.init_resource::<EquipErrors>()
@@ -1152,6 +1204,7 @@ impl Plugin for UiItemsPlugin {
             .init_resource::<crate::ui_bind_confirm::PendingEquips>()
             .init_resource::<crate::ui_bind_confirm::PendingBindOnUse>()
             .init_resource::<LockTransitions>()
+            .init_resource::<net::BagOpens>()
             // AFTER the chain opens — a bare Startup slot raced AssetSet::Open and, when it
             // won, silently skipped every item DBC (no ItemSets/ItemSubClasses resource for the
             // whole session: set tooltips lost their SET block, the crafting book its headers).
@@ -1577,8 +1630,7 @@ mod tests {
 /// at all (an equipped trinket's action button was inert) and put the backpack ahead of the bags.
 #[cfg(test)]
 mod find_item_tests {
-    use super::{find_item, ItemSearch};
-    use crate::items::Items;
+    use super::{find_item, ItemSearch, TestObjects};
     use benilla_protocol::ObjectFields;
 
     // Descriptor indices, raw (the module's own consts are private; the codebase's test idiom).
@@ -1613,23 +1665,23 @@ mod find_item_tests {
         ObjectFields::from_pairs(&pairs)
     }
 
-    /// A plain item instance of `entry` (optionally with live charges).
-    fn item(store: &mut Items, guid: u64, entry: u32, charges: Option<i32>) {
+    /// A plain item instance of `entry` (optionally with live charges), in the one index (2334).
+    fn item(objects: &mut TestObjects, guid: u64, entry: u32, charges: Option<i32>) {
         let mut pairs = vec![(ENTRY, entry)];
         if let Some(c) = charges {
             pairs.push((CHARGES, c as u32));
         }
-        store.insert_object(guid, ObjectFields::from_pairs(&pairs));
+        objects.spawn(guid, ObjectFields::from_pairs(&pairs));
     }
 
     /// A container instance holding `contents` at its own inner slots.
-    fn bag(store: &mut Items, guid: u64, entry: u32, contents: &[(u8, u64)]) {
+    fn bag(objects: &mut TestObjects, guid: u64, entry: u32, contents: &[(u8, u64)]) {
         let mut pairs = vec![(ENTRY, entry), (NUM_SLOTS, 16)];
         for &(i, item_guid) in contents {
             pairs.push((SLOT_1 + 2 * u16::from(i), item_guid as u32));
             pairs.push((SLOT_1 + 2 * u16::from(i) + 1, (item_guid >> 32) as u32));
         }
-        store.insert_object(guid, ObjectFields::from_pairs(&pairs));
+        objects.spawn_container(guid, ObjectFields::from_pairs(&pairs));
     }
 
     const ALL: ItemSearch = ItemSearch {
@@ -1649,12 +1701,12 @@ mod find_item_tests {
     /// identical copy sitting in the backpack, and the wire pair is the doll's `(255, 13)`.
     #[test]
     fn equipment_is_searched_before_everything_else() {
-        let mut items = Items::default();
-        item(&mut items, 0xE1, TRINKET, None);
-        item(&mut items, 0xB1, TRINKET, None);
+        let mut objs = TestObjects::new();
+        item(&mut objs, 0xE1, TRINKET, None);
+        item(&mut objs, 0xB1, TRINKET, None);
         let store = player(&[(13, 0xE1), (23, 0xB1)]);
         assert_eq!(
-            find_item(&store, &items, TRINKET, ALL),
+            find_item(&store, &objs.get(), TRINKET, ALL),
             Some((255, 13, 0xE1))
         );
     }
@@ -1663,12 +1715,12 @@ mod find_item_tests {
     /// This is the stage that decides USE-in-place vs EQUIP.
     #[test]
     fn the_equipment_only_stage_ignores_the_bags() {
-        let mut items = Items::default();
-        item(&mut items, 0xB1, TRINKET, None);
+        let mut objs = TestObjects::new();
+        item(&mut objs, 0xB1, TRINKET, None);
         let store = player(&[(23, 0xB1)]);
-        assert_eq!(find_item(&store, &items, TRINKET, WORN), None);
+        assert_eq!(find_item(&store, &objs.get(), TRINKET, WORN), None);
         assert_eq!(
-            find_item(&store, &items, TRINKET, ALL),
+            find_item(&store, &objs.get(), TRINKET, ALL),
             Some((255, 23, 0xB1))
         );
     }
@@ -1677,13 +1729,13 @@ mod find_item_tests {
     /// container) — the leg the old backpack-first walk had backwards.
     #[test]
     fn bag_contents_precede_the_backpack() {
-        let mut items = Items::default();
-        item(&mut items, 0xC1, TRINKET, None);
-        item(&mut items, 0xB1, TRINKET, None);
-        bag(&mut items, 0xBA, BAG, &[(2, 0xC1)]);
+        let mut objs = TestObjects::new();
+        item(&mut objs, 0xC1, TRINKET, None);
+        item(&mut objs, 0xB1, TRINKET, None);
+        bag(&mut objs, 0xBA, BAG, &[(2, 0xC1)]);
         let store = player(&[(19, 0xBA), (23, 0xB1)]);
         assert_eq!(
-            find_item(&store, &items, TRINKET, ALL),
+            find_item(&store, &objs.get(), TRINKET, ALL),
             Some((19, 2, 0xC1)),
             "bag 1's inner slot 2, addressed by the bag's own player-array index"
         );
@@ -1693,27 +1745,30 @@ mod find_item_tests {
     /// bar is a real, placeable action (`InventoryType` 18 passes PlaceAction's filter).
     #[test]
     fn an_equipped_bag_is_found_as_itself() {
-        let mut items = Items::default();
-        bag(&mut items, 0xBA, BAG, &[]);
+        let mut objs = TestObjects::new();
+        bag(&mut objs, 0xBA, BAG, &[]);
         let store = player(&[(19, 0xBA)]);
-        assert_eq!(find_item(&store, &items, BAG, ALL), Some((255, 19, 0xBA)));
+        assert_eq!(
+            find_item(&store, &objs.get(), BAG, ALL),
+            Some((255, 19, 0xBA))
+        );
     }
 
     /// The mode-`0x20` charge filter skips a SPENT copy and returns one with uses left — so a
     /// click on a charged item reaches a copy that still works.
     #[test]
     fn the_charge_filter_skips_a_spent_copy() {
-        let mut items = Items::default();
-        item(&mut items, 0xB1, TRINKET, Some(0));
-        item(&mut items, 0xB2, TRINKET, Some(3));
+        let mut objs = TestObjects::new();
+        item(&mut objs, 0xB1, TRINKET, Some(0));
+        item(&mut objs, 0xB2, TRINKET, Some(3));
         let store = player(&[(23, 0xB1), (24, 0xB2)]);
         assert_eq!(
-            find_item(&store, &items, TRINKET, ALL),
+            find_item(&store, &objs.get(), TRINKET, ALL),
             Some((255, 23, 0xB1)),
             "without the filter the first copy wins, spent or not"
         );
         assert_eq!(
-            find_item(&store, &items, TRINKET, CHARGED),
+            find_item(&store, &objs.get(), TRINKET, CHARGED),
             Some((255, 24, 0xB2)),
             "with it, the spent copy is skipped"
         );
@@ -1725,16 +1780,19 @@ mod find_item_tests {
     #[test]
     fn a_key_in_the_keyring_is_found_last() {
         const KEY: u32 = 7_146; // The Scarlet Key
-        let mut items = Items::default();
-        item(&mut items, 0xE1, KEY, None);
+        let mut objs = TestObjects::new();
+        item(&mut objs, 0xE1, KEY, None);
         let store = player(&[(81, 0xE1)]);
-        assert_eq!(find_item(&store, &items, KEY, ALL), Some((255, 81, 0xE1)));
+        assert_eq!(
+            find_item(&store, &objs.get(), KEY, ALL),
+            Some((255, 81, 0xE1))
+        );
 
         // ...and a copy anywhere earlier still wins: the keyring really is last, not first.
-        item(&mut items, 0xE2, KEY, None);
+        item(&mut objs, 0xE2, KEY, None);
         let store = player(&[(81, 0xE1), (23, 0xE2)]);
         assert_eq!(
-            find_item(&store, &items, KEY, ALL),
+            find_item(&store, &objs.get(), KEY, ALL),
             Some((255, 23, 0xE2)),
             "the backpack copy precedes the keyring one"
         );
@@ -1756,22 +1814,38 @@ mod find_item_tests {
         let (tx, _rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
 
+        let mut objs = TestObjects::new();
         let mut items = Items::default();
         let mut key_tpl = test_template("The Scarlet Key");
         key_tpl.bag_family = BAG_FAMILY_KEYS;
         items.insert_template(KEY, Some(key_tpl));
         items.insert_template(BREAD, Some(test_template("Tough Hunk of Bread")));
-        item(&mut items, 0xF1, KEY, None);
-        item(&mut items, 0xF2, BREAD, None);
+        item(&mut objs, 0xF1, KEY, None);
+        item(&mut objs, 0xF2, BREAD, None);
 
         // Nothing at all.
-        assert!(!has_key(&player(&[]), &items, &commands));
+        assert!(!has_key(&player(&[]), &objs.get(), &items, &commands));
         // A non-key in the backpack is not a key.
-        assert!(!has_key(&player(&[(23, 0xF2)]), &items, &commands));
+        assert!(!has_key(
+            &player(&[(23, 0xF2)]),
+            &objs.get(),
+            &items,
+            &commands
+        ));
         // The director's own case: the key sitting in keyring slot 1.
-        assert!(has_key(&player(&[(81, 0xF1)]), &items, &commands));
+        assert!(has_key(
+            &player(&[(81, 0xF1)]),
+            &objs.get(),
+            &items,
+            &commands
+        ));
         // And in the backpack, before it has been filed.
-        assert!(has_key(&player(&[(23, 0xF1)]), &items, &commands));
+        assert!(has_key(
+            &player(&[(23, 0xF1)]),
+            &objs.get(),
+            &items,
+            &commands
+        ));
 
         // The BANK — reachable only because HasKey passes 0x4f rather than the walker's default
         // 0x47. `find_item` must NOT see the same copy (its mode omits 0x08).
@@ -1779,11 +1853,11 @@ mod find_item_tests {
         banked.insert(39u16, 0xF1u64);
         let store = bank_player(&banked);
         assert!(
-            has_key(&store, &items, &commands),
+            has_key(&store, &objs.get(), &items, &commands),
             "a key in the bank still gives you a keyring"
         );
         assert_eq!(
-            find_item(&store, &items, KEY, ALL),
+            find_item(&store, &objs.get(), KEY, ALL),
             None,
             "...while the ordinary item search never reaches the bank"
         );
@@ -1809,8 +1883,7 @@ mod find_item_tests {
 /// `0x47`) and does not. Every case here is a slot band that separates the two scopes.
 #[cfg(test)]
 mod count_of_tests {
-    use super::{count_of, InventoryScope};
-    use crate::items::Items;
+    use super::{count_of, InventoryScope, TestObjects};
     use benilla_protocol::ObjectFields;
 
     // Descriptor indices, raw (the module's own consts are private; the codebase's test idiom).
@@ -1845,41 +1918,41 @@ mod count_of_tests {
         ObjectFields::from_pairs(&pairs)
     }
 
-    /// An item instance of `entry` holding `stack` copies.
-    fn stack(items: &mut Items, guid: u64, entry: u32, stack: u32) {
-        items.insert_object(
+    /// An item instance of `entry` holding `stack` copies, in the one index (2334).
+    fn stack(objects: &mut TestObjects, guid: u64, entry: u32, stack: u32) {
+        objects.spawn(
             guid,
             ObjectFields::from_pairs(&[(ENTRY, entry), (STACK, stack)]),
         );
     }
 
     /// A container instance holding `contents` at its own inner slots.
-    fn bag(items: &mut Items, guid: u64, contents: &[(u8, u64)]) {
+    fn bag(objects: &mut TestObjects, guid: u64, contents: &[(u8, u64)]) {
         let mut pairs = vec![(ENTRY, 4_500), (NUM_SLOTS, 16)];
         for &(slot, held) in contents {
             pairs.push((SLOT_1 + 2 * u16::from(slot), held as u32));
             pairs.push((SLOT_1 + 2 * u16::from(slot) + 1, (held >> 32) as u32));
         }
-        items.insert_object(guid, ObjectFields::from_pairs(&pairs));
+        objects.spawn_container(guid, ObjectFields::from_pairs(&pairs));
     }
 
     /// The headline: bank the quest's items and a quest objective still counts them. This is the
-    /// whole of the mask-`8` finding (wow-re `ui/scratch/quest-leaderboard-law.md` §3.1 — `8` is
+    /// whole of the mask-`8` finding (`0x622420` — `8` is
     /// exactly the bit that *adds the bank*, and every one of the six mask-`8` call sites in the
     /// reference is a quest surface).
     #[test]
     fn a_quest_objective_counts_banked_copies_and_nothing_else_does() {
         let store = player(&[(23, 0xA1), (39, 0xB1)]); // one stack in the backpack, one in the bank
-        let mut items = Items::default();
-        stack(&mut items, 0xA1, AMMO, 3);
-        stack(&mut items, 0xB1, AMMO, 5);
+        let mut objs = TestObjects::new();
+        stack(&mut objs, 0xA1, AMMO, 3);
+        stack(&mut objs, 0xB1, AMMO, 5);
         assert_eq!(
-            count_of(&store, &items, AMMO, InventoryScope::QUEST_ITEMS),
+            count_of(&store, &objs.get(), AMMO, InventoryScope::QUEST_ITEMS),
             8,
             "mask 0x4F sees the bank"
         );
         assert_eq!(
-            count_of(&store, &items, AMMO, InventoryScope::CARRIED),
+            count_of(&store, &objs.get(), AMMO, InventoryScope::CARRIED),
             3,
             "an action-bar/reagent count must NOT see the bank"
         );
@@ -1891,15 +1964,18 @@ mod count_of_tests {
     #[test]
     fn a_quest_objective_counts_the_contents_of_bank_bags() {
         let store = player(&[(63, 0xBB)]); // a bag in bank-bag slot 1
-        let mut items = Items::default();
-        bag(&mut items, 0xBB, &[(0, 0xC1), (4, 0xC2)]);
-        stack(&mut items, 0xC1, AMMO, 2);
-        stack(&mut items, 0xC2, AMMO, 6);
+        let mut objs = TestObjects::new();
+        bag(&mut objs, 0xBB, &[(0, 0xC1), (4, 0xC2)]);
+        stack(&mut objs, 0xC1, AMMO, 2);
+        stack(&mut objs, 0xC2, AMMO, 6);
         assert_eq!(
-            count_of(&store, &items, AMMO, InventoryScope::QUEST_ITEMS),
+            count_of(&store, &objs.get(), AMMO, InventoryScope::QUEST_ITEMS),
             8
         );
-        assert_eq!(count_of(&store, &items, AMMO, InventoryScope::CARRIED), 0);
+        assert_eq!(
+            count_of(&store, &objs.get(), AMMO, InventoryScope::CARRIED),
+            0
+        );
     }
 
     /// The other two bands `0x47` carries that benilla's own [`InventoryScope::CARRIED`] does not:
@@ -1907,15 +1983,15 @@ mod count_of_tests {
     #[test]
     fn the_quest_scope_also_reaches_worn_gear_and_the_keyring() {
         let store = player(&[(5, 0xE1), (81, 0xF1)]); // a worn copy and one in the keyring
-        let mut items = Items::default();
-        stack(&mut items, 0xE1, AMMO, 1);
-        stack(&mut items, 0xF1, AMMO, 1);
+        let mut objs = TestObjects::new();
+        stack(&mut objs, 0xE1, AMMO, 1);
+        stack(&mut objs, 0xF1, AMMO, 1);
         assert_eq!(
-            count_of(&store, &items, AMMO, InventoryScope::QUEST_ITEMS),
+            count_of(&store, &objs.get(), AMMO, InventoryScope::QUEST_ITEMS),
             2
         );
         assert_eq!(
-            count_of(&store, &items, AMMO, InventoryScope::CARRIED),
+            count_of(&store, &objs.get(), AMMO, InventoryScope::CARRIED),
             0,
             "benilla's pre-1158 count reached neither band — the named narrowing"
         );
@@ -1926,15 +2002,18 @@ mod count_of_tests {
     #[test]
     fn carried_bags_are_unchanged_in_both_scopes() {
         let store = player(&[(19, 0xBA), (25, 0xA2)]);
-        let mut items = Items::default();
-        bag(&mut items, 0xBA, &[(2, 0xC1)]);
-        stack(&mut items, 0xC1, AMMO, 4);
-        stack(&mut items, 0xA2, AMMO, 1);
+        let mut objs = TestObjects::new();
+        bag(&mut objs, 0xBA, &[(2, 0xC1)]);
+        stack(&mut objs, 0xC1, AMMO, 4);
+        stack(&mut objs, 0xA2, AMMO, 1);
         assert_eq!(
-            count_of(&store, &items, AMMO, InventoryScope::QUEST_ITEMS),
+            count_of(&store, &objs.get(), AMMO, InventoryScope::QUEST_ITEMS),
+            5
+        );
+        assert_eq!(
+            count_of(&store, &objs.get(), AMMO, InventoryScope::CARRIED),
             5
         );
-        assert_eq!(count_of(&store, &items, AMMO, InventoryScope::CARRIED), 5);
     }
 
     /// Buyback (slots 69–80) has no mask bit at all and is unreachable at every scope — an item
@@ -1944,12 +2023,12 @@ mod count_of_tests {
         // The buyback band has no accessor in the walk by construction; assert the neighbouring
         // bands still resolve so this is a real coverage statement, not a vacuous one.
         let store = player(&[(38, 0xA1), (68, 0xBB)]);
-        let mut items = Items::default();
-        stack(&mut items, 0xA1, AMMO, 1);
-        bag(&mut items, 0xBB, &[(0, 0xC1)]);
-        stack(&mut items, 0xC1, AMMO, 1);
+        let mut objs = TestObjects::new();
+        stack(&mut objs, 0xA1, AMMO, 1);
+        bag(&mut objs, 0xBB, &[(0, 0xC1)]);
+        stack(&mut objs, 0xC1, AMMO, 1);
         assert_eq!(
-            count_of(&store, &items, AMMO, InventoryScope::QUEST_ITEMS),
+            count_of(&store, &objs.get(), AMMO, InventoryScope::QUEST_ITEMS),
             2,
             "last backpack slot + last bank bag, with buyback between them untouched"
         );
diff --git a/crates/benilla-app/src/ui_items/net.rs b/crates/benilla-app/src/ui_items/net.rs
new file mode 100644
index 00000000..714f8e96
--- /dev/null
+++ b/crates/benilla-app/src/ui_items/net.rs
@@ -0,0 +1,266 @@
+//! The item feed's packet handlers (in the net handler table since 2319; the refusal moved out of
+//! the drain's loot arm file) — `SMSG_INVENTORY_CHANGE_FAILURE` onto the equip-error line, the
+//! pending item locks, and the loot latch's sixth clear; and `SMSG_OPEN_CONTAINER` onto the
+//! `BAG_OPEN` queue (decision 2339).
+
+use benilla_protocol::{ObjectFields, SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::{EquipError, EquipErrors, BAG_SLOT_FIRST, BANK_BAG_ID_FIRST};
+use crate::net::{NetHandlerApp, ObjectStore, SelfGuid, SelfPlayer};
+use crate::pending_item_ops::{LockTransitions, PendingItemOps};
+use crate::ui_loot::LootLatch;
+
+/// Register the handlers — called from [`super::UiItemsPlugin`].
+pub(super) fn register(app: &mut App) {
+    app.net_handler(SessionEventKind::InventoryFailure, on_inventory_failure)
+        .net_handler(SessionEventKind::OpenContainer, on_open_container)
+        .net_handler(SessionEventKind::Disconnected, on_session_end);
+}
+
+/// The pending item locks die with the socket — a listener on the session end (a second handler on
+/// the kind, after the bridge's own teardown). The unlock transitions still queued for the feed go
+/// too: they name the old session's slots, and the next session's VM starts with nothing locked.
+fn on_session_end(
+    In(_): In<SessionEvent>,
+    mut pending: ResMut<PendingItemOps>,
+    mut lock_cleared: ResMut<LockTransitions>,
+) {
+    pending.clear_session();
+    lock_cleared.0.clear();
+}
+
+/// The containers the server told us to open (`SMSG_OPEN_CONTAINER`), by container id, waiting
+/// for the feed ([`super::feed::feed_containers`]) to fire `BAG_OPEN(id)` through the VM — this
+/// handler has no `UiScript`, the [`LockTransitions`] shape (decision 2339).
+#[derive(Resource, Default)]
+pub(crate) struct BagOpens(pub(crate) Vec<i64>);
+
+fn on_open_container(
+    In(ev): In<SessionEvent>,
+    self_guid: Res<SelfGuid>,
+    self_q: Query<&ObjectStore, With<SelfPlayer>>,
+    mut opens: ResMut<BagOpens>,
+) {
+    if let SessionEvent::OpenContainer { item } = ev {
+        let store = self_q.single().ok().map(|s| &s.0);
+        match container_of(self_guid.0, store, item) {
+            Some(id) => opens.0.push(id),
+            None => debug!("open container {item:#x}: not one of our bags — no BAG_OPEN"),
+        }
+    }
+}
+
+/// The reference's `BAG_OPEN` raiser `0x4f9410`, transcribed: our own guid names the
+/// backpack, container **0**; otherwise the guid is looked up in the ten bag slots — the four
+/// equipped bags (`PLAYER_FIELD_INV_SLOT_HEAD` 19..22 → containers **1..4**) and the six bank
+/// bags (→ **5..10**), the same numbering `BAG_CLOSED` uses — and a guid in none of them fires
+/// nothing. vmangos sends the packet from `HandleAutoEquipItemOpcode` when the destination is a
+/// bag slot, i.e. when a bag gets equipped, which is why the stock `ContainerFrame_OnEvent`
+/// answers `BAG_OPEN` with `Show()` on the frame carrying that id.
+pub(super) fn container_of(
+    self_guid: Option<u64>,
+    store: Option<&ObjectFields>,
+    item: u64,
+) -> Option<i64> {
+    if self_guid.is_some_and(|me| me == item) {
+        return Some(0);
+    }
+    let store = store?;
+    (0..4u8)
+        .find(|i| store.player_inv_slot(BAG_SLOT_FIRST + i) == Some(item))
+        .map(|i| i64::from(i) + 1)
+        .or_else(|| {
+            (0..6u8)
+                .find(|j| store.player_bank_bag_slot(*j) == Some(item))
+                .map(|j| BANK_BAG_ID_FIRST + i64::from(j))
+        })
+}
+
+fn on_inventory_failure(
+    In(ev): In<SessionEvent>,
+    mut equip_errors: ResMut<EquipErrors>,
+    mut pending: ResMut<PendingItemOps>,
+    mut lock_cleared: ResMut<LockTransitions>,
+    mut latch: ResMut<LootLatch>,
+) {
+    if let SessionEvent::InventoryFailure {
+        reason,
+        required_level,
+        item_guid,
+        bag_slot,
+    } = ev
+    {
+        inventory_failure(
+            reason,
+            required_level,
+            item_guid,
+            bag_slot,
+            &mut equip_errors,
+            &mut pending,
+            &mut lock_cleared,
+            &mut latch,
+        );
+    }
+}
+
+/// The server refused an inventory operation (`SMSG_INVENTORY_CHANGE_FAILURE` — equip level,
+/// proficiency, bag full, …): the UI error line's inventory vocabulary, the equip twin of the
+/// cast-result failure path. Also the pending-lock's failure-driven clear (decision 0216 §4 /
+/// 0218 §3): every arrival here already has reason ≠ 0 (reason 0 is filtered before this event
+/// exists at all — `benilla_protocol::events`'s `if reason != 0` guard), so it always tries a
+/// [`PendingItemOps::clear_by_failure`]. This site has no `UiScript` to fire `ITEM_LOCK_CHANGED`
+/// through, so the transitioned slots queue in [`LockTransitions`] for the container feed
+/// ([`super::feed::feed_containers`]) to drain and fire next time it runs.
+fn inventory_failure(
+    reason: u8,
+    required_level: Option<u32>,
+    item_guid: u64,
+    bag_slot: u8,
+    equip_errors: &mut EquipErrors,
+    pending: &mut PendingItemOps,
+    lock_cleared: &mut LockTransitions,
+    latch: &mut LootLatch,
+) {
+    debug!("net: inventory failure {reason:#04x} (item {item_guid:#x}, bag slot {bag_slot})");
+    equip_errors.0.push(EquipError {
+        reason,
+        required_level,
+        bag_slot,
+    });
+    lock_cleared.0.extend(pending.clear_by_failure(item_guid));
+    // The sixth loot-latch clear (`0x5e3a84`, decision 1477): when
+    // the packet's **first item guid** is the object we are looting, the session ends here. It is
+    // how an item-container loot (a lockbox) closes when the move out of it fails — the one clear
+    // the 1471 census was missing. Guid-matched, as the bytes are.
+    if item_guid != 0 {
+        latch.clear_for(item_guid);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The sixth clear (`0x5e3a84`): an inventory-move failure whose first item guid IS the loot
+    /// target ends that session. Guid-matched, so an unrelated bag failure leaves it alone.
+    #[test]
+    fn an_inventory_failure_on_the_looted_object_clears_the_latch() {
+        const LOCKBOX: u64 = 0x4000_0000_0000_0007;
+        let mut errs = EquipErrors::default();
+        let mut pending = PendingItemOps::default();
+        let mut cleared = LockTransitions::default();
+        let mut latch = LootLatch(Some(LOCKBOX));
+
+        // An unrelated item's failure must not end the session.
+        inventory_failure(
+            2,
+            None,
+            0x1234,
+            0,
+            &mut errs,
+            &mut pending,
+            &mut cleared,
+            &mut latch,
+        );
+        assert_eq!(latch.0, Some(LOCKBOX));
+
+        inventory_failure(
+            2,
+            None,
+            LOCKBOX,
+            0,
+            &mut errs,
+            &mut pending,
+            &mut cleared,
+            &mut latch,
+        );
+        assert_eq!(latch.0, None);
+    }
+    /// **The item locks die with the session.** The lock is item-object state in the reference
+    /// (`item+0x314`), and the objects are rebuilt at every world entry — but ours is a resource,
+    /// and only a resolving field update, a failure or the loot close cleared it. A lockbox opened
+    /// in the frame the socket died never saw any of those, so it stayed greyed and locked for
+    /// the whole next session. Driven through the real registration.
+    #[test]
+    fn the_session_end_drops_every_item_lock() {
+        let mut app = App::new();
+        app.init_resource::<EquipErrors>()
+            .init_resource::<PendingItemOps>()
+            .init_resource::<LockTransitions>()
+            .init_resource::<BagOpens>()
+            .init_resource::<LootLatch>()
+            .init_resource::<SelfGuid>();
+        register(&mut app);
+        app.world_mut()
+            .resource_mut::<PendingItemOps>()
+            .add([(0, 3, 0x4000_0000_0000_0007, 1)]);
+        app.world_mut()
+            .resource_mut::<LockTransitions>()
+            .0
+            .push((0, 5));
+        let epoch = app.world().resource::<PendingItemOps>().epoch();
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![SessionEvent::Disconnected {
+                reason: "socket".into(),
+                end: benilla_protocol::SessionEnd::Lost,
+            }],
+        );
+
+        let pending = app.world().resource::<PendingItemOps>();
+        assert!(pending.is_empty() && !pending.contains(0, 3));
+        assert_ne!(pending.epoch(), epoch, "the feed's gate sees the set move");
+        assert!(
+            app.world().resource::<LockTransitions>().0.is_empty(),
+            "no ITEM_LOCK_CHANGED for the old session's slots"
+        );
+    }
+}
+
+#[cfg(test)]
+mod open_container_tests {
+    use super::*;
+    use benilla_protocol::field::FIELD_PLAYER_INV_SLOT_HEAD;
+
+    /// `PLAYER_FIELD_BANK_BAG_SLOT_1` (index 612; private to the fields module, so spelled here).
+    const BANK_BAG_SLOT_1: u16 = 612;
+
+    /// A self descriptor holding the given guids at the given first-dword indices.
+    fn store(guids: &[(u16, u64)]) -> ObjectFields {
+        let pairs: Vec<(u16, u32)> = guids
+            .iter()
+            .flat_map(|(i, g)| [(*i, *g as u32), (*i + 1, (*g >> 32) as u32)])
+            .collect();
+        ObjectFields::from_pairs(&pairs)
+    }
+
+    #[test]
+    fn the_bag_open_raiser_resolves_the_reference_container_ids() {
+        let me = 0x0000_0000_0000_0042;
+        let bag_in_slot_20 = 0x4000_0000_0000_0b02; // the second equipped bag → container 2
+        let bank_bag_3 = 0x4000_0000_0000_0b44; // the fourth bank bag → container 5 + 3
+        let s = store(&[
+            (FIELD_PLAYER_INV_SLOT_HEAD + 2 * 20, bag_in_slot_20),
+            (BANK_BAG_SLOT_1 + 2 * 3, bank_bag_3),
+        ]);
+        assert_eq!(
+            container_of(Some(me), Some(&s), me),
+            Some(0),
+            "our own guid is the backpack"
+        );
+        assert_eq!(container_of(Some(me), Some(&s), bag_in_slot_20), Some(2));
+        assert_eq!(container_of(Some(me), Some(&s), bank_bag_3), Some(8));
+        assert_eq!(
+            container_of(Some(me), Some(&s), 0xdead),
+            None,
+            "a stranger's guid fires nothing"
+        );
+        assert_eq!(
+            container_of(None, None, me),
+            None,
+            "no self, no store: nothing to match"
+        );
+    }
+}
diff --git a/crates/benilla-app/src/ui_layout.rs b/crates/benilla-app/src/ui_layout.rs
index 14a98660..0353a612 100644
--- a/crates/benilla-app/src/ui_layout.rs
+++ b/crates/benilla-app/src/ui_layout.rs
@@ -47,8 +47,7 @@
 //! **`layout-cache.txt` (`0x490c79`)** → the flat saved file (`0x490c7e`) → the per-addon files →
 //! `AddOns.txt` → the frame teardown. It rides the same five lifecycle roots as SavedVariables —
 //! logout to the character screen, quit, disconnect, application exit and **`/reload`** — and
-//! there is no autosave, no dirty bit and no per-frame write (wow-5875-re `system/ui/ui.md`;
-//! `scratch/camera-settings-persistence.md` §4).
+//! there is no autosave, no dirty bit and no per-frame write.
 //!
 //! Ours takes that slot: [`save_now`], called from [`crate::ui_script::shutdown_ui_state`]
 //! between `PLAYER_LOGOUT` and the flat file. **That is the load-bearing part, and it is what
diff --git a/crates/benilla-app/src/ui_logout.rs b/crates/benilla-app/src/ui_logout.rs
index 3e863b9f..7a1356b9 100644
--- a/crates/benilla-app/src/ui_logout.rs
+++ b/crates/benilla-app/src/ui_logout.rs
@@ -39,7 +39,7 @@
 //!
 //! The 1.12 FrameXML fixes the rest: the CAMP/QUIT dialogs, their 20 s timeouts, and their
 //! `PLAYER_CAMPING` / `PLAYER_QUITING` / `LOGOUT_CANCEL` drivers (UIParent.lua l.304-315, event
-//! ids 276/277/278 in wow-re's `re/events/event-catalog.tsv`).
+//! ids 276/277/278 in the client's event-name table `0xbe1198`).
 
 use benilla_ui::script::{SessionRequest, UiScript};
 use bevy::prelude::*;
@@ -215,9 +215,9 @@ fn drain_logout(
             }
             // `CMSG_PLAYER_LOGOUT`, the forced flavour: the dispatcher's own gate is a live
             // in-world session, and nothing happens without one (decision 1963).
-            // `0x5aaff0` calls the dispatcher with `force = 1`, which BYPASSES the pending bail
-            // and does NOT set the latch (wow-re `staticpopup-dialog-bindings.md` §4) — so a
-            // forced logout is exactly the escape hatch from a stuck pending one.
+            // `0x5aaff0` calls the dispatcher `0x5ab000` with `force = 1`, which BYPASSES the
+            // pending bail and does NOT set the latch — so a forced logout is exactly the escape
+            // hatch from a stuck pending one.
             SessionRequest::ForceLogout => {
                 if self_guid.0.is_some() {
                     info!("logout: forced");
@@ -261,6 +261,7 @@ pub struct UiLogoutPlugin;
 
 impl Plugin for UiLogoutPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<LogoutState>().add_systems(
             Update,
             (
@@ -272,6 +273,33 @@ impl Plugin for UiLogoutPlugin {
     }
 }
 
+/// The logout arc's two narration packets (decision 0674; in the net handler table since 2326)
+/// — this module owns the decision table; the handler is only the hand-off.
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::LogoutState;
+    use crate::net::NetHandlerApp;
+
+    /// Register the pair — called from [`super::UiLogoutPlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::LogoutResponse, on_narration)
+            .net_handler(K::LogoutCancelled, on_narration);
+    }
+
+    fn on_narration(In(ev): In<SessionEvent>, mut logout: ResMut<LogoutState>) {
+        match ev {
+            SessionEvent::LogoutResponse { reason, instant } => {
+                logout.apply_response(reason, instant)
+            }
+            SessionEvent::LogoutCancelled => logout.apply_cancelled(),
+            _ => {}
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use bevy::ecs::system::RunSystemOnce;
diff --git a/crates/benilla-app/src/ui_loot.rs b/crates/benilla-app/src/ui_loot/mod.rs
similarity index 97%
rename from crates/benilla-app/src/ui_loot.rs
rename to crates/benilla-app/src/ui_loot/mod.rs
index a7035baf..f56038a1 100644
--- a/crates/benilla-app/src/ui_loot.rs
+++ b/crates/benilla-app/src/ui_loot/mod.rs
@@ -7,7 +7,7 @@
 //! `SMSG_LOOT_CLEAR_MONEY` → the coin row becomes the same kind of gap
 //! ([`LootState::clear_money`]); `SMSG_LOOT_RELEASE_RESPONSE` → the window closes
 //! ([`LootState::clear`]); the error shape → a red line by GlobalStrings key, raised straight from
-//! the bridge ([`crate::net::apply::loot::loot_error`] — it needs no queue on this side);
+//! the bridge ([`crate::ui_loot::net::loot_error`] — it needs no queue on this side);
 //! `SMSG_ITEM_PUSH_RESULT` → a queued "You receive loot" line ([`LootState::receives`]). A removal
 //! that empties the window arms the client-authoritative **auto-close**
 //! ([`LootState::auto_release`] — the real engine's close-on-last-slot), released by
@@ -36,16 +36,15 @@ use crate::ui_items::KEYRING_CONTAINER;
 use crate::ui_party::{GroupState, GROUPTYPE_RAID, GROUP_MEMBER_SUBGROUP};
 use crate::ui_script::{UiFeed, UiInput};
 
+mod net;
+
 /// The coin-pile row icons (direct `Interface\Icons` paths — `SetTexture` takes them as-is, no DBC),
 /// **six of them, one per decade of copper**, all VERIFIED to extract from `interface.MPQ`.
 ///
 /// This used to be three, chosen by the highest nonzero denomination, and said so in a "stated
-/// approximation" note whose stated reason was that the real selection was not RE-recorded. It is:
-/// `0x4c2460` sends the money row to `0x4c248a call 0x6c62d0`, whose ladder at
-/// `0x6c6307`–`0x6c6386` is exactly the six thresholds below (wow-re
-/// `system/ui/scratch/loot-slot-record.md` §4). The gap closed when that note landed and nothing
-/// here noticed — which is why a "documented approximation" is a thing to re-check against the
-/// sibling repo, not a thing to leave standing.
+/// approximation" note whose stated reason was that the real selection was not read from the
+/// reference. It is: `0x4c2460` sends the money row to `0x4c248a call 0x6c62d0`, whose ladder at
+/// `0x6c6307`–`0x6c6386` is exactly the six thresholds below.
 ///
 /// The icon *order* is the client's own and it is not the numeric one — `_05, _06, _03, _04, _01,
 /// _02` as the amount climbs. What each of the six pieces of art depicts is not claimed here; the
@@ -68,8 +67,7 @@ const BIND_CONFIRM_MIN_QUALITY: u32 = 2;
 /// plain"). `0x4c23a0`'s second guard IS its coin leg: `0x4c23da test ecx,ecx` / `0x4c23dc jne`, so
 /// the money row (0-based slot 0 with `[0xb71ba0] != 0`) falls through to
 /// `0x4c23de xor eax,eax; ret` and never reaches the item-cache block the item rows read
-/// `[rec+0x1c]` from. The same guard is why its `quantity` is 0 (`0x4c22fd`). wow-re
-/// `system/ui/scratch/loot-slot-record.md` §10, a §5 round of five workers.
+/// `[rec+0x1c]` from. The same guard is why its `quantity` is 0 (`0x4c22fd`).
 ///
 /// Nothing downstream re-colours it: stock `LootFrame_Update` has no coin special case
 /// (`LootFrame.lua:81-85`) and `ITEM_QUALITY_COLORS[0]` is `0xff9d9d9d`.
@@ -470,11 +468,9 @@ impl LootState {
 /// `show_loot_spam` is 1.12's own `showLootSpam` — the *Detailed Loot Information* checkbox, whose
 /// subject is **group loot rolls**, not loot messages generally (decision 1589, the Chat page).
 /// It rides here rather than on [`crate::ui_loot_roll`] because it is one loot knob among the
-/// loot knobs and [`on_cvar`] writes both. VERIFIED at the bytes (wow-re
-/// `system/object-layer/scratch/lootroll-chat-and-lifecycle.md` §4): the CVar is `0xb4e2bc`,
-/// registered at `0x48fd1c` with default `"1"` and flags 5, and a byte census over the whole
-/// binary finds exactly four references — one writer and three readers, all three inside the
-/// loot-roll line composers.
+/// loot knobs and [`on_cvar`] writes both. The CVar is `0xb4e2bc`, registered at `0x48fd1c` with
+/// default `"1"` and flags 5, and a byte census over the whole binary finds exactly four
+/// references — one writer and three readers, all three inside the loot-roll line composers.
 #[derive(Resource)]
 pub(crate) struct LootConfig {
     pub(crate) auto_loot: bool,
@@ -493,7 +489,7 @@ impl Default for LootConfig {
 }
 
 /// The client-local **loot-target latch** — the mirror of the real client's `[player+0x1d28]`
-/// guid (wow-re `loot-anim-leg.md` §5, the 2026-08-21 §5 trio; decisions 0515 / 1471 / **1477**).
+/// guid (decisions 0515 / 1471 / **1477**).
 /// It says *a loot session is open on this object*, and it is read by far more than the kneel: the
 /// loot cursor, the re-loot lock-out (`0x5ec110`), `CMSG_LOOT_MONEY`'s gate, auto-loot.
 ///
@@ -514,7 +510,7 @@ impl Default for LootConfig {
 ///   vmangos replies `SendLoot(item guid, LOOT_CORPSE)`, i.e. wire type **1**, which a cold latch
 ///   refuses. 1477 read this arm as pose-only and left it out; the window stopped opening;
 /// - `CGPlayer_C::OnLootResponse 0x5eb900`, through its **admission gate** — see
-///   [`crate::net::apply::loot::loot_response`]. Not unconditional: a `loot_type == 1` response
+///   [`crate::ui_loot::net::loot_response`]. Not unconditional: a `loot_type == 1` response
 ///   against a cold latch is *refused and bounced*.
 ///
 /// Cleared on release/close (`0x48f2c9`/`0x5ec0d4`). Ours clears **guid-matched** (release
@@ -525,10 +521,9 @@ impl Default for LootConfig {
 pub(crate) struct LootLatch(pub(crate) Option<u64>);
 
 /// **Predicate B `0x612710`, the local-player branch** — whether the object the [`LootLatch`]
-/// currently names is one the character *kneels at* (wow-re `loot-anim-leg.md` §8, byte-verified
-/// §5 trio 2026-08-21; decision 1477). The loot leg `0x5fd260` needs predicate A (a session is
-/// open) **and** this one, and the split is the whole reason a fishing bobber does not kneel while
-/// a chest does — the latch is armed identically for both.
+/// currently names is one the character *kneels at* (decision 1477). The loot leg `0x5fd260` needs
+/// predicate A (a session is open) **and** this one, and the split is the whole reason a fishing
+/// bobber does not kneel while a chest does — the latch is armed identically for both.
 ///
 /// The byte table, transcribed:
 ///
@@ -603,16 +598,17 @@ impl LootLatch {
 /// reference's guard `0x60e990`, which every player-initiated movement-START emitter calls first
 /// and whose tail (`arg2 == 0`) closes an open loot: forward/back, strafe, keyboard-turn and pitch
 /// START, pitch STOP, `SetPitch`, and Jump. Mouse-look `SetFacing` passes `arg2 = 1` and does not.
-/// Written by `player::control` beside the cast bar's [`crate::ui_cast::LocalMoveStart`] (a
+/// Written by `player::control` beside the cast bar's [`crate::spell::LocalMoveStart`] (a
 /// different mask — the cast's `0x10f0` excludes TURN, this one includes it), consumed and cleared
 /// by [`drain_loot`] the next frame, which runs `CloseInteraction 0x48f200(cl=1, dl=1, 0)`: the
 /// kneel latch clears, `CMSG_LOOT_RELEASE` goes out, the frame closes, and a dead corpse that is
 /// also the selection is deselected — at distance zero, on the first step. Decision 2097.
 ///
-/// **The loot window has no distance leash at all** (wow-re `loot-window-leash.md`, a §5 that
-/// refuted 2094 and the 1741 census row it rested on: that row is a dead lottery kiosk). vmangos
-/// happens to release on every movement opcode too (`MovementHandler.cpp:1108`), which is why the
-/// missing client-side close was invisible on the local server and plain on cmangos (B381).
+/// **The loot window has no distance leash at all** (no loot target reaches the per-frame range
+/// gate `0x493230`, which refutes 2094 and the 1741 census row it rested on: that row is a dead
+/// lottery kiosk, `0x4c3eb0`). vmangos happens to release on every movement opcode too
+/// (`MovementHandler.cpp:1108`), which is why the missing client-side close was invisible on the
+/// local server and plain on cmangos (B381).
 #[derive(Resource, Default)]
 pub(crate) struct LootMoveStart(pub(crate) bool);
 
@@ -630,6 +626,7 @@ pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut loot: ResMut<LootCo
 
 impl Plugin for UiLootPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.add_observer(on_cvar);
         app.init_resource::<LootState>()
             .init_resource::<LootConfig>()
@@ -659,7 +656,7 @@ impl Plugin for UiLootPlugin {
 ///
 /// **Stated approximation (documented gap).** 1.12.1's GlobalStrings has **no** `GOLD_AMOUNT` /
 /// `SILVER_AMOUNT` / `COPPER_AMOUNT` "%d <Word>" patterns — those arrive in a later client. The real
-/// 1.12 coin text is produced inside `GetLootSlotInfo` (a C function, not FrameXML, not RE-recorded),
+/// 1.12 coin text is produced inside `GetLootSlotInfo` (a C function, not FrameXML, not yet read),
 /// so we compose "<n> <Word>" from the bare `GOLD`/`SILVER`/`COPPER` words and join them the way
 /// [`format_money`] always has (a single space); the exact client wording/separator is the stand-in.
 fn format_money(copper: u32) -> String {
@@ -734,7 +731,7 @@ fn resolve_item(
         item_id: item.item_id,
         link,
         // The roll rides as the raw id, exactly as the client's own loot record keeps it: the
-        // tooltip resolves it against the pushed roll table (§E5). Decision 1547.
+        // tooltip resolves it against the pushed roll table (`0x52b7bf`). Decision 1547.
         random_property_id: item.random_property_id,
     }
 }
@@ -1010,7 +1007,7 @@ fn feed_loot(
             // edge to zero (`0x4c2af6 dec` / `jne`). There is no repaint path to fall back on:
             // `LootFrame_Update` is reachable only through the XML `<OnShow>`, and `ShowUIPanel`
             // early-returns on an already-visible frame, so a second `LOOT_OPENED` would do
-            // nothing. Deferring IS the mechanism (wow-re `loot-slot-record.md` §11).
+            // nothing. Deferring IS the mechanism.
             //
             // Returning without advancing `last` re-evaluates next frame; the queries are already
             // in flight from `snapshot` above, and the auto-loot sweep below waits with the window,
@@ -1035,8 +1032,7 @@ fn feed_loot(
                         }
                         // Only an ALLOW_LOOT row: the reference's auto-loot sweep processes a
                         // record exactly when the wire's slot-type getter answers 0
-                        // (`0x4c2180`/`0x4c2196 test eax,eax; jne` — wow-re
-                        // `ui/scratch/loot-slot-record.md` §2). So a master-loot row is not
+                        // (`0x4c2180`/`0x4c2196 test eax,eax; jne`). So a master-loot row is not
                         // swept into a dropdown, and a roll-in-progress row is not sent as a
                         // take the server would refuse.
                         Some(LootAction::Item {
@@ -1123,7 +1119,7 @@ fn bind_confirm_required(items: &Items, commands: &NetCommands, item_id: u32) ->
 }
 
 /// `CloseInteraction 0x48f200(cl=1, dl=1, 0)` off the movement-START guard (decision 2097),
-/// transcribed per loot-target type from wow-re `loot-window-leash.md` §5:
+/// transcribed per loot-target type:
 ///
 /// | open loot | on the first movement start |
 /// |---|---|
@@ -1209,10 +1205,10 @@ fn drain_loot(
             // candidate dropdown instead of sending a take, and the decision is made here, on the
             // wire's slot-type byte, rather than in Lua: the real client branches on the same byte
             // inside its take dispatcher before any Lua runs (`0x4c2790`, which already reads the
-            // getter at `0x4c28a9` — wow-re `ui/scratch/loot-slot-record.md` §2), and the
-            // reference `LootFrame.lua` never consults `GetLootMethod` at all. The row's
-            // `LootFrame.selected*` bookkeeping is already stashed by the Lua `OnClick` that ran
-            // before this drain, so the event's `ToggleDropDownMenu` has its anchor button.
+            // getter at `0x4c28a9`), and the reference `LootFrame.lua` never consults
+            // `GetLootMethod` at all. The row's `LootFrame.selected*` bookkeeping is already
+            // stashed by the Lua `OnClick` that ran before this drain, so the event's
+            // `ToggleDropDownMenu` has its anchor button.
             Some(LootAction::Item { slot_type, .. }) if slot_type == slot_type::MASTER => {
                 debug!("ui_loot: row {index} is master-loot — opening the candidate list");
                 script.fire_event("OPEN_MASTER_LOOT_LIST", vec![]);
@@ -1242,8 +1238,8 @@ fn drain_loot(
                 let _ = commands
                     .0
                     .send(ClientCommand::AutostoreLootItem { slot: wire_slot });
-                // The pickup sound plays optimistically at the click, before the send (wow-re
-                // `acquire-spend-sounds.md`): looting an item plays its ItemGroupSounds kit[0].
+                // The pickup sound plays optimistically at the click, before the send (`0x4c2926`):
+                // looting an item plays its ItemGroupSounds kit[0].
                 pickup.write(crate::sound::LootPickupSound { display_id });
             }
             None => debug!("ui_loot: BenillaTakeLootSlot({index}) out of range — ignored"),
@@ -1393,7 +1389,7 @@ mod tests {
         app.world().resource::<LootKneel>().0
     }
 
-    /// **Predicate B `0x612710`, the local branch** (wow-re `loot-anim-leg.md` §8; decision 1477).
+    /// **Predicate B `0x612710`, the local branch** (decision 1477).
     /// The whole row set, because the *point* of this predicate is that arming the latch is not
     /// the same question as kneeling: a fishing bobber and a chest arm it identically, and only
     /// one of them is knelt at. Without this filter, 1471's response-arm gave benilla a kneel at
@@ -2272,10 +2268,9 @@ mod tests {
 
     /// The **rolled name** — the reference composes every display of an item's name through
     /// `0x5d8b00(entry, randomPropertyId)`, which joins `ItemRandomProperties`' suffix with
-    /// `ITEM_SUFFIX_TEMPLATE` ("%s %s"). Byte-verified for the loot row itself (`GetLootSlotInfo`'s
-    /// `item` producer `0x4c2550` ends in that call, wow-re `loot-slot-record.md` §3), and the
-    /// tooltip's own title line makes the same call — so row text, tooltip plate and link agree by
-    /// construction. Decision 1547.
+    /// `ITEM_SUFFIX_TEMPLATE` ("%s %s"). That holds for the loot row itself (`GetLootSlotInfo`'s
+    /// `item` producer `0x4c2550` ends in that call), and the tooltip's own title line makes the
+    /// same call — so row text, tooltip plate and link agree by construction. Decision 1547.
     #[test]
     fn a_rolled_drop_reads_its_suffix_in_the_row_the_link_and_the_lines() {
         use benilla_formats::{RandomProperty, RandomPropertyCatalog};
@@ -2516,8 +2511,8 @@ mod tests {
     /// **Movement closes the loot** (2097): the controller's move-start report makes the drain
     /// run `CloseInteraction` — latch cleared, the release on the wire once, the window gone, a
     /// dead-corpse selection torn down — with no server help and no VM. The exemptions the bytes
-    /// carve stay open: an item-guid loot (a lockbox) and a disenchant window with rows left; an
-    /// emptied disenchant closes like the rest. A GameObject (a fishing bobber) closes too — it
+    /// carve out stay open: an item-guid loot (a lockbox) and a disenchant window with rows left;
+    /// an emptied disenchant closes like the rest. A GameObject (a fishing bobber) closes too — it
     /// takes the same path as a corpse.
     #[test]
     fn a_movement_start_closes_and_releases_the_open_loot() {
diff --git a/crates/benilla-app/src/net/apply/loot.rs b/crates/benilla-app/src/ui_loot/net.rs
similarity index 71%
rename from crates/benilla-app/src/net/apply/loot.rs
rename to crates/benilla-app/src/ui_loot/net.rs
index 2d952fe0..c919d5e1 100644
--- a/crates/benilla-app/src/net/apply/loot.rs
+++ b/crates/benilla-app/src/ui_loot/net.rs
@@ -1,23 +1,154 @@
-//! Loot-window + item-template/inventory-failure arm bodies for [`super::apply_net_updates`]'s
-//! dispatch match — one of the largest arm families, split out on its own (decision 0084's loot
-//! feed, plus the item-template ask-once cache and the equip-refusal UI line). Each `pub(super)` fn
-//! here is exactly one arm's body; the match at the call site stays the dispatcher, one call per
-//! arm.
+//! The loot window's packet handlers (decision 0084; in the net handler table since 2319, moved
+//! out of the drain's loot arm file) — the [`LootState`] session and the [`LootLatch`] the loot
+//! feed ([`super`]) reads, the fishing verdicts, and the item push that prints "You receive …".
+//! The group rolls are [`crate::ui_loot_roll`]'s and the inventory refusal is
+//! [`crate::ui_items`]'s.
 
-use benilla_protocol::messages::{
-    ItemPushResult, LootAllPassed, LootItem, LootRoll, LootRollWon, LootStartRoll,
-};
-use benilla_protocol::ItemInfo;
+use benilla_protocol::messages::{ItemPushResult, LootItem};
+use benilla_protocol::{SessionEvent, SessionEventKind};
 use bevy::prelude::*;
 
-use super::super::SelfGuid;
-use crate::items::Items;
-use crate::net::ClientCommand;
+use super::{LootLatch, LootState};
+use crate::net::{ClientCommand, NetCommands, NetHandlerApp, SelfGuid};
 use crate::pending_item_ops::{LockTransitions, PendingItemOps};
 use crate::ui_action::{UiError, UiErrorKeys};
-use crate::ui_items::{EquipError, EquipErrors};
-use crate::ui_loot::{LootLatch, LootState};
-use crate::ui_loot_roll::LootRolls;
+
+/// Register the loot handlers — called from [`super::UiLootPlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::LootResponse, on_response)
+        .net_handler(K::LootError, on_error)
+        .net_handler(K::LootRemoved, on_removed)
+        .net_handler(K::LootMoneyNotify, on_money_notify)
+        .net_handler(K::LootClearMoney, on_clear_money)
+        .net_handler(K::LootReleaseResponse, on_release_response)
+        .net_handler(K::LootMasterList, on_master_list)
+        .net_handler(K::FishNotHooked, on_fish_verdict)
+        .net_handler(K::FishEscaped, on_fish_verdict)
+        .net_handler(K::ItemPushResult, on_item_push_result)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_response(
+    In(ev): In<SessionEvent>,
+    mut loot: ResMut<LootState>,
+    mut latch: ResMut<LootLatch>,
+    commands: Res<NetCommands>,
+) {
+    if let SessionEvent::LootResponse {
+        guid,
+        loot_type,
+        gold,
+        items,
+    } = ev
+    {
+        loot_response(
+            guid, loot_type, gold, items, &mut loot, &mut latch, &commands,
+        );
+    }
+}
+
+fn on_error(
+    In(ev): In<SessionEvent>,
+    mut errors: ResMut<UiErrorKeys>,
+    mut latch: ResMut<LootLatch>,
+    mut pending: ResMut<PendingItemOps>,
+    mut lock_cleared: ResMut<LockTransitions>,
+) {
+    if let SessionEvent::LootError { guid, error } = ev {
+        let unlock = ItemUnlock {
+            pending: &mut pending,
+            lock_cleared: &mut lock_cleared,
+        };
+        loot_error(guid, error, &mut errors, &mut latch, unlock);
+    }
+}
+
+fn on_removed(In(ev): In<SessionEvent>, mut loot: ResMut<LootState>) {
+    if let SessionEvent::LootRemoved { slot } = ev {
+        loot_removed(slot, &mut loot);
+    }
+}
+
+fn on_money_notify(In(ev): In<SessionEvent>) {
+    if let SessionEvent::LootMoneyNotify { amount } = ev {
+        loot_money_notify(amount);
+    }
+}
+
+fn on_clear_money(In(ev): In<SessionEvent>, mut loot: ResMut<LootState>) {
+    if let SessionEvent::LootClearMoney = ev {
+        loot_clear_money(&mut loot);
+    }
+}
+
+fn on_release_response(
+    In(ev): In<SessionEvent>,
+    mut loot: ResMut<LootState>,
+    mut latch: ResMut<LootLatch>,
+    mut pending: ResMut<PendingItemOps>,
+    mut lock_cleared: ResMut<LockTransitions>,
+) {
+    if let SessionEvent::LootReleaseResponse { guid } = ev {
+        let unlock = ItemUnlock {
+            pending: &mut pending,
+            lock_cleared: &mut lock_cleared,
+        };
+        loot_release_response(guid, &mut loot, &mut latch, unlock);
+    }
+}
+
+/// **`UnlockItem 0x495420`** as the loot closes call it — on the loot guid, which unlocks
+/// something only when that guid is an item we locked (a lockbox, clam or loot bag, locked at its
+/// `CMSG_OPEN_ITEM` send — decision 0916). The unlocked slots queue in [`LockTransitions`] for the
+/// container feed to fire `ITEM_LOCK_CHANGED`, like the inventory failure's clear.
+struct ItemUnlock<'a> {
+    pending: &'a mut PendingItemOps,
+    lock_cleared: &'a mut LockTransitions,
+}
+
+impl ItemUnlock<'_> {
+    fn unlock(self, guid: u64) {
+        self.lock_cleared.0.extend(self.pending.clear_by_guid(guid));
+    }
+}
+
+fn on_master_list(In(ev): In<SessionEvent>, mut loot: ResMut<LootState>) {
+    if let SessionEvent::LootMasterList { candidates } = ev {
+        loot_master_list(candidates, &mut loot);
+    }
+}
+
+fn on_fish_verdict(In(ev): In<SessionEvent>, mut errors: ResMut<UiErrorKeys>) {
+    match ev {
+        SessionEvent::FishNotHooked => fish_verdict(false, &mut errors),
+        SessionEvent::FishEscaped => fish_verdict(true, &mut errors),
+        _ => {}
+    }
+}
+
+fn on_item_push_result(
+    In(ev): In<SessionEvent>,
+    self_guid: Res<SelfGuid>,
+    mut loot: ResMut<LootState>,
+    mut tutorials: ResMut<crate::tutorial::Tutorials>,
+) {
+    if let SessionEvent::ItemPushResult(p) = ev {
+        item_push_result(p, &self_guid, &mut loot, &mut tutorials);
+    }
+}
+
+/// An open loot window and the kneel latch die with the socket (unconditionally). A listener on
+/// the session end (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(
+    In(_): In<SessionEvent>,
+    mut loot: ResMut<LootState>,
+    mut latch: ResMut<LootLatch>,
+) {
+    loot.clear_session();
+    latch.0 = None;
+}
 
 /// The wire `loot_type` values `SMSG_LOOT_RESPONSE`'s **cold-latch** admission accepts
 /// (`0x5eb94b`/`0x5eb953`/`0x5eb95b`) — vmangos `LootType`'s `PICKPOCKETING(2)` · `FISHING(3)` ·
@@ -30,8 +161,8 @@ const SERVER_STARTED_LOOT: [u8; 3] = [2, 3, 4];
 /// reach the window through an `OPEN_LOCK` cast, never through `CMSG_LOOT` (vmangos
 /// `Spell::SendLoot` → `Player::SendLoot`).
 ///
-/// **This handler is an admission gate, not an unconditional open** (wow-re `loot-anim-leg.md` §7,
-/// byte-verified; decision 1477 correcting 1471). `0x5eb924`:
+/// **This handler is an admission gate, not an unconditional open** (decision 1477 correcting
+/// 1471). `0x5eb924`:
 ///
 /// ```text
 /// ACCEPT ⇔ (latch != 0 && latch == pkt.guid) || (latch == 0 && loot_type ∈ {2,3,4})
@@ -45,15 +176,16 @@ const SERVER_STARTED_LOOT: [u8; 3] = [2, 3, 4];
 ///
 /// The accepted arm writes the latch verbatim (`0x5ebb60`) and — verified over the whole success
 /// path — calls **neither** the base-anim recompute nor the Loot-50 force-play. A chest is already
-/// kneeling by now: its arm was `SMSG_SPELL_GO` (§6, [`super::spells`]), one packet earlier.
-pub(super) fn loot_response(
+/// kneeling by now: its arm was `SMSG_SPELL_GO` (`0x6e831b`, [`super::spells`]), one packet
+/// earlier.
+fn loot_response(
     guid: u64,
     loot_type: u8,
     gold: u32,
     items: Vec<LootItem>,
     loot: &mut LootState,
     latch: &mut LootLatch,
-    net: &crate::net::NetCommands,
+    net: &NetCommands,
 ) {
     // `0x5eb924`–`0x5eb95b`, transcribed.
     let accept = match latch.0 {
@@ -75,7 +207,7 @@ pub(super) fn loot_response(
         return;
     }
     // The loot window opens (decision 0084): fill LootState from the wire; the feed
-    // ([`crate::ui_loot`]) resolves rows + fires LOOT_OPENED next frame. `loot_type` rides along
+    // ([`super`]) resolves rows + fires LOOT_OPENED next frame. `loot_type` rides along
     // for `IsFishingLoot()` (decision 1086).
     debug!(
         "net: loot response {guid:#x} type {loot_type} gold {gold} {} item(s)",
@@ -85,7 +217,7 @@ pub(super) fn loot_response(
     // `0x5ebb60` — the packet's guid, verbatim. Re-arming a corpse's already-matching latch is a
     // no-op; a chest re-arms what `SMSG_SPELL_GO` armed; a **fishing** bobber arms here for the
     // first time and still does not kneel, because the pose is predicate B's call, not the
-    // latch's ([`crate::ui_loot::LootKneel`]).
+    // latch's ([`super::LootKneel`]).
     latch.0 = Some(guid);
 }
 
@@ -94,9 +226,9 @@ pub(super) fn loot_response(
 /// ("Your fish got away!") when the skill roll failed on the click, `ERR_FISH_NOT_HOOKED`
 /// ("No fish are hooked.") when the bobber expired or was clicked before the splash. Yellow, not
 /// red: the reference handlers (`0x5e3fc5`/`0x5e3fe2` → `DisplayError` ids `0x13e`/`0x13f`) are
-/// **type-1** registry entries, which fire `UI_INFO_MESSAGE` — byte-verified in wow-re
-/// `fish-msg-handlers.md`, correcting 1086's shipped guess (the fold-back record).
-pub(super) fn fish_verdict(escaped: bool, errors: &mut UiErrorKeys) {
+/// **type-1** registry entries, which fire `UI_INFO_MESSAGE` (`DisplayError`'s type-1 arm
+/// `0x49684b`), correcting 1086's shipped guess.
+fn fish_verdict(escaped: bool, errors: &mut UiErrorKeys) {
     let key = if escaped {
         "ERR_FISH_ESCAPED"
     } else {
@@ -106,8 +238,7 @@ pub(super) fn fish_verdict(escaped: bool, errors: &mut UiErrorKeys) {
     errors.0.push(UiError::key(key));
 }
 
-/// The **default** arm releases — VERIFIED at the bytes (wow-re §5,
-/// `system/object-layer/scratch/loot-anim-leg.md` §7.1).
+/// The **default** arm releases.
 ///
 /// The out-of-range branch is not merely *adjacent* to code 7's arm, it **is** code 7's arm:
 ///
@@ -140,7 +271,7 @@ struct LootRefusal {
 }
 
 /// The refusal a `SMSG_LOOT_RESPONSE` error code produces — **the reference's own jump table**,
-/// transcribed (wow-re `system/ui/scratch/loot-slot-record.md` §1, byte-verified).
+/// transcribed.
 ///
 /// The error leg is entered on `lootType == 0` (`0x5eb9f4`), reads the code (`0x5eba02`) and
 /// dispatches `0x5eba0b add eax,-4; cmp eax,0xa; ja <default>; jmp [4*eax + 0x5ebc64]`. The
@@ -203,8 +334,12 @@ fn loot_refusal(reason: u8) -> LootRefusal {
 /// localization. Before this, benilla composed its own eight sentences here and six of them said
 /// something the client never says.
 ///
-/// **Two gaps this deliberately does not close** (surfaced by the wow-re §5, named here rather
-/// than left to a later bug report):
+/// The arms that release run the reference's release tail `0x5ebac2`, which also calls
+/// `UnlockItem 0x495420` on the packet's guid: a refused lockbox open drops the item's pending
+/// lock. For a corpse or chest guid there is no item, and nothing unlocks.
+///
+/// **A gap this deliberately does not close** (named here rather than left to a later bug
+/// report):
 ///
 /// 1. **A guid-MISMATCHED error takes a different arm in the reference.** The error leg is
 ///    reachable only past the admission gate, so the reference only ever *displays* a refusal for
@@ -212,11 +347,13 @@ fn loot_refusal(reason: u8) -> LootRefusal {
 ///    unconditionally, shows **nothing**, and (because `lootType == 0`) sends nothing. benilla has
 ///    no admission gate on the error shape — it displays the line and keeps the latch. Reachable
 ///    only under the corpse-switch race, and it belongs with the gate (1477), not with the text.
-/// 2. **`UnlockItem` fires `ITEM_LOCK_CHANGED` (188)** on the way through the tail, clearing
-///    `[item+0x314]` bit 0. That matters only when the loot source is an ITEM guid — a lockbox —
-///    where a refused open should drop the item's pending lock; for a corpse or chest guid there
-///    is no item to unlock. benilla does not touch [`LockTransitions`] here.
-pub(super) fn loot_error(guid: u64, error: u8, errors: &mut UiErrorKeys, latch: &mut LootLatch) {
+fn loot_error(
+    guid: u64,
+    error: u8,
+    errors: &mut UiErrorKeys,
+    latch: &mut LootLatch,
+    unlock: ItemUnlock,
+) {
     let LootRefusal { key, releases } = loot_refusal(error);
     debug!("net: loot error {error} on {guid:#x} → {key} (releases: {releases})");
     errors.0.push(UiError::key(key));
@@ -224,25 +361,26 @@ pub(super) fn loot_error(guid: u64, error: u8, errors: &mut UiErrorKeys, latch:
         // The latch armed at the `CMSG_LOOT` send drops (guid-matched — see [`LootLatch`]), or the
         // character would kneel forever at a corpse whose window never opened (decision 0515).
         latch.clear_for(guid);
+        unlock.unlock(guid);
     }
 }
 
 /// One loot-window row was taken, by anyone (`SMSG_LOOT_REMOVED`) — the UI clears that row.
-pub(super) fn loot_removed(slot: u8, loot: &mut LootState) {
+fn loot_removed(slot: u8, loot: &mut LootState) {
     // A row was taken (by anyone): drop it; the feed repaints via LOOT_UPDATE.
     debug!("net: loot slot {slot} removed");
     loot.remove_slot(slot);
 }
 
 /// Our share of the loot's coin pile (`SMSG_LOOT_MONEY_NOTIFY`), answering our `CMSG_LOOT_MONEY`.
-pub(super) fn loot_money_notify(amount: u32) {
+fn loot_money_notify(amount: u32) {
     // Our share of the coin pile — informational; the coin row drops on CLEAR_MONEY and
     // the purse rides the ordinary COINAGE flush. Solo looting rarely sends this.
     debug!("net: loot money {amount}");
 }
 
 /// The coin line disappears for every current looter (`SMSG_LOOT_CLEAR_MONEY`).
-pub(super) fn loot_clear_money(loot: &mut LootState) {
+fn loot_clear_money(loot: &mut LootState) {
     // The coin line disappears for everyone → drop the coin row.
     debug!("net: loot coin line cleared");
     loot.clear_money();
@@ -252,52 +390,28 @@ pub(super) fn loot_clear_money(loot: &mut LootState) {
 /// Idempotent — a client-side close already cleared. The latch clear is **guid-matched**: under
 /// the corpse-switch race (loot B requested while A was open) the old window's release response
 /// must not drop the latch the new request just armed (decision 0515).
-pub(super) fn loot_release_response(guid: u64, loot: &mut LootState, latch: &mut LootLatch) {
+///
+/// **An item loot unlocks here.** The handler (`0x5ec090`) ends in `0x48f200(cl=0, dl=0)`, whose
+/// `48f299` leg calls `UnlockItem 0x495420` when the loot object is an ITEM (`0x48f200` gates
+/// the unlock on `dl == 0`). It is the only clear an opened lockbox closed with loot left
+/// ever gets: vmangos' `DoLootRelease` destroys the item only once it is fully looted, so its
+/// slot never changes and [`PendingItemOps::resolve`] has nothing to see.
+fn loot_release_response(
+    guid: u64,
+    loot: &mut LootState,
+    latch: &mut LootLatch,
+    unlock: ItemUnlock,
+) {
     debug!("net: loot released {guid:#x}");
     loot.clear();
     latch.clear_for(guid);
-}
-
-/// A group roll opened on one drop (`SMSG_LOOT_START_ROLL`) — a `GroupLootFrame` goes up with
-/// Need/Greed/Pass and the countdown bar (decision 0591).
-pub(super) fn loot_start_roll(p: LootStartRoll, rolls: &mut LootRolls) {
-    debug!(
-        "net: loot roll opened on item {} ({:#x} slot {}), {} ms",
-        p.item_id, p.looted_target, p.item_slot, p.countdown_ms
-    );
-    rolls.start(p);
-}
-
-/// One roller's vote or dice result (`SMSG_LOOT_ROLL`) — the chat announcement line. The
-/// `(roll_number, roll_type)` pair is overloaded; `LootRoll::is_dice`/`vote` disentangle it.
-pub(super) fn loot_roll(p: LootRoll, rolls: &mut LootRolls) {
-    debug!(
-        "net: loot roll announce — roller {:#x} number {} type {}",
-        p.roller, p.roll_number, p.roll_type
-    );
-    rolls.announce(p);
-}
-
-/// A group roll resolved (`SMSG_LOOT_ROLL_WON`) — the "won" line, and that roll's frame closes.
-pub(super) fn loot_roll_won(p: LootRollWon, rolls: &mut LootRolls) {
-    debug!(
-        "net: loot roll won by {:#x} with {} (type {})",
-        p.winner, p.roll_number, p.roll_type
-    );
-    rolls.won(p);
-}
-
-/// Everyone passed (`SMSG_LOOT_ALL_PASSED`) — the frame closes and the item returns to the corpse
-/// as an ordinary lootable row.
-pub(super) fn loot_all_passed(p: LootAllPassed, rolls: &mut LootRolls) {
-    debug!("net: loot roll — everyone passed on item {}", p.item_id);
-    rolls.all_passed(p);
+    unlock.unlock(guid);
 }
 
 /// The master-loot candidate list (`SMSG_LOOT_MASTER_LIST`, decision 1675) — who the master looter
 /// may hand a row to. It arrives from inside the server's `SendLoot`, so it lands just AHEAD of the
 /// `SMSG_LOOT_RESPONSE` it belongs to; `LootState` stages it and the open claims it.
-pub(super) fn loot_master_list(candidates: Vec<u64>, loot: &mut LootState) {
+fn loot_master_list(candidates: Vec<u64>, loot: &mut LootState) {
     debug!("net: master-loot candidates: {} eligible", candidates.len());
     loot.set_master_candidates(candidates);
 }
@@ -325,7 +439,7 @@ fn is_our_push(p: &ItemPushResult, self_guid: &SelfGuid) -> bool {
 /// self check being the only thing that can stop a push here. The reference's
 /// `CGGameUI::OnItemPush 0x491a60` emits both from this one packet: it returns early only on a guid
 /// mismatch, and tests `showInChat` further down, after the `ITEM_PUSH` fire.
-pub(super) fn item_push_result(
+fn item_push_result(
     p: ItemPushResult,
     self_guid: &SelfGuid,
     loot: &mut LootState,
@@ -346,56 +460,25 @@ pub(super) fn item_push_result(
     loot.push_receive(&p);
 }
 
-/// An item template's display head (`SMSG_ITEM_QUERY_SINGLE_RESPONSE`, answering our
-/// `CMSG_ITEM_QUERY_SINGLE`).
-pub(super) fn item_template(entry: u32, info: Option<ItemInfo>, items: &mut Items) {
-    // Fill the ask-once template cache (decisions 0068/0072 — one cache serves held-
-    // item resolution and the container layer); a server miss records `None` so the
-    // entry is never re-asked. Consumers re-read it next frame.
-    debug!("net: item template {entry} → {info:?}");
-    items.insert_template(entry, info);
-}
-
-/// The server refused an inventory operation (`SMSG_INVENTORY_CHANGE_FAILURE` — equip level,
-/// proficiency, bag full, …): the UI error line's inventory vocabulary, the equip twin of the
-/// cast-result failure path. Also the pending-lock's failure-driven clear (decision 0216 §4 /
-/// 0218 §3): every arrival here already has reason ≠ 0 (reason 0 is filtered before this event
-/// exists at all — `benilla_protocol::events`'s `if reason != 0` guard), so it always tries a
-/// [`PendingItemOps::clear_by_failure`]. This site has no `UiScript` to fire `ITEM_LOCK_CHANGED`
-/// through, so the transitioned slots queue in [`LockTransitions`] for the container feed
-/// (`ui_items::feed::feed_containers`) to drain and fire next time it runs.
-pub(super) fn inventory_failure(
-    reason: u8,
-    required_level: Option<u32>,
-    item_guid: u64,
-    bag_slot: u8,
-    equip_errors: &mut EquipErrors,
-    pending: &mut PendingItemOps,
-    lock_cleared: &mut LockTransitions,
-    latch: &mut LootLatch,
-) {
-    debug!("net: inventory failure {reason:#04x} (item {item_guid:#x}, bag slot {bag_slot})");
-    equip_errors.0.push(EquipError {
-        reason,
-        required_level,
-        bag_slot,
-    });
-    lock_cleared.0.extend(pending.clear_by_failure(item_guid));
-    // The sixth loot-latch clear (`0x5e3a84`, wow-re `loot-anim-leg.md` §5; decision 1477): when
-    // the packet's **first item guid** is the object we are looting, the session ends here. It is
-    // how an item-container loot (a lockbox) closes when the move out of it fails — the one clear
-    // the 1471 census was missing. Guid-matched, as the bytes are.
-    if item_guid != 0 {
-        latch.clear_for(item_guid);
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
+    use bevy::ecs::system::RunSystemOnce;
+
+    use crate::pending_item_ops::{LockTransitions, PendingItemOps};
+
+    /// An [`ItemUnlock`] over an empty lock set — for the tests whose loot source is no item.
+    macro_rules! no_item {
+        () => {
+            ItemUnlock {
+                pending: &mut PendingItemOps::default(),
+                lock_cleared: &mut LockTransitions::default(),
+            }
+        };
+    }
 
     /// Both fish-verdict keys queue as **yellow** (type-1 / `UI_INFO_MESSAGE`) entries — the
-    /// byte-verified arm, wow-re `fish-msg-handlers.md` — and both resolve to the exact 1.12
+    /// `DisplayError` arm `0x49684b` — and both resolve to the exact 1.12
     /// strings in the shipped `GlobalStrings.lua` (the equip-error test's runtime pattern —
     /// a typo'd key would silently swallow the toast). Skips without client data.
     #[test]
@@ -424,9 +507,9 @@ mod tests {
     }
 
     /// **The refusal table is the reference's, by message id.** Each key must be the catalog row
-    /// whose id the binary's own jump table pushes to `DisplayError` (wow-re
-    /// `loot-slot-record.md` §1: `4→0x82 · 5→0x84 · 6→0x81 · 7→0x83 · 8→0x85 · 9→0x86 ·
-    /// 10→0x19b · 11→0x1bf · 12→0x1cd · 13→0x1ce · 14→0x1cf`, default `0x83`).
+    /// whose id the binary's own jump table pushes to `DisplayError` (`0x5ebc64`: `4→0x82 ·
+    /// 5→0x84 · 6→0x81 · 7→0x83 · 8→0x85 · 9→0x86 · 10→0x19b · 11→0x1bf · 12→0x1cd · 13→0x1ce ·
+    /// 14→0x1cf`, default `0x83`).
     ///
     /// Asserting the **id** rather than the spelling is the point: the key text is only a name for
     /// a number the client pushes, and the catalog is generated from that same table (decision
@@ -541,14 +624,14 @@ mod tests {
         for code in [4u8, 5, 6, 7, 8, 9, 11, 0, 1, 2, 3, 15, 16, 200, 255] {
             let mut errors = UiErrorKeys::default();
             let mut latch = LootLatch(Some(CORPSE));
-            loot_error(CORPSE, code, &mut errors, &mut latch);
+            loot_error(CORPSE, code, &mut errors, &mut latch, no_item!());
             assert_eq!(latch.0, None, "code {code} should release");
             assert_eq!(errors.0.len(), 1, "code {code} shows exactly one line");
         }
         for code in [10u8, 12, 13, 14] {
             let mut errors = UiErrorKeys::default();
             let mut latch = LootLatch(Some(CORPSE));
-            loot_error(CORPSE, code, &mut errors, &mut latch);
+            loot_error(CORPSE, code, &mut errors, &mut latch, no_item!());
             assert_eq!(
                 latch.0,
                 Some(CORPSE),
@@ -557,8 +640,8 @@ mod tests {
         }
     }
 
-    /// The **error leg's** clear stays guid-matched, and the wow-re §5 showed this is not the
-    /// deviation 0515 took it for: it is behaviourally *identical* to the reference.
+    /// The **error leg's** clear stays guid-matched, and this is not the deviation 0515 took it
+    /// for: it is behaviourally *identical* to the reference.
     ///
     /// The tail's own store is unconditional, but the tail cannot be reached on a mismatch.
     /// `0x5eb9f1` has exactly one predecessor image-wide — `0x5eb93e je`, which already required
@@ -575,7 +658,7 @@ mod tests {
     fn the_error_legs_clear_is_guid_matched() {
         let mut errors = UiErrorKeys::default();
         let mut latch = LootLatch(Some(CHEST));
-        loot_error(CORPSE, 8, &mut errors, &mut latch);
+        loot_error(CORPSE, 8, &mut errors, &mut latch, no_item!());
         assert_eq!(latch.0, Some(CHEST));
     }
 
@@ -614,7 +697,7 @@ mod tests {
 
         // The ordinary close path still ends it — the latch is guid-matched, and a chest guid is
         // no different from a corpse one there.
-        loot_release_response(CHEST, &mut loot, &mut latch);
+        loot_release_response(CHEST, &mut loot, &mut latch, no_item!());
         assert_eq!(latch.0, None, "the release ends the session");
     }
 
@@ -669,40 +752,91 @@ mod tests {
         );
     }
 
-    /// The sixth clear (`0x5e3a84`): an inventory-move failure whose first item guid IS the loot
-    /// target ends that session. Guid-matched, so an unrelated bag failure leaves it alone.
-    #[test]
-    fn an_inventory_failure_on_the_looted_object_clears_the_latch() {
-        const LOCKBOX: u64 = 0x4000_0000_0000_0007;
-        let mut errs = EquipErrors::default();
+    /// A lockbox's item guid (HIGHGUID_ITEM is 0x4000 in the high word).
+    const LOCKBOX: u64 = 0x4000_0000_0000_0007;
+
+    /// A World with what the release / error handlers write, and the lockbox's open-item lock
+    /// already armed at bag 0 slot 3 — `ui_items::drain`'s `CMSG_OPEN_ITEM` arm (0916).
+    fn opened_lockbox_world() -> World {
+        let mut world = World::new();
+        world.init_resource::<LootState>();
+        world.insert_resource(LootLatch(Some(LOCKBOX)));
+        world.init_resource::<UiErrorKeys>();
+        world.init_resource::<LockTransitions>();
         let mut pending = PendingItemOps::default();
-        let mut cleared = LockTransitions::default();
-        let mut latch = LootLatch(Some(LOCKBOX));
+        pending.add([(0, 3, LOCKBOX, 1)]);
+        world.insert_resource(pending);
+        world
+    }
 
-        // An unrelated item's failure must not end the session.
-        inventory_failure(
-            2,
-            None,
-            0x1234,
-            0,
-            &mut errs,
-            &mut pending,
-            &mut cleared,
-            &mut latch,
+    /// **The release unlocks an opened lockbox.** `SMSG_LOOT_RELEASE_RESPONSE` → `0x5ec090` →
+    /// `0x48f200(cl=0, dl=0)`, whose `48f299` leg calls `UnlockItem 0x495420` when the loot
+    /// object is an ITEM (`0x48f200` gates the unlock on `dl == 0`). Closing a lockbox's window
+    /// with loot left destroys nothing server-side (vmangos `DoLootRelease` destroys only a fully
+    /// looted item), so no field update ever resolves the lock — the release is the clear.
+    #[test]
+    fn a_release_for_the_opened_item_unlocks_its_slot() {
+        let mut world = opened_lockbox_world();
+        world
+            .run_system_once_with(
+                on_release_response,
+                SessionEvent::LootReleaseResponse { guid: LOCKBOX },
+            )
+            .expect("the handler runs as a one-shot system");
+        assert!(
+            !world.resource::<PendingItemOps>().contains(0, 3),
+            "the lockbox is no longer grey and locked"
         );
-        assert_eq!(latch.0, Some(LOCKBOX));
+        assert_eq!(
+            world.resource::<LockTransitions>().0,
+            vec![(0, 3)],
+            "…and the container feed fires ITEM_LOCK_CHANGED for it"
+        );
+    }
 
-        inventory_failure(
-            2,
-            None,
-            LOCKBOX,
-            0,
-            &mut errs,
-            &mut pending,
-            &mut cleared,
-            &mut latch,
-        );
-        assert_eq!(latch.0, None);
+    /// The control: a release naming some other object (a corpse closing) leaves the lockbox's
+    /// lock exactly where it was.
+    #[test]
+    fn a_release_for_another_guid_leaves_the_lock() {
+        let mut world = opened_lockbox_world();
+        world
+            .run_system_once_with(
+                on_release_response,
+                SessionEvent::LootReleaseResponse { guid: CORPSE },
+            )
+            .expect("the handler runs as a one-shot system");
+        assert!(world.resource::<PendingItemOps>().contains(0, 3));
+        assert!(world.resource::<LockTransitions>().0.is_empty());
+    }
+
+    /// The error leg's release tail `0x5ebac2` calls the same `UnlockItem 0x495420` on the
+    /// packet's guid — on the arms that release, and only those.
+    #[test]
+    fn a_releasing_loot_error_on_the_opened_item_unlocks_it() {
+        let mut world = opened_lockbox_world();
+        // PLAYER_NOT_FOUND (10) does not reach the tail: nothing unlocks.
+        world
+            .run_system_once_with(
+                on_error,
+                SessionEvent::LootError {
+                    guid: LOCKBOX,
+                    error: 10,
+                },
+            )
+            .expect("the handler runs as a one-shot system");
+        assert!(world.resource::<PendingItemOps>().contains(0, 3));
+        // TOO_FAR (4) does.
+        world
+            .run_system_once_with(
+                on_error,
+                SessionEvent::LootError {
+                    guid: LOCKBOX,
+                    error: 4,
+                },
+            )
+            .expect("the handler runs as a one-shot system");
+        assert!(!world.resource::<PendingItemOps>().contains(0, 3));
+        assert_eq!(world.resource::<LockTransitions>().0, vec![(0, 3)]);
     }
 
     const ME: u64 = 0x0000_0000_0000_002A;
diff --git a/crates/benilla-app/src/ui_loot_roll.rs b/crates/benilla-app/src/ui_loot_roll.rs
index 7d6d4f79..4f9d8c5c 100644
--- a/crates/benilla-app/src/ui_loot_roll.rs
+++ b/crates/benilla-app/src/ui_loot_roll.rs
@@ -41,8 +41,7 @@
 //! > A **hit** (non-zero return) calls `0x61b430`, which fires `START_LOOT_ROLL (0x1f9, "%d%d")`.
 //! > A **miss** issues the query and leaves the callback `0x61b460` armed — a trampoline whose
 //! > worker is that same `0x61b430` — so on a cold cache the event fires from the cache *arrival*,
-//! > not from the packet. (wow-re `system/object-layer/scratch/lootroll-chat-and-lifecycle.md` §5
-//! > and `scratch/w2e-decomp.c`'s `FUN_0061b310`/`FUN_0061b430`.)
+//! > not from the packet. (The reference's `FUN_0061b310`/`FUN_0061b430`, decompiled.)
 //!
 //! So `GetLootRollItemInfo`'s cache-miss tail is nearly unreachable in the real client, and was our
 //! common case. There is no repaint to fall back on — the same finding 1805 landed for
@@ -289,10 +288,85 @@ impl LootRolls {
     }
 }
 
+/// The group rolls' packet handlers (decision 0591; in the net handler table since 2319, moved out
+/// of the drain's loot arm file).
+mod net {
+    use benilla_protocol::messages::{LootAllPassed, LootRoll, LootRollWon, LootStartRoll};
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::LootRolls;
+    use crate::net::NetHandlerApp;
+
+    /// Register the roll handlers — called from [`super::UiLootRollPlugin`]. One for the four
+    /// kinds, plus the session-end listener.
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::LootStartRoll, on_packet)
+            .net_handler(K::LootRoll, on_packet)
+            .net_handler(K::LootRollWon, on_packet)
+            .net_handler(K::LootAllPassed, on_packet)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    fn on_packet(In(ev): In<SessionEvent>, mut rolls: ResMut<LootRolls>) {
+        match ev {
+            SessionEvent::LootStartRoll(p) => loot_start_roll(p, &mut rolls),
+            SessionEvent::LootRoll(p) => loot_roll(p, &mut rolls),
+            SessionEvent::LootRollWon(p) => loot_roll_won(p, &mut rolls),
+            SessionEvent::LootAllPassed(p) => loot_all_passed(p, &mut rolls),
+            _ => {}
+        }
+    }
+
+    /// Open group rolls die with the socket (decision 0591). A listener on the session end
+    /// (a second handler on the kind, after the bridge's own teardown).
+    fn on_session_end(In(_): In<SessionEvent>, mut rolls: ResMut<LootRolls>) {
+        rolls.clear();
+    }
+
+    /// A group roll opened on one drop (`SMSG_LOOT_START_ROLL`) — a `GroupLootFrame` goes up with
+    /// Need/Greed/Pass and the countdown bar (decision 0591).
+    fn loot_start_roll(p: LootStartRoll, rolls: &mut LootRolls) {
+        debug!(
+            "net: loot roll opened on item {} ({:#x} slot {}), {} ms",
+            p.item_id, p.looted_target, p.item_slot, p.countdown_ms
+        );
+        rolls.start(p);
+    }
+
+    /// One roller's vote or dice result (`SMSG_LOOT_ROLL`) — the chat announcement line. The
+    /// `(roll_number, roll_type)` pair is overloaded; `LootRoll::is_dice`/`vote` disentangle it.
+    fn loot_roll(p: LootRoll, rolls: &mut LootRolls) {
+        debug!(
+            "net: loot roll announce — roller {:#x} number {} type {}",
+            p.roller, p.roll_number, p.roll_type
+        );
+        rolls.announce(p);
+    }
+
+    /// A group roll resolved (`SMSG_LOOT_ROLL_WON`) — the "won" line, and that roll's frame closes.
+    fn loot_roll_won(p: LootRollWon, rolls: &mut LootRolls) {
+        debug!(
+            "net: loot roll won by {:#x} with {} (type {})",
+            p.winner, p.roll_number, p.roll_type
+        );
+        rolls.won(p);
+    }
+
+    /// Everyone passed (`SMSG_LOOT_ALL_PASSED`) — the frame closes and the item returns to the corpse
+    /// as an ordinary lootable row.
+    fn loot_all_passed(p: LootAllPassed, rolls: &mut LootRolls) {
+        debug!("net: loot roll — everyone passed on item {}", p.item_id);
+        rolls.all_passed(p);
+    }
+}
+
 pub(crate) struct UiLootRollPlugin;
 
 impl Plugin for UiLootRollPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<LootRolls>().add_systems(
             Update,
             (
@@ -329,8 +403,8 @@ impl Plugin for UiLootRollPlugin {
 ///
 /// **The `NO_SPAM` variants are the `showLootSpam == 0` branch**, and since decision 1589 (B246's
 /// Chat options page) that CVar has a row, so `detailed` is a real argument rather than a constant
-/// `true`. 0594 §3 recorded the whole gated flow waiting for exactly this; wow-re's
-/// `lootroll-chat-and-lifecycle.md` §4 is the byte census behind it:
+/// `true`. 0594 §3 recorded the whole gated flow waiting for exactly this; a byte census of the
+/// CVar `0xb4e2bc` is behind it:
 ///
 /// | `showLootSpam` | the per-vote / per-dice line (`0x61c0b0`) | the WON line (`0x61b9e0`) |
 /// |---|---|---|
@@ -895,8 +969,8 @@ mod tests {
         );
     }
 
-    /// `showLootSpam == 0` — the whole gated flow 0594 §3 recorded and 1589 finally wired, all
-    /// three of its claims in one place (wow-re `lootroll-chat-and-lifecycle.md` §4).
+    /// `showLootSpam == 0` (the CVar `0xb4e2bc`) — the whole gated flow 0594 §3 recorded and
+    /// 1589 finally wired, all three of its claims in one place.
     #[test]
     fn detail_off_suppresses_the_roll_lines_and_reshapes_the_winner() {
         // 1 · every vote and every dice line is dropped outright.
diff --git a/crates/benilla-app/src/ui_macro/mod.rs b/crates/benilla-app/src/ui_macro/mod.rs
index 43fa68c6..c73f417b 100644
--- a/crates/benilla-app/src/ui_macro/mod.rs
+++ b/crates/benilla-app/src/ui_macro/mod.rs
@@ -41,8 +41,8 @@ pub(crate) struct MacroFiles {
     identity: crate::ui_script::VmMemo<Option<(String, String)>>,
 }
 
-/// Macro index → its bound spell — benilla's `[rec+0x564]` (wow-re `action-spell-icon-apis.md`
-/// §2), the field an action-bar MACRO slot's whole dynamic state reads through, in the
+/// Macro index → its bound spell — benilla's `[rec+0x564]` (read by the MACRO arm `0x4e5ba0`),
+/// the field an action-bar MACRO slot's whole dynamic state reads through, in the
 /// reference's own three values ([`BoundSpell`]). Stored, not derived at read time, for the
 /// reference's own reason: it is a **field on the macro record**, recomputed when the macro (or
 /// the book) changes, so the three per-frame action-bar systems pay a hash lookup instead of a
@@ -251,8 +251,7 @@ fn rebind_macro_spells(
 
 /// The engine event a macro line is delivered as — `0x188` in the reference's runtime event
 /// registry, resolved to its name inside the binary (`0xbe1198 + 4*0x188` is written exactly once,
-/// at `0x51b4ff`, with `0x852470` = these bytes). wow-re `system/ui/scratch/macro-execution-law.md`
-/// §4, VERIFIED.
+/// at `0x51b4ff`, with `0x852470` = these bytes).
 const EXECUTE_CHAT_LINE: &str = "EXECUTE_CHAT_LINE";
 
 /// Run a macro by its 1-based index — the action bar's MACRO arm (`crate::ui_action::drain`) and
diff --git a/crates/benilla-app/src/ui_macro/run.rs b/crates/benilla-app/src/ui_macro/run.rs
index 42fb5672..b3536957 100644
--- a/crates/benilla-app/src/ui_macro/run.rs
+++ b/crates/benilla-app/src/ui_macro/run.rs
@@ -4,7 +4,7 @@
 //! ## Running: each line is fired as `EXECUTE_CHAT_LINE` (VERIFIED, 0996)
 //!
 //! 0983 shipped this as "push the line onto the chat-input queue", with the engine's route to Lua
-//! recorded as an open question. The wow-re §5 settled it, and the answer is better than the guess:
+//! recorded as an open question. The reference settles it, and the answer is better than the guess:
 //! the runner `0x4f14e0` fires **`FrameScript_SignalEvent(EXECUTE_CHAT_LINE, "%s", line)`** per
 //! non-empty line and does nothing else. It names no Lua function and holds no command table — which
 //! is precisely why a scan of `WoW.exe` finds no FrameXML function name but `GetText`, no
@@ -18,7 +18,7 @@
 //! reference's real one — ChatFrame1's registration is the *only* one in the default UI, so a macro
 //! line runs through that frame's box whichever chat frame has focus.
 //!
-//! The chat type of a plain line is decided nowhere in the engine (§6): the runner has no
+//! The chat type of a plain line is decided nowhere in the engine: the runner has no
 //! `SendChatMessage` call and no type constant. It is `ChatEdit_SendText`'s
 //! `editBox.chatType`, which the reference's trailing `ChatEdit_OnEscapePressed` resets to
 //! `stickyType` — benilla's drain sends as the box's current type, the same observable.
@@ -26,15 +26,15 @@
 //! ## The bound spell (`[rec+0x564]`, VERIFIED)
 //!
 //! A macro action-bar slot shows **the macro's own icon** but reports the **cooldown, usability,
-//! range and checked state of the spell it casts** — byte-verified: `0x4e5a50`'s macro arm
-//! resolves the macro record through `0x4f0f40` and returns `[rec+0x564]` as the slot's spell id
-//! (wow-re `action-spell-icon-apis.md` §2), and every `Is*Action`/`GetActionCooldown` binding reads
-//! through that resolver. [`bound_spell`] is how that field is filled: the body's first `/cast`
-//! line, or a `CastSpellByName("…")` call in a `/script` line.
+//! range and checked state of the spell it casts** — `0x4e5a50`'s macro arm resolves the macro
+//! record through `0x4f0f40` and returns `[rec+0x564]` as the slot's spell id, and every
+//! `Is*Action`/`GetActionCooldown` binding reads through that resolver. [`bound_spell`] is how
+//! that field is filled: the body's first `/cast` line, or a `CastSpellByName("…")` call in a
+//! `/script` line.
 //!
 //! 0983 called this derivation INFERRED (it was reasoned from the two string literals in the
-//! reference's `UIMacros.cpp` block). The wow-re §5 **read `0x4efe00` at the bytes and promoted it
-//! to VERIFIED**, with three refinements now implemented here:
+//! reference's `UIMacros.cpp` block). **`0x4efe00` confirms it at the bytes**, with three
+//! refinements now implemented here:
 //!
 //! - **Arm A** builds `"SLASH_CAST%d"` for n = 1, 2, … and reads each as a **Lua global's value**
 //!   (`FrameScript_GetText 0x703bf0`), stopping at the first nil/empty — never a hardcoded
@@ -79,8 +79,8 @@ use crate::ui_chat::commands::{Command, SlashCommands, SlashIndex};
 const CAST_BY_NAME_CALL: &str = "CastSpellByName(";
 
 /// Which of `0x4efe00`'s two arms matched the cast line — load-bearing because the two store
-/// different values for a name that does not resolve (wow-re `macro-execution-law.md` §7: arm A
-/// writes `-1` at `0x4eff48`, arm B stores the resolver's `0` verbatim at `0x4eff81`).
+/// different values for a name that does not resolve (arm A writes `-1` at `0x4eff48`, arm B
+/// stores the resolver's `0` verbatim at `0x4eff81`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum CastArm {
     /// A `/cast`-alias line (`SLASH_CAST%d`, read as Lua globals).
@@ -90,8 +90,8 @@ pub(crate) enum CastArm {
 }
 
 /// The reference's `[rec+0x564]` — a macro record's cached bound spell — as the three values it
-/// actually takes (wow-re `macro-execution-law.md` §7, VERIFIED; the usable consequence is
-/// decision 1636). The action bar reads this through `ui_action::state`'s slot resolve.
+/// actually takes (written by `0x4efe00`; the usable consequence is decision 1636). The action
+/// bar reads this through `ui_action::state`'s slot resolve.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub(crate) enum BoundSpell {
     /// `0` — no line matched either arm, or a `CastSpellByName(` name that did not resolve. The
@@ -107,8 +107,8 @@ pub(crate) enum BoundSpell {
 
 /// A macro body's runnable lines. The reference's tokenizer (`0x64ae50`) takes `"\r\n"` as a
 /// **delimiter SET** — either character splits — and skips empty tokens, which is why an interior
-/// blank line never even produces one (wow-re `macro-execution-law.md` §3/§6). So do we; a
-/// `macros-cache.txt` hand-copied off a Windows install is a real input, and so is a lone `\r`.
+/// blank line never even produces one. So do we; a `macros-cache.txt` hand-copied off a Windows
+/// install is a real input, and so is a lone `\r`.
 ///
 /// One friendly divergence: we **trim** each line. The reference hands the line over verbatim, so
 /// its `" /say hi"` is not a slash command and its `"/cast  Fireball"` (two spaces) binds a name
@@ -242,9 +242,8 @@ mod tests {
     }
 
     /// The separator after the alias is a **literal space** — the reference compares that one byte
-    /// against `0x20` (`0x4efe96`), so a tab is not a match and the line is simply not a cast line
-    /// (wow-re `macro-execution-law.md` §7). The alias itself folds case, which is the same
-    /// `_strnicmp` the ref uses.
+    /// against `0x20` (`0x4efe96`), so a tab is not a match and the line is simply not a cast line.
+    /// The alias itself folds case, which is the same `_strnicmp` the ref uses.
     #[test]
     fn the_alias_separator_is_a_literal_space_and_the_alias_folds_case() {
         let t = table();
@@ -321,7 +320,7 @@ mod tests {
         );
     }
 
-    /// The miss is arm-dependent, as the reference stores it (`macro-execution-law.md` §7 +
+    /// The miss is arm-dependent, as the reference stores it (`0x4eff48`/`0x4eff81` +
     /// decision 1636): a `/cast` of a spell this character does not know is the `-1` the bar
     /// greys; a body with no cast line, or a `CastSpellByName(` of an unknown name, is the `0`
     /// the bar draws full-colour with no spell state.
diff --git a/crates/benilla-app/src/ui_macro/tests.rs b/crates/benilla-app/src/ui_macro/tests.rs
index b9683689..c64be20b 100644
--- a/crates/benilla-app/src/ui_macro/tests.rs
+++ b/crates/benilla-app/src/ui_macro/tests.rs
@@ -94,13 +94,14 @@ fn ui() -> UiScript {
 }
 
 /// The runner delivers every body line through the reference's own door — one
-/// `EXECUTE_CHAT_LINE` event per non-empty line, in order (0996, wow-re `macro-execution-law.md`
-/// §4) — and the reference's own `ChatFrame_OnEvent` arm does the rest: `SetText(arg1)`,
+/// `EXECUTE_CHAT_LINE` event per non-empty line, in order (0996, `0x4f14e0`) — and the
+/// reference's own `ChatFrame_OnEvent` arm does the rest: `SetText(arg1)`,
 /// `ChatEdit_SendText`, `ChatEdit_OnEscapePressed` (ChatFrame.lua l.1343-1347). So a macro line
 /// lands wherever a typed line lands — a chat type in the send queue, an emote in the emote
 /// queue, a roll in the roll queue — without the runner knowing any of them.
 #[test]
 fn running_a_macro_runs_its_lines_through_the_references_edit_box() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui();
     s.set_macros(MacroState {
         account: vec![macro_view("Greet", "/wave\n\n  /say pew  \n/roll 1 100")],
@@ -142,6 +143,7 @@ fn running_a_macro_runs_its_lines_through_the_references_edit_box() {
 /// case anywhere in the runner.
 #[test]
 fn a_character_macro_runs_by_its_own_index() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui();
     s.set_macros(MacroState {
         account: Vec::new(),
@@ -202,6 +204,7 @@ fn the_generation_moves_on_every_write_and_is_not_drained() {
 /// UI's use of it.
 #[test]
 fn a_registered_frame_sees_every_macro_line_as_an_event() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui();
     s.run(
         r#"MacroSpy = CreateFrame("Frame")
@@ -239,10 +242,11 @@ fn a_registered_frame_sees_every_macro_line_as_an_event() {
 }
 
 /// The reference's tokenizer takes `"\r\n"` as a delimiter SET — either character splits a line
-/// (wow-re `macro-execution-law.md` §3). A body carrying lone `\r`s (an old-Mac hand edit, or a
-/// file round-tripped through one) is therefore three lines, not one long one.
+/// (`0x64ae50`). A body carrying lone `\r`s (an old-Mac hand edit, or a file round-tripped through
+/// one) is therefore three lines, not one long one.
 #[test]
 fn either_line_ending_splits_a_body() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui();
     s.set_macros(MacroState {
         account: vec![macro_view("Mixed", "/say Charge\r/say a\r\n/say b")],
@@ -283,8 +287,8 @@ fn either_line_ending_splits_a_body() {
 fn every_macro_chooser_icon_resolves_in_the_client_archives() {
     /// Icons on a stock 5875 install: `patch.MPQ` 77 + `interface.MPQ` 443 = 520 raw names under
     /// `Interface\Icons\` matching `Spell_`/`Ability_`, less 3 that differ only by case or
-    /// extension — independently counted off the binary's own enumeration by the wow-re note
-    /// `system/ui/scratch/macro-icon-chooser.md`. The DBC scan this replaced served 521, a
+    /// extension — independently counted off the binary's own enumeration
+    /// (`BuildMacroIconList 0x4f0090`). The DBC scan this replaced served 521, a
     /// different set: it included five names with no file and missed art the archive has.
     const CHOOSER_ICONS_5875: usize = 517;
 
diff --git a/crates/benilla-app/src/ui_mail/invoice.rs b/crates/benilla-app/src/ui_mail/invoice.rs
index 8b961c1e..99ddd453 100644
--- a/crates/benilla-app/src/ui_mail/invoice.rs
+++ b/crates/benilla-app/src/ui_mail/invoice.rs
@@ -3,9 +3,8 @@
 //!
 //! **The invoice is TEXT.** Nothing structured rides the wire: the auction house writes its numbers
 //! into the mail's *subject* and *body* as colon-separated fields, and the client parses them back
-//! out. That is not an emulator shortcut — it is what the real 1.12 client does, byte-verified
-//! (wow-re `system/ui/scratch/auction-house.md` §11.1a: `0x4ace70` for the subject,
-//! `GetInboxInvoiceInfo 0x4af360` for the body).
+//! out. That is not an emulator shortcut — it is what the real 1.12 client does (`0x4ace70` for
+//! the subject, `GetInboxInvoiceInfo 0x4af360` for the body).
 //!
 //! Two halves, and they answer different questions from different places:
 //!
diff --git a/crates/benilla-app/src/ui_mail/mod.rs b/crates/benilla-app/src/ui_mail/mod.rs
index 45168c83..a3f52925 100644
--- a/crates/benilla-app/src/ui_mail/mod.rs
+++ b/crates/benilla-app/src/ui_mail/mod.rs
@@ -3,13 +3,13 @@
 //!
 //! The mailbox window is entirely client-side (there is no `SMSG_SHOW_MAILBOX` on 5875): a
 //! right-click on a MAILBOX GameObject ([`crate::target`]) opens the session here — it stores the
-//! mailbox guid and requests the window's show; it sends **no** packet (the wow-re §5 confirms the
-//! MAILBOX use handler overrides the shared use-sender to a local open — never `CMSG_GAMEOBJ_USE`).
+//! mailbox guid and requests the window's show; it sends **no** packet (the MAILBOX use handler
+//! `0x5f6820` overrides the shared use-sender to a local open — never `CMSG_GAMEOBJ_USE`).
 //! The window's own `MAIL_SHOW` handler then calls `CheckInbox()`, whose intent this module drains
 //! into the first `CMSG_GET_MAIL_LIST` — one request, Lua-driven, exactly the reference flow
 //! (MailFrame.lua l.42).
 //!
-//! The net bridge ([`crate::net::apply::mail`]) fills [`MailOpen`] from the wire
+//! The mailbox's packet handlers ([`net`]) fill [`MailOpen`] from the wire
 //! (`SMSG_MAIL_LIST_RESULT` → the inbox rows; `SMSG_ITEM_TEXT_QUERY_RESPONSE` → the body cache;
 //! `SMSG_SEND_MAIL_RESULT` → the send/take result queues). Each frame [`feed_mail`] resolves each
 //! wire [`MailListEntry`] to a Lua-facing [`MailInboxRow`] (sender via the ask-once name cache, item
@@ -19,16 +19,16 @@
 //! `MAIL_SHOW` on open, `MAIL_INBOX_UPDATE` on a list/body change, `MAIL_CLOSED` on clear, and the
 //! send-result trio (see [`feed_mail`]). [`drain_mail`] pulls the Lua intents back out into the mail
 //! `CMSG`s. The standardized NPC-session range guard ([`crate::ui_session`]) client-side-closes the
-//! window when the player leaves the mailbox's interaction range (wow-re §5: the client's generic
-//! interaction-target range gate — past it every mail `CMSG` silently fails its `CheckMailBox`).
+//! window when the player leaves the mailbox's interaction range (the client's generic
+//! interaction-target range gate `0x493230` — past it every mail `CMSG` silently fails its
+//! `CheckMailBox`, `MailHandler.cpp:65`).
 //!
-//! **The arrival layer ([`MailPending`], decisions 0544 P3 / 0904 / 0913, wow-re
-//! `ui/scratch/mail-pending-countdown.md`).** `HasNewMail()` mirrors the real client's own model: a
-//! countdown float (`0x845eac`) read as **`|countdown| < ε`** — *near zero*, not `<= 0` (the sign
-//! matters, decision 0904: vmangos's "no mail" reply is `-86400.0`, which a `<= 0` predicate reads
-//! as "you have mail" at every login). vmangos only ever sends `0.0` ("waiting now") or `-86400.0`
-//! ("none") — never a positive value — but the countdown is implemented in full since that's the
-//! client's real model, not a two-value special case.
+//! **The arrival layer ([`MailPending`], decisions 0544 P3 / 0904 / 0913).** `HasNewMail()` mirrors
+//! the real client's own model: a countdown float (`0x845eac`) read as **`|countdown| < ε`** —
+//! *near zero*, not `<= 0` (the sign matters, decision 0904: vmangos's "no mail" reply is
+//! `-86400.0`, which a `<= 0` predicate reads as "you have mail" at every login). vmangos only ever
+//! sends `0.0` ("waiting now") or `-86400.0` ("none") — never a positive value — but the countdown
+//! is implemented in full since that's the client's real model, not a two-value special case.
 //!
 //! **The icon's whole life is that float**, because `MiniMapMailFrame` is the *only* listener of
 //! `UPDATE_PENDING_MAIL` in all of 1.12 FrameXML and its handler is a bare idempotent
@@ -53,11 +53,14 @@ use benilla_ui::script::{MailInboxRow, MailState, ScriptValue, StationeryView, U
 use crate::entities::ItemDisplays;
 use crate::items::Items;
 use crate::names::NameCache;
-use crate::net::{ClientCommand, EnteredWorldMessage, NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{
+    ClientCommand, EnteredWorldMessage, NetCommands, ObjectStore, Objects, SelfPlayer,
+};
 use crate::query_cache::QueryCache;
 use crate::ui_script::{UiFeed, UiInput};
 use crate::ui_session::{close_npc_session_out_of_range, NpcSession};
 
+mod net;
 mod pending;
 
 pub(crate) use pending::MailPending;
@@ -71,8 +74,8 @@ const CHECKED_COPIED: u32 = 0x4;
 /// l.108: a GM row shows its stationery icon even when it carries a package).
 const STATIONERY_GM: u32 = 61;
 
-/// The `CheckInbox` → `CMSG_GET_MAIL_LIST` client-side rate limit, in seconds (wow-re §5
-/// `ui/scratch/mail-interaction.md`: the real client drops repeat inbox queries inside this window).
+/// The `CheckInbox` → `CMSG_GET_MAIL_LIST` client-side rate limit, in seconds (`0x4aeab0`: the
+/// real client drops repeat inbox queries inside this window).
 const CHECK_INBOX_THROTTLE_SECS: f64 = 60.0;
 
 /// The letter-row icon by kind (the wire carries only a stationery id; the reference derives the
@@ -92,15 +95,15 @@ pub(crate) struct Stationery(pub(crate) benilla_formats::StationeryCatalog);
 /// One `SMSG_SEND_MAIL_RESULT` for `action == SEND`, queued by the net bridge for [`feed_mail`] to
 /// fire (the feed owns the `UiScript`, the apply site doesn't). `MAIL_FAILED` fires on **every**
 /// SEND result — success included — because the real client overloads it as "send resolved, unblock
-/// the UI" (wow-re §5, byte-verified; MailFrame.lua's `MAIL_FAILED` handler only re-enables the
-/// button). `MAIL_SEND_SUCCESS` fires additionally when `error == OK`.
+/// the UI" (`0x4ad15f`; MailFrame.lua's `MAIL_FAILED` handler only re-enables the button).
+/// `MAIL_SEND_SUCCESS` fires additionally when `error == OK`.
 pub(crate) struct MailSendAck {
     pub(crate) ok: bool,
     /// The message key for a non-OK, non-equip send failure (else `None`).
     pub(crate) refusal: Option<&'static str>,
 }
 
-/// The open mailbox, filled by the net bridge ([`crate::net::apply::mail`]) and read by
+/// The open mailbox, filled by the packet handlers ([`net`]) and read by
 /// [`feed_mail`]. Holds the mailbox guid and the inbox rows exactly as the wire delivered them
 /// (`SMSG_MAIL_LIST_RESULT`), the ask-once letter-body cache, and the send-result queues; the feed
 /// resolves each row to a display row and the drain maps a clicked 1-based row to its wire mail id.
@@ -114,14 +117,14 @@ pub(crate) struct MailOpen {
     /// Ask-once letter-body cache: `item_text_id` → body text, through [`QueryCache`] (2288).
     pub(crate) bodies: QueryCache<u32, String>,
     /// Fire `MAIL_SHOW` next feed — set on every mailbox click (the reference opens the window per
-    /// use; wow-re §5). Consumed by [`feed_mail`].
+    /// use, `0x4acd10`). Consumed by [`feed_mail`].
     show_requested: bool,
     /// Session-scoped throttle: the `Time::elapsed_secs_f64` of the last `CMSG_GET_MAIL_LIST`, or
     /// `None` when never queried this session (a fresh open queries immediately).
     last_list_query: Option<f64>,
     /// SEND-action results the net bridge queued for the feed to fire ([`MailSendAck`]).
     pub(crate) send_acks: Vec<MailSendAck>,
-    /// 1-based inbox rows a take just emptied and purged (`net::apply::mail`) — the feed fires
+    /// 1-based inbox rows a take just emptied and purged ([`net`]) — the feed fires
     /// `CLOSE_INBOX_ITEM(index)` for each, ahead of the `MAIL_INBOX_UPDATE` the purge causes.
     pub(crate) close_inbox: Vec<u32>,
     /// Refusals (a take/return/delete failure) the feed shows, as message keys — resolved at the
@@ -189,8 +192,9 @@ impl MailOpen {
 
 /// The mailbox window is an NPC-less interaction session: the standardized range guard
 /// ([`crate::ui_session`]) client-side-closes it — the exact `CloseMail` clear — when the player
-/// leaves the mailbox's interaction range (wow-re §5: the client's generic interaction-target range
-/// gate, the same one the mail `CMSG`s' server-side `CheckMailBox` enforces at 5 yd).
+/// leaves the mailbox's interaction range (the client's generic interaction-target range gate
+/// `0x493230`, the same one the mail `CMSG`s' server-side `CheckMailBox` (`MailHandler.cpp:65`)
+/// enforces at 5 yd).
 impl NpcSession for MailOpen {
     fn npc(&self) -> Option<u64> {
         self.mailbox
@@ -206,6 +210,7 @@ pub(crate) struct UiMailPlugin;
 impl Plugin for UiMailPlugin {
     fn build(&self, app: &mut App) {
         crate::query_cache::register::<MailOpen>(app);
+        net::register(app);
         app.init_resource::<MailOpen>()
             .init_resource::<MailPending>()
             .add_systems(
@@ -309,7 +314,7 @@ fn resolve_row(
     // carries attachments (item or money) from a not-yet-returned player sender — that is the
     // server's own expiry behavior (vmangos `ReturnOrDeleteOldMails`). Everything else — plain
     // letters, system mail, already-returned mail — deletes. The exact client predicate behind
-    // `InboxItemCanDelete` is un-RE'd; this mirrors the observable law.
+    // `InboxItemCanDelete` is not read from the reference; this mirrors the observable law.
     let can_delete =
         returned || entry.sender_guid.is_none() || (entry.item.is_none() && entry.money == 0);
 
@@ -352,7 +357,7 @@ fn resolve_row(
         .then(|| bodies.get(entry.item_text_id))
         .flatten();
 
-    // ── The auction house's mail (`ui_mail::invoice`, wow-re §11.1a) ─────────────────────────
+    // ── The auction house's mail (`ui_mail::invoice`, `0x4ace70`/`0x4af360`) ─────────────────
     // Two independent resolves off one subject: the DISPLAYED subject, which every auction notice
     // gets, and the INVOICE, which only a won/sold notice can answer and only once its body has
     // been fetched.
@@ -439,7 +444,7 @@ fn resolve_row(
 }
 
 /// Build the Lua-facing snapshot from [`MailOpen`] — `None` when no mailbox is open.
-/// The usable stationery list (wow-re `stationery-bindings.md` §`0x4ad970`, 1970): every
+/// The usable stationery list (`0x4ad970`, 1970): every
 /// `Stationery.dbc` row that is always available (`Flags & 1`) or whose item the player carries
 /// (bags, not the bank — the client's `0x622270`), and whose item template is cached — the name,
 /// icon and price come off the template — sorted by BuyPrice ascending, the client's comparator
@@ -448,6 +453,7 @@ fn resolve_row(
 fn stationeries(
     catalog: &Stationery,
     self_q: &Query<(&ObjectStore, &crate::net::Guid), With<SelfPlayer>>,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     commands: &NetCommands,
@@ -461,7 +467,7 @@ fn stationeries(
         let carried = store.is_some_and(|s| {
             crate::ui_items::count_of(
                 &s.0,
-                items,
+                objects,
                 row.item,
                 crate::ui_items::InventoryScope::CARRIED,
             ) > 0
@@ -535,6 +541,7 @@ struct MailFeedExtras<'w, 's> {
 fn feed_mail(
     script: Option<NonSendMut<UiScript>>,
     mut mail: ResMut<MailOpen>,
+    objects: Objects,
     items: Res<Items>,
     icons: Option<Res<ItemDisplays>>,
     stationery: Option<Res<Stationery>>,
@@ -574,20 +581,20 @@ fn feed_mail(
         .filter_map(|key| crate::ui_action::keyed_line(&script, key))
         .collect();
     crate::ui_action::show_messages(&mut script, &mut sink, "ui_mail", refusals);
-    // SEND acks: MAIL_FAILED on EVERY send result (unblocks the button — wow-re §5), plus
+    // SEND acks: MAIL_FAILED on EVERY send result (unblocks the button — `0x4ad15f`), plus
     // MAIL_SEND_SUCCESS on OK (resets the form) or the refusal's own line on a failure. The
     // success also SAYS so — `ERR_MAIL_SENT`, the yellow info line `0x4ad0b1` shows before it
     // resets the form (decision 1821).
     // A take emptied and purged a row: `CLOSE_INBOX_ITEM(index)` — the stock handler hides the
     // open letter when it is that row — ahead of the `MAIL_INBOX_UPDATE` the changed list fires
-    // below, the client's own order (wow-re `stationery-bindings.md` §8, 1970).
+    // below, the client's own order (`0x4ad772` before `0x4ad7a3`, 1970).
     for index in std::mem::take(&mut mail.close_inbox) {
         script.fire_event("CLOSE_INBOX_ITEM", vec![ScriptValue::Int(i64::from(index))]);
     }
-    // `SMSG_SEND_MAIL_RESULT 0x4ad050`, in its own order (wow-re `mail-interaction.md` §4): the
-    // GlobalString toast, then — on `action 0 / reason 0` only — the compose-tab reset `0x4acdc0(1)`
-    // with its three events, and **last, on every path, `MAIL_FAILED`** (`0x4ad15f`, unconditional:
-    // a successful send fires it too, as the generic "the send resolved, unblock the form" signal).
+    // `SMSG_SEND_MAIL_RESULT 0x4ad050`, in its own order: the GlobalString toast, then — on
+    // `action 0 / reason 0` only — the compose-tab reset `0x4acdc0(1)` with its three events, and
+    // **last, on every path, `MAIL_FAILED`** (`0x4ad15f`, unconditional: a successful send fires it
+    // too, as the generic "the send resolved, unblock the form" signal).
     for ack in std::mem::take(&mut mail.send_acks) {
         let key = if ack.ok {
             Some(MAIL_SENT_KEY)
@@ -649,7 +656,16 @@ fn feed_mail(
     let usable = stationery
         .as_deref()
         .filter(|_| !self_q.is_empty())
-        .map(|catalog| stationeries(catalog, &self_q, &items, icons.as_deref(), &commands))
+        .map(|catalog| {
+            stationeries(
+                catalog,
+                &self_q,
+                &objects,
+                &items,
+                icons.as_deref(),
+                &commands,
+            )
+        })
         .unwrap_or_default();
     let memo = last_stationeries.get(&script);
     if *memo != usable {
@@ -660,7 +676,7 @@ fn feed_mail(
         // The selection is cleared on open AND close (`0x4ace07`, 1970); the stock tab's reset
         // on MAIL_SHOW re-selects row 1.
         script.clear_stationery();
-        // The open core's own order (wow-re `mail-interaction.md` §1): store the mailbox, register
+        // The open core's own order (`0x4acd10`): store the mailbox, register
         // the interaction target, **reset the compose tab** — a fresh window carries no stale
         // attachment or money — and only THEN `MAIL_SHOW`. The reset's `MAIL_SEND_SUCCESS` is the
         // byte-verified open side-effect, so the page-turn sound on open is faithful, not a bug.
@@ -669,7 +685,7 @@ fn feed_mail(
     } else if closed {
         script.clear_stationery();
         script.fire_event("MAIL_CLOSED", vec![]);
-        // The close core's tail (wow-re `0x4acdad`/`0x4acdb1`, decision 0913): a session where a
+        // The close core's tail (`0x4acdad`/`0x4acdb1`, decision 0913): a session where a
         // mail was read — or one arrived while the window was open — re-asks the server, and the
         // sender stamps the countdown to "no mail" on the way out. This is the whole mechanism by
         // which checking your mail clears the minimap icon; nothing on the inbox path touches it.
@@ -721,7 +737,7 @@ fn drain_mail(
     mut mail: ResMut<MailOpen>,
     commands: Res<NetCommands>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
-    items: Res<Items>,
+    objects: Objects,
     time: Res<Time>,
     mut pending: ResMut<MailPending>,
 ) {
@@ -739,7 +755,7 @@ fn drain_mail(
         return;
     };
 
-    // CheckInbox → a session-scoped, 60s-throttled inbox query (wow-re §5).
+    // CheckInbox → a session-scoped, 60s-throttled inbox query (`0x4aeab0`).
     if script.take_mail_check_inbox() {
         let now = time.elapsed_secs_f64();
         if mail
@@ -751,7 +767,7 @@ fn drain_mail(
         }
     }
 
-    // Opened mails: mark read (once) then ask-once the body (wow-re §5: read FIRST, body second).
+    // Opened mails: mark read (once) then ask-once the body (`0x4af110`: read FIRST, body second).
     for index in script.take_mail_opens() {
         let Some((mail_id, text_id, read)) = index
             .checked_sub(1)
@@ -824,7 +840,7 @@ fn drain_mail(
     if let Some(req) = script.take_mail_send() {
         let item_guid = req.item.and_then(|(bag, slot)| {
             self_q.iter().next().and_then(|s| {
-                crate::ui_items::slot_guid(&s.0, bag, (slot.max(1) - 1) as u8, &items)
+                crate::ui_items::slot_guid(&s.0, bag, (slot.max(1) - 1) as u8, &objects)
             })
         });
         if req.item.is_some() && item_guid.is_none() {
diff --git a/crates/benilla-app/src/net/apply/mail.rs b/crates/benilla-app/src/ui_mail/net.rs
similarity index 58%
rename from crates/benilla-app/src/net/apply/mail.rs
rename to crates/benilla-app/src/ui_mail/net.rs
index 9919c191..d004b658 100644
--- a/crates/benilla-app/src/net/apply/mail.rs
+++ b/crates/benilla-app/src/ui_mail/net.rs
@@ -1,28 +1,111 @@
-//! The mail arc's drain-side arm bodies for [`super::apply_net_updates`]'s dispatch match
-//! (decision 0544 P1/P2). Each `pub(super)` fn here is one `SessionEvent` arm's body, filling the
-//! [`crate::ui_mail::MailOpen`] session the feed reads; the match at the call site stays the
-//! dispatcher. The `UiScript` events these ultimately drive are fired by [`crate::ui_mail::feed_mail`]
-//! (the feed owns the VM), so these arms only mutate resources + send the wire re-syncs.
+//! The mailbox's packet handlers (decision 0544 P1/P2/P3; in the net handler table since 2306) —
+//! the inbox/body/send-result kinds fill the [`MailOpen`] session the feed reads, the arrival
+//! pair feeds [`MailPending`] (`HasNewMail()`/the minimap icon). The `UiScript` events these
+//! ultimately drive are fired by [`super::feed_mail`] (the feed owns the VM), so nothing here
+//! touches it: the handlers only mutate resources + send the wire re-syncs.
 
 use benilla_protocol::messages::{mail_action, mail_error, mail_message_type, MailListEntry};
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
 
-use crate::net::{ClientCommand, NetCommands};
+use super::{mail_refusal, MailOpen, MailPending, MailSendAck};
+use crate::net::{ClientCommand, NetCommands, NetHandlerApp};
 use crate::ui_items::{EquipError, EquipErrors};
-use crate::ui_mail::{mail_refusal, MailOpen, MailPending, MailSendAck};
+
+/// Register the mailbox's handlers — called from [`super::UiMailPlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::MailList, on_mail_list)
+        .net_handler(K::SendMailResult, on_send_mail_result)
+        .net_handler(K::MailItemText, on_mail_item_text)
+        .net_handler(K::ReceivedMail, on_received_mail)
+        .net_handler(K::NextMailTime, on_next_mail_time)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_mail_list(In(ev): In<SessionEvent>, mut mail: ResMut<MailOpen>, commands: Res<NetCommands>) {
+    if let SessionEvent::MailList { mails } = ev {
+        mail_list(mails, &mut mail, &commands);
+    }
+}
+
+fn on_send_mail_result(
+    In(ev): In<SessionEvent>,
+    mut mail: ResMut<MailOpen>,
+    commands: Res<NetCommands>,
+    mut equip_errors: ResMut<EquipErrors>,
+) {
+    if let SessionEvent::SendMailResult {
+        mail_id,
+        action,
+        error,
+        equip_error,
+        item,
+    } = ev
+    {
+        send_mail_result(
+            mail_id,
+            action,
+            error,
+            equip_error,
+            item,
+            &mut mail,
+            &commands,
+            &mut equip_errors,
+        );
+    }
+}
+
+fn on_mail_item_text(In(ev): In<SessionEvent>, mut mail: ResMut<MailOpen>) {
+    if let SessionEvent::MailItemText { text_id, text } = ev {
+        mail_item_text(text_id, text, &mut mail);
+    }
+}
+
+fn on_received_mail(
+    In(ev): In<SessionEvent>,
+    mut pending: ResMut<MailPending>,
+    mail: Res<MailOpen>,
+    commands: Res<NetCommands>,
+) {
+    if let SessionEvent::ReceivedMail { seconds } = ev {
+        received_mail(seconds, &mut pending, &mail, &commands);
+    }
+}
+
+fn on_next_mail_time(In(ev): In<SessionEvent>, mut pending: ResMut<MailPending>) {
+    if let SessionEvent::NextMailTime { seconds } = ev {
+        next_mail_time(seconds, &mut pending);
+    }
+}
+
+/// An open mailbox dies with the socket, and the arrival countdown is login-scoped (decision
+/// 0544 P3): a fresh login re-queries `MSG_QUERY_NEXT_MAIL_TIME` at world-enter, so nothing
+/// carries over across a reconnect. A listener on the session end (a second handler on
+/// `Disconnected`, after the bridge's own teardown, `net::session::on_disconnected`).
+fn on_session_end(
+    In(_): In<SessionEvent>,
+    mut mail: ResMut<MailOpen>,
+    mut pending: ResMut<MailPending>,
+) {
+    mail.clear_session();
+    *pending = MailPending::default();
+}
 
 /// `SessionEvent::MailList` (`SMSG_MAIL_LIST_RESULT`) — replace the session's rows + fire the inbox
 /// repaint (via the feed's diff). The inbox handler auto-purges expired mail: any row whose timer ran
-/// out (`expire_days <= 0`) is deleted server-side (`CMSG_MAIL_DELETE`) and dropped here (wow-re §5,
-/// `ui/scratch/mail-interaction.md`).
+/// out (`expire_days <= 0`) is deleted server-side (`CMSG_MAIL_DELETE`) and dropped here
+/// (`0x4ad1b0`).
 ///
-/// **It does not touch [`crate::ui_mail::MailPending`]** — and that is a positive fact, not an
+/// **It does not touch [`MailPending`]** — and that is a positive fact, not an
 /// omission (decision 0913). This arm used to clear the countdown when the surviving list had
 /// nothing unread, on the inferred grounds that "checking your mail clears the icon" had to be the
-/// list's doing. A full write-xref of the countdown float in wow-re says otherwise: nothing on the
+/// list's doing. A full write-xref of the countdown float `0x845eac` says otherwise: nothing on the
 /// inbox path writes it. The icon clears because **opening a letter arms the deferred-refresh flag
-/// and the mailbox *close* re-asks the server** — modelled in [`crate::ui_mail`], where the close
+/// and the mailbox *close* re-asks the server** — modelled in [`super`], where the close
 /// edge lives.
-pub(super) fn mail_list(mails: Vec<MailListEntry>, mail: &mut MailOpen, commands: &NetCommands) {
+fn mail_list(mails: Vec<MailListEntry>, mail: &mut MailOpen, commands: &NetCommands) {
     let mailbox = mail.mailbox;
     mail.mails = mails
         .into_iter()
@@ -43,11 +126,11 @@ pub(super) fn mail_list(mails: Vec<MailListEntry>, mail: &mut MailOpen, commands
 }
 
 /// `MAIL_CHECK_MASK_COD_PAYMENT` — the `checked` bit (`byte[rec+0x148] & 8`) that marks a mail as
-/// the money a COD taker paid; taking that money empties the mail (wow-re, 1970).
+/// the money a COD taker paid; taking that money empties the mail (`0x4ad6b0`, 1970).
 const CHECKED_COD_PAYMENT: u32 = 8;
 
-/// The two take legs' "this mail is now empty" decision, off the client's own bytes (wow-re
-/// `stationery-bindings.md` §8, 1970): a take that empties the mail sends `CMSG_MAIL_DELETE`
+/// The two take legs' "this mail is now empty" decision, off the client's own bytes
+/// (1970): a take that empties the mail sends `CMSG_MAIL_DELETE`
 /// itself, then `CLOSE_INBOX_ITEM(index)`, then `MAIL_INBOX_UPDATE`. The money leg (`0x4ad6b0`)
 /// purges iff the mail is a COD payment, or an auction notice with no item; the item leg
 /// (`0x4ad7b0`) purges iff the money is gone and the mail is an auction notice or carries no
@@ -55,7 +138,7 @@ const CHECKED_COD_PAYMENT: u32 = 8;
 /// reference too (the stock `OpenMailFrame_OnHide` deletes a copied, emptied letter on close).
 ///
 /// The item leg's second conjunct reads `[rec+0x114] == 0 && [rec+0x25c] == 0`; `+0x114` is the
-/// letter's text id and `+0x25c` a second no-text field the carve did not name (INFERRED to be the
+/// letter's text id and `+0x25c` a second no-text field (inferred to be the
 /// fetched body). This takes the text id alone, which can only purge a mail the client also would
 /// when that second field is zero whenever the first is.
 fn take_empties(entry: &MailListEntry, action: u32) -> bool {
@@ -76,7 +159,7 @@ fn take_empties(entry: &MailListEntry, action: u32) -> bool {
 /// take/return/delete then re-syncs the inbox with a fresh `CMSG_GET_MAIL_LIST` (the reference
 /// client's inbox-refresh moment); an EQUIP_ERROR routes to the existing inventory-error surface;
 /// any other failure surfaces the red error line.
-pub(super) fn send_mail_result(
+fn send_mail_result(
     mail_id: u32,
     action: u32,
     error: u32,
@@ -145,25 +228,20 @@ pub(super) fn send_mail_result(
 
 /// `SessionEvent::MailItemText` (`SMSG_ITEM_TEXT_QUERY_RESPONSE`) — land the letter body in the
 /// ask-once cache + clear its pending flag; the feed repaints (MAIL_INBOX_UPDATE) on the change.
-pub(super) fn mail_item_text(text_id: u32, text: String, mail: &mut MailOpen) {
+fn mail_item_text(text_id: u32, text: String, mail: &mut MailOpen) {
     mail.bodies.insert(text_id, Some(text));
 }
 
 /// `SessionEvent::ReceivedMail` (`SMSG_RECEIVED_MAIL`) — mail just arrived. `seconds` is the wire's
 /// delay float (vmangos always sends `0.0` = "now"); it runs the countdown's set-value ladder,
 /// which takes the **busy** branch when a mailbox window is open — arming the deferred refresh
-/// instead of moving the icon under the player's nose (wow-re `0x4ad620`, decision 0913).
+/// instead of moving the icon under the player's nose (`0x4ad620`, decision 0913).
 ///
 /// The list re-sync is ours, not the reference's, and stays: a server push bypasses `CheckInbox`'s
 /// 60 s client-side throttle (decision 0544 P3), so a mail arriving while you stand at the mailbox
 /// shows up. The reference reaches the same place by its close-time re-query; leaving a mail you
 /// were just told about invisible for up to a minute is the worse client, and this costs one packet.
-pub(super) fn received_mail(
-    seconds: f32,
-    pending: &mut MailPending,
-    mail: &MailOpen,
-    commands: &NetCommands,
-) {
+fn received_mail(seconds: f32, pending: &mut MailPending, mail: &MailOpen, commands: &NetCommands) {
     pending.apply_received_mail(seconds, mail.mailbox.is_some());
     if let Some(mailbox) = mail.mailbox {
         let _ = commands.0.send(ClientCommand::GetMailList { mailbox });
@@ -171,10 +249,47 @@ pub(super) fn received_mail(
 }
 
 /// `SessionEvent::NextMailTime` (`MSG_QUERY_NEXT_MAIL_TIME`'s reply, one `f32`) — store the
-/// server's float verbatim and signal `UPDATE_PENDING_MAIL` **unconditionally** (wow-re `0x4ad5f0`,
+/// server's float verbatim and signal `UPDATE_PENDING_MAIL` **unconditionally** (`0x4ad5f0`,
 /// signal site `0x4ad605`; decision 0913). `0.0` = mail waiting now, negative (vmangos always sends
 /// `-86400.0`) = none, a positive value counts down per frame in `crate::ui_mail`'s `feed_mail` and
 /// flips `HasNewMail()` true as it lands inside ε.
-pub(super) fn next_mail_time(seconds: f32, pending: &mut MailPending) {
+fn next_mail_time(seconds: f32, pending: &mut MailPending) {
     pending.apply_query_reply(seconds);
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// End to end through the real registration: the wire's "mail is waiting" reaches the
+    /// countdown, a mailbox click survives until the session ends, and the session end — the
+    /// bridge's own teardown beside this listener — resets both.
+    #[test]
+    fn the_table_routes_the_arrival_and_the_session_end_to_the_mailbox() {
+        let (tx, _rx) = crossbeam_channel::unbounded();
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins)
+            .init_resource::<MailOpen>()
+            .init_resource::<MailPending>()
+            .init_resource::<EquipErrors>()
+            .insert_resource(NetCommands(tx));
+        register(&mut app);
+
+        app.world_mut().resource_mut::<MailOpen>().click(0x20);
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![SessionEvent::NextMailTime { seconds: 0.0 }],
+        );
+        assert!(app.world().resource::<MailPending>().has_new_mail());
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![SessionEvent::Disconnected {
+                reason: "socket".into(),
+                end: benilla_protocol::SessionEnd::Lost,
+            }],
+        );
+        assert!(!app.world().resource::<MailPending>().has_new_mail());
+        assert_eq!(app.world().resource::<MailOpen>().mailbox, None);
+    }
+}
diff --git a/crates/benilla-app/src/ui_mail/pending.rs b/crates/benilla-app/src/ui_mail/pending.rs
index f7182c21..974ce134 100644
--- a/crates/benilla-app/src/ui_mail/pending.rs
+++ b/crates/benilla-app/src/ui_mail/pending.rs
@@ -7,19 +7,19 @@
 //! purpose — the two only meet at the mailbox close edge, where a read letter turns into the
 //! re-query that clears the icon.
 //!
-//! Every rule here is byte-VERIFIED in wow-re (`ui/scratch/mail-pending-countdown.md`), which is
-//! also where the load-bearing *negative* lives: **nothing on the inbox path writes the countdown**.
+//! Every rule here is the reference's, and so is the load-bearing *negative*: **nothing on the
+//! inbox path writes the countdown** (`0x845eac`).
 
 use bevy::prelude::*;
 
 /// The `HasNewMail()` / countdown-step epsilon — the real client's `[0x8029d4]` = `2^-22`, the
 /// `fabs(x)`-vs-this threshold both `0x4afea0` (`HasNewMail`) and `0x4ade60` (the per-frame step)
-/// compare against (VERIFIED byte-exact in wow-re, `crates/ui/src/glue_geom_4a8.rs::EPS_BITS`).
-const MAIL_TIME_EPSILON: f32 = f32::from_bits(0x3480_0000); // 2^-22, wow-re's `EPS_BITS`
+/// compare against.
+const MAIL_TIME_EPSILON: f32 = f32::from_bits(0x3480_0000); // 2^-22, the reference's `[0x8029d4]`
 
 /// The "no mail waiting" stamp: the literal **`-1.0f`** the mail module's init (`0x4acb87`) and the
 /// `MSG_QUERY_NEXT_MAIL_TIME` **sender** (`0x4ade25`) both write into the countdown,
-/// unconditionally (VERIFIED wow-re, decision 0913). Any value outside ε of zero reads "no mail";
+/// unconditionally (decision 0913). Any value outside ε of zero reads "no mail";
 /// `-1.0` is simply the one the reference picks, and it is what the countdown holds between asking
 /// the server and hearing back.
 const MAIL_TIME_NO_MAIL: f32 = -1.0;
@@ -32,9 +32,7 @@ const MAIL_TIME_NO_MAIL: f32 = -1.0;
 /// and stamped back to [`MAIL_TIME_NO_MAIL`] whenever the client (re-)asks the server. Independent
 /// of [`MailOpen`] (that is session-scoped to one open window; this survives it closing).
 ///
-/// **The five writers**, all VERIFIED at the bytes (wow-re `mail-pending-countdown.md`; the
-/// earlier §4 note listed only three, which is what made the clear-on-inbox-read guess look
-/// plausible — decision 0913): the module init and the query sender stamp `-1.0`
+/// **The five writers** (decision 0913): the module init and the query sender stamp `-1.0`
 /// ([`Self::on_query_sent`]), the query reply stores the server's float
 /// ([`Self::apply_query_reply`]), `SMSG_RECEIVED_MAIL` runs the set-value ladder
 /// ([`Self::apply_received_mail`]), and the per-frame step counts down ([`Self::step`]).
@@ -67,7 +65,7 @@ impl Default for MailPending {
 }
 
 impl MailPending {
-    /// `HasNewMail()` (wow-re `0x4afea0` byte-exact: `fld [0x845eac]; fabs; fcomp [0x8029d4]`,
+    /// `HasNewMail()` (`0x4afea0`: `fld [0x845eac]; fabs; fcomp [0x8029d4]`,
     /// emitted `jp`) — true iff the countdown is **within ε of zero**. Strict `<`, symmetric, and
     /// false at exact equality and for NaN.
     ///
@@ -79,12 +77,11 @@ impl MailPending {
         self.countdown.abs() < MAIL_TIME_EPSILON
     }
 
-    /// The per-frame countdown step (wow-re `0x4ade60` byte-exact — carved as
-    /// `glue_geom_4a8::step_value`): a **non-positive countdown is left alone** (the "no mail"
-    /// stamp must never drift toward zero, and a reached-zero countdown must not sail past it into
-    /// negative — either would flip [`Self::has_new_mail`] the wrong way), and a positive one steps
-    /// down floor-clamped at `0.0`. The subtraction runs the client's x87 chain (f64 under PC_53,
-    /// narrowed at the store). Signals once, on the step that lands inside ε.
+    /// The per-frame countdown step (`0x4ade60`): a **non-positive countdown is left alone**
+    /// (the "no mail" stamp must never drift toward zero, and a reached-zero countdown must not
+    /// sail past it into negative — either would flip [`Self::has_new_mail`] the wrong way), and a
+    /// positive one steps down floor-clamped at `0.0`. The subtraction runs the client's x87 chain
+    /// (f64 under PC_53, narrowed at the store). Signals once, on the step that lands inside ε.
     pub(super) fn step(&mut self, delta_secs: f32) {
         if self.countdown > 0.0 {
             let diff = f64::from(self.countdown) - f64::from(delta_secs); // fsub, then fcom vs 0.0
@@ -95,14 +92,14 @@ impl MailPending {
         }
     }
 
-    /// The `MSG_QUERY_NEXT_MAIL_TIME` **reply** (wow-re `0x4ad5f0`): store the server's float
+    /// The `MSG_QUERY_NEXT_MAIL_TIME` **reply** (`0x4ad5f0`): store the server's float
     /// verbatim and signal — **unconditionally**, whether or not `HasNewMail()` changed.
     pub(crate) fn apply_query_reply(&mut self, seconds: f32) {
         self.countdown = seconds;
         self.notify = true; // 0x4ad605 — unconditional
     }
 
-    /// Sending `MSG_QUERY_NEXT_MAIL_TIME` (wow-re: the sender `0x4ade25` and the module init
+    /// Sending `MSG_QUERY_NEXT_MAIL_TIME` (the sender `0x4ade25` and the module init
     /// `0x4acb87` both stamp `-1.0f`): the countdown reads "no mail" from the moment we ask until
     /// the reply lands. **No signal** — the sender does not fire `UPDATE_PENDING_MAIL`, so the icon
     /// keeps its old face for the round trip and updates when the reply arrives.
@@ -110,7 +107,7 @@ impl MailPending {
         self.countdown = MAIL_TIME_NO_MAIL;
     }
 
-    /// `SMSG_RECEIVED_MAIL` (wow-re `0x4ad620` byte-exact — carved as `glue_geom_4a8::set_value`).
+    /// `SMSG_RECEIVED_MAIL` (`0x4ad620`).
     /// `mailbox_open` is the busy-flag pair `[0xb6ef88]|[0xb6ef8c]`, the open mailbox's guid:
     ///
     /// * **busy** → arm the deferred refresh and leave the countdown alone (the icon does not move
@@ -172,7 +169,7 @@ mod tests {
         assert!(pending_at(0.0).has_new_mail());
         assert!(!pending_at(-86400.0).has_new_mail());
         // The threshold itself: inside ε counts, ε and beyond does not — either sign. Strict `<`,
-        // so exact equality is false (wow-re: the emitted `jp` over the x87 C-bits).
+        // so exact equality is false (the emitted `jp` at `0x4afeb3` over the x87 C-bits).
         assert!(pending_at(MAIL_TIME_EPSILON / 2.0).has_new_mail());
         assert!(pending_at(-MAIL_TIME_EPSILON / 2.0).has_new_mail());
         assert!(!pending_at(MAIL_TIME_EPSILON).has_new_mail());
@@ -225,7 +222,7 @@ mod tests {
     }
 
     /// The query reply stores verbatim and signals **unconditionally** — even when `HasNewMail()`
-    /// did not change (wow-re `0x4ad605`). A transition-only fire would be a silent divergence.
+    /// did not change (`0x4ad605`). A transition-only fire would be a silent divergence.
     #[test]
     fn query_reply_stores_and_always_signals() {
         let mut p = MailPending::default();
@@ -240,7 +237,7 @@ mod tests {
     }
 
     /// Sending the query stamps "no mail" but does **not** signal — so the icon keeps its face for
-    /// the round trip and moves when the reply lands (wow-re: `0x4ade25` stamps, `0x4ad605` fires).
+    /// the round trip and moves when the reply lands (`0x4ade25` stamps, `0x4ad605` fires).
     #[test]
     fn sending_the_query_stamps_without_signalling() {
         let mut p = pending_at(0.0);
diff --git a/crates/benilla-app/src/ui_merchant.rs b/crates/benilla-app/src/ui_merchant/mod.rs
similarity index 97%
rename from crates/benilla-app/src/ui_merchant.rs
rename to crates/benilla-app/src/ui_merchant/mod.rs
index f7e7ea91..5fc76b46 100644
--- a/crates/benilla-app/src/ui_merchant.rs
+++ b/crates/benilla-app/src/ui_merchant/mod.rs
@@ -28,7 +28,7 @@ use benilla_ui::script::{ItemStatsHead, MerchantItem, MerchantState, ScriptValue
 use crate::entities::ItemDisplays;
 use crate::items::Items;
 use crate::names::NameCache;
-use crate::net::{ClientCommand, Guid, NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{ClientCommand, Guid, NetCommands, ObjectStore, Objects, SelfPlayer};
 use crate::ui_items::{item_link, slot_guid, wire_pos};
 use crate::ui_script::{UiFeed, UiInput};
 use crate::ui_session::{close_npc_session_out_of_range, npc_switched, NpcSession};
@@ -38,8 +38,8 @@ use benilla_protocol::messages::BAG_PLAYER_INVENTORY;
 /// `ItemHandler.cpp`); the Lua side sees it as `numAvailable == -1`.
 const STOCK_UNLIMITED: u32 = 0xFFFF_FFFF;
 
-/// `UNIT_NPC_FLAG_REPAIR` — the vendor-can-repair service bit `CanMerchantRepair` tests (wow-re
-/// repair-machinery.md `0x4fadb0`: a merchant-frame gate, deliberately never in the cursor ladder).
+/// `UNIT_NPC_FLAG_REPAIR` — the vendor-can-repair service bit `CanMerchantRepair` tests
+/// (`0x4fadb0`: a merchant-frame gate, deliberately never in the cursor ladder).
 const NPC_FLAG_REPAIR: u32 = 0x4000;
 
 /// The wire's first absolute buyback inventory slot (`BUYBACK_SLOT_START`; slots 69–80).
@@ -127,10 +127,13 @@ pub(crate) enum MerchantRefusal {
     Sell(u8),
 }
 
+mod net;
+
 pub(crate) struct UiMerchantPlugin;
 
 impl Plugin for UiMerchantPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<MerchantOpen>()
             .init_resource::<MerchantErrors>()
             .add_systems(
@@ -168,7 +171,7 @@ fn buy_error_key(reason: u8) -> Option<&'static str> {
     Some(match reason {
         // One arm (`0x5dcdee`) for both: vmangos calls 1 ALREADY_SOLD and 7 SOLD_OUT, and the
         // reference tells them apart only by code 1 also zeroing the row
-        // ([`crate::net::apply::npc::vendor_buy_failed`]).
+        // ([`crate::ui_merchant::net::vendor_buy_failed`]).
         buy_result::ITEM_ALREADY_SOLD | buy_result::ITEM_SOLD_OUT => "ERR_VENDOR_SOLD_OUT", // 0x23
         buy_result::NOT_ENOUGH_MONEY => "ERR_NOT_ENOUGH_MONEY", // 0x25 — speaks, line 0x28
         buy_result::SELLER_DONT_LIKE_YOU => "ERR_VENDOR_HATES_YOU", // 0x22
@@ -254,7 +257,7 @@ fn resolve_item(
 }
 
 /// The occupied buyback slots' player-descriptor indices (0–11) in the client's display order —
-/// timestamp-ascending, oldest first (wow-re `0x4fafd0`: scan slots 69–80 for a non-zero
+/// timestamp-ascending, oldest first (`0x4fafd0`: scan slots 69–80 for a non-zero
 /// guid+price pair, sort by the timestamp fields). Index `i` here is Lua's `GetBuybackItemInfo(i+1)`;
 /// the wire's absolute slot for an entry is `BUYBACK_SLOT_FIRST + index`.
 fn buyback_order(store: &benilla_protocol::ObjectFields) -> Vec<u8> {
@@ -275,12 +278,13 @@ fn buyback_order(store: &benilla_protocol::ObjectFields) -> Vec<u8> {
 fn resolve_buyback(
     idx: u8,
     store: &benilla_protocol::ObjectFields,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     commands: &NetCommands,
 ) -> MerchantItem {
     let guid = store.player_buyback_slot(idx).unwrap_or(0);
-    let obj = items.object(guid);
+    let obj = objects.object(guid);
     let entry = obj.and_then(|o| o.object_entry()).unwrap_or(0);
     let quantity = obj.and_then(|o| o.item_stack_count()).unwrap_or(1).max(1);
     let template = items.template(entry, guid, commands);
@@ -326,11 +330,12 @@ fn resolve_buyback(
 /// No reputation model yet → discount 0.
 fn item_repair_cost(
     guid: u64,
+    objects: &Objects,
     items: &Items,
     tables: &RepairTables,
     commands: &NetCommands,
 ) -> u32 {
-    let Some(obj) = items.object(guid) else {
+    let Some(obj) = objects.object(guid) else {
         return 0;
     };
     let cur = obj.item_durability().unwrap_or(0);
@@ -349,11 +354,12 @@ fn item_repair_cost(
         .repair_cost(points, level, quality, class, subclass, 0.0)
 }
 
-/// The repair-all total: the client's three sweeps (wow-re repair-machinery.md `0x4fbd60`) —
+/// The repair-all total: the client's three sweeps (`0x4fbd60`) —
 /// equipped 0–18, the backpack, and the CONTENTS of the 4 equipped bags (never bank/keyring/
 /// buyback).
 fn repair_all_cost(
     store: &benilla_protocol::ObjectFields,
+    objects: &Objects,
     items: &Items,
     tables: &RepairTables,
     commands: &NetCommands,
@@ -361,7 +367,7 @@ fn repair_all_cost(
     let mut total: u64 = 0;
     let mut add = |guid: u64, items: &Items| {
         if guid != 0 {
-            total += u64::from(item_repair_cost(guid, items, tables, commands));
+            total += u64::from(item_repair_cost(guid, objects, items, tables, commands));
         }
     };
     for i in 0..19u8 {
@@ -375,7 +381,7 @@ fn repair_all_cost(
         if bag_guid == 0 {
             continue;
         }
-        let slots: Vec<u64> = items
+        let slots: Vec<u64> = objects
             .object(bag_guid)
             .map(|b| {
                 let n = b.container_num_slots().unwrap_or(0).min(36) as u8;
@@ -393,6 +399,7 @@ fn repair_all_cost(
 /// when no vendor is open.
 fn snapshot(
     open: &MerchantOpen,
+    objects: &Objects,
     items: &Items,
     icons: Option<&ItemDisplays>,
     commands: &NetCommands,
@@ -405,13 +412,13 @@ fn snapshot(
         .map(|store| {
             buyback_order(store)
                 .into_iter()
-                .map(|idx| resolve_buyback(idx, store, items, icons, commands))
+                .map(|idx| resolve_buyback(idx, store, objects, items, icons, commands))
                 .collect()
         })
         .unwrap_or_default();
     let can_repair = vendor_npc_flags & NPC_FLAG_REPAIR != 0;
     let repair_cost = match (can_repair, player, tables) {
-        (true, Some(store), Some(t)) => repair_all_cost(store, items, t, commands),
+        (true, Some(store), Some(t)) => repair_all_cost(store, objects, items, t, commands),
         _ => 0,
     };
     Some(MerchantState {
@@ -433,6 +440,7 @@ fn snapshot(
 fn feed_merchant(
     script: Option<NonSendMut<UiScript>>,
     open: Res<MerchantOpen>,
+    objects: Objects,
     items: Res<Items>,
     icons: Option<Res<ItemDisplays>>,
     commands: Res<NetCommands>,
@@ -493,6 +501,7 @@ fn feed_merchant(
     let player = self_q.iter().next().map(|s| &s.0);
     let fresh = snapshot(
         &open,
+        &objects,
         &items,
         icons.as_deref(),
         &commands,
@@ -562,7 +571,7 @@ fn drain_merchant(
     mut open: ResMut<MerchantOpen>,
     commands: Res<NetCommands>,
     self_q: Query<(&ObjectStore, &Guid), With<SelfPlayer>>,
-    items: Res<Items>,
+    objects: Objects,
 ) {
     let Some(mut script) = script else {
         return;
@@ -624,7 +633,7 @@ fn drain_merchant(
     for (bag, slot) in script.take_merchant_cursor_sells() {
         let Some(vendor) = open.vendor else { continue };
         let slot0 = u8::try_from(slot.saturating_sub(1)).unwrap_or(0);
-        match self_store.and_then(|s| slot_guid(&s.0, bag, slot0, &items)) {
+        match self_store.and_then(|s| slot_guid(&s.0, bag, slot0, &objects)) {
             Some(item_guid) => {
                 debug!("ui_merchant: cursor sell bag {bag} slot {slot} (item {item_guid:#x})");
                 let _ = commands.0.send(ClientCommand::SellItem {
diff --git a/crates/benilla-app/src/ui_merchant/net.rs b/crates/benilla-app/src/ui_merchant/net.rs
new file mode 100644
index 00000000..ce5146d4
--- /dev/null
+++ b/crates/benilla-app/src/ui_merchant/net.rs
@@ -0,0 +1,119 @@
+//! The vendor window's packet handlers (decision 0081 phase 4; in the net handler table since
+//! 2318, moved out of the drain's npc arm file) — each fills the [`MerchantOpen`] session or the
+//! [`MerchantErrors`] line queue the merchant feed ([`super`]) reads.
+
+use benilla_protocol::messages::VendorItem;
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::{MerchantErrors, MerchantOpen, MerchantRefusal};
+use crate::net::NetHandlerApp;
+
+/// Register the vendor handlers — called from [`super::UiMerchantPlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::VendorInventory, on_inventory)
+        .net_handler(K::VendorBuyResult, on_buy_result)
+        .net_handler(K::VendorBuyFailed, on_buy_failed)
+        .net_handler(K::VendorSellFailed, on_sell_failed)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_inventory(In(ev): In<SessionEvent>, mut merchant: ResMut<MerchantOpen>) {
+    if let SessionEvent::VendorInventory { vendor, items } = ev {
+        vendor_inventory(vendor, items, &mut merchant);
+    }
+}
+
+fn on_buy_result(In(ev): In<SessionEvent>, mut merchant: ResMut<MerchantOpen>) {
+    if let SessionEvent::VendorBuyResult {
+        vendor,
+        slot,
+        new_count,
+        ..
+    } = ev
+    {
+        vendor_buy_result(vendor, slot, new_count, &mut merchant);
+    }
+}
+
+fn on_buy_failed(
+    In(ev): In<SessionEvent>,
+    mut merchant: ResMut<MerchantOpen>,
+    mut errors: ResMut<MerchantErrors>,
+) {
+    if let SessionEvent::VendorBuyFailed {
+        vendor,
+        item_entry,
+        reason,
+    } = ev
+    {
+        vendor_buy_failed(vendor, item_entry, reason, &mut merchant, &mut errors);
+    }
+}
+
+fn on_sell_failed(In(ev): In<SessionEvent>, mut errors: ResMut<MerchantErrors>) {
+    if let SessionEvent::VendorSellFailed { reason, .. } = ev {
+        vendor_sell_failed(reason, &mut errors);
+    }
+}
+
+/// An open vendor window dies with the socket. A listener on the session end
+/// (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut merchant: ResMut<MerchantOpen>) {
+    merchant.clear_session();
+}
+
+/// A vendor's stock (`SMSG_LIST_INVENTORY`): fill the [`MerchantOpen`] the merchant feed
+/// ([`super`]) reads. A successful buy updates the stock display via
+/// [`vendor_buy_result`] (the item itself lands via item-create); a successful sell is silent
+/// (never a packet here — only the error path is).
+fn vendor_inventory(vendor: u64, items: Vec<VendorItem>, merchant: &mut MerchantOpen) {
+    debug!("net: vendor {vendor:#x} listed {} items", items.len());
+    merchant.open(vendor, items);
+}
+
+/// A purchase updated the vendor's stock (`SMSG_BUY_ITEM`). Only touch stock for the open
+/// vendor (a late answer for a closed window is stale).
+fn vendor_buy_result(vendor: u64, slot: u32, new_count: u32, merchant: &mut MerchantOpen) {
+    if merchant.vendor == Some(vendor) {
+        merchant.update_stock(slot, new_count);
+    }
+}
+
+/// A purchase was refused (`SMSG_BUY_FAILED`) — the merchant window's error line, and for the
+/// out-of-stock code the refusing row's own count.
+///
+/// **`ITEM_ALREADY_SOLD` zeroes the row** (`0x5dcda7`..`0x5dcdd6`, decision 1821): the reference
+/// walks its 128-row vendor cache, writes 0 into the matching row's count word and repaints —
+/// gated, as every other stale-answer path here is, on the packet naming the vendor still open.
+///
+/// **NAMED DIVERGENCE in the key.** The reference matches the row's `+0x00`, the vendor *slot* —
+/// the same word `SMSG_BUY_ITEM` keys its stock update by. vmangos puts the item *entry* in that
+/// field (`Player::SendBuyError`, `Player.cpp:11637`: `packet->itemEntry = item`), so matching by
+/// slot would find nothing on the server we actually talk to; matching by entry is the same row.
+/// vmangos raises this code from exactly the condition the zeroing models —
+/// `GetVendorItemCurrentCount(crItem) < totalCount` under `crItem->maxcount != 0`
+/// (`Player.cpp:18508`).
+fn vendor_buy_failed(
+    vendor: u64,
+    item_entry: u32,
+    reason: u8,
+    merchant: &mut MerchantOpen,
+    errors: &mut MerchantErrors,
+) {
+    debug!("net: buy failed (entry {item_entry}, reason {reason})");
+    if reason == benilla_protocol::messages::buy_result::ITEM_ALREADY_SOLD
+        && merchant.vendor == Some(vendor)
+    {
+        merchant.sold_out(item_entry);
+    }
+    errors.0.push(MerchantRefusal::Buy(reason));
+}
+
+/// A sell was refused (`SMSG_SELL_ITEM`'s error path) — the merchant window's error line.
+fn vendor_sell_failed(reason: u8, errors: &mut MerchantErrors) {
+    debug!("net: sell failed (reason {reason})");
+    errors.0.push(MerchantRefusal::Sell(reason));
+}
diff --git a/crates/benilla-app/src/ui_mirror.rs b/crates/benilla-app/src/ui_mirror.rs
index ea3daed0..5755f676 100644
--- a/crates/benilla-app/src/ui_mirror.rs
+++ b/crates/benilla-app/src/ui_mirror.rs
@@ -78,8 +78,7 @@ fn global_string_label(kind: MirrorTimerKind) -> &'static str {
 
 /// The bar's caption — **arg6** of `MIRROR_TIMER_START`, and it is **not** a fixed word.
 ///
-/// §5-VERIFIED (wow-re `object-layer/scratch/mirror-timer.md`, the 2026-08-02 cross-check of
-/// handler `0x5e7990` and its label helper `0x5e7b10`): the client tries the **owning spell's
+/// Handler `0x5e7990` and its label helper `0x5e7b10`: the client tries the **owning spell's
 /// localized name first** — `Spell.dbc` `SpellRec + 0x1e0 + 4*locale`, indexed by the START
 /// packet's `spellId` — and only falls back to the `"<NAME>_LABEL"` global string when there is
 /// no spell (`spellId == 0`).
@@ -191,10 +190,43 @@ fn feed_mirror_timers(
 
 /// The mirror-timer UI seam: the queue + its drain, ordered like the cast bar's — before the VM
 /// ticks, so an edge and its first OnUpdate land on the same frame.
+/// The mirror timers' packet handlers (decision 0874; in the net handler table since 2313):
+/// breath / fatigue / feign-death. Pure queue handlers — every meaning (which bar, what colour,
+/// what caption, how fast it drains) is resolved at the UI seam in this module, and the
+/// countdown itself is the FrameXML's own OnUpdate integration.
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::{MirrorTimerEdge, MirrorTimerFeed};
+    use crate::net::NetHandlerApp;
+
+    /// Register the handlers — called from [`super::UiMirrorPlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::MirrorTimerStart, on_edge)
+            .net_handler(K::MirrorTimerPause, on_edge)
+            .net_handler(K::MirrorTimerStop, on_edge);
+    }
+
+    fn on_edge(In(ev): In<SessionEvent>, mut feed: ResMut<MirrorTimerFeed>) {
+        let edge = match ev {
+            SessionEvent::MirrorTimerStart(start) => MirrorTimerEdge::Start(start),
+            SessionEvent::MirrorTimerPause { kind, paused } => {
+                MirrorTimerEdge::Pause { kind, paused }
+            }
+            SessionEvent::MirrorTimerStop { kind } => MirrorTimerEdge::Stop { kind },
+            _ => return,
+        };
+        feed.0.push(edge);
+    }
+}
+
 pub(crate) struct UiMirrorPlugin;
 
 impl Plugin for UiMirrorPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<MirrorTimerFeed>()
             .add_systems(Update, feed_mirror_timers.in_set(UnitFeed));
     }
@@ -224,7 +256,7 @@ mod tests {
         assert_eq!(caption(MirrorTimerKind::FeignDeath, None), "");
     }
 
-    /// The correction 0874 got wrong (§5, wow-re `mirror-timer.md`): the client tries the OWNING
+    /// The correction 0874 got wrong (`0x5e7b10`): the client tries the OWNING
     /// SPELL's localized name first and only falls back to the global string. A water-breathing
     /// effect owns the breath timer while it is up, so the bar reads with the spell's name.
     #[test]
diff --git a/crates/benilla-app/src/ui_models/mod.rs b/crates/benilla-app/src/ui_models/mod.rs
index 50d7b3f9..073dc3db 100644
--- a/crates/benilla-app/src/ui_models/mod.rs
+++ b/crates/benilla-app/src/ui_models/mod.rs
@@ -2,12 +2,12 @@
 //! sweep, the autocast shine, the minimap and world-map pings, the item-push card, the map's
 //! arrow, and whatever an addon parks in a `CreateFrame("Model")`.
 //!
-//! ## The law (wow-re `system/ui/scratch/modelframe-render-law.md`, `e1b1794b`)
+//! ## The law
 //!
 //! A `<Model>` **whose file supplies a camera** draws its scene through it: the widget holds a raw
 //! camera index (ctor 0, `SetCamera(n)`), and the record's `lookAt(eye, target, up)` plus the
-//! client's diagonal-FOV projection at the pane's own width/height frame the model (§2, camera-law
-//! §4a). The authored eye and target are carried through the model's root transform, so
+//! client's diagonal-FOV projection at the pane's own width/height frame the model (`0x76cec0`,
+//! `0x7ac640`). The authored eye and target are carried through the model's root transform, so
 //! `SetModelScale` and `SetPosition` cancel for framing on that leg and bite only on the record's
 //! unscaled near/far. An index past the file's camera count installs a NULL camera, which is the
 //! other leg:
@@ -15,12 +15,13 @@
 //! A `<Model>` with no M2 camera picked draws its scene **orthographically over the frame's
 //! rect**: origin at the rect's bottom-left, `+X` right, `+Y` up, `Z` depth only, with the root
 //! matrix `T(pos · layoutScale) · R(facing, +Z) · S(G48 · 5/3 · modelScale · layoutScale)` — so one
-//! model unit is `1280 · modelScale · layoutScale` FrameXML units, aspect-independent (§2/§3).
-//! Every batch draws once, LEQUAL over a depth buffer cleared for the widget's own rect, straight
-//! into the back buffer (§6); every in-game UI M2 is UNLIT on every material (§5.7); the
-//! animator is the world's, on the widget's private clock (§4). A particle's half-extent is the
-//! one quantity outside the unit law — added in eye space, it maps at `768 · √(a²+1)` FrameXML
-//! units per model unit and carries neither scale (`clip-and-scale.md` §6).
+//! model unit is `1280 · modelScale · layoutScale` FrameXML units, aspect-independent (`0x7ad7f0`,
+//! `0x76d1a0`). Every batch draws once, LEQUAL over a depth buffer cleared for the widget's own
+//! rect, straight into the back buffer (`0x76d240`, `0x70b360`); every in-game UI M2 is UNLIT on
+//! every material (measured over the shipped files); the animator is the world's, on the widget's
+//! private clock (`0x714260`, `0x76d7f0`). A particle's half-extent is the one quantity outside the
+//! unit law — added in eye space, it maps at `768 · √(a²+1)` FrameXML units per model unit and
+//! carries neither scale (`0x7b2a50`).
 //!
 //! ## The shape here: tiles in one atlas, composited at the callback rank
 //!
@@ -67,8 +68,8 @@
 //!
 //! ## What a tile's light is
 //!
-//! `<Model>`'s embedded light is DISABLED (§5.2), and a LIT batch under no light renders black —
-//! which never shows on the shipped UI M2s because all of them are unlit, and which is the
+//! `<Model>`'s embedded light is DISABLED (ctor `0x76c8e0`), and a LIT batch under no light renders
+//! black — which never shows on the shipped UI M2s because all of them are unlit, and which is the
 //! faithful answer for an addon's lit one. So the DEFAULT tile light buffer is a black light (no
 //! ambient, no diffuse, fog off) and unlit batches bypass it.
 //!
@@ -165,7 +166,7 @@ pub(crate) fn trace_on() -> bool {
 }
 
 /// One pane's request for a tile this frame — what the extract knows about the widget: its
-/// size on the device, the unit ladder the render law derives from it, and the Lua-set scene.
+/// size on the device, the unit ladder `0x76d1a0` derives from it, and the Lua-set scene.
 /// Published by the extract's `ModelPane` arm (keyed by the pane's frame handle, overwritten on
 /// every conversion), read by [`sync_tiles`].
 #[derive(Clone, Debug, PartialEq)]
@@ -211,7 +212,7 @@ pub(crate) struct TileRequest {
     pub rect: Rect,
     /// The pane's paint key: `ZKey::callback(Artwork)` (1995), the composite's rank.
     pub z_key: u64,
-    /// The frame's OWN alpha (render law §4.4): the composite draws at it.
+    /// The frame's OWN alpha (`0x76d120`): the composite draws at it.
     pub alpha: f32,
     /// The enclosing ScrollFrame clip, if any (decision 0112), in the quad pass's space.
     pub clip: Option<Rect>,
@@ -265,12 +266,12 @@ impl TileScene {
     /// The light buffer this scene wants — the reference's collector, finalized.
     ///
     /// The collector is zeroed every frame and gathers only what the fill callback `0x76d680`
-    /// stages (render law §5.5): the fog when it is armed, and the light when it is **enabled**.
+    /// stages: the fog when it is armed, and the light when it is **enabled**.
     /// With the light off, the finalize writes zero ambient and zero diffuse and a LIT batch draws
     /// black — the reference's answer, not a gap. With it on, the type decides which arm:
     /// directional folds ambient + one diffuse lobe through the SH accumulators
     /// (`0x71bc70`/`0x71bce0`), point drops into the ≤4-nearest heap and contributes **no**
-    /// ambient (wow-re `glue-model-lighting.md` §16 B1).
+    /// ambient (`0x71bf90`).
     ///
     /// The lit lane here is the rig one, so the ambient and the lobe go into **probe slot 0** —
     /// the slot every tile part's `MeshTag` names — exactly as the glue booth's own scene blob
@@ -684,7 +685,7 @@ fn setup_tiles(
         layer: layer.clone(),
         lights: Vec::new(),
     };
-    // Slot 0 — the `<Model>` ctor's scene: light disabled, fog off (render law §5.2). Built here
+    // Slot 0 — the `<Model>` ctor's scene: light disabled, fog off (`0x76c8e0`). Built here
     // rather than lazily because every shipped pane wants it and nothing else ever does.
     //
     // Tile rigs skin from a light buffer's palette region (decision 0720's mirror law), and the
@@ -813,8 +814,8 @@ pub(crate) fn spawn_warm_tile_cam(
 }
 
 /// The bevy-space → tile-camera-space rotation: WoW `+X` (bevy `−Z`) to the right, WoW `+Y`
-/// (bevy `−X`) up, WoW `+Z` (bevy `+Y`) toward the viewer — the ortho leg's axes (§2). A proper
-/// rotation (determinant +1), so winding survives.
+/// (bevy `−X`) up, WoW `+Z` (bevy `+Y`) toward the viewer — the ortho leg's axes (`0x7ad7f0`).
+/// A proper rotation (determinant +1), so winding survives.
 fn wow_to_screen() -> Quat {
     Quat::from_mat3(&Mat3::from_cols(
         Vec3::new(0.0, -1.0, 0.0),
@@ -1238,7 +1239,7 @@ fn sync_tiles(
 
         // ── The leg ────────────────────────────────────────────────────────────────────
         //
-        // PERSPECTIVE (render law §2, camera-law §4a): the file's own camera record frames the
+        // PERSPECTIVE (`0x7ac640`): the file's own camera record frames the
         // pane, through a camera of this tile's own whose viewport is the tile's cell. The root
         // is `T(pos·layoutScale) · R(facing) · S(s)` in MODEL units — no pixel ladder, because
         // the projection is the record's and the viewport is the cell — and the authored
@@ -1358,13 +1359,12 @@ fn sync_tiles(
         let gseq_s = pane.clock_ms as f64 / 1000.0;
         // …and the BONE global-sequence channels read it too, not the world clock (decision
         // 2046). The animation kernel's Phase B cursor is `[[model+0x2c]+0xc] − [model+0x68]`
-        // — the clock of the scene that OWNS the instance, minus the attach snapshot — and a
-        // `<Model>` widget owns a private `CM2Scene` (`CSimpleModel+0x314`) that only its own
-        // `OnUpdate` advances (wow-re `gseq-anchor.md` §1/§2, `modelframe-animation-clock.md`
-        // §1.1/§3, both byte-verified). The visible case is the ping's 4833 ms spinner: its
-        // phase belongs to the pane, which is why "ping N resumes where ping N−1 stopped" needs
-        // no accumulator of ours (2013). The drive stamps its own anchor on its first tick, which
-        // is the attach.
+        // (`0x714260`) — the clock of the scene that OWNS the instance, minus the attach
+        // snapshot — and a `<Model>` widget owns a private `CM2Scene` (`CSimpleModel+0x314`)
+        // that only its own `OnUpdate` (`0x76d7f0`) advances. The visible case is the ping's
+        // 4833 ms spinner: its phase belongs to the pane, which is why "ping N resumes where
+        // ping N−1 stopped" needs no accumulator of ours (2013). The drive stamps its own anchor
+        // on its first tick, which is the attach.
         if let Some(mut d) = drive {
             d.set_clock(gseq_s);
         }
@@ -1384,7 +1384,7 @@ fn sync_tiles(
                 trace_alphas.push(a);
             }
             if let Ok((mut tag, mut pvis)) = parts.get_mut(part.entity) {
-                // The `A ≤ 0` cull (wow-re `m2-alpha-combine-cull`): a batch the artist keyed
+                // The `A ≤ 0` cull (`0x707b3a`): a batch the artist keyed
                 // off in this sequence is skipped, not drawn at zero.
                 let want = if a > 0.0 {
                     Visibility::Inherited
@@ -1434,8 +1434,8 @@ fn sync_tiles(
         }
         // A particle's half-extent is added in EYE space, so its unit is the leg's: the
         // orthographic leg measures the cell in pixels and hands it `768·√(a²+1)` FrameXML units
-        // per model unit (§6, carrying neither scale), while the perspective leg's eye space IS
-        // the root's, and its own projection does the conversion — the world's plain 1.0.
+        // per model unit (`0x7b2a50`, carrying neither scale), while the perspective leg's eye
+        // space IS the root's, and its own projection does the conversion — the world's plain 1.0.
         let star = if tile.cam_slot.is_some() && req.camera.is_some() {
             1.0
         } else {
@@ -1523,7 +1523,7 @@ fn sync_tiles(
     );
 }
 
-/// The perspective leg's rig for one pane — the pure half, so the law's own worked numbers can be
+/// The perspective leg's rig for one pane — the pure half, so the reference's worked numbers can be
 /// checked without a world.
 struct PerspectiveRig {
     /// The model's root, `T(pos · layoutScale) · R(facing, +Z) · S(s)` in Bevy model space —
@@ -1535,28 +1535,27 @@ struct PerspectiveRig {
     projection: WowPortraitProjection,
 }
 
-/// Build it (render law §2, camera-law §4a/§11).
+/// Build it.
 ///
 /// **The authored eye and target are carried through the root transform.** That is `0x718960`'s
 /// publish — `eye_published = (position_base + posTrack) · M_root` — and it is the whole reason
 /// `SetModelScale` and `SetPosition` cancel here: the camera moves with the model, so the framing
 /// is invariant to both. They are still applied rather than skipped, because the record's near and
-/// far are copied into the camera **unscaled** while every eye-space depth scales with `s`, so a
-/// LARGE `SetModelScale` drives the model through the **far** plane and a small one through the
-/// near (wow-re `modelframe-facing-cancels.md` §6 — the direction is the opposite of the obvious
-/// guess). `near`/`far` reach only `m22`/`m32`: `near` cancels algebraically out of `m00`/`m11`,
-/// so the x/y screen scale is `fov` and `aspect` alone.
+/// far are copied into the camera **unscaled** (`0x70ebd0`) while every eye-space depth scales
+/// with `s`, so a LARGE `SetModelScale` drives the model through the **far** plane and a small one
+/// through the near (the direction is the opposite of the obvious guess). `near`/`far` reach only
+/// `m22`/`m32`: `near` cancels algebraically out of `m00`/`m11`, so the x/y screen scale is `fov`
+/// and `aspect` alone.
 ///
 /// The **up** vector does not ride the root: `0x7ac640` assembles it out of four `CCamera` fields
 /// the publish never writes — `up = (sin(a₆)·sin(roll), −cos(a₆)·sin(roll), cos(roll))` in WoW
 /// model space, and property `a₆` has **no writer image-wide**, so it holds its constructor `0`
-/// for ever and the vector is `(0, −sin(roll), cos(roll))` (wow-re
-/// `modelframe-facing-cancels.md` §2). At `roll = 0` that is model-space `+Z` exactly — which is
-/// the very axis `SetFacing` turns the model about, and *that* is why the facing cancels here too:
-/// the eye, the target and the geometry all turn about an axis the up vector lies on, so the image
-/// does not move (§3). The reference's own one-frame publish lag — it reads the eye before it
-/// rebuilds the root, so the frame a facing CHANGES draws one step out of phase (§4) — is a quirk
-/// of the ordering, not the mechanism, and is deliberately not reproduced.
+/// for ever and the vector is `(0, −sin(roll), cos(roll))`. At `roll = 0` that is model-space `+Z`
+/// exactly — which is the very axis `SetFacing` turns the model about, and *that* is why the facing
+/// cancels here too: the eye, the target and the geometry all turn about an axis the up vector lies
+/// on, so the image does not move. The reference's own one-frame publish lag — its paint `0x76d240`
+/// reads the eye before it rebuilds the root, so the frame a facing CHANGES draws one step out of
+/// phase — is a quirk of the ordering, not the mechanism, and is deliberately not reproduced.
 fn perspective_rig(
     record: &benilla_assets::PortraitCamera,
     req: &TileRequest,
@@ -1746,7 +1745,7 @@ pub(crate) fn composite_quads(bridge: &UiModelTiles) -> Vec<UiQuad> {
                 z_key: req.z_key,
                 texture: Some(atlas.clone()),
                 uv: UvRect::from_tex_coords([u0, u1, v0, v1]),
-                // The instance draws at the widget's OWN alpha (render law §4.4).
+                // The instance draws at the widget's OWN alpha (`0x76d120`).
                 color: [1.0, 1.0, 1.0, req.alpha],
                 // A render target: premultiplied by construction (`UiQuad` doc).
                 premultiplied: true,
@@ -1879,7 +1878,7 @@ fn build_tile(
         let world = render.mats.steady(sub, texture, (i + 1) as u16)?;
         // The twin: same material, this rig's light buffer, and the batch's AUTHORED fog policy
         // when the pane armed fog — which is where the per-material UNFOGGED bit does its own
-        // work (render law §5.6: a fogged pane still draws its unfogged materials unfogged). A
+        // work (`0x70bb24`: a fogged pane still draws its unfogged materials unfogged). A
         // pane with no fog forces it off, as every tile did before 2027. The shade selector both
         // lanes flip is inert on an unlit batch, which is every shipped UI M2.
         let lane = if fogged {
@@ -2446,8 +2445,8 @@ mod tests {
         }
     }
 
-    /// `HumanMale`'s camera 1 as `benilla-extract m2cam` reads it — and as wow-re
-    /// `modelframe-camera-law.md` §7 records it, to the digit.
+    /// `HumanMale`'s camera 1 as `benilla-extract m2cam` reads it — and as the reference records
+    /// it, to the digit.
     fn human_male_cam1() -> benilla_assets::PortraitCamera {
         let wow = benilla_assets::coords::wow_to_bevy;
         benilla_assets::PortraitCamera {
@@ -2464,14 +2463,14 @@ mod tests {
     /// `t = tan(fovy / (2·√(aspect²+1)))`, `m11 = 1/t`, `m00 = m11/aspect` — not a vertical fov,
     /// and not an aspect-independent crop.
     ///
-    /// The numbers are wow-re's own worked checks. `camera-law.md` §12.1: a `318×224` pane gives
-    /// `θ = 0.287938 · fov` and a `233×224` pane `θ = 0.346523 · fov`. §8's fallback check:
+    /// The numbers are the reference's own worked checks: a `318×224` pane gives
+    /// `θ = 0.287938 · fov` and a `233×224` pane `θ = 0.346523 · fov`. The fallback camera's check:
     /// `aspect = 1.4196429`, `√(aspect²+1) = 1.7364815`, `tan(0.5/(2·1.7364815)) = 0.1449700`.
     #[test]
     fn the_perspective_projection_is_the_clients_diagonal_fov_matrix() {
         use bevy::camera::CameraProjection;
 
-        // §8's worked line, on the fallback camera's `fov = 0.5` at the pet pane's 318×224.
+        // The fallback camera's worked line: `fov = 0.5` at the pet pane's 318×224.
         let cam = benilla_assets::PortraitCamera {
             eye: Vec3::new(0.0, 0.0, 5.0),
             target: Vec3::ZERO,
@@ -2483,7 +2482,7 @@ mod tests {
         let aspect: f32 = 318.0 / 224.0;
         assert!((aspect - 1.419_642_9).abs() < 1e-6);
         let m = pane_projection(&cam, aspect).get_clip_from_view();
-        // `m11 = 1/t` with `t = tan(θ)`; §8's `t` is 0.1449700.
+        // `m11 = 1/t` with `t = tan(θ)`; the fallback check's `t` is 0.1449700.
         let t = 1.0 / m.y_axis.y;
         assert!((t - 0.144_97).abs() < 1e-5, "t = {t}");
         // …and `m00 = m11 / aspect` — the one `aspect` doing both jobs, never 1.0 (a transplanted
@@ -2494,7 +2493,7 @@ mod tests {
             m.x_axis.x,
             m.y_axis.y / aspect
         );
-        // §12.1's two half-angles, as fractions of the record fov.
+        // The two worked half-angles, as fractions of the record fov.
         for (w, h, want) in [(318.0, 224.0, 0.287_938), (233.0, 224.0, 0.346_523_f32)] {
             let a: f32 = w / h;
             let theta = (0.5_f32 * cam.fov / (a * a + 1.0).sqrt()) / cam.fov;
@@ -2502,11 +2501,11 @@ mod tests {
         }
     }
 
-    /// **`SetModelScale` and `SetPosition` CANCEL on the perspective leg** (camera-law §11.4): the
+    /// **`SetModelScale` and `SetPosition` CANCEL on the perspective leg** (`0x718960`): the
     /// authored eye and target are carried through the very root transform the geometry is drawn
     /// through, so the picture is invariant to both. This is the property the leg is built on, and
-    /// the failure mode it guards is the one wow-re's own §5 pair got backwards — applying the
-    /// root to the geometry but not to the camera, which is wrong by `1/s`.
+    /// the failure mode it guards is applying the root to the geometry but not to the camera,
+    /// which is wrong by `1/s`.
     ///
     /// The check is on the pixels, not on the matrices: a model-local point's clip-space `x/w`
     /// and `y/w` must be identical at any scale and any offset.
@@ -2570,10 +2569,8 @@ mod tests {
         );
     }
 
-    /// **`SetFacing` cancels too** — the half of the leg that had to be settled at the bytes
-    /// before it could be built (wow-re `modelframe-facing-cancels.md`, a §5 round commissioned
-    /// by this work; `modelframe-render-law.md` §2's "only `SetFacing`/`SetRotation` show" is
-    /// scoped to `<PlayerModel>`'s FROZEN camera and does not hold here).
+    /// **`SetFacing` cancels too** (on `<PlayerModel>`'s FROZEN camera, `0x7acf10`, only
+    /// `SetFacing`/`SetRotation` show; that does not hold here).
     ///
     /// The reason is the up vector: `0x7ac640` builds it as `(0, −sin(roll), cos(roll))` in model
     /// space out of `CCamera` fields the publish never writes, and at `roll = 0` — every camera a
@@ -2643,7 +2640,7 @@ mod tests {
         let want = (cam.target - cam.eye).normalize();
         assert!((fwd - want).length() < 1e-5, "{fwd:?} vs {want:?}");
         // The distance the record authors — the whole mechanism behind "the pane looks
-        // normalized" (camera-law §7: Blizzard authored a per-model distance).
+        // normalized" (measured over the shipped models: Blizzard authored a per-model distance).
         let d = (cam.target - cam.eye).length();
         assert!((d - 4.0234).abs() < 1e-3, "authored eye distance {d}");
         // Up is the model's own up, not the camera's roll-free default in some other frame.
diff --git a/crates/benilla-app/src/ui_party/feed.rs b/crates/benilla-app/src/ui_party/feed.rs
index c424ccd4..7aca697d 100644
--- a/crates/benilla-app/src/ui_party/feed.rs
+++ b/crates/benilla-app/src/ui_party/feed.rs
@@ -461,14 +461,14 @@ pub(super) fn feed_party(
     // expected to move *without* this event, and firing on them would make the whole raid pane
     // repaint every time somebody took damage.
     //
-    // The exact fire SITE is not pinned to bytes. wow-re has the event (FrameScript id `0x1f3`,
-    // its name slot `0xbe1964`) and the raid-roster TU that owns the neighbouring lines
-    // (`0x4ba220`/`0x4ba550`, `object-layer/scratch/party-group-wire.md`), but nobody has carved
-    // which of that TU's arms signal it. What IS constrained: `SMSG_GROUP_LIST` is the only
-    // packet that can move any of these four fields, and the reference's RaidFrame repaints on
-    // this event and on `PARTY_MEMBERS_CHANGED` alike — so a client that fires it on every
-    // identity change of the roster cannot show a stale pane, whatever the extra arms turn out to
-    // be. INFERRED, and named as such rather than left to be discovered from a bug.
+    // The exact fire SITE is not pinned to bytes. The reference has the event (FrameScript id
+    // `0x1f3`, its name slot `0xbe1964`) and the raid-roster TU that owns the neighbouring lines
+    // (`0x4ba220`/`0x4ba550`), but which of that TU's arms signal it is not identified. What IS
+    // constrained: `SMSG_GROUP_LIST` is the only packet that can move any of these four fields,
+    // and the reference's RaidFrame repaints on this event and on `PARTY_MEMBERS_CHANGED` alike
+    // — so a client that fires it on every identity change of the roster cannot show a stale
+    // pane, whatever the extra arms turn out to be. INFERRED, and named as such rather than left
+    // to be discovered from a bug.
     if raid_key != fed.raid_key {
         gate.audit("feed_party", "the raid-roster edge");
         fed.raid_key = raid_key;
@@ -494,10 +494,9 @@ pub(super) fn feed_party(
     // ── READY_CHECK (decision 1549) ─────────────────────────────────────────────────────────
     //
     // The reference's event `0x218`, fired by the `MSG_RAID_READY_CHECK` open handler
-    // (`0x4ba360` — wow-re `system/ui/ui.md`, "Raid target icons + ready check"), which is also
-    // where its 30 s deadline is armed (`0xb713f4 = clock + 0x7530`). UIParent registers it and
-    // calls `ShowReadyCheck()`; the countdown itself is the popup's own OnUpdate, so the deadline
-    // is Lua-side here rather than a second clock in Rust.
+    // (`0x4ba360`), which is also where its 30 s deadline is armed (`0xb713f4 = clock + 0x7530`).
+    // UIParent registers it and calls `ShowReadyCheck()`; the countdown itself is the popup's own
+    // OnUpdate, so the deadline is Lua-side here rather than a second clock in Rust.
     if group.ready_check != fed.ready_check {
         gate.audit("feed_party", "the ready-check edge");
         fed.ready_check = group.ready_check;
@@ -592,7 +591,7 @@ pub(super) struct RaidSelf {
     ///
     /// `NameCache::player_traits` is filled by `SMSG_NAME_QUERY_RESPONSE`, and **we never query
     /// ourselves**: the login seeds our own name with `traits: None` precisely so `"player"` needs
-    /// no round trip (`net::apply::session::connected`). So for our own row that lookup is `None`
+    /// no round trip (`net::session::connected`). So for our own row that lookup is `None`
     /// *forever*, which painted the local player's raid row with no class column and the plain
     /// font colour instead of their class's — caught in a live `/partytest raid` run, invisible to
     /// every unit test because the fixtures seed the traits by hand.
@@ -690,14 +689,14 @@ fn raid_guid_for_name(
         .map(|m| m.guid)
 }
 
-/// Build `GetRaidRosterInfo`'s array (decision 0434 §6's roster, wow-re
-/// `ui/scratch/raid-roster-bindings.md` §2). Empty outside a raid — `GroupState::group_type` is
-/// `1` only for one — which is what makes `GetNumRaidMembers()` answer `0` in a party.
+/// Build `GetRaidRosterInfo`'s array (decision 0434 §6's roster, `0x4bb560`). Empty outside a
+/// raid — `GroupState::group_type` is `1` only for one — which is what makes `GetNumRaidMembers()`
+/// answer `0` in a party.
 ///
 /// **The player is row 1.** The reference's array contains the local player (it is why
 /// `UnitInRaid("player")` answers `1`), and the wire's list does not, so the recipient is spliced
-/// back in here. *Where* the real client puts itself is **not derived** — the note carves the
-/// binding, not the array's fill order — and nothing observed depends on it: every corpus consumer
+/// back in here. *Where* the real client puts itself is **not derived** — the binding is derived,
+/// not the array's fill order — and nothing observed depends on it: every corpus consumer
 /// sweeps `1..GetNumRaidMembers()` (or `1..MAX_RAID_MEMBERS`) and keys the result by name.
 ///
 /// A pure function over plain data so the shape is testable without a second account in a raid:
@@ -713,7 +712,7 @@ fn raid_roster(
         return Vec::new();
     }
     // rank: 2 leader · 1 assistant · 0 member. The binding exposes `[edi+0xc]` unadjusted and
-    // wow-re could not derive the convention from its bytes; the corpus can and does —
+    // the convention cannot be derived from its bytes; the corpus can and does —
     // `ChatLog.lua:351-353` prints `@` for 2 and `*` for 1.
     let rank_of = |guid: u64, flags: u8| {
         if guid == group.leader {
@@ -808,15 +807,15 @@ fn member_unit_state(
         Some(store) => crate::ui_unit::snapshot(store, Some(m.name.clone()), 0, classes),
         // Out of range: **the roster record** — which is not only the `PARTY_MEMBER_STATS` wire
         // any more (decision 1640). It is seeded from the member's own live descriptor at the
-        // instant their object leaves the manager (`0x5f0880`, `net::apply::group::
+        // instant their object leaves the manager (`0x5f0880`, `ui_party::net::
         // member_deactivated`), seated with the `1/1` placeholder when they join the roster
         // unseen (`0x4e82d0`), and patched by the wire afterwards — so this leg never reads the
         // `0/0` report B334 is about, and there is always a record to read.
         //
-        // The reference's own getter chain, in order (`ui/scratch/party-oor-stats-and-portrait-
-        // law.md` §3): live descriptor → party record → pet record → 0. The pet leg is not
-        // reachable here (a `partyN` token is a player guid; the `partypetN` tokens resolve
-        // nowhere in benilla yet), so this is the whole of it.
+        // The reference's own getter chain, in order: live descriptor → party record (`0x496400`)
+        // → pet record (`0x496420`) → 0. The pet leg is not reachable here (a `partyN` token is a
+        // player guid; the `partypetN` tokens resolve nowhere in benilla yet), so this is the
+        // whole of it.
         None => UnitState {
             exists: true,
             name: Some(m.name.clone()),
@@ -829,7 +828,7 @@ fn member_unit_state(
             // range read ten times the rage of one in range.
             power: stats.map_or(0, PartyMemberStatsInfo::shown_power),
             max_power: stats.map_or(0, PartyMemberStatsInfo::shown_max_power),
-            // **The record's status bits, for the two predicates the RE actually pins to it**:
+            // **The record's status bits, for the two predicates the reference pins to it**:
             // `UnitIsDead 0x517b5d` reads `+0x08 & 4` and `UnitIsGhost 0x517c32` reads `& 8` on
             // the no-object leg. They matter because they are *fresher than the roster byte*: the
             // roster only moves on a `SMSG_GROUP_LIST`, while this byte is rewritten by the
@@ -837,12 +836,12 @@ fn member_unit_state(
             // member who was dead when they walked over the hill reads dead, where the last
             // roster echo still had them alive.
             //
-            // Connected / AFK / DND / PvP / FFA deliberately stay the roster's below: wow-re's §3
-            // table carves the no-object path for the health, power, level and dead/ghost/
-            // connected getters, and says nothing about `UnitIsAFK` and kin. Taking the record
-            // for those would be a guess, and vmangos only flags the status byte on the AFK/DND/
-            // PvP/FFA toggles anyway — never on death, which is exactly why the two above are the
-            // pair worth reading.
+            // Connected / AFK / DND / PvP / FFA deliberately stay the roster's below: the
+            // reference's no-object path (`0x496400`) is known for the health, power, level and
+            // dead/ghost/connected getters, and nothing is known of `UnitIsAFK` and kin. Taking
+            // the record for those would be a guess, and vmangos only flags the status byte on the
+            // AFK/DND/PvP/FFA toggles anyway — never on death, which is exactly why the two above
+            // are the pair worth reading.
             dead: stats.is_some_and(|s| s.status.unwrap_or(0) & member_status::DEAD != 0),
             ghost: stats.is_some_and(|s| s.status.unwrap_or(0) & member_status::GHOST != 0),
             ..Default::default()
@@ -1126,9 +1125,10 @@ fn test_apply_local(
 ) -> bool {
     match req {
         PartyRequest::Leave => {
-            // A local disband: the real path's all-zero list resets everything, sandbox
-            // flag included — `/partytest` starts a fresh one.
-            *group = GroupState::default();
+            // A local disband: exactly what the real path's all-zero list resets — the group
+            // facts, sandbox flag included (`/partytest` starts a fresh one), and not the
+            // session's tickets.
+            group.leave_group();
             true
         }
         PartyRequest::UninviteUnit(token) => {
@@ -1564,13 +1564,13 @@ mod tests {
     ///
     /// Two things this pins, and both were wrong before it. The bars come off the record at all
     /// (they used to read the wire-only snapshot and map an absent field to `0`, which is the
-    /// blanked frame Goudy reported); and the power pair is **divided** by the raw→display scale
+    /// blanked frame); and the power pair is **divided** by the raw→display scale
     /// on this leg exactly as on the live one — a warrior's rage rides the wire ×10, so without
     /// the divide an out-of-range warrior reads ten times an in-range one.
     #[test]
     fn an_out_of_range_member_reads_the_record_and_divides_its_rage() {
         let m = GroupMemberEntry {
-            name: "Thalyn".into(),
+            name: "Brisca".into(),
             guid: 0x1234,
             status: member_status::ONLINE,
             flags: 0,
@@ -1607,7 +1607,7 @@ mod tests {
     }
 
     /// **The record's dead/ghost bits are read out of range** — `UnitIsDead 0x517b5d` (`+0x08 &
-    /// 4`) and `UnitIsGhost 0x517c32` (`& 8`), the two predicates wow-re's §3 table pins to the
+    /// 4`) and `UnitIsGhost 0x517c32` (`& 8`), the two predicates the reference pins to the
     /// no-object leg.
     ///
     /// The falsifier is the roster byte's staleness: it only moves on a `SMSG_GROUP_LIST`, and
@@ -1618,7 +1618,7 @@ mod tests {
     #[test]
     fn an_out_of_range_members_dead_and_ghost_come_off_the_record() {
         let m = GroupMemberEntry {
-            name: "Thalyn".into(),
+            name: "Brisca".into(),
             guid: 0x1234,
             // The stale roster echo: online, alive.
             status: member_status::ONLINE,
diff --git a/crates/benilla-app/src/ui_party/mod.rs b/crates/benilla-app/src/ui_party/mod.rs
index bea9d671..45047635 100644
--- a/crates/benilla-app/src/ui_party/mod.rs
+++ b/crates/benilla-app/src/ui_party/mod.rs
@@ -6,12 +6,11 @@
 //! to the kicked player as the empty-body `SMSG_GROUP_UNINVITE`, and `SMSG_PARTY_COMMAND_RESULT`
 //! acks only the acting player. The real client composes every "%s joins the party." line
 //! engine-side from those packets against the GlobalStrings templates (the FrameXML never touches
-//! the `ERR_*` group strings; the mechanism is wow-re's verified errorId→GlobalStrings display,
+//! the `ERR_*` group strings; the mechanism is the reference's errorId→GlobalStrings display,
 //! `CGGameUI::DisplayError` 0x496720). benilla does the same here: [`GroupState`] mirrors the
 //! wire, and its `apply_*` methods return the finished lines for the net drain to push as
-//! CHAT_MSG_SYSTEM. The mapping is **byte-verified** (decision 0440's §5 fold-back, wow-re
-//! `system/object-layer/scratch/party-group-wire.md`, commit `a07c311c`): each opcode prints
-//! its own line and the GROUP_LIST diff prints the rest — there is NO empty-list state machine.
+//! CHAT_MSG_SYSTEM. In the mapping (decision 0440), each opcode prints its own line and the
+//! GROUP_LIST diff prints the rest — there is NO empty-list state machine.
 //!
 //! The line law (0440):
 //! - GROUP_LIST runs an **ungated** two-way roster diff: new guid → "%s joins the party."
@@ -35,6 +34,7 @@ use bevy::prelude::*;
 use crate::ui_script::{UiFeed, UiInput};
 
 mod feed;
+pub(crate) mod net;
 pub(crate) use feed::{
     raid_row_guid, synthetic_raid, synthetic_roster, GROUPTYPE_RAID, GROUP_MEMBER_SUBGROUP,
     PARTY_TOKENS, RAID_TOKENS,
@@ -44,6 +44,7 @@ pub(crate) struct UiPartyPlugin;
 
 impl Plugin for UiPartyPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<GroupState>().add_systems(
             Update,
             (
@@ -93,7 +94,8 @@ pub struct GroupState {
     /// A lockout is per-CHARACTER, not per-group, so this is the one field here that is not a
     /// group fact. It lives here anyway for the reason that matters: it is per-SESSION state that
     /// must die with the socket, and [`Self::clear_session`] is that guarantee — a second
-    /// resource would be a second thing to remember to clear.
+    /// resource would be a second thing to remember to clear. Leaving the group does NOT clear it
+    /// ([`Self::leave_group`]); nor the four ticket fields below.
     pub saved_instances: Vec<benilla_protocol::messages::RaidInstanceEntry>,
     /// **How many times the server has answered** — one per `SMSG_RAID_INSTANCE_INFO`. A TICKET,
     /// not a flag (the [`Self::ready_check`] shape), and the difference is load-bearing: the
@@ -102,12 +104,12 @@ pub struct GroupState {
     /// reaches the second for the ordinary player — their lockout list is empty, every answer says
     /// so, nothing ever changes, and the button they should not be able to press stays live (1561).
     ///
-    /// The real client fires per PACKET, not per change. VERIFIED off the bytes: the handler at
+    /// The real client fires per PACKET, not per change. The handler at
     /// `0x49e070` takes `jbe 0x49e19d` (`0x49e0d8`) when the entry count is zero — straight past
     /// the parse loop to `mov ecx, 0x21b` (539 = `UPDATE_INSTANCE_INFO`) and the one
     /// `call FrameScript_SignalEvent 0x703e50` at `0x49e1a7`, which is the function's only exit
-    /// and the event's only fire site in the binary (`re/events/event-firesites.tsv`). The empty
-    /// answer signals exactly like a full one.
+    /// and the event's only fire site in the binary. The empty answer signals exactly like a full
+    /// one.
     pub saved_instances_answers: u32,
     /// A ready-check TICKET, not a flag: every `MSG_RAID_READY_CHECK` open bumps it, so the feed
     /// fires `READY_CHECK` on a counter edge and a second check while the first popup is still up
@@ -144,8 +146,8 @@ impl GroupState {
         // one, and a solo-leader group has an empty member list *with* a leader guid).
         let leaving = leader == 0;
         // Raid wording keys off whichever side of the transition was a raid. INTERIM (0440):
-        // the §5 pinned the party line's `groupType==0` gate; the raid twin's exact trigger
-        // wasn't walked.
+        // the party line's `groupType==0` gate is pinned; the raid twin's exact trigger is not
+        // known.
         let (added, removed) = if group_type == 1 || (leaving && self.group_type == 1) {
             ("ERR_RAID_MEMBER_ADDED_S", "ERR_RAID_MEMBER_REMOVED_S")
         } else {
@@ -162,7 +164,7 @@ impl GroupState {
             }
         }
         if leaving {
-            *self = GroupState::default();
+            self.leave_group();
             return lines;
         }
         // Our own party→raid conversion (or joining straight into a raid). INTERIM like the
@@ -172,13 +174,12 @@ impl GroupState {
         }
         // The OTHER direction clears the raid-target board. `0x4ba550` — sole caller `0x5e6ebb`,
         // inside `SMSG_GROUP_LIST 0x7d`'s raid-flag-CLEAR leg — `rep stosd`-zeroes all eight slots
-        // and refreshes every formerly-marked unit (decision 1820, wow-re
-        // `object-layer/scratch/party-group-wire.md`). Without it a raid→party conversion leaves
-        // stale marks on screen: the icons are drawn from this board, and nothing else clears it
-        // short of a `0x321` for each slot, which the server does not send.
+        // and refreshes every formerly-marked unit (decision 1820). Without it a raid→party
+        // conversion leaves stale marks on screen: the icons are drawn from this board, and
+        // nothing else clears it short of a `0x321` for each slot, which the server does not send.
         //
-        // A full disband needs no arm here — `leaving` above replaces the whole state, and
-        // `[u64; 8]::default()` is already the empty board. 1820 recorded this as "stale icons
+        // A full disband needs no arm here — `leaving` above resets every group fact
+        // ([`Self::leave_group`]), and the board is one. 1820 recorded this as "stale icons
         // after a disband", which was wider than the truth; the conversion is the real gap.
         if group_type != 1 && self.group_type == 1 {
             self.raid_targets = [0; 8];
@@ -252,8 +253,7 @@ impl GroupState {
         }
     }
 
-    /// `SMSG_PARTY_COMMAND_RESULT` — **the reference's own jump table, transcribed** (wow-re
-    /// `system/object-layer/scratch/party-command-result-law.md`, byte-verified §5).
+    /// `SMSG_PARTY_COMMAND_RESULT` — **the reference's own jump table, transcribed**.
     ///
     /// The handler `0x5e68b0` dispatches `dec eax; cmp eax,7; ja <silent>; jmp [4*eax+0x5e6a14]`,
     /// and each arm is one `CGGameUI::DisplayError(msgId)`. Returning the **message** rather than
@@ -393,6 +393,54 @@ impl GroupState {
             .map_or(0, |i| i as u8 + 1)
     }
 
+    /// The all-zero `SMSG_GROUP_LIST` — we are no longer in a group. Resets the **group facts**
+    /// and nothing else.
+    ///
+    /// This used to be `*self = GroupState::default()`, which is [`Self::clear_session`]'s job,
+    /// and it took the per-SESSION tickets down with the roster: the feed fires on edges of those
+    /// tickets, so every leave, kick or disband fired a `READY_CHECK` (a popup naming no leader,
+    /// and a 30 s request armed for a check nobody started) and an `UPDATE_INSTANCE_INFO` over an
+    /// emptied lockout list. In the reference `READY_CHECK` has one fire site, the
+    /// `MSG_RAID_READY_CHECK` open handler (decision 1989), and a lockout belongs to the character.
+    ///
+    /// **The destructure is exhaustive on purpose** — no `..`: a field added to [`GroupState`]
+    /// does not compile until someone decides here which side of that line it is on. The defaulted
+    /// reset that caused this bug classified every new field silently.
+    pub(super) fn leave_group(&mut self) {
+        let GroupState {
+            // Group facts: the roster, its side-state, the sandbox (the wire always wins).
+            in_group,
+            group_type,
+            own_flags,
+            members,
+            leader,
+            loot,
+            stats,
+            raid_targets,
+            test,
+            // An invite is an offer into a group we are not in yet; it is cleared with the group
+            // as it always was here (UNVERIFIED either way — vmangos sends invitees nothing on a
+            // disband, so the case needs a leave to race an invite popup).
+            pending_invite,
+            // Session tickets — the feed's edges. Kept; `clear_session` is where they die.
+            saved_instances: _,
+            saved_instances_answers: _,
+            ready_check: _,
+            ready_check_requests: _,
+            ready_check_answers: _,
+        } = self;
+        *in_group = false;
+        *group_type = 0;
+        *own_flags = 0;
+        members.clear();
+        *leader = 0;
+        *loot = None;
+        stats.clear();
+        *raid_targets = [0; 8];
+        *test = false;
+        *pending_invite = None;
+    }
+
     /// Session teardown (decision 0065's lifecycle): everything resets with the socket.
     pub fn clear_session(&mut self) {
         *self = GroupState::default();
@@ -489,6 +537,59 @@ mod tests {
         assert!(g.saved_instances.is_empty());
     }
 
+    /// **Leaving the group is not the socket dying.** The all-zero `SMSG_GROUP_LIST` clears the
+    /// roster — and ONLY the roster. The ready-check and saved-instance fields are per-session
+    /// tickets the feed fires events on edges of: resetting them here made every leave, kick or
+    /// disband look like a new `READY_CHECK` (a popup with no leader, and a stale 30 s request
+    /// armed) and a fresh `UPDATE_INSTANCE_INFO` carrying an emptied lockout list — a blank Raid
+    /// Info panel. In the reference `READY_CHECK` has one fire site, the `MSG_RAID_READY_CHECK`
+    /// open handler (decision 1989); a lockout is the character's, not the group's.
+    #[test]
+    fn leaving_the_group_keeps_the_session_tickets() {
+        let lockout = benilla_protocol::messages::RaidInstanceEntry {
+            map: 409,
+            reset: 86_400,
+            instance: 7,
+        };
+        let mut g = GroupState {
+            in_group: true,
+            leader: 0xA11CE,
+            members: vec![member("Alice", 0xA11CE)],
+            ..Default::default()
+        };
+        g.raid_targets[0] = 0xA11CE;
+        g.apply_ready_check_request(false);
+        g.apply_raid_instance_info(Vec::new());
+        g.apply_raid_instance_info(vec![lockout]);
+        assert_eq!((g.ready_check, g.ready_check_requests), (1, 1));
+        assert_eq!(g.saved_instances_answers, 2);
+
+        g.apply_list(0, 0, vec![], 0, None);
+
+        // The group facts are gone …
+        assert!(!g.in_group);
+        assert!(g.members.is_empty());
+        assert_eq!(g.leader, 0);
+        assert_eq!(g.raid_targets, [0; 8]);
+        // … the session's tickets are not: no edge for the feed to fire on.
+        assert_eq!(
+            (g.ready_check, g.ready_check_requests),
+            (1, 1),
+            "no READY_CHECK edge"
+        );
+        assert_eq!(g.saved_instances_answers, 2, "no UPDATE_INSTANCE_INFO edge");
+        assert_eq!(
+            g.saved_instances,
+            vec![lockout],
+            "the lockouts are the character's"
+        );
+
+        // The socket's end is still the one place they die.
+        g.clear_session();
+        assert_eq!((g.ready_check, g.saved_instances_answers), (0, 0));
+        assert!(g.saved_instances.is_empty());
+    }
+
     /// The ungated diff (0440 byte law): a FIRST roster prints joins for everyone already
     /// there; later rosters diff both ways.
     /// The open form's two arms (decision 1989): the leader's own echo neither prints nor pops;
@@ -784,7 +885,7 @@ mod tests {
     /// **The refusal table is the reference's, asserted by message id.**
     ///
     /// Each `result` must name the catalog row whose id the binary's own jump table pushes to
-    /// `DisplayError` (wow-re `party-command-result-law.md` §3, read out of the PE at `0x5e6a14`).
+    /// `DisplayError` (read out of the PE at `0x5e6a14`).
     /// Asserting the *id* rather than the sentence is the point, and this family is the reason:
     /// nothing about the displayed English distinguishes a right key from a wrong one here, and a
     /// plausible-looking `ERR_WRONG_FACTION` — which exists in neither `GlobalStrings.lua` nor the
diff --git a/crates/benilla-app/src/net/apply/group.rs b/crates/benilla-app/src/ui_party/net.rs
similarity index 71%
rename from crates/benilla-app/src/net/apply/group.rs
rename to crates/benilla-app/src/ui_party/net.rs
index 80ce811c..9edf3070 100644
--- a/crates/benilla-app/src/net/apply/group.rs
+++ b/crates/benilla-app/src/ui_party/net.rs
@@ -1,8 +1,10 @@
-//! The group/party arm bodies (decision 0434 §D2, superseded by 0440) for
-//! [`super::apply_net_updates`]'s dispatch match. [`GroupState`] mirrors the wire and names the
-//! **messages** its roster diff implies; these are the drain-side shims that put them on the
-//! shared by-key queue. Each `pub(super)` fn here is exactly one arm's body; the match at the call
-//! site stays the dispatcher, one call per arm.
+//! The group/party packet handlers (decision 0434 §D2, superseded by 0440; in the net handler
+//! table since 2321, moved out of the drain's group arm file). [`GroupState`] mirrors the wire and
+//! names the **messages** its roster diff implies; these are the shims that put them on the
+//! shared by-key queue. Two bodies here are not packet handlers but the object layer's hook on a
+//! roster member's stream-out ([`member_deactivated`], [`roster_deactivated`]); the drain's
+//! object arms still call them, and they become listeners on the object kinds once those are
+//! peeled.
 //!
 //! **They are message ids, not sentences** (decisions 2045/2054). The reference reaches all twelve
 //! through one `CGGameUI::DisplayError(msgId)`, and the catalog row that id names answers three
@@ -15,12 +17,184 @@ use benilla_protocol::messages::{
 };
 use bevy::prelude::*;
 
+use benilla_protocol::{SessionEvent, SessionEventKind};
+
+use super::GroupState;
 use crate::names::NameCache;
+use crate::net::{ClientCommand, GuidIndex, NetCommands, NetHandlerApp, ObjectStore, SelfGuid};
 use crate::ui_action::{UiError, UiErrorKeys};
-use crate::ui_party::GroupState;
 use crate::ui_quest::QuestGiver;
 
-use super::super::{ClientCommand, GuidIndex, NetCommands, ObjectStore, SelfGuid};
+/// Register the group handlers — called from [`super::UiPartyPlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::GroupInvite, on_invite)
+        .net_handler(K::GroupDecline, on_decline)
+        .net_handler(K::GroupUninvited, on_uninvited)
+        .net_handler(K::GroupLeaderChanged, on_leader_changed)
+        .net_handler(K::GroupDestroyed, on_destroyed)
+        .net_handler(K::GroupList, on_list)
+        .net_handler(K::PartyCommandResult, on_command_result)
+        .net_handler(K::PartyMemberStats, on_member_stats)
+        .net_handler(K::RaidTargetSet, on_raid_target)
+        .net_handler(K::RaidTargetList, on_raid_target)
+        .net_handler(K::ReadyCheckRequest, on_ready_check_request)
+        .net_handler(K::ReadyCheckAnswer, on_ready_check_answer)
+        .net_handler(K::RaidInstanceInfo, on_raid_instance_info)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_invite(
+    In(ev): In<SessionEvent>,
+    mut group: ResMut<GroupState>,
+    mut errors: ResMut<UiErrorKeys>,
+) {
+    if let SessionEvent::GroupInvite { inviter } = ev {
+        invited(&mut group, &mut errors, &inviter);
+    }
+}
+
+fn on_decline(
+    In(ev): In<SessionEvent>,
+    mut group: ResMut<GroupState>,
+    mut errors: ResMut<UiErrorKeys>,
+) {
+    if let SessionEvent::GroupDecline { name } = ev {
+        declined(&mut group, &mut errors, &name);
+    }
+}
+
+fn on_uninvited(
+    In(ev): In<SessionEvent>,
+    mut group: ResMut<GroupState>,
+    mut errors: ResMut<UiErrorKeys>,
+) {
+    if let SessionEvent::GroupUninvited = ev {
+        uninvited(&mut group, &mut errors);
+    }
+}
+
+fn on_leader_changed(
+    In(ev): In<SessionEvent>,
+    mut group: ResMut<GroupState>,
+    mut errors: ResMut<UiErrorKeys>,
+    self_guid: Res<SelfGuid>,
+    names: Res<NameCache>,
+    commands: Res<NetCommands>,
+) {
+    if let SessionEvent::GroupLeaderChanged { name } = ev {
+        leader_changed(
+            &mut group,
+            &mut errors,
+            &name,
+            &self_guid,
+            &names,
+            &commands,
+        );
+    }
+}
+
+fn on_destroyed(
+    In(ev): In<SessionEvent>,
+    mut group: ResMut<GroupState>,
+    mut errors: ResMut<UiErrorKeys>,
+) {
+    if let SessionEvent::GroupDestroyed = ev {
+        destroyed(&mut group, &mut errors);
+    }
+}
+
+fn on_list(
+    In(ev): In<SessionEvent>,
+    mut group: ResMut<GroupState>,
+    mut errors: ResMut<UiErrorKeys>,
+    mut quest: ResMut<QuestGiver>,
+    names: Res<NameCache>,
+    index: Res<GuidIndex>,
+    commands: Res<NetCommands>,
+) {
+    if let SessionEvent::GroupList {
+        group_type,
+        own_flags,
+        members,
+        leader,
+        loot,
+    } = ev
+    {
+        list(
+            &mut group,
+            &mut errors,
+            &mut quest,
+            group_type,
+            own_flags,
+            members,
+            leader,
+            loot,
+            &names,
+            &index,
+            &commands,
+        );
+    }
+}
+
+fn on_command_result(
+    In(ev): In<SessionEvent>,
+    mut group: ResMut<GroupState>,
+    mut errors: ResMut<UiErrorKeys>,
+) {
+    if let SessionEvent::PartyCommandResult {
+        operation,
+        member,
+        result,
+    } = ev
+    {
+        command_result(&mut group, &mut errors, operation, &member, result);
+    }
+}
+
+fn on_member_stats(In(ev): In<SessionEvent>, mut group: ResMut<GroupState>) {
+    if let SessionEvent::PartyMemberStats { guid, full, info } = ev {
+        group.apply_stats(guid, full, *info);
+    }
+}
+
+fn on_raid_target(In(ev): In<SessionEvent>, mut group: ResMut<GroupState>) {
+    match ev {
+        SessionEvent::RaidTargetSet { icon, guid } => group.apply_raid_target(icon, guid),
+        SessionEvent::RaidTargetList { entries } => group.apply_raid_target_list(&entries),
+        _ => {}
+    }
+}
+
+fn on_ready_check_request(
+    In(ev): In<SessionEvent>,
+    mut group: ResMut<GroupState>,
+    mut errors: ResMut<UiErrorKeys>,
+    self_guid: Res<SelfGuid>,
+) {
+    if let SessionEvent::ReadyCheckRequest = ev {
+        ready_check_request(&mut group, &mut errors, &self_guid);
+    }
+}
+
+fn on_ready_check_answer(In(ev): In<SessionEvent>, mut group: ResMut<GroupState>) {
+    if let SessionEvent::ReadyCheckAnswer { guid, ready } = ev {
+        group.apply_ready_check_answer(guid, ready != 0);
+    }
+}
+
+fn on_raid_instance_info(In(ev): In<SessionEvent>, mut group: ResMut<GroupState>) {
+    if let SessionEvent::RaidInstanceInfo { entries } = ev {
+        group.apply_raid_instance_info(entries);
+    }
+}
+
+/// The group dies with the socket. A listener on the session end
+/// (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut group: ResMut<GroupState>) {
+    group.clear_session();
+}
 
 /// Queue the messages a `GroupState::apply_*` named. `ui_action::feed_actions` resolves each key
 /// against the VM's own `GlobalStrings.lua` and puts the line on the surface its catalog row
@@ -32,38 +206,34 @@ fn push_group_lines(errors: &mut UiErrorKeys, lines: Vec<UiError>) {
 /// `MSG_RAID_READY_CHECK`, the open form (decision 1989): our own echo as leader takes the
 /// response-collection arm and prints nothing; as anyone else we print the leader's line and take
 /// the popup ticket. The leader test is the reference's guid compare (`0x4ba3a0`).
-pub(super) fn ready_check_request(
-    group: &mut GroupState,
-    errors: &mut UiErrorKeys,
-    self_guid: &SelfGuid,
-) {
+fn ready_check_request(group: &mut GroupState, errors: &mut UiErrorKeys, self_guid: &SelfGuid) {
     let we_lead = self_guid.0 == Some(group.leader);
     push_group_lines(errors, group.apply_ready_check_request(we_lead));
 }
 
 /// `SMSG_GROUP_INVITE` — someone asked us into their group.
-pub(super) fn invited(group: &mut GroupState, errors: &mut UiErrorKeys, inviter: &str) {
+fn invited(group: &mut GroupState, errors: &mut UiErrorKeys, inviter: &str) {
     push_group_lines(errors, group.apply_invited(inviter));
 }
 
 /// `SMSG_GROUP_DECLINE` — our invitee said no (sent to the inviter only).
-pub(super) fn declined(group: &mut GroupState, errors: &mut UiErrorKeys, name: &str) {
+fn declined(group: &mut GroupState, errors: &mut UiErrorKeys, name: &str) {
     push_group_lines(errors, group.apply_declined(name));
 }
 
 /// `SMSG_GROUP_UNINVITE` — we were kicked.
-pub(super) fn uninvited(group: &mut GroupState, errors: &mut UiErrorKeys) {
+fn uninvited(group: &mut GroupState, errors: &mut UiErrorKeys) {
     push_group_lines(errors, group.apply_uninvited());
 }
 
 /// `SMSG_GROUP_DESTROYED` — the group is gone outright.
-pub(super) fn destroyed(group: &mut GroupState, errors: &mut UiErrorKeys) {
+fn destroyed(group: &mut GroupState, errors: &mut UiErrorKeys) {
     push_group_lines(errors, group.apply_destroyed());
 }
 
 /// `SMSG_GROUP_SET_LEADER` — the line reads differently when the new leader is us, so the composer
 /// needs our own name. It is cache-seeded at login (`session::connected`), so this never asks.
-pub(super) fn leader_changed(
+fn leader_changed(
     group: &mut GroupState,
     errors: &mut UiErrorKeys,
     name: &str,
@@ -81,14 +251,14 @@ pub(super) fn leader_changed(
 /// shared-quest availability, so the questgiver sweep re-asks from here (0654).
 ///
 /// **A roster entry is a sighting** (decision 1564): every member guid is warmed into the
-/// [`NameCache`] here, the same ask-once discipline `net::apply::objects` applies the moment a unit
+/// [`NameCache`] here, the same ask-once discipline `net::objects` applies the moment a unit
 /// streams in. The roster wire carries a member's *name*, so this is not asked for the name — it is
 /// asked for the `(race, class, gender)` triple that rides the same answer, and which is the ONLY
 /// source of those three for a member we never see: their descriptor never arrives. Two surfaces
 /// read them and both were empty for an out-of-area member before this — the raid grid's class
 /// column (`ui_party::feed::raid_roster`, whose own-row twin of this hole 1549 §7 found live), and
 /// the party frame's 2D portrait stand-in (`portrait::temporary_portrait`, report B315).
-pub(super) fn list(
+fn list(
     group: &mut GroupState,
     errors: &mut UiErrorKeys,
     quest: &mut QuestGiver,
@@ -116,8 +286,7 @@ pub(super) fn list(
     quest.bump_reask();
 }
 
-/// **The GROUP_LIST slot writer's record leg** — `0x4e82d0` (VERIFIED wow-re
-/// `ui/scratch/party-oor-stats-and-portrait-law.md` §2.2), the second of the two places the
+/// **The GROUP_LIST slot writer's record leg** — `0x4e82d0`, the second of the two places the
 /// reference asks for a member's stats.
 ///
 /// Per member the writer has two legs, chosen on whether the member already had a record
@@ -154,9 +323,8 @@ fn seat_new_records(
 }
 
 /// **The despawn edge** — CGPlayer_C vtable slot 1 `0x5e9aa0`, which `0x464920` invokes on both
-/// `SMSG_DESTROY_OBJECT` and the `SMSG_UPDATE_OBJECT` OUT_OF_RANGE block (VERIFIED wow-re
-/// `object-layer/scratch/party-record-live-snapshot.md` §3, `ui/scratch/party-oor-stats-and-
-/// portrait-law.md` §2.1). A party or raid member's object is leaving the object manager, so:
+/// `SMSG_DESTROY_OBJECT` and the `SMSG_UPDATE_OBJECT` OUT_OF_RANGE block. A party or raid
+/// member's object is leaving the object manager, so:
 /// **snapshot its live descriptor into the roster record** (`0x5f0880`), then **ask the server for
 /// the member's stats** (`CMSG_REQUEST_PARTY_MEMBER_STATS`, `0x4e8646`), in that order and on that
 /// same instruction sequence.
@@ -170,7 +338,7 @@ fn seat_new_records(
 /// on the roster falls straight through; and a guid we hold **no object for** falls through too —
 /// the hook is a *virtual on the object*, so no object means it never ran, and a server that
 /// re-announces a stream-out we have already applied must not cost a packet.
-pub(super) fn member_deactivated(
+pub(crate) fn member_deactivated(
     guid: u64,
     group: &mut GroupState,
     store: Option<&ObjectStore>,
@@ -195,7 +363,7 @@ pub(super) fn member_deactivated(
 /// [`member_deactivated`] for **every** streamed roster member at once — the bulk teardown a
 /// cross-map transfer performs, where the reference destroys the same objects one at a time and
 /// runs the same hook on each.
-pub(super) fn roster_deactivated(
+pub(crate) fn roster_deactivated(
     group: &mut GroupState,
     index: &GuidIndex,
     stores: &Query<&mut ObjectStore>,
@@ -214,7 +382,7 @@ pub(super) fn roster_deactivated(
 }
 
 /// `SMSG_PARTY_COMMAND_RESULT` — the verdict on an invite/kick/leave we asked for.
-pub(super) fn command_result(
+fn command_result(
     group: &mut GroupState,
     errors: &mut crate::ui_action::UiErrorKeys,
     operation: u32,
@@ -223,8 +391,8 @@ pub(super) fn command_result(
 ) {
     // By KEY, not by sentence, and into the shared queue rather than straight into chat: the
     // catalog row decides the surface, so `result == 7` reaches the red `UIErrorsFrame` line while
-    // the other nine stay chat lines (wow-re `party-command-result-law.md`; decision 2035's
-    // shape). `None` is the reference's own silence — three inputs display nothing at all.
+    // the other nine stay chat lines (`0x496720`; decision 2035's shape). `None` is the
+    // reference's own silence — three inputs display nothing at all.
     errors
         .0
         .extend(group.apply_command_result(operation, member, result));
@@ -272,7 +440,7 @@ mod tests {
             &mut quest,
             0,
             0,
-            vec![member(leader, "Frostshake"), member(far, "Thalyn")],
+            vec![member(leader, "Aldwyn"), member(far, "Brisca")],
             leader,
             None,
             &names,
@@ -294,14 +462,14 @@ mod tests {
         );
 
         // The answer lands for one of them; the re-sent roster asks for neither.
-        names.insert_player(leader, "Frostshake".into(), Some((1, 4, 1)));
+        names.insert_player(leader, "Aldwyn".into(), Some((1, 4, 1)));
         list(
             &mut group,
             &mut errors,
             &mut quest,
             0,
             0,
-            vec![member(leader, "Frostshake"), member(far, "Thalyn")],
+            vec![member(leader, "Aldwyn"), member(far, "Brisca")],
             leader,
             None,
             &names,
@@ -343,8 +511,8 @@ mod tests {
         group
     }
 
-    /// **The despawn edge is where the numbers are kept** (wow-re `0b2a594a` §2.1/§2.3 — the
-    /// deactivate virtual `0x5e9aa0` snapshots `0x5f0880` and sends `0x27f`, in that order).
+    /// **The despawn edge is where the numbers are kept** (the deactivate virtual `0x5e9aa0`
+    /// snapshots `0x5f0880` and sends `0x27f`, in that order).
     ///
     /// Falsifier for the whole report: delete the snapshot and this member's record stays whatever
     /// the wire last said — which, for a member who has never had a stats packet, is nothing, and
@@ -355,7 +523,7 @@ mod tests {
         let (tx, rx) = crossbeam_channel::unbounded();
         let net = NetCommands(tx);
         let guid = 0x1234;
-        let mut group = grouped(&[member(guid, "Thalyn"), member(0x99, "Frostshake")]);
+        let mut group = grouped(&[member(guid, "Brisca"), member(0x99, "Aldwyn")]);
         let _ = asked(&rx); // the roster's own seat-time asks (they are unstreamed here)
 
         // A warrior: rage rides the wire ×10, and the record stores it raw exactly as the
@@ -397,7 +565,7 @@ mod tests {
     fn a_despawn_that_is_not_a_party_member_asks_nothing() {
         let (tx, rx) = crossbeam_channel::unbounded();
         let net = NetCommands(tx);
-        let mut group = grouped(&[member(0x1234, "Thalyn")]);
+        let mut group = grouped(&[member(0x1234, "Brisca")]);
         let _ = asked(&rx);
         // A live object, so only the roster gate can stop it.
         let store = ObjectStore(benilla_protocol::messages::ObjectFields::from_pairs(&[(
@@ -413,7 +581,7 @@ mod tests {
         assert!(asked(&rx).is_empty());
     }
 
-    /// **The roster seat** (`0x4e82d0`, §2.2): a member new to the roster gets the `1/1`
+    /// **The roster seat** (`0x4e82d0`): a member new to the roster gets the `1/1`
     /// placeholder, and is asked for only when we hold no object for them. A resync asks nothing —
     /// the gate the reference puts on `srcRec`, and the reason a busy group does not fire four
     /// queries per GROUP_LIST.
@@ -434,7 +602,7 @@ mod tests {
         let mut world = bevy::ecs::world::World::new();
         index.0.insert(near, world.spawn_empty().id());
 
-        let roster = vec![member(near, "Frostshake"), member(far, "Thalyn")];
+        let roster = vec![member(near, "Aldwyn"), member(far, "Brisca")];
         let mut send = |group: &mut GroupState, members: Vec<GroupMemberEntry>| {
             list(
                 group,
diff --git a/crates/benilla-app/src/ui_pass.rs b/crates/benilla-app/src/ui_pass.rs
index bef5e7f9..744f393b 100644
--- a/crates/benilla-app/src/ui_pass.rs
+++ b/crates/benilla-app/src/ui_pass.rs
@@ -61,8 +61,9 @@
 //!   non-rectangular-region case even after real scissor lands.
 //! - **Text.** `FontString`s render through `cosmic-text` per 0068 §2; nothing here rasterizes glyphs.
 //! - **Extraction from a widget arena.** Nothing yet *produces* [`UiQuad`]s from frames/anchors/strata —
-//!   that's the widget-arena milestone this pass is built ahead of. The `dev`-gated demo feeder below
-//!   fills [`UiQuads`] directly to prove the pass in isolation.
+//!   that's the widget-arena milestone this pass is built ahead of. (A `WOW_UI_DEMO` feeder once
+//!   filled [`UiQuads`] with synthetic strata to prove the pass in isolation; the widget engine has
+//!   been the producer since, and the feeder retired — 2335.)
 
 use bevy::asset::RenderAssetUsages;
 use bevy::camera::visibility::RenderLayers;
@@ -79,8 +80,6 @@ use bevy::shader::ShaderRef;
 use bevy::sprite_render::{Material2d, Material2dKey, Material2dPlugin};
 use bevy::window::PrimaryWindow;
 
-use benilla_assets::{AssetSet, WorldAssets};
-
 /// Per-corner UVs for a quad: one explicit `(u,v)` sample per **screen** corner, in the
 /// [`Run::push_quad`] winding — `[top-left, top-right, bottom-right, bottom-left]`. Deliberately four
 /// independent pairs, **not** a `(min,max)` rect, for two reasons that a 2-corner rect can't serve:
@@ -203,11 +202,11 @@ pub(crate) struct UiQuad {
     ///
     /// The reference's minimap tile draw sets EGxBlend **1**, whose applicator `glDisable`s
     /// blending outright, and the `SetRenderState` id-7→id-8 cascade then arms
-    /// `glAlphaFunc(GL_GEQUAL, 0.87843144)` (`.data 0x85ad20[1] = 224`; wow-re
-    /// `wmo-interior-minimap-composite.md`). Blending those tiles instead leaves `(1−a)(1−b)` of
-    /// the black clear at EVERY boundary where two group tiles meet — up to 25% black where the
-    /// two filtered edges are complementary — which is B141's "odd black lines" (they recoloured
-    /// with the backing quad, which is how they were caught). Splits the batch run.
+    /// `glAlphaFunc(GL_GEQUAL, 0.87843144)` (`.data 0x85ad20[1] = 224`). Blending those tiles
+    /// instead leaves `(1−a)(1−b)` of the black clear at EVERY boundary where two group tiles meet
+    /// — up to 25% black where the two filtered edges are complementary — which is B141's "odd
+    /// black lines" (they recoloured with the backing quad, which is how they were caught). Splits
+    /// the batch run.
     pub alpha_test: Option<f32>,
     /// **The UV window this quad may sample**, already inset by half a texel — `None` = the
     /// sampler's own `ClampToEdge` is the whole story (decision 1608).
@@ -287,9 +286,8 @@ impl Default for UiQuad {
 
 /// The pass's one input resource, two lanes with distinct change protocols:
 ///
-/// - [`Self::quads`] — the BASE lane, owned by a wholesale producer (the widget arena's extract;
-///   the dev demo feeder): replaced in full, and the producer sets [`Self::dirty`] only when the
-///   new content differs.
+/// - [`Self::quads`] — the BASE lane, owned by a wholesale producer (the widget arena's extract):
+///   replaced in full, and the producer sets [`Self::dirty`] only when the new content differs.
 /// - [`Self::overlays`] — the APPEND lane ([`UiQuadAppend`]: the minimap fill, V-plates, combat
 ///   text): cleared at the top of the append window ([`clear_ui_overlays`]) and re-emitted every
 ///   frame; [`rebuild_ui_mesh`] itself diffs it against last frame's. Appenders never touch
@@ -434,12 +432,11 @@ pub(crate) struct UiQuadMaterial {
 /// on Intel's DX12 driver (2236).
 ///
 /// One BYTE per channel, `×255 + 0.5`: exactly how the reference packs a vertex colour
-/// (`CImVector`; `SetVertexColor` at `0x79abd0`, the frame-alpha fold at `0x77fac0` in bytes —
-/// wow-re `system/ui/scratch/texture-color-composition.md`), so this is the precision the real
-/// client draws with, not a step down from it. Stored COMPLEMENTED: an entity with no `MeshTag`
-/// reads 0 in bevy's extract, and the complement makes 0 unpack to opaque white — untinted —
-/// so a Mesh2d that draws with this material and never asked for a tint (the minimap's
-/// interior tiles) is right without knowing this exists.
+/// (`CImVector`; `SetVertexColor` at `0x79abd0`, the frame-alpha fold at `0x77fac0` in bytes), so
+/// this is the precision the real client draws with, not a step down from it. Stored COMPLEMENTED:
+/// an entity with no `MeshTag` reads 0 in bevy's extract, and the complement makes 0 unpack to
+/// opaque white — untinted — so a Mesh2d that draws with this material and never asked for a tint
+/// (the minimap's interior tiles) is right without knowing this exists.
 fn tint_tag(color: [f32; 4]) -> u32 {
     let byte = |v: f32| {
         // Round half up on a clamped value — `0x40a2b0`'s `×255.0 + 0.5` then truncate; the
@@ -555,9 +552,8 @@ pub(crate) struct UiQuadAppend;
 /// Project a world point for a world-anchored overlay, **with the reference projector's own accept
 /// verdict** — `None` means "this one does not draw", and the caller must honour it.
 ///
-/// `0x483ee0` returns a boolean (wow-re `object-layer/scratch/nameplate-offscreen-cull.md`,
-/// §5-VERIFIED 2026-08-15). It rejects a point behind the near plane (`483f7a`) **and** a point
-/// outside the viewport — the four tests at `484075`/`484086`/`484096`/`4840a6`, against the
+/// `0x483ee0` returns a boolean. It rejects a point behind the near plane (`483f7a`) **and** a
+/// point outside the viewport — the four tests at `484075`/`484086`/`484096`/`4840a6`, against the
 /// **WorldFrame**'s own region (`[0xb4b2bc]`, mirrored ÷G44/÷G48 at `0x483970`), so the accept
 /// region is exactly the viewport, inclusive. Both plate and worldtext callers **destroy** the
 /// thing they were about to place when it comes back false.
@@ -623,27 +619,9 @@ impl Plugin for PlayerUiPlugin {
             .add_systems(Update, clear_ui_overlays.before(UiQuadAppend))
             .add_systems(Update, rebuild_ui_mesh.after(UiQuadAppend))
             .add_systems(Last, count_material_events);
-
-        // Dev-only demo feeder (mirrors the repo's env-var dev-instrument gating — e.g. `$WOW_CAPTURE`,
-        // `$WOW_TILE_RADIUS` — since the compile-time `dev` cargo feature decision 0026 sets as the
-        // eventual seam isn't built yet; see `demo_enabled`'s doc comment). Runs once at Startup, after
-        // the asset chain opens so it can load a real BLP through `WorldAssets::sprite_texture`.
-        if demo_enabled() {
-            app.add_systems(Startup, seed_demo_quads.after(AssetSet::Open));
-        }
     }
 }
 
-/// `$WOW_UI_DEMO=1` fills [`UiQuads`] once at startup with synthetic content proving the sort, the
-/// texture-batching/ordering story, and the CPU clip. Same env-var-gated-instrument idiom as
-/// `capture.rs`'s `$WOW_CAPTURE` and `assets::open_world_assets`'s `$WOW_TILE_RADIUS`/`$WOW_TEX_TILES`
-/// — decision 0026 phase 1 (a compile-time `dev` cargo feature) is recorded as the target seam but not
-/// yet built (0026 §4: "phased, not built now"), so today's instrument-gating convention across the
-/// codebase is a runtime env-var check, not `#[cfg(feature = "dev")]`.
-fn demo_enabled() -> bool {
-    std::env::var("WOW_UI_DEMO").as_deref() == Ok("1")
-}
-
 /// A full-window overlay camera that composites the player-UI quad pass above the 3D world and below
 /// the egui dev overlays. Mirrors `debug_panel::spawn_egui_camera`'s pattern (own render layer, higher
 /// order, alpha-blend `Write` output, no clear) — see the module doc for the order arbitration.
@@ -1611,89 +1589,6 @@ fn rebuild_ui_mesh(
     }
 }
 
-/// Deliberately-overlapping synthetic content proving the sort: 5 z strata × 40 quads each, offset both
-/// within a stratum (neighbours overlap 35px) and across strata (each stratum offset 20px from the
-/// last, so a later, higher-`z_key` stratum's field visibly paints over the previous one's — the actual
-/// thing this pass exists to get right). Plus one real-BLP-textured quad and one CPU-clipped quad,
-/// both given the highest z_keys — see the module doc: this ordering is what makes the shared "white"
-/// texture identity get split into two separate runs (the icon quad sits between them in z_key).
-const STRATA: usize = 5;
-const PER_STRATUM: usize = 40;
-const QUAD_SIZE: f32 = 80.0;
-const COLS: usize = 10;
-
-fn strata_color(s: usize) -> [f32; 4] {
-    // Red → orange → yellow → green → blue, alpha < 1 so the overlaps are visibly additive-ish
-    // (provable by eye: a later stratum's quad should read as a *blend* over the earlier one where
-    // clipped by nothing else, and fully opaque-looking where nothing underlies it).
-    const COLORS: [[f32; 3]; STRATA] = [
-        [0.85, 0.15, 0.15],
-        [0.90, 0.55, 0.10],
-        [0.85, 0.80, 0.10],
-        [0.15, 0.75, 0.25],
-        [0.15, 0.45, 0.90],
-    ];
-    let c = COLORS[s % STRATA];
-    [c[0], c[1], c[2], 0.85]
-}
-
-fn seed_demo_quads(
-    mut quads: ResMut<UiQuads>,
-    world_assets: Option<ResMut<WorldAssets>>,
-    mut images: ResMut<Assets<Image>>,
-) {
-    let mut out = Vec::with_capacity(STRATA * PER_STRATUM + 2);
-
-    for s in 0..STRATA {
-        let stratum_offset = s as f32 * 20.0;
-        for i in 0..PER_STRATUM {
-            let (col, row) = (i % COLS, i / COLS);
-            let x = 40.0 + stratum_offset + col as f32 * 45.0;
-            let y = 40.0 + stratum_offset + row as f32 * 45.0;
-            out.push(UiQuad {
-                rect: Rect::new(x, y, x + QUAD_SIZE, y + QUAD_SIZE),
-                z_key: (s as u64) * 1000 + i as u64,
-                color: strata_color(s),
-                ..default()
-            });
-        }
-    }
-
-    // Real BLP through the same UI-art path the loading screen uses (`sprite_texture`: sRGB, clamp,
-    // no mip chain — one texture mapped to one quad, not tiling world art).
-    if let Some(mut assets) = world_assets {
-        if let Some(icon) =
-            assets.sprite_texture("Interface\\Icons\\INV_Misc_QuestionMark.blp", &mut images)
-        {
-            out.push(UiQuad {
-                rect: Rect::new(560.0, 40.0, 560.0 + 64.0, 40.0 + 64.0),
-                z_key: (STRATA as u64) * 1000 + 500,
-                texture: Some(icon),
-                ..default()
-            });
-        }
-    }
-
-    // CPU-clip demo: a 160×160 quad clipped to its left half — proves the intersect + UV-reprojection
-    // path (not just a quad that already happened to fit).
-    let clip_rect = Rect::new(700.0, 40.0, 700.0 + 160.0, 40.0 + 160.0);
-    out.push(UiQuad {
-        rect: clip_rect,
-        z_key: (STRATA as u64) * 1000 + 600,
-        color: [0.2, 0.8, 1.0, 1.0],
-        clip: Some(Rect::new(
-            clip_rect.min.x,
-            clip_rect.min.y,
-            clip_rect.min.x + 80.0,
-            clip_rect.max.y,
-        )),
-        ..default()
-    });
-
-    quads.quads = out;
-    quads.dirty = true;
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1942,7 +1837,7 @@ mod tests {
     }
 
     /// **The tag is the reference's byte colour, complemented.** `SetVertexColor` quantises
-    /// `×255 + 0.5` into one byte per channel (wow-re `texture-color-composition.md`), and the
+    /// `×255 + 0.5` into one byte per channel (`0x79abd0`), and the
     /// complement is what makes bevy's untagged 0 read as opaque white (the minimap's interior
     /// tiles never set one).
     #[test]
@@ -2116,7 +2011,7 @@ mod tests {
     }
 
     // A rotated backdrop TOP-edge UV (atlas-u tied to screen-Y, atlas-v to screen-X reversed —
-    // backdrop-mechanism.md §3): clipping to the left half must reproject the *v* axis (screen-X),
+    // `0x77f0c0`): clipping to the left half must reproject the *v* axis (screen-X),
     // leaving *u* (screen-Y) untouched. This is the case the old separable-lerp clip could not do
     // and the four-corner bilinear must.
     #[test]
diff --git a/crates/benilla-app/src/ui_pet/bar.rs b/crates/benilla-app/src/ui_pet/bar.rs
index 7610d1de..10ff729c 100644
--- a/crates/benilla-app/src/ui_pet/bar.rs
+++ b/crates/benilla-app/src/ui_pet/bar.rs
@@ -23,9 +23,9 @@ use crate::ui_action::Spells;
 use super::drain::UNIT_FLAG_POSSESSED;
 use super::PetBar;
 
-/// `GetPetActionsUsable()` — may the bar be used at all (wow-re §4, the predicate `0x4bcf70`).
+/// `GetPetActionsUsable()` — may the bar be used at all (the predicate `0x4bcf70`).
 ///
-/// benilla's earlier reading — "the enabled-flags byte's `0x8`" — was REFUTED by the RE as the
+/// benilla's earlier reading — "the enabled-flags byte's `0x8`" — was REFUTED as the
 /// *whole* answer, but it survives as one of the seven steps: the client tests bit 27 of the state
 /// dword, which is that same byte's `0x8` (see `PET_STATE_BAR_DISABLED`). The step it was missing
 /// is the pet's own crowd-control state — a **stunned, confused or feared** pet cannot be ordered,
@@ -139,7 +139,7 @@ pub(super) fn slot_paint(
         // - the compare is against the UNMASKED `state >> 8` (`PetSpells::command_state`'s own
         //   note), so a disabled bar puts every command button out;
         // - ATTACK gets the extra clause — and it is the *only* thing that can light ATTACK,
-        //   because the command byte is never written for it (§10.1).
+        //   because the command byte is never written for it (`0x4bc960`).
         //
         // So whether Attack ever appears lit is entirely a question about [`PetBar::attacking`],
         // and the answer for a pet bar is **never**: that latch is the possess bar's, gated on
@@ -165,7 +165,7 @@ pub(super) fn slot_paint(
         .flatten()
     {
         // The reaction compare's left side is forced to Passive when the bar is disabled
-        // (wow-re §2.2, `0x4bde3c`): a pet that cannot be ordered reads as Passive rather than
+        // (`0x4bde3c`): a pet that cannot be ordered reads as Passive rather than
         // keeping the mode light it had, which is the honest thing for it to say.
         let showing = if bar.bar_disabled() {
             benilla_protocol::messages::PET_REACT_PASSIVE
@@ -196,7 +196,7 @@ pub(super) fn slot_paint(
     PetActionView {
         name: Some(spell.name.clone()),
         subtext: spell.rank.clone(),
-        // THE ICON SWAP (decision 1007, wow-re §2.1 `0x4bdd2f`/`0x4bdd38`/`0x4bdd77`): a spell the
+        // THE ICON SWAP (decision 1007, `0x4bdd2f`/`0x4bdd38`/`0x4bdd77`): a spell the
         // pet is currently running draws its record's `ActiveIconID` instead of its `SpellIconID`.
         // Falling back to `icon` here would be wrong — the reference looks up whichever id the
         // predicate chose and pushes **nil** if that lookup fails (`0x4bdd50`), so an unresolvable
@@ -209,17 +209,16 @@ pub(super) fn slot_paint(
         },
         is_token: false,
         spell_id: Some(action),
-        // A spell slot NEVER reports isActive — VERIFIED nil on every path (wow-re §2.1, pushed
-        // at `0x4bdd5e`), which retires 0982's INTERIM. `isActive` is exclusively a token
-        // concept and `autoCast*` exclusively a spell one; the two halves of the signature never
-        // overlap (§2.5 quirk 3).
+        // A spell slot NEVER reports isActive — nil on every path (pushed at `0x4bdd5e`), which
+        // retires 0982's INTERIM. `isActive` is exclusively a token concept and `autoCast*`
+        // exclusively a spell one; the two halves of the signature never overlap (`0x4bdc50`).
         //
         // "The pet is running this spell" is expressed by the icon above, not by this flag — which
         // is why 0988's hole closes without this line changing.
         active: false,
-        // Autocast is bits 31/30 of the word, not the type byte (wow-re §2.1) — and both are
-        // additionally gated on the spell resolving in `Spell.dbc`, which the early return above
-        // has already enforced by the time we get here.
+        // Autocast is bits 31/30 of the word, not the type byte (`0x4bdd65`/`0x4bdda4`) — and both
+        // are additionally gated on the spell resolving in `Spell.dbc`, which the early return
+        // above has already enforced by the time we get here.
         autocast_allowed: entry.autocast_allowed(),
         autocast_enabled: entry.autocast_on(),
         attack_active: false,
@@ -229,9 +228,8 @@ pub(super) fn slot_paint(
     }
 }
 
-/// The pet spell slot that is **showing active** — the reference's `0x4bcea0` (wow-re
-/// `ui/scratch/pet-action-bar-api.md` §2.1), returning the spell id when it holds so the one
-/// answer can drive both of its consumers. Decision 1007.
+/// The pet spell slot that is **showing active** — the reference's `0x4bcea0`, returning the spell
+/// id when it holds so the one answer can drive both of its consumers. Decision 1007.
 ///
 /// It is not a new predicate: `0x4bcea0` is the *pet-side compiled twin* of the player's
 /// `0x4e55f0`, which we already carry as [`crate::ui_action::toggle::active_action_toggle`] — same
@@ -260,10 +258,10 @@ pub(super) fn active_aura_press(
 /// of the bar and `PET_BAR_UPDATE_COOLDOWN` on a change of its cooldowns alone.
 ///
 /// The reference fires `PET_BAR_UPDATE` from nine sites, each right after a state change, and
-/// `PET_BAR_UPDATE_COOLDOWN` from the cooldown subsystem when the PET bank mutates (wow-re
-/// `pet-action-bar-api.md` §9). Diffing the pushed state is the same edge from the other side:
-/// the slots' content and usability are the bar's, the ten triples are the bank's. `UNIT_PET` is
-/// `feed_pet_unit`'s; `UNIT_FLAGS`/`UNIT_AURA` for `"pet"` are the unit feed's.
+/// `PET_BAR_UPDATE_COOLDOWN` from the cooldown subsystem when the PET bank mutates (`0x6e2e8e`).
+/// Diffing the pushed state is the same edge from the other side: the slots' content and usability
+/// are the bar's, the ten triples are the bank's. `UNIT_PET` is `feed_pet_unit`'s;
+/// `UNIT_FLAGS`/`UNIT_AURA` for `"pet"` are the unit feed's.
 pub(super) fn feed_pet_bar(
     script: Option<NonSendMut<UiScript>>,
     bar: Res<PetBar>,
diff --git a/crates/benilla-app/src/ui_pet/drain.rs b/crates/benilla-app/src/ui_pet/drain.rs
index 300c4ab8..0481c980 100644
--- a/crates/benilla-app/src/ui_pet/drain.rs
+++ b/crates/benilla-app/src/ui_pet/drain.rs
@@ -114,7 +114,7 @@ pub(super) fn drain_pet_actions(
         )
         .collect();
     for (slot, entry) in presses {
-        // The spell arm's early exit (wow-re §10.1, `0x4bd240`–`0x4bd2ad`): a press on a spell the
+        // The spell arm's early exit (`0x4bd240`–`0x4bd2ad`): a press on a spell the
         // pet is already running takes the aura OFF and **returns** — `CMSG_PET_ACTION` never
         // leaves, so it is a cancel, not a re-cast. Nothing is latched locally either: the icon
         // goes back when the pet's `UNIT_FIELD_AURA` says the aura is gone, which is the honest
@@ -172,17 +172,13 @@ pub(super) fn drain_pet_actions(
         });
     }
     for slot in toggles {
-        let Some(entry) = slot_entry(&bar, slot).filter(|e| e.autocast_allowed()) else {
+        let Some(flipped) = toggle_slot_autocast(&mut bar, slot) else {
             continue;
         };
-        // The client flips bit 30 in the slot word IN PLACE and sends the whole new word — it is
-        // not a "set autocast to X for spell Y" verb (wow-re §10.2, `0x4bcbff`/`0x4bcc17`). The
-        // server reads the direction back out of the type byte it arrives in.
-        let flipped = entry.with_autocast(!entry.autocast_on());
         debug!(
             "ui_pet: autocast {} for spell {} (slot {slot})",
             flipped.autocast_on(),
-            entry.action()
+            flipped.action()
         );
         let _ = commands.0.send(ClientCommand::PetSetAction {
             pet_guid,
@@ -191,9 +187,6 @@ pub(super) fn drain_pet_actions(
             // `slot_entry` already rejected 0.
             entries: vec![(slot - 1, flipped.packed)],
         });
-        if let Some(e) = slot_entry_mut(&mut bar, slot) {
-            *e = flipped;
-        }
     }
     for _ in 0..stops {
         if stop_pet_attack(&mut bar, &commands) {
@@ -218,6 +211,38 @@ pub(super) fn drain_pet_actions(
     }
 }
 
+/// `TogglePetAutocast`'s local half, `0x4bcbb0` — flip the slot's autocast bit and write it back,
+/// returning the new word for the send, or `None` when the reference no-ops silently (a slot out
+/// of range, or a word that is not autocast-ALLOWED, bit 31 — `0x4bcbf1`).
+///
+/// The client flips bit 30 in the slot word IN PLACE and sends the whole new word — it is not a
+/// "set autocast to X for spell Y" verb (`0x4bcbff`/`0x4bcc17`). The server reads the
+/// direction back out of the type byte it arrives in.
+///
+/// Then `0x4bcc19` calls `0x4bd190(&bar[slot])` — the propagation into the **spellbook**: for a
+/// spell-type slot (type 1), scan the raw pet-spell array **backwards** for the entry equal to the
+/// slot under `& 0x3FFFFFFF` and copy the slot's FULL word into it. The pet book renders from that
+/// array, so without the copy a bar toggle left the Pet tab's ring stale until the next
+/// `SMSG_PET_SPELLS`. The book→bar direction is `ui_pet_book::flip_autocast` (decision 1032).
+pub(super) fn toggle_slot_autocast(bar: &mut PetBar, slot: u32) -> Option<PetActionEntry> {
+    let entry = slot_entry(bar, slot).filter(|e| e.autocast_allowed())?;
+    let flipped = entry.with_autocast(!entry.autocast_on());
+    *slot_entry_mut(bar, slot)? = flipped;
+    if flipped.kind() == 1 {
+        let key = flipped.packed & 0x3FFF_FFFF;
+        if let Some(book) = bar
+            .spells
+            .spells
+            .iter_mut()
+            .rev()
+            .find(|w| w.packed & 0x3FFF_FFFF == key)
+        {
+            *book = flipped;
+        }
+    }
+    Some(flipped)
+}
+
 /// `PetStopAttack`'s **core**, `0x4bd650` — call the pet off, and the only thing besides a new pet
 /// that puts the Attack button out.
 ///
@@ -384,7 +409,7 @@ pub(super) fn commit_press(
 ///   command, which is also the proof that bit 27 is server-owned: no client path writes it.
 ///
 /// **Only STAY and FOLLOW reach the command write.** The binary's type-7 arm gates it on
-/// `action <= 1` (§10.1): DISMISS (3) falls straight through, and ATTACK (2) leaves down the
+/// `action <= 1` (`0x4bd3b1`): DISMISS (3) falls straight through, and ATTACK (2) leaves down the
 /// validation chain that ends at `[0xb714b0] = 1` (`0x4bd42e`) — the attack latch, never the
 /// command byte. The distinction is the difference between a mode and an order: Stay and Follow
 /// are what the pet is *doing until told otherwise*, and they stay lit because `isActive`'s state
diff --git a/crates/benilla-app/src/ui_pet/menu.rs b/crates/benilla-app/src/ui_pet/menu.rs
index c9525fb9..2242c07a 100644
--- a/crates/benilla-app/src/ui_pet/menu.rs
+++ b/crates/benilla-app/src/ui_pet/menu.rs
@@ -7,8 +7,7 @@
 //! warlock's demon — and the row a player sees is the whole of the difference the client draws
 //! between "give this pet up forever" and "send this summon away".
 //!
-//! **The predicates are VERIFIED at the bytes** (wow-re `ui/scratch/pet-action-bar-api.md` §11c,
-//! carved for this build). `0x4be500` and `0x4be580` are byte-identical but for three dwords:
+//! **The predicates** `0x4be500` and `0x4be580` are byte-identical but for three dwords:
 //! resolve `[0xb714a0]`, check the pet's `UNIT_FIELD_SUMMONEDBY` against the local player, then test
 //! **one byte of `UNIT_FIELD_FLAGS`** — `[pet+0x110]+0xa0`, dword 46 — with mask `0x20` for abandon
 //! (`0x4be544`) and `0x10` for rename (`0x4be5c4`). Each returns exactly one value on every path: a
@@ -16,12 +15,11 @@
 //!
 //! **The `UNIT_FIELD_BYTES_2` byte-2 layout everybody remembers is REFUTED here** — that is the
 //! TBC+ home of these bits, its record is dword 164, and neither predicate touches it. This is the
-//! shape decision 0988 warns about, and it was one carve away from being built wrong: benilla's own
+//! shape decision 0988 warns about, and it was nearly built wrong: benilla's own
 //! queue had recorded the TBC guess, off a field that is always zero on this server.
 //!
-//! **The two give-up verbs are NOT one opcode**, which is the correction that made carving them
-//! worth it (the seam's two counts, kept apart on principle, are what made the fold a two-line
-//! change):
+//! **The two give-up verbs are NOT one opcode** (the seam's two counts, kept apart on principle,
+//! are what made the fold a two-line change):
 //!
 //! - `PetAbandon 0x4be4c0` → `0x4bd740` sends **`CMSG_PET_ABANDON` 0x176** `{u64 petGuid}`.
 //! - `PetDismiss 0x4be4d0` → `0x4bd6e0` **opens no packet at all**. It stages the packed slot word
@@ -45,9 +43,9 @@ use super::{PetBar, PetUnit};
 /// `UNIT_FIELD_FLAGS` bit 4 — `UNIT_FLAG_PET_RENAME`, `0x4be5c4`'s mask. Set on a tamed hunter pet
 /// that has never been renamed.
 ///
-/// **One-shot, and server-side only.** wow-re's census of field-view reads of `[+0x110]+0xa0` found
-/// exactly three sites testing these two masks — the two predicates and the rename sender's own
-/// re-check — and **no writer anywhere in `.text`**. Nothing client-side clears this; the row
+/// **One-shot, and server-side only.** Of the field-view reads of `[+0x110]+0xa0`, exactly three
+/// test these two masks — the two predicates and the rename sender's own re-check (`0x4bd8b5`) —
+/// and **no writer exists anywhere in `.text`**. Nothing client-side clears this; the row
 /// disappears because the server re-streams the field and `UnitPopup` re-evaluates when the menu is
 /// next built. There is no event to listen for and none is needed.
 const UNIT_FLAG_PET_RENAME: u32 = 0x0000_0010;
@@ -56,7 +54,7 @@ const UNIT_FLAG_PET_RENAME: u32 = 0x0000_0010;
 const UNIT_FLAG_PET_ABANDON: u32 = 0x0000_0020;
 
 /// The client's own silent cap on a pet name — `0x64a7f0(dst, 0x50, "%s", name)` in the rename
-/// sender, i.e. 79 characters plus the terminator (wow-re §11c).
+/// sender `0x4bd840`, i.e. 79 characters plus the terminator.
 ///
 /// It is **not** the 12 everyone knows: that is `RENAME_PET`'s `maxLetters` in FrameXML, a
 /// different layer with a different job. This one is the last thing between the Lua and the wire,
diff --git a/crates/benilla-app/src/ui_pet/mod.rs b/crates/benilla-app/src/ui_pet/mod.rs
index 8be067d2..f97623e2 100644
--- a/crates/benilla-app/src/ui_pet/mod.rs
+++ b/crates/benilla-app/src/ui_pet/mod.rs
@@ -41,14 +41,15 @@ use bevy::prelude::*;
 
 use benilla_protocol::messages::PetSpells;
 
-use crate::cooldowns::Cooldowns;
 use crate::net::{GuidIndex, ObjectStore};
+use crate::spell::Cooldowns;
 use crate::ui_script::UiInput;
 use crate::ui_unit::UnitFeed;
 
 mod bar;
 mod drain;
 mod menu;
+mod net;
 mod unit;
 
 use bar::feed_pet_bar;
@@ -64,6 +65,8 @@ mod tests;
 ///
 /// `spells.pet_guid == 0` is "there is no pet bar", and it is the single test: the teardown packet
 /// carries exactly that and nothing else.
+///
+/// The session end resets it the same way (`net::on_session_end`): a dropped socket sends no teardown.
 #[derive(Resource, Default)]
 pub(crate) struct PetBar {
     /// The last `SMSG_PET_SPELLS` in full, with `SMSG_PET_MODE`'s state edits folded in.
@@ -75,7 +78,7 @@ pub(crate) struct PetBar {
     /// the pet's guid.
     pub(crate) cooldowns: Cooldowns,
     /// **"The possessed unit is attacking"** — the client's own `[0xb714b0]`, a purely local latch
-    /// with no field behind it anywhere (wow-re §1), and **the possess bar's, not the pet bar's**.
+    /// with no field behind it anywhere, and **the possess bar's, not the pet bar's**.
     ///
     /// It is `IsPetAttackActive` entire, and `GetPetActionInfo`'s COMMAND branch ORs it into
     /// `isActive` for action 2 (`0x4bdf16`–`0x4bdf22`), so it is also the only thing that can ever
@@ -90,7 +93,7 @@ pub(crate) struct PetBar {
     /// the **old-target clear `0x493910` at `0x493a18`** ([`pet_stop_on_old_target_clear`]), which
     /// every selection writer runs.
     ///
-    /// benilla read this off the pet's streamed `UNIT_FIELD_TARGET` until the RE landed. That is a
+    /// benilla once read this off the pet's streamed `UNIT_FIELD_TARGET`. That is a
     /// different question with a different answer: a defensive pet that retaliates on its own has
     /// a target the player never ordered, and the reference does not light the Attack button for
     /// it either.
@@ -129,7 +132,7 @@ pub(crate) struct PetBar {
 
 impl PetBar {
     /// `PetHasActionBar()` — is there a bar at all. The client's own gate is exactly this, a
-    /// nonzero cached pet guid: no alive check, no control check (wow-re §3).
+    /// nonzero cached pet guid: no alive check, no control check (`0x4bdc20`).
     pub(crate) fn has_bar(&self) -> bool {
         self.spells.pet_guid != 0
     }
@@ -139,6 +142,7 @@ pub(crate) struct UiPetPlugin;
 
 impl Plugin for UiPetPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<PetBar>().add_systems(
             Update,
             (
diff --git a/crates/benilla-app/src/net/apply/pet.rs b/crates/benilla-app/src/ui_pet/net.rs
similarity index 81%
rename from crates/benilla-app/src/net/apply/pet.rs
rename to crates/benilla-app/src/ui_pet/net.rs
index 2de8dcb1..6a78ba8f 100644
--- a/crates/benilla-app/src/net/apply/pet.rs
+++ b/crates/benilla-app/src/ui_pet/net.rs
@@ -1,9 +1,11 @@
-//! The pet bar's wire arms (decisions 0982, 0988) — `SMSG_PET_SPELLS`, `SMSG_PET_MODE`,
-//! `SMSG_PET_ACTION_FEEDBACK`, `SMSG_PET_CAST_FAILED` folded into [`crate::ui_pet::PetBar`].
+//! The pet's packet handlers (decisions 0982, 0988, 2039; in the net handler table since 2321,
+//! moved out of the drain's pet arm file) — `SMSG_PET_SPELLS`, `SMSG_PET_MODE`,
+//! `SMSG_PET_ACTION_FEEDBACK`, `SMSG_PET_CAST_FAILED` folded into [`PetBar`], the three
+//! pet-feedback packets and the pet's voice.
 //!
 //! The whole file is short because `SMSG_PET_SPELLS` is not a delta — it **is** the bar, so
 //! applying it is a replace. These four arms own the bar's CONTENTS; its lit state is
-//! [`crate::ui_pet`]'s, latched on the press because the server never answers one (that file's
+//! [`super`]'s, latched on the press because the server never answers one (that file's
 //! module doc has the why). The only state this file writes is what actually arrives on the wire.
 //!
 //! The two refusal arms share the player's red-line **queues** — one drain, one sink, one
@@ -21,12 +23,93 @@ use std::time::Instant;
 use bevy::prelude::*;
 
 use benilla_protocol::messages::{PetMode, PetSpells};
+use benilla_protocol::{SessionEvent, SessionEventKind};
 
 use benilla_assets::coords::wow_to_bevy;
 
-use super::super::{GuidIndex, PetDismissSoundMessage, PetTalkMessage};
+use super::PetBar;
+use crate::net::{GuidIndex, NetHandlerApp, PetDismissSoundMessage, PetTalkMessage};
 use crate::ui_action::{CastErrors, PetTameFailures, Spells, UiError, UiErrorKeys};
-use crate::ui_pet::PetBar;
+
+/// Register the pet's handlers — called from [`super::UiPetPlugin`].
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::PetSpells, on_spells)
+        .net_handler(K::PetMode, on_mode)
+        .net_handler(K::PetActionFeedback, on_action_feedback)
+        .net_handler(K::PetCastFailed, on_cast_failed)
+        .net_handler(K::PetTameFailure, on_tame_failure)
+        .net_handler(K::PetNameInvalid, on_refusal_line)
+        .net_handler(K::PetBroken, on_refusal_line)
+        .net_handler(K::PetActionSound, on_action_sound)
+        .net_handler(K::PetDismissSound, on_dismiss_sound)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+/// The pet bar dies with the socket — a listener on the session end (a second handler on the kind,
+/// after the bridge's own teardown). The zero-guid `SMSG_PET_SPELLS` is the only in-session
+/// teardown, and a dropped socket never sends one: without this the next session kept the old
+/// pet's bar, pressed `CMSG_PET_ACTION` at a guid that no longer exists, and the stable read a live
+/// pet. The same reset as the zero guid's, cooldown store included.
+fn on_session_end(In(_): In<SessionEvent>, mut bar: ResMut<PetBar>) {
+    *bar = PetBar::default();
+}
+
+/// The pet action bar (decision 0982) — server-authoritative, so PET_SPELLS is a wholesale
+/// replace and its zero-guid form is the teardown.
+fn on_spells(In(ev): In<SessionEvent>, catalog: Option<Res<Spells>>, mut bar: ResMut<PetBar>) {
+    if let SessionEvent::PetSpells(spells) = ev {
+        pet_spells(*spells, catalog.as_deref(), &mut bar);
+    }
+}
+
+fn on_mode(In(ev): In<SessionEvent>, mut bar: ResMut<PetBar>) {
+    if let SessionEvent::PetMode(mode) = ev {
+        pet_mode(mode, &mut bar);
+    }
+}
+
+fn on_action_feedback(In(ev): In<SessionEvent>, mut errors: ResMut<UiErrorKeys>) {
+    if let SessionEvent::PetActionFeedback { reason } = ev {
+        pet_action_feedback(reason, &mut errors);
+    }
+}
+
+fn on_cast_failed(In(ev): In<SessionEvent>, mut errors: ResMut<CastErrors>) {
+    if let SessionEvent::PetCastFailed { spell_id, reason } = ev {
+        pet_cast_failed(spell_id, reason, &mut errors);
+    }
+}
+
+fn on_tame_failure(In(ev): In<SessionEvent>, mut failures: ResMut<PetTameFailures>) {
+    if let SessionEvent::PetTameFailure { reason } = ev {
+        pet_tame_failure(reason, &mut failures);
+    }
+}
+
+fn on_refusal_line(In(ev): In<SessionEvent>, mut errors: ResMut<UiErrorKeys>) {
+    match ev {
+        SessionEvent::PetNameInvalid => pet_name_invalid(&mut errors),
+        SessionEvent::PetBroken => pet_broken(&mut errors),
+        _ => {}
+    }
+}
+
+fn on_action_sound(
+    In(ev): In<SessionEvent>,
+    index: Res<GuidIndex>,
+    mut talks: MessageWriter<PetTalkMessage>,
+) {
+    if let SessionEvent::PetActionSound { pet_guid, talk } = ev {
+        pet_action_sound(pet_guid, talk, &index, &mut talks);
+    }
+}
+
+fn on_dismiss_sound(In(ev): In<SessionEvent>, mut sounds: MessageWriter<PetDismissSoundMessage>) {
+    if let SessionEvent::PetDismissSound { model_id, position } = ev {
+        pet_dismiss_sound(model_id, position, &mut sounds);
+    }
+}
 
 /// `SMSG_PET_SPELLS` — replace the whole bar, and reseed the pet's own cooldown store from the
 /// packet's tail.
@@ -35,7 +118,7 @@ use crate::ui_pet::PetBar;
 /// cooldown store goes with it, because the next pet is a different unit with different timers.
 /// Everything else is a wholesale replace — including a re-send from the same pet, which is how a
 /// learned spell, a mode change or an autocast toggle actually reaches the bar.
-pub(super) fn pet_spells(spells: PetSpells, catalog: Option<&Spells>, bar: &mut PetBar) {
+fn pet_spells(spells: PetSpells, catalog: Option<&Spells>, bar: &mut PetBar) {
     if spells.pet_guid == 0 {
         if bar.spells.pet_guid != 0 {
             debug!("net: pet bar torn down");
@@ -110,7 +193,7 @@ pub(super) fn pet_spells(spells: PetSpells, catalog: Option<&Spells>, bar: &mut
             .join(" · ")
     );
     let now = Instant::now();
-    bar.cooldowns = crate::cooldowns::Cooldowns::default();
+    bar.cooldowns = crate::spell::Cooldowns::default();
     for cd in &spells.cooldowns {
         let display = catalog.and_then(|c| c.catalog.get(cd.spell_id));
         bar.cooldowns.seed_pet(cd, display, now);
@@ -121,7 +204,7 @@ pub(super) fn pet_spells(spells: PetSpells, catalog: Option<&Spells>, bar: &mut
 /// `SMSG_PET_MODE` — the react/command state alone. Applied only when it names the pet whose bar
 /// we actually hold: a mode packet for a unit we have no bar for has nothing to write into, and
 /// taking its state anyway would light a reaction button on the wrong pet's bar.
-pub(super) fn pet_mode(mode: PetMode, bar: &mut PetBar) {
+fn pet_mode(mode: PetMode, bar: &mut PetBar) {
     if bar.spells.pet_guid == 0 || bar.spells.pet_guid != mode.pet_guid {
         return;
     }
@@ -134,7 +217,7 @@ pub(super) fn pet_mode(mode: PetMode, bar: &mut PetBar) {
 /// `SMSG_PET_ACTION_FEEDBACK` — one reason byte for a refused order, queued onto the red line by
 /// GlobalStrings key ([`UiErrorKeys`], the `DisplayError` route). An unrecognised code queues
 /// nothing, exactly as an absent key shows nothing.
-pub(super) fn pet_action_feedback(reason: u8, errors: &mut UiErrorKeys) {
+fn pet_action_feedback(reason: u8, errors: &mut UiErrorKeys) {
     debug!("net: pet action feedback {reason}");
     if let Some(key) = pet_feedback_key(reason) {
         errors.0.push(UiError::key(key));
@@ -188,7 +271,7 @@ fn pet_feedback_key(reason: u8) -> Option<&'static str> {
 /// No local state moves: the refusal is the server's last word on a spell that never took, and
 /// the client's own cast bookkeeping was already unwound by the `SMSG_CAST_RESULT` that came with
 /// it.
-pub(super) fn pet_tame_failure(reason: u8, failures: &mut PetTameFailures) {
+fn pet_tame_failure(reason: u8, failures: &mut PetTameFailures) {
     debug!(
         "net: pet tame failure {reason} ({})",
         benilla_protocol::messages::pet_tame_failure_key(reason)
@@ -200,12 +283,12 @@ pub(super) fn pet_tame_failure(reason: u8, failures: &mut PetTameFailures) {
 ///
 /// The packet carries nothing at all, so the opcode IS the message — which is exactly what the
 /// reference's arm does (`0x5e3e33`: `push 0xf7; call 0x496720`, no body read). Decision 1066
-/// recorded the opposite ("a refused rename silently does nothing") from a carve that had
-/// attributed `SMSG_PET_BROKEN`'s handler to this opcode; the two are different functions.
+/// recorded the opposite ("a refused rename silently does nothing"), attributing
+/// `SMSG_PET_BROKEN`'s handler to this opcode; the two are different functions.
 ///
 /// Nothing else moves: the rename was optimistic-free by design (1066), so there is no local name
 /// to roll back, and the popup has already closed.
-pub(super) fn pet_name_invalid(errors: &mut UiErrorKeys) {
+fn pet_name_invalid(errors: &mut UiErrorKeys) {
     debug!("net: pet name refused");
     errors.0.push(UiError::key("ERR_INVALID_PETNAME"));
 }
@@ -218,7 +301,7 @@ pub(super) fn pet_name_invalid(errors: &mut UiErrorKeys) {
 /// `Unsummon(PET_SAVE_AS_DELETED)` (`Pet.cpp:822`), so the zero-guid `SMSG_PET_SPELLS` that
 /// actually clears the bar arrives on its own heels — which is why touching the bar here would be
 /// a second, racing teardown rather than a fix.
-pub(super) fn pet_broken(errors: &mut UiErrorKeys) {
+fn pet_broken(errors: &mut UiErrorKeys) {
     debug!("net: pet ran away");
     errors.0.push(UiError::key("ERR_PET_BROKEN"));
 }
@@ -232,7 +315,7 @@ pub(super) fn pet_broken(errors: &mut UiErrorKeys) {
 ///
 /// The selector is not validated here — [`crate::sound::creature`]'s reader is where the
 /// two-armed `cmp` lives, because that is where the reference has it too (`0x604106`/`0x60411c`).
-pub(super) fn pet_action_sound(
+fn pet_action_sound(
     pet_guid: u64,
     talk: u32,
     index: &GuidIndex,
@@ -250,7 +333,7 @@ pub(super) fn pet_action_sound(
 /// The `+1.0` on `z` is the reference's own (`0x6041d0 fadd [0x7ff9d8]`), applied **before** the
 /// basis change because it is a WoW-space offset: the point on the wire is where the pet stood,
 /// and the kit sounds a yard above it.
-pub(super) fn pet_dismiss_sound(
+fn pet_dismiss_sound(
     model_id: u32,
     position: [f32; 3],
     sounds: &mut MessageWriter<PetDismissSoundMessage>,
@@ -282,7 +365,7 @@ pub(super) fn pet_dismiss_sound(
 ///   set is the two packet readers, `0x496720`, and the string plumbing behind it. So a pet's
 ///   refusal never prints "You fail to cast Growl: ..." in the log, and the drain's combat twin
 ///   skips it.
-pub(super) fn pet_cast_failed(spell_id: u32, reason: Option<u8>, errors: &mut CastErrors) {
+fn pet_cast_failed(spell_id: u32, reason: Option<u8>, errors: &mut CastErrors) {
     debug!("net: pet cast failed — spell {spell_id} reason {reason:?}");
     if let Some(reason) = reason {
         errors.push_pet(spell_id, reason);
diff --git a/crates/benilla-app/src/ui_pet/tests.rs b/crates/benilla-app/src/ui_pet/tests.rs
index 27af3220..86c9b957 100644
--- a/crates/benilla-app/src/ui_pet/tests.rs
+++ b/crates/benilla-app/src/ui_pet/tests.rs
@@ -286,7 +286,7 @@ fn an_unresolvable_spell_draws_nothing() {
     assert!(!v.autocast_allowed && !v.autocast_enabled);
 }
 
-/// A type outside 1–7 is inert. The client's own default arm under-pushes here (wow-re §2.5);
+/// A type outside 1–7 is inert. The client's own default arm under-pushes here (`0x4bde6f`);
 /// we answer the empty slot instead, and in particular never reach the spell catalog with an
 /// arbitrary number.
 #[test]
@@ -862,9 +862,9 @@ fn only_the_same_pets_moving_timestamp_reads_as_a_rename() {
     assert!(!was_renamed(Some((0xF14, Some(100))), (0xABC, Some(100))));
 }
 
-/// **Dismiss is a bar press with no button** — the correction the wow-re carve made to this build
-/// (§11c). `PetDismiss 0x4be4d0` opens no packet: it stages the packed word `0x07000003` and hands
-/// it to the same dispatcher every pet-bar click uses, so it leaves as `CMSG_PET_ACTION`.
+/// **Dismiss is a bar press with no button.** `PetDismiss 0x4be4d0` opens no packet: it stages
+/// the packed word `0x07000003` and hands it to the same dispatcher every pet-bar click uses, so it
+/// leaves as `CMSG_PET_ACTION`.
 ///
 /// The literal is pinned here against the word the constants build, because the two ways of saying
 /// it are the two halves of the finding, and the first draft of this feature sent
@@ -884,7 +884,7 @@ fn the_dismiss_word_is_the_carved_literal() {
 
 /// The bar's two events are two edges (1953): a change of the slots fires `PET_BAR_UPDATE`; a
 /// change of the cooldown triples alone fires `PET_BAR_UPDATE_COOLDOWN` — the reference's
-/// cooldown-subsystem fire for the pet bank (wow-re `pet-action-bar-api.md` §9) — and the
+/// cooldown-subsystem fire for the pet bank (`0x6e2e8e`) — and the
 /// pushed state carries the new triple either way.
 #[test]
 fn a_cooldown_alone_fires_the_cooldown_event_and_not_the_bar_update() {
@@ -959,3 +959,79 @@ fn a_cooldown_alone_fires_the_cooldown_event_and_not_the_bar_update() {
     );
     assert_eq!(enable, 1);
 }
+
+/// **A bar toggle reaches the spellbook**: after the
+/// local write-back, `0x4bcc19` calls `0x4bd190(&bar[slot])`, which scans the raw pet-spell
+/// array backwards for the entry equal to the slot under `& 0x3FFFFFFF` and copies the slot's
+/// FULL word into it. The book renders from that array, so without the copy the Pet tab kept
+/// the old autocast ring until the next `SMSG_PET_SPELLS`. The book→bar direction is
+/// `ui_pet_book::flip_autocast` (decision 1032); this is its twin.
+#[test]
+fn a_bar_autocast_toggle_reaches_the_pet_spellbook() {
+    const CLAW: u32 = 16827;
+    const GROWL: u32 = 2649;
+    let mut bar = PetBar {
+        spells: PetSpells {
+            pet_guid: 0x2A,
+            ..Default::default()
+        },
+        ..Default::default()
+    };
+    bar.spells.bar[3] = packed(CLAW, PET_ACT_ENABLED); // autocast allowed + on
+    bar.spells.spells = vec![
+        packed(GROWL, PET_ACT_ENABLED),
+        packed(CLAW, PET_ACT_ENABLED),
+    ];
+
+    let flipped = toggle_slot_autocast(&mut bar, 4).expect("an autocastable slot toggles");
+    assert!(!flipped.autocast_on());
+    assert!(!bar.spells.bar[3].autocast_on(), "the bar slot flipped");
+    assert!(
+        !bar.spells.spells[1].autocast_on(),
+        "…and the book's CLAW entry got the slot's whole word"
+    );
+    assert_eq!(bar.spells.spells[1].packed, flipped.packed);
+    assert!(
+        bar.spells.spells[0].autocast_on(),
+        "a different spell's book entry is untouched"
+    );
+
+    // And back on: the copy is the full word, both directions.
+    toggle_slot_autocast(&mut bar, 4);
+    assert!(bar.spells.spells[1].autocast_on());
+
+    // `0x4bcbf1`: a word without bit 31 aborts before anything is written, book included.
+    bar.spells.bar[5] = packed(3025, PET_ACT_PASSIVE);
+    bar.spells.spells.push(packed(3025, PET_ACT_PASSIVE));
+    assert!(toggle_slot_autocast(&mut bar, 6).is_none());
+    assert_eq!(bar.spells.spells[2], packed(3025, PET_ACT_PASSIVE));
+}
+
+/// **The pet bar dies with the session.** Only the zero-guid `SMSG_PET_SPELLS` cleared it, and a
+/// dropped socket never sends one — so the next session kept the old pet's bar: presses went out
+/// as `CMSG_PET_ACTION` to a guid that no longer exists, and the stable read `has_live_pet`.
+#[test]
+fn the_session_end_tears_the_pet_bar_down() {
+    let mut app = bevy::prelude::App::new();
+    app.add_plugins(UiPetPlugin);
+    {
+        let mut bar = app.world_mut().resource_mut::<PetBar>();
+        bar.spells.pet_guid = 0x2A;
+        bar.spells.bar[3] = packed(16827, PET_ACT_ENABLED);
+    }
+
+    crate::net::handlers::dispatch(
+        app.world_mut(),
+        vec![benilla_protocol::SessionEvent::Disconnected {
+            reason: "socket".into(),
+            end: benilla_protocol::SessionEnd::Lost,
+        }],
+    );
+
+    let bar = app.world().resource::<PetBar>();
+    assert_eq!(
+        bar.spells.pet_guid, 0,
+        "no pet bar carried into the next session"
+    );
+    assert!(bar.spells.bar[3].is_empty());
+}
diff --git a/crates/benilla-app/src/ui_pet/unit.rs b/crates/benilla-app/src/ui_pet/unit.rs
index ca449b95..f7ab55a6 100644
--- a/crates/benilla-app/src/ui_pet/unit.rs
+++ b/crates/benilla-app/src/ui_pet/unit.rs
@@ -2,7 +2,7 @@
 //!
 //! This lives with the pet bar rather than beside the `"player"`/`"target"` feed for one reason:
 //! the token's identity is [`PetBar`]'s cached pet guid — the client's `[0xb714a0]`, which is also
-//! what `UNIT_PET` fires off (wow-re §9) — so the token and its repaint wire read the same word,
+//! what `UNIT_PET` fires off (`0x4bc84f`) — so the token and its repaint wire read the same word,
 //! from the module that owns it.
 
 use bevy::prelude::*;
@@ -38,8 +38,7 @@ pub(super) struct PetUnitMemory {
 }
 
 /// `UNIT_FIELD_FLAGS` bit `0x800` — the **pet-in-combat** flag, and the whole trigger for
-/// `PET_ATTACK_START`/`PET_ATTACK_STOP` (`0x5ff75e test ah,8`, wow-re
-/// `object-layer/scratch/pet-command-validators.md` §4).
+/// `PET_ATTACK_START`/`PET_ATTACK_STOP` (`0x5ff75e test ah,8`).
 ///
 /// Server-owned and server-written: nothing client-side sets it, which is exactly why it — and not
 /// the local click latch — is what the reference watches.
@@ -48,7 +47,7 @@ pub(super) const UNIT_FLAG_PET_IN_COMBAT: u32 = 0x0000_0800;
 /// Feed the **`"pet"` unit token** and the pet frame's three events (decision 0990).
 ///
 /// **The token resolves off the bar's cached pet guid, not off our own `UNIT_FIELD_SUMMON`**, and
-/// that is the client's own choice rather than a convenience. wow-re §9 carves `UNIT_PET` as firing
+/// that is the client's own choice rather than a convenience. `UNIT_PET` fires
 /// from inside `SetPet 0x4bc7e0` (`0x4bc84f`: `SignalEvent(2, "%s", "player")`) — the single writer
 /// of `[0xb714a0]`, the same cached guid the whole pet bar reads — and **only when that guid
 /// actually changed**. Since `UNIT_PET` is the pet frame's only repaint wire, a token sourced from
@@ -106,7 +105,9 @@ pub(super) fn feed_pet_unit(
         .then(|| pet.store(pet_guid))
         .flatten()
         .map(|store| {
-            let name = names.resolve(pet_guid, &commands).map(str::to_string);
+            let name = names
+                .resolve_unit(pet_guid, Some(store), &commands)
+                .map(str::to_string);
             // No `ChrClasses.dbc` here, and none needed: a pet is a UNIT, so the reference's
             // own TYPEMASK_PLAYER gate refuses it before the class byte is ever read. Passing
             // the table could not change the answer.
@@ -150,8 +151,8 @@ pub(super) fn feed_pet_unit(
         None => memory.pushed = None,
     }
 
-    // UNIT_PET(arg1 = "player") — VERIFIED wow-re §9, including the `arg1` and the changed-guid
-    // gate. Summon, stable swap and dismiss are the three edges; a re-sent `SMSG_PET_SPELLS` for
+    // UNIT_PET(arg1 = "player"), fired only when the pet guid changes (`0x4bc84f`).
+    // Summon, stable swap and dismiss are the three edges; a re-sent `SMSG_PET_SPELLS` for
     // the same pet (a learned spell, a mode change) is not one, which is why this diffs the guid
     // rather than riding `feed_pet_bar`'s whole-state diff.
     if memory.guid != Some(pet_guid) {
@@ -165,11 +166,11 @@ pub(super) fn feed_pet_unit(
     // `UI-Player-AttackStatus` overlay.
     //
     // **CORRECTED.** Decision 0990 derived these from the attack latch `[0xb714b0]`'s edges and
-    // said so honestly; the derivation was wrong. wow-re later carved the real fire site —
-    // `0x5ff793`/`0x5ff79a` inside `0x5ff580`, a per-field change callback registered *by field
-    // byte offset* (`0x6042e2 mov edx,0xa0`), which is why walking the call graph out of the pet
-    // TU never reached it. The trigger is the unit's own server-supplied
-    // `UNIT_FIELD_FLAGS & 0x800` **transition**, gated on the unit's owner guid being ours.
+    // said so honestly; the derivation was wrong. The real fire site is `0x5ff793`/`0x5ff79a`
+    // inside `0x5ff580`, a per-field change callback registered *by field byte offset*
+    // (`0x6042e2 mov edx,0xa0`), which is why walking the call graph out of the pet TU never
+    // reaches it. The trigger is the unit's own server-supplied `UNIT_FIELD_FLAGS & 0x800`
+    // **transition**, gated on the unit's owner guid being ours.
     //
     // The two are not the same question and they visibly diverge: the latch is a local click
     // record with exactly three writers, so a pet that disengages on its own — its target dies, it
@@ -206,7 +207,7 @@ pub(super) fn feed_pet_unit(
 }
 
 /// **Watch the pet's name timestamp, drop the cached name when it moves, and announce it**
-/// (decision 1066; the mechanism is VERIFIED at the bytes — wow-re §11c).
+/// (decision 1066).
 ///
 /// A pet's name is the one name in the client that can change under us. It does not ride the
 /// descriptor — it is answered once by `CMSG_PET_NAME_QUERY` into `petnamecache.wdb` and keyed by
diff --git a/crates/benilla-app/src/ui_pet_doll.rs b/crates/benilla-app/src/ui_pet_doll.rs
index 73a1f404..0a71fbdd 100644
--- a/crates/benilla-app/src/ui_pet_doll.rs
+++ b/crates/benilla-app/src/ui_pet_doll.rs
@@ -172,7 +172,7 @@ mod tests {
         assert_eq!(
             s.defense_skill,
             (0, 0),
-            "INTERIM — pending the wow-re verdict"
+            "INTERIM — unconfirmed in the reference"
         );
     }
 
diff --git a/crates/benilla-app/src/ui_pet_stats.rs b/crates/benilla-app/src/ui_pet_stats.rs
index 553a9b79..f2459ba6 100644
--- a/crates/benilla-app/src/ui_pet_stats.rs
+++ b/crates/benilla-app/src/ui_pet_stats.rs
@@ -1,6 +1,5 @@
 //! The hunter pet's **paper-doll stat block** — `GetPetHappiness`, `GetPetLoyalty`,
-//! `GetPetTrainingPoints`, `GetPetExperience` and `HasPetUI` (decision 1005; wow-re
-//! `ui/scratch/pet-action-bar-api.md` §11b + §6).
+//! `GetPetTrainingPoints`, `GetPetExperience` and `HasPetUI` (decision 1005).
 //!
 //! Its own module rather than more of [`crate::ui_pet`] because it is a different concern on a
 //! different clock: the action bar's contents arrive whole in `SMSG_PET_SPELLS` and change when
@@ -12,7 +11,7 @@
 //! its `UNIT_FIELD_PETNUMBER`, requires its owner to be us, and finishes
 //! `cmp byte [player.fields + 0x79], 3; sete al` — `UNIT_FIELD_BYTES_0` byte 1, the class, against
 //! **Hunter**. (The enum is pinned by the combo-point gate's own class test on the same byte:
-//! `== 4 || == 0xB` is Rogue and Druid, wow-re `combo-point-gate.md`.) A warlock's imp therefore
+//! `== 4 || == 0xB` is Rogue and Druid, `GetComboPoints 0x51a190`.) A warlock's imp therefore
 //! resolves perfectly and still answers nothing — happiness, loyalty and training points are
 //! hunter machinery — and each binding says "nothing" in its own way ([`benilla_ui::script::PetStats`]).
 //!
@@ -38,7 +37,7 @@ use crate::ui_unit::UnitFeed;
 
 /// `UNIT_FIELD_BYTES_0` byte 1 == 3 — **Hunter**, the class the four stat bindings gate on
 /// (`0x611752`). Pinned rather than assumed: the same byte's `4`/`0xB` are Rogue and Druid in the
-/// already-carved combo-point gate, which fixes the enum this value sits in.
+/// combo-point gate (`GetComboPoints 0x51a190`), which fixes the enum this value sits in.
 const CLASS_HUNTER: u8 = 3;
 
 /// `UNIT_FIELD_BYTES_0` byte 3 == 4 — the **happiness** power, the field `GetPetHappiness`
@@ -179,15 +178,15 @@ fn stats_for(
         && self_store.map(|s| ((s.0.unit_bytes_0().unwrap_or(0) >> 8) & 0xff) as u8)
             == Some(CLASS_HUNTER);
     if !hunter {
-        // **The family WORD rides past the gate; the DIET does not** — and the split is carved,
-        // not chosen. `UnitCreatureFamily 0x51a310` has no class test at all (its only nil paths
-        // are "no record / id 0 / out of range / a null row"), so a warlock's minion shows "Imp"
-        // on the page's level line. `GetPetFoodTypes 0x4bea10` is gated on `0x6116e0(pet)` — the
-        // same owner-is-me + class-is-Hunter gate as the four stat bindings — so it answers
-        // *nothing* for a minion even though the word is there. The shipped data hides the
-        // difference for warlocks (every minion family ships food mask 0), but not for a
-        // **charmed beast under a non-hunter**: a mind-controlled boar has family 5 and mask 63,
-        // and the reference still answers an empty diet for it. (wow-re, 2026-08-06.)
+        // **The family WORD rides past the gate; the DIET does not** — and the split is the
+        // reference's, not chosen. `UnitCreatureFamily 0x51a310` has no class test at all (its
+        // only nil paths are "no record / id 0 / out of range / a null row"), so a warlock's
+        // minion shows "Imp" on the page's level line. `GetPetFoodTypes 0x4bea10` is gated on
+        // `0x6116e0(pet)` — the same owner-is-me + class-is-Hunter gate as the four stat
+        // bindings — so it answers *nothing* for a minion even though the word is there. The
+        // shipped data hides the difference for warlocks (every minion family ships food mask
+        // 0), but not for a **charmed beast under a non-hunter**: a mind-controlled boar has
+        // family 5 and mask 63, and the reference still answers an empty diet for it.
         return (
             has_ui,
             PetStats {
@@ -290,7 +289,8 @@ fn feed_pet_stats(
     // for it, `UNIT_CLASSIFICATION_CHANGED` (the reference's own "a creature query landed" wire,
     // decision 0782) is neither registered by the page nor even edge-able for a pet, whose gated
     // rank is pinned at 0. Inventing a fire site — `PET_UI_UPDATE`, or `UNIT_LEVEL` because the
-    // family shares the level's line — would be asserting a mechanism nobody has carved.
+    // family shares the level's line — would be asserting a mechanism nobody has found in the
+    // reference.
     //
     // What makes it *survivable* rather than broken: the query goes out the frame the pet's
     // descriptor arrives, thousands of frames before a human can open the character window, so
@@ -648,9 +648,9 @@ mod tests {
         assert_eq!(family_for(Some(&boar()), &names, &cmds, None), no_family());
     }
 
-    /// **The family WORD survives the hunter gate; the DIET does not** — the carved split
-    /// (wow-re, 2026-08-06: `UnitCreatureFamily 0x51a310` has no class test, `GetPetFoodTypes
-    /// 0x4bea10` shares `0x6116e0` with the four stats).
+    /// **The family WORD survives the hunter gate; the DIET does not** — the reference's split
+    /// (`UnitCreatureFamily 0x51a310` has no class test, `GetPetFoodTypes 0x4bea10` shares
+    /// `0x6116e0` with the four stats).
     ///
     /// The pet here is deliberately a **boar under a non-hunter** — a charmed beast, family 5,
     /// food mask 63 — because that is the one case where the gate is observable at all: a warlock
@@ -732,8 +732,8 @@ mod tests {
             .init_resource::<crate::ui_script::UiClock>()
             .init_resource::<crate::ui_action::UiErrorKeys>()
             .init_resource::<crate::net::Reputations>()
-            .init_resource::<crate::ui_cast::QueuedMeleeSpell>()
-            .init_resource::<crate::ui_action::AutoRepeatActive>()
+            .init_resource::<crate::spell::QueuedMeleeSpell>()
+            .init_resource::<crate::spell::AutoRepeatActive>()
             .add_message::<crate::creature_anim::SheathRequest>()
             .add_message::<crate::net::FieldChanged>()
             .insert_resource(NetCommands(tx))
diff --git a/crates/benilla-app/src/ui_petition/feed.rs b/crates/benilla-app/src/ui_petition/feed.rs
index ef7440d2..7ea9bfb3 100644
--- a/crates/benilla-app/src/ui_petition/feed.rs
+++ b/crates/benilla-app/src/ui_petition/feed.rs
@@ -6,10 +6,10 @@
 //! **`PETITION_SHOW` is DEFERRED, and that is the load-bearing behaviour of this file.** The real
 //! client fires it only when *no signer name is still resolving* **and** *the petition record has
 //! arrived* (`0x4f419b`-`0x4f41ad`), and it fires exactly once however many names were outstanding
-//! (`0x4f4320` decrements the pending counter and fires only on the transition to zero). wow-re's
-//! note puts it flatly: *"A client that fires `PETITION_SHOW` straight off the packet paints a
-//! window with blank signer names."* That is precisely what this file did before the carve — it
-//! opened immediately and repainted as each lookup landed, which is a visibly different window.
+//! (`0x4f4320` decrements the pending counter and fires only on the transition to zero). A client
+//! that fires `PETITION_SHOW` straight off the packet paints a window with blank signer names.
+//! That is precisely what this file once did — it opened immediately and repainted as each lookup
+//! landed, which is a visibly different window.
 //!
 //! Two things follow, and they are why the deferral is a simplification rather than a cost:
 //!
@@ -34,9 +34,8 @@ use benilla_ui::script::{
 };
 use bevy::prelude::*;
 
-use crate::items::Items;
 use crate::names::NameCache;
-use crate::net::{ClientCommand, NetCommands, ObjectStore, SelfGuid, SelfPlayer};
+use crate::net::{ClientCommand, NetCommands, ObjectStore, Objects, SelfGuid, SelfPlayer};
 use crate::ui_items::{find_item, ItemSearch};
 use crate::ui_session::{npc_switched, NpcSession};
 
@@ -223,7 +222,7 @@ pub(super) fn drain_petition(
     mut registrar: ResMut<GuildRegistrarState>,
     mut petition: ResMut<PetitionState>,
     names: Res<NameCache>,
-    items: Res<Items>,
+    objects: Objects,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
     self_guid: Res<SelfGuid>,
     selection: Res<crate::target::Selection>,
@@ -256,7 +255,7 @@ pub(super) fn drain_petition(
                 let charter = self_q.iter().next().and_then(|store| {
                     find_item(
                         &store.0,
-                        &items,
+                        &objects,
                         benilla_protocol::messages::CHARTER_ITEM_ENTRY,
                         ItemSearch::default(),
                     )
diff --git a/crates/benilla-app/src/ui_petition/lines.rs b/crates/benilla-app/src/ui_petition/lines.rs
index 46e0a3a4..bf0e2dd6 100644
--- a/crates/benilla-app/src/ui_petition/lines.rs
+++ b/crates/benilla-app/src/ui_petition/lines.rs
@@ -3,10 +3,8 @@
 //!
 //! The split is the part a re-implementation cannot guess, and we did guess it wrong first: by the
 //! key names, `ERR_PETITION_SIGNED_S` and `ERR_PETITION_ALREADY_SIGNED` look like the same kind of
-//! thing. They are not. wow-re
-//! `system/object-layer/scratch/petition-wire-law.md` §4 read the message catalog at `0xb4b498`
-//! (stride `0x14`, field `+4` = kind, routed through the four-entry table at `0x496888`) and swept
-//! every row:
+//! thing. They are not. A sweep of every row of the message catalog at `0xb4b498` (stride `0x14`,
+//! field `+4` = kind, routed through the four-entry table at `0x496888`) gives:
 //!
 //! - the **four** `_S`/success ids `0x141`-`0x144` carry kind `0` → the shared chat chokepoint
 //!   `0x49a870` with the row's own `+0x10` chat type, which is `0xa` → **`CHAT_MSG_SYSTEM`**, the
@@ -132,7 +130,7 @@ pub(super) fn name_refused_line(key: &str) -> Line {
         "ERR_GUILD_NAME_INVALID_SPACE" => "ERR_GUILD_NAME_INVALID_SPACE",
         "ERR_GUILD_NAME_NAME_CONSECUTIVE_SPACES" => "ERR_GUILD_NAME_NAME_CONSECUTIVE_SPACES",
         "ERR_GUILD_NAME_TOO_SHORT" => "ERR_GUILD_NAME_TOO_SHORT",
-        // The validator can name a key `0x6c9b70` has not been carved for. Re-keying it to the
+        // The validator can name a key `0x6c9b70` is not known to produce. Re-keying it to the
         // generic invalid-name row is what keeps a raw key off the screen; the match above is
         // what makes that a re-key rather than a pass-through.
         _ => "ERR_GUILD_NAME_INVALID",
diff --git a/crates/benilla-app/src/ui_petition/mod.rs b/crates/benilla-app/src/ui_petition/mod.rs
index e458dca1..e262265f 100644
--- a/crates/benilla-app/src/ui_petition/mod.rs
+++ b/crates/benilla-app/src/ui_petition/mod.rs
@@ -12,11 +12,10 @@
 //!   server pushes when the "How do I form a guild?" gossip row is selected — vmangos
 //!   `Player.cpp:12428-12431` closes the gossip menu and calls `SendPetitionShowList`), it knows a
 //!   price and an NPC guid, and it closes when the player walks away like every other NPC window
-//!   ([`crate::ui_session`]). wow-re corroborates the shape rather than merely permitting it: the
-//!   function that fires `GUILD_REGISTRAR_SHOW` (`0x4f4fb0`, firing at `0x4f4fff`) is one of the
-//!   fourteen callers of `CGGameUI::SetInteractNPC 0x4930d0`
-//!   (`system/object-layer/scratch/interaction-facing.md:177-178`), which is the *same* latch every
-//!   other NPC window arms.
+//!   ([`crate::ui_session`]). The reference corroborates the shape rather than merely permitting
+//!   it: the function that fires `GUILD_REGISTRAR_SHOW` (`0x4f4fb0`, firing at `0x4f4fff`) is one
+//!   of the fourteen callers of `CGGameUI::SetInteractNPC 0x4930d0`, which is the *same* latch
+//!   every other NPC window arms.
 //! - [`PetitionState`] is the item half: it opens on `SMSG_PETITION_SHOW_SIGNATURES`, is bound to a
 //!   charter **item guid**, and has no NPC at all. Walking away from the registrar must not close
 //!   it, which is why the two are separate resources rather than one with a half-meaning `close()`.
@@ -52,7 +51,7 @@
 //!   `SMSG_PETITION_SIGN_RESULTS` to both parties and **no fresh signatures packet**
 //!   (`:299`, `:312-316`), while the reference's `PetitionFrame` registers only `PETITION_SHOW` and
 //!   `PETITION_CLOSED`. Nothing would ever repaint the name rows. So an `OK` result naming the open
-//!   charter re-sends `CMSG_PETITION_SHOW_SIGNATURES` ([`apply::sign_results`]) — INFERRED, and
+//!   charter re-sends `CMSG_PETITION_SHOW_SIGNATURES` ([`net::sign_results`]) — INFERRED, and
 //!   flagged as such below.
 //! - **Two success paths are silent on the wire and speak locally.** Offering a charter answers the
 //!   *target*, not us, and finding no charter to turn in is refused before any packet is built —
@@ -62,12 +61,9 @@
 //!
 //! ## What is INFERRED, and what would settle it
 //!
-//! wow-re had **not carved a single one of this subsystem's contracts** when this landed — it holds
-//! the eight binding addresses (`system/ui/scratch/bindings.md:455-462`, all classified
-//! ORCHESTRATION: located, contract never derived) and the four event ids
-//! (`guild-api-carve.md:603-624`), and nothing about the wire or the handlers. Every claim below is
-//! read off the *demand* side (the shipped `PetitionFrame.lua` / `GuildRegistrarFrame.lua`) plus
-//! vmangos, and is named here so none of it is mistaken for byte law:
+//! Every claim below is read off the *demand* side (the shipped `PetitionFrame.lua` /
+//! `GuildRegistrarFrame.lua`) plus vmangos, and is named here so none of it is mistaken for byte
+//! law:
 //!
 //! 1. **`SMSG_PETITION_SHOWLIST` → `GUILD_REGISTRAR_SHOW`** (no args). The firer `0x4f4fb0` sits in
 //!    the petition band with `0x5eeb80` as its sole caller; the byte read of that handler settles
@@ -75,8 +71,8 @@
 //! 2. **`SMSG_PETITION_SHOW_SIGNATURES` → `PETITION_SHOW`** (no args), everything painted from
 //!    getters. The reference's own OnEvent uses no `arg1`, which makes this weak-but-consistent.
 //! 3. **`ClosePetition()` / `CloseGuildRegistrar()` send nothing.** Chosen because inventing
-//!    traffic 1.12 never sends is the worse failure, and because wow-re already recorded exactly
-//!    that verdict for the neighbouring `CloseGuildRoster` (`xor eax,eax; ret`).
+//!    traffic 1.12 never sends is the worse failure, and because the neighbouring
+//!    `CloseGuildRoster 0x4d2350` sends nothing either (`xor eax,eax; ret`).
 //! 4. **Re-requesting the signature list on an `OK` sign result** (above).
 //! 5. **`ERR_GUILD_FOUNDER_S` on a successful turn-in.** vmangos declares `GUILD_FOUNDER_S = 0x0E`
 //!    and **never sends it** — `Guild::Create` broadcasts no event at all on the founding path
@@ -141,7 +137,7 @@ impl GuildRegistrarState {
     /// `npc_flags` is the NPC's live `UNIT_NPC_FLAGS`, or `None` when the guid does not resolve to a
     /// streamed unit — which fails the gate, as the client's own `0x5eec1a` resolve does.
     ///
-    /// The three gates, from `system/object-layer/scratch/petition-wire-law.md` §2:
+    /// The three gates, in the showlist handler `0x5eeb80`:
     /// 1. the NPC resolves as a unit and carries [`REGISTRAR_NPC_FLAGS`];
     /// 2. **entry\[0\]**'s `entryFlags & 1` is set (`0x5eec42`, and it is entry\[0\]'s fifth dword
     ///    specifically — no other entry's flags are tested anywhere on this path);
@@ -402,6 +398,16 @@ impl PetitionState {
         self.open = None;
     }
 
+    /// The session end: the open charter, the in-flight sign and the undrained lines are the old
+    /// session's and go with it — silently, with **no** decline (the socket is gone, and a
+    /// decline is the close verb's, not the teardown's). The record cache stays: it is keyed by
+    /// the server's petition id, and the world-enter release already re-arms its asks.
+    fn clear_session(&mut self) {
+        self.open = None;
+        self.signing = false;
+        self.lines.clear();
+    }
+
     /// The open charter's item guid — what `SignPetition` / `OfferPetition` / `RenamePetition`
     /// address. `None` = nothing open, and the verb is dropped rather than sent against a guess.
     fn open_item(&self) -> Option<u64> {
@@ -414,6 +420,7 @@ pub(crate) struct UiPetitionPlugin;
 
 impl Plugin for UiPetitionPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         crate::query_cache::register::<PetitionState>(app);
         app.init_resource::<GuildRegistrarState>()
             .init_resource::<PetitionState>()
@@ -435,9 +442,126 @@ impl Plugin for UiPetitionPlugin {
 ///
 /// **Nothing here fires an event or writes a chat line directly.** Composed lines go onto
 /// [`PetitionState::lines`] and the feed drains them, because the red `UI_ERROR_MESSAGE` channel
-/// needs the `script` handle and apply has none (`crate::ui_bank`'s `BankErrors` shape).
-pub(crate) mod apply {
+/// needs the `script` handle and a packet handler has none (`crate::ui_bank`'s `BankErrors`
+/// shape). In the net handler table since 2312.
+pub(crate) mod net {
     use super::*;
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+
+    use crate::net::NetHandlerApp;
+
+    use crate::net::{GuidIndex, ObjectStore, SelfGuid};
+    use crate::ui_social::SocialState;
+
+    /// Register the family's handlers — called from [`UiPetitionPlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::PetitionShowList, on_show_list)
+            .net_handler(K::PetitionShowSignatures, on_show_signatures)
+            .net_handler(K::PetitionQueryResponse, on_query_response)
+            .net_handler(K::PetitionSignResults, on_sign_results)
+            .net_handler(K::TurnInPetitionResults, on_turn_in_results)
+            .net_handler(K::PetitionDeclined, on_declined)
+            .net_handler(K::PetitionRenamed, on_renamed)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    /// The charter window and the registrar die with the socket — a listener on the session end
+    /// (a second handler on the kind, after the bridge's own teardown). Without it the next
+    /// login's fresh VM saw `None → Some` and fired `PETITION_SHOW` for the old session's charter,
+    /// and closing that ghost declined it on the wire. The registrar's walk-away guard cannot
+    /// stand in: it measures from a self player, and there is none until the next world entry.
+    fn on_session_end(
+        In(_): In<SessionEvent>,
+        mut petition: ResMut<PetitionState>,
+        mut registrar: ResMut<GuildRegistrarState>,
+    ) {
+        petition.clear_session();
+        registrar.close();
+    }
+
+    /// The registrar's two `UNIT_NPC_FLAGS` gates are on LIVE NPC state rather than on the
+    /// packet, so the flags are read here, off the store. An unstreamed guid reads `None` and
+    /// fails the gate, as the client's own resolve does.
+    fn on_show_list(
+        In(ev): In<SessionEvent>,
+        mut registrar: ResMut<GuildRegistrarState>,
+        index: Res<GuidIndex>,
+        stores: Query<&ObjectStore>,
+    ) {
+        if let SessionEvent::PetitionShowList(list) = ev {
+            let flags = index
+                .0
+                .get(&list.npc)
+                .and_then(|e| stores.get(*e).ok())
+                .map(|s| s.0.unit_npc_flags());
+            show_list(&mut registrar, list, flags);
+        }
+    }
+
+    /// An ignored owner suppresses the ENTIRE update — no record fetch, no list, no event, no
+    /// error line (`0x5eeefe`). Consulted before anything else happens.
+    fn on_show_signatures(
+        In(ev): In<SessionEvent>,
+        mut petition: ResMut<PetitionState>,
+        social: Res<SocialState>,
+        commands: Res<NetCommands>,
+    ) {
+        if let SessionEvent::PetitionShowSignatures(sigs) = ev {
+            let ignored = social.is_ignored(sigs.owner);
+            show_signatures(&mut petition, sigs, ignored, &commands);
+        }
+    }
+
+    fn on_query_response(In(ev): In<SessionEvent>, mut petition: ResMut<PetitionState>) {
+        if let SessionEvent::PetitionQueryResponse(response) = ev {
+            query_response(&mut petition, response);
+        }
+    }
+
+    fn on_sign_results(
+        In(ev): In<SessionEvent>,
+        mut petition: ResMut<PetitionState>,
+        names: Res<NameCache>,
+        self_guid: Res<SelfGuid>,
+        commands: Res<NetCommands>,
+    ) {
+        if let SessionEvent::PetitionSignResults(results) = ev {
+            sign_results(
+                &mut petition,
+                &names,
+                self_guid.0.unwrap_or(0),
+                results,
+                &commands,
+            );
+        }
+    }
+
+    fn on_turn_in_results(
+        In(ev): In<SessionEvent>,
+        mut petition: ResMut<PetitionState>,
+        mut registrar: ResMut<GuildRegistrarState>,
+    ) {
+        if let SessionEvent::TurnInPetitionResults { result } = ev {
+            turn_in_results(&mut petition, &mut registrar, result);
+        }
+    }
+
+    fn on_declined(
+        In(ev): In<SessionEvent>,
+        mut petition: ResMut<PetitionState>,
+        names: Res<NameCache>,
+    ) {
+        if let SessionEvent::PetitionDeclined { player } = ev {
+            declined(&mut petition, &names, player);
+        }
+    }
+
+    fn on_renamed(In(ev): In<SessionEvent>, mut petition: ResMut<PetitionState>) {
+        if let SessionEvent::PetitionRenamed(rename) = ev {
+            renamed(&mut petition, rename);
+        }
+    }
 
     /// `SMSG_PETITION_SHOWLIST` — the registrar's charter list, subject to its three gates.
     ///
@@ -725,7 +849,7 @@ mod tests {
             min_signatures: 9,
             ..Default::default()
         });
-        apply::renamed(
+        net::renamed(
             &mut petition,
             PetitionRename {
                 item: 0x99,
@@ -735,7 +859,7 @@ mod tests {
         assert_eq!(open_title(&petition), Some("Second"));
 
         // An echo for a charter we do not have open is not ours to apply.
-        apply::renamed(
+        net::renamed(
             &mut petition,
             PetitionRename {
                 item: 0xdead,
@@ -744,4 +868,44 @@ mod tests {
         );
         assert_eq!(open_title(&petition), Some("Second"));
     }
+
+    /// **The charter window and the in-flight sign die with the session.** Only the Lua close,
+    /// a sign result or a turn-in cleared `open`, and a logout's fresh VM never runs the old
+    /// one's `OnHide` — so the next login's feed saw `None → Some` and fired `PETITION_SHOW` into
+    /// the new character's UI, and closing that ghost put `MSG_PETITION_DECLINE` on the wire for
+    /// the old session's charter. Driven through the real registration.
+    #[test]
+    fn the_session_end_closes_the_charter_and_forgets_the_sign() {
+        let (commands, _rx) = commands();
+        let mut app = App::new();
+        app.add_plugins(UiPetitionPlugin);
+        {
+            let mut petition = app.world_mut().resource_mut::<PetitionState>();
+            petition.show(signatures(0x99, 0xaa, 7, &[0xbb]), &commands);
+            petition.signing = true;
+        }
+        app.world_mut()
+            .resource_mut::<GuildRegistrarState>()
+            .open(&show_list(0x2a1f, &[(1000, 1)]), Some(REGISTRAR_NPC_FLAGS));
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![benilla_protocol::SessionEvent::Disconnected {
+                reason: "socket".into(),
+                end: benilla_protocol::SessionEnd::Lost,
+            }],
+        );
+
+        assert_eq!(app.world().resource::<GuildRegistrarState>().npc(), None);
+        let petition = app.world().resource::<PetitionState>();
+        assert_eq!(
+            petition.open_item(),
+            None,
+            "no charter carried into the next login"
+        );
+        assert!(
+            !petition.signing,
+            "no sign of the old session still in flight"
+        );
+    }
 }
diff --git a/crates/benilla-app/src/ui_quest.rs b/crates/benilla-app/src/ui_quest/mod.rs
similarity index 80%
rename from crates/benilla-app/src/ui_quest.rs
rename to crates/benilla-app/src/ui_quest/mod.rs
index 7cfa6928..b3b0e440 100644
--- a/crates/benilla-app/src/ui_quest.rs
+++ b/crates/benilla-app/src/ui_quest/mod.rs
@@ -55,12 +55,23 @@ pub(crate) struct QuestGiver {
     pub(crate) npc: Option<u64>,
     /// The open panel's wire view.
     pub(crate) view: Option<QuestView>,
-    /// The trailing `u32` of the last `SMSG_QUESTGIVER_QUEST_DETAILS`
-    /// ([`benilla_protocol::messages::QuestDetails::auto_finish`]) — the reference's `0xbe0824`,
-    /// a **latch** written by the DETAILS handler rather than a field of the open view, because
-    /// that is the shape the binary has and because its one reader ([`end_quest_session`]) runs
-    /// whichever panel is up. Non-zero suppresses the giver re-open on close (decision 1738).
-    pub(crate) detail_flag: u32,
+    /// The reference's `0xbe0824` — a **latch** written by THREE panel packets, not a field of
+    /// the open view: `SMSG_QUESTGIVER_QUEST_DETAILS`' trailing `u32` (publisher `0x500ef0`,
+    /// `0x50101a`), `SMSG_QUESTGIVER_OFFER_REWARD`'s `u32` after the reward text (the same
+    /// publisher), and `SMSG_QUESTGIVER_REQUEST_ITEMS`' `closeOnCancel` (`0x501070`, `0x50111a`);
+    /// zeroed only by the world-enter reset `0x500af0`. The greeting packet leaves it alone. Its
+    /// one reader is `DeclineQuest`'s fork ([`decline_leg`]), where non-zero diverts a plain
+    /// unit's decline from the giver re-open to the silent teardown — how the server says "this
+    /// panel was not reached through a menu, there is nothing to go back to" (vmangos sends 1 on
+    /// every DETAILS and OFFER_REWARD, and `closeOnCancel` = 1 on a single-quest auto-open,
+    /// 0 on the `COMPLETE_QUEST` path, `QuestHandler.cpp:390-395`).
+    pub(crate) close_on_cancel: u32,
+    /// The reference's "already acted" latch `0xbe0844`: set by every acting leg of
+    /// `AcceptQuest` (`0x5013c9`) and `DeclineQuest` (`0x50147a`/`0x5014d5`/`0x501549`), refusing
+    /// both verbs while set (`0x5013a8`, `0x5013fe`); cleared by each panel publish (`0x500bd0`,
+    /// `0x500d91` — our [`Self::open`]). It matters because a re-opening decline does not tear
+    /// the window down: the panel stays up until the server's answer replaces it.
+    pub(crate) acted: bool,
     /// Per-guid dialog status (`SMSG_QUESTGIVER_STATUS`) — the `!`/`?` marker's value, stored for a
     /// later world-marker slice.
     statuses: HashMap<u64, u32>,
@@ -94,6 +105,8 @@ impl QuestGiver {
     pub(crate) fn open(&mut self, npc: u64, view: QuestView) {
         self.npc = Some(npc);
         self.view = Some(view);
+        // `0x500bd0` clears the already-acted latch on every panel publish (`0x500d91`).
+        self.acted = false;
     }
 
     /// Whether a quest window is currently open (a predicate for callers + the module tests).
@@ -212,6 +225,8 @@ impl QuestGiver {
         self.clear();
         self.statuses.clear();
         self.messages.clear();
+        self.close_on_cancel = 0;
+        self.acted = false;
     }
 }
 
@@ -252,10 +267,13 @@ pub(crate) fn questgiver_failed_key(reason: u32) -> &'static str {
     }
 }
 
+mod net;
+
 pub(crate) struct UiQuestPlugin;
 
 impl Plugin for UiQuestPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<QuestGiver>().add_systems(
             Update,
             (
@@ -314,8 +332,7 @@ impl NpcSession for QuestGiver {
 /// The greeting panel's active-vs-available split — decision 0088's deferred item, now resolved by
 /// the **wire icon**, which is the reference's own and only predicate.
 ///
-/// VERIFIED at the bytes (wow-re `system/ui/scratch/questgiver-quest-pool.md`, dispatched for this;
-/// the split is `0x5dbbfe-0x5dbc08`): `icon == 3 || icon == 4` → ACTIVE, and **every other `u32`** →
+/// The split is `0x5dbbfe-0x5dbc08`: `icon == 3 || icon == 4` → ACTIVE, and **every other `u32`** →
 /// AVAILABLE. A flat two-way `cmp`/`je`, no range test and no third arm — and the client never
 /// consults its own quest log on this path. The values are vmangos's `__QuestGiverStatus`
 /// (`QuestDef.h:118-130`): 3 = `DIALOG_STATUS_INCOMPLETE` (held, unfinished), 4 =
@@ -342,7 +359,7 @@ pub(crate) fn row_is_active(icon: u32) -> bool {
 /// ACTIVE pool's `+0x48` is written literal `0` and read nowhere in the binary — `SelectActiveQuest`
 /// always sends `0x18a`.)
 ///
-/// wow-re flags exactly one thing here as open: whether a real 1.12 server ever emitted `icon == 0`
+/// Exactly one thing here is open: whether a real 1.12 server ever emitted `icon == 0`
 /// on this packet at all — vmangos emits only 2..=5, and its `DIALOG_STATUS_NONE` belongs to the
 /// separate `SMSG_QUESTGIVER_STATUS` path. The arm is byte-verified and correctly wired; only its
 /// live *reachability* is unknown, and the client predicate is total over `u32`, so implementing it
@@ -416,9 +433,8 @@ pub(crate) fn reward_spell_view(
         spell_id,
         name: d.map(|d| d.name.clone()),
         texture: d.and_then(|d| d.icon.clone()),
-        // `isTradeskillSpell` is `Spell.dbc` col 6 `Attributes` bit 5 (`0x20`) — `0x501e59`,
-        // wow-re quest-material-reward-spell-bindings.md §3 (1161 of 22357 rows set; craft-cast
-        // spells set, `Pattern:` teaching spells clear).
+        // `isTradeskillSpell` is `Spell.dbc` col 6 `Attributes` bit 5 (`0x20`) — `0x501e59`
+        // (1161 of 22357 rows set; craft-cast spells set, `Pattern:` teaching spells clear).
         tradeskill: d.is_some_and(|d| d.attributes & 0x20 != 0),
     })
 }
@@ -501,6 +517,7 @@ fn panel_event(panel: QuestPanel) -> &'static str {
 fn feed_quest(
     script: Option<NonSendMut<UiScript>>,
     mut giver: ResMut<QuestGiver>,
+    objects: crate::net::Objects,
     items: Res<Items>,
     icons: Option<Res<ItemDisplays>>,
     commands: Res<NetCommands>,
@@ -552,13 +569,14 @@ fn feed_quest(
         spells.as_deref(),
     );
     // The panel's background material is the SOURCE object's — an item's page material, a
-    // GameObject's template data — never a creature's, and never on the wire (1946; wow-re
-    // quest-material-reward-spell-bindings.md §1). Resolved the way the reader window resolves its
+    // GameObject's template data — never a creature's, and never on the wire (1946;
+    // `GetQuestBackgroundMaterial 0x502230`). Resolved the way the reader window resolves its
     // own, since the two bindings share a body.
     let fresh = fresh.map(|mut st| {
         st.background_material = giver.npc.and_then(|source| {
             crate::ui_item_text::object_material(
                 source,
+                &objects,
                 &items,
                 &go_templates,
                 materials.as_deref(),
@@ -611,60 +629,84 @@ fn feed_quest(
     *last_npc = giver.npc;
 }
 
-/// Drain the Lua intents: the greeting-row selects (map to the row's quest id → QUERY_QUEST for an
-/// available quest, COMPLETE_QUEST for an active one) and the button actions (Accept/Continue/Reward
-/// → the matching CMSG; Close → a local clear, no packet).
-/// **The quest session's one end** — the reference's `0x501130`, which every way out of the
-/// questgiver window funnels through: `DeclineQuest()`, `CloseQuest()` (ESC, the window's own
-/// OnHide), the walk-away watchdog and the leave-world teardown are four of its eleven callers, and
-/// they all do the same thing. That is why benilla models one [`QuestAction::Close`] and not the
-/// `Decline`/`Close` pair 1733 briefly split it into: two Lua verbs, one routine (decision 1738,
-/// VERIFIED by the wow-re §5 dispatched for 1733).
+/// `CloseQuest()` — the teardown `0x501130(0,1)` its binding `0x501a10` calls and nothing else:
+/// a PLAYER source — a party member whose shared quest we are walking away from — is answered
+/// `MSG_QUEST_PUSH_RESULT{DECLINE_QUEST}`; every other source is closed **network-silently**.
+/// There is no giver re-open here: that lives only in `DeclineQuest`'s fork ([`decline_leg`]).
+/// 1738 put the two verbs on one routine and so re-opened an NPC's list on ESC, which is the
+/// reason a multi-quest greeting could not be closed.
 ///
-/// It sends, and what it sends depends on **the giver's object type**, not on which button was
-/// pressed:
-///
-/// - **A player** — a party member whose shared quest we are turning down. The answer they are
-///   waiting on: `MSG_QUEST_PUSH_RESULT{sharerGuid, DECLINE_QUEST}`. This is the only verdict the
-///   client ever originates besides `BUSY`.
-/// - **A unit** — an ordinary questgiver, and the reference **re-opens its list**:
-///   `CMSG_GOSSIP_HELLO` for a gossip-flagged NPC, `CMSG_QUESTGIVER_HELLO` otherwise. Declining a
-///   quest putting you back in the NPC's menu is not a courtesy the server does; it is this send.
-///   benilla asserted the opposite in `QuestFrame.xml` ("vanilla's client-side decline sends no
-///   packet") from 0088 until 1738 refuted it at the bytes.
-///
-/// `detail_flag` suppresses the unit re-open when non-zero — the trailing `u32` of
-/// `SMSG_QUESTGIVER_QUEST_DETAILS` ([`QuestDetails::auto_finish`]), whose only reader in the whole
-/// image is this routine. `npc_flags` is `None` when the giver is not a streamed unit, which is
-/// also how an item giver (0664) and a player fall out of the unit branch.
-fn end_quest_session(npc: u64, detail_flag: u32, npc_flags: Option<u32>, commands: &NetCommands) {
+/// The PLAYER test is the guid's shape, as in [`QuestGiver::walk_away_send`]; the reference's
+/// `0x468460(typemask 0x10)` also requires the sharer to resolve, which a sharer out of view does
+/// not — a case the range guard closes on its own first.
+fn close_quest(npc: u64, commands: &NetCommands) {
     if benilla_protocol::guid::is_player(npc) {
-        debug!("ui_quest: declining {npc:#x}'s shared quest");
+        debug!("ui_quest: closing {npc:#x}'s shared quest — declining it");
         let _ = commands.0.send(ClientCommand::QuestPushResult {
             sharer: npc,
             msg: QuestShareMsg::DECLINE_QUEST,
         });
-        return;
-    }
-    let Some(flags) = npc_flags else {
-        // Not a streamed unit: an item giver, or an NPC that left view under the open window.
-        // Nothing to re-open and nobody to answer.
-        debug!("ui_quest: close on non-unit giver {npc:#x} (no packet)");
-        return;
-    };
-    if detail_flag != 0 {
-        debug!("ui_quest: close on {npc:#x} — detail flag {detail_flag} suppresses the re-open");
-        return;
-    }
-    if flags & crate::target::cursor_mode::npc_flags::GOSSIP != 0 {
-        debug!("ui_quest: close on {npc:#x} — re-opening the gossip menu");
-        let _ = commands.0.send(ClientCommand::GossipHello { guid: npc });
-    } else {
-        debug!("ui_quest: close on {npc:#x} — re-opening the quest list");
-        let _ = commands.0.send(ClientCommand::QuestgiverHello { npc });
     }
 }
 
+/// What `DeclineQuest()` does — the leg of its core `0x5013f0` a source takes.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum DeclineLeg {
+    /// The already-acted latch is set (`0x5013fe`), or the source does not resolve (`0x50142c`):
+    /// nothing at all — no send, no teardown.
+    Nothing,
+    /// The teardown `0x501130(0,1)` (`0x5014aa`): answers a PLAYER sharer, closes the window.
+    Teardown,
+    /// A gossip-flagged unit (`0x50143b`-`0x501474`): `CMSG_GOSSIP_HELLO`; the window stays.
+    GossipHello,
+    /// A plain unit (`0x5014e4`-`0x501526`): `CMSG_QUESTGIVER_HELLO`; the window stays.
+    QuestgiverHello,
+}
+
+/// **`DeclineQuest`'s fork** — its binding `0x501d30` calls `0x5013f0`, the one routine that
+/// re-opens a giver (`0x5013f0`-`0x501553`),
+/// tested in this order:
+///
+/// 1. the already-acted latch `0xbe0844` set, or the source unresolvable → nothing;
+/// 2. a UNIT whose `UNIT_NPC_FLAGS` carries GOSSIP → `CMSG_GOSSIP_HELLO` — **before** the
+///    `0xbe0824` test, so a gossip NPC is re-opened whatever the latch says;
+/// 3. an ITEM, a PLAYER, or `0xbe0824 != 0` → the teardown `0x501130(0,1)`, which answers a
+///    sharer and is silent otherwise;
+/// 4. a GAMEOBJECT → its interact virtual `[vtbl+0x60]` (`0x5014d0`);
+/// 5. any other unit → `CMSG_QUESTGIVER_HELLO`, which re-opens the quest list.
+///
+/// Legs 2, 4 and 5 set `0xbe0844` and do NOT tear the window down: the server's answer replaces
+/// the panel. **Leg 4 is modelled as the teardown**: the call site is the generic interact
+/// virtual, but `CGGameObject_C`'s override of it is not identified, so what goes on the wire is
+/// unknown; a silent close is the one outcome that cannot leave a dead window up.
+///
+/// `npc_flags` is the giver's live `UNIT_NPC_FLAGS`, `None` when it does not resolve to a streamed
+/// object. An item giver (0664) is taken by its guid's shape: it lives in our bags, where the
+/// reference always resolves it. A player is taken by shape too, as in [`close_quest`].
+fn decline_leg(npc: u64, acted: bool, close_on_cancel: u32, npc_flags: Option<u32>) -> DeclineLeg {
+    use benilla_protocol::guid;
+    if acted {
+        return DeclineLeg::Nothing;
+    }
+    if guid::is_player(npc) || guid::is_item(npc) {
+        return DeclineLeg::Teardown;
+    }
+    let Some(flags) = npc_flags else {
+        return DeclineLeg::Nothing;
+    };
+    let unit = guid::is_creature_or_pet(npc);
+    if unit && flags & crate::target::cursor_mode::npc_flags::GOSSIP != 0 {
+        return DeclineLeg::GossipHello;
+    }
+    if close_on_cancel != 0 || !unit {
+        return DeclineLeg::Teardown;
+    }
+    DeclineLeg::QuestgiverHello
+}
+
+/// Drain the Lua intents: the greeting-row selects (map to the row's quest id → QUERY_QUEST for an
+/// available quest, COMPLETE_QUEST for an active one) and the button actions (Accept/Continue/Reward
+/// → the matching CMSG; Decline → [`decline_leg`]; Close → [`close_quest`]).
 fn drain_quest(
     script: Option<NonSendMut<UiScript>>,
     mut giver: ResMut<QuestGiver>,
@@ -682,7 +724,7 @@ fn drain_quest(
         script.take_quest_actions();
         return;
     };
-    // The giver's live `UNIT_NPC_FLAGS`, for [`end_quest_session`]'s gossip/quest-list fork.
+    // The giver's live `UNIT_NPC_FLAGS`, for [`decline_leg`]'s gossip/quest-list fork.
     // `None` for anything that is not a streamed unit — an item giver, a player, a despawn.
     let npc_flags = index
         .0
@@ -731,11 +773,35 @@ fn drain_quest(
     for action in script.take_quest_actions() {
         match action {
             QuestAction::Close => {
-                end_quest_session(npc, giver.detail_flag, npc_flags, &commands);
+                close_quest(npc, &commands);
                 giver.clear();
             }
+            QuestAction::Decline => {
+                let leg = decline_leg(npc, giver.acted, giver.close_on_cancel, npc_flags);
+                debug!("ui_quest: decline on {npc:#x} — {leg:?}");
+                match leg {
+                    DeclineLeg::Nothing => {}
+                    DeclineLeg::Teardown => {
+                        close_quest(npc, &commands);
+                        giver.clear();
+                    }
+                    DeclineLeg::GossipHello => {
+                        let _ = commands.0.send(ClientCommand::GossipHello { guid: npc });
+                        giver.acted = true;
+                    }
+                    DeclineLeg::QuestgiverHello => {
+                        let _ = commands.0.send(ClientCommand::QuestgiverHello { npc });
+                        giver.acted = true;
+                    }
+                }
+            }
             QuestAction::Accept => {
+                // `0x501380` refuses while the already-acted latch is set (`0x5013a8`).
+                if giver.acted {
+                    continue;
+                }
                 if let Some(quest) = view_quest {
+                    giver.acted = true;
                     let _ = commands
                         .0
                         .send(ClientCommand::QuestgiverAccept { npc, quest });
@@ -1078,15 +1144,26 @@ mod tests {
 
     // ── The party share's one client-originated verdict (decision 1733) ──────────────────────────
 
-    /// Run `lua` against a quest window open on `giver`, and return what the drain sent.
+    /// Run `lua` against a quest window open on `giver` with the `0xbe0824` latch at
+    /// `close_on_cancel`, and return what the drain sent.
     /// `npc_flags` seats the giver as a streamed unit with those `UNIT_NPC_FLAGS`; `None` leaves it
     /// unstreamed (an item giver, or an NPC that left view).
     fn drain_after(
         giver: u64,
         npc_flags: Option<u32>,
-        detail_flag: u32,
+        close_on_cancel: u32,
         lua: &str,
     ) -> Vec<ClientCommand> {
+        drain_world(giver, npc_flags, close_on_cancel, lua).1
+    }
+
+    /// [`drain_after`], keeping the world so a test can read the [`QuestGiver`] afterwards.
+    fn drain_world(
+        giver: u64,
+        npc_flags: Option<u32>,
+        close_on_cancel: u32,
+        lua: &str,
+    ) -> (App, Vec<ClientCommand>) {
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut app = App::new();
         app.insert_resource(NetCommands(tx));
@@ -1100,10 +1177,7 @@ mod tests {
                 .0
                 .insert(giver, e);
         }
-        let mut quest = QuestGiver {
-            detail_flag,
-            ..Default::default()
-        };
+        let mut quest = QuestGiver::default();
         quest.open(
             giver,
             QuestView::Detail(QuestDetails {
@@ -1112,29 +1186,32 @@ mod tests {
                 title: "A Threat Within".into(),
                 details: String::new(),
                 objectives: String::new(),
-                auto_finish: detail_flag,
+                auto_finish: close_on_cancel,
                 choices: Vec::new(),
                 rewards: Vec::new(),
                 money: 0,
                 reward_spell: 0,
             }),
         );
+        // The latch is written by the packet, after the open (as `net::quest_detail` does).
+        quest.close_on_cancel = close_on_cancel;
         app.insert_resource(quest);
         let script = UiScript::new().unwrap();
         script.run(lua).unwrap();
         app.insert_non_send_resource(script);
         app.add_systems(Update, drain_quest);
         app.update();
-        rx.try_iter().collect()
+        let sent = rx.try_iter().collect();
+        (app, sent)
     }
 
     const SHARER: u64 = 0x0000_0000_0000_002A; // HIGHGUID_PLAYER: a zero high word
     const NPC: u64 = 0xF130_0000_0000_0007; // HIGHGUID_UNIT
 
     /// **Ending the session on a SHARED quest answers the sharer — and `CloseQuest` does it too.**
-    /// 1733 shipped these as two actions on the assumption that only `DeclineQuest` answered; the
-    /// §5 found both Lua verbs calling one routine (`0x501130`), so ESC-ing a share panel reports
-    /// the decline exactly as the button does. This test is the corrected form of 1733's
+    /// 1733 shipped these as two actions on the assumption that only `DeclineQuest` answered; both
+    /// Lua verbs reach the teardown `0x501130(0,1)` (`CloseQuest` directly, `DeclineQuest` through
+    /// its PLAYER leg), so ESC-ing a share panel reports the decline exactly as the button does. This test is the corrected form of 1733's
     /// `closing_a_shared_quest_panel_is_not_a_decline`, which asserted the opposite.
     #[test]
     fn every_way_out_of_a_shared_quest_answers_the_sharer() {
@@ -1153,8 +1230,8 @@ mod tests {
         }
     }
 
-    /// **Ending it on an NPC RE-OPENS the giver**, which benilla asserted for years that it did not
-    /// ("vanilla's client-side decline sends no packet"). The fork is on the NPC's own gossip flag:
+    /// **`DeclineQuest` on an NPC RE-OPENS the giver**, which benilla asserted for years that it did
+    /// not ("vanilla's client-side decline sends no packet"). The fork is on the NPC's own gossip flag:
     /// `CMSG_GOSSIP_HELLO` for a gossip-flagged NPC, `CMSG_QUESTGIVER_HELLO` otherwise. This is the
     /// mechanism behind the reference putting you back in the questgiver's menu after a decline.
     #[test]
@@ -1177,20 +1254,103 @@ mod tests {
         );
     }
 
-    /// The DETAILS packet's trailing `u32` **suppresses** that re-open when non-zero — the field
-    /// benilla parsed and ignored until the §5 found its one reader. Ignoring it meant a
+    /// The `0xbe0824` latch **suppresses** a plain unit's re-open when non-zero — the field
+    /// benilla parsed and ignored until its one reader (`0x5014a2`) was found. Ignoring it meant a
     /// suppressed giver was re-opened anyway.
     #[test]
-    fn a_non_zero_detail_flag_suppresses_the_reopen() {
+    fn a_non_zero_latch_suppresses_a_plain_units_reopen() {
         let sent = drain_after(NPC, Some(0), 1, "DeclineQuest()");
         assert!(sent.is_empty(), "flag 1 suppresses the re-open: {sent:?}");
     }
 
-    /// A giver that is not a streamed unit sends nothing at all: an item giver (0664) has no list
-    /// to re-open, and neither does an NPC that walked out of view under the open window.
+    /// A giver that does not resolve sends nothing at all. `CloseQuest` still tears the window
+    /// down; `DeclineQuest` bails before its fork (`0x50142c`) and leaves it — the range guard
+    /// closes a window whose giver has gone.
     #[test]
     fn an_unstreamed_giver_ends_the_session_silently() {
-        let sent = drain_after(NPC, None, 0, "CloseQuest()");
+        let (app, sent) = drain_world(NPC, None, 0, "CloseQuest()");
         assert!(sent.is_empty(), "no unit, no re-open: {sent:?}");
+        assert!(!app.world().resource::<QuestGiver>().is_open());
+
+        let (app, sent) = drain_world(NPC, None, 0, "DeclineQuest()");
+        assert!(sent.is_empty(), "{sent:?}");
+        assert!(app.world().resource::<QuestGiver>().is_open());
+    }
+
+    /// An item giver (0664) takes the teardown leg: silent, and the window closes.
+    #[test]
+    fn declining_an_item_quest_closes_silently() {
+        const ITEM: u64 = 0x4000_0000_0000_0099; // HIGHGUID_ITEM
+        let (app, sent) = drain_world(ITEM, None, 0, "DeclineQuest()");
+        assert!(sent.is_empty(), "{sent:?}");
+        assert!(!app.world().resource::<QuestGiver>().is_open());
+    }
+
+    /// **`CloseQuest()` is network-silent on an NPC** — ESC, the X, the greeting's Goodbye
+    /// (`HideUIPanel` → `QuestFrame_OnHide` → `CloseQuest`). Its binding `0x501a10` calls the
+    /// teardown `0x501130(0,1)` and nothing else, whose one send is the PLAYER-filtered push
+    /// result. It used to share `DeclineQuest`'s action and so re-open the list the player was
+    /// trying to close (a multi-quest NPC's greeting could not be dismissed).
+    #[test]
+    fn close_quest_on_an_npc_is_network_silent() {
+        use crate::target::cursor_mode::npc_flags;
+        for flags in [0, npc_flags::GOSSIP] {
+            for latch in [0, 1] {
+                let (app, sent) = drain_world(NPC, Some(flags), latch, "CloseQuest()");
+                assert!(
+                    sent.is_empty(),
+                    "CloseQuest on an NPC (flags {flags:#x}, latch {latch}) sends nothing: {sent:?}"
+                );
+                assert!(
+                    !app.world().resource::<QuestGiver>().is_open(),
+                    "…and tears the window down"
+                );
+            }
+        }
+    }
+
+    /// `DeclineQuest`'s gossip leg (`0x50143b`-`0x501474`) is tested BEFORE the `0xbe0824` latch
+    /// (`0x5014a2`), so a gossip-flagged NPC is re-opened whatever the latch says.
+    #[test]
+    fn the_gossip_leg_precedes_the_latch() {
+        use crate::target::cursor_mode::npc_flags;
+        let sent = drain_after(NPC, Some(npc_flags::GOSSIP), 1, "DeclineQuest()");
+        assert!(
+            matches!(sent.as_slice(), [ClientCommand::GossipHello { guid: NPC }]),
+            "a latched gossip NPC still gets GOSSIP_HELLO: {sent:?}"
+        );
+    }
+
+    /// The re-open legs do NOT tear the window down (no `0x501130` on them) — the server's answer
+    /// replaces the panel — and they set the already-acted latch `0xbe0844`, which refuses a
+    /// second `DeclineQuest` and an `AcceptQuest` until the next panel arrives.
+    #[test]
+    fn a_reopening_decline_keeps_the_window_and_latches_acted() {
+        let (app, sent) = drain_world(
+            NPC,
+            Some(0),
+            0,
+            "DeclineQuest() DeclineQuest() AcceptQuest()",
+        );
+        assert!(
+            matches!(
+                sent.as_slice(),
+                [ClientCommand::QuestgiverHello { npc: NPC }]
+            ),
+            "one re-open, and nothing after it: {sent:?}"
+        );
+        let giver = app.world().resource::<QuestGiver>();
+        assert!(
+            giver.is_open(),
+            "the window stays up for the server's answer"
+        );
+    }
+
+    /// The latch-diverted leg (`0x5014aa` → `0x501130(0,1)`) DOES tear the window down.
+    #[test]
+    fn a_latched_decline_closes_the_window() {
+        let (app, sent) = drain_world(NPC, Some(0), 1, "DeclineQuest()");
+        assert!(sent.is_empty(), "{sent:?}");
+        assert!(!app.world().resource::<QuestGiver>().is_open());
     }
 }
diff --git a/crates/benilla-app/src/net/apply/quests.rs b/crates/benilla-app/src/ui_quest/net.rs
similarity index 62%
rename from crates/benilla-app/src/net/apply/quests.rs
rename to crates/benilla-app/src/ui_quest/net.rs
index e65d5e57..b9ff5b69 100644
--- a/crates/benilla-app/src/net/apply/quests.rs
+++ b/crates/benilla-app/src/ui_quest/net.rs
@@ -1,30 +1,172 @@
-//! Questgiver-panel + quest-log arm bodies for [`super::apply_net_updates`]'s dispatch match — the
-//! largest arm family, split out on its own (decision 0088's panels + its deferred quest-log/toast
-//! slice). Each `pub(super)` fn here is exactly one arm's body; the match at the call site stays the
-//! dispatcher, one call per arm.
+//! The questgiver panels' packet handlers (decision 0088; in the net handler table since 2320,
+//! moved out of the drain's quests arm file) — each fills the [`QuestGiver`] the quest feed
+//! ([`super`]) reads; each panel packet replaces the open view, and the greeting/gossip quest-row
+//! clicks and the panel buttons flow back out through the quest/gossip drains. The quest log's
+//! template answer is [`crate::ui_quest_log`]'s and the party share's pair is
+//! [`crate::ui_quest_share`]'s.
 
 use benilla_protocol::messages::{
-    QuestComplete, QuestConfirmAccept, QuestDetails, QuestGiverList, QuestOfferReward,
-    QuestRequestItems, QuestShareMsg, QuestTemplate,
+    QuestComplete, QuestDetails, QuestGiverList, QuestOfferReward, QuestRequestItems, QuestShareMsg,
 };
+use benilla_protocol::{SessionEvent, SessionEventKind};
 use bevy::prelude::*;
 
+use super::QuestGiver;
+use crate::net::{ClientCommand, NetCommands, NetHandlerApp};
 use crate::ui_action::UiError;
-use crate::ui_quest::QuestGiver;
 use crate::ui_quest_log::QuestLog;
-use crate::ui_quest_share::QuestShare;
 
-use super::super::{ClientCommand, NetCommands};
+/// Register the questgiver handlers — called from [`super::UiQuestPlugin`]. One per kind, plus
+/// the session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::QuestGiverStatus, on_giver_status)
+        .net_handler(K::QuestGreeting, on_greeting)
+        .net_handler(K::QuestDetail, on_detail)
+        .net_handler(K::QuestProgress, on_progress)
+        .net_handler(K::QuestOffer, on_offer)
+        .net_handler(K::QuestComplete, on_complete)
+        .net_handler(K::QuestObjectiveKill, on_objective_kill)
+        .net_handler(K::QuestObjectiveItem, on_objective_item)
+        .net_handler(K::QuestObjectivesComplete, on_objectives_complete)
+        .net_handler(K::QuestFailed, on_failed)
+        .net_handler(K::QuestLogFull, on_log_full)
+        .net_handler(K::QuestGiverInvalid, on_giver_invalid)
+        .net_handler(K::QuestGiverFailed, on_giver_failed)
+        .net_handler(K::Disconnected, on_session_end)
+        .net_handler(K::Connected, on_login)
+        .net_handler(K::Worldport, on_worldport);
+}
+
+/// The world-enter reset `0x500af0` (sole caller `0x49099c`, inside the enter-world cascade
+/// `0x4908c0` that runs on a fresh login and on every worldport) zeroes the `0xbe0824` latch —
+/// its only clear (`0x500af0`). A second listener on each kind, after the bridge's.
+fn on_login(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::Connected { .. } = ev {
+        world_enter_reset(&mut quest);
+    }
+}
+
+/// [`on_login`]'s twin for the other entry into the cascade, the worldport.
+fn on_worldport(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::Worldport { .. } = ev {
+        world_enter_reset(&mut quest);
+    }
+}
+
+fn world_enter_reset(quest: &mut QuestGiver) {
+    quest.close_on_cancel = 0;
+}
+
+fn on_giver_status(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestGiverStatus { npc, status } = ev {
+        quest_giver_status(npc, status, &mut quest);
+    }
+}
+
+fn on_greeting(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestGreeting(list) = ev {
+        quest_greeting(list, &mut quest);
+    }
+}
+
+fn on_detail(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>, commands: Res<NetCommands>) {
+    if let SessionEvent::QuestDetail(d) = ev {
+        quest_detail(d, &mut quest, &commands);
+    }
+}
+
+fn on_progress(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestProgress(p) = ev {
+        quest_progress(p, &mut quest);
+    }
+}
+
+fn on_offer(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestOffer(o) = ev {
+        quest_offer(o, &mut quest);
+    }
+}
+
+fn on_complete(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestComplete(c) = ev {
+        quest_complete(c, &mut quest);
+    }
+}
+
+fn on_objective_kill(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestObjectiveKill {
+        quest_id: _,
+        entry,
+        count,
+        required,
+    } = ev
+    {
+        quest_objective_kill(entry, count, required, &mut quest);
+    }
+}
+
+fn on_objective_item(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestObjectiveItem { item_id, count } = ev {
+        quest_objective_item(item_id, count, &mut quest);
+    }
+}
+
+fn on_objectives_complete(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestObjectivesComplete { quest_id } = ev {
+        quest_objectives_complete(quest_id, &mut quest);
+    }
+}
+
+fn on_failed(
+    In(ev): In<SessionEvent>,
+    mut quest: ResMut<QuestGiver>,
+    mut quest_log: ResMut<QuestLog>,
+    commands: Res<NetCommands>,
+) {
+    if let SessionEvent::QuestFailed { quest_id, timed } = ev {
+        quest_failed(quest_id, timed, &mut quest_log, &commands, &mut quest);
+    }
+}
+
+fn on_log_full(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestLogFull = ev {
+        quest_log_full(&mut quest);
+    }
+}
+
+fn on_giver_invalid(In(ev): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    if let SessionEvent::QuestGiverInvalid { reason } = ev {
+        quest_giver_invalid(reason, &mut quest);
+    }
+}
+
+fn on_giver_failed(
+    In(ev): In<SessionEvent>,
+    mut quest: ResMut<QuestGiver>,
+    mut quest_log: ResMut<QuestLog>,
+    commands: Res<NetCommands>,
+) {
+    if let SessionEvent::QuestGiverFailed { quest_id, reason } = ev {
+        quest_giver_failed(quest_id, reason, &mut quest, &mut quest_log, &commands);
+    }
+}
+
+/// An open questgiver panel dies with the socket. A listener on the session end
+/// (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut quest: ResMut<QuestGiver>) {
+    quest.clear_session();
+}
 
 /// A questgiver dialog status for one NPC (`SMSG_QUESTGIVER_STATUS`) — the `!`/`?` marker's
 /// [`crate::messages::dialog_status`] value, stored per guid for the marker layer and the minimap
 /// quest dot.
 ///
-/// **A GameObject's answer is DROPPED, and that is the reference's own behaviour** (decision 1872,
-/// wow-re `questgiver-marker.md` §W14.1): the handler `0x5dc9f0` resolves the packet's GUID with
-/// `0x5dca22 mov ecx,8` — typemask `TYPEMASK_UNIT` — and `0x468460` is a bitmask AND against
-/// `OBJECT_FIELD_TYPE`, so a GameObject's `0x21` misses bit 3, returns NULL, and the handler exits
-/// at `0x5dca2f` without ever reaching the `UNIT_NPC_FLAGS` test, let alone the marker.
+/// **A GameObject's answer is DROPPED, and that is the reference's own behaviour** (decision
+/// 1872): the handler `0x5dc9f0` resolves the packet's GUID with `0x5dca22 mov ecx,8` — typemask
+/// `TYPEMASK_UNIT` — and `0x468460` is a bitmask AND against `OBJECT_FIELD_TYPE`, so a
+/// GameObject's `0x21` misses bit 3, returns NULL, and the handler exits at `0x5dca2f` without
+/// ever reaching the `UNIT_NPC_FLAGS` test, let alone the marker.
 ///
 /// This is not a hypothetical branch here: benilla now *sends* the query for quest-flagged
 /// GameObjects, exactly as the reference does ([`crate::quest_markers`]), and **vmangos answers
@@ -33,14 +175,17 @@ use super::super::{ClientCommand, NetCommands};
 /// So the drop is what keeps a vmangos-only answer from putting a `!` over a wanted poster that
 /// the reference client leaves bare.
 ///
-/// The test is the GUID's own shape rather than a live type lookup on purpose: it gives the same
-/// partition as typemask 8 for anything a server can send us, and it cannot be defeated by a status
-/// that arrives in the same drain as its object's create block (descriptors are flushed at the end
-/// of the drain, so a type test would read a not-yet-seeded store and drop a *unit's* answer that
-/// would then never be re-asked for). The reference's second conjunct — `UNIT_NPC_FLAGS & 0x2` on
-/// the resolved unit — is deliberately not modelled here for that same ordering reason;
-/// [`crate::quest_markers::query`]'s teardown leg covers the flag-clearing case from the other end.
-pub(super) fn quest_giver_status(npc: u64, status: u32, quest: &mut QuestGiver) {
+/// The test is the GUID's own shape rather than a live type lookup: it gives the same partition
+/// as typemask 8 for anything a server can send us. It was chosen when this was an arm of the
+/// drain's match, where a status arriving in the same drain as its object's create block would
+/// have read a not-yet-seeded store (descriptors were flushed at the end of the drain) and
+/// dropped a *unit's* answer that would then never be re-asked for. As a packet handler it runs
+/// after the create has landed (decision 2306), so that reason is gone; the shape test stays
+/// because it is the same partition. The reference's second conjunct — `UNIT_NPC_FLAGS & 0x2` on
+/// the resolved unit — was left unmodelled for the same ordering reason and is buildable now;
+/// until it is, [`crate::quest_markers::query`]'s teardown leg covers the flag-clearing case from
+/// the other end.
+fn quest_giver_status(npc: u64, status: u32, quest: &mut QuestGiver) {
     use benilla_protocol::guid;
     if !(guid::is_player(npc) || guid::is_creature_or_pet(npc)) {
         debug!("net: dropping a non-unit questgiver status ({npc:#x} → {status}) — typemask 8");
@@ -51,7 +196,7 @@ pub(super) fn quest_giver_status(npc: u64, status: u32, quest: &mut QuestGiver)
 }
 
 /// The greeting panel: an NPC's offered/active quest rows (`SMSG_QUESTGIVER_QUEST_LIST`).
-pub(super) fn quest_greeting(list: QuestGiverList, quest: &mut QuestGiver) {
+fn quest_greeting(list: QuestGiverList, quest: &mut QuestGiver) {
     debug!(
         "net: quest greeting on {:#x} — {} quests",
         list.npc,
@@ -61,7 +206,7 @@ pub(super) fn quest_greeting(list: QuestGiverList, quest: &mut QuestGiver) {
 }
 
 /// The accept panel: full quest text + rewards on offer (`SMSG_QUESTGIVER_QUEST_DETAILS`).
-pub(super) fn quest_detail(d: QuestDetails, quest: &mut QuestGiver, commands: &NetCommands) {
+fn quest_detail(d: QuestDetails, quest: &mut QuestGiver, commands: &NetCommands) {
     debug!("net: quest detail — quest {} on {:#x}", d.quest_id, d.npc);
     // **A share that arrives on top of an open window is refused, by the client** (`0x5dbf85`,
     // decision 1738): `MSG_QUEST_PUSH_RESULT{sharer, BUSY}` and the panel we are reading stays.
@@ -79,32 +224,37 @@ pub(super) fn quest_detail(d: QuestDetails, quest: &mut QuestGiver, commands: &N
         });
         return;
     }
-    // The trailing flag is a latch, not a field of the view (see `QuestGiver::detail_flag`).
-    quest.detail_flag = d.auto_finish;
+    // The trailing flag is a latch, not a field of the view (see `QuestGiver::close_on_cancel`).
+    quest.close_on_cancel = d.auto_finish;
     quest.open(d.npc, crate::ui_quest::QuestView::Detail(d));
 }
 
 /// The progress panel: "bring me these" text + required items/money + completability
 /// (`SMSG_QUESTGIVER_REQUEST_ITEMS`).
-pub(super) fn quest_progress(p: QuestRequestItems, quest: &mut QuestGiver) {
+fn quest_progress(p: QuestRequestItems, quest: &mut QuestGiver) {
     debug!(
         "net: quest progress — quest {} on {:#x} (complete: {})",
         p.quest_id, p.npc, p.is_complete
     );
+    // The progress publisher `0x501070` writes `closeOnCancel` into the same latch (`0x50111a`).
+    quest.close_on_cancel = p.close_on_cancel;
     quest.open(p.npc, crate::ui_quest::QuestView::Progress(p));
 }
 
 /// The reward panel: turn-in text + rewards to grant (`SMSG_QUESTGIVER_OFFER_REWARD`).
-pub(super) fn quest_offer(o: QuestOfferReward, quest: &mut QuestGiver) {
+fn quest_offer(o: QuestOfferReward, quest: &mut QuestGiver) {
     debug!(
         "net: quest reward offer — quest {} on {:#x}",
         o.quest_id, o.npc
     );
+    // The `u32` after the reward text lands in the same latch as DETAILS' trailing one — one
+    // publisher, `0x500ef0` (`0x50101a`).
+    quest.close_on_cancel = o.auto_finish;
     quest.open(o.npc, crate::ui_quest::QuestView::Reward(o));
 }
 
 /// The turn-in result: XP/money granted + fixed items (`SMSG_QUESTGIVER_QUEST_COMPLETE`).
-pub(super) fn quest_complete(c: QuestComplete, quest: &mut QuestGiver) {
+fn quest_complete(c: QuestComplete, quest: &mut QuestGiver) {
     // The completion fanfare (QUESTCOMPLETED kit → iQuestComplete.wav) — the client's C++ plays
     // it on exactly this packet; the giver feed drains the flag into the UI sound path.
     quest.completed_fanfare = true;
@@ -123,13 +273,6 @@ pub(super) fn quest_complete(c: QuestComplete, quest: &mut QuestGiver) {
     quest.bump_reask();
 }
 
-/// The full quest template (`SMSG_QUEST_QUERY_RESPONSE`, answering our `CMSG_QUEST_QUERY`) — the
-/// quest log's ask-once detail source, cached by `quest_id`.
-pub(super) fn quest_template(t: Box<QuestTemplate>, quest_log: &mut QuestLog) {
-    debug!("net: quest template {} ({})", t.quest_id, t.title);
-    quest_log.insert_template(*t);
-}
-
 /// A kill/use objective ticked (`SMSG_QUESTUPDATE_ADD_KILL`) / an item-collection tick
 /// (`SMSG_QUESTUPDATE_ADD_ITEM`). The visible surface — the yellow `UI_INFO_MESSAGE` toast, the
 /// ref's `ERR_QUEST_ADD_*_SII` popups — no longer fires from here: it rides the quest-log
@@ -137,15 +280,15 @@ pub(super) fn quest_template(t: Box<QuestTemplate>, quest_log: &mut QuestLog) {
 /// same descriptor/template/bag state the SMSG announces (the wire's item tick carries only the
 /// ADDED count — the "cur/req" is client-computed either way, the wire pin's finding). The old
 /// chat-line stopgap here is retired: the reference shows no chat echo for objective progress
-/// (INFERRED from ref screenshots; the dispatched §5 adjudicates, and this fn is the fold-back
-/// seat if the real handler does more — a sound, a distinct format).
-pub(super) fn quest_objective_kill(entry: u32, count: u32, required: u32, quest: &mut QuestGiver) {
+/// (inferred from reference screenshots, unconfirmed in the binary; if the real handler does
+/// more, a sound or a distinct format, it goes here).
+fn quest_objective_kill(entry: u32, count: u32, required: u32, quest: &mut QuestGiver) {
     debug!("net: quest kill/use objective {entry:#x} at {count}/{required}");
     quest.bump_reask();
 }
 
 /// See [`quest_objective_kill`] — same surface, item flavor.
-pub(super) fn quest_objective_item(item_id: u32, count: u32, quest: &mut QuestGiver) {
+fn quest_objective_item(item_id: u32, count: u32, quest: &mut QuestGiver) {
     debug!("net: quest item objective {item_id} +{count}");
     quest.bump_reask();
 }
@@ -155,7 +298,7 @@ pub(super) fn quest_objective_item(item_id: u32, count: u32, quest: &mut QuestGi
 /// kind-1 → UI_INFO_MESSAGE, never a chat line) — rides the quest-log diff's COMPLETE-flip
 /// detection (`crate::ui_quest_log::feed_quest_log`), same as the progress toasts; the slot's
 /// state byte carries the durable fact.
-pub(super) fn quest_objectives_complete(quest_id: u32, quest: &mut QuestGiver) {
+fn quest_objectives_complete(quest_id: u32, quest: &mut QuestGiver) {
     debug!("net: quest {quest_id} objectives complete");
     // The turn-in `?` can go gold with no quest-log field change of its own, so the reference
     // sweeps from these `SMSG_QUESTUPDATE_*` handlers (0654).
@@ -168,8 +311,7 @@ pub(super) fn quest_objectives_complete(quest_id: u32, quest: &mut QuestGiver) {
 ///
 /// **An uncached template is SILENT, and that is the handler's own gate rather than a fallback.**
 /// `0x5e5ad0`'s FAILED arm reads the questId, then *bails* if the template is not in the cache (or
-/// if the per-slot flag `byte[slot+7]&2` is set) — it never reaches `0x496720` (wow-re
-/// `object-layer/scratch/quest-update-ui-feedback-law.md` §"Per-opcode behaviour"). This used to
+/// if the per-slot flag `byte[slot+7]&2` is set) — it never reaches `0x496720`. This used to
 /// compose `"Quest failed."` there, a sentence 1.12 has no string for and never says (decision
 /// 2045 named it as one of two remaining inventions).
 ///
@@ -178,7 +320,7 @@ pub(super) fn quest_objectives_complete(quest_id: u32, quest: &mut QuestGiver) {
 /// own `GlobalStrings.lua` and `show_messages` reads the row. **That also lands the sound the old
 /// path was dropping**: row 139 names the cue `igQuestFailed`, which the reference plays here and
 /// benilla had noted as an unbuilt follow-up.
-pub(super) fn quest_failed(
+fn quest_failed(
     quest_id: u32,
     timed: bool,
     quest_log: &mut QuestLog,
@@ -200,7 +342,7 @@ pub(super) fn quest_failed(
 /// bare `DisplayError(153)` and nothing else (no panel close): `ERR_QUEST_LOG_FULL` is a kind-2
 /// record, so it is the RED line, not a chat line (decision 0669 — it used to be a hardcoded
 /// English chat push here).
-pub(super) fn quest_log_full(quest: &mut QuestGiver) {
+fn quest_log_full(quest: &mut QuestGiver) {
     debug!("net: quest log full");
     quest.push_message(UiError::key("ERR_QUEST_LOG_FULL"));
 }
@@ -214,7 +356,7 @@ pub(super) fn quest_log_full(quest: &mut QuestGiver) {
 /// the current questgiver guid (`0xbe0810`) and signals Lua event `0x130` = `QUEST_FINISHED` —
 /// our [`QuestGiver::clear`] plus the feed's own `QUEST_FINISHED` on the cleared view. Without
 /// this the panel sat open on a refused accept (decision 0669).
-pub(super) fn quest_giver_invalid(reason: u32, quest: &mut QuestGiver) {
+fn quest_giver_invalid(reason: u32, quest: &mut QuestGiver) {
     debug!("net: questgiver refused to offer the quest (reason {reason})");
     quest.push_message(UiError::key(crate::ui_quest::questgiver_invalid_key(
         reason,
@@ -228,7 +370,7 @@ pub(super) fn quest_giver_invalid(reason: u32, quest: &mut QuestGiver) {
 /// is refusing IS this quest) and fall back to the template cache. A full-bag refusal shows a
 /// SECOND line, the ref's bare `DisplayError(0)` = `ERR_INV_FULL` on the red surface. Closes the
 /// window like [`quest_giver_invalid`].
-pub(super) fn quest_giver_failed(
+fn quest_giver_failed(
     quest_id: u32,
     reason: u32,
     quest: &mut QuestGiver,
@@ -254,36 +396,12 @@ pub(super) fn quest_giver_failed(
     quest.clear();
 }
 
-/// One party member's verdict on a quest we shared (`MSG_QUEST_PUSH_RESULT`, decision 1733).
-///
-/// Parked rather than shown: the line's `%s` is the member's NAME, which may still need a
-/// `CMSG_NAME_QUERY` round trip, and this pass has no VM to resolve GlobalStrings through either.
-/// [`crate::ui_quest_share`] owns both.
-pub(super) fn quest_push_result(member: u64, msg: QuestShareMsg, share: &mut QuestShare) {
-    debug!(
-        "net: quest push result — member {member:#x} verdict {}",
-        msg.0
-    );
-    share.push_verdict(member, msg);
-}
-
-/// A party member started a `QUEST_FLAGS_PARTY_ACCEPT` (escort) quest and we are being asked
-/// whether to start it too (`SMSG_QUEST_CONFIRM_ACCEPT`). Parked for the same reason: the popup
-/// names the member, and the name may not be cached yet.
-pub(super) fn quest_confirm_accept(c: QuestConfirmAccept, share: &mut QuestShare) {
-    debug!(
-        "net: quest confirm accept — quest {} ({:?}) from {:#x}",
-        c.quest_id, c.title, c.sender
-    );
-    share.set_confirm(c);
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    /// **The typemask-8 refusal** (decision 1872, wow-re `questgiver-marker.md` §W14.1). benilla
-    /// now sends `CMSG_QUESTGIVER_STATUS_QUERY` for quest-flagged GameObjects because the reference
+    /// **The typemask-8 refusal** (decision 1872). benilla now sends
+    /// `CMSG_QUESTGIVER_STATUS_QUERY` for quest-flagged GameObjects because the reference
     /// does — and vmangos, unlike the real 1.12 service, *answers*. The reference's handler drops
     /// that answer at the lookup (`0x5dca22 mov ecx,8`), so we must too: otherwise a wanted poster
     /// would wear a gold `!` the reference client never puts there.
@@ -491,17 +609,79 @@ mod tests {
         assert!(rx.try_iter().next().is_none(), "no verdict, no refusal");
     }
 
-    /// The DETAILS trailing flag is LATCHED on the packet, not read off the open view — the
-    /// reference's `0xbe0824`, whose one reader runs whichever panel is up.
+    /// The `0xbe0824` latch is written by all THREE panel packets — DETAILS' trailing `u32`,
+    /// OFFER_REWARD's `u32` after the reward text (both through `0x500ef0`, `0x50101a`) and
+    /// REQUEST_ITEMS' `closeOnCancel` (`0x501070`, `0x50111a`) — and zeroed by the world-enter
+    /// reset `0x500af0`. It is a latch, not a field of the open view: its one reader runs
+    /// whichever panel is up. benilla used to write it from DETAILS alone and never clear it, so
+    /// a single-quest auto-open's progress panel (`closeOnCancel` = 1) re-opened the NPC on
+    /// Cancel, which answers with the same panel again.
     #[test]
-    fn the_detail_flag_latches_from_the_packet() {
+    fn the_latch_is_written_by_every_panel_packet_and_cleared_on_world_enter() {
+        const NPC: u64 = 0xF130_0000_0000_0007;
         let (tx, _rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
         let mut quest = QuestGiver::default();
 
-        let mut d = detail(0xF130_0000_0000_0007, 100);
+        let mut d = detail(NPC, 100);
         d.auto_finish = 3;
         quest_detail(d, &mut quest, &commands);
-        assert_eq!(quest.detail_flag, 3);
+        assert_eq!(quest.close_on_cancel, 3, "DETAILS writes it");
+
+        quest_progress(progress(NPC, 100, 1), &mut quest);
+        assert_eq!(
+            quest.close_on_cancel, 1,
+            "REQUEST_ITEMS' closeOnCancel writes it"
+        );
+        quest_progress(progress(NPC, 100, 0), &mut quest);
+        assert_eq!(quest.close_on_cancel, 0, "…including a zero");
+
+        quest_offer(offer(NPC, 100, 1), &mut quest);
+        assert_eq!(quest.close_on_cancel, 1, "OFFER_REWARD writes it");
+
+        world_enter_reset(&mut quest);
+        assert_eq!(quest.close_on_cancel, 0, "the world-enter reset zeroes it");
+    }
+
+    /// Every panel publish clears the already-acted latch (`0x500bd0`, `0x500d91`).
+    #[test]
+    fn a_panel_packet_clears_the_acted_latch() {
+        let (tx, _rx) = crossbeam_channel::unbounded();
+        let commands = NetCommands(tx);
+        let mut quest = QuestGiver {
+            acted: true,
+            ..Default::default()
+        };
+        quest_detail(detail(0xF130_0000_0000_0007, 100), &mut quest, &commands);
+        assert!(!quest.acted);
+    }
+
+    fn progress(npc: u64, quest_id: u32, close_on_cancel: u32) -> QuestRequestItems {
+        QuestRequestItems {
+            npc,
+            quest_id,
+            title: "A Threat Within".into(),
+            request_text: String::new(),
+            emote: 0,
+            close_on_cancel,
+            required_money: 0,
+            required_items: Vec::new(),
+            is_complete: false,
+        }
+    }
+
+    fn offer(npc: u64, quest_id: u32, auto_finish: u32) -> QuestOfferReward {
+        QuestOfferReward {
+            npc,
+            quest_id,
+            title: "A Threat Within".into(),
+            offer_text: String::new(),
+            auto_finish,
+            choices: Vec::new(),
+            rewards: Vec::new(),
+            money: 0,
+            quest_flags: 0,
+            reward_spell: 0,
+        }
     }
 }
diff --git a/crates/benilla-app/src/ui_quest_log.rs b/crates/benilla-app/src/ui_quest_log.rs
index dee3e84d..142f2fc9 100644
--- a/crates/benilla-app/src/ui_quest_log.rs
+++ b/crates/benilla-app/src/ui_quest_log.rs
@@ -1,6 +1,6 @@
 //! The app-side **quest-log state + feed** — decision 0088's deferred second slice (the giver-panel
 //! decision named the log window, `SMSG_QUEST_QUERY_RESPONSE`, and the `PLAYER_QUEST_LOG` field
-//! accessors as a follow-up; the wire is now pinned in `quest-log-wire-pin.md`, and this is the app
+//! accessors as a follow-up; the wire is now pinned, and this is the app
 //! layer over it). The inward half of the seam around [`benilla_ui::script::quest_log`], the log's
 //! twin of [`crate::ui_quest`]'s questgiver-panel feed.
 //!
@@ -19,13 +19,12 @@
 //! per quest whose objectives moved ([`quests_with_progressed_objectives`]), the progress-toast
 //! `UI_INFO_MESSAGE`s (each moved leaderboard line's fresh text — the yellow top-center popup —
 //! and the COMPLETE flip's "%s (Complete)"), the native `QUEST_WATCH_UPDATE(watchIndex)` (the
-//! §5-verified byte arg), and `BENILLA_QUEST_PROGRESS(logIndex)` (the auto-watch's feed — the
+//! byte arg, `0x4df880`), and `BENILLA_QUEST_PROGRESS(logIndex)` (the auto-watch's feed — the
 //! divergence note at the fire site / decision 0340) — diffed against a `Local`, exactly like
 //! every other feed in this crate.
 //!
-//! [`drain_quest_log_abandons`] maps the confirmed abandon's 1-based Lua entry index back to its
-//! descriptor slot (this frame's push order, kept on [`QuestLog`]) and sends
-//! `CMSG_QUESTLOG_REMOVE_QUEST`.
+//! [`drain_quest_log_abandons`] maps the confirmed abandon's quest id to its descriptor slot (this
+//! frame's rows, kept on [`QuestLog`]) and sends `CMSG_QUESTLOG_REMOVE_QUEST`.
 //!
 //! This module used to also answer the questgiver greeting's active/available split, via a
 //! `contains` membership test over the live descriptor slots. **It doesn't any more, and must not
@@ -76,20 +75,20 @@ struct Row {
 ///
 /// - `templates` — the `SMSG_QUEST_QUERY_RESPONSE` cache, ask-once by quest id through
 ///   [`QueryCache`] (the exact twin of [`Items`]'s item-template cache).
-/// - `entry_slots` — this frame's pushed entry order → descriptor slot, so
-///   [`drain_quest_log_abandons`] can turn a confirmed abandon's 1-based Lua index back into the
-///   `CMSG_QUESTLOG_REMOVE_QUEST` slot it came from (slots aren't contiguous — an abandoned/turned-in
-///   quest leaves a gap).
+/// - `row_slots` — this frame's quest rows as `(quest id, descriptor slot)`, folded ones included:
+///   the reference's row table `0xbb71c0`, which [`drain_quest_log_abandons`] searches by the
+///   confirmed abandon's quest id for the `CMSG_QUESTLOG_REMOVE_QUEST` slot (slots aren't
+///   contiguous — an abandoned/turned-in quest leaves a gap).
 #[derive(Resource, Default)]
 pub(crate) struct QuestLog {
     templates: QueryCache<u32, QuestTemplate>,
-    entry_slots: Vec<Option<u8>>,
+    row_slots: Vec<(u32, u8)>,
     /// Collapsed section headers, keyed by header TITLE (two zones sharing a name share a header
     /// row, so the fold state naturally shares too). Owned here — the engine only reports the
     /// flag and drains toggle intents ([`drain_quest_log_collapses`]).
     collapsed: HashSet<String>,
     /// This frame's pushed entry order → the header title for header rows (`None` for quests) —
-    /// the collapse drain's index→identity map, the fold twin of `entry_slots`.
+    /// the collapse drain's index→identity map.
     header_keys: Vec<Option<String>>,
 }
 
@@ -123,16 +122,55 @@ impl QuestLog {
     /// to re-ask that there's no reason to risk it.
     pub(crate) fn clear_session(&mut self) {
         self.templates.clear();
-        self.entry_slots.clear();
+        self.row_slots.clear();
         self.collapsed.clear();
         self.header_keys.clear();
     }
 }
 
+/// The quest log's packet handler (decision 0088's second slice; in the net handler table since
+/// 2320, moved out of the drain's quests arm file).
+mod net {
+    use benilla_protocol::messages::QuestTemplate;
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::QuestLog;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handler and the session-end listener — called from
+    /// [`super::UiQuestLogPlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::QuestTemplate, on_template)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    fn on_template(In(ev): In<SessionEvent>, mut quest_log: ResMut<QuestLog>) {
+        if let SessionEvent::QuestTemplate(t) = ev {
+            quest_template(t, &mut quest_log);
+        }
+    }
+
+    /// The log's session state dies with the socket. A listener on the session end
+    /// (a second handler on the kind, after the bridge's own teardown).
+    fn on_session_end(In(_): In<SessionEvent>, mut quest_log: ResMut<QuestLog>) {
+        quest_log.clear_session();
+    }
+
+    /// The full quest template (`SMSG_QUEST_QUERY_RESPONSE`, answering our `CMSG_QUEST_QUERY`) — the
+    /// quest log's ask-once detail source, cached by `quest_id`.
+    fn quest_template(t: Box<QuestTemplate>, quest_log: &mut QuestLog) {
+        debug!("net: quest template {} ({})", t.quest_id, t.title);
+        quest_log.insert_template(*t);
+    }
+}
+
 pub(crate) struct UiQuestLogPlugin;
 
 impl Plugin for UiQuestLogPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         crate::query_cache::register::<QuestLog>(app);
         app.init_resource::<QuestLog>()
             .add_systems(
@@ -156,7 +194,7 @@ impl Plugin for UiQuestLogPlugin {
 }
 
 /// The name a still-in-flight cache miss wears. The reference's miss reads `" "` (a single space,
-/// `0x82ee00`, wow-re `ui/scratch/quest-leaderboard-law.md` §5); ours reads this, a longer-standing
+/// `0x82ee00`); ours reads this, a longer-standing
 /// divergence that says "still in flight" rather than looking like a nameless objective.
 const NAME_PLACEHOLDER: &str = "...";
 
@@ -167,9 +205,9 @@ const NAME_PLACEHOLDER: &str = "...";
 /// sentence, and `QUEST_OBJECTS_FOUND`/`QUEST_ITEMS_NEEDED`/`ERR_QUEST_ADD_FOUND_SII`/
 /// `ERR_QUEST_ADD_ITEM_SII` are the same four). `GetQuestLogLeaderBoard 0x4e0000` resolves
 /// `QUEST_MONSTERS_KILLED` `0x84b61c` (creature, no override), `QUEST_OBJECTS_FOUND` `0x84b634`
-/// (the override leg AND both GameObject legs) and `QUEST_ITEMS_NEEDED` `0x84b5f8` (item) — §5's
-/// table, address by address. Only the toast handler `0x5e5ad0` names the `ERR_*` twins, and it
-/// names them because they are *message-catalog* rows; these three are not.
+/// (the override leg AND both GameObject legs) and `QUEST_ITEMS_NEEDED` `0x84b5f8` (item). Only
+/// the toast handler `0x5e5ad0` names the `ERR_*` twins, and it names them because they are
+/// *message-catalog* rows; these three are not.
 ///
 /// A key the install does not carry renders the line with **empty text rather than no line**: the
 /// reference's `FrameScript_GetText` hands back its pre-seeded empty string and the leaderboard
@@ -196,9 +234,9 @@ fn leaderboard_text(
 /// descriptor slot's 6-bit counter for this array index.
 ///
 /// The custom `text` field, when non-empty, REPLACES the auto-generated name in the line but keeps
-/// the "cur/req" suffix (wow-re §5: a creature objective carrying `ObjectiveText[i]` formats with
+/// the "cur/req" suffix (`0x4e03da`: a creature objective carrying `ObjectiveText[i]` formats with
 /// `QUEST_OBJECTS_FOUND`, not the "slain" key, and that text IS the name — while `type` still
-/// answers `"monster"`, read from a fresh sign test of the id).
+/// answers `"monster"`, read from a fresh sign test of the id, `0x4e04ca`).
 fn creature_line(
     obj: &QuestObjective,
     counter: u8,
@@ -211,7 +249,7 @@ fn creature_line(
     let req = obj.required_count;
     let is_go = obj.creature_or_go & GO_OBJECTIVE_BIT != 0;
     let cur = u32::from(counter).min(req);
-    // §5's fork, in its own order: a non-empty override IS the name and takes
+    // The reference's fork, in its own order: a non-empty override IS the name and takes
     // `QUEST_OBJECTS_FOUND` on either kind; a GameObject takes that key on both its legs (the
     // binding fetches it once, above its cache test, at `0x4e031e`); only a plain creature reaches
     // `QUEST_MONSTERS_KILLED`. No gameobject-name cache yet — a later CMSG_GAMEOBJECT_QUERY slice
@@ -242,9 +280,9 @@ fn creature_line(
 /// client counts bags itself.
 ///
 /// **The name comes from the item cache alone.** The per-objective override buffer
-/// (`template+0x14dc + i*0x100`) is read only by the creature and GameObject branches (§5), and
-/// on a quad that carries both kinds that buffer belongs to the *creature* objective — reading it
-/// here would label the item with the creature's text.
+/// (`template+0x14dc + i*0x100`) is read only by the creature and GameObject branches
+/// (`0x4e033f`, `0x4e03c9`), and on a quad that carries both kinds that buffer belongs to the
+/// *creature* objective — reading it here would label the item with the creature's text.
 fn item_line(
     obj: &QuestObjective,
     src_item_id: u32,
@@ -325,8 +363,8 @@ fn resolve_template_item(
 ///
 /// **The passes are independent walks of the whole array, not one walk of merged quads** — the
 /// reference enumerates `event`, then creature/GO over `ReqCreatureOrGOId[0..3]`, then item over
-/// `ReqItemId[0..3]`, then reputation (wow-re `ui/scratch/quest-leaderboard-law.md` §4, VERIFIED;
-/// decision 1156 §5 named the ORDER half of this and its worse half went unnoticed). Our merged
+/// `ReqItemId[0..3]`, then reputation (`0x4e0000`/`0x4e0110`; decision 1156 §5 named the ORDER
+/// half of this and its worse half went unnoticed). Our merged
 /// walk emitted at most ONE line per index, so an objective quad carrying BOTH kinds lost its item
 /// line outright: quest 358 "Graverobbers" (creature 1941 ×8 and item 2834 ×8, both at index 0)
 /// showed 2 lines where the reference shows 3, and `GetNumQuestLeaderBoards` under-counted with it.
@@ -337,6 +375,7 @@ fn build_objectives(
     template: &QuestTemplate,
     log_slot: &QuestLogSlot,
     store: &ObjectFields,
+    objects: &crate::net::Objects,
     items: &Items,
     names: &NameCache,
     commands: &NetCommands,
@@ -369,7 +408,7 @@ fn build_objectives(
         let item_name = items
             .template(obj.item_id, 0, commands)
             .map(|t| t.name.clone());
-        let bag_count = count_of(store, items, obj.item_id, InventoryScope::QUEST_ITEMS);
+        let bag_count = count_of(store, objects, obj.item_id, InventoryScope::QUEST_ITEMS);
         if let Some(line) = item_line(
             obj,
             template.src_item_id,
@@ -421,15 +460,15 @@ fn build_detail(
     }
 }
 
-/// Map a 1-based Lua entry index to its descriptor slot via this frame's push order (`entry_slots`)
-/// — the abandon drain's half of the flow; `None` for a header row (no slot to remove). Pure, so
-/// it's testable without a live [`QuestLog`]/ECS.
-fn abandon_slot(entry: u32, entry_slots: &[Option<u8>]) -> Option<u8> {
-    (entry as usize)
-        .checked_sub(1)
-        .and_then(|i| entry_slots.get(i))
-        .copied()
-        .flatten()
+/// The descriptor slot of the row carrying `quest_id` — `AbandonQuest`'s search (`0x4df070`: walk
+/// the 40-row table `0xbb71c0`, skip headers, match the row's quest id, send its slot `+0x4`);
+/// `None` when no row carries it, which the reference answers by doing nothing. Pure, so it's
+/// testable without a live [`QuestLog`]/ECS.
+fn abandon_slot(quest_id: u32, row_slots: &[(u32, u8)]) -> Option<u8> {
+    row_slots
+        .iter()
+        .find(|&&(id, _)| id == quest_id)
+        .map(|&(_, slot)| slot)
 }
 
 /// Re-point the engine's quest-log selection (a 1-based entry INDEX) across a snapshot rebuild —
@@ -476,9 +515,8 @@ fn feed_server_clock(
 
 /// The header literal the reference paints for a header whose id is exactly `0` (`0x84b4ec`, its
 /// only reference image-wide). It is a **designer-data tell, not a transient**: the only value that
-/// can become a header id is a CACHED template's `zoneOrSort`, so it cannot appear while a template
-/// is in flight — which is what makes it safe to render at all (wow-re
-/// `ui/scratch/questlog-list-rebuild.md`, B5).
+/// can become a header id is a CACHED template's `zoneOrSort` (`0x4de6f6`), so it cannot appear
+/// while a template is in flight — which is what makes it safe to render at all.
 const MISSING_HEADER: &str = "Missing header! (quest designers)";
 
 /// One row's grouping/ordering inputs — everything [`order_groups`] needs, and nothing else, so
@@ -494,9 +532,9 @@ struct GroupRow {
     slot: u8,
 }
 
-/// **The quest log's display order** — §5-verified (wow-re `ui/scratch/questlog-list-rebuild.md`;
-/// rebuild `0x4de510`, group sort `0x4de751`/`0x4de8f0`, row comparator `0x4deac0`). Returns the
-/// header groups in order, each with its rows' indices in order.
+/// **The quest log's display order** (rebuild `0x4de510`, group sort `0x4de751`/`0x4de8f0`, row
+/// comparator `0x4deac0`). Returns the header groups in order, each with its rows' indices in
+/// order.
 ///
 /// - **Groups**: one per distinct `ZoneOrSort`, and `id == 0` is forced **FIRST**, before any name
 ///   lookup (`0x4de913`). An id that names no row collates as `""` and lands next. The rest go by
@@ -536,13 +574,14 @@ fn order_groups(rows: &[GroupRow]) -> Vec<(i32, String, Vec<usize>)> {
 
 /// Read the self player's `PLAYER_QUEST_LOG` descriptor slots each frame, resolve entries/detail,
 /// and push a [`QuestLogState`] snapshot on change (diffed against a `Local`, the crate's standard
-/// feed shape). Also refreshes [`QuestLog::active_quest_ids`]/`entry_slots` for the greeting split
-/// and the abandon drain.
+/// feed shape). Also refreshes [`QuestLog`]'s `row_slots` for the abandon drain.
 fn feed_quest_log(
     script: Option<NonSendMut<UiScript>>,
     self_q: Query<(&ObjectStore, &Guid), With<SelfPlayer>>,
     mut quest_log: ResMut<QuestLog>,
     names: Res<NameCache>,
+    // The bag walk behind an item objective's carried count (2334).
+    objects: crate::net::Objects,
     items: Res<Items>,
     icons: Option<Res<ItemDisplays>>,
     commands: Res<NetCommands>,
@@ -620,12 +659,11 @@ fn feed_quest_log(
     //
     // So `GetNumQuestLogEntries()` answers `(visible rows, CACHED quest count)`, and `0, 0` is the
     // all-cold extreme rather than the general law. Skipping the whole log on any miss — what this
-    // did, on a note that read the cold case as the rule — blanked the entire window for a round
+    // did, reading the cold case as the rule — blanked the entire window for a round
     // trip every time a quest whose template we had never seen entered the log. That took the
     // engine selection with it (`remap_selection` reads an empty list as "your quest is gone"), so
     // the detail pane jumped to row 1 on every single pickup, and addons reading the log across
-    // the blank saw a log that briefly held nothing. Settled at the bytes by wow-re, whose
-    // `scratch/questlog-list-rebuild.md` §1.1 now carries the partial case (decision 2256).
+    // the blank saw a log that briefly held nothing (decision 2256).
     //
     // `template()` is called for EVERY row before any filtering, because the miss is what SENDS
     // the query (our `pending` set is the reference's once-per-id dedupe) — short-circuiting would
@@ -692,8 +730,12 @@ fn feed_quest_log(
     };
 
     let mut entries: Vec<QuestLogEntryView> = Vec::new();
-    let mut entry_slots: Vec<Option<u8>> = Vec::new();
     let mut header_keys: Vec<Option<String>> = Vec::new();
+    // The quests folded under a collapsed header: out of the visible list, still in the log. The
+    // engine's watch prune counts them, as the reference's does (`0x4de7a7`–`0x4de80f` scans the
+    // whole row array, hidden rows included); leaving
+    // them out made every collapse drop its quests' watches for good.
+    let mut hidden_quest_ids: Vec<u32> = Vec::new();
     for (_, name, row_idxs) in &groups {
         let collapsed = quest_log.collapsed.contains(name);
         entries.push(QuestLogEntryView {
@@ -709,12 +751,13 @@ fn feed_quest_log(
             objectives: Vec::new(),
             detail: None, // a header names a zone/sort; there is no quest to describe
         });
-        entry_slots.push(None);
         header_keys.push(Some(name.clone()));
         for &ri in row_idxs {
             let r = &rows[ri];
             if collapsed {
-                continue; // folded: the quest stays in the log, just not in the visible list
+                // Folded: the quest stays in the log, just not in the visible list.
+                hidden_quest_ids.push(r.quest_id);
+                continue;
             }
             let (title, level, tag, pushable, objectives, detail) =
                 match quest_log.template(r.quest_id, &commands) {
@@ -736,7 +779,16 @@ fn feed_quest_log(
                         // button we wrongly enabled would push, and the party would get a detail panel
                         // for a quest the server then refuses (decision 1733).
                         t.flags & quest_flags::SHARABLE != 0,
-                        build_objectives(t, &r.log_slot, &store.0, &items, &names, &commands, &get),
+                        build_objectives(
+                            t,
+                            &r.log_slot,
+                            &store.0,
+                            &objects,
+                            &items,
+                            &names,
+                            &commands,
+                            &get,
+                        ),
                         // Every row, not just the selection (decision 2247) — the detail bindings
                         // resolve the live selection against these at call time, the way the
                         // reference peeks its quest cache inside the call.
@@ -751,7 +803,7 @@ fn feed_quest_log(
                     ),
                     // Unreachable: the in-flight gate above emptied `rows` unless EVERY template is
                     // cached, which is the reference's own all-or-nothing rebuild. This arm used to
-                    // paint a `"..."` placeholder row — the behaviour the §5 refuted.
+                    // paint a `"..."` placeholder row, which the reference never does (`0x4de67e`).
                     None => unreachable!("the in-flight gate leaves only cached rows"),
                 };
             let complete = if r.log_slot.state & quest_slot_state::COMPLETE != 0 {
@@ -778,7 +830,6 @@ fn feed_quest_log(
                 objectives,
                 detail,
             });
-            entry_slots.push(Some(r.slot));
             header_keys.push(None);
         }
     }
@@ -789,18 +840,19 @@ fn feed_quest_log(
     if new_sel != sel {
         script.set_quest_log_selection(new_sel);
     }
-    quest_log.entry_slots = entry_slots;
+    // Every cached row, folded or not — the table `AbandonQuest` searches by quest id.
+    quest_log.row_slots = rows.iter().map(|r| (r.quest_id, r.slot)).collect();
     quest_log.header_keys = header_keys;
 
     let fresh = QuestLogState {
         entries,
         num_quests: rows.len() as u32,
+        hidden_quest_ids,
     };
     if fresh == *last {
         return;
     }
-    // The objective-progress announces (the quest-update handler law — wow-re
-    // `object-layer/scratch/quest-update-ui-feedback-law.md`, §5 trio 2026-07-12, handler
+    // The objective-progress announces (the quest-update handler
     // `0x5e5ad0`), all fired AFTER the log push so a handler reading the log sees the fresh
     // state. Per progressed quest ([`quests_with_progressed_objectives`] — present in BOTH
     // states; a fresh accept or a turn-in is not "achieved a quest objective"):
@@ -834,10 +886,10 @@ fn feed_quest_log(
                 script.fire_event("UI_INFO_MESSAGE", vec![ScriptValue::Str(line)]);
             }
             if quest.completed {
-                // The verified 0x198 pair — msgId `0xf8` `ERR_QUEST_OBJECTIVE_COMPLETE_S` when
+                // The 0x198 pair — msgId `0xf8` `ERR_QUEST_OBJECTIVE_COMPLETE_S` when
                 // the handler has the objective text, `0xf9` `ERR_QUEST_UNKNOWN_COMPLETE` when it
-                // does not (wow-re `object-layer/scratch/quest-update-ui-feedback-law.md` §5's
-                // table; never `ERR_QUEST_COMPLETE_S`, which is the turn-in's own call site).
+                // does not (`0x5e5d12`; never `ERR_QUEST_COMPLETE_S`, which is the turn-in's own
+                // call site).
                 // Both are catalog rows, so the surface and the sound come from there rather than
                 // from a hand-picked `fire_event` here (decisions 1770/1815).
                 let line = if quest.title.is_empty() {
@@ -868,7 +920,7 @@ fn feed_quest_log(
 /// Did one objective **advance** between two log states — the announce predicate, and the whole of
 /// decision 1152's fix for B237.
 ///
-/// The verified law (wow-re `object-layer/scratch/quest-update-ui-feedback-law.md`, handler
+/// The reference's law (handler
 /// `0x5e5ad0`) is that the progress toast fires from the server's *additive* announcements alone —
 /// `SMSG_QUESTUPDATE_ADD_KILL` (`ERR_QUEST_ADD_KILL_SII`) and `_ADD_ITEM`
 /// (`ERR_QUEST_ADD_ITEM_SII`, via `0x5dd060`). There is no removal opcode and no client-side
@@ -945,9 +997,9 @@ fn quests_with_progressed_objectives(
         .collect()
 }
 
-/// Drain the confirmed abandons (1-based Lua entry index, pinned at click time — see
+/// Drain the confirmed abandons (the quest id marked at click time — see
 /// `benilla_ui::script::quest_log`'s module doc) and map each to `CMSG_QUESTLOG_REMOVE_QUEST` via
-/// this frame's `entry_slots`.
+/// this frame's `row_slots`.
 /// The `ZoneOrSort → header name` lookup ([`benilla_formats::QuestHeaderNames`]), loaded once at
 /// startup. Absent when the client data didn't load — the feed then buckets everything under
 /// "Quests".
@@ -1043,13 +1095,13 @@ fn drain_quest_log_abandons(
     let Some(mut script) = script else {
         return;
     };
-    for entry in script.take_quest_log_abandons() {
-        match abandon_slot(entry, &quest_log.entry_slots) {
+    for quest in script.take_quest_log_abandons() {
+        match abandon_slot(quest, &quest_log.row_slots) {
             Some(slot) => {
-                debug!("ui_quest_log: abandon entry {entry} → slot {slot}");
+                debug!("ui_quest_log: abandon quest {quest} → slot {slot}");
                 let _ = commands.0.send(ClientCommand::QuestlogRemove { slot });
             }
-            None => debug!("ui_quest_log: abandon entry {entry} out of range — ignored"),
+            None => debug!("ui_quest_log: abandon quest {quest} is not in the log — ignored"),
         }
     }
 }
@@ -1058,7 +1110,7 @@ fn drain_quest_log_abandons(
 mod tests {
     use super::*;
 
-    // ── order_groups — the §5-verified display order ────────────────────────────────────────────
+    // ── order_groups — the reference's display order ────────────────────────────────────────────
 
     fn grow(zos: i32, header: &str, level: u32, title: &str, slot: u8) -> GroupRow {
         GroupRow {
@@ -1300,7 +1352,7 @@ mod tests {
         assert_eq!(line.text, "<NEEDED ... 2 of 5>");
     }
 
-    /// **The key fork §5 pins**, and the one an English assertion could never see: a creature
+    /// **The key fork**, and the one an English assertion could never see: a creature
     /// objective carrying `ObjectiveText[i]` stops being "slain" — the override IS the name and
     /// the format becomes `QUEST_OBJECTS_FOUND` (`mov ecx,0x84b634` @`0x4e03e1`) — while `type`
     /// still answers `"monster"`, because that is read from a fresh sign test of
@@ -1347,8 +1399,8 @@ mod tests {
     /// Decision 1158, correcting 0109: a line's `finished` is `cur >= req` and **nothing else**.
     /// The reference reads the whole-quest COMPLETE bit exactly once in `GetQuestLogLeaderBoard`
     /// (`0x4e02a2`), in the `event` branch, where it is that line's only predicate — it is never
-    /// or-ed into a counted line's verdict (wow-re `ui/scratch/quest-leaderboard-law.md` §7). Only
-    /// the whole-quest turn-in predicate `0x4df580` reads the bit and the counts together.
+    /// or-ed into a counted line's verdict. Only the whole-quest turn-in predicate `0x4df580` reads
+    /// the bit and the counts together.
     #[test]
     fn a_complete_quest_does_not_mark_a_short_objective_finished() {
         let o = obj(100, 10, 0, 0, "");
@@ -1415,6 +1467,9 @@ mod tests {
         };
         let store = ObjectFields::default(); // empty bags — the item objective reads 0/5
         let items = Items::default();
+        // Empty bags — every item objective here reads 0 owned (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let names = NameCache::default();
         let (tx, _rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
@@ -1423,6 +1478,7 @@ mod tests {
             &template,
             &log_slot,
             &store,
+            &objects,
             &items,
             &names,
             &commands,
@@ -1440,11 +1496,10 @@ mod tests {
         assert_eq!(objectives[1].kind, "item");
     }
 
-    /// **The bug this split exists for** (director, 2026-09-15; wow-re
-    /// `ui/scratch/quest-leaderboard-law.md` §4): the reference walks `ReqCreatureOrGOId[0..3]` and
-    /// `ReqItemId[0..3]` as two INDEPENDENT passes, so one objective quad carrying both kinds
-    /// produces two lines. Merging them per quad returned on the creature branch and dropped the
-    /// item outright.
+    /// **The bug this split exists for** (director, 2026-09-15): the reference walks
+    /// `ReqCreatureOrGOId[0..3]` (`0x4e02d7`) and `ReqItemId[0..3]` (`0x4e04f4`) as two
+    /// INDEPENDENT passes, so one objective quad carrying both kinds produces two lines. Merging
+    /// them per quad returned on the creature branch and dropped the item outright.
     ///
     /// The fixture is quest 358 "Graverobbers"' own shape — `ReqCreatureOrGOId1` 1941 ×8 and
     /// `ReqItemId1` 2834 ×8 both at index 0, plus a second creature at index 1 — which showed 2
@@ -1465,6 +1520,9 @@ mod tests {
         };
         let store = ObjectFields::default();
         let items = Items::default();
+        // Empty bags — every item objective here reads 0 owned (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let names = NameCache::default();
         let (tx, _rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
@@ -1473,6 +1531,7 @@ mod tests {
             &template,
             &log_slot,
             &store,
+            &objects,
             &items,
             &names,
             &commands,
@@ -1488,9 +1547,9 @@ mod tests {
         assert_eq!(objectives[2].kind, "item");
     }
 
-    /// The override buffer belongs to the CREATURE branch (§5) — on a shared quad it must not leak
-    /// into the item line, which takes its name from the item cache alone. The split made this
-    /// reachable for the first time, so it is asserted rather than assumed.
+    /// The override buffer belongs to the CREATURE branch (`0x4e03da`) — on a shared quad it must
+    /// not leak into the item line, which takes its name from the item cache alone. The split made
+    /// this reachable for the first time, so it is asserted rather than assumed.
     #[test]
     fn a_shared_quads_objective_text_names_the_creature_not_the_item() {
         let template = quest_template([
@@ -1507,6 +1566,9 @@ mod tests {
         };
         let store = ObjectFields::default();
         let items = Items::default();
+        // Empty bags — every item objective here reads 0 owned (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let names = NameCache::default();
         let (tx, _rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
@@ -1515,13 +1577,15 @@ mod tests {
             &template,
             &log_slot,
             &store,
+            &objects,
             &items,
             &names,
             &commands,
             &probe_strings,
         );
         assert_eq!(objectives.len(), 2);
-        // The override IS the creature's name, and flips its key to QUEST_OBJECTS_FOUND (§5).
+        // The override IS the creature's name, and flips its key to QUEST_OBJECTS_FOUND
+        // (`0x4e03e1`).
         assert_eq!(objectives[0].text, "<FOUND Graverobbers routed 8 of 8>");
         // The item line wears the in-flight placeholder, never the creature's text.
         assert_eq!(objectives[1].text, "<NEEDED ... 0 of 8>");
@@ -1546,6 +1610,9 @@ mod tests {
         };
         let store = ObjectFields::default();
         let items = Items::default();
+        // Empty bags — every item objective here reads 0 owned (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let names = NameCache::default();
         let (tx, _rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
@@ -1554,6 +1621,7 @@ mod tests {
             &template,
             &log_slot,
             &store,
+            &objects,
             &items,
             &names,
             &commands,
@@ -1564,7 +1632,7 @@ mod tests {
 
     /// The 0109-era behaviour this inverts: a COMPLETE slot state used to mark every line
     /// finished. Decision 1158 — the reference's per-line verdict never reads that bit
-    /// (`0x4e0110` §7); only the whole-quest turn-in predicate (`0x4df580`) combines the two.
+    /// (`0x4e0110`); only the whole-quest turn-in predicate (`0x4df580`) combines the two.
     #[test]
     fn a_complete_slot_state_does_not_finish_a_short_line() {
         let template = quest_template([
@@ -1581,6 +1649,9 @@ mod tests {
         };
         let store = ObjectFields::default();
         let items = Items::default();
+        // Empty bags — every item objective here reads 0 owned (2334).
+        let mut objs = crate::ui_items::TestObjects::new();
+        let objects = objs.get();
         let names = NameCache::default();
         let (tx, _rx) = crossbeam_channel::unbounded();
         let commands = NetCommands(tx);
@@ -1589,6 +1660,7 @@ mod tests {
             &template,
             &log_slot,
             &store,
+            &objects,
             &items,
             &names,
             &commands,
@@ -1611,18 +1683,103 @@ mod tests {
         assert_eq!(money_split(0), (0, 0));
     }
 
-    // ── abandon_slot: entry → descriptor slot across gaps ──────────────────────────────────────────
+    // ── abandon_slot: quest id → descriptor slot across gaps ───────────────────────────────────────
 
     #[test]
-    fn abandon_maps_entry_to_slot_across_a_gap_and_skips_headers() {
-        // A header row (None), then slots 0 and 2 (slot 1 empty in the descriptor array) — the
-        // push order skips the gap; entry 1 is the header, which maps to NO slot.
-        let entry_slots = vec![None, Some(0u8), Some(2u8)];
-        assert_eq!(abandon_slot(1, &entry_slots), None); // header row: nothing to remove
-        assert_eq!(abandon_slot(2, &entry_slots), Some(0));
-        assert_eq!(abandon_slot(3, &entry_slots), Some(2));
-        assert_eq!(abandon_slot(4, &entry_slots), None);
-        assert_eq!(abandon_slot(0, &entry_slots), None); // 1-based; 0 is never a valid entry
+    fn abandon_maps_quest_id_to_slot_across_a_gap() {
+        // Slots 0 and 2 (slot 1 empty in the descriptor array) — the id finds its own slot.
+        let row_slots = vec![(783u32, 0u8), (7, 2)];
+        assert_eq!(abandon_slot(783, &row_slots), Some(0));
+        assert_eq!(abandon_slot(7, &row_slots), Some(2));
+        assert_eq!(abandon_slot(8, &row_slots), None); // not in the log: nothing to remove
+        assert_eq!(abandon_slot(0, &row_slots), None); // 0 is never a quest
+    }
+
+    // ── The abandon mark is a QUEST ID (0x4dfb50 / 0x4df070) ─────────────────────────────────────
+
+    /// **An abandon names a quest, not a row.** `SetAbandonQuest` (`0x4dfb50`) copies the
+    /// selection `0xbb7480` — which holds the selected row's QUEST ID (`0x4def30`, `0x4def5d`) —
+    /// into the mark `0xbb7484`; `AbandonQuest` (`0x4dfe00` → `0x4df070`) searches the row table
+    /// `0xbb71c0` for that id and removes that row's slot. So a log that re-indexes while the
+    /// confirm popup is up — a fold, a quest arriving or leaving — cannot move the abandon onto a
+    /// neighbour. Ours pinned the 1-based row index and resolved it against the rows current at
+    /// confirm time: fold the group above and the popup's Yes abandoned the quest below.
+    #[test]
+    fn a_fold_between_mark_and_confirm_does_not_retarget_the_abandon() {
+        use benilla_protocol::messages::field::FIELD_PLAYER_QUEST_LOG_1_1;
+
+        // Z1 = zone 0 ("Missing header!", forced first) holding A; Z2 = zone 7 holding B and C.
+        // Entries: [Z1, A, Z2, B, C] — B is row 4.
+        const A: u32 = 101;
+        const B: u32 = 201;
+        const C: u32 = 202;
+        let quests = [(0u8, A, 0i32, "A"), (1, B, 7, "B"), (2, C, 7, "C")];
+
+        let (tx, rx) = crossbeam_channel::unbounded();
+        let mut app = App::new();
+        app.insert_resource(NetCommands(tx));
+        app.init_resource::<crate::net::GuidIndex>()
+            .init_resource::<NameCache>()
+            .init_resource::<Items>()
+            .init_resource::<crate::world_state::WorldStates>()
+            .init_resource::<crate::ui_chat::ChatLog>()
+            .init_resource::<crate::sound::MessageSounds>();
+        let mut log = QuestLog::default();
+        let mut pairs = Vec::new();
+        for (slot, id, zos, title) in quests {
+            let mut t = quest_template(std::array::from_fn(|_| obj(0, 0, 0, 0, "")));
+            t.quest_id = id;
+            t.zone_or_sort = zos;
+            t.title = title.into();
+            log.insert_template(t);
+            pairs.push((FIELD_PLAYER_QUEST_LOG_1_1 + 3 * u16::from(slot), id));
+        }
+        app.insert_resource(log);
+        app.world_mut().spawn((
+            ObjectStore(ObjectFields::from_pairs(&pairs)),
+            Guid(0x2A),
+            SelfPlayer,
+        ));
+        app.insert_non_send_resource(UiScript::new().unwrap());
+        app.add_systems(
+            Update,
+            (
+                drain_quest_log_collapses,
+                feed_quest_log,
+                drain_quest_log_abandons,
+            )
+                .chain(),
+        );
+        let run = |app: &mut App, lua: &str| {
+            app.world_mut()
+                .non_send_resource_mut::<UiScript>()
+                .run(lua)
+                .unwrap();
+        };
+
+        app.update();
+        run(&mut app, "SelectQuestLogEntry(4); SetAbandonQuest()");
+        assert_eq!(
+            app.world()
+                .non_send_resource::<UiScript>()
+                .eval::<String>("return GetAbandonQuestName()")
+                .unwrap(),
+            "B"
+        );
+        // The popup is up; the player folds Z1 — B moves from row 4 to row 3, C takes row 4.
+        run(&mut app, "CollapseQuestHeader(1)");
+        app.update();
+        run(&mut app, "AbandonQuest()");
+        app.update();
+
+        let sent: Vec<_> = rx
+            .try_iter()
+            .filter(|c| matches!(c, ClientCommand::QuestlogRemove { .. }))
+            .collect();
+        assert!(
+            matches!(sent.as_slice(), [ClientCommand::QuestlogRemove { slot: 1 }]),
+            "the abandon removes B's slot (1), never C's (2): {sent:?}"
+        );
     }
 
     // ── quests_with_progressed_objectives: the QUEST_WATCH_UPDATE per-quest trigger ─────────────────
@@ -1654,6 +1811,7 @@ mod tests {
         QuestLogState {
             num_quests: entries.iter().filter(|e| !e.is_header).count() as u32,
             entries,
+            hidden_quest_ids: Vec::new(),
         }
     }
 
diff --git a/crates/benilla-app/src/ui_quest_share.rs b/crates/benilla-app/src/ui_quest_share.rs
index ee9fc878..d373b4d8 100644
--- a/crates/benilla-app/src/ui_quest_share.rs
+++ b/crates/benilla-app/src/ui_quest_share.rs
@@ -33,7 +33,7 @@
 //! address a party member by guid and display a *name*, so both go through the [`NameCache`]'s
 //! ask-once resolve. The reference does not: it reads the object-name cache `0xc0e228` through
 //! `0x55f080` with a **null callback**, so a miss returns 0 and the message is **silently dropped**
-//! — no query, no defer, no line (decision 1738's §5). That is a quirk of a synchronous object
+//! — no query, no defer, no line (decision 1738). That is a quirk of a synchronous object
 //! manager that always has its party members to hand, not a behaviour worth reproducing: benilla's
 //! cache may genuinely not hold a member yet, and losing "Thrall has declined your quest" because a
 //! name query was in flight is strictly worse than showing it a frame later. So a verdict whose
@@ -109,12 +109,12 @@ impl QuestShare {
 /// from. `None` for an unmapped byte is the reference's data-suppression face, not a gap: an
 /// unknown verdict shows nothing rather than an English guess.
 ///
-/// **Both columns are now VERIFIED at the bytes** (decision 1738's fold-back of the §5 dispatched
-/// with 1733). The inbound `0x276` arm at `0x5e4781` maps `msg 0..8` onto message ids `0x181`-`0x189`
-/// — contiguous, in exactly this order — and all nine records carry **`kind 0`** (the nine
-/// `push 0x0` at `0x487dc9`-`0x487e69`), which `CGGameUI::DisplayError` dispatches to the chat
-/// window as `CHAT_MSG_SYSTEM`. Not one of them reaches `UIErrorsFrame`, which is what 1733
-/// guessed and is why the guess is recorded as having been a guess.
+/// **Both columns are now VERIFIED at the bytes** (decision 1738's fold-back). The inbound `0x276`
+/// arm at `0x5e4781` maps `msg 0..8` onto message ids `0x181`-`0x189` — contiguous, in exactly this
+/// order — and all nine records carry **`kind 0`** (the nine `push 0x0` at `0x487dc9`-`0x487e69`),
+/// which `CGGameUI::DisplayError` dispatches to the chat window as `CHAT_MSG_SYSTEM`. Not one of
+/// them reaches `UIErrorsFrame`, which is what 1733 guessed and is why the guess is recorded as
+/// having been a guess.
 fn verdict_message(msg: QuestShareMsg) -> Option<&'static str> {
     let key = match msg {
         QuestShareMsg::SHARING_QUEST => "ERR_QUEST_PUSH_SUCCESS_S",
@@ -131,6 +131,71 @@ fn verdict_message(msg: QuestShareMsg) -> Option<&'static str> {
     Some(key)
 }
 
+/// The party quest-share's packet handlers (decision 1733; in the net handler table since 2320,
+/// moved out of the drain's quests arm file): one member's verdict on a quest we pushed, and the
+/// escort-quest confirm. Both park in [`QuestShare`] for this module to name and raise — the guid
+/// needs a name query a packet handler cannot await.
+mod net {
+    use benilla_protocol::messages::{QuestConfirmAccept, QuestShareMsg};
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::QuestShare;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handlers and the session-end listener — called from
+    /// [`super::QuestSharePlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::QuestPushResult, on_push_result)
+            .net_handler(K::QuestConfirmAccept, on_confirm_accept)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    fn on_push_result(In(ev): In<SessionEvent>, mut share: ResMut<QuestShare>) {
+        if let SessionEvent::QuestPushResult { member, msg } = ev {
+            quest_push_result(member, msg, &mut share);
+        }
+    }
+
+    fn on_confirm_accept(In(ev): In<SessionEvent>, mut share: ResMut<QuestShare>) {
+        if let SessionEvent::QuestConfirmAccept(c) = ev {
+            quest_confirm_accept(c, &mut share);
+        }
+    }
+
+    /// A verdict on a share nobody is listening for any more, and a confirm whose server-side
+    /// latch died with the socket (decision 1733). A listener on the session end
+    /// (a second handler on the kind, after the bridge's own teardown).
+    fn on_session_end(In(_): In<SessionEvent>, mut share: ResMut<QuestShare>) {
+        share.clear_session();
+    }
+
+    /// One party member's verdict on a quest we shared (`MSG_QUEST_PUSH_RESULT`, decision 1733).
+    ///
+    /// Parked rather than shown: the line's `%s` is the member's NAME, which may still need a
+    /// `CMSG_NAME_QUERY` round trip, and this pass has no VM to resolve GlobalStrings through either.
+    /// [`crate::ui_quest_share`] owns both.
+    fn quest_push_result(member: u64, msg: QuestShareMsg, share: &mut QuestShare) {
+        debug!(
+            "net: quest push result — member {member:#x} verdict {}",
+            msg.0
+        );
+        share.push_verdict(member, msg);
+    }
+
+    /// A party member started a `QUEST_FLAGS_PARTY_ACCEPT` (escort) quest and we are being asked
+    /// whether to start it too (`SMSG_QUEST_CONFIRM_ACCEPT`). Parked for the same reason: the popup
+    /// names the member, and the name may not be cached yet.
+    fn quest_confirm_accept(c: QuestConfirmAccept, share: &mut QuestShare) {
+        debug!(
+            "net: quest confirm accept — quest {} ({:?}) from {:#x}",
+            c.quest_id, c.title, c.sender
+        );
+        share.set_confirm(c);
+    }
+}
+
 /// Owns [`QuestShare`] and its two systems — a plugin of its own rather than a lodger in
 /// [`crate::ui_quest`]'s, because nothing here is bound to the questgiver window: the verdicts are
 /// fired from the quest LOG and the confirm has no window at all.
@@ -138,6 +203,7 @@ pub(crate) struct QuestSharePlugin;
 
 impl Plugin for QuestSharePlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         // The [`crate::ui_duel`] shape exactly: feed before the input pass so a verdict line and
         // a confirm are on screen the same frame the packet landed, drain after it so the popup's
         // Yes goes out the same frame it was clicked.
diff --git a/crates/benilla-app/src/ui_reputation.rs b/crates/benilla-app/src/ui_reputation.rs
index 18b8d436..34facafb 100644
--- a/crates/benilla-app/src/ui_reputation.rs
+++ b/crates/benilla-app/src/ui_reputation.rs
@@ -11,7 +11,7 @@
 //!    player** — the client's own membership gate at `0x4d5555`, where the add call sits inside the
 //!    accept block of the same loop that picks the base value. Whether the pane then *lists* it is
 //!    the single flag `VISIBLE`, off until the player first meets them — which is why
-//!    `SMSG_SET_FACTION_VISIBLE` has to be applied (`net::apply::session::reputation_visible`).
+//!    `SMSG_SET_FACTION_VISIBLE` has to be applied (`net::session::reputation_visible`).
 //!
 //!    **Unlisted factions are pushed anyway, carrying `visible: false`.** They are how the pane's
 //!    headers learn their names: all five header factions carry `HEADER` (`0x08`) and only one of
@@ -449,8 +449,8 @@ mod live_wire_tests {
     ///
     /// Kept as real bytes rather than a hand-built fixture because this is the one input the whole
     /// pane is a function of, and a plausible-looking invention would agree with whatever the code
-    /// did. It also settles, at the wire, the single claim the wow-re carve could only mark
-    /// INFERRED: that the live server marks exactly the five header factions with `0x08`.
+    /// did. It also settles, at the wire, the single claim the binary alone could only leave
+    /// inferred: that the live server marks exactly the five header factions with `0x08`.
     const LIVE_FLAGS: &[(usize, u8)] = &[
         (0, 0x02),
         (2, 0x02),
@@ -525,7 +525,7 @@ mod live_wire_tests {
         let cat = benilla_formats::load_faction_catalog(&mut chain).expect("factions");
         let store = live_store();
 
-        // The five header factions, asserted at the wire — the wow-re carve's one INFERRED claim.
+        // The five header factions, asserted at the wire — the one claim the binary left inferred.
         use benilla_formats::faction_flags as flag;
         let headers: Vec<usize> = LIVE_FLAGS
             .iter()
diff --git a/crates/benilla-app/src/ui_saved.rs b/crates/benilla-app/src/ui_saved.rs
index 76e67133..09da1039 100644
--- a/crates/benilla-app/src/ui_saved.rs
+++ b/crates/benilla-app/src/ui_saved.rs
@@ -4,11 +4,10 @@
 //!
 //! **Load** — one chunk, executed straight into the VM immediately after the in-game UI's XML has
 //! loaded and before anything runs against it, then `VARIABLES_LOADED`. That ordering is the whole
-//! mechanism, byte-verified in wow-re (`system/ui/scratch/savedvariables-protocol.md`): the
-//! reference's `AddOn_Load 0x51f240` runs the addon's own files (step 2 — where the file-scope
-//! `TRAINER_FILTER_* = 1` defaults are assigned), *then* executes the saved file over the top
-//! (step 4), *then* fires the load event (step 6). Defaults first, saved values second, consumers
-//! third — reverse any two and the saved value can never win.
+//! mechanism: the reference's `AddOn_Load 0x51f240` runs the addon's own files (step 2 — where
+//! the file-scope `TRAINER_FILTER_* = 1` defaults are assigned), *then* executes the saved file
+//! over the top (step 4), *then* fires the load event (step 6). Defaults first, saved values
+//! second, consumers third — reverse any two and the saved value can never win.
 //!
 //! **Write** — `OnExit(InWorld)` (a `/logout` or a disconnect) and `AppExit`, the two edges our
 //! session has. The reference writes from exactly one place, the UI shutdown `0x490bd0`, reached
@@ -46,8 +45,9 @@ impl Plugin for UiSavedPlugin {
 ///
 /// Called from the in-game UI load ([`crate::ui_script`]) at the reference's own seam — after the
 /// XML, before anything consumes it. A missing file is the normal first-run case (defaults stand);
-/// a malformed one warns and is left on disk untouched, so a hand edit that fails to parse costs
-/// this session's settings and not the file.
+/// a malformed or unreadable one warns and is **held** ([`UiScript::hold_saved_file`]), so a hand
+/// edit that fails to parse costs this session's settings and not the file. Read as **bytes**
+/// (1193): the writer keeps a Lua byte string's bytes, so the file need not be UTF-8.
 ///
 /// **`host_settings` is the third store's turn** (decision 2132). A handful of the reference's
 /// `RegisterForSave` globals are settings benilla persists in `config.toml` instead — the
@@ -62,19 +62,24 @@ pub(crate) fn load_saved_variables(
 ) {
     // `None` = hermetic capture, or no install — session-only state, and the event below still fires.
     if let Some(path) = crate::local_state::saved_variables_path() {
-        match std::fs::read_to_string(&path) {
-            Ok(text) => {
-                if let Err(e) = script.run(&text) {
+        match std::fs::read(&path) {
+            Ok(bytes) => {
+                if let Err(e) = script.run_chunk(&bytes) {
                     warn!(
-                        "saved variables: {} did not load ({e}) — running on defaults",
+                        "saved variables: {} did not load ({e}) — running on defaults, and \
+                         leaving the file as it is",
                         path.display()
                     );
+                    script.hold_saved_file(&path);
                 } else {
                     info!("saved variables: loaded {}", path.display());
                 }
             }
             Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
-            Err(e) => warn!("saved variables: cannot read {}: {e}", path.display()),
+            Err(e) => {
+                warn!("saved variables: cannot read {}: {e}", path.display());
+                script.hold_saved_file(&path);
+            }
         }
     }
     host_settings(script);
@@ -98,11 +103,19 @@ pub(crate) fn save(script: &mut UiScript) {
     let Some(path) = crate::local_state::saved_variables_path() else {
         return;
     };
-    let body = script.saved_variables_text();
+    if script.saved_file_held(&path) {
+        warn!(
+            "saved variables: {} did not load this session — left as it is",
+            path.display()
+        );
+        return;
+    }
+    let mut body = HEADER.as_bytes().to_vec();
+    body.extend(script.saved_variables_bytes());
     for w in script.take_warnings() {
         warn!("saved variables: {w}");
     }
-    match crate::local_state::write_atomic(&path, &format!("{HEADER}{body}")) {
+    match crate::local_state::write_atomic_bytes(&path, &body) {
         Ok(()) => info!(
             "saved variables: wrote {} ({} names)",
             path.display(),
@@ -173,6 +186,40 @@ mod tests {
         load_saved_variables(&mut broken, |_| {});
         assert_eq!(broken.eval::<i64>("return KEPT").unwrap(), 1);
         assert_eq!(std::fs::read_to_string(&path).unwrap(), "KEPT = = 3\n");
+        // …and the shutdown write leaves it alone too. This is the half that used to fail: the
+        // load kept its promise, and the save then wrote this session's default over the file.
+        save(&mut broken);
+        assert_eq!(
+            std::fs::read_to_string(&path).unwrap(),
+            "KEPT = = 3\n",
+            "a file that did not load is not replaced by the defaults the session ran on"
+        );
+        std::fs::remove_dir_all(&tmp).ok();
+    }
+
+    /// **The bytes survive the folder.** A value that is not UTF-8 is written raw and read back
+    /// raw — the load reads bytes, so the file it now writes is one it can always read (a
+    /// `read_to_string` here would call it unreadable and the next save would replace it).
+    #[test]
+    fn a_byte_string_survives_the_file() {
+        let _l = ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let tmp = std::env::temp_dir().join(format!("benilla-svbytes-{}", std::process::id()));
+        std::fs::remove_dir_all(&tmp).ok();
+        let _c = EnvGuard::unset("WOW_CAPTURE");
+        let _h = EnvGuard::set("BENILLA_HOME", tmp.to_str().unwrap());
+
+        let mut s = script("string.char(65, 233, 255)");
+        save(&mut s);
+        let mut fresh = script("'x'");
+        load_saved_variables(&mut fresh, |_| {});
+        assert!(fresh
+            .eval::<bool>(
+                "return string.len(KEPT) == 3 and string.byte(KEPT, 2) == 233 \
+                 and string.byte(KEPT, 3) == 255"
+            )
+            .unwrap());
         std::fs::remove_dir_all(&tmp).ok();
     }
 
diff --git a/crates/benilla-app/src/ui_script/action_bar_tests.rs b/crates/benilla-app/src/ui_script/action_bar_tests.rs
index 1c3ab265..f8086997 100644
--- a/crates/benilla-app/src/ui_script/action_bar_tests.rs
+++ b/crates/benilla-app/src/ui_script/action_bar_tests.rs
@@ -12,6 +12,7 @@ fn action_ids(s: &mut UiScript) -> Vec<u32> {
 /// slots drawing no icon, and a physical click queuing the right UseAction id.
 #[test]
 fn shipped_action_bar_drives_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     super::test_ui::load_ui(&s, "Interface\\FrameXML\\Cooldown.xml");
@@ -226,6 +227,7 @@ fn load_action_bar(s: &UiScript) {
 /// `ACTIONBAR_UPDATE_STATE` checks the ring, and `IsUsableAction`'s OOM pair blue-tints the icon.
 #[test]
 fn state_feedback_drives_cooldown_checked_and_usable_through_the_xml() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ActionState;
 
     let mut s = UiScript::new().unwrap();
@@ -355,6 +357,7 @@ fn state_feedback_drives_cooldown_checked_and_usable_through_the_xml() {
 /// start behind the new epoch.
 #[test]
 fn a_start_behind_the_clocks_epoch_hides_the_stock_sweep() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ActionState;
 
     let mut s = UiScript::new().unwrap();
@@ -424,6 +427,7 @@ fn a_start_behind_the_clocks_epoch_hides_the_stock_sweep() {
 /// under the icon), which is exactly why the order is pinned end-to-end through the real XML.
 #[test]
 fn the_cooldown_sweep_paints_over_the_buttons_icon_and_ring() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ActionState;
 
     let mut s = UiScript::new().unwrap();
@@ -496,6 +500,7 @@ fn the_cooldown_sweep_paints_over_the_buttons_icon_and_ring() {
 /// `ui_models`' own tests.)
 #[test]
 fn a_cooldown_count_addons_hook_leaves_the_sweep_running() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ActionState;
 
     let mut s = UiScript::new().unwrap();
@@ -612,6 +617,7 @@ const COOLDOWN_COUNT_HOOK: &str = r#"
 /// cooldown came out at `button + 3` — over the count text the hook hangs at `button + 2`.
 #[test]
 fn a_cooldown_count_draws_over_the_bonus_bars_sweep() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ActionState;
 
     let mut s = UiScript::new().unwrap();
@@ -688,6 +694,7 @@ fn a_cooldown_count_draws_over_the_bonus_bars_sweep() {
 /// registration set is consulted.
 #[test]
 fn a_right_click_on_an_action_button_uses_the_action() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -740,6 +747,7 @@ fn a_right_click_on_an_action_button_uses_the_action() {
 /// unit tests directly — the modifier-key mirror gating `PickupAction` vs `UseAction`, end to end.
 #[test]
 fn shift_click_picks_up_not_uses() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -799,6 +807,7 @@ fn shift_click_picks_up_not_uses() {
 /// way to rearrange it at all.
 #[test]
 fn the_action_bar_lock_stops_the_drag_and_leaves_shift_click_alone() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -873,6 +882,7 @@ fn the_action_bar_lock_stops_the_drag_and_leaves_shift_click_alone() {
 /// the one gesture (0218 §4: "a drag-swap is two sends, never atomic").
 #[test]
 fn drag_drop_onto_another_button_hops_the_displaced_action() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -945,6 +955,7 @@ fn drag_drop_onto_another_button_hops_the_displaced_action() {
 /// the only order the runtime can produce.
 #[test]
 fn count_fontstring_follows_is_consumable_action_not_the_bag_count() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -1046,6 +1057,7 @@ fn count_fontstring_follows_is_consumable_action_not_the_bag_count() {
 /// macro on the bar was nameless.
 #[test]
 fn macro_name_line_follows_get_action_text_through_the_xml() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::{MacroState, MacroView};
 
     let mut s = UiScript::new().unwrap();
@@ -1319,6 +1331,7 @@ fn shipped_bag_frame_drives_end_to_end() {
 /// a usable/cooldown event with empties on the bar — and asserts no empty well gains a solid.
 #[test]
 fn state_events_leave_empty_wells_untinted() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ActionState;
 
     let mut s = UiScript::new().unwrap();
@@ -1389,6 +1402,7 @@ fn state_events_leave_empty_wells_untinted() {
 /// never the colour).
 #[test]
 fn an_occupied_slot_going_empty_leaves_no_white_plate() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ActionState;
 
     let mut s = UiScript::new().unwrap();
@@ -1461,6 +1475,7 @@ fn an_occupied_slot_going_empty_leaves_no_white_plate() {
 /// the visible bar shows.
 #[test]
 fn the_bonus_action_bar_exists_hidden_and_takes_layout_calls() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -1523,6 +1538,7 @@ fn the_bonus_action_bar_exists_hidden_and_takes_layout_calls() {
 /// forever, where nil fails loudly. Pinned so a later "completeness" pass cannot quietly add it.
 #[test]
 fn the_reference_action_bar_constants_are_defined() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_action_bar(&s);
 
@@ -1578,6 +1594,7 @@ fn the_reference_action_bar_constants_are_defined() {
 /// full thing, or 48 `inherits=` sites across four files silently lose their handlers.
 #[test]
 fn both_reference_action_button_templates_are_inheritable() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_action_bar(&s);
 
@@ -1662,6 +1679,7 @@ fn both_reference_action_button_templates_are_inheritable() {
 /// every extra bar ships off and nothing has claimed a page yet.
 #[test]
 fn the_main_bar_pages_and_a_bonus_page_still_outranks_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for file in [
@@ -1837,6 +1855,7 @@ fn the_main_bar_pages_and_a_bonus_page_still_outranks_it() {
 /// pressed the instant you enter stealth already drives the stealth page.
 #[test]
 fn bonus_bar_slides_up_with_sound_and_down_without() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     super::test_ui::load_ui(&s, "Interface\\FrameXML\\Cooldown.xml");
@@ -2059,6 +2078,7 @@ fn bonus_bar_slides_up_with_sound_and_down_without() {
 /// quirk (1524).
 #[test]
 fn bonus_bar_turnaround_continues_from_position() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     super::test_ui::load_ui(&s, "Interface\\FrameXML\\Cooldown.xml");
@@ -2141,6 +2161,7 @@ fn bonus_bar_turnaround_continues_from_position() {
 /// actually draws, which separates them — the insets are behaviour here, not decoration.
 #[test]
 fn the_page_arrows_do_not_steal_each_other_s_clicks() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     super::test_ui::load_ui(&s, "Interface\\FrameXML\\Cooldown.xml");
diff --git a/crates/benilla-app/src/ui_script/addons.rs b/crates/benilla-app/src/ui_script/addons.rs
index 997ce1d0..00e80e14 100644
--- a/crates/benilla-app/src/ui_script/addons.rs
+++ b/crates/benilla-app/src/ui_script/addons.rs
@@ -27,14 +27,13 @@
 //!
 //! ## The load order is the reference's, not a topological sort
 //!
-//! `AddOn_Load 0x51f240` is **recursive**, and wow-5875-re has it byte-verified
-//! (`system/ui/ui.md`, the SavedVariables §5 quad): for each addon, in order —
+//! `AddOn_Load 0x51f240` is **recursive**: for each addon, in order —
 //! **OptionalDeps first (failures ignored)** → **RequiredDeps (a failure ABORTS this addon's
 //! load)** → **its own `.toc`-listed files, in listed order**. We match that shape, because a
 //! pre-sorted flat list cannot express "a missing hard dependency drops exactly this addon and
 //! nothing else".
 //!
-//! **Our own interface is not an addon for lifecycle purposes.** The same source records that
+//! **Our own interface is not an addon for lifecycle purposes.** In the reference,
 //! *FrameXML does not go through `AddOn_Load`, so it gets no `ADDON_LOADED`* — and `benilla.toc`
 //! is excluded exactly as FrameXML is. Structurally, not by a filter: it loads through
 //! [`super::manifest::load_ingame_ui`], while [`Walk`] only ever walks what [`discover`] found.
@@ -47,7 +46,7 @@
 //! key-binding table the Key Bindings window edits, so an addon's binding is a row like any
 //! other; the app's dispatch runs its Lua body ([`crate::bindings`]).
 
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
 
 use bevy::prelude::*;
@@ -187,11 +186,10 @@ impl Addon {
     ///
     /// `path` is the entry already resolved into the install's path space, which is the only thing
     /// the client names a file chunk after: `"@%s"` (`0x8716e0`) over the resolved path, built by
-    /// `0x704bc0` for every `.lua` the loader touches (wow-re
-    /// `ui/scratch/include-lua-dispatch.md` §7). So an addon's file is `Interface\AddOns\<Folder>
-    /// \<File>` and a chain file is `Interface\FrameXML\…` — the second being both what the real
-    /// client names it and what keeps FrameXML *out* of the `\AddOns\` pattern the Ace2 family
-    /// matches against, because FrameXML is not an addon.
+    /// `0x704bc0` for every `.lua` the loader touches. So an addon's file is
+    /// `Interface\AddOns\<Folder>\<File>` and a chain file is `Interface\FrameXML\…` — the second
+    /// being both what the real client names it and what keeps FrameXML *out* of the `\AddOns\`
+    /// pattern the Ace2 family matches against, because FrameXML is not an addon.
     ///
     /// **One rule for both doors, which is the point** (decision 2155). `Loader::run` names a
     /// `<Script file=>` chunk by exactly this rule over exactly this space, so a manifest entry and
@@ -297,10 +295,10 @@ impl Addon {
             let report = benilla_ui::loader::load_in(script, &doc, &path, &provider);
             // `FrameXML_Debug`'s trace lines, if the player turned it on (2160). Log-only, and
             // never retained: the reference files them into the same per-document record as the
-            // errors, but at severity 0 and *where that record surfaces is an open question in
-            // wow-re* (`framexml-debug-trace-flag.md`, and `xml-template-name-lookup.md` §9 for
-            // severity 1). So they go where a trace can go without claiming a surface we have not
-            // derived — and the switch that produces them is off unless an addon asks.
+            // errors, but at severity 0 (`0x6ee2bc`), and *where that record surfaces is an open
+            // question*, for severity 1 as well. So they go where a trace can go without claiming a
+            // surface we have not derived — and the switch that produces them is off unless an
+            // addon asks.
             for t in &report.traces {
                 info!("ui_script({}/{file}): {t}", self.name);
             }
@@ -387,16 +385,15 @@ fn read_under(root: &Path, rel: &str) -> Option<Vec<u8>> {
 /// an addon's file, `Interface/FrameXML/…` for one that walked out of the AddOns tree. The
 /// reference has exactly one such space — `0x647e60` answers a name from a hash index of the
 /// install tree keyed by **install-root-relative path**, and then, attempt #4, from the MPQ chain
-/// (wow-re `ui/scratch/include-lua-dispatch.md` §4.1, VERIFIED; loose *before* archive, which is
-/// the order below). Two spaces is what this client had, and it cost three separate things:
+/// (loose *before* archive, which is the order below). Two spaces is what this client had, and it
+/// cost three separate things:
 ///
 /// - `..\Blizzard_AuctionUI\Blizzard_AuctionUITemplates.xml`, a `.toc` line in `Auctioneer` and
 ///   in `BeanCounter`, collapses to `Interface/AddOns/Blizzard_AuctionUI/…` — a folder that is a
 ///   `.pub` decoy on disk with the real files inside `patch.MPQ`. Only the chain leg has it.
 /// - `..\..\FrameXML\Fonts.xml`, a `.toc` line in `JIM_toolbox` and in `SpecialTalentUI`,
 ///   collapses out of the AddOns tree entirely, to `Interface/FrameXML/Fonts.xml`. Same leg.
-///   (wow-re records both by name as **RESOLVING** on the real client —
-///   `ui/scratch/xml-toc-path-resolution.md` §5 cases 1 and 2.)
+///   (Both **RESOLVE** on the real client: `0x6ede10` collapses the `..` before the open.)
 /// - and the one that was invisible: with the addon space rooted at the AddOns folder, a
 ///   `<Script file=>` chunk was NAMED after that space — `@AtlasLoot\Core\AtlasLoot.lua` — while
 ///   a `.toc`-listed one was named `@Interface\AddOns\AtlasLoot\…`. See [`Addon::chunk_name`].
@@ -504,13 +501,13 @@ fn chain_addons() -> Vec<Addon> {
 /// Every registered addon, in the reference's own **registration order**: the archive pass first,
 /// then the loose folders (decision 2175).
 ///
-/// **Two passes, archive before loose, and the first pass wins a duplicate.** Byte-read in wow-re
-/// `system/ui/scratch/addon-registry-scan-and-order.md` §1–§5: `AddOn_ScanAddOnDir 0x51c760` runs
+/// **Two passes, archive before loose, and the first pass wins a duplicate.**
+/// `AddOn_ScanAddOnDir 0x51c760` runs
 /// `0x401470` over each mounted archive's `(listfile)` (`0x648fb0`, textual line order) and only
 /// then `0x42ad10`'s `FindFirstFileW` walk of the loose directories; both funnel into
 /// `0x51c9b0`, which probes the name hash and **returns immediately on a hit** (`0x51ca10`), and
 /// links each new record at the TAIL (`0x521ad0` mode 2 — a tail insert with no comparison of any
-/// kind, so registry order *is* registration order). §10 measures the consequence on a stock
+/// kind, so registry order *is* registration order). Measured on a stock
 /// install: the twelve `Blizzard_*` `.toc`s are the only ones in any archive, so Blizzard occupies
 /// registry positions 1..12 and third-party always follows.
 ///
@@ -521,11 +518,12 @@ fn chain_addons() -> Vec<Addon> {
 ///
 /// The load walk barely notices (all twelve are `## LoadOnDemand: 1`, so `0x51f600` skips them),
 /// but the registry order is what the Lua index space is built from, and it is what decides which
-/// addon's copy of a shared global wins — the last writer, per §9.
+/// addon's copy of a shared global wins — the last writer, in the one shared Lua state
+/// (`0x7040d0`).
 fn discover() -> Vec<Addon> {
     // PASS 1 — the archive. `BLIZZARD_ADDONS` is in ascending name order, which is also the order
-    // the shipped `patch.MPQ` listfile happens to carry those twelve lines in (§10, measured). The
-    // note is explicit that a re-implementation may NOT rely on a listfile being sorted, so this is
+    // the shipped `patch.MPQ` listfile happens to carry those twelve lines in (measured). A
+    // re-implementation may NOT rely on a listfile being sorted, so this is
     // our deterministic choice for a set we enumerate ourselves, not a claim about the format.
     let mut found = chain_addons();
     // PASS 2 — the loose folders, minus anything the archive already registered.
@@ -541,11 +539,10 @@ fn discover() -> Vec<Addon> {
 /// **The reference's directory-listing order, as a sort key** — the one thing 2166 §7 left open.
 ///
 /// The reference's loose-folder pass is `0x42ad10`'s kernel32 `FindFirstFileW`/`FindNextFileW`
-/// walk (wow-re `system/ui/scratch/addon-registry-scan-and-order.md`), and that walk **imposes no
-/// ordering of its own**: the client never sorts, so its walk order is whatever the host
-/// filesystem hands back. wow-re states the consequence outright — *"a re-implementation cannot be
+/// walk, and that walk **imposes no ordering of its own**: the client never sorts, so its walk
+/// order is whatever the host filesystem hands back. So a re-implementation cannot be
 /// order-identical to the reference, because the reference's order is not a property of the
-/// reference."*
+/// reference.
 ///
 /// So there is no order to copy, and exactly one order worth choosing: **NTFS's**. It is the order
 /// every 1.12 install actually walked in, because that is the filesystem the client shipped on, and
@@ -564,8 +561,8 @@ fn discover() -> Vec<Addon> {
 /// positions move** — `Fubar_*` interleaves with `FuBar_*` instead of following it wholesale,
 /// `oRA2` climbs 31 places, `zBar` overtakes `Zorlen`, and `_LazyPig`/`_Nameplates` fall from the
 /// middle to dead last. Since the client runs every addon in one Lua state and adds no versioning
-/// (wow-re §9: *which provider of a shared library wins is exactly "whichever addon's files run
-/// last"*), that reshuffle decides which copy of `Tablet-2.0` a corpus of seventy providers ends up
+/// (`0x7040d0`: which provider of a shared library wins is exactly whichever addon's files run
+/// last), that reshuffle decides which copy of `Tablet-2.0` a corpus of seventy providers ends up
 /// with.
 ///
 /// The corpus corroborates the mechanism from the other side: the `!`-prefix convention
@@ -773,16 +770,21 @@ pub(crate) struct InstalledAddOn {
     pub(crate) url: Option<String>,
     pub(crate) dependencies: Vec<String>,
     /// `## Interface` as the version gate reads it (decision 1292): the leading integer, `0`
-    /// when absent — and now ENFORCED by the load walk when `checkAddonVersion` is on,
-    /// superseding 1191 §6's report-only interim (the RE answer it was waiting for landed:
-    /// wow-re `addon-version-gate.md`).
+    /// when absent — and now ENFORCED by the load walk when `checkAddonVersion` is on
+    /// (`0x51e876`), superseding 1191 §6's report-only interim.
     pub(crate) interface: u32,
     /// `## LoadOnDemand: 1` — shown as a status hint rather than a checkbox state, because a
     /// LoadOnDemand addon is not "off", it is waiting for a `LoadAddOn` call (1191 §6).
     /// Read by the char-select AddOns screen's rows (`char_select::addons`).
     pub(crate) load_on_demand: bool,
-    /// From this character's enable file; an addon the file never mentions is **enabled** (1191 §7).
-    pub(crate) enabled: bool,
+    /// `## DefaultState:` — what this addon is for a character with no opinion, and the tie-break
+    /// when the realm's characters disagree.
+    ///
+    /// **This row carries no enable bit**, deliberately (decision 2311). It used to, read out of
+    /// one character's file with "absent means enabled" baked in — which is the bug: an absent
+    /// row is not enabled, it is [`EnableStore::enabled_for`]'s question, and the store needs the
+    /// realm's whole character list to answer it. Metadata here, state there.
+    pub(crate) default_state: bool,
 }
 
 impl InstalledAddOn {
@@ -814,14 +816,13 @@ impl InstalledAddOn {
 /// The array's *membership* needs nothing here: it excludes the addons the server hid, which on a
 /// stock install is Blizzard's twelve, and this walk is the player's own folder only — they were
 /// never in it.
-pub(crate) fn installed(identity: Option<&(String, String)>) -> Vec<InstalledAddOn> {
-    let disabled = disabled_set(identity);
+pub(crate) fn installed_rows() -> Vec<InstalledAddOn> {
     // The player's own folder only: the glue's list is what a player can toggle, and the
     // reference's Blizzard addons are not in it.
     let mut rows: Vec<InstalledAddOn> = discover_folder()
         .into_iter()
         .map(|addon| InstalledAddOn {
-            enabled: !disabled.contains(&addon.name.to_ascii_lowercase()),
+            default_state: addon.toc.default_state(),
             title: addon.toc.directive("Title").map(str::to_owned),
             notes: addon.toc.directive("Notes").map(str::to_owned),
             url: addon.toc.directive("URL").map(str::to_owned),
@@ -843,18 +844,131 @@ pub(crate) fn installed(identity: Option<&(String, String)>) -> Vec<InstalledAdd
     rows
 }
 
-/// The lowercased names this character has turned off.
-fn disabled_set(identity: Option<&(String, String)>) -> HashSet<String> {
-    enable_state_path(identity)
-        .and_then(|p| std::fs::read(p).ok())
-        .map(|b| {
-            parse_enable_state(&benilla_ui::source::decode(&b))
-                .into_iter()
-                .filter(|(_, on)| !on)
-                .map(|(n, _)| n.to_ascii_lowercase())
-                .collect()
-        })
-        .unwrap_or_default()
+// ── The enable store — the reference's `ADDONSTATELIST` ──────────────────────────────────────────
+
+/// **One node per character on the realm's character list, each holding the explicit rows that
+/// character's `AddOns.txt` carried** — the reference's `ADDONSTATELIST` (anchor `0xbe1bd0`, head
+/// `ds:0xbe1bd8`), which `AddOnList_LoadCharacter 0x51ebe0` fills one node per character at
+/// char-list population.
+///
+/// The node set is the **char-list, in wire order, rebuilt whole** (decision 2316): the per-record
+/// callback `0x472300` is handed to an enumerator that walks every `SMSG_CHAR_ENUM` record with no
+/// filter and no early-out, and its driver destroys every existing node first (`0x51f0b0(NULL)`).
+///
+/// **A node with no file is EMPTY, not absent**, and the difference is the whole point: an empty
+/// node contributes no opinion to the aggregate, but it is still a character whose enable bit has
+/// to be answered — and the reference answers it from the *other* characters, never with a bare
+/// "enabled". That was the bug this type was written for (decision 2311): benilla resolved an
+/// absent row as enabled, so creating a character re-enabled every addon the player had just
+/// turned off, on every character at once.
+#[derive(Default)]
+pub(crate) struct EnableStore {
+    /// `(character, explicit rows)` in character-list order; the map is the node's enable hash,
+    /// keyed lowercased because every compare in the reference is `SStrCmpI`.
+    nodes: Vec<(String, HashMap<String, bool>)>,
+}
+
+impl EnableStore {
+    /// Load a node per character, each from its own `AddOns.txt`
+    /// (`benilla-config/addons/<Realm>-<Char>.txt`, decision 1191 §7). A character with no file
+    /// still gets its node.
+    pub(crate) fn load(realm: &str, characters: &[String]) -> Self {
+        let nodes = characters
+            .iter()
+            .map(|character| {
+                let id = (realm.to_string(), character.clone());
+                let rows = enable_state_path(Some(&id))
+                    .and_then(|p| std::fs::read(p).ok())
+                    .map(|b| parse_enable_state(&benilla_ui::source::decode(&b)))
+                    .unwrap_or_default();
+                let hash = rows
+                    .into_iter()
+                    // Last line wins, like the reference's hash insert (`0x51eeef`).
+                    .map(|(name, on)| (name.to_ascii_lowercase(), on))
+                    .collect();
+                (character.clone(), hash)
+            })
+            .collect();
+        Self { nodes }
+    }
+
+    /// `0x51e470(addon, NULL, useDefault = 0)` — the **explicit-only** aggregate. A node with no
+    /// entry for this addon is not counted at all (`0x51e5df je 0x51e60a`).
+    ///
+    /// `Some(v)` is the reference's 2/0 (every counted node agrees on `v`); `None` folds its two
+    /// *undecided* returns together — the mixed `1` and the `total == 0` epilogue — because both
+    /// resolve the same way one level up, through `DefaultState`.
+    fn aggregate(&self, addon: &str) -> Option<bool> {
+        let key = addon.to_ascii_lowercase();
+        let mut total = 0usize;
+        let mut on = 0usize;
+        for (_, hash) in &self.nodes {
+            if let Some(&v) = hash.get(&key) {
+                total += 1;
+                on += usize::from(v);
+            }
+        }
+        match (total, on) {
+            (0, _) => None,
+            (_, 0) => Some(false),
+            (t, o) if o == t => Some(true),
+            _ => None,
+        }
+    }
+
+    /// **The bit a character actually gets** — `0x51e470(addon, character, useDefault = 1)`
+    /// lowered to a bool (a single-character query returns only 0 or 2).
+    ///
+    /// Three cases, and the reference distinguishes the last two (decision 2316, which corrects
+    /// 2311's reading of them as one):
+    ///
+    /// * **their file has an explicit row** → that row, and nothing else is consulted;
+    /// * **they have a node but no row for this addon** → [`Self::aggregate`], the explicit-only
+    ///   fold over the character list (`0x51e5f0`'s self-recursion), falling to `## DefaultState`
+    ///   only where that is undecided;
+    /// * **no node carries their name at all** → `## DefaultState`, *not* the aggregate. The walk
+    ///   compares the name at every node and advances past each mismatch
+    ///   (`0x51e55a jne 0x51e611`, bypassing the stop-check at `0x51e60a`), so it exhausts with
+    ///   `total == 0` and takes that epilogue. A character the list does not carry inherits
+    ///   nothing. `None` — nobody picked yet — is this case too.
+    ///
+    /// That third arm is unreachable from our own callers: every panel column is a node, and
+    /// [`store_nodes`] seats the loading character. It is written faithfully anyway, because the
+    /// next caller would otherwise find the wrong branch sitting here and have no way to know.
+    pub(crate) fn enabled_for(
+        &self,
+        addon: &str,
+        default_state: bool,
+        character: Option<&str>,
+    ) -> bool {
+        let Some(node) = character.and_then(|c| self.node(c)) else {
+            return default_state;
+        };
+        match node.get(&addon.to_ascii_lowercase()) {
+            Some(&explicit) => explicit,
+            None => self.aggregate(addon).unwrap_or(default_state),
+        }
+    }
+
+    fn node(&self, character: &str) -> Option<&HashMap<String, bool>> {
+        self.nodes
+            .iter()
+            .find(|(name, _)| name.eq_ignore_ascii_case(character))
+            .map(|(_, hash)| hash)
+    }
+}
+
+/// The store's node set for a load: the realm's character list, with the loading character
+/// appended when the caller had no list to give (a test, a capture, a `.go`-style entry) — so a
+/// one-identity caller still gets its own file honoured, and nothing else.
+fn store_nodes(identity: Option<&(String, String)>, roster: &[String]) -> Vec<String> {
+    let mut names = roster.to_vec();
+    if let Some((_, character)) = identity {
+        if !names.iter().any(|n| n.eq_ignore_ascii_case(character)) {
+            names.push(character.clone());
+        }
+    }
+    names
 }
 
 /// Write a character's enable state — the AddOns screen's write (decision 1197) and, since 2139,
@@ -863,10 +977,10 @@ fn disabled_set(identity: Option<&(String, String)>) -> HashSet<String> {
 /// **Merges rather than replaces, because that is what the reference's writer structurally IS.**
 /// `0x51ef20` walks the in-memory enable **hash** and emits one `"%s: %s\r\n"` line per entry
 /// (`0x853968`), and that hash is built by the reader `0x51ebe0` from `AddOns.txt` itself — which
-/// "creates entries for every line, both states", strdup'ing each name as written. So a row for an
+/// creates entries for every line, both states, strdup'ing each name as written. So a row for an
 /// addon that is not installed right now was loaded, is never removed, and is written straight back
 /// out; and the spelling that survives is the FILE's, not any folder's, because the folder list
-/// never enters the hash at all (wow-5875-re `system/ui/scratch/addon-enable-store.md` §5/§6).
+/// never enters the hash at all.
 ///
 /// Both halves matter and both were divergent on the logout path, which used to rebuild the file
 /// from `addon_enable_states()` — the installed-folder registry. One logout erased
@@ -932,9 +1046,19 @@ pub(super) fn save_addon_variables(script: &mut UiScript, identity: Option<&(Str
                 continue;
             }
             let Some(dir) = dir else { continue };
-            let body = script.saved_variables_text_for(names);
             let path = dir.join(format!("{name}.lua"));
-            match crate::local_state::write_atomic(&path, &format!("{SAVED_HEADER}{body}")) {
+            if script.saved_file_held(&path) {
+                // It failed to load this session: its globals are the addon's defaults, and
+                // writing them would replace the player's file with them.
+                warn!(
+                    "ui_script: {} did not load this session — left as it is",
+                    path.display()
+                );
+                continue;
+            }
+            let mut body = SAVED_HEADER.as_bytes().to_vec();
+            body.extend(script.saved_variables_bytes_for(names));
+            match crate::local_state::write_atomic_bytes(&path, &body) {
                 Ok(()) => info!("ui_script: wrote {}", path.display()),
                 Err(e) => warn!("ui_script: cannot write {}: {e}", path.display()),
             }
@@ -967,6 +1091,7 @@ const SAVED_HEADER: &str = "\
 pub(super) fn load_third_party(
     script: &mut UiScript,
     identity: Option<&(String, String)>,
+    roster: &[String],
     version_check: bool,
 ) -> Vec<String> {
     let addons = discover();
@@ -976,15 +1101,19 @@ pub(super) fn load_third_party(
     let mut infos: Vec<_> = addons.iter().map(info_for).collect();
     // The chain-sourced rows read through the reference's own store (1957).
     script.set_addon_chain_reader(Box::new(super::reference_ui::read));
-    if let Some(text) = enable_state_path(identity).and_then(|p| std::fs::read_to_string(p).ok()) {
-        for (name, enabled) in parse_enable_state(&text) {
-            if let Some(i) = infos
-                .iter_mut()
-                .find(|i| i.name.eq_ignore_ascii_case(&name))
-            {
-                i.enabled = enabled;
-            }
-        }
+    // Every addon's enable bit, through the reference's own query (decision 2311): this
+    // character's explicit `AddOns.txt` row when they have one, else what the realm's other
+    // characters agree on, else the manifest's `## DefaultState`. Reading an absent row as a
+    // bare "enabled" is what re-enabled every addon the moment a character was created.
+    let store = EnableStore::load(
+        identity
+            .map(|(realm, _)| realm.as_str())
+            .unwrap_or_default(),
+        &store_nodes(identity, roster),
+    );
+    let character = identity.map(|(_, c)| c.as_str());
+    for (info, addon) in infos.iter_mut().zip(addons.iter()) {
+        info.enabled = store.enabled_for(&info.name, addon.toc.default_state(), character);
     }
     let disabled_names: HashSet<String> = infos
         .iter()
@@ -1072,7 +1201,7 @@ impl Walk {
     /// Load one addon by name, its dependencies first. `Err` means "this addon did not load", and
     /// is what a hard dependency's failure propagates.
     ///
-    /// The order inside is `AddOn_Load 0x51f240`'s, byte-verified in wow-5875-re (`system/ui/ui.md`):
+    /// The order inside is `AddOn_Load 0x51f240`'s:
     ///
     /// > OptionalDeps (failures ignored) → RequiredDeps (a failure aborts) → **this addon's own
     /// > `.toc`-listed files, in listed order** (`0x51f3fa`) → `Bindings.xml` (`0x51f400`) → the
@@ -1206,8 +1335,8 @@ impl Walk {
 mod tests {
     /// **The walk order is NTFS's, not byte order** — the fact 2166 §7 left open, pinned here.
     ///
-    /// The reference's loose pass is `FindFirstFileW` and sorts nothing (wow-re
-    /// `addon-registry-scan-and-order.md`), so its order is the host filesystem's; NTFS's `$I30`
+    /// The reference's loose pass is `FindFirstFileW` and sorts nothing
+    /// (`0x42ad10`), so its order is the host filesystem's; NTFS's `$I30`
     /// collation is the one we adopt, because it is the order the entire vanilla corpus was
     /// written against. Two rules distinguish it from `str`'s own `Ord`, and this asserts both:
     /// **case folds away** (so a lowercase-initial name sorts among its letter's block rather
@@ -1328,7 +1457,7 @@ mod tests {
         // No `## Title` at all — sorts under its folder name, the comparator's own fallback.
         write_addon(&home, "bravo", "## Interface: 11200\n", &[]);
 
-        let rows = installed(None);
+        let rows = installed_rows();
         assert_eq!(
             rows.iter().map(|a| a.name.as_str()).collect::<Vec<_>>(),
             vec!["Zulu", "bravo", "Mike", "Alpha"],
@@ -1454,7 +1583,7 @@ mod tests {
             "benilla.toc lists a Blizzard addon eagerly; the reference loads every one on demand"
         );
         // The glue's list is the player's folder alone.
-        assert!(installed(None)
+        assert!(installed_rows()
             .iter()
             .all(|a| !a.name.starts_with("Blizzard_")));
     }
@@ -1597,10 +1726,10 @@ mod tests {
     /// `IsAddOnLoadOnDemand(nil)` and AtlasLoot's AceDB keyed itself on a raw traceback. 80 of the
     /// 219-addon corpus ship at least one `<Script file=>`.
     ///
-    /// The reference names both the same way and the note says why: a `.toc` line resolves against
-    /// `Interface\AddOns\<Addon>\` and a bare `<Script file=X>` against `dirname(referrer)` —
-    /// the same directory — and the chunk name is `"@%s"` over the resolved path in both cases
-    /// (wow-re `ui/scratch/xml-toc-path-resolution.md` §1, `include-lua-dispatch.md` §7).
+    /// The reference names both the same way: a `.toc` line resolves against
+    /// `Interface\AddOns\<Addon>\` and a bare `<Script file=X>` against `dirname(referrer)`
+    /// (`0x6ee07b`) — the same directory — and the chunk name is `"@%s"` over the resolved path in
+    /// both cases (`0x704bc0`).
     #[test]
     fn an_xml_referenced_lua_is_named_like_a_toc_listed_one() {
         let tmp =
@@ -2010,8 +2139,8 @@ mod tests {
 
     /// **`benilla` never appears in an `ADDON_LOADED`.**
     ///
-    /// FrameXML does not go through `AddOn_Load` and gets no such event (wow-5875-re
-    /// `system/ui/ui.md`), and our own interface is FrameXML's counterpart. An addon that watches
+    /// In the reference, FrameXML does not go through `AddOn_Load` and gets no such event, and
+    /// our own interface is FrameXML's counterpart. An addon that watches
     /// `ADDON_LOADED` to detect *another* addon would otherwise see a name no reference client
     /// ever sends.
     ///
@@ -2102,7 +2231,7 @@ mod tests {
         let mut script = UiScript::new().unwrap();
         script.set_screen_size(1024.0, 768.0);
         script.run("EventLog = {}").unwrap();
-        let failures = load_third_party(&mut script, None, true);
+        let failures = load_third_party(&mut script, None, &[], true);
         assert!(failures.is_empty(), "load errors: {failures:?}");
         crate::ui_script::finish_ui_load(&mut script);
 
@@ -2175,7 +2304,7 @@ mod tests {
         );
 
         let mut script = UiScript::new().unwrap();
-        let failures = load_third_party(&mut script, None, true);
+        let failures = load_third_party(&mut script, None, &[], true);
         assert!(
             failures.iter().any(|f| f.contains("NeedsOld")),
             "the gated dependency is the dependent's failure: {failures:?}"
@@ -2199,7 +2328,7 @@ mod tests {
 
         // Force-load: the same folder, the checkbox's other state — everything loads.
         let mut open = UiScript::new().unwrap();
-        let failures = load_third_party(&mut open, None, false);
+        let failures = load_third_party(&mut open, None, &[], false);
         assert!(failures.is_empty(), "force-load load errors: {failures:?}");
         assert_eq!(
             open.eval::<bool>(
@@ -2273,7 +2402,7 @@ mod tests {
         );
 
         let mut script = UiScript::new().unwrap();
-        let failures = load_third_party(&mut script, None, true);
+        let failures = load_third_party(&mut script, None, &[], true);
         assert!(failures.is_empty(), "load errors: {failures:?}");
 
         // Discovery saw it at all — the `.toc` decoded rather than read as absent.
@@ -2365,8 +2494,7 @@ mod tests {
     /// **The client registers `GetAddOnInfo` twice, as two different functions**, and this test
     /// used to assert the wrong one. It was written off `Interface\GlueXML\AddonList.lua`, which
     /// describes glue's `0x46d460`: eight values, `url` at slot 4, `newVersion` at 8. The in-game
-    /// binding `0x48e390` answers seven, with **`enabled`** at slot 4 and no `url` at all
-    /// (wow-re `system/ui/scratch/addon-version-gate.md`).
+    /// binding `0x48e390` answers seven, with **`enabled`** at slot 4 and no `url` at all.
     ///
     /// Its own doc comment named the failure it then failed to catch — *"a row that shifts by one
     /// puts an addon's notes in its URL field, which nothing would notice"*. The row was shifted at
@@ -2394,7 +2522,7 @@ mod tests {
             &[],
         );
         let mut script = UiScript::new().unwrap();
-        let _ = load_third_party(&mut script, None, true);
+        let _ = load_third_party(&mut script, None, &[], true);
 
         // **One**, not one-plus-the-chain (decision 2175). The registry holds the chain's twelve
         // Blizzard rows too, but the Lua index space is a different set: `SMSG_ADDON_INFO` answers
@@ -2496,7 +2624,7 @@ mod tests {
 
         let mut script = UiScript::new().unwrap();
         let id = ("Realm".to_string(), "Char".to_string());
-        let failures = load_third_party(&mut script, Some(&id), true);
+        let failures = load_third_party(&mut script, Some(&id), &[], true);
 
         assert!(
             failures.is_empty(),
@@ -2554,7 +2682,7 @@ mod tests {
         );
         let mut script = UiScript::new().unwrap();
         script.set_screen_size(1024.0, 768.0);
-        let _ = load_third_party(&mut script, None, true);
+        let _ = load_third_party(&mut script, None, &[], true);
 
         // Discovered and described, but NOT run.
         // **One**, not one-plus-the-chain (decision 2175). The registry holds the chain's twelve
@@ -2650,7 +2778,7 @@ mod tests {
         );
         let mut script = UiScript::new().unwrap();
         script.set_screen_size(1024.0, 768.0);
-        let _ = load_third_party(&mut script, None, true);
+        let _ = load_third_party(&mut script, None, &[], true);
 
         // The dependency loaded at startup and the registry knows it — the stamp this rests on.
         assert_eq!(
@@ -2681,8 +2809,8 @@ mod tests {
     /// **A `.toc` line naming a file the package does not ship does not stop a demand load**
     /// (decision 2107) — 1450's rule, applied by `LoadAddOn` and not only by the startup walk.
     ///
-    /// The reference logs `Couldn't open %s` and carries on (wow-re
-    /// `xml-toc-path-resolution.md` §4). Ours sent the miss to the **script-error** channel
+    /// The reference logs `Couldn't open %s` and carries on
+    /// (`0x6edaa0`). Ours sent the miss to the **script-error** channel
     /// instead, and the corpus paid for it the moment `LoadAddOn` became reachable at scale:
     /// FuBar's `LoadLoadOnDemandPlugins` demand-loads 55 plugins whose `.toc`s each list an
     /// `AmmoFuLocale-koKR.lua` none of them ships, and every one of them scored a session
@@ -2704,7 +2832,7 @@ mod tests {
         );
         let mut script = UiScript::new().unwrap();
         script.set_screen_size(1024.0, 768.0);
-        let _ = load_third_party(&mut script, None, true);
+        let _ = load_third_party(&mut script, None, &[], true);
 
         assert_eq!(
             script
@@ -2766,7 +2894,7 @@ mod tests {
 
         let mut script = UiScript::new().unwrap();
         let id = ("Realm".to_string(), "Char".to_string());
-        let _ = load_third_party(&mut script, Some(&id), true);
+        let _ = load_third_party(&mut script, Some(&id), &[], true);
 
         for (call, want) in [
             ("LoadAddOn('NoSuchAddon')", "MISSING"),
@@ -2788,6 +2916,133 @@ mod tests {
         let _ = std::fs::remove_dir_all(home.parent().unwrap());
     }
 
+    /// **A character with no enable file does not load what the realm has unanimously turned
+    /// off** — the world-entry half of the director's 2026-09-17 report (decision 2311).
+    ///
+    /// The glue list showing a new character's addons as off would be worth nothing if the world
+    /// then loaded them anyway, so the load walk resolves through the same [`EnableStore`]: the
+    /// reference's `AddOn_CanLoad` check 3 is `0x51e470(name, character, useDefault = 1)`, which
+    /// for a character with no explicit entry takes the explicit-only aggregate over the realm's
+    /// other characters.
+    ///
+    /// The control is the second addon: one character left it on, so the roster does **not** agree
+    /// about it, and the newcomer gets its manifest's `## DefaultState` instead — enabled. Without
+    /// that half the test would pass on a client that simply disabled everything for new
+    /// characters.
+    #[test]
+    fn a_character_with_no_file_inherits_the_rosters_unanimous_disable() {
+        let _l = crate::local_state::test_env::ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let _c = crate::local_state::test_env::EnvGuard::unset("WOW_CAPTURE");
+        let (home, _h) = hermetic_root("inherit");
+        write_addon(
+            &home,
+            "Shunned",
+            "## Interface: 11200\nran.lua\n",
+            &[("ran.lua", "ShunnedRan = true")],
+        );
+        write_addon(
+            &home,
+            "Contested",
+            "## Interface: 11200\nran.lua\n",
+            &[("ran.lua", "ContestedRan = true")],
+        );
+        // Two characters who have played and saved: both turned `Shunned` off, they disagree
+        // about `Contested`.
+        for (who, contested) in [("Onemage", false), ("Onerogue", true)] {
+            let id = ("Realm".to_string(), who.to_string());
+            write_enable_state(
+                Some(&id),
+                &[("Shunned".into(), false), ("Contested".into(), contested)],
+            );
+        }
+        let roster = [
+            "Onemage".to_string(),
+            "Onerogue".to_string(),
+            "Freshling".to_string(),
+        ];
+
+        // …and the character just created, who has no file of their own.
+        let fresh = ("Realm".to_string(), "Freshling".to_string());
+        assert!(
+            !enable_state_path(Some(&fresh)).unwrap().exists(),
+            "the premise: a newly created character has written nothing"
+        );
+        let mut script = UiScript::new().unwrap();
+        let _ = load_third_party(&mut script, Some(&fresh), &roster, true);
+
+        assert_eq!(
+            script.eval::<bool>("return ShunnedRan == nil").ok(),
+            Some(true),
+            "the unanimous disable reaches the character who never expressed one"
+        );
+        assert_eq!(
+            script.eval::<bool>("return ContestedRan == true").ok(),
+            Some(true),
+            "…and a contested addon falls to its `## DefaultState`, which is enabled"
+        );
+        let _ = std::fs::remove_dir_all(home.parent().unwrap());
+    }
+
+    /// **A name the character list does not carry inherits nothing** — the third arm of
+    /// `0x51e470(addon, character, useDefault = 1)`, and the one 2311 got wrong (decision 2316).
+    ///
+    /// 2311 read "no explicit row" and "no node" as one case and sent both to the aggregate. The
+    /// reference splits them: the walk compares the name at every node and advances past each
+    /// mismatch (`0x51e55a jne 0x51e611`, bypassing the stop-check), so an unknown name exhausts
+    /// the list with `total == 0` and takes the `DefaultState ? 2 : 0` epilogue. Only a character
+    /// that *has* a node inherits.
+    ///
+    /// Unreachable from our own callers — every panel column is a node, and `store_nodes` seats
+    /// the loading character — so this is the falsifier standing in for the caller that does not
+    /// exist yet. `Known`, who has a node and no row, is the control that keeps the two arms
+    /// honestly distinguishable: both addons are unanimous, so an implementation that collapsed
+    /// the cases would answer `false` for `Stranger` too.
+    #[test]
+    fn an_unknown_character_takes_the_manifest_default_not_the_aggregate() {
+        let _l = crate::local_state::test_env::ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let _c = crate::local_state::test_env::EnvGuard::unset("WOW_CAPTURE");
+        let (home, _h) = hermetic_root("unknown-char");
+        // One unanimous `disabled`, and one addon whose manifest ships `DefaultState: disabled`
+        // so the epilogue's two outcomes are told apart rather than both reading `true`.
+        write_addon(&home, "Shunned", "## Interface: 11200\n", &[]);
+        write_addon(
+            &home,
+            "OptIn",
+            "## Interface: 11200\n## DefaultState: disabled\n",
+            &[],
+        );
+        for who in ["Onemage", "Onerogue"] {
+            let id = ("Realm".to_string(), who.to_string());
+            write_enable_state(
+                Some(&id),
+                &[("Shunned".into(), false), ("OptIn".into(), true)],
+            );
+        }
+        let roster = [
+            "Onemage".to_string(),
+            "Onerogue".to_string(),
+            "Known".to_string(),
+        ];
+        let store = EnableStore::load("Realm", &roster);
+
+        // `Known` has a node and no rows: both addons inherit their unanimous aggregate.
+        assert!(!store.enabled_for("Shunned", true, Some("Known")));
+        assert!(store.enabled_for("OptIn", false, Some("Known")));
+
+        // `Stranger` is on no node: neither aggregate reaches them — each addon answers with its
+        // own manifest default, which is the opposite verdict in both cases.
+        assert!(store.enabled_for("Shunned", true, Some("Stranger")));
+        assert!(!store.enabled_for("OptIn", false, Some("Stranger")));
+        // …and `None` (nobody picked yet) is the same epilogue.
+        assert!(store.enabled_for("Shunned", true, None));
+        assert!(!store.enabled_for("OptIn", false, None));
+        let _ = std::fs::remove_dir_all(home.parent().unwrap());
+    }
+
     /// Enable state survives the session: `DisableAddOn` from Lua is written back in the
     /// reference's own `AddOns.txt` format, and read back as a disable next time.
     #[test]
@@ -2807,7 +3062,7 @@ mod tests {
         let id = ("Realm".to_string(), "Char".to_string());
 
         let mut script = UiScript::new().unwrap();
-        let _ = load_third_party(&mut script, Some(&id), true);
+        let _ = load_third_party(&mut script, Some(&id), &[], true);
         script.run("DisableAddOn('Drop')").unwrap();
         save_enable_state(&script, Some(&id));
 
@@ -2828,7 +3083,7 @@ mod tests {
 
         // A fresh session reads it back and the addon stays off.
         let mut next = UiScript::new().unwrap();
-        let _ = load_third_party(&mut next, Some(&id), true);
+        let _ = load_third_party(&mut next, Some(&id), &[], true);
         assert_eq!(
             next.eval::<bool>("return DropRan == nil").ok(),
             Some(true),
@@ -2879,7 +3134,7 @@ mod tests {
         // ── session one: defaults, then the addon changes them ──
         let mut script = UiScript::new().unwrap();
         script.set_screen_size(1024.0, 768.0);
-        let failures = load_third_party(&mut script, Some(&id), true);
+        let failures = load_third_party(&mut script, Some(&id), &[], true);
         assert!(failures.is_empty(), "{failures:?}");
         assert_eq!(
             script.eval::<i64>("return KeeperSawAtEvent").ok(),
@@ -2894,7 +3149,7 @@ mod tests {
         // ── session two: a fresh VM reads them back ──
         let mut next = UiScript::new().unwrap();
         next.set_screen_size(1024.0, 768.0);
-        let failures = load_third_party(&mut next, Some(&id), true);
+        let failures = load_third_party(&mut next, Some(&id), &[], true);
         assert!(failures.is_empty(), "{failures:?}");
         assert_eq!(
             next.eval::<i64>("return KeeperDB.count").ok(),
@@ -2923,8 +3178,8 @@ mod tests {
     /// `0x7043f0`/`0x704480`): `NAME = value`, bracketed keys, TAB indent, a trailing comma on
     /// every entry, and the file split by scope. `["t"]`'s `[1] = 1,` is the reference's shape for
     /// a list too — its writer emits a bracketed key for every table shape and never a bare
-    /// positional entry (wow-re `system/ui/scratch/lua-table-storage-and-next-order.md` §Q5) —
-    /// and it reloads in index order because of what 1.12's *parser* does with it (decision 2111).
+    /// positional entry — and it reloads in index order because of what 1.12's *parser* does
+    /// with it (decision 2111).
     ///
     /// Asserted as bytes rather than by re-reading, because "it round-trips through our own
     /// loader" is exactly the check that passes for a private format. The reference's own client
@@ -2945,7 +3200,7 @@ mod tests {
         );
         let id = ("Realm".to_string(), "Char".to_string());
         let mut script = UiScript::new().unwrap();
-        let _ = load_third_party(&mut script, Some(&id), true);
+        let _ = load_third_party(&mut script, Some(&id), &[], true);
         script
             .run("GramDB = { ['on'] = true, ['n'] = 2, ['s'] = 'a\\\"b', ['t'] = { 1 } } GramChar = 5")
             .unwrap();
@@ -3007,7 +3262,7 @@ mod tests {
         let id = ("Realm".to_string(), "Char".to_string());
         let mut script = UiScript::new().unwrap();
         script.set_screen_size(1024.0, 768.0);
-        let _ = load_third_party(&mut script, Some(&id), true);
+        let _ = load_third_party(&mut script, Some(&id), &[], true);
         crate::ui_script::shutdown_ui_state(&mut script, Some(&id), true);
 
         let written = std::fs::read_to_string(home.join("saved/Last.lua")).unwrap();
@@ -3048,7 +3303,7 @@ mod tests {
 
         let mut script = UiScript::new().unwrap();
         script.set_screen_size(1024.0, 768.0);
-        let _ = load_third_party(&mut script, Some(&id), true);
+        let _ = load_third_party(&mut script, Some(&id), &[], true);
         script.eval::<()>("DisableAddOn('MyAddon')").unwrap();
         save_enable_state(&script, Some(&id));
 
@@ -3132,7 +3387,7 @@ mod tests {
                  AddonOrder = AddonOrder .. arg1 .. ',' end)",
             )
             .unwrap();
-        let _ = load_third_party(&mut script, None, true);
+        let _ = load_third_party(&mut script, None, &[], true);
 
         // Neither ran at startup — the walk skips LoadOnDemand, which is why a cycle among them
         // is never observed until something demand-loads one.
diff --git a/crates/benilla-app/src/ui_script/bag_tests.rs b/crates/benilla-app/src/ui_script/bag_tests.rs
index 89615c67..1069f952 100644
--- a/crates/benilla-app/src/ui_script/bag_tests.rs
+++ b/crates/benilla-app/src/ui_script/bag_tests.rs
@@ -590,12 +590,13 @@ fn hovered_bag_tooltip_fills_itself_when_the_stats_land() {
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// At a vendor, a bag hover shows the engine-truth sell-price money row (SellPrice × stack, wow-re
-/// tooltip-money.md 0x52b650@0x52e376) — or the ITEM_UNSELLABLE "No sell price" line — and arms
-/// the pouch cursor (ShowContainerSellCursor → Buy over a Point base, cursor-system.md §7);
+/// At a vendor, a bag hover shows the engine-truth sell-price money row (SellPrice × stack,
+/// 0x52b650@0x52e376) — or the ITEM_UNSELLABLE "No sell price" line — and arms
+/// the pouch cursor (ShowContainerSellCursor 0x4fa460 → Buy over a Point base);
 /// leaving resets it.
 #[test]
 fn vendor_bag_hover_shows_sell_price_and_arms_the_pouch_cursor() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::{MerchantState, ScriptValue, UiCursorMode};
 
     let mut s = UiScript::new().unwrap();
@@ -734,6 +735,7 @@ fn vendor_bag_hover_shows_sell_price_and_arms_the_pouch_cursor() {
 /// `this.readable → ShowInspectCursor()`); a plain item leaves the base cursor; leaving resets.
 #[test]
 fn readable_letter_hover_shows_the_inspect_magnifier() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::UiCursorMode;
 
     let mut s = UiScript::new().unwrap();
@@ -1837,10 +1839,9 @@ fn a_key_dropped_on_the_button_files_itself() {
     );
     // And it does not RAISE either, which is the half this test could not assert until the bytes
     // came back. `AddMessage`'s text is fetched through `lua_isstring 0x6f3510` whose failure edge
-    // is a silent jump to the function's own epilogue — no line, no error (wow-5875-re
-    // `addmessage-text-gate-silent-skip.md`, 4-worker cross-check). Ours took an mlua `String` and
-    // raised, which put a script-error dialog on an ordinary player gesture; the fix is in
-    // `messageframe/mod.rs::message_text` and its own test carries the full law.
+    // is a silent jump to the function's own epilogue (`0x79562c`) — no line, no error. Ours took
+    // an mlua `String` and raised, which put a script-error dialog on an ordinary player gesture;
+    // the fix is in `messageframe/mod.rs::message_text` and its own test carries the full law.
     //
     // So a full keyring is a DEAD CLICK on a real 1.12 client, and now here.
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
diff --git a/crates/benilla-app/src/ui_script/bagnon_render_tests.rs b/crates/benilla-app/src/ui_script/bagnon_render_tests.rs
index 161498cb..5033d43a 100644
--- a/crates/benilla-app/src/ui_script/bagnon_render_tests.rs
+++ b/crates/benilla-app/src/ui_script/bagnon_render_tests.rs
@@ -16,53 +16,19 @@
 //! The director saw the first (their `Bagnon_Core` loaded at startup, so `currentPlayer` was
 //! captured nil). Fix only that and you get the second. So the tests below pin **both**, and the
 //! headline is a quad count, not an error count: [`bagnon_draws_a_slot_for_every_bag_slot`] is
-//! green only when 16 item-slot quads actually reach the render list.
+//! green only when every live slot's quad actually reaches the render list — the backpack's 16
+//! and, since the reference's own `ContainerFrame.lua` runs off the chain (1751), the keyring's 12
+//! beside them (Bagnon's default bag set is `{-2, 0, 1, 2, 3, 4}`, `Bagnon.lua:25`).
 //!
 //! Nothing from the corpus is committed, and every test here skips cleanly on a machine without
 //! it — the `ui_chat::ace_gate_tests` rule.
 
-use std::path::{Path, PathBuf};
+use std::path::Path;
 
+use benilla_formats::addon_corpus_or_skip as corpus_or_skip;
 use benilla_ui::script::{AddOnInfo, ContainerSlot, ContainerState, QuadContent, UiScript};
 use benilla_ui::toc::Toc;
 
-/// Where the vanilla addon corpus might be — `$BENILLA_ADDON_CORPUS`, else a sibling checkout
-/// resolved from this crate's manifest (a pool worktree's cwd is not stable across tool calls).
-fn corpus_candidates() -> Vec<PathBuf> {
-    let mut out = Vec::new();
-    if let Some(over) = std::env::var_os("BENILLA_ADDON_CORPUS") {
-        out.push(PathBuf::from(over));
-    }
-    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
-    for up in [2usize, 3, 4] {
-        if let Some(root) = manifest.ancestors().nth(up) {
-            out.push(root.join("wow-addons-vanilla"));
-        }
-    }
-    out
-}
-
-/// The corpus root, or `None` — **a skip, never a failure**: it is third-party content that is
-/// deliberately not in this repo.
-fn corpus() -> Option<PathBuf> {
-    corpus_candidates().into_iter().find(|c| c.is_dir())
-}
-
-macro_rules! corpus_or_skip {
-    () => {
-        match corpus() {
-            Some(root) => root,
-            None => {
-                eprintln!(
-                    "skipping: no vanilla addon corpus — looked in {:?} (set $BENILLA_ADDON_CORPUS)",
-                    corpus_candidates()
-                );
-                return;
-            }
-        }
-    };
-}
-
 /// The corpus **and** a client install — for the tests whose subject is a global that comes from
 /// the reference file this client SOURCES off the player's own patch chain rather than shipping
 /// ([`super::reference_ui`], decision 1234).
@@ -177,6 +143,29 @@ fn roster() -> crate::char_select::Roster {
     crate::char_select::Roster::with_pending_pick(vec![row], 7)
 }
 
+/// The `"player"` snapshot the self descriptor builds when it lands — what `ui_unit::feed_units`
+/// pushes (its `"player"` leg) and fires `PLAYER_ENTERING_WORLD` off. It is the roster seat plus
+/// the fields only the descriptor can say: the unit EXISTS, at the roster's level, with health
+/// and a live object. [`super::seat_from_roster`] deliberately leaves those at nil/0 (decision
+/// 2263: the reference's `UnitExists("player")` is nil and `UnitLevel("player")` is 0 before the
+/// object exists), so the seat can no longer stand in for the descriptor the way it did from 1230
+/// until then — a fixture that never pushes this stays in the pre-object window for good, which
+/// is a state the real client is never in when a player opens their bags.
+fn descriptor_snapshot(seat: &benilla_ui::script::UnitState) -> benilla_ui::script::UnitState {
+    benilla_ui::script::UnitState {
+        exists: true,
+        has_object: true,
+        is_connected: true,
+        guid: 7,
+        level: 60,
+        health: 4_000,
+        max_health: 4_000,
+        power_type: 1, // a Warrior's rage
+        max_power: 1_000,
+        ..seat.clone()
+    }
+}
+
 /// A VM shaped like the director's session: our whole interface, their installed addons walked in
 /// dependency order the way `addons::load_third_party` walks them, and a real backpack.
 fn seat(root: &Path, seat: Seat) -> UiScript {
@@ -191,6 +180,10 @@ fn seat(root: &Path, seat: Seat) -> UiScript {
     s.set_realm_name("Harness");
     let player = super::seat_from_roster(&roster()).expect("a pending pick seats a player");
     if seat == Seat::BeforeAddons {
+        // The real entry load seeds the player RECORD beside the seat (`lifecycle.rs`, decisions
+        // 2261/2263); this one push does both, by `set_unit`'s keep-in-step rule — a `"player"`
+        // push that carries a name seeds the record — so `UnitName("player")` is "Harness" at
+        // addon file scope, which is what sends Bagnon down its LIVE path.
         s.set_unit("player", Some(player.clone()));
     }
     let failures = super::load_default_ui(&s);
@@ -239,12 +232,14 @@ fn seat(root: &Path, seat: Seat) -> UiScript {
     for event in ["VARIABLES_LOADED", "PLAYER_LOGIN"] {
         s.fire_event(event, Vec::new());
     }
-    // The self descriptor's arrival: `ui_unit::feed_units` pushes the player and fires
-    // PLAYER_ENTERING_WORLD off it. In the `AfterAddons` arm this is the FIRST time the VM has
-    // ever had a `"player"` — which is the state this file exists to reproduce.
-    if seat == Seat::AfterAddons {
-        s.set_unit("player", Some(player));
-    }
+    // The self descriptor's arrival: `ui_unit::feed_units` pushes the snapshot the descriptor
+    // builds and fires PLAYER_ENTERING_WORLD off it — in BOTH arms, because that is the world
+    // every real Bagnon open happens in. It matters: the reference's `GetKeyRingSize`
+    // (`ContainerFrame.lua:773-786`) reads `UnitLevel("player")`, and a fixture left in the
+    // pre-object window (level 0, the roster seat's answer since 2263) sizes the keyring at 4
+    // where the level-60 session sizes it at 12. In the `AfterAddons` arm this is the FIRST time
+    // the VM has ever had a `"player"` — which is the state this file exists to reproduce.
+    s.set_unit("player", Some(descriptor_snapshot(&player)));
     s.fire_event("PLAYER_ENTERING_WORLD", Vec::new());
     for _ in 0..10 {
         s.tick(0.1);
@@ -366,6 +361,7 @@ fn click(s: &mut UiScript, name: &str, button: &str) {
 /// director was on.
 #[test]
 fn bagnon_draws_a_slot_for_every_bag_slot() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = seat(&root, Seat::BeforeAddons);
 
@@ -381,17 +377,24 @@ fn bagnon_draws_a_slot_for_every_bag_slot() {
             .unwrap(),
         "the window must be on screen"
     );
+    // 28 = the backpack's 16 + the keyring's 12. Bagnon's default bag set carries the keyring
+    // (`Bagnon.lua:25`, `{-2, 0, 1, 2, 3, 4}`), and its size is the reference's own
+    // `GetKeyRingSize` ladder off `UnitLevel("player")` (`ContainerFrame.lua:773-786`: 4, 8 at
+    // 40, 12 at 50, 16 only above 60) — 12 for the fixture's level-60 Warrior. The four bag slots
+    // hold nothing, so they add nothing.
     assert_eq!(
         s.eval::<i64>("return Bagnon.size").unwrap(),
-        16,
-        "Bagnon must size itself off the LIVE backpack (GetContainerNumSlots(0) == 16), not off \
-         Bagnon_Forever's empty offline cache — nil UnitName('player') is what sent it there"
+        28,
+        "Bagnon must size itself off the LIVE bags (GetContainerNumSlots(0) == 16 plus \
+         GetKeyRingSize() == 12 at level 60), not off Bagnon_Forever's empty offline cache — nil \
+         UnitName('player') is what sent it there"
     );
     assert_eq!(
         bagnon_slot_quads(&mut s),
-        16,
-        "sixteen bag slots must actually be DRAWN — the director saw a title and a gold line and \
-         nothing else, while every column of the addon survey called this addon fine"
+        28,
+        "every live slot must actually be DRAWN (16 backpack + 12 keyring) — the director saw a \
+         title and a gold line and nothing else, while every column of the addon survey called \
+         this addon fine"
     );
     assert!(
         s.errors().is_empty(),
@@ -408,6 +411,7 @@ fn bagnon_draws_a_slot_for_every_bag_slot() {
 /// drawing slots, the headline above has stopped testing the thing it was written for.
 #[test]
 fn without_a_player_at_addon_load_bagnon_draws_an_empty_window() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = seat(&root, Seat::AfterAddons);
     s.run("ToggleBackpack()").expect("ToggleBackpack");
@@ -447,6 +451,7 @@ fn without_a_player_at_addon_load_bagnon_draws_an_empty_window() {
 /// on screen at all — and it is what the identity fix alone would have produced.
 #[test]
 fn the_item_button_helpers_paint_a_slots_icon_and_count() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().expect("VM");
     s.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
@@ -733,6 +738,7 @@ fn dragging_a_bagnon_slot_picks_the_item_up() {
 /// ```
 #[test]
 fn the_backpack_button_still_hovers_with_bagnon_holding_its_script() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = open_bagnon(&root);
 
@@ -761,10 +767,11 @@ fn the_backpack_button_still_hovers_with_bagnon_holding_its_script() {
 }
 
 /// **Bug 3.** `Bagnon_Forever/database/ui.lua:61` sizes its character dropdown from
-/// `button:GetTextWidth()` on a **CheckButton** — a real 1.12 Button method (wow-re
-/// `widget-api-batch-benilla.md` Q8 lists it present, and `GetStringWidth` absent, on Button).
+/// `button:GetTextWidth()` on a **CheckButton** — a real 1.12 Button method (`0x782290`, and
+/// `GetStringWidth` is absent on Button).
 #[test]
 fn a_button_reports_its_own_label_width() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = open_bagnon(&root);
 
@@ -827,6 +834,7 @@ fn a_button_reports_its_own_label_width() {
 /// we had never declared, so every one of the 36 buttons warned and the child came out bare.
 #[test]
 fn the_reference_cooldown_template_resolves() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let s = open_bagnon(&root);
     let occupied = bagnon_button_for_slot(&s, 0, 1);
@@ -855,12 +863,15 @@ fn the_reference_cooldown_template_resolves() {
 /// does.
 #[test]
 fn the_whole_bagnon_window_survives_being_used() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = open_bagnon(&root);
 
     // 1 · Every slot, hovered and left again — the OnEnter/OnUpdate/OnLeave loop on both an
-    //     occupied and an empty slot.
-    for i in 1..=16 {
+    //     occupied and an empty slot, across every bag the window lays out (the keyring's slots
+    //     come first in Bagnon's default order, the backpack's after them).
+    let size = s.eval::<i64>("return Bagnon.size").expect("Bagnon.size");
+    for i in 1..=size {
         let name = format!("BagnonItem{i}");
         if s.eval::<bool>(&format!("return getglobal(\"{name}\") ~= nil"))
             .unwrap_or(false)
@@ -886,7 +897,8 @@ fn the_whole_bagnon_window_survives_being_used() {
     // 3 · Bagnon's OWN bag buttons (the row it just revealed — `BagnonBags0..4` plus the
     //     keyring's `BagnonBags-2`, from `Bagnon.xml`'s `$parent<id>` naming): hover, click and
     //     drag each. `BagnonBag_OnClick` is `PutItemInBackpack`/`PutItemInBag`, `BagnonBag_OnDrag`
-    //     is `PickupBagFromSlot` — three engine verbs, none of which existed here.
+    //     is `PickupBagFromSlot` — three engine verbs that did not exist here when this test was
+    //     written and are `script/cursor/bag_verbs.rs` now.
     for id in ["0", "1", "2", "3", "4", "-2"] {
         let name = format!("BagnonBags{id}");
         if !s
@@ -906,8 +918,9 @@ fn the_whole_bagnon_window_survives_being_used() {
         s.mouse_button(x + 12.0, y + 12.0, "LeftButton", false);
     }
 
-    // 4 · The money frame's three coin buttons — `OpenCoinPickupFrame`, guarded in our own
-    //     MoneyFrame.xml and *not* guarded in Bagnon's copy of the same handler.
+    // 4 · The money frame's three coin buttons — `OpenCoinPickupFrame`, which Bagnon's own
+    //     `BagnonFrameMoney_OnClick` (`Frame.lua:537-543`) calls unguarded, exactly as the
+    //     reference's `MoneyFrame.xml` coin buttons do.
     for coin in ["Gold", "Silver", "Copper"] {
         let name = format!("BagnonMoneyFrame{coin}Button");
         if s.eval::<bool>(&format!(
@@ -949,32 +962,16 @@ fn the_whole_bagnon_window_survives_being_used() {
     //
     // To retire an entry: implement it and delete the line. To add one: you had better be able to
     // say why, in the same sentence.
-    const KNOWN_GAPS: &[(&str, &str)] = &[
-        // The bag-BUTTON cursor trio (`Bag.lua:199-215` — Bagnon's own bag row, click and drag).
-        // Three 1.12 engine bindings benilla does not have: `PutItemInBackpack 0x4c8f70`,
-        // `PutItemInBag 0x4c8f00`, `PickupBagFromSlot 0x4c8fa0` (wow-re `system/ui/ledger.tsv`
-        // l.1962-1964 has the registrations verified; the DECOMPILATION on disk is partial —
-        // Ghidra removed unreachable blocks from two of the three — so what each one actually
-        // DOES is not read).
-        //
-        // **Deliberately not guessed.** The open question is whether `PutItemInBag(inv)`
-        // auto-stores the held item into that bag's CONTENTS or places it onto the equipment slot,
-        // and those are different opcodes. Writing a cursor transition on the wrong one moves a
-        // player's items to the wrong place, which is the most expensive kind of wrong here
-        // (the contract §4), so an RE cross-check is dispatched into wow-5875-re and these land on
-        // its verdict, not before.
-        ("PutItemInBackpack", "Bagnon_Core\\core\\Bag.lua:202"),
-        ("PutItemInBag", "Bagnon_Core\\core\\Bag.lua:204"),
-        ("PickupBagFromSlot", "Bagnon_Core\\core\\Bag.lua:214"),
-        // Money on the cursor. `Frame.lua:537-543` — Bagnon's money frame calls this UNGUARDED
-        // where benilla's own `MoneyFrame.xml:411` guards its copy of the same reference handler.
-        // It is the head of a whole feature, not a missing line: the reference's
-        // `CoinPickupFrame.lua`/`.xml` need `GetCursorMoney`, `PickupPlayerMoney`, a MONEY cursor
-        // payload (wow-re `cursor-dragdrop-payload.md` row 2 — benilla's cursor has Item/Spell/
-        // Action only) and a keyboard-focused frame with `OnChar`/`OnKeyDown`, which this engine
-        // deliberately does not have (see `EnableKeyboard` in the same landing's report).
-        ("OpenCoinPickupFrame", "Bagnon_Core\\core\\Frame.lua:543"),
-    ];
+    //
+    // **Empty, and that is the list's best state, not a reason to delete it.** Four rows sat here
+    // when it was written, and each retired the way the rule above says: the bag-BUTTON cursor
+    // trio (`PutItemInBackpack`, `PutItemInBag`, `PickupBagFromSlot` — `Bag.lua:199-215`) once
+    // `script/cursor/bag_verbs.rs` bound all three; and money on
+    // the cursor (`OpenCoinPickupFrame`, `Frame.lua:537-543`) when the money kit went stock and
+    // the reference's own `CoinPickupFrame.xml` joined the manifest with the money cursor under
+    // it (decision 1962). With nothing on the list, "unexplained" is every error, which is the
+    // assertion this test was always reaching for.
+    const KNOWN_GAPS: &[(&str, &str)] = &[];
 
     let raised = s.errors();
     let unexplained: Vec<&String> = raised
@@ -1057,6 +1054,7 @@ fn text_quad(s: &mut UiScript, owner: &str) -> QuadContent {
 /// asserted as such — a future "fix" that adds one would be a divergence, not an improvement.
 #[test]
 fn a_stack_count_wears_the_font_object_its_font_attr_names() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = open_bagnon_stacked(&root);
 
@@ -1107,10 +1105,11 @@ fn a_stack_count_wears_the_font_object_its_font_attr_names() {
 /// `<Gradient>`, and dropped it in silence, so the white art rendered untinted.
 ///
 /// `<Gradient>` survives beside a `file=` where `<Color>` does not, and that asymmetry is the
-/// point: they land in different fields (vertex colours `+0xb8` vs the texture `+0xcc` —
-/// wow-re `texture-color-composition.md` §1-2).
+/// point: they land in different fields (vertex colours `+0xb8`, written by `0x77f910`, vs the
+/// texture `+0xcc`, written by `0x770360`).
 #[test]
 fn a_texture_gradient_tints_the_art_it_sits_on() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = open_bagnon_stacked(&root);
     s.run("BagnonDBUI_ShowCharacterList(Bagnon)")
@@ -1161,6 +1160,7 @@ fn a_texture_gradient_tints_the_art_it_sits_on() {
 /// The assertion is the FIRST open, which is the half that was broken.
 #[test]
 fn a_money_frame_is_the_right_width_on_the_first_open() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = seat(&root, Seat::BeforeAddons);
 
@@ -1225,6 +1225,7 @@ fn resolved_font(s: &UiScript, lua_expr: &str) -> (String, String) {
 /// zero against nine controls each returning one); it is a later-client idiom.
 #[test]
 fn a_button_state_font_takes_the_font_attribute_not_just_inherits() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = open_bagnon_stacked(&root);
     s.run("BagnonDBUI_ShowCharacterList(Bagnon)")
@@ -1258,6 +1259,7 @@ fn a_button_state_font_takes_the_font_attribute_not_just_inherits() {
 /// reference does not.
 #[test]
 fn a_fontheight_with_no_font_attr_beside_it_is_never_read() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let s = open_bagnon_stacked(&root);
     assert_eq!(
@@ -1298,6 +1300,7 @@ impl benilla_ui::script::TextMeasure for BlockFont {
 /// name plus the addon's own 40px of checkbox and padding.
 #[test]
 fn the_character_dropdown_is_as_wide_as_the_names_in_it() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = open_bagnon(&root);
     s.set_text_measurer(Box::new(BlockFont));
@@ -1352,18 +1355,26 @@ fn the_character_dropdown_is_as_wide_as_the_names_in_it() {
 /// (`ui_items::feed::tests::an_absent_self_player_is_no_source_never_an_empty_bag_burst`).
 #[test]
 fn bagnon_forevers_records_survive_the_logout_boundary() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = seat(&root, Seat::BeforeAddons);
 
     // The first-login scan (PLAYER_LOGIN, inside `seat`) recorded the live backpack: 16 slots,
     // the pouch in slot 1, in Bagnon_Forever's own short-link shape.
+    //
+    // **`16,1,` — the 1 is the reference's, not a stray.** The recorder's count is
+    // `GetInventoryItemCount("player", ContainerIDToInventoryID(0))`, and `ContainerIDToInventoryID`
+    // has no backpack arm (`0x4f94e0`: `id - 1 < 4` → `+20`), so bag 0 asks inventory slot 19 —
+    // the tabard slot. `GetInventoryItemCount 0x4c8680` pushes **1** for an empty slot
+    // (`0x4c8797`), and 1 for a
+    // worn tabard's stack count too, so the real client writes this row as `16,1,` either way.
     let record = "local r = BagnonForeverData[GetRealmName()][UnitName('player')] \
                   return tostring(r[0] and r[0].s), tostring(r[0] and r[0][1])";
     let (size, item) = s
         .eval::<(String, String)>(record)
         .expect("the record reads");
     assert_eq!(
-        size, "16,0,",
+        size, "16,1,",
         "the login scan records the backpack's size row"
     );
     assert_eq!(
@@ -1415,6 +1426,7 @@ fn bagnon_forevers_records_survive_the_logout_boundary() {
         None,
         Default::default(),
         Vec::new(),
+        Vec::new(),
     );
     s.fire_event("PLAYER_LEAVING_WORLD", Vec::new());
     s.fire_event("PLAYER_LOGOUT", Vec::new());
@@ -1422,7 +1434,7 @@ fn bagnon_forevers_records_survive_the_logout_boundary() {
         .eval::<(String, String)>(record)
         .expect("the record reads");
     assert_eq!(
-        size, "16,0,",
+        size, "16,1,",
         "the logout boundary must not erase the size row"
     );
     assert_eq!(item, "4496", "the logout boundary must not erase the slot");
@@ -1441,7 +1453,10 @@ fn bagnon_forevers_records_survive_the_logout_boundary() {
 /// here with a real mouse click, an equipped bag in slot 2, and Bagnon fully hooked.
 #[test]
 fn a_bag_slot_click_toggles_bagnon_not_the_native_window() {
-    let root = corpus_or_skip!();
+    // The install too: "is a native bag window open" is asked of the reference's own `IsBagOpen`
+    // scan (`ContainerFrame.lua:177`, off the chain) — the windows are RECYCLED (1751), so there
+    // is no frame to name, and `bag_tests.rs` asks the same way.
+    let root = corpus_and_install_or_skip!();
     let mut s = open_bagnon(&root);
 
     // An equipped bag behind CharacterBag1Slot (bagId 2): the inventory surface (the bag ITEM in
@@ -1489,8 +1504,7 @@ fn a_bag_slot_click_toggles_bagnon_not_the_native_window() {
         "the slot click must reach Bagnon's ToggleBag override and close its window"
     );
     assert!(
-        !s.eval::<bool>("return BenillaBagFrame2:IsVisible() or false")
-            .unwrap(),
+        !super::test_ui::bag_open(&s, 2),
         "the native bag window must NOT open — the click belongs to the addon's override"
     );
 
@@ -1508,8 +1522,7 @@ fn a_bag_slot_click_toggles_bagnon_not_the_native_window() {
         "the second click re-opens Bagnon through the same override"
     );
     assert!(
-        !s.eval::<bool>("return BenillaBagFrame2:IsVisible() or false")
-            .unwrap(),
+        !super::test_ui::bag_open(&s, 2),
         "the native window stays shut on the re-open too"
     );
     assert!(
@@ -1517,29 +1530,38 @@ fn a_bag_slot_click_toggles_bagnon_not_the_native_window() {
             .unwrap(),
         "the slot button stays unlit with an addon holding the bags (the ref scan is native-only)"
     );
+    // Nothing is filtered out any more: the bag-button cursor trio the round-trip reaches
+    // (`PutItemInBag` on the click) is built (`script/cursor/bag_verbs.rs`), so a raise on it is
+    // a real one.
     let raised = s.errors();
-    let unexplained: Vec<&String> = raised
-        .iter()
-        .filter(|e| !e.contains("PutItemIn") && !e.contains("PickupBagFromSlot"))
-        .collect();
     assert!(
-        unexplained.is_empty(),
-        "the click round-trip raised: {unexplained:#?}"
+        raised.is_empty(),
+        "the click round-trip raised: {raised:#?}"
     );
 }
 
-/// **Bug 7 — the director's unlit backpack button.** Bagnon lights `MainMenuBarBackpackButton`
-/// from its window's OnShow/OnHide (`Bagnon.lua:33/39` — `SetChecked(1/0)`), and OnShow dispatch
-/// is synchronous (wow-re `onshow-onhide-dispatch-order.md`), so whoever writes checked AFTER the
-/// toggle wins. Two of our seats overwrote it: the button's old click tail re-derived checked
-/// from the NATIVE backpack window (the ref's own scan — which leaves the button unlit on the
-/// real client's click path too, a ref wart our stated divergence closes), and the `B` binding
-/// ran the BUTTON handler instead of the ref's bare `ToggleBackpack()` body, dragging that tail
-/// onto the one path the real client lights. Now: a real click on the button ends lit while
-/// Bagnon's window is open and unlit when it closes, and the bare-global path (the binding's
-/// body) does the same.
+/// **Bug 7 — the director's unlit backpack button — and where it stands since the bag bar went
+/// stock.** Bagnon lights `MainMenuBarBackpackButton` from its window's OnShow/OnHide
+/// (`Bagnon.lua:33/39` — `SetChecked(1/0)`), and OnShow dispatch is synchronous
+/// (`0x775750` → `0x76ae10`), so whoever writes checked AFTER the toggle wins. On the
+/// reference's own click path the stock `BackpackButton_OnClick` tail
+/// (`MainMenuBarBagButtons.lua:55-69`) runs last: it re-derives checked by scanning the NATIVE
+/// container frames, finds none for bag 0 while an addon holds the bags, and writes 0 — so the
+/// real client leaves the button unlit after a click with Bagnon, a wart of its own. Our own
+/// `BagFrame.xml` once closed that wart on the director's call (Bug 7: an auto-toggle undo in
+/// place of the scan, a stated divergence); decision 1783 sourced the stock file unedited and the
+/// divergence went with it, unrecorded — and this suite, skipping at every land from 08-30
+/// (2329), never said so.
+///
+/// What this pins is the client as it is, which is the reference: the bare `ToggleBackpack()`
+/// path (the `B` binding's body) ends lit, because nothing runs after OnShow there; a real click
+/// ends **unlit** on open as well as on close, because the stock tail is the last word. Decision
+/// 2332 retired Bug 7's divergence on record (1751 §2 reserves shims for engine differences, and
+/// this is a look); if the director ever wants it lit, the second assertion below flips back and
+/// a shim in `ContainerFrameAdapters.xml` carries the why.
 #[test]
-fn the_backpack_button_lights_while_bagnon_holds_the_bags() {
+fn the_backpack_button_lit_state_with_bagnon_holding_the_bags() {
+    benilla_formats::wow_data_or_skip!();
     let root = corpus_or_skip!();
     let mut s = open_bagnon(&root);
 
@@ -1568,7 +1590,9 @@ fn the_backpack_button_lights_while_bagnon_holds_the_bags() {
         "closed ⇒ unlit (Bagnon's OnHide write is the last word)"
     );
 
-    // And the second click: open again, lit again — the director's report, closed.
+    // And the second click: open again — and UNLIT, the stock tail's native scan overwriting
+    // Bagnon's OnShow write, as the reference does. Bug 7's "lit" is the assertion this replaces;
+    // it comes back with the shim if the director asks for it (the doc above).
     s.mouse_button(x, y, "LeftButton", true);
     s.mouse_button(x, y, "LeftButton", false);
     assert!(
@@ -1577,8 +1601,9 @@ fn the_backpack_button_lights_while_bagnon_holds_the_bags() {
         "the second click re-opens Bagnon"
     );
     assert!(
-        s.eval::<bool>("return MainMenuBarBackpackButton:GetChecked() and true or false")
+        !s.eval::<bool>("return MainMenuBarBackpackButton:GetChecked() and true or false")
             .unwrap(),
-        "open ⇒ lit (Bagnon's OnShow write is the last word)"
+        "open by click ⇒ unlit: the stock BackpackButton_OnClick tail's native scan is the last \
+         word, as on the reference (Bug 7's divergence retired with the stock bag bar, 1783)"
     );
 }
diff --git a/crates/benilla-app/src/ui_script/basic_controls_tests.rs b/crates/benilla-app/src/ui_script/basic_controls_tests.rs
index a427abdc..dcfccfd8 100644
--- a/crates/benilla-app/src/ui_script/basic_controls_tests.rs
+++ b/crates/benilla-app/src/ui_script/basic_controls_tests.rs
@@ -23,6 +23,7 @@ fn basic_controls() -> UiScript {
 /// reason the frame has to exist rather than the function being a stub that prints somewhere.
 #[test]
 fn message_shows_the_script_errors_dialog_carrying_its_text() {
+    benilla_formats::wow_data_or_skip!();
     let s = basic_controls();
     assert!(
         !s.eval::<bool>("return ScriptErrors:IsVisible()").unwrap(),
@@ -57,6 +58,7 @@ fn message_shows_the_script_errors_dialog_carrying_its_text() {
 /// is replaceable — which is the entire point for the two corpus addons that replace it.
 #[test]
 fn error_message_returns_its_argument_and_can_be_replaced() {
+    benilla_formats::wow_data_or_skip!();
     let s = basic_controls();
     assert_eq!(
         s.eval::<String>(r#"return _ERRORMESSAGE("boom")"#).unwrap(),
@@ -82,6 +84,7 @@ fn error_message_returns_its_argument_and_can_be_replaced() {
 /// test used to be).
 #[test]
 fn error_message_is_the_installed_handler_and_the_host_channel_stays_sighted() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = basic_controls();
     assert!(
         s.eval::<bool>("return geterrorhandler() == _ERRORMESSAGE")
@@ -120,6 +123,7 @@ fn error_message_is_the_installed_handler_and_the_host_channel_stays_sighted() {
 /// `TEXT` is the identity function, and 26 corpus addons call it because shipped FrameXML does.
 #[test]
 fn text_is_the_identity_function_the_corpus_expects() {
+    benilla_formats::wow_data_or_skip!();
     let s = basic_controls();
     assert_eq!(
         s.eval::<String>(r#"return TEXT("Level")"#).unwrap(),
@@ -133,6 +137,7 @@ fn text_is_the_identity_function_the_corpus_expects() {
 /// name — `MyDialogButton`, never `DialogBoxFrameButton`.
 #[test]
 fn a_dialog_box_from_the_template_names_and_closes_the_callers_frame() {
+    benilla_formats::wow_data_or_skip!();
     let s = basic_controls();
     s.run(
         r#"MyDialog = CreateFrame("Frame", "MyDialog", UIParent, "DialogBoxFrame")
diff --git a/crates/benilla-app/src/ui_script/binder_tests.rs b/crates/benilla-app/src/ui_script/binder_tests.rs
index 26cbaa4a..04391ae7 100644
--- a/crates/benilla-app/src/ui_script/binder_tests.rs
+++ b/crates/benilla-app/src/ui_script/binder_tests.rs
@@ -30,6 +30,7 @@ fn setup() -> UiScript {
 /// this wiring the click produced no dialog and no packet at all (B249).
 #[test]
 fn the_confirm_shows_the_area_and_accept_queues_the_bind() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event(
         "CONFIRM_BINDER",
@@ -58,6 +59,7 @@ fn the_confirm_shows_the_area_and_accept_queues_the_bind() {
 /// no decline opcode), so the only observable is that no confirm was queued.
 #[test]
 fn declining_sends_nothing() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("CONFIRM_BINDER", vec![ScriptValue::Str("Goldshire".into())]);
     s.run("StaticPopup_OnClick(StaticPopup1, 2)").unwrap();
@@ -77,6 +79,7 @@ fn declining_sends_nothing() {
 /// nothing; the frame it goes false, the dialog hides itself — with no packet either way.
 #[test]
 fn leaving_the_innkeepers_range_hides_the_confirm() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("CONFIRM_BINDER", vec![ScriptValue::Str("Kharanos".into())]);
     s.run("StaticPopup_OnUpdate(StaticPopup1, 0.1)").unwrap();
diff --git a/crates/benilla-app/src/ui_script/bottom_hud_tests.rs b/crates/benilla-app/src/ui_script/bottom_hud_tests.rs
index 07dfc4db..31100fc5 100644
--- a/crates/benilla-app/src/ui_script/bottom_hud_tests.rs
+++ b/crates/benilla-app/src/ui_script/bottom_hud_tests.rs
@@ -309,6 +309,7 @@ const RAISABLE_BARS: &[&str] = &[
 /// eventually wired), and re-runs the pass between combinations exactly as a live bar change does.
 #[test]
 fn no_bottom_band_frame_overlaps_a_raised_bar() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1600.0, 900.0);
     // The in-game UI materializes on world entry (1051), so a player always exists by the time the
@@ -457,6 +458,7 @@ fn overlaps(a: (f32, f32, f32, f32), b: (f32, f32, f32, f32)) -> bool {
 /// is the test that says so out loud rather than the change slipping through green.
 #[test]
 fn the_item_push_card_shares_the_band_with_a_raised_bar_exactly_as_the_reference_does() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1600.0, 900.0);
     // The in-game UI materializes on world entry (1051), so a player always exists by the time the
diff --git a/crates/benilla-app/src/ui_script/buff_tests.rs b/crates/benilla-app/src/ui_script/buff_tests.rs
index e424ec60..6edd5c27 100644
--- a/crates/benilla-app/src/ui_script/buff_tests.rs
+++ b/crates/benilla-app/src/ui_script/buff_tests.rs
@@ -723,8 +723,8 @@ fn the_temporary_enchant_row_shows_a_weapon_enchant_and_moves_the_top_row_aside(
     // The direct probe, and its exact shape is the point. `BuffButtonTempEnchant` inherits
     // `BuffButtonTemplate` and blanks its three aura handlers with `<OnLoad>`↵`</OnLoad>` — a
     // WHITESPACE body, which 1.12 compiles into a valid empty function rather than storing nil
-    // (`SetScript 0x7025c0` tests `text[0]`, and nothing trims — wow-5875-re
-    // `xml-script-empty-element.md`). So each handler is still a FUNCTION here, and it is the
+    // (`SetScript 0x7025c0` tests `text[0]`, and nothing trims). So each handler is still a
+    // FUNCTION here, and it is the
     // reference's own no-op rather than `BuffButton_OnLoad`.
     //
     // Asserting `== nil` instead would be asserting a bug: an addon reading
@@ -1009,11 +1009,11 @@ fn a_settled_buff_button_rewrites_alpha_and_duration_as_the_reference_does() {
 /// The duration line against the **real shipped strings**, end to end — the leg the engine's own
 /// synthetic-template tests cannot reach.
 ///
-/// The engine formats through `tooltip::duration_text` (`0x52fa50`'s ladder, wow-re
-/// §3-BUFF-TIME-FORMAT) over whatever `GlobalStrings.lua` the player's install carries; this runs
+/// The engine formats through `tooltip::duration_text` (`0x52fa50`'s ladder) over whatever
+/// `GlobalStrings.lua` the player's install carries; this runs
 /// that file into a real VM exactly as the boot's `load_global_strings` does, then asserts the
 /// wording that comes back. Every expectation below is a reading the PREVIOUS two-arm formatter got
-/// wrong, so this is the carve's whole delta in one place. Skips without client data.
+/// wrong, so this is the whole delta in one place. Skips without client data.
 #[test]
 fn the_duration_line_reads_the_real_global_strings() {
     let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-app/src/ui_script/cast_tests.rs b/crates/benilla-app/src/ui_script/cast_tests.rs
index b2c6c711..6a531cb3 100644
--- a/crates/benilla-app/src/ui_script/cast_tests.rs
+++ b/crates/benilla-app/src/ui_script/cast_tests.rs
@@ -50,6 +50,7 @@ fn tex_quad<'a>(quads: &'a [ExtractedQuad], leaf: &str) -> Option<&'a ExtractedQ
 
 #[test]
 fn cast_fills_then_completes_green_and_fades() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     assert!(
         !s.eval::<bool>("return CastingBarFrame:IsShown()").unwrap(),
@@ -99,6 +100,7 @@ fn cast_fills_then_completes_green_and_fades() {
 
 #[test]
 fn a_hit_pushes_the_bar_back_it_does_not_cancel() {
+    benilla_formats::wow_data_or_skip!();
     // Pushback (`SMSG_SPELL_DELAYED` → `SPELLCAST_DELAYED`): a hit while casting must slide the
     // bar's window out (the spark jumps back and it keeps running), never hide or fail it —
     // decision 0256's open item, the "disappears on a hit" report.
@@ -145,6 +147,7 @@ fn a_hit_pushes_the_bar_back_it_does_not_cancel() {
 
 #[test]
 fn failed_cast_turns_red_holds_then_fades() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event(
         "SPELLCAST_START",
@@ -179,6 +182,7 @@ fn failed_cast_turns_red_holds_then_fades() {
 
 #[test]
 fn channel_counts_down_not_up() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     // SPELLCAST_CHANNEL_START(ms, name) — args reversed vs START, per the reference contract.
     // The name is whatever `ui_cast::channel_start_args` composed; for all but nine of the 323
@@ -261,6 +265,7 @@ fn channel_counts_down_not_up() {
 /// `SPELLCAST_CHANNEL_STOP` by hand, which is the *interrupt* timing, not this one.
 #[test]
 fn a_finished_channel_fades_on_its_own_clock_and_the_late_stop_is_inert() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event(
         "SPELLCAST_CHANNEL_START",
@@ -316,6 +321,7 @@ const FILL: &str = "UI-StatusBar";
 /// smear over the bar from the first frame — invisible to every state assertion above.
 #[test]
 fn the_flash_stays_hidden_for_the_whole_cast() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event(
         "SPELLCAST_START",
@@ -343,6 +349,7 @@ fn the_flash_stays_hidden_for_the_whole_cast() {
 /// finished.
 #[test]
 fn the_flash_blooms_from_zero_only_on_completion() {
+    benilla_formats::wow_data_or_skip!();
     const REF_TICK: f32 = 1.0 / 30.0; // one reference tick of wall clock
     let mut s = harness();
     s.fire_event(
@@ -373,6 +380,7 @@ fn the_flash_blooms_from_zero_only_on_completion() {
 /// A failed cast never flashes — the reference only arms the ramp on STOP/CHANNEL_STOP.
 #[test]
 fn a_failed_cast_never_flashes() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event(
         "SPELLCAST_START",
@@ -395,6 +403,7 @@ fn a_failed_cast_never_flashes() {
 /// border art's own layer, where declaration order put the fill on top.)
 #[test]
 fn the_fill_draws_beneath_the_border_art() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event(
         "SPELLCAST_START",
@@ -411,11 +420,12 @@ fn the_fill_draws_beneath_the_border_art() {
     );
 }
 
-/// A StatusBar fill CROPs its texture — it never squeezes it (wow-re `nameplate-vkey.md`). At a
+/// A StatusBar fill CROPs its texture — it never squeezes it (`0x770410`). At a
 /// fraction f the quad is f·width wide AND samples u ∈ [0, f], so `UI-StatusBar`'s left-to-right
 /// ramp keeps its true gradient at every fill level.
 #[test]
 fn the_fill_crops_its_texture_rather_than_stretching_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event(
         "SPELLCAST_START",
@@ -460,6 +470,7 @@ fn bottom(s: &UiScript, name: &str) -> f64 {
 /// (base + bottomEither/bottomLeft + pet, and chat's bottomLeft-and-pet +23 extra).
 #[test]
 fn managed_positions_track_the_bottom_bar_stack() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -553,6 +564,7 @@ fn managed_positions_track_the_bottom_bar_stack() {
 /// "exists" and still break every addon that drives the bar through it.
 #[test]
 fn the_casting_bar_publishes_its_status_bar_alias() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     assert!(
         s.eval::<bool>("return CastingBarFrameStatusBar ~= nil")
diff --git a/crates/benilla-app/src/ui_script/chat_tests.rs b/crates/benilla-app/src/ui_script/chat_tests.rs
index 8166e027..c0d35044 100644
--- a/crates/benilla-app/src/ui_script/chat_tests.rs
+++ b/crates/benilla-app/src/ui_script/chat_tests.rs
@@ -67,6 +67,7 @@ fn close(a: f32, b: f32) -> bool {
 
 #[test]
 fn injected_lines_render_in_the_pinned_colors() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     // The app's feed passes 0..1 floats from the pinned type→color table; the seam quantizes them.
     // SAY white (FFFFFF), SYSTEM yellow (FFFF00 — the GM-feedback color), LOOT green (00AA00).
@@ -104,6 +105,7 @@ fn injected_lines_render_in_the_pinned_colors() {
 
 #[test]
 fn newest_line_sits_at_the_bottom() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     s.add_chat_message("ChatFrame1", "older", 1.0, 1.0, 1.0);
     s.add_chat_message("ChatFrame1", "newer", 1.0, 1.0, 1.0);
@@ -124,11 +126,12 @@ fn newest_line_sits_at_the_bottom() {
 
 /// The whole fade round trip as it reaches a real chat window: a line ramps down, a scroll brings
 /// it back to full, the scrolled-up view then holds it there, and returning to the bottom lets it
-/// ramp again. The re-arm half is `msgframe-fade-rearm-law.md` — every scroll entry reaches
+/// ramp again. The re-arm half: every scroll entry reaches
 /// `0x788b80` or the relayout's `0x788af0`; before it, a faded-out chat could not be recovered by
 /// any input the client offers (director-reported, 2026-08-29).
 #[test]
 fn wheel_scroll_re_arms_the_fade_then_freezes_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     s.run("ChatFrame1:SetTimeVisible(0); ChatFrame1:SetFadeDuration(4)")
         .unwrap();
@@ -160,6 +163,7 @@ fn wheel_scroll_re_arms_the_fade_then_freezes_it() {
 
 #[test]
 fn input_editbox_enter_drains_the_typed_line() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     assert!(s.focus_editbox("ChatFrameEditBox"), "the edit box focuses");
     assert!(s.has_keyboard_focus(), "focus gates the world's keys");
@@ -184,6 +188,7 @@ fn input_editbox_enter_drains_the_typed_line() {
 
 #[test]
 fn input_escape_closes_without_submitting() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     assert!(s.focus_editbox("ChatFrameEditBox"));
     s.char_input("hello");
@@ -198,6 +203,7 @@ fn input_escape_closes_without_submitting() {
 /// leave LEFT/RIGHT consumed-but-dead here, and an unpushed history would leave Up/Down empty.
 #[test]
 fn chat_box_arrows_edit_and_history_recalls() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::{EditAction, EditUnit};
     let mut s = chat_frame();
     assert!(s.focus_editbox("ChatFrameEditBox"));
@@ -265,6 +271,7 @@ fn chat_box_arrows_edit_and_history_recalls() {
 /// untouched (a silent item dismissal would be a destroy — only the world-drop popup offers that).
 #[test]
 fn chat_click_dismisses_a_stuck_spell_but_not_an_item() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::{
         ContainerSlot, ContainerState, SpellBookState, SpellSlotView, SpellTabView,
     };
@@ -380,11 +387,12 @@ fn chat_click_dismisses_a_stuck_spell_but_not_an_item() {
 
 /// `ChatTypeInfo` carries the shipped default chat colors twice: once in
 /// `Interface\FrameXML\ChatFrame.xml` for addons to read, and once in
-/// [`crate::ui_chat::default_color`] for our own feed to render. Both are the same wow-re byte
-/// table (`chat-color-table.md`, the static registry at `.rdata 0x804710`) — so this is the gate
+/// [`crate::ui_chat::default_color`] for our own feed to render. Both are the same reference byte
+/// table (the static registry at `.rdata 0x804710`) — so this is the gate
 /// that makes the duplication safe: every kind we model must agree to the byte, and the table's shape (`sticky`/`id`) must be the reference's.
 #[test]
 fn chat_type_info_matches_the_host_color_table() {
+    benilla_formats::wow_data_or_skip!();
     use crate::ui_chat::{default_color, ChatEventKind as K};
 
     /// Each modeled kind and its `ChatTypeInfo` key — the reference's own spellings.
@@ -453,6 +461,7 @@ fn chat_type_info_matches_the_host_color_table() {
 /// extras. An addon reads `.sticky` and `.id` as often as it reads the color.
 #[test]
 fn chat_type_info_has_the_references_shape() {
+    benilla_formats::wow_data_or_skip!();
     let s = chat_frame();
 
     let count: i64 = s
@@ -518,6 +527,7 @@ fn chat_type_info_has_the_references_shape() {
 /// a matching table key fails here instead of shipping a name nothing can resolve.
 #[test]
 fn fired_event_names_are_all_chat_type_info_keys() {
+    benilla_formats::wow_data_or_skip!();
     use crate::ui_chat::{event_name, ChatEventKind as K};
 
     let s = chat_frame();
@@ -544,6 +554,7 @@ fn fired_event_names_are_all_chat_type_info_keys() {
 /// guard (`LazyPig.lua:1992`), so the constant without the frames is worse than neither.
 #[test]
 fn every_window_num_chat_windows_promises_is_a_real_frame() {
+    benilla_formats::wow_data_or_skip!();
     let s = chat_frame();
     assert_eq!(s.eval::<i64>("return NUM_CHAT_WINDOWS").unwrap(), 7);
     for i in 1..=7 {
@@ -561,6 +572,7 @@ fn every_window_num_chat_windows_promises_is_a_real_frame() {
 /// `getglobal(...):IsVisible()` that used to die at i=3.
 #[test]
 fn the_lazypig_window_walk_survives_all_seven_indices() {
+    benilla_formats::wow_data_or_skip!();
     let s = chat_frame();
     let visible: i64 = s
         .eval(
@@ -587,6 +599,7 @@ fn the_lazypig_window_walk_survives_all_seven_indices() {
 /// tabs (1575), so the Outfitter walk below is still safe.
 #[test]
 fn the_undocked_windows_are_hidden_and_carry_no_is_docked() {
+    benilla_formats::wow_data_or_skip!();
     let s = chat_frame();
     for i in 1..=2 {
         let docked: bool = s
@@ -626,6 +639,7 @@ fn the_undocked_windows_are_hidden_and_carry_no_is_docked() {
 /// frame will disagree about the same window. The drift guard between the Rust table and the XML.
 #[test]
 fn get_chat_window_info_shown_matches_the_shipped_frames() {
+    benilla_formats::wow_data_or_skip!();
     let s = chat_frame();
     for i in 1..=7 {
         let agrees: bool = s
@@ -650,6 +664,7 @@ fn get_chat_window_info_shown_matches_the_shipped_frames() {
 /// in ChatFrame3 and nowhere near the window the player is reading.
 #[test]
 fn a_line_added_to_chat_frame3_lands_in_chat_frame3_only() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     s.add_chat_message("ChatFrame1", "a real line", 1.0, 1.0, 1.0);
     s.run("ChatFrame3:AddMessage('Radar: debug', 1, 1, 0)")
@@ -683,6 +698,7 @@ fn a_line_added_to_chat_frame3_lands_in_chat_frame3_only() {
 /// reaches it, since both pass `DEFAULT_CHAT_FRAME`.
 #[test]
 fn fcf_select_dock_frame_selects_by_frame_and_leaves_an_undocked_one_alone() {
+    benilla_formats::wow_data_or_skip!();
     let s = chat_frame();
     s.run("FCF_SelectDockFrame(ChatFrame2)").unwrap();
     let (one, two): (bool, bool) = (
@@ -733,6 +749,7 @@ fn fcf_select_dock_frame_selects_by_frame_and_leaves_an_undocked_one_alone() {
 /// next tick overwrites 0.42 with 0 and this goes red.
 #[test]
 fn an_idle_dock_stops_rewriting_the_tab_alpha_every_frame() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     s.mouse_move(1500.0, 850.0); // far from the dock: no hover, so `reveal` stays 0
     for _ in 0..8 {
@@ -758,6 +775,7 @@ fn an_idle_dock_stops_rewriting_the_tab_alpha_every_frame() {
 /// cursor over the dock for longer than `CHAT_TAB_SHOW_DELAY` fades the selected tab to full.
 #[test]
 fn hovering_the_dock_still_reveals_the_tabs() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     s.mouse_move(1500.0, 850.0);
     for _ in 0..4 {
@@ -798,6 +816,7 @@ fn hovering_the_dock_still_reveals_the_tabs() {
 /// 0.5s toggle; and scrolling back while the flash is LIT still hides it and zeroes the timer.
 #[test]
 fn a_chat_view_at_the_bottom_stops_rewriting_the_flash() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     for t in ["L0", "L1", "L2"] {
         s.add_chat_message("ChatFrame1", t, 1.0, 1.0, 1.0);
@@ -866,6 +885,7 @@ fn a_chat_view_at_the_bottom_stops_rewriting_the_flash() {
 /// dead driver. So this drives the clock and nothing else.
 #[test]
 fn selecting_the_combat_log_keeps_the_dock_driver_running() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     let (x, y): (f32, f32) = s
         .eval(
@@ -912,6 +932,7 @@ fn selecting_the_combat_log_keeps_the_dock_driver_running() {
 /// `reveal` never decayed either, so the chat box and both tabs stayed lit after the cursor left.
 #[test]
 fn the_dock_still_fades_out_with_the_combat_log_selected() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     let (x, y): (f32, f32) = s
         .eval(
@@ -955,6 +976,7 @@ fn the_dock_still_fades_out_with_the_combat_log_selected() {
 /// button, which only happens if window 2 both HAS the button and runs `ChatFrame_OnUpdate`.
 #[test]
 fn the_combat_log_window_runs_its_own_bottom_button_blink() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     s.run("FCF_SelectDockFrame(ChatFrame2)").unwrap();
     for i in 0..40 {
@@ -1064,6 +1086,7 @@ fn the_chat_menu_builds_its_rows_on_the_references_kit() {
 /// the chat window shows the tabs and the buttons but no plate.
 #[test]
 fn a_glass_windows_plate_fades_in_on_every_hover() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_frame();
     s.mouse_move(1500.0, 850.0);
     for _ in 0..4 {
@@ -1109,6 +1132,7 @@ fn a_glass_windows_plate_fades_in_on_every_hover() {
 /// The same law under the WHOLE shipped manifest, driven the way the app drives it.
 #[test]
 fn a_glass_windows_plate_fades_in_on_every_hover_under_the_full_manifest() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1600.0, 900.0);
     super::test_ui::load_ui(&s, "Interface\\FrameXML\\GlobalStrings.lua");
@@ -1207,6 +1231,7 @@ fn a_glass_windows_plate_fades_in_on_every_hover_under_the_full_manifest() {
 /// then a repair of nothing.
 #[test]
 fn a_quick_exit_and_reentry_keeps_the_plates_hover_fade() {
+    benilla_formats::wow_data_or_skip!();
     fn drive(s: &mut UiScript) -> (f64, f64, f64) {
         let (x, y): (f32, f32) = s
             .eval(
@@ -1312,6 +1337,7 @@ fn a_quick_exit_and_reentry_keeps_the_plates_hover_fade() {
 /// broken — which is exactly how this shipped.
 #[test]
 fn the_stock_afk_and_dnd_commands_reach_the_wire() {
+    benilla_formats::wow_data_or_skip!();
     use crate::net::ChatKind;
     use crate::ui_chat::edit::SendType;
 
diff --git a/crates/benilla-app/src/ui_script/cinematic_tests.rs b/crates/benilla-app/src/ui_script/cinematic_tests.rs
index 239cb10d..96796428 100644
--- a/crates/benilla-app/src/ui_script/cinematic_tests.rs
+++ b/crates/benilla-app/src/ui_script/cinematic_tests.rs
@@ -2,9 +2,9 @@
 //!
 //! `CinematicFrame` is fullscreen, keyboard-enabled, and carries an `OnKeyDown` that answers
 //! ESCAPE. In the reference that is enough to swallow **every** key while it is up, because the
-//! key-down walk's gate is EXISTENCE, not handling (wow-re `ui/scratch/frame-key-script-delivery.md`
-//! §3, VERIFIED): a shown keyboard frame with the slot set consumes the key whatever its script
-//! does with it, and a 1.12 handler has no way to signal "not handled" (§3.1).
+//! key-down walk's gate is EXISTENCE, not handling (`0x76b7d0`): a shown keyboard frame with the
+//! slot set consumes the key whatever its script does with it, and a 1.12 handler has no way to
+//! signal "not handled" (`0x76ba25`).
 //!
 //! The reference's own Lua is the proof, and it is why these tests exist: that same `OnKeyDown` has
 //! to call `RunBinding("SCREENSHOT")` **by hand** to get one key back. It would not need to if
@@ -51,6 +51,7 @@ fn start_cinematic(s: &mut UiScript) {
 /// cannot walk during a cinematic.
 #[test]
 fn a_playing_cinematic_swallows_the_movement_keys() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui_with_the_cinematic_frame();
 
     // Before it starts, the frame is hidden and declines: the world keeps its keys.
@@ -84,6 +85,7 @@ fn a_playing_cinematic_swallows_the_movement_keys() {
 /// never that they fall through.
 #[test]
 fn escape_is_consumed_and_acted_on_rather_than_falling_through() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui_with_the_cinematic_frame();
     start_cinematic(&mut s);
 
@@ -132,6 +134,7 @@ fn the_host_has_a_reference_name_for_the_keys_it_now_delivers() {
 /// ever asked about keys the frame *swallows*.
 #[test]
 fn the_screenshot_key_is_handed_back_to_its_binding() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui_with_the_cinematic_frame();
     // The binding table the passthrough reads: `GetBindingKey("SCREENSHOT")` has to answer, or the
     // arm is skipped and the test proves nothing.
@@ -183,6 +186,7 @@ fn the_screenshot_key_is_handed_back_to_its_binding() {
 /// `IsVisible` the honest question again, so the check is an assertion instead of a log.
 #[test]
 fn a_cinematic_hides_the_hud_through_uiparent_and_spares_the_cinematic_frame() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui_with_the_cinematic_frame();
     let visible = |s: &UiScript, f: &str| {
         s.eval::<i64>(&format!("return {f}:IsVisible() and 1 or 0"))
@@ -235,6 +239,7 @@ fn a_cinematic_hides_the_hud_through_uiparent_and_spares_the_cinematic_frame() {
 /// silent about the hide.
 #[test]
 fn the_screenshot_confirmation_shows_during_a_cinematic() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.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
diff --git a/crates/benilla-app/src/ui_script/color_picker_tests.rs b/crates/benilla-app/src/ui_script/color_picker_tests.rs
index df528e32..3671118f 100644
--- a/crates/benilla-app/src/ui_script/color_picker_tests.rs
+++ b/crates/benilla-app/src/ui_script/color_picker_tests.rs
@@ -44,9 +44,10 @@ fn picker() -> UiScript {
 ///
 /// It is emphatically **not** the identity, and not a simple quantize either: `SetColorRGB` rounds
 /// half-up into bytes and stores HSV floats, while every read path floors, so 9.75 % of colours come
-/// back a step low on one channel (wow-re `system/ui/scratch/colorselect-color-law.md`, exhaustive
-/// over all 256³). `benilla_ui::script::colorselect`'s own tests pin that law against wow-re's
-/// measured witnesses; these tests use it as a given so they stay about the Dewdrop plumbing.
+/// back a step low on one channel (`SetColorRGB 0x78eae0`, the read-back floor `0x7bbec0`;
+/// measured exhaustively over all 256³). `benilla_ui::script::colorselect`'s own tests pin that law
+/// against the reference's measured witnesses; these tests use it as a given so they stay about the
+/// Dewdrop plumbing.
 fn after_round_trip(r: f64, g: f64, b: f64) -> (f64, f64, f64) {
     let mut cs = benilla_ui::widget::ColorSelectState::default();
     cs.set_rgb(r, g, b);
diff --git a/crates/benilla-app/src/ui_script/combat_text_tests.rs b/crates/benilla-app/src/ui_script/combat_text_tests.rs
index 19f1a428..eca631e3 100644
--- a/crates/benilla-app/src/ui_script/combat_text_tests.rs
+++ b/crates/benilla-app/src/ui_script/combat_text_tests.rs
@@ -336,8 +336,7 @@ fn combat_text_master_toggle_unregisters() {
 /// fast arm into a plain `lua_gettable(LUA_GLOBALSINDEX)` — so whatever is in the global when the
 /// world-entry load edge closes is what the numbers draw in. Stock `Fonts.xml` puts Friz there;
 /// MikScrollingBattleText and pfUI put their own face there at `ADDON_LOADED`, which the reference
-/// reads because `0x6c8470` runs *after* the addon load, not at CRT init as three wow-re notes
-/// had it.
+/// reads because `0x6c8470` runs *after* the addon load, not at CRT init.
 ///
 /// Skips without client data.
 #[test]
diff --git a/crates/benilla-app/src/ui_script/content.rs b/crates/benilla-app/src/ui_script/content.rs
index c672b8c2..1c969d10 100644
--- a/crates/benilla-app/src/ui_script/content.rs
+++ b/crates/benilla-app/src/ui_script/content.rs
@@ -8,7 +8,7 @@
 //! machine's source tree. On a player's machine every one of those files resolves to nothing and
 //! the client boots with no interface at all: not a crash, just an empty screen and one log line
 //! per manifest entry that nobody sees.
-//! `assets/ui` is our own content (MIT/Apache, not Blizzard's — the contract's hard rule is
+//! `assets/ui` is our own content (MIT/Apache, not Blizzard's — `docs/METHOD.md`'s hard rule is
 //! untouched), so it can simply be part of the program.
 //!
 //! ## Resolution order — the same in every build
@@ -71,7 +71,7 @@ fn read_source_tree(req: &str) -> Option<String> {
 ///
 /// It exists because a number taken from the corpus harness is meaningless without it. In a dev
 /// build [`read`] prefers the SOURCE TREE, so editing an `assets/ui` file changes what a survey
-/// loads **with no rebuild** — and this repo's worktrees are routinely shared by several agents at
+/// loads **with no rebuild** — and a tree is routinely edited by several agents at
 /// once. Three separate measurements this arc were taken across a moving tree and one of them
 /// landed a wrong attribution in a decision record: 87/218 was credited to a single table when a
 /// controlled A/B later put it at 75, with the other twelve belonging to a neighbour's uncommitted
diff --git a/crates/benilla-app/src/ui_script/death_tests.rs b/crates/benilla-app/src/ui_script/death_tests.rs
index a1ac60d7..6de05315 100644
--- a/crates/benilla-app/src/ui_script/death_tests.rs
+++ b/crates/benilla-app/src/ui_script/death_tests.rs
@@ -28,6 +28,7 @@ fn setup() -> UiScript {
 /// the Repop intent, and PLAYER_ALIVE (the release landing) hides it.
 #[test]
 fn death_popup_counts_down_and_release_queues_repop() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_death(DeathUiState {
         release_remaining: Some(300.0),
@@ -80,6 +81,7 @@ fn death_popup_counts_down_and_release_queues_repop() {
 /// "Reincarnate" default, and clicking it queues `UseSoulstone` — while button1 still releases.
 #[test]
 fn death_popup_offers_the_self_resurrect_and_spends_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_death(DeathUiState {
         release_remaining: Some(300.0),
@@ -119,6 +121,7 @@ fn death_popup_offers_the_self_resurrect_and_spends_it() {
 /// `DisplayButton2` nor `OnShow` per tick).
 #[test]
 fn death_popup_button2_is_decided_at_show_time() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_death(DeathUiState {
         release_remaining: Some(300.0),
@@ -159,6 +162,7 @@ fn death_popup_button2_is_decided_at_show_time() {
 /// DEATH_RELEASE_NOTIMER text and never counts down.
 #[test]
 fn death_popup_no_timer_shows_the_static_text() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_death(DeathUiState {
         release_remaining: None,
@@ -180,6 +184,7 @@ fn death_popup_no_timer_shows_the_static_text() {
 /// name in, gates Accept behind the recovery delay, and Accept/Decline queue their intents.
 #[test]
 fn resurrect_request_picks_variant_and_answers() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     // No sickness + timer, delay already elapsed: RESURRECT_NO_SICKNESS with an armed Accept.
     s.set_death(DeathUiState {
@@ -251,6 +256,7 @@ fn resurrect_request_picks_variant_and_answers() {
 /// and keeps the dialog, the second queues AcceptXPLoss; walking out of range auto-hides.
 #[test]
 fn xp_loss_two_step_confirm_then_range_hide() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_death(DeathUiState {
         sickness_duration: Some("8 Minutes".into()),
@@ -320,6 +326,7 @@ fn xp_loss_two_step_confirm_then_range_hide() {
 /// instance.
 #[test]
 fn xp_loss_cancel_then_reconfirm_reshows_with_the_alert_dress() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_death(DeathUiState {
         sickness_duration: Some("8 Minutes".into()),
@@ -373,6 +380,7 @@ fn xp_loss_cancel_then_reconfirm_reshows_with_the_alert_dress() {
 /// false for it; decision 0308 §1).
 #[test]
 fn the_ghost_predicates() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_unit(
         "player",
@@ -405,6 +413,7 @@ fn the_ghost_predicates() {
 /// variant is the buttonless notice.
 #[test]
 fn corpse_range_events_drive_recover_corpse() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_death(DeathUiState {
         recovery_delay: 2.0,
@@ -465,6 +474,7 @@ fn corpse_range_events_drive_recover_corpse() {
 /// WorldMapFrame.lua:443-452 law the map's update block branches on.
 #[test]
 fn corpse_map_position_binding() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     let (x, y) = s
         .eval::<(f64, f64)>("return GetCorpseMapPosition()")
diff --git a/crates/benilla-app/src/ui_script/delete_item_tests.rs b/crates/benilla-app/src/ui_script/delete_item_tests.rs
index f1b15482..2351f2ab 100644
--- a/crates/benilla-app/src/ui_script/delete_item_tests.rs
+++ b/crates/benilla-app/src/ui_script/delete_item_tests.rs
@@ -135,6 +135,7 @@ fn drop_in_world(s: &mut UiScript, item_id: u32, name: &str, quality: u32) {
 /// `DeleteCursorItem()` — the item leaves the cursor and queues its wire destroy.
 #[test]
 fn delete_item_confirm_shows_the_real_strings_and_yes_deletes() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     pick_up_and_drop_in_world(&mut s);
 
@@ -261,6 +262,7 @@ fn desaturated(s: &mut UiScript, button: &str) -> bool {
 /// this mainly proves the popup itself closes.)
 #[test]
 fn escape_closes_the_delete_confirm_popup() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     pick_up_and_drop_in_world(&mut s);
 
@@ -280,6 +282,7 @@ fn escape_closes_the_delete_confirm_popup() {
 /// DIFFERENT visible dialog is untouched by cursor traffic.
 #[test]
 fn the_delete_entry_polls_itself_hidden_and_other_dialogs_are_untouched() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     pick_up_and_drop_in_world(&mut s);
     assert!(s.eval::<bool>("return StaticPopup1:IsVisible()").unwrap());
@@ -316,6 +319,7 @@ fn the_delete_entry_polls_itself_hidden_and_other_dialogs_are_untouched() {
 /// focused, and OKAY **disabled** until the confirm word is typed.
 #[test]
 fn a_rare_payload_raises_the_typed_confirm_with_okay_disabled() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     drop_in_world(&mut s, 871, "Flurry Axe", 4);
 
@@ -354,6 +358,7 @@ fn a_rare_payload_raises_the_typed_confirm_with_okay_disabled() {
 /// passes, and backing away from the word disables it again. Then OKAY destroys.
 #[test]
 fn typing_the_confirm_word_enables_okay_and_untyping_it_disables_again() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     drop_in_world(&mut s, 871, "Flurry Axe", 4);
 
@@ -408,6 +413,7 @@ fn typing_the_confirm_word_enables_okay_and_untyping_it_disables_again() {
 /// only while OKAY is enabled, so a reflexive Enter over a half-typed word does nothing at all.
 #[test]
 fn enter_in_the_box_destroys_only_once_okay_is_enabled() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     drop_in_world(&mut s, 871, "Flurry Axe", 4);
 
@@ -437,6 +443,7 @@ fn enter_in_the_box_destroys_only_once_okay_is_enabled() {
 /// left over from last time would be armed before the player read the dialog).
 #[test]
 fn no_on_the_typed_confirm_clears_and_leaves_the_box_empty_for_next_time() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     drop_in_world(&mut s, 871, "Flurry Axe", 4);
     s.run(r#"StaticPopup1EditBox:SetText("DELETE")"#).unwrap();
@@ -476,6 +483,7 @@ fn no_on_the_typed_confirm_clears_and_leaves_the_box_empty_for_next_time() {
 /// cancel here, which the earlier form of this test pinned.
 #[test]
 fn escape_in_the_typed_confirms_box_is_swallowed_as_the_reference_leaves_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     drop_in_world(&mut s, 871, "Flurry Axe", 4);
     assert_eq!(
@@ -502,6 +510,7 @@ fn escape_in_the_typed_confirms_box_is_swallowed_as_the_reference_leaves_it() {
 /// destroy must not grow a field to type into. The control for every test above.
 #[test]
 fn the_plain_arm_shows_no_edit_box() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     pick_up_and_drop_in_world(&mut s); // Tough Jerky, quality 1
 
diff --git a/crates/benilla-app/src/ui_script/dressup_tests.rs b/crates/benilla-app/src/ui_script/dressup_tests.rs
index 9ad39c95..0a8fb8cd 100644
--- a/crates/benilla-app/src/ui_script/dressup_tests.rs
+++ b/crates/benilla-app/src/ui_script/dressup_tests.rs
@@ -278,6 +278,7 @@ fn shift_click_posts_the_link_with_chat_open_and_splits_with_it_closed() {
 /// is what the message frame's `OnHyperlinkClick` calls with the full markup.
 #[test]
 fn ctrl_clicking_a_chat_link_previews_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_room(&s);
@@ -412,6 +413,7 @@ fn shift_clicking_an_unresolved_slot_posts_nothing_and_never_raises() {
 /// BOTH mouse edges, so one tap is 0.06 (decision 0638 §3).
 #[test]
 fn reset_re_dresses_close_empties_and_the_arrows_spin_the_pane() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_room(&s);
diff --git a/crates/benilla-app/src/ui_script/dropdown_tests.rs b/crates/benilla-app/src/ui_script/dropdown_tests.rs
index fd2d2225..78bdcf6d 100644
--- a/crates/benilla-app/src/ui_script/dropdown_tests.rs
+++ b/crates/benilla-app/src/ui_script/dropdown_tests.rs
@@ -41,6 +41,7 @@ fn load_dropdown_kit(s: &UiScript) {
 /// `DropDownList1:Hide()` on its own.
 #[test]
 fn hiding_the_parent_list_closes_an_open_submenu() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_dropdown_kit(&s);
 
@@ -70,6 +71,7 @@ fn hiding_the_parent_list_closes_an_open_submenu() {
 /// The divergence from the reference is in this file, so it is fixed and falsified in this file.
 #[test]
 fn hiding_a_list_clears_its_open_menu_registry_entry() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_dropdown_kit(&s);
 
@@ -110,6 +112,7 @@ fn hiding_a_list_clears_its_open_menu_registry_entry() {
 /// equals some number: a literal would pass a number check and still be wrong.
 #[test]
 fn the_default_text_height_is_derived_from_button1_not_a_literal() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_dropdown_kit(&s);
 
@@ -141,6 +144,7 @@ fn the_default_text_height_is_derived_from_button1_not_a_literal() {
 /// `GameFontHighlightSmall` by name because that is what `UIDropDownMenuButtonTemplate` declares.
 #[test]
 fn a_button_label_reports_the_font_object_its_button_set() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_dropdown_kit(&s);
 
diff --git a/crates/benilla-app/src/ui_script/duel_tests.rs b/crates/benilla-app/src/ui_script/duel_tests.rs
index cbd80737..e5a233c0 100644
--- a/crates/benilla-app/src/ui_script/duel_tests.rs
+++ b/crates/benilla-app/src/ui_script/duel_tests.rs
@@ -27,6 +27,7 @@ fn setup() -> UiScript {
 /// Accept queues `AcceptDuel()`.
 #[test]
 fn the_challenge_popup_shows_the_name_and_accept_queues_the_accept() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event(
         "DUEL_REQUESTED",
@@ -54,6 +55,7 @@ fn the_challenge_popup_shows_the_name_and_accept_queues_the_accept() {
 /// engine routes an escape through OnCancel.
 #[test]
 fn decline_and_escape_both_cancel() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("DUEL_REQUESTED", vec![ScriptValue::Str("Twomage".into())]);
     s.run("StaticPopup_OnClick(StaticPopup1, 2)").unwrap();
@@ -69,6 +71,7 @@ fn decline_and_escape_both_cancel() {
 /// StaticPopup engine's per-tick branch, and `DUEL_INBOUNDS` takes it away.
 #[test]
 fn out_of_bounds_counts_down_and_inbounds_dismisses_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("DUEL_OUTOFBOUNDS", vec![]);
     assert!(s.eval::<bool>("return StaticPopup1:IsVisible()").unwrap());
@@ -100,6 +103,7 @@ fn out_of_bounds_counts_down_and_inbounds_dismisses_it() {
 /// leave a stale popup or fire a second cancel.
 #[test]
 fn finishing_sweeps_both_dialogs_silently() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("DUEL_REQUESTED", vec![ScriptValue::Str("Twomage".into())]);
     assert!(s.eval::<bool>("return StaticPopup1:IsVisible()").unwrap());
@@ -123,6 +127,7 @@ fn finishing_sweeps_both_dialogs_silently() {
 /// their argument through so the app can resolve it.
 #[test]
 fn the_era_globals_queue_their_intents() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.run("AcceptDuel(); CancelDuel(); StartDuel('Onerogue'); StartDuelUnit('target')")
         .unwrap();
diff --git a/crates/benilla-app/src/ui_script/durability_tests.rs b/crates/benilla-app/src/ui_script/durability_tests.rs
index 81e5f66e..3124afe0 100644
--- a/crates/benilla-app/src/ui_script/durability_tests.rs
+++ b/crates/benilla-app/src/ui_script/durability_tests.rs
@@ -115,8 +115,8 @@ fn armor_guy_shows_red_broken_yellow_damaged_and_hides_clean() {
     );
     assert_eq!(cell_color(&mut s, WEAPON_CELL), Some(RED), "broken → red");
 
-    // Damaged legs (3 points left — the byte law's ABSOLUTE 1..=5, wow-re inventory-alert-law
-    // `cmp [D+0xa0],5`): every body piece shows, legs yellow, the un-alerted head the faded
+    // Damaged legs (3 points left — the byte law's ABSOLUTE 1..=5, `cmp [D+0xa0],5` at
+    // `0x4c8012`): every body piece shows, legs yellow, the un-alerted head the faded
     // white(0.5); the weapon glyph (repaired now) hides.
     let mut inv: InventorySlots = Default::default();
     inv[7] = slot(39, Some((3, 25)));
@@ -162,7 +162,7 @@ fn armor_guy_shows_red_broken_yellow_damaged_and_hides_clean() {
     assert!(s.errors().is_empty(), "errors: {:?}", s.errors());
 }
 
-/// The FLAGS bits (wow-re inventory-alert-law): `0x10` forces red regardless of durability;
+/// The FLAGS bits (`0x4c7faa`, `0x4c7fc8`): `0x10` forces red regardless of durability;
 /// `0x08` (wrapped gift) silences the region entirely. And the client's 12th region — low ammo
 /// (carried count <= 20 → 3) — answers through `GetInventoryAlertStatus(12)` even though the
 /// 1.12 FrameXML never reads it.
diff --git a/crates/benilla-app/src/ui_script/enchant_confirm_tests.rs b/crates/benilla-app/src/ui_script/enchant_confirm_tests.rs
index a8f94d6c..7c837577 100644
--- a/crates/benilla-app/src/ui_script/enchant_confirm_tests.rs
+++ b/crates/benilla-app/src/ui_script/enchant_confirm_tests.rs
@@ -1,5 +1,5 @@
 //! The two enchant-apply confirms (decision 0928, EnchantConfirm.xml): the Lua wiring between the
-//! events `ui_action::targeting`'s item-bind gate fires and the shared StaticPopup engine, driven
+//! events `spell::targeting`'s item-bind gate fires and the shared StaticPopup engine, driven
 //! exactly as that gate drives it.
 //!
 //! What these pin is the seam, not the gate: that `BIND_ENCHANT` and `REPLACE_ENCHANT` reach a
@@ -32,6 +32,7 @@ fn setup() -> UiScript {
 /// — which on the app side re-enters `0x495d60` with the confirmed flag, not a send.
 #[test]
 fn the_bind_confirm_shows_and_its_okay_queues_bind_enchant() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("BIND_ENCHANT", vec![]);
     assert!(
@@ -52,6 +53,7 @@ fn the_bind_confirm_shows_and_its_okay_queues_bind_enchant() {
 /// — the fire site pushes the enchant already on the item first, then the one about to land.
 #[test]
 fn the_replace_confirm_names_the_old_enchant_first() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event(
         "REPLACE_ENCHANT",
@@ -73,6 +75,7 @@ fn the_replace_confirm_names_the_old_enchant_first() {
 /// returned before `BindTarget` and the targeting word is still standing.
 #[test]
 fn declining_either_confirm_queues_nothing() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("BIND_ENCHANT", vec![]);
     s.run("StaticPopup_OnClick(StaticPopup1, 2)").unwrap();
@@ -92,6 +95,7 @@ fn declining_either_confirm_queues_nothing() {
 /// anything, so a cancelled or replaced cast must not leave a live Yes button behind.
 #[test]
 fn a_changed_pending_cast_dismisses_both() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("BIND_ENCHANT", vec![]);
     s.fire_event("CURRENT_SPELL_CAST_CHANGED", vec![]);
diff --git a/crates/benilla-app/src/ui_script/escape_tests.rs b/crates/benilla-app/src/ui_script/escape_tests.rs
index f2a7e9d3..9ce78ec9 100644
--- a/crates/benilla-app/src/ui_script/escape_tests.rs
+++ b/crates/benilla-app/src/ui_script/escape_tests.rs
@@ -139,9 +139,8 @@ fn escape_closes_bag_and_panel_releases_loot_and_clears_cursor() {
     );
     // **ESC does NOT drop the cursor's item.** Our retired ladder opened with
     // `if CursorHasItem() then ClearCursor() end`; the reference's `ToggleGameMenu`
-    // (`UIParent.lua:1465-1497`) has no such arm, and wow-re's cursor carve places the
-    // ESC→ClearCursor wiring in FrameXML rather than the engine
-    // (`ui/scratch/cursor-dragdrop-payload.md`) — so in 1.12 the held item survives the key
+    // (`UIParent.lua:1465-1497`) has no such arm, and the ESC→ClearCursor wiring is inferred to
+    // live in FrameXML rather than the engine — so in 1.12 the held item survives the key
     // (1988).
     assert!(
         s.cursor_item().is_some(),
@@ -203,6 +202,7 @@ fn escape_is_consumed_by_a_focused_editbox_and_leaves_windows_open() {
 /// to eat, opens the menu (one eater per press, the 0449 law).
 #[test]
 fn escape_closes_the_options_window_before_opening_the_menu() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -526,6 +526,7 @@ fn escape_ladder_targeting_rung_after_cast_before_windows() {
 /// `Hide`, never `HideUIPanel`, because these frames hold no panel slot.
 #[test]
 fn an_addon_frame_registered_in_uispecialframes_closes_on_escape() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
diff --git a/crates/benilla-app/src/ui_script/event_shape_gate.rs b/crates/benilla-app/src/ui_script/event_shape_gate.rs
index eaff3cdf..a06a55c2 100644
--- a/crates/benilla-app/src/ui_script/event_shape_gate.rs
+++ b/crates/benilla-app/src/ui_script/event_shape_gate.rs
@@ -19,7 +19,8 @@
 //!
 //! ## What is compared, and what the table can and cannot say
 //!
-//! The oracle is wow-re's two byte-level censuses, vendored by `scripts/gen-reference-events.py`.
+//! The oracle is two byte-level censuses of the reference, vendored by
+//! `scripts/gen-reference-events.py`.
 //! Its `conf` column carries the gate rule per row, exactly as `1.12-shapes.tsv` does:
 //!
 //! * `exact` — every producer that reaches the event has a known shape. **This is the column this
diff --git a/crates/benilla-app/src/ui_script/exp_bar_tests.rs b/crates/benilla-app/src/ui_script/exp_bar_tests.rs
index 74d7e565..45b067f4 100644
--- a/crates/benilla-app/src/ui_script/exp_bar_tests.rs
+++ b/crates/benilla-app/src/ui_script/exp_bar_tests.rs
@@ -53,6 +53,7 @@ fn exp_bar_harness() -> UiScript {
 /// transparent and the hover silently never fires, which no tooltip assertion alone would catch.
 #[test]
 fn the_xp_bar_takes_the_mouse_and_explains_itself() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = exp_bar_harness();
     s.resolve();
 
@@ -106,6 +107,7 @@ fn the_xp_bar_takes_the_mouse_and_explains_itself() {
 /// pool whose span runs past the level's end hides the tick but keeps the rested blue.
 #[test]
 fn the_exhaustion_tick_marks_where_rested_runs_out() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = exp_bar_harness();
 
     s.set_player_xp(1000, 10000);
@@ -113,8 +115,8 @@ fn the_exhaustion_tick_marks_where_rested_runs_out() {
     s.fire_event("PLAYER_ENTERING_WORLD", vec![]);
     s.resolve();
 
-    // The binding trio underneath (the app-feed shape the XML consumes) — the byte-verified
-    // contract (wow-re rested-xp-bindings.md, decision 1087).
+    // The binding trio underneath (the app-feed shape the XML consumes) — the reference's
+    // contract (`0x48d350`, `0x48d3f0`, `0x516ea0`; decision 1087).
     let (id, name, mult) = s
         .eval::<(i64, String, f64)>("return GetRestState()")
         .unwrap();
@@ -220,6 +222,7 @@ fn the_exhaustion_tick_marks_where_rested_runs_out() {
 /// hides it — the ref's own load order, ending hidden.
 #[test]
 fn the_max_level_rail_replaces_the_xp_bar_at_60() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = exp_bar_harness();
     s.set_player_xp(1000, 10000);
     s.set_rest_state(1, 700, true);
@@ -271,6 +274,7 @@ fn the_max_level_rail_replaces_the_xp_bar_at_60() {
 /// re-stamp can lift a lower layer over them.
 #[test]
 fn the_gryphons_outrank_the_bars_across_hide_show_cycles() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = exp_bar_harness();
     s.set_player_xp(300, 400);
     s.fire_event("PLAYER_ENTERING_WORLD", vec![]);
@@ -307,6 +311,7 @@ fn the_gryphons_outrank_the_bars_across_hide_show_cycles() {
 /// 0↔1 edge — the `statusBarText` cvar that pins it on permanently reads OFF here).
 #[test]
 fn the_xp_bar_numerals_show_on_hover() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = exp_bar_harness();
     s.set_player_xp(1234, 5678);
     s.fire_event("PLAYER_ENTERING_WORLD", vec![]);
@@ -342,6 +347,7 @@ fn the_xp_bar_numerals_show_on_hover() {
 /// held-open newbie tip, once (the handshake is consumed).
 #[test]
 fn the_rest_state_line_joins_the_held_open_tooltip() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = exp_bar_harness();
     s.set_player_xp(1000, 10000);
     s.set_rest_state(1, 700, true);
diff --git a/crates/benilla-app/src/ui_script/extract/colorselect.rs b/crates/benilla-app/src/ui_script/extract/colorselect.rs
index 744e8092..bed06d00 100644
--- a/crates/benilla-app/src/ui_script/extract/colorselect.rs
+++ b/crates/benilla-app/src/ui_script/extract/colorselect.rs
@@ -11,10 +11,7 @@
 //! (`hsv_to_rgb` scales all three outputs by `v` and by nothing else, so `rgb(h, s, v)` really is
 //! `v · rgb(h, s, 1)`).
 //!
-//! Everything below is byte-verified in wow-re's `system/ui/scratch/colorselect-drawn-appearance.md`
-//! (a §5 cross-check dispatched from this repo for exactly this window: six workers in three pairs,
-//! one of each briefed cold, plus the orchestrator's own contiguous derivation). What it settled,
-//! and what each fact cost to get wrong:
+//! The reference's drawn appearance, and what each fact cost to get wrong:
 //!
 //! * **The disc is a 128×128 generated ARGB texture** (`0x78b580`, 16384 dwords into a
 //!   function-local static, uploaded once per process), drawn unmodulated — not a vertex-coloured
@@ -25,7 +22,7 @@
 //! * **The texel lattice is integers**, `X, Y ∈ [−64, 63]`, drawn iff `X² + Y² ≤ 0x1000` —
 //!   boundary *inclusive* — and outside is `0x00000000`, a hard alpha cut with no mask and no
 //!   feathering. `S = √(X²+Y²)/64`; `H = (atan2(Y, X) + π)·180/π`, the exact inverse of the pick
-//!   law (`colorselect-color-law.md` §5), which is what makes clicking a texel select the colour
+//!   law (`0x78bd80`), which is what makes clicking a texel select the colour
 //!   that texel shows. Row 0 is `Y = +63`: the top.
 //! * **The strip is an 8×8 solid texture of `HSV(H, S, 1)` times a vertical vertex gradient**,
 //!   black at the bottom and white at the top (`0x78b8a0` + `0x78b92a call 0x77f910`, and
@@ -140,8 +137,8 @@ mod tests {
     }
 
     /// The one property the disc must have: the colour a texel *shows* is the colour a click on
-    /// that texel *selects*. The right-hand side here is the pick law from wow-re
-    /// `colorselect-color-law.md` §5, which `benilla-ui`'s own `wheel_hs` transcribes — if the two
+    /// that texel *selects*. The right-hand side here is the reference's pick law
+    /// (`0x78bd80`), which `benilla-ui`'s own `wheel_hs` transcribes — if the two
     /// ever part company, one of these sides moves and this fails.
     #[test]
     fn every_texel_shows_the_colour_a_click_on_it_would_pick() {
@@ -170,8 +167,9 @@ mod tests {
     }
 
     /// The disc's cardinal points, spelled out — this is what pins the *orientation* of the whole
-    /// image, and it is the half a sign error would silently mirror. wow-re read it off the fill
-    /// loop: **red LEFT, chartreuse BOTTOM, cyan RIGHT, violet TOP**, hue rising counter-clockwise.
+    /// image, and it is the half a sign error would silently mirror. Off the reference's fill loop
+    /// (`0x78b580`): **red LEFT, chartreuse BOTTOM, cyan RIGHT, violet TOP**, hue rising
+    /// counter-clockwise.
     #[test]
     fn the_discs_cardinal_hues_are_the_pick_laws() {
         let (w, h, rgba) = wheel_pixels();
diff --git a/crates/benilla-app/src/ui_script/extract/mod.rs b/crates/benilla-app/src/ui_script/extract/mod.rs
index 72569ad2..f504fc9e 100644
--- a/crates/benilla-app/src/ui_script/extract/mod.rs
+++ b/crates/benilla-app/src/ui_script/extract/mod.rs
@@ -574,9 +574,9 @@ pub(super) fn tick_script(
     };
     let (w, h) = (window.width(), window.height());
     // The 768-virtual UI space (decision 0582 — byte law: the client's FrameXML space is ALWAYS
-    // 768 units tall, every aspect, mapped to the window; wow-re ui.md's converter identity
-    // `f(screenH) = 768` + the caret `H_px/192` law), times the uiScale dial (decision 0584 —
-    // the VM's screen is `768/uiScale` units tall, so a dial below 1 shrinks everything). The VM
+    // 768 units tall, every aspect, mapped to the window; the converter identity `f(screenH) = 768`
+    // (`0x41ad10`) + the caret `H_px/192` law (`0x77b8c0`)), times the uiScale dial (decision 0584
+    // — the VM's screen is `768/uiScale` units tall, so a dial below 1 shrinks everything). The VM
     // lives entirely in that space: this seam scales quads ×s on the way out, mouse ÷s on the
     // way in (input.rs), and measures ÷s on the way back. At a 768-tall window with the dial at
     // 1 the whole pipeline is bit-identical to the pre-virtual behavior.
@@ -650,16 +650,10 @@ pub(super) fn tick_script(
     {
         let _span = bevy::log::info_span!("ui_script: tick").entered();
         let resized = script.set_screen_size(w / s, if h > 0.0 { h / s } else { 768.0 });
-        // A resize re-runs the bottom-stack manage pass (decision 1499). Anchors follow the new
-        // screen rect by themselves; what does not is a seat somebody COMPUTED from the old
-        // height — the open-bag stack starts a fresh column when the current one would run off
-        // the top, and that decision is made from `GetScreenHeight()` at layout time. Without
-        // this, dragging the window smaller leaves the bag columns wrapped for the old height
-        // until the next bag opens. Existence-guarded: the pass is defined by `UIParent.xml`,
-        // which is in-game UI, and this system also runs on the glue screens.
+        // A resize re-runs everything the interface COMPUTED from the old screen size — see
+        // [`super::manifest::on_screen_resized`].
         if resized {
-            let _ = script
-                .run("if UIParent_ManageFramePositions then UIParent_ManageFramePositions() end");
+            super::manifest::on_screen_resized(&script);
         }
         script.tick(time.delta_secs());
     }
@@ -928,7 +922,7 @@ pub(super) fn paint_script(
             script.set_editbox_advances(req.id, req.key, cum, rows, cell_h / s);
         }
     }
-    // The focused edit box's text-UI geometry (RF-0082 leaves caret/highlight geometry to the
+    // The focused edit box's text-UI geometry (the engine leaves caret/highlight geometry to the
     // host): which Text quad is the box's, the scroll window to draw, and the caret/selection
     // x-spans within it — advance-derived engine-side (the blink phase too, `0x77a790`'s 0.5 s
     // law in the engine tick), matched in the Text arm below.
@@ -1460,7 +1454,7 @@ fn convert_entry(
         } => {
             use crate::portrait::PortraitSource;
             // A FILE pane (decision 2008): publish what the tile renderer needs — the pane's
-            // device-pixel size, the render law's unit ladder off it, and where the composite
+            // device-pixel size, the reference's unit ladder off it, and where the composite
             // goes (its rect, paint key, alpha and clip). The request is idempotent, so the
             // memoized conversion may re-publish it freely; which panes draw is the engine's
             // paint list, and the quad itself is the renderer's per-frame output
@@ -1481,18 +1475,19 @@ fn convert_entry(
                     crate::ui_models::TileRequest {
                         path: path.to_string(),
                         size_px,
-                        // `1 model unit = 1280 · modelScale · layoutScale` FrameXML units (§3).
+                        // `1 model unit = 1280 · modelScale · layoutScale` FrameXML units
+                        // (`0x76d1a0`).
                         px_per_unit: 1280.0 * model_scale * layout * s * dpi,
                         // `SetPosition` is in layout units: `768 · √(a²+1)` FrameXML per unit.
                         pos_px_per_unit: 768.0 * diag * layout * s * dpi,
-                        // A particle's half-extent: eye space, neither scale (§6).
+                        // A particle's half-extent: eye space, neither scale (`0x7b2a50`).
                         star_px_per_unit: 768.0 * diag * s * dpi,
                         facing,
                         position: Vec3::new(position.0, position.1, position.2),
                         // The PERSPECTIVE leg's root (decision 2027), which is in model units,
                         // not pixels: `T(pos · layoutScale) · R(facing) · S(s)` with
                         // `s = G48·(5/3)·modelScale·layoutScale` — and `G48·(5/3)` is exactly
-                        // `√((4/3)²+1)/√(a²+1)`, the 4:3 renormalizer (camera-law §11.2). The
+                        // `√((4/3)²+1)/√(a²+1)`, the 4:3 renormalizer (`0x80655c`). The
                         // camera is carried through the same matrix, so both terms cancel for
                         // framing; they are here because the record's near/far are NOT scaled
                         // with them, and because the geometry has to be drawn somewhere.
@@ -1504,7 +1499,7 @@ fn convert_entry(
                         icon: icon.clone(),
                         rect,
                         z_key: eq.z,
-                        // The instance draws at the widget's OWN alpha (render law §4.4).
+                        // The instance draws at the widget's OWN alpha (`0x76d120`).
                         alpha: own_alpha,
                         clip,
                     },
@@ -1652,7 +1647,7 @@ fn convert_entry(
             // used to fall through to `color.unwrap_or(WHITE)` with a `None` texture, which
             // `ui_pass` renders as the shared 1×1 white image tinted white: an opaque white
             // rectangle at the region's rect, which is how B221's macro icons reached the
-            // director's screen. wow-re settles what the reference does: `TextureCreate` does
+            // director's screen. What the reference does: `TextureCreate` does
             // build an 8×8 placeholder, but `CSimpleTexture::SetTexture` (`0x770200`) checks the
             // status severity and at ≥2 releases it and returns **without touching the widget's
             // texture** — the widget keeps what it had, and Lua gets `nil`. Nothing goes white.
@@ -2584,7 +2579,7 @@ mod extract_gate_tests {
     /// half that can silently rot: the shader's `select(a, k, premultiplied)` is only correct if
     /// exactly the render-target quads carry the flag. Drop it and every additive effect the pane
     /// draws over EMPTY space is multiplied by its own zero alpha again — the R14 pauldrons' fire
-    /// gone, a weapon glow chopped at the model's silhouette (Goudy, `#bugs` 2026-07-27).
+    /// gone, a weapon glow chopped at the model's silhouette.
     #[test]
     fn a_booth_bake_quad_is_flagged_premultiplied_and_a_plain_one_is_not() {
         let mut app = app_with_marker();
@@ -2696,7 +2691,7 @@ mod extract_gate_tests {
             before - 1,
             "the cleared marker's quad is gone from the stitched list"
         );
-        // The follow-up (0 → 1 quads) splices against the RE-DERIVED spans.
+        // The follow-up (0 → 1 quads) splices against the re-derived spans.
         app.world_mut().resource_mut::<UiQuads>().dirty = false;
         app.world_mut()
             .non_send_resource_mut::<UiScript>()
@@ -2782,7 +2777,7 @@ mod extract_gate_tests {
         );
         // The reference must share the app's HISTORY, not just its end state: `Show()` on a
         // hidden frame re-stacks it to the tail of its draw bucket — the client's own
-        // `effective_visible_show 0x76ae10` re-adding it to the level's intrusive list — so B
+        // effective-visibility show `0x76ae10` re-adding it to the level's intrusive list — so B
         // draws above C afterwards. (The splice got that right on its own; this reference did
         // not, which is how the difference surfaced.)
         let mut reference = app_from_script(&format!("{BUILD}\nhidden:Hide()\nhidden:Show()"));
diff --git a/crates/benilla-app/src/ui_script/extract/text.rs b/crates/benilla-app/src/ui_script/extract/text.rs
index b3bfbfb5..228795d7 100644
--- a/crates/benilla-app/src/ui_script/extract/text.rs
+++ b/crates/benilla-app/src/ui_script/extract/text.rs
@@ -332,7 +332,7 @@ pub(super) fn emit(
     }
     // The probe's seat line: the drawn INK rows (glyph-quad union, logical px, relative to the
     // rect top) — the measurable half of the vertical-seat law
-    // (`fontstring-vertical-placement.md`): compare `ink` against the law's `d + ascender` seat
+    // (`0x5d1360`): compare `ink` against the law's `d + ascender` seat
     // when hunting a vertical offset. Fill quads only (the shadow pass above would smear the
     // bounds one px down-right).
     let vpl = style.world_seat && benilla_assets::trace::enabled_for("vpl");
@@ -382,7 +382,7 @@ pub(super) fn emit(
             #[allow(clippy::cast_precision_loss)]
             let top = top + ui.caret_row as f32 * cell_h;
             // caret_x is engine UI units (÷scale advances); the 1-px bar width stays device-thin
-            // (the client's 4-unit caret is a named residual, ui.md's caret law).
+            // (the client's 4-unit caret, `0x77b8c0`, is a named residual).
             let cx = x0 + ui.caret_x * host.scale;
             out.push(UiQuad {
                 rect: Rect::new(cx, top, cx + 1.0, top + cell_h),
diff --git a/crates/benilla-app/src/ui_script/fade_tests.rs b/crates/benilla-app/src/ui_script/fade_tests.rs
index ef331008..7e6d1d05 100644
--- a/crates/benilla-app/src/ui_script/fade_tests.rs
+++ b/crates/benilla-app/src/ui_script/fade_tests.rs
@@ -11,6 +11,7 @@ use super::test_ui::load_ui as load_xml;
 
 #[test]
 fn a_started_fade_ramps_off_uiparents_tick_and_completes() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, r"Interface\FrameXML\MoneyFrame.lua");
@@ -67,6 +68,7 @@ fn a_started_fade_ramps_off_uiparents_tick_and_completes() {
 /// twelve faux lists shipped unable to scroll (1868), so this runs a real flash to completion.
 #[test]
 fn a_flash_alternates_then_stops() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, r"Interface\FrameXML\MoneyFrame.lua");
diff --git a/crates/benilla-app/src/ui_script/faux_scroll_tests.rs b/crates/benilla-app/src/ui_script/faux_scroll_tests.rs
index 9fbe934c..ffbbb098 100644
--- a/crates/benilla-app/src/ui_script/faux_scroll_tests.rs
+++ b/crates/benilla-app/src/ui_script/faux_scroll_tests.rs
@@ -78,6 +78,7 @@ fn harness() -> UiScript {
 /// wear instead of a `Benilla*` one.)
 #[test]
 fn a_fresh_faux_frame_loads_at_the_top_with_no_range() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     assert_eq!(s.eval::<i64>("return TestScroll.offset").unwrap(), 0);
     let (lo, hi) = s
@@ -98,6 +99,7 @@ fn a_fresh_faux_frame_loads_at_the_top_with_no_range() {
 /// row, and `FauxScrollFrame_Update` returns the reference's `showScrollBar`.
 #[test]
 fn more_rows_than_fit_raise_the_bar_over_the_overflow_range() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     let shown = s
         .eval::<i64>("return FauxScrollFrame_Update(TestScroll, 12, 5, 16)")
@@ -139,6 +141,7 @@ fn more_rows_than_fit_raise_the_bar_over_the_overflow_range() {
 /// in five slots shows nothing, and there is no off-by-one that leaves a dead bar up.
 #[test]
 fn a_list_that_exactly_fits_shows_no_bar() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     let shown = s
         .eval::<Option<i64>>("return FauxScrollFrame_Update(TestScroll, 5, 5, 16)")
@@ -176,6 +179,7 @@ fn a_list_that_exactly_fits_shows_no_bar() {
 /// this test used to read a clamped offset immediately.
 #[test]
 fn a_shrinking_list_clamps_the_offset_back_into_range() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.run("FauxScrollFrame_Update(TestScroll, 20, 5, 16)")
         .unwrap();
@@ -238,6 +242,7 @@ fn a_shrinking_list_clamps_the_offset_back_into_range() {
 /// it leaves (ref UIPanelTemplates.lua l.205-223).
 #[test]
 fn the_shrink_widen_tail_resizes_the_rows_and_the_highlight() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     s.run(
         "FauxScrollFrame_Update(TestScroll, 12, 5, 16, \"TestRow\", 280, 300, TestHighlight, 276, 296)",
@@ -280,6 +285,7 @@ fn the_shrink_widen_tail_resizes_the_rows_and_the_highlight() {
 /// value model in one test (pixels on the bar, rows in the offset, `floor(v/step + 0.5)` between).
 #[test]
 fn dragging_the_bar_steps_the_offset_by_rows_and_repaints() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.run("TestRepaints = 0 function TestUpdate() TestRepaints = TestRepaints + 1 end")
         .unwrap();
@@ -354,6 +360,7 @@ fn dragging_the_bar_steps_the_offset_by_rows_and_repaints() {
 /// → `FauxScrollFrame_OnVerticalScroll`'s `floor(v / step + 0.5)`, the reference's path end to end.
 #[test]
 fn the_reference_on_vertical_scroll_path_runs_once_a_scroll_child_exists() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     load_inline(
         &s,
@@ -416,6 +423,7 @@ fn the_reference_on_vertical_scroll_path_runs_once_a_scroll_child_exists() {
 /// on that fallback, so the no-argument path is what this test drives.
 #[test]
 fn scrolling_edit_helpers_answer_bare_calls_from_a_handler() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
     load_xml(&s, "ScrollTemplates.xml");
diff --git a/crates/benilla-app/src/ui_script/frame_flag_gate.rs b/crates/benilla-app/src/ui_script/frame_flag_gate.rs
index 17f64443..94f60a72 100644
--- a/crates/benilla-app/src/ui_script/frame_flag_gate.rs
+++ b/crates/benilla-app/src/ui_script/frame_flag_gate.rs
@@ -1,7 +1,7 @@
 //! **The reference's frame FLAGS are the test oracle** — the flag half of decision 0675's "the
 //! reference file is the test oracle", and the gate for the class decision 1739 closed.
 //!
-//! `framexml_diff` guards the *numbers* a transcribed window carries. Nothing guarded its *flags*,
+//! A window's numbers are the stock file's own now. Nothing guarded its *flags*,
 //! and they went quietly wrong at scale: on 2026-08-30 a sweep found **47 frames** the reference
 //! marks `toplevel` and ours did not (so no window ever came to the front), **23** the reference
 //! makes mouse-interactive and ours did not (so a click on a window's own background fell through
@@ -14,8 +14,8 @@
 //! **Our side is read from the ENGINE, never from our XML.** An attribute-vs-attribute diff is
 //! precisely what let the class hide, twice over: benilla renames templates (`ChatFrameTemplate` →
 //! `BenillaChatFrameTemplate`), so a name-keyed text diff reports a gap of zero on a window that is
-//! entirely missing the flag; and the `<Scripts>` **auto-enable** law (wow-re
-//! `ui/scratch/scripts-auto-enable.md` §1, VERIFIED — an `<OnEnter>`/`<OnLeave>`/`<OnMouseDown>`/
+//! entirely missing the flag; and the `<Scripts>` **auto-enable** law (an
+//! `<OnEnter>`/`<OnLeave>`/`<OnMouseDown>`/
 //! `<OnMouseUp>`/`<OnDragStart>` reaches the same enable primitive `0x76af00(2,-1)` the attribute
 //! does) makes `enableMouse=` a poor proxy for whether the frame actually takes the mouse. Asking
 //! the loaded engine — `IsToplevel()`, `IsMouseEnabled()`, `GetID()`, `GetParent()` — is immune to
@@ -71,11 +71,10 @@
 //! can hide a divergence, never invent one — so nothing it misses turns into a false failure. It
 //! would be a `KNOWN` entry's reason if any frame still needed one.
 //!
-//! The whole module skips cleanly with no install — `_extracted_framexml/` is a gitignored
-//! Blizzard asset, like every other client-data test here.
+//! The whole module skips cleanly with no install — the reference corpus is read off the
+//! player's own patch chain, like every other client-data test here.
 
-use std::collections::HashMap;
-use std::path::{Path, PathBuf};
+use std::collections::{HashMap, HashSet};
 
 use benilla_ui::framexml::{self, Element, TopLevel};
 
@@ -104,7 +103,7 @@ const FRAME_TAGS: &[&str] = &[
 ];
 
 /// The five `<Scripts>` handler names that auto-enable the MOUSE kind, and only those five
-/// (wow-re `ui/scratch/scripts-auto-enable.md` §1's kind-2 OR-chain, `0x769fb7`..`0x76a022`).
+/// (the kind-2 OR-chain, `0x769fb7`..`0x76a022`).
 /// `OnDragStop`/`OnReceiveDrag` bind a slot and trip no enable — they are deliberately absent.
 const MOUSE_HANDLERS: &[&str] = &[
     "OnEnter",
@@ -232,34 +231,54 @@ const KNOWN: &[Known] = &[
     // window is the reference's own now, scroll children and all.
 ];
 
-/// The extracted reference FrameXML directory, or `None` when the install isn't there.
-fn reference_dir() -> Option<PathBuf> {
-    let dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../WoW/_extracted_framexml");
-    dir.is_dir().then_some(dir)
+/// Every reference FrameXML document, read off the player's own patch chain in the client's
+/// load order: the files `FrameXML.toc` lists, and what each `<Include>`s, each once. `None`
+/// without an install. Off the chain, never an extracted folder, so the gate is armed on any
+/// machine with the install rather than on the one that happened to extract it.
+fn reference_documents() -> Option<Vec<framexml::ParsedDocument>> {
+    let data = benilla_formats::wow_data()?;
+    let chain = benilla_formats::open_chain(&data).ok()?;
+    let toc = chain.read("Interface\\FrameXML\\FrameXML.toc").ok()?;
+    let toc = benilla_ui::toc::Toc::parse(&benilla_ui::source::decode(&toc));
+    let mut queue: Vec<String> = toc
+        .files
+        .iter()
+        .filter(|f| f.to_ascii_lowercase().ends_with(".xml"))
+        .map(|f| format!("Interface\\FrameXML\\{f}"))
+        .collect();
+    let mut seen = HashSet::new();
+    let mut docs = Vec::new();
+    while !queue.is_empty() {
+        let path = queue.remove(0);
+        if !seen.insert(path.to_ascii_lowercase()) {
+            continue;
+        }
+        let Ok(bytes) = chain.read(&path) else {
+            continue;
+        };
+        // Blizzard ships a UTF-8 BOM on some of these and stray high bytes in comments; the parse
+        // is what matters, so read lossily rather than refusing the file.
+        let text = String::from_utf8_lossy(&bytes);
+        let Ok(doc) = framexml::parse(text.trim_start_matches('\u{feff}')) else {
+            continue;
+        };
+        let dir = path.rsplit_once('\\').map(|(d, _)| d).unwrap_or("");
+        for item in &doc.items {
+            if let TopLevel::Include(file) = item {
+                queue.push(format!("{dir}\\{file}"));
+            }
+        }
+        docs.push(doc);
+    }
+    Some(docs)
 }
 
 /// Every named *frame* element in the reference corpus, keyed by name — templates and instances
 /// alike, nested `<Frames>` included, `$parent`-relative names excluded (they repeat across
 /// templates and name nothing on their own).
 fn reference_frames() -> Option<HashMap<String, Element>> {
-    let dir = reference_dir()?;
-    let mut paths: Vec<PathBuf> = std::fs::read_dir(&dir)
-        .ok()?
-        .flatten()
-        .map(|e| e.path())
-        .filter(|p| p.extension().is_some_and(|e| e.eq_ignore_ascii_case("xml")))
-        .collect();
-    paths.sort();
-
     let mut out: HashMap<String, Element> = HashMap::new();
-    for path in paths {
-        // Blizzard ships a UTF-8 BOM on some of these and stray high bytes in comments; the parse
-        // is what matters, so read lossily rather than refusing the file.
-        let bytes = std::fs::read(&path).ok()?;
-        let text = String::from_utf8_lossy(&bytes);
-        let Ok(doc) = framexml::parse(text.trim_start_matches('\u{feff}')) else {
-            continue;
-        };
+    for doc in reference_documents()? {
         for item in &doc.items {
             if let TopLevel::Template(el) | TopLevel::Instance(el) = item {
                 collect_named(el, &mut out);
@@ -315,24 +334,8 @@ fn collect_nesting(
 
 /// The reference's nesting table, built over the same corpus [`reference_frames`] reads.
 fn reference_nesting() -> Option<HashMap<String, Option<String>>> {
-    let dir = reference_dir()?;
-    let mut paths: Vec<PathBuf> = std::fs::read_dir(&dir)
-        .ok()?
-        .flatten()
-        .map(|e| e.path())
-        .filter(|p| p.extension().is_some_and(|e| e.eq_ignore_ascii_case("xml")))
-        .collect();
-    paths.sort();
-
     let mut out: HashMap<String, Option<String>> = HashMap::new();
-    for path in paths {
-        let Ok(bytes) = std::fs::read(&path) else {
-            continue;
-        };
-        let text = String::from_utf8_lossy(&bytes);
-        let Ok(doc) = framexml::parse(text.trim_start_matches('\u{feff}')) else {
-            continue;
-        };
+    for doc in reference_documents()? {
         for item in &doc.items {
             if let TopLevel::Template(el) | TopLevel::Instance(el) = item {
                 collect_nesting(el, None, &mut out);
@@ -396,7 +399,7 @@ fn declares_handler(
 }
 
 /// Whether the reference's frame of this name **takes the mouse** once loaded — the three ways
-/// `0x76af00(2, -1)` is reached, per `scripts-auto-enable.md` §1.3: the widget's own ctor, the
+/// `0x76af00(2, -1)` is reached: the widget's own ctor, the
 /// `enableMouse` attribute, or an auto-enabling `<Scripts>` handler.
 fn reference_takes_mouse(name: &str, frames: &HashMap<String, Element>) -> bool {
     let Some(el) = frames.get(name) else {
@@ -436,14 +439,8 @@ fn describe(frame: &str, flag: Flag, ours: &str, theirs: &str) -> String {
 /// `parent="UIParent"` back on `BlackoutWorld` and it names that.
 #[test]
 fn the_shipped_frames_carry_the_references_flags() {
-    // Two gates, because the corpus and the manifest are two assets: the extracted reference
-    // dir below, and the chain `load_default_ui` reads — under `WOW_DATA=` (1451) the first is
-    // still there and the second is not.
     let _data = benilla_formats::wow_data_or_skip!();
-    let Some(reference) = reference_frames() else {
-        eprintln!("skipping: no extracted reference FrameXML (WoW/_extracted_framexml)");
-        return;
-    };
+    let reference = reference_frames().expect("the reference FrameXML off the player's chain");
     let nesting = reference_nesting().expect("the same corpus the frames came from");
     assert!(
         reference.len() > 500,
diff --git a/crates/benilla-app/src/ui_script/framexml_diff.rs b/crates/benilla-app/src/ui_script/framexml_diff.rs
deleted file mode 100644
index 00f957a4..00000000
--- a/crates/benilla-app/src/ui_script/framexml_diff.rs
+++ /dev/null
@@ -1,171 +0,0 @@
-//! **The reference file is the test oracle** (decision 0675) — the shared half of it.
-//!
-//! A transcribed window's geometry errors are invisible to every behavioural test: the frames
-//! load, the buttons click, the lists populate, and only the *look* is wrong. 0675 built the
-//! detector for `FriendsFrame` after two rounds of the director's eye caught what a one-number
-//! diff would have caught on its first run, and closed with "for the next transcribed window,
-//! write the diff test first". This is that scraper, lifted out of `friends_tests` so the next
-//! window costs a call rather than a copy (`QuestTimerFrame` is the first to pay the lower price).
-//!
-//! Deliberately narrow: it does not try to understand the XML, only to notice that a number moved.
-//! Two properties make it a guard rather than a comfort, and both are the caller's to keep —
-//! **known-benign differences are an explicit list, never a pattern**, so a new difference cannot
-//! hide inside a tolerance; and **it must be verified to fail** (perturb one number by 1 px and
-//! watch it name the element).
-
-use std::collections::HashMap;
-use std::path::{Path, PathBuf};
-
-/// The extracted reference FrameXML file of that name, or `None` when the install isn't there
-/// (these tests skip cleanly without it — it is a gitignored Blizzard asset).
-pub(super) fn reference(file: &str) -> Option<PathBuf> {
-    let path = Path::new(env!("CARGO_MANIFEST_DIR"))
-        .join("../../WoW/_extracted_framexml")
-        .join(file);
-    path.is_file().then_some(path)
-}
-
-/// Named element → the `<AbsDimension>` pairs inside it, up to the next named element.
-///
-/// Hand-rolled rather than a regex: this crate has no regex dependency, and adding one for a scan
-/// of two files is a worse trade than twenty lines of `find`.
-///
-/// `$parent*` names repeat across templates (every row template has a `$parentText`), so a bare
-/// name would compare one template's column against another's. Each is qualified by the template
-/// it lives in — the nearest preceding real name.
-fn scrape(text: &str) -> Vec<(String, Vec<(f32, f32)>)> {
-    const TAGS: &[&str] = &[
-        "<Button name=\"",
-        "<Frame name=\"",
-        "<EditBox name=\"",
-        "<ScrollFrame name=\"",
-        "<FontString name=\"",
-        "<Texture name=\"",
-        "<CheckButton name=\"",
-    ];
-    // Every (offset, name) where a named element starts, in document order.
-    let mut marks: Vec<(usize, String)> = Vec::new();
-    for tag in TAGS {
-        let mut from = 0;
-        while let Some(hit) = text[from..].find(tag) {
-            let at = from + hit;
-            let name_start = at + tag.len();
-            let Some(len) = text[name_start..].find('"') else {
-                break;
-            };
-            marks.push((at, text[name_start..name_start + len].to_string()));
-            from = name_start + len;
-        }
-    }
-    marks.sort_by_key(|(at, _)| *at);
-
-    let mut owner = String::new();
-    marks
-        .iter()
-        .enumerate()
-        .map(|(i, (at, name))| {
-            let end = marks.get(i + 1).map_or(text.len(), |(next, _)| *next);
-            let key = if let Some(child) = name.strip_prefix("$parent") {
-                format!("{owner}/{child}")
-            } else {
-                owner = name.clone();
-                name.clone()
-            };
-            (key, dimensions(&text[*at..end]))
-        })
-        .collect()
-}
-
-/// Every `<AbsDimension x=".." y=".."/>` in `chunk`, in order.
-fn dimensions(chunk: &str) -> Vec<(f32, f32)> {
-    const OPEN: &str = "<AbsDimension x=\"";
-    let mut out = Vec::new();
-    let mut rest = chunk;
-    while let Some(hit) = rest.find(OPEN) {
-        rest = &rest[hit + OPEN.len()..];
-        let Some((x, tail)) = rest.split_once('"') else {
-            break;
-        };
-        let Some(y_at) = tail.find("y=\"") else { break };
-        let Some((y, tail)) = tail[y_at + 3..].split_once('"') else {
-            break;
-        };
-        if let (Ok(x), Ok(y)) = (x.parse(), y.parse()) {
-            out.push((x, y));
-        }
-        rest = tail;
-    }
-    out
-}
-
-/// Assert every element benilla's `ours` file shares with the reference `reference` file carries
-/// the reference's `<AbsDimension>` numbers.
-///
-/// - `ours` is a path under `assets/ui/`; names are matched to the reference's after stripping the
-///   house `Benilla` prefix (a window whose frames keep the bare reference names — decision 0591
-///   §3 — matches unchanged).
-/// - `expected` lists the *deliberate* deviations by their REFERENCE name. Every entry earns a
-///   comment at the call site naming its reason; that is what keeps this a guard.
-/// - `min_compared` fails the test if fewer elements paired up than that, so a scrape or a naming
-///   change that quietly stops comparing anything is caught rather than reported as a pass.
-///
-/// Elements ours has and the reference does not (our own template faces) are skipped, not failed.
-pub(super) fn assert_geometry_matches(
-    ours: &str,
-    reference: &Path,
-    expected: &[&str],
-    min_compared: usize,
-) {
-    assert_geometry_matches_text(
-        ours,
-        &std::fs::read_to_string(reference).unwrap(),
-        expected,
-        min_compared,
-    );
-}
-
-/// [`assert_geometry_matches`] against reference TEXT rather than a file on disk.
-///
-/// The split exists because not every reference file is *on* disk: `_extracted_framexml/` holds
-/// FrameXML only, and a window whose specification is partly a `Blizzard_*` **addon** — the raid
-/// grid is the first, decision 1549 — has to read its half straight out of the patch chain
-/// (`benilla_formats::open_chain`, the same door `mpqx` uses). Reading it rather than requiring
-/// someone to have extracted it first is what keeps that half of the diff ARMED instead of
-/// skipped, and it writes nothing into the install.
-pub(super) fn assert_geometry_matches_text(
-    ours: &str,
-    reference_text: &str,
-    expected: &[&str],
-    min_compared: usize,
-) {
-    let ours_text = std::fs::read_to_string(
-        Path::new(env!("CARGO_MANIFEST_DIR"))
-            .join("assets/ui")
-            .join(ours),
-    )
-    .unwrap();
-    let theirs: HashMap<String, Vec<(f32, f32)>> = scrape(reference_text).into_iter().collect();
-
-    let mut compared = 0;
-    let mut drifted = Vec::new();
-    for (name, dims) in scrape(&ours_text) {
-        let key = name.replace("Benilla", "");
-        let Some(ref_dims) = theirs.get(&key) else {
-            continue; // ours alone (the local template faces) — nothing to compare against
-        };
-        compared += 1;
-        if dims != *ref_dims && !expected.contains(&key.as_str()) {
-            drifted.push(format!("{key}: ours {dims:?} != ref {ref_dims:?}"));
-        }
-    }
-    assert!(
-        compared >= min_compared,
-        "only {compared} elements of {ours} matched by name (expected >= {min_compared}) — the \
-         scrape or the naming broke"
-    );
-    assert!(
-        drifted.is_empty(),
-        "{ours} geometry differs from the reference FrameXML:\n  {}",
-        drifted.join("\n  ")
-    );
-}
diff --git a/crates/benilla-app/src/ui_script/friends_tests.rs b/crates/benilla-app/src/ui_script/friends_tests.rs
index 6438449d..54fcba89 100644
--- a/crates/benilla-app/src/ui_script/friends_tests.rs
+++ b/crates/benilla-app/src/ui_script/friends_tests.rs
@@ -124,7 +124,7 @@ fn the_window_opens_on_friends_with_the_guild_tab_disabled() {
 /// `FriendsFrameTab1..4` inherit `FriendsFrameTabTemplate`, which inherits
 /// `CharacterFrameTabButtonTemplate` (the reference's own file, on the chain since 1993). The
 /// middle template declares an `<OnClick>` and nothing else, and handler replacement is **per
-/// handler name** (wow-re `template-onload-replacement-law.md`) — so the base template's
+/// handler name** (`0x76a0d0`) — so the base template's
 /// `<OnShow>` fit still runs, two hops down. That is the arrangement this pins: a row of tabs
 /// still wearing the base template's authored 115 would mean the OnShow was lost on the way.
 #[test]
@@ -784,8 +784,8 @@ fn selecting_a_row_reads_back_in_the_same_tick() {
         .contains(&SocialRequest::SelectFriend(2)));
 }
 
-/// **B363 — the who list reaches its last rows.** Liho's `/who` found 49, showed 17, and the knob
-/// travelled while the rows stayed. On the stock window the mechanism is a one-row loss:
+/// **B363 — the who list reaches its last rows.** The symptom: a `/who` of 49 shows 17, and the
+/// knob travels while the rows stay. On the stock window the mechanism is a one-row loss:
 /// `WhoListScrollFrame` is 287 tall (stock `FriendsFrame.xml` l.1661) against seventeen rows of
 /// sixteen, so the child's overflow past the frame, `n × 16 − 287`, sits fifteen pixels under the
 /// bar's `(n − 17) × 16`, and an engine that clamped `SetVerticalScroll` into that overflow
diff --git a/crates/benilla-app/src/ui_script/guild_tests.rs b/crates/benilla-app/src/ui_script/guild_tests.rs
index 5def5670..f4e87b56 100644
--- a/crates/benilla-app/src/ui_script/guild_tests.rs
+++ b/crates/benilla-app/src/ui_script/guild_tests.rs
@@ -884,9 +884,9 @@ fn the_column_headers_sort_by_their_own_keys() {
 
 /// **The Show Offline Members checkbox EXISTS.** The reference declares it `virtual="true"` inside
 /// a `<Frames>` block, which reads like "this is a template, do not build it" — and is not: the
-/// `virtual` attribute is only consulted by the top-level file loader (wow-5875-re rf24,
-/// `0x6ede10`), while a `<Frames>` child goes straight to the instantiator via `LoadChildFrames`
-/// (rf26). So the box is a real frame in the reference and must be one here.
+/// `virtual` attribute is only consulted by the top-level file loader (`0x6ede10`), while a
+/// `<Frames>` child goes straight to the instantiator via `LoadChildFrames 0x76a060`. So the box
+/// is a real frame in the reference and must be one here.
 ///
 /// Its click also DROPS THE SELECTION before re-filtering: the roster is about to be re-ordered,
 /// so index 7 will not be the member index 7 was.
diff --git a/crates/benilla-app/src/ui_script/honor_frame_tests.rs b/crates/benilla-app/src/ui_script/honor_frame_tests.rs
index 845c3885..e01d2f4c 100644
--- a/crates/benilla-app/src/ui_script/honor_frame_tests.rs
+++ b/crates/benilla-app/src/ui_script/honor_frame_tests.rs
@@ -281,7 +281,7 @@ fn the_bar_takes_the_fraction_and_the_faction_colour() {
     let _data = benilla_formats::wow_data_or_skip!();
     let s = shown_honor_page();
     // Against the binding's own arithmetic, not against `191/255`. The client MULTIPLIES by the
-    // f32 nearest 1/255 (`0x3B808081`, wow-re `honor-panel-law.md` `0x51aace`) rather than
+    // f32 nearest 1/255 (`0x3B808081`, `0x51aace`) rather than
     // dividing, and the two answers differ in the eighth decimal — a tolerance loose enough to
     // accept both would stop pinning the correction the moment it was made.
     let want = 191.0 * f64::from(f32::from_bits(0x3B80_8081));
diff --git a/crates/benilla-app/src/ui_script/input.rs b/crates/benilla-app/src/ui_script/input.rs
index 0aa463ba..94a802e9 100644
--- a/crates/benilla-app/src/ui_script/input.rs
+++ b/crates/benilla-app/src/ui_script/input.rs
@@ -13,6 +13,7 @@ use bevy::window::PrimaryWindow;
 use benilla_ui::script::UiScript;
 
 use super::{CursorPayloadHeld, PlayerUiClickConsumed, PlayerUiHover, UiKeyboardCapture};
+use crate::bindings::WheelNotches;
 use crate::textinput::{self, keymap, HostClipboard};
 
 /// The pointer-side state [`feed_ui_input`] reads and writes, as one
@@ -58,6 +59,28 @@ impl PointerFeed<'_> {
     }
 }
 
+/// The frame's wheel travel into the pane under the cursor's `OnMouseWheel` — **one call per whole
+/// notch**, `arg1 = ±1`.
+///
+/// The travel is normalised to lines first ([`crate::bindings::wheel_lines`]) and the fraction
+/// carried in `notches`: a trackpad reports a gesture as a `Pixel` trickle across many frames, and
+/// passing each frame's raw delta fired the handler once per frame — the stock handlers act on
+/// the sign alone (`ScrollFrameTemplate_OnMouseWheel` scrolls half a pane per call), so a gentle
+/// swipe slammed the pane to its end. A mouse wheel's `Line` notch still fires once, as before.
+fn feed_wheel(
+    script: &mut UiScript,
+    notches: &mut WheelNotches,
+    x: f32,
+    y: f32,
+    scroll: &AccumulatedMouseScroll,
+) {
+    let whole = notches.feed(crate::bindings::wheel_lines(scroll.unit, scroll.delta.y));
+    let step = whole.signum() as f32;
+    for _ in 0..whole.unsigned_abs() {
+        script.mouse_wheel(x, y, step);
+    }
+}
+
 /// Feed the window's cursor + buttons + wheel + keyboard into the UI engine (after
 /// [`super::extract::tick_script`] has resolved this frame's rects), firing
 /// OnEnter/OnLeave/OnClick/OnMouseWheel and the EditBox
@@ -73,7 +96,9 @@ pub(super) fn feed_ui_input(
     // winit has actually created the surface.
     window: Query<(&Window, Option<&bevy::window::RawHandleWrapper>), With<PrimaryWindow>>,
     buttons: Res<ButtonInput<MouseButton>>,
-    scroll: Res<AccumulatedMouseScroll>,
+    // The frame's wheel travel, and the fraction of a notch carried between frames
+    // ([`feed_wheel`]) — one param for clippy's argument ceiling.
+    (scroll, mut notches): (Res<AccumulatedMouseScroll>, ResMut<WheelNotches>),
     // One [`PointerFeed`] (clippy's argument ceiling): the hover + click-consumed outputs this
     // pass writes, the world pick that routes the world-click payload legs (decision 0571), and
     // the payload-held mirror written for the Send-side world-click consumers.
@@ -219,9 +244,7 @@ pub(super) fn feed_ui_input(
                 script.mouse_button(x, y, name, false);
             }
         }
-        if scroll.delta.y != 0.0 {
-            script.mouse_wheel(x, y, scroll.delta.y);
-        }
+        feed_wheel(&mut script, &mut notches, x, y, &scroll);
     } else if !synthetic {
         // The OS pointer left the window: leave whatever frame was hovered (once, on the
         // Some→None transition) and — every frame it stays outside — clear any armed press/drag
@@ -239,7 +262,7 @@ pub(super) fn feed_ui_input(
     capture.typing = script.has_keyboard_focus();
     // The per-key half is this frame's alone (a frame's existence gate ate THIS key).
     capture.consumed.clear();
-    // ── The alt-arrow exemption (wow-re `ignorearrows-alt-arrow-gate.md`, §5 VERIFIED) ─────────
+    // ── The alt-arrow exemption ────────────────────────────────────────────────────────────────
     // A focused EditBox in alt-arrow mode (`ignoreArrows` in XML, `SetAltArrowKeyMode` in Lua)
     // does NOT consume LEFT/UP/RIGHT/DOWN unless ALT is held: the reference's handler returns 0
     // at `0x77b1c4` and the strata walk carries the key down to `CGWorldFrame`, which runs its
@@ -287,7 +310,7 @@ pub(super) fn feed_ui_input(
         // `frame_key_input` walks in the engine's own order and declines at a focused box, so the
         // box's editing keys can never be stolen by a frame below it; a `true` here means a frame
         // consumed the key, which suppresses BOTH the chord below and the key's binding (the
-        // reference's existence gate, wow-re `frame-key-script-delivery.md` §3).
+        // reference's existence gate, `0x76b7d0`).
         let frame_named = match ev.key_code {
             KeyCode::Backspace => Some("BACKSPACE"),
             KeyCode::Delete => Some("DELETE"),
@@ -310,12 +333,12 @@ pub(super) fn feed_ui_input(
         }
         // EVERY OTHER KEY reaches a keyboard frame by name too. The reference's key-down walk
         // carries the whole key table — its `arg1` comes from the *same* table the keybinding
-        // chord uses (wow-re `frame-key-script-delivery.md` §4.2), which is [`chord::key_token`]
-        // here — and the frame's gate is EXISTENCE, not handling: a shown keyboard frame with an
-        // `OnKeyDown` swallows the key whatever its script does with it (§3, §3.1). This host used
-        // to feed only the ten names above, so `CinematicFrame` — fullscreen, keyboard-enabled, an
-        // `OnKeyDown` that answers ESCAPE — consumed ESC and let W straight through, and the player
-        // walked around underneath their own intro cinematic.
+        // chord uses (`0x4b66b0`), which is [`chord::key_token`] here — and the frame's gate is
+        // EXISTENCE, not handling: a shown keyboard frame with an `OnKeyDown` swallows the key
+        // whatever its script does with it (`0x76b7d0`, `0x76ba25`). This host used to feed only
+        // the ten names above, so `CinematicFrame` — fullscreen, keyboard-enabled, an `OnKeyDown`
+        // that answers ESCAPE — consumed ESC and let W straight through, and the player walked
+        // around underneath their own intro cinematic.
         //
         // The reference's own Lua is the proof this is the law and not an over-reading: that
         // handler has to call `RunBinding("SCREENSHOT")` **by hand** to get one key back. It would
@@ -368,8 +391,8 @@ pub(super) fn feed_ui_input(
                 // because `arrows_fall_through` exempts exactly these four from the typing gate.
                 keymap::Chord::Edit(_) => {}
                 // The clipboard trio needs the OS pasteboard, so it resolves here against the held
-                // [`HostClipboard`]: copy/cut pull the selection out of the box (RF-0082 §4
-                // `0x77e1d0` — selection required; a password box yields its mask run, never the
+                // [`HostClipboard`]: copy/cut pull the selection out of the box
+                // (`0x77e1d0` — selection required; a password box yields its mask run, never the
                 // real text), paste sanitizes+inserts.
                 keymap::Chord::Copy => {
                     if let Some(text) = script.editbox_copy() {
@@ -417,3 +440,93 @@ pub(super) fn feed_ui_input(
 // bare-key window toggles — moved into the command registry (`crate::bindings::commands`,
 // decision 0997): one chord→command table, rebindable, with 0585's modifier law enforced once
 // in the dispatch instead of per branch here.
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use bevy::input::mouse::MouseScrollUnit;
+
+    /// A bare VM with one wheel-enabled pane at the screen's centre whose `OnMouseWheel` counts
+    /// its calls and sums its `arg1`s.
+    fn wheel_pane() -> UiScript {
+        let mut s = UiScript::new().unwrap();
+        s.set_screen_size(1024.0, 768.0);
+        s.run(
+            r#"
+            local f = CreateFrame("Frame", "WheelProbe")
+            f:SetWidth(200) f:SetHeight(200) f:SetPoint("CENTER", nil, "CENTER", 0, 0)
+            f:EnableMouseWheel(true)
+            f:SetScript("OnMouseWheel", function()
+                WheelCalls = (WheelCalls or 0) + 1
+                WheelSum = (WheelSum or 0) + arg1
+            end)
+            f:Show()
+            "#,
+        )
+        .unwrap();
+        s.resolve();
+        s
+    }
+
+    fn calls(s: &UiScript) -> (i64, f64) {
+        s.eval::<(Option<i64>, Option<f64>)>("return WheelCalls, WheelSum")
+            .map(|(c, v)| (c.unwrap_or(0), v.unwrap_or(0.0)))
+            .unwrap()
+    }
+
+    fn frame_of(unit: MouseScrollUnit, dy: f32) -> AccumulatedMouseScroll {
+        AccumulatedMouseScroll {
+            unit,
+            delta: Vec2::new(0.0, dy),
+        }
+    }
+
+    /// **A gentle trackpad swipe is not a notch a frame.** Ten frames of a small `Pixel` delta —
+    /// a tenth of a line apiece at Bevy's factor, one line in total — must fire the pane's
+    /// `OnMouseWheel` at most the ONE notch they add up to. Fed raw, it fired ten times, and a
+    /// stock `ScrollFrameTemplate_OnMouseWheel` moves half a pane per call off the sign alone.
+    #[test]
+    fn a_trackpad_trickle_fires_only_the_notches_it_adds_up_to() {
+        let mut s = wheel_pane();
+        let mut notches = WheelNotches::default();
+        let step = MouseScrollUnit::SCROLL_UNIT_CONVERSION_FACTOR / 10.0;
+        for _ in 0..10 {
+            feed_wheel(
+                &mut s,
+                &mut notches,
+                512.0,
+                384.0,
+                &frame_of(MouseScrollUnit::Pixel, step),
+            );
+        }
+        let (n, sum) = calls(&s);
+        assert!(
+            n <= 1,
+            "ten frames adding up to one line fired {n} wheel calls (sum {sum})"
+        );
+        assert!(sum <= 1.0, "…and they may move at most one notch: {sum}");
+    }
+
+    /// A mouse wheel's notch arrives as one `Line` delta and fires exactly once, `arg1 = 1`.
+    #[test]
+    fn a_line_notch_fires_once() {
+        let mut s = wheel_pane();
+        let mut notches = WheelNotches::default();
+        feed_wheel(
+            &mut s,
+            &mut notches,
+            512.0,
+            384.0,
+            &frame_of(MouseScrollUnit::Line, 1.0),
+        );
+        assert_eq!(calls(&s), (1, 1.0));
+        feed_wheel(
+            &mut s,
+            &mut notches,
+            512.0,
+            384.0,
+            &frame_of(MouseScrollUnit::Line, -1.0),
+        );
+        assert_eq!(calls(&s), (2, 0.0), "and the other way is a notch down");
+    }
+}
diff --git a/crates/benilla-app/src/ui_script/inspect_tests.rs b/crates/benilla-app/src/ui_script/inspect_tests.rs
index 3af72bb1..7ddbbdb6 100644
--- a/crates/benilla-app/src/ui_script/inspect_tests.rs
+++ b/crates/benilla-app/src/ui_script/inspect_tests.rs
@@ -244,8 +244,8 @@ fn inspect_unit_refuses_out_of_range() {
 /// The two verified thresholds and their **different operators** — `CanInspect` refuses only on a
 /// strict `100.0 < d²` (so exactly 100.0 is IN range), while `CheckInteractDistance` admits only on
 /// a strict `d² < table[type-1]` (so exactly 100.0 is OUT). That asymmetry is the binary's own
-/// (wow-re §5: `test ah,0x41; jne` vs `test ah,0x5; jp`), and it is the kind of detail a rewrite
-/// silently normalizes — hence a test on the boundary itself.
+/// (`test ah,0x41; jne` at `0x48a28b` vs `test ah,0x5; jp` at `0x48bb0a`), and it is the kind of
+/// detail a rewrite silently normalizes — hence a test on the boundary itself.
 #[test]
 fn range_predicates_transcribe_the_verified_thresholds() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -280,7 +280,7 @@ fn range_predicates_transcribe_the_verified_thresholds() {
         "the same distance is out of range for the 10-yard type"
     );
     // **A token the object manager holds no unit for answers nil — the null-object arm** (report
-    // B316, wow-re `dist2-null-unit-arm.md` VERIFIED). This is the party member outside the local
+    // B316, `0x48babe`). This is the party member outside the local
     // area: the roster wire gives them a GUID, so the token resolves, and the object lookup then
     // misses silently. It used to answer 1, which lit every distance row for exactly the member
     // who was furthest away.
@@ -533,7 +533,7 @@ fn the_active_tab_is_inert_and_toggle_inspect_closes() {
 /// reference's own behaviour** (decision 1834 settled what 1832 had to leave open).
 ///
 /// `InspectFrame_OnHide` sets `this.unit = nil`, so a re-open runs `InspectFrame_OnShow` with no
-/// token. wow-re censused the whole binding table: `SetPortraitTexture 0x519ef0` gates its unit
+/// token. In the reference, `SetPortraitTexture 0x519ef0` gates its unit
 /// argument at `0x519fb4` with `lua_isstring` and raises `Usage: SetPortraitTexture(texture,
 /// "unit")`, and `luaL_error` does not return — so the reference raises here too, on its own
 /// shipped code. The widget clear sits six instructions PAST the gate, so the portrait is not even
@@ -544,7 +544,7 @@ fn the_active_tab_is_inert_and_toggle_inspect_closes() {
 /// abandons the handler the same way. So: the window shows, the portrait and name do not update,
 /// and there is exactly one error — which is what this now asserts.
 ///
-/// One correction from that census worth keeping: stock 1.12 ships **no** inspect keybind (0 of 234
+/// One correction worth keeping: stock 1.12 ships **no** inspect keybind (0 of 234
 /// `Binding name=` entries) and no caller of `ToggleInspect` outside the addon's own tab buttons,
 /// which are children of the hidden `InspectFrame`. So on the stock UI's own paths this is
 /// unreachable — only an addon or a macro gets here. It is still ours to reproduce.
diff --git a/crates/benilla-app/src/ui_script/keybindings_tests.rs b/crates/benilla-app/src/ui_script/keybindings_tests.rs
index ef46891b..c3fc1020 100644
--- a/crates/benilla-app/src/ui_script/keybindings_tests.rs
+++ b/crates/benilla-app/src/ui_script/keybindings_tests.rs
@@ -96,6 +96,7 @@ const ROW: &str = "BenillaOptionsFrameContainerBodyKeybindingsRow";
 
 #[test]
 fn the_page_is_an_options_category_with_the_collapsed_honest_tree() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     on_page(&mut s);
     assert!(s
@@ -191,6 +192,7 @@ fn the_page_is_an_options_category_with_the_collapsed_honest_tree() {
 
 #[test]
 fn the_capture_flow_binds_steals_and_refuses_like_112() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     on_page(&mut s);
     s.run(&format!("{ROW}1Header:Click()")).unwrap(); // expand Movement
@@ -300,6 +302,7 @@ fn the_capture_flow_binds_steals_and_refuses_like_112() {
 
 #[test]
 fn unbind_reset_and_the_live_commit_replace_okay_cancel() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     on_page(&mut s);
     s.run(&format!("{ROW}1Header:Click()")).unwrap(); // expand Movement
@@ -348,6 +351,7 @@ fn unbind_reset_and_the_live_commit_replace_okay_cancel() {
 
 #[test]
 fn the_esc_ladder_closes_the_window_and_the_checkbox_switches_sets() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     on_page(&mut s);
     // The ladder (the ESC binding's own body): the options rung hides the window — since 1008
@@ -400,6 +404,7 @@ fn the_esc_ladder_closes_the_window_and_the_checkbox_switches_sets() {
 
 #[test]
 fn search_surfaces_bindings_as_live_rows_under_the_redirect_head() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.run(r#"BINDING_NAME_JUMP = "Jump""#).unwrap();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
@@ -463,6 +468,7 @@ fn search_surfaces_bindings_as_live_rows_under_the_redirect_head() {
 
 #[test]
 fn the_action_bar_abbreviation_is_the_refs_own_getbindingtext() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     // ref UIParent.lua:1819 transcribed (UIParent.xml): one modifier abbreviates…
     assert_eq!(
@@ -519,6 +525,7 @@ fn the_action_bar_abbreviation_is_the_refs_own_getbindingtext() {
 /// own -32 — anchoring it to body-right hung the bar on the window border.
 #[test]
 fn the_wheel_bubbles_from_the_rows_and_the_bar_rides_the_gutter() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     on_page(&mut s);
     // Every section open: 100+ flat rows — the list overflows its 19 slots and the bar shows.
@@ -543,8 +550,8 @@ fn the_wheel_bubbles_from_the_rows_and_the_bar_rides_the_gutter() {
     // `FauxScrollFrameTemplate` carries a real `<ScrollChild>` which `FauxScrollFrame_Update` sizes
     // to `numItems * valueStep` (~5275px with every section open), our old template had none, and
     // the range is measured by unioning the scroll child's whole SUBTREE — the reference's own
-    // `0x786f80` recursion, which "re-enters itself for each shown child frame" with no clip or
-    // ScrollFrame exception (wow-re `system/ui/ui.md`, decision 1338). The reference would measure
+    // `0x786f80` recursion, which re-enters itself for each shown child frame with no clip or
+    // ScrollFrame exception (decision 1338). The reference would measure
     // the same; it simply never nests a faux list inside a real-scroll page, which our options
     // window is alone in doing.
     //
@@ -694,6 +701,7 @@ fn the_wheel_bubbles_from_the_rows_and_the_bar_rides_the_gutter() {
 /// path a player actually finds a binding by — paints the row live with that key on its capsule.
 #[test]
 fn the_pet_lane_is_registered_under_the_action_bar_header() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     on_page(&mut s);
 
diff --git a/crates/benilla-app/src/ui_script/lifecycle.rs b/crates/benilla-app/src/ui_script/lifecycle.rs
index 88a5b5af..a7a89a40 100644
--- a/crates/benilla-app/src/ui_script/lifecycle.rs
+++ b/crates/benilla-app/src/ui_script/lifecycle.rs
@@ -13,6 +13,7 @@ use bevy::prelude::*;
 use benilla_assets::LockRecover;
 use benilla_ui::script::UiScript;
 
+use super::manifest::silenced_ui_load;
 use super::{
     load_font_registry, load_ingame_ui, CursorPayloadHeld, PlayerUiHover, UiClock,
     UiKeyboardCapture,
@@ -45,8 +46,7 @@ pub(crate) fn setup_script(world: &mut World) {
 /// with `_G`, and the native `CSimpleFont` registry with the frame-script owner (`0x7839c0`, torn
 /// down at `0x490c97`). Because [`end_ui_session`] routes every login through here, every session's
 /// VM gets the registry and every `inherits="GameFontNormal"` in FrameXML resolves. A design that
-/// dropped the VM and skipped index 0 on the in-game load would fail exactly there — verified in
-/// wow-re's §5 for this change (2277).
+/// dropped the VM and skipped index 0 on the in-game load would fail exactly there (2277).
 fn install_boot_vm(world: &mut World) {
     let mut script = match UiScript::new() {
         Ok(s) => s,
@@ -72,7 +72,7 @@ fn install_boot_vm(world: &mut World) {
 /// it where the process already is, and [`UiClock`] is re-anchored to match in the same breath.
 ///
 /// The reference's `GetTime` (`0x515ea0`) reads `KERNEL32!GetTickCount` and scales by 0.001 (the
-/// thunk `0x42c010` → `0x42b790`, wow-re's `core` boundary row): an OS clock, with no relationship
+/// thunk `0x42c010` → `0x42b790`): an OS clock, with no relationship
 /// to the Lua VM, that cannot restart. Ours is a Lua global the VM owns, and since 1290/1291 the VM
 /// is destroyed and rebuilt at every logout/login and every `ReloadUI` — so without this seed the
 /// clock went back to zero on each of those, and every host value already converted onto it
@@ -276,8 +276,7 @@ fn unpark_boot_vm(world: &mut World) {
 /// 2226). It said `UI_Init 0x48fbf0` fires the world-enter cascade from inside itself, so a UI-less
 /// client never sees a unit event; that is 1348's reading and the bytes refute it, because the
 /// cascade call at `0x490168` is gated on an active-player GUID that is still 0/0 on a fresh login
-/// (see [`finish_ui_init`]). The conclusion survives, on four independent structural grounds, all
-/// re-verified in wow-5875-re:
+/// (see [`finish_ui_init`]). The conclusion survives, on four independent structural grounds:
 ///
 /// - World entry is a **category-5** callee (`0x420d63`), dispatched after the same iteration's
 ///   **category-6** inbound drain (`0x420d55`) has already returned.
@@ -457,6 +456,14 @@ pub(crate) fn load_ingame_ui_on_world_entry(world: &mut World) {
     let identity = world
         .get_resource::<crate::char_select::Roster>()
         .and_then(crate::ui_macro::identity);
+    // …and the realm's whole character list, which is the enable store's node set: the reference
+    // populates one `ADDONSTATELIST` node per character at char-list time, and an addon this
+    // character has never had an opinion about is resolved from what the others said
+    // (decision 2311).
+    let roster: Vec<String> = world
+        .get_resource::<crate::char_select::Roster>()
+        .map(|r| r.chars.iter().map(|c| c.name.clone()).collect())
+        .unwrap_or_default();
     // **The Lua index space, before a single addon file runs** (decision 2175). The reference has
     // the array in hand well before `UI_Init 0x48fbf0` reaches the addon walk — `SMSG_ADDON_INFO`
     // lands during the handshake — so an addon reading `GetNumAddOns()` at file scope sees a
@@ -576,47 +583,58 @@ pub(crate) fn load_ingame_ui_on_world_entry(world: &mut World) {
     // through its whole load edge and only converged a frame later off whatever poll the caller
     // had written to survive it.
     seat_raster_seam_for_load(world, &mut script);
-    let _ = load_ingame_ui(&mut script, identity.as_ref(), version_check);
-    // The Minimap widget was born a moment ago with `MinimapState::default()`; seed its two live
-    // zoom indices from the persisted CVars now, before anything reads them — the reference's own
-    // minimap reset path copying each CVar object's int into its live index (decision 1131). Once
-    // only: from here the widget's index is the live truth and `Minimap:SetZoom` writes the CVar
-    // back. Startup always precedes this state edge (1038), so the knob is already loaded.
-    let zoom = world.resource::<crate::minimap::MinimapZoom>();
-    script.set_minimap_zoom(zoom.outdoor, zoom.inside);
-    // The saved-variables chunk runs HERE — after the XML assigned its file-scope defaults, before
-    // any consumer reads them — then `VARIABLES_LOADED`. That is the reference's own load order
-    // (`AddOn_Load 0x51f240` steps 2 → 4 → 6, decision 1128); reversing it means the defaults
-    // always win and nothing can ever be remembered.
-    //
-    // **And the chat cache restores inside it, between `VARIABLES_LOADED` and `PLAYER_LOGIN`** —
-    // the reference's own slot for the reader's `UPDATE_CHAT_WINDOWS` + `UPDATE_CHAT_COLOR` burst
-    // (`0x4900d6`, after `0x4900b2` and before `0x490959`; decisions 2119 and 2125). It is the
-    // sole firer of `UPDATE_CHAT_WINDOWS`, which is the only thing that registers a chat frame for
-    // any `CHAT_MSG_*` (ref `ChatFrame.lua` l.1261-1273) — as an `Update` system it landed after
-    // the session's first chat had already been routed, and the login MOTD went to a window
-    // registered for nothing.
-    // The plate pair is read out of the world FIRST: the second closure borrows `world` for the
-    // chat-cache restore, and a `Copy` of two bools costs nothing next to fighting that borrow.
-    // Absent in a bare test world, where "both off" is also the resource's own default.
+    // The minimap zoom pair and the plate pair are read out of the world FIRST: the bracket's body
+    // borrows `world` for the chat-cache restore, and two `Copy` pairs cost nothing next to
+    // fighting that borrow. The plates are absent in a bare test world, where "both off" is also
+    // the resource's own default.
+    let zoom = {
+        let z = world.resource::<crate::minimap::MinimapZoom>();
+        (z.outdoor, z.inside)
+    };
     let plates = world
         .get_resource::<crate::vplates::VPlateMode>()
         .copied()
         .unwrap_or_default();
-    finish_ui_load_with(
-        &mut script,
-        // `NAMEPLATES_ON` / `FRIENDNAMEPLATES_ON` (2132). This seat, and not the `Update` feed
-        // beside it, is what fixes the bug: `UIParent_OnEvent`'s first `UpdateNameplates()` runs
-        // inside the `VARIABLES_LOADED` fired at the end of this very call.
-        |script| crate::vplates::push_plate_globals(script, plates),
-        |script| {
-            crate::ui_chat::restore_chat_looks(world, script);
-        },
-    );
+    // **The whole load edge is silent** — the TOC walk, every addon, the saved variables and
+    // `PLAYER_LOGIN`, the span `0x48fbf0` brackets itself across (`0x48fbfa` → `0x49016d`). Both
+    // login and `ReloadUI` come through here; see [`silenced_ui_load`].
+    silenced_ui_load(&mut script, |script| {
+        let _ = load_ingame_ui(script, identity.as_ref(), &roster, version_check);
+        // The Minimap widget was born a moment ago with `MinimapState::default()`; seed its two
+        // live zoom indices from the persisted CVars now, before anything reads them — the
+        // reference's own minimap reset path copying each CVar object's int into its live index
+        // (decision 1131). Once only: from here the widget's index is the live truth and
+        // `Minimap:SetZoom` writes the CVar back. Startup always precedes this state edge (1038),
+        // so the knob is already loaded.
+        script.set_minimap_zoom(zoom.0, zoom.1);
+        // The saved-variables chunk runs HERE — after the XML assigned its file-scope defaults,
+        // before any consumer reads them — then `VARIABLES_LOADED`. That is the reference's own
+        // load order (`AddOn_Load 0x51f240` steps 2 → 4 → 6, decision 1128); reversing it means the
+        // defaults always win and nothing can ever be remembered.
+        //
+        // **And the chat cache restores inside it, between `VARIABLES_LOADED` and `PLAYER_LOGIN`**
+        // — the reference's own slot for the reader's `UPDATE_CHAT_WINDOWS` + `UPDATE_CHAT_COLOR`
+        // burst (`0x4900d6`, after `0x4900b2` and before `0x490959`; decisions 2119 and 2125). It
+        // is the sole firer of `UPDATE_CHAT_WINDOWS`, which is the only thing that registers a chat
+        // frame for any `CHAT_MSG_*` (ref `ChatFrame.lua` l.1261-1273) — as an `Update` system it
+        // landed after the session's first chat had already been routed, and the login MOTD went to
+        // a window registered for nothing.
+        finish_ui_load_with(
+            script,
+            // `NAMEPLATES_ON` / `FRIENDNAMEPLATES_ON` (2132). This seat, and not the `Update`
+            // feed beside it, is what fixes the bug: `UIParent_OnEvent`'s first
+            // `UpdateNameplates()` runs inside the `VARIABLES_LOADED` fired at the end of this
+            // very call.
+            |script| crate::vplates::push_plate_globals(script, plates),
+            |script| {
+                crate::ui_chat::restore_chat_looks(world, script);
+            },
+        );
+    });
     // **Say it out loud when an addon didn't load** (decision 1495). Every failure the walk found
     // is retained now, but a log nobody knows to open does not fix silence — and silence is the
-    // actual defect B293 reports: *"there are a lot of addons that still doesn't work"*, with
-    // nothing on screen to say which or why. Counted off the retained log rather than the walk's
+    // actual defect: addons that do not load, with nothing on screen to say which or why. Counted
+    // off the retained log rather than the walk's
     // `failures` vec so the number matches what `/errors` will show: the log deduplicates, and one
     // broken addon that fails four files should not read as four broken addons. The VM is fresh
     // per world entry, so every `Load` row here is this load's.
@@ -755,8 +773,7 @@ pub(crate) fn seat_from_roster(
         // lua_pushnil`. `UnitLevel 0x517fc0` likewise carries no `"player"` compare at all and
         // reaches its total-miss arm `0x51813e push 0; push 0` — the **number 0**, not nil. The
         // two misses are deliberately asymmetric and a client that modelled "no data" uniformly
-        // would be wrong on one of them (wow-re `ui/scratch/unit-verbs-before-player-object.md`
-        // §2-§3; it also corrected that repo's own `main`, which had published the opposite).
+        // would be wrong on one of them.
         //
         // This seat is no longer what makes the player *answerable* — the record above is — so it
         // no longer has to claim a unit exists in order to deliver a name. What it still carries
@@ -846,20 +863,17 @@ pub(crate) fn arm_leaving_world_on_self_create(
     }
 }
 
-/// **The UI shutdown, in the reference's own order** — `0x490bd0`, whose ordered tail wow-5875-re
-/// carves as (`system/ui/ui.md`):
+/// **The UI shutdown, in the reference's own order** — `0x490bd0`, whose ordered tail is:
 ///
 /// > `PLAYER_LEAVING_WORLD` (273) → **`PLAYER_LOGOUT`** (271, `0x490c2a`) → `layout-cache.txt` →
 /// > **the flat saved file** (`0x490c7e`) → **the per-addon files** (`0x490c83`) → `AddOns.txt`
 /// > (`0x490c88`) → destroy the frame-script owner (`0x490c97`) → nil all 216 C bindings out of
 /// > `_G` (`0x490cba` → `0x490ce0`)
 ///
-/// **The last step is not "destroy the Lua state"** — which is what three of wow-re's own notes
-/// said, until this client's teardown made the question load-bearing and a §5 cross-check settled
-/// it (`system/ui/scratch/lua-state-lifecycle.md`; 2277). `0x490c97` is the frame-script owner's
+/// **The last step is not "destroy the Lua state"** (2277). `0x490c97` is the frame-script owner's
 /// scalar-deleting destructor — the widget tree and the native virtual-font registry — and the Lua
 /// state outlives it. The state is closed and re-opened at `0x703b80`, which reaches `InitLua` by a
-/// **tail-`jmp`** (`0x703b8e`) rather than a call, which is exactly why a call-census missed it.
+/// **tail-`jmp`** (`0x703b8e`) rather than a call, which is exactly why a call-census misses it.
 /// Its three callers are `UI_Init 0x48fbf0` (at its *head*), `ShutdownGame 0x491180`, and the glue
 /// builder `0x46a7b0` — so a logout/login cycle runs through four distinct states, and the glue
 /// screen gets its own.
@@ -953,7 +967,7 @@ pub(crate) fn end_ui_session(world: &mut World) {
     // that lands in an engine-side store that survives), before the VM is replaced. The next
     // VM's registration seeds from what this writes ([`crate::cvars`]'s saved base).
     crate::cvars::fold_dying_vm_cvars(world);
-    // The chat cache, on the same terms and for the same reason (decision NNNN): it composes the
+    // The chat cache, on the same terms and for the same reason (decision 2184): it composes the
     // player's file out of the DYING VM, and `/reload` never crosses the `OnExit(InWorld)` edge
     // its flush used to hang on — so a window moved in the last second before a reload was
     // written nowhere and re-read stale from disk.
@@ -1070,9 +1084,7 @@ pub(crate) fn shutdown_on_exit(
 /// The UI-init sequence's ordered tail, once every file — ours and every addon's — has loaded:
 /// the saved-variables chunk and `VARIABLES_LOADED`, then `PLAYER_LOGIN`.
 ///
-/// **The order is the reference's**, byte-verified in wow-5875-re (`system/ui/ui.md`, and the
-/// cascade in `system/ui/scratch/mail-pending-countdown.md`). Inside `UI_Init 0x48fbf0`, in
-/// straight-line address order:
+/// **The order is the reference's**. Inside `UI_Init 0x48fbf0`, in straight-line address order:
 ///
 /// | | |
 /// |---|---|
@@ -1086,7 +1098,7 @@ pub(crate) fn shutdown_on_exit(
 /// and a window that waits on `PLAYER_LOGIN` expects both — so it is worth being able to assert.
 ///
 /// **The third row does not run on a fresh login, and this doc used to say it did** (corrected
-/// 2226; the claim came from 1348 and was re-checked in wow-5875-re against the bytes). The call
+/// 2226; the claim came from 1348 and was re-checked against the bytes). The call
 /// at `0x490168` is gated three instructions earlier:
 ///
 /// ```text
@@ -1106,8 +1118,8 @@ pub(crate) fn shutdown_on_exit(
 /// resolved.** Our `finish_ui_init` fires the cascade inside the load, which matches the reload
 /// case and not the fresh-login one; whether to split those is its own change with its own
 /// measurements, and 2226 (which was about the VM's identity, not the cascade's timing) is not it.
-/// wow-re's own `DEFERRED:` entry — which of `0x4908c0`'s two data-dependent entries fires first on
-/// a real login — is still open, so the target shape is not yet known.
+/// Which of `0x4908c0`'s two data-dependent entries fires first on a real login is still open, so
+/// the target shape is not yet known.
 ///
 /// **`PLAYER_LOGIN` is the conditional one; `PLAYER_ENTERING_WORLD` is not.** The cascade fires
 /// the former only when `[0xb4e260]` is set, and only the FrameXML-loader path sets it, clearing
@@ -1130,8 +1142,7 @@ pub(crate) fn finish_ui_load(script: &mut UiScript) {
 /// The reference's login is `FrameXML → addons + ADDON_LOADED (0x4900a3) → VARIABLES_LOADED
 /// (0x4900b2) → the chat-cache reader's burst (0x4900d6, firing synchronously through the
 /// register-or-fire-now trampoline 0x498a20) → PLAYER_LOGIN (0x490959) → PLAYER_ENTERING_WORLD
-/// (0x49096a)` — byte-derived in wow-re `system/ui/scratch/login-chat-colour-pipeline.md`, §5
-/// cross-checked. 2119 put the restore ahead of `VARIABLES_LOADED`, which is one step too early:
+/// (0x49096a)`. 2119 put the restore ahead of `VARIABLES_LOADED`, which is one step too early:
 /// an addon reading its chat colours out of a `VARIABLES_LOADED` handler would see the file's
 /// values where the reference shows it the boot ones.
 ///
@@ -1402,7 +1413,7 @@ mod tests {
         // …and the pair every `Instant`→`GetTime` conversion runs through moved with it: a
         // 10-minute cooldown armed 30 s before the rebuild still derives its real start.
         let clock = world.resource::<UiClock>();
-        let armed = crate::cooldowns::CooldownInfo {
+        let armed = crate::spell::cooldowns::CooldownInfo {
             start: startup + Duration::from_secs(60),
             remaining_ms: 570_000,
             duration_ms: 600_000,
diff --git a/crates/benilla-app/src/ui_script/loot_tests.rs b/crates/benilla-app/src/ui_script/loot_tests.rs
index 41e3b654..229a4906 100644
--- a/crates/benilla-app/src/ui_script/loot_tests.rs
+++ b/crates/benilla-app/src/ui_script/loot_tests.rs
@@ -90,6 +90,7 @@ fn coin_and_two_items() -> LootState {
 /// close button releases through OnHide → CloseLoot.
 #[test]
 fn shipped_loot_frame_drives_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -283,6 +284,7 @@ fn shipped_loot_frame_drives_end_to_end() {
 /// rare — but the branch must exist, and this proves it fires the right kit and only then.
 #[test]
 fn loot_empty_roll_plays_the_empty_open_kit() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -324,6 +326,7 @@ fn loot_empty_roll_plays_the_empty_open_kit() {
 /// the next ordinary open resets the skull (the ref re-stamps TargetDead at every show, l.133).
 #[test]
 fn fishing_loot_open_plays_the_reel_and_swaps_the_portrait() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -375,6 +378,7 @@ fn fishing_loot_open_plays_the_reel_and_swaps_the_portrait() {
 /// pager on page 2 — the real shipped XML driving the render, not just the arithmetic.
 #[test]
 fn shipped_loot_frame_pages_five_items() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -472,6 +476,7 @@ fn shipped_loot_frame_pages_five_items() {
 /// the synthetic stand-in the merchant panel test uses.
 #[test]
 fn shipped_loot_pushed_to_center_by_merchant() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -549,6 +554,7 @@ fn shipped_loot_pushed_to_center_by_merchant() {
 /// frames (`SetFrameStrata 0x76a470` is a whole-subtree cascade).
 #[test]
 fn the_loot_window_draws_over_the_party_frames() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -602,6 +608,7 @@ fn the_loot_window_draws_over_the_party_frames() {
 /// unmodified click still loots — the regression that would otherwise ship silently.
 #[test]
 fn ctrl_and_shift_on_a_loot_row_preview_and_post_without_looting() {
+    benilla_formats::wow_data_or_skip!();
     const WOOL_LINK: &str = "|cffffffff|Hitem:2589:0:0:0|h[Wool Cloth]|h|r";
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
@@ -750,6 +757,7 @@ fn ctrl_and_shift_on_a_loot_row_preview_and_post_without_looting() {
 /// out and an epic asks. The misspelling is the reference's own (`LootFrame.lua:3`).
 #[test]
 fn shipped_loot_frame_hands_a_master_row_to_a_candidate() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -881,7 +889,7 @@ fn shipped_loot_frame_hands_a_master_row_to_a_candidate() {
     );
 }
 
-/// **The raid arm of the master-loot menu** (decision 1675) — the half the wow-re §5 corrected.
+/// **The raid arm of the master-loot menu** (decision 1675).
 ///
 /// In a raid the candidate array is not the wire order: the client files each candidate into its
 /// own subgroup's five-slot block, leaving holes. `GroupLootDropDown_Initialize` reads those holes
@@ -890,6 +898,7 @@ fn shipped_loot_frame_hands_a_master_row_to_a_candidate() {
 /// the menu that comes out, which a densely-packed list could not produce.
 #[test]
 fn the_master_loot_menu_groups_raid_candidates_by_subgroup() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::{PartyState, RaidMemberInfo};
 
     let mut s = UiScript::new().unwrap();
@@ -973,6 +982,7 @@ fn the_master_loot_menu_groups_raid_candidates_by_subgroup() {
 /// take. Cancel sends nothing at all, and `LOOT_CLOSED` takes the dialog down with the window.
 #[test]
 fn the_loot_bind_confirm_raises_the_dialog_and_okay_calls_loot_slot() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -1060,6 +1070,7 @@ fn the_loot_bind_confirm_raises_the_dialog_and_okay_calls_loot_slot() {
 /// would sit there doing nothing (decision 1744).
 #[test]
 fn a_row_click_takes_rather_than_continues() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -1098,6 +1109,7 @@ fn a_row_click_takes_rather_than_continues() {
 /// `ITEM_QUALITY_COLORS[-1]`, the row `UIParent.lua`'s `for i = -1, 6` exists to provide.
 #[test]
 fn loot_row_awaiting_its_template_opens_clean() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
@@ -1173,7 +1185,7 @@ fn loot_row_awaiting_its_template_opens_clean() {
     // It is a REOPEN and not a repaint on purpose. The app fires `LOOT_UPDATE` when an open
     // window's content changes, and `LOOT_UPDATE` is not a 1.12 event — it appears nowhere in the
     // reference's FrameXML and `LootFrame_OnLoad` does not register it — so nothing in the stock
-    // file listens. What the real client does when a template arrives mid-window is out at wow-re
+    // file listens. What the real client does when a template arrives mid-window is still open
     // (the arrival callback `0x4c2ac0` is recorded as clearing the pending flag and nothing else);
     // this test deliberately asserts only what is settled.
     s.fire_event("LOOT_CLOSED", vec![]);
@@ -1209,13 +1221,13 @@ fn loot_row_awaiting_its_template_opens_clean() {
 /// `<PushedTexture>` and no `<HighlightTexture>` at all: no Quickslot border on the icons, and
 /// nothing to light under the mouse. The gate is wrong about the reference: `CLootButton`'s
 /// geometry vtable differs from `CSimpleButton`'s in exactly one slot — the destructor thunk — and
-/// `LoadXML` is not it, so `0x7788c0` parses a `<LootButton>` element verbatim (wow-re
-/// `ui/scratch/lootbutton-widget-type.md` §4).
+/// `LoadXML` is not it, so `0x7788c0` parses a `<LootButton>` element verbatim.
 ///
 /// Asserted through the ENGINE's hover path rather than off the state: what a player sees is the
 /// emitted quad, and the quad is what was missing.
 #[test]
 fn stock_loot_rows_wear_the_item_button_art_and_light_under_the_cursor() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::LOOT_UI {
diff --git a/crates/benilla-app/src/ui_script/macro_tests.rs b/crates/benilla-app/src/ui_script/macro_tests.rs
index 7117f220..bec71aca 100644
--- a/crates/benilla-app/src/ui_script/macro_tests.rs
+++ b/crates/benilla-app/src/ui_script/macro_tests.rs
@@ -641,8 +641,8 @@ fn the_tab_highlight_is_exactly_its_tab() {
                 // **The two tabs carry DIFFERENT highlight widths, and that is the reference's,
                 // not a loader bug.** Exactly one `<OnLoad>` runs — the most-derived one; the
                 // template's is installed and then *destroyed*, because `SetScript` releases the
-                // slot's single ref before it even looks at the new body (wow-re
-                // `template-onload-replacement-law.md`). So a tab gets whichever formula ITS OWN
+                // slot's single ref before it even looks at the new body (`0x7025ec`). So a tab
+                // gets whichever formula ITS OWN
                 // body ends with:
                 //
                 //   * tab 2's body is just `PanelTemplates_TabResize(-15, nil, nil, 150)`, whose
diff --git a/crates/benilla-app/src/ui_script/manifest.rs b/crates/benilla-app/src/ui_script/manifest.rs
index a16eead3..71482e5e 100644
--- a/crates/benilla-app/src/ui_script/manifest.rs
+++ b/crates/benilla-app/src/ui_script/manifest.rs
@@ -150,6 +150,69 @@ pub(super) fn apply_buff_durations(script: &UiScript) -> Result<(), String> {
         .map_err(|e| e.to_string())
 }
 
+/// **What a screen-size change re-runs** — called from `extract::tick_script`'s resize arm, the
+/// frame [`UiScript::set_screen_size`] reports a change on. Anchors follow the new screen rect by
+/// themselves; what does not is a size or seat somebody COMPUTED from the old one.
+///
+/// The bottom-stack manage pass (decision 1499): the open-bag stack starts a fresh column when
+/// the current one would run off the top, and that decision is made from `GetScreenHeight()` at
+/// layout time. Without this, dragging the window smaller leaves the bag columns wrapped for the
+/// old height until the next bag opens. Existence-guarded: the pass is defined by `UIParent.xml`,
+/// which is in-game UI, and the resize arm also runs on the glue screens.
+///
+/// **And the three full-screen quads the stock files size once** — a stated repair of a reference
+/// gap, in the same posture as [`install_durability_reseat`]: nothing of Blizzard's is edited.
+/// `WorldMapFrame_OnLoad` sizes `BlackoutWorld` and `CinematicFrame_OnLoad` sizes
+/// `UpperBlackBar`/`LowerBlackBar` from `GetScreenWidth()`/`GetScreenHeight()` at load, and no
+/// stock handler touches them again (no `DISPLAY_SIZE_CHANGED` listener) — the reference could
+/// afford that because its screen changed only across a restart. 2242 fixed the load edge; this
+/// is the other edge: after a window resize or a `uiScale` change the blackout stopped short of
+/// the new screen and the world showed through beside the map. [`FULLSCREEN_QUADS_RESEAT`] is the
+/// two OnLoads' own arithmetic re-run, so a quad after a resize is exactly what a fresh load at
+/// the new size would have made. A stateless chunk rather than an installed hook, so a `ReloadUI`
+/// has nothing to re-install and nothing can stack.
+pub(super) fn on_screen_resized(script: &UiScript) {
+    let _ = script.run("if UIParent_ManageFramePositions then UIParent_ManageFramePositions() end");
+    if let Err(e) = script.run(FULLSCREEN_QUADS_RESEAT) {
+        error!("ui_script: full-screen quad re-seat: {e}");
+    }
+}
+
+/// `WorldMapFrame.lua` `WorldMapFrame_OnLoad` l.19-28 and `CinematicFrame.lua`
+/// `CinematicFrame_OnLoad` l.5-19, verbatim in their arithmetic, each existence-guarded (the
+/// glue screens have neither). One addition to the letterbox: the stock OnLoad does nothing below
+/// 4:3, which leaves the bars at `CinematicFrame.xml`'s declared `1024 x 128` — so a resize to
+/// below 4:3 puts that declared size back, rather than keeping a wide screen's recompute.
+const FULLSCREEN_QUADS_RESEAT: &str = r#"
+if BlackoutWorld then
+    local width = GetScreenWidth()
+    local height = GetScreenHeight()
+    if ( width / height < 4 / 3 ) then
+        width = width * 1.25
+        height = height * 1.25
+    end
+    BlackoutWorld:SetWidth( width )
+    BlackoutWorld:SetHeight( height )
+end
+if UpperBlackBar and LowerBlackBar then
+    local width = GetScreenWidth()
+    local height = GetScreenHeight()
+    local barWidth, blackBarHeight = 1024, 128
+    if ( width / height > 4 / 3 ) then
+        local desiredHeight = width / 2
+        if ( desiredHeight > height ) then
+            desiredHeight = height
+        end
+        barWidth = width
+        blackBarHeight = ( height - desiredHeight ) / 2
+    end
+    UpperBlackBar:SetHeight( blackBarHeight )
+    UpperBlackBar:SetWidth( barWidth )
+    LowerBlackBar:SetHeight( blackBarHeight )
+    LowerBlackBar:SetWidth( barWidth )
+end
+"#;
+
 /// **A stated divergence from the reference, installed rather than edited in** (1751 window 4).
 ///
 /// The reference seats `DurabilityFrame` 20 further in when one of its three side glyphs is up
@@ -186,6 +249,34 @@ if DurabilityFrame and not DurabilityFrame.benillaReseat then
 end
 "#;
 
+/// **The UI load's sound-suppression bracket — the one site both load paths go through.**
+///
+/// `CGGameUI::Initialize 0x48fbf0` brackets ITSELF in the counted suppression scope —
+/// `0x48fbfa call 0x458f50` on entry, `0x49016d call 0x458f60` on exit — across the TOC walk,
+/// Bindings.xml, the AddOns, the saved variables and the world-enter cascade it calls at
+/// `0x490168` (`PLAYER_LOGIN`), so both of its callers (login `0x48f681` and `/reloadui`
+/// `0x495669`) load without a sound. The only reader of that depth is `PlaySoundByName
+/// 0x458030`, which drops the call outright.
+///
+/// This is the mechanism, not a workaround for one noisy handler: stock `TargetFrame_OnHide`
+/// really does fire at load (the frame ships shown and its OnLoad hides it) and really does call
+/// `PlaySound("INTERFACESOUND_LOSTTARGETUNIT")`. The engine throws it away. Decision 1033 reached
+/// the right rule from the director's ear; this is the binary agreeing.
+///
+/// One function rather than a push/pop pair at each caller because the production edge
+/// ([`super::load_ingame_ui_on_world_entry`]) spent its life unbracketed while the tests' whole-
+/// manifest load was — every `/reload` played the lost-target click. Generic over the borrow so
+/// the `&UiScript` test loader and the owning production edge share it.
+pub(super) fn silenced_ui_load<S: std::borrow::Borrow<UiScript>, R>(
+    script: &mut S,
+    body: impl FnOnce(&mut S) -> R,
+) -> R {
+    script.borrow().push_sound_suppression();
+    let out = body(script);
+    script.borrow().pop_sound_suppression();
+    out
+}
+
 /// Load benilla's own default UI — every file [`MANIFEST`] names — through the engine-free loader.
 /// This is our content (MIT/Apache), committed and **compiled into the binary**
 /// ([`super::content`], decision 1175); a dev build still prefers the copy on disk, so editing a
@@ -219,20 +310,12 @@ pub(crate) fn load_default_ui(script: &UiScript) -> Vec<String> {
     // have been registered here with real consumers since 1493/1502; the probes simply never had
     // them, and 218 tests found that out the hour this row went on the manifest.
     script.register_cvars(crate::cvars::registered_pairs());
-    // **Silent, the way the client's own load is.** `0x48fbf0` brackets ITSELF in the counted
-    // sound-suppression scope — `0x48fbfa call 0x458f50` on entry, `0x49016d call 0x458f60` on
-    // exit — across the TOC walk, Bindings.xml and the AddOns, so both of its callers (login
-    // `0x48f681` and `/reloadui` `0x495669`) load without a sound. The only reader of that depth
-    // is `PlaySoundByName 0x458030`, which drops the call outright.
-    //
-    // This is the mechanism, not a workaround for one noisy handler: stock `TargetFrame_OnHide`
-    // really does fire at load (the frame ships shown and its OnLoad hides it) and really does
-    // call `PlaySound("INTERFACESOUND_LOSTTARGETUNIT")`. The engine throws it away. Decision 1033
-    // reached the right rule from the director's ear; this is the binary agreeing.
-    script.push_sound_suppression();
-    let mut failures = load_manifest(script, &Addon::builtin().toc.files);
-    failures.extend(bootstrap_positions(script));
-    script.pop_sound_suppression();
+    // Silent, the way the client's own load is — see [`silenced_ui_load`].
+    let mut failures = silenced_ui_load(&mut &*script, |script| {
+        let mut failures = load_manifest(script, &Addon::builtin().toc.files);
+        failures.extend(bootstrap_positions(script));
+        failures
+    });
     // **A handler that raised DURING the walk is a load failure.** The loader's own report holds
     // the raises it dispatched itself (a `<Script file=>` chunk, an OnLoad); a raise one call
     // deeper — an OnLoad that `Show()`s a frame whose OnShow indexes a global its file has not
@@ -296,15 +379,17 @@ pub(crate) fn load_font_registry(script: &UiScript) -> Vec<String> {
 /// The reference does the same at `CGGameUI::Initialize 0x48fbf0`, reached only from world entry
 /// (`0x401570` ← `0x46c236`), and loads its addons from that same function (`0x4900a3` →
 /// `0x51f600`); its glue screens run GlueXML with their own `GlueFonts.xml` registry, which is why
-/// the reference has no equivalent of our shared-atlas coupling (wow-5875-re, 1051).
+/// the reference has no equivalent of our shared-atlas coupling (1051).
 ///
 /// Addons load **after** the built-in interface, not interleaved with it: an addon may reference
 /// our templates and globals (that is the point of 1178's seam), and nothing of ours may depend on
 /// an addon.
 ///
 /// `identity` is `(realm, character)`, which names this character's AddOn enable-state file — the
-/// reference keys `AddOns.txt` per character too. `None` (no pick yet, a capture) means every
-/// discovered addon is enabled, the same answer an absent file gives.
+/// reference keys `AddOns.txt` per character too — and `roster` is every character on that realm's
+/// list, which is the enable store's node set (decision 2311: an addon this character has no row
+/// for is resolved from what the *other* characters said, never from a bare "enabled"). `None`
+/// with an empty roster is the no-pick case: every addon falls to its own `## DefaultState`.
 ///
 /// `version_check` is the persisted `checkAddonVersion` — the *Load out of date AddOns* toggle,
 /// inverted — resolved by the caller because at load time this VM's own CVar table does not
@@ -314,6 +399,7 @@ pub(crate) fn load_font_registry(script: &UiScript) -> Vec<String> {
 pub(crate) fn load_ingame_ui(
     script: &mut UiScript,
     identity: Option<&(String, String)>,
+    roster: &[String],
     version_check: bool,
 ) -> Vec<String> {
     // The whole load edge runs bounded (decision 1306): the reference files sourced off the
@@ -332,6 +418,7 @@ pub(crate) fn load_ingame_ui(
     failures.extend(super::addons::load_third_party(
         script,
         identity,
+        roster,
         version_check,
     ));
     failures
diff --git a/crates/benilla-app/src/ui_script/merchant_tests.rs b/crates/benilla-app/src/ui_script/merchant_tests.rs
index 4b195f40..320e6422 100644
--- a/crates/benilla-app/src/ui_script/merchant_tests.rs
+++ b/crates/benilla-app/src/ui_script/merchant_tests.rs
@@ -48,6 +48,7 @@ fn frame_rect(quads: &[ExtractedQuad], w: f32, h: f32) -> benilla_ui::layout::Re
 /// intent, and MERCHANT_CLOSED hiding it through HideUIPanel, vacating the left slot.
 #[test]
 fn shipped_merchant_frame_drives_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // The named virtual Font objects the re-skinned rows/title inherit through — loaded first at
@@ -338,6 +339,7 @@ fn shipped_merchant_frame_drives_end_to_end() {
 /// → Hide() fires OnHide. Nothing queues at load (the frame is authored hidden="true").
 #[test]
 fn merchant_show_hide_plays_open_and_close_kits() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::MERCHANT_UI {
@@ -528,6 +530,7 @@ fn vendor_opens_and_closes_all_equipped_bags() {
 /// doesn't clear the vendor it just re-opened to.
 #[test]
 fn merchant_switch_plays_close_then_open_and_queues_the_consumable_close() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::MERCHANT_UI {
@@ -571,6 +574,7 @@ fn merchant_switch_plays_close_then_open_and_queues_the_consumable_close() {
 /// with no buy-price line (the price is on the row). Leaving the row hides it all.
 #[test]
 fn shipped_merchant_hover_scopes_highlight_and_anchors_item_tooltip() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // The stock tooltip declares no size: it sizes from its lines through the font engine, as
@@ -824,6 +828,7 @@ fn shipped_merchant_hover_scopes_highlight_and_anchors_item_tooltip() {
 /// queue the BuybackItem/RepairAllItems intents the app drains.
 #[test]
 fn merchant_tabs_drive_buyback_page_and_repair_pair() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::MERCHANT_UI {
@@ -954,6 +959,7 @@ fn merchant_tabs_drive_buyback_page_and_repair_pair() {
 /// configuration the app does not have.
 #[test]
 fn merchant_tabs_fit_their_labels() {
+    benilla_formats::wow_data_or_skip!();
     /// `2 * $parentLeft:GetWidth()` — the template's two 20-unit end slices.
     const SIDES: f64 = 40.0;
     let mut s = UiScript::new().unwrap();
@@ -992,6 +998,7 @@ fn merchant_tabs_fit_their_labels() {
 /// the frame's `OnUpdate` (a `tick`) exactly as the app does, since the coin is re-armed per frame.
 #[test]
 fn shipped_merchant_frame_arms_the_buy_cursor_on_hover() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::UiCursorMode;
 
     let mut s = UiScript::new().unwrap();
@@ -1088,6 +1095,7 @@ fn shipped_merchant_frame_arms_the_buy_cursor_on_hover() {
 /// ellipsis. If this FAILS, the bug is structural and reproduced here; if it PASSES, it is live-only.
 #[test]
 fn trade_recipient_money_renders_the_digit_not_ellipsis() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for f in super::test_ui::MERCHANT_UI {
@@ -1146,6 +1154,7 @@ fn trade_recipient_money_renders_the_digit_not_ellipsis() {
 /// right-button guard, l.332-333) a CTRL-held right-click buys nothing at all.
 #[test]
 fn ctrl_and_shift_on_a_vendor_row_preview_and_post_without_buying() {
+    benilla_formats::wow_data_or_skip!();
     const WATER_LINK: &str = "|cffffffff|Hitem:159:0:0:0|h[Refreshing Spring Water]|h|r";
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
@@ -1179,7 +1188,7 @@ fn ctrl_and_shift_on_a_vendor_row_preview_and_post_without_buying() {
             num_available: -1,
             item_id: 159,
             stats: None,
-            // Fed exactly as `ui_merchant.rs` builds it off the row's template answer.
+            // Fed exactly as `ui_merchant` builds it off the row's template answer.
             link: Some(WATER_LINK.into()),
             max_stack: Some(1),
         }],
diff --git a/crates/benilla-app/src/ui_script/minimap_tests.rs b/crates/benilla-app/src/ui_script/minimap_tests.rs
index 101d0db7..17bc8f91 100644
--- a/crates/benilla-app/src/ui_script/minimap_tests.rs
+++ b/crates/benilla-app/src/ui_script/minimap_tests.rs
@@ -305,7 +305,7 @@ fn a_click_on_the_minimap_parks_a_centre_relative_ping_request() {
 }
 
 /// `Minimap:GetPingPosition()` answers **two numbers always** (the reference recomputes them
-/// from statics nothing clears — wow-re `minimap-ping-law.md`), and the stock
+/// from statics nothing clears — `0x4eefd0`), and the stock
 /// `Minimap_OnUpdate` leans on exactly that: while its 5 s timer runs it multiplies the answer
 /// with no nil test. The pair is the app's last publish, `(0, 0)` before any.
 #[test]
@@ -448,7 +448,7 @@ fn the_meeting_stone_icon_follows_the_queue_across_meetingstone_changed() {
 
 /// **The ping's pixels are the stock `<Model>`'s own file** (decision 2008): shown by
 /// `MINIMAP_PING` with the file's facts landed, the extract publishes ONE tile request for the
-/// pane — at its device size, the render law's unit ladder, and the composite's rect/key/alpha
+/// pane — at its device size, the reference's unit ladder, and the composite's rect/key/alpha
 /// — and pushes no quad of its own. Once the renderer has handed back a cell, the cell draws as
 /// one premultiplied quad over the pane's rect **on the very next frame, with nothing else in
 /// the interface moving** (decision 2023): the composite is the renderer's per-frame output in
diff --git a/crates/benilla-app/src/ui_script/mod.rs b/crates/benilla-app/src/ui_script/mod.rs
index 8e373bf1..5983fb17 100644
--- a/crates/benilla-app/src/ui_script/mod.rs
+++ b/crates/benilla-app/src/ui_script/mod.rs
@@ -180,7 +180,7 @@ pub(crate) struct PlayerUiHover(pub(crate) Option<u32>);
 
 /// **Who owns this frame's keys** — written by [`feed_ui_input`], read by the binding dispatch and the
 /// dev keyboard readers, all of which are ordered after `UiInput` so they see this frame's value and
-/// not last frame's. The app-side twin of the client's `DAT_00cf4dc8 != 0` gate (RF-0082 §1).
+/// not last frame's. The app-side twin of the client's `DAT_00cf4dc8 != 0` gate.
 ///
 /// **Two fields because the reference has two mechanisms, and collapsing them into one boolean was
 /// bug 2196.** A focused EditBox swallows *every* key for as long as it holds focus
@@ -189,7 +189,7 @@ pub(crate) struct PlayerUiHover(pub(crate) Option<u32>);
 /// and nothing more. Neither releases anything already held: the only things that clear the
 /// reference's direction bits are the OS **window deactivate** (`0x514490`, whose sole caller
 /// `0x493058` hangs off the WM_ACTIVATE callback slot) and the world-enter cascade (`0x5144c0`).
-/// A UI focus change clears nothing — wow-re `rf79-autorun-cancel-set.md`, and the reason holding
+/// A UI focus change clears nothing — the reason holding
 /// W keeps you running while you type or read the map. See `decisions/2196`.
 #[derive(Resource, Default)]
 pub(crate) struct UiKeyboardCapture {
@@ -197,7 +197,7 @@ pub(crate) struct UiKeyboardCapture {
     /// the alt-arrow one below). Whole-frame, because there is at most one focused box.
     pub(crate) typing: bool,
     /// The keys a shown keyboard-enabled **frame** consumed this frame (decision 1319's existence
-    /// gate, wow-re `frame-key-script-delivery.md` §3) — `WorldMapFrame`'s fullscreen `OnKeyDown`,
+    /// gate, `0x76b7d0`) — `WorldMapFrame`'s fullscreen `OnKeyDown`,
     /// `CinematicFrame`, the stack-split spinner. **Per key, not per frame**: the map eating its
     /// own `M` must not also suppress an unrelated binding, and — the bug this list exists for —
     /// must not be mistaken for a text box taking focus.
@@ -209,7 +209,7 @@ pub(crate) struct UiKeyboardCapture {
     /// (`ignoreArrows` / `SetAltArrowKeyMode`) and ALT is not held, so the reference's own key
     /// handler declines LEFT/UP/RIGHT/DOWN at `0x77b1c4` and the strata walk carries them down to
     /// `CGWorldFrame`, which runs their bindings. That is what lets you turn while the chat box
-    /// has focus (wow-re `ignorearrows-alt-arrow-gate.md`, §5 VERIFIED).
+    /// has focus.
     ///
     /// It is a whole-frame flag rather than a per-key one because both of its terms are:
     /// there is at most one focused box, and ALT is read off the same modifier mirror. Only the
@@ -384,8 +384,8 @@ impl Default for UiScaleCvar {
 /// director's eye — the taste call this dial exists for).
 ///
 /// **It also happens to be what the reference itself lands on above ~853 px tall**, which we did
-/// not know when it was chosen (wow-re `system/ui/scratch/modelframe-uiscale-law.md`, out of the
-/// autocast-shine thread): `0x492f70` computes `max((H > 768) ? 768/H : 1.0, 0.9)` and is called
+/// not know when it was chosen: `0x492f70` computes
+/// `max((H > 768) ? 768/H : 1.0, 0.9)` and is called
 /// **both** on a mode set and from the `useUiScale`-OFF leg (`0x4908ad`) — and OFF is the shipped
 /// default (`0x8430c0` = `"0"`). So the reference is 1.0 at 768 and below, 0.96 at 1280×800, and
 /// **0.9 at 1080p and 1440p**. Our flat 0.9 therefore agrees with it on every modern window and
@@ -457,6 +457,7 @@ impl Plugin for UiScriptPlugin {
             // the hover recorder is armed; the producer owns the resource so any minimal app that
             // runs the UI pass (the extract tests) has it.
             .init_resource::<UiFrameCost>()
+            .init_resource::<crate::bindings::WheelNotches>()
             .init_resource::<UiCostWanted>()
             .init_resource::<PointerOverUi>()
             .init_resource::<SyntheticPointer>()
@@ -932,7 +933,7 @@ impl benilla_ui::script::TextMeasure for FixedWidthFont {
 #[cfg(test)]
 pub(crate) mod test_ui;
 
-/// The chat loader's two login events (wow-re chat-cache-grammar.md §8; `ui_chat::settings`):
+/// The chat loader's two login events (`0x498a60`; `ui_chat::settings`):
 /// `UPDATE_CHAT_WINDOWS` once, then `UPDATE_CHAT_COLOR` for every registry entry. The reference's
 /// `FloatingChatFrame_Update` docks, hides and colours the windows on the first and
 /// `ChatFrame_OnEvent` fills `ChatTypeInfo` from the second, so a test VM that loads the
@@ -1178,10 +1179,6 @@ mod duel_tests;
 #[cfg(test)]
 mod enchant_confirm_tests;
 
-/// The shared reference-geometry diff (decision 0675) every transcribed window's test calls.
-#[cfg(test)]
-mod framexml_diff;
-
 /// Its FLAG twin (decision 1739): the whole-tree sweep for `toplevel`/mouse/`id` against the
 /// reference, read off the loaded engine rather than off our XML.
 #[cfg(test)]
diff --git a/crates/benilla-app/src/ui_script/money_frame_tests.rs b/crates/benilla-app/src/ui_script/money_frame_tests.rs
index 90f496bd..88d8aa1a 100644
--- a/crates/benilla-app/src/ui_script/money_frame_tests.rs
+++ b/crates/benilla-app/src/ui_script/money_frame_tests.rs
@@ -74,6 +74,7 @@ fn shown(s: &UiScript, frame: &str) -> (bool, bool, bool) {
 /// `MoneyFrame_SetType("PLAYER")`.
 #[test]
 fn a_money_frame_loads_as_the_player_purse_and_splits_the_denominations() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(12_345); // 1g 23s 45c
     assert_eq!(
         s.eval::<String>("return TestPurse.moneyType").unwrap(),
@@ -103,6 +104,7 @@ fn a_money_frame_loads_as_the_player_purse_and_splits_the_denominations() {
 /// take the mouse (`canPickup`), and how they collapse.
 #[test]
 fn set_type_rewires_the_source_the_mouse_and_the_collapse() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(12_345);
 
     // PLAYER: canPickup, so all three coins are mouse-enabled.
@@ -151,6 +153,7 @@ fn set_type_rewires_the_source_the_mouse_and_the_collapse() {
 /// STATIC does not, so the same amount is gold alone.
 #[test]
 fn showsmallercoins_is_what_keeps_the_zero_coins_visible() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(50_000); // exactly 5g
 
     assert_eq!(coins(&s, "TestPurse"), ("5".into(), "0".into(), "0".into()));
@@ -182,6 +185,7 @@ fn showsmallercoins_is_what_keeps_the_zero_coins_visible() {
 /// frame's own width is recomputed from the coins that survived the collapse.
 #[test]
 fn update_paints_a_static_frame_by_name_and_resizes_it() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(0);
     s.run("this = TestPurse MoneyFrame_SetType(\"STATIC\") this = nil")
         .unwrap();
@@ -222,6 +226,7 @@ fn update_paints_a_static_frame_by_name_and_resizes_it() {
 /// constants (`MONEY_ICON_WIDTH` / `MONEY_BUTTON_SPACING`), selected purely by `this.small`.
 #[test]
 fn the_large_template_measures_with_the_nineteen_pixel_icon() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(20_304);
     // One 8px digit + the 19px icon — the same digit sum as the small template, over the other
     // icon constant. That the two differ ONLY by the icon is what this test is for.
@@ -249,6 +254,7 @@ fn the_large_template_measures_with_the_nineteen_pixel_icon() {
 /// it had.
 #[test]
 fn an_unknown_money_type_leaves_the_frame_on_the_one_it_had() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(12_345);
     s.run("this = TestPurse MoneyFrame_SetType(\"NOT_A_TYPE\") this = nil")
         .unwrap();
@@ -269,6 +275,7 @@ fn an_unknown_money_type_leaves_the_frame_on_the_one_it_had() {
 /// and not the icons" is actually observable.
 #[test]
 fn set_money_frame_color_recolours_the_digits_and_not_the_icons() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(12_345); // 1g 23s 45c — three distinguishable digit strings
     s.run("SetMoneyFrameColor(\"TestPurse\", 1.0, 0.1, 0.1)")
         .unwrap();
@@ -327,6 +334,7 @@ fn set_money_frame_color_recolours_the_digits_and_not_the_icons() {
 /// their engine getters hold (`GetSendMailMoney`/`GetSendMailCOD`, built by 1962).
 #[test]
 fn the_money_type_table_carries_all_seven_reference_types() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(12_345);
     for t in [
         "PLAYER",
diff --git a/crates/benilla-app/src/ui_script/multibar_stance_tests.rs b/crates/benilla-app/src/ui_script/multibar_stance_tests.rs
index 4d5ec589..36daec44 100644
--- a/crates/benilla-app/src/ui_script/multibar_stance_tests.rs
+++ b/crates/benilla-app/src/ui_script/multibar_stance_tests.rs
@@ -84,6 +84,7 @@ fn show_bars(s: &UiScript, bars: &[u32]) {
 /// about what a bar looks like once the player has asked for it.
 #[test]
 fn shipped_multibars_drive_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -264,9 +265,11 @@ fn shipped_multibars_drive_end_to_end() {
 /// The stance bar (StanceBar.xml) through the REAL shipped XML: hidden at zero forms, sized to
 /// the pushed list (buttons past numForms hide), the checked ring on the active form, the 0.4
 /// grey on a not-castable one, a click queuing the form's spell id, and an emptied push hiding
-/// the whole frame again — the wow-re shapeshift-bar-api mechanism driven end to end.
+/// the whole frame again — the reference's form list (`0xb71100`) and its four bindings driven
+/// end to end.
 #[test]
 fn shipped_stance_bar_drives_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ShapeshiftFormView;
 
     let mut s = UiScript::new().unwrap();
@@ -461,6 +464,7 @@ fn shipped_stance_bar_drives_end_to_end() {
 /// past it, so nothing else showed the bug.
 #[test]
 fn multibar_hover_renders_the_buttons_own_action() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     for file in [
@@ -581,6 +585,7 @@ fn multibar_hover_renders_the_buttons_own_action() {
 /// Since 1500 "hidden" is where they START rather than where they stay — see the toggle tests.
 #[test]
 fn the_vertical_multibars_exist_hidden_on_the_reference_pages() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_action_bar(&s);
     load_xml(&s, "Interface\\FrameXML\\Cooldown.xml");
@@ -632,7 +637,7 @@ fn the_vertical_multibars_exist_hidden_on_the_reference_pages() {
 /// **Every extra bar is down until its own toggle says otherwise, and `MultiBarLeft` needs two.**
 ///
 /// The four bits of `PLAYER_FIELD_BYTES` byte 2 map to bars 1-4 at the FrameXML layer (the binary
-/// is bar-agnostic — wow-5875-re `system/ui/scratch/action-bar-toggles.md`), and a fresh
+/// is bar-agnostic — `SetActionBarToggles 0x4e76e0` packs four unnamed bits), and a fresh
 /// character's byte is 0, which is the whole of "off by default": nothing here fakes a default,
 /// the bars simply have nothing telling them to show.
 ///
@@ -642,6 +647,7 @@ fn the_vertical_multibars_exist_hidden_on_the_reference_pages() {
 /// hanging off a bar that is not on screen.
 #[test]
 fn every_extra_bar_stays_down_until_its_own_toggle_is_set() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -729,6 +735,7 @@ fn every_extra_bar_stays_down_until_its_own_toggle_is_set() {
 /// frames drawing straight through a bar the player just asked for (decision 1499's screenshot).
 #[test]
 fn raising_a_bottom_bar_moves_the_managed_bottom_stack() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -793,6 +800,7 @@ fn raising_a_bottom_bar_moves_the_managed_bottom_stack() {
 /// which was only ever right because visibility was static.
 #[test]
 fn viewable_action_bar_pages_follow_the_bar_toggles() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -859,6 +867,7 @@ fn viewable_action_bar_pages_follow_the_bar_toggles() {
 /// can ever nest" stopped being true the moment this switch existed.
 #[test]
 fn the_grid_option_holds_the_extra_bars_empty_wells_open() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -958,12 +967,13 @@ fn the_grid_option_holds_the_extra_bars_empty_wells_open() {
 /// DIVERGENCES, chosen in 1782. In stock 1.12.1 the dim is fanned to every button and then never
 /// cleared by anything: `SetNormalTexture(path)` reuses the region and writes only its texture
 /// handle, and a 3-argument `SetVertexColor` is `SetVertexColor(r, g, b, currentAlpha)` — so the
-/// first spell anyone picks up leaves every border at alpha 0x80 for the session (wow-re
-/// `button-state-texture-path-setter.md` §2/§7, byte-verified). That is a stuck state keyed to
+/// first spell anyone picks up leaves every border at alpha 0x80 for the session (the reuse leg
+/// `0x778f10`, the alpha-keeping `SetVertexColor` `0x79abd0`). That is a stuck state keyed to
 /// nothing the player can see. We take the look the dim was written for and let go of it with the
 /// payload, which is what the last two assertions here pin.
 #[test]
 fn a_held_payload_ghosts_the_empty_wells_it_opens() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -1088,10 +1098,10 @@ fn a_held_payload_ghosts_the_empty_wells_it_opens() {
     );
     // What happens to that ring NEXT is decision 1782's open question, deliberately not asserted:
     // the reference's `SetVertexColor(1, 1, 1)` in `ActionButton_UpdateUsable` keeps the alpha
-    // already on the region (byte-pinned, wow-re button-state-texture-path-setter.md §7 — the
-    // "stuck dim" a 1.12 player sees after a drag), while this engine's three-argument call still
-    // resets it to 1.0 until the director calls 1782. A test that pinned either outcome would be
-    // enshrining a divergence as fidelity.
+    // already on the region (`SetVertexColor` `0x79abd0` — the "stuck dim" a 1.12 player sees
+    // after a drag), while this engine's three-argument call still resets it to 1.0 until the
+    // director calls 1782. A test that pinned either outcome would be enshrining a divergence as
+    // fidelity.
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
@@ -1099,14 +1109,15 @@ fn a_held_payload_ghosts_the_empty_wells_it_opens() {
 ///
 /// The whole round trip, over the REAL bindings (`benilla_ui::script::action_bar_toggles`): the
 /// row's setter writes a global, re-derives the bars and posts `CMSG_SET_ACTIONBAR_TOGGLES` with
-/// the WHOLE byte — bits `0x01/0x02/0x04/0x08`, verified against the 1.12.1 binary (wow-5875-re
-/// `417c2d31`). Coming back, the server's descriptor push is the only thing that moves the getter,
-/// and `UIParent.xml`'s `PLAYER_ENTERING_WORLD` arm reads it exactly once as the seed.
+/// the WHOLE byte — bits `0x01/0x02/0x04/0x08` (`SetActionBarToggles 0x4e76e0`). Coming back,
+/// the server's descriptor push is the only thing that moves the getter, and `UIParent.xml`'s
+/// `PLAYER_ENTERING_WORLD` arm reads it exactly once as the seed.
 ///
 /// Every `Set` is one packet, deliberately (the binding gates nothing), which is why the drain is a
 /// list and each step below checks the packet it just caused.
 #[test]
 fn a_bar_toggle_sends_the_byte_its_globals_pack_to() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -1194,6 +1205,7 @@ fn a_bar_toggle_sends_the_byte_its_globals_pack_to() {
 /// this file drives the real binding.
 #[test]
 fn the_shipped_setter_passes_exactly_four_arguments() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_action_bar(&s);
@@ -1245,6 +1257,7 @@ fn the_shipped_setter_passes_exactly_four_arguments() {
 /// here rather than assumed.
 #[test]
 fn the_stance_bar_sits_where_the_pass_puts_it() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ShapeshiftFormView;
 
     let mut s = UiScript::new().unwrap();
@@ -1317,6 +1330,7 @@ fn the_stance_bar_sits_where_the_pass_puts_it() {
 /// set once at load.
 #[test]
 fn the_stance_shelf_follows_the_bottom_left_bar() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ShapeshiftFormView;
 
     let mut s = UiScript::new().unwrap();
@@ -1438,6 +1452,7 @@ fn the_stance_shelf_follows_the_bottom_left_bar() {
 /// exercised 2 and 3 forms and only ever read `IsShown()`, which is exactly why it shipped.
 #[test]
 fn the_stance_shelf_is_as_long_as_the_form_count() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ShapeshiftFormView;
 
     let mut s = UiScript::new().unwrap();
@@ -1554,6 +1569,7 @@ fn the_stance_shelf_is_as_long_as_the_form_count() {
 /// slot has an action.
 #[test]
 fn an_extra_bars_empty_well_keeps_its_bound_hotkey_label() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // The real command set, so MULTIACTIONBAR1BUTTONn is bindable at all (it ships unbound —
@@ -1663,6 +1679,7 @@ fn an_extra_bars_empty_well_keeps_its_bound_hotkey_label() {
 /// the end caps (atlas crops of `ShapeshiftBarEnds`).
 #[test]
 fn the_middle_strip_tiles_along_its_length_only() {
+    benilla_formats::wow_data_or_skip!();
     use super::extract::tiling_axes;
     use crate::ui_pass::UvRect;
     use benilla_ui::script::{ShapeshiftFormView, TexCoords};
@@ -1729,7 +1746,7 @@ fn the_middle_strip_tiles_along_its_length_only() {
 /// alone, both end caps down.
 ///
 /// The reference fires `UPDATE_SHAPESHIFT_FORMS` for exactly one thing: the form LIST changed
-/// (learn / unlearn / rank — wow-re `shapeshift-bar-api.md`, the fires at `0x4b28ff`/`0x4b2e43`).
+/// (learn / unlearn / rank — the fires at `0x4b28ff`/`0x4b2e43`).
 /// Our feed fired it for any change in the pushed view — a stance switch, a castable flip, the
 /// shared 1 s category cooldown arming and then EXPIRING. Every fire runs the stock
 /// `ShapeshiftBar_Update` (BonusActionBarFrame.lua l.170): `ShapeshiftBarMiddle:Show()`
@@ -1745,6 +1762,7 @@ fn the_middle_strip_tiles_along_its_length_only() {
 /// one the switch really carries and reading the checked ring.
 #[test]
 fn a_forms_state_change_leaves_the_shelf_down_over_the_raised_bar() {
+    benilla_formats::wow_data_or_skip!();
     use crate::ui_shapeshift::{push_forms, FormsEdge, StanceMemory};
     use benilla_ui::script::ShapeshiftFormView;
 
diff --git a/crates/benilla-app/src/ui_script/options_tests.rs b/crates/benilla-app/src/ui_script/options_tests.rs
index 1cb724fb..43d3f917 100644
--- a/crates/benilla-app/src/ui_script/options_tests.rs
+++ b/crates/benilla-app/src/ui_script/options_tests.rs
@@ -104,6 +104,7 @@ fn harness_on(mut s: UiScript) -> UiScript {
 /// igMainMenuOption kit.
 #[test]
 fn the_menu_options_button_swaps_the_menu_for_the_options_window() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.run("ShowUIPanel(GameMenuFrame)").unwrap();
     let _ = s.take_sounds();
@@ -133,6 +134,7 @@ fn the_menu_options_button_swaps_the_menu_for_the_options_window() {
 /// label — including the one key whose label differs from it (ActionBars → "Action Bars").
 #[test]
 fn controls_is_the_default_category_and_the_title_reads_it() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
 
@@ -159,6 +161,7 @@ fn controls_is_the_default_category_and_the_title_reads_it() {
 /// survives a close/reopen (the OnShow re-applies the last seat, not the default).
 #[test]
 fn clicking_a_row_moves_the_selection_and_the_page_title() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
 
@@ -195,6 +198,7 @@ fn clicking_a_row_moves_the_selection_and_the_page_title() {
 /// the guard itself is pinned by `the_defaults_button_is_armed_by_rows_not_by_a_category` below.
 #[test]
 fn the_close_button_hides_the_window() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
 
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
@@ -223,6 +227,7 @@ fn the_close_button_hides_the_window() {
 /// (.196,.388,.8) while the locked gold stands — 1.14's LockHighlight guard.
 #[test]
 fn the_selected_row_wears_the_gold_wash_and_hover_runs_blue() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     // Pin the window at scale 1 so row rects and the pointer share coordinates (the fit
     // clamp stays out of the way at 1024x768: both ratios sit above 1).
@@ -336,6 +341,7 @@ fn the_selected_row_wears_the_gold_wash_and_hover_runs_blue() {
 /// would smear across the rope's inner half, which is exactly the mistake this pins.
 #[test]
 fn the_ground_dim_draws_over_the_tile_and_clear_of_the_rope() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.run("ERA_WINDOW_SCALE = 1").unwrap();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
@@ -404,6 +410,7 @@ fn the_ground_dim_draws_over_the_tile_and_clear_of_the_rope() {
 /// (the one-layout-law pin) with the page view restored.
 #[test]
 fn search_reflows_live_rows_and_restores_the_page() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowAudio:Click()")
@@ -499,6 +506,7 @@ fn search_reflows_live_rows_and_restores_the_page() {
 /// first within the group — "master volume" seats Master above the token-matched children.
 #[test]
 fn the_phrase_match_outranks_its_words() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameSearchBox:SetText(\"master volume\")")
@@ -524,6 +532,7 @@ fn the_phrase_match_outranks_its_words() {
 /// the box) and a no-match query (the section-header "no results" line, nothing chained).
 #[test]
 fn a_head_click_ends_the_search_and_a_miss_shows_no_results() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
 
@@ -584,6 +593,7 @@ fn a_head_click_ends_the_search_and_a_miss_shows_no_results() {
 /// dragging (0250 §5's capture began), and the stepper buttons no longer exist.
 #[test]
 fn a_track_press_seats_the_thumb_and_keeps_dragging() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.set_cvar_host("MasterVolume", "0.1");
     s.run("ERA_WINDOW_SCALE = 1").unwrap(); // pointer and rects share coordinates
@@ -660,6 +670,7 @@ fn a_track_press_seats_the_thumb_and_keeps_dragging() {
 /// window has: a label/value line, and the groove still riding 3 units high of the row.
 #[test]
 fn a_slider_rows_readout_sits_on_its_labels_line() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     for (page, rows) in [
@@ -918,6 +929,7 @@ fn actionbars_harness() -> UiScript {
 /// Leaving the page hides it and puts Defaults back to sleep.
 #[test]
 fn the_audio_page_reads_the_cvar_table_on_select() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("MusicVolume", "0.7");
     s.set_cvar_host("EnableMusic", "0");
@@ -973,6 +985,7 @@ fn the_audio_page_reads_the_cvar_table_on_select() {
 /// (the page reading the table) queues nothing.
 #[test]
 fn a_slider_move_snaps_and_writes_the_cvar() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowAudio:Click()")
@@ -1009,6 +1022,7 @@ fn a_slider_move_snaps_and_writes_the_cvar() {
 /// 1.12 dependency holds: Enable All Sound off greys exactly the Enable Ambience row.
 #[test]
 fn the_checkbox_rows_write_flags_and_the_master_greys_ambience() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowAudio:Click()")
@@ -1059,6 +1073,7 @@ fn the_checkbox_rows_write_flags_and_the_master_greys_ambience() {
 /// exactly two rows in `SoundOptionsFrame_UpdateDependencies` and never grew a third.
 #[test]
 fn the_background_sound_row_boots_off_and_writes_the_era_cvar() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowAudio:Click()")
@@ -1098,6 +1113,7 @@ fn the_background_sound_row_boots_off_and_writes_the_era_cvar() {
 /// the era per-page reset, on the one page with rows.
 #[test]
 fn defaults_resets_the_audio_page_to_registered_defaults() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("MusicVolume", "0.9");
     s.set_cvar_host("EnableMusic", "0");
@@ -1141,6 +1157,7 @@ fn defaults_resets_the_audio_page_to_registered_defaults() {
 /// Audio's body takes over when clicked.
 #[test]
 fn the_graphics_page_reads_the_cvar_table_on_select() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("uiScale", "0.8");
     s.set_cvar_host("farclip", "297");
@@ -1218,6 +1235,7 @@ fn the_graphics_page_reads_the_cvar_table_on_select() {
 /// inverted by a later edit, and until this test there was no coverage of the row at all.
 #[test]
 fn the_display_mode_dropdown_maps_its_entries_to_the_gx_window_polarity() {
+    benilla_formats::wow_data_or_skip!();
     const ROW: &str = "BenillaOptionsFrameContainerBodyGraphicsRowDisplayMode";
     let mut s = audio_harness();
     s.set_cvar_host("gxWindow", "0");
@@ -1279,6 +1297,7 @@ fn the_display_mode_dropdown_maps_its_entries_to_the_gx_window_polarity() {
 /// and wgpu can — so the click commits, like every other checkbox here.
 #[test]
 fn the_vertical_sync_row_reads_and_writes_the_present_mode_cvar() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("gxVSync", "0");
     let mut s = harness_on(s);
@@ -1342,6 +1361,7 @@ fn the_vertical_sync_row_reads_and_writes_the_present_mode_cvar() {
 /// never did was move the slider, which is the only thing a player does. So this one drags.
 #[test]
 fn the_brightness_slider_writes_through_its_engine_pair_and_survives_a_reopen() {
+    benilla_formats::wow_data_or_skip!();
     const ROW: &str = "BenillaOptionsFrameContainerBodyGraphicsRowBrightness";
     let s = audio_harness();
     let mut s = harness_on(s);
@@ -1407,6 +1427,7 @@ fn the_brightness_slider_writes_through_its_engine_pair_and_survives_a_reopen()
 /// and writes nothing back (0959's out-of-range law).
 #[test]
 fn the_world_detail_slider_writes_the_cvar_and_the_readout_names_its_stop() {
+    benilla_formats::wow_data_or_skip!();
     const ROW: &str = "BenillaOptionsFrameContainerBodyGraphicsRowWorldDetail";
     let mut s = audio_harness();
     s.set_cvar_host("WorldDetail", "0");
@@ -1572,6 +1593,7 @@ fn a_world_entry_leaves_the_saved_nameplate_setting_alone() {
 
 #[test]
 fn the_nameplates_page_toggles_the_unit_name_cvars() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowNameplates:Click()")
@@ -1660,6 +1682,7 @@ fn the_nameplates_page_toggles_the_unit_name_cvars() {
 /// committed value clears the pending without a commit (era's IsModified).
 #[test]
 fn the_ui_scale_slider_defers_to_the_apply_button() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowGraphics:Click()")
@@ -1749,6 +1772,7 @@ fn the_ui_scale_slider_defers_to_the_apply_button() {
 ///   could not tell what it did.
 #[test]
 fn the_render_scale_row_shows_a_percentage_and_defers_to_apply() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("renderScale", "1");
     let mut s = harness_on(s);
@@ -1820,6 +1844,7 @@ fn the_render_scale_row_shows_a_percentage_and_defers_to_apply() {
 /// only when the window hides — the reopened window reads the committed truth.
 #[test]
 fn a_pending_ui_scale_survives_the_page_switch_and_dies_on_hide() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowGraphics:Click()")
@@ -1873,6 +1898,7 @@ fn a_pending_ui_scale_survives_the_page_switch_and_dies_on_hide() {
 /// write is what moves the far-clip wall and the residency window together.
 #[test]
 fn the_terrain_distance_slider_snaps_to_the_1_12_grid_and_writes_live() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowGraphics:Click()")
@@ -1913,6 +1939,7 @@ fn the_terrain_distance_slider_snaps_to_the_1_12_grid_and_writes_live() {
 /// dies with it (the default write supersedes what Apply would have committed).
 #[test]
 fn defaults_resets_the_graphics_page_to_registered_defaults() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("uiScale", "0.8");
     s.set_cvar_host("farclip", "297");
@@ -1976,6 +2003,7 @@ const ADVGFX: &str = "BenillaOptionsFrameContainerBodyAdvancedGraphics";
 // MONKEY (volumetric fog): exercise translations and numeric writes through the real UI.
 #[test]
 fn volumetric_fog_dropdown_is_localised_and_live() {
+    benilla_formats::wow_data_or_skip!();
     // MONKEY (volumetric fog): validate the authored table and row even on a
     // data-free checkout; the complete window additionally needs stock FrameXML.
     let xml = include_str!("../../assets/ui/OptionsFrame.xml");
@@ -2029,6 +2057,7 @@ fn volumetric_fog_dropdown_is_localised_and_live() {
 
 #[test]
 fn water_quality_writes_numeric_tiers_with_localised_labels() {
+    benilla_formats::wow_data_or_skip!();
     for (locale, labels, lava_label) in [
         ("enUS", ["Classic", "Enhanced", "High"], "Lava Glow"),
         ("ruRU", ["Классическое", "Улучшенное", "Высокое"], "Свечение лавы"),
@@ -2056,6 +2085,7 @@ fn water_quality_writes_numeric_tiers_with_localised_labels() {
 
 #[test]
 fn advanced_graphics_fire_spell_and_lava_sliders_read_and_write_the_full_range() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("fireLightGain", "3.25");
     s.set_cvar_host("spellLightGain", "3.25");
@@ -2083,6 +2113,7 @@ fn advanced_graphics_fire_spell_and_lava_sliders_read_and_write_the_full_range()
 
 #[test]
 fn advanced_graphics_selects_its_locale_at_load_including_yards() {
+    benilla_formats::wow_data_or_skip!();
     for (locale, title, distance) in [
         ("enUS", "Advanced Graphics", "80 yd"),
         ("ruRU", "Расширенная графика", "80 ярд."),
@@ -2117,6 +2148,7 @@ fn advanced_graphics_selects_its_locale_at_load_including_yards() {
 /// CVar, which nothing else in this file would catch.
 #[test]
 fn the_advanced_graphics_page_reads_the_lighting_cvars_on_select() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("shadowMapSize", "4096");
     s.set_cvar_host("interiorShadows", "0");
@@ -2202,6 +2234,7 @@ fn the_advanced_graphics_page_reads_the_lighting_cvars_on_select() {
 /// spelling, and nothing else queued.
 #[test]
 fn the_lighting_quality_row_writes_one_cvar_and_leaves_the_members_to_the_host() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowAdvancedGraphics:Click()")
@@ -2235,6 +2268,7 @@ fn the_lighting_quality_row_writes_one_cvar_and_leaves_the_members_to_the_host()
 /// beside the label would climb as the world got lighter, under a label that says "Darkness".
 #[test]
 fn the_darkness_sliders_read_out_so_that_left_is_darker() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowAdvancedGraphics:Click()")
@@ -2279,6 +2313,7 @@ fn the_darkness_sliders_read_out_so_that_left_is_darker() {
 /// children where they were left.
 #[test]
 fn the_advanced_graphics_masters_grey_what_they_gate() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowAdvancedGraphics:Click()")
@@ -2326,6 +2361,7 @@ fn the_advanced_graphics_masters_grey_what_they_gate() {
 /// page is open. Without the poll the player would pick a preset and watch nothing below it move.
 #[test]
 fn the_page_repaints_when_a_host_write_moves_a_row_under_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowAdvancedGraphics:Click()")
@@ -2375,6 +2411,7 @@ fn the_page_repaints_when_a_host_write_moves_a_row_under_it() {
 /// `deselectOnClick` is "0", the 1.12 interface panel's own arm), the plain flags direct.
 #[test]
 fn the_controls_page_reads_flags_with_the_sticky_inversion() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("deselectOnClick", "0");
     s.set_cvar_host("autoLootDefault", "1");
@@ -2419,6 +2456,7 @@ fn the_controls_page_reads_flags_with_the_sticky_inversion() {
 /// Sticky Targeting writes the CVar inverted both ways.
 #[test]
 fn the_controls_checkboxes_write_flags_with_the_interface_panel_kit() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     assert!(
@@ -2463,6 +2501,7 @@ fn the_controls_checkboxes_write_flags_with_the_interface_panel_kit() {
 /// autoLootDefault "0"), the rows follow, and only the moved values queue.
 #[test]
 fn defaults_resets_the_controls_page_to_registered_defaults() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("deselectOnClick", "0");
     s.set_cvar_host("autoLootDefault", "1");
@@ -2515,6 +2554,7 @@ fn settle(s: &mut UiScript) {
 /// rect until scrolled to.
 #[test]
 fn a_broad_search_scrolls_the_page_instead_of_overflowing_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     // On NAMEPLATES, not the default Controls page: since 2180 seated the four camera toggles and
@@ -2661,6 +2701,7 @@ fn a_broad_search_scrolls_the_page_instead_of_overflowing_it() {
 /// keybindings_tests, where the harness has a real binding registry to overflow the list with.)
 #[test]
 fn the_page_scroll_bar_wears_the_trough_with_its_arrows_in_the_sockets() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameSearchBox:SetText(\"e\")")
@@ -2792,6 +2833,7 @@ fn scroll_into_view(s: &mut UiScript, frame: &str) {
 /// property the 1.12 panel's own `getglobal("OPTION_TOOLTIP_"..key)` lookup buys.
 #[test]
 fn a_hovered_row_raises_its_1_12_description_on_the_era_seat() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     // The stock tooltip declares no size: it sizes from its lines through the font engine, as
     // the client's does (1968) — a harness that reads its rect needs one; the fixed-width
@@ -2868,6 +2910,7 @@ fn a_hovered_row_raises_its_1_12_description_on_the_era_seat() {
 /// hover driven without the outgoing row's OnLeave (1054) must still put the neighbour away.
 #[test]
 fn a_row_with_no_1_12_string_raises_no_plate() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("OPTION_TOOLTIP_GAMEFIELD_DESELECT = \"Sticky's own description.\"")
         .unwrap();
@@ -3124,6 +3167,7 @@ fn every_row_tooltip_key_resolves_in_the_real_global_strings() {
 /// line instead of a plate, which no key-mapping check would ever see.
 #[test]
 fn every_flavor_of_row_raises_its_plate_from_the_page_it_lives_on() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     // Stand-in strings for every key the rows name (the real texts are the data test's job).
     s.run(
@@ -3234,6 +3278,7 @@ fn every_flavor_of_row_raises_its_plate_from_the_page_it_lives_on() {
 /// effect is the per-type `show` flag and the scroll function.
 #[test]
 fn the_combat_page_writes_saved_variable_globals_and_applies_them() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = combat_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowCombat:Click()")
@@ -3331,6 +3376,7 @@ fn the_combat_page_writes_saved_variable_globals_and_applies_them() {
 /// wake is the master's own click rather than the load: the same rule, entered from the other end.
 #[test]
 fn the_combat_master_greys_the_family_and_combo_points_is_class_gated() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = combat_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowCombat:Click()")
@@ -3388,6 +3434,7 @@ fn the_combat_master_greys_the_family_and_combo_points_is_class_gated() {
 /// Defaults lands a player back on a stock 1.12 combat-text family.
 #[test]
 fn defaults_resets_the_combat_page_to_the_shipped_assignments() {
+    benilla_formats::wow_data_or_skip!();
     let s = combat_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowCombat:Click()")
@@ -3454,6 +3501,7 @@ fn defaults_resets_the_combat_page_to_the_shipped_assignments() {
 /// text comes up with the player's choice rather than CombatText.xml's shipped default.
 #[test]
 fn what_the_combat_page_writes_survives_a_restart() {
+    benilla_formats::wow_data_or_skip!();
     let s = combat_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowCombat:Click()")
@@ -3466,7 +3514,7 @@ fn what_the_combat_page_writes_survives_a_restart() {
     s.run("BenillaOptionsFrameContainerBodyCombatRowHonorGainedCheck:Click()")
         .unwrap();
 
-    let saved = s.saved_variables_text();
+    let saved = String::from_utf8(s.saved_variables_bytes()).unwrap();
     assert!(
         saved.contains("COMBAT_TEXT_SHOW_HONOR_GAINED = \"0\""),
         "the toggle is in the saved text:\n{saved}"
@@ -3528,6 +3576,7 @@ fn what_the_combat_page_writes_survives_a_restart() {
 /// (including the shift-click that deliberately still works); this owns the wire between them.
 #[test]
 fn the_action_bars_page_locks_the_real_bar() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = actionbars_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowActionBars:Click()")
@@ -3592,6 +3641,7 @@ fn the_action_bars_page_locks_the_real_bar() {
 /// questgiver's instant-text arm, live on the very next show.
 #[test]
 fn the_interface_page_writes_the_three_stock_globals() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = interface_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowInterface:Click()")
@@ -3665,6 +3715,7 @@ fn the_interface_page_writes_the_three_stock_globals() {
 /// * the picker's five values are the reference's own strings, in its own order.
 #[test]
 fn the_target_of_target_rows_gate_each_other_and_write_their_globals() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = interface_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowInterface:Click()")
@@ -3772,6 +3823,7 @@ fn the_target_of_target_rows_gate_each_other_and_write_their_globals() {
 /// a second click inside that round trip would otherwise compute the wrong direction.
 #[test]
 fn the_equipment_display_rows_read_and_write_through_the_api_not_a_store() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = interface_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowInterface:Click()")
@@ -3850,6 +3902,7 @@ fn the_equipment_display_rows_read_and_write_through_the_api_not_a_store() {
 /// tutorial.
 #[test]
 fn show_tutorials_reads_the_bank_and_writes_through_clear_and_reset() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = interface_harness();
     // A bank with unacknowledged bits: tutorials are enabled.
     s.set_tutorial_bank(Some(vec![0x00; 32]));
@@ -3908,6 +3961,7 @@ fn show_tutorials_reads_the_bank_and_writes_through_clear_and_reset() {
 /// has dismissed — an option that silently undoes hours of play.
 #[test]
 fn a_no_op_write_does_not_re_arm_the_tutorials() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = interface_harness();
     s.set_tutorial_bank(Some(vec![0x00; 32])); // enabled
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
@@ -3932,6 +3986,7 @@ fn a_no_op_write_does_not_re_arm_the_tutorials() {
 /// no-op default must not queue a packet that would turn the preference on its head.
 #[test]
 fn defaults_sends_a_flip_only_for_the_row_that_moved() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = interface_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowInterface:Click()")
@@ -3971,6 +4026,7 @@ fn defaults_sends_a_flip_only_for_the_row_that_moved() {
 /// property worth holding: the capture follows the definer wherever the definer stands.
 #[test]
 fn defaults_on_the_interface_page_restores_the_definers_own_assignment() {
+    benilla_formats::wow_data_or_skip!();
     let s = interface_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowInterface:Click()")
@@ -4009,6 +4065,7 @@ fn defaults_on_the_interface_page_restores_the_definers_own_assignment() {
 /// player's choice instead of QuestLogFrame.xml's shipped one.
 #[test]
 fn what_the_interface_page_writes_survives_a_restart() {
+    benilla_formats::wow_data_or_skip!();
     let s = interface_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowInterface:Click()")
@@ -4016,7 +4073,7 @@ fn what_the_interface_page_writes_survives_a_restart() {
     s.run("BenillaOptionsFrameContainerBodyInterfaceRowAutoQuestWatchCheck:Click()")
         .unwrap();
 
-    let saved = s.saved_variables_text();
+    let saved = String::from_utf8(s.saved_variables_bytes()).unwrap();
     assert!(
         saved.contains("AUTO_QUEST_WATCH = \"0\""),
         "the toggle is in the saved text under the reference's name:\n{saved}"
@@ -4066,6 +4123,7 @@ fn what_the_interface_page_writes_survives_a_restart() {
 /// other one: the registrations were never armed at all, and only the walk can arm them.
 #[test]
 fn a_saved_switch_with_a_side_effect_is_applied_when_the_variables_land() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = combat_harness();
     // What the saved chunk does, verbatim: assign over the file-scope default, then the event.
     s.run("SHOW_COMBAT_TEXT = \"1\"").unwrap();
@@ -4103,6 +4161,7 @@ fn a_saved_switch_with_a_side_effect_is_applied_when_the_variables_land() {
 /// only which of them a fresh install opens on.
 #[test]
 fn the_buff_durations_row_repitches_the_bar_and_the_pitch_survives_a_restart() {
+    benilla_formats::wow_data_or_skip!();
     let gap = |s: &mut UiScript| -> f64 {
         s.resolve();
         s.eval::<f64>("return BuffButton0:GetBottom() - BuffButton8:GetTop()")
@@ -4138,7 +4197,7 @@ fn the_buff_durations_row_repitches_the_bar_and_the_pitch_survives_a_restart() {
 
     // Restart: the fresh tree comes up on the shipped geometry, the chunk replaces the value, and
     // VARIABLES_LOADED is what puts the bar where the value says.
-    let saved = s.saved_variables_text();
+    let saved = String::from_utf8(s.saved_variables_bytes()).unwrap();
     assert!(
         saved.contains("SHOW_BUFF_DURATIONS = \"1\""),
         "the switch is in the saved text:\n{saved}"
@@ -4174,6 +4233,7 @@ fn the_buff_durations_row_repitches_the_bar_and_the_pitch_survives_a_restart() {
 /// rather than through a stand-in page — there is no longer one to borrow.
 #[test]
 fn the_defaults_button_is_armed_by_rows_not_by_a_category() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
 
@@ -4236,6 +4296,7 @@ fn the_defaults_button_is_armed_by_rows_not_by_a_category() {
 /// (l.337). So a fresh client shows the box **unchecked**, and ticking it turns the filter off.
 #[test]
 fn the_disable_spam_filter_row_is_inverted() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowChat:Click()")
@@ -4277,6 +4338,7 @@ fn the_disable_spam_filter_row_is_inverted() {
 /// column-C chain rather than joining the Chat page.
 #[test]
 fn the_profanity_filter_row_sits_on_the_interface_page_and_writes_its_cvar() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = interface_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowInterface:Click()")
@@ -4303,6 +4365,7 @@ fn the_profanity_filter_row_sits_on_the_interface_page_and_writes_its_cvar() {
 
 #[test]
 fn the_chat_page_toggles_the_chat_bubble_cvars() {
+    benilla_formats::wow_data_or_skip!();
     // No host override: since 1804 the registered pair IS bubbles-on / party-off, so the page's
     // read below is of the shipped table rather than of a value this test planted.
     let mut s = harness_on(audio_harness());
@@ -4376,6 +4439,7 @@ fn the_chat_page_toggles_the_chat_bubble_cvars() {
 /// 1136's rule for when a row needs one, seen from both sides on one page).
 #[test]
 fn the_chat_page_writes_the_hover_delay_global_and_the_loot_spam_cvar() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowChat:Click()")
@@ -4459,6 +4523,7 @@ fn the_chat_page_writes_the_hover_delay_global_and_the_loot_spam_cvar() {
 /// fresh VM has re-run `ChatFrame.xml`'s file-scope `"0"`.
 #[test]
 fn a_saved_hover_delay_is_applied_when_the_variables_land() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = chat_harness();
     // What the saved-variables chunk does: assign the global, then the window's VARIABLES_LOADED.
     s.run("REMOVE_CHAT_DELAY = \"1\"").unwrap();
@@ -4492,6 +4557,7 @@ fn a_saved_hover_delay_is_applied_when_the_variables_land() {
 /// here is the uppercase display name and not the CVar's own spelling.
 #[test]
 fn the_status_bar_text_row_pins_the_numerals_the_moment_it_is_clicked() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = interface_harness();
     // The bar needs a real span before it decides anything about its numerals (its update bails
     // on valueMax == 0 and hides the strip instead).
@@ -4549,6 +4615,7 @@ fn the_status_bar_text_row_pins_the_numerals_the_moment_it_is_clicked() {
 /// `LookConfig::sensitivity`.
 #[test]
 fn the_mouse_sensitivity_slider_snaps_to_the_reference_step() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = audio_harness();
     s.set_cvar_host("mousespeed", "1.25");
     let mut s = harness_on(s);
@@ -4607,6 +4674,7 @@ fn the_mouse_sensitivity_slider_snaps_to_the_reference_step() {
 /// rather than down it.
 #[test]
 fn the_max_camera_distance_slider_stores_a_factor_and_reads_out_yards() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowControls:Click()")
@@ -4679,12 +4747,13 @@ fn the_max_camera_distance_slider_stores_a_factor_and_reads_out_yards() {
 /// Controls-page dropdown, and the setting that decides whether the camera returns to behind the
 /// character at all. What is pinned here is the trap: the reference's own dropdown writes `1/2/3`,
 /// but the ENGINE's tables are indexed `0 = Never · 1 = Smart · 2 = Always`, and `3` is not a style
-/// — the validator accepts it while the terrain-tilt consumer indexes off the end of its table
-/// (wow-re `camera-smooth-style.md` §2/§4). So our entries carry the engine's numbers in the
+/// — the validator (`0x50c060`) accepts it while the terrain-tilt consumer (`0x50dbc0`) indexes
+/// off the end of its table. So our entries carry the engine's numbers in the
 /// reference's display order, a stray `3` still reads as Never rather than as the numerically
 /// nearest "Always", and the plate follows the SELECTION the way that dropdown's own does.
 #[test]
 fn the_camera_following_style_dropdown_carries_the_engine_enum_and_plate() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowControls:Click()")
@@ -4814,6 +4883,7 @@ fn the_camera_following_style_dropdown_carries_the_engine_enum_and_plate() {
 /// `MultiActionBar_Update`, which reaches `UIParent_ManageFramePositions`.
 #[test]
 fn the_action_bars_page_toggles_the_real_bars() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = actionbars_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowActionBars:Click()")
@@ -4992,6 +5062,7 @@ impl benilla_ui::script::TextMeasure for SteppedFont {
 /// (64 and 76 here); on the show, behind the window's own OnShow, they measure at the drawn 0.78.
 #[test]
 fn the_two_option_tabs_fit_their_labels_at_the_drawn_scale() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_text_measurer(Box::new(SteppedFont(6.0)));
     let mut s = harness_on(s);
@@ -5062,6 +5133,7 @@ fn the_two_option_tabs_fit_their_labels_at_the_drawn_scale() {
 /// seated `AtlasMeasurer` for certain, whatever order the boot took.
 #[test]
 fn without_a_seated_measurer_the_same_fit_reads_zero() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(UiScript::new().unwrap());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.resolve();
@@ -5138,6 +5210,7 @@ const UNBACKED_REFERENCE_CVARS: &[(&str, &str)] = &[
 /// us and shipping one was somebody re-reading a decision record from months ago.
 #[test]
 fn every_cvar_the_reference_table_names_is_registered_or_listed_with_its_blocker() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     // The table as the file declares it: `name` (the display key) -> its `cvar`, if it has one.
     // **BOTH of the reference's option tables** (2115). The checkbuttons were the whole census
@@ -5222,6 +5295,7 @@ fn every_cvar_the_reference_table_names_is_registered_or_listed_with_its_blocker
 /// player change and benilla does not, and it costs a stated reason at the row.
 #[test]
 fn every_registered_reference_cvar_has_a_row_on_our_own_window() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
 
     // Both of the reference's own option tables, exactly as the registration census reads them.
@@ -5328,6 +5402,7 @@ const UNREACHABLE_REFERENCE_CVARS: &[(&str, &str)] = &[];
 /// `cameraWaterCollision` a player who wants them OFF had no way to say so at all.
 #[test]
 fn the_four_camera_toggles_read_their_shipped_defaults_and_write_on_the_click() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowControls:Click()")
@@ -5376,6 +5451,7 @@ fn the_four_camera_toggles_read_their_shipped_defaults_and_write_on_the_click()
 /// kept floating.
 #[test]
 fn the_pet_damage_box_and_the_look_slider_each_write_their_unnamed_twin() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = combat_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowCombat:Click()")
@@ -5428,6 +5504,7 @@ fn the_pet_damage_box_and_the_look_slider_each_write_their_unnamed_twin() {
 /// combat text also turns off damage numbers, which is the opposite of what `CombatDamage` does.
 #[test]
 fn show_target_damage_greys_its_own_pair_and_the_floating_text_master_leaves_it_alone() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = combat_harness();
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
     s.run("BenillaOptionsFrameCategoryListRowCombat:Click()")
@@ -5479,6 +5556,7 @@ fn show_target_damage_greys_its_own_pair_and_the_floating_text_master_leaves_it_
 /// (l.715-719 — there is no follow to set a speed for).
 #[test]
 fn the_guild_line_greys_with_player_names_and_the_follow_speed_with_the_style() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness_on(audio_harness());
     s.run("ShowUIPanel(BenillaOptionsFrame)").unwrap();
 
diff --git a/crates/benilla-app/src/ui_script/panel_tests.rs b/crates/benilla-app/src/ui_script/panel_tests.rs
index 7a2f5e59..4b3e222f 100644
--- a/crates/benilla-app/src/ui_script/panel_tests.rs
+++ b/crates/benilla-app/src/ui_script/panel_tests.rs
@@ -296,7 +296,7 @@ fn shipped_gossip_frame_renders_quest_rows_above_options() {
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 
     // Rows 1-2 carry the quest titles (active first, matching the order the menu supplied them —
-    // benilla's seam already flattens available/active into one ordered list, ui_gossip.rs), row 3
+    // benilla's seam already flattens available/active into one ordered list, `ui_gossip`), row 3
     // the option, row 4+ hidden.
     let (r1_text, r1_vis, r2_vis, r3_text, r3_vis, r4_vis, r5_text, r5_vis, r6_vis): (
         String,
@@ -1271,8 +1271,8 @@ fn a_dead_player_opens_only_whiledead_windows() {
         s.eval::<bool>("return GetLeftFrame() == nil").unwrap(),
         "the refused window took no slot"
     );
-    // ...and the refusal is heard: NotWhileDeadError (the binary's 0x48d340 — push 0x7e, wow-re
-    // cross-checked) queued the catalog row's key for the app to resolve and toast.
+    // ...and the refusal is heard: NotWhileDeadError (the binary's 0x48d340 — push 0x7e) queued
+    // the catalog row's key for the app to resolve and toast.
     assert_eq!(
         s.take_ui_errors(),
         vec!["ERR_PLAYER_DEAD"],
diff --git a/crates/benilla-app/src/ui_script/perf_bar_tests.rs b/crates/benilla-app/src/ui_script/perf_bar_tests.rs
index e399b270..bb4ba910 100644
--- a/crates/benilla-app/src/ui_script/perf_bar_tests.rs
+++ b/crates/benilla-app/src/ui_script/perf_bar_tests.rs
@@ -61,6 +61,7 @@ fn bar_quad(s: &mut UiScript) -> (usize, [f32; 4], Option<[f32; 4]>) {
 /// grey column into the slot rather than floating it above.
 #[test]
 fn the_meter_sits_in_the_bar_recess_the_reference_leaves_for_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     s.resolve();
 
@@ -90,6 +91,7 @@ fn the_meter_sits_in_the_bar_recess_the_reference_leaves_for_it() {
 /// would paint over the metal surround that frames the 10-wide slot.
 #[test]
 fn the_meter_paints_under_the_bar_art_it_shows_through() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     let (meter, _, _) = bar_quad(&mut s);
 
@@ -128,6 +130,7 @@ fn the_meter_paints_under_the_bar_art_it_shows_through() {
 /// — color is the entire readout, which is why this test asserts the tint and the rect separately.
 #[test]
 fn the_meter_tints_by_latency_on_the_reference_thresholds() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
 
     // The first tick polls immediately (updateInterval starts at 0), so an unmeasured connection
@@ -197,6 +200,7 @@ fn poll_beat(s: &mut UiScript) {
 /// arithmetic on them can't error.
 #[test]
 fn get_net_stats_reports_the_pushed_latency() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     assert_eq!(
         s.eval::<(f64, f64, f64)>("return GetNetStats()").unwrap(),
@@ -229,6 +233,7 @@ fn get_net_stats_reports_the_pushed_latency() {
 /// tooltip that is quietly one line short.
 #[test]
 fn hovering_the_meter_shows_the_live_latency() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[r"Interface\FrameXML\UIParent.xml"]);
     s.set_latency_ms(Some(42));
     // 1.12 ships detailed tips ON — `SHOW_NEWBIE_TIPS = "1"` is UIOptionsFrame_Init's (ref
@@ -309,6 +314,7 @@ fn hovering_the_meter_shows_the_live_latency() {
 /// the bar's end-to-end test pins, kept here so the two move together.
 #[test]
 fn the_meter_adds_its_two_frames_to_the_bar() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(&[]);
     for name in [
         "MainMenuBarPerformanceBarFrame",
diff --git a/crates/benilla-app/src/ui_script/pet_bar_tests.rs b/crates/benilla-app/src/ui_script/pet_bar_tests.rs
index d2ebea92..c032fa85 100644
--- a/crates/benilla-app/src/ui_script/pet_bar_tests.rs
+++ b/crates/benilla-app/src/ui_script/pet_bar_tests.rs
@@ -128,6 +128,7 @@ fn texture_rect(
 /// painting what they should, and hidden again when the pet goes.
 #[test]
 fn the_shipped_pet_bar_drives_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_pet_bar(&s);
@@ -249,6 +250,7 @@ fn the_shipped_pet_bar_drives_end_to_end() {
 /// `IsPetAttackActive` fork — the one branch that makes the Attack button a toggle).
 #[test]
 fn clicks_route_through_the_attack_toggle_fork() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_pet_bar(&s);
@@ -310,6 +312,7 @@ fn clicks_route_through_the_attack_toggle_fork() {
 /// director; decision 1027 diverged from it and 1030 put it back.
 #[test]
 fn a_click_drops_the_ring_and_the_repaint_restores_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_pet_bar(&s);
@@ -353,6 +356,7 @@ fn a_click_drops_the_ring_and_the_repaint_restores_it() {
 /// looks like, and collapsing it to "hide the bar" would lose the state entirely.
 #[test]
 fn a_disabled_bar_greys_rather_than_hides() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_pet_bar(&s);
@@ -429,6 +433,7 @@ fn pet_bar_row(with_multibar: bool) -> (usize, f32) {
 /// is the base position, so a pass that never fired would leave it exactly where the bug was.
 #[test]
 fn the_pet_bar_rises_and_sheds_its_shelf_over_the_bottom_left_bar() {
+    benilla_formats::wow_data_or_skip!();
     let (low_shelf, low_top) = pet_bar_row(false);
     let (high_shelf, high_top) = pet_bar_row(true);
 
@@ -454,6 +459,7 @@ fn the_pet_bar_rises_and_sheds_its_shelf_over_the_bottom_left_bar() {
 /// exists, and the reason an unnamed button's `Hide()` is conditional.
 #[test]
 fn dragging_a_pet_spell_between_slots_moves_it_through_the_shipped_handlers() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_pet_bar(&s);
@@ -507,6 +513,7 @@ fn dragging_a_pet_spell_between_slots_moves_it_through_the_shipped_handlers() {
 /// reference leaves it (l.253-255).
 #[test]
 fn the_lock_stops_the_pet_bar_drag_but_not_its_shift_click() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_pet_bar(&s);
@@ -556,6 +563,7 @@ fn the_lock_stops_the_pet_bar_drag_but_not_its_shift_click() {
 /// puts shift above the left/right split, so it never toggles autocast by accident.
 #[test]
 fn shift_clicking_a_pet_button_picks_it_up_rather_than_casting() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_pet_bar(&s);
@@ -598,6 +606,7 @@ fn shift_clicking_a_pet_button_picks_it_up_rather_than_casting() {
 /// one worth pinning. Read as "ordinary pets differ from clicks", this test would be lying.
 #[test]
 fn the_keybind_pair_pushes_and_casts_without_the_clicks_forks() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_pet_bar(&s);
@@ -661,7 +670,7 @@ fn the_keybind_pair_pushes_and_casts_without_the_clicks_forks() {
 
 /// A hunter bar hovered through the REAL gesture, with the real binding registry and the real CVar
 /// table behind it — `mouse_move` runs the shipped `<OnEnter>` with `this` bound, which is the only
-/// way this fork gets exercised the way nazriel exercised it.
+/// way this fork gets exercised the way a player's hover exercises it.
 ///
 /// Buttons are 30 px chained +8 from the bar's own origin: button 1 spans x[72,102] y[56,86] ⇒
 /// centre (87,71), button 4's left = 72 + 3·38 ⇒ centre (201,71) — the geometry
@@ -692,8 +701,7 @@ fn tooltip_line1(s: &UiScript) -> String {
 
 /// **B230 — Attack/Follow/Stay name their keybinding; the pet's own spells do not.**
 ///
-/// nazriel: *"On 1.12 when you hover over Attack, Follow, Stay pet action buttons they show the
-/// keybinding - which is not the case with Benilla"*. The reference agrees with him and is
+/// On 1.12, hovering Attack, Follow or Stay shows the button's keybinding in its tooltip. That is
 /// narrower than "the pet bar": `PetActionButton_OnEnter` (PetActionBarFrame.lua l.285-305) forks
 /// on `isToken or UberTooltips == "0"`, and only THAT branch concatenates
 /// `NORMAL_FONT_COLOR_CODE.." ("..GetBindingText(GetBindingKey("BONUSACTIONBUTTON"..id), "KEY_")..")"`.
@@ -705,6 +713,7 @@ fn tooltip_line1(s: &UiScript) -> String {
 /// which is what the stock `MicroButtonTooltipText` — the same idea, the other shape — produces).
 #[test]
 fn token_tooltips_name_their_binding_and_pet_spells_do_not() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = hovered_pet_bar();
 
     s.mouse_move(ATTACK_BUTTON.0, ATTACK_BUTTON.1);
@@ -742,6 +751,7 @@ fn token_tooltips_name_their_binding_and_pet_spells_do_not() {
 /// deliberate unbind to see, which is exactly what this does.
 #[test]
 fn an_unbound_token_row_renders_the_references_empty_parentheses() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = hovered_pet_bar();
     s.run(r#"SetBinding("CTRL-1")"#).unwrap();
     assert!(
@@ -770,6 +780,7 @@ fn an_unbound_token_row_renders_the_references_empty_parentheses() {
 /// at all because these Lua sites read it (the honest-tree rule's live-consumer half).
 #[test]
 fn ubertooltips_off_takes_the_spells_through_the_token_branch_and_moves_the_plate() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = hovered_pet_bar();
     s.set_cvar_engine("UberTooltips", "0");
 
diff --git a/crates/benilla-app/src/ui_script/pet_frame_tests.rs b/crates/benilla-app/src/ui_script/pet_frame_tests.rs
index 8edc796e..efa3e5ba 100644
--- a/crates/benilla-app/src/ui_script/pet_frame_tests.rs
+++ b/crates/benilla-app/src/ui_script/pet_frame_tests.rs
@@ -2,7 +2,7 @@
 //! `PetFrame` over synthetic `"pet"` snapshots and the events the app's feed fires.
 //!
 //! The frame's whole job is to be right about **which unit an event names**, and that is what most
-//! of these test: `UNIT_PET` names the OWNER (`arg1 == "player"`, wow-re §9), every other `UNIT_*`
+//! of these test: `UNIT_PET` names the OWNER (`arg1 == "player"`, `0x4bc84f`), every other `UNIT_*`
 //! names the pet itself, and a frame that mixes the two repaints off the player's health.
 
 use benilla_ui::script::{
@@ -132,6 +132,7 @@ fn pet_buff(spell_id: u32, name: &str, count: u8) -> AuraState {
 /// `UNIT_PET` is the only wire either edge has, which is why it carries them both.
 #[test]
 fn the_pet_frame_appears_on_a_summon_and_leaves_on_a_dismiss() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
     assert!(
@@ -169,6 +170,7 @@ fn the_pet_frame_appears_on_a_summon_and_leaves_on_a_dismiss() {
 /// this drives each event with the WRONG token and asserts nothing moved.
 #[test]
 fn the_frame_answers_only_the_events_that_name_its_own_unit() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     s.set_unit("pet", Some(pet("Grimjaw", 72, 45, 80, 0)));
     s.fire_event("UNIT_PET", vec![ScriptValue::Str("player".into())]);
@@ -226,6 +228,7 @@ fn the_frame_answers_only_the_events_that_name_its_own_unit() {
 /// because it means the bar comes back only through a value change, never through `PetFrame.lua`.
 #[test]
 fn a_powerless_pet_wears_the_no_mana_plate() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
 
     const PLAIN: &str = "Interface\\TargetingFrame\\UI-SmallTargetingFrame";
@@ -262,6 +265,7 @@ fn a_powerless_pet_wears_the_no_mana_plate() {
 /// repaints the rest of the frame (they are the ref's own early returns).
 #[test]
 fn the_attack_overlay_follows_its_own_two_events() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     s.set_unit("pet", Some(pet("Grimjaw", 72, 45, 80, 0)));
     s.fire_event("UNIT_PET", vec![ScriptValue::Str("player".into())]);
@@ -318,6 +322,7 @@ fn the_attack_overlay_follows_its_own_two_events() {
 ///    house at all; the old assertion was reading a FontString our transcription invented.
 #[test]
 fn the_debuff_row_fills_from_the_pets_own_auras() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     s.set_unit("pet", Some(pet("Grimjaw", 72, 45, 80, 0)));
     s.fire_event("UNIT_PET", vec![ScriptValue::Str("player".into())]);
@@ -366,6 +371,7 @@ fn the_debuff_row_fills_from_the_pets_own_auras() {
 /// the app answers in `target::click::target_unit_requests`' `"pet"` arm.
 #[test]
 fn left_clicking_the_pet_frame_targets_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     s.set_unit("pet", Some(pet("Grimjaw", 72, 45, 80, 0)));
     s.fire_event("UNIT_PET", vec![ScriptValue::Str("player".into())]);
@@ -395,6 +401,7 @@ fn left_clicking_the_pet_frame_targets_it() {
 /// a queued token and no error.
 #[test]
 fn every_leg_of_the_pet_frame_click_reaches_a_live_binding() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     s.set_unit("pet", Some(pet("Grimjaw", 72, 45, 80, 0)));
     s.fire_event("UNIT_PET", vec![ScriptValue::Str("player".into())]);
@@ -489,6 +496,7 @@ fn stats(
 /// branch ran** — `PET_HAPPINESS2` can only come from the `happiness == 2` arm.
 #[test]
 fn the_happiness_icon_shows_per_bucket_and_hides_for_a_non_hunter_pet() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     declare_happiness_strings(&s);
     s.set_unit("pet", Some(pet("Grimjaw", 72, 45, 80, 2)));
@@ -533,9 +541,10 @@ fn the_happiness_icon_shows_per_bucket_and_hides_for_a_non_hunter_pet() {
 
 /// **Bucket 0 keeps the icon up.** The reference hides on `not happiness`, and `0` is truthy in
 /// Lua — so a client that folded bucket 0 into nil would hide a frame the reference shows. This is
-/// the trap wow-re calls out by name, tested where it would actually bite: in the frame.
+/// the `GetPetHappiness 0x4be900` trap, tested where it would actually bite: in the frame.
 #[test]
 fn happiness_bucket_zero_keeps_the_icon_showing() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     declare_happiness_strings(&s);
     s.set_unit("pet", Some(pet("Grimjaw", 72, 45, 80, 2)));
@@ -560,6 +569,7 @@ fn happiness_bucket_zero_keeps_the_icon_showing() {
 /// frame-wide update, so a happiness tick must not be a full repaint.
 #[test]
 fn unit_happiness_repaints_only_the_icon() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_pet_frame();
     declare_happiness_strings(&s);
     s.set_unit("pet", Some(pet("Grimjaw", 72, 45, 80, 2)));
@@ -600,6 +610,7 @@ fn unit_happiness_repaints_only_the_icon() {
 /// the mana bar and simply covers the rail.
 #[test]
 fn the_pet_art_paints_over_the_bars() {
+    benilla_formats::wow_data_or_skip!();
     let s = load_pet_frame();
     let level: (i64, i64, i64) = s
         .eval(
diff --git a/crates/benilla-app/src/ui_script/pet_paperdoll_tests.rs b/crates/benilla-app/src/ui_script/pet_paperdoll_tests.rs
index 6c633ef8..359f8b53 100644
--- a/crates/benilla-app/src/ui_script/pet_paperdoll_tests.rs
+++ b/crates/benilla-app/src/ui_script/pet_paperdoll_tests.rs
@@ -484,11 +484,10 @@ fn hovering_the_diet_icon_lists_what_the_pet_eats() {
     // **The pane's scene draws AFTER the icon, and that is the reference's own order.**
     // `PetPaperDollPetInfo` is a sibling frame of `PetModelFrame` (same parent, so the same
     // `(strata, level)` bucket) and its happiness art is a BACKGROUND texture on it; a model's
-    // scene drains out of that bucket's ARTWORK batch, last (wow-re
-    // `ui/scratch/model-frame-draw-order.md`: `0x76d160` registers the render callback only for
-    // layer 2, and `0x76fb00` drains quads, then text, then callbacks). The icon stays visible
-    // because a model pane is not an opaque quad — the bake is transparent everywhere the pet
-    // is not, here as in the client. This assertion is the ordering, not the pixels.
+    // scene drains out of that bucket's ARTWORK batch, last (`0x76d160` registers the render
+    // callback only for layer 2, and `0x76fb00` drains quads, then text, then callbacks). The icon
+    // stays visible because a model pane is not an opaque quad — the bake is transparent everywhere
+    // the pet is not, here as in the client. This assertion is the ordering, not the pixels.
     assert!(
         pane.z > icon.z,
         "the pane's scene draws out of the ARTWORK batch, after a sibling's BACKGROUND art \
diff --git a/crates/benilla-app/src/ui_script/quest_share_tests.rs b/crates/benilla-app/src/ui_script/quest_share_tests.rs
index f227e232..be27ada0 100644
--- a/crates/benilla-app/src/ui_script/quest_share_tests.rs
+++ b/crates/benilla-app/src/ui_script/quest_share_tests.rs
@@ -42,6 +42,7 @@ fn confirm(s: &mut UiScript, who: &str, quest: &str) {
 /// right at a glance.
 #[test]
 fn the_confirm_names_the_player_first_and_the_quest_second() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     confirm(&mut s, "Thrall", "Escort Duty");
     assert!(
@@ -59,6 +60,7 @@ fn the_confirm_names_the_player_first_and_the_quest_second() {
 /// Yes queues exactly one `ConfirmAcceptQuest()` and closes the popup.
 #[test]
 fn yes_answers_once() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     confirm(&mut s, "Thrall", "Escort Duty");
     s.run("StaticPopup_OnClick(StaticPopup1, 1)").unwrap();
@@ -75,6 +77,7 @@ fn yes_answers_once() {
 /// latch is cleared by the next thing that touches it. Same for ESC.
 #[test]
 fn no_and_escape_send_nothing() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     confirm(&mut s, "Thrall", "Escort Duty");
     s.run("StaticPopup_OnClick(StaticPopup1, 2)").unwrap();
@@ -92,6 +95,7 @@ fn no_and_escape_send_nothing() {
 /// stale popup would send the wrong quest id.
 #[test]
 fn a_second_confirm_replaces_the_first() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     confirm(&mut s, "Thrall", "Escort Duty");
     confirm(&mut s, "Jaina", "Deeper Still");
diff --git a/crates/benilla-app/src/ui_script/quest_tests.rs b/crates/benilla-app/src/ui_script/quest_tests.rs
index e7427f64..7d431991 100644
--- a/crates/benilla-app/src/ui_script/quest_tests.rs
+++ b/crates/benilla-app/src/ui_script/quest_tests.rs
@@ -15,6 +15,7 @@ use super::test_ui::load_ui as load_xml;
 /// Same pair as gossip — questgiver and gossip are the same "list" surface to the client.
 #[test]
 fn questgiver_show_hide_plays_open_and_close_kits() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -86,6 +87,7 @@ fn questgiver_show_hide_plays_open_and_close_kits() {
 /// stays open is silent).
 #[test]
 fn panel_events_show_exactly_one_child_panel_and_hide_the_others() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -185,6 +187,7 @@ fn panel_events_show_exactly_one_child_panel_and_hide_the_others() {
 /// have and a split the ref's own function cannot be written against.
 #[test]
 fn detail_panel_reward_grid_follows_the_refs_two_per_row_layout() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -288,6 +291,7 @@ fn detail_panel_reward_grid_follows_the_refs_two_per_row_layout() {
 /// the highlight and arms `GetQuestReward`'s 1-based→0-based conversion.
 #[test]
 fn reward_panel_choice_click_selects_and_completes_with_zero_based_index() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -368,6 +372,7 @@ fn reward_panel_choice_click_selects_and_completes_with_zero_based_index() {
 /// v1 layout never carried) — a plain client-side close, no `DeclineQuest()` call (ref l.748-752).
 #[test]
 fn greeting_goodbye_button_closes_the_window() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -426,6 +431,7 @@ fn greeting_goodbye_button_closes_the_window() {
 /// The write-on arm is `write_on_still_fades_when_instant_text_is_off`'s subject.
 #[test]
 fn detail_panel_action_buttons_resolve_to_real_onscreen_rects() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -555,6 +561,7 @@ fn detail_panel_action_buttons_resolve_to_real_onscreen_rects() {
 /// objectives/rewards block FADES in over QUESTINFO_FADE_IN rather than snapping.
 #[test]
 fn write_on_still_fades_when_instant_text_is_off() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -633,6 +640,7 @@ fn write_on_still_fades_when_instant_text_is_off() {
 /// update it too (the 0112-era capture showed a permanently blank bar).
 #[test]
 fn npc_name_reaches_the_title_bar_on_open_and_on_refresh() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -713,6 +721,7 @@ fn npc_name_reaches_the_title_bar_on_open_and_on_refresh() {
 /// 6 px/char × 14 px/line measure fake as the gossip row test.
 #[test]
 fn greeting_panel_title_rows_grow_to_their_wrapped_titles() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // Stock sizes each row at show time — `SetHeight(GetTextHeight() + 2)` right after SetText
@@ -818,6 +827,7 @@ fn greeting_panel_title_rows_grow_to_their_wrapped_titles() {
 /// it closes the giver window, exactly as it does in play.
 #[test]
 fn reward_rows_preview_and_post_without_selecting_the_choice() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
diff --git a/crates/benilla-app/src/ui_script/quest_timer_tests.rs b/crates/benilla-app/src/ui_script/quest_timer_tests.rs
index 62a1a49f..f846927d 100644
--- a/crates/benilla-app/src/ui_script/quest_timer_tests.rs
+++ b/crates/benilla-app/src/ui_script/quest_timer_tests.rs
@@ -71,6 +71,7 @@ fn log(entries: Vec<QuestLogEntryView>) -> QuestLogState {
     QuestLogState {
         num_quests: entries.len() as u32,
         entries,
+        hidden_quest_ids: Vec::new(),
     }
 }
 
@@ -180,30 +181,3 @@ fn a_world_entry_paints_a_quest_already_running() {
     // gap reads 89 through the `−1`.
     assert_eq!(row_text(&s, 1), "1 Min 29 Secs ");
 }
-
-/// **The reference file is the test oracle** (decision 0675). Scrapes both this window and the
-/// extracted reference `QuestTimerFrame.xml` for `<AbsDimension>` pairs per named element and
-/// asserts every shared element's numbers match — the guard that catches a transcription whose
-/// frames all load, click and populate while every number is wrong.
-///
-/// Verified to fail: perturbing `QuestTimer1`'s TOP offset from -30 to -29 reports
-/// `QuestTimer1: ours [(140.0, 16.0), (0.0, -29.0)] != ref [(140.0, 16.0), (0.0, -30.0)]`.
-#[test]
-fn the_window_geometry_matches_the_reference_framexml() {
-    let _data = benilla_formats::wow_data_or_skip!();
-    let Some(reference) =
-        super::framexml_diff::reference("Interface\\FrameXML\\QuestTimerFrame.xml")
-    else {
-        eprintln!("skipping: no extracted FrameXML");
-        return;
-    };
-    // No exemptions: this window's frames keep the reference's bare names (decision 0591 §3 — the
-    // manage pass and the ref's own row lookup both resolve by literal name), and every number in
-    // it is the reference's. If an entry ever needs to go here, it names its reason.
-    super::framexml_diff::assert_geometry_matches(
-        "Interface\\FrameXML\\QuestTimerFrame.xml",
-        &reference,
-        &[],
-        22,
-    );
-}
diff --git a/crates/benilla-app/src/ui_script/questlog_tests.rs b/crates/benilla-app/src/ui_script/questlog_tests.rs
index 8b8c1ec6..7fa26f9b 100644
--- a/crates/benilla-app/src/ui_script/questlog_tests.rs
+++ b/crates/benilla-app/src/ui_script/questlog_tests.rs
@@ -80,6 +80,7 @@ fn eight_entries() -> QuestLogState {
     QuestLogState {
         num_quests: 8,
         entries,
+        hidden_quest_ids: Vec::new(),
     }
 }
 
@@ -167,7 +168,8 @@ fn shipped_questlog_frame_drives_end_to_end() {
     );
 
     // Row 1 carries entry 1's title (indented), the count line reads "Quests: |cffffffff8/20|r", and nothing having been
-    // selected, the first non-header entry auto-selects (pin §2's SetFirstValidSelection).
+    // selected, the first non-header entry auto-selects (`QuestLog_SetFirstValidSelection`,
+    // `QuestLogFrame.lua:295`).
     assert!(s
         .eval::<String>("return QuestLogTitle1NormalText:GetText()")
         .unwrap()
@@ -473,7 +475,7 @@ fn shift_click_toggles_the_watch_checkbox_and_the_tracker_hud() {
 /// Shift-clicking a quest with zero objectives (ref `QUEST_WATCH_NO_OBJECTIVES`) and shift-clicking
 /// past `GetNumQuestWatches() >= 5` (ref `QUEST_WATCH_TOO_MANY`) both refuse the watch and put the
 /// ref's red line on the errors frame through its own `UIErrorsFrame:AddMessage`; the click still
-/// selects the row exactly like any other click (pin §5).
+/// selects the row exactly like any other click.
 #[test]
 fn watch_guards_no_op_without_erroring() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -586,7 +588,7 @@ fn watch_guards_no_op_without_erroring() {
 /// The auto quest watch (ref `AUTO_QUEST_WATCH` default-on, QuestLogFrame.lua:702-786 —
 /// "Quests are automatically watched for 5 minutes when you achieve a quest objective."): the
 /// engine's per-quest `BENILLA_QUEST_PROGRESS(logIndex)` arms a 300 s timed watch (the native
-/// QUEST_WATCH_UPDATE carries the WATCH-LIST index per the §5-verified byte law — repaint only,
+/// QUEST_WATCH_UPDATE carries the WATCH-LIST index from `0x4df880` — repaint only,
 /// the shipped 1.12 auto-watch chain being broken at that seam), fresh progress
 /// re-arms it, and expiry (the watch frame's OnUpdate) unwatches and hides the empty HUD.
 #[test]
@@ -1065,6 +1067,7 @@ fn overflowing_entry() -> QuestLogState {
         .collect();
     QuestLogState {
         num_quests: 1,
+        hidden_quest_ids: Vec::new(),
         entries: vec![QuestLogEntryView {
             quest_id: 1,
             title: "A Very Long Quest".into(),
@@ -1232,7 +1235,7 @@ fn wheel_over_the_detail_pane_changes_vertical_scroll() {
     );
 }
 
-/// Pin §3/§5's doNotScroll asymmetry (QUESTLOG-PIN.md, `QuestLogFrame.lua:348/455-457`): a manual
+/// The reference's doNotScroll asymmetry (`QuestLogFrame.lua:348/455-457`): a manual
 /// reselect always snaps the detail pane's scroll back to the top, but the `QUEST_LOG_UPDATE`
 /// data-refresh path must NOT — a quest updating while already being read shouldn't yank the
 /// reader's scroll position out from under them.
@@ -1293,7 +1296,7 @@ fn selection_change_resets_detail_scroll_but_a_quest_log_update_refresh_does_not
         s.eval::<f32>("return QuestLogDetailScrollFrame:GetVerticalScroll()")
             .unwrap(),
         10.0,
-        "QUEST_LOG_UPDATE's data-refresh path must not yank the scroll position (pin §5)"
+        "QUEST_LOG_UPDATE's data-refresh path must not yank the scroll position"
     );
 
     // A manual reselect (the row-click path — no doNotScroll) DOES reset it.
@@ -1856,7 +1859,7 @@ fn share_quest_click_queues_the_selected_quests_id() {
 /// It is correct, and the reading was wrong about our own engine: the title FontString carries a
 /// DECLARED height (`<ButtonText …><AbsDimension x="0" y="10"/>`), which arms both overflow
 /// regimes — the line stack and the height-gated ellipsis — so the paint is one truncated line,
-/// which is the reference's own result (wow-re `fontstring-overflow.md`: the ellipsis gate is
+/// which is the reference's own result (`0x771ec0`'s ellipsis gate is
 /// `boxW > 0 && boxH > 0`, and only an AUTO-height FontString escapes it). The render half is
 /// pinned on the real font in `ui_text::layout`'s
 /// `a_capped_quest_log_title_ellipsizes_on_one_line`; this is the geometry half — that the row
diff --git a/crates/benilla-app/src/ui_script/quiver_tests.rs b/crates/benilla-app/src/ui_script/quiver_tests.rs
index 12a6d5c3..22597bc2 100644
--- a/crates/benilla-app/src/ui_script/quiver_tests.rs
+++ b/crates/benilla-app/src/ui_script/quiver_tests.rs
@@ -37,27 +37,12 @@ use std::path::{Path, PathBuf};
 use benilla_ui::script::{ScriptValue, UiScript, UnitState};
 use benilla_ui::toc::Toc;
 
-/// Where the vanilla addon corpus might be — `$BENILLA_ADDON_CORPUS`, else a sibling checkout
-/// resolved from this crate's manifest (a pool worktree's cwd is not stable across tool calls).
-fn corpus_candidates() -> Vec<PathBuf> {
-    let mut out = Vec::new();
-    if let Some(over) = std::env::var_os("BENILLA_ADDON_CORPUS") {
-        out.push(PathBuf::from(over));
-    }
-    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
-    for up in [2usize, 3, 4] {
-        if let Some(root) = manifest.ancestors().nth(up) {
-            out.push(root.join("wow-addons-vanilla"));
-        }
-    }
-    out
-}
-
 /// The corpus root **and** a Quiver in it, or `None` — a skip, never a failure. Quiver is a live
 /// third-party addon (`github.com/SabineWren/Quiver`) whose shipped file is a generated bundle, so
-/// a machine that wants this test builds it into the corpus once.
+/// a machine that wants this test builds it into the corpus once. The corpus itself resolves
+/// through `benilla_formats::addon_corpus` — the one resolver, whose doc carries the incident.
 fn quiver_root() -> Option<PathBuf> {
-    corpus_candidates()
+    benilla_formats::addon_corpus_candidates()
         .into_iter()
         .find(|c| c.join("Quiver").join("Quiver.toc").is_file())
 }
@@ -67,10 +52,10 @@ macro_rules! quiver_or_skip {
         match quiver_root() {
             Some(root) => root,
             None => {
-                eprintln!(
-                    "skipping: no Quiver in the addon corpus — looked in {:?} \
-                     (set $BENILLA_ADDON_CORPUS; the folder needs Quiver.toc + Quiver.bundle.lua)",
-                    corpus_candidates()
+                benilla_formats::skipped(
+                    "no Quiver in the addon corpus (set $BENILLA_ADDON_CORPUS; the folder needs \
+                     Quiver.toc + Quiver.bundle.lua)",
+                    &benilla_formats::addon_corpus_candidates(),
                 );
                 return;
             }
@@ -217,6 +202,7 @@ fn seat_a_hunter(root: &Path) -> UiScript {
 /// again even if it left a different error behind.
 #[test]
 fn quiver_publishes_its_global_functions_for_a_hunter() {
+    benilla_formats::wow_data_or_skip!();
     let root = quiver_or_skip!();
     let mut s = seat_a_hunter(&root);
 
@@ -264,6 +250,7 @@ fn quiver_publishes_its_global_functions_for_a_hunter() {
 /// the test that names a *new* wall the moment one appears, instead of reporting a nil field.
 #[test]
 fn quiver_survives_a_hunter_session_start_without_raising() {
+    benilla_formats::wow_data_or_skip!();
     let root = quiver_or_skip!();
     let mut s = seat_a_hunter(&root);
     assert!(load_addon_files(&s, &root, "Quiver").is_empty());
@@ -337,6 +324,7 @@ fn shot_state(s: &mut UiScript) -> (bool, bool, f64, f64) {
 /// forever for a shot it is never told about — which is a bar pinned at 100%.
 #[test]
 fn auto_shot_bar_saturates_when_no_ammo_lock_event_ever_arrives() {
+    benilla_formats::wow_data_or_skip!();
     let root = quiver_or_skip!();
     let mut s = seat_a_hunter(&root);
     seat_a_bow(&mut s);
@@ -368,6 +356,7 @@ fn auto_shot_bar_saturates_when_no_ammo_lock_event_ever_arrives() {
 /// the addon, on `SetWidth`, or on the standing-still check.
 #[test]
 fn auto_shot_bar_drains_the_moment_an_ammo_lock_event_arrives() {
+    benilla_formats::wow_data_or_skip!();
     let root = quiver_or_skip!();
     let mut s = seat_a_hunter(&root);
     seat_a_bow(&mut s);
@@ -451,6 +440,7 @@ fn draws(s: &mut UiScript, leaf: &str) -> bool {
 /// dependency of ours, and a break in any of them shows up here as a missing quad.
 #[test]
 fn aspect_tracker_draws_the_icon_for_an_active_aspect() {
+    benilla_formats::wow_data_or_skip!();
     let root = quiver_or_skip!();
     let mut s = seat_a_hunter(&root);
     assert!(load_addon_files(&s, &root, "Quiver").is_empty());
@@ -492,6 +482,7 @@ fn aspect_tracker_draws_the_icon_for_an_active_aspect() {
 /// Hawk is up" and failed — the addon was right and the test was wrong.
 #[test]
 fn the_hawk_reminder_is_suppressed_only_once_frames_are_locked() {
+    benilla_formats::wow_data_or_skip!();
     let root = quiver_or_skip!();
     let mut s = seat_a_hunter(&root);
     assert!(load_addon_files(&s, &root, "Quiver").is_empty());
@@ -531,6 +522,7 @@ fn the_hawk_reminder_is_suppressed_only_once_frames_are_locked() {
 /// spent**, which is the half that was missing (decision 1509).
 #[test]
 fn spending_an_arrow_starts_quivers_reload_through_the_real_item_feed() {
+    benilla_formats::wow_data_or_skip!();
     use crate::ui_items::feed::{apply_container_source, FeedMemory};
     use benilla_ui::script::{ContainerSlot, ContainerState};
     use std::collections::HashMap;
@@ -565,6 +557,7 @@ fn spending_an_arrow_starts_quivers_reload_through_the_real_item_feed() {
         quiver(200),
         Default::default(),
         Vec::new(),
+        Vec::new(),
     );
 
     s.fire_event("START_AUTOREPEAT_SPELL", Vec::new());
@@ -580,6 +573,7 @@ fn spending_an_arrow_starts_quivers_reload_through_the_real_item_feed() {
         quiver(199),
         Default::default(),
         Vec::new(),
+        Vec::new(),
     );
     s.tick(0.1);
 
diff --git a/crates/benilla-app/src/ui_script/reference_ui.rs b/crates/benilla-app/src/ui_script/reference_ui.rs
index 2963606d..ab55a61c 100644
--- a/crates/benilla-app/src/ui_script/reference_ui.rs
+++ b/crates/benilla-app/src/ui_script/reference_ui.rs
@@ -259,7 +259,7 @@ mod tests {
     /// Strip what is not code, before any call census over a FrameXML file.
     ///
     /// Both `Name(` and `:Name(` counted calls inside comments until decision 1800: the round that
-    /// built `PickupMerchantItem` also asked wow-re for `ShowInventorySellCursor`, which
+    /// built `PickupMerchantItem` also asked about `ShowInventorySellCursor`, which
     /// [`chain_gap_report`] had named as `PaperDollFrame.xml`'s last engine gap — and the answer
     /// was that stock `PaperDollFrame.lua:754-756` has the call **commented out**, all three
     /// lines. A real binding, never called, blocking a window that was not blocked.
@@ -433,7 +433,7 @@ mod tests {
 
         // Order still decides, and it is still the whole rule — so it is asserted directly rather
         // than through whichever window happens to collide this month. Two chunks, the same name,
-        // and the later one stands; `publish_global`'s non-overwriting rule (RF-0023) applies to
+        // and the later one stands; `publish_global`'s non-overwriting rule (`0x701bd0`) applies to
         // FRAMES, never to a plain Lua global, and confusing the two has produced confident wrong
         // diagnoses before.
         s.run("function _order_probe() return 1 end").unwrap();
@@ -482,7 +482,7 @@ mod tests {
     ///
     /// A candidate whose frame NAMES our own shipped file already owns produces failures that are
     /// artefacts of the probe, not of the window. `publish_global` is deliberately non-overwriting
-    /// (RF-0023), so the second frame to claim a name gets a wrapper that `_G` never points at —
+    /// (`0x701bd0`), so the second frame to claim a name gets a wrapper that `_G` never points at —
     /// and any reference body using the `getglobal(this:GetName())` idiom then reads a DIFFERENT
     /// table than the `this` it just wrote to.
     ///
@@ -998,11 +998,11 @@ mod tests {
             // wrong (1801). So this one runs the load itself — the same fresh-VM-plus-manifest
             // pass the readiness probe does — and reports it in the same row.
             // **A `LOAD:` line for a window we ALSO ship is suspect**, and the reason is the same
-            // one `chain_readiness_report` carries: `publish_global` is non-overwriting (RF-0023),
-            // so loading the stock file on top of our identically-named one leaves every colliding
-            // frame's global pointing at OUR frame while the stock file's handlers run against
-            // THEIRS. A field set on `this` in an OnLoad is then invisible to `getglobal(name)`,
-            // and the failure looks like a bug in whatever read it back.
+            // one `chain_readiness_report` carries: `publish_global` is non-overwriting
+            // (`0x701bd0`), so loading the stock file on top of our identically-named one leaves
+            // every colliding frame's global pointing at OUR frame while the stock file's handlers
+            // run against THEIRS. A field set on `this` in an OnLoad is then invisible to
+            // `getglobal(name)`, and the failure looks like a bug in whatever read it back.
             //
             // Worked example, because it cost an hour: stock `TradeFrame.xml` reported
             // `MoneyFrame.xml:525: attempt to index local 'info'`. Nothing was wrong with our
@@ -1523,7 +1523,7 @@ mod tests {
             (
                 "SkillFrame.xml",
                 "BuySkillTier",
-                "a 5875 binding (wow-re `bindings.md`: marshals and delegates to a C++ \
+                "a 5875 binding (`0x4d3e50`: marshals and delegates to a C++ \
                  method/net-send) of the pre-1.12 skill-point purchase UI. the detail bar's LearnSkillButton calls it, and \
                  that button shows only while `UnitCharacterPoints`'s second value or a row's \
                  step/rank cost is non-zero — which no 1.12 server sends. Unreachable until the \
@@ -1532,7 +1532,7 @@ mod tests {
             (
                 "SkillFrame.xml",
                 "AddSkillUp",
-                "a 5875 binding (wow-re `bindings.md`: marshals and delegates to a C++ \
+                "a 5875 binding (`0x4d3c30`: marshals and delegates to a C++ \
                  method/net-send) of the pre-1.12 skill-point purchase UI. the detail bar's RightArrow calls it, and \
                  that button shows only while `UnitCharacterPoints`'s second value or a row's \
                  step/rank cost is non-zero — which no 1.12 server sends. Unreachable until the \
@@ -1541,7 +1541,7 @@ mod tests {
             (
                 "SkillFrame.xml",
                 "RemoveSkillUp",
-                "a 5875 binding (wow-re `bindings.md`: marshals and delegates to a C++ \
+                "a 5875 binding (`0x4d3c70`: marshals and delegates to a C++ \
                  method/net-send) of the pre-1.12 skill-point purchase UI. the detail bar's LeftArrow calls it, and \
                  that button shows only while `UnitCharacterPoints`'s second value or a row's \
                  step/rank cost is non-zero — which no 1.12 server sends. Unreachable until the \
@@ -1593,8 +1593,8 @@ mod tests {
             (
                 "StaticPopup.xml",
                 "ReplaceTradeEnchant",
-                "a registered 1.12 binding whose body is uncarved (wow-re `bindings.md`, structural row only); a \
-                 wow-re orchestrator is out on it and it is built when the carve lands (1960). Reached by TRADE_REPLACE_ENCHANT's Accept, an event this engine does not fire yet.",
+                "a registered 1.12 binding (`0x48d330`) whose body is not yet known; it is built \
+                 once it is (1960). Reached by TRADE_REPLACE_ENCHANT's Accept, an event this engine does not fire yet.",
             ),
         ];
 
@@ -2331,8 +2331,8 @@ mod tests {
                 "TRADE_REQUEST",
                 "UIParent.lua — the trade ASK dialog, and the one entry on this list that is \
                  UNPRODUCEABLE rather than unbuilt: the 5875 client registers the event and \
-                 signals it from NOWHERE (a whole-image census, wow-re \
-                 ui/scratch/incoming-trade-request-law.md §3), so StaticPopupDialogs[\"TRADE\"] is \
+                 signals it from NOWHERE (a whole-image census: no signal site passes its id, \
+                 `0x11d`), so StaticPopupDialogs[\"TRADE\"] is \
                  dead code THERE too. benilla wired the dialog up once and took it back out — \
                  decision 1764. Producing this would be a divergence, not a fix",
             ),
@@ -2341,7 +2341,6 @@ mod tests {
                 "UIParent.lua — the enchant-replacement confirm inside a trade; benilla's trade \
                  feed does not derive it",
             ),
-            ("BAG_OPEN", "ContainerFrame.lua"),
             (
                 "CLOSE_WORLD_MAP",
                 "WorldMapFrame.lua — the engine-side close the reference fires when the map is \
@@ -2363,8 +2362,8 @@ mod tests {
             (
                 "SHOW_COMPARE_TOOLTIP",
                 "PaperDollFrame.lua — the second `TRADE_REQUEST` (decision 1764): event 377 is \
-                 registered in 5875 and signalled from NOWHERE (zero fire sites in wow-re's own \
-                 census, `merchant-compare-item-law.md` §8), so this listener is dead code THERE \
+                 registered in 5875 and signalled from NOWHERE (zero fire sites in the whole \
+                 image), so this listener is dead code THERE \
                  too. benilla fired it from 0283 until 2202, then drove the plates itself on a \
                  shift-held hover until 2210; both were supersets. Nothing in this engine seats a \
                  shopping plate now — the reference's own callers do (`MerchantFrame.xml:63-80`, \
diff --git a/crates/benilla-app/src/ui_script/reputation_frame_tests.rs b/crates/benilla-app/src/ui_script/reputation_frame_tests.rs
index 0610f669..5549f0f4 100644
--- a/crates/benilla-app/src/ui_script/reputation_frame_tests.rs
+++ b/crates/benilla-app/src/ui_script/reputation_frame_tests.rs
@@ -537,11 +537,11 @@ fn clicking_a_bar_opens_the_detail_popup_on_that_faction() {
 /// gates its hide-old step on the new state having a texture, so the `UI-CheckBox-Up` box stays up
 /// and the row reads "a greyed **At War** beside an empty box". Ours resolved the shown texture as
 /// a pure function of the state, hid it, and left a bare grey label with nothing beside it — which
-/// is what MarcusAga photographed on Ironforge.
+/// is how the Ironforge row drew.
 ///
 /// Three rows, because the tick is the half that made the report confusing: a peace-forced faction
 /// that is NOT at war shows the empty box (the shot), a peace-forced faction that IS at war shows
-/// the box plus its grey `DisabledCheckedTexture` (*"the tick renders, however"*), and a
+/// the box plus its grey `DisabledCheckedTexture` (the tick still draws), and a
 /// toggleable one is the control that must not move.
 #[test]
 fn the_at_war_box_keeps_its_art_while_it_is_disabled() {
diff --git a/crates/benilla-app/src/ui_script/resolve_bench.rs b/crates/benilla-app/src/ui_script/resolve_bench.rs
index de0f32d6..fc435c40 100644
--- a/crates/benilla-app/src/ui_script/resolve_bench.rs
+++ b/crates/benilla-app/src/ui_script/resolve_bench.rs
@@ -156,6 +156,7 @@ fn tooltip_change_costs_a_whole_ui_solve() {
 /// about the second solve is tooltip-sized, and nothing about it is cheap.
 #[test]
 fn a_tooltip_content_change_costs_exactly_one_layout_solve() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     install_changing_tooltip(&s, "GateOwner", "gate_change");
 
@@ -215,6 +216,7 @@ fn a_tooltip_content_change_costs_exactly_one_layout_solve() {
 /// backtracing the touch sites on a live run.
 #[test]
 fn the_settled_shipped_ui_costs_no_gate_walk_on_a_quiet_frame() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     // Ticked frames, so the shipped UI's own OnUpdate handlers run — the whole point (see
     // `app_frame_ticked`). A couple of frames of grace first: `settled_default_ui` stops as soon
@@ -272,6 +274,7 @@ fn the_settled_shipped_ui_costs_no_gate_walk_on_a_quiet_frame() {
 ///   walks was exactly that, so the old counter under-reported the bug by a third.
 #[test]
 fn a_region_moving_every_frame_costs_one_gate_walk_on_the_shipped_ui() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     s.run(
         r#"
@@ -356,6 +359,7 @@ fn a_region_moving_every_frame_costs_one_gate_walk_on_the_shipped_ui() {
 /// everything else, and only a ticked frame can see that.
 #[test]
 fn a_region_moving_every_frame_costs_no_graph_derivation_on_the_shipped_ui() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     s.run(
         r#"
@@ -424,6 +428,7 @@ fn a_region_moving_every_frame_costs_no_graph_derivation_on_the_shipped_ui() {
 /// skipped as well as the ones it resolved.
 #[test]
 fn a_tooltip_content_change_solves_a_tooltip_sized_scope() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     install_changing_tooltip(&s, "ScopeSizeOwner", "scope_size_change");
 
@@ -457,6 +462,7 @@ fn a_tooltip_content_change_solves_a_tooltip_sized_scope() {
 /// bug, and a stale rect that one does carry is the bug in the form the screen would show it.
 #[test]
 fn a_scoped_resolve_reproduces_the_whole_graph_solve() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     install_changing_tooltip(&s, "ScopeOwner", "scope_change");
 
@@ -530,6 +536,7 @@ fn measure_sweep_steady_state_cost() {
 /// structural) and the counter is proved able to move.
 #[test]
 fn a_tooltip_line_flipping_wrapped_to_plain_costs_no_graph_derivation() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     s.run(
         r#"
@@ -601,6 +608,7 @@ fn a_tooltip_line_flipping_wrapped_to_plain_costs_no_graph_derivation() {
 /// is big enough for the derivation to matter.
 #[test]
 fn a_hover_sweep_across_owners_costs_no_graph_derivation() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     s.run(
         r#"
@@ -676,6 +684,7 @@ fn a_hover_sweep_across_owners_costs_no_graph_derivation() {
 /// idiom, not the gesture.
 #[test]
 fn an_action_bar_hover_sweep_costs_no_graph_derivation() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     s.run(
         r#"
@@ -752,6 +761,7 @@ fn an_action_bar_hover_sweep_costs_no_graph_derivation() {
 /// addons. `derives/frame` read 0.88 with Bagnon and 0.00 without.
 #[test]
 fn a_bag_addon_hover_sweep_costs_no_graph_derivation() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = settled_default_ui();
     s.run(
         r#"
diff --git a/crates/benilla-app/src/ui_script/screenshot_tests.rs b/crates/benilla-app/src/ui_script/screenshot_tests.rs
index 3cd6fa0e..479c7694 100644
--- a/crates/benilla-app/src/ui_script/screenshot_tests.rs
+++ b/crates/benilla-app/src/ui_script/screenshot_tests.rs
@@ -50,6 +50,7 @@ fn alpha(s: &UiScript) -> f64 {
 /// captured cannot contain it.
 #[test]
 fn the_capture_is_asked_for_silently_and_only_the_answer_speaks() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     assert!(!shown(&s), "the status line starts hidden");
 
@@ -76,6 +77,7 @@ fn the_capture_is_asked_for_silently_and_only_the_answer_speaks() {
 /// engine is asked — otherwise that shot would have "Screen Captured" printed across it.
 #[test]
 fn a_second_press_inside_the_fade_clears_the_line_before_capturing() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event("SCREENSHOT_SUCCEEDED", Vec::new());
     s.tick(0.5);
@@ -97,6 +99,7 @@ fn a_second_press_inside_the_fade_clears_the_line_before_capturing() {
 /// The 1.5 s fade: alpha falls with elapsed time and the frame takes itself off screen at the end.
 #[test]
 fn the_line_fades_out_over_the_reference_s_second_and_a_half() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event("SCREENSHOT_SUCCEEDED", Vec::new());
 
@@ -114,6 +117,7 @@ fn the_line_fades_out_over_the_reference_s_second_and_a_half() {
 /// The failure path says so, in the reference's own words.
 #[test]
 fn a_failed_capture_shows_the_failure_string() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event("SCREENSHOT_FAILED", Vec::new());
     assert!(shown(&s));
diff --git a/crates/benilla-app/src/ui_script/shape_gate.rs b/crates/benilla-app/src/ui_script/shape_gate.rs
index a6028026..9234dfcf 100644
--- a/crates/benilla-app/src/ui_script/shape_gate.rs
+++ b/crates/benilla-app/src/ui_script/shape_gate.rs
@@ -15,9 +15,9 @@
 //! `1` — reads a `true` as "not held". So the kinds column is gated as well, wherever the table
 //! says it is trustworthy (decision 2118).
 //!
-//! The table is wow-re's `re/audit/binding-shapes.tsv`, vendored: 1722 rows over all 82 registrar
-//! tables, one per registered binding, generated and differentially tested against that repo's
-//! other harvester. It carries the gate rule **per row** rather than in prose, which is the whole
+//! The table is a harvest of the reference binary, vendored: 1722 rows over all 82 registrar
+//! tables, one per registered binding, generated and differentially tested against a second
+//! harvester. It carries the gate rule **per row** rather than in prose, which is the whole
 //! reason it can be enforced instead of remembered:
 //!
 //! * `arity_conf = exact` — sound. This is the column to gate on.
@@ -71,9 +71,9 @@ const NOT_YET_ASSERTED: &[(&str, usize, &str)] = &[];
 /// two it held did exactly that, within the day.
 ///
 /// **It is empty.** It held `GetSendMailItem`, whose no-attachment leg the shapes table types as
-/// two numbers and no recorded note gave the values of. wow-re answered it at the bytes —
-/// `0x4ae590` pushes `(nil, nil, 0, 0)`, and the stray `1` we had was borrowed from
-/// `GetAuctionSellItemInfo`'s empty leg — and 2129 folded the verdict back.
+/// two numbers without their values. The bytes answer it — `0x4ae590` pushes `(nil, nil, 0, 0)`,
+/// and the stray `1` we had was borrowed from `GetAuctionSellItemInfo`'s empty leg — and 2129
+/// folded the verdict back.
 const KINDS_NOT_YET_ASSERTED: &[(&str, &str, &str)] = &[];
 
 /// The widget kind gate's shrinking list — see [`KINDS_NOT_YET_ASSERTED`].
@@ -124,12 +124,11 @@ fn rows_of_kind(kind: &str) -> Vec<Row> {
                 return None;
             }
             // **`agree` is necessary and not sufficient, and the second condition is the table's
-            // own too** (2150 + wow-re `scratch/binding-kinds-stack-overwrite.md`). The kinds
-            // come from tracing each binding's `lua_push*` calls; a row whose notes carry
-            // `delegated-push` has a CALLEE that pushes on its own behalf, which the trace sees
-            // one level too high up, so its tuple covers the binding's own ops only. `eax` is
-            // unaffected, so arity stays gated on every row — it is the kinds claim alone that
-            // narrows.
+            // own too** (2150). The kinds come from tracing each binding's `lua_push*` calls; a row
+            // whose notes carry `delegated-push` has a CALLEE that pushes on its own behalf, which
+            // the trace sees one level too high up, so its tuple covers the binding's own ops only.
+            // `eax` is unaffected, so arity stays gated on every row — it is the kinds claim alone
+            // that narrows.
             let delegated = f.len() > 11 && f[11].contains("delegated-push");
             Some(Row {
                 name: f[0].to_string(),
@@ -322,7 +321,7 @@ fn every_query_binding_answers_the_reference_s_return_arity() {
 const BASELIB_PROBES: &[(&str, &str)] = &[
     ("collectgarbage", ""),
     ("date", ""),
-    // The five shipped stubs — `xor eax,eax; ret` in the image (`lua-dialect.md` §3a), so calling
+    // The five shipped stubs — `xor eax,eax; ret` in the image (`0x7027e0`–`0x702820`), so calling
     // one is as safe here as it is there, and their `0 exact ()` rows are still worth holding.
     ("debugbreak", ""),
     ("debugdump", ""),
diff --git a/crates/benilla-app/src/ui_script/shipped_xml_tests.rs b/crates/benilla-app/src/ui_script/shipped_xml_tests.rs
index 02a7c570..cf409a13 100644
--- a/crates/benilla-app/src/ui_script/shipped_xml_tests.rs
+++ b/crates/benilla-app/src/ui_script/shipped_xml_tests.rs
@@ -49,6 +49,7 @@ fn every_shipped_ui_xml_parses() {
 /// window's entry is covered the moment it is added rather than when someone remembers to test it.
 #[test]
 fn the_whole_shipped_manifest_loads_without_errors() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.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
@@ -88,6 +89,7 @@ fn the_whole_shipped_manifest_loads_without_errors() {
 /// every single launch.
 #[test]
 fn loading_the_shipped_ui_queues_no_sounds() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.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
@@ -154,6 +156,7 @@ fn pet_bar_vm() -> benilla_ui::script::UiScript {
 /// catch a third template added with a borrowed number.
 #[test]
 fn the_autocast_brackets_reach_each_buttons_corners() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::framexml::{Element, TopLevel};
 
     /// The fraction of `UI-AutoCastableOverlay.blp` the bracket art actually covers, measured off
@@ -252,6 +255,7 @@ fn the_autocast_brackets_reach_each_buttons_corners() {
 /// drifting, or being "corrected" back to 1.22 by someone who only read the ref.
 #[test]
 fn the_shine_panes_ask_for_the_rims_we_meant() {
+    benilla_formats::wow_data_or_skip!();
     let mut found: Vec<(String, f32, f32)> = Vec::new();
     let mut s = super::spellbook_tests::spellbook_ui(1024.0, 768.0);
     s.run("ToggleSpellBook(BOOKTYPE_SPELL)").unwrap();
@@ -530,10 +534,10 @@ fn every_archive_path_a_shipped_lua_chunk_names_survives_its_own_escaping() {
             }
         }
     }
-    // Never let the sweep pass by matching nothing (19 after 1971, 8 after 1980, 4 after 1987;
-    // the floor follows the census down as windows migrate).
+    // Never let the sweep pass by matching nothing; the floor follows the census down as windows
+    // migrate.
     assert!(
-        paths.len() >= 4,
+        paths.len() >= 3,
         "only {} archive paths swept out of the shipped Lua",
         paths.len()
     );
@@ -577,10 +581,9 @@ fn every_archive_path_a_shipped_lua_chunk_names_survives_its_own_escaping() {
 /// **Every `text=` in the shipped UI is answerable against the REAL `GlobalStrings.lua`** — the
 /// tripwire for the defect that put "CREATE_MACROS" across the macro window's title bar (0991).
 ///
-/// `text=` is a global-string LOOKUP, not a literal (wow-re rf28 l.36/l.115 → `FrameScript_GetText
-/// 0x703bf0`). The loader didn't do the lookup at all, so **23 key-shaped values across six
-/// windows** were rendering as their own key names — and nothing anywhere said so. Two halves, both
-/// needed:
+/// `text=` is a global-string LOOKUP, not a literal (`FrameScript_GetText 0x703bf0`). The loader
+/// didn't do the lookup at all, so **23 key-shaped values across six windows** were rendering as
+/// their own key names — and nothing anywhere said so. Two halves, both needed:
 ///
 /// - a **key-shaped** value (`SCREAMING_SNAKE`) must resolve to a non-empty string, or it reaches a
 ///   real screen as its own key;
@@ -779,6 +782,7 @@ fn no_shipped_script_sets_a_global_string_key_as_display_text() {
 /// churn on every action-bar edit, and a noisy gate is a gate nobody reads.
 #[test]
 fn every_texture_frame_outranks_its_status_bars() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::order::unpack;
 
     let mut s = benilla_ui::script::UiScript::new().unwrap();
@@ -894,6 +898,7 @@ fn every_texture_frame_outranks_its_status_bars() {
 /// screen; this is the structural half of that fix.)
 #[test]
 fn the_boot_phase_materializes_no_frames() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // The font registry is manifest entry 0 and comes off the chain since 1888, so this reads
@@ -922,6 +927,7 @@ fn the_boot_phase_materializes_no_frames() {
 /// rebakeable.
 #[test]
 fn the_font_registry_alone_covers_the_whole_bake_plan() {
+    benilla_formats::wow_data_or_skip!();
     let plan = |whole: bool| -> std::collections::BTreeSet<(String, String, String)> {
         let mut s = benilla_ui::script::UiScript::new().unwrap();
         s.set_screen_size(1024.0, 768.0);
@@ -978,6 +984,7 @@ fn the_font_registry_alone_covers_the_whole_bake_plan() {
 /// handler that errors on the one event that runs before any window has been shown.
 #[test]
 fn the_shipped_ui_takes_variables_loaded_without_a_script_error() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.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
@@ -1018,6 +1025,7 @@ fn the_shipped_ui_takes_variables_loaded_without_a_script_error() {
 /// `Tablet-2.0.lua:289` header-size probe, 268 read sites).
 #[test]
 fn every_shipped_font_object_is_published_as_a_lua_global() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.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
@@ -1107,6 +1115,7 @@ fn every_shipped_font_object_is_published_as_a_lua_global() {
 /// geometry and the script the reference confers.
 #[test]
 fn the_inheritable_reference_templates_confer_their_shape() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.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
@@ -1171,6 +1180,7 @@ fn the_inheritable_reference_templates_confer_their_shape() {
 /// it from its keyring fork.
 #[test]
 fn the_inspect_cursor_pair_takes_both_arms() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.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
@@ -1247,6 +1257,7 @@ fn the_inspect_cursor_pair_takes_both_arms() {
 ///   stops exactly as the reference's does.)
 #[test]
 fn a_cinematic_leaves_nothing_of_the_interface_on_screen() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.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
@@ -1352,6 +1363,7 @@ fn a_cinematic_leaves_nothing_of_the_interface_on_screen() {
 /// because of it.
 #[test]
 fn every_declared_parent_really_attaches() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = benilla_ui::script::UiScript::new().unwrap();
     s.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
@@ -1965,7 +1977,7 @@ fn the_stock_video_options_window_loads_hidden_and_owns_its_own_name() {
             .unwrap(),
         "…so the dropdown is left empty but ENABLED — the greying branch is the driver-quirk one, \
          and inventing a 0 to reach it would be inventing a value the binary never produces \
-         (`IsEnabled` answers a NUMBER — wow-re `binding-shapes.tsv` 0x7800b0)"
+         (`IsEnabled` answers a NUMBER — `0x7800b0`)"
     );
     // The optional index argument is tolerated, which is the shape `SetScreenResolution` shares.
     assert!(
@@ -2000,7 +2012,8 @@ fn the_stock_video_options_window_loads_hidden_and_owns_its_own_name() {
         "`not hasTripleBuffering` must stay FALSE (the dead clause) while `== 1` is also false"
     );
 
-    // `SetScreenResolution`'s three carved argument behaviours, and the one deliberate divergence.
+    // `SetScreenResolution`'s three argument behaviours in the reference, and the one deliberate
+    // divergence.
     assert!(
         s.eval::<bool>("SetScreenResolution() return GetCVar(\"gxResolution\") == \"1280x720\"")
             .unwrap(),
@@ -2073,7 +2086,7 @@ fn the_stock_video_options_window_loads_hidden_and_owns_its_own_name() {
 }
 
 /// **The display-brightness pair** (decision 2182) — `GetGamma`/`SetGamma` and the Graphics page
-/// row that drives them, held to the reference's own carve.
+/// row that drives them, held to the reference's own behaviour.
 ///
 /// The claim that needs an assertion rather than a comment is the **unit**: `0x4891d0` is FSUBR,
 /// so `GetGamma()` is `1.0 − gamma` and `SetGamma(v)` writes `gamma := 1.0 − v`. Read as
@@ -2086,9 +2099,6 @@ fn the_stock_video_options_window_loads_hidden_and_owns_its_own_name() {
 /// And the second claim: **there is no clamp**, anywhere, in the reference (the positive control
 /// is `baseMip`'s validating callback `0x689090`). `SetGamma(5)` writes `"-4.000000"` and the
 /// store keeps it — benilla's clamp is at the render consumer, where it cannot lie to `GetCVar`.
-///
-/// (wow-re `ui/scratch/video-options-verbs.md` §3 and
-/// `ffxeffects/scratch/whole-frame-grade-verdict.md` §(a), both VERIFIED.)
 #[test]
 fn the_display_brightness_pair_speaks_the_reference_slider_unit() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -2198,8 +2208,6 @@ fn the_display_brightness_pair_speaks_the_reference_slider_unit() {
 /// exist in the reference, with a capital F, while `value.func` is the lowercase `"farclip"`. The
 /// stock client takes the CVar path for far clip **only because `getglobal` is case-sensitive** — so
 /// this asserts that too, against a name we DO define.
-///
-/// (wow-re `ui/scratch/video-options-verbs.md` §5 and §7.7, both VERIFIED.)
 #[test]
 fn the_video_windows_ten_composed_names_stay_nil() {
     let _data = benilla_formats::wow_data_or_skip!();
@@ -2252,7 +2260,7 @@ fn the_video_windows_ten_composed_names_stay_nil() {
 /// gap rather than hiding it, and saying in as many words that "the day something registers it,
 /// THIS assertion goes red and gets deleted". That day is this change: `UIOptionsFrameSliders`
 /// row 3 is `cameraYawMoveSpeed`, `_Load` does `slider:SetValue(GetCVar(value.cvar))`, and
-/// `Slider:SetValue` is a shape-A binding (`0x790980`, wow-re `numeric-arg-coercion-law.md`) that
+/// `Slider:SetValue` is a shape-A binding (`0x790980`) that
 /// raises on a nil in the reference too. All four slider CVars are registered, so the walk reaches
 /// its end — and `_SetDefaults`, which does the same through `GetCVarDefault`, with it.
 #[test]
@@ -2357,3 +2365,36 @@ fn the_stock_options_windows_load_and_save_are_reachable_for_addons() {
         "_Save should write the slider's 180 and its half; got yaw={yaw} pitch={pitch}"
     );
 }
+
+/// `assets/ui` does not grow. The interface is the stock 1.12 FrameXML executed off the player's
+/// own patch chain; what is left here is the glue and the shims, named below. A new file means a
+/// window was authored instead of migrated: point `benilla.toc` at
+/// `Interface\FrameXML\<Window>.xml`, delete ours, and build the engine verbs the stock file calls.
+#[test]
+fn assets_ui_does_not_grow() {
+    const SHIPPED: &[&str] = &[
+        "ContainerFrameAdapters.xml",
+        "GameMenuFrame.xml",
+        "KeyBindingsPage.xml",
+        "OptionsFrame.xml",
+        "ScriptLogFrame.xml",
+        "ScrollTemplates.xml",
+        "SpellBookAdapters.xml",
+        "benilla.toc",
+    ];
+    let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("assets/ui");
+    let mut found: Vec<String> = std::fs::read_dir(&dir)
+        .expect("assets/ui")
+        .flatten()
+        .map(|e| e.file_name().to_string_lossy().into_owned())
+        .filter(|n| !n.starts_with('.'))
+        .collect();
+    found.sort();
+    let mut shipped: Vec<String> = SHIPPED.iter().map(|s| s.to_string()).collect();
+    shipped.sort();
+    assert_eq!(
+        found, shipped,
+        "assets/ui changed. It does not grow: a window is migrated, not authored (docs/METHOD.md). \
+         A file that retired comes off this list; a new one needs a reason this list can name."
+    );
+}
diff --git a/crates/benilla-app/src/ui_script/skills_frame_tests.rs b/crates/benilla-app/src/ui_script/skills_frame_tests.rs
index d8feb273..623653fc 100644
--- a/crates/benilla-app/src/ui_script/skills_frame_tests.rs
+++ b/crates/benilla-app/src/ui_script/skills_frame_tests.rs
@@ -8,7 +8,7 @@
 //! proficiencies, which the server really does report as `1/1`, and the **single-rank** lines
 //! (class skills, Dual Wield, racials, the per-mount riding lines), whose `skillMaxRank` the
 //! engine overrides to `1` off `SkillRaceClassInfo.flags & 0x400` however high the server's own
-//! descriptor is (`benilla-ui`'s `SkillEntry::mono`; wow-re `0x4d3610`'s `4d38b1` branch). A
+//! descriptor is (`benilla-ui`'s `SkillEntry::mono`; `0x4d3610`'s `4d38b1` branch). A
 //! hunter's `Beast Mastery` on vmangos arrives as `300/300` and must still read gray and
 //! numberless, exactly as it does in the real client.
 //!
@@ -374,11 +374,11 @@ fn the_pages_close_button_sits_where_the_reference_seats_it_and_closes_the_windo
 
     // Its label is the CLOSE global string's seat, in the panel-button gold.
     // **"Close", not "CLOSE".** An XML `text=` attribute is a GlobalStrings LOOKUP, not a literal
-    // (`loader::Loader::resolve_text`, wow-re `rf28-typed-widget-loadxml.md` l.36 —
-    // `FrameScript_GetText 0x703bf0`), and `CLOSE = "Close"` (`GlobalStrings.lua:760`). This test
-    // read "CLOSE" while the page's list carried no `GlobalStrings.lua`: it was asserting the
-    // miss-fallback (the raw attribute), which is the REFERENCE's own arm too (`0x778c31` /
-    // `0x771032`), not the label a client with the strings loaded draws.
+    // (`loader::Loader::resolve_text` — `FrameScript_GetText 0x703bf0`), and `CLOSE = "Close"`
+    // (`GlobalStrings.lua:760`). This test read "CLOSE" while the page's list carried no
+    // `GlobalStrings.lua`: it was asserting the miss-fallback (the raw attribute), which is the
+    // REFERENCE's own arm too (`0x778c31` / `0x771032`), not the label a client with the strings
+    // loaded draws.
     // [`super::test_ui::CHARACTER_UI`] loads the player's own strings first, as the app does, so
     // this is the real label now.
     let label = page_quads(&s)
@@ -507,8 +507,8 @@ fn the_expand_tab_fits_its_label_at_load() {
     assert!(s.errors().is_empty(), "errors: {:?}", s.errors());
 }
 
-/// **B370 — the list reaches its last rows.** MarcusAga's Skills tab stopped three rows short of
-/// the end: the knob mid-track, Maces the last row shown. The reference's own
+/// **B370 — the list reaches its last rows.** The symptom: the Skills tab stops three rows short
+/// of the end, the knob mid-track, Maces the last row shown. The reference's own
 /// `FauxScrollFrame_Update` sizes the bar to `(n − 12) × 15` and the scroll child to `n × 15`, and
 /// `SkillListScrollFrame` is 220 tall (stock `SkillFrame.xml` l.468) against twelve rows of
 /// fifteen — so the child's overflow past the frame, `n × 15 − 220`, is forty pixels short of
diff --git a/crates/benilla-app/src/ui_script/spellbook_tests.rs b/crates/benilla-app/src/ui_script/spellbook_tests.rs
index 89cd23a4..63c91733 100644
--- a/crates/benilla-app/src/ui_script/spellbook_tests.rs
+++ b/crates/benilla-app/src/ui_script/spellbook_tests.rs
@@ -127,6 +127,7 @@ pub(super) fn spellbook_ui(w: f32, h: f32) -> UiScript {
 /// AutoCast Model child) + 8 skill-line tabs + the 3 Spell/Pet toggle tabs + the tab flash frame.
 #[test]
 fn shipped_spellbook_loads_clean() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_xml(&s, "Interface\\FrameXML\\Fonts.xml");
     load_xml(&s, r"Interface\FrameXML\MoneyFrame.lua");
@@ -166,6 +167,7 @@ fn shipped_spellbook_loads_clean() {
 /// bar-to-bar drag uses — packing kind 0x00 (SPELL) with the spell id.
 #[test]
 fn shipped_spellbook_drives_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = spellbook_ui(1024.0, 768.0);
     s.fire_event("PLAYER_ENTERING_WORLD", vec![]);
 
@@ -256,6 +258,7 @@ fn shipped_spellbook_drives_end_to_end() {
 /// parked until SMSG_COOLDOWN_EVENT) keeps the widget hidden and dims the icon to 40% (l.361-365).
 #[test]
 fn shipped_spellbook_shows_the_cooldown_pie() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::QuadContent;
 
     let mut s = spellbook_ui(1024.0, 768.0);
@@ -331,6 +334,7 @@ fn shipped_spellbook_shows_the_cooldown_pie() {
 /// finding, which stands). That is the half this still pins.
 #[test]
 fn shipped_spellbook_empty_slot_draws_its_background_and_socket_ring() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = spellbook_ui(640.0, 700.0);
     // A one-spell book: slot 5 takes the reference's `id > offset + numSpells` disable path. (A
     // book with NO spells is a state no character is ever in — the reference's own
@@ -371,6 +375,7 @@ fn shipped_spellbook_empty_slot_draws_its_background_and_socket_ring() {
 /// l.132/134/268/296-303/336): 1/"true"/true check; 0/"false"/nil/non-numeric strings uncheck.
 #[test]
 fn set_checked_uses_blizzard_bool_coercion() {
+    benilla_formats::wow_data_or_skip!();
     let s = spellbook_ui(1024.0, 768.0);
     for (arg, want) in [
         ("1", true),
@@ -438,6 +443,7 @@ fn pet_book() -> benilla_ui::script::PetBookState {
 /// the class token's label, and a right-click flips autocast instead of casting.
 #[test]
 fn the_pet_tab_switches_books_and_renders_the_pets_spells() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = spellbook_ui(1024.0, 768.0);
     s.fire_event("PLAYER_ENTERING_WORLD", vec![]);
     s.set_spellbook(book());
@@ -659,6 +665,7 @@ fn the_pet_tab_switches_books_and_renders_the_pets_spells() {
 /// wrong, and the install says it is what 1.12.1 does.
 #[test]
 fn the_macro_editor_takes_a_shift_click_and_only_a_shift_click() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // The macro window's own strings (the app runs the real `GlobalStrings.lua`; `macro_tests`'
diff --git a/crates/benilla-app/src/ui_script/static_popup_tests.rs b/crates/benilla-app/src/ui_script/static_popup_tests.rs
index a5eb61d3..ec8c520e 100644
--- a/crates/benilla-app/src/ui_script/static_popup_tests.rs
+++ b/crates/benilla-app/src/ui_script/static_popup_tests.rs
@@ -27,6 +27,7 @@ fn setup() -> UiScript {
 /// (ref StaticPopup_OnUpdate l.1713-1726).
 #[test]
 fn timeout_expires_into_a_timeout_cancel() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.run(
         r#"reason = "unset"
@@ -62,6 +63,7 @@ fn timeout_expires_into_a_timeout_cancel() {
 /// itself is exercised too.
 #[test]
 fn start_delay_gates_button1_then_swaps_the_text_in() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.run(
         r#"StaticPopupDialogs["RECOVER_CORPSE"] = {
@@ -105,6 +107,7 @@ fn start_delay_gates_button1_then_swaps_the_text_in() {
 /// the death arc's RESURRECT-cancels-DEATH chain.
 #[test]
 fn showing_a_dialog_cancels_its_named_victim_with_override() {
+    benilla_formats::wow_data_or_skip!();
     let s = setup();
     s.run(
         r#"victim_reason = "unset"
@@ -137,6 +140,7 @@ fn showing_a_dialog_cancels_its_named_victim_with_override() {
 /// non-escapable entry — the DEATH release popup's law — survives ToggleGameMenu.
 #[test]
 fn escape_skips_dialogs_without_hide_on_escape() {
+    benilla_formats::wow_data_or_skip!();
     let s = setup();
     s.run(
         r#"StaticPopupDialogs["TEST_STICKY"] = {
@@ -169,6 +173,7 @@ fn escape_skips_dialogs_without_hide_on_escape() {
 /// `timeleft` re-renders "%d %s until release" every tick, minutes above 60 s.
 #[test]
 fn the_death_countdown_text_rerenders_each_tick() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.run(
         r#"StaticPopupDialogs["DEATH"] = {
@@ -212,6 +217,7 @@ fn the_death_countdown_text_rerenders_each_tick() {
 /// kind has at most one, so its data is never consulted.
 #[test]
 fn hide_and_find_address_one_instance_by_data_only_for_a_multiple_dialog() {
+    benilla_formats::wow_data_or_skip!();
     let s = setup();
     s.run(
         r#"
@@ -269,6 +275,7 @@ fn hide_and_find_address_one_instance_by_data_only_for_a_multiple_dialog() {
 /// binding this engine answers.
 #[test]
 fn the_verb_dialogs_open_from_their_events_and_call_their_verbs() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::ScriptValue;
     let mut s = setup();
     load_xml(&s, r"Interface\FrameXML\UIParent.xml"); // the arms
diff --git a/crates/benilla-app/src/ui_script/summon_tests.rs b/crates/benilla-app/src/ui_script/summon_tests.rs
index bbb95c3f..5baac59c 100644
--- a/crates/benilla-app/src/ui_script/summon_tests.rs
+++ b/crates/benilla-app/src/ui_script/summon_tests.rs
@@ -53,6 +53,7 @@ fn setup() -> UiScript {
 /// per-tick branch at all rather than `StaticPopup_Show`'s arguments.
 #[test]
 fn the_confirm_names_the_summoner_and_accept_queues_the_response() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("CONFIRM_SUMMON", Vec::new());
     assert!(
@@ -86,6 +87,7 @@ fn the_confirm_names_the_summoner_and_accept_queues_the_response() {
 /// engine's shared `StaticPopupTimeUnit`, reached through this dialog's own four-argument format.
 #[test]
 fn the_countdown_line_switches_to_seconds_and_singularises() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_summon_confirm(SummonConfirmUiState {
         summoner: "Twomage".into(),
@@ -117,6 +119,7 @@ fn the_countdown_line_switches_to_seconds_and_singularises() {
 /// countdown branch re-reads the getters rather than caching `StaticPopup_Show`'s arguments.
 #[test]
 fn a_summoner_whose_name_is_still_resolving_fills_in_on_a_later_tick() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_summon_confirm(SummonConfirmUiState {
         summoner: String::new(),
@@ -151,6 +154,7 @@ fn a_summoner_whose_name_is_still_resolving_fills_in_on_a_later_tick() {
 /// confirm in the folder. Cancel is never touched.
 #[test]
 fn combat_locks_accept_without_taking_the_dialog_down() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.set_unit("player", Some(player(false)));
     s.fire_event("CONFIRM_SUMMON", Vec::new());
@@ -198,6 +202,7 @@ fn combat_locks_accept_without_taking_the_dialog_down() {
 /// expiry.
 #[test]
 fn declining_and_expiring_both_send_nothing() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("CONFIRM_SUMMON", Vec::new());
     s.run("StaticPopup_OnClick(StaticPopup1, 2)").unwrap();
diff --git a/crates/benilla-app/src/ui_script/talent_wipe_tests.rs b/crates/benilla-app/src/ui_script/talent_wipe_tests.rs
index 65ff7cd5..165ee019 100644
--- a/crates/benilla-app/src/ui_script/talent_wipe_tests.rs
+++ b/crates/benilla-app/src/ui_script/talent_wipe_tests.rs
@@ -32,6 +32,7 @@ fn setup() -> UiScript {
 /// parsed as an unknown opcode and dropped.
 #[test]
 fn the_confirm_shows_and_accept_queues_the_wipe() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("CONFIRM_TALENT_WIPE", vec![ScriptValue::Int(15_000)]);
     assert!(
@@ -58,6 +59,7 @@ fn the_confirm_shows_and_accept_queues_the_wipe() {
 /// raise one, and the engine's `hasMoneyFrame` leg is what shows it.
 #[test]
 fn the_cost_lands_in_the_money_frame() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     assert!(
         !s.eval::<bool>("return StaticPopup1MoneyFrame:IsVisible()")
@@ -100,6 +102,7 @@ fn the_cost_lands_in_the_money_frame() {
 /// other), so the only observable is that no confirm was queued.
 #[test]
 fn declining_sends_nothing() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("CONFIRM_TALENT_WIPE", vec![ScriptValue::Int(15_000)]);
     s.run("StaticPopup_OnClick(StaticPopup1, 2)").unwrap();
@@ -120,6 +123,7 @@ fn declining_sends_nothing() {
 /// holds, ticking changes nothing; the frame it goes false, the dialog hides itself.
 #[test]
 fn leaving_the_trainers_range_hides_the_confirm() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = setup();
     s.fire_event("CONFIRM_TALENT_WIPE", vec![ScriptValue::Int(15_000)]);
     s.run("StaticPopup_OnUpdate(StaticPopup1, 0.1)").unwrap();
diff --git a/crates/benilla-app/src/ui_script/target_aura_tests.rs b/crates/benilla-app/src/ui_script/target_aura_tests.rs
index fe3c1a78..f93df949 100644
--- a/crates/benilla-app/src/ui_script/target_aura_tests.rs
+++ b/crates/benilla-app/src/ui_script/target_aura_tests.rs
@@ -134,6 +134,7 @@ fn size(s: &UiScript, name: &str) -> (f64, f64) {
 
 #[test]
 fn a_hostile_target_draws_debuffs_first_with_tint_and_count() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     target(
         &mut s,
@@ -214,6 +215,7 @@ fn a_hostile_target_draws_debuffs_first_with_tint_and_count() {
 
 #[test]
 fn a_friendly_target_puts_the_buff_row_first() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     target(
         &mut s,
@@ -241,6 +243,7 @@ fn a_friendly_target_puts_the_buff_row_first() {
 
 #[test]
 fn reaching_the_wrap_shrinks_the_first_row_to_17px() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     let debuffs: Vec<AuraState> = (0..6)
         .map(|i| debuff(1000 + i, &format!("D{i}"), 1, None))
@@ -262,6 +265,7 @@ fn reaching_the_wrap_shrinks_the_first_row_to_17px() {
 
 #[test]
 fn clearing_the_list_or_the_target_hides_the_buttons() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     target(&mut s, 2, vec![debuff(589, "Pain", 1, Some("Magic"))]);
     assert!(shown(&s, "TargetFrameDebuff1"));
diff --git a/crates/benilla-app/src/ui_script/taxi_tests.rs b/crates/benilla-app/src/ui_script/taxi_tests.rs
index 2a51daca..4dfca1c8 100644
--- a/crates/benilla-app/src/ui_script/taxi_tests.rs
+++ b/crates/benilla-app/src/ui_script/taxi_tests.rs
@@ -78,6 +78,7 @@ fn menu() -> TaxiUiState {
 /// hides it again.
 #[test]
 fn shipped_taxi_frame_drives_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = taxi_script();
 
     assert!(!s.eval::<bool>("return TaxiFrame:IsVisible()").unwrap());
@@ -133,6 +134,7 @@ fn shipped_taxi_frame_drives_end_to_end() {
 /// refusal is visible through.
 #[test]
 fn no_single_hop_destination_posts_the_error_and_closes() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = taxi_script();
     s.set_taxi(Some(TaxiUiState {
         art: "Interface\\TaxiFrame\\TAXIMAP0".into(),
@@ -172,6 +174,7 @@ fn no_single_hop_destination_posts_the_error_and_closes() {
 /// the window hides immediately (no one-frame lag) — the Gossip/Trainer close-button precedent.
 #[test]
 fn close_button_queues_the_intent_and_hides() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = taxi_script();
     s.set_taxi(Some(menu()));
     seat_flight_master(&mut s, "Dungar Longdrink");
diff --git a/crates/benilla-app/src/ui_script/test_ui.rs b/crates/benilla-app/src/ui_script/test_ui.rs
index 27178a40..7809446b 100644
--- a/crates/benilla-app/src/ui_script/test_ui.rs
+++ b/crates/benilla-app/src/ui_script/test_ui.rs
@@ -216,7 +216,7 @@ fn load_entry(s: &UiScript, entry: &str, strict_templates: bool, no_warnings: bo
 /// answers), then runs the reference's own body. First use rather than load time, and unnamed,
 /// because both registries keep the first writer: the arena's name map
 /// (`named_registry_is_non_overwriting`) and `_G` itself — a named frame is published
-/// non-overwriting (RF-0023: a `lua_gettable` nil check on GLOBALSINDEX, which is why a
+/// non-overwriting (`0x701bd0`: a `lua_gettable` nil check on GLOBALSINDEX, which is why a
 /// metatable fallback would block the real publish just the same). A stand-in seated before the
 /// real declaration shadows the real frame for good; the first cut did exactly that, 126
 /// failures, every tabbed panel's `numTabs` read off the stand-in. `fire_chat_login`'s
@@ -268,7 +268,7 @@ pub(super) const UIPARENT_STAND_INS: &str = r#"
     PETACTIONBAR_XPOS = PETACTIONBAR_XPOS or 36
 
     -- The frames these three read UNGUARDED, seated on the call rather than at load: a frame's
-    -- publish to _G is non-overwriting (RF-0023), so a stand-in seated before the real file loads
+    -- publish to _G is non-overwriting (0x701bd0), so a stand-in seated before the real file loads
     -- would shadow the real window for good.
     local function benilla_seat(names)
         for _, name in ipairs(names) do
diff --git a/crates/benilla-app/src/ui_script/tooltip_anchor_tests.rs b/crates/benilla-app/src/ui_script/tooltip_anchor_tests.rs
index ad13fc37..c02c7d3b 100644
--- a/crates/benilla-app/src/ui_script/tooltip_anchor_tests.rs
+++ b/crates/benilla-app/src/ui_script/tooltip_anchor_tests.rs
@@ -57,6 +57,7 @@ fn wolf() -> UnitState {
 /// resolves, and its rect IS the screen.
 #[test]
 fn uiparent_is_a_real_full_screen_frame() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     s.resolve();
     let ok: bool = s
@@ -77,6 +78,7 @@ fn uiparent_is_a_real_full_screen_frame() {
 /// kept its load-time position instead.
 #[test]
 fn world_hover_seats_the_default_corner() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     s.set_unit("mouseover", Some(wolf()));
     assert!(s.world_tooltip_unit("mouseover"), "the hover shows");
@@ -99,6 +101,7 @@ fn world_hover_seats_the_default_corner() {
 /// world mouseover keeps the ramp; this is the unit *frame*.
 #[test]
 fn unit_frame_hover_takes_the_default_corner_and_drops_on_leave() {
+    benilla_formats::wow_data_or_skip!();
     // The kit + popups precede the unit frames (their DropDown children's OnLoad), app order.
     let mut s = harness(&[
         // The stock unit frames resolve GlobalStrings at LOAD (`CombatFeedback.lua` l.7-17,
@@ -214,6 +217,7 @@ fn a_pending_name_hover_titles_the_chains_unknownobject() {
 /// (the sibling test above).
 #[test]
 fn your_own_portrait_explains_the_menu_instead_of_showing_your_health() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[
         // The stock unit frames resolve GlobalStrings at LOAD (`CombatFeedback.lua` l.7-17,
         // `UnitFrame.lua` l.1-6) and `UnitFrame_OnEnter` passes `PARTY_OPTIONS_LABEL` /
@@ -287,6 +291,7 @@ fn your_own_portrait_explains_the_menu_instead_of_showing_your_health() {
 /// table so the pass means what it says.
 #[test]
 fn action_button_hover_takes_the_default_corner() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness(&[
         "Interface\\FrameXML\\Cooldown.xml",
         "Interface\\FrameXML\\ActionButtonTemplate.xml",
@@ -328,6 +333,7 @@ fn action_button_hover_takes_the_default_corner() {
 /// (`script/tooltip/verbs.rs`).
 #[test]
 fn ubertooltips_off_seats_action_bar_plates_beside_the_button() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[
         "Interface\\FrameXML\\Cooldown.xml",
         "Interface\\FrameXML\\ActionButtonTemplate.xml",
@@ -408,6 +414,7 @@ fn ubertooltips_off_seats_action_bar_plates_beside_the_button() {
 /// un-collapsed with it.
 #[test]
 fn ubertooltips_off_seats_stance_plates_beside_the_button() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[
         "Interface\\FrameXML\\Cooldown.xml",
         "Interface\\FrameXML\\ActionButtonTemplate.xml",
@@ -461,6 +468,7 @@ fn ubertooltips_off_seats_stance_plates_beside_the_button() {
 /// BOTTOMLEFT.
 #[test]
 fn buff_hover_hangs_below_left_of_the_button() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[
         "Interface\\FrameXML\\Cooldown.xml",
         "Interface\\FrameXML\\ActionButtonTemplate.xml",
@@ -498,7 +506,7 @@ fn buff_hover_hangs_below_left_of_the_button() {
     s.resolve();
     // Through the template's real `<OnEnter>` — the reference keeps the SetOwner/SetPlayerBuff pair
     // inline there rather than in a named function, so the handler body itself is what this drives.
-    // `this` is set by hand because the engine sets it only when it *fires* a handler (RF-0025);
+    // `this` is set by hand because the engine sets it only when it *fires* a handler (`0x704d50`);
     // calling the compiled function directly does not, and the body reads `this`, not its argument.
     s.run("this = BuffButton0; BuffButton0:GetScript(\"OnEnter\")(BuffButton0)")
         .unwrap();
@@ -527,6 +535,7 @@ fn buff_hover_hangs_below_left_of_the_button() {
 /// cost.
 #[test]
 fn a_cursor_seated_gameobject_plate_is_owned() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     assert!(s.world_tooltip_gameobject("Brill", &[], Some((512.0, 384.0))));
     let owned: bool = s.eval("return GameTooltip:IsOwned(UIParent)").unwrap();
@@ -551,6 +560,7 @@ fn a_cursor_seated_gameobject_plate_is_owned() {
 /// plate is ever shown. With the owner written, so do we.
 #[test]
 fn a_cursor_seated_gameobject_plate_survives_an_addons_on_show_hook() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     // Questie's hook, in one line: the plate's own show event calls Show() again.
     s.run(r#"GameTooltip:SetScript("OnShow", function() GameTooltip:Show() end)"#)
@@ -579,6 +589,7 @@ fn a_cursor_seated_gameobject_plate_survives_an_addons_on_show_hook() {
 /// the failure 2255 had just fixed on the cursor arm.
 #[test]
 fn a_corner_seated_gameobject_plate_is_owned_and_shown() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     assert!(s.world_tooltip_gameobject("Ironforge Main Gate", &[], None));
     let owned: bool = s.eval("return GameTooltip:IsOwned(UIParent)").unwrap();
@@ -593,6 +604,7 @@ fn a_corner_seated_gameobject_plate_is_owned_and_shown() {
 /// `GameTooltip:Show()`, and `:Show()` is the existence gate `0x530a80`.
 #[test]
 fn a_corner_seated_gameobject_plate_survives_an_addons_on_show_hook() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness(&[]);
     s.run(r#"GameTooltip:SetScript("OnShow", function() GameTooltip:Show() end)"#)
         .unwrap();
diff --git a/crates/benilla-app/src/ui_script/tooltip_compare_tests.rs b/crates/benilla-app/src/ui_script/tooltip_compare_tests.rs
index a3291d57..61372ae7 100644
--- a/crates/benilla-app/src/ui_script/tooltip_compare_tests.rs
+++ b/crates/benilla-app/src/ui_script/tooltip_compare_tests.rs
@@ -7,7 +7,7 @@
 //! **1.12.1 has no hover compare, and neither does benilla now.** `SHOW_COMPARE_TOOLTIP` (event
 //! 377) has zero fire sites in 5875, so `PaperDollFrame.lua:621-640` is dead code there and the
 //! vendor row (plus the auction row, 1971) is the only live consumer of the shopping plates
-//! (wow-re `merchant-compare-item-law.md` §8). benilla fired that event until 2202 and then drove
+//! (`SetMerchantCompareItem 0x536080`). benilla fired that event until 2202 and then drove
 //! the plates itself on a shift-held hover until 2210; both were supersets of a client that
 //! compares only where its own FrameXML asks. The plates' geometry and lifetime belong to that
 //! FrameXML — this engine seats none of them.
@@ -412,7 +412,7 @@ fn shipped_merchant_row_raises_the_compare_plates() {
 }
 
 /// An armour template in one `InventoryType` — the CLASS is what the selection law compares by
-/// (wow-re `merchant-compare-item-law.md` §3).
+/// (the class test at `0x536262` in `SetMerchantCompareItem 0x536080`).
 fn armor_template(name: &str, inventory_type: u32) -> ItemTemplateView {
     ItemTemplateView {
         name: name.into(),
diff --git a/crates/benilla-app/src/ui_script/tooltip_template_tests.rs b/crates/benilla-app/src/ui_script/tooltip_template_tests.rs
index 6a097bae..484da9a6 100644
--- a/crates/benilla-app/src/ui_script/tooltip_template_tests.rs
+++ b/crates/benilla-app/src/ui_script/tooltip_template_tests.rs
@@ -99,6 +99,7 @@ fn drawn_textures(s: &mut UiScript) -> Vec<String> {
 /// itself never publishes a line region.
 #[test]
 fn an_addon_tooltip_from_the_template_names_its_lines_after_the_caller() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     // AtlasLoot/Core/AtlasLoot.xml l.576's declaration, renamed.
     let report = load_addon_xml(
@@ -168,6 +169,7 @@ fn an_addon_tooltip_from_the_template_names_its_lines_after_the_caller() {
 /// Strip `<Backdrop>` out of `GameTooltipTemplate` and this is the assertion that goes red.
 #[test]
 fn an_addon_tooltip_from_the_template_gets_the_plate() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     load_addon_xml(
         &s,
@@ -214,6 +216,7 @@ fn an_addon_tooltip_from_the_template_gets_the_plate() {
 /// Asserted from both sides: no error, and the tint actually landed.
 #[test]
 fn an_addon_may_call_gametooltip_onload_the_reference_way_with_no_argument() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     let report = load_addon_xml(
         &s,
@@ -240,7 +243,7 @@ fn an_addon_may_call_gametooltip_onload_the_reference_way_with_no_argument() {
 
     // The tint the bare call was there to apply (ref-GameTooltip.lua l.79-82's two colours),
     // QUANTIZED: the reference's backdrop colour field is a packed `0xAARRGGBB` byte quad and the
-    // setter converts `×255 + 0.5` through `__ftol` (wow-re `numeric-arg-coercion-law.md` Q4), so
+    // setter converts `×255 + 0.5` through `__ftol` (`SetBackdropColor 0x777d30`), so
     // `0.09` stores as 23 and reads back as `23/255`. This used to compare against `0.09` exactly,
     // which was our lossless `[f32; 4]` showing through a store the client cannot make.
     let q = |x: f32| f32::from((x * 255.0 + 0.5) as u8) / 255.0;
@@ -266,6 +269,7 @@ fn an_addon_may_call_gametooltip_onload_the_reference_way_with_no_argument() {
 /// owns the children, and the plate came along.
 #[test]
 fn createframe_with_the_template_is_the_same_tooltip() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     // BetterCharacterStats/helper.lua l.3, verbatim in shape (its `getglobal(...) or` guard and
     // the WorldFrame owner both collapse to this in a fresh VM).
@@ -305,6 +309,7 @@ fn createframe_with_the_template_is_the_same_tooltip() {
 /// an explicit `Hide()` between passes (l.1832). Both read `TextRight` as well as `TextLeft`.
 #[test]
 fn the_scanner_shape_reads_both_columns_and_hides_again() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     load_addon_xml(
         &s,
@@ -368,6 +373,7 @@ fn the_scanner_shape_reads_both_columns_and_hides_again() {
 /// instance, which is where it lived while it was inlined.
 #[test]
 fn the_status_bar_is_the_templates_because_tipbuddy_anchors_to_it() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     let report = load_addon_xml(
         &s,
@@ -423,6 +429,7 @@ fn the_status_bar_is_the_templates_because_tipbuddy_anchors_to_it() {
 /// would notice.
 #[test]
 fn an_instance_attribute_beats_the_templates() {
+    benilla_formats::wow_data_or_skip!();
     let s = harness();
     load_addon_xml(
         &s,
@@ -461,6 +468,7 @@ fn an_instance_attribute_beats_the_templates() {
 /// so 30 hidden pairs add no height and no width.
 #[test]
 fn the_tooltip_line_globals_exist_cold_and_do_not_count_as_lines() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
 
     for name in [
diff --git a/crates/benilla-app/src/ui_script/tot_frame_tests.rs b/crates/benilla-app/src/ui_script/tot_frame_tests.rs
index 98d9d295..3e47703c 100644
--- a/crates/benilla-app/src/ui_script/tot_frame_tests.rs
+++ b/crates/benilla-app/src/ui_script/tot_frame_tests.rs
@@ -170,6 +170,7 @@ fn raid(n: usize) -> PartyState {
 /// frame, so this is the switch alone.
 #[test]
 fn the_frame_ships_off_and_the_switch_is_what_shows_it() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
     assert_eq!(
@@ -191,6 +192,7 @@ fn the_frame_ships_off_and_the_switch_is_what_shows_it() {
 /// target, a target OF it, a target that is not you, and a target that is alive.
 #[test]
 fn the_four_unit_gates_each_take_the_frame_down() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
     assert!(shown(&mut s));
@@ -240,6 +242,7 @@ fn the_four_unit_gates_each_take_the_frame_down() {
 /// [`the_solo_mode_keeps_the_frame_when_a_raid_forms`], which shows the frame first.
 #[test]
 fn the_five_modes_answer_solo_party_and_raid() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
 
@@ -290,6 +293,7 @@ fn the_five_modes_answer_solo_party_and_raid() {
 /// sixty times a second and still never takes the frame down.
 #[test]
 fn the_solo_mode_keeps_the_frame_when_a_raid_forms() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
     s.run(r#"SHOW_TARGET_OF_TARGET_STATE = "3" this = TargetofTargetFrame TargetofTarget_Update() this = nil"#)
@@ -325,6 +329,7 @@ fn the_solo_mode_keeps_the_frame_when_a_raid_forms() {
 /// answer one with if it did (ref TargetFrame.xml l.612-625).
 #[test]
 fn the_frame_paints_its_unit() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
     s.tick(0.016);
@@ -379,6 +384,7 @@ fn the_frame_paints_its_unit() {
 /// only thing that ever calls `TargetofTarget_CheckDead`.
 #[test]
 fn the_dead_word_needs_a_connected_corpse() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
     s.tick(0.016);
@@ -420,6 +426,7 @@ fn the_dead_word_needs_a_connected_corpse() {
 /// reached from the frame's OnUpdate and nowhere else.
 #[test]
 fn the_portrait_tints_with_a_players_state_and_never_a_creatures() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
     s.tick(0.016);
@@ -456,6 +463,7 @@ fn the_portrait_tints_with_a_players_state_and_never_a_creatures() {
 /// reason the frame is clickable.
 #[test]
 fn the_left_click_targets_the_unit() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
     s.run(r#"TargetofTarget_OnClick("LeftButton")"#).unwrap();
@@ -481,6 +489,7 @@ fn the_left_click_targets_the_unit() {
 /// it appear.
 #[test]
 fn the_debuff_row_draws_what_the_unit_carries() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
     s.set_auras(
@@ -520,6 +529,7 @@ fn the_debuff_row_draws_what_the_unit_carries() {
 /// wrapped short behind it.
 #[test]
 fn the_target_rows_wrap_short_while_the_frame_stands_beside_them() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     // A hostile target, so the debuffs lead and the buffs hang off them.
     s.set_auras("target", Some(vec![debuff(2000, "Sunder", None)]));
@@ -571,6 +581,7 @@ fn the_target_rows_wrap_short_while_the_frame_stands_beside_them() {
 /// runs only while you have a target.
 #[test]
 fn the_reconcile_takes_the_frame_down_when_the_token_goes_silent() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = load_tot();
     switch_on(&mut s);
     assert!(shown(&mut s));
diff --git a/crates/benilla-app/src/ui_script/trainer_tests.rs b/crates/benilla-app/src/ui_script/trainer_tests.rs
index 25f6023d..c769007e 100644
--- a/crates/benilla-app/src/ui_script/trainer_tests.rs
+++ b/crates/benilla-app/src/ui_script/trainer_tests.rs
@@ -244,6 +244,7 @@ fn menu() -> TrainerState {
 /// and hides on TRAINER_CLOSED.
 #[test]
 fn shipped_trainer_frame_drives_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
 
     // Hidden by default.
@@ -351,6 +352,7 @@ fn shipped_trainer_frame_drives_end_to_end() {
 /// the row button's OnClick → Collapse/ExpandTrainerSkillLine(headerIndex).
 #[test]
 fn clicking_a_header_row_collapses_its_group() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(50);
     s.set_trainer(Some(menu()));
@@ -388,6 +390,7 @@ fn clicking_a_header_row_collapses_its_group() {
 /// its header stays, and the row count falls.
 #[test]
 fn filter_hides_a_state_keeping_headers() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(50);
     s.set_trainer(Some(menu()));
@@ -424,6 +427,7 @@ fn filter_hides_a_state_keeping_headers() {
 /// have to agree.
 #[test]
 fn filter_rows_toggle_through_the_dropdown_kit() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(50);
     s.set_trainer(Some(menu()));
@@ -513,6 +517,7 @@ fn long_menu() -> TrainerState {
 
 #[test]
 fn wheel_over_a_row_scrolls_the_list() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(50);
     s.set_trainer(Some(long_menu()));
@@ -594,6 +599,7 @@ fn wheel_over_a_row_scrolls_the_list() {
 /// (decision 1605).
 #[test]
 fn a_selected_or_hovered_service_row_paints_its_name_white() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(50);
     s.set_trainer(Some(menu()));
@@ -657,6 +663,7 @@ fn a_selected_or_hovered_service_row_paints_its_name_white() {
 /// while the arrow BUTTONS keep the ref's `UChatScrollButton` click.
 #[test]
 fn wheel_scroll_is_silent_but_the_arrows_click() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(50);
     s.set_trainer(Some(long_menu())); // 16 rows > 11 visible → the bar + arrows show
@@ -707,6 +714,7 @@ fn wheel_scroll_is_silent_but_the_arrows_click() {
 /// a number someone has to re-derive.
 #[test]
 fn the_scrollbar_arrows_step_the_list_the_way_they_point() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(50);
     s.set_trainer(Some(long_menu())); // 16 rows > 11 visible → the bar shows
@@ -810,7 +818,7 @@ fn the_state_filter_survives_a_restart_through_the_saved_variables_file() {
         0,
         "the click must write the SAVED global, not just the engine mask"
     );
-    let text = s.saved_variables_text_for(&info().saved_variables);
+    let text = String::from_utf8(s.saved_variables_bytes_for(&info().saved_variables)).unwrap();
     assert!(
         text.contains("TRAINER_FILTER_UNAVAILABLE = 0"),
         "the file carries the toggle: {text}"
@@ -841,6 +849,7 @@ fn the_state_filter_survives_a_restart_through_the_saved_variables_file() {
 /// the window re-pushes its saved globals on every show.
 #[test]
 fn a_new_list_packet_resets_the_filter_mask_and_the_collapse_set() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_trainer(Some(menu()));
     s.fire_event(
@@ -930,6 +939,7 @@ fn recipe_menu() -> TrainerState {
 /// carries a wrap width, the long name measures two lines, and its height passes the row height.
 #[test]
 fn a_long_row_name_stays_on_one_line_and_carries_its_rank_along() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(5000);
     s.set_trainer(Some(recipe_menu()));
@@ -1032,6 +1042,7 @@ fn a_long_row_name_stays_on_one_line_and_carries_its_rank_along() {
 /// collapsed groups, which 1128 recorded as "a collapse does not survive a purchase" — with it.
 #[test]
 fn learning_a_spell_keeps_the_filter_and_the_collapse_a_re_open_still_resets() {
+    benilla_formats::wow_data_or_skip!();
     use crate::ui_trainer::TrainerOpen;
     const DAZALAR: u64 = 0xabc;
 
@@ -1085,12 +1096,11 @@ fn learning_a_spell_keeps_the_filter_and_the_collapse_a_re_open_still_resets() {
     s.run("CollapseTrainerSkillLine(1)").unwrap();
     assert_eq!(rows(&mut s), 3, "the folded group keeps its header only");
 
-    // He trains. The app re-asks for the list (`trainer_buy_succeeded`) and marks its own answer as
-    // the repaint it is; the bought service comes back gray.
+    // He trains. The spell lands (`SMSG_LEARNED_SPELL`) and the state re-evaluator (2333, the
+    // reference's `0x4d7d40`) repaints the bought row gray IN PLACE — no second list, so nothing
+    // that a list packet resets.
     let mut learned = menu();
     learned.services[0].category = TrainerServiceCategory::Used;
-    open.refresh_pending = true;
-    open.open(DAZALAR, 0, vec![], "Hello, hunter!".into());
     feed(&mut s, &mut open, learned, "TRAINER_UPDATE");
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
     assert!(
@@ -1161,6 +1171,7 @@ fn learning_a_spell_keeps_the_filter_and_the_collapse_a_re_open_still_resets() {
 /// reason: the packet-vs-repaint decision under test is the app's own.
 #[test]
 fn learning_a_spell_takes_the_detail_pane_with_it_instead_of_stranding_the_last_one() {
+    benilla_formats::wow_data_or_skip!();
     use crate::ui_trainer::TrainerOpen;
     const DAZALAR: u64 = 0xabc;
 
@@ -1214,13 +1225,12 @@ fn learning_a_spell_takes_the_detail_pane_with_it_instead_of_stranding_the_last_
         "the Train button bought the selected row"
     );
 
-    // The app re-asks for the list and marks its answer the repaint it is (B256); the bought
-    // service comes back gray and, with "already known" off, leaves the list. Cleave slides up into
-    // row 2 under where the selection used to be.
+    // The spell lands and the re-evaluator (2333) repaints the bought row gray in place; with
+    // "already known" off it leaves the list, and Cleave slides up into row 2 under where the
+    // selection used to be. (Until 2333 this was a second list packet marked as a refresh —
+    // B256.)
     let mut learned = menu();
     learned.services[0].category = TrainerServiceCategory::Used;
-    open.refresh_pending = true;
-    open.open(DAZALAR, 0, vec![], "Hello, warrior!".into());
     feed(&mut s, &mut open, learned, "TRAINER_UPDATE");
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 
@@ -1265,6 +1275,7 @@ fn learning_a_spell_takes_the_detail_pane_with_it_instead_of_stranding_the_last_
 /// (`mov ecx,0x136; jmp 0x703e50`). Ours did not, so the checkbox moved and the list did not.
 #[test]
 fn a_filter_click_repaints_the_rows_the_player_is_looking_at() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = trainer_script();
     s.set_money(50);
     s.set_trainer(Some(menu()));
diff --git a/crates/benilla-app/src/ui_script/ui_menu_tests.rs b/crates/benilla-app/src/ui_script/ui_menu_tests.rs
index 22364e13..273a5a74 100644
--- a/crates/benilla-app/src/ui_script/ui_menu_tests.rs
+++ b/crates/benilla-app/src/ui_script/ui_menu_tests.rs
@@ -7,8 +7,8 @@
 //! What places the label is the template's `<NormalFont inherits="GameFontNormal"
 //! justifyH="LEFT"/>`: `SetText`'s lazy label creation funnels through the adopter
 //! `CSimpleButton::SetFontString 0x778d20`, which anchors an unanchored label to the button by the
-//! NORMAL embedded font's justify word (`[button+0x390]`: LEFT→LEFT, RIGHT→RIGHT, else CENTER —
-//! wow-re `system/ui/scratch/resize-bounds-and-button-fontstring.md` §5.2, VERIFIED). Decision 1996.
+//! NORMAL embedded font's justify word (`[button+0x390]`: LEFT→LEFT, RIGHT→RIGHT, else CENTER).
+//! Decision 1996.
 
 use benilla_ui::script::UiScript;
 
diff --git a/crates/benilla-app/src/ui_script/uiparent_tests.rs b/crates/benilla-app/src/ui_script/uiparent_tests.rs
index 7eca8dc7..0dafa16f 100644
--- a/crates/benilla-app/src/ui_script/uiparent_tests.rs
+++ b/crates/benilla-app/src/ui_script/uiparent_tests.rs
@@ -37,6 +37,7 @@ fn ui_parent() -> UiScript {
 /// bounds are strict, so a cursor exactly on an edge is outside.
 #[test]
 fn mouse_is_over_is_the_references_own_box_test() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui_parent();
     // The box is x 200..300, y 300..350.
     s.mouse_move(250.0, 325.0);
@@ -100,6 +101,7 @@ fn mouse_is_over_is_the_references_own_box_test() {
 /// so repeated calls accumulate.
 #[test]
 fn raise_and_lower_frame_level_step_the_frames_own_level() {
+    benilla_formats::wow_data_or_skip!();
     let s = ui_parent();
     let base: i64 = s.eval("return Box:GetFrameLevel()").unwrap();
 
@@ -121,6 +123,7 @@ fn raise_and_lower_frame_level_step_the_frames_own_level() {
 /// `IgniteStatus` calls it at file scope and dies on `attempt to call global`.
 #[test]
 fn randomseed_is_a_bare_global_like_random() {
+    benilla_formats::wow_data_or_skip!();
     let s = ui_parent();
     // Seeding twice with the same value must produce the same first draw; that is the whole
     // contract an addon wants from it.
@@ -138,6 +141,7 @@ fn randomseed_is_a_bare_global_like_random() {
 /// laid out answers nil from `GetLeft()`, and `MouseIsOver` must return nil rather than raise.
 #[test]
 fn mouse_is_over_survives_a_frame_with_no_resolved_rect() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui_parent();
     s.mouse_move(250.0, 325.0);
     s.run(r#"Floating = CreateFrame("Frame", "Floating", UIParent)"#)
@@ -162,6 +166,7 @@ fn mouse_is_over_survives_a_frame_with_no_resolved_rect() {
 /// that rather than reading one key.
 #[test]
 fn raid_class_colors_is_the_references_own_nine() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     // RAID_CLASS_COLORS comes off the chain with the font registry since 1888.
     super::test_ui::load_ui(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -216,6 +221,7 @@ fn raid_class_colors_is_the_references_own_nine() {
 /// found rather than the block those four came out of. It now enumerates the block.
 #[test]
 fn the_font_path_globals_are_the_references_own_four() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     // The four font-path globals come off the chain with the registry since 1888.
     super::test_ui::load_ui(&s, "Interface\\FrameXML\\Fonts.xml");
@@ -294,6 +300,7 @@ fn the_font_path_globals_are_the_references_own_four() {
 /// answered nil under the very cursor that had just entered it (decision 1985).
 #[test]
 fn mouse_is_over_reads_a_scaled_frame_in_its_own_units() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = ui_parent();
     s.run(
         r#"Scaled = CreateFrame("Frame", "Scaled", UIParent) Scaled:SetWidth(200) Scaled:SetHeight(100)
diff --git a/crates/benilla-app/src/ui_script/unit_frame_tests.rs b/crates/benilla-app/src/ui_script/unit_frame_tests.rs
index b131409f..f6fca0f4 100644
--- a/crates/benilla-app/src/ui_script/unit_frame_tests.rs
+++ b/crates/benilla-app/src/ui_script/unit_frame_tests.rs
@@ -48,6 +48,7 @@ fn load_unit_frames(s: &UiScript) {
 /// name arriving via UNIT_NAME_UPDATE.
 #[test]
 fn shipped_unit_frames_drive_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -306,6 +307,7 @@ fn extracted_text_height(s: &mut UiScript, text: &str) -> Option<f32> {
 /// touches it (only the player frame registers UNIT_COMBAT in 1.12).
 #[test]
 fn unit_combat_drives_the_player_hit_indicator() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -408,6 +410,7 @@ fn unit_combat_drives_the_player_hit_indicator() {
 /// menu), the full leader set once a party is pushed.
 #[test]
 fn left_clicking_the_player_frame_targets_self() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // The SELF-menu strings the popup rows bake at UnitPopup.xml load arrive with
@@ -528,6 +531,7 @@ fn left_clicking_the_player_frame_targets_self() {
 /// unit. The level-1 click was pinned above; this pins the level the marks actually live on.
 #[test]
 fn raid_mark_clicks_through_the_nested_level() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // The menu strings arrive with `load_unit_frames`' own `GlobalStrings.lua`
@@ -644,6 +648,7 @@ fn raid_mark_clicks_through_the_nested_level() {
 /// GetQuestGreenRange binding.
 #[test]
 fn shipped_target_frame_runs_the_level_law() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::PlayerReqState;
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
@@ -742,8 +747,9 @@ fn shipped_target_frame_runs_the_level_law() {
         .unwrap();
     assert!(ok, "hostile +10: the skull shows ({:?})", s.errors());
 
-    // A DEAD mob is NOT a corpse (§5: UnitIsCorpse is a pure TYPEID_CORPSE object check, and
-    // UnitLevel has no health test) — the ref shows a dead mob's NUMBER, not the skull.
+    // A DEAD mob is NOT a corpse (UnitIsCorpse `0x5161c0` is a pure TYPEID_CORPSE object check,
+    // and UnitLevel `0x517fc0` has no health test) — the ref shows a dead mob's NUMBER, not the
+    // skull.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -835,6 +841,7 @@ fn shipped_target_frame_runs_the_level_law() {
 /// UNIT_FACTION edge, not on every repaint.
 #[test]
 fn pvp_icon_follows_the_three_branch_law() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -944,6 +951,7 @@ fn pvp_icon_follows_the_three_branch_law() {
 /// both collapsed into blue.
 #[test]
 fn flagged_friendly_player_plate_is_green() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -1005,6 +1013,7 @@ fn flagged_friendly_player_plate_is_green() {
 /// UNIT_CLASSIFICATION_CHANGED alone, with no re-target.
 #[test]
 fn target_frame_border_follows_the_classification_law() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -1135,6 +1144,7 @@ fn target_frame_border_follows_the_classification_law() {
 /// level *below* the texture frame, where no layer can lift them back over it.
 #[test]
 fn the_ring_art_paints_over_the_bars() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -1206,6 +1216,7 @@ fn the_ring_art_paints_over_the_bars() {
 /// silence — nobody was in a party when the director reported the player frame.
 #[test]
 fn the_party_art_paints_over_the_bars() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     // The loot test's prefix (`loot_tests.rs`): PartyFrame's inline <Script> reads
@@ -1344,6 +1355,7 @@ fn the_party_art_paints_over_the_bars() {
 /// lights on the same `UnitHealth(unit) <= 0` test a corpse trips.
 #[test]
 fn a_feigning_target_paints_empty_bars_and_the_dead_text() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -1352,7 +1364,7 @@ fn a_feigning_target_paints_empty_bars_and_the_dead_text() {
         Some(UnitState {
             exists: true,
             is_connected: true, // CheckDead's second term — a feign is not a link-drop
-            name: Some("Nazriel".into()),
+            name: Some("Corvane".into()),
             health,
             max_health: 1500,
             level: 60,
@@ -1444,6 +1456,7 @@ fn a_feigning_target_paints_empty_bars_and_the_dead_text() {
 /// ring/swords/disc — resting still wins when both hold — and leaving both states clears the lot.
 #[test]
 fn the_player_frame_flashes_zzz_while_resting() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -1546,6 +1559,7 @@ fn the_player_frame_flashes_zzz_while_resting() {
 /// the number rode on the badge (director report, 2026-08-07).
 #[test]
 fn the_rest_badge_covers_the_level_number() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -1616,6 +1630,7 @@ fn the_rest_badge_covers_the_level_number() {
 /// no such cut.
 #[test]
 fn status_bar_text_paints_the_player_numerals_but_not_the_targets() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -1785,6 +1800,7 @@ fn status_bar_text_paints_the_player_numerals_but_not_the_targets() {
 /// back to its owner's rect and every string would appear to sit in the same box.
 #[test]
 fn no_two_numeral_strings_overlap_on_any_frame() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
@@ -1871,6 +1887,7 @@ fn no_two_numeral_strings_overlap_on_any_frame() {
 /// addons and fires events, but never hovers anything.
 #[test]
 fn the_unit_frame_hover_hooks_carry_the_references_names() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_unit_frames(&s);
 
@@ -1922,6 +1939,7 @@ fn the_unit_frame_hover_hooks_carry_the_references_names() {
 /// sheet's mark order says it should.
 #[test]
 fn the_raid_mark_helper_maps_each_index_to_its_cell() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_unit_frames(&s);
     s.run(r#"RTMark = UIParent:CreateTexture("RTMark", "OVERLAY")"#)
@@ -1963,6 +1981,7 @@ fn the_raid_mark_helper_maps_each_index_to_its_cell() {
 /// index is `0` — the player's own seat on that scale — *and* that we are grouped at all.
 #[test]
 fn the_player_frame_wears_the_leader_and_master_looter_icons() {
+    benilla_formats::wow_data_or_skip!();
     use benilla_ui::script::{PartyMemberInfo, PartyState};
 
     let mut s = UiScript::new().unwrap();
@@ -1972,7 +1991,7 @@ fn the_player_frame_wears_the_leader_and_master_looter_icons() {
         "player",
         Some(UnitState {
             exists: true,
-            name: Some("Frostshake".into()),
+            name: Some("Aldwyn".into()),
             health: 100,
             max_health: 100,
             level: 60,
@@ -1994,7 +2013,7 @@ fn the_player_frame_wears_the_leader_and_master_looter_icons() {
 
     let party = |leader_index: u32, master_looter: Option<u32>, method: &str| PartyState {
         members: vec![PartyMemberInfo {
-            name: "Thalyn".into(),
+            name: "Brisca".into(),
             guid: 0x7A17,
         }],
         leader_index,
@@ -2057,6 +2076,7 @@ fn the_player_frame_wears_the_leader_and_master_looter_icons() {
 /// not asserted against; what is asserted is that nothing the reference declares is absent.
 #[test]
 fn the_unit_frames_publish_every_name_the_reference_declares() {
+    benilla_formats::wow_data_or_skip!();
     let s = UiScript::new().unwrap();
     load_unit_frames(&s);
 
@@ -2189,6 +2209,7 @@ fn the_unit_frames_publish_every_name_the_reference_declares() {
 /// This drives the real stock file, so it is the symptom itself and not a proxy for it.
 #[test]
 fn the_target_leader_crown_follows_player_flags_changed() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
     load_unit_frames(&s);
diff --git a/crates/benilla-app/src/ui_script/verb_event_gate.rs b/crates/benilla-app/src/ui_script/verb_event_gate.rs
index d2d80518..8fa3f854 100644
--- a/crates/benilla-app/src/ui_script/verb_event_gate.rs
+++ b/crates/benilla-app/src/ui_script/verb_event_gate.rs
@@ -156,7 +156,7 @@ const ELSEWHERE: &[(&str, &str, &str)] = &[
 ];
 
 /// Pairs nothing fires on the verb's path, each with its reason. A row is a gap with a name,
-/// never a reason to stop; the reference's own site is in the table for the grep into wow-re.
+/// never a reason to stop; the reference's own site is in the table.
 const GAP: &[(&str, &str, &str)] = &[
     (
         "CancelSkillUps",
@@ -170,15 +170,15 @@ const GAP: &[(&str, &str, &str)] = &[
         "ClickTargetTradeButton",
         "TRADE_REPLACE_ENCHANT",
         "the reference runs the enchant clash check 0x496170 when a spell is on the cursor and \
-         fires this for the replace dialog (wow-re staticpopup-dialog-bindings.md §3.1); casting \
+         fires this for the replace dialog; casting \
          an enchant onto the partner's slot is not built here — `ui_trade.rs` only mirrors the \
          wire's enchant slot — so the verb is the money arm alone",
     ),
     (
         "CloseTrade",
         "PLAYER_TRADE_MONEY",
-        "fired only when the trade did not complete (`[0xb71748] == 0`, wow-re \
-         incoming-trade-request-law.md), zeroing the cancelled offer under a frame TRADE_CLOSED \
+        "fired only when the trade did not complete (`[0xb71748] == 0`), \
+         zeroing the cancelled offer under a frame TRADE_CLOSED \
          hides; here `TradeSession::begin` resets the whole session at the next trade, so the \
          next window opens at zero either way",
     ),
@@ -199,8 +199,8 @@ const GAP: &[(&str, &str, &str)] = &[
     (
         "PetDismiss",
         "PET_DISMISS_START",
-        "the worker 0x4bd6e0 sends the dismiss and fires this with a duration (`%d`, 10000 — \
-         wow-re pet-action-bar-api.md §10.8); no shipped file listens, the dismiss reaches the \
+        "the worker 0x4bd6e0 sends the dismiss and fires this with a duration (`%d`, 10000); \
+         no shipped file listens, the dismiss reaches the \
          wire through the app's drain, and the pet frame follows the unit's departure",
     ),
     (
diff --git a/crates/benilla-app/src/ui_script/world_entry_tests.rs b/crates/benilla-app/src/ui_script/world_entry_tests.rs
index c783efe3..3bfa5d7f 100644
--- a/crates/benilla-app/src/ui_script/world_entry_tests.rs
+++ b/crates/benilla-app/src/ui_script/world_entry_tests.rs
@@ -288,7 +288,7 @@ fn quitting_from_the_character_screen_does_not_blank_the_session_it_wrote() {
 ///
 /// This is the regression the latch design could most easily have caused, so it is pinned rather
 /// than argued. The obvious guard for the tail — "is there a player object?" — reads FALSE on a
-/// `/logout` by the time the tail runs: `net::apply::session::logged_out` despawns our avatar in
+/// `/logout` by the time the tail runs: `net::session::logged_out` despawns our avatar in
 /// the same drain that writes `LoggedOutMessage`, `back_on_logout` sets `NextState` off that same
 /// message, and `OnExit(InWorld)` does not run until the next frame's `StateTransition`. A
 /// predicate would have silenced the event on every logout to fix a quit on a loading screen.
@@ -449,6 +449,7 @@ fn logging_out_leaves_no_in_game_frames_behind() {
 /// the world.
 #[test]
 fn reload_ui_is_a_fresh_login_in_place() {
+    benilla_formats::wow_data_or_skip!();
     let _l = ENV_LOCK
         .lock()
         .unwrap_or_else(std::sync::PoisonError::into_inner);
@@ -615,6 +616,7 @@ fn reload_outside_the_world_is_dropped() {
 /// entirely off terminal WARN lines because the client showed nothing.
 #[test]
 fn an_addon_error_while_entering_world_reports_on_screen_and_the_sibling_loads() {
+    benilla_formats::wow_data_or_skip!();
     let _l = ENV_LOCK
         .lock()
         .unwrap_or_else(std::sync::PoisonError::into_inner);
@@ -664,6 +666,7 @@ fn an_addon_error_while_entering_world_reports_on_screen_and_the_sibling_loads()
 /// loads, and this test FINISHING is the claim — before 1306 it would hang here forever.
 #[test]
 fn a_looping_addon_cannot_freeze_world_entry() {
+    benilla_formats::wow_data_or_skip!();
     let _l = ENV_LOCK
         .lock()
         .unwrap_or_else(std::sync::PoisonError::into_inner);
@@ -935,14 +938,14 @@ fn the_login_one_shots_wait_for_the_in_game_ui() {
 /// ship — used to `warn!` to the terminal and vanish. Nothing raised, so 1305's dialog could not
 /// fire; the walk's failure list was dropped on the floor at `load_ingame_ui_on_world_entry`; and
 /// the per-frame drain kept no history. From the player's chair the addon simply was not there and
-/// the client said nothing, which is the literal content of *"there are a lot of addons that still
-/// doesn't work"*.
+/// the client said nothing.
 ///
 /// Three claims, and the third is the one that makes the first two reachable: the failure is
 /// **retained**, it is **readable from Lua** (so the window is a view of it, not a second copy),
 /// and the player is **told to look**.
 #[test]
 fn an_addon_that_fails_to_load_without_raising_is_readable_in_the_error_log() {
+    benilla_formats::wow_data_or_skip!();
     let _l = ENV_LOCK
         .lock()
         .unwrap_or_else(std::sync::PoisonError::into_inner);
@@ -1117,9 +1120,9 @@ fn a_repeating_error_is_one_row_with_a_count_not_a_flood() {
 
 // ── B353 · the layout cache is a resident of the shutdown tail ───────────────────────────────
 //
-// st1rk, 2026-09-01: *"Unlock a chat window (right-click tab → Unlock Window), resize or drag it,
-// `/logout` or `/reload`, log back in. It's back at the original size. `benilla-config/layout/`
-// isnt created."* The engine seam and the file round trip were already proven by
+// The symptom: an unlocked chat window, resized or dragged, comes back at its original size after
+// a `/reload` or a relog, and `benilla-config/layout/` is never created. The engine seam and the
+// file round trip were already proven by
 // [`crate::ui_script::chat_resize_tests::the_geometry_round_trips_through_the_save_file`]; what
 // was wrong is which edge writes. [`crate::ui_layout`] hung its saver off `OnExit(InWorld)`, and a
 // `/reload` never leaves `InWorld` — [`super::run_pending_reload`] calls the shutdown and the
@@ -1274,7 +1277,7 @@ fn window_geometry(world: &World) -> (f32, f32, String, f32, f32) {
         .expect("read the probe window back")
 }
 
-/// **The whole loop, on the root that reported it** — st1rk's retest, in one test: place a window,
+/// **The whole loop, on the root that reported it**, in one test: place a window,
 /// `/reload`, meet a fresh tree that has it on its authored anchors, and let the loader seat the
 /// saved geometry back over the top.
 ///
@@ -1331,6 +1334,7 @@ fn a_placed_window_comes_back_after_a_reload() {
 /// file reddens this instead of scrolling past, and closing one means deleting a line here.
 #[test]
 fn a_clean_world_entry_raises_only_the_warnings_we_have_named() {
+    benilla_formats::wow_data_or_skip!();
     let _l = ENV_LOCK
         .lock()
         .unwrap_or_else(std::sync::PoisonError::into_inner);
@@ -1722,3 +1726,63 @@ fn the_entry_load_seeds_a_record_the_feed_cannot_take_away() {
 
     let _ = std::fs::remove_dir_all(&tmp);
 }
+
+// ─────────────────── The production load is silent (the UI-load sound bracket) ───────────────────
+
+/// Every kit name the live VM has queued since the last drain.
+fn taken_kit_names(world: &mut World) -> Vec<String> {
+    world
+        .get_non_send_resource_mut::<benilla_ui::script::UiScript>()
+        .expect("in-world VM")
+        .take_sounds()
+        .into_iter()
+        .filter_map(|r| match r {
+            benilla_ui::script::SoundRequest::KitName(n) => Some(n),
+            _ => None,
+        })
+        .collect()
+}
+
+/// **A login and a `/reload` load without a sound** — `0x48fbf0` brackets itself in the counted
+/// suppression scope (`0x48fbfa` → `0x49016d`) across the TOC walk, the addons, the saved
+/// variables and the login cascade, and both of its callers (login `0x48f681`, `/reloadui`
+/// `0x495669`) go through it.
+///
+/// Stock `TargetFrame_OnLoad` → `TargetFrame_Update` → `Hide()` → `TargetFrame_OnHide` really does
+/// call `PlaySound("INTERFACESOUND_LOSTTARGETUNIT")` at load; the engine drops it. Before the
+/// production edge carried the bracket only the tests' whole-manifest load did, and every
+/// `/reload` played the lost-target click.
+#[test]
+fn a_login_and_a_reload_load_without_the_lost_target_sound() {
+    let _data = benilla_formats::wow_data_or_skip!();
+    let _l = ENV_LOCK
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
+    let (tmp, _c, _h) = hermetic_probe("load-silent");
+    let mut world = booted_world();
+
+    log_in_as(&mut world, "Onehunter", 1);
+    assert!(
+        frame_exists(&world, "TargetFrame"),
+        "the stock target frame loaded"
+    );
+    let at_login = taken_kit_names(&mut world);
+    assert!(
+        !at_login
+            .iter()
+            .any(|n| n == "INTERFACESOUND_LOSTTARGETUNIT"),
+        "the login load must be silent — the lost-target click was queued: {at_login:?}"
+    );
+
+    reload(&mut world, crate::char_select::ClientState::InWorld);
+    let at_reload = taken_kit_names(&mut world);
+    assert!(
+        !at_reload
+            .iter()
+            .any(|n| n == "INTERFACESOUND_LOSTTARGETUNIT"),
+        "the /reload load must be silent — the lost-target click was queued: {at_reload:?}"
+    );
+
+    drop(world);
+    let _ = std::fs::remove_dir_all(&tmp);
+}
diff --git a/crates/benilla-app/src/ui_script/world_map_tests.rs b/crates/benilla-app/src/ui_script/world_map_tests.rs
index 9e697e79..96182f0b 100644
--- a/crates/benilla-app/src/ui_script/world_map_tests.rs
+++ b/crates/benilla-app/src/ui_script/world_map_tests.rs
@@ -52,7 +52,7 @@ fn harness() -> UiScript {
 /// button and the elapsed time its one argument. Everything on the sheet — the arrow, the party
 /// and raid blips, the battleground teammates and flags, the corpse — is seated here.
 /// The map arrow's file facts (`MinimapArrow.m2`: one looping 3.333 s Stand keying no bone; the
-/// header box `x ∈ [−0.0127, 0.0135]`, `y ∈ [−0.0118, 0.0145]` — render law §2), handed to the
+/// header box `x ∈ [−0.0127, 0.0135]`, `y ∈ [−0.0118, 0.0145]`), handed to the
 /// engine the way the app does once the asset lands (2007/2015).
 fn arrow_facts(s: &mut UiScript) {
     use benilla_ui::widget::{ModelFileFacts, SequenceFacts};
@@ -915,3 +915,52 @@ fn a_stale_layout_row_cannot_seat_a_stock_frame() {
     assert_eq!(saved[0], row(), "unchanged through the round trip");
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
+
+/// **The full-screen quads follow a resize** — `BlackoutWorld` behind the map, and the cinematic
+/// letterbox bars. Stock `WorldMapFrame_OnLoad` and `CinematicFrame_OnLoad` size them ONCE from
+/// `GetScreenWidth()`/`GetScreenHeight()` and nothing in FrameXML touches them again (no
+/// `DISPLAY_SIZE_CHANGED` listener); 2242 fixed the load edge, and this is the other edge. A window
+/// grown after the load left the quad at the old size and the world showed through beside it.
+#[test]
+fn the_fullscreen_quads_follow_a_resize() {
+    let _data = benilla_formats::wow_data_or_skip!();
+    let mut s = UiScript::new().unwrap();
+    s.set_screen_size(1600.0, 900.0);
+    // A player exists by the time the manifest loads (decision 1848; see the test above).
+    s.set_unit(
+        "player",
+        Some(benilla_ui::script::UnitState {
+            exists: true,
+            name: Some("Probefour".into()),
+            level: 60,
+            ..Default::default()
+        }),
+    );
+    let failures = super::load_default_ui(&s);
+    assert!(failures.is_empty(), "manifest load errors: {failures:#?}");
+    s.resolve();
+
+    let width = |s: &UiScript, f: &str| s.eval::<f64>(&format!("return {f}:GetWidth()")).unwrap();
+    assert_eq!(width(&s, "BlackoutWorld"), 1600.0, "the load edge sized it");
+
+    // Grown, still wider than 4:3 so every one of the three takes its recompute branch.
+    assert!(s.set_screen_size(1920.0, 1080.0), "the size changed");
+    super::manifest::on_screen_resized(&s);
+    s.resolve();
+
+    let screen = s.eval::<f64>("return GetScreenWidth()").unwrap();
+    assert_eq!(screen, 1920.0);
+    for quad in ["BlackoutWorld", "UpperBlackBar", "LowerBlackBar"] {
+        assert_eq!(
+            width(&s, quad),
+            screen,
+            "{quad} still spans the OLD screen after a resize — the world shows through beside it"
+        );
+    }
+    assert_eq!(
+        s.eval::<f64>("return BlackoutWorld:GetHeight()").unwrap(),
+        1080.0,
+        "…and the blackout is the new height too"
+    );
+    assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
+}
diff --git a/crates/benilla-app/src/ui_script/world_state_tests.rs b/crates/benilla-app/src/ui_script/world_state_tests.rs
index 54d696d3..12753762 100644
--- a/crates/benilla-app/src/ui_script/world_state_tests.rs
+++ b/crates/benilla-app/src/ui_script/world_state_tests.rs
@@ -81,6 +81,7 @@ pub(crate) fn push(s: &mut UiScript, rows: Vec<WorldStateUiView>) {
 /// The Eastern Plaguelands readout: two labelled tower counters, each with its faction icon.
 #[test]
 fn the_tower_counters_draw_with_their_icons() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event("PLAYER_ENTERING_WORLD", vec![ScriptValue::Str("".into())]);
     assert!(
@@ -122,6 +123,7 @@ fn the_tower_counters_draw_with_their_icons() {
 /// are hidden rather than left painting a stale count.
 #[test]
 fn leaving_the_zone_clears_the_readout() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event("PLAYER_ENTERING_WORLD", vec![ScriptValue::Str("".into())]);
     push(
@@ -146,7 +148,7 @@ fn leaving_the_zone_clears_the_readout() {
     );
 }
 
-/// The dynamic icon is a SECOND slot, not a swap (wow-re `worldstate-ui-law.md` §12; decision
+/// The dynamic icon is a SECOND slot, not a swap (`GetWorldStateUIInfo 0x4c5a70`; decision
 /// 1604). The `Icon` column and the `DynamicIcon` column feed two different regions — a 42x42
 /// static slot and a 32x32 button off the row's right edge — and only `uiState == 2`, the
 /// flag-taken value, lights the second one. The first pass replaced the static art whenever the
@@ -154,6 +156,7 @@ fn leaving_the_zone_clears_the_readout() {
 /// never have moved; both halves of that are pinned here.
 #[test]
 fn the_dynamic_icon_is_a_second_slot_lit_only_by_the_taken_state() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event("PLAYER_ENTERING_WORLD", vec![ScriptValue::Str("".into())]);
 
@@ -245,6 +248,7 @@ fn the_dynamic_icon_is_a_second_slot_lit_only_by_the_taken_state() {
 /// icon is optional, and the row must not collapse when the DBC column is empty.
 #[test]
 fn a_row_without_an_icon_still_shows_its_text() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event("PLAYER_ENTERING_WORLD", vec![ScriptValue::Str("".into())]);
     push(
@@ -263,6 +267,7 @@ fn a_row_without_an_icon_still_shows_its_text() {
 /// Our transcription had shown the text; the reference's file draws the bar (1972).
 #[test]
 fn a_capture_point_row_is_a_bar_not_a_line_of_text() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.fire_event("PLAYER_ENTERING_WORLD", vec![ScriptValue::Str("".into())]);
     push(
@@ -289,6 +294,7 @@ fn a_capture_point_row_is_a_bar_not_a_line_of_text() {
 /// value — the number `0`, not nil and not ten nils — and a non-number argument raises.
 #[test]
 fn the_bindings_answer_the_reference_shape() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = harness();
     s.set_world_state_ui(vec![WorldStateUiView {
         ui_state: 7,
@@ -363,11 +369,11 @@ fn ink_box(chain: &mut benilla_formats::Chain, path: &str) -> (f32, f32, f32, f3
 /// have. Every icon the readout names is a sprite authored into the UPPER-LEFT corner of a
 /// power-of-two canvas (`AllianceTower` fills 16x16 of 32x32; `UI-PVP-Alliance` ~40x40 of 64x64),
 /// nothing is cropped, and the reference compensates *geometrically* — a 42x42 slot hung 6 units
-/// off the row's left edge with the label seated 10 above its centreline (wow-re
-/// `worldstate-ui-law.md` §12). Pin the OUTCOME rather than the constants: whatever the numbers,
-/// the visible art must sit beside its label and share its line. A snug icon box — the obvious
-/// thing to write, and what we shipped — puts the ink up and to the left of its own slot, which is
-/// exactly what the director saw. Skips without client data.
+/// off the row's left edge with the label seated 10 above its centreline (`WorldStateFrame.xml`).
+/// Pin the OUTCOME rather than the constants: whatever the numbers, the visible art must sit beside
+/// its label and share its line. A snug icon box — the obvious thing to write, and what we shipped
+/// — puts the ink up and to the left of its own slot, which is exactly what the director saw.
+/// Skips without client data.
 #[test]
 fn the_visible_ink_sits_beside_its_label_not_adrift_of_it() {
     let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-app/src/ui_script/zone_text_tests.rs b/crates/benilla-app/src/ui_script/zone_text_tests.rs
index a3ce16ab..cb72a8a9 100644
--- a/crates/benilla-app/src/ui_script/zone_text_tests.rs
+++ b/crates/benilla-app/src/ui_script/zone_text_tests.rs
@@ -172,7 +172,7 @@ fn abbey_grounds_subzone_hop_shows_no_territory_line() {
     );
 }
 
-/// The abbey repro, indoor half — the byte-corrected feed (wow-re `zonetext-indoor-bit.md` (d)):
+/// The abbey repro, indoor half — the byte-corrected feed (`0x67e670`):
 /// crossing the abbey threshold, the zone-name override SKIPS (the whole-WMO name
 /// "Northshire Abbey" equals the yard subzone), so the ZONE slot stays "Elwynn Forest" and the
 /// group row's name re-populates the SUBZONE ("Main Hall"). ZoneTextFrame's text never changes ⇒
@@ -208,7 +208,7 @@ fn abbey_interior_shows_the_room_in_the_small_line_alone() {
 
 /// The INN case — the override FIRES (the whole-WMO name differs from the street subzone):
 /// zone slot = the inn's name, subzone nulls (unnamed group rows). The big splash shows the inn
-/// name, and — the FIFO dispatch law (wow-re `event-dispatch-order.md`: SubZoneTextFrame
+/// name, and — the FIFO dispatch law (`RegisterEvent 0x702140` tail-appends: SubZoneTextFrame
 /// registered second fires LAST, its SetZoneText(1) is the last writer) — the territory line
 /// shows under it, exactly as on a NEW_AREA splash.
 #[test]
diff --git a/crates/benilla-app/src/ui_shapeshift.rs b/crates/benilla-app/src/ui_shapeshift.rs
index f84f8049..f7279058 100644
--- a/crates/benilla-app/src/ui_shapeshift.rs
+++ b/crates/benilla-app/src/ui_shapeshift.rs
@@ -1,7 +1,7 @@
 //! The stance/shapeshift bar feed + drain — the app side of `benilla_ui::script::shapeshift`'s
-//! seam, from the wow-re-verified mechanism (`system/ui/scratch/shapeshift-bar-api.md`, the §5
-//! cross-check behind `GetNumShapeshiftForms 0x4b4590` / `GetShapeshiftFormInfo 0x4b45c0` /
-//! `CastShapeshiftForm 0x4b4810` / `GetShapeshiftFormCooldown 0x4b49a0`):
+//! seam, from the reference's mechanism (`GetNumShapeshiftForms 0x4b4590` /
+//! `GetShapeshiftFormInfo 0x4b45c0` / `CastShapeshiftForm 0x4b4810` /
+//! `GetShapeshiftFormCooldown 0x4b49a0`):
 //!
 //! - **Admission** (the list build `0x4b25b0`): a KNOWN spell joins the bar when
 //!   `AttributesEx2 & 0x2 == 0` AND (it carries a `SPELL_AURA_MOD_SHAPESHIFT` apply-aura effect
@@ -21,7 +21,7 @@
 //!   MOD_SHAPESHIFT spell, the 48-slot aura scan for a force-admitted one ([`form_active`]).
 //! - **isCastable**: the active form reads hardcoded-castable; otherwise the usability predicate
 //!   `0x6e3d60` — the SAME full walk the action bar's `IsUsableAction` runs
-//!   ([`crate::ui_action::usable`], decision 0269's fold-back: reagents, forms, stealth, aura
+//!   ([`crate::spell::usable`], decision 0269's fold-back: reagents, forms, stealth, aura
 //!   states, the power gate).
 //! - **cooldown**: the form spell's own spell/category read ([`Cooldowns::info`]).
 //! - **Click** (`CastShapeshiftForm`): the ACTIVE form CANCELS (`CMSG_CANCEL_AURA`) — unless
@@ -33,13 +33,13 @@
 //!
 //! - **The list** — which spells sit on the bar, in what order — fires `UPDATE_SHAPESHIFT_FORMS`,
 //!   the real client's learn/unlearn/rank edge (`0x5e9c20`/`0x5e9fe0`/`0x4b2f50` → event `0x183`
-//!   at `0x4b28ff`/`0x4b2e43`, VERIFIED in wow-re's `shapeshift-bar-api.md`) and the ONLY thing
-//!   that fires it there. The stock `ShapeshiftBar_Update` treats every fire as a list rebuild: it
-//!   re-seats the shelf, shows the middle strip past two forms unconditionally, and `Show()`s a
-//!   frame that is already shown — no `OnShow`, no `UIParent_ManageFramePositions`, and nothing
-//!   takes the strip back down over a raised bottom-left bar. Firing it on a state change painted
-//!   exactly that plate (the one-event model this file carried until 2009: our own `StanceBar.xml`
-//!   had documented the collapse as a deliberate divergence, and 1938's stock bar inherited it).
+//!   at `0x4b28ff`/`0x4b2e43`) and the ONLY thing that fires it there. The stock
+//!   `ShapeshiftBar_Update` treats every fire as a list rebuild: it re-seats the shelf, shows the
+//!   middle strip past two forms unconditionally, and `Show()`s a frame that is already shown — no
+//!   `OnShow`, no `UIParent_ManageFramePositions`, and nothing takes the strip back down over a
+//!   raised bottom-left bar. Firing it on a state change painted exactly that plate (the one-event
+//!   model this file carried until 2009: our own `StanceBar.xml` had documented the collapse as a
+//!   deliberate divergence, and 1938's stock bar inherited it).
 //! - **A form's state** — active, texture, cooldown — is pushed silently; the stock bar repaints
 //!   state on the reference's own state events, which the feeds that own those transitions fire:
 //!   `PLAYER_AURAS_CHANGED` for the form byte (a MOD_SHAPESHIFT aura holds an aura slot — the
@@ -63,11 +63,12 @@ use bevy::prelude::*;
 
 use benilla_ui::script::{ShapeshiftFormView, UiScript};
 
-use crate::cooldowns::Cooldowns;
 use crate::items::Items;
-use crate::net::{ClientCommand, GuidIndex, NetCommands, ObjectStore, Reputations, SelfPlayer};
+use crate::net::{ClientCommand, NetCommands, ObjectStore, Objects, Reputations, SelfPlayer};
+use crate::spell::Cooldowns;
+use crate::spell::{cast_target, usable, CastCommit, CastLadder};
 use crate::target::Selection;
-use crate::ui_action::{cast_target, usable, CastCommit, CastLadder, PlayerActions, Spells};
+use crate::ui_action::{PlayerActions, Spells};
 use crate::ui_script::UiInput;
 use crate::ui_unit::UnitFeed;
 
@@ -81,9 +82,9 @@ const ATTR_EX2_STANCE_BAR_EXCLUDE: u32 = 0x2;
 /// Ironweave Battlesuit 27733 and a band of `zzOLD*` rows. Decision 1302 corrects 0270 here.
 const ATTR_EX2_STANCE_BAR_FORCE: u32 = 0x10;
 
-/// `GetShapeshiftFormInfo 0x4b45c0`'s **isActive**, both arms (wow-re `shapeshift-bar-api.md`,
-/// VERIFIED). The reference forks on the spell's own `formId` — its first `MOD_SHAPESHIFT`
-/// effect's `EffectMiscValue`, or 0 when it has no such effect at all:
+/// `GetShapeshiftFormInfo 0x4b45c0`'s **isActive**, both arms. The reference forks on the spell's
+/// own `formId` — its first `MOD_SHAPESHIFT` effect's `EffectMiscValue`, or 0 when it has no such
+/// effect at all:
 ///
 /// - `formId != 0` → active ⇔ the caster's form byte matches it (`4b46a0`–`4b46af`).
 /// - `formId == 0` (a **force-admitted** row, `AttributesEx2 & 0x10`) **and `ActiveIconID != 0`**
@@ -91,7 +92,7 @@ const ATTR_EX2_STANCE_BAR_FORCE: u32 = 0x10;
 ///   array with **nibble bit 0** of `UNIT_FIELD_AURAFLAGS` set (`4b4739 test al,1` — the
 ///   *cancelable* bit). That is exactly [`crate::ui_action::toggle::active_action_toggle`], the
 ///   byte-twin `0x4e55f0` the main action bar's own toggle runs, which is why it is reused rather
-///   than open-coded: the §5 confirmed the two scans test the same bit.
+///   than open-coded: the two scans test the same bit.
 ///
 /// Both arms converge on **one** shared block at `4b4754` — the form-byte match *jumps* there, the
 /// aura-scan hit *falls through* into it — and that block is the sole writer of `isActive = 1`.
@@ -125,10 +126,10 @@ fn form_active(
 /// arm, reasoning that the icon is picked at a *lower address* than the aura scan and so could
 /// not depend on it. That inference was wrong, and instructively so: **MSVC laid
 /// the deciding block at a higher address than the scan that feeds it**, so ordering the citations
-/// by address yields the opposite control flow. The wow-re §5 on `0x4b45c0` carved it and
-/// corrected us — a scan hit at `4b473e` falls *through* `4b4751` into the very block the form-byte
-/// match jumps to, and the `mov ebx,[ebp-0xc]` at `4b4751` exists for no reason but to restore the
-/// lua_State across that fall-through. So a lit paladin aura **does** wear `ActiveIconID` 122.
+/// by address yields the opposite control flow. In `0x4b45c0` a scan hit at `4b473e` falls
+/// *through* `4b4751` into the very block the form-byte match jumps to, and the `mov ebx,[ebp-0xc]`
+/// at `4b4751` exists for no reason but to restore the lua_State across that fall-through. So a lit
+/// paladin aura **does** wear `ActiveIconID` 122.
 ///
 /// `active_icon` is `None` exactly when the column is 0, so the `or_else` is the reference's own
 /// `4b4763 je` — a MOD_SHAPESHIFT row can report active while still painting `SpellIconID`
@@ -232,14 +233,16 @@ fn feed_shapeshift_bar(
     cooldowns: Res<Cooldowns>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
     selection: Res<Selection>,
-    index: Res<GuidIndex>,
+    // The object lookup (2334) — the guid index the selection resolves through, plus the bag
+    // walk behind each form's reagent leg. One param, not two.
+    objects: Objects,
     units: Query<&ObjectStore, Without<SelfPlayer>>,
     factions: Option<Res<crate::target::Factions>>,
     reputations: Res<Reputations>,
     items: Res<Items>,
     commands: Res<NetCommands>,
     clock: Res<crate::ui_script::UiClock>,
-    spell_mods: Res<crate::spell_mods::SpellModifiers>,
+    spell_mods: Res<crate::spell::SpellModifiers>,
     mut memory: Local<crate::ui_script::VmMemo<StanceMemory>>,
 ) {
     let Some(mut script) = script else {
@@ -259,8 +262,8 @@ fn feed_shapeshift_bar(
     // action feed's own ctx.
     let target_store = selection
         .guid
-        .and_then(|g| index.0.get(&g))
-        .and_then(|&e| units.get(e).ok());
+        .and_then(|g| objects.entity(g))
+        .and_then(|e| units.get(e).ok());
 
     // Admission + order (module docs).
     let mut rows: Vec<(u32, &benilla_formats::SpellDisplay)> = actions
@@ -285,7 +288,7 @@ fn feed_shapeshift_bar(
 
     // The bags walked once for every form's reagent leg (see `feed_action_state`).
     let carried = store
-        .map(|s| crate::ui_items::carried_counts(&s.0, &items))
+        .map(|s| crate::ui_items::carried_counts(&s.0, &objects))
         .unwrap_or_default();
     let fresh: Vec<ShapeshiftFormView> = rows
         .into_iter()
@@ -304,7 +307,7 @@ fn feed_shapeshift_bar(
                         carried: &carried,
                         spell_mods: &spell_mods,
                     };
-                    usable::spell_usable(id, d, &spells, &ctx, &items, &commands).0
+                    usable::spell_usable(id, d, &spells, &ctx, &objects, &items, &commands).0
                 });
             let texture = form_texture(d, active);
             let cooldown = cooldowns
@@ -448,7 +451,7 @@ mod tests {
         assert!(!form_active(465, &iconless, 0, Some(&up)));
     }
 
-    /// The `ActiveIconID` election, both arms (1302 §5, carved by the wow-re §5 on `0x4b45c0`).
+    /// The `ActiveIconID` election, both arms (1302 §5; `0x4b45c0`).
     /// Both determinations converge on the one block that elects it, so a lit aura wears the swirl
     /// exactly as a shifted druid wears the paw — and the `ActiveIconID == 0` fallback is the
     /// reference's own `4b4763 je`, reachable only on the MOD_SHAPESHIFT arm.
diff --git a/crates/benilla-app/src/ui_social/feed.rs b/crates/benilla-app/src/ui_social/feed.rs
index cb93dbaf..5fdaa04f 100644
--- a/crates/benilla-app/src/ui_social/feed.rs
+++ b/crates/benilla-app/src/ui_social/feed.rs
@@ -47,7 +47,7 @@ const WHO_KEYS: [&str; 4] = [
 /// **`ecx` is the RAW wire display count** (`[ebp-0x14]`), not the 50-capped global the cap at
 /// `0x5adf92` writes — a re-implementation must not test its own clamped count and call it the
 /// same rule. Ours is [`SocialState::who`]'s length, which is the wire's count uncapped (vmangos
-/// sends at most 49), so the two agree. wow-re `who-list-sort-law.md` §11.3, decision 2030.
+/// sends at most 49), so the two agree. Decision 2030.
 const WHO_CHAT_MAX: usize = 3;
 
 /// What the feed last announced, so the Era events fire on edges rather than every frame.
@@ -205,7 +205,7 @@ fn drain_result_lines(
 ///
 /// The order is the parser's, not a presentation choice: `0x5ae0a1` composes a record's line
 /// inside the loop that reads it, and the summary block `0x5ae0f1`–`0x5ae12a` sits after the
-/// loop's back-edge (wow-re `who-list-sort-law.md` §11.4).
+/// loop's back-edge.
 fn who_lines(rows: &[WhoInfo], total: u32, get: &dyn Fn(&str) -> Option<String>) -> Vec<Shown> {
     use benilla_ui::strings::{fill, Arg};
 
@@ -566,7 +566,7 @@ mod tests {
     /// the `qsort` that orders the array sits past that loop's back-edge (`0x5ae0e2`) — so the
     /// lines are already gone by the time anything is sorted, and only the array `GetWhoInfo`
     /// reads is ordered. Sorting them "for consistency" is the plausible wrong answer, and it was
-    /// this client's until wow-re read the call site (`who-list-sort-law.md` §11.4).
+    /// this client's until the call site was read.
     #[test]
     fn the_chat_lines_come_out_in_wire_order_with_the_total_last() {
         let mut social = SocialState::default();
@@ -611,10 +611,10 @@ mod tests {
 
     /// The comparator's "missing DBC row" marker is the **empty** name, and it must stay that
     /// way: `who_row` leaves an unresolvable class/race/zone empty, and the chain ties on it
-    /// rather than ordering it (wow-re §11.1 — the arm jumps to the loop's `inc esi`).
+    /// rather than ordering it (the arm jumps to the loop's `inc esi` at `0x5adbb2`).
     ///
     /// **This test is a tripwire.** The reference's `GetWhoInfo 0x5ad6e0` substitutes the
-    /// localized `"UNKNOWN"` on those same three legs (§11.2), so the two sides deliberately
+    /// localized `"UNKNOWN"` on those same three legs, so the two sides deliberately
     /// disagree: the cell reads UNKNOWN and the row sorts as if the column were not there. If
     /// this client ever adopts that substitution — it should; ours shows an empty cell today —
     /// the miss has to travel to the comparator by some other route than the string, or the tie
diff --git a/crates/benilla-app/src/ui_social/mod.rs b/crates/benilla-app/src/ui_social/mod.rs
index 307bda54..7d7f68c9 100644
--- a/crates/benilla-app/src/ui_social/mod.rs
+++ b/crates/benilla-app/src/ui_social/mod.rs
@@ -3,8 +3,8 @@
 //!
 //! [`SocialState`] mirrors the wire the way [`crate::ui_party`]'s `GroupState` does: the three
 //! server packets replace it wholesale or patch one row, and the feed turns it into the VM
-//! snapshot the FriendsFrame reads. Two client-side laws from wow-re's `FriendList.cpp` findings
-//! (`system/net/scratch/w2b.md`, the 0x728-byte object at `DAT_00c28168`) shape everything here:
+//! snapshot the FriendsFrame reads. Two client-side laws of the reference's `FriendList.cpp` (the
+//! 0x728-byte object at `DAT_00c28168`) shape everything here:
 //!
 //! - **The lists are guids.** A friend slot holds `{status, note*, guid, area, level, class}` —
 //!   no name — and the display name comes from the ObjectMgr name cache (`0x55f080`) at format
@@ -28,13 +28,12 @@
 //!
 //! Which result maps to which GlobalStrings key is *inferred by name* (the `ERR_FRIEND_*` /
 //! `ERR_IGNORE_*` set is one-to-one with vmangos's `FriendsResult` enum, and 18 results collapse
-//! to the 17 ids because both ADDED codes share `ERR_FRIEND_ADDED_S`) — the open dispatch item in
-//! the record.
+//! to the 17 ids because both ADDED codes share `ERR_FRIEND_ADDED_S`) — still open.
 //!
 //! ## What the ignore list is *for*
 //!
 //! Not the window — the silence. `FriendList::IsIgnored 0x5ae5a0` gates inbound chat and text
-//! emotes (wow-re `system/ui/scratch/text-emote-composition.md`: ignored performer ⇒ dropped
+//! emotes (the `SMSG_TEXT_EMOTE` handler `0x49dbe0`: ignored performer ⇒ dropped
 //! silently, no line at all) and the duel handler's auto-decline (`0x4d4a33`). [`is_ignored`] is
 //! that predicate; its callers are the chat apply arm and the duel one, which is how decision
 //! 0633's stated "no ignore list yet" deviation closes.
@@ -97,9 +96,9 @@ impl SocialState {
     /// Only [`Self::who_sort`] survives, and it survives because the reference's chain is
     /// per-process: its initialiser `0x5adc50` is reached once from the process-start run at
     /// `0x401666`, never from a login, so a player who left the who list sorted by level
-    /// descending finds it that way after a relog (wow-re `who-list-sort-law.md` §3). Everything
-    /// else is login-scoped for the reasons decision 0668 gives — the server re-pushes both lists
-    /// at the next login, and a stale ignore list would silence the wrong guids.
+    /// descending finds it that way after a relog. Everything else is login-scoped for the reasons
+    /// decision 0668 gives — the server re-pushes both lists at the next login, and a stale ignore
+    /// list would silence the wrong guids.
     pub(crate) fn clear_session(&mut self) {
         *self = Self {
             who_sort: std::mem::take(&mut self.who_sort),
@@ -115,7 +114,7 @@ impl SocialState {
 
     /// Is `guid` on the FRIEND list? The reference's `FriendList::FindFriendSlot 0x5ae810` —
     /// base `this+8`, stride `0x20`, bound `0x32`, the same triple `GetNumFriends 0x5ae490`
-    /// counts over (§5, wow-re `system/object-layer/scratch/guild-signon-cvar-gate.md`).
+    /// counts over.
     ///
     /// Its one consumer is the guild sign-on/sign-off line's fourth conjunct, and its purpose is
     /// **de-duplication, not suppression**: `SMSG_FRIEND_STATUS` emits the same two chat ids with
@@ -288,10 +287,61 @@ fn status_flag_key(status: u8) -> Option<&'static str> {
     })
 }
 
-/// The net drain's `SessionEvent::Friend*`/`Who*` arms, factored here so the wire laws live
-/// beside the state they drive ([`crate::ui_duel::apply`]'s shape).
-pub(crate) mod apply {
+/// The social family's packet handlers (decision 0668; in the net handler table since 2312),
+/// beside the state they drive ([`crate::ui_duel::net`]'s shape): the friend/ignore lists, the
+/// `/who` answer, and the result codes that print their own chat lines. The lines and the Era
+/// events fire off the mirror in [`feed_social`] — every one of them needs a NAME, which the
+/// feed resolves.
+pub(crate) mod net {
     use super::*;
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+
+    use crate::net::NetHandlerApp;
+
+    /// Register the family's handlers — called from [`UiSocialPlugin`]. One per kind, plus the
+    /// session-end listener.
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::FriendList, on_friend_list)
+            .net_handler(K::IgnoreList, on_ignore_list)
+            .net_handler(K::FriendStatus, on_friend_status)
+            .net_handler(K::WhoResults, on_who)
+            .net_handler(K::Disconnected, on_session_end);
+    }
+
+    fn on_friend_list(In(ev): In<SessionEvent>, mut social: ResMut<SocialState>) {
+        if let SessionEvent::FriendList { friends } = ev {
+            friend_list(&mut social, friends);
+        }
+    }
+
+    fn on_ignore_list(In(ev): In<SessionEvent>, mut social: ResMut<SocialState>) {
+        if let SessionEvent::IgnoreList { guids } = ev {
+            ignore_list(&mut social, guids);
+        }
+    }
+
+    fn on_friend_status(In(ev): In<SessionEvent>, mut social: ResMut<SocialState>) {
+        if let SessionEvent::FriendStatus(update) = ev {
+            friend_status(&mut social, update);
+        }
+    }
+
+    fn on_who(In(ev): In<SessionEvent>, mut social: ResMut<SocialState>) {
+        if let SessionEvent::WhoResults(results) = ev {
+            who(&mut social, results);
+        }
+    }
+
+    /// The friend/ignore lists and the last `/who` are session state (decision 0668): the
+    /// server re-pushes both lists at the next login, and a stale ignore list would silence the
+    /// wrong guids after a reconnect renumbers nothing but re-streams everything. The `/who`
+    /// sort chain is the one thing that survives — it is per-PROCESS in the reference, not
+    /// per-login (decision 2030), which is why this is a `clear_session` and not a `default()`.
+    /// A listener on the session end (a second handler on the kind, after the bridge's own teardown).
+    fn on_session_end(In(_): In<SessionEvent>, mut social: ResMut<SocialState>) {
+        social.clear_session();
+    }
 
     /// `SMSG_FRIEND_LIST`.
     pub(crate) fn friend_list(social: &mut SocialState, friends: Vec<FriendEntry>) {
@@ -319,6 +369,7 @@ pub(crate) struct UiSocialPlugin;
 
 impl Plugin for UiSocialPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<SocialState>().add_systems(
             Update,
             (
diff --git a/crates/benilla-app/src/ui_spellbook.rs b/crates/benilla-app/src/ui_spellbook.rs
index 83b4031e..8143a167 100644
--- a/crates/benilla-app/src/ui_spellbook.rs
+++ b/crates/benilla-app/src/ui_spellbook.rs
@@ -4,15 +4,13 @@
 //! join, and drives `benilla_ui::script::spellbook`'s snapshot + cast-drain seam behind
 //! `SpellBookFrame.xml` (the P key, `ui_script/input.rs`).
 //!
-//! The **add-gate** is byte-verified (decision 0227; wow-re `system/ui/scratch/
-//! spellbook-book-build.md`): a known spell reaches the book only when
+//! The **add-gate** (decision 0227; `0x4b25b0`): a known spell reaches the book only when
 //! [`SpellDisplay::in_spellbook`](benilla_formats::SpellDisplay::in_spellbook) — `Attributes` not
 //! `DO_NOT_DISPLAY`/`IS_TRADESKILL`, `castUI == 0`. Languages, armor/weapon proficiencies, and
 //! hidden racial passives are excluded exactly as the real client excludes them, so a live
 //! character's book no longer grows the junk tabs the pre-0227 build showed.
 //!
-//! Tab classification is byte-verified (decision 0228; wow-re
-//! `system/ui/scratch/spellbook-book-build.md` §3): a spell's `SkillLineAbility` line is routed
+//! Tab classification (decision 0228; `0x4b24f0`): a spell's `SkillLineAbility` line is routed
 //! through the per-race/class table (`0x6ddf90` → `SkillRaceClassInfo.dbc`) — if no row admits the
 //! player's race+class, or the matching row carries `SKILL_FLAG_DISPLAY_SORTED` (`flags & 0x80`),
 //! the spell lands in the **General** tab (key 0) instead of its line's own. That collapses
@@ -22,9 +20,9 @@
 //! to [`SkillLineCatalog::spell_tab`]; absent a character (capture with no self player) or the
 //! `SkillRaceClassInfo` data, the collapse is skipped and each line keeps its own tab.
 //!
-//! Tab order + book order follow the same §5 (`0x4b3040`/`0x4b30c0`): **General/key-0 pinned
-//! first**, then alphabetical by `SkillLine.dbc` name (locale collator `0x64a480` — plain byte
-//! order stands in for enUS); within a tab, name → **parsed rank number** ([`spell_sort_key`]).
+//! Tab order + book order (`0x4b3040`/`0x4b30c0`): **General/key-0 pinned first**, then
+//! alphabetical by `SkillLine.dbc` name (locale collator `0x64a480` — plain byte order stands in
+//! for enUS); within a tab, name → **parsed rank number** ([`spell_sort_key`]).
 //!
 //! INTERIM (flagged, none load-bearing): the multi-row `SkillRaceClassInfo` tie-break (first
 //! admitting row wins — the client's `0x6ddf90` returns one; consistent for the lines that matter),
@@ -40,11 +38,9 @@ use benilla_ui::script::{ScriptValue, SpellBookState, SpellSlotView, SpellTabVie
 
 use crate::entities::ItemDisplays;
 use crate::items::Items;
-use crate::net::{NetCommands, ObjectStore, SelfPlayer};
-use crate::ui_action::{
-    cast_target, melee_auto_attack_icon, ranged_weapon_icon, CastCommit, CastLadder, PlayerActions,
-    Spells,
-};
+use crate::net::NetCommands;
+use crate::spell::{cast_target, CastCommit, CastLadder};
+use crate::ui_action::{melee_auto_attack_icon, ranged_weapon_icon, PlayerActions, Spells};
 use crate::ui_script::{gate, UiInput};
 use crate::ui_unit::UnitFeed;
 use benilla_assets::{AssetSet, LockRecover, WorldAssets};
@@ -57,9 +53,9 @@ pub(crate) struct SkillLines {
 }
 
 /// The line id for a spell with no resolvable skill line — the **General tab, key 0**, which the
-/// client pins FIRST in the tab strip and renders with a fixed name + icon (byte-verified: wow-re
-/// spellbook-book-build.md, `GetSpellTabInfo 0x4b3ce0` — key 0 → the localized `GENERAL`
-/// GlobalString name `0x846910` + the hardcoded icon `Interface\Icons\Ability_Kick` `0x8468f0`).
+/// client pins FIRST in the tab strip and renders with a fixed name + icon
+/// (`GetSpellTabInfo 0x4b3ce0` — key 0 → the localized `GENERAL` GlobalString name `0x846910` +
+/// the hardcoded icon `Interface\Icons\Ability_Kick` `0x8468f0`).
 /// `0` is never a real vmangos `SkillType` (`SharedDefines.h`'s `SKILL_NONE = 0`), so it can't
 /// collide with a real line id.
 const NO_LINE: u32 = 0;
@@ -72,7 +68,7 @@ const GENERAL_TAB_ICON: &str = "Interface\\Icons\\Ability_Kick";
 /// `LEARNED_SPELL_IN_TAB` (event 510; decision 2252).
 ///
 /// Filled by the two net arms the reference reaches its announce block from
-/// (`crate::net::apply::spells`' learn and rank-up), never by the `SMSG_INITIAL_SPELLS` bulk load:
+/// (`crate::spell::net`'s learn and rank-up), never by the `SMSG_INITIAL_SPELLS` bulk load:
 /// the reference gates all of this on `0x4b25b0`'s live-mutation flag, which the login drain
 /// passes clear. Drained by [`feed_spellbook`].
 ///
@@ -137,8 +133,8 @@ struct FeedMemory {
     pushed: SpellBookState,
     /// The gate's counter memories (1439) — the stores whose lazy resolves poison `is_changed`
     /// (the weapon-icon template asks, the cooldown store's per-frame prune), plus the self
-    /// store's PRESENCE: the book's weapon icons flip on a despawn no `Changed` filter sees.
-    items_objects: gate::Watch,
+    /// store's PRESENCE: the book's weapon icons flip on a despawn no `Changed` filter sees. The
+    /// item OBJECTS are an entity watch since 2334 ([`crate::items::ItemChanges`]), not a counter.
     items_templates: gate::Watch,
     cooldown_epoch: gate::Watch,
     self_present: gate::Watch,
@@ -149,12 +145,14 @@ fn feed_spellbook(
     actions: Res<PlayerActions>,
     spells: Option<Res<Spells>>,
     skill_lines: Option<Res<SkillLines>>,
-    self_q: Query<&ObjectStore, With<SelfPlayer>>,
-    changed_self: Query<(), (With<SelfPlayer>, Changed<ObjectStore>)>,
+    // The inventory read (2334): the self store (race/class, the form byte, the two weapon
+    // slots), its change tick, the object lookup the weapon icons resolve through, and the
+    // item entities' change watch.
+    mut inv: crate::items::Inventory,
     items: Res<Items>,
     icons: Option<Res<ItemDisplays>>,
     commands: Res<NetCommands>,
-    cooldowns: Res<crate::cooldowns::Cooldowns>,
+    cooldowns: Res<crate::spell::Cooldowns>,
     clock: Res<crate::ui_script::UiClock>,
     mut memory: Local<crate::ui_script::VmMemo<FeedMemory>>,
     mut learned: ResMut<LearnedInTab>,
@@ -168,14 +166,16 @@ fn feed_spellbook(
     // see the memory struct), the item stores behind the weapon icons, and the cooldown
     // store. `UiClock` is deliberately NOT an input: `ui_triple` is frame-stable per arm and
     // natural expiry rides the store's `feed_epoch`.
-    let objects_moved = memory.items_objects.moved(items.object_epoch());
+    let objects_moved = inv.changes.moved();
     let templates_moved = memory.items_templates.moved(items.template_epoch());
     let cooldowns_moved = memory.cooldown_epoch.moved(cooldowns.feed_epoch());
-    let presence_moved = memory.self_present.moved(u64::from(!self_q.is_empty()));
+    let presence_moved = memory
+        .self_present
+        .moved(u64::from(!inv.self_store.is_empty()));
     // The frame a timer crosses zero, BEFORE the per-frame prune has moved the epoch
     // (`sweep_pending`'s own doc) — the triple flips to None right then.
     let sweep = cooldowns.sweep_pending(clock.anchor);
-    let self_changed = !changed_self.is_empty();
+    let self_changed = !inv.self_changed.is_empty();
     let actions_changed = actions.is_changed();
     let spells_changed = spells.as_ref().is_some_and(|r| r.is_changed());
     let lines_changed = skill_lines.as_ref().is_some_and(|r| r.is_changed());
@@ -228,21 +228,29 @@ fn feed_spellbook(
     };
     // The player's race/class drive the General collapse (module doc). Absent (no self player
     // yet), 0/0 skips the collapse — each line keeps its own tab until the descriptor arrives.
-    let store = self_q.single().ok();
+    let store = inv.self_store.single().ok();
     let (race, class) = store
         .map(|s| (s.0.unit_race().unwrap_or(0), s.0.unit_class().unwrap_or(0)))
         .unwrap_or((0, 0));
     // The melee auto-attack's icon is the equipped main-hand weapon (or Spell-Reset when unarmed),
     // not spell 6603's `Temp` placeholder (decision 0230) — resolved here where the self player +
     // item stores are in hand, once for the whole page (it's the same for any auto-attack spell).
-    let attack_icon = store
-        .map(|s| melee_auto_attack_icon(s, &spells.forms, &items, icons.as_deref(), &commands));
+    let attack_icon = store.map(|s| {
+        melee_auto_attack_icon(
+            s,
+            &spells.forms,
+            &inv.objects,
+            &items,
+            icons.as_deref(),
+            &commands,
+        )
+    });
     // The ranged auto-repeat shots (Auto Shot, wand Shoot) borrow the equipped ranged weapon's
     // icon the same way (decision 0231's ranged case; `None` — unarmed/thrown — keeps the
     // spell's own icon, never Spell-Reset). Character-level like the melee icon: one resolve
     // serves the page.
-    let ranged_icon =
-        store.and_then(|s| ranged_weapon_icon(s, &items, icons.as_deref(), &commands));
+    let ranged_icon = store
+        .and_then(|s| ranged_weapon_icon(s, &inv.objects, &items, icons.as_deref(), &commands));
     let (mut fresh, tab_lines) = build_book(
         &actions.spells,
         &spells.catalog,
@@ -252,15 +260,14 @@ fn feed_spellbook(
         attack_icon,
         ranged_icon,
     );
-    // The `IsCurrentCast` verdict per slot — the delegate `0x4b3600` (wow-re
-    // `spellbook-checked-predicate.md`, §5-verified): its OWN function, NOT the action bar's
-    // `0x4e53a0`, and deliberately narrower — TWO arms only. The shapeshift arm is built here: a
-    // MOD_SHAPESHIFT spell reads current exactly while the player's form byte equals its form id
-    // (keyed on the FORM, so any spell/rank granting it reads true — Ghost Wolf's slot glows
-    // while shifted, a druid form's likewise). The other arm (the open trade-skill window) stays
-    // unmodeled with the trade-skill session itself. The action predicate's casting-now /
+    // The `IsCurrentCast` verdict per slot — the delegate `0x4b3600`: its OWN function, NOT the
+    // action bar's `0x4e53a0`, and deliberately narrower — TWO arms only. The shapeshift arm is
+    // built here: a MOD_SHAPESHIFT spell reads current exactly while the player's form byte equals
+    // its form id (keyed on the FORM, so any spell/rank granting it reads true — Ghost Wolf's slot
+    // glows while shifted, a druid form's likewise). The other arm (the open trade-skill window)
+    // stays unmodeled with the trade-skill session itself. The action predicate's casting-now /
     // awaiting-target / item / attack arms are ABSENT in the binary — a book slot must NOT light
-    // during an ordinary cast (the verdict's load-bearing negative).
+    // during an ordinary cast (the load-bearing negative).
     let form_byte = store.map(|s| s.0.unit_shapeshift_form()).unwrap_or(0);
     if form_byte != 0 {
         for slot in &mut fresh.slots {
@@ -538,12 +545,11 @@ fn drain_spell_casts(
         return;
     };
     for spell_id in script.take_spell_casts() {
-        // The `CastSpell` dispatcher's two press-again-to-cancel forks (`0x4b3300`, wow-re
-        // `shapeshift-plaincast-toggle.md`), in the ref's own order: the active-action toggle
-        // (`0x4b36f0` → cancel `0x4b3466`), then the shapeshift form-match fork
-        // (`0x4b348b`–`0x4b35e5`) with its non-cancelable silent no-op (`0x4b35cf`). This is the
-        // leg `UseAction` does NOT have — a druid's `/cast Cat Form` powershift-out and a
-        // shaman's Ghost Wolf re-cast both land here.
+        // The `CastSpell` dispatcher's two press-again-to-cancel forks (`0x4b3300`), in the ref's
+        // own order: the active-action toggle (`0x4b36f0` → cancel `0x4b3466`), then the shapeshift
+        // form-match fork (`0x4b348b`–`0x4b35e5`) with its non-cancelable silent no-op
+        // (`0x4b35cf`). This is the leg `UseAction` does NOT have — a druid's `/cast Cat Form`
+        // powershift-out and a shaman's Ghost Wolf re-cast both land here.
         if let (Some(sp), Some(store)) =
             (ladder.spells.as_ref(), targeting.self_store.iter().next())
         {
diff --git a/crates/benilla-app/src/ui_stable.rs b/crates/benilla-app/src/ui_stable/mod.rs
similarity index 93%
rename from crates/benilla-app/src/ui_stable.rs
rename to crates/benilla-app/src/ui_stable/mod.rs
index a2d1adf4..5e9a1486 100644
--- a/crates/benilla-app/src/ui_stable.rs
+++ b/crates/benilla-app/src/ui_stable/mod.rs
@@ -44,10 +44,13 @@ use crate::ui_pet_stats::{PetFamilyTables, PetStatTables};
 use crate::ui_script::{UiFeed, UiInput};
 use crate::ui_session::{close_npc_session_out_of_range, npc_switched, NpcSession};
 
+mod net;
+
 pub(crate) struct UiStablePlugin;
 
 impl Plugin for UiStablePlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<StableOpen>()
             .init_resource::<StableErrors>()
             .add_systems(
@@ -98,7 +101,7 @@ pub(crate) struct StableOpen {
     pub(crate) pets: Vec<StabledPet>,
     /// A list packet has landed and the feed has not yet turned it into `PET_STABLE_SHOW`.
     ///
-    /// The distinction this latch draws is the carve's: `PET_STABLE_SHOW` fires **unconditionally
+    /// The distinction this latch draws is the client's: `PET_STABLE_SHOW` fires **unconditionally
     /// at the tail of every `MSG_LIST_STABLED_PETS` handler** (`0x4cac9b`) — every list, not just
     /// the first — while `PET_STABLE_UPDATE`/`_PADERDOLL` fire from the **creature-cache
     /// callbacks** (`0x4cb3bf`, `0x4cba5f`), i.e. exactly when a late template answer fills a row
@@ -351,7 +354,7 @@ fn drain_stable(
 }
 
 /// Point the stable window's model pane at the pet `GetSelectedStablePet()` names — the app half of
-/// the reference's `SetPetStablePaperdoll` (wow-re `ui/scratch/stable-master-window.md` §7.1).
+/// the reference's `SetPetStablePaperdoll 0x4cb870`.
 ///
 /// **The reference's own fork, and it is the whole of this system.** On `[0xb72250] == -1` — the
 /// summoned pet — it resolves the live pet by GUID and takes `[unit+0xb30]`'s model; the resolve
@@ -405,8 +408,8 @@ fn feed_stable_booth(
 /// The selection → `(live unit, display id)` fork, pure so the law is testable without a VM, a
 /// wire or a world (module doc on [`feed_stable_booth`] for the reference's shape).
 ///
-/// **The live arm consults no row at all** — §7.1's `[0xb72250] == -1` branch reads the live pet's
-/// GUID out of `[0xb714a0]` and takes its model; the stable array is not in that path. So a
+/// **The live arm consults no row at all** — `0x4cb870`'s `[0xb72250] == -1` branch reads the live
+/// pet's GUID out of `[0xb714a0]` and takes its model; the stable array is not in that path. So a
 /// summoned pet is drawn from its world body whether or not the list happened to carry its row.
 ///
 /// **The display arm is resolved regardless**, because that is the reference's own order: the live
@@ -431,9 +434,9 @@ fn stable_subject(
 
 /// Stable refusals staged for the feed, as **message-catalog keys** — only ever
 /// `ERR_NOT_ENOUGH_MONEY`, the single code the client speaks for (decision 1677), reached through
-/// `DisplayError(0x25)` (wow-re `system/ui/scratch/stable-master-window.md` §5, VERIFIED). A key
-/// rather than the resolved text because that row carries error-speech line `0x28` too — the
-/// character says it aloud (decision 1815).
+/// `DisplayError(0x25)` (the `SMSG_STABLE_RESULT` handler `0x4cacb0`). A key rather than the
+/// resolved text because that row carries error-speech line `0x28` too — the character says it
+/// aloud (decision 1815).
 #[derive(Resource, Default)]
 pub(crate) struct StableErrors(pub(crate) Vec<&'static str>);
 
@@ -524,4 +527,32 @@ mod tests {
             "the template ships no display"
         );
     }
+
+    /// **The stable window dies with the session.** The walk-away guard does not cover it: it
+    /// needs a self player to measure from, and between the socket dying and the next world
+    /// entry there is none — so a stable open at the drop rode into the next login's fresh VM.
+    #[test]
+    fn the_session_end_closes_the_stable() {
+        let mut app = App::new();
+        app.init_resource::<StableOpen>()
+            .init_resource::<StableErrors>()
+            .init_resource::<crate::names::NameCache>();
+        net::register(&mut app);
+        {
+            let mut open = app.world_mut().resource_mut::<StableOpen>();
+            open.npc = Some(0xF130_0000_0000_0042);
+            open.num_stable_slots = 2;
+        }
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![benilla_protocol::SessionEvent::Disconnected {
+                reason: "socket".into(),
+                end: benilla_protocol::SessionEnd::Lost,
+            }],
+        );
+
+        let open = app.world().resource::<StableOpen>();
+        assert_eq!((open.npc, open.num_stable_slots), (None, 0));
+    }
 }
diff --git a/crates/benilla-app/src/ui_stable/net.rs b/crates/benilla-app/src/ui_stable/net.rs
new file mode 100644
index 00000000..aa92c4df
--- /dev/null
+++ b/crates/benilla-app/src/ui_stable/net.rs
@@ -0,0 +1,143 @@
+//! The stable master's packet handlers (decisions 1677, 1688; in the net handler table since
+//! 2318, moved out of the drain's npc arm file) — the [`StableOpen`] session and the
+//! [`StableErrors`] line queue the stable feed ([`super`]) reads.
+
+use benilla_protocol::messages::StabledPet;
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::{StableErrors, StableOpen};
+use crate::names::NameCache;
+use crate::net::{ClientCommand, NetCommands, NetHandlerApp};
+
+/// Register the stable handlers — called from [`super::UiStablePlugin`].
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::ListStabledPets, on_list)
+        .net_handler(K::StableResult, on_result)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+/// The stable window dies with the socket — a listener on the session end (a second handler on the
+/// kind, after the bridge's own teardown). The walk-away guard cannot stand in: it measures from a
+/// self player, and there is none between the drop and the next world entry.
+fn on_session_end(In(_): In<SessionEvent>, mut stable_open: ResMut<StableOpen>) {
+    stable_open.clear();
+}
+
+fn on_list(
+    In(ev): In<SessionEvent>,
+    mut stable_open: ResMut<StableOpen>,
+    mut names: ResMut<NameCache>,
+) {
+    if let SessionEvent::ListStabledPets {
+        npc,
+        num_stable_slots,
+        pets,
+    } = ev
+    {
+        list_stabled_pets(npc, num_stable_slots, pets, &mut stable_open, &mut names);
+    }
+}
+
+fn on_result(
+    In(ev): In<SessionEvent>,
+    mut stable_open: ResMut<StableOpen>,
+    mut errors: ResMut<StableErrors>,
+    commands: Res<NetCommands>,
+) {
+    if let SessionEvent::StableResult { result } = ev {
+        stable_result(result, &mut stable_open, &mut errors, &commands);
+    }
+}
+
+/// A stable master's pet list (`MSG_LIST_STABLED_PETS`): fill the [`StableOpen`] the stable feed
+/// ([`super`]) reads. Arrives unprompted off the gossip stable option — that is how the
+/// window opens — and again in answer to our own refresh send.
+fn list_stabled_pets(
+    npc: u64,
+    num_stable_slots: u8,
+    pets: Vec<StabledPet>,
+    stable_open: &mut StableOpen,
+    names: &mut NameCache,
+) {
+    debug!(
+        "net: stable master {npc:#x} listed {} pets ({num_stable_slots} slots bought)",
+        pets.len()
+    );
+    // **Seed the pet-name cache from the list** (decision 1688). Every row carries the pet's own
+    // number and the name its owner gave it — the exact `(pet_number, name)` pair
+    // `SMSG_PET_NAME_QUERY_RESPONSE` would answer with — so the pet a player unstables has a
+    // resolvable `UnitName("pet")` the moment it is summoned, instead of after a round trip.
+    //
+    // The window this closes is a real one the director hit: `PetStable_Update` sets the current
+    // pet's button tooltip to a bare `UnitName("pet")` (`PetStable.lua:161`, transcribed
+    // unguarded because the reference is unguarded), and hands it to `GameTooltip:SetText`, whose
+    // byte-pinned signature REQUIRES a string (`0x531b90`) and raises otherwise. Nil name ⇒ Lua
+    // error dialog, once per unstable.
+    //
+    // Why the reference does not trip over its own unguarded line: its pet-name cache is
+    // `petnamecache.wdb`, which **persists across sessions**, so a pet you have owned before is
+    // already warm before the packet arrives. benilla has no such file, so a window the reference
+    // has practically closed is wide open for us. Seeding is not a workaround for the missing
+    // cache — it is using the answer the server has already sent us in this very packet.
+    for pet in &pets {
+        if !pet.name.is_empty() {
+            names.insert_pet(pet.pet_number, pet.name.clone());
+        }
+    }
+    stable_open.open(npc, num_stable_slots, pets);
+}
+
+/// The answer to a stable verb (`SMSG_STABLE_RESULT`) — one byte, and the client's whole response
+/// to it is a five-way jump table (the raw remap/jump bytes at `0x4cadac`/`0x4cad98`; decision
+/// 1677):
+///
+/// | code | what the client does |
+/// |---|---|
+/// | 1 | `DisplayError(0x25)` = **`ERR_NOT_ENOUGH_MONEY`** — the only code that says anything |
+/// | 2–7 | **absolutely nothing** — vmangos's catch-all `STABLE_ERR_STABLE = 6` included |
+/// | 8, 9 | re-request the list |
+/// | 10 | **`inc` the local purchased-slot count**, then re-request |
+/// | 11 | fire `PET_STABLE_UPDATE` (no vmangos counterpart — nothing in 1.12 sends it) |
+/// | 0, ≥12 | nothing |
+///
+/// The re-request is not a benilla convenience: no success carries an updated list, so without it
+/// the window would go on showing the pre-action arrangement.
+///
+/// **Code 10's local increment happens BEFORE the guid test**, so a buy-slot success arriving with
+/// no stable master open still bumps the count without refreshing. That ordering is reproduced
+/// deliberately — it is what makes the purchase row correct if the window is reopened, and the
+/// alternative would be to invent a tidier client than the one being reimplemented.
+fn stable_result(
+    result: u8,
+    stable_open: &mut StableOpen,
+    errors: &mut StableErrors,
+    net_commands: &NetCommands,
+) {
+    use benilla_protocol::messages::stable_result as code;
+    // Ahead of the guid test, exactly as `0x4cacf3` sits ahead of `0x4cad05`.
+    if result == code::SUCCESS_BUY_SLOT {
+        stable_open.num_stable_slots = stable_open.num_stable_slots.saturating_add(1);
+    }
+    match result {
+        // The one code that speaks. Its text is the reference's own `GlobalStrings` value for
+        // `ERR_NOT_ENOUGH_MONEY`, reached through `DisplayError` row 0x25.
+        code::ERR_MONEY => {
+            debug!("net: stable purchase refused — not enough money");
+            errors.0.push("ERR_NOT_ENOUGH_MONEY");
+        }
+        code::SUCCESS_STABLE | code::SUCCESS_UNSTABLE | code::SUCCESS_BUY_SLOT => {
+            let Some(npc) = stable_open.npc else {
+                debug!("net: stable success {result} with no open stable — no re-list");
+                return;
+            };
+            debug!("net: stable action succeeded (code {result}) — re-listing");
+            let _ = net_commands.0.send(ClientCommand::ListStabledPets { npc });
+        }
+        // Codes 2–7 (the generic ERR_STABLE among them), 0 and ≥12: the client shows NOTHING.
+        // Not an omission — the catch-all is one code for six causes, and the reference declines to
+        // guess which.
+        _ => debug!("net: stable result {result} — no client-visible effect"),
+    }
+}
diff --git a/crates/benilla-app/src/ui_summon.rs b/crates/benilla-app/src/ui_summon.rs
index b913a923..94270afe 100644
--- a/crates/benilla-app/src/ui_summon.rs
+++ b/crates/benilla-app/src/ui_summon.rs
@@ -27,7 +27,7 @@
 //!    resolves the active player (`0x468550` → `0x468460` with typemask `0x10` = player) and, if
 //!    `0x605f30` says yes, returns without latching *or* firing (`5e6194: jne`). So the request
 //!    does not merely fail to show a dialog: it does not disturb a previously latched one either,
-//!    which is why [`apply::request`] is the gate and the popup engine's `whileDead` rule is not.
+//!    which is why [`net::request`] is the gate and the popup engine's `whileDead` rule is not.
 //!
 //!    **`0x605f30` is not "is dead"** — that reading cost a wrong first cut here. It is
 //!    `[values+0x40] <= 0` (signed, `605f3b: jle`) **OR** (typemask bit `0x10` **AND** the
@@ -78,7 +78,7 @@ use crate::net::{ClientCommand, NetCommands};
 use crate::ui_script::{UiFeed, UiInput};
 
 /// The pending summon question — the reference's four-global bank (module doc, pin 1). Written by
-/// the net drain's `SummonRequest` arm through [`apply::request`], read by [`feed_summon`] (which
+/// the net drain's `SummonRequest` arm through [`net::request`], read by [`feed_summon`] (which
 /// pushes the three getters' answers and fires `CONFIRM_SUMMON`) and by [`drain_summon`] (which
 /// turns the dialog's Accept into the response).
 #[derive(Resource, Default)]
@@ -246,12 +246,58 @@ fn end_session_summon(
     }
 }
 
-/// The net drain's `SessionEvent::SummonRequest` arm, factored here so the wire law lives beside
-/// the state it drives.
-pub(crate) mod apply {
-    use bevy::prelude::debug;
+/// The summon's packet handler (decision 1747; in the net handler table since 2312), beside the
+/// state it drives.
+pub(crate) mod net {
+    use bevy::prelude::*;
 
     use super::SummonState;
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+
+    use crate::net::NetHandlerApp;
+    use crate::net::{GuidIndex, ObjectStore, SelfGuid};
+
+    /// Register the handler — called from [`super::UiSummonPlugin`].
+    pub(super) fn register(app: &mut App) {
+        app.net_handler(SessionEventKind::SummonRequest, on_request);
+    }
+
+    /// Someone is asking to pull us to them. The reference gates this in the HANDLER, not the
+    /// dialog: a dead or ghost player's request is dropped before the latch, so it cannot
+    /// disturb a live question either (`0x5e6194`). The predicate is `0x605f30` — **health ≤ 0
+    /// OR (is-player AND `PLAYER_FLAGS` ghost bit)**, which is both of these accessors and not
+    /// the one `unit_is_dead` alone would give (a ghost's wire health is 1). A self object we
+    /// have not streamed yet reads as alive: the reference's own default (`0x5e6189` sends a
+    /// NULL object through to the latch).
+    fn on_request(
+        In(ev): In<SessionEvent>,
+        mut summon: ResMut<SummonState>,
+        self_guid: Res<SelfGuid>,
+        index: Res<GuidIndex>,
+        stores: Query<&ObjectStore>,
+        real_clock: Res<Time<Real>>,
+    ) {
+        if let SessionEvent::SummonRequest {
+            summoner,
+            zone,
+            delay_ms,
+        } = ev
+        {
+            let dead_or_ghost = self_guid
+                .0
+                .and_then(|g| index.0.get(&g))
+                .and_then(|e| stores.get(*e).ok())
+                .is_some_and(|s| s.0.unit_is_dead() || s.0.player_is_ghost());
+            request(
+                summoner,
+                zone,
+                delay_ms,
+                dead_or_ghost,
+                real_clock.elapsed_secs_f64(),
+                &mut summon,
+            );
+        }
+    }
 
     /// `SMSG_SUMMON_REQUEST` — latch the offer and owe the UI a dialog, unless we are dead or a
     /// ghost.
@@ -295,6 +341,7 @@ pub(crate) struct UiSummonPlugin;
 
 impl Plugin for UiSummonPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<SummonState>().add_systems(
             Update,
             (
@@ -349,15 +396,15 @@ mod tests {
     #[test]
     fn a_summon_that_arrives_while_refused_latches_nothing() {
         let mut summon = SummonState::default();
-        apply::request(0x2a, 1519, 120_000, true, 100.0, &mut summon);
+        net::request(0x2a, 1519, 120_000, true, 100.0, &mut summon);
         assert_eq!(summon.pending(), None);
         assert!(!summon.ask);
         assert_eq!(summon.time_left_ms(100.0), 0);
 
         // A live question, then a second request while refused: the first survives untouched.
-        apply::request(0x2a, 1519, 120_000, false, 100.0, &mut summon);
+        net::request(0x2a, 1519, 120_000, false, 100.0, &mut summon);
         summon.ask = false;
-        apply::request(0x99, 1, 120_000, true, 150.0, &mut summon);
+        net::request(0x99, 1, 120_000, true, 150.0, &mut summon);
         assert_eq!(
             summon.pending(),
             Some(0x2a),
diff --git a/crates/benilla-app/src/ui_tabard.rs b/crates/benilla-app/src/ui_tabard.rs
index d3bfaafa..bae54585 100644
--- a/crates/benilla-app/src/ui_tabard.rs
+++ b/crates/benilla-app/src/ui_tabard.rs
@@ -1,4 +1,4 @@
-//! The guild tabard designer (decision 1977; wow-re `system/ui/scratch/tabard-designer.md`):
+//! The guild tabard designer (decision 1977):
 //! the app half of the stock `TabardFrame.xml` — the vendor session, the body preview, the save's
 //! pre-flight checks and wire, the reply, and the four events.
 //!
@@ -235,7 +235,8 @@ fn drain_tabard(
             TabardIntent::Close => open.close_core(),
             TabardIntent::Save(design) => {
                 // The vendor guid is the global UI interaction target, which the open set to
-                // this vendor (§2c); ours is the session's stored guid, the same value.
+                // this vendor (`0x502a60` reads `[0xb4e2d0]`); ours is the session's stored guid,
+                // the same value.
                 let Some(vendor) = open.vendor else {
                     continue;
                 };
@@ -287,10 +288,49 @@ fn reset_on_world_enter(
     design.0 = None;
 }
 
+/// The tabard vendor's packet handlers (in the net handler table since 2312), beside the state
+/// they drive.
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::TabardOpen;
+    use crate::net::NetHandlerApp;
+    use crate::ui_guild::GuildState;
+
+    /// Register the two handlers — called from [`super::TabardUiPlugin`].
+    pub(super) fn register(app: &mut App) {
+        use SessionEventKind as K;
+        app.net_handler(K::TabardVendorActivate, on_activate)
+            .net_handler(K::SaveGuildEmblemResult, on_save_result);
+    }
+
+    fn on_activate(In(ev): In<SessionEvent>, mut tabard: ResMut<TabardOpen>) {
+        if let SessionEvent::TabardVendorActivate(vendor) = ev {
+            tabard.open(vendor);
+        }
+    }
+
+    /// A saved emblem evicts our guild's cached record (`0x5e715f`): the next query anywhere
+    /// re-fetches it — no event, no packet.
+    fn on_save_result(
+        In(ev): In<SessionEvent>,
+        mut tabard: ResMut<TabardOpen>,
+        mut guild: ResMut<GuildState>,
+    ) {
+        if let SessionEvent::SaveGuildEmblemResult(result) = ev {
+            if tabard.apply_result(result) {
+                guild.evict_own_identity();
+            }
+        }
+    }
+}
+
 pub(crate) struct TabardUiPlugin;
 
 impl Plugin for TabardUiPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<TabardOpen>()
             .init_resource::<TabardDesign>()
             .add_systems(
diff --git a/crates/benilla-app/src/ui_talent.rs b/crates/benilla-app/src/ui_talent.rs
index 93a0b3af..030ea774 100644
--- a/crates/benilla-app/src/ui_talent.rs
+++ b/crates/benilla-app/src/ui_talent.rs
@@ -10,14 +10,14 @@
 //! - **name/icon** ride the display rank's spell (`Spell.dbc`), max(rank, 1) — an unlearned
 //!   talent wears rank 1's face, the reference's own look.
 //! - **`learnable`** (the tooltip's green "Click to learn" hint) = unspent points > 0 ∧
-//!   `rank < maxRank` — the hint's own byte-verified gate (SetTalent `0x535170`, wow-re
-//!   `talent-api.md`); the frame's gold/green/gray availability compose Lua-side from the
-//!   transcribed reference (tier gate, prereq triplets, meetsPrereq). The learn SEND gates on
-//!   not-at-max only (LearnTalent `0x4f36a0`) — the server enforces the rest.
+//!   `rank < maxRank` — the hint's own gate (SetTalent `0x535170`); the frame's gold/green/gray
+//!   availability compose Lua-side from the transcribed reference (tier gate, prereq triplets,
+//!   meetsPrereq). The learn SEND gates on not-at-max only (LearnTalent `0x4f36a0`) — the server
+//!   enforces the rest.
 //! - **tooltip req lines** (red, shown while locked): `TOOLTIP_TALENT_TIER_POINTS` (`0x854a40`)
 //!   for a short tab total, `TOOLTIP_TALENT_PREREQ[_P1]` (`0x854a5c`) per unmet prereq slot, and
 //!   `ITEM_REQ_SKILL` (`0x84e338`, reused from the item tooltip) for an unmet `required_spell` —
-//!   the three keys `0x52b390` emits, in wow-re `talent-api.md`'s own order. **Keys, resolved off
+//!   the three keys `0x52b390` emits, in the reference's own order. **Keys, resolved off
 //!   the player's own `GlobalStrings.lua` at the feed** (decision 2045), never sentences written
 //!   here; a key the install does not carry renders no line, which is the reference's own
 //!   data-suppression face (the desaturation still communicates the lock).
@@ -251,8 +251,8 @@ pub(crate) fn build_pages(
                 0
             };
             let d = spells.get(display_spell);
-            // meetsPrereq is the requiredSpell known-check ONLY (byte-verified GetTalentInfo,
-            // wow-re talent-api.md — the 0305 fold-back; talent prereqs live in the triplets).
+            // meetsPrereq is the requiredSpell known-check ONLY (GetTalentInfo `0x4f3200` — the
+            // 0305 fold-back; talent prereqs live in the triplets).
             let meets_prereq = t.required_spell == 0 || known.contains(&t.required_spell);
             // The tier gate reads the tab's own spent sum; prereqs read the prereq's rank.
             let tier_unlocked = t.row * 5 <= spent;
@@ -264,8 +264,8 @@ pub(crate) fn build_pages(
                 );
             }
             // The requiredSpell line rides ITEM_REQ_SKILL (`0x84e338`, the item tooltip's own
-            // key reused) — byte-verified in the SetTalent builder, wow-re talent-api.md. It is
-            // NOT the `LOCKED_WITH_*`/`SPELL_FAILED_*` family, which reads identically in enUS.
+            // key reused) — emitted by the SetTalent requirement builder `0x52b390`. It is NOT the
+            // `LOCKED_WITH_*`/`SPELL_FAILED_*` family, which reads identically in enUS.
             if !meets_prereq {
                 if let Some(req) = spells.get(t.required_spell) {
                     req_lines.extend(get("ITEM_REQ_SKILL").map(|f| fill(&f, &[Arg::S(&req.name)])));
@@ -294,7 +294,7 @@ pub(crate) fn build_pages(
                 }
             }
             // The green learn hint's own gate is points-available && not-maxed ONLY
-            // (byte-verified SetTalent, wow-re talent-api.md) — the frame's gold/green/gray
+            // (SetTalent `0x535170`) — the frame's gold/green/gray
             // availability law stays the transcribed Lua's (tier/prereq/meetsPrereq).
             let learnable = rank < max_rank && points.0 > 0;
             views.push(TalentView {
@@ -418,7 +418,7 @@ mod tests {
     /// them dropped before 1584. That is why the director's screenshot could show a 20-point
     /// Discipline tree beside "Talent Points: 51": the points are a descriptor field and arrived,
     /// the ranks are this set and did not. The arm that empties it has its own test beside it
-    /// (`net::apply::spells::a_removal_shrinks_the_book_and_dirties_the_feeds`).
+    /// (`spell::net::tests::a_removal_shrinks_the_book_and_dirties_the_feeds`).
     #[test]
     fn an_emptied_book_reads_as_a_wiped_tree() {
         let t = talent(1, 201, 0, 0, &[14522, 14788, 14789]);
diff --git a/crates/benilla-app/src/ui_talent_wipe.rs b/crates/benilla-app/src/ui_talent_wipe.rs
index fd74b447..7efc31c0 100644
--- a/crates/benilla-app/src/ui_talent_wipe.rs
+++ b/crates/benilla-app/src/ui_talent_wipe.rs
@@ -13,8 +13,7 @@
 //! It is the innkeeper bind's twin, not a talent-window affordance, and that is why it lives beside
 //! [`crate::ui_binder`] rather than inside [`crate::ui_talent`]: same shape on the wire (a question
 //! carrying a guid, an answer echoing it), same latch, same range gate, same free-standing dialog
-//! over a gossip menu that is already gone. wow-re says so at the bytes
-//! (`system/ui/scratch/gossip-icon-and-binder-flow.md` §5.3): the talent master
+//! over a gossip menu that is already gone. The bytes say so: the talent master
 //! (`0xc4d7a0`/`0xc4d7a4`), the pet untrainer and the binder are **one latch/range family**, three
 //! copies of a single shape.
 //!
@@ -28,8 +27,7 @@
 //!   the frame it goes false.
 //!
 //! Both halves are **byte-pinned** against the reference's `0x5df980`, one function that serves
-//! both directions of the opcode (wow-re `system/ui/scratch/talent-api.md` §ConfirmTalentWipe, and
-//! the disassembly under it):
+//! both directions of the opcode:
 //!
 //! 1. **Arrival** (`guid != 0`): resolve the unit, gate on `d² <= [0xc4c28c]` — the identical
 //!    constant behind [`crate::target::SERVICE_RANGE_SQ`], which is what makes modelling the
@@ -196,10 +194,39 @@ fn drain_talent_wipe(
 }
 
 /// The respec flow: the range guard, the dialog's feed, and its answer.
+/// The talent-wipe question's packet handler (decision 1580; in the net handler table since 2313).
+mod net {
+    use benilla_protocol::{SessionEvent, SessionEventKind};
+    use bevy::prelude::*;
+
+    use super::TalentWipeState;
+    use crate::net::NetHandlerApp;
+
+    /// Register the handler — called from [`super::UiTalentWipePlugin`].
+    pub(super) fn register(app: &mut App) {
+        app.net_handler(SessionEventKind::TalentWipeConfirm, on_confirm);
+    }
+
+    /// A zero trainer guid is vmangos's "you have no talents to reset" refusal, not a question —
+    /// there is nothing to ask about, so nothing goes on screen (this module's header carries
+    /// why the reference instead re-sends here).
+    fn on_confirm(In(ev): In<SessionEvent>, mut wipe: ResMut<TalentWipeState>) {
+        if let SessionEvent::TalentWipeConfirm { trainer, cost } = ev {
+            if trainer == 0 {
+                debug!("net: talent wipe refused (no talents to reset) — no dialog");
+            } else {
+                debug!("net: trainer {trainer:#x} asks to wipe talents for {cost} copper");
+                wipe.ask(trainer, cost);
+            }
+        }
+    }
+}
+
 pub(crate) struct UiTalentWipePlugin;
 
 impl Plugin for UiTalentWipePlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<TalentWipeState>().add_systems(
             Update,
             (
diff --git a/crates/benilla-app/src/ui_taxi/mod.rs b/crates/benilla-app/src/ui_taxi/mod.rs
index 71447d52..e68a2ee7 100644
--- a/crates/benilla-app/src/ui_taxi/mod.rs
+++ b/crates/benilla-app/src/ui_taxi/mod.rs
@@ -1,7 +1,7 @@
 //! The app-side **taxi feed/drain** (decision 0484 phases 1-2) — the two-way half of the taxi-map
 //! seam around [`benilla_ui::script`]'s `taxi` module ([`crate::ui_trainer`]'s feed/drain shape).
 //!
-//! **Phase 1** (unchanged): the net bridge (`crate::net::apply::npc`) fills [`TaxiState`] from the
+//! **Phase 1** (unchanged): the net bridge (`crate::ui_taxi::net`) fills [`TaxiState`] from the
 //! wire — `SMSG_SHOWTAXINODES` opens the map (flight master + nearest node + known-node bitmask),
 //! `SMSG_ACTIVATETAXIREPLY` stages the activate verdict, the first-visit "learn" pair stages the
 //! discovery flag — and the standardized NPC-session range guard client-side-closes the map when
@@ -34,8 +34,8 @@ use bevy::prelude::*;
 use benilla_ui::script::{TaxiUiState, UiScript};
 
 use crate::names::NameCache;
-use crate::net::{ClientCommand, NetCommands};
-use crate::player::Player;
+use crate::net::{ClientCommand, NetCommands, ObjectStore, SelfPlayer};
+use crate::player::UNIT_FLAG_TAXI_FLIGHT;
 use crate::ui_script::{UiFeed, UiInput};
 use crate::ui_session::{close_npc_session_out_of_range, NpcSession};
 
@@ -98,8 +98,8 @@ impl TaxiState {
 
 /// A flight master's answered node status (`SMSG_TAXINODE_STATUS`, upserted by the net bridge):
 /// `known = false` (an undiscovered nearest node) shows the green `TalkToMeGreen` overhead icon —
-/// the client's `0x5ecdd0` handler → `0x607480` marker swap (resource table `0xc4d9d8` index 4),
-/// byte-verified in the 0497 §5.
+/// the client's `0x5ecdd0` handler → `0x607480` marker swap (resource table `0xc4d9d8` index 4,
+/// decision 0497).
 ///
 /// **The query and the teardown are [`crate::quest_markers::query`]'s, not this module's**
 /// (decision 1918). `0x5eb170` — the only `CMSG_TAXINODE_STATUS_QUERY` sender in the image — has
@@ -128,19 +128,17 @@ impl NpcSession for TaxiState {
 /// Push the current taxi map into the VM, fire `TAXIMAP_OPENED`/`TAXIMAP_CLOSED` on a transition
 /// (or a content/name change), surface an activate refusal on the red error line (closing the map
 /// on `OK` instead — the flight starts and the map has nothing left to show), present a
-/// first-visit discovery, and push the `UnitOnTaxi` ride flag off [`Player::server_riding`].
-/// Diffed against `Local` memory, the trainer/merchant feed shape.
+/// first-visit discovery. Diffed against `Local` memory, the trainer/merchant feed shape. (The
+/// `UnitOnTaxi` flag is [`feed_on_taxi`]'s — it reads the descriptor, not the taxi window.)
 fn feed_taxi(
     script: Option<NonSendMut<UiScript>>,
     mut state: ResMut<TaxiState>,
     catalogs: Option<Res<TaxiCatalogs>>,
-    player: Res<Player>,
     names: Res<NameCache>,
     commands: Res<NetCommands>,
     mut cache: ResMut<TaxiRouteCache>,
     mut last: Local<crate::ui_script::VmMemo<Option<TaxiUiState>>>,
     mut last_name: Local<crate::ui_script::VmMemo<Option<String>>>,
-    mut last_riding: Local<crate::ui_script::VmMemo<Option<bool>>>,
     mut sink: crate::ui_action::MessageSink,
 ) {
     let Some(mut script) = script else {
@@ -148,7 +146,6 @@ fn feed_taxi(
     };
     let last = last.get(&script);
     let last_name = last_name.get(&script);
-    let last_riding = last_riding.get(&script);
 
     // The activate verdict (SMSG_ACTIVATETAXIREPLY), staged by the net bridge: a refusal goes to
     // the surface its message record names ([`taxi_error_key`] — seven of the twelve are the
@@ -178,8 +175,8 @@ fn feed_taxi(
     }
 
     // The first-visit "learn" (SMSG_NEW_TAXI_PATH): the real client shows message 0xf2 —
-    // ERR_NEWTAXIPATH, "New flight path discovered!" — via its descriptor (byte-verified at §5
-    // grade, decision 0516 resolving 0501 §1's INTERIM): channel 1 routes the text to the
+    // ERR_NEWTAXIPATH, "New flight path discovered!" — via its descriptor (decision 0516
+    // resolving 0501 §1's INTERIM): channel 1 routes the text to the
     // YELLOW `UI_INFO_MESSAGE` FrameScript event (`0x4945b0` → event 0xe1 — good news, not the
     // red warning), and tag 0x44 plays the descriptor's `+0x08` string as a SOUND-KIT NAME
     // through `PlaySoundByName` (`0x458030`, the `MasterSoundEffects`-gated kit lookup) —
@@ -251,14 +248,37 @@ fn feed_taxi(
         *last = fresh;
         *last_name = flightmaster_name;
     }
+}
 
-    // UnitOnTaxi: a server-authored spline currently owns the avatar (Charge/knockback/taxi —
-    // 0260's rails); taxi is one of its callers, so this is the faithful signal without any
-    // taxi-specific movement state. Diffed like every other single-value push.
-    let riding = player.server_riding();
-    if *last_riding != Some(riding) {
-        script.set_on_taxi(riding);
-        *last_riding = Some(riding);
+/// Push `UnitOnTaxi("player")` — **our own descriptor's `UNIT_FLAG_TAXI_FLIGHT`, and nothing
+/// else**. The reference's verb (`0x517a40`) resolves the token, then reads `UNIT_FIELD_FLAGS`
+/// (`[[obj+0x110]+0xa0]`) and answers `1` iff bit 20 is set (`0x517a86 shr ecx,0x14; test cl,1`).
+/// vmangos sets and clears that bit exactly around a flight (`WaypointMovementGenerator.cpp`, the
+/// `FlightPathMovementGenerator` initialize/finalize).
+///
+/// It used to read [`crate::player::Player::server_riding`] — "a server spline owns the avatar" —
+/// which is also true under a fear's flee path, a Charge and a knockback. That was not a cosmetic
+/// over-answer: stock `UIParent.lua`'s `PLAYER_CONTROL_LOST` handler returns early on
+/// `UnitOnTaxi("player")`, so a feared player kept every window open that the reference closes.
+///
+/// No self store streamed yet reads as not on a taxi — the verb's own absent-object `nil`.
+/// Diffed like every other single-value push.
+fn feed_on_taxi(
+    script: Option<NonSendMut<UiScript>>,
+    self_q: Query<&ObjectStore, With<SelfPlayer>>,
+    mut last: Local<crate::ui_script::VmMemo<Option<bool>>>,
+) {
+    let Some(mut script) = script else {
+        return;
+    };
+    let last = last.get(&script);
+    let on_taxi = self_q
+        .iter()
+        .next()
+        .is_some_and(|s| s.0.unit_flags() & UNIT_FLAG_TAXI_FLIGHT != 0);
+    if *last != Some(on_taxi) {
+        script.set_on_taxi(on_taxi);
+        *last = Some(on_taxi);
     }
 }
 
@@ -323,10 +343,13 @@ fn drain_taxi(
     }
 }
 
+mod net;
+
 pub(crate) struct UiTaxiPlugin;
 
 impl Plugin for UiTaxiPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<TaxiState>()
             .init_resource::<TaxiRouteCache>()
             .add_systems(
@@ -338,6 +361,7 @@ impl Plugin for UiTaxiPlugin {
                     // frame; drain after it (mirrors ui_merchant/ui_trainer).
                     close_npc_session_out_of_range::<TaxiState>.before(feed_taxi),
                     feed_taxi.in_set(UiFeed),
+                    feed_on_taxi.in_set(UiFeed),
                     drain_taxi.after(UiInput),
                 ),
             );
@@ -347,6 +371,50 @@ impl Plugin for UiTaxiPlugin {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use benilla_protocol::field::FIELD_UNIT_FLAGS;
+    use benilla_protocol::ObjectFields;
+
+    /// `UnitOnTaxi("player")` answers our descriptor's `UNIT_FLAG_TAXI_FLIGHT` — `1` with the
+    /// bit, `nil` without it — whatever else owns the avatar's movement. (A fear's flee path, a
+    /// Charge or a knockback are server splines too, and the feed reads nothing that knows about
+    /// them: it takes no `Player` at all.)
+    #[test]
+    fn unit_on_taxi_reads_the_taxi_flight_flag() {
+        let mut app = App::new();
+        app.add_systems(Update, feed_on_taxi);
+        app.insert_non_send_resource(UiScript::new().unwrap());
+        let me = app
+            .world_mut()
+            .spawn((
+                SelfPlayer,
+                ObjectStore(ObjectFields::from_pairs(&[(FIELD_UNIT_FLAGS, 0x1000)])),
+            ))
+            .id();
+        let on_taxi = |app: &mut App| -> bool {
+            app.update();
+            let s = app.world_mut().non_send_resource_mut::<UiScript>();
+            s.eval::<Option<i64>>(r#"return UnitOnTaxi("player")"#)
+                .unwrap()
+                .is_some()
+        };
+        assert!(!on_taxi(&mut app), "no TAXI_FLIGHT bit: nil");
+
+        app.world_mut()
+            .entity_mut(me)
+            .insert(ObjectStore(ObjectFields::from_pairs(&[(
+                FIELD_UNIT_FLAGS,
+                0x1000 | UNIT_FLAG_TAXI_FLIGHT,
+            )])));
+        assert!(on_taxi(&mut app), "the bit set: 1");
+
+        app.world_mut()
+            .entity_mut(me)
+            .insert(ObjectStore(ObjectFields::from_pairs(&[(
+                FIELD_UNIT_FLAGS,
+                0,
+            )])));
+        assert!(!on_taxi(&mut app), "landed: nil again");
+    }
 
     #[test]
     fn open_close_and_session_clear() {
diff --git a/crates/benilla-app/src/ui_taxi/net.rs b/crates/benilla-app/src/ui_taxi/net.rs
new file mode 100644
index 00000000..3222e7dd
--- /dev/null
+++ b/crates/benilla-app/src/ui_taxi/net.rs
@@ -0,0 +1,102 @@
+//! The taxi map's packet handlers (decision 0484 phase 1; in the net handler table since 2318,
+//! moved out of the drain's npc arm file) — the [`TaxiState`] session the taxi feed ([`super`])
+//! reads, and the flight masters' overhead status.
+
+use benilla_protocol::messages::TaxiMask;
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::TaxiState;
+use crate::net::{GuidIndex, NetHandlerApp};
+
+/// Register the taxi handlers — called from [`super::UiTaxiPlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::TaxiNodesShown, on_nodes_shown)
+        .net_handler(K::TaxiNodeStatus, on_node_status)
+        .net_handler(K::ActivateTaxiReply, on_activate_reply)
+        .net_handler(K::NewTaxiPath, on_new_path)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_nodes_shown(In(ev): In<SessionEvent>, mut taxi: ResMut<TaxiState>) {
+    if let SessionEvent::TaxiNodesShown {
+        flightmaster,
+        nearest_node,
+        known_mask,
+    } = ev
+    {
+        taxi_nodes_shown(flightmaster, nearest_node, known_mask, &mut taxi);
+    }
+}
+
+fn on_node_status(In(ev): In<SessionEvent>, mut commands: Commands, index: Res<GuidIndex>) {
+    if let SessionEvent::TaxiNodeStatus { guid, known } = ev {
+        taxi_node_status(guid, known, &mut commands, &index);
+    }
+}
+
+fn on_activate_reply(In(ev): In<SessionEvent>, mut taxi: ResMut<TaxiState>) {
+    if let SessionEvent::ActivateTaxiReply { code } = ev {
+        taxi_activate_reply(code, &mut taxi);
+    }
+}
+
+fn on_new_path(In(ev): In<SessionEvent>, mut taxi: ResMut<TaxiState>) {
+    if let SessionEvent::NewTaxiPath = ev {
+        taxi_new_path(&mut taxi);
+    }
+}
+
+/// An open taxi map dies with the socket. A listener on the session end
+/// (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut taxi: ResMut<TaxiState>) {
+    taxi.clear_session();
+}
+
+/// The taxi map (`SMSG_SHOWTAXINODES`): fill the [`TaxiState`] phase 2's feed will read — the
+/// trainer list's shape.
+fn taxi_nodes_shown(
+    flightmaster: u64,
+    nearest_node: u32,
+    known_mask: TaxiMask,
+    taxi: &mut TaxiState,
+) {
+    debug!("net: taxi map on {flightmaster:#x} — nearest node {nearest_node}");
+    taxi.open(flightmaster, nearest_node, known_mask);
+}
+
+/// A taxi node's known status (`SMSG_TAXINODE_STATUS`) — answers `CMSG_TAXINODE_STATUS_QUERY`
+/// ([`super`]'s per-flight-master ask), and also rides the first-visit learn pair
+/// alongside `SMSG_NEW_TAXI_PATH` ([`taxi_new_path`] carries that signal into `discovered`; the
+/// paired `known = true` here is what clears the icon live on a learn). Upserts
+/// [`super::FlightMasterStatus`] on the flight master: `known = false` shows the green
+/// `TalkToMeGreen` overhead icon — the client's `0x5ecdd0` handler → `0x607480` marker swap
+/// (resource table `0xc4d9d8` index 4; decision 0497). The client also gates the reply on the
+/// unit's NPC_FLAGS bit 3 — moot here: only flight masters are ever queried or answered.
+fn taxi_node_status(guid: u64, known: bool, commands: &mut Commands, index: &GuidIndex) {
+    debug!("net: taxi node status — {guid:#x} known={known}");
+    if let Some(&e) = index.0.get(&guid) {
+        commands
+            .entity(e)
+            .insert(super::FlightMasterStatus { known });
+    }
+}
+
+/// The activate verdict (`SMSG_ACTIVATETAXIREPLY`) — staged for phase 2's window to surface as
+/// the red error line and clear (the trainer/merchant error-line pattern, folded into
+/// `TaxiState.reply` since there's no other consumer yet).
+fn taxi_activate_reply(code: u32, taxi: &mut TaxiState) {
+    debug!("net: activate taxi reply — code {code}");
+    taxi.reply = Some(code);
+}
+
+/// A first-visit "learn" landed (`SMSG_NEW_TAXI_PATH`, empty body) — vmangos's only send site
+/// (`SendLearnNewTaxiNode`) always pairs this with a `SMSG_TAXINODE_STATUS(known=true)` for the
+/// same flight master, so the empty body alone is the discovery signal; phase 2's presentation
+/// reads the flag.
+fn taxi_new_path(taxi: &mut TaxiState) {
+    debug!("net: taxi — first-visit node learned (SMSG_NEW_TAXI_PATH)");
+    taxi.discovered = true;
+}
diff --git a/crates/benilla-app/src/ui_taxi/routing.rs b/crates/benilla-app/src/ui_taxi/routing.rs
index 73e199e7..a205d228 100644
--- a/crates/benilla-app/src/ui_taxi/routing.rs
+++ b/crates/benilla-app/src/ui_taxi/routing.rs
@@ -1,6 +1,6 @@
 //! The taxi domain logic split out of [`super`] purely for size (the ui_taxi module doc): the
 //! static DBC catalogs, the byte-verified map projection and geo-distance route search (decision
-//! 0496 — the 0484 §5 fold-back), and the node list they build together. Pure/testable — no Bevy
+//! 0496 — the 0484 fold-back), and the node list they build together. Pure/testable — no Bevy
 //! system runs here except the catalog loader, which only reaches out for the patch chain.
 
 use std::cmp::Reverse;
@@ -74,9 +74,8 @@ pub(super) fn load_taxi_catalogs(
     }
 }
 
-/// Project a node's world `(x, y)` onto the taxi map's normalized 0..1 space — **byte-VERIFIED**
-/// (decision 0496 folds back the 0484 §5's TU-2: the FPU trace at `0x4db958`, recorded in wow-re
-/// `system/ui/scratch/taxi-system.md`): rect = `WorldMapContinent.dbc` fields 9–12
+/// Project a node's world `(x, y)` onto the taxi map's normalized 0..1 space (decision 0496; the
+/// FPU trace at `0x4db958`): rect = `WorldMapContinent.dbc` fields 9–12
 /// (Xmin/Ymin/Xmax/Ymax), matched by continentId, and
 ///
 /// ```text
@@ -104,8 +103,8 @@ pub(crate) fn project(cont: &WorldMapContinent, world_x: f32, world_y: f32) -> (
 type Edge = (u32, u32);
 
 /// Shortest route from `from` to `to` over a directed graph, expansion restricted to nodes `known`
-/// marks discovered — **the byte-verified metric** (decision 0496 folds back 0484 §5 TU-3,
-/// superseding INTERIM I2's fare-Dijkstra): the client's route relaxation (`0x4dbce0`, metric
+/// marks discovered — **the byte-verified metric** (decision 0496 folds back 0484, superseding
+/// INTERIM I2's fare-Dijkstra): the client's route relaxation (`0x4dbce0`, metric
 /// `0x4dbbd0`) minimizes **summed geographic distance**, carrying the money fare and the hop
 /// count *alongside* the optimization, not in it. `edges(node)` returns `node`'s outgoing
 /// `(to, fare)` pairs; `dist(a, b)` is the geographic metric between two node ids (production:
@@ -283,11 +282,11 @@ pub(super) fn build_nodes(
 ///
 /// The reference's parser `FUN_005ed1e0` indexes a 13-entry table at `[0x85fedc + 4*code]` and
 /// hands the result straight to `CGGameUI::DisplayError 0x496720`: `code == 0` closes the map,
-/// `1..=12` toast, `code >= 13` does nothing at all (wow-re `system/ui/scratch/taxi-system.md`
-/// §TU-1, VERIFIED byte-exact). So this returns a key rather than a string, and the catalog row
-/// behind it decides the text, the **surface** and the sound — which matters here more than
-/// anywhere: **seven of the twelve are `kind = 1`, the YELLOW info line**, not the red one they
-/// all used to take, and `ERR_TAXINOTENOUGHMONEY` carries error-speech line `0x36` (decision 1815).
+/// `1..=12` toast, `code >= 13` does nothing at all. So this returns a key rather than a string,
+/// and the catalog row behind it decides the text, the **surface** and the sound — which matters
+/// here more than anywhere: **seven of the twelve are `kind = 1`, the YELLOW info line**, not the
+/// red one they all used to take, and `ERR_TAXINOTENOUGHMONEY` carries error-speech line `0x36`
+/// (decision 1815).
 ///
 /// `OK` and anything past the table return `None` — the reference's own `code >= 13` no-op, in
 /// place of the "Taxi activation failed (n)." literal that used to stand here and that the
diff --git a/crates/benilla-app/src/ui_text/engine/faces.rs b/crates/benilla-app/src/ui_text/engine/faces.rs
index 7c977c13..51f77d2d 100644
--- a/crates/benilla-app/src/ui_text/engine/faces.rs
+++ b/crates/benilla-app/src/ui_text/engine/faces.rs
@@ -15,10 +15,10 @@ pub(super) const CLIENT_FONTS: &[&str] = &[
 /// The face's baseline ascender as a fraction of the em — `hhea.asc / (hhea.asc + |hhea.desc|)` —
 /// straight from the raw sfnt bytes. This is the term in the client's glyph *placement* law: the
 /// ink hangs from the pixel ascender `[CGxFont+0x17c] = round(em · asc/(asc+|desc|))`, threaded
-/// unchanged into `glyph_vplace` (0x5d1360) as the operand that fixes `baseline = cellTop +
-/// ascender` (wow-re `system/font`, §5-verified 2026-07-09: the call chain `0x5ca160 → 0x5d1120
-/// [ebp+0xc] → 0x5d1360 [ebp+0x10]`, where the cell's own `[[FT_Face+0x54]+0x68]` is the
-/// per-glyph `bitmap_top`, the *subordinate* operand). This is the `ComputeRasterMetrics`
+/// unchanged into the glyph placement kernel (0x5d1360) as the operand that fixes
+/// `baseline = cellTop + ascender` (the call chain `0x5ca160 → 0x5d1120 [ebp+0xc] → 0x5d1360
+/// [ebp+0x10]`, where the cell's own `[[FT_Face+0x54]+0x68]` is the per-glyph `bitmap_top`, the
+/// *subordinate* operand). This is the `ComputeRasterMetrics`
 /// `load_param`; the FreeType scaled hhea ascender (`asc/upem` ≈ 0.965) appears NOWHERE in the
 /// placement path — seating with it drops every line ~3px too low for Friz (965/1215 ≈ 0.794 vs
 /// 0.965 → baseline row 10 vs 13 in a 13-tall cell). A tiny table-directory walk (`hhea` →
diff --git a/crates/benilla-app/src/ui_text/engine/mod.rs b/crates/benilla-app/src/ui_text/engine/mod.rs
index 71c013eb..63a54003 100644
--- a/crates/benilla-app/src/ui_text/engine/mod.rs
+++ b/crates/benilla-app/src/ui_text/engine/mod.rs
@@ -22,15 +22,14 @@
 //!
 //! ## What the real client does
 //!
-//! wow-re `system/font` (T3, verified — the lifecycle re-derived by a four-pair cross-check for
-//! decision 1342): a `CGxFont` exists per (face, flags, **exact pixel size**), the size being
-//! `min(32, round(H · max(reqSize, 2/H)))` (`0x5ca030` → `[CGxFont+0x24c]`) — integer device
-//! pixels, always. Glyphs are rasterized **on demand** by `NewCodeDesc` (`0x5cabd0`) into a
-//! per-font `TSHashTable<codepoint → CharCodeDesc>` (`+0x30/+0x38`) and land in a row-partitioned
-//! texture cache (`texcache_set_cellsize` `0x5cf360`, cell size `em + 2·outline pad`, free-slot
-//! search `0x5cf5a0`) of up to 8 pages (`CGxFont+0x18c`). One bitmap per (font, codepoint), zero
-//! subpixel phases — the face is sized by `FT_Set_Pixel_Sizes` to a square integer ppem and the
-//! module calls no `FT_Set_Transform` anywhere.
+//! In the reference (decision 1342), a `CGxFont` exists per (face, flags, **exact pixel size**),
+//! the size being `min(32, round(H · max(reqSize, 2/H)))` (`0x5ca030` → `[CGxFont+0x24c]`) —
+//! integer device pixels, always. Glyphs are rasterized **on demand** by `NewCodeDesc` (`0x5cabd0`)
+//! into a per-font `TSHashTable<codepoint → CharCodeDesc>` (`+0x30/+0x38`) and land in a
+//! row-partitioned texture cache (the cell-size setter `0x5cf360`, cell size `em + 2·outline pad`,
+//! free-slot search `0x5cf5a0`) of up to 8 pages (`CGxFont+0x18c`). One bitmap per (font,
+//! codepoint), zero subpixel phases — the face is sized by `FT_Set_Pixel_Sizes` to a square integer
+//! ppem and the module calls no `FT_Set_Transform` anywhere.
 //!
 //! There is no size ladder and no snapping. **`k` has no counterpart in the ordinary UI path**,
 //! and the reason is precise: `CSimpleFontString`'s constructor sets the one-to-one bit
@@ -822,20 +821,15 @@ impl UiFontAtlas {
     }
 }
 
-/// Read one font path from the two stores, chain first.
+/// Read one font path from the two stores, chain first —
+/// [`benilla_assets::read_chain_or_loose`], the one rule every by-path addon asset resolves by.
 ///
-/// The loose leg goes through the same [`benilla_assets::loose_addon_file`] the sprite decoder
-/// uses, so it inherits its rules whole: only `Interface\AddOns\` paths reach the folder, the
-/// component walk is case-insensitive (MSBT names its own files `Interface\Addons\…` with a
-/// lowercase `d`, and ships `mailrays.TTF` while its table says `mailrays.ttf`), and a
+/// It inherits that rule whole rather than restating it: only `Interface\AddOns\` paths reach the
+/// folder, the component walk is case-insensitive (MSBT names its own files `Interface\Addons\…`
+/// with a lowercase `d`, and ships `mailrays.TTF` while its table says `mailrays.ttf`), and a
 /// dot-component is refused before any filesystem call.
 fn read_font_bytes(source: &FontSource, path: &str) -> Option<Vec<u8>> {
-    if let Ok(bytes) = source.chain.lock_recover().read(path) {
-        return Some(bytes);
-    }
-    let root = source.loose_root.as_deref()?;
-    let file = benilla_assets::loose_addon_file(root, &benilla_assets::normalize_path(path))?;
-    std::fs::read(file).ok()
+    benilla_assets::read_chain_or_loose(&source.chain, source.loose_root.as_deref(), path)
 }
 
 /// A real-font engine for a test: the client faces, read through the app's own patch chain. `None`
diff --git a/crates/benilla-app/src/ui_text/layout/measure.rs b/crates/benilla-app/src/ui_text/layout/measure.rs
index 0215f44d..c64c5eb4 100644
--- a/crates/benilla-app/src/ui_text/layout/measure.rs
+++ b/crates/benilla-app/src/ui_text/layout/measure.rs
@@ -108,8 +108,8 @@ pub(crate) fn measure_line_width_for_test(
 /// Greedy word-boundary wrap of one markup line (a `\n`-delimited run sequence) into sub-lines that
 /// each fit within `max_width` px.
 ///
-/// The break law is the byte-verified regime-2 wrap (`system/ui/scratch/fontstring-overflow.md`,
-/// the `0x5c6c50`/`0x5c7780` kernel): break at the last break opportunity; a word with none that
+/// The break law is the regime-2 wrap (the `0x5c6c50`/`0x5c7780` kernel): break at the last
+/// break opportunity; a word with none that
 /// overflows alone force-breaks at the last fitting glyph — a rendered line never exceeds the wrap
 /// width. Inter-word whitespace is preserved verbatim (a double space after a period stays a double
 /// space — see [`tokenize_words`]), and only the trailing separator at a line break drops. Colors
@@ -181,9 +181,9 @@ pub(crate) fn measure_text(
     // refactor's.
     //
     // Height: N lines at the client's intrinsic pitch — the font em, NO outline pad (the byte law:
-    // `font_textblock_height 0x5c2070` = N·S + (N−1)·gap, spacing 0 for all shipped UI; the +2r
-    // lives only in the atlas CELL, never the block math — `fontstring-vertical-placement.md`). An
-    // outlined line's ring pokes past this height by design, exactly as it does in the client.
+    // the text-block height kernel `0x5c2070` = N·S + (N−1)·gap, spacing 0 for all shipped UI; the
+    // +2r lives only in the atlas CELL, never the block math). An outlined line's ring pokes past
+    // this height by design, exactly as it does in the client.
     (max_w.ceil() + 1.0, render_lines.len() as f32 * r.size)
 }
 
@@ -213,9 +213,9 @@ fn wrapped_rows(e: &TextEngine, r: Resolved, text: &str, wrap_width: f32) -> usi
 /// [`wrapped_rows`] that stops once `cap` rows exist — the client's own fit walk is bounded by the
 /// BOX, not by the string: `GxuFont_GetMaxCharsWithinHeight` (`0x5c21c0`) lays out `min(needed,
 /// fits + 1)` lines and abandons the rest, because the height test sits downstream of the per-line
-/// kernel call (wow-re `system/ui/scratch/fontstring-ellipsis-cost.md`). A caller that only needs
-/// to know whether the text OVERFLOWS passes `allowed + 1` and never pays for the tail; the chat
-/// band's row count, which is a real number, passes [`usize::MAX`].
+/// kernel call. A caller that only needs to know whether the text OVERFLOWS passes `allowed + 1`
+/// and never pays for the tail; the chat band's row count, which is a real number, passes
+/// [`usize::MAX`].
 fn wrapped_rows_capped(
     e: &TextEngine,
     r: Resolved,
@@ -261,9 +261,9 @@ pub(super) fn wrapped_rows_capped_for_test(
 }
 
 /// The FontString display string under the height-gated ellipsis-truncate — `CSimpleFontString
-/// 0x771ec0`, regime 3 of the overflow verdict (`fontstring-overflow.md`, decision 0292's named
-/// residue): when the wrapped text needs more lines than the box allows, the tail is replaced by
-/// `"..."`, backed off one char at a time until the candidate fits. `None` = draw the raw text
+/// 0x771ec0`, regime 3 of the overflow law (decision 0292's named residue): when the wrapped text
+/// needs more lines than the box allows, the tail is replaced by `"..."`, backed off one char at a
+/// time until the candidate fits. `None` = draw the raw text
 /// (fits, or the gate fails). The gate is geometric — `boxW > 0 && boxH > 0` on the resolved rect
 /// (`maxLines` unmodeled; nothing shipped sets it): an auto-height FontString's rect height IS its
 /// wrapped block (the measure round-trip), so it always fits and never truncates — the byte law's
diff --git a/crates/benilla-app/src/ui_text/layout/mod.rs b/crates/benilla-app/src/ui_text/layout/mod.rs
index 50c35b2b..7c601f9c 100644
--- a/crates/benilla-app/src/ui_text/layout/mod.rs
+++ b/crates/benilla-app/src/ui_text/layout/mod.rs
@@ -84,9 +84,8 @@ pub(crate) struct FontSpec<'a> {
     pub height: Option<f32>,
     /// The font's TRUE glyph outline ([`Outline::None`] for the common case). It selects the
     /// composite cell variant (ring+fill in one texture) AND, for THICK only, the step law's extra
-    /// `+1` (`GlyphStepBase` 0x5ca2b0 biases solely under the THICK flag — wow-re
-    /// `outline-bake-tint.md`), so [`measure_text`] must see it too: a THICK outline changes
-    /// measured/wrapped width.
+    /// `+1` (`GlyphStepBase` 0x5ca2b0 biases solely under the THICK flag), so [`measure_text`]
+    /// must see it too: a THICK outline changes measured/wrapped width.
     pub outline: Outline,
     /// The write-on reveal (`SetAlphaGradient` — per-FontString paint state, like `outline`):
     /// [`layout_text_quads`] multiplies each glyph's alpha by the ramp at its character position.
@@ -96,9 +95,9 @@ pub(crate) struct FontSpec<'a> {
     pub alpha_gradient: Option<(f32, f32)>,
 }
 
-/// The client's per-glyph **step law** (verified in wow-re, `system/font`): the rasterizer stores
-/// each glyph's step base as `(FT_advance >> 6) + 1.0` — the FreeType advance floored to integer
-/// pixels **plus one** (`rasterize_glyph` 0x5d1120, `out[5]`); an outlined font biases it another
+/// The client's per-glyph **step law**: the rasterizer stores each glyph's step base as
+/// `(FT_advance >> 6) + 1.0` — the FreeType advance floored to integer pixels **plus one** (the
+/// glyph rasterizer 0x5d1120, `out[5]`); an outlined font biases it another
 /// `+1.0` (`GlyphStepBase` 0x5ca2b0); `ComputeStep` 0x5ca2d0 consumes exactly that (plus
 /// only-negative kerning scaled by the face's advance-adjust, then rounds). This extra tracking is
 /// look-defining — it is why real client text reads wider/denser than the raw font metrics.
@@ -121,11 +120,10 @@ fn client_step(raw_physical_advance: f32, step_extra: f32) -> f32 {
 
 /// The step-law bias for a font's outline flag: the base `+1` for everyone, and one more `+1` for
 /// **THICK only** — `GlyphStepBase 0x5ca2b0` adds its extra pixel solely under the THICK font flag
-/// (wow-re `outline-bake-tint.md`, §5 + difftests, commit `f80ce699`, CORRECTING the earlier "any
-/// outline" reading this module shipped with: a NORMAL-outlined font steps exactly like a plain
-/// one, its 1px ring riding the base `+1` tracking; mirroring the cell pad onto the advance was the
-/// flagged trap). NumberFontNormal digits (money, counts, hotkeys) are the visible beneficiaries:
-/// one less pixel of gap per glyph.
+/// (CORRECTING the earlier "any outline" reading this module shipped with: a NORMAL-outlined font
+/// steps exactly like a plain one, its 1px ring riding the base `+1` tracking; mirroring the cell
+/// pad onto the advance was the flagged trap). NumberFontNormal digits (money, counts, hotkeys) are
+/// the visible beneficiaries: one less pixel of gap per glyph.
 fn step_extra_of(outline: Outline) -> f32 {
     match outline {
         Outline::Thick => 2.0,
@@ -133,15 +131,14 @@ fn step_extra_of(outline: Outline) -> f32 {
     }
 }
 
-/// The client's SINGLE vertical anchor snap (`anchor_justify_snap 0x5cdf70` @`0x5ce051`,
-/// `fontstring-vertical-placement.md`): the composed block top — rect top plus the justify offset —
-/// rounds ONCE to the integer pixel grid; the per-line ladder and the within-cell ascender are added
-/// as exact integers after it, never re-snapped. The client's round runs in the y-UP frame
-/// (`round(viewH·anchor.y)`), so a half-pixel tie pushes the block UP on screen — in y-down units
-/// that is round-half-DOWN, `ceil(y − 0.5)` (the money row's H=13/S=14 MIDDLE tie: offset −1, not 0
-/// — the note's Case 3). Applied in LOGICAL units: the byte law at the 768-tall design resolution
-/// (the 0292 posture), so a retina window seats text exactly as the design-resolution layout,
-/// scaled.
+/// The client's SINGLE vertical anchor snap (`0x5cdf70` @`0x5ce051`): the composed block top — rect
+/// top plus the justify offset — rounds ONCE to the integer pixel grid; the per-line ladder and the
+/// within-cell ascender are added as exact integers after it, never re-snapped. The client's round
+/// runs in the y-UP frame (`round(viewH·anchor.y)`), so a half-pixel tie pushes the block UP on
+/// screen — in y-down units that is round-half-DOWN, `ceil(y − 0.5)` (the money row's H=13/S=14
+/// MIDDLE tie: offset −1, not 0). Applied in LOGICAL units: the byte law at the 768-tall design
+/// resolution (the 0292 posture), so a retina window seats text exactly as the design-resolution
+/// layout, scaled.
 fn snap_block_top(y: f32) -> f32 {
     snap_block_top_law(y) + UI_SEAT_NUDGE
 }
@@ -285,10 +282,10 @@ fn layout_text_quads_inner(
     // The render lays the same lines the measure counted, or a MIDDLE-justified block seats
     // against a height it does not have ([`fontstring_lines`], decision 1343).
     let lines = fontstring_lines(text, base_color);
-    // The THICK ink rise (`fontstring-baseline-row.md`, §5 trio): the client's THICK quad shift
-    // (−2, `0x5cd0e1`) against its blit's baked seat nets the INK **1 row above** the plain
-    // baseline law; NORMAL cancels exactly (outline-invariant). Our composite cell reproduces the
-    // blit, so the quad carries the net: THICK cells rise 1 logical px.
+    // The THICK ink rise: the client's THICK quad shift (−2, `0x5cd0e1`) against its blit's baked
+    // seat nets the INK **1 row above** the plain baseline law; NORMAL cancels exactly
+    // (outline-invariant). Our composite cell reproduces the blit, so the quad carries the net:
+    // THICK cells rise 1 logical px.
     let thick_rise = f32::from(u8::from(matches!(font.outline, Outline::Thick)));
 
     // Word-wrap within the rect when it carries a pinned width; an unsized single-point FontString
@@ -306,12 +303,11 @@ fn layout_text_quads_inner(
     } else {
         lines
     };
-    // The height-limit line stack (regime 2's vertical half, `CGxString+0x40`,
-    // `fontstring-overflow.md`): a height-pinned rect stops emitting wrapped lines when the
-    // accumulated pitch passes it. A FontString the ellipsis seam ([`ellipsize_to_fit`]) already
-    // truncated fits by construction, so this is the belt under any caller that skips that seam —
-    // in the client the same split: the ui truncate feeds the gx string, and the gx line stack
-    // clamps regardless.
+    // The height-limit line stack (regime 2's vertical half, `CGxString+0x40` in `0x5cdc20`): a
+    // height-pinned rect stops emitting wrapped lines when the accumulated pitch passes it. A
+    // FontString the ellipsis seam ([`ellipsize_to_fit`]) already truncated fits by construction,
+    // so this is the belt under any caller that skips that seam — in the client the same split: the
+    // ui truncate feeds the gx string, and the gx line stack clamps regardless.
     if rect.height() > HEIGHT_LIMIT_MIN {
         render_lines.truncate(overflow::lines_allowed(rect.height(), r.size));
     }
@@ -326,10 +322,10 @@ fn layout_text_quads_inner(
     // single-point anchor, pre-measure) keeps the v1 top placement rather than hoisting text above
     // its anchor.
     //
-    // NO outline pad in the pitch — the byte law (`fontstring-vertical-placement.md`, VERIFIED at
-    // `0x5cdc20`/`0x5cdf70`): the justify block is `h = N·S`, and the `+2r` lives ONLY in the atlas
-    // cell (`[font+0x178]`), which the layout never reads. (The pre-verdict `+2r` here seated every
-    // outlined MIDDLE string r px too high — the money-digit bug.)
+    // NO outline pad in the pitch — the byte law (`0x5cdc20`/`0x5cdf70`): the justify block is
+    // `h = N·S`, and the `+2r` lives ONLY in the atlas cell (`[font+0x178]`), which the layout
+    // never reads. (The earlier `+2r` here seated every outlined MIDDLE string r px too high — the
+    // money-digit bug.)
     let pitch = r.size;
     let block_h = render_lines.len() as f32 * pitch;
     let v_offset = if rect.height() > f32::EPSILON {
@@ -342,10 +338,10 @@ fn layout_text_quads_inner(
         0.0
     };
     // Baseline of the first line: the row the client hangs ink from — the face's pixel ascender
-    // `[CGxFont+0x17c] = round(size · asc/(asc+|desc|))`, threaded unchanged into `glyph_vplace`
-    // 0x5d1360 as the operand that fixes `baseline = cellTop + ascender` (wow-re `system/font`,
-    // §5-verified 2026-07-09). NOT `asc/upem` ≈ 0.965 — that is the FreeType scaled hhea ascender,
-    // which appears nowhere in the placement path; seating with it dropped every line ~3px too low.
+    // `[CGxFont+0x17c] = round(size · asc/(asc+|desc|))`, threaded unchanged into the glyph
+    // placement kernel 0x5d1360 as the operand that fixes `baseline = cellTop + ascender`. NOT
+    // `asc/upem` ≈ 0.965 — that is the FreeType scaled hhea ascender, which appears nowhere in the
+    // placement path; seating with it dropped every line ~3px too low.
     let ascent_ratio = e.ascent_ratio_of(r.face);
     let baseline_in_cell = (f64::from(r.size) * f64::from(ascent_ratio) + 0.5).floor() as f32;
     // The block top takes the client's ONE vertical snap ([`snap_block_top`]) — unless this block
@@ -481,9 +477,9 @@ fn layout_text_quads_inner(
 mod seat_tests {
     use super::*;
 
-    /// The composed MIDDLE seat for one line: block top from box top, per
-    /// `fontstring-vertical-placement.md` — `d = H − round_half_away((H+h)/2)` in the client's
-    /// y-up frame, which [`snap_block_top`] reproduces in y-down over the exact offset.
+    /// The composed MIDDLE seat for one line: block top from box top, per the anchor snap
+    /// `0x5cdf70` — `d = H − round_half_away((H+h)/2)` in the client's y-up frame, which
+    /// [`snap_block_top`] reproduces in y-down over the exact offset.
     fn middle_d(box_h: f32, block_h: f32) -> f32 {
         snap_block_top_law((box_h - block_h) * 0.5)
     }
@@ -618,9 +614,9 @@ mod measure_fits_render {
     /// second line inside the 16-unit row; 1944 then put the reference's own file on the chain and
     /// the cap went live with it. The reading was wrong about our own engine, and this pins why:
     /// the title FontString carries a DECLARED height (`<ButtonText>` `y="10"`), which arms both
-    /// overflow regimes — the ellipsis gate (`boxW > 0 && boxH > 0`, wow-re
-    /// `fontstring-overflow.md`; [`measure::ellipsize_to_fit`]) and the line stack
-    /// ([`overflow::lines_allowed`]) — and each on its own holds the paint to one line. The
+    /// overflow regimes — the ellipsis gate (`boxW > 0 && boxH > 0`, `0x771ec0`;
+    /// [`measure::ellipsize_to_fit`]) and the line stack ([`overflow::lines_allowed`]) — and each
+    /// on its own holds the paint to one line. The
     /// reference does exactly this: its gate holds on the same declared height and its display
     /// string is `prefix + "..."`.
     ///
@@ -912,7 +908,7 @@ mod ellipsis_cost {
     use std::time::Instant;
 
     /// The reported page verbatim — vmangos `page_text` 2676, the *Alliance Military Ranks* plaque
-    /// in Stormwind's Old Town (`GameObject` 3011, the object in Goudy's screenshots). 647 bytes.
+    /// in Stormwind's Old Town (`GameObject` 3011). 647 bytes.
     const PAGE: &str = concat!(
         "<HTML>\n",
         "<BODY>\n",
@@ -938,8 +934,8 @@ mod ellipsis_cost {
     );
 
     /// The longest body vmangos actually ships (`page_text` 2880, a Hearthglen letter, 928 bytes)
-    /// — **plain prose, no markup at all**. It is here because the report's framing ("html text")
-    /// names the loudest case, not the boundary: the seam is armed by OVERFLOW, and the longest
+    /// — **plain prose, no markup at all**. It is here because HTML is the loudest case, not
+    /// the boundary: the seam is armed by OVERFLOW, and the longest
     /// pages in the world are plain. `$b` arrives expanded (`npc_text::substitute`, the feed).
     const PLAIN: &str = concat!(
         "Reuben,\n\nI write this letter knowing you may never see it; I simply can't remain idle, ",
diff --git a/crates/benilla-app/src/ui_text/layout/overflow.rs b/crates/benilla-app/src/ui_text/layout/overflow.rs
index ab00f1e5..7685c72f 100644
--- a/crates/benilla-app/src/ui_text/layout/overflow.rs
+++ b/crates/benilla-app/src/ui_text/layout/overflow.rs
@@ -1,9 +1,8 @@
-//! The overflow law — the pure side of the FontString three-regime overflow verdict
-//! (`system/ui/scratch/fontstring-overflow.md`, decision 0292): the height-limit line stack
-//! (regime 2's vertical half, `CGxString+0x40`) and the height-gated ellipsis-truncate
-//! (regime 3, `CSimpleFontString 0x771ec0`). Pure (no atlas, no shaping) — the parent binds the
-//! row-count closure ([`super::ellipsize_to_fit`]), mirroring how [`super::wrap`] binds its
-//! measure; the tests here run on stub row counts.
+//! The overflow law — the pure side of the FontString's three overflow regimes (decision 0292):
+//! the height-limit line stack (regime 2's vertical half, `CGxString+0x40`) and the height-gated
+//! ellipsis-truncate (regime 3, `CSimpleFontString 0x771ec0`). Pure (no atlas, no shaping) — the
+//! parent binds the row-count closure ([`super::ellipsize_to_fit`]), mirroring how [`super::wrap`]
+//! binds its measure; the tests here run on stub row counts.
 
 /// The client's truncation marker: three ASCII dots (`.rdata 0x800188` = `2e 2e 2e 00`) — never
 /// the single `…` glyph.
@@ -31,8 +30,8 @@ pub(super) fn lines_allowed(box_h: f32, pitch: f32) -> usize {
 /// the one the ellipsis-truncate measures against.
 ///
 /// The truncate loop re-measures each backed-off candidate through
-/// `0x44d960` → **`0x5c21c0` `GxuFont_GetMaxCharsWithinHeight`** (`system/font/scratch/
-/// re-wave1-capi.md` l.53-61), whose per-line test **breaks** when `boxH + 2⁻²⁰ < accumH + lineH`.
+/// `0x44d960` → **`0x5c21c0` `GxuFont_GetMaxCharsWithinHeight`**, whose per-line test **breaks**
+/// when `boxH + 2⁻²⁰ < accumH + lineH`.
 /// A line is therefore admitted only if it lands *wholly within* the box: the largest `n` with
 /// `n·pitch ≤ box_h`. That is a **floor**, where [`lines_allowed`]'s render stack is a **ceil** —
 /// the render emits a line and *then* notices it overran, so it draws one more line than fits
@@ -46,8 +45,7 @@ pub(super) fn lines_allowed(box_h: f32, pitch: f32) -> usize {
 ///
 /// `0` is this floor's honest answer for a box shorter than a single line — but it is NOT what the
 /// ellipsis seam may act on: `0x771ec0` clamps its box height to one line pitch *before* the fit
-/// test (`boxH := max(boxH, lineH+gap)` when maxLines==0 — bytes `0x771f9e..0x771faa`, byte-read
-/// 2026-07-23, recorded in wow-re's `fontstring-overflow.md` "The min-one-line height clamp"), so
+/// test (`boxH := max(boxH, lineH+gap)` when maxLines==0 — bytes `0x771f9e..0x771faa`), so
 /// the sub-one-line call this 0 describes never happens in the client. [`ellipsize_in_box`]
 /// mirrors the clamp. Decision 0597's "0 lines → the loop backs off to the bare ellipsis" reading
 /// missed it and turned every sub-one-line fixed box into three dots — money purses, hotkeys,
diff --git a/crates/benilla-app/src/ui_text/layout/wrap.rs b/crates/benilla-app/src/ui_text/layout/wrap.rs
index f99e26ff..4cbcc8a6 100644
--- a/crates/benilla-app/src/ui_text/layout/wrap.rs
+++ b/crates/benilla-app/src/ui_text/layout/wrap.rs
@@ -2,9 +2,9 @@
 //! tokenization, the greedy packer, and the run re-join. Pure (no atlas, no shaping) — the parent
 //! binds the measure closure ([`super::wrap_line`]); the tests here run on stub measures. Split
 //! out of `layout.rs` when it crossed the size budget (the fade-composite arc). The break law is
-//! the byte-verified regime-2 wrap (`system/ui/scratch/fontstring-overflow.md`): break at the last
-//! opportunity, force-break a no-opportunity overflow at the last fitting glyph — a rendered line
-//! never exceeds the wrap width. Remaining approximation stated on [`super::wrap_line`].
+//! the regime-2 wrap (`0x5c7780`): break at the last opportunity, force-break a no-opportunity
+//! overflow at the last fitting glyph — a rendered line never exceeds the wrap width. Remaining
+//! approximation stated on [`super::wrap_line`].
 
 use crate::ui_text::markup::ColorRun;
 
@@ -143,10 +143,10 @@ pub(super) fn tokenize_words(line: &[ColorRun]) -> Vec<WrapWord> {
 /// A word that exceeds `max_width` alone on its line **force-breaks at the last fitting glyph** —
 /// the client's no-break-opportunity path (`0x5c7780` picks the last opportunity in the line; with
 /// none, `0x5c7623 fcomp / 0x5c762b je` drops the exceeding glyph and ends the line — a rendered
-/// line never exceeds the wrap width; `system/ui/scratch/fontstring-overflow.md` regime 2). When
-/// not even one glyph fits (a sub-glyph-width box), the builder makes no progress and bails —
-/// the client drops the remainder; we mirror it per source line. Unreachable for any shipped box
-/// (all are tens of px wide), kept for loop-termination correctness.
+/// line never exceeds the wrap width). When not even one glyph fits (a sub-glyph-width box), the
+/// builder makes no progress and bails — the client drops the remainder; we mirror it per source
+/// line. Unreachable for any shipped box (all are tens of px wide), kept for loop-termination
+/// correctness.
 pub(super) fn greedy_pack<F: FnMut(&str) -> f32>(
     words: Vec<WrapWord>,
     max_width: f32,
@@ -310,7 +310,7 @@ mod wrap_tests {
     #[test]
     fn overlong_word_force_breaks_at_the_last_fitting_glyph() {
         // A single word wider than the limit force-breaks (the client's no-opportunity path,
-        // fontstring-overflow.md regime 2): each produced line fits the width exactly greedily.
+        // `0x5c7623`): each produced line fits the width exactly greedily.
         let w = words(&[("Supercalifragilistic", WHITE), ("ok", WHITE)]);
         let lines = greedy_pack(w, 8.0, char_measure);
         assert_eq!(lines.len(), 3);
diff --git a/crates/benilla-app/src/ui_text/markup.rs b/crates/benilla-app/src/ui_text/markup.rs
index 8d002d29..fab37b4f 100644
--- a/crates/benilla-app/src/ui_text/markup.rs
+++ b/crates/benilla-app/src/ui_text/markup.rs
@@ -1,5 +1,6 @@
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Markup — ported verbatim from probes/text-glyph/src/markup.rs
+// Markup — ported verbatim from decision 0068's text-glyph probe (`probes/text-glyph`, retired
+// from the tree by 2331; git history keeps it)
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 /// A `|H<link>|h<text>|h` hyperlink a run sits inside: the link payload (`item:2000:0:0:0`,
@@ -40,7 +41,7 @@ pub(super) struct ColorRun {
 ///
 /// **Stated divergence:** the client gates `|n` off for a single-line box (`K & 0x200`, set by
 /// `SetMultiLine`'s single-line leg at `0x77a5e2`) while its *cursor* model parses it regardless —
-/// a disagreement wow-re records as an anomaly, not a design. We have no flags word here and draw
+/// a disagreement that reads as an anomaly, not a design. We have no flags word here and draw
 /// `|n` as a break everywhere; nothing in our FrameXML emits one, and a user cannot type one
 /// (`0x77c200` turns a typed `|` into `||`).
 pub(super) fn parse_markup(input: &str, base_color: [f32; 4]) -> Vec<Vec<ColorRun>> {
@@ -100,9 +101,7 @@ pub(super) fn parse_markup(input: &str, base_color: [f32; 4]) -> Vec<Vec<ColorRu
 }
 
 /// [`parse_markup`] under the FontString **line-count law** — what the client's height kernel
-/// `GxuFont_GetTextBlockHeight 0x5c2070` actually counts (wow-re `system/font/scratch/
-/// re-wave1-capi.md`; the two edge cases spelled out in `system/ui/scratch/
-/// simplehtml-markup-engine.md` §4.4).
+/// `GxuFont_GetTextBlockHeight 0x5c2070` actually counts.
 ///
 /// The kernel walks the string: a bare line break at the cursor is an empty line and costs one;
 /// otherwise it lays a line, and **that line's own terminating break is consumed with it**. So a
@@ -266,7 +265,7 @@ mod markup_tests {
     }
 
     /// There is no inline-texture escape in build 5875 — the remap table at `0x5c2b10` sends every
-    /// `|`-lead but C/H/N/R to the ordinary-character arm (wow-re RF-0087 §1.1). Our renderer used
+    /// `|`-lead but C/H/N/R to the ordinary-character arm. Our renderer used
     /// to strip `|T…|t`, a later-expansion feature we had invented; it now draws, like the client's.
     #[test]
     fn there_is_no_inline_texture_escape() {
@@ -419,7 +418,7 @@ mod markup_tests {
         // The item tooltip's SET spacer, the reference's own literal `0x854b2c`: ONE row
         // carrying one space. Two under a split, and then the blank gold lines above the set
         // bonuses would each be a row taller than 1.12's.
-        assert_eq!(n(" \n"), 1, "the §22 blank gold spacer is one row");
+        assert_eq!(n(" \n"), 1, "the set's blank gold spacer is one row");
         assert_eq!(n(""), 0, "an empty string is zero lines, height 0.0");
         // …and everything else is unchanged.
         assert_eq!(n("a"), 1);
diff --git a/crates/benilla-app/src/ui_text/measurer.rs b/crates/benilla-app/src/ui_text/measurer.rs
index a5803fad..553602ed 100644
--- a/crates/benilla-app/src/ui_text/measurer.rs
+++ b/crates/benilla-app/src/ui_text/measurer.rs
@@ -46,16 +46,16 @@ pub(crate) fn measure_request(
         // frame-local UI units below.
         height: super::drawn_px(r.height, r.text_height, rs),
         // The TRUE outline: THICK biases the client's step law (+1px per glyph — GlyphStepBase
-        // 0x5ca2b0, THICK-only per outline-bake-tint.md), so measure must see it.
+        // 0x5ca2b0, THICK-only), so measure must see it.
         outline: r.outline,
         alpha_gradient: None, // alpha never changes metrics
     };
     let wrap = r.wrap_width.map(|w| w * rs);
     let (w, h) = super::measure_text(e, &r.text, wrap, spec());
     // …and the NATURAL width, which is what `GetStringWidth` answers with (the reference measures
-    // its getter's string with no wrap constraint — wow-re `fontstring-overflow.md`, "The
-    // measurement echo"). A second pass only for the regions that actually carry a declared width;
-    // for the rest the two are one number.
+    // its getter's string with no wrap constraint — the extent measure `0x5c6940`). A second pass
+    // only for the regions that actually carry a declared width; for the rest the two are one
+    // number.
     let natural = if wrap.is_some() {
         super::measure_text(e, &r.text, None, spec()).0
     } else {
diff --git a/crates/benilla-app/src/ui_text/mod.rs b/crates/benilla-app/src/ui_text/mod.rs
index 0d9d0272..cb9d7d49 100644
--- a/crates/benilla-app/src/ui_text/mod.rs
+++ b/crates/benilla-app/src/ui_text/mod.rs
@@ -22,7 +22,7 @@
 //!   replaced and why.
 //! - **Outlines are one composite cell.** An outlined glyph's black ring and its fill are
 //!   rasterized together into a single cell and blitted once — the client's own baked-outline
-//!   architecture (`glyph_blit_aa_outline 0x5cea30`; see [`outline`]), which is what makes an
+//!   architecture (the AA-outline blit `0x5cea30`; see [`outline`]), which is what makes an
 //!   outlined string fade as one thing instead of blackening. The Number* fonts (action-bar
 //!   hotkeys/counts) carry it.
 //! - **`justifyH` and `justifyV` are honored** (see [`layout_text_quads`]): lines justify
@@ -36,11 +36,11 @@
 //!
 //! `cosmic-text`'s shaper is used for glyph SELECTION and rasterization, **one character at a
 //! time** ([`engine::TextEngine::ensure_char`]); the pen then **advances by the client's own step
-//! law** (wow-re `system/font`): per glyph, `floor(advance) + 1` px (`rasterize_glyph` 0x5d1120's
+//! law**: per glyph, `floor(advance) + 1` px (the glyph rasterizer 0x5d1120's
 //! `out[5] = (FT_advance>>6)+1.0`), plus another `+1` for a **THICK**-outlined font only
-//! (`GlyphStepBase` 0x5ca2b0 biases solely under the THICK flag — `outline-bake-tint.md`,
-//! correcting this module's earlier any-outline reading) — the extra tracking that makes real
-//! client text read wider/denser than raw font metrics.
+//! (`GlyphStepBase` 0x5ca2b0 biases solely under the THICK flag — correcting this module's earlier
+//! any-outline reading) — the extra tracking that makes real client text read wider/denser than
+//! raw font metrics.
 //!
 //! Per character is not a shortcut; it is the law. The client's `ComputeStep` (0x5ca2d0) has no
 //! neighbour term, so a string's width is a pure function of its characters — which is what lets
@@ -53,9 +53,9 @@
 //! *negative* pair kerns and rounds — ~0 at UI sizes; the test that pins the width law also pins
 //! that this is what we are doing), and glyph BITMAPS are cosmic/swash unhinted coverage where the
 //! client runs 2004-era FreeType with hinting flags (0x208a/0x20c2) — slightly slimmer stems at
-//! small sizes. A future bit-exact replacement (wow-re's font kernel) only changes this module;
-//! nothing in its callers moves. The deliberate *rendering* divergences — where the client stretches
-//! a cell and we rasterize the true size — are named in [`engine`]'s module doc.
+//! small sizes. A future bit-exact replacement (a port of the client's font kernel) only changes
+//! this module; nothing in its callers moves. The deliberate *rendering* divergences — where the
+//! client stretches a cell and we rasterize the true size — are named in [`engine`]'s module doc.
 
 mod engine;
 mod layout;
@@ -80,8 +80,8 @@ pub(crate) use layout::{
 /// pre-font-object behavior; a font object supplies a per-`FontString` height instead.
 const DEFAULT_FONT_SIZE: f32 = 12.0;
 
-/// The FontString **one-to-one raster cap** (wow-re `system/ui/scratch/fontstring-overflow.md`,
-/// §5 pair + byte arbitration, VERIFIED): every `CSimpleFontString` ships with the one-to-one bit
+/// The FontString **one-to-one raster cap**:
+/// every `CSimpleFontString` ships with the one-to-one bit
 /// set (`+0x120` bit `0x200`, ctor `0x770d30` default `0x212`; the sole clearer is `SetTextHeight`
 /// `0x771600`, which nothing we ship calls), so the size every build/measure actually uses is the
 /// getter `0x7727b0(1)`'s return — the font's RASTERIZED pixel size drawn 1:1, not the requested
@@ -110,10 +110,10 @@ pub(crate) fn fontstring_em(height: Option<f32>) -> Option<f32> {
     height.map(|h| h.min(FONTSTRING_EM_CAP))
 }
 
-/// The DRAWN pixel height of a UI FontString under the client's two size regimes (§5-verified,
-/// wow-re `fontstring-overflow.md` + `font-size-to-freetype-em.md`), times the seam scale
-/// `s = windowH/768 × uiScale` (decisions 0582 + 0584, `crate::ui_script::seam_scale`; `s = 1`
-/// at the design height with the dial at 1, where this is byte-identical to the pre-scaling law):
+/// The DRAWN pixel height of a UI FontString under the client's two size regimes (the size getter
+/// `0x7727b0`), times the seam scale `s = windowH/768 × uiScale` (decisions 0582 + 0584,
+/// `crate::ui_script::seam_scale`; `s = 1` at the design height with the dial at 1, where this is
+/// byte-identical to the pre-scaling law):
 ///
 /// - **one-to-one** (the ctor default, everything but SetTextHeight): the raster size — the
 ///   [`FONTSTRING_EM_CAP`] applied in UNITS (the recorded divergence above: the client caps in
@@ -149,7 +149,7 @@ mod cap_tests {
     }
 }
 // NOTE on line pitch: there is deliberately NO line-height factor. The client's line-step law
-// (`LayoutLines` 0x5cdc20, wow-re `system/font`) is `lineStep = px(size) + spacing`, where
+// (`LayoutLines` 0x5cdc20) is `lineStep = px(size) + spacing`, where
 // `spacing` is the FontString's own extra line gap (XML `spacing`, default **0** — none of our
 // shipped UI sets one), so the pitch IS the font height. The earlier `1.25` factor here was
 // cosmic-text's convention, not the client's, and read as "line height too large" against the
@@ -159,13 +159,12 @@ mod cap_tests {
 /// The FontString **display string** — the ellipsis seam's answer, remembered per region.
 ///
 /// The real client does not recompute this per frame, and the reason it can afford the back-off's
-/// shape is that it almost never runs (wow-re `system/ui/scratch/fontstring-ellipsis-cost.md`, §5
-/// trio + byte arbitration): `0x771ec0`'s result is built into the `CGxString` at `+0xf8` and
-/// rebuilt only when the rebuild guard `[fontstring+0x60] & 1` is cleared — by `SetFont`
+/// shape is that it almost never runs: `0x771ec0`'s result is built into the `CGxString` at `+0xf8`
+/// and rebuilt only when the rebuild guard `[fontstring+0x60] & 1` is cleared — by `SetFont`
 /// (`0x7715e0`), `SetTextHeight` (`0x771666`), `SetText` (`0x771ea4`), or a resolved-rect **size**
 /// change (`0x768d20`, which fires nothing when all four edges move less than `1e-5`). Nothing on
-/// the draw path can reach it at all: the note's dword scan of every PE section finds `0x771ec0`
-/// and `0x7724a0` in no vtable, table or pointer cell, so the complete caller set is their direct
+/// the draw path can reach it at all: a dword scan of every PE section finds `0x771ec0` and
+/// `0x7724a0` in no vtable, table or pointer cell, so the complete caller set is their direct
 /// `call` sites — none of them per-frame. **A pure move, a same-text `SetText`, and any no-op
 /// setter cost zero.**
 ///
@@ -257,10 +256,10 @@ impl EllipsisMemo {
     }
 }
 
-/// [`EllipsisMemo`]'s invalidation set — the client's own (`fontstring-ellipsis-cost.md` §6:
-/// `SetFont`, `SetTextHeight`, `SetText`, and a resolved-rect SIZE change past `1e-5`), expressed
-/// as an input comparison. A memo that misses is merely slow; one that HITS when an input moved
-/// draws a stale string, so each input gets its own test.
+/// [`EllipsisMemo`]'s invalidation set — the client's own (what rebuilds `0x7724a0`: `SetFont`,
+/// `SetTextHeight`, `SetText`, and a resolved-rect SIZE change past `1e-5`), expressed as an input
+/// comparison. A memo that misses is merely slow; one that HITS when an input moved draws a stale
+/// string, so each input gets its own test.
 #[cfg(test)]
 mod ellipsis_memo_tests {
     use super::*;
diff --git a/crates/benilla-app/src/ui_text/outline.rs b/crates/benilla-app/src/ui_text/outline.rs
index d6f0aaa7..3c1572d1 100644
--- a/crates/benilla-app/src/ui_text/outline.rs
+++ b/crates/benilla-app/src/ui_text/outline.rs
@@ -2,7 +2,7 @@
 //!
 //! An outlined font (`outline="NORMAL"/"THICK"`, the Number* fonts) does not draw a ring and a fill
 //! as two things. The real client composites both into **one** atlas cell and blits it once
-//! (`glyph_blit_aa_outline 0x5cea30`, dispatched by `0x5cf310` off the font flags at
+//! (the AA-outline blit `0x5cea30`, dispatched by `0x5cf310` off the font flags at
 //! `[CGxFont+0x180]`), which is what makes an outlined string fade correctly: one quad, one alpha,
 //! ring and fill thinning together. Stamping a ring behind a fill instead — which this codebase did
 //! before the composite cell — blackens mid-fade on the `α(1−α)` compositing term.
@@ -23,15 +23,13 @@ pub(super) fn radius_of(outline: benilla_ui::script::Outline) -> u8 {
     }
 }
 
-/// The client's AA neighbour-count → outline-alpha LUT (`DAT_0080a8ec`, wow-re
-/// `system/font/scratch/outline-bake-tint.md`, §5 double-pair + difftests, commit `f80ce699`):
-/// index = the number of marked cells in the in-bounds 3×3 box (centre included), value = the
-/// 4-bit alpha, here pre-widened to 8-bit (`nibble × 17`).
+/// The client's AA neighbour-count → outline-alpha LUT (`DAT_0080a8ec`): index = the number of
+/// marked cells in the in-bounds 3×3 box (centre included), value = the 4-bit alpha, here
+/// pre-widened to 8-bit (`nibble × 17`).
 const AA_NEIGHBOUR_LUT: [u8; 10] = [0, 17, 17, 51, 85, 119, 153, 187, 221, 255];
 
 /// Composite one glyph's coverage bitmap into an **outlined cell** — the byte recipe of the
-/// client's AA-outline blit (`glyph_blit_aa_outline 0x5cea30`, dispatched by `0x5cf310`; wow-re
-/// `outline-bake-tint.md`, difftested emulation `wow-5875-re/crates/font/src/raster.rs`):
+/// client's AA-outline blit (`0x5cea30`, dispatched by `0x5cf310`):
 ///
 /// 1. **Mark** every texel with non-zero coverage.
 /// 2. **Dilate** iteratively — each pass marks every virgin texel 8-adjacent to a marked one.
@@ -46,9 +44,9 @@ const AA_NEIGHBOUR_LUT: [u8; 10] = [0, 17, 17, 51, 85, 119, 153, 187, 221, 255];
 ///    white-with-thin-alpha) at the LUT alpha. The binary quantizes to ARGB4444; we keep 8-bit
 ///    (same law, no banding — the one deliberate widening, like the LUT `×17`).
 ///
-/// Draw-side law this feeds (same note, prongs 2–3): one quad per glyph, vertex color MODULATE —
-/// white fill takes the text tint, black ring stays black — and ONE alpha per pass, so a frame fade
-/// thins ring+fill together (no `α(1−α)` blackening, the defect the stamped halos had).
+/// Draw-side law this feeds: one quad per glyph (the quad builder `0x5ccbe0`), vertex color
+/// MODULATE — white fill takes the text tint, black ring stays black — and ONE alpha per pass, so a
+/// frame fade thins ring+fill together (no `α(1−α)` blackening, the defect the stamped halos had).
 ///
 /// Returns `(rgba, out_w, out_h, pad)`: the cell grows by `pad = r·round(dpi)` texels each side
 /// (the binary's cell `em+2/+4` and origin col `1/2`, generalized); the caller shifts bearings by
diff --git a/crates/benilla-app/src/ui_tooltip/mod.rs b/crates/benilla-app/src/ui_tooltip/mod.rs
index 797aab59..35d26b5c 100644
--- a/crates/benilla-app/src/ui_tooltip/mod.rs
+++ b/crates/benilla-app/src/ui_tooltip/mod.rs
@@ -20,7 +20,7 @@ use benilla_ui::strings::Arg;
 
 use crate::items::Items;
 use crate::names::NameCache;
-use crate::net::{NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{NetCommands, ObjectStore, Objects, SelfPlayer};
 use crate::target::{
     go_is_nearest, ring_reaction, Hovered, HoveredObject, GO_FLAG_LOCKED, GO_TYPE_GENERIC,
 };
@@ -42,10 +42,10 @@ impl Plugin for UiTooltipPlugin {
 }
 
 /// Everything a view needs beyond the spell catalogs — the player-dependent halves of the line
-/// law: the worn set (law §3.6's equipped-item test), the bags (§3.8's reagent possession, and
+/// law: the worn set (the equipped-item test, `0x5f0c50`), the bags (the reagent possession, and
 /// the item-name cache the reagent names come from), the current form, and the bind point `$z`
 /// substitutes against.
-struct ViewCtx<'a> {
+struct ViewCtx<'a, 'w, 's> {
     home_area: Option<&'a str>,
     form: u8,
     store: Option<&'a ObjectStore>,
@@ -56,12 +56,15 @@ struct ViewCtx<'a> {
     /// arm resolves `[caster+0xc48]` itself, so this cell moves with the mob you are swinging at
     /// and falls back to doubling the caster's own reach when nothing is engaged.
     attack_target_reach: Option<f32>,
+    /// The one object index (2334) — what the possession cells resolve an instance guid
+    /// through: the worn-item line's search and each reagent's carried count.
+    objects: &'a Objects<'w, 's>,
     items: &'a mut Items,
     commands: &'a NetCommands,
     sub_classes: Option<&'a benilla_formats::ItemSubClassCatalog>,
     /// The talent spell-modifier tables — the cost cell shows the RESOLVED cost, which since
-    /// `SPELLMOD_COST` landed means the modified one (`crate::ui_action::usable::power_cost`).
-    spell_mods: &'a crate::spell_mods::SpellModifiers,
+    /// `SPELLMOD_COST` landed means the modified one (`crate::spell::usable::power_cost`).
+    spell_mods: &'a crate::spell::SpellModifiers,
     /// The VM's own `GlobalStrings.lua` (decision 2045) — every cell this builder composes is a
     /// key, and this is where they resolve. `text` is the `%d`-filling twin the `$`-engine's
     /// keyed tokens take (`benilla_formats::TokenContext::text`).
@@ -79,16 +82,17 @@ fn keyed(get: &dyn Fn(&str) -> Option<String>, key: &str, args: &[Arg<'_>]) -> O
 
 /// Build one spell's tooltip view (decision 0274 P2) — the verified spell line law's inputs,
 /// every string resolved here where the catalogs live: the cost cell (the RESOLVED
-/// `power_cost` through the power-type key array, health fallback, `_PER_TIME` composite — law
-/// §3.3, 1074; rage prints wire-cost ÷ 10), the range cell ("N yd range", "N-M yd range" when
+/// `power_cost` through the power-type key array `0x85416c`, health fallback, `_PER_TIME`
+/// composite — 1074; rage prints wire-cost ÷ 10), the range cell ("N yd range", "N-M yd range" when
 /// the resolved min is nonzero — the law's `"%d-%d"` fork; the melee family resolves through the
 /// same key off the caster's combat reach, and the on-next-swing class shows no cell at all), the cast cell
 /// (the full `52eb45` ladder: sec/min, the negative-base sentinel, "Next melee"/"Attack
-/// speed"/"Channeled", and the mana-keyed Instant fork — law §3.4, 1074; None = the law's
+/// speed"/"Channeled", and the mana-keyed Instant fork — 1074; None = the law's
 /// passive gate, which omits the whole line), the cooldown cell
-/// (`max(RecoveryTime, CategoryRecoveryTime)` — law §3.4), the required-item and required-form
-/// lines (law §3.6), the reagents line (law §3.8), and the $-substituted
-/// description/aura-description (byte-exact formulas, `benilla_formats::substitute`).
+/// (`max(RecoveryTime, CategoryRecoveryTime)` at `0x52eada`), the required-item and
+/// required-form lines (`[0x52eea7, 0x52f2ae)`), the reagents line (`SPELL_REAGENTS 0x854e54`),
+/// and the $-substituted description/aura-description (byte-exact formulas,
+/// `benilla_formats::substitute`).
 ///
 /// Line TEXT is composed in English here, as every cell in this builder is; the reference reads
 /// its own GlobalStrings templates ("Reagents: ", "Requires %s"). That is this builder's standing
@@ -108,7 +112,7 @@ fn spell_tooltip_view(
         home_area,
         text: vctx.text,
     };
-    // The cost cell (law §3.3, the `0x52e8ad` caller): the RESOLVED cost — `GetPowerCost`'s
+    // The cost cell (the `0x52e8ad` caller): the RESOLVED cost — `GetPowerCost`'s
     // number, the same `power_cost` the usable walk compares (0948) — through the power-type key
     // array (`0x85416c`: Mana/Rage/Focus/Energy/Happiness) with HEALTH as the out-of-range
     // fallback (the `jl`/`cmp 5` fork at `0x52e8fc` — Life Tap's and Bloodrage's −2 → "N Health";
@@ -121,7 +125,7 @@ fn spell_tooltip_view(
     // HAPPINESS_COST has no GlobalStrings entry and no 5875 player spell reaches powerType 4;
     // the unit word is a dead arm kept for the array's shape.
     let resolved_cost = vctx.store.map_or(d.mana_cost, |s| {
-        crate::ui_action::usable::power_cost(d, s, vctx.spell_mods)
+        crate::spell::usable::power_cost(d, s, vctx.spell_mods)
     });
     let cost = {
         // The one `0x6e7130` table, not a local `if power_type == 1` — decision 2117 found three
@@ -147,9 +151,8 @@ fn spell_tooltip_view(
             Some(format!("{} {unit}", resolved_cost / div))
         }
     };
-    // The range cell (law §3.3 / wow-re `tooltip-globalstring-key-resolves.md` §A3, VERIFIED):
-    // two attribute gates, then `GetMinMaxRange 0x6e3480` with **`target = NULL`** (`0x52e9c2`),
-    // then a third gate on the resolved `max <= 0`.
+    // The range cell: two attribute gates, then `GetMinMaxRange 0x6e3480` with **`target = NULL`**
+    // (`0x52e9c2`), then a third gate on the resolved `max <= 0`.
     //
     // **There is no melee wording anywhere in the client** — `SPELL_RANGE_AREA` is not in
     // `WoW.exe` at all, and the melee family is not a display name either: a melee spell is one
@@ -187,7 +190,7 @@ fn spell_tooltip_view(
             keyed(vctx.get, "SPELL_RANGE", &[Arg::S(&yards)])
         })
         .flatten();
-    // Law §3.4's own gate — wider than the spellbook's `passive`: a TRADE_SKILL or ATTACK
+    // The cast line gate `0x52eb15` — wider than the spellbook's `passive`: a TRADE_SKILL or ATTACK
     // Effect[0] omits the line too ([`SpellDisplay::tooltip_omits_cast_line`]). The arm order is
     // the byte ladder `0x52eb45-0x52ec90` (1074): a positive time prints sec/min at the 60 s
     // threshold; a NEGATIVE SpellCastTimes base is the "Instant cast" sentinel (`52ebce`); at
@@ -232,7 +235,7 @@ fn spell_tooltip_view(
             keyed(vctx.get, key, &[])
         }
     };
-    // The cooldown cell reads BOTH recovery columns (law §3.4: `max([+0x4c],[+0x50])>0` —
+    // The cooldown cell reads BOTH recovery columns (`max([+0x4c],[+0x50])>0` at `0x52eada` —
     // Charge's 15 s is CategoryRecoveryTime; its RecoveryTime is 0).
     let recovery_ms = d.recovery_ms.max(d.category_recovery_ms);
     let cooldown = (recovery_ms > 0)
@@ -246,7 +249,7 @@ fn spell_tooltip_view(
             keyed(vctx.get, key, &[Arg::F(v)])
         })
         .flatten();
-    // The required-form line (law §3.6): the Stances mask's form names off
+    // The required-form line: the Stances mask's form names off
     // SpellShapeshiftForm.dbc, joined; bit b = form id b+1. Met against the CURRENT form.
     //
     // `Stances != 0` is NOT the gate on its own — the column is overloaded. When `AttributesEx2`
@@ -255,10 +258,10 @@ fn spell_tooltip_view(
     // Moonkin-castable balance spells; reading those as requirements put a red "Requires
     // Shadowform" on Inner Fire and "Requires Spirit of Redemption" on Flash Heal (1483).
     //
-    // Now byte-carved as wow-re §3-REQFORM, `[0x52f10a, 0x52f2ae)`: `52f115` reads AttributesEx2,
+    // The block is `[0x52f10a, 0x52f2ae)`: `52f115` reads AttributesEx2,
     // ands `0x80000`, and jumps *over the whole name loop* — the loop is the only writer of the
     // "nothing appended" flag `[ebp-8]`, so the AddLine is skipped entirely. The line is
-    // **suppressed, not recoloured**. Three earned negatives came with it: StancesNot `+0x30` is
+    // **suppressed, not recoloured**. Three earned negatives: StancesNot `+0x30` is
     // never read here, `Attributes` bit 16 is never tested, and `0x612480` is never called — the
     // builder duplicates the gate inline rather than sharing the usable walk's helper, which is
     // why the two could drift apart in the first place.
@@ -285,12 +288,12 @@ fn spell_tooltip_view(
         })
         .flatten();
     let form_met = form != 0 && d.stances & (1u32 << (u32::from(form) - 1)) != 0;
-    // The equipped-item-class half of law §3.6 — "Requires Wands" on the wand Shoot, and "Requires
-    // Melee Weapon" on Parry. A mask with several bits set is NOT a reason to print nothing (what we
-    // used to do): the reference names the whole mask through ItemSubClassMask.dbc first, and only
-    // falls back to comma-joining the individual subclasses. Law §3-EQUIPITEM, in the catalog.
-    // §3-EQUIPITEM's three entry gates, all of which skip the line: Targets bit 0x10 set, class < 0,
-    // or an empty mask.
+    // The equipped-item-class half of the requirement lines, `[0x52eea7, 0x52f10a)` — "Requires
+    // Wands" on the wand Shoot, and "Requires Melee Weapon" on Parry. A mask with several bits set
+    // is NOT a reason to print nothing (what we used to do): the reference names the whole mask
+    // through ItemSubClassMask.dbc first, and only falls back to comma-joining the individual
+    // subclasses; that lookup lives in the catalog. Its three entry gates, all of which skip the
+    // line: Targets bit 0x10 set, class < 0, or an empty mask.
     let requires_item = (d.targets & TARGET_ITEM == 0 && d.equipped_item_class >= 0)
         .then(|| {
             vctx.sub_classes?
@@ -298,17 +301,17 @@ fn spell_tooltip_view(
         })
         .flatten()
         .and_then(|name| keyed(vctx.get, "SPELL_EQUIPPED_ITEM", &[Arg::S(&name)]));
-    // The chance-to-X line (law line 10, §3-CHANCE): `Effect[0]` picks which of the player's four
+    // The chance-to-X line (`[0x52f5b1, 0x52f697)`): `Effect[0]` picks which of the player's four
     // avoidance/crit percentages to print, and — except for ATTACK, which bypasses the gate — the
     // spell must be passive. The percentages are already percents on the wire.
     let chance = chance_line(d, vctx.store);
     let item_met = vctx.store.is_none_or(|s| {
-        crate::ui_action::usable::equipped_item_fits(d, s, vctx.items, vctx.commands)
+        crate::spell::usable::equipped_item_fits(d, s, vctx.objects, vctx.items, vctx.commands)
     });
-    // Reagents (law §3.8): the named slots, `count > 1` suffixed, a slot the player is short of
-    // wrapped in the builder's inline red. A reagent whose item template hasn't streamed yet is
-    // simply absent from this snapshot — `feed_spell_tooltips` re-pushes when it lands, which is
-    // our shape of the ref's own query-then-redisplay callback.
+    // Reagents (`SPELL_REAGENTS 0x854e54`): the named slots, `count > 1` suffixed, a slot the
+    // player is short of wrapped in the builder's inline red. A reagent whose item template hasn't
+    // streamed yet is simply absent from this snapshot — `feed_spell_tooltips` re-pushes when it
+    // lands, which is our shape of the ref's own query-then-redisplay callback.
     let reagents = {
         let mut parts: Vec<String> = Vec::new();
         for (entry, count) in d.reagents.iter().copied().filter(|&(e, _)| e != 0) {
@@ -325,7 +328,7 @@ fn spell_tooltip_view(
                 name
             };
             let short = vctx.store.is_some_and(|s| {
-                count_of(&s.0, vctx.items, entry, InventoryScope::CARRIED) < count
+                count_of(&s.0, vctx.objects, entry, InventoryScope::CARRIED) < count
             });
             parts.push(if short {
                 format!("|cffff2020{text}|r")
@@ -338,7 +341,7 @@ fn spell_tooltip_view(
     Some(benilla_ui::script::SpellTooltipView {
         name: d.name.clone(),
         rank: d.rank.clone(),
-        // The aura variant's right column (law §3-BUFF) — gated inside the catalog by
+        // The aura variant's right column (`[0x52f8e5, 0x52f911)`) — gated inside the catalog by
         // SpellDispelType.dbc's own `[+0x28]`, so Stealth-class auras hand back None.
         dispel_type: spells.catalog.dispel_name(d).map(str::to_string),
         cost,
@@ -365,18 +368,17 @@ fn spell_tooltip_view(
 }
 
 /// `Targets` bit `0x10` — set ⇒ the equipped-item requirement line is skipped whatever the class
-/// and mask say (§3-EQUIPITEM's first gate; the bit test is verified, the `TARGET_FLAG_ITEM` name
-/// wow-re flags as inferred).
+/// and mask say (the line's first gate, `0x52eeaa`; the `TARGET_FLAG_ITEM` name is inferred).
 const TARGET_ITEM: u32 = 0x10;
 
 /// `SPELL_EFFECT_DODGE` / `_PARRY` / `_BLOCK` / `_ATTACK` — the four `Effect[0]` values that select
-/// a chance-to-X line (law §3-CHANCE's jump table).
+/// a chance-to-X line (the jump table `0x52f7c4`).
 const EFFECT_DODGE: u32 = 20;
 const EFFECT_PARRY: u32 = 22;
 const EFFECT_BLOCK: u32 = 23;
 const EFFECT_ATTACK: u32 = 78;
 
-/// The chance-to-X line (law line 10 / §3-CHANCE) — `None` when the spell names none of the four
+/// The chance-to-X line (`[0x52f5b1, 0x52f697)`) — `None` when the spell names none of the four
 /// effects, when the gate rejects it, or before the player's descriptor has streamed.
 ///
 /// The predicate is the reference's, and its asymmetry is the point: **ATTACK bypasses the passive
@@ -403,19 +405,20 @@ struct SpellFeedMemory {
     pushed: std::collections::HashSet<u32>,
     /// The bind point `$z` substitutes against.
     home: Option<String>,
-    /// The current shapeshift form (law §3.6's stance line, white/red).
+    /// The current shapeshift form (the required-form line's white/red, `0x52f1e3`).
     form: Option<u8>,
-    /// The 19 worn-slot guids (law §3.6's item line, white/red).
+    /// The 19 worn-slot guids (the equipped-item line's white/red, `0x5f0c50`).
     worn: Option<[u64; 19]>,
     /// The player's block/dodge/parry/crit percentages, as raw bit patterns so the diff needs no
-    /// float comparison (law line 10's printed value — it moves with gear, buffs and talents).
+    /// float comparison (the chance-to-X line's printed value, `0x52f5b1` — it moves with gear,
+    /// buffs and talents).
     avoidance: Option<[u32; 4]>,
     /// The two reaches the melee range cell reads, as raw bit patterns — the caster's own
     /// (which moves with scale and shapeshift) and its auto-attack target's (which changes with
     /// the mob).
     combat_reach: Option<(Option<u32>, Option<u32>)>,
-    /// Per reagent entry currently on show: `(owned count, item name resolved)` — law §3.8's
-    /// inline red plus the ask-once template landing.
+    /// Per reagent entry currently on show: `(owned count, item name resolved)` — the reagent
+    /// line's inline red (`0x854120`) plus the ask-once template landing.
     reagents: std::collections::BTreeMap<u32, (u32, bool)>,
 }
 
@@ -435,7 +438,9 @@ fn feed_spell_tooltips(
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
     // Who the player is auto-attacking, if anyone — the melee range cell's second reach.
     engaged_q: Query<&crate::creature_anim::Engaged, With<SelfPlayer>>,
-    guids: Res<crate::net::GuidIndex>,
+    // The object lookup (2334) — the guid index the engaged-target reach resolves through,
+    // plus the bag walk each watched reagent's carried count takes.
+    objects: Objects,
     home_bind: Option<Res<crate::net::HomeBind>>,
     area_names: Option<Res<crate::ui_quest_log::QuestHeaderNamesRes>>,
     mut items: ResMut<Items>,
@@ -444,7 +449,7 @@ fn feed_spell_tooltips(
     // spell-modifier tables the cost cell resolves through.
     lookups: (
         Option<Res<crate::ui_items::ItemSubClasses>>,
-        Res<crate::spell_mods::SpellModifiers>,
+        Res<crate::spell::SpellModifiers>,
     ),
     commands: Res<NetCommands>,
     mut memory: Local<crate::ui_script::VmMemo<SpellFeedMemory>>,
@@ -523,7 +528,7 @@ fn feed_spell_tooltips(
         wanted.extend(memory.pushed.drain());
     }
     // A stance/form change re-pushes too: the required-form line's white/red tracks the CURRENT
-    // form (law §3.6), and the views are static snapshots until re-pushed.
+    // form (`0x52f1e3`), and the views are static snapshots until re-pushed.
     let form = self_q
         .single()
         .map(|s| s.0.unit_shapeshift_form())
@@ -534,8 +539,8 @@ fn feed_spell_tooltips(
     }
     let self_store = self_q.single().ok();
     // …and so do the two BAG-dependent halves, which the views likewise snapshot: the worn set
-    // (law §3.6's item line flips white/red on a weapon swap) and the owned counts of the
-    // reagents currently on show (law §3.8's inline red, plus the item names themselves landing
+    // (the item line, `0x5f0c50`, flips white/red on a weapon swap) and the owned counts of the
+    // reagents currently on show (the inline red `0x854120`, plus the item names themselves landing
     // from the ask-once template cache — the ref's query-then-redisplay callback in our shape).
     // Both signatures are tiny: 19 slot guids, and one count per DISTINCT reagent in play.
     let worn =
@@ -544,7 +549,7 @@ fn feed_spell_tooltips(
         memory.worn = worn;
         wanted.extend(memory.pushed.drain());
     }
-    // …and so does the chance-to-X line's percentage (law line 10), which the views snapshot the
+    // …and so does the chance-to-X line's percentage (`0x52f5b1`), which the views snapshot the
     // same way: a weapon swap, a buff or a talent moves it.
     let avoidance = self_store.map(|s| {
         [
@@ -564,9 +569,8 @@ fn feed_spell_tooltips(
     let attack_target_reach = engaged_q
         .single()
         .ok()
-        .and_then(|e| guids.0.get(&e.0))
-        .and_then(|&e| stores.get(e).ok())
-        .map(|s| s.0.unit_combat_reach());
+        .and_then(|e| objects.object(e.0))
+        .map(|f| f.unit_combat_reach());
     let reaches = (
         self_store.map(|s| s.0.unit_combat_reach().to_bits()),
         attack_target_reach.map(f32::to_bits),
@@ -589,7 +593,7 @@ fn feed_spell_tooltips(
         .map(|entry| {
             let named = items.template(entry, 0, &commands).is_some();
             let owned = self_store.map_or(0, |s| {
-                count_of(&s.0, &items, entry, InventoryScope::CARRIED)
+                count_of(&s.0, &objects, entry, InventoryScope::CARRIED)
             });
             (entry, (owned, named))
         })
@@ -611,6 +615,7 @@ fn feed_spell_tooltips(
             store: self_store,
             combat_reach: self_store.map_or(1.5, |s| s.0.unit_combat_reach()),
             attack_target_reach,
+            objects: &objects,
             items: &mut items,
             commands: &commands,
             sub_classes: sub_classes.as_deref().map(|c| &c.0),
@@ -629,7 +634,7 @@ fn feed_spell_tooltips(
                         {
                             let named = vctx.items.template(entry, 0, vctx.commands).is_some();
                             let owned = vctx.store.map_or(0, |s| {
-                                count_of(&s.0, vctx.items, entry, InventoryScope::CARRIED)
+                                count_of(&s.0, vctx.objects, entry, InventoryScope::CARRIED)
                             });
                             slot.insert((owned, named));
                         }
@@ -755,7 +760,9 @@ fn drive_mouseover_tooltip(
     // The hovered UNIT's snapshot (a hovered non-unit resolves no store here).
     let unit = hovered.target.zip(hovered.guid).and_then(|(entity, guid)| {
         let store = stores.get(entity).ok()?;
-        let name = names.resolve(guid, &commands).map(str::to_string);
+        let name = names
+            .resolve_unit(guid, Some(store), &commands)
+            .map(str::to_string);
         let reaction = ring_reaction(
             rx.factions.as_deref(),
             &rx.reputations,
@@ -774,8 +781,8 @@ fn drive_mouseover_tooltip(
         Some((guid, s))
     });
     // The hovered GAMEOBJECT, when it is the nearer pick (the click router's own arbitration).
-    // Deliberately NOT gated on the highlightable predicate — §5-VERIFIED (wow-re 2026-07-20,
-    // 0558/0559): the mouseover publisher `0x492890` dispatches the GO tooltip builder `0x52aa20`
+    // Deliberately NOT gated on the highlightable predicate (0558/0559): the mouseover publisher
+    // `0x492890` dispatches the GO tooltip builder `0x52aa20`
     // by object KIND on both branches; highlightable is never read on the tooltip path (it gates
     // the cursor and the click only). So a GENERIC(5) signpost, a pre-quest INTERACT_COND chest,
     // and an IN_USE object all show the gold name plate while showing NO interact cursor — 0466's
@@ -805,9 +812,8 @@ fn drive_mouseover_tooltip(
         }
         return;
     }
-    // The **corpse plate** — "Corpse of <owner>" (the reference's own builder `0x52aef0`, wow-re
-    // `corpse-click-and-reclaim.md` Q6, §5 cross-checked). Ahead of the GameObject arm because the
-    // corpse is the nearer pick whenever `go` came back empty.
+    // The **corpse plate** — "Corpse of <owner>" (the reference's own builder `0x52aef0`). Ahead
+    // of the GameObject arm because the corpse is the nearer pick whenever `go` came back empty.
     //
     // It is a *name plate and nothing else*: no health bar, no reaction recolour, no level or
     // creature-type line — a corpse is not a unit, and the publisher deliberately fires **no
@@ -989,7 +995,7 @@ fn drive_mouseover_tooltip(
                     go_inputs.spells.as_deref(),
                     go_inputs.skill_lines.as_ref().map(|s| &s.catalog),
                     self_store,
-                    &go_inputs.items,
+                    &go_inputs.objects,
                     facts,
                     &mut matched,
                 )
@@ -1007,7 +1013,7 @@ fn drive_mouseover_tooltip(
                     if let Some(t) = go_inputs.items.template(slot0.index, 0, &commands) {
                         // `LOCKED_WITH_ITEM`, resolved at `0x52acb8` — one of eleven 1.12 keys
                         // whose enUS value is exactly "Requires %s", and the only one this arm
-                        // reaches (wow-re `tooltip-globalstring-key-resolves.md` §B).
+                        // reaches.
                         if let Some(text) = keyed(&go_get, "LOCKED_WITH_ITEM", &[Arg::S(&t.name)]) {
                             lines.push((text, TooltipTint::White));
                         }
diff --git a/crates/benilla-app/src/ui_tooltip/tests.rs b/crates/benilla-app/src/ui_tooltip/tests.rs
index d19a2e01..e19e81de 100644
--- a/crates/benilla-app/src/ui_tooltip/tests.rs
+++ b/crates/benilla-app/src/ui_tooltip/tests.rs
@@ -21,7 +21,7 @@ struct TestCtx {
     text: Box<Filler>,
     /// Empty tables, which is the un-talented character every cell here is graded as: the cost
     /// cell's modifier hop must be the identity when nothing has been sent.
-    spell_mods: crate::spell_mods::SpellModifiers,
+    spell_mods: crate::spell::SpellModifiers,
 }
 
 /// The two lookup shapes, named so the harness's fields read.
@@ -39,7 +39,7 @@ impl TestCtx {
             commands: NetCommands(tx),
             _rx: rx,
             get: Box::new(move |key| benilla_ui::strings::global(for_get.lua(), key)),
-            spell_mods: crate::spell_mods::SpellModifiers::default(),
+            spell_mods: crate::spell::SpellModifiers::default(),
             text: Box::new(move |key, args: &[i64]| {
                 let template = benilla_ui::strings::global(for_text.lua(), key)?;
                 let args: Vec<_> = args
@@ -51,33 +51,36 @@ impl TestCtx {
         }
     }
 
-    fn ctx<'a>(
+    fn ctx<'a, 'w, 's>(
         &'a mut self,
+        objects: &'a Objects<'w, 's>,
         form: u8,
         sub_classes: Option<&'a benilla_formats::ItemSubClassCatalog>,
-    ) -> ViewCtx<'a> {
-        self.ctx_for(form, sub_classes, None)
+    ) -> ViewCtx<'a, 'w, 's> {
+        self.ctx_for(objects, form, sub_classes, None)
     }
 
     /// The same context with an auto-attack target engaged — the melee range arm's second
     /// reach, which `0x6e3480` resolves out of `[caster+0xc48]` rather than taking as an
     /// argument.
-    fn ctx_engaged<'a>(
+    fn ctx_engaged<'a, 'w, 's>(
         &'a mut self,
+        objects: &'a Objects<'w, 's>,
         store: Option<&'a ObjectStore>,
         target_reach: f32,
-    ) -> ViewCtx<'a> {
-        let mut ctx = self.ctx_for(0, None, store);
+    ) -> ViewCtx<'a, 'w, 's> {
+        let mut ctx = self.ctx_for(objects, 0, None, store);
         ctx.attack_target_reach = Some(target_reach);
         ctx
     }
 
-    fn ctx_for<'a>(
+    fn ctx_for<'a, 'w, 's>(
         &'a mut self,
+        objects: &'a Objects<'w, 's>,
         form: u8,
         sub_classes: Option<&'a benilla_formats::ItemSubClassCatalog>,
         store: Option<&'a ObjectStore>,
-    ) -> ViewCtx<'a> {
+    ) -> ViewCtx<'a, 'w, 's> {
         ViewCtx {
             home_area: None,
             form,
@@ -86,6 +89,7 @@ impl TestCtx {
             // The tests drive the melee arm through `combat_reach` alone; the engaged-target
             // reach has its own case in `range_cell_on_real_data`.
             attack_target_reach: None,
+            objects,
             items: &mut self.items,
             commands: &self.commands,
             sub_classes,
@@ -96,6 +100,14 @@ impl TestCtx {
     }
 }
 
+/// The object index the possession cells resolve through — nothing streamed, which is what
+/// every case here is graded against: the worn-item search finds no instance and each reagent's
+/// carried count reads 0 (decision 2334). Held beside the [`TestCtx`] because the lookup borrows
+/// the world it reads.
+fn no_objects() -> crate::ui_items::TestObjects {
+    crate::ui_items::TestObjects::new()
+}
+
 /// A player descriptor with nothing worn and nothing in the bags — the "owns none of it"
 /// pole of both possession tests.
 fn empty_player() -> ObjectStore {
@@ -120,7 +132,9 @@ fn fireball_view_on_real_data() {
         radii: benilla_formats::load_spell_radii(&mut chain).expect("SpellRadius.dbc"),
     };
     let mut t = TestCtx::new();
-    let v = spell_tooltip_view(133, &spells, &mut t.ctx(0, None)).expect("Fireball view");
+    let mut objs = no_objects();
+    let objects = objs.get();
+    let v = spell_tooltip_view(133, &spells, &mut t.ctx(&objects, 0, None)).expect("Fireball view");
     assert_eq!(v.name, "Fireball");
     assert_eq!(v.rank.as_deref(), Some("Rank 1"));
     assert_eq!(v.cost.as_deref(), Some("30 Mana"));
@@ -150,7 +164,7 @@ fn fireball_view_on_real_data() {
     // Charge rank 1 (100) — the director's reference shot, end to end: the dual-bound range
     // row (SpellRange 95 = {8, 25}), the CATEGORY-column cooldown (recoveryTime 0 /
     // categoryRecoveryTime 15000), and the Stances-mask form line (0x10000 → form 17).
-    let v = spell_tooltip_view(100, &spells, &mut t.ctx(0, None)).expect("Charge view");
+    let v = spell_tooltip_view(100, &spells, &mut t.ctx(&objects, 0, None)).expect("Charge view");
     assert_eq!(v.name, "Charge");
     assert_eq!(v.rank.as_deref(), Some("Rank 1"));
     assert_eq!(v.cost, None, "Charge costs nothing (it generates rage)");
@@ -163,7 +177,7 @@ fn fireball_view_on_real_data() {
         v.description,
         "Charge an enemy, generate 9 rage, and stun it for 1 sec.  Cannot be used in combat."
     );
-    let v = spell_tooltip_view(100, &spells, &mut t.ctx(17, None)).expect("Charge view");
+    let v = spell_tooltip_view(100, &spells, &mut t.ctx(&objects, 17, None)).expect("Charge view");
     assert!(v.form_met, "form 17 = Battle Stance satisfies the mask");
 
     // 1483 — a PERMISSIVE Stances mask prints no line at all. 5875 overloads the column: with
@@ -183,7 +197,7 @@ fn fireball_view_on_real_data() {
             d.form_mask_is_permissive(),
             "{name} carries AttributesEx2 b19"
         );
-        let v = spell_tooltip_view(id, &spells, &mut t.ctx(0, None)).expect(name);
+        let v = spell_tooltip_view(id, &spells, &mut t.ctx(&objects, 0, None)).expect(name);
         assert_eq!(v.requires_form, None, "{name} demands no form");
     }
 }
@@ -207,6 +221,8 @@ fn cost_and_cast_cells_on_real_data() {
         radii: benilla_formats::load_spell_radii(&mut chain).expect("SpellRadius.dbc"),
     };
     let mut t = TestCtx::new();
+    let mut objs = no_objects();
+    let objects = objs.get();
     // A level-60 warrior-shaped store: max health 4000, base mana 1000 (field indices are
     // the protocol crate's: health 22, maxhealth 28, level 34, base mana 162).
     let store = ObjectStore(benilla_protocol::ObjectFields::from_pairs(&[
@@ -219,15 +235,23 @@ fn cost_and_cast_cells_on_real_data() {
     // Bloodrage (2687): pct-ONLY health cost — 20% of MAX health resolves to a flat number
     // through the health fallback; never a percentage line. Instant on a non-mana type reads
     // bare "Instant" whatever it costs.
-    let v = spell_tooltip_view(2687, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Bloodrage view");
+    let v = spell_tooltip_view(
+        2687,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Bloodrage view");
     assert_eq!(v.cost.as_deref(), Some("800 Health"), "20% of 4000");
     assert_eq!(v.cast_time.as_deref(), Some("Instant"));
 
     // Life Tap (1454): the 5875 file carries NO cost columns for any rank — the cell is
     // empty, exactly the reference render (the printed health cost is 2.x's change).
-    let v = spell_tooltip_view(1454, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Life Tap view");
+    let v = spell_tooltip_view(
+        1454,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Life Tap view");
     assert_eq!(v.cost, None, "1.12 Life Tap has no cost cell");
     assert_eq!(
         v.cast_time.as_deref(),
@@ -237,50 +261,71 @@ fn cost_and_cast_cells_on_real_data() {
 
     // Health Funnel (755): the `_PER_TIME` composite in the health lane, and the channeled
     // cast cell.
-    let v = spell_tooltip_view(755, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Health Funnel view");
+    let v = spell_tooltip_view(
+        755,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Health Funnel view");
     assert_eq!(v.cost.as_deref(), Some("11 Health, plus 5 per sec"));
     assert_eq!(v.cast_time.as_deref(), Some("Channeled"));
 
     // Judgement (20271): pct-of-base-mana resolves to its flat number — the line B152
     // reported as "% of base mana" never exists on the reference. DBC-only (no store)
     // degrades to the flat cost: none here.
-    let v = spell_tooltip_view(20271, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Judgement view");
+    let v = spell_tooltip_view(
+        20271,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Judgement view");
     assert_eq!(v.cost.as_deref(), Some("60 Mana"), "6% of base mana 1000");
-    let v = spell_tooltip_view(20271, &spells, &mut t.ctx(0, None)).expect("Judgement view");
+    let v =
+        spell_tooltip_view(20271, &spells, &mut t.ctx(&objects, 0, None)).expect("Judgement view");
     assert_eq!(v.cost, None, "a DBC-only view cannot resolve a pct cost");
 
     // Heroic Strike (78): the cost cell keeps its rage (wire 150 ÷ 10) and "Next melee"
     // moves to the CAST cell where the ref's ladder puts it.
-    let v = spell_tooltip_view(78, &spells, &mut t.ctx_for(0, None, Some(&store)))
+    let v = spell_tooltip_view(78, &spells, &mut t.ctx_for(&objects, 0, None, Some(&store)))
         .expect("Heroic Strike view");
     assert_eq!(v.cost.as_deref(), Some("15 Rage"));
     assert_eq!(v.cast_time.as_deref(), Some("Next melee"));
 
     // Throw (2764) and Auto Shot (75): the ranged bit reads "Attack speed" — and for Throw
     // the bit is ALONE (`Attributes & 0x2`, not the auto-repeat or-pair). Melee Attack
-    // (6603) is the §3.4 skip: Effect[0] == ATTACK omits the whole line.
-    let v = spell_tooltip_view(2764, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Throw view");
+    // (6603) is the cast line's skip at `0x52eb3c`: Effect[0] == ATTACK omits the whole line.
+    let v = spell_tooltip_view(
+        2764,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Throw view");
     assert_eq!(v.cast_time.as_deref(), Some("Attack speed"));
-    let v = spell_tooltip_view(75, &spells, &mut t.ctx_for(0, None, Some(&store)))
+    let v = spell_tooltip_view(75, &spells, &mut t.ctx_for(&objects, 0, None, Some(&store)))
         .expect("Auto Shot view");
     assert_eq!(v.cast_time.as_deref(), Some("Attack speed"));
-    let v = spell_tooltip_view(6603, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Attack view");
+    let v = spell_tooltip_view(
+        6603,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Attack view");
     assert_eq!(v.cast_time, None, "ATTACK Effect[0] omits the line");
 
     // Mind Flay (15407): a channeled MANA spell — the cost cell and the channeled cell
     // together.
-    let v = spell_tooltip_view(15407, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Mind Flay view");
+    let v = spell_tooltip_view(
+        15407,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Mind Flay view");
     assert_eq!(v.cost.as_deref(), Some("45 Mana"));
     assert_eq!(v.cast_time.as_deref(), Some("Channeled"));
 }
 
-/// The RANGE cell's whole law on the REAL 5875 data (wow-re `tooltip-globalstring-key-resolves.md`
-/// §A3): the melee family renders through `SPELL_RANGE` off the caster's own combat reach — the
+/// The RANGE cell's whole law (`[0x52e9a2, 0x52ea8c)`) on the REAL 5875 data: the melee family
+/// renders through `SPELL_RANGE` off the caster's own combat reach — the
 /// invented "Melee Range" decision 2080 named is gone — the authored rows print their own numbers
 /// through the same key, and the on-next-swing class and the self-only rows print no cell at all.
 /// Skips without client data.
@@ -297,6 +342,8 @@ fn range_cell_on_real_data() {
         radii: benilla_formats::load_spell_radii(&mut chain).expect("SpellRadius.dbc"),
     };
     let mut t = TestCtx::new();
+    let mut objs = no_objects();
+    let objects = objs.get();
     // A default-reach player: `UNIT_FIELD_COMBATREACH` (130) unset reads the descriptor's 1.5.
     let store = empty_player();
 
@@ -306,8 +353,12 @@ fn range_cell_on_real_data() {
     let d = spells.catalog.get(1752).expect("Sinister Strike 1752");
     assert_eq!(d.range_index, 2, "the melee row");
     assert!(spells.ranges.get(2).expect("row 2").is_melee());
-    let v = spell_tooltip_view(1752, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Sinister Strike view");
+    let v = spell_tooltip_view(
+        1752,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Sinister Strike view");
     assert_eq!(v.range.as_deref(), Some("5 yd range"));
 
     // …and it MOVES with the caster's reach, which is the whole reason the cell needs a store:
@@ -316,35 +367,47 @@ fn range_cell_on_real_data() {
         130u16,
         4.0f32.to_bits(),
     )]));
-    let v = spell_tooltip_view(1752, &spells, &mut t.ctx_for(0, None, Some(&big)))
+    let v = spell_tooltip_view(1752, &spells, &mut t.ctx_for(&objects, 0, None, Some(&big)))
         .expect("Sinister Strike view");
     assert_eq!(v.range.as_deref(), Some("9 yd range"));
 
     // …and the second reach is the AUTO-ATTACK target's, not the caster's doubled: swinging at
     // a 4.0-reach mob with a default 1.5 body reads 1.5 + 4.0 + 1.3333334 = 6.833 -> 7.
-    let v = spell_tooltip_view(1752, &spells, &mut t.ctx_engaged(Some(&store), 4.0))
-        .expect("Sinister Strike view");
+    let v = spell_tooltip_view(
+        1752,
+        &spells,
+        &mut t.ctx_engaged(&objects, Some(&store), 4.0),
+    )
+    .expect("Sinister Strike view");
     assert_eq!(v.range.as_deref(), Some("7 yd range"));
 
     // An authored single-number row: Fireball's 0–35.
-    let v = spell_tooltip_view(133, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Fireball view");
+    let v = spell_tooltip_view(
+        133,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Fireball view");
     assert_eq!(v.range.as_deref(), Some("35 yd range"));
 
     // An authored PAIR (the `"%d-%d"` nested fill): Charge's 8–25, unpadded — the tooltip's own
     // `GetMinMaxRange` call passes `target = NULL`, so the reach never joins these two.
-    let v =
-        spell_tooltip_view(100, &spells, &mut t.ctx_for(0, None, Some(&big))).expect("Charge view");
+    let v = spell_tooltip_view(100, &spells, &mut t.ctx_for(&objects, 0, None, Some(&big)))
+        .expect("Charge view");
     assert_eq!(v.range.as_deref(), Some("8-25 yd range"));
 
     // The two absences. Heroic Strike (78) carries the on-next-swing pair, which jumps the cell
     // before the resolver runs — it does NOT read "Melee Range", and it does not read 5 yd
     // either. Bloodrage (2687) sits on the self row, whose resolved max is 0.
-    let v = spell_tooltip_view(78, &spells, &mut t.ctx_for(0, None, Some(&store)))
+    let v = spell_tooltip_view(78, &spells, &mut t.ctx_for(&objects, 0, None, Some(&store)))
         .expect("Heroic Strike view");
     assert_eq!(v.range, None, "Attributes & 0x404 → no range cell");
-    let v = spell_tooltip_view(2687, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Bloodrage view");
+    let v = spell_tooltip_view(
+        2687,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Bloodrage view");
     assert_eq!(v.range, None, "the self row resolves max 0");
 }
 
@@ -364,33 +427,44 @@ fn the_pinned_c6_lines_on_real_data() {
     };
     let subs = benilla_formats::load_item_sub_classes(&mut chain).expect("ItemSubClass.dbc");
     let mut t = TestCtx::new();
+    let mut objs = no_objects();
+    let objects = objs.get();
     let store = empty_player();
 
     // 1 · The wand Shoot (5019, class 2 / submask bit 19) — "Requires Wands", red with no
     // wand worn. The same row feeds the cast-fail line's SINGULAR "Wand" (see `cast_fail`).
     assert_eq!(subs.name(2, 19), Some("Wands"), "the verbose plural");
     assert_eq!(subs.display_name(2, 19), Some("Wand"), "the singular");
-    let v = spell_tooltip_view(5019, &spells, &mut t.ctx_for(0, Some(&subs), Some(&store)))
-        .expect("Shoot view");
+    let v = spell_tooltip_view(
+        5019,
+        &spells,
+        &mut t.ctx_for(&objects, 0, Some(&subs), Some(&store)),
+    )
+    .expect("Shoot view");
     assert_eq!(v.requires_item.as_deref(), Some("Requires Wands"));
     assert!(!v.item_met, "nothing worn satisfies class 2 / bit 19 → red");
-    // A multi-bit mask is named by ItemSubClassMask.dbc, not skipped (law §3-EQUIPITEM — we
-    // printed nothing here until `0x6e2380` was carved): Parry's 0x2a5f3 is exactly the eleven
+    // A multi-bit mask is named by ItemSubClassMask.dbc, not skipped (`0x52eef0` — we
+    // printed nothing here until `0x6e2380` was decoded): Parry's 0x2a5f3 is exactly the eleven
     // melee subclasses, which that table names in one word.
     let parry = spells.catalog.get(3127).expect("Parry 3127");
     assert!(parry.equipped_item_subclass_mask.count_ones() > 1);
-    let v = spell_tooltip_view(3127, &spells, &mut t.ctx_for(0, Some(&subs), Some(&store)))
-        .expect("Parry view");
+    let v = spell_tooltip_view(
+        3127,
+        &spells,
+        &mut t.ctx_for(&objects, 0, Some(&subs), Some(&store)),
+    )
+    .expect("Parry view");
     assert_eq!(v.requires_item.as_deref(), Some("Requires Melee Weapon"));
 
     // 2 · Attack (6603) — `Effect[0] == 78` omits the cast|cooldown line WHOLE, even though
-    // `Attributes & 0x40` is clear. Before the §3.4 gate widened, this read "Instant".
+    // `Attributes & 0x40` is clear. Before the cast-line gate `0x52eb15` widened, this read
+    // "Instant".
     let d = spells.catalog.get(6603).expect("Attack 6603");
     assert_eq!(d.effects[0], 78, "SPELL_EFFECT_ATTACK");
     assert!(!d.passive, "6603 carries Attributes 0x10, not 0x40");
-    let v = spell_tooltip_view(6603, &spells, &mut t.ctx(0, None)).expect("Attack view");
+    let v = spell_tooltip_view(6603, &spells, &mut t.ctx(&objects, 0, None)).expect("Attack view");
     assert_eq!(v.cast_time, None, "the law's Effect[0] gate");
-    // …and the chance line the same Effect[0] selects (law line 10 / §3-CHANCE). ATTACK
+    // …and the chance line the same Effect[0] selects (`[0x52f5b1, 0x52f697)`). ATTACK
     // BYPASSES the passive gate, which is the whole reason a non-passive Attack shows a crit
     // line at all. No descriptor = no line; the percentages are already percents on the wire.
     assert_eq!(v.chance, None, "no player streamed yet");
@@ -399,35 +473,51 @@ fn the_pinned_c6_lines_on_real_data() {
         (1109u16, 2.62f32.to_bits()), // PLAYER_CRIT_PERCENTAGE
         (1107u16, 5.5f32.to_bits()),  // PLAYER_DODGE_PERCENTAGE
     ]));
-    let v = spell_tooltip_view(6603, &spells, &mut t.ctx_for(0, None, Some(&rated)))
-        .expect("Attack view");
+    let v = spell_tooltip_view(
+        6603,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&rated)),
+    )
+    .expect("Attack view");
     assert_eq!(v.chance.as_deref(), Some("2.62% chance to crit"));
     // Dodge (81) is passive and reads its own field.
     let dodge = spells.catalog.get(81).expect("Dodge 81");
     assert_eq!(dodge.effects[0], 20, "SPELL_EFFECT_DODGE");
     assert!(dodge.passive, "81 carries Attributes 0x40");
-    let v =
-        spell_tooltip_view(81, &spells, &mut t.ctx_for(0, None, Some(&rated))).expect("Dodge view");
+    let v = spell_tooltip_view(81, &spells, &mut t.ctx_for(&objects, 0, None, Some(&rated)))
+        .expect("Dodge view");
     assert_eq!(v.chance.as_deref(), Some("5.50% chance to dodge"));
     // A spell naming none of the four effects has no line at all.
-    let v = spell_tooltip_view(133, &spells, &mut t.ctx_for(0, None, Some(&rated)))
-        .expect("Fireball view");
+    let v = spell_tooltip_view(
+        133,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&rated)),
+    )
+    .expect("Fireball view");
     assert_eq!(v.chance, None);
 
     // 3 · Slow Fall (130) — "Reagents: Light Feather", inline-red while unowned (no store =
     // owns nothing). The name rides the ask-once item cache, seeded here as the server would.
     let d = spells.catalog.get(130).expect("Slow Fall 130");
     assert_eq!(d.reagents[0], (17056, 1), "Light Feather ×1");
-    let v = spell_tooltip_view(130, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Slow Fall view");
+    let v = spell_tooltip_view(
+        130,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Slow Fall view");
     assert_eq!(
         v.reagents, None,
         "the template hasn't landed: the line waits rather than printing an id"
     );
     t.items
         .insert_template(17056, Some(crate::items::test_template("Light Feather")));
-    let v = spell_tooltip_view(130, &spells, &mut t.ctx_for(0, None, Some(&store)))
-        .expect("Slow Fall view");
+    let v = spell_tooltip_view(
+        130,
+        &spells,
+        &mut t.ctx_for(&objects, 0, None, Some(&store)),
+    )
+    .expect("Slow Fall view");
     assert_eq!(
         v.reagents.as_deref(),
         Some("Reagents: |cffff2020Light Feather|r"),
diff --git a/crates/benilla-app/src/ui_trade.rs b/crates/benilla-app/src/ui_trade/mod.rs
similarity index 95%
rename from crates/benilla-app/src/ui_trade.rs
rename to crates/benilla-app/src/ui_trade/mod.rs
index f3948210..6bc2e18a 100644
--- a/crates/benilla-app/src/ui_trade.rs
+++ b/crates/benilla-app/src/ui_trade/mod.rs
@@ -2,7 +2,7 @@
 //! [`benilla_ui::script`]'s `trade` module, the two-sided twin of [`crate::ui_mail`]'s mailbox seam.
 //!
 //! Trade is entirely server-driven: a right-click → **Trade** ([`crate::ui_trade`] via the UnitPopup
-//! row) sends `CMSG_INITIATE_TRADE`; the net bridge ([`crate::net::apply::trade`]) then folds the two
+//! row) sends `CMSG_INITIATE_TRADE`; the packet handlers ([`net`]) then fold the two
 //! status packets into [`TradeSession`] — `SMSG_TRADE_STATUS` drives the open/accept/close state
 //! machine, `SMSG_TRADE_STATUS_EXTENDED` replaces one side's item/gold snapshot. Each frame
 //! [`feed_trade`] resolves both sides' wire [`TradeItem`]s to Lua-facing
@@ -18,18 +18,18 @@
 //! `SMSG_TRADE_STATUS(BEGIN_TRADE)` only *records* the request; [`answer_trade_request`] walks the
 //! reference's own eight-leg ladder (`0x4bf736`) and either refuses it — on one of three different
 //! opcodes, or with no packet at all — or accepts it, which is what the client did unconditionally
-//! before. The split is what makes the ladder possible: it reads the ignore list, the cinematic
-//! state, player control, the auction house, the initiator's descriptor, an outbound initiate of
-//! ours and the [`BlockTrades`] CVar, none of which can reach `apply_net_updates` at Bevy's
-//! 16-`SystemParam` ceiling — and its answer may span frames, which a wire decoder cannot do at
-//! all. Decision 1725 left the cinematic leg unbuilt for exactly that reason and said so; this is
-//! the seam that makes it, and the seven beside it, ordinary.
+//! before. The split is what made the ladder possible when it was built: it reads the ignore
+//! list, the cinematic state, player control, the auction house, the initiator's descriptor, an
+//! outbound initiate of ours and the [`BlockTrades`] CVar, none of which could reach the drain's
+//! dispatch match at Bevy's 16-`SystemParam` ceiling (decision 1725 left the cinematic leg unbuilt
+//! for exactly that reason and said so). Since 2306 the status packet is this module's own
+//! handler ([`net`]) and that ceiling is gone; what keeps the ladder a system of its own is that
+//! its answer may **span frames**, which a packet handler cannot do.
 //!
 //! **There is no consent prompt, and that is faithful rather than missing.** 1.12.1 registers a
-//! `TRADE_REQUEST` event and signals it from nowhere, so the `TRADE` StaticPopup that would have
-//! asked is dead code in the real client (§5 cross-checked — wow-re
-//! `ui/scratch/incoming-trade-request-law.md` §3). benilla wired that dialog up and took it back
-//! out (decision 1764): the reference's answer to an unwanted trade is the ignore list and the
+//! `TRADE_REQUEST` event (slot `0xbe160c`) and signals it from nowhere, so the `TRADE` StaticPopup
+//! that would have asked is dead code in the real client. benilla wired that dialog up and took it
+//! back out (decision 1764): the reference's answer to an unwanted trade is the ignore list and the
 //! *Block Trades* checkbox, both of which are legs of the ladder below.
 //!
 //! **The partner's portrait** rides the shared `"npc"` booth token: [`TradeSession`] implements
@@ -54,12 +54,14 @@ use benilla_ui::script::{ScriptValue, TradeSideState, TradeSlotItem, TradeState,
 use crate::entities::ItemDisplays;
 use crate::items::Items;
 use crate::names::NameCache;
-use crate::net::{ClientCommand, GuidIndex, NetCommands, ObjectStore, SelfPlayer};
+use crate::net::{ClientCommand, GuidIndex, NetCommands, ObjectStore, Objects, SelfPlayer};
 use crate::target::Selection;
 use crate::ui_party::GroupState;
 use crate::ui_script::{UiFeed, UiInput};
 use crate::ui_session::NpcSession;
 
+mod net;
+
 /// One side's offer as the wire delivered it — the seven slots (index 0 = trade slot 1 … index 6 =
 /// the non-traded / enchant slot) plus the gold and the enchant-slot spell. Filled from
 /// `SMSG_TRADE_STATUS_EXTENDED`; the feed resolves the [`TradeItem`]s to display rows.
@@ -71,7 +73,7 @@ struct TradeOffer {
     enchant_spell_id: u32,
 }
 
-/// The open trade window's session, filled by the net bridge ([`crate::net::apply::trade`]) and read
+/// The open trade window's session, filled by the packet handlers ([`net`]) and read
 /// by [`feed_trade`]. Holds the partner guid, the open flag, both sides' wire offers, and the two
 /// accept flags. Cleared on cancel/complete/close and on disconnect.
 ///
@@ -119,7 +121,7 @@ pub(crate) struct TradeSession {
     /// The partner pressed Trade (their accept glow) — set by `TRADE_STATUS_TRADE_ACCEPT`.
     their_accept: bool,
     /// **A `TRADE_REQUEST_CANCEL` is owed to the VM** — set by the `CANCELED` arm of
-    /// [`crate::net::apply::trade::trade_status`], drained by [`feed_trade`] on the next frame.
+    /// [`net`]'s status handler, drained by [`feed_trade`] on the next frame.
     ///
     /// It is a *pending signal* rather than session state, so it is the one field
     /// [`Self::close`] carries across the reset: the reference's own `CANCELED` arm signals the
@@ -132,11 +134,10 @@ pub(crate) struct TradeSession {
     ///
     /// The reference has no queue because it never waits: `ERR_INITIATE_TRADE_S` comes off the
     /// player-name cache inside the `CMSG_INITIATE_TRADE` sender (`0x5d4031`, printing at
-    /// `0x5d4042` on a hit and from the query callback `0x5d4080` at `0x5d40ca` on a miss — wow-re
-    /// `ui/scratch/incoming-trade-request-law.md` §10.2), and the status arms' `%s` lines read the
-    /// name straight off the live `CGUnit` (`0x609210`). benilla may need a `CMSG_NAME_QUERY`
-    /// round trip for either, which is a wait a wire decoder cannot do — the same seam
-    /// [`answer_trade_request`]'s leg 8 exists for.
+    /// `0x5d4042` on a hit and from the query callback `0x5d4080` at `0x5d40ca` on a miss), and the
+    /// status arms' `%s` lines read the name straight off the live `CGUnit` (`0x609210`). benilla
+    /// may need a `CMSG_NAME_QUERY` round trip for either, which is a wait a wire decoder cannot
+    /// do — the same seam [`answer_trade_request`]'s leg 8 exists for.
     ///
     /// A `Vec` rather than one slot because two can be owed at once: our own initiate parks a line
     /// and the server's refusal of that same initiate parks another, and the second must not eat
@@ -161,7 +162,7 @@ pub(crate) struct NamedLine {
     /// Cases 0/5/14 take the name off the named player's **live `CGUnit`** (`0x609210`) after
     /// asking `0x468460(guid, TYPEMASK_PLAYER)` whether the object is still there — so if it is
     /// not, the reference prints **nothing**, and never waits. `ERR_INITIATE_TRADE_S` is the
-    /// opposite shape (wow-re §10.2): it goes through the player-name **cache** `0x55f080`, has no
+    /// opposite shape: it goes through the player-name **cache** `0x55f080`, has no
     /// object test at all, and defers to the name query's callback when the cache misses.
     ///
     /// benilla has one name source for both, so the distinction has to be carried: `true` drops
@@ -317,8 +318,8 @@ impl TradeSession {
 
     /// **Signal `TRADE_REQUEST_CANCEL`** — the one Lua event the reference's 23-case status
     /// dispatcher fires, from the top of its `CANCELED` arm (`0x4bf832`, the sole `SignalEvent`
-    /// inside `[0x4bf720, 0x4bfa08)` — wow-re `re/events/event-firesites.tsv`). See
-    /// [`Self::request_cancel`] for why it survives [`Self::close`].
+    /// inside `[0x4bf720, 0x4bfa08)`). See [`Self::request_cancel`] for why it survives
+    /// [`Self::close`].
     pub(crate) fn signal_request_cancel(&mut self) {
         self.request_cancel = true;
     }
@@ -455,7 +456,7 @@ impl TradeSession {
     }
 
     // ── Test windows onto the private state, for the sibling module that owns the status arm ──
-    //    (`crate::net::apply::trade`, whose tests drive `trade_status` and then have to ask what
+    //    ([`net`], whose tests drive `trade_status` and then have to ask what
     //    it did). Reading them through named accessors rather than opening the fields keeps the
     //    session's invariants — `partner`/`request` mutually exclusive, `open` gating `npc()` —
     //    enforced in exactly one file.
@@ -502,6 +503,7 @@ pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut block: ResMut<Block
 impl Plugin for UiTradePlugin {
     fn build(&self, app: &mut App) {
         app.add_observer(on_cvar);
+        net::register(app);
         app.init_resource::<TradeSession>()
             .init_resource::<BlockTrades>()
             .add_systems(
@@ -544,19 +546,17 @@ pub(crate) struct BlockTrades(pub(crate) bool);
 /// **Answer an incoming trade request** — the arm the reference keeps inside `CGTradeInfo`'s
 /// dispatcher (`0x4bf736`, case 1 of the 23-case `0x4bf720`), lifted out to where its inputs live.
 ///
-/// The net drain only *records* the request ([`TradeSession::request`]); this system decides. The
-/// split is the point: the decision reads the ignore list, the cinematic state, player control, the
-/// auction house, the initiator's own descriptor, an outbound initiate of ours and a CVar, and none
-/// of those can reach `apply_net_updates`, whose signature is at Bevy's 16-`SystemParam` ceiling.
-/// That ceiling is exactly why decision 1725 left the cinematic leg unbuilt and said so; it is not
-/// a ceiling this side of the seam has. The answer can also **span frames**, which a wire decoder
-/// cannot do at all: the `BlockTrades` line names the initiator, and that name may need a
-/// `CMSG_NAME_QUERY` first.
+/// The status handler only *records* the request ([`TradeSession::request`]); this system decides.
+/// The split is the point: the answer can **span frames**, which a packet handler cannot do — the
+/// `BlockTrades` line names the initiator, and that name may need a `CMSG_NAME_QUERY` first. (It
+/// was first cut for a second reason that 2306 retired: the decision reads the ignore list, the
+/// cinematic state, player control, the auction house, the initiator's own descriptor, an outbound
+/// initiate of ours and a CVar, none of which could reach the drain's dispatch match at Bevy's
+/// 16-`SystemParam` ceiling — exactly why decision 1725 left the cinematic leg unbuilt and said so.)
 ///
 /// **The ladder is the reference's, in its order** — eight legs, walked contiguously over
-/// `[0x4bf736, 0x4bf7f8)` and cross-checked by four independent derivations (wow-re
-/// `ui/scratch/incoming-trade-request-law.md` §2). Three answer with something other than "busy",
-/// which is why this is a ladder and not a boolean:
+/// `[0x4bf736, 0x4bf7f8)`. Three answer with something other than "busy", which is why this is a
+/// ladder and not a boolean:
 ///
 /// | # | condition | benilla reads | answer |
 /// |---|---|---|---|
@@ -582,10 +582,9 @@ pub(crate) struct BlockTrades(pub(crate) bool);
 /// player would feel, and the reference's own answer to an unwanted trade is leg 2 and leg 8 —
 /// ignore them, or tick *Block Trades*.
 ///
-/// Three legs were wrong in wow-re's earlier five-condition gloss and were corrected by the round
-/// that produced the note above — `[0xb4b3e4]` is player *control*, not "in world"; `[0xb725f8]` is
-/// the auction house, not a pending trade; and the ignore leg was missing entirely. This is why the
-/// gloss was not built from.
+/// Three legs are easy to get wrong: `[0xb4b3e4]` is player *control*, not "in world";
+/// `[0xb725f8]` is the auction house, not a pending trade; and the ignore leg is easy to miss
+/// entirely.
 /// **`0x468460(guid, TYPEMASK_PLAYER)`** — the guid's live object, or `None` when it is not a
 /// streamed player. The reference asks this in two places in this arc and benilla now asks it in
 /// the same two: the incoming ladder's leg 3 (`0x4bf779`, which drops a request from a guid that
@@ -763,14 +762,15 @@ fn own_item_at(
     bag: i64,
     slot: u32,
     store: Option<&ObjectStore>,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
 ) -> Option<TradeItem> {
-    let (guid, count) = crate::ui_items::slot_guid_count(store, bag, slot, items);
+    let (guid, count) = crate::ui_items::slot_guid_count(store, bag, slot, objects);
     if guid == 0 {
         return None;
     }
-    let entry = items.object(guid).and_then(|f| f.object_entry())?;
+    let entry = objects.object(guid).and_then(|f| f.object_entry())?;
     let display_id = items
         .template(entry, guid, commands)
         .map(|t| t.display_info_id)
@@ -870,7 +870,7 @@ fn feed_trade(
     }
     // The per-slot events the stock TradeFrame.lua repaints one slot on (`0x4bf414`/`0x4bf452`
     // TRADE_TARGET_ITEM_CHANGED, `0x4bf487`/`0x4bfaef` TRADE_PLAYER_ITEM_CHANGED, arg1 the 1-based
-    // slot — wow-re `event-firesites.tsv`; decision 1966). The full TRADE_UPDATE below is kept:
+    // slot; decision 1966). The full TRADE_UPDATE below is kept:
     // the reference fires it too, from `0x4c034f`.
     if changed && trade.is_open() && !opened {
         let empty = TradeState::default();
@@ -913,8 +913,8 @@ fn feed_trade(
         }
     }
     // `TRADE_REQUEST_CANCEL` — the `CANCELED` arm's own signal, and the ONLY Lua event the
-    // reference's 23-case status dispatcher fires (`0x4bf832`; wow-re `event-firesites.tsv` finds
-    // no other `SignalEvent` in `[0x4bf720, 0x4bfa08)`). It goes out **ahead of** the
+    // reference's 23-case status dispatcher fires (`0x4bf832`; there is no other `SignalEvent` in
+    // `[0x4bf720, 0x4bfa08)`). It goes out **ahead of** the
     // `TRADE_CLOSED` the same arm's window clear fires, which is the arm's own address order:
     // signal `0x4bf832`, then `0x4bf842 call 0x4bf4e0`, whose `0x4bf522` is `TRADE_CLOSED`.
     //
@@ -991,6 +991,7 @@ fn drain_trade(
     commands: Res<NetCommands>,
     selection: Res<Selection>,
     group: Res<GroupState>,
+    objects: Objects,
     items: Res<Items>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
 ) {
@@ -1048,7 +1049,7 @@ fn drain_trade(
         if let Some(trade_slot) = id.checked_sub(1).and_then(|n| u8::try_from(n).ok()) {
             // Optimistic own display: vmangos echoes the placement only to the partner, so resolve the
             // bag item and fill our own column client-side (decision 0592 P2).
-            if let Some(item) = own_item_at(bag, slot, store, &items, &commands) {
+            if let Some(item) = own_item_at(bag, slot, store, &objects, &items, &commands) {
                 trade.place_own_item(id, item);
             }
             info!(target: "trade", "set item: slot {id} <- bag {bag}/{slot} (wire {wire_bag}/{wire_slot}); sending CMSG_SET_TRADE_ITEM");
@@ -1343,6 +1344,7 @@ mod tests {
         app.init_resource::<TradeSession>()
             .init_resource::<GroupState>()
             .init_resource::<Items>()
+            .init_resource::<GuidIndex>()
             .insert_resource(NetCommands(tx))
             .insert_resource(Selection {
                 target: None,
@@ -1401,9 +1403,8 @@ mod tests {
 
     /// **`TRADE_REQUEST_CANCEL` fires, and only on `CANCELED`.** It is the one Lua event the
     /// reference's 23-case status dispatcher signals (`0x4bf832`, the sole `SignalEvent` inside
-    /// `[0x4bf720, 0x4bfa08)` — wow-re `re/events/event-firesites.tsv`), and benilla fired it from
-    /// nowhere: 1764 noticed the gap and left it, and the stock `UIParent.lua` has listened for it
-    /// ever since without anything to hear.
+    /// `[0x4bf720, 0x4bfa08)`), and benilla fired it from nowhere: 1764 noticed the gap and left
+    /// it, and the stock `UIParent.lua` has listened for it ever since without anything to hear.
     ///
     /// Nothing stock *acts* on it (it hides the `TRADE` StaticPopup, which can never be up — that
     /// dialog is dead code in the reference too), so the observable is the event itself, which is
@@ -1427,7 +1428,7 @@ mod tests {
         assert_eq!(cancels_seen(&mut app), 0, "nothing has cancelled anything");
 
         // A plain close — what `COMPLETE` and `CLOSE_WINDOW` do — signals nothing. (Which
-        // statuses reach which of these two is `net::apply::trade`'s own test; this is the half
+        // statuses reach which of these two is `ui_trade::net`'s own test; this is the half
         // that turns a signal into an event.)
         app.world_mut()
             .resource_mut::<TradeSession>()
@@ -1456,7 +1457,7 @@ mod tests {
 
     /// **The outgoing line.** "You have requested to trade with %s." is printed by the reference
     /// from inside its own `CMSG_INITIATE_TRADE` sender (`0x5d4042` on a name-cache hit,
-    /// `0x5d40ca` from the name-query callback on a miss — wow-re §10.2), not from anything the
+    /// `0x5d40ca` from the name-query callback on a miss), not from anything the
     /// server says back. benilla sent the packet in silence, so a trade that the server then
     /// refused produced no text at all, in either direction.
     ///
@@ -1618,7 +1619,7 @@ mod tests {
     /// **Block Trades** refuses without asking, and it is the one refusal that speaks: the
     /// `ERR_TRADE_BLOCKED_S` line naming the initiator (`0x496720(0xbb, …)`). Catalog row `0xbb`
     /// is `kind = 0` — the **chat frame**, chat type `0xa` — so this is a system chat line and
-    /// **not** the red `UI_ERROR_MESSAGE`, which is `kind = 2`. That correction is the RE's.
+    /// **not** the red `UI_ERROR_MESSAGE`, which is `kind = 2`.
     #[test]
     fn block_trades_refuses_and_says_so() {
         let (mut app, rx) = request_app(true, false, true);
@@ -1666,8 +1667,8 @@ mod tests {
     }
 
     /// Leg 7 — an open auction house refuses the request. `[0xb725f8]`/`[0xb725fc]` is the open
-    /// auctioneer's guid, which the old five-condition gloss had mislabelled as "a trade is
-    /// already pending". benilla was one commit from building that wrong leg.
+    /// auctioneer's guid, which is easy to mislabel as "a trade is already pending". benilla was
+    /// one commit from building that wrong leg.
     #[test]
     fn an_open_auction_house_refuses_the_request() {
         let (mut app, rx) = request_app(false, false, true);
@@ -1734,8 +1735,8 @@ mod tests {
     /// Legs 1 and 3 — the two that answer with **nothing at all**: our own initiate in flight
     /// (`[0xc4bec8]`), and an initiator that resolves to no streamed player object. Both drop the
     /// request without a packet, which is the reference's behaviour and not an oversight — it has
-    /// nothing to say to a trade it cannot see. Leg 1 is also what replaced the "already trading"
-    /// leg the old gloss claimed: the latch is set by the initiate sender and never by
+    /// nothing to say to a trade it cannot see. Leg 1 is also what replaced an "already trading"
+    /// leg: the latch is set by the initiate sender and never by
     /// `OPEN_WINDOW`, so it is "we asked somebody", not "a window is up".
     #[test]
     fn two_legs_answer_with_no_packet_at_all() {
@@ -1841,6 +1842,7 @@ mod tests {
         app.init_resource::<TradeSession>()
             .init_resource::<GroupState>()
             .init_resource::<Items>()
+            .init_resource::<GuidIndex>()
             .insert_resource(NetCommands(tx))
             .insert_resource(Selection::default());
         let mut vm = UiScript::new().unwrap();
@@ -1888,6 +1890,7 @@ mod tests {
         app.init_resource::<TradeSession>()
             .init_resource::<GroupState>()
             .init_resource::<Items>()
+            .init_resource::<GuidIndex>()
             .insert_resource(NetCommands(tx))
             .insert_resource(Selection::default());
         app.insert_non_send_resource(UiScript::new().unwrap());
diff --git a/crates/benilla-app/src/net/apply/trade.rs b/crates/benilla-app/src/ui_trade/net.rs
similarity index 86%
rename from crates/benilla-app/src/net/apply/trade.rs
rename to crates/benilla-app/src/ui_trade/net.rs
index 9995a0c3..dd2eacfd 100644
--- a/crates/benilla-app/src/net/apply/trade.rs
+++ b/crates/benilla-app/src/ui_trade/net.rs
@@ -1,20 +1,54 @@
-//! The player-trade arc's drain-side arm bodies for [`super::apply_net_updates`]'s dispatch match
-//! (decision 0592 P1). Each `pub(super)` fn here is one `SessionEvent` arm's body, driving the
-//! [`crate::ui_trade::TradeSession`] state machine the feed reads; the match at the call site stays
-//! the dispatcher. The `UiScript` events these ultimately drive are fired by
-//! [`crate::ui_trade::feed_trade`] (the feed owns the VM), so these arms only mutate the session +
-//! send the auto-reply.
+//! The player trade's packet handlers (decision 0592 P1; in the net handler table since 2306) —
+//! the status packet drives the open/accept/close state machine, the extended snapshot replaces
+//! one side's item/gold, both into the [`TradeSession`] the feed reads. The `UiScript` events
+//! these ultimately drive are fired by [`super::feed_trade`] (the feed owns the VM), so the
+//! handlers only mutate the session + send the auto-reply.
 
 use benilla_protocol::messages::{TradeStatus, TradeStatusExtended};
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
 
-use crate::net::{ClientCommand, NetCommands};
+use super::{NamedLine, TradeSession};
+use crate::net::{ClientCommand, NetCommands, NetHandlerApp};
 use crate::ui_action::{UiError, UiErrorKeys};
-use crate::ui_trade::{NamedLine, TradeSession};
+
+/// Register the trade's handlers — called from [`super::UiTradePlugin`]. One per kind, plus the
+/// session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::TradeStatus, on_trade_status)
+        .net_handler(K::TradeStatusExtended, on_trade_status_extended)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+fn on_trade_status(
+    In(ev): In<SessionEvent>,
+    mut trade: ResMut<TradeSession>,
+    mut errors: ResMut<UiErrorKeys>,
+    commands: Res<NetCommands>,
+) {
+    if let SessionEvent::TradeStatus { status } = ev {
+        trade_status(status, &mut trade, &mut errors, &commands);
+    }
+}
+
+fn on_trade_status_extended(In(ev): In<SessionEvent>, mut trade: ResMut<TradeSession>) {
+    if let SessionEvent::TradeStatusExtended { state } = ev {
+        trade_status_extended(&state, &mut trade);
+    }
+}
+
+/// An open trade dies with the socket (decision 0592) — the reconnect starts with no trade. A
+/// listener on the session end (a second handler on `Disconnected`, after the bridge's own
+/// teardown, `net::session::on_disconnected`).
+fn on_session_end(In(_): In<SessionEvent>, mut trade: ResMut<TradeSession>) {
+    trade.clear_session();
+}
 
 /// `SessionEvent::TradeStatus` (`SMSG_TRADE_STATUS`) — benilla's face of the reference's own
 /// 23-case dispatcher `CGTradeInfo 0x4bf720` (`ecx` = the status code; jump table `0x4bfa08`;
 /// sole caller `0x5d4923`, inside the `SMSG_TRADE_STATUS` handler `0x5d47c0`). Every arm below is
-/// that function's, walked (wow-re `ui/scratch/incoming-trade-request-law.md` §11).
+/// that function's, walked.
 ///
 /// **Three different things a status can do, and they are not the same set.**
 ///
@@ -33,12 +67,12 @@ use crate::ui_trade::{NamedLine, TradeSession};
 /// is unobservable — every code in (3) that is not in (2) arrives as an *initiate* refusal, with
 /// no window open — but it made the code claim `TARGET_STUNNED` tears down a trade window, and it
 /// got `REJECTED` and `UNKNOWN_13` wrong in opposite directions (decision 1764 wrote both down as
-/// unsettled; §11 settles them).
+/// unsettled; their arms, `0x4bf821` and `0x4bfa02`, settle them).
 ///
 /// `BEGIN_TRADE` records the incoming request **without answering it** (decision 1764 — the reply
-/// is a ladder of eight gates, so [`crate::ui_trade::answer_trade_request`] owns it, and it is the
+/// is a ladder of eight gates, so [`super::answer_trade_request`] owns it, and it is the
 /// only arm of the reference's dispatcher that speaks to the wire).
-pub(super) fn trade_status(
+fn trade_status(
     status: TradeStatus,
     trade: &mut TradeSession,
     errors: &mut UiErrorKeys,
@@ -87,9 +121,8 @@ pub(super) fn trade_status(
         }
         // The three that really do tear the window down. `CANCELED` also signals
         // `TRADE_REQUEST_CANCEL` (`0x4bf832`) — the ONE Lua event this whole dispatcher fires
-        // (wow-re `re/events/event-firesites.tsv` finds no other `SignalEvent` in
-        // `[0x4bf720, 0x4bfa08)`) — and it signals it BEFORE the close, which is why the flag
-        // survives [`TradeSession::close_window`].
+        // (there is no other `SignalEvent` in `[0x4bf720, 0x4bfa08)`) — and it signals it BEFORE
+        // the close, which is why the flag survives [`TradeSession::close_window`].
         //
         // Each of the three also sends `CMSG_CANCEL_TRADE` from inside `0x4bf4e0`. benilla does
         // not send it here and does not need to: the window is the stock `TradeFrame.xml`, whose
@@ -138,14 +171,14 @@ enum Line {
 /// Five arms genuinely say nothing (`OPEN_WINDOW`, `TRADE_ACCEPT`, `BACK_TO_TRADE`, `REJECTED`,
 /// `UNKNOWN_13`); the other eighteen print. Two of those eighteen answer `None` *here* for reasons
 /// of their own: `BEGIN_TRADE`'s line is the ladder's
-/// ([`crate::ui_trade::answer_trade_request`]'s leg 8), and `CLOSE_WINDOW`'s is the gap at the
+/// ([`super::answer_trade_request`]'s leg 8), and `CLOSE_WINDOW`'s is the gap at the
 /// bottom of this doc.
 ///
 /// **Eleven of the ids are outside the trade block** `0xb9..=0xbf` — which is why the arc shipped
 /// four of them and read as done: that block's own emit-site census answers "which arms print a
 /// *trade-keyed* message", and that is a different question from "which arms print". The full walk
-/// is wow-re §11; the tell was in the reference's own interface, where `ERR_TARGET_STUNNED`'s
-/// `GlobalStrings.lua` comment reads `-- Trade failure`.
+/// covers every arm of `0x4bf720`; the tell was in the reference's own interface, where
+/// `ERR_TARGET_STUNNED`'s `GlobalStrings.lua` comment reads `-- Trade failure`.
 ///
 /// | # | status | id | key | catalog kind |
 /// |---|---|---|---|---|
@@ -167,7 +200,7 @@ enum Line {
 /// | 22 | `ONLY_CONJURED` | `0x1ca` | `ERR_TRADE_WRONG_REALM` | `2` red |
 ///
 /// Case 1's own line (`ERR_TRADE_BLOCKED_S`, leg 8 only) is
-/// [`crate::ui_trade::answer_trade_request`]'s, and case 12's is the gap below.
+/// [`super::answer_trade_request`]'s, and case 12's is the gap below.
 ///
 /// **Nothing here decides a surface.** Three of these are chat lines and thirteen are toasts,
 /// split between yellow and red, and the split does not follow the English: the two *successful*
@@ -178,9 +211,9 @@ enum Line {
 /// `0x4bfd70` maps the packet's `result` word (our [`TradeStatus::CloseWindow::result`]) over a
 /// **61-id** range, tail-jumping `0x622630` for everything it does not special-case, with `0x1d1`
 /// as a suppression sentinel. vmangos never sends status 12 (`SharedDefines.h` defines it;
-/// `TradeHandler.cpp` sends it nowhere), so there is no observable to build against — and wow-re
-/// flagged a self/other polarity inconsistency inside that mapper that wants a live capture to
-/// settle. Transcribing 61 rows nothing can reach, around a known-doubtful axis, is how a table
+/// `TradeHandler.cpp` sends it nowhere), so there is no observable to build against — and a
+/// self/other polarity inconsistency inside that mapper wants a live capture to settle.
+/// Transcribing 61 rows nothing can reach, around a known-doubtful axis, is how a table
 /// gets written wrong and believed; the window still closes on 12, it just says nothing.
 fn status_message(status: TradeStatus) -> Option<Line> {
     Some(match status {
@@ -215,7 +248,7 @@ fn status_message(status: TradeStatus) -> Option<Line> {
 
 /// `SessionEvent::TradeStatusExtended` (`SMSG_TRADE_STATUS_EXTENDED`) — replace one side's item/gold
 /// snapshot (decision 0592 P1); the feed repaints (`TRADE_UPDATE`) on the change.
-pub(super) fn trade_status_extended(ext: &TradeStatusExtended, trade: &mut TradeSession) {
+fn trade_status_extended(ext: &TradeStatusExtended, trade: &mut TradeSession) {
     bevy::log::info!(
         target: "trade",
         "SMSG_TRADE_STATUS_EXTENDED their_window={} gold={} items={}",
@@ -304,6 +337,36 @@ mod tests {
         trade
     }
 
+    /// End to end through the real registration: a status opens the window, and the session
+    /// end — the bridge's own teardown beside this listener — takes the trade with it.
+    #[test]
+    fn the_table_routes_the_status_and_the_session_end_to_the_trade() {
+        let (_, commands, _rx) = sink();
+        let mut app = App::new();
+        app.add_plugins(MinimalPlugins)
+            .init_resource::<TradeSession>()
+            .init_resource::<UiErrorKeys>()
+            .insert_resource(commands);
+        register(&mut app);
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![SessionEvent::TradeStatus {
+                status: TradeStatus::OpenWindow,
+            }],
+        );
+        assert!(app.world().resource::<TradeSession>().is_open());
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![SessionEvent::Disconnected {
+                reason: "socket".into(),
+                end: benilla_protocol::SessionEnd::Lost,
+            }],
+        );
+        assert!(!app.world().resource::<TradeSession>().is_open());
+    }
+
     /// **Eighteen of the twenty-three arms print; this table carries sixteen.** The arc raised
     /// four, which is the report.
     ///
diff --git a/crates/benilla-app/src/ui_tradeskill.rs b/crates/benilla-app/src/ui_tradeskill.rs
index da98230a..0185254c 100644
--- a/crates/benilla-app/src/ui_tradeskill.rs
+++ b/crates/benilla-app/src/ui_tradeskill.rs
@@ -4,7 +4,7 @@
 //!
 //! There is no wire here at all, by the byte law: casting a profession opener (`Effect[0] ==
 //! SPELL_EFFECT_TRADE_SKILL`) never reaches the send — `Spell_C::TryCast 0x6e4b60` branches
-//! client-side and opens the window (wow-re `wave-cast.md`, VERIFIED; 0437). benilla mirrors that
+//! client-side and opens the window (0437). benilla mirrors that
 //! as the [`TradeSkillOpens`] intercept inside `ui_action::send_spell_cast`. The book itself is
 //! **client-built**: every known spell ([`PlayerActions::spells`]) carrying
 //! `SPELL_ATTR_IS_TRADESKILL` (`0x20` — the same bit that hides recipes from the spellbook, 0227)
@@ -12,7 +12,7 @@
 //! `Spell.dbc` columns, have-counts off the bags ([`count_of`]), the product off
 //! `EffectItemType`, names/icons through the ask-once item-template cache.
 //!
-//! The §5 fold-back (wow-re `tradeskill` node, VERIFIED at the bytes, decision 0446): the
+//! Per decision 0446 (the book build `0x4fca20`, `DoTradeSkill 0x500280`): the
 //! client-built list, the difficulty bands + the `low==0 → high−25` fallback, the numMade dice
 //! law, the one-cast-per-item repeat machine (clamped to numAvailable at the latch, re-cast off
 //! our own `SMSG_SPELL_GO`, canceled by fail/ESC/close), and the `EffectMiscValue[0] != 0`
@@ -20,7 +20,7 @@
 //! by the created item's `(ItemClass, ItemSubClass)`, named from `ItemSubClass.dbc`, two-level
 //! sort (0446; the filter family on top of it, 0452) — this feed resolves each recipe's `group`
 //! ([`resolve_recipe`]), so the book is no longer flat. The spell-focus tool never renders red, and
-//! that is **faithful, not a gap** (wow-re `tradeskill-tools-and-spell-focus.md`, §5-carved): the
+//! that is **faithful, not a gap** (`0x4ffa8b`): the
 //! reference's own `hasTool` for a focus is the literal `1.0` with no predicate anywhere, and the
 //! client holds neither a focus id nor a radius to test proximity with. The server refusing the
 //! cast is the whole of the feedback, there as here.
@@ -31,6 +31,7 @@ use bevy::prelude::*;
 
 use benilla_formats::{SpellFocusCatalog, SPELL_ATTR_IS_TRADESKILL, SPELL_EFFECT_CREATE_ITEM};
 use benilla_protocol::messages::PLAYER_SKILL_SLOTS;
+use benilla_protocol::{SessionEvent, SessionEventKind};
 use benilla_ui::script::{
     TradeSkillDifficulty, TradeSkillReagent, TradeSkillRecipe, TradeSkillState, UiScript,
 };
@@ -38,8 +39,9 @@ use benilla_ui::script::{
 use crate::creature_anim::{CastEvent, CastEventKind};
 use crate::entities::ItemDisplays;
 use crate::items::Items;
-use crate::net::{NetCommands, ObjectStore, SelfPlayer};
-use crate::ui_action::{cast_target, CastCommit, CastLadder, PlayerActions, Spells};
+use crate::net::{NetCommands, NetHandlerApp, ObjectStore, Objects, SelfPlayer};
+use crate::spell::{cast_target, CastCommit, CastLadder};
+use crate::ui_action::{PlayerActions, Spells};
 use crate::ui_items::{count_of, item_icon, InventoryScope};
 use crate::ui_script::UiInput;
 use crate::ui_spellbook::SkillLines;
@@ -53,15 +55,19 @@ use benilla_assets::{AssetSet, LockRecover, WorldAssets};
 pub(crate) struct TradeSkillOpens(pub(crate) Vec<u32>);
 
 /// The open crafting book: the skill line whose recipes the window shows. `None` = closed.
-/// Client-local state — no wire owns it (0437).
+/// Client-local state — no wire owns it (0437). Cleared by the Lua close and by the session end
+/// ([`on_session_end`]): a logout installs a fresh VM without running the old one's `OnHide`, so
+/// the close alone never comes, and the next login's feed would fire `TRADE_SKILL_SHOW` into the
+/// new character's UI.
 #[derive(Resource, Default)]
 pub(crate) struct TradeSkillOpen {
     pub(crate) line: Option<u32>,
 }
 
-/// The Create/Create All repeat machine (TU-D, byte-confirmed — decision 0446):
+/// The Create/Create All repeat machine (`DoTradeSkill 0x500280`, decision 0446):
 /// `DoTradeSkill(spell, n)` latches `n`, casts once, and each of our own `SMSG_SPELL_GO`s for
-/// that spell decrements and re-casts until dry; any cast failure or a window close stops it cold.
+/// that spell decrements and re-casts until dry; any cast failure, a window close or the session
+/// end ([`on_session_end`]) stops it cold.
 #[derive(Resource, Default)]
 pub(crate) struct TradeSkillRepeat {
     pub(crate) spell_id: u32,
@@ -85,6 +91,7 @@ pub(crate) struct UiTradeSkillPlugin;
 
 impl Plugin for UiTradeSkillPlugin {
     fn build(&self, app: &mut App) {
+        app.net_handler(SessionEventKind::Disconnected, on_session_end);
         app.init_resource::<TradeSkillOpens>()
             .init_resource::<TradeSkillOpen>()
             .init_resource::<TradeSkillRepeat>()
@@ -103,6 +110,20 @@ impl Plugin for UiTradeSkillPlugin {
     }
 }
 
+/// The book and its repeat die with the session — a listener on the session end (a second handler
+/// on the kind, after the bridge's own teardown). Queued opener casts go too: they were the old
+/// character's.
+fn on_session_end(
+    In(_): In<SessionEvent>,
+    mut opens: ResMut<TradeSkillOpens>,
+    mut open: ResMut<TradeSkillOpen>,
+    mut repeat: ResMut<TradeSkillRepeat>,
+) {
+    opens.0.clear();
+    open.line = None;
+    repeat.clear();
+}
+
 fn load_spell_focus(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let Some(assets) = assets else { return };
     let loaded = {
@@ -124,7 +145,7 @@ fn load_spell_focus(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
 /// Resolve intercepted opener casts to their skill line and open the right book. The line comes
 /// from the opener's own `SkillLineAbility` row (3908 Tailoring → 197) — the client's
 /// `SkillLineRecIndex_Find` hop (`0x6de040`); the Craft-vs-TradeSkill fork is the opener's
-/// `EffectMiscValue[0]` (byte-VERIFIED, wow-re `tradeskill` TU-A).
+/// `EffectMiscValue[0]` (`0x6e4bd7`).
 fn open_trade_skill(
     mut opens: ResMut<TradeSkillOpens>,
     mut open: ResMut<TradeSkillOpen>,
@@ -142,10 +163,10 @@ fn open_trade_skill(
             warn!("ui_tradeskill: opener {spell_id} has no SkillLineAbility row — dropped");
             continue;
         };
-        // The routing key — byte-VERIFIED (wow-re `tradeskill` TU-A, `0x6e4bd7`): the opener's
+        // The routing key (`0x6e4bd7`): the opener's
         // `EffectMiscValue[0] != 0` routes to the CraftFrame (Enchanting 3, Beast Training 1);
         // zero routes to the TradeSkillFrame. NOT a skill-line test — 0437's line-333 INTERIM
-        // is corrected by this fold-back. The nonzero value is not merely a flag: it IS the craft
+        // is corrected here. The nonzero value is not merely a flag: it IS the craft
         // type the client keeps at `ds:0xbdcfb8`, and the Craft window keys both its admission
         // filter and its row comparator on it (decision 1124), so it rides along.
         let craft_type = spells
@@ -182,7 +203,7 @@ fn skill_rank(store: &ObjectStore, skill_id: u32) -> (u32, u32) {
     (0, 0)
 }
 
-/// The difficulty banding — byte-VERIFIED (wow-re `tradeskill` TU-C): gray at rank ≥ trivialHigh,
+/// The difficulty banding (`0x4fcbfc`): gray at rank ≥ trivialHigh,
 /// green ≥ the (low+high)/2 midpoint, yellow ≥ trivialLow, orange below; the client's one
 /// fallback is `low == 0 → low = max(high − 25, 0)`. The TradeSkill window bands the RAW rank;
 /// the Craft window bands the effective skill (rank + bonuses) — the caller picks.
@@ -204,16 +225,15 @@ pub(crate) fn difficulty(rank: u32, low: u32, high: u32) -> TradeSkillDifficulty
 }
 
 /// **Law C** — the TradeSkill window's row icon, transcribing `GetTradeSkillIcon 0x4fdae0`
-/// (byte-VERIFIED; wow-re `ui/scratch/spell-icon-substitution-law.md` §2, folded back by decision
-/// 1107). Read `EffectItemType[0]` **unconditionally** as an item id and paint that item's icon;
-/// on any miss — a zero id, a template not yet landed — return **`None`**.
+/// (decision 1107). Read `EffectItemType[0]` **unconditionally** as an item id and paint that
+/// item's icon; on any miss — a zero id, a template not yet landed — return **`None`**.
 ///
 /// Two things the binding pointedly does *not* do, both of which this used to:
 ///
 /// - **No `CREATE_ITEM` gate.** `Effect[0]` (`+0xf4`) is never read anywhere in `[0x4fdae0,
 ///   0x4fdc29]`. So this takes `d.effect_item_type[0]` directly rather than the `product_item`
-///   computed beside it — that variable's `CREATE_ITEM` gate belongs to the separately-verified
-///   *made-count* law (wow-re `tradeskill` TU-C) and has no business steering an icon.
+///   computed beside it — that variable's `CREATE_ITEM` gate belongs to the separate
+///   *made-count* law (`GetTradeSkillNumMade 0x4fdc50`) and has no business steering an icon.
 /// - **No spell-icon fallback.** `+0x1d4`/`+0x1d8` and the `SpellIcon.dbc` globals appear nowhere
 ///   in the extent — proof by exhaustion over its three return paths, the last of which is a bare
 ///   `lua_pushnil`. A row whose item will not resolve shows *nothing*, never the recipe's own art.
@@ -249,9 +269,10 @@ fn resolve_recipe(
     icons: Option<&ItemDisplays>,
     subclasses: Option<&crate::ui_items::ItemSubClasses>,
     store: &ObjectStore,
+    objects: &Objects,
     items: &Items,
     commands: &NetCommands,
-    cooldowns: &crate::cooldowns::Cooldowns,
+    cooldowns: &crate::spell::Cooldowns,
     now: Instant,
 ) -> Option<TradeSkillRecipe> {
     let d = spells.catalog.get(spell_id)?;
@@ -261,7 +282,7 @@ fn resolve_recipe(
     let mut reagents = Vec::new();
     let mut num_available = u32::MAX;
     for &(entry, need) in d.reagents.iter().filter(|&&(e, n)| e != 0 && n != 0) {
-        let have = count_of(&store.0, items, entry, InventoryScope::CARRIED);
+        let have = count_of(&store.0, objects, entry, InventoryScope::CARRIED);
         let (name, icon) = match items.template(entry, 0, commands) {
             Some(t) => (Some(t.name.clone()), item_icon(icons, t.display_info_id)),
             None => (None, None),
@@ -281,8 +302,8 @@ fn resolve_recipe(
 
     // The product (CREATE_ITEM's EffectItemType, slot 0 — every probed recipe carries it there;
     // a multi-slot product is unobserved in 5875): the tooltip channel's item and the header key's
-    // source. The made-count is byte-VERIFIED (wow-re `tradeskill` TU-C): min = BasePoints +
-    // BaseDice, max = BasePoints + DieSides × BaseDice (multiplicative), clamped ≥ 1.
+    // source. The made-count (`GetTradeSkillNumMade 0x4fdc50`): min = BasePoints + BaseDice,
+    // max = BasePoints + DieSides × BaseDice (multiplicative), clamped ≥ 1.
     let (product_item, min_made, max_made) = if d.effects[0] == SPELL_EFFECT_CREATE_ITEM {
         let base = d.effect_base_points[0].max(0) as u32;
         let dice = d.effect_base_dice[0].max(0) as u32;
@@ -293,7 +314,7 @@ fn resolve_recipe(
         (0, 1, 1)
     };
     let icon = recipe_icon(d, icons, items, commands);
-    // The VERIFIED header key (wow-re `tradeskill` TU-B): the created item's (class, subclass),
+    // The header key (the book build `0x4fca20`): the created item's (class, subclass),
     // named from ItemSubClass.dbc (verbose-first). `None` while the ask-once template is in
     // flight — the client's own one-frame header deferral; the engine buckets it trailing. The
     // same template answer carries the product's InventoryType — the InvSlot filter's raw input
@@ -312,8 +333,7 @@ fn resolve_recipe(
         .flatten()
         .map_or((None, 0, 0), |(g, it, il)| (Some(g), it, il));
 
-    // Tools — **the spell FOCUS first, then `Totem[0]`, then `Totem[1]`** (wow-re
-    // `tradeskill/scratch/tradeskill-tools-and-spell-focus.md`, §5-carved: `0x4ff980`'s own push
+    // Tools — **the spell FOCUS first, then `Totem[0]`, then `Totem[1]`** (`0x4ff980`'s own push
     // order). We had the totems leading, which reverses the Requirements line for every recipe
     // that needs both — a Blacksmithing anvil recipe reads "Blacksmith Hammer, Anvil" instead of
     // "Anvil, Blacksmith Hammer".
@@ -336,7 +356,7 @@ fn resolve_recipe(
         }
     }
     for &t in d.totems.iter().filter(|&&t| t != 0) {
-        let have = count_of(&store.0, items, t, InventoryScope::CARRIED) > 0;
+        let have = count_of(&store.0, objects, t, InventoryScope::CARRIED) > 0;
         if let Some(info) = items.template(t, 0, commands) {
             tools.push((info.name.clone(), have));
         }
@@ -363,7 +383,7 @@ fn resolve_recipe(
 
 /// Build the book: the known attr-`0x20` recipes of the open line, difficulty-banded against the
 /// current rank. No sort applied here — the engine owns ALL ordering (group + tier + name, the
-/// VERIFIED two-level law, decision 0446 wow-re `tradeskill` TU-B).
+/// two-level law `0x4fd180`, decision 0446).
 fn feed_trade_skill(
     script: Option<NonSendMut<UiScript>>,
     open: Res<TradeSkillOpen>,
@@ -375,9 +395,10 @@ fn feed_trade_skill(
     subclasses: Option<Res<crate::ui_items::ItemSubClasses>>,
     repeat: Res<TradeSkillRepeat>,
     self_store: Query<&ObjectStore, With<SelfPlayer>>,
+    objects: Objects,
     items: Res<Items>,
     commands: Res<NetCommands>,
-    cooldowns: Res<crate::cooldowns::Cooldowns>,
+    cooldowns: Res<crate::spell::Cooldowns>,
     mut last: Local<crate::ui_script::VmMemo<Option<TradeSkillState>>>,
 ) {
     let Some(mut script) = script else {
@@ -416,6 +437,7 @@ fn feed_trade_skill(
                     icons.as_deref(),
                     subclasses.as_deref(),
                     store,
+                    &objects,
                     &items,
                     &commands,
                     &cooldowns,
@@ -423,8 +445,8 @@ fn feed_trade_skill(
                 )
             })
             .collect();
-        // No app-side sort: the engine owns ALL ordering (group + tier + name — the VERIFIED
-        // two-level law, wow-re `tradeskill` TU-B).
+        // No app-side sort: the engine owns ALL ordering (group + tier + name — the
+        // two-level law, `0x4fd180`).
         Some(TradeSkillState {
             line,
             line_name,
@@ -634,4 +656,33 @@ mod tests {
         let d = recipe(SPELL_EFFECT_CREATE_ITEM, 777);
         assert_eq!(recipe_icon(&d, None, &deps.items, &deps.commands), None);
     }
+
+    /// **The book and its repeat die with the session.** Both are client-local and only the Lua
+    /// close cleared them — but a logout installs a fresh VM without running the old one's
+    /// `OnHide`, so the close never comes: the next login's feed saw `None → Some` and fired
+    /// `TRADE_SKILL_SHOW` into the new character's UI, and a latched "Create All" re-cast on that
+    /// character's first own `SMSG_SPELL_GO` of the same id. Driven through the real registration.
+    #[test]
+    fn the_session_end_closes_the_book_and_drops_the_repeat() {
+        let mut app = App::new();
+        app.add_plugins(UiTradeSkillPlugin);
+        app.world_mut().resource_mut::<TradeSkillOpen>().line = Some(197);
+        {
+            let mut repeat = app.world_mut().resource_mut::<TradeSkillRepeat>();
+            repeat.spell_id = 3915;
+            repeat.remaining = 4;
+        }
+
+        crate::net::handlers::dispatch(
+            app.world_mut(),
+            vec![benilla_protocol::SessionEvent::Disconnected {
+                reason: "logged out".into(),
+                end: benilla_protocol::SessionEnd::LoggedOut,
+            }],
+        );
+
+        assert_eq!(app.world().resource::<TradeSkillOpen>().line, None);
+        let repeat = app.world().resource::<TradeSkillRepeat>();
+        assert_eq!((repeat.spell_id, repeat.remaining), (0, 0));
+    }
 }
diff --git a/crates/benilla-app/src/ui_trainer/law.rs b/crates/benilla-app/src/ui_trainer/law.rs
index eeb8f02f..766988fb 100644
--- a/crates/benilla-app/src/ui_trainer/law.rs
+++ b/crates/benilla-app/src/ui_trainer/law.rs
@@ -12,8 +12,8 @@
 //! obviously tidy — decision 1124 is the second time a plausible unification (the display name,
 //! assumed to hop like the group key) turned out to be refuted at the bytes.
 //!
-//! Sources: wow-re `system/ui/scratch/spell-icon-substitution-law.md` §1 (the icon),
-//! `trainer-service-tooltip-law.md` (the tooltip) and `trainer-craft-list-order.md` (the group key).
+//! Sources: `GetTrainerServiceIcon 0x4d8f50` (the icon), `SetTrainerService 0x5338b0` (the tooltip)
+//! and the list builder `0x4d7560` (the group key).
 
 use benilla_formats::{
     SkillLineCatalog, SpellCatalog, SPELL_ATTR_IS_TRADESKILL, SPELL_EFFECT_CREATE_ITEM,
@@ -29,9 +29,8 @@ use crate::ui_items::item_icon;
 
 use super::{TRAINER_TYPE_MOUNT, TRAINER_TYPE_TRADESKILL};
 
-/// The trainer's **icon law** — `GetTrainerServiceIcon 0x4d8f50`, byte-verified whole in wow-re
-/// (`system/ui/scratch/spell-icon-substitution-law.md` §1; the binding is not a marshal, the entire
-/// resolution is inlined there). Three gates, then a fallback:
+/// The trainer's **icon law** — `GetTrainerServiceIcon 0x4d8f50` (the binding is not a marshal,
+/// the entire resolution is inlined there). Three gates, then a fallback:
 ///
 /// 1. **The trainer type is 2** (tradeskill/profession — `[0xb73a08]`, the trainer-list packet's
 ///    type dword stored verbatim). A class/mount/pet trainer never substitutes.
@@ -85,11 +84,10 @@ pub(super) fn service_icon(
     wire.icon.clone()
 }
 
-/// The trainer's **tooltip law** — `SetTrainerService 0x5338b0`, byte-verified whole in wow-re
-/// (`system/ui/scratch/trainer-service-tooltip-law.md`). It is a *selector*, not a renderer: the
-/// binding emits no tooltip line of its own (verified negative — none of the four AddLine helpers
-/// appears in its extent) and hands one of the two shared builders a subject. That is why this
-/// returns a [`TrainerTooltip`] rather than any text.
+/// The trainer's **tooltip law** — `SetTrainerService 0x5338b0`. It is a *selector*, not a
+/// renderer: the binding emits no tooltip line of its own (verified negative — none of the four
+/// AddLine helpers appears in its extent) and hands one of the two shared builders a subject. That
+/// is why this returns a [`TrainerTooltip`] rather than any text.
 ///
 /// ```text
 /// for i in 0..3:
@@ -153,9 +151,9 @@ pub(super) fn service_tooltip(wire_spell: u32, spells: &SpellCatalog) -> Trainer
 }
 
 /// The **group-key law** — the builder `0x4d7560`'s per-trainer-type branch at `0x4d7786`
-/// (byte-verified, decision 1124; wow-re `system/ui/scratch/trainer-craft-list-order.md`). It is the
-/// third law on this page that forks on the same dword the other two do, and the one that decides
-/// what the director actually sees at the top of a profession trainer's list.
+/// (decision 1124). It is the third law on this page that forks on the same dword the other two
+/// do, and the one that decides what the director actually sees at the top of a profession
+/// trainer's list.
 ///
 /// **Type 2 (tradeskill) does not resolve a skill line at all.** The key defaults to `2` and becomes
 /// `1` iff the **WIRE** spell's own `Spell.dbc Effect[0..2]` contains `44 SKILL_STEP` (`0x4d77b6`) —
diff --git a/crates/benilla-app/src/ui_trainer/mod.rs b/crates/benilla-app/src/ui_trainer/mod.rs
index a9240c20..347b04a2 100644
--- a/crates/benilla-app/src/ui_trainer/mod.rs
+++ b/crates/benilla-app/src/ui_trainer/mod.rs
@@ -13,10 +13,12 @@
 //! `TRAINER_UPDATE` on a content change / `TRAINER_CLOSED` on clear. [`drain_trainer`] pulls the Lua
 //! intents back out: the Train button's `BuyTrainerService` → `CMSG_TRAINER_BUY_SPELL` for the open
 //! trainer, and `CloseTrainer` → a local clear (vanilla's client-side close sends no packet). A
-//! successful buy answers `SMSG_TRAINER_BUY_SUCCEEDED` — the spell itself lands via
-//! `SMSG_LEARNED_SPELL` (already in the book), and the net apply re-requests the list to repaint the
-//! bought row green→gray; a refusal (`SMSG_TRAINER_BUY_FAILED`) stages into [`TrainerErrors`] for the
-//! feed to surface on the window's red error line.
+//! successful buy answers `SMSG_TRAINER_BUY_SUCCEEDED`, which the reference does not even handle:
+//! the spell itself lands via `SMSG_LEARNED_SPELL`, and that — like a level, a skill point, a coin
+//! or a pet spell — runs the **state re-evaluator** ([`reeval`], the reference's `0x4d7d40`,
+//! decision 2333) over the open list and fires `TRAINER_UPDATE`; a refusal
+//! (`SMSG_TRAINER_BUY_FAILED`) stages into [`TrainerErrors`] for the feed to surface on the
+//! window's red error line.
 //!
 //! The standardized NPC-session range guard ([`crate::ui_session`]) client-side-closes the window
 //! when the player walks out of the trainer's service range (or the trainer despawns) — the same
@@ -36,7 +38,13 @@ use benilla_ui::script::{
 use crate::entities::ItemDisplays;
 use crate::items::Items;
 use crate::names::NameCache;
-use crate::net::{ClientCommand, NetCommands};
+use benilla_protocol::field::{
+    FIELD_PLAYER_FIELD_COINAGE, FIELD_PLAYER_SKILL_INFO_1_1, FIELD_UNIT_LEVEL,
+};
+use benilla_protocol::messages::PLAYER_SKILL_SLOTS;
+use bevy::ecs::system::SystemParam;
+
+use crate::net::{ClientCommand, FieldChanged, GuidIndex, NetCommands, ObjectStore, SelfPlayer};
 use crate::ui_action::{PlayerActions, Spells};
 use crate::ui_script::{UiFeed, UiInput};
 use crate::ui_session::{close_npc_session_out_of_range, npc_switched, NpcSession};
@@ -66,26 +74,27 @@ pub(crate) struct TrainerOpen {
     pub(crate) trainer_type: u32,
     /// The trainer's greeting line (`SMSG_TRAINER_LIST`'s trailing string).
     pub(crate) greeting: String,
-    /// A `SMSG_TRAINER_LIST` that **begins a window session** has landed and the feed has not yet
-    /// handed it to the engine. Drives the engine's filter/collapse/**selection** reset
-    /// ([`UiScript::reset_trainer_list_state`]) — the reference's builder rewrites all three on every
-    /// list packet (decision 1128; 2231 for the selection, `0x4d7b42`). It is not the same edge as a
-    /// snapshot change: those re-push the same list.
+    /// A `SMSG_TRAINER_LIST` has landed and the feed has not yet handed it to the engine. Drives
+    /// the engine's filter/collapse/**selection** reset ([`UiScript::reset_trainer_list_state`]) —
+    /// the reference's builder rewrites all three on every list packet (decision 1128; 2231 for
+    /// the selection, `0x4d7b42`). It is not the same edge as a snapshot change: those re-push
+    /// the same list.
     ///
-    /// "Begins a session", not "a packet arrived", because the two are the same thing in the
-    /// reference and are **not** in benilla (B253/B256's arc): the reference gets a list packet only
-    /// when a trainer opens — it repaints a purchase from a client-side state re-derivation
-    /// (`0x4d7d40`, decision 1128 §4.2) — while we ask for a fresh list after every buy. Letting our
-    /// own refresh carry the reference's per-packet reset made the state filter (and the collapse
-    /// set) evaporate on learning a spell, which is not something the reference can do. See
-    /// [`Self::refresh_pending`].
+    /// Every list packet begins a window session, in benilla as in the reference: the reference
+    /// gets one only when a trainer opens, and since 2333 so does benilla — a purchase, a level
+    /// or a skill point repaints the open window through the state re-evaluator ([`reeval`]),
+    /// never through a second list. (B253/B256's arc, when benilla still re-requested the list
+    /// after every buy, needed a "this packet is our own refresh" mark here so the player's
+    /// filter survived a purchase; the re-request and the mark went together.)
     pub(crate) fresh_list: bool,
-    /// The post-buy re-list **we asked for** ([`crate::net::apply`]'s `trainer_buy_succeeded`) is in
-    /// flight: the answering packet repaints the open window rather than opening one, so it must not
-    /// reset the filter/collapse masks — nor the selection, which is what leaves the learned spell
-    /// selected-but-hidden and so takes the detail pane down with it, the reference's own
-    /// post-purchase behaviour (2231). Cleared by the packet it belongs to, and by any close.
-    pub(crate) refresh_pending: bool,
+    /// One of the reference's twelve re-evaluation triggers fired while the window is open — a
+    /// spell learned/removed/superseded, a spell modifier (the two "talent" callers, 2336), the
+    /// pet's spellbook, or (read by the feed itself off the descriptor edges) money, level or a
+    /// skill slot. The feed runs [`reeval::re_derive_all`]
+    /// over the list and fires `TRAINER_UPDATE` whether or not a state moved, as `0x4d7d40`'s
+    /// tail does (`0x4d83f4`) — the stock window re-reads `GetMoney()` for the Train button on
+    /// exactly that event.
+    pub(crate) re_derive: bool,
 }
 
 impl TrainerOpen {
@@ -97,14 +106,21 @@ impl TrainerOpen {
         services: Vec<TrainerSpell>,
         greeting: String,
     ) {
-        // A repaint of the trainer already on screen, asked for by our own post-buy re-request, is
-        // not a new window session — so it carries no mask reset (the field's own doc says why).
-        let refresh = self.trainer == Some(trainer) && std::mem::take(&mut self.refresh_pending);
         self.trainer = Some(trainer);
         self.trainer_type = trainer_type;
         self.services = services;
         self.greeting = greeting;
-        self.fresh_list = !refresh;
+        // Every list packet is a window session (the field's doc says why), and a fresh list is
+        // the server's own states: nothing is pending against it.
+        self.fresh_list = true;
+        self.re_derive = false;
+    }
+
+    /// One of the twelve triggers fired: re-derive on the next feed, if a window is open.
+    pub(crate) fn trigger_re_derive(&mut self) {
+        if self.trainer.is_some() {
+            self.re_derive = true;
+        }
     }
 
     /// Close the open window (a client-side close). Keeps nothing — a re-open re-lists.
@@ -114,8 +130,7 @@ impl TrainerOpen {
         self.trainer_type = 0;
         self.greeting.clear();
         self.fresh_list = false;
-        // An in-flight refresh dies with the window: the next list is a real open, and must reset.
-        self.refresh_pending = false;
+        self.re_derive = false;
     }
 
     /// Disconnect: drop the open window (mirrors the gossip/merchant session clears).
@@ -130,10 +145,14 @@ impl TrainerOpen {
 #[derive(Resource, Default)]
 pub(crate) struct TrainerErrors(pub Vec<u32>);
 
+mod net;
+mod reeval;
+
 pub(crate) struct UiTrainerPlugin;
 
 impl Plugin for UiTrainerPlugin {
     fn build(&self, app: &mut App) {
+        net::register(app);
         app.init_resource::<TrainerOpen>()
             .init_resource::<TrainerErrors>()
             .add_systems(
@@ -143,7 +162,11 @@ impl Plugin for UiTrainerPlugin {
                     // push before the input pass so an open/close is on screen the same frame; drain
                     // after it (mirrors ui_merchant/ui_gossip).
                     close_npc_session_out_of_range::<TrainerOpen>.before(feed_trainer),
-                    feed_trainer.in_set(UiFeed),
+                    // After the unit feeds: the re-evaluator reads the pet bar (2333), which the
+                    // pet's old-target clear (a `UnitFeed` member) also writes — the same shape
+                    // `ui_script`'s demo feed takes. Either order reads the same pet spellbook;
+                    // the declaration is what the schedule ratchet asks for (2287).
+                    feed_trainer.in_set(UiFeed).after(crate::ui_unit::UnitFeed),
                     drain_trainer.after(UiInput),
                 ),
             );
@@ -152,9 +175,9 @@ impl Plugin for UiTrainerPlugin {
 
 /// A trainer refusal (`SMSG_TRAINER_BUY_FAILED`'s
 /// [`benilla_protocol::messages::train_fail`] code) is **silent on every player-facing surface**,
-/// and goes to the log instead. That is the reference's own behaviour, byte-carved rather than
-/// assumed (wow-re dispatch, 2026-09-07; handler `0x5e5f10`, registered at `0x5e3291`, arms at
-/// `0x5e5f95` / `0x5e5fb8` / `0x5e5fdc`, a code ≥ 3 doing nothing at all):
+/// and goes to the log instead. That is the reference's own behaviour (handler `0x5e5f10`,
+/// registered at `0x5e3291`, arms at `0x5e5f95` / `0x5e5fb8` / `0x5e5fdc`, a code ≥ 3 doing
+/// nothing at all):
 ///
 /// - there is **no GlobalStrings key and no message-catalog id** — the handler passes neither;
 /// - there is **no `DisplayError 0x496720` and no `0x4945b0`** anywhere in its body, so the line
@@ -229,11 +252,11 @@ fn resolve_service(
         met: skill_met,
     });
     // Each prerequisite ability is coloured by whether the player already KNOWS that specific spell —
-    // the byte-verified real-client mechanism (wow-re `system/ui/scratch/trainer-requirement.md`):
+    // the real-client mechanism (`0x4d96e0`):
     // `GetTrainerServiceAbilityReq`'s hasReq is `IsSpellKnown(reqSpellId)`, evaluated per-requirement
     // and INDEPENDENT of the service's overall category — so a spell gated only by LEVEL still shows
     // its already-learned prev-rank prerequisite WHITE, not red. The req id is a real ability id (not
-    // a learn wrapper — verified there too), so there's no hop: look it up directly. The name carries
+    // a learn wrapper), so there's no hop: look it up directly. The name carries
     // its rank exactly as the client does — `SpellDisplay::ranked_name`, the shared composer for the
     // client's `"%s (%s)"` literal (decision 2243). The client also ORs `KnownHigherRank`; benilla
     // has no rank chain, and sequential trainer ranks never reach that clause, so the direct
@@ -341,17 +364,33 @@ fn snapshot(
     })
 }
 
+/// **The re-evaluator's inputs and three of its triggers** (2333), bundled: the player's own
+/// descriptor (level, the skill slots) and its per-field edges (money, level, a skill slot —
+/// decision 2297), the pet bar, and the object index + stores that resolve the pet's descriptor.
+#[derive(SystemParam)]
+struct ReEvalInputs<'w, 's> {
+    self_player: Query<'w, 's, (Entity, &'static ObjectStore), With<SelfPlayer>>,
+    stores: Query<'w, 's, &'static ObjectStore>,
+    index: Res<'w, GuidIndex>,
+    pet_bar: Res<'w, crate::ui_pet::PetBar>,
+    edges: MessageReader<'w, 's, FieldChanged>,
+}
+
 /// Push the current trainer into the VM and fire the show/update/close events on a transition (or a
 /// content change). Diffed against a `Local` memory, exactly like the gossip/merchant feeds. A
 /// different trainer while the window is already open is a real close+open (the client's `ShowUIPanel`
 /// early-returns when visible, so the open sound only re-plays after a hide — decision 0096).
+#[allow(clippy::too_many_arguments)] // one Bevy system's full input set
 fn feed_trainer(
     script: Option<NonSendMut<UiScript>>,
-    // ResMut only to consume the fresh-packet latch below — the feed never authors trainer content.
+    // ResMut to consume the fresh-packet latch and to write the re-derived states (2333) — the
+    // states are the one piece of trainer content the client authors, exactly as the reference's
+    // `0x4d7d40` overwrites its own records.
     mut open: ResMut<TrainerOpen>,
     actions: Res<PlayerActions>,
     spells: Option<Res<Spells>>,
     skill_lines: Option<Res<SkillLines>>,
+    mut re_eval: ReEvalInputs,
     // A tradeskill trainer's rows front the CREATED ITEM's icon, so the feed needs the ask-once
     // template cache + `ItemDisplayInfo.dbc` — the tradeskill window's own pair ([`service_icon`]).
     icons: Option<Res<ItemDisplays>>,
@@ -394,6 +433,94 @@ fn feed_trainer(
         script.reset_trainer_list_state(open.trainer_type);
         open.fresh_list = false;
     }
+    // The descriptor-side triggers of the re-evaluator (2333): money, level, any skill slot, on
+    // the player's own object. Read every frame so the reader never backs up; they only matter
+    // while a window is open.
+    let self_player = re_eval.self_player.iter().next();
+    for edge in re_eval.edges.read() {
+        let Some((me, _)) = self_player else {
+            continue;
+        };
+        if edge.entity != me {
+            continue;
+        }
+        // The skill watchers (2336): the reference registers the VALUE word and the MAX and
+        // PERMBONUS words of every slot (`0x5de180`, `0x5de450`), not the id/step dword and not
+        // the temp bonus — so a slot's second dword always triggers and its third only when the
+        // high half (permBonus) moved.
+        let skill_edge = edge
+            .index
+            .checked_sub(FIELD_PLAYER_SKILL_INFO_1_1)
+            .filter(|&r| r < 3 * u16::from(PLAYER_SKILL_SLOTS))
+            .is_some_and(|r| match r % 3 {
+                1 => true,
+                2 => (edge.old ^ edge.new) & 0xFFFF_0000 != 0,
+                _ => false,
+            });
+        let player_field = edge.kind == benilla_protocol::messages::ObjectType::Player
+            && (edge.index == FIELD_PLAYER_FIELD_COINAGE || skill_edge);
+        if player_field || edge.unit_field(FIELD_UNIT_LEVEL) {
+            open.trigger_re_derive();
+        }
+    }
+    // The re-evaluation itself — `0x4d7d40` over every row, then `TRAINER_UPDATE` regardless of
+    // whether a state moved (its tail fires `0x136` unconditionally).
+    let forced = open.re_derive && open.trainer.is_some();
+    if forced {
+        open.re_derive = false;
+        let player = reeval::PlayerView {
+            known: actions.spells.clone(),
+            level: self_player
+                .and_then(|(_, store)| store.0.unit_level())
+                .unwrap_or(0),
+            skills: self_player
+                .map(|(_, store)| {
+                    (0..PLAYER_SKILL_SLOTS)
+                        .filter_map(|i| store.0.player_skill(i))
+                        .filter(|s| s.skill_id != 0)
+                        .map(|s| reeval::SkillSlot {
+                            skill_id: u32::from(s.skill_id),
+                            step: u32::from(s.step),
+                            // The permanent bonus rides only a non-zero value (`0x4d8087`'s
+                            // guard, the skill-pair reader's too).
+                            value_plus_perm: if s.value == 0 {
+                                0
+                            } else {
+                                i32::from(s.value) + i32::from(s.perm_bonus)
+                            },
+                        })
+                        .collect()
+                })
+                .unwrap_or_default(),
+            pet: (re_eval.pet_bar.spells.pet_guid != 0)
+                .then(|| re_eval.index.0.get(&re_eval.pet_bar.spells.pet_guid))
+                .flatten()
+                .and_then(|&e| re_eval.stores.get(e).ok())
+                .map(|store| reeval::PetView {
+                    level: store.0.unit_level().unwrap_or(0),
+                    known: re_eval
+                        .pet_bar
+                        .spells
+                        .spells
+                        .iter()
+                        .filter(|e| e.is_spell())
+                        .map(|e| e.action())
+                        .collect(),
+                }),
+        };
+        let TrainerOpen {
+            services,
+            trainer_type,
+            ..
+        } = &mut *open;
+        reeval::re_derive_all(
+            services,
+            *trainer_type,
+            &spells.catalog,
+            &skill_lines.catalog,
+            &player,
+        );
+    }
     let fresh = snapshot(
         &open,
         &spells.catalog,
@@ -422,7 +549,7 @@ fn feed_trainer(
         .and_then(|g| names.resolve(g, &commands).map(str::to_string));
     let name_changed = *last_name != trainer_name;
     let switched = npc_switched(*last_trainer, open.trainer);
-    if fresh == *last && !name_changed && !switched {
+    if fresh == *last && !name_changed && !switched && !forced {
         return;
     }
     script.set_trainer(fresh.clone());
diff --git a/crates/benilla-app/src/ui_trainer/net.rs b/crates/benilla-app/src/ui_trainer/net.rs
new file mode 100644
index 00000000..acb126f3
--- /dev/null
+++ b/crates/benilla-app/src/ui_trainer/net.rs
@@ -0,0 +1,129 @@
+//! The trainer window's packet handlers (decision 0237; in the net handler table since 2318,
+//! moved out of the drain's npc arm file) — the [`TrainerOpen`] session and the
+//! [`TrainerErrors`] line queue the trainer feed ([`super`]) reads.
+
+use benilla_protocol::messages::TrainerSpell;
+use benilla_protocol::{SessionEvent, SessionEventKind};
+use bevy::prelude::*;
+
+use super::{TrainerErrors, TrainerOpen};
+use crate::net::NetHandlerApp;
+
+/// Register the trainer handlers — called from [`super::UiTrainerPlugin`]. One per kind, plus
+/// the session-end listener.
+pub(super) fn register(app: &mut App) {
+    use SessionEventKind as K;
+    app.net_handler(K::TrainerList, on_list)
+        .net_handler(K::TrainerBuySucceeded, on_buy_succeeded)
+        .net_handler(K::TrainerBuyFailed, on_buy_failed)
+        // Five of the reference's twelve re-evaluation triggers arrive as packets (2333, 2336):
+        // a spell learned, removed or superseded, a spell modifier, and the pet's spellbook. Second handlers on the
+        // kind — the feed does the re-derivation later in the frame, so it reads the book as it
+        // is after every handler on the packet has run, whatever the registration order.
+        .net_handler(K::SpellLearned, on_spell_learned)
+        .net_handler(K::SpellRemoved, on_spell_removed)
+        .net_handler(K::SpellSuperceded, on_spell_superceded)
+        .net_handler(K::PetSpells, on_pet_spells)
+        .net_handler(K::SpellModifier, on_spell_modifier)
+        .net_handler(K::Disconnected, on_session_end);
+}
+
+/// A spell modifier arrived (`SMSG_SET_FLAT/PCT_SPELL_MODIFIER` — the reference's two "talent"
+/// callers, `0x6e999f`/`0x6e99bb`, 2336): the same re-derivation.
+fn on_spell_modifier(In(ev): In<SessionEvent>, mut trainer_open: ResMut<TrainerOpen>) {
+    if matches!(ev, SessionEvent::SpellModifier { .. }) {
+        trainer_open.trigger_re_derive();
+    }
+}
+
+/// A spell entered the book while a trainer is open (`0x5e9fb7`): re-derive on the next feed.
+fn on_spell_learned(In(ev): In<SessionEvent>, mut trainer_open: ResMut<TrainerOpen>) {
+    if matches!(ev, SessionEvent::SpellLearned { .. }) {
+        trainer_open.trigger_re_derive();
+    }
+}
+
+/// A spell left the book (`0x5ea25f`): the same.
+fn on_spell_removed(In(ev): In<SessionEvent>, mut trainer_open: ResMut<TrainerOpen>) {
+    if matches!(ev, SessionEvent::SpellRemoved { .. }) {
+        trainer_open.trigger_re_derive();
+    }
+}
+
+/// A rank replaced another: the book moved, so the "known at a higher rank" answers may have.
+fn on_spell_superceded(In(ev): In<SessionEvent>, mut trainer_open: ResMut<TrainerOpen>) {
+    if matches!(ev, SessionEvent::SpellSuperceded { .. }) {
+        trainer_open.trigger_re_derive();
+    }
+}
+
+/// The pet's spellbook arrived or changed (`0x4bdaf5`): a pet-spell service may have flipped.
+fn on_pet_spells(In(ev): In<SessionEvent>, mut trainer_open: ResMut<TrainerOpen>) {
+    if matches!(ev, SessionEvent::PetSpells(_)) {
+        trainer_open.trigger_re_derive();
+    }
+}
+
+fn on_list(In(ev): In<SessionEvent>, mut trainer_open: ResMut<TrainerOpen>) {
+    if let SessionEvent::TrainerList {
+        trainer,
+        trainer_type,
+        services,
+        greeting,
+    } = ev
+    {
+        trainer_list(trainer, trainer_type, services, greeting, &mut trainer_open);
+    }
+}
+
+fn on_buy_succeeded(In(ev): In<SessionEvent>) {
+    if let SessionEvent::TrainerBuySucceeded { trainer, spell_id } = ev {
+        trainer_buy_succeeded(trainer, spell_id);
+    }
+}
+
+fn on_buy_failed(In(ev): In<SessionEvent>, mut errors: ResMut<TrainerErrors>) {
+    if let SessionEvent::TrainerBuyFailed { error, .. } = ev {
+        trainer_buy_failed(error, &mut errors);
+    }
+}
+
+/// An open trainer window dies with the socket. A listener on the session end
+/// (a second handler on the kind, after the bridge's own teardown).
+fn on_session_end(In(_): In<SessionEvent>, mut trainer_open: ResMut<TrainerOpen>) {
+    trainer_open.clear_session();
+}
+
+/// A trainer's service list (`SMSG_TRAINER_LIST`): fill the [`TrainerOpen`] the trainer feed
+/// ([`super`]) reads.
+fn trainer_list(
+    trainer: u64,
+    trainer_type: u32,
+    services: Vec<TrainerSpell>,
+    greeting: String,
+    trainer_open: &mut TrainerOpen,
+) {
+    debug!(
+        "net: trainer {trainer:#x} (type {trainer_type}) listed {} services",
+        services.len()
+    );
+    trainer_open.open(trainer, trainer_type, services, greeting);
+}
+
+/// A trainer taught a service — confirmation only, and the reference **registers no handler for
+/// this opcode** (0x1B3 is absent from the 387 opcodes registered via `0x5ab650`/`0x537a60`).
+/// The spell itself lands via `SMSG_LEARNED_SPELL`, and that packet is one of the twelve triggers
+/// of the state re-evaluator ([`super::reeval`], decision 2333), which repaints the bought row
+/// green→gray and unlocks the next rank from the player's own book. Until 2333 benilla answered
+/// this packet by re-requesting the whole list — a round trip the reference never makes
+/// (VERIFIED vmangos `HandleTrainerBuySpellOpcode`: the server never resends on its own either),
+/// and the reason the player's filter kept dying on a purchase (B256). Logged, nothing more.
+fn trainer_buy_succeeded(trainer: u64, spell_id: u32) {
+    debug!("net: trainer {trainer:#x} taught spell {spell_id}");
+}
+
+/// A trainer refused a purchase — the trainer window's error line.
+fn trainer_buy_failed(error: u32, errors: &mut TrainerErrors) {
+    debug!("net: trainer buy failed (code {error})");
+    errors.0.push(error);
+}
diff --git a/crates/benilla-app/src/ui_trainer/reeval.rs b/crates/benilla-app/src/ui_trainer/reeval.rs
new file mode 100644
index 00000000..efcc4ce8
--- /dev/null
+++ b/crates/benilla-app/src/ui_trainer/reeval.rs
@@ -0,0 +1,216 @@
+//! **The trainer's state re-evaluator** — the reference's `0x4d7d40`, transcribed (decision 2333).
+//!
+//! The service `state` byte a trainer window shows is a wire value only on the **first** frame.
+//! The real client keeps twelve triggers on the open window — money, level, a skill change, a
+//! spell learned or removed, a talent, the pet's spellbook, and the two async spell-data callbacks
+//! — and each of them runs `0x4d7d40`, which **discards** every service's wire state and
+//! re-derives it from the player's own spellbook, skills, level and pet, then recounts the groups
+//! and fires `TRAINER_UPDATE`. It is *not* called by the builder or the
+//! packet handler, so a freshly opened window shows the server's bytes verbatim until the first
+//! trigger.
+//!
+//! Until 2333 benilla treated the wire state as durable and, on a purchase, asked the server for a
+//! fresh list — a round trip the reference never makes (it registers no handler for
+//! `SMSG_TRAINER_BUY_SUCCEEDED` at all) — so a level gained or a skill point earned with the window
+//! open left the rows stale. This module is the re-derivation; [`super::feed_trainer`] runs it on
+//! the same triggers and fires the same event.
+//!
+//! **What it deliberately reproduces:** the skill leg's not-found exit jumps *past* the state
+//! write (`0x4d8082` → `0x4d8123`), so a service whose required skill line the player does not
+//! hold at all comes out **green** — the opposite of the server's red. That is the 1.12 client's
+//! own behaviour, pinned by `a_skill_line_the_player_lacks_entirely_reads_green`, and the
+//! reason a fresh Blacksmithing recipe list can flip from red to green under a level-up without
+//! the player touching anything.
+//!
+//! **The whole law** (decision 2336):
+//! the admission gate, the two `trainerType == 1` writes of state 3, the pet-spell legs as early
+//! exits, the required-ability leg's pet variant, and the twelve triggers named to their
+//! handlers. What is not built is the one thing no vmangos server reaches: a type-1 (mount)
+//! trainer's layout, where a row re-derived to state 2 also has its group key severed
+//! (`0x4d82c1`) — noted, not transcribed, until that layout exists.
+
+use std::collections::BTreeSet;
+
+use benilla_formats::{LearnEffect, SkillLineCatalog, SpellCatalog};
+use benilla_protocol::messages::trainer_spell_state::{GRAY, GREEN, RED};
+use benilla_protocol::messages::TrainerSpell;
+
+/// The `trainerType` the reference gates its state-3 writes on (`ds:0xb73a08 == 1`).
+const TRAINER_TYPE_STATE_THREE: u32 = 1;
+/// The state the type-1 required-ability leg writes instead of RED (`0x4d83a4`): a row no filter
+/// can ever show (`SetTrainerServiceTypeFilter` sets bits 0/1/2 only, `0x4da390`).
+const HIDDEN: u8 = 3;
+
+/// One `PLAYER_SKILL_INFO` slot as the re-evaluator reads it: the line id, the step word
+/// (`+0x84a`) and `value + permBonus` (`+0x84c` + `+0x852`) — the bonus added only when the
+/// value is non-zero, the same guard the skill-pair reader `0x5ea460` has (verified, 2336).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) struct SkillSlot {
+    pub skill_id: u32,
+    pub step: u32,
+    pub value_plus_perm: i32,
+}
+
+/// The player's pet, when the bar names one whose object has streamed: its level and its own
+/// spellbook (the `IsSpellKnown` pet path scans the pet's book, not the player's).
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub(super) struct PetView {
+    pub level: u32,
+    pub known: BTreeSet<u32>,
+}
+
+/// Everything `0x4d7d40` reads off the player, gathered once per re-evaluation.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub(super) struct PlayerView {
+    /// The player's known-spell set (`[0xb710fc]`'s bitmap).
+    pub known: BTreeSet<u32>,
+    /// `UNIT_FIELD_LEVEL`.
+    pub level: u32,
+    /// The occupied `PLAYER_SKILL_INFO` slots.
+    pub skills: Vec<SkillSlot>,
+    /// The pet, or `None` — "no pet" is itself a verdict for a pet-spell service.
+    pub pet: Option<PetView>,
+}
+
+impl PlayerView {
+    fn skill(&self, skill_id: u32) -> Option<&SkillSlot> {
+        self.skills.iter().find(|s| s.skill_id == skill_id)
+    }
+}
+
+/// `IsSpellKnown(unit, id) || KnownHigherRank(unit, id)` — `0x60c740` OR `0x60c8d0`, against
+/// whichever unit's book `known` is.
+fn known_or_higher(id: u32, known: &BTreeSet<u32>, skill_lines: &SkillLineCatalog) -> bool {
+    known.contains(&id) || skill_lines.higher_rank_known(id, known)
+}
+
+/// Re-derive one service's state byte from the player, as `0x4d7d40` does per row. The wire
+/// state is an input only through the admission gate: a row whose wire spell has no `Spell.dbc`
+/// record is skipped whole and keeps it (`0x4d7dcd` → next row); every other row restarts at 0
+/// (`0x4d7dec`).
+pub(super) fn re_derive(
+    wire: &TrainerSpell,
+    trainer_type: u32,
+    spells: &SpellCatalog,
+    skill_lines: &SkillLineCatalog,
+    player: &PlayerView,
+) -> u8 {
+    // 0 · the admission gate.
+    if spells.get(wire.spell).is_none() {
+        return wire.state;
+    }
+    // 1 · the wire state is discarded; the state restarts at 0.
+    let mut state = GREEN;
+    // 2 · per learn effect of the WIRE spell, in slot order; every write overwrites the last.
+    let mut learn_effects = 0u32;
+    let mut known_effects = 0u32;
+    // The row's LEARN_SPELL target (`[ebp-0x28]`) and the pet its LEARN_PET_SPELL resolved
+    // (`[ebp-0x18]`) — both read again by the required-ability leg.
+    let mut taught: Option<u32> = None;
+    let mut pet_resolved: Option<&PetView> = None;
+    for effect in spells.learn_effects(wire.spell) {
+        match *effect {
+            LearnEffect::Spell(t) => {
+                learn_effects += 1;
+                taught = Some(t);
+                if trainer_type == TRAINER_TYPE_STATE_THREE
+                    && skill_lines.higher_rank_known(t, &player.known)
+                {
+                    // `0x4d7e3e`: at a type-1 trainer a rank the player has already passed is
+                    // hidden outright — counted as a learn effect, never as a known one, so
+                    // step 3 cannot turn it into 2.
+                    state = HIDDEN;
+                } else if known_or_higher(t, &player.known, skill_lines) {
+                    known_effects += 1;
+                }
+            }
+            LearnEffect::SkillStep { skill, step } => {
+                // The player's step word for that line against the effect's value (`0x4d7f17`);
+                // no slot for the line ⇒ no write (`0x4d7ecf`).
+                if player.skill(skill).is_some_and(|s| s.step >= step) {
+                    state = GRAY;
+                }
+            }
+            LearnEffect::PetSpell(t) => {
+                learn_effects += 1;
+                // No pet ⇒ unavailable (`0x4d803c`), and the loop ends there.
+                let Some(pet) = &player.pet else {
+                    state = RED;
+                    break;
+                };
+                pet_resolved = Some(pet);
+                if known_or_higher(t, &pet.known, skill_lines) {
+                    // Known by the PET (`IsSpellKnown`'s pet path scans the pet's book).
+                    known_effects += 1;
+                } else if wire.req_level > 1 && pet.level < u32::from(wire.req_level) {
+                    // A pet below the row's level ⇒ unavailable (`0x4d7fac`), loop ends.
+                    state = RED;
+                    break;
+                }
+            }
+        }
+    }
+    // 3 · every learn effect known ⇒ known (`0x4d7fc6`), over whatever the loop left.
+    if learn_effects > 0 && known_effects == learn_effects {
+        state = GRAY;
+    }
+    // 4 · only while still 0: the skill leg. A slot for the line, below the requirement ⇒
+    //     unavailable (`0x4d811f`); NO slot ⇒ no write at all (`0x4d8082` jumps past it) — the
+    //     reference's own green-for-a-skill-you-lack.
+    if state == GREEN && wire.req_skill != 0 {
+        if let Some(slot) = player.skill(wire.req_skill) {
+            if slot.value_plus_perm < wire.req_skill_value as i32 {
+                state = RED;
+            }
+        }
+    }
+    // 5 · still 0: the required abilities, against the PET's book when the row resolved one
+    //     (`0x4d81c4`) and the player's otherwise; the first missing one decides. On the pet the
+    //     verdict is always unavailable (`0x4d8204`). On the player at a type-1 trainer it is the
+    //     hidden state (`0x4d83a4`) when the missing ability is exactly the rank before what the
+    //     row teaches — `SkillLineAbility.forward(missing) == taught` — and unavailable
+    //     (`0x4d83ad`) for any other missing ability.
+    if state == GREEN {
+        let (book, on_pet) = match pet_resolved {
+            Some(pet) => (&pet.known, true),
+            None => (&player.known, false),
+        };
+        let missing = wire
+            .req_spells
+            .iter()
+            .copied()
+            .filter(|&id| id != 0)
+            .find(|&id| !known_or_higher(id, book, skill_lines));
+        if let Some(missing) = missing {
+            let previous_rank_of_taught =
+                taught.is_some_and(|t| skill_lines.rank_successor(missing) == Some(t));
+            state =
+                if !on_pet && trainer_type == TRAINER_TYPE_STATE_THREE && previous_rank_of_taught {
+                    HIDDEN
+                } else {
+                    RED
+                };
+        }
+    }
+    //     Still 0: a level requirement above 1 the player has not reached (`0x4d8239`); no
+    //     trainer-type variant.
+    if state == GREEN && wire.req_level > 1 && player.level < u32::from(wire.req_level) {
+        state = RED;
+    }
+    state
+}
+
+/// Re-derive every listed service in place — the whole of `0x4d7d40`'s per-row pass. The group
+/// recount the reference does next (`0x4d8260`–`0x4d83c9`) is the engine's, synthesized from the
+/// pushed states (`benilla_ui::script::trainer`), so nothing is counted here.
+pub(super) fn re_derive_all(
+    services: &mut [TrainerSpell],
+    trainer_type: u32,
+    spells: &SpellCatalog,
+    skill_lines: &SkillLineCatalog,
+    player: &PlayerView,
+) {
+    for wire in services.iter_mut() {
+        wire.state = re_derive(wire, trainer_type, spells, skill_lines, player);
+    }
+}
diff --git a/crates/benilla-app/src/ui_trainer/tests.rs b/crates/benilla-app/src/ui_trainer/tests.rs
index 481b5e3a..4d230623 100644
--- a/crates/benilla-app/src/ui_trainer/tests.rs
+++ b/crates/benilla-app/src/ui_trainer/tests.rs
@@ -86,7 +86,7 @@ fn snap(open: &TrainerOpen, spells: &SpellCatalog) -> Option<TrainerState> {
     )
 }
 
-/// The icon law's fixture (wow-re `spell-icon-substitution-law.md` §1's shape, synthetic so
+/// The icon law's fixture (`GetTrainerServiceIcon 0x4d8f50`'s shape, synthetic so
 /// every gate is reachable): wrapper 100 teaches 200 via a slot-0 `LEARN_SPELL`; 200 creates
 /// item 777; item 777's display 5 carries the "real" art. Each spell has a DISTINCT icon so a
 /// wrong arm is named by the assertion, not merely unequal.
@@ -255,7 +255,7 @@ fn trainer_icon_is_nil_until_the_product_template_lands_and_asks_once() {
     );
 }
 
-/// The director's exact case on the real shipped `Spell.dbc` — the check wow-re's §7 pins:
+/// The director's exact case on the real shipped `Spell.dbc` (`GetTrainerServiceIcon 0x4d8f50`):
 /// spell 2756 is the wrapper a Blacksmithing trainer sends, 2739 the recipe it teaches, 2847 the
 /// sword. At a tradeskill trainer the law must reach for item 2847; at a class trainer it must
 /// serve 2756's own icon. Skips without client data.
@@ -455,7 +455,7 @@ fn resolve_reads_cost_state_and_gates_with_no_catalog() {
 }
 
 /// A prerequisite ability's met/unmet is per-gate — whether the player KNOWS that spell — and is
-/// decoupled from the service's overall category (wow-re `system/ui/scratch/trainer-requirement.md`).
+/// decoupled from the service's overall category (`GetTrainerServiceAbilityReq 0x4d96e0`).
 /// The director's exact case: an UNAVAILABLE spell (gated by level) whose already-learned prev-rank
 /// prerequisite must still read met (white), not red. Deterministic (no client data needed).
 #[test]
@@ -695,18 +695,15 @@ fn tooltip_falls_back_to_the_wire_spell() {
     );
 }
 
-/// **B256 — the state filter died on every purchase.** The reset the reference's list builder does
-/// per packet (`0x4d75d9`, decision 1128) is only ever observable there at a window *opening*: the
-/// reference never receives a list packet with the window already up, because it repaints a purchase
-/// from a client-side state re-derivation (`0x4d7d40`). benilla has no such re-derivation and asks
-/// the server for a fresh list after every buy — so our synthetic packet was dragging a reset along
-/// that the reference cannot produce, and the player's "Available only" came back as
-/// available+unavailable the moment they learned a spell (their collapsed groups went with it).
-///
-/// So [`TrainerOpen::fresh_list`] means *this packet begins a window session*, and the post-buy
-/// re-request marks its own answer as the repaint it is. The four cases below are the whole law.
+/// **Every list packet begins a window session.** The reset the reference's list builder does
+/// per packet (`0x4d75d9`, decision 1128) is only ever observable at a window *opening*, because
+/// the reference never receives a list packet with the window already up: a purchase, a level, a
+/// skill point repaint the open window through the state re-evaluator (`0x4d7d40`,
+/// [`super::reeval`], decision 2333), never through a second list. Since 2333 benilla is the
+/// same — the post-buy re-request that B256's "refresh" mark existed to tell apart is gone — so
+/// the law is one line: a list packet opens, and opening resets.
 #[test]
-fn only_a_packet_that_opens_a_window_resets_the_filter() {
+fn every_list_packet_begins_a_window_session() {
     const TRAINER: u64 = 0xabc;
     let list = || vec![wire(1, trainer_spell_state::GREEN, 10, 1, 0)];
     let mut open = TrainerOpen::default();
@@ -715,37 +712,410 @@ fn only_a_packet_that_opens_a_window_resets_the_filter() {
     assert!(open.fresh_list, "a first list opens the window: reset");
     open.fresh_list = false; // the feed consumes it
 
-    // The post-buy re-request (`net::apply::npc::trainer_buy_succeeded`) marks its own answer.
-    open.refresh_pending = true;
-    open.open(TRAINER, 0, list(), "Greetings".into());
-    assert!(
-        !open.fresh_list,
-        "our own re-list repaints the open window — the player's filter and collapse stand"
-    );
-    assert!(
-        !open.refresh_pending,
-        "and the mark is spent, so the NEXT packet is a real open again"
-    );
-
     open.open(TRAINER, 0, list(), "Greetings".into());
     assert!(
         open.fresh_list,
-        "an unmarked packet is always a session start"
+        "the same trainer's list again is a session start again"
     );
 
-    // A refresh that never came back must not eat a later open's reset: the close spends it.
-    open.refresh_pending = true;
+    // A pending re-derivation never survives a list: the packet carries the server's own states.
+    open.fresh_list = false;
+    open.trigger_re_derive();
+    assert!(open.re_derive);
+    open.open(TRAINER, 0, list(), "Greetings".into());
+    assert!(
+        !open.re_derive,
+        "a fresh list is the server's states — nothing pending against it"
+    );
+
+    // And a trigger with no window open is nothing at all (`0x4d7d46`'s early-out).
     open.clear();
-    open.open(TRAINER, 0, list(), "Greetings".into());
-    assert!(open.fresh_list, "a close drops any in-flight refresh mark");
+    open.trigger_re_derive();
+    assert!(!open.re_derive);
+}
 
-    // Nor may a mark meant for one trainer be spent by another's list.
-    open.refresh_pending = true;
-    open.open(TRAINER + 1, 0, list(), "Greetings".into());
-    assert!(
-        open.fresh_list,
-        "a different trainer is a new window whatever is in flight"
-    );
+mod re_derive {
+    //! The state re-evaluator's clauses ([`super::super::reeval`]), one test per leg of
+    //! `0x4d7d40`, on synthetic catalogs.
+    use super::super::reeval::{re_derive, PetView, PlayerView, SkillSlot};
+    use super::*;
+    use benilla_formats::{LearnEffect, SlaInfo, SpellDisplay};
+    use std::collections::HashMap;
+
+    const BLACKSMITHING: u32 = 164;
+    /// Wrapper 2020 teaches 2018 and steps Blacksmithing to 1 — the real openers' shape.
+    const OPENER: u32 = 2020;
+    const TAUGHT: u32 = 2018;
+    /// A class ability wrapper: rank 1 teaches 100, rank 2 teaches 101 (100 → 101 by
+    /// `forward_spellid`), no skill step.
+    const RANK1_WRAPPER: u32 = 500;
+    const RANK1: u32 = 100;
+    const RANK2: u32 = 101;
+    /// A pet wrapper: teaches the pet 300.
+    const PET_WRAPPER: u32 = 700;
+    const PET_SPELL: u32 = 300;
+
+    /// A rank-2 wrapper: teaches RANK2 (whose previous rank is RANK1).
+    const RANK2_WRAPPER: u32 = 501;
+
+    fn catalog() -> SpellCatalog {
+        // Every wrapper has a record — the admission gate (`0x4d7dcd`) skips a row without one.
+        let displays = [OPENER, RANK1_WRAPPER, RANK2_WRAPPER, PET_WRAPPER]
+            .into_iter()
+            .map(|id| (id, SpellDisplay::default()))
+            .collect();
+        SpellCatalog::from_displays_and_effects(
+            displays,
+            HashMap::from([
+                (
+                    OPENER,
+                    vec![
+                        LearnEffect::Spell(TAUGHT),
+                        LearnEffect::SkillStep {
+                            skill: BLACKSMITHING,
+                            step: 1,
+                        },
+                    ],
+                ),
+                (RANK1_WRAPPER, vec![LearnEffect::Spell(RANK1)]),
+                (RANK2_WRAPPER, vec![LearnEffect::Spell(RANK2)]),
+                (PET_WRAPPER, vec![LearnEffect::PetSpell(PET_SPELL)]),
+            ]),
+        )
+    }
+
+    fn skill_lines() -> SkillLineCatalog {
+        let row = |skill_id, forward| SlaInfo {
+            skill_id,
+            req_skill_value: 0,
+            forward_spell_id: forward,
+            trivial_low: 0,
+            trivial_high: 0,
+        };
+        SkillLineCatalog::from_abilities([(RANK1, row(1, RANK2)), (RANK2, row(1, 0))])
+    }
+
+    fn service(spell: u32) -> TrainerSpell {
+        // The WIRE state is RED on purpose: every case below must ignore it (`0x4d7dec`).
+        let mut w = wire(spell, trainer_spell_state::RED, 10, 1, 0);
+        w.req_skill_value = 0;
+        w
+    }
+
+    fn player() -> PlayerView {
+        PlayerView {
+            known: BTreeSet::new(),
+            level: 10,
+            skills: Vec::new(),
+            pet: None,
+        }
+    }
+
+    fn state(wire: &TrainerSpell, trainer_type: u32, player: &PlayerView) -> u8 {
+        re_derive(wire, trainer_type, &catalog(), &skill_lines(), player)
+    }
+
+    #[test]
+    fn the_wire_state_is_discarded_and_a_met_service_reads_green() {
+        assert_eq!(
+            state(&service(RANK1_WRAPPER), 0, &player()),
+            trainer_spell_state::GREEN
+        );
+    }
+
+    #[test]
+    fn every_learn_effect_known_reads_gray() {
+        let mut p = player();
+        p.known.insert(RANK1);
+        assert_eq!(
+            state(&service(RANK1_WRAPPER), 0, &p),
+            trainer_spell_state::GRAY
+        );
+    }
+
+    #[test]
+    fn a_higher_known_rank_counts_as_known() {
+        // Rank 2 in the book, rank 1 offered: `KnownHigherRank` (0x60c8d0) says known.
+        let mut p = player();
+        p.known.insert(RANK2);
+        assert_eq!(
+            state(&service(RANK1_WRAPPER), 0, &p),
+            trainer_spell_state::GRAY
+        );
+    }
+
+    #[test]
+    fn a_skill_step_the_player_already_holds_reads_gray() {
+        let mut p = player();
+        p.skills.push(SkillSlot {
+            skill_id: BLACKSMITHING,
+            step: 1,
+            value_plus_perm: 1,
+        });
+        assert_eq!(state(&service(OPENER), 0, &p), trainer_spell_state::GRAY);
+    }
+
+    #[test]
+    fn a_skill_line_below_the_requirement_reads_red() {
+        // A recipe-shaped service: a plain learn wrapper with a skill requirement. (An OPENER
+        // would read gray here — the player already holds the step it teaches.)
+        let mut w = service(RANK1_WRAPPER);
+        w.req_skill = BLACKSMITHING;
+        w.req_skill_value = 75;
+        let mut p = player();
+        p.skills.push(SkillSlot {
+            skill_id: BLACKSMITHING,
+            step: 1,
+            value_plus_perm: 40,
+        });
+        assert_eq!(state(&w, 0, &p), trainer_spell_state::RED);
+        // Met (value + permanent bonus reaches it): the leg leaves the state alone.
+        p.skills[0].value_plus_perm = 75;
+        assert_eq!(state(&w, 0, &p), trainer_spell_state::GREEN);
+    }
+
+    /// The reference's own wart (`0x4d8082`): the skill scan's not-found exit jumps past the
+    /// compare, so a line the player lacks entirely writes nothing — green, where the server sends
+    /// red.
+    #[test]
+    fn a_skill_line_the_player_lacks_entirely_reads_green() {
+        let mut w = service(RANK1_WRAPPER);
+        w.req_skill = BLACKSMITHING;
+        w.req_skill_value = 75;
+        assert_eq!(state(&w, 0, &player()), trainer_spell_state::GREEN);
+    }
+
+    #[test]
+    fn an_unknown_required_ability_reads_red_or_hidden_at_type_one() {
+        // The opener (its taught spell unknown, no skill slot held) with a prerequisite ability.
+        let mut w = service(OPENER);
+        w.req_spells = [RANK1, 0, 0];
+        assert_eq!(state(&w, 0, &player()), trainer_spell_state::RED);
+        assert_eq!(state(&w, 2, &player()), trainer_spell_state::RED);
+        // Trainer type 1 too: RANK1 is not the rank before TAUGHT, so this is a plain miss, not
+        // the hidden state (`0x4d83a4`'s extra conjunct — `a_missing_previous_rank_…` pins it).
+        assert_eq!(state(&w, 1, &player()), trainer_spell_state::RED);
+        // Known — or known at a higher rank — satisfies it.
+        let mut p = player();
+        p.known.insert(RANK2);
+        assert_eq!(state(&w, 0, &p), trainer_spell_state::GREEN);
+        let mut p = player();
+        p.known.insert(RANK1);
+        assert_eq!(state(&w, 1, &p), trainer_spell_state::GREEN);
+    }
+
+    #[test]
+    fn a_level_requirement_above_one_gates_on_the_players_level() {
+        let mut w = service(RANK1_WRAPPER);
+        w.req_level = 20;
+        assert_eq!(state(&w, 0, &player()), trainer_spell_state::RED);
+        let mut p = player();
+        p.level = 20;
+        assert_eq!(state(&w, 0, &p), trainer_spell_state::GREEN);
+        // `req_level <= 1` is not a gate at all (`row[+0x14] > 1`).
+        w.req_level = 1;
+        let mut p = player();
+        p.level = 0;
+        assert_eq!(state(&w, 0, &p), trainer_spell_state::GREEN);
+    }
+
+    #[test]
+    fn a_pet_spell_needs_a_pet_of_the_rows_level_and_reads_off_the_pets_book() {
+        let mut w = service(PET_WRAPPER);
+        w.req_level = 12;
+        // The row's level binds the player too (`0x4d8239`); keep the player clear of it so the
+        // pet legs are what decides.
+        let player = || PlayerView {
+            level: 20,
+            ..player()
+        };
+        assert_eq!(state(&w, 3, &player()), trainer_spell_state::RED, "no pet");
+        let mut p = player();
+        p.pet = Some(PetView {
+            level: 11,
+            known: BTreeSet::new(),
+        });
+        assert_eq!(
+            state(&w, 3, &p),
+            trainer_spell_state::RED,
+            "pet below the row's level"
+        );
+        p.pet = Some(PetView {
+            level: 12,
+            known: BTreeSet::new(),
+        });
+        assert_eq!(state(&w, 3, &p), trainer_spell_state::GREEN);
+        // Known by the PET, not the player: gray.
+        p.pet = Some(PetView {
+            level: 12,
+            known: BTreeSet::from([PET_SPELL]),
+        });
+        assert_eq!(state(&w, 3, &p), trainer_spell_state::GRAY);
+        p.known.insert(PET_SPELL);
+        p.pet = Some(PetView {
+            level: 12,
+            known: BTreeSet::new(),
+        });
+        assert_eq!(
+            state(&w, 3, &p),
+            trainer_spell_state::GREEN,
+            "the player's own book is not the pet's"
+        );
+    }
+
+    #[test]
+    fn the_legs_run_in_the_references_order() {
+        // A known service with an unmet skill line and an unmet level is GRAY: legs 4 and 5 run
+        // only while the state is still 0.
+        let mut w = service(OPENER);
+        w.req_skill = BLACKSMITHING;
+        w.req_skill_value = 300;
+        w.req_level = 60;
+        let mut p = player();
+        p.known.insert(TAUGHT);
+        p.skills.push(SkillSlot {
+            skill_id: BLACKSMITHING,
+            step: 1,
+            value_plus_perm: 1,
+        });
+        assert_eq!(state(&w, 2, &p), trainer_spell_state::GRAY);
+    }
+
+    /// The admission gate (`0x4d7dcd`): a wire spell with no `Spell.dbc` record is skipped
+    /// whole — its wire state stands, whatever the player has.
+    #[test]
+    fn a_row_without_a_spell_record_keeps_its_wire_state() {
+        let w = wire(999_999, trainer_spell_state::RED, 10, 1, 0);
+        assert_eq!(state(&w, 0, &player()), trainer_spell_state::RED);
+        let w = wire(999_999, trainer_spell_state::GRAY, 10, 1, 0);
+        assert_eq!(state(&w, 0, &player()), trainer_spell_state::GRAY);
+    }
+
+    /// `0x4d7e3e`: at a type-1 trainer, a rank the player has already passed is hidden — and it
+    /// is counted as a learn effect but never as a known one, so it cannot come back as gray.
+    #[test]
+    fn a_higher_rank_known_at_a_type_one_trainer_hides_the_row() {
+        let mut p = player();
+        p.known.insert(RANK2);
+        assert_eq!(state(&service(RANK1_WRAPPER), 1, &p), 3);
+        assert_eq!(
+            state(&service(RANK1_WRAPPER), 0, &p),
+            trainer_spell_state::GRAY
+        );
+        // Knowing exactly the taught rank is not "higher": gray at every type.
+        let mut p = player();
+        p.known.insert(RANK1);
+        assert_eq!(
+            state(&service(RANK1_WRAPPER), 1, &p),
+            trainer_spell_state::GRAY
+        );
+    }
+
+    /// `0x4d83a4`: the type-1 hidden state on the required-ability leg needs the missing ability
+    /// to be exactly the rank before what the row teaches; any other missing ability is plain
+    /// unavailable, and so is every miss at every other type.
+    #[test]
+    fn a_missing_previous_rank_at_a_type_one_trainer_hides_the_row() {
+        let mut w = service(RANK2_WRAPPER);
+        w.req_spells = [RANK1, 0, 0];
+        assert_eq!(
+            state(&w, 1, &player()),
+            3,
+            "the missing ability is the previous rank"
+        );
+        assert_eq!(state(&w, 0, &player()), trainer_spell_state::RED);
+        let mut w = service(RANK2_WRAPPER);
+        w.req_spells = [RANK1 + 500, 0, 0];
+        assert_eq!(
+            state(&w, 1, &player()),
+            trainer_spell_state::RED,
+            "an unrelated ability"
+        );
+    }
+
+    /// The pet-spell legs are early exits: nothing after a missing or under-level pet is
+    /// visited (`0x4d803c`/`0x4d7fac` leave the loop), and a pet that KNOWS the spell is never
+    /// level-tested at all.
+    #[test]
+    fn the_pet_legs_leave_the_loop_and_a_knowing_pet_skips_the_level_test() {
+        let spells = SpellCatalog::from_displays_and_effects(
+            HashMap::from([(PET_WRAPPER, SpellDisplay::default())]),
+            HashMap::from([(
+                PET_WRAPPER,
+                vec![
+                    LearnEffect::PetSpell(PET_SPELL),
+                    LearnEffect::SkillStep {
+                        skill: BLACKSMITHING,
+                        step: 1,
+                    },
+                ],
+            )]),
+        );
+        let mut w = service(PET_WRAPPER);
+        w.req_level = 12;
+        let mut p = player();
+        p.level = 20;
+        p.skills.push(SkillSlot {
+            skill_id: BLACKSMITHING,
+            step: 1,
+            value_plus_perm: 1,
+        });
+        // No pet: the step effect after it is never reached, so the row stays unavailable.
+        assert_eq!(
+            re_derive(&w, 3, &spells, &skill_lines(), &p),
+            trainer_spell_state::RED
+        );
+        // A pet that knows the spell, below the row's level: known, not level-tested.
+        p.pet = Some(PetView {
+            level: 5,
+            known: BTreeSet::from([PET_SPELL]),
+        });
+        assert_eq!(
+            re_derive(&w, 3, &spells, &skill_lines(), &p),
+            trainer_spell_state::GRAY
+        );
+    }
+
+    /// The required-ability leg runs on the PET's book when the row resolved a pet, and its
+    /// failure is unavailable at every trainer type — the type-1 hidden state is the player
+    /// variant's alone.
+    #[test]
+    fn a_pet_rows_required_abilities_are_the_pets_and_never_hide() {
+        let mut w = service(PET_WRAPPER);
+        w.req_spells = [RANK1, 0, 0];
+        let mut p = player();
+        p.level = 20;
+        p.known.insert(RANK1); // the PLAYER knows it — irrelevant for a pet row
+        p.pet = Some(PetView {
+            level: 20,
+            known: BTreeSet::new(),
+        });
+        assert_eq!(state(&w, 3, &p), trainer_spell_state::RED);
+        assert_eq!(
+            state(&w, 1, &p),
+            trainer_spell_state::RED,
+            "no hidden state on the pet path"
+        );
+        p.pet = Some(PetView {
+            level: 20,
+            known: BTreeSet::from([RANK2]),
+        });
+        assert_eq!(
+            state(&w, 3, &p),
+            trainer_spell_state::GREEN,
+            "the pet knows a higher rank"
+        );
+    }
+
+    #[test]
+    fn re_derive_all_rewrites_every_row_in_place() {
+        let mut list = vec![service(RANK1_WRAPPER), service(OPENER)];
+        let mut p = player();
+        p.known.insert(RANK1);
+        super::super::reeval::re_derive_all(&mut list, 0, &catalog(), &skill_lines(), &p);
+        assert_eq!(list[0].state, trainer_spell_state::GRAY);
+        assert_eq!(list[1].state, trainer_spell_state::GREEN);
+    }
 }
 
 /// The three group-header keys against the player's REAL `GlobalStrings.lua` — the guard the
diff --git a/crates/benilla-app/src/ui_unit.rs b/crates/benilla-app/src/ui_unit.rs
index 7747952c..2be4b53b 100644
--- a/crates/benilla-app/src/ui_unit.rs
+++ b/crates/benilla-app/src/ui_unit.rs
@@ -55,13 +55,13 @@ use crate::ui_script::{gate, UiInput};
 pub(crate) struct UnitFeed;
 
 /// One combat occurrence over a unit — the `UNIT_COMBAT` event feed (decision 0576: the portrait
-/// hit indicator's wire; the shipped `CombatFeedback.lua` is the consumer). **§5-verified**
-/// (wow-re `object-layer/scratch/unit-combat-event-law.md`): the one emitter `0x494600` fires
+/// hit indicator's wire; the shipped `CombatFeedback.lua` is the consumer). The one emitter
+/// `0x494600` fires
 /// `(token, action, descriptor, amount, type)` once per live token the unit maps to, with **no
 /// self-suppression and no cvar gate** — the worldtext Gate A's inverse. `type` (arg5) is the
 /// damage school on the melee/spell-damage paths; the miss and heal wrappers hard-code 0. The
 /// melee victim event is **deferred to the swing impact keyframe** (it rides inside `0x6243e0`,
-/// reached only from the `0x624530` victim dispatcher — C2 CONFIRMED). ENERGIZE never fires in
+/// reached only from the `0x624530` victim dispatcher). ENERGIZE never fires in
 /// 5875 (string absent binary-wide). Producers: melee at [`melee_unit_combat`], spells/heals at
 /// packet receive (`net/apply/combat_log.rs`). Consumed by [`fire_unit_combat`], which resolves
 /// the entity to its live unit tokens.
@@ -80,8 +80,7 @@ pub(crate) struct UnitCombatFeedback {
 }
 
 /// One center-combat-text message — the `COMBAT_TEXT_UPDATE` event feed (decision 0578; the
-/// Blizzard_CombatText transcription is the consumer). **§5-verified** (wow-re
-/// `playername/scratch/combat-text-update-emission-law.md`): event id 0x21E, fired via the
+/// Blizzard_CombatText transcription is the consumer). Event id 0x21E, fired via the
 /// formatted SignalEvent `0x703f50` from the UnitCombatLog_C.cpp emit helpers — every producer
 /// fires **at packet parse** (the melee one too: `0x6255b0 → 0x629d30`, one call stack — NOT the
 /// impact-keyframe deferral, which belongs to the worldtext/UNIT_COMBAT victim dispatch).
@@ -101,22 +100,22 @@ pub(crate) struct CombatTextEvent {
 ///
 /// **`PLAYER_LEAVING_WORLD` on a cross-map worldport** (decision 2235, corrected by 2238).
 ///
-/// The reference fires event `0x111` at `0x490b48`, inside `0x490a80`. wow-re's census of both
+/// The reference fires event `0x111` at `0x490b48`, inside `0x490a80`. A census of both
 /// signal helpers puts the id at exactly one site image-wide — 336/336 ids resolved through
 /// `0x703e50`, 149/149 through `0x703f50`, and the encoding `b9 11 01 00 00` occurs once in the
 /// binary — so that is the whole of the FIRE, and it is what this doc used to conflate with the
 /// whole of the event.
 ///
-/// **One fire site, three callers, and this system is one of them** (2238; wow-re `5ad31a12`).
+/// **One fire site, three callers, and this system is one of them** (2238).
 /// `0x490a80` is reached from the local player object's own destructor (`0x401bc0` → `0x467700`
 /// → `0x467800` → the per-object `[vtbl+0]` → `0x5dd500` → `0x5dd600` → `0x5dd72c` → `0x5dd543`)
 /// — **this system's occasion** — and also from `0x490c20` inside the shutdown tail `0x490bd0`,
 /// which is where an in-world `/reload`, a logout, a quit and a disconnect reach it, and from
 /// `0x5e9b5a`, vtable slot 1, on a DESTROY / OUT_OF_RANGE of the local player object.
-/// 2235 read `5ce96437`'s "three gates" as three gates on the event and its subject line as a
-/// census of the callers; neither is what they were. Two of those gates (`0x5dd71c`/`0x5dd721`/
-/// `0x5dd725` and `0x5dd539`/`0x5dd53e`/`0x5dd541`) sit in the destructor chain and gate only the
-/// caller below; `0x490a80`'s own only gate is the latch at `[0xb4b424]`.
+/// 2235 read the "three gates" as three gates on the event, which they are not. Two of those
+/// gates (`0x5dd71c`/`0x5dd721`/`0x5dd725` and `0x5dd539`/`0x5dd53e`/`0x5dd541`) sit in the
+/// destructor chain and gate only the caller below; `0x490a80`'s own only gate is the latch at
+/// `[0xb4b424]`.
 ///
 /// **The tail's occasions are already ours**, and were years before this system existed:
 /// [`crate::ui_script::shutdown_ui_state`] fires `PLAYER_LEAVING_WORLD` then `PLAYER_LOGOUT` as
@@ -141,8 +140,8 @@ pub(crate) struct CombatTextEvent {
 /// handler runs *during* teardown, after the three manager unlinks and ~35 of `0x490a80`'s 37
 /// teardown calls, so a real addon's handler already sees a substantially dismantled UI.
 ///
-/// **What "dismantled" costs there is the opposite of what 2235 guessed** (2238; wow-re
-/// `20210d32`). The GUID hash's link is `obj+0x1c` and the destructor splices the object out
+/// **What "dismantled" costs there is the opposite of what 2235 guessed** (2238). The GUID
+/// hash's link is `obj+0x1c` and the destructor splices the object out
 /// (`0x467887 call 0x468680`) *before* `call [vtbl+0]`, so on THIS occasion — and only this one —
 /// a hash lookup misses. But `UnitName("player")` never asks the hash: `0x517020` short-circuits
 /// at `0x51707d` and answers from the cached character record `[0xc27d88]`, which has one writer
@@ -242,7 +241,8 @@ struct UnitFeedMemo {
     /// would snap the value back to the stale descriptor in between.
     worn_hidden: Option<(bool, bool)>,
     /// The self player's last-pushed `PLAYER_FIELD_BYTES` byte 2 — the four extra bars' visibility
-    /// (wow-re `action-bar-toggles.md`). A player-global like the combo pair, pushed on the edge.
+    /// (read by `GetActionBarToggles 0x4e7660`). A player-global like the combo pair, pushed on the
+    /// edge.
     /// `None` until first seen; there is no event to fire on it, because the real client registers
     /// no field-change callback anywhere near this offset.
     action_bar_toggles: Option<u8>,
@@ -347,7 +347,7 @@ fn load_languages(mut commands: Commands, assets: Option<Res<benilla_assets::Wor
 }
 
 /// The languages this character **knows**, folded the reference's way and fed to the VM for
-/// `GetNumLaguages`/`GetLanguageByIndex` (wow-re `chat-language-scramble.md` §8, C6):
+/// `GetNumLaguages`/`GetLanguageByIndex`:
 ///
 /// 1. `0x4b25b0` runs on spell add and stores `[languageId] = spellId` for a spell whose
 ///    `Effect_1 == 39` — so the table holds only languages *this character's known spells*
@@ -558,8 +558,8 @@ fn load_exhaustion_rows(
     }
 }
 
-/// Melee swing → the `UNIT_COMBAT` vocabulary (§5-verified shape, wow-re
-/// `unit-combat-event-law.md`): the action comes from the melee wrapper's per-victim-state table
+/// Melee swing → the `UNIT_COMBAT` vocabulary: the action comes from the melee wrapper's
+/// per-victim-state table
 /// (`0x4946d0` → `actionTable@0x83de28`), the descriptor from HitInfo bits **keyed on the
 /// amount's sign** — `amount > 0` picks among CRITICAL `0x80` / GLANCING `0x4000` / CRUSHING
 /// `0x8000`, `amount ≤ 0` among ABSORB `0x20` / BLOCK `0x800` / RESIST `0x40`, else `""`.
@@ -601,7 +601,7 @@ fn melee_feedback(hit_info: u32, victim_state: u32, damage: u32) -> (&'static st
 /// channel for. Every victim qualifies (no Gate A, no source class on the portrait path); token
 /// resolution happens in [`fire_unit_combat`], so a swing on an un-tokened bystander simply
 /// fires nothing. The center combat text does NOT ride here — the client fires it synchronously
-/// at packet parse (§5-corrected, decision 0580; the producer lives in `net/apply/combat.rs`).
+/// at packet parse (decision 0580; the producer lives in `net/apply/combat.rs`).
 fn melee_unit_combat(
     mut impacts: MessageReader<crate::creature_anim::SwingImpact>,
     mut out: MessageWriter<UnitCombatFeedback>,
@@ -904,8 +904,8 @@ fn reach_tokens() -> impl Iterator<Item = &'static str> {
 }
 
 /// The squared distance between two world positions, in the binary's own accumulation shape: `f32`
-/// inputs widened to `f64`, summed `(dz² + dx²) + dy²` (wow-re's transcription of
-/// `0x48a26f..0x48a27d`, the kernel `caninspect_dist2` and `check_interact_dist2` share).
+/// inputs widened to `f64`, summed `(dz² + dx²) + dy²` (`0x48a26f..0x48a27d`, the kernel
+/// `CanInspect 0x48a1b0` and `CheckInteractDistance 0x48ba00` share).
 ///
 /// Our axes are Bevy's rather than the client's WoW triple. d² is invariant under that rotation, so
 /// the only conceivable divergence from the binary is a last-ulp one — which can only change the
@@ -922,9 +922,8 @@ fn dist_sq(q: Vec3, p: Vec3) -> f64 {
 /// `PLAYER_CONTROL_LOST` / `PLAYER_CONTROL_GAINED` — `SMSG_CLIENT_CONTROL_UPDATE` naming the
 /// local player reaches `0x4958e0`, which writes the player-control flag and, **on a change**,
 /// fires LOST when the byte is zero and GAINED when it is not; the boot init is "in control"
-/// (wow-re `farsight-and-client-control.md` §5, `incoming-trade-request-law.md`). The flag is
-/// [`crate::player::Player::control_lost`], which `player::wire_in` writes from that packet; this
-/// fires the edge, and a fresh VM's memo is the boot value.
+/// (`0x48f626`). The flag is [`crate::player::Player::control_lost`], which `player::wire_in`
+/// writes from that packet; this fires the edge, and a fresh VM's memo is the boot value.
 fn feed_player_control(
     script: Option<NonSendMut<UiScript>>,
     player: Option<Res<crate::player::Player>>,
@@ -948,9 +947,9 @@ fn feed_player_control(
 }
 
 /// `PLAYER_FARSIGHT_FOCUS_CHANGED` — the `PLAYER_FARSIGHT` field-change callback (`0x5de0d0`)
-/// fires it on both of its legs, whether or not the new guid resolves to a streamed object
-/// (wow-re `farsight-and-client-control.md` §2). The edge is the FIELD's, so this diffs the
-/// descriptor value the camera's `publish_view_subject` reads, never the resolved pose.
+/// fires it on both of its legs, whether or not the new guid resolves to a streamed object.
+/// The edge is the FIELD's, so this diffs the descriptor value the camera's `publish_view_subject`
+/// reads, never the resolved pose.
 fn feed_farsight_focus(
     script: Option<NonSendMut<UiScript>>,
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
@@ -986,8 +985,8 @@ fn feed_farsight_focus(
 ///   the published tag, "out of range" after 1564 flipped the absent default. Both are the same
 ///   defect: the map was never asked about mobs at all.
 ///
-/// That the *client* checks those two is INFERRED (the 348-byte `0x48a1b0`'s non-math part isn't in
-/// the RE record), but a wrong guess can only cost a request the server would drop.
+/// That the *client* checks those two is inferred (the 348-byte `0x48a1b0`'s non-math part is
+/// undecoded), but a wrong guess can only cost a request the server would drop.
 ///
 /// Ungated, unlike every other feed here (1439): the numbers change whenever anything moves, so a
 /// change gate would fire every frame anyway and cost a comparison for nothing. Nothing keys an
@@ -1045,10 +1044,15 @@ fn feed_unit_reach(
 pub(crate) struct UnitStores<'w, 's> {
     /// Every streamed object's descriptor, read by guid → entity.
     all: Query<'w, 's, &'static ObjectStore>,
-    /// Whose descriptor moved this frame — the feed's dirty gate.
-    changed: Query<'w, 's, (), Changed<ObjectStore>>,
-    /// Whose object left the manager — the other half of that gate, and cleared every run.
-    removed: RemovedComponents<'w, 's, ObjectStore>,
+    /// Whose descriptor moved this frame — the feed's dirty gate. Not an item's: items carry an
+    /// `ObjectStore` since 2334, and a durability tick or a stack count naming no unit token
+    /// would open the gate for nothing (2343).
+    changed: Query<'w, 's, (), (Changed<ObjectStore>, Without<crate::items::ItemObject>)>,
+    /// Whose object left the manager — the other half of that gate, and cleared every run. The
+    /// [`Guid`], not the store: a torn-down object sheds its guid at the teardown while its
+    /// fading model keeps the store another two seconds ([`crate::net::tear_down`]), and a
+    /// despawn removes both.
+    removed: RemovedComponents<'w, 's, Guid>,
     /// The per-field edges this run (decision 2297) — [`fire_transitions`]' three mirror-diff
     /// arms fire off these, per token naming the moved unit.
     edges: MessageReader<'w, 's, FieldChanged>,
@@ -1075,10 +1079,9 @@ pub(crate) fn snapshot(
         exists: true,
         // **This function IS the reference's `0x468460` having succeeded.** It is only ever called
         // with a live `ObjectStore`, so every snapshot it builds is a unit the object manager holds
-        // — which is the whole of `UnitIsVisible` (wow-re
-        // `ui/scratch/unitisvisible-object-presence.md`). Set here rather than at the call sites so
-        // a future feed cannot forget it: the roster-only legs build a `UnitState` literally and
-        // get `false` from `Default`, which is the correct out-of-range answer.
+        // — which is the whole of `UnitIsVisible 0x516030`. Set here rather than at the call
+        // sites so a future feed cannot forget it: the roster-only legs build a `UnitState`
+        // literally and get `false` from `Default`, which is the correct out-of-range answer.
         has_object: true,
         name,
         // The UI-facing health/power getters, not the raw fields (decision 1022): a unit carrying
@@ -1143,7 +1146,7 @@ pub(crate) fn snapshot(
         pvp: store.0.unit_flags() & 0x1000 != 0,
         skinnable: store.0.unit_flags() & 0x0400_0000 != 0,
         // `UnitPlayerControlled` — the same word, bit 3 (`UNIT_FLAG_PVP_ATTACKABLE 0x8`, which is
-        // behaviourally "player-controlled"; `target::relations` already carved it for the duel
+        // behaviourally "player-controlled"; `target::relations` already reads it for the duel
         // leg of the selection ring). Wider than `is_player` above: a pet or a charmed creature
         // sets it without being a player.
         player_controlled: store.0.unit_flags() & 0x8 != 0,
@@ -1160,8 +1163,8 @@ pub(crate) fn snapshot(
             .or_else(|| store.0.unit_created_by())
             .unwrap_or(0),
         // `UnitAffectingCombat 0x517e10` — the SAME `UNIT_FIELD_FLAGS` word, bit 19
-        // (`shr ecx,0x13; test cl,1`). One flag for every token: wow-re's whole-image census of
-        // that idiom found the local-player readers reading this identical bit, so there is no
+        // (`shr ecx,0x13; test cl,1`). One flag for every token: a whole-image census of
+        // that idiom finds the local-player readers reading this identical bit, so there is no
         // player-specific combat latch to model beside it.
         in_combat: store.0.unit_flags() & crate::player::UNIT_FLAG_IN_COMBAT != 0,
         // Free-for-all PvP (decision 0646 §1): `PLAYER_FLAGS` bit 7, the same field the ghost
@@ -1290,9 +1293,8 @@ fn drain_worn_display_toggles(script: Option<NonSendMut<UiScript>>, commands: Re
     }
 }
 
-/// Drain the `SetActionBarToggles` posts into `CMSG_SET_ACTIONBAR_TOGGLES` (wow-re
-/// `system/ui/scratch/action-bar-toggles.md` §3) — the Options window's four extra-bar rows, and
-/// the only callers there are.
+/// Drain the `SetActionBarToggles` posts into `CMSG_SET_ACTIONBAR_TOGGLES` (sent at `0x4e771d`)
+/// — the Options window's four extra-bar rows, and the only callers there are.
 ///
 /// **Every queued call becomes a packet**, with no did-it-change gate and no coalescing: the real
 /// binding has neither (unlike `ShowHelm`/`ShowCloak`, which send only on a difference), so two
@@ -1316,12 +1318,12 @@ fn drain_action_bar_toggles(script: Option<NonSendMut<UiScript>>, commands: Res<
 const PLAYER_FLAGS_PVP_DESIRED: u32 = 0x200;
 
 /// `PLAYER_FLAGS_RESTING` — inside a rest area now (vmangos `Player.h:320`); the bit
-/// `IsResting 0x516ea0` tests (`shr 5; test 1` — wow-re rested-xp-bindings.md §3).
+/// `IsResting 0x516ea0` tests (`shr 5; test 1`).
 const PLAYER_FLAGS_RESTING: u32 = 0x20;
 
 /// `PLAYER_FLAGS` bit 12 / bit 13 — the two **play-time** regimes an anti-addiction realm puts an
 /// account into, read by `PartialPlayTime` (`0x48eb70`) and `NoPlayTime` (`0x48ebe0`). Decision
-/// 1746 carved both, and settled that `0x1000` is PARTIAL_PLAY_TIME on 5875 rather than the
+/// 1746 decoded both, and settled that `0x1000` is PARTIAL_PLAY_TIME on 5875 rather than the
 /// pre-1.6.1 `CAN_SELF_RESURRECT` it had been read as. Stock `PlayerFrame_UpdatePlaytime` tests
 /// them at LOAD, so their absence is a raise on the first frame, not a cosmetic gap.
 const PLAYER_FLAGS_PARTIAL_PLAY_TIME: u32 = 0x1000;
@@ -1351,8 +1353,8 @@ fn pvp_announcement(was: Option<bool>, now: bool) -> Option<(&'static str, &'sta
     })
 }
 
-/// The rest-state chat line (decision 1098; wow-re rested-xp-bindings.md §§6-10, byte-verified
-/// §5): the rest-state BYTE watcher `0x5de4e0` messages only on a real old≠new transition (the
+/// The rest-state chat line (decision 1098): the rest-state BYTE watcher `0x5de4e0` messages
+/// only on a real old≠new transition (the
 /// dispatcher's `rep cmpsb` mirror diff at `0x4655bb`), through the hard-coded 3×2 pair table
 /// `0x80af50` — state 1 → `ERR_EXHAUSTION_RESTED`, state 2 → `ERR_EXHAUSTION_NORMAL`, state 0 →
 /// the table's deliberate no-message sentinel (id 0x1d1), states ≥ 3 gated off before the table
@@ -1419,7 +1421,7 @@ fn creature_type_word(t: u32) -> Option<&'static str> {
         8 => "Critter",
         9 => "Mechanical",
         // The shipped `CreatureType.dbc` is **1..11 dense**, not 1..9 — this table stopped two
-        // rows early. 11 is reachable and wow-re's own nameplate filter tests for it
+        // rows early. 11 is reachable and the reference's own nameplate filter tests for it
         // (`0x605570 == 0xb`).
         11 => "Totem",
         // 10 is "Not specified" in the DBC. Deliberately still None: this word is the tooltip's
@@ -1457,8 +1459,8 @@ pub(crate) fn fire_transitions(
     if changed(|u| u64::from(u.power_type)) {
         script.fire_event("UNIT_DISPLAYPOWER", vec![tok()]);
     }
-    // `UNIT_FLAGS` (id 40) — the per-field watch bridge (wow-re `unit-field-event-bridge.md`,
-    // VERIFIED): `0x51bbb0` registers one watch per named unit field, the notifier `0x465570`
+    // `UNIT_FLAGS` (id 40) — the per-field watch bridge:
+    // `0x51bbb0` registers one watch per named unit field, the notifier `0x465570`
     // fires `0x51bd50` → `0x515e50` on any change of the dword's bytes, once per token mapping to
     // the unit, `arg1` the token. The create leg runs no notify pass, so a unit's FIRST snapshot
     // is not a transition here — unlike the fields above, whose first-appearance fire is this
@@ -1487,13 +1489,12 @@ pub(crate) fn fire_transitions(
     //    That is why the trigger is the raw dword (`UnitState::player_flags`) and not a bool.
     // 2. **Above the local-GUID gate** at `0x5eea93` (the ghost/resting/PvP/play-time arms below it
     //    are self-only; this one is not) — and the trampoline `0x5e2850` resolves the changed
-    //    object by GUID under TYPEMASK_PLAYER, "any player, not the local one" (wow-re
-    //    `object-layer/ledger.tsv`). So a *stranger's* flags fire it, which is the whole reason the
-    //    stock target frame can listen.
+    //    object by GUID under TYPEMASK_PLAYER, "any player, not the local one". So a *stranger's*
+    //    flags fire it, which is the whole reason the stock target frame can listen.
     // 3. **Once per unit token naming that GUID, `arg1` = the token, no `arg2`** — `0x515e50` walks
-    //    `0x515c50`'s token array and calls `0x703f50(id, "%s", token)` per entry (wow-re
-    //    `ui/scratch/unit-field-event-bridge.md` §2.2). That is exactly this function's own shape,
-    //    which is why the arm belongs here and not beside the self-only feeds below.
+    //    `0x515c50`'s token array and calls `0x703f50(id, "%s", token)` per entry. That is exactly
+    //    this function's own shape, which is why the arm belongs here and not beside the self-only
+    //    feeds below.
     //
     // **"Fires for any player" is not "reaches Lua", and the difference is free here.**
     // `0x515e63 test eax,eax / 0x515e6a jle 0x515e8a` skips the fan-out loop entirely on a zero
@@ -1501,7 +1502,7 @@ pub(crate) fn fire_transitions(
     // announces **nothing** to the VM — the handler still runs, and its helm/cloak arms above the
     // gate still repaint them, but no event is signalled. This feed gets that for nothing by
     // construction: it is only ever called *per token*, so a tokenless player is never reached
-    // (wow-re `object-layer/scratch/player-flags-delta-arms.md`, the 2078 correction round).
+    // (decision 2078).
     //
     // Off the field edge for the same reason `UNIT_FLAGS` is: this is a mirror-diff watcher,
     // and a unit's first snapshot is its CREATE, which runs no notify pass (1098 §4).
@@ -1509,10 +1510,10 @@ pub(crate) fn fire_transitions(
     // **The sole 1.12 consumer is the target frame's PARTY-LEADER icon, not an AFK/DND badge** —
     // `TargetFrame.lua:88-95` re-runs the `UnitIsPartyLeader("target")` show/hide, and bit `0x1` is
     // that predicate's descriptor leg. Nothing in 1.12 FrameXML draws an AFK or DND badge on a unit
-    // frame, and build 5875 has no `UnitIsAFK`/`UnitIsDND` binding at all (wow-re
-    // `ui/scratch/unit-predicate-return-shape.md` §5, a zero-hit whole-image byte census); the
-    // `<AFK>`/`<DND>` the era shows are the chat line's `arg6` flag. This comment is here because
-    // the gap list said "the AFK/DND badge" for months and sent the first look at the wrong window.
+    // frame, and build 5875 has no `UnitIsAFK`/`UnitIsDND` binding at all (a zero-hit whole-image
+    // byte census); the `<AFK>`/`<DND>` the era shows are the chat line's `arg6` flag. This comment
+    // is here because the gap list said "the AFK/DND badge" for months and sent the first look at
+    // the wrong window.
     if edges.moved(cur.guid, benilla_protocol::field::FIELD_PLAYER_FLAGS) {
         script.fire_event("PLAYER_FLAGS_CHANGED", vec![tok()]);
     }
@@ -1577,15 +1578,15 @@ pub(crate) fn fire_transitions(
     //
     // **And on the TAPPED bit, which is not a faction field and fires this event anyway.** The
     // reference's `UNIT_DYNAMIC_FLAGS` watcher tests bit `0x4` and dispatches event id **29** —
-    // `UNIT_FACTION` — at `0x6005a1 test al,4` -> `0x6005b0 mov edx,0x1d` -> `0x515e50` (wow-re
-    // `ui/scratch/tapped-bits-and-unit-faction.md`, controlled across all 37 fire sites).
+    // `UNIT_FACTION` — at `0x6005a1 test al,4` -> `0x6005b0 mov edx,0x1d` -> `0x515e50`
+    // (controlled across all 37 fire sites).
     //
     // This line is the whole reason `UnitIsTapped` is worth publishing. Without it both verbs
     // answer CORRECTLY and no frame ever repaints: pfUI's grey-bar branch runs inside
     // `RefreshUnit`, which is event-driven, so a mob that becomes someone else's tap would stay
     // full-colour until something unrelated happened to refresh it. A passing unit test on the
     // predicates would have said nothing about that — the mechanism existing is not the mechanism
-    // applying (`method.md` step 5).
+    // applying (`docs/METHOD.md` step 5).
     //
     // Bit `0x8` deliberately has NO arm here: the reference's watcher has none for it either
     // (proven by enumerating all 122 instructions and 12 branches of `0x600440`). The pair is read
@@ -1710,7 +1711,9 @@ fn feed_units(
     // resolve through the cache — a miss queries the server once and lands on a later frame.
     let self_pair = self_q.iter().next();
     let player = self_pair.map(|(store, guid)| {
-        let name = names.resolve(guid.0, &commands).map(str::to_string);
+        let name = names
+            .resolve_unit(guid.0, Some(store), &commands)
+            .map(str::to_string);
         let mut s = snapshot(store, name, 0, chr);
         s.is_player = true;
         // The stated `is_connected` gap, closed for every token this feed pushes — the field's own
@@ -1766,7 +1769,9 @@ fn feed_units(
     // stays server memory outside it, which the disjoint field borrows above preserve.)
     let target = selection.target.zip(selection.guid).and_then(|(e, guid)| {
         let store = stores.all.get(e).ok()?;
-        let name = names.resolve(guid, &commands).map(str::to_string);
+        let name = names
+            .resolve_unit(guid, Some(store), &commands)
+            .map(str::to_string);
         // The target's reaction toward us, on the `UnitReaction` 1..8 scale — the same decode the
         // selection ring runs (reputation-first, else the faction-template comparator). `ring_reaction`
         // returns the raw 0..7 rank (neutral its no-data fallback), which is `UnitReaction − 1`; +1
@@ -1824,7 +1829,9 @@ fn feed_units(
         .and_then(|guid| Some((*index.as_ref()?.0.get(&guid)?, guid)))
         .and_then(|(entity, guid)| {
             let store = stores.all.get(entity).ok()?;
-            let name = names.resolve(guid, &commands).map(str::to_string);
+            let name = names
+                .resolve_unit(guid, Some(store), &commands)
+                .map(str::to_string);
             let reaction = ring_reaction(
                 factions.as_deref(),
                 &reputations,
@@ -1892,10 +1899,10 @@ fn feed_units(
     }
 
     // `"npc"` — the unit the player is interacting with, resolved through the SAME interaction guid
-    // the real client's token reads (`CGGameUI`'s `[0xb4e2d0]`, what `CGGameUI::SetInteractNPC`
-    // writes; wow-re confirms the guild registrar's own opener is one of that function's fourteen
-    // callers). `crate::ui_session::InteractNpc` is benilla's model of exactly that cell, so the
-    // token and the portrait booth cannot disagree about who "npc" is.
+    // the real client's token reads (`CGGameUI`'s `[0xb4e2d0]`, what
+    // `CGGameUI::SetInteractNPC 0x4930d0` writes; the guild registrar's own opener is one of that
+    // function's fourteen callers). `crate::ui_session::InteractNpc` is benilla's model of exactly
+    // that cell, so the token and the portrait booth cannot disagree about who "npc" is.
     //
     // **It had no feed at all until decision 1678**, and the gap was invisible because nothing
     // called it: `TaxiFrame.xml` and `TradeFrame.xml` both take the NPC's name from an event
@@ -1912,7 +1919,9 @@ fn feed_units(
         .and_then(|i| Some((i.0?, i.1?)))
         .and_then(|(entity, guid)| {
             let store = stores.all.get(entity).ok()?;
-            let name = names.resolve(guid, &commands).map(str::to_string);
+            let name = names
+                .resolve_unit(guid, Some(store), &commands)
+                .map(str::to_string);
             let reaction = ring_reaction(
                 factions.as_deref(),
                 &reputations,
@@ -2005,14 +2014,13 @@ fn feed_units(
     // ```
     //
     // `0x5eeaf2` sits INSIDE the `0x20` arm (`0x5eeaf2 < 0x5eeafc`, the `je`'s target), so
-    // **PLAYER_UPDATE_RESTING fires only on the resting bit's own edge** — not, as wow-re's
-    // `rested-xp-bindings.md` §5 and its `0x5ee990` ledger row both say, "on every flags change,
-    // not only the resting bit". That claim is what this feed was built against, and it made every
-    // helm toggle, every leadership pass and every AFK flip announce a resting change to the UI.
-    // The note's "argless unconditionally" is true only of the *direction*: the inner
-    // `0x5eeae4 je` skips the tutorial popup, never the fire, so both edges of the bit fire it.
-    // A correction round is dispatched into wow-re; the bytes above are read straight out of
-    // `WoW.exe` (file offset 0x1eead0, PE imagebase 0x400000, .text RVA 0x1000 → raw 0x1000).
+    // **PLAYER_UPDATE_RESTING fires only on the resting bit's own edge** — not "on every flags
+    // change, not only the resting bit", the reading of `0x5ee990` this feed was built against,
+    // which made every helm toggle, every leadership pass and every AFK flip announce a resting
+    // change to the UI. The same reading's "argless unconditionally" is true only of the
+    // *direction*: the inner `0x5eeae4 je` skips the tutorial popup, never the fire, so both edges
+    // of the bit fire it. The bytes above are read straight out of `WoW.exe` (file offset
+    // 0x1eead0, PE imagebase 0x400000, .text RVA 0x1000 → raw 0x1000).
     //
     // `UPDATE_EXHAUSTION` is unchanged and was already right: two separate watchers, `0x5de4e0` on
     // the rest-state byte and `0x5de4b0` on the pool field, neither of them this handler.
@@ -2124,17 +2132,18 @@ fn feed_units(
     }
 
     // The action-bar toggle feed: `PLAYER_FIELD_BYTES` byte 2 — which of the four extra bars the
-    // player has switched on (wow-re `system/ui/scratch/action-bar-toggles.md`). PRIVATE, like the
-    // combo byte one address down (`+0x1029` vs `+0x102a`), and pushed on the EDGE.
+    // player has switched on. PRIVATE, like the combo byte one address down (`+0x1029` vs
+    // `+0x102a`), and pushed on the EDGE.
     //
     // **This push is the ONLY thing that moves the VM's copy**, and that is the mechanism rather
-    // than our simplification: no instruction in the real client writes this cell (§4.1 — the one
-    // `+0x102a` access image-wide is `GetActionBarToggles`' read), so `SetActionBarToggles` posts
-    // the byte and leaves the descriptor alone until the server's UPDATE_OBJECT echoes it. Nothing
-    // is notified when it lands either (§4.2: all 49 field-change registrations at `0x468070` were
-    // enumerated; none sits at an offset ≥ `0x1000`), so there is **no event to fire here** — the
-    // reference reads the binding exactly once, in `UIParent.lua`'s `PLAYER_ENTERING_WORLD`
-    // handler, and keeps `SHOW_MULTI_ACTIONBAR_1..4` as its optimistic copy in between.
+    // than our simplification: no instruction in the real client writes this cell (the one
+    // `+0x102a` access image-wide is `GetActionBarToggles`' read at `0x4e768c`), so
+    // `SetActionBarToggles` posts the byte and leaves the descriptor alone until the server's
+    // UPDATE_OBJECT echoes it. Nothing is notified when it lands either (all 49 field-change
+    // registrations at `0x468070` were enumerated; none sits at an offset ≥ `0x1000`), so there is
+    // **no event to fire here** — the reference reads the binding exactly once, in `UIParent.lua`'s
+    // `PLAYER_ENTERING_WORLD` handler, and keeps `SHOW_MULTI_ACTIONBAR_1..4` as its optimistic copy
+    // in between.
     //
     // Which is why this sits ABOVE the fire, on 1087's precedent for the XP/rest pushes: the
     // handler that reads `GetActionBarToggles()` runs synchronously inside `fire_event`, so a push
@@ -2142,7 +2151,7 @@ fn feed_units(
     //
     // `unwrap_or(0)` is faithful, not a shrug: with no local player the reference's chain fails
     // soft and the getter returns four `nil`s, which is exactly what a zero byte returns — "not in
-    // world" and "byte == 0" share the branch and are indistinguishable to Lua (§5).
+    // world" and "byte == 0" share the branch (`0x4e7684`) and are indistinguishable to Lua.
     if let Some((store, _)) = self_q.iter().next() {
         let toggles = store.0.player_action_bar_toggles().unwrap_or(0);
         if memo.action_bar_toggles != Some(toggles) {
@@ -2334,7 +2343,7 @@ fn feed_units(
 ///
 /// The two halves diverge because the client's watches do. Event 202 is registered at `0x5dd9d9`
 /// as a **one-byte field-change watch on `+0x1029`** — the count — and `PLAYER_FIELD_COMBO_TARGET`
-/// carries no watch of its own (§5-VERIFIED, decision 0879). So a re-bank onto a different unit at
+/// carries no watch of its own (decision 0879). So a re-bank onto a different unit at
 /// an unchanged count moves the *value* `GetComboPoints` reads without announcing itself, and the
 /// UI hears about it through `PLAYER_TARGET_CHANGED` instead. The watch has no value test, so the
 /// drop back to zero fires like any other change — the edge that takes the dots down.
@@ -2434,14 +2443,14 @@ mod tests {
     /// `UnitIsTapped` answering correctly is only half of it. pfUI's grey-bar branch lives inside
     /// `RefreshUnit`, which is event-driven — so a mob that becomes someone else's tap would stay
     /// full-colour until something unrelated happened to repaint the frame. The predicate would be
-    /// right and the screen would be wrong, which no test of the predicate can see (`method.md`
+    /// right and the screen would be wrong, which no test of the predicate can see (`docs/METHOD.md`
     /// step 5: the mechanism existing is not the mechanism applying).
     ///
     /// The reference dispatches event id **29** — `UNIT_FACTION`, not a tapped-specific event —
     /// from its `UNIT_DYNAMIC_FLAGS` watcher's bit-`0x4` arm (`0x6005a1 test al,4` ->
-    /// `0x6005b0 mov edx,0x1d` -> `0x515e50`; wow-re `ui/scratch/tapped-bits-and-unit-faction.md`,
-    /// controlled across all 37 fire sites image-wide). Reusing the faction event for a
-    /// non-faction field is not something anyone would invent, which is exactly why it is pinned.
+    /// `0x6005b0 mov edx,0x1d` -> `0x515e50`, controlled across all 37 fire sites image-wide).
+    /// Reusing the faction event for a non-faction field is not something anyone would invent,
+    /// which is exactly why it is pinned.
     ///
     /// Bit `0x8` has **no** arm, in the reference or here — proven there by enumerating all 122
     /// instructions and 12 branches of the watcher. The negative half is asserted too, because
@@ -2792,9 +2801,9 @@ mod tests {
     ///
     /// `0x5ee990`'s local-GUID gate at `0x5eea93` divides it: `PLAYER_FLAGS_CHANGED` above (any
     /// player), and below it three arms that each carry their own `test` against the XOR-diff.
-    /// benilla fired `PLAYER_UPDATE_RESTING` on *any* `PLAYER_FLAGS` delta, because wow-re's
-    /// `rested-xp-bindings.md` §5 says it does; `0x5eead0 f6 45 fc 20 / 74 26` says otherwise —
-    /// the `je`'s target is `0x5eeafc` and the fire is at `0x5eeaf2`, inside the arm.
+    /// benilla fired `PLAYER_UPDATE_RESTING` on *any* `PLAYER_FLAGS` delta;
+    /// `0x5eead0 f6 45 fc 20 / 74 26` says otherwise — the `je`'s target is `0x5eeafc` and the
+    /// fire is at `0x5eeaf2`, inside the arm.
     #[test]
     fn the_self_flag_events_each_fire_on_their_own_bits() {
         use bevy::ecs::system::RunSystemOnce;
@@ -3346,7 +3355,7 @@ mod tests {
         }
     }
 
-    /// The rest-state chat law (decision 1098, wow-re §§6-10): a message needs a real byte
+    /// The rest-state chat law (decision 1098; the watcher `0x5de4e0`): a message needs a real byte
     /// TRANSITION, and only states 1/2 speak — state 0 is the pair table's no-message sentinel,
     /// the beta tiers (≥3) are gated off before the table, and a re-send of the same byte is
     /// swallowed by the dispatcher's mirror diff.
diff --git a/crates/benilla-app/src/ui_world_map.rs b/crates/benilla-app/src/ui_world_map.rs
index 9cee6983..fbef8946 100644
--- a/crates/benilla-app/src/ui_world_map.rs
+++ b/crates/benilla-app/src/ui_world_map.rs
@@ -5,7 +5,7 @@
 //! - [`seed_world_map_catalog`] (at the world-entry edge, before any interface file runs — 2240):
 //!   builds the static **catalog** from `WorldMapArea` × `AreaTable` × `WorldMapContinent` ×
 //!   `Map` × the `.zmp` bitmaps and pushes it into the engine. Every ordering/naming rule is the
-//!   wow-re-verified one (Q1/Q3 verdicts, 2026-07-07): continents in WorldMapArea **file
+//!   reference's own: continents in WorldMapArea **file
 //!   order** (Kalimdor, then EK — the `0x4a5d00` builder's walk), displayed under their
 //!   `Map.dbc` localized names ("Eastern Kingdoms", not the art folder's "Azeroth"); zones
 //!   sorted case-insensitively by AreaTable localized name (the `0x4a6390` comparator's
@@ -143,7 +143,7 @@ fn map_row_view(
                     o.hit_rect_right,
                 ),
                 // The zone-level hover's label inside that rect: the FIRST area slot's AreaTable
-                // name — `0x4a7fa0` reads `+0x8` only (wow-re 15b2a8ea §1d); a slot that resolves
+                // name — `0x4a7fa0` reads `+0x8` only; a slot that resolves
                 // to no row makes the overlay invisible to the hover, never to the draw.
                 area_name: areas.name(o.area_id[0]).map(str::to_string),
             })
@@ -177,7 +177,7 @@ pub(crate) fn build_catalog(
     };
 
     // Continents: the areaId==0 rows in WorldMapArea FILE order — the 0x4a5d00 builder's walk,
-    // which defines the Lua continent index (Kalimdor, then EK in 5875; wow-re Q1(d) verdict).
+    // which defines the Lua continent index (Kalimdor, then EK in 5875).
     let cont_rows: Vec<(u32, &WorldMapArea)> = wma.iter().filter(|(_, a)| a.area_id == 0).collect();
 
     let mut entries = Vec::with_capacity(cont_rows.len());
@@ -223,7 +223,7 @@ pub(crate) fn build_catalog(
 
         // The continent's area bitmap, remapped from raw AreaTable ids to 1-based zone indices —
         // the client's load-time remap (one-hop parent rollup, then the (mapId, areaId) match;
-        // wow-re Q1(b)), fused with its zone-index resolution since our engine consumes indices.
+        // `0x4a6070`), fused with its zone-index resolution since our engine consumes indices.
         let zone_grid: Vec<u16> = match load_zone_map(&mut *chain, &cont.name) {
             Ok(grid) => grid
                 .iter()
@@ -250,7 +250,7 @@ pub(crate) fn build_catalog(
 
         views.push(WorldMapContinentView {
             // Display name = Map.dbc's localized MapName ("Eastern Kingdoms"), never the art
-            // folder (wow-re Q3(a)); the folder stays the map_file.
+            // folder (`0x4a65a0`); the folder stays the map_file.
             name: maps
                 .0
                 .name(cont.map_id)
@@ -279,8 +279,7 @@ pub(crate) fn build_catalog(
         });
     }
 
-    // ── The THIRD list: the orphans — the instance maps (wow-re
-    // `system/ui/scratch/worldmap-direct-area-selection.md` §2). `0x4a5d00` fills a container
+    // ── The THIRD list: the orphans — the instance maps. `0x4a5d00` fills a container
     // beside the continents with every row that has `areaID != 0` and whose mapID matches **no**
     // continent record's mapID, in `WorldMapArea.dbc` **file order with no sort** — the passes at
     // `0x4a6130` (count) and `0x4a61c9` (fill), whose predicate is the exact complement of the
@@ -398,7 +397,7 @@ fn build_catalog_from_world(world: &World) -> Option<(Vec<WorldMapContinentView>
 /// branches on.
 ///
 /// **The direct-area state answers [`MapLevel::Zone`], and that is the reference's own law rather
-/// than an approximation** (wow-re `worldmap-direct-area-selection.md` §6). Both gates that read
+/// than an approximation**. Both gates that read
 /// this enum test "zone **or** orphan": the AreaPOI level flag falls into the zone-level
 /// `test [rec+0x20],0x4` at `-2` (`0x4a79de cmp eax,-2; jne`), and `GetMapLandmarkInfo`'s
 /// `textureIndex` substitution is reached when the zone cell is `-1` **and** the continent is `-2`
@@ -492,8 +491,7 @@ fn is_degenerate(uv: (f32, f32)) -> bool {
     uv.0.abs() < EPS && uv.1.abs() < EPS
 }
 
-/// The three gates `0x4a67a0`'s AreaPOI walk applies, in the reference's order (wow-re
-/// `system/ui/scratch/gossip-poi-marker.md` §7 + §8.2).
+/// The three gates `0x4a67a0`'s AreaPOI walk applies, in the reference's order.
 ///
 /// 1. **The level flag** (`0x4a79b0`'s fall-through chain, `0x4a79cb`–`0x4a7a05`): a row must
 ///    carry `0x04` to show at zone level, `0x08` at continent level, and **both `0x10` and
@@ -760,9 +758,8 @@ fn feed_world_map(
     // each continent record's `+0x00`, then walks that record's sorted child-zone array for the
     // zone whose WMA areaID equals the player's current-area global — and **"no zone match ⇒
     // `SetMap(continent, −1)`"**, i.e. the CONTINENT map, with only "no continent match" falling
-    // through to the orphan list and then `SetMap(−1, −1)` = the world view (wow-re
-    // `system/ui/scratch/geometry.md` §"Worldmap data model"; `GetCurrentMapZone 0x4a7f00` is
-    // `DAT_00845070 + 1`, so that −1 reads back to Lua as **0**).
+    // through to the orphan list and then `SetMap(−1, −1)` = the world view
+    // (`GetCurrentMapZone 0x4a7f00` is `DAT_00845070 + 1`, so that −1 reads back to Lua as **0**).
     //
     // We used to resolve both or neither, so a zone the catalog has no row for — and, before the
     // area feed answers, a zone we simply do not know yet — slammed the selection to the WORLD
@@ -870,7 +867,7 @@ fn feed_world_map(
         // Then the guard-directions marker (`crate::poi_marker`), appended last exactly as
         // `0x4a69c7` does and — like it — exempt from every gate above: no level flag, no
         // exploration bit, no world state, its `Icon` verbatim with no level-15 substitution
-        // (wow-re `gossip-poi-marker.md` §8, the `+0x10 == 1` element). Only the same
+        // (the `+0x10 == 1` element). Only the same
         // non-degenerate projection test applies.
         if let Some(poi) = poi_marker.on_map(map.0) {
             if let Some(uv) = project(poi.continent_id, poi.pos[0], poi.pos[1]) {
@@ -963,7 +960,7 @@ fn feed_world_map(
 ///
 /// **Zone and continent sheets only.** At the *world* level (both continents on one sheet) the
 /// client's own UV→world law `0x4a7100` is not the inverse of its world→UV law — a confirmed,
-/// reproduced anomaly (wow-re Q2 verdict; see [`map_proj::world_click_world`]) — so a click there
+/// reproduced anomaly (see [`map_proj::world_click_world`]) — so a click there
 /// would land somewhere real but wrong by ~1.33× the sheet offset. Rather than invent a corrected
 /// inverse the reference doesn't have, the jump declines and says to zoom in first.
 ///
@@ -1090,7 +1087,7 @@ mod tests {
         benilla_formats::AreaTableCatalog::from_rows(Vec::new())
     }
 
-    /// The level-flag chain, in the shape §7 says it has: `0x04` for zone, `0x08` for continent,
+    /// The level-flag chain, in the shape `0x4a79b0` has: `0x04` for zone, `0x08` for continent,
     /// and world demanding **both** `0x10` and `0x08` because the tests fall through rather than
     /// switch. A row with `0x10` alone is invisible everywhere — the case the shipped data can't
     /// exhibit (no 5875 row sets `0x10` without `0x08`) and the one a switch would get wrong.
@@ -1426,7 +1423,7 @@ mod player_zone_tests {
 
     /// **The two halves fail separately** — `SetMapToCurrentZone`'s resolver `0x4a6650`:
     /// "no zone match ⇒ `SetMap(continent, −1)`", and only "no continent match" reaches the world
-    /// view (wow-re `system/ui/scratch/geometry.md`). Resolving both-or-neither sent a player
+    /// view. Resolving both-or-neither sent a player
     /// whose zone the catalog cannot name — and, for the frames before the area feed answers,
     /// EVERY player — to the world level, where `GetPlayerMapPosition` answers a world-SHEET uv
     /// that every zone-uv consumer silently mis-scales.
@@ -1523,9 +1520,8 @@ mod player_zone_tests {
 
     /// **The engine selects the player's zone itself, on the first world-enter** — the side call
     /// `0x494780` makes to `0x4a6650` when the cached zone id was 0. We transcribed that
-    /// function's event election (`crate::area`) and dropped this half; wow-re carved it as
-    /// `system/ui/scratch/worldmap-selection-autosync.md` (`0x4947ac`, guarded by `sete al` on
-    /// `[0xb4e314] == 0`, with the new zone committed *before* the call).
+    /// function's event election (`crate::area`) and dropped this half (`0x4947ac`, guarded by
+    /// `sete al` on `[0xb4e314] == 0`, with the new zone committed *before* the call).
     ///
     /// Dropping it is why Questie's quest arrow pointed ~100 yards off the turn-in while the
     /// reference was exact: with no zone selected, `GetPlayerMapPosition` answers a world-SHEET
diff --git a/crates/benilla-app/src/video.rs b/crates/benilla-app/src/video.rs
index fb48cee1..07c17824 100644
--- a/crates/benilla-app/src/video.rs
+++ b/crates/benilla-app/src/video.rs
@@ -498,10 +498,9 @@ 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`, wow-re
-/// `cvar/scratch/graphics-cost-cvar-census.md` §2), 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.
+/// 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.
 pub(crate) fn on_cvar(
     ev: On<crate::cvars::CvarChanged>,
     mut cfg: ResMut<VideoConfig>,
@@ -703,8 +702,8 @@ pub(crate) fn on_cvar(
         }
         // 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]` (wow-re `graphics-cost-cvar-census.md` §4).
-        // What that table does with an off-grid int is NOT carved, so the clamp here is the
+        // {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.
         "weatherdensity" => weather.weather_density = v.trunc().clamp(0.0, 3.0) as u8,
@@ -817,9 +816,8 @@ 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** (wow-re
-/// `ui/scratch/video-options-verbs.md` §1.1, all VERIFIED at `0x48bcfa`–`0x48bd18`), in its own
-/// order: keep iff `w/h >= 1.248`, `w >= 800`, `h >= 600`.
+/// **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
diff --git a/crates/benilla-app/src/vplates.rs b/crates/benilla-app/src/vplates.rs
index da3f8e01..ec703c9e 100644
--- a/crates/benilla-app/src/vplates.rs
+++ b/crates/benilla-app/src/vplates.rs
@@ -1,6 +1,6 @@
-//! **V-key nameplates** — `CGNamePlateFrame` (wow-re `object-layer/scratch/nameplate-vkey.md`,
-//! §5-verified 2026-07-06): 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`): the toggled health-bar plates
+//! over units' heads, a **2-D overlay** distinct from the world-pass overhead *names*
+//! (`crate::nameplates`) they replace.
 //!
 //! The pinned law, transcribed:
 //! - **Master toggles** (`[0xc4da34]` bit 0 enemy / bit 3 friendly; real-client boot default
@@ -9,28 +9,27 @@
 //!   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`], wow-re `nameplate-category-gate.md` §2/§3,
-//!   §5-VERIFIED 2026-08-22 — this file shipped `rank >= 4` for a year and 1530 corrects it) —
+//!   ([`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" was the census that missed it. And the sphere is bounded by the frustum:
+//!   "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 — wow-re
-//!   `nameplate-offscreen-cull.md`, §5-VERIFIED 2026-08-15); it is never clamped in from
-//!   off-screen, which is what ours did (1341/1344).
+//!   **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 — §8 Q5) and is edge-clamped half a plate inside the screen;
+//!   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²)` (§8 Q4 — and never
+//!   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 (§9, byte-closed) and the director rejected that
+//!   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
@@ -54,13 +53,12 @@
 //! - **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 (byte-verified, wow-re `questgiver-marker.md`
-//!   Q4a) and the director rejected that overlap; rationale on `quest_markers::pose_markers`,
-//!   2274/2275.)
+//!   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`, §5-VERIFIED 2026-07-17, the same one the tooltip/quest-range APIs read; it is
-//! vacuous on a ≥ +10 hostile and kept for transcription fidelity.)
+//! — `0x5f0700`, the same one the tooltip/quest-range APIs read; it is vacuous on a ≥ +10
+//! hostile and kept for transcription fidelity.)
 
 use bevy::ecs::entity::EntityHashSet;
 use bevy::ecs::system::SystemParam;
@@ -90,8 +88,8 @@ pub(crate) mod border;
 /// [`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 (wow-re, VERIFIED:
-/// no such string exists in the binary), so the names are the LATER-era engine's, the same posture
+/// `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.
 ///
@@ -145,7 +143,7 @@ pub(crate) struct PlateClicks {
 }
 
 /// The plate frame, gx screen-height units (`[0x87d9cc]`/`[0x87d9d0]`): 0.1 × 0.025. The border
-/// SetAllPoints-fills it; everything else anchors inside it (§7, byte-verified offsets).
+/// SetAllPoints-fills it; everything else anchors inside it (offsets: `0x7cb250`, `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.
@@ -159,14 +157,14 @@ const BAR_H: f32 = 0.007025;
 ///
 /// `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 is
-/// byte-closed end to end, wow-re §9 Q3: live re-raster on resize, no fixed UI space, no staleness).
+/// 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).
 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 (vkey §7, VERIFIED): 0.02 × 0.02, RIGHT ← border.LEFT (0,0) — it hangs
+/// 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.
 const RAID_ICON_SIZE: f32 = 0.02;
 /// The plate's world lift above the overhead anchor: 2/3 yd (`[0x80abfc]`).
@@ -186,7 +184,7 @@ 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 (§7, VERIFIED dwords): hostile
+/// 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.
@@ -202,7 +200,7 @@ fn plate_tint(rank: u8, is_player: bool) -> [f32; 4] {
     }
 }
 
-/// The level con palette — the client's EXACT dwords (§7; the softened WoW colors, not the
+/// 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`.
 const CON_RED: [f32; 4] = [1.0, 25.0 / 255.0, 25.0 / 255.0, 1.0];
@@ -211,7 +209,7 @@ 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 (§7, byte-verified — thresholds AND the grayband table
+/// 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
@@ -259,8 +257,8 @@ pub(crate) fn device_snap(v: f32, scale: f32) -> f32 {
 }
 
 /// 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 (wow-re §9,
-/// byte-closed: ~294 px plate + em-29 name at 2560×1440, bilinear-softened) — the director
+/// (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
@@ -271,9 +269,10 @@ const PLATE_DIAG_KNEE: f32 = 1280.0;
 /// 1 the faithful law.
 const PLATE_GROWTH_DAMP: f32 = 0.5;
 
-/// One gx screencoord unit = the screen **DIAGONAL** `√(W²+H²)` (§8 Q4 — 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).
+/// 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.
 pub(crate) fn plate_basis(viewport: Vec2) -> f32 {
@@ -292,10 +291,9 @@ pub(crate) fn gx_px(v: f32, basis: f32) -> f32 {
 }
 
 /// Plate FontString height → the FreeType em: `min(32, round(h · basis))`. The real client's
-/// law is **byte-closed end to end** (wow-re `25cfa33e` + §9 Q3: 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
+/// 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`].
 pub(crate) fn text_px(h: f32, basis: f32) -> f32 {
@@ -432,7 +430,7 @@ struct PlateWorld<'w, 's> {
     // 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`).
-    targeting: Res<'w, crate::ui_action::SpellTargeting>,
+    targeting: Res<'w, crate::spell::SpellTargeting>,
 }
 
 /// Gate + draw, every frame: decide which units carry a plate (into [`VPlates`], the
@@ -532,7 +530,7 @@ fn drive_vplates(
     script.set_nameplate_hit_test_veto(
         world
             .targeting
-            .wants(crate::ui_action::targeting::TargetingWants::Location),
+            .wants(crate::spell::targeting::TargetingWants::Location),
     );
     let hovered_key = script.hovered_nameplate();
     let clicked = script.take_nameplate_clicks();
@@ -569,8 +567,7 @@ fn drive_vplates(
         // (`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** (wow-re
-        // `object-layer/scratch/not-selectable-mouse-refusal.md`, decision 2060): a plate hover
+        // **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
@@ -579,17 +576,16 @@ fn drive_vplates(
             continue;
         }
         // A DEAD unit shows no plate — the per-tick gate `0x60f600`'s FIRST, unconditional
-        // test (§8 Q2, byte-confirmed): signed `UNIT_FIELD_HEALTH ≤ 0`, absent = 0 (the
+        // 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).
         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`, byte-VERIFIED wow-re
-        // ghost-death-visuals.md — 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.
+        // …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.
         if store.is_some_and(|s| s.0.unit_is_ghost_visual()) {
             continue;
         }
@@ -645,7 +641,7 @@ fn drive_vplates(
         // 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 (wow-re `nameplate-offscreen-cull.md`, §5-VERIFIED 2026-08-15).
+        // 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
@@ -688,21 +684,22 @@ fn drive_vplates(
         };
         // The bar tint: the NAMEPLATE palette in `0x7cbaa0`'s exact order.
         let tint = plate_tint(rank, is_player);
-        // The frame SEAT (§8 Q5, byte-confirmed): the plate's TOP-CENTER lands on the projected
+        // 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).
+        // (fill/border/text hues overlap under zoom). The `vpl` lines of the shared trace below
+        // are read back by `scripts/vplsum.py`.
         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 (nameplate-vkey §8.5, now corrected by the solver note).
+        // was this law minus the solve.
         let desired = Rect::new(
             screen.x - pw * 0.5,
             screen.y,
@@ -804,8 +801,8 @@ fn drive_vplates(
             key: guid.0,
             top_centre: (x_units, y_units),
             // RAW health and its max — `healthbar:GetValue()` is `[bar+0x320]`, not a fraction
-            // (`nameplate-lua-surface.md` Q5, which corrected wow-re's own note). pfUI and
-            // CustomNameplates both divide, and a fraction here would read as full health.
+            // (`0x78f5d0`). pfUI and CustomNameplates both divide, and a fraction here would read
+            // as full health.
             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,10 +810,10 @@ fn drive_vplates(
                 .max(1) as f32,
             bar_colour: [tint[0], tint[1], tint[2]],
             name: names
-                .resolve(guid.0, &net_commands)
+                .resolve_unit(guid.0, store, &net_commands)
                 .map(str::to_owned)
                 .unwrap_or_default(),
-            // The skull's two legs (`0x7cbb40`, §7-VERIFIED): a WORLD BOSS — creature-
+            // 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,
@@ -829,7 +826,9 @@ fn drive_vplates(
             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(
-                    benilla_protocol::guid::entry(guid.0).and_then(|e| names.creature_record(e)),
+                    store
+                        .and_then(|s| s.0.object_entry())
+                        .and_then(|e| names.creature_record(e)),
                     store,
                 ) == 3
                     || (rank <= 1 && level >= my_level + 10 && !unit_is_grey(my_level, level))
@@ -936,9 +935,9 @@ impl Plugin for VPlatesPlugin {
 mod tests {
     use super::*;
 
-    /// The client's own con law (§7): 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).
+    /// 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).
     #[test]
     fn con_color_matches_the_byte_table() {
         assert_eq!(con_color(30, 35), CON_RED);
@@ -1135,7 +1134,8 @@ mod tests {
     /// [`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, §8 Q4).
+    /// Below the knee the diagonal rules unchanged (a smaller window shrinks the plate,
+    /// `0x41ad10`).
     #[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/weapon_trail.rs b/crates/benilla-app/src/weapon_trail.rs
index b7e67b79..b9926eb8 100644
--- a/crates/benilla-app/src/weapon_trail.rs
+++ b/crates/benilla-app/src/weapon_trail.rs
@@ -1,5 +1,5 @@
 //! The weapon **swing trail** — `SpellVisualKit` CharProc type **8**, the ribbon a melee ability
-//! smears behind its blade (wow-re `charproc8-weapon-trail.md`, §5-verified end to end).
+//! smears behind its blade.
 //!
 //! 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
@@ -32,8 +32,7 @@
 //!
 //! 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, derived at the bytes
-//! in wow-re `format7-lighting-term.md`:
+//! contradiction and it is not a no-op — it selects a specific, reduced term:
 //!
 //! ```text
 //! out = (Σ enabled lights' Ambient) × authoredColour  +  inherited material Emissive
@@ -56,18 +55,17 @@
 //! 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`). Both halves are
-//! four-way byte-derived (wow-re `format7-lighting-term.md`, `part-lit-normal-space.md` §6):
+//! the wearer's own by aliasing (`[item+0x3b8] = [wearer+0x3b8]`, `0x718960`):
 //!
-//! - **outdoors** a unit's committed ambient IS the day/night ambient, so
+//! - **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)` — 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.
+//! - **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 that round did not pin, and `EMISSIVEMATERIALSOURCE` is set nowhere,
+//! 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
@@ -106,9 +104,9 @@ 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 — both of wow-re's independent derivations found it — 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.
+/// 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.
 const READ_MODULUS: u32 = 0x7f;
 
 /// `0x811278` in `.rdata` — `0x3b5a740e`, the nearest f32 to `1/300`, and the per-millisecond fade
@@ -219,7 +217,7 @@ struct Swing {
     /// `+0x610`.
     start_ms: u32,
     /// `+0x614` — the previous evaluation's timestamp. The step's first factor is the delta
-    /// against this, **not** the elapsed time (wow-re §7a: feeding elapsed makes `fadeStep`
+    /// against this, **not** the elapsed time (`0x6c65c1`: feeding elapsed makes `fadeStep`
     /// explode and kills the trail after one or two frames).
     last_ms: u32,
 }
@@ -293,8 +291,7 @@ impl Swing {
         }
         // `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, and wow-re reached it twice
-        // independently from opposite ends of the function — do not invert it.
+        // pair at the weapon lands at ≈ 0. Counter-intuitive but byte-exact: 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;
@@ -328,7 +325,7 @@ 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 (wow-re `charproc8-trail-draw-state.md` §10).
+    // the binary does.
     let raw = (f64::from(dt_ms) * f64::from(FADE_PER_MS) * f64::from(alpha)).trunc() as i64 as u32;
     if raw & 0xff >= 1 {
         raw
@@ -464,9 +461,9 @@ 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 (wow-re
-        // `charproc8-trail-draw-state.md` §1) — three of which contradict what a spell ribbon
-        // looks like it should be, and every one of the three is visible:
+        // 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 | |
         // |---|---|---|
diff --git a/crates/benilla-app/src/weapon_trail/tests.rs b/crates/benilla-app/src/weapon_trail/tests.rs
index c3618429..b6971751 100644
--- a/crates/benilla-app/src/weapon_trail/tests.rs
+++ b/crates/benilla-app/src/weapon_trail/tests.rs
@@ -16,8 +16,8 @@ fn armed(trail: TrailProc) -> WeaponTrail {
     t
 }
 
-/// wow-re §8's worked example: "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`'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.
 #[test]
 fn shipped_frame_gives_five_and_twenty() {
     for dt in [16, 17] {
@@ -113,21 +113,21 @@ 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");
-    // §8's nominal is 20 pairs (alpha 100 / fadeStep 5), but `fadeStep` is a TRUNCATED product,
+    // 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.
     assert_eq!(
         longest, 22,
         "the retained history peaks just over the nominal 20 pairs"
     );
-    // wow-re §8 estimates the visible life at "≈ duration/2 + (alpha/fadeStep)·dt ≈ duration",
-    // holding `fadeStep` constant. It is not constant — it is `trunc(dt·alpha/300)`, so it shrinks
+    // 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.
     assert_eq!(
         end, 1_250,
-        "a 600 ms kit is visible for 1.25 s, not §8's ~0.6 s"
+        "a 600 ms kit is visible for 1.25 s, not the constant-step ~0.6 s"
     );
 }
 
diff --git a/crates/benilla-app/src/world_state.rs b/crates/benilla-app/src/world_state.rs
index d75c7f5d..18edc4df 100644
--- a/crates/benilla-app/src/world_state.rs
+++ b/crates/benilla-app/src/world_state.rs
@@ -16,8 +16,7 @@
 //! 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** — carved 2026-08-25 (wow-re
-//! `system/ui/scratch/worldstate-ui-law.md`), correcting the assumption this module shipped with.
+//! **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]`,
@@ -45,7 +44,7 @@ impl WorldStates {
     ///
     /// 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`, wow-re `gossip-poi-marker.md` §8.2), so a landmark list is
+    /// (`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.
diff --git a/crates/benilla-app/src/world_state_ui.rs b/crates/benilla-app/src/world_state_ui.rs
index 707d4769..490b53d7 100644
--- a/crates/benilla-app/src/world_state_ui.rs
+++ b/crates/benilla-app/src/world_state_ui.rs
@@ -5,8 +5,7 @@
 //! 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.
 //!
-//! Everything below is the reference's, carved 2026-08-25 (wow-re
-//! `system/ui/scratch/worldstate-ui-law.md`).
+//! Everything below is the reference's.
 //!
 //! ## The list builder (`0x4c56e0`)
 //!
diff --git a/crates/benilla-app/tests/auction_frame.rs b/crates/benilla-app/tests/auction_frame.rs
index 5024cb79..207a0faf 100644
--- a/crates/benilla-app/tests/auction_frame.rs
+++ b/crates/benilla-app/tests/auction_frame.rs
@@ -61,6 +61,7 @@ fn load_ui_with_classes(s: &mut UiScript) {
     s.set_auction_item_classes(vec![AuctionCategory {
         class_id: 4,
         name: "Armor".into(),
+        has_subclass_filter: true,
         subclasses: vec![AuctionSubCategory {
             sub_id: 1,
             name: "Cloth".into(),
@@ -256,6 +257,208 @@ 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.
+#[test]
+fn the_auctions_tab_cannot_repaint_before_it_has_been_shown() {
+    let _data = benilla_formats::wow_data_or_skip!();
+    let mut s = UiScript::new().unwrap();
+    load_ui_with_classes(&mut s);
+    seat_player(&mut s, 500_000);
+    s.set_auction(Some(state(vec![row(
+        "Linen Cloth",
+        1000,
+        5000,
+        0,
+        "Seller",
+    )])));
+
+    // Open, and land a browse result — the whole of what a search does. Clean.
+    s.fire_event("AUCTION_HOUSE_SHOW", vec![]);
+    s.fire_event("AUCTION_ITEM_LIST_UPDATE", vec![]);
+    assert!(
+        s.take_errors().is_empty(),
+        "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.
+    s.fire_event("AUCTION_OWNED_LIST_UPDATE", vec![]);
+    let errors = s.take_errors();
+    assert!(
+        errors.iter().any(|e| e.contains("page")),
+        "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.
+    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![]);
+    assert!(
+        s.take_errors().is_empty(),
+        "and now the owned list may announce itself"
+    );
+}
+
+/// 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.
+#[test]
+fn only_the_bids_pane_gets_its_page_without_being_opened() {
+    let _data = benilla_formats::wow_data_or_skip!();
+    let mut s = UiScript::new().unwrap();
+    load_ui_with_classes(&mut s);
+
+    let page = |s: &UiScript, pane: &str| {
+        s.eval::<String>(&format!("return tostring({pane}.page)"))
+            .unwrap()
+    };
+
+    // At load, with no session: no pane has been shown, so none has a page.
+    for pane in [
+        "AuctionFrameBrowse",
+        "AuctionFrameBid",
+        "AuctionFrameAuctions",
+    ] {
+        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.
+    seat_player(&mut s, 500_000);
+    s.set_auction(Some(state(vec![row(
+        "Linen Cloth",
+        1000,
+        5000,
+        0,
+        "Seller",
+    )])));
+    s.fire_event("AUCTION_HOUSE_SHOW", vec![]);
+    assert_eq!(page(&s, "AuctionFrameBrowse"), "0");
+    assert_eq!(
+        page(&s, "AuctionFrameBid"),
+        "0",
+        "hidden=\"false\": the Bids pane rode the window up and back down"
+    );
+    assert!(
+        !s.eval::<bool>("return AuctionFrameBid:IsShown()").unwrap(),
+        "and it is not the visible tab"
+    );
+    assert_eq!(
+        page(&s, "AuctionFrameAuctions"),
+        "nil",
+        "the Auctions pane is the one an unowed event can still kill"
+    );
+    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.
+#[test]
+fn the_show_cascade_notifies_the_bids_pane_once_and_keeps_its_page() {
+    let _data = benilla_formats::wow_data_or_skip!();
+    let mut s = UiScript::new().unwrap();
+    load_ui_with_classes(&mut s);
+    seat_player(&mut s, 500_000);
+    s.set_auction(Some(state(vec![row(
+        "Linen Cloth",
+        1000,
+        5000,
+        0,
+        "Seller",
+    )])));
+
+    // Both handlers are called by global name from their `<OnShow>`, so wrapping the globals
+    // records the order the cascade actually fired them in.
+    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",
+    )
+    .unwrap();
+    let order = |s: &UiScript| {
+        s.eval::<String>("return table.concat(ShowOrder, \",\")")
+            .unwrap()
+    };
+    let page = |s: &UiScript| {
+        s.eval::<String>("return tostring(AuctionFrameBid.page)")
+            .unwrap()
+    };
+
+    s.fire_event("AUCTION_HOUSE_SHOW", vec![]);
+    assert_eq!(
+        order(&s),
+        "window,pane",
+        "OURS, and a known deviation (2317): the reference's cascade is post-order, \"pane,window\""
+    );
+    assert_eq!(
+        page(&s),
+        "0",
+        "the pane the XML leaves shown takes its page riding the window up — this is what keeps a \
+         mis-aimed AUCTION_BIDDER_LIST_UPDATE off the nil-page path"
+    );
+    assert_eq!(
+        s.take_auction_bidder_query(),
+        Some(0),
+        "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.
+    s.run("HideUIPanel(AuctionFrame)").unwrap();
+    let _ = s.take_auction_close();
+    s.fire_event("AUCTION_HOUSE_SHOW", vec![]);
+    assert_eq!(
+        order(&s),
+        "window,pane,window",
+        "the reopen notifies the window and not the pane it left hidden"
+    );
+    assert_eq!(page(&s), "0", "kept from the first open, not re-assigned");
+    assert_eq!(
+        s.take_auction_bidder_query(),
+        None,
+        "and the reopen puts no second bids query on the wire"
+    );
+    assert!(s.errors().is_empty(), "{:?}", s.errors());
+}
+
 /// The part that proves it works: a fed snapshot paints the Browse rows.
 #[test]
 fn the_browse_list_populates_from_the_fed_snapshot() {
@@ -514,7 +717,12 @@ 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);
-    assert_eq!(query.class, Some(1), "the selected class row, 1-based");
+    // The stock Lua hands over the class row's POSITION (1); the wire carries its item class id.
+    assert_eq!(
+        query.class,
+        Some(4),
+        "Armor is item class 4, not menu row 1"
+    );
     assert!(query.usable_only);
     assert_eq!(query.page, 0);
     assert!(s.errors().is_empty(), "clean search: {:?}", s.errors());
diff --git a/crates/benilla-app/tests/common/mod.rs b/crates/benilla-app/tests/common/mod.rs
index ade99dec..14ce592c 100644
--- a/crates/benilla-app/tests/common/mod.rs
+++ b/crates/benilla-app/tests/common/mod.rs
@@ -106,7 +106,7 @@ const UIPARENT_STAND_INS: &str = r#"
     PETACTIONBAR_XPOS = PETACTIONBAR_XPOS or 36
 
     -- The frames these three read UNGUARDED, seated on the call rather than at load: a frame's
-    -- publish to _G is non-overwriting (RF-0023), so a stand-in seated before the real file loads
+    -- publish to _G is non-overwriting (0x701bd0), so a stand-in seated before the real file loads
     -- would shadow the real window for good.
     local function benilla_seat(names)
         for _, name in ipairs(names) do
diff --git a/crates/benilla-app/tests/item_text_frame.rs b/crates/benilla-app/tests/item_text_frame.rs
index 538be523..f7f01b5f 100644
--- a/crates/benilla-app/tests/item_text_frame.rs
+++ b/crates/benilla-app/tests/item_text_frame.rs
@@ -83,10 +83,10 @@ 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 (wow-re
-/// `simplehtml-markup-engine.md` §5.1; 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.
+/// `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.
 fn page_blocks(s: &UiScript) -> Vec<String> {
     use benilla_ui::script::QuadContent;
     s.extract()
@@ -249,7 +249,7 @@ fn closing_queues_the_close_intent() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **B240's render half, on the reported page.** Goudy's plaque body (`page_text` 2676, the
+/// **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
@@ -314,16 +314,15 @@ fn the_reported_html_page_draws_as_blocks_not_as_its_own_markup() {
     );
 }
 
-/// **B342, on the reported page, through the real archives.** Goudy, 2026-08-27 (`#bugs`
-/// `1542371921486811236`): *"html images in books are not scaled correctly"* — the Alliance crest
-/// on *A Treatise on Military Ranks* drawn several times the reference's size with the page's own
-/// text over it, beside a 1.12.1 shot of the same page for comparison.
+/// **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 (wow-re `region-size-fallback.md` §2, decision
-/// 1349). `Interface\PvPRankBadges\PvPRankAlliance` is a 128×128 BLP, so the crest is a 128-unit
+/// 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
@@ -443,7 +442,7 @@ fn the_reported_book_crest_draws_at_the_blps_own_size() {
     }
 }
 
-/// **B288, closed at the reported symptom** (CarlG, decision 1507): the Verdant Note open from
+/// **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
diff --git a/crates/benilla-app/tests/message_keys.rs b/crates/benilla-app/tests/message_keys.rs
index 25a673b3..06d070b5 100644
--- a/crates/benilla-app/tests/message_keys.rs
+++ b/crates/benilla-app/tests/message_keys.rs
@@ -97,7 +97,7 @@ 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
-    /// `net::apply::pet` (errorId 337, both pet handlers' NOPATH arm). A fourth entry here is a
+    /// `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*
diff --git a/crates/benilla-app/tests/reference_strings.rs b/crates/benilla-app/tests/reference_strings.rs
index 70ec307c..73831730 100644
--- a/crates/benilla-app/tests/reference_strings.rs
+++ b/crates/benilla-app/tests/reference_strings.rs
@@ -72,10 +72,8 @@ fn is_instrument(rel: &str) -> bool {
     [
         "/capture/",
         "/bin/",
-        "/probes/",
         "debug_panel",
         "shape_gate",
-        "framexml_diff",
         "resolve_bench",
     ]
     .iter()
diff --git a/crates/benilla-app/tests/talent_frame.rs b/crates/benilla-app/tests/talent_frame.rs
index 89ceb6c4..3e3a1152 100644
--- a/crates/benilla-app/tests/talent_frame.rs
+++ b/crates/benilla-app/tests/talent_frame.rs
@@ -347,7 +347,7 @@ fn an_unavailable_talent_reaches_the_renderer_desaturated() {
     );
     // 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 (wow-re `texture-desaturate-law.md` §6.2; decision 1330 corrected 1327 here). It is
+    // 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.
     assert!(
diff --git a/crates/benilla-app/tests/tradeskill_frame.rs b/crates/benilla-app/tests/tradeskill_frame.rs
index 9799d953..8adfc817 100644
--- a/crates/benilla-app/tests/tradeskill_frame.rs
+++ b/crates/benilla-app/tests/tradeskill_frame.rs
@@ -117,6 +117,7 @@ fn pump(script: &mut UiScript) {
 
 #[test]
 fn collapse_all_tab_and_filter_dropdowns_work_end_to_end() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
 
@@ -208,6 +209,7 @@ fn collapse_all_tab_and_filter_dropdowns_work_end_to_end() {
 /// deviation note); this pins the load + the text attribute + the hidden-in-practice state.
 #[test]
 fn craft_collapse_tab_loads_with_text_and_stays_hidden_for_a_flat_list() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
 
@@ -243,6 +245,7 @@ fn craft_collapse_tab_loads_with_text_and_stays_hidden_for_a_flat_list() {
 /// test going red.
 #[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);
 
@@ -386,6 +389,7 @@ fn reagent_slots_carry_the_questitemtemplate_shape_in_both_windows() {
 /// the tooltip it opens happens to be empty in a headless VM.
 #[test]
 fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
     s.set_trade_skill(Some(state()));
@@ -481,6 +485,7 @@ fn a_row_click_shows_the_selection_glow_and_a_row_hover_shows_nothing() {
 /// colour off the extracted text quad, not off any Lua state, so it fails if either half regresses.
 #[test]
 fn a_hovered_or_selected_recipe_row_paints_its_label_white() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
     s.set_screen_size(1024.0, 768.0);
@@ -593,6 +598,7 @@ fn a_hovered_or_selected_recipe_row_paints_its_label_white() {
 /// (decision 1605).
 #[test]
 fn a_hovered_or_selected_craft_row_paints_its_label_white() {
+    benilla_formats::wow_data_or_skip!();
     let mut s = UiScript::new().unwrap();
     load_ui(&s);
     s.set_screen_size(1024.0, 768.0);
diff --git a/crates/benilla-app/tests/ui_script_wall.rs b/crates/benilla-app/tests/ui_script_wall.rs
index 9d65e37a..ada6b811 100644
--- a/crates/benilla-app/tests/ui_script_wall.rs
+++ b/crates/benilla-app/tests/ui_script_wall.rs
@@ -18,39 +18,62 @@
 //! 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.
 
 use std::path::{Path, PathBuf};
 
-/// The standing count. **2026-09-16, 164** — measured the day the instrument was built, against
-/// 1177's 141 five weeks earlier. It moved twice on that one day, for two different files, and
-/// both reasons are kept because each is a different kind of legitimate:
+/// Where a file that names the VM stands under 1177 (decision 2338).
+#[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.
+    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.
+    Feed,
+    /// `capture/` — a live probe that asks the STOCK binding on purpose (2283, 2290): fed a
+    /// model value it would prove nothing. Reported.
+    Probe,
+    /// A test module beside the code it tests. Reported.
+    Test,
+}
+
+fn family(rel: &str) -> Family {
+    let file = rel.rsplit('/').next().unwrap_or(rel);
+    if rel.starts_with("capture/") {
+        Family::Probe
+    } else if file == "tests.rs" || file.ends_with("_tests.rs") || rel.contains("/tests/") {
+        Family::Test
+    } else if rel.starts_with("ui_") {
+        Family::Feed
+    } else {
+        Family::Game
+    }
+}
+
+/// The standing count of **`Game`** files — gameplay code outside the feeds that names the VM.
 ///
-/// - **165 (decision 2279)** — `game_plugins.rs`, the structural test for the VM's one-shot
-///   consumers, which has to name the identifier it scans for. A test *about* the wall, not a file
-///   that learned the VM exists.
-/// - **166 (decision 2283)** — `capture/probe_stone.rs`, the meeting-stone live probe, joining the
-///   fifteen sibling probes that read the VM *on purpose*. A probe's whole value is that it asks
-///   the **stock** binding (`IsInMeetingStoneQueue()`, `MiniMapMeetingStoneFrame:IsShown()`)
-///   rather than our own mirror of it, so feeding it a model value would make it prove nothing.
-////// - **167 (decision 2290)** — `capture/probe_bg.rs`, the inside-a-battleground live probe, the
-///   same class again and for the same reason, sharpened: it takes the port through the stock
-///   `AcceptBattlefieldPort(slot, 1)` and reads the battleground back through
-///   `GetNumWorldStateUI()`, `GetBattlefieldStatus()` and a Lua event tap. A probe that asked our
-///   own model instead could not have found what this one did — that the battleground's
-///   `CHAT_MSG_BG_SYSTEM_NEUTRAL` lines reach the interface, which no app-side reading shows.
-///
-/// The ratchet is for *production* feed code. Both numbers still went up, and both are written
-/// down — which is the whole point of it, and why two sessions raising it the same day collided
-/// here instead of quietly passing each other.
-const CEILING: usize = 167;
+/// **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;
 
 /// How far under [`CEILING`] the count may sit before the test asks for the ceiling to follow it.
-const SLACK: usize = 8;
+const SLACK: usize = 4;
 
 #[test]
 fn the_vm_is_named_by_no_more_files_than_the_ceiling_says() {
     let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
-    let mut files: Vec<String> = rs_files(&src)
+    let mut files: Vec<(Family, String)> = rs_files(&src)
         .into_iter()
         .filter_map(|p| {
             let rel = p
@@ -62,28 +85,39 @@ fn the_vm_is_named_by_no_more_files_than_the_ceiling_says() {
                 return None;
             }
             let text = std::fs::read_to_string(&p).ok()?;
-            names_ident(&text, "UiScript").then_some(rel)
+            names_ident(&text, "UiScript").then(|| (family(&rel), rel))
         })
         .collect();
     files.sort();
-    let n = files.len();
-    eprintln!("files outside ui_script/ naming UiScript: {n} (ceiling {CEILING}, slack {SLACK})");
+    let count = |f: Family| files.iter().filter(|(fam, _)| *fam == f).count();
+    let n = count(Family::Game);
+    eprintln!(
+        "files outside ui_script/ naming UiScript: {} — {n} game (ceiling {CEILING}, slack \
+         {SLACK}), {} feeds, {} probes, {} tests",
+        files.len(),
+        count(Family::Feed),
+        count(Family::Probe),
+        count(Family::Test),
+    );
     if std::env::var("WOW_UISCRIPT_DUMP").is_ok() {
-        eprintln!("{}", files.join("\n"));
+        for (fam, rel) in &files {
+            eprintln!("  {fam:?}\t{rel}");
+        }
     }
     assert!(
         n <= CEILING,
-        "{n} files outside ui_script/ name UiScript; the ceiling is {CEILING}.\n\
-         A new file learned that the FrameXML VM exists. Decision 1177's line is that only the \
-         feed layer may know; either feed a model value instead, or — if this file genuinely is \
-         feed code — raise CEILING here with the reason, the way world_api_wall.rs requires.\n\
-         WOW_UISCRIPT_DUMP=1 lists the files."
+        "{n} gameplay files outside ui_script/ and the feeds name UiScript; the ceiling is \
+         {CEILING}.\nA new file learned that the FrameXML VM exists. Decision 1177's line is that \
+         only the feed layer may know: feed a model value instead, or — if this file genuinely is \
+         feed code — it belongs under a `ui_*` module, and a probe under `capture/`. Raise CEILING \
+         here only with the reason, the way world_api_wall.rs requires.\nWOW_UISCRIPT_DUMP=1 lists \
+         the files by family."
     );
     assert!(
         n + SLACK >= CEILING,
-        "only {n} files name UiScript and the ceiling still says {CEILING}. Lower CEILING to {n} \
-         in this file so the next coupling has to earn its place — the ratchet only holds if the \
-         number follows the work down."
+        "only {n} gameplay files name UiScript and the ceiling still says {CEILING}. Lower CEILING \
+         to {n} in this file so the next coupling has to earn its place — the ratchet only holds \
+         if the number follows the work down."
     );
 }
 
diff --git a/crates/benilla-app/tests/world_api_wall.rs b/crates/benilla-app/tests/world_api_wall.rs
index 1acd7a17..246c71ae 100644
--- a/crates/benilla-app/tests/world_api_wall.rs
+++ b/crates/benilla-app/tests/world_api_wall.rs
@@ -21,6 +21,16 @@
 //! 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.
 
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
@@ -110,7 +120,13 @@ const INSTRUMENT_ROOTS: &[&str] = &["art_scope", "debug_panel", "perf", "pipe_wa
 /// 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.
-const INSTRUMENT_CONSUMERS: &[&str] = &["crash", "debug_panel", "perf", "pipe_warm"];
+///
+/// `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.
+const INSTRUMENT_CONSUMERS: &[&str] = &["capture", "crash", "debug_panel", "perf", "pipe_warm"];
 
 /// Is this file one of the app-side instruments?
 fn is_instrument_consumer(rel: &str) -> bool {
@@ -118,8 +134,223 @@ fn is_instrument_consumer(rel: &str) -> bool {
     INSTRUMENT_CONSUMERS.contains(&root)
 }
 
-/// The gate. 1163 sets it at forty; this is the current standing count, ratcheted down by each
-/// commit that lands a DOWN or a CLOSE from 1164's sort.
+/// **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.
+const PUBLISHED: &[(&str, &str)] = &[
+    ("bgwin::BgWinPlugin", "wall"),
+    ("bgwin::background_run", "2338"),
+    ("bgwin::no_pixel_run", "2338"),
+    ("billboard::BillboardCard", "1164"),
+    ("boot::tuned_default_plugins", "2338"),
+    ("build_id::BuildId", "2338"),
+    ("build_id::banner", "1179"),
+    ("collision::ColliderEpoch", "1384"),
+    ("collision::MoverTraceExclusions", "1767"),
+    ("collision::WorldCollision", "1164"),
+    ("decal::WorldDecal", "1164"),
+    ("dev_state::STILL_INPUTS_CHANGED", "1979"),
+    ("doodad_anim::AnimMatPart", "2295"),
+    ("doodad_anim::DoodadAnimHost", "1365"),
+    ("doodad_anim::MatAnim", "1164"),
+    ("doodad_anim::TintLoop", "2295"),
+    ("doodad_anim::UvLoops", "2282"),
+    ("doodad_anim::register_entity_uv", "2295"),
+    ("doodad_anim::register_fx_uv", "2282"),
+    ("doodad_anim::register_tint", "2295"),
+    ("doodad_anim::spawn_anim_host", "1164"),
+    ("ffx_glow::FfxBackdrop", "2234"),
+    ("ffx_glow::FfxGlow", "1164"),
+    ("ffx_glow::GlueFfx", "1731"),
+    ("final_pass::FinalPassTarget", "2206"),
+    ("instance_tint::InstanceTintMirrors", "1731"),
+    ("instance_tint::InstanceTints", "1164"),
+    ("interact::PickMesh", "1164"),
+    ("interact::WorldObject", "1164"),
+    ("interact::WorldPick", "1164"),
+    ("interact::cast_pick_ray", "1164"),
+    ("interior::NodeAmbient", "2079"),
+    ("lighting::LightBlob", "1164"),
+    ("lighting::WorldTime", "1167"),
+    ("lighting::WowLighting", "1164"),
+    ("mac_quit::MacQuitPlugin", "1528"),
+    ("mat_anim_table::MatAnimMirrors", "2023"),
+    ("mat_anim_table::MatAnimTable", "1381"),
+    ("mat_anim_table::affine_row", "2019"),
+    ("mesh_tag::HIGHLIGHT_BIT", "1164"),
+    ("model_fade::ModelFade", "1164"),
+    ("model_fade::ParentModel", "1164"),
+    ("model_fade::RenderFade", "1164"),
+    ("model_fade::UnitRenderAlpha", "wall"),
+    ("model_forms::ModelForms", "1167"),
+    ("model_render::BatchVariants", "1164"),
+    ("model_render::EntityUvLane", "2295"),
+    ("model_render::M2BatchMaterials", "1164"),
+    ("model_render::ModelKind", "1164"),
+    ("model_render::ModelPart", "1164"),
+    ("model_render::lazy::realize", "1940"),
+    ("modkeys::SyntheticHold", "wall"),
+    ("particles::ViewThrottled", "1559"),
+    ("particles::render::EFFECT_DRAW_STATS", "1955"),
+    ("particles::spawn_emitter", "1164"),
+    ("ride_frame::RideFrame", "1661"),
+    ("rig_anim::AnimParked", "wall"),
+    ("rig_anim::GlobalSeqDrive", "wall"),
+    ("rig_anim::PosePost", "wall"),
+    ("rig_anim::RigAnchor", "wall"),
+    ("rig_anim::RigFrame", "wall"),
+    ("rig_anim::RigPose", "wall"),
+    ("rig_palette::RigPalettes", "1164"),
+    ("rig_palette::RigSkin", "1164"),
+    ("rig_rider::RigRider", "1609"),
+    ("schedule::WorldLive", "1160"),
+    ("schedule::WorldStage", "1164"),
+    ("sky_order::Rung", "wall"),
+    ("terrain_stream::SPAWN_XY", "wall"),
+    ("terrain_stream::ViewFocus", "1160"),
+    ("terrain_stream::WorldLoadProgress", "wall"),
+    ("thread_qos::QosClass", "2338"),
+    ("thread_qos::ThreadQosPlugin", "wall"),
+    ("thread_qos::promote_current_thread", "2338"),
+    ("view::MsaaFormats", "1632"),
+    ("view::MsaaSetting", "1629"),
+    ("view::ViewDistance", "1164"),
+    ("view::Viewer", "wall"),
+    ("view::WorldCamera", "1164"),
+    ("vis_chain::VisChainOnly", "1441"),
+    ("weather::WeatherMessage", "1164"),
+    ("weather::WeatherState", "2181"),
+    ("wmo_portal::room_pvs_visible", "1475"),
+    ("world_census::CensusReport", "1164"),
+    ("world_census::WorldCensus", "1164"),
+    ("world_map::CurrentMap", "1164"),
+    ("world_map::MapChange", "1164"),
+    ("world_plugins::WorldPlugins", "1164"),
+    ("world_point::Subject", "1164"),
+    ("world_point::WorldPoint", "1164"),
+    ("world_unit::ViewerUnit", "wall"),
+    ("world_unit::WorldUnit", "wall"),
+    ("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.
+const SORTED_LEAKS: &[(&str, &str)] = &[
+    ("billboard::BillboardJointRig", "CLOSE/absorb"),
+    ("billboard::BillboardPlace", "CLOSE/absorb"),
+    ("billboard::billboard_basis", "CLOSE/move-engine"),
+    ("billboard::billboard_joint_palette", "CLOSE/absorb"),
+    ("clutter::ClutterConfig", "CLOSE/absorb"),
+    ("collision::PickOccluder", "CLOSE/absorb"),
+    ("decal::DecalFrame", "CLOSE/absorb"),
+    ("doodad_anim::DoodadAnimTier", "CLOSE/absorb"),
+    ("doodad_anim::TintAnimMaterials", "CLOSE/move-engine"),
+    ("doodad_anim::UvAnimMaterials", "CLOSE/move-engine"),
+    ("doodad_anim::classify", "CLOSE/absorb"),
+    ("doodad_anim::sample_mat_anim", "CLOSE/invert"),
+    ("doodad_anim::wants_rig", "CLOSE/move-engine"),
+    ("entity_shade::GroundShade", "CLOSE/absorb"),
+    ("ffx_glow::FfxDeathFade", "CLOSE/absorb"),
+    ("instance_tint::IDENTITY", "CLOSE/absorb"),
+    ("instance_tint::pack", "CLOSE/absorb"),
+    ("interact::PickBox", "CLOSE/absorb"),
+    ("interact::WorldClick", "CLOSE/move-game"),
+    ("interact::WorldRightClick", "CLOSE/move-game"),
+    ("interact::WorldRightPress", "CLOSE/move-game"),
+    ("interact::cast_pick_ray_inflated", "CLOSE/absorb"),
+    ("interior::BodyBakeCenter", "CLOSE/absorb"),
+    ("interior::ContainmentAttach", "CLOSE/absorb"),
+    ("interior::InteriorLit", "CLOSE/invert"),
+    ("interior::InteriorReauthor", "CLOSE/invert"),
+    ("interior::classify_entity_interior", "CLOSE/absorb"),
+    ("interior::part_interior_lit", "CLOSE/absorb"),
+    ("lighting::GameClock", "CLOSE/absorb"),
+    ("lighting::PropProbeSlot", "CLOSE/move-engine"),
+    ("lighting::PropProbes", "CLOSE/move-engine"),
+    ("liquid::WaterChunkInfo", "CLOSE/absorb"),
+    ("map_proj::WorldProj", "CLOSE/move-game"),
+    ("map_proj::ZoneRect", "CLOSE/move-game"),
+    ("mesh_tag::describe", "CLOSE/absorb"),
+    ("mesh_tag::with_alpha", "CLOSE/invert"),
+    ("model_fade::DespawnFade", "CLOSE/move-game"),
+    ("model_fade::FadeMaterials", "CLOSE/absorb"),
+    ("model_fade::FadeSet", "CLOSE/absorb"),
+    ("model_fade::JoinedFade", "CLOSE/absorb"),
+    ("model_fade::MAX_MODEL_CHAIN", "CLOSE/invert"),
+    ("model_fade::PartFade", "CLOSE/absorb"),
+    ("model_fade::PendingAppearFade", "CLOSE/invert"),
+    ("model_fade::UnitAppearFade", "CLOSE/move-game"),
+    ("model_fade::apply_render_fade", "CLOSE/absorb"),
+    ("model_fade::fade_alpha", "CLOSE/absorb"),
+    ("model_fade::join_unit_appear_fade", "CLOSE/absorb"),
+    ("model_render::FarSideOfWater", "CLOSE/invert"),
+    ("model_render::FarSideTwins", "CLOSE/invert"),
+    ("model_render::ModelVisSet", "CLOSE/absorb"),
+    ("model_render::ShadeSel", "CLOSE/absorb"),
+    ("model_render::far_resolved", "CLOSE/invert"),
+    ("model_render::replace_fog_policy", "CLOSE/absorb"),
+    ("modkeys::DEV_CHORD", "CLOSE/move-engine"),
+    ("modkeys::dev_chord", "CLOSE/move-engine"),
+    ("particles::EmitClock", "CLOSE/absorb"),
+    ("particles::EmitterFade", "CLOSE/invert"),
+    ("particles::EmitterFrames", "CLOSE/absorb"),
+    ("particles::OwnerLoss", "CLOSE/absorb"),
+    ("particles::ParticleEmitter", "CLOSE/invert"),
+    ("particles::buffer::EffectLightOverride", "CLOSE/invert"),
+    ("particles::buffer::EffectQuads", "CLOSE/invert"),
+    ("particles::buffer::EffectVertex", "CLOSE/absorb"),
+    ("particles::buffer::WorldEffectDraw", "CLOSE/absorb"),
+    ("particles::buffer::begin_effect_frame", "CLOSE/absorb"),
+    ("ribbons::RibbonSeq", "CLOSE/absorb"),
+    ("ribbons::RibbonTrail", "CLOSE/invert"),
+    ("ribbons::spawn_ribbon", "CLOSE/absorb"),
+    ("rig_palette::RigPaletteMirrors", "CLOSE/absorb"),
+    ("rig_palette::RigPart", "CLOSE/absorb"),
+    ("rig_palette::RigStarved", "CLOSE/invert"),
+    ("rig_palette::rig_cost_enabled", "CLOSE/absorb"),
+    ("terrain_stream::AreaAuthoritySet", "CLOSE/absorb"),
+    ("terrain_stream::CurrentArea", "CLOSE/absorb"),
+    ("terrain_stream::PendingCollider", "CLOSE/move-engine"),
+    ("terrain_stream::PropLobeLight", "CLOSE/move-engine"),
+    ("terrain_stream::ShadeResolve", "CLOSE/move-engine"),
+    ("terrain_stream::SpawnedModel", "CLOSE/move-engine"),
+    ("terrain_stream::TerrainStreamer", "CLOSE/absorb"),
+    ("terrain_stream::build_collider_task", "CLOSE/move-engine"),
+    ("terrain_stream::doodad_ground_shade", "CLOSE/move-engine"),
+    ("terrain_stream::fold_interior_probe", "CLOSE/move-engine"),
+    ("terrain_stream::hex_word", "CLOSE/move-engine"),
+    ("terrain_stream::m2_anim_bound", "CLOSE/move-engine"),
+    ("terrain_stream::m2_fade", "CLOSE/move-engine"),
+    (
+        "terrain_stream::placement_collider_data",
+        "CLOSE/move-engine",
+    ),
+    ("terrain_stream::point_light", "CLOSE/absorb"),
+    ("terrain_stream::spawn_model_entities", "CLOSE/move-engine"),
+    ("view::CAM_FOVY", "CLOSE/absorb"),
+    ("view::FARCLIP_RANGE", "CLOSE/absorb"),
+    ("view::NEARCLIP_DEFAULT", "CLOSE/absorb"),
+    ("wmo_portal::UnitWmoRoom", "CLOSE/absorb"),
+    ("wmo_portal::WmoPortalInstance", "CLOSE/absorb"),
+    ("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
@@ -308,7 +539,7 @@ fn is_instrument_consumer(rel: &str) -> bool {
 /// 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 — wow-re `ghost-death-visuals.md` §6, report B49, decision 1481)
+/// 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
@@ -496,61 +727,127 @@ fn is_instrument_consumer(rel: &str) -> bool {
 /// 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.
-const CEILING: usize = 190;
+///
+/// **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.
+const LEAK_CEILING: usize = 107;
 
-/// How far under [`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.
-const SLACK: usize = 10;
+/// 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.
+const LEAK_SLACK: usize = 10;
 
 #[test]
 fn the_world_api_doorway_stays_shut() {
     let all = measure();
-    // Partition: 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.
+    // 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.
     let (probes, surface): (BTreeMap<_, _>, BTreeMap<_, _>) = all
         .into_iter()
         .partition(|(_, files)| files.iter().all(|f| is_instrument_consumer(f)));
-    let n = surface.len();
-    // Always say the number: `cargo test -p benilla-app --test world_api_wall -- --nocapture` is
-    // the one-command answer to "where is the wall now", which is asked on every unit of 1164's
-    // sort and used to need a deliberately-failing ceiling to get.
+    // Partition two (decision 2338): the doorway is the published API plus the leaks, and 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
+        .keys()
+        .filter(|k| sorted_by.contains_key(*k))
+        .copied()
+        .collect();
+    assert!(
+        both.is_empty(),
+        "an item cannot be both published and a sorted leak: {both:?}"
+    );
+    let (published, leaks): (BTreeMap<_, _>, BTreeMap<_, _>) = surface
+        .into_iter()
+        .partition(|(k, _)| published_by.contains_key(k.as_str()));
+    let n = leaks.len();
+    let sorted = leaks
+        .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".
     eprintln!(
-        "world API surface: {n} items (ceiling {CEILING}, slack {SLACK})  \
-         + {} named only by the instruments",
+        "world API surface: {} items — {n} leaks (ceiling {LEAK_CEILING}, slack {LEAK_SLACK}; \
+         {sorted} sorted by 1164, {} unsorted), {} published; + {} named only by the instruments",
+        published.len() + n,
+        n - sorted,
+        published.len(),
         probes.len()
     );
 
-    // `WOW_API_DUMP=1` prints the surface itself, most-named first. 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 (a second scanner disagreeing by
-    // one is how this got added).
+    // 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.
+    let stale: Vec<&str> = PUBLISHED
+        .iter()
+        .map(|(k, _)| *k)
+        .filter(|k| !published.contains_key(*k) && !probes.contains_key(*k))
+        .chain(
+            SORTED_LEAKS
+                .iter()
+                .map(|(k, _)| *k)
+                .filter(|k| !leaks.contains_key(*k) && !probes.contains_key(*k)),
+        )
+        .collect();
+    assert!(
+        stale.is_empty(),
+        "rows in PUBLISHED / SORTED_LEAKS that no game file names any more — delete them (a \
+         closed leak is a deleted row; a published item nobody uses is not API):\n  {}",
+        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.
     if std::env::var("WOW_API_DUMP").is_ok() {
-        let mut rows: Vec<_> = surface.iter().map(|(k, v)| (v.len(), k)).collect();
-        rows.sort_by(|a, b| b.0.cmp(&a.0).then(a.1.cmp(b.1)));
-        eprintln!("{}", render(&rows));
-        let mut probe_rows: Vec<_> = probes.iter().map(|(k, v)| (v.len(), k)).collect();
-        probe_rows.sort_by(|a, b| b.0.cmp(&a.0).then(a.1.cmp(b.1)));
+        let tagged = |m: &BTreeMap<String, BTreeSet<String>>, tag: &dyn Fn(&str) -> String| {
+            let mut rows: Vec<_> = m
+                .iter()
+                .map(|(k, v)| (v.len(), format!("{k}  [{}]", tag(k))))
+                .collect();
+            rows.sort_by(|a, b| b.0.cmp(&a.0).then(a.1.cmp(&b.1)));
+            rows.iter()
+                .map(|(n, k)| format!("  {n:3} file(s)  {k}"))
+                .collect::<Vec<_>>()
+                .join("\n")
+        };
         eprintln!(
-            "--- named only by the instruments ---\n{}",
-            render(&probe_rows)
+            "--- leaks ---\n{}\n--- published ---\n{}\n--- named only by the instruments ---\n{}",
+            tagged(&leaks, &|k| sorted_by
+                .get(k)
+                .map_or_else(|| "unsorted".to_string(), |b| b.to_string())),
+            tagged(&published, &|k| published_by[k].to_string()),
+            tagged(&probes, &|k| published_by.get(k).map_or_else(
+                || "instrument".to_string(),
+                |b| format!("published {b}")
+            )),
         );
     }
 
-    if n > CEILING {
-        let fresh: Vec<_> = surface.iter().map(|(k, v)| (v.len(), k)).collect();
+    if n > LEAK_CEILING {
+        let fresh: Vec<_> = leaks
+            .iter()
+            .filter(|(k, _)| !sorted_by.contains_key(k.as_str()))
+            .map(|(k, v)| (v.len(), k))
+            .collect();
         panic!(
-            "world API surface is {n} items, ceiling is {CEILING}.\n\
-             Something new crossed the line. Either close it, or — if it is genuine engine API — \
-             raise the ceiling in this file WITH the justification, the way decision 1164 requires \
-             for every item in the PUBLISH bucket.\n\n{}",
+            "world API leaks: {n}, ceiling {LEAK_CEILING}.\n\
+             Something new crossed the line and no record publishes it. Either close it, or — if \
+             it is genuine engine API — add it to PUBLISHED with the record that says so (decision \
+             2338); never a bare number. The unsorted leaks on this tree:\n\n{}",
             render(&fresh)
         );
     }
     assert!(
-        n + SLACK >= CEILING,
-        "world API surface is down to {n} items and the ceiling still says {CEILING}. \
-         Lower CEILING to {n} in this file so the next leak has to earn its place — the ratchet \
+        n + LEAK_SLACK >= LEAK_CEILING,
+        "world API leaks are down to {n} and the ceiling still says {LEAK_CEILING}. Lower \
+         LEAK_CEILING to {n} in this file so the next leak has to earn its place — the ratchet \
          only holds if the number follows the work down."
     );
 }
@@ -758,7 +1055,7 @@ fn paths_in(text: &str, split: bool, want_engine: bool) -> Vec<(String, usize)>
     // `#[cfg(test)] pub(crate) use …;`) it ends at that statement's semicolon.
     let mut test_at: Option<i32> = None;
     let mut test_open = false;
-    for (n, line) in text.lines().enumerate() {
+    for (n, line) in logical_lines(text).iter().map(|(n, l)| (*n, l.as_str())) {
         let t = line.trim_start();
         if t.starts_with("#[cfg(test)]") {
             test_at = Some(depth);
@@ -851,6 +1148,46 @@ 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).
+fn logical_lines(text: &str) -> Vec<(usize, String)> {
+    fn open(s: &str) -> i32 {
+        s.matches('{').count() as i32 - s.matches('}').count() as i32
+    }
+    fn strip_comment(s: &str) -> &str {
+        s.find("//").map_or(s, |i| &s[..i])
+    }
+    let mut out = Vec::new();
+    let mut lines = text.lines().enumerate();
+    while let Some((n, line)) = lines.next() {
+        let t = line.trim_start();
+        let is_use = t.starts_with("use ")
+            || (t.starts_with("pub") && t.contains(" use ") && !t.contains('='));
+        if is_use && open(strip_comment(line)) > 0 {
+            let mut joined = strip_comment(line).trim_end().to_string();
+            let mut depth = open(&joined);
+            for (_, next) in lines.by_ref() {
+                let next = strip_comment(next);
+                joined.push(' ');
+                joined.push_str(next.trim());
+                depth += open(next);
+                if depth <= 0 {
+                    break;
+                }
+            }
+            out.push((n, joined));
+        } else {
+            out.push((n, line.to_string()));
+        }
+    }
+    out
+}
+
 fn is_ident(c: char) -> bool {
     c.is_alphanumeric() || c == '_'
 }
@@ -984,3 +1321,25 @@ fn render(items: &[(usize, &String)]) -> String {
         .collect::<Vec<_>>()
         .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.
+#[test]
+fn a_use_group_spanning_lines_counts_every_member() {
+    let text =
+        "use benilla_world::interact::{\n    PickParts,\n    ray_mesh_bounds, // a lead\n    \
+                ray_posed_mesh,\n};\nfn f() {}\n";
+    let mut found: Vec<String> = paths_in(text, true, true)
+        .into_iter()
+        .map(|(p, _)| p)
+        .collect();
+    found.sort();
+    assert_eq!(
+        found,
+        [
+            "interact::PickParts",
+            "interact::ray_mesh_bounds",
+            "interact::ray_posed_mesh"
+        ]
+    );
+}
diff --git a/crates/benilla-assets/Cargo.toml b/crates/benilla-assets/Cargo.toml
index 359e8062..0cd91ff2 100644
--- a/crates/benilla-assets/Cargo.toml
+++ b/crates/benilla-assets/Cargo.toml
@@ -9,10 +9,8 @@ description = "Bevy AssetSource + AssetLoaders over the WoW 1.12.1 MPQ patch cha
 workspace = true
 
 [features]
-# Forwarded dev/player seam (0026 · 1173/1174 · 1175). Default-on. `benilla-formats` must be taken
-# with `default-features = false` and its `dev` re-exported here: it is default-on there too, so
-# without this a `--no-default-features` player build gets the feature back through unification and
-# the binary carries the build machine's source-tree path after all.
+# The dev/player seam, on by default. `benilla-formats` comes in without default features and its
+# `dev` is forwarded here, or unification would put it back in a player build.
 default = ["dev"]
 dev = ["benilla-formats/dev"]
 
@@ -20,7 +18,7 @@ dev = ["benilla-formats/dev"]
 anyhow.workspace = true
 bevy.workspace = true
 benilla-formats = { path = "../benilla-formats", default-features = false }
-# Nearest-neighbour resize for off-Elwynn layer BLPs authored below LAYER_TEX_SIZE (texel
-# replication in gamma byte space — no averaging, so the C2 mid-tone darkening can't creep in).
+# Nearest-neighbour resize of layer BLPs smaller than `LAYER_TEX_SIZE`: texel replication in gamma
+# bytes, with no averaging to darken mid-tones.
 image = { version = "0.25", default-features = false }
 serde = { version = "1", features = ["derive"] }
diff --git a/crates/benilla-assets/examples/face_facing_at.rs b/crates/benilla-assets/examples/face_facing_at.rs
index ea97c4c9..6e935093 100644
--- a/crates/benilla-assets/examples/face_facing_at.rs
+++ b/crates/benilla-assets/examples/face_facing_at.rs
@@ -1,25 +1,13 @@
-//! Which way do the collidable faces under a world pin actually FACE — and would the reference
-//! block on them?
+//! Every walking-collidable WMO face under a world pin, with its height, its authored normal
+//! against a fall, and whether the reference blocks on it.
 //! `cargo run -p benilla-assets --example face_facing_at -- <map> <x> <y> <z> [wmo-substring]`
 //! e.g. `face_facing_at Kalimdor -8137.9 -4897.2 2.0 caverns`.
 //!
-//! The reference's movement collision is **one-sided** (decision 0967, wow-re
-//! `collision/scratch/wmo-movement-group-gate.md`): `0x671cc0` emits each candidate face's plane at
-//! the **unflipped file winding**, and `0x632700` then processes it only if `n·dir <= -1e-5`. A
-//! player falling straight down has `dir` = −up, so **a face blocks the fall iff its authored normal
-//! points up**. Ours is a parry trimesh — two-sided — so it blocks either way.
-//!
-//! This tool turns that difference into a number at a specific `.go xyz` pin: every walking-collidable
-//! WMO face whose footprint contains the pin, with its world height, its authored normal's up
-//! component, and the reference's verdict. Where a face reads `PASSES`, the reference falls through
-//! it and we stand on it.
-//!
-//! It goes through the **same transform the app bakes colliders with** — `wow_to_bevy` per vertex
-//! then the placement `Transform`, exactly as `terrain_stream::collider::placement_collider_data`
-//! does — so the geometry here is the geometry the player collides with, not a re-derivation. Both
-//! maps are proper rotations, so a face's winding (and the sign of `n·dir`) survives them.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! The reference's movement collision is one-sided: `0x671cc0` emits each face's plane at the file
+//! winding and `0x632700` processes it only if `n·dir <= -1e-5`, so a face blocks a fall only if
+//! its authored normal points up. Faces take the app's collider transform, `wow_to_bevy` then the
+//! placement `Transform`; both are proper rotations, so the winding and the sign of `n·dir`
+//! survive. Output is Blizzard data: never commit it.
 
 use benilla_assets::coords::{placement_rotation, wow_to_bevy};
 use bevy::prelude::*;
@@ -71,8 +59,7 @@ fn main() -> anyhow::Result<()> {
     for (model, transform, uid) in &placements {
         let stem = model.to_ascii_lowercase().replace('\\', "/");
         let stem = stem.strip_suffix(".wmo").unwrap_or(&stem).to_string();
-        // Walk group files by index — the same `<stem>_NNN.wmo` naming the loader uses. A gap is not
-        // expected, but tolerate a few misses rather than trusting a count we did not read.
+        // Group files by index, `<stem>_NNN.wmo` as the loader names them, tolerating a few misses.
         let (mut gi, mut misses) = (0u32, 0u32);
         while misses < 4 {
             let Ok(gbytes) = chain.read_file(&format!("{stem}_{gi:03}.wmo")) else {
@@ -81,8 +68,7 @@ fn main() -> anyhow::Result<()> {
                 continue;
             };
             misses = 0;
-            // The WALKING gather — the player-body audience, skip DETAIL (`0x04`). Identical call to
-            // the one the WMO asset loader makes.
+            // The walking gather, DETAIL (`0x04`) skipped, as the WMO loader makes it.
             let (mut pos, mut idx) = (Vec::new(), Vec::new());
             benilla_formats::accumulate_wmo_group_collision(&gbytes, &mut pos, &mut idx);
             let verts: Vec<Vec3> = pos
@@ -131,7 +117,7 @@ fn main() -> anyhow::Result<()> {
     );
     let (mut blocks, mut passes) = (0usize, 0usize);
     for h in &hits {
-        // The pin is Bevy-space; its Y is the WoW Z the tester read off the panel.
+        // The pin is Bevy-space; its Y is WoW Z.
         let reference_blocks = h.dot <= FACING_EPS;
         if reference_blocks {
             blocks += 1;
@@ -161,15 +147,15 @@ fn main() -> anyhow::Result<()> {
 struct Hit {
     /// World height (Bevy +Y = WoW +Z) where the pin's vertical line meets this face's plane.
     height: f32,
-    /// The authored winding normal dotted with the fall direction — the reference's gate input.
+    /// The authored winding normal dotted with the fall direction, the reference's gate input.
     dot: f32,
     group: u32,
     uid: u32,
     model: String,
 }
 
-/// Where the vertical line through `pin` meets the triangle's plane — `None` unless the pin's
-/// horizontal footprint is inside the triangle (the XZ projection in Bevy space, since +Y is up).
+/// Where the vertical through `pin` meets the triangle's plane, if the pin is inside its XZ
+/// projection.
 fn plane_height_under(pin: Vec3, tri: [Vec3; 3]) -> Option<f32> {
     let p = Vec2::new(pin.x, pin.z);
     let [a, b, c] = tri.map(|v| Vec2::new(v.x, v.z));
diff --git a/crates/benilla-assets/src/adt.rs b/crates/benilla-assets/src/adt.rs
index 86955f9c..249228c7 100644
--- a/crates/benilla-assets/src/adt.rs
+++ b/crates/benilla-assets/src/adt.rs
@@ -1,27 +1,9 @@
-//! ADT → terrain-tile asset loader.
-//!
-//! Decodes one vanilla ADT tile into an [`AdtTile`]: the decoded per-MCNK chunks + a
-//! [`ChunkShading`] per chunk (the splat-array indices resolved while packing), plus the tile's
-//! three `texture_2d_array`s — ground layers, per-chunk alpha (blend) maps, per-chunk MCSH shadow
-//! maps — and the raw doodad/WMO placement lists (for the spawn system to load as
-//! `M2Model`/`WmoModel`).
-//!
-//! **The loader ships no meshes.** A tile's ~256 chunk meshes used to be labeled sub-assets built
-//! here — which made a tile's landing atomic: the whole set hit the render world's
-//! extract/prepare in ONE frame (~80–105 ms of process CPU per fresh row, measured — the B181
-//! first-contact spike), and no app-side budget downstream of the load could spread work the
-//! loader had already packaged. The app builds each cell's mesh itself via [`chunk_to_mesh`], a
-//! few cells per frame (`terrain_stream::furnish`), so the render-world cost of a landing is
-//! paced at the only place pacing is possible: mesh-asset creation.
-//!
-//! Each chunk mesh carries its array indices on every one of its vertices — `COLOR` (4 layer
-//! indices) and `UV1` (alpha index `.x`, shadow index `.y`, `-1` = none) — which is why all 256
-//! chunks of a tile still share **one** material; the app's terrain material reads them.
-//!
-//! Layer textures are read via [`LoadContext::read_asset_bytes`] (raw bytes, dependency-tracked) and
-//! packed by [`crate::terrain`] — the BLP's authored mips verbatim (the C2 fidelity invariant).
-//! Materials, the collider, and the placement *models* are built by the app at spawn — this loader
-//! produces decoded data only.
+//! ADT terrain tile loader: the decoded MCNK chunks with a [`ChunkShading`] each, the tile's three
+//! `texture_2d_array`s (ground layers, per-chunk alpha, per-chunk MCSH shadow) and the raw doodad
+//! and WMO placements. It builds no meshes: a tile's chunk meshes built here would all land in one
+//! frame, so the app builds them a few per frame. Every vertex carries its chunk's array indices,
+//! `COLOR` the 4 layers and `UV1` the alpha (`.x`) and shadow (`.y`, `-1` none), so a whole tile
+//! shares one material.
 
 use std::collections::HashMap;
 
@@ -40,17 +22,12 @@ use crate::terrain::{
     alpha_array_image, layer_array_image, pack_layers, shadow_array_image, RawLayer, LAYER_TEX_SIZE,
 };
 
-/// A loaded ADT terrain tile: the decoded chunks + per-chunk shading indices + the tile's three
-/// texture arrays, plus the raw doodad/WMO placements (which the spawn system resolves to
-/// `M2Model`/`WmoModel` handles). Cell meshes are built by the app, per chunk, via
-/// [`chunk_to_mesh`] — see the module doc for why the loader ships none.
+/// A loaded ADT tile; the app builds its meshes with [`chunk_to_mesh`].
 #[derive(Asset, TypePath)]
 pub struct AdtTile {
-    /// The splat-array indices for each entry of `chunks` (index-parallel; a hole-emptied chunk
-    /// carries the default, which [`chunk_to_mesh`] never reads because it returns `None` first).
-    /// Resolved here because only the loader knows the arrays' layout — it packs them.
+    /// The array indices of each entry of `chunks`; a hole-emptied chunk carries the default.
     pub shading: Vec<ChunkShading>,
-    /// `texture_2d_array` of the tile's ground textures (the C2-faithful authored mip chains).
+    /// `texture_2d_array` of the tile's ground textures, authored mips verbatim.
     pub layer_array: Handle<Image>,
     /// `texture_2d_array` of per-chunk alpha (blend-weight) maps.
     pub alpha_array: Handle<Image>,
@@ -60,25 +37,20 @@ pub struct AdtTile {
     pub doodads: Vec<Doodad>,
     /// WMO building placements (raw WoW coords).
     pub wmos: Vec<WmoInstance>,
-    /// The tile's decoded per-MCNK chunks — the source the arrays were built from and the cell
-    /// meshes are built from ([`chunk_to_mesh`]), kept resident so the app can derive everything
-    /// else it owes the tile: the terrain collider, the MCLQ liquid surfaces (each
-    /// `ChunkMesh.liquid`) and the ground-clutter scatter (per-chunk layers/normals/MCSH + the
-    /// app-side ground-effect catalog). Bounded by the loaded-tile count; the heaviest field on the
-    /// asset, carried because clutter/liquid are app concerns (the loader stays catalog-independent).
+    /// The decoded MCNK chunks, kept resident: the app derives the collider, the MCLQ liquids and
+    /// the ground clutter from them.
     pub chunks: Vec<ChunkMesh>,
 }
 
-/// One drawn chunk's resolved splat indices — everything [`chunk_to_mesh`] needs beyond the
-/// decoded [`ChunkMesh`] itself. Uniform across the chunk's own vertices by construction.
+/// One drawn chunk's array indices, uniform over its vertices.
 #[derive(Clone, Copy)]
 pub struct ChunkShading {
-    /// The chunk's up-to-4 layer-array indices (vertex `COLOR`; unused slots repeat slot 0, whose
-    /// alpha weight is 0, so they never show).
+    /// Up to 4 layer-array indices (vertex `COLOR`); an unused slot repeats slot 0 and never shows,
+    /// as its alpha weight is 0.
     pub layers: [u32; 4],
-    /// The chunk's alpha-array index (vertex `UV1.x`; 0 — a weight-0 slot — when it has no map).
+    /// The alpha-array index (vertex `UV1.x`); 0 when the chunk has no map.
     pub alpha: u32,
-    /// The chunk's shadow-array index (vertex `UV1.y`; `-1.0` = no MCSH shadow map).
+    /// The shadow-array index (vertex `UV1.y`); `-1.0` when there is no MCSH map.
     pub shadow: f32,
 }
 
@@ -92,33 +64,17 @@ impl Default for ChunkShading {
     }
 }
 
-/// Build one drawn MCNK chunk's render mesh (Bevy space, absolute world coords) — called by the
-/// app a few cells per frame, never by the loader (see the module doc: a loader-built set lands
-/// atomically, and the landing IS the B181 first-contact spike).
-///
-/// **Per chunk, not per tile, because the cull's unit is the chunk** (decision 0780): the
-/// exterior-scene cull tests one AABB per drawn object, and the reference's object there is the
-/// 33.333 yd cell (`0x683bf0`), never the 533 yd tile — a slab the camera stands on intersects
-/// every portal window, so it could never be hidden from inside a building. Nothing is duplicated
-/// by the split: the merged form never shared a vertex across a chunk boundary either.
-///
-/// `RenderAssetUsages::RENDER_WORLD`: the render world takes the buffers on extract — no clone on
-/// landing, no resident main-world copy per cell. Nothing reads the *mesh* main-side: the
-/// collider, liquid, and clutter all derive from the decoded [`AdtTile::chunks`]. The one thing
-/// the main world does need from it — the cell's `Aabb`, which the exterior cull FAILS OPEN
-/// without — the caller takes via `Mesh::compute_aabb` before handing the mesh over.
-///
-/// Returns `None` for a chunk the hole mask emptied (it draws nothing: no mesh, no entity).
+/// One drawn MCNK chunk's mesh in Bevy space and absolute world coords; `None` for a chunk the
+/// hole mask emptied. The reference's exterior cull tests one AABB per 33.333 yd chunk
+/// (`0x683bf0`). The mesh is `RENDER_WORLD` only, so the caller takes its `Aabb` first
+/// (`Mesh::compute_aabb`): the exterior cull fails open without one.
 pub fn chunk_to_mesh(chunk: &ChunkMesh, shading: &ChunkShading) -> Option<Mesh> {
     chunks_to_mesh(&[(chunk, shading)])
 }
 
-/// [`chunk_to_mesh`] over several chunks of ONE tile as one mesh — the terrain CELL (decision
-/// 1944): every per-chunk fact the shader reads (the layer indices, the alpha/shadow slot) is
-/// already baked per vertex, and a tile's chunks share its material, so concatenating them
-/// changes nothing a pixel can see and turns sixteen draws into one. Positions are absolute,
-/// so no per-chunk transform is folded. A hole-emptied chunk contributes nothing; a cell of
-/// nothing but holes is `None`.
+/// [`chunk_to_mesh`] over several chunks of one tile as one mesh, the terrain cell: the indices
+/// the shader reads are per vertex and the tile shares one material, so the merge draws the same
+/// pixels in one draw. `None` when every chunk is a hole.
 pub fn chunks_to_mesh(parts: &[(&ChunkMesh, &ChunkShading)]) -> Option<Mesh> {
     let live: Vec<&(&ChunkMesh, &ChunkShading)> =
         parts.iter().filter(|(c, _)| c.indices.len() >= 3).collect();
@@ -169,7 +125,7 @@ pub fn chunks_to_mesh(parts: &[(&ChunkMesh, &ChunkShading)]) -> Option<Mesh> {
     Some(mesh)
 }
 
-/// Bevy [`AssetLoader`] decoding a vanilla `*.adt` tile → [`AdtTile`].
+/// Loads a `*.adt` tile into an [`AdtTile`].
 #[derive(Default, TypePath)]
 pub struct AdtLoader;
 
@@ -189,10 +145,8 @@ impl AssetLoader for AdtLoader {
         let to_io = |e: anyhow::Error| std::io::Error::other(format!("{e:#}"));
         let tile = adt_to_tile_mesh(&bytes).map_err(to_io)?;
 
-        // Layer array: a solid-green fallback at index 0, then each unique referenced layer texture.
-        // The layers are collected in their **authored** form and packed only once the tile is fully
-        // read — one `texture_2d_array` has one format, so whether this tile's DXT blocks go up
-        // untouched is a question about the whole set (`terrain::pack_layers`, decision 1646).
+        // Layer array: a solid-green fallback at index 0, then each unique layer texture, packed
+        // once the whole tile is read.
         let mut layers: Vec<RawLayer> = Vec::new();
         let mut layer_index: HashMap<String, u32> = HashMap::new();
 
@@ -201,21 +155,14 @@ impl AssetLoader for AdtLoader {
         let mut shadow_buf: Vec<u8> = Vec::new();
         let mut shadow_count = 0u32;
 
-        // One shading entry per chunk (holes get the default). COLOR carries the chunk's 4 layer
-        // indices, UV1 its alpha/shadow — uniform over the chunk's own vertices, which is what
-        // keeps ONE material per tile. The MESH built from these lands later, app-side and paced
-        // (`chunk_to_mesh`); only the array-index resolution belongs here, with the arrays.
         let mut shading: Vec<ChunkShading> = Vec::with_capacity(tile.chunks.len());
 
         for chunk in tile.chunks.iter() {
-            // A chunk the hole mask emptied draws nothing: no mesh, no entity, and no alpha/shadow
-            // array slot either (the indices below are running counters, so skipping here is free).
+            // A hole-emptied chunk takes no alpha or shadow slot either.
             if chunk.indices.len() < 3 {
                 shading.push(ChunkShading::default());
                 continue;
             }
-            // Resolve up to 4 layer textures to array indices (appending new ones). Missing slots
-            // reuse layer 0 (its alpha weight is 0, so it never shows).
             let mut li = [0u32; 4];
             for (slot, name) in chunk.layer_textures.iter().take(4).enumerate() {
                 let key = normalize_path(name);
@@ -270,10 +217,7 @@ impl AssetLoader for AdtLoader {
 
         let layer_count = layers.len() as u32 + 1;
         let packed = pack_layers([107, 133, 82, 0], layers);
-        // Which lane this tile took, and what it cost. Per-tile rather than aggregated because the
-        // question after a perf report is always "which tiles fell back, and where am I standing" —
-        // and one greppable format name per tile answers it from a player's log with no machinery
-        // (`grep -c Bc2RgbaUnorm` against `grep -c Rgba8Unorm`) (1646).
+        // Per tile, so a log shows which tiles fell back to the decoded format.
         debug!(
             "adt {}: layer array {layer_count} x {:?}, {} KiB",
             ctx.path(),
@@ -300,13 +244,8 @@ impl AssetLoader for AdtLoader {
     }
 }
 
-/// Read a layer texture in its authored form. Prefers the `_s` specular variant (sheen mask in
-/// alpha); else falls back to the base BLP, flagged `matte` so no sheen rides it. `key` is a
-/// normalized internal path.
-///
-/// **Native, not decoded**: the blocks are kept here so [`pack_layers`] still has the choice. A
-/// Raw1/Raw3 BLP has no block form and comes back decoded anyway, which is why the caller never has
-/// to ask — it is [`benilla_formats::BlpMipChain::texels`] that says what arrived.
+/// Read a layer texture with its blocks intact, preferring the `_s` specular variant (sheen mask in
+/// alpha); the base BLP alone is flagged `matte`.
 async fn read_layer(ctx: &mut LoadContext<'_>, key: &str) -> Option<RawLayer> {
     if let Some(spec) = key.strip_suffix(".blp").map(|stem| format!("{stem}_s.blp")) {
         if let Ok(bytes) = ctx.read_asset_bytes(mpq_url(&spec)).await {
@@ -323,17 +262,17 @@ async fn read_layer(ctx: &mut LoadContext<'_>, key: &str) -> Option<RawLayer> {
     Some(RawLayer { chain, matte: true })
 }
 
-/// An internal (`\`/lowercase) path → an `mpq://` URL.
+/// An internal path as an `mpq://` URL.
 fn mpq_url(key: &str) -> String {
     format!("mpq://{}", key.replace('\\', "/"))
 }
 
-/// Normalize an internal asset path so case/slash variants share one layer-array index.
+/// Normalize an internal asset path so case and slash variants share one layer-array index.
 fn normalize_path(path: &str) -> String {
     path.replace('/', "\\").to_ascii_lowercase()
 }
 
-/// Flat per-chunk normals for the rare chunk lacking authored MCNR (most carry it).
+/// Normals for the rare chunk without authored MCNR.
 fn computed_normals(positions: &[[f32; 3]], indices: &[u32]) -> Vec<[f32; 3]> {
     let mut acc = vec![Vec3::ZERO; positions.len()];
     for tri in indices.as_chunks::<3>().0 {
diff --git a/crates/benilla-assets/src/anim_rng.rs b/crates/benilla-assets/src/anim_rng.rs
index 66031179..77bf6f13 100644
--- a/crates/benilla-assets/src/anim_rng.rs
+++ b/crates/benilla-assets/src/anim_rng.rs
@@ -1,85 +1,48 @@
-//! The client's **one** `rand()` stream — the MSVC-CRT LCG at `0x7400e5`.
+//! The client's one `rand()` stream, the MSVC CRT LCG at `0x7400e5`, in this leaf crate because
+//! the engine's placed doodads and the game's creature, GameObject and portrait-booth arms all
+//! draw from it. The reference keeps one cell per thread (`[ptd+0x14]`) and runs every arm on the
+//! main thread (the frame loop `0x420c00`); that interleaving de-syncs a stand of identical props,
+//! so it must stay one stream.
 //!
-//! **It lives down here, below both sides of decision 1160's line, because both sides draw from
-//! it** — `trace`'s placement argument, verbatim, for the same reason. The engine's placed-doodad
-//! host and the game's creature, GameObject and portrait-booth arms all roll a variation off this
-//! sequence, and in the reference they roll it off the *same cell*: `rand` reads and rewrites
-//! `[ptd+0x14]`, one per thread, and every animation arm in the client runs on the primary thread
-//! (`_initterm` is pre-`WinMain`; the frame loop is inline, not spawned — wow-re
-//! `net/scratch/crt-rand-stream-seeding.md` §4). A leaf with no dependencies can be reached by
-//! everything; an owner at the top of the stack cannot be reached by the engine at all.
-//!
-//! **Why one stream and not one per consumer** (decision 0768, and 2301 which found the drift):
-//! a shared sequence is what de-syncs a stand of identical props. Not a per-placement seed — just
-//! consecutive draws. benilla had four independent streams for a while, three of them seeded 0
-//! against the fourth's 1, while all four docstrings claimed to be this one; interleaving is the
-//! whole mechanism, so splitting it is not a harmless refactor.
-//!
-//! **The seed is the reference's, and it is not 1.** `1` is real — the CRT's per-thread default at
-//! `_initptd 0x40aca8`, which is what [`AnimRng::default`] returns — but the client overwrites it
-//! during CRT static initialization, before `WinMain`: `_initterm` slot **3691** (`.data
-//! 0x82a9ac` → the `_dynamic_initializer_for_*` trampoline `0x5b7ff0` → `0x5b8000`) calls
-//! `0x5d1c70`, which calls `srand(GetTickCount())` at `0x5d1c8b`. So the reference's variation
-//! sequence differs on every run, and [`AnimRng::seed_for_session`] is where benilla says the same
-//! thing. Byte-VERIFIED by a wow-re §5 round; recorded in
-//! `net/scratch/crt-rand-stream-seeding.md`.
-//!
-//! **Sequence parity with the reference is not achievable and is not the goal.** Where the stream
-//! stands at any given arm depends on every intervening draw — the noise table `Model2::Initialize`
-//! builds, the sky LUT, every `CParticleEmitter2` constructor, and FrameXML's own `random()` (bound
-//! as a bare global by the embedded `compat.lua`, and called in ordinary play). What benilla
-//! reproduces is the *structure*: one stream, wall-clock seeded, shared, non-repeating across runs.
+//! The reference seeds it with `srand(GetTickCount())` in CRT static init (`0x5d1c70`, the call
+//! at `0x5d1c8b`), so each run rolls differently. Its exact sequence is out of reach: every other
+//! draw moves the stream, FrameXML's `random()` and each particle emitter among them.
 
 use bevy::prelude::Resource;
 
-/// The shared `rand()` state — see the module note. Seeded by [`Self::seed_for_session`] at
-/// startup; [`Default`] is the CRT's own pre-`srand` value so a test or a headless build that
-/// never seeds still walks a defined sequence.
+/// The shared `rand()` state, seeded once per session by [`Self::seed_for_session`].
 #[derive(Resource)]
 pub struct AnimRng(u32);
 
 impl Default for AnimRng {
     fn default() -> Self {
-        Self(1) // `_initptd 0x40aca8` — the CRT's per-thread default, before `srand` runs
+        Self(1) // `_initptd 0x40aca8`: the CRT's per-thread default, before `srand` runs
     }
 }
 
 impl AnimRng {
-    /// One `rand()` draw: `seed = seed·214013 + 2531011`, result `(seed >> 16) & 0x7fff` — the
-    /// closed range `[0, 32767]`, 32768 equiprobable outcomes, taken with no scale, mask, modulo
-    /// or divide (`0x7400ed`-`0x740101`).
+    /// One `rand()` draw, in `[0, 32767]` (`0x7400ed`-`0x740101`).
     pub fn draw(&mut self) -> u16 {
         self.0 = self.0.wrapping_mul(214_013).wrapping_add(2_531_011);
         ((self.0 >> 16) & 0x7fff) as u16
     }
 
-    /// The play-window's **replay count** `R = max(1, min + ((rand()·(max−min)) >> 15))` — the
-    /// reference's `windowHi = now + span·R` (`0x712692`-`0x7126cd`). `replay = (0, 0)`, the
-    /// overwhelming majority, always yields `R = 1`: one loop per window, so the variation
-    /// re-rolls every single pass.
-    ///
-    /// The draw is taken **unconditionally**, even when it cannot change the answer: it is one
-    /// sub-expression of the reference's formula, so the shared stream has to advance the same way
-    /// whatever the span. A caller that skips it de-phases every later draw in the process.
+    /// The play window's replay count `R`, as in the reference's `windowHi = now + span·R`
+    /// (`0x712692`-`0x7126cd`). It draws even when the range cannot change `R`, as the reference
+    /// does; skipping the draw de-phases every later roll.
     pub fn replay_count(&mut self, replay: (u32, u32)) -> u32 {
         let (lo, hi) = replay;
         let r = lo + ((u64::from(self.draw()) * u64::from(hi.saturating_sub(lo))) >> 15) as u32;
         r.max(1)
     }
 
-    /// The reference's `srand(GetTickCount())` from CRT static init (module note) — a **wall-clock
-    /// seed, once per process**, so a fresh session does not replay the last one's variations.
-    ///
-    /// `deterministic` is the capture carve-out and the only place benilla differs: a golden frame
-    /// has to be reproducible, so a capture run keeps the CRT's own pre-`srand` value. That is the
-    /// same trade every other sim in the harness makes, at the one site that knows a capture is
-    /// running rather than smeared through the lanes that draw.
+    /// The reference's `srand(GetTickCount())`: a wall-clock seed, once per process. Deviation: a
+    /// capture run (`deterministic`) keeps the default seed, so its frames reproduce.
     pub fn seed_for_session(&mut self, deterministic: bool) {
         if deterministic {
             return;
         }
-        // `GetTickCount` is milliseconds since boot; the wall clock's sub-second span is the same
-        // kind of number and is what a non-Windows host can offer.
+        // `GetTickCount` counts milliseconds since boot; wall-clock milliseconds stand in for it.
         self.0 = std::time::SystemTime::now()
             .duration_since(std::time::UNIX_EPOCH)
             .map_or(1, |d| d.as_millis() as u32);
@@ -90,20 +53,15 @@ impl AnimRng {
 mod tests {
     use super::*;
 
-    /// The LCG itself, against the bytes at `0x7400ed`-`0x740101` — and against the CRT's own
-    /// documented sequence from seed 1, which is the one value a reader can check anywhere.
+    /// Seed 1 gives the MSVC CRT's documented sequence.
     #[test]
     fn the_draw_is_the_crt_lcg() {
         let mut rng = AnimRng::default();
         let first: Vec<u16> = (0..6).map(|_| rng.draw()).collect();
         assert_eq!(first, vec![41, 18_467, 6_334, 26_500, 19_169, 15_724]);
-        // Every draw is inside the closed range the `and eax,0x7fff` produces.
         assert!(first.iter().all(|&r| r <= 0x7fff));
     }
 
-    /// `(0, 0)` — the overwhelming majority of shipped sequences — is one pass, and it still costs
-    /// a draw. The second half is the part a "tidy" rewrite breaks: skipping the draw when it
-    /// cannot change the answer de-phases every later roll in the process.
     #[test]
     fn a_zero_replay_pair_is_one_pass_and_still_advances_the_stream() {
         let mut rng = AnimRng::default();
@@ -117,7 +75,6 @@ mod tests {
         );
     }
 
-    /// The window scales with the range, and never below one pass.
     #[test]
     fn a_replay_range_scales_the_window() {
         let mut rng = AnimRng::default();
@@ -131,8 +88,6 @@ mod tests {
         assert_eq!(rng.replay_count((2, 1)), 2);
     }
 
-    /// A seeded session does not replay the default sequence — the whole point of
-    /// `srand(GetTickCount())` — and a capture run does.
     #[test]
     fn a_capture_keeps_the_fixed_seed_and_a_session_does_not() {
         let mut capture = AnimRng::default();
diff --git a/crates/benilla-assets/src/blp.rs b/crates/benilla-assets/src/blp.rs
index 37c9bb3a..cce75de5 100644
--- a/crates/benilla-assets/src/blp.rs
+++ b/crates/benilla-assets/src/blp.rs
@@ -1,17 +1,4 @@
-//! BLP → Bevy [`Image`] loader.
-//!
-//! Decodes a WoW BLP texture into an `Image` in one of several variants (selected by loader
-//! settings):
-//! - [`BlpVariant::WorldArt`] — tiling world/model albedo: `Rgba8Unorm` (the RE'd gamma-space
-//!   invariant — the GPU does *not* linearize albedo on sample, so shader math stays in WoW's
-//!   gamma/byte space), the BLP's **authored** mip pyramid used verbatim (the real 1.12 client cannot
-//!   regenerate mips — it uploads the stored ones), repeat + the process filter policy
-//!   ([`crate::tex_filter`]).
-//! - [`BlpVariant::Sprite`] — emissive billboards (sun/moon discs): `Rgba8UnormSrgb`, clamp, mip 0.
-//! - [`BlpVariant::Cursor`] — the OS cursor image: `Rgba8UnormSrgb`, single mip.
-//!
-//! Fidelity rationale (authored mips, the gamma-space `Unorm` invariant) is anchored in
-//! `wow-5875-re/system/{terrain,lighting}`; here we only build the GPU resource.
+//! BLP to Bevy [`Image`] loader, in the [`BlpVariant`] the load settings choose.
 
 use bevy::asset::io::Reader;
 use bevy::asset::{AssetLoader, LoadContext, RenderAssetUsages};
@@ -24,32 +11,25 @@ use benilla_formats::{blp_bytes_to_native_chain, blp_to_rgba};
 
 use crate::gpu_blp::{for_upload, UploadChain};
 
-/// Which on-GPU form a BLP decodes to. See the module docs.
+/// Which on-GPU form a BLP decodes to.
 #[derive(Default, Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
 pub enum BlpVariant {
-    /// Tiling world/model albedo — `Rgba8Unorm`, authored mips, repeat + the filter policy. The default.
+    /// World and model albedo, the default: non-sRGB, so shader math stays in gamma bytes; the
+    /// authored mips as stored (the 1.12 client never regenerates them); the process filter policy.
     #[default]
     WorldArt,
-    /// Emissive billboard (celestial disc) — `Rgba8UnormSrgb`, clamp, mip 0 only.
+    /// Emissive billboard (the sun and moon discs): `Rgba8UnormSrgb`, clamp, mip 0 only.
     Sprite,
-    /// Gamma-lane effect sprite (rain splashes, weather mist) — `Rgba8Unorm` like
-    /// [`Self::WorldArt`] but **mip 0 only** + clamp: these draw as world-space quads that are
-    /// magnified far more often than minified, and their thin cut-out arms collapse to near-zero
-    /// alpha under the authored mip chain.
+    /// Gamma-lane effect sprite (rain splashes, weather mist): `Rgba8Unorm`, clamp, mip 0 only, as
+    /// these quads are mostly magnified and their thin cut-out arms fade out down the mips.
     Effect,
-    /// A **point sprite** — [`Self::Effect`]'s clamp and gamma lane, but with the BLP's
-    /// **authored mip pyramid** kept (trilinear, no anisotropy). The snow flake's lane: the
-    /// reference draws it through `glDrawArrays(GL_POINTS)` with `GL_COORD_REPLACE`, so the whole
-    /// texture maps across a sprite that is **14 px at the eye and 1 px past 46 yd** — a 4.5×–64×
-    /// *minification* of a 64×64 texture, which is why the asset ships 7 mip levels. Mip-0-only
-    /// here is not "crisp", it is aliased: a 1-px flake samples one arbitrary texel of a dendrite
-    /// and the field becomes flickering speckle.
-    /// (wow-re `system/lighting/scratch/rf-snow-flake-render.md` §2.1/§6.)
+    /// The snow flake: [`Self::Effect`] with the authored mips kept. The reference draws it as
+    /// `GL_POINTS` with `GL_COORD_REPLACE` (`0x678610`; device init `0x59cf30`-`0x59cf58`), 14 px
+    /// at the eye and 1 px past 46 yd, where mip 0 alone aliases into speckle.
     PointSprite,
-    /// A **minimap tile** (ADT `map<X>_<Y>` or a WMO group's interior tile) — clamp, mip 0, linear,
-    /// and filtered in **gamma space**, the reference's `GL_SKIP_DECODE_EXT`. See [`map_tile_image`].
+    /// A minimap tile (ADT `map<X>_<Y>` or a WMO group's interior tile): [`map_tile_image`].
     MapTile,
-    /// OS cursor image — `Rgba8UnormSrgb`, single mip.
+    /// OS cursor image: `Rgba8UnormSrgb`, single mip.
     Cursor,
 }
 
@@ -59,7 +39,7 @@ pub struct BlpLoaderSettings {
     pub variant: BlpVariant,
 }
 
-/// Bevy [`AssetLoader`] decoding `*.blp` → [`Image`].
+/// Bevy [`AssetLoader`] decoding `*.blp` to [`Image`].
 #[derive(Default, TypePath)]
 pub struct BlpImageLoader;
 
@@ -79,11 +59,9 @@ impl AssetLoader for BlpImageLoader {
         let to_io = |e: anyhow::Error| std::io::Error::other(format!("{e:#}"));
         Ok(match settings.variant {
             BlpVariant::WorldArt => world_art_image(
-                // The blocks go straight to the GPU where it can take them (decision 1626);
-                // `for_upload` decodes only when it cannot, and hands back the matching format.
                 for_upload(blp_bytes_to_native_chain(&bytes).map_err(to_io)?),
-                // The address mode rides the asset path (`crate::texture_url`, decision 0763): the
-                // sampler is a property of this upload, and one `.blp` legitimately has two.
+                // The address mode rides the asset path (`crate::texture_url`): one `.blp` can be
+                // uploaded under two samplers.
                 crate::sampler_mode_of(&ctx.path().to_string()),
             ),
             BlpVariant::Sprite => {
@@ -113,13 +91,9 @@ impl AssetLoader for BlpImageLoader {
     }
 }
 
-/// The gamma-byte lane's uncompressed format — non-sRGB, so the GPU does not linearize on sample
-/// and shader math stays in WoW's byte space (the RE'd faithful invariant;
-/// `wow-5875-re/system/lighting`). Every decoded lane below uploads as this.
+/// The gamma lanes' uncompressed format: non-sRGB, so the GPU does not linearize on sample.
 const GAMMA_BYTES: TextureFormat = TextureFormat::Rgba8Unorm;
 
-/// World/model albedo: the BLP's authored mip pyramid laid in verbatim, repeat + the process
-/// filter policy ([`crate::tex_filter`]). (Port of the old `repeat_texture_authored`.)
 fn world_art_image(upload: UploadChain, wrap: (bool, bool)) -> Image {
     let UploadChain { chain, format } = upload;
     let levels = chain.mips.len() as u32;
@@ -127,9 +101,8 @@ fn world_art_image(upload: UploadChain, wrap: (bool, bool)) -> Image {
     for mip in &chain.mips {
         data.extend_from_slice(mip);
     }
-    // `new_uninit` rather than `new`: `Image::new`'s length assert is written for uncompressed
-    // formats (it skips itself when `pixel_size()` errors, which is every BC format), and feeding
-    // it mip 0 just to satisfy that assert cost a clone of the largest level on every load.
+    // `new_uninit`: `Image::new` would clone mip 0 only to feed a length assert meant for
+    // uncompressed formats.
     let mut image = Image::new_uninit(
         Extent3d {
             width: chain.width,
@@ -138,15 +111,8 @@ fn world_art_image(upload: UploadChain, wrap: (bool, bool)) -> Image {
         },
         TextureDimension::D2,
         format,
-        // `RENDER_WORLD`: the render world TAKES the mip chain on extract instead of cloning it and
-        // leaving a main-world copy resident for the asset's life (bevy_render `render_asset.rs` —
-        // the `asset_usage == RENDER_WORLD` branch moves, every other usage clones). This is the
-        // variant carrying every terrain layer, model albedo and WMO albedo in the game, so the
-        // default usage was paying a full mip-chain memcpy on every landing frame and holding a
-        // second copy of the whole world's art in system RAM. Nothing reads a world texture
-        // main-side (the minimap, colliders and clutter all derive from other sources) — same
-        // reasoning, and now the same usage, as the terrain tile arrays (`terrain.rs`) and the
-        // Sprite/Effect/PointSprite variants below.
+        // The render world takes the chain on extract rather than cloning it and keeping a
+        // main-world copy (bevy_render `render_asset.rs`); nothing reads world art main-side.
         RenderAssetUsages::RENDER_WORLD,
     );
     image.data = Some(data);
@@ -158,10 +124,8 @@ fn world_art_image(upload: UploadChain, wrap: (bool, bool)) -> Image {
             ImageAddressMode::ClampToEdge
         }
     };
-    // The mip filter and the anisotropy are NOT this lane's to choose: the reference forces both
-    // from two process globals at every `TextureCreate` (`0x449ae0`), and what a virgin install
-    // gets from `hwDetect` is trilinear with anisotropy OFF. See [`crate::tex_filter`] — this used
-    // to read `Linear` / `8`, which is mode 5 shipped as if it were the default.
+    // The reference's terrain, WMO and M2 textures take the mip filter and anisotropy from the
+    // process policy (`0x449ae0`, `crate::tex_filter`).
     let filter = crate::tex_filter::tex_filter();
     image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
         address_mode_u: mode(wrap.0),
@@ -175,8 +139,7 @@ fn world_art_image(upload: UploadChain, wrap: (bool, bool)) -> Image {
     image
 }
 
-/// Emissive billboard (celestial disc): sRGB so an unlit pass round-trips the authored gamma bytes to
-/// screen; clamp + linear, mip 0 only (the disc maps to one quad and never tiles/minifies far).
+/// Emissive billboard: sRGB, so an unlit pass returns the authored gamma bytes to screen.
 fn sprite_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     let mut image = Image::new(
         Extent3d {
@@ -199,29 +162,14 @@ fn sprite_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     image
 }
 
-/// A **minimap tile** — clamp, mip 0, **LINEAR**, and filtered in **GAMMA** space.
-///
-/// The reference binds one sampler object for every minimap tile it draws, interior and outdoor
-/// alike, and the trace reads it whole: `CLAMP_TO_EDGE` both axes, `MAG_FILTER = MIN_FILTER =
-/// GL_LINEAR` with no mip term, LOD bias 0, anisotropy 1, and — the part that is not the default —
-/// **`GL_TEXTURE_SRGB_DECODE_EXT = GL_SKIP_DECODE_EXT`**, plus `GL_TEXTURE_MAX_LEVEL = 0` per tile.
-/// (wow-re `system/minimap/scratch/wmo-interior-no-adt-underlay.md` §7, device-observed and matching
-/// its own binary derivation; a positive control in the same trace emits `GL_NEAREST` for a
-/// different sampler, so the layer would have shown point sampling had the client asked for it.)
-///
-/// SKIP_DECODE is the whole reason this is not [`sprite_image`]: it means the hardware **filters the
-/// authored bytes**, not their linearisation. An `Rgba8UnormSrgb` upload decodes each texel to
-/// linear before the filter weights it, so every blend across an edge lands on a different colour
-/// than the reference's — darker, because averaging in linear space and re-encoding is darker than
-/// averaging the gamma bytes. On a 1-bit-alpha bake whose edges sit against black that is a visible
-/// dark fringe at every alpha boundary. So the tile arrives as gamma bytes ([`GAMMA_BYTES`], no
-/// decode) and the shader converts AFTER the filter.
+/// A minimap tile, sampled as the reference samples every tile (the tile loader `0x6d9ed0`): clamp,
+/// `GL_LINEAR` with no mips, anisotropy 1 and `GL_SKIP_DECODE_EXT`, so the hardware filters the
+/// gamma bytes. An sRGB upload would darken every alpha edge against black, so the tile uploads as
+/// [`GAMMA_BYTES`] and the shader converts after the filter.
 fn map_tile_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     effect_image(width, height, rgba)
 }
 
-/// Gamma-lane effect sprite: `Rgba8Unorm` (the shader does WoW's byte-space combine), clamp,
-/// **mip 0 only** — see [`BlpVariant::Effect`].
 fn effect_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     let mut image = Image::new(
         Extent3d {
@@ -244,9 +192,7 @@ fn effect_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     image
 }
 
-/// Point sprite: [`effect_image`]'s gamma lane and clamp, with the **authored mip pyramid** —
-/// see [`BlpVariant::PointSprite`]. No anisotropy: a point sprite is always screen-axis-aligned
-/// and square, so there is no anisotropic footprint to correct for.
+/// No anisotropy: a point sprite is square and screen-aligned, with no anisotropic footprint.
 fn point_sprite_image(upload: UploadChain) -> Image {
     let UploadChain { chain, format } = upload;
     let levels = chain.mips.len() as u32;
@@ -271,16 +217,12 @@ fn point_sprite_image(upload: UploadChain) -> Image {
         address_mode_v: ImageAddressMode::ClampToEdge,
         mag_filter: ImageFilterMode::Linear,
         min_filter: ImageFilterMode::Linear,
-        // A mip chain means the policy owns the mip filter here too — the reference's override is
-        // unconditional across every texture it creates, with no per-class exemption. The aniso
-        // stays absent by the argument above, and the policy agrees in modes 3 and 4.
         mipmap_filter: crate::tex_filter::tex_filter().mipmap_filter(),
         ..Default::default()
     });
     image
 }
 
-/// OS cursor image: sRGB, single mip (cursors are tiny and need neither a mip chain nor repeat).
 fn cursor_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     Image::new(
         Extent3d {
diff --git a/crates/benilla-assets/src/column_grid.rs b/crates/benilla-assets/src/column_grid.rs
index 8fc4c036..719a7b55 100644
--- a/crates/benilla-assets/src/column_grid.rs
+++ b/crates/benilla-assets/src/column_grid.rs
@@ -1,56 +1,26 @@
-//! The **column index**: which of a face set's triangles can own a vertical (x, y) column.
-//!
-//! Every position question this client asks a WMO is a column query — which room is the camera in
-//! (`wmo_portal::seed`), which room is a unit in (`track_unit_interiors`), which floor's baked MOCV
-//! lights an entity (`interior::classify_entity_interior`), what the zone text should say. All of
-//! them cast straight down and want "the triangles whose XY projection contains this point".
-//!
-//! Until now the narrow phase for that was **a linear scan of every triangle in every group whose
-//! AABB contains the column** (decisions 0330/0364 built the per-group bounds; the group is where
-//! the culling stopped). That is fine for a cottage and catastrophic for a dungeon: Blackrock
-//! Spire's groups hold ~11–16k faces each, and a vertically stacked spire puts several of them in
-//! any given column. Measured in LBRS on 2026-07-27: **~1.2 M triangle tests per frame** to light
-//! **37 moving NPCs** — ~32k per unit per frame, 11 ms of a 29 ms frame, the second-largest term in
-//! the NPC-population collapse (B31/B06 + the BWL/LBRS reports).
-//!
-//! So each group's faces get a uniform XY grid, built once at load: a column tests one cell's
-//! worth of triangles instead of the group's whole face list.
-//!
-//! **The index never changes a verdict.** It is a pure accelerator with two properties the callers
-//! depend on, both pinned by tests:
-//!
-//! - **Superset** — every triangle whose XY projection contains the column is a candidate. A
-//!   triangle is inserted into every cell its XY AABB touches (inclusive both ends), a query point
-//!   outside the grid clamps into the edge cell rather than missing, and a triangle whose AABB
-//!   spans more cells than [`MAX_SPAN_CELLS`] goes in [`ColumnGrid::spanning`], tested always.
-//! - **Order** — candidates come back in **ascending triangle index**, the order a linear scan
-//!   visits them, so every tie-break downstream (`down_ray_claim`'s first-wins, `footprint_sample`'s
-//!   later-wins) resolves exactly as it did before the index existed.
+//! The column index: which of a face set's triangles can own a vertical (x, y) column, for the
+//! down-cast position queries against a WMO (the camera's room, a unit's room, the floor MOCV that
+//! lights an entity). It never changes a verdict: the candidates are a superset of the triangles
+//! whose XY box holds the column, in ascending index order, the order a linear scan visits them,
+//! so the first-wins and later-wins tie-breaks downstream resolve the same.
 
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::OnceLock;
 
-/// A triangle whose XY AABB touches more cells than this is not binned at the level being built —
-/// it is handed to the next level down (the coarse grid), and only a face too large for *that*
-/// becomes a [`ColumnGrid::spanning`] always-tested residue. Big floor slabs are the case: at a
-/// ~1-triangle-per-cell sizing a 100-yd slab would otherwise be copied into hundreds of cells.
+/// A triangle touching more cells than this goes to the next level down, and past the coarse level
+/// to [`ColumnGrid::spanning`], so a big floor slab is not copied into hundreds of cells.
 const MAX_SPAN_CELLS: u32 = 32;
 
-/// Below this many oversized faces, a second grid is not worth its own allocation pair and lookup —
-/// they stay an always-tested list. Well under the per-query counts 1351 measured (~480), so the
-/// pin's groups all take the coarse level.
+/// Below this many oversized faces they stay an always-tested list instead of a second grid.
 const MIN_COARSE_TRIS: usize = 24;
 
-/// Never build cells finer than this (yd) — a degenerate face set (all triangles stacked in one
-/// spot) would otherwise ask for an unbounded grid.
+/// The finest cell, yd, so a face set stacked in one spot cannot ask for an unbounded grid.
 const MIN_CELL: f32 = 0.25;
 
-/// Cell budget per group: the grid is at most this many cells regardless of face count, so a
-/// 500-yd dungeon group costs tens of KB of index, not tens of MB.
+/// The most cells one level holds, whatever the face count.
 const MAX_CELLS: usize = 1 << 16;
 
-/// One uniform XY grid over some set of triangles — CSR (`starts`/`items`), so one allocation
-/// pair per level rather than a `Vec` per cell.
+/// One uniform XY grid in CSR form (`starts`, `items`).
 #[derive(Debug, Clone)]
 struct Level {
     /// Grid origin (the indexed set's XY minimum).
@@ -61,69 +31,38 @@ struct Level {
     ny: u32,
     /// CSR row offsets into [`Self::items`], length `nx * ny + 1`.
     starts: Vec<u32>,
-    /// **Global** triangle indices, ascending within each cell.
+    /// Global triangle indices, ascending within each cell.
     items: Vec<u32>,
 }
 
-/// A face set's column index: **two grids and a residue**.
-///
-/// One grid cannot serve a dungeon group. Sizing cells at ~1 triangle each is right for the ~11–16k
-/// small faces, and catastrophic for the handful of 40–100 yd floor slabs sharing the group: a slab
-/// would be copied into hundreds of cells, so [`MAX_SPAN_CELLS`] sets it aside instead — and
-/// "aside" used to mean *tested on every query*.
-///
-/// 1351 measured what that cost at the LBRS pin: **99.26 %** of all triangles tested per frame were
-/// those set-aside slabs — 93,624 of 94,322, against 698 that came from a cell list. The index was
-/// accelerating the 0.7 %.
-///
-/// So the oversized set gets its own grid, sized from its own extent and its own count (0711's
-/// named fix, deferred there and confirmed by 1351). Cells at that level are ~an order of magnitude
-/// wider, which is exactly what a slab needs to bin. Whatever is still too big for the coarse level
-/// — a face spanning the whole group — falls to [`Self::spanning`] and keeps the old always-tested
-/// behaviour, which is now a residue rather than the main term.
-///
-/// **Two levels, not recursion.** A recursive grid would need a boxed iterator per query on the
-/// hottest path in the interior lane; two explicit levels keep [`ColumnGrid::candidates`] a
-/// three-way merge of three ascending *slices* — no allocation, no indirection, and the
-/// superset+ascending invariants hold at each level independently.
+/// A face set's column index: a fine grid at about one triangle a cell, a coarse grid over the
+/// faces too large for it (dungeon floor slabs), and a residue too large for both.
 #[derive(Debug, Clone)]
 pub struct ColumnGrid {
     /// The ~1-triangle-per-cell grid over the ordinary faces.
     fine: Level,
-    /// The coarse grid over the faces `fine` set aside. `None` when there were too few of them to
-    /// be worth a second index — then they are all in [`Self::spanning`], as before.
+    /// The grid over the faces `fine` set aside; `None` when too few, all in [`Self::spanning`].
     coarse: Option<Level>,
-    /// Faces too large to bin at **either** level, ascending — candidates for every query.
+    /// Faces too large for either level, ascending: candidates for every query.
     spanning: Vec<u32>,
 }
 
-/// `WOW_COLUMN_COST=1`: how many triangles a column query actually tests, split by **source** —
-/// `binned` (the fine level's cell), `coarse` (the coarse level's cell), and `spanning` (the
-/// residue too large for either, tested on every query).
-///
-/// This is 0711's residual, and the counter that confirmed it. That hunt cut the lane from ~1.2 M
-/// triangle tests/frame to an 88 k remainder, wrote down what the remainder was — big floor slabs,
-/// too large to bin, merged into every column query — named the fix, and left it. 1351 measured the
-/// remainder three weeks later: **99.26 %** of tested triangles were that set, and `resolve_ms` was
-/// still 1.14, byte for byte the number 0711 recorded, because nothing had touched the file.
-///
-/// The counter stays as the **regression watch** on the two-level index: `spanning_pct` is now the
-/// residue's share and should read near zero. If it climbs, some face set has a slab too big for
-/// even the coarse level and the lane is quietly reverting to 0711's shape.
+/// `WOW_COLUMN_COST=1`: triangles tested per column query by source (fine cell, coarse cell,
+/// residue). The residue's share should read near zero; a climb means a slab too big for the
+/// coarse level.
 static COLUMN_QUERIES: AtomicU64 = AtomicU64::new(0);
 static COLUMN_BINNED: AtomicU64 = AtomicU64::new(0);
 static COLUMN_COARSE: AtomicU64 = AtomicU64::new(0);
 static COLUMN_SPANNING: AtomicU64 = AtomicU64::new(0);
 
-/// Whether the column-query meter is armed (`WOW_COLUMN_COST`). Read once, then a relaxed bool.
+/// Whether the column-query meter is armed (`WOW_COLUMN_COST`), read once.
 pub fn column_cost_enabled() -> bool {
     static ON: OnceLock<bool> = OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_COLUMN_COST").is_some())
 }
 
-/// Take and zero the column-query counters: `(queries, binned, coarse, spanning)` triangles tested.
-///
-/// One caller per frame — the meter that prints them — so the numbers are always per-frame.
+/// Take and zero the counters, `(queries, binned, coarse, spanning)`; one caller a frame keeps them
+/// per frame.
 pub fn take_column_query_stats() -> (u64, u64, u64, u64) {
     (
         COLUMN_QUERIES.swap(0, Ordering::Relaxed),
@@ -134,11 +73,8 @@ pub fn take_column_query_stats() -> (u64, u64, u64, u64) {
 }
 
 impl Level {
-    /// Index `ids` (ascending, global triangle indices) into one uniform grid.
-    ///
-    /// Returns the level plus the **overflow**: the ids whose XY AABB spans more than
-    /// [`MAX_SPAN_CELLS`] cells at this level's sizing, ascending, for the next level down.
-    /// `None` when the set has no finite extent to grid.
+    /// Index ascending `ids` into one grid, also returning, ascending, the ids that span more than
+    /// [`MAX_SPAN_CELLS`] cells, for the next level; `None` when the set has no finite extent.
     fn build(
         ids: &[u32],
         xy_aabb: &impl Fn(usize) -> ([f32; 2], [f32; 2]),
@@ -155,10 +91,8 @@ impl Level {
         if !w.is_finite() || !h.is_finite() || (w <= 0.0 && h <= 0.0) {
             return None;
         }
-        // Aim for ~one triangle per cell, then clamp both ways: never finer than MIN_CELL, never
-        // more than MAX_CELLS cells. Sizing from THIS set's own count and extent is what makes the
-        // coarse level coarse: a few hundred slabs over the same group span give cells ~an order of
-        // magnitude wider than the fine level's, which is what lets a slab bin at all.
+        // About one triangle a cell, clamped by MIN_CELL and MAX_CELLS. Sizing from this set's own
+        // count and extent is what makes the coarse level coarse enough for a slab to bin.
         let target_cells = ids.len().clamp(1, MAX_CELLS) as f32;
         let area = (w * h).max(f32::MIN_POSITIVE);
         let mut cell = (area / target_cells).sqrt().max(MIN_CELL);
@@ -170,7 +104,7 @@ impl Level {
         let inv_cell = 1.0 / cell;
         let cells = nx as usize * ny as usize;
 
-        // Pass 1 — count per cell, and set the oversized triangles aside for the next level.
+        // Pass 1: count per cell, and set the oversized triangles aside.
         let mut counts = vec![0u32; cells + 1];
         let mut overflow = Vec::new();
         let span_of = |i: u32| -> Option<(u32, u32, u32, u32)> {
@@ -203,8 +137,7 @@ impl Level {
         }
         starts[cells] = acc;
 
-        // Pass 2 — fill. `ids` is ascending, so each cell fills in ascending triangle order, which
-        // is the order guarantee the tie-breaks downstream rest on.
+        // Pass 2: fill. `ids` is ascending, so each cell is too, which the tie-breaks rest on.
         let mut items = vec![0u32; acc as usize];
         let mut cursor = starts.clone();
         for &i in ids {
@@ -231,7 +164,7 @@ impl Level {
         ))
     }
 
-    /// This level's own cell list for the column at `(x, y)` — ascending, possibly empty.
+    /// This level's cell list for the column at `(x, y)`, ascending.
     fn cell(&self, x: f32, y: f32) -> &[u32] {
         let cx = cell_of(x, self.min[0], self.inv_cell, self.nx);
         let cy = cell_of(y, self.min[1], self.inv_cell, self.ny);
@@ -241,12 +174,9 @@ impl Level {
 }
 
 impl ColumnGrid {
-    /// Build the index for `count` triangles, given each one's XY AABB by index.
-    ///
-    /// Returns `None` when there is nothing to accelerate — an empty face set, or one small enough
-    /// that a linear scan beats the indirection (the caller then keeps its plain scan).
+    /// Index `count` triangles by their XY AABBs; `None` for a set small enough that the caller's
+    /// linear scan is cheaper.
     pub fn build(count: usize, xy_aabb: impl Fn(usize) -> ([f32; 2], [f32; 2])) -> Option<Self> {
-        // Below this a linear scan is the cheaper answer and the grid is pure overhead.
         const MIN_TRIS: usize = 64;
         if count < MIN_TRIS {
             return None;
@@ -254,9 +184,6 @@ impl ColumnGrid {
         let all: Vec<u32> = (0..count as u32).collect();
         let (fine, oversized) = Level::build(&all, &xy_aabb)?;
 
-        // The oversized set gets its own grid when there are enough of them to pay for one. What
-        // *that* level cannot bin stays an always-tested residue — the old behaviour, now applied
-        // to a set 1351 predicts is tiny rather than to 99 % of the traffic.
         let (coarse, spanning) = if oversized.len() >= MIN_COARSE_TRIS {
             match Level::build(&oversized, &xy_aabb) {
                 Some((level, residue)) => (Some(level), residue),
@@ -273,7 +200,7 @@ impl ColumnGrid {
         })
     }
 
-    /// The triangles that can own the column at `(x, y)` — a superset, in ascending index order.
+    /// The triangles that can own the column at `(x, y)`: a superset, ascending.
     pub fn candidates(&self, x: f32, y: f32) -> ColumnCandidates<'_> {
         let binned = self.fine.cell(x, y);
         let coarse = self.coarse.as_ref().map_or(&[][..], |c| c.cell(x, y));
@@ -290,7 +217,7 @@ impl ColumnGrid {
         }
     }
 
-    /// Index size in triangle slots — the memory the acceleration costs, for the load-time log.
+    /// Index size in triangle slots, for the load-time log.
     pub fn slots(&self) -> usize {
         self.fine.items.len()
             + self.coarse.as_ref().map_or(0, |c| c.items.len())
@@ -298,13 +225,8 @@ impl ColumnGrid {
     }
 }
 
-/// Ascending merge of the three sources a column can draw from: the fine level's cell, the coarse
-/// level's cell, and the always-tested residue. All three are ascending, so this is a three-pointer
-/// walk and the output order matches a linear scan exactly — which is the guarantee every downstream
-/// tie-break (`down_ray_claim`'s first-wins, `footprint_sample`'s later-wins) rests on.
-///
-/// A triangle appears in exactly one source by construction: a face is binned at the fine level, or
-/// handed down to the coarse level, or in the residue — never two. So the merge cannot duplicate.
+/// Ascending merge of the fine cell, the coarse cell and the residue. A face is in exactly one of
+/// them, so the merge never duplicates, and its order is a linear scan's.
 pub struct ColumnCandidates<'a> {
     binned: &'a [u32],
     coarse: &'a [u32],
@@ -344,9 +266,8 @@ fn dims(w: f32, h: f32, cell: f32) -> (u32, u32) {
     (n(w), n(h))
 }
 
-/// Cell coordinate of a world value, clamped into the grid — a column outside the face set's
-/// bounds lands in the edge cell rather than missing, which keeps the candidate set a superset
-/// under float error at the boundary.
+/// A value's cell, clamped into the grid so a column just outside the bounds (float error at the
+/// edge) still lands in the edge cell.
 fn cell_of(v: f32, min: f32, inv_cell: f32, n: u32) -> u32 {
     let i = ((v - min) * inv_cell).floor();
     if i < 0.0 {
@@ -360,7 +281,6 @@ fn cell_of(v: f32, min: f32, inv_cell: f32, n: u32) -> u32 {
 mod tests {
     use super::*;
 
-    /// A triangle's XY AABB, the shape the callers hand `build`.
     fn aabb(tri: [[f32; 3]; 3]) -> ([f32; 2], [f32; 2]) {
         let xs = [tri[0][0], tri[1][0], tri[2][0]];
         let ys = [tri[0][1], tri[1][1], tri[2][1]];
@@ -376,8 +296,7 @@ mod tests {
         )
     }
 
-    /// A deterministic pseudo-random field of small triangles plus a few slabs — the dungeon shape
-    /// (many small faces, a handful of huge floors) the index has to survive.
+    /// Small pseudo-random triangles with a slab every 97th: the dungeon shape.
     fn field(n: usize) -> Vec<[[f32; 3]; 3]> {
         let mut out = Vec::with_capacity(n);
         let mut s = 12345u32;
@@ -388,7 +307,7 @@ mod tests {
         for i in 0..n {
             let (x, y) = (rnd() * 200.0 - 100.0, rnd() * 200.0 - 100.0);
             if i % 97 == 0 {
-                // A slab spanning a large area — the MAX_SPAN_CELLS path.
+                // A slab: the MAX_SPAN_CELLS path.
                 out.push([[x, y, 0.0], [x + 80.0, y, 0.0], [x, y + 80.0, 0.0]]);
             } else {
                 let (dx, dy) = (rnd() * 3.0, rnd() * 3.0);
@@ -398,9 +317,6 @@ mod tests {
         out
     }
 
-    /// The load-bearing property: for any column, the index's candidates are a SUPERSET of the
-    /// triangles a linear scan would find containing it — an index that can miss a face silently
-    /// moves a unit's room, its light, and the zone name.
     #[test]
     fn candidates_are_a_superset_of_the_linear_scan() {
         let tris = field(4000);
@@ -428,8 +344,6 @@ mod tests {
         assert!(probes > 500, "the sweep must actually probe");
     }
 
-    /// The other half of "never changes a verdict": candidates arrive in the order a linear scan
-    /// visits them, so first-wins / later-wins tie-breaks downstream are unaffected.
     #[test]
     fn candidates_are_ascending() {
         let tris = field(2000);
@@ -447,8 +361,6 @@ mod tests {
         }
     }
 
-    /// A column far outside the face set still returns a valid (edge-cell) candidate list rather
-    /// than panicking or indexing out of range.
     #[test]
     fn columns_outside_the_bounds_are_safe() {
         let tris = field(200);
@@ -458,17 +370,13 @@ mod tests {
         }
     }
 
-    /// The two-level structure actually engages on the dungeon shape, and the residue it leaves is
-    /// small. Without this, a regression that quietly stopped building the coarse level would still
-    /// pass every invariant test above — the index would just be slow again, which is exactly how
-    /// 0711's residual survived ~600 decision records unnoticed.
+    /// The tests above would still pass with no coarse level at all; this one would not.
     #[test]
     fn the_coarse_level_takes_the_slabs() {
         let tris = field(4000);
         let grid = ColumnGrid::build(tris.len(), |i| aabb(tris[i])).expect("field indexes");
 
-        // `field` plants a slab every 97th triangle; every one of them is far too wide to bin at
-        // the fine level's ~1-triangle-per-cell sizing.
+        // Every 97th triangle is a slab, too wide for the fine level.
         let slabs = tris.len().div_ceil(97);
         let coarse = grid
             .coarse
@@ -486,8 +394,6 @@ mod tests {
         );
     }
 
-    /// The merge draws from three sources; a face must appear in exactly one of them, or a column
-    /// would test it twice and `later-wins` tie-breaks would read the same triangle as two hits.
     #[test]
     fn no_triangle_is_in_two_sources() {
         let tris = field(3000);
@@ -508,7 +414,6 @@ mod tests {
         }
     }
 
-    /// Small face sets opt out — the caller keeps its linear scan rather than paying indirection.
     #[test]
     fn tiny_face_sets_are_not_indexed() {
         let tris = field(8);
diff --git a/crates/benilla-assets/src/coords.rs b/crates/benilla-assets/src/coords.rs
index 92c9865d..7f649db9 100644
--- a/crates/benilla-assets/src/coords.rs
+++ b/crates/benilla-assets/src/coords.rs
@@ -1,30 +1,23 @@
-//! The WoW ⇄ Bevy coordinate transform — the single documented boundary between raw WoW
-//! coordinates (kept everywhere in `benilla-formats` / `benilla-protocol`, matching wowdev.wiki + vmangos)
-//! and Bevy's render space.
-//!
-//! WoW is right-handed with **+X north, +Y west, +Z up**, 1 unit = 1 yard. Bevy is right-handed
-//! with **+Y up, −Z forward**. The map is the pure rotation `bevy = (−y, z, −x)` — determinant +1,
-//! so it never mirrors (winding/normals are preserved) and 1 unit stays 1 yard. See decision 0002.
-//!
-//! Extracted from `main.rs` into its own module so the transform — including the quaternion
-//! conjugation used for model placement, historically the trickiest part — is unit-tested in
-//! isolation (no game assets, no GPU, no running app).
+//! The WoW to Bevy coordinate transform, the one boundary between raw WoW coordinates (kept in
+//! `benilla-formats` and `benilla-protocol`) and Bevy's render space. WoW is right-handed with +X
+//! north, +Y west, +Z up; Bevy is +Y up, −Z forward. The map is the rotation `bevy = (−y, z, −x)`,
+//! determinant +1, so it never mirrors a winding and 1 unit stays 1 yard.
 
 use bevy::math::{Mat3, Quat, Vec3};
 use bevy::transform::components::Transform;
 
-/// WoW `[x, y, z]` → Bevy. Pure rotation, 1 unit = 1 yard.
+/// WoW `[x, y, z]` to Bevy.
 pub fn wow_to_bevy(p: [f32; 3]) -> Vec3 {
     Vec3::new(-p[1], p[2], -p[0])
 }
 
-/// Inverse of [`wow_to_bevy`]: Bevy coords → raw WoW `[x, y, z]` (for sending our position upstream).
+/// Inverse of [`wow_to_bevy`], for sending our position upstream.
 pub fn bevy_to_wow(b: Vec3) -> [f32; 3] {
     [-b.z, -b.x, b.y]
 }
 
-/// The fixed WoW→Bevy basis rotation (the rotation part of [`wow_to_bevy`]); used to conjugate
-/// placement rotations, since the model meshes are baked into Bevy space.
+/// The rotation of [`wow_to_bevy`], which conjugates placement rotations into Bevy space, where
+/// the meshes are baked.
 fn wow_to_bevy_quat() -> Quat {
     // Columns = Bevy images of the WoW basis: X→−Z, Y→−X, Z→+Y.
     Quat::from_mat3(&Mat3::from_cols(
@@ -34,18 +27,10 @@ fn wow_to_bevy_quat() -> Quat {
     ))
 }
 
-/// Convert an MDDF/MODF Euler rotation (degrees) into the Bevy quaternion for a baked (Bevy-space)
-/// mesh.
-///
-/// Derived from wowdev.wiki's ADT/v18 `createPlacementMatrix`, whose output frame is — verified
-/// against our own MDDF→position math — exactly the WoW gameplay frame (Z up). The model→world
-/// rotation it gives is `Rx(90°)·Ry(90°)·Ry(ry−270°)·Rz(−rx)·Rx(rz−90°)`, which simplifies to
-/// `Rx(90°)·Ry(ry−180°)·Rz(−rx)·Rx(rz−90°)`; we then conjugate it into Bevy space (the meshes are
-/// baked there). `ry` is the heading about the up axis; `rx`/`rz` are pitch/roll.
-///
-/// The leading `Rx(90°)` is the **M2-local→world base reorientation** the old formula skipped — it
-/// only changes the result when pitch/roll (`rx`/`rz`) are non-zero, so flat doodads and symmetric
-/// trees are unaffected, but leaning/tilted segments (fences) now orient correctly.
+/// An MDDF/MODF Euler rotation (degrees) as the Bevy quaternion of a baked mesh: wowdev.wiki's ADT
+/// `createPlacementMatrix`, `Rx(90°)·Ry(ry−180°)·Rz(−rx)·Rx(rz−90°)` in the WoW frame, conjugated
+/// into Bevy space. `ry` is the heading, `rx` and `rz` pitch and roll; the leading `Rx(90°)` is the
+/// M2-local base reorientation, which only shows on a tilted placement.
 pub fn placement_rotation(rotation_deg: [f32; 3]) -> Quat {
     use std::f32::consts::{FRAC_PI_2, PI};
     let (rx, ry, rz) = (
@@ -61,17 +46,9 @@ pub fn placement_rotation(rotation_deg: [f32; 3]) -> Quat {
     to_bevy * in_wow * to_bevy.inverse()
 }
 
-/// The Bevy-space local [`Transform`] of a **WMO doodad** (an MODD entry) within its WMO's model
-/// space. Compose it onto the WMO instance's world transform — `wmo_world.mul_transform(this)` — to
-/// place the doodad in the world.
-///
-/// Unlike MDDF/MODF map placements (Euler angles + the client's base reorientation, see
-/// [`placement_rotation`]), an MODD carries the doodad's **full orientation as a quaternion**
-/// `(x, y, z, w)` directly — no separate base reorientation — alongside a position and uniform scale,
-/// all in WMO model space (WoW axes, Z up; the same space the WMO's own geometry lives in, which we
-/// already bake into Bevy via [`wow_to_bevy`]). So we map position via `wow_to_bevy`, conjugate the
-/// rotation by the WoW→Bevy basis (the meshes are baked there), and keep the uniform scale (a uniform
-/// scale is basis-invariant). This mirrors the conjugation in [`placement_rotation`].
+/// An MODD doodad's Bevy-space [`Transform`] in its WMO's model space, to compose onto the
+/// instance's (`wmo_world.mul_transform(this)`). Unlike MDDF and MODF, an MODD carries its full
+/// orientation as a quaternion `(x, y, z, w)`, with no base reorientation.
 pub fn wmo_doodad_local(position: [f32; 3], orientation: [f32; 4], scale: f32) -> Transform {
     Transform {
         translation: wow_to_bevy(position),
@@ -80,17 +57,12 @@ pub fn wmo_doodad_local(position: [f32; 3], orientation: [f32; 4], scale: f32) -
     }
 }
 
-/// A rotation authored in **WoW model space** `(x, y, z, w)` → the equivalent rotation of a mesh
-/// already baked into Bevy space: the basis conjugation `B · q · B⁻¹`.
-///
-/// The conjugation (rather than a component shuffle) is the whole point — [`wow_to_bevy`] is a
-/// change of basis, and a rotation changes basis by similarity, not by permuting its parts. Every
-/// caller that has a stored WoW quaternion wants this: an MODD doodad's orientation
-/// ([`wmo_doodad_local`]) and an M2 bone track's rotation key alike.
+/// A WoW-space rotation `(x, y, z, w)` as the rotation of a mesh baked into Bevy space: the basis
+/// conjugation `B · q · B⁻¹`, not a component shuffle.
 pub fn wow_rotation_to_bevy(q: [f32; 4]) -> Quat {
     let q_wow = Quat::from_xyzw(q[0], q[1], q[2], q[3]);
     let to_bevy = wow_to_bevy_quat();
-    // q and −q are the same rotation; normalize guards a denormalized stored quat.
+    // Normalized against a denormalized stored quaternion.
     (to_bevy * q_wow * to_bevy.inverse()).normalize()
 }
 
@@ -102,8 +74,6 @@ mod tests {
         (a - b).length() < 1e-5
     }
 
-    /// `bevy_to_wow` must exactly undo `wow_to_bevy` for arbitrary points (a sign/axis slip in
-    /// either direction would desync our outbound position from the server's frame).
     #[test]
     fn wow_bevy_round_trips() {
         for p in [
@@ -120,11 +90,8 @@ mod tests {
         }
     }
 
-    /// The yaw-conjugation law the transport platform frame rests on (decision 0438 phase 2):
-    /// a WoW orientation θ about WoW-up (+Z) is exactly a Bevy yaw θ about Bevy-up (+Y) through
-    /// the basis map — `wow_to_bevy(rot_z(θ)·v) == rot_y(θ)·wow_to_bevy(v)`. This is what lets a
-    /// rider's boat-local pose convert between spaces with the plain linear map and lets the
-    /// wire's local orientation be `face_yaw − boat_yaw` with no correction term.
+    /// `wow_to_bevy(rot_z(θ)·v) == rot_y(θ)·wow_to_bevy(v)`, which lets a transport rider's wire
+    /// orientation be `face_yaw − boat_yaw` with no correction term.
     #[test]
     fn yaw_conjugates_through_the_basis_map() {
         for theta in [0.0f32, 0.7, 2.4, -1.1, 5.9] {
@@ -138,7 +105,6 @@ mod tests {
         }
     }
 
-    /// Pin the basis mapping with hand-verified golden values: north/west/up map where the docs say.
     #[test]
     fn wow_bevy_basis_is_golden() {
         // WoW +X (north) → Bevy −Z (forward).
@@ -158,8 +124,6 @@ mod tests {
         ));
     }
 
-    /// The conjugation quaternion must reproduce `wow_to_bevy` on every vector — otherwise placement
-    /// rotations are conjugated by the wrong basis and asymmetric doodads/buildings face wrong.
     #[test]
     fn placement_quat_matches_the_position_transform() {
         for w in [
@@ -173,7 +137,6 @@ mod tests {
         }
     }
 
-    /// Determinant +1 ⇒ a proper rotation (no mirroring); the whole coordinate decision rests on this.
     #[test]
     fn transform_is_a_proper_rotation() {
         let m = Mat3::from_quat(wow_to_bevy_quat());
@@ -184,9 +147,6 @@ mod tests {
         );
     }
 
-    /// A pure MDDF/MODF heading (`ry`) is a yaw about WoW +Z, which conjugates to a yaw about
-    /// Bevy +Y — so it must leave the vertical axis fixed. This is the invariant that actually
-    /// validates the conjugation (a wrong basis would tilt the model when it should only spin).
     #[test]
     fn heading_only_placement_spins_about_vertical() {
         for deg in [0.0, 30.0, 90.0, 250.0] {
@@ -199,8 +159,6 @@ mod tests {
         }
     }
 
-    /// An MODD with identity orientation is a pure translate (by `wow_to_bevy(pos)`) + uniform
-    /// scale — no rotation. A wrong conjugation basis would leak rotation in here.
     #[test]
     fn wmo_doodad_identity_is_translate_scale() {
         let t = wmo_doodad_local([3.0, -2.0, 5.0], [0.0, 0.0, 0.0, 1.0], 2.5);
@@ -213,8 +171,6 @@ mod tests {
         assert!((t.scale - Vec3::splat(2.5)).length() < 1e-5);
     }
 
-    /// A doodad at the WMO origin, composed onto the WMO instance's world transform, must land
-    /// exactly at the instance's world position — the property the whole compose relies on.
     #[test]
     fn wmo_doodad_at_origin_lands_on_instance() {
         let wmo_world = Transform {
@@ -227,9 +183,6 @@ mod tests {
         assert!(close(world.translation, wmo_world.translation));
     }
 
-    /// An MODD heading — a rotation about WoW +Z (up) — must conjugate to a yaw about Bevy +Y, so it
-    /// leaves the vertical axis fixed (the same invariant that validates `placement_rotation`'s
-    /// conjugation, but via the quaternion path). A wrong basis would tilt the doodad.
     #[test]
     fn wmo_doodad_heading_spins_about_vertical() {
         for deg in [0.0_f32, 35.0, 90.0, 215.0] {
@@ -243,7 +196,6 @@ mod tests {
         }
     }
 
-    /// Placement rotations are always unit quaternions (a non-unit quat would scale/shear the mesh).
     #[test]
     fn placement_rotations_are_unit_quaternions() {
         for r in [[0.0, 0.0, 0.0], [12.0, 34.0, 56.0], [-90.0, 180.0, 45.0]] {
@@ -252,14 +204,11 @@ mod tests {
         }
     }
 
-    /// Golden snapshot of the full placement rotation, including pitch/roll — captured after the
-    /// fence orientation was confirmed correct on screen. Locks the MDDF convention so a future
-    /// change to the formula can't silently regress doodad/building orientation. The first case is a
-    /// real leaning fence segment (`[rx, ry, rz]` degrees). Quaternions double-cover rotations, so
-    /// compare by |dot| ≈ 1 (q and −q are the same rotation).
+    /// The first case is a real leaning fence segment, `[rx, ry, rz]` in degrees. q and −q are the
+    /// same rotation, so the check is |dot| ≈ 1.
     #[test]
     fn placement_rotation_goldens() {
-        use std::f32::consts::FRAC_1_SQRT_2; // 0.70710678…
+        use std::f32::consts::FRAC_1_SQRT_2;
         let cases = [
             (
                 [86.0_f32, 252.0, 93.5],
diff --git a/crates/benilla-assets/src/gpu_blp.rs b/crates/benilla-assets/src/gpu_blp.rs
index 92a0a976..e1c01f73 100644
--- a/crates/benilla-assets/src/gpu_blp.rs
+++ b/crates/benilla-assets/src/gpu_blp.rs
@@ -1,31 +1,8 @@
-//! Where a BLP's stored form meets the GPU: **can we hand the blocks over untouched?**
-//!
-//! WoW ships almost all world art as S3TC (DXT1/DXT3/DXT5) blocks, and the reference client uploads
-//! those blocks verbatim — `glCompressedTexImage2DARB`, with the software DXT decoder existing only
-//! as a 16-bit-device fallback (wow-re `system/image/image.md`: *"raw passthrough — device eats
-//! DXT"*, and `system/models/scratch/wmo-texture-sampling.md` for the per-level upload formats).
-//! benilla used to decode every one of them to `Rgba8Unorm` on the CPU and upload that: **8x the
-//! bytes of DXT1, 4x of DXT3/DXT5**, on the whole resident working set and on every texture fetch
-//! that misses the cache. On a bandwidth-starved integrated GPU that is the frame's dominant cost,
-//! and it is the divergence Liho's Steam Deck reading exposed (decision 1626).
-//!
-//! Two things have to be true before the blocks can go straight over, and this module owns both:
-//!
-//! 1. **The device must accept BC.** [`bc_supported`] is a process-wide fact published once from
-//!    the render device (see [`publish_bc_support`]). Not a guess: `wgpu-hal`'s Metal backend gates
-//!    `TEXTURE_COMPRESSION_BC` on `format_bc: os_is_mac` and the Vulkan backend on the device's
-//!    `textureCompressionBC`, and bevy's `WgpuSettingsPriority::Functionality` (the default) requests
-//!    every feature the adapter reports. Every desktop target we ship has it — but "every target we
-//!    ship" is not "every device", so the fallback stays.
-//! 2. **The dimensions must be whole 4x4 blocks.** A BC texture is addressed in blocks; a BLP whose
-//!    mip 0 is not a multiple of 4 on both axes cannot be uploaded as one. Real 1.12 world art is
-//!    power-of-two, so this practically never fires — it exists so that when it does, the texture
-//!    renders decoded instead of failing.
-//!
-//! When either is false the caller decodes, exactly as before. That is why the fallback lives here
-//! as one function and not as a flag threaded through two loaders: there is one rule, and both the
-//! async `AssetLoader` lane ([`crate::blp`]) and the synchronous `WorldAssets` lane
-//! ([`crate::world_assets`]) ask it the same question.
+//! Whether a BLP's stored S3TC blocks can go to the GPU untouched, as the reference uploads them
+//! (`glCompressedTexImage2DARB`; its software DXT decoder is a 16-bit-device fallback, device
+//! formats `0x58a230`, per-level upload formats `0x59f270`). They can when the device accepts BC
+//! ([`bc_supported`]) and mip 0 is whole 4x4 blocks; otherwise the chain decodes to `Rgba8Unorm`.
+//! Both the async loader ([`crate::blp`]) and `WorldAssets` ([`crate::world_assets`]) ask here.
 
 use std::sync::OnceLock;
 
@@ -36,42 +13,29 @@ use bevy::render::render_resource::TextureFormat;
 
 static BC_SUPPORTED: OnceLock<bool> = OnceLock::new();
 
-/// Publish whether this run's GPU accepts BC textures. Called once, from the app's plugin
-/// `finish()`, after `RenderPlugin` has inserted `CompressedImageFormatSupport` into the main world.
-///
-/// **Ordering is why this is a `OnceLock` and not a resource.** An `AssetLoader` runs on the async
-/// task pool with no world access, and the synchronous `WorldAssets` lane is called from ordinary
-/// systems — neither can read a resource the other can. But every plugin's `finish()` completes
-/// before the runner's first update, and no BLP is loaded before then, so a single process-wide
-/// publish is both sufficient and race-free. Absent a render device (headless tests), nothing
-/// publishes and [`bc_supported`] reports `false` — the decoded path, which is what a test that
-/// inspects pixels wants anyway.
+/// Publish whether this run's GPU accepts BC, once, from a plugin's `finish()`. A `OnceLock`, not
+/// a resource, because the async loader has no world access; every `finish()` runs before the
+/// first update, so before any BLP loads. Headless, nothing publishes and the decoded path runs.
 pub fn publish_bc_support(supported: bool) {
     let _ = BC_SUPPORTED.set(supported);
 }
 
-/// Does this run's GPU accept BC? `false` until [`publish_bc_support`] says otherwise.
+/// Whether this run's GPU accepts BC; `false` until [`publish_bc_support`].
 pub fn bc_supported() -> bool {
     *BC_SUPPORTED.get().unwrap_or(&false)
 }
 
-/// Publishes [`bc_supported`] from the live render device. Added by
-/// [`crate::register_asset_loaders`], so both the client and the world viewer get it.
-///
-/// **All the work is in `finish`, deliberately.** `RenderPlugin::finish` is what inserts
-/// `CompressedImageFormatSupport` into the main world (bevy_render `lib.rs`, the
-/// `FutureRenderResources` block) — it does not exist at `build` time, and it never exists at all
-/// in a headless app. Reading it here, one plugin later, is the earliest honest moment.
+/// Publishes [`bc_supported`] from the render device; added by [`crate::register_asset_loaders`].
+/// The work is in `finish`: `RenderPlugin::finish` inserts `CompressedImageFormatSupport`, which
+/// does not exist at `build` time or in a headless app.
 pub struct BlpGpuSupportPlugin;
 
 impl Plugin for BlpGpuSupportPlugin {
     fn build(&self, _app: &mut App) {}
 
     fn finish(&self, app: &mut App) {
-        // `WOW_NO_BC=1` — force the decoded path on a device that could take blocks. The A/B lever
-        // for this whole change: it is the only way to price the passthrough against what it
-        // replaced on one machine in one session, and the first thing to try if a texture ever
-        // looks wrong (hardware block decode is not bit-identical to `texpresso`'s — see 1626).
+        // `WOW_NO_BC=1` forces the decoded path: the A/B lever, and the first thing to try when a
+        // texture looks wrong (hardware block decode is not bit-identical to `texpresso`'s).
         let forced_off = std::env::var("WOW_NO_BC").as_deref() == Ok("1");
         let device_can = app
             .world()
@@ -79,9 +43,7 @@ impl Plugin for BlpGpuSupportPlugin {
             .is_some_and(|s| s.0.contains(CompressedImageFormats::BC));
         let supported = device_can && !forced_off;
         publish_bc_support(supported);
-        // At `info`, not `debug`: "which texture lane am I on?" is the first question any perf or
-        // look report about this change has to answer, and a line that only exists in a debug build
-        // cannot answer it from a player's log.
+        // At `info`, so a player's log says which texture lane the run is on.
         if supported {
             info!("blp: DXT blocks upload natively (BC)");
         } else if forced_off {
@@ -92,7 +54,6 @@ impl Plugin for BlpGpuSupportPlugin {
     }
 }
 
-/// Can `chain` be uploaded in the form it is already in?
 fn uploadable_as_blocks(chain: &BlpMipChain) -> bool {
     chain.texels.is_block_compressed()
         && bc_supported()
@@ -100,25 +61,15 @@ fn uploadable_as_blocks(chain: &BlpMipChain) -> bool {
         && chain.height.is_multiple_of(4)
 }
 
-/// A chain and the `TextureFormat` it uploads as — **decided together, returned together.**
-///
-/// This pairing is the whole point of the type. The first cut of this module had two functions, one
-/// that picked the chain and one that picked the format, and a caller reached the second without
-/// going through the first: it uploaded DXT3 blocks under an `Rgba8Unorm` descriptor and wgpu
-/// panicked slicing 262144 bytes out of an 87392-byte chain. There is no way to hold one of these
-/// without the other, so that class of mistake cannot recur.
+/// A chain and the `TextureFormat` it uploads as, decided together so block bytes can never meet
+/// an uncompressed descriptor.
 pub struct UploadChain {
     pub chain: BlpMipChain,
     pub format: TextureFormat,
 }
 
-/// A BLP's authored mip chain in the best form this GPU can take, with the format that matches it:
-/// **blocks if it can, pixels if it cannot.**
-///
-/// The format is always in the **gamma-byte (non-sRGB) lane** every world/model albedo lives in —
-/// the RE'd invariant that the GPU must not linearize albedo on sample
-/// (`wow-5875-re/system/lighting`). `Bc1RgbaUnorm` and friends carry that rule exactly as
-/// `Rgba8Unorm` does, which is what makes the passthrough look-neutral.
+/// A BLP's authored mip chain in the best form this GPU takes, with its format: blocks if it can,
+/// pixels if not. Always non-sRGB, so the GPU never linearizes albedo on sample.
 pub fn for_upload(chain: BlpMipChain) -> UploadChain {
     if uploadable_as_blocks(&chain) {
         let format = match chain.texels {
@@ -130,9 +81,7 @@ pub fn for_upload(chain: BlpMipChain) -> UploadChain {
         };
         return UploadChain { chain, format };
     }
-    // Either it was never blocks, or this device/texture cannot take them. `into_rgba8` is a no-op
-    // in the first case and the decode we were trying to avoid in the second — and it cannot fail,
-    // which is why the format below is unconditionally right.
+    // `into_rgba8` is a no-op on pixels and an infallible decode of blocks.
     UploadChain {
         chain: chain.into_rgba8(),
         format: TextureFormat::Rgba8Unorm,
@@ -153,8 +102,6 @@ mod tests {
         }
     }
 
-    /// Without a published device fact we decode. A headless test that reads pixels depends on
-    /// this, and so does any run whose GPU genuinely lacks BC.
     #[test]
     fn no_published_support_means_the_decoded_path() {
         // `publish_bc_support` is never called in this test binary, so the lock stays empty.
@@ -164,9 +111,6 @@ mod tests {
         assert!(up.chain.is_rgba8(), "blocks must have been decoded");
     }
 
-    /// **The invariant this module exists to hold**: whatever comes back, the bytes and the format
-    /// agree about how big mip 0 is. This is the assertion whose absence let block bytes be
-    /// uploaded under an `Rgba8Unorm` descriptor.
     #[test]
     fn the_returned_format_always_matches_the_returned_bytes() {
         for texels in [
@@ -195,10 +139,8 @@ mod tests {
         }
     }
 
-    /// The block-alignment rule is on mip 0's dimensions, both axes. wgpu-core rejects a compressed
-    /// texture whose size is not a whole number of blocks (`NotMultipleOfBlockWidth/Height`), and
-    /// its default error handler makes that a process panic — so this is a hard gate, not a
-    /// preference.
+    /// wgpu-core rejects a compressed texture that is not whole blocks
+    /// (`NotMultipleOfBlockWidth/Height`), and its default error handler panics.
     #[test]
     fn non_block_aligned_dimensions_are_refused() {
         for (w, h) in [(258u32, 256u32), (256, 258), (6, 6), (1, 1)] {
@@ -209,7 +151,6 @@ mod tests {
         }
     }
 
-    /// An already-decoded chain is never re-encoded, and never copied through a decode path.
     #[test]
     fn an_rgba_chain_passes_through_untouched() {
         let c = chain(BlpTexels::Rgba8Unorm, 8, 8);
diff --git a/crates/benilla-assets/src/lib.rs b/crates/benilla-assets/src/lib.rs
index dd1a202c..fe83b930 100644
--- a/crates/benilla-assets/src/lib.rs
+++ b/crates/benilla-assets/src/lib.rs
@@ -1,12 +1,5 @@
-//! `benilla-assets` — the bridge from the WoW 1.12.1 MPQ patch chain into Bevy's asset system.
-//!
-//! Registers an `mpq://` [`AssetSource`](bevy::asset::io::AssetSource) backed by
-//! [`benilla_formats::Chain`], so every WoW asset loads through the standard
-//! [`AssetServer`](bevy::asset::AssetServer) as a `Handle<T>` — gaining async loading, handle dedup,
-//! a dependency graph, and hot-reload for free, instead of the bespoke caches and hand-rolled
-//! worker/finalize pipeline the old client carried (decision 0005). The per-format
-//! [`AssetLoader`](bevy::asset::AssetLoader)s (BLP→`Image`, M2/WMO→model, ADT→tile, DBC→catalog)
-//! build on this foundation.
+//! `benilla-assets`: the WoW 1.12.1 MPQ patch chain as an `mpq://` Bevy asset source backed by
+//! [`benilla_formats::Chain`], and the per-format loaders (BLP, M2, WMO, ADT, WDT) on top of it.
 
 use std::path::Path;
 use std::sync::Arc;
@@ -50,7 +43,7 @@ pub use adt::{chunk_to_mesh, chunks_to_mesh, AdtLoader, AdtTile, ChunkShading};
 pub use wdt::{WdtIndex, WdtIndexLoader};
 mod blp;
 pub use blp::{BlpImageLoader, BlpLoaderSettings, BlpVariant};
-/// Whether this run's GPU can eat WoW's stored DXT blocks, and the chain form that follows.
+/// Whether this GPU takes WoW's stored DXT blocks, and the chain form that follows.
 mod gpu_blp;
 pub use gpu_blp::{bc_supported, for_upload, publish_bc_support, BlpGpuSupportPlugin, UploadChain};
 mod tex_filter;
@@ -73,16 +66,14 @@ pub use wmo::{
 /// The asset-source id for MPQ-backed assets: load paths look like `mpq://World/Azeroth/foo.adt`.
 pub const MPQ_SOURCE: &str = "mpq";
 
-/// A Bevy [`AssetReader`] over the vanilla MPQ patch chain. Cheap to clone — every clone shares the
-/// one open chain ([`Chain`] reads through fresh per-call handles, so this is `Send + Sync`).
+/// A Bevy [`AssetReader`] over the MPQ patch chain; every clone shares the one open [`Chain`].
 #[derive(Clone)]
 pub struct MpqAssetReader {
     chain: Arc<Chain>,
 }
 
 impl MpqAssetReader {
-    /// Open the patch chain from a `Data` directory (or a single `.MPQ`), ready to back an
-    /// `mpq://` source.
+    /// Open the patch chain from a `Data` directory or a single `.MPQ`.
     pub fn open(data_dir: &Path) -> Result<Self> {
         Ok(Self {
             chain: Arc::new(Chain::open(data_dir)?),
@@ -95,8 +86,7 @@ impl AssetReader for MpqAssetReader {
         let raw = path
             .to_str()
             .ok_or_else(|| AssetReaderError::NotFound(path.to_path_buf()))?;
-        // Strip the sampler-mode marker ([`texture_url`]) before the archive lookup — it is part of
-        // the ASSET identity, not of the file name.
+        // The sampler-mode marker (`texture_url`) names the asset, not the archive file.
         let stripped = strip_sampler_marker(raw);
         let internal = stripped.as_deref().unwrap_or(raw);
         if !self.chain.contains(internal) {
@@ -118,7 +108,7 @@ impl AssetReader for MpqAssetReader {
         &'a self,
         path: &'a Path,
     ) -> Result<Box<PathStream>, AssetReaderError> {
-        // We load by explicit path; directory enumeration / folder-watching isn't supported.
+        // Loads are by explicit path; there is no directory listing.
         Err(AssetReaderError::NotFound(path.to_path_buf()))
     }
 
@@ -127,22 +117,12 @@ impl AssetReader for MpqAssetReader {
     }
 }
 
-/// The sampler-mode marker separator in an `mpq://` texture URL (see [`texture_url`]).
+/// The sampler-mode marker in an `mpq://` texture URL.
 const SAMPLER_MARKER: char = '@';
 
-/// Build the `mpq://` URL for a model texture at a given sampler address mode.
-///
-/// The address mode lives on the GPU sampler, which in Bevy rides the `Image`, which is keyed by
-/// asset path — so two modes of one `.blp` need two asset paths. **243 of the corpus's 4677 texture
-/// paths are asked for more than one mode** (`benilla-extract texmodescan`), so this is not a
-/// hypothetical: without it, whichever model loaded a shared sheet first would decide the mode for
-/// every later one.
-///
-/// Repeat/repeat — the overwhelming majority — keeps the bare path, so the common case is one upload
-/// and every pre-existing URL is unchanged. Any other mode gets a marker **before the extension**
-/// (`…\leaves01@cc.blp`), because Bevy selects the loader by extension and a trailing marker would
-/// stop `.blp` resolving. [`MpqAssetReader::read`] strips it back off for the archive lookup.
-/// Decision 0763.
+/// The `mpq://` URL of a model texture at a sampler address mode. Bevy keys the sampler to the
+/// `Image` and the `Image` to its path, so a mode other than repeat/repeat marks the path before
+/// the extension (`…/leaves01@cc.blp`), which must stay `.blp` to pick the loader.
 pub fn texture_url(internal: &str, wrap: (bool, bool)) -> String {
     let path = internal.replace('\\', "/").to_ascii_lowercase();
     if wrap == (true, true) {
@@ -159,27 +139,13 @@ pub fn texture_url(internal: &str, wrap: (bool, bool)) -> String {
     }
 }
 
-/// Bevy resource wrapper around the format crate's [`MapCatalog`] (`mapId` -> directory +
-/// `LoadingScreenID`), read out of `Map.dbc`.
-///
-/// The newtype exists because the orphan rule forbids `Resource` on a foreign type, and it lives
-/// here rather than in the client for the same reason the rest of this crate does: a `.dbc` table
-/// turned into something Bevy can hold is exactly this layer's job, and the three readers are the
-/// WDL streamer, the world-map UI and the loading screen — one engine, two game (decision 1164).
-/// The *loader* stays up top with the patch chain's plugin shell, which is what inserts it.
+/// The `Map.dbc` [`MapCatalog`] (`mapId` to directory and `LoadingScreenID`) as a Bevy resource; a
+/// newtype because the orphan rule forbids `Resource` on a foreign type.
 #[derive(Resource)]
 pub struct MapCatalogRes(pub benilla_formats::MapCatalog);
 
-/// The `mpq://` URL an authored **model** path resolves to.
-///
-/// The archive holds 1.12.1 `.mdx`/`.mdl`, the loader produces an `M2Model`, and Bevy picks a loader
-/// by extension — so every reference is normalised to one lowercase `mpq://…m2`, which is also what
-/// makes the handle dedup work (a path differing only in case or slash would load twice). The WMO and
-/// skin builders are the same rewrite for their own extensions. They sit beside [`texture_url`]
-/// because they are the same act: turning a path the game files wrote into the one URL this crate's
-/// asset source answers to (decision 1164).
-/// A model reference path (`.mdx`/`.mdl`, mixed case, backslashes) → its `mpq://…m2` load URL.
-/// Lowercased so case variants share one `AssetServer` handle; the physical archive file is `.m2`.
+/// A model reference path (`.mdx`/`.mdl`, any case, backslashes) as its lowercase `mpq://…m2` URL:
+/// the archive file is `.m2`, and one spelling per model keeps the handle dedup working.
 pub fn m2_url(raw: &str) -> String {
     let p = raw.to_ascii_lowercase().replace('\\', "/");
     let stem = p
@@ -190,13 +156,13 @@ pub fn m2_url(raw: &str) -> String {
     format!("mpq://{stem}.m2")
 }
 
-/// A WMO root path → its `mpq://…wmo` load URL (already `.wmo`; lowercased for handle dedup).
+/// A WMO root path as its `mpq://…wmo` URL, lowercased for handle dedup.
 pub fn wmo_url(raw: &str) -> String {
     format!("mpq://{}", raw.to_ascii_lowercase().replace('\\', "/"))
 }
 
-/// A creature skin variation → its `mpq://…blp` URL: `<model-dir>\<name>.blp`. `model_dir` is the
-/// directory of the creature's model path (where its `Monster1/2/3` skins live).
+/// A creature skin variation's `mpq://` URL, `<model-dir>/<name>.blp`: the `Monster1/2/3` skins
+/// live beside the model.
 pub fn skin_url(model_dir: &str, name: &str) -> String {
     let dir = model_dir.replace('\\', "/").to_ascii_lowercase();
     let name = name.to_ascii_lowercase();
@@ -220,17 +186,15 @@ pub fn sampler_mode_of(path: &str) -> (bool, bool) {
     }
 }
 
-/// Remove a [`texture_url`] marker, yielding the real archive path. `None` when there is none.
+/// The archive path under a [`texture_url`] marker; `None` when unmarked.
 fn strip_sampler_marker(path: &str) -> Option<String> {
     let (stem, ext) = path.rsplit_once('.')?;
     let (base, tag) = stem.rsplit_once(SAMPLER_MARKER)?;
     matches!(tag, "rc" | "cr" | "cc").then(|| format!("{base}.{ext}"))
 }
 
-/// Register the `mpq://` asset source on `app`, backed by the patch chain at `data_dir`.
-///
-/// Must be called **before** Bevy's `AssetPlugin` builds (i.e. before `DefaultPlugins`): asset
-/// sources are read when the plugin initializes the [`AssetServer`](bevy::asset::AssetServer).
+/// Register the `mpq://` source on `app`, backed by the patch chain at `data_dir`. Call it before
+/// `AssetPlugin` builds (before `DefaultPlugins`), which reads the sources.
 pub fn register_mpq_source(app: &mut App, data_dir: &Path) -> Result<()> {
     let reader = MpqAssetReader::open(data_dir)?;
     app.register_asset_source(
@@ -240,24 +204,20 @@ pub fn register_mpq_source(app: &mut App, data_dir: &Path) -> Result<()> {
     Ok(())
 }
 
-/// Register benilla's asset loaders on `app`. Call **after** Bevy's `AssetPlugin` (loaders register
-/// into the live [`AssetServer`](bevy::asset::AssetServer)); pair with [`register_mpq_source`], which
-/// must run *before* `AssetPlugin`.
+/// Register benilla's asset loaders on `app`, after `AssetPlugin`, into its live `AssetServer`.
 pub fn register_asset_loaders(app: &mut App) {
     app.init_asset::<M2Model>();
     app.init_asset::<WmoModel>();
     app.init_asset::<AdtTile>();
     app.init_asset::<WdtIndex>();
-    // Publishes whether this device can eat DXT blocks (decision 1626). A plugin, because the
-    // answer only exists after `RenderPlugin::finish` — see `BlpGpuSupportPlugin`.
+    // A plugin: whether the device takes DXT blocks is known only after `RenderPlugin::finish`.
     app.add_plugins(BlpGpuSupportPlugin);
     app.register_asset_loader(BlpImageLoader);
     app.register_asset_loader(M2ModelLoader);
     app.register_asset_loader(WmoModelLoader);
     app.register_asset_loader(AdtLoader);
     app.register_asset_loader(WdtIndexLoader);
-    // The render materials' WGSL, compiled in rather than served off the host binary's asset root
-    // (decision 1164) — same "after AssetPlugin" requirement as the loaders above, so it rides here.
+    // The materials' WGSL, compiled in; it too needs `AssetPlugin` first.
     materials::register_shaders(app);
 }
 
@@ -267,25 +227,21 @@ mod tests {
     use bevy::camera::primitives::MeshAabb;
     use bevy::tasks::block_on;
 
-    /// The sampler-mode URL round-trips, and repeat/repeat stays byte-identical to the old bare
-    /// path — so the common case keeps ONE upload and no pre-existing URL changed (decision 0763).
     #[test]
     fn sampler_mode_rides_the_asset_path_and_round_trips() {
         let tex = "World\\KhazModan\\Ironforge\\PassiveDoodads\\Trees\\IronForgeleaves01.blp";
-        // The default is the bare path — unchanged from before this scheme existed.
         let repeat = texture_url(tex, (true, true));
         assert_eq!(
             repeat,
             "mpq://world/khazmodan/ironforge/passivedoodads/trees/ironforgeleaves01.blp"
         );
         assert_eq!(sampler_mode_of(&repeat), (true, true));
-        // Every other mode marks the STEM, so the `.blp` extension still selects the loader.
+        // Every other mode marks the stem, so `.blp` still picks the loader.
         for wrap in [(false, false), (true, false), (false, true)] {
             let url = texture_url(tex, wrap);
             assert!(url.ends_with(".blp"), "extension must survive: {url}");
             assert_ne!(url, repeat, "a marked mode is a distinct asset path");
             assert_eq!(sampler_mode_of(&url), wrap, "round-trip {wrap:?}");
-            // ...and the marker comes back off for the archive lookup.
             assert_eq!(
                 strip_sampler_marker(url.strip_prefix("mpq://").unwrap()).as_deref(),
                 Some("world/khazmodan/ironforge/passivedoodads/trees/ironforgeleaves01.blp"),
@@ -302,7 +258,6 @@ mod tests {
         let data = benilla_formats::wow_data_or_skip!();
         let reader = MpqAssetReader::open(&data).expect("open mpq reader");
 
-        // A real file resolves and drains to its bytes through the Bevy AssetReader/Reader traits.
         let bytes = block_on(async {
             let mut r = AssetReader::read(&reader, Path::new("DBFilesClient/Spell.dbc"))
                 .await
@@ -314,7 +269,7 @@ mod tests {
         assert_eq!(&bytes[..4], b"WDBC", "Spell.dbc starts with the WDBC magic");
         assert!(bytes.len() > 1_000_000, "Spell.dbc should be sizable");
 
-        // A missing path yields NotFound — the variant Bevy relies on for meta fallback.
+        // A missing path is `NotFound`, which Bevy's meta fallback relies on.
         let missing = block_on(AssetReader::read(&reader, Path::new("does/not/exist.blp")));
         assert!(
             matches!(missing, Err(AssetReaderError::NotFound(_))),
@@ -325,7 +280,6 @@ mod tests {
     #[test]
     fn loads_a_blp_image_through_the_full_mpq_pipeline() {
         let data = benilla_formats::wow_data_or_skip!();
-        // Full pipeline, headless: mpq:// source → AssetServer → BlpImageLoader → Handle<Image>.
         let mut app = App::new();
         app.add_plugins(MinimalPlugins);
         register_mpq_source(&mut app, &data).expect("register mpq source");
@@ -339,7 +293,7 @@ mod tests {
             .load("mpq://Interface/Icons/Spell_Holy_ArcaneIntellect.blp");
 
         let mut got = None;
-        // Same generous ceiling as the WMO test below — parallel-session load starves the IO pool.
+        // A generous ceiling: a parallel gate run starves the IO pool.
         for _ in 0..15_000 {
             app.update();
             if let Some(img) = app.world().resource::<Assets<Image>>().get(&handle) {
@@ -361,12 +315,8 @@ mod tests {
         );
     }
 
-    /// Regression guard: `load_with_settings(Sprite)` must reach the loader on the async `mpq://`
-    /// path so a streamed tile lands as `Rgba8UnormSrgb`, not the loader's `WorldArt` default
-    /// (`Rgba8Unorm`). The minimap streams its tiles this way (`minimap.rs`), and the UI pass's
-    /// contract is sRGB textures (linearize → multiply → re-encode); a silent regression to the
-    /// gamma-space default re-encodes every tile ~2× brighter — the decision-0178 over-bright class
-    /// of bug, but for the minimap. Skips without the vanilla client data.
+    /// The minimap streams its tiles with `load_with_settings(Sprite)`; the UI pass wants sRGB, and
+    /// the `WorldArt` default would draw every tile about twice as bright.
     #[test]
     fn minimap_tile_settings_reach_the_async_loader() {
         use bevy::render::render_resource::TextureFormat;
@@ -378,9 +328,7 @@ mod tests {
         app.init_asset::<Image>();
         register_asset_loaders(&mut app);
 
-        // IN ISOLATION — the real app (minimap.rs) only ever loads a tile via
-        // `load_with_settings(Sprite)`, never a bare `load()` of the same path. Loading both here
-        // would let Bevy's path-dedup hand the second call the first's settings, masking the truth.
+        // In isolation: a bare `load()` of the same path would share the handle and its settings.
         let tile = "mpq://textures/Minimap/ea283abc0bf9637c3fad5e840a65b38b.blp";
         let server = app.world().resource::<AssetServer>().clone();
         let sprite_h: Handle<Image> =
@@ -389,7 +337,7 @@ mod tests {
             });
 
         let mut sprite_fmt = None;
-        // Same generous ceiling as the WMO test below — parallel-session load starves the IO pool.
+        // A generous ceiling: a parallel gate run starves the IO pool.
         for _ in 0..15_000 {
             app.update();
             if let Some(img) = app.world().resource::<Assets<Image>>().get(&sprite_h) {
@@ -406,10 +354,7 @@ mod tests {
         );
     }
 
-    /// The WMO interior-minimap tile grid (`crate::minimap::group_axis_grid`) verified against real
-    /// authored data: load Ironforge and check the per-group tile count each axis matches the
-    /// `md5translate.trs` ground truth — group 66 = 2×2, 44 = 1(X)×2(Y), 89 = 2(X)×1(Y), and the
-    /// small groups 1×1. Grounds the (RE-inferred) footprint→grid bake the interior renderer rests on.
+    /// Ironforge's interior minimap tile counts per group, against `md5translate.trs`.
     #[test]
     fn ironforge_group_grid_matches_trs() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -425,9 +370,7 @@ mod tests {
             .resource::<AssetServer>()
             .load("mpq://World/wmo/KhazModan/Cities/Ironforge/Ironforge.wmo");
         let mut model = None;
-        // A generous ~30 s ceiling (healthy runs finish in well under a second): the async IO
-        // pool gets starved when a parallel session runs its own full gates on this machine, and
-        // the old ~4 s budget flaked exactly then (2026-07-10, two concurrent workspace runs).
+        // About 30 s, though a healthy run takes under one: a parallel gate run starves IO.
         for _ in 0..15_000 {
             app.update();
             if let Some(m) = app.world().resource::<Assets<WmoModel>>().get(&h) {
@@ -437,7 +380,7 @@ mod tests {
             std::thread::sleep(std::time::Duration::from_millis(2));
         }
         let m = model.expect("Ironforge loads");
-        // (group index, expected X-count, expected Y-count) — read off the trs tile names.
+        // (group, X tiles, Y tiles), read off the trs tile names.
         let grid = |ext: f32| crate::minimap_grid::group_axis_grid(ext).0;
         for &(g, ex_n, ey_n) in &[
             (1, 1, 1),
@@ -463,16 +406,14 @@ mod tests {
         app.add_plugins(bevy::asset::AssetPlugin::default());
         app.init_asset::<Image>();
         app.init_asset::<Mesh>();
-        // The M2 loader emits labeled sub-assets the skinned + animated path needs (decision 0019): the
-        // inverse bind poses, plus the idle `AnimationClip` + `AnimationGraph`. The real app registers
-        // these via `DefaultPlugins` (bevy_mesh's `MeshPlugin` + `AnimationPlugin`); the minimal harness
-        // registers them here so the campfire's M2 (which has bones + a Stand sequence) loads.
+        // The M2 loader emits inverse bind poses, an `AnimationClip` and an `AnimationGraph`, which
+        // `DefaultPlugins` would register.
         app.init_asset::<bevy::mesh::skinning::SkinnedMeshInverseBindposes>();
         app.init_asset::<bevy::animation::AnimationClip>();
         app.init_asset::<bevy::animation::graph::AnimationGraph>();
-        register_asset_loaders(&mut app); // inits M2Model + registers BLP/M2 loaders
+        register_asset_loaders(&mut app);
 
-        // A doodad with embedded (hardcoded) textures — the campfire (`.mdx` ref → `.m2` physical file).
+        // The campfire: a doodad with embedded textures.
         let handle: Handle<M2Model> = app
             .world()
             .resource::<AssetServer>()
@@ -498,9 +439,8 @@ mod tests {
         assert!(has_bounds, "M2 carries authored bounds");
         assert!(textured > 0, "campfire batches reference embedded textures");
 
-        // The loader ships geometry, no meshes (decision 0834) — the app builds the render form.
-        // Exercise both builders per batch: non-empty, and the static form must yield the Aabb
-        // the spawn side inserts explicitly (RENDER_WORLD meshes race `calculate_bounds`).
+        // The loader ships geometry; the spawn side inserts the static form's Aabb itself, as
+        // `RENDER_WORLD` meshes race `calculate_bounds`.
         for g in &geometries {
             let mesh = submesh_to_static_mesh(g);
             assert!(mesh.count_vertices() > 0, "submesh has vertices");
@@ -525,7 +465,7 @@ mod tests {
         app.init_asset::<Mesh>();
         register_asset_loaders(&mut app);
 
-        // The Goldshire Inn — a root + group WMO; the loader reads the groups via read_asset_bytes.
+        // The Goldshire Inn: a root and its group files.
         let handle: Handle<WmoModel> = app
             .world()
             .resource::<AssetServer>()
@@ -550,7 +490,6 @@ mod tests {
         );
         assert!(textured > 0, "WMO batches reference textures");
 
-        // Geometry, no meshes (decision 0834): the static build is the WMO's one render form.
         for g in &geometries {
             let mesh = submesh_to_static_mesh(g);
             assert!(mesh.count_vertices() > 0, "group submesh has vertices");
@@ -561,7 +500,6 @@ mod tests {
     #[test]
     fn loads_an_adt_terrain_tile_through_the_pipeline() {
         let data = benilla_formats::wow_data_or_skip!();
-        // Find an existing Elwynn-area Azeroth tile (don't hardcode exact coords).
         let reader = benilla_formats::Chain::open(&data).expect("open chain");
         let mut url = None;
         'find: for tx in 28..36u32 {
@@ -606,11 +544,7 @@ mod tests {
         let (cells, n_shading, layer_h, alpha_h, shadow_h, n_doodads) =
             info.expect("the ADT tile should load via mpq:// + AdtLoader");
 
-        // One drawn mesh per MCNK cell, never one merged slab (decision 0780) — the exterior-scene
-        // cull's unit is the chunk, and a tile that loads as a single object cannot be culled from
-        // inside a building. The loader ships the shading (index-parallel with the chunks); the
-        // mesh itself is the app's paced `chunk_to_mesh` build — exercised per cell here. Every
-        // drawn cell must be a 145-vertex 9×9+8×8 grid.
+        // One mesh per drawn MCNK chunk, a 145-vertex 9×9 + 8×8 grid.
         assert_eq!(n_shading, cells.len(), "one ChunkShading per decoded chunk");
         let drawn: Vec<Mesh> = cells
             .iter()
@@ -645,7 +579,7 @@ mod tests {
         );
         assert!(images.get(&alpha_h).is_some(), "alpha array present");
         assert!(images.get(&shadow_h).is_some(), "shadow array present");
-        // Placement lists are carried as data (count is tile-dependent — some tiles are bare).
+        // Some tiles have no placements, so the count is only printed.
         eprintln!(
             "ADT tile loaded: {} MCNK cells, {n_doodads} doodad placements",
             drawn.len()
diff --git a/crates/benilla-assets/src/m2.rs b/crates/benilla-assets/src/m2.rs
index 49339370..2ea85e23 100644
--- a/crates/benilla-assets/src/m2.rs
+++ b/crates/benilla-assets/src/m2.rs
@@ -1,21 +1,6 @@
-//! M2 → model asset loader.
-//!
-//! Decodes a WoW M2 (`*.m2`) into an [`M2Model`]: one [`ModelSubmesh`] per render batch, each
-//! carrying the batch's **decoded geometry** plus its texture as a `Handle<Image>` **dependency**
-//! (through the `mpq://` source). **The loader ships no meshes** (decision 0834, the model-lane
-//! twin of 0832's terrain rule): a labeled mesh sub-asset lands the whole model's render form in
-//! ONE frame — the city first-contact spike — so the app builds each batch's `Mesh` paced at the
-//! spawn side (`benilla`'s `model_forms`, via [`submesh_to_static_mesh`](crate::submesh_to_static_mesh)
-//! / [`submesh_to_skinned_mesh`](crate::submesh_to_skinned_mesh)).
-//!
-//! Deliberately app-independent: ships **geometry + texture handles + metadata only**, not materials
-//! (the WoW lighting material is an app concern built at spawn) — so this asset is shared verbatim by
-//! doodads, creatures, GameObjects, and the star model. Creature **skin variations** (`Monster1/2/3`)
-//! are blank here (no `skins` passed) and resolved at the spawn site from `CreatureDisplayInfo`; this
-//! loads the model's own embedded (hardcoded) textures.
-//!
-//! References use `.mdx`/`.mdl`, but the physical archive file is `.m2`; callers map the extension when
-//! forming the `mpq://…m2` load path (the loader registers for `m2`).
+//! The M2 asset loader: one [`ModelSubmesh`] per render batch, with its decoded geometry and a
+//! texture dependency but no `Mesh` (see [`ModelSubmesh`]), plus the model's rig, animations,
+//! effects and cameras. Materials and creature skins are applied at the spawn site.
 
 use std::sync::Arc;
 
@@ -41,171 +26,105 @@ use crate::model::{
     upper_subtree_root, AnimClip, ModelAnimations, ModelAttachment, ModelSkeleton, ModelSubmesh,
 };
 
-/// A loaded M2 model: its render batches + authored bounds (the distance-fade size source) + the
-/// coarse collision hull (the app bakes a collider from it per placement) + its particle emitters.
+/// A loaded M2: its batches, bounds, collision hull, rig, animations, effects and cameras.
 #[derive(Asset, TypePath, Clone)]
 pub struct M2Model {
     pub submeshes: Vec<ModelSubmesh>,
-    /// Authored bounding sphere/box (model-local yards) — the reference's distance-fade size. `None`
-    /// if the header bounds couldn't be read.
+    /// The authored bounds (model-local yards), the reference's distance-fade size.
     pub bounds: Option<M2Bounds>,
-    /// The doodad's collision hull in raw WoW model space (trunk/solid; ≪ render mesh). `None` when the
-    /// model carries no hull (`nBoundingTriangles == 0` — many small props are collide-iff-hull).
+    /// The collision hull in WoW model space; `None` means the model does not collide.
     pub collision: Option<CollisionMesh>,
-    /// Particle emitters (flames, glows, smoke). Each carries its parsed def (positions in raw WoW
-    /// model space) + its resolved texture handle. Empty for most models; one or two for campfires.
+    /// Particle emitters, positions in WoW model space.
     pub emitters: Vec<ModelEmitter>,
-    /// Ribbon emitters (weapon trails, wisp streamers, missile trails — wow-re
-    /// `ribbon-emitter-spec.md`). Same shape as the particle emitters: parsed def + resolved trail
-    /// texture + the host bone's pivot for joint riding. Empty for nearly everything (176 models
-    /// corpus-wide author one).
+    /// Ribbon emitters (trails), the reference's `CRibbonEmitter` (simulated at `0x7b7e60`).
     pub ribbons: Vec<ModelRibbon>,
-    /// M2 light blocks (raw WoW model space + the host bone's rest pivot). The spawn site turns each
-    /// casting `type==1` (point) light into a Bevy `PointLight` that lays the faithful dynamic
-    /// hot-spot on every lit surface (decisions 0016/0273). Empty for nearly all models; one on fire
-    /// props (campfire/firepit/cooker/forge) — and one on the held torch every torch-bearing NPC
-    /// carries.
+    /// M2 light blocks in WoW model space; fire props and held torches author a point light.
     pub lights: Vec<ModelLight>,
-    /// The model's rest skeleton in Bevy space (decision 0019) — the joint tree the skinned creature
-    /// path spawns one entity per bone from. Empty for a boneless model.
+    /// The rest skeleton in Bevy space; empty for a boneless model.
     pub skeleton: ModelSkeleton,
-    /// The matching inverse bind poses (`translate(−pivot)` per bone), shared across every instance of
-    /// this model; each skinned submesh references it from its `SkinnedMesh`. A labeled sub-asset.
+    /// The inverse bind poses, `translate(−pivot)` per bone, as a labeled sub-asset.
     pub inverse_bindposes: Handle<SkinnedMeshInverseBindposes>,
-    /// The model's animations, ready to play (decision 0019) — one shared `AnimationGraph` with every
-    /// sequence's clip. `None` for a model with no animated sequences (static props, boneless models).
-    /// Built once here; each creature instance drives it with its own `AnimationPlayer`.
+    /// The animations; `None` when no bone, global sequence, emitter or material loop animates.
     pub animations: Option<ModelAnimations>,
-    /// The **file-order-first sequence's authored duration** (seconds, one full pass) — carried even
-    /// when no clip builds ([`ModelAnimations`] drops sequences that move no bone, and a model whose
-    /// sequences all sit still has no `animations` at all). The real client's effect-completion
-    /// clock runs one pass of the armed sequence regardless of bone keys or the LOOP flag
-    /// (byte-verified, wow-re `ceffect-selfterm.md`: the fire is the CM2 advance `0x7194f8`, a pure
-    /// end-boundary compare; loop is tested only *after* it) — the spell-fx self-termination reads
-    /// this. Named approximation: the client arms `animationLookup[0]`'s sequence, not strictly the
-    /// file-order-first one; they coincide on every effect model probed (single-sequence models).
-    /// `None` for a model with no sequences at all.
+    /// The first sequence's length in seconds, the spell-fx completion clock: the reference ends
+    /// an effect after one pass of its armed sequence, whatever its bones or loop flag
+    /// (`0x7194f8`). The reference arms `animationLookup[0]`'s sequence, not the first; the two
+    /// coincide on every effect model checked.
     pub first_seq_span: Option<f32>,
-    /// **Every sequence the file owns, in file order** — id, slot, length, loop — whatever
-    /// [`Self::animations`] kept a clip for. The UI model pane's clock needs exactly this
-    /// (decision 2008): which `AnimationData` ids the file answers to, how long each runs and
-    /// whether it clamps — for sequences that key no bone too, which `ModelAnimations` drops
-    /// (the cooldown indicator's sweep keys a constant on its one bone; its texture transforms
-    /// and colour tracks are what move). Empty for a file with no sequences.
+    /// Every parsed sequence in file order, listed even when [`Self::animations`] is `None`: the
+    /// UI model pane's clock reads them.
     pub sequences: Vec<M2SequenceInfo>,
-    /// The model's attachment points (decision 0072 — held items): weapon/shield hand slots, sheath
-    /// points, etc. Each carries the bone it rides + its bind-pose-relative offset (see
-    /// [`ModelAttachment`]). Empty for a model with no attachment table (most doodads/WMO props).
+    /// Attachment points (hands, sheaths), each on its bone.
     pub attachments: Vec<ModelAttachment>,
-    /// The animation-event table's positional markers (`$CSL`/`$CSR`/`$CST` casting hands, `$BWR`
-    /// ranged release, …), baked like [`Self::attachments`] and queried by 4CC first-match — the
-    /// client's `0x7130e0`/`0x7131b0` surface. Empty for a model with no events.
+    /// The event table's positional markers, queried by 4CC, first match (`0x7130e0`/`0x7131b0`).
     pub markers: Vec<crate::ModelMarker>,
-    /// The model's authored **portrait camera** (`benilla_formats::M2PortraitCamera` baked to Bevy
-    /// space) — the exact rig the real client renders the unit-frame portrait through (VERIFIED,
-    /// wow-re portrait-render §4: `cameraLookup[0]`, `lookAt` + authored perspective, no engine-side
-    /// framing on top). `None` for a model with no camera table (props, a few creatures).
+    /// The unit-frame portrait camera, `cameraLookup[0]` (`0x713540`), rendered as authored:
+    /// `lookAt` and the record's perspective, with no framing on top (`0x7ac640`).
     pub portrait_camera: Option<PortraitCamera>,
-    /// The camera **table's first record** — the glue screens' `Model:SetCamera(0)` rig (the
-    /// create/select background scenes; their camera *lookup* is the 0xffff none sentinel, so
-    /// `portrait_camera` sees nothing there). Same Bevy-space conversion as `portrait_camera`.
+    /// The camera table's first record, the glue scenes' `Model:SetCamera(0)`; their
+    /// `cameraLookup[0]` is the `0xffff` none sentinel.
     pub camera0: Option<PortraitCamera>,
-    /// The camera table's **second** record — what a 1.12 `<PlayerModel>` UI widget (the paper doll,
-    /// the inspect pane, the pet page) renders through (VERIFIED, wow-re
-    /// `ui/scratch/modelframe-camera-law.md`: `0x505b30` → the chooser `0x505890` selects **raw
-    /// index 1**, the `type == 1` "characterinfo" camera, and freezes it at `0x7acf10`).
-    ///
-    /// **Raw, not through `cameraLookup`** — that array is the portrait bake's path and is not
-    /// consulted here; the index is a literal 1 whatever the record's `type` says. `None` for a
-    /// model with fewer than two cameras, where the client synthesizes a *fixed* camera instead
-    /// (transcribed at the framing site). Same Bevy-space conversion as `portrait_camera`.
+    /// The camera table's second record, which a `<PlayerModel>` (paper doll, inspect, pet page)
+    /// renders through: raw index 1, not through `cameraLookup` (`0x505b30`, chooser `0x505890`,
+    /// frozen at `0x7acf10`). `None` with fewer than two cameras, where the reference builds a
+    /// fixed camera.
     pub pane_camera: Option<PortraitCamera>,
-    /// The **whole camera table**, in file order — the raw index space a `<Model>` widget's
-    /// `SetCamera(n)` walks (decision 2027). `camera0` and `pane_camera` above are the two fixed
-    /// indices two other paths take; this is the general one, and it is the only one that can
-    /// answer "how many cameras does this file have", which is the question that decides whether
-    /// a pane renders through the perspective leg at all (an index past the count installs a NULL
-    /// camera and the pane falls back to the orthographic leg).
+    /// The whole camera table by raw index, for `SetCamera(n)`; an index past its end leaves the
+    /// pane on the orthographic leg.
     pub cameras: Vec<PaneCamera>,
-    /// A bow's `$WTT`/`$WTB` bowstring anchors (wow-re `nocked-ammo-cancel.md` §G2), baked to Bevy
-    /// space: `[top, bottom]` as `(bone index, model-local position)` — the two limb-tip points the
-    /// engine-drawn string spans. `None` for every non-bow model.
+    /// A bow's `$WTT`/`$WTB` string ends `[top, bottom]` as (bone, Bevy-space point), for the
+    /// string drawer `0x611ff0`.
     pub string_anchors: Option<[(u16, Vec3); 2]>,
-    /// The fishing pole's `$CCH` line anchor (wow-re `fishing-line.md` §2), baked to Bevy space in
-    /// the mesh frame — the rod-tip point the engine-drawn fishing line starts from. `None` for
-    /// every model that doesn't author it (exactly one weapon model in the chain does).
+    /// The fishing pole's `$CCH` rod tip, Bevy space, where the line draw `0x61f780` starts.
     pub cch_marker: Option<Vec3>,
-    /// MD20 header `GlobalModelFlags` (`+0x10`). Bits `&3` are the **terrain-conform gate**
-    /// (wow-re `terrain-tilt.md`, §5 byte-verified): `1` = pitch to the ground slope (every
-    /// mount + most quadrupeds), `3` = pitch **and** roll (kodo/crab/spider), `0`/`2` = level.
-    /// The entity layer reads it to conform a standing model to the terrain under it.
+    /// The header's `GlobalModelFlags` (`+0x10`); bits `&3` conform the model to the ground
+    /// (`0x7106c0`): 1 pitch, 3 pitch and roll, else level.
     pub global_flags: u32,
 }
 
-/// One sequence of an M2, as the file table has it — see [`M2Model::sequences`].
+/// One sequence as the file's table has it.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct M2SequenceInfo {
     /// The `AnimationData.dbc` id (`M2Sequence+0x00`).
     pub anim_id: u16,
-    /// The sequence's file slot — the axis the per-sequence material bakes are keyed on
-    /// ([`benilla_formats::ModelAnimation::seq_index`]).
+    /// The sequence's file slot, which the per-sequence bakes key on.
     pub seq_index: usize,
     /// `end − start` on the file's timeline, ms.
     pub duration_ms: u32,
-    /// The band's **start** on the file's global timeline, ms (`M2Sequence+0x04`) — what a
-    /// per-sequence cursor is added to before an absolute-timeline track is sampled. The camera
-    /// tracks are the one consumer: their keys are absolute like every other M2 track's, while a
-    /// pane's play head is a cursor inside the armed band.
+    /// The band's start on the file's timeline, ms (`M2Sequence+0x04`): add it to a cursor before
+    /// sampling an absolute track, such as a camera's.
     pub start_ms: u32,
     /// Loops (flag bit 0 clear); a clamped sequence holds its last frame.
     pub looping: bool,
 }
 
-/// An M2's authored portrait-camera rig in Bevy space (see [`M2Model::portrait_camera`]): eye/target
-/// in model-local yards at scale 1 (the client bakes portraits with root scale reset to 1), the
-/// projection scalars straight from the record.
+/// An authored camera in Bevy space, at model scale 1 as the reference bakes portraits.
 #[derive(Clone, Copy)]
 pub struct PortraitCamera {
     pub eye: Vec3,
     pub target: Vec3,
-    /// Roll about the eye→target axis (radians) — rotates the up vector; `0.0` on every portrait
-    /// camera audited (kept for fidelity, not observed nonzero).
+    /// Roll about the eye-to-target axis, radians.
     pub roll: f32,
-    /// The record's FOV (radians), verbatim — a **diagonal** angle in the client's convention;
-    /// the consumer builds the client's diagonal-FOV projection from it at whichever aspect its
-    /// path uses (`benilla`'s `WowPortraitProjection`) — `1.0` for the round portrait bake, so
-    /// `fovy = fov/√2` (decision 1543), the pane's own rect for a `<PlayerModel>` (1089).
+    /// The record's field of view in radians, a diagonal angle: at aspect 1, `fovy = fov/√2`.
     pub fov: f32,
     pub near: f32,
     pub far: f32,
 }
 
-/// One record of the file's camera table, by **raw index** — see [`M2Model::cameras`].
-///
-/// The rest rig ([`Self::still`]) is Bevy space like every other camera on this asset; the
-/// authored tracks stay raw WoW space behind [`Self::at`], which does the conversion, so there is
-/// no mixed-convention field to misread.
+/// One camera-table record: [`Self::still`] in Bevy space, tracks in WoW space behind [`Self::at`].
 #[derive(Clone)]
 pub struct PaneCamera {
-    /// The record's `type` word — `0` portrait, `1` "characterinfo", `-1` on the fly-bys and the
-    /// six glue scenes. Carried, never selected on: the widget's index is raw.
+    /// The record's `type` (0 portrait, 1 characterinfo, -1 fly-bys and glue); never selected on.
     pub camera_type: i32,
-    /// The rig at rest (bases + each track's first key), Bevy space. The whole answer for every
-    /// model a `<Model>` pane can name — wow-re's census over the composite's 9691 `.m2` found
-    /// every one of those cameras keying a single `(0,0,0)` on all three tracks.
+    /// The rig at rest (bases plus first keys); every camera a `<Model>` pane can name is static.
     pub still: PortraitCamera,
-    /// The authored tracks, raw WoW space, kept only when one of them actually moves — the
-    /// `Cameras\*.m2` fly-bys. Read through [`Self::at`].
+    /// The tracks in WoW space, kept only when one moves (the `Cameras\*.m2` fly-bys).
     tracks: Option<Arc<benilla_formats::M2CameraTracks>>,
 }
 
 impl PaneCamera {
-    /// The rig at absolute file-timeline `ms`, Bevy space — [`Self::still`] for a static camera,
-    /// the cubically sampled tracks for a moving one (`benilla_m2::M2Track::sample_ms`, the
-    /// reference's own four-way `interp` dispatch).
-    ///
-    /// `wow_to_bevy` is linear, so converting the summed `base + track(t)` is the same as
-    /// converting each — which is why the tracks can stay raw behind this one door.
+    /// The rig at file-timeline `ms`, Bevy space, sampled with the reference's four-way `interp`.
+    /// `wow_to_bevy` is linear, so converting `base + track(t)` once is exact.
     pub fn at(&self, ms: u32) -> PortraitCamera {
         let Some(t) = self.tracks.as_deref() else {
             return self.still;
@@ -223,110 +142,54 @@ impl PaneCamera {
     }
 }
 
-/// The **billboard frame** an emitter's bone chain reaches — the host bone's arm, its pivot in raw
-/// WoW model space, and **which bone it is**. See [`ModelEmitter::billboard`] for when it is `Some`
-/// and why the emitter's live origin is then `pivot + camBasis·(def.position − pivot)`.
-///
-/// The bone index is what lets a **rigged** consumer be exactly right rather than approximately:
-/// seating the replacement frame on that bone's own joint puts it at the composed pivot with the
-/// chain above it already folded in, where placing it at `pivot` under the model root silently
-/// assumes every ancestor is at rest.
+/// The billboard bone an emitter's chain reaches; see [`ModelEmitter::billboard`].
 #[derive(Clone, Copy, Debug)]
 pub struct EmitterBillboard {
     pub kind: benilla_formats::BillboardKind,
-    /// The host bone's pivot, **raw WoW model space**.
+    /// The bone's pivot, WoW model space.
     pub pivot: [f32; 3],
-    /// The host bone's index — its seat in the skeleton, for a consumer that has a rig.
+    /// The bone, so a rigged consumer seats the frame on its joint, the chain above folded in.
     pub bone: u16,
 }
 
-/// One particle emitter of an [`M2Model`]: the parsed [`ParticleEmitterDef`] plus its resolved
-/// particle texture as a `Handle<Image>` dependency (loaded through the `mpq://` source, like a
-/// submesh albedo). The app's particle system simulates + renders it at the spawn site.
+/// One particle emitter: its parsed def and its texture dependency.
 #[derive(Clone)]
 pub struct ModelEmitter {
     pub def: ParticleEmitterDef,
     pub texture: Option<Handle<Image>>,
-    /// The host bone's (`def.bone`) pivot, **raw WoW model space** (0130 phase 4). `def.position` is
-    /// model-space; `position − bone_pivot` is the same point in the bone's own frame — the offset
-    /// an emitter riding a live joint composes through the joint's transform. Rest pose is identity
-    /// about the pivot, so the static path (`placement · position`) is the exact special case.
-    /// `[0; 3]` when the bone index is out of range (or the model is boneless).
+    /// The host bone's pivot, WoW model space: `def.position − bone_pivot` is the emitter in the
+    /// bone's frame. Zero for an out-of-range bone.
     pub bone_pivot: [f32; 3],
-    /// The **billboard frame** this emitter rides, when its bone chain reaches a billboard bone
-    /// (`benilla_formats::Skeleton::billboard_host`): that bone's arm and its pivot, **raw WoW
-    /// model space**. The emitter's live origin is then camera-dependent —
-    /// `pivot + camBasis·(def.position − pivot)` — because the reference folds the record position
-    /// through the *replaced* palette matrix (wow-re `part-anchoring-live-bone.md` §1 row 3,
-    /// `billboard-bone-law.md`'s "children multiply onto this").
-    ///
-    /// A rigged host in the WORLD needs nothing from this: its joint palette already carries the
-    /// replacement (`billboard::billboard_joint_palette`) and the emitter rides the joint. Two
-    /// lanes still do: the spawn paths with **no rig** — an equipped item's model
-    /// (helm/shoulders/held), where the whole affected population's chains are otherwise rest-pose
-    /// (corpus-verified: 95 item models / 197 emitters ride a billboard chain, **zero** with an
-    /// animating one — `benilla-extract bbscan`) — and every **booth** bake, rigged or not, whose
-    /// pose deliberately drops the camera arms (`RigPose::without_camera_billboards`: the world
-    /// pass would face them at the *world* camera, which is not the one drawing a booth). `None`
-    /// for the ordinary case.
+    /// The billboard bone this emitter's chain reaches. The reference folds the position through
+    /// the replaced palette matrix (`0x718960` at `0x7190a9`-`0x71910c`, written by `0x715868`),
+    /// so the origin is `pivot + camBasis·(def.position − pivot)`. A rigged world host has it in
+    /// its palette already; unrigged item models and booth bakes, whose pose drops the camera
+    /// arms, need it.
     pub billboard: Option<EmitterBillboard>,
-    /// The **recursion model** (`def.recursion_model`) as a loaded dependency: its own emitters
-    /// become this emitter's CHILD emitters (wow-re `part-child-recursion.md`), wired by the
-    /// app's particle system once the asset resolves. `None` when unauthored.
+    /// The recursion model, whose emitters become this one's children (`0x7b5dd0`).
     pub recursion: Option<Handle<M2Model>>,
-    /// The **geometry model** (`def.geometry_model`) as a loaded dependency: this emitter's
-    /// particles render as 3-D instances of it instead of billboard quads (wow-re
-    /// `part-model-particles.md`). `None` when unauthored.
+    /// The geometry model, drawn per particle in place of a quad (`0x7b4840`).
     pub geometry: Option<Handle<M2Model>>,
-    /// How far the OWNER model's own transparent-pass batches sort from its origin, model-local
-    /// yards — the bound the draw-order rung is sized from (`particles::owner_last_bias`,
-    /// decisions 0719/0721). Computed by [`benilla_formats::m2_owner_reach`], which is where the
-    /// reasoning lives.
+    /// How far the owner model's transparent batches sort from its origin, model-local yards:
+    /// the owner-last draw-order rung's size ([`benilla_formats::m2_owner_reach`]).
     pub owner_reach: f32,
-    /// The OWNER model's authored bound sphere — the water-plane classification input (wow-re
-    /// `water-frame-straddle.md` §6, byte-VERIFIED): the reference dots `world_matrix ×
-    /// (bbox_min+bbox_max)/2` against the plane once per MODEL and every emitter reads that one
-    /// verdict, with the slack `above ⇔ d ≥ −r`, `r = |matrix row 0| × sphere radius`. Centre in
-    /// **Bevy model space** (the same frame the instance transform maps), radius model-local
-    /// yards. `(ZERO, 0)` when the header carries no bounds — the sign test at the anchor.
+    /// The owner model's bound sphere for the water-plane side, Bevy model space: the reference
+    /// classifies once per model, above when `d ≥ −r`, `r = |world matrix row 0| × radius`
+    /// (`0x7083df`-`0x7084dd`). `(ZERO, 0)` without header bounds.
     pub water_bound: (Vec3, f32),
-    /// The OWNER model's **loader-idle file sequence slot**
-    /// ([`crate::ModelAnimations::idle_seq`]) — the sequence every M2 instance is playing when no
-    /// rig has armed anything, and therefore the slot this emitter's per-sequence rate/gate/param
-    /// bakes sample against by default (decision 0936). Baked onto the emitter, not asked of the
-    /// spawn site, because the lanes that need it most are exactly the ones with no rig to ask:
-    /// a content-gated GameObject (`spawn_emitter`'s `EmitClock::Host` whose player armed nothing)
-    /// and an unrigged placed doodad (`EmitClock::Pinned`). `0` for a model with no sequences —
-    /// the same degrade as before, now stated once instead of falling out of an `unwrap_or`.
+    /// The owner's loader-idle file slot ([`crate::ModelAnimations::idle_seq`]), baked here for
+    /// the lanes with no rig to ask; 0 when the model builds no animations.
     pub idle_seq: usize,
 }
 
-/// Whether looping `anim` would look like anything other than the **static mesh** — the doodad
-/// content gate (decision 0130, premise corrected by 0637).
-///
-/// The original gate asked "does some track have >1 key", reasoning that a constant pose renders
-/// identically to the un-rigged mesh. That premise is false: the static mesh is the **bind** pose,
-/// and a constant clip only equals it when the constant *is* rest. `DuelingFlag.m2` is the
-/// counter-example that cost us the bug — its Stand band brackets to a constant bone-0 translation
-/// of `−9.124` (the flag planted in the ground) while its bind pose is 9 yards up in the air, so a
-/// "constant ⇒ skip the rig" gate renders it floating.
-///
-/// So: a track that MOVES qualifies, and so does a constant sitting away from rest — translation
-/// ≠ 0 (the M2 translation track is a delta on the pivot offset), rotation ≠ identity, scale ≠ 1.
-/// Genuinely rest-posed idles — the ~90% of placed doodads decision 0130 measured — still take the
-/// static path, so that optimization survives intact.
-///
-/// The predicate itself is `ModelAnimation::is_rest_pose`, beside the parse, so
-/// `benilla-extract idleslotscan`'s corpus census of this gate's reach can't drift from the gate
-/// (decision 0936). What it decides is **whether to build a rig**, and nothing else — the sequence
-/// the instance is playing is [`ModelAnimations::idle_seq`], which has an answer either way.
+/// The doodad content gate: whether looping `anim` differs from the static mesh, the bind pose.
+/// A constant pose away from rest counts: `DuelingFlag.m2`'s Stand holds the flag 9 yd below its
+/// bind pose. It decides the rig only; the playing sequence is [`ModelAnimations::idle_seq`].
 fn idle_pose_differs(anim: &benilla_formats::ModelAnimation) -> bool {
     !anim.is_rest_pose()
 }
 
-/// A model reference inside an M2 record (`.mdx`/`.mdl`, mixed case, backslashes) → its
-/// `mpq://…m2` load URL — the same extension remap the client's loader does (the physical
-/// archive file is `.m2`).
+/// A model path inside an M2 record (`.mdx`/`.mdl`, backslashes) as its `mpq://….m2` URL.
 fn m2_dep_url(raw: &str) -> String {
     let p = raw.to_ascii_lowercase().replace('\\', "/");
     let stem = p
@@ -337,32 +200,20 @@ fn m2_dep_url(raw: &str) -> String {
     format!("mpq://{stem}.m2")
 }
 
-/// One ribbon emitter of an [`M2Model`]: the parsed [`benilla_formats::RibbonEmitterDef`] plus its
-/// resolved trail texture and — like [`ModelEmitter::bone_pivot`] — the host bone's rest pivot, so
-/// the spawn site can ride the bone's joint with `position − pivot` in the joint frame (the
-/// reference transforms the bone-local position by the live bone matrix each frame, `0x718960`).
+/// One ribbon emitter, riding its bone like [`ModelEmitter::bone_pivot`] (`0x718960`).
 #[derive(Clone)]
 pub struct ModelRibbon {
     pub def: benilla_formats::RibbonEmitterDef,
     pub texture: Option<Handle<Image>>,
     pub bone_pivot: [f32; 3],
-    /// The owner model's reach — same field, same bound, same reason as
-    /// [`ModelEmitter::owner_reach`]. A trail is one of its model's emitters and takes the same
-    /// owner-last draw-order rung: measured on the wisp (14 blend batches, 3 streamers), its
-    /// trails otherwise interleave with its own body, 6 batches deep, and which batches are over
-    /// which streamer *changes frame to frame* as they whip (decision 0721).
+    /// As [`ModelEmitter::owner_reach`]: a trail takes its model's owner-last rung too.
     pub owner_reach: f32,
-    /// The owner model's bound sphere for the water-plane side — same field, same law as
-    /// [`ModelEmitter::water_bound`]: the ribbon leg reads the MODEL's side-A boolean verbatim
-    /// (wow-re `water-frame-straddle.md` §6 — `cmp [ebp-0x24],0` at `0x7081f1`), slack included.
+    /// As [`ModelEmitter::water_bound`]; the ribbon leg reads the model's verdict too (`0x7081f1`).
     pub water_bound: (Vec3, f32),
 }
 
-/// One M2 light block of an [`M2Model`]: the raw [`M2Light`] record plus — like
-/// [`ModelEmitter::bone_pivot`] — its host bone's rest pivot, so a light on an ANIMATING model can
-/// ride that bone's joint with `position − pivot` in the joint frame. The reference does exactly
-/// this every frame (`0x718960` transforms the def position by the live bone matrix before
-/// registering the light), which is how a torch's glow tracks the hand that swings it.
+/// One M2 light and its bone's rest pivot: the reference moves the light with the live bone each
+/// frame (`0x718960`), so a torch's glow follows the hand.
 #[derive(Clone, Copy)]
 pub struct ModelLight {
     pub def: M2Light,
@@ -441,16 +292,12 @@ impl AssetLoader for M2ModelLoader {
         reader.read_to_end(&mut bytes).await?;
         let to_io = |e: anyhow::Error| std::io::Error::other(format!("{e:#}"));
 
-        // `dir` only feeds creature skin-variation resolution, which is inert here (we pass no skins —
-        // skins are applied at the spawn site from CreatureDisplayInfo), so an empty dir is correct.
+        // Skins fill at the spawn site, so no skin directory or list is passed.
         let subs = parse_m2_render_submeshes(&bytes, "", &[]).map_err(to_io)?;
         let bounds = parse_m2_bounds(&bytes).ok();
-        // The owner-last draw-order bound, once for the whole model: every effect this model
-        // authors (quad emitters, ribbon trails, model-particle instances) takes the rung it sizes,
-        // because the reference draws them all in the one post-batch bracket.
+        // One owner bound for every effect: the reference draws them all after the batches.
         let owner_reach = benilla_formats::m2_owner_reach(&subs);
-        // The water-plane classification sphere, once for the whole model — the header AABB's
-        // midpoint (Bevy model frame) + the header sphere radius. See [`ModelEmitter::water_bound`].
+        // The water-plane sphere: the header box's midpoint and the header sphere's radius.
         let water_bound = bounds.as_ref().map_or((Vec3::ZERO, 0.0), |b| {
             (
                 wow_to_bevy([
@@ -461,25 +308,15 @@ impl AssetLoader for M2ModelLoader {
                 b.sphere_radius,
             )
         });
-        // The collision hull (collide-iff-hull): keep only a non-empty mesh so the spawn site can skip
-        // hull-less props cheaply.
+        // An empty hull is no hull: the model does not collide.
         let collision = parse_m2_collision_hull(&bytes)
             .ok()
             .filter(|c| !c.is_empty());
 
         let mut submeshes = Vec::with_capacity(subs.len());
         for sub in subs {
-            // No meshes built here (decision 0834): the geometry ships on the submesh and the app
-            // builds the render form paced — the static mesh on demand, the skinned twin only for
-            // the lanes that rig (which also retires the old always-built, mostly-unused twin).
-            //
-            // Embedded texture → an mpq:// dependency (WorldArt, the loader default). Lowercase the
-            // path: Bevy's loader lookup is case-sensitive, and these tables carry uppercase `.BLP`
-            // (the `BlpImageLoader` registers `blp`), so an uppercase extension silently falls back to
-            // type-based resolution — which is ambiguous with Bevy's built-in image loader and spams a
-            // "Multiple AssetLoaders found" warning per texture. Lowercasing also dedupes case variants.
-            // The URL carries the batch's authored sampler address mode, because two modes of one
-            // `.blp` are two different `Image` uploads (decision 0763 — `crate::texture_url`).
+            // The URL is lowercased, since Bevy matches the `blp` extension case-sensitively, and
+            // carries the wrap modes, since two modes of one texture are two uploads.
             let texture = sub
                 .texture
                 .as_deref()
@@ -514,19 +351,11 @@ impl AssetLoader for M2ModelLoader {
                 geometry: std::sync::Arc::new(sub),
             });
         }
-        // M2 light blocks (raw — wow-m2's light parse reads the wrong vanilla record shape). The spawn
-        // site filters to casting point lights ([`M2Light::casts`]). Empty for nearly all models.
-        // The bone-pivot bake is below, once the skeleton is parsed.
+        // The spawn site keeps the casting point lights (`M2Light::casts`).
         let light_defs = parse_m2_lights(&bytes);
 
-        // The rest skeleton (decision 0019): bake the raw bone tree to Bevy-space joints + the matching
-        // inverse bind poses. A boneless model yields an empty skeleton + an empty bindpose set (the
-        // skinned mesh then carries no joint attributes, so it never takes the SKINNED path).
         let skeleton_raw = parse_m2_skeleton(&bytes).unwrap_or_default();
 
-        // Particle emitters: resolve each emitter's texture to an `mpq://` image dependency (same
-        // lowercase normalisation as submesh albedos), and bake its host bone's pivot so the spawn
-        // site can ride a live joint (see [`ModelEmitter::bone_pivot`]). Absent on most models.
         let mut emitters: Vec<ModelEmitter> = parse_m2_particle_emitters(&bytes)
             .unwrap_or_default()
             .into_iter()
@@ -541,8 +370,6 @@ impl AssetLoader for M2ModelLoader {
                     .bones
                     .get(def.bone as usize)
                     .map_or([0.0; 3], |b| b.pivot);
-                // The recursion/geometry models load as ordinary mpq:// M2 dependencies —
-                // children wiring and model-particle instancing happen app-side on resolve.
                 let recursion = def
                     .recursion_model
                     .as_deref()
@@ -551,7 +378,6 @@ impl AssetLoader for M2ModelLoader {
                     .geometry_model
                     .as_deref()
                     .map(|p| ctx.load::<M2Model>(m2_dep_url(p)));
-                // The billboard frame the emitter's bone chain inherits, if any (see the field).
                 let billboard = skeleton_raw.billboard_host(def.bone).and_then(|h| {
                     let b = skeleton_raw.bones.get(h)?;
                     Some(EmitterBillboard {
@@ -574,8 +400,6 @@ impl AssetLoader for M2ModelLoader {
             })
             .collect();
 
-        // Ribbon emitters (trails): same texture resolution, bone-pivot bake and owner-reach bake
-        // as the particles — a trail is one of the model's emitters and draws under the same law.
         let ribbons: Vec<ModelRibbon> = benilla_formats::parse_m2_ribbon_emitters(&bytes)
             .unwrap_or_default()
             .into_iter()
@@ -739,25 +563,17 @@ impl AssetLoader for M2ModelLoader {
             SkinnedMeshInverseBindposes::from(inverse_bindposes),
         );
 
-        // The attachment-point table (decision 0072 — held items): the same bind-pose pivots
-        // `build_skeleton` used above, so a held item's offset is exactly consistent with the joint
-        // it's spawned under. Empty for a boneless/attachment-less model.
+        // Attachments, markers and clip events all take the pivots the joints were built from.
         let attachments = build_attachments(
             &parse_m2_attachments(&bytes).unwrap_or_default(),
             &skeleton_pivots(&skeleton_raw),
         );
-        // The event-marker table, same bake (the missile-launch $CSL/$CSR/$CST/$BWR points).
         let markers = crate::model::build_markers(
             &benilla_formats::parse_m2_event_markers(&bytes).unwrap_or_default(),
             &skeleton_pivots(&skeleton_raw),
         );
-        // …and the same pivots again for the per-clip event keys below ([`crate::ClipEvent`]),
-        // so a fired key's point is bake-consistent with the joint it composes through.
         let pivots = skeleton_pivots(&skeleton_raw);
 
-        // The animations (decision 0019): build each sequence's clip into one shared `AnimationGraph`
-        // (the bench scrubs them; gameplay plays Stand). All as labeled sub-assets. `None` unless at
-        // least one sequence produced an animated clip.
         let sequences = parse_m2_animations(&bytes);
         let first_seq_span = sequences.first().map(|a| a.duration).filter(|d| *d > 0.0);
         let sequence_infos: Vec<M2SequenceInfo> = sequences
@@ -773,19 +589,13 @@ impl AssetLoader for M2ModelLoader {
         let animations = {
             let mut graph = AnimationGraph::new();
             let root = graph.root;
-            // The direct pose evaluator's bake (decision 0712) — filled beside every graph
-            // mutation below so the table mirrors the graph by construction: `bone_masks` beside
-            // each `add_target_to_mask_group`, `set_node` beside each `add_clip*`.
+            // The pose bake mirrors the graph: update it beside every mask group and `add_clip*`.
             let mut pose = crate::model::PoseSource {
                 bone_masks: vec![0u64; skeleton_raw.bones.len()],
                 ..Default::default()
             };
-            // Per-arm mask groups for the client's per-slot one-shots (the draw/stow plays each
-            // hand's ceremony on its own arm subtree, over the gait). Each arm's subtree root is the
-            // **shoulder-keybone ancestor of the hand attachment's bone** (attachment id 1 = right
-            // hand, 2 = left; keybones 2/3 = the shoulders — data-driven, no left/right guessing).
-            // Every joint *outside* an arm joins that arm's mask group, so a node masked with group
-            // 0 (or 1) animates only the right (or left) arm.
+            // Groups 0 and 1 hold every joint outside the right and the left arm, so a node masked
+            // with one animates only that arm.
             let arm_roots = arm_subtree_roots(&skeleton_raw, &attachments);
             if let Some((right_root, left_root)) = arm_roots {
                 for i in 0..skeleton_raw.bones.len() {
@@ -800,9 +610,7 @@ impl AssetLoader for M2ModelLoader {
                     }
                 }
             }
-            // The upper-body one-shot mask group (decision 0087): group 2 collects every joint
-            // *outside* the SpineLow subtree (the legs + pelvis), so a clip masked with it animates
-            // only the upper body — the general form of the per-arm ceremony above, one subtree wider.
+            // Group 2 holds every joint outside the upper body: the legs and the pelvis.
             let upper_root = upper_subtree_root(&skeleton_raw);
             if let Some(upper_root) = upper_root {
                 for i in 0..skeleton_raw.bones.len() {
@@ -812,10 +620,8 @@ impl AssetLoader for M2ModelLoader {
                     }
                 }
             }
-            // Per-hand **finger** mask groups (3 = right hand, 4 = left) for the weapon grip: a clip
-            // masked with group 3 (or 4) animates only that hand's finger key-bone subtrees, so the
-            // `HandsClosed` pose curls the fingers while the arm keeps its gait (wow-re
-            // `hand-grip-mechanism.md`). Empty per hand for a model with no finger key-bones (beasts).
+            // Groups 3 and 4 hold every joint outside the right and the left fingers, for the
+            // weapon grip (`CloseHand`, `0x479660`).
             let finger_roots = finger_subtree_roots(&skeleton_raw);
             for i in 0..skeleton_raw.bones.len() {
                 let target = bone_target_id(i as u16);
@@ -836,40 +642,24 @@ impl AssetLoader for M2ModelLoader {
                     pose.bone_masks[i] |= 1 << 4;
                 }
             }
-            // The model's baked PlayableAnimationLookup (decision 0082): parsed straight off the M2
-            // header alongside the sequences above, so a model lacking a requested clip can resolve
-            // to its own baked substitute at play time (`ModelAnimations::resolve`) instead of the
-            // creature driver silently doing nothing. Read BEFORE the clip walk because the
-            // loader-idle seed below resolves through it.
+            // Read before the clip walk: the loader-idle seed resolves through it.
             let playable_animation_lookup =
                 parse_m2_playable_animation_lookup(&bytes).unwrap_or_default();
-            // The model's own "do I author id X" table (the reference's `0x711960`) — the
-            // GameObject arm's missing-sequence remap branches on it (`ModelAnimations::owns`).
             let animation_lookup =
                 benilla_formats::parse_m2_animation_lookup(&bytes).unwrap_or_default();
             let mut clips = Vec::new();
-            // The loader-idle seed (decision 0637, wow-re `gameobject-anim-arm.md` §1 — the
-            // corrected `0x71019b` read): the loader arms **animation id 0 ("Stand")** resolved
-            // through the model's own `playableAnimationLookup`, NOT the file-order-first
-            // sequence. For the overwhelming majority of models those coincide, which is why the
-            // old file-order read survived; they diverge exactly on models whose first sequence is
-            // a Spawn — `DuelingFlag.m2` is Spawn(145)/Stand(0)/Despawn(157), and looping its
-            // Spawn band left the flag hanging 9 yards in the air on a 3.3 s cycle.
+            // The loader-idle seed (`0x71019b`): id 0 via the playable lookup, not file slot 0.
             let idle_id = playable_animation_lookup
                 .first()
                 .map_or(0, |p: &benilla_formats::PlayableAnim| p.resolved_id);
             let mut first_seq = None;
             for (i, anim) in sequences.iter().enumerate() {
-                // EVERY sequence becomes a clip — the clip carries the instance's sequence CLOCK,
-                // not just a bone pose (decision 0941, [`build_animation_clip`]). `poses_bones`
-                // separates the two meanings: the clock is free, the rig is not.
+                // Every sequence becomes a clip, since the clip is the sequence clock;
+                // `poses_bones` says whether it also needs a rig.
                 {
                     let (clip, pose_clip, poses_bones) = build_animation_clip(anim, &skeleton);
-                    // `first_seq` stays the RENDERING question — "is this seed worth a skin +
-                    // player" (0130's content gate, and decision 0936's split). The identity
-                    // question, "which sequence does the loader arm", is
-                    // [`ModelAnimations::idle_seq`]/`idle_clip`, which asks the same selection
-                    // without the gate.
+                    // `first_seq` asks whether the seed needs a rig; `ModelAnimations::idle_seq`
+                    // makes the same selection without that gate.
                     if first_seq.is_none() && anim.anim_id == idle_id && idle_pose_differs(anim) {
                         first_seq = Some(clips.len());
                     }
@@ -878,7 +668,7 @@ impl AssetLoader for M2ModelLoader {
                     let clip = ctx.add_labeled_asset(format!("clip{i}"), clip);
                     let node = graph.add_clip(clip.clone(), 1.0, root);
                     pose.set_node(node, pose_idx, 0);
-                    // The sheath family gets per-arm masked variants ([`AnimClip::arm_nodes`]).
+                    // The sheath family (89/90) gets per-arm masked nodes.
                     let arm_nodes =
                         (matches!(anim.anim_id, 89 | 90) && arm_roots.is_some()).then(|| {
                             let nodes = (
@@ -889,10 +679,8 @@ impl AssetLoader for M2ModelLoader {
                             pose.set_node(nodes.1, pose_idx, 1 << 1);
                             nodes
                         });
-                    // The upper-body masked variant ([`AnimClip::upper_node`]): the masked destination
-                    // for a one-shot routed over a live base (swing/emote — the route is chosen per play
-                    // in `creature_anim`). Built for every clip when the model has a split key-bone, so
-                    // any one-shot id can take the masked route; `None` on the −1-sentinel models.
+                    // With an upper-body root, every clip gets an upper-body node, so a one-shot
+                    // can play over a live base.
                     let upper_node = upper_root.map(|_| {
                         let n = graph.add_clip_with_mask(clip.clone(), 1 << 2, 1.0, root);
                         pose.set_node(n, pose_idx, 1 << 2);
@@ -912,10 +700,8 @@ impl AssetLoader for M2ModelLoader {
                         // The axis mapping flips signs, so min/max are re-derived componentwise.
                         bounds_min: wow_to_bevy(anim.bounds_min).min(wow_to_bevy(anim.bounds_max)),
                         bounds_max: wow_to_bevy(anim.bounds_min).max(wow_to_bevy(anim.bounds_max)),
-                        // The kernel's own quantity, baked (see [`ClipEvent`]): the bone-local
-                        // offset for a rigged model and the model-space point for one whose bone
-                        // chain never moves — both from the record's OWN bone, never a by-4CC
-                        // re-find, because a model may author the tag more than once.
+                        // `offset` and `point` both use the record's own bone, never a by-4CC
+                        // lookup: a model may author a tag more than once.
                         events: anim
                             .events
                             .iter()
@@ -938,16 +724,11 @@ impl AssetLoader for M2ModelLoader {
                     });
                 }
             }
-            // The per-hand weapon-grip nodes ([`ModelAnimations::hand_close`]): a purpose-built grip clip
-            // — each finger key-bone posed at its **clamped** `HandsClosed` value — masked to one hand's
-            // finger subtrees (group 3 = right, 4 = left). Built separately from the sequence clips above
-            // because the general in-band read drops the weapon-hand fingers (keyed off the HandsClosed
-            // frame); [`hand_grip_finger_poses`] clamps them, scoped to the grip (wow-re
-            // `hand-grip-mechanism.md`). `None` per hand for a model with no finger key-bones / no grip pose.
+            // The grip is its own clip of clamped `HandsClosed` finger poses: the sequence read
+            // drops fingers keyed off that frame, which `hand_grip_finger_poses` clamps.
             let mut hand_close: [Option<bevy::animation::graph::AnimationNodeIndex>; 2] =
                 [None, None];
-            // Every bone in a finger subtree — the key-bone AND its child segments (the fingertip joints),
-            // so the whole finger curls, not just its base (HandsClosed keys the tips too, ~51° vs ~30°).
+            // Every bone of each finger subtree, tips included, since `HandsClosed` keys them too.
             let finger_bones: Vec<u16> = (0..skeleton_raw.bones.len())
                 .filter(|&i| {
                     finger_roots
@@ -974,22 +755,11 @@ impl AssetLoader for M2ModelLoader {
                     hand_close[1] = Some(n);
                 }
             }
-            // Global-sequence channels alone are enough to carry `ModelAnimations`: a model whose
-            // sequences produced no clips can still pulse/flicker on its free-running loops (the
-            // doodad `GlobalSeqOnly` tier, decision 0130) — dropping them because `clips` came up
-            // empty would silently freeze it.
+            // Global-sequence channels alone earn `ModelAnimations` (the `GlobalSeqOnly` tier).
             let global_bones =
                 build_global_bones(&parse_m2_global_sequence_bones(&bytes), &skeleton);
-            // The gate is "does ANYTHING in this model vary with the sequence clock" — and its
-            // consumer list was incomplete (decision 0941). A bone-posing clip and a global
-            // sequence were counted; the **per-sequence samplers** were not: the emitters'
-            // rate/enable/params tracks, a ribbon's, and the material alpha/colour/UV loops all
-            // resolve through the instance's playing sequence. 807 corpus models animate ONLY
-            // through those, and denying them `ModelAnimations` denied them the clock itself —
-            // no player, no slot, no time — so every one of those tracks read file slot 0 at
-            // t=0 for ever. Models with none of the three keep the static path: the optimization
-            // decision 0130 measured (~90% of placed doodads) is untouched, and 6342 boneless
-            // models with nothing to sample stay out of the animation lane entirely.
+            // A model animates if a bone poses, a global sequence runs, or something samples the
+            // sequence clock: emitters, ribbons, or a material's alpha, colour or UV loop.
             let samples_sequence = !emitters.is_empty()
                 || !ribbons.is_empty()
                 || submeshes
@@ -1013,19 +783,13 @@ impl AssetLoader for M2ModelLoader {
             })
         };
 
-        // Stamp every emitter with the model's loader-idle slot (decision 0936) — the sequence a
-        // rig-less instance is playing, and so the slot its rate/gate/param bakes sample by
-        // default. Done here rather than in the map above because the selection needs the built
-        // clips (their `seq_index` + the `playableAnimationLookup` resolve), and only `None` when
-        // the model builds no clip at all — nothing to name, so the historical slot 0 stands.
+        // Stamped only now: the idle selection needs the built clips.
         let idle_seq = animations.as_ref().and_then(ModelAnimations::idle_seq);
         for e in &mut emitters {
             e.idle_seq = idle_seq.unwrap_or(0);
         }
 
-        // The authored portrait camera (raw WoW model space → Bevy, same pure rotation the meshes
-        // bake through, so eye/target land in exactly the submeshes' frame) — and the camera
-        // table's first record, the glue screens' `SetCamera(0)` rig.
+        // Cameras take the meshes' WoW-to-Bevy rotation, so eye and target share their frame.
         let to_bevy = |c: benilla_formats::M2PortraitCamera| PortraitCamera {
             eye: wow_to_bevy(c.position),
             target: wow_to_bevy(c.target),
@@ -1037,7 +801,6 @@ impl AssetLoader for M2ModelLoader {
         let portrait_camera = parse_m2_portrait_camera(&bytes).map(to_bevy);
         let camera0 = benilla_formats::parse_m2_camera(&bytes, 0).map(to_bevy);
         let pane_camera = benilla_formats::parse_m2_camera(&bytes, 1).map(to_bevy);
-        // The whole table, raw index — the `<Model>` widget's `SetCamera(n)` space (2027).
         let cameras: Vec<PaneCamera> = benilla_formats::parse_m2_pane_cameras(&bytes)
             .into_iter()
             .map(|c| PaneCamera {
@@ -1047,7 +810,6 @@ impl AssetLoader for M2ModelLoader {
             })
             .collect();
 
-        // The bowstring anchors (bows only): raw WoW positions → Bevy, the meshes' frame.
         let string_anchors = benilla_formats::parse_m2_string_anchors(&bytes).map(|a| {
             [
                 (a.top.0, wow_to_bevy(a.top.1)),
@@ -1055,11 +817,9 @@ impl AssetLoader for M2ModelLoader {
             ]
         });
 
-        // The fishing line's near anchor (mesh frame, like the bowstring anchors).
         let cch_marker = benilla_formats::parse_m2_cch_marker(&bytes).map(|(_, p)| wow_to_bevy(p));
 
-        // The header GlobalModelFlags word sits at a fixed offset (MD20 magic @0, +0x10) — a
-        // bare scalar the sectioned parsers never touch.
+        // `GlobalModelFlags` sits at MD20 `+0x10`, outside every sectioned parser.
         let global_flags = bytes
             .get(0x10..0x14)
             .map_or(0, |b| u32::from_le_bytes(b.try_into().unwrap()));
diff --git a/crates/benilla-assets/src/materials.rs b/crates/benilla-assets/src/materials.rs
index a34085d1..18aa1682 100644
--- a/crates/benilla-assets/src/materials.rs
+++ b/crates/benilla-assets/src/materials.rs
@@ -1,29 +1,8 @@
-//! **The render materials** — the four `ExtendedMaterial`s a WoW 1.12.1 world is drawn with
-//! (terrain splat, M2/WMO model, WDL far band, liquid surface) and the WGSL each one binds.
+//! The render materials: the four `ExtendedMaterial`s the world is drawn with (terrain splat,
+//! M2/WMO model, WDL far band, liquid surface) and the WGSL each one binds.
 //!
-//! They live *below* the renderer, in the crate that turns WoW files into GPU resources, because
-//! that is what they are: the thing an `.m2` submesh or an `.adt` chunk BECOMES. Decision 1164 —
-//! the material type is the value type of the shared dedup cache (`WorldAssets::model_materials`),
-//! and 26 gameplay files name `WowModelMaterial` for spell effects, equipment and portraits with
-//! no terrain streamer anywhere in sight. Verified before the move: this file names nothing from
-//! the client at all — its whole import surface is `bevy::*` — so it is a leaf that belongs here,
-//! not a piece of the renderer dragged down with the caches.
-//!
-//! **The WGSL is embedded, not served.** `shaders/*.wgsl` next to this file are compiled in via
-//! [`register_shaders`] and addressed as `embedded://benilla_assets/shaders/…`. A relative
-//! `"shaders/x.wgsl"` would resolve against whatever `AssetPlugin::file_path` the *host binary*
-//! happened to set, so a second program standing on this crate would get a material that silently
-//! renders nothing — the same trap `boot.rs` already documents for the capture harness. Embedding
-//! makes the crate answer for its own shaders.
-//!
-//! Phase 6 terrain splat material: an [`ExtendedMaterial`] over `StandardMaterial` that blends up
-//! to 4 tiled layer textures by a packed alpha map, keeping PBR lighting/shadows/fog.
-//!
-//! **Per-tile, not per-chunk.** A whole ADT tile shares ONE material: its ground textures are stacked
-//! into a `layer_array` (`texture_2d_array`) and its per-chunk alpha maps into an `alpha_array`. Each
-//! merged-mesh vertex carries its chunk's 4 layer indices (vertex `COLOR`) + alpha-layer index
-//! (`UV1.x`), so all 256 chunks draw from one material — letting Bevy batch the tile into a single
-//! draw instead of 256. (The old design bound 4 textures + an alpha map per chunk → a material each.)
+//! The WGSL is embedded (`embedded://benilla_assets/shaders/…`), not served: a relative path would
+//! resolve against the host binary's `AssetPlugin::file_path` and render nothing elsewhere.
 
 use bevy::image::Image;
 use bevy::mesh::MeshVertexBufferLayoutRef;
@@ -54,84 +33,46 @@ pub fn register_shaders(app: &mut App) {
     load_shader_library!(app, "shaders/enhanced_water.wgsl");
 }
 
-/// The WDL far-band shader's source, for the law tests that live beside the renderer rather than
-/// beside the material (`wdl.rs`). Exported instead of letting a sibling crate `include_str!` its
-/// way across the workspace by relative path.
+/// The WDL far-band shader's source, for the tests that live beside the renderer (`wdl.rs`).
 pub const WDL_WGSL: &str = include_str!("shaders/wdl.wgsl");
 
-/// Alpha-test reference for `Blend_AlphaKey` (M2 blend mode 1) materials — the value below which a
-/// fragment is discarded (`D3DCMP_GREATEREQUAL`). Per wowdev.wiki M2/Rendering this is **version
-/// dependent**: `224/255 ≈ 0.878` on **≤ WotLK** (our target is 1.12.1 build 5875), vs `128/255 ≈
-/// 0.5` on Cata+. We initially hardcoded the Cata value (0.5), which left foliage too dense and a
-/// white fringe on cutout edges. The spec multiplies this by the element's animated alpha (1.0 for
-/// static doodads), so the bare constant is correct until we add doodad alpha fades.
-/// Source: <https://wowdev.wiki/M2/Rendering> § Alpha Testing.
+/// Alpha-test reference for blend mode 1 (`Blend_AlphaKey`): 224 in the reference's
+/// per-blend-mode table at `0x85ad20`, `{0, 224, 1, 1, 1, 1, 1, 0, 0, 0, 0}`. Must stay in sync
+/// with `VANILLA_ALPHA_KEY` in `shaders/wow_model.wgsl`.
 pub const VANILLA_ALPHA_KEY_REF: f32 = 224.0 / 255.0;
 
-/// `StandardMaterial` + our per-tile layer-blend extension.
+/// `StandardMaterial` plus the per-tile layer-blend extension.
 pub type TerrainMaterial = ExtendedMaterial<StandardMaterial, TerrainExtension>;
 
-/// World models (doodads/WMO/creatures/GameObjects) lit by the **same WoW lighting as terrain** —
-/// `tex × saturate(ambient + diffuse·N·L) × scale` in gamma space — instead of PBR. Reuses
-/// `StandardMaterial` for the texture/alpha/cull (set in `model_material`); the extension just
-/// carries the shared light. Keeping models and terrain on one lighting model is what makes the
-/// scene coherent (PBR couldn't clamp, so it tinted models orange).
+/// World models (doodads, WMOs, creatures, GameObjects) lit in gamma space like terrain, not by
+/// PBR; `StandardMaterial` carries only the texture, alpha mode and culling.
 pub type WowModelMaterial = ExtendedMaterial<StandardMaterial, WowModelExt>;
 
-/// Pipeline-specialization key for [`WowModelExt`] — picks the two distance-fade pipeline tweaks Bevy
-/// has no built-in `AlphaMode` for. Both make the fade **OPACITY** with **depth-write ON**, matching the
-/// reference (`RECONCILE-fade-render-state.md` / `-clutter-fade-render-state.md`):
-/// - `fade` (`model_flags.y`) = the **M2-doodad** fade blend twin: `AlphaMode::Blend` (transparent pass,
-///   depth-write normally OFF) → `specialize` forces depth-write back ON so a fading haystack's near
-///   cross-quads occlude its far ones. Silhouette stable for an AlphaKey source (the shader re-applies
-///   the 224/255 cutout via `clutter_fade.z` bit 10 — an Opaque source never alpha-tests; 0842).
-/// - `clutter` (`clutter_fade.w`) = ground clutter: an `AlphaMode::Mask` (alpha-mask pass, depth-write
-///   already ON) that the reference also **blends** (prog 201: `SRC_ALPHA/ONE_MINUS_SRC_ALPHA`) so the
-///   ~70 yd ramp fades opacity. `specialize` forces that over-blend on in place; the 128/255 discard +
-///   `tex × ramp` output alpha are already done in the shader.
+/// Pipeline-specialization key for [`WowModelExt`]: the depth and blend states Bevy's `AlphaMode`
+/// cannot express. `fade` (`model_flags.y`) is the M2 doodad fade twin and `clutter`
+/// (`clutter_fade.w`) ground clutter; both fade opacity with depth-write on, as the reference does.
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 pub struct WowModelKey {
     fade: bool,
     clutter: bool,
-    /// Additive glow card (`model_flags.w == 2.0`) — `specialize` forces a `SrcAlpha`-additive blend
-    /// state (`rgb·α + dst`) so the glow texture's radial alpha shapes a soft halo. See `model_render`.
+    /// Additive glow card (`clutter_fade.z` bit 2).
     additive: bool,
-    /// M2 render flag 0x10 — disable depth WRITE for this batch (packed into `clutter_fade.z` bit 0 by
-    /// `model_material`; `clutter_fade.z` is unread by the shader, so it carries this Rust-side marker).
+    /// M2 render flag 0x10, no depth write (`clutter_fade.z` bit 0).
     no_depth_write: bool,
-    /// M2 render flag 0x08 — disable depth TEST (packed into `clutter_fade.z` bit 1).
+    /// M2 render flag 0x08, no depth test (`clutter_fade.z` bit 1).
     no_depth_test: bool,
-    /// The MULTIPLY blends (clutter_fade.z bits 7/8; decision 0528) — `specialize` swaps the blend
-    /// state to the byte-verified factors: Mod `DST_COLOR/ZERO`, Mod2x `DST_COLOR/SRC_COLOR`
-    /// (wow-re `m2-depth-blend-state`). Exact on the 0161 gamma lane — the framebuffer holds gamma
-    /// values, so the hardware multiply IS the reference's byte multiply.
+    /// The multiply blends, Mod and Mod2x (`clutter_fade.z` bits 7/8).
     modulate: bool,
     modulate2x: bool,
-    /// Depth-prime twin (`clutter_fade.z` bit 9 — `model_render::zfill_material`, the reference's
-    /// `M2UseZFill` clone command, wow-re `m2-blend-promotion-zfill.md` §4): `specialize` masks the
-    /// colour writes off, turns blend off, and forces depth-write ON.
+    /// The depth-prime twin (`clutter_fade.z` bit 9, `model_render::zfill_material`).
     zfill: bool,
-    /// Far side of the water plane (`clutter_fade.z` bit 11 — `model_render`'s far twin, the
-    /// water-plane interleave's mesh lane): the material's huge negative SORT bias must stay
-    /// sort-only, so `specialize` zeroes the rasterizer `DepthBiasState` constant the base
-    /// `StandardMaterial` derived from the same field (at −4e4 that constant is a ~0.5% relative
-    /// depth pull — enough to clip a blade's coplanar sheen/glow layers behind the blade itself).
+    /// Far side of the water plane (`clutter_fade.z` bit 11).
     far_side: bool,
-    /// The **WMO-skybox lane** (`clutter_fade.z` bit 13 — `model_render::SKY_DEPTH_MARKER`): the
-    /// building-owned painted sky, drawn as the ordinary M2 it is. `specialize` compiles the
-    /// `WOW_SKY_DEPTH` def into BOTH stages: the vertex pins clip z to 0 — reverse-Z far, the sky
-    /// depth law every other sky shader obeys (`benilla_world::sky_order`) — and the fragment
-    /// writes no depth at all (it did until 2016, at the cost of the pipeline's early-Z). It is a
-    /// key axis because the pin is one model's: every other draw on this lane keeps its real
-    /// depth. Like [`Self::far_side`] it also zeroes the rasterizer bias constant: the lane's rung
-    /// is a SORT rung (`sky_order::WMO_SKYBOX_BIAS`, ~−6e4), and the pinned depth is a constant
-    /// the rasterizer must not be perturbing behind the shader's back.
+    /// The WMO-skybox lane (`clutter_fade.z` bit 13, `model_render::SKY_DEPTH_MARKER`), a key axis
+    /// because only this model's depth is pinned.
     sky_depth: bool,
-    // NB: the WMO authored batch order is deliberately NOT a key axis. It used to be (a
-    // per-batch-index `DepthBiasState` constant), which made every batch index its own pipeline —
-    // the city first-sight compile stall (decision 0837). The coplanar-layering nudge now rides
-    // `sun_scale.y` into `wow_model.wgsl`'s vertex stage as uniform data; `model_render::MatKey`
-    // still dedups materials per order, so per-batch identity is intact.
+    // The WMO batch order is deliberately not a key axis (a pipeline per batch index stalls a
+    // city's first sight): the file-order layering (`0x6b4f10`/`0x6b5190`) rides `sun_scale.y`.
 }
 
 impl From<&WowModelExt> for WowModelKey {
@@ -152,82 +93,37 @@ impl From<&WowModelExt> for WowModelKey {
     }
 }
 
-/// The WoW light, shared by every model material. **All Vec4 uniforms merge onto one binding
-/// (100)** — `AsBindGroup` packs multiple `#[uniform(N)]` fields at the same `N` into a single
-/// buffer entry, which is what keeps the model pipeline under Metal's 16-buffer vertex-stage cap.
-/// (Bevy 0.18's AsBindGroup macro hardcodes uniform-binding visibility to `FRAGMENT|VERTEX|COMPUTE`
-/// regardless of `visibility(fragment)`, so the only effective lever for the BUFFER count is the
-/// number of bindings — pack, don't narrow.) The WGSL struct order **must** match the field order
-/// below (each Vec4 is 16 bytes, no implicit padding).
+/// The model material's extension. Every `Vec4` uniform packs into binding 100, one buffer entry,
+/// to stay under Metal's 16-buffer vertex-stage cap (Bevy 0.18 ignores `visibility` on uniforms);
+/// `ModelParams` in `wow_model.wgsl` must match the field order.
 #[derive(Asset, AsBindGroup, Clone, TypePath)]
 #[bind_group_data(WowModelKey)]
 pub struct WowModelExt {
-    /// Ground-clutter distance fade: `x` = full-opacity radius (yd), `y` = fully-faded radius (yd),
-    /// `w` = enabled (>0.5). `Vec4::ZERO` (the default for trees/WMOs/creatures) disables it; clutter
-    /// sets it to the detail-doodad horizon (~52.5→70 yd) so grass erodes out with distance. Per-material
-    /// (set at creation, not light) so it stays on the cheap packed uniform, not the shared buffer.
+    /// Clutter fade: `x`, `y` = full-opacity and fully-faded view depth (yd; the ~70 yd horizon),
+    /// `w` = clutter, all zero off clutter; `z` = the batch marker bits.
     #[uniform(100)]
     pub clutter_fade: Vec4,
-    /// Per-material flags (set at material creation, NOT light). `x` = **is_wmo** (>0.5 ⇒ FFP directional
-    /// `ambient + sun·N·L` × MOCV at sun-scale 1, no exterior terrain-shade). `y` = **fade variant** (>0.5 ⇒
-    /// the distance-fade BLEND twin → `specialize` forces depth-write ON; the 224/255 stable-silhouette
-    /// cutout rides `clutter_fade.z` bit 10 separately, set only for AlphaKey sources — 0842; see
-    /// [`WowModelKey`]). `zw` reserved.
+    /// `x` = WMO, `y` = the fade blend twin, `z` = interior, `w` = unlit fullbright.
     #[uniform(100)]
     pub model_flags: Vec4,
-    /// Per-material MCSH terrain-shade **selector** (`wow_model.wgsl`, the exterior doodad matte). `x` picks
-    /// which live doodad sun LEVEL scales the FFP matte's diffuse/sun term — `1.0` ⇒ lit ground, `0.2` ⇒
-    /// MCSH-shadowed ground (the shader thresholds at 0.5), so a doodad inherits the shade it stands in like
-    /// the clutter/terrain beside it. Set at creation (a doodad doesn't move, so its shade is static ⇒ it
-    /// rides the deduped material, not per-instance `MeshTag`). Clutter/WMO ignore it (sun-scale 1);
-    /// creatures/player default `1.0` until the live-sample pass. `y` = the WMO authored batch order
-    /// (shader-unread; `WowModelKey` reads it back for the per-batch depth bias). `zw` = the batch's
-    /// live **UV-animation offset** (decision 0130 phase 3): added to the stage UVs in
-    /// `wow_model.wgsl`; `0` for static batches, re-sampled per frame by
-    /// `doodad_anim::tick_anim_materials` for texanim batches (flowing waterfalls).
+    /// `x` = the terrain-shade selector, `y` = the WMO batch order (the clip-z layering nudge),
+    /// `zw` = the UV-animation offset.
     #[uniform(100)]
     pub sun_scale: Vec4,
-    /// Per-material **RGB tint** (`xyz`): the M2Color colour multiplied into the albedo exactly
-    /// where the static vertex-colour tint folds — carrying the tint of batches whose colour track
-    /// ANIMATES (the vertex bake is skipped for those, `benilla-formats` `m2_batches`). Seeded at
-    /// the track's first key (pixel-identical to the old static bake for a lane that never ticks
-    /// it); the effect lane clones the material per instance and re-samples per frame (a spell
-    /// effect's white-hot flash cooling to red). `xyz = 1` — the identity — for the overwhelming
-    /// majority. **`w` = the WMO interior batch-class lane** (`0` = exterior law, `1` = interior
-    /// INT ⇒ unlit `tex × MOCV`, `2` = interior TRANS ⇒ the per-vertex MOCV-alpha lit↔bake lerp —
-    /// wow-re `trace-forensics-abbey-interior-d3d` §2); `0` for every non-WMO batch.
+    /// `xyz` = the M2Color tint of a batch whose colour track animates, identity otherwise; `w` =
+    /// the WMO interior batch class (`0x6b5190`): `0` exterior, `1` INT, `2` TRANS.
     #[uniform(100)]
     pub tint: Vec4,
-    /// The WMO window/glass law (byte-verified, wow-re `wmo-lit-selector` / `wmo-interior-night-light`).
-    /// `xyz` = the MOMT **SIDN** authored emissive colour (gamma bytes /255; `0` for non-SIDN and every
-    /// M2): the shader multiplies it by the live night fraction (`wow_light.grade.x`) and adds it inside
-    /// the lit sum on lit lanes — windows glow warm at night, nothing by day. `w` = the MOMT **WINDOW**
-    /// flag (>0.5): an interior-group batch swaps to the brighter Direct/Ambient-midpoint light
-    /// (ambient +16/255) — the warm pane seen from inside a building.
+    /// WMO glass, `0` on M2: `xyz` = the MOMT SIDN night emissive (ramp `0x6b4090`), `w` = the MOMT
+    /// WINDOW flag, the brighter interior light (`0x6d37e0`, ambient +16/255).
     #[uniform(100)]
     pub sidn: Vec4,
-    /// The shared mat-anim TABLE slots (decision 1381): `x` = the UV-scroll slot + 1, `y` = the
-    /// animated-tint slot + 1 — `0` = not table-animated, and the shader uses the static lanes
-    /// (`sun_scale.zw` / `tint.xyz`) exactly as before. Baked when the batch registers its
-    /// sampler; the per-frame samples live in the shared light buffer's `matanim` region, so an
-    /// animating material is never mutated again (no per-frame `Modified`, no bind-group
-    /// rebuild, no whole-population `AssetChanged` walks — B131's chain, severed at the root).
-    /// `z` = the **affine** slot (decision 2019): its row is the texture transform's rotation
-    /// and scale as deltas from the identity, `[cos − 1, sin, sx − 1, sy − 1]`
-    /// (`mat_anim_table::affine_row`), composed about the pivot `(½, ½)` after the translation —
-    /// the reference's `uv' = R((uv + t − p) ⊙ s) + p`. Row 0 is the identity, so a material
-    /// with no rotation reads exactly the translated UV it always did. Written by the lanes that
-    /// own a material per instance (the UI model tiles); `w` free.
+    /// Rows of the shared light buffer's `matanim` region, `0` = identity: `x` = UV scroll, `y` =
+    /// tint, `z` = the texture-transform affine, `w` = the UI tile's cell clip.
     #[uniform(100)]
     pub anim_slots: Vec4,
-    /// **The shared global light** (`lighting::global_light`): one storage buffer every material reads,
-    /// updated once/frame in place — replaces the per-material light/fog/SH uniforms (ambient/diffuse/
-    /// sun/spec + fog + the 7 Model2.bls SH-probe coeffs) the old `apply_wow_lighting` re-pushed every
-    /// frame (re-creating every bind group). `wow_model.wgsl` reads it as `var<storage, read> wow_light`
-    /// (rows 0-12 + the point-light table). Both stages: the fragment does the custom shading, the
-    /// vertex evaluates the Gouraud point-light term from the appended table (decision 0278 — bevy's
-    /// own clusterable buffer is fragment-only in the view layout, so the lights ride our buffer).
-    /// Set once, never mutated.
+    /// The shared global light (`lighting::global_light`), updated in place once a frame; the
+    /// vertex stage reads its point-light table, since Bevy's clusterable lights are fragment-only.
     #[storage(90, read_only, buffer, visibility(vertex, fragment))]
     pub light_buf: Buffer,
     /// MONKEY (torch shadows Phase 3A): the interior torch depth-map ARRAY — the one shared
@@ -270,9 +166,7 @@ pub struct TorchBinds {
 }
 
 impl MaterialExtension for WowModelExt {
-    /// Custom vertex stage (decision 0278): bevy's mesh vertex verbatim plus the GOURAUD point-light
-    /// term — the dynamic light sum evaluates per VERTEX like the reference FFP and interpolates,
-    /// which is what spreads a fixture's floor pool and keeps the forge hood dim.
+    /// Bevy's mesh vertex plus the point-light term, per vertex like the reference's FFP.
     fn vertex_shader() -> ShaderRef {
         "embedded://benilla_assets/shaders/wow_model.wgsl".into()
     }
@@ -281,25 +175,16 @@ impl MaterialExtension for WowModelExt {
         "embedded://benilla_assets/shaders/wow_model.wgsl".into()
     }
 
-    /// Per-batch depth + blend overrides Bevy's `AlphaMode` can't express. **Depth:** the real client
-    /// writes depth for EVERY M2 batch — opaque or transparent — and tests `LEQUAL`, *unless* the
-    /// material's render flag 0x10 (no-write) / 0x08 (no-test) clears it (VERIFIED, wow-re
-    /// `m2-depth-blend-state`). Bevy's transparent pass defaults depth-write OFF, so a model's own
-    /// transparent cards bleed through / flicker from some angles; we set it per-flag. The distance-fade
-    /// blend twin (`fade`) additionally forces depth-write ON (benilla's feather pass) regardless.
+    /// The reference writes depth for every M2 batch, transparent ones too, and tests `LEQUAL`,
+    /// unless render flag 0x10 (no write) or 0x08 (no test) clears it (`0x70c190`).
     fn specialize(
         _pipeline: &MaterialExtensionPipeline,
         descriptor: &mut RenderPipelineDescriptor,
         layout: &MeshVertexBufferLayoutRef,
         key: MaterialExtensionKey<Self>,
     ) -> Result<(), SpecializedMeshPipelineError> {
-        // The owned-palette skinning path (decision 0720): a mesh carrying the WOW joint
-        // attributes (the skinned twin — `crate::build_skinned_submesh_mesh`) compiles
-        // the WOW_RIG_SKIN vertex path, which skins from the shared buffer's palette region by
-        // the instance's MeshTag rig field. The base mesh pipeline built the vertex buffer
-        // layout without the joint attributes (they're not Bevy's, so it doesn't know them);
-        // rebuild it with the same conditionals (mesh.rs `specialize`, locations 0-5) plus ours
-        // at 10/11. Bevy's own SKINNED branch never fires for these meshes — that's the point.
+        // `WOW_RIG_SKIN` skins from the shared buffer's palette. The base layout lacks our joint
+        // attributes: rebuild it with Bevy's conditionals (mesh.rs, locations 0-5) plus 10/11.
         if layout.0.contains(crate::ATTRIBUTE_WOW_JOINT_INDEX) {
             descriptor.vertex.shader_defs.push("WOW_RIG_SKIN".into());
             // The FRAGMENT stage keys on the same def: a skinned unit takes the whole-unit
@@ -325,12 +210,8 @@ impl MaterialExtension for WowModelExt {
             attrs.push(crate::ATTRIBUTE_WOW_JOINT_WEIGHT.at_shader_location(11));
             descriptor.vertex.buffers = vec![layout.0.get_layout(&attrs)?];
         }
-        // The merged fader blob (decisions 1418/1420): a mesh carrying the per-vertex fade
-        // sphere compiles the WOW_MERGED_FADE path — the faithful doodad fade curve computed
-        // per vertex (folded into the tag fade the fragment already consumes) and a clip-space
-        // collapse at zero (the Hidden channel). The blob's material is its blend TWIN, so the
-        // feather is the reference's own translucent ramp. Same rebuild pattern as the joints
-        // above; the two attribute sets never co-occur (merged blobs never skin).
+        // A merged blob computes the doodad fade per vertex from its fade sphere; same rebuild,
+        // and merged blobs never skin.
         if layout.0.contains(crate::ATTRIBUTE_WOW_FADE_SPHERE) {
             descriptor.vertex.shader_defs.push("WOW_MERGED_FADE".into());
             if let Some(fragment) = descriptor.fragment.as_mut() {
@@ -350,8 +231,7 @@ impl MaterialExtension for WowModelExt {
                 }
             }
             attrs.push(crate::ATTRIBUTE_WOW_FADE_SPHERE.at_shader_location(12));
-            // The interior-prop half (1418 lane 3): the baked SH-probe slot replaces the
-            // per-entity MeshTag payload.
+            // An interior-prop blob's baked SH-probe slot replaces the per-entity MeshTag payload.
             if layout.0.contains(crate::ATTRIBUTE_WOW_MERGED_SLOT) {
                 descriptor.vertex.shader_defs.push("WOW_MERGED_SLOT".into());
                 if let Some(fragment) = descriptor.fragment.as_mut() {
@@ -361,31 +241,20 @@ impl MaterialExtension for WowModelExt {
             }
             descriptor.vertex.buffers = vec![layout.0.get_layout(&attrs)?];
         }
-        // M2 render flags 0x10 (no depth-write) / 0x08 (no depth-test), per batch. Default: write depth
-        // (LEQUAL) like the real client — including transparent batches, which fixes the bleed-through.
         if let Some(ds) = descriptor.depth_stencil.as_mut() {
             ds.depth_write_enabled = !key.bind_group_data.no_depth_write;
             if key.bind_group_data.no_depth_test {
                 ds.depth_compare = CompareFunction::Always;
             }
         }
-        // A far-side-of-water twin's bias is a SORT rung only (the water-plane interleave,
-        // `sky_order::FAR_SIDE_BIAS`): the base `StandardMaterial::specialize` has just packed the
-        // same f32 into the rasterizer `DepthBiasState` constant (bevy 0.18 `pbr_material.rs`,
-        // `depth_stencil.bias.constant`), where −4e4 ULPs would pull every far fragment ~0.5%
-        // deeper and clip a blade's coplanar sheen/glow against the blade's own opaque depth.
-        // Zero it back — the effect lane splits sort from raster by construction; this bit is the
-        // mesh lane's split.
+        // A sort bias is not a raster bias: the base `StandardMaterial::specialize` also packs it
+        // into `depth_stencil.bias.constant`, where the far side's −4e4 would clip coplanar layers.
         if key.bind_group_data.far_side {
             if let Some(ds) = descriptor.depth_stencil.as_mut() {
                 ds.bias.constant = 0;
             }
         }
-        // The WMO-skybox lane: pin the sky's far depth in the vertex stage (the def reaches the
-        // fragment too, for symmetry with the other lane defs — it reads nothing there), and —
-        // like the far-side twin above — keep its big negative rung sort-only. The rung
-        // (`sky_order::WMO_SKYBOX_BIAS`) exists to sink a camera-anchored backdrop under every
-        // world transparent; as a rasterizer constant it would be perturbing the pinned depth.
+        // The skybox pins clip z to 0, reverse-Z far, in the vertex stage; its bias is sort-only.
         if key.bind_group_data.sky_depth {
             descriptor.vertex.shader_defs.push("WOW_SKY_DEPTH".into());
             if let Some(fragment) = descriptor.fragment.as_mut() {
@@ -395,29 +264,15 @@ impl MaterialExtension for WowModelExt {
                 ds.bias.constant = 0;
             }
         }
-        // The WMO authored-batch-order depth nudge (the coplanar MOBA layering determinism) is NOT
-        // here any more: as a fixed-function `DepthBiasState` constant it made every batch index its
-        // own PIPELINE — Stormwind alone queued ~3000 variants of this one shader, each a
-        // synchronous render-thread compile on macOS (the city first-sight stall, decision 0837).
-        // The nudge now lives in `wow_model.wgsl`'s vertex stage, an exact relative scale of clip z
-        // driven by `sun_scale.y` (uniform DATA, no pipeline axis) — same one-ULP-per-index
-        // semantics, byte-verified intent unchanged (wow-5875-re wmo-batch-blend-depth-state.md).
         if key.bind_group_data.fade && !key.bind_group_data.sky_depth {
-            // The distance-fade blend twin needs depth-write ON so near geometry occludes far within the
-            // same fading model — force it regardless of the per-flag rule above. EXCEPT on the
-            // WMO-skybox lane: its twin exists for the 4-second crossfade, where every fragment
-            // forces the one far depth — there is no within-model occlusion to preserve, and the
-            // sky's own law is depth-write off, always (the fragment leaves the z-buffer at its
-            // clear value so the world and the forced-far glare quads order by depth alone).
+            // A fading model's near cards occlude its far ones; the sky never writes depth.
             if let Some(ds) = descriptor.depth_stencil.as_mut() {
                 ds.depth_write_enabled = true;
             }
         }
         if key.bind_group_data.clutter {
-            // Ground clutter (AlphaMode::Mask → alpha-mask pass, depth-write already ON): force the
-            // reference's over-blend on in place, so the ~70 yd ramp fades OPACITY instead of a hard
-            // alpha-test cut. The 128/255 discard (crisp blade silhouette) + `tex × ramp` output alpha
-            // are already produced in the shader; we only flip the blend state.
+            // Clutter blends in the alpha-mask pass, as the reference does, so the ~70 yd ramp
+            // fades opacity; the shader keeps the 128/255 discard.
             if let Some(target) = descriptor
                 .fragment
                 .as_mut()
@@ -428,11 +283,8 @@ impl MaterialExtension for WowModelExt {
             }
         }
         if key.bind_group_data.additive {
-            // Additive glow cards: a PURE (ONE, ONE) add — the shader has already folded the
-            // radial alpha into the colour IN GAMMA SPACE (wow_model.wgsl, decision 0160: a
-            // hardware `SrcAlpha` factor would multiply after the linear conversion, inflating
-            // every soft skirt by α^(1/2.2) — the fat hard-disc halo). Not Bevy's `AlphaMode::Add`
-            // (its premultiply is linear-side too).
+            // A pure (ONE, ONE) add: the shader weights by alpha in gamma space, where a `SrcAlpha`
+            // factor or `AlphaMode::Add` would weight after linearising and fatten soft edges.
             if let Some(target) = descriptor
                 .fragment
                 .as_mut()
@@ -454,15 +306,9 @@ impl MaterialExtension for WowModelExt {
             }
         }
         if key.bind_group_data.zfill {
-            // The depth-prime twin (`model_render::zfill_material` — the reference's `M2UseZFill`
-            // clone, wow-re `m2-blend-promotion-zfill.md` §4): a translucent model's z-writing
-            // batches draw once colour-masked-off, blend-off, z-write ON, sorted before its colour
-            // batches (the material's negative sort bias) — so each colour fragment passes
-            // GreaterEqual only at the model's own nearest surface, and interior/overlapped layers
-            // fail. One blended layer everywhere: no self-overlap darkening on a stealthed body.
-            // The fragment still runs its discards (farclip, the bit-10 twin cutout);
-            // its colour output is computed and masked (an early return would be the natural
-            // spelling, but naga's MSL backend miscompiles the dead tail — see the shader note).
+            // The reference's `M2UseZFill` pre-pass (`0x707f7d`-`0x708072`): depth only, so a
+            // translucent model shows one blended layer. The colour is computed and masked, not
+            // skipped by an early return, which naga's MSL backend miscompiles.
             if let Some(frag) = descriptor.fragment.as_mut() {
                 if let Some(target) = frag.targets.get_mut(0).and_then(|t| t.as_mut()) {
                     target.blend = None;
@@ -473,11 +319,7 @@ impl MaterialExtension for WowModelExt {
                 ds.depth_write_enabled = true;
             }
         }
-        // The straddle split's waterline clip (decision 2188 — `benilla_world::straddle`): only a
-        // transparent-pass batch is ever classified against the water plane, so only its
-        // pipelines carry the clip. Keyed on the blend pass Bevy already specializes on, so it
-        // mints no pipeline of its own; the fragment clips nothing unless the instance's slot
-        // says it straddles.
+        // The waterline clip (`benilla_world::straddle`) keys on the blend pass: no new pipelines.
         if key
             .mesh_key
             .intersection(MeshPipelineKey::BLEND_RESERVED_BITS)
@@ -489,12 +331,8 @@ impl MaterialExtension for WowModelExt {
         }
         let key = &key.bind_group_data;
         if key.modulate || key.modulate2x {
-            // The MULTIPLY blends (decision 0528, byte-verified wow-re `m2-depth-blend-state`):
-            // Mod (M2 mode 5 / WMO 4) = DST_COLOR/ZERO → out = src·dst; Mod2x (M2 6 / WMO 5) =
-            // DST_COLOR/SRC_COLOR → out = 2·src·dst — the ARMORREFLECT weapon/armor sheen (neutral
-            // at mid-grey, brightening at the streak). The framebuffer holds gamma (0161), so these
-            // factors reproduce the reference's byte math exactly. Alpha: the equation reads no
-            // source alpha — keep the destination's.
+            // `0x70c190`: Mod (M2 mode 5, WMO 4) is `DST_COLOR/ZERO`, Mod2x (M2 6, WMO 5)
+            // `DST_COLOR/SRC_COLOR`; on a gamma framebuffer this is the reference's byte math.
             if let Some(target) = descriptor
                 .fragment
                 .as_mut()
@@ -523,21 +361,14 @@ impl MaterialExtension for WowModelExt {
     }
 }
 
-/// Distant low-detail terrain (WDL): unlit white geometry under a saturated fog of its own — flat
-/// scene-fog colour, the "fog hull" (decision 1521) — the horizon hills the reference draws beyond the
-/// streamed detailed tiles. Both shader stages are custom (`shaders/wdl.wgsl`): white verts × the
-/// scene fog COLOUR with the hull pass's own start-0 / end-1.0 pair (never the scene's distances),
-/// opaque (`AlphaMode::Opaque` ⇒ depth-LEQUAL + depth-write, no blend — the verified WoW.8 state).
+/// Distant low-detail terrain (WDL), the horizon hills beyond the streamed tiles: opaque white
+/// geometry under the scene fog colour at the hull pass's own start 0 and end 1.0.
 pub type WdlMaterial = ExtendedMaterial<StandardMaterial, WdlExt>;
 
-/// WDL reads the scene fog COLOUR straight off the shared global light — it has no per-material input
-/// of its own (the band is white geometry whose entire colour is the fog, saturated).
+/// WDL has no per-material input: its whole colour is the scene fog, off the shared global light.
 #[derive(Asset, AsBindGroup, Clone, TypePath)]
 pub struct WdlExt {
-    /// **The shared global light** (`lighting::global_light`), the same buffer terrain and the models
-    /// bind. `wdl.wgsl` reads rows 4/5 only — the SCENE fog colour (block 1) plus the farclip wall, which is
-    /// right by construction: the band *is* the horizon, so it is never inside a WMO. Set once at
-    /// startup, never mutated (this replaces the per-material `apply_wow_lighting` push).
+    /// The shared global light, rows 4/5 only (scene fog colour, farclip wall).
     #[storage(90, read_only, buffer)]
     pub light_buf: Buffer,
 }
@@ -551,20 +382,12 @@ impl MaterialExtension for WdlExt {
     }
 }
 
-/// MCLQ liquid surfaces (lakes/rivers/ocean): a port of the reference's `ocean0_s.bls` shader path.
-/// The animated frame set is a `texture_2d_array` whose RGB is near-black and whose **ALPHA is the
-/// ripple** (→ surface transparency); the visible colour is the dark texture **hardware-lit**
-/// (`ambient + N·L·sun`) and **fog-tinted by distance** — NOT a flat tint (the blue/teal is the blue
-/// ambient + fog). Two-sided, alpha-blended, depth-write off (Bevy's transparent pass = the verified
-/// WoW state). P1 omits the unit-1 detail ripple + specular term.
+/// Liquid surfaces, one `liquid.wgsl` arm per reference liquid renderer: ADT MCLQ (the
+/// `ocean0_s.bls` combine), WMO exterior and interior water, and magma and slime.
 pub type LiquidMaterial = ExtendedMaterial<StandardMaterial, LiquidExt>;
 
-/// Liquid material inputs: the animated frame array, the per-material kind lanes, and the current
-/// animation frame index. Everything that is *light* — ambient/diffuse/sun/spec, both water swatches
-/// and both fog blocks — comes off the shared global-light buffer, exactly like terrain and the
-/// models; this material carries only what genuinely varies per material. **The Vec4 uniforms merge
-/// onto one binding (102)** (same packing trick as the other extensions). WGSL struct order must
-/// match the field order.
+/// Liquid inputs: the animated frames and the per-material lanes; all light comes off the shared
+/// global light. The `Vec4` uniforms pack into binding 102, in the WGSL struct's field order.
 #[derive(Asset, AsBindGroup, Clone, TypePath)]
 pub struct LiquidExt {
     /// MONKEY (enhanced water): the water module's own bindings (103-106, `enhanced_water.wgsl`).
@@ -587,40 +410,23 @@ pub struct LiquidExt {
     #[texture(100, dimension = "2d_array", visibility(fragment))]
     #[sampler(101, visibility(fragment))]
     pub frames: Handle<Image>,
-    /// The per-material constants that pick which *lanes* of the shared light this surface reads.
-    /// None of them is a light value; all four are fixed at material creation.
-    ///
-    /// - `x` = **fullbright** (>0.5 ⇒ magma/slime): the animated texture IS the opaque body — skip
-    ///   the depth swatch and the N·L term. Not "skip the fog"; see `liquid.wgsl` and decision 0691.
-    /// - `y` = **ocean** (>0.5): read the ocean water swatch (shared-light rows 15/16, `Light.dbc`
-    ///   IntBand 14/15) instead of the river/lake one (rows 13/14, IntBand 16/17).
-    /// - `z` = **interior fog** (>0.5): this surface is a WMO *interior* group's own liquid, so it
-    ///   fogs with the interior block (rows 18/19) like the walls around it, not the scene fog. The
-    ///   reference gates the WMO liquid pass's fog submit (`0x6b6323`–`0x6b6342`) on exactly the same
-    ///   `[0xca7f00]` as the WMO *geometry* pass (`0x6b51d9`/`0x6b51ea`) — one flag, so the pool and
-    ///   the room can never disagree. ADT liquid is 0: the ADT pass submits no fog of its own and
-    ///   draws under the once-a-frame scene submit.
-    /// - `w` = the sun-sheen **shininess** (`lighting::WATER_SHININESS`) for the `ocean0_s.bls`
-    ///   `secondary` Blinn term — water's own exponent, not the shared row-3 terrain shininess.
+    /// Which lanes of the shared light this surface reads:
+    /// - `x` = fullbright (magma, slime): the sheet is the opaque body.
+    /// - `y` = ocean: rows 15/16 (`Light.dbc` IntBand 14/15), else rows 13/14 (IntBand 16/17).
+    /// - `z` = a WMO interior group's liquid, fogged with the interior block (rows 18/19): the
+    ///   reference gates its fog (`0x6b6323`-`0x6b6342`) on the same `[0xca7f00]` as the group's
+    ///   geometry (`0x6b51d9`/`0x6b51ea`).
+    /// - `w` = the sun-sheen shininess (`lighting::WATER_SHININESS`).
     #[uniform(102)]
     pub kind: Vec4,
-    /// - `x` = **which renderer** this surface belongs to (`liquid::surface::LiquidPath`): `0` = ADT
-    ///   MCLQ (`ocean0_s.bls`), `1` = WMO exterior (`MapObjExtWater0.bls`), `2` = WMO interior
-    ///   (fixed-function, unlit). The reference has three liquid renderers with genuinely different
-    ///   combines, stage counts and opacity sources; this is which one `liquid.wgsl` runs.
-    /// - `y`/`z`/`w` reserved.
+    /// `x` = the renderer (`liquid::surface::LiquidPath`): `0` ADT MCLQ, `1` WMO exterior, `2` WMO
+    /// interior.
     #[uniform(102)]
     pub path: Vec4,
-    /// `x` = reserved (frame 0), `y` = frame count, `z` = scroll flag, `w` = clock enable —
-    /// the shader derives frame index and scroll from `globals.time` (liquid.wgsl `anim_time`);
-    /// nothing mutates this uniform after build.
+    /// `y` = frame count, `z` = scroll flag, `w` = clock enable.
     #[uniform(102)]
     pub anim: Vec4,
-    /// **The shared global light** (`lighting::global_light`): the one storage buffer terrain and the
-    /// models already read, now liquid's source too. `liquid.wgsl` reads rows 0-5 (light + scene fog +
-    /// farclip), 13-16 (the two water swatches) and 18/19 (the interior fog block). Read in BOTH
-    /// stages — the vertex stage evaluates the faithful per-vertex sun sheen. Set once at material
-    /// creation, never mutated.
+    /// The shared global light, read in both stages (the vertex stage evaluates the sun sheen).
     #[storage(90, read_only, buffer, visibility(vertex, fragment))]
     pub light_buf: Buffer,
 }
@@ -633,18 +439,9 @@ impl MaterialExtension for LiquidExt {
         "embedded://benilla_assets/shaders/liquid.wgsl".into()
     }
 
-    /// **`WATER_BIAS` is a SORT rung; keep it out of the rasterizer** — the same split the far-side
-    /// twin and the WMO skybox make above, for the one surface that most needs it.
-    ///
-    /// The water pass has a fixed frame slot (`sky_order::WATER_BIAS`, −2e4), and the base
-    /// `StandardMaterial::specialize` packs that same f32 into `depth_stencil.bias.constant` (bevy
-    /// 0.18 `pbr_material.rs`). At −2e4 ULPs that shoves every water fragment ~0.24 % of its view
-    /// distance *away* from the eye — and the water plane is the one world surface that meets the
-    /// ground at a grazing angle over tens of yards, so a relative depth pull there does not settle
-    /// a tie, it moves the waterline. Worse, a float depth buffer's bias unit is the ULP at the
-    /// primitive's own depth, so the pull **doubles at every exponent boundary**: two water
-    /// triangles either side of one land in different buckets and their shorelines stop agreeing.
-    /// The ordering job needs none of it — the rung exists for the transparent phase's sort key.
+    /// `sky_order::WATER_BIAS` (−2e4) is a sort rung, kept out of the rasterizer: as a depth-bias
+    /// constant it would move the waterline, by an amount that doubles at every float exponent
+    /// boundary, so neighbouring triangles' shorelines would disagree.
     fn specialize(
         _pipeline: &MaterialExtensionPipeline,
         descriptor: &mut RenderPipelineDescriptor,
@@ -658,23 +455,11 @@ impl MaterialExtension for LiquidExt {
     }
 }
 
-/// Per-tile splat inputs: a `texture_2d_array` of the tile's ground textures, a `texture_2d_array`
-/// of its per-chunk alpha maps, and the tiling factor. Which array layers a fragment blends comes
-/// from the merged mesh's vertex `COLOR` (4 layer indices) and `UV1.x` (alpha index).
+/// Per-tile terrain splat, one material per ADT tile: each merged-mesh vertex carries its chunk's
+/// four layer indices (`COLOR`) and alpha layer (`UV1.x`), so a tile is one draw.
 ///
-/// **One shared sampler** (repeating, on `layer_array`) covers both arrays: `StandardMaterial`
-/// already uses ~6 of Metal's 16 fragment samplers and the view adds more, so extra samplers risk
-/// the per-stage limit. Layer UVs are tiled; the alpha map is sampled in 0..1 where repeat == clamp.
-/// **All terrain Vec4 uniforms merge onto one binding (106).** AsBindGroup packs multiple
-/// `#[uniform(N)]` fields at the same `N` into a single buffer entry; the WGSL declares one
-/// `var<uniform> t: TerrainParams;` whose fields land in the SAME order as the Rust declaration
-/// (each Vec4 is 16 bytes, no padding). One buffer entry per pipeline stage instead of eleven —
-/// which is what keeps us under Metal's 16-buffer vertex-stage cap once Step 5's fog uniforms are
-/// added. Visibility-narrowing via `visibility(fragment)` doesn't work on uniforms (Bevy 0.18
-/// hardcodes them to all stages), so packing is the effective lever for the buffer count.
-///
-/// Textures + sampler ARE fragment-narrowable (the macro respects `visibility(fragment)` there)
-/// so the splat / alpha / shadow arrays stay fragment-only.
+/// One repeating sampler (105) serves every array, to stay under Metal's 16 fragment samplers;
+/// `terrain.wgsl` insets the alpha UVs by half a texel so they do not wrap at a chunk edge.
 #[derive(Asset, AsBindGroup, Clone, TypePath)]
 pub struct TerrainExtension {
     #[texture(100, dimension = "2d_array", visibility(fragment))]
@@ -682,24 +467,16 @@ pub struct TerrainExtension {
     pub layer_array: Handle<Image>,
     #[texture(104, dimension = "2d_array", visibility(fragment))]
     pub alpha_array: Handle<Image>,
-    /// Per-chunk MCSH baked shadow maps (one R8 layer each, `R` = shadowed). The merged mesh's
-    /// `UV1.y` carries the layer index, or `-1` for a chunk with no shadow map. Shares sampler 105.
+    /// Per-chunk MCSH shadow maps (`R` = shadowed); `UV1.y` is the layer, `-1` for none.
     #[texture(110, dimension = "2d_array", visibility(fragment))]
     pub shadow_array: Handle<Image>,
 
-    // ------------------------------------------------------------------------------------------
-    // Packed uniform buffer at binding 106 — fields below appear in the WGSL `TerrainParams` struct
-    // in the SAME order (each Vec4 16 bytes, no padding). Reordering is a breaking change.
-    // ------------------------------------------------------------------------------------------
+    // Binding 106's uniforms, in the field order of the WGSL `TerrainParams`.
     /// `x` = texture tiling factor (repeats per chunk); other lanes unused.
     #[uniform(106)]
     pub params: Vec4,
 
-    /// **The shared global light** (`lighting::global_light`): one persistent storage buffer all
-    /// materials reference, updated once/frame in place — the faithful replacement for the old
-    /// per-material light/fog uniforms (ambient/diffuse/sun/spec + fog) that `apply_wow_lighting`
-    /// re-pushed every frame (re-creating every bind group). Set once at tile spawn, never mutated.
-    /// `terrain.wgsl` reads it as `var<storage, read> wow_light` (rows 0-5: light + fog + farclip).
+    /// The shared global light, rows 0-5 (light, fog, farclip).
     #[storage(90, read_only, buffer)]
     pub light_buf: Buffer,
     /// MONKEY (outdoor torch shadows: terrain): the torch receiver's three bindings, at the SAME
@@ -723,8 +500,7 @@ pub struct TerrainExtension {
 }
 
 impl MaterialExtension for TerrainExtension {
-    // Custom VERTEX shader too (not just fragment): the sun specular is computed per-vertex (Q14), and
-    // Bevy's `VertexOutput` has no slot to carry the interpolated result.
+    // The sun specular is per vertex (the reference's light flush `0x59c820`).
     fn vertex_shader() -> ShaderRef {
         "embedded://benilla_assets/shaders/terrain.wgsl".into()
     }
@@ -812,8 +588,7 @@ mod tests {
     #[test]
     fn the_sky_lane_pins_the_far_depth_at_the_vertex() {
         let src = include_str!("shaders/wow_model.wgsl");
-        // The pin, BEHIND its ifdef — matched with the guard attached, so ungating it (every model
-        // draw at the far plane) fails here rather than as a blank world.
+        // The pin, matched behind its ifdef: ungated, every model draw sits at the far plane.
         let pin = src
             .find("#ifdef WOW_SKY_DEPTH")
             .expect("the sky-depth branch is gone");
@@ -831,41 +606,32 @@ mod tests {
         );
     }
 
-    /// The ADT depth swatch, pinned two ways: the WGSL still carries the reference's own row
-    /// arithmetic, and that arithmetic reproduces wow-re's published byte vectors.
-    ///
-    /// The mirror below is a **spec anchor**, not a second implementation — nothing else calls it.
-    /// It exists because WGSL has no unit-test harness here (Bevy's `#import`/`#ifdef` mean naga
-    /// cannot validate these files standalone), so the source-text pin above it is what ties the two
-    /// together: change the shader's formula and this fails, pointing at the numbers it has to keep
-    /// producing.
-    ///
-    /// The vectors are wow-re's, from `terrain/scratch/ocean-depth-ramp-law.md` — `Light.dbc` id 4,
-    /// map 0, t = 1440, the ocean pair `LightIntBand` sub-14 → sub-15.
+    /// The WGSL carries the reference's swatch row arithmetic, and a Rust mirror of it reproduces
+    /// the row fill `0x68a830` on `Light.dbc` id 4, map 0, t = 1440, ocean `LightIntBand` 14 to 15.
     #[test]
     fn liquid_swatch_reproduces_the_reference_row_ramp() {
         let src = include_str!("shaders/liquid.wgsl");
-        // The row accumulator: `c0 + floor(i*(c1 - c0)/64)`, NOT a lerp to the deep endpoint.
+        // The row accumulator `c0 + floor(i*(c1 - c0)/64)`, not a lerp to the deep endpoint.
         assert!(
             src.contains("let row = c0 + floor(i * (c1 - c0) / 64.0);"),
             "the swatch stopped building its rows the way FUN_0068a830 does — a plain lerp to the \
              deep endpoint runs a 64th of a ramp that does not exist (decision 2074)"
         );
-        // The ocean-only tail: floor(0.9*byte) on the LAST row, alpha forced opaque.
+        // The ocean-only tail: floor(0.9*byte) on the last row, alpha forced opaque.
         assert!(
             src.contains("if ocean && i >= 63.0 {")
                 && src.contains("vec4<f32>(floor(row.rgb * 0.9), 255.0)"),
             "the ocean's last-row darkening is gone — ~80% of the world's ocean vertices sample \
              that row, so this is the open sea's colour (decision 2074)"
         );
-        // LINEAR sampling across the two rows V falls between, at texel `V*64 - 0.5`.
+        // Linear sampling across the two rows V falls between, at texel `V*64 - 0.5`.
         assert!(
             src.contains("let t = clamp(v * 64.0 - 0.5, 0.0, 63.0);"),
             "the swatch stopped sampling as an 8x64 LINEAR/CLAMP texture — the ocean darkening \
              would step instead of ramping across the final 1/64 of V (decision 2074)"
         );
 
-        /// `row(i)` for one channel, mirroring `swatch_row`'s byte arithmetic exactly.
+        /// `row(i)` for one channel, `swatch_row`'s byte arithmetic.
         fn row(c0: i32, c1: i32, i: i32) -> i32 {
             c0 + (i * (c1 - c0)).div_euclid(64)
         }
@@ -878,7 +644,7 @@ mod tests {
         let (shallow, deep) = ([69, 123, 99], [11, 34, 40]);
         let at = |i| [0, 1, 2].map(|k| row(shallow[k], deep[k], i));
 
-        // Row 63 is one short of the endpoint on G — the ramp never arrives.
+        // Row 63 is one short of the endpoint on G: the ramp never arrives.
         assert_eq!(at(63), [11, 35, 40], "row 63 before the ocean tail");
         assert_ne!(
             at(63)[1],
@@ -895,7 +661,7 @@ mod tests {
             [9, 31, 36],
             "row 63 after the ocean tail (HSV V *= 0.9, which is floor(0.9*byte) per channel)"
         );
-        // The shallow end is the endpoint exactly — the tail and the shortfall are deep-end only.
+        // The tail and the shortfall are deep-end only.
         assert_eq!(at(0), shallow, "row 0 is the shallow endpoint verbatim");
     }
 }
diff --git a/crates/benilla-assets/src/minimap_grid.rs b/crates/benilla-assets/src/minimap_grid.rs
index d2c16c3c..82db6707 100644
--- a/crates/benilla-assets/src/minimap_grid.rs
+++ b/crates/benilla-assets/src/minimap_grid.rs
@@ -1,37 +1,21 @@
-//! The WMO **interior minimap** tile grid: how one WMO group's world footprint subdivides into the
-//! `<wmo>_<group>_<X>_<Y>.blp` minimap tiles the client streams inside a building (decision 0203's
-//! interior arc). Pure geometry — no Bevy — so the app renderer and the against-real-data test share
-//! one source of truth.
-//!
-//! Mechanism (RE'd in `wow-5875-re`'s minimap node, tile producer in the CMapObj/WMO TU; the grid
-//! **corrected + verified against Ironforge's authored tiles this session**, see
-//! `ironforge_group_grid_matches_trs`): the bake is a fixed **0.5 yd/texel**, each tile a
-//! power-of-two texel square clamped to `[32, 256]` px, sized to cover the group's footprint extent,
-//! and the tiles tile across that extent.
-//!
-//! Both roundings go **up**: the binary's round-to-int (`FUN_0073fdf5`) loads a control word with
-//! the RC field = round-toward-+∞, i.e. `ceil` — so the pixel edge is `2^ceil(log2(extent·2))` and
-//! the count is `ceil(extent / 128)` (a full 256-px tile = 128 yd). The RE note first read these as
-//! `floor`, which under-counts (group 1 → 0 columns, group 66 → 1×1); the byte-verified `ceil`
-//! matches the authored data — root cause in `wmo-interior-minimap.md` (fold-back this session).
+//! The WMO interior minimap tile grid: how one group's footprint splits into the
+//! `<wmo>_<group>_<X>_<Y>.blp` tiles the client streams inside a building (tile producer
+//! `0x6a5270`). Each tile is a power-of-two texel square clamped to 32..256 px at 0.5 yd a texel,
+//! and both roundings go up: the round-to-int (`FUN_0073fdf5`) runs round-toward-+∞, so the edge
+//! is `2^ceil(log2(extent·2))` px and the count `ceil(extent / 128)`.
 
-/// The minimap tile bake resolution: world yards per texel (RE constant `0xca7ebc`).
+/// World yards per minimap texel (`0xca7ebc`).
 pub const YD_PER_TEXEL: f32 = 0.5;
 
-/// Smallest / largest authored tile edge in texels (RE clamp; a full tile = 256 px = 128 yd).
+/// The tile edge clamp in texels; a full 256 px tile spans 128 yd.
 const MIN_TILE_PX: u32 = 32;
 const MAX_TILE_PX: u32 = 256;
 
-/// World yards a full (256-px) tile spans — the fixed divisor of the `ceil(extent/128)` tile count.
+/// World yards a full tile spans, the divisor of the tile count.
 const TILE_SPAN_YD: f32 = MAX_TILE_PX as f32 * YD_PER_TEXEL;
 
-/// For one axis of a WMO group whose footprint `extent` (yards) is known: `(tile_count, tile_world)`
-/// — how many minimap tiles span that axis, and the world size (yards) each tile covers (its stride).
-/// The tile world size is the next-pow2 texel square (clamped) that covers `extent` at `0.5 yd/texel`;
-/// the count is `ceil(extent / 128)`, both per the binary's round-toward-+∞.
-///
-/// Verified against Ironforge: group 66 → 2×2, 44 → 1×2, 89 → 2×1, small groups → 1×1
-/// (`benilla-assets` test `ironforge_group_grid_matches_trs`).
+/// One axis of a group's footprint `extent` (yd) as `(tile_count, tile_world)`: the tiles across
+/// it and the yards each one covers.
 pub fn group_axis_grid(extent: f32) -> (u32, f32) {
     let texels = (extent / YD_PER_TEXEL).max(1.0);
     let px = next_pow2(texels.ceil() as u32).clamp(MIN_TILE_PX, MAX_TILE_PX);
@@ -64,15 +48,11 @@ mod tests {
 
     #[test]
     fn grid_counts_and_sizes_match_ironforge_footprints() {
-        // Extents (yd) read off the real Ironforge groups; expected counts read off the trs tiles.
-        // grp 1  (20.6): 1 tile, sized 64 px = 32 yd.
+        // Extents (yd) of Ironforge groups 1, 44 (X, Y), 66 and 89 (X, Y); counts from the trs.
         assert_eq!(group_axis_grid(20.6), (1, 32.0));
-        // grp 44 X (51.3): 1 tile of 128 px = 64 yd; Y (201.0): 2 tiles of 256 px = 128 yd.
         assert_eq!(group_axis_grid(51.3), (1, 64.0));
         assert_eq!(group_axis_grid(201.0), (2, 128.0));
-        // grp 66 (185.6): 2 tiles of 128 yd.
         assert_eq!(group_axis_grid(185.6), (2, 128.0));
-        // grp 89 X (128.4): just over one tile → 2; Y (107.7): 1.
         assert_eq!(group_axis_grid(128.4).0, 2);
         assert_eq!(group_axis_grid(107.7).0, 1);
     }
diff --git a/crates/benilla-assets/src/model.rs b/crates/benilla-assets/src/model.rs
index 907e4b95..02dd5130 100644
--- a/crates/benilla-assets/src/model.rs
+++ b/crates/benilla-assets/src/model.rs
@@ -1,7 +1,5 @@
-//! Shared building blocks for the M2 and WMO model loaders: the per-batch submesh type and the
-//! WoW→Bevy mesh bake. Both formats decode to a list of these (geometry + texture + blend/sidedness),
-//! with materials deferred to the spawn site (see the loader module docs) so the assets stay
-//! app-independent.
+//! What the M2 and WMO loaders share: the per-batch submesh and the WoW-to-Bevy bakes of its mesh,
+//! skeleton, attachments and animation clips. Materials are built at the spawn site.
 
 use benilla_formats::{
     BillboardKind, BoneScaleAnim, CharSkinSlot, M2Attachment, ModelAnimation, ModelBlend,
@@ -19,156 +17,86 @@ use crate::coords::wow_to_bevy;
 
 mod anims;
 mod pose;
-// `PlayableAnim`/`ResolvedAnim` aren't re-exported further by `lib.rs` (nothing outside this crate
-// names them yet), so rustc can't see this re-export escape — allow silences the resulting
-// unused-import false positive on an otherwise-live facade re-export.
-#[allow(unused_imports)]
-pub use anims::{AnimClip, ClipEvent, ModelAnimations, PlayableAnim, ResolvedAnim};
+pub use anims::{AnimClip, ClipEvent, ModelAnimations};
 pub use pose::{PoseBone, PoseClip, PoseNode, PoseSource, PoseTrack};
 
-/// A billboarded submesh's render data (Bevy space): the bone pivot the card rotates about (model-local
-/// — compose with the instance transform) and the billboard kind. The mesh is built **centred at
-/// `pivot`** so the spawn site can rotate it about the pivot to face the camera each frame.
+/// A billboarded batch's card in Bevy space; its mesh is centred on `pivot` (model-local).
 #[derive(Clone)]
 pub struct BillboardInfo {
     pub pivot: Vec3,
-    /// The billboard bone's index — the joint the card rides on an animated host (swinging lamp,
-    /// mount lights). On a rest-pose host the pivot alone places the card.
+    /// The billboard bone, the joint the card rides on an animated host.
     pub bone: u16,
     pub kind: BillboardKind,
-    /// The billboard bone's global-sequence scale animation (the looping glow-card pulse), if any —
-    /// sampled per-frame at the spawn site and folded into the card scale. `None` for a static card.
+    /// The bone's global-sequence scale loop (a glow card's pulse), folded into the card's scale.
     pub scale_anim: Option<BoneScaleAnim>,
-    /// The bone's per-sequence translation loops `(anim id, loop)`, keys baked to **Bevy axes** —
-    /// a model-local offset the card adds at its pivot when the spawn site arms one. Anim 0 is the
-    /// load arm's default (the questgiver `?` marker's low bob); anim 190 the marker's raised bob,
-    /// armed while the unit shows an overhead name (only the marker arms these today; see
-    /// `benilla_formats::Billboard::seq_translations`).
+    /// The bone's per-sequence translation loops `(anim id, loop)`, keys in Bevy axes: the quest
+    /// marker bobs low on anim 0, and higher on 190 while its unit shows an overhead name.
     pub seq_translations: Vec<(u16, BoneScaleAnim)>,
 }
 
-/// One render batch of a loaded model (an M2 batch or a WMO group batch): the decoded geometry,
-/// the batch's albedo texture (WorldArt), and its blend/sidedness. Carries data + metadata only —
-/// **no `Mesh` assets** (decision 0834, the model-lane twin of 0832's terrain rule): a labeled
-/// mesh sub-asset lands the instant the decode completes and the render world ingests the whole
-/// model in ONE frame, which is the city first-contact spike. The app builds each batch's render
-/// form paced (`benilla`'s `model_forms`) via [`submesh_to_static_mesh`] /
-/// [`submesh_to_skinned_mesh`]; the material stays a spawn-site concern as before.
+/// One render batch of an M2 or a WMO group: decoded geometry, texture and draw state, but no
+/// `Mesh` asset, since a labeled mesh sub-asset uploads the whole model in one frame. The app
+/// builds meshes paced, through [`submesh_to_static_mesh`] and [`submesh_to_skinned_mesh`].
 #[derive(Clone)]
 pub struct ModelSubmesh {
-    /// The batch's decoded geometry (model space, WoW axes) — everything the mesh builders below
-    /// need, shared across every instance of the model. `Arc` keeps the submesh clone cheap and is
-    /// the model's single resident CPU copy of the vertex data (the static render form is
-    /// GPU-only; see [`submesh_to_static_mesh`]).
+    /// The decoded geometry in WoW model space, the model's one resident CPU copy of its vertices.
     pub geometry: std::sync::Arc<RenderSubmesh>,
-    /// Embedded albedo texture, if any. `None` for creature skin slots (filled at spawn from the
-    /// display's skin variation — see [`Self::skin_slot`]).
+    /// The embedded albedo texture; `None` for a creature skin slot, filled at spawn.
     pub texture: Option<Handle<Image>>,
-    /// The creature skin variation this batch draws from (`Some(0/1/2)` ⇒ `Monster1/2/3`) when its
-    /// [`Self::texture`] is `None` — so the entity spawn site can fill it from `CreatureDisplayInfo`.
-    /// `None` for batches with their own embedded texture (all doodads/WMOs; most M2 batches).
+    /// The creature skin variation this batch draws from (`0/1/2` for `Monster1/2/3`).
     pub skin_slot: Option<u8>,
-    /// The batch's `skinSectionId` (geoset / mesh-part ID, see
-    /// [`benilla_formats::RenderSubmesh::geoset_id`]) — `group*100 + variant`. The character compositor
-    /// selects which geosets a player shows by this; `0` for a single-geoset model (creatures/doodads).
+    /// The geoset id, `group * 100 + variant`, by which the character compositor picks parts.
     pub geoset_id: u16,
-    /// The character runtime texture slot this batch carries (see
-    /// [`benilla_formats::RenderSubmesh::char_slot`]) — the spawn site fills its texture per-player from
-    /// the appearance (decisions 0041 / 0044 / 0045). `None` for everything with its own texture.
+    /// The character texture slot the spawn site fills from the player's appearance.
     pub char_slot: Option<CharSkinSlot>,
     pub blend: ModelBlend,
     pub two_sided: bool,
-    /// This batch is a WMO **interior** group (see [`benilla_formats::RenderSubmesh::interior`]) — lit
-    /// by its baked MOCV with the directional sun off. `false` for M2 doodads and exterior WMO groups.
+    /// A WMO interior group's batch, lit by its baked MOCV with the sun off.
     pub interior: bool,
-    /// This batch is unlit (see [`benilla_formats::RenderSubmesh::emissive`]) — rendered fullbright:
-    /// M2 `UNLIT (0x01)` glass/glow, or WMO `UNLIT` on an exterior-group batch. `false` otherwise.
+    /// Unlit, drawn fullbright: M2 render flag `UNLIT` (0x01), or WMO `UNLIT` on an exterior group.
     pub emissive: bool,
-    /// This batch's texture is the **icon slot** (M2 texture type 14, see
-    /// [`benilla_formats::RenderSubmesh::icon_slot`]): the spawn site fills it from
-    /// `Model:ReplaceIconTexture`'s path. `false` for every other batch and all of WMO.
+    /// The icon slot (M2 texture type 14), filled from `Model:ReplaceIconTexture`'s path.
     pub icon_slot: bool,
-    /// The WMO MOMT **SIDN** night-glow colour (see [`benilla_formats::RenderSubmesh::sidn`]) — the
-    /// authored emissive RGB the shader ramps by the night fraction on lit lanes. `None` for M2.
+    /// The WMO MOMT SIDN night-glow colour, ramped by the night fraction.
     pub sidn: Option<[u8; 3]>,
-    /// WMO MOMT **WINDOW** (see [`benilla_formats::RenderSubmesh::window`]) — an interior-group
-    /// batch takes the brighter Direct/Ambient-midpoint light. `false` for M2.
+    /// WMO MOMT WINDOW: an interior batch lit by the Direct/Ambient midpoint.
     pub window: bool,
-    /// This batch blends **additively** (M2 glow cards / coronae — see
-    /// [`benilla_formats::RenderSubmesh::additive`]): the spawn site builds it with `AlphaMode::Add` so
-    /// its warm colour is added on top of the scene, not mixed with the background. `false` otherwise.
+    /// Blends additively (M2 glow cards and coronae).
     pub additive: bool,
-    /// This batch's texture coordinates are **generated, not authored** (see
-    /// [`benilla_formats::RenderSubmesh::env_map`]): a sphere-map environment coordinate off the
-    /// view-space reflection vector. The spawn site marks the material so `wow_model.wgsl` derives
-    /// the UV instead of reading the (meaningless) vertex one. `false` for WMO batches and for the
-    /// M2 batches that name a real UV channel.
+    /// Sphere-mapped: `wow_model.wgsl` derives the UV from the view-space reflection.
     pub env_map: bool,
-    /// M2 render flag **0x10 — disable depth write** (see [`benilla_formats::RenderSubmesh::no_depth_write`]):
-    /// `specialize` keeps depth-write ON for transparent batches *unless* this is set, matching the real
-    /// client (so a model's transparent cards occlude each other instead of bleeding through). `false` for WMO.
+    /// M2 render flag 0x10; unset, a transparent batch writes depth, as in the reference.
     pub no_depth_write: bool,
-    /// M2 render flag **0x08 — disable depth test** (drawn over everything). `false` for WMO.
+    /// M2 render flag 0x08: no depth test.
     pub no_depth_test: bool,
-    /// The batch's fog COLOUR policy (see [`benilla_formats::RenderSubmesh::fog_policy`]) — `Scene`
-    /// for WMO and every non-M2 batch.
+    /// The batch's fog colour policy; `Scene` for WMO.
     pub fog_policy: benilla_formats::FogPolicy,
-    /// Set when this batch rides an M2 billboard bone (glow cards, chains): the spawn site faces it to
-    /// the camera each frame. The [`Self::mesh`] is built centred at the pivot so it rotates in place.
+    /// Set when the batch rides an M2 billboard bone; its mesh is built centred on the pivot.
     pub billboard: Option<BillboardInfo>,
-    /// The batch's **animated material alpha** (decision 0130 phase 2, wow-re `m2-alpha-combine-cull`):
-    /// time-varying colour-alpha/transparency-weight loops (or a dimming constant) the doodad spawn
-    /// site samples per instance into the render-alpha channel. `None` for the overwhelming majority
-    /// (both factors static-1 or statically culled). `Arc` keeps the submesh clone cheap.
+    /// The animated material alpha, colour alpha times transparency weight (`0x707680`).
     pub alpha_anim: Option<std::sync::Arc<benilla_formats::AlphaAnim>>,
-    /// The batch's **UV-animation** loop (decision 0130 phase 3, wow-re `m2-texanim-uv`): the
-    /// texture transform's translation track — sampled per frame into the batch material's UV
-    /// offset (flowing waterfalls, scrolling energy). `None` for the ~98.6% of models with no
-    /// texture transform and all WMO batches. The `Arc` doubles as the material-dedup identity:
-    /// every instance of a loaded model shares this allocation.
+    /// The texture transform's translation loop (sampled at `0x714260`, applied at `0x70b740`).
+    /// The `Arc` is also the material-dedup identity, shared by every instance.
     pub uv_anim: Option<std::sync::Arc<benilla_formats::UvAnim>>,
-    /// The batch's UV loop **per file sequence slot**, `Some` only where the slots disagree — the
-    /// batches for which [`Self::uv_anim`]'s single loop is structurally unable to be right,
-    /// because which loop applies depends on the sequence the *instance* is playing (decision
-    /// 1408). Like [`Self::uv_anim`], the `Arc` doubles as a material-dedup identity.
+    /// The UV loop per file sequence slot, `Some` only where slots disagree; also a dedup identity.
     pub uv_seq: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 2]>>>,
-    /// The batch's texture-transform **rotation** loop per file sequence slot (decision 2019)
-    /// — the UI model tiles sample it off the pane's play head into the material's affine row;
-    /// no world lane reads it (no placed doodad authors one). `None` for the rest.
+    /// The texture-transform rotation loop per file sequence slot, read only by the UI model tiles.
     pub uv_rot_seq: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 4]>>>,
-    /// The scaling twin of [`Self::uv_rot_seq`].
+    /// The scale loop per file sequence slot, likewise.
     pub uv_scale_seq: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 2]>>>,
-    /// The batch's **animated RGB tint** (the M2Color colour track, time-varying only — a spell
-    /// effect's white-hot flash cooling to red). When `Some`, the static vertex tint was skipped
-    /// at parse (`benilla-formats`): the render side seeds the material's tint at the first key —
-    /// pixel-identical to the old static bake — and the material-animating lanes tick it per
-    /// frame. `None` for constant/keyless tints (the vertex bake).
+    /// The time-varying M2Color tint; when `Some`, the material carries it, not the vertex colour.
     pub rgb_anim: Option<std::sync::Arc<benilla_formats::RgbAnim>>,
-    /// The tint twin of [`Self::uv_seq`], on the same rule.
+    /// The tint loop per file sequence slot, on [`Self::uv_seq`]'s rule.
     pub rgb_seq: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 3]>>>,
-    /// The batch's MOBA section for WMO group batches ([`benilla_formats::WmoBatchClass`] — an
-    /// interior group's per-batch lighting law: INT = unlit `tex × MOCV`, TRANS = the MOCV-alpha
-    /// lit↔bake lerp, EXT = the exterior day/night law). `None` for every M2 batch.
+    /// The WMO batch's MOBA section, which picks an interior batch's lighting (INT, TRANS, EXT).
     pub wmo_batch: Option<benilla_formats::WmoBatchClass>,
-    /// The batch's flat **ground-plane quad** shape ([`benilla_formats::GroundQuad`], detected at
-    /// load — corners stay in WoW model space; consumers map through `coords::wow_to_bevy`). The
-    /// ground-fx decal lane (`benilla::ground_fx`) re-renders such parts of a base-anchored spell
-    /// effect as projected surface decals. `None` for ordinary geometry and all WMO batches.
+    /// A flat ground quad (WoW model space), which the ground-fx lane redraws as a projected decal.
     pub ground_quad: Option<benilla_formats::GroundQuad>,
 }
 
-/// Turn a [`RenderSubmesh`] (model space) into a Bevy [`Mesh`] baked to Bevy space — decision 0002,
-/// applied here at the render boundary. Prefers the authored normals (soft, outward — how WoW lights
-/// foliage); recomputes flat ones only when absent. WMO per-vertex MOCV colour is folded in when
-/// present (M2 has none). The WoW→Bevy map is a pure rotation, so it applies to normals too.
-///
-/// `usages` is the caller's lane split (decision 0834): the **static** form is `RENDER_WORLD`-only
-/// (nothing reads it main-side; the render world takes the buffers at extract, no resident CPU
-/// copy), while the **skinned** twin keeps the default `MAIN_WORLD | RENDER_WORLD` because the
-/// mouseover picker rays its vertices on the main world (`target::hover::ray_posed_mesh`).
+/// Bake a [`RenderSubmesh`] to a Bevy-space [`Mesh`]: authored normals, else flat ones.
 fn build_submesh_mesh(sub: &RenderSubmesh, usages: RenderAssetUsages) -> Mesh {
-    // A billboard batch is built centred at its bone pivot, so the spawn site can rotate it about that
-    // point to face the camera (the entity transform then re-places it at the pivot in the world).
+    // A billboard batch is centred on its bone pivot, so the spawn site turns it in place.
     let center = sub
         .billboard
         .as_ref()
@@ -186,15 +114,9 @@ fn build_submesh_mesh(sub: &RenderSubmesh, usages: RenderAssetUsages) -> Mesh {
         mesh.insert_attribute(Mesh::ATTRIBUTE_COLOR, sub.vertex_colors.clone());
     }
     if sub.normals.len() == sub.positions.len() {
-        // A billboard CARD is lit on the face it PRESENTS (decision 0788): a card authored
-        // back-to-front against the law's `+X`-at-the-viewer gets its plane's normals turned round
-        // here, so its shading stops swinging with the camera (the shape, the reference's own
-        // behaviour and the 279-batch population are on
-        // [`RenderSubmesh::billboard_card_faces_away`]).
-        //
-        // **Normals only — never the winding.** The 177 away-facing SINGLE-sided cards are
-        // authored placeholder geometry the reference backface-culls from every angle
-        // (`bbfacescan`), and our `cull_mode` reproduces that; re-winding them would reveal it.
+        // A card authored facing away from the viewer is lit on the face it presents, so flip its
+        // normals, never its winding: the reference culls the single-sided ones from every angle,
+        // and re-winding would show them.
         let flip = sub.billboard_card_faces_away();
         let normals: Vec<[f32; 3]> = sub
             .normals
@@ -211,22 +133,16 @@ fn build_submesh_mesh(sub: &RenderSubmesh, usages: RenderAssetUsages) -> Mesh {
     mesh
 }
 
-/// The skinned twin's per-vertex joint indices (`Uint16x4` — M2 bone indices, used directly as
-/// palette indices). **Deliberately NOT `Mesh::ATTRIBUTE_JOINT_INDEX`** (decision 0720): Bevy's
-/// `SKINNED` pipeline path triggers on the standard attributes being in the mesh LAYOUT — while
-/// its draw-time skin bind group resolves per ENTITY registration — so a mesh carrying them can
-/// only ever render through Bevy's skin lane. Our own attribute ids keep Bevy's `is_skinned()`
-/// false everywhere; `WowModelExt::specialize` sees them in the layout and compiles the
-/// `WOW_RIG_SKIN` path instead, which skins from the owned palette region of the shared light
-/// buffer (`rig_palette`). Shader locations 10/11 (Bevy's builtin set ends at 7).
+/// The skinned mesh's per-vertex M2 bone indices, at shader location 10. Not Bevy's
+/// `ATTRIBUTE_JOINT_INDEX`, whose presence in a layout forces Bevy's own skinning: this id makes
+/// `WowModelExt::specialize` compile the `WOW_RIG_SKIN` path, which reads our own palette.
 pub const ATTRIBUTE_WOW_JOINT_INDEX: bevy::mesh::MeshVertexAttribute =
     bevy::mesh::MeshVertexAttribute::new(
         "Wow_JointIndex",
         988_540_917,
         bevy::render::render_resource::VertexFormat::Uint16x4,
     );
-/// The skinned twin's per-vertex joint weights (`Float32x4`, normalised) — see
-/// [`ATTRIBUTE_WOW_JOINT_INDEX`].
+/// The skinned mesh's per-vertex joint weights, normalized, at shader location 11.
 pub const ATTRIBUTE_WOW_JOINT_WEIGHT: bevy::mesh::MeshVertexAttribute =
     bevy::mesh::MeshVertexAttribute::new(
         "Wow_JointWeight",
@@ -234,11 +150,8 @@ pub const ATTRIBUTE_WOW_JOINT_WEIGHT: bevy::mesh::MeshVertexAttribute =
         bevy::render::render_resource::VertexFormat::Float32x4,
     );
 
-/// A merged fader blob's per-vertex fade sphere (`center.xyz` world-space, `w` = fade radius —
-/// decision 1418): every vertex of one baked placement carries the placement's sphere, and
-/// `wow_model.wgsl` computes the faithful `doodad_fade_alpha` from it per vertex (the erode
-/// lane), replacing the per-entity MeshTag/twin/Hidden fade channels a merged draw cannot
-/// express. Own attribute id for the same reason as the joints above; shader location 12.
+/// A merged blob's per-vertex fade sphere (world centre, fade radius), the same on every vertex
+/// of one placement, from which `wow_model.wgsl` fades each placement. Shader location 12.
 pub const ATTRIBUTE_WOW_FADE_SPHERE: bevy::mesh::MeshVertexAttribute =
     bevy::mesh::MeshVertexAttribute::new(
         "Wow_FadeSphere",
@@ -246,10 +159,8 @@ pub const ATTRIBUTE_WOW_FADE_SPHERE: bevy::mesh::MeshVertexAttribute =
         bevy::render::render_resource::VertexFormat::Float32x4,
     );
 
-/// A merged interior-prop blob's per-vertex SH-probe slot (decision 1418 lane 3): the slot
-/// index every vertex of one baked placement carries, replacing the per-entity `MeshTag`
-/// payload (`wow_model.wgsl`'s `WOW_MERGED_SLOT` reads it instead of the tag bits). Shader
-/// location 13.
+/// A merged interior-prop blob's per-vertex SH-probe slot, in place of the `MeshTag` payload.
+/// Shader location 13.
 pub const ATTRIBUTE_WOW_MERGED_SLOT: bevy::mesh::MeshVertexAttribute =
     bevy::mesh::MeshVertexAttribute::new(
         "Wow_MergedSlot",
@@ -257,22 +168,14 @@ pub const ATTRIBUTE_WOW_MERGED_SLOT: bevy::mesh::MeshVertexAttribute =
         bevy::render::render_resource::VertexFormat::Uint32,
     );
 
-/// The app-facing **static** mesh build (decision 0834): geometry only, `RENDER_WORLD`-only
-/// usages — the render world takes the vertex buffers at extract and the main world keeps no
-/// copy. Consumers must pair it with an explicit `Aabb` computed at build time (the exterior
-/// cull fails OPEN on a missing bound, and `RENDER_WORLD` races Bevy's `calculate_bounds` —
-/// the same rule 0832 set for terrain cells).
+/// The static mesh, render-world only. Pair it with an explicit `Aabb`: a render-world mesh races
+/// Bevy's `calculate_bounds`, and the exterior cull draws a mesh that has no bound.
 pub fn submesh_to_static_mesh(sub: &RenderSubmesh) -> Mesh {
     build_submesh_mesh(sub, RenderAssetUsages::RENDER_WORLD)
 }
 
-/// Build the **skinned** twin of [`submesh_to_static_mesh`]: the same baked geometry plus the
-/// per-vertex [`ATTRIBUTE_WOW_JOINT_INDEX`] + [`ATTRIBUTE_WOW_JOINT_WEIGHT`]. These two
-/// attributes are the entire trigger for the owned-palette skinning path (decisions 0019/0720).
-/// When the submesh carries no skin (WMO / a boneless batch) this is identical to the static
-/// mesh — harmless, but the rigged paths are the only consumers regardless. Keeps the default
-/// `MAIN_WORLD | RENDER_WORLD` usages: the mouseover picker skins these vertices on the CPU
-/// (`target::hover`), so the main-world copy is read, not waste.
+/// The skinned mesh: the static one plus the joint attributes. It keeps its main-world copy,
+/// which the mouseover picker (`target::hover`) skins on the CPU.
 pub fn submesh_to_skinned_mesh(sub: &RenderSubmesh) -> Mesh {
     let mut mesh = build_submesh_mesh(sub, RenderAssetUsages::default());
     if sub.joints.len() == sub.positions.len() && !sub.joints.is_empty() {
@@ -288,58 +191,36 @@ pub fn submesh_to_skinned_mesh(sub: &RenderSubmesh) -> Mesh {
     mesh
 }
 
-/// One joint of a model's rest skeleton, baked to Bevy space (decision 0019): its parent joint index
-/// (`-1` = root → parented to the entity) and its **local** rest translation. The skinned creature
-/// path spawns one entity per joint carrying this translation; animation later drives each joint's TRS.
+/// One rest-skeleton joint in Bevy space: its parent (`-1` for the root) and local translation.
 #[derive(Clone, Copy)]
 pub struct ModelJoint {
     pub parent: i16,
     pub local_translation: Vec3,
-    /// The bone's billboard arm, if authored (M2 bone flags `0x08/0x10/0x20/0x40`). The byte law
-    /// replaces the billboarded bone's rotation IN THE PALETTE, so children — and any geometry
-    /// skinned to them — inherit the camera facing (the frost-armor sheets skin to the scale-in
-    /// CHILD of a lock-Z bone). Rigged hosts feed this to the billboard joint pass; the per-batch
-    /// card split only covers geometry skinned to the billboard bone itself.
-    ///
-    /// Authored on every bone that carries the flag, welded seam or not: `m2_animate` reads no
-    /// vertex, weight or triangle data at all, so there is no topology gate on the arm (decision
-    /// 0945 superseding 0935). A welded seam stays welded because the replacement is built about
-    /// the bone's own pivot, which is what makes the blended seam ring move by millimetres.
+    /// The bone's billboard arm (bone flags 0x08/0x10/0x20/0x40). The reference replaces the
+    /// bone's rotation in the palette, so its children inherit the facing, and arms every flagged
+    /// bone: the animate kernel `0x714260` reads no vertex data, so a welded seam is no gate. The
+    /// seam holds because the replacement is built about the bone's own pivot.
     pub billboard: Option<benilla_formats::BillboardKind>,
-    /// Bone flags `0x1/0x2/0x4` (see [`benilla_formats::SkeletonBone::parent_arm`]): how the
-    /// bone's effective PARENT matrix is rebuilt from the model's own root frame before it
-    /// composes. Applied by the same palette passes as `billboard`, and *before* them.
+    /// Bone flags 0x1/0x2/0x4: how the parent matrix is rebuilt from the model's root frame,
+    /// applied before the billboard arm.
     pub parent_arm: Option<benilla_formats::ParentArm>,
 }
 
-/// A model's rest skeleton in Bevy space (decision 0019). Built once per M2 asset; the creature path
-/// spawns a joint-entity hierarchy per instance from `joints` and shares the matching inverse bind
-/// poses ([`build_skeleton`]'s second return) across instances.
+/// A model's rest skeleton in Bevy space, shared by every instance.
 #[derive(Clone, Default)]
 pub struct ModelSkeleton {
     pub joints: Vec<ModelJoint>,
-    /// The bone whose `KeyBoneID == 4` (SpineLow) — the client's display-facing counter-twist spine
-    /// channel (`0x711f10(4, …)` in the `0x607ed0` body-facing tail): while a unit's rendered root
-    /// yaw is offset from its aim (a strafe), this subtree counter-rotates back toward the aim.
-    /// `None` when the model lacks the key-bone (beasts, props).
+    /// The KeyBoneID 4 (SpineLow) bone, which counter-twists toward the aim while the body's yaw
+    /// is off it, as in a strafe (`0x711f10(4, …)` in `0x607ed0`).
     pub spine_bone: Option<u16>,
-    /// The bone whose `KeyBoneID == 6` (Head) — the twist's head channel (`0x711f10(6, …)`), taking
-    /// the gap the spine channel leaves so the head lands back on the aim. `None` when absent.
+    /// The KeyBoneID 6 (Head) bone, which takes the rest of that twist (`0x711f10(6, …)`).
     pub head_bone: Option<u16>,
 }
 
-/// Bake a raw [`Skeleton`] into the Bevy-space [`ModelSkeleton`] + its inverse-bind-pose matrices.
-///
-/// Verified rig math (wow-5875-re: vanilla M2 has no inverse-bind array, rest pose is identity TRS,
-/// the **pivot encodes bind position**) composed with Bevy's joint formula
-/// (`joint_matrix = joint_global · inverse_bindpose`, which *becomes* `world_from_local`):
-/// - **inverse bind pose** `i = translate(−pivot_i)` (model→bone-local at bind),
-/// - **joint rest-local translation** = `pivot_i − pivot_parent` (pure translations, so they telescope
-///   to `pivot_i` up the chain). At rest every joint matrix collapses to the entity transform, so the
-///   creature renders exactly where the static mesh did, undeformed — even with a scaled entity
-///   transform (the two pivot translations cancel before scale acts).
-///
-/// Pivots map WoW→Bevy via [`wow_to_bevy`] (a pure rotation), so the whole skeleton lives in mesh space.
+/// Bake a [`Skeleton`] to Bevy space, with its inverse bind poses. A vanilla M2 has no
+/// inverse-bind array and an identity rest pose, and a bone's pivot is its bind position, so the
+/// inverse bind pose is `translate(−pivot)` and a joint's rest translation `pivot − parent pivot`:
+/// at rest every joint matrix is the entity transform.
 pub(crate) fn build_skeleton(skel: &Skeleton) -> (ModelSkeleton, Vec<Mat4>) {
     let pivots = skeleton_pivots(skel);
     let joints = skel
@@ -360,8 +241,7 @@ pub(crate) fn build_skeleton(skel: &Skeleton) -> (ModelSkeleton, Vec<Mat4>) {
         })
         .collect();
     let inverse_bindposes = pivots.iter().map(|p| Mat4::from_translation(-*p)).collect();
-    // A bone carries KeyBoneID `k` iff `keyBoneLookup[k]` points at it (same rule as
-    // [`upper_subtree_root`]); 4 = SpineLow, 6 = Head — the display-facing twist channels.
+    // A bone carries KeyBoneID `k` iff `keyBoneLookup[k]` points at it.
     let key_bone = |k: i16| {
         skel.bones
             .iter()
@@ -378,18 +258,13 @@ pub(crate) fn build_skeleton(skel: &Skeleton) -> (ModelSkeleton, Vec<Mat4>) {
     )
 }
 
-/// Each bone's Bevy-space bind-pose pivot (`wow_to_bevy(bone.pivot)`), in file order — the one
-/// source [`build_skeleton`] (inverse bind poses) and [`build_attachments`] (attach-point offsets)
-/// both derive from, so the two never compute a divergent pivot.
+/// Each bone's Bevy-space pivot, the one source for the joints and the attachment offsets.
 pub(crate) fn skeleton_pivots(skel: &Skeleton) -> Vec<Vec3> {
     skel.bones.iter().map(|b| wow_to_bevy(b.pivot)).collect()
 }
 
-/// One M2 attachment point (decision 0072 — held items), baked to a **Bevy-space bone-local
-/// offset**: a child spawned under the bone's joint entity at `Transform::from_translation(offset)`
-/// sits exactly at the attach point at bind pose and rides the bone's animation thereafter.
-/// `offset` is `≈ Vec3::ZERO` on character models (the attach bones are leaves sitting exactly at
-/// the attach point — VERIFIED, direct dump of `HumanMale.m2`, `decisions/0072`).
+/// One M2 attachment point as an offset from its bone's pivot, Bevy space; about zero on
+/// character models, whose attach bones sit on the point.
 #[derive(Clone, Copy)]
 pub struct ModelAttachment {
     pub id: u16,
@@ -397,11 +272,8 @@ pub struct ModelAttachment {
     pub offset: Vec3,
 }
 
-/// The right/left **arm subtree roots** for the per-arm animation masks: each hand attachment's
-/// (id 1 = right, id 2 = left) bone walked up to its shoulder-keybone ancestor (keybones 2/3 —
-/// either; the walk just finds "the shoulder above this hand", so no left/right convention is
-/// assumed). `None` when the model lacks either hand attachment or a shoulder ancestor (beasts,
-/// props — they never play per-slot one-shots).
+/// The right and left arm subtree roots: each hand attachment's bone (1 right, 2 left) walked up
+/// to its shoulder key-bone (2 or 3).
 pub(crate) fn arm_subtree_roots(
     skel: &Skeleton,
     attachments: &[ModelAttachment],
@@ -422,26 +294,17 @@ pub(crate) fn arm_subtree_roots(
     Some((shoulder_of(1)?, shoulder_of(2)?))
 }
 
-/// The model's **upper-body split key-bone** subtree root — the client's `CGUnit+0xd5c`, selected by
-/// the capability probe `0x60ce70` (`keyBoneLookup[4]` preferred, `[6]` fallback, else the −1
-/// sentinel = no split). On HumanMale `keyBoneLookup[4]` is bone 20 (SpineLow: chest/shoulders/arms/
-/// hands/head — a subtree that provably **excludes** the legs, which hang off the pelvis sibling
-/// bone 21), so a clip masked to this subtree moves the upper body only (wow-re
-/// `anim-composition-model.md` §1, `923ac7bc`). A bone carries KeyBoneID `k` iff `keyBoneLookup[k]`
-/// points at it, so the SpineLow bone is the one whose `key_bone == 4` (else `== 6`). `None` when the
-/// model has neither (the −1 sentinel) — the one-shot route then falls back to full-body.
+/// The upper-body subtree root, the reference's `CGUnit+0xd5c` from the probe `0x60ce70`:
+/// key-bone 4 (SpineLow), else 6 (Head). SpineLow's subtree leaves out the legs, which hang off
+/// the pelvis. `None` means no split, and a one-shot plays full-body.
 pub(crate) fn upper_subtree_root(skel: &Skeleton) -> Option<usize> {
     let bone_with = |k: i16| skel.bones.iter().position(|b| b.key_bone == k);
     bone_with(4).or_else(|| bone_with(6))
 }
 
-/// The model's **finger key-bone subtree roots** per hand `(right, left)` — the client's `CloseHand`
-/// targets. WoW rigs each hand's fingers under **key-bones 8–12 (mainhand/right)** and **13–17 (offhand/
-/// left)**; the grip pose (`HandsClosed`, AnimationData 15) is armed on exactly these when a weapon is
-/// held in that hand (wow-re `hand-grip-mechanism.md`: `0x479660`/`0x60b590`). Only the *rigged* ones
-/// exist (HumanMale carries 11/12 and 16/17; the rest are the −1 sentinel), so each entry is the set of
-/// bones actually carrying a finger key-bone in that hand's range — **empty** for a model with no finger
-/// key-bones (beasts/props), which never grip.
+/// The finger key-bones per hand `(right, left)`, 8-12 and 13-17: the reference's `CloseHand`
+/// targets, posed with `HandsClosed` (AnimationData 15) while that hand holds a weapon
+/// (`0x479660`/`0x60b590`). Empty for a model without them.
 pub(crate) fn finger_subtree_roots(skel: &Skeleton) -> [Vec<usize>; 2] {
     let roots = |lo: i16, hi: i16| -> Vec<usize> {
         skel.bones
@@ -454,7 +317,7 @@ pub(crate) fn finger_subtree_roots(skel: &Skeleton) -> [Vec<usize>; 2] {
     [roots(8, 12), roots(13, 17)]
 }
 
-/// Whether bone `i` is `root` or one of its descendants (a parent-chain walk).
+/// Whether bone `i` is `root` or one of its descendants.
 pub(crate) fn in_subtree(skel: &Skeleton, i: usize, root: usize) -> bool {
     let mut cur = i;
     loop {
@@ -472,10 +335,7 @@ pub(crate) fn in_subtree(skel: &Skeleton, i: usize, root: usize) -> bool {
     }
 }
 
-/// Bake the raw [`M2Attachment`] table into [`ModelAttachment`]s: `offset = wow_to_bevy(position) −
-/// pivot_bevy(bone)`, the bone-local offset from the joint's bind position. Records whose `bone`
-/// indexes past `pivots` are dropped (defence in depth — `benilla-m2` already range-checks against
-/// its own bone array; this guards against the skeleton/attachment parses ever disagreeing).
+/// Bake the [`M2Attachment`] table to bone-local offsets, dropping a record with a bad bone.
 pub(crate) fn build_attachments(
     attachments: &[M2Attachment],
     pivots: &[Vec3],
@@ -493,11 +353,8 @@ pub(crate) fn build_attachments(
         .collect()
 }
 
-/// One M2 animation-event **positional marker**, baked exactly like [`ModelAttachment`] (same
-/// bone-local Bevy-space offset convention — a consumer transforms it by the bone joint's live
-/// global). The client's by-4CC position queries (`0x7130e0`/`0x7131b0`) read this table first
-/// match: the missile launch points `$CSL`/`$CSR`/`$CST` (casting hand) and `$BWR` (ranged
-/// release) are the consumers here.
+/// One animation-event position, baked like [`ModelAttachment`]. The reference's by-4CC queries
+/// (`0x7130e0`/`0x7131b0`) take the first match: `$CSL`/`$CSR`/`$CST` hands, `$BWR` ranged release.
 #[derive(Clone, Copy)]
 pub struct ModelMarker {
     /// The identifier 4CC, stored forward (`*b"$CSL"`).
@@ -506,10 +363,7 @@ pub struct ModelMarker {
     pub offset: Vec3,
 }
 
-/// Bake the raw [`benilla_formats::EventMarker`] table into [`ModelMarker`]s — the same
-/// `offset = wow_to_bevy(position) − pivot_bevy(bone)` bake and the same defence-in-depth bone
-/// range check as [`build_attachments`]. File order is preserved (queries take the first ident
-/// match, the client's scan order).
+/// Bake the event markers like [`build_attachments`], in file order: queries take the first match.
 pub(crate) fn build_markers(
     markers: &[benilla_formats::EventMarker],
     pivots: &[Vec3],
@@ -527,17 +381,12 @@ pub(crate) fn build_markers(
         .collect()
 }
 
-/// A stable [`AnimationTargetId`] for bone index `bone` (decision 0019). The idle clip's curves and the
-/// joint entities' target ids both derive from the bone index (via a synthetic name), so they match
-/// without a real `Name` hierarchy. Scoped to one creature's joints + its shared clip.
+/// A bone's stable [`AnimationTargetId`], shared by the clips' curves and the joint entities.
 pub fn bone_target_id(bone: u16) -> AnimationTargetId {
     AnimationTargetId::from_name(&Name::new(format!("benilla_bone_{bone}")))
 }
 
-/// The WoW→Bevy basis change as a quaternion. DR 0002's map is a proper rotation (det +1); a bone
-/// rotation track is a WoW-space quat, and a rotation transforms under a basis change by **conjugation**
-/// `r·q·r⁻¹`, so this `r` is what [`build_idle_clip`] conjugates each rotation keyframe by. Derived from
-/// `wow_to_bevy` itself (its images of the basis vectors are `R`'s columns) so it can't drift from it.
+/// The WoW-to-Bevy basis change as a quaternion `r`; a rotation key converts as `r·q·r⁻¹`.
 fn wow_to_bevy_quat() -> Quat {
     Quat::from_mat3(&Mat3::from_cols(
         wow_to_bevy([1.0, 0.0, 0.0]),
@@ -546,8 +395,7 @@ fn wow_to_bevy_quat() -> Quat {
     ))
 }
 
-/// Build a keyframe curve, handling Bevy's ≥2-sample requirement: a single key (a constant channel)
-/// becomes a flat curve spanning `[0, duration]`. `None` for no keys (the channel stays at rest).
+/// A keyframe curve; one key becomes a flat curve over `[0, duration]`, as Bevy needs two.
 fn keyframe_curve<T: Animatable + Clone>(
     duration: f32,
     keys: Vec<(f32, T)>,
@@ -563,23 +411,10 @@ fn keyframe_curve<T: Animatable + Clone>(
     }
 }
 
-/// Build one sequence's [`AnimationClip`] — **and its [`PoseClip`] twin** (decision 0712, one walk
-/// so the two cannot drift) — from parsed raw-WoW keyframes (decision 0019), transforming each
-/// channel into the joints' Bevy-space `Transform`:
-/// - **translation** = the bone's rest local (`pivot − pivot_parent`) **plus** `wow_to_bevy(track)` —
-///   the M2 translation track is a delta on the pivot offset;
-/// - **rotation** = the WoW quat conjugated into Bevy space (`r·q·r⁻¹`);
-/// - **scale** = the WoW scale with axes permuted to Bevy's (magnitudes; near-always uniform anyway).
-///
-/// Always returns a clip, and a flag for whether any channel produced a **curve**. A sequence
-/// whose bones all hold bind pose still gets one — an empty clip carrying the sequence's own
-/// duration — because the clip is not only a bone pose: it is this model's carrier for the
-/// instance's **sequence clock** (which slot is playing, and how far into it), which the emitter
-/// rate/params tracks, the material-alpha loops and the GameObject state arm all resolve through.
-/// Dropping the track-less ones left 807 corpus models — the ones whose animation is authored
-/// entirely in the *emitter* tracks — with no clock at all, frozen on slot 0 at t=0 for ever
-/// (decision 0941). The flag is what the doodad content gate reads instead (`poses_bones`): a clip
-/// with no curves can only ever render the bind-pose mesh, so it must not spawn a rig.
+/// Build one sequence's [`AnimationClip`] and its [`PoseClip`] in one walk. The M2 translation
+/// track is a delta on the rest offset, a rotation converts as `r·q·r⁻¹`, and scale permutes axes.
+/// A sequence that poses no bone still gets a clip of its own duration, since the clip is the
+/// instance's sequence clock; the flag says whether any channel made a curve for a rig to pose.
 pub(crate) fn build_animation_clip(
     anim: &ModelAnimation,
     skeleton: &ModelSkeleton,
@@ -646,19 +481,13 @@ pub(crate) fn build_animation_clip(
         });
     }
     if !any {
-        // Bevy derives a clip's duration from its curves; with none, the sequence's own band
-        // length is the clock's period — without it the player would wrap on a 0-second loop
-        // (a modulo by zero) and the clock would never leave t=0, which is the whole defect.
+        // Bevy takes a clip's duration from its curves; with none, the clock would never leave 0.
         clip.set_duration(anim.duration.max(1e-3));
     }
     (clip, pose, any)
 }
 
-/// Build the weapon-grip **overlay clip** from clamped finger poses ([`benilla_formats::hand_grip_finger_poses`]):
-/// a single constant rotation key per finger key-bone, conjugated into Bevy space with the same `r·q·r⁻¹`
-/// as [`build_animation_clip`]. Played masked to one hand's finger subtrees, it holds those fingers curled
-/// over the gait (rotation only — the fingers don't translate). Empty `poses` → an empty clip (the caller
-/// builds no grip node).
+/// The weapon-grip overlay: one constant rotation per finger bone, played masked to one hand.
 pub(crate) fn build_grip_clip(poses: &[(u16, [f32; 4])]) -> (AnimationClip, PoseClip) {
     let r = wow_to_bevy_quat();
     let mut clip = AnimationClip::default();
@@ -681,12 +510,7 @@ pub(crate) fn build_grip_clip(poses: &[(u16, [f32; 4])]) -> (AnimationClip, Pose
     (clip, pose)
 }
 
-/// The [`BillboardInfo`] for a submesh that rides a billboard bone (Bevy space): the pivot to rotate
-/// about. `None` for ordinary geometry. Pairs with [`build_submesh_mesh`], which centres the mesh.
-///
-/// It used to also derive the card's resting plane normal from its first triangle. Nothing has read
-/// that since the camera-basis law replaced the facet-normal card (0788's family), so it is deleted
-/// rather than left as a field that reads as load-bearing.
+/// The [`BillboardInfo`] of a submesh that rides a billboard bone, in Bevy space.
 pub(crate) fn billboard_info(sub: &RenderSubmesh) -> Option<BillboardInfo> {
     let bb = sub.billboard.as_ref()?;
     Some(BillboardInfo {
@@ -694,8 +518,7 @@ pub(crate) fn billboard_info(sub: &RenderSubmesh) -> Option<BillboardInfo> {
         bone: bb.bone,
         kind: bb.kind,
         scale_anim: bb.scale_anim.clone(),
-        // Translation values are model-space offsets — bake each key to Bevy axes here (scale keys
-        // above stay raw: per-axis factors, not vectors).
+        // Translation keys are vectors and take Bevy axes; the scale keys stay per-axis factors.
         seq_translations: bb
             .seq_translations
             .iter()
@@ -710,9 +533,7 @@ pub(crate) fn billboard_info(sub: &RenderSubmesh) -> Option<BillboardInfo> {
     })
 }
 
-/// A global-sequence bone channel baked to Bevy space: the free-clock loop the runtime samples at
-/// `(model_time mod period)` and writes onto the joint. `period` and key times are **seconds**; values
-/// are already in the joints' Bevy `Transform` frame. See [`GlobalBone`].
+/// A global-sequence bone channel in Bevy space, a free-running loop; times in seconds.
 #[derive(Clone)]
 pub struct GlobalSeqChannel<T> {
     pub period: f32,
@@ -720,8 +541,7 @@ pub struct GlobalSeqChannel<T> {
 }
 
 impl<T: Copy> GlobalSeqChannel<T> {
-    /// The two keys bracketing `t` (wrapped into `[0, period]`) and the fraction between them. Clamps to
-    /// the end keys (WoW authors the first/last key at the loop endpoints, so there is no wrap gap).
+    /// The keys around `t` mod the period, clamped at the end keys, which sit on the loop's ends.
     fn bracket(&self, t: f32) -> (T, T, f32) {
         let period = self.period.max(1e-3);
         let t = t.rem_euclid(period);
@@ -754,9 +574,7 @@ impl GlobalSeqChannel<Quat> {
     }
 }
 
-/// A bone's global-sequence channels baked to Bevy space (see [`GlobalSeqChannel`]) — any of
-/// translation / rotation / scale, each on its own free clock. The runtime writes only the driven
-/// components onto the bone's joint entity, leaving the rest to the playing animation.
+/// A bone's global-sequence channels; only the driven ones override the playing animation.
 #[derive(Clone)]
 pub struct GlobalBone {
     pub bone: u16,
@@ -765,10 +583,7 @@ pub struct GlobalBone {
     pub scale: Option<GlobalSeqChannel<Vec3>>,
 }
 
-/// Bake the raw [`benilla_formats::GlobalSeqBone`] channels into Bevy-space [`GlobalBone`]s, applying
-/// the same per-channel transforms as [`build_animation_clip`]: translation = the bone's rest-local
-/// (`pivot − pivot_parent`) plus `wow_to_bevy(track)`; rotation conjugated `r·q·r⁻¹`; scale axis-permuted
-/// to Bevy's. Times/periods convert ms → seconds.
+/// Bake the global-sequence channels with [`build_animation_clip`]'s transforms, ms to seconds.
 pub(crate) fn build_global_bones(
     gseq: &[benilla_formats::GlobalSeqBone],
     skeleton: &ModelSkeleton,
@@ -817,27 +632,12 @@ pub(crate) fn build_global_bones(
         .collect()
 }
 
-/// Build ONE mesh from many placed static submeshes — the transforms baked into the vertices
-/// (the production blob build, 1418; the retired `WOW_MEGA_STATIC` bracket's unfaded twin died
-/// with it): same attribute recipe as [`submesh_to_static_mesh`], concatenated, with each part's
-/// placement transform applied to positions and its rotation to normals (placements scale
-/// uniformly, so directions survive), plus the per-vertex [`ATTRIBUTE_WOW_FADE_SPHERE`] (one
-/// sphere per PART, replicated onto each of its vertices). `slots` (index-parallel with `parts`
-/// when `Some`) additionally bakes each part's SH-probe slot as [`ATTRIBUTE_WOW_MERGED_SLOT`] —
-/// the interior-prop lane. Parts lacking vertex colours pad white when any part has them — one
-/// attribute set must cover the whole concatenation.
-///
-/// **The mesh is recentred on its union-AABB centre** and that world centre is returned last:
-/// the caller places the entity AT the centre (`Transform::from_translation`), and the returned
-/// min/max are mesh-LOCAL for its `Aabb`. A world-baked mesh on `Transform::IDENTITY` sorts the
-/// entity at the WORLD ORIGIN in Bevy's transparent phase — ~9 400 yd out, drawn first among
-/// ALL transparent content with the twin's depth-write ON, so a feathering blob's translucent
-/// pixels depth-killed every transparent entity drawn after it (a per-entity fader behind a
-/// 20 %-alpha merged fence vanished outright, popping in only when the sightline cleared the
-/// segment — decision 1422). Centre-sort restores the same location-sort semantics every
-/// per-entity draw has (whose sort key is its placement origin). The fade spheres stay
-/// WORLD-space — the shader compares them against the camera, never against mesh-local
-/// positions — so the recentring does not touch them.
+/// One mesh from many placed static parts, transforms baked in (normals take only the rotation,
+/// as placements scale uniformly), each vertex carrying its part's fade sphere and, with `slots`,
+/// its SH-probe slot; missing normals and colours pad (up, white). Returns the mesh, its local
+/// bounds and its world centre, where the caller must place the entity: Bevy sorts transparent
+/// draws by entity origin, and a mesh left at the world origin draws first and depth-hides the
+/// transparent draws behind it. The fade spheres stay world-space.
 pub fn merged_static_mesh_faded(
     parts: &[(std::sync::Arc<RenderSubmesh>, Transform)],
     spheres: &[Vec4],
@@ -876,9 +676,6 @@ fn merged_static_mesh_impl(
                 normals.push(if flip { -b } else { b }.normalize_or_zero().to_array());
             }
         } else {
-            // The lone compute_normals fallback path never merges (its models are rare and the
-            // bracket tolerates flat shading there): pad up, face normals are close enough for a
-            // measurement build.
             normals.extend(std::iter::repeat_n([0.0, 1.0, 0.0], sub.positions.len()));
         }
         uvs.extend(sub.uvs.iter().copied());
@@ -923,10 +720,7 @@ fn merged_static_mesh_impl(
         }
     }
     mesh.insert_indices(Indices::U32(indices));
-    // Recentre on the union-AABB centre (see `merged_static_mesh`'s doc): positions become
-    // mesh-local, min/max follow, the centre goes back to the caller for the entity Transform.
-    // Guard the empty accumulation (no parts) — a MAX/MIN sentinel centre would explode.
-    // (`mn > mx` iff the vertex loop never ran; `positions` has been moved into the mesh.)
+    // Recentre on the union-AABB centre; with no vertices (`mn > mx`) the centre is the origin.
     let center = if mn.x > mx.x {
         Vec3::ZERO
     } else {
@@ -951,7 +745,7 @@ fn merged_static_mesh_impl(
 mod tests {
     use super::*;
 
-    /// One sequence record, `bones` supplied by the caller — everything else at a neutral value.
+    /// One sequence record with the given bones, the rest neutral.
     fn sequence(duration: f32, bones: Vec<benilla_formats::BoneKeys>) -> ModelAnimation {
         ModelAnimation {
             anim_id: 0,
@@ -974,13 +768,7 @@ mod tests {
         }
     }
 
-    /// A sequence whose bones hold bind pose still becomes a clip — an EMPTY one carrying the
-    /// sequence's own duration — because the clip is this model's carrier for the instance's
-    /// **sequence clock** (decision 0941). Dropping it left 807 corpus models whose animation is
-    /// authored purely in their emitter tracks with no clock at all: no player, so no slot and no
-    /// time, so every per-sequence track read file slot 0 at t = 0 for ever. The duration is the
-    /// load-bearing half — Bevy derives a clip's period from its curves, and a 0-second period
-    /// would wrap the player's `seek_time` by a modulo-zero and never leave t = 0.
+    /// A clip with no curves still carries its sequence's duration, or its clock never advances.
     #[test]
     fn a_boneless_sequence_still_yields_a_clock_clip() {
         let skeleton = ModelSkeleton {
@@ -996,7 +784,7 @@ mod tests {
             "the clock's period is the sequence's own band, not 0: {}",
             clip.duration()
         );
-        // The flag is what the doodad content gate reads: a clock-only clip must never spawn a rig.
+        // The flag gates the rig: a clock-only clip must never spawn one.
         let moving = benilla_formats::BoneKeys {
             bone: 0,
             translation: vec![(0.0, [0.0, 0.0, 0.0]), (0.5, [0.0, 0.0, 1.0])],
@@ -1007,9 +795,7 @@ mod tests {
         assert!(poses_bones, "a keyed track ⇒ a real pose");
     }
 
-    /// A [`GlobalSeqChannel`] samples with linear interpolation, clamps at the endpoint keys, and wraps
-    /// on its period — the eye-blink shape: `0` (open) held, a fast ramp to `1` (shut), back to `0`, and
-    /// the whole thing repeating every `period`. Models the real eyelid keys (ms → seconds).
+    /// The eye-blink shape from a real eyelid track: open, a fast ramp shut, open, repeating.
     #[test]
     fn global_seq_channel_samples_and_wraps() {
         let ch = GlobalSeqChannel {
@@ -1043,8 +829,6 @@ mod tests {
         );
     }
 
-    /// The WoW→Bevy rotation quat must reproduce `wow_to_bevy` on vectors — it's the same rotation, so
-    /// `r·v` equals the coordinate map. (Guards against `wow_to_bevy_quat` drifting from `wow_to_bevy`.)
     #[test]
     fn rotation_quat_matches_the_coordinate_map() {
         let r = wow_to_bevy_quat();
@@ -1058,9 +842,7 @@ mod tests {
         }
     }
 
-    /// A bone rotation about WoW **up** (+Z) must conjugate to a rotation about Bevy **up** (+Y) by the
-    /// same angle — the load-bearing check for the `r·q·r⁻¹` conjugation + the `[x,y,z,w]` quat order.
-    /// (A wrong conjugation/sign/order is exactly the "plausible but twisted creature" failure.)
+    /// Pins the conjugation and the `[x, y, z, w]` key order.
     #[test]
     fn wow_up_yaw_conjugates_to_bevy_up_yaw() {
         let r = wow_to_bevy_quat();
@@ -1077,7 +859,6 @@ mod tests {
         );
     }
 
-    /// Conjugating the identity rotation is the identity (a sanity floor for the conjugation).
     #[test]
     fn identity_rotation_conjugates_to_identity() {
         let r = wow_to_bevy_quat();
@@ -1085,21 +866,9 @@ mod tests {
         assert!(id.dot(Quat::IDENTITY).abs() > 0.9999, "got {id:?}");
     }
 
-    /// **A welded billboard bone still reaches the palette with its arm** (decision 0945,
-    /// superseding 0935's gate) — on the real shipped asset, the director's own pauldron.
-    ///
-    /// `LShoulder_Plate_PVPAlliance_A_01.m2` authors 3 bones: a plain root and two spherical
-    /// billboard spikes whose 8-vertex 50/50 seam rings stitch them to the body. 0935 dropped
-    /// their arm on exactly that welding. `m2_animate` reads no vertex, weight or triangle data at
-    /// all — over its whole extent there is a single `movzx byte ptr`, the arm-selector map — so
-    /// no such gate exists in the reference (wow-re `billboard-bone-law.md` §9.4 SQ1). The seam
-    /// survives because the replacement is built about the bone's own pivot, not because the arm
-    /// is skipped.
-    ///
-    /// The predicate itself is still live and still correct where it belongs: the per-batch **card
-    /// split** refuses to lift a welded bone's geometry into its own draw (0839). This test pins
-    /// that the two lanes now disagree *on purpose* — welded for the card split, faced by the
-    /// palette. Skips when the client isn't installed (the repo ships no assets).
+    /// The shipped pauldron `LShoulder_Plate_PVPAlliance_A_01.m2` welds two spherical billboard
+    /// bones to the body with 50/50 seam rings: the card split refuses to lift them, and the
+    /// palette faces them anyway, since `0x714260` reads no vertex data.
     #[test]
     fn a_welded_billboard_bone_still_reaches_the_palette_with_its_arm() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -1107,8 +876,7 @@ mod tests {
         let path = "Item\\ObjectComponents\\Shoulder\\LShoulder_Plate_PVPAlliance_A_01.m2";
         let bytes = chain.read_file(path).expect("read the pauldron");
         let raw = benilla_formats::parse_m2_skeleton(&bytes).expect("parse its skeleton");
-        // The asset really does author two spherical arms — otherwise this test would pass on a
-        // build that had simply stopped parsing bone flags.
+        // Two authored arms, so the test cannot pass on a build that stopped parsing bone flags.
         assert_eq!(
             raw.bones.iter().filter(|b| b.billboard.is_some()).count(),
             2,
@@ -1131,15 +899,9 @@ mod tests {
         );
     }
 
-    /// **The mount seat's parent arm survives the bake** — the load-bearing case, on the asset
-    /// that decides it.
-    ///
-    /// `RidingHorse.m2` attachment 0 (the rider seat) rides bone 30, `flags = 0x6` = ignore parent
-    /// rotation + scale. That is why a galloping horse never rocks its rider: the seat's basis is
-    /// replaced by the mount's own root basis before the rider's frame is built from it, so the
-    /// spine's ~21° stride swing is discarded at the saddle while the seat still *translates* with
-    /// it (wow-re §9.1/§9.2, byte-verified). Every vanilla player mount is `0x4`, `0x6`, or has a
-    /// seat whose ancestors don't rotate.
+    /// `RidingHorse.m2`'s rider seat (attachment 0) rides bone 30, flags 0x6: the mount's root
+    /// basis replaces the seat's, so the gallop's spine swing reaches the rider as translation
+    /// only (the copy-root leg `0x714a18`).
     #[test]
     fn the_riding_horse_seat_bone_carries_the_root_basis_arm() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -1163,7 +925,7 @@ mod tests {
             }),
             "the seat takes the mount's own root basis — the gallop reaches it as translation only"
         );
-        // The spine bones it hangs off carry no arm: they are what supplies the discarded swing.
+        // The spine bones above it carry no arm; they supply the swing.
         assert!(
             built.joints[23].parent_arm.is_none() && built.joints[25].parent_arm.is_none(),
             "the swinging spine bones are ordinary"
diff --git a/crates/benilla-assets/src/model/anims.rs b/crates/benilla-assets/src/model/anims.rs
index d76df5ad..3c2bd54a 100644
--- a/crates/benilla-assets/src/model/anims.rs
+++ b/crates/benilla-assets/src/model/anims.rs
@@ -1,240 +1,125 @@
-//! The playable-animation surface: the types + resolution logic the game queries at runtime
-//! ([`AnimClip`], [`ModelAnimations`], [`ResolvedAnim`], and `ModelAnimations`'s `find`/
-//! `pick_variation`/`resolve`) — kept separate from the bake-side builders in [`super`] (meshes,
-//! skeleton, attachments, masks/subtree helpers, grip poses, billboard info).
+//! A model's playable animations, and how a requested animation id resolves to one of them.
 
 use benilla_formats::AnimDataCatalog;
 pub use benilla_formats::PlayableAnim;
 use bevy::animation::graph::{AnimationGraph, AnimationNodeIndex};
 use bevy::prelude::*;
 
-/// One **event keyframe** on a clip — the baked twin of [`benilla_formats::AnimEvent`], exactly as
-/// [`super::ModelMarker`] is the baked twin of `EventMarker`, and carrying the same bone-local
-/// Bevy-space offset convention.
-///
-/// It carries **where** as well as **when**, because the reference's event kernel does: `0x719370`
-/// computes `placementMatrix · (boneMatrix[event.bone] · event.position)` and snapshots it by
-/// value into the deferred callback record every dispatcher reads (wow-re
-/// `spell/scratch/camera-shake-producers.md` §5). A consumer that plays at the model root is using
-/// the placement alone, which is the same point only where the record sits at the origin — and
-/// corpus-wide it does not: 149 of 244 `$DSL` records are off-origin, out to 67.6 yd
-/// (`Maraudon_Waterfall01.m2`), and every player model's six `$CSD` records ride the head
-/// (`benilla-extract eventmarkerscan`).
-///
-/// **Two points, because there are two cases and both are exact.** [`Self::offset`] is bone-local
-/// and wants the joint's live global ([`benilla_world::rig_anim::RigPose::posed_point`]);
-/// [`Self::point`] is the model-space rest position and wants the model's own world frame. The
-/// second is not an approximation of the first: with no keys a bone's matrix composes to the
-/// identity, so `placement · position` *is* the kernel's quantity — which is the whole placed-doodad
-/// population, where 0 of 244 `$DSL` records ride a bone any sequence keys.
+/// One event keyframe on a clip, with where as well as when: the reference's event kernel
+/// (`0x719370`) fires at `placement · boneMatrix[bone] · position`, and many records sit far from
+/// the model origin. [`Self::offset`] serves a posed joint, [`Self::point`] a bone chain that
+/// never moves; both are exact.
 #[derive(Debug, Clone, Copy)]
 pub struct ClipEvent {
     /// Seconds from the clip start.
     pub time: f32,
     /// The forward-stored 4CC (`*b"$SND"`).
     pub ident: [u8; 4],
-    /// The payload — a SoundEntries id for `$SND`/`$DSL`/`$DSO`, else 0.
+    /// The payload: a SoundEntries id for `$SND`/`$DSL`/`$DSO`, else 0.
     pub data: u32,
     /// The bone this record rides.
     pub bone: u16,
-    /// The authored point **relative to [`Self::bone`]'s pivot**, Bevy space — compose it with the
-    /// joint's live global.
+    /// The point relative to [`Self::bone`]'s pivot, Bevy space, for the joint's live global.
     pub offset: Vec3,
-    /// The authored point in the model's own space, Bevy space — compose it with the model's world
-    /// frame. Equals the kernel's quantity whenever the bone chain is unanimated.
+    /// The point in model space, Bevy axes, for the model's world frame when the chain is still.
     pub point: Vec3,
 }
 
-/// One animation in a model's [`ModelAnimations`] graph (decision 0019): its `AnimationData.dbc` id,
-/// the graph node an `AnimationPlayer` plays to run it, and whether it loops.
+/// One sequence in a model's [`ModelAnimations`] graph.
 #[derive(Clone)]
 pub struct AnimClip {
     pub anim_id: u16,
-    /// The sequence's **file slot** ([`benilla_formats::ModelAnimation::seq_index`]) — not this
-    /// clip's index in [`ModelAnimations::clips`]. The key into a batch's per-sequence
-    /// material-alpha loops (`benilla_formats::AlphaAnim::seq`), so the lane that knows which clip
-    /// a unit is playing can sample the batch visibility that sequence authored.
+    /// The file slot the per-sequence bakes key on, not the index in [`ModelAnimations::clips`].
     pub seq_index: usize,
     pub node: AnimationNodeIndex,
     pub looping: bool,
-    /// Clip length in seconds — used to seek a one-shot clip (Death) to its end pose, e.g. for a unit
-    /// that streamed in already dead so it shows the settled corpse instead of replaying the collapse.
+    /// Length in seconds; a unit streamed in dead seeks its one-shot to the end pose.
     pub duration: f32,
-    /// The sequence's authored design movement speed (`ModelAnimation::move_speed`, yd/s) — the
-    /// denominator the locomotion playback-rate scaler divides the unit's live speed by, so a fast
-    /// mover cycles its legs proportionally faster. `0.0` for a non-locomotion clip (left at rate 1×).
-    ///
-    /// **Signed, and the sign is load-bearing — never `abs()` it.** A backwards gait is authored
-    /// NEGATIVE (`RidingKodo.m2` seq 14, WalkBackwards: `-2.5`), and the client's rate guard is a
-    /// strict `divisor > 0` (`0x5fe2f0`, §5-verified — decisions 0903/0910/0912). So an authored
-    /// backwards clip plays at a flat 1×, while a model that has *no* WalkBackwards and falls back
-    /// to Walk (`+2.5`) gets speed-scaled. That asymmetry is the reference's behaviour; taking the
-    /// magnitude here — an inviting-looking tidy-up — inverts it on every model authoring a reverse
-    /// gait.
+    /// The authored gait speed (yd/s) the playback rate divides the live speed by; 0 if none.
+    /// Signed: a backwards gait is authored negative and the reference's guard is `divisor > 0`
+    /// (`0x5fe2f0`), so it plays at 1×. Never take `abs()`.
     pub move_speed: f32,
-    /// The sequence's blend-in time (`ModelAnimation::blend_time`, seconds) — the cross-fade duration the
-    /// spawn site uses when transitioning *into* this clip, so a gait change eases instead of snapping.
+    /// The cross-fade into this clip, in seconds.
     pub blend_time: f32,
-    /// The sequence's bounds-sphere centre, **Bevy model space** (the raw `M2Sequence` CAaBox centre
-    /// mapped like the mesh vertices, so it shares the rendered parts' frame). With
-    /// [`Self::bounds_radius`], the mouse-pick **broad phase**: the real client tests the cursor ray
-    /// against the *current* animation's sphere — world-placed + scaled, no pad — before the posed
-    /// per-triangle narrow test (wow-re pick-volume RE, `0x7089c0`).
+    /// The sequence's bounds-sphere centre, Bevy model space: the reference's mouse-pick broad
+    /// phase, ahead of the posed per-triangle test (`0x7089c0`).
     pub bounds_center: Vec3,
-    /// The sequence's bounds-sphere radius (model-local yards). `0.0` ⇒ unauthored (callers fall back).
+    /// The bounds-sphere radius in model-local yards; 0 when unauthored.
     pub bounds_radius: f32,
-    /// The sequence's CAaBox, **Bevy model space** (componentwise min/max of the WoW-space corners
-    /// mapped like the mesh vertices). The unit **blob shadow**'s projection box: the real client
-    /// sizes the shadow from the *current* animation's box — clamped into ±5 per axis, scaled by
-    /// the world matrix, yaw-rotated then axis-aligned (VERIFIED wow-5875-re `unit-blob-shadow.md`,
-    /// `0x711a20` + the `0x6d7920` corner build). `(Vec3::ZERO, Vec3::ZERO)` ⇒ unauthored.
+    /// The sequence's box, Bevy model space, which sizes the blob shadow: clamped to ±5 per axis,
+    /// scaled, yaw-rotated, then axis-aligned (`0x711a20`, corners at `0x6d7920`); zero when
+    /// unauthored.
     pub bounds_min: Vec3,
     pub bounds_max: Vec3,
-    /// The sequence's event keyframes (`$SND`/footsteps/`$CSS`… — decision 0070 slice 3), sorted by
-    /// time, seconds on the clip clock. Shared (`Arc`) so cloning a clip stays cheap; empty for the
-    /// overwhelming majority of sequences.
+    /// The sequence's event keyframes, by time on the clip clock.
     pub events: std::sync::Arc<[ClipEvent]>,
-    /// Per-arm masked variants `(right, left)` of this clip — graph nodes that animate **only** the
-    /// right/left arm subtree (shoulder keybone down), for the client's per-slot one-shots played
-    /// *over* the gait (the draw/stow: mainhand ceremony on the right arm, offhand on the left,
-    /// legs untouched). Built only for the sheath family (ids 89/90) on models whose hand
-    /// attachments + shoulder keybones resolve; `None` otherwise.
+    /// Right- and left-arm masked nodes for the sheath family (89/90), so a draw or stow plays
+    /// on one arm over the gait.
     pub arm_nodes: Option<(AnimationNodeIndex, AnimationNodeIndex)>,
-    /// The **upper-body masked variant** of this clip: a graph node that animates only the
-    /// SpineLow-subtree ([`upper_subtree_root`] — keyBoneLookup[4]/[6], the legs excluded), for the
-    /// one-shot route's masked destination (decision 0087 — a swing/emote played *over* a live base:
-    /// legs keep running/sitting/jumping while the torso swings or emotes). The general form of the
-    /// per-arm [`Self::arm_nodes`] ceremony machinery, one subtree wider. `None` for a model with no
-    /// split key-bone (the −1 sentinel) — the route falls back to full-body on the base node.
+    /// The upper-body masked node, so a swing or emote plays over the legs' own animation.
     pub upper_node: Option<AnimationNodeIndex>,
-    /// This variation's weight in the per-play roll (`M2Sequence.frequency` @+0x14): sequences
-    /// sharing an `anim_id` are **variations** (the alternating 1H swing arcs, the wound recoils),
-    /// and the real client picks one per one-shot play by a `_rand()`-weighted walk of the chain
-    /// (wow-re `anim-id-resolution.md`, op4 `0x71248a..`) — [`ModelAnimations::pick_variation`].
+    /// This variation's weight in the reference's per-play roll (`M2Sequence+0x14`, `0x71248a`).
     pub frequency: u16,
-    /// The sequence's `(minReplay, maxReplay)` range (`M2Sequence` +0x18/+0x1c): the client rolls a
-    /// play count `R = max(1, min + ((rand()·(max−min)) >> 15))` at every arm and multiplies it into
-    /// the play window (`windowHi = now + span·R`), so a clamp-flag one-shot runs `R` times before
-    /// freezing. Benilla expresses that as a `RepeatAnimation::Count(R)` on the one-shot play.
-    /// `(0, 0)` — the overwhelming majority — rolls to `R = 1`.
-    ///
-    /// **A loop-flag sequence does NOT ignore it** (this doc said so, sourced from
-    /// `loop-replay-fidget.md`'s unit-lane reading, and decision 0768 corrected it): the window still
-    /// governs, and for a *placed doodad* its expiry is what fires the re-arm that rolls a fresh
-    /// variation — `(0, 0)` ⇒ `R = 1` ⇒ a re-roll every single loop. That is the whole mechanism
-    /// behind the Blasted Lands lightning wandering instead of strobing from one fixed spot.
+    /// `(minReplay, maxReplay)` (`M2Sequence+0x18/+0x1c`): each arm rolls a play count `R` from
+    /// it, so a one-shot runs `R` times. A loop uses it too: a placed doodad re-rolls its
+    /// variation when the window expires, every loop for `(0, 0)`.
     pub replay: (u32, u32),
-    /// Whether this clip actually **poses bones** — some bone track produced a curve. `false` for a
-    /// sequence whose bones all hold bind pose: it still exists as a clip (playing it is how the
-    /// instance's sequence clock names a slot and advances a time, which the emitter tracks, the
-    /// material loops and the GameObject arm all read), but skinning to it can only ever reproduce
-    /// the static mesh. So a rig is spawned for a *posing* clip, never for a clock-only one —
-    /// decision 0941's split between the clock (free) and the rig (a palette slot, a skinned twin).
+    /// Whether a bone track made a curve; a clip that poses none is only a clock and gets no rig.
     pub poses_bones: bool,
 }
 
-/// A model's animations as a playable bundle (decision 0019): one shared `AnimationGraph` holding every
-/// sequence's clip, plus the per-sequence node/id/loop info. Built once per M2 asset and shared across
-/// instances; each creature instance drives this graph with its own `AnimationPlayer`. Also attached to
-/// the creature **as a component**, so the model bench can scrub `clips` and gameplay (Milestone C) can
-/// select by `AnimationData.dbc` id (Stand now, walk/run later) — both query it on the entity.
+/// A model's animations: one `AnimationGraph` shared by its instances, each with its own player.
 #[derive(Clone, Component)]
 pub struct ModelAnimations {
     pub graph: Handle<AnimationGraph>,
     pub clips: Vec<AnimClip>,
-    /// The **`HandsClosed` finger-grip masked nodes** `(right, left)` — graph nodes that animate only one
-    /// hand's finger key-bone subtrees ([`finger_subtree_roots`]) with the model's `HandsClosed`
-    /// (AnimationData 15) pose, played as a persistent weighted overlay over the gait while a weapon is
-    /// held in that hand (wow-re `hand-grip-mechanism.md`: the fingers curl for a held weapon; a
-    /// forearm-mounted shield or an empty hand stays open). `None` per hand for a model with no finger
-    /// key-bones or no `HandsClosed` clip (beasts, props — they never grip).
+    /// The `HandsClosed` grip nodes `(right, left)`, overlaid while that hand holds a weapon
+    /// (`0x479660`/`0x60b590`); an empty hand or a forearm shield stays open.
     pub hand_close: [Option<AnimationNodeIndex>; 2],
-    /// The model's baked **PlayableAnimationLookup** (decision 0082, M2 header `+0x2c/+0x30`, see
-    /// [`PlayableAnim`]): row `i` is the model's own precomputed substitute for requested
-    /// `AnimationData.dbc` id `i`. Empty for a model whose header carries no table (a boneless
-    /// doodad-shaped cube fallback, a malformed M2) — [`Self::resolve`] then degrades to identity.
+    /// The header's PlayableAnimationLookup (`+0x2c/+0x30`): row `i` substitutes for requested id
+    /// `i`. Empty without a table, and [`Self::resolve`] then returns the id itself.
     pub playable_animation_lookup: Vec<PlayableAnim>,
-    /// The model's **AnimationLookup** (M2 header `+0x24`/`+0x28`): `AnimationData.dbc` id → the
-    /// model's first sequence slot for it, `0xffff` where it authors none. Kept beside the playable
-    /// table because it is a *different question* — "does this model own id X at all", the
-    /// reference's `0x711960` — and the GameObject arm's missing-sequence remap branches on it four
-    /// times (wow-re `gameobject-anim-arm.md` §2c). See [`Self::owns`].
+    /// The header's AnimationLookup (`+0x24/+0x28`): each id's first slot, `0xffff` for none.
     pub animation_lookup: Vec<u16>,
-    /// The model's **global-sequence bone channels** baked to Bevy space (the eye-blink eyelid scale and
-    /// kin): free-clock loops the runtime samples independently of the playing animation and composes
-    /// over the sequence pose (see [`super::GlobalBone`]). Empty for a model with no global-sequence
-    /// tracks.
+    /// The global-sequence bone channels (an eyelid's blink), free-running over the sequence pose.
     pub global_bones: Vec<super::GlobalBone>,
-    /// Index into [`Self::clips`] of the model's **loader-idle seed** — the sequence the client's
-    /// M2-instance loader arms once at load and plays forever (wow-re `gameobject-anim-arm.md` §1,
-    /// byte-verified `0x71019b`): **animation id 0 ("Stand")**, resolved through the model's own
-    /// `playableAnimationLookup`. NOT the file-order-first sequence — an earlier reading of
-    /// `doodad-anim-host.md` said `animations[0].id`, and wow-re corrected it in place (0637).
-    /// The two coincide for almost every model and diverge exactly on one whose first sequence is
-    /// a Spawn: `DuelingFlag.m2` is Spawn/Stand/Despawn, and arming file-order-0 looped its Spawn
-    /// band, leaving the duel flag hanging 9 yards in the air on a 3.3 s cycle.
-    ///
-    /// `None` when the resolved idle leaves every bone at **bind pose** — looping that really does
-    /// render identically to the static mesh, so the spawn site skips the skin + player (the
-    /// content gate, decision 0130; the ~90% of placed doodads `doodadscan` measured). A *constant
-    /// but non-rest* pose does NOT qualify for that skip — see `m2::idle_pose_differs`.
+    /// Index into [`Self::clips`] of the loader-idle seed, the sequence the reference arms at load
+    /// (`0x71019b`): id 0 through the playable lookup, not the first file slot, which on
+    /// `DuelingFlag.m2` is Spawn. `None` when that idle is the rest pose and needs no rig.
     pub first_seq: Option<usize>,
-    /// The direct pose evaluator's baked data (decision 0712): the pose twin of every clip above,
-    /// the node → (clip, mask) table, and the per-bone mask bits — filled by the same code that
-    /// builds [`Self::graph`], so it mirrors the graph by construction. `Arc`: the component is
-    /// cloned per instance; the bake is shared.
+    /// The pose evaluator's bake, mirroring [`Self::graph`].
     pub pose: std::sync::Arc<super::PoseSource>,
 }
 
-/// A requested `AnimationData.dbc` id resolved to what a specific model actually plays (decision
-/// 0082, wow-re `anim-id-resolution.md`, byte-verified `0x711bf0`) — see [`ModelAnimations::resolve`].
+/// A requested animation id resolved to what this model plays (`0x711bf0`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ResolvedAnim {
-    /// The `AnimationData.dbc` id to look up via [`ModelAnimations::find`].
+    /// The id to look up with [`ModelAnimations::find`].
     pub id: u16,
-    /// PATH 1's high16 direction/variant playback code (`0` from PATH 2 / the no-table degrade, which
-    /// have no such code of their own). **Plumbed through, not applied**: decision 0082 flags the
-    /// exact playback consumption (wow-re `~0x7126d2`) as untraced — no consumer reads this yet.
+    /// PATH 1's high-16 direction code, else 0. Carried, not applied: the reference's arm negates
+    /// the play rate for code 1 and zeroes it for 2 and 3 (`0x7126d2`-`0x712712`).
     pub dir_flags: u16,
 }
 
 impl ModelAnimations {
-    /// The clip for an `AnimationData.dbc` id (0 Stand, 4 Walk, 5 Run, …), or `None` if this model has
-    /// no sequence with that id (e.g. a static-Stand creature has no animated id-0 clip — the caller
-    /// then falls back to Stand or to bind pose rather than to an arbitrary clip). Returns the id's
-    /// **head variation** — the stable identity callers compare/loop on; a one-shot play that should
-    /// alternate variations goes through [`Self::pick_variation`] instead.
+    /// The id's head variation; a one-shot that alternates uses [`Self::pick_variation`].
     pub fn find(&self, anim_id: u16) -> Option<&AnimClip> {
         self.clips.iter().find(|c| c.anim_id == anim_id)
     }
 
-    /// **Does the model author `anim_id`?** — the reference's `0x711960`: a bounds-checked read of
-    /// [`Self::animation_lookup`] against the `0xffff` sentinel. Deliberately NOT `find(..).is_some()`:
-    /// `clips` drops sequences we can't build (zero-duration ones among them), so a clip scan can
-    /// answer "no" where the reference answers "yes" and takes a different branch. Use this to decide
-    /// what the reference would *request*; use [`Self::find`] to get something we can actually play.
+    /// Whether the model authors `anim_id` (`0x711960`), which the GameObject arm's remap branches
+    /// on (`0x5f3930`). Not `find(..).is_some()`: `clips` lacks the zero-length sequences the parse
+    /// skips, which the reference still counts.
     pub fn owns(&self, anim_id: u16) -> bool {
         self.animation_lookup
             .get(anim_id as usize)
             .is_some_and(|&slot| slot != 0xffff)
     }
 
-    /// The clip a free/effect model instance runs: the caller's `preferred` id when the model has
-    /// it (the thrown-weapon missile asks for InFlight), else the reference's **model-load
-    /// bootstrap** — animation id **0 (`Stand`)**, variation 0 (wow-re `ceffect-anim-lifecycle.md`
-    /// §D1a, byte-verified `0x710153`–`0x71019b`: `0x711bf0(reqId = 0)` → `0x711960` → op4 with an
-    /// explicit `push 0x0` variation), falling back to the first sequence record's own id only when
-    /// the model authors no `Stand` (the guarded `*(dword*)&sequences[0]` at `0x710181`).
-    ///
-    /// **Not the file-order-first slot**, which is what this used to be: the two differ on 583
-    /// models corpus-wide (`benilla-extract fxlifescan`), and arming slot 0 hands
-    /// `Spells\LightningShield_State_Base` its `Decay` sequence from frame one. It is the same
-    /// correction `first_seq` already carries for the placed-doodad lane (0637, the duel flag) —
-    /// but taken *without* that field's bind-pose content gate, because an effect's emitters read
-    /// the posed joints even when the mesh would render identically.
-    ///
-    /// One selector so the rig (`entities::spell_fx::arm_effect_rig`) and its per-sequence riders
-    /// agree on which sequence is playing.
+    /// The clip a free or effect model runs: `preferred` when the model has it, else the
+    /// reference's load bootstrap (`0x710153`-`0x71019b`), id 0 `Stand` at variation 0, else the
+    /// first record's id (`0x710181`). Unlike [`Self::first_seq`], no bind-pose gate: an effect's
+    /// emitters read the posed joints.
     pub fn preferred_clip(&self, preferred: Option<u16>) -> Option<&AnimClip> {
         preferred
             .and_then(|id| self.find(id))
@@ -242,33 +127,14 @@ impl ModelAnimations {
             .or_else(|| self.clips.first())
     }
 
-    /// The **FILE sequence slot** the loader-idle seed arms — [`Self::first_seq`]'s selection taken
-    /// *without* its bind-pose content gate, and expressed as the slot the per-sequence bakes are
-    /// keyed on rather than as a `clips` index.
-    ///
-    /// The two fields answer different questions and must not be conflated (decision 0936). The
-    /// reference arms this sequence on **every** M2 instance the moment it goes LIVE (`0x70ebd0`'s
-    /// tail — no instance in the client ever exists with nothing armed), so "which sequence is this
-    /// model playing" always has an answer. `first_seq` answers the narrower *rendering* question
-    /// "is it worth building a skin + `AnimationPlayer` for it", and says `None` when looping the
-    /// idle would render identically to the static mesh. That skip is sound for the mesh — and
-    /// silently wrong for every consumer keyed on the sequence *identity*, which then degraded to
-    /// file slot 0 (`EmitTiming::idx`/`EmitParams::sample`/`AlphaAnim::seq` all resolve `None` that
-    /// way). Slot 0 is only accidentally the idle one: on the Spawn/Stand/Despawn GameObjects
-    /// (`DuelingFlag`-shaped — the battlefield banners, the goobers, `ArenaFlag`) it is the **Spawn**
-    /// flourish, whose emitters then pour for ever at its opening frame.
-    ///
-    /// `None` only for a model with no buildable clip at all (the `GlobalSeqOnly` tier), where there
-    /// is no sequence to name.
+    /// The file slot the loader-idle seed arms, [`Self::first_seq`]'s selection without its
+    /// bind-pose gate: the reference arms it on every instance (`0x70ebd0`), so a consumer keyed on
+    /// the playing sequence needs it, rig or not. `None` only for a model with no clip.
     pub fn idle_seq(&self) -> Option<usize> {
         self.idle_clip().map(|c| c.seq_index)
     }
 
-    /// The loader-idle seed's **clip** — [`Self::idle_seq`]'s selection, before it is reduced to a
-    /// slot number. What a spawn site plays to put an instance on that sequence: since every
-    /// sequence builds a clip (decision 0941), a model whose bones never move still has one to arm,
-    /// and arming it is what gives its emitters/material loops a running clock instead of a frozen
-    /// slot-0 read. Distinct from [`Self::first_seq`], which stays the *rendering* question.
+    /// The loader-idle seed's clip, which a spawn site arms to start the instance's sequence clock.
     pub fn idle_clip(&self) -> Option<&AnimClip> {
         let idle_id = self
             .playable_animation_lookup
@@ -280,15 +146,10 @@ impl ModelAnimations {
             .or_else(|| self.clips.first())
     }
 
-    /// Pick a **variation** of `anim_id` for one play, given a fresh `roll` (the client's `_rand()`,
-    /// `0..0x7fff`): the byte-verified weighted walk (wow-re `anim-id-resolution.md`, op4 with
-    /// variationIdx −1) — `roll < frequency` picks the current node, else `roll -= frequency` and
-    /// advance; chain exhaustion falls back to the **head** (the client leaves the resolved seqIndex
-    /// untouched on the exhaust path — `edi` set at `0x71247a`, only the win path overwrites it at
-    /// `0x7124e9`; wow-re `loop-replay-fidget.md`, correcting decision 0114's clamp-to-last).
-    /// Variations are the sequences sharing `anim_id`, taken in file order (retail exporters bake
-    /// the `variationNext` chain contiguously and in order — the same assumption [`Self::find`]'s
-    /// head = variation 0 already rests on). `None` iff the model has no sequence for `anim_id`.
+    /// Pick a variation of `anim_id` for a `rand()` roll, the reference's weighted walk
+    /// (`0x7121a0`, variation −1). Exhaustion keeps the head: only the win path (`0x7124e9`)
+    /// overwrites the slot set at `0x71247a`. Variations are the sequences sharing `anim_id` in
+    /// file order, as retail files lay out the `variationNext` chain.
     pub fn pick_variation(&self, anim_id: u16, roll: u16) -> Option<&AnimClip> {
         let mut roll = i32::from(roll);
         let mut head = None;
@@ -302,17 +163,10 @@ impl ModelAnimations {
         head
     }
 
-    /// Resolve a *requested* `AnimationData.dbc` id to the id this model actually plays (decision
-    /// 0082, wow-re `anim-id-resolution.md` — the byte-verified two-path `0x711bf0` resolver the real
-    /// client runs before every sequence lookup, ahead of [`Self::find`]):
-    /// - **PATH 1** (`requested < playable_animation_lookup.len()`): the model's own baked table —
-    ///   one dword read, already the precomputed `AnimationData.dbc` Fallback-column walk's result for
-    ///   THIS model's actual sequence set (a chicken lacking Attack2H bakes `[18] = 16`).
-    /// - **PATH 2** (`requested` ≥ the table length, table non-empty): the guarded `AnimationData.dbc`
-    ///   Fallback-column walk over `catalog` — reachable only for the 5 ids ≥ 203 on a normal retail
-    ///   asset set (`nPlayableAnimationLookup` is a fixed 203; `AnimationData.dbc` has 208 rows).
-    /// - **No table at all** (`playable_animation_lookup` empty — a cube fallback / malformed M2):
-    ///   degrades to identity; [`Self::find`] then does its own direct lookup (today's behavior).
+    /// Resolve a requested id as the reference does before every sequence lookup (`0x711bf0`):
+    /// - PATH 1, inside the playable lookup: the model's own baked substitute.
+    /// - PATH 2, past it (ids 203-207 on retail data): the `AnimationData.dbc` fallback walk.
+    /// - No table: the id itself.
     pub fn resolve(&self, requested: u16, catalog: &AnimDataCatalog) -> ResolvedAnim {
         if let Some(row) = self.playable_animation_lookup.get(requested as usize) {
             return ResolvedAnim {
@@ -329,16 +183,10 @@ impl ModelAnimations {
         self.resolve_path2(requested, catalog)
     }
 
-    /// PATH 2 — the `AnimationData.dbc` Fallback-column walk (wow-re `anim-id-resolution.md`): follow
-    /// `catalog.fallback` from `requested` until this model actually has a sequence for the current id
-    /// (mirrors the real walk's `animationLookup[eax] != 0xffff` success test via [`Self::find`]),
-    /// guarded by a 208-entry visited set (`AnimationData.dbc`'s row count — the byte-verified cycle
-    /// guard). `catalog.fallback` already collapses the walk's NULL-row guard, self-fallback
-    /// termination, and "Fallback is 0 (Stand)" into a single `None` — each of those is a dead end that
-    /// leads to the same exhaustion default, so folding them costs nothing here. Exhaustion → Stand(0),
-    /// matching decision 0082's stated simplification (the real client's fuller default — the
-    /// GameObject-rest pose 147, or the model's first sequence id — is a further-out RE gap no benilla
-    /// id exercises: every id benilla requests resolves through PATH 1).
+    /// PATH 2 (`0x711c1f`): follow `catalog.fallback` until the model has a clip for the id, with
+    /// the reference's 208-row cycle guard. Exhaustion gives Stand (0), where the reference takes
+    /// Stand only if the model authors it, else 147 if authored, else the first sequence's id
+    /// (`0x711c22`-`0x711c4e`); every id benilla requests resolves in PATH 1.
     fn resolve_path2(&self, requested: u16, catalog: &AnimDataCatalog) -> ResolvedAnim {
         const STAND: ResolvedAnim = ResolvedAnim {
             id: 0,
@@ -366,7 +214,7 @@ impl ModelAnimations {
 mod tests {
     use super::*;
 
-    // ── ModelAnimations::resolve (decision 0082) ──────────────────────────────────────────────
+    // ── ModelAnimations::resolve ──────────────────────────────────────────────
 
     use bevy::animation::graph::AnimationNodeIndex;
 
@@ -416,8 +264,7 @@ mod tests {
         AnimDataCatalog::from_rows([])
     }
 
-    /// PATH 1: a table entry within range is read verbatim, low16 as the id and high16 as the dir
-    /// code — the chicken-lacking-Attack2H shape (`[18] = {16, 0}`), model has clip 16 not 18.
+    /// A chicken without Attack2H bakes `[18] = 16`.
     #[test]
     fn path1_reads_the_baked_table_entry() {
         let mut table = vec![playable(0, 0); 19];
@@ -433,9 +280,7 @@ mod tests {
         );
     }
 
-    /// PATH 1 also carries the dir-flags code — the real byte-verified HumanMale example
-    /// (`playableAnimationLookup[6] = 0x00030001`, wow-re `anim-id-resolution.md` §4): resolved id 1,
-    /// dir code 3. PATH 1 never consults the catalog at all (an empty one is fine here).
+    /// HumanMale's `playableAnimationLookup[6]` is `0x00030001`: id 1, direction code 3.
     #[test]
     fn path1_carries_dir_flags_through_unapplied() {
         let mut table = vec![playable(0, 0); 7];
@@ -451,8 +296,6 @@ mod tests {
         );
     }
 
-    /// PATH 2: id ≥ the table length walks the DBC Fallback chain (via `catalog`) until the model
-    /// actually has a sequence for the current id.
     #[test]
     fn path2_walks_the_dbc_fallback_past_the_table() {
         let cat = AnimDataCatalog::from_rows([
@@ -482,7 +325,6 @@ mod tests {
         );
     }
 
-    /// PATH 2's cycle guard: a Fallback loop (5→6→5→…) terminates at Stand(0) rather than spinning.
     #[test]
     fn path2_cycle_guard_terminates_at_stand() {
         let cat = AnimDataCatalog::from_rows([
@@ -512,9 +354,7 @@ mod tests {
         );
     }
 
-    /// PATH 2's self-fallback / NULL-row termination: an id with no usable Fallback (an unknown row,
-    /// or one whose Fallback is itself/0 — `AnimDataCatalog::fallback` already collapses all three to
-    /// `None`) exhausts to Stand(0) on the first hop.
+    /// `AnimDataCatalog::fallback` gives `None` for an unknown row, a self-fallback or Stand.
     #[test]
     fn path2_self_or_null_fallback_exhausts_to_stand() {
         let anims = test_anims(&[], vec![playable(0, 0); 3]);
@@ -528,8 +368,7 @@ mod tests {
         );
     }
 
-    /// PATH 2's NULL/max-id guard: an id at or past the 208-row `AnimationData.dbc` bound can't even
-    /// be marked visited — it exhausts to Stand(0) immediately, not just when it recurs.
+    /// An id past the 208 rows cannot be marked visited, so it exhausts at once.
     #[test]
     fn path2_out_of_dbc_range_id_exhausts_to_stand() {
         let anims = test_anims(&[], vec![playable(0, 0); 3]);
@@ -543,8 +382,6 @@ mod tests {
         );
     }
 
-    /// A model with no baked table at all (a cube fallback / malformed M2) degrades to identity —
-    /// `resolve` hands the id straight back so the caller's own `find` does today's direct lookup.
     #[test]
     fn no_table_degrades_to_identity() {
         let anims = test_anims(&[0], Vec::new());
@@ -558,27 +395,22 @@ mod tests {
         );
     }
 
-    // ── preferred_clip: the model-load bootstrap (wow-re `ceffect-anim-lifecycle.md` §D1a) ──────
+    // ── preferred_clip: the model-load bootstrap (`0x710153`–`0x71019b`) ─────────────────────
 
-    /// The bootstrap arms **id 0 `Stand`**, not the file's first slot. `LightningShield_State`'s
-    /// real shape: sequence 0 is its `Decay`(159), and arming file-order-first handed a freshly
-    /// cast shield its fade-out from frame one.
+    /// `LightningShield_State`'s shape: slot 0 is its Decay (159).
     #[test]
     fn preferred_clip_arms_stand_over_the_file_order_first_slot() {
         let anims = test_anims(&[159, 0, 158], Vec::new());
         assert_eq!(anims.preferred_clip(None).map(|c| c.anim_id), Some(0));
     }
 
-    /// The guarded fallback (`0x710181`): a model authoring no `Stand` at all — Cripple, Curse of
-    /// Tongues, both Holy Word: Shields, whose slot 0 is `Hold` — plays that first record's own id.
+    /// The guarded fallback (`0x710181`), as on Cripple's effect: no Stand, slot 0 Hold (158).
     #[test]
     fn preferred_clip_falls_back_to_the_first_record_without_a_stand() {
         let anims = test_anims(&[158, 159], Vec::new());
         assert_eq!(anims.preferred_clip(None).map(|c| c.anim_id), Some(158));
     }
 
-    /// A caller-named id still wins (the thrown-weapon missile's InFlight) — and when the model
-    /// lacks it, the resolve falls through to the bootstrap rather than to slot 0.
     #[test]
     fn preferred_clip_honours_a_named_id_then_falls_to_stand() {
         let anims = test_anims(&[159, 0, 158], Vec::new());
@@ -589,10 +421,9 @@ mod tests {
         assert_eq!(anims.preferred_clip(Some(42)).map(|c| c.anim_id), Some(0));
     }
 
-    // ── idle_seq: the loader-idle FILE slot, split from the render content gate ──────────────
+    // ── idle_seq: the loader-idle file slot, apart from the rig gate ─────────────────────────
 
-    /// `test_anims` in file order, with each clip's `seq_index` set to its slot — the axis the
-    /// per-sequence bakes (`EmitTiming`/`EmitParams`/`AlphaAnim`) are keyed on.
+    /// `test_anims` with each clip's `seq_index` set to its file slot.
     fn slotted(ids: &[u16], table: Vec<PlayableAnim>) -> ModelAnimations {
         let mut a = test_anims(ids, table);
         for (i, c) in a.clips.iter_mut().enumerate() {
@@ -601,18 +432,13 @@ mod tests {
         a
     }
 
-    /// The Spawn/Stand/Despawn GameObject shape — `DuelingFlag`, the battlefield banners,
-    /// `ArenaFlag`, the goobers. The idle slot is **1**, not 0: slot 0 is the Spawn flourish, whose
-    /// emitters pour at its opening frame for ever if a consumer degrades to it.
+    /// The Spawn/Stand/Despawn GameObject shape (`DuelingFlag`, `ArenaFlag`, battlefield banners).
     #[test]
     fn idle_seq_is_the_stand_slot_not_file_slot_zero() {
         let anims = slotted(&[145, 0, 157], Vec::new());
         assert_eq!(anims.idle_seq(), Some(1));
     }
 
-    /// It is `first_seq`'s selection **without** the bind-pose content gate: the field stays `None`
-    /// (looping a constant-pose idle renders identically to the static mesh, so the rig tier skips
-    /// the arm) while the slot is still known. Conflating the two is the whole defect.
     #[test]
     fn idle_seq_answers_even_when_the_content_gate_skipped_the_arm() {
         let anims = slotted(&[145, 0, 157], Vec::new());
@@ -624,31 +450,25 @@ mod tests {
         );
     }
 
-    /// The idle id is resolved through the model's own `playableAnimationLookup` — the same
-    /// `0x711bf0(reqId = 0)` chain `first_seq` takes (0637). 268 models corpus-wide remap requested
-    /// id 0 (`Cripple_State_Base` → 158 Hold), and slot 0 is not their idle either.
+    /// `Cripple_State_Base` remaps requested id 0 to 158 (Hold).
     #[test]
     fn idle_seq_resolves_id_zero_through_the_playable_lookup() {
         let anims = slotted(&[159, 158], vec![playable(158, 0)]);
         assert_eq!(anims.idle_seq(), Some(1));
     }
 
-    /// No sequence for the resolved idle id ⇒ the first record's own slot, the guarded
-    /// `*(dword*)&sequences[0]` fallback — and `None` only when there is no clip at all to name.
     #[test]
     fn idle_seq_falls_back_to_the_first_record_then_to_none() {
         assert_eq!(slotted(&[158, 159], Vec::new()).idle_seq(), Some(0));
         assert_eq!(slotted(&[], Vec::new()).idle_seq(), None);
     }
 
-    /// The variation pick is the client's weighted walk (wow-re `anim-id-resolution.md`, op4 with
-    /// variationIdx −1): `roll < frequency` picks, else `roll -= frequency` and advance; chain
-    /// exhaustion clamps to the last variation; a lone variation always wins.
+    /// A roll past every weight gives the head variation, not the last.
     #[test]
     fn pick_variation_walks_the_weighted_chain() {
         let mut anims = test_anims(&[16, 16, 5], Vec::new());
-        anims.clips[0].frequency = 0x6000; // Attack1H variation 0 — the common arc
-        anims.clips[1].frequency = 0x1fff; // variation 1 — the off-side swing
+        anims.clips[0].frequency = 0x6000; // Attack1H variation 0, the common arc
+        anims.clips[1].frequency = 0x1fff; // variation 1, the off-side swing
         let pick = |anims: &ModelAnimations, id, roll| {
             let c = anims.pick_variation(id, roll).unwrap();
             anims.clips.iter().position(|x| std::ptr::eq(x, c)).unwrap()
@@ -657,8 +477,7 @@ mod tests {
         assert_eq!(pick(&anims, 16, 0x5fff), 0); // last roll inside variation 0's weight
         assert_eq!(pick(&anims, 16, 0x6000), 1); // first roll past it
         assert_eq!(pick(&anims, 16, 0x7ffe), 1);
-        // Weights under-cover the roll → the HEAD, not the last (the client's exhaust path leaves
-        // the resolved seqIndex untouched — wow-re loop-replay-fidget.md, corrects decision 0114).
+        // A roll past the weights keeps the head (the reference's exhaust path, `0x7124de`).
         assert_eq!(pick(&anims, 16, 0x7fff), 0);
         assert_eq!(pick(&anims, 5, 0x7fff), 2); // lone variation wins by exhaustion→head (weight 0)
         assert!(anims.pick_variation(99, 0).is_none());
diff --git a/crates/benilla-assets/src/model/pose.rs b/crates/benilla-assets/src/model/pose.rs
index ea64c736..692cd318 100644
--- a/crates/benilla-assets/src/model/pose.rs
+++ b/crates/benilla-assets/src/model/pose.rs
@@ -1,30 +1,21 @@
-//! The pose source — the direct M2 pose evaluator's baked data (decision 0712).
-//!
-//! Bevy's `animate_targets` prices every bone at graph-walk + hash-lookup + boxed-curve rates
-//! (~1.9 µs/bone — 0711's second lane). These types hold the *same* Bevy-space keyframes as the
-//! `AnimationClip`s — emitted by the same bake walk, so they cannot drift — in the flat shape a
-//! direct sampler wants: per clip, bone-sorted channel tracks; per graph node, the (clip, mask)
-//! pair; per bone, its mask-group bits. The runtime evaluator (`benilla::creature_anim::pose`)
-//! folds these with Bevy's own `Animatable::interpolate`, reproducing `animate_targets`' output
-//! exactly (goldens there assert it bone-for-bone).
+//! The direct M2 pose evaluator's baked data: the `AnimationClip`s' keyframes from the same bake
+//! walk, flattened per clip, graph node and bone. The evaluator (`benilla_world::rig_anim::pose`)
+//! reproduces Bevy's `animate_targets` output exactly, so these must match the clips key for key.
 
 use bevy::animation::animatable::Animatable;
 use bevy::animation::graph::AnimationNodeIndex;
 use bevy::prelude::*;
 
-/// One channel's keyframes: times ascending and strictly deduplicated — the exact normalization
-/// `UnevenCore::new` applies to the twin `AnimatableKeyframeCurve` (stable sort by time, dedup
-/// keeping the FIRST sample at each time), so [`Self::sample`] and `sample_clamped` agree
-/// key-for-key. Empty ⇒ the channel is absent (the clip never keys it — Bevy leaves the joint
-/// component untouched, and so does the evaluator).
+/// One channel's keyframes, normalized as `UnevenCore::new` does (stable sort by time, the first
+/// sample at a time kept), so [`Self::sample`] matches the clip's curve. Empty: the clip does not
+/// key the channel, and the joint keeps its value.
 #[derive(Clone)]
 pub struct PoseTrack<T> {
     times: Vec<f32>,
     values: Vec<T>,
 }
 
-// Manual: the derive would bound `T: Default`, which `Quat` channels don't need — an empty track
-// has no values of `T` at all.
+// Manual: the derive would add a needless `T: Default` bound.
 impl<T> Default for PoseTrack<T> {
     fn default() -> Self {
         Self {
@@ -35,10 +26,8 @@ impl<T> Default for PoseTrack<T> {
 }
 
 impl<T: Animatable + Clone> PoseTrack<T> {
-    /// Bake a channel from the clip walk's key list, mirroring `keyframe_curve`'s presence rules
-    /// exactly: no keys ⇒ absent; one key ⇒ a constant (Bevy builds a flat 2-key curve — same
-    /// sampled value everywhere); ≥2 keys ⇒ `UnevenCore`'s sort + dedup, and absent if fewer than
-    /// 2 distinct times remain (Bevy's constructor errors there and the channel is dropped).
+    /// Mirrors `keyframe_curve`: one key is a constant, and keys that dedup to fewer than two
+    /// times are absent, since Bevy's constructor refuses them.
     pub fn new(keys: &[(f32, T)]) -> Self {
         match keys.len() {
             0 => Self::default(),
@@ -59,10 +48,7 @@ impl<T: Animatable + Clone> PoseTrack<T> {
         }
     }
 
-    /// Sample at `t`, clamped into the key span — `uneven_interp`'s law verbatim (binary search;
-    /// exact hit returns that key; before/after the span clamps to the end keys; between keys
-    /// interpolates with `Animatable::interpolate` — `Vec3::lerp` / `Quat::slerp`, the same calls
-    /// the Bevy curve makes). `None` iff the channel is absent.
+    /// Sample at `t`, clamped into the key span, as Bevy's `uneven_interp` does.
     #[inline]
     pub fn sample(&self, t: f32) -> Option<T> {
         let times = &self.times;
@@ -88,7 +74,7 @@ impl<T: Animatable + Clone> PoseTrack<T> {
     }
 }
 
-/// One bone's channels in one clip — only bones with at least one present channel appear.
+/// One bone's channels in one clip; a bone with no channel is left out.
 #[derive(Clone)]
 pub struct PoseBone {
     pub bone: u16,
@@ -97,17 +83,14 @@ pub struct PoseBone {
     pub scale: PoseTrack<Vec3>,
 }
 
-/// One clip's keyed bones, sorted ascending by bone index (the evaluator's merge walk relies on
-/// it). The same channels, values, and presence as the twin `AnimationClip`.
+/// One clip's keyed bones, ascending by bone index, which the evaluator's merge walk needs.
 #[derive(Clone, Default)]
 pub struct PoseClip {
     pub bones: Vec<PoseBone>,
 }
 
 impl PoseClip {
-    /// Push a bone's channels, keeping [`Self::bones`] sorted (the bake walks file bone order,
-    /// which is ascending for every retail M2 — the insertion sort is a no-op there and a
-    /// correctness backstop elsewhere). Bones with no present channel are skipped.
+    /// Insert a bone in bone order, skipping one with no channel.
     pub fn push(&mut self, bone: PoseBone) {
         if bone.translation.is_empty() && bone.rotation.is_empty() && bone.scale.is_empty() {
             return;
@@ -117,18 +100,15 @@ impl PoseClip {
     }
 }
 
-/// One graph node the evaluator understands: which [`PoseClip`] it plays and its mask bits (the
-/// `add_clip_with_mask` argument; a node whose mask bit intersects a bone's mask groups skips
-/// that bone — Bevy's `computed_masks` law with a flat graph, where ancestors contribute 0).
-/// Node weights are all 1.0 by construction (`add_clip(_, 1.0, root)`), so none is stored.
+/// One graph node: the [`PoseClip`] it plays and its mask bits, which skip a bone whose mask
+/// groups they intersect. Every node's weight is 1.0, so none is stored.
 #[derive(Clone, Copy)]
 pub struct PoseNode {
     pub clip: u32,
     pub mask: u64,
 }
 
-/// A model's baked pose source (decision 0712): everything the runtime evaluator needs, filled by
-/// the same code that builds the `AnimationGraph` so the two cannot drift.
+/// A model's baked pose source, filled beside the `AnimationGraph` it mirrors.
 #[derive(Clone, Default)]
 pub struct PoseSource {
     /// The pose twin of each built clip (sequence clips in build order, then the grip clip).
@@ -140,8 +120,7 @@ pub struct PoseSource {
 }
 
 impl PoseSource {
-    /// Record `node` as playing `clip` under `mask` — called right after the corresponding
-    /// `graph.add_clip*` so the table mirrors the graph by construction.
+    /// Record `node` as playing `clip` under `mask`; call it beside each `graph.add_clip*`.
     pub fn set_node(&mut self, node: AnimationNodeIndex, clip: u32, mask: u64) {
         let i = node.index();
         if self.nodes.len() <= i {
@@ -163,10 +142,6 @@ mod tests {
     use bevy::animation::animation_curves::AnimatableKeyframeCurve;
     use bevy::math::curve::Curve;
 
-    /// The channel golden (decision 0712): [`PoseTrack::sample`] must equal
-    /// `AnimatableKeyframeCurve::sample_clamped` — the exact curve the twin `AnimationClip`
-    /// carries — over a dense time sweep spanning before-first, between-keys, exact-hit, and
-    /// past-last, for both Vec3 (lerp) and Quat (slerp) channels.
     #[test]
     fn track_matches_the_bevy_keyframe_curve() {
         let vkeys = [
@@ -204,9 +179,6 @@ mod tests {
         }
     }
 
-    /// The presence rules mirror `keyframe_curve`: a single key is a constant everywhere (Bevy's
-    /// flat 2-key curve), duplicate-time keys dedup keeping the FIRST (`UnevenCore::new`), and a
-    /// list that dedups below 2 keys is absent (Bevy's constructor errors → the channel drops).
     #[test]
     fn presence_and_dedup_mirror_the_curve_constructor() {
         assert!(PoseTrack::<Vec3>::new(&[]).sample(0.5).is_none());
@@ -234,13 +206,12 @@ mod tests {
             assert_eq!(dup.sample(t).unwrap(), curve.sample_clamped(t), "t={t}");
         }
 
-        // Two keys at one time: Bevy's constructor would fail — the channel must be absent.
+        // Two keys at one time: Bevy's constructor fails, so the channel is absent.
         assert!(PoseTrack::new(&[(0.5, Vec3::X), (0.5, Vec3::Y)])
             .sample(0.5)
             .is_none());
     }
 
-    /// `PoseClip::push` keeps bones ascending and drops all-absent bones.
     #[test]
     fn clip_bones_stay_sorted() {
         let bone = |i: u16| PoseBone {
diff --git a/crates/benilla-assets/src/shaders/liquid.wgsl b/crates/benilla-assets/src/shaders/liquid.wgsl
index e93833e3..1a9d72e7 100644
--- a/crates/benilla-assets/src/shaders/liquid.wgsl
+++ b/crates/benilla-assets/src/shaders/liquid.wgsl
@@ -1,93 +1,26 @@
-// Liquid shader — a port of the reference's **ADT** water path (`ocean0_s.bls`) to WGSL.
+// Liquid shader, one arm per reference liquid renderer:
+//   ADT MCLQ river/ocean (`0x6851b0`/`0x685010`): `ocean0_s.bls`, the depth swatch on stage 0 and
+//     the animated sheet on stage 1; the only arm with a depth ramp.
+//   WMO MLIQ water (`0x6b62e0` category 0), split on `MOGP.flags & 0x48`: exterior `0x6b6630`
+//     binds `MapObjExtWater0.bls`, interior `0x6b6420` is fixed-function and unlit.
+//   Magma/slime (`0x6b68f0` WMO, `0x68dca0` ADT): the sheet is the opaque body.
 //
-// ## SCOPE — this file implements ONE of the reference's three liquid renderers
+// The ADT combine, `Shaders\Pixel\ocean0_s.bls` (0.25 is the program's own `PARAM`):
+//   rgb   = primary·colorTex.rgb + detail.rgb + (secondary + 0.25)·detail.a
+//   alpha = colorTex.a
+// colorTex is the depth swatch off the zone's `Light.dbc` water bands (IntBand 16/17 river/lake,
+// 14/15 ocean), rebuilt every frame (`0x680b90`, refill `0x58acd0`); detail is the `lake_a` or
+// `ocean_h` frame, near-black RGB and the ripple in alpha, which its authored mips fade with
+// distance, so the sampler's mips and anisotropy matter; primary is the lit default white vertex
+// (`glColorMaterial`); secondary is the sun sheen.
+// Deviation: the reference's ADT water alpha is the `0xc7fbc0` LUT curve `1.6·(i/63)^8`; this keeps
+// the linear swatch alpha, because switching changes the look of every ADT water surface.
+// Deviation: this is the `specular`/`pixelShaders` = 1 leg the reference install runs; both CVars
+// (`0x6886a0`/`0x688712`) default to 0, where water has no program, no specular, a plain ADD
+// combine and no blend. An active ARB program bypasses the texture environment.
 //
-// This is the ADT MCLQ river/ocean path and nothing else. It is also, today, what benilla runs on
-// WMO-embedded liquid, and that is **wrong** — see `liquid/surface.rs`'s `spawn_wmo_liquids` and the
-// `wmo_liquid_arms` census. The reference has three:
-//
-//   * **ADT MCLQ river/ocean** — passes `0x6851b0`/`0x685010`. Two texture stages: a static depth-ramp
-//     on stage 0, the animated sheet on stage 1, combined by the pixel program `ocean0_s.bls`. The
-//     only liquid path with a depth ramp, and the only one whose vertex carries NO colour. **This
-//     file.**
-//   * **WMO MLIQ water** — `0x6b62e0` category 0, split again on the group's `MOGP.flags & 0x48`:
-//     exterior `0x6b6630` (binds `MapObjExtWater0.bls`), interior `0x6b6420` (no shader, lighting
-//     forced off). One texture stage, no depth ramp at all — zero references to the ADT ramp globals
-//     `0xc7fbc0`/`0xc81768`/`0xc7fcd8` anywhere in `[0x6b0000, 0x6c4000)` — and alpha comes from a
-//     per-vertex authored byte, not from a depth swatch. 164 groups; 90% of them interior.
-//   * **magma/slime** — `0x6b68f0` (WMO) / `0x68dca0` (ADT), arm-blind, the sheet IS the body.
-//
-// ## The ADT combine (VERIFIED — the program is an asset, extracted and read)
-//
-// `Shaders\Pixel\ocean0_s.bls` out of `patch.MPQ`, verbatim ARB:
-//
-//   PARAM c[1] = { { 0.25 } };
-//   TEX R0, fragment.texcoord[0], texture[0], 2D;   # colorTex  = the depth ramp
-//   TEX R1, fragment.texcoord[1], texture[1], 2D;   # detailTex = the animated sheet
-//   MAD R1.xyz, fragment.color.primary, R0, R1;
-//   ADD R0.xyz, fragment.color.secondary, c[0].x;
-//   MAD result.color.xyz, R0, R1.w, R1;
-//   MOV result.color.w, R0;                          # R0.w still holds colorTex.a
-//
-//   ⇒ rgb = primary*colorTex.rgb + detailTex.rgb + (secondary + 0.25)*detailTex.a
-//     alpha = colorTex.a
-//
-// The `+0.25` is the program's own scalar `PARAM`, not an FFP env colour (`glTexEnvfv` has zero call
-// sites image-wide) and not a material. **The formula this file has always carried is right, verbatim
-// — but its provenance was fiction**: the header used to cite "apitrace WoW.17 program 159" and a
-// `docs/knowledge/terrain.md`, neither of which exists, and wow-re had the program attributed to a
-// *character* draw (`Model2.bls` ships 32 ARBfp permutations, none containing `0.25` or
-// `fragment.color.secondary`). Corrected and recorded: wow-re `terrain/scratch/water-shading-law.md`.
-//
-//   * colorTex (unit 0) is the depth swatch — a 2-endpoint linear lerp of the zone's dedicated
-//     `Light.dbc` water rows, RAW (no ×0.711): `water_shallow.rgb` = IntBand row 16 (river/lake) / 14
-//     (ocean), `water_deep.rgb` = row 17 / 15. Rebuilt **per world frame**, not baked once: the dirty
-//     flags `[0xc8117c]`/`[0xc81b70]` clear at `0x680b90`/`0x680b97` and refill via `0x58acd0`, so the
-//     colour and the opacity track the zone and the clock. (The earlier "reflected sky × 0.711 via
-//     `FUN_0068c250`" model fingered the WRONG builder — a separate grey edge texture never bound on
-//     the water unit. Rows 14–17 were right all along.)
-//   * detailTex (unit 1) is the animated `lake_a`/`ocean_h` frame: RGB near-black, ALPHA = the ripple.
-//     MEASURED off the shipped BLPs (DXT3, 9 authored mips): lake_a RGB mean 0.0140 and achromatic to
-//     ±1 LSB, alpha mean 0.21 / p50 51 / p99 255. So it adds a faint flat lift + an achromatic shimmer
-//     on the crests — NOT the body. The authored mip chain deliberately kills the shimmer with
-//     distance (per-mip alpha max 255, 255, 255, 136, 68, then flat 51), which is why the sampler's
-//     mips and 16× aniso are load-bearing rather than a nicety.
-//   * primary = the vertex's lit colour `clamp(ambient + N·L·sun)`. The ADT liquid vertex has no
-//     colour element, so `glColor` is the device default `(1,1,1,1)` tracked into material
-//     ambient+diffuse by `glColorMaterial(FRONT_AND_BACK, AMBIENT_AND_DIFFUSE)`, and `GL_LIGHTING` is
-//     ON at both water draws (lava explicitly turns it off; water does not).
-//   * secondary = the specular sheen — see `sun_sheen` for what is verified in it and what is not.
-//   * alpha = swatch.a over the SAME V as the colour. LightParams endpoints: river 0.5→1.0, ocean
-//     0.75→1.0. Deeper water = more opaque. **Open**: wow-re reads the byte-verified ADT water alpha
-//     as the `0xc7fbc0` LUT's `1.6·(i/63)^8` curve rather than the linear `127+2·row` this file
-//     applies — a much later-breaking ramp. Not changed here; it is a look change to every ADT water
-//     surface in the game and it belongs in the same A/B as the WMO arms.
-//
-// **Both `ocean0_s.bls` and `MapObjExtWater0.bls` are CVar-gated** — `specular` and `pixelShaders`
-// (registered `0x6886a0`/`0x688712`) default to `"0"`, and with them off there is no program, no
-// specular, the stage-1 combine is a plain ADD, and blend is never set so water draws OPAQUE. Our
-// reference install's `Config.wtf` sets both to `"1"`, so every capture and every director comparison
-// is against the shader leg — which is the leg we implement. The two do not compose: an active ARB
-// program bypasses the texture environment entirely.
-//
-// A SINGLE swatch row (V) indexes both the colour and the alpha — they track together. Each kind reads
-// its OWN verified LUT, built side by side in `FUN_0068c4c0`: `clamp(byte/42)` for river/lake
-// (`c81768`, `FUN_0068d790`, saturates ~5 yd → the channel middle hits the deep teal row) and
-// `clamp(byte/255)` for ocean (`c7fcd8`, `FUN_0068d690`, saturates ~148 yd). The divisors differ
-// because the authored bytes do — the sea ramps 1.72 byte/yd against a river's 8.96, and 83 % of ocean
-// vertices are pinned at 255 outright (decision 2069, `examples/liquid_depth_census`). (Earlier cuts:
-// ripple-as-colour → black; ×8 over-saturated; FLAT colour killed the gradient; sky×0.711 was the wrong
-// builder; `byte/255` on the RIVER was the wrong LUT → river middle never went teal. Corrected to
-// rows 14–17 raw lerp + the /42 V on rivers, 2026-05-31.)
-//
-// Two-sided comes from the material (cull off) and is right for EVERY kind: all four reference liquid
-// passes force GL_CULL_FACE off at pass entry against a cull-ON device baseline, and `glFrontFace` is
-// not even imported (VERIFIED wow-re `liquid-render-state-sided` §6). Blending is per KIND, decided in
-// liquid.rs: water/ocean blend with depth-write off; magma/slime are opaque and depth-write. Fog + gamma
-// mirror terrain.wgsl (planar eye-Z GL_LINEAR fog in gamma space; raw gamma out — GAMMA LANE, 0161), fog
-// applies to every kind — magma and slime included — and WHICH fog block a surface takes is per-surface:
-// a WMO interior group's own pool fogs with the interior block, everything else with the scene block
-// (see `apply_fog`). Light, fog and both water swatches all come off the ONE shared global-light buffer.
+// Culling is off for every kind: all four reference liquid passes disable GL_CULL_FACE. Water
+// blends with depth write off; magma and slime are opaque and write depth. Output is raw gamma.
 
 #import bevy_pbr::{
     mesh_functions,
@@ -104,35 +37,28 @@
 struct LiquidParams {
     // x = fullbright (magma/slime); y = ocean swatch; z = interior fog; w = sun-sheen shininess.
     kind: vec4<f32>,
-    // x = WHICH RENDERER (see `LiquidPath`): 0 = ADT MCLQ, 1 = WMO exterior, 2 = WMO interior.
-    // y/z/w reserved.
+    // x = renderer (`LiquidPath`): 0 = ADT MCLQ, 1 = WMO exterior, 2 = WMO interior; yzw reserved.
     path: vec4<f32>,
-    // x = reserved (frame 0); y = frame count; z = the SCROLL FLAG (1 only on the nibble-6/7
-    // WMO magma/slime lane — the reference's animated stage-0 texture matrix; see
-    // `liquid/surface.rs`'s `scrolls`, and `apply_scroll` below); w = the clock enable (0 on a
-    // deterministic run — the whole animation freezes at frame 0 / scroll 0, the 0600 capture
-    // pin, baked at material build).
+    // y = frame count; z = scroll flag (WMO magma/slime only, liquid nibbles 6/7); w = clock
+    // enable (0 on a deterministic run).
     anim: vec4<f32>,
 };
 @group(#{MATERIAL_BIND_GROUP}) @binding(102) var<uniform> w: LiquidParams;
 
-// The shared global light (`lighting::global_light`) — the SAME buffer terrain and the models read,
-// mirrored here as its canonical row prefix. Liquid used to carry its own copy of every one of these
-// values, re-pushed per material by `apply_wow_lighting`; that copy is what left it with only the
-// scene fog and no way to see the interior block (decision 0691).
+// The prefix of the shared global light (`lighting::global_light`); it must match row for row.
 struct WowLight {
     light_ambient: vec4<f32>,      // 0  rgb = ambient; w = Mod2x scale
     light_diffuse: vec4<f32>,      // 1  rgb = sun diffuse; w = clamp flag
-    light_sun: vec4<f32>,          // 2  xyz = sun TRAVEL dir (to-light = −xyz)
-    light_spec: vec4<f32>,         // 3  rgb = row-9 specular colour; w = TERRAIN shininess (liquid uses w.kind.w)
+    light_sun: vec4<f32>,          // 2  xyz = sun travel direction (to-light = −xyz)
+    light_spec: vec4<f32>,         // 3  rgb = row-9 specular colour; w = terrain shininess, unread
     fog_color: vec4<f32>,          // 4  rgb = scene fog (block 1, gamma 0..1); w = enable (>0.5)
     fog_params: vec4<f32>,         // 5  x = start yd; y = end yd; w = the farclip wall
-    _sh: array<vec4<f32>, 6>,      // 6-11  model SH coeffs — unread here
+    _sh: array<vec4<f32>, 6>,      // 6-11  model SH coefficients, unread here
     _sh_c16: vec4<f32>,            // 12
-    water_river: array<vec4<f32>, 2>, // 13-14 shallow/deep river-lake swatch (IntBand 16/17); w = alpha
-    water_ocean: array<vec4<f32>, 2>, // 15-16 shallow/deep ocean swatch    (IntBand 14/15); w = alpha
+    water_river: array<vec4<f32>, 2>, // 13-14 river/lake shallow, deep (IntBand 16/17); w = alpha
+    water_ocean: array<vec4<f32>, 2>, // 15-16 ocean shallow, deep (IntBand 14/15); w = alpha
     _grade: vec4<f32>,             // 17
-    wmo_fog_color: vec4<f32>,      // 18 rgb = INTERIOR fog (block 2); w = enable
+    wmo_fog_color: vec4<f32>,      // 18 rgb = interior fog (block 2); w = enable
     wmo_fog_params: vec4<f32>,     // 19 x = start yd; y = end yd
 };
 @group(#{MATERIAL_BIND_GROUP}) @binding(90) var<storage, read> wow_light: WowLight;
@@ -143,112 +69,52 @@ struct LiquidVsOut {
     @location(1) world_normal: vec3<f32>,
     @location(2) uv: vec2<f32>,
     @location(3) depth: f32,
-    // The sun-sheen `secondary` evaluated PER-VERTEX (the faithful 1.12 path: the real client computes
-    // the Blinn highlight in its FFP vertex shader and interpolates it across the coarse water mesh).
-    // The fragment shader uses this interpolated value directly.
+    // The sun sheen, per vertex and interpolated, as the reference's fixed-function stage does.
     @location(4) secondary_vtx: vec3<f32>,
-    // The mesh's vertex COLOUR, which on a WMO INTERIOR pool carries its `MOMT.diffColor` body
-    // colour — the reference's own interior water vertex carries a colour dword for exactly this.
-    // White on every other lane (and on any mesh with no colour attribute), where nothing reads it.
+    // A WMO interior pool's `MOMT.diffColor`, as its reference vertex carries; white elsewhere.
     @location(5) vcolor: vec4<f32>,
-    // The per-frame INTERIOR FOG lane for this surface's own room (decision 1787): the client's
-    // `[0xca7f00]`, which gates the WMO liquid pass's block-2 submit (`0x6b6323`–`0x6b6342`)
-    // exactly as it gates the geometry pass — so a pool and the walls around it can never
-    // disagree about which fog they wear. Carried on `MeshTag` bit 30, read once in the vertex
-    // stage and flat-interpolated (the whole surface is one instance).
+    // `MeshTag` bit 30: the room's per-frame interior-fog gate, the reference's `[0xca7f00]`.
     @location(6) @interpolate(flat) room_fog: u32,
 }
 
-// Sun sheen (`secondary`): a Blinn highlight of the sun on the flat water surface — the glint that's
-// strongest at grazing (sunrise/sunset) sun. `secondary = light_spec.rgb · (N·H)^shininess`. Shared by
-// both stages so the per-vertex (faithful) and per-pixel (current) paths run IDENTICAL math — only the
-// EVALUATION DOMAIN differs (interpolated vs evaluated per fragment).
+// Sun sheen (`secondary`): the Blinn highlight `light_spec.rgb · (N·H)^shininess`.
 fn sun_sheen(world_normal: vec3<f32>, world_pos: vec3<f32>) -> vec3<f32> {
     let n = normalize(world_normal);
     let to_light = -normalize(wow_light.light_sun.xyz);
-    // LOCAL viewer, not the infinite-viewer constant: the reference sets
-    // `GL_LIGHT_MODEL_LOCAL_VIEWER = 1` at `0x59cf89`, so `H = normalize(L + normalize(eye − vertex))`
-    // and the eye vector is recomputed per vertex (VERIFIED wow-re `water-shading-law.md`). It is
-    // the difference between a highlight and a flood: with the infinite viewer `N·H` is very nearly
-    // CONSTANT over a flat water plane, so at high sun the whole sheet saturates at once instead of
-    // carrying a glint that moves with the camera.
+    // Local viewer, per vertex: the reference sets `GL_LIGHT_MODEL_LOCAL_VIEWER = 1` at `0x59cf89`.
     let to_view = normalize(view.world_position.xyz - world_pos);
     let half_v = normalize(to_light + to_view);
     let ndoth = max(dot(n, half_v), 0.0);
-    // The reference's specular is additionally gated on `N·L > 0` (the fixed-function rule: a light
-    // behind the surface contributes no specular). **Deliberately not ported**, because it cannot
-    // fire here: `DayNight::SetDirection` holds the LIGHTING sun's azimuth constant and wobbles its
-    // elevation only between +20° and +37° — it is always above the horizon, night being the colours
-    // going dark rather than the sun setting (`lighting::daynight::sun_direction`, and the separate
-    // *visible* sun is the one that rises and sets). Against a liquid surface's flat up normal `N·L`
-    // is therefore positive at every minute of the day, so the gate is a branch that can only ever
-    // take one arm. Named rather than added: it is real, it is verified, and it is inapplicable.
-    //
-    // Shininess is WATER's own (`w.kind.w`), not the shared row-3 terrain exponent. Material
-    // specular is white (`SetRenderState(3, 0xffffffff)`) and the exponent is 6.0 (`[0x8102e8]`),
-    // both VERIFIED — so `light_spec.rgb` is the whole scale, and it is the one input here that is
-    // still INFERRED: wow-re pinned the mechanism (`CGLight+0x48` → `collector+0x6c` → `0x589d80(0)`
-    // → `glLightfv(GL_SPECULAR)`) but not the number, and reads it as a warm ≈(1.0, 0.91, 0.76)
-    // against the row-9 feed we use. Left on row 9 until that lands rather than swapped for an
-    // estimate.
+    // No `N·L > 0` specular gate: the sun stays between +20° and +37° (`DayNight::SetDirection`),
+    // so N·L on the flat up normal is always > 0. Shininess is water's own (6.0, `[0x8102e8]`) and
+    // material specular is white (`SetRenderState(3, 0xffffffff)`). The reference's specular light
+    // colour (`CGLight+0x48` to `glLightfv(GL_SPECULAR)`) is not pinned; row 9 stands in for it.
     return wow_light.light_spec.rgb * pow(ndoth, max(w.kind.w, 1.0));
 }
 
-// The lava/slime **surface scroll**: the reference's animated stage-0 texture matrix, which for
-// liquid-type nibbles 6 and 7 is the identity with element 13 — the **v translate** — set to
-// `fmod(uptime_s, 10.0) · 0.1` (VERIFIED wow-re `liquid-uv-scroll-law.md`, six-agent §5, matrix
-// built at `0x6b68f0` and pushed at stage 0 by `0x6b6ae3`). A texture matrix times `(s, t, 0, 1)`
-// with only element 13 non-identity is exactly `t += phase`, so the whole mechanism is this add —
-// no matrix, no second sampler, no cost on the paths that do not scroll (`anim.z` is a hard 0
-// there, which the CPU side guarantees rather than the shader branching on it).
-//
-// A full repeat every 10 s, so `REPEAT` wrapping makes the sawtooth's reset invisible. Only the
-// rate and the period are reproducible — the reference's phase comes off `GetTickCount`, i.e. the
-// machine's uptime, so its absolute value is not a thing to match.
-// The liquid clock: `globals.time` (the same wall-elapsed seconds the CPU cycler used to read)
-// under the build-time enable. Both animations below are pure functions of it — the CPU-side
-// 24 Hz `Assets::get_mut` tick this replaces mutated ~14 materials a tick and its Modified
-// fallout (uniform re-uploads, bind-group rebuilds, whole-population `AssetChanged` arming)
-// measured 0.28 cpu_ms/frame at the SW pin (2026-08-18 bracket).
 fn anim_time() -> f32 {
     return w.anim.w * globals.time;
 }
 
-// The 24 fps frame flip — 30 frames over 1.25 s (VERIFIED `FUN_0068aac0`), floor-quantized to
-// the tick exactly as the reference's integer frame index is.
+// The 24 fps flip, 30 frames over 1.25 s (`FUN_0068aac0`), floored to a whole frame.
 fn frame_layer() -> i32 {
     return i32(floor(anim_time() * 24.0) % max(w.anim.y, 1.0));
 }
 
 fn apply_scroll(uv: vec2<f32>) -> vec2<f32> {
-    // v += (t mod 10) · 0.1 — repeats/s `[0x801620]` = 0.1, period `[0x80e5a0]` = 10.0 (VERIFIED
-    // wow-re `liquid-uv-scroll-law.md` §5): a sawtooth over exactly one repeat, invisible under
-    // REPEAT wrapping. CONTINUOUS now, where the CPU tick quantized it to 1/24 s — the reference
-    // itself rebuilds the matrix per draw off a millisecond clock, so this is the more faithful
-    // reading, not a new liberty. anim.z is the flag: hard 0 on every non-scrolling lane.
+    // Magma/slime scroll (liquid nibbles 6/7): the reference's stage-0 texture matrix (`0x6b68f0`,
+    // pushed at `0x6b6ae3`) translates v by `fmod(t, 10) · 0.1` (rate `[0x801620]`, period
+    // `[0x80e5a0]`), continuously; its phase is machine uptime, so only rate and period match.
+    // REPEAT wrapping hides the reset.
     return vec2<f32>(uv.x, uv.y + w.anim.z * fract(anim_time() / 10.0));
 }
 
-// Distance fog — planar eye-Z, GL_LINEAR, gamma space (mirrors terrain.wgsl). Applied to EVERY liquid
-// kind, because the reference never disables fog for a liquid batch: the device default for GL_FOG is
-// **ON** (`0x593bf0` writes state id `0x0f` = 1) and all 42 fog-enable setters in the binary are
-// Push/Pop-scoped, so what a batch inherits at its draw is that default. The ADT lava pass sets only
-// cull/lighting/blend (`0x6855ca`/`0x6855d6`/`0x6855e2`) and the WMO magma/slime arm sets only lighting
-// (`0x6b6afe`) — neither touches fog — while the WMO *river* arm goes out of its way to re-assert
-// `(0x0f, 1)`, which only makes sense in a world where fog-on is liquid's intended state. (VERIFIED
-// wow-re `liquid-render-state-sided` §1–§3, §5.)
-//
-// WHICH fog is a per-surface choice, and it is the reference's own (VERIFIED wow-re `fog-env-state`
-// §5, the complete 6-site submit census). The device holds two fog blocks: **block 1** (`+0x70/74/78`)
-// is the scene fog, submitted once a frame from `WorldFrame::Render` (`0x66ff20`), and **block 2**
-// (`+0x80/84/88`) is block 1 smoothed toward the MFOG/zone target over ~4 s (`0x6cf054`+) — the
-// interior haze. Only two call sites in the whole binary re-submit block 2, and they are the WMO
-// *geometry* pass (`0x6b51d9`/`0x6b51ea`) and the WMO *liquid* pass (`0x6b6323`–`0x6b6342`), both under
-// the same `[0xca7f00]` gate. So an interior room's pool takes the room's fog, in lockstep with the
-// walls around it; ADT liquid submits nothing and draws under the scene block. `w.kind.z` is the STATIC
-// half of that gate, resolved at spawn from the group's `MOGI & 0x48`; the per-frame half is the
-// room's own `[0xca7f00]` bit on `MeshTag` bit 30 (decision 1787 — the flood decides it, and the
-// WMO geometry lane reads the same answer, which is what keeps the two in step).
+// Planar eye-Z GL_LINEAR fog in gamma space, as terrain.wgsl; GL_FOG defaults on (`0x593bf0`) and
+// no liquid pass turns it off. Block 1 (`+0x70/74/78`) is the scene fog (`0x66ff20`); block 2
+// (`+0x80/84/88`) is the interior haze, eased toward the MFOG or zone target over about 4 s
+// (`0x6cf054`). Only the WMO geometry pass (`0x6b51d9`/`0x6b51ea`) and the WMO liquid pass
+// (`0x6b6323` to `0x6b6342`) submit block 2, under the room gate `[0xca7f00]`: `w.kind.z` is its
+// static half (`MOGI & 0x48`), `room_fog` the per-frame half.
 fn apply_fog(rgb: vec3<f32>, world_pos: vec3<f32>, room_fog: u32) -> vec3<f32> {
     var fog_color = wow_light.fog_color;
     var fog_span = wow_light.fog_params.xy;
@@ -281,56 +147,27 @@ fn vertex(in: Vertex) -> LiquidVsOut {
 #else
     out.vcolor = vec4<f32>(1.0);
 #endif
-    // Per-vertex MCLQ depth (0..1) packed into UV1.x; drives the opacity ramp.
+    // Depth coordinate V (0..1) in UV1.x: the swatch row on ADT water, the alpha ramp on WMO.
     out.depth = in.uv_b.x;
-    // The faithful per-vertex sun sheen — interpolated across the coarse mesh by the fragment stage.
     out.secondary_vtx = sun_sheen(out.world_normal, out.world_position.xyz);
-    // `MeshTag` bit 30 — see `LiquidVsOut::room_fog`. ADT surfaces carry no tag (0 ⇒ scene fog,
-    // which is their only lane anyway).
+    // ADT surfaces carry no `MeshTag`, so they take the scene fog.
     out.room_fog = mesh_functions::get_tag(in.instance_index) & 0x40000000u;
     return out;
 }
 
-// ── The ADT depth swatch, as the reference actually BUILDS and SAMPLES it ────────────────────
+// ── The ADT depth swatch ─────────────────────────────────────────────────────────────────────
 //
-// `FUN_0068a830` fills an 8×64 texture (U inert — each row is `rep stosd`-replicated across all 8
-// columns, matching the vertex fill's pinned `u = 0.5`). Its rows are an exact 32-bit integer
-// accumulator in **byte space**, not a float lerp:
-//
-//     step   = ((c1 - c0) << 8) >> 6     ; == 4*(c1 - c0) EXACTLY (six zero low bits, so the sar
-//     acc    = c0 << 8 ; acc += step     ;  cannot truncate -> no accumulator drift over 64 rows)
-//     row(i) = (acc >> 8) & 0xff         ; == c0 + floor(i*(c1 - c0) / 64),  i = 0..63
-//
-// Two things that costs us, both missed until wow-re's ocean §5 round (decision 2074):
-//
-//   * **the ramp never reaches the deep endpoint.** Row 63 is `c0 + floor(63*d/64)`, ≈98.4 % of the
-//     way, not `c1`. Our old `mix(shallow, deep, V)` ran the last 1/64 of the ramp that does not
-//     exist.
-//   * **the ocean's last row alone is darkened.** The tail `[0x68a9c0, 0x68aa36)` is gated on *last
-//     row* AND *selector == 0* (ocean; river is selector 1 and gets neither): RGB→HSV,
-//     `0x68aa13 fmul [0x8102ec]` — **V *= 0.9** (`0x3f666666`, the f32 nearest 0.9) — HSV→RGB, then
-//     `0x7bbec0`/`0x7bbec8` forcing that row's alpha to 255. `0x7bbd60`'s HSV→RGB writes every
-//     channel as a product with V and the tail touches neither H nor S (and `S == 0` returns
-//     `(V,V,V)` without reading H, so achromatic input takes no hue shift), so the colour half is
-//     exactly `floor(0.9 * byte)` per channel — transcribed at f32 and run over all 2^24 byte
-//     triples: 99.03 % bit-exact, **max deviation 1/255**.
-//
-// It is not a corner case: ~80 % of the ocean vertices in the shipped world carry depth byte 255,
-// so `V = 1.0` and this row IS the open sea (decision 2069's census).
-//
-// Sampling is **LINEAR/LINEAR, no mip, D3DTADDRESS_CLAMP** — flags word `0x201`, `0x5a2a18 and 7`
-// -> `0x85c7d8` row 1 `{MAG, MIN, MIP} = {2, 2, 0}`, `0x5a2a62 shr 3` -> `0x80a254[0] = 3`;
-// corroborated by a GL capture of this exact texture (8x64, levels 1, CLAMP_TO_EDGE, LINEAR/LINEAR).
-// So V maps to the texel coordinate `V*64 - 0.5` and blends across neighbouring rows: the darkening
-// **ramps in over the final 1/64 of V**, it does not step. That band is the only place any of this
-// is visible on a shore.
-//
-// The WMO arms do NOT come through here — their opacity is a different, 256-entry ramp
-// (`0xca7f10`), whose 1/256 granularity the plain lerp above reproduces.
+// `FUN_0068a830` fills an 8×64 texture, each row the same across its 8 columns, with an exact
+// byte-space integer accumulator, `row(i) = c0 + floor(i * (c1 - c0) / 64)` for i = 0..63, so
+// row 63 stops short of the deep endpoint. On the ocean (selector 0) the last row's HSV value is
+// scaled by 0.9 (`0x68aa13`, `[0x8102ec]`), which `floor(0.9 * byte)` reproduces within 1/255,
+// and its alpha is forced to 255 (`0x7bbec0`/`0x7bbec8`). Sampling is LINEAR, no mip, clamped
+// (flags `0x201`), so V maps to texel `V*64 - 0.5` and the ocean darkening ramps over the last
+// 1/64 of V. The WMO arms use the 256-entry ramp `0xca7f10` instead, which a plain lerp
+// reproduces.
 fn swatch_row(shallow: vec4<f32>, deep: vec4<f32>, i: f32, ocean: bool) -> vec4<f32> {
-    // RGB endpoints arrive already BYTES (`0x68a8fb`/`0x68a902` read two packed dwords straight out
-    // of DayNight state — there is no quantization step for RGB at all); the ALPHA endpoints are
-    // `LightParams` floats the reference quantizes `floor(v*255)` first.
+    // RGB endpoints are bytes already (`0x68a8fb`/`0x68a902`), so they round back exactly; alpha
+    // endpoints are `LightParams` floats the reference quantizes with `floor(v*255)`.
     let c0 = vec4<f32>(round(shallow.rgb * 255.0), floor(shallow.w * 255.0));
     let c1 = vec4<f32>(round(deep.rgb * 255.0), floor(deep.w * 255.0));
     let row = c0 + floor(i * (c1 - c0) / 64.0);
@@ -353,9 +190,7 @@ fn swatch_at(shallow: vec4<f32>, deep: vec4<f32>, v: f32, ocean: bool) -> vec4<f
 
 @fragment
 fn fragment(in: LiquidVsOut) -> @location(0) vec4<f32> {
-    // HARD FAR-CLIP WALL (same as terrain/models, see terrain.wgsl): discard water beyond the
-    // projection far plane so lakes/rivers don't render past the wall. `fog_params.w` = farclip
-    // (0 ⇒ disabled).
+    // The far-clip wall, as terrain and models: discard beyond `fog_params.w` (0 disables it).
     if (wow_light.fog_params.w > 0.0) {
         let clip_z = -(view.view_from_world * vec4<f32>(in.world_position.xyz, 1.0)).z;
         if (clip_z > wow_light.fog_params.w) {
@@ -389,69 +224,32 @@ fn fragment(in: LiquidVsOut) -> @location(0) vec4<f32> {
         view.mip_bias,
     );
 
-    // Magma / slime (kind.x > 0.5): the animated texture IS the opaque body colour — no depth swatch
-    // (the ADT liquid vertex format carries no colour element at all, and the WMO one is a hard
-    // `0xffffffff`, so there is nothing to modulate the sheet by) and no N·L (lighting state 0 on both
-    // paths). It IS fogged, like every other liquid batch.
-    //
-    // The earlier "emissive / no-darken / no fog" reading here was WRONG, and wrong twice over: it came
-    // from the ADT-lava row of `rf-water-liquid-type-texture-material`, which read GX state `0x37` as an
-    // emissive path when `0x37` is the per-stage TEXTURE-MATRIX enable pushing an identity — a texgen
-    // *reset*; and that row is the ADT queue, which never dispatches slime at all (Undercity's slime is
-    // WMO liquid). Skipping fog is what made a submerged slime surface a flat unshaded sheet at any
-    // depth instead of one that recedes into the murk. (VERIFIED wow-re `liquid-render-state-sided`
-    // §3/§3.1/§5, which corrects that row.)
+    // Magma/slime: the sheet is the opaque body, unmodulated (the ADT vertex has no colour, the WMO
+    // one is `0xffffffff`) and unlit (lighting off on both paths), but fogged.
     if (w.kind.x > 0.5) {
         return vec4<f32>(apply_fog(detail.rgb, in.world_position.xyz, in.room_fog), 1.0);
     }
 
-    // Per-vertex swatch coord V (in `in.depth`, computed CPU-side in wow-formats/liquid.rs): river/lake
-    // = `clamp(byte/42)` (VERIFIED WoW.exe `c81768` LUT / `FUN_0068d790`, saturating ~5 yd so the channel
-    // middle reaches the deep/teal row), ocean = `clamp(byte/255)` (VERIFIED `c7fcd8` / `FUN_0068d690`,
-    // its own LUT on its own authored byte scale — decision 2069). The depth swatch
-    // is a plain 2-endpoint lerp (`FUN_0068a830`), so a SINGLE V indexes BOTH the colour and the alpha
-    // row: colour `shallow→deep` and opacity `shallow_α→deep_α` track together. (Earlier `×4` colour
-    // compression + the gentle `byte/255` V were band-aids for a wrong "V tops at 0.31" belief — removed.)
+    // V, from the authored depth byte CPU-side: clamp(byte/42) on river/lake (LUT `0xc81768`,
+    // `FUN_0068d790`, saturating near 5 yd), clamp(byte/255) on ocean (LUT `0xc7fcd8`,
+    // `FUN_0068d690`), both built in `FUN_0068c4c0`. One V indexes colour and alpha alike.
     let depth = clamp(in.depth, 0.0, 1.0);
-    // The kind's swatch endpoints, off the shared light: ocean reads rows 15/16 (IntBand 14/15),
-    // river/lake rows 13/14 (IntBand 16/17). Both are packed every frame by `build_light_data`.
     var shallow = wow_light.water_river[0];
     var deep = wow_light.water_river[1];
     if (w.kind.y > 0.5) {
         shallow = wow_light.water_ocean[0];
         deep = wow_light.water_ocean[1];
     }
-    // ---- The two WMO water arms ------------------------------------------------------------
-    //
-    // Neither is the ADT combine below. `0x6b62e0`'s category 0 splits on the owning group's
-    // `MOGP.flags & 0x48`, and both halves bind ONE texture (the animated sheet) with no depth ramp
-    // anywhere — there is not a single reference to the ADT ramp globals `0xc7fbc0`/`0xc81768`/
-    // `0xc7fcd8` in all of `[0x6b0000, 0x6c4000)`. Opacity on both is the per-vertex authored byte
-    // through the zone's linear alpha ramp, which `in.depth` carries and this lerp reproduces
-    // (`wmo_water_alpha_v`). VERIFIED wow-re `terrain/scratch/water-shading-law.md` §11.
+    // ---- The WMO water arms: opacity is the per-vertex authored byte through the zone's linear
+    // alpha ramp, carried in `in.depth`.
     let vtx_alpha = mix(shallow.w, deep.w, depth);
     if (w.path.x > 1.5) {
-        // ---- WMO INTERIOR (`0x6b6420`) — 134 of the game's 164 water groups, Blackfathom included.
-        //
-        // Fixed-function, always: the kernel body contains no `mov ecx,0x3f` at all (a positive
-        // finding — the same scan on the exterior kernel finds two), and `[0xc9607c]`, the
-        // specular/pixelShaders gate, is never read on this path. So it ignores those CVars, runs
-        // with lighting OFF (`0x0e = 0`) and fog ON (`0x0f = 1`), and its whole output is the
-        // combine preset `(0x1f, 3)` over one texture stage:
-        //
+        // ---- WMO interior (`0x6b6420`): fixed-function whatever the CVars (`[0xc9607c]` unread),
+        // lighting off (`0x0e = 0`), fog on (`0x0f = 1`), combine preset `(0x1f, 3)`:
         //     rgb = clamp(Cf + Ct)      alpha = clamp(Af + At)
-        //
-        // `Cf` is the pool's `MOMT[materialId].diffColor` taken RAW — baked into the mesh's vertex
-        // colour, which is where the reference's own 6-float vertex carries it. NO sun term and no
-        // sheen: that vertex has no normal to compute one from.
-        //
-        // The ALPHA op is the part worth stating. Preset 3 is `GL_ADD` on both channels via
-        // `GL_COMBINE` (`COMBINE_ALPHA = GL_ADD` @`0x85c2fc`, operands left at the GL default), NOT
-        // the legacy `GL_TEXTURE_ENV_MODE = GL_ADD` whose alpha would be `Af · At`. The client takes
-        // the COMBINE path because `GL_ARB_texture_env_combine` is GL 1.3 core. So the ripple **adds**
-        // to the pool's opacity instead of multiplying it away — a pool is at its authored opacity in
-        // the troughs and saturates opaque on the crests, which is the opposite of what the legacy
-        // reading would have drawn.
+        // Cf is the pool's raw `MOMT.diffColor`; the vertex has no normal, so no sun and no sheen.
+        // Preset 3 is `GL_ADD` through `GL_COMBINE` on both channels (`COMBINE_ALPHA` at
+        // `0x85c2fc`), so the ripple adds to the pool's opacity rather than multiplying it.
         let body = clamp(in.vcolor.rgb + detail.rgb, vec3<f32>(0.0), vec3<f32>(1.0));
         return vec4<f32>(
             apply_fog(body, in.world_position.xyz, in.room_fog),
@@ -459,42 +257,14 @@ fn fragment(in: LiquidVsOut) -> @location(0) vec4<f32> {
         );
     }
     if (w.path.x > 0.5) {
-        // ---- WMO EXTERIOR (`0x6b6630`) — Stormwind's canals and fountains.
-        //
-        // This arm DOES bind a pixel program, `Shaders\Pixel\MapObjExtWater0.bls` (bound at
-        // `0x6b6654`, unbound `0x6b689c`), under the `[0xc9607c]` specular/pixelShaders gate. Both
-        // CVars default to "0", but our reference install's `Config.wtf` sets both to "1", so the
-        // shader leg is what every director comparison is against and it is the leg we implement.
-        // Decoded verbatim from the asset:
-        //
+        // ---- WMO exterior (`0x6b6630`): `Shaders\Pixel\MapObjExtWater0.bls` (bound `0x6b6654`),
+        // the shader leg of the `[0xc9607c]` gate:
         //     rgb = primary.rgb + detail.rgb + secondary·detail.a      alpha = primary.a
-        //
-        // **No `+0.25`.** That constant is the ADT program's own `PARAM` and has no counterpart
-        // here, so carrying it over — which is what we did — added a flat achromatic lift to every
-        // canal pixel at all times, sun or no sun. Against the sheet's real texel distribution that
-        // is ~3.5x the ripple contrast off the glint, and it is why the reference's canal shimmers
-        // only where the sun is while ours sparkled everywhere.
-        //
-        // `primary` is FFP-lit over a constant up-normal with the vertex colour tracked into
-        // ambient+diffuse (`glColorMaterial(GL_FRONT_AND_BACK, GL_AMBIENT_AND_DIFFUSE)`), so the band
-        // is the MATERIAL colour and `primary = band · clamp(ambient + diffuse·max(N·L, 0))`.
-        // Lighting really is on here: neither this kernel nor its dispatch touches render-state id
-        // `0x0e`, and the control that such a call would be findable is the interior kernel, which
-        // does exactly that at `0x6b65bf`.
-        //
-        // The band is a SINGLE one — there is no bathymetry to lerp by — and it is the **deep** river
-        // row, `LightIntBand` sub-17, i.e. `water_river[1]`. Read as a hard immediate
-        // (`0x6b66be add edi, 0xec`), so nibbles 0, 4 and 8 all take it; exterior ocean cannot arise
-        // (category 2 falls to a bare epilogue with no draw).
-        //
-        // **Sub-17, not sub-16, and the distinction cost a round trip.** A DayNight band *slot* is not
-        // a `LightIntBand` *sub*: `0x6d64d0` displaces sub-8 out to record `+0x4c`, so `sub = slot + 1`
-        // across slots 8–16, and the kernel's slot 16 is sub-17. The shipped data says the same thing
-        // twice over — across all 367 LightParams rows carrying river bands, sub-16 is browns, olives
-        // and muddy yellows (G > B in 71%: the shallow colour of water over a riverbed) while sub-17 is
-        // blues and teals. At Stormwind sub-16 is `(79, 93, 20)`, which renders the canals olive-green;
-        // sub-17 is `(51, 82, 85)`. The ADT ramp runs sub-16 → sub-17 across its 64 texels; WMO
-        // exterior water takes the deep end alone, flat.
+        // No `+0.25`, which is the ADT program's own. Lighting is on (`0x0e` never set), so
+        // primary = band · clamp(ambient + diffuse·max(N·L, 0)), the band one flat colour for
+        // every nibble: the deep river row, `LightIntBand` sub-17 (`water_river[1]`), an immediate
+        // at `0x6b66be`. A DayNight slot is not a sub: `0x6d64d0` moves sub-8 out to `+0x4c`, so
+        // the kernel's slot 16 is sub-17.
         let n_ext = normalize(in.world_normal);
         let to_light_ext = -normalize(wow_light.light_sun.xyz);
         let primary_ext = clamp(
@@ -504,12 +274,12 @@ fn fragment(in: LiquidVsOut) -> @location(0) vec4<f32> {
             vec3<f32>(1.0),
         ) * deep.rgb;
         let rgb_ext = primary_ext + detail.rgb + in.secondary_vtx * detail.a;
-        // `result.color.w = fragment.color.primary` — the vertex alpha ALONE. The bound program
-        // bypasses the texture environment entirely, so the interior arm's `+ At` does not apply here.
+        // Alpha is `fragment.color.primary` alone: the bound program bypasses the texture
+        // environment, so the interior arm's `+ At` does not apply.
         return vec4<f32>(apply_fog(rgb_ext, in.world_position.xyz, in.room_fog), vtx_alpha);
     }
 
-    // Body colour: lit vertex colour × the depth-lerped water-row swatch colour (`primary·colorTex`).
+    // The ADT arm. `primary`: the lit white vertex.
     let n = normalize(in.world_normal);
     let to_light = -normalize(wow_light.light_sun.xyz);
     let ndotl = max(dot(n, to_light), 0.0);
@@ -519,33 +289,19 @@ fn fragment(in: LiquidVsOut) -> @location(0) vec4<f32> {
         vec3<f32>(1.0),
     );
 
-    // Sun sheen (`secondary`): the `ocean0_s.bls` Blinn highlight, computed PER-VERTEX in `fn vertex`
-    // and interpolated across the coarse ~4 yd MCLQ mesh — the faithful 1.12 path (the real client
-    // evaluates it in its FFP vertex stage). Per-pixel evaluation of the sharply-peaked `pow(N·H,6)`
-    // would fill its broad lobe at full value (a brighter, denser sheen); interpolating from the
-    // vertices flattens the peak to match the reference. (A per-pixel/per-vertex A/B toggle proved the
-    // two visually identical on our mesh — we keep per-vertex as the faithful mechanism; RE:
-    // `docs/knowledge/scratch/liquid-depth/fleck-deep.md`.)
     let secondary = in.secondary_vtx;
 
-    // The stage-0 depth swatch, built and sampled as the reference does (see `swatch_row`): a
-    // byte-space 64-row ramp that stops short of the deep endpoint, LINEAR across rows, with the
-    // ocean's last row darkened `floor(0.9*byte)` and its alpha forced opaque.
+    // colorTex: the stage-0 depth swatch.
     let swatch = swatch_at(shallow, deep, depth, w.kind.y > 0.5);
 
-    // primary·colorTex.rgb  +  detail.rgb  +  (secondary + 0.25)·detail.a   (the ocean0_s.bls math)
+    // The `ocean0_s.bls` combine.
     var rgb = primary * swatch.rgb + detail.rgb + (secondary + vec3<f32>(0.25)) * detail.a;
 
-    // Opacity: depth ramp between the shallow/deep LightParams water alphas, over the SAME V as the
-    // colour. Deeper = more opaque, up to α=1.0 where V saturates (river/lake byte 42 ≈ 5 yd), so the
-    // channel middle is opaque + teal while the shore stays semi-transparent (V→0, α≈0.5) and the bottom
-    // shows through (faithful — the pale edge band). One steep V drives both colour and opacity together.
+    // `colorTex.a`, over the same V as the colour: deeper water is more opaque.
     let alpha = swatch.w;
 
-    // Distance fog (see `apply_fog`) — the water fog colour is also teal, so far water converges on the
-    // haze.
     rgb = apply_fog(rgb, in.world_position.xyz, in.room_fog);
 
-    // GAMMA LANE (0161): raw gamma out; alpha blends in gamma like the reference's bytes.
+    // Raw gamma out; alpha blends in gamma space like the reference's bytes.
     return vec4<f32>(rgb, alpha);
 }
diff --git a/crates/benilla-assets/src/shaders/terrain.wgsl b/crates/benilla-assets/src/shaders/terrain.wgsl
index 5f6ae40b..dbbd71d5 100644
--- a/crates/benilla-assets/src/shaders/terrain.wgsl
+++ b/crates/benilla-assets/src/shaders/terrain.wgsl
@@ -1,29 +1,13 @@
-// Phase 6 terrain splat shader — extends Bevy's StandardMaterial with a CUSTOM vertex + fragment stage.
+// Terrain splat shader: a custom vertex and fragment stage on Bevy's StandardMaterial. Blends up to
+// four tiled layers by a per-chunk alpha map, lit as the reference's fixed-function terrain:
+//   diffuse  = clamp(ambient (row 1) + diffuse (row 0)·max(N·L, 0) + Σ point·att·N·L), evaluated
+//     and clamped per vertex (GL T&L), Gouraud-interpolated, modulated 1× into the texture;
+//   specular = clamp(row 9 · max(N·H, 0)^20) per vertex (local viewer), times the sheen mask (the
+//     `_s` texture's per-texel alpha, blended like the colour), added after the modulate.
+// Evaluated per pixel, or unmasked, the near-white row 9 would wash lit ground to cream.
 //
-// Blends up to 4 tiled layer textures by a per-chunk alpha map, then lights the result with WoW's
-// faithful terrain lighting (fixed-function GL_LIGHTING, reproduced):
-//   • DIFFUSE — `clamp(ambient_row1 + diffuse_row0·max(N·L,0) + Σ point·att·N·L)`, modulated into
-//     the texture (MOD 1×). Evaluated AND CLAMPED per VERTEX (the GL T&L locus), then
-//     Gouraud-interpolated — the clamp position matters once an over-gamut point light is in the
-//     sum (see the `primary` varying note).
-//   • SPECULAR (the bare-ground "sheen") — `clamp(row9 · pow(max(N·H,0),20)) · sheen_mask`, added
-//     AFTER the texture modulate (separate-specular, LOCAL_VIEWER). The Blinn term is computed
-//     PER-VERTEX (clamped per vertex, Gouraud-interpolated); the `sheen_mask` is the `_s` texture's
-//     per-texel ALPHA, blended like the colour (so the sheen rides only shiny texels — stone, not
-//     grass). See docs/knowledge/lighting.md
-//     ⚠️ Two things bound it, BOTH needed (each was a separate blow-out): (a) per-vertex undersampling
-//     of the sharp lobe (sampled only at the ~4 yd MCVT vertices, clamped, linearly smeared) vs a
-//     per-PIXEL eval that saturates; (b) the `_s` alpha sheen-mask (ref mean ≈ 0.1) vs applying it at
-//     a uniform 1.0 — row 9 ≈ near-white, so unmasked it washes the whole lit face to cream.
-//
-// Because Bevy's `VertexOutput` has no slot for the interpolated specular, we do our own (minimal)
-// vertex transform and a custom IO struct, and drop `main_pass_post_lighting_processing` (fog returns
-// IN-SHADER at Step 5, per docs/plans/lighting-rebuild.md — not Bevy's DistanceFog).
-//
-// One material serves a whole ADT tile (see terrain.rs): layer textures live in a `texture_2d_array`
-// (binding 100), per-chunk alpha maps in another (104). Each merged-mesh vertex carries its chunk's 4
-// layer indices in `color` (vertex COLOR) and its alpha-layer index in `uv_b.x` (UV1) — constant across
-// the chunk, so interpolation lands back on the integer index.
+// Bevy's `VertexOutput` has no slot for the interpolated specular, so the vertex transform and IO
+// struct are our own and `main_pass_post_lighting_processing` is dropped; fog is in-shader.
 
 #import bevy_pbr::{
     mesh_functions,
@@ -52,15 +36,12 @@ struct TerrainParams {
 };
 @group(#{MATERIAL_BIND_GROUP}) @binding(106) var<uniform> t: TerrainParams;
 
-// The shared global light (lighting::global_light): ONE storage buffer every material reads, updated
-// once/frame in place — replaces the per-material light/fog uniforms `apply_wow_lighting` re-pushed
-// each frame. Rows 0-5 (of the 18-row LightStd430) are the light + fog terrain needs, plus the grade
-// row at the end (rows 6-16 — model SH + water swatches — are skipped as a pad). Read in BOTH stages
-// (the per-vertex sheen needs light_sun/spec in the vertex stage).
+// The shared global light (`lighting::global_light`), updated in place once a frame; this mirrors
+// its row layout, which must match.
 struct WowLight {
     light_ambient: vec4<f32>, // rgb = row 1 ambient; w = Mod2x scale (×1).
     light_diffuse: vec4<f32>, // rgb = row 0 sun diffuse; w = clamp-light flag (>0.5 ⇒ saturate).
-    light_sun: vec4<f32>,     // xyz = world-space sun TRAVEL direction (to-light = −xyz); w unused.
+    light_sun: vec4<f32>,     // xyz = world-space sun travel direction (to-light = −xyz); w unused.
     light_spec: vec4<f32>,    // rgb = row 9 specular color; w = shininess (20). rgb == 0 disables.
     fog_color: vec4<f32>,     // rgb = row 7 fog (raw, gamma 0..1); w = enable (>0.5 ⇒ blend).
     fog_params: vec4<f32>,    // x = fog_start yd; y = fog_end yd; z = signed +sun / -moon shadow weight; w = farclip wall.
@@ -249,14 +230,9 @@ struct TerrainVsOut {
     @location(3) uv_b: vec2<f32>,
     @location(4) color: vec4<f32>,
     @location(5) specular: vec3<f32>,
-    // The full Gouraud diffuse — `clamp01(ambient + sun·max(N·L,0) + Σ point·att·N·L)`, evaluated
-    // AND CLAMPED per VERTEX: the GL T&L locus. The clamp position is load-bearing for a hot
-    // carried light (the raw committed torch is (1.4, 0.87, 0.40)): GL clamps the summed vertex
-    // colour BEFORE interpolation, so an over-gamut torch saturates one vertex and Gouraud falls
-    // linearly away from it. Interpolating the raw sum and clamping per pixel — what we did
-    // before — keeps pixels pinned at white far from the hot vertex: a wide flat plateau with a
-    // hard knee, the director's "hard square". Sun N·L moving per-pixel → per-vertex is the
-    // faithful direction (Step 3's own note: indistinguishable on the smooth term).
+    // The Gouraud diffuse, summed and clamped per vertex as GL T&L does: an over-gamut light (a
+    // carried torch is (1.4, 0.87, 0.40)) saturates one vertex and falls off linearly from it,
+    // where clamping per pixel would pin a wide plateau at white.
     @location(6) primary: vec3<f32>,
     // The receiver normal is carried so the real cascaded shadow lookup can apply a slope-aware
     // bias. This is forward-pass data only; the terrain shadow caster is a stock Bevy proxy.
@@ -285,11 +261,10 @@ struct TerrainVsOut {
     @location(10) point_lit: vec3<f32>,
 }
 
-// Terrain's point-light **candidacy half-width** (yd): the reference's guaranteed covered box is
-// `w + 10` where `w` is the chunk's bounding-sphere radius — `sqrt(2·16.666666² + (zExtent/2)²)`,
-// i.e. 23.570166 on flat ground (`0x68df70` hard-codes that same constant at `68dfac`). Relief
-// widens a chunk's own `w`; we use the flat value, so on steep ground we gather very slightly
-// narrower than the reference — the lights that differ are ≥33 yd out, where `att ≈ 0.02`.
+// Terrain's point-light candidacy half-width (yd): `w + 10`, `w` being the chunk's bounding-sphere
+// radius `sqrt(2·16.666666² + (zExtent/2)²)`, 23.570166 on flat ground (constant at `0x68dfac`).
+// This takes the flat `w` everywhere, so steep chunks gather slightly narrower than the reference;
+// the lights that differ are 33 yd out or more, where att ≈ 0.02.
 const TERRAIN_REACH: f32 = 33.570166;
 
 // The dynamic point-light term at a world-space point (decisions 0016/0273/0278, selection 0285) —
@@ -548,23 +523,13 @@ fn point_light_eval_shadowed(sel: vec4<u32>, P: vec3<f32>, N: vec3<f32>) -> vec3
     return sum;
 }
 
-// The MCNK chunk cell center under a world point — terrain's light-selection anchor (the terrain
-// draw unit; the grid is fixed world-wide, chunk = 533.3333/16 yd, half-extent 32 tiles). WoW x/y
-// are Bevy −z/−x and the grid is symmetric, so snapping Bevy x/z directly lands on the same cells.
-//
-// **The XY snap is VERIFIED** (wow-re `terrain-dynamic-light-gather.md`: `CMapChunk+0x5c..0x64` is
-// the chunk's world AABB centre, written by the MCVT world-vert builder `0x6b0e50` at
-// `6b106c`/`6b10ec`, and the 33.33-yd chunk really is the draw unit — gather → commit → draw pair
-// 1:1 per record at `68478a`/`68479c`/`6847bb`/`6847c4`).
-//
-// **The height is KNOWN-WRONG and deliberately not fixed here.** The reference's anchor Z is the
-// chunk's own mid-height `(minH + maxH)/2` over its 145 verts — one constant per chunk. We keep the
-// vertex's own y, which means the anchor VARIES within a chunk, so on relief two vertices of the
-// same chunk can select different light sets and seam mid-chunk — the reference cannot do that.
-// Fixing it needs a per-chunk constant plumbed to the vertex stage (a custom mesh attribute + a
-// `specialize` on the terrain material, which has none today), so it is scoped as its own change;
-// on flat ground the two anchors coincide and nothing differs. Mirrored in wow_model.wgsl (clutter
-// snaps to the same cells).
+// The MCNK chunk cell centre under a world point: the reference's light anchor, the chunk's world
+// AABB centre `CMapChunk+0x5c..0x64` (written by `0x6b0e50`). The grid is fixed world-wide (chunk
+// 533.33333/16 yd, half-extent 32 tiles) and symmetric, and WoW x/y are Bevy −z/−x, so snapping
+// Bevy x/z lands on the same cells; wow_model.wgsl mirrors it for clutter.
+// The anchor height is the vertex's own y, not the chunk's mid-height `(minH + maxH)/2`, so on
+// relief one chunk's vertices can select different lights: the per-chunk constant is not plumbed
+// to the vertex stage. On flat ground the two agree.
 fn mcnk_cell_anchor(P: vec3<f32>) -> vec3<f32> {
     let cell = 533.33333 / 16.0;
     let half = 32.0 * 533.33333;
@@ -591,9 +556,8 @@ fn vertex(in: Vertex) -> TerrainVsOut {
     out.uv_b = in.uv_b;
     out.color = in.color;
 
-    // STEP 3b: terrain SUN SPECULAR, computed PER-VERTEX (Q14). Material spec = white, shininess =
-    // wow_light.light_spec.w (20), spec color = row 9 (wow_light.light_spec.rgb); H = halfway(to-light, to-eye) with
-    // the LOCAL viewer (per-vertex eye dir). Clamp HERE, per vertex — rasterizer Gouraud-interpolates.
+    // Sun specular per vertex: white material, row-9 colour, shininess `light_spec.w` (20), local
+    // viewer; clamped here, then Gouraud-interpolated.
     let n = normalize(world_normal);
     let l = -normalize(wow_light.light_sun.xyz); // to-light (the sun travels along +light_sun)
     let v = normalize(view.world_position.xyz - out.world_position.xyz); // to-eye (local viewer)
@@ -628,11 +592,8 @@ fn vertex(in: Vertex) -> TerrainVsOut {
 
 @fragment
 fn fragment(in: TerrainVsOut) -> @location(0) vec4<f32> {
-    // HARD FAR-CLIP WALL (faithful `farclip`): the reference clips the detailed world at its projection
-    // far plane (~777 yd). Geometry beyond is GPU-clipped per-pixel, so a tall object reveals
-    // closest-part-first as you approach and the sky/WDL shows behind it. We reproduce that with a
-    // per-fragment discard on PLANAR eye-Z (same coordinate as the fog) beyond `fog_params.w` = farclip
-    // (0 ⇒ disabled). WDL/sky use other shaders, so they still render to the horizon behind the wall.
+    // The far-clip wall: the reference clips the detailed world per pixel at its far plane
+    // (`farclip`, about 777 yd). Discard beyond `fog_params.w` (0 disables) on planar eye-Z.
     if (wow_light.fog_params.w > 0.0) {
         let clip_z = -(view.view_from_world * vec4<f32>(in.world_position.xyz, 1.0)).z;
         if (clip_z > wow_light.fog_params.w) {
@@ -640,27 +601,21 @@ fn fragment(in: TerrainVsOut) -> @location(0) vec4<f32> {
         }
     }
 
-    // Per-chunk array indices, baked into the merged mesh: COLOR = 4 layer indices, UV1.x = alpha.
+    // Per-chunk array indices baked per vertex, COLOR the 4 layers and UV1.x the alpha; constant
+    // across a chunk, so they interpolate back to the integer.
     let li = vec4<i32>(round(in.color));
     let ai = i32(round(in.uv_b.x));
 
     let tiled = in.uv * t.params.x;
-    // Full RGBA: `.rgb` = diffuse, `.a` = the `_s` texture's per-texel SHEEN MASK (see assets.rs /
-    // terrain.rs — the base `.blp` has no alpha, so we load the `_s` variant; matte where no mask).
-    // `view.mip_bias` (decision 1639): a render scale below 1 doubles every derivative and so
-    // picks a coarser mip, and that blur is then stretched back up by the resolve. The bias undoes
-    // exactly that shift and is 0.0 at native and above, so this is an identity at scale 1.
-    // Only the LAYER array takes it: `alpha_array`/`shadow_array` are one 64x64 grid per chunk,
-    // built with a single mip level (terrain.rs `array_image`), so no bias could move them.
+    // `.a` is the `_s` texture's sheen mask, 0 without an `_s`. `view.mip_bias` undoes the coarser
+    // mip a render scale below 1 picks; the alpha and shadow arrays have one mip, so only the
+    // layers take it.
     let s0 = textureSampleBias(layer_array, splat_samp, tiled, li.x, view.mip_bias);
     let s1 = textureSampleBias(layer_array, splat_samp, tiled, li.y, view.mip_bias);
     let s2 = textureSampleBias(layer_array, splat_samp, tiled, li.z, view.mip_bias);
     let s3 = textureSampleBias(layer_array, splat_samp, tiled, li.w, view.mip_bias);
-    // Alpha + shadow maps are one 64² grid per chunk in 0..1 (NOT tiled), yet they share the layer
-    // textures' Repeat sampler. The old "repeat == clamp here" assumption is FALSE under LINEAR
-    // filtering: at a chunk edge (uv→0/1) the bilinear footprint WRAPS to the chunk map's opposite
-    // edge, blending unrelated weights → a thin seam at every chunk border (the creases; introduced
-    // when 228d336 switched Nearest→Linear). Inset by half a texel so the footprint clamps instead.
+    // The alpha and shadow maps (one untiled 64² grid per chunk) share the layers' repeat sampler,
+    // so a linear footprint at a chunk edge would wrap to the far edge; a half-texel inset clamps.
     let auv = clamp(in.uv, vec2<f32>(0.5 / 64.0), vec2<f32>(1.0 - 0.5 / 64.0));
     let a = textureSample(alpha_array, splat_samp, auv, ai);
 
@@ -669,10 +624,8 @@ fn fragment(in: TerrainVsOut) -> @location(0) vec4<f32> {
     color = mix(color, s2.rgb, a.g);
     color = mix(color, s3.rgb, a.b);
 
-    // Sheen mask: blend the layers' `_s` alpha with the SAME splat weights as the colour, so the sun
-    // specular rides only the shiny texels (stone/pebbles), not matte grass/dirt. This per-pixel mask
-    // is what bounds the highlight — the real client's mask averages ≈ 0.1 (Q14); applying the sheen at
-    // a uniform 1.0 is what blew out the floor. (FP: `secondary · texture[0].w`.)
+    // The sheen mask, blended with the colour's splat weights (the fragment program's
+    // `secondary · texture[0].w`).
     var specmask = s0.a;
     specmask = mix(specmask, s1.a, a.r);
     specmask = mix(specmask, s2.a, a.g);
@@ -756,11 +709,10 @@ fn fragment(in: TerrainVsOut) -> @location(0) vec4<f32> {
         primary = clamp(in.base_lit * shadow_terms.y + points, vec3<f32>(0.0), vec3<f32>(1.0));
     }
 
-    // STEP 4: MCSH baked shadow. On the reference path (pixelShaders+specular) terrain is ONE pass
-    // through `terrainp_s.bls`, which carries the MCSH bit in the blend texture's alpha (1.0 lit / 0.0
-    // shadowed) and uses it TWO ways (Q15) — NOT the Q11 separate ambient-tint overlay (that's the
-    // legacy/non-pixelShaders path). Our `shadow_array` R8 is 255=shadowed/0=lit, so `shadow_lit =
-    // 1 - mcsh`. Chunks with no MCSH map (`uv_b.y < 0`) are fully lit.
+    // MCSH baked shadow. With `pixelShaders` and `specular` on, terrain is one pass through
+    // `terrainp_s.bls`, which reads the MCSH bit from the blend texture's alpha (1 lit, 0 shadowed)
+    // and uses it twice, below; with them off the reference draws a separate ambient-tint overlay.
+    // Our `shadow_array` is 255 shadowed, 0 lit; a chunk with no MCSH map (`uv_b.y < 0`) is lit.
     var shadow_lit = 1.0;
     let si = in.uv_b.y;
     if (si >= 0.0) {
@@ -829,8 +781,7 @@ fn fragment(in: TerrainVsOut) -> @location(0) vec4<f32> {
         tuned = mix(wow_light.fog_color.xyz, tuned, factor);
     }
 
-    // GAMMA LANE (decision 0161): the framebuffer HOLDS gamma bytes — all blending happens in
-    // gamma exactly like the reference's byte framebuffer; the frame's ONE decode lives in the
-    // FFXGlow combine (the last node). Output raw.
+    // Raw gamma out: the framebuffer holds gamma bytes and blends in gamma like the reference's;
+    // the frame's one decode is the FFXGlow combine.
     return vec4<f32>(tuned, 1.0);
 }
diff --git a/crates/benilla-assets/src/shaders/wdl.wgsl b/crates/benilla-assets/src/shaders/wdl.wgsl
index c958710a..69d4e93b 100644
--- a/crates/benilla-assets/src/shaders/wdl.wgsl
+++ b/crates/benilla-assets/src/shaders/wdl.wgsl
@@ -1,56 +1,14 @@
-// WDL distant-terrain shader — the coarse horizon hills the reference draws beyond the streamed
-// detailed tiles (docs/knowledge/terrain.md "WDL"). Both stages custom.
+// WDL distant terrain: the coarse horizon hulls the reference draws past the detailed tiles,
+// unlit, untextured, white vertex diffuse fogged with the scene's fog colour. The hull emitter
+// `0x6bd780` sets its own fog pair, start 0 and end 1.0 (`0x6bd7ae`-`0x6bd7c8`), so beyond one
+// yard the hull is the flat fog colour: a silhouette against the unfogged sky.
 //
-// The reference draws WDL UNLIT + UNTEXTURED with white vertex diffuse under the scene's fog COLOUR
-// (VERIFIED apitrace WoW.8: prog 96 vertex-white, fog.color matching the zone haze) — but NOT under
-// the scene's fog DISTANCES. The hull emitter `0x6bd780` submits its own pair right before the draw
-// (byte-read at `0x6bd7ae`–`0x6bd7c8`: `push 0; mov ecx,0xA; call 0x589e30` = fog start 0, then
-// `push 1.0f; mov ecx,0xB; call 0x589e30` = fog end 1.0; wow-re `fog-env-state.md` §5's submit
-// census, decision 1521). Linear fog `f = (end − z)/(end − start) = 1 − z` is zero for every fragment
-// beyond one yard, so the hull is the fog colour, FLAT, at every distance — a "fog hull", which is
-// what the binary calls it. What the band contributes is therefore pure silhouette: fog-coloured
-// hills occluding the (un-fogged) sky. Gamma handling mirrors terrain.wgsl: the output is raw gamma
-// — the buffer holds bytes and the frame's one decode lives in the FFXGlow combine (GAMMA LANE, 0161).
-//
-// It used to read the scene distances (`fog_params.xy`, start = frac × end, end = min(zone end, farclip))
-// and fog the white hull with them like a surface. Past the wall that is the same pure haze — but the
-// 33 yd overlap below (`WDL_OVERLAP`) then sat INSIDE the fog ramp, mixed toward WHITE by up to
-// `33 / (end − start)` = `44 / farclip` at the usual 0.25 start fraction: 25% at 177, 15% at 297, 13% at
-// 350 — and 0 whenever the zone's own fog ends nearer than `farclip`, which is why the default 777 never
-// showed it. Wherever the coarse hull rides above the fine mesh along a grazing ray — a crater rim, a
-// dip the 33-yd sampling bridges — that pale hull showed above the fine terrain's fogged-out silhouette
-// as a band brightest at its lower edge and fading upward, growing as the view distance dropped (the
-// director's "white from beyond the cutoff showing through the fog", decision 1521).
-//
-// ## The far band is a BACKDROP, not the far half of a plane partition (decision 0684)
-//
-// The reference's far-band pass (`CWorldScene` drain `0x6841a0`, wow-re `terrain.md` + `rf35-render-list`)
-// does NOT share a clip plane with the detailed world. It draws the coarse hulls under its own
-// projection — `SetPerspective(fov, aspect, near = farclip − 33.0, far = horizonfarclip)`, byte-read at
-// the two call sites `0x6842f2` (render) / `0x68317f` (the far walk's cull frustum), the `33.0` at
-// `[0x8101b0]`, the horizon far from the runtime box `[0xc7b49c]` — into a **compressed depth range
-// `[0.955, 0.96]`** (`[0x80febc]=0.96`, `[0x80fec4]=0.005`), i.e. squashed into the back half-percent of
-// the depth buffer so it can never occlude anything the detailed world drew. Two properties fall out,
-// and BOTH are load-bearing:
-//
-//   * the band **overlaps** the detailed world by 33 yd (≈ one WDL outer cell, spacing 33.333) — so a
-//     coarse hull that crosses back inside the wall is still drawn, and no hole can open at the seam;
-//   * it is **depth-pushed**, never near-clipped at the wall — so that overlap cannot poke through the
-//     fine terrain, and nothing coarse near the camera can paint over the sky (its near plane stops it).
-//
-// We used to partition instead: terrain discarded past `farclip`, WDL discarded before it, sharing one
-// plane with zero overlap. Two different surfaces cannot partition cleanly at one plane — wherever a ray
-// grazed the coarse hull entirely INSIDE the wall while the fine mesh it approximates lay beyond it (a
-// ridge crest, exactly), both passes discarded and the sky showed through as a band at the horizon
-// (the director's "in-between area at the clip barrier", Weazel's Crater, 2026-07-26).
-//
-// Our depth buffer is Bevy's infinite REVERSE-Z (`perspective_infinite_reverse_rh`: depth = near/eye_z,
-// 0 = infinitely far, and never exactly 0 for finite geometry), so the reference's `[0.955, 0.96]`
-// window becomes a clamp rather than a `glDepthRange`: every detailed-world fragment lives at
-// `depth ≥ near/farclip` (it is discarded past the wall), so clamping WDL just below that value puts the
-// whole band behind the world by construction, while leaving it in front of the sky's forced `0.0`
-// (`sky_order.rs`, "The depth law"). Order of the three backdrop tiers, all decided by depth and nothing
-// else: sky (0.0) → WDL band → detailed world.
+// The band is a backdrop, not the far half of a shared clip plane. The reference's far-band pass
+// (`0x6841a0`, projection at `0x6842f2`) uses near `farclip - 33` (`[0x8101b0]`) and the depth
+// range `[0.955, 0.96]` (`[0x80febc]` = 0.96, `[0x80fec4]` = 0.005): the band overlaps the detailed
+// world by 33 yd, closing the seam, and stays behind all of it. On Bevy's infinite reverse-Z
+// (depth = near / eye_z) that range becomes a clamp just below `near / farclip`, the farthest
+// depth the detailed world keeps (it discards past the wall), still in front of the sky's 0.0.
 
 #import bevy_pbr::{
     mesh_functions,
@@ -59,21 +17,16 @@
     mesh_view_bindings::view,
 }
 
-/// How far the far band reaches back INSIDE the detailed world's far-clip wall — the reference's
-/// far-band near plane `farclip − 33.0` (`[0x8101b0]`, one WDL outer cell). This overlap is what
-/// closes the coarse-vs-fine seam; the depth clamp below is what keeps it harmless.
+/// How far the band reaches inside the far-clip wall: the reference's far-band near plane
+/// `farclip - 33.0` (`[0x8101b0]`, about one WDL outer cell).
 const WDL_OVERLAP: f32 = 33.0;
 
-/// Nudge off the wall depth so the band is strictly BEHIND a detailed-world fragment sitting exactly
-/// at the wall, instead of tying it (reverse-Z `GreaterEqual` lets a tie through, and the winner would
-/// then be draw order). Multiplicative so it can never cross zero into the sky.
+/// Keeps the band strictly behind a world fragment exactly at the wall (`GreaterEqual` passes a
+/// tie); multiplicative, so it never crosses zero into the sky.
 const WDL_DEPTH_PUSH: f32 = 0.999;
 
-// The shared global light (`lighting::global_light`) — the same buffer terrain, the models and liquid
-// bind, mirrored here as the row prefix WDL needs. Rows 4/5 are the SCENE fog (block 1) plus the
-// farclip wall, and that is the right block by construction: the band IS the horizon, so it is never
-// inside a WMO and never wants the interior block. (WDL used to hold its own copy of these two rows,
-// re-pushed per material by `apply_wow_lighting`.)
+// The shared global light (`lighting::global_light`), mirrored up to the rows WDL reads. Rows 4
+// and 5 are the scene fog block, right by construction: the horizon band is never inside a WMO.
 struct WowLight {
     _light_ambient: vec4<f32>, // 0
     _light_diffuse: vec4<f32>, // 1
@@ -106,31 +59,27 @@ fn vertex(in: Vertex) -> WdlVsOut {
 
 @fragment
 fn fragment(in: WdlVsOut) -> WdlFsOut {
-    // PLANAR eye-Z (view-space depth), NOT radial — same as terrain.wgsl (apitrace-verified). Used for
-    // the band's near plane (below); the hull's own fog is saturated everywhere, so it needs no distance.
+    // Planar eye-z, not radial: the band's near plane is a projection plane.
     let eye_z = -(view.view_from_world * vec4<f32>(in.world_position.xyz, 1.0)).z;
     let farclip = w.fog_params.w;
 
-    // The far band's NEAR PLANE: `farclip − 33` (the reference's, see the header). Deliberately NOT the
-    // wall — the 33 yd overlap is what stops a hole opening at the coarse-vs-fine seam. (0 ⇒ disabled.)
+    // The near plane is `farclip - 33`, not the wall: the overlap closes the coarse-vs-fine seam.
     if (farclip > 0.0 && eye_z < farclip - WDL_OVERLAP) {
         discard;
     }
 
-    // White vertex diffuse under the hull pass's OWN fog pair — start 0, end 1.0 (the header; decision
-    // 1521): saturated for every fragment beyond one yard, so the hull is the fog colour, flat. The
-    // scene fog DISTANCES (`fog_params.xy`) are deliberately not read here — only its colour and the
-    // enable (with fog off, the reference shows the bare white hull, and so do we).
+    // White vertex diffuse under the hull's own fog pair, saturated beyond one yard: the flat fog
+    // colour, never the scene fog distances. With fog off the reference shows the bare white hull.
     var rgb = vec3<f32>(1.0);
     if (w.fog_color.w > 0.5) {
         rgb = w.fog_color.xyz;
     }
 
     var out: WdlFsOut;
-    // GAMMA LANE (0161): raw gamma out; the frame decodes once in the FFXGlow combine.
+    // Raw gamma out; the frame decodes once, in the FFXGlow combine.
     out.color = vec4<f32>(rgb, 1.0);
-    // The depth push (the reference's compressed far-band depth range). `view_z_to_depth_ndc` takes a
-    // view-space z — negative in front of the camera — so the wall is at `-farclip`.
+    // The depth clamp. `view_z_to_depth_ndc` takes view-space z, negative in front of the camera,
+    // so the wall is at `-farclip`.
     var depth = in.clip_position.z;
     if (farclip > 0.0) {
         depth = min(depth, view_z_to_depth_ndc(-farclip) * WDL_DEPTH_PUSH);
diff --git a/crates/benilla-assets/src/shaders/wow_model.wgsl b/crates/benilla-assets/src/shaders/wow_model.wgsl
index cdaff568..07705ba5 100644
--- a/crates/benilla-assets/src/shaders/wow_model.wgsl
+++ b/crates/benilla-assets/src/shaders/wow_model.wgsl
@@ -1,46 +1,13 @@
-// WoW model lighting — paired with terrain.wgsl. Step 7 (matte) restores the faithful gamma-space
-// combine for M2/WMO/creature meshes; trees, doodads, and buildings stop being black. **Step 8d:**
-// ground clutter (grass/flowers) is lit by the **terrain ground normal under each tuft** (baked onto
-// its vertices in clutter.rs), not the grass-quad's own normal — VERIFIED faithful: WoW writes the
-// terrain quadrant-plane normal onto the clutter vertex normal channel and lights per-vertex with it
-// (ground-effects.md), so a tuft darkens with the dirt it stands on as slope / shade / sun change.
-// MCSH grey from q12 still rides on `ATTRIBUTE_COLOR → pbr_input.material.base_color` so per-doodad
-// shadowing remains.
-//
-//   color = clamp(A + D·I·f(N·u)) × tex × tint          // M2 doodads: the Model2.bls order-2 lobe (0803)
-//   color = clamp(ambient + diffuse·max(N·L,0)) × …      // clutter / WMO: FFP directional matte (sun-scale 1)
-//   color = mix(fog_color, color, fog_factor)                                // Step 5 fog
-//   out   = color                            // raw gamma — the frame's ONE decode is in FFXGlow (0161)
-//
-// For trees / WMOs / creatures, `material_tint` is the StandardMaterial base_color (white by default
-// — vertex colour attribute absent → VERTEX_COLORS shader-def not set → no per-vertex factor). For
-// detail clutter, the merged mesh ships `ATTRIBUTE_COLOR = (mcsh_tint, mcsh_tint, mcsh_tint, 1)`,
-// which Bevy folds into base_color → the lit factor is multiplied by the MCSH grey per-doodad.
-//
-// **Two different lighting laws live in this file, and confusing them has cost us three decisions.**
-// Terrain, clutter and WMO genuinely ARE fixed-function (GL_LIGHTING + GL_LIGHT0 + GL_COLOR_MATERIAL,
-// byte-verified off WoW.exe 5875 — and all five FFP light-commit call sites are terrain's), so they take
-// `clamp(ambient + diffuse·max(N·L,0))`. The exterior M2 lane is NOT fixed-function: the reference loads
-// `Shaders\Vertex\Model2.bls` out of misc.MPQ (gated on the VERTEX cvar `M2UseShaders`, which defaults to
-// "1") and that program is an order-2 irradiance lobe, running on every exterior M2 it draws — doodad,
-// GameObject, creature and player alike. So M2 doodads take that lobe, `E = A + D·I·(4/17)(0.375 + 2μ +
-// 1.875μ²)` with μ = N·u toward-light, clamp01 on the SUM (0803, and the lane comment at step 7).
-// Per-instance `I` is the terrain-shade family sampled at the doodad's base (2.5 lit / 0.5 MCSH-shadowed,
-// `[def+0xa4]`) — see step 7 for the one part of that still open.
-//
-// Two retracted claims are recorded rather than deleted, because each stood long enough to seed a
-// decision record and the next reader should know they were retired, not that they were never made:
-// (a) "there is NO M2 irradiance lobe … no such program runs — M2UsePixelShaders defaults off" — wrong
-// twice, wrong cvar and the program does run; (b) "on the exterior M2 lane that matte is OUR choice"
-// (0796's framing) — true while 0410's cutoff stood, retired by 0803, which put the lane back on the
-// reference's own curve.
-//
-// Specular (row 9 separate-specular, local viewer) is verified by q4/q5/Q13 but kept OUT of this
-// step — M2 per-material shininess (q4 §6 INFERRED) is its own A/B and lives in Step 7b. WMO
-// per-group authored colour (q4 §5) is also deferred.
-//
-// The clutter distance-fade alpha ramp (~52.5→70 yd) still applies on top — that's a draw-distance
-// concern, not a lighting one (ground-effects.md Q4/Q10).
+// The model pass for M2, WMO and ground-clutter meshes, lit and fogged in gamma space:
+//   M2:           color = clamp01(A + D·I·(4/17)(0.375 + 2μ + 1.875μ²)) × tex × tint, μ = N·L
+//   clutter, WMO: color = clamp(ambient + diffuse·max(N·L, 0)) × tex × tint
+//   fog:          color = mix(fog_color, color, fog_factor); out = color, raw gamma
+// The M2 law is the order-2 SH lobe of `Shaders\Vertex\Model2.bls` (cvar `M2UseShaders`, default
+// 1); M2's one FFP light site (`70bdf6`) runs only with that cvar off. Clutter and WMO are the FFP
+// light (GL_LIGHTING, GL_LIGHT0, GL_COLOR_MATERIAL); clutter's normal is the terrain normal under
+// the tuft, which the reference writes onto the clutter vertex.
+// Not built: a specular term (the M2 per-material shininess is only inferred) and the WMO
+// per-group authored colour.
 
 #import bevy_pbr::{
     pbr_fragment::pbr_input_from_standard_material,
@@ -54,55 +21,31 @@
 // MONKEY (shadow hook): the realtime directional-shadow term (fetch + edge/night fade) lives here.
 #import benilla::shadow_hook
 
-// Our own fragment output — bevy's `forward_io::FragmentOutput` verbatim (`@location(0) color` and
-// nothing else, bevy_pbr 0.18.1 `forward_io.wgsl`), kept as a named struct so the lane's output
-// has one place to grow. The WMO-skybox lane's forced far depth (`WOW_SKY_DEPTH`) used to add a
-// fragment-depth builtin here; it is a VERTEX-stage pin now (below, decision 2016) — a fragment
-// depth write costs the pipeline its early-Z, and even on the one camera-anchored model that lane
-// draws, the same number decided one stage earlier is free.
+// bevy_pbr 0.18.1's `forward_io::FragmentOutput`. No depth output: a fragment depth write costs
+// the pipeline early-Z, so the sky lane pins its depth in the vertex stage.
 struct WowFragOut {
     @location(0) color: vec4<f32>,
 }
 
-// Per-material model uniforms packed at binding 100 (see `WowModelExt` in terrain.rs). Light + fog + the
-// SH coeffs moved OUT to the shared global-light storage buffer (below); only the per-material draw flags
-// remain. Field order MUST match the Rust struct.
-//   clutter_fade — x = plateau-end VIEW DEPTH (yd, = 0.75·far); y = ramp-zero view depth (yd, the
-//                  ~70 yd detail-doodad horizon `[0x867958]`); w = enabled (>0.5). The client draws
-//                  clutter only within that horizon, with the reference's quantised 64-texel ramp
-//                  over the last quarter, addressed by VIEW-SPACE DEPTH — see the fragment note
-//                  (2004). 0 = off.
-//   model_flags  — x = is_wmo (>0.5 ⇒ the WMO surface lanes); y = fade-blend twin;
-//                  z = interior (>0.5): a WMO interior group (with is_wmo ⇒ the INT/TRANS batch-class
-//                      lanes below) OR an interior M2 doodad prop (without is_wmo ⇒ lit by its folded
-//                      SH probe, slot per-instance in MeshTag — day/night-independent);
-//                  w = unlit fullbright (>0.5 ⇒ bypass lighting): M2 UNLIT (0x01), or WMO UNLIT on an
-//                      exterior-group batch (the interior drawer ignores the flag — section law).
+// Per-material uniforms at binding 100, in `WowModelExt`'s field order (materials.rs).
+//   clutter_fade: x = plateau-end view depth (yd, 0.75·far), y = ramp-zero view depth (the ~70 yd
+//     detail-doodad horizon `[0x867958]`), z = the batch marker bits, w = clutter
+//   model_flags: x = WMO, y = fade blend twin, z = interior (a WMO interior group, or an interior
+//     M2 lit by its SH probe), w = unlit fullbright (M2 UNLIT 0x01 or Mod/Mod2x, or WMO UNLIT on
+//     an exterior-group batch; the interior drawer ignores it)
 struct ModelParams {
     clutter_fade: vec4<f32>,
     model_flags: vec4<f32>,
-    // x = per-material MCSH terrain-shade SELECTOR (≥0.5 ⇒ lit ground, <0.5 ⇒ MCSH-shadowed); the shader
-    // thresholds it into the lit/shaded doodad sun INTENSITY family below. yzw reserved.
+    // x = the terrain-shade selector (see the doodad sun), y = the WMO batch order, zw = the
+    // UV-scroll seed.
     sun_scale: vec4<f32>,
-    // xyz = the M2Color RGB tint for batches whose colour track ANIMATES (the static vertex bake is
-    // skipped for those — WowModelExt::tint): folded into the albedo exactly where the vertex tint
-    // folds. (1,1,1) — identity — for everything else. w = the WMO interior BATCH-CLASS lane
-    // (wow-re trace-forensics-abbey-interior-d3d §2): 0 = exterior law, 1 = interior INT (unlit
-    // tex × MOCV), 2 = interior TRANS (per-vertex MOCV-alpha lit↔bake lerp).
+    // xyz = the animated M2Color tint (identity when static); w = the WMO interior batch class:
+    // 0 exterior law, 1 INT, 2 TRANS.
     tint: vec4<f32>,
-    // The WMO window/glass law (wow-re wmo-lit-selector / wmo-interior-night-light; 0 for all M2):
-    // xyz = the MOMT SIDN (0x10) authored emissive colour (gamma bytes /255) — multiplied by the live
-    // night fraction (wow_light.grade.x) and added INSIDE the lit sum on lit lanes, like the
-    // reference's glMaterialfv(GL_EMISSION): tex × (lit + sidn·night). Windows glow warm at night,
-    // nothing by day; dead on the unlit INT lane and under UNLIT, exactly like the FFP.
-    // w = the MOMT WINDOW (0x20) flag (>0.5): an interior-group batch swaps GL_LIGHT0 to the brighter
-    // midpoint pair — ambient AND diffuse = (Direct + Ambient)/2, ambient +16/255 — the warm pane
-    // seen from inside a building (derivation 0x6d37e0, byte-verified).
+    // WMO glass, 0 on M2: xyz = the MOMT SIDN (0x10) emissive (gamma /255), w = MOMT WINDOW (0x20).
     sidn: vec4<f32>,
-    // The shared mat-anim TABLE slots (decision 1381): x = the UV-scroll slot, y = the animated-
-    // tint slot — 0 (the pinned-zero identity row) for every static material, so the folds below
-    // add the row unconditionally, branch-free. The rows are DELTAS from the built seeds
-    // (sun_scale.zw / tint.xyz), which stay exactly as built; zw free.
+    // Rows of `wow_light.matanim`, 0 = identity: x = UV scroll, y = tint, z = texture-transform
+    // affine, w = the UI tile's cell clip.
     anim_slots: vec4<f32>,
 };
 @group(#{MATERIAL_BIND_GROUP}) @binding(100) var<uniform> m: ModelParams;
@@ -120,8 +63,8 @@ const SHADOW_SUN_FLOOR: f32 = 0.45;
 struct WowLight {
     light_ambient: vec4<f32>, // rgb ambient; w = Mod2x scale
     light_diffuse: vec4<f32>, // rgb sun diffuse; w = clamp-light flag (>0.5 ⇒ saturate)
-    light_sun: vec4<f32>,     // xyz sun TRAVEL dir (to-light = −xyz); w = directional-light enable (>0.5)
-    light_spec: vec4<f32>,    // rgb spec color; w = shininess (terrain's — unused by the matte model path)
+    light_sun: vec4<f32>,     // xyz sun travel dir (to-light = −xyz); w = directional enable
+    light_spec: vec4<f32>,    // terrain's specular (w = its shininess); unread here
     fog_color: vec4<f32>,     // rgb row-7 fog (gamma); w = enable (>0.5)
     fog_params: vec4<f32>,    // x=start y=end z=signed +sun / -moon shadow weight w=farclip wall
     // The global Model2.bls SH rows (6-12): the scene day/night light as an order-2 probe at
@@ -150,13 +93,10 @@ struct WowLight {
     // lane below decodes. (It had carried the 0273 point gain, the 0750/0751 sun dial and 0799's
     // response A/B before those were retired — hence the long-standing "free" note here.)
     sh_c16: vec4<f32>,
-    _water: array<vec4<f32>, 4>, // rows 13-16: the liquid swatches — unread by models.
-    // x = SIDN night fraction (1 overnight, 0 by day — scales m.sidn.rgb).
-    // yzw = the sun's SH DC redistribution per channel, at intensity 1 (× the per-instance I).
+    _water: array<vec4<f32>, 4>, // rows 13-16: the liquid swatches, unread here
+    // x = the SIDN night fraction (1 overnight, 0 by day); yzw = the sun's SH DC at intensity 1.
     grade: vec4<f32>,
-    // Rows 18-19: the INTERIOR fog triple — the 4 s camera-in-WMO MFOG crossfade (== the scene fog
-    // outdoors). Consumed by the interior lanes only (round-6 Q-I): interior WMO-group surfaces
-    // and that group's doodads (`0x6b5190` / `0x6b62e0`) — selected below by `m.model_flags.z`.
+    // Rows 18-19: the interior fog, the 4 s camera-in-WMO MFOG crossfade (the scene fog outdoors).
     wmo_fog_color: vec4<f32>,    // rgb interior fog (gamma); w = enable (mirrors fog_color.w)
     wmo_fog_params: vec4<f32>,   // x = start yd; y = end yd; zw = free lanes (retired A/B dials)
     // The dynamic point-light table (decision 0278), packed by `global_light::build_light_data`:
@@ -172,41 +112,22 @@ struct WowLight {
     // packed reach is always ≥ 1 yd and can never be mistaken for the exterior 0.
     point_count: vec4<f32>,
     points: array<vec4<f32>, 512>,
-    // The interior-prop SH probe table (lighting::prop_probes — 7 rows per slot, 8192 slots; keep in
-    // sync with MAX_PROP_PROBES): the folded committed light of each lit interior MODD prop. The
-    // prop's MeshTag payload is its slot; the interior-prop lane below evaluates rows
-    // [7·slot .. 7·slot+7) over the fragment normal. Only this shader declares the region — the
-    // other shaders mirror the buffer PREFIX and bind the same (larger) buffer.
+    // The interior-prop SH probes, 7 rows per slot (`MAX_PROP_PROBES` = 8192 slots). Only this
+    // shader declares this tail; the other shaders bind the same buffer by its prefix.
     prop_probes: array<vec4<f32>, 57344>,
-    // The owned skin palette (decision 0720; rig_palette.rs mirrors both sizes). `rig_table`:
-    // one base bone index per rig slot (2048 = mesh_tag's 11-bit rig field; the instance's slot
-    // rides its MeshTag bits 19-29). `palettes`: 3 vec4 rows per bone — the rows of
-    // `rig_from_joint × inverse_bindpose`, the same matrix Bevy's skin lane would feed
-    // `skin_model` except measured from the RIG's own origin rather than the map's (decision
-    // 0974) — blended in the vertex stage below (WOW_RIG_SKIN).
+    // Per rig slot (sizes mirrored in rig_palette.rs): the base bone index into `palettes`, whose
+    // 3 rows per bone are `rig_from_joint × inverse_bindpose` from the rig's own origin.
     rig_table: array<u32, 2048>,
-    // The per-instance body TINT, on the SAME slot index as `rig_table` (instance_tint.rs, decision
-    // 0812): the CM2 `model+0x184/188/18c` modulate colour, packed `0xFFRRGGBB` exactly as the
-    // reference packs its node value (`0x60d840`: `param | 0xff000000`). A word of **0 is identity**
-    // — so slot 0 (every unskinned instance in the world), a zeroed studio buffer and an untinted
-    // frame all cost nothing, while a genuine authored BLACK tint still reads as 0xFF000000.
+    // Per rig slot: the CM2 body tint (`model+0x184/188/18c`) packed `0xFFRRGGBB` like the
+    // reference's node value (`0x60d840`: `param | 0xff000000`); 0 is identity.
     rig_tint: array<u32, 2048>,
-    // The rig ORIGIN table (decision 0974), on the SAME slot index again: `xyz` = the world
-    // position that rig's palette rows are measured from (`w` unused). The vertex stage adds it
-    // back as `origin − camera`, so a skinned vertex is never expressed as an absolute world
-    // coordinate in f32 — which is what the ~1 mm/frame character shimmer was.
+    // Per rig slot: the world origin its palette rows are measured from.
     rig_origin: array<vec4<f32>, 2048>,
-    // The mat-anim delta table (decision 1381; mat_anim_table.rs mirrors the size): row 0 is the
-    // pinned-zero identity every static material's anim_slots = 0 reads; a live row is the drawn
-    // batch's sampled UV-scroll delta (xy, added to sun_scale.zw), tint delta (xyz, added to
-    // tint.rgb), or texture-transform affine (decision 2019: [cos − 1, sin, sx − 1, sy − 1]).
-    // Zero region = every batch at its built seed — the studio buffers and deterministic
-    // captures ride that exactly like the tint table's zero-identity.
+    // The mat-anim rows (size mirrored in mat_anim_table.rs), row 0 zero: a UV-scroll delta (xy),
+    // a tint delta (xyz), a texture-transform affine `[cos − 1, sin, sx − 1, sy − 1]` or a UI cell.
     matanim: array<vec4<f32>, 2048>,
-    // The straddle split's waterline (decision 2188; benilla-world straddle.rs mirrors the size),
-    // on the SAME slot index again: `x` = the plane's world height (Bevy Y), `y` = the side the
-    // instance's NEAR copy keeps (+1 above, −1 below). `y == 0` is "not straddling" — slot 0,
-    // every slot nothing wrote, every zeroed studio buffer — so a dry world pays one compare.
+    // Per rig slot, the straddle waterline (size mirrored in straddle.rs): x = its world height
+    // (Bevy Y), y = the side the near copy keeps (+1 above, −1 below, 0 not straddling).
     water_clip: array<vec2<f32>, 2048>,
     palettes: array<vec4<f32>>,
 };
@@ -390,17 +311,11 @@ fn torch_entity_debug_factor(P: vec3<f32>, N: vec3<f32>) -> f32 {
 // twin so its silhouette matches the steady cutout exactly.
 const VANILLA_ALPHA_KEY: f32 = 0.8784314;
 
-// The detail-doodad (ground clutter) texture LOD bias — the reference sets
-// `D3DSAMP_MIPMAPLODBIAS = +0.25` on stage 0 for its detail-doodad pass alone (`0x6813f4`,
-// capture-confirmed on all 29 doodad batches). It is what makes the distance cut resolve per pixel
-// rather than per leaf; the full derivation is at the use site in `fragment`, and in wow-re
-// `terrain/scratch/doodad-fade-pixel-granularity.md`.
+// The detail-doodad pass's stage-0 `D3DSAMP_MIPMAPLODBIAS = +0.25` (`0x6813f4`).
 const DETAIL_DOODAD_LOD_BIAS: f32 = 0.25;
 
-// bevy's `VertexOutput` (same fields, same locations, same defs) + the per-vertex dynamic
-// point-light term at a free location. One extra interpolant is why this can't BE `VertexOutput`;
-// the fragment rebuilds one for `pbr_input_from_standard_material`. (Our meshes never carry
-// tangents / morphs / visibility ranges, so those defs stay unset and unmirrored.)
+// Bevy's `VertexOutput` (same fields, locations and defs; no tangents, morphs or visibility
+// ranges) plus our interpolants; the fragment rebuilds a `VertexOutput` from it.
 struct WowVsOut {
     @builtin(position) position: vec4<f32>,
     @location(0) world_position: vec4<f32>,
@@ -417,14 +332,10 @@ struct WowVsOut {
 #ifdef VERTEX_OUTPUT_INSTANCE_INDEX
     @location(6) @interpolate(flat) instance_index: u32,
 #endif
-    // The Gouraud-interpolated point-light sum (decision 0278): `Σ att·sat(N·L)·colour` evaluated at
-    // the VERTEX, like the reference FFP — the tessellation-scale smoothing IS the authored look
-    // (wide floor pools, dim hoods). The fragment folds in the live gain and the saturating clamp.
+    // The point-light sum `Σ att·sat(N·L)·colour`, per vertex like the reference FFP.
     @location(8) point_lit: vec3<f32>,
 #ifdef WOW_MERGED_FADE
-    // The merged fader blob's per-placement fade alpha (decision 1418), computed in the vertex
-    // stage from the baked fade sphere. Constant across a placement's vertices, so plain
-    // interpolation reproduces it exactly.
+    // A merged blob's per-placement fade alpha, constant over the placement.
     @location(9) merged_fade: f32,
 #endif
 #ifdef WOW_MERGED_SLOT
@@ -462,7 +373,7 @@ struct WowVsOut {
 // on 82. A plain `normalize()` turns that legal, shipped datum into NaN, and NaN poisons the whole
 // lighting chain: every SH dot is NaN, `clamp(NaN, 0, 1)` floors to 0, and the batch renders PURE
 // BLACK over its correct texture — the reported symptom, which only "came back" while the unit was
-// targeted because the highlight's `+64/255` emissive rides OUTSIDE the poisoned factor.
+// targeted because the highlight (the scene ambient, added) rides OUTSIDE the poisoned factor.
 //
 // The reference lands on the zero vector instead: its `Model2.bls` lit permutations normalize with
 // the era's `RSQ`/`MUL` pair (wow-re `models/scratch/model2-bls-vertex-sh.md` §2), where the
@@ -1013,10 +924,8 @@ fn wmo_exterior_point_sum(P: vec3<f32>, N: vec3<f32>) -> vec3<f32> {
 // 0720; Bevy's `forward_io::Vertex` only declares joints under its own SKINNED path, which no
 // benilla mesh triggers anymore).
 #ifdef WOW_MERGED_FADE
-// The faithful per-object doodad fade curve (`model_fade::doodad_fade_alpha`, exact
-// `FUN_00683f80` constants): horizontal-plane distance, `d = dist − radius`, size-bucketed
-// band, `1 − (d − start)/range` clamped. `radius > 7` never fades (never-fade members of a
-// merged blob bake their true radius and land here).
+// The doodad fade curve (`FUN_00683f80`, in sync with `model_fade::doodad_fade_alpha`): alpha =
+// 1 − (d − start)/range, d = horizontal distance − radius, over a size-bucketed band.
 fn merged_fade_alpha(radius: f32, horiz_dist: f32) -> f32 {
     if (radius > 7.0) {
         return 1.0;
@@ -1035,6 +944,9 @@ fn merged_fade_alpha(radius: f32, horiz_dist: f32) -> f32 {
 }
 #endif
 
+// Bevy 0.18's `forward_io::Vertex` at Bevy's locations, plus the palette joints at 10/11 (appended
+// by `WowModelExt::specialize` for a mesh with `ATTRIBUTE_WOW_JOINT_INDEX`) and the merged-blob
+// attributes at 12/13.
 struct WowVertex {
     @builtin(instance_index) instance_index: u32,
 #ifdef VERTEX_POSITIONS
@@ -1057,28 +969,22 @@ struct WowVertex {
     @location(11) joint_weights: vec4<f32>,
 #endif
 #ifdef WOW_MERGED_FADE
-    // The baked placement fade sphere (decision 1418): `xyz` world center, `w` fade radius.
+    // The placement fade sphere: xyz = world centre, w = fade radius.
     @location(12) fade_sphere: vec4<f32>,
 #endif
 #ifdef WOW_MERGED_SLOT
-    // The baked interior-prop SH-probe slot (1418 lane 3) — replaces the MeshTag payload the
-    // per-entity lane carries.
+    // The interior-prop SH-probe slot, in place of the per-entity MeshTag payload.
     @location(13) merged_slot: u32,
 #endif
 }
 
 #ifdef WOW_RIG_SKIN
-// The instance's rig slot — the shared index into `rig_table`, `rig_tint` and `rig_origin`.
 fn wow_rig_slot(instance_index: u32) -> u32 {
     return (mesh_functions::get_tag(instance_index) >> 19u) & 0x7ffu;
 }
 
-// The owned-palette skin model (decision 0720): the instance's rig slot from its MeshTag rig
-// field (bits 19-29) → the rig's base bone index → the four indexed bones' palette rows blended
-// by the vertex weights. Returns `rig_from_local` — structurally what Bevy's `skin_model` returns
-// (and it REPLACES the mesh's world matrix, never composes with it), except the translation is
-// measured from the rig's own origin rather than the map's (decision 0974). `rig_origin[slot]`
-// carries the missing piece; the vertex stage applies it camera-relative.
+// Blends the four weighted bones' palette rows into `rig_from_local`, which replaces the mesh's
+// world matrix like Bevy's `skin_model`; its translation is relative to `rig_origin[slot]`.
 fn wow_skin_model(instance_index: u32, indices: vec4<u32>, weights: vec4<f32>) -> mat4x4<f32> {
     let base = wow_light.rig_table[wow_rig_slot(instance_index)];
     let b0 = 3u * (base + indices.x);
@@ -1097,7 +1003,7 @@ fn wow_skin_model(instance_index: u32, indices: vec4<u32>, weights: vec4<f32>) -
         + weights.y * wow_light.palettes[b1 + 2u]
         + weights.z * wow_light.palettes[b2 + 2u]
         + weights.w * wow_light.palettes[b3 + 2u];
-    // r0/r1/r2 are the affine's ROWS; a wgsl matrix is column-major.
+    // r0/r1/r2 are the affine's rows; a WGSL matrix is column-major.
     return mat4x4<f32>(
         vec4<f32>(r0.x, r1.x, r2.x, 0.0),
         vec4<f32>(r0.y, r1.y, r2.y, 0.0),
@@ -1106,7 +1012,7 @@ fn wow_skin_model(instance_index: u32, indices: vec4<u32>, weights: vec4<f32>) -
     );
 }
 
-// bevy_pbr::skinning's normal math verbatim (inverse-transpose via the adjugate), on our matrix.
+// bevy_pbr::skinning's inverse-transpose via the adjugate, verbatim.
 fn inverse_transpose_3x3m(in: mat3x3<f32>) -> mat3x3<f32> {
     let x = cross(in[1], in[2]);
     let y = cross(in[2], in[0]);
@@ -1115,8 +1021,6 @@ fn inverse_transpose_3x3m(in: mat3x3<f32>) -> mat3x3<f32> {
     return mat3x3<f32>(x / det, y / det, z / det);
 }
 
-// (Translation-free by construction — so the rig-relative frame of decision 0974 feeds it
-// unchanged: a normal never cared where the rig stands.)
 fn wow_skin_normals(frame_from_local: mat4x4<f32>, normal: vec3<f32>) -> vec3<f32> {
     return wow_normalize(
         inverse_transpose_3x3m(mat3x3<f32>(
@@ -1128,23 +1032,15 @@ fn wow_skin_normals(frame_from_local: mat4x4<f32>, normal: vec3<f32>) -> vec3<f3
 }
 #endif
 
-// Custom vertex stage — bevy 0.18's `mesh.wgsl` vertex verbatim (VERTEX_* attributes; morph
-// targets omitted — no model mesh authors them) with the owned-palette skinning in place of
-// Bevy's SKINNED path (decision 0720), plus the per-vertex point-light evaluation on the
-// post-skin world position/normal. A `MaterialExtension` swaps the whole stage, so the mirror
-// must track bevy's on upgrades.
+// Bevy 0.18's `mesh.wgsl` vertex stage plus our skinning and point lights. A `MaterialExtension`
+// replaces the whole stage, so this must track Bevy's on upgrades.
 @vertex
 fn vertex(vertex: WowVertex) -> WowVsOut {
     var out: WowVsOut;
 
     let mesh_world_from_local = mesh_functions::get_world_from_local(vertex.instance_index);
-    // **Split the instance placement into (frame, origin)** — decision 0974. `frame_from_local`
-    // carries the orientation and a SMALL translation; `frame_origin` carries the ~9 k-yard world
-    // position. Skinned: the palette rows are already rig-relative and `rig_origin` is the rig's
-    // world position. Unskinned: the mesh matrix's own translation column moves over. Either way
-    // the world position is `frame_from_local · v + frame_origin`, and the point is that neither
-    // factor is a big-times-small product — that product is where a ~1 mm f32 ULP was landing on
-    // every animated vertex, freshly every frame.
+    // Precision: `frame_from_local` holds the orientation and a small translation, `frame_origin`
+    // the ~9 k yd world position, so no f32 product mixes the two (an f32 ULP at 9 k is ~1 mm).
 #ifdef WOW_RIG_SKIN
     var frame_from_local = wow_skin_model(
         vertex.instance_index,
@@ -1170,12 +1066,9 @@ fn vertex(vertex: WowVertex) -> WowVsOut {
 #endif
 
 #ifdef VERTEX_POSITIONS
-    // Camera-relative all the way to clip space. `p_cam` is built from two small quantities, so
-    // it keeps ~1e-7 yd of precision where the absolute route kept ~1e-3 — and `clip_from_view ×
-    // (R_view · p_cam)` has none of the catastrophic cancellation `clip_from_world × p_world`
-    // suffers when camera and geometry both sit at ~9 k (0733 §2 fixed the same defect on the
-    // effect lane; this is the model lane's). `world_position` goes back to absolute for the
-    // lighting/fog/shadow consumers downstream, which are not precision consumers.
+    // Precision: camera-relative to clip space; `clip_from_world × p_world` cancels
+    // catastrophically with camera and geometry near 9 k yd. `world_position` is absolute again:
+    // lighting and fog need no such precision.
     let p_cam = (frame_from_local * vec4<f32>(vertex.position, 1.0)).xyz
         + (frame_origin - view.world_position);
     out.world_position = vec4<f32>(p_cam + view.world_position, 1.0);
@@ -1185,29 +1078,18 @@ fn vertex(vertex: WowVertex) -> WowVsOut {
         view.view_from_world[2].xyz,
     );
     out.position = view.clip_from_view * vec4<f32>(view_rot * p_cam, 1.0);
-    // WMO authored batch order (`m.sun_scale.y`; 0 = non-WMO ⇒ exact no-op): the client resolves
-    // coplanar batches (wall + decal/trim) by strict MOBA draw order under depth-write + LEQUAL
-    // (wow-5875-re `wmo-batch-blend-depth-state.md`, byte-verified); Bevy orders draws for
-    // batching, so a later batch must instead WIN the reverse-Z GreaterEqual test. Scaling clip z
-    // by (1 + n·2⁻²³) raises the interpolated depth z/w by exactly n ULP-steps per fragment —
-    // the same one-unit-per-index nudge the old fixed-function `DepthBiasState` constant applied,
-    // but as uniform DATA: as pipeline state it made every batch index its own pipeline, and a
-    // first city sight synchronously compiled ~3000 of them on the render thread (decision 0837).
+    // WMO batch order (`sun_scale.y`, 0 off WMO): the reference layers coplanar batches by MOBA
+    // draw order under depth-write + LEQUAL; Bevy reorders draws, so a later batch must win the
+    // reverse-Z GreaterEqual test. Scaling clip z by (1 + n·2⁻²³) raises z/w by n ULPs. Uniform
+    // data, not a `DepthBiasState`, which would make every batch index its own pipeline.
     out.position.z *= 1.0 + m.sun_scale.y * 1.1920929e-7;
 #ifdef WOW_SKY_DEPTH
-    // The WMO-skybox lane (`clutter_fade.z` bit 13, `model_render::SKY_DEPTH_MARKER`): clip z
-    // pinned to 0 — reverse-Z "infinitely far" for every fragment, whatever w — under bevy's
-    // `GreaterEqual` test: the sky depth law (`benilla_world::sky_order`, "The depth law"). The
-    // world paints over the painted sky whatever the shell's radius, and the sky can never land
-    // in front of world geometry. A pipeline-key branch, never unconditional: every other model
-    // draw keeps its real depth.
+    // The WMO-skybox lane (`clutter_fade.z` bit 13): clip z = 0 is reverse-Z infinitely far, so
+    // the world always draws over the sky shell (`benilla_world::sky_order`).
     out.position.z = 0.0;
 #endif
 #ifdef WOW_MERGED_FADE
-    // The merged fader lane (decision 1418). Alpha channel: the faithful curve, per vertex.
-    // Hidden channel: a fully-faded placement collapses its clip position past the far plane —
-    // its triangles never rasterize, the shader-side equivalent of `Visibility::Hidden` at
-    // fade 0 (the CPU authority never sees inside a blob).
+    // A fully faded placement leaves the clip volume, so its triangles never rasterize.
     let fade_d = distance(view.world_position.xz, vertex.fade_sphere.xz);
     out.merged_fade = merged_fade_alpha(vertex.fade_sphere.w, fade_d);
     if (out.merged_fade <= 0.0) {
@@ -1221,29 +1103,10 @@ fn vertex(vertex: WowVertex) -> WowVsOut {
 
 #ifdef VERTEX_UVS_A
     out.uv = vertex.uv;
-    // **Environment-mapped batches GENERATE their texcoord — here, in the VERTEX stage, because
-    // that is where the reference generates it.** `Shaders\Vertex\Model2.bls` writes it as a
-    // vertex-program output and lets the rasteriser interpolate:
-    //
-    //     DP3 R0.x, R1.xyz, R2.xyz          ; dot(P, N)      P = view-space skinned position
-    //     MUL R0.x, c0.w, R0.x              ; ×2             N = normalize(view-space normal)
-    //     MAD R0.yzw, -R0.x, R2.xxyz, R1.xxyz   ; R = P − 2(P·N)N
-    //     DP3/RSQ/MUL                       ; normalize(R)
-    //     MAD result.texcoord[3].xy, R0.xyxx, c1.x, c1.x   ; ·0.5 + 0.5   (c0.w = 2, c1.x = 0.5)
-    //
-    // — the `(0.5,0,0,0.5 / 0,0.5,0,0.5)` remap wow-re byte-derived at `0x70b8d0` (models.md §944),
-    // reached whenever `texture_unit_lookup[texCoordSet] > 2` (`0x70b8bd`). Its space is pinned by
-    // the same program: `c2` (projection alone) × `c31` × vertex = clip, so `c31` — and therefore
-    // P and N — are **view space**, and wow-re's `lookat_v1` (`0x5c3e70`) stores row0 = side,
-    // row1 = up, row2 = forward, so `R.xy` is (camera-right, camera-up). Bevy's view basis is
-    // −Z-forward, which is exactly `F = diag(1,1,−1)`: `P'·N' = P·N`, hence `R' = F·R` and `R'.xy`
-    // is **identical**. No handedness fixup is needed or wanted.
-    //
-    // `view_rot * p_cam` is the view-space position already built for clip space above, so this
-    // costs one normalize and reuses the camera-relative precision (0974) instead of round-tripping
-    // an absolute world coordinate. Decision 0971 evaluated this per FRAGMENT instead; measured on
-    // `GnomeSubwayGlass` the two differ by ≤0.004 UV across a whole ring (the sphere-map disk has
-    // radius 0.5), so the deviation bought nothing and cost fidelity — see decision 0980.
+    // Env-mapped batches (`clutter_fade.z` bit 12; `texture_unit_lookup[texCoordSet] > 2` at
+    // `0x70b8bd`) generate their texcoord per vertex as `Model2.bls` does: in view space
+    // R = normalize(P − 2(P·N)N), uv = R.xy·0.5 + 0.5 (`0x70b8d0`). The reference view basis
+    // (`0x5c3e70`) and Bevy's −Z-forward one differ only in z, so R.xy needs no fixup.
 #ifdef VERTEX_POSITIONS
 #ifdef VERTEX_NORMALS
     if ((u32(m.clutter_fade.z) & 4096u) != 0u) {
@@ -1312,15 +1175,9 @@ fn vertex(vertex: WowVertex) -> WowVsOut {
 
 @fragment
 fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
-    // **The UI model tile's cell clip** (decision 2093). A `<Model>` pane's batches render into
-    // that pane's cell of ONE shared atlas, and a model may draw outside its widget rect —
-    // `ForcedBackpackItem.mdx`'s card is authored 45..83 layout units above an origin that sits
-    // at the rect's bottom-left. The reference cannot leak: it draws each pane straight into the
-    // back buffer with the widget's rect as the VIEWPORT (`modelframe-render-law.md` §6). One
-    // shared atlas camera cannot carry a viewport per pane, so the tile hands its cell down as a
-    // mat-anim row (`anim_slots.w`, the row's `[min.x, min.y, max.x, max.y]` in ATLAS TEXELS —
-    // which is what `@builtin(position)` is here) and the fragment is the scissor. `w == 0` is
-    // the pinned-zero row: every world material, no clip, one comparison.
+    // The UI model tile's cell clip: the reference gives each `<Model>` pane its widget rect as the
+    // viewport; our panes share an atlas, so the tile passes its cell as a mat-anim row
+    // (`anim_slots.w`, `[min.x, min.y, max.x, max.y]` in atlas texels) and this is the scissor.
     if (m.anim_slots.w > 0.5) {
         let r = wow_light.matanim[u32(m.anim_slots.w)];
         if (in.position.x < r.x || in.position.y < r.y
@@ -1328,9 +1185,8 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
             discard;
         }
     }
-    // HARD FAR-CLIP WALL (faithful `farclip` ~777 yd) — see terrain.wgsl. Per-pixel discard beyond the
-    // projection far plane (planar eye-Z), so distant buildings/trees reveal closest-part-first and the
-    // sky/WDL shows behind. `wow_light.fog_params.w` = farclip (0 ⇒ disabled). Clutter (≤70 yd) never hits it.
+    // The far-clip wall: discard past `farclip` (`fog_params.w`, 0 = off) by planar eye depth, as
+    // terrain.wgsl does.
     if (wow_light.fog_params.w > 0.0) {
         let clip_z = -(view.view_from_world * vec4<f32>(in.world_position.xyz, 1.0)).z;
         if (clip_z > wow_light.fog_params.w) {
@@ -1338,11 +1194,9 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         }
     }
 #ifdef WOW_WATER_CLIP
-    // THE STRADDLE SPLIT (decision 2188, straddle.rs; wow-re water-frame-straddle.md §2): a
-    // translucent model crossing its water plane draws on BOTH sides of the water pass — this
-    // batch on the eye's (near) list, its far twin (FAR_SIDE_MARKER, `clutter_fade.z` bit 11)
-    // before the water — and each copy keeps only its own half: the reference's `M2UseClipPlanes`
-    // hardware clip plane at the waterline. `straddle::keeps` is this block's Rust twin.
+    // The straddle split: a translucent model crossing its water plane draws on each side of the
+    // water pass (the far copy has `clutter_fade.z` bit 11) and each copy keeps its half, the
+    // reference's `M2UseClipPlanes` plane at the waterline. In sync with `straddle::keeps`.
     let water_clip = wow_light.water_clip[(mesh_functions::get_tag(in.instance_index) >> 19u) & 0x7ffu];
     if (water_clip.y != 0.0) {
         let far_copy = (u32(m.clutter_fade.z) & 2048u) != 0u;
@@ -1352,32 +1206,16 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         }
     }
 #endif
-    // Rebuild bevy's `VertexOutput` from our extended interstage struct (WowVsOut carries one extra
-    // interpolant — the per-vertex point term — which the pbr entry point doesn't know about).
-    // M2 UV animation folds in here (decision 0130 phase 3, wow-re m2-texanim-uv; the full law
-    // since decision 2019, wow-re modelframe-texanim-and-sequence-law §3.4):
-    //     uv' = R((uv + t − p) ⊙ s) + p,  p = (½, ½)
-    // — the batch's live texture-transform TRANSLATION is added to the stage UVs (`sun_scale.zw`
-    // is the built seed, the mat-anim row its delta), then the scale is applied about the pivot,
-    // then the rotation about the pivot. The affine row (`anim_slots.z`) carries `[cos − 1, sin,
-    // sx − 1, sy − 1]`; row 0 is all zeros, so a static batch and every translation-only doodad
-    // read `uv + t` exactly as before. `benilla_formats::uv_transform` is this fold's twin.
+    // Rebuild Bevy's `VertexOutput` with the M2 texture transform (in sync with
+    // `tex_anim::uv_transform`): uv' = R((uv + t − p) ⊙ s) + p, p = (½, ½), t = `sun_scale.zw`
+    // plus its mat-anim delta, R and s from the affine row `[cos − 1, sin, sx − 1, sy − 1]`.
     var vo: VertexOutput;
     vo.position = in.position;
     vo.world_position = in.world_position;
     vo.world_normal = in.world_normal;
 #ifdef VERTEX_UVS_A
-    // **Environment-mapped batches GENERATE their texture coordinates** (`clutter_fade.z` bit 12,
-    // model_render's `ENV_MAP_MARKER`; the asset's `texture_unit_lookup[texCoordSet] > 2`). Such a
-    // batch authors NO usable UVs — GnomeSubwayGlass's 330 vertices all sit at exactly (0,0),
-    // because the runtime is meant to supply them — so reading the raw vertex UV paints the whole
-    // surface in one corner texel of a reflection sheet (the Deeprun Tram tube's flat yellow).
-    //
-    // The coordinate itself is generated in the VERTEX stage, where the reference generates it
-    // (see the derivation there); `in.uv` already carries it, interpolated. All that is left here
-    // is to keep the UV **animation** off it: the reference's gate excludes an env stage from
-    // `textureTransform` by construction (`m2-texanim-uv` §2), so adding the live translation
-    // would drift a reflection that must stay pinned to the view.
+    // An env-mapped coordinate takes no UV animation: the reference excludes an env stage from
+    // `textureTransform`.
     if ((u32(m.clutter_fade.z) & 4096u) != 0u) {
         vo.uv = in.uv;
     } else {
@@ -1398,20 +1236,10 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
     vo.instance_index = in.instance_index;
 #endif
     var pbr_input = pbr_input_from_standard_material(vo, is_front);
-    // Ground-clutter distance fade: multiply the cutout alpha by the camera-distance ramp BEFORE the
-    // alpha test, so distant detail doodads erode out by `clutter_fade.y` yd (the client's ~70-yd
-    // horizon). Disabled (no-op) for normal models where `clutter_fade.w == 0`. This is a draw-distance
-    // concern, not lighting, so it survives the Phase-0 strip.
     var base_color = pbr_input.material.base_color;
-    // WMO batches carry LIGHTING data in the MOCV ALPHA — TRANS (tint.w == 2) the lit↔bake lerp
-    // factor, INT (tint.w == 1) the ×4 self-illumination mask. Bevy pre-folds ATTRIBUTE_COLOR
-    // (rgba) into base_color, but coverage must stay the texel alpha, exactly the reference's
-    // WMO pixel path (its output alpha is tex.a; MOCV.a never reaches coverage —
-    // wow-re models.md). Re-sampling the texture here (same UV, same implicit derivatives — the
-    // texture cache makes it free) replaces the old divide-the-fold-back-out reconstruction,
-    // which was numerically annihilated where MOCV.a ≈ 0: `tex.a × ε ÷ max(ε, 1/255)` collapses
-    // to 0 at ε = 0 and to 4-bit rubble near it — B65's Great Forge chasm deck, whose
-    // self-illumination mask is authored 0, alpha-eroded into "missing floor" exactly there.
+    // WMO MOCV alpha is lighting data (the TRANS lerp, the INT glow mask), and the reference's WMO
+    // output alpha is tex.a alone. Bevy folds the vertex alpha into base_color, so re-sample the
+    // texel alpha: dividing the fold back out loses everything where MOCV.a ≈ 0.
 #ifdef VERTEX_COLORS
     if (m.model_flags.x > 0.5) {
 #ifdef VERTEX_UVS_A
@@ -1419,9 +1247,8 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
             pbr_bindings::base_color_texture,
             pbr_bindings::base_color_sampler,
             vo.uv,
-            // The same LOD `pbr_input_from_standard_material` just sampled the colour at — it
-            // applies `view.mip_bias` itself (1639), and coverage read from a different mip than
-            // the colour is a cutout that erodes out of step with the art it masks.
+            // The colour's LOD: `pbr_input_from_standard_material` applies `view.mip_bias`, and
+            // coverage from another mip erodes out of step with the art.
             view.mip_bias,
         ).a;
 #else
@@ -1429,31 +1256,11 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
 #endif
     }
 #endif
-    // **The detail-doodad LOD BIAS** — the state that decides whether the fade cuts a leaf pixel by
-    // pixel or takes it whole (wow-re `terrain/scratch/doodad-fade-pixel-granularity.md`, 2021).
-    // `0x6813d0` sets `D3DSAMP_MIPMAPLODBIAS = +0.25` on stage 0 at `0x6813f4`, once per frame,
-    // immediately before the pass dispatches `0x6c02d0` — outside `[0x6b1000, 0x6b3200)`, which is
-    // why 2004's state census missed it. Capture-confirmed: all 29 doodad batches bind a sampler
-    // with `GL_TEXTURE_LOD_BIAS = 0.25` where the draws just before them bind an otherwise
-    // byte-identical sampler with bias 0.
-    //
-    // Why a quarter-mip is worth a re-sample: three of the shipped detail atlases (Elwynn's among
-    // them) carry a **binary** alpha pyramid — mip 0 has DXT3's 16 levels, every level below it has
-    // two. A fragment can only reach `a ≈ 1.0`, and so share the terminal death depth, inside a 2×2
-    // all-opaque texel neighbourhood; those neighbourhoods run out between mip 2 and mip 3. Biasing
-    // a quarter-mip blurrier lands the reference past that cliff, so no fragment holds full alpha
-    // and the tuft erodes continuously instead of every leaf crossing together. Measured on the
-    // dominant Elwynn cell, the share of a tuft's pixels leaving in the last half-yard: **2.2 %**
-    // with this bias, **11.6 %** without it.
-    //
-    // wgpu has no sampler LOD bias (WebGPU dropped it), so it goes on the sample. Re-sampling here
-    // rather than pre-biasing the sampler is what keeps it *this lane's* bias: the sampler is shared
-    // with every other model batch, which must keep the reference's 0. Same UV, same implicit
-    // derivatives, so the texture cache makes the second tap nearly free.
-    // `pbr_input_from_standard_material` folds ATTRIBUTE_COLOR and the material tint into what it
-    // sampled; for clutter the material tint is white and the vertex colour is the MCSH lit/shadow
-    // grey, so re-applying `vo.color` reproduces the fold exactly — no divide-back-out, which is the
-    // trap the WMO branch above documents.
+    // The detail-doodad LOD bias (`0x6813f4`): on the atlases whose alpha pyramid is binary below
+    // mip 0 it keeps every fragment below full alpha, so the fade erodes per pixel, not per leaf.
+    // wgpu has no sampler LOD bias and the sampler is shared with unbiased batches, so it goes on
+    // this sample. Clutter's tint is white and its vertex colour the MCSH grey, so `* vo.color`
+    // reproduces Bevy's fold.
     if (m.clutter_fade.w > 0.5) {
 #ifdef VERTEX_UVS_A
         var biased = textureSampleBias(
@@ -1468,26 +1275,10 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         base_color = biased;
 #endif
     }
-    // Ground-clutter distance fade — the reference's stage-1 ramp, byte-exact and capture-confirmed
-    // (wow-re `terrain/scratch/detail-doodad-distance-fade.md`, 2004). Three facts shape this:
-    //
-    //  * **The coordinate is VIEW-SPACE DEPTH, not radial distance.** `0x6b2b80` texgens
-    //    `D3DTSS_TCI_CAMERASPACEPOSITION` (`EGxRs 0x30 = 3`, `TEXCOORDINDEX = stage | 0x20000`)
-    //    through `T(0,0,−52.5)·Ry(π/2)·S(1/17.5)`, giving `u = (z_eye − 52.5) / 17.5`. The fade
-    //    boundary is therefore a PLANE across the view, not a sphere around the camera — which is
-    //    what a radial `distance()` drew here until 2004, and a sphere reads as a hard ring on the
-    //    ground that sweeps as the player moves.
-    //  * **The ramp is a quantised 64-texel table, not a clean 1→0 line.** `0x6b2320` fills a 64×8
-    //    CLAMP/LINEAR texture, RGB white, `alpha = 4·(63 − col)`; a bilinear read across texel
-    //    centres is `alpha = (254 − 256·u)/255`, capped at texel 0's `252/255`. So the plateau ends
-    //    at `near + 0.0078·band` and the ramp reaches zero at `far − 0.0078·band`, never quite at
-    //    the two named radii, and near clutter tops out at 98.8 % opaque, never 100 %.
-    //  * **It multiplies into the alpha the CUTOUT reads.** Both stages take texenv preset 1
-    //    (`MODULATE` on colour AND alpha) and `ALPHAREF` is `detailDoodadAlpha` = 128, so the test
-    //    sees `tex0.a × ramp`: survivors blend at 0.502..0.988 (the visible opacity fade) and the
-    //    tuft erodes out entirely at ramp 128/255, i.e. 61.11 yd of the 70 yd horizon. That erosion
-    //    is the reference's own behaviour, not our artefact — the blend is what makes it read as a
-    //    fade rather than a cut, so what matters is that the survivors are genuinely translucent.
+    // The clutter distance fade, the reference's stage-1 ramp: u = (z_eye − 52.5)/17.5 by a
+    // camera-space texgen (`0x6b2b80`), so the boundary is a view plane, not a sphere; the ramp is
+    // a bilinear read of the 64-texel table `4·(63 − col)` (`0x6b2320`). It multiplies the alpha
+    // the cutout tests (ALPHAREF `detailDoodadAlpha` = 128).
     if (m.clutter_fade.w > 0.5) {
         let z_eye = -(view.view_from_world * vec4<f32>(in.world_position.xyz, 1.0)).z;
         let u = (z_eye - m.clutter_fade.x) / max(m.clutter_fade.y - m.clutter_fade.x, 0.001);
@@ -1495,57 +1286,23 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         base_color.a = base_color.a * ramp;
     }
 
-    // Faithful per-object WORLD-DOODAD distance fade (`FUN_00683f80`/`model_fade.rs`): the fade alpha
-    // (1.0 = opaque) rides in the per-instance `MeshTag`; tag 0 (clutter/WMO) ⇒ 1.0 no-op.
-    // VERIFIED reference behaviour (`RECONCILE-fade-render-state.md`): a fading doodad is the SAME draw
-    // as the steady cutout — the alpha-test ref scales WITH the fade so the effective cutoff stays a
-    // constant `tex0.a < 224/255` (STABLE silhouette, never grows/snaps) — with blend on and source
-    // alpha = `tex0.a × fade`. On the blend twin `AlphaMode::Blend` does no discard, so we re-apply
-    // that hard cutout here on the UNFADED alpha — but ONLY for a twin whose SOURCE batch alpha-tests
-    // (clutter_fade.z bit 10, model_render's TWIN_CUTOUT_MARKER): the reference keys ALPHAREF on the
-    // STORED blend mode (m2-blend-promotion-zfill.md §2), so a fading/stealthed OPAQUE batch blends
-    // with no alpha test at all. Keying the discard on the twin bit itself cut every texel under
-    // 224/255 out of promoted Opaque batches — Gressil's blade body erased to its rune pattern under
-    // stealth (decision 0842). `specialize` keeps depth-write ON for every twin (`model_flags.y`).
-    // The payload is TYPED (mesh_tag.rs, decisions 0173/0720): bits 0-5 = the fade alpha (6-bit
-    // fraction; a whole payload of 0 = the untagged ⇒ opaque sentinel), bits 19-29 = the skin
-    // rig slot (vertex-stage concern — the fragment never reads it, but it rides every payload,
-    // so the 0-sentinel test uses the WHOLE masked payload as before). Between them the exterior
-    // payload carries the per-instance ground-shade byte in bits 6-13 (0 lit → 255 MCSH-shadowed
-    // — decoded at the doodad sun below; entities ramp it, statics leave 0). On an interior-mode
-    // material (interior z, not WMO x) bits 6-18 carry the SH-probe SLOT instead — static MODD
-    // props at spawn, and every indoor entity on the footprint-bake law (decision 0354: units
-    // keep the probe lane indoors; the day/night state is the exterior material at the
-    // intensity-1.0 shade byte, not a mode of its own).
-    // Tag bits 31/30 are standalone flags (mesh_tag.rs), split off before the payload decode so the
-    // 0-sentinel and both payload modes read the masked value: bit 31 = hover/target HIGHLIGHT,
-    // bit 30 = INTERIOR FOG — the instance's model stands in a WMO interior, so it fogs with the
-    // interior triple below (the reference stages unit fog by the unit's own classification,
-    // wow-re m2-unit-interior-fog.md).
+    // The MeshTag (mesh_tag.rs): bit 31 = highlight, bit 30 = interior fog; payload bits 0-5 = the
+    // fade alpha (a zero payload is untagged, opaque), 19-29 = the rig slot, 6-13 = the ground
+    // shade (0 lit, 255 MCSH-shadowed) or, on an interior-prop material, 6-18 = the SH-probe slot.
     let interior_prop = m.model_flags.z > 0.5 && m.model_flags.x < 0.5;
     let raw_tag = mesh_functions::get_tag(in.instance_index);
     let highlighted = (raw_tag & 0x80000000u) != 0u;
     let interior_fogged = (raw_tag & 0x40000000u) != 0u;
-    // Bits 0-5 are the fade alpha in BOTH payload modes, so a feathering indoor entity keeps its
-    // probe AND its alpha ramp — and a skinned part keeps its rig slot through either.
     let fade_tag = raw_tag & 0x3fffffffu;
     let alpha6 = f32(fade_tag & 0x3fu) / 63.0;
     var obj_fade = select(alpha6, 1.0, fade_tag == 0u);
 #ifdef WOW_MERGED_FADE
-    // The merged per-vertex fade composes exactly where the per-entity tag fade did (1420):
-    // every downstream consumer — `faded_alpha`, the multiply-lerp, the additive scale, and
-    // the bit-10 re-discard on UNFADED texel alpha — sees the same algebra an individual
-    // fading doodad produced, so a fader blob on its blend twin feathers exactly like the
-    // reference (and a steady member at fade 1.0 is pixel-identical to the cutout it left).
+    // A merged blob's per-vertex fade composes where the tag fade does, so it feathers the same.
     obj_fade = obj_fade * in.merged_fade;
 #endif
-    // The per-instance body TINT (instance_tint.rs, decision 0812) — the aura state kit's CharProc 1:
-    // an aura painting the whole model one colour (ghost pale blue, poison green, Frostbolt blue).
-    // Indexed by the SAME rig slot the vertex stage skins from (bits 19-29), so it needs no tag bits
-    // of its own; a `0` word is identity, which is every unskinned instance (slot 0) and every
-    // untinted unit. It is the material's ambient+diffuse colour (gx SetState(1) →
-    // GL_COLOR_MATERIAL), so it multiplies the light sum INSIDE the clamp below and never the
-    // emission terms — the same placement the WMO branch already gives MOCV.
+    // The body tint (an aura colouring the whole model), by rig slot, 0 = identity: the material
+    // ambient+diffuse colour (gx SetState(1), GL_COLOR_MATERIAL), so it multiplies the light sum
+    // inside the clamp, never the emission.
     let tint_word = wow_light.rig_tint[(fade_tag >> 19u) & 0x7ffu];
     let inst_tint = select(
         vec3<f32>(
@@ -1556,143 +1313,49 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         vec3<f32>(1.0),
         tint_word == 0u,
     );
+    // The blend twin re-applies its source's cutout: the reference scales ALPHAREF with the fade,
+    // so the cutoff stays tex.a < 224/255 on the unfaded alpha. Only for a source batch that
+    // alpha-tests (bit 10): ALPHAREF keys on the stored blend mode.
     if ((u32(m.clutter_fade.z) & 1024u) != 0u && base_color.a < VANILLA_ALPHA_KEY) {
         discard;
     }
-    // DEPTH-PRIME TWIN (the zfill pipeline variant — terrain.rs `specialize`, the reference's
-    // M2UseZFill clone command, wow-re m2-blend-promotion-zfill.md §4): colour writes are masked
-    // off at the pipeline, so on that variant only the discards above (farclip wall, the
-    // bit-10 twin cutout) shape what depth gets written; the lighting/fog below is computed and
-    // thrown away. (A shader-def early return here would be the natural spelling, but naga's MSL
-    // backend miscompiles the dead tail — "redefinition of '_tmp'" — so the twin pays the colour
-    // math instead. Episodes are transient; the cost is bounded.)
-    // Blend source alpha = texel alpha × fade (translucent fade of the fixed cutout shape). For steady
-    // cutout/opaque draws blend is off so this is ignored; for the fade twin it drives the feather.
+    // The depth-prime twin (`M2UseZFill`) masks colour writes, so only the discards above shape its
+    // depth. No early return: naga's MSL backend miscompiles the dead tail ("redefinition of
+    // '_tmp'").
     let faded_alpha = base_color.a * obj_fade;
-    // Steady cutout (Mask) / opaque discard per the StandardMaterial alpha mode (no-op for the blend twin).
     let base = alpha_discard(pbr_input.material, base_color);
 
-    // --- STEPS 7+8d: matte lighting, split on clutter ---------------------------------------------
-    // M2/WMO meshes get the same directional matte lighting as terrain — `lit = clamp(ambient +
-    // diffuse·max(N·L,0))`, where N is the model's authored vertex normal and L is the Bevy-space
-    // sun travel dir (to-light = `−light_sun`).
-    //
-    // **Clutter is lit by the GROUND normal under each tuft** (Step 8d). VERIFIED faithful: WoW's
-    // CreateDetailDoodads computes the terrain quadrant-plane normal under the tuft and writes it onto
-    // the clutter vertex's normal channel (docs/knowledge/ground-effects.md), and the reference's
-    // clutter draw (apitrace WoW.5, prog 186 / alpha-ref 128/255) lights per-vertex with
-    // `dot(L, that normal)` × a per-vertex colour, MODULATE × texture — so a tuft darkens with the
-    // ground it stands on (shaded/sloped tufts go darker, like the dirt beneath). We bake that normal
-    // in clutter.rs (`terrain_normal_at`). World-up was an earlier flat-ground approximation, removed.
-    // **Exterior M2 doodads take the verified `Model2.bls` sun curve** (0747, below) with the
-    // diffuse/sun term scaled by the terrain-shade at the doodad's base (lit vs MCSH-shadowed ground);
-    // clutter and WMO keep the plain FFP `ambient + diffuse·max(N·L,0)` — clutter lit by the ground
-    // normal, WMO by its own (both genuinely fixed-function reference programs).
+    // --- Lighting --------------------------------------------------------------------------------
     let is_clutter = m.clutter_fade.w > 0.5;
     let L = -normalize(wow_light.light_sun.xyz);
-    // `wow_normalize`, not `normalize`: the unskinned lane carries an authored `(0,0,0)` normal
-    // through to here unchanged, and a NaN out of this line blacks the whole batch (see the helper).
+    // `wow_normalize`: an authored zero normal reaches here on the unskinned lane.
     let n_m2 = wow_normalize(pbr_input.world_normal);
-    // Bevy negates `world_normal` on the back faces of any DOUBLE-SIDED material — two-sided foliage
-    // cross-quads (grass tufts, leaf cards) AND every WMO group face (our WMO loader marks all WMO
-    // submeshes two-sided, models.rs). The reference has NO such per-face negation: WoW sets the GL
-    // lighting model once (`FUN_0059ce30`) and NEVER enables `GL_LIGHT_MODEL_TWO_SIDE`, so BOTH faces of
-    // every polygon — clutter, M2 doodad, WMO group — are lit from the SAME submitted normal. So we
-    // un-flip Bevy's negation here and light EVERY path below from `n_lit`; the raw `n_m2` is never used
-    // for lighting directly. For single-sided materials back faces are culled ⇒ `is_front` always true
-    // ⇒ `n_lit == n_m2` (no-op). Universal "two-side-off" fix → no view-dependent lit/unlit seam, on
-    // M2 foliage (doodad matte path) OR WMO group geometry (the FFP N·L path below) (foliage.md).
+    // Bevy negates `world_normal` on back faces of double-sided materials (foliage, every WMO
+    // face); the reference never enables GL_LIGHT_MODEL_TWO_SIDE (`FUN_0059ce30`), so undo it.
     let n_lit = select(-n_m2, n_m2, is_front);
     let ndotl = max(dot(n_lit, L), 0.0);
     let lit_nl = clamp(wow_light.light_ambient.rgb + wow_light.light_diffuse.rgb * ndotl, vec3<f32>(0.0), vec3<f32>(1.0));
-    // The order-2 SH basis products over the fragment normal — shared by the global exterior eval
-    // below and the interior-prop probe lane further down.
+    // The order-2 SH basis, shared by the exterior lobe and the interior probes.
     let quad = vec4<f32>(n_lit.x * n_lit.y, n_lit.y * n_lit.z, n_lit.z * n_lit.z, n_lit.x * n_lit.z);
     let n1 = vec4<f32>(n_lit, 1.0);
     let x2y2 = n_lit.x * n_lit.x - n_lit.y * n_lit.y;
-    // Exterior world doodad/entity: **the reference's own response** —
-    // `clamp01(A + C·I·(4/17)(0.375 + 2μ + 1.875μ²))`, μ = N·u toward-light, the order-2
-    // `Model2.bls` lobe evaluated over the SH rows above (0803; read that record and 0796 before
-    // touching this lane).
-    //
-    // The long way round, because the scar tissue matters: 0410 replaced this curve with a
-    // hard-cutoff FFP matte on the director's look call — a sunlit character's shadow side must read
-    // the SAME as the same skin standing in shade, and the lobe's authored wrap (0.059·C on the
-    // anti-sun side, dipping −0.037·C mid-back) tinted it warm and lifted it. 0753 then read the
-    // reference's own apitrace as CORROBORATING the cutoff (an FFP light slot, "no SH constants
-    // anywhere in the trace"). **0796 refuted that**: wow-re's §5 cross-check shows the reference's
-    // M2 lane — ADT doodad, GameObject, creature, player alike — is its own authored `Model2.bls`
-    // vertex shader running order-2 SH, and the FFP light commits visible in a world frame belong to
-    // TERRAIN (`0x71c730`'s five `0x68xxxx` call sites) and the WMO path. M2's single FFP call site
-    // (`70bdf6`) is reachable only with `M2UseShaders` off. "No SH constants" was a measurement
-    // artifact — constants upload as dirty-range deltas whose start register varies. That left 0410
-    // standing as a look preference against a verified curve, so 0799 put the two behind an A/B and
-    // 0803 is the director choosing the curve. The cutoff branch left with the flag.
-    //
-    // The CPU light animator targets the per-instance intensity `[node+0xa4]` — 2.5 on lit ground
-    // / 0.5 on MCSH-shadowed ground / 1.0 on the interior/WMO-prop leg (`0x69e4ad`, `0x69e280`;
-    // the force-1.0 leg is `0x69e36b`). Lane history: `Model2.bls` SH lobe (0354/0358) → FFP
-    // matte, hard cutoff (0410, director's call) → unclamped source (0706) → verified curve
-    // (0747) → peak-norm (0750) → calibration dial (0751) → the 0753 trace law → 0796 (kept the
-    // pixels, demoted the justification) → 0799 (the A/B) → 0803, back on the curve for good.
-    //
-    // The per-material `sun_scale.x` selector has THREE states (model_render::ShadeSel): ≥0.85 =
-    // the lit-ground family — **entity M2s only** since 2050 (animator target 2.5, mixed toward
-    // 0.5 by the per-instance tag shade byte, which units/players/GameObjects ramp CPU-side like
-    // the binary's `0x69e770`); 0.5..0.85 = fixed intensity 1.0, which is **both doodad classes**
-    // (an ADT map doodad and an exterior WMO MODD prop are one C++ class and neither can reach the
-    // 2.5 site); <0.5 = statically MCSH-shadowed (0.5). Statics leave the tag byte 0. The ramp
-    // runs in animator units and the COMMIT clamps.
-    //
-    // **`min(I, 1)` is OURS, and it is the one unfaithful term in this lane (0803 §3, 0814, 0821).**
-    // The reference does not cap the gain. On the VS/SH lane — the default config, and the lane this
-    // shader IS — `0x71c4e0` bakes `[node+0xa4]` straight into the SH moments with no clamp; on the
-    // FFP lane `0x71c730`→`0x71ca80` clamps the **product** `D × I` (by max-channel, preserving hue),
-    // never the multiplier. So the cap below is a benilla choice, and it costs us twice:
-    //
-    //   1. **Brightness.** A lit ENTITY — unit, player, GameObject — commits ×1.0 where the
-    //      reference gives ×2.5, so characters in sun read dimmer than the reference. Still open —
-    //      lifting it pushes a sun-facing surface well past 1.0 (with an over-gamut sun, into green
-    //      as well), which is a world-wide look change and the director's call, not one to
-    //      self-grade. (Doodads were in this sentence until 2050; see below.)
-    //
-    //      **Doodads are NOT in that sentence any more (2050).** wow-re settled it at the bytes
-    //      and in the capture: a `CMapDoodadDef` — ADT MDDF and WMO MODD alike — commits 1.0 lit /
-    //      0.5 shadowed and never ramps; it has no ramp target field (`+0xf8` is `m[2][3]` of its
-    //      world matrix), and the 2.5 belongs to the WENTITY node an entity hangs off `[obj+0xe0]`.
-    //      §6's attribution of 2.5 to ADT doodads was the error. So this cap is a **no-op on the
-    //      faithful doodad input** and never dimmed a tree; what it dims is units, players and
-    //      GameObjects, which is what item 1 above is now about.
-    //
-    //      The trap that leaves behind, and why 2050 moved the selector rather than waiting for
-    //      the cap: feeding every M2 a lit 2.5 and then capping emits the right number for a lit
-    //      doodad **for the wrong reason**. Lifting the cap without giving doodads their own 1.0
-    //      would have taken every tree in Elwynn to 2.5×, and a uniformly too-bright world is the
-    //      kind of wrong nobody files. The scale is per-class now, so that is no longer coupled.
-    //   2. **Timing — fixed CPU-side (0821).** Because the cap sits on the multiplier, every target
-    //      from 2.5 down to 1.0 renders identically, so a unit ramping 2.5 → 0.5 spent its first
-    //      0.45 s (75 % of the chase) invisibly pinned at 1.0 and then dropped in 0.15 s. It read as a
-    //      dead pause then a snap — what the director reported walking sun → shade.
-    //      `entity_shade::LIT_T` now aims the LIT target at the value this cap can actually show
-    //      (1.0), so the chase moves only through visible range, at the reference's own
-    //      3.3333 intensity-units/s. The cap is a backstop here, not the thing the ramp fights.
-    //
-    // Two faces of one bug, and they unwind together: **cut `min(I, 1)` and `LIT_T` goes back to 0.0**
-    // so the full 2.5 → 0.5 sweep becomes visible on its own. Do not cut one alone — and note that
-    // the pair is now an ENTITY-only concern: since 2050 no doodad rides this band, so lifting the
-    // cap changes units, players and GameObjects and leaves the world's trees and props where they
-    // are. That decoupling was the prerequisite, and it is done. (Units are on this
-    // chain again — 0809's flat ×1.0 pin was wrong and 0814 reverted it; the null fallback that
-    // motivated it is real, but it is a lifecycle state we do not model.)
+    // Exterior doodads and entities: the header's `Model2.bls` lobe at the per-instance intensity
+    // I, `[node+0xa4]` (animator targets 2.5 lit and 0.5 shadowed, `0x69e4ad`/`0x69e280`; 1.0
+    // indoors, `0x69e36b`). `sun_scale.x` picks the family:
+    //   ≥ 0.85: an entity M2, 2.5 mixed toward 0.5 by the tag's shade byte (ramped like `0x69e770`)
+    //   0.5..0.85: a doodad (ADT MDDF or WMO MODD, both `CMapDoodadDef`): 1.0, never 2.5
+    //   < 0.5: a doodad on MCSH-shadowed ground: 0.5
+    // Deviation: `min(I, 1)`. The reference bakes I into the SH unclamped (`0x71c4e0`), so a lit
+    // entity commits ×2.5 there and ×1.0 here; lifting the cap takes sun-facing surfaces past 1.0.
+    // `entity_shade::LIT_T` aims the lit ramp at 1.0 because of it: lift the cap and set `LIT_T`
+    // back to 0.0 together.
     let inst_shade = select(f32((fade_tag >> 6u) & 0xffu) / 255.0, 0.0, interior_prop);
     let mat_shade = select(0.0, 1.0, m.sun_scale.x < 0.5);
     let shade_t = max(mat_shade, inst_shade);
     let mid_band = m.sun_scale.x >= 0.5 && m.sun_scale.x < 0.85;
     let intensity = min(select(mix(2.5, 0.5, shade_t), 1.0, mid_band), 1.0);
-    // The lobe. Same closed form the interior-prop lane below runs and the same one
-    // `pack_model_core_rows` folds. Every sun band is linear in the committed colour, so ONE
-    // `intensity` multiply covers the whole lobe (never I²); ambient rides the c10 `.w` lanes and
-    // does NOT scale with it, and the sun's DC redistribution rides `grade.yzw`.
+    // One `intensity` multiply covers every sun band (never I²); the c10 `.w` ambient does not
+    // scale. `pack_model_core_rows` packs the same closed form.
     let sun_dc = wow_light.grade.yzw * intensity;
     let sun_lobe = vec3<f32>(
         wow_light.sh_c10_r.w + sun_dc.x
@@ -1708,36 +1371,19 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
                 * (dot(wow_light.sh_c10_b.xyz, n_lit) + dot(wow_light.sh_c13_b, quad)
                     + wow_light.sh_c16.z * x2y2),
     );
-    // clamp01 the SUM, never per term — the lobe dips to −0.037·C around μ≈−0.53 (low-order-SH
-    // ringing, the reference's own authored response), and clamping the sun term alone would floor
-    // that away and erase the mid-back dip. That dip is part of the response 0803 chose, not noise
-    // to tidy up.
+    // Clamp the sum, never a term: the lobe's own ringing dips to −0.037·C near μ ≈ −0.53, and a
+    // per-term clamp would erase it.
     let lit_doodad = clamp(sun_lobe, vec3<f32>(0.0), vec3<f32>(1.0));
-    // WMO buildings (model_flags.x) use the FFP directional N·L at sun-scale 1.0 — the reference lights them
-    // with `ambient + sun·max(N·L,0)` and does NOT apply the exterior doodad terrain-shade (verified: prog
-    // 198/VS 151). Their per-vertex MOCV shade rides in `base_color` (ATTRIBUTE_COLOR) → folds into `albedo`,
-    // giving tex × MOCV × lit. Exterior world doodads (not clutter, not WMO) take the terrain-shaded matte;
-    // clutter uses its own ground-normal matte. `light_sun.w` is the directional-enable flag (on outdoors).
+    // WMO and clutter take the FFP N·L light with no terrain shade; the lobe needs the directional
+    // light on (`light_sun.w`).
     let is_wmo = m.model_flags.x > 0.5;
     let is_interior = m.model_flags.z > 0.5;
     let use_doodad_shade = (wow_light.light_sun.w > 0.5) && !is_clutter && !is_wmo;
     let lit_exterior = select(lit_nl, lit_doodad, use_doodad_shade);
-    // WMO INTERIOR surfaces (model_flags.z; groupFlags & 0x48 == 0) — by BATCH CLASS (tint.w; wow-re
-    // trace-forensics-abbey-interior-d3d §2, observed on the abbey at close range):
-    //   INT (tint.w = 1): UNLIT — the draw is pure `tex × MOCV`; the baked vertex colours (the
-    //     artists' lamp/forge/hearth/candle warmth) ARE the room's light, constant day and night.
-    //     No exterior light, no point lights (the reference commits zero to any WMO surface).
-    //   TRANS (tint.w = 2): the per-vertex MOCV-ALPHA LERP between the day/night-lit surface and
-    //     that unlit bake — the reference's two-pass (lit × SRC_ALPHA + unlit × (1−SRC_ALPHA))
-    //     collapsed to one pass: `mix(1, extLit, MOCV.a)` as the lit factor.
-    //   EXT (tint.w = 0): an interior group's exterior-law batches — plain `lit_nl`.
-    //
-    // WINDOW (MOMT 0x20, m.sidn.w) — interior drawer only: the batch's lit lanes swap GL_LIGHT0 to
-    // the brighter interior pair, ambient AND diffuse = the MIDPOINT of the Direct (sun diffuse) and
-    // Ambient bands, ambient +16/255 saturating (wow-re wmo-interior-night-light §2, 0x6d37e0). It
-    // folds the warm Direct band in at full weight, so an interior pane reads bright and warm in
-    // daylight instead of taking the flat exterior ambient — and still tracks time of day. The
-    // exterior drawer has no WINDOW machinery, so exterior-group batches keep plain lit_nl.
+    // WMO interior groups (`groupFlags & 0x48 == 0`) by batch class (`tint.w`): INT (1) is unlit
+    // `tex × MOCV`; TRANS (2) is the reference's two passes, lit × MOCV.a + unlit × (1 − MOCV.a),
+    // as one lerp; EXT (0) is `lit_nl`. A WINDOW batch (MOMT 0x20) on the interior drawer lights
+    // with ambient = diffuse = the Direct/Ambient midpoint, ambient +16/255 (`0x6d37e0`).
     var trans_a = 1.0;
 #ifdef VERTEX_COLORS
     trans_a = in.color.a;
@@ -1755,19 +1401,12 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
     } else if (m.tint.w < 0.5) {
         lit_wmo_interior = lit_int_base;
     }
-    // INTERIOR M2 PROPS — WMO MODD doodads only (inn kegs/tables/candelabra; is_interior but NOT
-    // is_wmo). The real client fills the prop's base ONCE at create from the MODD entry's own baked
-    // colour (never a footprint sample — that chain is the ADT-MDDF path) and commits it with the
-    // fixed-axis diffuse lobe + the owning group's MOLR point lobes as an order-2 SH probe the
-    // vertex shader evaluates (wow-re trace-forensics-abbey-interior-d3d §1, decoded live off the
-    // abbey stands to ~1e-7). benilla folds the identical closed form at spawn
-    // (`lighting::prop_probe_coeffs`) into the per-instance probe table; the MeshTag payload is the
-    // slot. Evaluated here per fragment over the same basis — note the SH lobe's soft wrap (side-on
-    // ≈ 0.088·C) is the reference's authored response, deliberately NOT a hard max(N·L,0).
-    // Units/GameObjects never reach this lane (base CGLight — plain day/night ×1.0, §8/§9).
+    // Interior M2 props (WMO MODD doodads): the reference commits the prop's MODD colour through a
+    // fixed-axis diffuse lobe plus its group's MOLR lights as an order-2 SH probe, folded at spawn
+    // by `lighting::prop_probe_coeffs` and evaluated here per fragment (the reference: per vertex).
+    // Its soft wrap (≈ 0.088·C side-on) is the reference's response, not a max(N·L, 0).
 #ifdef WOW_MERGED_SLOT
-    // A merged interior-prop blob (1418 lane 3): the slot is baked per vertex — the tag's
-    // payload bits belong to the whole blob and carry only fog/alpha.
+    // A merged blob bakes the slot per vertex; its tag carries only fog and alpha.
     let probe = 7u * in.merged_slot;
 #else
     let probe = 7u * ((fade_tag >> 6u) & 0x1fffu);
@@ -1788,13 +1427,8 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         vec3<f32>(1.0),
     );
     let lit_interior = select(lit_m2_interior, lit_wmo_interior, is_wmo);
-    // AUTHORED-RIG lane (`ShadeSel::Rig`, sun_scale.x = 2.0 — the glue create booth, decision
-    // 0429): the lit value is the probe-slot SH eval — the scene M2's ambient + directional
-    // lights, folded into slot 0 of the material's OWN buffer (booth instances carry tag 0, so
-    // `lit_m2_interior` above already evaluated exactly that probe). No sun, no intensity family,
-    // no day/night — a glue scene's light is entirely its authored rig. Rig materials are neither
-    // WMO nor interior, so the per-vertex point term (the rig's authored point lights) flows in
-    // through `point_diffuse` below like any exterior entity.
+    // The authored-rig lane (`ShadeSel::Rig`, glue scenes): the scene's lights are folded into
+    // probe slot 0 of the material's own buffer, which `lit_m2_interior` already evaluated (tag 0).
     let is_rig = m.sun_scale.x >= 1.5;
     let lit = select(select(lit_exterior, lit_interior, is_interior), lit_m2_interior, is_rig);
     // MONKEY (shadow hook): the realtime shadow (fetch + edge/night fade) is computed by
@@ -1874,27 +1508,20 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         lit_with_shadow = sky * player_moon;
     }
 
-    // Gamma-space albedo — the lane (0161): the buffer holds bytes, lighting math runs on the
-    // authored values. (The old fog_params.z linear-space A/B is dead — settled by the lane.)
-    // `m.tint` is the animated M2Color RGB (identity 1 for static batches) — the same per-batch
-    // tint the vertex colours carry for constant tracks, so it folds at the same point.
-    let albedo = base.rgb * (m.tint.rgb + wow_light.matanim[u32(m.anim_slots.y)].xyz);
-    // Unlit fullbright (model_flags.w): M2 UNLIT (0x01) glass/glow cards, or WMO UNLIT on an
-    // exterior-group batch (`tex × white` — the inn's always-lit outside panes). Wins over the lit
-    // path; faithfully receives NO emission terms (lighting is off, so GL_EMISSION is dead there).
+    // Gamma-space albedo: lighting runs on the authored byte values. `m.tint` plus its mat-anim
+    // delta is the animated M2Color tint.
+    let anim_tint = m.tint.rgb + wow_light.matanim[u32(m.anim_slots.y)].xyz;
+    let albedo = base.rgb * anim_tint;
+    // An unlit batch replaces the lit path: fullbright, with only the highlight added (below).
     let is_emissive = m.model_flags.w > 0.5;
-    // SIDN night glow (MOMT 0x10, m.sidn.rgb): the authored emissive × the live night fraction
-    // (grade.x — 1 overnight, 0 all day, ramps 20:30→21:30 / 06:00→07:00). A GL material EMISSION
-    // term, so it adds INSIDE the clamped lit sum (tex × (lit + sidn·night)) and reaches LIT lanes
-    // only: exterior-drawer lit batches and an interior group's EXT lane at full weight, TRANS by
-    // its lit-pass weight (MOCV.a), and never the unlit INT lane (wow-re wmo-interior-night-light
-    // §4, wmo-lit-selector §1.3). Zero for every M2 batch.
+    // SIDN night glow: the emissive × the night fraction (ramping 20:30→21:30, 06:00→07:00), a
+    // GL_EMISSION term inside the clamped lit sum, on lit lanes only.
     var sidn_w = 1.0;
     if (is_interior && is_wmo) {
         if (m.tint.w > 1.5) {
-            sidn_w = trans_a; // TRANS: emission rides the lit pass A, weighted by the lerp
+            sidn_w = trans_a; // TRANS: weighted by its lit pass
         } else if (m.tint.w > 0.5) {
-            sidn_w = 0.0; // INT: lighting off — the emissive write is dead, like the FFP
+            sidn_w = 0.0; // INT: unlit, so no emission
         }
     }
     let sidn_e = m.sidn.rgb * (wow_light.grade.x * sidn_w);
@@ -1933,45 +1560,29 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         );
     }
 
-    // Hover/target model brighten (tag bit 31): the client's per-model highlight emissive —
-    // `glMaterialfv(GL_EMISSION, +64/255)` per channel (shipped config default 0xff404040), verified
-    // wow-re selection-circle PART 2. GL_EMISSION adds INSIDE the lighting sum, which is clamped [0,1]
-    // BEFORE the texture modulate — darks lift toward fully-lit, already-bright spots saturate. It
-    // rides the lighting equation, so the fullbright/UNLIT path below faithfully never receives it.
-    let highlight = select(0.0, 0.2509804, highlighted);
-    // FFP combine (byte + trace verified, decision 0273): the LIGHT SUM — matte base + point lights +
-    // the highlight emission — saturates per fragment FIRST, and the texture modulates the clamped
-    // result, so a surface never exceeds its own fully-lit texture (a fixture light at zero distance
-    // drives the prop to tex×1, not past it — the old `clamp(albedo·sum)` order blew emitter props to
-    // saturated gold). WMO surfaces fold their vertex colour INSIDE the clamp (GL_COLOR_MATERIAL:
-    // MOCV is the material ambient+diffuse — `tex × clamp(MOCV·sum + emission)`), so a strong fixture
-    // light overdrives a dim bake toward the full texture exactly like the reference. Bevy pre-folds
-    // ATTRIBUTE_COLOR into `base`, so un-fold it with a guarded divide (a dim channel's product is ~0
-    // either way). At zero point contribution every factor is ≤1 and both forms collapse to the old
-    // product — the approved interior/exterior base looks are preserved bit-for-bit.
+    // The hover/target highlight (tag bit 31): the scene's committed ambient
+    // (`0x614576`-`0x6145bd`), added to the batch colour inside the final clamp, lit or unlit
+    // (`c29`). Sampled live, where the reference holds the value sampled when the highlight
+    // began: a unit's tag has no slot to hold a colour, and the ambient moves slowly.
+    let highlight = select(vec3<f32>(0.0), wow_light.light_ambient.rgb, highlighted);
+    // The FFP combine: the light sum (lit, point lights, emission) clamps first and the texture
+    // modulates it, `tex × clamp(C·sum + emission)`, with C the GL_COLOR_MATERIAL colour (MOCV on
+    // WMO, the body tint on M2). The WMO branch divides Bevy's MOCV fold back out, guarded; a dim
+    // channel's product is ~0 either way.
     var lit_rgb: vec3<f32>;
 #ifdef VERTEX_COLORS
     if (is_wmo) {
         let vc = in.color.rgb;
-        // MOCV multiplies the lit terms (GL_COLOR_MATERIAL) but NOT the emission terms — SIDN and
-        // the highlight add alongside, exactly the FFP's material-emission placement.
         let primary = clamp(
-            vc * (lit_with_shadow + point_diffuse) + sidn_e + vec3<f32>(highlight),
+            vc * (lit_with_shadow + point_diffuse) + sidn_e + highlight,
             vec3<f32>(0.0),
             vec3<f32>(1.0),
         );
         let tex_rgb = base.rgb / max(vc, vec3<f32>(1.0 / 255.0));
         lit_rgb = tex_rgb * m.tint.rgb * primary;
         if (is_interior && m.tint.w > 0.5 && m.tint.w < 1.5) {
-            // INT: the MOCV-ALPHA SELF-ILLUMINATION term. The reference's interior pixel shader is
-            // `tex·MOCV.rgb·(1 + 4·MOCV.a)` with only the framebuffer's final [0,1] clamp — read
-            // off the client's own D3D pixel shader in the Goldshire-inn trace (literal 4.0 in the
-            // source, no lights referenced), so the glow multiplies the FULL product and may
-            // overdrive it to white, never pre-clamped like the FFP light sum above. The alpha
-            // channel is an authored emissive mask: the inn fireplace surround bakes α≈100 (×2.6),
-            // hearths glow, and the FixColorVertexAlpha 255 at interior↔exterior portal seams
-            // lifts doorways to full brightness. Near-zero everywhere unpainted (the abbey rooms),
-            // where this collapses to the plain tex×MOCV it replaces.
+            // INT: the reference's interior pixel shader, `tex·MOCV.rgb·(1 + 4·MOCV.a)` with only
+            // the framebuffer's final clamp.
             lit_rgb = clamp(
                 tex_rgb * m.tint.rgb * vc * (1.0 + 4.0 * trans_a),
                 vec3<f32>(0.0),
@@ -1979,24 +1590,19 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
             );
         }
     } else {
-        // An M2 instance: `inst_tint` is its CM2 modulate colour, multiplying the light terms inside
-        // the clamp exactly where the WMO branch above multiplies MOCV — both are the material's
-        // ambient+diffuse under GL_COLOR_MATERIAL — and never the emission terms beside them. It is
-        // identity for everything untinted, so this is the old product bit-for-bit until an aura
-        // writes a colour. (Left off the `is_wmo` branch on purpose: a WMO surface is not a CM2
-        // instance and has no tint slot of its own.)
+        // An M2: the body tint multiplies the light terms as MOCV does above. A WMO surface has
+        // no tint slot, so the WMO branch leaves it out.
         let primary = clamp(
-            inst_tint * (lit_with_shadow + point_diffuse) + sidn_e + vec3<f32>(highlight),
+            inst_tint * (lit_with_shadow + point_diffuse) + sidn_e + highlight,
             vec3<f32>(0.0),
             vec3<f32>(1.0),
         );
         lit_rgb = albedo * primary;
     }
 #else
-    // (`sidn_e` is zero for every M2 batch; a WMO batch without MOCV lands here too and keeps it —
-    // harmlessly, since a WMO instance's tint slot is the identity slot 0.)
+    // A WMO batch without MOCV lands here too; its tint slot is the identity slot 0.
     let primary = clamp(
-        inst_tint * (lit_with_shadow + point_diffuse) + sidn_e + vec3<f32>(highlight),
+        inst_tint * (lit_with_shadow + point_diffuse) + sidn_e + highlight,
         vec3<f32>(0.0),
         vec3<f32>(1.0),
     );
@@ -2028,7 +1634,7 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         // lane's light sum too. It is the same GL_EMISSION placement as the exterior branches above
         // — added to the material's ambient+diffuse product INSIDE the [0,1] saturate, with the
         // texture (`albedo`) modulating the clamped result — so an indoor chair lifts by exactly the
-        // +64/255 an outdoor one does. It has to be folded HERE, not left in `lit_rgb`, because this
+        // the scene-ambient lift an outdoor one does. It has to be folded HERE, not left in `lit_rgb`, because this
         // lane REPLACES the exterior result a few lines down (`mix(lit_rgb, room_rgb, lane_w)`):
         // with `lane_w` at 1 (a settled indoor unit) the exterior sum that carried the lift was
         // discarded wholesale, which is why hovering a chair inside a Stormwind house brightened
@@ -2045,7 +1651,7 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         let bake = INTERIOR_BAKE_ENTITY_MEAN * (fract(wow_light.sh_c16.w) / BAKE_LANE_SCALE);
         var room_rgb = albedo * clamp(
             inst_tint * (vec3<f32>(1.0) - exp(-(room + vec3<f32>(bake)) * wow_light.point_count.w))
-                + vec3<f32>(highlight),
+                + highlight,
             vec3<f32>(0.0),
             vec3<f32>(1.0),
         );
@@ -2070,32 +1676,37 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
         let lane_w = select(f32((fade_tag >> 15u) & 0xfu) / 15.0, 1.0, is_interior);
         lit_rgb = mix(lit_rgb, room_rgb, lane_w);
     }
-    // The fullbright/UNLIT path takes the tint too, unlike the highlight: with GL_LIGHTING off the
-    // same gx state (SetState(1)) is a plain `glColor` modulate on the texture, while GL_EMISSION is
-    // dead. So a ghost's glow cards tint with its body.
-    var rgb = select(lit_rgb, albedo * inst_tint, is_emissive);
+    // The unlit path: an M2's unlit program outputs `c28 + c29` (`0x70c663`-`0x70c693` fold the
+    // tint·M2Color term into `c29` beside the highlight), so the texel modulates
+    // `clamp(C·tint + highlight)`, C the M2Color. A WMO keeps the plain modulate.
+    var unlit_rgb = albedo * inst_tint;
+    if (!is_wmo) {
+#ifdef VERTEX_COLORS
+        // The constant M2Color rides the vertex colour, which Bevy folded into `base`.
+        let unlit_c = in.color.rgb * anim_tint;
+        let unlit_tex = base.rgb / max(in.color.rgb, vec3<f32>(1.0 / 255.0));
+#else
+        let unlit_c = anim_tint;
+        let unlit_tex = base.rgb;
+#endif
+        let unlit_sum = unlit_c * inst_tint + highlight;
+        unlit_rgb = unlit_tex * clamp(unlit_sum, vec3<f32>(0.0), vec3<f32>(1.0));
+    }
+    var rgb = select(lit_rgb, unlit_rgb, is_emissive);
+    // An M2 Mod or Mod2x batch draws the bare texel: the reference zeroes its tint·M2Color term and
+    // forces the primary colour to the blend identity (`0x70c507`/`0x70c5b8`), so neither the
+    // animated M2Color nor the body tint reaches it. Its alpha still does, through the lerp below.
+    let is_mod = (u32(m.clutter_fade.z) & 128u) != 0u;
+    let is_mod2x = (u32(m.clutter_fade.z) & 256u) != 0u;
+    if ((is_mod || is_mod2x) && !is_wmo) {
+        rgb = base.rgb;
+    }
 
-    // Step 5 fog — same gamma-space linear fog as terrain.wgsl. Same DBC values are pushed onto
-    // both materials by `apply_wow_lighting`, so a tree and the dirt under it land on the same
-    // haze byte at the same distance. Fog coordinate is PLANAR eye-Z (view-space depth), NOT radial
-    // distance — see terrain.wgsl for the apitrace-verified rationale (radial over-fogs the edges).
-    // The fog COLOUR is per-batch policy (M2 state setter 0x70baf0, wow-re ROUND 4): scene for
-    // opaque/alpha, BLACK for additive (the batch fades under the storm veil instead of adding grey
-    // — the level-up fix), WHITE for Mod, GREY for Mod2x; policy 4 (render flag 0x02) = unfogged.
-    // Encoded in clutter_fade.z bits 4-6.
-    // Interior lanes fog with the INTERIOR triple — the room keeps its warm MFOG haze while the
-    // storm's veil stays on everything seen through the door. ONE route in, the per-INSTANCE tag
-    // bit 30, written by two disjoint owners for the two mechanisms the reference has:
-    //   * room-bound WMO content (group geometry, its doodad props) takes the client's per-group
-    //     `[0xca7f00]` gate on the two interior-fog pushes `0x6b5190`/`0x6b62e0` (round-6 Q-I),
-    //     resolved per frame by the portal flood (`wmo_portal::GroupPvs::interior_fog`);
-    //   * an entity M2 takes its OWN light-node classification (`0x71c110`/`[node+0xc]`, wow-re
-    //     m2-unit-interior-fog.md), which is a different gate on the same triple.
-    // The material's own `model_flags.z` is NOT that test: it is static per batch, so before
-    // decision 1787 every true-interior group in a building wore the building's MFOG the moment
-    // the camera stood anywhere inside it — B335, where the Shadowfang room two exterior-lit
-    // courtyards away read as a flat teal wash at 70 yd. At camera-out the two triples are equal,
-    // so the bit only ever diverges inside a fogged WMO. Every other lane inherits the scene fog.
+    // Linear fog by planar eye depth, as in terrain.wgsl. Per-batch colour policy (`clutter_fade.z`
+    // bits 4-6, the M2 state setter `0x70baf0`): 0 scene, 1 black (additive), 2 white (Mod),
+    // 3 grey (Mod2x), 4 unfogged (render flag 0x02). Tag bit 30, not the static `model_flags.z`,
+    // selects the interior triple: WMO content by the per-group `[0xca7f00]` gate on the pushes
+    // `0x6b5190`/`0x6b62e0`, an entity M2 by its node's classification (`0x71c110`, `[node+0xc]`).
     var fog_color = wow_light.fog_color;
     var fog_span = wow_light.fog_params.xy;
     if (interior_fogged) {
@@ -2116,52 +1727,27 @@ fn fragment(in: WowVsOut, @builtin(front_facing) is_front: bool) -> WowFragOut {
 
 
     var out: WowFragOut;
-    // Raw gamma out (GAMMA LANE, 0161 — the frame's one decode is the FFXGlow combine). Alpha = the
-    // faded cutout alpha (tex × fade) for the blend twin; ignored (blend off) on steady/opaque draws.
-    // OPAQUE-INTENT alpha pin (clutter_fade.z bit 3, set in model_render for steady opaque/alpha-key
-    // batches): their output alpha is spec-meaningless — opaque/mask pipelines ignore it; only a blend
-    // pipeline would read it, and none should ever be bound for them. Pinning it to 1.0 is therefore a
-    // no-op under correct pipeline state, and armor under the observed multi-view pipeline mixup
-    // (macOS/Metal: with an extra camera, some opaque WMO/M2 draws intermittently bind a blending
-    // pipeline and bleed the BLP's garbage alpha — the "pale film on buildings"). Fade twins, genuine
-    // Blend batches (glass), and additive glow cards keep their real alpha.
+    // Output alpha is tex × fade. Opaque intent (`clutter_fade.z` bit 3) pins it to 1: a no-op
+    // under correct pipeline state, and a guard for macOS/Metal with an extra camera, where an
+    // opaque draw can bind a blending pipeline and show the BLP's garbage alpha.
     let opaque_intent = (u32(m.clutter_fade.z) & 8u) != 0u;
-    // ADDITIVE batches (glow cards — model_flags.w == 2.0): fold the alpha weight into the colour
-    // HERE, in gamma space, exactly as the reference's byte pipeline weights its source term
-    // (src_g·α added in bytes). The old hardware `SrcAlpha` blend multiplied AFTER the linear
-    // conversion — α^(1/2.2) inflation that fattened every soft halo into a hard disc (the
-    // director's brazier, decision 0160). The pipeline blend state is now a pure (ONE, ONE) add.
-    // The additive marker is clutter_fade.z BIT 2 (the same word specialize keys on — NOT
-    // model_flags.w, whose stale "== 2.0" comment caused the flat-square regression the director
-    // caught: the gate never fired while the blend state had already become a pure add).
+    // Additive (`clutter_fade.z` bit 2, the bit `specialize` keys the (ONE, ONE) blend on): the
+    // alpha weight folds into the colour here, in gamma, as the reference weights its source.
     let is_additive = (u32(m.clutter_fade.z) & 4u) != 0u;
     var out_rgb = rgb;
     if (is_additive) {
         out_rgb = out_rgb * faded_alpha;
     }
-    // MULTIPLY batches (Mod bit 7 / Mod2x bit 8 — the ARMORREFLECT sheen family, 0528): their
-    // blend equation reads no source alpha, so the instance fade cannot ride the alpha channel.
-    // It rides the SOURCE COLOUR instead, and that is the reference's own mechanism, not a
-    // deviation: texenv preset 5 (`INTERPOLATE, TEXTURE·PREVIOUS·PREVIOUS`) computes
-    // `mix(prev.rgb, tex.rgb, prev.a)`, the mode-5/6 arms force the primary colour to the blend
-    // IDENTITY — V_A=0, V_B = white (Mod: src·dst = dst) / 0.5 grey (Mod2x: 2·0.5·dst = dst),
-    // discarding tint AND the M2Color track — and prev.a is the combined instance alpha, so a
-    // fading Mod batch converges continuously onto "framebuffer unchanged", the same endpoint
-    // as the A<=0 cull (wow-re `m2-mod-fade-source-colour.md`, byte-verified; decision 1489,
-    // re-lawing 0865's identical mechanism from deliberate deviation to byte-faithful; 0528's
-    // "holds full strength and pops" and its non-white-M2Color residual both fall with it).
-    // The lerp factor is `obj_fade` (never the texture alpha) and it commutes with the White/
-    // Grey fog above exactly because the fog target IS the identity colour. At obj_fade 1 the
-    // mix degenerates to the texture colour — the steady look — for any identity value.
-    let is_mod = (u32(m.clutter_fade.z) & 128u) != 0u;
-    let is_mod2x = (u32(m.clutter_fade.z) & 256u) != 0u;
+    // Mod (bit 7) and Mod2x (bit 8) read no source alpha, so the fade rides the colour as in the
+    // reference: texenv preset 5, `mix(prev.rgb, tex.rgb, prev.a)`, with the primary colour forced
+    // to the blend identity (white, or 0.5 grey for Mod2x) and prev.a the instance alpha. The fog
+    // above commutes with this because its white and grey are that identity.
     if (is_mod || is_mod2x) {
         let identity = select(vec3<f32>(1.0), vec3<f32>(0.5), is_mod2x);
         out_rgb = mix(identity, out_rgb, obj_fade);
     }
-    // GAMMA LANE (0161): raw gamma out — blending (alpha AND additive) happens in gamma like
-    // the reference's byte framebuffer; the frame decodes once in the FFXGlow combine. (The old
-    // `lin` A/B emitted linear for the sRGB encode — subsumed by the lane.)
+    // Raw gamma out: blending happens in gamma like the reference's byte framebuffer; the frame
+    // decodes once, in the FFXGlow combine.
     out.color = vec4<f32>(out_rgb, select(faded_alpha, 1.0, opaque_intent));
     return out;
 }
diff --git a/crates/benilla-assets/src/spatial_cache.rs b/crates/benilla-assets/src/spatial_cache.rs
index aced3fd8..80e6daa1 100644
--- a/crates/benilla-assets/src/spatial_cache.rs
+++ b/crates/benilla-assets/src/spatial_cache.rs
@@ -1,60 +1,29 @@
-//! **The spatial dedup cache** — a `HashMap` whose entries remember *where they were last used
-//! from*, so a sweep can drop the art of a place you have left.
-//!
-//! A drop-in for the `HashMap<K, Handle<_>>` these caches used to be: the only difference at a call
-//! site is that a lookup is [`SpatialCache::fetch`] (it counts as a use). `None` in an entry's stamp
-//! means "used since the last sweep" — that inverted spelling is what removes all the plumbing,
-//! because *not* being stamped is the cheap default and stamping happens once per sweep instead of
-//! once per hit.
-//!
-//! It lives here, below the renderer, because it is the cache the asset foundation itself is built
-//! out of (`WorldAssets`' textures and model materials) and because it knows nothing about a world:
-//! [`SpatialCache::scope`] is handed the focus, the radius and the clock as three plain scalars and
-//! never asks anyone for them. Decision 1164. The *instrumentation* around it — which caches exist,
-//! what a census row is, where the focus comes from — stayed up in `art_scope`, which is the half
-//! that reads the camera and the character roster.
+//! The spatial dedup cache: a `HashMap` whose entries remember where they were last used from, so
+//! a sweep can drop the art of a place you have left.
 
 use std::collections::HashMap;
 use std::hash::Hash;
 
-/// The **dwell floor**: nothing is dropped within this many wall seconds of its last use, however far
-/// away you have gone. Distance decides *what* expires; this decides how soon it is allowed to.
-///
-/// Found by the director's first real run, and it is the case the distance rule alone gets wrong. The
-/// detached free-fly camera (`F`, `FlyCam::speed` 40–100 yd/s, ×5 on Ctrl) travels at up to 500 yd/s —
-/// so it crosses the 2667 yd radius in **five seconds**, and a sweep then drops a whole city's dedup
-/// that the same camera re-creates on the way back. Their 48-second leg evicted 25 570 entries and
-/// rebuilt `pmat` 3086 → 15354 doing exactly that: the eviction was *correct* by the radius and
-/// useless in effect, because nothing had finished being wanted.
-///
-/// 30 s covers a 15 000 yd round trip at boosted fly speed. Under gameplay speed it never binds at
-/// all (a gryphon needs ~107 s to cover the radius), so B131's own case is unchanged — this only
-/// stops the thrash at speeds the radius was never sized for. Residency stays bounded either way:
-/// what you hold is at most the art of the last 30 seconds of travel, which does not grow with how
-/// long the process has run.
+/// The dwell floor: nothing is dropped within this many wall seconds of its last use, however far
+/// away. A free-fly camera at 500 yd/s crosses the radius in seconds, and distance alone would
+/// drop art it rebuilds on the way back; at gameplay speed the floor never binds.
 const MIN_DWELL_SECS: f32 = 30.0;
 
-/// Horizontal (tile-plane) distance between two wow-space points. Height is deliberately ignored:
-/// residency is a 2D question — the streamer's window is a tile square, and art 200 yd below a
-/// gryphon is in front of you, not away from you.
+/// Horizontal distance between two WoW-space points; height is ignored, as the streamer's window
+/// is a tile square.
 fn plan_dist(a: [f32; 3], b: [f32; 3]) -> f32 {
     let (dx, dy) = (a[0] - b[0], a[1] - b[1]);
     (dx * dx + dy * dy).sqrt()
 }
 
-/// A dedup cache whose entries remember **where they were last used from**, so a sweep can drop the
-/// art of a place you have left. A drop-in for the `HashMap<K, Handle<_>>` these caches used to be:
-/// the only difference at a call site is that a lookup is [`Self::fetch`] (it counts as a use).
-///
-/// `None` in the stamp means "used since the last sweep" — see the module docs for why that inverted
-/// spelling is what removes all the plumbing.
+/// A dedup cache that a sweep can empty of the art of places left behind. A lookup is
+/// [`Self::fetch`], which counts as a use; a `None` stamp means used since the last sweep, so a
+/// hit costs no stamping.
 pub struct SpatialCache<K, V> {
     map: HashMap<K, (V, Option<Stamp>)>,
 }
 
-/// Where and when an entry was last wanted: the view focus at the first sweep after its last use.
-/// Both halves are load-bearing — `at` decides whether it is far enough to expire, `t` whether it has
-/// been idle long enough to be allowed to ([`MIN_DWELL_SECS`]).
+/// The view focus and the time of the first sweep after an entry's last use.
 #[derive(Clone, Copy)]
 struct Stamp {
     at: [f32; 3],
@@ -70,25 +39,23 @@ impl<K, V> Default for SpatialCache<K, V> {
 }
 
 impl<K: Eq + Hash, V> SpatialCache<K, V> {
-    /// Live entry count — what the census reports and the map-change evictors log.
+    /// Live entry count.
     pub fn len(&self) -> usize {
         self.map.len()
     }
 
-    /// Whether the cache holds nothing. Here because a `pub len` without it is a lint, and because
-    /// "did the map-change teardown actually empty this?" is a real question at a call site.
+    /// Whether the cache holds nothing.
     pub fn is_empty(&self) -> bool {
         self.map.is_empty()
     }
 
-    /// Drop everything (the map-scope teardown, decision 0729 — still the hard reset).
+    /// Drop everything: the map-change teardown.
     pub fn clear(&mut self) {
         self.map.clear();
     }
 
-    /// Fetch a deduped value, **counting the hit as a use** so it restarts its distance grace.
-    /// Clones out rather than lending a reference: every caller wants an owned `Handle` anyway, and
-    /// ending the borrow at the call is what lets the miss path insert in the same expression.
+    /// Fetch a value, counting the hit as a use. It clones out so the miss path can insert in the
+    /// same expression.
     pub fn fetch(&mut self, key: &K) -> Option<V>
     where
         V: Clone,
@@ -103,22 +70,15 @@ impl<K: Eq + Hash, V> SpatialCache<K, V> {
         self.map.insert(key, (value, None));
     }
 
-    /// Get-or-build in place, counted as a use — for the caches whose value is too big to clone out
-    /// ([`crate::clutter::ClutterGeometry`]'s decoded submeshes).
+    /// Get or build in place, counted as a use, for a value too big to clone out.
     pub fn or_insert_with(&mut self, key: K, build: impl FnOnce() -> V) -> &mut V {
         let slot = self.map.entry(key).or_insert_with(|| (build(), None));
         slot.1 = None;
         &mut slot.0
     }
 
-    /// Stamp everything used since the last sweep at `focus`/`now`, then drop every entry that is
-    /// **both** more than `radius` yards away **and** idle for at least [`MIN_DWELL_SECS`]. Returns
-    /// how many were dropped.
-    ///
-    /// The two conditions are not redundant. Distance alone expires art the moment a fast camera
-    /// pulls away from it, which is how the director's free-fly leg lost a city's dedup and rebuilt
-    /// it seconds later; the dwell floor is what makes "not immediate" true at any speed, not just at
-    /// gameplay speed.
+    /// Stamp everything used since the last sweep at `focus` and `now`, then drop every entry both
+    /// more than `radius` yd away and idle for [`MIN_DWELL_SECS`]; returns how many were dropped.
     pub fn scope(&mut self, focus: [f32; 3], radius: f32, now: f32) -> usize {
         let before = self.map.len();
         self.map.retain(|_, (_, stamp)| match *stamp {
@@ -139,23 +99,18 @@ mod tests {
 
     /// When the art is used and stamped.
     const NOW: f32 = 1000.0;
-    /// A sweep past the dwell floor — the earliest moment distance is *allowed* to expire anything.
-    /// Every "…is dropped" assertion sweeps here, which is itself the dwell floor's regression test:
-    /// swap this back to `NOW` and three of them fail (verified).
+    /// A sweep just past the dwell floor, the earliest that distance can expire anything.
     const LATER: f32 = NOW + MIN_DWELL_SECS + 1.0;
     const HOME: [f32; 3] = [0.0, 0.0, 0.0];
     const FAR: [f32; 3] = [4000.0, 0.0, 0.0];
-    /// Five ADT tiles — `art_scope`'s default eviction radius at the time these were written. Any
-    /// radius exercises the same code; the number is here only so the distances read naturally.
+    /// Five ADT tiles; any radius exercises the same code.
     const R: f32 = 2667.0;
 
-    /// A fresh entry survives its first sweep — that is the sweep that *stamps* it. Without this the
-    /// grace period would depend on where in the second the art happened to load.
     #[test]
     fn the_first_sweep_stamps_rather_than_judges() {
         let mut c: SpatialCache<u32, u32> = SpatialCache::default();
         c.insert(1, 10);
-        // Swept from the far side immediately: the entry has no stamp yet, so it cannot be too far.
+        // No stamp yet, so it cannot be too far.
         assert_eq!(c.scope(FAR, R, NOW), 0);
         assert_eq!(c.len(), 1);
         // Now it is stamped at FAR, so a later sweep from HOME drops it.
@@ -176,8 +131,6 @@ mod tests {
         assert_eq!(c.scope(FAR, R, LATER), 1, "beyond it");
     }
 
-    /// A hit restarts the grace, which is what keeps art in the direction of travel resident: the
-    /// same tree material is re-fetched by every new placement that streams in ahead of you.
     #[test]
     fn a_use_restarts_the_grace() {
         let mut c: SpatialCache<u32, u32> = SpatialCache::default();
@@ -195,7 +148,6 @@ mod tests {
         }
     }
 
-    /// `or_insert_with` builds once and counts as a use, like `fetch`.
     #[test]
     fn or_insert_with_builds_once_and_counts_as_a_use() {
         let mut c: SpatialCache<u32, Vec<u32>> = SpatialCache::default();
@@ -215,9 +167,6 @@ mod tests {
         );
     }
 
-    /// **The director's free-fly case.** A camera at boosted fly speed crosses the radius in ~5 s; if
-    /// distance alone decided, the art it just streamed would be dropped and then rebuilt as the same
-    /// camera came back. Nothing expires inside the dwell floor however far away the focus goes.
     #[test]
     fn a_fast_camera_cannot_outrun_the_dwell_floor() {
         let mut c: SpatialCache<u32, u32> = SpatialCache::default();
@@ -232,15 +181,14 @@ mod tests {
                 "dropped {s} s out — the free-fly thrash"
             );
         }
-        // Fly all the way back inside the radius and the entry is still the same one: no rebuild.
+        // Back inside the radius, the same entry: no rebuild.
         assert_eq!(c.scope(HOME, R, NOW + 6.0), 0);
         assert_eq!(c.fetch(&1), Some(10));
-        // Stay away past the floor and it does expire — the bound is delayed, not removed.
+        // Away past the floor, it does expire.
         c.scope(HOME, R, NOW + 7.0);
         assert_eq!(c.scope(FAR, R, NOW + 7.0 + MIN_DWELL_SECS), 1);
     }
 
-    /// Height is not distance: flying over a city must not evict it.
     #[test]
     fn altitude_is_not_distance() {
         let mut c: SpatialCache<u32, u32> = SpatialCache::default();
@@ -249,11 +197,7 @@ mod tests {
         assert_eq!(c.scope([0.0, 0.0, 10_000.0], R, LATER), 0);
     }
 
-    /// **The mechanism the whole design rests on**: dropping the cache's handle really does free the
-    /// asset. If `Assets<T>` kept the value alive past its last strong handle, eviction would cost us
-    /// the dedup and recover no memory — a failure indistinguishable, from the outside, from "the fix
-    /// did nothing". Checked here rather than assumed, because the *reason* B131's `images` column
-    /// never fell is precisely that these caches held the last handle.
+    /// Eviction frees memory only if dropping the last handle frees the asset.
     #[test]
     fn dropping_the_last_handle_frees_the_asset() {
         let mut app = App::new();
@@ -287,8 +231,6 @@ mod tests {
         );
     }
 
-    /// A cache nobody sweeps (the `Local<MaterialCache>`s in the glue booth / portrait bake) expires
-    /// nothing: without a `scope` call the stamps stay `None` forever.
     #[test]
     fn an_unswept_cache_never_expires() {
         let mut c: SpatialCache<u32, u32> = SpatialCache::default();
diff --git a/crates/benilla-assets/src/terrain.rs b/crates/benilla-assets/src/terrain.rs
index 984efb9b..b214132b 100644
--- a/crates/benilla-assets/src/terrain.rs
+++ b/crates/benilla-assets/src/terrain.rs
@@ -1,29 +1,8 @@
-//! Terrain-tile texture-array packing for the ADT loader.
-//!
-//! A tile's ground textures are stacked into one repeating, mipmapped `texture_2d_array`; its
-//! per-chunk alpha (blend-weight) and MCSH shadow maps into two more arrays. The fidelity-critical
-//! rule (the "C2" invariant, anchored in `wow-5875-re/system/terrain`): the BLP's **authored** mip
-//! pyramid is laid in **verbatim** — never CPU-regenerated by averaging texels in gamma byte space,
-//! which darkens mid-tones and cools foliage. Off-Elwynn BLPs authored below [`LAYER_TEX_SIZE`] fill
-//! the top mips by `NEAREST` upsample (texel replication — gamma-safe, no averaging).
-//!
-//! # The array's format is a property of the TILE, not of any one texture
-//!
-//! `Tileset\` is ~98 % S3TC, and 1626 handed the blocks straight to the GPU for model and WMO
-//! albedo — but not here, because this lane resamples and stomps texels on the CPU. [`pack_layers`]
-//! is what unblocks it: it holds every layer in its **authored** form until the whole tile has been
-//! read, then asks one question of the set — *can all of these go up as blocks, together?* One
-//! `texture_2d_array` has exactly one format and one mip-0 size, so the answer is all-or-nothing per
-//! tile, and the fallback is the decode this lane always did.
-//!
-//! **The rule earns its narrowness from the install** (censused across all 2 275 textured ADTs):
-//! a tile passes when every chosen layer shares one block form, is natively [`LAYER_TEX_SIZE`]² with
-//! a full [`LAYER_MIP_COUNT`]-level chain, and needs no matte stomp. That is **87 % of Azeroth's
-//! tiles and 92 % of Kalimdor's**, worth 2.5x / 2.9x off their layer bytes. The two obvious
-//! extensions were measured and are deliberately **not** built: doing the matte stomp in block space
-//! (legal on Bc2/Bc3 — zero the alpha half) buys **0** further tiles, and a block-space power-of-two
-//! NEAREST upsample buys **8**. What is left out is left out because it is worth nothing, not
-//! because it is hard.
+//! Terrain tile texture arrays: the ground layers in one repeating, mipmapped `texture_2d_array`,
+//! the per-chunk alpha and MCSH shadow maps in two more. As in the reference, each BLP's authored
+//! mips go in verbatim, never regenerated by averaging gamma bytes, which darkens mid-tones; a BLP
+//! below [`LAYER_TEX_SIZE`] fills the top mips by NEAREST upsample. One array has one format and
+//! one mip-0 size, so a tile uploads its layers as S3TC blocks only when all of them can.
 
 use benilla_formats::{BlpMipChain, BlpTexels};
 use bevy::asset::RenderAssetUsages;
@@ -34,22 +13,19 @@ use bevy::render::render_resource::{
     TextureViewDimension,
 };
 
-/// Edge length every layer BLP is uploaded at for the per-tile array (uniform so they share one
-/// `texture_2d_array`). The Elwynn A/B target's layer BLPs are all natively 256² with 8 authored mips.
+/// Every layer's edge in the tile array; Elwynn's ground BLPs are natively 256² with 8 mips.
 pub(crate) const LAYER_TEX_SIZE: u32 = 256;
 
-/// Per-layer mip count for the array — the authored count at 256². Fewer-mip BLPs repeat the last
-/// authored level; sub-256² BLPs upsample (NEAREST) to fill the top.
+/// Per-layer mip count, the authored count at 256².
 pub(crate) const LAYER_MIP_COUNT: u32 = 8;
 
-/// Albedo format: non-sRGB `Rgba8Unorm` — the GPU does not linearize on sample, so shader math stays
-/// in WoW's gamma/byte space (the RE'd invariant; matches the model/BLP albedo format).
+/// Non-sRGB, so sampling does not linearize and shader math stays in gamma byte space, as in the
+/// reference.
 fn color_format() -> TextureFormat {
     TextureFormat::Rgba8Unorm
 }
 
-/// The block form's albedo format — the same **non-sRGB** gamma-byte lane [`color_format`] is in
-/// (0161). `Bc*RgbaUnormSrgb` would linearize on sample and is the one wrong answer here.
+/// The block form's albedo format, non-sRGB like [`color_format`]; an `Srgb` one would linearize.
 fn block_color_format(texels: BlpTexels) -> TextureFormat {
     match texels {
         BlpTexels::Bc1 => TextureFormat::Bc1RgbaUnorm,
@@ -59,24 +35,17 @@ fn block_color_format(texels: BlpTexels) -> TextureFormat {
     }
 }
 
-/// One ground texture packed for the per-tile array: its authored mip chain at [`LAYER_TEX_SIZE`]²,
-/// concatenated mip-major (level 0 first), `mip_count` levels.
+/// One ground texture's mip chain at [`LAYER_TEX_SIZE`]², level 0 first.
 pub(crate) struct LayerTexture {
     pub(crate) chain: Vec<u8>,
     pub(crate) mip_count: u32,
 }
 
-/// Pack a BLP's authored mip pyramid into a [`LayerTexture`] for the tile array — authored levels
-/// used verbatim (the C2 fix). When the BLP's mip 0 is smaller than `target_size` (off-Elwynn) the
-/// top of the chain is NEAREST-upsampled (texel replication, gamma-safe), with the BLP's authored
-/// smaller mips slotting into the deeper array levels; when its chain runs out the last authored mip
-/// is reused (NEAREST-resampled if the dims still differ).
+/// Pack a BLP's authored levels verbatim; a mip 0 below `target_size` is NEAREST-upsampled into the
+/// top levels, and a chain that runs out repeats its last level.
 pub(crate) fn chain_to_layer(blp: BlpMipChain, target_size: u32) -> LayerTexture {
-    // **This function cannot take DXT blocks.** It NEAREST-resamples levels to a uniform array size,
-    // and [`pack_layers`] stomps the alpha byte after it for the matte case — both are per-texel CPU
-    // writes, which is exactly what a block form does not have. That is why the passthrough is a
-    // decision taken *before* this point, in [`pack_layers`], rather than a flag threaded through
-    // here: a chain that reaches this function has already been ruled out of it (1646).
+    // Decoded chains only: the resample and the matte stomp are per-texel writes, so the block
+    // passthrough is decided before this, in `pack_layers`.
     debug_assert!(
         blp.is_rgba8(),
         "terrain layer packing indexes texels; it needs a decoded chain"
@@ -86,14 +55,13 @@ pub(crate) fn chain_to_layer(blp: BlpMipChain, target_size: u32) -> LayerTexture
         let level_w = (target_size >> level).max(1);
         let level_h = level_w; // tilesets are square in 1.12
         if blp.width >= level_w {
-            // `BLP width >> j == level_w`  ⟹  `j = log2(BLP width / level_w)`, clamped to the BLP's
-            // available mips (if it doesn't go that deep, repeat the last authored level).
+            // Source level `log2(width / level_w)`, clamped to the last authored level.
             let ratio = (blp.width / level_w).max(1);
             let src_level = (ratio.trailing_zeros() as usize).min(blp.mips.len() - 1);
             let (sw, sh) = blp.mip_size(src_level as u32);
             extend_nearest(&mut chain, &blp.mips[src_level], sw, sh, level_w, level_h);
         } else {
-            // Authored smaller than this level — NEAREST-upsample mip 0 (texel replication).
+            // Authored smaller than this level: NEAREST-upsample mip 0.
             extend_nearest(
                 &mut chain,
                 &blp.mips[0],
@@ -110,46 +78,25 @@ pub(crate) fn chain_to_layer(blp: BlpMipChain, target_size: u32) -> LayerTexture
     }
 }
 
-/// One of a tile's ground textures as it was read, **before** the tile has decided what form its
-/// layer array takes — held in its authored form (DXT blocks kept) because that decision belongs to
-/// the whole set, not to any one texture. See [`pack_layers`].
+/// One ground texture as read, blocks intact, until the whole tile picks its array's form.
 pub(crate) struct RawLayer {
-    /// The BLP's authored chain, blocks intact ([`benilla_formats::blp_bytes_to_native_chain`]).
     pub(crate) chain: BlpMipChain,
-    /// No `_s` specular variant existed for this layer, so its sheen mask must read 0 (matte). On
-    /// the decoded path that is an alpha stomp; on the block path it is why the tile is not eligible.
+    /// No `_s` specular variant exists, so the sheen mask must read 0.
     pub(crate) matte: bool,
 }
 
-/// A tile's layer array, packed: LayerMajor bytes plus the format and level count that describe them.
+/// A tile's layer array: LayerMajor bytes, their format and level count.
 pub(crate) struct PackedLayers {
     pub(crate) data: Vec<u8>,
     pub(crate) format: TextureFormat,
     pub(crate) mip_count: u32,
 }
 
-/// The block form this whole tile's layer array can be uploaded in, or `None` if it must be decoded.
-///
-/// Every clause is a property one `texture_2d_array` cannot vary across its layers, plus the two
-/// CPU texel writes this lane used to do unconditionally:
-///
-/// - **one block form** — an array has one `TextureFormat`, and `Bc1`/`Bc2` are different widths;
-/// - **natively [`LAYER_TEX_SIZE`]²** — an array has one mip-0 size, and NEAREST-resampling a level
-///   to reach it is a per-texel write blocks do not support;
-/// - **a full [`LAYER_MIP_COUNT`]-level chain, every level exactly the size its form implies** — the
-///   levels are laid in verbatim, so a short chain would have to repeat one at the wrong size (the
-///   same resample again), and a level whose byte count disagreed with the format would corrupt
-///   every layer after it rather than fail. `decode_native` pads to whole blocks, so this always
-///   holds — it is checked in **release** anyway, because the one bug 1626 shipped was bytes
-///   uploaded under a format that implied a different count, and a `debug_assert` cannot catch that
-///   in a player's build;
-/// - **no matte layer** — zeroing the sheen mask is a per-texel alpha write. (It *is* expressible in
-///   Bc2/Bc3 block space — memset the alpha half — and that was measured to buy **zero** further
-///   tiles, because a layer with no `_s` variant is a `Bc1` base and its tile is mixed-format anyway.)
-///
-/// [`crate::gpu_blp::bc_supported`] gates the whole thing, so `WOW_NO_BC=1` and a device without BC
-/// both land on the decoded path exactly as before — and so does every headless test, which is what
-/// keeps the pixel-reading ones honest.
+/// The block form the whole tile's layer array can upload in, or `None` to decode. Every layer
+/// needs the same block form, natively [`LAYER_TEX_SIZE`]², a full [`LAYER_MIP_COUNT`] chain of
+/// exactly the sizes the form implies (checked in release: a wrong byte count corrupts every later
+/// layer instead of failing), and no matte stomp. [`crate::gpu_blp::bc_supported`] gates it all,
+/// so `WOW_NO_BC=1`, a device without BC and every headless test take the decoded path.
 fn passthrough_form(layers: &[RawLayer], bc_supported: bool) -> Option<BlpTexels> {
     if !bc_supported {
         return None;
@@ -170,18 +117,14 @@ fn passthrough_form(layers: &[RawLayer], bc_supported: bool) -> Option<BlpTexels
     uniform.then_some(form)
 }
 
-/// Pack a tile's ground textures into its layer array — blocks straight through when the whole set
-/// allows it ([`passthrough_form`]), else the decode-resample-stomp path this lane always took.
-///
-/// `fallback` is layer 0's solid colour: the "this texture would not load" placeholder every tile
-/// carries at index 0, which is why it has to be synthesised in whichever form the tile picked.
+/// Pack a tile's ground textures into its layer array, as blocks when [`passthrough_form`] allows.
+/// `fallback` is layer 0, the solid placeholder for a texture that fails to load, synthesised in
+/// the form the tile picked.
 pub(crate) fn pack_layers(fallback: [u8; 4], layers: Vec<RawLayer>) -> PackedLayers {
     pack(fallback, layers, crate::gpu_blp::bc_supported())
 }
 
-/// [`pack_layers`] with the device fact passed in rather than read from the process — so the block
-/// path is exercisable in a headless test, where [`crate::gpu_blp::bc_supported`] is always false
-/// and would otherwise leave the whole passthrough untested.
+/// [`pack_layers`] with device support passed in, so a headless test can reach the block path.
 fn pack(fallback: [u8; 4], layers: Vec<RawLayer>, bc_supported: bool) -> PackedLayers {
     if let Some(form) = passthrough_form(&layers, bc_supported) {
         let per_layer: usize = (0..LAYER_MIP_COUNT)
@@ -190,8 +133,6 @@ fn pack(fallback: [u8; 4], layers: Vec<RawLayer>, bc_supported: bool) -> PackedL
         let mut data = Vec::with_capacity((layers.len() + 1) * per_layer);
         data.extend_from_slice(&solid_block_chain(form, fallback));
         for layer in &layers {
-            // A straight copy: `passthrough_form` has already established that each of these levels
-            // is exactly what `format` implies, so the upload's own slicing cannot disagree.
             for level in layer.chain.mips.iter().take(LAYER_MIP_COUNT as usize) {
                 data.extend_from_slice(level);
             }
@@ -209,8 +150,6 @@ fn pack(fallback: [u8; 4], layers: Vec<RawLayer>, bc_supported: bool) -> PackedL
     let mut data = fb.chain;
     for layer in layers {
         let matte = layer.matte;
-        // `into_rgba8` is free for a chain that was never blocks and is the decode we were trying to
-        // avoid for one that was — but it cannot fail, so this path is always available.
         let mut packed = chain_to_layer(layer.chain.into_rgba8(), LAYER_TEX_SIZE);
         if matte {
             packed
@@ -229,23 +168,15 @@ fn pack(fallback: [u8; 4], layers: Vec<RawLayer>, bc_supported: bool) -> PackedL
     }
 }
 
-/// Bytes one array level occupies per layer in `form` — the arithmetic the eligibility check, the
-/// packer and the fallback synthesiser all have to agree on, stated once.
+/// Bytes of one layer's array level in `form`, shared by the check, the packer and the fallback.
 fn form_level_bytes(form: BlpTexels, level: u32) -> usize {
     let w = (LAYER_TEX_SIZE >> level).max(1);
     form.level_bytes(w, w)
 }
 
-/// One solid-colour 4x4 block in `form`.
-///
-/// The colour half is a DXT1 colour block with `c0` = the colour, `c1` = 0 and every 2-bit index 0,
-/// so all 16 texels read `c0` — quantised to RGB565, which is what a solid colour costs in any block
-/// form. `Bc2`/`Bc3` carry the alpha exactly (explicit 4-bit / a constant 8-bit endpoint pair).
-///
-/// **`Bc1` cannot carry alpha at all**, so a `Bc1` tile's placeholder samples as opaque and would
-/// take the sun sheen the `Rgba8Unorm` placeholder (alpha 0) suppresses. That is accepted, not
-/// overlooked: layer 0 is only ever sampled when a BLP named by MTEX fails to read, which no healthy
-/// install does — the census resolved all 1 048 `Tileset\` names — and it is a placeholder either way.
+/// One solid 4x4 block in `form`: a DXT1 colour half with `c0` the RGB565 colour, `c1` 0 and every
+/// index 0, after `Bc2`/`Bc3`'s alpha. `Bc1` has no alpha, so its placeholder samples opaque and
+/// takes the sheen; layer 0 is only sampled when an MTEX texture fails to read.
 fn solid_block(form: BlpTexels, rgba: [u8; 4]) -> Vec<u8> {
     let c = ((rgba[0] as u16 >> 3) << 11) | ((rgba[1] as u16 >> 2) << 5) | (rgba[2] as u16 >> 3);
     let color = [c as u8, (c >> 8) as u8, 0, 0, 0, 0, 0, 0];
@@ -260,14 +191,12 @@ fn solid_block(form: BlpTexels, rgba: [u8; 4]) -> Vec<u8> {
     block
 }
 
-/// A solid-colour block chain at [`LAYER_TEX_SIZE`]² with [`LAYER_MIP_COUNT`] levels — the block-form
-/// twin of [`solid_layer_chain`], for layer 0 of a passthrough array.
+/// The block form of [`solid_layer_chain`], for layer 0 of a passthrough array.
 fn solid_block_chain(form: BlpTexels, rgba: [u8; 4]) -> Vec<u8> {
     let block = solid_block(form, rgba);
     let mut out = Vec::new();
     for level in 0..LAYER_MIP_COUNT {
-        // Levels below 4x4 still occupy one whole block — `form_level_bytes` rounds up, which is
-        // exactly what the authored chains next to this one do at their 2x2 tail.
+        // A level below 4x4 still takes one whole block, as the authored chains do.
         for _ in 0..(form_level_bytes(form, level) / block.len()) {
             out.extend_from_slice(&block);
         }
@@ -275,8 +204,7 @@ fn solid_block_chain(form: BlpTexels, rgba: [u8; 4]) -> Vec<u8> {
     out
 }
 
-/// A solid-colour layer chain at [`LAYER_TEX_SIZE`]² with [`LAYER_MIP_COUNT`] levels — the per-tile
-/// array's fallback layer 0 (a solid colour downsamples to itself, so every mip is the same colour).
+/// The decoded fallback layer 0: one colour at every level.
 pub(crate) fn solid_layer_chain(rgba: [u8; 4]) -> LayerTexture {
     let mut chain = Vec::with_capacity(mip_chain_byte_size(LAYER_TEX_SIZE, LAYER_MIP_COUNT));
     for level in 0..LAYER_MIP_COUNT {
@@ -301,9 +229,8 @@ pub(crate) fn mip_chain_byte_size(top: u32, mip_count: u32) -> usize {
         .sum()
 }
 
-/// Append `src` (RGBA8 `sw × sh`) resized to `dw × dh` to `out` using `NEAREST` — pure texel
-/// replication/decimation, so gamma-encoded bytes pass through unchanged (no averaging → no
-/// darkening). Identity at `(sw, sh) == (dw, dh)`.
+/// Append RGBA8 `src` resized from `sw × sh` to `dw × dh` by NEAREST, which never averages gamma
+/// bytes.
 pub(crate) fn extend_nearest(out: &mut Vec<u8>, src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) {
     if sw == dw && sh == dh {
         out.extend_from_slice(src);
@@ -317,8 +244,7 @@ pub(crate) fn extend_nearest(out: &mut Vec<u8>, src: &[u8], sw: u32, sh: u32, dw
     out.extend_from_slice(resized.as_raw());
 }
 
-/// Stack the tile's ground textures into a repeating, mipmapped `2d_array`. `rgba` holds each layer's
-/// full `mip_levels`-deep chain (LayerMajor order); `layer_count` layers at `size²` mip 0.
+/// The tile's packed ground layers as a repeating, mipmapped `2d_array`.
 pub(crate) fn layer_array_image(size: u32, layer_count: u32, packed: PackedLayers) -> Image {
     let PackedLayers {
         data,
@@ -329,11 +255,8 @@ pub(crate) fn layer_array_image(size: u32, layer_count: u32, packed: PackedLayer
     image.data = Some(data);
     image.texture_descriptor.mip_level_count = mip_count;
     image.data_order = TextureDataOrder::LayerMajor;
-    // Ground is the surface the filter policy costs the most on — a tiling texture at a grazing
-    // angle is the anisotropy axis's worst case, and it fills most of the frame. The reference
-    // does not let this lane choose: both values come from the process globals
-    // ([`crate::tex_filter`]) — trilinear with anisotropy off, which is what `hwDetect` hands a
-    // virgin install (1645).
+    // As in the reference, ground filtering comes from the process globals (`crate::tex_filter`):
+    // trilinear with anisotropy off on a fresh install (`hwDetect`).
     let filter = crate::tex_filter::tex_filter();
     image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
         address_mode_u: ImageAddressMode::Repeat,
@@ -347,35 +270,24 @@ pub(crate) fn layer_array_image(size: u32, layer_count: u32, packed: PackedLayer
     image
 }
 
-/// Stack `layer_count` per-chunk alpha maps (each `size²`, concatenated) into a linear `2d_array` —
-/// the tile's blend weights (R/G/B = layers 1/2/3 opacity). Non-colour, so `Rgba8Unorm`.
+/// The per-chunk alpha maps as a linear `2d_array`: R, G and B are layers 1, 2 and 3's opacity.
 pub(crate) fn alpha_array_image(size: u32, layer_count: u32, rgba: Vec<u8>) -> Image {
     let mut image = array_image(size, layer_count, TextureFormat::Rgba8Unorm);
     image.data = Some(rgba);
     image
 }
 
-/// Stack `layer_count` MCSH shadow maps (each `size²`, one byte/texel) into a single-channel
-/// `2d_array` — WoW's pre-baked static terrain shadows (`R` = shadowed, 0 = lit).
+/// The MCSH baked shadow maps as a one-byte `2d_array`: `R` is shadowed, 0 lit.
 pub(crate) fn shadow_array_image(size: u32, layer_count: u32, data: Vec<u8>) -> Image {
     let mut image = array_image(size, layer_count, TextureFormat::R8Unorm);
     image.data = Some(data);
     image
 }
 
-/// Build a `2d_array` `Image` from concatenated per-layer bytes, with a `D2Array` view so the
-/// `dimension = "2d_array"` bindings resolve.
-///
-/// `RenderAssetUsages::RENDER_WORLD`: the render world takes the bytes on extract — a tile's
-/// three arrays are megabytes each, and nothing reads them main-side (they flow into the terrain
-/// material as handles; the minimap, collider, clutter all derive from other sources). The
-/// default usage cloned every array on landing AND kept a main-world copy resident per tile —
-/// pure cost on both the B181 landing frame and the resident-set memory.
+/// A `2d_array` image with a `D2Array` view. `RENDER_WORLD` only: nothing reads a tile's arrays
+/// main-side, so no main-world copy stays resident.
 fn array_image(size: u32, layer_count: u32, format: TextureFormat) -> Image {
-    // `new_uninit`, not `new`: `Image::new`'s length assert is written for uncompressed formats
-    // (it skips itself when `pixel_size()` errors, which is every BC format) and it would force a
-    // mip-0-sized dummy allocation on every tile just to be thrown away. The caller sets `data`.
-    // Same reasoning, same call, as the model lane's `world_art_image` (`blp.rs`).
+    // `new_uninit`, not `new`, which would allocate a mip-0 dummy per tile; the caller sets `data`.
     let mut image = Image::new_uninit(
         Extent3d {
             width: size,
@@ -425,8 +337,7 @@ mod tests {
 
     #[test]
     fn chain_to_layer_upsamples_a_small_blp_without_darkening() {
-        // A 64² BLP packed to 256²: the top levels are NEAREST-upsampled. A solid 200 in must come
-        // out solid 200 — averaging (the C2 bug) would dim it below 200.
+        // Averaging would dim a solid 200 below 200.
         let layer = chain_to_layer(synthetic_chain(64, 7), 256);
         assert_eq!(layer.chain.len(), mip_chain_byte_size(256, LAYER_MIP_COUNT));
         assert!(
@@ -467,8 +378,7 @@ mod tests {
         assert_eq!(img.texture_descriptor.mip_level_count, LAYER_MIP_COUNT);
     }
 
-    /// A synthetic block chain: `mips` authored levels at `size²` in `form`, padded to whole blocks
-    /// exactly as `benilla_blp::decode_native` delivers them.
+    /// Zeroed levels in `form`, padded to whole blocks as `benilla_blp::decode_native` delivers.
     fn block_chain(form: BlpTexels, size: u32, mips: u32) -> BlpMipChain {
         let levels = (0..mips)
             .map(|i| {
@@ -491,8 +401,6 @@ mod tests {
         }
     }
 
-    /// The whole eligibility rule, clause by clause — each `None` here is a tile that keeps paying
-    /// 4 bytes a texel, so each one is worth stating.
     #[test]
     fn a_tile_passes_its_blocks_through_only_when_every_clause_holds() {
         let ok = || {
@@ -503,22 +411,21 @@ mod tests {
         };
         assert_eq!(passthrough_form(&ok(), true), Some(BlpTexels::Bc2));
 
-        // No device support (every headless test, and `WOW_NO_BC=1`).
+        // No device support.
         assert_eq!(passthrough_form(&ok(), false), None);
-        // Mixed block forms — one array, one format. This is the common mixed tile: a `_s` variant
-        // is DXT3 while a base without one is DXT1 (413 of 416 pairs in the install).
+        // Mixed block forms, the common case: a `_s` variant is DXT3, a base without one DXT1.
         let mixed = vec![
             raw(BlpTexels::Bc1, 256, 8, false),
             raw(BlpTexels::Bc2, 256, 8, false),
         ];
         assert_eq!(passthrough_form(&mixed, true), None);
-        // Not natively 256² — reaching the array size is a NEAREST resample, a per-texel write.
+        // Not natively 256².
         let small = vec![raw(BlpTexels::Bc2, 128, 7, false)];
         assert_eq!(passthrough_form(&small, true), None);
-        // A short chain would have to repeat a level at the wrong size — the same resample.
+        // A short chain.
         let short = vec![raw(BlpTexels::Bc2, 256, 5, false)];
         assert_eq!(passthrough_form(&short, true), None);
-        // A matte layer needs its alpha stomped to 0, which is a per-texel write.
+        // A matte layer.
         let matte = vec![raw(BlpTexels::Bc2, 256, 8, true)];
         assert_eq!(passthrough_form(&matte, true), None);
         // Raw1/Raw3 tilesets have no block form at all.
@@ -527,20 +434,15 @@ mod tests {
             matte: false,
         }];
         assert_eq!(passthrough_form(&raw1, true), None);
-        // A tile with no layers at all is the fallback-only tile — nothing to pass through.
+        // The fallback-only tile.
         assert_eq!(passthrough_form(&[], true), None);
     }
 
-    /// The bug 1626 shipped for twenty minutes was blocks uploaded under a format that implied a
-    /// different byte count. This asserts the pairing directly, for every block form: the packed
-    /// buffer must be exactly what `format` says a `LAYER_TEX_SIZE²` × `mip_count` × `layers` array
-    /// holds — nothing else can be sliced out of it correctly.
     #[test]
     fn a_packed_block_array_is_exactly_the_size_its_format_implies() {
         for form in [BlpTexels::Bc1, BlpTexels::Bc2, BlpTexels::Bc3] {
             let layers = vec![raw(form, 256, 8, false), raw(form, 256, 8, false)];
-            // A level that lies about its size must not reach the packer: it would corrupt every
-            // layer after it in the array rather than fail (1626's own twenty-minute bug).
+            // A level of the wrong size must not reach the packer.
             let mut short = raw(form, 256, 8, false);
             short.chain.mips[3].truncate(4);
             assert_eq!(passthrough_form(&[short], true), None, "{form:?}");
@@ -552,9 +454,8 @@ mod tests {
                 .sum();
             // 3 layers: the synthesised fallback at index 0, then the two real ones.
             assert_eq!(packed.data.len(), 3 * per_layer, "{form:?}");
-            // And the point of the whole change, pinned: DXT1 is 0.5 bytes a texel and DXT3/DXT5
-            // are 1, against `Rgba8Unorm`'s 4. (The sub-4x4 tail mips cost a whole block in either
-            // form, which is the entire 0.01 the ratio falls short of the texel arithmetic.)
+            // DXT1 is 0.5 bytes a texel, DXT3 and DXT5 are 1, decoded is 4; the sub-4x4 tail
+            // levels take a whole block, the 0.01 the ratio falls short.
             let decoded = 3 * mip_chain_byte_size(LAYER_TEX_SIZE, LAYER_MIP_COUNT);
             let ratio = decoded as f64 / packed.data.len() as f64;
             let want = if form == BlpTexels::Bc1 { 8.0 } else { 4.0 };
@@ -565,8 +466,6 @@ mod tests {
         }
     }
 
-    /// Layer 0 is synthesised, not read, so it is the one part of a passthrough array whose bytes we
-    /// author ourselves — decode them back and check they are the colour we asked for.
     #[test]
     fn the_synthesised_fallback_block_decodes_to_its_colour() {
         let rgba = [107u8, 133, 82, 0];
@@ -585,8 +484,7 @@ mod tests {
             .into_rgba8()
             .mips
             .remove(0);
-            // RGB565 is what a solid colour costs in any block form; assert within one quantisation
-            // step per channel rather than pretending the round trip is exact.
+            // Within one RGB565 step per channel.
             for px in top.as_chunks::<4>().0 {
                 for (got, want) in px[..3].iter().zip(&rgba[..3]) {
                     assert!(
@@ -595,8 +493,7 @@ mod tests {
                     );
                 }
             }
-            // Alpha is the sheen mask: `Bc2`/`Bc3` carry the requested 0; `Bc1` has no alpha channel
-            // and samples opaque, which is the documented limitation of the placeholder.
+            // `Bc1` has no alpha and samples opaque.
             let alpha_ok = match form {
                 BlpTexels::Bc1 => true,
                 _ => top.as_chunks::<4>().0.iter().all(|px| px[3] == rgba[3]),
@@ -605,8 +502,6 @@ mod tests {
         }
     }
 
-    /// The decoded path must still be byte-for-byte what this lane always produced — including the
-    /// matte stomp, which moved out of the ADT loader and into `pack`.
     #[test]
     fn the_decoded_path_still_stomps_a_matte_layers_alpha() {
         let layers = vec![
diff --git a/crates/benilla-assets/src/tex_filter.rs b/crates/benilla-assets/src/tex_filter.rs
index 5086e01d..1f55e8fa 100644
--- a/crates/benilla-assets/src/tex_filter.rs
+++ b/crates/benilla-assets/src/tex_filter.rs
@@ -1,90 +1,27 @@
-//! The frame's **texture filter policy** — one process-global pair, exactly as the reference holds
-//! it, and the divergence that pair was hiding.
+//! The process texture-filter policy: `trilinear` and `anisotropic` resolved into one filter mode,
+//! as the reference holds it in two globals.
 //!
-//! ## What the reference actually does
+//! `TextureCreate` (`0x449d90`) hands `0x449ae0` an `applyGlobal` flag; when it is 1, the filter
+//! bits 0-2 are overwritten from `[0x835250]` (static 3) and the aniso bits 9-13 from
+//! `(mode == 5 ? [0x835254] : 1)`, globals set only from the CVar callbacks (`0x449ac0`,
+//! `0x449ad0`). Terrain (`0x6c4c77`), WMO (the same wrapper `0x6c4c20`), M2 (`0x71da72`) and the
+//! liquid sheets (`0x68abab`) pass 1. Six subsystems pass 0 and keep their own mode: weather
+//! sprites (a hard-coded mode 4), the minimap, glue and loading screens, Lua texture widgets, the
+//! sky and footprint decals (`0x699bd0`).
 //!
-//! The real 1.12.1 client does not let a texture choose how it is filtered. Every
-//! `TextureCreate` (`0x449d90`) runs the caller's request through **`0x449ae0`** with a force flag
-//! that is a literal `1` at every observed call site, and `0x449ae0` **overwrites** it from two
-//! globals: filter bits 0-2 from `[0x835250]`, aniso bits 9-13 from
-//! `(mode == 5 ? [0x835254] : 1)`. Their static `.data` values are **`[0x835250] = 3`** and
-//! **`[0x835254] = 1`**, and a full image-wide caller census of their only two writers
-//! (`0x449ac0` / `0x449ad0`) finds exactly three call sites, all inside the CVar callbacks below.
-//! WMO, M2/character and terrain textures all share the one policy; there is no per-draw filter
-//! override anywhere. (wow-re `system/models/scratch/wmo-texture-sampling.md` §2, VERIFIED off
-//! `0x449ae0`/`0x59f170`/`0x58a980`/`0x6c4c20` + the registration block `0x6885b0`-`0x688840`.)
+//! Mode 3 is `GL_LINEAR_MIPMAP_NEAREST`, 4 `GL_LINEAR_MIPMAP_LINEAR`, 5 trilinear with anisotropy
+//! N (applied at `0x59f170`). `trilinear` (`0x688608`, registered `"0"`) sets 4; `anisotropic`
+//! (`0x6887d0`, registered `"1"`) above 1 sets 5 and outranks it.
 //!
-//! Mode 3 — the static `.data` value — is `GL_LINEAR_MIPMAP_NEAREST` / `GL_LINEAR`: bilinear with
-//! nearest-mip select, anisotropy off. Two CVars move it, and only upward:
+//! A fresh install renders at mode 4: `hwDetect` (`0x641260`, `0x639a60`) sets sixteen video CVars
+//! from `VideoHardware.dbc`, and any current GPU takes the fallback scan (`0x641610`, its tier from
+//! `0x58bc90`), whose rows 169 and 170 set `trilinear` 1 at both CPU tiers. `anisotropic` is not
+//! one of the sixteen (`0xc7f2e4` is absent from `[0x639a60, 0x639b80)`), so anisotropy stays off.
 //!
-//! - **`trilinear`** (reg `0x688608`, registered default `"0"`) — nonzero sets mode 4,
-//!   `GL_LINEAR_MIPMAP_LINEAR`.
-//! - **`anisotropic`** (reg `0x6887d0`, registered default **`"1"`**) — a value >1 sets mode 5
-//!   (trilinear *plus* real aniso N, clamped to the device cap) and **outranks** `trilinear`.
-//!
-//! ## …and why the registrar's string is not what the client renders at
-//!
-//! **`hwDetect` overwrites it before the first frame.** `hwDetect` registers `"1"`, and
-//! `DetectHardware 0x641260` → `0x639a60` then `CVar::Set`s **sixteen** video CVars from the
-//! matched `VideoHardware.dbc` row, self-clears to `"0"`, and persists — so the registrar's string
-//! is only ever what an install renders at if the hardware table has nothing to say.
-//!
-//! It always has something to say. Every GPU this client runs on now is unlisted in a 2004 table,
-//! so the row comes from the **fallback** scan (`0x641610`, from record index 1, vendor `0xFFFF`
-//! against a D3D9 capability tier from `CGxDevice::DeviceAdapterInfer 0x58bc90`), whose reachable
-//! set is exactly three rows: **168** (tier 0), **169** (tier 1), **170** (tier 2). Tier 2 needs
-//! HW T&L, >2 simultaneous textures and PS ≥ 1.1 — which any D3D9 part saturates.
-//!
-//! **`trilinear` is 1 on rows 169 and 170, at both CPU tiers, and carries no CPU bias term.** So
-//! the mode a real machine gets from a virgin install is **4**, not 3, and that is what benilla
-//! registers (decision 1645, superseding 1642's `"0"`). Measured, not only derived: the reference
-//! client's own `WoW/Logs/gx.log` on the director's machine reads `VID: 106b` (unlisted) →
-//! `DeviceAdapterInfer … DID: 2` → `DetectHardware(): videoID: 170`.
-//!
-//! **`anisotropic` is NOT one of the sixteen** (verified by scanning `[0x639a60, 0x639b80)`:
-//! sixteen record-pointer reads, `0xc7f2e4` absent). It keeps its registered `"1"` on every path,
-//! so anisotropy really is off out of the box — 1642's load-bearing half stands.
-//!
-//! ## One correction to how wide the policy reaches
-//!
-//! 1642 said there is no per-texture filter override anywhere in the reference. That is **too
-//! broad**. `applyGlobal` is a per-*call* argument to `0x449ae0`, and while terrain (`0x6c4c77`),
-//! WMO (the same wrapper `0x6c4c20`) and M2 (`0x71da72`) all pass `1` — which is what this module
-//! needs and is confirmed — six subsystems pass `0` and keep their own mode: weather sprites
-//! (hard-coded mode 4), the minimap, glue/loading, Lua texture widgets and the sky. None of them
-//! is a lane this module builds a sampler for, so the code is right; the claim was not.
-//!
-//! ## The divergence this module closes
-//!
-//! benilla hardcoded `mipmap_filter: Linear` + `anisotropy_clamp: 8` at every sampler it built —
-//! mode 5 at aniso 8, on every terrain layer array, model albedo, WMO albedo and static-GX array
-//! in the game, with no CVar and no way to turn it off. That is the *maximum* of what the
-//! reference will do on request, shipped as the thing it does before anybody asks.
-//!
-//! It is [`decisions/1624`]'s mistake one sampler over, and it was made the same way. `farclip`
-//! shipped at 777 because that was "what most players' `Config.wtf` had"; the filtering shipped at
-//! trilinear+aniso because an apitrace of the repo's reference install showed trilinear+aniso16 —
-//! and that install's `Config.wtf` carries `SET anisotropic "16"`. Both read a *set* value as a
-//! *registered* one. Verifying that a mechanism exists is not verifying that it is the default.
-//!
-//! The cost is not incidental. Mode 3 takes one bilinear tap per sample. Mode 5 at aniso 8 takes up
-//! to **sixteen** — eight along the anisotropy axis, doubled by the trilinear mip blend — and the
-//! worst case for the anisotropy axis is a tiling surface at a grazing angle, which is what ground
-//! is from a third-person camera. On the GPU-bound Steam Deck frame behind 1624 (B329) the texture
-//! path is where the frame already lives.
-//!
-//! ## Why a process global here too
-//!
-//! Not imitation: the same constraint the reference had. A sampler is baked into the [`Image`]
-//! asset at load time, and the lanes that build one are an async `AssetLoader` with no world
-//! access ([`crate::blp`]) and ordinary systems ([`crate::world_assets`], `static_gx`) — neither
-//! can read the other's resource. This is exactly the shape [`crate::gpu_blp`]'s `bc_supported`
-//! already has, for exactly the same reason.
-//!
-//! **Latched, like `gxMultisample`** (decision 1629): read once at boot and never again, because a
-//! sampler already baked into an uploaded texture cannot be changed without rebuilding it — which
-//! is also why the reference's own UI says "enabled upon restart". The CVar holds the pending
-//! value; the textures keep what they were born with.
+//! A process global because a sampler is baked into the [`Image`] at load, by an async loader
+//! ([`crate::blp`]) and by systems ([`crate::world_assets`]) that share no resource. Latched at
+//! boot like `gxMultisample`: a baked sampler cannot change without a rebuild, which is why the
+//! reference's UI says "enabled upon restart".
 
 use std::sync::OnceLock;
 
@@ -92,32 +29,25 @@ use bevy::image::ImageFilterMode;
 use bevy::prelude::*;
 use bevy::render::render_resource::FilterMode;
 
-/// The reference's `anisotropic` clamp — its callback parses 1-16 before clamping to the device
-/// cap (`0x689110`).
+/// The reference's `anisotropic` range: its callback parses 1-16, then clamps to the device cap
+/// (`0x689110`).
 pub const ANISO_RANGE: std::ops::RangeInclusive<u32> = 1..=16;
 
-/// The two globals, as one value: `trilinear` and `anisotropic` resolved into the policy every
-/// sampler in the process takes.
-///
-/// The precedence is the reference's own, not a choice: `anisotropic >= 2` writes mode 5 at
-/// `0x68919f` and `trilinear` writes mode 4 at `0x688d0f` *only* when the aniso option bit is
-/// clear (`0x688d0d js` skips it), so aniso outranks trilinear whichever order the callbacks run.
+/// `trilinear` and `anisotropic` resolved into the policy every sampler takes. Aniso outranks
+/// trilinear in either callback order: `anisotropic >= 2` writes mode 5 (`0x68919f`), and
+/// `trilinear` writes mode 4 (`0x688d0f`) only while the aniso bit is clear (`0x688d0d`).
 #[derive(Resource, Clone, Copy, PartialEq, Eq, Debug)]
 pub struct TexFilterSetting {
-    /// `trilinear` — mode 4 when set and aniso is off.
+    /// `trilinear`: mode 4 when set and aniso is off.
     pub trilinear: bool,
-    /// `anisotropic` — 1 is off; >=2 is mode 5 at that level.
+    /// `anisotropic`: 1 is off; 2 and up is mode 5 at that level.
     pub aniso: u32,
 }
 
 impl Default for TexFilterSetting {
-    /// What a virgin install actually renders at — `trilinear` **on**, `anisotropic` off — with
-    /// `$WOW_TRILINEAR` / `$WOW_ANISO` overriding **session-only**, the same law `$WOW_MSAA` and
-    /// `$WOW_FARCLIP` run under: this is the A/B lever for pricing the filter policy on one machine
-    /// in one session, and a value pinned into `config.toml` would make a measurement sticky.
-    ///
-    /// `trilinear` is `true` here and not the registrar's `"0"` because `hwDetect` sets it on both
-    /// fallback rows a real GPU can reach — see the module doc, and decision 1645.
+    /// A fresh install: `trilinear` on, as `hwDetect` sets it, and `anisotropic` off.
+    /// `$WOW_TRILINEAR` and `$WOW_ANISO` override for the session only, like `$WOW_MSAA`, so an A/B
+    /// never sticks in `config.toml`.
     fn default() -> Self {
         let env_flag = |k: &str| {
             std::env::var(k)
@@ -135,8 +65,7 @@ impl Default for TexFilterSetting {
 }
 
 impl TexFilterSetting {
-    /// The reference's filter mode 0-5 (`[0x835250]`) this policy resolves to. Only 3, 4 and 5 are
-    /// reachable from the two CVars; the lower three are set by nothing in the shipped image.
+    /// The reference's filter mode (`[0x835250]`); the two CVars reach only 3, 4 and 5.
     pub fn mode(self) -> u8 {
         if self.aniso >= 2 {
             5
@@ -147,7 +76,7 @@ impl TexFilterSetting {
         }
     }
 
-    /// The mip filter this policy asks for: mode 3 selects the nearer mip, 4 and 5 blend the two.
+    /// Mode 3 selects the nearer mip; 4 and 5 blend the two.
     pub fn mipmap_filter(self) -> ImageFilterMode {
         match self.mode() {
             3 => ImageFilterMode::Nearest,
@@ -155,8 +84,7 @@ impl TexFilterSetting {
         }
     }
 
-    /// The same, for the lanes that build a raw wgpu [`SamplerDescriptor`](
-    /// bevy::render::render_resource::SamplerDescriptor) instead of an [`Image`]'s.
+    /// The same, for a lane that builds a raw wgpu `SamplerDescriptor`.
     pub fn gpu_mipmap_filter(self) -> FilterMode {
         match self.mode() {
             3 => FilterMode::Nearest,
@@ -164,10 +92,8 @@ impl TexFilterSetting {
         }
     }
 
-    /// The max anisotropy — `(mode == 5 ? [0x835254] : 1)`, `0x449afc`.
-    ///
-    /// wgpu additionally requires all three filters to be `Linear` before it will accept a clamp
-    /// above 1, which mode 5 satisfies by construction and modes 3/4 never reach.
+    /// The max anisotropy, `(mode == 5 ? [0x835254] : 1)` (`0x449afc`). wgpu takes a clamp above 1
+    /// only with every filter `Linear`, which mode 5 always has.
     pub fn anisotropy_clamp(self) -> u16 {
         if self.mode() == 5 {
             self.aniso.clamp(*ANISO_RANGE.start(), *ANISO_RANGE.end()) as u16
@@ -179,18 +105,14 @@ impl TexFilterSetting {
 
 static POLICY: OnceLock<TexFilterSetting> = OnceLock::new();
 
-/// Publish the resolved policy for the process. Called once, from the CVar load
-/// (`benilla_app::cvars::load_config`, the `CvarLoad` set) — the earliest moment `config.toml` has
-/// been folded in, and before any system that can request a texture has run.
+/// Publish the resolved policy once, from the CVar load (`benilla_app::cvars::load_config`, the
+/// `CvarLoad` set): after `config.toml` is folded in, before any system can request a texture.
 pub fn publish_tex_filter(setting: TexFilterSetting) {
     let _ = POLICY.set(setting);
 }
 
-/// The policy every sampler in the process takes.
-///
-/// Unpublished — the world viewer, a headless test, or a texture somehow requested ahead of
-/// `CvarLoad` — falls back to [`TexFilterSetting::default`], which is what a virgin install
-/// renders at. A race can therefore only ever produce the faithful value, never a wrong one.
+/// The policy every sampler takes; unpublished (the world viewer, a headless test), it is
+/// [`TexFilterSetting::default`], a fresh install's value.
 pub fn tex_filter() -> TexFilterSetting {
     *POLICY.get_or_init(TexFilterSetting::default)
 }
@@ -199,14 +121,8 @@ pub fn tex_filter() -> TexFilterSetting {
 mod tests {
     use super::*;
 
-    /// **What benilla actually ships** — `hwDetect`'s row-170 outcome, not the registrar's string:
-    /// trilinear on, anisotropy off, mode 4 (decision 1645). If this ever reads mode 5, we are
-    /// shipping the divergence 1642 removed; if it reads mode 3, we are back to reading the
-    /// registrar's string as if `hwDetect` did not exist.
-    ///
-    /// `Default` is the assertion's subject deliberately: it is the value every unpublished lane
-    /// falls back to, so this pins the fallback and the shipped default in one place. It reads the
-    /// env, hence the guard — the levers are session-only and a set one must not fail the suite.
+    /// `hwDetect`'s row-170 outcome, mode 4. `Default` is also the unpublished fallback; it reads
+    /// the env, so a set lever skips the test.
     #[test]
     fn what_ships_is_trilinear_with_anisotropy_off() {
         if std::env::var_os("WOW_TRILINEAR").is_some() || std::env::var_os("WOW_ANISO").is_some() {
@@ -226,10 +142,7 @@ mod tests {
         assert_eq!(shipped.anisotropy_clamp(), 1);
     }
 
-    /// The registrar's own string, which is a real thing that is simply not what a machine gets:
-    /// `[0x835250] = 3` with `trilinear "0"` is the state a client would render at if the hardware
-    /// table said nothing. Kept as a test because the mode-3 arm is still reachable — any run whose
-    /// `config.toml` or `$WOW_TRILINEAR` says 0 takes it.
+    /// The registered strings alone, mode 3, reached when `config.toml` or `$WOW_TRILINEAR` says 0.
     #[test]
     fn the_registrars_own_string_is_still_mode_three() {
         let registrar = TexFilterSetting {
@@ -242,7 +155,6 @@ mod tests {
         assert_eq!(registrar.anisotropy_clamp(), 1);
     }
 
-    /// `trilinear 1` alone is mode 4: the mip blend arrives, the aniso does not.
     #[test]
     fn trilinear_alone_is_mode_four() {
         let s = TexFilterSetting {
@@ -254,8 +166,6 @@ mod tests {
         assert_eq!(s.anisotropy_clamp(), 1);
     }
 
-    /// `anisotropic >= 2` is mode 5 and **outranks** `trilinear` in both directions — the mip
-    /// blend comes with it whether or not `trilinear` was ever set.
     #[test]
     fn aniso_outranks_trilinear_in_both_directions() {
         for trilinear in [false, true] {
@@ -269,8 +179,6 @@ mod tests {
         }
     }
 
-    /// `anisotropic 1` is off, not "aniso at one sample" — the reference's own reading of the
-    /// registered string, and the reason the default is not mode 5.
     #[test]
     fn aniso_one_is_off() {
         let s = TexFilterSetting {
@@ -280,8 +188,6 @@ mod tests {
         assert_eq!(s.mode(), 3);
     }
 
-    /// wgpu rejects a clamp above 1 unless every filter is `Linear`; modes 3 and 4 must therefore
-    /// never report one, whatever the CVar holds.
     #[test]
     fn a_clamp_above_one_only_ever_rides_all_linear_filters() {
         for s in [
diff --git a/crates/benilla-assets/src/trace.rs b/crates/benilla-assets/src/trace.rs
index becac458..5df4eeba 100644
--- a/crates/benilla-assets/src/trace.rs
+++ b/crates/benilla-assets/src/trace.rs
@@ -1,30 +1,9 @@
-//! The shared debug-trace sink behind `WOW_MOVE_TRACE=<path>`: one file, one clock, written by
-//! the player mover's frame lines (`benilla::player`'s `move_trace`), its outbound wire lines
-//! (`snd`), the anim driver's event lines (`benilla::creature_anim`), and the remote-replay lines
-//! (`rly`/`run`, `benilla::net::motion`) — so the layers interleave on a common timeline and a feel
-//! report ("it snaps when I land") can be read across all of them.
-//!
-//! **The two wire tags are `in` and `out`, and between them every packet is accounted for by
-//! name.** `in` is the full inbound opcode stream (decision 0624); `out` is the full outbound one
-//! (decision 1901), written by the write thread from the writer's own post-write log — so an `out`
-//! line is a *transmission*, where the mover's `snd` line is a decision taken before the command is
-//! even queued and `wire` carries only failures. Each file opens with a
-//! `# t0=<unix epoch>` header so **two clients' traces align with each other**, which is what a
-//! sender-vs-observer question needs. Costs one `OnceLock` read per call when the env var is unset.
-//!
-//! **It lives down here, below both sides of decision 1160's line, because both sides write to it**
-//! — the engine's billboard/zfill/particle traces and the game's mover and wire traces share one
-//! file and one clock, which is the whole point of it. An instrument at the *top* of the stack
-//! could not be called by the engine at all; a leaf with no dependencies can be called by
-//! everything. It carries no domain knowledge: a tag, a message, a mutex and a file.
-//!
-//! **`WOW_MOVE_TRACE_TAGS="move,snd,in"` narrows it to those tags** (unset = everything). This is
-//! not tidiness: every line is an unbuffered `write` under one global mutex on the main thread, so a
-//! busy tag distorts the run it is meant to measure. A 600-yd fall probe (decision 0880) wrote
-//! ~4,200 lines/s, nearly all of them `card`, and the `move` line's own `t=` then carried whatever
-//! the queue ahead of it cost — frames read back as 0.011 s with 2.86 yd of travel, or 0.040 s with
-//! 0.96 yd, against a physics integration that was exact. A trace whose clock cannot be trusted for
-//! per-frame timing is half an instrument; filtering to the tags the question needs gives it back.
+//! The shared debug-trace sink behind `WOW_MOVE_TRACE=<path>`: one file and one clock for every
+//! layer's tagged lines, engine and game alike, so it sits below both. `in` and `out` are the full
+//! inbound and outbound opcode streams; `out` is written after the send, where the mover's `snd`
+//! is a decision before queueing. Each file opens with a `# t0=<unix epoch>` header so two
+//! clients' traces align. `WOW_MOVE_TRACE_TAGS="move,snd,in"` keeps only those tags: every line is
+//! an unbuffered write under one mutex on the main thread, so a busy tag skews every `t=`.
 
 use std::fs::File;
 use std::io::Write;
@@ -44,10 +23,7 @@ fn sink() -> Option<&'static Mutex<Sink>> {
         let mut out = File::create(&path)
             .map_err(|e| eprintln!("dbg-trace: cannot create {path}: {e}"))
             .ok()?;
-        // The wall-clock epoch of this file's `t=0`, so **two traces can be read against each other**
-        // — a sender's `snd` lines beside an observer's `rly`/`run` lines from a different process
-        // (decision 0619). `t=` alone is per-process seconds and says nothing across clients; with
-        // this header, wall time is `t0 + t`.
+        // Wall time is `t0 + t`, which aligns the traces of two processes.
         let t0_wall = std::time::SystemTime::now()
             .duration_since(std::time::UNIX_EPOCH)
             .map_or(0.0, |d| d.as_secs_f64());
@@ -60,11 +36,10 @@ fn sink() -> Option<&'static Mutex<Sink>> {
     .as_ref()
 }
 
-/// The optional tag allow-list from `WOW_MOVE_TRACE_TAGS`; `None` (unset or empty) = keep everything.
+/// The tag allow-list from `WOW_MOVE_TRACE_TAGS`; `None`, unset or empty, keeps everything.
 static TAGS: OnceLock<Option<Vec<String>>> = OnceLock::new();
 
-/// Whether `tag` survives the allow-list. Checked **before** the mutex, so a filtered-out tag costs
-/// a slice compare rather than a lock and a syscall — which is the whole point (see the module note).
+/// Whether `tag` survives the allow-list, checked before the mutex so a filtered tag takes no lock.
 fn tag_allowed(tag: &str) -> bool {
     TAGS.get_or_init(|| {
         let raw = std::env::var("WOW_MOVE_TRACE_TAGS").ok()?;
@@ -79,13 +54,12 @@ fn tag_allowed(tag: &str) -> bool {
     .is_none_or(|allow| allow.iter().any(|t| t == tag))
 }
 
-/// Whether the trace is enabled — lets callers skip building their line when it's off.
+/// Whether the trace is on, so a caller can skip building its line.
 pub fn enabled() -> bool {
     sink().is_some()
 }
 
-/// Whether this *tag* is being written — [`enabled`] plus the allow-list, for a caller whose line is
-/// expensive to build (a per-frame `format!` over a hot loop) and which is filtered out anyway.
+/// [`enabled`] plus the allow-list, for a caller whose line is expensive to build.
 pub fn enabled_for(tag: &str) -> bool {
     enabled() && tag_allowed(tag)
 }
diff --git a/crates/benilla-assets/src/wdt.rs b/crates/benilla-assets/src/wdt.rs
index d54eddb2..519f0519 100644
--- a/crates/benilla-assets/src/wdt.rs
+++ b/crates/benilla-assets/src/wdt.rs
@@ -1,12 +1,6 @@
-//! WDT → map tile-index asset loader.
-//!
-//! Decodes a map's tiny `.wdt` into a [`WdtIndex`] — the 64×64 `MAIN` tile-existence grid the
-//! terrain streamer consults before requesting any `.adt` (decision 0476): open ocean authors no
-//! tiles, and probing them wholesale spammed asset-server NotFound errors on every boat crossing.
-//! It also carries the map's **global WMO** where there is one (decision 0688): on the 20 shipped
-//! maps that author no terrain at all, that single placement is the entire world.
-//! The parse itself is `benilla-wdt`'s [`WdtReader`] (oracle-tested in the 0021 migration); this
-//! module only wraps it in the Bevy asset machinery.
+//! WDT loader: a map's 64×64 `MAIN` tile-existence grid, which the terrain streamer checks before
+//! requesting an `.adt` (open ocean authors none), and its global WMO, the whole world on a map
+//! with no terrain.
 
 use benilla_formats::{GlobalWmo, WdtFile, WdtReader, WowVersion};
 use bevy::asset::io::Reader;
@@ -18,23 +12,21 @@ use bevy::reflect::TypePath;
 pub struct WdtIndex(WdtFile);
 
 impl WdtIndex {
-    /// Whether tile `(tile_x, tile_y)` has an `.adt` (`MAIN` flag bit 0) — the same index order as
-    /// the `Map_<tile_x>_<tile_y>.adt` file names and [`benilla_formats::world_to_tile`].
-    /// Out-of-range ⇒ `false`.
+    /// Whether tile `(tile_x, tile_y)` has an `.adt` (`MAIN` flag bit 0), in the order of the
+    /// `Map_<tile_x>_<tile_y>.adt` names.
     pub fn has_tile(&self, tile_x: u32, tile_y: u32) -> bool {
         self.0
             .get_tile(tile_x as usize, tile_y as usize)
             .is_some_and(|t| t.has_adt)
     }
 
-    /// The map's single global building, on a map with no terrain (`MPHD` bit 0) — see
-    /// [`GlobalWmo`]. `None` on an ADT map.
+    /// The single global building of a map with no terrain (`MPHD` bit 0); `None` on an ADT map.
     pub fn global_wmo(&self) -> Option<&GlobalWmo> {
         self.0.global_wmo()
     }
 }
 
-/// Bevy [`AssetLoader`] decoding a vanilla `*.wdt` → [`WdtIndex`].
+/// Loads a `*.wdt` into a [`WdtIndex`].
 #[derive(Default, TypePath)]
 pub struct WdtIndexLoader;
 
@@ -64,9 +56,7 @@ impl AssetLoader for WdtIndexLoader {
 mod tests {
     use super::*;
 
-    /// A minimal synthetic WDT: MVER + a MAIN grid with exactly two tiles flagged present.
-    /// Pins the parse AND the index order ([`WdtIndex::has_tile`] is `(tile_x, tile_y)`, the
-    /// on-disk grid is row-major `y * 64 + x`).
+    /// The on-disk grid is row-major, `y * 64 + x`.
     #[test]
     fn parses_main_grid_in_tile_index_order() {
         let mut buf = Vec::new();
diff --git a/crates/benilla-assets/src/wmo.rs b/crates/benilla-assets/src/wmo.rs
index 15fbc6cc..31b11fc5 100644
--- a/crates/benilla-assets/src/wmo.rs
+++ b/crates/benilla-assets/src/wmo.rs
@@ -1,14 +1,7 @@
-//! WMO → model asset loader.
-//!
-//! A WMO (building) is a **root** file plus N **group** files (`<stem>_NNN.wmo`). The loader reads the
-//! root from the [`Reader`], then reads each group via [`LoadContext::read_asset_bytes`] (raw bytes,
-//! recorded as a dependency — *not* `load()`, which would recurse back into this loader), building one
-//! [`ModelSubmesh`] per group render batch with its texture resolved against the root's material
-//! tables.
-//!
-//! Same app-independent shape as the M2 loader (geometry + texture handles + metadata; meshes are
-//! built paced app-side — decision 0834 — and materials at spawn). WMOs don't size-fade, so there
-//! are no bounds.
+//! WMO asset loader: a root file plus its group files (`<stem>_NNN.wmo`), one [`ModelSubmesh`] per
+//! group render batch. Groups are read with [`LoadContext::read_asset_bytes`], not `load()`, which
+//! would recurse into this loader. The app builds the meshes, paced, as a city's thousands of
+//! batches would land in one frame.
 
 use crate::column_grid::ColumnGrid;
 use std::sync::Arc;
@@ -27,11 +20,8 @@ use bevy::reflect::TypePath;
 
 use crate::model::ModelSubmesh;
 
-/// Per-WMO-group navigation data for the portal visibility cull (`crate::wmo_portal`): the group's
-/// MOGP flags (the EXTERIOR `0x8` bit the flood defers on), its bounding box (WMO model space, WoW
-/// axes — the camera current-group containment test), and its slice of [`WmoModel::portal_refs`].
-/// Indexed by **absolute group index** (parallel gaps for unreadable groups carry a degenerate box +
-/// zero refs, so they're never a current-group candidate and never flood).
+/// One WMO group's portal-cull data: MOGP flags (the flood defers on EXTERIOR `0x8`), the MOGI box
+/// and its slice of [`WmoModel::portal_refs`]; an unreadable group never floods.
 #[derive(Clone, Copy)]
 pub struct WmoGroupNav {
     pub flags: u32,
@@ -39,198 +29,111 @@ pub struct WmoGroupNav {
     pub bbox_max: [f32; 3],
     pub ref_start: u16,
     pub ref_count: u16,
-    /// The group's `WMOAreaTable.WMOGroupID` key (MOGP `uniqueID`; 0 = none carried).
+    /// The `WMOAreaTable.WMOGroupID` key, MOGP `uniqueID`; 0 when none.
     pub area_table_id: u32,
-    /// The group's MOGP fog indices (disk `+0x30`, empirically pinned against the Goldshire inn) —
-    /// up to four indices into [`WmoModel::fogs`], walked by the camera-in-interior fog selector
-    /// (`0x69de20`, wow-re `rf-weather-emission-timeline` ROUND 5).
+    /// MOGP fog indices (disk `+0x30`) into [`WmoModel::fogs`], for the fog selector (`0x69de20`).
     pub fog_indices: [u8; 4],
-    /// MOGP `groupLiquid` (`0xf` = none) — the **whole-group submersion override**. On the 13
-    /// shipped groups that set it, the client's liquid probe answers "submerged" for the entire
-    /// group at every Z with no grid involved at all; see
-    /// [`benilla_formats::WmoGroupHeader::group_liquid`].
+    /// MOGP `groupLiquid` (`0xf` = none): when set, the whole group reads submerged at every Z.
     pub group_liquid: u32,
 }
 
-/// A loaded WMO building: the render batches across all its groups, flattened, plus the flattened
-/// collidable triangles (the app bakes a collider from these per placement).
-/// `Default` = the empty building (every field vacuous) — a test scaffold, never a loader product.
+/// A loaded WMO building; `Default` is an empty test scaffold, never a loader product.
 #[derive(Asset, TypePath, Clone, Default)]
 pub struct WmoModel {
-    /// The building's `WMOAreaTable.WMOID` key (root `MOHD.wmoID`; NSabbey → 59).
+    /// The `WMOAreaTable.WMOID` key (root `MOHD.wmoID`).
     pub wmo_id: u32,
     pub submeshes: Vec<ModelSubmesh>,
-    /// Group index per entry in [`Self::submeshes`] (parallel) — which WMO group each render batch
-    /// belongs to, so the portal cull can hide a whole group by toggling its submeshes' `Visibility`.
+    /// The group of each entry in [`Self::submeshes`], so the portal cull can hide a whole group.
     pub submesh_group: Vec<u16>,
-    /// The portal graph (MOPV vertices / MOPT infos / MOPR refs), WMO model space (WoW axes). The
-    /// per-frame cull floods this from the camera's current group (`crate::wmo_portal`). Empty ⇒ no
-    /// portals (single-group props) ⇒ every group stays visible.
+    /// The portal graph (MOPV, MOPT, MOPR) in model space; with none, every group stays visible.
     pub portal_vertices: Vec<[f32; 3]>,
     pub portal_infos: Vec<WmoPortalInfo>,
     pub portal_refs: Vec<WmoPortalRef>,
-    /// Per-group nav (flags + bbox + portal-ref slice), indexed by absolute group index.
+    /// Per-group cull data, indexed by absolute group index.
     pub group_nav: Vec<WmoGroupNav>,
-    /// The root's MFOG fog records — record 0 is the WMO default (the interior-fog selector's
-    /// seed); a group's [`WmoGroupNav::fog_indices`] point here. Consumed by the camera-in-interior
-    /// fog resolve (`crate::wmo_portal` in the app), per wow-re `rf-weather-emission-timeline`
-    /// ROUND 5 (`0x69de20`).
+    /// The root's MFOG records; record 0 is the building default.
     pub fogs: Vec<WmoFog>,
-    /// The root's **MOSB** skybox model (`.m2`), drawn as the sky backdrop while the camera stands in
-    /// a group whose flags carry `0x40000` — see `crate::skybox` in the app for the gate and
-    /// `benilla_formats::WmoGroupInfo::show_skybox` for how that bit was identified. `None` for all
-    /// but a handful of roots (`benilla-extract skyboxscan`); carrying it here costs one `Option`
-    /// per building and saves the sky lane a second root parse.
+    /// The root's MOSB skybox model, drawn while the camera is in a group flagged `0x40000`.
     pub skybox: Option<String>,
-    /// Per-group **walking-collision** triangles (WoW model space, indexed by absolute group index) —
-    /// the Leg-A face set for the current-group **down-ray** (`crate::wmo_portal`). The faithful "which
-    /// room is the camera in" test casts a ray straight down from the eye against the same face set the
-    /// player's walking collision uses — every non-DETAIL face, **no orientation filter** (`wow-5875-re`
-    /// `system/models/scratch/wmo-portal-audit.md` Q3/Q4: the client's Leg A is the walking-collision
-    /// BSP, mask `0x84`; an earlier render-face `|n.z|` floor heuristic mis-seeded doorways and slab
-    /// edges). Same triangles as [`Self::collision`], kept per group for group attribution.
+    /// Per-group walking-collision faces (non-DETAIL, no orientation filter): the reference's
+    /// walking BSP set (`0x6be250`, mask `0x84`) that the current-group down-ray casts on.
     pub group_collision_tris: Vec<Vec<[[f32; 3]; 3]>>,
-    /// Per-group **camera-only** triangles (parallel to [`Self::group_collision_tris`]): the faces
-    /// the camera gather keeps but the walking gather drops — DETAIL (`0x04`) set, NOCAMCOLLIDE
-    /// (`0x02`) clear. The down-ray's **camera-void fallback** (decision 0692) races this set only
-    /// after the faithful walking Leg A and portal Leg B both miss AND no terrain surface sits at or
-    /// below the eye: an eye held between camera-collidable surfaces (the Deadmines entrance pocket,
-    /// whose floor is all-DETAIL) then still names its room instead of blanking the building.
+    /// Per-group camera-only faces (DETAIL `0x04` set, NOCAMCOLLIDE `0x02` clear). Deviation: the
+    /// down-ray tries them when the walking and portal legs miss and no terrain lies below the eye,
+    /// because the reference reads outside there and blanks the building around a camera sealed in
+    /// an all-DETAIL pocket.
     pub group_camera_only_tris: Vec<Vec<[[f32; 3]; 3]>>,
-    /// Per-group AABB of [`Self::group_collision_tris`] (parallel; `None` = no collision faces),
-    /// computed at load **from the triangles themselves** — the broad phase for the faces-only
-    /// down-ray (`area_down_ray`). Bounds derived from the faces can only summarize the geometry,
-    /// never understate it the way an authored MOGI box can (NSabbey group 3's authored bottom
-    /// floats 1.5 yd above its own floor polys — the 2026-07-12 indoor flap), so culling on them
-    /// is exact: a group is skipped only when no face of it could own the probe column.
+    /// Per-group AABB of [`Self::group_collision_tris`], from the faces rather than MOGI: an
+    /// authored MOGI box can sit above its own floor (Northshire Abbey group 3, by 1.5 yd).
     pub group_collision_bounds: Vec<Option<([f32; 3], [f32; 3])>>,
-    /// Per-group column index over [`Self::group_collision_tris`] (parallel; `None` = a face set
-    /// too small to be worth indexing, and the caller keeps its linear scan). The narrow phase the
-    /// per-group bounds above never had: a dungeon group holds ~11–16k faces, so bounds alone
-    /// still left every down-ray scanning tens of thousands of triangles per unit per frame
-    /// (LBRS, 2026-07-27). See [`crate::column_grid`].
+    /// Per-group [`ColumnGrid`] over [`Self::group_collision_tris`]; `None` when too few to index.
     pub group_collision_grids: Vec<Option<ColumnGrid>>,
-    /// The union of [`Self::group_collision_bounds`] — the whole-building broad phase: a probe
-    /// column outside it cannot hit any collision face, so the per-frame indoor trackers skip the
-    /// placed instance outright (a camera in open country pays one AABB test per building, not a
-    /// face scan — the 2026-07-12 fps regression).
+    /// The union of [`Self::group_collision_bounds`]: the whole-building broad phase.
     pub collision_bounds: Option<([f32; 3], [f32; 3])>,
-    /// **Walking** collidable triangles across all groups in raw WMO-local coords — the player-body
-    /// gather (excludes DETAIL faces). `None` when the building carries no collidable geometry.
+    /// Walking collision across all groups in WMO-local coords, DETAIL faces excluded.
     pub collision: Option<CollisionMesh>,
-    /// **Camera/LOS** collidable triangles — the third-person-camera gather (excludes NOCAMCOLLIDE,
-    /// *keeps* DETAIL). Distinct from [`Self::collision`]; the app bakes a separate collider on the
-    /// camera collision layer so the camera can't slip behind visible decals/overhangs (e.g. forge
-    /// pipes) the player walks under. `None` when the building has no camera-collidable geometry.
+    /// Camera and line-of-sight collision: DETAIL kept, NOCAMCOLLIDE dropped.
     pub collision_camera: Option<CollisionMesh>,
-    /// The root's placed doodads (MODD props — candle stands, banners), in WMO model space; the app
-    /// spawns each as an M2 composed with the WMO instance transform, selected by doodad set.
+    /// The root's MODD doodads in WMO model space, spawned by doodad set.
     pub doodads: Vec<WmoDoodad>,
-    /// The doodad sets (MODS) — ranges into [`Self::doodads`]; set 0 is global, a placement picks one more.
+    /// The MODS ranges into [`Self::doodads`]: set 0 always, plus the one a placement picks.
     pub doodad_sets: Vec<WmoDoodadSet>,
-    /// The root's MOLT lights (the interior fixture lights — fireplaces, forge, candles, chandeliers),
-    /// in WMO model space. Spawned as dynamic point lights (decisions 0016/0273) that warm nearby
-    /// doodads/NPCs, terrain, and the building's own walls/floor over their baked MOCV.
+    /// The root's MOLT fixture lights in WMO model space, spawned as point lights.
     pub lights: Vec<WmoLight>,
-    /// Per-group interior flag + bounding box (MOGI), WMO model space — classifies which placed doodads
-    /// are interior (lit off the room/fixtures) vs exterior (lit off the sky). See [`WmoGroupInfo`].
+    /// Per-group MOGI interior flag and box, in WMO model space.
     pub group_bounds: Vec<WmoGroupInfo>,
-    /// Per-MODD lighting base, parallel to [`Self::doodads`] — resolved ONCE at load (placements are
-    /// fixed in the root). See [`DoodadBase`]: an interior-group doodad's base is its own MODD
-    /// entry's baked colour, and its point light comes only from its owning group's MOLR list. The
-    /// footprint down-ray this replaced (decision 0290) is byte-real code, but it is the ADT-MDDF
-    /// attach path — a WMO MODD doodad never reaches it (create never calls SetMatrix; wow-re
-    /// `trace-forensics-abbey-interior-d3d` §1.1).
+    /// Per-MODD lighting base, parallel to [`Self::doodads`]. A MODD doodad never takes the
+    /// footprint down-ray: its create (`0x694e90`) never calls `SetMatrix` (`0x698d20`).
     pub doodad_base: Vec<DoodadBase>,
-    /// Per-MODD **instantiating group** (the first group whose MODR refs name it), parallel to
-    /// [`Self::doodads`]; `None` for a MODD no group references. The reference creates a doodad
-    /// once, on the first visible-group walk that reaches it, and that create is what fills its
-    /// baked colour words — so this names the MOLR set the interior fold gates on
-    /// ([`Self::doodad_base`]). It is **not** the interior/exterior class: every referrer writes the
-    /// lane of the same def and exterior is absorbing, so the class reads [`Self::doodad_groups`]
-    /// (see [`resolve_doodad_bases`]).
+    /// Per-MODD first referencing group, whose MOLR set the interior lane folds; the
+    /// interior/exterior class reads [`Self::doodad_groups`].
     pub doodad_owner: Vec<Option<u16>>,
-    /// Per-MODD **referencing groups** — every group whose MODR names it, parallel to
-    /// [`Self::doodads`]; empty for a MODD no group references.
-    ///
-    /// This is the prop's portal-cull key. The reference commits a WMO's doodads **per visible
-    /// group** — `0x695aa0` loops the group's own MODR refs at `group+0xe8`/count `+0x144`, called
-    /// from the visible-group walk `0x698720` (wow-re `m2-interior-doodad-base-light.md` §453,
-    /// `trace-forensics-abbey-interior-d3d.md` §90) — so a group the portal flood culled draws none
-    /// of its furniture, and a prop **any** of whose referrers is visible is drawn. Without the key
-    /// at all, props outlive their own building: cull every group of a dungeon and its lanterns,
-    /// crates and cobwebs hang in the void (decision 0689). With the key collapsed to one owner, a
-    /// prop that hangs through several rooms — a lava fall — blinks out on every camera angle whose
-    /// flood reaches a different one of its referrers.
+    /// Per-MODD every group whose MODR names it: the portal-cull key, as the reference draws
+    /// doodads per visible group (`0x695aa0`, MODR at `+0xe8`, count `+0x144`, walk `0x698720`).
     pub doodad_groups: Vec<Arc<[u16]>>,
-    /// Per-group FOOTPRINT face set (render tris + baked MOCV + MOPY flags), indexed by absolute
-    /// group index; `None` for exterior groups / groups without MOCV. The **GameObject M2** light
-    /// lane samples it: the entity node's env-update attach down-rays the render mesh under the
-    /// object and bakes the hit's barycentric MOCV, floor-168/cap-96, on the fixed interior axis
-    /// (`0x69e4c0`; wow-re `wmo-lit-selector.md`, trace-decisive on the abbey benches).
+    /// Per-group footprint faces (render faces, MOCV, MOPY flags); `None` for exterior groups and
+    /// groups without MOCV. A GameObject M2 down-rays them for its MOCV lighting (`0x69e4c0`).
     pub group_footprints: Vec<Option<FootprintTris>>,
-    /// Root MOMT `ground_type` per material — the `TerrainType.dbc` id a face's
-    /// `FootprintTris::mopy_material` resolves to. Shared by every group (MOMT lives on the root),
-    /// and the tail of the footstep chain's WMO leg (decision 1161).
+    /// Root MOMT `ground_type` per material: the `TerrainType.dbc` id of a face's MOPY material.
     pub material_ground_type: Vec<u32>,
-    /// Root MOMT `diffColor` per material, RGB 0..1 — the body colour an **interior** MLIQ pool
-    /// takes, indexed by its `LiquidMesh::material_id`. MOMT lives in the root, so a group file
-    /// cannot resolve its own pool's colour; the spawner does it from here.
+    /// Root MOMT `diffColor` per material, RGB 0..1: an interior MLIQ pool's colour, by material.
     pub material_diff_color: Vec<[f32; 3]>,
-    /// Per-group AABB of the faces [`Self::group_footprints`] actually references (parallel;
-    /// `None` = no footprint faces), computed at load from the triangles themselves — the broad
-    /// phase for the footprint down-ray, the same exact-cull argument as
-    /// [`Self::group_collision_bounds`]: a probe column outside a group's face bounds in XY, or
-    /// wholly below its lowest vertex, can hit none of its faces. Without it every re-rayed
-    /// entity scanned EVERY interior group of the whole model — at Stormwind (one WMO, all
-    /// districts) that was the live-session frame (decision 0364).
+    /// Per-group AABB of the faces [`Self::group_footprints`] uses: the footprint broad phase.
     pub group_footprint_bounds: Vec<Option<([f32; 3], [f32; 3])>>,
-    /// Per-group column index over [`Self::group_footprints`] (parallel; `None` = not indexed).
-    /// The footprint sample is the heavier of the two column rays — it walks render faces, not
-    /// collision ones. See [`crate::column_grid`].
+    /// Per-group [`ColumnGrid`] over [`Self::group_footprints`]; `None` when not indexed.
     pub group_footprint_grids: Vec<Option<ColumnGrid>>,
-    /// Per-group MOLR light refs (indices into [`Self::lights`]), indexed by absolute group index —
-    /// the point lights that fold into an interior GameObject's committed light are gated by the
-    /// footprint-hit group's list, same as a MODD prop's by its owning group.
+    /// Per-group MOLR refs into [`Self::lights`]: a MODD prop folds its owning group's list, a
+    /// GameObject its footprint-hit group's.
     pub group_light_refs: Vec<Vec<u16>>,
-    /// Per-group MLIQ liquid surface (the animated water/lava/slime a group embeds — Stormwind's
-    /// canals + fountains, the Ironforge lava, dungeon pools), indexed by absolute group index;
-    /// `None` for a group with no `MLIQ`. Built in WMO model space (WoW axes); the app spawns each at
-    /// the placement transform, on the shared per-kind liquid material.
+    /// Per-group MLIQ liquid surface in WMO model space; `None` for a group without one.
     pub group_liquids: Vec<Option<LiquidMesh>>,
 }
 
-/// The load-resolved lighting base of one placed MODD doodad. The real client fills an
-/// interior-group doodad's slot-0 words at CREATE, from the MODD record's own colour field —
-/// byte-verified (`0x694e90` → `6950de call 0x6a77e0(&MODD.colour, &diffuse, 0x70, &ambient, 0x60)`)
-/// and read live off the reference's abbey draws, where both decoded stands' diffuse words equal
-/// their MODD colour bytes verbatim (wow-re `trace-forensics-abbey-interior-d3d` §1).
+/// One MODD doodad's lighting base. The reference fills an interior doodad's words at create from
+/// the MODD colour: `0x694e90` calls `0x6a77e0`, diffuse floor `0x70`, ambient cap `0x60`.
 #[derive(Clone, PartialEq, Debug)]
 pub enum DoodadBase {
-    /// Exterior-group doodad — the sky-lit lane (day/night sun; a WMO prop takes the plain matte).
+    /// The sky-lit lane of an exterior-group doodad.
     Exterior,
-    /// Interior-group doodad: the MODD-colour base + the owning group's light refs.
+    /// An interior-group doodad: the MODD-colour base and the owning group's light refs.
     Interior(InteriorPropBase),
 }
 
-/// An interior MODD doodad's resolved base light — computed once at load, day/night-independent.
+/// An interior MODD doodad's base light, independent of the time of day.
 #[derive(Clone, PartialEq, Debug)]
 pub struct InteriorPropBase {
-    /// The ambient word: `cap96(MODD.colour)` (0–1 RGB). See [`cap96`].
+    /// The ambient word, [`cap96`] of the MODD colour, RGB 0..1.
     pub ambient: [f32; 3],
-    /// The diffuse word: `floor112(MODD.colour)` (0–1 RGB), committed as a directional lobe on the
-    /// fixed engine axis (−0.30822, −0.30822, −0.9) — never the day/night sun. See [`floor112`].
+    /// The diffuse word, [`floor112`] of the MODD colour, lit along the fixed axis
+    /// (−0.30822, −0.30822, −0.9), never the sun.
     pub diffuse: [f32; 3],
-    /// The owning group's MOLR light refs (indices into [`WmoModel::lights`]): the ONLY point lights
-    /// this doodad's committed light folds (range-gated by each light's disk attenStart/attenEnd at
-    /// spawn). Empty — a group with no MOLR — means NO point light at all, its own flame included.
+    /// The owning group's MOLR refs into [`WmoModel::lights`], the only point lights it folds
+    /// (range-gated by attenStart and attenEnd); empty means none, its own flame included.
     pub light_refs: Vec<u16>,
 }
 
-/// Per-group AABBs of the footprint faces each group actually references —
-/// [`WmoModel::group_footprint_bounds`], derived at load from the indexed vertices (not the whole
-/// position array, which may carry vertices no footprint face uses). Shared with the fixture
-/// builders so tests and the loader can never disagree on what the bounds mean.
+/// Per-group AABBs of the vertices the footprint faces index, not of every position; shared with
+/// the test fixtures.
 pub fn footprint_tri_bounds(
     footprints: &[Option<FootprintTris>],
 ) -> Vec<Option<([f32; 3], [f32; 3])>> {
@@ -254,9 +157,7 @@ pub fn footprint_tri_bounds(
         .collect()
 }
 
-/// Per-group column indexes over the footprint faces — [`WmoModel::group_footprint_grids`].
-/// Shared with the fixture builders for the same reason the bounds are: a test model and a loaded
-/// one must be indexed by identical code, or an exactness test proves nothing about the real path.
+/// Per-group column indexes over the footprint faces, shared with the test fixtures.
 pub fn footprint_tri_grids(footprints: &[Option<FootprintTris>]) -> Vec<Option<ColumnGrid>> {
     footprints
         .iter()
@@ -280,7 +181,7 @@ pub fn footprint_tri_grids(footprints: &[Option<FootprintTris>]) -> Vec<Option<C
         .collect()
 }
 
-/// Per-group column indexes over a per-group triangle set — [`WmoModel::group_collision_grids`].
+/// Per-group column indexes over a per-group triangle set.
 pub fn collision_tri_grids(tris: &[Vec<[[f32; 3]; 3]>]) -> Vec<Option<ColumnGrid>> {
     tris.iter()
         .map(|group| {
@@ -301,9 +202,7 @@ pub fn collision_tri_grids(tris: &[Vec<[[f32; 3]; 3]>]) -> Vec<Option<ColumnGrid
         .collect()
 }
 
-/// The per-group AABBs of a per-group triangle set + their union — [`WmoModel::group_collision_bounds`]
-/// and [`WmoModel::collision_bounds`], derived from the faces at load (shared with the down-ray tests,
-/// so fixtures and the loader can never disagree on what the bounds mean).
+/// Per-group AABBs of a per-group triangle set, and their union; shared with the down-ray tests.
 #[allow(clippy::type_complexity)]
 pub fn collision_tri_bounds(
     tris: &[Vec<[[f32; 3]; 3]>],
@@ -343,10 +242,8 @@ pub fn collision_tri_bounds(
     (per_group, union)
 }
 
-/// The ambient-word CAP of `0x6a77e0` (exact fixed-point arithmetic, byte-verified — re-derived in
-/// wow-re `trace-forensics-abbey-interior-d3d` §1.1 and bit-exact against both decoded abbey stands):
-/// a colour whose max channel exceeds 96 is scaled down so max = 96 — per channel
-/// `(c·scale + 255) >> 8` with `scale = round(96·255/max − 0.5)`; max ≤ 96 passes through raw.
+/// The ambient cap of `0x6a77e0`, in its fixed point: a colour whose max channel exceeds 96 scales
+/// per channel to `(c·scale + 255) >> 8`, `scale = round(96·255/max − 0.5)`; otherwise it is raw.
 pub fn cap96(c: [u8; 3]) -> [f32; 3] {
     let max = c[0].max(c[1]).max(c[2]);
     if max <= 96 {
@@ -356,42 +253,30 @@ pub fn cap96(c: [u8; 3]) -> [f32; 3] {
     c.map(|v| ((u32::from(v) * scale + 255) >> 8) as f32 / 255.0)
 }
 
-/// The diffuse-word FLOOR of `0x6a77e0`: a colour whose max channel is below `thresh` is raised —
-/// HSV round-trip re-emitting at value `thresh`, which for an RGB triple is a hue/saturation-
-/// preserving scale by `thresh/max`, **truncated** per channel. The rounding was OPEN until the
-/// abbey INNBENCH decode exercised the raise leg live: bench MOCVs (59,65,92)/(69,63,83) raise to
-/// diffuse (107,118,168)/(139,127,168) — 63·(168/83) = 127.52 lands on 127, which truncation gives
-/// and nearest-rounding does not (wow-re `wmo-lit-selector.md`, machine-zero fits).
+/// The diffuse floor of `0x6a77e0`: a colour whose max channel is below `thresh` is raised by the
+/// reference's HSV round trip at value `thresh`, a scale by `thresh/max` truncated per channel.
 fn floor_raise(c: [u8; 3], thresh: u8) -> [f32; 3] {
     let max = c[0].max(c[1]).max(c[2]);
     if max >= thresh || max == 0 {
         return c.map(|v| f32::from(v) / 255.0);
     }
-    // Integer scale — truncating by construction AND exact on the max channel (a float
-    // `v · (thresh/max)` can land a hair under `thresh` and truncate to `thresh − 1`).
+    // Integer math: a float `v · (thresh/max)` can land under `thresh`, truncating to `thresh − 1`.
     c.map(|v| ((u32::from(v) * u32::from(thresh)) / u32::from(max)) as f32 / 255.0)
 }
 
-/// [`floor_raise`] at the MODD create site's diffuse threshold `0x70` (112). Max ≥ 112 passes
-/// through RAW — both decoded abbey stands do (maxes 134/141 → the diffuse word IS the MODD colour
-/// verbatim).
+/// [`floor_raise`] at the MODD create site's diffuse threshold `0x70` (112).
 pub fn floor112(c: [u8; 3]) -> [f32; 3] {
     floor_raise(c, 112)
 }
 
-/// [`floor_raise`] at the entity/footprint attach site's diffuse threshold `0xA8` (168) — the
-/// GameObject M2 lane (`0x69e4c0`, the entity twin of the ADT-MDDF `0x6a8410`; wow-re
-/// `wmo-lit-selector.md`). Both decoded abbey benches take the raise leg (MOCV maxes 92/83 →
-/// diffuse max exactly 168 on the wire).
+/// [`floor_raise`] at the GameObject footprint attach site's diffuse threshold `0xA8` (168),
+/// `0x69e4c0`, the entity twin of the ADT-MDDF attach at `0x6a8410`.
 pub fn floor168(c: [u8; 3]) -> [f32; 3] {
     floor_raise(c, 168)
 }
 
-/// Invert MODR: MODD index → its **instantiating** group. First referencing group wins — the
-/// reference creates a doodad once, on the first visible-group walk that names it, and that create
-/// is what fills its baked colour words. `None` = referenced by no group at all (the reference never
-/// instantiates such a MODD). This picks the interior lane's **MOLR light set**; the interior/exterior
-/// *class* is the whole referrer set's ([`resolve_doodad_bases`]), and the *cull* key is [`modr_refs`].
+/// MODD index to its first referencing group, whose MOLR set the interior lane uses. The reference
+/// creates a doodad on the first visible-group walk that names it, and never one no group names.
 fn modr_owners(doodad_count: usize, group_doodad_refs: &[Vec<u16>]) -> Vec<Option<u16>> {
     let mut owner: Vec<Option<u16>> = vec![None; doodad_count];
     for (gi, refs) in group_doodad_refs.iter().enumerate() {
@@ -404,13 +289,8 @@ fn modr_owners(doodad_count: usize, group_doodad_refs: &[Vec<u16>]) -> Vec<Optio
     owner
 }
 
-/// Invert MODR the other way: MODD index → **every** group whose refs name it. The draw loop is
-/// per *visible* group over that group's own MODR (`0x695aa0` from the visible-group walk
-/// `0x698720`), so a doodad named by N groups is reached by N independent chances to draw — it is
-/// on screen when ANY of them is in the portal PVS, not only its first. Collapsing this to the
-/// first owner is what made Blackrock's and the Great Forge's lava falls blink out by camera
-/// angle: `BLACKROCKSTATUELAVAFLOW` is named by 9–19 groups apiece and `LAVAPOTS` by 13, so all
-/// but one referrer's rooms hid a prop that the reference draws from every one of them.
+/// MODD index to every group whose MODR names it: the reference draws per visible group
+/// (`0x695aa0` from the walk at `0x698720`), so a prop shows while any of them is visible.
 fn modr_refs(doodad_count: usize, group_doodad_refs: &[Vec<u16>]) -> Vec<Arc<[u16]>> {
     let mut refs: Vec<Vec<u16>> = vec![Vec::new(); doodad_count];
     for (gi, group) in group_doodad_refs.iter().enumerate() {
@@ -426,27 +306,10 @@ fn modr_refs(doodad_count: usize, group_doodad_refs: &[Vec<u16>]) -> Vec<Arc<[u1
     refs.into_iter().map(Arc::from).collect()
 }
 
-/// Resolve every MODD placement's lighting base once, at load. Ownership follows the faithful
-/// create path: a doodad belongs to the group(s) whose **MODR** references it (the instantiate loop
-/// is per-group over MODR — never a spatial test), and the interior lane's point-light candidate
-/// set is its owning group's **MOLR** list. A MODD referenced by no group is never instantiated by
-/// the reference at all — Exterior here (the harmless default if our spawner shows it anyway).
-///
-/// **EXTERIOR WINS.** The class is *not* the first referrer's: the reference caches one
-/// `CMapDoodadDef` per (MODD index, **placement instance**) — `0x694e90` matches on
-/// `[def+0xb4] == modd` *and* `[def+0xc8] == [placement+0x7c]+1` — so every group of a placed
-/// building writes the lane of the *same* def, and the classify at `0x695aa0` makes exterior
-/// absorbing: an interior group refuses to mark a def already flagged exterior
-/// (`695ba0 test al,0x4; 695ba2 jne` → the exterior leg), while an exterior group **clears** the
-/// interior bit and sets its own (`695bbd and ecx,0xfffd; 695bc3 or ecx,0x4`). So a prop any
-/// exterior group names is sky-lit from the first frame that group is walked, and never goes back.
-/// Taking the first referrer instead pinned Booty Bay's entrance arch — named by g22 (interior) and
-/// g42 (exterior) — to the interior lane, whose whole base is the MODD colour: `#000000` there, i.e.
-/// a pure black silhouette at the town gate (decision 0969; `benilla-extract darkpropscan` is the
-/// corpus census).
-///
-/// `owner` is [`modr_owners`]' inversion and `refs` is [`modr_refs`]' — the latter shared with the
-/// portal-cull key ([`WmoModel::doodad_groups`]), so the lane and the cull read the same relation.
+/// Every MODD doodad's lighting base, from MODR ownership, never a spatial test; an unnamed MODD
+/// is Exterior. Exterior wins: the reference keeps one def per (MODD, placement) (`0x694e90`), and
+/// its classify (`0x695aa0`) never re-marks an exterior def interior while an exterior group
+/// clears the interior bit, so any exterior referrer makes the prop sky-lit.
 fn resolve_doodad_bases(
     doodads: &[WmoDoodad],
     groups: &[WmoGroupInfo],
@@ -466,7 +329,7 @@ fn resolve_doodad_bases(
             let Some(gi) = owner.get(di).copied().flatten() else {
                 return DoodadBase::Exterior;
             };
-            // Exterior is absorbing across the whole referrer set — not just the first referrer.
+            // Exterior is absorbing across the whole referrer set.
             let all_interior = refs
                 .get(di)
                 .is_some_and(|gs| !gs.is_empty() && gs.iter().all(interior_group));
@@ -486,7 +349,7 @@ fn resolve_doodad_bases(
         .collect()
 }
 
-/// Bevy [`AssetLoader`] decoding a WMO root `*.wmo` (+ its group files) → [`WmoModel`].
+/// Loads a WMO root and its group files into a [`WmoModel`].
 #[derive(Default, TypePath)]
 pub struct WmoModelLoader;
 
@@ -506,8 +369,7 @@ impl AssetLoader for WmoModelLoader {
         let to_io = |e: anyhow::Error| std::io::Error::other(format!("{e:#}"));
         let root = parse_wmo_root(&bytes).map_err(to_io)?;
 
-        // Root path → stem for the group files. Lowercased so the suffix strip + group URLs are
-        // consistent (MPQ resolution is case-insensitive regardless).
+        // Lowercased so the `.wmo` strip matches; MPQ lookup is case-insensitive anyway.
         let root_path = ctx.path().path().to_string_lossy().to_ascii_lowercase();
         let stem = root_path
             .strip_suffix(".wmo")
@@ -515,13 +377,9 @@ impl AssetLoader for WmoModelLoader {
             .to_string();
 
         let mut submeshes = Vec::new();
-        // Group index per submesh (parallel to `submeshes`) — the portal cull's handle on which group a
-        // render batch belongs to.
         let mut submesh_group: Vec<u16> = Vec::new();
-        // Per-group nav, pre-sized to the full group count and indexed by absolute group index so the
-        // MOPR `group` references line up even when a group file is skipped below. Bounds come from the
-        // root MOGI (available for every group); flags + portal-ref span are filled from each group
-        // header as it's read.
+        // Pre-sized to the group count so MOPR group indices line up when a group file is skipped;
+        // boxes from the root MOGI, the rest from each MOGP header.
         let mut group_nav: Vec<WmoGroupNav> = (0..root.group_count() as usize)
             .map(|gi| {
                 let (bbox_min, bbox_max) = root
@@ -542,24 +400,14 @@ impl AssetLoader for WmoModelLoader {
                 }
             })
             .collect();
-        // Per-group walking-collision triangles for the current-group down-ray, indexed by absolute
-        // group index (the flat collider below is fed from the same gather).
         let mut group_collision_tris: Vec<Vec<[[f32; 3]; 3]>> =
             vec![Vec::new(); root.group_count() as usize];
-        // Per-group camera-only triangles (DETAIL set, NOCAMCOLLIDE clear) — the down-ray's
-        // camera-void fallback set (decision 0692), disjoint from the walking gather above.
         let mut group_camera_only_tris: Vec<Vec<[[f32; 3]; 3]>> =
             vec![Vec::new(); root.group_count() as usize];
-        // Collidable triangles flattened across every group (raw WMO-local coords), accumulated as we
-        // read each group's bytes — no second pass / second read.
         let mut col_pos: Vec<[f32; 3]> = Vec::new();
         let mut col_idx: Vec<u32> = Vec::new();
-        // Camera/LOS gather (keeps DETAIL, drops NOCAMCOLLIDE) — a separate mesh from the walking one.
         let mut cam_pos: Vec<[f32; 3]> = Vec::new();
         let mut cam_idx: Vec<u32> = Vec::new();
-        // Per-group MODR (doodad ownership, transient — consumed into the doodad bases) + MOLR
-        // (light refs — kept on the asset: the GameObject footprint lane gates its point lobes by
-        // the hit group's list) + footprint face sets (interior groups only).
         let mut group_doodad_refs: Vec<Vec<u16>> = vec![Vec::new(); root.group_count() as usize];
         let mut group_light_refs: Vec<Vec<u16>> = vec![Vec::new(); root.group_count() as usize];
         let mut group_liquids: Vec<Option<LiquidMesh>> =
@@ -569,10 +417,8 @@ impl AssetLoader for WmoModelLoader {
         for gi in 0..root.group_count() {
             let group_url = format!("mpq://{stem}_{gi:03}.wmo");
             let Ok(gbytes) = ctx.read_asset_bytes(group_url).await else {
-                continue; // a missing/unreadable group is skipped, like the chain reader
+                continue; // a missing or unreadable group is skipped
             };
-            // Fill this group's flags + portal-ref span from its MOGP header (what the client's
-            // visibility pass reads). Bounds were seeded from MOGI above.
             if let (Some(h), Some(nav)) =
                 (wmo_group_header(&gbytes), group_nav.get_mut(gi as usize))
             {
@@ -583,8 +429,7 @@ impl AssetLoader for WmoModelLoader {
                 nav.fog_indices = h.fog_indices;
                 nav.group_liquid = h.group_liquid;
             }
-            // Walking gather once per group: the per-group down-ray face set AND the flat collider
-            // (appended with an index offset) come from the same buffers.
+            // One walking gather feeds both the per-group faces and the flat collider.
             let mut gpos: Vec<[f32; 3]> = Vec::new();
             let mut gidx: Vec<u32> = Vec::new();
             accumulate_wmo_group_collision(&gbytes, &mut gpos, &mut gidx);
@@ -603,8 +448,6 @@ impl AssetLoader for WmoModelLoader {
             col_pos.extend_from_slice(&gpos);
             col_idx.extend(gidx.iter().map(|i| i + base));
             accumulate_wmo_group_camera_collision(&gbytes, &mut cam_pos, &mut cam_idx);
-            // Camera-only gather (the walking gather's DETAIL complement) — kept per group for the
-            // down-ray's camera-void fallback (decision 0692).
             let (mut dpos, mut didx): (Vec<[f32; 3]>, Vec<u32>) = (Vec::new(), Vec::new());
             accumulate_wmo_group_camera_only_collision(&gbytes, &mut dpos, &mut didx);
             if let Some(tris) = group_camera_only_tris.get_mut(gi as usize) {
@@ -619,9 +462,7 @@ impl AssetLoader for WmoModelLoader {
                 }
             }
             let subs = wmo_group_submeshes(&gbytes, &root).map_err(to_io)?;
-            // This group's MODR (which MODD placements it owns/instantiates) + MOLR (which MOLT
-            // lights fold into its doodads' committed light) — the per-doodad base resolution below
-            // consumes both (wow-re trace-forensics-abbey-interior-d3d §1.1/§4).
+            // The reference walks MODR at `0x695aa0` and MOLR at `0x695c00`.
             if let Some(slot) = group_doodad_refs.get_mut(gi as usize) {
                 *slot = wmo_group_doodad_refs(&gbytes);
             }
@@ -635,14 +476,8 @@ impl AssetLoader for WmoModelLoader {
                 *slot = wmo_group_liquid_mesh(&gbytes);
             }
             for sub in subs {
-                // No meshes built here (decision 0834): a city root's ~thousands of group batches
-                // as labeled sub-assets landed in ONE frame — the geometry ships on the submesh
-                // and the app builds each batch's mesh paced (`benilla`'s `model_forms`).
-                //
-                // Lowercase the path: Bevy's loader lookup is case-sensitive and these tables carry
-                // uppercase `.BLP`, so an uppercase extension falls back to type-based resolution —
-                // ambiguous with Bevy's built-in image loader, which spams a "Multiple AssetLoaders
-                // found" warning per texture. Lowercasing matches `BlpImageLoader`'s `blp` + dedupes case.
+                // Lowercased: Bevy's loader lookup is case-sensitive, and an uppercase `.BLP` falls
+                // to type-based resolution, ambiguous with Bevy's own image loader.
                 let texture = sub.texture.as_deref().map(|t| {
                     ctx.load::<Image>(format!(
                         "mpq://{}",
@@ -651,41 +486,36 @@ impl AssetLoader for WmoModelLoader {
                 });
                 submeshes.push(ModelSubmesh {
                     texture,
-                    skin_slot: sub.skin_slot, // always None for WMO groups (no creature skins)
-                    geoset_id: 0,             // WMO has no M2 geoset concept
-                    char_slot: None,          // WMO is never a character body
-                    icon_slot: false,         // M2-only (texture type 14)
+                    skin_slot: sub.skin_slot,
+                    geoset_id: 0,
+                    char_slot: None,
+                    icon_slot: false,
                     blend: sub.blend,
                     two_sided: sub.two_sided,
                     interior: sub.interior,
                     emissive: sub.emissive,
-                    sidn: sub.sidn, // MOMT SIDN (0x10) — the authored night-glow colour
-                    window: sub.window, // MOMT WINDOW (0x20) — the interior midpoint light
-                    additive: sub.additive, // always false for WMO (additive WMO batches deferred)
-                    env_map: false, // M2-only (the WMO env/specular overlay is a separate path)
-                    no_depth_write: false, // WMO uses the standard opaque/transparent depth state
+                    sidn: sub.sidn, // MOMT SIDN (0x10): the authored night-glow colour
+                    window: sub.window, // MOMT WINDOW (0x20): the interior midpoint light
+                    additive: sub.additive,
+                    env_map: false,
+                    no_depth_write: false,
                     no_depth_test: false,
-                    fog_policy: sub.fog_policy, // always Scene for WMO (remap_submesh's default)
-                    billboard: None,            // WMO geometry isn't billboarded
-                    alpha_anim: None,           // WMO batches carry no M2 colour/weight tracks
-                    uv_anim: None,              // …nor texture transforms
-                    uv_seq: None,               // …so no per-sequence set either (1408)
+                    fog_policy: sub.fog_policy,
+                    billboard: None,
+                    alpha_anim: None,
+                    uv_anim: None,
+                    uv_seq: None,
                     uv_rot_seq: None,
                     uv_scale_seq: None,
                     rgb_anim: None,
-                    rgb_seq: None,            // …nor M2Color tints
-                    wmo_batch: sub.wmo_batch, // the MOBA section — an interior group's lighting law
-                    ground_quad: None,        // the fx decal lane is M2-only
+                    rgb_seq: None,
+                    wmo_batch: sub.wmo_batch, // the MOBA section: an interior group's lighting
+                    ground_quad: None,
                     geometry: std::sync::Arc::new(sub),
                 });
                 submesh_group.push(gi as u16);
             }
         }
-        // Resolve every MODD placement's base once — placements, colours, MODR ownership, and MOLR
-        // light lists are all fixed in the root/groups, so nothing here is ever re-derived. Both
-        // MODR inversions come off the same refs: the first-owner one names the MOLR set the
-        // interior fold gates on, the full-set one is both the per-visible-group cull key and the
-        // exterior-wins lane test.
         let doodad_owner = modr_owners(root.doodads().len(), &group_doodad_refs);
         let doodad_groups = modr_refs(root.doodads().len(), &group_doodad_refs);
         let doodad_base = resolve_doodad_bases(
@@ -750,21 +580,11 @@ impl AssetLoader for WmoModelLoader {
     }
 }
 
-/// Apply the MLIQ **shared-tile gate** across a model's groups: a cell flagged `0x80`
-/// ([`LiquidMesh::shared`]) is claimed by TWO groups and authored in both, and exactly one of them
-/// may draw it. Both drawing means the translucent sheet composites twice over the overlap band —
-/// the visible line along the Stormwind canals (B141's water half).
-///
-/// The reference picks the winner by 2-colouring the portal graph on the depth parity of the flood
-/// that reached each group, recomputed every frame (`0x6b41c0`/`0x6b4074`/`0x6b61a0`, wow-re
-/// `terrain/scratch/wmo-liquid-shared-tile-gate.md`). We pick **the lowest group index**, which is
-/// pixel-identical and needs no flood: the RE measured all 415 corners of Stormwind's 190 shared
-/// cells and the two claimants agree exactly — the same per-vertex alpha byte (415/415) and heights
-/// within 5e-6 yd. Which one draws cannot be seen; that two draw can.
-///
-/// Cells are matched on their XY centre quantised to a hundredth of a yard — the two authors share
-/// the same MLIQ lattice, so the coordinates agree to float exactness and the quantisation is only
-/// there to make them hashable.
+/// The MLIQ shared-cell gate: a cell flagged `0x80` ([`LiquidMesh::shared`]) is authored in two
+/// groups and only one may draw it, or the sheet composites twice. The reference picks the drawer
+/// by the portal flood's depth parity each frame (`0x6b41c0`, `0x6b4074`, `0x6b61a0`); the lowest
+/// group index draws the same pixels, as both claimants carry the same alpha and heights. Cells
+/// match on their XY centre, quantised to 0.01 yd only to hash.
 fn resolve_shared_liquid_cells(group_liquids: &mut [Option<LiquidMesh>]) {
     let key = |m: &LiquidMesh, c: usize| -> Option<(i32, i32)> {
         let (cols, rows) = (m.grid[0] as usize, m.grid[1] as usize);
@@ -832,50 +652,35 @@ mod doodad_base_tests {
         }
     }
 
-    /// GOLDEN — the two abbey stands the reference trace decoded (wow-re
-    /// `trace-forensics-abbey-interior-d3d` §1): MODD[18] colour (78,76,134) → ambient (56,55,96)
-    /// diffuse raw; MODD[24] colour (90,86,141) → ambient (61,59,96) diffuse raw. Both bit-exact
-    /// through the `0x6a77e0` fixed-point cap (scales 182 and 173).
+    /// Northshire Abbey's candle stands MODD[18] and MODD[24], as the reference commits them
+    /// through `0x6a77e0` (cap scales 182 and 173).
     #[test]
     fn cap96_matches_the_decoded_abbey_stands_bit_exact() {
         let as_bytes = |c: [f32; 3]| c.map(|v| (v * 255.0).round() as u8);
         assert_eq!(as_bytes(cap96([78, 76, 134])), [56, 55, 96]);
         assert_eq!(as_bytes(cap96([90, 86, 141])), [61, 59, 96]);
-        // max ≤ 96 passes through raw.
         assert_eq!(as_bytes(cap96([96, 40, 20])), [96, 40, 20]);
-        // The diffuse floor: max ≥ 112 is RAW (both stands), below 112 raises hue-preserving.
         assert_eq!(as_bytes(floor112([78, 76, 134])), [78, 76, 134]);
         assert_eq!(as_bytes(floor112([90, 86, 141])), [90, 86, 141]);
         let raised = as_bytes(floor112([56, 28, 14]));
-        assert_eq!(raised[0], 112); // max channel lands on the 112 value
-        assert_eq!(raised, [112, 56, 28]); // pure scale — hue/saturation preserved
-                                           // Black stays black — and that IS the reference, not just our divide-by-zero guard. The
-                                           // raise re-emits through HSV, and `RGBtoHSV(0,0,0)` gives S=0/H=−1 (`7bbcb5`/`7bbccd`) so
-                                           // `HSVtoRGB` would return the grey `(V,V,V)` (`7bbd76`) — but the caller SCALES the value
-                                           // rather than setting it (`6a78a5 fild thresh · 6a78ab fidiv max · 6a78b1 fmul V`), and
-                                           // `V·thresh/max` is 0 when V is. `6a780e cmp dl,1 / 6a7813 mov bl,1` forces max to 1 only
-                                           // to keep that `fidiv` finite. So a zero-colour interior prop commits black in the real
-                                           // client too, and the black Booty Bay arch was a LANE bug, never this (decision 0969).
+        assert_eq!(raised[0], 112);
+        assert_eq!(raised, [112, 56, 28]);
+        // Black stays black in the reference too: it scales the HSV value by `thresh/max`
+        // (`0x6a78a5`) and forces max to 1 only to keep that divide finite (`0x6a780e`).
         assert_eq!(as_bytes(floor112([0, 0, 0])), [0, 0, 0]);
     }
 
     #[test]
     fn floor168_matches_the_decoded_abbey_benches_bit_exact() {
-        // wow-re `wmo-lit-selector.md`: the INNBENCH GameObject draws (14150796/14150859) decode to
-        // ambient = the raw MOCV (max ≤ 96 → cap96 pass-through) and diffuse = floor168(MOCV) with
-        // TRUNCATING rounding — 63·168/83 = 127.52 lands on 127 (nearest would give 128).
+        // The abbey inn benches as the reference commits them; 63·168/83 = 127.52 truncates to 127.
         let as_bytes = |c: [f32; 3]| c.map(|v| (v * 255.0).round() as u8);
         assert_eq!(as_bytes(cap96([59, 65, 92])), [59, 65, 92]);
         assert_eq!(as_bytes(cap96([69, 63, 83])), [69, 63, 83]);
         assert_eq!(as_bytes(floor168([59, 65, 92])), [107, 118, 168]);
         assert_eq!(as_bytes(floor168([69, 63, 83])), [139, 127, 168]);
-        // max ≥ 168 passes through raw.
         assert_eq!(as_bytes(floor168([200, 30, 10])), [200, 30, 10]);
     }
 
-    /// Ownership is MODR, never spatial: an interior-group doodad takes its MODD colour (cap96
-    /// ambient / floor112 diffuse) + its OWNING group's MOLR; an exterior-group doodad is sky-lit;
-    /// an unreferenced MODD (never instantiated by the reference) defaults exterior.
     #[test]
     fn modr_ownership_picks_the_lane_and_the_light_refs() {
         let doodads = vec![
@@ -888,8 +693,6 @@ mod doodad_base_tests {
         let molr = vec![vec![7u16, 9u16], vec![3u16]];
         let owner = modr_owners(doodads.len(), &modr);
         let refs = modr_refs(doodads.len(), &modr);
-        // The same inversion the portal cull keys props on (decision 0689): owned props name their
-        // group, the unreferenced one names none — so it is the one prop the cull can't hide.
         assert_eq!(owner, vec![Some(0), Some(1), None]);
         let bases = resolve_doodad_bases(&doodads, &groups, &owner, &refs, &molr);
         match &bases[0] {
@@ -904,12 +707,6 @@ mod doodad_base_tests {
         assert_eq!(bases[2], DoodadBase::Exterior);
     }
 
-    /// EXTERIOR WINS over every interior referrer, whatever the MODR order — the reference's def is
-    /// per (MODD, placement) and its classify makes the exterior bit absorbing (`0x695aa0`:
-    /// `695ba2 jne` refuses to re-mark interior, `695bbd/695bc3` clears interior and sets exterior).
-    /// Booty Bay's entrance arch is the live case: g22 (interior) names it FIRST and g42 (exterior)
-    /// second, its MODD colour is `#000000`, and first-referrer-wins therefore drew it as a pure
-    /// black silhouette at the town gate (decision 0969).
     #[test]
     fn one_exterior_referrer_makes_the_whole_prop_exterior() {
         let doodads = vec![
@@ -934,9 +731,6 @@ mod doodad_base_tests {
             "the exterior referrer wins even though an interior group names it first"
         );
         match &bases[1] {
-            // Interior-only: the lane still applies, and a zero MODD colour still commits black —
-            // the reference's own arithmetic (`0x6a77e0` forces max=1 only to dodge the divide, so
-            // the HSV raise re-emits value 0·112/1 = 0). Only its MOLR fixtures can light it.
             DoodadBase::Interior(b) => {
                 assert_eq!(b.ambient, [0.0; 3]);
                 assert_eq!(b.diffuse, [0.0; 3]);
@@ -946,13 +740,8 @@ mod doodad_base_tests {
         }
     }
 
-    /// GOLDEN, on the shipped asset that produced the report: Booty Bay's entrance arch
-    /// (`BootyBay.wmo` MODD[3], `BootyBayEntrance_02`, MODF uid 118213 at world
-    /// (-14258.29, 330.26, 44.00)) resolves **Exterior**. Its MODR referrers are g22 (interior,
-    /// first) and g42 (exterior), and its MODD colour is `#000000` — so first-referrer-wins put it
-    /// on the interior lane with an all-zero base and drew it as a pure black silhouette over the
-    /// town gate. This reads the real root + group files through the same inversions the loader
-    /// calls, so it fails the moment the lane law regresses (decision 0969).
+    /// Booty Bay's entrance arch, `BootyBay.wmo` MODD[3], named first by interior g22 and also by
+    /// exterior g42, with a black MODD colour.
     #[test]
     fn booty_bays_entrance_arch_is_sky_lit_not_a_black_silhouette() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -1012,9 +801,8 @@ mod doodad_base_tests {
         );
     }
 
-    /// A group with NO MOLR chunk gives its doodads an EMPTY light set — the abbey's group 3 case:
-    /// the director's stand receives zero point light, its own flame included (machine-zero in the
-    /// reference decode).
+    /// Northshire Abbey's group 3 has no MOLR, and its candle stand takes no point light in the
+    /// reference, its own flame included.
     #[test]
     fn no_molr_means_no_point_lights_at_all() {
         let bases = resolve_doodad_bases(
@@ -1030,30 +818,21 @@ mod doodad_base_tests {
         }
     }
 
-    /// A MODD named by several groups resolves to its **first** referencing group, and the mapping is
-    /// dense over the doodad list — the interior fold's MOLR set keys off this (the create that fills
-    /// the baked words runs once, on the first visible-group walk to reach it). Out-of-range MODR
-    /// entries (a malformed group) are ignored rather than panicking.
     #[test]
     fn a_shared_modd_takes_its_first_referencing_groups_molr() {
-        // g0 names doodad 2; g1 names 0 and 2; g2 names 1 — plus a ref past the end of the list.
+        // g0 names doodad 2; g1 names 0 and 2; g2 names 1, plus a ref past the end of the list.
         let modr = vec![vec![2u16], vec![0u16, 2u16], vec![1u16, 99u16]];
         assert_eq!(
             modr_owners(3, &modr),
             vec![Some(1), Some(2), Some(0)],
             "doodad 2 is named by g0 and g1 — g0 wins"
         );
-        // No groups at all ⇒ nothing is owned, and nothing is cullable.
         assert_eq!(modr_owners(2, &[]), vec![None, None]);
     }
 
-    /// The CULL key is the whole referrer set, not the first: the draw loop runs per *visible* group
-    /// over that group's MODR, so a prop several rooms name is drawn from every one of them. Keying
-    /// it to the first owner instead is what blinked Blackrock's and the Great Forge's lava falls
-    /// out by camera angle — real files name those props from 9–19 groups apiece.
     #[test]
     fn the_cull_key_is_every_referencing_group() {
-        // Same fixture as above: g0 names 2; g1 names 0 and 2; g2 names 1 + an out-of-range ref.
+        // The fixture above: g0 names 2; g1 names 0 and 2; g2 names 1 and an out-of-range ref.
         let modr = vec![vec![2u16], vec![0u16, 2u16], vec![1u16, 99u16]];
         let refs = modr_refs(3, &modr);
         assert_eq!(&*refs[0], &[1], "doodad 0 is named by g1 alone");
@@ -1063,8 +842,7 @@ mod doodad_base_tests {
             &[0, 1],
             "doodad 2 hangs in two rooms — either one draws it"
         );
-        // A group naming the same doodad twice contributes it once; no groups ⇒ no key at all (the
-        // prop is uncullable, matching `modr_owners`' `None`).
+        // A doodad named twice by one group counts once.
         assert_eq!(&*modr_refs(1, &[vec![0u16, 0u16]])[0], &[0]);
         assert!(modr_refs(2, &[])[0].is_empty());
     }
diff --git a/crates/benilla-assets/src/world_assets/images.rs b/crates/benilla-assets/src/world_assets/images.rs
index 3c496364..4ca61b1b 100644
--- a/crates/benilla-assets/src/world_assets/images.rs
+++ b/crates/benilla-assets/src/world_assets/images.rs
@@ -1,6 +1,5 @@
-//! Texture/image helpers: turn decoded BLP mip chains + raw RGBA into Bevy `Image`s (correct format,
-//! sampler, mip layout) plus the small solid-colour / cursor / liquid-frame textures. Pure helpers the
-//! asset foundation (`super`) and other subsystems call. Split out of `assets/mod.rs`.
+//! Image helpers: BLP mip chains and raw RGBA into Bevy `Image`s (format, sampler, mip layout),
+//! for world art, liquid frames, sprites, masks and the cursor.
 
 use bevy::asset::RenderAssetUsages;
 use bevy::image::{Image, ImageAddressMode, ImageFilterMode, ImageSampler, ImageSamplerDescriptor};
@@ -11,28 +10,13 @@ use bevy::render::render_resource::{
 
 use benilla_formats::BlpMipChain;
 
-/// Build a full mip chain for an RGBA texture (mip 0 = `mip0`), halving each level to 1×1 with a
-/// triangle (box-ish) downsample. Returns the concatenated mip data + the level count. For a single
-/// layer this is the `LayerMajor`/`MipMajor`-agnostic order (mip0, mip1, …).
-/// Color (albedo) texture format: **non-sRGB `Rgba8Unorm`**, so the GPU does NOT linearize albedo on
-/// sample. Vanilla's fixed-function pipeline multiplied gamma (sRGB) texture bytes by gamma light
-/// bytes in **gamma/byte space**; loading albedo as `…Unorm` keeps our shader math in that same space.
-/// This is the RE'd faithful **invariant** (no sRGB↔linear round-trip anywhere). Used for model +
-/// terrain albedo.
+/// Albedo format, non-sRGB: the reference multiplies gamma texture bytes by gamma light bytes.
 pub fn color_texture_format() -> TextureFormat {
     TextureFormat::Rgba8Unorm
 }
 
-/// A repeating, **mipmapped + anisotropically-filtered** texture built from the BLP's **authored**
-/// mip pyramid — the levels the real 1.12 client uploads verbatim (`WoW.exe` has no GLU /
-/// `glGenerateMipmap`; it cannot regenerate mips, only upload the stored ones). Using the authored
-/// levels instead of CPU-resampling mip 0 with a box/Triangle filter in gamma byte space is the
-/// model-side of the C2 fix: gamma-byte averaging darkens mid-tones and, on alpha-cutout foliage,
-/// skews the leaf colour cool (it averages the dark *transparent* texels' RGB into the leaves, 5–18
-/// LSB darker in R/G) and drifts coverage with distance. The authored mips already encode WoW's
-/// coverage-correct, leaf-coloured downsample, so we lay them in as-is under the alpha test — no
-/// re-filter, no alpha-to-coverage (1.12 does neither). Mips + anisotropy give the no-shimmer look
-/// at distance without softening the up-close art.
+/// World or model albedo from the BLP's authored mips as stored: the 1.12 client has no GLU or
+/// `glGenerateMipmap`, and does no re-filter or alpha-to-coverage.
 pub fn repeat_texture_authored(upload: crate::gpu_blp::UploadChain, wrap: (bool, bool)) -> Image {
     let crate::gpu_blp::UploadChain { chain, format } = upload;
     let levels = chain.mips.len() as u32;
@@ -40,9 +24,6 @@ pub fn repeat_texture_authored(upload: crate::gpu_blp::UploadChain, wrap: (bool,
     for mip in &chain.mips {
         data.extend_from_slice(mip);
     }
-    // Taking an `UploadChain` rather than a bare chain is deliberate: the format and the bytes are
-    // decided together by `gpu_blp::for_upload`, so this function cannot be handed blocks under an
-    // uncompressed descriptor. It was, once — see `UploadChain`'s doc (decision 1626).
     let mut image = Image::new_uninit(
         Extent3d {
             width: chain.width,
@@ -51,22 +32,14 @@ pub fn repeat_texture_authored(upload: crate::gpu_blp::UploadChain, wrap: (bool,
         },
         TextureDimension::D2,
         format,
-        // `RENDER_WORLD` — see [`image_gpu_bytes`] and the `blp.rs` `WorldArt` variant this is the
-        // synchronous twin of: the render world takes the chain rather than cloning it and keeping
-        // a main-world copy. Its callers are `WorldAssets::texture` and the character-skin
-        // composite, and neither reads the result back; a composite is built CPU-side and handed
-        // over whole.
+        // The synchronous twin of `blp.rs`'s `WorldArt` lane: the render world takes the chain, and
+        // neither caller (`WorldAssets::texture`, the character-skin composite) reads it back.
         RenderAssetUsages::RENDER_WORLD,
     );
     image.data = Some(data);
     image.texture_descriptor.mip_level_count = levels;
-    // The address mode is the M2 texture record's own (`flags & 0x1/0x2`), not a blanket Repeat.
-    // On a cutout sheet it decides the SILHOUETTE: content authors a card's UVs past `0..1` so the
-    // margin clamps to the transparent border and the card ends there — repeat instead folds that
-    // margin into the opposite edge, drawing the sheet's opaque middle as solid geometry with a hard
-    // seam at the crossing. 1250 batches across 775 models author clamp and sample outside the unit
-    // square (`benilla-extract uvwrapscan`); 802 are cutout/blend, where it changes shape and not
-    // merely colour. Decision 0763 (bugs B52/B96 — Dun Morogh's snow-firs, the Plaguelands bush).
+    // The M2 texture record's own address mode (`flags & 0x1/0x2`): a cutout card authors UVs
+    // past `0..1` to clamp onto its transparent border, where repeat folds its opaque middle in.
     let mode = |repeat: bool| {
         if repeat {
             ImageAddressMode::Repeat
@@ -74,10 +47,7 @@ pub fn repeat_texture_authored(upload: crate::gpu_blp::UploadChain, wrap: (bool,
             ImageAddressMode::ClampToEdge
         }
     };
-    // The reference forces the mip filter and the anisotropy from two process globals at every
-    // `TextureCreate`, and a virgin install lands on trilinear with anisotropy OFF
-    // ([`crate::tex_filter`]). This read `Linear` / `8` — mode 5 — under the comment "the vanilla
-    // look", which was the look of an install with `SET anisotropic "16"` in its `Config.wtf`.
+    // M2, WMO and character textures take the process filter policy (`0x449ae0`, applyGlobal 1).
     let filter = crate::tex_filter::tex_filter();
     image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
         address_mode_u: mode(wrap.0),
@@ -91,42 +61,21 @@ pub fn repeat_texture_authored(upload: crate::gpu_blp::UploadChain, wrap: (bool,
     image
 }
 
-/// `WOW_LIQUID_DC=raw` restores the shipped frames' own per-frame DC — the A/B lever for
-/// [`flatten_frame_dc`] while the fidelity question behind it is open (see that function).
+/// `WOW_LIQUID_DC=raw` keeps the shipped frames' own DC, the A/B lever for [`flatten_frame_dc`].
 fn dc_normalization_enabled() -> bool {
     std::env::var("WOW_LIQUID_DC").as_deref() != Ok("raw")
 }
 
-/// Flatten each frame's **DC** (per level, per channel) onto the loop's mean — the fix for the
-/// water sheet breathing once per animation loop.
+/// Shift each frame's DC (per level, per channel) onto the loop's mean.
 ///
-/// The shipped ocean frames do not share a mean. Across `ocean_h`'s 30-frame loop the full-texture
-/// mean alpha runs 55.985..57.628, and DXT3's 4-bit alpha quantisation makes the small levels drift
-/// harder still: measured swing is 1.64 at mip 0, 3.72 at mip 5 and 6.38 at mip 6. Near the camera
-/// that is invisible, because each pixel lands on a different texel and the variation scatters as
-/// ripple shimmer. At distance mipping averages the whole level into one value, so every pixel of
-/// the far sheet moves *together* and the surface visibly brightens and dims once per loop —
-/// 1.25 s at the 24 fps flip. Director-reported at Ratchet (2026-09-06); measured off their capture
-/// at 0.8..1.84/255 with an autocorrelation period of exactly 1.250 s, and confirmed coherent
-/// rather than noise (a 0.82/255 swing in a 104k-pixel mean cannot come from per-pixel scatter).
-/// It reads as a flicker only at a high `farclip` — at 300 that band is fogged out or past the
-/// wall, which is why the report came with "not visible at 300".
-///
-/// The correction is a per-level **additive** offset, not a gain: the drift is a DC shift, and an
-/// offset removes it without touching the ripple's contrast — where a multiplicative fit would
-/// scale the crests (alpha reaches 255) and clip them. Applied per channel because both terms of
-/// the ADT combine carry the drift (`detail.rgb`, and `detail.a` through the sheen factor).
-///
-/// **Water/ocean only.** Magma and slime take the animated sheet as their opaque BODY colour, where
-/// a per-frame brightness swing is the intended pulse, so the caller passes `false` for the
-/// fullbright kinds and their DC is left alone.
-///
-/// **This is a deliberate divergence from the shipped art**, pending the RE round on whether the
-/// reference shows the same breathing (it uploads the same authored, same-quantised mips, so it
-/// plausibly does). `WOW_LIQUID_DC=raw` restores the frames verbatim for the A/B.
+/// Deviation: the reference uploads the shipped frames as they are; this evens them because their
+/// means differ (`ocean_h` alpha 55.985..57.628 over its 30 frames, more down the DXT3 mips), and
+/// at distance, where mipping averages a level to one value, the far sheet brightens and dims once
+/// per 1.25 s loop. An additive offset leaves the ripple's crests unscaled; per channel, since
+/// `detail.rgb` and `detail.a` both drift. Water only: magma and slime keep their pulse.
 fn flatten_frame_dc(data: &mut [u8], spans: &[Vec<(usize, usize)>], levels: usize) {
     for level in 0..levels {
-        // The loop's target sum-per-texel for this level, over every frame.
+        // The loop's target sum per texel for this level, over every frame.
         let mut sums = [0i64; 4];
         let mut texels = 0usize;
         for frame in spans {
@@ -160,11 +109,9 @@ fn flatten_frame_dc(data: &mut [u8], spans: &[Vec<(usize, usize)>], levels: usiz
                 if delta == 0 {
                     continue;
                 }
-                // Spend the delta in ±1 steps, walking the level on a stride coprime with its
-                // texel count so the touched texels scatter instead of forming a patch at the
-                // start. Repeated passes each add at most 1 LSB per texel, so a large correction
-                // stays a faint uniform lift rather than a few blown texels; texels already at the
-                // 0/255 rail are skipped, and a pass that moves nothing ends the walk.
+                // Spend the delta in ±1 steps on a stride coprime with the texel count, so the
+                // touched texels scatter and each pass adds at most 1 LSB per texel; railed texels
+                // are skipped, and a pass that moves nothing ends the walk.
                 let stride = if n % 7 == 0 { 1 } else { 7 };
                 let mut progress = true;
                 while delta != 0 && progress {
@@ -190,18 +137,12 @@ fn flatten_frame_dc(data: &mut [u8], spans: &[Vec<(usize, usize)>], levels: usiz
     }
 }
 
-/// Stack the animated liquid frames into one **mipmapped + anisotropic** `texture_2d_array` from each
-/// frame's BLP **authored** mip pyramid — same fidelity rule as [`repeat_texture_authored`]: the real
-/// 1.12 client uploads the BLP's stored mips verbatim (no client-side regeneration). Without mips, the
-/// 256² ripple tiled over ~16 yd aliases into dense sparkle "noise" at distance; the authored mips +
-/// anisotropy give the reference's smooth, streaky wave highlights instead. Data is laid out
-/// **LayerMajor** (`frame0[mip0..mipN], frame1[mip0..], …`, the wgpu/Bevy default) with a full
-/// `size→1` chain; a frame whose authored chain is shorter/odd is filled by `NEAREST` from its nearest
-/// authored level (gamma-safe, no averaging — mirrors [`chain_to_layer`]). All frames must share mip-0
-/// `size` (the caller enforces this). Returns a `D2Array`-viewed image with `mip_level_count` set.
+/// The animated liquid frames stacked layer-major into one `texture_2d_array` from their authored
+/// mips, a full chain to 1×1; a level a frame lacks is filled `NEAREST` from its nearest authored
+/// level, so no gamma averaging. Every frame shares mip 0's `size` (the caller enforces it).
 pub fn liquid_frame_array(frames: Vec<BlpMipChain>, normalize_dc: bool) -> Image {
     let size = frames[0].width;
-    // Full mip chain down to 1×1 (square 1.12 frames): levels = log2(size) + 1.
+    // Square 1.12 frames: levels = log2(size) + 1.
     let mip_level_count = {
         let (mut n, mut s) = (1u32, size);
         while s > 1 {
@@ -211,15 +152,13 @@ pub fn liquid_frame_array(frames: Vec<BlpMipChain>, normalize_dc: bool) -> Image
         n
     };
     let mut data = Vec::with_capacity(frames.len() * mip_chain_byte_size(size, mip_level_count));
-    // Where each (frame, level) region landed, so the DC pass below can address one level of one
-    // frame without re-deriving the LayerMajor arithmetic.
+    // Where each (frame, level) region landed, for the DC pass.
     let mut spans: Vec<Vec<(usize, usize)>> = Vec::with_capacity(frames.len());
     for blp in &frames {
         let mut per_level = Vec::with_capacity(mip_level_count as usize);
         for level in 0..mip_level_count {
             let lw = (size >> level).max(1);
-            // Match the array level to the authored mip of the same size (normally identity — water
-            // frames carry a full chain); fall back to the nearest authored level via NEAREST.
+            // The authored mip of this size (water frames carry a full chain), else the nearest.
             let src_level = if blp.width >= lw {
                 let ratio = (blp.width / lw).max(1);
                 (ratio.trailing_zeros() as usize).min(blp.mips.len() - 1)
@@ -244,10 +183,7 @@ pub fn liquid_frame_array(frames: Vec<BlpMipChain>, normalize_dc: bool) -> Image
         },
         TextureDimension::D2,
         color_texture_format(),
-        // `RENDER_WORLD`: 136 frames of a 256² nine-level RGBA8 pyramid is 47,535,264 B (the figure
-        // `gpu_bytes_count_every_array_layer` pins), built at `Startup` and resident for the whole
-        // process. The default usage held that twice — once on the GPU and once in system RAM,
-        // which nothing ever read.
+        // 47,535,264 B resident for the whole process, never read main-side.
         RenderAssetUsages::RENDER_WORLD,
     );
     image.data = Some(data);
@@ -256,14 +192,7 @@ pub fn liquid_frame_array(frames: Vec<BlpMipChain>, normalize_dc: bool) -> Image
         dimension: Some(TextureViewDimension::D2Array),
         ..default()
     });
-    // **The apitrace that pinned this was read one step too far.** WoW.20 showed the ripple
-    // sampler at LINEAR_MIPMAP_LINEAR + MAX_ANISOTROPY 16 and it was recorded here as "VERIFIED
-    // the reference ripple sampler" — but that capture came off the repo's reference install,
-    // whose `Config.wtf` carries `SET anisotropic "16"`. It proves the *mechanism* (the global
-    // reaches the liquid sampler like every other), not the *default*, which is aniso off. There
-    // is no per-texture filter override anywhere in the reference, so water takes the same policy
-    // as ground ([`crate::tex_filter`]) — and at `anisotropic 16` this lane is byte-identical to
-    // what it was.
+    // The liquid sheets take the process filter policy (`0x68abab`, applyGlobal 1), as ground does.
     let filter = crate::tex_filter::tex_filter();
     image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
         address_mode_u: ImageAddressMode::Repeat,
@@ -277,9 +206,7 @@ pub fn liquid_frame_array(frames: Vec<BlpMipChain>, normalize_dc: bool) -> Image
     image
 }
 
-/// A single-mip RGBA8 image for winit's custom OS cursor (`CursorIcon::Custom`). Vanilla cursors are
-/// tiny (`Point.blp` is 32×32), so unlike [`repeat_texture`] this needs neither a mip chain nor a
-/// repeat sampler. macOS doesn't use this path (it builds an `NSCursor` directly — see `crate::cursor`).
+/// A single-mip sRGB image for winit's custom OS cursor; macOS builds an `NSCursor` instead.
 #[cfg(not(target_os = "macos"))]
 pub fn cursor_texture(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     Image::new(
@@ -295,10 +222,8 @@ pub fn cursor_texture(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     )
 }
 
-/// A single-mip, **sRGB**, clamp-sampled image for an emissive celestial billboard (the sun/moon
-/// discs — see [`WorldAssets::sprite_texture`]). sRGB so an unlit pass round-trips the authored gamma
-/// bytes to screen; clamp-to-edge + linear (no repeat, no mips) since the whole texture maps to one
-/// quad and the disc never tiles or minifies far.
+/// A single-mip sRGB sprite, clamped and linear, for the celestial discs and the UI: sRGB so an
+/// unlit pass returns the authored gamma bytes to screen.
 pub fn sprite_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     let mut image = Image::new(
         Extent3d {
@@ -321,12 +246,8 @@ pub fn sprite_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     image
 }
 
-/// A coverage **mask** image (the minimap's `MinimapMask.blp`, decision 0203): identical sampling
-/// to [`sprite_image`] (clamp, linear filtering, no mips) but uploaded **`Rgba8Unorm`** (not
-/// sRGB) — the shader reads coverage, not color, so no gamma decode belongs anywhere in the path.
-/// The coverage itself rides the ALPHA channel (`MinimapMask.blp` is DXT3: white color plane, the
-/// circle ramp authored in its 8-bit alpha; alpha is gamma-free in either format, but the linear
-/// upload keeps the color plane byte-exact too, and documents the intent).
+/// A coverage mask (the minimap's `MinimapMask.blp`, its circle ramp in the alpha): sampled like
+/// [`sprite_image`] but uploaded `Rgba8Unorm`, since the shader reads coverage, not colour.
 pub fn mask_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     let mut image = Image::new(
         Extent3d {
@@ -349,12 +270,8 @@ pub fn mask_image(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     image
 }
 
-/// A portrait sprite: [`sprite_image`] with the RGBA pre-masked to its **inscribed circle** — the
-/// alpha of every texel outside the largest centred circle is zeroed (with a 1px anti-aliased edge),
-/// so a square icon or model reads as the round portrait the unit-frame ring expects. The ring in
-/// `UI-TargetingFrame` is a thin band with transparent corners; without the mask the square texture's
-/// corners poke past it (the placeholder `INV_Misc_QuestionMark` even bakes a grey border, so its
-/// corners read as metal brackets). Same sRGB/clamp/linear/no-mip setup as [`sprite_image`].
+/// A portrait: [`sprite_image`] with alpha zeroed outside the inscribed circle (1 px anti-aliased),
+/// so square art does not poke past the unit frame's round ring (`UI-TargetingFrame`).
 pub fn portrait_image(width: u32, height: u32, mut rgba: Vec<u8>) -> Image {
     if width > 0 && height > 0 && rgba.len() == (width * height * 4) as usize {
         let (cx, cy) = (width as f32 / 2.0, height as f32 / 2.0);
@@ -364,7 +281,6 @@ pub fn portrait_image(width: u32, height: u32, mut rgba: Vec<u8>) -> Image {
                 let dx = x as f32 + 0.5 - cx;
                 let dy = y as f32 + 0.5 - cy;
                 let dist = (dx * dx + dy * dy).sqrt();
-                // Coverage: 1 well inside, 0 well outside, a 1px linear ramp across the edge.
                 let coverage = (radius - dist).clamp(0.0, 1.0);
                 let a = ((y * width + x) * 4 + 3) as usize;
                 rgba[a] = (f32::from(rgba[a]) * coverage).round() as u8;
@@ -374,33 +290,18 @@ pub fn portrait_image(width: u32, height: u32, mut rgba: Vec<u8>) -> Image {
     sprite_image(width, height, rgba)
 }
 
-/// A single-mip, **sRGB**, **repeat**-sampled image for a frame `Backdrop`'s tiled pieces (the
-/// tooltip/panel border edges + a tiling background — `backdrop-mechanism.md` §2/§3). Identical to
-/// [`sprite_image`] except the address mode is `Repeat`: a backdrop edge strip runs UVs `[0..N]`
-/// (N = the edge count = frame-side / edgeSize − 2) and a tiled bg runs `[0..w/period]`, so the
-/// slice must *wrap*, not clamp-stretch. The real client flags exactly this on the backdrop's
-/// `SetTexture` (arg2 pushed twice into the load descriptor — `backdrop-mechanism.md` §2, INFERRED
-/// U+V wrap). sRGB + no mips, same as the clamp sprite (UI art, one authored gamma round-trip).
-///
-/// Both axes wrap — the backdrop's bg tiles both ways, and its edge strips are atlas crops on
-/// their bounded axis, kept off the image edge by `inset_atlas_bleed`. A texture that tiles
-/// along ONE axis and spans the whole image on the other takes [`sprite_image_wrapped`] instead
-/// (decision 2000).
+/// [`sprite_image`] wrapping on both axes, for a frame `Backdrop`, whose `SetTexture` pushes one
+/// argument twice into the load descriptor (`0x770200`), read as U and V wrap but not traced to
+/// the sampler: an edge strip runs UVs `[0..N]` (N = frame side / edgeSize − 2) and a tiled
+/// background `[0..w/period]` (`0x77e8d0`, `0x77f0c0`). The edge strips are atlas crops kept off
+/// the image edge (`inset_atlas_bleed`), so their bounded axis does not bleed.
 pub fn sprite_image_tiled(width: u32, height: u32, rgba: Vec<u8>) -> Image {
     sprite_image_wrapped(width, height, rgba, (true, true))
 }
 
-/// [`sprite_image`]'s decode with the address mode chosen **per axis**: `Repeat` where `wrap`
-/// says so, `ClampToEdge` elsewhere.
-///
-/// The reference's tiling idiom, `SetTexCoord(0, n, 0, 1)` on an n-slot strip, runs past the
-/// texture along one axis only; the other spans exactly `[0, 1]`. Sampling that bounded axis
-/// with `Repeat` is a bleed: bilinear filtering at `v = 0` weighs in the texture's LAST row, so a
-/// strip whose bottom row is opaque draws that row as a faint hairline along its own top edge —
-/// the stance shelf's middle piece (`ShapeshiftBarMiddle.blp`: rows 0-7 transparent, row 31
-/// opaque grey) wore a one-device-px grey line across the top of the strip at every four-form
-/// bar, over the world. Wrapping only the axis that actually tiles is the fix at the root: the
-/// bounded axis clamps at its edge, exactly as a stand-alone clamped sprite would (decision 2000).
+/// [`sprite_image`] with `Repeat` on the axes `wrap` names and clamp elsewhere. The reference's
+/// `SetTexCoord(0, n, 0, 1)` strips tile along one axis only; repeat on the bounded axis would
+/// filter the last row into the first as a hairline along the strip's edge.
 pub fn sprite_image_wrapped(width: u32, height: u32, rgba: Vec<u8>, wrap: (bool, bool)) -> Image {
     let mut image = Image::new(
         Extent3d {
@@ -430,21 +331,14 @@ pub fn sprite_image_wrapped(width: u32, height: u32, rgba: Vec<u8>, wrap: (bool,
     image
 }
 
-/// The bytes an [`Image`] occupies **on the GPU** — every mip level of every array layer, derived
-/// from the `texture_descriptor` alone.
-///
-/// Read from the descriptor, never from `image.data.len()`: an asset declared
-/// [`RenderAssetUsages::RENDER_WORLD`] has its bytes *moved* into the render world on extract
-/// (`bevy_render::render_asset`), so main-side `data` is `None` for its whole life. A meter that
-/// measures `data` therefore reads 0 for exactly the textures that cost the most — the terrain
-/// arrays, the sprite sheets, the world albedo. This is the arithmetic bevy_image itself uses, and
-/// it is block-aware, so it stays right if a format is ever uploaded compressed.
+/// The bytes an [`Image`] occupies on the GPU, every mip of every layer, from the
+/// `texture_descriptor` alone: a `RENDER_WORLD` asset's `data` moves to the render world on
+/// extract, so main-side it reads `None`. Block-aware, as bevy_image computes it.
 pub fn image_gpu_bytes(image: &Image) -> usize {
     let d = &image.texture_descriptor;
     let format = d.format;
     let (bw, bh) = format.block_dimensions();
-    // A copy is defined per block, and a block is only whole: a 1×1 mip of a 4×4-block format still
-    // costs one full block.
+    // A block is whole: a 1×1 mip of a 4×4-block format costs a full block.
     let Some(block_bytes) = format.block_copy_size(None) else {
         return 0; // multi-planar/depth-stencil: no single block size, and we upload neither
     };
@@ -475,16 +369,15 @@ pub fn mip_chain_byte_size(top: u32, mip_count: u32) -> usize {
         .sum()
 }
 
-/// Append `src` (RGBA8 `sw × sh`) resized to `dw × dh` to `out`, using `NEAREST` filtering in
-/// gamma byte space. NEAREST = pure texel-replication (or decimation), so no averaging happens —
-/// preserves gamma-encoded bytes verbatim (no darkening). Identity at `(sw, sh) == (dw, dh)`.
+/// Append `src` (RGBA8 `sw × sh`) resized to `dw × dh` by `NEAREST`, which only replicates or
+/// decimates texels and so keeps the gamma bytes verbatim.
 pub fn extend_nearest(out: &mut Vec<u8>, src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) {
     if sw == dw && sh == dh {
         out.extend_from_slice(src);
         return;
     }
     let Some(buf) = image::RgbaImage::from_raw(sw, sh, src.to_vec()) else {
-        // Shape mismatch — fall back to a black layer rather than panicking.
+        // A shape mismatch gives a black layer rather than a panic.
         out.extend(std::iter::repeat_n(0u8, (dw * dh * 4) as usize));
         return;
     };
@@ -496,8 +389,7 @@ pub fn extend_nearest(out: &mut Vec<u8>, src: &[u8], sw: u32, sh: u32, dw: u32,
 mod tests {
     use super::*;
 
-    /// Two 2x2 frames whose means differ by a lot, with a full 2-level chain each — the smallest
-    /// shape that exercises the per-level DC pass.
+    /// Two 2x2 frames with far-apart means and a full 2-level chain each.
     fn dc_frames() -> Vec<BlpMipChain> {
         let frame = |base: u8| BlpMipChain {
             width: 2,
@@ -530,10 +422,6 @@ mod tests {
         vec![frame(40), frame(80)]
     }
 
-    /// The whole point of [`flatten_frame_dc`]: after it, no frame's level mean differs from any
-    /// other's, so a mip-averaged sheet cannot brighten and dim as the loop plays. This is the
-    /// property the Ratchet report turned on — a 1.25 s whole-sheet breath measured at up to
-    /// 1.84/255 — and a still frame can never show it, so it is asserted here instead.
     #[test]
     fn flatten_frame_dc_equalizes_every_frame_at_every_level() {
         let frames = dc_frames();
@@ -562,12 +450,10 @@ mod tests {
         }
     }
 
-    /// The lever back to the shipped art, and the control for the test above: with
-    /// `WOW_LIQUID_DC=raw` the frames keep their own DC, so the drift the fix removes is still
-    /// there. Without this, a no-op `flatten_frame_dc` would pass the assertion above trivially.
+    /// The control for the test above: opted out (the magma and slime lane), the frames keep their
+    /// own DC, so a no-op pass cannot pass it.
     #[test]
     fn raw_lever_keeps_the_authored_per_frame_dc() {
-        // The pass is skipped when the caller opts out, which is the fullbright (magma/slime) lane.
         let frames = dc_frames();
         let img = liquid_frame_array(frames, false);
         let data = img.data.as_ref().expect("array has data");
@@ -597,8 +483,6 @@ mod tests {
         image
     }
 
-    /// The arithmetic must agree with [`mip_chain_byte_size`], which the liquid array already
-    /// budgets with — two independent expressions of the same pyramid.
     #[test]
     fn gpu_bytes_agree_with_the_rgba8_chain_arithmetic() {
         for (top, mips) in [(256, 9), (128, 8), (64, 7), (1, 1)] {
@@ -619,8 +503,7 @@ mod tests {
         }
     }
 
-    /// The number the liquid lane costs, stated once so it cannot drift silently: 136 frames of a
-    /// 256² RGBA8 nine-level pyramid, stacked as array layers.
+    /// The liquid lane: 136 frames of a 256² RGBA8 nine-level pyramid, stacked as array layers.
     #[test]
     fn gpu_bytes_count_every_array_layer() {
         let frames = 136;
@@ -640,8 +523,6 @@ mod tests {
         );
     }
 
-    /// Block-compressed formats are the point of reading the descriptor rather than a pixel size:
-    /// a 4×4-block format still owes a WHOLE block for its 2×2 and 1×1 mips.
     #[test]
     fn gpu_bytes_are_block_aware_and_round_up() {
         let bc1 = descriptor_only(
@@ -680,8 +561,6 @@ mod wrap_tests {
         }
     }
 
-    /// The stance shelf's case: tiles along its length, spans the whole texture in height — the
-    /// height axis must CLAMP, or the strip's opaque bottom row bleeds into its top edge.
     #[test]
     fn a_one_axis_tile_wraps_that_axis_and_clamps_the_other() {
         let img = sprite_image_wrapped(2, 2, vec![0; 16], (true, false));
@@ -696,7 +575,6 @@ mod wrap_tests {
         );
     }
 
-    /// The backdrop's case is unchanged: both axes wrap.
     #[test]
     fn the_tiled_sprite_still_wraps_both_axes() {
         let img = sprite_image_tiled(2, 2, vec![0; 16]);
diff --git a/crates/benilla-assets/src/world_assets/mod.rs b/crates/benilla-assets/src/world_assets/mod.rs
index 94bd6a98..dba6e3e8 100644
--- a/crates/benilla-assets/src/world_assets/mod.rs
+++ b/crates/benilla-assets/src/world_assets/mod.rs
@@ -1,20 +1,6 @@
-//! **The shared asset store** — the one open patch chain, the dedup caches every model/texture load
-//! goes through, and the helpers that turn raw BLP pixels into Bevy textures and per-submesh
-//! materials.
-//!
-//! It lives here rather than in the client because it is a layer *under* both sides, and 1164
-//! measured how far under: `WorldAssets` alone is named by 63 files, `LockRecover` by 43 and
-//! `AssetSet` by 37, and they serve UI sprites, portraits and the minimap mask exactly as much as
-//! they serve terrain. Nothing in here reads game state — it knows what pixel shape something
-//! wants, not what a unit frame *is*.
-//!
-//! What stayed up in the client is the 115-line plugin shell that drives it: opening the chain at
-//! startup needs the shared light buffer, evicting on a map change needs the world-map message, and
-//! the residency sweep needs the art-scope instrument. Those three are the only upward reaches the
-//! module ever had (decision 1164) — the data core below has none.
-//!
-//! Deduping by path/material means each unique BLP is decoded + uploaded once, and submeshes sharing
-//! a texture+blend share a material handle — which is what lets Bevy batch draws.
+//! The shared asset store: the one open patch chain, the dedup caches every model and texture load
+//! goes through, and the helpers that turn BLP pixels into textures and per-submesh materials. It
+//! reads no game state.
 
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
@@ -28,78 +14,41 @@ use crate::materials::{TorchBinds, WowModelExt, WowModelMaterial, VANILLA_ALPHA_
 use crate::SpatialCache;
 use benilla_formats::{blp_to_rgba, read_texture_native_chain, tga_to_rgba, Chain, ModelBlend};
 
-/// BLP/RGBA -> Bevy `Image` texture helpers (+ solid/cursor/liquid-frame textures). Split out for
-/// size; re-exported so callers keep using `benilla_assets::{solid_layer_chain, …}`.
+/// BLP and RGBA to `Image` helpers, re-exported.
 mod images;
 pub use images::*;
 
-/// Shared asset store: the **one** open patch chain plus dedup caches, used by every model/texture
-/// load (terrain layers, doodads, WMOs, creatures, GameObjects). Replaces the three independent
-/// chains we used to open. Deduping by path/material means each unique BLP is decoded + uploaded
-/// once, and submeshes sharing a texture+blend share a `StandardMaterial` handle — which is what
-/// lets Bevy batch their draw calls.
+/// The shared asset store: the one open patch chain and the dedup caches, so each BLP decodes once
+/// and submeshes sharing a texture and blend share a material that Bevy batches.
 #[derive(Resource)]
 pub struct WorldAssets {
-    /// The **one** open patch chain, behind `Arc<Mutex<…>>` because the streaming loaders thread a
-    /// `&mut Chain` (the `read_file` shim); the `Mutex` is `Send + Sync` glue, not a read serializer —
-    /// `Chain` reads are `&self` and open a fresh OS handle, so they share no seek state.
-    /// Main-thread reads lock via [`LockRecover`] (poison-tolerant); contention is ~nil since after
-    /// startup the only main-thread reads are the occasional map-change WDL load + lazy clutter M2s.
+    /// The one open patch chain. The `Mutex` is `Send + Sync` glue for the streaming loaders'
+    /// `&mut Chain`, not a read serializer: `Chain` reads are `&self` on a fresh OS handle.
     pub chain: Arc<Mutex<Chain>>,
-    /// Decoded GPU textures by normalized path.
-    /// Keyed by `(normalized path, wrap_u, wrap_v)`: the SAME BLP is legitimately sampled both
-    /// ways by different models (a sheet that tiles on a wall and clamps on a cutout card), and the
-    /// address mode lives on the Bevy `Image`'s sampler — so each mode needs its own upload
-    /// (decision 0763). Before that key existed, whichever model loaded the texture first decided
-    /// the mode for every later one.
+    /// Decoded GPU textures by `(normalized path, wrap_u, wrap_v)`: one BLP can be sampled both
+    /// ways (tiled on a wall, clamped on a cutout card), and the address mode lives on the sampler.
     pub textures: SpatialCache<(String, bool, bool), Handle<Image>>,
-    /// Decoded UI sprite textures by resolved path (`None` = a miss, cached so a bad path never
-    /// re-walks the chain per frame). Separate from `textures`: sprites are sRGB/clamped, world
-    /// art is Unorm/repeat — the same BLP can legitimately live in both.
+    /// UI sprites by resolved path, misses cached as `None` so a bad path never re-walks the chain
+    /// per frame.
     sprites: HashMap<String, Option<Handle<Image>>>,
-    /// Decoded UI sprite textures sampled with **repeat** addressing on one or both axes (frame
-    /// `Backdrop` pieces — tiled edges/bg — and the reference's `SetTexCoord(0, n, 0, 1)` strips).
-    /// Keyed by resolved path **and** the per-axis wrap, separate from `sprites`: the *same* BLP
-    /// can be wanted clamp-sampled as a plain sprite and repeat-sampled as a backdrop piece, and
-    /// each address-mode pair needs its own GPU image (the sampler is baked into the `Image`).
-    /// See [`Self::sprite_texture_wrapped`].
+    /// UI sprites by path and per-axis wrap, since the sampler bakes into the `Image`.
     tiled_sprites: HashMap<(String, bool, bool), Option<Handle<Image>>>,
-    /// Sprites RESAMPLED to an exact physical size, by `(path, w, h)` — the nameplate border's
-    /// 0188 sharpen and nothing else so far. Keyed by size because that is the whole point: the
-    /// art is re-rasterised whenever the plate's pixel size moves, and reused on every frame in
-    /// between (a resize is rare; a plate is drawn 60 times a second).
+    /// Sprites resampled to an exact physical size, by `(path, w, h)`.
     resampled_sprites: HashMap<(String, u32, u32), Option<Handle<Image>>>,
-    /// The decoded source pixels behind [`Self::resampled_sprites`], so a resize re-samples
-    /// instead of re-decoding the BLP.
+    /// The decoded pixels behind [`Self::resampled_sprites`], so a resize does not re-decode.
     resample_sources: HashMap<String, Option<(u32, u32, Vec<u8>)>>,
-    /// Decoded **portrait** sprites — [`Self::sprite_texture`]'s clamp/sRGB sprite with a circular
-    /// alpha mask baked in ([`portrait_image`]). Its own cache, like `tiled_sprites`: the mask bakes
-    /// into the GPU image, so the same BLP wanted as a plain icon and as a portrait needs two images.
+    /// Portrait sprites, the circular mask baked in ([`portrait_image`]).
     portraits: HashMap<String, Option<Handle<Image>>>,
-    /// Decoded coverage **masks** ([`mask_image`] — linear, not sRGB): the minimap's circular clip
-    /// (decision 0203). Its own cache for the same reason as the others: the format is baked into
-    /// the GPU image.
+    /// Coverage masks ([`mask_image`]): the minimap's circular clip.
     masks: HashMap<String, Option<Handle<Image>>>,
-    /// **Generated** UI sprites — pixels this client computes rather than decodes, keyed by a
-    /// caller-chosen static name ([`Self::generated_sprite`]). Its own cache for the same reason as
-    /// every other one: the sampler bakes into the GPU image. Nothing about the *content* lives
-    /// here — the caller supplies the RGBA — so this stays a cache, not a second art pipeline.
+    /// UI sprites whose pixels the client computes ([`Self::generated_sprite`]).
     generated: HashMap<&'static str, Handle<Image>>,
-    /// The **loose-file root for `Interface\AddOns\` sprite paths** — the AddOns folder, installed
-    /// by the app ([`Self::set_loose_addon_root`]), `None` until then and in every capture run
-    /// (the app resolves it through `local_state`, which is hermetic under `$WOW_CAPTURE`).
-    ///
-    /// Addon art never lives in an MPQ: the reference's Storm open reads loose files from the game
-    /// directory, which is how `<Texture file="Interface\AddOns\Atlas\Images\…"/>` works at all.
-    /// Our equivalent maps that virtual prefix onto the one addon root (decision 1185's single
-    /// folder; decision 1322). Only the UI-sprite decoders consult it — world art has no business
-    /// under `AddOns\`.
+    /// The AddOns folder, where `Interface\AddOns\` paths resolve as loose files, as the reference
+    /// reads them from the game directory; `None` until the app installs it and in capture runs.
     loose_root: Option<PathBuf>,
-    /// Materials deduped by their identity (texture path + blend, or the untextured fallback).
+    /// Materials deduped by [`MaterialKey`].
     pub model_materials: SpatialCache<MaterialKey, Handle<WowModelMaterial>>,
-    /// The shared global-light storage buffer (`lighting::global_light`). Held here so `model_material`
-    /// can clone it into every deduped model material's `light_buf` without threading a `Buffer` through
-    /// the many call sites. One buffer for the whole scene, updated in place each frame.
+    /// The shared global-light buffer, cloned into every deduped model material's `light_buf`.
     pub shared_light: Buffer,
     /// MONKEY (torch shadows Phase 3A): the shared torch depth image + torch table buffer, held
     /// beside `shared_light` for the same reason — cloned into every deduped model material's
@@ -107,37 +56,24 @@ pub struct WorldAssets {
     pub torch: TorchBinds,
 }
 
-/// Identity of a deduped model material: a textured material is uniquely determined by its texture
-/// path, blend mode, sidedness, alpha-key cutoff, and clutter fade-distance; everything textureless
-/// (missing/failed texture) shares one fallback. Cutoff + fade are in the key so ground clutter (lower
-/// alpha ref + a distance fade) doesn't collide with a tree sharing the same texture.
+/// Identity of a deduped model material; everything textureless shares one fallback per WMO flag.
+/// The cutoff and fade distance are in it so ground clutter never shares a tree's material.
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub enum MaterialKey {
     /// `(texture, blend, two_sided, alpha_key_u8, fade_far_yd_u16, is_wmo, is_fade_variant,
-    /// wrap_u, wrap_v)` — the address mode is part of the identity because it selects a different
-    /// `Image` upload (decision 0763).
+    /// wrap_u, wrap_v)`; the address mode selects a different `Image` upload.
     Textured(String, ModelBlend, bool, u8, u16, bool, bool, bool, bool),
     Fallback(bool),
 }
 
-/// Normalize an internal asset path so case/slash variants of the same file share a cache entry
-/// (MPQ lookup is case-insensitive and accepts either slash).
+/// Fold case and slashes so variants of one file share a cache entry, as MPQ lookup does.
 pub fn normalize_path(path: &str) -> String {
     path.replace('/', "\\").to_ascii_lowercase()
 }
 
-/// The **cache key** a UI sprite reference folds to: [`normalize_path`], then an extension of
-/// **exactly three characters** stripped — a dot at `len - 4`.
-///
-/// That is the reference's own rule (`0x449590`, which strips a 3-char extension and returns which
-/// of `{".tga", ".blp"}` it was), and its texture cache is keyed on the resulting stem — so
-/// `Foo`, `Foo.blp` and `Foo.tga` are **one** entry, not three. Ours keys the same way, which is
-/// why this is separate from [`sprite_candidates`]: the key identifies the texture, the candidates
-/// are the files that might hold it.
-///
-/// Note a 3-char extension is stripped whatever it is: `Foo.bmp` keys as `Foo`. A longer or shorter
-/// one is not an extension to the client at all — `Foo.jpeg` keys as `Foo.jpeg` and looks for
-/// `Foo.jpeg.blp`.
+/// The cache key a UI sprite reference folds to: [`normalize_path`], then any three-character
+/// extension stripped, as the reference strips it (`0x449590`) and keys its texture cache on the
+/// stem. `Foo`, `Foo.blp` and `Foo.tga` are one entry; `Foo.jpeg` keys as itself.
 pub fn sprite_key(path: &str) -> String {
     let key = normalize_path(path);
     match key.len().checked_sub(4) {
@@ -146,28 +82,10 @@ pub fn sprite_key(path: &str) -> String {
     }
 }
 
-/// The two archive names a UI sprite reference may live under, **in the order the reference tries
-/// them** — `TextureCreate`'s fixed two-candidate chain (`0x449d90`, extension table `0x835248 =
-/// {".tga", ".blp"}`). The supplied extension's pipeline goes first, the other second; both open
-/// through the same Storm primitive, and a miss on the first is silent, so the second is a genuine
-/// fallback rather than an error path.
-///
-/// | reference | first | second |
-/// |---|---|---|
-/// | `Foo` (no 3-char extension) | `Foo.blp` | `Foo.tga` |
-/// | `Foo.blp` | `Foo.blp` | `Foo.tga` |
-/// | `Foo.tga` | `Foo.tga` | `Foo.blp` |
-/// | `Foo.bmp` (any other 3-char) | `Foo.blp` | `Foo.tga` |
-/// | `Foo.jpeg` (not 3 chars) | `Foo.jpeg.blp` | `Foo.jpeg.tga` |
-///
-/// This chain is what makes `Interface\Icons\Ability_Druid_Mangle.tga` — a real macro-chooser entry,
-/// since `Ability_Druid_Mangle.tga.blp` ships and the chooser stores names extension-stripped —
-/// resolve to `…Mangle.blp` on the second try instead of drawing a white square (bug B221). The old
-/// rule here passed an extensioned path through untouched and had no second try at all.
-///
-/// One function, used by the decoders below *and* by the sweeps that assert our own paths resolve
-/// (`ui_script::shipped_xml_tests`, `ui_macro::tests`): a sweep re-implementing this could agree
-/// with itself while disagreeing with what actually draws.
+/// The two files a UI sprite reference may live in, in the order of `TextureCreate`'s two-candidate
+/// chain (`0x449d90`, extension table `0x835248 = {".tga", ".blp"}`): `.tga` first for a `.tga`
+/// reference, `.blp` first otherwise, and a miss on the first is silent. The sweeps that assert our
+/// own paths resolve call this too, so they cannot disagree with what draws.
 pub fn sprite_candidates(path: &str) -> [String; 2] {
     let stem = sprite_key(path);
     let normalized = normalize_path(path);
@@ -179,15 +97,9 @@ pub fn sprite_candidates(path: &str) -> [String; 2] {
     }
 }
 
-/// The **texel dimensions** of a UI sprite reference, or `None` when nothing resolves — the number
-/// the client's `CSimpleTexture` size getters read out of `[tex+0x144]`/`[tex+0x148]` when a region
-/// authored no size on an axis (wow-re `region-size-fallback.md` §2, decision 1349: one texel is one
-/// FrameXML unit).
-///
-/// It goes through [`decode_sprite`] rather than sniffing a header, so the size layout uses is the
-/// size the screen shows: the same candidate order, the same BLP-vs-TGA content sniff, and the same
-/// verdict on a candidate that reads but will not decode. The caller memoises — this is asked once
-/// per distinct path, for the handful of regions whose rect is derived from their art.
+/// The texel size of a UI sprite, which `CSimpleTexture`'s size getters read (`[tex+0x144]`,
+/// `[tex+0x148]`; `0x770720`, `0x770790`) for a region with no authored size, one texel per
+/// FrameXML unit. Decoded, so layout gets the size the screen shows.
 pub fn sprite_dimensions(
     chain: &Mutex<Chain>,
     loose_root: Option<&Path>,
@@ -196,32 +108,9 @@ pub fn sprite_dimensions(
     decode_sprite(chain, loose_root, path).map(|(w, h, _)| (w, h))
 }
 
-/// Decode a UI sprite key to RGBA8, **warning once per key that fails to resolve**.
-///
-/// Every sprite cache below stores misses as well as hits, and each calls this on the miss path
-/// *before* inserting — so the warning is self-limiting by construction (one line per distinct key
-/// for the process's life), with no separate "already warned" set to keep.
-///
-/// It exists because the renderer's fallback for an unresolvable path is **silent**. It used to be
-/// silent *and* look like art: a `Texture` region whose file could not be found still pushed a
-/// quad, which `ui_pass` drew with the shared 1×1 white image tinted white — an opaque WHITE
-/// RECTANGLE at the region's exact rect, which is how bug B221's macro-chooser icons looked. That
-/// half is gone (`ui_script::extract` now drops the quad outright when the resolve misses), so the
-/// miss draws *nothing* rather than a white square. It is no less silent for that: nothing on
-/// screen and nothing in Lua says why, and `shipped_xml_tests` sweeps only static XML `file=`
-/// attributes, never a path that arrives at runtime from a DBC or from an addon. So the report
-/// still belongs here.
-///
-/// Walks [`sprite_candidates`] in order and takes the first that both reads and decodes; only when
-/// **all** fail is it a miss. A candidate that reads but won't decode falls through exactly like
-/// one that isn't there — the reference's two loaders both fail silently, so a bad first candidate
-/// can't poison the second.
-///
-/// Each candidate is asked of **two stores**: the patch chain, then — for `Interface\AddOns\`
-/// paths — the loose addon folder ([`loose_addon_file`], decision 1322). The chain never holds an
-/// `AddOns\` path (Blizzard's own `Blizzard_*` stubs aside, addon art only exists on disk), so the
-/// order between the stores is unobservable; chain-first keeps every non-addon path on exactly the
-/// code it always ran.
+/// Decode the first of [`sprite_candidates`] that reads and decodes, from the chain and then the
+/// AddOns folder, as the reference's two loaders fail silently. A miss warns, once per key since
+/// every cache stores its misses: a missing sprite draws nothing, and nothing else says why.
 fn decode_sprite(
     chain: &Mutex<Chain>,
     loose_root: Option<&Path>,
@@ -244,10 +133,7 @@ fn decode_sprite(
             }
         }
     }
-    // **"Not there" and "there but would not decode" are different faults, and saying only the
-    // first sends the reader hunting a path that is sitting on disk.** Three colour-mapped TGAs in
-    // the addon corpus read fine and failed to decode for years while this line asserted they did
-    // not resolve (decision 2128).
+    // "Not there" and "there but would not decode" are different faults; say which.
     let found_but_undecodable: Vec<&String> = candidates
         .iter()
         .filter(|c| {
@@ -279,10 +165,8 @@ fn decode_sprite(
     None
 }
 
-/// Decode one candidate's bytes to RGBA8, picking the format by content: a `BLP2` magic is a BLP,
-/// anything else is offered to the TGA decoder (TGA has no magic; its header validation is the
-/// gate). Content, not extension, because the ecosystem mislabels freely — a BLP named `.tga` and
-/// the reverse both ship in real addon folders, and the pixel bytes always know what they are.
+/// Decode by content, not extension, since addon folders mislabel both ways: a `BLP2` magic is a
+/// BLP, anything else goes to the TGA decoder, whose header check is the gate.
 fn decode_sprite_bytes(bytes: &[u8]) -> anyhow::Result<(u32, u32, Vec<u8>)> {
     if bytes.starts_with(b"BLP2") {
         blp_to_rgba(bytes)
@@ -291,20 +175,24 @@ fn decode_sprite_bytes(bytes: &[u8]) -> anyhow::Result<(u32, u32, Vec<u8>)> {
     }
 }
 
-/// Map a **normalized** addon-relative path (`interface\addons\<addon>\<…>`, lowercase,
-/// backslashed — [`normalize_path`] has run) onto a file under the loose addon root, or `None` if
-/// it is not an `Interface\AddOns\` path or nothing is there.
-///
-/// **Not sprite-specific, and named for that** (decision 2103): 1322 built this for addon-shipped
-/// BLP/TGA art, and an addon's own TTFs reach the client by exactly the same route — a loose file
-/// under the one AddOns root, named by a virtual `Interface\AddOns\…` path no MPQ carries. One
-/// resolver, one prefix rule, one sandbox.
-///
-/// The walk matches each component **case-insensitively** (exact join first — free on the
-/// case-insensitive filesystems macOS installs default to — then a `read_dir` scan): the reference
-/// is a Windows client and addons reference their own art in arbitrary case. The candidate cannot
-/// escape the root — `normalize_path` leaves no `/`, and any dot-component is refused before a
-/// filesystem call happens (same lexical posture as `ui_script::addons::read_under`).
+/// Read a file from the patch chain, then, for an `Interface\AddOns\` path, the loose addon folder:
+/// how art, fonts and audio an addon ships all load. The reference asks the install tree first
+/// (`0x647e60`'s attempt #4 is the MPQ); the chain holds no `AddOns\` path, so the order is moot.
+pub fn read_chain_or_loose(
+    chain: &Mutex<Chain>,
+    loose_root: Option<&Path>,
+    path: &str,
+) -> Option<Vec<u8>> {
+    if let Ok(bytes) = chain.lock_recover().read(path) {
+        return Some(bytes);
+    }
+    let file = loose_addon_file(loose_root?, &normalize_path(path))?;
+    std::fs::read(file).ok()
+}
+
+/// Map a normalized `interface\addons\…` path onto a file under the addon root, matching each
+/// component case-insensitively as the Windows reference does; a dot-component is refused, so a
+/// path cannot escape the root.
 pub fn loose_addon_file(root: &Path, candidate: &str) -> Option<PathBuf> {
     let rel = candidate.strip_prefix("interface\\addons\\")?;
     let mut at = root.to_path_buf();
@@ -327,14 +215,9 @@ pub fn loose_addon_file(root: &Path, candidate: &str) -> Option<PathBuf> {
     at.is_file().then_some(at)
 }
 
-/// Mutate an asset only when `differs` says its current state doesn't already match.
-///
-/// `Assets::get_mut` alone marks the asset Modified — a uniform re-upload and (on the Metal
-/// non-bindless path) a bind-group rebuild that frame — so a per-frame writer re-pushing an
-/// unchanged value is pure cost (the teleport leak's CPU engine was exactly this shape; the sky
-/// family idled at ~17 such writes per frame). The gate decides on the immutable view; pair it
-/// with values quantized to display precision ([`quantize`]/[`quant255`]) or continuous inputs
-/// defeat the compare.
+/// Mutate an asset only when `differs` says it does not already match: `Assets::get_mut` alone
+/// marks it Modified, a uniform re-upload and, on Metal's non-bindless path, a bind-group rebuild.
+/// Pair it with values quantized to display precision ([`quantize`], [`quant255`]).
 pub fn write_gated<M: bevy::asset::Asset>(
     assets: &mut Assets<M>,
     handle: &Handle<M>,
@@ -348,17 +231,13 @@ pub fn write_gated<M: bevy::asset::Asset>(
     }
 }
 
-/// Quantize to `n`-ths — the write-gate's precision floor for continuously-drifting inputs
-/// (time-of-day bands, camera-aim envelopes). Choose `n` at or below what the output can show:
-/// the reference packs its celestial/sky lanes to bytes (`floor(255·…)`, the 0xFF broadcasts)
-/// and re-submits them as per-frame vertex data, so a 1/255 step IS the reference's own
-/// precision for color/alpha; geometry scalars gate at a sub-pixel step instead.
+/// Quantize to `n`ths, the write gate's floor for drifting inputs: 255 for colour ([`quant255`]),
+/// a sub-pixel step for geometry.
 pub fn quantize(x: f32, n: f32) -> f32 {
     (x * n).round() / n
 }
 
-/// [`quantize`] each channel to the display's 1/255 LSB — the byte precision the reference's own
-/// color lanes carry.
+/// [`quantize`] each channel to 1/255: the reference packs its sky and celestial colours to bytes.
 pub fn quant255(c: [f32; 3]) -> [f32; 3] {
     [
         quantize(c[0], 255.0),
@@ -367,13 +246,8 @@ pub fn quant255(c: [f32; 3]) -> [f32; 3] {
     ]
 }
 
-/// Lock a `Mutex`, recovering the guard even if a previous holder **poisoned** it by panicking.
-///
-/// The shared [`WorldAssets::chain`] is read from many systems; one panic mid-read would otherwise
-/// poison the lock and turn every subsequent `lock().unwrap()` — including the render loop's — into a
-/// cascade. The chain read is a best-effort decode (a half-read texture is harmless), so we recover
-/// the guard and carry on. (Phase 3 deleted the net subsystem's shared mutexes entirely; this remains
-/// only for the asset foundation, which is its one legitimate user.)
+/// Lock a `Mutex`, recovering the guard if a holder panicked, so one failed read of the shared
+/// chain does not fail every later lock; a half-read texture is harmless.
 pub trait LockRecover<T> {
     fn lock_recover(&self) -> MutexGuard<'_, T>;
 }
@@ -413,10 +287,14 @@ impl WorldAssets {
         }
     }
 
-    /// Install (or clear) the loose-file root for `Interface\AddOns\` sprite paths — see the
-    /// [`Self::loose_root`] field doc. Called by the app once it knows the AddOns folder; evicts
-    /// cached **misses** so a path asked before the root existed gets a second look (a cached hit
-    /// can only have come from the chain and stays right).
+    /// [`read_chain_or_loose`] over this store, for an asset class with no decoder here (audio:
+    /// `PlayMusic`, `PlaySoundFile`).
+    pub fn read_file_or_loose(&self, path: &str) -> Option<Vec<u8>> {
+        read_chain_or_loose(&self.chain, self.loose_root.as_deref(), path)
+    }
+
+    /// Install or clear the AddOns folder. Cached misses are evicted so a path asked before it
+    /// existed gets a second look; a cached hit came from the chain and stays right.
     pub fn set_loose_addon_root(&mut self, root: Option<PathBuf>) {
         if self.loose_root == root {
             return;
@@ -428,8 +306,7 @@ impl WorldAssets {
         self.masks.retain(|_, v| v.is_some());
     }
 
-    /// Decode + upload a BLP once per path; later requests for the same texture share the handle.
-    /// `None` if the texture is missing or fails to decode.
+    /// Decode and upload a BLP once per path and wrap; later requests share the handle.
     pub fn texture(
         &mut self,
         path: &str,
@@ -440,33 +317,22 @@ impl WorldAssets {
         if let Some(handle) = self.textures.fetch(&key) {
             return Some(handle);
         }
-        // Passthrough: world art is uploaded in the form the BLP stores it (decision 1626).
-        // Nothing reads a world texture main-side — the same reasoning that already makes this
-        // lane `RenderAssetUsages::RENDER_WORLD` — so there are no CPU texels to lose.
+        // World art uploads as the BLP stores it; nothing reads it main-side.
         let chain = read_texture_native_chain(&mut self.chain.lock_recover(), &key.0).ok()?;
         let handle = images.add(repeat_texture_authored(crate::for_upload(chain), wrap));
         self.textures.insert(key, handle.clone());
         Some(handle)
     }
 
-    /// Decode a BLP into a clamp-sampled **sRGB** sprite image (mip 0 only) — the celestial discs
-    /// (sun/moon) and every player-UI quad. Unlike [`Self::texture`] (repeat-sampled, gamma-space
-    /// `Unorm`, mipmapped — for tiling world art), this is sRGB + clamp-to-edge with no mip chain.
-    /// Extensionless references get `.blp` appended (the FrameXML convention). Cached by resolved
-    /// path — hits and misses both — in its own `sprites` map, separate from the `textures` cache
-    /// (the same BLP can live in both, with different sampling).
+    /// A clamp-sampled sRGB sprite, mip 0 only: the celestial discs and every UI quad.
     pub fn sprite_texture(
         &mut self,
         path: &str,
         images: &mut Assets<Image>,
     ) -> Option<Handle<Image>> {
-        // FrameXML/DBC texture references are canonically EXTENSIONLESS
-        // (`Interface\Buttons\UI-Quickslot2`) — the real client appends `.blp` at resolve. Paths
-        // that already carry an extension (`textures\moon.blp`) pass through unchanged.
         let key = sprite_key(path);
-        // Cached (hits AND misses): the UI extractor asks per quad per frame — uncached, every
-        // frame re-decoded every BLP into a fresh `Image` (unbounded asset growth) and the fresh
-        // handles defeated the quad-list dirty check.
+        // Hits and misses are cached: the UI extractor asks per quad per frame, and a fresh handle
+        // would defeat its dirty check.
         if let Some(cached) = self.sprites.get(&key) {
             return cached.clone();
         }
@@ -476,24 +342,13 @@ impl WorldAssets {
         loaded
     }
 
-    /// Decode a texture to raw RGBA8 `(w, h, bytes)` **without** uploading a GPU image — for callers
-    /// that resample the pixels themselves before upload (the V-plate border sharpen, decision 0188,
-    /// which resizes the 128×32 frame to the plate's exact size). Same extensionless→`.blp` resolve
-    /// as [`Self::sprite_texture`]; not cached (a one-shot decode at load, not a per-frame ask).
+    /// Decode a UI sprite to raw RGBA8 without uploading or caching, for a caller that resamples.
     pub fn decode_rgba(&mut self, path: &str) -> Option<(u32, u32, Vec<u8>)> {
         decode_sprite(&self.chain, self.loose_root.as_deref(), path)
     }
 
-    /// A UI sprite **resampled to an exact pixel size** by the caller's own kernel, cached by that
-    /// size — the nameplate border (decision 0188).
-    ///
-    /// The plate's frame art is a 128 × 32 BLP drawn at whatever size the plate is, which past the
-    /// 1024×768 knee (and always on a retina framebuffer) is a magnification: the GPU's bilinear
-    /// filter smears the 1 px gold bevel across several soft output pixels, which is the director's
-    /// "blurry border". Resampling the SAME pixels to the target size with a sharp kernel keeps the
-    /// art and loses the smear. This lives here rather than in the plate driver because since
-    /// decision 2148 the plate is a widget like any other and its border is an ordinary texture
-    /// region — the substitution has to happen where a texture path becomes an image.
+    /// A UI sprite resampled to an exact pixel size by the caller's kernel, cached by size: the
+    /// nameplate border, whose 1 px bevel bilinear magnification would smear.
     pub fn resampled_sprite(
         &mut self,
         path: &str,
@@ -516,10 +371,7 @@ impl WorldAssets {
         made
     }
 
-    /// A UI sprite decoded with **repeat** (wrap) addressing on both axes — the frame `Backdrop`
-    /// tiled pieces (`backdrop-mechanism.md`): a border edge strip samples UVs `[0..N]` and a tiled
-    /// bg `[0..w/period]`, so the texture must wrap, not clamp. [`Self::sprite_texture_wrapped`]
-    /// with both axes on; see there for the cache and the decode.
+    /// A UI sprite repeating on both axes, for a frame `Backdrop`'s tiled pieces (`0x77f0c0`).
     pub fn sprite_texture_tiled(
         &mut self,
         path: &str,
@@ -528,13 +380,7 @@ impl WorldAssets {
         self.sprite_texture_wrapped(path, (true, true), images)
     }
 
-    /// A UI sprite decoded with **repeat** addressing on the axes `wrap` names and clamp on the
-    /// rest — the reference's one-axis tiling idiom (`SetTexCoord(0, n, 0, 1)` on the stance
-    /// shelf's middle strip) wraps along its length and must clamp across it, or the strip's
-    /// bottom row bleeds into its top edge (decision 2000; [`sprite_image_wrapped`]). Same
-    /// sRGB/no-mip decode + extensionless→`.blp` resolve as [`Self::sprite_texture`], but its
-    /// own cache keyed by the wrap pair (the sampler is baked into the `Image`, so a path wanted
-    /// under two address modes needs two GPU images). Cached hits **and** misses.
+    /// A UI sprite repeating on the axes `wrap` names ([`sprite_image_wrapped`]).
     pub fn sprite_texture_wrapped(
         &mut self,
         path: &str,
@@ -551,17 +397,8 @@ impl WorldAssets {
         loaded
     }
 
-    /// A sprite whose pixels this client **computes**, cached under `key` and built at most once.
-    /// `make` returns `(width, height, rgba8)` and runs only on the first ask.
-    ///
-    /// The customer is the colour picker: the reference's `<ColorWheelTexture>` and
-    /// `<ColorValueTexture>` carry no `file=` at all, because the hue disc and the brightness ramp
-    /// are generated by the client and no BLP in the chain is either of them. The generation itself
-    /// deliberately stays with the caller — the pixel law belongs to the widget, not to the asset
-    /// layer, which knows only how to cache and upload.
-    ///
-    /// Uploaded through [`sprite_image`], so it samples exactly like every other UI sprite:
-    /// sRGB, clamp-to-edge, linear, no mips.
+    /// A sprite whose pixels the client computes, built once by `make`: the colour picker's
+    /// `<ColorWheelTexture>` and `<ColorValueTexture>`, which name no `file=`.
     pub fn generated_sprite(
         &mut self,
         key: &'static str,
@@ -577,10 +414,7 @@ impl WorldAssets {
         handle
     }
 
-    /// A **portrait** sprite: [`Self::sprite_texture`]'s clamp/sRGB decode with a circular alpha mask
-    /// baked in ([`portrait_image`]) — the unit-frame portrait, round like the client's. Same
-    /// extensionless→`.blp` resolve; its own cache (the mask bakes into the GPU image, so a path
-    /// wanted both plain and portrait needs two images). Cached hits **and** misses.
+    /// A unit-frame portrait, the circular mask baked in ([`portrait_image`]).
     pub fn portrait_texture(
         &mut self,
         path: &str,
@@ -596,11 +430,9 @@ impl WorldAssets {
         loaded
     }
 
-    /// The tabard designer's emblem cell (decision 1977): the emblem BLP decoded and rewritten to
-    /// **white carrying its own alpha** — `(a << 24) | 0x00FFFFFF` per texel, the reference's
-    /// `0x503431` loop — as an ordinary clamped sprite the caller tints. Cached per path like a
-    /// sprite; a file that fails to open yields `None` (the reference installs its static array's
-    /// stale contents instead; nothing here has a previous emblem to show).
+    /// The tabard designer's emblem cell for the caller to tint: white carrying its own alpha,
+    /// `(a << 24) | 0x00FFFFFF` per texel (the reference's `0x503431` loop). A file that fails to
+    /// open gives `None`, where the reference keeps its static array's stale contents.
     pub fn emblem_mask_texture(
         &mut self,
         path: &str,
@@ -623,9 +455,7 @@ impl WorldAssets {
         loaded
     }
 
-    /// A coverage **mask** ([`mask_image`] — linear/clamp, the texel bytes handed to the shader
-    /// 1:1): the minimap's `MinimapMask.blp` circle (decision 0203, [`crate::ui_pass::UiQuadMask`]).
-    /// Same extensionless→`.blp` resolve as [`Self::sprite_texture`]; its own cache, hits AND misses.
+    /// A coverage mask, its bytes handed to the shader 1:1 ([`mask_image`]): the minimap's circle.
     pub fn mask_texture(
         &mut self,
         path: &str,
@@ -641,10 +471,8 @@ impl WorldAssets {
         loaded
     }
 
-    /// Decode a cursor BLP (e.g. `Interface\Cursor\Point.blp`) into a single-mip GPU image for
-    /// winit's custom OS cursor (`CursorIcon::Custom`) — *not* the mipmapped, repeat-sampled
-    /// [`repeat_texture_authored`] used for world art. `None` if the file is missing or fails to decode.
-    /// macOS doesn't use this (it drives `NSCursor` from the raw RGBA directly — see `crate::cursor`).
+    /// Decode a cursor BLP (`Interface\Cursor\Point.blp`) for winit's custom OS cursor; macOS
+    /// drives `NSCursor` from the raw RGBA instead.
     #[cfg(not(target_os = "macos"))]
     pub fn decode_cursor(
         &mut self,
@@ -659,9 +487,8 @@ impl WorldAssets {
         Some(images.add(cursor_texture(w, h, rgba)))
     }
 
-    /// A `StandardMaterial` for a model submesh, deduped by (texture, blend) so submeshes/models
-    /// sharing a texture share one material handle (enabling draw-call batching). A missing/failed
-    /// texture falls back to a single shared untextured material.
+    /// A model submesh material, deduped by [`MaterialKey`] so submeshes sharing a texture share a
+    /// handle and batch; a missing texture falls back to one shared untextured material.
     pub fn model_material(
         &mut self,
         texture: Option<&str>,
@@ -676,10 +503,9 @@ impl WorldAssets {
         images: &mut Assets<Image>,
         materials: &mut Assets<WowModelMaterial>,
     ) -> Handle<WowModelMaterial> {
-        // Alpha-test cutoff: callers may override (ground clutter uses the detail-doodad ref ≈ 0.5);
-        // everything else uses the general vanilla model alpha key.
+        // Ground clutter passes its own cutoff (128/255); everything else takes the M2 alpha key.
         let cutoff = alpha_cutoff.unwrap_or(VANILLA_ALPHA_KEY_REF);
-        // Ground-clutter distance fade (None for normal models). Near = 0.75× far (the client's ratio).
+        // Ground-clutter fade: near is 0.75 of far, the client's ratio.
         let clutter_fade = match fade_far {
             Some(far) => Vec4::new(far * 0.75, far, 0.0, 1.0),
             None => Vec4::ZERO,
@@ -688,7 +514,7 @@ impl WorldAssets {
             self.texture(t, wrap, images)
                 .map(|h| (normalize_path(t), h))
         });
-        // Only AlphaTest consumes the cutoff, so don't fragment opaque/blend materials by it.
+        // Only AlphaTest reads the cutoff, so opaque and blend materials do not split on it.
         let key_alpha = if blend == ModelBlend::AlphaTest {
             (cutoff * 255.0).round() as u8
         } else {
@@ -712,21 +538,15 @@ impl WorldAssets {
         if let Some(handle) = self.model_materials.fetch(&key) {
             return handle;
         }
-        // Per-submesh blend (opaque trunk/wall vs alpha-cut leaves/windows). This builder serves
-        // ground clutter, which never authors the multiply modes — Mod/Mod2x fall to plain Blend
-        // here rather than growing this path the marker bits `model_render::model_material` packs
-        // (that builder is the one every Mod-capable consumer uses; decision 0528).
+        // This builder serves ground clutter, which never authors Mod/Mod2x; every Mod-capable
+        // consumer uses `model_render::model_material`.
         let alpha_mode = match blend {
             ModelBlend::Opaque => AlphaMode::Opaque,
             ModelBlend::AlphaTest => AlphaMode::Mask(cutoff),
             ModelBlend::Blend | ModelBlend::Mod | ModelBlend::Mod2x => AlphaMode::Blend,
         };
-        // Single-sided unless the M2's 0x04 flag is set — matches the real client (many canopy planes
-        // are visible from one direction only).
+        // Single-sided unless the M2's 0x04 flag is set, as in the reference.
         let cull_mode = if two_sided { None } else { Some(Face::Back) };
-        // The base StandardMaterial carries texture/alpha/cull; our `wow_model.wgsl` extension does
-        // the WoW lighting (PBR fields like reflectance/roughness are ignored by it). Light uniforms
-        // are placeholders — `apply_wow_lighting` fills them from Light.dbc + the panel knobs.
         let base = match resolved {
             Some((_, image)) => StandardMaterial {
                 base_color_texture: Some(image),
@@ -735,8 +555,7 @@ impl WorldAssets {
                 cull_mode,
                 ..default()
             },
-            // No resolved texture → untextured WHITE draw (stage disabled in the reference —
-            // wow-re m2-runtime-texture-null-bind.md; see model_render.rs for the full note).
+            // No texture: an untextured white draw, the reference's disabled stage (`0x59d020`).
             None => StandardMaterial {
                 base_color: Color::WHITE,
                 ..default()
@@ -746,21 +565,18 @@ impl WorldAssets {
             base,
             extension: WowModelExt {
                 clutter_fade,
-                // x = WMO (FFP N·L × MOCV, not SH); y = distance-fade blend variant (depth-write-on
-                // via `specialize` — see WowModelKey; no live caller passes it here).
+                // x = WMO (FFP N·L × MOCV), y = the fade blend twin (no caller passes it here).
                 model_flags: Vec4::new(
                     if is_wmo { 1.0 } else { 0.0 },
                     if is_fade_variant { 1.0 } else { 0.0 },
                     0.0,
                     0.0,
                 ),
-                // x = doodad-lobe sun scale; `1.0` (lit) here — this builder serves clutter, which lights on
-                // the FFP N·L path with its own baked MCSH tint, so the lobe's `sun_scale` is unused.
+                // Clutter lights on the FFP N·L path with its own MCSH tint; no selector.
                 sun_scale: Vec4::new(1.0, 0.0, 0.0, 0.0),
-                tint: Vec4::ONE, // clutter never carries an animated M2Color tint (w: not a WMO batch)
+                tint: Vec4::ONE, // clutter has no animated M2Color tint and is not a WMO batch
                 sidn: Vec4::ZERO, // clutter is never SIDN/WINDOW glass (WMO-only)
                 anim_slots: Vec4::ZERO,
-                // The shared global light (light/fog/SH come from here, updated in place each frame).
                 light_buf: self.shared_light.clone(),
                 // MONKEY (torch shadows Phase 3A): the shared torch receiver bindings.
                 torch_depth: self.torch.depth.clone(),
@@ -772,27 +588,18 @@ impl WorldAssets {
     }
 }
 
-/// World/render configuration read once at startup from the environment, shared by the subsystems
-/// that need it: terrain reads `tex_tiles` (splat tiling) + `unload_budget` (the release lane).
-/// Inserted by [`AssetPlugin`] alongside [`WorldAssets`]; its *presence* is also the "there is a
-/// client install" gate the world-side setups key on.
-///
-/// How far terrain streams is deliberately **not** here: the residency window derives from the
-/// live `farclip` view distance (`benilla_world::view::ViewDistance` — the player's Terrain
-/// Distance setting), as the reference derives it (decision 1513).
+/// Render configuration read once from the environment at startup, inserted beside
+/// [`WorldAssets`]; its presence is the "there is a client install" gate world setups key on.
+/// Terrain residency is not here: it derives from the live `farclip`, as in the reference.
 #[derive(Resource, Clone, Copy)]
 pub struct RenderConfig {
-    /// Ground-texture repeats per chunk (`$WOW_TEX_TILES`, default 8).
-    pub tex_tiles: f32,
-    /// Stale tiles released per frame on a within-map window shift (`$WOW_TILE_UNLOAD`,
-    /// default 1; `0` = unbudgeted — the whole trailing row in one frame, the pre-B181
-    /// behaviour, kept as the controlled A/B leg on one build).
+    /// Stale tiles released per frame on a within-map window shift (`$WOW_TILE_UNLOAD`, default 1;
+    /// `0` releases the whole trailing row in one frame, the unbudgeted A/B leg).
     pub unload_budget: usize,
 }
 
-/// Startup ordering seam: [`AssetPlugin`] opens the patch chain in this set so every other
-/// subsystem's startup (catalog loads, terrain/lighting setup) can run `.after(AssetSet::Open)` and
-/// borrow the shared [`WorldAssets`].
+/// Startup ordering: the patch chain opens in [`AssetSet::Open`], so other startup systems run
+/// after it and borrow [`WorldAssets`].
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum AssetSet {
     Open,
@@ -802,9 +609,6 @@ pub enum AssetSet {
 mod tests {
     use super::*;
 
-    /// The disk tree spells its names in mixed case, the candidate arrives normalized-lowercase
-    /// (as [`sprite_candidates`] always hands it over) — the walk must land on the file anyway,
-    /// because the reference is a Windows client and addon authors never matched their own case.
     #[test]
     fn loose_addon_file_maps_addon_paths_case_insensitively() {
         let root =
@@ -813,9 +617,7 @@ mod tests {
         std::fs::create_dir_all(&dir).unwrap();
         std::fs::write(dir.join("BlackrockDepths.blp"), b"x").unwrap();
 
-        // The returned SPELLING is filesystem-dependent (a case-insensitive filesystem answers
-        // the exact-join fast path with the candidate's own casing), so the claim is that the
-        // path opens the right file, not how it is spelt.
+        // The returned spelling depends on the filesystem's case sensitivity, so check the file.
         let hit = loose_addon_file(
             &root,
             "interface\\addons\\atlas\\images\\maps\\blackrockdepths.blp",
@@ -823,7 +625,6 @@ mod tests {
         .expect("mixed-case tree resolves a lowercase candidate");
         assert_eq!(std::fs::read(&hit).unwrap(), b"x");
 
-        // Not an AddOns path → not this store's question.
         assert_eq!(loose_addon_file(&root, "interface\\icons\\foo.blp"), None);
         // A directory is not a file, and a missing file is a miss, not an error.
         assert_eq!(loose_addon_file(&root, "interface\\addons\\atlas"), None);
@@ -831,8 +632,7 @@ mod tests {
             loose_addon_file(&root, "interface\\addons\\atlas\\images\\maps\\nope.blp"),
             None
         );
-        // Dot-components never reach the filesystem (the read_under posture; `normalize_path`
-        // already forbids `/`, so this is the one lexical escape left to refuse).
+        // Dot-components never reach the filesystem; `normalize_path` already leaves no `/`.
         assert_eq!(
             loose_addon_file(&root, "interface\\addons\\..\\..\\etc\\passwd"),
             None
@@ -840,4 +640,44 @@ mod tests {
 
         std::fs::remove_dir_all(&root).ok();
     }
+
+    /// Against the real chain: a client file must still come from the archive, and the loose
+    /// folder is a fallback, not a shadow over it.
+    #[test]
+    fn read_chain_or_loose_asks_the_chain_then_an_addons_own_file_on_disk() {
+        let data = benilla_formats::wow_data_or_skip!();
+        let chain = Mutex::new(Chain::open(&data).expect("open the chain"));
+        let root =
+            std::env::temp_dir().join(format!("benilla-loose-audio-test-{}", std::process::id()));
+        let addons = root.join("AddOns");
+        std::fs::create_dir_all(addons.join("Jukebox")).unwrap();
+        std::fs::write(addons.join("Jukebox").join("Track.mp3"), b"ID3!").unwrap();
+
+        // The archive leg: a client track the chain does carry.
+        let theme = read_chain_or_loose(
+            &chain,
+            Some(&addons),
+            "Sound\\Music\\GlueScreenMusic\\wow_main_theme.mp3",
+        )
+        .expect("the glue theme lives in sound.MPQ");
+        assert!(theme.len() > 1_000_000, "the theme is a ~3 MB stored MP3");
+
+        // The loose leg: an addon's own track, named by the virtual path, spelt in its own case.
+        assert_eq!(
+            read_chain_or_loose(
+                &chain,
+                Some(&addons),
+                "Interface\\AddOns\\Jukebox\\Track.mp3"
+            )
+            .as_deref(),
+            Some(&b"ID3!"[..])
+        );
+        // In neither store: a plain miss, which every caller renders as silence.
+        assert!(read_chain_or_loose(&chain, Some(&addons), "Sound\\Music\\nope.mp3").is_none());
+        // No folder configured (a capture run, where `local_state` is hermetic): chain only.
+        assert!(
+            read_chain_or_loose(&chain, None, "Interface\\AddOns\\Jukebox\\Track.mp3").is_none()
+        );
+        std::fs::remove_dir_all(&root).ok();
+    }
 }
diff --git a/crates/benilla-blp/Cargo.toml b/crates/benilla-blp/Cargo.toml
index c0c84dae..3942468f 100644
--- a/crates/benilla-blp/Cargo.toml
+++ b/crates/benilla-blp/Cargo.toml
@@ -3,13 +3,12 @@ name = "benilla-blp"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "BLP2 texture decoder for WoW 1.12.1 (build 5875) — in-repo, decision 0021"
+description = "BLP2 texture decoder for WoW 1.12.1 (build 5875)"
 
 [lints]
 workspace = true
 
 [dependencies]
 benilla-bytes = { path = "../benilla-bytes" }
-# S3TC/DXT block decompression — the same fixed-point codec wow-blp uses, so DXT output is
-# byte-identical. Decompression is a deterministic algorithm (no quantization), unlike encode.
+# S3TC/DXT block decompression, a deterministic fixed-point decode.
 texpresso = "2"
diff --git a/crates/benilla-blp/src/bin/blpx.rs b/crates/benilla-blp/src/bin/blpx.rs
index 3dfb3ffc..1c37cce6 100644
--- a/crates/benilla-blp/src/bin/blpx.rs
+++ b/crates/benilla-blp/src/bin/blpx.rs
@@ -1,7 +1,5 @@
-//! One-off inspection helper (session tool, not shipped): `blpx <in.blp> <out.ppm>` writes mip 0
-//! as P6 PPM, alpha composited over magenta so cutout regions read at a glance (pipe through
-//! `sips -s format png` for a viewable PNG). An `<out>` ending in `.rgba` instead dumps mip 0 as
-//! raw RGBA8 bytes (width×height×4, row-major) for scripted analysis of the real alpha channel.
+//! `blpx <in.blp> <out.ppm>`: mip 0 as a P6 PPM, alpha composited over magenta so cutouts show; an
+//! `<out>` ending in `.rgba` gets raw RGBA8 instead (width×height×4, row-major).
 
 fn main() {
     let mut args = std::env::args().skip(1);
diff --git a/crates/benilla-blp/src/lib.rs b/crates/benilla-blp/src/lib.rs
index ab6f740c..450342a0 100644
--- a/crates/benilla-blp/src/lib.rs
+++ b/crates/benilla-blp/src/lib.rs
@@ -1,35 +1,14 @@
-//! A BLP2 texture decoder for **WoW 1.12.1 (build 5875)** — in-repo, replacing `wow-blp` (decision
-//! 0021). Decodes to `Rgba8Unorm` (the gamma-byte form the renderer uploads verbatim).
+//! A BLP2 texture decoder for WoW 1.12.1, which ships Direct content in three shapes:
+//! - Raw1: a 256-entry BGRA palette and 1-byte indices, then a 0, 1, 4 or 8-bit alpha block.
+//! - Raw3: uncompressed BGRA8.
+//! - DXTC: S3TC blocks, `alpha_type` selecting DXT1 (0), DXT3 (1) or DXT5 (7).
 //!
-//! 1.12 ships **BLP2 / Direct** content in three shapes (no JPEG in practice):
-//! - **Raw1** — a 256-entry **BGRA** palette + 1-byte indices, with a separate 0/1/4/8-bit alpha block.
-//! - **Raw3** — uncompressed BGRA8.
-//! - **DXTC** — S3TC blocks; `alpha_type` selects DXT1 (0) / DXT3 (1) / DXT5 (7), decoded via the same
-//!   `texpresso` codec `wow-blp` uses, so the output is byte-identical.
-//!
-//! **Two entry points, because the GPU wants the blocks and the CPU wants the pixels.**
-//! [`decode`] always yields `Rgba8Unorm`; [`decode_native`] hands back the DXTC blocks *verbatim*
-//! and only decodes the shapes that have no GPU-native form (Raw1/Raw3). The reference client
-//! uploads the stored blocks untouched (`glCompressedTexImage2DARB`; wow-re `system/image/image.md`
-//! "raw passthrough — device eats DXT"), so the native path is both the faithful one and 4x-8x
-//! cheaper in VRAM and texture bandwidth. Decoding is for consumers that read texels on the CPU.
-//!
-//! Two fidelity points that cost the old `wow-blp` two forks, folded in here natively:
-//! 1. the palette is **BGRA**, not RGBA (reading it as RGBA swaps R↔B on every palettized Blizzard
-//!    atlas — the "Westfall clutter is blue" bug);
-//! 2. a stale/unknown `alpha_type` byte (e.g. `2` on alpha-less particle atlases) is **not fatal** —
-//!    alpha presence is governed by `alpha_bits`; `alpha_type` only picks the DXT variant.
-//!
-//! Proven byte-for-byte against `wow-blp` over the real corpus during the decision-0021 migration
-//! (oracle test in git history); the `benilla-formats` texture loaders exercise it on every run.
-//!
-//! Byte access goes through `benilla-bytes` (decision 0064): every header read is bounds-checked,
-//! and `width`/`height` are capped at [`MAX_DIM`] so a corrupt header can't turn into a
-//! multi-gigabyte allocation in [`decode_dxt`].
+//! [`decode`] yields gamma-encoded `Rgba8Unorm`, never linearized; [`decode_native`] keeps the
+//! DXTC blocks, which the reference uploads untouched (`glCompressedTexImage2DARB` in `0x59f270`).
 
 use benilla_bytes::ByteExt;
 
-/// Decode error. Anything outside the 1.12 BLP2 envelope surfaces here rather than guessing.
+/// A BLP decode error: anything outside the 1.12 BLP2 envelope.
 #[derive(Debug)]
 pub enum Error {
     NotBlp2,
@@ -39,8 +18,7 @@ pub enum Error {
     OutOfBounds {
         level: usize,
     },
-    /// `width`/`height` from the header exceed [`MAX_DIM`] — most likely a corrupt or hostile
-    /// header, since no real 1.12 BLP is anywhere near this large.
+    /// The header's dimensions exceed [`MAX_DIM`], which no real 1.12 BLP comes near.
     DimensionsTooLarge {
         width: u32,
         height: u32,
@@ -67,13 +45,10 @@ impl std::error::Error for Error {}
 
 type Result<T> = std::result::Result<T, Error>;
 
-/// A decoded BLP: mip-major `Rgba8Unorm`. `mips[0]` is the full image and is always present; deeper
-/// levels follow while the file carries them. [`mip_chain_count`](DecodedBlp::mip_chain_count) is the
-/// count `wow-blp` reports for the dimensions (what the renderer's authored-mip upload iterates).
+/// A decoded BLP, `Rgba8Unorm` per mip; `mips[0]` is always present.
 pub struct DecodedBlp {
     pub width: u32,
     pub height: u32,
-    /// One RGBA8 buffer per decoded mip level, level 0 first.
     pub mips: Vec<MipLevel>,
     mip_chain_count: usize,
 }
@@ -86,9 +61,8 @@ pub struct MipLevel {
 }
 
 impl DecodedBlp {
-    /// The authored mip-chain length for these dimensions, matching `wow-blp`'s `mipmaps_count()`
-    /// (`max(log2 w, log2 h)` when the file has mipmaps, else 0). The renderer's mip-chain upload
-    /// iterates exactly this many levels; `mips` may hold one more (level 0) when this is 0.
+    /// The authored chain length: `max(log2 w, log2 h)` with mipmaps, else 0 (`mips` still holds
+    /// level 0).
     pub fn mip_chain_count(&self) -> usize {
         self.mip_chain_count
     }
@@ -97,15 +71,9 @@ impl DecodedBlp {
 const HEADER_SIZE: usize = 148; // magic..=mip_sizes[16]
 const PALETTE_SIZE: usize = 256 * 4;
 
-/// Sanity cap on header `width`/`height`. Real 1.12 art tops out at 1024×1024; this is pure
-/// headroom above any real asset, and its only job is bounding allocation: [`decode_dxt`] sizes
-/// both its block-padding buffer and its `w*h*4` RGBA output straight from these fields, so a
-/// corrupt header claiming e.g. 65535×65535 would otherwise reserve gigabytes before a single
-/// byte of pixel data is checked.
+/// A cap on the header's dimensions, which size the buffers (1.12 art stops at 1024×1024).
 const MAX_DIM: u32 = 8192;
 
-/// `wow-blp`'s mip count formula (kept bit-identical, float `log2` and all, so the chain length we
-/// report matches the oracle exactly).
 fn mip_chain_count(width: u32, height: u32, has_mipmaps: bool) -> usize {
     if has_mipmaps {
         let w = (width as f32).log2() as usize;
@@ -125,13 +93,9 @@ fn level_size(width: u32, height: u32, level: usize) -> (u32, u32) {
 }
 
 /// The texel form a [`NativeBlp`] level carries.
-///
-/// A BLP is one of three shapes on disk (module header); only DXTC has a GPU-native form, so the
-/// other two report [`Self::Rgba8Unorm`] and carry decoded pixels. Callers switch on this to pick a
-/// `TextureFormat` and to size a level.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum BlpTexels {
-    /// Decoded pixels — the Raw1 (palettized) and Raw3 (BGRA8) shapes, which have no block form.
+    /// Decoded pixels, from Raw1 or Raw3, which have no block form.
     Rgba8Unorm,
     /// DXT1 blocks (8 bytes per 4x4), `alpha_type` 0. 1-bit alpha at most.
     Bc1,
@@ -142,15 +106,12 @@ pub enum BlpTexels {
 }
 
 impl BlpTexels {
-    /// Is this a block-compressed form (i.e. can it be uploaded to the GPU verbatim)?
+    /// Whether this is a block form, uploadable verbatim.
     pub fn is_block_compressed(self) -> bool {
         !matches!(self, Self::Rgba8Unorm)
     }
 
-    /// How many bytes a `width x height` level occupies in this form.
-    ///
-    /// Block forms round **up** to whole 4x4 blocks, which is why a 2x2 or 1x1 tail mip still costs
-    /// one full block — exactly what the BLP stores for it, and what wgpu expects to receive.
+    /// The bytes a `width x height` level takes; block forms round up to whole 4x4 blocks.
     pub fn level_bytes(self, width: u32, height: u32) -> usize {
         match self {
             Self::Rgba8Unorm => (width as usize) * (height as usize) * 4,
@@ -161,7 +122,6 @@ impl BlpTexels {
         }
     }
 
-    /// The `texpresso` codec for a block form, or `None` for [`Self::Rgba8Unorm`].
     fn codec(self) -> Option<texpresso::Format> {
         match self {
             Self::Rgba8Unorm => None,
@@ -172,13 +132,13 @@ impl BlpTexels {
     }
 }
 
-/// A BLP with its levels in whatever form the file stores them — see [`decode_native`].
+/// A BLP with its levels in the form the file stores them.
 pub struct NativeBlp {
     pub width: u32,
     pub height: u32,
     /// What every entry of `mips` holds.
     pub texels: BlpTexels,
-    /// One buffer per level, level 0 first. Never empty (same guarantee as [`DecodedBlp::mips`]).
+    /// One buffer per level, level 0 first; never empty.
     pub mips: Vec<NativeMip>,
     mip_chain_count: usize,
 }
@@ -187,11 +147,8 @@ pub struct NativeBlp {
 pub struct NativeMip {
     pub width: u32,
     pub height: u32,
-    /// Block bytes (DXTC) or RGBA8 pixels — per [`NativeBlp::texels`]. Always exactly
-    /// [`BlpTexels::level_bytes`] long: a sub-block tail level the header under-stores is
-    /// completed from the bytes that follow it in the file, as the reference copies it
-    /// (`Header::dxt_level_span`), and only a level the file ends inside is zero-padded —
-    /// matching what [`decode`] does before handing blocks to the codec.
+    /// Block bytes or RGBA8 pixels, per [`NativeBlp::texels`], exactly [`BlpTexels::level_bytes`]
+    /// long: a short level is completed from the bytes after it, as the reference reads it.
     pub bytes: Vec<u8>,
 }
 
@@ -212,20 +169,15 @@ struct Header<'a> {
     offsets: Vec<u32>,
     sizes: Vec<u32>,
     palette: &'a [u8],
-    /// The authored chain length, `mip_chain_count(width, height, has_mipmaps)`.
     chain: usize,
 }
 
-/// Parse and bounds-check the BLP2 header, palette and level table. Shared by [`decode`] and
-/// [`decode_native`] so the two can never disagree about what a file says.
+/// Parse and bounds-check the BLP2 header, palette and level table.
 fn parse_header(bytes: &[u8]) -> Result<Header<'_>> {
     if bytes.len() < HEADER_SIZE || &bytes[0..4] != b"BLP2" {
         return Err(Error::NotBlp2);
     }
-    // content @4 (u32; 1 = Direct — we only handle direct, the only kind 1.12 ships).
-    // These reads are already covered by the `HEADER_SIZE` length check above; routed through
-    // `ByteExt` anyway for uniformity (decision 0064) — no future reader should have to ask
-    // "is this offset guarded?".
+    // `content` @4 is unread: 1.12 ships only Direct (1).
     let compression = bytes.u8_at(8).ok_or(Error::Truncated("header"))?;
     let alpha_bits = bytes.u8_at(9).ok_or(Error::Truncated("header"))? as u32;
     let alpha_type = bytes.u8_at(10).ok_or(Error::Truncated("header"))?;
@@ -239,15 +191,12 @@ fn parse_header(bytes: &[u8]) -> Result<Header<'_>> {
         .map(|i| bytes.u32_at(84 + i * 4).ok_or(Error::Truncated("header")))
         .collect::<Result<_>>()?;
 
-    // The corrupt-header guard (see `MAX_DIM`): bound before anything downstream sizes an
-    // allocation from these fields. Zero is left alone — see the decode_dxt/decode_raw1/
-    // decode_raw3 zero-pixel behavior, unchanged from before this migration.
+    // Checked before anything sizes a buffer from them; zero passes.
     if width > MAX_DIM || height > MAX_DIM {
         return Err(Error::DimensionsTooLarge { width, height });
     }
 
-    // BLP2 direct content always carries a 256-entry palette right after the header (used only by
-    // Raw1; present-but-ignored for Raw3/DXT). Read as BGRA bytes.
+    // A 256-entry BGRA palette always follows the header; only Raw1 reads it.
     let palette = bytes
         .get(HEADER_SIZE..HEADER_SIZE + PALETTE_SIZE)
         .ok_or(Error::BadColorMap)?;
@@ -267,8 +216,7 @@ fn parse_header(bytes: &[u8]) -> Result<Header<'_>> {
 }
 
 impl Header<'_> {
-    /// The raw stored bytes of level `level`, or `None` when the chain ends early (some textures
-    /// stop before the formula's count).
+    /// Level `level`'s stored bytes, or `None` where the chain ends before the formula's count.
     fn level_data<'b>(&self, bytes: &'b [u8], level: usize) -> Result<Option<&'b [u8]>> {
         let off = self.offsets[level] as usize;
         let sz = self.sizes[level] as usize;
@@ -281,26 +229,12 @@ impl Header<'_> {
             .ok_or(Error::OutOfBounds { level })
     }
 
-    /// The bytes of DXTC level `level` **as the reference copies them** — `need` bytes from the
-    /// level's file offset, not the `sizes[level]` the header records — or `None` when the chain
-    /// ends early (same rule as [`Self::level_data`]).
-    ///
-    /// The two disagree exactly on the **sub-block tail**. The BLP encoder stores a level as
-    /// `max(1, (w/4)·(h/4))` blocks — ONE block for a 2×16 or a 1×8 level, where the block grid the
-    /// GPU decodes needs four and two. The reference never reads the header's size for a DXT level.
-    /// On its shipped Direct3D default the fill copies each level through the block copier
-    /// `0x5a5780`, `max(4,w)·max(4,h)` bytes flat from `fileImage + mipOffsets[level]`; on the
-    /// OpenGL arm it hands the upload that same pointer (`0x5a8555`, no copy) and `0x59f270` sizes
-    /// the read from the format alone, `bpp · max(4, wL) · max(4, hL) / 8` (`0x59f4e6`–`0x59f515`).
-    /// Either way the GPU gets the full block grid from the level's offset, so a short level is
-    /// completed with the bytes that FOLLOW it in the file: the next levels' own authored blocks
-    /// (wow-re `system/image/scratch/dxt-level-span-law.md`, both arms VERIFIED; decisions
-    /// 2020/2024). Padding the difference with
-    /// zeros instead (an all-zero BC block = colour black, alpha 0) is what turned the far rain
-    /// black: `RainDrop01.blp`'s levels 3 and 4 came out three-quarters and half black, and its
-    /// Mod2x lane reads no alpha (decision 2020, B358/B225). Only a level the FILE itself ends
-    /// inside is left short here, for [`pad_to`] to zero-fill — the reference reads past the file
-    /// into whatever its shared read buffer held before, which is nothing to be faithful to.
+    /// DXTC level `level` as the reference reads it: `bpp·max(4,w)·max(4,h)/8` bytes from the
+    /// level's offset, never the header's size (`0x5a8555` points each level into the file;
+    /// OpenGL sizes the read at `0x59f4e6`–`0x59f515`, Direct3D copies `max(4,w)·max(4,h)` bytes
+    /// via `0x5a5780`). The encoder stores `max(1, (w/4)·(h/4))` blocks, one for a 2×16 level
+    /// whose grid needs four, so a short level takes the next levels' bytes. Deviation: past the
+    /// file's end [`pad_to`] zero-fills, because the reference reads stale buffer bytes there.
     fn dxt_level_span<'b>(
         &self,
         bytes: &'b [u8],
@@ -318,9 +252,8 @@ impl Header<'_> {
         Ok(Some(&bytes[off..end]))
     }
 
-    /// Which block form this file's DXTC levels are in. `alpha_type` 0→DXT1, 1→DXT3, 7→DXT5;
-    /// anything else (a stale byte — e.g. `2` on alpha-less particle atlases) → DXT1, since
-    /// `alpha_bits` already governs whether alpha is meaningful.
+    /// The DXTC form by `alpha_type`. Any other value (a stale `2` on alpha-less particle atlases)
+    /// is DXT1, not an error: `alpha_bits` governs alpha.
     fn dxt_texels(&self) -> BlpTexels {
         match self.alpha_type {
             1 => BlpTexels::Bc2,
@@ -333,15 +266,12 @@ impl Header<'_> {
 /// Decode a BLP2 texture (raw archive bytes) to RGBA8 mip levels.
 pub fn decode(bytes: &[u8]) -> Result<DecodedBlp> {
     let h = parse_header(bytes)?;
-    // Always decode level 0 (blp_to_rgba needs it even when the chain count is 0); then deeper levels
-    // up to the chain count, stopping if the file doesn't carry one.
+    // Level 0 always, then deeper levels up to the chain count while the file carries them.
     let n = h.chain.clamp(1, 16);
 
     let mut mips = Vec::with_capacity(n);
     for level in 0..n {
         let (lw, lh) = level_size(h.width, h.height, level);
-        // DXTC levels span what the reference copies (`dxt_level_span`), not what the header
-        // records — the two differ on the sub-block tail, and the difference was black.
         let data = if h.compression == 2 {
             let texels = h.dxt_texels();
             h.dxt_level_span(bytes, level, texels.level_bytes(lw, lh))?
@@ -372,13 +302,8 @@ pub fn decode(bytes: &[u8]) -> Result<DecodedBlp> {
     })
 }
 
-/// Decode a BLP2 texture **keeping its DXTC blocks verbatim** — the form the reference uploads.
-///
-/// DXTC levels come back as block bytes with [`NativeBlp::texels`] naming the variant; Raw1/Raw3
-/// files, which have no block form, are decoded exactly as [`decode`] would and report
-/// [`BlpTexels::Rgba8Unorm`]. Either way every level is padded to its full
-/// [`BlpTexels::level_bytes`], so a caller can concatenate the chain and hand it to the GPU without
-/// re-deriving sizes.
+/// Decode a BLP2 texture keeping its DXTC blocks verbatim, the form the reference uploads; Raw1
+/// and Raw3 decode as in [`decode`].
 pub fn decode_native(bytes: &[u8]) -> Result<NativeBlp> {
     let h = parse_header(bytes)?;
     let texels = if h.compression == 2 {
@@ -422,12 +347,8 @@ pub fn decode_native(bytes: &[u8]) -> Result<NativeBlp> {
     })
 }
 
-/// Decode one block-compressed level to RGBA8 — the inverse of keeping the blocks.
-///
-/// For a caller that took [`decode_native`]'s passthrough and then found it could not upload it
-/// after all (no BC on the device): it can get the pixels without re-reading and re-parsing the
-/// file. `texels` must be a block form; [`BlpTexels::Rgba8Unorm`] returns `bytes` unchanged, since
-/// that is already the answer.
+/// Decode one block-compressed level to RGBA8, for a device without BC support;
+/// [`BlpTexels::Rgba8Unorm`] returns `bytes` unchanged.
 pub fn decode_level(texels: BlpTexels, width: u32, height: u32, bytes: &[u8]) -> Vec<u8> {
     let Some(fmt) = texels.codec() else {
         return bytes.to_vec();
@@ -438,12 +359,8 @@ pub fn decode_level(texels: BlpTexels, width: u32, height: u32, bytes: &[u8]) ->
     out
 }
 
-/// `data` grown to exactly `need` bytes with zeros (or truncated if the file over-stores).
-///
-/// After `Header::dxt_level_span` this only ever pads a level the FILE ends inside (a truncated
-/// archive) — the sub-block tail the encoder under-stores is completed from the following levels
-/// first, the way the reference does. Zero here is a BC block that decodes to black at alpha 0,
-/// which is why the span comes first (decision 2020).
+/// `data` zero-padded or truncated to exactly `need` bytes. A zero BC block is black at alpha 0,
+/// so a DXTC level is completed from the file first (`Header::dxt_level_span`).
 fn pad_to(data: &[u8], need: usize) -> Vec<u8> {
     let mut out = vec![0u8; need];
     let n = data.len().min(need);
@@ -451,7 +368,7 @@ fn pad_to(data: &[u8], need: usize) -> Vec<u8> {
     out
 }
 
-/// Palettized: 1-byte indices into a 256-entry BGRA palette, then a packed alpha block (`alpha_bits`).
+/// Palettized: 1-byte indices into the BGRA palette, then a packed `alpha_bits` alpha block.
 fn decode_raw1(palette: &[u8], data: &[u8], w: u32, h: u32, alpha_bits: u32) -> Result<Vec<u8>> {
     let px = (w as usize) * (h as usize);
     let indices = data.get(..px).ok_or(Error::Truncated("raw1 indices"))?;
@@ -460,7 +377,7 @@ fn decode_raw1(palette: &[u8], data: &[u8], w: u32, h: u32, alpha_bits: u32) ->
     for i in 0..px {
         let ci = indices[i] as usize;
         let p = ci * 4;
-        // Palette is BGRA: byte0=B, byte1=G, byte2=R. (The fork fix — RGBA reading swaps R↔B.)
+        // The palette is BGRA.
         out[i * 4] = palette[p + 2]; // R
         out[i * 4 + 1] = palette[p + 1]; // G
         out[i * 4 + 2] = palette[p]; // B
@@ -469,7 +386,7 @@ fn decode_raw1(palette: &[u8], data: &[u8], w: u32, h: u32, alpha_bits: u32) ->
     Ok(out)
 }
 
-/// Per-pixel alpha from the packed block. `0` ⇒ opaque (no alpha channel); `1/4/8` ⇒ packed bits.
+/// Pixel `i`'s alpha from a block of 1, 4 or 8 bits per pixel; 0 bits is opaque.
 fn alpha_at(alpha: &[u8], i: usize, alpha_bits: u32) -> u8 {
     match alpha_bits {
         1 => {
@@ -508,9 +425,7 @@ fn decode_raw3(data: &[u8], w: u32, h: u32) -> Result<Vec<u8>> {
     Ok(out)
 }
 
-/// DXTC → RGBA8. The variant comes from [`Header::dxt_texels`]. `data` is the level's span as
-/// the reference copies it (`Header::dxt_level_span`); anything still short of the block size —
-/// a file that ends inside the level — is zero-padded so the level decodes.
+/// DXTC to RGBA8; a level the file ends inside is zero-padded first.
 fn decode_dxt(data: &[u8], w: u32, h: u32, texels: BlpTexels) -> Result<Vec<u8>> {
     let fmt = texels.codec().expect("dxt_texels never returns Rgba8Unorm");
     let blocks = pad_to(data, fmt.compressed_size(w as usize, h as usize));
@@ -523,7 +438,7 @@ fn decode_dxt(data: &[u8], w: u32, h: u32, texels: BlpTexels) -> Result<Vec<u8>>
 mod tests {
     use super::*;
 
-    /// Build a minimal-but-complete BLP2 header (magic..=mip_sizes[16], `HEADER_SIZE` bytes).
+    /// A BLP2 header, magic to `mip_sizes[16]`.
     fn header(
         compression: u8,
         alpha_bits: u8,
@@ -554,9 +469,7 @@ mod tests {
 
     #[test]
     fn corrupt_header_huge_dims_errors_cleanly() {
-        // The fix under test: a header claiming an absurd width/height must fail fast, not size a
-        // multi-gigabyte allocation in decode_dxt. No palette/pixel bytes needed — the dimension
-        // check runs before either is touched.
+        // No palette or pixels: the dimension check runs first.
         let b = header(3, 0, 0, 0, 65535, 65535, [0; 16], [0; 16]);
         assert!(matches!(
             decode(&b),
@@ -565,8 +478,6 @@ mod tests {
                 height: 65535
             })
         ));
-        // Right at the cap is fine (still fails later for lack of palette/pixel bytes, but not on
-        // the dimension check); just over the cap on either axis alone is rejected.
         let b = header(3, 0, 0, 0, MAX_DIM + 1, 4, [0; 16], [0; 16]);
         assert!(matches!(decode(&b), Err(Error::DimensionsTooLarge { .. })));
         let b = header(3, 0, 0, 0, 4, MAX_DIM + 1, [0; 16], [0; 16]);
@@ -575,7 +486,6 @@ mod tests {
 
     #[test]
     fn truncated_header_errors_cleanly() {
-        // Shorter than HEADER_SIZE, even with a valid magic, is rejected before any field read.
         let mut b = vec![0u8; 10];
         b[0..4].copy_from_slice(b"BLP2");
         assert!(matches!(decode(&b), Err(Error::NotBlp2)));
@@ -583,15 +493,13 @@ mod tests {
         assert!(matches!(decode(b"not a blp at all"), Err(Error::NotBlp2)));
     }
 
-    /// Build a DXT-compressed (compression 2) BLP with a real mip chain: 8x8 down to 1x1, so the
-    /// tail levels are the sub-block ones that make block handling interesting.
+    /// A DXTC BLP (compression 2) with an 8x8 to 1x1 chain, so the tail levels are sub-block.
     fn dxt_blp(alpha_type: u8, block_bytes: usize) -> Vec<u8> {
         let mut offsets = [0u32; 16];
         let mut sizes = [0u32; 16];
         let mut payload = Vec::new();
         let base = (HEADER_SIZE + PALETTE_SIZE) as u32;
-        // 8x8, 4x4, 2x2, 1x1 — mip_chain_count(8, 8, true) == 3, so both entry points read the
-        // first THREE levels (8x8, 4x4, 2x2); the 1x1 is stored but past the authored count.
+        // The chain count for 8x8 is 3, so the stored 1x1 is past it and unread.
         for (i, (w, h)) in [(8u32, 8u32), (4, 4), (2, 2), (1, 1)]
             .into_iter()
             .enumerate()
@@ -600,7 +508,7 @@ mod tests {
             let n = blocks * block_bytes;
             offsets[i] = base + payload.len() as u32;
             sizes[i] = n as u32;
-            // Deterministic non-trivial block payload so a byte swap would show.
+            // A non-trivial payload, so a byte swap would show.
             payload.extend((0..n).map(|k| (k as u32 * 37 + i as u32 * 11) as u8));
         }
         let mut b = header(2, 8, alpha_type, 1, 8, 8, offsets, sizes);
@@ -609,10 +517,6 @@ mod tests {
         b
     }
 
-    /// The load-bearing equivalence for the native upload path: `decode_native` must hand back the
-    /// file's blocks *verbatim*, and running those blocks through the codec must reproduce exactly
-    /// what `decode` produces. If these ever diverge, a GPU-uploaded texture stops matching what
-    /// every CPU-side consumer sees.
     #[test]
     fn native_blocks_are_verbatim_and_decode_to_the_same_pixels() {
         for (alpha_type, texels, block_bytes) in [
@@ -632,21 +536,17 @@ mod tests {
 
             for (level, (n, d)) in native.mips.iter().zip(&decoded.mips).enumerate() {
                 assert_eq!((n.width, n.height), (d.width, d.height));
-                // Every level is exactly its full block size — including the 2x2 and 1x1 tails,
-                // which occupy one whole block each.
                 assert_eq!(
                     n.bytes.len(),
                     texels.level_bytes(n.width, n.height),
                     "level {level} block size"
                 );
-                // Verbatim: the bytes are the file's, not re-encoded.
                 let off = native_level_offset(&b, level);
                 assert_eq!(
                     &n.bytes[..],
                     &b[off..off + n.bytes.len()],
                     "level {level} must be the file's own blocks"
                 );
-                // And they decode to exactly what the RGBA path produced.
                 let fmt = texels.codec().unwrap();
                 let mut out = vec![0u8; (n.width as usize) * (n.height as usize) * 4];
                 fmt.decompress(&n.bytes, n.width as usize, n.height as usize, &mut out);
@@ -655,13 +555,11 @@ mod tests {
         }
     }
 
-    /// Where level `i`'s payload starts, read back out of the header we built.
+    /// Where `level`'s payload starts, read back from the header.
     fn native_level_offset(blp: &[u8], level: usize) -> usize {
         u32::from_le_bytes(blp[20 + level * 4..24 + level * 4].try_into().unwrap()) as usize
     }
 
-    /// Raw1/Raw3 have no block form, so the native path decodes them and says so — a caller that
-    /// switches on `texels` gets a correct `Rgba8Unorm` upload rather than garbage.
     #[test]
     fn native_reports_rgba_for_the_shapes_with_no_block_form() {
         let pixel_offset = (HEADER_SIZE + PALETTE_SIZE) as u32;
@@ -685,16 +583,12 @@ mod tests {
         );
     }
 
-    /// A level the header under-stores is completed from the bytes that FOLLOW it in the file —
-    /// the reference's upload (`0x59f4e6`–`0x59f515`: `bpp·max(4,w)·max(4,h)/8` bytes read from
-    /// the level's file offset) — so the concatenated chain a caller uploads is always exactly
-    /// the size wgpu expects, and it is the file's bytes, not zeros. Zeros were the bug: an
-    /// all-zero BC block is black.
+    /// The reference reads `bpp·max(4,w)·max(4,h)/8` bytes from the level's offset
+    /// (`0x59f4e6`–`0x59f515`), whatever the header records.
     #[test]
     fn a_short_level_is_completed_from_the_bytes_that_follow_it() {
         let mut b = dxt_blp(0, 8);
-        // Level 2 is the 2x2 tail — one whole BC1 block. Shrink its recorded size to 3 bytes; the
-        // 1x1 level's 8 bytes follow it in the file.
+        // Level 2, the 2x2 tail, is one BC1 block: record it as 3 bytes, the 1x1's 8 following.
         let short = 3u32;
         b[84 + 2 * 4..88 + 2 * 4].copy_from_slice(&short.to_le_bytes());
         let off = native_level_offset(&b, 2);
@@ -711,7 +605,7 @@ mod tests {
             tail.bytes[short as usize..].iter().any(|&x| x != 0),
             "nothing was zero-filled — that was B358's black"
         );
-        // And decode() reads the same span — the two paths complete identically.
+        // `decode` reads the same span.
         let decoded = decode(&b).unwrap();
         assert_eq!(decoded.mips.len(), native.mips.len());
         let mut out = vec![0u8; 2 * 2 * 4];
@@ -719,15 +613,12 @@ mod tests {
         assert_eq!(out, decoded.mips.last().unwrap().rgba);
     }
 
-    /// **The shipped shape of the bug**, in miniature: a DXT3 texture taller than it is wide,
-    /// whose 2×8 level the encoder stores as ONE block (`max(1, (2/4)·(8/4))`) where the block
-    /// grid needs two. The reference uploads `8·max(4,2)·max(4,8)/8 = 32` bytes from that level's
-    /// offset — the stored block plus the 1×4 level's block after it. `RainDrop01.blp` is this at
-    /// 16×128: its 2×16 and 1×8 levels store 16 bytes each where the grid needs 64 and 32.
+    /// A 2×8 DXT3 level is stored as one block (`max(1, (2/4)·(8/4))`) where the grid needs two;
+    /// the reference reads `8·max(4,2)·max(4,8)/8 = 32` bytes, taking the 1×4 level's block too.
+    /// `RainDrop01.blp` ships this shape at 16×128.
     #[test]
     fn a_sub_block_dxt3_level_spans_into_its_successors_as_the_reference_copies_it() {
-        // 4x16 DXT3: levels 4x16 (4 blocks), 2x8 (grid: 2 blocks; STORED: 1), 1x4 (1 block),
-        // 1x2 (1 block). mip_chain_count(4, 16, true) = 4, so all four are read.
+        // 4x16 DXT3: 4x16 (4 blocks), 2x8 (grid 2, stored 1), 1x4 (1), 1x2 (1); a chain of 4.
         let mut offsets = [0u32; 16];
         let mut sizes = [0u32; 16];
         let mut payload = Vec::new();
@@ -758,12 +649,11 @@ mod tests {
             l1.bytes[16..].iter().all(|&x| x == 0x30),
             "second block: the 1x4 level's, which follows it in the file — never zeros"
         );
-        // The levels that ARE a whole block are untouched by the rule.
+        // Whole-block levels are untouched.
         assert!(native.mips[2].bytes.iter().all(|&x| x == 0x30));
         assert!(native.mips[3].bytes.iter().all(|&x| x == 0x40));
-        // A short level the FILE ends inside is the one case left for the zero pad: the same
-        // texture authored with only its first two levels, the file ending right after the 2x8
-        // level's single stored block — the completion has nothing to read.
+        // A level the file ends inside is zero-padded: the same texture, two levels, ending after
+        // the 2x8's one stored block.
         let mut offsets = [0u32; 16];
         let mut sizes = [0u32; 16];
         offsets[0] = base;
@@ -787,8 +677,7 @@ mod tests {
 
     #[test]
     fn tiny_raw3_decodes_expected_pixels() {
-        // A 2x2 uncompressed BGRA8 (Raw3) image, no mipmaps: the smallest concrete shape decode()
-        // handles. Pixel data sits right after the header + 256-entry BGRA palette.
+        // A 2x2 Raw3 image, no mipmaps; the pixels follow the header and palette.
         let pixel_offset = (HEADER_SIZE + PALETTE_SIZE) as u32;
         let pixel_size = 2 * 2 * 4;
         let mut offsets = [0u32; 16];
@@ -796,8 +685,7 @@ mod tests {
         offsets[0] = pixel_offset;
         sizes[0] = pixel_size;
         let mut b = header(3, 8, 0, 0, 2, 2, offsets, sizes);
-        b.resize(HEADER_SIZE + PALETTE_SIZE, 0); // palette bytes: unused by Raw3, present anyway
-                                                 // Four BGRA8 pixels.
+        b.resize(HEADER_SIZE + PALETTE_SIZE, 0); // the palette, unused by Raw3
         let bgra: &[u8] = &[
             10, 20, 30, 40, // B G R A
             50, 60, 70, 80, //
@@ -809,13 +697,12 @@ mod tests {
         let decoded = decode(&b).expect("valid tiny BLP decodes");
         assert_eq!(decoded.width, 2);
         assert_eq!(decoded.height, 2);
-        assert_eq!(decoded.mip_chain_count(), 0); // no mipmaps: chain formula reports 0
-        assert_eq!(decoded.mips.len(), 1); // level 0 is still decoded regardless
+        assert_eq!(decoded.mip_chain_count(), 0); // no mipmaps
+        assert_eq!(decoded.mips.len(), 1); // level 0 is still decoded
 
         let mip = &decoded.mips[0];
         assert_eq!(mip.width, 2);
         assert_eq!(mip.height, 2);
-        // BGRA -> RGBA per pixel.
         assert_eq!(
             mip.rgba,
             vec![
diff --git a/crates/benilla-buildstamp/Cargo.toml b/crates/benilla-buildstamp/Cargo.toml
index 690ae057..369af53c 100644
--- a/crates/benilla-buildstamp/Cargo.toml
+++ b/crates/benilla-buildstamp/Cargo.toml
@@ -3,12 +3,11 @@ name = "benilla-buildstamp"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "The git build-id stamp emitter shared by the launcher shims' build scripts (decision 0993/1160)"
+description = "The git build-id stamp shared by the launchers' build scripts"
 
 [lints]
 workspace = true
 
 [lib]
-# A build-dependency only. No tests, no bevy, no app deps — it runs inside cargo's build-script
-# pass and must stay trivially cheap to compile.
+# A build-dependency only: it runs in cargo's build-script pass, so it must stay cheap to compile.
 path = "src/lib.rs"
diff --git a/crates/benilla-buildstamp/src/lib.rs b/crates/benilla-buildstamp/src/lib.rs
index a41d69ae..d313954d 100644
--- a/crates/benilla-buildstamp/src/lib.rs
+++ b/crates/benilla-buildstamp/src/lib.rs
@@ -1,63 +1,26 @@
-//! The **build-id stamp emitter** — the `build.rs` body both launcher shims share.
-//!
-//! Two binaries carry the stamp now (`benilla` and `benilla-worldview`, decision 1160), and a
-//! copy-pasted build script is exactly the thing that rots: one shim gets a fix, the other keeps
-//! reporting a sha by a rule that changed. So the script is a function and each shim's `build.rs`
-//! is one line that calls it.
-//!
-//! It stays a **build-dependency of the shims**, never of `benilla-app`: cargo dirties the compile
-//! units of the package that owns a `rerun-if-changed` path on the file's mtime alone, and those
-//! paths move on every commit, rebase and checkout. In a ~30-line shim that costs the shim's
-//! recompile plus one relink; in the app crate it cost ~2 minutes of pure stamp tax per commit
-//! across the gates, which is what decision 0993 measured and moved out.
+//! The build stamp: the `build.rs` body the `benilla` and `benilla-worldview` launcher shims
+//! share. It stays a build-dependency of the shims, never of `benilla-app`: cargo rebuilds the
+//! package that owns a `rerun-if-changed` path whenever that path's mtime moves, and these paths
+//! move on every commit, rebase and checkout.
 
 use std::path::Path;
 use std::process::Command;
 
-/// Stamp the **commit this binary was built from** into the calling package: its `main.rs`
-/// reads the four vars back with `env!` and hands them to `benilla_app`'s entry point as the
-/// `BuildId` resource (`benilla-app/src/build_id.rs` — the runtime side and its two surfaces).
+/// Stamp the commit this binary was built from into the calling package as four `rustc-env`
+/// vars, which its `main.rs` reads back with `env!` into a `BuildId`:
 ///
-/// Why it exists: people run benilla from a clone of the public snapshot repo, and a report ("this
-/// looks wrong", "it crashed here") is only actionable if we know *which* code they ran. A git sha
-/// is the only id that can't drift — the crate version is a permanent `0.1.0` and there are no
-/// releases to number. For a public clone the stamp is the **snapshot** sha, which maps back to the
-/// private commit exactly (`pubsync` tags it `pub/<public-short-sha>`); for our own worktrees it is
-/// the private commit itself.
+/// - `BENILLA_GIT_SHA`: the full sha.
+/// - `BENILLA_GIT_SHORT`: git's own abbreviation of it.
+/// - `BENILLA_GIT_DATE`: the commit date (`%cs`, `YYYY-MM-DD`), not the build date.
+/// - `BENILLA_PROFILE`: the profile directory's name, which tells `ship` from `release` where
+///   cargo's `PROFILE` does not.
 ///
-/// It emits four `rustc-env` vars. The three git ones come back **empty** when git can't answer (a
-/// source zip with no `.git`, or no `git` on PATH), which the runtime side reports as an unknown
-/// build rather than failing to compile:
-///
-/// - `BENILLA_GIT_SHA` — the full 40-char sha (what the panel copies to the clipboard).
-/// - `BENILLA_GIT_SHORT` — git's own abbreviation, so the string matches the `pub/<sha>` tag names
-///   (`pubsync` abbreviates the same way, in the same repo).
-/// - `BENILLA_GIT_DATE` — the commit date (`%cs`, `YYYY-MM-DD`). Committer date, not build date:
-///   it is a property of the sha, so it can never disagree with it.
-///
-/// …plus `BENILLA_PROFILE`, the profile directory name — `debug` / `release` / `ship` (0736's
-/// shipping profile). Cargo's own `PROFILE` var collapses every release-like profile to `release`,
-/// so `ship` and `release` would be indistinguishable; the profile *directory* inside `OUT_DIR`
-/// carries the real name, which is what a "why is this slow" report needs to say.
-///
-/// ## Staleness — the only thing that could make this lie
-///
-/// A stamp is worthless if it can report a commit the binary isn't. The rerun triggers below are
-/// therefore exactly the files that change when HEAD moves: `HEAD` itself (checkout, rebase,
-/// detach) and the ref it names (a commit rewrites `refs/heads/<branch>`, not `HEAD`). Both are
-/// resolved with `git rev-parse --git-path`, which applies the worktree rules — in a `wt.sh` pool
-/// slot `.git` is a *file*, `HEAD` lives in `<primary>/.git/worktrees/<slot>/`, and `refs/heads/*`
-/// stay in the common dir. Only paths that exist are emitted: cargo reruns a build script whose
-/// watched path is *missing* on every build, and every one of those reruns relinks the app crate.
-///
-/// What the stamp deliberately does **not** claim is that the working tree was clean: it names the
-/// commit the build came *from*. A dirty flag can only be as fresh as the last build-script run, so
-/// in the normal dev loop (edit, run, don't stage) it would read "clean" while the binary carried
-/// uncommitted work — a flag that is wrong exactly when it matters. "Which snapshot" is the
-/// question a remote report needs answered, and a bare sha answers it without lying.
+/// The git vars are empty when git cannot answer (no `.git`, no `git` on `PATH`), which the
+/// runtime reports as an unknown build. The rerun triggers are `HEAD` and the ref it names,
+/// resolved with `git rev-parse --git-path` so a linked worktree resolves too; only paths that
+/// exist are emitted, since cargo reruns a build script whose watched path is missing on every
+/// build.
 pub fn emit() {
-    // Build scripts run with the package root as cwd, but be explicit: `-C` makes the git calls
-    // independent of that guarantee.
     let dir = std::env::var("CARGO_MANIFEST_DIR").expect("cargo sets CARGO_MANIFEST_DIR");
     let git = |args: &[&str]| -> Option<String> {
         let out = Command::new("git")
@@ -81,14 +44,12 @@ pub fn emit() {
     };
     watch(git(&["rev-parse", "--git-path", "HEAD"]));
     if let Some(git_ref) = git(&["symbolic-ref", "-q", "HEAD"]) {
-        // The loose ref file, plus `packed-refs` for the freshly-cloned/gc'd repo where the branch
-        // has no loose file at all (a public clone is exactly that).
+        // The loose ref, plus `packed-refs`: a fresh clone's branch has no loose file.
         watch(git(&["rev-parse", "--git-path", &git_ref]));
         watch(git(&["rev-parse", "--git-path", "packed-refs"]));
     }
-    // A stamp that never changes when the rule is edited would be its own kind of stale. The
-    // shim's `build.rs` is watched by cargo automatically; this file is watched because cargo
-    // rebuilds a build script when its build-dependency changes.
+    // An edit to the rule restamps: cargo reruns a build script when `build.rs` or one of its
+    // build-dependencies changes.
     println!("cargo::rerun-if-changed=build.rs");
 
     for (var, args) in [
@@ -98,12 +59,12 @@ pub fn emit() {
     ] {
         println!(
             "cargo::rustc-env={var}={}",
-            git(args).unwrap_or_default() // empty ⇒ "unknown build" at runtime
+            git(args).unwrap_or_default() // empty: an unknown build at runtime
         );
     }
 
-    // `OUT_DIR` is `<target>/[<triple>/]<profile-dir>/build/<pkg>-<hash>/out` — the component
-    // before `build` is the profile directory. Falls back to cargo's coarse `PROFILE`.
+    // `OUT_DIR` is `<target>/[<triple>/]<profile-dir>/build/<pkg>-<hash>/out`; the fallback is
+    // cargo's coarse `PROFILE`.
     let out_dir = std::env::var("OUT_DIR").unwrap_or_default();
     let parts: Vec<_> = Path::new(&out_dir).components().collect();
     let profile = parts
diff --git a/crates/benilla-bytes/Cargo.toml b/crates/benilla-bytes/Cargo.toml
index ba42e121..f9cbae99 100644
--- a/crates/benilla-bytes/Cargo.toml
+++ b/crates/benilla-bytes/Cargo.toml
@@ -3,7 +3,7 @@ name = "benilla-bytes"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "Bounds-checked byte readers + IFF chunk iteration shared by the format parsers — decision 0064"
+description = "Bounds-checked byte readers and IFF chunk iteration shared by the format parsers"
 
 [lints]
 workspace = true
diff --git a/crates/benilla-bytes/src/lib.rs b/crates/benilla-bytes/src/lib.rs
index 9aad5a8a..84a57152 100644
--- a/crates/benilla-bytes/src/lib.rs
+++ b/crates/benilla-bytes/src/lib.rs
@@ -1,21 +1,7 @@
-//! Bounds-checked byte readers + IFF chunk iteration shared by the format parsers
-//! (decision 0064). Three primitives, nothing else:
-//!
-//! - [`ByteExt`] — fallible little-endian accessors on `[u8]`. There is deliberately **no**
-//!   panicking variant: parsers map `None` to their own truncation error with `?`, so an unguarded
-//!   offset is a compile-shape impossibility, not a convention.
-//! - [`chunks`] — the IFF `(magic, payload)` iterator every chunked WoW format walks. **Lenient by
-//!   documented property**: iteration stops cleanly at a truncated 8-byte header, and a payload
-//!   whose declared size overruns the buffer is clamped to the buffer end (real 1.12 art needs the
-//!   tolerance — e.g. the trailing-junk chunks some Classic files carry).
-//! - [`capped`] — the allocation guard for count-driven `Vec::with_capacity`: reserve at most what
-//!   the remaining input could possibly hold, so a corrupt header count can never reserve more
-//!   than the file's own size.
-//!
-//! Magic bytes are yielded exactly as stored (WoW writes IFF magics reversed on disk, so callers
-//! match `b"DHOM"` for MOHD — same as the pre-0064 per-crate iterators).
+//! Bounds-checked byte readers and IFF chunk iteration for the format parsers.
 
-/// Fallible little-endian reads at an offset. `None` iff the read would run past the end.
+/// Little-endian reads at an offset, `None` past the end. There is no panicking variant on
+/// purpose: a parser maps `None` to its own truncation error.
 pub trait ByteExt {
     fn u8_at(&self, o: usize) -> Option<u8>;
     fn u16_at(&self, o: usize) -> Option<u16>;
@@ -57,8 +43,9 @@ impl ByteExt for [u8] {
     }
 }
 
-/// Iterate IFF chunks as `(magic-as-stored, payload)`. See the module doc for the (deliberate)
-/// leniency: truncated header → clean stop; over-declared payload → clamped to the buffer end.
+/// Iterate IFF chunks as `(magic, payload)`, the magic as stored: reversed on disk, so MOHD is
+/// `b"DHOM"`. A truncated header ends iteration and an overrunning payload is clamped to the
+/// buffer end, a tolerance real 1.12 art needs.
 pub fn chunks(b: &[u8]) -> impl Iterator<Item = ([u8; 4], &[u8])> {
     let mut pos = 0usize;
     std::iter::from_fn(move || {
@@ -68,19 +55,16 @@ pub fn chunks(b: &[u8]) -> impl Iterator<Item = ([u8; 4], &[u8])> {
         let magic = [b[pos], b[pos + 1], b[pos + 2], b[pos + 3]];
         let size = b.u32_at(pos + 4)? as usize;
         let start = pos + 8;
-        // `start <= b.len()` (checked above) and `size` came from a u32, so on 64-bit targets the
-        // sum cannot wrap; saturate anyway so the invariant doesn't depend on pointer width.
+        // Saturating, so a 32-bit target cannot wrap either.
         let end = start.saturating_add(size).min(b.len());
         pos = end;
         Some((magic, &b[start..end]))
     })
 }
 
-/// Cap a count-driven reservation by what `avail` remaining bytes could possibly hold, so a corrupt
-/// header can at worst reserve the input's own size. `elem_size` of 0 is a caller bug; treat it as 1
-/// rather than divide by zero. The *count* used for iteration stays the caller's — only the
-/// up-front reservation is capped (a short file then fails at the bounds-checked read, not in the
-/// allocator).
+/// Cap a count-driven reservation at what `avail` bytes could hold, so a corrupt count reserves at
+/// most the input's size; the caller still iterates its own count and fails at the checked read.
+/// An `elem_size` of 0 counts as 1.
 pub fn capped(count: usize, elem_size: usize, avail: usize) -> usize {
     count.min(avail / elem_size.max(1))
 }
diff --git a/crates/benilla-dbc/Cargo.toml b/crates/benilla-dbc/Cargo.toml
index 4bf84425..6a833815 100644
--- a/crates/benilla-dbc/Cargo.toml
+++ b/crates/benilla-dbc/Cargo.toml
@@ -3,7 +3,7 @@ name = "benilla-dbc"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "WDBC (client DBC) reader for WoW 1.12.1 (build 5875) — in-repo, decision 0021"
+description = "WDBC (client DBC) reader for WoW 1.12.1 (build 5875)"
 
 [lints]
 workspace = true
diff --git a/crates/benilla-dbc/src/lib.rs b/crates/benilla-dbc/src/lib.rs
index 37617f42..dea52dcc 100644
--- a/crates/benilla-dbc/src/lib.rs
+++ b/crates/benilla-dbc/src/lib.rs
@@ -1,20 +1,5 @@
-//! A WDBC (client DBC) reader for **WoW 1.12.1 (build 5875)** — in-repo, replacing `wow-cdbc`
-//! (decision 0021).
-//!
-//! A DBC is dead simple: a 20-byte `WDBC` header (record count, field count, record size, string-block
-//! size), then `record_count × record_size` bytes of fixed-width **4-byte** fields, then a string
-//! block. The file carries no column *types*, so the caller supplies a [`Schema`] (its expanded field
-//! count must equal the header's `field_count`); each field is read as `u32`/`i32`/`f32`, or as a
-//! [`StringRef`] offset into the string block. Layouts are validated clean-room against build 5875.
-//!
-//! Proven against `wow-cdbc` over real DBCs during the decision-0021 migration (oracle test in git
-//! history); the catalog loaders in `benilla-formats` (Map/Light/Creature/GameObject/…) pin exact
-//! decoded values end-to-end on every run.
-//!
-//! Byte access goes through `benilla-bytes` (decision 0064): header reads are bounds-checked, the
-//! `record_count × record_size + string_block_size` size arithmetic is overflow-checked (a corrupt
-//! header used to wrap past the parse-time guard and panic on the later re-slice), and record
-//! reservations are capped by what the body could actually hold.
+//! A WDBC reader for WoW 1.12.1: a 20-byte header, `record_count × record_size` bytes of 4-byte
+//! fields, then a string block. The file has no column types; the caller supplies a [`Schema`].
 
 use std::io::{Cursor, Write};
 
@@ -30,8 +15,7 @@ pub enum FieldType {
     String,
 }
 
-/// One schema field: a name, a type, and a repeat `count` (1 for a scalar; N for an inline array, which
-/// occupies N consecutive 4-byte slots).
+/// One schema field; a `count` above 1 is an inline array of that many 4-byte slots.
 #[derive(Debug, Clone)]
 pub struct SchemaField {
     pub name: String,
@@ -82,7 +66,7 @@ impl Schema {
         self.key_field = Some(name.into());
     }
 
-    /// Total 4-byte slots this schema covers (arrays expanded) — must equal the header `field_count`.
+    /// The 4-byte slots covered, arrays expanded; the header's `field_count` must match.
     fn expanded_len(&self) -> usize {
         self.fields.iter().map(|f| f.count).sum()
     }
@@ -134,8 +118,7 @@ pub enum Error {
         file: u32,
     },
     BadStringRef(u32),
-    /// `record_count × record_size + string_block_size` overflows `usize` — a corrupt header, not a
-    /// real file (see decision 0064: this used to wrap silently and panic on the later re-slice).
+    /// `record_count × record_size + string_block_size` overflows `usize`: a corrupt header.
     SizeOverflow,
 }
 
@@ -162,12 +145,7 @@ impl std::error::Error for Error {}
 
 type Result<T> = std::result::Result<T, Error>;
 
-/// Read a little-endian u32, zero-extending any bytes past the end of `b` (a record whose
-/// `record_size` is shorter than `field_count × 4` — see the parse loop). This deliberately differs
-/// from [`ByteExt::u32_at`], which is all-or-nothing (`None` on any out-of-range byte): a short tail
-/// here is a legitimate, previously-observed record shape, not truncation, so it zero-pads instead of
-/// failing. Built on the same bounds-checked primitive (`u8_at`) byte-by-byte so there is no raw
-/// indexing left to panic.
+/// A little-endian u32 whose bytes past the end of `b` read as zero, unlike [`ByteExt::u32_at`].
 fn rd_u32_at(b: &[u8], o: usize) -> u32 {
     let mut bytes = [0u8; 4];
     for (k, slot) in bytes.iter_mut().enumerate() {
@@ -178,12 +156,7 @@ fn rd_u32_at(b: &[u8], o: usize) -> u32 {
     u32::from_le_bytes(bytes)
 }
 
-/// The shared `record_count × record_size (+ string_block_size)` layout arithmetic, checked —
-/// [`Header::record_count`]/`record_size`/`string_block_size` are attacker-controlled `u32`s, and a
-/// corrupt combination must error, never silently wrap past a size guard onto a later panicking
-/// re-slice (decision 0064: this is the verified bug the migration fixes). Both `parse` and
-/// `parse_records` call this one function so the two can never disagree even if the code drifts
-/// later. Returns `(record_bytes_len, record_bytes_len + string_block_size)`.
+/// `(record bytes, record bytes + string block)`, checked: the header's counts are unvalidated.
 fn checked_body_layout(
     record_count: usize,
     record_size: usize,
@@ -194,17 +167,16 @@ fn checked_body_layout(
     Some((record_bytes_len, total))
 }
 
-/// A DBC opened for reading: header parsed, body+strings located, schema optional until applied.
+/// A DBC opened for reading; a [`Schema`] is attached before decoding records.
 pub struct DbcParser<'a> {
     header: Header,
-    /// Everything after the 20-byte header: `record_count × record_size` record bytes + string block.
+    /// Everything after the 20-byte header: the record bytes, then the string block.
     body: &'a [u8],
     schema: Option<Schema>,
 }
 
 impl<'a> DbcParser<'a> {
-    /// Parse the header from a cursor over the whole DBC bytes (position is ignored; the file starts
-    /// with the header). Kept cursor-shaped to match the call sites.
+    /// Parse the header of a whole DBC; the cursor's position is ignored.
     pub fn parse(cursor: &mut Cursor<&'a [u8]>) -> Result<Self> {
         let all: &'a [u8] = cursor.get_ref();
         if all.len() < 20 || &all[0..4] != b"WDBC" {
@@ -256,8 +228,6 @@ impl<'a> DbcParser<'a> {
         let rc = self.header.record_count as usize;
         let rs = self.header.record_size as usize;
         let fc = self.header.field_count as usize;
-        // Same checked arithmetic `parse` used to size-check the header — recomputed here (not
-        // assumed) so the two can never disagree even if the code drifts later.
         let (record_bytes_len, strings_end) =
             checked_body_layout(rc, rs, self.header.string_block_size as usize)
                 .ok_or(Error::SizeOverflow)?;
@@ -271,7 +241,7 @@ impl<'a> DbcParser<'a> {
             .ok_or(Error::Truncated("string block"))?
             .to_vec();
 
-        // Expand the schema into a per-slot type list (arrays → repeated type) + per-slot column names.
+        // One type and one column name per 4-byte slot, arrays expanded.
         let mut types = Vec::with_capacity(fc);
         let mut names = Vec::with_capacity(fc);
         for field in &schema.fields {
@@ -285,11 +255,13 @@ impl<'a> DbcParser<'a> {
             }
         }
 
-        // `rc` comes straight from the header; a corrupt `record_size` of 0 would otherwise let it
-        // pass the size guard unbounded (0 * anything fits). Cap the reservation by what the record
-        // bytes could actually hold — a short body then fails at the bounds-checked read below, not
-        // in the allocator.
-        let mut records = Vec::with_capacity(capped(rc, rs, records_bytes.len()));
+        // A `record_size` of 0 passes the size guard for any count and `rd_u32_at` never fails, so
+        // records claimed at size 0 are refused and the loop runs over what the bytes hold.
+        if rs == 0 && rc > 0 {
+            return Err(Error::Truncated("records claimed at record_size 0"));
+        }
+        let rc = capped(rc, rs, records_bytes.len());
+        let mut records = Vec::with_capacity(rc);
         for r in 0..rc {
             let base = r * rs;
             let mut values = Vec::with_capacity(fc);
@@ -340,8 +312,7 @@ impl RecordSet {
     }
 }
 
-/// Write a record set as CSV (header row of column names, then one row per record; string refs
-/// resolved). Used by the `benilla-extract` CLI. Minimal RFC-4180 quoting.
+/// Write a record set as RFC-4180 CSV: column names, then one row per record, strings resolved.
 pub fn export_to_csv<W: Write>(rs: &RecordSet, mut w: W) -> std::io::Result<()> {
     writeln!(w, "{}", rs.field_names.join(","))?;
     for record in &rs.records {
@@ -372,7 +343,7 @@ fn csv_quote(s: &str) -> String {
 mod tests {
     use super::*;
 
-    /// A minimal WDBC: 20-byte header + record bytes + string block.
+    /// A WDBC: the 20-byte header, the record bytes, the string block.
     fn build_wdbc(
         record_count: u32,
         field_count: u32,
@@ -391,7 +362,6 @@ mod tests {
         b
     }
 
-    /// Two fields per record: `id` (UInt32), `name` (a string-block offset).
     fn id_name_schema() -> Schema {
         let mut s = Schema::new("Test");
         s.add_field(SchemaField::new("id", FieldType::UInt32));
@@ -437,8 +407,6 @@ mod tests {
 
     #[test]
     fn rd_u32_at_zero_extends_short_tail() {
-        // Preserves the pre-0064 semantics exactly: a read that runs past the end zero-pads the
-        // missing bytes rather than failing, unlike `ByteExt::u32_at` (all-or-nothing).
         let b = [0xAA, 0xBB];
         assert_eq!(rd_u32_at(&b, 0), 0x0000_BBAA);
         assert_eq!(rd_u32_at(&b, 1), 0x0000_00BB);
@@ -448,26 +416,20 @@ mod tests {
 
     #[test]
     fn header_size_arithmetic_overflow_errors_cleanly_not_panic() {
-        // Header fields are u32, so on a 64-bit host record_count*record_size+string_block_size can
-        // never actually overflow a 64-bit usize (u32::MAX^2 + u32::MAX < usize::MAX) — the real
-        // trigger is a 32-bit target wrapping in release, which is exactly what decision 0064 flags.
-        // Exercise the shared checked arithmetic directly with usize inputs a real u32 header could
-        // never produce on this host, to pin that it errors instead of silently wrapping.
+        // u32 header fields overflow only a 32-bit usize, so the arithmetic is driven directly.
         assert_eq!(checked_body_layout(usize::MAX, 2, 0), None);
         assert_eq!(checked_body_layout(4, 4, usize::MAX), None);
         assert_eq!(checked_body_layout(usize::MAX, 1, 1), None);
         assert_eq!(checked_body_layout(10, 4, 6), Some((40, 46)));
 
-        // And through the public API: a header whose declared size can't be satisfied by the (valid,
-        // in-bounds) body still errors cleanly rather than panicking on a later re-slice.
+        // Through the public API, an all-zero header parses.
         let bytes = build_wdbc(0, 0, 0, &[], &[]);
         assert!(DbcParser::parse(&mut Cursor::new(bytes.as_slice())).is_ok());
     }
 
     #[test]
     fn truncated_body_errors_cleanly_not_panic() {
-        // Header claims 2 records of 8 bytes + a 10-byte string block, but the body holds only one
-        // record's worth of bytes and no string block at all.
+        // The header claims 2 records of 8 bytes; the body holds one.
         let bytes = build_wdbc(2, 2, 8, &[0u8; 8], &[]);
         let err = DbcParser::parse(&mut Cursor::new(bytes.as_slice()))
             .err()
@@ -495,7 +457,6 @@ mod tests {
 
     #[test]
     fn schema_field_count_must_match_header() {
-        // Header declares 2 fields; a 3-slot schema is rejected before any record is touched.
         let bytes = build_wdbc(1, 2, 8, &[0u8; 8], &[]);
         let parser = DbcParser::parse(&mut Cursor::new(bytes.as_slice())).unwrap();
         let mut wide = Schema::new("Wide");
@@ -510,7 +471,6 @@ mod tests {
 
     #[test]
     fn array_field_expands_to_consecutive_slots() {
-        // One record: a scalar `id` then a 3-wide `coords` array = 4 field slots.
         let mut records = Vec::new();
         records.extend_from_slice(&7u32.to_le_bytes()); // id
         records.extend_from_slice(&10u32.to_le_bytes()); // coords[0]
@@ -528,7 +488,6 @@ mod tests {
             .unwrap()
             .parse_records()
             .unwrap();
-        // Array occupies slots 1..=3, and the expanded column names carry the `[k]` index.
         assert_eq!(
             rs.field_names,
             ["id", "coords[0]", "coords[1]", "coords[2]"]
@@ -564,7 +523,6 @@ mod tests {
 
     #[test]
     fn get_string_handles_bad_ref_and_unterminated_tail() {
-        // A one-field record whose string ref we vary by hand.
         let strings = b"hi\0tail"; // "tail" has no trailing NUL
         let bytes = build_wdbc(1, 1, 4, &0u32.to_le_bytes(), strings);
         let rs = {
@@ -578,9 +536,8 @@ mod tests {
                 .unwrap()
         };
         assert_eq!(rs.get_string(StringRef(0)).unwrap(), "hi");
-        // An offset into an un-terminated run reads to the end of the block.
         assert_eq!(rs.get_string(StringRef(3)).unwrap(), "tail");
-        // Offset == len is the empty string at the very end (in bounds); past len errors.
+        // An offset equal to the length is the empty string; past it errors.
         assert_eq!(rs.get_string(StringRef(strings.len() as u32)).unwrap(), "");
         assert!(matches!(
             rs.get_string(StringRef(strings.len() as u32 + 1)),
@@ -590,8 +547,6 @@ mod tests {
 
     #[test]
     fn csv_export_resolves_strings_and_quotes_per_rfc4180() {
-        // A row with a comma, a quote, and a newline must be wrapped and its quotes doubled; a plain
-        // row stays bare. Two fields: an id and a name that references the string block.
         let strings = b"plain\0a,b\0he said \"hi\"\0line1\nline2\0";
         // offsets: plain@0, "a,b"@6, 'he said "hi"'@10, "line1\nline2"@23
         let mut records = Vec::new();
@@ -617,4 +572,24 @@ mod tests {
              4,\"line1\nline2\"\n";
         assert_eq!(csv, expected);
     }
+
+    /// A 20-byte file claiming `u32::MAX` records of size 0 must not run the loop that many times.
+    #[test]
+    fn zero_record_size_with_records_is_refused_not_iterated() {
+        let bytes = build_wdbc(u32::MAX, 2, 0, &[], &[]);
+        let parser = DbcParser::parse(&mut Cursor::new(bytes.as_slice()))
+            .expect("0 × anything fits the size guard")
+            .with_schema(id_name_schema())
+            .expect("schema matches");
+        assert!(matches!(parser.parse_records(), Err(Error::Truncated(_))));
+        // No records at size 0 still decodes, to nothing.
+        let bytes = build_wdbc(0, 2, 0, &[], &[]);
+        let rs = DbcParser::parse(&mut Cursor::new(bytes.as_slice()))
+            .unwrap()
+            .with_schema(id_name_schema())
+            .unwrap()
+            .parse_records()
+            .unwrap();
+        assert!(rs.records().is_empty());
+    }
 }
diff --git a/crates/benilla-formats/Cargo.toml b/crates/benilla-formats/Cargo.toml
index d018a5ad..e9495141 100644
--- a/crates/benilla-formats/Cargo.toml
+++ b/crates/benilla-formats/Cargo.toml
@@ -9,12 +9,9 @@ description = "WoW 1.12.1 asset-format adapters (MPQ/BLP/DBC/ADT/WDT) and the be
 workspace = true
 
 [features]
-# The dev/player seam (0026, built by 1173/1174). Default-on, so every normal build keeps the
-# instruments; `--no-default-features` is the player build. Here it gates exactly one thing:
-# `install::candidates`' project-folder probe, which bakes THIS source tree's absolute path
-# (decision 1175). EVERY dependent must take this crate with `default-features = false` and
-# re-export `dev`, or feature unification puts `/Users/…` back into a player binary —
-# `scripts/gates.sh`'s `--no-default-features` line is what catches getting that wrong.
+# `dev` gates one thing, `install::candidates`' project-folder probe, which bakes this source
+# tree's path into the binary. Every dependent takes this crate without default features and
+# forwards `dev`, or unification puts the path back into a player build.
 default = ["dev"]
 dev = []
 
@@ -27,15 +24,7 @@ benilla-dbc = { path = "../benilla-dbc" }
 benilla-m2 = { path = "../benilla-m2" }
 benilla-mpq = { path = "../benilla-mpq" }
 benilla-blp = { path = "../benilla-blp" }
-# PNG only, matching every sibling crate. `image`'s DEFAULT features enable `avif`, which drags
-# in ravif -> rav1e -> av-scenechange: a complete AV1 video ENCODER, monomorphized into this
-# crate, for the two calls below that both write a PNG. Cutting it takes this crate's graph from
-# 112 to 48 dependencies and the workspace's from 499 to 466.
-#
-# It is NOT why `cargo play` used to fail to link -- that was rustc #86049, fixed by `lto = "off"`
-# in `[profile.play]` (decision 1698). The tempting story is that rav1e's monomorphized bulk is
-# what tripped it; the evidence says otherwise, since 2 of the 7 poisoned codegen units held only
-# our own DBC catalog loaders. Two independent wins, and this is the smaller one. Decision 1698.
+# PNG only: the default `avif` feature would pull in rav1e, a whole AV1 encoder, to write PNGs.
 image = { version = "0.25", default-features = false, features = ["png"] }
 benilla-wdt = { path = "../benilla-wdt" }
 benilla-wmo = { path = "../benilla-wmo" }
diff --git a/crates/benilla-formats/examples/area_trigger_at.rs b/crates/benilla-formats/examples/area_trigger_at.rs
index d2bb3f95..df358770 100644
--- a/crates/benilla-formats/examples/area_trigger_at.rs
+++ b/crates/benilla-formats/examples/area_trigger_at.rs
@@ -1,23 +1,12 @@
-//! Where an area trigger actually **is**, and how to walk into it:
-//! `cargo run -p benilla-formats --example area_trigger_at -- <id|map> [id|map…]`
+//! Each area trigger's volume, with a `.go` spot outside it and the facing that walks you in.
+//! `cargo run -p benilla-formats --example area_trigger_at -- <id|map:N>...`
 //!
-//! The client's half of every portal is pure geometry (`crate::area_trigger`'s law), and that
-//! geometry lives only in `AreaTrigger.dbc` — the server's `areatrigger_teleport` row names the
-//! *destination* but never the volume you have to cross to reach it. So a probe that wants to
-//! reproduce a portal the way a player meets it — **walking in**, which the module's own warning
-//! says is not the same as a `.go` that lands inside — has no way to aim without this.
-//!
-//! Prints each row's volume (sphere radius, or the oriented box) plus a ready-made `.go` for a spot
-//! `APPROACH` yards **outside** it on the box's own axis, and the facing that then walks you
-//! through. An argument about whether a portal fired is otherwise unfalsifiable: landing inside the
-//! volume races the server's re-check and is silently ignored about one time in six (measured, see
-//! `crate::area_trigger`).
-//!
-//! Output is Blizzard-derived; pipe it to the scratchpad, never into the repo.
+//! The volume lives only in `AreaTrigger.dbc`; the server's teleport row holds the destination. A
+//! `.go` that lands inside races the server's re-check against its stored position and is
+//! sometimes ignored, so a portal is tested by walking in.
+//! Output is Blizzard data: never commit it.
 
-/// How far outside the volume to park the approach `.go`, in yards. Far enough that the trigger is
-/// unambiguously *not* yet entered (so the walk-in is a real crossing), close enough that a few
-/// seconds of held-forward covers it.
+/// Yards outside the volume for the approach spot.
 const APPROACH: f32 = 12.0;
 
 fn main() -> anyhow::Result<()> {
@@ -47,7 +36,7 @@ fn main() -> anyhow::Result<()> {
                     "id {:5}  map {:3}  SPHERE r={:.1} at ({x:.2}, {y:.2}, {z:.2})",
                     r.id, r.map_id, r.radius
                 );
-                // A sphere has no authored axis; approach along -Y, the arbitrary but stated choice.
+                // A sphere has no authored axis: approach along -Y, an arbitrary choice.
                 let sy = y + r.radius + APPROACH;
                 println!(
                     "        walk in:  .go xyz {x:.2} {sy:.2} {z:.2} {}   then face -Y (yaw {:.3}) and hold forward",
diff --git a/crates/benilla-formats/examples/batch_alpha.rs b/crates/benilla-formats/examples/batch_alpha.rs
index 3fc405af..42248464 100644
--- a/crates/benilla-formats/examples/batch_alpha.rs
+++ b/crates/benilla-formats/examples/batch_alpha.rs
@@ -1,12 +1,7 @@
-//! Print every render batch's **animated material alpha** across a named sequence — the factor the
-//! renderer multiplies into the instance's render alpha (`A = instanceAlpha × colourAlpha × weight`).
-//!
+//! Every render batch's animated alpha over one sequence, `colourAlpha × weight` in
+//! `A = instanceAlpha × colourAlpha × weight`. A batch that never reaches exactly 1.0 stays on the
+//! fade blend twin, which writes depth even for a `no_depth_write` batch (M2 render flag 0x10).
 //! `cargo run -p benilla-formats --example batch_alpha -- 'Creature\Voidwalker\Voidwalker.m2' 0`
-//!
-//! The number that matters is whether a batch ever reads **exactly 1.0**: benilla swaps a faded
-//! entity onto its `AlphaMode::Blend` twin whenever `alpha < 1.0`, and that twin forces depth-write
-//! ON. A batch whose authored weight never reaches 1.0 therefore never returns to the steady
-//! material — so a `no_depth_write` batch (M2 flag 0x10) starts writing depth it must never write.
 
 fn main() -> anyhow::Result<()> {
     let mut args = std::env::args().skip(1);
diff --git a/crates/benilla-formats/examples/batch_lit.rs b/crates/benilla-formats/examples/batch_lit.rs
index 60cde3ad..2e718b1d 100644
--- a/crates/benilla-formats/examples/batch_lit.rs
+++ b/crates/benilla-formats/examples/batch_lit.rs
@@ -1,15 +1,8 @@
-//! Print every render batch's **lighting-relevant material state** — the UNLIT (0x01) / UNFOGGED
-//! (0x02) render flags as our reader resolves them, beside the blend mode and texture.
-//!
-//! `cargo run -p benilla-formats --example batch_lit -- 'Interface\Glues\Models\UI_Tauren\UI_Tauren.m2'`
-//!
-//! Built for B121: wow-re's glue backdrop finding is that a glue scene's ground is a multi-layer
-//! stack whose overlay layers are authored **UNLIT** (drawn fullbright, `colour = c28[0]·E_SH +
-//! c28[1]` with `c28[0] = 0`), which is why UI_Tauren can author no ambient-fill light and still
-//! show a lit ground in the reference. The question this answers is the one a grep cannot: whether
-//! the flag survives *our* batch reader's render-flag indexing to the `RenderSubmesh` the material
-//! builder consumes. A batch printed `LIT` here that the asset authors UNLIT is a reader bug; the
-//! asset's own flag table is a separate read (the render-flag array at header 0x84).
+//! Every render batch's UNLIT (0x01) and UNFOGGED (0x02) flags as our reader resolves them, with
+//! blend mode and texture. A batch printed `lit` that the asset authors UNLIT (the render-flag
+//! array at header 0x84) is a reader bug. Glue-scene ground overlays are authored UNLIT and drawn
+//! fullbright (`0x70c190`), which is how UI_Tauren's ground is lit with no ambient light.
+//! `cargo run -p benilla-formats --example batch_lit -- <m2 path>`
 
 fn main() -> anyhow::Result<()> {
     let virt = std::env::args()
diff --git a/crates/benilla-formats/examples/clutter_cut.rs b/crates/benilla-formats/examples/clutter_cut.rs
index 36f71d69..6e65e4d9 100644
--- a/crates/benilla-formats/examples/clutter_cut.rs
+++ b/crates/benilla-formats/examples/clutter_cut.rs
@@ -1,35 +1,13 @@
-//! **How the ground-clutter fade boundary cuts** — pixel by pixel, or leaf by leaf?
-//!
+//! Whether the ground-clutter fade erodes a tuft or flips whole leaves, per detail atlas and mip.
 //! `cargo run -p benilla-formats --example clutter_cut [substring]`
 //!
-//! The detail-doodad draw alpha-tests `texel.a × ramp(view_depth)` against `detailDoodadAlpha`
-//! (128/255), so as the ramp falls the surviving set is `{ texel.a ≥ 0.502 / ramp }`. Whether that
-//! reads as a tuft *eroding* — the boundary sweeping through a leaf a pixel at a time — or as the
-//! leaf *flipping whole* is decided entirely by the alpha distribution **at the mip the tuft is
-//! sampled at**. The alpha arithmetic is settled and identical either way, so when the cut looks
-//! wrong the answer is in what is being cut, not in the cutting.
-//!
-//! Per atlas, per mip level, three numbers:
-//!
-//! * **`distinct`** — how many distinct alpha values the level carries. **`2` means binary**: the
-//!   product `a × ramp` is then either `0` or `ramp`, so the alpha test degenerates to a global
-//!   on/off and *every texel of every leaf crosses the threshold at the same view depth*. No
-//!   erosion is possible at such a level, at any distance, ever.
-//! * **coverage** across the fade band — the share of the atlas still drawn at each depth. Sliding
-//!   down = the tuft erodes. Holding flat then dropping to zero = the tuft pops.
-//! * **cliff** — how much of the still-drawn coverage goes in the last 0.2 yd before the crossing.
-//!   100% means everything that was left leaves in one step.
-//!
-//! The header line also prints the BLP's own `compression / alpha_bits / alpha_type / has_mips`,
-//! because the shipped art is not uniform: some detail atlases carry a properly averaged mip
-//! pyramid and some carry a **binary-thresholded** one, and the two behave completely differently
-//! at the boundary. Parsed inline from the documented BLP2 layout rather than through the decoder,
-//! so this reports what the *file* says independently of how we read it.
+//! The draw alpha-tests `texel.a × ramp(view_depth)` against 128/255, so the alpha distribution at
+//! the sampled mip decides the cut: a level with only 2 distinct alphas crosses all at once.
 
 use std::collections::BTreeSet;
 
-/// The reference's ramp (wow-re `terrain/scratch/detail-doodad-distance-fade.md`): a 64-texel
-/// CLAMP/LINEAR table read at texel centres, capped at texel 0's `252/255`.
+/// The reference's ramp (`0x6b1b6e`): a 64-texel CLAMP/LINEAR table read at texel centres, capped
+/// at texel 0's `252/255`.
 fn ramp(view_depth: f32, far: f32) -> f32 {
     let near = far * 0.75;
     let u = (view_depth - near) / (far - near);
@@ -39,14 +17,11 @@ fn ramp(view_depth: f32, far: f32) -> f32 {
 /// The detail-doodad alpha-test reference (`detailDoodadAlpha` = 128).
 const CUTOUT: f32 = 128.0 / 255.0;
 
-/// Where in the band to sample coverage — clustered at the 61.11 yd crossing, where even a fully
-/// opaque texel fails the test and the whole question lives.
+/// Depths to sample coverage at, clustered at 61.11 yd, where even an opaque texel fails the test.
 const BANDS: [f32; 8] = [52.5, 54.0, 56.0, 58.0, 60.0, 61.0, 61.1, 61.2];
 
-/// What the BLP2 header says about itself: `compression` (1 = palettized, 2 = DXT, 3 = BGRA8),
-/// `alpha_bits`, `alpha_type` (DXT sub-form: 1 = DXT3, 7 = DXT5) and the `has_mipmaps` byte at
-/// offset 0x0B — whose value tracks, in the shipped detail art, whether the mip chain is averaged
-/// or thresholded.
+/// The BLP2 header's `compression` (1 palettized, 2 DXT, 3 BGRA8), `alpha_bits`, `alpha_type`
+/// (1 DXT3, 7 DXT5) and `has_mips` (0x0B), which in the detail art tracks a thresholded chain.
 fn blp_header(bytes: &[u8]) -> Option<(u8, u8, u8, u8)> {
     (bytes.len() >= 20 && &bytes[0..4] == b"BLP2")
         .then(|| (bytes[8], bytes[9], bytes[10], bytes[11]))
@@ -58,7 +33,6 @@ fn main() -> anyhow::Result<()> {
     let mut chain = benilla_formats::open_chain(&data)?;
     let catalog = benilla_formats::load_ground_effect_catalog(&mut chain, true)?;
 
-    // Every distinct detail texture the catalog can place.
     let mut models: BTreeSet<String> = BTreeSet::new();
     for id in 0..4096u32 {
         if let Some(e) = catalog.effect(id) {
@@ -103,9 +77,7 @@ fn main() -> anyhow::Result<()> {
             None => println!("\n{name}"),
         }
 
-        // What an AVERAGED chain would carry, for comparison — mip0's alpha box-filtered down.
-        // This is the control for a binary chain: it says how much of the flat coverage is the
-        // art's own and how much is the authored mip pyramid throwing the gradient away.
+        // The control: mip0's alpha box-filtered down, what an averaged chain would carry.
         let mip0_alpha: Vec<u8> = mips.mips[0]
             .as_chunks::<4>()
             .0
@@ -174,8 +146,6 @@ fn main() -> anyhow::Result<()> {
                 "  mip{i} {w:3}x{h:3} distinct {distinct:<4} [{}]  cliff@61 {cliff:3.0}%",
                 covs.join(" ")
             );
-            // The averaged control, printed only where the authored level is binary — that is the
-            // only case where the two can disagree, and seeing them side by side is the point.
             if i > 0 && distinct <= 2 {
                 if let Some(avg) = averaged.get(i) {
                     let mut seen = [false; 256];
diff --git a/crates/benilla-formats/examples/clutter_size.rs b/crates/benilla-formats/examples/clutter_size.rs
index 77596e88..23ac95c2 100644
--- a/crates/benilla-formats/examples/clutter_size.rs
+++ b/crates/benilla-formats/examples/clutter_size.rs
@@ -1,28 +1,17 @@
-//! **How big is one tuft, and how much DEPTH does it span?** — the geometry half of the
-//! "why does the fade cut leaf-by-leaf instead of pixel-by-pixel" question.
-//!
-//! `cargo run -p benilla-formats --example clutter_size`
-//!
-//! The fade boundary is a **plane** at a fixed view depth (the reference texgens camera-space Z).
-//! Whether that plane *slices* a tuft — some of it drawn, the rest gone, a per-pixel cut — or
-//! passes it by in a single frame depends on how much view depth one tuft occupies. A tuft that
-//! spans 1 yd of depth is sliced for as long as it takes the player to walk 1 yd. A tuft that
-//! spans 5 cm is, for practical purposes, either wholly in or wholly out: it pops.
-//!
-//! So this prints, per detail model: the world-space bounding box, the tuft's **depth span at the
-//! worst yaw** (its horizontal diagonal — the widest it can present to the camera), and the
-//! screen-space size that implies at the 61.11 yd cutout crossing.
+//! Each detail model's size and the view depth one tuft spans. The fade boundary is a plane at a
+//! fixed view depth (the reference texgens camera-space Z), so a deep tuft is sliced and a thin
+//! one pops. `cargo run -p benilla-formats --example clutter_size`
 
 use std::collections::BTreeSet;
 
-/// Vertical FOV benilla's camera runs at (Bevy's `PerspectiveProjection` default, ≈ the
-/// reference's 44.1°) over a 1080-tall viewport — the same basis `clutter_state` uses.
+/// Pixels per yard at `distance` for benilla's 45° vertical FOV (the reference's is ≈44.1° at
+/// 16:9) on a 1080-tall viewport, the same basis as `clutter_state`.
 fn px_per_yard(distance: f32) -> f32 {
     let fov: f32 = std::f32::consts::PI / 4.0;
     (1080.0 / 2.0) / ((fov / 2.0).tan() * distance)
 }
 
-/// Where the `detailDoodadAlpha` = 128 cutout erases even a fully-opaque texel.
+/// The view depth where the 128/255 cutout erases even an opaque texel.
 const CROSSING: f32 = 61.113;
 
 fn main() -> anyhow::Result<()> {
@@ -109,17 +98,10 @@ fn main() -> anyhow::Result<()> {
          the per-pixel slice. Below roughly a tenth of a yard it is a single-frame pop instead."
     );
 
-    // **Which mip a tuft is sampled at, and why the answer moves with the window.** This is the
-    // number the whole look turns on: the shipped Elwynn/Westfall/AeriePeaks atlases carry a binary
-    // alpha pyramid, and a fragment can only hold full alpha — and so die at the same depth as
-    // every other fragment of its leaf — inside a 2x2 all-opaque texel neighbourhood. Those run out
-    // between mip 2 and mip 3 (wow-re counts 179/56/10/0/0/0 for levels 0-5 on the dominant Elwynn
-    // cell), so sampling past ~3 erodes continuously and sampling below it takes leaves whole.
-    //
-    // The reference's `+0.25` stage-0 LOD bias buys a quarter of a mip toward that cliff — but the
-    // sample LOD falls as the viewport grows, so the SAME bias lands differently on a bigger
-    // window. wow-re measured the reference itself at lambda 2.9-3.3 in a 1152x648 capture and
-    // lambda ~2.45 at 1920x1080, i.e. the reference pops leaf-by-leaf at a modern resolution too.
+    // The sampled mip decides the cut: on the binary-alpha atlases a fragment keeps full alpha only
+    // inside an all-opaque 2x2 neighbourhood, which runs out between mip 2 and 3, so past ~3 a tuft
+    // erodes and below it leaves cross whole. The reference biases stage 0 by +0.25 (`0x6813d0`);
+    // its lambda was measured at 2.9-3.3 at 1152x648, and ~2.45 at 1920x1080 is computed from that.
     const DENSITY: f32 = 100.0; // texels per yard, the median from `clutter_state`
     println!("\nsampled mip at the {CROSSING:.1} yd crossing (median {DENSITY:.0} texels/yd art):");
     for height in [648.0f32, 1080.0, 1440.0, 2160.0] {
diff --git a/crates/benilla-formats/examples/clutter_state.rs b/crates/benilla-formats/examples/clutter_state.rs
index bf7b560e..231df571 100644
--- a/crates/benilla-formats/examples/clutter_state.rs
+++ b/crates/benilla-formats/examples/clutter_state.rs
@@ -1,15 +1,8 @@
-//! Dump the **render state and texture alpha profile** of every ground-clutter (detail-doodad) model
-//! the `GroundEffect*` catalog resolves — the inputs benilla's clutter draw derives its material from.
-//!
+//! Every ground-clutter model's batch render state and each detail texture's alpha per mip, the
+//! inputs to the ~70 yd clutter fade. The reference's detail pass (`0x6b2b80`) ignores the batches'
+//! blend and two-sidedness and forces one state for every tuft; the fade multiplies the texture
+//! alpha, so its per-mip distribution is the fade's shape.
 //! `cargo run -p benilla-formats --example clutter_state`
-//!
-//! Two questions it answers, both load-bearing for the ~70 yd distance fade:
-//!   * what **blend mode / two-sidedness** each detail M2's batches author — the reference's
-//!     detail-doodad pass (`0x6b2b80`) ignores these and forces one state for every tuft, so a
-//!     per-batch value benilla passes through is a divergence to see, not to assume;
-//!   * how each detail texture's **alpha is distributed per mip level** — a cutout whose alpha is
-//!     binary (0/255) snaps out of an alpha test all at once, while a smoothly-distributed one
-//!     erodes gradually. The fade multiplies this alpha, so the distribution *is* the fade's shape.
 
 use std::collections::{BTreeMap, BTreeSet};
 
@@ -18,8 +11,7 @@ fn main() -> anyhow::Result<()> {
     let mut chain = benilla_formats::open_chain(&data)?;
     let catalog = benilla_formats::load_ground_effect_catalog(&mut chain, true)?;
 
-    // Every distinct model the catalog can place. `GroundEffectCatalog` exposes rows by id only, so
-    // sweep the id space the DBC uses (ids are small and dense; a miss costs one hash lookup).
+    // Every distinct model the catalog can place; it exposes rows by id only, so sweep the ids.
     let mut models: BTreeSet<String> = BTreeSet::new();
     for id in 0..4096u32 {
         if let Some(e) = catalog.effect(id) {
@@ -72,8 +64,7 @@ fn main() -> anyhow::Result<()> {
         }
     }
     println!("\nbatch blend modes: {blends:?}");
-    // Screen-space mip level per distance: the vertical FOV benilla's camera uses (Bevy's
-    // `PerspectiveProjection` default, ~= the reference's 44.1 deg) over a 1080-tall viewport.
+    // Mip level per distance, for benilla's 45° vertical FOV on a 1080-tall viewport.
     let fov: f32 = std::f32::consts::PI / 4.0;
     let px_per_yard = |d: f32| (1080.0 / 2.0) / ((fov / 2.0).tan() * d);
     densities.sort_by(f32::total_cmp);
@@ -137,9 +128,8 @@ fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
-/// Texels-per-yard for a batch: the atlas footprint its UVs cover divided by the world size its
-/// geometry covers. With the screen-space pixels-per-yard at a distance this gives the mip level the
-/// GPU selects there — and the mip level decides the alpha the cutout test sees.
+/// Texels per yard for a batch, its UV span in atlas texels over its world span; against pixels per
+/// yard at a distance it gives the mip sampled there.
 fn texel_density(sub: &benilla_formats::RenderSubmesh, atlas: f32) -> Option<f32> {
     if sub.positions.is_empty() || sub.uvs.len() != sub.positions.len() {
         return None;
diff --git a/crates/benilla-formats/examples/dbc_head.rs b/crates/benilla-formats/examples/dbc_head.rs
index 0dd123eb..a01fe286 100644
--- a/crates/benilla-formats/examples/dbc_head.rs
+++ b/crates/benilla-formats/examples/dbc_head.rs
@@ -1,5 +1,4 @@
-//! Throwaway: dump a DBC's header (record count / field count / record size) and the first rows'
-//! raw dwords, so a claimed column offset can be checked against the real shipped file.
+//! Each named DBC's header and first rows' raw dwords, to check a column offset against the file.
 fn main() -> anyhow::Result<()> {
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = benilla_formats::open_chain(&data)?;
diff --git a/crates/benilla-formats/examples/dump_anim_names.rs b/crates/benilla-formats/examples/dump_anim_names.rs
index 451571c7..0afeb0fd 100644
--- a/crates/benilla-formats/examples/dump_anim_names.rs
+++ b/crates/benilla-formats/examples/dump_anim_names.rs
@@ -1,6 +1,5 @@
-//! Session probe: print AnimationData.dbc rows (id, name, weapon flags, fallback) —
-//! `cargo run -p benilla-formats --example dump_anim_names <Data-dir> [id ...]`. Without ids,
-//! prints all 208 rows. Built for the bowstring round (which sequences do bow M2s carry).
+//! `AnimationData.dbc` rows (id, name, weapon flags, fallback), all of them without ids.
+//! `cargo run -p benilla-formats --example dump_anim_names <Data-dir> [id ...]`
 
 fn main() {
     let mut args = std::env::args().skip(1);
diff --git a/crates/benilla-formats/examples/dump_bone_keys.rs b/crates/benilla-formats/examples/dump_bone_keys.rs
index 95ee8f3e..2002c8f4 100644
--- a/crates/benilla-formats/examples/dump_bone_keys.rs
+++ b/crates/benilla-formats/examples/dump_bone_keys.rs
@@ -1,7 +1,6 @@
-//! Session probe: which bones carry keys in a given sequence — `cargo run -p benilla-formats
-//! --example dump_bone_keys <file.m2> <anim_id> [bone ...]`. With bone indices, prints their
-//! key counts + first rotation keys; without, lists every keyed bone. Extract the file first
-//! via `mpqx` (benilla-mpq). Built for the nocked-ammo RE round (decision 2273 follow-up).
+//! Which bones carry keys in one sequence, with their first keys; bone indices narrow the list.
+//! `cargo run -p benilla-formats --example dump_bone_keys <file.m2> <anim_id> [bone ...]`, the
+//! file extracted first with `mpqx`.
 
 fn main() {
     let mut args = std::env::args().skip(1);
@@ -64,9 +63,7 @@ fn main() {
                     q[0], q[1], q[2], q[3]
                 );
             }
-            // T/S values too, not just counts — for a flare or a rise the VALUES are the
-            // effect (the gseqdump lesson, here for sequence keys), and per-axis (non-)uniformity
-            // of a scale key is load-bearing for the billboard law's per-axis preserve.
+            // Translation and scale values, not only counts: a billboard preserves scale per axis.
             for (t, v) in bk.translation.iter().take(8) {
                 println!(
                     "    trans t={t:.3} ({:+.3},{:+.3},{:+.3})",
diff --git a/crates/benilla-formats/examples/dump_emitters.rs b/crates/benilla-formats/examples/dump_emitters.rs
index 388fe798..80cb059d 100644
--- a/crates/benilla-formats/examples/dump_emitters.rs
+++ b/crates/benilla-formats/examples/dump_emitters.rs
@@ -1,12 +1,7 @@
-//! Print a model's particle-emitter records — the authored numbers to hold a live
-//! `WOW_PARTICLE_CENSUS` line against: `cargo run -p benilla-formats --example dump_emitters --
-//! 'World\...\RubyCrystalLarge01.m2'`.
-//!
-//! The pair is the check that matters (decision 0653): the census says how many particles are
-//! *live*, this says how many the file asks for (`rate × lifespan`), and the over-life ramp says
-//! how big they get. A mismatch is our sim's bug; a match moves the question to the look.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! A model's particle-emitter records, the authored side of a live `WOW_PARTICLE_CENSUS` line:
+//! the file asks for `rate × lifespan` live particles, and a census that disagrees is our bug.
+//! `cargo run -p benilla-formats --example dump_emitters -- 'World\...\RubyCrystalLarge01.m2'`
+//! Output is Blizzard data: never commit it.
 
 fn main() -> anyhow::Result<()> {
     let virt = std::env::args()
diff --git a/crates/benilla-formats/examples/dump_file.rs b/crates/benilla-formats/examples/dump_file.rs
index 4336fb5e..7d123e5f 100644
--- a/crates/benilla-formats/examples/dump_file.rs
+++ b/crates/benilla-formats/examples/dump_file.rs
@@ -1,7 +1,6 @@
-//! Dump any file from the 5875 patch chain to stdout — the generic MPQ extractor for
-//! reference reads (FrameXML sources, DBC layouts): `cargo run -p benilla-formats
-//! --example dump_file -- 'Interface\FrameXML\TradeSkillFrame.lua'`. Output is Blizzard
-//! data — pipe it to the scratchpad, never into the repo.
+//! Any file from the patch chain to stdout, such as a FrameXML source or a DBC.
+//! `cargo run -p benilla-formats --example dump_file -- 'Interface\FrameXML\TradeSkillFrame.lua'`
+//! Output is Blizzard data: never commit it.
 
 use std::io::Write;
 
diff --git a/crates/benilla-formats/examples/dump_model_anim.rs b/crates/benilla-formats/examples/dump_model_anim.rs
index 4d02a796..4e2dbc92 100644
--- a/crates/benilla-formats/examples/dump_model_anim.rs
+++ b/crates/benilla-formats/examples/dump_model_anim.rs
@@ -1,19 +1,8 @@
-//! What can this model move, at all? Print the [`M2AnimSummary`](benilla_formats::M2AnimSummary)
-//! — every animation channel family — plus the texture-transform (UV-scroll) tracks, for one M2 or
-//! for every M2 whose path matches a substring:
-//!
-//! ```text
-//! cargo run -p benilla-formats --example dump_model_anim -- 'World\...\RubyCrystalLarge01.m2'
-//! cargo run -p benilla-formats --example dump_model_anim -- maraudon      # every match
-//! ```
-//!
-//! This is the **falsifier for a flicker report** (decision 0653): if the summary says a model is
-//! fully static and the screen shows it changing every frame, the change is not coming from the
-//! model, and the hunt moves to what is drawn *over* it (particles, a second doodad) or to the
-//! renderer. Answering that for the Maraudon crystal took one run of this and one of
-//! `WOW_NO_PARTICLES=1`.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! Every animation channel family a model has ([`M2AnimSummary`](benilla_formats::M2AnimSummary))
+//! and its texture-transform tracks, for one M2 or each animated M2 matching a substring. A fully
+//! static model that changes on screen is being changed by something drawn over it, or by the
+//! renderer. Output is Blizzard data: never commit it.
+//! `cargo run -p benilla-formats --example dump_model_anim -- <m2 path | substring>`
 
 use std::io::Cursor;
 
@@ -24,8 +13,7 @@ fn main() -> anyhow::Result<()> {
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = benilla_formats::open_chain(&data)?;
 
-    // An exact path dumps in full; anything else is a substring sweep that prints only the models
-    // with something to say (a listing of "all static" is noise when you asked about a zone).
+    // An exact path dumps in full; a substring sweep skips fully static models.
     let exact = chain.contains(&arg);
     let names: Vec<String> = if exact {
         vec![arg]
diff --git a/crates/benilla-formats/examples/emdump.rs b/crates/benilla-formats/examples/emdump.rs
index ff93abf7..bfa0f504 100644
--- a/crates/benilla-formats/examples/emdump.rs
+++ b/crates/benilla-formats/examples/emdump.rs
@@ -1,15 +1,6 @@
-//! `emdump <internal\path.m2>` — every particle emitter one model authors, one line each.
-//!
-//! The per-emitter counterpart to `benilla-extract partcensus`, which answers "which models in the
-//! corpus carry emitters matching this flag mask?" but never what an individual emitter *is*. B16
-//! needed the other direction — the voidwalker's eye glow is emitters 1 and 2 of four, bone 60/61,
-//! flags `0x0001` (plain anchored), `Add`/`GLOWBALL.BLP` — and reading that off a hex dump by hand
-//! is exactly the kind of asset fact that should be one command.
-//!
-//! The header line carries the model's **reach** (how far its own transparent-pass batches sort
-//! from its origin — `m2_owner_reach`) and the `Transparent3d` draw-order rung it produces
-//! (`owner_last_rung`): the rung is what keeps a model's effects drawing after its own transparent
-//! batches, and it is sized from that number, so the two belong on screen together.
+//! Every particle emitter one model authors, one line each, under the model's reach
+//! (`m2_owner_reach`) and the `Transparent3d` rung sized from it (`owner_last_rung`), which keeps
+//! its effects drawing after its own transparent batches. `emdump <internal\path.m2>`
 
 fn main() -> anyhow::Result<()> {
     let virt = std::env::args().nth(1).unwrap();
@@ -18,8 +9,7 @@ fn main() -> anyhow::Result<()> {
     let bytes = chain.read_file(&virt)?;
     let dir = virt.rsplit_once('\\').map_or("", |(d, _)| d);
     let subs = benilla_formats::parse_m2_render_submeshes(&bytes, dir, &[]).unwrap_or_default();
-    // The renderer's own bound and rung, not a re-derivation of them: a survey tool has to print
-    // what the renderer will actually do.
+    // The renderer's own bound and rung, not a re-derivation of them.
     let reach = benilla_formats::m2_owner_reach(&subs);
     let rung = benilla_formats::owner_last_rung(reach);
     println!("{virt}: reach {reach:.3} yd -> draw-order rung {rung:.0}");
diff --git a/crates/benilla-formats/examples/eye_burial_anim.rs b/crates/benilla-formats/examples/eye_burial_anim.rs
index 5332cb37..619b4c9f 100644
--- a/crates/benilla-formats/examples/eye_burial_anim.rs
+++ b/crates/benilla-formats/examples/eye_burial_anim.rs
@@ -1,36 +1,16 @@
-//! **Is the eye emitter still proud of the face once the model ANIMATES?**
-//!
-//! `eye_quad_pass` answers the depth contest at *bind* pose, where benilla already matches the
-//! reference. Decision 0707 measured the failing case and found the split: benilla's freshest eye
-//! particle — born this frame at the current bone pose — sits **1.6–4.7 cm behind the face our
-//! renderer draws**, against **2.5–34 mm** at bind. "Faithful at rest" and "faithful in motion" are
-//! different claims, and this is the instrument for the second one.
-//!
-//! It builds the bone palette ourselves, from our own parse, at sampled times across a sequence:
-//! `palette[b] = parentPalette · T(pivot) · R(rot) · S(scale) · T(-pivot)`, the M2 skinning matrix.
-//! Then, per sample, it reports the two numbers that decide the contest:
-//!
-//! - `gap` — the distance from the animated eye-bone pivot (where our particles are born, verified
-//!   `birth == joint`) to the **nearest skinned vertex** of the depth-writing batches. At bind this
-//!   is 0.0162 for bone 60 (wow-re `part-flush-emitter-depth.md` §0). If our animation swings the
-//!   skin centimetres past the bone, this grows — and that growth *is* the bug.
-//! - `pass%` — the constant-depth quad's surviving area against the animated shell, front view.
-//!
-//! `cargo run -p benilla-formats --example eye_burial_anim -- 'Creature\Voidwalker\Voidwalker.m2' 0`
-//!
-//! A `gap` that stays near its bind value across the cycle says our pose is self-consistent and 0707's
-//! centimetres came from somewhere else in the renderer. A `gap` that blows out says our skinning or
-//! our animation moved the face off the bone, and the fix is there.
+//! Whether an eye emitter stays in front of the face while the model animates; `eye_quad_pass`
+//! answers it at bind pose. At samples across one sequence it builds the M2 skinning palette from
+//! our own parse and prints `gap`, the emitter's distance to the nearest skinned vertex of the
+//! depth-writing batches (bone 60 of `Voidwalker.m2`: 0.0162 at bind), and `pass%`, the share of
+//! the constant-depth quad the animated shell leaves visible. A gap that grows over the cycle
+//! means our skinning or animation moves the face off the bone.
+//! `cargo run -p benilla-formats --example eye_burial_anim -- <m2 path> [seq slot]`
 
 use benilla_formats::{ModelAnimation, RenderSubmesh, Skeleton};
 use glam::{Mat4, Quat, Vec3};
 
-/// The M2 skinning palette at time `t` (seconds into `anim`), in file-bone order.
-///
-/// The pivot dance is the whole point: a bone's animated rotation/scale act **about its own pivot**,
-/// so the matrix is `T(pivot) · R · S · T(-pivot)` composed under the parent. At rest (no keys) every
-/// factor is identity and the palette is identity — which is why an emitter record `position` that
-/// equals its bone pivot maps to itself at bind.
+/// The M2 skinning palette at `t` seconds into `anim`, in file-bone order: rotation and scale act
+/// about the bone's pivot, `T(pivot + tr) · R · S · T(-pivot)` under the parent.
 fn palette(skel: &Skeleton, anim: &ModelAnimation, t: f32) -> Vec<Mat4> {
     let sample_v = |keys: &[(f32, [f32; 3])], t: f32, dflt: Vec3| -> Vec3 {
         if keys.is_empty() {
@@ -88,7 +68,6 @@ fn palette(skel: &Skeleton, anim: &ModelAnimation, t: f32) -> Vec<Mat4> {
     out
 }
 
-/// Skin one vertex by its 4 bone/weight pairs (weights already normalised by the parser).
 fn skin(p: [f32; 3], j: [u16; 4], w: [f32; 4], pal: &[Mat4]) -> Vec3 {
     let v = Vec3::from(p);
     let mut acc = Vec3::ZERO;
@@ -199,10 +178,8 @@ fn main() -> anyhow::Result<()> {
         anim.bones.len()
     );
 
-    // Which bones does the depth-writing shell actually skin to, and does any of them sit under a
-    // BILLBOARD bone? A billboard joint is re-aimed at the camera every frame and its children
-    // inherit that rotation, so shell geometry under one moves with the *camera* — which is exactly
-    // the signature of a burial that appears from one camera elevation and not another.
+    // Shell bones under a billboard bone: a billboard re-aims at the camera each frame and its
+    // children inherit that, so their skin moves with the camera.
     {
         let mut shell_bones: Vec<usize> = Vec::new();
         for s in &subs {
@@ -252,8 +229,7 @@ fn main() -> anyhow::Result<()> {
         if b >= skel.bones.len() {
             continue;
         }
-        // Only the additive quad emitters mounted flush in the shell are the B16 subject; the
-        // others are printed anyway so the contrast is on the same page.
+        // Every emitter prints; the eye quads are the additive ones mounted flush in the shell.
         println!(
             "\nemitter bone {b}  pos ({:.4},{:.4},{:.4})  blend {:?}",
             e.position[0], e.position[1], e.position[2], e.blend
diff --git a/crates/benilla-formats/examples/eye_quad_pass.rs b/crates/benilla-formats/examples/eye_quad_pass.rs
index 93bff631..f2e39b4e 100644
--- a/crates/benilla-formats/examples/eye_quad_pass.rs
+++ b/crates/benilla-formats/examples/eye_quad_pass.rs
@@ -1,24 +1,13 @@
-//! **The flush-emitter depth contest, computed offline** — what fraction of a particle emitter's
-//! constant-depth billboard survives `LEQUAL` against its own model's z-writing batches, from a
-//! given camera direction. No client, no camera, no capture: pure geometry over *our* parse.
-//!
-//! This exists to hold benilla's asset side against wow-re's measured table
-//! (`system/models/scratch/part-flush-emitter-depth.md` §4 — Voidwalker bone 60, half 0.0833:
-//! front 43.4 %, 30° above 38.8 %, 60° left 43.3 %). Agreement means our mesh, our bone pivots and
-//! our quad model are faithful and any missing glow is the *renderer's*; disagreement localises the
-//! bug to the asset side, where it can be fixed without ever launching the game.
-//!
-//! `cargo run -p benilla-formats --example eye_quad_pass -- 'Creature\Voidwalker\Voidwalker.m2'`
-//!
-//! Model space, rest pose, WoW axes (X forward, Y left, Z up) — the emitter record `position` is
-//! the quad centre (it is bit-identical to its bone's pivot, and the palette is identity at rest).
-//! The occluder is every batch that is **not** `no_depth_write`, exactly the set the depth buffer
-//! holds when the particle pass runs.
+//! The share of a particle emitter's constant-depth quad that passes `LEQUAL` against its own
+//! model's depth-writing batches, per camera direction, from our parse alone. The reference's quad
+//! writer (`0x7b2a50`) gives 43.4% front, 38.8% 30° above and 43.3% 60° left for `Voidwalker.m2`
+//! bone 60 at half-size 0.0833; a mismatch puts the bug in our asset side, a match in the renderer.
+//! Model space, rest pose, WoW axes (X forward, Y left, Z up); the emitter `position`, equal to its
+//! bone's pivot, is the quad centre. `cargo run -p benilla-formats --example eye_quad_pass -- <m2>`
 
 use benilla_formats::RenderSubmesh;
 
-/// Möller–Trumbore. Returns the ray parameter `t` of the hit, if the ray meets the triangle ahead
-/// of its origin.
+/// Möller-Trumbore: the ray parameter `t` of a hit ahead of the origin.
 fn ray_tri(orig: [f32; 3], dir: [f32; 3], a: [f32; 3], b: [f32; 3], c: [f32; 3]) -> Option<f32> {
     let sub = |p: [f32; 3], q: [f32; 3]| [p[0] - q[0], p[1] - q[1], p[2] - q[2]];
     let cross = |p: [f32; 3], q: [f32; 3]| {
@@ -36,8 +25,7 @@ fn ray_tri(orig: [f32; 3], dir: [f32; 3], a: [f32; 3], b: [f32; 3], c: [f32; 3])
     if det.abs() < 1e-9 {
         return None; // ray parallel to the triangle plane
     }
-    // Two-sided on purpose: the shell's inward-facing triangles occlude too — the depth buffer
-    // holds whatever rasterized, and these batches are authored two-sided or seen from inside.
+    // Two-sided on purpose: the depth buffer holds inward-facing triangles too.
     let inv = 1.0 / det;
     let s = sub(orig, a);
     let u = inv * dot(s, h);
@@ -53,10 +41,8 @@ fn ray_tri(orig: [f32; 3], dir: [f32; 3], a: [f32; 3], b: [f32; 3], c: [f32; 3])
     (t > 1e-6).then_some(t)
 }
 
-/// The camera-facing orthonormal pair for a view direction (the two screen axes the quad's corners
-/// are offset along — the third axis carries the shared depth).
 fn screen_axes(view: [f32; 3]) -> ([f32; 3], [f32; 3]) {
-    // `view` points from the camera toward the model. Any up-ish reference not parallel to it.
+    // `view` points from the camera toward the model; any up reference not parallel to it.
     let up = if view[2].abs() > 0.9 {
         [1.0, 0.0, 0.0]
     } else {
@@ -78,9 +64,8 @@ fn screen_axes(view: [f32; 3]) -> ([f32; 3], [f32; 3]) {
     (right, real_up)
 }
 
-/// Fraction of the quad's area that passes `LEQUAL` — i.e. whose sample point is not occluded by
-/// any z-writing triangle between it and the camera. Constant depth: every sample sits on the plane
-/// through `center` perpendicular to `view`, so "occluded" is simply "a triangle lies in front".
+/// The share of the quad that passes `LEQUAL`: every sample sits at the quad's one depth, so it
+/// fails iff a depth-writing triangle lies between it and the camera.
 fn pass_fraction(
     tris: &[([f32; 3], [f32; 3], [f32; 3])],
     center: [f32; 3],
@@ -89,13 +74,12 @@ fn pass_fraction(
     n: usize,
 ) -> f32 {
     let (right, up) = screen_axes(view);
-    // Cast *toward* the camera: anything hit is in front of the sample point.
+    // Cast toward the camera: anything hit is in front of the sample point.
     let back = [-view[0], -view[1], -view[2]];
     let mut passed = 0usize;
     let mut total = 0usize;
     for iy in 0..n {
         for ix in 0..n {
-            // Sample cell centres so the grid is unbiased at the quad's edges.
             let fx = (ix as f32 + 0.5) / n as f32 * 2.0 - 1.0;
             let fy = (iy as f32 + 0.5) / n as f32 * 2.0 - 1.0;
             let p = [
@@ -115,12 +99,8 @@ fn pass_fraction(
     passed as f32 / total as f32
 }
 
-/// Every triangle of every batch that writes depth — the occluder set, in model space.
-///
-/// `all` ignores the per-material `no_depth_write` bit, i.e. models a renderer that writes depth for
-/// the whole model. That is the counterfactual worth pricing: it is what benilla's distance-fade
-/// blend twin does (it forces depth-write ON regardless of the flag), so the two columns bracket
-/// "did we leak the model's own transparent cards into the depth buffer?".
+/// The occluder set in model space: every triangle of every depth-writing batch, or with `all` of
+/// every batch, as benilla's fade blend twin writes depth regardless of `no_depth_write`.
 fn occluders(subs: &[RenderSubmesh], all: bool) -> Vec<([f32; 3], [f32; 3], [f32; 3])> {
     let mut tris = Vec::new();
     for s in subs {
@@ -163,8 +143,7 @@ fn main() -> anyhow::Result<()> {
         tris.len()
     );
 
-    // Camera directions, as (label, azimuth° about +Z from +X, elevation° above the horizontal).
-    // `view` points camera → model, so the camera sits at -view.
+    // (label, azimuth° about +Z from +X, elevation°); the camera sits at -view.
     let views: &[(&str, f32, f32)] = &[
         ("front (+X)", 0.0, 0.0),
         ("15 above", 0.0, 15.0),
@@ -178,8 +157,7 @@ fn main() -> anyhow::Result<()> {
     ];
 
     for e in benilla_formats::parse_m2_particle_emitters(&bytes)?.iter() {
-        // Only the plane/quad emitters we can model this way, and only those actually mounted in
-        // the mesh — the point of the exercise.
+        // Meaningful only for a quad emitter mounted in the mesh; every emitter prints.
         println!(
             "\nemitter bone {} pos ({:.4}, {:.4}, {:.4})  blend {:?}",
             e.bone, e.position[0], e.position[1], e.position[2], e.blend
@@ -189,7 +167,6 @@ fn main() -> anyhow::Result<()> {
             print!("  {set:9} half {half:.4}:");
             for &(label, az, el) in views {
                 let (a, l) = (az.to_radians(), el.to_radians());
-                // Camera at azimuth `az`, elevation `el`, looking at the model: view = -(camera dir)
                 let view = [-(a.cos() * l.cos()), -(a.sin() * l.cos()), -(l.sin())];
                 let f = pass_fraction(occ, e.position, half, view, 64);
                 print!("  {label} {:.1}%", f * 100.0);
diff --git a/crates/benilla-formats/examples/fade_bucket.rs b/crates/benilla-formats/examples/fade_bucket.rs
index a710551b..3b84cace 100644
--- a/crates/benilla-formats/examples/fade_bucket.rs
+++ b/crates/benilla-formats/examples/fade_bucket.rs
@@ -1,12 +1,7 @@
-//! What distance-fade band does a doodad actually land in? Prints each matching M2's authored
-//! bounding-sphere radius (the reference's `rec+0x68` source) and the band the radius selects:
+//! Each matching M2's bounding-sphere radius (the reference's `rec+0x68` source) and the
+//! distance-fade band it selects, which depends on size alone. Radii are model-local; a
+//! placement's `scale` multiplies them. Output is Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example fade_bucket -- fence`
-//!
-//! The band is chosen by SIZE, never by what the thing is — so "fences fade at 40→50" is a claim
-//! about a radius, not about a fence. This prints the radius so the claim can be checked instead
-//! of remembered. Radii are model-local (pre-scale); a placement's `scale` multiplies them.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 fn main() -> anyhow::Result<()> {
     let pat = std::env::args()
@@ -38,7 +33,7 @@ fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
-/// The `FUN_00683f80` size buckets, as `model_fade.rs` encodes them.
+/// The size buckets of `0x683f80`, in sync with `model_fade.rs`.
 fn band(r: f32) -> &'static str {
     match r {
         r if r > 7.0 => "never fades",
diff --git a/crates/benilla-formats/examples/gseqdump.rs b/crates/benilla-formats/examples/gseqdump.rs
index 99c89a25..ff6f3933 100644
--- a/crates/benilla-formats/examples/gseqdump.rs
+++ b/crates/benilla-formats/examples/gseqdump.rs
@@ -1,9 +1,6 @@
-//! `gseqdump <internal\path.m2>` — every global-sequence bone channel with its RAW KEYS.
-//!
-//! `benilla-extract m2anim` names which bones carry global-sequence channels and their periods,
-//! but never the key VALUES — and for a twinkle (a scale loop on a star card) the values ARE the
-//! effect: a 0→1 flicker and a 0→20 flare are the same one-line summary. Output is Blizzard
-//! data — pipe it to the scratchpad, never into the repo.
+//! Every global-sequence bone channel with its raw keys: for a twinkle the scale values are the
+//! effect, and a 0-1 flicker and a 0-20 flare can share a period. `gseqdump <internal\path.m2>`
+//! Output is Blizzard data: never commit it.
 
 fn main() -> anyhow::Result<()> {
     let virt = std::env::args()
diff --git a/crates/benilla-formats/examples/impass_here.rs b/crates/benilla-formats/examples/impass_here.rs
index b9809b1f..043c5123 100644
--- a/crates/benilla-formats/examples/impass_here.rs
+++ b/crates/benilla-formats/examples/impass_here.rs
@@ -1,35 +1,21 @@
-//! Where the ADT's impassable chunks are around a pin:
+//! A top-down map of the MCNK impassable flag (header flag bit 1) around a pin: north up, one
+//! glyph per 33.333 yd chunk, across tile seams, since a band crosses them. `what_is_here` covers
+//! models. Output is Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example impass_here -- <map> <x> <y> [radius_chunks]`
-//! e.g. `impass_here Azeroth -6601.98 -531.87 10`.
-//!
-//! An "invisible wall" report (B129) names a *place* — a `.go xyz` pin — and the first question is
-//! whether the wall is authored terrain at all: an MCNK with header flag bit 1 (`MCNK_IMPASSABLE`)
-//! set, or a WMO/M2 hull the reporter walked into. This prints
-//! the flag as a top-down chunk map — north up, west left, the in-game map's orientation, one
-//! glyph per 33.333 yd chunk — so the answer is a picture of the band rather than a guess, and the
-//! pin's own chunk is marked. `what_is_here` answers the other half (is there a model here).
-//!
-//! The map crosses tile seams on purpose: the flag is per chunk and a band runs across ADT
-//! boundaries, so a single-tile view is exactly how you miss the wall you are standing against —
-//! B129's pin sits 1.5 yd from its wall, with the flagged chunk in the *next* tile east.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 use std::collections::HashMap;
 
 use benilla_formats::{impassable_at, world_to_tile, TileMesh, CHUNK_SIZE, TILE_SIZE};
 
-/// The map's NW origin: world x/y both run *down* from `+32 tiles` as the grid runs south/east.
+/// The map's NW corner: world x and y fall from 32 tiles as the grid runs south and east.
 const MAP_CENTER: f32 = 32.0 * TILE_SIZE;
 
-/// Global chunk index of a world coordinate on either axis — row from x (grows south), column from
-/// y (grows east). The same falling-from-`MAP_CENTER` addressing the client's per-chunk lookups use
-/// (wow-re's MCSH texel law, `0x69b350`).
+/// Global chunk index of a world coordinate on either axis, row from x and column from y, falling
+/// from `MAP_CENTER` as the client's per-chunk lookups do (`0x69b350`).
 fn chunk_index(coord: f32) -> i32 {
     ((MAP_CENTER - coord) / CHUNK_SIZE).floor() as i32
 }
 
-/// The world coordinate of a global chunk index's centre (inverse of [`chunk_index`], +½ chunk).
 fn chunk_centre(index: i32) -> f32 {
     MAP_CENTER - (index as f32 + 0.5) * CHUNK_SIZE
 }
@@ -67,7 +53,7 @@ fn main() -> anyhow::Result<()> {
     println!("  '#' impassable · '.' passable · '@' the pin's chunk · ' ' no tile");
     print!("      ");
     for dc in -radius..=radius {
-        // A tile seam every 16 chunks: mark it so a band's tile ownership is readable at a glance.
+        // A tile seam every 16 chunks.
         print!(
             "{}",
             if (pin_col + dc).rem_euclid(16) == 0 {
@@ -94,8 +80,7 @@ fn main() -> anyhow::Result<()> {
         println!();
     }
 
-    // The pin's own verdict, and how far the wall is in each cardinal direction — the number a
-    // retest needs ("walk east 1.5 yd and you should stop").
+    // The pin's own chunk, and the distance to the wall in each cardinal direction.
     let pin_flag = flag_at(&mut chain, x, y);
     println!(
         "\npin chunk: {}",
@@ -111,8 +96,7 @@ fn main() -> anyhow::Result<()> {
         ("west  (+y)", 0.0, 1.0),
         ("east  (-y)", 0.0, -1.0),
     ] {
-        // Step chunk by chunk from the pin until the flag flips, then report the distance to that
-        // chunk's *near boundary* — where a mover would actually be stopped.
+        // Step chunk by chunk until the flag flips; a mover stops at that chunk's near boundary.
         let hit = (1..=radius).find(|n| {
             let (sx, sy) = (
                 x + dx * *n as f32 * CHUNK_SIZE,
diff --git a/crates/benilla-formats/examples/liquid_depth_census.rs b/crates/benilla-formats/examples/liquid_depth_census.rs
index e6864acb..ee05e9a1 100644
--- a/crates/benilla-formats/examples/liquid_depth_census.rs
+++ b/crates/benilla-formats/examples/liquid_depth_census.rs
@@ -1,26 +1,8 @@
-//! What the shipped MCLQ **depth byte** actually is, per liquid kind — the instrument behind the
-//! ocean depth-ramp settle:
+//! The shipped MCLQ depth byte per liquid kind over wet-cell vertices: its histogram, its slope
+//! against the real `surface - terrain` depth, mid-ramp shore pins and what each divisor does to
+//! the picture. The reference maps the byte to its depth swatch per kind, river `min(d/42, 1)` and
+//! ocean `min(d/255, 1)`. Output is Blizzard data: never commit it.
 //! `cargo run --release -p benilla-formats --example liquid_depth_census -- [map ...]`
-//! (default: `Azeroth Kalimdor`, i.e. every ADT ocean and river in the vanilla world.)
-//!
-//! The reference indexes its water depth-swatch by this one byte through a per-kind LUT — river
-//! `min(d/42, 1)`, ocean `min(d/255, 1)` — so the *look* of a sea is that LUT applied to whatever
-//! the artists authored into the byte. A divisor argued from the binary alone can still be wrong
-//! about the picture if the authored range never reaches it, so this measures the range, and the
-//! byte→yard slope that turns it into a distance a swimmer can feel:
-//!
-//! - the **depth-byte histogram** per kind, over vertices that touch a wet cell (dry-cell verts
-//!   carry the FLT_MAX height sentinel and no meaningful byte);
-//! - the **byte→yard slope**, least-squares through the origin against the real geometric depth
-//!   `surface − terrain` at each vertex, plus the correlation — which is also the check that byte 0
-//!   of the water/ocean union IS a depth at all;
-//! - a handful of **shore-band pins** — world coords where the depth byte is mid-ramp, i.e. the only
-//!   places the divisor is visible at all. Everything else is either the pale edge or the pinned-deep
-//!   open sea, and an A/B aimed anywhere else photographs two identical pictures;
-//! - **what each candidate divisor does to the picture**: the share of wet water that lands on the
-//!   deep swatch row (V ≥ 0.95), on the shallow row (V ≤ 0.05), and the mean V.
-//!
-//! Output is Blizzard-derived data — read it, pipe it to the scratchpad, never into the repo.
 
 use std::collections::BTreeMap;
 
@@ -28,34 +10,27 @@ use benilla_formats::{terrain_height_at, LiquidKind, CHUNK_SIZE};
 
 /// MCLQ vertex-grid pitch: the 9×9 grid spans one 8-cell chunk.
 const UNIT: f32 = CHUNK_SIZE / 8.0;
-/// MCLQ grid side (9 verts) and cell side (8).
 const GRID: usize = 9;
 const CELLS: usize = 8;
-/// Cell-flag low nibble meaning "dry".
 const DRY_NIBBLE: u8 = 0x0f;
 /// Verts under no liquid carry FLT_MAX; `is_finite()` is true for it, so gate on magnitude.
 const HEIGHT_SENTINEL: f32 = 1.0e9;
 
 /// The per-kind accumulator: the byte histogram plus the paired (byte, yard) samples.
 struct Kind {
-    /// Count per raw depth byte, 0..=255.
     hist: Box<[u64; 256]>,
-    /// Vertices whose terrain height resolved, for the byte→yard fit.
+    /// Vertices whose terrain height resolved, for the byte-to-yard fit.
     paired: u64,
-    /// Σ byte·yd, Σ byte², Σ yd², Σ byte, Σ yd — enough for a through-origin slope and an r.
+    /// Σ byte·yd, Σ byte², Σ yd², Σ byte, Σ yd, for the through-origin slope and r.
     sum_by: f64,
     sum_bb: f64,
     sum_yy: f64,
     sum_b: f64,
     sum_y: f64,
-    /// Blocks seen.
     blocks: u64,
-    /// A spread of mid-ramp sample points: `(zone, map, x, y, byte, yards)`, at most one per
-    /// 2000-yd neighbourhood, so the list names distinct coastlines instead of 200 vertices of one
-    /// bay. Named by `AreaTable`, because a pin you can walk to is worth more than a coordinate.
+    /// Mid-ramp points `(zone, map, x, y, byte, yards)`, at most one per 2000-yd neighbourhood.
     pins: Vec<(String, String, f32, f32, u8, f32)>,
-    /// Σ yards and count per depth byte — the empirical byte→depth curve, which the single
-    /// through-origin slope cannot show once a kind's byte saturates (the ocean's does, hard).
+    /// Σ yards and count per byte: the depth curve a single slope hides where the byte saturates.
     yd_sum: Box<[f64; 256]>,
     yd_n: Box<[u64; 256]>,
 }
@@ -98,7 +73,6 @@ impl Kind {
         self.hist.iter().sum()
     }
 
-    /// Byte at the given share of the distribution.
     fn percentile(&self, p: f64) -> u8 {
         let target = (self.total() as f64 * p) as u64;
         let mut seen = 0;
@@ -129,9 +103,8 @@ impl Kind {
         Some((slope, r))
     }
 
-    /// Least-squares `byte = k · yards` through the origin over a byte window only. The ocean
-    /// pins 83 % of its vertices at 255, which drags a whole-range fit toward the pile and hides
-    /// the ramp that actually paints the shore; this reads the ramp where it varies.
+    /// The through-origin slope over a byte window only: the ocean pins 83% of its vertices at
+    /// 255, and a whole-range fit hides the ramp that paints the shore.
     fn slope_in(&self, lo: u8, hi: u8) -> Option<(f64, u64)> {
         let (mut sby, mut syy, mut n) = (0.0, 0.0, 0u64);
         for b in lo..=hi {
@@ -180,7 +153,6 @@ fn main() -> anyhow::Result<()> {
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = benilla_formats::open_chain(&data)?;
 
-    // Names for the shore-band pins. Optional: a census still reads without a DBC.
     let areas = benilla_formats::load_area_table_catalog(&mut chain).ok();
 
     let mut kinds: BTreeMap<String, Kind> = BTreeMap::new();
@@ -194,8 +166,7 @@ fn main() -> anyhow::Result<()> {
             let Ok(bytes) = chain.read_file(&path) else {
                 continue;
             };
-            // The mesh is only the TERRAIN reference here — the depth bytes come off the raw parse,
-            // so the census can never be a restatement of the divisor it is measuring.
+            // The mesh gives only the terrain; the depth bytes come off the raw parse.
             let Ok(mesh) = benilla_formats::adt_to_tile_mesh(&bytes) else {
                 continue;
             };
@@ -209,8 +180,7 @@ fn main() -> anyhow::Result<()> {
                     if block.vertices.len() < GRID * GRID {
                         continue;
                     }
-                    // Kind from the majority WET cell nibble — the verified type source, and the
-                    // same rule `build_liquid_mesh` uses, so the census bins as the renderer draws.
+                    // Kind from the majority wet-cell nibble, the same rule as `build_liquid_mesh`.
                     let mut counts = [0u32; 16];
                     let mut wet = [false; CELLS * CELLS];
                     for (c, w) in wet.iter_mut().enumerate() {
@@ -256,13 +226,11 @@ fn main() -> anyhow::Result<()> {
                         }
                         let x = wx - row as f32 * UNIT;
                         let y = wy - col as f32 * UNIT;
-                        // Nudge off the exact lattice line so the terrain lookup lands inside a
-                        // triangle rather than on a chunk seam.
+                        // Nudge off the lattice so the terrain lookup lands inside a triangle.
                         let ground = terrain_height_at(&mesh.chunks, [x - 0.01, y - 0.01, 0.0]);
                         let yards = ground.map(|g| h - g).filter(|d| *d > 0.0 && *d < 500.0);
                         let byte = block.vertices[n].depth_byte();
-                        // One mid-ramp pin per tile: where the ramp is neither pinned deep nor at
-                        // the pale edge, which is the only band an A/B can see.
+                        // Mid-ramp pins, the only band where the divisor shows on screen.
                         if (40..=200).contains(&byte)
                             && acc.pins.len() < 64
                             && !acc.pins.iter().any(|p| {
@@ -342,7 +310,6 @@ fn main() -> anyhow::Result<()> {
                 println!("    {map} {x:9.1} {y:9.1}  byte {b:3}  depth {yd:5.1} yd  {zone}");
             }
         }
-        // The coarse shape, so a bimodal or pinned distribution shows without a plot.
         print!("  histogram (16 buckets of 16):");
         for b in 0..16 {
             let n: u64 = k.hist[b * 16..(b + 1) * 16].iter().sum();
diff --git a/crates/benilla-formats/examples/list_chain.rs b/crates/benilla-formats/examples/list_chain.rs
index 361f2115..38547383 100644
--- a/crates/benilla-formats/examples/list_chain.rs
+++ b/crates/benilla-formats/examples/list_chain.rs
@@ -1,16 +1,12 @@
-//! List every file in the 5875 patch chain whose path contains a substring (case-insensitive):
-//! `cargo run -p benilla-formats --example list_chain -- maraudon`. The "what is this thing
-//! actually called" tool — a report names a *place* ("the red crystal in Maraudon"), and finding
-//! the asset behind it is the first step of every scene-render diagnosis.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! Every file in the patch chain whose path contains a substring, case-insensitive, optionally of
+//! one extension. `cargo run -p benilla-formats --example list_chain -- maraudon [m2]`
+//! Output is Blizzard data: never commit it.
 
 fn main() -> anyhow::Result<()> {
     let pat = std::env::args()
         .nth(1)
         .ok_or_else(|| anyhow::anyhow!("usage: list_chain <substring> [ext]"))?
         .to_lowercase();
-    // An optional second argument filters by extension — `list_chain maraudon m2`.
     let ext = std::env::args()
         .nth(2)
         .map(|e| format!(".{}", e.to_lowercase()));
diff --git a/crates/benilla-formats/examples/m2_shared_section.rs b/crates/benilla-formats/examples/m2_shared_section.rs
index d372f24a..1bcc80b1 100644
--- a/crates/benilla-formats/examples/m2_shared_section.rs
+++ b/crates/benilla-formats/examples/m2_shared_section.rs
@@ -1,29 +1,15 @@
-//! **Which M2 batches share their triangles with another batch** — the coplanar-sibling census:
-//! `cargo run -p benilla-formats --example m2_shared_section -- [path-substring]`.
-//!
-//! An M2 skin *section* is a run of triangles; a *batch* is one draw of one section. When two
-//! batches name the SAME section they rasterize the SAME triangles — a base layer and a shine /
-//! reflect layer authored on top of it (`ARMORREFLECT3`, `BALISTASHINE02`). The reference draws
-//! both from one vertex array under depth-write + LEQUAL, so the second always wins the tie
-//! exactly (wow-re `m2-depth-blend-state`).
-//!
-//! We only match that if both batches take the SAME vertex-transform path. They do not when a
-//! consolidator (`static_gx`, `terrain_stream::merge`) admits one and refuses the other: the
-//! retained lane bakes world positions on the CPU and the entity lane rotates on the GPU, and the
-//! two agree only to the last few ULPs — enough, on coplanar triangles, to turn the depth test
-//! into a per-pixel coin flip that re-rolls whenever the camera moves. That is the ballista's
-//! flickering bolt heads and shields.
-//!
-//! So this prints, per model, every multi-batch section and whether its batches DISAGREE on the
-//! facts the consolidators exclude on (env-mapped UVs, render flags `0x10` no-depth-write / `0x08`
-//! no-depth-test, additive blend 3/4). A `SPLIT` line is a model that can z-fight against itself.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! M2 batches that share a skin section, and so the same triangles, with another batch. The
+//! reference draws both from one vertex array under depth-write and LEQUAL, so the later one wins
+//! the tie exactly (`0x70b3f6`, `0x70c190`). We match that only when both take the same vertex
+//! path: a consolidator (`static_gx`, `terrain_stream::merge`) bakes positions on the CPU, which
+//! differ from the GPU's in the last ULPs, so a section it splits z-fights (a `SPLIT` line).
+//! Output is Blizzard data: never commit it.
+//! `cargo run -p benilla-formats --example m2_shared_section -- [path-substring]`
 
 use std::io::Cursor;
 
-/// The facts every consolidator excludes on — a batch answering `true` can never ride the
-/// retained/merged lanes, so it stays on the entity path whatever its siblings do.
+/// What every consolidator excludes on: a `true` batch stays on the entity path whatever its
+/// siblings do.
 fn refusable(model: &benilla_m2::M2Model, batch: &benilla_m2::SkinBatch) -> bool {
     let mat = model.materials.get(batch.material_index as usize);
     let flags = mat.map_or(0, |m| m.flags.bits());
diff --git a/crates/benilla-formats/examples/mm_seam_probe.rs b/crates/benilla-formats/examples/mm_seam_probe.rs
index 103ef3e9..1ae79700 100644
--- a/crates/benilla-formats/examples/mm_seam_probe.rs
+++ b/crates/benilla-formats/examples/mm_seam_probe.rs
@@ -1,11 +1,7 @@
-//! TEMP (B141): rasterise the WMO-interior minimap **offline**, from the shipped tiles and the
-//! client's own placement + alpha test, so "where do the black lines come from" is a measurement on
-//! the data rather than a reading of a screenshot.
-//!
-//! Writes three PNGs: `colour` (what the composite would show), `cover` (white where SOME tile
-//! passes the 224/255 test), and `any` (white where some tile has alpha > 0 at all). A line that is
-//! black in `cover` but white in `any` is the alpha test cutting art that exists; black in both is
-//! a genuine hole in the bake — or a placement that never covers that spot.
+//! The WMO-interior minimap rasterised offline from the shipped tiles, with the client's placement
+//! and 224/255 alpha test, written as `mm_{colour,cover,any,owner,seam}.png` under `MM_OUT`. Black
+//! in `cover` (some tile passes the test) but white in `any` (some tile has alpha) is the test
+//! cutting art; black in both is a hole in the bake or a spot no placement covers.
 use std::collections::BTreeMap;
 use std::io::Cursor;
 
@@ -54,7 +50,6 @@ fn model_to_world(rot_deg: [f32; 3], p: [f32; 3]) -> [f32; 3] {
     let p = rot_y(p, ry - std::f32::consts::PI);
     rot_x(p, std::f32::consts::FRAC_PI_2)
 }
-/// Inverse of [`model_to_world`] (the rotation is orthonormal, so: same angles, reversed order).
 fn world_to_model(rot_deg: [f32; 3], p: [f32; 3]) -> [f32; 3] {
     let (rx, ry, rz) = (
         rot_deg[0].to_radians(),
@@ -81,7 +76,6 @@ fn world_to_model(rot_deg: [f32; 3], p: [f32; 3]) -> [f32; 3] {
 
 struct Tile {
     gi: usize,
-    /// The drawn rect (grid cell + outer-edge bleed).
     x0: f32,
     y0: f32,
     tw: f32,
@@ -106,7 +100,7 @@ fn main() -> anyhow::Result<()> {
     let mut chain = benilla_formats::open_chain(&data)?;
     let trs = benilla_formats::load_minimap_translate(&mut chain)?;
 
-    // Find the placement whose model bbox contains the pin, over every WMO placed in this ADT.
+    // The WMO placement in this ADT whose origin is nearest the pin.
     let (tc, tr) = benilla_formats::world_to_tile(pin[0], pin[1]);
     let adt_name = format!("World\\Maps\\Azeroth\\Azeroth_{tc}_{tr}.adt");
     let bytes = chain.read_file(&adt_name)?;
@@ -127,8 +121,7 @@ fn main() -> anyhow::Result<()> {
         }
     }
     let (model, origin, rot, _) = best.expect("no WMO placement in this ADT");
-    // MM_MODEL="x,y[,z]" pins in the WMO's MODEL space instead — how a captured reference frame
-    // states the player's position, so a capture can be reproduced exactly.
+    // `MM_MODEL="x,y[,z]"` pins in the WMO's model space instead, as a reference capture states it.
     let pm = match std::env::var("MM_MODEL") {
         Ok(v) => {
             let n: Vec<f32> = v.split(',').map(|t| t.trim().parse().unwrap()).collect();
@@ -163,8 +156,7 @@ fn main() -> anyhow::Result<()> {
     }
     eprintln!("{} groups, model bbox {glo:?} .. {ghi:?}", infos.len());
 
-    // MM_AUDIT: our computed per-group tile grid against the one actually authored in the trs.
-    // A short grid leaves world the composite can never cover, whatever the group selection does.
+    // `MM_AUDIT`: our per-group tile grid against the one authored in the translate table.
     if std::env::var("MM_AUDIT").is_ok() {
         let (mut bad, mut tiles_ours, mut tiles_theirs) = (0usize, 0usize, 0usize);
         for (gi, info) in infos.iter().enumerate() {
@@ -203,10 +195,7 @@ fn main() -> anyhow::Result<()> {
         return Ok(());
     }
 
-    // MM_BLP: what the tile art actually declares and holds — the alpha histogram of every tile
-    // near the pin, so "transparent" is a fact about the file rather than about our decoder.
-    // MM_FIT: the authored tile's PIXEL size against the group's world extent — i.e. what the bake's
-    // real yards-per-texel is, per group, instead of the 0.5 we assume.
+    // `MM_FIT`: each group's real yards per texel, from its authored tile size and its extent.
     if std::env::var("MM_FIT").is_ok() {
         println!("  gi  authored px   grid   extent yd        yd/texel (x, y)");
         let mut ratios: Vec<f32> = Vec::new();
@@ -237,7 +226,7 @@ fn main() -> anyhow::Result<()> {
                 info.bbox_max[0] - info.bbox_min[0],
                 info.bbox_max[1] - info.bbox_min[1],
             );
-            // Tile art is transposed vs the model axes: image WIDTH runs along model Y, HEIGHT along X.
+            // This read pairs model X with image height and rows: the layout below, transposed.
             let (nx, ny) = ((mc + 1) as f32, (mr + 1) as f32);
             let ypt_x = ex / (dim.1 as f32 * ny);
             let ypt_y = ey / (dim.0 as f32 * nx);
@@ -265,9 +254,7 @@ fn main() -> anyhow::Result<()> {
         return Ok(());
     }
 
-    // MM_ANCHOR: where inside its power-of-two texture does a single-tile group's OPAQUE art sit,
-    // and how big is it — against the group's own extent at 0.5 yd/texel. This is what says whether
-    // the bake pads (art at one corner, transparent remainder) or stretches, and which corner.
+    // `MM_ANCHOR`: where a single-tile group's opaque art sits in its power-of-two texture.
     if std::env::var("MM_ANCHOR").is_ok() {
         println!("  gi   tex     opaque box (u0,u1)x(v0,v1)   extent/0.5 texels   fill");
         for (gi, info) in infos.iter().enumerate().take(40) {
@@ -311,8 +298,7 @@ fn main() -> anyhow::Result<()> {
         return Ok(());
     }
 
-    // MM_MULTI: the same anchor read on MULTI-tile groups, which is what says which name index runs
-    // along which model axis and where the power-of-two padding lands across a row of tiles.
+    // `MM_MULTI`: the same on multi-tile groups, for which name index runs along which axis.
     if std::env::var("MM_MULTI").is_ok() {
         let mut shown = 0;
         for (gi, info) in infos.iter().enumerate() {
@@ -369,6 +355,7 @@ fn main() -> anyhow::Result<()> {
         return Ok(());
     }
 
+    // `MM_BLP`: each tile's declared header and alpha histogram, as the file holds them.
     if std::env::var("MM_BLP").is_ok() {
         for gi in 0..infos.len() {
             for c in 0..4u32 {
@@ -414,14 +401,10 @@ fn main() -> anyhow::Result<()> {
         let (ny, twy) = group_axis_grid(info.bbox_max[1] - info.bbox_min[1]);
         for col in 0..nx {
             for row in 0..ny {
-                // MEASURED tile layout (MM_ANCHOR / MM_MULTI, read off the shipped art): image u
-                // runs along model +X with u_global = 0 at the group's bbox X-MIN, column index
-                // advancing with +X; image v runs along model Y INVERTED, the grid anchored at its
-                // BOTTOM so the last row's last texel sits at the group's Y anchor.
-                // The verified rect: cells stride `tw` and share their interior edges, and a cell
-                // on the grid's boundary is grown 1.0 yd on that side alone (wow-re
-                // `wmo-interior-no-adt-underlay.md` §8). `MM_NOBLEED` drops the bleed, which is
-                // what B141 was: without it two groups' art abuts instead of overlapping by 2 yd.
+                // Measured off the shipped art: image u runs along model +X from the bbox X-min,
+                // columns advancing with +X; v runs along model Y inverted. Cells stride `tw` and
+                // share interior edges; a boundary cell grows 1.0 yd on its outer side
+                // (`0x6a5270`), and `MM_NOBLEED` drops that, so neighbouring groups only abut.
                 let bleed = if std::env::var("MM_NOBLEED").is_ok() {
                     0.0
                 } else {
@@ -474,7 +457,8 @@ fn main() -> anyhow::Result<()> {
     for k in cache.iter().filter(|(_, v)| v.is_none()).take(4) {
         eprintln!("  MISS {}", k.0);
     }
-    // Same order the app draws in: by group bbox Z-mid relative to the player, ascending.
+    // Farthest group Z-mid first. The reference paints ascending by signed `Zmid - playerZ`, the
+    // player's own group last (`0x4ebeb0`).
     tiles.sort_by(|a, b| {
         (a.midz - pm[2])
             .abs()
@@ -488,8 +472,7 @@ fn main() -> anyhow::Result<()> {
     let mut anyv = vec![0u8; (px * px) as usize];
     let mut owner = vec![0u8; (px * px * 3) as usize];
     let bilinear = std::env::var("MM_BILINEAR").is_ok();
-    // OPTIONAL UNDERLAY: the outdoor ADT minimap tiles (`Azeroth\\map<x>_<y>.blp`), sampled through
-    // the placement so they land under the WMO tiles in the same frame. `MM_TERRAIN=1`.
+    // `MM_TERRAIN`: an outdoor ADT tile underlay; the reference's interior composite has none.
     if std::env::var("MM_TERRAIN").is_ok() {
         let mut adt_cache: BTreeMap<(u32, u32), Option<Vec<u8>>> = BTreeMap::new();
         for iy in 0..px {
@@ -533,12 +516,8 @@ fn main() -> anyhow::Result<()> {
                 if mx < t.x0 || mx >= t.x0 + t.tw || my < t.y0 || my >= t.y0 + t.th {
                     continue;
                 }
-                // MM_BILINEAR reproduces the reference's LINEAR sampler (CLAMP_TO_EDGE), so the
-                // alpha the 224/255 test sees is the interpolated one — which is what decides how
-                // far a tile's opaque art actually reaches past its last opaque texel CENTRE
-                // (0.122 of a texel at ref 224, against nearest's half-texel to the texel EDGE).
-                // The client samples `[0.5/W, 1−0.5/W]` across the drawn rect, so the W texel
-                // CENTRES span it exactly: step = rect / (W−1), texel 0's centre on the rect edge.
+                // `MM_BILINEAR` is the reference's LINEAR, CLAMP_TO_EDGE sampler. The client
+                // samples `[0.5/W, 1-0.5/W]` across the drawn rect, so its W texel centres span it.
                 let fu = (mx - t.x0) / (t.tw / (t.w as f32 - 1.0));
                 let fv = (t.y0 + t.th - my) / (t.th / (t.h as f32 - 1.0));
                 let (u, v) = (
@@ -572,9 +551,7 @@ fn main() -> anyhow::Result<()> {
             }
         }
     }
-    // A HAIRLINE is an uncovered run at most 4 px wide with coverage on BOTH sides — a seam
-    // between two tiles, as opposed to the large unauthored gaps (streets, the exterior group)
-    // that are simply not part of any interior group's bake.
+    // A hairline is an uncovered run of at most 4 px with coverage on both sides: a tile seam.
     let mut seam = colour.clone();
     let mut hair = 0usize;
     let mut runs: BTreeMap<usize, usize> = BTreeMap::new();
@@ -620,8 +597,8 @@ fn main() -> anyhow::Result<()> {
         px,
         image::ColorType::Rgb8,
     )?;
-    // The VISIBLE DISC — what the blit actually shows: radius `MM_DISC` yards about the player.
-    // The reference capture reports 95.84% painted / 4.16% clear over exactly this.
+    // `MM_DISC`: the painted share of the visible disc of that radius in yards; the reference
+    // leaves 4.16% of it clear in its Stormwind capture.
     if let Ok(v) = std::env::var("MM_DISC") {
         let rd: f32 = v.parse().unwrap();
         let c0 = px as f32 * 0.5;
diff --git a/crates/benilla-formats/examples/mm_water_pin.rs b/crates/benilla-formats/examples/mm_water_pin.rs
index 8c337ee1..77f63720 100644
--- a/crates/benilla-formats/examples/mm_water_pin.rs
+++ b/crates/benilla-formats/examples/mm_water_pin.rs
@@ -1,6 +1,6 @@
-//! TEMP (B141/N05): what the WMO's liquid actually looks like around a pin — which groups hold
-//! water there, their MOGP flags/liquid type, their MLIQ base heights, and whether two surfaces
-//! abut, overlap or step. Run: `cargo run -p benilla-formats --example mm_water_pin -- x y z [r]`.
+//! The WMO liquid around a pin: the groups holding water there, their MOGP flags, liquid type and
+//! MLIQ heights, and how many surfaces claim each point.
+//! `cargo run -p benilla-formats --example mm_water_pin -- x y z [r]`
 use std::io::Cursor;
 
 const MAP_CENTER: f32 = 17066.666;
@@ -146,9 +146,7 @@ fn main() -> anyhow::Result<()> {
         );
     }
 
-    // How many DISTINCT groups claim each point as wet? Two coplanar surfaces over the same ground
-    // are drawn twice — a transparent water quad composited twice is visibly darker, and at equal
-    // depth they also z-fight. Sampled on a 0.25 yd lattice over the pin's window.
+    // Groups claiming each point as wet; a point claimed twice draws darker and z-fights.
     let step = 0.25f32;
     let n = (2.0 * r / step) as i32;
     let mut hist = std::collections::BTreeMap::<usize, usize>::new();
@@ -201,7 +199,6 @@ fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
-/// The cell index `(mx, my)` falls in, if it is inside the grid at all.
 fn cell_at(m: &benilla_formats::LiquidMesh, mx: f32, my: f32) -> Option<usize> {
     let (cols, rows) = (m.grid[0] as usize, m.grid[1] as usize);
     if cols < 2 || rows < 2 {
diff --git a/crates/benilla-formats/examples/order_probe.rs b/crates/benilla-formats/examples/order_probe.rs
index 0f890f5e..1b5d7d47 100644
--- a/crates/benilla-formats/examples/order_probe.rs
+++ b/crates/benilla-formats/examples/order_probe.rs
@@ -1,10 +1,7 @@
-//! Throwaway: the sort/admission inputs the trainer & craft windows key on. Two modes:
-//!
-//! * `line <skill-line-name-substring>...` — a line's abilities with their raw
-//!   `SkillLineAbility.dbc` columns (`req_skill_value` col 7, `reqtrainpoints` col 14), their
-//!   `Spell.dbc` name/rank, `castUI`, `attributes` and `spellLevel`.
-//! * `castui <n>` — every spell whose `castUI == n`, with the skill line (if any) its first
-//!   `SkillLineAbility` row names: the client's craft-admission key vs benilla's SLA join.
+//! The inputs the trainer and craft windows sort and admit on. `line <name-substring>...` prints a
+//! line's abilities with `SkillLineAbility.dbc` columns 7 (`req_skill_value`) and 14
+//! (`reqtrainpoints`) and their spell's `castUI`, attributes and level; `castui <n>` prints every
+//! spell with that `castUI`, the client's craft admission key, beside its skill line.
 fn main() -> anyhow::Result<()> {
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = benilla_formats::open_chain(&data)?;
diff --git a/crates/benilla-formats/examples/png_disc.rs b/crates/benilla-formats/examples/png_disc.rs
index 1c673603..f04a7f39 100644
--- a/crates/benilla-formats/examples/png_disc.rs
+++ b/crates/benilla-formats/examples/png_disc.rs
@@ -1,6 +1,6 @@
-//! TEMP (B141): what fraction of a captured minimap disc is the composite's black clear.
-//! `cargo run -p benilla-formats --example png_disc -- <png> [cx cy r]` — defaults to the whole
-//! image's inscribed circle, which is what the `WOW_MM_PROBE` crop is.
+//! The share of a captured minimap disc that is the composite's black clear; the default circle is
+//! the image's inscribed one, which is the `WOW_MM_PROBE` crop.
+//! `cargo run -p benilla-formats --example png_disc -- <png> [cx cy r]`
 fn main() -> anyhow::Result<()> {
     let a: Vec<String> = std::env::args().skip(1).collect();
     let img = image::open(&a[0])?.to_rgb8();
diff --git a/crates/benilla-formats/examples/scan_events.rs b/crates/benilla-formats/examples/scan_events.rs
index db55a8ac..f4440e0c 100644
--- a/crates/benilla-formats/examples/scan_events.rs
+++ b/crates/benilla-formats/examples/scan_events.rs
@@ -1,12 +1,7 @@
-//! Which models author a given M2 animation event? `cargo run -p benilla-formats --example
-//! scan_events -- '$CCH' weapon` — scans every `.m2` in the 5875 chain whose path contains the
-//! (optional, case-insensitive) substring and prints each model authoring the 4CC, with the
-//! event's bone and raw WoW position. The sibling of `dump_attach`: that answers "what does THIS
-//! model author", this answers "who else authors THIS event" — the question every event-keyed
-//! consumer (bowstring `$WTT`, fishing line `$CCH`, GO sound slots `$GC0`) eventually asks when
-//! deciding whether the ident alone is a safe gate.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! Every M2 authoring a given animation-event 4CC, with the event's bone and raw position, to
+//! check whether the ident alone is a safe gate (`$WTT` bowstring, `$CCH` fishing line).
+//! `cargo run -p benilla-formats --example scan_events -- '$CCH' [path-substring]`
+//! Output is Blizzard data: never commit it.
 
 fn le_u32(b: &[u8], o: usize) -> u32 {
     u32::from_le_bytes(b[o..o + 4].try_into().unwrap())
diff --git a/crates/benilla-formats/examples/seamswing.rs b/crates/benilla-formats/examples/seamswing.rs
index a82357d7..6ba18fe6 100644
--- a/crates/benilla-formats/examples/seamswing.rs
+++ b/crates/benilla-formats/examples/seamswing.rs
@@ -1,26 +1,14 @@
-//! Where does a welded billboard bone's geometry SIT relative to its pivot — how far, and along
-//! which local axis?
-//!
-//! Two readings, and the second is the one that decides anything. **Distance** answers the seam
-//! question: a partially-weighted seam vertex is dragged by its weight times the re-orientation and
-//! linear-blend skinning shrinks it toward the pivot on the way (the candy-wrapper), so a seam ring
-//! sitting ON the pivot hinges cleanly and one sitting far out tears.
-//!
-//! **Direction answers whether the geometry moves at all.** A spherical billboard maps the bone's
-//! local axes onto fixed camera axes, so an offset lying along a single local axis lands on the same
-//! camera axis from every angle: it does not sweep, it only loses its roll and its foreshortening.
-//! Only an offset spread across the axes sweeps. Magnitude alone cannot tell those apart, and
-//! reading a 0.29 yd radius as a 0.29 yd arc is exactly how decision 0847 withdrew a correct change
-//! — the spikes it measured run **along** their bone (worst vertex 12° off axis), so the sweep it
-//! described never existed (wow-re `billboard-bone-law.md` §6.3, and this tool's own output).
-//!
-//! Usage: `cargo run -p benilla-formats --example seamswing -- <WoW/Data> <internal\path.m2>`
+//! Where a welded billboard bone's geometry sits relative to its pivot: how far, and along which
+//! local axis. Distance decides the seam, since linear-blend skinning drags a partly weighted
+//! vertex toward the pivot. Direction decides whether the geometry moves at all: a spherical
+//! billboard (`0x71547c`) maps local axes onto fixed camera axes, so an offset along one axis only
+//! loses its roll and foreshortening, while one spread across the axes sweeps.
+//! `cargo run -p benilla-formats --example seamswing -- <WoW/Data> <internal\path.m2>`
 
 use benilla_formats::open_chain;
 
 fn main() -> anyhow::Result<()> {
     let mut args = std::env::args().skip(1);
-    // An explicit dir still wins; with none, ask the one resolver (decision 1175).
     let data = args
         .next()
         .map(std::path::PathBuf::from)
@@ -37,8 +25,7 @@ fn main() -> anyhow::Result<()> {
     for &b in &denied {
         let bone = &model.bones[b as usize];
         let piv = [bone.pivot.x, bone.pivot.y, bone.pivot.z];
-        // Every vertex with any weight on this bone: its weight, and its distance from the pivot —
-        // which is the radius the re-orientation sweeps it around.
+        // Every vertex weighted to this bone, with its weight and its distance from the pivot.
         let (mut pure, mut seam) = (Vec::new(), Vec::new());
         for v in &model.vertices {
             for i in 0..4 {
@@ -83,12 +70,7 @@ fn main() -> anyhow::Result<()> {
         if let Some(&(w, _)) = seam.first() {
             println!("  seam weight on this bone: {w:.2}");
         }
-        // DIRECTION, which is what actually decides whether re-orientation moves the geometry.
-        // A spherical billboard maps the bone's local axes to fixed camera axes, so an offset that
-        // lies along ONE local axis lands on that camera axis from every angle: it does not sweep,
-        // it only loses its roll and its foreshortening. An offset spread across the axes does
-        // sweep. Magnitude alone cannot tell these apart — decision 0847 read a 0.29 yd radius as a
-        // 0.29 yd arc and withdrew a correct change on the strength of it.
+        // Direction: the local axis the offsets run along, and how far the worst vertex strays.
         if !pure.is_empty() {
             let mut lo = [f32::MAX; 3];
             let mut hi = [f32::MIN; 3];
@@ -98,10 +80,8 @@ fn main() -> anyhow::Result<()> {
                     hi[k] = hi[k].max(o[k]);
                 }
             }
-            // The DIRECTION axis is the one the offsets are largest along — NOT the one they are
-            // most spread across. Those differ here and confusing them inverts the reading: this
-            // spike runs along z (|z| ≈ 0.29) but is widest across y (spread 0.105, its cross
-            // section). Report both, named, so neither can be mistaken for the other.
+            // The axis the offsets are largest along is not the one they spread widest across (a
+            // spike's cross section); both print, named.
             let mean_abs =
                 |k: usize| pure.iter().map(|&(_, o)| o[k].abs()).sum::<f32>() / pure.len() as f32;
             let along = (0..3)
@@ -110,8 +90,6 @@ fn main() -> anyhow::Result<()> {
             let widest = (0..3)
                 .max_by(|&a, &c| (hi[a] - lo[a]).total_cmp(&(hi[c] - lo[c])))
                 .unwrap();
-            // How far the WORST vertex strays from that one axis — the number that decides whether
-            // "runs along a single axis" is a fair description of the whole batch or only its mean.
             let worst_deg = pure
                 .iter()
                 .filter(|&&(d, _)| d > 1e-6)
diff --git a/crates/benilla-formats/examples/spell_interrupt.rs b/crates/benilla-formats/examples/spell_interrupt.rs
index 7cf57532..238583fa 100644
--- a/crates/benilla-formats/examples/spell_interrupt.rs
+++ b/crates/benilla-formats/examples/spell_interrupt.rs
@@ -1,5 +1,4 @@
-//! Throwaway: print the interrupt-flag columns for named spell ids, so a claim about what
-//! cancels a spell locally can be checked against the real shipped Spell.dbc.
+//! The interrupt-flag and attribute columns of `Spell.dbc` for the given spell ids.
 fn main() -> anyhow::Result<()> {
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = benilla_formats::open_chain(&data)?;
diff --git a/crates/benilla-formats/examples/spell_row.rs b/crates/benilla-formats/examples/spell_row.rs
index e08de5b0..375f586a 100644
--- a/crates/benilla-formats/examples/spell_row.rs
+++ b/crates/benilla-formats/examples/spell_row.rs
@@ -1,7 +1,5 @@
-//! Throwaway: print the cast-arm targeting facts for named spell ids — `Targets`,
-//! `EffectImplicitTargetA[0]`, the three effects, and the item-target gate columns — so a claim
-//! about which targeting seam a spell arms can be checked against the real shipped Spell.dbc
-//! instead of reasoned about.
+//! The targeting columns of `Spell.dbc` for the given spell ids: `Targets`,
+//! `EffectImplicitTargetA[0]`, the first effect and the equipped-item gate columns.
 fn main() -> anyhow::Result<()> {
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = benilla_formats::open_chain(&data)?;
diff --git a/crates/benilla-formats/examples/srci_dump.rs b/crates/benilla-formats/examples/srci_dump.rs
index 59279abb..be56dfd3 100644
--- a/crates/benilla-formats/examples/srci_dump.rs
+++ b/crates/benilla-formats/examples/srci_dump.rs
@@ -1,6 +1,6 @@
-//! Throwaway: dump `SkillRaceClassInfo.dbc` rows admitting a race/class, with the flags word in
-//! hex — the table the client's `GetSkillLineInfo` reads for its 0x400 single-rank cap and 0x20
-//! unlearnable bit. Usage: `cargo run -p benilla-formats --example srci_dump -- <race> <class>`.
+//! `SkillRaceClassInfo.dbc` rows admitting a race and class, flags in hex: `GetSkillLineInfo` reads
+//! its 0x400 single-rank cap and 0x20 unlearnable bit here.
+//! `cargo run -p benilla-formats --example srci_dump -- <race> <class>`
 fn main() -> anyhow::Result<()> {
     let mut args = std::env::args().skip(1);
     let race: u32 = args.next().unwrap_or_else(|| "4".into()).parse()?;
@@ -8,7 +8,6 @@ fn main() -> anyhow::Result<()> {
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = benilla_formats::open_chain(&data)?;
 
-    // Skill line names, so the dump reads.
     let lines = chain.read_file("DBFilesClient\\SkillLine.dbc")?;
     let name_of = |id: u32| -> String {
         let g = |b: &[u8], o: usize| u32::from_le_bytes(b[o..o + 4].try_into().unwrap());
@@ -48,7 +47,7 @@ fn main() -> anyhow::Result<()> {
             g(base + 20),
             g(base + 24),
         );
-        // race/class 0 = dump EVERY row (masks unfiltered, duplicates kept).
+        // Race or class 0 dumps every row, unfiltered, duplicates kept.
         let all = race == 0 || class == 0;
         if !all && (race_mask & rmask == 0 || class_mask & cmask == 0 || seen.contains(&skill)) {
             continue;
diff --git a/crates/benilla-formats/examples/surface_here.rs b/crates/benilla-formats/examples/surface_here.rs
index 01e3c51d..2ee75e2b 100644
--- a/crates/benilla-formats/examples/surface_here.rs
+++ b/crates/benilla-formats/examples/surface_here.rs
@@ -1,28 +1,14 @@
-//! What surface the footstep chain resolves under a patch of world:
+//! The footstep surface the ADT leg resolves around a pin, as a top-down map of `TerrainType`s
+//! (north up, west left), and at the pin the whole chain to the sound kit. The client arbitrates
+//! this against a WMO probe and the nearer surface wins, so indoors this is the ground under the
+//! floor; `RUST_LOG=benilla_app::sound=debug` logs which leg answered in a live run. Output is
+//! Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example surface_here -- <map> <x> <y> [radius_yd] [class]`
-//! e.g. `surface_here Azeroth -5595.89 -529.48 24`.
-//!
-//! A footstep bug is reported as a *sound* ("I'm walking on snow indoors") but it is decided far
-//! upstream, by which surface the down-ray claims under the foot. This prints that claim as a
-//! top-down map — north up, west left — so the answer is a picture of the ground rather than an
-//! impression of the audio: per cell the `TerrainType` the chain lands on, and at the pin the full
-//! walk through to the `SoundEntries` kit that would actually play.
-//!
-//! **This is the ADT leg only** — deliberately. The client (and, since decision 1161, benilla)
-//! arbitrates this against a WMO probe and the nearer surface wins, so inside a building the live
-//! answer comes from the floor, not from here. What this map shows indoors is the ground *under*
-//! that floor: the counterfactual. That is what makes a wrong-surface report legible — B236's
-//! sequel was "snow indoors", and this printed 1681 of 1681 cells Snow beneath the Kharanos inn.
-//! To see which leg actually answered in a live run, use `RUST_LOG=benilla_app::sound=debug` and
-//! read the `footstep: wmo|adt terrain N` line.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 use std::collections::HashMap;
 
-/// `TerrainType.SoundID` → its authored name and map glyph. The domain is closed and verified
-/// against build 5875 (`benilla_formats::footsteps` module docs): the eleven rows collapse to ten
-/// sound classes, `DustyGrass` sharing `Grass`'s.
+/// `TerrainType.SoundID` to its name and map glyph; the eleven shipped rows use ten sound classes,
+/// `DustyGrass` sharing `Grass`'s.
 fn class_glyph(sound_class: u32) -> (char, &'static str) {
     match sound_class {
         0 => ('.', "None"),
@@ -47,8 +33,7 @@ fn main() -> anyhow::Result<()> {
     let x: f32 = args.next().ok_or_else(usage)?.parse()?;
     let y: f32 = args.next().ok_or_else(usage)?.parse()?;
     let radius: f32 = args.next().map_or(Ok(20.0), |r| r.parse())?;
-    // 7 is the humanoid/character class (its ten rows are the `CharacterMediumLarge*` kits); 8 is
-    // the small-character class. Both reach it as ordinary data, never a code default.
+    // Class 7 is the character class (the `CharacterMediumLarge*` kits), 8 the small character.
     let class: u32 = args.next().map_or(Ok(7), |c| c.parse())?;
 
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
@@ -56,8 +41,7 @@ fn main() -> anyhow::Result<()> {
     let cat = benilla_formats::load_footstep_catalog(&mut chain)?;
     let tiles = benilla_formats::MapTiles::load(&mut chain, &map)?;
 
-    // One sample per cell of a square centred on the pin, north (+x) up and west (+y) left — the
-    // orientation the in-game map uses, so a spot on this grid is a spot on their screen.
+    // One sample per cell of a square on the pin, north (+x) up and west (+y) left, as the map.
     let cols = 41usize;
     let step = (radius * 2.0) / (cols - 1) as f32;
     let mut meshes: HashMap<(u32, u32), Option<benilla_formats::TileMesh>> = HashMap::new();
@@ -90,7 +74,7 @@ fn main() -> anyhow::Result<()> {
             *census.entry(terrain).or_default() += 1;
             let glyph = match terrain.and_then(|t| cat.sound_class_of(t)) {
                 Some(sc) => class_glyph(sc).0,
-                // No effect layer / unknown terrain — the client's −1 sentinel, a SILENT footfall.
+                // No effect layer or unknown terrain: the client's -1 sentinel, a silent footfall.
                 None => ' ',
             };
             line.push(glyph);
@@ -118,7 +102,7 @@ fn main() -> anyhow::Result<()> {
         println!("  {n:5}  {label}");
     }
 
-    // The pin itself, walked end to end — the line a bug report can be checked against.
+    // The pin itself, walked end to end.
     let effect = sample(&mut chain, &mut meshes, x, y);
     println!("\nat the pin exactly:");
     println!("  GroundEffectTexture: {effect:?}");
diff --git a/crates/benilla-formats/examples/water_here.rs b/crates/benilla-formats/examples/water_here.rs
index 8ef2c692..b0f66157 100644
--- a/crates/benilla-formats/examples/water_here.rs
+++ b/crates/benilla-formats/examples/water_here.rs
@@ -1,43 +1,15 @@
-//! What the ADT liquid actually **is** under a pin — the shoreline instrument:
+//! The ADT liquid under a pin against the terrain it lies on: the MCLQ blocks, overlapping and
+//! stepped cells, and where the 4.167-yd wet-cell lattice ends short of or past the waterline.
+//! Output is Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example water_here -- <map> <x> <y> [radius_yd]`
-//! e.g. `water_here Azeroth -12512.69 -180.21 40`.
-//!
-//! A water-at-the-shore report ("there's a step in it", "the foam runs past the waterline") is a
-//! question about three surfaces that only ever agree in the middle of a lake: the MCLQ **wet-cell
-//! lattice** (4.167-yd cells, the granularity everything on the water path clips to), the liquid
-//! **surface height** on those cells, and the **terrain** underneath. This prints all three over one
-//! neighbourhood so the geometry can be read instead of guessed:
-//!
-//! - the **block census** — one line per MCLQ block: kind, wet cells, surface-height span, depth-byte
-//!   span. Where a step would be *authored*, this is where it shows: two blocks over one chunk, or a
-//!   block whose own plane has relief;
-//! - the **overlap** scan — cells claimed by two blocks at once, which would composite the
-//!   translucent water twice;
-//! - the **seam** scan — every pair of adjacent wet cells whose planes disagree, so an authored step
-//!   can be told apart from a rendered one before anyone opens the renderer;
-//! - the **lattice-vs-waterline** scan — dry cells the ground still runs under. Whole wet cells are
-//!   the only thing the renderer draws, so wherever the lattice runs out before the ground climbs
-//!   through the plane, the water ends on a 4.167-yd straight edge in open water: a shape no
-//!   shoreline has;
-//! - its **mirror** — wet cells the ground climbs out of, which is the skirt of liquid-lattice
-//!   geometry that lies over dry sand. Nothing renders there only because the terrain drew first
-//!   and won the depth test, so this is the exact budget a depth bias spends: a decal pulled `b`
-//!   yards toward the eye paints `b / slope` yards of that skirt;
-//! - the **shoreline slope** at the pin, and what a coplanarity *lift* costs there. A decal held `l`
-//!   yards above the water plane keeps painting for `l / slope` yards past the waterline, on dry
-//!   ground — the arithmetic behind B348's foam-on-the-sand, and the reason that settle is a depth
-//!   bias now and not a lift.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 use std::collections::BTreeMap;
 
 use benilla_formats::{terrain_height_at, ChunkMesh, CHUNK_SIZE};
 
-/// One MCLQ cell edge, in yards — the granularity of `wet`, and of every clip on the water path.
+/// One MCLQ cell edge in yards, the granularity of `wet` and of every clip on the water path.
 const CELL: f32 = CHUNK_SIZE / 8.0;
-/// How far past the reported radius the block census still enumerates, so that a cell at the edge
-/// of the answer has its real neighbours to be judged against (one chunk clears it).
+/// How far past the radius the census enumerates, so an edge cell has its real neighbours.
 const MARGIN: f32 = CHUNK_SIZE;
 
 /// One seam between two adjacent wet cells whose surface planes disagree.
@@ -50,14 +22,13 @@ struct Seam {
 
 /// One MCLQ cell of one block, resolved into world terms.
 struct Cell {
-    /// Cell-centre world XY.
     x: f32,
     y: f32,
-    /// The block's surface height over the cell (bilinear at the centre, as the queries sample it).
+    /// Surface height at the cell centre, bilinear, as the queries sample it.
     surface: f32,
     /// Terrain height at the same point, `None` where the tile has a hole.
     ground: Option<f32>,
-    /// Which chunk/block this cell came from — `(chunk index, block index)`.
+    /// `(chunk index, block index)`.
     owner: (usize, usize),
     kind: benilla_formats::LiquidKind,
 }
@@ -86,10 +57,7 @@ fn main() -> anyhow::Result<()> {
         let Some(nw) = chunk.positions.first() else {
             continue;
         };
-        // The chunk's own footprint against the pin box (chunk spans south/east of its NW corner),
-        // widened by MARGIN so every cell inside the radius has its real neighbours loaded — a cell
-        // at the box edge would otherwise read as "the lattice stops here" when it is only the
-        // enumeration that stopped.
+        // The chunk's footprint (south and east of its NW corner) against the box plus `MARGIN`.
         if nw[0] - CHUNK_SIZE > x + radius + MARGIN
             || nw[0] < x - radius - MARGIN
             || nw[1] - CHUNK_SIZE > y + radius + MARGIN
@@ -158,8 +126,7 @@ fn main() -> anyhow::Result<()> {
     }
 
     // ── Overlap: two blocks claiming one patch of world, at two heights ──────────────────────
-    // Key a cell by its lattice index, floored — two DIFFERENT cells of one block must never
-    // collide, or the overlap report cries wolf on its own rounding.
+    // Key a cell by its floored lattice index, so two cells of one block never collide.
     let key = |c: &Cell| ((c.x / CELL).floor() as i32, (c.y / CELL).floor() as i32);
     let mut by_key: BTreeMap<(i32, i32), Vec<usize>> = BTreeMap::new();
     for (n, c) in cells.iter().enumerate() {
@@ -212,12 +179,9 @@ fn main() -> anyhow::Result<()> {
         println!("    {:?} -> {:?}  dz {:+.3} yd", s.from, s.to, s.dz);
     }
 
-    // ── Where the LATTICE stops vs where the WATERLINE is ────────────────────────────────────
-    // The renderer draws whole wet cells and nothing else, so the water's visible boundary is the
-    // *lattice* edge wherever the lattice runs out before the ground climbs through the plane. That
-    // edge is a 4.167-yd straight line in open water — the shape a shoreline never has. Sample every
-    // dry cell that touches a wet one on a 0.25-yd grid and report how deep the water would have
-    // been there.
+    // ── Where the lattice stops vs where the waterline is ────────────────────────────────────
+    // The renderer draws whole wet cells only, so where the lattice ends before the ground rises
+    // through the plane the water ends on a straight cell edge; sample each dry neighbour's depth.
     let mut short_cells: Vec<(f32, (i32, i32))> = Vec::new();
     for k in by_key.keys().copied().collect::<Vec<_>>() {
         for nb in [
@@ -260,13 +224,9 @@ fn main() -> anyhow::Result<()> {
         );
     }
 
-    // ── The mirror: WET cells the ground climbs out of ───────────────────────────────────────
-    // The scan above finds water that is missing; this one finds water geometry that is *over dry
-    // land*. Whole wet cells are the unit the renderer draws, so wherever the ground climbs through
-    // the plane inside a cell, the liquid mesh — and every decal built on the same lattice — carries
-    // a skirt of geometry up the beach. Nothing renders there only because the terrain drew first
-    // and won the depth test, which makes this number the exact **budget a depth bias spends**: a
-    // decal pulled `b` yards toward the eye paints `b / slope` yards of that skirt onto the sand.
+    // ── The mirror: wet cells the ground climbs out of ───────────────────────────────────────
+    // The liquid mesh and every decal on its lattice carry a skirt up the beach that only the depth
+    // test hides, so a decal pulled `b` yards toward the eye paints `b / slope` yards of it.
     let mut skirts: Vec<(f32, f32, (i32, i32))> = Vec::new(); // (height above plane, run inland, cell)
     for (k, idxs) in by_key.iter() {
         let c = &cells[idxs[0]];
@@ -319,9 +279,8 @@ fn main() -> anyhow::Result<()> {
     }
 
     // ── The waterline's slope, and what a coplanarity lift costs horizontally ────────────────
-    // A decal on the water plane, lifted `l` yards to win the coplanar tie, keeps painting for
-    // `l / slope` yards past the waterline — up the beach, on dry ground. Measure the slope where
-    // the plane actually meets the ground nearest the pin.
+    // A decal lifted `l` yards off the water plane paints `l / slope` yards past the waterline; the
+    // slope is measured where the plane meets the ground nearest the pin.
     let mut best: Option<(f32, f32, f32, f32)> = None; // (dist to pin, x, y, slope)
     for c in &cells {
         let Some(g) = c.ground else { continue };
diff --git a/crates/benilla-formats/examples/what_is_here.rs b/crates/benilla-formats/examples/what_is_here.rs
index f9ed651d..a8bf63e6 100644
--- a/crates/benilla-formats/examples/what_is_here.rs
+++ b/crates/benilla-formats/examples/what_is_here.rs
@@ -1,14 +1,7 @@
-//! What is actually standing at a world coordinate:
+//! The WMO and M2 doodad placements within a radius of a pin, nearest first. Two batches of one WMO
+//! share its authored MOBA order; a WMO and a nearby doodad have no ordering relationship.
+//! Output is Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example what_is_here -- <map> <x> <y> [radius_yd]`
-//! e.g. `what_is_here Kalimdor 295.72 -3689.61 60`.
-//!
-//! A bug report names a *place* — a `.go xyz` pin — and every scene-render diagnosis starts by
-//! turning that pin into the **placements** behind it: which WMOs and which M2 doodads, with their
-//! distance from the pin. The distinction is load-bearing for draw-order defects: two batches of one
-//! WMO share the authored MOBA order the pipeline biases by, while a WMO and a nearby M2 doodad are
-//! separate lanes with no ordering relationship at all.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 fn main() -> anyhow::Result<()> {
     let mut args = std::env::args().skip(1);
@@ -24,8 +17,7 @@ fn main() -> anyhow::Result<()> {
     let (tx, ty) = tiles.tile_at(x, y);
     println!("{map}: pin ({x}, {y}) is tile {tx}_{ty}; scanning r={radius} yd across 3x3");
 
-    // The pin can sit near a tile seam and the building it names be authored in the neighbour, so
-    // sweep the 3x3 — a placement is deduped by uniqueId, which is stable across the tiles it spans.
+    // Sweep the 3x3 tiles; a placement spanning several is deduped by its uniqueId.
     let mut seen_wmo = std::collections::HashSet::new();
     let mut seen_doodad = std::collections::HashSet::new();
     let mut wmos: Vec<(f32, String, [f32; 3], u32)> = Vec::new();
diff --git a/crates/benilla-formats/examples/where.rs b/crates/benilla-formats/examples/where.rs
index 445dec61..930a350c 100644
--- a/crates/benilla-formats/examples/where.rs
+++ b/crates/benilla-formats/examples/where.rs
@@ -1,16 +1,6 @@
-//! `cargo run -p benilla-formats --example where` — **where does benilla think the install is?**
-//!
-//! The resolver's own answer, printed (decision 1175). Two callers, and both are the reason this
-//! is a program rather than a comment:
-//!
-//! - `scripts/gates.sh`, to decide whether the enforcer gate can run. It used to hand-roll half
-//!   the rule (`[ -n "$WOW_DATA" ] || [ -d WoW/Data ]`), which is exactly the duplication 1175
-//!   exists to end — a gate that disagrees with the client about where the install is will skip
-//!   on a machine where the client would have run, or run on one where it cannot.
-//! - a human whose client came up with no world. "It looked in these four places and none of them
-//!   existed" is actionable; "the terrain just doesn't appear" is not.
-//!
-//! Exits **0** when an install was found and **1** when none was, so a shell can branch on it.
+//! The install benilla's resolver finds, or every place it looked; exits 1 when there is none.
+//! `scripts/gates.sh` asks this rather than repeating the rule.
+//! `cargo run -p benilla-formats --example where`
 
 fn main() -> std::process::ExitCode {
     match benilla_formats::wow_data() {
diff --git a/crates/benilla-formats/examples/wmo_antiportal_census.rs b/crates/benilla-formats/examples/wmo_antiportal_census.rs
index cd72612d..be9f00fa 100644
--- a/crates/benilla-formats/examples/wmo_antiportal_census.rs
+++ b/crates/benilla-formats/examples/wmo_antiportal_census.rs
@@ -1,63 +1,13 @@
-//! **Do any 1.12.1 WMOs author an ANTIPORTAL group, and if so which MOGP bit says so?**
-//! `cargo run -p benilla-formats --example wmo_antiportal_census`.
+//! Whether any shipped WMO group has the wowdev `ANTIPORTAL` shape (no MOBA render batches, only a
+//! MOGI box) and which MOGP flag bit, if any, marks it: a histogram of every bit, the batch-less
+//! groups found without reading flags, and the two cross-tabulated.
+//! `cargo run -p benilla-formats --example wmo_antiportal_census`
 //!
-//! Later WoW documentation (wowdev.wiki `SMOGroupFlags`) names a high MOGP `flags` bit
-//! `ANTIPORTAL`: a group with **no render batches at all**, kept only for its bounding box, which
-//! the portal flood uses as an occluder rather than something it ever draws. Nothing in benilla or
-//! `wow-5875-re` has verified that bit for build 5875 — the portal flood
-//! ([`benilla_world::wmo_portal`]) only ever branches on `flags & 0x48` (EXTERIOR / EXTERIOR_LIT)
-//! and never treats any group as occlusion-only. So the question is purely empirical: does the
-//! shipped 5875 data contain such a group at all, and which bit(s) does it carry?
-//!
-//! **Bit-agnostic by construction.** Rather than assume the wowdev bit number applies unchanged to
-//! this build, this walks every group of every root WMO in the install and builds two independent
-//! signals, then cross-tabulates them:
-//!
-//! 1. A histogram of **every** MOGP flag bit (0..31) — how many groups set it, how many distinct
-//!    roots contain at least one.
-//! 2. The **batch-less set** — every group whose MOGP-owned MOBA chunk has zero render batches,
-//!    found without looking at flags at all. This is the wowdev ANTIPORTAL *shape*: no geometry to
-//!    draw, kept only for `MOGI`'s bounding box.
-//!
-//! If 1.12 ships any antiportal-shaped groups, they land in the batch-less set regardless of which
-//! bit (if any) names them, and the cross-tab against the flag histogram is what tells us — from
-//! the data, not a doc — which bit (if any) 5875 actually uses for it.
-//!
-//! **The run (2026-09-01, 815/815 roots, 5220/5220 groups, zero read/parse failures): yes, but no
-//! single bit names it.** 15 groups across 9 roots ship with zero MOBA render batches — Naxxramas'
-//! `frostwyrm_final01.wmo` (7 tiny connector groups), three of AQ40's boss-encounter "enterance"
-//! shells, and the three Hyjal `worldtreeroots` collision volumes among them (see the batch-less
-//! census below for the full list) — so the wowdev *shape* is real in 5875. But the cross-tab finds
-//! **no MOGP bit set by all 15 and rare among the other 5205**: bit 0 (`0x1`) is set on literally
-//! every group in the corpus (batch-less or not) and so distinguishes nothing; EXTERIOR (`0x8`)
-//! covers 13/15 but also 1052/5205 batch-having groups; every other bit covers fewer than a third of
-//! the batch-less set. Whatever these 15 groups are for — several read as pure collision volumes by
-//! name/folder (`collidabledoodads\hyjal\worldtreeroots`) rather than deliberate portal occluders —
-//! 5875 does not flag them with a dedicated ANTIPORTAL bit the way later clients' `SMOGroupFlags`
-//! documentation describes. That is a fact about the *data*, not yet about the *engine*: whether
-//! `WoW.exe` 5875's occluder pass (if it has one) singles these 15 out by shape rather than by flag
-//! is a `wow-5875-re` question this census doesn't answer.
-//!
-//! Only three MOGP bits are named anywhere in benilla's own code today (verified by grep over
-//! `benilla-world/src/wmo_portal`, `benilla-assets/src/wmo.rs`, and
-//! `benilla-formats/src/models/wmo`, 2026-09-01): `0x8` EXTERIOR, `0x40` EXTERIOR_LIT
-//! ([`benilla_world::wmo_portal`]'s flood-defer/lighting-class bits), and `0x40000` SHOW_SKYBOX
-//! ([`benilla_formats::WmoGroupInfo::show_skybox`]). The other candidate bits a hypothetical
-//! ANTIPORTAL census might reach for — `0x1` (HAS_BSP/MOBN), `0x4` (VERTEXCOLOR), `0x200`
-//! (HAS_LIGHTS/MOLR), `0x800` (HAS_LIQUID/MLIQ), `0x2000` (INTERIOR), `0x800000`/`0x1000000`
-//! (second MOCV/MOTV) — are *not* named or tested anywhere in our reader: we discover MOLR/MLIQ/a
-//! second MOTV by the sub-chunk's presence, never by these flag bits, and INTERIOR is our own
-//! `flags & 0x48 == 0` derived test, not a single bit. None of those six get a name in the table
-//! below; only a bit our code already states gets one, per the census's own charter.
-//!
-//! Every field per group comes from the same bytes the runtime reads: [`wmo_group_header`]'s
-//! `flags` (MOGP `+0x08`, full 32 bits — **not** the two-bit-derived `interior`/`show_skybox` bools
-//! `parse_wmo_root`'s MOGI reader exposes), `benilla_wmo::parse_wmo`'s `render_batches`/
-//! `vertex_positions` (MOBA/MOVT), `wmo_group_header`'s `portal_ref_count` (MOPR, sliced from the
-//! group's own header span), and the root's [`WmoGroupInfo`] bounding box (MOGI, the same box the
-//! portal code treats as a loose AABB of the group's volume).
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! 15 shipped groups are batch-less, and no bit singles them out. The 1.12 client has no antiportal
+//! branch on the group flags (the only bits above `0x10000` it tests are `0x40000` at `0x6b42e0`
+//! and `0x20000` at `0x6c46a6`), so a batch-less group is invisible geometry, not an occluder.
+//! Flags are MOGP's own 32 bits at `+0x08`, in every shipped group a superset of the MOGI copy.
+//! Output is Blizzard data: never commit it.
 
 use std::collections::{BTreeMap, BTreeSet};
 use std::io::Cursor;
@@ -65,48 +15,39 @@ use std::io::Cursor;
 use benilla_formats::{parse_wmo_root, wmo_group_header, Chain};
 use benilla_wmo::{parse_wmo, ParsedWmo};
 
-/// A bit counts as "rare" — and earns an example listing — below this many groups. Chosen well
-/// above the size of any plausible antiportal set (a handful of buildings at most) and well below
-/// EXTERIOR/EXTERIOR_LIT, which sit in the thousands.
+/// Below this many groups a bit is rare and gets an example listing.
 const RARE_THRESHOLD: u32 = 200;
-/// Example rows kept per rare bit.
 const MAX_EXAMPLES: usize = 40;
-/// Batch-less rows printed in full before the report falls back to "N more, elided".
 const MAX_BATCHLESS_PRINTED: usize = 200;
-/// Root-failure examples kept for the audit trail.
 const MAX_FAILURE_EXAMPLES: usize = 20;
-/// Rows in the "most EXTERIOR groups" table (see its section for why that ranking is worth having).
 const MAX_EXTERIOR_RANK: usize = 25;
 
-/// MOGP EXTERIOR — the bit the deferred-window worklist and its Pass-2 replay key on.
+/// The MOGP EXTERIOR bit.
 const EXTERIOR: u32 = 0x8;
 
-/// One group's full fact row — what every example listing and the batch-less census print.
+/// One group's facts, as the listings print them.
 #[derive(Clone)]
 struct GroupRow {
-    /// The ROOT's chain path (e.g. `world\wmo\...\foo.wmo`); the group file is `{stem}_{NNN}.wmo`.
+    /// The root's chain path; the group file is `{stem}_{NNN}.wmo`.
     root_path: String,
     group_index: u32,
-    /// MOGP `flags` @ `+0x08`, all 32 bits, unfiltered.
+    /// MOGP `flags` at `+0x08`, all 32 bits.
     flags: u32,
     /// MOBA render-batch count.
     batches: usize,
     /// MOVT vertex count.
     vertices: usize,
-    /// MOPR portal-ref count (this group's slice, from its own MOGP header span).
+    /// MOPR portal-ref count, this group's slice from its own MOGP header.
     portal_refs: u16,
-    /// MOGI bounding box, WMO model space (WoW axes) — `None` if the root's MOGI table is shorter
-    /// than its declared group count (never observed, but not asserted away).
+    /// MOGI bounding box in model space; `None` if the MOGI table is shorter than the group count.
     bbox: Option<([f32; 3], [f32; 3])>,
 }
 
 impl GroupRow {
-    /// `{root}#{group}` for compact example rows.
     fn label(&self) -> String {
         format!("{}#{:03}", self.root_path, self.group_index)
     }
 
-    /// Bounding-box extent (max − min) per axis, or `?` if MOGI didn't carry one.
     fn bbox_str(&self) -> String {
         match self.bbox {
             Some((min, max)) => {
@@ -121,8 +62,7 @@ impl GroupRow {
     }
 }
 
-/// Per-bit tally: how many groups/roots set it, split by batch-less vs. batch-having, plus a
-/// bounded example list for the rare-bit report.
+/// Per-bit tally of groups and roots, batch-less against batch-having, with examples.
 #[derive(Default)]
 struct BitStat {
     groups: u32,
@@ -132,14 +72,12 @@ struct BitStat {
     examples: Vec<GroupRow>,
 }
 
-/// Normalize a chain path the way the MPQ hash compares them (matches `wmo_ownerless_pools`).
+/// A chain path normalised as the MPQ hash compares it.
 fn key(name: &str) -> String {
     name.replace('/', "\\").to_ascii_lowercase()
 }
 
-/// Bench a known-name label for a MOGP bit — filled in ONLY for bits benilla's own code already
-/// names as a flag test (verified 2026-09-01; see the module doc for what was checked and ruled
-/// out). Everything else prints blank: this census must not invent names the data alone can't back.
+/// A name only for the MOGP bits benilla's own code tests as flags; the rest print blank.
 fn known_name(bit: u32) -> &'static str {
     match bit {
         3 => "EXTERIOR (0x8)",
@@ -154,12 +92,8 @@ fn main() -> anyhow::Result<()> {
         .ok_or_else(|| anyhow::anyhow!("no 1.12.1 install found (set $WOW_DATA)"))?;
     let chain = Chain::open(&data)?;
 
-    // Every ROOT `.wmo` the chain lists, across every mounted archive — a group file's stem ends
-    // `_NNN`, a root's does not (same heuristic as `wmo_ownerless_pools`). The listfile is not a
-    // provably complete index of every archive (`Chain::list`'s own doc), so a root reachable ONLY
-    // by name and absent from every listfile would be missed here; nothing in the corpus is known
-    // to do that, but the failure counts below exist so a gap like it would show up as a number
-    // rather than silence.
+    // Every root `.wmo` the chain lists (a group file's stem ends `_NNN`, a root's does not); a
+    // root absent from every listfile is missed.
     let roots: BTreeSet<String> = chain
         .list()?
         .into_iter()
@@ -219,10 +153,8 @@ fn main() -> anyhow::Result<()> {
                     continue;
                 }
             };
-            // Two independent reads of the same bytes, deliberately: `wmo_group_header` for the raw
-            // MOGP `flags`/MOPR span (the load-bearing 32 bits this census exists to histogram), and
-            // `benilla_wmo::parse_wmo` for MOBA/MOVT counts — the same split `wmo_group_submeshes`
-            // itself makes.
+            // `wmo_group_header` for the raw MOGP flags and MOPR span, `parse_wmo` for the MOBA and
+            // MOVT counts, the split `wmo_group_submeshes` makes.
             let Some(header) = wmo_group_header(&gbytes) else {
                 group_parse_fail += 1;
                 continue;
@@ -306,17 +238,10 @@ cross-tab below for which flag bit(s) the data implicates.",
         }
     }
 
-    // ==== which buildings own MANY exterior groups ================================================
-    //
-    // Not an antiportal question — a *consumer* one, and the reason it sits in this census rather
-    // than in a throwaway script. The reference draws a building's EXTERIOR groups only through the
-    // deferred portal windows the interior flood leaves behind, each group tested against its own
-    // window's sub-frustum (`wow-5875-re` `wmo-insideleg-phase3.md` Pass 2; benilla decision 1826).
-    // A building with ONE exterior group cannot show that law at work: a single whole-envelope shell
-    // has a box wide enough to intersect any window, so it draws from everywhere and looks identical
-    // either way — which is exactly why Stormwind (306 groups, one `0x8`) is the wrong subject to
-    // eyeball the behaviour on. The buildings below, whose shells are split into many groups, are
-    // where per-window culling is visible at all, and so where a retest belongs.
+    // ==== which buildings own many exterior groups ============================================
+    // The reference draws exterior groups only through the deferred portal windows the interior
+    // flood leaves, each against its own window's sub-frustum (`0x6b3c73`-`0x6b3d6f`); only a
+    // building whose shell is split into many groups shows that culling.
     println!("\n---- roots by EXTERIOR (0x8) group count, top {MAX_EXTERIOR_RANK} ----");
     let mut ranked: Vec<(&String, &u32)> = exterior_per_root.iter().collect();
     ranked.sort_by(|a, b| b.1.cmp(a.1).then_with(|| a.0.cmp(b.0)));
@@ -432,11 +357,7 @@ cross-tab below for which flag bit(s) the data implicates.",
     }
 
     // ==== cross-tab: which bit(s) does the batch-less set actually carry? =========================
-    // For every bit, how it splits across the batch-less/batch-having populations — the
-    // flag-agnostic and flag-based signals collide here. A bit set by (close to) ALL batch-less
-    // groups and by (close to) none of the batch-having ones is the data's own answer to "which bit
-    // means antiportal in 5875"; the reverse (never set on a batch-less group) rules a candidate out
-    // regardless of what later documentation calls it.
+    // A bit set by every batch-less group and rare among the rest would mark antiportals.
     let other_total = groups_scanned - batchless.len() as u32;
     println!(
         "\n---- cross-tab: bit occurrence, batch-less ({} groups) vs. batch-having ({} groups) ----",
diff --git a/crates/benilla-formats/examples/wmo_bsp.rs b/crates/benilla-formats/examples/wmo_bsp.rs
index 08ddc048..78da8ef9 100644
--- a/crates/benilla-formats/examples/wmo_bsp.rs
+++ b/crates/benilla-formats/examples/wmo_bsp.rs
@@ -1,35 +1,20 @@
-//! Which WMO faces the reference's collision BSP can actually **reach** — and which ones we collide
-//! that it never tests:
+//! Which WMO faces the reference's collision BSP can reach, against the faces we collide.
 //! `cargo run -p benilla-formats --example wmo_bsp -- <wmo-path-or-substring>`
-//! e.g. `wmo_bsp cavernsoftime`.
 //!
-//! The reference never brute-forces a WMO's triangles. Every collision query descends the group's
-//! **MOBN** BSP and tests only the faces its leaves list in **MOBR**, then applies the per-face MOPY
-//! reject mask (wow-re `collision.md` § "The WMO per-face MOPY collision mask": leaf `0x6bc700`,
-//! *"a BSP-leaf face is skipped iff `(MOPY.flags & rejectMask) != 0`"* — walking `0x84`, camera
-//! `0x82`). We parse no BSP at all: `accumulate_wmo_group_faces` walks **every** MOPY-passing
-//! triangle. So the two agree only where MOBR happens to reference everything the mask keeps.
-//!
-//! This tool measures that gap per group — how many faces we collide that the reference's BSP cannot
-//! reach, and where they are — which would be the difference between "solid wall" and "walk straight
-//! through" at a WMO the file never asked to be solid. **Measured on CavernsOfTime (decision 0963):
-//! the gap is ZERO across all 35 groups** — MOBR's leaves reach every non-DETAIL face, so our
-//! brute-force set is exactly the reference's reachable set and the shortcut costs nothing but time.
-//! Re-run it on any WMO whose collision is under suspicion before assuming the same.
-//!
-//! `inward` is the other half of the same question, for *rendering*: the share of a group's faces
-//! whose winding normal points at the group's own centroid. A hollow room hull authored to be seen
-//! from inside runs high (CoT's 34 interior groups: 59–100%), which is why the reference — single-sided since
-//! MOMT `0x04` is clear — is see-through from outside, and why we were not until 0680.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! The reference tests only the faces a group's MOBN leaves list in MOBR, skipping one iff
+//! `MOPY.flags & rejectMask != 0`: walking's box query at leaf `0x6bca50` with mask `0x84`, the
+//! camera and LOS segment query at leaf `0x6bc700` with `0x82`. `accumulate_wmo_group_faces`
+//! walks every face the mask keeps, so the two agree only where MOBR reaches them all, as it does
+//! on CavernsOfTime. `inward` counts faces turned toward the centroid: with MOMT `0x04` clear the
+//! reference culls back faces, so a hull built to be seen from inside is see-through from outside.
+//! Output is Blizzard data: never commit it.
 
 use std::collections::HashSet;
 
 use benilla_wmo::{parse_wmo, ParsedWmo};
 
-/// The walking gather's persistent MOPY reject bit (DETAIL/decal) — wow-re mask `0x84` minus the
-/// transient `0x80` visited bit.
+/// Walking's persistent MOPY reject bit (DETAIL): mask `0x84` (`0x6315f0`) minus the transient
+/// `0x80` visited bit.
 const MOPY_DETAIL: u8 = 0x04;
 
 fn main() -> anyhow::Result<()> {
@@ -96,16 +81,12 @@ fn main() -> anyhow::Result<()> {
                     .collect()
             })
             .unwrap_or_default();
-        // Reachability, not mere presence: a face listed in MOBR but sitting under a leaf the
-        // descent never enters is never tested. Walk MOBN from node 0 and union the leaves' spans.
+        // Reachability, not presence: a face under a leaf the descent never enters is never tested.
         let (bsp_reach, bad) = descend(nodes, &mobr);
-        // What the reference's walking query can ever hit: a face the BSP lists AND whose MOPY
-        // clears DETAIL. What we hit: every face whose MOPY clears DETAIL.
+        // Walking in the reference hits reachable faces that clear DETAIL; ours hits all that do.
         let (mut bsp_hit, mut we_hit, mut gap) = (0usize, 0usize, 0usize);
         let mut gap_aabb = [[f32::MAX; 3], [f32::MIN; 3]];
-        // Which way the shell presents. A hollow interior hull is authored to be seen from INSIDE:
-        // its winding normals point at the group's own centroid, so single-sided it is invisible
-        // (and see-through) from outside. Counted over every face, render or not.
+        // Faces whose winding normal points at the group's centroid, over every face.
         let mut centroid = [0.0f64; 3];
         for p in &group.vertex_positions {
             for (c, v) in [p.x, p.y, p.z].into_iter().enumerate() {
@@ -182,7 +163,6 @@ fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
-/// A face's three positions, or `None` if any index is out of range.
 fn face_verts(group: &benilla_wmo::WmoGroup, f: usize) -> Option<[[f32; 3]; 3]> {
     let mut out = [[0.0f32; 3]; 3];
     for (k, slot) in out.iter_mut().enumerate() {
@@ -193,8 +173,8 @@ fn face_verts(group: &benilla_wmo::WmoGroup, f: usize) -> Option<[[f32; 3]; 3]>
     Some(out)
 }
 
-/// The right-hand-rule normal of a face in its authored winding — the direction the face PRESENTS
-/// under the reference's `GL_BACK`/CCW cull (and ours: `wow_to_bevy` is a proper rotation).
+/// A face's right-hand normal in its authored winding: the side it presents under the reference's
+/// CCW back-face cull, and ours, since `wow_to_bevy` is a proper rotation.
 fn winding_normal(group: &benilla_wmo::WmoGroup, f: usize) -> Option<[f32; 3]> {
     let [a, b, c] = face_verts(group, f)?;
     let (u, v) = (
@@ -208,7 +188,6 @@ fn winding_normal(group: &benilla_wmo::WmoGroup, f: usize) -> Option<[f32; 3]> {
     ])
 }
 
-/// A face's centroid.
 fn face_centroid(group: &benilla_wmo::WmoGroup, f: usize) -> Option<[f32; 3]> {
     let vs = face_verts(group, f)?;
     let mut out = [0.0f32; 3];
@@ -218,13 +197,10 @@ fn face_centroid(group: &benilla_wmo::WmoGroup, f: usize) -> Option<[f32; 3]> {
     Some(out)
 }
 
-/// Walk the MOBN tree from node 0 and return the set of MOBR **face indices the descent can
-/// actually reach**, plus a count of malformed references (out-of-range children or face spans).
-///
-/// Node layout (wowdev, stride `0x10` — the stride itself is VERIFIED in wow-re
-/// `models/scratch/re-pass.md`): `u16 flags · i16 negChild · i16 posChild · u16 nFaces ·
-/// u32 faceStart · f32 planeDist`. `flags & 0x4` = leaf. The `bad` counter is the falsifier: read
-/// the layout wrong and children/spans go out of range immediately rather than quietly.
+/// The MOBR face indices a descent from MOBN node 0 can reach, and the count of out-of-range
+/// children or spans, which a misread layout drives up at once. A node is `u16 flags, i16 negChild,
+/// i16 posChild, u16 nFaces, u32 faceStart, f32 planeDist`, stride `0x10` (`0x692f20`), and
+/// `flags & 0x4` marks a leaf.
 fn descend(nodes: &[u8], mobr: &[u16]) -> (HashSet<u16>, usize) {
     let n = nodes.len() / 0x10;
     let (mut seen, mut reach, mut bad) = (vec![false; n], HashSet::new(), 0usize);
diff --git a/crates/benilla-formats/examples/wmo_chunk_census.rs b/crates/benilla-formats/examples/wmo_chunk_census.rs
index 5e5f7698..506a328d 100644
--- a/crates/benilla-formats/examples/wmo_chunk_census.rs
+++ b/crates/benilla-formats/examples/wmo_chunk_census.rs
@@ -1,20 +1,11 @@
-//! Chunk-integrity census over WMO files: walk the top-level chunk list the way the loader's
-//! [`find_wmo_chunk`] walk does and report every file whose chunk stream does not tile exactly — a
-//! chunk whose declared size overruns EOF. The reference **clamps** such a chunk (wow-re
-//! `models.md` "WMO chunk-structure contract": *"reads chunks while the 8-byte header is in-bounds
-//! and clamps the last chunk to EOF … e.g. `Undercity_144.wmo`'s MOGP runs 1 B past EOF,
-//! tolerated"*), so an overrun here must cost us nothing; a file listed as losing a chunk is a bug.
-//!
-//! ```text
-//! cargo run -p benilla-formats --example wmo_chunk_census -- <root.wmo>   # one building
-//! cargo run -p benilla-formats --example wmo_chunk_census -- --all        # the whole corpus
-//! ```
-//!
-//! Output is Blizzard-derived — pipe it to the scratchpad, never into the repo.
+//! WMO files whose top-level chunk stream does not tile exactly, a chunk's declared size running
+//! past EOF, and whether our loader still reads them. The reference clamps the last chunk to EOF
+//! (`0x6c3a60`, `0x6c3f80`: chunks are read while the 8-byte header is in bounds), so
+//! `Undercity_144.wmo`'s MOGP one byte past EOF loads, and a file our loader loses is a bug.
+//! `cargo run -p benilla-formats --example wmo_chunk_census -- <root.wmo> | --all`
+//! Output is Blizzard data: never commit it.
 
-/// Walk `b`'s chunk stream as a pure **data** question: is it exactly tiled, or does some chunk
-/// declare more bytes than the file holds? Returns `(tag, declared_end, file_len)` for the first
-/// over-declared chunk. Whether the loader survives it is asked separately, of the loader itself.
+/// The first chunk declaring more bytes than the file holds, as `(tag, declared_end, file_len)`.
 fn overrun(b: &[u8]) -> Option<(String, usize, usize)> {
     let mut off = 0usize;
     while off + 8 <= b.len() {
@@ -66,8 +57,8 @@ fn main() -> anyhow::Result<()> {
             continue;
         }
         checked += 1;
-        // The loader's own verdict, not a re-implementation of it: a group file must yield its MOGP
-        // header (flags + portal-ref span — losing it dead-ends the portal flood), a root must parse.
+        // The loader's own verdict: a group must yield its MOGP header, which the portal flood
+        // needs, and a root must parse.
         let is_group = b.len() > 16 && &b[12..16] == b"PGOM";
         let loads = if is_group {
             benilla_formats::wmo_group_header(&b).is_some()
diff --git a/crates/benilla-formats/examples/wmo_collision_cost.rs b/crates/benilla-formats/examples/wmo_collision_cost.rs
index b23ef2e2..e70bcbe6 100644
--- a/crates/benilla-formats/examples/wmo_collision_cost.rs
+++ b/crates/benilla-formats/examples/wmo_collision_cost.rs
@@ -1,34 +1,15 @@
-//! What a WMO's **collision** actually costs, and whether its walking gather has a floor at all:
+//! Each WMO's collision triangle counts, walking against camera gather, and the groups whose
+//! walking gather (MOPY DETAIL `0x04` dropped) has no walkable face where the camera's does. The
+//! triangle count drives how long a placement takes to turn solid, against the mover's
+//! `SETTLE_TIMEOUT`. Output is Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example wmo_collision_cost -- <wmo-path-or-substring>...`
-//! e.g. `wmo_collision_cost stratholme.wmo zulgurubcity`.
-//!
-//! The falsifier for a **fall-through** report, which has exactly two shapes and they take opposite
-//! fixes:
-//!
-//! * **No floor to stand on** — the walking gather (`flags & 0x04` DETAIL dropped) came back with no
-//!   upward-facing faces in a group the camera gather *does* see. Then the collider is present and
-//!   correct and still cannot hold you: the authored floor is flagged decal-only. A data fact, fixed
-//!   by widening the gather, and visible here without entering the game.
-//! * **A floor that arrives too late** — the faces are there, but the placement's trimesh is big
-//!   enough that its off-thread build plus the per-frame attach budget runs past the mover's settle
-//!   timeout, so gravity switches on over geometry that is not solid yet. A *timing* fact; this
-//!   prints the triangle count that drives it, so the margin can be compared against
-//!   `SETTLE_TIMEOUT` without guessing which buildings are the heavy ones.
-//!
-//! Both readings are properties of the shipped file, so read them here rather than inferring them
-//! from a fall you may or may not be able to reproduce on your own machine — the timing shape
-//! reproduces only on a machine slow enough, which is exactly why it reaches players and not us.
-//!
-//! Output is Blizzard-derived; pipe it to the scratchpad, never into the repo.
 
 use benilla_formats::{accumulate_wmo_group_camera_collision, accumulate_wmo_group_collision};
 
-/// Faces at least this upward-facing count as a **floor** — the mover's own walkable test
-/// (`GROUND_COS`, ~50° from vertical). A group with collidable faces but none of them walkable is
-/// a wall/ceiling shell you slide down, not something you can stand on.
+/// A face at least this upward-facing is a floor, as the mover's `GROUND_COS` (about 50° from
+/// vertical) judges it.
 const WALKABLE_COS: f32 = 0.64;
 
-/// One gather's shape: how many triangles, and how many of them you could stand on.
 struct Gather {
     tris: usize,
     walkable: usize,
diff --git a/crates/benilla-formats/examples/wmo_coplanar.rs b/crates/benilla-formats/examples/wmo_coplanar.rs
index 0a06920e..8eed3dd7 100644
--- a/crates/benilla-formats/examples/wmo_coplanar.rs
+++ b/crates/benilla-formats/examples/wmo_coplanar.rs
@@ -1,34 +1,23 @@
-//! Which batches of a WMO are **coplanar with each other**, and by how much:
+//! Which batches of a WMO are coplanar, with each other or with themselves: per pair, the smallest
+//! plane gap between near-parallel overlapping faces. A `0.000` gap is a true tie the depth test
+//! cannot decide; anything else is a separation to set against the depth buffer's resolution at
+//! that range. Output is Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example wmo_coplanar -- <wmo-path-or-substring> [gap_yd]`
-//! e.g. `wmo_coplanar orctower 0.05`.
-//!
-//! The falsifier for a z-fighting report. Two surfaces that swap which one is in front do it for one
-//! of two reasons, and they take different fixes: a **true tie** (the author put both faces on the
-//! same plane, so the depth test has nothing to decide with and the winner is whoever drew last) or
-//! **depth precision** (a real but tiny separation that quantises away). The distinction is a
-//! property of the *file*, not of the frame — so read it here rather than inferring it from pixels.
-//!
-//! Prints, for every pair of batches whose geometry overlaps in space, the smallest plane gap between
-//! near-parallel faces that actually overlap. A `0.000` gap is a tie; anything else is a separation
-//! to compare against the depth buffer's resolution at that range.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 use benilla_formats::RenderSubmesh;
 
 /// Faces this close to parallel are treated as the same plane orientation (≈2.6°).
 const PARALLEL_DOT: f32 = 0.999;
 
-/// One triangle reduced to its plane plus the box it occupies — everything the gap test needs.
+/// One triangle as its plane and bounding box.
 struct Face {
     normal: [f32; 3],
     /// Plane offset: `normal · vertex`.
     d: f32,
     min: [f32; 3],
     max: [f32; 3],
-    /// The triangle's own corners, kept so a batch can be compared against **itself**: two faces of
-    /// one flat quad share an edge and are trivially coplanar, which is not a defect. Real overlapping
-    /// sheets share no vertex.
+    /// The corners, so a batch can be compared with itself: two halves of one flat quad share a
+    /// vertex, overlapping sheets do not.
     verts: [[f32; 3]; 3],
 }
 
@@ -76,12 +65,10 @@ fn dot(a: [f32; 3], b: [f32; 3]) -> f32 {
     a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
 }
 
-/// Do the two boxes overlap, allowing `slack` of separation on every axis?
 fn boxes_touch(a: &Face, b: &Face, slack: f32) -> bool {
     (0..3).all(|c| a.min[c] - slack <= b.max[c] && b.min[c] - slack <= a.max[c])
 }
 
-/// Do the triangles share a corner? Two halves of a quad do; two stacked sheets do not.
 fn shares_a_vertex(a: &Face, b: &Face) -> bool {
     a.verts.iter().any(|p| {
         b.verts
@@ -90,9 +77,8 @@ fn shares_a_vertex(a: &Face, b: &Face) -> bool {
     })
 }
 
-/// The smallest plane gap between near-parallel, spatially-overlapping faces of `a` and `b`, or
-/// `None` if no such pair sits within `gap`. When `a` and `b` are the same batch, edge-sharing
-/// neighbours are skipped — they are how a flat surface is built, not a defect.
+/// The smallest plane gap within `gap` between near-parallel overlapping faces of `a` and `b`;
+/// within one batch, faces sharing a vertex are skipped.
 fn closest_coplanar(a: &[Face], b: &[Face], gap: f32, same_batch: bool) -> Option<f32> {
     let mut best: Option<f32> = None;
     for (i, fa) in a.iter().enumerate() {
@@ -122,8 +108,7 @@ fn main() -> anyhow::Result<()> {
     let pat = args
         .next()
         .ok_or_else(|| anyhow::anyhow!("usage: wmo_coplanar <wmo-path-or-substring> [gap_yd]"))?;
-    // Report pairs whose faces sit within this gap. The default is generous — a real z-fight needs a
-    // gap far under a centimetre, but seeing the near misses tells you where the margin actually is.
+    // Pairs within this gap; the default is wide enough to show near misses too.
     let gap: f32 = args.next().map_or(Ok(0.05), |g| g.parse())?;
 
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
diff --git a/crates/benilla-formats/examples/wmo_dark_floors.rs b/crates/benilla-formats/examples/wmo_dark_floors.rs
index 44f6e6b8..a5813ca6 100644
--- a/crates/benilla-formats/examples/wmo_dark_floors.rs
+++ b/crates/benilla-formats/examples/wmo_dark_floors.rs
@@ -1,21 +1,9 @@
-//! **Every WMO in the chain that authors a surface too dark to render on its own** — the world sweep
-//! behind decision 0956's Dire Maul report:
+//! Every WMO surface baked near-black at `MOCV.α = 0` that only the doorway fade
+//! (`FixColorVertexAlpha`) lights: without the fade the TRANS and INT batches render the bake as
+//! is, a black floor. A vertex is dark at luminance < 48 and alpha 0 when the fade lifts it past
+//! 200; a triangle counts when all three are, and batches rank by that area.
+//! Output is Blizzard data: never commit it.
 //! `cargo run --release -p benilla-formats --example wmo_dark_floors [-- <substring>]`
-//!
-//! The bug 0956 fixed was never Dire Maul's: a WMO transition group may bake a surface at near-black
-//! with `MOCV.α = 0`, leaving the runtime bright-doorway fade (`FixColorVertexAlpha`) to light it.
-//! Skip the fade and the interior TRANS/INT law renders the bake literally — a black floor. One
-//! building was *reported*; this asks the question the report could not, which is how many others
-//! were sitting there unreported.
-//!
-//! Severity is **area, not vertex count**. A vertex is *dark* when the file bakes it near-black at
-//! zero alpha (luminance < 48, `α == 0`) and the fade lifts it past 200 — it would have drawn black
-//! and now draws lit. A **triangle** counts when all three of its vertices are, and its model-space
-//! area is summed: that is literally the square yardage of black floor a player would have walked
-//! over (floor, wall or ceiling alike). Batches are reported with their share of their own surface, so a wholly-black walkway
-//! (Dire Maul: 100%) sorts above a darkened seam.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 use benilla_wmo::{parse_wmo, ParsedWmo};
 
@@ -36,9 +24,8 @@ struct Hit {
     batch: usize,
     class: &'static str,
     texture: String,
-    /// Square yards of triangle whose every vertex was dark.
+    /// Square yards of triangles whose every vertex is dark.
     area: f32,
-    /// That area as a share of the batch's own total.
     share: f32,
 }
 
@@ -100,7 +87,7 @@ fn main() -> anyhow::Result<()> {
             if !is_dark.iter().any(|&d| d) {
                 continue;
             }
-            // MOBA is laid out TRANS, INT, EXT — only the first two render the bake.
+            // MOBA runs TRANS, INT, EXT; only the first two render the bake.
             let (trans_n, int_n) = benilla_formats::wmo_group_header(&gbytes)
                 .map(|_| ())
                 .and_then(|()| {
diff --git a/crates/benilla-formats/examples/wmo_doubled.rs b/crates/benilla-formats/examples/wmo_doubled.rs
index 265a0aa1..76253877 100644
--- a/crates/benilla-formats/examples/wmo_doubled.rs
+++ b/crates/benilla-formats/examples/wmo_doubled.rs
@@ -1,46 +1,28 @@
-//! Which faces of a WMO are **authored twice** — two triangles on the same three positions:
+//! Which faces of a WMO are authored twice, two triangles on the same three positions, with each
+//! pair's MOMT flags. Opposite winding is how 1.12 authors cloth seen from both sides on a
+//! single-sided material: the reference culls each copy from its back, so one covers any pixel,
+//! and a renderer that draws the batches two-sided makes the copies z-fight. MOMT `0x04`
+//! (UNCULLED) set means the file asks for two-sided drawing. `wmo_coplanar` cannot see these, as it
+//! skips same-batch faces that share a vertex. Output is Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example wmo_doubled -- <wmo-path-or-substring>`
-//! e.g. `wmo_doubled orctower`.
-//!
-//! The falsifier `wmo_coplanar` structurally cannot be. That tool skips same-batch face pairs that
-//! share a vertex ("two halves of a quad") — but a thin sheet whose two *sides* are authored by
-//! reusing the same vertices with **reversed winding** shares all three, so a doubled canvas awning
-//! is invisible to it by construction (it reported the B38 tent's nearest partner at 1.91 yd while
-//! the tent's own two sides sat at 0.000). This tool asks the opposite question: which triangles
-//! occupy the SAME three positions?
-//!
-//! Doubled-with-opposite-winding is not a defect — it is how 1.12 authors visible-from-both-sides
-//! cloth when the material is single-sided: the real client backface-culls each copy from the wrong
-//! side, so exactly one covers any pixel. It *becomes* a defect the moment the renderer draws WMO
-//! batches two-sided — ours did until `3af8854f` honoured MOMT `0x04` (B38, decision 0680): both
-//! copies then rasterize at depths equal to the ulp, and the winner per pixel is floating-point
-//! noise — latched while the camera is bit-still, flickering while anything creeps. That is the
-//! defect this tool was built to name, and it is now closed; it stays as the census. Each pair
-//! prints with its
-//! batches' MOMT flags: `0x04` (UNCULLED) set means the file *asked* for two-sided and the double
-//! draw is authored intent; clear means the renderer's shortcut is manufacturing a z-tie the file
-//! never contained.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 use std::collections::HashMap;
 
 use benilla_wmo::{parse_wmo, ParsedWmo};
 
-/// Positions are matched to a tenth of a millimetre — far under authoring precision, far over f32
-/// noise at building scale.
+/// Positions match to a tenth of a millimetre, under authoring precision and over f32 noise.
 const QUANT: f32 = 10_000.0;
 
 fn key(p: [f32; 3]) -> [i64; 3] {
     p.map(|c| (c * QUANT).round() as i64)
 }
 
-/// A triangle's identity (order-free) plus the data needed to classify its partner.
+/// A triangle's batch and facing, to classify its partner.
 struct Tri {
     batch: usize,
-    /// Geometric normal in original winding order — two copies with `dot < 0` are opposite-wound.
+    /// Geometric normal in authored winding; two copies with `dot < 0` are opposite-wound.
     normal: [f32; 3],
-    /// Mean authored (MONR) normal, to name which side of the sheet this copy is.
+    /// Summed authored (MONR) normals, naming which side of the sheet this copy is.
     authored: [f32; 3],
 }
 
@@ -66,8 +48,7 @@ fn main() -> anyhow::Result<()> {
     };
     println!("{path}\n");
 
-    // The root's MOMT table, raw — the submeshes don't carry material flags, and the flags decide
-    // whether a doubled pair is authored intent (0x04 UNCULLED) or a renderer-manufactured tie.
+    // The root's raw MOMT table: the submeshes carry no material flags.
     let root_bytes = chain.read_file(&path.to_ascii_lowercase())?;
     let (materials, textures, tex_map) = match parse_wmo(&mut std::io::Cursor::new(&root_bytes))? {
         ParsedWmo::Root(r) => (r.materials, r.textures, r.texture_offset_index_map),
@@ -89,8 +70,7 @@ fn main() -> anyhow::Result<()> {
 
     let subs = benilla_formats::load_wmo(&mut chain, &path)?;
 
-    // One global bucket per geometric triangle, across every batch: any bucket holding two entries
-    // is a doubled face, wherever its copies live.
+    // One bucket per geometric triangle across every batch; two entries make a doubled face.
     let mut buckets: HashMap<[[i64; 3]; 3], Vec<Tri>> = HashMap::new();
     for (bi, s) in subs.iter().enumerate() {
         for t in s.indices.as_chunks::<3>().0 {
@@ -117,9 +97,8 @@ fn main() -> anyhow::Result<()> {
         }
     }
 
-    // Doubled-face census per batch pair, split by winding — opposite is the two-sided-sheet
-    // authoring; same-winding true duplicates would be a different (and stranger) finding.
-    /// Per batch pair: doubled-face count + each side's summed authored normal.
+    // Per batch pair, split by winding: opposite is a two-sided sheet, same is a true duplicate.
+    /// Per batch pair: the doubled-face count and each side's summed authored normal.
     type OppositeCensus = HashMap<(usize, usize), (usize, [f32; 3], [f32; 3])>;
     let mut opposite: OppositeCensus = HashMap::new();
     let mut same: HashMap<(usize, usize), usize> = HashMap::new();
@@ -131,8 +110,7 @@ fn main() -> anyhow::Result<()> {
                 if dot(a.normal, b.normal) < 0.0 {
                     let e = opposite.entry(pair).or_insert((0, [0.0; 3], [0.0; 3]));
                     e.0 += 1;
-                    // Accumulate each side's authored normal by batch order, so the report can say
-                    // "batch A faces up, batch B faces down" rather than just "they differ".
+                    // Each side's authored normal in batch order, to say which way each faces.
                     let (first, second) = if a.batch <= b.batch { (a, b) } else { (b, a) };
                     for c in 0..3 {
                         e.1[c] += first.authored[c];
diff --git a/crates/benilla-formats/examples/wmo_liquid_arms.rs b/crates/benilla-formats/examples/wmo_liquid_arms.rs
index 31d1bd95..f89ad538 100644
--- a/crates/benilla-formats/examples/wmo_liquid_arms.rs
+++ b/crates/benilla-formats/examples/wmo_liquid_arms.rs
@@ -1,38 +1,18 @@
-//! **Which WMO water ARM each pool takes**, over the whole shipped corpus:
-//! `cargo run -p benilla-formats --example wmo_liquid_arms`.
-//!
-//! The reference does not have *one* WMO water renderer. `0x6b62e0` dispatches the type nibble to a
-//! category, and category 0 (river/water — nibbles 0/4/8) then splits again on the owning group's
-//! `MOGP.flags & 0x48`:
-//!
-//! * `& 0x48 != 0` → **EXTERIOR**, kernel `0x6b6630`. A 9-float (`0x24`) vertex — position, an up
-//!   normal, a colour dword, `u,v` — and the kernel binds the pixel program
-//!   `Shaders\Pixel\MapObjExtWater0.bls` at `0x6b6654` (`GxRsSet(0x3f, …)`, gated on `[0xc9607c]`).
-//! * `& 0x48 == 0` → **INTERIOR**, kernel `0x6b6420`. A 6-float (`0x18`) vertex — position, a colour
-//!   dword, `u,v` — with **no normal at all**, the colour coming from the map object's own light
-//!   records (`CMapObj+0x1d8`).
-//!
-//! The arm split is **category 0 only**. Magma and slime (nibbles 2/3/6/7) go to category 1 and one
-//! shared kernel `0x6b68f0` whatever their group's flags say, so their rows below are context, not
-//! two arms — they are reported because the same building often holds both, and because a reader
-//! comparing group counts would otherwise assume the split is universal.
-//!
-//! Neither water arm is the **ADT** path (`0x6851b0`/`0x685010` → `ocean0_s.bls`), which is the only
-//! one with a depth-ramp texture on stage 0 and the only one whose vertex carries no colour.
-//!
-//! benilla renders all three through one material and one shader — the ADT one. This census says how
-//! much content each arm actually owns, so the divergence can be sized instead of guessed: the two
-//! reported sites (B136 Blackfathom Deeps, and Stormwind's canals) land on opposite arms, and
-//! neither is the path we implement.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! Which WMO water arm each shipped liquid group takes. The reference's dispatch `0x6b62e0` splits
+//! water (nibbles 0/4/8) on the owning group's `MOGP.flags & 0x48`: set runs the exterior kernel
+//! `0x6b6630`, a 9-float vertex with an up normal, binding `MapObjExtWater0.bls` at `0x6b6654`;
+//! clear runs the interior kernel `0x6b6420`, a 6-float vertex with no normal, coloured from the
+//! map object's lights (`CMapObj+0x1d8`). Magma and slime (nibbles 2/3/6/7) take `0x6b68f0`
+//! whatever the flags, and neither arm is the ADT path (`0x6851b0`, `0x685010`, `ocean0_s.bls`).
+//! Output is Blizzard data: never commit it.
+//! `cargo run -p benilla-formats --example wmo_liquid_arms`
 
 use std::collections::BTreeMap;
 
 use benilla_formats::{wmo_group_header, wmo_group_liquid_mesh, Chain};
 
-/// MOGP `flags & 0x48` — the reference's interior test (`0x6b3f90`, and the liquid dispatch's own
-/// `[owner+0x10] & 0x48` at `0x6b62e0`). Zero ⇒ interior.
+/// The reference's interior test, zero meaning interior (`0x6b3f90`; the liquid dispatch
+/// `0x6b62e0` tests `[owner+0x10] & 0x48`).
 const EXTERIOR_MASK: u32 = 0x48;
 
 #[derive(Default, Clone, Copy)]
@@ -46,11 +26,8 @@ fn main() -> anyhow::Result<()> {
         .ok_or_else(|| anyhow::anyhow!("no 1.12.1 install found (set $WOW_DATA)"))?;
     let reader = Chain::open(&data)?;
 
-    // Group files are `<root stem>_NNN.wmo`; the roots are what the chain lists, so walk the listing
-    // once and keep the group files directly — a root's group count is not knowable without parsing
-    // it, and the names are self-describing.
     let mut by_arm: BTreeMap<(bool, String), Tally> = BTreeMap::new();
-    // Per building, so a site can be looked up rather than re-derived.
+    // Per building: (interior, exterior) water groups.
     let mut buildings: BTreeMap<String, (u32, u32)> = BTreeMap::new();
 
     for entry in reader.list()? {
@@ -125,7 +102,7 @@ fn main() -> anyhow::Result<()> {
             }
         );
         if !water {
-            continue; // the totals below are the WATER arms; fullbright takes neither
+            continue; // the totals below are the water arms; fullbright takes neither
         }
         if *interior {
             int_g += t.groups;
@@ -139,9 +116,7 @@ fn main() -> anyhow::Result<()> {
         "\nWATER arms — INTERIOR {int_g} groups / {int_t} wet tiles   EXTERIOR {ext_g} groups / {ext_t} wet tiles"
     );
 
-    // Buildings carrying WATER on both arms: a single-shader renderer cannot be right for the whole
-    // building. (Undercity holds both flags too, but its liquid is slime, which takes neither arm —
-    // hence the water-only filter.)
+    // Buildings with water on both arms; Undercity's liquid is slime, which takes neither.
     let mixed: Vec<_> = buildings
         .iter()
         .filter(|(_, (i, e))| *i > 0 && *e > 0)
diff --git a/crates/benilla-formats/examples/wmo_liquid_scope.rs b/crates/benilla-formats/examples/wmo_liquid_scope.rs
index 153a9dee..f2544594 100644
--- a/crates/benilla-formats/examples/wmo_liquid_scope.rs
+++ b/crates/benilla-formats/examples/wmo_liquid_scope.rs
@@ -1,53 +1,34 @@
-//! Where liquid **scoping** can still get the wrong answer, read off the shipped files rather than
-//! argued: `cargo run -p benilla-formats --example wmo_liquid_scope`.
+//! Where WMO liquid scoping can claim the wrong position, read off every placed WMO (from an ADT
+//! or a WDT), each hit with a `.go`. `cargo run -p benilla-formats --example wmo_liquid_scope`
 //!
-//! The "swim in air" family (0634 → 0635 → 0696 → 0701) is one defect met at successively finer
-//! grain: a liquid footprint has no bound of its own, so each round found a wider set of positions
-//! it was still claiming. This is the falsifier that says which bounds are actually load-bearing on
-//! shipped content, and where — an argument about WMO liquid is otherwise unfalsifiable from inside
-//! the game, where you can only stand in one room at a time.
+//! - STOREY: a pool's wet cells over another group's floor, submerged by placement scoping alone.
+//! - OVERHANG: how far wet cells reach past their own group's XY box, up to 25 yd, which is why
+//!   benilla bounds a pool by that box's Z floor only where the reference tests the whole box
+//!   (`0x6a4e00`).
+//! - DRY-GROUP: a group with a `groupLiquid` other than `0xf` and no MLIQ, which the reference
+//!   answers with an unconditional hit at height `FLT_MAX` (`0x6b9f10`).
 //!
-//! * **STOREY** — a placement holding a pool in one group and a **floor below it** in another.
-//!   Placement scoping alone claims the lower room (submerged on dry stone, the B60 shape). This is
-//!   what found decision 0701's Undercity site, and it now also reports whether 0701's floor rule
-//!   closes each hit. Tested against the pool's real **wet cells**, not its bounding box: a liquid
-//!   grid is sparse, so a bbox routinely spans dry ground it never touches (decision 0635).
-//! * **OVERHANG** — how far a pool's wet cells reach *outside* their own group's box. This is why
-//!   0701 bounds a pool by its group's Z **floor** and not by the reference's whole per-group AABB:
-//!   on shipped content a pool overhangs its own room by up to 25 yd in XY, so an XY box test would
-//!   newly reject pools that work today.
-//! * **DRY-GROUP** — a group whose MOGP `groupLiquid` (@0x34) is not the `0xf` no-liquid sentinel
-//!   but that carries **no MLIQ chunk**. The reference's `0x6b9f10` is reported to answer such a
-//!   group with an unconditional hit at height `FLT_MAX`; we answer *nothing*, and since 0634/0696
-//!   suppress the ADT leg indoors, the room reads DRY. **Still open** — three placed groups.
-//!
-//! Only placements found in a shipped ADT are reported — an unplaced WMO cannot be stood in — and
-//! each hit prints a `.go` for the lower room's floor so it can be looked at.
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! Output is Blizzard data: never commit it.
 
 use std::collections::BTreeMap;
 use std::io::Cursor;
 
 use benilla_formats::LiquidMesh;
 
-/// MOGP `groupLiquid` @ 0x34: the value meaning "this group holds no liquid".
+/// MOGP `groupLiquid` (`+0x34`) for a group holding no liquid.
 const NO_LIQUID: u32 = 0xf;
 
-/// Half the 34133⅓-yard map (32 tiles × 533⅓) — the MODF→world origin shift.
+/// Half the 34133⅓-yard map (32 tiles × 533⅓), the MODF-to-world origin shift.
 const MAP_CENTER: f32 = 17066.666;
 
-/// What one group file says about liquid.
 struct Group {
     liquid_type: u32,
-    /// The group's MLIQ surface in WMO model space, if it has one.
     liquid: Option<LiquidMesh>,
-    /// MOGP bounding box (model space), @0x0c.
+    /// MOGP bounding box in model space, at `+0x0c`.
     lo: [f32; 3],
     hi: [f32; 3],
 }
 
-/// One placement of a model in the world.
 struct Site {
     map: String,
     /// Placement origin in WoW world coords.
@@ -93,16 +74,14 @@ fn read_group(bytes: &[u8]) -> Option<Group> {
     })
 }
 
-/// Does this group file carry an MLIQ sub-chunk at all? (The MOGP payload is a 68-byte header
-/// followed by its own sub-chunks.) Distinct from [`Group::liquid`], which is `None` for an
-/// all-holes grid too.
+/// Whether the group carries an MLIQ sub-chunk after MOGP's 68-byte header; [`Group::liquid`] is
+/// also `None` for an all-holes grid.
 fn has_mliq(bytes: &[u8]) -> bool {
     chunk(bytes, b"PGOM").is_some_and(|m| m.len() > 0x44 && chunk(&m[0x44..], b"QILM").is_some())
 }
 
-/// The model→world rotation for a MODF placement, in the **WoW** frame (Z up) — the `in_wow` half
-/// of `benilla_assets::coords::placement_rotation`, as a plain 3×3 so this example needs no math
-/// dependency. `Rx(90°)·Ry(ry−180°)·Rz(−rx)·Rx(rz−90°)`, applied to a model-space point.
+/// A MODF placement's model-to-world rotation in the WoW frame (Z up), the `in_wow` half of
+/// `benilla_assets::coords::placement_rotation`: `Rx(90°)·Ry(ry-180°)·Rz(-rx)·Rx(rz-90°)`.
 fn model_to_world(rot_deg: [f32; 3], p: [f32; 3]) -> [f32; 3] {
     let (rx, ry, rz) = (
         rot_deg[0].to_radians(),
@@ -214,11 +193,7 @@ fn main() -> anyhow::Result<()> {
             }
         }
     }
-    // A WMO-only map has no ADT at all — the whole world is the WDT's single `MODF` (20 of the 43
-    // shipped maps, decision 0688). Scanning only ADTs therefore declared the Deeprun Tram, the
-    // jails and every instance-shaped dungeon *unplaced*, which is the one thing this census uses
-    // to decide a group is unreachable. The tram's own flooded sections are named by the RE note
-    // that commissioned this check, so the blind spot was hiding exactly the sites asked about.
+    // A WMO-only map has no ADT: its world is the WDT's single `MODF` (20 of the 43 shipped maps).
     let wdts: Vec<String> = chain
         .list()?
         .into_iter()
@@ -239,9 +214,8 @@ fn main() -> anyhow::Result<()> {
         let Some(g) = wdt.global_wmo() else { continue };
         let lower = name.to_lowercase();
         let map = lower.split(['\\', '/']).nth(2).unwrap_or("?").to_string();
-        // No `MAP_CENTER − v` remap here: a global WMO's MODF is authored in world coords already
-        // (0688, falsified against all 26 of the server's entry points). Every shipped one is
-        // (0,0,0), so a `.go` printed for one of these is the model-space offset itself.
+        // No `MAP_CENTER - v` remap: a global WMO's MODF is in world coords already, and every
+        // shipped one sits at (0,0,0).
         placed
             .entry(g.model.to_lowercase().replace('/', "\\"))
             .or_default()
@@ -259,8 +233,7 @@ fn main() -> anyhow::Result<()> {
     let mut storey: Vec<(f32, String)> = Vec::new();
     let mut overhang: Vec<(f32, String)> = Vec::new();
     let mut floor_misses = 0usize;
-    // groupLiquid value -> (groups with an MLIQ chunk, groups without) — the sentinel sanity check:
-    // `0xf` is only the "no liquid" marker if it is what the overwhelming majority of dry groups say.
+    // groupLiquid value -> (groups with an MLIQ chunk, groups without).
     let mut type_census: BTreeMap<u32, (usize, usize)> = BTreeMap::new();
 
     for (model, sites) in &placed {
@@ -277,9 +250,7 @@ fn main() -> anyhow::Result<()> {
             } else {
                 e.1 += 1;
                 if g.liquid_type != NO_LIQUID {
-                    // The ROOM, not the building origin: a placement origin routinely sits
-                    // inside rock, so a `.go` to it is unusable for an eyeball check. Aim at the
-                    // group box's own centre, just off its floor.
+                    // Aim at the room's box centre, just off its floor, not the placement origin.
                     let mid = |a: usize| (g.lo[a] + g.hi[a]) * 0.5;
                     dry_groups.push(format!(
                         "  {model} group {gi:03} liquidType {}  box z [{:.1}..{:.1}]\n      room  {}\n      origin{}",
@@ -294,7 +265,7 @@ fn main() -> anyhow::Result<()> {
             groups.push(g);
         }
 
-        // STOREY: for each pool, the lower groups its WET CELLS actually hang over.
+        // STOREY: for each pool, the lower groups its wet cells hang over.
         for (ai, a) in groups.iter().enumerate() {
             let Some(lq) = a.liquid.as_ref() else {
                 continue;
@@ -314,27 +285,23 @@ fn main() -> anyhow::Result<()> {
                 if ai == bi {
                     continue;
                 }
-                // The claim only fires where the query would: a point in B under the pool's height
-                // and inside a wet cell's XY. Take B's own floor as the standing surface.
+                // Where the query fires: under the pool's height, in a wet cell, on B's floor.
                 let stand = b.lo[2] + 1.5;
                 let mut best: Option<([f32; 4], f32)> = None;
                 for (xy, h) in &cells {
                     if *h <= stand {
-                        continue; // the pool is at or below this floor — no false submersion
+                        continue; // the pool is at or below this floor: no false submersion
                     }
                     let overlap =
                         xy[0] < b.hi[0] && xy[2] > b.lo[0] && xy[1] < b.hi[1] && xy[3] > b.lo[1];
-                    // …and B must not simply BE the pool's own room: skip when B's box contains the
-                    // liquid height, i.e. the pool is inside B and the submersion is real.
+                    // Skip B when its box holds the liquid height: that submersion is real.
                     if overlap && *h > b.hi[2] && best.is_none_or(|(_, bh)| *h > bh) {
                         best = Some((*xy, *h));
                     }
                 }
                 if let Some((xy, h)) = best {
                     let pt = [(xy[0] + xy[2]) * 0.5, (xy[1] + xy[3]) * 0.5, stand];
-                    // Would a FLOOR under the pool — "a pool cannot claim anything below its own
-                    // group's box" — close this one? The candidate fix, checked per hit rather
-                    // than assumed to generalize from the site that motivated it.
+                    // Whether the floor rule (nothing below the pool's group box) closes this.
                     let floored = stand < a.lo[2];
                     if !floored {
                         floor_misses += 1;
@@ -368,12 +335,8 @@ fn main() -> anyhow::Result<()> {
         println!("  {d:>7.2} yd  {line}");
     }
 
-    // ---- the ARCHIVE-WIDE census. -----------------------------------------------------------
-    // The placed-model census below answers "what does shipped, reachable content use". This one
-    // answers the prior question: is `groupLiquid` a field the 1.12 authors USED at all? If every
-    // MLIQ-carrying group in the whole archive says `0xf`, then the type-override branch never
-    // fires on real data and a stray non-`0xf` value on a group with no liquid is content noise,
-    // not a feature we are failing to implement.
+    // ---- the archive-wide census. -----------------------------------------------------------
+    // `groupLiquid` over every group file in the archive, placed or not.
     let mut all_census: BTreeMap<u32, (usize, usize)> = BTreeMap::new();
     let mut odd: Vec<String> = Vec::new();
     for name in chain.list()?.into_iter().map(|e| e.name) {
diff --git a/crates/benilla-formats/examples/wmo_mocv.rs b/crates/benilla-formats/examples/wmo_mocv.rs
index 079b168f..4a3567d4 100644
--- a/crates/benilla-formats/examples/wmo_mocv.rs
+++ b/crates/benilla-formats/examples/wmo_mocv.rs
@@ -1,27 +1,14 @@
-//! What a WMO's surfaces are **baked** to — the per-group MOCV census behind a "this floor is black"
-//! report:
+//! Each WMO group's MOCV bake per batch, up-facing vertices apart from the rest, with its MOGP
+//! flags, batch class and the bake after the doorway fade. The reference lights an interior surface
+//! only from the bake: an INT batch draws `tex × MOCV` and a TRANS batch lerps to it by `MOCV.a`,
+//! and `FixColorVertexAlpha` (`0x6c43d0`) brightens interior vertices toward white within 6.67 yd
+//! of a portal to an exterior group. A model-space `x,y,z` keeps only the groups whose box holds
+//! it; `--survey` prints only the fade per group. Output is Blizzard data: never commit it.
 //! `cargo run -p benilla-formats --example wmo_mocv -- <wmo-path-or-substring> [gN | x,y,z]`
-//!
-//! An interior WMO surface takes no exterior light in the reference: an INT-class batch draws
-//! `tex × MOCV` and a TRANS-class batch lerps to it by `MOCV.a`, so the *only* thing between a black
-//! floor and a lit one is the bake in the file — plus the runtime portal fixup the client applies
-//! over it (`FixColorVertexAlpha`, wow-re `wmo-group-lighting.md §4`, which brightens interior verts
-//! toward white within 6.67 yd of an exterior-neighbour portal). A "dark floor here" report therefore
-//! has exactly two shapes, told apart by numbers rather than by looking: either the file bakes it
-//! dark (and the fixup is what lights it), or our reader/classifier mislabels the batch. This prints
-//! both halves — the group's MOGP flags and per-batch class, and the MOCV spread of each batch's
-//! vertices split by facing, so a FLOOR (n.z up) reads apart from the walls sharing its batch.
-//!
-//! With a model-space `x,y,z` it reports only the groups whose bounding box contains the point (a
-//! `.gps` pin, inverse-transformed by the placement, names the group the director is standing in).
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
 
 use benilla_wmo::{parse_wmo, ParsedWmo};
 
-/// Walk a WMO file's top-level chunks for `magic` (FourCC reversed on disk), returning its payload.
-/// The examples can't use the crate-private reader, and a group file's MOGP header is the only thing
-/// here that isn't already on a parsed struct.
+/// The payload of a WMO file's top-level chunk `magic`, FourCC reversed as on disk.
 fn chunk<'a>(bytes: &'a [u8], magic: &[u8; 4]) -> Option<&'a [u8]> {
     let mut off = 0usize;
     while off + 8 <= bytes.len() {
@@ -93,11 +80,7 @@ fn main() -> anyhow::Result<()> {
     let filter = args.next();
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = benilla_formats::open_chain(&data)?;
-    // A `.wmo` argument is taken as a literal chain path, but only if the chain HAS it: `stormwind.wmo`
-    // ends in `.wmo` and is not a path, and the old "ends_with ⇒ literal" rule turned that into a hard
-    // read error. Read as "no groups affected" from a grepped log, it cost a wrong all-clear on
-    // Stormwind, Ironforge and Stratholme. Falling back to the substring search cannot mislead: the
-    // resolved path is printed, and a genuine miss still errors.
+    // A `.wmo` argument is a literal path only if the chain has it; `stormwind.wmo` is a substring.
     let lower = pat.to_lowercase();
     let path = if lower.ends_with(".wmo") && chain.read_file(&lower).is_ok() {
         pat.clone()
@@ -205,8 +188,7 @@ fn main() -> anyhow::Result<()> {
             if has_colors { "yes" } else { "ABSENT" },
             group.render_batches.len(),
         );
-        // The fade's blast radius on this group: how many authored slots it rewrites, and by how much
-        // — the number that says whether the doorway fixup is a targeted lift or a wash over the room.
+        // How many authored slots the doorway fade rewrites on this group, and by how much.
         if let Some(fixed) = benilla_formats::wmo_group_fixed_colors(&gbytes, &wmo_root) {
             let lum = |c: [f32; 3]| 0.299 * c[0] + 0.587 * c[1] + 0.114 * c[2];
             let (mut changed, mut before, mut after) = (0usize, 0.0f32, 0.0f32);
@@ -251,7 +233,7 @@ fn main() -> anyhow::Result<()> {
                 .vertex_indices
                 .get(start..start + batch.count as usize)
                 .unwrap_or(&[]);
-            // Split by facing: a floor's up-facing verts are what a "dark floor" report is about.
+            // Split by facing, so a floor's up-facing verts read apart from its walls.
             let (mut up, mut other) = (Stat::new(), Stat::new());
             for &i in idx {
                 let i = i as usize;
@@ -274,10 +256,8 @@ fn main() -> anyhow::Result<()> {
             println!("        up-facing {}", up.line());
             println!("        other     {}", other.line());
         }
-        // The same census *after* the reader's bright-doorway fade — what the renderer actually
-        // uploads. A batch that reads black above and white here is a floor the file never baked and
-        // the runtime fixup lights (a WMO transition corridor); one that stays black in both is a
-        // genuinely dark room.
+        // The same census after the reader's doorway fade, as the renderer uploads it: black above
+        // and white here is a surface only the fade lights.
         let subs = benilla_formats::wmo_group_submeshes(&gbytes, &wmo_root)?;
         println!(
             "  --- after FixColorVertexAlpha ({} submeshes) ---",
diff --git a/crates/benilla-formats/examples/wmo_ownerless_pools.rs b/crates/benilla-formats/examples/wmo_ownerless_pools.rs
index 92daac53..3e470ea7 100644
--- a/crates/benilla-formats/examples/wmo_ownerless_pools.rs
+++ b/crates/benilla-formats/examples/wmo_ownerless_pools.rs
@@ -1,49 +1,14 @@
-//! **Which buildings' embedded pools have no visibility authority**, over the whole shipped corpus:
-//! `cargo run -p benilla-formats --example wmo_ownerless_pools`.
+//! Which WMO roots have embedded pools but no `WmoPortalInstance` to own them. A placement gets an
+//! instance only with a portal graph or an authored `WMOAreaTable` identity, the spawn site's
+//! `has_portals || m.wmo_id != 0` (`terrain_stream::spawn`), and a pool's `WmoGroupVis`/`WmoRoom`
+//! scope is keyed to it. No shipped root is both portal-less and unnamed: the only `wmoID == 0`
+//! root, `pvp_alterac_ent01.wmo`, has portals.
+//! `cargo run -p benilla-formats --example wmo_ownerless_pools`
 //!
-//! A placed WMO gets a `WmoPortalInstance` only when it has a portal graph **or** an authored
-//! `WMOAreaTable` identity — `has_portals || m.wmo_id != 0`, the spawn site in
-//! `benilla-world/src/terrain_stream/spawn/mod.rs`. Everything about a building's *rooms* hangs off
-//! that instance: it is the per-placement entity the group-visible set lives on, and it is what a
-//! pool's `WmoGroupVis`/`WmoRoom` scope is keyed to.
-//!
-//! So a root that has **neither** portals **nor** a wmoID is instance-less — and until decision 1652
-//! that meant its embedded MLIQ pools were tagged with *neither* `WmoGroupVis` nor `ExteriorScene`,
-//! i.e. no system ever wrote their `Visibility` at all, while the same placement's walls were
-//! tagged `ExteriorScene` unconditionally and window-culled normally. A sealed well room drawing a
-//! disc of water in mid-air is what that *would* look like from outside.
-//!
-//! Whether any shipped root actually falls in that cell is the question — an unreachable branch and
-//! a widespread defect are the same code, and only the corpus tells them apart.
-//!
-//! **The answer is zero** (run 2026-08-27, decision 1652): of 815 roots, 448 carry no portal graph
-//! and exactly **one** carries `wmoID == 0` — `pvp_alterac_ent01.wmo` — and that one *does* have
-//! portals. The two conditions never coincide in shipped data, so the instance-less branch is dead
-//! and 1652's unconditional tag on pools closes a hole no building reaches. That is worth a census
-//! rather than a guess in either direction: it is the difference between a fix that earns a sighting
-//! and one that must never be credited with one.
-//!
-//! Two facts per root, both read from the bytes the runtime reads:
-//!
-//! * **instance** — `MOPT` and `MOPR` both non-empty (`benilla_assets::WmoModel::portal_infos` /
-//!   `portal_refs`), or `MOHD.wmoID @0x20 != 0` ([`benilla_formats::wmo_root_id`], the
-//!   `WMOAreaTable.WMOID` key).
-//! * **liquid** — any group file for which [`benilla_formats::wmo_group_liquid_mesh`] yields a
-//!   surface. That is the *same* call `WmoModel::group_liquids` makes, so a root counted wet here is
-//!   exactly a root that spawns pool entities at placement. (`resolve_shared_liquid_cells` can drop
-//!   one group's mesh afterwards, but only in favour of a sibling group of the same root, so it
-//!   cannot change a root's wet/dry verdict.) A group whose MOGP `groupLiquid` @`0x34` declares
-//!   whole-group submersion but carries no `MLIQ` grid (13 in the archive, decision 1000) is **not**
-//!   counted: it spawns no pool entity, so there is nothing for an instance to own. The liquid-group
-//!   total cross-checks against `wmo_liquid_arms`, which reaches the same groups from the other side
-//!   — the listfile's `_NNN` group files rather than `MOHD.nGroups` per root.
-//!
-//! Roots are also split by whether the world actually **places** them — an unplaced WMO can never be
-//! stood next to, so it cannot show the defect. Placements come from every ADT's `MODF` plus the
-//! WDT global-WMO of the 20 WMO-only maps (decision 0688 — scanning only ADTs would call the Deeprun
-//! Tram and every instance-shaped dungeon unplaced).
-//!
-//! Output is Blizzard data — pipe it to the scratchpad, never into the repo.
+//! A root has liquid when [`benilla_formats::wmo_group_liquid_mesh`] yields a surface for any of
+//! its groups, the call `WmoModel::group_liquids` makes; a group flooded by `groupLiquid` alone
+//! spawns no pool and is not counted. Placements come from every ADT's `MODF` and each WMO-only
+//! map's WDT global WMO. Output is Blizzard data: never commit it.
 
 use std::collections::{BTreeMap, BTreeSet};
 use std::io::Cursor;
@@ -54,38 +19,35 @@ use benilla_formats::{
 
 /// What one root says about the two axes.
 struct Root {
-    /// `MOHD.wmoID @0x20` — the `WMOAreaTable.WMOID` key; `0` ⇒ the building has no authored identity.
+    /// `MOHD.wmoID` (`+0x20`), the `WMOAreaTable.WMOID` key; 0 means no authored identity.
     wmo_id: u32,
-    /// `MOPT` ∧ `MOPR` both non-empty — the spawn site's `has_portals`.
+    /// `MOPT` and `MOPR` both non-empty, the spawn site's `has_portals`.
     has_portals: bool,
     /// Group files the root declares (`MOHD.nGroups`).
     groups: u32,
     /// Groups whose MLIQ resolves to a liquid surface.
     liquid_groups: u32,
-    /// Wet cells across those surfaces — the size of what draws.
     wet_tiles: u32,
-    /// Maps the root is placed on (empty ⇒ never placed).
+    /// Maps the root is placed on; empty if never placed.
     maps: BTreeSet<String>,
 }
 
 impl Root {
-    /// The spawn site's test, verbatim: no instance ⇒ nothing owns this building's rooms.
+    /// The spawn site's test: without an instance nothing owns the building's rooms.
     fn has_instance(&self) -> bool {
         self.has_portals || self.wmo_id != 0
     }
 }
 
-/// Normalize a chain path the way the MPQ hash compares them, so ADT `MWMO` names and listfile
-/// names land on the same key.
+/// A chain path normalised as the MPQ hash compares it, so ADT `MWMO` and listfile names agree.
 fn key(name: &str) -> String {
     name.replace('/', "\\").to_ascii_lowercase()
 }
 
-/// Every WMO root the world actually places, mapped to the maps it appears on: ADT `MODF` first,
-/// then the WDT global-WMO that IS the world on a WMO-only map (decision 0688).
+/// Every placed WMO root and the maps it is on: ADT `MODF`s, then each WMO-only map's WDT global.
 fn placed_roots(chain: &Chain) -> anyhow::Result<BTreeMap<String, BTreeSet<String>>> {
     let mut placed: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
-    // `World\Maps\<map>\<map>_XX_YY.adt` — the map name is the third path component.
+    // `World\Maps\<map>\<map>_XX_YY.adt`: the map name is the third path component.
     let map_of = |name: &str| key(name).split('\\').nth(2).unwrap_or("?").to_string();
 
     let names: Vec<String> = chain.list()?.into_iter().map(|e| e.name).collect();
@@ -137,13 +99,8 @@ fn main() -> anyhow::Result<()> {
     let placed = placed_roots(&chain)?;
     eprintln!("{} distinct WMO roots placed in the world", placed.len());
 
-    // A group file's stem ends `_NNN`; a root's does not. The chain lists both.
-    //
-    // The listfile is NOT a complete index (`Chain::list`'s own doc: a file absent from every
-    // archive's listfile is readable by name but not enumerated), so the scanned set is the UNION of
-    // the listed roots and every root an ADT/WDT actually references. A placed-but-unlisted root is
-    // exactly the one this census must not miss, and the two counts printed below say whether the
-    // union ever added anything.
+    // Roots are the listed `.wmo` files whose stem lacks `_NNN`, plus every placed root the
+    // listfile misses: a file absent from every listfile is readable but not enumerated.
     let listed: BTreeSet<String> = chain
         .list()?
         .into_iter()
@@ -177,8 +134,7 @@ fn main() -> anyhow::Result<()> {
         let Ok(bytes) = chain.read(k) else {
             continue;
         };
-        // `parse_wmo_root` is the group-count authority (`MOHD.nGroups`); a file that fails it is
-        // not a root and has no rooms to own.
+        // `parse_wmo_root` gives the group count (`MOHD.nGroups`); a file it rejects has no rooms.
         let Ok(root) = parse_wmo_root(&bytes) else {
             continue;
         };
@@ -243,9 +199,7 @@ fn main() -> anyhow::Result<()> {
         .count();
     let liquid_groups: u32 = census.values().map(|r| r.liquid_groups).sum();
 
-    // The two axes on their own. The cross-tab cannot say WHICH half of `has_portals || wmo_id != 0`
-    // carries a root, and "no root is instance-less" is a claim that has to be falsifiable from the
-    // same run rather than taken on the strength of one collapsed cell.
+    // Each axis alone: the cross-tab cannot say which half of `has_portals || wmo_id != 0` holds.
     let portal_less = census.values().filter(|r| !r.has_portals).count();
     let unnamed = census.values().filter(|r| r.wmo_id == 0).count();
     println!(
@@ -258,9 +212,7 @@ fn main() -> anyhow::Result<()> {
 {liquid_groups} liquid groups in all"
     );
 
-    // Every root on the rarer axis, named: `wmoID == 0` is what makes the instance depend on the
-    // portal graph at all, so the handful that have it are the whole falsifiable surface of the
-    // cross-tab's empty cell.
+    // Every `wmoID == 0` root by name: only these depend on their portal graph for an instance.
     println!("\nroots with wmoID 0:");
     for (path, r) in census.iter().filter(|(_, r)| r.wmo_id == 0) {
         println!(
diff --git a/crates/benilla-formats/src/anim_data.rs b/crates/benilla-formats/src/anim_data.rs
index a89ce009..1f0dcdde 100644
--- a/crates/benilla-formats/src/anim_data.rs
+++ b/crates/benilla-formats/src/anim_data.rs
@@ -1,32 +1,9 @@
-//! `AnimationData.dbc` — the per-animation policy row behind the sheath reconcile (decision 0080)
-//! and, later, missing-clip fallback resolution.
-//!
-//! Layout — VERIFIED against build 5875 (header + full 208-row decode with name joins,
-//! 2026-07-03): **208 × 7 × 28 B**: `ID(0), Name(str, 1), WeaponFlags(2), BodyFlags(3), _col4(4),
-//! _col5(5), Fallback(6)`.
-//!
-//! - **WeaponFlags (col 2)** — the sheath-reconcile bits the client tests on every `PlayAnimation`
-//!   (`0x5fdf80`). The identification is **byte-verified** (wow-re `sheath-policy.md` §6a, §5
-//!   cross-checked): the reconcile indexes the `WowClientDB<AnimationData>` cache (`0xc0e070`,
-//!   loader-asserted 7 columns × 28 B against `DBFilesClient\AnimationData.dbc`) by the current
-//!   sequence's AnimationData id, and all three flag tests read row offset `+0x8` = column 2.
-//!   The bits: `4` force-stow (casts, Swim 42–45, Mount 91,
-//!   SitChair 102–104, Loot 50), `0x10` force-stow (every Emote, AttackUnarmed 16/117,
-//!   SitGround 96–98, Kneel 114–116, AttackBow/Rifle/Thrown), `0x20` force-draw-melee (armed
-//!   attacks 17–19/85–88, Ready1H/2H/2HL 26–28, specials, FishingCast/Loop 133–134). The column's
-//!   exact 5875 value set is `{0, 4, 16, 20, 32}` — precisely the tested bit triple.
-//! - **Fallback (col 6)** — identified from the data (the chains are unambiguous:
-//!   Attack2H→Attack1H→AttackUnarmed, Sprint→Run, JumpLandRun→Run, Sleep→SleepDown, Drowned→Drown,
-//!   WalkBackwards→Walk, StealthWalk→Walk; col 5 read as a fallback yields nonsense — Attack2H→Stop,
-//!   Sleep→SpellCast). **Not the primary runtime missing-clip mechanism** (decision 0082, amending
-//!   this file's earlier reading): the real client's per-id fallback for ids `< 203` is a single
-//!   indexed read of the M2's own baked `PlayableAnimationLookup` (a per-model precomputed cache of
-//!   *this* column's walk against that model's actual sequence set — see
-//!   `benilla_formats::PlayableAnim` / `benilla_assets::ModelAnimations::resolve`). This column is
-//!   PATH 2 of that resolver (ids ≥ 203 only, `AnimationData.dbc`'s 208 rows) and the *source* the
-//!   baked tables were computed from. `0` = fall back to Stand.
-//! - Cols 4/5 are unidentified here (4 reads priority-like — 500 on Death/Dead/Drown, 10 on
-//!   locomotion; 5 flag-like) and are not exposed.
+//! `AnimationData.dbc`, the per-animation policy: 208 rows of `ID`, `Name`, `WeaponFlags`,
+//! `BodyFlags`, two unidentified columns and `Fallback`. The reference's sheath reconcile
+//! (`0x5fdf80`, on every `PlayAnimation`) reads `WeaponFlags` at row `+0x8` of the `0xc0e070` cache
+//! for the requested id, not a model's substitute: `4` and `0x10` stow, `0x20` draws melee, and
+//! 5875 sets no other bit. `Fallback` is walked only for ids past a model's baked
+//! `PlayableAnimationLookup` (203 and up), which was computed from it.
 
 use std::collections::HashMap;
 
@@ -39,7 +16,7 @@ use crate::Chain;
 /// One animation's policy row.
 #[derive(Clone, Copy)]
 pub struct AnimEntry {
-    /// The sheath-reconcile bits (see the module doc). `0` for most rows.
+    /// The sheath-reconcile bits (col 2).
     pub weapon_flags: u32,
     /// The substitute animation id when a model lacks this clip (`0` = Stand).
     pub fallback: u16,
@@ -48,15 +25,13 @@ pub struct AnimEntry {
 /// `AnimationData.dbc` id → its policy row.
 pub struct AnimDataCatalog {
     rows: HashMap<u16, AnimEntry>,
-    /// id → the row's Name string (col 1, `"Attack1H"`) — the human face for debug readouts
-    /// (the inspector's anim line). Beside [`AnimEntry`] so the policy row stays `Copy`.
+    /// The Name column (col 1, `"Attack1H"`) for debug readouts, kept apart so [`AnimEntry`]
+    /// stays `Copy`.
     names: HashMap<u16, String>,
 }
 
 impl AnimDataCatalog {
-    /// Build a catalog directly from rows — the synthetic-table entry point for tests exercising
-    /// missing-clip resolution's PATH 2 walk (decision 0082, `benilla_assets::ModelAnimations::resolve`)
-    /// without a real `AnimationData.dbc`.
+    /// A catalog of synthetic rows with no names, for tests without an `AnimationData.dbc`.
     pub fn from_rows(rows: impl IntoIterator<Item = (u16, AnimEntry)>) -> Self {
         Self {
             rows: rows.into_iter().collect(),
@@ -64,13 +39,13 @@ impl AnimDataCatalog {
         }
     }
 
-    /// The sheath-reconcile WeaponFlags for an animation id (`0` for an unknown id — no policy).
+    /// The WeaponFlags for an animation id, `0` (no policy) for an unknown one.
     pub fn weapon_flags(&self, id: u16) -> u32 {
         self.rows.get(&id).map_or(0, |r| r.weapon_flags)
     }
 
-    /// The fallback animation for a model lacking clip `id` — `None` when the row has none
-    /// (fallback 0 = Stand, left to the caller's own id-list fallbacks) or the id is unknown.
+    /// The fallback for a model lacking clip `id`; `None` for Stand (`0`), which the caller
+    /// resolves itself.
     pub fn fallback(&self, id: u16) -> Option<u16> {
         self.rows
             .get(&id)
@@ -78,8 +53,7 @@ impl AnimDataCatalog {
             .filter(|&f| f != 0 && f != id)
     }
 
-    /// The row's Name string (`"Run"`, `"Attack1H"`) — `None` for an unknown id or a
-    /// synthetic-table catalog ([`Self::from_rows`] keeps no names).
+    /// The row's Name (`"Run"`); a [`Self::from_rows`] catalog has none.
     pub fn name(&self, id: u16) -> Option<&str> {
         self.names.get(&id).map(String::as_str)
     }
@@ -134,9 +108,7 @@ pub fn load_anim_data_catalog(chain: &mut Chain) -> Result<AnimDataCatalog> {
 mod tests {
     use super::*;
 
-    /// The real 5875 table: the WeaponFlags value set is exactly the reconcile's tested bit
-    /// triple, the decision-0080 spot rows carry the recorded bits, and the fallback chains
-    /// resolve (Attack2H→Attack1H, Sprint→Run). Skips without client data.
+    /// The 5875 table: WeaponFlags within the reconcile's three bits, spot rows, fallback chains.
     #[test]
     fn real_animation_data_decodes() {
         let data = crate::wow_data_or_skip!();
@@ -144,7 +116,6 @@ mod tests {
         let cat = load_anim_data_catalog(&mut chain).expect("load AnimationData");
         assert_eq!(cat.len(), 208);
 
-        // The whole column stays within the tested bit triple {0, 4, 0x10, 0x14, 0x20}.
         for (&id, row) in &cat.rows {
             assert!(
                 matches!(row.weapon_flags, 0 | 4 | 0x10 | 0x14 | 0x20),
@@ -153,7 +124,6 @@ mod tests {
             );
         }
 
-        // Decision 0080's transcribed highlights.
         assert_eq!(cat.weapon_flags(42), 4, "Swim force-stows");
         assert_eq!(cat.weapon_flags(91), 4, "Mount force-stows");
         assert_eq!(cat.weapon_flags(102), 4, "SitChairLow force-stows");
@@ -169,18 +139,16 @@ mod tests {
         assert_eq!(cat.weapon_flags(133), 0x20, "FishingCast force-draws");
         assert_eq!(cat.weapon_flags(0), 0, "Stand carries no policy");
 
-        // The ranged-handling trio the reconcile exempts (0x69/0x6a/0x70).
+        // The ranged-handling trio the reconcile exempts.
         for id in [105, 106, 112] {
             assert_eq!(cat.weapon_flags(id), 0, "Load* anims carry no policy");
         }
 
-        // The name column (the inspector's anim line).
         assert_eq!(cat.name(0), Some("Stand"));
         assert_eq!(cat.name(5), Some("Run"));
         assert_eq!(cat.name(17), Some("Attack1H"));
         assert_eq!(cat.name(255), None, "unknown id has no name");
 
-        // The fallback chains.
         assert_eq!(cat.fallback(18), Some(17), "Attack2H → Attack1H");
         assert_eq!(cat.fallback(17), Some(16), "Attack1H → AttackUnarmed");
         assert_eq!(cat.fallback(143), Some(5), "Sprint → Run");
diff --git a/crates/benilla-formats/src/area_poi.rs b/crates/benilla-formats/src/area_poi.rs
index d390895d..e5b4a6d1 100644
--- a/crates/benilla-formats/src/area_poi.rs
+++ b/crates/benilla-formats/src/area_poi.rs
@@ -1,27 +1,8 @@
-//! `AreaPOI.dbc` — the world-map's named points of interest: inns, flight masters, dungeon
-//! entrances, battleground nodes — everything the minimap's nearest-3 POI blips (decision 0203
-//! phase 3) and the world map's POI icons draw from.
-//!
-//! **Client-only: vmangos carries no struct for this table** (never loaded server-side). Layout
-//! pinned by inspection this session (header + full 339-row decode, cross-checked against a
-//! community reference struct for the same build, 2026-07-07): **339 × 29 × 116 B**:
-//! `ID(0), Importance(1), Icon(2), FactionID(3), Pos[3](4-6, world x/y/z), ContinentID(7),
-//! Flags(8), AreaID(9), Name_lang(10, enUS string) + 7 other-locale slots(11-17) + NameFlags(18),
-//! Description_lang(19, enUS string) + 7 other-locale slots(20-26) + DescriptionFlags(27),
-//! WorldStateID(28)` — the field the task brief's 28-column enumeration left unaccounted for.
-//!
-//! Every field past `Pos`/`Name`/`Description` was proven by scanning all 339 rows, not assumed:
-//! `Importance` ∈ `{0,2,3,4}` and `Icon` takes 43 distinct small values (both enum-shaped);
-//! `FactionID` ∈ `{0,83,84}` (a `FactionTemplate` FK used for only the faction-tinted rows);
-//! `ContinentID` ∈ `{0,1,30,37,529}` — Azeroth/Kalimdor plus three battleground map ids;
-//! `AreaID` ranges `−1..=3427` including both `−1` (raw, stored as `u32::MAX` — the
-//! `WMOAreaTable`-style "no group" sentinel) and a distinct `0`; every row's `Pos.x`/`Pos.y` falls
-//! well inside `±17066` (the world-map half-extent); every row's enUS `Name_lang` is non-empty;
-//! and **field 28 is `0` on 209 rows and a small nonzero id on the other 130**, each of those 130
-//! landing in one of a handful of tight numeric bands (`1301-1304`, `1325-1340`, …) — exactly the
-//! shape of a `WorldState` id, confirmed on a named example: id 1613 "Stables" (an Arathi Basin
-//! node, `ContinentID` 529) carries `WorldStateID` 1770 and `Description_lang` "In Conflict", the
-//! live capture-state label a BG node's map icon shows.
+//! `AreaPOI.dbc`, the named points of interest (inns, flight masters, dungeon entrances,
+//! battleground nodes) behind the minimap's landmark blips and the world map's icons. Client-only:
+//! vmangos never loads it. 339 rows of 29 columns (116 B): `ID`, `Importance`, `Icon`,
+//! `FactionID`, `Pos[3]`, `ContinentID`, `Flags`, `AreaID`, then `Name` and `Description` as
+//! 9-column loc-strings (enUS, 7 other locales, flags), then `WorldStateID`.
 
 use std::collections::HashMap;
 
@@ -33,40 +14,34 @@ use crate::Chain;
 
 const AREA_POI: &str = "DBFilesClient\\AreaPOI.dbc";
 
-/// One `AreaPOI.dbc` row — a named world-map point of interest.
+/// One `AreaPOI.dbc` row.
 #[derive(Clone, Debug)]
 pub struct AreaPoi {
-    /// Map-icon prominence tier (`{0,2,3,4}` in 5875 — higher shows at more zoomed-out levels).
+    /// Prominence tier, `{0, 2, 3, 4}` in 5875; the minimap ranks its landmark arrows by it.
     pub importance: u32,
-    /// The map-icon art index (43 distinct icons in 5875).
+    /// The map icon, a cell of `POIIcons.blp`.
     pub icon: u32,
-    /// `FactionTemplate.dbc` FK for a faction-tinted icon; `0` = untinted (the common case).
+    /// `FactionTemplate.dbc` id for a faction-tinted icon, `0` for none.
     pub faction_id: u32,
     /// World position `(x, y, z)`.
     pub pos: [f32; 3],
-    /// The map id this POI's `pos` is expressed in (Azeroth `0`, Kalimdor `1`, or a
-    /// battleground/instance map id).
+    /// The map `pos` is in: `0` Azeroth, `1` Kalimdor, or a battleground map.
     pub continent_id: u32,
     pub flags: u32,
-    /// `AreaTable.dbc` id, or `u32::MAX` (raw `−1`) for a continent-wide POI — distinct in this
-    /// data from a plain `0` (see the module doc).
+    /// `AreaTable.dbc` id, or `u32::MAX` (raw `-1`) for a continent-wide POI.
     pub area_id: u32,
-    /// enUS display name (locale slot 0) — non-empty on every 5875 row.
+    /// enUS display name (locale slot 0).
     pub name: String,
-    /// enUS description (locale slot 0) — empty on the ~2/3 of rows with no live status text.
+    /// enUS live status text (`"In Conflict"`), empty on most rows.
     pub description: String,
-    /// `WorldState` id driving this POI's live label/icon (e.g. a battleground node's capture
-    /// state); `0` = no live state (209 of 339 rows).
+    /// The `WorldState` id driving the live label and icon (a battleground node's capture
+    /// state), `0` for none.
     pub world_state_id: u32,
 }
 
-/// `AreaPOI.dbc` — every row in **file order**, plus the id index.
-///
-/// File order is not tidiness: the reference's world-map landmark builder `0x4a67a0` walks the
-/// whole table by record (`[0xc0e054]`, count `[0xc0e058]`, stride `0x74`) and appends survivors
-/// in that order, so the landmark *index* a Lua `GetMapLandmarkInfo(i)` reads is the DBC's own
-/// order. A hash iteration would also make our landmark list a different permutation every frame,
-/// which the world map's change-diff would read as a change and repaint on.
+/// Every `AreaPOI.dbc` row in file order, plus an id index. The order is the reference's: its
+/// landmark builder `0x4a67a0` walks the table by record (`[0xc0e054]`, count `[0xc0e058]`), so
+/// `GetMapLandmarkInfo(i)` indexes in DBC order.
 pub struct AreaPoiCatalog {
     rows: Vec<(u32, AreaPoi)>,
     by_id: HashMap<u32, usize>,
@@ -77,9 +52,7 @@ impl AreaPoiCatalog {
         self.by_id.get(&id).map(|&i| &self.rows[i].1)
     }
 
-    /// Every row in **file order** — the reference builder's walk (see the type doc). The
-    /// nearest-3 minimap selection (decision 0203 phase 3) filters this by `continent_id` +
-    /// distance itself; the world map's landmark pass runs the `0x4a67a0` gate chain over it.
+    /// Every row in file order.
     pub fn rows(&self) -> impl Iterator<Item = (u32, &AreaPoi)> {
         self.rows.iter().map(|(id, poi)| (*id, poi))
     }
@@ -93,9 +66,6 @@ impl AreaPoiCatalog {
     }
 }
 
-/// 29 fields per the module doc: the two loc-string blocks are 9 dwords each (a string + 7
-/// other-locale string slots + a flags dword), matching the `TaxiNodes` schema pattern
-/// (`crate::schema_for`).
 fn schema() -> Schema {
     let mut s = Schema::new("AreaPOI");
     for name in ["ID", "Importance", "Icon", "FactionID"] {
@@ -151,9 +121,7 @@ pub fn load_area_poi_catalog(chain: &mut Chain) -> Result<AreaPoiCatalog> {
 mod tests {
     use super::*;
 
-    /// The real 5875 table proves the layout: every row's enUS name is readable text, continent
-    /// ids and world positions land in the expected ranges, and the pinned Arathi Basin "Stables"
-    /// example resolves its `WorldStateID` + live status description. Skips without client data.
+    /// The 5875 layout: readable names, positions in range, and Arathi Basin's Stables node.
     #[test]
     fn real_area_poi_layout_sanity() {
         let data = crate::wow_data_or_skip!();
@@ -172,7 +140,6 @@ mod tests {
                 "world x/y within the map half-extent: {:?}",
                 poi.pos
             );
-            // 0/1 are the continents; the rest are battleground/instance map ids — all small.
             assert!(poi.continent_id < 10_000, "continentId is a small map id");
             if poi.world_state_id != 0 {
                 worldstate_nonzero += 1;
@@ -184,7 +151,6 @@ mod tests {
             "a meaningful share of rows carry a live WorldStateID: {worldstate_nonzero}"
         );
 
-        // The pinned Arathi Basin "Stables" node.
         let stables = cat.get(1613).expect("id 1613 (Stables)");
         assert_eq!(stables.name, "Stables");
         assert_eq!(stables.continent_id, 529, "Arathi Basin's map id");
diff --git a/crates/benilla-formats/src/area_sound.rs b/crates/benilla-formats/src/area_sound.rs
index 87400f2b..8aed2517 100644
--- a/crates/benilla-formats/src/area_sound.rs
+++ b/crates/benilla-formats/src/area_sound.rs
@@ -1,20 +1,7 @@
-//! The zone→audio data plane: **AreaTable** (the zone/subzone row the MCNK `areaId` points at)
-//! joined to **ZoneMusic** / **SoundAmbience** / **ZoneIntroMusicTable** (decision 0070, slice 1).
-//!
-//! Layouts — VERIFIED against build 5875 (header + row decodes, 2026-07-02):
-//! - `AreaTable.dbc` **1081 × 25 × 100 B**: `ID(0), ContinentID(1), ParentAreaID(2), AreaBit(3),
-//!   Flags(4), SoundProviderPref(5), SoundProviderPrefUnderwater(6), AmbienceID(7), ZoneMusic(8),
-//!   IntroSound(9), ExplorationLevel(10), AreaName_lang(11..19), FactionGroupMask(20),
-//!   LiquidTypeID[4](21..24)`. Spot-check row 12: "Elwynn Forest", Ambience 35, ZoneMusic 1.
-//!   NOTE the wowdev-wiki 5875 struct appends TBC+ fields (28 cols) — **wrong**; 25 verified
-//!   (decision 0070).
-//! - `ZoneMusic.dbc` **99 × 8 × 32 B**: `ID, SetName(str), SilenceMin[2], SilenceMax[2],
-//!   Sounds[2]` — the `[2]` arrays are `[day, night]`, intervals in **ms**, `Sounds` →
-//!   SoundEntries kits (type 28). Row 1: "Zone-Forest", 180 000–300 000 ms, kit 2523/2523.
-//! - `ZoneIntroMusicTable.dbc` **43 × 5 × 20 B**: `ID, Name(str), SoundID, Priority,
-//!   MinDelayMinutes`. Row 61: "Valley of Heroes", 2541, 1, 60.
-//! - `SoundAmbience.dbc` **68 × 3 × 12 B**: `ID, AmbienceID[2] = [day, night]` → looping
-//!   SoundEntries kits (type 50). Row 22: day 4163 / night 4204.
+//! The zone audio tables: `AreaTable` (the row an MCNK `areaId` names) joined to `ZoneMusic`,
+//! `SoundAmbience` and `ZoneIntroMusicTable`. `AreaTable.dbc` has 25 columns in 5875, not the 28
+//! of later builds: the eleven `area_schema` names, `AreaName_lang` (11-19), `FactionGroupMask`
+//! and `LiquidTypeID[4]`.
 
 use std::collections::HashMap;
 
@@ -27,19 +14,18 @@ use crate::dbc::{parse, str_at, u32_at};
 /// The audio-relevant slice of one `AreaTable` row.
 pub struct AreaEntry {
     pub id: u32,
-    /// Parent zone (subzone rows inherit unset audio fields from it; 0 = a top-level zone).
+    /// The parent zone, `0` for a top-level one; a subzone inherits its unset audio ids.
     pub parent: u32,
-    /// `SoundAmbience.dbc` FK (0 = inherit/none).
+    /// `SoundAmbience.dbc` id, `0` to inherit.
     pub ambience: u32,
-    /// `ZoneMusic.dbc` FK (0 = inherit/none).
+    /// `ZoneMusic.dbc` id, `0` to inherit.
     pub zone_music: u32,
-    /// `ZoneIntroMusicTable.dbc` FK (0 = inherit/none).
+    /// `ZoneIntroMusicTable.dbc` id, `0` to inherit.
     pub intro_sound: u32,
-    /// `SoundProviderPreferences.dbc` FK — the dry-land reverb preset (0 = inherit/none; only
-    /// 8 areas in 1.12, all dungeon floors — interiors carry theirs on `WMOAreaTable`).
+    /// `SoundProviderPreferences.dbc` id of the dry-land reverb preset, `0` to inherit;
+    /// interiors carry theirs on `WMOAreaTable`.
     pub sound_provider: u32,
-    /// `SoundProviderPreferences.dbc` FK while the listener is submerged (pref 11 "Underwater"
-    /// on 568 areas; 0 = inherit/none).
+    /// The preset while the listener is submerged (11 is "Underwater"), `0` to inherit.
     pub sound_provider_underwater: u32,
     /// The zone/subzone display name (enUS column).
     pub name: String,
@@ -49,24 +35,24 @@ pub struct AreaEntry {
 pub struct ZoneMusicEntry {
     pub id: u32,
     pub set_name: String,
-    /// Silence between tracks, milliseconds, uniform in `[min, max]`.
+    /// Silence between tracks in ms, uniform in `[min, max]`.
     pub silence_min: [u32; 2],
     pub silence_max: [u32; 2],
-    /// SoundEntries kits (type 28) — the track pool per phase.
+    /// `SoundEntries` kits (type 28), the track pool per phase.
     pub sounds: [u32; 2],
 }
 
-/// One `ZoneIntroMusicTable` row — the entry fanfare.
+/// One `ZoneIntroMusicTable` row, the fanfare on entering an area.
 pub struct ZoneIntroEntry {
     pub id: u32,
     pub sound_id: u32,
     /// Higher wins when nested areas compete.
     pub priority: u32,
-    /// Replay throttle, minutes.
+    /// Replay throttle in minutes.
     pub min_delay_minutes: u32,
 }
 
-/// One `SoundAmbience` row: the looping ambience kits, `[day, night]`.
+/// One `SoundAmbience` row: the looping ambience kits (type 50), `[day, night]`.
 pub struct SoundAmbienceEntry {
     pub id: u32,
     pub kits: [u32; 2],
@@ -80,7 +66,7 @@ pub struct AreaSoundCatalog {
     ambience: HashMap<u32, SoundAmbienceEntry>,
 }
 
-/// An area's fully-resolved audio identity (after the parent walk).
+/// An area's audio after the parent walk.
 pub struct AreaAudio<'a> {
     pub area_name: &'a str,
     pub music: Option<&'a ZoneMusicEntry>,
@@ -99,20 +85,18 @@ impl AreaSoundCatalog {
         self.zone_music.get(&id)
     }
 
-    /// A `ZoneIntroMusicTable` row by id (the WMO interior override path resolves intros
-    /// directly — `WMOAreaTable.IntroSound` — instead of through an area row).
+    /// A `ZoneIntroMusicTable` row by id, for a `WMOAreaTable.IntroSound` interior override.
     pub fn intro(&self, id: u32) -> Option<&ZoneIntroEntry> {
         self.intros.get(&id)
     }
 
-    /// A `SoundAmbience` row by id (the WMO interior override path).
+    /// A `SoundAmbience` row by id, for a WMO interior override.
     pub fn ambience_row(&self, id: u32) -> Option<&SoundAmbienceEntry> {
         self.ambience.get(&id)
     }
 
-    /// Resolve an `areaId` to its audio rows, walking `ParentAreaID` for any FK that is 0 on the
-    /// subzone row (the standard vanilla inheritance: a subzone without its own music plays the
-    /// zone's). Cycle-guarded; `None` fields mean "no music/ambience anywhere up the chain".
+    /// An `areaId`'s audio rows, each id left `0` taken from the nearest ancestor up
+    /// `ParentAreaID`: a subzone without its own music plays its zone's.
     pub fn resolve(&self, area_id: u32) -> Option<AreaAudio<'_>> {
         let first = self.areas.get(&area_id)?;
         let (mut music, mut intro, mut ambience) = (None, None, None);
@@ -325,10 +309,7 @@ pub fn load_area_sound_catalog(chain: &mut Chain) -> Result<AreaSoundCatalog> {
 mod tests {
     use super::*;
 
-    /// End-to-end on the **real** 5875 tables: Elwynn Forest (area 12) resolves to the
-    /// "Zone-Forest" music set (3–5 min silence, kit 2523) and ambience 35; a subzone with its
-    /// own row zeroes (Crystal Lake 87, parent 12) inherits Elwynn's music through the parent
-    /// walk. Skips without client data.
+    /// The 5875 tables: Elwynn Forest (area 12) and a subzone inheriting its music.
     #[test]
     fn real_area_chain_resolves_elwynn() {
         let data = crate::wow_data_or_skip!();
@@ -355,7 +336,6 @@ mod tests {
         assert_eq!(music.sounds, [2523, 2523]);
         assert!(elwynn.ambience.is_some(), "Elwynn has ambience");
 
-        // A subzone of Elwynn inherits through the parent walk when its own FKs are 0.
         let sub = cat
             .areas
             .values()
diff --git a/crates/benilla-formats/src/area_table.rs b/crates/benilla-formats/src/area_table.rs
index aa82f5f3..a07f69cb 100644
--- a/crates/benilla-formats/src/area_table.rs
+++ b/crates/benilla-formats/src/area_table.rs
@@ -1,20 +1,6 @@
-//! `AreaTable.dbc` — the area catalog: id → (map, parent zone, explore bit, name). The world map
-//! (decision 0203 phase 2) resolves the player's MCNK `areaId` to its **top-level zone** through
-//! the parent chain here (`SetMapToCurrentZone`), and labels zones with the localized `AreaName`
-//! (the WorldMapArea string is the art *folder* — "Elwynn" — while the display name lives here —
-//! "Elwynn Forest"). Phase 3's exploration overlays key off [`AreaTableRow::explore_flag`].
-//!
-//! Layout — VERIFIED against build 5875 (2026-07-07, real-row decode: Northshire Valley id 9 →
-//! zone 12 = Elwynn Forest; Booty Bay id 35 → zone 33 = Stranglethorn Vale; cross-checked against
-//! mangoszero's `AreaTableEntry`): **25 × u32 cols**: `ID(0), MapID(1), ZoneID(2 — the parent
-//! area, 0 = this row IS a top-level zone), ExploreFlag(3), Flags(4), … ExplorationLevel(10, the
-//! binary's `+0x28`), AreaName(11)` + loc block, `FactionGroupMask(20)`. Sibling readers of the
-//! same file: `quest_headers.rs` (id → name only), `area_sound.rs` (the audio columns).
-//!
-//! The PvP columns (zone-splash arc, decision 0287) — census of the real 5875 table:
-//! `FactionGroupMask` is 2/4/0 (Alliance/Horde/neither) on zone rows and ~always 0 on subzone
-//! rows; `Flags` bit `0x80` marks exactly the three FFA duel pits (Battle Ring 2177, The Rumble
-//! Cage 2857, The Maul 3217 + its UNUSED twin) — *not* the enclosing "Gurubashi Arena" row.
+//! `AreaTable.dbc`, the area catalog. The world map walks an MCNK `areaId` up the parent chain to
+//! its top-level zone (`SetMapToCurrentZone`) and labels it with the localized `AreaName`
+//! ("Elwynn Forest"; `WorldMapArea` holds the art folder, "Elwynn").
 
 use std::collections::HashMap;
 
@@ -26,28 +12,21 @@ use crate::dbc::{parse, str_at, u32_at};
 
 const AREA_TABLE: &str = "DBFilesClient\\AreaTable.dbc";
 
-/// One `AreaTable.dbc` row (the columns the map arc reads).
+/// One `AreaTable.dbc` row, the columns the map reads.
 #[derive(Clone, Debug)]
 pub struct AreaTableRow {
     /// `Map.dbc` id the area lives on.
     pub map_id: u32,
-    /// The parent area's id — `0` means this row is itself a top-level zone.
+    /// The parent area's id; `0` means this row is itself a top-level zone.
     pub zone_id: u32,
-    /// The exploration bit index (`PLAYER_EXPLORED_ZONES` bitset / `WorldMapOverlay` join,
-    /// phase 3).
+    /// The exploration bit index into `PLAYER_EXPLORED_ZONES`, also the `WorldMapOverlay` join.
     pub explore_flag: u32,
-    /// Area flags (col 4). Bit `0x80` = FFA duel pit ("PvP Area" / `isArena`, decision 0287);
-    /// bit `0x1` = snow; capitals carry `0x138`.
+    /// Bit `0x80` marks an FFA duel pit row (not its arena's), `0x1` snow; capitals carry `0x138`.
     pub flags: u32,
-    /// `FactionGroup.dbc` mask of the owning side (col 20): 2 = Alliance, 4 = Horde, 0 = neither
-    /// (contested — or a subzone row deferring to its zone).
+    /// `FactionGroup.dbc` mask of the owner: 2 Alliance, 4 Horde, 0 contested or a subzone row.
     pub faction_group_mask: u32,
-    /// `ExplorationLevel` (col 10, the binary's `AreaTable+0x28`) — **signed**, and read only as
-    /// `>= 0` vs `< 0`. It is the world-map landmark builder's exploration gate: a landmark whose
-    /// `AreaID` lands on a row with `>= 0` here stays hidden until the player has explored that
-    /// area ([`Self::explore_flag`]'s bit); `-1` exempts it (wow-re `gossip-poi-marker.md` §8.2,
-    /// `0x4a6890`–`0x4a68f3`). The 5875 table is `-1` on exactly one row and `>= 0` on the other
-    /// 1080, so in practice the gate applies wherever an `AreaID` resolves at all.
+    /// `ExplorationLevel` (`AreaTable+0x28`), read for its sign: a world-map landmark on a row
+    /// `>= 0` stays hidden until the area is explored, `-1` exempts it (`0x4a6890`-`0x4a68f3`).
     pub exploration_level: i32,
     /// The localized display name ("Elwynn Forest").
     pub name: String,
@@ -59,9 +38,7 @@ pub struct AreaTableCatalog {
 }
 
 impl AreaTableCatalog {
-    /// A catalog over rows given directly, rather than read off the chain — for a caller that
-    /// needs a table of exactly known shape (the map-arc gate tests build two-row ones, so that
-    /// what a gate does with `ExplorationLevel -1` is asserted rather than hoped for).
+    /// A catalog over rows given directly, for tests that need a table of known shape.
     pub fn from_rows(rows: Vec<(u32, AreaTableRow)>) -> Self {
         Self {
             by_id: rows.into_iter().collect(),
@@ -72,14 +49,12 @@ impl AreaTableCatalog {
         self.by_id.get(&id)
     }
 
-    /// The display name for `id`, or `None`.
+    /// The localized display name for `id`.
     pub fn name(&self, id: u32) -> Option<&str> {
         self.by_id.get(&id).map(|r| r.name.as_str())
     }
 
-    /// The top-level zone containing `area_id`: walk the `zone_id` parent chain until a row whose
-    /// parent is 0 (possibly `area_id` itself). `None` for an unknown id. Depth-guarded — the
-    /// 5875 chains are 1–2 deep, anything deeper is data corruption, not geography.
+    /// The top-level zone above `area_id`, or itself; a chain deeper than eight is corrupt data.
     pub fn top_zone(&self, area_id: u32) -> Option<u32> {
         let mut id = area_id;
         for _ in 0..8 {
@@ -92,24 +67,9 @@ impl AreaTableCatalog {
         None
     }
 
-    /// Is `area_id` **cold** — does a unit standing here puff visible breath?
-    ///
-    /// The client's `0x67e9c0` (wow-re `object-layer/scratch/cold-breath-law.md` Q2), byte-exact:
-    ///
-    /// ```text
-    /// cold ⟺ ((leaf.Flags & 0x2) || no valid parent ? leaf.Flags : parent.Flags) & 0x1
-    /// ```
-    ///
-    /// **One hop, never a chain walk** ([`Self::top_zone`] is a different question with a
-    /// different answer). Bit `0x1` is authored on exactly four leaf rows in 5875 — Dun Morogh,
-    /// Winterspring, Razorfen Downs, Naxxramas — and the single-hop inheritance is what spreads it
-    /// to the 45 areas that are actually cold: every sub-area of Dun Morogh and Winterspring
-    /// carries `0x40` (bit `0x2` clear) and therefore reads its zone's flags instead. Bit `0x2` is
-    /// the opt-out that makes a sub-area answer for itself.
-    ///
-    /// This is **independent of the weather**: snowfall and breath vapour share no input, and
-    /// there is no indoor suppression — standing in the Thunderbrew Distillery is as cold as the
-    /// road outside, because indoor-ness only changes *which row* resolves, not this test.
+    /// Whether a unit standing in `area_id` puffs visible breath (`0x67e9c0`): bit `0x1` of the
+    /// leaf's flags when it sets bit `0x2` or has no parent row, else of its parent's. One hop,
+    /// never a chain walk, and no weather or indoor input.
     pub fn is_cold(&self, area_id: u32) -> bool {
         let Some(leaf) = self.by_id.get(&area_id) else {
             return false;
@@ -122,13 +82,7 @@ impl AreaTableCatalog {
         row.flags & 0x1 != 0
     }
 
-    /// The id of the zone **named** `name`, case-insensitively — the reverse of [`Self::name`],
-    /// for the one caller that has a name and needs the id: `/who`'s `z-"Elwynn Forest"` term,
-    /// which goes on the wire as a zone id (decision 0668).
-    ///
-    /// Names are not unique across the table (a subzone can share its zone's name, instance rows
-    /// repeat), so a **top-level** row (`zone_id == 0`) wins over any other match — that is what
-    /// "zone" means to the caller. Linear, which is fine at one call per query.
+    /// The id of the area named `name` (any case) for `/who`'s `z-` term; a top-level row wins.
     pub fn id_for_name(&self, name: &str) -> Option<u32> {
         let mut fallback = None;
         for (id, row) in &self.by_id {
@@ -143,9 +97,7 @@ impl AreaTableCatalog {
         fallback
     }
 
-    /// Every row, unordered — for the rare query that is a whole-table **scan by flag** rather
-    /// than a lookup by id. The chat auto-join's city-word row (`Flags & 0x200`) is the first such
-    /// consumer, and it is a scan in the client too.
+    /// Every row, unordered, for a scan by flag (the chat auto-join's `Flags & 0x200` city row).
     pub fn rows(&self) -> impl Iterator<Item = &AreaTableRow> {
         self.by_id.values()
     }
@@ -159,9 +111,6 @@ impl AreaTableCatalog {
     }
 }
 
-/// 25 u32-wide columns; only
-/// `ID/MapID/ZoneID/ExploreFlag/Flags/ExplorationLevel/AreaName/FactionGroupMask` are read (see
-/// module doc).
 fn schema() -> Schema {
     let mut s = Schema::new("AreaTable");
     for i in 0..25 {
@@ -192,8 +141,7 @@ pub fn load_area_table_catalog(chain: &mut Chain) -> Result<AreaTableCatalog> {
             continue;
         };
         let faction_group_mask = u32_at(r, 20).unwrap_or(0);
-        // Signed: `-1` is the "no exploration requirement" row. Absent reads as `-1` for the
-        // same reason — an unreadable column must not invent a gate.
+        // Signed; an absent column reads as `-1`, no exploration gate.
         let exploration_level = u32_at(r, 10).map_or(-1, |v| v as i32);
         by_id.insert(
             id,
@@ -215,9 +163,6 @@ pub fn load_area_table_catalog(chain: &mut Chain) -> Result<AreaTableCatalog> {
 mod tests {
     use super::*;
 
-    /// The real 5875 table: the verified parent chains (Northshire → Elwynn, Booty Bay →
-    /// Stranglethorn), a top-level zone resolving to itself, and the display-vs-art-folder name
-    /// split. Skips without client data.
     #[test]
     fn real_area_table_parent_chains_and_names() {
         let data = crate::wow_data_or_skip!();
@@ -234,29 +179,23 @@ mod tests {
         assert_eq!(northshire.name, "Northshire Valley");
         assert_eq!(cat.top_zone(9), Some(12));
 
-        // A leaf two hops down: Booty Bay → Stranglethorn Vale (top-level).
+        // Booty Bay (35) sits under Stranglethorn Vale (33), a top-level zone.
         assert_eq!(cat.top_zone(35), Some(33));
 
-        // A top-level zone resolves to itself; its display name differs from the art folder.
         assert_eq!(cat.top_zone(12), Some(12));
         assert_eq!(cat.name(12), Some("Elwynn Forest"));
 
-        // The phase-3 explore bit is populated (Elwynn's is 126 in 5875).
         assert_eq!(cat.get(12).expect("Elwynn").explore_flag, 126);
 
-        // The PvP columns (decision 0287): ownership masks on zone rows…
         assert_eq!(cat.get(12).expect("Elwynn").faction_group_mask, 2);
         assert_eq!(cat.get(14).expect("Durotar").faction_group_mask, 4);
         assert_eq!(cat.get(33).expect("Stranglethorn").faction_group_mask, 0);
-        // …and the FFA-pit bit on the leaf pit rows, NOT the enclosing arena row.
+        // The FFA-pit bit is on the pit row, not the enclosing arena row.
         assert_ne!(cat.get(2177).expect("Battle Ring").flags & 0x80, 0);
         assert_eq!(cat.get(1741).expect("Gurubashi Arena").flags & 0x80, 0);
     }
 
-    /// The cold-breath predicate on the shipped table (`0x67e9c0`): bit `0x1` is authored on
-    /// exactly four rows, and the ONE-HOP parent inheritance is what makes the sub-areas cold.
-    /// This is the test that would have caught reading the leaf alone — every place a player
-    /// actually stands in Dun Morogh is a sub-area whose own flags are `0x40`.
+    /// The sub-areas carry `0x40`, so only the one-hop inheritance makes them cold.
     #[test]
     fn cold_areas_inherit_one_hop_from_their_zone() {
         let data = crate::wow_data_or_skip!();
@@ -274,7 +213,6 @@ mod tests {
             assert!(cat.is_cold(id), "{label} is cold");
         }
 
-        // The sub-areas: own flags `0x40` (bit 0x1 clear, bit 0x2 clear) → they read the zone's.
         for (id, label) in [
             (131, "Kharanos"),
             (132, "Coldridge Valley"),
@@ -286,8 +224,8 @@ mod tests {
             assert!(cat.is_cold(id), "{label} inherits its zone's cold");
         }
 
-        // Negative controls, including the sharp one: Gnomeregan the Dun Morogh sub-area (133) is
-        // cold; Gnomeregan the dungeon row (721), which is its own top-level zone, is not.
+        // Gnomeregan the Dun Morogh sub-area (133) is cold; the dungeon row (721), its own
+        // top-level zone, is not.
         assert!(cat.is_cold(133), "Gnomeregan the sub-area");
         for (id, label) in [
             (721, "Gnomeregan (dungeon)"),
diff --git a/crates/benilla-formats/src/area_trigger.rs b/crates/benilla-formats/src/area_trigger.rs
index 54d8599c..9b00944a 100644
--- a/crates/benilla-formats/src/area_trigger.rs
+++ b/crates/benilla-formats/src/area_trigger.rs
@@ -1,18 +1,6 @@
-//! `AreaTrigger.dbc` — the world's invisible trip-wires, and the containment law that fires them.
-//!
-//! A trigger is a volume the *client* watches: when the player walks into one, the client sends
-//! `CMSG_AREATRIGGER` naming its id and the **server** decides what that means — a teleport (every
-//! instance entrance, the Darnassus/Rut'theran portals), a quest's "explore here" objective, the
-//! inn's rested-XP state, a battleground's entrance list. The client owns only the geometry; it
-//! never knows what any trigger does.
-//!
-//! Layout — 10 × 4-byte columns (record stride `0x28`, which is what the reference's own scan
-//! strides by): `ID(0), MapID(1), X(2), Y(3), Z(4), Radius(5), BoxLength(6), BoxWidth(7),
-//! BoxHeight(8), BoxYaw(9)`. Positions are WoW world space (the space `bevy_to_wow` produces),
-//! yaw in radians.
-//!
-//! The containment law is [`AreaTriggerRow::contains`] — read from the reference's `0x5e22d0`
-//! (wow-5875-re `object-layer/scratch/w2b1-decomp.c`), which is the only place this math lives.
+//! `AreaTrigger.dbc`, the world's trigger volumes. The client owns only the geometry, sending
+//! `CMSG_AREATRIGGER` on entering one; the server alone decides what it does. Rows stride `0x28`,
+//! as the reference's scan does; positions are WoW world space (`bevy_to_wow`), yaw in radians.
 
 use std::collections::HashMap;
 
@@ -24,8 +12,7 @@ use crate::dbc::{f32_at, parse, u32_at};
 
 const AREA_TRIGGER: &str = "DBFilesClient\\AreaTrigger.dbc";
 
-/// One `AreaTrigger.dbc` row: a sphere (`radius != 0`) or an oriented box (`radius == 0`) sitting
-/// on one map, in WoW world space.
+/// One `AreaTrigger.dbc` row: a sphere (`radius != 0`) or an oriented box (`radius == 0`).
 #[derive(Clone, Copy, Debug)]
 pub struct AreaTriggerRow {
     /// The id that goes on the wire in `CMSG_AREATRIGGER`.
@@ -34,34 +21,20 @@ pub struct AreaTriggerRow {
     pub map_id: u32,
     /// Centre, WoW world space.
     pub position: [f32; 3],
-    /// Sphere radius (yd). `0` ⇒ this row is a box; see [`Self::contains`].
+    /// Sphere radius in yards; `0` makes the row a box.
     pub radius: f32,
-    /// **Full** box extents along the box's own local X/Y/Z (yd) — halved by the containment test,
-    /// which is how the reference reads them.
+    /// Full box extents along its local X/Y/Z in yards; the containment test halves them.
     pub box_size: [f32; 3],
-    /// The box's yaw about world Z (radians, CCW from +X), i.e. where its local +X points.
+    /// The box's yaw about world Z in radians, CCW from +X: where its local +X points.
     pub box_yaw: f32,
 }
 
 impl AreaTriggerRow {
-    /// Is `p` (WoW world space) inside this volume?
-    ///
-    /// **VERIFIED** against the reference's containment predicate `0x5e22d0` (wow-5875-re
-    /// `object-layer/scratch/w2b1-decomp.c`; the ledger classes it ORCHESTRATION over gx's matrix
-    /// ops, and the comparison it owns is what this reproduces):
-    ///
-    /// - **`radius != 0` ⇒ sphere**, tested in **3D** and **inclusively**: the reference computes
-    ///   `Σ(centre − p)²` and returns "inside" on `radius² >= dist²`.
-    /// - **`radius == 0` ⇒ oriented box**: the point is carried into the box's own frame (translate
-    ///   to the centre, rotate by **−`box_yaw`** about Z) and compared against ±half of each
-    ///   `box_size` component, **strictly** on all six faces (`-h < l < h`). The reference does the
-    ///   transform through gx (`0x7bdc40` load / `0x7bdd60` rotate-about-Z / `0x7bd700` apply) and
-    ///   owns only the comparison; vmangos's `IsPointInAreaTriggerZone` reaches the same law from
-    ///   the other side (it rotates the player by `2π − box_orientation`, which is this rotation).
-    ///
-    /// The server re-runs the same test with **5 yd of slop** before acting
-    /// (`MiscHandler.cpp:641`), so a marginally tight answer here still opens the door; a
-    /// marginally *loose* one is simply ignored.
+    /// Whether `p` is inside, as the reference's `0x5e22d0` tests it. A sphere is a plain 3D
+    /// distance check, inclusive (`radius² >= Σ(centre − p)²`); a box carries `p` into its frame
+    /// through gx's matrix ops (`0x7bdc40` load, `0x7bdd60` rotate by `-box_yaw`, `0x7bd700`
+    /// apply), strict against half of `box_size` on all six faces. The server re-tests with 5 yd
+    /// of slop (`MiscHandler.cpp:641`).
     pub fn contains(&self, p: [f32; 3]) -> bool {
         if self.radius != 0.0 {
             let d = [
@@ -73,8 +46,7 @@ impl AreaTriggerRow {
             return self.radius * self.radius >= dist_sq;
         }
 
-        // World → box-local: the box's local +X points along `box_yaw`, so the inverse rotation is
-        // by −yaw about Z. Z is unrotated (the volume never pitches or rolls).
+        // World to box-local: rotate by -yaw about Z; the volume never pitches or rolls.
         let (sin, cos) = (-self.box_yaw).sin_cos();
         let dx = p[0] - self.position[0];
         let dy = p[1] - self.position[1];
@@ -90,31 +62,25 @@ impl AreaTriggerRow {
     }
 }
 
-/// Every `AreaTrigger.dbc` row, bucketed by map — the per-map window the reference narrows to
-/// before each check (`0x5e2080` walks the map-sorted table for a `[first, end)` index range;
-/// bucketing answers the same question without depending on the file staying sorted).
-///
-/// **File order is preserved inside each bucket**, because the check takes the *first* containing
-/// row and volumes do overlap (an instance entrance sits inside its building's larger trigger).
+/// Every row bucketed by map, the window the reference narrows to (`0x5e2080`). File order holds
+/// in a bucket: the check takes the first containing row, and volumes overlap.
 pub struct AreaTriggerCatalog {
     by_map: HashMap<u32, Vec<AreaTriggerRow>>,
     len: usize,
 }
 
 impl AreaTriggerCatalog {
-    /// The triggers on `map_id`, in file order (empty for a map with none).
+    /// The triggers on `map_id`, in file order.
     pub fn on_map(&self, map_id: u32) -> &[AreaTriggerRow] {
         self.by_map.get(&map_id).map_or(&[], |v| v.as_slice())
     }
 
-    /// The **first** trigger on `map_id` containing `p` — the reference's own pick
-    /// (`0x5e2110` breaks its scan on the first hit).
+    /// The first trigger on `map_id` containing `p`, where `0x5e2110` stops its scan.
     pub fn first_containing(&self, map_id: u32, p: [f32; 3]) -> Option<&AreaTriggerRow> {
         self.on_map(map_id).iter().find(|t| t.contains(p))
     }
 
-    /// A row by id (linear over its map's bucket is not available here — ids are unique table-wide,
-    /// so this walks every bucket; used by tests and diagnostics, never per frame).
+    /// A row by id, walking every bucket: for tests and diagnostics, never per frame.
     pub fn get(&self, id: u32) -> Option<&AreaTriggerRow> {
         self.by_map.values().flatten().find(|t| t.id == id)
     }
@@ -128,7 +94,7 @@ impl AreaTriggerCatalog {
     }
 }
 
-/// 10 u32/f32-wide columns (see module doc).
+/// The 10-column `AreaTrigger.dbc` schema.
 pub fn area_trigger_schema() -> Schema {
     let mut s = Schema::new("AreaTrigger");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -186,7 +152,6 @@ mod tests {
         }
     }
 
-    /// The sphere leg: 3D, and inclusive exactly on the surface (the reference's `radius² >= d²`).
     #[test]
     fn sphere_is_3d_and_inclusive() {
         let t = sphere(5.0);
@@ -196,12 +161,11 @@ mod tests {
             "exactly on the surface is in"
         );
         assert!(!t.contains([15.1, 20.0, 30.0]));
-        // Z counts: straight up out of the sphere is out, which a 2D test would miss.
+        // Z counts: straight up out of the sphere is out.
         assert!(!t.contains([10.0, 20.0, 36.0]));
         assert!(t.contains([10.0, 20.0, 34.0]));
     }
 
-    /// The box leg: half-extents, strict faces, and the yaw actually rotating the volume.
     #[test]
     fn box_is_half_extents_strict_and_yawed() {
         let axis_aligned = AreaTriggerRow {
@@ -215,12 +179,10 @@ mod tests {
         assert!(axis_aligned.contains([4.9, 1.9, 0.9]));
         // Half, not full: 6 yd along a 10-yd box is outside.
         assert!(!axis_aligned.contains([6.0, 0.0, 0.0]));
-        // Strict on the face itself.
         assert!(!axis_aligned.contains([5.0, 0.0, 0.0]));
         assert!(!axis_aligned.contains([0.0, 0.0, 1.0]));
 
-        // Rotate the same box a quarter turn: the long axis now runs along world +Y, so a point
-        // that was inside along X is outside, and its mirror along Y is inside.
+        // A quarter turn puts the long axis along world +Y.
         let turned = AreaTriggerRow {
             box_yaw: std::f32::consts::FRAC_PI_2,
             ..axis_aligned
@@ -229,8 +191,6 @@ mod tests {
         assert!(turned.contains([0.0, 4.0, 0.0]));
     }
 
-    /// The real 5875 table: the Darnassus portal pair the reports name (B70), a box row and a
-    /// sphere row both present, and the per-map bucketing. Skips without client data.
     #[test]
     fn real_area_triggers_load_and_contain_their_own_centres() {
         let data = crate::wow_data_or_skip!();
@@ -238,21 +198,16 @@ mod tests {
         let cat = load_area_trigger_catalog(&mut chain).expect("load AreaTrigger");
         assert_eq!(cat.len(), 432, "5875 ships 432 area triggers");
 
-        // The two the Darnassus report rides on (B70), both on Kalimdor, both 10-yd spheres. They
-        // pin the coordinate columns from *outside* the client: vmangos's `areatrigger_teleport`
-        // sends 527 ("Darnassus - Exit") to (8785.79, 966.98, 30.20) — which is trigger **542**'s
-        // own position here, and vice versa. Two independent sources, agreeing to a couple of yards,
-        // on a pair of doorways that teleport to each other.
+        // The Darnassus portal pair, 10-yd spheres on Kalimdor: vmangos's `areatrigger_teleport`
+        // sends 527 to (8785.79, 966.98, 30.20), trigger 542's position here, and 542 to 527's.
         let exit = *cat.get(527).expect("trigger 527 (Darnassus - Exit)");
         let entrance = *cat.get(542).expect("trigger 542 (Darnassus - Entrance)");
         assert_eq!((exit.map_id, entrance.map_id), (1, 1));
         assert!(exit.contains([9947.0, 2630.0, 1318.0]), "{exit:?}");
         assert!(entrance.contains([8799.0, 970.0, 30.0]), "{entrance:?}");
-        // …and 25 yd away is outside a 10-yd sphere.
         assert!(!entrance.contains([8824.0, 970.0, 30.0]));
 
-        // Every volume contains its own centre — the one invariant that catches a column shift
-        // (a size read as a coordinate, or a radius read from the wrong slot, breaks it).
+        // Every volume contains its own centre, which a column shift breaks.
         for t in cat.on_map(1) {
             assert!(
                 t.contains(t.position),
@@ -261,15 +216,12 @@ mod tests {
             );
         }
 
-        // Both shapes are represented in the shipped table.
-        // Both shapes ship: 80 boxes, the rest spheres.
         let boxes = cat.on_map(0).iter().filter(|t| t.radius == 0.0).count();
         assert!(
             boxes > 0 && boxes < cat.on_map(0).len(),
             "map 0 has both shapes"
         );
 
-        // Buckets are per map, and the two continents carry most of the table.
         assert!(cat.on_map(1).iter().all(|t| t.map_id == 1));
         assert_eq!((cat.on_map(0).len(), cat.on_map(1).len()), (133, 121));
     }
diff --git a/crates/benilla-formats/src/auction_house.rs b/crates/benilla-formats/src/auction_house.rs
index 30fe8024..b670aeaa 100644
--- a/crates/benilla-formats/src/auction_house.rs
+++ b/crates/benilla-formats/src/auction_house.rs
@@ -1,29 +1,6 @@
-//! AuctionHouse.dbc — the **rates** each auction house charges: the deposit it takes to list an
-//! item, and the cut it takes out of a sale.
-//!
-//! One consumer, and it is why the table has to be loaded rather than hardcoded: the sell pane's
-//! `Deposit:` line has to show a number *before* the item is listed, so the client computes it
-//! locally — `GetAuctionHouseDepositRate()` is a straight read of [`AuctionHouseCatalog::deposit_percent`]
-//! at the house the session is talking to. Which house that is arrives on the wire:
-//! `MSG_AUCTION_HELLO`'s reply carries a `houseId` alongside the auctioneer guid, and it keys this
-//! table (decision 1511). Send the window the wrong id and the pane quietly shows Blackwater's 25%
-//! where a city auctioneer charges 5%.
-//!
-//! Record layout (7 rows in the shipped 5875 file, verified by reading it): `ID@0`, `FactionID@1`,
-//! `DepositPercent@2`, `CutPercent@3`, `Name_Lang@4..11`, `NameFlags@12`. Ids are 1..=7 and
-//! contiguous, but this is keyed rather than indexed for the reason every catalog here is keyed: a
-//! `houseId` off the wire is data, not an index we control.
-//!
-//! The shipped table is two tiers — the six faction houses charge **5% / 5%**, and Blackwater
-//! (id 7, the neutral goblin house at faction 369) charges **25% / 15%**. That spread is the whole
-//! economic point of the neutral auction house, so it is data worth reading rather than a constant
-//! worth inlining.
-//!
-//! **The rate is only half of the deposit.** The server's charge also scales by stack count, by
-//! duration, and by its own `Rate.Auction.Deposit` config multiplier, none of which live here; and
-//! the real client's displayed number is computed with an intermediate truncation the server's is
-//! not, so the two can disagree by a copper or two on cheap items. Decision 1511 records that
-//! divergence and what benilla does about it — this module only supplies the percentage.
+//! `AuctionHouse.dbc`, each auction house's deposit and cut rates. The server scales the deposit
+//! further by stack count, duration and `Rate.Auction.Deposit`, and the reference's displayed
+//! figure truncates midway where the server's does not, so they can differ by a copper or two.
 
 use std::collections::HashMap;
 
@@ -38,40 +15,37 @@ const AUCTION_HOUSE: &str = "DBFilesClient\\AuctionHouse.dbc";
 /// One auction house's row.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AuctionHouseInfo {
-    /// The faction this house serves (`369` = Booty Bay, the neutral house).
+    /// The faction this house serves (`369`, Booty Bay, for the neutral house).
     pub faction: u32,
-    /// Percent of the item's vendor sell price taken to list it, before stack/duration scaling.
+    /// Percent of the item's vendor sell price taken to list it, before stack and duration scaling.
     pub deposit_percent: u32,
     /// Percent of the winning bid taken out of the seller's proceeds.
     pub cut_percent: u32,
-    /// The house's name ("Stormwind Auction House"), as shipped.
+    /// The house's name (`"Stormwind Auction House"`).
     pub name: String,
 }
 
-/// AuctionHouse.dbc keyed by the `houseId` that `MSG_AUCTION_HELLO`'s reply carries.
+/// `AuctionHouse.dbc` keyed by the `houseId` that `MSG_AUCTION_HELLO`'s reply carries.
 pub struct AuctionHouseCatalog {
     houses: HashMap<u32, AuctionHouseInfo>,
 }
 
 impl AuctionHouseCatalog {
-    /// The whole row for `house_id`; `None` for an id with no row.
+    /// The row for `house_id`.
     pub fn get(&self, house_id: u32) -> Option<&AuctionHouseInfo> {
         self.houses.get(&house_id)
     }
 
-    /// The listing deposit rate, in percent — `GetAuctionHouseDepositRate()`'s answer. `None` for
-    /// an id with no row, which leaves the caller to decide (the sell pane shows no deposit rather
-    /// than inventing one).
+    /// The listing deposit rate in percent, `GetAuctionHouseDepositRate()`'s answer.
     pub fn deposit_percent(&self, house_id: u32) -> Option<u32> {
         self.houses.get(&house_id).map(|h| h.deposit_percent)
     }
 
-    /// The sale cut, in percent.
+    /// The sale cut in percent.
     pub fn cut_percent(&self, house_id: u32) -> Option<u32> {
         self.houses.get(&house_id).map(|h| h.cut_percent)
     }
 
-    /// Row count, for the load log.
     pub fn len(&self) -> usize {
         self.houses.len()
     }
@@ -94,7 +68,7 @@ fn auction_house_schema() -> Schema {
     s
 }
 
-/// Load AuctionHouse.dbc from the patch chain.
+/// Load `AuctionHouse.dbc` from the patch chain.
 pub fn load_auction_houses(chain: &mut Chain) -> Result<AuctionHouseCatalog> {
     let bytes = chain
         .read_file(AUCTION_HOUSE)
@@ -124,9 +98,6 @@ pub fn load_auction_houses(chain: &mut Chain) -> Result<AuctionHouseCatalog> {
 mod tests {
     use super::load_auction_houses;
 
-    /// The shipped 5875 table, read as data. The two tiers pinned here are the arithmetic the sell
-    /// pane rests on: every faction house is 5%/5%, and the neutral goblin house is 25%/15% — the
-    /// spread that makes cross-faction trading cost something. Skips without client data.
     #[test]
     fn the_shipped_houses_carry_the_two_rate_tiers() {
         let data = crate::wow_data_or_skip!();
@@ -135,7 +106,6 @@ mod tests {
 
         assert_eq!(cat.len(), 7, "the whole shipped table");
 
-        // The six faction houses: a flat 5% to list, 5% of the sale.
         for id in 1..=6 {
             let h = cat.get(id).unwrap_or_else(|| panic!("house {id}"));
             assert_eq!(h.deposit_percent, 5, "house {id} deposit");
@@ -146,14 +116,12 @@ mod tests {
             Some("Stormwind Auction House")
         );
 
-        // Blackwater — the neutral house, and the reason this is a table and not a constant.
         let neutral = cat.get(7).expect("house 7");
         assert_eq!(neutral.faction, 369, "Booty Bay");
         assert_eq!(neutral.deposit_percent, 25);
         assert_eq!(neutral.cut_percent, 15);
         assert_eq!(neutral.name, "Blackwater Auction House");
 
-        // Past the table: no row. The sell pane shows no deposit rather than inventing one.
         assert_eq!(cat.deposit_percent(8), None);
     }
 }
diff --git a/crates/benilla-formats/src/bank_bag_slot_prices.rs b/crates/benilla-formats/src/bank_bag_slot_prices.rs
index ca006bf0..5e048f43 100644
--- a/crates/benilla-formats/src/bank_bag_slot_prices.rs
+++ b/crates/benilla-formats/src/bank_bag_slot_prices.rs
@@ -1,11 +1,6 @@
-//! `BankBagSlotPrices.dbc` — the bank's purchase-ladder price table (decision 0604).
-//!
-//! 12 rows × 2 `u32` columns (`ID`, price in copper). Verified from the real 5875 `dbc.MPQ`
-//! (dumped this session): rows 1–6 = 1000, 10000, 100000, 250000, 500000, 1000000; rows 7–12 a
-//! `999999999` sentinel — only the first 6 bank bag slots are actually purchasable
-//! (`GetNumBankSlots()` reports `full` at 6; the sentinel rows exist but are unreachable).
-//! `CMSG_BUY_BANK_SLOT` carries no slot index — the server buys slot `purchased_count + 1` itself
-//! (`PLAYER_BYTES_2` byte 2) — so the client's only job is pricing that next slot.
+//! `BankBagSlotPrices.dbc`: the copper price of each bank bag slot. Rows 7-12 hold an unreachable
+//! `999999999` sentinel, as `GetNumBankSlots()` reports full at 6. `CMSG_BUY_BANK_SLOT` carries no
+//! index: the server buys the slot after the count in `PLAYER_BYTES_2` byte 2.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -20,10 +15,7 @@ const BANK_BAG_SLOT_PRICES: &str = "DBFilesClient\\BankBagSlotPrices.dbc";
 pub struct BankBagSlotPrices(HashMap<u32, u32>);
 
 impl BankBagSlotPrices {
-    /// The cost of the *next* bank bag slot, given `purchased_count` already bought (slot
-    /// `purchased_count + 1`, 1-based to match the DBC's row ids). `None` past the table — no row
-    /// for that slot number at all, not merely the sentinel (the 6-purchasable-slot cap is a data
-    /// fact, not something this reader hardcodes).
+    /// The price of slot `purchased_count + 1`; a sentinel row still reads as its price.
     pub fn next_slot_price(&self, purchased_count: u8) -> Option<u32> {
         self.0.get(&(u32::from(purchased_count) + 1)).copied()
     }
@@ -52,7 +44,6 @@ pub fn load_bank_bag_slot_prices(chain: &mut Chain) -> Result<BankBagSlotPrices>
     table_from(&bytes)
 }
 
-/// The parse itself, split from the chain read so the golden test drives the identical path.
 fn table_from(bytes: &[u8]) -> Result<BankBagSlotPrices> {
     let rs = parse(bytes, schema(), "BankBagSlotPrices")?;
     let mut prices = HashMap::with_capacity(rs.records().len());
@@ -68,8 +59,7 @@ fn table_from(bytes: &[u8]) -> Result<BankBagSlotPrices> {
 mod tests {
     use super::*;
 
-    /// A hand-built WDBC with the real 5875 rows (verified against `dbc.MPQ` this session,
-    /// decision 0604): 6 real prices then the 6-row `999999999` sentinel.
+    /// A WDBC with the shipped rows: six prices, then six `999999999` sentinel rows.
     fn synthesize() -> Vec<u8> {
         let rows: &[[u32; 2]] = &[
             [1, 1_000],
diff --git a/crates/benilla-formats/src/bin/benilla-extract/chaincensus.rs b/crates/benilla-formats/src/bin/benilla-extract/chaincensus.rs
index acd153b9..539cf43c 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/chaincensus.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/chaincensus.rs
@@ -1,23 +1,13 @@
-//! `chaincensus`: the whole-table view of the **beam/chain** system (decision 0955) — every
-//! `SpellVisualKit` that draws a `SpellChainEffects` beam, the row it names, and the spells that
-//! reach it through which lifecycle stage.
-//!
-//! The scope instrument for B161 ("Chain Lightning has no chain effect"). It answers, from the
-//! shipped table rather than from expectation, the two questions that turned that one report into
-//! a system: *which* spells are affected (not just Chain Lightning — every drain, funnel and eye
-//! beam in the game), and whether the small-int decode of `CharParamZero` is the real mechanism —
-//! because if it is, **every** live slot must resolve to a real row of an 18-row table and name a
-//! texture that matches the spell. A decode that were merely plausible would scatter.
-//!
-//! Read the `stage` column with the flag: `channel` kits ship flag 1, `cast` kits flag 0, and that
-//! flag — not the type key's name — is the only thing the client distinguishes.
+//! `chaincensus`: every `SpellVisualKit` that draws a `SpellChainEffects` beam, the row it names
+//! and the spells that reach it by stage. Each live slot must name one of the table's 18 rows, or
+//! the small-int decode of `CharParamZero` is wrong. The client tells the two kinds apart by the
+//! flag alone, never the type key: `channel` kits ship flag 1, `cast` kits flag 0.
 
 use std::collections::{BTreeMap, BTreeSet};
 
 use anyhow::Result;
 use benilla_formats::{char_proc_type, Chain, SpellVisualCatalog, VisualStages};
 
-/// A `SpellVisual` stage's column selector — one of the five lifecycle-kit fields.
 type StagePick = fn(&VisualStages) -> u32;
 
 const STAGES: [(&str, StagePick); 5] = [
@@ -35,7 +25,6 @@ struct Reach {
     stages: BTreeSet<&'static str>,
 }
 
-/// Every kit → the spells that reach it, and by which stage.
 fn kit_reachability(
     chain: &mut Chain,
     visuals: &SpellVisualCatalog,
diff --git a/crates/benilla-formats/src/bin/benilla-extract/charatlas.rs b/crates/benilla-formats/src/bin/benilla-extract/charatlas.rs
index 84b8caf8..8ff0b1e2 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/charatlas.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/charatlas.rs
@@ -1,26 +1,8 @@
-//! `charatlas` — composite one character's body atlas off the chain and report **what painted
-//! what**.
-//!
-//! The instrument the two "outfit texture" reports needed and nobody had. A dressed character's
-//! body is one 256² atlas of ten fixed tiles (the RF-0062 bbox table), and every visible defect in
-//! that class — a garment that stops early, a boot repainting a robe's hem, a bare band below the
-//! knee — is one tile receiving the wrong contribution. Reading that off a screenshot means
-//! guessing; reading it off the atlas means measuring.
-//!
-//! Three things it prints, all derived from the composite's own law
-//! ([`benilla_formats::equip_blits`]), never a second transcription:
-//!
-//! 1. **The plan** — every equipment contribution in blit order, with the file each name actually
-//!    resolved to (or `MISSING`, which is the silent skip that reads as "the texture ends early").
-//! 2. **The per-tile diff** vs the same character composited naked, per atlas ROW. A tile whose
-//!    lower rows go unpainted is a garment that stops early; a row count that changes when one slot
-//!    is added is that slot's footprint.
-//! 3. **The geosets** the same equipment selects, with the atlas rows each one samples — so "which
-//!    tile does the robe's skirt read?" is answered next to "what is in that tile".
-//!
-//! The tile↔geoset pairing is the whole diagnosis: geoset 1302 (the robe skirt) samples atlas rows
-//! 112–223, which straddles the LegUpper **and LegLower** tiles — so a boot's LegLower contribution
-//! lands on a robe's hem even though the boot's own geometry is disabled under a robe.
+//! `charatlas`: composite one character's body atlas off the chain and report what painted what:
+//! the equipment blits in [`benilla_formats::equip_blits`] order with the file each resolved to
+//! (`MISSING` leaves base skin), the rows each tile repaints against the naked body, and the
+//! geosets the equipment selects. Geoset 1302, the robe skirt, samples atlas rows 112-223 across
+//! the LegUpper and LegLower tiles, so a boot's LegLower blit shows on a robe's hem.
 
 use anyhow::{Context, Result};
 use benilla_formats::{
@@ -28,8 +10,7 @@ use benilla_formats::{
     CharSections, CharacterGeosets, EmblemLayer, EquipGeosets, GuildEmblem, ItemDisplay,
 };
 
-/// The ten atlas tiles by group, for the per-tile report — the five head/left-column ones included,
-/// so a head-section regression shows up in the same table as an equipment one.
+/// The body's ten fixed tiles in its 256² atlas (the reference's bbox table `0xb42450`).
 const TILES: [(&str, u32, u32, u32, u32); 10] = [
     ("g0 ArmUpper", 0, 0, 128, 64),
     ("g1 ArmLower", 0, 64, 128, 64),
@@ -43,13 +24,12 @@ const TILES: [(&str, u32, u32, u32, u32); 10] = [
     ("g7 Foot", 128, 224, 128, 32),
 ];
 
-/// The worn bodyslots the composite takes, in `equipment` order (bodyslot − 2).
+/// The worn bodyslots the composite takes, in `equipment` order (bodyslot - 2).
 const SLOT_NAMES: [&str; 8] = [
     "shirt", "chest", "belt", "pants", "boots", "wrist", "gloves", "tabard",
 ];
 
-/// One character appearance + what it wears — the whole input, so a report is reproducible from the
-/// command line that made it.
+/// One appearance and what it wears: the whole input, so its command line reproduces a report.
 pub struct Look {
     pub race: u8,
     pub sex: u8,
@@ -58,17 +38,13 @@ pub struct Look {
     pub facial_hair: u8,
     pub hair_style: u8,
     pub hair_color: u8,
-    /// The eight worn display ids in `equipment` order; `0` = the slot is empty.
+    /// The eight worn display ids in `equipment` order; 0 is an empty slot.
     pub slots: [u32; 8],
-    /// The wearer's guild tabard, or `None` for "no guild" — the same input the world composite
-    /// takes (decision 1704). It only paints over a tabard whose display asks for it, so passing
-    /// one without a guild-emblem tabard in the tabard slot is a no-op, on purpose.
+    /// The guild tabard; it paints only over a tabard display that asks for an emblem.
     pub emblem: Option<GuildEmblem>,
 }
 
-/// A BLP's header as the composite cares about it: the dimensions it blits at and the alpha depth
-/// that picks REPLACE (0) / 1-bit key (1) / blend (≥2) — the three that decide whether a
-/// contribution *covers* the one under it or lets it through.
+/// A BLP2's size and alpha depth, which picks the blit: replace (0), 1-bit key (1) or blend (2+).
 fn blp_shape(chain: &mut Chain, path: &str) -> Option<(u32, u32, u8)> {
     let b = chain.read_file(path).ok()?;
     if b.len() < 20 || &b[0..4] != b"BLP2" {
@@ -112,9 +88,7 @@ pub fn charatlas(chain: &mut Chain, look: &Look, out: Option<&std::path::Path>)
         }
     }
 
-    // (1) The plan — the composite's own order, with what each name resolved to. Worn garments and
-    // the guild tabard's three layers come through the same list, because they land in the same
-    // rows and the question ("what repainted this cell?") is the same one.
+    // (1) The plan, in the composite's order; worn garments and the three emblem layers share it.
     println!("\nequipment blits (by ascending cell; later covers earlier within a tile):");
     for step in equip_blits(&equipment, look.emblem, false) {
         let (_x, y, w, h) = equip_tile(step.layer).expect("layer < 8");
@@ -222,7 +196,6 @@ pub fn charatlas(chain: &mut Chain, look: &Look, out: Option<&std::path::Path>)
             })
             .collect();
         let rows = painted.iter().filter(|n| **n > 0).count();
-        // Where a tile stops is the diagnosis, so name the run rather than dumping 64 numbers.
         let first = painted.iter().position(|n| *n > 0);
         let last = painted.iter().rposition(|n| *n > 0);
         let span = match (first, last) {
@@ -235,18 +208,15 @@ pub fn charatlas(chain: &mut Chain, look: &Look, out: Option<&std::path::Path>)
         );
     }
 
-    // (3) The geosets this same equipment selects. The atlas rows each samples are the model's
-    // (`benilla-extract m2batch <the race model>` prints the UV extents these come from), so the
-    // two halves of "which art lands on which geometry" sit in one report.
+    // (3) The geosets this equipment selects; `m2batch` on the race model prints their UV extents.
     let mut eq = EquipGeosets::default();
     for (i, d) in equipment.iter().enumerate() {
         if let Some(d) = d {
             eq.bodyslots[i] = Some(d.geoset_groups);
         }
     }
-    // B3's gate is the ArmLower tile's occupancy — read off the same plan printed above (1864).
+    // The shirt-cuff geoset's gate is the ArmLower tile's occupancy, read off the same plan.
     eq.forearm_dressed = forearm_dressed(&equipment);
-    // Sorted + deduplicated at the source (`visible_geosets`).
     let ids = geosets.visible_geosets(look.race, look.sex, look.hair_style, look.facial_hair, &eq);
     println!("\nvisible geosets: {ids:?}");
 
diff --git a/crates/benilla-formats/src/bin/benilla-extract/charprocs.rs b/crates/benilla-formats/src/bin/benilla-extract/charprocs.rs
index b65b9e2e..310ec327 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/charprocs.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/charprocs.rs
@@ -1,22 +1,14 @@
-//! `charprocs`: census the `SpellVisualKit` **CharProc** columns (fields 15–34) — the character-half
-//! of a kit: what a kit does to the *body* (its alpha, its tint) rather than at an attach point.
-//!
-//! The scope instrument for the aura-state CharProc system (B114 — "Stealth shows nothing on the
-//! character"). It answers, from the shipped table rather than from expectation: which proc **types**
-//! exist, how many kits carry each, which **lifecycle stage** reaches them from a live spell, and —
-//! for the state stage, whose kits live for an aura's whole life — exactly which spells reach which
-//! proc with which parameter. A type that shows up only behind `cast`/`impact` is a discrete-play
-//! concern; a type behind `state` is an aura-lifetime one.
+//! `charprocs`: census the `SpellVisualKit` CharProc columns (fields 15-34), what a kit does to
+//! the body rather than at an attach point: which proc types exist, which stage reaches each from
+//! a live spell, and every state-stage proc, which lasts as long as its aura.
 
 use std::collections::{BTreeMap, BTreeSet};
 
 use anyhow::Result;
 use benilla_formats::{char_proc_type, Chain, SpellVisualCatalog, TrailProc, VisualStages};
 
-/// A `SpellVisual` stage's column selector — one of the five lifecycle-kit fields.
 type StagePick = fn(&VisualStages) -> u32;
 
-/// The five `SpellVisual` lifecycle stages, in field order — the label plus its column selector.
 const STAGES: [(&str, StagePick); 5] = [
     ("precast", |s| s.precast),
     ("cast", |s| s.cast),
@@ -25,7 +17,6 @@ const STAGES: [(&str, StagePick); 5] = [
     ("channel", |s| s.channel),
 ];
 
-/// A human label for the proc types benilla models by name.
 fn type_name(ty: i32) -> &'static str {
     match ty {
         char_proc_type::TINT => "TINT (body RGB)",
@@ -38,12 +29,12 @@ fn type_name(ty: i32) -> &'static str {
     }
 }
 
-/// Census every kit's CharProc slots, then reachability per stage, then the state-stage detail.
+/// Census the CharProc slots, their reach by stage, the state-stage procs and the weapon trails.
 pub fn run(chain: &mut Chain) -> Result<()> {
     let spells = benilla_formats::load_spell_catalog(chain)?;
     let visuals = benilla_formats::load_spell_visual_catalog(chain)?;
 
-    // 1. The raw table census: proc type → the kits carrying it.
+    // 1. Every proc type and the kits carrying it.
     let mut by_type: BTreeMap<i32, BTreeSet<u32>> = BTreeMap::new();
     let mut kits_with_any = 0usize;
     for kit_id in visuals.kit_ids() {
@@ -70,8 +61,7 @@ pub fn run(chain: &mut Chain) -> Result<()> {
         );
     }
 
-    // 2. Reachability: which stage of which spell's visual actually reaches each proc type. A kit
-    //    nobody's visual chain names is authored-but-dead as far as the client is concerned.
+    // 2. Each proc type's reach by stage from a live spell; a kit no visual names never plays.
     let mut by_stage: BTreeMap<(&str, i32), BTreeSet<u32>> = BTreeMap::new();
     // The state stage's detail rows: (spell id, name, kit, proc type, params[0]).
     let mut state_rows: Vec<(u32, String, u32, i32, f32)> = Vec::new();
@@ -107,7 +97,7 @@ pub fn run(chain: &mut Chain) -> Result<()> {
         );
     }
 
-    // 3. The state stage in full — these are the aura-lifetime procs, one line per (spell, proc).
+    // 3. Every state-stage proc, which lasts its aura's life, one line per spell and proc.
     println!(
         "\nSTATE-stage CharProcs — the aura-lifetime set ({} spell/proc pair(s)):",
         state_rows.len()
@@ -120,10 +110,7 @@ pub fn run(chain: &mut Chain) -> Result<()> {
         );
     }
 
-    // 4. The TRAIL set in full. Its shape is unlike the others': the proc carries no model and no
-    //    emitter, so a kit whose slot list is EMPTY still has a visual — and 18 of these are exactly
-    //    that, which is the single fact that decides whether the proc is worth building. The census
-    //    prints the slot count beside every row so that number stays checkable rather than quoted.
+    // 4. The weapon-trail kits; a trail needs no effect slot, so it draws on a kit with none.
     let trail_kits: BTreeMap<u32, TrailProc> = visuals
         .kit_ids()
         .filter_map(|id| Some((id, visuals.kit(id)?.trail_proc()?)))
@@ -160,10 +147,8 @@ pub fn run(chain: &mut Chain) -> Result<()> {
         let anim = kit.and_then(|k| k.anim_id);
         let [r, g, b] = trail.rgb();
         let spells = reach.get(kit_id);
-        // `CharParamOne` is printed even though the type-8 arm never reads it (`0x60d80a`'s three
-        // `_ftol`s take Zero/Two/Three only). wow-re's note states every shipped row carries
-        // `20.0` there; a census that hides the column cannot catch that being wrong, and it is —
-        // Sinister Strike's kit 399 carries 15.0.
+        // The type-8 arm never reads `CharParamOne` (`0x60d80a`), but it is printed: not every row
+        // carries 20.0 there, and Sinister Strike's kit 399 carries 15.0.
         let unread = kit
             .and_then(|k| {
                 k.char_procs()
@@ -188,8 +173,7 @@ pub fn run(chain: &mut Chain) -> Result<()> {
     Ok(())
 }
 
-/// The kits a spell's visual chain reaches, printed as one line per stage — the per-spell view of
-/// the census above (used by `spellvis`'s CharProc lines; kept here beside the type names).
+/// Print one kit's CharProc slots, one line each.
 pub fn print_kit_procs(visuals: &SpellVisualCatalog, kit_id: u32, indent: &str) {
     let Some(kit) = visuals.kit(kit_id) else {
         return;
diff --git a/crates/benilla-formats/src/bin/benilla-extract/glueextent.rs b/crates/benilla-formats/src/bin/benilla-extract/glueextent.rs
index 15070f2a..92cd5147 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/glueextent.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/glueextent.rs
@@ -1,14 +1,6 @@
-//! `glueextent` — how wide each shipped glue scene's art is, off the chain (decision 1619).
-//!
-//! The instrument behind the glue framing ceiling: for every `UI_*` diorama it prints the measured
-//! [`benilla_formats::ArtExtent`] (the same call the client makes at scene spawn), the authored
-//! 4:3 half-extents it is measured against, and the derived facts the framing law acts on — the
-//! window aspect at which the art runs out of **width** under 1587's hor+ (past it the law zooms
-//! in, holding the width) and the aspect at which it runs out of **height** for a narrow window.
-//!
-//! Beside the law's own reading (opaque batches, front faces) it prints two looser ones — opaque +
-//! alpha-tested, and every batch — so a scene whose measured edge looks wrong against a capture can
-//! be read for *which* batches sit at that edge without a second tool.
+//! `glueextent`: every shipped glue scene's [`benilla_formats::ArtExtent`], measured off the chain
+//! (the numbers `SHIPPED_GLUE_SCENES` transcribes), against its authored 4:3 half-extents, and the
+//! window aspects at which its art runs out of width and of height.
 
 use anyhow::{Context, Result};
 use benilla_formats::{
@@ -16,7 +8,7 @@ use benilla_formats::{
     parse_m2_render_submeshes, Chain, Coverage, CoverageReader, ModelBlend, GLUE_AUTHORED_ASPECT,
 };
 
-/// The seven shipped scenes: the login gate + the six race stages (Gnome→Dwarf, Troll→Orc share).
+/// The login gate and the six race stages (Gnome shares Dwarf's, Troll shares Orc's).
 const SCENES: [&str; 7] = [
     "MainMenu", "Human", "Orc", "Dwarf", "NightElf", "Scourge", "Tauren",
 ];
@@ -39,10 +31,8 @@ pub fn glueextent(chain: &mut Chain, batches: bool) -> Result<()> {
         };
         let t0 = authored_half_height(cam.fov);
         let h0 = t0 * GLUE_AUTHORED_ASPECT;
-        // The law's reading — every batch painting by its texels (the module's rule) — and the
-        // two readings on either side of it, so a scene whose measured edge looks wrong against
-        // a capture can be read for which rule moved it: opaque batches only, and every batch
-        // as if it painted fully.
+        // The texel rule the shipped table is measured by, bracketed by opaque batches only and
+        // by every batch painting fully.
         let mut reader = CoverageReader::new(chain);
         let mut paints: Vec<Option<Coverage>> = Vec::with_capacity(subs.len());
         for s in &subs {
@@ -76,8 +66,6 @@ pub fn glueextent(chain: &mut Chain, batches: bool) -> Result<()> {
             opaque_only,
             with_all,
         );
-        // Which batches sit at the measured edge: every opaque batch, with its blend, so a
-        // suspicious number can be traced to a card without a second command.
         let mut kinds = [0usize; 5];
         for s in &subs {
             kinds[match s.blend {
@@ -101,8 +89,7 @@ pub fn glueextent(chain: &mut Chain, batches: bool) -> Result<()> {
             cam.near_clip,
         );
         if batches {
-            // Every batch's footprint in the frame, in units of t0 (so `±1.333` is the authored
-            // 4:3 box's side, `±1.0` its top/bottom): which card sets the edge.
+            // Each batch's footprint in units of t0: ±1.333 is the 4:3 box's side, ±1.0 its top.
             println!(
                 "          {:>3} {:<9} {:<3} {:<6} {:>5} {:>5} {:>4}  {:>14}  {:>14}  tex",
                 "idx", "blend", "2s", "paints", "front", "back", "clip", "x'/t0", "y'/t0"
diff --git a/crates/benilla-formats/src/bin/benilla-extract/kitanim.rs b/crates/benilla-formats/src/bin/benilla-extract/kitanim.rs
index a75c714e..a7852231 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/kitanim.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/kitanim.rs
@@ -1,34 +1,15 @@
-//! `kitanim`: census the `SpellVisualKit` **animation** column (field 2) — the half of a kit that
-//! plays a clip on the unit's *own body*, as opposed to the attach-point effect models
-//! (`spellvis`), the CharProcs (`charprocs`) or the camera shake (`shakecensus`).
-//!
-//! The scope instrument for "the spell landed on me and my character did nothing". A kit's anim is
-//! the only part of a visual that can be *invisible by omission*: an effect model that fails to
-//! spawn leaves a trace line, while an anim that is never asked for, or is asked for and instantly
-//! overwritten, leaves nothing at all. So the population has to be read off the shipped table:
-//!
-//! - **by stage**, because the stage decides the lifetime. A `cast`/`impact` anim is a one-shot on
-//!   the caster/victim; a **`state`** anim belongs to an aura's whole life, which is a different
-//!   consumer entirely (`creature_anim::spell_visual::arm_aura_state_fx`'s slot watcher, not
-//!   `play_impact`).
-//! - **anim-only kits are called out**, because they are the class an "does this kit do anything?"
-//!   test drops. That test is the B114 shape: the aura-state watcher used to arm only on effect
-//!   models, so Stealth — whose whole visual is one CharProc — showed nothing. A state kit whose
-//!   whole visual is an *anim* fails the same way one level over.
-//! - **wound-branch ids are marked**, because 8/9/10 (`StandWound`/`CombatWound`/`CombatCritical`)
-//!   do not play as themselves: the client's kit player hands them to the severity-0 flinch
-//!   (`0x60f3b8: push 0; call 0x60ea70`), so they are a different mechanism wearing the same
-//!   column.
+//! `kitanim`: census the `SpellVisualKit` animation column (field 2), the clip a kit plays on the
+//! unit's own body, by stage: a `cast` or `impact` anim is a one-shot on the caster or victim, a
+//! `state` anim lasts the aura's life. Anim-only kits are marked, as a consumer keyed on effect
+//! models never sees them.
 
 use std::collections::{BTreeMap, BTreeSet};
 
 use anyhow::Result;
 use benilla_formats::{AnimDataCatalog, Chain, VisualStages};
 
-/// A `SpellVisual` stage's column selector — one of the five lifecycle-kit fields.
 type StagePick = fn(&VisualStages) -> u32;
 
-/// The five `SpellVisual` lifecycle stages, in field order — the label plus its column selector.
 const STAGES: [(&str, StagePick); 5] = [
     ("precast", |s| s.precast),
     ("cast", |s| s.cast),
@@ -37,14 +18,13 @@ const STAGES: [(&str, StagePick); 5] = [
     ("channel", |s| s.channel),
 ];
 
-/// The kit-player's wound branch: ids 8–10 are handed to the severity-0 flinch instead of being
-/// played as themselves (`0x60f3b8`), so they are counted apart from the real body clips.
+/// Ids 8-10 (`StandWound`, `CombatWound`, `CombatCritical`): the kit player hands them to the
+/// severity-0 flinch instead of playing them (`0x60f3b8: push 0; call 0x60ea70`).
 fn is_wound_id(id: u16) -> bool {
     (8..=10).contains(&id)
 }
 
-/// One state-stage kit's row: everything that decides whether a consumer keyed on effect models
-/// alone would see it.
+/// One state-stage kit: what decides whether a consumer keyed on effect models sees it.
 struct StateKit {
     anim: u16,
     slots: usize,
@@ -55,19 +35,16 @@ struct StateKit {
 }
 
 impl StateKit {
-    /// Nothing but the anim — the class an effects/sound/proc test drops on the floor.
     fn anim_only(&self) -> bool {
         self.slots == 0 && !self.world && !self.sound && self.procs == 0
     }
 }
 
-/// Census the anim column: the raw table, then reachability per stage, then the two stages whose
-/// consumers differ — `state` (aura lifetime) in full, `impact` (the victim's one-shot) ranked.
+/// Census the anim column, its reach by stage, every `state` kit and the top `impact` kits.
 pub fn run(chain: &mut Chain) -> Result<()> {
     let spells = benilla_formats::load_spell_catalog(chain)?;
     let visuals = benilla_formats::load_spell_visual_catalog(chain)?;
-    // `AnimationData.dbc` is only the naming column here — a missing table degrades to bare ids
-    // rather than failing the census (the same optional shape every DBC consumer takes).
+    // `AnimationData.dbc` only names the ids, so a missing table prints `?` rather than failing.
     let anims = benilla_formats::load_anim_data_catalog(chain).ok();
     let name = |id: u16| -> String {
         anims
@@ -77,7 +54,7 @@ pub fn run(chain: &mut Chain) -> Result<()> {
             .to_string()
     };
 
-    // 1. The raw table: which anim ids the shipped kits ask for at all.
+    // 1. Which anim ids the shipped kits ask for.
     let mut by_anim: BTreeMap<u16, BTreeSet<u32>> = BTreeMap::new();
     for kit_id in visuals.kit_ids() {
         if let Some(anim) = visuals.kit(kit_id).and_then(|k| k.anim_id) {
@@ -104,8 +81,7 @@ pub fn run(chain: &mut Chain) -> Result<()> {
         );
     }
 
-    // 2. Reachability: a kit no spell's visual chain names is authored-but-dead, and the STAGE is
-    //    what picks the consumer, so both are counted here.
+    // 2. The reach by stage; a kit no spell's visual names never plays.
     let mut stage_kits: BTreeMap<&str, BTreeSet<u32>> = BTreeMap::new();
     let mut stage_spells: BTreeMap<&str, BTreeSet<u32>> = BTreeMap::new();
     let mut state: BTreeMap<u32, StateKit> = BTreeMap::new();
@@ -157,8 +133,7 @@ pub fn run(chain: &mut Chain) -> Result<()> {
         );
     }
 
-    // 3. The STATE stage in full — the aura-lifetime set, which is the whole reason this census
-    //    exists. `ANIM-ONLY` marks the kits an effects/sound/proc arm test never sees.
+    // 3. Every state kit; `ANIM-ONLY` marks those with no effect slot, world effect, sound or proc.
     let state_spells: usize = state
         .values()
         .flat_map(|k| k.spells.iter())
@@ -194,8 +169,7 @@ pub fn run(chain: &mut Chain) -> Result<()> {
         }
     }
 
-    // 4. The IMPACT stage, ranked — the VICTIM's body one-shot, the other consumer. Kept to a
-    //    ranked list rather than spelled out: the population is the whole damage table.
+    // 4. The impact kits, the victim's one-shot, ranked by spell count.
     let impact_spells: usize = impact
         .values()
         .flat_map(|(_, s)| s.iter())
diff --git a/crates/benilla-formats/src/bin/benilla-extract/m2dump.rs b/crates/benilla-formats/src/bin/benilla-extract/m2dump.rs
index 8b14f941..1ba48336 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/m2dump.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/m2dump.rs
@@ -1,7 +1,4 @@
-//! Per-model M2 dump printers: `m2coll`, `m2seq`, `m2attach`, `m2anim`, `m2bones`, `m2batch` —
-//! the single-model diagnostics that read one `.m2` and print everything a given concern
-//! (collision hull, sequences, attachment points, animation channels, bone table, render
-//! batches) actually carries.
+//! The single-model M2 dumps: each reads one `.m2` and prints all it carries for one concern.
 
 use anyhow::{Context, Result};
 use benilla_formats::{Chain, M2AnimSummary};
@@ -40,10 +37,8 @@ pub fn m2coll(chain: &mut Chain, internal_path: &str) -> Result<()> {
     Ok(())
 }
 
-/// Dump every sequence's EVENT keyframes: time (s from sequence start), 4CC ident, payload.
-/// The event-order instrument (decision 0279): on attack clips, whether `$CPP` (the victim
-/// defense dispatch) precedes `$AH0-3`/`$CAH` (the impact dispatch) decides which of the two
-/// mutually-exclusive victim reactions the shared swing record feeds.
+/// Dump every sequence's event keyframes. On an attack clip, whether `$CPP` (the victim's defense)
+/// precedes `$AH0-3`/`$CAH` (the impact) picks which exclusive reaction the swing record feeds.
 pub fn m2events(chain: &mut Chain, internal_path: &str) -> Result<()> {
     let name = normalize(internal_path);
     let data = chain
@@ -83,19 +78,13 @@ pub fn m2seq(chain: &mut Chain, internal_path: &str) -> Result<()> {
         .read_file(&name)
         .with_context(|| format!("reading '{name}' from chain"))?;
     let seqs = benilla_formats::parse_m2_animations(&data);
-    // `band` is the sequence's absolute window on the model's global keyframe timeline: every
-    // non-global-sequence track selects its keys from it, so it is what says whether a track is
-    // actually keyed HERE or is holding a clamped value from some other sequence's band.
-    // NB `idx` is this list's index, not the file's: zero-duration sequences are dropped.
+    // `band` is the window on the keyframe timeline every non-global-sequence track keys in. `idx`
+    // is not the file slot: zero-duration sequences are dropped.
     println!(
         "idx  anim   mode   dur(s)   mspd  blend   band(ms)          freq  replay   bones   keys"
     );
     for (i, s) in seqs.iter().enumerate() {
-        // How much data the sequence's own time band actually holds: bones with any
-        // keyed track, and total keys across T/R/S (clamp constants included — a bone
-        // unkeyed in this band pins to its nearest authored key, see `read_bone_track`).
-        // Uneven coverage across same-id variations is what exposed the task-#14 tilt
-        // (HumanMale Stand idx 136 keys 13 fewer bones than the head).
+        // Bones with any keyed track in this band, and total T/R/S keys, clamp constants included.
         let bones = s
             .bones
             .iter()
@@ -111,14 +100,11 @@ pub fn m2seq(chain: &mut Chain, internal_path: &str) -> Result<()> {
             s.anim_id,
             if s.looping { "loop " } else { "clamp" },
             s.duration,
-            // `mspd` = the sequence's authored design movement speed (yd/s) — the DIVISOR of the
-            // locomotion playback rate (`speed / (mspd · |modelScale|)`, wow-re `0x5fe2f0`
-            // @0x5fe4be..0x5fe550). `0.00` ⇒ not a locomotion sequence, so it plays at rate 1×.
+            // `mspd`: the authored move speed (yd/s) dividing the locomotion rate,
+            // `speed / (mspd · |modelScale|)` (`0x5fe2f0` at 0x5fe4be..0x5fe550); 0 plays at 1×.
             s.move_speed,
-            // `blend` = the sequence's authored blend-IN time (s) — how long the client cross-fades
-            // from the outgoing pose into this one on a blended arm (op4 `blendFlag != 0`, the
-            // `+0x98 -> +0xc4` snapshot decayed over `1/blendTime`). `0.000` = an instant cut, and
-            // that is what a doll's turn looks like without it.
+            // `blend`: the blend-in time (s) the client cross-fades over on a blended arm (op4
+            // `blendFlag != 0`, the `+0x98 -> +0xc4` snapshot decayed over `1/blendTime`); 0 cuts.
             s.blend_time,
             s.start_ms,
             s.end_ms,
@@ -138,9 +124,7 @@ pub fn m2attach(chain: &mut Chain, internal_path: &str) -> Result<()> {
         .read_file(&name)
         .with_context(|| format!("reading '{name}' from chain"))?;
     let attachments = benilla_formats::parse_m2_attachments(&data)?;
-    // The position is raw WoW model space (X forward, Y left, Z up), as the M2 stores it — "where
-    // on the model does this rider actually sit?" needs it as much as the bone does: an item glow
-    // hangs on ids 0..4, spread along a weapon's length (decision 0805).
+    // Raw WoW model space (X forward, Y left, Z up); item glows hang on ids 0..4 along a weapon.
     println!("id  bone  position (WoW model space)");
     for a in &attachments {
         let [x, y, z] = a.position;
@@ -150,8 +134,6 @@ pub fn m2attach(chain: &mut Chain, internal_path: &str) -> Result<()> {
     Ok(())
 }
 
-/// One texture-transform track line for the `m2anim` dump: key count, interp/gseq tags, and the
-/// first/last keys (enough to read a scroll direction + rate off a waterfall).
 fn print_txfm_track<V: std::fmt::Debug + Copy + PartialEq>(name: &str, t: &benilla_m2::M2Track<V>) {
     if t.keys.is_empty() {
         println!("    {name}: -");
@@ -172,7 +154,6 @@ fn print_txfm_track<V: std::fmt::Debug + Copy + PartialEq>(name: &str, t: &benil
     );
 }
 
-/// The `m2anim` subcommand's dump — one section per channel family.
 fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
     println!("sequences: {}", s.sequence_count);
     println!(
@@ -204,10 +185,6 @@ fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
         s.texture_transform_count
     );
     println!("particle emitters:  {}", s.particle_emitter_count);
-    // The full defs (pos/blend/texture/shape/rate-keys/ramps) alongside the summary's bone links —
-    // which emitter is the flame and which the glow is unreadable from bone+flags alone (the
-    // blood-spurt starburst diagnosis, decision 0141; a flame that "doesn't burn" is usually
-    // visible right here: an unresolved texture, or a burst rate track whose first key is 0).
     let defs = benilla_formats::parse_m2_particle_emitters(bytes).unwrap_or_default();
     for (i, e) in s.emitter_bones.iter().enumerate() {
         println!(
@@ -222,13 +199,9 @@ fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
             }
         );
         let Some(d) = defs.get(i) else { continue };
-        // The emission MODEL first: a BURST emitter fires one ftol(rate) puff at its rate edge
-        // and never pours — reading its keys as a continuous rate is the exact misdiagnosis
-        // behind the Eviscerate 0.5s-vs-2s gap (wow-re part-emission-burst-flag.md).
+        // A burst emitter fires one `ftol(rate)` puff at its rate edge and never pours
+        // (`0x718ec8` → `0x7b5550`).
         let burst = if d.burst() { "BURST " } else { "" };
-        // PER-SEQUENCE timing (the runtime's actual sampling unit — the old print showed the two
-        // tracks rebased onto sequence 0's band, which read as authoritative and was exactly the
-        // B27 misparse). The quiet case stays quiet: one constant rate, no gate anywhere.
         let views = d.timing.slot_views();
         let rate = match d.timing.constant_rate() {
             Some(r) => format!("{burst}rate {r:.1}/s"),
@@ -247,10 +220,9 @@ fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
                 format!("{burst}rate/seq [{}]", per.join("  "))
             }
         };
-        // The enabled gate, per sequence slot (seconds from the slot's band start) — a one-shot
-        // effect's choreography, and a state GameObject's "which clips actually fire this".
+        // The enabled gate per sequence slot, in seconds from the slot's band start.
         let rate = if views.iter().all(|(_, _, e)| e.is_none()) {
-            rate // no gate authored anywhere (the overwhelmingly common shape) — no noise
+            rate // no gate authored anywhere, the common case
         } else {
             let per: Vec<String> = views
                 .iter()
@@ -273,8 +245,7 @@ fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
                 .collect();
             format!("{rate}  enabled/seq [{}]", per.join("  "))
         };
-        // A tail's streak length is |velocity|·tail_time — without it "how long is this
-        // streak" needs a hand-parse of the raw record (the Eviscerate diagnosis gap).
+        // A tail's streak length is |velocity| · tail_time.
         let tail = if d.head_tail >= 1 {
             format!(
                 "  tail {:.2}s{}",
@@ -288,10 +259,7 @@ fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
         } else {
             String::new()
         };
-        // The parameter channels sample per frame ([`benilla_formats::EmitParams`]); the compact
-        // line shows their opening values, and any channel that actually MOVES prints its full
-        // keyed ramp below — the view whose absence hid Frost Nova's 0.19 → 13.2 yd emission-
-        // radius ride behind a flat "radius [0.19..0.19]" (decision 0844).
+        // Each parameter channel's opening value; one that moves prints its keyed ramp below.
         let now = d.params.sample(None, 0.0, 0.0);
         println!(
             "             {:?} {:?} {}  {rate}  life {:.2}s  speed {:.2}  grav {:.2}  drag {:.1}{tail}  twinkle [{:.2}..{:.2}] spd {:.1} pct {:.2}  spin {:.2}",
@@ -323,16 +291,15 @@ fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
                 }
             }
         }
-        // The kernel spread (wow-re part-shape-kernels): a sphere's ranges are latitude/longitude
-        // about +X (area = min/max shell radius); a plane's are the ±θ/±φ cone about +Z (area =
-        // the spawn rectangle). `(lat ±π, lon ±0)` reads directly as the edge-on ring family.
+        // The kernel spread (`0x7b8d70`, `0x7b8890`): a sphere's ranges are latitude and longitude
+        // about +X, its area the shell radii; a plane's a cone about +Z, its area the rectangle.
         let spread = match d.shape {
             benilla_formats::ParticleShape::Sphere => format!(
                 "radius [{:.2}..{:.2}] lat ±{:.2} lon ±{:.2}",
                 now.area_length, now.area_width, now.vertical_range, now.horizontal_range
             ),
-            // Spline repurposing (wow-re part-spline-file-layout): area = tMin/tMax,
-            // vRange = tangent-spin ψ, hRange = scatter.
+            // A spline repurposes them (loader `0x70fa5e`-`0x70fae5`): area is tMin/tMax, vRange
+            // the tangent spin, hRange the scatter.
             benilla_formats::ParticleShape::Spline => match &d.spline {
                 Some(s) => format!(
                     "spline {} pts [{:.2} {:.2} {:.2} ..], t [{:.2}..{:.2}] spin ±{:.2} scatter {:.2}",
@@ -357,16 +324,14 @@ fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
         } else {
             String::new()
         };
-        // The per-emitter model references: geometry (3-D model particles) and recursion
-        // (child emitters).
         if let Some(g) = &d.geometry_model {
             println!("             MODEL-PARTICLES: {g}");
         }
         if let Some(r) = &d.recursion_model {
             println!("             CHILD-EMITTERS: {r}");
         }
-        // The emitter-motion terms (wow-re part-emitter-motion): the follow-delta response
-        // line's authored (speed → fraction) samples, and the velocity-inherit scale.
+        // The emitter-motion terms (`0x7b5230`): the follow-delta response's (speed, fraction)
+        // samples and the velocity-inherit scale.
         let motion = match (d.follow_emitter(), d.inherits_emitter_motion()) {
             (false, false) => String::new(),
             (f, i) => {
@@ -400,9 +365,7 @@ fn print_m2anim_summary(s: &M2AnimSummary, bytes: &[u8]) {
         );
     }
     println!("ribbon emitters:    {}", s.ribbon_emitter_count);
-    // A keyed look track prints its full `(ms, value)` ramp — the value[0]-only display once
-    // masked HolySmite's slash ribbons (height keyed 0 → 0.167 → 0 printed as `+0.00`, reading
-    // as "no ribbon" when the model authors a flare).
+    // A keyed ribbon track prints its whole `(ms, value)` ramp; its first value alone can read 0.
     let scalar = |t: &benilla_formats::ValueTrack| -> String {
         match t.keys.len() {
             0 | 1 => format!("{:.2}", t.first()),
@@ -466,8 +429,6 @@ pub fn m2anim(chain: &mut Chain, internal_path: &str) -> Result<()> {
         .with_context(|| format!("parsing M2 animation summary '{name}'"))?;
     print_m2anim_summary(&summary, &data);
 
-    // Texture-transform detail (0130 phase 3 grounding): the parsed TRS tracks plus the
-    // batch → lookup → transform wiring, straight from the full parser.
     let fmt = benilla_m2::parse_m2(&mut std::io::Cursor::new(&data[..]))
         .with_context(|| format!("parsing M2 '{name}'"))?;
     let m = fmt.model();
@@ -491,18 +452,13 @@ pub fn m2anim(chain: &mut Chain, internal_path: &str) -> Result<()> {
             }
         }
     }
-    // Color-alpha + texture-weight keys in full (they're tiny scalar tracks): the "how does this
-    // effect fade" instrument — the UI cooldown model's finish-flash ramp was pinned from exactly
-    // this dump (decision 0137 phase 4).
     if !m.color_alpha_tracks.is_empty() {
         println!("=== color alpha tracks (per M2Color) ===");
         for (i, t) in m.color_alpha_tracks.iter().enumerate() {
             println!("  color {i}: interp {}, keys {:?}", t.interp, t.keys);
         }
     }
-    // The RGB half of the same M2Colors: the per-batch tint the client multiplies into the vertex
-    // colour. An effect that reads white where the reference reads coloured is usually visible
-    // right here (the Frost Nova purple-mist diagnosis).
+    // The M2Colors' RGB half: the per-batch tint the client multiplies into the vertex colour.
     if m.color_rgb_tracks.iter().any(|t| t.keys.len() > 1) {
         println!("=== color rgb tracks (per M2Color) ===");
         for (i, t) in m.color_rgb_tracks.iter().enumerate() {
@@ -524,9 +480,6 @@ pub fn m2anim(chain: &mut Chain, internal_path: &str) -> Result<()> {
             println!("  weight {i}: interp {}, keys {:?}", t.interp, t.keys);
         }
     }
-    // Bone SCALE keys per sequence — the "how does this element grow" instrument (the cooldown
-    // star's finish-flash pulse is a bone-scale curve, decision 0263's INTERIM). Scale-keyed
-    // bones only; effect/UI models keep this tiny.
     let seqs = benilla_formats::parse_m2_animations(&data);
     let any_scaled = seqs
         .iter()
@@ -560,12 +513,8 @@ pub fn m2bones(chain: &mut Chain, internal_path: &str) -> Result<()> {
         .with_context(|| format!("parsing M2 '{name}'"))?;
     let m = fmt.model();
     let seqs = benilla_formats::parse_m2_animations(&data);
-    // `ign` is `flags & 0x7` spelled out — which of the parent's Translate/Scale/Rotate this bone
-    // REFUSES, taking the model root's instead (decision 0945). The raw flags hex could always be
-    // read for it and never was: three billboard rounds and a mount round each looked at
-    // `RidingHorse` bone 30's `0x00000006` and none read it as "the saddle discards the gallop",
-    // which decision 0932 then measured as a 21° rider swing and called faithful. A bone-table
-    // dump exists to answer "what does this bone actually inherit"; now it says so in words.
+    // `ign` spells out `flags & 0x7`: which of its parent's translation, scale and rotation the
+    // bone refuses, taking the model root's instead.
     println!(
         "idx  keybone  flags       bb  ign  parent  pivot                       \
          keyed (seq[idx] T/R/S counts)"
@@ -604,9 +553,7 @@ pub fn m2bones(chain: &mut Chain, internal_path: &str) -> Result<()> {
             b.pivot.z,
             keyed.join(" "),
         );
-        // Small tracks get their actual key values — two sequences can share a key COUNT while
-        // holding different values (the questgiver-marker seq 0 vs 190 lesson: counts alone
-        // mislabeled them "the same").
+        // Small tracks print their key values: equal key counts can hide different values.
         for (si, s) in seqs.iter().enumerate() {
             let Some(bk) = s.bones.iter().find(|bk| bk.bone as usize == i) else {
                 continue;
@@ -619,17 +566,9 @@ pub fn m2bones(chain: &mut Chain, internal_path: &str) -> Result<()> {
                     .collect();
                 println!("       seq{si} (anim {}) T: {}", s.anim_id, keys.join("  "));
             }
-            // Rotation keys as axis-angle (model-space WoW axes, Z up) — the "which way does
-            // this element actually turn" instrument: an emitter/billboard orientation bug
-            // needs the spin axis as ground truth, which a bare key COUNT never shows. Small
-            // tracks print every key; a long track (a swirl/rotor loop) prints first/last plus
-            // the axis of the first key-to-key increment — the spin axis itself.
-            //
-            // A long track also prints `swing` — the largest angle any key makes with the first,
-            // i.e. the track's actual AMPLITUDE. `step` is only the first increment, so a summary
-            // without this cannot answer "how far does this bone swing", which is the question a
-            // "does the rider inherit the mount's gallop pitch" investigation puts to it. Reading
-            // `step` as the amplitude under-reports a 20° swing as 1.5°.
+            // Rotation keys as axis-angle (WoW model axes, Z up). A long track prints its first and
+            // last keys, `step` (the first increment, whose axis is the spin axis) and `swing` (the
+            // largest angle any key makes with the first, the amplitude `step` is not).
             if !bk.rotation.is_empty() {
                 let aa = |q: &[f32; 4]| {
                     let w = q[3].clamp(-1.0, 1.0);
@@ -653,7 +592,7 @@ pub fn m2bones(chain: &mut Chain, internal_path: &str) -> Result<()> {
                     let (t0, q0) = &bk.rotation[0];
                     let (_t1, q1) = &bk.rotation[1];
                     let (tn, qn) = bk.rotation.last().unwrap();
-                    // increment = q1 · q0⁻¹ — its axis is the track's spin axis.
+                    // increment = q1 · q0⁻¹, whose axis is the spin axis.
                     let inv0 = [-q0[0], -q0[1], -q0[2], q0[3]];
                     let inc = [
                         q1[3] * inv0[0] + q1[0] * inv0[3] + q1[1] * inv0[2] - q1[2] * inv0[1],
@@ -661,9 +600,8 @@ pub fn m2bones(chain: &mut Chain, internal_path: &str) -> Result<()> {
                         q1[3] * inv0[2] + q1[0] * inv0[1] - q1[1] * inv0[0] + q1[2] * inv0[3],
                         q1[3] * inv0[3] - q1[0] * inv0[0] - q1[1] * inv0[1] - q1[2] * inv0[2],
                     ];
-                    // The amplitude: the largest angle any key makes with the first. `2·acos|⟨qi,q0⟩|`
-                    // is the geodesic angle between two unit quats, sign-folded so a double-cover
-                    // flip doesn't read as a 360° swing.
+                    // `2·acos|⟨qi,q0⟩|` is the angle between two unit quats, sign-folded so a
+                    // double-cover flip does not read as a 360° swing.
                     let swing = bk
                         .rotation
                         .iter()
@@ -682,12 +620,6 @@ pub fn m2bones(chain: &mut Chain, internal_path: &str) -> Result<()> {
                     );
                 }
             }
-            // Scale keys. A bone whose ONLY channel is scale — the pulsing card a spell
-            // effect hangs off a billboard, the freezing trap's ice shard — printed nothing
-            // here at all: the header row said `S2` and no detail line followed, so "how big
-            // does this thing actually get, and in which sequence" could not be answered from
-            // the dump. Non-uniform scale is exactly the interesting case (a square card
-            // stretched into a column), so all three components print.
             if !bk.scale.is_empty() && bk.scale.len() <= 8 {
                 let keys: Vec<String> = bk
                     .scale
@@ -702,14 +634,7 @@ pub fn m2bones(chain: &mut Chain, internal_path: &str) -> Result<()> {
     Ok(())
 }
 
-/// Dump an M2's render batches as the renderer sees them, preceded by the model-level material
-/// state the **static visibility cull** reads (wow-re `m2-alpha-combine-cull`: a batch is skipped
-/// when `colorAlpha · transparencyWeight ≤ 0`). Batches this dump *lists* are ones that survived
-/// that cull — when one of them turns out to be a stray primitive in game, these tables are where
-/// the answer has to be, so they print together.
-/// The facing readout for one batch (see the call site in [`m2batch`]): the first triangle's
-/// winding normal, the mean authored vertex normal, and their dot. `None` for a batch with no
-/// triangle to measure.
+/// One batch's facing: its first triangle's winding normal, its mean vertex normal and their dot.
 fn winding(s: &benilla_formats::RenderSubmesh) -> Option<String> {
     let tri = s.indices.get(..3)?;
     let p = |i: u32| s.positions.get(i as usize).copied();
@@ -724,8 +649,7 @@ fn winding(s: &benilla_formats::RenderSubmesh) -> Option<String> {
     };
     let norm = |v: [f32; 3]| {
         let l = (v[0] * v[0] + v[1] * v[1] + v[2] * v[2]).sqrt();
-        // A degenerate (zero-area) triangle has no direction to report — say so rather than
-        // printing NaNs that read like data.
+        // A zero-area triangle has no direction; say so rather than print NaNs that read as data.
         (l > 1e-9).then(|| [v[0] / l, v[1] / l, v[2] / l])
     };
     let facet = norm(cross(sub(b, a), sub(c, a)));
@@ -741,10 +665,8 @@ fn winding(s: &benilla_formats::RenderSubmesh) -> Option<String> {
         (Some(f), Some(n)) => format!("{:+.2}", f[0] * n[0] + f[1] * n[1] + f[2] * n[2]),
         _ => "-".to_string(),
     };
-    // A billboard card authored back-to-front against the law's `+X`-at-the-viewer: the renderer
-    // turns its normals round so the card is lit off the face it presents (decision 0788). `vnorm`
-    // alone cannot answer this — it is the MEAN, so a batch whose normals cancel reads the same as
-    // one flat plane — hence the shape's own verdict here rather than an eyeball off the numbers.
+    // A billboard card wound away from its `+X` viewer: the renderer turns its normals round so it
+    // is lit off the face it presents. The mean `vnorm` cannot show this, so the shape decides.
     let lit_face = if s.billboard_card_faces_away() {
         "  LIT-FACE-FLIP"
     } else {
@@ -757,23 +679,13 @@ fn winding(s: &benilla_formats::RenderSubmesh) -> Option<String> {
     ))
 }
 
-/// Which BONES a batch's vertices actually ride, and — for a billboard batch — whether the batch is
-/// a rigid card at all.
-///
-/// The reference skins **per vertex**: every vertex is placed by its own (up to four) bone matrices
-/// and weights, so a batch that straddles a billboard bone and a static one *deforms* — the static
-/// end stays welded to the body while the billboard end swings to the camera. benilla instead splits
-/// a batch into per-billboard-bone submeshes keyed on each **triangle's first vertex** and rotates
-/// each group rigidly about that bone's pivot. The two agree only when a group's vertices are all
-/// 100% on the one billboard bone; where they aren't, we tear geometry off the model that the
-/// reference keeps attached. `MIXED` is exactly that condition, and `SPLIT-W` the softer form (a
-/// vertex blended across bones, which a rigid group cannot express at all).
+/// The bones a batch's vertices ride and, for a billboard batch, whether it is a rigid card. The
+/// reference skins each vertex through its own bone weights, so only geometry wholly on the
+/// billboard bone turns as one card: `MIXED` counts vertices off it, `SPLIT-W` blended vertices.
 fn skin_census(s: &benilla_formats::RenderSubmesh) -> Option<String> {
     if s.joints.is_empty() {
         return None;
     }
-    // Vertices per PRIMARY bone (`bone_indices[0]` — the key our batch split groups on), in
-    // ascending bone order so two models' lines compare by eye.
     let mut per_bone: std::collections::BTreeMap<u16, usize> = std::collections::BTreeMap::new();
     for j in &s.joints {
         *per_bone.entry(j[0]).or_default() += 1;
@@ -802,9 +714,7 @@ fn skin_census(s: &benilla_formats::RenderSubmesh) -> Option<String> {
     if split > 0 {
         verdict.push_str(&format!("  SPLIT-W: {split} verts blended across bones"));
     }
-    // The distinct skin TUPLES with their vertex counts — a rigid group is one tuple at weight 1;
-    // anything else names the seam the split has to cut along. Capped so a 300-vert creature batch
-    // can't drown the dump (the question only ever has a handful of answers on a card-sized batch).
+    // Distinct skin tuples and their vertex counts, capped at 8; a rigid card is one at weight 1.
     let mut tuples: std::collections::BTreeMap<String, usize> = std::collections::BTreeMap::new();
     for (j, w) in s.joints.iter().zip(&s.weights) {
         let key = (0..4)
@@ -871,13 +781,10 @@ pub fn m2batch(chain: &mut Chain, internal_path: &str) -> Result<()> {
             m.transparency_lookup,
         );
         if let Ok(skin) = m.parse_embedded_skin(&data, 0) {
-            // One line per batch, because the batch → material/track mapping is the thing an alpha
-            // question turns on and it is NOT inferable from the render flags: `mat` indexes the
-            // materials list above, `color` the colour-alpha tracks (`ffff` = none), and `weight`
-            // indexes `transLookup` → the transparency track. The verified combine is
+            // `mat` indexes the materials above, `color` the colour-alpha tracks (`ffff` for none)
+            // and `weight` `transLookup`. The reference skips a batch whose
             // `A = instanceAlpha × colors[color].alpha × transparency[transLookup[weight]].weight`
-            // (wow-re `m2-alpha-combine-cull.md`), so these three name every input to a batch's
-            // visibility.
+            // is 0 or less (`0x707680`).
             println!("skin batches ({}):", skin.batches().len());
             for (i, b) in skin.batches().iter().enumerate() {
                 let w = m
@@ -919,9 +826,7 @@ pub fn m2batch(chain: &mut Chain, internal_path: &str) -> Result<()> {
         if s.billboard.is_some() {
             flags.push("BILLBOARD");
         }
-        // This batch's texcoords are GENERATED (`texture_unit_lookup > 2`), so the `uv` line below
-        // reports the authored UVs the runtime does *not* read — a degenerate span there is the
-        // asset saying "supply these", not a defect in the model.
+        // Texcoords generated at runtime (`texture_unit_lookup > 2`): the `uv` line is unused.
         if s.env_map {
             flags.push("ENV-MAP");
         }
@@ -931,16 +836,11 @@ pub fn m2batch(chain: &mut Chain, internal_path: &str) -> Result<()> {
         if s.uv_anim.is_some() {
             flags.push("uv-anim");
         }
-        // A character runtime slot (body atlas / hair / object / extra skin) has no embedded path —
-        // name the slot rather than a misleading bare NONE.
         let tex = match (&s.texture, s.char_slot) {
             (Some(t), _) => t.clone(),
             (None, Some(slot)) => format!("<char:{slot:?}>"),
             (None, None) => "NONE".into(),
         };
-        // Model-space extent + centre: a batch that renders as a stray primitive is explained by
-        // where and how big it actually is (a degenerate zero-area batch is a different bug from a
-        // real card the reference hides some other way).
         let ext = |axis: usize| -> (f32, f32) {
             s.positions
                 .iter()
@@ -970,13 +870,8 @@ pub fn m2batch(chain: &mut Chain, internal_path: &str) -> Result<()> {
             flags.join(" "),
             tex,
         );
-        // The batch's UV extent, and the texel-per-yard density it implies. Two questions this
-        // answers that nothing else did: does the batch tile (range outside 0..1 — the sampler
-        // repeats, and a wrap discontinuity across a triangle blows up the derivative and drags
-        // the sampled mip to the coarsest level), and is the authored density so far above the
-        // screen's that even mip 0 is a minification? A cutout batch is where either shows up
-        // first, because a coarser mip does not merely soften it — it dissolves the silhouette
-        // the alpha key cuts (the Dun Morogh snow-fir report, B52).
+        // The UV extent and its density per yard. A range past 0..1 tiles, and a wrap across a
+        // triangle drags its mip to the coarsest level, which dissolves an alpha-keyed cutout.
         if !s.uvs.is_empty() && !s.positions.is_empty() {
             let uext = |axis: usize| {
                 s.uvs.iter().fold((f32::MAX, f32::MIN), |(lo, hi), t| {
@@ -985,7 +880,6 @@ pub fn m2batch(chain: &mut Chain, internal_path: &str) -> Result<()> {
             };
             let (u, v) = (uext(0), uext(1));
             let (du, dv) = (u.1 - u.0, v.1 - v.0);
-            // Model-space diagonal of the batch, as the yard scale the UV span stretches over.
             let diag = {
                 let (x, y, z) = (ext(0), ext(1), ext(2));
                 ((x.1 - x.0).powi(2) + (y.1 - y.0).powi(2) + (z.1 - z.0).powi(2)).sqrt()
@@ -1005,17 +899,11 @@ pub fn m2batch(chain: &mut Chain, internal_path: &str) -> Result<()> {
                 if diag > 1e-6 { du.max(dv) / diag } else { 0.0 },
             );
         }
-        // Which way the geometry FACES, in model space — the question a single-sided batch that
-        // renders when it shouldn't (or doesn't when it should) turns on. `facet` is the winding
-        // normal of the first triangle (`(p1−p0)×(p2−p0)`, WoW model axes); `vnorm` is the mean
-        // authored vertex normal. `dot` compares them: a batch whose winding disagrees with its own
-        // authored normals is wound back-to-front, and single-sided (`two_sided` absent above) it is
-        // culled from the side the author lit.
+        // A batch whose winding (`facet`) disagrees with its authored normals (`vnorm`) is wound
+        // back to front: single-sided, it is culled from the side the author lit.
         if let Some(w) = winding(s) {
             println!("      {w}");
         }
-        // Which bones the batch's vertices ride — and whether a billboard group is a rigid card or
-        // a strip we tore off a static neighbour (see [`skin_census`]).
         if let Some(k) = skin_census(s) {
             println!("      {k}");
         }
@@ -1023,11 +911,9 @@ pub fn m2batch(chain: &mut Chain, internal_path: &str) -> Result<()> {
     Ok(())
 }
 
-/// One track's value across sequence `seq_idx`'s band, under the reference's own key-search law
-/// (wow-re `eval.md` FN1 `0x713d50`): the search window is `ranges[seq_idx]`, and a window that
-/// collapses (`lo >= hi`) resolves to the single key `keys[lo]`. Returns `(lo, hi, held)` — the
-/// value range the batch takes across the band, and whether the band keys nothing (so the value is
-/// the bracket hold rather than authored motion).
+/// A track's `(lo, hi, held)` over sequence `seq_idx`'s band, by the reference's key search
+/// (`0x713d50`): the window is `ranges[seq_idx]`, and a collapsed window (`lo >= hi`) holds
+/// `keys[lo]`, so `held` means the band keys nothing.
 fn band_span(
     track: &benilla_m2::M2ScalarTrack,
     seq_idx: usize,
@@ -1055,15 +941,9 @@ fn band_span(
     (held, held, true)
 }
 
-/// Dump an M2's **per-sequence material alpha**: every colour-alpha / transparency track's keys,
-/// then the combined per-batch factor (`colour.alpha × transparency.weight`, the verified combine
-/// of wow-re `m2-alpha-combine-cull.md`) for **every sequence band**, not just the first.
-///
-/// This is the "which batches does the reference hide, and when" instrument. A batch whose factor
-/// is `0` in a band is one the real client **skips entirely** in that animation (`A ≤ 0` culls
-/// before the blend mode is read), so a row of zeros under Stand and ones under Death is a batch
-/// authored to appear only on death — exactly the voidwalker/banshee shape. `m2batch` gives the
-/// batch → track wiring this reads; `m2seq` gives the bands.
+/// Dump an M2's per-sequence material alpha: every colour-alpha and transparency track, then each
+/// batch's `colour.alpha × transparency.weight` (the reference's combine, `0x707680`) per sequence
+/// band. The reference skips a batch whose factor is 0 or less in that animation.
 pub fn m2alpha(chain: &mut Chain, internal_path: &str) -> Result<()> {
     let name = normalize(internal_path);
     let data = chain
@@ -1076,10 +956,9 @@ pub fn m2alpha(chain: &mut Chain, internal_path: &str) -> Result<()> {
         println!("no embedded skin — no batches to combine");
         return Ok(());
     };
-    // Sequences in **file order**, straight off the header array (count@0x1c/ofs@0x20, stride
-    // 0x44: anim id u16 @+0x00, band start/end u32 @+0x04/+0x08). Deliberately NOT
-    // `parse_m2_animations`, which drops zero-duration sequences and so renumbers the list — and
-    // the per-sequence `ranges` array below is indexed by the FILE slot.
+    // Sequences in file order off the header array (count at 0x1c, offset at 0x20, stride 0x44:
+    // u16 anim id at +0, u32 band start and end at +4 and +8), not `parse_m2_animations`, which
+    // drops zero-duration sequences: `ranges` is indexed by file slot.
     let seqs: Vec<(u16, (u32, u32))> = {
         let n = u32::from_le_bytes(data[0x1c..0x20].try_into().unwrap_or_default()) as usize;
         let o = u32::from_le_bytes(data[0x20..0x24].try_into().unwrap_or_default()) as usize;
@@ -1119,8 +998,7 @@ pub fn m2alpha(chain: &mut Chain, internal_path: &str) -> Result<()> {
                 .map(|&(ms, v)| format!("{ms}={v:.3}"))
                 .collect::<Vec<_>>()
                 .join(" "),
-            // The per-sequence key windows the reference indexes by the playing sequence's file
-            // slot — printed so the `*` hold cells below can be checked against the file itself.
+            // The key windows the reference indexes by the playing sequence's file slot.
             if t.ranges.is_empty() {
                 "none (whole-track search)".to_string()
             } else {
@@ -1142,10 +1020,9 @@ pub fn m2alpha(chain: &mut Chain, internal_path: &str) -> Result<()> {
         println!("  #{i:<3} {}", keys(t));
     }
 
-    // Each skin batch's two factor tracks, resolved exactly as the draw loop resolves them:
-    // colorIndex indexes `colors[]` DIRECTLY (out of range — incl. the 0xffff sentinel — means the
-    // factor doesn't apply); textureWeightComboIndex goes through `transLookup` (and applies only
-    // when the batch's textureCount is non-zero).
+    // As the draw loop resolves them: `colorIndex` indexes `colors[]` directly, and out of range
+    // (0xffff included) means no factor; the weight goes through `transLookup`, and only when
+    // `textureCount` is non-zero.
     let batches = skin.batches();
     let color_of = |b: &benilla_m2::SkinBatch| m.color_alpha_tracks.get(b.color_index as usize);
     let weight_of = |b: &benilla_m2::SkinBatch| {
@@ -1166,8 +1043,7 @@ pub fn m2alpha(chain: &mut Chain, internal_path: &str) -> Result<()> {
     for (i, &(anim_id, band)) in seqs.iter().enumerate() {
         print!("{i:>4} {anim_id:>5} {:>7}..{:<7}", band.0, band.1);
         for b in batches {
-            // A gseq-clocked track ignores the sequence band entirely (it runs on the global
-            // sequence's own clock), so report its full range rather than a band slice.
+            // A gseq track keeps its global sequence's clock, not the band: print its full range.
             let span = |t: Option<&benilla_m2::M2ScalarTrack>| match t {
                 None => (1.0, 1.0, false),
                 Some(t) if t.keys.is_empty() => (1.0, 1.0, false),
@@ -1187,8 +1063,7 @@ pub fn m2alpha(chain: &mut Chain, internal_path: &str) -> Result<()> {
             } else {
                 format!("{lo:.2}..{hi:.2}")
             };
-            // `HIDE` marks a batch the reference never draws in this sequence: the combine can
-            // only reach 0 there, and `A ≤ 0` skips the batch outright.
+            // `HIDE`: the combine stays at or below 0 here, and `A ≤ 0` skips the batch.
             let cell = if hi <= 0.0 {
                 format!("{cell} HIDE")
             } else {
@@ -1200,13 +1075,11 @@ pub fn m2alpha(chain: &mut Chain, internal_path: &str) -> Result<()> {
     }
     println!(
         "\n* = the band keys nothing: the value is `keys[ranges[seq].lo]`, the bracket the \
-         reference's collapsed key window holds (wow-re `eval.md` FN1)"
+         reference's collapsed key window holds (`0x713d50`)"
     );
 
-    // The same question asked of OUR bake, per RENDER batch — which is not the same index space:
-    // a batch spanning several billboard bones splits into one submesh per bone, so `m2batch`'s
-    // render list runs longer than the skin list. This half is what the renderer will actually do,
-    // so a disagreement with the table above is a bug in the bake, not in the art.
+    // Our bake per render batch (a billboard batch may split per bone, lengthening the list);
+    // disagreeing with the table above is a bake bug, not the art's.
     let dir = name.rsplit_once('\\').map(|(d, _)| d).unwrap_or("");
     let subs = benilla_formats::parse_m2_render_submeshes(&data, dir, &[])
         .with_context(|| format!("parsing M2 render submeshes '{name}'"))?;
@@ -1243,32 +1116,21 @@ pub fn m2alpha(chain: &mut Chain, internal_path: &str) -> Result<()> {
     Ok(())
 }
 
-/// Decode a particle emitter's file-flag word into the mechanism names the runtime keys off
-/// (each is a [`benilla_formats::ParticleEmitterDef`] predicate), plus any bit the loader maps
-/// to nothing — an unmapped bit on a model that looks wrong is a lead, not noise.
+/// An emitter's file flags as the mechanisms the runtime keys off, plus any unmapped bits.
 fn part_flags(flags: u32) -> String {
     const NAMED: [(u32, &str); 14] = [
-        // The reference has NO "lit" bit — 0x1 is the UNLIT flag, the inverse of the wiki lore
-        // (wow-re `part-scene-multipliers.md` §1). Naming it the way the binary reads it is the
-        // point: an emitter WITHOUT this bit is the one that takes the scene's light, and that
-        // silent majority-of-one is what a dump has to make visible.
+        // 0x1 is unlit, not lit (`0x70bb00`): an emitter without it takes the scene's light.
         (0x0001, "unlit"),
-        // Runtime `rt+0x1ac` bit 0x10 (loader `0x70fd13` → `0x7b5d00`): the emitter's live
-        // particles are heap-sorted back-to-front on view depth before the quad writer runs
-        // (`0x7b3a10`), instead of drawn in pool order. NOT YET IMPLEMENTED — we draw pool
-        // order for every emitter; harmless where a cloud is one flat colour (alpha coverage is
-        // order-independent), visible where it is not.
+        // Runtime `rt+0x1ac` bit 0x10 (loader `0x70fd13` → `0x7b5d00`): the reference heap-sorts
+        // live particles back to front before the quad writer (`0x7b3a10`); we draw pool order.
         (0x0002, "depthSortParticles(TODO)"),
-        // NOT unmapped, and printing it as a lead sent one session hunting it as the ride switch
-        // (1578): file `0x8` feeds the SECOND runtime flag word, `rt+0x194` bit 1 = NOT(file 0x8)
-        // (loader `0x70fd01`), the vertex-format/blend word — wow-re `part-simspace-fields.md` §A2
-        // calls it "orthogonal to simulation space". Bit 1's own reader is unread there; bit 0's
-        // (from file `0x1`) picks a 4- vs 8-word vertex stride. Half the corpus authors it.
+        // File 0x8 sets `rt+0x194` bit 1 = NOT(0x8) (loader `0x70fd01`), the vertex-format word,
+        // not the ride switch; bit 1's reader is untraced, and bit 0 (file 0x1) picks a 4- or
+        // 8-word vertex stride. Half the corpus authors 0x8.
         (0x0008, "vertexFormat(rt+0x194 b1, reader unread)"),
-        // **The ride-vs-trail switch** (wow-re `part-emitter-motion.md` §2c, decision 1578): SET
-        // stores emitter-LOCAL and re-applies the live emitter matrix at draw (a rigid ride);
-        // CLEAR bakes the birth into WORLD and never re-applies it, so a moving host lays a trail
-        // `speed × lifetime` long. 30.4% of the corpus, 71% of `Item\ObjectComponents`.
+        // The ride-or-trail switch (spawn `0x7b8a9a`, draw `0x7b3e6f`): set keeps particles
+        // emitter-local, riding the live emitter; clear bakes birth into world space, so a moving
+        // host lays a trail `speed × lifetime` long.
         (0x0010, "modelSpace(ride)"),
         (0x0020, "sizeByInstanceScale"),
         (0x0040, "inheritEmitterMotion"),
@@ -1305,7 +1167,7 @@ fn keys_str(keys: &[(f32, f32)]) -> String {
         .join(" ")
 }
 
-/// Dump one M2's particle emitters in full — see the `M2part` command doc.
+/// Dump one M2's particle emitters in full.
 pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
     let name = normalize(internal_path);
     let data = chain
@@ -1344,9 +1206,7 @@ pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
                 1 => "tail",
                 _ => "head+tail",
             },
-            // The scene-light verdict the renderer will take (`ParticleEmitterDef::lit`) — the
-            // difference between "this sheet is shaded by the world" and "this sheet is a
-            // full-white cutout", which no other line here shows.
+            // Whether the renderer lights this emitter from the scene (`ParticleEmitterDef::lit`).
             if e.lit { "LIT" } else { "unlit" }
         );
         println!(
@@ -1364,13 +1224,8 @@ pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
             println!("     recursion model (child emitters): {r}");
         }
         if let Some(s) = &e.spline {
-            // EVERY control point, and at full precision. This used to print `first .. last`,
-            // which is actively misleading on a cubic Bézier: the path is `3K+1` points and the
-            // two INTERIOR handles of each segment are what bend it, so an emitter whose ends
-            // both sit at the origin can still fling its particles a long way — or not move them
-            // at all. Reading "(0,0,0) .. (0,0,0)" as "the particles never travel" is a guess
-            // the truncated line invites and cannot support (B228 nearly rested on it).
-            // Wrapped at 4 per line so a long path stays readable.
+            // Every control point at full precision: the path is `3K+1` points of cubic Bézier,
+            // bent by each segment's interior handles, so its ends alone say nothing of its reach.
             let pt = |p: &[f32; 3]| format!("({:.4},{:.4},{:.4})", p[0], p[1], p[2]);
             println!(
                 "     spline: {} control points ({} cubic segment(s)), model-local:",
@@ -1383,7 +1238,6 @@ pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
             }
         }
 
-        // Emission timing: the rate/gate pair, per file sequence slot.
         match e.timing.constant_rate() {
             Some(r) => println!("     rate {r:.2}/s (same in every sequence)"),
             None => {
@@ -1420,9 +1274,7 @@ pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
             }
         );
 
-        // The nine emission parameter tracks: the flat ones on one line, the moving ones spelled
-        // out per slot (decision 0844 — a flattened track is exactly how a spread-out effect
-        // collapses to a point).
+        // The nine emission parameter tracks: flat ones on one line, moving ones per slot.
         let views = e.params.channel_views();
         let mut flat: Vec<String> = Vec::new();
         let mut animated: Vec<String> = Vec::new();
@@ -1481,10 +1333,7 @@ pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
                 c[0], c[1], c[2], c[3]
             );
         }
-        // 4 decimals, not 3: UI models author their sizes in thousandths, where `{:.3}` turns the
-        // autocast shine's 0.0015 mid-key into a printed "0.002" — a 33% error that a transcriber
-        // reads as authored truth (B228). The colour ramp above stays at 3 because 0..1 channels
-        // do not have that problem.
+        // Four decimals: UI models author sizes in thousandths, as the autocast shine's 0.0015.
         println!(
             "       size    {:.4} -> {:.4} -> {:.4} yd (half-extent)",
             ol.scale[0], ol.scale[1], ol.scale[2]
@@ -1503,12 +1352,9 @@ pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
             ol.repeat[1]
         );
 
-        // The derived read: what this record actually puts on screen.
         let rate = e.timing.peak_rate();
-        // A burst emitter's count is NOT its peak rate: the burst fires on the rising edge of
-        // `enabled && rate > 0`, and an emitter whose gate closes on the same keyframe its rate
-        // opens fires nothing at all. Reading `peak_rate` here reported 50 phantom particles for
-        // `Strike_Impact_Chest`'s flare and sent a whole diagnosis 2.7x over on count.
+        // A burst's count is not its peak rate: it fires on the rising edge of
+        // `enabled && rate > 0`, and one whose gate closes as its rate opens fires nothing.
         let burst = e.timing.first_burst(Some(0));
         let life = e.params.peak_lifespan();
         let speed = views[0]
@@ -1517,8 +1363,7 @@ pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
             .flatten()
             .flat_map(|k| k.iter().map(|&(_, v)| v.abs()))
             .fold(0.0f32, f32::max);
-        // Drag caps total travel near `speed/drag` (the integrator's exponential decay); with no
-        // drag a particle simply coasts for its lifetime.
+        // Drag caps travel near `speed/drag`; without drag a particle coasts for its whole life.
         let reach = if e.drag > 1e-6 {
             (speed / e.drag).min(speed * life)
         } else {
@@ -1548,17 +1393,9 @@ pub fn m2part(chain: &mut Chain, internal_path: &str) -> Result<()> {
     Ok(())
 }
 
-/// Dump an M2's **camera table**, in raw file-index order — the index space a `<Model>` widget's
-/// `Model:SetCamera(n)` walks (decision 2027; the selection is raw, `cameraLookup` is not
-/// consulted there, so the table position IS the answer and the record's `type` is not).
-///
-/// Prints, per record: its `type` word, the eye and look-at target at rest (`base + key 0`, raw
-/// WoW model space), the diagonal fov in radians and degrees, near/far, the roll, and the key
-/// count of each of the three tracks — the last column being the one that says whether the camera
-/// is a still rig (every character/creature/interface camera in the chain) or an authored path
-/// (the `Cameras\*.m2` fly-bys). The `cameraLookup` table is printed beside it, because the
-/// portrait bake selects through it and the pane does not, and confusing the two is a one-line
-/// mistake with a wrong picture at the end of it.
+/// Dump an M2's camera table in raw file-index order, the index `Model:SetCamera(n)` selects by
+/// without `cameraLookup`, which prints beside it because the portrait bake selects through it.
+/// Key counts tell a still rig from an authored path (the `Cameras\*.m2` fly-bys).
 pub fn m2cam(chain: &mut Chain, internal_path: &str) -> Result<()> {
     let name = normalize(internal_path);
     let data = chain
diff --git a/crates/benilla-formats/src/bin/benilla-extract/main.rs b/crates/benilla-formats/src/bin/benilla-extract/main.rs
index 7a550899..39b97ff2 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/main.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/main.rs
@@ -1,13 +1,6 @@
-//! `benilla-extract` — Phase 1 CLI over WoW 1.12.1 (build 5875) MPQ archives.
-//!
-//! Implemented: `list`, `extract` (raw bytes), operating on the **patch chain**
-//! (later archives override earlier; real names come from patch.MPQ's `(listfile)`).
-//! BLP->PNG and DBC->CSV come next.
-//!
-//! This file is the stable face: the clap [`Cli`]/[`Command`] definitions, the dispatch `match`,
-//! and the tiny helpers shared across concerns. The heavier subcommands live in sibling modules by
-//! concern: per-model M2 dump printers ([`m2dump`]), corpus-scan reports ([`scan`]), and the spell
-//! visual chain ([`spellvis`]).
+//! `benilla-extract`: a CLI over the 1.12.1 (build 5875) MPQ patch chain, where later archives
+//! override earlier ones and names come from `patch.MPQ`'s `(listfile)`. This file holds the clap
+//! commands, their dispatch and the shared helpers; the subcommands live in modules by concern.
 
 use std::path::PathBuf;
 
@@ -58,28 +51,20 @@ enum Command {
         internal_path: String,
         /// Output `.png` file.
         output: PathBuf,
-        /// Also write every authored mip level (`<stem>.mip<N>.png`) and print a per-level
-        /// texel census: how many texels the author left transparent vs not, the luma range of
-        /// each class, and how many sit below 128 — the set that DARKENS under a Mod2x lane,
-        /// which reads no alpha. The "what does the far sampler see" instrument (B358).
+        /// Also write every mip (`<stem>.mip<N>.png`) and census each: transparent and opaque
+        /// texels, their luma, and how many sit below 128, which darken under alpha-blind Mod2x.
         #[arg(long)]
         mips: bool,
     },
-    /// Composite ONE character's body atlas off the chain and report what painted what: the
-    /// equipment blits in blit order (with the file each region name resolved to, or `MISSING`),
-    /// the per-tile rows repainted vs the same character naked, and the geoset set the same
-    /// equipment selects. The "this garment stops early / that slot repainted this one" instrument
-    /// — a dressed body is ten fixed atlas tiles, and every defect in that class is one tile
-    /// receiving the wrong contribution.
+    /// Composite one character's body atlas and report what painted what.
     Charatlas {
-        /// `ChrRaces` id (1 human · 2 orc · 3 dwarf · 4 night elf · 5 undead · 6 tauren · 7 gnome ·
-        /// 8 troll).
+        /// `ChrRaces`: 1 human, 2 orc, 3 dwarf, 4 night elf, 5 undead, 6 tauren, 7 gnome, 8 troll.
         #[arg(long)]
         race: u8,
         /// 0 male · 1 female.
         #[arg(long)]
         sex: u8,
-        /// `skinColor` — the CharSections variation the base skin + head sections key on.
+        /// `skinColor`, the CharSections variation the base skin and head sections key on.
         #[arg(long, default_value_t = 0)]
         skin: u8,
         /// `faceType`.
@@ -94,29 +79,21 @@ enum Command {
         /// `hairColor`.
         #[arg(long, default_value_t = 0)]
         hair_color: u8,
-        /// The eight worn `ItemDisplayInfo` ids, comma-separated, in bodyslot order:
-        /// shirt,chest,belt,pants,boots,wrist,gloves,tabard. `0` leaves a slot empty; a short list
-        /// leaves the rest empty.
+        /// The eight worn `ItemDisplayInfo` ids, comma-separated in bodyslot order (shirt, chest,
+        /// belt, pants, boots, wrist, gloves, tabard); a 0 or a short list leaves slots empty.
         #[arg(long, value_delimiter = ',', default_value = "0")]
         slots: Vec<u32>,
-        /// The wearer's guild tabard, comma-separated in
-        /// `emblemStyle,emblemColor,borderStyle,borderColor,backgroundColor` order — the five
-        /// indices `SMSG_GUILD_QUERY_RESPONSE` carries (decision 1704). Omit for "no guild". Only
-        /// paints when the tabard slot holds a guild-emblem display (20621 is the shipped one).
+        /// The guild tabard, `emblemStyle,emblemColor,borderStyle,borderColor,backgroundColor` as
+        /// `SMSG_GUILD_QUERY_RESPONSE` carries them; only a guild-emblem tabard (20621) shows it.
         #[arg(long, value_delimiter = ',')]
         emblem: Option<Vec<i32>>,
         /// Write the composited atlas here as a PNG (256²).
         #[arg(long)]
         out: Option<PathBuf>,
     },
-    /// Measure every shipped glue scene's **art extent** (decision 1619): how far the opaque art
-    /// of each `UI_*` diorama covers around its authored camera 0, and the window aspects past
-    /// which the glue framing law stops widening and zooms instead. The instrument behind B330
-    /// (the login backdrop's edges showing at 16:9) — the same measurement the client makes at
-    /// scene spawn, printed for all seven scenes with the looser readings beside it.
+    /// Measure each shipped glue scene's art extent and the window aspects where it runs out.
     Glueextent {
-        /// Also print every batch's footprint in the frame (front/back/clipped triangle counts,
-        /// projected extents) — which card sets the measured edge.
+        /// Also print every batch's footprint: front, back and clipped triangles and its extents.
         #[arg(long)]
         batches: bool,
     },
@@ -127,564 +104,284 @@ enum Command {
         /// Output `.csv` file.
         output: PathBuf,
     },
-    /// Dump a spell's visual chain: spell → SpellVisual stages → each kit's anim/sound (decision
-    /// 0099's phase-2 instrument; columns per decision 0107).
+    /// Dump a spell's visual chain: its `SpellVisual` stages and each kit's contents.
     Spellvis {
         /// The `Spell.dbc` id (e.g. 133 = Fireball).
         spell_id: u32,
     },
-    /// Census the **beam/chain** system (decision 0955): the 18-row `SpellChainEffects` table,
-    /// then every `SpellVisualKit` that draws a beam — the row it names, its beam count and
-    /// flag, and the spells that reach it through which lifecycle stage. The scope instrument
-    /// for B161 ("Chain Lightning has no chain effect"), and the check that the `CharParamZero`
-    /// small-int decode is the real mechanism: every live slot must land on a real row.
+    /// Census the beam system: `SpellChainEffects` and every `SpellVisualKit` that draws a beam.
     Chaincensus,
-    /// Census the **camera-shake** system (decision 1540): the 24 shipped `CameraShakes.dbc`
-    /// presets and every `CreatureModelData` row that names one, through the footstep column or
-    /// the death-thud column. The scope instrument for B298 ("walking past an Ancient Protector
-    /// shakes no screen"), and the check that fields 11/12 really are `CameraShakes` keys — every
-    /// live value must land on a real row.
+    /// Census the camera-shake system: the 24 `CameraShakes.dbc` presets and all that names one.
     Shakecensus,
-    /// Census the **death thud** — the body-fall sound a corpse makes on landing (`$DTH` →
-    /// `0x6236e0`, the sibling of the camera shake above). Two halves: the `DeathThudLookups.dbc`
-    /// matrix in full (`SizeClass × TerrainTypeSoundID` → the named land/water `SoundEntries`
-    /// kits), and the population sweep of which creature M2s key a `$DTH` at all, with the size
-    /// class their displays resolve to. The scope instrument for "a big corpse hits the ground
-    /// silently": it separates authored silence (an empty water column) from a real gap.
+    /// Census the death thud a corpse makes on landing (`$DTH`, `0x6236e0`): the
+    /// `DeathThudLookups.dbc` grid and which creature models key a `$DTH`.
     Thudcensus,
-    /// Census the `SpellVisualKit` **CharProc** columns (a kit's effect on the BODY — its alpha,
-    /// its tint): which proc types the shipped table carries, which lifecycle stage reaches each
-    /// from a live spell, and every state-stage (aura-lifetime) proc in full. The scope instrument
-    /// for the aura-state CharProc system.
+    /// Census the `SpellVisualKit` CharProc columns, a kit's effect on the body, by stage.
     Charprocs,
-    /// Census the `SpellVisualKit` **animation** column (field 2) — the half of a kit that plays a
-    /// clip on the unit's own BODY, as opposed to its attach-point effect models, its CharProcs or
-    /// its camera shake. Which anim ids the shipped table asks for, which lifecycle stage reaches
-    /// each (the stage picks the consumer: a `cast`/`impact` anim is a one-shot on the
-    /// caster/victim, a `state` anim belongs to an aura's whole life), then the state set in full
-    /// and the impact set ranked. The scope instrument for "the spell landed on me and my
-    /// character did nothing" — an anim that is never asked for leaves no trace to grep, unlike an
-    /// effect model that fails to spawn. `ANIM-ONLY` marks the state kits whose whole visual is the
-    /// anim, the class a "does this kit do anything?" test drops (the B114 shape one level over).
+    /// Census the `SpellVisualKit` animation column (field 2), a clip on the unit's body, by stage.
     Kitanim,
-    /// Dump an M2's collision hull as the mover collides with it: vertex/triangle counts, the
-    /// model-space AABB (WoW axes, Z up), and its extents — the "what does walking into this
-    /// actually hit" instrument (the step-up climb-vs-slide asset question, decision 0195; a
-    /// placement's own scale still multiplies these numbers).
+    /// Dump an M2's collision hull: counts and the model-space AABB (WoW axes, Z up), unscaled.
     M2coll {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump an M2's animation sequences in file order: `AnimationData.dbc` id, loop/clamp flag,
-    /// duration, authored design speed (the rate divisor), variation frequency, replay range —
-    /// the variation/replay instrument (decisions 0114/0117; sequences sharing an id are its
-    /// variation chain).
+    /// Dump an M2's sequences in file order: anim id, loop or clamp, duration, design speed (the
+    /// rate divisor), variation frequency and replay range; sequences sharing an id are variations.
     M2seq {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump an M2's **camera table** by raw file index — the index space a `<Model>` widget's
-    /// `Model:SetCamera(n)` walks (decision 2027): type, rest eye/target, diagonal fov, near/far,
-    /// roll, and each track's key count (which says still rig vs authored path). The
-    /// `cameraLookup` table is printed beside it — the portrait bake selects through that, the
-    /// pane does not.
+    /// Dump an M2's camera table by raw file index, the index `Model:SetCamera(n)` selects by;
+    /// the portrait bake selects through `cameraLookup` instead, printed beside it.
     M2cam {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump an M2's animation EVENT keyframes per sequence (`$CSS`/`$CAH`/`$AH0-3`/`$CPP`/`$HIT`…,
-    /// time + payload) — the event-order instrument (decision 0279: whether `$CPP` precedes the
-    /// impact tag decides defense-anim vs flinch on the shared swing record).
+    /// Dump an M2's animation event keyframes per sequence; whether `$CPP` precedes the impact
+    /// tag decides defense animation or flinch.
     M2events {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump an M2's attachment points (id + bone) — which sheath/held/effect anchors a model
-    /// actually has (decisions 0072/0122; a placement whose id is absent hangs nothing).
+    /// Dump an M2's attachment points (id and bone); a placement on an absent id hangs nothing.
     M2attach {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump an M2's animation-channel summary: sequence-0 bone motion, global-sequence bone
-    /// channels, transparency/color track key counts, texture transforms, and — per particle
-    /// emitter — its full def: shape, blend mode, head/tail, emission-rate keys (burst emitters
-    /// key `0 → peak → 0`), lifespan/speed/scale, position/area, resolved texture, and the
-    /// over-life color/alpha/size ramps. The one-command diagnosis for "this effect looks wrong /
-    /// doesn't show" (decisions 0130/0141); paired with `doodadscan`.
+    /// Dump an M2's animation channels, texture transforms and every particle emitter in full.
     M2anim {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump an M2's bone table: KeyBoneID, flags (billboard bits tagged), the `flags & 0x7`
-    /// parent-ignore bits spelled out (`ign` — which of the parent's Translate/Scale/Rotate the
-    /// bone refuses), parent, pivot, and which sequences key each bone (T/R/S key counts) — the
-    /// bone-attach / billboard-geometry instrument (decisions 0028/0122: which bone a rider
-    /// actually rides and whether it faces the camera; 0945: what it actually inherits from its
-    /// parent, which is how a saddle travels with the gallop without rotating with it).
+    /// Dump an M2's bone table, with the parent channels each bone ignores (`flags & 0x7`).
     M2bones {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump an M2's render batches as the renderer sees them: geoset, blend/flags
-    /// (emissive/additive/two-sided/billboard/depth), texture, vertex count, and whether an
-    /// alpha/UV animation baked — the "why doesn't this part of the model draw (or draw wrong)"
-    /// instrument (the Orgrimmar-bonfire missing-flame diagnosis).
+    /// Dump an M2's render batches as the renderer sees them.
     M2batch {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump an M2's **per-sequence material alpha**: every colour-alpha/transparency track's raw
-    /// keys, then the combined per-batch factor for EVERY sequence band — the "which batches does
-    /// the reference hide, and in which animation" instrument. A `HIDE` cell is a batch the real
-    /// client skips outright in that sequence (`A <= 0` culls before the blend mode is read,
-    /// wow-re `m2-alpha-combine-cull.md`). Pair with `m2batch` (the batch -> track wiring) and
-    /// `m2seq` (the bands).
+    /// Dump an M2's per-sequence material alpha: each colour-alpha and transparency track, then
+    /// every batch's combined factor per sequence band. `HIDE` marks a batch the reference skips
+    /// in that sequence: `A <= 0` culls before the blend mode is read (`0x707b3a`-`0x707b5c`).
     M2alpha {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Dump ONE M2's particle emitters in full — every authored field of every record, as the
-    /// runtime parses it: bone/position/shape/blend/head-tail, texture + atlas, the decoded file
-    /// flags, the rate/gate timing and the nine emission tracks (flagged `ANIM` with their keys
-    /// when they actually move), drag/spin/tail/twinkle, spline and geometry/recursion models,
-    /// and the over-life colour/size/flipbook ramps. Closes with a derived read per emitter —
-    /// steady-state live count, ballistic reach, size range — so "this flame is a bright blob,
-    /// not a spread-out fire" is answered from the asset before anything is blamed on the
-    /// renderer. The per-model counterpart to the corpus sweeps (`partcensus`, `partscan`).
+    /// Dump one M2's particle emitters in full, with each one's derived count, reach and size.
     M2part {
         /// Internal path to the `.m2` (forward or back slashes accepted).
         internal_path: String,
     },
-    /// Sweep every `.m2` and report where **addressing an attachment by id** through the model's
-    /// AttachLookup (the reference's `0x710310`) disagrees with scanning its record table — the
-    /// duplicate-id census behind decision 0805 (item glows hang on ids 0..4 of the item model).
+    /// Sweep every `.m2` for where addressing an attachment by id through AttachLookup
+    /// (`0x710310`) disagrees with scanning its records; item glows hang on the item's ids 0..4.
     Attachscan {
         /// Optional path prefix to restrict the sweep (e.g. `Item\ObjectComponents\Weapon`).
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` in the chain and list the models carrying RIBBON emitters (header
-    /// `0x134`) — the population instrument for the ribbon subsystem (weapon trails, streamers):
-    /// which content actually authors one, before we build for it.
+    /// Sweep every `.m2` and list the models carrying ribbon emitters (header `0x134`).
     Ribbonscan,
-    /// Sweep every `.m2` and census its particle emitters' over-life **flipbook** fields: cell
-    /// ramps that play BACKWARDS (`begin > end` — legal, shipped, and fatal to a reader that
-    /// clamps into the pair), tail streaks whose ramp differs from the head's, indices past the
-    /// atlas (the reference wraps the column and lets the row run off), per-segment repeat counts,
-    /// and the two degenerate shapes the reference itself falls back on. Decision 0685.
+    /// Sweep every `.m2` and census particle flipbook fields: backward ramps (`begin > end`, legal
+    /// and shipped), tail ramps unlike the head's, indices past the atlas (the reference wraps the
+    /// column, the row runs off), repeat counts, and the reference's two degenerate fallbacks.
     Cellscan,
-    /// Sweep every `.m2` (optionally under a path prefix) and list the models whose MATERIAL
-    /// table authors the MULTIPLY blend modes 5 (Mod) / 6 (Mod2x) — the ARMORREFLECT sheen
-    /// family (decision 0528): the population instrument for the multiply-blend mechanism.
+    /// Sweep every `.m2` for materials with the multiply blends 5 (Mod) and 6 (Mod2x), the
+    /// armor-reflect sheen family.
     Blendscan {
         /// Internal-path prefix filter (e.g. `item\objectcomponents\weapon`), case-insensitive;
         /// all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and classify its BILLBOARD usage:
-    /// which arms it authors (spherical / lock-X / lock-Y / lock-Z), and whether geometry rides
-    /// them DIRECTLY (verts skinned to the billboard bone — the per-batch card path) or
-    /// INHERITED (verts on a descendant — the joint-palette path, decision 0205). The
-    /// population instrument for the billboard mechanism: which arms real content exercises, so
-    /// a class of spell visuals is closed by mechanism instead of tested spell-by-spell.
+    /// Sweep every `.m2` and classify its billboards: which arms it authors (spherical, lock-X,
+    /// -Y or -Z) and whether geometry is skinned to the billboard bone or rides a descendant.
     Bbscan {
         /// Internal-path prefix filter (e.g. `spells`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and classify each BILLBOARD batch by
-    /// which way its geometry FACES. A billboard bone puts the model's +X toward the viewer, so a
-    /// batch's winding normal decides whether it is ever seen: +X faces the camera, −X faces away
-    /// and — single-sided — is backface-culled by the reference from every angle. The population
-    /// instrument for "the card renders but shouldn't": the away+single-sided list is exactly the
-    /// authored placeholder geometry the reference hides and a forced-two-sided renderer reveals.
+    /// Sweep every `.m2` and classify each billboard batch by facing: a billboard bone turns +X to
+    /// the viewer, so a single-sided batch facing -X is culled by the reference from every angle.
     Bbfacescan {
-        /// Internal-path prefix filter (e.g. `world\generic`), case-insensitive; all models if omitted.
+        /// Internal-path prefix filter (e.g. `world\generic`), case-insensitive; all if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and report models that author flat
-    /// ground-plane render geometry: batches whose vertices all sit at model-space z≈0 (WoW axes,
-    /// Z up), which sloped terrain buries (Battle Shout's crescents are the canonical case — 6
-    /// batches, each a 4-vert quad, every vertex exactly z=0, each quad skinned 100% to a single
-    /// bone). Flat batches sub-classify QUAD-1BONE (that exact crescent shape) vs OTHER-FLAT — the
-    /// population instrument for how general the ground-plane renderer mechanism must be.
+    /// Sweep every `.m2` for flat ground-plane batches (every vertex at model-space z≈0), which
+    /// sloped terrain buries; `QUAD-1BONE` is Battle Shout's crescent shape, a quad on one bone.
     Groundscan {
         /// Internal-path prefix filter (e.g. `spells`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and census the batches carrying
-    /// **degenerate authored vertex normals** — `(0,0,0)`, which the shipped corpus really does
-    /// author (the AQ40 Qiraji Brainwasher's sleeves, Uldaman Ironaya's skirt). The reference
-    /// consumes such a normal as the zero vector and its order-2 SH collapses to the flat DC term,
-    /// so the surface draws lit; a renderer that `normalize()`s it gets NaN, `clamp(NaN)` floors
-    /// the whole lighting factor to 0, and the batch renders PURE BLACK over its correct texture.
-    /// The population instrument for that class (decision 1268, bug B134) — `ALL` marks a batch
-    /// where every vertex is degenerate, and the tail names the worst-hit models.
+    /// Sweep every `.m2` for batches with zero authored vertex normals: the reference takes one as
+    /// is and its order-2 SH collapses to the flat DC term, so the surface draws lit, where
+    /// `normalize()` gives NaN and a black batch. `ALL` marks a batch degenerate at every vertex.
     Normalscan {
         /// Internal-path prefix filter (e.g. `creature`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and measure how far its authored header
-    /// bounding box — the model's **all-animation** vertex extent, and the box the reference
-    /// derives its doodad cull sphere from (`rec+0x5c`/`rec+0x68`) — reaches past its **bind-pose**
-    /// vertex extent. The population instrument for decision 1259: an animated placement's submesh
-    /// keeps its transform at the placement origin while the joint palette moves its vertices, so a
-    /// bind-pose bound culls an object whose geometry is still on screen. The ambient critters are
-    /// the extreme — `World\critter\birds\Bird01.m2` authors a 67 yd box around a 1.2 yd body,
-    /// because its root bone flies it 64 yd along a circuit. Also reports the reverse (`SHORT`:
-    /// bind-pose geometry OUTSIDE the authored box), which is why the fix unions the two boxes.
+    /// Sweep every `.m2` and measure how far its header bounds, the all-animation extent the
+    /// reference derives its doodad cull sphere from (`rec+0x5c`/`rec+0x68`), reach past its
+    /// bind-pose extent; `SHORT` marks bind-pose geometry outside the header box.
     Animboundscan {
         /// Internal-path prefix filter (e.g. `world\critter`), case-insensitive; all if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and census the geometry a
-    /// **non-character** spawn draws that the reference may not: MULTI-GEOSET models (more than
-    /// one `skinSectionId` — only the character compositor selects among them, so every other
-    /// spawn path draws all of them), UNTEX batches (no embedded texture and no character runtime
-    /// slot) and TINY batches (at most 2 faces). The population instrument behind the stray
-    /// untextured-primitive reports; `m2batch` then explains a single model in full.
+    /// Sweep every `.m2` for geometry a non-character spawn draws that the reference may not:
+    /// multi-geoset models (only the character compositor picks among geosets), untextured batches
+    /// and tiny ones (at most 2 faces).
     Geosetscan {
         /// Internal-path prefix filter (e.g. `creature`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every model named by **GameObjectDisplayInfo.dbc** and resolve what the reference's
-    /// GameObject animation arm plays in each reachable `GAMEOBJECT_STATE` × `GAMEOBJECT_ANIMPROGRESS`
-    /// substate (wow-re `gameobject-anim-arm.md` §2b/§2c: the substate table, the `0x8607e4` LUT, the
-    /// four-way missing-sequence remap) — beside the generic loader seed the same model gets at build
-    /// (§1, animation id 0 through `playableAnimationLookup`). The population instrument for "which
-    /// GameObjects can the wire state actually be SEEN on": a model whose every substate lands on the
-    /// seed's own sequence is state-blind, so skipping the arm on its GO type costs nothing, while a
-    /// STATE-SENSITIVE model renders in the wrong pose the moment its type is left off the machine.
-    /// Also counts the models whose pose depends on the §2c remap (benilla plays nothing there today,
-    /// i.e. bind pose) and the ones reaching a rate-0 freeze leg.
+    /// Sweep every `GameObjectDisplayInfo` model and resolve what the reference's GameObject
+    /// animation arm plays per reachable state and anim-progress substate (substate table
+    /// `0x5f3c30`, LUT `0x8607e4`, missing-sequence remap `0x5f3972`) against the loader's seed
+    /// (`0x710153`, animation 0 through `playableAnimationLookup`); a model whose every substate
+    /// lands on the seed's sequence is state-blind.
     Goanimscan,
-    /// Sweep every `.m2` and census the **event table's positional half**: the `bone` and
-    /// `position` every `M2Event` record carries beside its 4CC. The reference's event dispatchers
-    /// hand their arms the event's own world point (the authored `position` through its bone's live
-    /// matrix and the model's placement), while a consumer that plays at the model root uses the
-    /// placement alone — so this reports, per 4CC, how many records sit off the origin and how many
-    /// ride a bone any sequence keys. Where both are zero the two are the same point.
+    /// Sweep every `.m2` and census each `M2Event`'s `bone` and `position`: the reference's
+    /// dispatchers play at the event's own world point, so per 4CC it counts the records off the
+    /// origin and those on a bone some sequence keys.
     Eventmarkerscan {
         /// Internal-path prefix filter (e.g. `creature`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Census the **GameObject display sound slots** (`GameObjectDisplayInfo.Sound[0..9]`) against
-    /// the only thing that can reach them. Exactly one function in the reference reads those
-    /// columns (`0x5f4010`) and it is called only from the GO M2 anim-event dispatcher
-    /// (`0x5f3e20`): `$GO0..5` -> slots 0..5, `$GC0..3` -> slots 6..9 (wow-re
-    /// `go-display-sound-events.md` §1/§3). So a filled column is audible only when the display's
-    /// own model authors the matching event tag AND that tag sits on a sequence the GameObject
-    /// animation arm can actually play. Reports, per slot: columns filled, of those how many are
-    /// tagged, how many of those are on an armable sequence, and how many name a LOOPING (0x200)
-    /// kit — the flag that selects `0x5f4010`'s emitter-pool lane over its one-shot lane.
+    /// Census `GameObjectDisplayInfo.Sound[0..9]`: only `0x5f4010` reads them, called only from
+    /// the GameObject anim-event dispatcher (`0x5f3e20`), `$GO0..5` to slots 0-5 and `$GC0..3` to
+    /// 6-9. Per slot: filled, tagged by the display's model, on an armable sequence, and naming a
+    /// looping kit (0x200, which picks `0x5f4010`'s emitter-pool lane over its one-shot lane).
     Goslotscan,
-    /// Sweep every `.m2` (optionally under a path prefix) and census the models whose batch
-    /// visibility is PER SEQUENCE — geometry the reference draws in one animation and skips in
-    /// another (the verified `A <= 0` alpha cull). The population instrument for "a single-sequence
-    /// material bake draws the wrong set"; `m2alpha` then explains one model in full.
+    /// Sweep every `.m2` for batches whose visibility changes per sequence, drawn in one
+    /// animation and culled by `A <= 0` in another.
     Alphascan {
         /// Internal-path prefix filter (e.g. `creature`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and census the **effect-model animation
-    /// lifecycle**: which models author the `Stand`(0) -> `Hold`(158) -> `Decay`(159) triple, and
-    /// what a consumer that arms ONE sequence and never advances renders for each. A spell-effect
-    /// model puts its grow-in in the clamping `Stand`, its sustained pulse in the looping `Hold`
-    /// and its fade-out in `Decay` — so arming only the first freezes on the birth's last frame for
-    /// the effect's whole life (the frozen Ice Barrier shield). The population instrument for that
-    /// class: FREEZE / hold-loops / decay-only counts, corpus-wide; `m2seq` explains one model.
+    /// Sweep every `.m2` for the effect lifecycle `Stand`(0), `Hold`(158), `Decay`(159): arming
+    /// only the clamping Stand freezes the effect on its last frame instead of pulsing in Hold.
     Fxlifescan {
         /// Internal-path prefix filter (e.g. `spells`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and measure how far our SKELETAL parse
-    /// sits from the reference's sampler, per bone track per sequence band: empty bands (our
-    /// nearest-key clamp vs the file's own `interpolation_ranges` window), held band edges (our
-    /// hold vs the reference's ongoing lerp toward the next key), and STEP tracks (`interp == 0`,
-    /// which the reference copies and we interpolate). The population instrument behind decision
-    /// 0133's named residual — and the safety check that a band's keys never fall outside the
-    /// window the reference searches.
+    /// Sweep every `.m2` and measure our skeletal parse against the reference's sampler, per bone
+    /// track and band: empty bands (our nearest-key clamp, its `interpolation_ranges` window), held
+    /// band edges (our hold, its lerp toward the next key) and step tracks (`interp == 0`, which it
+    /// copies and we interpolate). It also checks no band's keys fall outside the searched window.
     Bonescan {
         /// Internal-path prefix filter (e.g. `creature`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and census every particle-emitter
-    /// FEATURE the corpus authors — shapes, head/tail, blend modes (incl. the folded Mod/Mod2x),
-    /// every file-flag bit, spin signs, twinkle gates, atlas tiling, spline emitters, and the
-    /// record fields the renderer doesn't parse yet (geometry-model "model particles",
-    /// recursion-model child emitters, the rate track's interp word) — each with counts, example
-    /// models, and the spells whose visual chain plays them. The population instrument that turns
-    /// "this spell looks wrong" reports into a ranked mechanism worklist, closing feature classes
-    /// corpus-wide instead of spell-by-spell.
+    /// Sweep every `.m2` and census each particle-emitter feature the corpus authors.
     Partcensus {
         /// Internal-path prefix filter (e.g. `spells`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and list the particle emitters whose
-    /// **file slot 0 is dead while a later slot is alive** (`peak0 <= 0 < peakN`). The reference
-    /// samples the PLAYING sequence's rate window every frame, so an emitter whose burst is keyed
-    /// in a later variation is ordinary content — but a consumer that PINS slot 0 renders it as
-    /// nothing at all, for ever, on every placement, while the emitter still builds, pools and
-    /// ticks. The population instrument for that silent class (decision 0760; found on
-    /// `BlastedLandsLightningbolt01.m2`, the Blasted Lands strike that never fires).
+    /// Sweep every `.m2` for emitters whose file slot 0 is dead while a later slot lives
+    /// (`peak0 <= 0 < peakN`): the reference samples the playing sequence's rate window, so a
+    /// consumer pinned to slot 0 never emits them.
     Partslotscan {
         /// Internal-path prefix filter (e.g. `world`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and census the batches the bake routes
-    /// to a **per-placement material** — the ones whose UV loop or M2Color RGB tint loop is not the
-    /// same in every FILE sequence slot, so no material shared by every instance can be right for
-    /// them (decision 1408). The texture-transform twin of `partslotscan`.
-    ///
-    /// It asks the **bake**, not a copy of it: `RenderSubmesh::uv_seq` / `rgb_seq` are `Some`
-    /// exactly when `SeqLoops::uniform()` refused the shared lane, so the census and the runtime
-    /// cannot disagree by construction. It used to transcribe the sampler instead — it was written
-    /// to SIZE this fix, before the fix existed — and once the fix landed the twin drifted from it:
-    /// the transcription compared periods and value EXTENTS at 1e-3, which calls
-    /// `Spells\AdrenalineRush_Cast_Base` the same loop in both slots, where the bake's own tail key
-    /// differs by a full 1.0 (slot 0 ends blue, slot 1 returns to red).
-    ///
-    /// Per (batch, channel): **SHARED** — the set is `None`, the slots agree, nothing changes for
-    /// it (with the sub-count that actually animates on that lane) — and **PER-PLACEMENT**, the set
-    /// is `Some`. The latter splits by WHY the slots disagree, which is the question of whether
-    /// `uniform()`'s exact float equality is *earning* the routing it does: **DEAD-0** (slot 0
-    /// bakes nothing while a later slot animates — the B98 shape, `BlackrockStatueLavaBubble.m2`
-    /// keying its whole UV flipbook inside file slot 1, a 50/50 variation of animation id 0, so the
-    /// slot-0 bake returns `None` and every placement is frozen for ever), **WRAP-ONLY** and
-    /// **KEYS-EPSILON** — the over-application buckets, where the slots hold the same authored loop
-    /// and are split only by the wrap flag or by sub-epsilon noise in a rebased key — and
-    /// **REAL-DIFFERS** (genuinely different loops, or slot 0 alive against a dead later slot).
-    /// Over the shipped corpus both over-application buckets are **empty**, so nothing is on the
-    /// per-placement lane that a coarser comparison would have left off it.
-    ///
-    /// Each bucket closes with its content family and a named worst-hit tail (batches, file
-    /// sequence slots). `World\` is the only family the per-placement lane reaches at all — a
-    /// placed doodad or WMO prop; `Creature\`/`Spells\` and the `World\Goober\` GameObject
-    /// displays resolve their own sequence through the entity lane — so a bucket living outside it
-    /// costs nothing whatever it says.
+    /// Sweep every `.m2` for batches the bake routes to a per-placement material, whose UV or
+    /// M2Color tint loop differs across file sequence slots, read from the bake itself (`uv_seq`
+    /// and `rgb_seq` are `Some` exactly when `SeqLoops::uniform()` refuses the shared lane) and
+    /// bucketed by why: `DEAD-0`, `WRAP-ONLY`, `KEYS-EPSILON` or `REAL-DIFFERS`. Only placed
+    /// doodads and WMO props reach the lane; creatures, spells and GameObjects use the entity lane.
     Uvslotscan {
         /// Internal-path prefix filter (e.g. `world`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and list the models whose animation is
-    /// authored **entirely outside the bone tracks**: sequences exist, per-sequence consumers exist
-    /// (particle emitters, ribbons, material alpha/colour, UV transforms), and not one sequence
-    /// keys a bone. A sequence clock that rides a bone-animation clip has nothing to ride on such a
-    /// model — no clip, no player, no "which sequence, how far in" — so every per-sequence consumer
-    /// degrades to file slot 0 at t = 0, for ever. The population instrument for that silent class
-    /// (decision 0941; found on the Molten Core rune + flame ring). `[GO]` marks a
-    /// `GameObjectDisplayInfo` model — the hosted-clock lane, where the freeze is total.
+    /// Sweep every `.m2` for models animated entirely outside the bone tracks: no sequence keys a
+    /// bone, so a clock riding a bone clip leaves every per-sequence consumer at slot 0, t = 0.
+    /// `[GO]` marks a `GameObjectDisplayInfo` model, where the freeze is total.
     Seqclockscan {
         /// Internal-path prefix filter (e.g. `world`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and list batches whose texture is authored
-    /// **CLAMP** (`M2Texture.flags` bit 0/1 clear) while the batch's UVs run **outside `0..1`** — the
-    /// population a repeat-sampling renderer draws wrong. That margin is deliberate: clamped it
-    /// samples the sheet's transparent border and the card fades to nothing; wrapped it folds into
-    /// the opposite edge and draws as solid geometry with a seam at the crossing (decision 0763,
-    /// bugs B52/B96 — the Dun Morogh snow-firs and the Plaguelands bush).
+    /// Sweep every `.m2` for batches whose texture is authored clamp on an axis (`M2Texture.flags`
+    /// bit 0 or 1 clear) while their UVs run outside 0..1 there on purpose: clamped they fade into
+    /// the sheet's transparent border, wrapped they draw solid with a seam where they cross.
     Uvwrapscan {
         /// Internal-path prefix filter (e.g. `world`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every model the **spell-visual chain** can reach — every `SpellVisualEffectName`
-    /// path a kit's ten effect slots, a `SpellVisual` row's missile model or its dest-anchored
-    /// model names — and census the batches whose **texture transform animates**, then classify
-    /// each by what a consumer that runs NONE of it renders.
-    ///
-    /// Decision 0271 deferred this channel on the claim that "no effect model in the current
-    /// corpus needs it"; this is that claim, made countable — it is what 2282 read to size the
-    /// missing scroll, and it is how the same question was re-asked of the unit / GameObject /
-    /// held-item corpus that 2295 then fixed (`entityuvscan`, its twin). It asks the **bake**,
-    /// not a transcription of it: a batch is in scope
-    /// exactly when `tex_anim` emitted a loop on any of the three channels, the same test the
-    /// lanes that DO run them use (`ui_models` 2019, `spell_fx` 2282).
-    ///
-    /// The classes are what a frozen batch draws, judged from the texture's own alpha through its
-    /// authored address mode — because a CLAMP-authored sheet's border is what a UV outside `0..1`
-    /// samples, and on this corpus that border is transparent:
-    ///
-    /// - **INVISIBLE** — frozen, every texel the batch reaches is transparent, while the scroll
-    ///   reaches painted ones: the batch renders **nothing at all**. `Spells\SwipeCaster.m2`
-    ///   (druid Swipe) is the class: two 51-vertex claw-trail strips whose UVs are authored at
-    ///   `u[+0.945..+1.944]` over a 16×16 CLAMP sheet, so frozen they sample column 15 alone —
-    ///   alpha 0 — and the whole of their visible existence is the `−0.97` U scroll.
-    /// - **FROZEN** — it draws, statically: the scroll is the motion it loses.
-    /// - **HELD** — keyed to a constant non-identity offset, so a lane that seeds none draws it
-    ///   mis-registered rather than still.
-    /// - **NEVER** / **UNKNOWN** — flagged, never counted as INVISIBLE: nothing painted at any
-    ///   point of the loop, or no alpha lane to judge from (`Mod`/`Mod2x`, an undecodable sheet).
-    ///
-    /// Each batch prints its per-axis reasoning (address mode, authored and frozen UV spans, the
-    /// texel indices those reach) so the call is checkable, and the report closes with the INVISIBLE
-    /// listing joined back through the chain: which spells reach it, and through which lifecycle
-    /// stage (`precast`/`cast`/`impact`/`state`/`channel`/`missile`/`area`).
+    /// Sweep every model the spell-visual chain reaches (kit effect slots, missile and
+    /// dest-anchored models) for batches whose texture transform animates, classed by what a
+    /// consumer running none of it draws, from the texture's alpha through its address mode:
+    /// `INVISIBLE` (frozen, it samples only transparent texels while the scroll reaches painted
+    /// ones), `FROZEN`, `HELD`, `NEVER` or `UNKNOWN`. It closes with the `INVISIBLE` batches joined
+    /// to the spells that reach them.
     Fxuvscan {
         /// Internal-path prefix filter (e.g. `spells`), case-insensitive; all reachable effect
         /// models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every model the **ENTITY lane** can render — every `CreatureDisplayInfo` →
-    /// `CreatureModelData` body (NPCs, critters, mounts, and every PLAYER, which resolves through
-    /// the same chain, decision 0041), every `GameObjectDisplayInfo` model, every
-    /// `ItemDisplayInfo` left/right model joined to the `Item\ObjectComponents\` folder the
-    /// archives actually hold it in, and the corpse lane's `<Race><Sex>DeathSkeleton` bone piles —
-    /// and census the batches whose **texture transform animates**, then classify each by what a
-    /// consumer that runs NONE of it renders.
-    ///
-    /// The twin of `Fxuvscan`, asked of the corpus that record's fix did NOT reach. Decision 2282
-    /// gave the spell-effect lane its texture transform and named this as its first deferral:
-    /// `model_render::batch::Materials::entity_variants` passed `play_uv = false`, and `build`
-    /// does `play_uv.then_some(sub.uv_anim.as_ref()).flatten()` — so every unit, player,
-    /// GameObject and held-item batch was handed no loop and drew its authored UVs, untransformed,
-    /// for ever. Nobody had measured how much content that is; this is that measurement, it is
-    /// what sized **decision 2295**, which closed it, and it shares `fxuvscan`'s whole per-batch
-    /// reader (`uv_batch`) so the two corpora cannot be judged by two different rules. It stays
-    /// because the census is how the claim "this lane needs no channel" is kept checkable — which
-    /// is the one thing 0271's deferral was missing.
-    ///
-    /// **Read the corpus from the tables, never from a path prefix.** "The path looks broken" and
-    /// "the path is reachable" are different questions and only the second one is worth a session
-    /// (2282's own closing note). A held item's directory is not even a column — the equipment lane
-    /// picks `Weapon`/`Shield`/`Shoulder`/`Head`/`Ammo`/`Quiver` from the slot the item is worn in
-    /// — so the sweep asks the archives which folder holds each display's basename, and expands a
-    /// helm stem into its sixteen per-race/sex files the way the attach does.
-    ///
-    /// The classes are `fxuvscan`'s, judged the same way — from the texture's own alpha through the
-    /// batch's authored address mode (INVISIBLE / NEVER / FROZEN / HELD / UNKNOWN; that command's
-    /// doc is where they are explained) — with one thing this corpus adds: a CREATURE batch's
-    /// `Monster1/2/3` sheet is **blank in the M2** and filled per display from
-    /// `CreatureDisplayInfo.textureVariation`, so one batch has as many sheets as the model has
-    /// skins and the verdict is asked once per skin. A character composite (body atlas, hair,
-    /// object skin) has no authored sheet at all and reads UNKNOWN, which is the honest answer
-    /// rather than a silent pass.
-    ///
-    /// **The load-bearing column is the CLOCK**, because it decides the SHAPE of the fix and not
-    /// merely its size:
-    ///
-    /// - **GSEQ** — every live loop rides a global sequence, a free-running per-scene clock the
-    ///   reference anchors once per instance at attach. One shared material uniform is faithful
-    ///   there; that is 0136 choice 1's lane, already built.
-    /// - **BAND** — every live loop rides its sequence band, i.e. the instance's own play head. Two
-    ///   units playing different animations, or the same one at different phases, are at different
-    ///   offsets, and no shared uniform can serve both: that is 2282's per-instance `UvLoop`.
-    /// - **MIXED** / **HOLD** — the batch's channels disagree, or it is keyed to a constant
-    ///   non-identity offset that needs a seed and no clock at all.
-    ///
-    /// Each affected batch prints its three channels (translation / rotation / scaling — a sweep
-    /// that looked only at translation would have missed `GroundingTotem_Impact` entirely, which is
-    /// scale-only), its per-axis texel reasoning, both frozen verdicts, its clock, which file
-    /// sequence slots carry the keys and what those sequences are *called*, and — where the bake
-    /// refused the shared lane — `uvslotscan`'s own `uniform()` verdict for the same set. The
-    /// report closes with every affected model sorted by POPULATION: how many table rows can put it
-    /// on screen, which is the difference between one gnome terminal and every murloc in the game.
-    ///
-    /// **And then the same corpus again for the M2COLOR TINT**, because the UV channel is not the
-    /// only one this lane drops. `build` passes `sub.rgb_anim.as_ref()` *unconditionally* — there
-    /// is no `play_rgb` to flip — so a tint-animating entity batch is seeded at the loop's first
-    /// key and then never re-sampled, because `doodad_anim::register_tint`'s only call sites (like
-    /// `register_uv`'s) are in the world streamer's `assemble.rs`. The hole is the missing
-    /// REGISTRATION, not a missing argument, which is why flipping `play_uv` alone would only
-    /// trade one frozen frame for another.
-    ///
-    /// A tint is a **multiply**, so its failure mode is the wrong colour rather than missing
-    /// geometry, and the classes say how wrong: BLACK (the frozen tint kills the batch), STRONG,
-    /// SLIGHT, NEGLIGIBLE — bands over one printed number, the worst per-channel distance between
-    /// the frozen value and anything the loop reaches. Two qualifications the raw count would
-    /// overstate without: a batch whose slot 0 bakes nothing seeds **white**, so it is the right
-    /// colour until a later slot's animation plays and wrong only *during* it (the `slots` line
-    /// names which); and the **ALPHA** channel is counted beside them precisely because this lane
-    /// DOES serve it — `attach::dress::spawn_part` gives every part a `MatAnim` that
-    /// `sample_mat_anim` ticks per instance. One of the three material-animation channels runs.
+    /// `fxuvscan`'s census over the entity lane's models, as the tables reach them: every
+    /// `CreatureDisplayInfo` body (players included), `GameObjectDisplayInfo` model,
+    /// `ItemDisplayInfo` model in whichever `Item\ObjectComponents\` folder holds it (a helm as its
+    /// 16 race and sex files) and `<Race><Sex>DeathSkeleton`. A creature's `Monster1/2/3` sheet is
+    /// filled per display from `textureVariation`, so each skin is judged. The clock column is
+    /// `GSEQ` (a global sequence, which the reference anchors once per instance at attach), `BAND`
+    /// (the instance's own play head), `MIXED` or `HOLD`. It then repeats for the M2Color tint
+    /// (`BLACK`, `STRONG`, `SLIGHT`, `NEGLIGIBLE`), with the alpha channel counted beside it.
     Entityuvscan {
         /// Internal-path prefix filter (e.g. `creature`), case-insensitive; all reachable entity
         /// models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and census the batches whose texture
-    /// coordinates are **GENERATED, not authored** — the sphere-map environment stages
-    /// (`texture_unit_lookup[texCoordSet] > 2`, the reference's gate at `0x70b8bd`). Such a batch
-    /// carries no usable UVs *by design* (the artist collapses the mesh onto one point because the
-    /// runtime supplies the coordinates), so a renderer that reads the vertex UV paints the whole
-    /// surface in **one texel** of a reflection sheet — silently, with no missing geometry to
-    /// notice. `DEGENERATE` marks exactly that population; the rest carry unused leftover UVs and
-    /// misdraw as a static smear instead. The instrument behind the Deeprun Tram glass tube.
+    /// Sweep every `.m2` for batches whose texture coordinates are generated, the sphere-map
+    /// stages (`texture_unit_lookup[texCoordSet] > 2`, the reference's gate at `0x70b8bd`). Their
+    /// UVs go unused by design; `DEGENERATE` marks those collapsed to one point, which a renderer
+    /// reading vertex UVs paints as one texel.
     Envmapscan {
         /// Internal-path prefix filter (e.g. `world`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` and report which sampler ADDRESS MODES the corpus asks of each texture
-    /// path, and how many paths are asked for more than one — the design check behind decision
-    /// 0763 (the mode lives on the sampler, which rides the `Image`, which is keyed by path).
+    /// Sweep every `.m2` and report the sampler address modes the corpus asks of each texture
+    /// path, and how many paths are asked for more than one.
     Texmodescan {
         /// Internal-path prefix filter, case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and count the two halves of the
-    /// **owner-last draw-order** law per model: the EFFECTS it authors (particle emitters +
-    /// ribbon trails) and the TRANSPARENT-pass batches of its own body those effects must draw
-    /// after (decisions 0719/0721), plus the model's reach and the draw-order rung that reach
-    /// produces. The population instrument for "how much does this fix, besides the one creature
-    /// it was found on": a model with effects AND transparent batches of its own is one whose
-    /// effects our distance sort could interleave with its own body; one without never had the
-    /// defect at all.
+    /// Sweep every `.m2` and count both halves of the owner-last draw order: each model's effects
+    /// (particle emitters and ribbons) and its own transparent-pass batches, with reach and rung.
     Fxordercensus {
         /// Internal-path prefix filter (e.g. `creature`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and census the **3-D model particles**:
-    /// emitters carrying a geometry-model reference, whose shard instances render the GEOMETRY
-    /// model's own submeshes stamped with the OWNER model's owner-last draw-order rung. Per
-    /// (owner, geometry) pair: the owner's rung and reach plus the geometry's material family
-    /// tuples (blend, two_sided, additive, no_depth_write, no_depth_test) — the exact keys the
-    /// shard materials are built from. The ground truth sizing the pipeline-warm menagerie's
-    /// shard rows: rung histogram, family-tuple set split by transparent-pass membership, and
-    /// the unresolvable-path bound.
+    /// Sweep every `.m2` for 3-D model particles, emitters whose shards draw a geometry model's
+    /// submeshes at the owner's draw-order rung: per (owner, geometry) pair, the rung, reach and
+    /// material family tuples the shard materials are built from.
     Shardcensus {
         /// Internal-path prefix filter (e.g. `spells`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and list the models where the
-    /// **loader-idle sequence is not file slot 0** while benilla's render content gate leaves it
-    /// unarmed — so every per-sequence bake (emission rate/gate, the nine parameter channels,
-    /// material alpha) degrades to slot 0, a sequence the instance is not playing. On the
-    /// `DuelingFlag`-shaped GameObjects (Spawn/Stand/Despawn) slot 0 is the **Spawn flourish**:
-    /// the population instrument for decision 0936, found on the Stormwind battlefield banner
-    /// pouring its spawn sparkle-tails for ever.
+    /// Sweep every `.m2` for models whose loader-idle sequence is not file slot 0 while benilla's
+    /// render content gate leaves them unarmed, so every per-sequence bake reads slot 0, a sequence
+    /// the instance is not playing; on `DuelingFlag`-shaped GameObjects that is the Spawn flourish.
     Idleslotscan {
         /// Internal-path prefix filter (e.g. `world`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` and census the **animation-driven sound emitters**: the models whose
-    /// sequences carry a `$DSL` (doodad sound loop) / `$DSE` (its release token) / `$DSO` (doodad
-    /// sound one-shot) / `$SND` (generic one-shot) marker, the `SoundEntries` kit each names with its 3D parameters, and —
-    /// the column this exists for — whether the carrying sequence is REST-posed, i.e. one the
-    /// render content gate (decision 0130) never builds a rig for. A placed lamp's hum is a single
-    /// `$DSL` on a sequence that keys no bone at all, so the whole class is unreachable through an
-    /// `AnimationPlayer`: the population instrument for "every world doodad is silent" (B345).
+    /// Sweep every `.m2` for animation sound markers (`$DSL` doodad loop, `$DSE` its release,
+    /// `$DSO` doodad one-shot, `$SND` one-shot) with each kit's 3-D parameters, and whether the
+    /// carrying sequence is rest-posed, one the render content gate builds no rig for.
     Soundeventscan {
         /// Internal-path prefix to limit the sweep (e.g. `world`); all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and list the models whose PARTICLE
-    /// emitters carry any of the given file-flag bits (`M2ParticleEmitter+0x04`) — the
-    /// population instrument for particle-flag mechanisms (which content actually authors
-    /// e.g. the `0x1000` plane-quad leg), so a class of effects is closed by mechanism
-    /// instead of tested spell-by-spell.
+    /// Sweep every `.m2` and list the models whose particle emitters carry any of the given
+    /// file-flag bits (`M2ParticleEmitter+0x04`).
     Partscan {
         /// The flag mask to match, hex or decimal (e.g. `0x1000`).
         mask: String,
         /// Internal-path prefix filter (e.g. `spells`), case-insensitive; all models if omitted.
         prefix: Option<String>,
     },
-    /// Sweep every `.m2` (optionally under a path prefix) and report which models author M2
-    /// dynamic LIGHT blocks — the population instrument for the mechanism (decision 0016 / wow-re
-    /// `system/models/scratch/m2-dynamic-lights.md`). Per model: its point (`type==1`, the GL
-    /// hot-spot caster) vs directional (ambient-feed) light counts, then per point light its
-    /// bone/position/diffuse colour×intensity/attenuation/visibility-gate. The closing summary —
-    /// totals, a breakdown by top-level content family (Creature/Item.ObjectComponents/
-    /// Character/World/Spells/other), and a diffuse-palette tally — is the real deliverable:
-    /// benilla only spawns these lights for ADT-placed doodads and WMO props today, so it answers
-    /// how much of the entity path (creatures, held items, GameObjects) is missing them.
+    /// Sweep every `.m2` for M2 dynamic lights (`0x718960`): per model its point (`type==1`) and
+    /// directional light counts, each point light's bone, position, colour, attenuation and
+    /// visibility gate, then totals by content family and a diffuse-palette tally.
     M2lightscan {
         /// Internal-path prefix filter (e.g. `item\objectcomponents`), case-insensitive; all
         /// models if omitted.
@@ -707,11 +404,9 @@ enum Command {
     /// Also the population instrument: which 1.12 buildings replace the `Light.dbc` gradient dome
     /// with an authored sky (Stratholme's burning city is the only one reachable), and how much
     Skyboxscan,
-    /// Dump all 18 `LightIntBand` rows of the `Light.dbc` entry covering a world position at a
-    /// time of day — the band-semantics instrument (which row holds which colour at which hour;
-    /// the celestial-diffuse band question, decision 0485). ⚠ This is ONE params record RAW —
-    /// near a sphere's falloff edge the LIVE light is mostly the continent global and looks
-    /// nothing like these rows; `lightblend` shows what actually wins at the position (0706).
+    /// Dump all 18 `LightIntBand` rows of the `Light.dbc` entry covering a position at a time of
+    /// day. One params record, raw: near a sphere's falloff edge the live light is mostly the
+    /// continent global, and `lightblend` shows what wins there.
     Lightbands {
         /// Map id (0 = Eastern Kingdoms, 1 = Kalimdor).
         map: u32,
@@ -727,21 +422,18 @@ enum Command {
         /// Game minute-of-day (0..1440; 720 = noon).
         minute: u32,
     },
-    /// Dump every `LightIntBand`/`LightFloatBand` row of an explicitly named `LightParams` id — the
-    /// instrument for rows **no position can reach**, because nothing in `Light.dbc` references them:
-    /// magma submersion reads the fixed global row 7 and slime row 6 (VERIFIED `0x6d2371`), not the
-    /// zone's underwater slot.
+    /// Dump every `LightIntBand` and `LightFloatBand` row of a named `LightParams` id, for rows no
+    /// position reaches: magma submersion reads the fixed global row 7 and slime row 6
+    /// (`0x6d2371`), not the zone's underwater slot.
     Lightparam {
         /// `LightParams.dbc` id (1-based).
         id: u32,
         /// Game minute-of-day (0..1440; 720 = noon).
         minute: u32,
     },
-    /// Dump the **per-weather-slot** light resolve at a world position: which `LightParams` id each
-    /// of the five `Light.dbc` slots names (clear / clear-underwater / storm / storm-underwater /
-    /// death), which of them are UNSET (and so fall back to clear), and the fog/ambient/diffuse the
-    /// blend resolves for each. `lightbands` only ever shows the clear slot, so an underwater or
-    /// ghost atmosphere that reads wrong could not be told from data that simply has no such record.
+    /// Dump the per-weather-slot light resolve at a position: the `LightParams` id each of the five
+    /// `Light.dbc` slots names (clear, clear underwater, storm, storm underwater, death), the unset
+    /// ones that fall back to clear, and each one's fog, ambient and diffuse.
     Lightslots {
         /// Map id (0 = Eastern Kingdoms, 1 = Kalimdor).
         map: u32,
@@ -757,11 +449,8 @@ enum Command {
         /// Game minute-of-day (0..1440; 720 = noon).
         minute: u32,
     },
-    /// Dump every light SPHERE covering a world position — distance, falloff, blend alpha, each
-    /// sphere's clear ambient/sun — then the faithful area-blend result vs the single `pick_light`
-    /// sample. The instrument for "which palette actually wins HERE": a position near a zone
-    /// sphere's falloff edge resolves mostly the continent global, and the raw per-params band dump
-    /// (`lightbands`) cannot show that.
+    /// Dump every light sphere covering a position (distance, falloff, blend alpha, clear ambient
+    /// and sun), then the area-blend result against the single `pick_light` sample.
     Lightblend {
         /// Map id (0 = Eastern Kingdoms, 1 = Kalimdor).
         map: u32,
@@ -777,9 +466,8 @@ enum Command {
         /// Game minute-of-day (0..1440; 720 = noon).
         minute: u32,
     },
-    /// Bulk-scan placed doodads (MDDF) and WMO doodad-set-0 props (MODF → MODS/MODD) across a
-    /// `(2·tile_radius+1)²` block of ADT tiles around a world position, and report how much of that
-    /// content animates (see `m2anim`) — the doodad-animation perf/scope instrument.
+    /// Scan placed doodads (MDDF) and WMO doodad-set-0 props (MODF, MODS, MODD) over a
+    /// `(2·tile_radius+1)²` block of ADT tiles around a position, and report how much animates.
     Doodadscan {
         /// Map directory name (e.g. `Azeroth`).
         map: String,
@@ -792,14 +480,11 @@ enum Command {
         /// ADT tile radius around the center tile to scan (0 = just the containing tile).
         tile_radius: u32,
     },
-    /// Dump a WMO root's placed-prop tables: every MODD doodad with its MODS set membership and
-    /// its OWNING group(s) read from the group files' MODR lists — the relation the reference
-    /// instantiates from (a *visible* group's own refs, `0x695aa0`), so a prop referenced by NO
-    /// group is one the real client never creates at all (the divergence decision 0689 names,
-    /// which benilla still spawns). The "which props exist in this building, who owns them, and
-    /// which would the reference even draw" instrument.
+    /// Dump a WMO root's placed props: each MODD doodad with its MODS sets and the groups whose
+    /// MODR names it. The reference creates props only from a group's MODR refs (`0x695aa0`), so
+    /// it never creates one no group names; benilla still spawns those.
     Wmodoodads {
-        /// Internal path to the WMO **root** (forward or back slashes accepted).
+        /// Internal path to the WMO root (forward or back slashes accepted).
         internal_path: String,
         /// Case-insensitive substring of the prop's model path (e.g. `lightray`); all if omitted.
         filter: Option<String>,
@@ -843,11 +528,8 @@ enum Command {
         /// Internal-path prefix to limit the sweep (e.g. `world\wmo\azeroth`); all if omitted.
         prefix: Option<String>,
     },
-    /// List individual doodad (MDDF) and WMO (MODF) placements around a world position whose
-    /// model path contains a substring — position, Euler rotation (deg), scale, uniqueId. The
-    /// "point at a thing in the world, tell me exactly how it's placed" instrument: an
-    /// orientation bug needs the placement rotation as ground truth, which `doodadscan`'s
-    /// aggregates never show.
+    /// List the doodad (MDDF) and WMO (MODF) placements around a position whose model path
+    /// contains a substring: position, Euler rotation (deg), scale and uniqueId.
     Placescan {
         /// Map directory name (e.g. `Azeroth`).
         map: String,
@@ -862,12 +544,9 @@ enum Command {
         /// Case-insensitive substring of the model path (e.g. `instanceportal`).
         filter: String,
     },
-    /// Print the terrain MCSH baked-shadow bit at a world position — the per-instance
-    /// terrain-shade selector an exterior M2 doodad samples once at its base (sun intensity
-    /// 2.5 lit / 0.5 shadowed, `0x69e4ad`; decisions 0063/0747) — plus an ASCII texel
-    /// neighborhood. A doodad base near a shadow edge sits one ~0.52 yd texel from the OTHER
-    /// intensity family, so two adjacent fence pieces can land on opposite sides — the
-    /// "why is ONE of these blown out" instrument.
+    /// Print the terrain MCSH baked-shadow bit at a position, which an exterior M2 doodad samples
+    /// once at its base (sun scale 1.0 lit, 0.5 shadowed, `0x698cb4`), and the texel
+    /// neighbourhood: one ~0.52 yd texel can split adjacent pieces across a shadow edge.
     Shadeat {
         /// Map directory name (e.g. `Azeroth`).
         map: String,
@@ -885,10 +564,8 @@ fn normalize(path: &str) -> String {
     path.replace('/', "\\")
 }
 
-/// The grouping/lookup key for a model path referenced from MDDF/MODD (`doodadscan`'s instance
-/// tables): lowercase, `.mdx`/`.mdl` → `.m2`. Mirrors `benilla_formats`' own (crate-private)
-/// `model_path` normalization so two placements of the same model authored under different
-/// casing/extension collapse to one row instead of double-counting it.
+/// A placed model path's grouping key, lowercase with `.mdx`/`.mdl` as `.m2`; it must match
+/// `benilla_formats`' crate-private `model_path` normalization.
 fn model_key(raw: &str) -> String {
     let lower = raw.to_ascii_lowercase();
     match lower
@@ -908,7 +585,6 @@ fn parse_u32_maybe_hex(s: &str) -> Result<u32> {
     }
 }
 
-/// `"yes"`/`"-"` for a compact table cell.
 fn yn(b: bool) -> &'static str {
     if b {
         "yes"
@@ -987,7 +663,7 @@ fn main() -> Result<()> {
             output,
         } => {
             let name = normalize(&internal_path);
-            // Note which archive the file resolved from (handy for debugging overrides).
+            // The archive the file resolved from, which shows an override.
             let source = chain
                 .find_file_archive(&name)
                 .map(|p| p.display().to_string());
diff --git a/crates/benilla-formats/src/bin/benilla-extract/scan/geometry.rs b/crates/benilla-formats/src/bin/benilla-extract/scan/geometry.rs
index e4578f8e..42c1c3c1 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/scan/geometry.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/scan/geometry.rs
@@ -1,38 +1,22 @@
-//! Corpus scans over **what geometry a model draws** — the shape of its batches, independent of
-//! how they are textured or shaded.
-//!
-//! Billboard cards and which way they face (`bbscan`, `bbfacescan`), geosets and the untextured /
-//! single-triangle strays (`geosetscan`), flat ground-plane quads (`groundscan`), and degenerate
-//! authored vertex normals (`normalscan`). What MATERIAL a batch carries is [`super::material`]'s
-//! question.
+//! Corpus scans over a model's geometry: billboards, geosets, ground quads, bounds, normals.
 
 use std::collections::{BTreeMap, HashMap};
 
 use anyhow::Result;
 use benilla_formats::Chain;
 
-/// Sweep every `.m2` (under `prefix`, if given) and classify every BILLBOARD batch by which way its
-/// geometry faces — see the `Bbfacescan` command doc for why the sign decides visibility.
-///
-/// A billboard bone puts the model's **+X** toward the viewer (`billboard-bone-law`, spherical arm),
-/// so a batch whose winding normal is +X faces the camera and a −X one faces away. Single-sided
-/// (`two_sided` false, i.e. no material `0x04`), the away-facing ones are backface-culled by the
-/// reference from every angle — they are authored placeholders the author never saw.
+/// Classify every billboard batch by facing: a billboard bone turns the model's +X toward the
+/// viewer (the spherical arm, `0x71547c`), so a single-sided batch (no material `0x04`) whose
+/// winding faces −X is culled by the reference from every angle.
 pub fn bbfacescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut cards) = (0u32, 0u32);
-    // The four card populations. `away_single` is the one the renderer's forced-two-sided override
-    // changes: those and only those become visible when a card is not allowed to be culled.
+    // The four card populations; `away_single` is what a forced two-sided draw would reveal.
     let (mut toward, mut away_single, mut away_two, mut edge_on) = (0u32, 0u32, 0u32, 0u32);
-    // …and the batches that are not cards at all. A facing only exists for a batch that IS one
-    // plane; a closed solid has faces every way round, backface culling never hides it, and
-    // sampling its first triangle answers a question it doesn't have (see `plane_normal`).
+    // Billboard batches that are not one plane: a solid has no single facing.
     let mut solid = 0u32;
-    // …and the other side of the same gate: batches the split REFUSED because their geometry is
-    // welded to a billboard bone (`RenderSubmesh::welded_billboard`, decisions 0839/0841). These
-    // carry no `billboard` at all, so the card loop below never sees them — they are counted from
-    // the flag the render lanes read, which is what makes this a cross-check of `bbscan`'s SEAM
-    // column (same models, counted from the two ends of the rule) rather than a re-derivation.
+    // Batches the card split refused as welded to a billboard bone: they carry no `billboard`,
+    // so they are counted from the render lanes' flag, a cross-check of `bbscan`'s SEAM column.
     let (mut welded, mut weld_models) = (0u32, 0u32);
     for name in names {
         let Ok(bytes) = chain.read_file(&name) else {
@@ -50,12 +34,10 @@ pub fn bbfacescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         for (i, s) in subs.iter().enumerate() {
             let Some(bb) = &s.billboard else { continue };
             cards += 1;
-            // Not one plane ⇒ not a card. Counted apart rather than classified by a triangle.
             if s.plane_normal().is_none() {
                 solid += 1;
                 continue;
             }
-            // The winding normal's X component: +1 faces the viewer, −1 faces away.
             let Some(fx) = facet_x(s) else {
                 edge_on += 1;
                 continue;
@@ -96,8 +78,7 @@ pub fn bbfacescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// The X component of a batch's first-triangle winding normal, in WoW model space — `None` when the
-/// triangle is degenerate or the normal lies in the YZ plane (nothing to decide a facing from).
+/// The X of a batch's first-triangle unit winding normal, WoW model space; `None` if degenerate.
 fn facet_x(s: &benilla_formats::RenderSubmesh) -> Option<f32> {
     let tri = s.indices.get(..3)?;
     let p = |i: u32| s.positions.get(i as usize).copied();
@@ -115,11 +96,8 @@ fn facet_x(s: &benilla_formats::RenderSubmesh) -> Option<f32> {
     (len > 1e-9).then(|| n[0] / len)
 }
 
-/// The widest max/min axis spread a scale track ever holds — `1.0` for a uniform track (the
-/// overwhelming majority: a glow card that only pulses in size), `> 1` for one that stretches its
-/// bone along an axis. A key with an axis at or below zero contributes `1.0`: a zero axis is the
-/// reference's own "hide this" (the eyelid blink's retracted lid), not a stretch, and dividing by
-/// it would report infinity.
+/// The widest max/min axis ratio a scale track holds, 1 for uniform. A key with an axis at zero
+/// counts as 1: a zero axis hides the bone (the eyelid blink), it does not stretch it.
 fn scale_spread<T>(keys: &[(T, [f32; 3])]) -> f32 {
     keys.iter()
         .map(|(_, s)| {
@@ -135,24 +113,12 @@ fn scale_spread<T>(keys: &[(T, [f32; 3])]) -> f32 {
         .fold(1.0f32, f32::max)
 }
 
-/// Sweep every `.m2` (under `prefix`, if given) and classify its billboard usage — see the
-/// `Bbscan` command doc. Output per model: the authored arms and how many vertices ride each
-/// DIRECTLY (primary bone is the billboard bone — the card path) vs INHERITED (primary bone
-/// descends from one — the joint-palette path, decision 0205), then the same question for the
-/// model's **particle emitters and ribbons** (`fx[…]`) — the population behind decision 0813: an
-/// emitter on (or under) a billboard bone has a camera-dependent origin, because the reference
-/// folds the record position through the *replaced* palette matrix
-/// (wow-re `part-anchoring-live-bone.md` §1 row 3 · `m2emitspine::particle_bone_xform`).
-///
-/// The `NONUNIF[…]` column is the third population: billboard bones whose SCALE is animated
-/// **non-uniformly** (in any sequence band, or on a global-sequence loop), listed as
-/// `bone:arm×ratio` where the ratio is the widest max/min axis spread the bone ever holds. The
-/// billboard law preserves the bone's scale under the substituted camera basis (`T·R_cam·S`), so
-/// such a bone stretches its card along one model axis — the Lightwell's lock-Z shaft
-/// (`World\Goober\G_HolyLightWell.m2` bone 0, `×4.26`) is a 0.12 yd card pulled into a 4.5 yd
-/// column of light. Any consumer that reduces the scale to one scalar renders these squat and
-/// blown-out instead (bug B169), and a `d` in the direct column is where that lands on a **card**,
-/// whose transform is rebuilt from the joint rather than skinned from it.
+/// Per model with billboard bones, the vertices riding each arm directly (the card path) or
+/// through a descendant (the palette path), and three populations: `fx[…]`, emitters and ribbons
+/// on a billboard chain, whose position the reference folds through the replaced palette matrix
+/// (`0x7190a9`–`0x71910c`); `SEAM[…]`, bones the card split refuses; `NONUNIF[…]`,
+/// `bone:arm×ratio` for non-uniform animated scale, which the reference keeps under the camera
+/// basis (`T·R_cam·S`), so the card stretches along one axis (`G_HolyLightWell.m2` bone 0, ×4.26).
 pub fn bbscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let arm = |k: benilla_formats::BillboardKind| match k {
@@ -165,14 +131,9 @@ pub fn bbscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     // Corpus totals: models exercising each arm, split by how the geometry rides it.
     let mut direct_models: HashMap<&'static str, u32> = HashMap::new();
     let mut inherited_models: HashMap<&'static str, u32> = HashMap::new();
-    // …and the effect riders (particles/ribbons on a billboard chain).
     let mut fx_models = 0u32;
     let mut fx_total: HashMap<String, u32> = HashMap::new();
-    // …and the seam population (see the classification below).
     let (mut seam_models, mut seam_bones) = (0u32, 0u32);
-    // …and the non-uniform-scale population: billboard bones that stretch their card along one
-    // model axis, split by whether geometry rides them DIRECTLY (the card path, where a scalar
-    // scale loses the stretch outright) or only by inheritance (the palette path).
     let (mut nonunif_models, mut nonunif_bones, mut nonunif_direct) = (0u32, 0u32, 0u32);
     for name in names {
         let Ok(bytes) = chain.read_file(&name) else {
@@ -192,9 +153,8 @@ pub fn bbscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         }
         hits += 1;
-        // Nearest billboard ancestor (self included) per bone — the arm whose palette
-        // replacement a vertex on this bone inherits. Bounded walk (M2 parents precede
-        // children; the bound is just a malformed-file guard).
+        // The nearest billboard bone at or above `i`, whose palette replacement a vertex on `i`
+        // inherits; the bound guards a malformed parent chain.
         let ancestor_arm = |mut i: usize| -> Option<(bool, benilla_formats::BillboardKind)> {
             let mut hops = 0;
             loop {
@@ -218,22 +178,15 @@ pub fn bbscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 None => {}
             }
         }
-        // SEAM bones: billboard bones whose geometry is welded to the rest of the model — by a
-        // partial vertex weight, or by a triangle it shares with a static neighbour. The reference
-        // skins per vertex, so such geometry BENDS (a flap's root stays on the body while its tip
-        // swings to the camera); a rigid card cannot express that at all, and moving the group
-        // rigidly tears the flap in two. These are the bones the split declines (decision 0839),
-        // read through the renderer's own predicate so this census cannot drift from it.
+        // SEAM: billboard bones welded to the model by a partial weight or a shared triangle. The
+        // reference skins per vertex, so the geometry bends; a rigid card would tear it.
         let seam = benilla_formats::non_separable_billboard_bones(&bytes);
         let fmt_counts = |m: &HashMap<&str, u32>| {
             let mut v: Vec<String> = m.iter().map(|(k, n)| format!("{k}:{n}")).collect();
             v.sort();
             v.join(" ")
         };
-        // The EFFECT riders: a particle emitter / ribbon whose bone chain reaches a billboard
-        // bone has a camera-dependent live frame (its record position rides the replaced palette
-        // matrix), so a consumer that places it at the rest pose puts it in the wrong place.
-        // `d` = the effect's own bone is the billboard bone, `i` = it descends from one.
+        // Effects on a billboard chain: `d` on the billboard bone itself, `i` below one.
         let mut fx: HashMap<String, u32> = HashMap::new();
         let mut tally = |tag: &str, bone: u16| {
             if let Some((direct, k)) = ancestor_arm(bone as usize) {
@@ -259,7 +212,6 @@ pub fn bbscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             v.join(" ")
         };
         let bones: String = kinds.iter().flatten().map(|&k| arm(k)).collect();
-        // NON-UNIFORM billboard scale (see the `NONUNIF` column in the doc above).
         let seqs = benilla_formats::parse_m2_animations(&bytes);
         let gseq = benilla_formats::parse_m2_global_sequence_bones(&bytes);
         let mut nonunif: BTreeMap<usize, f32> = BTreeMap::new();
@@ -278,16 +230,14 @@ pub fn bbscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 *e = e.max(r);
             }
         }
-        // Only the BILLBOARD bones matter — an ordinary bone's non-uniform scale rides the joint
-        // palette like any other transform and nothing reduces it.
+        // Only billboard bones: an ordinary bone's scale rides the joint palette unreduced.
         nonunif.retain(|&b, _| kinds.get(b).copied().flatten().is_some());
         let nonunif_col = if nonunif.is_empty() {
             String::new()
         } else {
             nonunif_models += 1;
             nonunif_bones += nonunif.len() as u32;
-            // Does geometry ride this bone DIRECTLY (primary bone == it, and separable)? That is
-            // the card path — where the stretch has to survive a transform rebuild.
+            // The card path: geometry rides the bone directly and the split accepts it.
             let direct_bone = |b: usize| {
                 !seam.contains(&(b as u16))
                     && m.vertices.iter().any(|v| v.bone_indices[0] as usize == b)
@@ -369,29 +319,15 @@ pub fn bbscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (under `prefix`, if given) and census the **geometry a non-character model
-/// draws that the reference may not** — the population instrument behind the bug channel's
-/// "stray untextured primitive" family. Three independent signals per model, all read through the
-/// renderer's own batch resolution (`m2batch`'s), so the report can't drift from the mechanism:
-///
-/// - **MULTI-GEOSET** — more than one distinct `skinSectionId`. The character compositor selects
-///   among these; every other spawn path draws **all** of them, so this is exactly the population
-///   an unfiltered creature/doodad/effect draw over-renders (`Creature\Banshee\Banshee.m2` is the
-///   pinned case: `0`×17 + `402`×9).
-/// - **UNTEX** — batches with no texture *and* no runtime slot that fills one: neither a character
-///   composite slot ([`benilla_formats::RenderSubmesh::char_slot`]) nor a creature skin variation
-///   ([`benilla_formats::RenderSubmesh::skin_slot`], filled at spawn from `CreatureDisplayInfo`).
-///   Both fills are ordinary, so counting them would drown the signal — 324 of 420 `Creature\`
-///   models carry a skin slot. What is left is geometry nothing can texture.
-/// - **TINY** — batches of at most 2 faces: the literal single-triangle/quad primitives.
-///
-/// A model is listed when it trips any of the three. `m2batch` then explains one model in full.
+/// List the models whose batches trip any of three signals, read through the renderer's own
+/// batch resolution: `MULTI-GEOSET`, more than one `skinSectionId` (the reference builds every
+/// geoset visible, `0x70ebd0`, and only the character compositor hides any); `UNTEX`, no texture
+/// and no character or creature-skin slot to fill one; `TINY`, at most two faces.
 pub fn geosetscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut hits) = (0u32, 0u32);
     let (mut multi_models, mut untex_models, mut tiny_models) = (0u32, 0u32, 0u32);
-    // Top-level directory → multi-geoset model count, so the report says *where* the population
-    // lives (Creature/, Spells/, World/…) rather than only how big it is.
+    // Top-level directory → multi-geoset model count.
     let mut by_dir: BTreeMap<String, u32> = BTreeMap::new();
     for name in names {
         let Ok(bytes) = chain.read_file(&name) else {
@@ -463,26 +399,17 @@ pub fn geosetscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (under `prefix`, if given) and report models that author flat ground-plane
-/// render geometry — the population instrument for the class of spell effects that lie in the
-/// model-space XY plane at z≈0 (WoW axes, Z up) and get buried by sloped terrain (Battle Shout's
-/// crescents are the canonical case: 6 batches, each a 4-vert quad, every vertex exactly z=0, each
-/// quad skinned 100% to a single bone). Per batch (same batch/geoset resolution `m2batch` uses):
-/// FLAT if every vertex has `|z| <= 0.01` in model space; flat batches sub-classify QUAD-1BONE
-/// (the crescent shape — [`benilla_formats::RenderSubmesh::ground_quad`], the ground-fx decal
-/// lane's own detector) vs OTHER-FLAT (flat but not that shape, staying on the ordinary render
-/// path) — which decides how general the renderer mechanism has to be.
+/// List the models with flat batches, every vertex at model-space `|z| <= 0.01`: effects that lie
+/// on the ground, which sloped terrain buries (Battle Shout's six single-bone quads). A flat batch
+/// is `QUAD-1BONE` when [`benilla_formats::RenderSubmesh::ground_quad`], the decal lane's
+/// detector, takes it, else `OTHER-FLAT`.
 pub fn groundscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut hits, mut all_flat, mut mixed) = (0u32, 0u32, 0u32, 0u32);
     let (mut quad_total, mut other_total) = (0u32, 0u32);
-    // The hover census: every ground-quad-SHAPED batch whose uniform plane sits ABOVE z = 0
-    // (any height — the shape test is the renderer's own, the ceiling is lifted), the population
-    // that decides where the decal lane's hover ceiling (`GROUND_HOVER_MAX`) can sit.
+    // Quad-shaped batches whose plane sits above z = 0, uncapped: where `GROUND_HOVER_MAX` can sit.
     let mut hovers: Vec<(f32, String)> = Vec::new();
-    // The TINT census: ground quads whose whole colour is a CONSTANT M2Color
-    // (`GroundQuad::tint`) — the population a decal consumer draws white unless it carries the
-    // vertex-colour bake across (the Flare's two washes on the neutral `GENERICGLOW*` radials).
+    // Ground quads with a constant M2Color tint (`GroundQuad::tint`), which a decal must carry.
     let (mut tinted_total, mut tinted_models) = (0u32, 0u32);
     for name in names {
         let Ok(bytes) = chain.read_file(&name) else {
@@ -516,9 +443,6 @@ pub fn groundscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             if !blend_modes.contains(&bm) {
                 blend_modes.push(bm);
             }
-            // The RENDERER's own detector, so this report is exactly what the ground-fx
-            // decal lane will do with each batch — the instrument can't drift from the
-            // mechanism it measures.
             if let Some(q) = s.ground_quad() {
                 quad_count += 1;
                 if q.tint != [1.0; 3] && !tints.contains(&q.tint) {
@@ -590,24 +514,10 @@ pub fn groundscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (under `prefix`, if given) and measure how far its authored header bounding
-/// box — the model's **all-animation** vertex extent, and the box the reference derives its doodad
-/// cull sphere from — reaches past its **bind-pose** vertex extent.
-///
-/// The population instrument for decision 1259. A placed model's submesh entity keeps its transform
-/// at the placement origin while the joint palette moves its vertices, so a bind-pose mesh bound
-/// stops describing what is drawn the moment the model animates: cull with it and the object blinks
-/// out while its geometry is still on screen. `SLACK` is how many yards the authored box reaches
-/// past the bind-pose box on its worst face — for the ambient critters (birds, bats, butterflies,
-/// wasps) that is tens of yards against a sub-yard body, which is the whole bug.
-///
-/// `SHORT` is the same measure with the signs reversed: yards of bind-pose geometry sticking out of
-/// the *authored* box. It is not zero in the shipped corpus, which is why the fix unions the two
-/// boxes instead of swapping one for the other — the reference never trips over it because it tests
-/// the box's circumsphere, which swallows the overhang.
-///
-/// `ANIM` marks the models the widened bound actually applies to: any bone track with more than one
-/// key, or any global-sequence bone channel. A static model keeps its tighter per-batch bound.
+/// Rank the animated models by how far the header box, the all-animation extent the reference
+/// builds its doodad cull sphere from, reaches past the bind-pose vertex extent (`SLACK`, yards on
+/// the worst face): a bind-pose bound culls such a model while its geometry is on screen. `SHORT`
+/// is bind-pose geometry outside the header box, which the reference's circumsphere swallows.
 pub fn animboundscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     // (slack, short, animates, bind-pose half-diagonal, name)
@@ -651,8 +561,7 @@ pub fn animboundscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         let half_diag =
             ((hi[0] - lo[0]).powi(2) + (hi[1] - lo[1]).powi(2) + (hi[2] - lo[2]).powi(2)).sqrt()
                 * 0.5;
-        // "Animates" the way `doodad_anim::classify` means it: geometry that MOVES relative to the
-        // placement transform — a keyed bone track, or a free-running global-sequence channel.
+        // Animates as `doodad_anim::classify` means it: a keyed bone track or a global sequence.
         let keyed = benilla_formats::parse_m2_animations(&bytes)
             .iter()
             .any(|a| {
@@ -682,9 +591,7 @@ pub fn animboundscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         "{:>9}  {:>8}  {:>9}  {:>4}  MODEL",
         "SLACK", "SHORT", "BIND-R", "ANIM"
     );
-    // The class the bug is about: the authored box dwarfs the body, so the animation carries the
-    // model clean out of any bind-pose bound. Ranked by that ratio, not by raw slack — a 200 yd
-    // waterfall with 200 yd of slack is never culled either way.
+    // Ranked by slack over body size: a large model with large slack is never culled either way.
     let mut ranked: Vec<&(f32, f32, bool, f32, String)> =
         rows.iter().filter(|r| r.2 && r.0 > 1.0).collect();
     ranked.sort_by(|a, b| (b.0 / b.3.max(0.05)).total_cmp(&(a.0 / a.3.max(0.05))));
@@ -697,18 +604,10 @@ pub fn animboundscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// `normalscan` — census the batches carrying **degenerate authored vertex normals** (`(0,0,0)`).
-///
-/// The shipped corpus authors them, and the reference draws those surfaces lit: its `Model2.bls`
-/// vertex program consumes the normal as the zero vector, so the order-2 SH quadratic form
-/// collapses to its DC term (wow-re `models/scratch/model2-bls-vertex-sh.md` §2). A renderer that
-/// `normalize()`s the same datum gets NaN, `clamp(NaN, 0, 1)` floors the lighting factor to 0, and
-/// the batch renders **pure black over its correct texture** — bug B134's Qiraji Brainwasher
-/// sleeves and Ironaya skirt, and the reason the shader's normalize is guarded (decision 1268).
-///
-/// This is the population instrument for that class: how many models are on it, how much of each
-/// batch is degenerate, and which models are worst hit. `ALL` marks a batch with no usable normal
-/// at all — the one that renders as a solid black shape rather than a shaded gradient.
+/// Census the batches with degenerate `(0,0,0)` authored normals. The reference lights them: its
+/// `Model2.bls` vertex program takes the zero normal as is, collapsing the order-2 SH form to its
+/// DC term, where a `normalize()` gives NaN and draws the batch black. `ALL` marks a batch with no
+/// usable normal.
 pub fn normalscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     // (degenerate verts, total verts, batches touched, all-degenerate batches, model)
diff --git a/crates/benilla-formats/src/bin/benilla-extract/scan/lighting.rs b/crates/benilla-formats/src/bin/benilla-extract/scan/lighting.rs
index 1b3ff638..a96b5013 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/scan/lighting.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/scan/lighting.rs
@@ -14,23 +14,11 @@ use benilla_formats::{Chain, M2Light};
 
 use crate::model_key;
 
-/// Sweep every WMO **root** (under `prefix`, if given) and list the placed MODD props whose
-/// INTERIOR lighting lane commits **literal black**.
-///
-/// The interior lane's whole base light is the MODD entry's own baked colour field: ambient =
-/// `cap96(colour)`, diffuse = `floor112(colour)` (`0x694e90` create → `0x6a77e0`; wow-re
-/// `trace-forensics-abbey-interior-d3d` §1.1). The floor leg *raises* a dim colour to max 112 — but
-/// it is a hue-preserving scale by `112/max`, so a colour of exactly `#000000` has nothing to raise
-/// and both words come out zero. Such a prop is lit by nothing but its owning group's MOLR fixture
-/// lights, and a group carrying none (or none within its authored attenuation disk) leaves it a
-/// pure black silhouette.
-///
-/// The colour field is zero on ~3% of shipped MODDs — the baker leaves it unbaked for props it
-/// treats as exterior — so what decides the symptom is the **class of the groups that reference the
-/// prop**, and EXTERIOR WINS (decision 0969: the reference's def is per (MODD, placement) and
-/// `0x695aa0` makes the exterior bit absorbing). A prop any exterior group's MODR names is therefore
-/// sky-lit and never listed here; the `RESCUED` tally counts them, because taking the *first*
-/// referrer instead is exactly what drew Booty Bay's entrance arch as a black silhouette.
+/// List the placed MODD props that the interior lane lights literal black. Its base light is the
+/// MODD colour, ambient `cap96`, diffuse `floor112` (`0x694e90` → `0x6a77e0`), and the floor is a
+/// hue-preserving scale by `112/max`, so `#000000` stays black and only the owning group's MOLR
+/// lights reach the prop. Exterior wins: any exterior referrer makes the prop sky-lit
+/// (`0x695aa0`); `RESCUED` counts those an interior group names first.
 pub fn darkpropscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let roots = super::wmo_roots(chain, prefix)?;
 
@@ -46,7 +34,6 @@ pub fn darkpropscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         };
         roots_scanned += 1;
         modds_total += root.doodads().len() as u32;
-        // Nothing to classify without a zero-colour MODD — skip the group reads entirely.
         if !root.doodads().iter().any(|d| d.color[..3] == [0, 0, 0]) {
             continue;
         }
@@ -80,11 +67,10 @@ pub fn darkpropscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             }
             zero_colour += 1;
             let Some(referrers) = refs.get(&(i as u16)) else {
-                continue; // ORPHAN: no group names it — the exterior default
+                continue; // no group names it: lit as exterior
             };
             let owner = referrers[0];
-            // EXTERIOR WINS over every interior referrer (decision 0969) — the MODD-colour lane is
-            // for props referenced by interior groups ONLY.
+            // Exterior wins over every interior referrer.
             if !referrers
                 .iter()
                 .all(|g| infos.get(*g as usize).is_some_and(|gi| gi.interior))
@@ -94,9 +80,8 @@ pub fn darkpropscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 }
                 continue;
             }
-            // The owning group's MOLR omni lights, gated by their own attenuation disk measured
-            // from the prop's origin (the spawn fold uses the loaded M2's bounds reference point;
-            // the origin is within a model radius of it, so this is the census approximation).
+            // The owning group's MOLR omni lights in range of the prop's origin; the spawn measures
+            // from the M2's bounds reference point, within a model radius of it.
             let in_range = light_refs
                 .get(&owner)
                 .map(|ls| {
@@ -158,11 +143,10 @@ pub fn darkpropscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// How many rows of the closing colour tally print (the rest are counted, never silently dropped).
+/// Rows of the closing colour tally that print; the rest are counted.
 const TALLY_ROWS: usize = 20;
 
-/// Cheap warm/cool/neutral hue classification of a `diffuse_color`, used only to eyeball the
-/// colour-tally section of `m2lightscan`'s summary — the warm-torch family vs anything unusual.
+/// A rough warm, cool or neutral tag for a light colour in `m2lightscan`'s tally.
 fn hue_tag(r: f32, g: f32, b: f32) -> &'static str {
     if r >= g && r > b * 1.15 {
         "warm"
@@ -173,9 +157,7 @@ fn hue_tag(r: f32, g: f32, b: f32) -> &'static str {
     }
 }
 
-/// Per-family tally for `m2lightscan`'s summary: how many models in this content family carry
-/// lights, how many `type==1` point lights they author in total, how many of those are dark
-/// (`visibility_off`), and a handful of example paths.
+/// One content family's row in `m2lightscan`'s summary; `dark` counts `visibility_off` lights.
 #[derive(Default)]
 struct FamilyStats {
     models: u32,
@@ -184,23 +166,14 @@ struct FamilyStats {
     examples: Vec<String>,
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and report which models author M2 dynamic
-/// LIGHT blocks — the population instrument for the mechanism (decision 0016 / wow-re
-/// `system/models/scratch/m2-dynamic-lights.md`). Per model (only models with ≥1 light, printed
-/// sorted by path): its `type==1` point-light count vs directional (`type==0`, ambient-feed, not
-/// a discrete GL light) count, then per POINT light: bone, model-space position, `diffuse_color ×
-/// diffuse_intensity` (raw colour, intensity, and the product), authored attenuation start/end,
-/// and an `OFF` tag when [`M2Light::visibility_off`] — the one shape (a static `0` visibility
-/// key) that keeps a light dark (§9.4). The closing summary is the real deliverable: totals, a
-/// breakdown by top-level content family ([`super::family_of`]) — benilla only spawns these
-/// lights for ADT-placed doodads and WMO props today, so this answers how much of the entity path
-/// (creatures, held items, GameObjects) is actually missing them — and a cheap diffuse
-/// colour×intensity tally ([`hue_tag`]).
+/// List the models that author M2 light blocks (`0x718960`): per point light (`type` 1) its bone,
+/// position, diffuse colour times intensity and attenuation, `OFF` when a static 0 visibility key
+/// keeps it dark (`0x71646d`); directional lights (`type` 0) feed ambient and are only counted.
+/// The summary totals them by content family and by colour.
 pub fn m2lightscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
 
-    // Rounded `(r, g, b) × 100` (int-keyed to stay orderable) — a cheap grouping key for the
-    // authored diffuse×intensity palette across point lights.
+    // Diffuse times intensity in hundredths, as integers so the key orders.
     type ColorKey = (i32, i32, i32);
 
     let (mut scanned, mut hits, mut total_point, mut total_dark) = (0u32, 0u32, 0u32, 0u32);
@@ -307,7 +280,6 @@ pub fn m2lightscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         let tag = hue_tag(r, g, b);
         println!("{count:>4}x  ({r:.2}, {g:.2}, {b:.2})  {tag:<5}  e.g. {example}");
     }
-    // Never let the top-20 read as "that's all of them".
     if let Some(rest) = ranked.len().checked_sub(TALLY_ROWS).filter(|n| *n > 0) {
         println!("      … and {rest} rarer colours (top {TALLY_ROWS} shown)");
     }
diff --git a/crates/benilla-formats/src/bin/benilla-extract/scan/material.rs b/crates/benilla-formats/src/bin/benilla-extract/scan/material.rs
index 9c95a570..af913e50 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/scan/material.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/scan/material.rs
@@ -1,30 +1,13 @@
-//! Corpus scans over **how a batch is textured and blended** — the material side of a model's
-//! render submeshes.
-//!
-//! Blend modes (`blendscan`), per-sequence batch visibility through the alpha combine
-//! (`alphascan`), sampler address modes and the UVs that need them (`uvwrapscan`, `texmodescan`),
-//! generated-texcoord environment stages (`envmapscan`), and the batches whose animated
-//! texture-transform / tint loop is not the same in every sequence slot, which the bake routes to
-//! a per-placement material (`uvslotscan`).
-//!
-//! `fxuvscan` is the intersection of the first two, asked of one corpus: the spell-effect models,
-//! whose animated texture transform decides — through their CLAMP-authored UVs — whether a
-//! consumer that runs none of it loses the batch's motion or its whole existence. It sized
-//! decision 2282, which built the consumer; it stays the way that question is asked at all — and
-//! `entityuvscan` is that same question asked of the unit / GameObject / held-item corpus, which
-//! sized decision 2295. Both lanes run their transform today; what the two scans are for is
-//! keeping "this lane needs no channel" a countable claim rather than an assumed one. They share
-//! their whole per-batch reader.
+//! Corpus scans over how a batch is textured and blended, and what the effect and entity corpora's
+//! animated texture transforms and tints render for a consumer that runs none of them.
 
 use std::collections::BTreeMap;
 
 use anyhow::{Context, Result};
 use benilla_formats::{Chain, KeyAnim, SeqLoops};
 
-/// Sweep every `.m2` (under `prefix`, if given) and list the models whose MATERIAL table authors
-/// blend mode 5 (Mod) / 6 (Mod2x) — the multiply-blend census (decision 0528). One line per
-/// matching model: its per-material `(flags, blend)` pairs and path. The raw header read (materials
-/// count/ofs at `0x84`, 4-byte `{u16 flags, u16 blend}` records) matches `benilla-m2`'s parse.
+/// List the models whose material table authors blend mode 5 (Mod) or 6 (Mod2x): materials at
+/// `0x84`/`0x88`, 4-byte `{u16 flags, u16 blend}` records.
 pub fn blendscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut hits) = (0u32, 0u32);
@@ -58,18 +41,8 @@ pub fn blendscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (under `prefix`, if given) and census the models whose batch visibility is
-/// **per sequence** — geometry the reference draws in one animation and skips in another, via the
-/// verified alpha combine (`A = colourAlpha × weight`, `A ≤ 0` culls; wow-re
-/// `m2-alpha-combine-cull.md`).
-///
-/// This is the population instrument for the class of bug where a client bakes the material tracks
-/// once and draws the result forever: every model listed here has at least one batch whose authored
-/// visibility CHANGES between sequences, so a single-sequence bake is guaranteed to be wrong for it
-/// in some animation. Per model it reports how many batches are **hidden in the model's first
-/// sequence** (what a doodad-shaped bake would show) versus hidden in *some* sequence, so the two
-/// failure directions — drawing geometry that should be hidden, and hiding geometry that should
-/// draw — are separated. `m2alpha` then explains one model in full.
+/// List the models whose batch visibility changes between sequences through the alpha combine
+/// (`A = colourAlpha × weight`, `A ≤ 0` culls; `0x707680`), which a single-sequence bake misses.
 pub fn alphascan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut hits) = (0u32, 0u32);
@@ -88,8 +61,7 @@ pub fn alphascan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         if seq_count < 2 {
             continue; // a one-sequence model can't disagree with itself
         }
-        // A batch is "hidden in slot s" when its combined factor is 0 across that whole band. The
-        // sampling grid is coarse on purpose — a batch that so much as flickers non-zero is drawn.
+        // Hidden in slot s: the combined factor is 0 at every sample; any flicker above 0 draws.
         let hidden_in = |sub: &benilla_formats::RenderSubmesh, slot: usize| -> bool {
             sub.alpha_anim.as_ref().is_some_and(|a| {
                 (0..=16u16).all(|k| a.sample(Some(slot), f32::from(k) * 0.25, 0.0) <= 0.0)
@@ -123,7 +95,6 @@ pub fn alphascan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         *by_dir.entry(top.to_ascii_lowercase()).or_default() += 1;
         rows.push((name, varies, first, any));
     }
-    // Loudest first: the models where the most geometry changes hands between sequences.
     rows.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(&b.0)));
     println!(
         "model                                                        varies  hid@seq0  hid@any"
@@ -142,19 +113,9 @@ pub fn alphascan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and list the batches whose texture is
-/// authored **CLAMP** (`M2Texture.flags` bit 0/1 clear) while the batch's own UVs run **outside
-/// `0..1`** — the exact population a repeat-sampling renderer draws wrong (decision 0763, B52/B96).
-///
-/// The margin outside `0..1` is deliberate authoring: clamped, it samples the texture's transparent
-/// border and the card fades out to nothing. Sampled with repeat it wraps into the opposite edge —
-/// on a cutout sheet, the opaque middle — so the margin draws as solid geometry with a hard seam
-/// where u or v crosses the wrap. That is why a snow-fir grows pale plates with a crease down each
-/// bough, and why the artefact never looked like an extra primitive: it is the *same* card,
-/// sampling the wrong texels.
-///
-/// `over` is how far past the edge the batch reaches, in UV units — the width of the wrongly-drawn
-/// margin as a fraction of the sheet.
+/// List the clamp-authored batches (`M2Texture.flags` bit 0 or 1 clear) whose UVs leave `0..1`:
+/// clamped, the margin samples the transparent border, where repeat draws the opposite edge with a
+/// seam. `over` is how far past the edge the batch reaches, in UV units.
 pub fn uvwrapscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut batches, mut hits, mut models) = (0u32, 0u32, 0u32, 0u32);
@@ -180,9 +141,7 @@ pub fn uvwrapscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 })
             };
             let (u, v) = (ext(0), ext(1));
-            // Only an axis authored CLAMP can be drawn wrong by repeat; a wrapping axis is meant
-            // to tile. A hair of float slop past the edge is not a margin — require 1/512 of a
-            // sheet, well under the thinnest authored border and well over rounding.
+            // Only a clamp axis draws wrong under repeat; under 1/512 of a sheet is float slop.
             const SLOP: f32 = 1.0 / 512.0;
             let bad_u = !s.wrap_x && (u.0 < -SLOP || u.1 > 1.0 + SLOP);
             let bad_v = !s.wrap_y && (v.0 < -SLOP || v.1 > 1.0 + SLOP);
@@ -235,13 +194,8 @@ pub fn uvwrapscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` and report, per texture path, which sampler ADDRESS MODES the corpus asks of
-/// it — and how many paths are asked for **more than one** (decision 0763).
-///
-/// The design question behind it: the address mode lives on the GPU sampler, which in our asset
-/// layer is a property of the loaded `Image`, which is keyed by path. If a `.blp` is only ever
-/// asked for one mode, path-keying stays correct and the mode can simply ride the load. Every path
-/// asked for two needs two uploads, or one of its users renders wrong.
+/// List the texture paths the corpus asks for in more than one address mode: the mode rides the
+/// loaded `Image`, keyed by path, so such a path needs one upload per mode.
 pub fn texmodescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     // texture path -> set of (wrap_x, wrap_y) asked for, as a 4-bit mask
@@ -286,36 +240,19 @@ pub fn texmodescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and census the batches whose texture
-/// coordinates are **GENERATED, not authored** — the sphere-map environment stages
-/// (`texture_unit_lookup[texCoordSet] > 2`, the reference's gate at `0x70b8bd`).
-///
-/// The population instrument for a silent class: such a batch carries no usable UVs *by design* —
-/// the artist collapses the whole mesh onto one point because the runtime is meant to supply the
-/// coordinates — so a renderer that reads the vertex UV draws the entire surface in **one texel**
-/// of a reflection sheet. Nothing about that failure is loud: no missing geometry, no error, just a
-/// flat wash of whatever colour happens to sit at that corner (`GnomeSubwayGlass.m2` → the Deeprun
-/// Tram tube's yellow, `AKGNOMEREFLECT.BLP` texel 0,0 = 225,221,142, doubled by its Mod2x blend).
-///
-/// **DEGENERATE** marks the batches where the authored UVs collapse to a single point — the ones
-/// that render as a flat colour field. The rest carry leftover UVs that merely go unused, so they
-/// misdraw as a static smear of the sheet instead: wrong, but not obviously so. Both are fixed by
-/// the same mechanism; the split says which reports a renderer's env support explains.
+/// List the batches whose texture coordinates are generated, not authored: the sphere-map
+/// environment stages (`texture_unit_lookup[texCoordSet] > 2`, gated at `0x70b8bd`). A
+/// `DEGENERATE` batch's authored UVs collapse to one point, so reading them draws one flat texel
+/// (`GnomeSubwayGlass.m2`: `AKGNOMEREFLECT.BLP` texel 0,0, doubled by Mod2x).
 pub fn envmapscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut batches, mut hits, mut models, mut degenerate) =
         (0u32, 0u32, 0u32, 0u32, 0u32);
-    // Which blend modes and which sheets the mechanism actually serves — a Mod2x env layer tints
-    // what is behind it (glass), an Add one lays a highlight over the surface (the metal sheen).
+    // The blend modes and sheets env stages use: Mod2x tints what is behind (glass), Add a sheen.
     let mut by_blend: BTreeMap<String, u32> = BTreeMap::new();
     let mut by_sheet: BTreeMap<String, u32> = BTreeMap::new();
-    // **The fallback census.** `stage_is_env_mapped` reads an OUT-OF-RANGE `texture_unit_lookup`
-    // index as env — the reference's own unguarded read, and the only safe direction. But that
-    // branch is the one way the gate can *invent* env-mapping on a model whose art never asked for
-    // it, so it is counted separately: a hit is trustworthy exactly when it came from a real
-    // `>= 3` entry. `empty_table` is the degenerate shape of the same thing (no table at all ⇒
-    // every batch falls through), broken out because it would tar a whole model rather than a
-    // stage.
+    // `stage_is_env_mapped` reads an out-of-range `texture_unit_lookup` index as env, as the
+    // reference's unguarded read does; those hits, and models with no table at all, count apart.
     let (mut from_oob, mut empty_table) = (0u32, 0u32);
     for name in names {
         let Ok(bytes) = chain.read_file(&name) else {
@@ -350,8 +287,6 @@ pub fn envmapscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             *by_blend.entry(format!("{:?}", s.blend)).or_default() += 1;
             let sheet = s.texture.as_deref().unwrap_or("NONE").to_string();
             *by_sheet.entry(sheet.clone()).or_default() += 1;
-            // Does the authored UV set collapse to a point? Then the vertex data cannot even
-            // approximate the sheet and the batch renders as one flat colour.
             let span = |axis: usize| {
                 s.uvs.iter().fold((f32::MAX, f32::MIN), |(lo, hi), t| {
                     (lo.min(t[axis]), hi.max(t[axis]))
@@ -408,15 +343,13 @@ pub fn envmapscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// The two per-batch channels the bake resolves **per file sequence slot** — the pair
-/// `models::m2_batches` hands the runtime as `uv_seq` / `rgb_seq`. Both are `C3Vector` tracks, so
-/// one classifier serves both; only how many components survive the bake differs.
+/// The two per-batch channels the bake resolves per file sequence slot (`uv_seq`, `rgb_seq`),
+/// both `C3Vector` tracks, so one classifier serves both.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Channel {
-    /// The texture transform's **translation** track (`tex_anim::bake_uv_seqs`), read off
-    /// `RenderSubmesh::uv_seq` and its shared-lane twin `uv_anim`.
+    /// The texture transform's translation (`tex_anim::bake_uv_seqs`): `uv_seq`, or `uv_anim`.
     Uv,
-    /// The M2Color **RGB** tint track (`mat_anim::bake_rgb_seqs`), read off `rgb_seq` / `rgb_anim`.
+    /// The M2Color RGB tint (`mat_anim::bake_rgb_seqs`): `rgb_seq`, or `rgb_anim`.
     Rgb,
 }
 
@@ -435,7 +368,6 @@ impl Channel {
         }
     }
 
-    /// The field name the report quotes, so a reader can grep the struct the numbers came from.
     fn field(self) -> &'static str {
         match self {
             Self::Uv => "uv_seq",
@@ -443,9 +375,6 @@ impl Channel {
         }
     }
 
-    /// Axis names for the value-range cells — one per component the bake keeps. The UV pair stays
-    /// `x`/`y`: the bake carries the track's raw components and how the reference maps them onto
-    /// U/V is still under RE (`tex_anim`'s module doc).
     fn axes(self) -> &'static [&'static str] {
         match self {
             Self::Uv => &["x", "y"],
@@ -454,36 +383,22 @@ impl Channel {
     }
 }
 
-/// How far apart two baked loops may be and still be the **same authored function**. Tight on
-/// purpose: this is the noise floor of a `u32` millisecond key rebased through an `f32` divide, not
-/// an authoring tolerance — a disagreement anyone could see is orders of magnitude larger.
+/// How far apart two baked loops may be and still be one authored loop: the noise of a `u32` ms
+/// key rebased through an `f32` divide.
 const KEY_EPS: f32 = 1e-4;
 
-/// Why one batch's slots disagree — the sub-classification of every batch the bake routed to the
-/// per-placement lane, i.e. of every set whose [`SeqLoops::uniform`] came back `None`.
-///
-/// The question these four answer is whether that verdict is **earned**. `uniform()` compares
-/// `KeyAnim` by `PartialEq` — exact float equality on the clock flags, the period and every key —
-/// so two slots holding the same authored loop can still be split by a single flag or by
-/// sub-epsilon noise in a rebased timestamp. `Dead0` and `RealDiffers` are real divergence, where
-/// one material per placement is the only right answer; `WrapOnly` and `KeysEpsilon` are batches a
-/// coarser comparison would have left on the shared lane, and their count IS the over-application.
+/// Why a batch's slots disagree, for every set [`SeqLoops::uniform`] refused. `uniform()` is exact
+/// float equality, so `WrapOnly` and `KeysEpsilon` are sets a coarser test would share; `Dead0`
+/// and `RealDiffers` need a material per placement.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Why {
-    /// Slot 0 bakes nothing while a later slot bakes a loop — the B98 shape, the founding case, and
-    /// the only class a slot-0-pinned bake could not render at all.
+    /// Slot 0 bakes nothing while a later slot bakes a loop.
     Dead0,
-    /// Every slot bakes the same loop except [`KeyAnim::wrap`]: the sequences carrying it disagree
-    /// on their own loop flag, so one band clamps at its tail where another wraps. Visible only at
-    /// the very end of a one-shot band — and never at all on a placed doodad, which loops.
+    /// The slots differ only in [`KeyAnim::wrap`]: one band clamps at its tail where another wraps.
     WrapOnly,
-    /// Every slot agrees to within [`KEY_EPS`] on every number and on every flag — the slots differ
-    /// only by float noise in the rebased key times, and exact `PartialEq` is the whole reason they
-    /// are here.
+    /// The slots agree within [`KEY_EPS`] on every number and flag: float noise only.
     KeysEpsilon,
-    /// Genuinely different loops: a different key count, a different interpolation or clock law,
-    /// numbers apart by more than noise — or slot 0 alive against a later slot that holds still,
-    /// DEAD-0's mirror.
+    /// Different loops (key count, clock law or values), or slot 0 alive beside a dead later slot.
     RealDiffers,
 }
 
@@ -504,7 +419,6 @@ impl Why {
         }
     }
 
-    /// The one-line reading of the bucket, printed beside its counts.
     fn blurb(self) -> &'static str {
         match self {
             Self::Dead0 => {
@@ -530,16 +444,13 @@ impl Why {
 /// One batch-channel's read of the bake.
 struct Verdict {
     why: Why,
-    /// The largest numeric disagreement between slot 0 and any other slot. `0.0` means the slots
-    /// are bit-identical — which, for a set the bake kept, means only a *flag* differs.
+    /// The largest disagreement between slot 0 and another slot; 0 means only a flag differs.
     delta: f32,
-    /// The report line's detail cell.
     detail: String,
 }
 
-/// The largest absolute disagreement between two baked loops over everything a consumer reads: the
-/// period, and every key's time and value. `None` when they are not the same **shape** at all — a
-/// different key count or a different interpolation/clock law is a different function, not noise.
+/// The largest difference between two baked loops in period, key times and values; `None` when
+/// their key count or clock law differs.
 fn loop_delta<V: AsRef<[f32]>>(a: &KeyAnim<V>, b: &KeyAnim<V>) -> Option<f32> {
     if a.step != b.step || a.gseq != b.gseq || a.keys.len() != b.keys.len() {
         return None;
@@ -554,9 +465,7 @@ fn loop_delta<V: AsRef<[f32]>>(a: &KeyAnim<V>, b: &KeyAnim<V>) -> Option<f32> {
     Some(d)
 }
 
-/// `[.L]` — one character per **file** sequence slot: `L` where the slot bakes a loop, `.` where
-/// its key window moves nothing. Slot 0 is leftmost, so a leading `.` reads as the B98 shape at a
-/// glance. Long tables (a creature's fifty-odd sequences) are truncated to a readable head.
+/// `[.L]`, one character per file sequence slot from slot 0: `L` bakes a loop, `.` moves nothing.
 fn slot_cell<V>(slots: &[Option<KeyAnim<V>>]) -> String {
     const HEAD: usize = 28;
     let bits: String = slots
@@ -571,8 +480,7 @@ fn slot_cell<V>(slots: &[Option<KeyAnim<V>>]) -> String {
     }
 }
 
-/// `[Wc.]` — the per-slot clock law, the other half of what `PartialEq` compares: `W` wrap, `c`
-/// clamp, `.` dead. The whole content of a WRAP-ONLY row.
+/// `[Wc.]`, each slot's clock law: `W` wrap, `c` clamp, `.` dead.
 fn wrap_cell<V>(slots: &[Option<KeyAnim<V>>]) -> String {
     slots
         .iter()
@@ -584,8 +492,7 @@ fn wrap_cell<V>(slots: &[Option<KeyAnim<V>>]) -> String {
         .collect::<String>()
 }
 
-/// `1.500s wrap 28k x[+0.000..+0.938] y[…]` — one baked loop as its consumer sees it: the clock,
-/// the size, and the range it sweeps on every component the bake keeps.
+/// One baked loop as `1.500s wrap 28k x[+0.000..+0.938] y[…]`: period, clock, keys, ranges.
 fn loop_cell<V: AsRef<[f32]>>(l: &KeyAnim<V>, ch: Channel) -> String {
     let range = ch
         .axes()
@@ -611,13 +518,11 @@ fn loop_cell<V: AsRef<[f32]>>(l: &KeyAnim<V>, ch: Channel) -> String {
     )
 }
 
-/// Read one batch-channel's per-slot set exactly as the runtime does — [`SeqLoops::slots`], the
-/// same values [`SeqLoops::uniform`] compared — and say why they disagree.
+/// Why one batch-channel's slots disagree, read through [`SeqLoops::slots`] as the runtime does.
 fn classify<V: AsRef<[f32]> + PartialEq>(set: &SeqLoops<V>, ch: Channel) -> Verdict {
     let slots = set.slots();
     let cell = slot_cell(slots);
-    // A set exists only when SOME slot bakes, so a dead slot 0 is by construction a dead slot 0
-    // beside a live later one — no second test needed.
+    // A set exists only when some slot bakes, so a dead slot 0 has a live later one.
     let Some(base) = slots.first().and_then(Option::as_ref) else {
         let (s, live) = slots
             .iter()
@@ -639,9 +544,7 @@ fn classify<V: AsRef<[f32]> + PartialEq>(set: &SeqLoops<V>, ch: Channel) -> Verd
                 detail: format!("{cell} slot 0 {} vs slot {s} dead", loop_cell(base, ch),),
             };
         };
-        // Name WHAT diverges, not merely that something did: a value-range cell hides a timing
-        // difference (same extremes, different key times) behind identical-looking brackets, and
-        // that is exactly the ambiguity this scan exists to remove.
+        // Name what diverges: a value range hides a timing difference behind identical brackets.
         let reason = match loop_delta(base, l) {
             Some(d) if d <= KEY_EPS => {
                 delta = delta.max(d);
@@ -677,50 +580,36 @@ fn classify<V: AsRef<[f32]> + PartialEq>(set: &SeqLoops<V>, ch: Channel) -> Verd
     }
 }
 
-/// Per-channel corpus counters. Model counts are per bucket and count a model once if **any** of
-/// its batches lands there, so they overlap rather than partition.
+/// Per-channel corpus counters; a model counts once in each bucket any of its batches lands in.
 #[derive(Default)]
 struct Tally {
-    /// The set is `None`: every slot bakes the same loop, so the batch keeps the shared lane.
+    /// Batches whose slots all bake the same loop, which keep the shared lane.
     shared_b: u32,
-    /// …and of those, the ones that actually animate there (`uv_anim`/`rgb_anim` with `period > 0`).
+    /// Of those, the ones that animate there (`period > 0`).
     shared_live_b: u32,
     shared_live_m: u32,
-    /// The set is `Some` — batches and models routed to the per-placement lane, by [`Why`].
+    /// Batches and models on the per-placement lane, by [`Why`].
     per_b: [u32; 4],
     per_m: [u32; 4],
-    /// Models with at least one per-placement batch on this channel, whatever the reason.
     per_m_any: u32,
-    /// WRAP-ONLY batches whose slots are **bit-identical** apart from the flag; the rest carry
-    /// sub-epsilon key noise on top of it.
+    /// WRAP-ONLY batches bit-identical apart from the flag.
     wrap_exact: u32,
 }
 
-/// One model's per-placement batches in one (channel, bucket) — the row the family census and the
-/// worst-hit tail are both built from.
+/// One model's per-placement batches in one (channel, bucket).
 struct Hit {
     name: String,
     ch: Channel,
     why: Why,
     batches: u32,
-    /// The model's **file** sequence slot count, straight off the set the bake built.
     slots: usize,
 }
 
-/// How many rows of the worst-hit tail print (the rest are counted, never silently dropped).
 const TAIL_ROWS: usize = 25;
 
-/// Sweep every `.m2` (optionally under a path prefix) and census the batches the bake routes to a
-/// **per-placement material** because their UV / tint loop is not the same in every file sequence
-/// slot — see the `Uvslotscan` command doc for the why.
-///
-/// It reads the bake's own verdict (`RenderSubmesh::uv_seq` / `rgb_seq`, `Some` exactly when
-/// [`SeqLoops::uniform`] refused the shared lane) rather than re-deriving it: this scan used to
-/// carry a transcribed sampler because the fix it was sizing did not exist yet, and once it did the
-/// twin drifted from it — the very failure `idleslotscan`'s rule names ("beside the parse, so the
-/// census asks the renderer's own question instead of a hand-copied twin that can drift from it").
-/// Every number below is therefore what the runtime sees, and the four PER-PLACEMENT buckets say
-/// how much of it `uniform()`'s exact float equality is *earning*.
+/// Census the batches the bake gives a per-placement material because their UV or tint loop
+/// differs between file sequence slots, read off the bake's own verdict (`uv_seq`/`rgb_seq`,
+/// `Some` when [`SeqLoops::uniform`] refused the shared lane), with the `Why` of each.
 pub fn uvslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut batches) = (0u32, 0u64);
@@ -738,9 +627,7 @@ pub fn uvslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         scanned += 1;
         batches += subs.len() as u64;
         let mut lines: Vec<String> = Vec::new();
-        // This model's own contribution, folded into the corpus tally once per channel below:
-        // (shared, shared-and-live) batch counts, per-bucket batch counts, and the file sequence
-        // slot count — which only a batch carrying a set can report, because the set IS the table.
+        // This model's counts per channel: (shared, shared and live), per bucket, its slot count.
         let mut shared = [(0u32, 0u32); 2];
         let mut per = [[0u32; 4]; 2];
         let mut slots = [0usize; 2];
@@ -856,9 +743,6 @@ pub fn uvslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 t.wrap_exact
             );
         }
-        // Where each bucket's population LIVES, and which models carry most of it. `World\` is a
-        // placed doodad or WMO prop — the only lane the per-placement material reaches — so a
-        // bucket that is mostly `Creature\`/`Spells\` costs nothing today whatever it says.
         for w in Why::ALL {
             let rows: Vec<&Hit> = hits
                 .iter()
@@ -895,50 +779,31 @@ pub fn uvslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
 }
 
 // ---------------------------------------------------------------------------
-// fxuvscan — what the SPELL-EFFECT corpus's animated texture transforms render
-// for a consumer that runs none of them.
-//
-// Everything down to `uv_batch` is shared with `entityuvscan` below, which asks
-// the identical question of the corpus 2282's fix did NOT reach. The sheet
-// decode, the two frozen states, the per-axis texel reasoning and the five
-// classes live here once on purpose: two sweeps that classified the same batch
-// by two slightly different rules would be worse than one sweep.
+// fxuvscan, and the per-batch reader down to `uv_batch` that `entityuvscan` shares
 // ---------------------------------------------------------------------------
 
-/// How many spells print per INVISIBLE model before the rest are counted.
 const FX_SPELL_ROWS: usize = 12;
 
-/// How many unreadable model paths print before the rest are counted.
 const FX_UNREAD_ROWS: usize = 20;
 
-/// How many time samples the animated sweep takes across each slot's loop — enough to bound a
-/// scroll that only crosses the sheet for part of its period (the reported box is the union, so
-/// it only ever over-states what the animation reaches, never under-states it).
+/// Time samples per slot's loop in the animated sweep; the reported box is their union.
 const FX_ANIM_SAMPLES: usize = 64;
 
-/// One texture's mip-0 channels, as the visibility question needs them.
-///
-/// Alpha decides it for the modes that read alpha — `Blend`/`AlphaTest`, and M2 mode 4 `Add`
-/// (`SRC_ALPHA/ONE`), which is most of the effect corpus. An `Opaque` batch paints whatever it
-/// covers and a `Mod`/`Mod2x` batch's equation reads no alpha at all (decision 0528), so neither
-/// is called from the sheet. The one mode that needs [`Self::rgb`] is **3, `NoAlphaAdd`**
-/// (`ONE/ONE`): it adds the texel's colour with the alpha channel untouched, so an alpha-0 border
-/// with non-zero RGB still puts light on the screen. `BloodSpurtSmall01`'s border column is
-/// exactly that shape — alpha 0, RGB up to 107 — so the distinction is not hypothetical.
+/// One texture's mip-0 alpha, plus [`Self::rgb`] for blend 3 `NoAlphaAdd` (`ONE/ONE`), which adds
+/// colour whatever the alpha (`BloodSpurtSmall01`'s border: alpha 0, RGB up to 107); `Opaque`,
+/// `Mod` and `Mod2x` batches are not judged from the sheet.
 struct Sheet {
     w: u32,
     h: u32,
     /// Row-major, one byte per texel.
     alpha: Vec<u8>,
-    /// Row-major `max(r, g, b)` — what an `ONE/ONE` add would put on the screen.
+    /// Row-major `max(r, g, b)`.
     rgb: Vec<u8>,
 }
 
 impl Sheet {
-    /// The inclusive texel index ranges one axis's UV span `[lo, hi]` reaches under the batch's own
-    /// address mode — clamped to the edge texel (`wrap == false`, the border-sampling case this
-    /// whole scan turns on) or folded back into `0..1`. A wrapping span of a full sheet or more
-    /// reaches every texel.
+    /// The inclusive texel ranges a UV span `[lo, hi]` reaches: clamped to the edge texel, or
+    /// folded into `0..1` when `wrap`.
     fn axis(lo: f32, hi: f32, n: u32, wrap: bool) -> Vec<(u32, u32)> {
         let last = n.saturating_sub(1);
         let texel = |t: f32| ((t * n as f32) as i64).clamp(0, i64::from(last)) as u32;
@@ -957,13 +822,8 @@ impl Sheet {
         }
     }
 
-    /// The most this sheet can PAINT anywhere in the UV box `u × v` — the greatest alpha, or, when
-    /// `with_rgb` (a batch that may be `NoAlphaAdd`), the greater of alpha and `max(r, g, b)`.
-    /// `0` exactly when every texel the box reaches contributes nothing.
-    ///
-    /// The box is the batch's UV **bounding box**, which is a superset of the texels its triangles
-    /// actually cover, so a `0` here is conservative in the one direction that matters: it cannot
-    /// call a batch invisible that in fact paints.
+    /// The most the sheet paints in the UV box `u × v`: its greatest alpha, and with `with_rgb`
+    /// its greatest `max(r, g, b)`. The box bounds the triangles, so a 0 is never a false one.
     fn paint(
         &self,
         u: (f32, f32),
@@ -994,8 +854,8 @@ impl Sheet {
     }
 }
 
-/// Decode one texture's mip-0 alpha channel, memoised by lowercased path. `None` for a path the
-/// chain has no BLP for, or one that will not decode — reported as `UNKNOWN`, never a silent pass.
+/// One texture's [`Sheet`], memoised by lowercased path; `None`, reported `UNKNOWN`, if it will
+/// not load.
 fn fx_sheet<'a>(
     cache: &'a mut BTreeMap<String, Option<Sheet>>,
     chain: &mut Chain,
@@ -1021,8 +881,7 @@ fn fx_sheet<'a>(
         .as_ref()
 }
 
-/// One effect model's place in the spell-visual chain: the `SpellVisualEffectName` rows that name
-/// it, and every spell that reaches it with the lifecycle stages it arrives through.
+/// An effect model's `SpellVisualEffectName` rows and the spells that reach it, by stage.
 #[derive(Default)]
 struct FxReach {
     /// The table's own spelling of the path (`.mdx`), for display.
@@ -1032,9 +891,8 @@ struct FxReach {
     spells: BTreeMap<u32, (String, std::collections::BTreeSet<&'static str>)>,
 }
 
-/// Fold one `SpellVisualEffectName` id's model into the corpus, and — when `spell` is given — note
-/// that that spell reaches it through that lifecycle stage. An id with no row or an empty path
-/// (the table's absent-model convention) folds to nothing, which is the client's own no-op.
+/// Fold one `SpellVisualEffectName` id's model into the corpus, noting `spell`'s stage when given;
+/// an id with no row or path adds nothing.
 fn fx_record(
     out: &mut BTreeMap<String, FxReach>,
     visuals: &benilla_formats::SpellVisualCatalog,
@@ -1044,11 +902,8 @@ fn fx_record(
     let Some(path) = visuals.effect_path(effect) else {
         return;
     };
-    // One shipped row spells its path with a LEADING separator
-    // (`\\spells\\HellFire_FirePuff_Caster_Base.mdx`, `SpellVisualEffectName` 1180). The chain has
-    // the model under the same name without it, so the key drops leading separators while the
-    // DISPLAY path keeps the table's own spelling — the quirk stays visible instead of being
-    // silently smoothed away.
+    // `SpellVisualEffectName` 1180 spells its path with a leading separator; the chain holds it
+    // without one, so the key drops it and the display path keeps it.
     let e = out
         .entry(crate::model_key(path.trim_start_matches(['\\', '/'])))
         .or_default();
@@ -1065,15 +920,9 @@ fn fx_record(
     }
 }
 
-/// Every model the spell-visual chain can reach, keyed by [`crate::model_key`] — walked from the
-/// **tables**, not from the spells, so a kit no shipped spell names is still swept (it is still
-/// content the lane can be asked to play); the spell join is the second pass over the same map.
-///
-/// The reachable set is every kit's ten effect slots (`VisualKit::effects` — the nine bone-attach
-/// slots plus the world/state plant), every `SpellVisual` row's missile model (field 7) and its
-/// dest-anchored model (field 12, the DynamicObject's own `.mdx`). The stage labels are the five
-/// lifecycle kit columns plus `missile` and `area`, the latter covering both dest-anchored columns
-/// (field 12's model and field 13's area kit) — one lane, one name.
+/// Every model the spell-visual tables reach, keyed by [`crate::model_key`], then joined to the
+/// spells: every kit's ten effect slots, and each `SpellVisual` row's missile model (field 7) and
+/// dest-anchored model (field 12). Stage `area` covers field 12 and the area kit (field 13).
 fn fx_corpus(
     visuals: &benilla_formats::SpellVisualCatalog,
     spells: &benilla_formats::SpellCatalog,
@@ -1126,24 +975,18 @@ fn fx_corpus(
     out
 }
 
-/// What a consumer that runs NO texture-transform animation renders for one batch whose transform
-/// the bake DID key.
+/// What a consumer that runs no texture-transform animation renders for a keyed batch.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 enum FxClass {
-    /// The transform moves, and frozen the batch samples no painted texel while the animation does:
-    /// the batch renders **nothing at all**. The `SwipeCaster` class.
+    /// Frozen, the batch samples no painted texel while the animation does: it draws nothing.
     Invisible,
-    /// The transform moves, and the batch paints nothing at any point of the loop — so the missing
-    /// UV animation is not what is wrong with it. Flagged, never counted as INVISIBLE.
+    /// It paints nothing at any point of the loop, so the frozen transform is not its fault.
     Never,
-    /// The transform moves and the batch draws — statically, where the scroll is the motion.
+    /// It draws, but statically.
     Frozen,
-    /// The transform is keyed but never moves within its band: a constant NON-identity offset the
-    /// bake carries as a `period == 0` hold. A lane that seeds no offset draws the batch at the
-    /// identity instead — a static mis-registration, not a missing scroll.
+    /// A constant non-identity offset (`period == 0`), which a lane seeding none draws misplaced.
     Held,
-    /// No call from the sheet: a `Mod`/`Mod2x` batch (its blend equation reads no alpha) or a
-    /// texture the chain will not hand over. Flagged.
+    /// No call from the sheet: a `Mod`/`Mod2x` batch, or a texture that will not load.
     Unknown,
 }
 
@@ -1188,9 +1031,8 @@ impl FxClass {
     }
 }
 
-/// The batch's texture-transform state at `(slot, t)` — the triple [`benilla_formats::uv_transform`]
-/// composes, read the way the one lane that RUNS it reads it (`ui_models::UvPart::write_rows`): the
-/// per-slot set when the bake built one, else the single shared loop.
+/// The texture-transform triple [`benilla_formats::uv_transform`] composes at `(slot, t)`: the
+/// per-slot set when the bake built one, else the shared loop.
 fn fx_state(
     sub: &benilla_formats::RenderSubmesh,
     slot: usize,
@@ -1214,8 +1056,7 @@ fn fx_state(
     (trans, rot, scale)
 }
 
-/// How many file sequence slots this batch's transform was baked across (1 when only the shared
-/// single-slot loop exists), and the longest loop period in slot `slot`.
+/// How many file sequence slots the batch's transform was baked across, at least 1.
 fn fx_slots(sub: &benilla_formats::RenderSubmesh) -> usize {
     let n = |v: Option<usize>| v.unwrap_or(0);
     n(sub.uv_seq.as_ref().map(|s| s.slots().len()))
@@ -1224,8 +1065,7 @@ fn fx_slots(sub: &benilla_formats::RenderSubmesh) -> usize {
         .max(1)
 }
 
-/// The longest period any of the batch's three transform channels loops on in slot `slot`;
-/// `0.0` when every one of them is a constant hold there.
+/// The longest transform period in slot `slot`; 0 when every channel holds.
 fn fx_period(sub: &benilla_formats::RenderSubmesh, slot: usize) -> f32 {
     let t = match (&sub.uv_seq, &sub.uv_anim) {
         (Some(s), _) => s.seq(Some(slot)).map_or(0.0, |l| l.period),
@@ -1245,8 +1085,7 @@ fn fx_period(sub: &benilla_formats::RenderSubmesh, slot: usize) -> f32 {
     t.max(r).max(s)
 }
 
-/// The batch's UV bounding box carried through [`benilla_formats::uv_transform`] — all four
-/// corners, so a rotation or scale is bounded rather than assumed away.
+/// The UV bounding box through [`benilla_formats::uv_transform`], all four corners.
 fn fx_box(
     u: (f32, f32),
     v: (f32, f32),
@@ -1265,9 +1104,7 @@ fn fx_box(
     out
 }
 
-/// Does this batch's texture transform animate? The UI lane's own test, verbatim: any of the three
-/// channels baked to something ([`benilla_formats::RenderSubmesh::uv_anim`] and the three
-/// per-sequence sets). Shared, so the two sweeps cannot drift into asking it differently.
+/// Whether the batch's texture transform is keyed: the shared loop or any per-sequence set.
 fn uv_keyed(sub: &benilla_formats::RenderSubmesh) -> bool {
     sub.uv_anim.is_some()
         || sub.uv_seq.is_some()
@@ -1275,14 +1112,8 @@ fn uv_keyed(sub: &benilla_formats::RenderSubmesh) -> bool {
         || sub.uv_scale_seq.is_some()
 }
 
-/// Does this model author M2 blend mode **3** (`NoAlphaAdd`, `ONE/ONE`) anywhere?
-///
-/// The bake folds modes 3 and 4 into one `Blend` + `additive` pair, and no `RenderSubmesh` carries
-/// the source material back (the billboard split means batches are not even 1:1 with skin batches),
-/// so the question is asked of the model's MATERIAL TABLE — the same raw read `blendscan` does
-/// (count/ofs at `0x84`, 4-byte `{u16 flags, u16 blend}`). A model with no mode-3 material has
-/// alpha-gated additives and the alpha test is exact; one that has any gets the stricter
-/// alpha-or-RGB test on its additive batches, which can only make INVISIBLE harder to claim.
+/// Whether the material table (read as `blendscan` does) authors blend 3 `NoAlphaAdd`: the bake
+/// folds modes 3 and 4 into `additive`, so such a model's additive batches are judged on RGB too.
 fn authors_no_alpha_add(bytes: &[u8]) -> bool {
     let at = |o: usize| -> Option<u32> {
         Some(u32::from_le_bytes(bytes.get(o..o + 4)?.try_into().ok()?))
@@ -1298,27 +1129,20 @@ fn authors_no_alpha_add(bytes: &[u8]) -> bool {
     }
 }
 
-/// One animating batch's whole texture-transform read — the per-batch body [`fxuvscan`] and
-/// [`entityuvscan`] share, so the two sweeps cannot answer the same question differently.
-///
-/// The caller supplies the sheet path because the two corpora do not resolve it the same way: an
-/// effect model's batch names its own `.blp`, while a CREATURE batch's `Monster1/2/3` slot is blank
-/// in the M2 and filled per display from `CreatureDisplayInfo.textureVariation` — so the same batch
-/// has as many sheets as the model has skins, and the visibility question has to be asked of each.
+/// One keyed batch's texture-transform read, shared by [`fxuvscan`] and [`entityuvscan`]. The
+/// caller supplies the sheet: a creature batch's `Monster1/2/3` slot is filled per display from
+/// `CreatureDisplayInfo`, so it has one sheet per skin.
 struct UvBatch {
-    /// The verdict under the seed a `play_uv = false` lane renders at (the identity).
+    /// The verdict at the identity, the offset a material built with `play_uv = false` seeds.
     class: FxClass,
-    /// The verdict under the track's first key — what the same batch becomes on a lane that hands
-    /// `model_material` the loop but never ticks it.
+    /// The verdict at the first key, where a lane that seeds the loop and never ticks it sits.
     key_class: FxClass,
-    /// `uv_anim.sample(0.0)` — the translation seed, `[0, 0]` when the shared loop is absent.
+    /// `uv_anim.sample(0.0)`, `[0, 0]` without a shared loop.
     seed: [f32; 2],
-    /// The report block, in print order.
     lines: Vec<String>,
 }
 
-/// Read one batch's texture transform — see [`UvBatch`]. The caller has already established that
-/// the transform is keyed ([`uv_keyed`]) and that the batch has UVs to transform.
+/// Read one batch's texture transform; the caller has checked [`uv_keyed`] and that it has UVs.
 fn uv_batch(
     sheets: &mut BTreeMap<String, Option<Sheet>>,
     chain: &mut Chain,
@@ -1336,27 +1160,15 @@ fn uv_batch(
     let slots = fx_slots(sub);
     let moves = (0..slots).any(|s| fx_period(sub, s) > 0.0);
 
-    // THE TWO FROZEN STATES, because our codebase has two seeding conventions and they
-    // are not the same picture:
-    //
-    // - **identity** — the offset an effect part actually renders at. Its material is
-    //   built by `model_render::batch::Materials::entity_variants`, whose `play_uv` is
-    //   `false`, so `model_material` is handed no loop and seeds `sun_scale.zw = (0, 0)`:
-    //   the batch draws its AUTHORED UVs, untransformed. This is the primary verdict.
-    // - **first key** — `uv_anim.sample(0.0)`, what the same builder seeds when a lane
-    //   DOES hand it the loop (the doodad and off-world lanes). Reported beside it,
-    //   because a fix that wires the loop in without ticking it lands the batch here.
-    //
-    // Rotation and scale are at the identity in both: the translation seed is the only
-    // transform channel a shared material carries at all (the affine pair is the UI
-    // lane's per-pane table row, decision 2019).
+    // Two frozen states: the identity, which a material built with `play_uv = false` seeds
+    // (`sun_scale.zw = (0, 0)`, the authored UVs), and the first key, which `model_material`
+    // seeds when handed the loop. Rotation and scale stay at the identity in both: a shared
+    // material carries only the translation seed.
     let seed = sub.uv_anim.as_ref().map_or([0.0, 0.0], |a| a.sample(0.0));
     let (fu, fv) = fx_box(au, av, [0.0, 0.0], [0.0, 0.0, 0.0, 1.0], [1.0, 1.0]);
     let (ku, kv) = fx_box(au, av, seed, [0.0, 0.0, 0.0, 1.0], [1.0, 1.0]);
 
-    // ANIMATED REACH. The union over every slot and a uniform sweep of its loop — an
-    // over-approximation by construction, so "nothing painted here either" is a claim the
-    // geometry cannot contradict.
+    // The animated reach: the union over every slot's sampled loop, an over-approximation.
     let mut ru = (f32::MAX, f32::MIN);
     let mut rv = (f32::MAX, f32::MIN);
     for slot in 0..slots {
@@ -1386,7 +1198,6 @@ fn uv_batch(
         ),
         None => (0, 0, 0, "—".to_string()),
     };
-    // One rule, run twice — once per frozen state, so the two verdicts cannot drift apart.
     let verdict = |painted: u8| {
         if !moves {
             FxClass::Held
@@ -1414,11 +1225,8 @@ fn uv_batch(
             n(sub.uv_scale_seq.is_some(), "S"),
         )
     };
-    // The per-axis reasoning, read off the TEXELS rather than off the span: a CLAMP axis
-    // whose frozen span runs past an edge samples that edge's texel for every bit of it
-    // past the edge, so a span like `[+0.951..+1.950]` over a 16-texel sheet is not
-    // "mostly outside" — it is column 15, alone, for its whole length. That collapse is the
-    // whole mechanism, so the line names it.
+    // Per axis, in texels: a clamp span past an edge samples the edge texel, so `[+0.951..+1.950]`
+    // over 16 texels is column 15 alone.
     let axis = |wrap: bool, a: (f32, f32), f: (f32, f32), n: u32| {
         let (texels, verdict) = match n {
             0 => ("—".to_string(), "no sheet"),
@@ -1504,21 +1312,18 @@ fn uv_batch(
     }
 }
 
-/// One classified batch — the row the class listings and the spell join are both built from.
 struct FxHit {
-    /// The corpus key (lowercased `.m2`), so the reach map joins straight onto it.
+    /// The corpus key (lowercased `.m2`) the reach map joins on.
     key: String,
     batch: usize,
-    /// The verdict under the seed the effect lane actually renders at (the identity).
+    /// The verdict at the identity seed.
     class: FxClass,
-    /// The verdict under the track's first key — what the same batch becomes on a lane that hands
-    /// `model_material` the loop but never ticks it.
+    /// The verdict at the first-key seed.
     key_class: FxClass,
 }
 
-/// Sweep every model the SPELL-VISUAL CHAIN can reach and census the batches whose **texture
-/// transform animates** — then classify each by what a consumer that runs none of it renders. See
-/// the `Fxuvscan` command doc for the why.
+/// Classify every keyed texture-transform batch the spell-visual chain reaches by what a consumer
+/// that runs none of it renders.
 pub fn fxuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let visuals = benilla_formats::load_spell_visual_catalog(chain)?;
     let spells = benilla_formats::load_spell_catalog(chain)?;
@@ -1531,14 +1336,9 @@ pub fn fxuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let mut per_class: BTreeMap<FxClass, u32> = BTreeMap::new();
     let mut per_key_class: BTreeMap<FxClass, u32> = BTreeMap::new();
     let mut hits: Vec<FxHit> = Vec::new();
-    // Every model the chain names that the archives do not carry, or will not parse — listed,
-    // never a silent hole in the sweep.
     let mut unread: Vec<String> = Vec::new();
-    // How many batches the two frozen states disagree about (see the classification below): the
-    // number that says whether "what does a no-UV-animation consumer render" has one answer here
-    // or two.
     let mut seed_disagrees = 0u32;
-    // Of the batches that DO draw frozen, how many draw at UVs the loop never opens at.
+    // Batches that draw frozen at UVs the loop never opens at.
     let mut misregistered = 0u32;
 
     for (key, reach) in &corpus {
@@ -1578,8 +1378,6 @@ pub fn fxuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             if read.class != read.key_class {
                 seed_disagrees += 1;
             }
-            // A batch that draws today but at a picture the loop never opens at: the identity is
-            // not the seed, so what is on screen is neither the animation nor its first frame.
             if read.class == FxClass::Frozen && (read.seed[0] != 0.0 || read.seed[1] != 0.0) {
                 misregistered += 1;
             }
@@ -1648,9 +1446,8 @@ pub fn fxuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     );
     if !unread.is_empty() {
         println!();
-        // Every one of these on the shipped 1.12 chain is a DEAD TABLE ROW, not a hole in the
-        // sweep: `SpellVisualEffectName` still carries the Warcraft-III-era `Particles\*.mdl`
-        // names the 1.12 archives never shipped. The extension split says so at a glance.
+        // On 1.12 each is a dead `SpellVisualEffectName` row, mostly `Particles\*.mdl` names the
+        // archives never shipped.
         let mdl = unread
             .iter()
             .filter(|u| u.to_ascii_lowercase().contains(".mdl "))
@@ -1721,9 +1518,7 @@ pub fn fxuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             c,
         );
     }
-    // The batches the first-key seed alone condemns: they draw today, and would stop drawing on a
-    // lane that seeds the loop's opening value without running it. Named, because that is exactly
-    // the shape of a half-finished fix.
+    // Batches invisible only at the first-key seed, where a lane that never ticks the loop sits.
     let key_only: Vec<&FxHit> = hits
         .iter()
         .filter(|h| h.key_class == FxClass::Invisible && h.class != FxClass::Invisible)
@@ -1751,9 +1546,7 @@ pub fn fxuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         }
     }
 
-    // The deliverable: the distinct spells that reach an INVISIBLE batch at all, named in full —
-    // the set a player can cast and see nothing for. `+` marks a spell that is only reached under
-    // the first-key seed, never under the one the lane renders at today.
+    // The spells that reach an invisible batch; `+` marks one reached only at the first-key seed.
     let mut reached: BTreeMap<u32, (String, std::collections::BTreeSet<&'static str>, bool)> =
         BTreeMap::new();
     for h in hits
@@ -1790,59 +1583,46 @@ pub fn fxuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
 }
 
 // ---------------------------------------------------------------------------
-// entityuvscan — what the UNIT / GAMEOBJECT / HELD-ITEM corpus's animated
-// texture transforms render on the lane that runs none of them.
+// entityuvscan: the unit, GameObject and held-item corpus
 // ---------------------------------------------------------------------------
 
-/// How many display ids print per model before the rest are counted.
 const ENTITY_ID_ROWS: usize = 12;
 
-/// How many unreadable model paths print before the rest are counted.
 const ENTITY_UNREAD_ROWS: usize = 20;
 
-/// The `Item\ObjectComponents\<dir>\` folders an `ItemDisplayInfo` **left** model column can land
-/// in, and the kind label each one carries. The directory is NOT a column of the table: it is
-/// chosen by the slot the item is worn in (`entities::equipment::ensure_item_model`), which is a
-/// property of the *item*, not of the display — so a census asks the archives which of them
-/// actually holds the file.
+/// The `Item\ObjectComponents\<dir>\` folders an `ItemDisplayInfo` left model can live in. The
+/// table has no folder column (the worn slot picks it), so the census asks the archives.
 const ITEM_DIRS_L: [&str; 4] = ["Weapon", "Shield", "Shoulder", "Quiver"];
 
-/// …and of a **right** model column: the right pauldron, or an arrow/bullet.
+/// The folders a right model can live in: the right pauldron, or an arrow or bullet.
 const ITEM_DIRS_R: [&str; 2] = ["Shoulder", "Ammo"];
 
-/// Helm files are per race and sex — `<stem>_<Ra><S>.m2`, prefix by race id, `M`/`F` by sex
-/// (`ensure_item_model`'s own table, pinned against the MPQ listing in decision 0074).
+/// Helm files are per race and sex, `<stem>_<Ra><S>.m2`: this prefix by race id, then `M` or `F`,
+/// as `ensure_item_model` spells them.
 const HELM_RACE_PREFIX: [&str; 8] = ["Hu", "Or", "Dw", "Ni", "Sc", "Ta", "Gn", "Tr"];
 
-/// One entity-lane model's place in the DBCs: every table row that can put it on screen, so a
-/// broken batch joins back to something a director can go and look at.
+/// Every table row that can put an entity-lane model on screen.
 #[derive(Default)]
 struct EntityReach {
     /// The table's own spelling of the path (`.mdx`), for display.
     path: String,
     /// The `CreatureModelData` row ids naming it (normally one).
     creature_models: std::collections::BTreeSet<u32>,
-    /// The `CreatureDisplayInfo` rows that reach it — the POPULATION number: one model reached by
-    /// 300 display rows is a different fix from one reached by 1.
+    /// The `CreatureDisplayInfo` rows that reach it, the population measure.
     creature_displays: Vec<u32>,
-    /// The playable `(race, sex)` bodies among those displays (`ChrRaces` cols 4/5 → the same
-    /// CreatureDisplayInfo chain a streamed unit takes, decision 0041), spelled as the glue does.
+    /// The playable `(race, sex)` bodies among those displays (`ChrRaces` columns 4 and 5).
     player_bodies: Vec<String>,
-    /// `GameObjectDisplayInfo` rows naming it.
     go_displays: Vec<u32>,
     /// `ItemDisplayInfo` rows naming it, and through which `Item\ObjectComponents\` join.
     item_displays: BTreeMap<u32, std::collections::BTreeSet<&'static str>>,
-    /// The bone-pile skeletons (`<Race><Sex>DeathSkeleton`) — the corpse lane's own models, which
-    /// no display table names.
+    /// The corpse lane's bone piles (`<Race><Sex>DeathSkeleton`), which no display table names.
     bones: Vec<String>,
-    /// Also named by the SPELL-VISUAL chain, i.e. already swept by `fxuvscan` and already running
-    /// its transform on the effect lane since 2282. Marked, never dropped: a model can be held in
-    /// a hand (this lane, frozen) and thrown as a missile (that lane, animated) on the same tick.
+    /// Also reached by the spell-visual chain, so also swept by `fxuvscan`.
     also_fx: bool,
 }
 
 impl EntityReach {
-    /// How many table rows can put this model on screen — the rough instance-population proxy.
+    /// Table rows that can put this model on screen, a rough population measure.
     fn rows(&self) -> usize {
         self.creature_displays.len()
             + self.go_displays.len()
@@ -1909,26 +1689,21 @@ impl EntityReach {
 #[derive(Default)]
 struct EntityCorpus {
     models: BTreeMap<String, EntityReach>,
-    /// `CreatureDisplayInfo` rows walked, and the `CreatureModelData` rows no display reaches
-    /// (unreachable content — counted, never swept).
+    /// `CreatureDisplayInfo` rows walked, and `CreatureModelData` rows no display reaches.
     creature_rows: usize,
     creature_orphan_models: usize,
     /// `GameObjectDisplayInfo` rows walked, and those naming a `.wmo` (no M2 batches to animate).
     go_rows: usize,
     go_wmo: usize,
-    /// `ItemDisplayInfo` model columns walked, and the two ways one can fail to reach a file: the
-    /// basename ships under an `Item\ObjectComponents\` folder this column is never joined to
-    /// (`item_other_dir` — every one of these is a thrown weapon named in BOTH columns, so the
-    /// model is already in the corpus through its left column and only the extra display-id join
-    /// is dropped), or nothing ships it at all (`item_absent` — a dead row, the shape `fxuvscan`
-    /// found in `SpellVisualEffectName`).
+    /// `ItemDisplayInfo` model columns walked; `item_other_dir` names a file under a folder its
+    /// column never joins (thrown weapons, swept through the left column), `item_absent` a file
+    /// nothing ships.
     item_rows: usize,
     item_other_dir: usize,
     item_absent: usize,
 }
 
-/// Fold one model path into the corpus under [`crate::model_key`], keeping the table's own
-/// spelling for display.
+/// Fold one model path into the corpus under [`crate::model_key`], keeping the table's spelling.
 fn entity_record<'a>(
     out: &'a mut BTreeMap<String, EntityReach>,
     path: &str,
@@ -1942,15 +1717,9 @@ fn entity_record<'a>(
     e
 }
 
-/// Every model the ENTITY lane can render, walked from the tables that name one — never from a
-/// path prefix, because reachability is the whole question ("the path looks broken" and "the path
-/// is reachable" are different questions, 2282's own closing note).
-///
-/// Four sources, one per `build_parts` caller that is not the spell-effect lane:
-/// `CreatureDisplayInfo` → `CreatureModelData` (every NPC, critter, mount — and every PLAYER body,
-/// which resolves through the same chain, decision 0041), `GameObjectDisplayInfo`,
-/// `ItemDisplayInfo`'s two model columns joined to the `Item\ObjectComponents\` folder the archives
-/// actually hold them in, and the corpse lane's `<Race><Sex>DeathSkeleton` bone piles.
+/// Every model the entity lane can render, walked from the tables: `CreatureDisplayInfo` →
+/// `CreatureModelData` (player bodies included), `GameObjectDisplayInfo`, `ItemDisplayInfo`'s two
+/// model columns joined to the folders that hold them, and the corpse lane's bone piles.
 fn entity_corpus(chain: &mut Chain) -> Result<EntityCorpus> {
     let mut out = EntityCorpus::default();
 
@@ -2017,15 +1786,12 @@ fn entity_corpus(chain: &mut Chain) -> Result<EntityCorpus> {
     }
 
     // --- held / worn item geometry ----------------------------------------------------------
-    // The archives decide which folder a display's basename lives in, because the table does not
-    // carry one: the equipment lane picks the directory from the slot the item is worn in.
     let item_files: Vec<String> = super::m2_names(chain, Some("item\\objectcomponents"))?
         .into_iter()
         .map(|n| n.to_ascii_lowercase())
         .collect();
     let files: std::collections::HashSet<&str> = item_files.iter().map(String::as_str).collect();
-    // …and the same listing keyed by BASENAME, so an unjoinable column can say which of the two
-    // failures it is rather than being counted as one lump.
+    // The same listing by basename, to tell `item_other_dir` from `item_absent`.
     let by_base: std::collections::HashSet<&str> = item_files
         .iter()
         .filter_map(|f| f.rsplit_once('\\').map(|(_, b)| b))
@@ -2054,8 +1820,7 @@ fn entity_corpus(chain: &mut Chain) -> Result<EntityCorpus> {
                     placed = true;
                 }
             }
-            // A HELM ships as sixteen per-race/sex files under one stem, and the display row names
-            // the stem alone — so the census expands it the way the attach does.
+            // A helm row names only the stem; the files are per race and sex.
             if col == 0 {
                 let stem = name.strip_suffix(".m2").unwrap_or(name);
                 for prefix in HELM_RACE_PREFIX {
@@ -2079,9 +1844,7 @@ fn entity_corpus(chain: &mut Chain) -> Result<EntityCorpus> {
         }
     }
 
-    // Every id list above is built by walking a HashMap, so it comes out in a different order
-    // every run. Sorted here, once, because an instrument whose report reshuffles cannot be
-    // diffed against its own previous output.
+    // The id lists come from HashMap walks: sort them so the report diffs run to run.
     for e in out.models.values_mut() {
         e.creature_displays.sort_unstable();
         e.go_displays.sort_unstable();
@@ -2089,7 +1852,7 @@ fn entity_corpus(chain: &mut Chain) -> Result<EntityCorpus> {
         e.bones.sort();
     }
 
-    // --- the mark: which of these the spell-effect lane already runs -------------------------
+    // --- the models the spell-visual chain also reaches -------------------------------------
     if let (Ok(visuals), Ok(spells)) = (
         benilla_formats::load_spell_visual_catalog(chain),
         benilla_formats::load_spell_catalog(chain),
@@ -2103,22 +1866,18 @@ fn entity_corpus(chain: &mut Chain) -> Result<EntityCorpus> {
     Ok(out)
 }
 
-/// Which clock one batch's keyed transform runs on — the question that decides the SHAPE of the
-/// fix, not just its size (0136 choice 1 versus 2282's per-instance lane).
+/// Which clock a batch's keyed transform runs on.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 enum UvClock {
-    /// Every live loop is clocked on a **global sequence**: a free-running per-scene ms clock the
-    /// reference anchors once per instance at attach (`gseq-anchor.md`, `CM2Model+0x68`). One
-    /// shared uniform on a free-running clock is faithful here — 0136's lane, unchanged.
+    /// Every live loop runs on a global sequence, a free-running clock the reference anchors once
+    /// per instance at attach (`0x70eae1`, `CM2Model+0x68`), so one shared uniform serves it.
     Gseq,
-    /// Every live loop is clocked on its **sequence band**: the host's own playing-clip time, so
-    /// two instances playing different animations — or the same one at different phases — are at
-    /// different offsets. A shared uniform cannot be right for both.
+    /// Every live loop runs on its sequence band, the host's play head, which no shared uniform
+    /// serves.
     Band,
     /// The batch's three channels disagree: some global, some band.
     Mixed,
-    /// Keyed but never moving — a constant non-identity hold (`period == 0`), which needs a seed
-    /// and no clock at all.
+    /// A constant hold (`period == 0`): a seed, no clock.
     Hold,
 }
 
@@ -2155,20 +1914,20 @@ impl UvClock {
 /// One transform channel's read of the clock question.
 #[derive(Default)]
 struct ChannelClock {
-    /// `[L.L]` per file sequence slot — `None` when the channel carries no per-slot set.
+    /// `[L.L]` per file slot; `None` without a per-slot set.
     cell: Option<String>,
-    /// File slots whose loop is LIVE (`period > 0`).
+    /// File slots whose loop is live (`period > 0`).
     live: Vec<usize>,
     /// `true` for each live loop clocked on a global sequence.
     gseq: Vec<bool>,
     /// The leading live loop as the report prints it: `(period, wrap, gseq)`.
     lead: Option<(f32, bool, bool)>,
-    /// The channel's one loop is the SHARED slot-0 bake — every sequence plays the same one.
+    /// The channel's one loop is the shared slot-0 bake.
     uniform: bool,
 }
 
 impl ChannelClock {
-    /// `gseq 2.000s wrap` / `band 1.500s clamp` / `—`.
+    /// `gseq 2.000s wrap`, `band 1.500s clamp`, `held`, or a dash.
     fn cell_text(&self) -> String {
         match self.lead {
             None if self.cell.is_none() => "—".to_string(),
@@ -2182,8 +1941,7 @@ impl ChannelClock {
     }
 }
 
-/// Read one channel's per-slot set (or its shared slot-0 twin, for the translation channel which is
-/// the only one that has one) the way the runtime reads it.
+/// Read one channel's per-slot set, or the translation channel's shared slot-0 loop.
 fn channel_clock<V: AsRef<[f32]> + PartialEq>(
     set: Option<&SeqLoops<V>>,
     shared: Option<&KeyAnim<V>>,
@@ -2214,7 +1972,6 @@ fn channel_clock<V: AsRef<[f32]> + PartialEq>(
     out
 }
 
-/// One classified entity batch — the row every listing and the population tail are built from.
 struct EntityHit {
     key: String,
     batch: usize,
@@ -2223,22 +1980,18 @@ struct EntityHit {
     clock: UvClock,
     /// `T`/`R`/`S`, in that order, for the channels the bake keyed.
     chans: [bool; 3],
-    /// The batch's translation lane: `true` when it carries a per-sequence set (`uv_seq`), which is
-    /// `uvslotscan`'s PER-PLACEMENT population; `false` when it keeps the shared slot-0 loop.
+    /// The translation has a per-sequence set (`uv_seq`), `uvslotscan`'s per-placement population.
     per_seq_trans: bool,
-    /// …and whether that shared loop is LIVE — `uvslotscan`'s "carry a LIVE loop there" count, the
-    /// number this sweep's corpus must be a subset of.
+    /// The shared translation loop is live, `uvslotscan`'s live shared count.
     live_shared_trans: bool,
 }
 
-/// Sweep every model the UNIT / GAMEOBJECT / HELD-ITEM tables reach and census the batches whose
-/// texture transform animates — see the `Entityuvscan` command doc for the why.
+/// Classify the keyed texture-transform and tint batches the unit, GameObject and item tables
+/// reach.
 pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let corpus = entity_corpus(chain)?;
     let pfx = prefix.map(|p| p.to_ascii_lowercase().replace('/', "\\"));
     let anim_names = benilla_formats::load_anim_data_catalog(chain).ok();
-    // Loaded once, beside the corpus, because the per-batch sheet question asks it per MODEL: a
-    // creature batch's `Monster1/2/3` slot is filled from the display's own texture variations.
     let creatures = benilla_formats::load_creature_catalog(chain).unwrap_or_default();
 
     let mut sheets: BTreeMap<String, Option<Sheet>> = BTreeMap::new();
@@ -2255,20 +2008,17 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let mut misregistered = 0u32;
     // The `uvslotscan` cross-check: this corpus's share of the two whole-corpus translation counts.
     let (mut live_shared, mut per_seq) = (0u32, 0u32);
-    // Batches whose sheet is filled at RUNTIME (a creature skin variation, a character composite),
-    // and those where two of a model's skins disagree about what a frozen batch paints.
+    // Batches whose sheet is filled at runtime (a creature skin, a character composite), and
+    // those where two of a model's skins disagree about what a frozen batch paints.
     let (mut skin_filled, mut skin_disagrees) = (0u32, 0u32);
 
-    // --- the TINT half of the same sweep (the second dead channel on this lane) ---
+    // --- the tint half of the same sweep ---
     let (mut tint_models, mut tint_batches) = (0u32, 0u32);
     let mut tint_class: BTreeMap<TintClass, u32> = BTreeMap::new();
     let mut tint_clock: BTreeMap<UvClock, u32> = BTreeMap::new();
     let mut tint_hits: Vec<TintHit> = Vec::new();
     let mut tint_blocks: Vec<(String, Vec<String>)> = Vec::new();
     let (mut tint_live_shared, mut tint_per_seq) = (0u32, 0u32);
-    // …and the ALPHA channel beside them, which this lane DOES serve — counted so the report can
-    // say which of the three material-animation channels is a hole and which is not, rather than
-    // leaving the reader to assume all three are the same.
     let (mut alpha_models, mut alpha_batches, mut alpha_live) = (0u32, 0u32, 0u32);
 
     let keys: Vec<String> = corpus.models.keys().cloned().collect();
@@ -2295,9 +2045,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         };
         batches += subs.len() as u64;
-        // Any of the three channels keeps the model: a batch can animate its tint and not its UVs
-        // (four do), and gating on `uv_keyed` alone is exactly the shape of predicate this sweep
-        // exists to catch.
+        // Any of the three channels keeps the model: a batch can animate its tint and not its UVs.
         if !subs
             .iter()
             .any(|sub| uv_keyed(sub) || tint_keyed(sub) || sub.alpha_anim.is_some())
@@ -2305,16 +2053,13 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         }
         let no_alpha_add = authors_no_alpha_add(&bytes);
-        // File sequence slot -> its `AnimationData.dbc` id, so a BAND loop can be named by the
-        // animations that carry it rather than by an opaque slot number. A slot with no entry is a
-        // zero-duration sequence (`parse_m2_animations` drops those; the bake does not).
+        // File slot -> `AnimationData.dbc` id; a missing slot is a zero-duration sequence, which
+        // the parse drops and the bake keeps.
         let slot_anim: BTreeMap<usize, u16> = benilla_formats::parse_m2_animations(&bytes)
             .iter()
             .map(|a| (a.seq_index, a.anim_id))
             .collect();
-        // The creature skins this model is rendered with — `Monster1/2/3` is blank in the M2 and
-        // filled per display from `CreatureDisplayInfo.textureVariation`, so a batch on one of
-        // those slots has as many sheets as the model has skins.
+        // The creature skins per `Monster1/2/3` slot, from each display's `textureVariation`.
         let mut skins: [std::collections::BTreeSet<String>; 3] = Default::default();
         for d in &corpus.models[&key].creature_displays {
             let Some(m) = creatures.model(*d) else {
@@ -2327,8 +2072,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             }
         }
 
-        // WHICH BANDS carry the keys — the load-bearing half for a band loop, because it says
-        // whether the loop is one animation's or every animation's. Shared by both channels.
+        // Which bands carry the live loops, named by animation.
         let slot_line = |c: &ChannelClock| -> String {
             match (&c.cell, c.uniform) {
                 (Some(cell), _) => {
@@ -2351,7 +2095,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             }
         };
 
-        // --- the TINT + ALPHA pass over the same batches -----------------------------------
+        // --- the tint and alpha pass over the same batches ---------------------------------
         let mut tlines: Vec<String> = Vec::new();
         let mut model_has_alpha = false;
         for (bi, sub) in subs.iter().enumerate() {
@@ -2429,9 +2173,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             }
             anim_batches += 1;
 
-            // WHICH SHEET. An authored path where the batch carries one; otherwise the display's
-            // own skin variations, each asked separately — the frozen verdict is a property of the
-            // texture, and two skins of one model can answer differently.
+            // The sheet: the authored path, else each of the display's skins, which can differ.
             let candidates: Vec<String> = match (&sub.texture, sub.skin_slot, sub.char_slot) {
                 (Some(t), _, _) => vec![t.clone()],
                 (None, Some(slot), _) => {
@@ -2442,8 +2184,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                         .unwrap_or_default()
                 }
                 (None, None, Some(_)) => {
-                    // A runtime character composite (body atlas, object skin, hair): there is no
-                    // authored sheet to judge, and UNKNOWN is what that has to read as.
+                    // A runtime character composite has no sheet to judge: UNKNOWN.
                     skin_filled += 1;
                     Vec::new()
                 }
@@ -2464,7 +2205,6 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             }
             let read = &reads[0].1;
 
-            // THE CLOCK, per channel, exactly as the runtime resolves it.
             let t = channel_clock(sub.uv_seq.as_ref(), sub.uv_anim.as_ref());
             let r = channel_clock::<[f32; 4]>(sub.uv_rot_seq.as_ref(), None);
             let s = channel_clock::<[f32; 2]>(sub.uv_scale_seq.as_ref(), None);
@@ -2538,8 +2278,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             if s.cell.is_some() {
                 lines.push(format!("      slots  S {}", slot_line(&s)));
             }
-            // …and, when the translation set exists, WHY the bake refused the shared lane — the
-            // `uniform()` question `uvslotscan` asks, asked here of the same set.
+            // Why the bake refused the shared lane, as `uvslotscan` reports it.
             if let Some(set) = sub.uv_seq.as_ref() {
                 let v = classify(set, Channel::Uv);
                 lines.push(format!("      uv_seq {:<12} {}", v.why.label(), v.detail));
@@ -2622,9 +2361,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
          counts for the same two lanes (its `of those … carry a LIVE loop there` and \
          `PER-PLACEMENT` lines) — this corpus is a subset of that one by construction."
     );
-    // The two translation lanes NAMED, not just counted: `uvslotscan` prints the same two
-    // populations over the whole corpus, so listing the models here makes the subset claim
-    // checkable by eye instead of on trust.
+    // The two translation lanes by model, to check against `uvslotscan`'s listings.
     let mut shared_models: std::collections::BTreeSet<&str> = std::collections::BTreeSet::new();
     let mut per_seq_models: BTreeMap<&str, u32> = BTreeMap::new();
     for h in &hits {
@@ -2670,8 +2407,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         }
     }
 
-    // Every model carrying a batch of class `c`, with the rows that reach it — the join back from
-    // a verdict to something a director can go and stand in front of.
+    // Every model with a batch of class `c`, and the table rows that reach it.
     let listing = |title: &str, note: &str, pick: fn(&EntityHit) -> FxClass, c: FxClass| {
         let rows: Vec<&EntityHit> = hits.iter().filter(|h| pick(h) == c).collect();
         if rows.is_empty() {
@@ -2711,9 +2447,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             c,
         );
     }
-    // The batches the first-key seed alone condemns: they draw today, and would stop drawing on a
-    // lane that seeds the loop's opening value without running it. Named, because that is exactly
-    // the shape of a half-finished fix.
+    // Batches invisible only at the first-key seed, where a lane that never ticks the loop sits.
     let key_only: Vec<&EntityHit> = hits
         .iter()
         .filter(|h| h.key_class == FxClass::Invisible && h.class != FxClass::Invisible)
@@ -2741,8 +2475,6 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         }
     }
 
-    // The deliverable: every affected model, what it renders today, and how much of the world
-    // reaches it — sorted by POPULATION, because that is what sizes the fix.
     let mut models: BTreeMap<&str, (Vec<&EntityHit>, usize)> = BTreeMap::new();
     for h in &hits {
         let e = models.entry(h.key.as_str()).or_default();
@@ -2784,8 +2516,7 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     }
 
     // =====================================================================================
-    // The M2COLOR TINT half. Same corpus, same walk, a different dead channel — and a
-    // different failure mode, because a tint is a multiply and a UV offset is a lookup.
+    // The M2Color tint half: a tint multiplies, where a UV offset looks up.
     // =====================================================================================
     println!();
     println!(
@@ -2890,7 +2621,6 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
          already."
     );
 
-    // The join-back for the tint, by class — same shape as the UV listings.
     let tlisting = |title: &str, c: TintClass| {
         let rows: Vec<&TintHit> = tint_hits.iter().filter(|h| h.class == c).collect();
         if rows.is_empty() {
@@ -2931,7 +2661,6 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         tlisting(c.label(), c);
     }
 
-    // …and the population tail, sorted the same way the UV one is.
     let mut tmodels: BTreeMap<&str, (Vec<&TintHit>, usize)> = BTreeMap::new();
     for h in &tint_hits {
         let e = tmodels.entry(h.key.as_str()).or_default();
@@ -2964,20 +2693,16 @@ pub fn entityuvscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
 }
 
 // ---------------------------------------------------------------------------
-// The M2COLOR TINT half of the same census — the second dead channel on the
-// same lane, found by asking where `register_tint` is called from.
+// The M2Color tint half of the entity census
 // ---------------------------------------------------------------------------
 
-/// Does this batch's M2Color tint animate? The runtime's own test: the shared slot-0 bake, or the
-/// per-sequence set the bake keeps when the slots disagree. The twin of [`uv_keyed`], and written
-/// as a union for the same reason — a predicate spelled `rgb_anim.is_some()` silently skips a batch
-/// whose slot 0 is a dead hold beside a live later slot (the tint corpus has four of those).
+/// Whether the batch's tint is keyed: the shared slot-0 loop, or the per-sequence set, which
+/// alone carries a batch whose slot 0 is dead.
 fn tint_keyed(sub: &benilla_formats::RenderSubmesh) -> bool {
     sub.rgb_anim.is_some() || sub.rgb_seq.is_some()
 }
 
-/// How many file sequence slots this batch's tint was baked across (1 when only the shared
-/// single-slot loop exists) — [`fx_slots`]'s tint twin.
+/// How many file sequence slots the tint was baked across, at least 1.
 fn tint_slots(sub: &benilla_formats::RenderSubmesh) -> usize {
     sub.rgb_seq.as_ref().map_or(1, |s| s.slots().len()).max(1)
 }
@@ -2991,9 +2716,7 @@ fn tint_period(sub: &benilla_formats::RenderSubmesh, slot: usize) -> f32 {
     }
 }
 
-/// The tint at `(slot, t)`, read the way a consumer that RAN this channel would read it — the
-/// per-slot set when the bake built one, else the single shared loop ([`fx_state`]'s shape).
-/// White where neither exists, which is the tint identity.
+/// The tint at `(slot, t)`: the per-slot set, else the shared loop, else white.
 fn tint_state(sub: &benilla_formats::RenderSubmesh, slot: usize, t: f32) -> [f32; 3] {
     match (&sub.rgb_seq, &sub.rgb_anim) {
         (Some(s), _) => s.seq(Some(slot)).map_or([1.0; 3], |l| l.sample(t)),
@@ -3002,33 +2725,22 @@ fn tint_state(sub: &benilla_formats::RenderSubmesh, slot: usize, t: f32) -> [f32
     }
 }
 
-/// Rec.709 relative luminance — a reading aid for "how far apart are these two tints", not a
-/// perceptual model. The per-channel deltas beside it are the evidence; this is the single number
-/// that sorts a hue swap from a brightness swing.
+/// Rec.709 relative luminance, a reading aid beside the per-channel deltas.
 fn luma(c: [f32; 3]) -> f32 {
     0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]
 }
 
-/// What a consumer that seeds the tint and never re-samples it renders.
-///
-/// A tint is a **multiply**, so the failure mode is never "invisible geometry" the way a UV freeze
-/// can be — it is the wrong colour, and how wrong is the only question worth asking. The bands are
-/// a reading aid over one measured number (the worst per-channel distance between the frozen value
-/// and anything the loop reaches, in 0..1 tint units); every batch prints that number, so the call
-/// is checkable and the thresholds are not load-bearing.
+/// What a consumer that seeds the tint and never re-samples it renders, banded by the worst
+/// per-channel distance between the seed and anything the loop reaches (0..1 tint units).
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 enum TintClass {
-    /// The frozen tint is (near) BLACK while the loop reaches lit values: the multiply kills the
-    /// batch's colour outright, so it draws black — or, on an additive batch, not at all. The one
-    /// band where "wrong colour" becomes "wrong existence".
+    /// The seed is near black while the loop lights up: it draws black, or nothing if additive.
     Black,
-    /// The frozen value is a quarter of the tint range or more away from what the loop reaches —
-    /// a colour difference nobody has to look for.
+    /// 0.25 or more away.
     Strong,
     /// Between 0.05 and 0.25 away: visible side by side, easy to miss alone.
     Slight,
-    /// Under 0.05 away — the loop barely moves, or it moves and comes back. Frozen is
-    /// unobjectionable, and counting it as a bug would overstate the hole.
+    /// Under 0.05 away: the loop barely moves.
     Negligible,
 }
 
@@ -3061,38 +2773,28 @@ impl TintClass {
     }
 }
 
-/// One batch's whole tint read.
 struct TintBatch {
     class: TintClass,
-    /// What `model_material` actually bakes into `tint.xyz`: `rgb_anim.sample(0.0)` — the SHARED
-    /// slot-0 loop's first key — or identity white when there is no slot-0 bake at all.
+    /// What `model_material` seeds into `tint.xyz`: the shared loop's first key, else white.
     seed: [f32; 3],
-    /// …and which of those two it was. A white seed is the tint twin of the UV lane's DEAD-0: the
-    /// batch's live tint lives in a later sequence slot the shared material cannot see.
+    /// The seed is white: there is no shared loop, and the tint lives in a later slot.
     seed_is_white: bool,
     /// The worst per-channel distance between the seed and anything the loop reaches.
     delta: f32,
-    /// This batch carries a per-sequence set (`rgb_seq`) — `uvslotscan`'s PER-PLACEMENT population.
     per_seq: bool,
-    /// …and the shared slot-0 loop is live (`period > 0`) — its SHARED-live population.
     live_shared: bool,
     lines: Vec<String>,
 }
 
-/// Read one batch's animated tint — see [`TintBatch`]. The caller has established [`tint_keyed`].
+/// Read one batch's keyed tint; the caller has checked [`tint_keyed`].
 fn tint_batch(sub: &benilla_formats::RenderSubmesh, bi: usize) -> TintBatch {
     let slots = tint_slots(sub);
-    // THE SEED, read off the builder rather than assumed: `model_render::model_material` does
-    // `rgb_anim.map_or([1,1,1], |a| a.sample(0.0))` and writes it to `tint.xyz`, and
-    // `batch::Materials::build` hands it `sub.rgb_anim.as_ref()` UNCONDITIONALLY — there is no
-    // `play_rgb` gate to flip. So unlike the UV channel, which freezes at the identity, the tint
-    // freezes at the loop's OPENING COLOUR… except where slot 0 baked nothing, and then it freezes
-    // at white while every live slot tints.
+    // `model_material` seeds `tint.xyz` with `rgb_anim`'s first key, or white without one, and
+    // the builder always hands it the loop, so an unticked tint holds its opening colour.
     let seed = sub.rgb_anim.as_ref().map_or([1.0; 3], |a| a.sample(0.0));
     let seed_is_white = sub.rgb_anim.is_none();
 
-    // Everything the loop reaches, over every slot and a uniform sweep of each — the same
-    // over-approximating union `uv_batch` takes, for the same reason.
+    // Everything the loop reaches: the same sampled union `uv_batch` takes.
     let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
     let mut delta = 0.0f32;
     for slot in 0..slots {
@@ -3157,20 +2859,15 @@ fn tint_batch(sub: &benilla_formats::RenderSubmesh, bi: usize) -> TintBatch {
     }
 }
 
-/// One classified entity tint batch — the row the listings and the population tail are built from.
 struct TintHit {
     key: String,
     batch: usize,
     class: TintClass,
     clock: UvClock,
-    /// The colour the material is frozen at — printed in the listings, because "which wrong
-    /// colour" is the whole content of a tint bug.
+    /// The colour the material is seeded with.
     seed: [f32; 3],
-    /// **Is the freeze visible at REST?** True when file sequence slot 0 — the band a resting
-    /// instance plays — carries a live loop. False means the seed is the right colour in every
-    /// state but the ones a later slot keys, so the batch is wrong only *while that animation
-    /// plays*. Four of this corpus's five are that second shape, and reporting them as flatly
-    /// broken would overstate the hole.
+    /// Slot 0, the band a resting instance plays, carries a live loop; otherwise the seed holds
+    /// until a later slot's animation plays.
     rest_wrong: bool,
     seed_is_white: bool,
     delta: f32,
diff --git a/crates/benilla-formats/src/bin/benilla-extract/scan/mod.rs b/crates/benilla-formats/src/bin/benilla-extract/scan/mod.rs
index 8b284b47..cb49a36b 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/scan/mod.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/scan/mod.rs
@@ -1,24 +1,5 @@
-//! Corpus-scan reports: the **population instruments** that sweep many models or placements to
-//! answer "how big is this class, and where does it live", rather than dumping one asset (that is
-//! [`crate::m2dump`]'s job). Every one of them is reached as `scan::<name>` from the dispatch in
-//! [`crate::main`]; the submodules group them by the question they answer, not by the file format
-//! they read:
-//!
-//! - [`world`] — placed content: a WMO root's own tables, an ADT block's placements.
-//! - [`lighting`] — what lights a model: the WMO prop lanes, M2 light blocks, terrain shadow.
-//! - [`geometry`] — what geometry a model draws: billboards, geosets, flat ground quads.
-//! - [`material`] — how a batch is textured and blended: blend modes, UV wrap, env stages,
-//!   the batches whose UV/tint loop differs between sequence slots, and what the spell-effect
-//!   (`fxuvscan`) and unit/GameObject/held-item (`entityuvscan`) corpora's animated texture
-//!   transforms render for a consumer that runs none of them.
-//! - [`particles`] — particle and ribbon emitters, and the features the corpus authors.
-//! - [`skeleton`] — the bone tree and the attachment table that addresses it.
-//! - [`sequence`] — which sequence an arm plays, what breaks when it is the wrong one, and
-//!   which of its event markers an arm can reach at all.
-//!
-//! Split out of a single 3.9k-line `scan.rs` once it had grown ~30 independent sweeps: the file
-//! was one *kind* of thing, but not one concern, and nothing in it was shared across families
-//! except the corpus listing below.
+//! Corpus-scan reports: sweeps over many models or placements that measure how big a class is
+//! and where it lives, grouped by the question they answer rather than the format they read.
 
 use anyhow::{Context, Result};
 use benilla_formats::Chain;
@@ -45,13 +26,8 @@ pub use sequence::{
 pub use skeleton::{attachscan, bonescan, eventmarkerscan};
 pub use world::{doodadscan, placescan, skyboxscan, wmodoodads};
 
-/// Every `.m2` in the chain, in listfile order, narrowed to a path `prefix` when one is given.
-///
-/// The opening line of nearly every sweep here, and — before the split — twenty-two copy-pasted
-/// copies of it. Names come back in their listfile casing (that is what a report prints and what
-/// [`Chain::read_file`] is handed); the `.m2` test and the prefix match are both done on a
-/// lowercased copy, and the prefix is normalized to the chain's own `\` separators, so a caller
-/// may pass either slash in either case.
+/// Every `.m2` in the chain in listfile order and casing, narrowed to a path `prefix` matched
+/// case-insensitively with either slash.
 pub(crate) fn m2_names(chain: &mut Chain, prefix: Option<&str>) -> Result<Vec<String>> {
     let pfx = prefix.map(|p| p.to_ascii_lowercase().replace('/', "\\"));
     Ok(chain
@@ -66,16 +42,8 @@ pub(crate) fn m2_names(chain: &mut Chain, prefix: Option<&str>) -> Result<Vec<St
         .collect())
 }
 
-/// Every WMO **root** in the chain, narrowed to a path `prefix` when one is given — same casing
-/// and matching rules as [`m2_names`].
-///
-/// A WMO ships as one root plus one file per group, named `<stem>_NNN.wmo`. Only the root carries
-/// the tables a sweep wants (MOHD/MODS/MODD/MOGI/MOLT/MOSB); a group file handed to
-/// [`benilla_formats::parse_wmo_root`] is just a parse failure to skip. Underscore then exactly
-/// three digits is the whole test — and it is here, once, because the two sweeps that used to
-/// spell it inline had drifted into spelling it *differently* (one guarded a stem shorter than
-/// four characters, the other did not, so a hypothetical `123.wmo` was a root to one and a group
-/// to the other).
+/// Every WMO root in the chain, narrowed like [`m2_names`]. Only a root carries the
+/// MOHD/MODS/MODD/MOGI/MOLT/MOSB tables; a group file is `<stem>_NNN.wmo`, exactly three digits.
 pub(crate) fn wmo_roots(chain: &mut Chain, prefix: Option<&str>) -> Result<Vec<String>> {
     let pfx = prefix.map(|p| p.to_ascii_lowercase().replace('/', "\\"));
     Ok(chain
@@ -96,9 +64,7 @@ pub(crate) fn wmo_roots(chain: &mut Chain, prefix: Option<&str>) -> Result<Vec<S
         .collect())
 }
 
-/// Capitalize an `Item\ObjectComponents\<sub>` path component for consistent family-key display
-/// regardless of how a given asset's listfile entry happened to be cased (`WEAPON`/`weapon`/
-/// `Weapon` all collapse to `Weapon`).
+/// Title-case an `Item\ObjectComponents\<sub>` component so its listfile casings share one key.
 fn title_case(s: &str) -> String {
     let mut chars = s.chars();
     match chars.next() {
@@ -109,17 +75,8 @@ fn title_case(s: &str) -> String {
     }
 }
 
-/// The top-level content-family bucket for an internal M2 path — the summary dimension for "how
-/// much content is affected, and of what KIND", shared by [`lighting::m2lightscan`] and
-/// [`material::uvslotscan`]. Derived from the path's first one or two components,
-/// case-insensitively.
-///
-/// The split that earns its keep is `World\` versus everything else: a `World\` model is a placed
-/// doodad or WMO prop, which reaches the screen through the shared-material lanes (the M2-light
-/// spawn, the `UvAnimMaterials`/`MatAnimTable` registries), while a `Creature\`/`Spells\` one
-/// reaches an entirely different consumer. `World\Goober\` (GameObject displays) splits off again
-/// because it is the hosted lane, not the ADT/WMO one; everything not otherwise named folds into
-/// `other`.
+/// The content family of an M2 path, a sweep's summary dimension: `World\` is placed doodads and
+/// WMO props, `World\Goober\` GameObject displays.
 pub(super) fn family_of(name: &str) -> String {
     let comps: Vec<&str> = name.split('\\').collect();
     let low = |s: &str| s.to_ascii_lowercase();
diff --git a/crates/benilla-formats/src/bin/benilla-extract/scan/particles.rs b/crates/benilla-formats/src/bin/benilla-extract/scan/particles.rs
index 276b8a6b..9d0709aa 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/scan/particles.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/scan/particles.rs
@@ -1,9 +1,5 @@
-//! Corpus scans over **particle and ribbon emitters** — which of the emitter system's features
-//! the shipped data actually authors, and which shapes a consumer can get wrong.
-//!
-//! The feature census (`partcensus`), the flipbook ramps (`cellscan`), the per-slot emission
-//! windows (`partslotscan`), the 3-D geometry-model shards (`shardcensus`), and the draw-order
-//! population effects share with their owner's own transparent batches (`fxordercensus`).
+//! Corpus scans over particle and ribbon emitters: the features the data authors, and the shapes
+//! a consumer can get wrong.
 
 use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
 
@@ -12,14 +8,9 @@ use benilla_formats::Chain;
 
 use crate::model_key;
 
-/// Sweep every `.m2` in the chain and list the models carrying RIBBON emitters, with each
-/// model's `+0xc0` **enable-gate** census beside the count — the population instrument for
-/// "which trails are state-dependent, and where does the gate actually key".
-///
-/// A `GATED` line names the sequences a trail is dark in; `MID-SEQ` marks the models whose gate
-/// flips *inside* a band rather than only at its start, which a band-start-only reader cannot
-/// express (decision 1011 — `G_FrostTrap`'s streamers light 200 ms into the trigger and nowhere
-/// else, so a band-start read says "never" and an ungated consumer says "always").
+/// List the models with ribbon emitters and each ribbon's `+0xc0` enable gate per sequence;
+/// `MID-SEQ` marks a gate that flips inside a band, not only at its start (`G_FrostTrap`'s
+/// streamers light 200 ms into the trigger and nowhere else).
 pub fn ribbonscan(chain: &mut Chain) -> Result<()> {
     let names = super::m2_names(chain, None)?;
     let (mut scanned, mut hits, mut gated, mut mid_seq) = (0u32, 0u32, 0u32, 0u32);
@@ -35,7 +26,6 @@ pub fn ribbonscan(chain: &mut Chain) -> Result<()> {
         }
         hits += 1;
         let defs = benilla_formats::parse_m2_ribbon_emitters(&bytes).unwrap_or_default();
-        // Per ribbon: the sequences it can be dark in, and whether the gate keys mid-band.
         let mut notes: Vec<String> = Vec::new();
         let (mut any_gate, mut any_mid) = (false, false);
         for (i, d) in defs.iter().enumerate() {
@@ -55,12 +45,8 @@ pub fn ribbonscan(chain: &mut Chain) -> Result<()> {
             per.sort();
             notes.push(format!("    r{i}  {}", per.join("  ")));
         }
-        // The BLEND census beside the gate one. A ribbon takes its blend from a real M2 material
-        // (`materialIndices[0]` → render-flags `blend`), so unlike a particle emitter it can in
-        // principle author any mode — and the two the parse folds (`Opaque`, covering file modes
-        // 0/1/5/6) render with no alpha test at all, which is exactly what painted the particle
-        // side's AlphaKey debris as solid squares. Tallied here so the fold stays a MEASURED
-        // approximation instead of an assumed-empty one.
+        // A ribbon's blend is its material's (`materialIndices[0]` → render flags), so unlike a
+        // particle's it can be any mode; the tally shows what the parse folds each raw mode to.
         for d in &defs {
             let raw = d.blend_mode.map_or("?".into(), |m| m.to_string());
             *blends
@@ -89,9 +75,7 @@ pub fn ribbonscan(chain: &mut Chain) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (under `prefix`, if given) and list the models whose particle emitters
-/// carry any bit of `mask` in their file flags — see the `Partscan` command doc. One line per
-/// matching emitter: its index, full flag word, shape/type, and the model path.
+/// List the particle emitters whose file flags carry any bit of `mask`.
 pub fn partscan(chain: &mut Chain, mask: u32, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut hits, mut emitters) = (0u32, 0u32, 0u32);
@@ -130,11 +114,9 @@ pub fn partscan(chain: &mut Chain, mask: u32, prefix: Option<&str>) -> Result<()
     Ok(())
 }
 
-/// The census's raw-extras view of one on-disk emitter record: the fields the shipped
-/// [`benilla_formats::ParticleEmitterDef`] deliberately does not carry (yet). Read straight off
-/// the record bytes (stride/header per the parser's module doc): the two model-filename M2Arrays
-/// at `+0x18` (geometry model — 3-D "model particles") and `+0x20` (recursion model — per-particle
-/// child emitters), and the emission-rate track's interpolation word (`+0xdc`, 0 = step).
+/// Raw fields of one emitter record (stride `0x1f8`): the geometry-model (`+0x18`) and
+/// recursion-model (`+0x20`) path `M2Array`s, and the emission-rate track's interpolation word
+/// (`+0xdc`, 0 = step) and key count.
 struct RecordExtras {
     geometry_model: Option<String>,
     recursion_model: Option<String>,
@@ -142,7 +124,6 @@ struct RecordExtras {
     rate_keys: u32,
 }
 
-/// Read the raw extras for every emitter record in an M2 (empty if not an MD20 or no emitters).
 fn record_extras(bytes: &[u8]) -> Vec<RecordExtras> {
     const STRIDE: usize = 0x1f8;
     let u16_at = |o: usize| u16::from_le_bytes([bytes[o], bytes[o + 1]]);
@@ -215,8 +196,7 @@ fn spell_attribution(chain: &mut Chain) -> HashMap<String, Vec<(u32, String)>> {
     map
 }
 
-/// One census dimension's tally. `model_count` counts every distinct model exactly;
-/// `models` keeps the first 64 (sorted) for the example listings.
+/// One census dimension: `model_count` counts every model, `models` keeps the first 64, sorted.
 #[derive(Default)]
 struct Tally {
     emitters: u32,
@@ -239,8 +219,7 @@ impl Tally {
     }
 }
 
-/// Sweep every `.m2` (under `prefix`, if given) and census which particle-emitter FEATURES the
-/// corpus actually authors — see the `Partcensus` command doc.
+/// Census which particle-emitter features the corpus authors, with the spells behind rare ones.
 pub fn partcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let attribution = spell_attribution(chain);
     let names = super::m2_names(chain, prefix)?;
@@ -270,12 +249,8 @@ pub fn partcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 benilla_formats::ParticleShape::Sphere => hit("shape:sphere"),
                 benilla_formats::ParticleShape::Spline => hit("shape:SPLINE"),
             }
-            // ANISOTROPIC plane rectangles — the population on which the areaLength↔areaWidth axis
-            // pairing is observable at all (a SQUARE area renders identically either way). 0563 and
-            // 0566 both pre-named "a 90°-wrong ANISOTROPIC effect" as this lane's suspect, but no
-            // instrument could LIST that population, so the swapped pairing outlived both audits
-            // until Gressil's 0.1 × 1.1 blade smoke drew its curtain across the blade. Bucketed by
-            // aspect so a thin curtain (load-bearing) separates from a near-square (invisible).
+            // Anisotropic plane areas, the only ones where the areaLength/areaWidth axis pairing
+            // shows (a square renders the same either way), bucketed by aspect.
             let now = d.params.sample(None, 0.0, 0.0);
             if d.shape == benilla_formats::ParticleShape::Plane {
                 let lo = now.area_length.abs().min(now.area_width.abs());
@@ -289,10 +264,8 @@ pub fn partcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                     }
                 }
             }
-            // ANIMATED parameter channels (decision 0844): the population the value[0] flatten
-            // silently mis-rendered — Frost Nova's emission radius riding its ring out, Arcane
-            // Explosion's riding its dome. Tallied per channel so the census names WHICH knob
-            // actually moves in the corpus.
+            // Parameter channels that animate, per channel (Frost Nova's emission radius rides
+            // its ring out).
             const PARAM_KEYS: [&str; 9] = [
                 "param-anim:speed",
                 "param-anim:speedVar",
@@ -394,8 +367,8 @@ pub fn partcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 }
                 if x.rate_keys > 1 && x.rate_interp != 0 {
                     hit("rate:LERP-RAMP(interp!=0)");
-                    // A BURST emitter with a lerp rate track would arm a near-zero count at its
-                    // rising edge — if the corpus authored one, the burst edge law needs a re-look.
+                    // A burst emitter with a lerped rate would arm a near-zero count at its
+                    // rising edge.
                     if d.burst() {
                         hit("rate:BURST+LERP(suspect)");
                     }
@@ -418,8 +391,6 @@ pub fn partcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         );
     }
 
-    // The full model list — with spell attribution — for the dimensions that decide mechanism
-    // scope (the UPPERCASE keys: unimplemented or folded legs, plus the odd corners).
     let detail: &[&str] = &[
         "MODEL-PARTICLES(geometry)",
         "CHILD-EMITTERS(recursion)",
@@ -471,23 +442,11 @@ pub fn partcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` and census its particle emitters' over-life **flipbook** fields — the
-/// population instrument behind decision 0685 (the reverse-playing cell ramp).
-///
-/// One line per emitter that is interesting on any axis, then the totals. The axes are exactly the
-/// ways a flipbook reader can be wrong, each of which shipped data does exercise:
-///
-/// - `INVERTED` — a `begin > end` pair. Legal, and it means *play the sheet backwards*; a reader
-///   that clamps into `[begin, end]` mangles it (and in Rust panics outright).
-/// - `TAIL-RAMP` — the tail streak's own ramp differs from the head's, on an emitter that draws a
-///   tail. The two are independently authored (file +0x168.. vs +0x174..); handing the head's cell
-///   to the streak animates it through a sheet the author pinned to one cell.
-/// - `PAST-ATLAS` — a cell index beyond `rows·cols`. The reference masks the COLUMN and leaves the
-///   ROW unbounded, so the index wraps to row 0 rather than holding the last cell.
-/// - `REPEAT` — a per-segment repeat count ≠ 1, i.e. the sheet cycles more than once per segment.
-/// - `NON-POW2` / `MID` — the two shapes the reference itself degrades on (a 1×1 fallback, and a
-///   `mid` of 0/1 that walks its own sampler into a NaN). Both are empty in 1.12.1 and are here so
-///   that stays checkable.
+/// Census the emitters' over-life flipbook fields: `INVERTED` (`begin > end`) plays the sheet
+/// backwards, which a `clamp` into it panics on; `TAIL-RAMP`, a tail ramp (`+0x174`) unlike the
+/// head's (`+0x168`); `PAST-ATLAS`, a cell past `rows·cols`, which the reference wraps to row 0
+/// (it masks the column only); `REPEAT`, a segment repeat other than 1; `NON-POW2` and `MID`,
+/// shapes the reference degrades on (a 1×1 fallback, a NaN sampler), none in 1.12.1.
 pub fn cellscan(chain: &mut Chain) -> Result<()> {
     let names = super::m2_names(chain, None)?;
 
@@ -524,7 +483,7 @@ pub fn cellscan(chain: &mut Chain) -> Result<()> {
                     pair(&ol.head_cells[1])
                 );
             }
-            // Only a tail-drawing emitter (particleType 1/2) can show a tail-ramp difference.
+            // Only a tail-drawing emitter (particleType 1 or 2) shows a tail ramp.
             if e.head_tail >= 1 && ol.tail_cells != ol.head_cells {
                 tail_ramp += 1;
                 println!(
@@ -542,8 +501,7 @@ pub fn cellscan(chain: &mut Chain) -> Result<()> {
             let atlas = e.tile_rows * e.tile_cols;
             if ramps.iter().any(|r| r.begin >= atlas || r.end >= atlas) {
                 past_atlas += 1;
-                // On a 1×1 sheet every index resolves to the same texture, so only a real atlas
-                // can show the wrap.
+                // On a 1×1 sheet every index is the same texture: only a real atlas shows the wrap.
                 if atlas > 1 {
                     past_atlas_real += 1;
                     println!(
@@ -576,19 +534,10 @@ pub fn cellscan(chain: &mut Chain) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and list the emitters whose **file slot 0 is
-/// dead while another slot is alive** — the shape that makes a pinned-slot-0 consumer silently
-/// render nothing (decision 0760, found on `BlastedLandsLightningbolt01.m2`, B63).
-///
-/// The reference samples the **playing** sequence's rate window every frame (wow-re
-/// `part-emission-rate-animated.md` §2); a consumer that pins slot 0 instead is only correct while
-/// slot 0 carries the emitter's whole story. When an author keys the burst in a *later* variation —
-/// a lightning strike that fires on 5 % of arms, an ambient prop with a rare flourish — slot 0 is a
-/// flat zero and the pinned consumer emits nothing, for ever, on every placement. That is invisible
-/// from the outside: the emitter is built, pooled, and ticking; it just never births a particle.
-///
-/// `peak0` is slot 0's own peak rate, `peakN` the best any other slot reaches. A listed emitter has
-/// `peak0 <= 0 < peakN`. `slots` counts FILE sequence slots (the axis `EmitTiming` bakes on).
+/// List the emitters whose file slot 0 never emits while another slot does (`peak0 <= 0 <
+/// peakN`, the peak rates). The reference samples the playing sequence's rate window every frame
+/// (`0x71850d`), so a consumer pinned to slot 0 never births a particle from them. `slots` counts
+/// file sequence slots, the axis `EmitTiming` bakes on.
 pub fn partslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut with_emitters, mut emitters, mut dead0) = (0u32, 0u32, 0u32, 0u32);
@@ -654,25 +603,15 @@ pub fn partslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and census the corpus's **3-D model
-/// particles**: the emitters whose record carries a geometry-model reference (`+0x18` — a shard
-/// instance renders that GEOMETRY model's own submeshes, not a billboard quad). Per OWNER model:
-/// the owner-last draw-order rung its shards are stamped with at runtime
-/// (`owner_last_rung(m2_owner_reach(owner submeshes))`); per referenced GEOMETRY model: the
-/// material family tuples its render submeshes author — (blend, two_sided, additive,
-/// no_depth_write, no_depth_test), the exact key the shard's material is built from.
-///
-/// This is the **ground truth for the pipeline-warm menagerie's shard rows**: warming a pipeline
-/// per (rung × family) cell is only worth its table if the corpus's cells are enumerable, and this
-/// census is what enumerates them — the rung histogram sizes the rung axis, the family-tuple set
-/// (split by transparent-pass membership, the renderer's own test) sizes the material axis, and
-/// the unresolved-path count bounds what the table can never cover.
+/// Census the 3-D model particles, emitters with a geometry model (`+0x18`) whose shards draw that
+/// model's submeshes: per owner the draw-order rung its shards are stamped with
+/// (`owner_last_rung(m2_owner_reach(..))`), per geometry model the material families its shards
+/// are built from. The rung and family sets size the pipeline-warm table's shard rows.
 pub fn shardcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
 
-    // A submesh's material family: the tuple the shard material is keyed by, rendered compactly
-    // (`Blend+2s+add`), plus its transparent-pass membership — the renderer's own test, where
-    // `additive` forces the pass whatever the authored blend says (`model_material`).
+    // A submesh's material family label and whether it draws in the transparent pass, which
+    // `additive` forces whatever the blend (`model_material`).
     let fam = |s: &benilla_formats::RenderSubmesh| {
         let transparent = s.additive
             || matches!(
@@ -692,8 +631,7 @@ pub fn shardcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         (label, transparent)
     };
 
-    // Each distinct geometry model is read, parsed, and tallied exactly once; the cache keeps its
-    // (family, transparent) list per submesh for the per-pair lines. `None` = unresolvable.
+    // Each geometry model is read and tallied once; `None` marks an unresolvable path.
     let mut geo_cache: BTreeMap<String, Option<Vec<(String, bool)>>> = BTreeMap::new();
     let mut fam_transparent: BTreeMap<String, u32> = BTreeMap::new();
     let mut fam_opaque: BTreeMap<String, u32> = BTreeMap::new();
@@ -709,9 +647,8 @@ pub fn shardcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         if benilla_formats::parse_m2_particle_emitters(&bytes).is_err() {
             continue;
         }
-        // Distinct geometry references, normalized the way the chain resolves model paths
-        // (lowercase, `\` separators, `.mdx`/`.mdl` → `.m2` — `model_key` mirrors the crate's own
-        // `model_path`).
+        // Distinct geometry paths, normalized as the chain resolves them (`model_key` mirrors
+        // the crate's `model_path`).
         let geos: BTreeSet<String> = record_extras(&bytes)
             .iter()
             .filter_map(|e| e.geometry_model.as_deref())
@@ -721,8 +658,7 @@ pub fn shardcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         }
         owners += 1;
-        // The rung the owner's shards are stamped with: the renderer's own bound and rung, at
-        // placement scale 1 (a scaled placement multiplies the reach).
+        // The owner's rung at placement scale 1; a scaled placement multiplies the reach.
         let dir = name.rsplit_once('\\').map_or("", |(d, _)| d);
         let owner_subs =
             benilla_formats::parse_m2_render_submeshes(&bytes, dir, &[]).unwrap_or_default();
@@ -810,19 +746,12 @@ pub fn shardcensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and count, per model, the two halves of the
-/// **owner-last draw-order** law: the EFFECTS a model authors (particle emitters + ribbon trails)
-/// and the TRANSPARENT-pass batches of its own body those effects must draw after (decisions
-/// 0719/0721). A model with both is one the rung actually changes; a model with effects and no
-/// transparent batch of its own never had the defect and is listed only in the totals.
-///
-/// This is the population instrument the two decisions were argued from. "Does this fix anything
-/// besides the voidwalker's eyes?" is not a question to answer by naming plausible creatures —
-/// it is a count, and the count is what says whether the mechanism closes a class or a case.
+/// Count per model the two halves of the owner-last draw order: the effects it authors (particle
+/// emitters and ribbons) and its own transparent-pass batches they must draw after. Only a model
+/// with both is changed by the rung, and only those are listed.
 pub fn fxordercensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
-    // Per top-level content family (Creature / Item / Spells / World / …), so the totals say
-    // WHERE the class lives rather than only how big it is.
+    // Top-level directory → (models with effects, of those at risk).
     let mut family: BTreeMap<String, (u32, u32)> = BTreeMap::new();
     let (mut scanned, mut with_fx, mut at_risk) = (0u32, 0u32, 0u32);
     let mut rungs: BTreeMap<u32, u32> = BTreeMap::new();
@@ -839,9 +768,8 @@ pub fn fxordercensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         }
         with_fx += 1;
-        // The occluders: batches the renderer puts in the one distance-sorted transparent list.
-        // `additive` forces that pass whatever the authored blend says (`model_material`), so the
-        // test mirrors the renderer's rather than reading the blend word alone.
+        // Batches in the distance-sorted transparent pass, which `additive` forces whatever the
+        // blend (`model_material`).
         let dir = name.rsplit_once('\\').map_or("", |(d, _)| d);
         let subs = benilla_formats::parse_m2_render_submeshes(&bytes, dir, &[]).unwrap_or_default();
         let occluders: Vec<&benilla_formats::RenderSubmesh> = subs
@@ -857,7 +785,6 @@ pub fn fxordercensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             })
             .collect();
         let transparent = occluders.len();
-        // The renderer's own bound and the renderer's own rung — not a re-derivation of them.
         let reach = benilla_formats::m2_owner_reach(&subs);
         let fam = name.split('\\').next().unwrap_or("?").to_string();
         family.entry(fam).or_default().0 += 1;
@@ -869,7 +796,7 @@ pub fn fxordercensus(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             .entry(name.split('\\').next().unwrap_or("?").to_string())
             .or_default()
             .1 += 1;
-        // At placement scale 1 — the survey number; a scaled placement multiplies the reach.
+        // At placement scale 1; a scaled placement multiplies the reach.
         let rung = benilla_formats::owner_last_rung(reach);
         *rungs.entry(rung as u32).or_default() += 1;
         println!(
diff --git a/crates/benilla-formats/src/bin/benilla-extract/scan/sequence.rs b/crates/benilla-formats/src/bin/benilla-extract/scan/sequence.rs
index 37323c36..727c227b 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/scan/sequence.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/scan/sequence.rs
@@ -1,13 +1,5 @@
-//! Corpus scans over **which sequence is playing** — the animation-arm side, where being on the
-//! wrong sequence (or on none at all) silently mis-renders everything keyed to it.
-//!
-//! The GameObject substate arm (`goanimscan`), the effect-model Stand/Hold/Decay lifecycle
-//! (`fxlifescan`), the loader-idle slot the per-sequence bakes degrade away from (`idleslotscan`),
-//! and the models with no keyed bone at all, so no clock ever advances (`seqclockscan`).
-//!
-//! Plus the arm's *reach*: which models author a sound-event marker the rig gate never arms
-//! (`soundeventscan`) — the same failure one level down, where the sequence is right and nothing
-//! runs its clock.
+//! Corpus scans over which sequence is playing: GameObject substates, the effect-model lifecycle,
+//! the idle slot, clockless models, and the markers a sequence carries.
 
 use std::collections::{BTreeMap, HashSet};
 
@@ -16,10 +8,9 @@ use benilla_formats::Chain;
 
 use crate::model_key;
 
-/// The GameObject animation arm's LUT (wow-re `gameobject-anim-arm.md` §2c, `.data 0x8607e4`):
-/// internal **substate** → the `AnimationData.dbc` id the object layer arms.
+/// The GameObject arm's LUT (`.data 0x8607e4`): internal substate → the `AnimationData.dbc` id.
 const SUBSTATE_ANIM: [u16; 13] = [
-    145, // 0  Spawn      — NO client path produces this substate (§2c census)
+    145, // 0  Spawn      (one-shot on create, `0x5f382f` → `0x5f8c50`)
     147, // 1  Closed     (rest)
     148, // 2  Open       (motion)
     149, // 3  Opened     (rest)
@@ -27,17 +18,16 @@ const SUBSTATE_ANIM: [u16; 13] = [
     150, // 5  Destroy    (motion)
     151, // 6  Destroyed  (rest)
     152, // 7  Rebuild    (motion)
-    153, 154, 155, 156, // 8..11 Custom0-3 — reachable only via SMSG_GAMEOBJECT_CUSTOM_ANIM
+    153, 154, 155, 156, // 8..11 Custom0-3 (one-shots through `0x5f8c50`)
     157, // 12 Despawn
 ];
 
-/// The **transient** (transition-motion) substates among the reachable ones — the rows slot 14
-/// `0x5f4120` advances off at the arm's window end (§2d: 2 Open → 3 Opened, 4 Close → 1 Closed,
-/// 5 Destroy → 6 Destroyed). Their duration is the object layer's, never the clip's loop bit.
+/// The transition substates, which slot 14 (`0x5f4120`) advances at the arm's window end
+/// (2 Open → 3 Opened, 4 Close → 1 Closed, 5 Destroy → 6 Destroyed), whatever the clip's loop bit.
 const MOTION_SUBSTATES: [usize; 3] = [2, 4, 5];
 
-/// The six substates a `GAMEOBJECT_STATE` × `GAMEOBJECT_ANIMPROGRESS` pair can actually produce
-/// (§2b). Substate 0 (Spawn) has no producer at all, and 8..12 come from other opcodes entirely.
+/// The six substates a `GAMEOBJECT_STATE` × `GAMEOBJECT_ANIMPROGRESS` pair produces (`0x5f3c30`);
+/// Spawn (0), Custom0-3 (8..11) and Despawn (12) come from the one-shot channel `0x5f8c50`.
 const REACHABLE: [(usize, &str); 6] = [
     (1, "READY  settled"),
     (4, "READY  mid    "),
@@ -47,9 +37,8 @@ const REACHABLE: [(usize, &str); 6] = [
     (5, "ALT    mid    "),
 ];
 
-/// The §2c four-way remap: what the arm actually requests when the model doesn't author the
-/// substate's LUT id. Returns `(id, rate0)` — `rate0` marks the two legs that freeze a *motion*
-/// clip at frame 0 to stand in for a missing *rest* pose.
+/// The four-way remap (`0x5f3972`) for a model that lacks the substate's LUT id, as `(id, rate0)`:
+/// `rate0` marks the two legs that freeze a motion clip at frame 0 in place of a missing rest pose.
 fn go_remap(m: &benilla_m2::M2Model, id: u16) -> (u16, bool) {
     if m.owns_animation(id) {
         return (id, false);
@@ -76,14 +65,13 @@ fn go_remap(m: &benilla_m2::M2Model, id: u16) -> (u16, bool) {
         149 if m.owns_animation(148) => (149, false),
         149 if m.owns_animation(146) => (146, true),
         149 => (151, false),
-        // Outside the door group there is no remap — the id goes to op4 as-is.
+        // Outside the door group the id goes to op4 as is.
         other => (other, false),
     }
 }
 
-/// op4's own id → played sequence resolve (`0x7121a0` via `0x711bf0`): the model's
-/// `playableAnimationLookup` row (when the id is in range), then `animationLookup` to a file slot.
-/// `None` when nothing playable comes out — the reference arms nothing and the pose simply stands.
+/// op4's id resolve (`0x7121a0` via `0x711bf0`): `playableAnimationLookup` when the id is in
+/// range, then `animationLookup` to a file slot. With no slot the reference arms nothing.
 fn go_resolve_slot(m: &benilla_m2::M2Model, id: u16) -> Option<(u16, u16)> {
     let played = m
         .playable_animation_lookup
@@ -93,9 +81,8 @@ fn go_resolve_slot(m: &benilla_m2::M2Model, id: u16) -> Option<(u16, u16)> {
     (slot != 0xffff).then_some((played, slot))
 }
 
-/// The generic loader seed (§1, `0x71019b`): resolve id 0, and arm **id 0** when the model owns what
-/// that resolves to — only the degenerate leg (owning nothing reachable) falls back to the raw
-/// `animations[0]` dword.
+/// The loader seed (`0x71019b`): id 0 when the model owns what id 0 resolves to, else the
+/// file-order-first sequence's own id (`animations[0]`).
 fn go_loader_seed(
     m: &benilla_m2::M2Model,
     seqs: &[benilla_formats::ModelAnimation],
@@ -107,18 +94,16 @@ fn go_loader_seed(
     if m.owns_animation(resolved) {
         go_resolve_slot(m, 0)
     } else {
-        // The degenerate leg: `animations[0]`'s low16 — the file-order-first sequence's own id.
         go_resolve_slot(m, seqs.first()?.anim_id)
     }
 }
 
-/// Sweep every model named by **GameObjectDisplayInfo.dbc** and resolve, per model, what the
-/// reference's GameObject animation arm plays in each reachable `GAMEOBJECT_STATE` ×
-/// `GAMEOBJECT_ANIMPROGRESS` substate — see the `Goanimscan` command doc.
+/// Resolve, for every `GameObjectDisplayInfo` model, what the reference's GameObject arm plays in
+/// each state substate, printing the models where that differs from the loader seed.
 pub fn goanimscan(chain: &mut Chain) -> Result<()> {
     let catalog =
         benilla_formats::load_gameobject_catalog(chain).context("GameObjectDisplayInfo.dbc")?;
-    // displayId → path, deduped to one entry per model (many displays share a model).
+    // Model path → its display ids; many displays share a model.
     let mut models: BTreeMap<String, Vec<u32>> = BTreeMap::new();
     for (id, path) in catalog.iter() {
         let key = model_key(path);
@@ -131,17 +116,12 @@ pub fn goanimscan(chain: &mut Chain) -> Result<()> {
     }
     let (mut parsed, mut no_seq, mut blind, mut sensitive, mut needs_remap, mut rate0) =
         (0u32, 0u32, 0u32, 0u32, 0u32, 0u32);
-    // The transition half (decision 1151): a MOTION substate whose resolved sequence is bit-0-clear
-    // is one the kernel wraps for ever — so it is bounded only by the object layer's §2d completion
-    // advance, and a consumer that arms it by the loop bit instead flaps. And `replay` decides
-    // whether that window is one band or several.
+    // A motion substate on a looping sequence (flags bit 0 clear) wraps until the completion
+    // advance (`0x5f4120`) ends it; the replay range sets how many bands that window spans.
     let (mut looping_motion, mut looping_motion_sensitive, mut multi_replay) = (0u32, 0u32, 0u32);
-    // The VARIATION half (wow-re `gameobject-anim-arm.md` §2c, `0x5f3aee: push -1`): the GameObject
-    // arm rolls a `_rand`-weighted variation, while the §1 loader seed underneath it takes an
-    // explicit variation 0. So a model that authors a CHAIN on a reachable substate's id plays
-    // something the seed never reaches — and a consumer resolving the id to its head variation
-    // renders the whole rest of the chain unreachable. Onyxia's lava traps are the case
-    // (`ONYZIASLAIRLAVATRAP`: Stand ×2, and only the 10 %-weighted second one spurts lava).
+    // The arm rolls a weighted variation (`0x5f3aee` pushes -1) where the loader seed takes
+    // variation 0 (`0x71019b`), so a chain on a substate's id reaches sequences the seed cannot
+    // (`ONYZIASLAIRLAVATRAP`: two Stands, only the 10%-weighted second spurts lava).
     let mut chained = 0u32;
     let mut chained_paths: Vec<String> = Vec::new();
     for (path, displays) in &models {
@@ -170,16 +150,12 @@ pub fn goanimscan(chain: &mut Chain) -> Result<()> {
             remapped |= req != lut;
             froze |= r0;
             differs |= armed.map(|(_, s)| s) != seed.map(|(_, s)| s);
-            // The played sequence's own kernel law. `slot` is the M2's FILE slot, which is not this
-            // list's index (zero-duration sequences are dropped), so match on `seq_index`.
+            // `slot` is a file slot, not an index here (zero-duration sequences are dropped).
             let played =
                 armed.and_then(|(_, slot)| seqs.iter().find(|s| s.seq_index == slot as usize));
-            // A transient substate (a transition motion) armed on a band the kernel wraps: what
-            // ends it is §2d, never the clip.
             let motion = MOTION_SUBSTATES.contains(&sub);
             flaps |= motion && !r0 && played.is_some_and(|s| s.looping);
             replays |= played.is_some_and(|s| (s.min_replay, s.max_replay) != (0, 0));
-            // A variation chain on THIS substate's armed id: >1 sequence sharing it.
             let variations =
                 armed.map_or(0, |(id, _)| seqs.iter().filter(|s| s.anim_id == id).count());
             has_chain |= variations > 1;
@@ -229,8 +205,7 @@ pub fn goanimscan(chain: &mut Chain) -> Result<()> {
         }
         remapped.then(|| needs_remap += 1);
         froze.then(|| rate0 += 1);
-        // Only the state-SENSITIVE models are worth printing: on every other one the arm lands on
-        // the same sequence the loader seed already holds, so `GAMEOBJECT_STATE` is unobservable.
+        // Print only state-sensitive models; on the rest every substate plays the seed's sequence.
         if differs {
             println!("{path}  ({} sequences, displays {displays:?})", seqs.len());
             println!(
@@ -257,7 +232,7 @@ pub fn goanimscan(chain: &mut Chain) -> Result<()> {
         "  STATE-SENSITIVE {sensitive}  — at least one substate plays something else: exactly the \
          models a GO type that skips the arm renders in the wrong pose"
     );
-    println!("  needing the §2c remap on some substate: {needs_remap}");
+    println!("  needing the four-way remap on some substate: {needs_remap}");
     println!(
         "  authoring a VARIATION CHAIN on a reachable substate: {chained}  — the models the arm's \
          `variationIdx = -1` roll can reach and the loader seed's explicit variation 0 cannot"
@@ -268,7 +243,7 @@ pub fn goanimscan(chain: &mut Chain) -> Result<()> {
     println!(
         "  arming a LOOPING band on a transition (motion) substate: {looping_motion} \
          ({looping_motion_sensitive} of them state-SENSITIVE, i.e. the transition is a clip the \
-         rest pose isn't)  — the §2d completion advance is the only thing that ends these; read \
+         rest pose isn't)  — the completion advance is the only thing that ends these; read \
          as \"should this clip repeat?\" they swing for ever (decision 1151)"
     );
     println!(
@@ -279,33 +254,16 @@ pub fn goanimscan(chain: &mut Chain) -> Result<()> {
     Ok(())
 }
 
-/// `AnimationData.dbc` ids of the effect-model lifecycle triple (names read from the real DBC).
+/// `AnimationData.dbc` ids of the effect-model lifecycle: Stand, Hold, Decay.
 const ANIM_STAND: u16 = 0;
 const ANIM_HOLD: u16 = 158;
 const ANIM_DECAY: u16 = 159;
 
-/// Sweep every `.m2` (optionally under a path prefix) and census the **effect-model animation
-/// lifecycle**: which models author the `Stand`(0) → `Hold`(158) → `Decay`(159) triple, and what a
-/// consumer that arms ONE sequence and never advances would render for each.
-///
-/// The reference arms an effect instance's default track — `animationLookup[0]`, i.e. `Stand` — and
-/// a model that also owns `Hold` authors `Stand` as a **birth** (grow-in, clamp flag set) with the
-/// sustained pulse living in the separate looping `Hold` sequence, and the fade-out in `Decay`.
-/// A one-sequence consumer therefore FREEZES on the last frame of the birth for the effect's whole
-/// life — no pulse, no fade — which is exactly what "the Ice Barrier shield is frozen" looks like.
-///
-/// The classification is that failure, made countable:
-/// - **FREEZE** — owns `Hold`, and the armed `Stand` clamps: the reference pulses, we hold a pose.
-/// - **hold-loops** — owns `Hold` but `Stand` itself loops: still wrong (the wrong clip), but moving.
-/// - **decay-only** — owns `Decay` and no `Hold`: only the reap leg is unrendered.
-///
-/// It also counts the **file-order divergence**: the reference arms `animationLookup[0]`, so a
-/// consumer that arms the file's *first slot* instead is additionally wrong on any model whose slot
-/// 0 is not its `Stand` (the `DuelingFlag.m2` Spawn/Stand/Despawn shape, decision 0637). The two
-/// bugs are independent and the closing line separates them.
-///
-/// The population instrument for the mechanism, so it is closed corpus-wide rather than spell by
-/// spell; `m2seq` then explains one model in full.
+/// Census the effect models with a `Hold` (158) or `Decay` (159) leg. The reference arms
+/// `animationLookup[0]`, `Stand`, which beside a `Hold` is a clamped birth before the looping
+/// pulse, so a consumer that never advances freezes on its last frame (`FREEZE`); `hold-loops`
+/// has a looping `Stand`, `decay-only` no `Hold`. It also lists the models whose file slot 0 is
+/// not `Stand` (`DuelingFlag.m2`: Spawn, Stand, Despawn), where arming slot 0 is wrong outright.
 pub fn fxlifescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut freeze, mut hold_loops, mut decay_only) = (0u32, 0u32, 0u32, 0u32);
@@ -321,13 +279,12 @@ pub fn fxlifescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         if seqs.is_empty() {
             continue;
         }
-        // What the reference arms: `animationLookup[0]` — Stand — never the file-order-first slot
-        // (they diverge on any model whose sequence 0 is not its Stand).
+        // The reference arms `animationLookup[0]`, Stand, not file slot 0.
         let armed = seqs.iter().find(|s| s.anim_id == ANIM_STAND);
         let hold = seqs.iter().find(|s| s.anim_id == ANIM_HOLD);
         let decay = seqs.iter().find(|s| s.anim_id == ANIM_DECAY);
         if hold.is_none() && decay.is_none() {
-            continue; // neither leg authored — no lifecycle to miss
+            continue; // no lifecycle leg authored
         }
         let class = match (hold.is_some(), armed) {
             (true, Some(a)) if !a.looping => {
@@ -343,8 +300,6 @@ pub fn fxlifescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 "decay-only"
             }
         };
-        // The file-order divergence, independent of the lifecycle bug: what a slot-0 consumer arms
-        // versus the reference's `animationLookup[0]`.
         let arm = match (armed, seqs[0].anim_id) {
             (None, first) => {
                 no_stand += 1;
@@ -388,8 +343,6 @@ pub fn fxlifescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         "of those, the file-order divergence (a slot-0 consumer arms the wrong sequence outright): \
          {slot0_not_stand} with slot 0 != Stand, {no_stand} with no Stand at all"
     );
-    // Named in full, never left to the row cap: this set is small and each member is a distinct
-    // "arms the wrong sequence from frame one" case.
     for (name, _, arm, ..) in rows.iter().filter(|r| r.2 != "slot0") {
         println!("  {name:<58}  {arm}");
     }
@@ -400,20 +353,10 @@ pub fn fxlifescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and list the models where the **loader-idle
-/// sequence is not file slot 0** while benilla's render content gate declines to arm it — so every
-/// per-sequence bake (`EmitTiming`/`EmitParams`/`AlphaAnim`) degrades to slot 0, a sequence the
-/// instance is not playing (decision 0936, found on the Stormwind battlefield banner).
-///
-/// The reference arms the loader-idle sequence on **every** M2 instance at load (`0x70ebd0`'s tail,
-/// wow-re `gameobject-anim-arm.md` §1), so "which sequence is this playing" always has an answer.
-/// benilla skips the arm when looping the idle would render identically to the static mesh — sound
-/// for the *mesh*, and silently wrong for anything keyed on the sequence *identity*. The two only
-/// disagree visibly when the idle is not slot 0, which is the `DuelingFlag` shape:
-/// `Spawn(145) / Stand(0) / Despawn(157)`, where slot 0 is the **Spawn flourish**.
-///
-/// Reports, per model: the emitters whose enabled/rate gate at t = 0 differs between slot 0 and the
-/// idle slot (`FX`), and the batches whose combined material-alpha factor differs (`ALPHA`).
+/// List the models whose loader-idle sequence is not file slot 0 and is a rest pose the content
+/// gate leaves unarmed, with the emitters (`FX`) and batches (`ALPHA`) that differ at t = 0
+/// between the two slots. The reference arms the idle on every instance at load (`0x70ebd0`'s
+/// tail), so a per-sequence bake follows it, never slot 0 (`DuelingFlag.m2`'s slot 0 is Spawn).
 pub fn idleslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut unarmed, mut window) = (0u32, 0u32, 0u32);
@@ -431,8 +374,7 @@ pub fn idleslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             .unwrap_or_default()
             .first()
             .map_or(0, |p| p.resolved_id);
-        // benilla's render content gate (`benilla_assets`' `idle_pose_differs`): a bind-pose idle
-        // is not armed at all, so nothing ever overrides the per-sequence bakes' opening slot.
+        // The content gate (`benilla_assets`' `idle_pose_differs`) arms no rig for a rest pose.
         if anims
             .iter()
             .any(|a| a.anim_id == idle_id && !a.is_rest_pose())
@@ -445,7 +387,7 @@ pub fn idleslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             .find(|a| a.anim_id == idle_id)
             .map_or(0, |a| a.seq_index);
         if idle == 0 {
-            continue; // degrading to slot 0 happens to BE the idle slot — no divergence
+            continue; // the idle is slot 0: nothing differs
         }
         window += 1;
         let mut lines = Vec::new();
@@ -496,30 +438,12 @@ pub fn idleslotscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and list the models whose animation is
-/// authored **entirely outside the bone tracks** — sequences exist, per-sequence consumers exist
-/// (particle emitters, ribbons, material alpha/colour, UV transforms), and **not one sequence
-/// keys a bone**.
-///
-/// That combination is the blind spot of a renderer whose sequence clock rides a *bone* animation
-/// clip: with no keyed bone there is no clip, so there is no player, so nothing ever says which
-/// sequence is playing or how far into it — and every per-sequence consumer degrades to "file slot
-/// 0, at t = 0", permanently. The emitters still build, pool and tick; they just read the wrong
-/// column of a table that never advances. Found on the Molten Core rune + flame ring (decision
-/// 0941): the rune's slot 0 is its *Closed* band, where every emission rate key is 0 (no flames at
-/// all), and the ring's spline spawn-window opens `0 → 1` over its first second, so frozen at t=0
-/// all 180 particles are born at one point of a 2.8-yd circle — one bright blob.
-///
-/// The `[GO]` mark is the cross-tab that matters: a `GameObjectDisplayInfo` model reaches the
-/// world through the **hosted** clock (`EmitClock::Host`), which is the lane that freezes at
-/// `t = 0`. A placed doodad of the same shape still runs its spawn-age clock (only its *slot* is
-/// pinned — decision 0760's axis), so it is wrong in a different, milder way.
-///
-/// PARTIAL models — some sequences key bones, some don't — are tallied, not listed: there the
-/// clock exists, but the unkeyed sequences are unreachable (no clip to arm), so a GameObject
-/// substate or a creature animation id that resolves to one plays nothing.
+/// List the models whose sequences drive per-sequence consumers (emitters, ribbons, material
+/// alpha and colour, UV transforms) while no sequence keys a bone, so their sequence clock cannot
+/// hang on bone curves. `[GO]` marks a `GameObjectDisplayInfo` model, whose emitters run on the
+/// host's clock (`EmitClock::Host`); models where only some sequences key a bone are `PARTIAL`.
 pub fn seqclockscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
-    // Which models a GameObject can display — the hosted-clock lane.
+    // The models a GameObject can display, whose emitters run on the host's clock.
     let go_models: HashSet<String> = benilla_formats::load_gameobject_catalog(chain)
         .map(|c| c.iter().map(|(_, p)| model_key(p)).collect())
         .unwrap_or_default();
@@ -537,8 +461,7 @@ pub fn seqclockscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         }
         with_seqs += 1;
-        // Exactly the runtime's own test (`build_animation_clip`): a sequence becomes a clip iff
-        // some bone track produced a key inside its band.
+        // Whether a sequence poses a bone, as `build_animation_clip`'s flag decides it.
         let keyed = seqs
             .iter()
             .filter(|a| {
@@ -547,17 +470,15 @@ pub fn seqclockscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 })
             })
             .count();
-        // Counted over EVERY model with sequences, consumers or not: it measures clip
-        // REACHABILITY (can an arm find this sequence at all), which is a property of the model.
+        // Counted over every model with sequences, consumers or not.
         if keyed > 0 && keyed < seqs.len() {
             partial += 1;
         }
         let Ok(s) = benilla_formats::parse_m2_animation_summary(&bytes) else {
             continue;
         };
-        // The per-sequence consumers: everything that samples a track on the playing sequence's
-        // clock. A constant (≤1 key) colour/alpha track is excluded — it reads the same in every
-        // slot, so a frozen clock costs it nothing.
+        // Everything that samples a track on the playing sequence's clock; a constant (≤1 key)
+        // colour or alpha track reads the same in every slot and is left out.
         let consumers = s.particle_emitter_count
             + s.ribbon_emitter_count
             + s.color_alpha_tracks.1
@@ -565,9 +486,7 @@ pub fn seqclockscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             + s.transparency_tracks.1
             + s.texture_transform_count;
         if keyed == 0 && consumers == 0 {
-            // The same shape with nothing to sample: a clock costs it nothing and buys it
-            // nothing. Counted because it IS the cost side of giving every sequenced model a
-            // clock — these are the models that gain an inert one.
+            // No keyed bone and nothing to sample: a clock here is inert.
             inert += 1;
         }
         if consumers > 0 && keyed == 0 {
@@ -602,25 +521,11 @@ pub fn seqclockscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` and census the **animation-driven sound emitters**: the models whose
-/// sequences carry a `$DSL` (doodad sound loop) / `$DSE` (its release token) / `$DSO` (doodad
-/// sound one-shot) / `$SND` (generic one-shot) event marker, the `SoundEntries` kit each names,
-/// and — the column this exists for — whether the carrying sequence is **rest-posed**.
-///
-/// `$DSE` is in the set because it is half of `$DSL`'s lifecycle and it is **lane-specific**: the
-/// placed-doodad handler `0x6951e0` has an arm for it, the GameObject dispatcher `0x5f3e20` has
-/// none at all (wow-re `doodad-sound-emitters.md` §13), so which models author it decides whether
-/// a consumer may route the token uniformly.
-///
-/// Why that column decides everything: `benilla_assets`' render content gate
-/// (`idle_pose_differs` → [`benilla_formats::ModelAnimation::is_rest_pose`], decision 0130) skips
-/// building a rig for a sequence that would render as the static mesh, and the whole point of
-/// that gate is that it is a question **about pixels only**. A placed lamp's Stand band keys no
-/// bone at all — it is pure rest pose — yet it carries the one `$DSL` marker that is its hum. So
-/// every model in the `REST` column is one whose sound the arm can never reach through a rig: its
-/// events need a clock that does not depend on there being anything to animate.
-///
-/// Reports the per-model rows, then a tag/kit histogram and the `REST`-gated share.
+/// Census the `$DSL` (loop), `$DSE` (its release), `$DSO` and `$SND` (one-shots) markers per model,
+/// the `SoundEntries` kit each names, and whether the carrying sequence is a rest pose (`REST`),
+/// which gets no rig ([`benilla_formats::ModelAnimation::is_rest_pose`]), so only a rig-free clock
+/// reaches its marker (a lamp's Stand keys no bone yet carries its `$DSL` hum). `$DSE` has an arm
+/// in the placed-doodad handler `0x6951e0` and none in the GameObject dispatcher `0x5f3e20`.
 pub fn soundeventscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     const SOUND_TAGS: [&[u8; 4]; 4] = [b"$DSL", b"$DSE", b"$DSO", b"$SND"];
     let kits = benilla_formats::load_sound_kit_catalog(chain).ok();
@@ -638,14 +543,9 @@ pub fn soundeventscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         }
         scanned += 1;
-        // The spawn tier `benilla_world::doodad_anim::classify` would give this model, from the
-        // same three inputs it reads: a boneless model is `Static` outright (the 0035 guard);
-        // otherwise the 0130 content gate picks `FirstSeq` when the loader-idle clip's pose
-        // differs from bind, else `GlobalSeqOnly` when free-running channels exist, else
-        // `Static`. `is_rest_pose` is the gate's own predicate (decision 0936 pushed it down
-        // beside the parse so this census cannot drift from it); the tier matters here because
-        // only the two animated tiers get an anim-root ENTITY at all — a `Static` carrier has
-        // nothing but loose submeshes to hang an emitter on.
+        // The spawn tier `benilla_world::doodad_anim::classify` gives this model: `Static` when
+        // boneless, else `FirstSeq` when the idle is not a rest pose, else `GlobalSeqOnly` with
+        // global-sequence channels, else `Static`.
         let bones = benilla_m2::parse_m2(&mut std::io::Cursor::new(&bytes))
             .map_or(0, |f| f.model().bones.len());
         let idle_id = benilla_formats::parse_m2_playable_animation_lookup(&bytes)
@@ -676,8 +576,7 @@ pub fn soundeventscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             if marks.is_empty() {
                 continue;
             }
-            // The gate is asked of the sequence that CARRIES the marker: that is the one whose
-            // clock has to run for the marker to be reached at all.
+            // Asked of the sequence that carries the marker: its clock must run to reach it.
             let rest = a.is_rest_pose();
             model_rest_gated |= rest;
             for e in &marks {
@@ -751,15 +650,14 @@ pub fn soundeventscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// The ten `GameObjectDisplayInfo.Sound[n]` slots, in column order — the names the reference's
-/// own substate family gives them (`gameobject-anim-arm.md` §2c's LUT order).
+/// The sound-slot names of the ten `GameObjectDisplayInfo.Sound[n]` columns, in column order.
 const GO_SLOT_NAMES: [&str; 10] = [
     "Stand", "Open", "Loop", "Close", "Destroy", "Opened", "Custom0", "Custom1", "Custom2",
     "Custom3",
 ];
 
-/// The event tag that reaches each display slot (wow-re `go-display-sound-events.md` §3, the
-/// dispatcher `0x5f3e20`'s ten call sites): `$GO0..5` → slots 0..5, `$GC0..3` → slots 6..9.
+/// The event tag that plays each display slot through `0x5f3e20`: `$GO0..5` → slots 0..5,
+/// `$GC0..3` → slots 6..9.
 fn go_slot_tag(slot: usize) -> [u8; 4] {
     if slot < 6 {
         [b'$', b'G', b'O', b'0' + slot as u8]
@@ -768,13 +666,11 @@ fn go_slot_tag(slot: usize) -> [u8; 4] {
     }
 }
 
-/// The model sequence **file slots** the GameObject arm can ever put on screen: the loader seed
-/// (§1) plus every substate any client path produces — the six `GAMEOBJECT_STATE` ×
-/// `GAMEOBJECT_ANIMPROGRESS` ones ([`REACHABLE`]), the four Custom ones (opcode `0xb3`) and
-/// Despawn (`0x215`) — each through the §2c remap and op4's `playableAnimationLookup` resolve.
-///
-/// This is the reachability half of [`goslotscan`]: an authored `$GOn` on a sequence outside this
-/// set is a marker no arm can ever cross, so its display slot is dead however the DBC is filled.
+/// The file slots the GameObject arm can put on screen: the loader seed (`0x71019b`), the six
+/// state substates through the four-way remap (`0x5f3972`), and the Custom0-3 (opcode `0xb3`) and
+/// Despawn (`0x215`) one-shots, resolved through `playableAnimationLookup`. Spawn, which the
+/// create path arms (`0x5f382f`), is left out, so a marker only its sequence carries reads as
+/// unarmable.
 fn go_armable_slots(
     m: &benilla_m2::M2Model,
     seqs: &[benilla_formats::ModelAnimation],
@@ -789,15 +685,15 @@ fn go_armable_slots(
     out
 }
 
-/// Census the **GameObject display sound slots** against the model events that are the only thing
-/// that can reach them — see the `Goslotscan` command doc for what the join proves.
+/// Census the GameObject display sound slots against the `$GOn`/`$GCn` model events, the only
+/// path that plays them (`0x5f4010`, called from `0x5f3e20` alone).
 pub fn goslotscan(chain: &mut Chain) -> Result<()> {
     let catalog =
         benilla_formats::load_gameobject_catalog(chain).context("GameObjectDisplayInfo.dbc")?;
     let sounds =
         benilla_formats::load_gameobject_sounds(chain).context("GameObjectDisplayInfo.dbc")?;
     let kits = benilla_formats::load_sound_kit_catalog(chain).ok();
-    // displayId → model path, so the same model parsed once serves every display that names it.
+    // Model path → the displays that name it, so each model is parsed once.
     let mut per_model: BTreeMap<String, Vec<u32>> = BTreeMap::new();
     for (id, path) in catalog.iter() {
         if sounds.slots(id).is_some() {
@@ -807,18 +703,16 @@ pub fn goslotscan(chain: &mut Chain) -> Result<()> {
     for ids in per_model.values_mut() {
         ids.sort_unstable();
     }
-    // Per slot: displays carrying a kit · of those, models authoring the tag · of those, on an
-    // armable sequence · and how many of the live ones name a LOOPING (0x200) kit — the lane
-    // select `0x458830` hands `0x5f4010`, which is the emitter-pool arm rather than a one-shot.
+    // Per slot: displays with a kit, of those with the tag authored, of those on an armable
+    // sequence, and the live ones whose kit loops (flag 0x200), which `0x5f4010` plays through
+    // the emitter pool (`0x461d80`) rather than as a one-shot.
     let mut filled = [0u32; 10];
     let mut tagged = [0u32; 10];
     let mut reachable = [0u32; 10];
     let mut looping = [0u32; 10];
-    // Filled columns whose model authors no reaching tag at all — dead data in the reference, and
-    // exactly what a state-transition-driven consumer would play that the reference never does.
+    // Filled columns whose model authors no reaching tag: dead data the reference never plays.
     let mut dead = [0u32; 10];
-    // Markers authored where the display's column is 0 — the tag fires and `0x458830` fails a null
-    // id, so the reference is silent. Counted per tag so "authored but silent" is visible.
+    // Tags authored where the column is 0: the tag fires and `0x458830` fails on the null id.
     let mut silent_tag = [0u32; 10];
     let mut unarmable_tag = [0u32; 10];
     let (mut models_seen, mut wmo_or_missing) = (0u32, 0u32);
diff --git a/crates/benilla-formats/src/bin/benilla-extract/scan/skeleton.rs b/crates/benilla-formats/src/bin/benilla-extract/scan/skeleton.rs
index c1a5baf1..2cf4e4ca 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/scan/skeleton.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/scan/skeleton.rs
@@ -1,8 +1,4 @@
-//! Corpus scans over the **bone tree and what addresses it** — the skeleton's own tracks, and
-//! the attachment table things hang off.
-//!
-//! `bonescan` measures our skeletal parse against the reference's sampler band by band;
-//! `attachscan` censuses where a table scan disagrees with the reference's `attachLookup`.
+//! Corpus scans over the bone tree and what addresses it: bone tracks, attachments, event markers.
 
 use std::collections::{BTreeMap, BTreeSet};
 
@@ -11,15 +7,9 @@ use benilla_formats::Chain;
 
 use crate::model_key;
 
-/// Sweep every `.m2` and census its **attachment addressing**: how many records it authors, how
-/// many attach ids its AttachLookup resolves, and — the point of the report — where the two
-/// disagree, i.e. where "scan the table for a record with this id" answers differently from the
-/// reference's `lookup[id]` (`0x710310`).
-///
-/// Built for decision 0805 (item glows hang on the item model's ids 0..4) to answer the question
-/// that decides whether the lookup can be adopted globally: which models change hands? One line
-/// per divergent model — `+id` = an id only the lookup reaches, `-id` = an id only a table scan
-/// reaches (a record the reference cannot address at all), `id:a→b` = same id, different record.
+/// List the models where a table scan for an attachment id and the reference's `lookup[id]`
+/// (`0x710310`) disagree: `+id` only the lookup reaches, `-id` only the scan reaches (the
+/// reference cannot address it), `id:a→b` a different record.
 pub fn attachscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
     let (mut scanned, mut with_points, mut divergent) = (0u32, 0u32, 0u32);
@@ -37,8 +27,6 @@ pub fn attachscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         }
         with_points += 1;
-        // What a table scan would answer (first record per id — the pre-0805 rule) against what
-        // the lookup answers, compared by the record each id lands on.
         let mut scan: BTreeMap<u16, usize> = BTreeMap::new();
         for (i, a) in model.attachments.iter().enumerate() {
             scan.entry(a.id).or_insert(i);
@@ -85,12 +73,8 @@ pub fn attachscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// One bone `M2Track` read straight off the file bytes (v256 stride `0x1c`: interp@0, gseq@2,
-/// interpolation_ranges `M2Array`@0x04/0x08, timestamps@0x0c/0x10, values@0x14/0x18).
-///
-/// Deliberately raw rather than via `parse_m2_animations`: this instrument's whole job is to
-/// compare what the **file** says against what our parser currently emits, so it must not go
-/// through the parser under test.
+/// One bone `M2Track` read raw, so the check never goes through the parser it tests: v256 stride
+/// `0x1c`, interp@0, gseq@2, then `M2Array`s ranges@0x04, timestamps@0x0c, values@0x14.
 struct RawBoneTrack {
     interp: u16,
     gseq: u16,
@@ -151,17 +135,17 @@ impl RawBoneTrack {
         })
     }
 
-    /// The reference's sample at absolute time `t_ms` for sequence file slot `slot` — FN1
-    /// (`0x713d50`) verbatim, then the sampler's own lerp/step leg (wow-re `eval.md` FN1/FN2/FN6).
+    /// The reference's sample at absolute `t_ms` for file slot `slot`: `0x713d50`'s key search,
+    /// then the lerp or step of `0x713ea0`/`0x71af20`.
     fn reference(&self, slot: usize, t_ms: u32) -> Option<[f32; 4]> {
         let last = self.ts.len().checked_sub(1)?;
-        // FN1 §1: the window is `ranges[slot]` when the array is present, else the whole key list.
+        // `0x713d59`: the window is `ranges[slot]` when present, else the whole key list.
         let (lo, hi) = match self.ranges.get(slot) {
             Some(&(lo, hi)) => (lo as usize, hi as usize),
             None => (0, last),
         };
         let (lo, hi) = (lo.min(last), hi.min(last));
-        // FN1 §2: a collapsed window resolves to `keys[lo]` outright.
+        // `0x713d7b`: a collapsed window resolves to `keys[lo]` outright.
         if lo >= hi {
             return Some(self.vals[lo]);
         }
@@ -173,7 +157,7 @@ impl RawBoneTrack {
                 break;
             }
         }
-        // FN1 §5: `k1 = k0+1`, bounded by the TOTAL key count — never by the window's `hi`.
+        // `0x713e45`: `k1 = k0 + 1`, bounded by the total key count, not the window's `hi`.
         if self.interp == 0 || k0 + 1 > last {
             return Some(self.vals[k0]);
         }
@@ -190,9 +174,8 @@ impl RawBoneTrack {
         Some(out)
     }
 
-    /// What `models::anim::read_bone_track` emits for this band today: the in-band keys, or — when
-    /// the band holds none — the single **nearest** out-of-band key (benilla decision 0133).
-    /// Returns `(value_at_band_start, value_at_band_end, band_was_empty)`.
+    /// A plain hold, the answer without the `ranges` window: the band's first and last own keys,
+    /// or the nearest out-of-band key when it has none, as `(start, end, band_was_empty)`.
     fn benilla_today(&self, start: u32, end: u32) -> Option<([f32; 4], [f32; 4], bool)> {
         let inb: Vec<usize> = (0..self.ts.len())
             .filter(|&k| self.ts[k] >= start && self.ts[k] <= end)
@@ -212,9 +195,8 @@ impl RawBoneTrack {
         Some((self.vals[k], self.vals[k], true))
     }
 
-    /// Distance between two sampled values in the channel's own units: **degrees** of rotation for
-    /// a quaternion (numerically stable near identity — `acos(dot)` has a ~0.04° floor in f32),
-    /// **model units** for a translation/scale vector.
+    /// Distance in the channel's units: degrees for a quaternion, by the chord form since
+    /// `acos(dot)` floors near 0.04° in f32; model units otherwise.
     fn delta(&self, a: [f32; 4], b: [f32; 4]) -> f32 {
         if self.comps == 4 {
             let norm = |q: [f32; 4]| {
@@ -245,30 +227,14 @@ impl RawBoneTrack {
     }
 }
 
-/// Sweep every `.m2` (optionally under a path prefix) and measure, per bone track and per sequence
-/// band, how far **our** skeletal parse sits from the **reference's** sampler — the population
-/// instrument behind benilla decision 0133's named residual ("an empty band clamps to the nearest
-/// authored key … a named approximation of the mid-gap lerp").
-///
-/// Three separately-reported disagreements, each a distinct mechanism (wow-re `eval.md`):
-///
-/// - **EMPTY bands** — a band with no keys of its own. We hold the nearest authored key; the
-///   reference holds `keys[ranges[slot].lo]`, or lerps across the bracket when the window spans two
-///   keys. The 0133 residual proper.
-/// - **HELD edges** — a keyed band whose first key is late / last key is early. Bevy holds the edge
-///   key; the reference keeps interpolating toward the neighbouring **out-of-band** key, because
-///   FN1's `k1 = k0+1` is bounded by the total key count and not by the window.
-/// - **STEP tracks** — `interpolation_type == 0`. The reference's samplers branch on it and copy
-///   `keys[k0]` with no interpolation; our bone parse emits keys and lets Bevy interpolate, so a
-///   snap becomes a glide.
-///
-/// Plus the safety check the whole idea rests on: whether any band's own keys fall **outside** the
-/// window `ranges[slot]` would search (they never do — if they did, adopting the window would
-/// reintroduce the garbage pose 0133 records).
+/// Measure, per bone track and sequence band, how far a plain key hold sits from the reference's
+/// sampler (`0x713d50`): an empty band samples the `ranges[slot]` window, past a band's last key
+/// the reference keeps lerping toward `k0 + 1` (bounded by the total key count, not the window),
+/// and a step track (`interp == 0`) copies `keys[k0]` where the emitted clips glide. It also
+/// checks that no band's keys fall outside its own window, which makes reading the window safe.
 pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let names = super::m2_names(chain, prefix)?;
-    // Above the f32 noise floor of the stable angle formula (~1e-4°) by two orders, and far below
-    // anything an eye could catch — a slot over this is a real authored difference.
+    // Two orders above the angle formula's f32 noise (about 1e-4°), far below what shows.
     const ROT_EPS: f32 = 0.01; // degrees
     const VEC_EPS: f32 = 1e-4; // model units
     let (mut scanned, mut models_step, mut models_empty_differ, mut models_edge_differ) =
@@ -282,7 +248,7 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     let mut gseq_orphan_models: BTreeSet<String> = BTreeSet::new();
     let mut gseq_restrict_models: BTreeSet<String> = BTreeSet::new();
     let mut emitted_extra = 0u64;
-    // (empty-band peak, keyed-edge peak) per channel kind — the bound, not a threshold count.
+    // (empty-band peak, keyed-edge peak) per channel kind.
     let (mut peak_rot, mut peak_vec) = ((0.0f32, 0.0f32), (0.0f32, 0.0f32));
     let mut emitted_models: BTreeSet<String> = BTreeSet::new();
     // Worst offender per class: (delta, model, bone, channel, slot).
@@ -303,7 +269,7 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 .map(|s| u32::from_le_bytes(s.try_into().unwrap()) as usize)
                 .unwrap_or(0)
         };
-        // Sequences in FILE order (count@0x1c/ofs@0x20, stride 0x44) — the order `ranges` indexes.
+        // Sequences in file order (count@0x1c, ofs@0x20, stride 0x44), the order `ranges` indexes.
         let (sn, so) = (u32_at(0x1c), u32_at(0x20));
         let seqs: Vec<(u32, u32)> = (0..sn)
             .map_while(|i| {
@@ -311,7 +277,7 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 (e + 0x44 <= b.len()).then(|| (u32_at(e + 4) as u32, u32_at(e + 8) as u32))
             })
             .collect();
-        // globalSequences @0x14/0x18 — a duration per entry; 0 means the loop has no period.
+        // globalSequences @0x14/0x18: a duration per entry, 0 for no period.
         let (gn, go) = (u32_at(0x14), u32_at(0x18));
         let gseq_period = |g: u16| -> u32 {
             let i = g as usize;
@@ -339,8 +305,7 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 if tr.interp == 0 {
                     step_tracks += 1;
                     m_step += 1;
-                    // The step deviation only becomes visible when a band holds TWO keys: that is
-                    // where the reference snaps and we glide. Measure the size of the snap.
+                    // A step shows only where a band holds two keys: the reference snaps there.
                     for (slot, &(start, end)) in seqs.iter().enumerate() {
                         if end <= start {
                             continue;
@@ -361,14 +326,10 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                         }
                     }
                 }
-                // A global-sequence track runs on its own clock. `read_bone_track` keeps the
-                // SINGLE-key case (a constant channel — the stowed-weapon rest quats) and leaves
-                // the multi-key case to `parse_m2_global_sequence_bones` → the `GlobalSeqDrive`
-                // lane, which needs a non-zero `globalSequences[gseq]` period. A multi-key channel
-                // on a ZERO-period global sequence falls between the two and is sampled by
-                // neither — census that gap, and the shape of the `ranges` window the reference
-                // would still apply here (FN1 selects the window BEFORE it resolves the gseq
-                // clock, so a restrictive window would clip the loop).
+                // A global-sequence track runs on its own clock: one key is a constant in every
+                // clip, more go to `parse_m2_global_sequence_bones`, which needs a non-zero
+                // period, so a multi-key track on a zero period plays nowhere. `0x713d50` picks
+                // the `ranges` window before the gseq clock, so a narrow window clips the loop.
                 if tr.gseq != 0xffff {
                     gseq_tracks += 1;
                     if tr.ts.len() > 1 {
@@ -426,8 +387,7 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                     } else {
                         peak.1 = peak.1.max(d);
                         slots_keyed += 1;
-                        // Does this band's own key set sit inside the window the reference
-                        // searches? If not, adopting the window would drop playable keys.
+                        // Reading the window is safe only if the band's own keys sit inside it.
                         if let Some(&(lo, hi)) = tr.ranges.get(slot) {
                             let inb: Vec<usize> = (0..tr.ts.len())
                                 .filter(|&k| tr.ts[k] >= start && tr.ts[k] <= end)
@@ -447,9 +407,8 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
                 }
             }
         }
-        // The other half of the check: what our parser ACTUALLY emits. A band-slot whose emitted
-        // key count exceeds its own in-band key count is one where the head/tail sample differed
-        // from the edge key and had to be carried — the only slots this parse changes.
+        // What the parse emits: a band-slot with more keys than its own in-band count carries a
+        // head or tail sample from the window.
         for a in benilla_formats::parse_m2_animations(&b) {
             for bk in &a.bones {
                 for (off, comps, emitted) in [
@@ -486,7 +445,6 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
         if m_edge > 0 {
             models_edge_differ += 1;
         }
-        // Keep the worst-offender lists bounded without losing the tail.
         for w in [&mut worst_empty, &mut worst_edge] {
             if w.len() > 4096 {
                 w.sort_by(|a, b| b.0.total_cmp(&a.0));
@@ -582,34 +540,19 @@ pub fn bonescan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// Sweep every `.m2` and census the **event table's positional half** — the `bone` and `position`
-/// fields every `M2Event` record carries beside its 4CC and timestamps.
-///
-/// The question it exists to answer: the reference's animation-event dispatchers hand their arms
-/// the event's **own** world point (`0x5f3e20`'s `[ebp+0x10]`, `&M2SceneCallback.position` — the
-/// authored `position` transformed by its bone's live matrix and the model's placement), while a
-/// consumer that plays every anim-event sound at the model root is using the placement alone. That
-/// difference is worth code only where the records are actually *off* the origin, or on a bone
-/// that *moves*; where every record of a tag sits at the origin on a static bone the two are the
-/// same point and the simpler consumer is not wrong.
-///
-/// So, per 4CC: how many records, how many sit more than [`OFF_ORIGIN`] from the model origin (the
-/// `position` field is already model-space — it is the marker's REST point, which is why
-/// `build_markers` subtracts the bone pivot to get a bone-local offset), how many ride a bone
-/// **whose chain any sequence keys** (the bone's own track being empty says nothing: it inherits
-/// its parent's matrix), and the largest offset seen with the model that authors it.
+/// Census each 4CC's `M2Event` records by `bone` and `position`. The reference hands an event's
+/// arm its own world point, the model-space rest `position` moved by its bone's live matrix and the
+/// placement (`0x5f3e20`'s `[ebp+0x10]`), which differs from the model root only for a record off
+/// the origin or on a bone whose chain any sequence keys.
 pub fn eventmarkerscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
-    /// Yards from the model origin past which a marker is "off the origin". Well under any
-    /// audible 3D difference, so it is a *presence* threshold, not a significance one.
+    /// Yards from the model origin past which a marker counts as off it: a presence threshold.
     const OFF_ORIGIN: f32 = 0.01;
     let names = super::m2_names(chain, prefix)?;
     // 4CC → (records, off-origin, on a keyed bone, max offset, the model + bone at that max)
     let mut per_tag: BTreeMap<String, (u32, u32, u32, f32, String)> = BTreeMap::new();
     let (mut scanned, mut carriers) = (0u32, 0u32);
-    // Models authoring the SAME 4CC more than once, and those whose duplicates disagree about
-    // where they are: the reference's kernel fires a specific RECORD and snapshots that record's
-    // point, so a consumer that resolves the tag by a first-match table scan answers the wrong
-    // point exactly here.
+    // Models that author a 4CC more than once, and those whose copies sit apart: the reference
+    // fires a specific record and takes its point, so a first-match lookup by tag is wrong there.
     let (mut dup_models, mut dup_split) = (0u32, 0u32);
     let mut dup_examples: Vec<String> = Vec::new();
     for name in names {
@@ -625,10 +568,7 @@ pub fn eventmarkerscan(chain: &mut Chain, prefix: Option<&str>) -> Result<()> {
             continue;
         }
         carriers += 1;
-        // Which bones any sequence keys at all. A marker's own bone being unkeyed is NOT enough
-        // to make it static — the bone inherits its parent's matrix — so the test walks the
-        // ancestor chain, which is the difference between "sits still" and "sits still relative to
-        // something that moves".
+        // The bones any sequence keys; a marker moves if any bone up its parent chain is keyed.
         let keyed: BTreeSet<u16> = benilla_formats::parse_m2_animations(&bytes)
             .iter()
             .flat_map(|a| a.bones.iter().map(|b| b.bone))
diff --git a/crates/benilla-formats/src/bin/benilla-extract/scan/world.rs b/crates/benilla-formats/src/bin/benilla-extract/scan/world.rs
index c8f7f553..b6c1191e 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/scan/world.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/scan/world.rs
@@ -1,8 +1,4 @@
-//! Corpus scans over **placed world content** — what a WMO root or an ADT tile block puts in
-//! the world, and how much of it the reference would even draw.
-//!
-//! One `.wmo` root's own tables (`wmodoodads`, `skyboxscan`) and one map region's placements
-//! (`placescan`, `doodadscan`). How a placed prop is LIT is a separate question — [`super::lighting`].
+//! Corpus scans over placed world content: a WMO root's own tables and an ADT region's placements.
 
 use std::collections::{BTreeMap, HashMap, HashSet};
 
@@ -11,12 +7,9 @@ use benilla_formats::{Chain, M2AnimSummary};
 
 use crate::{model_key, yn};
 
-/// Dump a WMO root's placed-prop tables: every MODD doodad with its MODS set membership and its
-/// OWNING group(s) read from the group files' MODR lists — the relation the reference instantiates
-/// from (`0x695aa0` loops a *visible* group's own refs, wow-re `m2-interior-doodad-base-light.md`
-/// §453). A prop referenced by NO group is never created by the real client at all — the
-/// divergence decision 0689 names and benilla still spawns. This answers "which props exist here,
-/// who owns them, and which would the reference even draw" in one read (the B30/B32 question).
+/// Dump a WMO root's MODD props with their MODS sets and owning groups, read from the group files'
+/// MODR lists. The reference creates a prop only from a visible group's refs (`0x695aa0`), so it
+/// never draws a prop no group names (`ORPHAN`); benilla spawns one with no room gate.
 pub fn wmodoodads(chain: &mut Chain, raw_path: &str, filter: Option<&str>) -> Result<()> {
     let root_path = raw_path.replace('/', "\\").to_ascii_lowercase();
     let bytes = chain
@@ -26,7 +19,7 @@ pub fn wmodoodads(chain: &mut Chain, raw_path: &str, filter: Option<&str>) -> Re
         .with_context(|| format!("parsing WMO root '{root_path}'"))?;
     let set_names = mods_set_names(&bytes);
 
-    // MODD index -> the groups whose MODR reference it (the ownership relation).
+    // MODD index -> the groups whose MODR names it.
     let stem = root_path.strip_suffix(".wmo").unwrap_or(&root_path);
     let mut owners: BTreeMap<u16, Vec<u32>> = BTreeMap::new();
     let mut groups_read = 0u32;
@@ -121,9 +114,8 @@ pub fn wmodoodads(chain: &mut Chain, raw_path: &str, filter: Option<&str>) -> Re
     Ok(())
 }
 
-/// The MODS set names (`char name[20]` per 32-byte record) — `WmoDoodadSet` keeps only the ranges,
-/// so read the names off the raw root bytes here (top-level chunks are `[magic][size][data]`, magic
-/// on disk reversed: MODS → `SDOM`).
+/// The MODS set names, `char name[20]` at the head of each 32-byte record, read off the raw root
+/// (chunk magics are reversed on disk: `SDOM`) since `WmoDoodadSet` keeps only the ranges.
 fn mods_set_names(bytes: &[u8]) -> Vec<String> {
     let mut off = 0usize;
     while off + 8 <= bytes.len() {
@@ -156,31 +148,14 @@ fn mods_set_names(bytes: &[u8]) -> Vec<String> {
     Vec::new()
 }
 
-/// Sweep every WMO **root** in the chain and report the two halves of the skybox mechanism: which
-/// roots author a **MOSB** skybox model, and which carry groups flagged `0x40000`
-/// ([`benilla_formats::WmoGroupInfo::show_skybox`]).
-///
-/// This is the instrument that *identifies* the flag — and **exactly how far that identification
-/// reaches is the point**. `0x40000` is undocumented, so the cross-tab is what establishes it means
-/// anything at all: the bit never appears on a group whose root names no skybox, across all 815
-/// roots. That is a one-way implication, `flag ⇒ MOSB`, and the summary prints it so the claim is
-/// re-checkable in one command rather than trusted from a decision record.
-///
-/// **It does not, and cannot, say which group the RENDERER tests** — and reading it as if it did is
-/// the mistake decision 0767 made (superseded by 0773). The carved law is that `0x40000` is tested
-/// inside the portal flood (`0x6b42e0` in `0x6b41c0`) on the group being *visited*, so the predicate
-/// is "any flood-reached group carries the bit". A census over static asset bytes has no way to see
-/// that distinction; only the binary did.
-///
-/// It is also the population instrument for the mechanism: which buildings in 1.12 replace the
-/// `Light.dbc` gradient dome with an authored sky, and how much of each one does it. Stratholme's
-/// city shell sets the bit on 61 of its 83 groups; the only other roots that set it at all are the
-/// four Caverns of Time shells, which ship in the 5875 data with no 1.12 instance to enter.
+/// Cross-tab every WMO root's MOSB skybox model against its groups flagged `0x40000`
+/// ([`benilla_formats::WmoGroupInfo::show_skybox`]): across the 815 roots the flag never appears
+/// without a MOSB. Which group counts is not in the assets: the reference tests the bit on each
+/// group its portal flood visits (`0x6b42e0` in `0x6b41c0`). Only Stratholme's shell (61 of 83
+/// groups) and the four unused Caverns of Time shells set it.
 pub fn skyboxscan(chain: &mut Chain) -> Result<()> {
-    // Roots only, because only the root carries MOSB/MOGI.
     let names = super::wmo_roots(chain, None)?;
 
-    // The cross-tab that identifies the flag: roots with/without a MOSB × groups with/without 0x40000.
     let (mut both, mut mosb_only, mut flag_only, mut neither) = (0u32, 0u32, 0u32, 0u32);
     let mut scanned = 0u32;
     let mut hits: Vec<(String, String, usize, usize)> = Vec::new();
@@ -235,7 +210,7 @@ pub fn skyboxscan(chain: &mut Chain) -> Result<()> {
         );
         println!(
             "   It does NOT say WHICH group the renderer tests, and reading it as if it did is the \
-             mistake decision 0767 made (superseded by 0773). The carved law: 0x40000 is tested \
+             mistake decision 0767 made (superseded by 0773). The actual law: 0x40000 is tested \
              inside the portal flood (0x6b42e0 in 0x6b41c0) on the group being VISITED, never on the \
              group the camera stands in — so the predicate is 'any FLOOD-REACHED group carries the \
              bit, and the root names a MOSB'. Stratholme's King's Square is the counter-example that \
@@ -251,10 +226,7 @@ pub fn skyboxscan(chain: &mut Chain) -> Result<()> {
     Ok(())
 }
 
-/// List individual doodad (MDDF) and WMO (MODF) placements around a world position whose model
-/// path contains `filter` (case-insensitive) — the per-placement position / Euler rotation /
-/// scale / uniqueId ground truth an orientation investigation needs (`doodadscan` only
-/// aggregates).
+/// List the MDDF and MODF placements near a world position whose model path contains `filter`.
 pub fn placescan(
     chain: &mut Chain,
     map: &str,
@@ -300,9 +272,8 @@ pub fn placescan(
     Ok(())
 }
 
-/// Bulk-scan placed doodads (MDDF) and WMO doodad-set-0 props (MODF → MODS/MODD) across a
-/// `(2·tile_radius+1)²` block of ADT tiles around a world position, and report how much of that
-/// content animates.
+/// Count the placed doodads (MDDF) and WMO set-0 props (MODF → MODS/MODD) in the
+/// `(2·tile_radius+1)²` tiles around a world position, and how much of that content animates.
 pub fn doodadscan(
     chain: &mut Chain,
     map: &str,
@@ -314,12 +285,10 @@ pub fn doodadscan(
         .with_context(|| format!("loading tiles around ({center_x}, {center_y}) on {map}"))?;
     eprintln!("{} tile(s) loaded", tiles.len());
 
-    // Direct M2 placements (MDDF) — deduped by uniqueId, which a tile-straddling doodad
-    // repeats identically across every tile it touches (decision-0021 terrain streamer's own
-    // dedup key; see `benilla_formats::Doodad::unique_id`).
+    // MDDF placements, deduped by uniqueId: a doodad straddling tiles repeats in each one.
     let mut seen_doodad_ids: HashSet<u32> = HashSet::new();
     let mut m2_instances: HashMap<String, u32> = HashMap::new();
-    // WMO placements (MODF) — same dedup, by their own uniqueId.
+    // MODF placements, deduped the same way.
     let mut seen_wmo_ids: HashSet<u32> = HashSet::new();
     let mut wmo_instances: HashMap<String, u32> = HashMap::new();
     for (_, tile) in &tiles {
@@ -345,10 +314,7 @@ pub fn doodadscan(
         wmo_instances.len()
     );
 
-    // Fold each unique WMO's doodad-set-**0** M2 props into the same instance table (set 0 is
-    // the WMO's always-on global set, per `WmoDoodadSet` doc), each multiplied by that WMO's
-    // own (deduped) placement count — one building placement = one instance of every set-0 prop
-    // it carries.
+    // Each WMO placement adds one instance of every set-0 prop, the always-on global set.
     let mut wmo_root_failures = 0u32;
     for (wmo_path, &count) in &wmo_instances {
         let root_path = wmo_path.to_ascii_lowercase(); // matches `load_wmo`'s own normalization
@@ -374,7 +340,6 @@ pub fn doodadscan(
         eprintln!("  ({wmo_root_failures} WMO root(s) failed to read/parse — skipped)");
     }
 
-    // Per-unique-model animation summary — one parse per model regardless of instance count.
     let mut summaries: HashMap<String, M2AnimSummary> = HashMap::new();
     let mut parse_failures: Vec<(String, String)> = Vec::new();
     for model in m2_instances.keys() {
@@ -453,9 +418,7 @@ pub fn doodadscan(
         }
     }
 
-    // The rare material channels by NAME (each is <1% of instances, so the top-30 table
-    // almost never surfaces them): the exact models the phase-2/3 material-animation work
-    // verifies against.
+    // The rare material channels by name: each is under 1% of instances, below the top 30.
     println!();
     println!("=== material-channel models (animated transparency / color / UV) ===");
     let mut rare: Vec<(&String, &u32)> = m2_instances
@@ -480,8 +443,7 @@ pub fn doodadscan(
         );
     }
 
-    // Moving-seq0 models with a variation chain, by NAME (the wow-re §4a random-variation
-    // arm correction): the exact placed models where variationIdx −1 vs 0 is visible at all.
+    // Moving seq-0 models with a variation chain, where the random pick (`0x695100`) shows.
     println!();
     println!("=== moving-seq0 multi-variation models ===");
     let mut varied: Vec<(&String, &u32)> = m2_instances
@@ -501,9 +463,7 @@ pub fn doodadscan(
         );
     }
 
-    // Emitters hosted on a moving bone chain, by NAME (0130 phase 4 grounding): the exact
-    // placed models where emitter bone-follow is visible at all — an emitter on a static
-    // chain sits at its rest pose whether or not we attach it.
+    // Emitters on a moving bone chain: the placed models where emitter bone-follow shows.
     println!();
     println!("=== emitter-on-moving-bone models ===");
     let mut movers: Vec<(&String, &u32)> = m2_instances
diff --git a/crates/benilla-formats/src/bin/benilla-extract/shakecensus.rs b/crates/benilla-formats/src/bin/benilla-extract/shakecensus.rs
index 2874a377..bee26f19 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/shakecensus.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/shakecensus.rs
@@ -1,30 +1,7 @@
-//! `shakecensus`: the whole-table view of the **camera-shake** system (decisions 1540/1849) — the
-//! 24 shipped `CameraShakes.dbc` presets, and everything that names one: the creature models
-//! (footstep + death thud), and the `SpellEffectCameraShakes.dbc` groups the spell side reaches
-//! them through.
-//!
-//! The scope instrument for B298 ("walking past an Ancient Protector shakes no screen"). It
-//! answers, from the shipped data rather than from expectation, the two questions that turn that
-//! one report into a system: *which* creatures are affected (not just the Ancients — every kodo,
-//! giant, titan and dragon in the game), and whether `CreatureModelData` fields 11/12 really are
-//! `CameraShakes` keys — because if they are, every live value must land on a real row of a
-//! 24-row table, and the amplitudes must rank by mass. A column map that were merely plausible
-//! would scatter across the id space and hit holes.
-//!
-//! Read the output beside the module doc of [`benilla_formats::CameraShakeCatalog`]: the creature
-//! rows and the spell rows are visibly different shapes (phase, duration, the direction triples),
-//! and that split is itself the check.
-//!
-//! The **group** half (decision 1849) is the same instrument one indirection out: 58 of the 1772
-//! shipped `SpellVisualKit` rows name a group in field 14, every value must land on the 9-row
-//! table, and the census names the kits so a spell-side shake can be traced from a preset back to
-//! the kit that fires it. Then the `$SHK` sweep, whose **host** column is the one that matters —
-//! only a GameObject or DynamicObject decodes the tag, so a marker on a creature or spell-effect
-//! model, or on one nothing hosts at all, is authored-but-inert.
-//!
-//! The roll-up at the end is deliberately **two tiers**, because they answer different questions: a
-//! preset can be *named by a table* and still have nothing that fires it. Keeping them apart is
-//! what caught this census's own field-12 mistake (see the `$SHK` block).
+//! `shakecensus`: the 24 shipped `CameraShakes.dbc` presets and all that names one: creature
+//! models (`CreatureModelData` fields 11 and 12, footstep and death thud), the 9
+//! `SpellEffectCameraShakes.dbc` groups that `SpellVisualKit` field 14 names, and `$SHK` animation
+//! events. Every named id must land on a real row, or the column map is wrong.
 
 use std::collections::{BTreeMap, BTreeSet};
 
@@ -38,8 +15,7 @@ struct Users {
     death_thud: Vec<String>,
 }
 
-/// A model path reduced to a comparison key: lowercase, back-slashed, extension dropped. The DBCs
-/// name models `.mdx`; the archives hold them as `.m2`, and the casing is arbitrary in both.
+/// A model path's comparison key: DBCs name models `.mdx`, the archives hold `.m2`, in any case.
 fn mdx_key(path: &str) -> String {
     let p = path.to_ascii_lowercase().replace('/', "\\");
     match p.rsplit_once('.') {
@@ -48,7 +24,6 @@ fn mdx_key(path: &str) -> String {
     }
 }
 
-/// The model's own file name — the census reads better without the `Creature\\Foo\\` prefix.
 fn short(path: &str) -> String {
     path.rsplit('\\').next().unwrap_or(path).to_string()
 }
@@ -78,7 +53,7 @@ pub fn shakecensus(chain: &mut Chain) -> Result<()> {
         }
     }
 
-    // Which groups name each preset, and which kits name each group — the spell side's two hops.
+    // The spell side's two hops: the groups naming each preset, the kits naming each group.
     let mut group_users: BTreeMap<u32, Vec<u32>> = BTreeMap::new();
     for g in shakes.groups() {
         for id in g.shakes() {
@@ -145,8 +120,7 @@ pub fn shakecensus(chain: &mut Chain) -> Result<()> {
         );
     }
 
-    // Every value the creature columns actually carry must resolve — a miss would say the column
-    // map is wrong, which is the whole point of running this.
+    // Every value the creature columns carry must resolve; a miss means the column map is wrong.
     let mut dangling = Vec::new();
     for (model_id, path, footstep, thud) in &models {
         for (col, id) in [
@@ -210,24 +184,13 @@ pub fn shakecensus(chain: &mut Chain) -> Result<()> {
         }
     }
 
-    // The third producer: the `$SHK` animation event, whose payload is a GROUP id (never a preset
-    // id). Only the GameObject and DynamicObject dispatchers decode it — `CGUnit_C::HandleAnimEvent`
-    // does not — so a `$SHK` on a creature M2 is inert, and this sweep is what says whether the
-    // shipped content authors any at all.
+    // The third producer, the `$SHK` animation event, whose payload is a group id, never a preset.
     println!("\n$SHK animation events — the third producer (GameObject / DynamicObject only)\n");
-    // The HOST column is what decides whether a marker is live at all: only the GameObject
-    // (typemask 0x20, `0x5f3e20`) and DynamicObject (0x40, `0x5d58c0`) dispatchers decode `$SHK`.
-    // A marker on a creature M2 reaches `CGUnit_C::HandleAnimEvent`, which does not decode the tag
-    // (decision 1540); one on a model that is only ever a bone-attached `CEffect` reaches the fixed
-    // `$SND`/`$HIT` router `0x61f6f0`. Both are authored-but-inert.
-    //
-    // The DynamicObject side is easy to get wrong and this census got it wrong once: the anchor's
-    // area model is `SpellVisual` **field 12**, gated by field 11 ([`VisualStages::area_effect`] /
-    // `area_gate` — wow-re `dynobject-visual-machine.md`, benilla's `entities::dest_fx`). Judging
-    // the `Spells\*` carriers by "no display table names it" reported six presets dead that are
-    // not: Warlock **Inferno** (SpellVisual 4859 → effect 2362 `Infernal_Impact_Base`) and
-    // Ragnaros's **Meteor** (7479 → 3007 `Meteor_Impact_Base`) both plant one, and both models
-    // carry `$SHK` group 2. So the host set is three, not two.
+    // Only the GameObject (typemask 0x20, `0x5f3e20`) and DynamicObject (0x40, `0x5d58c0`)
+    // dispatchers decode `$SHK`; on a creature it reaches `CGUnit_C::HandleAnimEvent` and on a
+    // bone-attached `CEffect` the fixed `$SND`/`$HIT` router `0x61f6f0`, and neither decodes it.
+    // A DynamicObject's area model is `SpellVisual` field 12, gated by field 11 (`0x5d57c0`):
+    // Inferno's visual 4859 and Meteor's 7479 plant one (effects 2362, 3007) with `$SHK` group 2.
     let gos = benilla_formats::load_gameobject_catalog(chain)?;
     let go_models: BTreeSet<String> = gos.iter().map(|(_, path)| mdx_key(path)).collect();
     let creature_models: BTreeSet<String> = creatures.model_paths().map(mdx_key).collect();
@@ -316,10 +279,8 @@ pub fn shakecensus(chain: &mut Chain) -> Result<()> {
         tally(&shk_live_groups)
     );
 
-    // The roll-up, in two tiers, because they answer different questions. A preset can be NAMED by
-    // a table and still have nothing that fires it — presets 7/8/9 sit only in group 2, and a group
-    // no kit and no `$SHK` marker names is a dead row. A shipped-but-unreachable preset is a
-    // finding, not a bug; it is printed rather than inferred so nobody has to guess.
+    // Two tiers: a preset a table names can still have nothing that fires it, as a group no kit
+    // and no live `$SHK` marker names is dead.
     let named: BTreeSet<u32> = users
         .keys()
         .copied()
diff --git a/crates/benilla-formats/src/bin/benilla-extract/spellvis.rs b/crates/benilla-formats/src/bin/benilla-extract/spellvis.rs
index 4fedadfc..da34b162 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/spellvis.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/spellvis.rs
@@ -1,6 +1,4 @@
-//! `spellvis`: dump a spell's visual chain — spell → SpellVisual stages → each kit's anim/sound/
-//! camera shake/attach effects, plus the missile block — decision 0099's phase-2 instrument
-//! (columns per decisions 0107 and 1849).
+//! `spellvis`: dump a spell's visual chain, every stage's kit and the missile.
 
 use anyhow::Result;
 use benilla_formats::Chain;
@@ -38,9 +36,7 @@ pub fn run(chain: &mut Chain, spell_id: u32) -> Result<()> {
                         kit.anim_id.map_or("—".into(), |a| a.to_string()),
                         kit.sound.map_or("—".into(), |s| s.to_string()),
                     );
-                    // The kit's CAMERA SHAKE (field 14, decision 1849): a
-                    // `SpellEffectCameraShakes` GROUP id, expanded to the presets it fires.
-                    // `benilla-extract … shakecensus` is the whole-table view.
+                    // Field 14: a `SpellEffectCameraShakes` group id, expanded to its presets.
                     if let Some(group) = kit.shake {
                         match shakes.group(group) {
                             Some(g) => println!(
@@ -55,11 +51,9 @@ pub fn run(chain: &mut Chain, spell_id: u32) -> Result<()> {
                             ),
                         }
                     }
-                    // The kit's CharProcs (fields 15-34): what it does to the BODY.
+                    // The kit's CharProcs (fields 15-34), what it does to the body.
                     crate::charprocs::print_kit_procs(&visuals, kit_id, "           ");
-                    // The kit's BEAM, if it draws one (decision 0955): the chain CharProc's
-                    // decoded `SpellChainEffects` row. `benilla-extract … chaincensus` is the
-                    // whole-table view.
+                    // The beam, if any: the chain CharProc's decoded `SpellChainEffects` row.
                     if let Some(c) = kit.chain_proc() {
                         match visuals.chain_effect(c.effect_id) {
                             Some(e) => println!(
@@ -81,7 +75,6 @@ pub fn run(chain: &mut Chain, spell_id: u32) -> Result<()> {
                             ),
                         }
                     }
-                    // The kit's attach-point emitter slots (phase 3): tag + effect model.
                     for (tag, effect) in kit.effects() {
                         println!(
                             "           attach {tag:#04x} effect {effect:<5} -> {}",
diff --git a/crates/benilla-formats/src/bin/benilla-extract/thudcensus.rs b/crates/benilla-formats/src/bin/benilla-extract/thudcensus.rs
index 5f24fa1a..7235cd07 100644
--- a/crates/benilla-formats/src/bin/benilla-extract/thudcensus.rs
+++ b/crates/benilla-formats/src/bin/benilla-extract/thudcensus.rs
@@ -1,29 +1,14 @@
-//! `thudcensus`: the whole-table view of the **death thud** — the body-fall sound a corpse makes
-//! as it lands (`$DTH` → `0x6236e0`), the sibling of the same event's camera shake.
-//!
-//! Two halves, because the report it exists for ("a big corpse hits the ground silently") has two
-//! possible causes and they look identical in game:
-//!
-//! 1. **The table** — the `DeathThudLookups.dbc` matrix in full, `SizeClass × TerrainTypeSoundID`
-//!    → the land and water `SoundEntries` kits, named. An empty cell here is *authored* silence
-//!    (Sand and Soggy have no water column at all), and telling that apart from a bug is the
-//!    whole point of printing the grid rather than the rows.
-//! 2. **The population** — which creature M2s actually key a `$DTH` at all, on which sequences,
-//!    and what size class each resolves to. A model that keys none is silent in the reference
-//!    too; a model that keys one and still sounds wrong is a runtime question, not a data one.
-//!
-//! The cross-check that validates the column map: every live `DeathThudLookups` sound id must
-//! land on a real `SoundEntries` row, every terrain axis value on a real `TerrainTypeSounds` row,
-//! and every model's `SizeClass` inside `0..=4` — a shifted field would scatter across the id
-//! space and hit holes, exactly as `shakecensus` checks fields 11/12.
+//! `thudcensus`: the death thud a corpse makes as it lands (`$DTH`, `0x6236e0`): the full
+//! `DeathThudLookups.dbc` grid, `SizeClass × TerrainTypeSoundID` to land and water `SoundEntries`
+//! kits, and the creature models that key a `$DTH`. An empty cell is authored silence (Sand and
+//! Soggy have no water column), as is a model with no `$DTH`.
 
 use std::collections::{BTreeMap, BTreeSet};
 
 use anyhow::Result;
 use benilla_formats::Chain;
 
-/// A model path reduced to a comparison key: lowercase, back-slashed, extension dropped. The DBCs
-/// name models `.mdx`; the archives hold them as `.m2`.
+/// A model path's comparison key: DBCs name models `.mdx`, the archives hold `.m2`.
 fn mdx_key(path: &str) -> String {
     let p = path.to_ascii_lowercase().replace('/', "\\");
     match p.rsplit_once('.') {
@@ -32,8 +17,7 @@ fn mdx_key(path: &str) -> String {
     }
 }
 
-/// The `SizeClass` names the shipped kits give themselves (`DeathThudSmallDirt` …
-/// `DeathThudColossalWood`).
+/// The `SizeClass` names the kits carry, `DeathThudSmallDirt` to `DeathThudColossalWood`.
 const SIZE_NAMES: [&str; 5] = ["Small", "Medium", "Large", "Giant", "Colossal"];
 
 fn size_name(class: i32) -> String {
@@ -50,8 +34,7 @@ pub fn thudcensus(chain: &mut Chain) -> Result<()> {
     let creatures = benilla_formats::load_creature_catalog(chain)?;
 
     // ── 1 · the table ────────────────────────────────────────────────────────────────────────
-    // The terrain axis, with the TerrainType rows that reach each id — a terrain sound nothing
-    // names is unreachable however well-populated its column is.
+    // The terrain axis with the TerrainType rows naming each id; an unnamed sound is unreachable.
     let mut terrain_names: BTreeMap<u32, Vec<u32>> = BTreeMap::new();
     for terrain in 0..64 {
         if let Some(sound) = steps.sound_class_of(terrain) {
@@ -104,9 +87,7 @@ pub fn thudcensus(chain: &mut Chain) -> Result<()> {
     }
 
     // ── 2 · the population ───────────────────────────────────────────────────────────────────
-    // Which creature models key a `$DTH`, and the size class(es) the displays that reach each one
-    // resolve to. A model whose displays disagree is normal — 2 971 displays override their
-    // model's column — and the census prints the whole set so a mis-sized thud is visible.
+    // 2971 displays override their model's size class, so each model prints the whole set.
     let mut resolved: BTreeMap<u32, BTreeSet<u32>> = BTreeMap::new();
     for (display, model) in creatures.display_models() {
         if let Some(class) = creatures.size_class(display) {
@@ -204,16 +185,10 @@ pub fn thudcensus(chain: &mut Chain) -> Result<()> {
         off_axis.len()
     );
 
-    // ── 3 · where a corpse is SILENT ─────────────────────────────────────────────────────────
-    // The asymmetry the table half implies and only this sweep sizes. Both lookups are keyed on
-    // `TerrainType.SoundID`, and `TerrainType 10 "None"` — the unauthored default a WMO surface
-    // takes when its `MOMT+0x20` says nothing — has `SoundID = 0`. `FootstepTerrainLookup` has a
-    // **row at terrain sound 0** for 17 footstep classes; `DeathThudLookups` has **none at all**.
-    // So the same floor that creaks underfoot swallows the body that lands on it, and that is
-    // authored data in both directions, not a gap on either side.
-    //
-    // What this section measures is how much of the shipped building stock that covers, because
-    // "a corpse landed silently indoors" is a *correct* observation that looks exactly like a bug.
+    // ── 3 · where a corpse is silent ─────────────────────────────────────────────────────────
+    // Both lookups key on `TerrainType.SoundID`, and TerrainType 10 "None", the default of a WMO
+    // surface whose `MOMT+0x20` is unset, has `SoundID` 0. `FootstepTerrainLookup` has rows there
+    // for 17 footstep classes and `DeathThudLookups` none, so a corpse on such a floor is silent.
     let ftl_at_zero: Vec<u32> = (0..256)
         .filter(|c| steps.resolve_terrain(*c, 10).is_some())
         .collect();
@@ -244,9 +219,7 @@ pub fn thudcensus(chain: &mut Chain) -> Result<()> {
         for ground_type in root.material_ground_types() {
             materials += 1;
             *by_terrain.entry(ground_type).or_default() += 1;
-            // A material thuds iff its terrain id reaches a nonzero TerrainTypeSounds class that
-            // the thud table has a row for. Size class is irrelevant to *whether* — every class
-            // 0..=4 is populated on the same terrain axis.
+            // Size class 0 stands for all: every class 0..=4 has rows on the same terrain axis.
             if steps
                 .sound_class_of(ground_type)
                 .is_some_and(|ts| thuds.resolve(0, ts).is_some())
@@ -284,8 +257,7 @@ pub fn thudcensus(chain: &mut Chain) -> Result<()> {
         "\n{silent_roots} of {wmo_roots} WMO roots have NO surface that can thud; {} do",
         thudding.len()
     );
-    // All of them, not a head: the question this list answers is "does THIS building thud", and a
-    // truncated list cannot answer it. 121 lines is a census, not a flood.
+    // Untruncated: the list answers whether a given building thuds.
     for p in &thudding {
         println!("  thuds somewhere: {p}");
     }
diff --git a/crates/benilla-formats/src/bin/mpqx.rs b/crates/benilla-formats/src/bin/mpqx.rs
index 3e7389a5..fc8a3cb5 100644
--- a/crates/benilla-formats/src/bin/mpqx.rs
+++ b/crates/benilla-formats/src/bin/mpqx.rs
@@ -1,9 +1,6 @@
-//! One-off extraction helper (session tool, not shipped): `mpqx <data-dir> <virtual-path> <out>`.
-//! Reads through the SAME patch chain as the runtime ([`benilla_formats::Chain`], the full vanilla
-//! mount law) — it used to hand-roll a partial archive list in `benilla-mpq` and silently
-//! miss whole archives (`wmo.MPQ`: "not found" for every building/ship). A path the top archive
-//! **delete-marks** is reported as DELETED (exit 2) — the client doesn't load it; look for a
-//! `Blizzard_*` addon replacement (decision 0246).
+//! Extraction helper, not shipped: `mpqx <data-dir> <virtual-path> <out>`, read through the
+//! runtime's patch chain ([`benilla_formats::Chain`]). It exits 2 on a path the top archive
+//! delete-marks, which the client does not load.
 
 use std::path::Path;
 
@@ -32,7 +29,7 @@ fn main() {
                 from
             );
         }
-        // Chain::read distinguishes the tombstone in its message; surface it with the old exit code.
+        // `Chain::read` names a delete-marked path in its error message.
         Err(e) if e.to_string().contains("deleted from patch chain") => {
             eprintln!("{e} — the client does not load this path (see decision 0246)");
             std::process::exit(2);
diff --git a/crates/benilla-formats/src/camera_shakes.rs b/crates/benilla-formats/src/camera_shakes.rs
index deab81f1..de7bb993 100644
--- a/crates/benilla-formats/src/camera_shakes.rs
+++ b/crates/benilla-formats/src/camera_shakes.rs
@@ -1,69 +1,12 @@
-//! `CameraShakes.dbc` — the shipped camera-shake presets.
+//! `CameraShakes.dbc`, the 24 shipped camera-shake presets, and `SpellEffectCameraShakes.dbc`,
+//! the 9 groups of up to three presets fired at one point.
 //!
-//! A shake is **not** authored per model or per animation: the model names a preset id, and this
-//! 24-row table holds the shape. Two id spaces reach it (decisions 1540, 1849):
-//!
-//! - **The big-creature footstep/death thud** names a preset **directly** —
-//!   `CreatureModelData.FootstepShakeSize` (field 11) and `.DeathThudShakeSize` (field 12), read
-//!   here through [`CreatureCatalog::footstep_shake`](crate::CreatureCatalog::footstep_shake).
-//! - **Everything else names a GROUP** — `SpellEffectCameraShakes.dbc`, the 9-row indirection read
-//!   here too ([`SpellShakeGroup`]): up to three `CameraShakes` ids fired at one point. Both
-//!   `SpellVisualKit` field 14 and the `$SHK` animation event speak this id space and never the
-//!   preset one (wow-re `go-display-sound-events.md`: `[0xc0d814]`, bound `0xc0d818`).
-//!
-//! **Layout — VERIFIED** against build 5875 (header + row decode, 2026-08-22): `24 × 8 × 32 B`,
-//! string block empty. The **column names** are the conventional map (wowdev.wiki + vmangos
-//! `DBCStructure.h`), and the shipped values corroborate them structurally rather than by
-//! assertion: rows 4/5/6, 7/8/9, 13/14/15, 16/17/18, 36/37/38 and 76/77/78 are **direction
-//! triples** — identical `Duration` within a triple, `Direction` running 0·1·2 — which is what a
-//! per-axis column looks like and nothing else does.
-//!
-//! **The two families are visibly distinct**, which is the check that the creature columns really
-//! do index this table:
-//!
-//! | family | rows | `Type`/`Direction` | `Duration` | `Phase` | `Coefficient` |
-//! |---|---|---|---|---|---|
-//! | creature (footstep + thud) | 1, 2, 10, 11, 12 | `1` / `2` | 0.40–0.65 s | **nonzero** | 1.0–2.0 |
-//! | spell (the direction triples) | 4–9, 13–18, 36–38, 76–78 | 0 or 1 / 0·1·2 | 0.6–20 s | **0.0** | 0.4–3.0 |
-//!
-//! and within the creature family the amplitude ranks by mass exactly as it should: the Ancient
-//! Protector and the kodo take row 1 (`amplitude 2.0`), the Ancient of Lore/War, the giants and
-//! the dragons take row 2 (`amplitude 7.0`), and the death thuds (rows 11/12) are longer and
-//! stronger than the footsteps.
-//!
-//! **The semantics** — what `ShakeType` and `Direction` select, and the distance attenuation the
-//! evaluator applies — were settled by the wow-re dispatch behind decision 1540 and live beside the
-//! evaluator, in `benilla-app`'s `camera_shake`. This module stays the shipped data and nothing
-//! more.
-//!
-//! ## The group table — `SpellEffectCameraShakes.dbc` (9 rows × 4 fields, recsize 16)
-//!
-//! Every **spell-side** producer names a row of *this* table, never a `CameraShakes` id: the
-//! reference's shake spawner is reached through a group that fires **up to three presets at one
-//! point**. Layout verified against build 5875 the same way ([`SpellShakeGroup`]): `ID` plus three
-//! `CameraShakes` ids at `+0x4/+0x8/+0xc`, zeros skipped, string block empty. The shipped rows:
-//!
-//! | group | slots | group | slots |
-//! |---|---|---|---|
-//! | 1 | 4 · 5 · 6 | 6 | 4 · 5 · 6 |
-//! | 2 | 7 · 8 · 9 | 7 | 18 · 17 · 18 |
-//! | 3 | 1 | 26 | 36 · 37 · 38 |
-//! | 4 | 15 · 14 · 15 | 66 | 76 · 77 · 78 |
-//! | 5 | 11 | | |
-//!
-//! **The three slots are slots, not axes.** Group 4 lists `15` twice and group 7 lists `18` twice —
-//! a per-axis reading cannot survive that. The *intent* is clearly a per-axis triple (the ids named
-//! are the `direction` 0·1·2 members of a `CameraShakes` family), but the duplicate simply loses the
-//! evaluator's strict-`>` tie-break and contributes nothing.
-//!
-//! **Reachability.** The creature columns name `CameraShakes` {1, 2, 10} (footstep) and
-//! {10, 11, 12, 38} (thud); the nine groups name {1, 4, 5, 6, 7, 8, 9, 11, 14, 15, 17, 18, 36, 37,
-//! 38, 76, 77, 78}. Their union is 21 of the 24 shipped rows — **13, 16 and 56 are named by neither
-//! table**. All three are `direction 0` rows; 13 and 16 are the missing member of a family whose
-//! other two *are* named (14/15 by group 4, 17/18 by group 7), and 56 stands alone. See
-//! `benilla-extract shakecensus`, which prints the whole map — and keeps "named by a table" apart
-//! from "has a live producer behind it", which are the same 21 rows here only because every group
-//! turns out to have a producer.
+//! Two id spaces, never conflated: the creature footstep and death-thud columns
+//! (`CreatureModelData` fields 11 and 12, read through
+//! [`CreatureCatalog::footstep_shake`](crate::CreatureCatalog::footstep_shake)) name a preset
+//! directly, while `SpellVisualKit` field 14 and the `$SHK` animation event name a group, never a
+//! preset (`[0xc0d814]`, bound `0xc0d818`). Column names follow vmangos `DBCStructure.h`; what
+//! `ShakeType` and `Direction` select is the evaluator's, `benilla-app`'s `camera_shake`.
 
 use std::collections::HashMap;
 
@@ -76,17 +19,13 @@ use crate::Chain;
 const CAMERA_SHAKES: &str = "DBFilesClient\\CameraShakes.dbc";
 const SPELL_EFFECT_CAMERA_SHAKES: &str = "DBFilesClient\\SpellEffectCameraShakes.dbc";
 
-/// One `CameraShakes.dbc` row — the authored shape of a shake, in the table's own units.
-///
-/// Every field below `id` is data as shipped; see the module doc for what is verified (the layout
-/// and the family split) and what still awaits the reference (the evaluator's reading of them).
+/// One `CameraShakes.dbc` row: a shake's authored shape, in the table's own units.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct CameraShake {
     pub id: u32,
-    /// `ShakeType` — 0 or 1 across the shipped table; every creature row is `1`.
+    /// `ShakeType`: 0 or 1 as shipped; every creature row is 1.
     pub shake_type: u32,
-    /// `Direction` — 0·1·2, running consistently across the spell rows' triples; every creature
-    /// row is `2`.
+    /// `Direction`: 0, 1 or 2, one per member of a spell-side triple; every creature row is 2.
     pub direction: u32,
     pub amplitude: f32,
     pub frequency: f32,
@@ -96,32 +35,25 @@ pub struct CameraShake {
     pub coefficient: f32,
 }
 
-/// One `SpellEffectCameraShakes.dbc` row — **up to three [`CameraShake`] ids fired at one point**.
-///
-/// This is the id space every *spell-side* producer speaks: `SpellVisualKit` field 14 and the
-/// `$SHK` animation event both name a **group**, never a preset. Zero is the empty slot; the
-/// reference walks the three in order and skips them (`edi = 3`, `0x6ecb40`).
+/// One `SpellEffectCameraShakes.dbc` row: up to three [`CameraShake`] ids fired at one point. The
+/// reference walks the three slots in order and skips a zero (`0x6ecb40`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SpellShakeGroup {
     pub id: u32,
-    /// The three slots as shipped, zeros included — iterate with [`Self::shakes`].
+    /// As shipped, zeros included; [`Self::shakes`] skips them.
     pub slots: [u32; 3],
 }
 
 impl SpellShakeGroup {
-    /// The populated slots, in the reference's walk order. A group can name the same preset twice
-    /// (group 4 is `15 · 14 · 15`); the duplicate is kept here and loses the evaluator's tie-break.
+    /// The populated slots in walk order. A duplicate (group 4 is `15, 14, 15`) is kept: the slots
+    /// are slots, not axes, and it loses the evaluator's strict `>` tie-break.
     pub fn shakes(&self) -> impl Iterator<Item = u32> + '_ {
         self.slots.iter().copied().filter(|&id| id != 0)
     }
 }
 
-/// The camera-shake tables: `CameraShakes.dbc` keyed by row id, and the
-/// `SpellEffectCameraShakes.dbc` groups that index it — **two id spaces, never conflated**
-/// (the same per-table split [`crate::SpellVisualCatalog`] keeps).
-///
-/// `Default` is the **empty** catalog — the same thing "the DBC failed to load" already means to
-/// every consumer (every lookup misses and the caller takes its documented fallback).
+/// Both camera-shake tables, presets and groups each keyed by their own id. `Default` is the empty
+/// catalog, which is what a failed load means to every consumer.
 #[derive(Default)]
 pub struct CameraShakeCatalog {
     rows: HashMap<u32, CameraShake>,
@@ -129,8 +61,7 @@ pub struct CameraShakeCatalog {
 }
 
 impl CameraShakeCatalog {
-    /// One preset by id. `None` for id 0 (the "no shake" value both creature columns use) and for
-    /// any id the shipped table does not carry.
+    /// One preset by id; 0, the creature columns' "no shake", is never a row.
     pub fn get(&self, id: u32) -> Option<&CameraShake> {
         self.rows.get(&id)
     }
@@ -148,8 +79,7 @@ impl CameraShakeCatalog {
         self.rows.is_empty()
     }
 
-    /// One `SpellEffectCameraShakes.dbc` group by id — the spell side's whole lookup. `None` for
-    /// id 0 (the "no shake" value the kit column uses) and for any id the 9-row table lacks.
+    /// One group by id; 0, the kit column's "no shake", is never a row.
     pub fn group(&self, id: u32) -> Option<&SpellShakeGroup> {
         self.groups.get(&id)
     }
@@ -163,16 +93,14 @@ impl CameraShakeCatalog {
         self.groups.len()
     }
 
-    /// Seed one preset — for fixtures exercising the evaluator without a client install (the same
-    /// builder shape [`crate::SpellVisualCatalog::with_chain_effect`] uses). The live path is
-    /// [`load_camera_shakes`].
+    /// Seed one preset, for fixtures that run the evaluator without an install.
     #[must_use]
     pub fn with_row(mut self, row: CameraShake) -> Self {
         self.rows.insert(row.id, row);
         self
     }
 
-    /// Seed one group. See [`Self::with_row`].
+    /// Seed one group, for fixtures.
     #[must_use]
     pub fn with_group(mut self, group: SpellShakeGroup) -> Self {
         self.groups.insert(group.id, group);
@@ -205,12 +133,8 @@ fn spell_effect_camera_shakes_schema() -> Schema {
     s
 }
 
-/// Read both camera-shake tables off the patch chain.
-///
-/// `SpellEffectCameraShakes.dbc` is loaded beside `CameraShakes.dbc` rather than on demand: it is
-/// nine rows, it ships in the same archive, and every spell-side producer needs both to resolve a
-/// single shake. A missing or malformed table is a hard error like every other DBC (1300) — the
-/// caller's fallback is to run with no shake system at all, which is what an empty catalog means.
+/// Read both camera-shake tables off the patch chain. A missing or malformed table is an error;
+/// the caller's fallback is the empty catalog, no shakes at all.
 pub fn load_camera_shakes(chain: &mut Chain) -> Result<CameraShakeCatalog> {
     let bytes = chain
         .read_file(CAMERA_SHAKES)
@@ -259,11 +183,8 @@ pub fn load_camera_shakes(chain: &mut Chain) -> Result<CameraShakeCatalog> {
 mod tests {
     use std::collections::BTreeSet;
 
-    /// The nine shipped `SpellEffectCameraShakes.dbc` groups, verbatim — the id space every
-    /// spell-side producer speaks. Sparse ids (`…7, 26, 66`) and duplicate slots (group 4 lists
-    /// `15` twice, group 7 lists `18` twice) are both load-bearing: the sparseness is what makes a
-    /// wrong column map impossible to miss, and the duplicate is what proves the three slots are
-    /// **slots, not axes**.
+    /// The nine shipped groups, verbatim. The sparse ids expose a wrong column map; the duplicate
+    /// slots in groups 4 and 7 show the three are slots, not axes.
     #[test]
     fn the_spell_shake_groups_decode_as_shipped() {
         let data = crate::wow_data_or_skip!();
@@ -299,8 +220,7 @@ mod tests {
         );
     }
 
-    /// **The property that licenses the column map**: every id the group table names must land on a
-    /// real row of the 24-row preset table. A merely plausible map would dangle.
+    /// The check on the column map: a merely plausible one would leave group slots dangling.
     #[test]
     fn every_group_slot_resolves_to_a_preset() {
         let data = crate::wow_data_or_skip!();
@@ -318,8 +238,7 @@ mod tests {
             "the 18 presets the spell side reaches"
         );
 
-        // The census the module doc states: with the creature columns' {1,2,10} and
-        // {10,11,12,38}, three shipped rows are named by NEITHER table.
+        // The footstep column names {1, 2, 10} and the thud column {10, 11, 12, 38}.
         let creature: BTreeSet<u32> = [1, 2, 10, 11, 12, 38].into_iter().collect();
         let all: BTreeSet<u32> = cat.iter().map(|r| r.id).collect();
         let unreached: Vec<u32> = all.difference(&(&named | &creature)).copied().collect();
diff --git a/crates/benilla-formats/src/chain.rs b/crates/benilla-formats/src/chain.rs
index 4b5d0e6d..980900b1 100644
--- a/crates/benilla-formats/src/chain.rs
+++ b/crates/benilla-formats/src/chain.rs
@@ -1,16 +1,6 @@
-//! The vanilla patch chain — a priority-ordered set of MPQ archives, read through `benilla-mpq`.
-//!
-//! Replaces `wow-mpq`'s `PatchChain` *and* the old `ChainReader` (decision 0021). Those were two types
-//! because `wow-mpq`'s `Archive::open` re-parsed the hash/block (and the useless `(attributes)`) tables
-//! on every open, so `ChainReader` bolted a `Mutex<HashMap<…, Archive>>` handle-cache on top to avoid
-//! re-paying that per read. `benilla_mpq::Archive` now caches its parsed tables in an `Arc` and reads
-//! `&self` (a fresh OS handle per read, no seek-state sharing), so the cache is gone and one `Chain`
-//! serves both the `&self` concurrent Bevy `AssetReader` path and the `&mut` streaming-loader path.
-//!
-//! Later archives override earlier ones for files sharing an internal path (so a patch archive
-//! wins); a read resolves a name to the highest-priority archive that holds it. Base content
-//! archives carry no `(listfile)`, so resolution is by name **hash**, which works without one.
-//! Which archives mount, and in what order, is [`mount_order`]'s law (decision 1300).
+//! The vanilla patch chain: a priority-ordered set of MPQ archives, read through `benilla-mpq`. A
+//! read resolves a name to the highest-priority archive holding it, so a patch wins; base archives
+//! carry no `(listfile)`, so resolution is by name hash.
 
 use std::collections::HashSet;
 use std::path::Path;
@@ -28,13 +18,12 @@ pub struct ChainEntry {
 
 /// A priority-ordered patch chain of MPQ archives (`Send + Sync`; reads are `&self` and lock-free).
 pub struct Chain {
-    /// Ascending priority — later archives win. `resolve` scans back-to-front.
+    /// Ascending priority: later archives win.
     archives: Vec<Archive>,
 }
 
-/// `patch-?.MPQ` with the reference's FindFirstFileW semantics: `?` matches **exactly one**
-/// character, case-insensitively — `patch-3.MPQ` mounts, `patch-10.MPQ` does not (VERIFIED at the
-/// glob template `0x82edbc` and its wrapper `0x42ad10`; wow-re `patch-mount-order.md`).
+/// `patch-?.MPQ` as the reference's `FindFirstFileW` glob matches it (template `0x82edbc`, wrapper
+/// `0x42ad10`): `?` is exactly one character, any case, so `patch-10.MPQ` never mounts.
 fn is_patch_glob_match(name: &str) -> bool {
     let lower = name.to_ascii_lowercase();
     let Some(mid) = lower
@@ -46,14 +35,10 @@ fn is_patch_glob_match(name: &str) -> bool {
     mid.chars().count() == 1
 }
 
-/// The vanilla mount law over a `Data` directory listing, **ascending priority** (decision 1300;
-/// the mounter `0x403740`, carved in wow-re `system/mpq/scratch/patch-mount-order.md`): the ten
-/// [`VANILLA_BASE_ORDER`] archives at their fixed priorities, then `patch.MPQ`, then every
-/// `patch-?.MPQ` sorted ascending by case-folded name — the binary sorts its glob matches
-/// *descending* (`strnicmp`) and walks the array backwards, so the order is deterministic, never
-/// filesystem enumeration; `patch-3` overrides `patch-2` — then `speech2.MPQ` above every patch.
-/// Names are matched case-insensitively (the reference runs on a case-insensitive filesystem) and
-/// returned as found on disk; absent archives are simply not in the result.
+/// The reference's mount order over a `Data` listing, ascending priority (`0x403740`): the ten
+/// [`VANILLA_BASE_ORDER`] archives, `patch.MPQ`, every `patch-?.MPQ` by case-folded name (the
+/// reference sorts descending with `strnicmp` and walks backwards), then `speech2.MPQ`. Names
+/// match case-insensitively and come back as found on disk.
 fn mount_order(dir_names: &[String]) -> Vec<String> {
     let find = |want: &str| {
         dir_names
@@ -75,13 +60,11 @@ fn mount_order(dir_names: &[String]) -> Vec<String> {
 }
 
 impl Chain {
-    /// Open a chain from a vanilla `Data` directory (every archive [`mount_order`] finds in it,
-    /// lowest priority first) or a single `.MPQ` file (just that archive).
+    /// Open a `Data` directory's archives in [`mount_order`], or a single `.MPQ` file.
     ///
-    /// An archive that exists but fails to open is a hard error, deliberately: the reference logs
-    /// `"Failed to open archive"` and continues, but a silent skip turns a corrupt `dbc.MPQ` — or a
-    /// modder's malformed `patch-3.MPQ` — into cryptic missing-file failures far downstream. Same
-    /// composite on a healthy install; a clear error instead of a quirk on a broken one (1300).
+    /// Deviation: an archive that fails to open is an error, where the reference logs
+    /// `"Failed to open archive"` and goes on, because a skipped corrupt archive surfaces only as
+    /// missing files far downstream.
     pub fn open(path: &Path) -> Result<Self> {
         let mut archives = Vec::new();
         if path.is_dir() {
@@ -113,34 +96,29 @@ impl Chain {
         Ok(Self { archives })
     }
 
-    /// The highest-priority archive with an *entry* for `name` (readable file **or** delete-marker),
-    /// if any. Stops at the winning archive — including a tombstone, which correctly shadows any
-    /// lower-priority copy (decision 0246). Callers that want "readable" must check
-    /// [`Archive::is_delete_marker`].
+    /// The highest-priority archive with an entry for `name`, a delete marker included, as a
+    /// tombstone shadows every lower copy: check [`Archive::is_delete_marker`] for a readable file.
     fn resolve(&self, name: &str) -> Option<&Archive> {
         self.archives.iter().rev().find(|a| a.contains(name))
     }
 
-    /// Whether the chain holds `name` as a **readable** file (accepts `/` or `\`; case-insensitive).
-    /// A path whose winning entry is a delete-marker is *not* present — the client deleted it (0246).
+    /// Whether `name` (`/` or `\`, any case) is a readable file, not a delete marker.
     pub fn contains(&self, name: &str) -> bool {
         self.resolve(name)
             .is_some_and(|a| !a.is_delete_marker(name))
     }
 
-    /// The path of the archive `name` resolves to (the winning override) — for debugging / extract.
+    /// The path of the archive `name` resolves to, for debugging and extraction.
     pub fn find_file_archive(&self, name: &str) -> Option<&Path> {
         self.resolve(name).map(|a| a.path())
     }
 
-    /// Read a file by internal path (accepts `/` or `\`), from its winning archive. `&self`: safe to
-    /// call concurrently (the Bevy `AssetReader` does).
+    /// Read a file by internal path (`/` or `\`) from its winning archive.
     pub fn read(&self, name: &str) -> Result<Vec<u8>> {
         let archive = self
             .resolve(name)
             .ok_or_else(|| anyhow!("file not in patch chain: {name}"))?;
-        // A tombstone shadows every lower copy: the path is deleted from the composite, so this is a
-        // clean "not found", not a fall-through to a stale base version (decision 0246).
+        // A tombstone deletes the path from the composite: not found, never a stale lower copy.
         if archive.is_delete_marker(name) {
             bail!(
                 "file deleted from patch chain: {name} (tombstoned by {})",
@@ -152,19 +130,14 @@ impl Chain {
             .with_context(|| format!("reading {name} from {}", archive.path().display()))
     }
 
-    /// `&mut` alias of [`Chain::read`] — kept so the streaming-loader call sites that thread a
-    /// `&mut Chain` read exactly as they did against `wow-mpq`'s `PatchChain`.
+    /// `&mut` alias of [`Chain::read`] for call sites that thread a `&mut Chain`.
     pub fn read_file(&mut self, name: &str) -> Result<Vec<u8>> {
         self.read(name)
     }
 
-    /// List the chain's named files with sizes. Dev/extract use only — files absent from every
-    /// listfile (most of `texture.MPQ`) are reachable by name but not enumerated.
-    ///
-    /// Unions the `(listfile)` of **every** archive that carries one: each archive's listfile names
-    /// only the files *it* holds, so resolving `(listfile)` like an ordinary overridden file (as this
-    /// used to) returns just the top patch archive's sliver — 92 names from `patch-2.MPQ` instead of
-    /// the chain's ~86k. Sizes still resolve per-name to the winning archive.
+    /// The chain's named files with sizes, for development and extraction; a file in no listfile
+    /// (most of `texture.MPQ`) is readable by name but not listed. Unions every archive's
+    /// `(listfile)`, as each names only its own files; sizes come from the winning archive.
     pub fn list(&self) -> Result<Vec<ChainEntry>> {
         let mut seen = HashSet::new();
         let mut out = Vec::new();
@@ -174,12 +147,12 @@ impl Chain {
             };
             for raw in String::from_utf8_lossy(&listfile).split([';', '\r', '\n']) {
                 let name = raw.trim();
-                // Dedupe across archives the way MPQ hashing compares names: case-insensitive, `/`≡`\`.
+                // Dedupe the way MPQ hashing compares names: any case, `/` and `\` alike.
                 if name.is_empty() || !seen.insert(name.replace('/', "\\").to_ascii_lowercase()) {
                     continue;
                 }
                 if let Some(a) = self.resolve(name) {
-                    // A tombstoned path isn't a file in the composite — don't list it (0246).
+                    // A tombstoned path is not a file in the composite.
                     if a.is_delete_marker(name) {
                         continue;
                     }
@@ -207,11 +180,9 @@ mod tests {
         assert!(is_patch_glob_match("patch-2.MPQ"));
         assert!(is_patch_glob_match("patch-3.MPQ"));
         assert!(is_patch_glob_match("PATCH-A.mpq"));
-        // Zero or two-plus characters: FindFirstFileW's `?` is exactly one.
         assert!(!is_patch_glob_match("patch-.MPQ"));
         assert!(!is_patch_glob_match("patch-10.MPQ"));
         assert!(!is_patch_glob_match("patch-33.MPQ"));
-        // Not the glob's shape at all.
         assert!(!is_patch_glob_match("patch.MPQ"));
         assert!(!is_patch_glob_match("patch-2.MPQ.bak"));
         assert!(!is_patch_glob_match("mypatch-2.MPQ"));
@@ -219,8 +190,7 @@ mod tests {
 
     #[test]
     fn mount_order_is_the_carved_law() {
-        // A shuffled install with a custom patch, plus files the mounter must ignore:
-        // base.MPQ (telemetry-only in the reference), backup.MPQ, loose non-archives.
+        // base.MPQ is telemetry-only in the reference and never mounts.
         let dir = owned(&[
             "patch-2.MPQ",
             "backup.MPQ",
@@ -249,8 +219,6 @@ mod tests {
 
     #[test]
     fn patch_sort_is_ascending_and_case_folded() {
-        // Later wins in `Chain`, so ascending case-folded order makes patch-3 override patch-2
-        // and `patch-B` override `patch-a` ('a' < 'b' after the strnicmp-style fold).
         let dir = owned(&["patch-B.MPQ", "patch-3.MPQ", "patch-a.MPQ", "patch-2.MPQ"]);
         assert_eq!(
             mount_order(&dir),
diff --git a/crates/benilla-formats/src/characters/customization.rs b/crates/benilla-formats/src/characters/customization.rs
index 8a067c64..f420ef5b 100644
--- a/crates/benilla-formats/src/characters/customization.rs
+++ b/crates/benilla-formats/src/characters/customization.rs
@@ -1,24 +1,9 @@
-//! Character-creation source data (decision 0423): the per-race body displayIds (ChrRaces), the
-//! race/class combos (CharBaseInfo), and the five appearance-dial *ranges* per (race, sex) derived
-//! from CharSections + CharHairGeosets + CharacterFacialHairStyles.
-//!
-//! **The ranges are data-derived, never hardcoded** (the RF-0071/73/74 grid law). Each dial cycles
-//! index `0..count-1`; the counts come from:
-//! - **skin color** = distinct `ColorIndex` of CharSections `SECTION_SKIN` (variation 0) for (race, sex);
-//! - **face** = distinct `VariationIndex` of `SECTION_FACE`;
-//! - **hair style** = distinct `VariationID` of **CharHairGeosets** for (race, sex), `max(1, …)` (the
-//!   client's `0x478540` count fetcher — bald is style 0);
-//! - **hair color** = distinct `ColorIndex` of `SECTION_HAIR`;
-//! - **facial hair** = distinct `VariationID` of **CharacterFacialHairStyles** for (race, sex).
-//!
-//! By construction every `(skin, face, hairStyle, hairColor, facialHair)` tuple in the product of a
-//! (race, sex)'s ranges passes vmangos's `Player::ValidateAppearance` — the server checks, in order,
-//! that CharSections rows exist for `SKIN(0, skin)`, `FACE(face, skin)` (face is keyed by *skinColor*),
-//! `HAIR(hairStyle, hairColor)`, and — unless the (race, sex) is facial-hair-excluded (Tauren, or a
-//! female that isn't Night Elf / Undead) — `FACIAL_HAIR(facialHair, hairColor)`, plus a
-//! CharacterFacialHairStyles row for `facialHair`. The real 5875 grids are *complete* over each
-//! coupled pair, so the independent per-dial counts never produce an invalid tuple — asserted
-//! exhaustively against the transcribed predicate in the real-data test.
+//! Character-creation source data from ChrRaces, CharBaseInfo and CharStartOutfit, and the five
+//! appearance-dial ranges per (race, sex), counted from the DBCs: skin colour, face and hair colour
+//! off the CharSections rows the client groups into its grid (`0x476020`), hair and facial-hair
+//! styles off CharHairGeosets and CharacterFacialHairStyles. Every tuple in a (race, sex)'s ranges
+//! passes vmangos's `Player::ValidateAppearance`, since the shipped grids are complete over each
+//! coupled pair.
 
 use std::collections::{HashMap, HashSet};
 
@@ -35,10 +20,7 @@ const CHAR_HAIR_GEOSETS: &str = "DBFilesClient\\CharHairGeosets.dbc";
 const CHAR_FACIAL_HAIR_STYLES: &str = "DBFilesClient\\CharacterFacialHairStyles.dbc";
 const CHAR_SECTIONS: &str = "DBFilesClient\\CharSections.dbc";
 
-// CharSections `SectionType` values the range derivation reads (wow-re RF-0074; the same constants
-// `sections.rs` uses — kept local so the two concerns don't couple). `SECTION_FACIAL_HAIR` (2) isn't
-// here: the facial-hair *count* comes from CharacterFacialHairStyles, not CharSections (the test's
-// ValidateAppearance transcription defines it there, where it's used).
+// CharSections `SectionType` values the dial ranges read (hair is 3 at `0x4784c0`).
 const SECTION_SKIN: u8 = 0;
 const SECTION_FACE: u8 = 1;
 const SECTION_HAIR: u8 = 3;
@@ -46,12 +28,10 @@ const SECTION_HAIR: u8 = 3;
 /// A CharSections availability key: `(race, sex, sectionType, variation, color)`.
 type SectionKey = (u8, u8, u8, u8, u8);
 
-/// The 8 playable races (ChrRaces ids 1–8); higher rows (Goblin = 9) aren't character-creatable.
+/// The playable races, ChrRaces ids 1–8; Goblin (9) and above are not creatable.
 const PLAYABLE_RACES: [u8; 8] = [1, 2, 3, 4, 5, 6, 7, 8];
 
-/// The 8 playable races' ChrRaces client fileStrings (col 15), a **frozen fact** of the build — the
-/// load-time misparse guard for the string-column positions in [`load_races`] (if col 15 drifted,
-/// these wouldn't match), and the GlueStrings key stems (`RACE_INFO_SCOURGE`, not `…_UNDEAD`).
+/// The shipped ChrRaces fileStrings (col 15), guarding [`load_races`]' string columns.
 const KNOWN_FILES: [(u8, &str); 8] = [
     (1, "Human"),
     (2, "Orc"),
@@ -63,15 +43,12 @@ const KNOWN_FILES: [(u8, &str); 8] = [
     (8, "Troll"),
 ];
 
-/// The **raw** 1.12 `CharBaseInfo` content, race → classes (a frozen fact of the file; class ids:
-/// Warrior 1, Paladin 2, Hunter 3, Rogue 4, Priest 5, Shaman 7, Mage 8, Warlock 9, Druid 11). Used
-/// only as the load-time misparse guard (proves the 2-byte parse landed) — note it is NOT the
-/// playable set: the file carries one dead pair, Dwarf-Mage, which the real client never offers
-/// (see [`UNUSED_COMBOS`]).
+/// The shipped `CharBaseInfo` rows by race, the load-time guard on the 2-byte parse; not the
+/// playable set, as it holds the dead Dwarf-Mage row ([`UNUSED_COMBOS`]).
 const KNOWN_COMBOS: [(u8, &[u8]); 8] = [
     (1, &[1, 2, 4, 5, 8, 9]), // Human
     (2, &[1, 3, 4, 7, 9]),    // Orc
-    (3, &[1, 2, 3, 4, 5, 8]), // Dwarf — 8 (Mage) is the dead row, stripped after the guard
+    (3, &[1, 2, 3, 4, 5, 8]), // Dwarf; 8 (Mage) is the dead row
     (4, &[1, 3, 4, 5, 11]),   // Night Elf
     (5, &[1, 4, 5, 8, 9]),    // Undead
     (6, &[1, 3, 7, 11]),      // Tauren
@@ -79,19 +56,11 @@ const KNOWN_COMBOS: [(u8, &[u8]); 8] = [
     (8, &[1, 3, 4, 5, 7, 8]), // Troll
 ];
 
-/// The `CharBaseInfo` pairs the real client never offers on the create screen — leftovers in the
-/// data, not creatable content. Dwarf-Mage (3, 8) sits fully populated in both CharBaseInfo *and*
-/// CharStartOutfit, yet the real client hardcodes the skip: its class-list builder (`0x4706b0`)
-/// iterates CharBaseInfo and drops rows matching the literal `race == 3 && class == 8` — two x86
-/// immediates, the only such pair binary-wide, byte-confirmed by wow-5875-re §5 (decisions
-/// 0549/0550). Stripped here right after the raw-parse guard — the same mechanism, one layer down —
-/// so `allows`/`classes_for_race` answer what the real client offers.
+/// `CharBaseInfo` pairs the client never offers: its class-list builder `0x4706b0` skips the
+/// literal `race == 3 && class == 8` (Dwarf-Mage), though the row and its outfit are populated.
 const UNUSED_COMBOS: [(u8, u8); 1] = [(3, 8)];
 
-/// One renderable item of a class's level-1 starting outfit (CharStartOutfit.dbc, decision 0527):
-/// the item's **ItemDisplayInfo** id — the same kind of id the char-enum equipment carries, so it
-/// feeds the equipment pipeline directly with no Item.dbc/template hop — and its InventoryType (the
-/// worn slot). Non-worn entries (bags, food, hearthstone — InventoryType 0) are dropped at load.
+/// One worn item of a CharStartOutfit row: its ItemDisplayInfo id and its InventoryType.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct StartOutfitItem {
     pub display_id: u32,
@@ -108,66 +77,53 @@ pub struct DialRanges {
     pub facial_hair: u8,
 }
 
-/// Character-creation source data: race body displayIds, race/class combos, and per-(race, sex)
-/// appearance-dial ranges. Loaded once from the DBCs ([`Self::load`]).
+/// Character-creation source data, loaded once from the DBCs ([`Self::load`]).
 pub struct CharCreateCatalog {
     /// race → (male displayId, female displayId), from ChrRaces cols 4/5.
     displays: HashMap<u8, (u32, u32)>,
-    /// race → the ChrRaces client fileString (col 15: `"Human"`, `"Scourge"`, …) — the stem the glue
-    /// screens key GlueStrings entries on (`RACE_INFO_<FILE>`, `ABILITY_INFO_<FILE><n>`).
+    /// race → ChrRaces fileString (col 15), the GlueStrings key stem (`RACE_INFO_<FILE>`).
     files: HashMap<u8, String>,
-    /// race → (facial-hair customization token per sex [male, female] — cols 26/27 — and the hair
-    /// customization token — col 28). The glue tokens behind the per-race dial labels
-    /// (`HAIR_<tok>_STYLE`, `FACIAL_HAIR_<tok>`); a facial token of `"NONE"` hides that dial.
+    /// race → ([male, female] facial-hair token, cols 26/27; hair token, col 28).
     custom_tokens: HashMap<u8, ([String; 2], String)>,
-    /// The (race, class) combos CharBaseInfo permits.
     combos: HashSet<(u8, u8)>,
-    /// (race, sex) → the five dial counts.
     ranges: HashMap<(u8, u8), DialRanges>,
-    /// (race, class, sex) → the level-1 starting-outfit items the create preview dresses in
-    /// (CharStartOutfit, decision 0527) — worn slots only, DisplayId + InventoryType.
+    /// (race, class, sex) → the worn starting-outfit items.
     start_outfits: HashMap<(u8, u8, u8), Vec<StartOutfitItem>>,
 }
 
 impl CharCreateCatalog {
-    /// The body model displayId for a (race, sex) — resolved through the ordinary CreatureDisplayInfo
-    /// chain, the same as any streamed unit (decision 0041). `None` for a non-playable race.
+    /// The body displayId for a (race, sex), resolved through CreatureDisplayInfo like any unit.
     pub fn body_display(&self, race: u8, sex: u8) -> Option<u32> {
         self.displays
             .get(&race)
             .map(|&(m, f)| if sex == 0 { m } else { f })
     }
 
-    /// Whether a race may be created as a class (CharBaseInfo).
+    /// Whether a race may be created as a class (CharBaseInfo less `UNUSED_COMBOS`).
     pub fn allows(&self, race: u8, class: u8) -> bool {
         self.combos.contains(&(race, class))
     }
 
-    /// The ChrRaces client fileString for a race (`"Human"`, `"Scourge"`, …) — the GlueStrings key
-    /// stem. `None` for a non-playable race.
+    /// The ChrRaces fileString for a race (`"Human"`, `"Scourge"`), the GlueStrings key stem.
     pub fn race_file(&self, race: u8) -> Option<&str> {
         self.files.get(&race).map(String::as_str)
     }
 
-    /// The hair-customization glue token for a race (`"NORMAL"`, `"HORNS"`) — the dial-label key
-    /// (`HAIR_<tok>_STYLE` / `HAIR_<tok>_COLOR`).
+    /// A race's hair glue token (`"NORMAL"`, `"HORNS"`), keying `HAIR_<tok>_STYLE`/`_COLOR`.
     pub fn hair_customization(&self, race: u8) -> Option<&str> {
         self.custom_tokens.get(&race).map(|(_, h)| h.as_str())
     }
 
-    /// The facial-hair-customization glue token for a (race, sex) (`"NORMAL"`, `"MARKINGS"`, …) —
-    /// the dial-label key (`FACIAL_HAIR_<tok>`); `"NONE"` means the dial is hidden (the ref's
-    /// `GetFacialHairCustomization() == "NONE"` branch).
+    /// A (race, sex)'s facial-hair glue token, keying `FACIAL_HAIR_<tok>`; the glue hides the dial
+    /// when `GetFacialHairCustomization()` is `"NONE"`.
     pub fn facial_hair_customization(&self, race: u8, sex: u8) -> Option<&str> {
         self.custom_tokens
             .get(&race)
             .map(|(f, _)| f[(sex as usize).min(1)].as_str())
     }
 
-    /// The classes a race may be created as, ascending by class id. The real client's grid order is
-    /// CharBaseInfo *row* order (its builder `0x4706b0` walks the table, decision 0550) — which in
-    /// the 5875 file is ascending class id for all 8 races (verified byte fact), so the sort here is
-    /// order-equivalent on the real data.
+    /// The classes a race may be created as, ascending by id: the client lists them in CharBaseInfo
+    /// row order (`0x4706b0`), which is ascending class id in the shipped file.
     pub fn classes_for_race(&self, race: u8) -> Vec<u8> {
         let mut cs: Vec<u8> = self
             .combos
@@ -179,24 +135,20 @@ impl CharCreateCatalog {
         cs
     }
 
-    /// The five appearance-dial counts for a (race, sex). `None` for a non-playable race.
+    /// The five appearance-dial counts for a (race, sex).
     pub fn ranges(&self, race: u8, sex: u8) -> Option<DialRanges> {
         self.ranges.get(&(race, sex)).copied()
     }
 
-    /// The renderable starting-outfit items for a (race, class, sex) — the level-1 gear the create
-    /// screen dresses the preview in (decision 0527). Empty for a combo with no CharStartOutfit row.
+    /// The worn level-1 gear the create preview dresses a (race, class, sex) in.
     pub fn start_outfit(&self, race: u8, class: u8, sex: u8) -> &[StartOutfitItem] {
         self.start_outfits
             .get(&(race, class, sex))
             .map_or(&[], Vec::as_slice)
     }
 
-    /// Load the character-creation catalog from the patch chain (ChrRaces + CharBaseInfo +
-    /// CharSections + CharHairGeosets + CharacterFacialHairStyles). Two load-time self-checks fail
-    /// loudly on a misparse: the parsed combos must equal the frozen 1.12 table (guards the 2-byte
-    /// CharBaseInfo layout), and every playable (race, sex) must have a body display + all five
-    /// ranges nonzero.
+    /// Load the catalog from the patch chain. The misparse guards compare the raw combos, so they
+    /// run before `UNUSED_COMBOS` are stripped.
     pub fn load(chain: &mut Chain) -> Result<Self> {
         let (displays, files, custom_tokens) = load_races(chain)?;
         let combos = load_combos(chain)?;
@@ -230,7 +182,6 @@ impl CharCreateCatalog {
         Ok(catalog)
     }
 
-    /// Load-time misparse guards (see [`Self::load`]).
     fn self_check(&self) -> Result<()> {
         for (race, classes) in KNOWN_COMBOS {
             let got = self.classes_for_race(race);
@@ -250,12 +201,8 @@ impl CharCreateCatalog {
                 );
             }
         }
-        // CharStartOutfit byte-layout guard (like the CharBaseInfo one): Human(1) Warrior(1) male(0)
-        // wears the recruit set — shirt disp 9891 (inv 4/BODY), pants 9892 (7/LEGS), boots 10141
-        // (8/FEET), plus the worn shortsword 1542 (21/MAINHAND) and small shield 18730 (14/SHIELD).
-        // If the packed race/class/gender head or the DisplayId/InventoryType array offsets drifted,
-        // these (display, inv) pairs wouldn't line up. Bags/food (InventoryType 0) are dropped, so
-        // the count is exactly these five worn items.
+        // CharStartOutfit layout guard: the shipped Human Warrior male set, (display,
+        // InventoryType) for the shirt, pants, boots, shortsword and shield.
         let hw = self.start_outfit(1, 1, 0);
         for &(disp, inv) in &[
             (9891u32, 4u8),
@@ -301,12 +248,8 @@ impl CharCreateCatalog {
     }
 }
 
-/// ChrRaces → per playable race: the (male, female) displayIds, the client fileString, and the glue
-/// customization tokens. 29 fields in build 5875 (record size 116); we read cols 0 (RaceID),
-/// 4 (MaleDisplayId), 5 (FemaleDisplayId), 15 (ClientFileString), 26/27 (FacialHairCustomization
-/// male/female) and 28 (HairCustomization) — the rest (name strings + spell/sound ids) are declared
-/// `UInt32` (a string column is a 4-byte offset, read and ignored). The string-column positions are
-/// guarded by [`CharCreateCatalog::self_check`]'s frozen fileString table.
+/// ChrRaces (29 fields, 116-byte records) → per playable race: displayIds (cols 4/5), fileString
+/// (15), facial-hair (26/27) and hair (28) tokens; other string columns are read as ignored `u32`s.
 #[allow(clippy::type_complexity)] // one pass over one DBC → the catalog's three race-keyed maps
 fn load_races(
     chain: &mut Chain,
@@ -351,10 +294,7 @@ fn load_races(
     Ok((displays, files, tokens))
 }
 
-/// CharBaseInfo → the (race, class) combos. A **special** DBC: 2 columns of **one byte each**
-/// (record size 2, not 8), so the generic 4-byte-field reader can't touch it — parsed by hand off the
-/// raw record block. Byte 0 = RaceID, byte 1 = ClassID (verified against the 5875 file + the known
-/// combo table).
+/// CharBaseInfo → (race, class) pairs: two one-byte fields, parsed by hand off the record block.
 fn load_combos(chain: &mut Chain) -> Result<HashSet<(u8, u8)>> {
     let bytes = chain
         .read_file(CHAR_BASE_INFO)
@@ -380,15 +320,9 @@ fn load_combos(chain: &mut Chain) -> Result<HashSet<(u8, u8)>> {
     Ok(combos)
 }
 
-/// CharStartOutfit → (race, class, sex) → the worn starting items. A **special** DBC (like
-/// CharBaseInfo): 41 columns / 152 bytes with a byte-packed race/class/gender/unused head, so the
-/// generic 4-byte-field reader can't touch it — parsed by hand off the raw record block. Layout,
-/// byte-verified against the 5875 file: `ID` u32 @0; `Race`/`Class`/`Gender`/unused u8 @4/5/6/7;
-/// `ItemId[12]` i32 @8 (dropped — we render by display); **`DisplayId[12]` i32 @56**;
-/// **`InventoryType[12]` i32 @104**. Each row keeps the (DisplayId, InventoryType) pair of every
-/// **worn** slot (both ≥ 1 — this drops the empty `-1` tail and the InventoryType-0 bag/food/hearth
-/// entries, which never render). DisplayId is already an ItemDisplayInfo id (the char-enum
-/// equipment convention), so it feeds the equipment pipeline with no template hop.
+/// CharStartOutfit → (race, class, sex) → worn items, parsed by hand (41 fields, 152 bytes): `ID`
+/// u32 @0, race/class/gender u8 @4/5/6, `ItemId[12]` @8, `DisplayId[12]` @56, `InventoryType[12]`
+/// @104. A slot is kept when both are ≥ 1, dropping the `-1` tail and the InventoryType-0 bags.
 fn load_start_outfits(chain: &mut Chain) -> Result<HashMap<(u8, u8, u8), Vec<StartOutfitItem>>> {
     let bytes = chain
         .read_file(CHAR_START_OUTFIT)
@@ -431,10 +365,8 @@ fn load_start_outfits(chain: &mut Chain) -> Result<HashMap<(u8, u8, u8), Vec<Sta
     Ok(map)
 }
 
-/// CharSections → the set of *available* `(race, sex, sectionType, variation, color)` keys — the rows
-/// a player may select (`Flags & 0x1 == 0`; the `0x1`-flagged rows are `SECTION_FLAG_UNAVAILABLE`,
-/// the late `…_100` extras the compositor already skips). This is exactly the domain vmangos's
-/// `GetCharSectionEntry` searches, so range derivation + validation read the same predicate.
+/// CharSections → the selectable keys, rows without flag `0x1` (`SECTION_FLAG_UNAVAILABLE`): the
+/// domain vmangos's `GetCharSectionEntry` searches.
 fn load_available_sections(chain: &mut Chain) -> Result<HashSet<SectionKey>> {
     let bytes = chain
         .read_file(CHAR_SECTIONS)
@@ -459,8 +391,7 @@ fn load_available_sections(chain: &mut Chain) -> Result<HashSet<SectionKey>> {
     Ok(avail)
 }
 
-/// CharHairGeosets → (race, sex) → the set of hair-style `VariationID`s. 6 fields (ID, Race, Sex,
-/// Variation, GeosetID, unused); we key on cols 1/2/3 (wow-re RF-0073).
+/// CharHairGeosets → (race, sex) → hair-style variations, keyed on cols 1/2/3 as `0x478540` does.
 fn load_hair_geosets(chain: &mut Chain) -> Result<HashMap<(u8, u8), HashSet<u8>>> {
     let bytes = chain
         .read_file(CHAR_HAIR_GEOSETS)
@@ -481,8 +412,7 @@ fn load_hair_geosets(chain: &mut Chain) -> Result<HashMap<(u8, u8), HashSet<u8>>
     Ok(map)
 }
 
-/// CharacterFacialHairStyles → (race, sex) → the set of facial-hair `VariationID`s. 9 fields; the
-/// keys are cols 0/1/2 (Race, Sex, Variation — wow-re RF-0073, note col 0 is Race here, not an ID).
+/// CharacterFacialHairStyles → (race, sex) → variations, keyed on cols 0/1/2 as `0x478740` does.
 fn load_facial_hair_styles(chain: &mut Chain) -> Result<HashMap<(u8, u8), HashSet<u8>>> {
     let bytes = chain
         .read_file(CHAR_FACIAL_HAIR_STYLES)
@@ -519,7 +449,6 @@ fn section_axis_count(
         .len() as u8
 }
 
-/// Derive the five dial counts for a (race, sex) from the section domain + the two geoset tables.
 fn derive_ranges(
     race: u8,
     sex: u8,
@@ -530,9 +459,8 @@ fn derive_ranges(
     DialRanges {
         skin: section_axis_count(avail, race, sex, SECTION_SKIN, false),
         face: section_axis_count(avail, race, sex, SECTION_FACE, true),
-        // The hair-style count is the client's CharHairGeosets fetcher (`max(1, …)` — a race/sex with
-        // no rows still has the bald style), NOT the CharSections HAIR variation count (Orc female has
-        // one extra HAIR variation with no geoset; offering it would be a dead style).
+        // Hair styles are CharHairGeosets variations, at least 1 (bald), not CharSections HAIR
+        // variations: Orc female has one HAIR variation with no geoset.
         hair_style: hair_geo
             .get(&(race, sex))
             .map_or(1, |v| v.len().max(1) as u8),
@@ -541,9 +469,7 @@ fn derive_ranges(
     }
 }
 
-/// A schema of `n` `UInt32` fields named `f0..fn` — for the DBCs we read purely by index (the field
-/// *names* are irrelevant; string columns are 4-byte offsets read as ints and ignored). The parser
-/// requires the count to match the file header, which is the alignment guard.
+/// `n` `UInt32` fields for a DBC read by index; the parser's field-count check guards the layout.
 fn all_u32_schema(name: &str, n: usize) -> Schema {
     let mut s = Schema::new(name);
     for i in 0..n {
@@ -556,13 +482,11 @@ fn all_u32_schema(name: &str, n: usize) -> Schema {
 mod tests {
     use super::*;
 
-    /// CharSections `SECTION_TYPE_FACIAL_HAIR` — used only by the predicate transcription (the runtime
-    /// facial-hair count comes from CharacterFacialHairStyles, so the lib never references it).
+    /// CharSections `SECTION_TYPE_FACIAL_HAIR`, needed only by the transcribed check.
     const SECTION_FACIAL_HAIR: u8 = 2;
 
-    /// vmangos's `Player::ValidateAppearance`, transcribed verbatim (`Player.cpp:326`): the exact
-    /// predicate the server runs on `CMSG_CHAR_CREATE`. `GetCharSectionEntry` is an available-row
-    /// lookup (`avail` already excludes the `0x1`-flagged rows), and face is keyed by *skinColor*.
+    /// vmangos's `Player::ValidateAppearance` (`Player.cpp:326`), run on `CMSG_CHAR_CREATE`;
+    /// `avail` already excludes the `0x1`-flagged rows, and face is keyed by skin colour.
     fn validate_appearance(
         avail: &HashSet<SectionKey>,
         facial: &HashMap<(u8, u8), HashSet<u8>>,
@@ -584,7 +508,7 @@ mod tests {
         if !has(SECTION_HAIR, hair, hair_color) {
             return false;
         }
-        // Tauren, and any female that isn't Night Elf (4) or Undead (5), have no FACIAL_HAIR sections.
+        // Tauren and all females but Night Elf (4) and Undead (5) have no FACIAL_HAIR sections.
         let excluded = race == 6 || (sex == 1 && race != 4 && race != 5);
         if !excluded && !has(SECTION_FACIAL_HAIR, facial_hair, hair_color) {
             return false;
@@ -594,10 +518,6 @@ mod tests {
             .is_some_and(|vs| vs.contains(&facial_hair))
     }
 
-    /// The whole Phase-2 contract on the **real** 5875 DBCs: the 16 body displayIds resolve to a
-    /// character body model; the parsed combos equal the frozen 1.12 table; the derived ranges are
-    /// dense `0..n-1` on every dial; and — the load-bearing guarantee — every tuple in the product of
-    /// a (race, sex)'s ranges passes the transcribed `ValidateAppearance`. Skips without client data.
     #[test]
     fn char_create_catalog_matches_the_5875_dbcs() {
         let data = crate::wow_data_or_skip!();
@@ -605,7 +525,6 @@ mod tests {
         let cat = CharCreateCatalog::load(&mut chain).expect("load char-create catalog");
         let creatures = crate::load_creature_catalog(&mut chain).expect("load creatures");
 
-        // 1 · The 16 body displayIds resolve through the CreatureDisplayInfo chain to a body model.
         for race in PLAYABLE_RACES {
             for sex in [0u8, 1] {
                 let display = cat.body_display(race, sex).expect("has display");
@@ -623,8 +542,7 @@ mod tests {
             }
         }
 
-        // 2 · The catalog answers the *playable* sets: the frozen raw table (guarded at load)
-        // minus the dead pairs the real client never offers (UNUSED_COMBOS — Dwarf-Mage).
+        // The playable sets are the raw table less the dead pairs.
         for (race, classes) in KNOWN_COMBOS {
             let playable: Vec<u8> = classes
                 .iter()
@@ -644,11 +562,8 @@ mod tests {
              CharBaseInfo row must not reach the create screen)"
         );
 
-        // 2b · The glue customization tokens land in the right columns (spot-checks pin both the
-        // column positions and the male/female order of cols 26/27 against the dumped 5875 rows:
-        // Tauren cycle horns, males normal facial hair, Human females piercings, Night Elf
-        // females markings, trolls tusks both sexes). Note: no 5875 row is "NONE" — every
-        // (race, sex) has a facial dial in this build.
+        // The glue tokens against the shipped rows, pinning cols 26/27's male/female order; no
+        // shipped row is "NONE".
         assert_eq!(cat.hair_customization(6), Some("HORNS"), "Tauren hair tok");
         assert_eq!(cat.hair_customization(1), Some("NORMAL"), "Human hair tok");
         assert_eq!(
@@ -672,11 +587,7 @@ mod tests {
             "Troll male facial tok"
         );
 
-        // 2c · CharStartOutfit (decision 0527): every creatable (race, class, sex) combo dresses
-        // in ≥1 worn item, and the InventoryType semantics land — the Human Warrior recruit set
-        // (guarded at load too) and the Human Mage's robe (InventoryType 20, chest column).
-        // (Creatable = the playable sets; the dead Dwarf-Mage pair also has a populated outfit
-        // row, but nothing can ever wear it.)
+        // Every creatable combo wears at least one item; the Human Mage wears a robe (inv 20).
         for (race, classes) in KNOWN_COMBOS {
             for &class in classes
                 .iter()
@@ -702,7 +613,7 @@ mod tests {
             "Human Mage male should wear a robe (inv 20, disp 12647): {mage:?}"
         );
 
-        // 3 + 4 · Ranges dense; every producible tuple passes ValidateAppearance.
+        // Every tuple in the dial ranges passes ValidateAppearance.
         let avail = load_available_sections(&mut chain).expect("sections");
         let facial = load_facial_hair_styles(&mut chain).expect("facial hair");
         for race in PLAYABLE_RACES {
diff --git a/crates/benilla-formats/src/characters/geosets.rs b/crates/benilla-formats/src/characters/geosets.rs
index a57a3359..78c2f19f 100644
--- a/crates/benilla-formats/src/characters/geosets.rs
+++ b/crates/benilla-formats/src/characters/geosets.rs
@@ -10,9 +10,9 @@ const CHAR_HAIR_GEOSETS: &str = "DBFilesClient\\CharHairGeosets.dbc";
 const CHAR_FACIAL_HAIR: &str = "DBFilesClient\\CharacterFacialHairStyles.dbc";
 const HELMET_GEOSET_VIS: &str = "DBFilesClient\\HelmetGeosetVisData.dbc";
 
-/// The default 16 region-base geosets (`cc+0x144`, RF-0038) — increments of 100 (group 7's base is the
-/// outlier 702). Entries 0–3 (hair + the 3 facial-hair groups) are overwritten by the customization;
-/// 4–15 (the equipment-group bases: glove/boot/sleeve/…/cloak) stay as these bare-skin defaults.
+/// The 16 default region bases of `cc+0x144` (ctors `0x476810`/`0x476960`); group 7's is 702.
+/// Entries 0–3, hair and facial hair, are replaced by the customization; 4–15 are the equipment
+/// groups' bare defaults.
 const REGION_BASES: [u16; 16] = [
     1, 101, 201, 301, 401, 501, 601, 702, 801, 901, 1001, 1101, 1201, 1301, 1401, 1501,
 ];
@@ -21,49 +21,33 @@ const REGION_BASES: [u16; 16] = [
 pub struct CharacterGeosets {
     /// (race, sex, hairStyle) → hair `GeosetID` (group 0).
     hair: HashMap<(u8, u8, u8), u32>,
-    /// (race, sex, facialHair) → the 3 facial-hair geoset variations (DBC fields gA/gB/gC, in file
-    /// order — gA→group 1 (+100), gB→group 3 (+300), gC→group 2 (+200), per RF-0073's `0x478660`).
+    /// (race, sex, facialHair) → three geoset variations in file order, for groups 1, 3, 2
+    /// (`0x478660`).
     facial: HashMap<(u8, u8, u8), [u32; 3]>,
-    /// HelmetGeosetVisData row id → its 5 **race** bitmasks (VERIFIED wow-re RF-0083, consumer
-    /// `0x4799a0`): a set bit `1 << race` in column *c* forces one region-base slot back to its
-    /// group base — hiding the styled hair/facial geoset (and the ears) under a worn helm.
+    /// HelmetGeosetVisData row id → five race bitmasks (`0x4799a0`): bit `1 << race` forces a hair,
+    /// facial-hair or ear slot back to its group base under a helm.
     helmet_vis: HashMap<u32, [u32; 5]>,
 }
 
-/// The worn geoset selectors the RF-0038 equipment branches read (decisions 0074, 1864): per
-/// bodyslot 2–9 (shirt, chest, belt, pants, boots, wrist, gloves, tabard) the item's
-/// `geosetGroup[0..2]` (`None` = the slot is empty), plus the cloak's `geosetGroup[0]`, plus the
-/// worn helm's `HelmetGeosetVisData` row pair (`[male, female]` — ItemDisplayInfo cols 12/13).
-/// Default = naked.
-///
-/// **Two of the eight branches are not fed by an ItemDisplayInfo column at all** and take their own
-/// field here (decision 1864): B3 reads the ArmLower *composite grid*, and B6 reads a client flag.
+/// What the equipment branches of `0x477520` read: each bodyslot 2–9's three `geosetGroup`s
+/// (shirt, chest, belt, pants, boots, wrist, gloves, tabard), the cloak's first, and the helm's
+/// `HelmetGeosetVisData` rows (`[male, female]`, ItemDisplayInfo cols 12/13). Default is naked.
 #[derive(Default, Clone, Copy)]
 pub struct EquipGeosets {
     pub bodyslots: [Option<[u32; 3]>; 8],
     pub cloak: Option<u32>,
     pub helm_vis: Option<[u32; 2]>,
-    /// B3's gate: does anything **other than the shirt** dress the forearm? — the six dwords
-    /// `cc+0x26c..cc+0x280` (ArmLower cells 1..6). Fill it from
-    /// [`forearm_dressed`](crate::forearm_dressed), which reads the one composite plan.
+    /// Branch B3's gate: something other than the shirt dresses the forearm (`cc+0x26c..cc+0x280`,
+    /// ArmLower cells 1–6); fill it from [`forearm_dressed`](crate::forearm_dressed).
     pub forearm_dressed: bool,
-    /// B6's gate: `[cc+0xc]`, "the guild registrar's tabard designer is open on this character"
-    /// (wow-re RF-0089 §7c). Set while that window is up so the body wears a previewable tabard
-    /// with an **empty** tabard slot; nothing else in the client ever sets it.
+    /// Branch B6's gate `[cc+0xc]`: the tabard designer is open (setter `0x5e07fb`), so the body
+    /// wears a previewable tabard over an empty tabard slot.
     pub tabard_preview: bool,
 }
 
 impl CharacterGeosets {
-    /// The geoset IDs a character of this appearance renders — RF-0038's opening block (the naked
-    /// set) plus **all eight** equipment branches B1–B8 of `0x477520` (decisions 0074, 1864 —
-    /// implemented from the transcription's *arithmetic*; its prose labels were mislabels wow-re
-    /// corrected in RF-0088/RF-0089, and the branch comments below name each one at its address).
-    /// A body submesh whose `skinSectionId` is in this set is drawn; all others hidden. Most
-    /// branches gate on an ItemDisplayInfo `geosetGroup` field being non-zero ("section present");
-    /// B3 and B6 do not, and read [`EquipGeosets::forearm_dressed`] / [`EquipGeosets::tabard_preview`].
-    ///
-    /// Returned **sorted and deduplicated**: the client toggles a per-submesh flag, where several
-    /// branches re-enable a base the opening loop already set, so a list needs normalising once.
+    /// The geosets (`skinSectionId`s) this appearance draws, sorted and deduplicated: the naked
+    /// set, then the eight equipment branches B1–B8 of `0x477520`.
     pub fn visible_geosets(
         &self,
         race: u8,
@@ -72,26 +56,21 @@ impl CharacterGeosets {
         facial_hair: u8,
         equip: &EquipGeosets,
     ) -> Vec<u16> {
+        // The naked set: the region bases and geoset 0, the body.
         let mut set = REGION_BASES.to_vec();
-        set.push(0); // geoset 0 (the body), enabled unconditionally
-                     // Entry 0 (group 0 = hair): the chosen hairstyle's geoset, clamped ≥1 (`0x478540`
-                     // returns `max(1, geosetId)`, so a bald style still resolves to geoset 1, the scalp).
+        set.push(0);
+        // Hair: `0x478540` returns `max(1, geosetId)`, so a bald style shows geoset 1, the scalp.
         if let Some(&g) = self.hair.get(&(race, sex, hair_style)) {
             set[0] = g.max(1) as u16;
         }
-        // Entries 1–3 (groups 1/2/3 = facial hair): DBC variation + the group base (`0x478660` adds
-        // 100/300/200 to fields gA/gB/gC respectively). Absent row ⇒ the default bases 101/201/301 stand.
+        // Facial hair: `0x478660` adds 100/300/200 to the row's fields; no row keeps the bases.
         if let Some(&[a, b, c]) = self.facial.get(&(race, sex, facial_hair)) {
-            set[1] = (a + 100) as u16; // gA → group 1
-            set[3] = (b + 300) as u16; // gB → group 3
-            set[2] = (c + 200) as u16; // gC → group 2
+            set[1] = (a + 100) as u16;
+            set[3] = (b + 300) as u16;
+            set[2] = (c + 200) as u16;
         }
-        // A worn helm's vis row (VERIFIED wow-re RF-0083, `0x4799a0`): each of the 5 columns is a
-        // **race** bitmask; a set `1 << race` bit forces one region-base slot back to its group
-        // base, dropping the styled geoset the customization just selected — hair to the bare scalp
-        // (1), the facial groups to their bases, and the ears to **701** (over the 702 default no
-        // customization touches). Runs after the customization overwrites, exactly the client's
-        // order; the slots {0,1,2,3,7} are disjoint from every equipment branch below.
+        // A helm's vis row (`0x4799a0`) forces slots back to their bases, the ears to 701, after
+        // the customization; its slots {0,1,2,3,7} are disjoint from every equipment branch.
         if let Some(rows) = equip.helm_vis {
             let row = rows[usize::from(sex == 1)];
             if let Some(masks) = self.helmet_vis.get(&row) {
@@ -104,40 +83,32 @@ impl CharacterGeosets {
                 }
             }
         }
-        // The equipment branches. `g(slot, sub)` = the slot's geosetGroup[sub], gated non-zero.
-        // EquipGeosets bodyslot indices: 0 shirt · 1 chest · 2 belt · 3 pants · 4 boots · 5 wrist ·
-        // 6 gloves · 7 tabard.
+        // The equipment branches; `g(slot, sub)` is a non-zero geosetGroup, slots 0 shirt, 1 chest,
+        // 2 belt, 3 pants, 4 boots, 5 wrist, 6 gloves, 7 tabard.
         let g = |slot: usize, sub: usize| {
             equip.bodyslots[slot]
                 .map(|groups| groups[sub])
                 .filter(|v| *v != 0)
         };
         let disable = |set: &mut Vec<u16>, lo: u16, hi: u16| set.retain(|id| *id < lo || *id > hi);
-        // The robe bit: chest or pants geosetGroup[2] (B4's guard) — it also suppresses B5's tabard
-        // flap and B6's preview. B7 is NOT gated on it: that branch reads the chest's bit alone.
+        // The robe bit (chest or pants geosetGroup[2]) gates B4, B5 and B6; B7 reads the chest's.
         let robe = g(1, 2).or_else(|| g(3, 2));
-        // B1/B2 (`0x477564`): gloves replace the glove group (401+v, own range disabled); else the
-        // chest's sleeves (the `else` arm wow-re numbers B2).
+        // B1/B2 (`0x477564`): gloves replace the glove group, else the chest's sleeves show.
         if let Some(v) = g(6, 0) {
             disable(&mut set, 401, 499);
             set.push(401 + v as u16);
         } else if let Some(v) = g(1, 0) {
             set.push(801 + v as u16);
         }
-        // B3 (`0x4775bd`): the shirt's sleeve cuff — only when nothing ELSE dresses the forearm.
-        // The reference's gate is the ArmLower equip row's cells 1..6, not "is a chest equipped":
-        // most chest pieces leave that tile empty and the cuff survives them, while a bracer or a
-        // glove takes it and the cuff goes (decision 1864; [`EquipGeosets::forearm_dressed`]).
+        // B3 (`0x4775bd`): the shirt's cuff, unless something else dresses the forearm.
         if !equip.forearm_dressed {
             if let Some(v) = g(0, 0) {
                 set.push(801 + v as u16);
             }
         }
-        // B4 (`0x4775fb`): a robe hides boots/kneepads/pant-legs/trousers and shows its skirt
-        // (1301+v); else the boots replace the boot group; else the pants' kneepads. The bare `901`
-        // enables are the reference's own (`0x477648`, `0x477685`) and are no-ops here — the 16-base
-        // loop already carries 901 and nothing on this path disables group 9 — kept so the sequence
-        // stays the reference's rather than resting on that invariant.
+        // B4 (`0x4775fb`): a robe hides the leg groups and shows its skirt, else boots replace the
+        // boot group, else the pants' kneepads. The bare 901 enables are the reference's own
+        // (`0x477648`, `0x477685`), redundant with the bases.
         if let Some(v) = robe {
             disable(&mut set, 501, 599);
             disable(&mut set, 902, 999);
@@ -145,10 +116,8 @@ impl CharacterGeosets {
             disable(&mut set, 1300, 1399);
             set.push(1301 + v as u16);
         } else if let Some(v) = g(4, 0) {
-            // `0x477639` disables the WHOLE boot group before enabling the boot's own geoset — the
-            // naked foot comes off with the boot on. 501 is a real submesh on 11 of the 18 character
-            // models (64 vertices on Human male), so leaving it on — as benilla did until decision
-            // 1864, on a misread of this same note — put a bare ankle inside every boot.
+            // `0x477639` disables the whole boot group first: the bare foot, 501, is a real submesh
+            // on 11 of the 18 character models.
             disable(&mut set, 501, 599);
             set.push(901);
             set.push(501 + v as u16);
@@ -157,30 +126,22 @@ impl CharacterGeosets {
         } else {
             set.push(901);
         }
-        // B5 (`0x477706`): the tabard flap (robes hide it).
+        // B5 (`0x477706`): the tabard flap, hidden by a robe.
         if robe.is_none() {
             if let Some(v) = g(7, 0) {
                 set.push(1201 + v as u16);
             }
         }
-        // B6 (`0x477752`): the tabard-designer preview. **No ItemDisplayInfo column feeds this
-        // branch** — its gate is the flag `[cc+0xc]`, set only while the guild registrar's tabard
-        // designer is open (wow-re RF-0089 §7c; the branch's old "helm-skirt" label was a mislabel,
-        // and no shipped head display carries a geoset group at all). It forces the tabard group on
-        // with an EMPTY tabard slot: 1201, plus 1202 when neither the chest nor the legs carries the
-        // robe bit. On shipped character models 1201 has no submesh (it is the group's "no tabard"
-        // base) and 1202 is the flap — so the observable effect is exactly "wear the tabard so the
-        // design can be previewed" (decision 1864).
+        // B6 (`0x477752`): the designer preview wears 1201, the group's empty base, and without a
+        // robe 1202, the flap.
         if equip.tabard_preview {
-            set.push(1201); // already on from the opening loop; the reference enables it anyway
+            set.push(1201); // redundant with the bases; the reference enables it too
             if robe.is_none() {
                 set.push(1202);
             }
         }
-        // B7 (`0x477799`): the shirt's doublet + the pants' leg geoset (the recorded 1102 base — not
-        // 1101). Skipped ENTIRELY when the CHEST is a robe (`0x4777a4` — the legs' own robe bit does
-        // NOT gate here, unlike B4/B5/B6) or when a TABARD is worn (`0x4777b8`, bodyslot 9 sub 0;
-        // RF-0088 corrected this guard from "glove" to "tabard"). Decision 1864.
+        // B7 (`0x477799`): the shirt's doublet and the pants' legs (base 1102, not 1101); skipped
+        // under a chest robe (`0x4777a4`, not a legs robe) or a tabard (`0x4777b8`).
         if g(1, 2).is_none() && g(7, 0).is_none() {
             if let Some(v) = g(0, 1) {
                 set.push(1001 + v as u16);
@@ -189,36 +150,20 @@ impl CharacterGeosets {
                 set.push(1102 + v as u16);
             }
         }
-        // B8 (`0x47780a`): a cloak replaces the cloak group (1501+v, range disabled).
+        // B8 (`0x47780a`): a cloak replaces the cloak group.
         if let Some(v) = equip.cloak.filter(|v| *v != 0) {
             disable(&mut set, 1500, 1599);
             set.push(1501 + v as u16);
         }
-        // The client's `0x7110d0` writes a flag per submesh, so enabling an already-enabled geoset
-        // is idempotent there; ours is a list, and several branches re-enable a base the opening
-        // loop already added. Normalise once at the end so the result is a canonical set.
+        // The client sets a flag per submesh (`0x7110d0`), so a repeated enable is a no-op there.
         set.sort_unstable();
         set.dedup();
         set
     }
 
-    /// Load both customization DBCs from the patch chain.
-    ///
-    /// **A duplicated `(race, sex, variation)` key resolves to the FIRST row** (decision 0682). Both
-    /// consumers are *linear scans* of the loaded table — `0x478540` for the hair geoset, `0x478740`
-    /// for the facial-hair record (wow-re RF-0073; `object-layer/scratch/r1.md:358` calls `0x478540`
-    /// "a loaded-DBC linear scan, NOT a pool") — so the earliest matching record is the one the
-    /// reference returns, where a last-write `HashMap::insert` would take the latest.
-    ///
-    /// It matters exactly once in the shipped data, and it was B11: `CharHairGeosets` carries **four**
-    /// rows for **(race 9 goblin, sex 0, variation 0)** — ids 241–244, geosets 1 / 2 / 1 / 2, the only
-    /// duplicated key in the file (243/244 read as the goblin-*female* pair with a zeroed sex column,
-    /// which is why goblin females, having no row at all, were always right). Geoset 1 is the bare
-    /// scalp; geoset 2 is that scalp **plus** a 38-vertex topknot whose texture slot is `Monster1` —
-    /// a slot no character-model goblin display fills, so it drew flat white (decision 0157). All 314
-    /// character-model goblin displays select variation 0, so last-write put a white tuft on every one
-    /// of them. `CharacterFacialHairStyles` has no duplicate keys today; it takes the same rule
-    /// because the same scan law governs it.
+    /// Load the customization DBCs from the patch chain. A repeated `(race, sex, variation)` key
+    /// takes its first row, as the client's linear scans (`0x478540`, `0x478740`) do: the shipped
+    /// CharHairGeosets lists goblin male variation 0 four times (geosets 1, 2, 1, 2).
     pub fn load(chain: &mut Chain) -> Result<Self> {
         let hair = {
             let bytes = chain
@@ -231,7 +176,7 @@ impl CharacterGeosets {
                 if let (Some(race), Some(sex), Some(var), Some(geoset)) =
                     (u32_at(r, 1), u32_at(r, 2), u32_at(r, 3), u32_at(r, 4))
                 {
-                    // FIRST row wins — see the duplicate-key note on [`CharacterGeosets::load`].
+                    // The first row wins.
                     m.entry((race as u8, sex as u8, var as u8))
                         .or_insert(geoset);
                 }
@@ -249,7 +194,7 @@ impl CharacterGeosets {
             )?;
             let mut m = HashMap::with_capacity(rs.records().len());
             for r in rs.records() {
-                // fields: RaceID, SexID, VariationID(facialHair), 3×unused, gA, gB, gC (no ID column).
+                // fields: RaceID, SexID, VariationID(facialHair), 3×unused, Geoset100/300/200.
                 if let (Some(race), Some(sex), Some(var)) =
                     (u32_at(r, 0), u32_at(r, 1), u32_at(r, 2))
                 {
@@ -258,14 +203,13 @@ impl CharacterGeosets {
                         u32_at(r, 7).unwrap_or(0),
                         u32_at(r, 8).unwrap_or(0),
                     ];
-                    // FIRST row wins — see the duplicate-key note on [`CharacterGeosets::load`].
+                    // The first row wins.
                     m.entry((race as u8, sex as u8, var as u8)).or_insert(g);
                 }
             }
             m
         };
-        // HelmetGeosetVisData — the helm hide-masks (RF-0083). Soft-optional: a missing/undecodable
-        // table just means helms never hide hair (the pre-0083 behavior), like the other soft-fails.
+        // HelmetGeosetVisData, the helm hide-masks: without the file, helms hide nothing.
         let helmet_vis = match chain.read_file(HELMET_GEOSET_VIS) {
             Ok(bytes) => {
                 let rs = parse(&bytes, helmet_vis_schema(), "HelmetGeosetVisData")?;
@@ -287,7 +231,7 @@ impl CharacterGeosets {
     }
 }
 
-/// CharHairGeosets.dbc — 6 fields in build 5875 (verified against the file header).
+/// CharHairGeosets.dbc: 6 fields.
 pub(crate) fn char_hair_geosets_schema() -> Schema {
     let mut s = Schema::new("CharHairGeosets");
     for (name, ty) in [
@@ -303,8 +247,8 @@ pub(crate) fn char_hair_geosets_schema() -> Schema {
     s
 }
 
-/// HelmetGeosetVisData.dbc — 6 fields in build 5875 (verified: the loader `0x546f00` asserts
-/// fieldCount 6 / recordSize 0x18; the 5 mask columns are **race** bitmasks, RF-0083).
+/// HelmetGeosetVisData.dbc: 6 fields, 0x18-byte records (loader `0x546f00`); the five masks are
+/// race bitmasks (`0x4799a0`).
 pub(crate) fn helmet_vis_schema() -> Schema {
     let mut s = Schema::new("HelmetGeosetVisData");
     for (name, ty) in [
@@ -320,7 +264,7 @@ pub(crate) fn helmet_vis_schema() -> Schema {
     s
 }
 
-/// CharacterFacialHairStyles.dbc — 9 fields in build 5875 (verified); no ID column (keyed race/sex/var).
+/// CharacterFacialHairStyles.dbc: 9 fields, no ID column.
 pub(crate) fn char_facial_hair_schema() -> Schema {
     let mut s = Schema::new("CharacterFacialHairStyles");
     for (name, ty) in [
@@ -330,9 +274,9 @@ pub(crate) fn char_facial_hair_schema() -> Schema {
         ("Unused3", FieldType::UInt32),
         ("Unused4", FieldType::UInt32),
         ("Unused5", FieldType::UInt32),
-        ("Geoset100", FieldType::UInt32), // gA → group 1 (+100)
-        ("Geoset300", FieldType::UInt32), // gB → group 3 (+300)
-        ("Geoset200", FieldType::UInt32), // gC → group 2 (+200)
+        ("Geoset100", FieldType::UInt32),
+        ("Geoset300", FieldType::UInt32),
+        ("Geoset200", FieldType::UInt32),
     ] {
         s.add_field(SchemaField::new(name, ty));
     }
@@ -343,8 +287,7 @@ pub(crate) fn char_facial_hair_schema() -> Schema {
 mod tests {
     use super::*;
 
-    /// The equipment geoset branches (decisions 0074/1864, from the RF-0038 arithmetic):
-    /// gloves/boots/robe/cloak **replace** their groups, and a robe suppresses the tabard branch.
+    /// Gloves, boots, a robe and a cloak replace their groups; a robe hides the tabard flap.
     #[test]
     fn equipment_geoset_branches() {
         let cg = CharacterGeosets {
@@ -355,21 +298,18 @@ mod tests {
         let naked = cg.visible_geosets(1, 0, 0, 0, &EquipGeosets::default());
         assert!(naked.contains(&401) && naked.contains(&1101) && naked.contains(&1501));
 
-        // Gloves v=1: the glove group is replaced (401 out, 402 in).
         let mut eq = EquipGeosets::default();
         eq.bodyslots[6] = Some([1, 0, 0]);
         let set = cg.visible_geosets(1, 0, 0, 0, &eq);
         assert!(set.contains(&402) && !set.contains(&401));
 
-        // Boots v=2: the boot group is replaced — 503 in, the naked foot 501 OUT (`0x477639`
-        // disables [501,599] first). benilla stacked them until decision 1864.
+        // Boots take the bare foot, 501, off (`0x477639`).
         let mut eq = EquipGeosets::default();
         eq.bodyslots[4] = Some([2, 0, 0]);
         let set = cg.visible_geosets(1, 0, 0, 0, &eq);
         assert!(set.contains(&503) && !set.contains(&501));
 
-        // A robe (chest group[2]=1) shows its skirt (1302) and hides boots/pant-legs/trousers —
-        // including a worn tabard's flap and the pants' own branches.
+        // A robe shows its skirt and hides the leg groups and the tabard flap.
         let mut eq = EquipGeosets::default();
         eq.bodyslots[1] = Some([1, 0, 1]);
         eq.bodyslots[3] = Some([2, 1, 0]);
@@ -385,7 +325,6 @@ mod tests {
         assert!(!set.contains(&1202), "tabard suppressed under a robe");
         assert!(set.contains(&802), "the chest's sleeves still show");
 
-        // Cloak v=4: the cloak group is replaced (1501 out, 1505 in).
         let eq = EquipGeosets {
             cloak: Some(4),
             ..Default::default()
@@ -394,10 +333,7 @@ mod tests {
         assert!(set.contains(&1505) && !set.contains(&1501));
     }
 
-    /// **B3's real gate** (`0x4775bd`, decision 1864): the shirt's sleeve cuff survives or dies by
-    /// what dresses the *forearm tile*, not by whether a chest is equipped. Both directions matter —
-    /// 533 of the 637 shipped chest displays leave `ArmLowerTexture` empty, and 566 of 570 wrist
-    /// displays fill it — and benilla had both backwards until this record.
+    /// Branch B3 (`0x4775bd`) keys the shirt's cuff on the forearm tile, not the chest slot.
     #[test]
     fn b3_shirt_sleeve_follows_the_forearm_tile_not_the_chest_slot() {
         let cg = CharacterGeosets {
@@ -418,9 +354,7 @@ mod tests {
             !cg.visible_geosets(1, 0, 0, 0, &shirt(true)).contains(&802),
             "something else paints the forearm: the cuff goes"
         );
-        // And a chest in the slot is NOT the gate: a chest whose ArmLower art is empty leaves the
-        // tile free, and the cuff stays. (The chest's own sleeve geoset is B1's `else`, group 8 too,
-        // so give this one none.)
+        // A chest with no sleeve geoset (B2 would add one to group 8 too) leaves the cuff.
         let mut eq = shirt(false);
         eq.bodyslots[1] = Some([0, 0, 0]);
         assert!(
@@ -429,10 +363,7 @@ mod tests {
         );
     }
 
-    /// **B6 — the tabard-designer preview** (`0x477752`, wow-re RF-0089 §7c; decision 1864). The one
-    /// branch of the eight with no ItemDisplayInfo column behind it: its gate is `[cc+0xc]`, "the
-    /// guild registrar's tabard designer is open", and it wears the tabard flap (1202) with an
-    /// **empty** tabard slot — unless a robe is on, which suppresses it exactly as it suppresses B5.
+    /// Branch B6 (`0x477752`): the open designer wears the flap over an empty slot, unless robed.
     #[test]
     fn b6_tabard_preview_wears_the_flap_with_an_empty_slot() {
         let cg = CharacterGeosets {
@@ -440,10 +371,8 @@ mod tests {
             facial: HashMap::new(),
             helmet_vis: HashMap::new(),
         };
-        // Off: an empty tabard slot shows no flap.
         let set = cg.visible_geosets(1, 0, 0, 0, &EquipGeosets::default());
         assert!(!set.contains(&1202), "no tabard, no designer: no flap");
-        // On: the flap appears with nothing in the slot.
         let preview = EquipGeosets {
             tabard_preview: true,
             ..Default::default()
@@ -451,7 +380,6 @@ mod tests {
         let set = cg.visible_geosets(1, 0, 0, 0, &preview);
         assert!(set.contains(&1202), "the designer forces the flap on");
         assert!(set.contains(&1201), "and the group base with it");
-        // A robe suppresses it, from either the chest's or the legs' robe bit.
         for slot in [1usize, 3] {
             let mut eq = preview;
             eq.bodyslots[slot] = Some([0, 0, 1]);
@@ -462,9 +390,7 @@ mod tests {
         }
     }
 
-    /// **B7's two guards** (`0x4777a4` / `0x4777b8`, decision 1864): the shirt-doublet + pant-leg arm
-    /// is skipped whole when the CHEST is a robe or when a TABARD is worn — and, unlike B4/B5/B6,
-    /// the *legs'* own robe bit does not gate it.
+    /// Branch B7 is off under a chest robe or a tabard (`0x4777a4`, `0x4777b8`), not a legs robe.
     #[test]
     fn b7_is_gated_by_the_chest_robe_and_the_tabard() {
         let cg = CharacterGeosets {
@@ -492,7 +418,6 @@ mod tests {
             "ungated: both on"
         );
 
-        // A worn tabard skips the whole branch (RF-0088 corrected this guard from "glove").
         let mut eq = base;
         eq.bodyslots[7] = Some([1, 0, 0]);
         let set = cg.visible_geosets(1, 0, 0, 0, &eq);
@@ -502,7 +427,6 @@ mod tests {
             "a tabard skips B7 whole"
         );
 
-        // A chest robe skips it too — and takes the doublet with it, which the pre-1864 code left on.
         let mut eq = base;
         eq.bodyslots[1] = Some([0, 0, 1]);
         let set = cg.visible_geosets(1, 0, 0, 0, &eq);
@@ -511,8 +435,7 @@ mod tests {
             "a chest robe skips B7 whole"
         );
 
-        // The LEGS' robe bit does not: B4-long still hides the pant-leg group, but the doublet —
-        // enabled after that disable — stays on. This is the asymmetry the old `robe` shortcut lost.
+        // A legs robe: B4 hides the pant-leg group, then B7 enables its geosets anyway.
         let mut eq = base;
         eq.bodyslots[3] = Some([1, 0, 1]);
         let set = cg.visible_geosets(1, 0, 0, 0, &eq);
@@ -523,10 +446,7 @@ mod tests {
         );
     }
 
-    /// The helm-vis force (VERIFIED wow-re RF-0083): each vis column is a **race** bitmask; a set
-    /// `1 << race` bit forces the slot back to its group base — hair to the bare scalp (1), facial
-    /// groups to 101/201/301, ears to 701 — dropping the styled geosets. The row is sex-selected
-    /// (ItemDisplayInfo col 12 male / 13 female); a mask without our race bit leaves the style.
+    /// The helm vis row (`0x4799a0`) is picked by sex, and a race bit forces the group bases.
     #[test]
     fn helm_vis_forces_group_bases_by_race() {
         let mut hair = HashMap::new();
@@ -534,8 +454,8 @@ mod tests {
         let mut facial = HashMap::new();
         facial.insert((1, 0, 1), [2u32, 3, 4]); // styled facial → 102/303/204
         let mut helmet_vis = HashMap::new();
-        helmet_vis.insert(368, [u32::MAX; 5]); // hide-everything row (real id, dumped)
-        helmet_vis.insert(245, [0u32; 5]); // hide-nothing row (real id, dumped)
+        helmet_vis.insert(368, [u32::MAX; 5]); // a shipped row id, hiding everything
+        helmet_vis.insert(245, [0u32; 5]); // a shipped row id, hiding nothing
         let cg = CharacterGeosets {
             hair,
             facial,
@@ -545,14 +465,14 @@ mod tests {
             helm_vis: Some([368, 245]),
             ..Default::default()
         };
-        // Male (sex 0) picks row 368: everything forced to base.
+        // Male picks row 368.
         let set = cg.visible_geosets(1, 0, 1, 1, &helm);
         assert!(set.contains(&1) && !set.contains(&5), "hair → bare scalp");
         assert!(set.contains(&101) && !set.contains(&102));
         assert!(set.contains(&201) && !set.contains(&204));
         assert!(set.contains(&301) && !set.contains(&303));
         assert!(set.contains(&701) && !set.contains(&702), "ears → 701");
-        // The female column of this pair is the hide-nothing row: styles survive.
+        // Female picks row 245.
         let mut hair = HashMap::new();
         hair.insert((1, 1, 1), 5u32);
         let cg2 = CharacterGeosets {
@@ -581,9 +501,7 @@ mod tests {
         assert!(set.contains(&5), "race bit miss → style kept");
     }
 
-    /// The naked selection for a known Human-male appearance (rows dumped from the build-5875 files):
-    /// hairStyle 1 → GeosetID 2; facialHair 1 → gA/gB/gC = 1/2/1. So the set carries the body (0), the
-    /// hair geoset (2), the three facial geosets (101 / 201 / 302), and the default group bases.
+    /// A Human male's naked set, shipped rows: hairStyle 1 → geoset 2, facialHair 1 → 1/2/1.
     #[test]
     fn naked_human_male_selection() {
         let mut hair = HashMap::new();
@@ -602,13 +520,12 @@ mod tests {
         assert!(set.contains(&101), "facial group 1: gA 1 + 100");
         assert!(set.contains(&302), "facial group 3: gB 2 + 300");
         assert!(set.contains(&201), "facial group 2: gC 1 + 200");
-        // Default equipment-group bases (entries 4–15) stand for a naked body.
         assert!(set.contains(&401) && set.contains(&702) && set.contains(&1501));
-        // A non-selected hair variant is hidden (geoset 5 is hairStyle 4, not chosen).
+        // Geoset 5 is hairStyle 4, not chosen.
         assert!(!set.contains(&5), "unselected hair variant hidden");
     }
 
-    /// A bald hairstyle (GeosetID 0) still resolves to geoset 1 (the scalp), never 0-the-body-collision.
+    /// A bald style (GeosetID 0) resolves to geoset 1, the scalp, not 0, the body.
     #[test]
     fn bald_resolves_to_scalp_geoset_one() {
         let mut hair = HashMap::new();
@@ -622,20 +539,14 @@ mod tests {
         assert!(set.contains(&1), "max(1, 0) = scalp geoset 1");
     }
 
-    /// **B11, against the shipped DBC** (decision 0682): `CharHairGeosets` carries four rows for the
-    /// goblin male's only hairstyle, and the reference's linear scan takes the first — geoset **1**,
-    /// the bare scalp. Last-write took id 244's geoset **2**, which adds an untextured topknot.
-    ///
-    /// Three things are pinned here because each on its own could rot: that the shipped file really
-    /// does duplicate that key (the defect only exists if it does), that we resolve it to 1, and that
-    /// **no other key in the table is duplicated** — which is what bounds this change to goblins.
+    /// The shipped CharHairGeosets repeats only the goblin male's one style, and the first row,
+    /// geoset 1, the bare scalp, wins; geoset 2 adds an untextured topknot.
     #[test]
     fn goblin_male_hair_takes_the_first_of_four_duplicate_rows() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
 
-        // The file's own rows, read independently of the loader, so the test states the premise it
-        // rests on rather than assuming it.
+        // The file's rows, read without the loader.
         let bytes = chain.read_file(CHAR_HAIR_GEOSETS).expect("CharHairGeosets");
         let rs = parse(&bytes, char_hair_geosets_schema(), "CharHairGeosets").expect("parse");
         let mut keys: HashMap<(u32, u32, u32), Vec<u32>> = HashMap::new();
@@ -658,7 +569,6 @@ mod tests {
             "the goblin-male block is the duplicate, in file order"
         );
 
-        // And the loader resolves it the reference's way.
         let cg = CharacterGeosets::load(&mut chain).expect("load customization tables");
         let set = cg.visible_geosets(9, 0, 0, 0, &EquipGeosets::default());
         assert!(
@@ -669,9 +579,7 @@ mod tests {
             !set.contains(&2),
             "goblin male does NOT show geoset 2 — the white topknot of B11"
         );
-        // The goblin female has no row at all (race 9 ships only sex-0 rows), so she falls to the
-        // region base, which is the same scalp. She was never affected; assert it so a future
-        // "fix" to the sex column has to notice her.
+        // Race 9 ships only sex-0 rows, so the goblin female keeps the region base, the same scalp.
         let f = cg.visible_geosets(9, 1, 0, 0, &EquipGeosets::default());
         assert!(f.contains(&1) && !f.contains(&2), "goblin female unchanged");
     }
diff --git a/crates/benilla-formats/src/characters/mod.rs b/crates/benilla-formats/src/characters/mod.rs
index 534ff965..4f5ee29c 100644
--- a/crates/benilla-formats/src/characters/mod.rs
+++ b/crates/benilla-formats/src/characters/mod.rs
@@ -1,23 +1,10 @@
-//! Character customization render data (decision 0041, Milestone B) — what a player's appearance
-//! selects: which **geosets** the body shows ([`CharacterGeosets`]) and which **skin textures** the
-//! body wears ([`CharSections`]).
+//! Character appearance render data: the geosets an appearance shows ([`CharacterGeosets`], the
+//! client's geoset dispatch `0x477520`) and the body skin it wears: body-skin batches
+//! (`M2TextureType::Other(1)`) have no texture of their own, and [`CharSections::composite_body`]
+//! builds one on the 256² partition `0x475c50` and the section→cell map `0x4782e0`.
 //!
-//! **Geosets.** A character model contains *every* hairstyle, facial-hair piece, and body-option geoset;
-//! the real client renders only the selected ones. The selection is the compositor's geoset dispatch
-//! `0x477520` (wow-re charactermodel RF-0038). For a character with **no equipment** the 8 per-item
-//! branches all no-op (their `ItemDisplayInfo` records are null), leaving only the unconditional opening
-//! block: disable every geoset, enable geoset 0, then enable the 16 region-base entries of `cc+0x144` —
-//! entries 0–3 overwritten by the customization DBCs (the chosen hair + 3 facial-hair geosets), entries
-//! 4–15 the default group bases. We render an M2 submesh iff its `skinSectionId` is in that set.
-//!
-//! **Skin textures.** A character body's `M2TextureType::Other(1)` (body skin) batches have no embedded
-//! texture — the client supplies a runtime composite keyed on the appearance ([`CharSections::composite_body`],
-//! decision 0044). The **base skin** (`sectionType 0`) is a single full 256² body-layout BLP per (race,
-//! sex, skinColor); the face / facial-hair / hair / underwear overlays (`sectionTypes 1–4`) are region
-//! BLPs blended on top at fixed atlas tiles (the RF-0062 partition + RF-0067/0074 section→tile map).
-//!
-//! DBC field maps byte-verified in wow-re charactermodel (RF-0073 geosets, RF-0042 CharSections); field
-//! counts + row semantics cross-checked against the build-5875 files.
+//! DBC layouts follow the client's record readers: CharSections `0x575540`, the geoset tables
+//! `0x5753b0`/`0x575a80`.
 
 mod customization;
 mod geosets;
@@ -30,7 +17,6 @@ pub use sections::{
     BlitSource, CharSections, EmblemLayer, EquipBlit, GuildEmblem,
 };
 
-// The appearance tables' schemas, for the `benilla-extract dbc` CSV dump (`crate::schema_for`) —
-// the same constructors the loaders above use, never a second transcription of the same layout.
+// The loaders' own schemas, for the `benilla-extract dbc` CSV dump (`crate::schema_for`).
 pub(crate) use geosets::{char_facial_hair_schema, char_hair_geosets_schema, helmet_vis_schema};
 pub(crate) use sections::char_sections_schema;
diff --git a/crates/benilla-formats/src/characters/sections.rs b/crates/benilla-formats/src/characters/sections.rs
index ad251850..83fee743 100644
--- a/crates/benilla-formats/src/characters/sections.rs
+++ b/crates/benilla-formats/src/characters/sections.rs
@@ -9,63 +9,37 @@ use crate::{read_texture_mip_chain, BlpMipChain, Chain};
 
 const CHAR_SECTIONS: &str = "DBFilesClient\\CharSections.dbc";
 
-/// CharSections `sectionType` values (wow-re RF-0074): the layer a row supplies. `skin` is the full
-/// base atlas; the rest are region overlays the body composite blends on top (decision 0044).
+/// CharSections `sectionType` values (facial hair 2 at `0x478660`, hair 3 at `0x4784c0`).
 const SECTION_SKIN: u8 = 0;
 const SECTION_FACE: u8 = 1;
 const SECTION_FACIAL_HAIR: u8 = 2;
 const SECTION_HAIR: u8 = 3;
 const SECTION_UNDERWEAR: u8 = 4;
 
-/// The hair variation the client's type-6 binder substitutes when the selected style resolves no
-/// texture — a **literal 1** in the binary at two of its three call sites (`0x478445`, `0x4786f2`),
-/// not a search. See [`CharSections::hair_mesh_texture`]; wow-re `rf84`, decision 0536.
+/// The hair variation the type-6 binder falls back to: a literal 1 at `0x478445` and `0x4786f2`.
 const HAIR_SUBSTITUTE_VARIATION: u8 = 1;
 
-/// An atlas rect `(x, y, w, h)` in pixels — a composite destination tile.
+/// An atlas rect `(x, y, w, h)` in pixels.
 type Tile = (u32, u32, u32, u32);
 
-/// The body-atlas tiles the head + underwear overlays composite into — four of the RF-0062 static 256²
-/// partition's 10 rects. g8/g9 are the head strip (left column, Y 160–256: g8 the 32-tall upper band, g9
-/// the 64-tall lower band); g3 (torso upper) and g5 (pelvis) are the right column's Y 0–64 and Y 96–160 —
-/// the two tiles the underwear section dresses, one per texture column (RF-0062's group→cell map: the
-/// group-3 handler `0x4772f0` takes underwear cell `cc+0x20c`, the group-5 handler `0x4773a0` takes
-/// `cc+0x208`, and `0x478790` builds those two from the sectionType-4 row's `TextureName[1]`/`[0]`).
+/// The head strip of the 256² partition `0x475c50` writes: g8 the upper band, g9 the lower.
 const TILE_G8: Tile = (0, 160, 128, 32);
 const TILE_G9: Tile = (0, 192, 128, 64);
-// The underwear's two tiles ARE two of the equipment tiles — the composite reaches them through
-// `EQUIP_TILES` so there is one transcription of the rects, and these names exist for the tests,
-// which read far better naming the group than indexing the array.
+// The underwear's torso and pelvis tiles are equipment tiles g3 and g5, named for the tests.
 #[cfg(test)]
 const TILE_G3: Tile = EQUIP_TILES[3];
 #[cfg(test)]
 const TILE_G5: Tile = EQUIP_TILES[5];
 
-/// The underwear section's two blits: `(textureColumn, equipLayer, columnsTested)` — which
-/// `TextureName` column dresses which equipment tile, and **how far into that tile's equipment
-/// columns the client looks before it draws at all** (wow-re RF-0086, byte-derived from the two
-/// handlers).
-///
-/// The underwear is not an under-layer — it is the tile's **fallback**. `0x4772f0` (TorsoUpper)
-/// tests `cc+0x2e8/0x2ec/0x2f0` = columns 0–2 and `0x4773a0` (LegUpper) tests `cc+0x368/0x36c` =
-/// columns 0–1, each `jne` straight past the underwear blit; only with every tested cell null does
-/// the handler blit `cc+0x20c`/`cc+0x208`. So a shirt, a chest/robe or a guild tabard's background
-/// hides the bra, and legs or a robe hide the panties — but the tested set is a strict **prefix**,
-/// and the columns past it are not consulted: **a belt never hides the panties, and a plain tabard
-/// never hides the bra**, even though both repaint their tile afterwards.
-///
-/// The base-skin blit is unconditional in both branches, so a suppressed tile shows *skin*, not a
-/// hole — and the underwear itself is a REPLACE (alphaDepth 0, an opaque full-tile paste), never a
-/// blend.
+/// The underwear's blits, `(TextureName column, layer, cells tested)`: the tile's fallback, drawn
+/// by `0x4772f0` (TorsoUpper, `cc+0x20c`) only with cells 0–2 empty and by `0x4773a0` (LegUpper,
+/// `cc+0x208`) only with cells 0–1 empty; `0x478790` fills both from the sectionType-4 row.
 const UNDERWEAR_TILES: [(usize, usize, i8); 2] = [
-    (0, 5, 2), // TextureName[0] → LegUpper: {Legs, Chest/Robe} tested; the belt (col 2) is not
-    (1, 3, 3), // TextureName[1] → TorsoUpper: {Shirt, Chest/Robe, guild-tabard Background} tested
+    (0, 5, 2), // pelvis into LegUpper: pants and chest tested, not the belt
+    (1, 3, 3), // torso into TorsoUpper: shirt, chest and a guild tabard's background tested
 ];
 
-/// The eight equipment tiles g0–g7 (RF-0062), in **layer order** — the load-bearing identity of
-/// decision 0074: ItemDisplayInfo texture column *i* = compositor layer *i* = tile g*i*. Note g3 ==
-/// [`TILE_G3`] and g5 == [`TILE_G5`] — equipment TorsoUpper/LegUpper share the underwear's two tiles;
-/// underwear blits first, so it sits under.
+/// The equipment tiles g0–g7 of `0x475c50`: ItemDisplayInfo texture column i is layer i, tile gi.
 const EQUIP_TILES: [Tile; 8] = [
     (0, 0, 128, 64),     // g0 ArmUpper
     (0, 64, 128, 64),    // g1 ArmLower
@@ -77,8 +51,7 @@ const EQUIP_TILES: [Tile; 8] = [
     (128, 224, 128, 32), // g7 Foot
 ];
 
-/// The `Item\TextureComponents\` region directory per layer/column (decision 0074; empirically
-/// suffix-matched — the on-disk dirs are exactly these eight).
+/// The `Item\TextureComponents\` directory per layer, the eight the data ships.
 const EQUIP_TEX_DIRS: [&str; 8] = [
     "ArmUpperTexture",
     "ArmLowerTexture",
@@ -90,17 +63,9 @@ const EQUIP_TEX_DIRS: [&str; 8] = [
     "FootTexture",
 ];
 
-/// The `[0x803bf8]` bodyslot×layer table (wow-re RF-0088), rows = bodyslots 2–9 (shirt, chest, belt,
-/// pants, boots, wrist, gloves, tabard), columns = layers 0–7: the **cell** within the layer's row
-/// that this slot's contribution occupies, `-1` = this slot never touches the layer.
-///
-/// It is a **default, not a fixed priority** — that was decision 0074's mistake and B326/B327's
-/// cause. `0x478ad0` tests the cell for `-1` and for a non-empty texture name, then hands the slot to
-/// the layer's own **chooser** `[0xb42424 + layer*4]`, and two of the eight choosers overrule the
-/// table from the item's `geosetGroup` (see [`equip_column`]). Layers 0/2/3/4/5/7 take it verbatim.
-///
-/// The row is 16 cells and holds **one record per cell**; the composite handler fans out over it by
-/// ascending cell index, so a higher cell is blitted later and covers a lower one.
+/// The `[0x803bf8]` table: per bodyslot 2–9 and layer 0–7, the default cell of the slot's art,
+/// `-1` for never; two layer choosers (`[0xb42424 + layer*4]`) overrule it ([`equip_column`]).
+/// A row holds one record per cell, blitted by ascending cell.
 const EQUIP_LAYER_COLUMN: [[i8; 8]; 8] = [
     [0, 0, -1, 0, 0, -1, -1, -1],    // shirt
     [1, 1, -1, 1, 1, 1, 1, -1],      // chest (robes reach the legs)
@@ -109,101 +74,55 @@ const EQUIP_LAYER_COLUMN: [[i8; 8]; 8] = [
     [-1, -1, -1, -1, -1, -1, 2, 0],  // boots
     [-1, 2, -1, -1, -1, -1, -1, -1], // wrist
     [-1, 3, 0, -1, -1, -1, -1, -1],  // gloves
-    [-1, -1, -1, 4, 4, -1, -1, -1], // tabard (RF-0088: TorsoUpper is cell 4, not 3 — 0074 mis-read it)
+    [-1, -1, -1, 4, 4, -1, -1, -1],  // tabard
 ];
 
-/// The worn-slot indices the two overruling choosers name, in `equipment` order (bodyslot − 2).
+/// Worn-slot indices in `equipment` order, bodyslot − 2.
 const SLOT_CHEST: usize = 1;
 const SLOT_PANTS: usize = 3;
 const SLOT_BOOTS: usize = 4;
 const SLOT_GLOVES: usize = 6;
-/// The tabard's worn-slot index (bodyslot 9 − 2) — the slot whose display decides whether the
-/// guild-emblem layers install at all ([`ItemDisplay::takes_guild_emblem`]).
+/// The tabard's worn slot, whose display decides whether the guild emblem installs.
 const SLOT_TABARD: usize = 7;
 
 /// Where the guild tabard's art lives.
 const GUILD_EMBLEM_DIR: &str = "Textures\\GuildEmblems";
 
-/// The two compositor layers the guild tabard paints, and the filename half each names: TorsoUpper
-/// takes the `_TU_` files, TorsoLower the `_TL_` ones (wow-re RF-0086: `0x47a610` stores the `_TU_`
-/// trio into group 3's cells and the `_TL_` twins into group 4's). No other layer is touched — the
-/// emblem is a torso garment, and the arms/legs keep whatever the rest of the outfit painted.
+/// The guild tabard's layers and name halves (`0x47a610`): TorsoUpper `_TU_`, TorsoLower `_TL_`.
 const EMBLEM_LAYERS: [(usize, &str); 2] = [(3, "TU"), (4, "TL")];
 
-/// The filename half layer `layer` reads its guild-emblem art from, or `None` for a layer the
-/// tabard never reaches.
 fn emblem_half(layer: usize) -> Option<&'static str> {
     EMBLEM_LAYERS
         .iter()
         .find_map(|&(l, half)| (l == layer).then_some(half))
 }
 
-/// CharSections texture lookup: (race, sex, sectionType, variation, colorIndex) → that row's up-to-3
-/// `TextureName` columns (empty strings for absent columns). Feeds both the base body skin
-/// (`sectionType 0`) and the head/pelvis region overlays the body composite blends on top (decision 0044).
+/// CharSections: (race, sex, sectionType, variation, colorIndex) → the row's `TextureName`s.
 pub struct CharSections {
     sections: HashMap<(u8, u8, u8, u8, u8), [String; 3]>,
 }
 
 impl CharSections {
-    /// The base body-skin BLP for an appearance — CharSections `sectionType 0`, the single full 256²
-    /// body-layout texture keyed by skinColor. `None` if the row is absent.
+    /// The 256² base body skin for a skin colour (`sectionType 0`).
     pub fn skin_texture(&self, race: u8, sex: u8, skin_color: u8) -> Option<&str> {
         self.tex(race, sex, SECTION_SKIN, 0, skin_color, 0)
     }
 
-    /// The standalone **extra-skin** BLP for an appearance — CharSections `sectionType 0`,
-    /// `TextureName[1]`, keyed by skinColor (`…Skin00_NN_Extra.blp`). The texture the client binds to a
-    /// character body's M2 texture type 8 batches, loaded plain — never composited (the client's extra
-    /// loader is a bare TextureCreate). Only fur races author the column: tauren bind their head/leg fur
-    /// to it; every other race's rows leave it empty (and their models carry no type-8 batch).
+    /// The extra skin (`sectionType 0`, `TextureName[1]`), bound uncomposited to M2 texture type 8;
+    /// only the fur races author it (tauren).
     pub fn skin_extra_texture(&self, race: u8, sex: u8, skin_color: u8) -> Option<&str> {
         self.tex(race, sex, SECTION_SKIN, 0, skin_color, 1)
     }
 
-    /// The hair-**mesh** texture for an appearance — CharSections `sectionType 3`, `TextureName[0]`,
-    /// keyed by hairStyle (variation) + hairColor. The single BLP the client binds to the hair geometry's
-    /// M2 texture type 6 (decision 0045); the colour is baked into the chosen file, not a runtime tint.
-    /// `None` when the row/column is empty (e.g. a bald style, variation 0 — its columns are blank).
-    /// (`TextureName[1]/[2]` of the same row are the scalp-on-skin overlays the body composite blends into
-    /// the head atlas — those go through [`Self::composite_body`], not here.)
+    /// The hair row's `TextureName[0]`, colour baked in; meshes use [`Self::hair_mesh_texture`].
     pub fn hair_texture(&self, race: u8, sex: u8, hair_style: u8, hair_color: u8) -> Option<&str> {
         self.tex(race, sex, SECTION_HAIR, hair_style, hair_color, 0)
     }
 
-    /// The texture to bind to a character body's M2 **type 6** batches — the hair sheet, which on
-    /// several races dresses the *facial* hair geometry (beard/mustache geosets) as well as the
-    /// scalp hair. Prefer this over [`Self::hair_texture`] anywhere a mesh is being textured;
-    /// `hair_texture` is the raw row accessor, and a bald row is genuinely blank.
-    ///
-    /// **The mechanism** (byte-verified, wow-re `rf84-hair-texture-type6-resolution.md`; decision
-    /// 0536). The client has no fallback *lookup*. `0x478220(cc, variationIdx)` is the sole type-6
-    /// binder, it always reads `TextureName[0]` (never column-indexed), and an **empty name is a
-    /// no-op that leaves the slot untouched** (`0x47827d cmp BYTE PTR [ecx],0x0` → `je 0x4782d8`) —
-    /// not a null bind. Three sites call it, in build order skin → hairStyle → facialHair:
-    ///
-    /// 1. `0x478445` — variation **literal 1**, gated `sex==0 && hairStyle==0 && ChrRaces.Flags & 8`
-    /// 2. `0x478450` — variation `hairStyle`, unconditional
-    /// 3. `0x4786f2` — variation **literal 1**, gated on the selected beard having geoset geometry
-    ///    and the hairStyle row missing a detail column; no sex/race/hairStyle test
-    ///
-    /// Because no site ever clears the slot, the result is simply the **last site that resolved a
-    /// non-empty name** — which reduces to: take the hairStyle row, and when it is blank take
-    /// **variation 1** at the same colour. That is the fixpoint of the client's incremental apply
-    /// pipeline, and it is what this implements; we resolve a whole look at once rather than
-    /// re-applying per dial, so emulating the three sites separately would add machinery without
-    /// changing an output.
-    ///
-    /// The literal 1 is load-bearing where a race authors several sheets per colour: Human male
-    /// resolves `Hair03_<colour>.blp` specifically, not an arbitrary non-blank row.
-    ///
-    /// **Where this can diverge** (verified inert on 1.12.1 data, kept honest rather than dropped):
-    /// site 3's trigger is broader than "the hairStyle row is blank" — it also fires for Dwarf M
-    /// {0,2,4,9}, Scourge M {1,3,4,8} and Orc F {7}, i.e. 14 of 145 variation groups rather than the
-    /// 5 blank ones. In every one of those the variation-1 sheet is byte-identical to what the real
-    /// hairStyle already bound, so the reduction above is exact on the shipped build. It would only
-    /// part company with the client on data where a site-3 group's variation-1 sheet differs from
-    /// its own — which build 5875 does not contain.
+    /// The sheet for M2 texture type 6, the hair and on several races the beard: the style's row,
+    /// else variation 1 at the same colour. The client's binder `0x478220` ignores an empty name
+    /// (`0x47827d`) and runs for variation 1 (`0x478445`, `0x4786f2`) and the style (`0x478450`);
+    /// on the shipped data its last non-empty bind is always this.
     pub fn hair_mesh_texture(
         &self,
         race: u8,
@@ -215,7 +134,7 @@ impl CharSections {
             .or_else(|| self.hair_texture(race, sex, HAIR_SUBSTITUTE_VARIATION, hair_color))
     }
 
-    /// One `TextureName` column of a section row, or `None` if the row/column is absent or empty.
+    /// One `TextureName` column of a row; an empty name is `None`.
     fn tex(&self, race: u8, sex: u8, ty: u8, var: u8, color: u8, col: usize) -> Option<&str> {
         self.sections
             .get(&(race, sex, ty, var, color))
@@ -223,27 +142,12 @@ impl CharSections {
             .filter(|s| !s.is_empty())
     }
 
-    /// Composite a character's full body-skin atlas: the base 256² skin with the face / facial-hair /
-    /// hair / underwear region overlays blended in at their fixed atlas tiles, returned as one mip
-    /// pyramid ready to upload (decision 0044). `Ok(None)` if the base skin row is absent; a missing or
-    /// undecodable overlay is skipped (best-effort, like the rest of the asset pipeline).
+    /// The body-skin atlas as one mip pyramid: the 256² base skin, the head overlays, the
+    /// underwear, the equipment by bodyslot − 2 and the guild emblem ([`equip_blits`]), each at its
+    /// tile per authored mip level (`0x475c50`, `0x4770f0`); `Ok(None)` without a base skin row.
     ///
-    /// Each overlay is read from its own origin and source-over blitted onto the base at the verified
-    /// tile (RF-0062 bbox table + RF-0067 per-layer src rect + RF-0074 head-section map). The overlay
-    /// BLP's own alpha is the blend control, so an opaque overlay (`alphaDepth 0` → the real client's
-    /// REPLACE: face, pelvis) overwrites the base and an alpha one (facial hair) blends — at full 8-bit
-    /// precision, not the client's 16-bit RGB565 / 2-bit-coverage memory format (the modern-client
-    /// choice; the decision has the why). Composited per **authored** mip level — no gamma-byte CPU
-    /// downsample, the same C2 rule [`read_texture_mip_chain`]/the world-art upload follow.
-    ///
-    /// `equipment` is the dressed extension (decision 0074): the worn ItemDisplayInfo rows by
-    /// **bodyslot − 2** (shirt, chest, belt, pants, boots, wrist, gloves, tabard; `None` = the slot
-    /// is empty). Their region textures blit into the eight equipment tiles after the skin sections,
-    /// stacked per layer by the client's priority table — and they also **gate** the underwear, which
-    /// is the tile's fallback rather than an under-layer ([`UNDERWEAR_TILES`]).
-    ///
-    /// `emblem` is the wearer's guild tabard (decision 1704), which paints the torso layers' cells
-    /// 2/3/4 over the garment's own — see [`equip_blits`] for when it installs and when it does not.
+    /// Deviation: blends in 8-bit RGBA, not the client's RGB565 with 2-bit coverage, because that
+    /// format only saves texture memory and loses precision.
     pub fn composite_body(
         &self,
         chain: &mut Chain,
@@ -263,13 +167,8 @@ impl CharSections {
         };
         let mut atlas = read_texture_mip_chain(chain, base_path)
             .with_context(|| format!("reading base skin '{base_path}'"))?;
-        // The head overlays: (sectionType, variation, color, texColumn, destTile) — the verified fan-out
-        // (RF-0067 §"section → cell core" + RF-0074 head map). Within a tile, order matters (later
-        // overwrites/blends over earlier): base skin (already the canvas) → face → facial hair → hair.
-        // Note the columns differ by section: face/facial-hair use TextureName[0]/[1] (lower/upper),
-        // hair uses [1]/[2]. Hair is blank for e.g. Human male (its texid columns are empty), so those
-        // reads no-op there; included so the path is correct for races whose hairline does composite
-        // into the head.
+        // The head overlays `(sectionType, variation, color, column, tile)` of `0x4782e0`, in order
+        // face, facial hair, hair; face and facial hair use columns 0/1, hair 1/2.
         let overlays: [(u8, u8, u8, usize, Tile); 6] = [
             (SECTION_FACE, face, skin, 0, TILE_G9),
             (SECTION_FACE, face, skin, 1, TILE_G8),
@@ -286,13 +185,10 @@ impl CharSections {
                 blit_over(&mut atlas, &overlay, tile);
             }
         }
-        // The equipment plan, built once: the blits below consume it, and the underwear reads it as its
-        // gate. One plan, so "what dresses this tile?" has a single answer (decision 0074's `equip_blits`).
+        // One plan gates the underwear and drives the equipment blits.
         let plan = equip_blits(&equipment, emblem, tabard_preview);
-        // The underwear ([`UNDERWEAR_TILES`]) — the tile's fallback, not an under-layer: a contribution
-        // in any of the group's TESTED columns and the client draws no underwear there at all, leaving
-        // the base skin it already blitted. Drawn before the equipment because the untested columns (the
-        // belt, the tabard) still stack on top of it.
+        // The underwear, skipped when a tested cell is taken (`UNDERWEAR_TILES`); drawn first, so
+        // the untested cells (belt, tabard) stack on top.
         for (col, layer, tested) in UNDERWEAR_TILES {
             if plan.iter().any(|s| s.layer == layer && s.column < tested) {
                 continue;
@@ -304,11 +200,7 @@ impl CharSections {
                 blit_over(&mut atlas, &overlay, EQUIP_TILES[layer]);
             }
         }
-        // The equipment layers (decision 0074) and the guild tabard's three (decision 1704), in the
-        // one order [`equip_blits`] decides, each taking the first of its own
-        // [`EquipBlit::candidates`] that decodes. A name that resolves to nothing is skipped —
-        // best-effort, like the skin overlays; on the model it reads as a garment that stops early,
-        // which is what the instrument's `MISSING` line is for.
+        // The equipment and emblem layers in plan order, each from its first decodable candidate.
         for step in &plan {
             if let Some(overlay) = step
                 .candidates(sex)
@@ -343,12 +235,8 @@ impl CharSections {
                     str_at(&rs, r, 8).unwrap_or_default(),
                 ];
                 let key = (race as u8, sex as u8, ty as u8, var as u8, color as u8);
-                // The standard player sections are `flags == 0`. Some (race,sex,type,color) keys ALSO have
-                // an `EXTRA`-flagged row (`flags & 0x1`) sharing the same colorIndex — e.g. human-male
-                // skinColor 0/1 carry both `HumanMaleSkin00_00` (flags 0) and the late `…_100` (flags 1).
-                // Those are not the chargen-selectable skins; a player with skinColor 0/1 must get `…_00`.
-                // So a standard row always wins; an extra row only fills a key no standard row provides
-                // (order-independent — robust to the extras appearing before or after the standards).
+                // A row flagged `0x1` can share its key with a standard row (Human male skin 0 has
+                // `…Skin00_00` and `…_100`); the standard row wins in either order.
                 let extra = u32_at(r, 9).unwrap_or(0) & 0x1 != 0;
                 if extra {
                     sections.entry(key).or_insert(texs);
@@ -361,37 +249,25 @@ impl CharSections {
     }
 }
 
-/// One equipment contribution the body composite blits, carrying the worn bodyslot it came from,
-/// the layer/tile it lands in, and the `ItemDisplayInfo` region-texture name it draws.
-///
-/// This is the *plan* [`CharSections::composite_body`] executes, exposed so the instrument
-/// (`benilla-extract charatlas`) reads the composite off the **same law the composite runs** rather
-/// than a second transcription that can drift. "Which worn slot repainted this tile?" is the
-/// question both reported outfit bugs turned on, and it was unanswerable without this.
+/// One step of the equipment plan [`CharSections::composite_body`] runs, public so
+/// `benilla-extract charatlas` reports the same plan.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct EquipBlit<'a> {
-    /// The compositor layer — `ItemDisplayInfo` texture column *i* = layer *i* = atlas tile g*i*.
+    /// The compositor layer: ItemDisplayInfo texture column i, atlas tile gi.
     pub layer: usize,
-    /// The cell this contribution occupies in the layer's row — [`equip_column`]'s answer for a worn
-    /// garment, or the guild tabard's fixed 2/3/4. Ascending = blitted later.
+    /// The cell in the layer's row ([`equip_column`], or the emblem's 2/3/4); higher blits later.
     pub column: i8,
     /// Where the art comes from.
     pub source: BlitSource<'a>,
 }
 
-/// What one [`EquipBlit`] paints with — a worn garment's own region texture, or one of the three
-/// guild-tabard layers. Two different filename laws, which is why this is an enum and not a path:
-/// a garment resolves `Item\TextureComponents\<dir>\<name>_<U|M|F>.blp` (`_U` first, the
-/// wearer's gender letter as the fallback), the tabard `Textures\GuildEmblems\<…>_<TU|TL>_U.blp`
-/// with no gender variant at all.
+/// What an [`EquipBlit`] paints: a garment's `Item\TextureComponents\<dir>\<name>_<U|M|F>.blp`,
+/// or a guild-tabard layer's `Textures\GuildEmblems\<…>_<TU|TL>_U.blp`, which is never gendered.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum BlitSource<'a> {
-    /// A worn garment's `ItemDisplayInfo` region texture: the bodyslot it came from, indexed as
-    /// [`CharSections::composite_body`]'s `equipment` is (bodyslot − 2: 0 shirt · 1 chest · 2 belt ·
-    /// 3 pants · 4 boots · 5 wrist · 6 gloves · 7 tabard), and the row's name for this layer (no
-    /// directory, no gender suffix).
+    /// A worn garment: its slot (bodyslot − 2) and its bare region-texture name for this layer.
     Worn { slot: usize, texture: &'a str },
-    /// One of the wearer's guild-tabard layers — see [`EmblemLayer`].
+    /// One of the wearer's guild-tabard layers.
     Emblem {
         part: EmblemLayer,
         emblem: GuildEmblem,
@@ -399,12 +275,8 @@ pub enum BlitSource<'a> {
 }
 
 impl EquipBlit<'_> {
-    /// The chain paths this contribution is looked up under, **in the order the composite tries
-    /// them**, first hit wins. Two for a worn garment (`_U`, then the wearer's gender letter — the
-    /// RF-0088 §7 order); one for a guild-tabard layer, which ships a single ungendered name.
-    ///
-    /// The composite runs this and the instrument reports it, so "which file did that cell take?"
-    /// has one answer and cannot drift into two transcriptions.
+    /// The chain paths to try, first hit wins: `_U` then the gender letter for a garment
+    /// (`0x476e20`), the one ungendered name for an emblem layer.
     pub fn candidates(&self, sex: u8) -> Vec<String> {
         match self.source {
             BlitSource::Worn { texture, .. } => {
@@ -417,51 +289,28 @@ impl EquipBlit<'_> {
     }
 }
 
-/// A guild's tabard — the five indices `SMSG_GUILD_QUERY_RESPONSE` carries, and the whole input to
-/// the guild-emblem composite. They are file indices, not colours: each names a shipped BLP under
-/// `Textures\GuildEmblems\`, and an index with no file simply paints nothing (the client's
-/// `**** Unable to Load Texture %s` leaves the cell null), so nothing here is range-checked.
-///
-/// **Signed on purpose.** A guild that has never bought a tabard carries `-1` in all five (vmangos
-/// `Guild/Guild.cpp:86`; `int32` on the wire), and `{:02}` renders that as `-1` — the same
-/// `Emblem_-1_-1_TU_U` the client's own `%02d` builds, which resolves to no file and so paints
-/// nothing. Clamping, or casting through unsigned, would invent a crest for a guild that has none.
+/// A guild's tabard: the five `SMSG_GUILD_QUERY_RESPONSE` indices, each naming a BLP under
+/// `Textures\GuildEmblems\` (the designer's counts `[0x808220]` = {170, 17, 6, 17, 51}); an index
+/// with no file paints nothing. Signed, never clamped: a guild with no tabard sends `-1` in all
+/// five (vmangos `Guild/Guild.cpp:86`, `int32`).
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
 pub struct GuildEmblem {
-    /// The emblem symbol — `Emblem_<style>_<color>_…`; 170 shipped (000–169), a complete 170 × 17.
+    /// The symbol, `Emblem_<style>_<color>_…`.
     pub emblem_style: i32,
-    /// The emblem symbol's colour — 17 shipped (00–16), every style authoring all of them.
+    /// The symbol's colour.
     pub emblem_color: i32,
-    /// The border style — `Border_<style>_<color>_…`. **Only 00–05 are reachable**: the client's own
-    /// count table `[0x808220] = {170, 17, 6, 17, 51}` caps the designer at six, and the 52
-    /// `Border_06..09_*` files it ships are dead art (wow-re `rf89`). A server that put 7 on the
-    /// wire would simply resolve nothing, which is the same outcome the reference reaches.
+    /// The border, `Border_<style>_<color>_…`; the designer never offers the shipped styles 6–9.
     pub border_style: i32,
-    /// The border's colour — 17 for the six reachable styles; the shipped table is ragged (118
-    /// files per half, not 170) only because the dead styles author 4 colours each.
+    /// The border's colour.
     pub border_color: i32,
-    /// The background colour — `Background_<color>_…`; 51 shipped (00–50), and the only layer with
-    /// a single index. **29 ships uppercase** (`BACKGROUND_29_TU_U.blp`, no lowercase sibling), so
-    /// the chain lookup this feeds must stay case-insensitive — pinned by a test.
+    /// The background; 29 ships as `BACKGROUND_29_TU_U.blp`, so the lookup must ignore case.
     pub background_color: i32,
 }
 
 impl GuildEmblem {
-    /// Whether this guild has actually **designed** a tabard — every one of the five indices is a
-    /// real one. `false` = the `-1` sentinel is present, and the crest must not install at all.
-    ///
-    /// This is the client's own guard, not a convenience: `0x6d6d20` returns success **iff** the
-    /// guild record is cached AND none of its five fields is `-1` (five `cmp …,-1; je` at
-    /// `0x6d6d73`/`0x6d6d78`/`0x6d6d81`/`0x6d6d8a`/`0x6d6d93`, before any value reaches a path
-    /// builder, over out-params pre-initialised to `-1`). On failure the install `0x47a610` is never
-    /// entered — and since the clear of cells 4→2 lives *inside* that function
-    /// (`0x47a616 push 4; call 0x47a5c0`), the equipped tabard's own art is left standing.
-    ///
-    /// **Getting this wrong is visible, not academic.** Painting the crest unconditionally builds
-    /// `Emblem_-1_-1_TU_U`, which names no file — but the plan has already taken cell 4 away from
-    /// the garment, so an undesigned guild's tabard renders as bare skin. It is `-1` on **any** of
-    /// the five, not all: the reference tests them one at a time and bails on the first.
-    /// (wow-re `rf89-guild-tabard-emblem-install.md` §Q6.)
+    /// Whether none of the five is `-1`, the client's guard `0x6d6d20` (`0x6d6d73`–`0x6d6d93`).
+    /// Otherwise `0x47a610` is never entered, so its clear of cells 4→2 (`0x47a616 push 4;
+    /// 0x47a61a call 0x47a5c0`) never runs and the tabard keeps its own art.
     pub fn is_designed(&self) -> bool {
         [
             self.emblem_style,
@@ -475,29 +324,18 @@ impl GuildEmblem {
     }
 }
 
-/// The "this guild has no tabard" sentinel, in every one of [`GuildEmblem`]'s five fields — the
-/// value vmangos constructs a guild with (`Guild/Guild.cpp:86`) and the one the reference's
-/// `0x6d6d20` tests for. See [`GuildEmblem::is_designed`].
+/// The no-tabard sentinel a new guild carries (`Guild/Guild.cpp:86`), tested by `0x6d6d20`.
 const NO_TABARD: i32 = -1;
 
-/// One of the three layers a guild tabard paints, in blit order — the cells `0x47a610` refills
-/// after clearing 4→2, so background sits under border sits under symbol.
+/// A guild tabard's three layers, in the blit order of the cells `0x47a610` refills.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum EmblemLayer {
-    /// Cell 2 — the tabard's field colour, and the **only emblem layer inside TorsoUpper's
-    /// underwear-suppression prefix**: cell 2 < the 3 tested columns, so a guild tabard hides the
-    /// bra where a plain one (cell 4) does not ([`UNDERWEAR_TILES`], decision 1614).
-    ///
-    /// That gate is on the *cell being filled*, not on coverage, and the distinction is real here:
-    /// the background is a **cutout**, not a full-tile paste — `Background_12_TU_U` measures 79.5%
-    /// opaque, 16.8% fully transparent, the transparent part being outside the tabard's silhouette.
-    /// So the suppressed bra leaves bare skin at the sides, which is the unconditional base-skin
-    /// blit showing through, exactly as RF-0086 describes.
+    /// Cell 2, the field colour: inside TorsoUpper's tested cells, so a guild tabard hides the bra,
+    /// and its cutout shows the base skin (`0x477070`) at the sides.
     Background,
-    /// Cell 3 — the trim around the field, mostly transparent (`Border_01_07_TU_U`: 65% clear).
+    /// Cell 3, the trim around the field.
     Border,
-    /// Cell 4 — the symbol itself, over everything, and over the tabard garment's own art (the
-    /// cell the equipped tabard would otherwise own).
+    /// Cell 4, the symbol, in the cell the tabard's own art would take.
     Symbol,
 }
 
@@ -509,8 +347,7 @@ impl EmblemLayer {
         EmblemLayer::Symbol,
     ];
 
-    /// The cell this layer occupies in its row — fixed, not chosen: no bodyslot chooser can write
-    /// cells 2/3/4 of layers 3/4, so these three are the guild tabard's alone (wow-re RF-0088).
+    /// The layer's fixed cell in its row (`0x47a610`).
     pub fn column(self) -> i8 {
         match self {
             EmblemLayer::Background => 2,
@@ -519,13 +356,8 @@ impl EmblemLayer {
         }
     }
 
-    /// This layer's chain path for one emblem and one tabard half (`"TU"` / `"TL"`).
-    ///
-    /// The reference's own format strings carry **no extension** (`0x838dd8` is
-    /// `Textures\GuildEmblems\Background_%02d_TU_U`, flat); its texture loader appends `".blp"`
-    /// at `0x449641` after truncating any trailing `.tga`/`.blp`. We build the finished path in one
-    /// step, which is the same string — and `%02d` is a **minimum** width, not a truncation, so
-    /// emblem style 169 is `Emblem_169_…` and not `Emblem_16_…`.
+    /// This layer's chain path for one tabard half (`"TU"`/`"TL"`): the client's `%02d` format
+    /// (`0x838dd8`) plus the `.blp` its loader appends (`0x449641`); `%02d` pads, never truncates.
     pub fn path(self, emblem: &GuildEmblem, half: &str) -> String {
         match self {
             EmblemLayer::Background => format!(
@@ -544,31 +376,16 @@ impl EmblemLayer {
     }
 }
 
-/// The cell a worn slot's contribution to `layer` occupies — the `[0x803bf8]` default, unless the
-/// layer's chooser overrules it (wow-re RF-0088 §5, byte-true; `0x479210` and `0x4793f0`).
-///
-/// **This is the fix for B327 and half of B326.** Only two of the eight choosers look past the
-/// table, and both read an `ItemDisplayInfo.geosetGroup` — so what a garment *is* moves where it
-/// paints:
-///
-/// - **ArmLower** (`0x479210`): gloves with a glove geoset, and a chest with a sleeve geoset, are
-///   promoted clear of the plain cells (to 6 and 5) so a sleeved chest paints over a bracer.
-/// - **LegLower** (`0x4793f0`): a **robe** (chest `geosetGroup[2]`) is promoted to **4**, above a
-///   boot's 3-or-2 — so footwear paints *under* a robe's skirt, never over its hem. Trousers
-///   carrying their own robe bit take 3 when the chest is a robe too, else 4.
-///
-/// Note the asymmetry that makes the bug: a *plain* chest stays at 1 and a boot sits at 2 or 3, so
-/// boots do cover ordinary trousers on the shin — which is right, and is why reading the table as a
-/// fixed priority looked correct for years. Only the robe inverts it.
+/// The cell a worn slot takes in `layer`'s row: the `[0x803bf8]` default, unless the ArmLower
+/// (`0x479210`) or LegLower (`0x4793f0`) chooser overrules it from a `geosetGroup`.
 pub fn equip_column(equipment: &[Option<&ItemDisplay>; 8], slot: usize, layer: usize) -> i8 {
     let group = |s: usize, j: usize| equipment[s].is_some_and(|d| d.geoset_groups[j] != 0);
     match (layer, slot) {
-        // ArmLower — `0x479210`, one `0x4774f0(rec, 0)` up front, applied on two bodyslots.
+        // ArmLower (`0x479210`, via `0x4774f0(rec, 0)`): geoset gloves to 6, a sleeved chest to 5.
         (1, SLOT_GLOVES) if group(slot, 0) => 6,
         (1, SLOT_CHEST) if group(slot, 0) => 5,
-        // LegLower — `0x4793f0`. The boot geoset lifts a boot 2 → 3; the robe bit lifts a chest
-        // 1 → 4, over both. The trouser leg reads the CHEST's robe bit as well: a robe over robe-
-        // trousers puts the trousers at 3 (under the robe), otherwise they take 4 themselves.
+        // LegLower (`0x4793f0`): a boot geoset lifts boots 2 → 3, the robe bit lifts a chest 1 → 4
+        // over them, and robe-trousers take 3 under a robe chest, else 4.
         (6, SLOT_BOOTS) if group(slot, 0) => 3,
         (6, SLOT_CHEST) if group(slot, 2) => 4,
         (6, SLOT_PANTS) if group(slot, 2) => {
@@ -582,32 +399,20 @@ pub fn equip_column(equipment: &[Option<&ItemDisplay>; 8], slot: usize, layer: u
     }
 }
 
-/// The ordered equipment blits a dressed composite performs: per layer, each worn slot that clears
-/// `0x478ad0`'s two gates (a cell that is not `-1` in the default table, and a **non-empty** texture
-/// name — the client's test is on the string's first byte, not on the pointer) placed in the cell
-/// [`equip_column`] gives it, then emitted by ascending cell index.
+/// The equipment plan: per layer, each worn slot with a table cell and a non-empty name
+/// (`0x478ad0` tests the first byte) in its [`equip_column`] cell, by ascending cell. A cell holds
+/// one record: the later slot wins here, the later-equipped item in the client (`0x478900`). The
+/// only slots that meet in a cell are robe-trousers under a robe chest and geoset boots, at
+/// LegLower's 3.
 ///
-/// A row holds **one record per cell**, so two slots landing on the same cell do not stack — the
-/// later writer replaces the earlier, which is what the client's `0x478900` store does. Reachable
-/// only when robe-trousers meet a robe chest and booted feet; `equipment` order decides it here,
-/// where the client's is equip order.
-///
-/// `emblem` is the wearer's guild tabard, or `None` when they have no guild / the guild's identity
-/// has not arrived yet. It installs **only** over a tabard whose display asks for it
-/// ([`ItemDisplay::takes_guild_emblem`]) — a faction tabard that clears the flag keeps its own art,
-/// and a guild member wearing no tabard shows no emblem. When it does install it writes cells 2/3/4
-/// of layers 3 and 4 **last**, so the symbol replaces the tabard garment's own cell-4 contribution:
-/// that is the client's ordering, not a priority rule (`0x478a53` clears cells 4→2 of both layers
-/// when the tabard slot is set, then `0x47a610` refills all three — wow-re RF-0086/RF-0088).
+/// `emblem` installs over a flagged tabard or in the designer preview: `0x47a610` clears cells 4→2
+/// of layers 3 and 4 (`0x47a616`, `0x47a61a`) and refills them, replacing the tabard's own art.
 pub fn equip_blits<'a>(
     equipment: &[Option<&'a ItemDisplay>; 8],
     emblem: Option<GuildEmblem>,
     tabard_preview: bool,
 ) -> Vec<EquipBlit<'a>> {
-    // The tabard designer's preview (decision 1977, wow-re RF-0089 §6/§7c): the reference's
-    // `0x47a610` installs the five onto the character component with no ItemDisplayInfo test —
-    // the previewed tabard is the geoset flap over an EMPTY slot — so the emblem paints whenever
-    // the preview flag is up, and otherwise only over a worn tabard whose display asks for it.
+    // In the designer preview `0x47a610` installs with no ItemDisplayInfo test, over an empty slot.
     let emblem = emblem.filter(|_| {
         tabard_preview
             || equipment[SLOT_TABARD].is_some_and(|d: &ItemDisplay| d.takes_guild_emblem())
@@ -652,75 +457,40 @@ pub fn equip_blits<'a>(
     plan
 }
 
-/// The **ArmLower** layer — the tile whose occupancy gates the shirt's sleeve geoset (below).
 const LAYER_ARM_LOWER: usize = 1;
 
-/// Whether anything **other than the shirt** dresses the forearm — the byte-true gate on the geoset
-/// dispatch's B3 arm (`0x4775bd`, the six dwords `cc+0x26c..cc+0x280` = cells 1..6 of the ArmLower
-/// equip row; the shirt's own default cell is 0, which the loop skips).
-///
-/// The shirt carries a sleeve geoset (802/803, the cuff flare) that must not survive under a
-/// garment painting the same skin: a chest with sleeve art, a bracer, or a glove takes the tile and
-/// the cuff underneath it is dropped. Reading the *grid* rather than "is a chest equipped" is what
-/// makes both directions right — 533 of the 637 shipped chest displays leave `ArmLowerTexture`
-/// empty (the cuff survives them), while 566 of 570 wrist displays fill it (the cuff goes).
-///
-/// Off [`equip_blits`], so the promotion rules stay in one place: a sleeved chest and a
-/// glove-geoset glove are lifted to cells 5 and 6, still inside the tested range. The guild emblem
-/// is passed as `None` because it only ever writes layers 3 and 4 ([`EMBLEM_LAYERS`]) — this row
-/// reads the same either way.
+/// Whether anything but the shirt dresses the forearm, ArmLower cells 1–6 (`cc+0x26c..cc+0x280`):
+/// branch B3's gate on the shirt's cuff (`0x4775bd`). 533 of 637 shipped chests leave the tile
+/// empty, 566 of 570 bracers fill it; the emblem never reaches this layer.
 pub fn forearm_dressed(equipment: &[Option<&ItemDisplay>; 8]) -> bool {
     equip_blits(equipment, None, false)
         .iter()
         .any(|b| b.layer == LAYER_ARM_LOWER && (1..=6).contains(&b.column))
 }
 
-/// The atlas rect layer `layer`'s equipment contributions composite into — `(x, y, w, h)` in pixels
-/// of the 256² body atlas (the RF-0062 bbox table). Out of range past layer 7.
+/// A layer's atlas rect `(x, y, w, h)` in the 256² body atlas (`0x475c50`).
 pub fn equip_tile(layer: usize) -> Option<(u32, u32, u32, u32)> {
     EQUIP_TILES.get(layer).copied()
 }
 
-/// The `Item\TextureComponents\` subdirectory layer `layer` reads its art from.
+/// A layer's `Item\TextureComponents\` subdirectory.
 pub fn equip_tex_dir(layer: usize) -> Option<&'static str> {
     EQUIP_TEX_DIRS.get(layer).copied()
 }
 
-/// The chain paths a region texture is looked up under, in the order the composite tries them:
-/// **`_U`, then the wearer's gender letter** (wow-re RF-0088 §7, byte-true).
-///
-/// The order is load-bearing and it is the inverse of what benilla shipped, which was **B326**.
-/// `0x476e20` stages the literal `"U"` as the format's third `%s` before it computes anything else,
-/// probes that exact path (`0x648a10`, an existence test), and patches the character's gender letter
-/// over the `U` at `strlen-5` **only on a miss** — one byte, one branch, and no second attempt
-/// anywhere in the image. So a gendered file that exists **loses to `_U` whenever `_U` also exists**.
-///
-/// Of 7944 shipped basenames, 5920 are `_U`-only (the probe hits), 1937 are `_M`+`_F` with no `_U`
-/// (the patch is what those are for), and **43 ship both** — on those 43 the gendered art is dead.
-/// `Leather_A_02_Pant_LL` is one: its `_F` is 18 rows shorter than its `_U`, so preferring `_F` left
-/// a bare-skin ring below a night elf female's knee that the reference does not have.
-///
-/// Public so the instrument can report **which** candidate a contribution actually resolved to, and
-/// name the ones that resolved to nothing — a silently-skipped region reads on the model as a
-/// garment that stops early, which is exactly how it was first reported.
+/// A region texture's chain paths in the order the composite tries them: `_U`, then the gender
+/// letter. `0x476e20` probes the `_U` path (`0x648a10`) and patches in the gender letter only on a
+/// miss, so `_U` wins on the 43 shipped basenames that have both.
 pub fn equip_region_candidates(layer: usize, name: &str, sex: u8) -> [String; 2] {
     let dir = EQUIP_TEX_DIRS[layer];
     let letter = if sex == 1 { 'F' } else { 'M' };
     ['U', letter].map(|c| format!("Item\\TextureComponents\\{dir}\\{name}_{c}.blp"))
 }
 
-/// Source-over composite of one region overlay's authored mip pyramid onto the body atlas at a fixed
-/// tile. Per mip level `i` the destination tile is `(x>>i, y>>i, w>>i, h>>i)` and the overlay's level-`i`
-/// pixels are read from its **own origin** — the RF-0067 overlay src rect (`src = (0,0)`, `dst = tile.xy`,
-/// extent `tile.wh`), so the overlay BLP is authored exactly tile-sized. Straight 8-bit source-over per
-/// channel (`out = src·a + dst·(1−a)`, `out_a = a + dst_a·(1−a)`): an opaque overlay (`a == 255`) is a
-/// plain copy (the client's REPLACE), an alpha one blends. Levels past either pyramid's end, and the
-/// sub-pixel remainder of a degenerate deep-mip tile, are clamped/skipped.
+/// Source-over blit of an overlay's mip pyramid at `tile`, level by level, from the overlay's own
+/// origin (`0x4770f0`: src `(0,0)`, extent the tile); an opaque texel copies, the client's REPLACE.
 fn blit_over(dst: &mut BlpMipChain, src: &BlpMipChain, tile: Tile) {
-    // The composite is a per-texel source-over blend, so both sides must be decoded pixels. Every
-    // reader here goes through `read_texture_mip_chain` (never the block-passthrough twin) — this
-    // says so out loud, because a chain that arrived as DXT blocks would blend garbage silently
-    // rather than fail (decision 1626).
+    // Both chains must be decoded RGBA: DXT blocks would blend into garbage without failing.
     debug_assert!(
         dst.is_rgba8() && src.is_rgba8(),
         "character-skin compositing needs decoded chains on both sides"
@@ -733,7 +503,6 @@ fn blit_over(dst: &mut BlpMipChain, src: &BlpMipChain, tile: Tile) {
         let sw = (src.width >> i).max(1) as usize;
         let sh = (src.height >> i).max(1) as usize;
         let (ox, oy) = ((tx >> i) as usize, (ty >> i) as usize);
-        // Copy extent: the tile size at this level, clamped to what both the source and the dest hold.
         let cw = ((tw >> i).max(1) as usize)
             .min(sw)
             .min(dw.saturating_sub(ox));
@@ -750,7 +519,7 @@ fn blit_over(dst: &mut BlpMipChain, src: &BlpMipChain, tile: Tile) {
                 }
                 let a = s[si + 3] as u32;
                 if a == 0 {
-                    continue; // fully transparent overlay texel — leave the base
+                    continue;
                 }
                 if a == 255 {
                     d[di..di + 4].copy_from_slice(&s[si..si + 4]);
@@ -766,7 +535,7 @@ fn blit_over(dst: &mut BlpMipChain, src: &BlpMipChain, tile: Tile) {
     }
 }
 
-/// CharSections.dbc — 10 fields in build 5875 (verified); 3 string columns are texture-name offsets.
+/// CharSections.dbc: 10 fields, three of them texture names.
 pub(crate) fn char_sections_schema() -> Schema {
     let mut s = Schema::new("CharSections");
     for (name, ty) in [
@@ -788,9 +557,7 @@ pub(crate) fn char_sections_schema() -> Schema {
 
 #[cfg(test)]
 mod tests {
-    /// The `(cell, texture)` pair of a **worn** contribution — the shape every cell-order assertion
-    /// below reads. These fixtures pass no emblem, so a guild-tabard layer here is a bug in the
-    /// test, not a case to handle.
+    /// The `(cell, texture)` of a worn contribution; these fixtures pass no emblem.
     fn worn_cell<'a>(step: &EquipBlit<'a>) -> (i8, &'a str) {
         match step.source {
             BlitSource::Worn { texture, .. } => (step.column, texture),
@@ -799,8 +566,7 @@ mod tests {
     }
     use super::*;
 
-    /// The base skin resolves the full-body BLP for (race, sex, skinColor) — the path the renderer
-    /// applies to the body-skin batches (value = the real build-5875 row for Human male skinColor 3).
+    /// The value is the shipped Human male skinColor 3 row.
     #[test]
     fn base_skin_texture_resolves() {
         let mut sections = HashMap::new();
@@ -820,7 +586,6 @@ mod tests {
         assert_eq!(cs.skin_texture(1, 0, 99), None, "absent color → no texture");
     }
 
-    /// A bare [`ItemDisplay`] carrying only the region textures and geoset groups a test cares about.
     fn worn(regions: [Option<&str>; 8], geoset_groups: [u32; 3]) -> ItemDisplay {
         ItemDisplay {
             region_textures: regions.map(|r| r.map(str::to_string)),
@@ -829,17 +594,12 @@ mod tests {
         }
     }
 
-    /// Legwear + footwear + a chest, named so the cases below read as outfits.
+    /// Region textures for LegUpper and a named LegLower.
     fn leg(tex: &str) -> [Option<&str>; 8] {
         [None, None, None, None, None, Some("lu"), Some(tex), None]
     }
 
-    /// [`equip_blits`] is the composite's whole equipment law, so the two things a reported outfit
-    /// defect turns on are pinned here: **which** slots reach a tile, and in **what cell order**.
-    ///
-    /// The `[0x803bf8]` value is a **default**, not a fixed priority (wow-re RF-0088 §5): the layer's
-    /// chooser may overrule it from the item's `geosetGroup`, and the row is walked by ascending cell
-    /// with later covering earlier. Reading it as a fixed priority is what shipped **B327**.
+    /// The `[0x803bf8]` cell is a default the ArmLower chooser (`0x479210`) overrules.
     #[test]
     fn equip_blits_places_each_slot_in_its_chooser_cell() {
         let plain_chest = worn(
@@ -899,8 +659,7 @@ mod tests {
             [1, 0, 0],
         );
 
-        // ArmLower (`0x479210`): plain items take the table (shirt 0, chest 1, wrist 2, gloves 3);
-        // a glove/sleeve geoset lifts gloves to 6 and the chest to 5, clear of the plain cells.
+        // Plain items take the table's cells; geoset gloves go to 6, a sleeved chest to 5.
         let eq = [
             None,
             Some(&plain_chest),
@@ -939,11 +698,7 @@ mod tests {
         );
     }
 
-    /// The guild tabard's three layers (decision 1704). Two facts, and they are the whole law:
-    /// the emblem installs **only** over a tabard whose display asks for it
-    /// ([`ItemDisplay::takes_guild_emblem`]), and when it does it takes cells 2/3/4 of layers 3 and
-    /// 4 — **including the cell the tabard garment itself had**, because the client clears 4→2 and
-    /// refills all three (wow-re RF-0086/RF-0088).
+    /// The emblem installs only over a flagged tabard, taking cells 2/3/4 of layers 3 and 4.
     #[test]
     fn the_guild_emblem_replaces_the_tabard_it_is_worn_on() {
         let torso = [
@@ -997,8 +752,6 @@ mod tests {
             v.iter().map(|(l, c, t)| (*l, *c, t.to_string())).collect()
         };
 
-        // Worn alone with a guild: background/border/symbol, ascending, on BOTH torso layers — and
-        // the garment's own `tabard_tu`/`tabard_tl` are gone, not stacked under.
         let eq = [
             None,
             None,
@@ -1021,15 +774,12 @@ mod tests {
             ]),
             "the emblem owns cells 2/3/4 of the two torso layers, the tabard's own art none"
         );
-        // No guild (or the query hasn't answered yet) — the garment keeps its own art. This is the
-        // look a guildless player wearing a Guild Tabard gets, and the look everyone gets for the
-        // frames between spawning and `SMSG_GUILD_QUERY_RESPONSE`.
+        // No guild, or no `SMSG_GUILD_QUERY_RESPONSE` yet: the garment keeps its art.
         assert_eq!(
             cells(&equip_blits(&eq, None, false)),
             want(&[(3, 4, "tabard_tu"), (4, 4, "tabard_tl")])
         );
-        // A tabard that does not ask for the emblem keeps its art even for a guilded wearer: the
-        // gate is the DISPLAY's flag, not "does this player have a guild".
+        // An unflagged tabard keeps its art for a guilded wearer.
         let plain = [
             None,
             None,
@@ -1044,11 +794,8 @@ mod tests {
             cells(&equip_blits(&plain, Some(emblem), false)),
             want(&[(3, 4, "tabard_tu"), (4, 4, "tabard_tl")])
         );
-        // And no tabard at all is no emblem, however guilded the wearer.
         assert!(equip_blits(&[None; 8], Some(emblem), false).is_empty());
 
-        // Under a shirt: the shirt keeps cell 0, the emblem stacks above it — and nothing reaches
-        // the arm layers, which the shirt still owns alone.
         let eq = [
             Some(&shirt),
             None,
@@ -1076,17 +823,7 @@ mod tests {
         );
     }
 
-    /// The six filenames an emblem builds, byte-for-byte — the one place a `%02d` transcription
-    /// error would show up as "the crest is just missing" and nothing else. Three cases:
-    ///
-    /// - a real crest, with the **two-digit** padding the format string's `%02d` gives;
-    /// - a three-digit style, which `%02d` does **not** truncate (170 emblem styles ship, so
-    ///   `Emblem_169_…` is a real file and a `{:02.2}`-shaped mistake would break the top third of
-    ///   the table);
-    /// - the **undesigned** guild, whose five `-1`s render as `-1` and resolve to nothing — which
-    ///   is why [`GuildEmblem`] is signed. Casting through unsigned would build
-    ///   `Emblem_4294967295_…`: also a miss, but for the wrong reason and off a value that could
-    ///   collide with a real index if anything ever clamped it.
+    /// The client's `%02d` names: padded, a three-digit style kept whole, and `-1` kept signed.
     #[test]
     fn emblem_layer_paths_are_the_clients_own_format() {
         let e = GuildEmblem {
@@ -1109,7 +846,6 @@ mod tests {
             "Textures\\GuildEmblems\\Emblem_07_03_TL_U.blp",
             "the TorsoLower half is the same name with the other tag"
         );
-        // `%02d` is a MINIMUM width, not a truncation — the 170th emblem style is three digits.
         assert_eq!(
             EmblemLayer::Symbol.path(
                 &GuildEmblem {
@@ -1121,7 +857,6 @@ mod tests {
             ),
             "Textures\\GuildEmblems\\Emblem_169_16_TU_U.blp"
         );
-        // A guild that never bought a tabard: `-1` in all five, and no file for any of them.
         let none = GuildEmblem {
             emblem_style: -1,
             emblem_color: -1,
@@ -1140,12 +875,7 @@ mod tests {
         );
     }
 
-    /// The `-1` guard (wow-re `rf89` §Q6). A guild that has never designed a tabard carries the
-    /// sentinel, and the crest must not install **at all** — not "install and resolve to nothing",
-    /// which is the failure this pins: the plan takes cell 4 away from the garment before the file
-    /// lookup happens, so painting through the sentinel leaves a blank tabard rather than the
-    /// default one. The reference bails on the **first** `-1` of the five, so a half-designed
-    /// record (impossible from its own designer UI, but the wire is the server's) is also nil.
+    /// The `-1` guard (`0x6d6d20`): any one `-1` of the five means no crest.
     #[test]
     fn an_undesigned_guild_has_no_crest_to_paint() {
         let designed = GuildEmblem {
@@ -1156,9 +886,8 @@ mod tests {
             background_color: 12,
         };
         assert!(designed.is_designed());
-        // Index 0 is a real index in every field — `Emblem_00_00` etc. all ship.
+        // Index 0 ships in every field.
         assert!(GuildEmblem::default().is_designed());
-        // The fresh-guild record: every field the sentinel.
         assert!(!GuildEmblem {
             emblem_style: -1,
             emblem_color: -1,
@@ -1167,7 +896,6 @@ mod tests {
             background_color: -1,
         }
         .is_designed());
-        // …and any ONE field is enough, which is the half the "all five" reading gets wrong.
         for spoil in [
             GuildEmblem {
                 emblem_style: -1,
@@ -1194,10 +922,7 @@ mod tests {
         }
     }
 
-    /// The underwear consequence, which is the one thing about the emblem that is *not* confined to
-    /// its own cells: TorsoUpper's bra is suppressed by a contribution in cells 0/1/**2**, and cell 2
-    /// is the guild tabard's **background** ([`UNDERWEAR_TILES`]). So a guild tabard hides the bra
-    /// and a plain one — which only ever reaches cell 4 — does not, exactly as wow-re RF-0086 says.
+    /// A guild tabard's background (cell 2) hides the bra, a plain tabard's cell 4 does not.
     #[test]
     fn only_a_guild_tabards_background_reaches_the_underwear_prefix() {
         let torso = [
@@ -1261,10 +986,7 @@ mod tests {
         );
     }
 
-    /// **B327, the carve.** On LegLower the chooser `0x4793f0` lifts a *robe* (chest `geosetGroup[2]`)
-    /// to cell 4 — above a boot's 3-or-2 — so footwear paints under a robe's skirt and can never
-    /// repaint its hem. The control that must not move: a **plain** chest stays at 1 and boots still
-    /// cover ordinary trousers, which is why the fixed-priority reading looked right for years.
+    /// LegLower (`0x4793f0`): a robe takes cell 4 over boots, while a plain chest stays under them.
     #[test]
     fn a_robe_outranks_footwear_on_leglower() {
         let robe = worn(leg("robe_ll"), [1, 0, 1]);
@@ -1308,13 +1030,11 @@ mod tests {
                 })
                 .collect()
         }
-        /// The expected cells, spelled the way the assertions read.
         fn cells(want: &[(i8, &str)]) -> Vec<(i8, String)> {
             want.iter().map(|(c, t)| (*c, t.to_string())).collect()
         }
 
-        // The report: a robe with sandals (no boot geoset) and with real boots. Either way the robe
-        // is last, so the skirt's hem is the robe's own art.
+        // A robe over sandals and over geoset boots: the robe is last either way.
         let eq = [
             None,
             Some(&robe),
@@ -1346,7 +1066,7 @@ mod tests {
             "boots under the robe too"
         );
 
-        // The control: a plain chest does NOT get lifted, so boots still cover ordinary trousers.
+        // A plain chest is not lifted, so boots still cover trousers.
         let eq = [
             None,
             Some(&plain_chest),
@@ -1363,9 +1083,7 @@ mod tests {
             "footwear still paints over trousers"
         );
 
-        // Trousers carrying their own robe bit: 3 under a robe chest, 4 when there is no robe over
-        // them. The first case collides with a geoset-boot's 3 — one cell holds one record, and the
-        // later writer (the boots) wins, exactly as `0x478900` overwrites.
+        // Robe-trousers take 3 under a robe chest, else 4.
         let eq = [
             None,
             Some(&robe),
@@ -1390,8 +1108,7 @@ mod tests {
         assert_eq!(g6(&eq), cells(&[(1, "chest_ll"), (4, "robetrouser_ll")]));
     }
 
-    /// `0x478ad0`'s two gates: a `-1` cell is a hard "this slot never touches this layer", and the
-    /// texture test is on the **string**, not the pointer — an empty name contributes nothing.
+    /// `0x478ad0`'s gates: a `-1` cell and an empty name contribute nothing.
     #[test]
     fn equip_blits_drops_ungated_and_empty_contributions() {
         let odd = worn(
@@ -1415,10 +1132,7 @@ mod tests {
         );
     }
 
-    /// **B326.** The region filename resolves `_U` FIRST and falls back to the wearer's gender letter
-    /// only when `_U` is absent (wow-re RF-0088 §7) — the inverse of what benilla shipped. On the 43
-    /// basenames that carry both, the gendered art is dead: `Leather_A_02_Pant_LL_F` is 18 rows
-    /// shorter than its `_U`, and preferring it left a bare ring below a night elf female's knee.
+    /// `_U` comes before the gender letter (`0x476e20`); `Leather_A_02_Pant_LL` ships both.
     #[test]
     fn region_textures_resolve_unisex_before_the_gender_letter() {
         let female = equip_region_candidates(6, "Leather_A_02_Pant_LL", 1);
@@ -1431,11 +1145,10 @@ mod tests {
         );
         let male = equip_region_candidates(6, "Leather_A_02_Pant_LL", 0);
         assert!(male[0].ends_with("_U.blp") && male[1].ends_with("_M.blp"));
-        // There is no third attempt anywhere in the image — a bare name never resolves.
+        // No third attempt: a bare name never resolves.
         assert_eq!(male.len(), 2);
     }
 
-    /// A single-level RGBA helper for the blit test.
     fn chain(width: u32, height: u32, px: Vec<u8>) -> BlpMipChain {
         BlpMipChain {
             width,
@@ -1445,14 +1158,10 @@ mod tests {
         }
     }
 
-    /// `blit_over`: an opaque overlay REPLACEs the tile; an alpha overlay source-over blends; a fully
-    /// transparent texel leaves the base; pixels outside the tile are untouched.
     #[test]
     fn blit_over_replaces_blends_and_clamps() {
-        // 2×2 mid-grey opaque base (4 px of RGBA [128,128,128,255]).
         let mut dst = chain(2, 2, [128, 128, 128, 255].repeat(4));
 
-        // 1×1 opaque red at tile (0,0,1,1) → replaces pixel 0, leaves the rest.
         blit_over(&mut dst, &chain(1, 1, vec![255, 0, 0, 255]), (0, 0, 1, 1));
         assert_eq!(
             &dst.mips[0][0..4],
@@ -1465,7 +1174,7 @@ mod tests {
             "neighbour untouched"
         );
 
-        // 1×1 half-alpha blue at (1,1) → blends 50/50 with grey: R≈64, B≈191, stays opaque.
+        // Half-alpha blue over grey: R≈64, B≈191.
         blit_over(&mut dst, &chain(1, 1, vec![0, 0, 255, 128]), (1, 1, 1, 1));
         let px = &dst.mips[0][12..16];
         assert!((px[0] as i32 - 64).abs() <= 1, "blended R ≈ 128·(1−a)");
@@ -1475,17 +1184,12 @@ mod tests {
         );
         assert_eq!(px[3], 255, "over an opaque base the result stays opaque");
 
-        // A fully transparent overlay texel is a no-op (the base shows through).
         let before = dst.mips[0].clone();
         blit_over(&mut dst, &chain(1, 1, vec![1, 2, 3, 0]), (0, 0, 1, 1));
         assert_eq!(dst.mips[0], before, "transparent texel is a no-op");
     }
 
-    /// End-to-end regression on the **real** build-5875 files: compositing a Human-male body must yield
-    /// a 256² mip pyramid whose head (g8/g9) + pelvis (g5) tiles are overlaid from the base, while a
-    /// control tile that carries no naked-body overlay (g3) is untouched. Guards the section→tile map +
-    /// the CharSections schema against a silent break (a wrong tile or a shifted column would move/lose
-    /// these diffs). Skips when the client data isn't present.
+    /// On the shipped files a Human male's head and pelvis tiles change, and the torso does not.
     #[test]
     fn composite_body_overlays_land_on_real_human_male() {
         let data = crate::wow_data_or_skip!();
@@ -1514,21 +1218,16 @@ mod tests {
                 })
                 .count()
         };
-        // Face replaces the head tiles; pelvis replaces g5 — each should change most of its tile.
         assert!(changed(TILE_G9) > 4000, "face lower overlaid into g9");
         assert!(changed(TILE_G8) > 2000, "face upper overlaid into g8");
         assert!(changed(TILE_G5) > 4000, "pelvis overlaid into g5");
-        // The torso tile is the underwear's second column — and **no male row authors it** (the bra is
-        // female-only; every sectionType-4 male row leaves `TextureName[1]` empty), so a human male's g3
-        // must stay byte-identical to the base. The female half is the next test.
+        // No male underwear row authors `TextureName[1]`, the torso.
         assert_eq!(
             changed(TILE_G3),
             0,
             "no male underwear row authors the naked-torso column"
         );
 
-        // Hair-mesh texture (decision 0045): a real hairstyle resolves a `Hair…` BLP; the bald style
-        // (variation 0) has none. Guards the `SECTION_HAIR` constant + the type-3 row keying.
         let hair = cs
             .hair_texture(1, 0, 1, 0)
             .expect("hairStyle 1 has a hair texture");
@@ -1542,11 +1241,7 @@ mod tests {
             "bald style has no hair texture"
         );
 
-        // The type-6 MESH resolver's substitute (decision 0536, byte-verified wow-re `rf84`): when the
-        // selected style resolves nothing, the client's binder has already bound variation **1** and an
-        // empty name leaves that slot untouched. A bald orc/gnome male still wears a beard, and on those
-        // races the beard is geometry on the hair unit — so the blank bald row must not leave it
-        // untextured (the flat-white bug: decision 0157's fallback showing through).
+        // A bald orc or gnome male's beard is hair geometry, so bald still resolves a sheet.
         for (race, sex, name) in [(2u8, 0u8, "Orc"), (7, 0, "Gnome")] {
             let styled = cs
                 .hair_mesh_texture(race, sex, 1, 0)
@@ -1562,7 +1257,7 @@ mod tests {
                 bald.contains("Hair00_00"),
                 "{name} sheet is Hair00_00, got {bald:?}"
             );
-            // The fallback tracks hair COLOUR (the beard is hair-coloured), not just any row.
+            // The fallback keeps the hair colour.
             let bald_c2 = cs
                 .hair_mesh_texture(race, sex, 0, 2)
                 .unwrap_or_else(|| panic!("{name} bald at colour 2 resolves"));
@@ -1573,11 +1268,7 @@ mod tests {
             assert_ne!(bald, bald_c2, "{name} colour must change the sheet");
         }
 
-        // Human authors TWO distinct sheets per colour, which is exactly where the literal-1 substitute
-        // is load-bearing: a bald human male resolves variation 1's sheet specifically, not "whichever
-        // non-blank row we happened to find". The earlier interim searched for a unique non-blank
-        // variation and returned None here — behaviourally inert (a bald human's facial hair is a
-        // painted overlay, so there is no type-6 geometry to texture) but not the client's mechanism.
+        // Human authors two sheets per colour, so the literal variation 1 matters.
         let human_bald = cs
             .hair_mesh_texture(1, 0, 0, 0)
             .expect("the substitute resolves variation 1 even where a race authors several sheets");
@@ -1590,15 +1281,12 @@ mod tests {
             human_bald.contains("Hair03_00"),
             "human male variation 1 is the Hair03 sheet, got {human_bald:?}"
         );
-        // A real style is never touched by the substitute, on any race.
         assert_eq!(
             cs.hair_mesh_texture(1, 0, 1, 0),
             cs.hair_texture(1, 0, 1, 0)
         );
 
-        // Extra-skin texture (the tauren fur, M2 type 8): the type-0 row's SECOND column. Tauren male
-        // skinColor 0 resolves the real build-5875 `_Extra` BLP; a race that doesn't author the column
-        // (human) yields None — its models carry no type-8 batch.
+        // The extra skin, M2 type 8: tauren author it, humans do not.
         assert_eq!(
             cs.skin_extra_texture(6, 0, 0),
             Some("Character\\Tauren\\Male\\TaurenMaleSkin00_00_Extra.blp"),
@@ -1610,8 +1298,7 @@ mod tests {
             "human male authors no extra skin"
         );
 
-        // skinColor 0/1 must resolve the standard chargen skin, NOT the EXTRA-flagged `…_100/_101` row
-        // sharing the same colorIndex (the flags-precedence fix).
+        // Skin colours 0 and 1 resolve the standard row, not the `0x1`-flagged `…_100`/`_101`.
         assert_eq!(
             cs.skin_texture(1, 0, 0),
             Some("Character\\Human\\Male\\HumanMaleSkin00_00.blp"),
@@ -1623,20 +1310,14 @@ mod tests {
         );
     }
 
-    /// The underwear section spends **both** its texture columns (bug B325): `TextureName[0]` is the
-    /// pelvis (g5) and `TextureName[1]` the naked **torso** (g3) — the bra, authored only on the female
-    /// rows. Before this, a bare-chested female composited panties and nothing above them.
-    ///
-    /// The pin is byte-exact rather than a diff count: `…NakedTorsoSkin00_00.blp` is a 128×64 fully
-    /// opaque sheet (BLP alphaDepth 0 → the client's REPLACE), so if it lands at the right tile from its
-    /// own origin the composite's g3 rect must equal the file's mip 0 pixel-for-pixel. A wrong tile, a
-    /// wrong column, or a src-origin slip all break that equality.
+    /// The underwear's `TextureName[1]` is the female torso (g3), an opaque tile-sized sheet, so g3
+    /// must equal it byte for byte.
     #[test]
     fn composite_body_dresses_the_female_torso_underwear() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cs = CharSections::load(&mut chain).expect("load CharSections");
-        // Night elf female, skinColor 0 — the appearance the B325 report shipped a screenshot of.
+        // Night elf female, skin colour 0.
         let (race, sex, skin) = (4u8, 1u8, 0u8);
         assert_eq!(
             cs.tex(race, sex, SECTION_UNDERWEAR, 0, skin, 1),
@@ -1672,17 +1353,8 @@ mod tests {
         }
     }
 
-    /// The underwear is the tile's **fallback**, and only the group's TESTED columns suppress it
-    /// (wow-re RF-0086; the byte-derived prefix in [`UNDERWEAR_TILES`]). This is the discriminating
-    /// pin, because the shipped art cannot make it: a real chest or a real pair of pants repaints
-    /// its whole tile opaquely, so "the underwear was suppressed" and "the underwear was painted
-    /// over" produce the same pixels.
-    ///
-    /// So the fixture is a display that **occupies a region column while painting nothing** — its
-    /// texture name resolves to no shipped file, so `read_equip_region` finds nothing to blit while
-    /// the column is still taken. That is the client's own gate: `0x4772f0`/`0x4773a0` test the
-    /// composite *cell*, not the equipped item. The same name at a different bodyslot lands in a
-    /// different column, and the outcome flips — which is the whole claim.
+    /// Only the tested cells suppress the underwear (`0x4772f0`, `0x4773a0`). Real art would paint
+    /// over it either way, so the fixture's display takes a cell but names no shipped file.
     #[test]
     fn only_the_tested_equipment_columns_suppress_the_underwear() {
         let data = crate::wow_data_or_skip!();
@@ -1712,7 +1384,7 @@ mod tests {
         let (torso_sheet, pelvis_sheet) = (sheet(&torso), sheet(&pelvis));
         let (base_g3, base_g5) = (rect(&base, TILE_G3, 256), rect(&base, TILE_G5, 256));
 
-        // A display that TAKES the column without painting it (see the doc above).
+        // A display that takes the cell without painting it.
         let occupies = |layers: &[usize]| {
             let mut region_textures: [Option<String>; 8] = Default::default();
             for l in layers {
@@ -1723,7 +1395,7 @@ mod tests {
                 ..Default::default()
             }
         };
-        // bodyslot − 2: 0 shirt · 1 chest · 2 belt · 3 pants · 7 tabard.
+        // Slots, bodyslot − 2: 0 shirt, 1 chest, 2 belt, 3 pants, 7 tabard.
         let (shirt, chest, belt, pants, tabard) = (
             occupies(&[3]),
             occupies(&[3, 5]), // a robe reaches both groups
@@ -1739,8 +1411,6 @@ mod tests {
             e
         }
 
-        // Byte-exact, but reported as a texel count and a name — a raw 32 KiB `assert_eq!` dump of a
-        // 128×64 RGBA tile is unreadable, and the useful fact is *which* of the three it is not.
         let differing = |got: &[u8], want: &[u8]| {
             got.as_chunks::<4>()
                 .0
@@ -1758,35 +1428,35 @@ mod tests {
                 ("the bra", &torso_sheet),
                 ("the panties", &pelvis_sheet),
             ),
-            // Shirt is TorsoUpper column 0 — tested. Torso suppressed; the pelvis is a different group.
+            // The shirt is TorsoUpper cell 0, tested.
             (
                 "shirt",
                 worn(&[(0, &shirt)]),
                 ("bare skin", &base_g3),
                 ("the panties", &pelvis_sheet),
             ),
-            // A tabard occupies TorsoUpper too, but past the tested prefix: the bra still draws.
+            // A tabard's cell 4 is past the tested cells.
             (
                 "tabard",
                 worn(&[(7, &tabard)]),
                 ("the bra", &torso_sheet),
                 ("the panties", &pelvis_sheet),
             ),
-            // Legs is LegUpper column 0 — tested. Pelvis suppressed, torso untouched.
+            // Pants are LegUpper cell 0, tested.
             (
                 "pants",
                 worn(&[(3, &pants)]),
                 ("the bra", &torso_sheet),
                 ("bare skin", &base_g5),
             ),
-            // A belt is LegUpper column 2, past the prefix: the panties survive it.
+            // A belt is LegUpper cell 2, untested.
             (
                 "belt",
                 worn(&[(2, &belt)]),
                 ("the bra", &torso_sheet),
                 ("the panties", &pelvis_sheet),
             ),
-            // A robe reaches both groups at column 1, and suppresses both.
+            // A chest takes cell 1 of both.
             (
                 "chest",
                 worn(&[(1, &chest)]),
@@ -1812,21 +1482,13 @@ mod tests {
                 );
             }
         }
-        // The fixture only means something if the three expectations are actually distinguishable.
+        // The cases mean something only if the expectations differ.
         assert_ne!(torso_sheet, base_g3, "the bra differs from bare skin");
         assert_ne!(pelvis_sheet, base_g5, "the panties differ from bare skin");
     }
 
-    /// The guild emblem on the **real** files (decision 1704). Display **20621** is the row item
-    /// 5976 *Guild Tabard* wears, and the only guild-emblem display any 1.12.1 item template points
-    /// at. Three things this pins that the synthetic plan tests cannot:
-    ///
-    /// 1. the shipped row really does set the flag (so the gate is not vacuous on real data);
-    /// 2. all six `Textures\GuildEmblems\` names an emblem builds resolve, and each is authored
-    ///    **exactly tile-sized** — the RF-0067 overlay src convention (`src = (0,0)`, extent =
-    ///    the tile), which is what lets them blit from their own origin;
-    /// 3. the emblem repaints the two torso tiles and **nothing else** — no arm, leg, head or foot
-    ///    texel moves — and a different index set paints a different tabard.
+    /// On the shipped files display 20621 (item 5976, Guild Tabard) is flagged, its six emblem
+    /// files are tile-sized (`0x4770f0`), and the emblem repaints only the torso tiles.
     #[test]
     fn composite_body_paints_the_guild_emblem_on_the_real_tabard() {
         let data = crate::wow_data_or_skip!();
@@ -1853,7 +1515,6 @@ mod tests {
         let equipment: [Option<&ItemDisplay>; 8] =
             [None, None, None, None, None, None, None, Some(tabard)];
 
-        // (2) — every layer resolves, and each is authored at its tile's exact extent.
         for step in equip_blits(&equipment, Some(emblem), false) {
             let path = step
                 .candidates(0)
@@ -1869,7 +1530,6 @@ mod tests {
             );
         }
 
-        // (3) — the repaint is confined to the two torso tiles.
         let mut compose = |em: Option<GuildEmblem>| {
             cs.composite_body(&mut chain, 1, 0, 3, 0, 1, 0, 0, equipment, em, false)
                 .expect("composite ok")
@@ -1904,7 +1564,6 @@ mod tests {
             strays.first().map(|i| (i % 256, i / 256))
         );
 
-        // …and the indices are actually consumed: a different background is a different tabard.
         let other = compose(Some(GuildEmblem {
             background_color: 30,
             ..emblem
@@ -1914,11 +1573,7 @@ mod tests {
             "the background index must reach the file name"
         );
 
-        // **Background 29 ships UPPERCASE and has no lowercase sibling** — `BACKGROUND_29_TU_U.blp`
-        // is the one odd name in 6118 files (wow-re `rf89`). A case-SENSITIVE chain lookup would
-        // lose exactly one background colour on exactly one tile, which is the kind of defect that
-        // reads as "that guild's tabard is subtly wrong" and nothing else. Ours is insensitive;
-        // this is the tripwire that keeps it that way.
+        // Background 29 ships uppercase (`BACKGROUND_29_TU_U.blp`), so the lookup must ignore case.
         let odd = GuildEmblem {
             background_color: 29,
             ..emblem
@@ -1932,12 +1587,8 @@ mod tests {
         }
     }
 
-    /// Equipment layers on the **real** files (decision 0074): dressing the Human male in One's
-    /// starter kit (shirt 9891 / pants 9892 / boots 10141) must repaint exactly the tiles those
-    /// displays' region columns name — torso from the shirt, LegUpper from the pants, Foot from the
-    /// boots — and leave a tile no item touches (g2 Hand) byte-identical to the naked composite.
-    /// Also pins the boots-over-pants stacking on the shared LegLower tile (both contribute; the
-    /// priority table puts the boot layer on top, so g6 must differ from the pants-only composite).
+    /// The Human Warrior starter shirt, pants and boots (displays 9891, 9892, 10141) repaint their
+    /// tiles, leave Hand alone, and the boots cover the pants on LegLower.
     #[test]
     fn composite_body_equipment_layers_land_on_real_human_male() {
         let data = crate::wow_data_or_skip!();
@@ -1955,7 +1606,7 @@ mod tests {
                 .expect("base skin row present")
         };
         let naked = compose([None; 8]);
-        // bodyslot-2 indexing: shirt = slot 2 (idx 0), pants = slot 5 (idx 3), boots = slot 6 (idx 4).
+        // Indices are bodyslot − 2: shirt 0, pants 3, boots 4.
         let mut equipment: [Option<&ItemDisplay>; 8] = [None; 8];
         equipment[0] = Some(shirt);
         equipment[3] = Some(pants);
diff --git a/crates/benilla-formats/src/chat_channels.rs b/crates/benilla-formats/src/chat_channels.rs
index aba7e055..38e2a88d 100644
--- a/crates/benilla-formats/src/chat_channels.rs
+++ b/crates/benilla-formats/src/chat_channels.rs
@@ -1,31 +1,6 @@
-//! `ChatChannels.dbc` — the six built-in chat channels and, in their flags, **which ones the
-//! client joins by itself**.
-//!
-//! 1.12 has no server-side zone-channel join: vmangos's `Player::UpdateLocalChannels`
-//! (`src/game/Objects/Player.cpp:5121`) is an empty function whose whole body is the comment
-//! `// Updated client-side`. The client walks this table at world entry **and on every zone
-//! change** and sends `CMSG_JOIN_CHANNEL` for each auto-join row with the zone's name spliced into
-//! the row's pattern — one function, `ZoneChannelRefresh 0x49a210`, VERIFIED in wow-re
-//! `system/ui/scratch/zone-chat-channel-autojoin.md` (decision 0288 phase 6; the walk itself is
-//! this crate's consumer, `benilla_app::ui_chat::channels`).
-//!
-//! Layout — the real 5875 file, decoded here (662 bytes, 6 records × **21 × u32** cols, 138-byte
-//! string block): `ChannelID(0), Flags(1), FactionGroup(2), Name[8](3..10), NameMask(11),
-//! Shortcut[8](12..19), ShortcutMask(20)`. The whole shipped table, verbatim:
-//!
-//! | ID | flags | name pattern (enUS) | shortcut |
-//! |---|---|---|---|
-//! | 1 | `0x00003` | `General - %s` | `General` |
-//! | 2 | `0x0003B` | `Trade - %s` | `Trade` |
-//! | 22 | `0x10003` | `LocalDefense - %s` | `LocalDefense` |
-//! | 23 | `0x10004` | `WorldDefense` | `WorldDefense` |
-//! | 24 | `0x00000` | `LookingForGroup` | `LookingForGroup` |
-//! | 25 | `0x20032` | `GuildRecruitment - %s` | `GuildRecruitment` |
-//!
-//! The flag names are vmangos's ([`flags`], `src/game/Chat/Channel.h`). **Exactly rows 1, 2 and 22
-//! carry `INITIAL`** — and that is independently corroborated: the reference client's own
-//! `WTF/…/chat-cache.txt` persists `ZONECHANNELS 2097155` = `0x200003` = bits 0, 1 and 21, i.e.
-//! `1 << (ChannelID - 1)` for exactly those three. Two unrelated artifacts, one set.
+//! `ChatChannels.dbc`, the six built-in chat channels. The zone-channel join is the client's
+//! (vmangos's `Player::UpdateLocalChannels`, `Objects/Player.cpp:5121`, is empty): at world entry
+//! and every zone change `0x49a210` sends `CMSG_JOIN_CHANNEL` for each auto-join row.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -35,40 +10,39 @@ use crate::dbc::{parse, str_at, u32_at};
 
 const CHAT_CHANNELS: &str = "DBFilesClient\\ChatChannels.dbc";
 
-/// `ChatChannels.dbc` flag bits, named per vmangos `Channel::ChannelDBCFlags`
-/// (`src/game/Chat/Channel.h:107-116`) and checked against the shipped rows in the module table.
+/// `ChatChannels.dbc` flag bits, named as vmangos's `ChannelDBCFlags` (`Chat/Channel.h:107-116`).
 pub mod flags {
-    /// The client joins this channel on its own. Rows 1 (General), 2 (Trade), 22 (LocalDefense).
+    /// The client joins it on its own: General (1), Trade (2) and LocalDefense (22).
     pub const INITIAL: u32 = 0x00001;
-    /// The name carries a `%s` filled per zone — the channel is re-joined when the zone changes.
+    /// The name carries a `%s` filled per zone, so the channel is re-joined on a zone change.
     pub const ZONE_DEP: u32 = 0x00002;
     /// One channel for the whole realm (WorldDefense).
     pub const GLOBAL: u32 = 0x00004;
     /// The trade channel proper.
     pub const TRADE: u32 = 0x00008;
-    /// Only joined while inside a capital. Trade and GuildRecruitment carry both city bits.
+    /// Joined only inside a capital; Trade and GuildRecruitment carry both city bits.
     pub const CITY_ONLY: u32 = 0x00010;
-    /// Its twin — vmangos reads this one for its own `CHANNEL_FLAG_CITY`.
+    /// The second city bit; vmangos reads this one for its `CHANNEL_FLAG_CITY`.
     pub const CITY_ONLY2: u32 = 0x00020;
-    /// LocalDefense / WorldDefense.
+    /// LocalDefense and WorldDefense.
     pub const DEFENSE: u32 = 0x10000;
-    /// GuildRecruitment — needs a guild.
+    /// GuildRecruitment, which needs a guild.
     pub const GUILD_REQ: u32 = 0x20000;
-    /// LookingForGroup. Zero on the 1.12 row, so nothing carries it in this build.
+    /// LookingForGroup; the 1.12 row's flags are 0, so no row carries it.
     pub const LFG: u32 = 0x40000;
 }
 
 /// One `ChatChannels.dbc` row.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ChatChannelRow {
-    /// `ChannelID` — the number the client hands Lua as a chat event's **arg7** and as
-    /// `JoinChannelByName`'s first return (`ChatFrame.lua:786`, `:1379`).
+    /// `ChannelID`: a chat event's `arg7` and `JoinChannelByName`'s first return
+    /// (`ChatFrame.lua:786`, `:1379`).
     pub id: u32,
-    /// See [`flags`].
+    /// Bits from [`flags`].
     pub flags: u32,
     /// The enUS name pattern, `%s` intact ("General - %s").
     pub pattern: String,
-    /// The enUS shortcut ("General") — the number-less, zone-less name.
+    /// The enUS shortcut ("General"), the name without number or zone.
     pub shortcut: String,
 }
 
@@ -83,47 +57,27 @@ impl ChatChannelRow {
         self.flags & flags::ZONE_DEP != 0
     }
 
-    /// Is this row **only joined inside a capital**? Gated on `CITY_ONLY` (`0x10`) alone — the
-    /// client tests the zone's own capital flag under this bit and no other
-    /// (`0x49a3b8`/`0x49a512`; wow-re `system/ui/scratch/zone-chat-channel-autojoin.md` §4).
+    /// Whether the row is joined only inside a capital; the client tests the zone's capital flag
+    /// under `CITY_ONLY` alone (`0x49a3b8`/`0x49a512`).
     pub fn is_city_only(&self) -> bool {
         self.flags & flags::CITY_ONLY != 0
     }
 
-    /// Is this the row a **guild** decides about — `GUILD_REQ` (`0x20000`), `GuildRecruitment`
-    /// alone in the 1.12 table? The client keys three things on it: the cascade's composer
-    /// `0x49f140` finds the row by this bit, and a manual `JoinChannelByName`/`LeaveChannelByName`
-    /// on it forces the auto-join option off (`0x49ed3d`/`0x49ef8f`; wow-re
-    /// `guild-recruitment-mode.md` §3/§5).
+    /// Whether this is the guild-gated row (`GUILD_REQ`), which the client finds by that bit
+    /// (`0x49f140`); a manual join or leave on it turns its auto-join off (`0x49ed3d`/`0x49ef8f`).
     pub fn is_guild_recruitment(&self) -> bool {
         self.flags & flags::GUILD_REQ != 0
     }
 
-    /// Does this row's `%s` take the shared **city** word instead of the zone's name?
-    ///
-    /// A different bit from [`Self::is_city_only`] — `CITY_ONLY2` (`0x20`) — and a different test
-    /// in the client (`0x49a308`/`0x49a4ea` pick the substitution on it, §3). Rows 2 and 25 carry
-    /// both bits, so the two questions have the same answer on the 1.12 table; they are kept apart
-    /// because the client keeps them apart.
+    /// Whether the `%s` takes the city word, not the zone's name: `CITY_ONLY2`, tested apart from
+    /// [`Self::is_city_only`] (`0x49a308`/`0x49a4ea`) though 1.12 rows set both bits or neither.
     pub fn takes_city_name(&self) -> bool {
         self.flags & flags::CITY_ONLY2 != 0
     }
 
-    /// The joinable name for a player standing in `zone_name`, with `city_name` the shared capital
-    /// word.
-    ///
-    /// The `%s` is the **zone**'s display name for an ordinary zone-dependent row
-    /// ("General - Elwynn Forest") and `city_name` for a city-named one ("Trade - City") — one
-    /// trade channel shared by every capital rather than one per city.
-    ///
-    /// **"City" is DBC data, not a string literal**, VERIFIED at the bytes (wow-re
-    /// `zone-chat-channel-autojoin.md` §3): the client keeps the word at `0xb4e4f0`, whose single
-    /// writer `0x4985fd` is a load-time scan of `AreaTable.dbc` for the row with `Flags & 0x200`.
-    /// In the shipped 5875 table that is **exactly one row — id 3459, `AreaName[enUS] = "City"`**
-    /// (asserted in [`tests`] against the real file), which is precisely why searching `WoW.exe`
-    /// for `City\0` finds nothing at all. The caller passes the word in rather than this crate
-    /// re-reading `AreaTable.dbc`, because the auto-join walk already holds that catalog — and
-    /// passing it keeps the localized name localized.
+    /// The joinable name in `zone_name`, or with `city_name` on a city-named row ("Trade - City").
+    /// The city word is data: `0x4985fd` stores at `0xb4e4f0` the name of the one `AreaTable.dbc`
+    /// row with `Flags & 0x200` (id 3459, "City").
     pub fn joinable_name(&self, zone_name: &str, city_name: &str) -> String {
         if !self.is_zone_dependent() {
             return self.pattern.clone();
@@ -144,8 +98,7 @@ pub struct ChatChannelsCatalog {
 }
 
 impl ChatChannelsCatalog {
-    /// Build a catalog from rows directly — for tests that must run without an install (the real
-    /// six rows are asserted against the shipped DBC by [`tests`]).
+    /// A catalog from rows given directly, for tests that run without an install.
     pub fn from_rows(rows: Vec<ChatChannelRow>) -> Self {
         ChatChannelsCatalog { rows }
     }
@@ -158,18 +111,13 @@ impl ChatChannelsCatalog {
         self.rows.is_empty()
     }
 
-    /// The rows the client joins by itself, in table order ([`ChatChannelRow::is_auto_join`]).
+    /// The rows the client joins by itself, in table order.
     pub fn auto_join_rows(&self) -> impl Iterator<Item = &ChatChannelRow> {
         self.rows.iter().filter(|r| r.is_auto_join())
     }
 
-    /// The row a composed channel name belongs to, or `None` for a custom channel.
-    ///
-    /// Matched the way the server matches it — vmangos's `GetChannelEntryFor(std::string const&)`
-    /// (`src/game/Database/DBCStores.cpp:531`) strips the `%s` from each pattern and asks whether
-    /// the name *contains* what is left, so `"General - Elwynn Forest"` resolves to ChannelID 1.
-    /// Matching the server's own rule is the point: it is what decides whether the channel we
-    /// joined is the built-in one both clients land in.
+    /// The row a composed name belongs to, matched as the server does: the name contains the
+    /// pattern minus its `%s` (`GetChannelEntryFor`, `Database/DBCStores.cpp:531`).
     pub fn row_for_name(&self, name: &str) -> Option<&ChatChannelRow> {
         let lower = name.to_ascii_lowercase();
         self.rows.iter().find(|r| {
@@ -178,8 +126,7 @@ impl ChatChannelsCatalog {
         })
     }
 
-    /// The `ChatChannels.dbc` ChannelID behind a composed name — a chat event's **arg7**.
-    /// 0 for a custom channel, which is what the reference passes there too.
+    /// The ChannelID behind a composed name, a chat event's `arg7`; 0 for a custom channel.
     pub fn zone_channel_id(&self, name: &str) -> u32 {
         self.row_for_name(name).map_or(0, |r| r.id)
     }
@@ -224,9 +171,6 @@ pub fn load_chat_channels_catalog(chain: &mut Chain) -> Result<ChatChannelsCatal
 mod tests {
     use super::*;
 
-    /// The real shipped table, row for row — the module doc's table asserted rather than trusted,
-    /// because every channel name benilla sends on the wire is composed from these six rows.
-    /// Skips without client data.
     #[test]
     fn the_real_table_is_the_six_documented_rows() {
         let data = crate::wow_data_or_skip!();
@@ -250,13 +194,11 @@ mod tests {
             ]
         );
 
-        // The auto-join set is exactly the `chat-cache.txt` ZONECHANNELS mask 0x200003 — two
-        // artifacts, one answer (module doc).
+        // The auto-join set is the reference's `chat-cache.txt` `ZONECHANNELS` mask.
         let mask: u32 = cat.auto_join_rows().map(|r| 1 << (r.id - 1)).sum();
         assert_eq!(mask, 0x0020_0003, "General + Trade + LocalDefense");
     }
 
-    /// Name composition, both arms, and the reverse lookup the server also does.
     #[test]
     fn names_compose_per_zone_and_resolve_back_to_their_row() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/chr_classes.rs b/crates/benilla-formats/src/chr_classes.rs
index a9f738b2..15c6399b 100644
--- a/crates/benilla-formats/src/chr_classes.rs
+++ b/crates/benilla-formats/src/chr_classes.rs
@@ -1,79 +1,19 @@
-//! `ChrClasses.dbc` — the per-class client table, and the three columns anything here reads off
-//! it.
+//! `ChrClasses.dbc`, the per-class table, narrowed to the three columns the reference reads off
+//! its class-indexed record table (`0xc0def4`, max id `0xc0def8`, loader `0x542360`).
 //!
-//! One file, one parse. Two of the three are answers the *engine* gives Lua about a class and the
-//! third is the talent spell-modifier gate's right-hand side; all three are read by address off
-//! the same class-indexed record table at `ds:0xc0def4`, bounded by the max id at `ds:0xc0def8`
-//! (store `0xc0deec`, loader `0x542360`, filename `0x85838c`).
+//! Field 4, the pet name token: the second return of `HasPetSpells` (`0x4b4410`), `"PET"` on every
+//! row but the Warlock's `"DEMON"`. FrameXML resolves it with `getglobal("PET_TYPE_"..token)`
+//! (`SpellBookFrame.lua:173`), so the token is a key, never display text, and is not localized.
 //!
-//! ## Field 4 — the pet name token
+//! Field 15, the class spell family: a talent modifier applies to a spell only when its
+//! `SpellFamilyName` (`Spell.dbc` column 160) equals the local player's (`GetSpellModifiers`,
+//! `0x6e6b30`), cached in `[0xcecaac]` by its one non-zeroing writer, `0x6e6ca0` (called from
+//! `0x5debcc`). The shipped values are vmangos `SpellFamilyNames`.
 //!
-//! `HasPetSpells()`'s second return, and the only thing that decides whether the spellbook's
-//! second tab reads "Pet" or "Demon" (decision 1032). `HasPetSpells 0x4b4410` pushes it verbatim:
-//!
-//! ```text
-//! 0x4b445d  eax = [player + 0x110]                  ; the descriptor fields
-//! 0x4b4463  eax = byte [fields + 0x79]              ; UNIT_FIELD_BYTES_0 byte 1 = the CLASS
-//! 0x4b446b  if (class < 0 || class > [0xc0def8]) -> the out-of-range arm
-//! 0x4b4473  ecx = [0xc0def4]                        ; the class record table
-//! 0x4b4479  eax = ecx[class]                        ; 1-BASED — index 0 is never a class
-//! 0x4b447c  edx = [rec + 0x10]                      ; <- the token string
-//! 0x4b44a6  (player did not resolve) edx = "PET"    ; the literal 0x846a40
-//! ```
-//!
-//! **`rec + 0x10` is field 4, and the file says which field that is**: dumped from the real 5875
-//! `ChrClasses.dbc` (9 rows, 17 columns, 0x44-byte records), field 4 is `"PET"` in every row except
-//! Warlock (id 9), which is `"DEMON"`. Field 5 is the class name (`Warrior`/`Paladin`/…), so a
-//! one-column slip would put "Warlock" on the tab — plausible enough to ship, which is why
-//! [`tests`] anchors both columns.
-//!
-//! FrameXML then does `getglobal("PET_TYPE_"..token)` (`SpellBookFrame.lua:173`) against
-//! `PET_TYPE_PET = "Pet"` / `PET_TYPE_DEMON = "Demon"` (`GlobalStrings.lua:3057-3058`) — so the
-//! token is a **key**, never display text, and it is right that it is not localized here.
-//!
-//! ## Field 16 — the relic-slot flag
-//!
-//! `UnitHasRelicSlot 0x519e50` reads it and nothing else. Same walk — typemask bit 4 (PLAYER),
-//! `UNIT_FIELD_BYTES_0` byte 1 for the class, bound against `0xc0def8`, index `0xc0def4` — then:
-//!
-//! ```text
-//! 0x519ebb  mov ecx,[row + 0x40]                    ; <- field 16, the relic flag
-//! ```
-//!
-//! Non-zero pushes the **number 1.0**; zero pushes **nil** (never `false`). There is no `cmp`
-//! against a class id anywhere in the function: 1.12 is entirely data-driven here, and this table
-//! is the data. In the shipped file the column is 1 for exactly **2 Paladin, 7 Shaman, 11 Druid**
-//! — Libram, Totem, Idol.
-//!
-//! **Why this was believed impossible, and the trap worth keeping.** The base `dbc.MPQ` copy of
-//! this file is **16 fields / 64-byte records and has no field 16 at all**; `patch.MPQ` supersedes
-//! it with the 17-field / 68-byte version, and the 5875 loader asserts exactly those two numbers
-//! (`0x54240e`/`0x542446`), so the patch copy is the only one the client can read. Read the base
-//! archive alone — or an early-vanilla 16-column struct — and the flag simply is not there, which
-//! is how "the relic slot post-dates 1.12" became a settled belief in this codebase and stayed one
-//! across two decision records. It is false; see decision 1796. [`CHR_CLASSES_FIELDS`] is what
-//! keeps us on the patch copy, and it is load-bearing, not defensive.
-//!
-//! The flag is engine-enforced, not a UI conceit: `IsValidForSlot 0x5da1d0`'s `slot == 0x11` leg
-//! requires `(InventoryType == 28 RELIC) == hasRelicSlot`, so **INVSLOT 17 takes a relic for those
-//! three classes and a ranged weapon for everyone else** — one slot, two meanings. 1.12 has no
-//! *separate* relic slot, which is the one true fragment inside the old belief.
-//!
-//! ## Field 15 — the class's spell family
-//!
-//! `GetSpellModifiers 0x6e6b30`'s second gate: a talent modifier applies to a spell only when that
-//! spell's own `SpellFamilyName` (`Spell.dbc` column 160) equals the LOCAL PLAYER's class family,
-//! which the client caches in the global `[0xcecaac]`. That global has exactly one
-//! non-zeroing writer, `0x6e6ca0` (sole caller `0x5debcc`, the local-player create-finalise): it
-//! takes `UNIT_FIELD_BYTES_0` byte 1 — the class, the same walk both sections above make — and
-//! stores `ChrClasses[class] + 0x3c`, i.e. **field 15** (wow-re
-//! `system/spell/scratch/spellmod-table-law.md` §8).
-//!
-//! Anchored on the shipped 5875 file, which is also a could-have-failed control on the column: the
-//! nine rows read Warrior 4, Paladin 10, Hunter 9, Rogue 8, Priest 6, Shaman 11, Mage 3, Warlock 5,
-//! Druid 7 — the vmangos `SpellFamilyNames` values exactly, in an order no neighbouring column
-//! could reproduce (field 14 is a name-flags word reading 8323199 on every row, field 16 is the
-//! relic flag above).
+//! Field 16, the relic-slot flag, read by `UnitHasRelicSlot` (`0x519e50`) and nothing else: no
+//! class id is compared, the table is the data. It is set for Paladin, Shaman and Druid, and
+//! `IsValidForSlot` (`0x5da1d0`) enforces it: INVSLOT 17 takes a relic (`InventoryType` 28) for
+//! those three and a ranged weapon for everyone else.
 
 use std::collections::HashMap;
 
@@ -85,27 +25,24 @@ use crate::dbc::{parse, str_at, u32_at};
 
 const CHR_CLASSES: &str = "DBFilesClient\\ChrClasses.dbc";
 
-/// `ChrClasses.dbc`'s column count in 5875 (the header's `field_count`; `benilla-dbc` enforces it).
-///
-/// This is the **patch** copy's shape. The base archive's 16-field copy fails the check rather
-/// than silently reading one column short of the relic flag — see the module header.
+/// The patch copy's column count, which `benilla-dbc` enforces as the reference loader does
+/// (`0x54240e`, `0x542446`): the base archive's 16-column copy lacks the relic flag and is refused,
+/// never read one column short.
 const CHR_CLASSES_FIELDS: usize = 17;
 
-/// The pet-name-token column — byte `0x10` in the client's own record read, i.e. field 4.
+/// Field 4, read at `rec + 0x10` by `HasPetSpells` (`0x4b447c`).
 const PET_NAME_TOKEN_FIELD: usize = 0x10 / 4;
 
-/// The relic-slot column — byte `0x40` in `UnitHasRelicSlot`'s read, i.e. field 16.
+/// Field 16, read at `row + 0x40` by `UnitHasRelicSlot` (`0x519ebb`).
 const RELIC_SLOT_FIELD: usize = 0x40 / 4;
 
-/// The class spell-family column — byte `0x3c` in `0x6e6ca0`'s read, i.e. field 15. See the module
-/// header for the walk and the shipped-file anchor.
+/// Field 15, read at `+0x3c` by `0x6e6ca0`.
 const SPELL_FAMILY_FIELD: usize = 0x3c / 4;
 
-/// The literal the client pushes when the player object does not resolve (`0x846a40`). Also the
-/// value nine of the ten class rows carry, which is why an unloaded table degrades invisibly.
+/// The literal the reference pushes when the player does not resolve (`0x846a40`). Every class but
+/// the Warlock carries it too, so an unloaded table degrades invisibly.
 pub const PET_NAME_TOKEN_FALLBACK: &str = "PET";
 
-/// One class row, narrowed to the columns anything reads.
 #[derive(Debug, Clone)]
 struct ChrClass {
     pet_name_token: Option<String>,
@@ -113,14 +50,13 @@ struct ChrClass {
     spell_family: u32,
 }
 
-/// `ChrClasses.dbc` → class id ⇒ the columns we read.
+/// `ChrClasses.dbc`'s read columns by class id.
 #[derive(Debug, Default, Clone)]
 pub struct ChrClasses(HashMap<u32, ChrClass>);
 
 impl ChrClasses {
-    /// The pet name token for a class id, or the client's own [`PET_NAME_TOKEN_FALLBACK`] for a
-    /// class with no row. Mirrors `0x4b44a6`: the reference never answers nil here, only ever a
-    /// string.
+    /// `HasPetSpells`' second return: always a string, never nil, and the literal
+    /// [`PET_NAME_TOKEN_FALLBACK`] for a class with no row (`0x4b44a6`).
     pub fn pet_name_token(&self, class: u32) -> &str {
         self.0
             .get(&class)
@@ -128,22 +64,16 @@ impl ChrClasses {
             .unwrap_or(PET_NAME_TOKEN_FALLBACK)
     }
 
-    /// Whether a class id's INVSLOT 17 is a relic slot — `UnitHasRelicSlot`'s whole body.
-    ///
-    /// A class with no row answers `false`, which is the reference's own shape: its bound check
-    /// against `0xc0def8` falls to the nil leg, and an unloaded table reads every class as an
-    /// ordinary ranged wielder rather than inventing a relic slot for one.
+    /// Whether the class's INVSLOT 17 is a relic slot, `UnitHasRelicSlot` whole. A class with no
+    /// row answers false, as the reference's bound check against `0xc0def8` falls to its nil leg.
     pub fn has_relic_slot(&self, class: u32) -> bool {
         self.0.get(&class).is_some_and(|c| c.has_relic_slot)
     }
 
-    /// The class's spell family — the value the reference caches in `[0xcecaac]` and compares
-    /// every spell's `SpellFamilyName` against before any talent modifier may apply.
-    ///
-    /// A class with no row answers `0`, which is the reference's own degraded state: `0x6e7150`
-    /// zeroes the global at world-enter (`6e7317`, `esi = 0`) and it stays 0 until the local
-    /// player resolves — and `GetSpellModifiers`' first conjunct (`SpellFamilyName != 0`) exists
-    /// precisely so nothing matches during that window.
+    /// The class spell family, which the reference caches in `[0xcecaac]` and matches against a
+    /// spell's `SpellFamilyName` before a talent modifier applies. A class with no row answers 0,
+    /// the global's value from world-enter (`0x6e7150`) until the player resolves, which the
+    /// gate's `SpellFamilyName != 0` conjunct makes match nothing.
     pub fn spell_family(&self, class: u32) -> u32 {
         self.0.get(&class).map_or(0, |c| c.spell_family)
     }
@@ -156,8 +86,8 @@ impl ChrClasses {
 fn schema() -> Schema {
     let mut s = Schema::new("ChrClasses");
     for i in 0..CHR_CLASSES_FIELDS {
-        // Only the two read columns are typed; everything else stays an opaque dword. The class
-        // NAME block (field 5 up) is deliberately not decoded — nothing here displays it.
+        // Only the token is a string; the rest, the class name block from field 5 included, stay
+        // opaque dwords.
         let ty = if i == PET_NAME_TOKEN_FIELD {
             FieldType::String
         } else {
@@ -198,9 +128,7 @@ mod tests {
         Some(crate::open_chain(&data).expect("open chain"))
     }
 
-    /// The real 5875 table, byte-anchored on the one column that matters. The neighbouring field
-    /// holds the class NAME, so a one-column slip reads "Warlock"/"Hunter" — which would still
-    /// resolve a `PET_TYPE_*` global lookup to nil and blank the tab, i.e. fail silently.
+    /// Field 5 holds the class name, so a one-column slip would blank the spellbook tab silently.
     #[test]
     fn warlocks_pet_is_a_demon_and_everyone_elses_is_a_pet() {
         let Some(mut chain) = chain() else { return };
@@ -210,15 +138,11 @@ mod tests {
         for (class, who) in [(1, "Warrior"), (3, "Hunter"), (11, "Druid")] {
             assert_eq!(t.pet_name_token(class), "PET", "{who}");
         }
-        // 6 and 10 have no row in 1.12 (Death Knight / Monk arrive later); the client's own
-        // out-of-range arm answers the literal, and so does this.
+        // 6 and 10 have no row in 1.12; the reference's out-of-range arm answers the literal.
         assert_eq!(t.pet_name_token(6), PET_NAME_TOKEN_FALLBACK);
         assert_eq!(t.pet_name_token(0), PET_NAME_TOKEN_FALLBACK);
     }
 
-    /// Field 16, anchored against the shipped file the same way — and against the belief it
-    /// replaces. Three classes, and exactly three: this asserts the whole column, because a
-    /// half-right answer here (say, Paladin alone) is the shape the old claim would decay into.
     #[test]
     fn libram_totem_and_idol_are_the_three_relic_classes() {
         let Some(mut chain) = chain() else { return };
@@ -236,15 +160,13 @@ mod tests {
         ] {
             assert!(!t.has_relic_slot(class), "{who} wields a ranged weapon");
         }
-        // No row, and no invented slot — the reference's nil leg.
+        // No row: the reference's nil leg.
         assert!(!t.has_relic_slot(6));
         assert!(!t.has_relic_slot(0));
     }
 
-    /// Field 15, the spell-family gate's right-hand side. The whole column is asserted because
-    /// that is what makes it a column pin rather than a coincidence: nine distinct values in nine
-    /// rows, each matching the vmangos `SpellFamilyNames` enum, is a shape no neighbour has
-    /// (field 14 is 8323199 on every row, field 16 is the three-row relic flag).
+    /// The whole column pins field 15: nine distinct values matching vmangos `SpellFamilyNames`
+    /// are a shape no neighbour has (field 14 is the class's file name, field 16 the relic flag).
     #[test]
     fn every_class_row_carries_its_vmangos_spell_family() {
         let Some(mut chain) = chain() else { return };
@@ -262,7 +184,7 @@ mod tests {
         ] {
             assert_eq!(t.spell_family(class), family, "{who}");
         }
-        // No row: the reference's zeroed global, which conjunct 1 of the gate refuses.
+        // No row: the reference's zeroed global, which the gate's first conjunct refuses.
         assert_eq!(t.spell_family(6), 0);
         assert_eq!(t.spell_family(0), 0);
     }
diff --git a/crates/benilla-formats/src/cinematics.rs b/crates/benilla-formats/src/cinematics.rs
index 91b898a3..f20c6e8a 100644
--- a/crates/benilla-formats/src/cinematics.rs
+++ b/crates/benilla-formats/src/cinematics.rs
@@ -1,79 +1,18 @@
-//! `CinematicSequences.dbc` + `CinematicCamera.dbc` — the in-engine cinematic fly-bys, and the
+//! `CinematicSequences.dbc` and `CinematicCamera.dbc`: the in-engine cinematic fly-bys and the
 //! world-space camera path each one resolves to.
 //!
-//! A cinematic in 1.12 is **not** a movie file. `SMSG_TRIGGER_CINEMATIC` carries a
-//! `CinematicSequences.dbc` id; the row names up to eight `CinematicCamera.dbc` cameras; each of
-//! those names a `Cameras\*.m2` whose single [`M2Camera`](benilla_m2::M2Camera) record *is* the
-//! shot — an eye path, a look-at path and a roll, keyed over a timeline in the model's own local
-//! frame — plus the world origin and facing to plant that frame at. The client flies its view
-//! along it and the world renders normally underneath. (The pre-rendered `.avi` under
-//! `Data\<locale>\Interface\Cinematics` is the *other* thing, the opening movie; it is not this.)
+//! A cinematic is not a movie. `SMSG_TRIGGER_CINEMATIC` carries a sequence id, the sequence names
+//! up to eight camera rows, and each row names a `Cameras\*.m2` whose one
+//! [`M2Camera`](benilla_m2::M2Camera) record is the shot: eye, look-at and roll tracks in the
+//! model's local frame, planted at the row's world origin and facing. The world renders normally
+//! underneath. A shot ranges far from its origin (the Tauren intro starts 1741 yd out), and the
+//! server re-anchors object visibility to the flying camera while one runs (vmangos
+//! `Player::UpdateCinematic`), so the world streams from the camera, not the avatar.
 //!
-//! **The shipped tables, dumped 2026-08-29 (VERIFIED — the bytes, not a wiki):**
-//! `CinematicSequences.dbc` is `10 × 10 fields × 40 B`: `ID · soundId · camera[8]`. Every shipped
-//! row uses exactly **one** camera and authors `soundId = 0`. `CinematicCamera.dbc` is
-//! `10 × 7 × 28 B`: `ID · model (string) · soundId · originX · originY · originZ · originFacing`.
-//! The model column ships `.mdx`; the archive file is `.m2` ([`camera_model_path`]). The ten rows
-//! are the eight race intros plus `PalantirOfAzora` and `Scry_cam`. Facing is **radians** — the
-//! shipped values include `3.14159` and `4.71239` (π and 3π/2) to five decimals, which no degree
-//! table would.
-//!
-//! **The world transform** — `world = origin + Rz(+facing)·local`, `z` straight through — is the
-//! one non-obvious step, and it is now settled twice over.
-//!
-//! It was first checked against an independent oracle rather than assumed: vmangos walks its own
-//! server-side copy of these paths (`Player::UpdateCinematic`) off a hand-built
-//! `cinematic_waypoints` table of sampled world positions, and our evaluated path lands on those
-//! samples (tens of yards over ~600-yard offsets, on a table whose z column is ground-level, not
-//! camera-level). The three sign/axis alternatives miss by 700–1800 yards. See
-//! [`CinematicPath::sample`].
-//!
-//! It is now **byte-verified too** (wow-re `ui/scratch/cinematic-camera-law.md`, a §5 with a
-//! Unicorn run of the binary's own bytes as arbiter), and the earlier round's contradicting
-//! answer is explained rather than left hanging. The client applies affines as a **row vector on
-//! the left** (`out = in·M`), and the stored 3×3 is `[[cos,sin,0],[−sin,cos,0],[0,0,1]]`. Read as
-//! a diagram acting on a *column* vector that is `Rz(−facing)` — which is what a matrix picture
-//! invites, and what the earlier worker reported. The client never applies it that way. The bytes
-//! and the oracle never actually disagreed.
-//!
-//! **The shipped corpus, read out of the ten `Cameras\*.m2` files** (`fov` radians, `d₀` = how far
-//! the shot's first eye position sits from its own origin, horizontally):
-//!
-//! | cam | model | fov | length | pos keys | roll | d₀ |
-//! |---|---|---|---|---|---|---|
-//! | 1 | PalantirOfAzora | 0.7854 | 14.9 s | 10 | const 0 | 205 yd |
-//! | 2 | FlybyUndead | **1.5708** | 102.0 s | 22 | 18 keys | 523 yd |
-//! | 122 | FlybyNightElf | 0.7854 | 102.0 s | 32 | 19 keys | 813 yd |
-//! | 142 | FlyByHuman | 0.7854 | 87.5 s | 20 | const 2π | 663 yd |
-//! | 162 | FlyByGnome | 0.7854 | 76.7 s | 27 | const 0 | 705 yd |
-//! | 182 | FlyByTroll | 0.7854 | 57.8 s | 21 | 12 keys | 39 yd |
-//! | 202 | FlyByTauren | 0.7854 | 70.3 s | 19 | 7 keys | 1741 yd |
-//! | 224 | Scry_cam | 0.7854 | 3.3 s | 1 | const 3π | 0 yd |
-//! | 234 | FlyByDwarf | 0.7854 | 59.6 s | 28 | const 2π | 652 yd |
-//! | 235 | FlybyOrc | 0.7854 | 70.2 s | 22 | 14 keys | 1100 yd |
-//!
-//! Three things there are load-bearing and none of them are guessable. **The Undead intro's FOV is
-//! 90°, not 45°** — a client that hard-coded the other nine's value would render that one shot at
-//! half the intended width. **Roll is authored around multiples of 2π rather than around 0**
-//! (`FlyByDwarf` holds a constant `6.2832`; `Scry_cam` holds `3π`), so it is an *angle to apply*,
-//! and a "roll is zero, skip it" shortcut happens to be right only by the identity `2π ≡ 0`; five
-//! of the ten genuinely animate it. And the shots **start far from their own origin** — a Tauren
-//! 1741 yards out — which is why the server re-anchors object visibility to the flying camera
-//! while one runs (decision 0196), and why the client has to stream the world from the *camera*
-//! and not the avatar for the duration.
-//!
-//! **The optics in this table are data, not the shot's framing** (decision 1711, off wow-re
-//! `ui/scratch/cinematic-camera-law.md`, VERIFIED). A 24-site census settles it: the M2 camera
-//! record's `fov`, `nearClip` and `farClip` are written at model load and read only by `0x7ac640`,
-//! which is reachable solely from the portrait and `<Model>` frame paths. **On the cinematic path
-//! nothing reads any of the three.** A fly-by is rendered through the *world camera's own* optics,
-//! re-stamped every frame.
-//!
-//! That dissolves the puzzle this note used to record: the authored clips are `0.22222` / `27.7778`
-//! (8/36 and 1000/36, identical on every shipped shot), and a 27.8-yard far plane would render the
-//! dwarf intro's mountains as empty sky. They are not world clips because they are not clips at
-//! all here — which is what two floats nobody consumes look like. They stay parsed because they
-//! are genuinely in the record and the portrait path does read them.
+//! The plant is `world = origin + Rz(+facing)·local`, z unchanged. The reference applies affines
+//! to a row vector on the left (`out = in·M`, `0x7bca80`), so its stored 3×3
+//! `[[cos,sin,0],[−sin,cos,0],[0,0,1]]` (`0x50c870`) is `Rz(+facing)`, though it reads as
+//! `Rz(−facing)` on a column vector.
 
 use std::collections::HashMap;
 
@@ -90,37 +29,32 @@ const CAMERAS: &str = "DBFilesClient\\CinematicCamera.dbc";
 /// How many camera slots a `CinematicSequences.dbc` row carries (fields 2..=9).
 pub const SEQUENCE_CAMERAS: usize = 8;
 
-/// One `CinematicSequences.dbc` row — what a `SMSG_TRIGGER_CINEMATIC` id resolves to.
+/// One `CinematicSequences.dbc` row, what a `SMSG_TRIGGER_CINEMATIC` id resolves to.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CinematicSequence {
     pub id: u32,
-    /// `soundId` (field 1). **Zero on every shipped row** — the sound a fly-by plays comes from
-    /// its *camera* row instead ([`CinematicCameraRow::sound_id`]).
+    /// `soundId` (field 1): 0 on every shipped row; a fly-by's sound is its camera row's.
     pub sound_id: u32,
     /// The camera ids to play, in order, trailing zeros dropped. Every shipped row holds one.
     pub cameras: Vec<u32>,
 }
 
-/// One `CinematicCamera.dbc` row — a shot: which path model, where to plant it, and the sound.
+/// One `CinematicCamera.dbc` row, a shot: its path model, where to plant it, and its sound.
 #[derive(Debug, Clone, PartialEq)]
 pub struct CinematicCameraRow {
     pub id: u32,
-    /// The path model as the table ships it (`Cameras\FlyByDwarf.mdx`). Use
-    /// [`camera_model_path`] for the archive path.
+    /// The path model as the table ships it (`.mdx`); [`camera_model_path`] gives the archive path.
     pub model: String,
-    /// `SoundEntries.dbc` id for the shot's audio, `0` for none (`PalantirOfAzora` and `Scry_cam`
-    /// are the two silent rows).
+    /// `SoundEntries.dbc` id for the shot's audio, 0 for none.
     pub sound_id: u32,
     /// Where the path's local frame is planted, raw WoW world coordinates.
     pub origin: [f32; 3],
-    /// The local frame's yaw about `+Z`, **radians**.
+    /// The local frame's yaw about `+Z`, in radians.
     pub origin_facing: f32,
 }
 
-/// Both cinematic tables, keyed by row id.
-///
-/// `Default` is the **empty** catalog — what "the DBCs failed to load" already means to a caller
-/// (every lookup misses, and a trigger it cannot resolve is a trigger it skips).
+/// Both cinematic tables, keyed by row id. `Default` is the empty catalog: every lookup misses,
+/// so a trigger it cannot resolve is skipped.
 #[derive(Default)]
 pub struct CinematicCatalog {
     sequences: HashMap<u32, CinematicSequence>,
@@ -156,8 +90,7 @@ impl CinematicCatalog {
     }
 }
 
-/// The archive path for a camera row's model: the table's `.mdx` reference mapped to the `.m2` the
-/// MPQ actually holds (the same normalisation every other model reference in the client takes).
+/// The archive path for a camera row's model: the table ships `.mdx`, the MPQ holds `.m2`.
 pub fn camera_model_path(model: &str) -> String {
     let stem = model.rsplit_once('.').map_or(model, |(stem, ext)| {
         match ext.to_ascii_lowercase().as_str() {
@@ -203,8 +136,7 @@ pub fn load_cinematics(chain: &mut Chain) -> Result<CinematicCatalog> {
     let mut sequences = HashMap::with_capacity(rs.records().len());
     for r in rs.records() {
         let Some(id) = u32_at(r, 0) else { continue };
-        // Trailing zeros are "no camera", not camera 0 — the shipped rows are one camera then
-        // seven zeros. Stop at the first, so a hypothetical gap can't smuggle a zero in.
+        // A zero slot is "no camera", not camera 0; the list stops at the first one.
         let cameras = (0..SEQUENCE_CAMERAS)
             .map_while(|i| u32_at(r, 2 + i).filter(|&c| c != 0))
             .collect();
@@ -244,13 +176,13 @@ pub fn load_cinematics(chain: &mut Chain) -> Result<CinematicCatalog> {
     Ok(CinematicCatalog { sequences, cameras })
 }
 
-/// One instant of a cinematic: where the view is, what it looks at, and how it is banked — all in
-/// **raw WoW world coordinates** (X north, Y west, Z up), the convention this crate keeps.
+/// One instant of a cinematic: eye, look-at target and roll, in raw WoW world coordinates.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct CinematicView {
     pub eye: [f32; 3],
     pub target: [f32; 3],
-    /// Roll about the view axis, radians. The authored sign, unconverted.
+    /// Roll about the view axis in radians, the authored sign unconverted: an angle to apply, never
+    /// tested for 0, as shots hold values such as 2π (`FlyByDwarf`) and 3π (`Scry_cam`).
     pub roll: f32,
 }
 
@@ -258,35 +190,19 @@ pub struct CinematicView {
 pub struct CinematicPath {
     /// The camera row this was built from.
     pub camera_id: u32,
-    /// The row's `SoundEntries.dbc` narration id, `0` for a silent shot — carried here so a
-    /// consumer that has the shot has everything the shot plays.
+    /// The row's `SoundEntries.dbc` narration id, 0 for a silent shot.
     pub sound_id: u32,
-    /// The authored field of view, radians — `0.7854` (45°) on fifteen of the sixteen shipped
-    /// shots and `1.5708` (90°) on the Undead intro.
-    ///
-    /// **The reference reads this from nothing on the cinematic path** (wow-re
-    /// `ui/scratch/cinematic-camera-law.md`, VERIFIED by a 24-site census: the M2 camera's fov and
-    /// the two clips are written at model load and read only by `0x7ac640`, which is reachable
-    /// solely from the portrait and `<Model>` frame paths). A fly-by is rendered through the
-    /// **world camera's own** optics, re-stamped every frame. So this is a real field of the
-    /// record, and it is not what a fly-by is framed with — see decision 1711 for what benilla did
-    /// with it before that was known.
+    /// The authored field of view in radians: 45° on every shipped shot but the Undead intro's 90°.
+    /// Not the fly-by's framing: the reference reads the record's optics only in `0x7ac640`, on the
+    /// portrait and `<Model>` paths, and flies through the world camera's own, set every frame.
     pub fov: f32,
-    /// The authored near clip, radians-free yards — read by nothing on this path, like [`Self::fov`].
-    ///
-    /// It is carried because it is *there*, and because its value is the tell: every shipped shot
-    /// authors `8/36` or `1000/36` — `0.2222` and `27.7778` yards. As world clips those are
-    /// nonsense (a 27.8-yard far plane renders the dwarf intro's mountains as empty sky), which is
-    /// exactly what you would expect of two floats nothing consumes.
+    /// The authored near clip (8/36 on every shipped shot), unread on this path like [`Self::fov`].
     pub near_clip: f32,
-    /// The authored far clip — see [`Self::near_clip`].
+    /// The authored far clip (1000/36 on every shipped shot), unread on this path.
     pub far_clip: f32,
-    /// How long the shot runs, milliseconds — the *width* of the sequence band the tracks are
-    /// keyed inside (`end − start`), not its end. See [`Self::sample`] for why the two differ.
+    /// How long the shot runs in ms: the width of its sequence band (`end − start`), not its end.
     pub duration_ms: u32,
-    /// Where that band begins on the model's global timeline; added to the sample time so a shot
-    /// whose first key is not at zero (`FlybyNightElf`, `Scry_cam`) starts on its first key
-    /// instead of holding it.
+    /// The band's start on the model's global timeline, added to every sample time.
     band_start: u32,
     origin: [f32; 3],
     facing_sin_cos: (f32, f32),
@@ -294,8 +210,7 @@ pub struct CinematicPath {
 }
 
 impl CinematicPath {
-    /// Build a shot from its camera row: read the `.m2` off the chain, take its camera record, and
-    /// plant it at the row's origin/facing.
+    /// Build a shot from its camera row: the `.m2`'s camera record, planted at the row's origin.
     pub fn load(chain: &mut Chain, row: &CinematicCameraRow) -> Result<Self> {
         let path = camera_model_path(&row.model);
         let bytes = chain
@@ -306,22 +221,14 @@ impl CinematicPath {
 
     /// The same, from bytes already in hand (the test/tooling seam).
     pub fn from_m2_bytes(bytes: &[u8], row: &CinematicCameraRow) -> Result<Self> {
-        // The camera array alone, not a whole model parse: a `Cameras\*.m2` carries no geometry to
-        // parse and the shot is entirely in this one record.
+        // The camera array alone: a `Cameras\*.m2` has no geometry, and the shot is this record.
         let camera = benilla_m2::parse_cameras(bytes)
             .into_iter()
             .next()
             .ok_or_else(|| anyhow::anyhow!("model carries no camera record"))?;
-        // The shot's length is the model's own sequence band (stride 0x44 records at header
-        // 0x1c/0x20, band `[start, end]` at +0x04/+0x08 — the same walk the emitter-timing bake
-        // uses). The reference arms this as an ordinary M2 animation on sequence 0, so the shot
-        // runs the band: it *plays* for `end − start` and its tracks are keyed at absolute
-        // global-timeline stamps inside `[start, end]`. Eight of the ten shipped cameras band at
-        // `[0, end]` and the distinction is invisible on them — but `FlybyNightElf` bands at
-        // `[333, 102333]` and `Scry_cam` at `[33, 3333]`, and reading `end` as the duration
-        // played those two 333 ms / 33 ms too long with the opening frames frozen on the first
-        // key (which is what sampling `t = 0` against a track that starts at 333 returns).
-        // The fallback, for a file that authors no sequence at all, is the last key.
+        // The reference plays the shot as an ordinary M2 animation on sequence 0: it runs for
+        // `end − start`, its keys stamped on the global timeline inside `[start, end]`. A file
+        // with no sequence falls back to its last key.
         let (band_start, band_end) = sequence_band(bytes)
             .or_else(|| {
                 [
@@ -349,28 +256,8 @@ impl CinematicPath {
         })
     }
 
-    /// Sample the shot at `ms` from its start, **end-clamped** at both ends.
-    ///
-    /// `ms` is measured from the *shot's* start; the tracks are keyed on the model's global
-    /// timeline, so it is offset by [`Self::band_start`] before it reaches them. On eight of the
-    /// ten shipped cameras that offset is zero and the two are the same number; on
-    /// `FlybyNightElf` (band `[333, 102333]`) and `Scry_cam` (`[33, 3333]`) it is the difference
-    /// between opening on the authored first key and holding it for a third of a second first.
-    ///
-    /// Two steps, in this order. The reference's publish pass composes each track against its base
-    /// (`eye = position_base + positions(t)`, `target = target_position_base + target(t)`); then
-    /// the local frame is planted in the world by the camera row's origin and facing:
-    ///
-    /// ```text
-    /// world.x = origin.x + local.x·cos(facing) − local.y·sin(facing)
-    /// world.y = origin.y + local.x·sin(facing) + local.y·cos(facing)
-    /// world.z = origin.z + local.z
-    /// ```
-    ///
-    /// i.e. a plain yaw about `+Z` by the row's facing, then a translation — no scale, no
-    /// handedness flip. Checked against vmangos's independently sampled `cinematic_waypoints` for
-    /// the dwarf (41) and human (81) intros; the sign-flipped and axis-swapped alternatives are
-    /// off by an order of magnitude (module doc).
+    /// Sample the shot `ms` after its start, clamped at both ends: each track composed against its
+    /// base, then planted in the world by the row's origin and facing, with no scale or flip.
     pub fn sample(&self, ms: u32) -> CinematicView {
         let ms = self.band_start.saturating_add(ms);
         let eye = self.to_world(sample_against(
@@ -400,22 +287,15 @@ impl CinematicPath {
     }
 }
 
-/// A camera track sampled and composed against its base — the reference's publish form.
+/// A camera track sampled and composed against its base, the reference's publish form.
 fn sample_against(track: &M2Track<M2SplineKey<[f32; 3]>>, base: [f32; 3], ms: u32) -> [f32; 3] {
     let d = track.sample_ms(ms).unwrap_or([0.0; 3]);
     std::array::from_fn(|i| base[i] + d[i])
 }
 
-/// The model's **first** sequence band, `(start, end)` in global-timeline milliseconds (header
-/// `0x1c` count / `0x20` offset, entry stride `0x44`, band at `+0x04`/`+0x08`). `None` for a model
-/// with no sequences.
-///
-/// **`start` is not always zero, and the shipped corpus is its own proof of these offsets.** Eight
-/// of the ten cameras band at `[0, end]`, but `FlybyNightElf` bands at `[333, 102333]` and
-/// `Scry_cam` at `[33, 3333]` — and in both files the band's `start` is *exactly* the first
-/// timestamp on the position and target tracks, while `end` is exactly the last. Two fields that
-/// land on the first and last key of every file in the corpus are the first and last key, which
-/// is why this is read rather than assumed to be a duration.
+/// The model's first sequence band, `(start, end)` in global-timeline ms: count at header `0x1c`,
+/// offset at `0x20`, entries `0x44` apart, band at `+0x04`/`+0x08`. `start` is not always 0
+/// (`FlybyNightElf` bands at `[333, 102333]`).
 fn sequence_band(b: &[u8]) -> Option<(u32, u32)> {
     let le_u32 = |o: usize| -> Option<u32> {
         b.get(o..o + 4)
@@ -432,9 +312,8 @@ fn sequence_band(b: &[u8]) -> Option<(u32, u32)> {
 mod tests {
     use super::*;
 
-    /// The eight race intros, by `ChrRaces.dbc` `CinematicSequence` (field 16) — the ids a first
-    /// login actually sends (VERIFIED in the shipped `ChrRaces.dbc`, and matching vmangos's
-    /// `SendCinematicStart(rEntry->CinematicSequence)`).
+    /// The eight race intros, `ChrRaces.dbc` `CinematicSequence` (field 16), which vmangos sends
+    /// on a first login (`CharacterHandler.cpp:581`).
     const RACE_INTROS: [u32; 8] = [2, 21, 41, 61, 81, 101, 121, 141];
 
     #[test]
@@ -445,8 +324,7 @@ mod tests {
         );
         assert_eq!(camera_model_path("Cameras\\X.MDX"), "Cameras\\X.m2");
         assert_eq!(camera_model_path("Cameras\\X.m2"), "Cameras\\X.m2");
-        // A path with no extension at all still names an .m2, and a dot inside a directory name
-        // is not an extension.
+        // A path with no extension still names an `.m2`.
         assert_eq!(camera_model_path("Cameras\\X"), "Cameras\\X.m2");
     }
 
@@ -458,14 +336,13 @@ mod tests {
         assert_eq!(cat.sequence_count(), 10);
         assert_eq!(cat.camera_count(), 10);
 
-        // Every shipped sequence names exactly one camera and carries no sound of its own.
         for id in RACE_INTROS {
             let seq = cat.sequence(id).unwrap_or_else(|| panic!("sequence {id}"));
             assert_eq!(seq.cameras.len(), 1, "sequence {id} camera count");
             assert_eq!(seq.sound_id, 0, "sequence {id} sound");
         }
 
-        // The dwarf intro, end to end — the row decision 0196 captured live.
+        // The dwarf intro's shipped row, end to end.
         let dwarf = cat.shots(41);
         assert_eq!(dwarf.len(), 1);
         let cam = dwarf[0];
@@ -494,18 +371,10 @@ mod tests {
                 path.camera.positions.keys.len() >= 10,
                 "sequence {id} is richly keyed"
             );
-            // Cubic Bézier on both vector tracks — the case the four-way interp dispatch exists
-            // for, and the one a step/linear-only sampler would silently mangle.
+            // Interp 2 is cubic Bézier, on both vector tracks.
             assert_eq!(path.camera.positions.interp, 2, "sequence {id} position");
             assert_eq!(path.camera.target.interp, 2, "sequence {id} target");
-            // **The end condition, and the proof of the band offsets.** The authored sequence
-            // band brackets both vector tracks exactly: its `start` is the first key's timestamp
-            // and its `end` is the last one's, on every shipped fly-by. Two header fields that
-            // land on the first and last key of all eight files are the first and last key — and
-            // that is what licenses reading the playback length as `end − start` rather than as
-            // `end`, which is the bug this assertion now pins (`FlybyNightElf` bands at
-            // `[333, 102333]`, so the two readings differ by a third of a second and by whether
-            // the shot opens on its first key or holds it).
+            // The band brackets both tracks exactly: `start` is the first key, `end` the last.
             for (what, track) in [
                 ("position", &path.camera.positions),
                 ("target", &path.camera.target),
@@ -521,12 +390,7 @@ mod tests {
                     "sequence {id} {what} track ends on the band"
                 );
             }
-            // The clips are uniform across the corpus; the FOV is NOT — the Undead intro is 90°
-            // where the rest are 45°. Kept as a **data** assertion, and no longer as a reason to
-            // read it per shot: decision 1711 established that the reference's cinematic path
-            // reads none of these three, so the split is a fact about the files and not about how
-            // any shot is framed. It stays because a parser that silently started returning zeros
-            // for all three would otherwise pass every other test in this file.
+            // Data only: uniform clips, and a 90° fov on the Undead intro against 45° elsewhere.
             assert!((path.near_clip - 8.0 / 36.0).abs() < 1e-6);
             assert!((path.far_clip - 1000.0 / 36.0).abs() < 1e-4);
             let want_fov = if id == 2 {
@@ -542,14 +406,8 @@ mod tests {
         }
     }
 
-    /// The dwarf intro's world path, pinned at three instants.
-    ///
-    /// These numbers are the **transform's** golden: they were derived independently (a
-    /// hand-written evaluator over the raw bytes) and then cross-checked, time-independently,
-    /// against vmangos's `cinematic_waypoints` samples for this cinematic — our arc passes within
-    /// 59.6 yd horizontally of every one of the server's six samples (mean 35.5). The three
-    /// alternative conventions do far worse on the same measure: `Rz(−facing)` 436.8 yd,
-    /// axis-swapped 334.0, no rotation at all 859.9. So a sign flip here fails this test loudly.
+    /// The golden points come from a separate evaluator over the raw bytes; the arc passes within
+    /// 59.6 yd of all six of vmangos's `cinematic_waypoints` samples for this intro.
     #[test]
     fn real_dwarf_intro_flies_the_authored_arc() {
         let data = crate::wow_data_or_skip!();
@@ -577,11 +435,9 @@ mod tests {
         near(mid.target, [-5715.481, -427.434, 450.394], "mid target");
         let end = path.sample(path.duration_ms);
         near(end.eye, [-6246.921, 333.773, 384.187], "end eye");
-        // Past the end the path holds its last key — it does not wrap to the start.
+        // Past the end the path holds its last key; it does not wrap.
         assert_eq!(path.sample(u32::MAX).eye, end.eye);
-        // Roll here is a single key holding **2π**, not 0 — the authored angles sit around whole
-        // turns (`Scry_cam` holds 3π), so roll is applied as an angle and only *happens* to be an
-        // identity on this shot.
+        // One roll key, holding 2π rather than 0.
         assert!(
             (start.roll - std::f32::consts::TAU).abs() < 1e-4,
             "{}",
@@ -590,9 +446,6 @@ mod tests {
         assert_eq!(mid.roll, start.roll, "a single-key roll track is constant");
     }
 
-    /// The shots range far from their own origin — the reason the server re-anchors object
-    /// visibility to the flying camera while a cinematic runs (decision 0196), and the reason
-    /// benilla has to stream the world from the camera rather than the avatar for the duration.
     #[test]
     fn real_flyby_shots_range_far_from_their_origin() {
         let data = crate::wow_data_or_skip!();
@@ -601,8 +454,7 @@ mod tests {
         for id in RACE_INTROS {
             let row = cat.shots(id)[0].clone();
             let path = CinematicPath::load(&mut chain, &row).expect("path");
-            // The furthest the eye gets from the body's neighbourhood over the whole shot. The
-            // troll intro *starts* only 39 yd out, so this is the reach, not the first frame.
+            // The reach over the whole shot, not the first frame: the troll intro starts 39 yd out.
             let reach = (0..=path.duration_ms)
                 .step_by(500)
                 .map(|ms| {
diff --git a/crates/benilla-formats/src/creature_families.rs b/crates/benilla-formats/src/creature_families.rs
index 93dbd533..3f839de4 100644
--- a/crates/benilla-formats/src/creature_families.rs
+++ b/crates/benilla-formats/src/creature_families.rs
@@ -1,68 +1,12 @@
-//! `CreatureFamily.dbc` + `ItemPetFood.dbc` — the pet's **family word** and the **diet** it implies
-//! (decision 1062): `UnitCreatureFamily`'s "Imp"/"Wolf"/"Cat", and `GetPetFoodTypes`'s
-//! "Meat, Fish".
+//! `CreatureFamily.dbc` and `ItemPetFood.dbc`: a pet's family word (`UnitCreatureFamily`,
+//! `0x51a310`) and the diet its food mask names (`GetPetFoodTypes`, `0x4bea10`).
 //!
-//! Both layouts below were **dumped from this install's own shipped files** rather than taken from
-//! memory or a wiki — the WDBC header first, then every column of every row, then a census of what
-//! each column actually holds. What that dump says:
+//! `CreatureFamily.dbc` is 18 fields in 0x48-byte records, 23 rows with ids 1..28 (10, 13, 14, 18
+//! and 22 absent). `ItemPetFood.dbc` is 10 fields, 8 rows. Mask bit `b` names food row `b + 1`,
+//! low bit first, which is the client's record order (vmangos `Objects/Pet.cpp:1503-1504`).
 //!
-//! **`CreatureFamily.dbc` — 18 fields, `record_size` 0x48, 23 rows, string block 933 bytes.**
-//!
-//! | field | byte | holds |
-//! |---|---|---|
-//! | 0 | 0x00 | `ID` — 1..28 with gaps (10, 13, 14, 18, 22 are absent) |
-//! | 1 | 0x04 | `minScale`, a **float** (0.4 … 1.0) |
-//! | 2 | 0x08 | `minScaleLevel` — **1 on all 22 real families**, warlock minions included; 0 only on row 28 |
-//! | 3 | 0x0c | `maxScale`, a **float** (0.6 … 1.1) |
-//! | 4 | 0x10 | `maxScaleLevel` — **60 on all 22**; 0 only on row 28 |
-//! | 5 | 0x14 | `skillLine[0]` — a `SkillLine.dbc` id (188…758), distinct on every row |
-//! | 6 | 0x18 | `skillLine[1]` — 270 on every tameable family, 0 on the rest |
-//! | 7 | 0x1c | **`petFoodMask`** — the bitfield this module's other half indexes |
-//! | 8..15 | 0x20 | the localized `Name` block; **enUS is field 8**, the other seven are all zero |
-//! | 16 | 0x40 | the name block's locale-present flags (0x7EFFFE or 0x3F007E) — **not** zero |
-//! | 17 | 0x44 | `iconFile` — `Interface\Icons\Ability_Hunter_Pet_*` (a string, not a dword) |
-//!
-//! (The 2026-08-06 dump's note that the level columns are "0 for the warlock ones" was wrong, and
-//! is corrected above off the shipped file: Imp/Voidwalker/Succubus/Felhunter/Doomguard all read
-//! 1 → 60 like every hunter family, and simply carry `minScale == maxScale` so their ramp is flat.
-//! Only "Remote Control" (row 28) is 0/0/0/0. It matters because those four columns are the
-//! character-select pet's SIZE — decision 1538.)
-//!
-//! That confirms the `0x48` record and the 23 rows [`crate::pet_stats`]'s header already recorded,
-//! and **corrects its "every dword from `0x28` up is zero"**: fields 10..15 (`0x28`–`0x3c`) are
-//! indeed all zero — which is what that argument actually rested on, since the reads it was ruling
-//! out were at `+0x28`/`+0x30`/`+0x3c`/`+0x48` — but `0x40` and `0x44` are not. The conclusion
-//! stands (a `rec+0x48` read still runs off the end of a 0x48-byte record); the sentence was one
-//! column too wide.
-//!
-//! **`ItemPetFood.dbc` — 10 fields, `record_size` 0x28, 8 rows, string block 55 bytes**: `ID`@0,
-//! the localized `Name` block@1..8 (**enUS is field 1**, the rest zero), name flags@9. The eight
-//! rows in id order are exactly `Meat / Fish / Cheese / Bread / Fungus / Fruit / Raw Meat /
-//! Raw Fish`.
-//!
-//! **The mask's bit → row mapping is `bit b` → `ItemPetFood` row `b + 1`** (see
-//! [`PetFoodNames::for_mask`]) — DATA-derived twice over. The highest bit any shipped row sets is
-//! **7** (Turtle, mask 178) and the table has exactly 8 rows, so a 0-based mapping would leave row
-//! 8 permanently unreachable and Wolf (mask 1) with an empty diet. And vmangos, reading the same
-//! file, tests exactly `1 << (item->FoodType - 1)` against this column (`Objects/Pet.cpp:1503-1504`,
-//! `Database/DBCStructure.h:251` — its `CreatureFamilyfmt` `"nfifiiiissssssssxx"` is this table's
-//! layout above, field for field). Every resulting diet matches vanilla's documented ones: Wolf =
-//! Meat, Cat = Meat+Fish, Bear/Boar = all six, Gorilla = Fungus+Fruit, Wind Serpent = Fish+Cheese+
-//! Bread.
-//!
-//! **All of the above is now also byte-VERIFIED** (wow-re, 2026-08-06 — `GetPetFoodTypes 0x4bea10`
-//! and `UnitCreatureFamily 0x51a310`), and the two dumps agree line for line with nothing left
-//! over: the mask is column 7, the bit map is `1 << (recordID - 1)`, the family name is column
-//! `8 + locale`, the food name is column `1 + locale`, the id space really does have null rows at
-//! 10/13/14/18/22, and the binary's own positive controls (Wolf → Meat; Bear and Boar → all six;
-//! Turtle → Fish/Fungus/Fruit/Raw Fish) are the rows asserted below. The one claim that had been
-//! flagged INFERRED here — that the walk is **low bit first** — is settled the same way: the client
-//! pushes in **record order**, which is what ascending bits produce.
-//!
-//! What this module deliberately does **not** model is `GetPetFoodTypes`' own `0x6116e0` gate
-//! (owner-is-me + the local player is a Hunter). That is a live-state question, not a table one, so
-//! it lives at the feed (`benilla_app::ui_pet_stats`) — and it is why a charmed boar under a priest
-//! answers an empty diet despite a mask of 63.
+//! `GetPetFoodTypes`' gate (the pet is ours and we are a Hunter, `0x6116e0`) is live state, applied
+//! at the feed (`benilla_app::ui_pet_stats`): a charmed boar under a priest has no diet.
 
 use std::collections::HashMap;
 
@@ -75,57 +19,35 @@ use crate::dbc::{f32_at, parse, str_at, u32_at};
 const CREATURE_FAMILY: &str = "DBFilesClient\\CreatureFamily.dbc";
 const ITEM_PET_FOOD: &str = "DBFilesClient\\ItemPetFood.dbc";
 
-/// `CreatureFamily.dbc`'s column count (the DBC header's `field_count`; `benilla-dbc` enforces it,
-/// so a wrong number fails loudly instead of misaligning every column).
+/// `CreatureFamily.dbc`'s field count, which `benilla-dbc` checks against the header.
 const FAMILY_FIELDS: usize = 18;
-/// `ItemPetFood.dbc`'s column count.
 const FOOD_FIELDS: usize = 10;
 
-/// `CreatureFamily.dbc`'s level → size ramp — bytes `0x04`/`0x08`/`0x0c`/`0x10`, i.e. fields 1–4.
-/// (Written as indices, not the `byte / 4` the columns below use: `0x04 / 4` is `4 / 4`, which
-/// clippy's `eq_op` reads as a mistake — and it is not worth an allow to keep one idiom.)
 const FAMILY_MIN_SCALE_FIELD: usize = 1;
 const FAMILY_MIN_SCALE_LEVEL_FIELD: usize = 2;
 const FAMILY_MAX_SCALE_FIELD: usize = 3;
 const FAMILY_MAX_SCALE_LEVEL_FIELD: usize = 4;
-/// `CreatureFamily.dbc`'s pet-food mask — byte `0x1c` = field 7.
 const FAMILY_FOOD_MASK_FIELD: usize = 0x1c / 4;
-/// `CreatureFamily.dbc`'s enUS `Name` — byte `0x20` = field 8.
+/// The enUS name, the localized block's first slot.
 const FAMILY_NAME_FIELD: usize = 0x20 / 4;
-/// `CreatureFamily.dbc`'s `iconFile` — byte `0x44` = field 17. The last column, past the name
-/// block's locale flags; not read by anything yet, typed as a string so the schema is honest.
+/// `iconFile`, after the name block's locale flags.
 const FAMILY_ICON_FIELD: usize = 0x44 / 4;
-/// `ItemPetFood.dbc`'s enUS `Name` — field 1, the same shape every other localized table here uses.
+/// `ItemPetFood.dbc`'s enUS name.
 const FOOD_NAME_FIELD: usize = 1;
 
-/// The number of `ItemPetFood` rows a mask can name. Not a guess at the file's size: it is the
-/// width the *mask* can address, and the shipped table happens to fill it exactly (bit 7 → row 8,
-/// Turtle's "Raw Fish"). Bits above this are ignored rather than fabricating rows.
+/// The reference tests `1 << (row - 1)` for each of the 8 food rows, so higher bits name nothing.
 const MAX_FOOD_BITS: u32 = 8;
 
-/// One `CreatureFamily.dbc` row, reduced to its live columns: the family word, the diet mask, and
-/// the **level → size ramp**.
+/// One `CreatureFamily.dbc` row: the family word, icon, diet mask and level-to-size ramp.
 #[derive(Debug, Clone, PartialEq)]
 pub struct CreatureFamily {
-    /// The localized family word — "Wolf", "Imp", "Wind Serpent". What `UnitCreatureFamily` pushes.
+    /// The localized family word ("Wolf", "Imp"), what `UnitCreatureFamily` returns.
     pub name: String,
-    /// The family's icon path — `Interface\\Icons\\Ability_Hunter_Pet_<Family>` for every one of
-    /// the 22 real families (verified by dumping the shipped table this session; the column is
-    /// field 17, `0x44`). This is a pet's icon everywhere one is shown without an item behind it:
-    /// the stable window's slot buttons and `GetPetIcon` (decision 1676). The schema already
-    /// declared the column so the parser aligned past it; only the read into this struct is new.
-    ///
-    /// Empty for a row that ships no icon — the same "render the empty-slot art" case as a pet
-    /// whose creature query has not landed, which is why consumers treat it as absent rather than
-    /// passing an empty path to a texture setter (decision 1046: a path resolving to nothing draws
-    /// WHITE).
+    /// `Interface\\Icons\\Ability_Hunter_Pet_<Family>`; empty when the row ships none.
     pub icon: String,
-    /// The pet-food bitfield (field 7). **`0` for every warlock minion** — Imp, Voidwalker,
-    /// Succubus, Felhunter, Doomguard all ship a zero mask, and so does row 28 ("Remote Control") —
-    /// which is why a diet list can be legitimately empty without anything having gone wrong.
+    /// The diet bitfield; 0 on the five warlock minions and row 28, so an empty diet is real.
     pub pet_food_mask: u32,
-    /// The size ramp's ends (fields 1–4): the model scale at `min_scale_level` and at
-    /// `max_scale_level`. See [`CreatureFamily::scale_at`].
+    /// The size ramp: the model scale at `min_scale_level` and at `max_scale_level`.
     pub min_scale: f32,
     pub min_scale_level: u32,
     pub max_scale: f32,
@@ -133,28 +55,16 @@ pub struct CreatureFamily {
 }
 
 impl CreatureFamily {
-    /// **A pet's render scale at a level** — the character-select pet's whole size law (decision
-    /// 1538, wow-re `glue/scratch/glue-select-pet.md`):
+    /// A pet's render scale at `level`, the reference's size law for the character-select pet:
     ///
     /// ```text
     /// S = minScale + (maxScale − minScale) · clamp(level − minScaleLevel, 0, range) / range
     /// range = maxScaleLevel − minScaleLevel
     /// ```
     ///
-    /// This is what the reference actually sizes the select pet with. It *also* computes the
-    /// familiar `CreatureModelData.modelScale × CreatureDisplayInfo.scale` product one instruction
-    /// earlier and then **overwrites it** with this (`0x472e87 fstp`) — the product survives only
-    /// when the family lookup misses, which for a real pet it never does.
-    ///
-    /// Every one of the 22 real families ramps 1 → 60, so a freshly tamed wolf really is visibly
-    /// smaller than a level-60 one (Wolf 0.7 → 1.0, Crab 0.7 → 1.4, Spider 0.4 → 0.6); the warlock
-    /// minions ship `min == max`, so theirs is flat at every level (Imp 0.5, Voidwalker 0.8,
-    /// Succubus and Doomguard 1.0, Felhunter 0.7).
-    ///
-    /// **`None` for a degenerate ramp** — `range <= 0`, which only row 28 ("Remote Control", all
-    /// four columns 0) ships. The reference has no guard there and divides by zero into a NaN
-    /// scale; that is a defect of the original, not a mechanism, so we answer "no ramp" and let the
-    /// caller take the product fallback the reference itself takes on a lookup miss.
+    /// The reference overwrites the `modelScale × scale` product with it (`0x472e87`), so the
+    /// product survives only a family lookup miss. Deviation: a zero range (row 28 only) is `None`,
+    /// the lookup-miss fallback, because the reference divides by zero there into a NaN scale.
     pub fn scale_at(&self, level: u32) -> Option<f32> {
         let range = self.max_scale_level.checked_sub(self.min_scale_level)?;
         if range == 0 {
@@ -171,18 +81,13 @@ impl CreatureFamily {
 pub struct CreatureFamilies(HashMap<u32, CreatureFamily>);
 
 impl CreatureFamilies {
-    /// The row for a family id, or `None`.
-    ///
-    /// **Family `0` is `None` and that is the common case, not an error**: the file's ids start at
-    /// 1, and every creature that is neither a tameable beast nor a warlock minion carries `0` in
-    /// the wire's `pet_family` slot. `UnitCreatureFamily`'s nil is this `None`.
+    /// The row for a family id; the wire's 0 (no family) is `None`, `UnitCreatureFamily`'s nil.
     pub fn get(&self, id: u32) -> Option<&CreatureFamily> {
         self.0.get(&id)
     }
 
-    /// The localized family word for an id — [`Self::get`]'s name half.
-    /// The family's icon path, or `None` for an unknown family or a row that ships none —
-    /// the stable window's slot art and `GetPetIcon`'s answer (decision 1676).
+    /// The icon for the stable's slots and `GetPetIcon`; `None` for an unknown family or an empty
+    /// path, which would draw white.
     pub fn icon(&self, id: u32) -> Option<&str> {
         self.0
             .get(&id)
@@ -194,9 +99,8 @@ impl CreatureFamilies {
         self.get(id).map(|f| f.name.as_str())
     }
 
-    /// A pet's render scale from its family and level — [`CreatureFamily::scale_at`] over
-    /// [`Self::get`]. `None` for an unknown family (including the wire's `0`) or a degenerate ramp;
-    /// the caller then takes the display's own scale product, as the reference does.
+    /// [`CreatureFamily::scale_at`] by family id; on `None` the caller takes the display's scale
+    /// product, as the reference does.
     pub fn pet_scale(&self, family: u32, level: u32) -> Option<f32> {
         self.get(family)?.scale_at(level)
     }
@@ -219,18 +123,8 @@ impl PetFoodNames {
         self.0.get(&id).map(String::as_str)
     }
 
-    /// Expand a [`CreatureFamily::pet_food_mask`] into the localized names it selects — **bit `b`
-    /// selects row `b + 1`**, ascending, which is the client's own **record order**
-    /// (`0x4bea10`'s `1 << (recordID - 1)`; the module header carries the derivation).
-    ///
-    /// An empty result is a real answer, not a failure: a warlock minion's family ships mask `0`.
-    /// `GetPetFoodTypes` then returns nothing at all, which is exactly what the reference's own
-    /// `BuildListString()` turns into nil — and the diet icon that would show it is hidden for a
-    /// minion anyway (`HasPetUI`'s second return, decision 1005).
-    ///
-    /// **This is the table half only.** The binding's live gate — owner-is-me and the local player
-    /// is a Hunter (`0x6116e0`) — is the feed's to apply; a charmed boar has a mask of 63 and still
-    /// answers nothing under a non-hunter.
+    /// The food names a [`CreatureFamily::pet_food_mask`] selects, bit `b` naming row `b + 1` in
+    /// the reference's record order (`0x4bea10`). The `0x6116e0` gate is the caller's.
     pub fn for_mask(&self, mask: u32) -> Vec<&str> {
         (0..MAX_FOOD_BITS)
             .filter(|b| mask & (1 << b) != 0)
@@ -250,11 +144,10 @@ fn family_schema() -> Schema {
     let mut s = Schema::new("CreatureFamily");
     for i in 0..FAMILY_FIELDS {
         let ty = match i {
-            // minScale / maxScale — the only two floats in the record.
+            // minScale and maxScale, the record's only floats.
             1 | 3 => FieldType::Float32,
             FAMILY_NAME_FIELD | FAMILY_ICON_FIELD => FieldType::String,
-            // The rest of the locale block reads as dwords: every one is 0 in the shipped file, and
-            // typing them as strings would make the parser chase seven zero offsets per row.
+            // The other locale slots, all 0 in the shipped file, read as dwords.
             _ => FieldType::UInt32,
         };
         s.add_field(SchemaField::new(format!("F{i}"), ty));
@@ -284,8 +177,7 @@ pub fn load_creature_families(chain: &mut Chain) -> Result<CreatureFamilies> {
     let mut by_id = HashMap::with_capacity(rs.records().len());
     for r in rs.records() {
         let Some(id) = u32_at(r, 0) else { continue };
-        // A row with no enUS name is dropped rather than stored empty: the binding's contract is
-        // "a word or nil", and an empty string would render as a trailing space on the level line.
+        // A nameless row is dropped: `UnitCreatureFamily` answers a word or nil, never "".
         let Some(name) = str_at(&rs, r, FAMILY_NAME_FIELD).filter(|n| !n.is_empty()) else {
             continue;
         };
@@ -330,17 +222,7 @@ mod tests {
         Some(crate::open_chain(&data).expect("open chain"))
     }
 
-    /// **The level → size ramp, off the shipped file** (decision 1538) — the character-select pet's
-    /// whole size law, and four columns that fail silently if they slide: misread one and every pet
-    /// is simply the wrong size, which no other assertion here would catch.
-    ///
-    /// The load-bearing shape is that **all 22 real families ramp 1 → 60**, warlock minions
-    /// included — they are flat only because `min == max`, not because their level columns are
-    /// zero. Row 28 ("Remote Control") is the sole 0/0/0/0 row, and the sole `None`.
-    /// The icon column, off the shipped file (decision 1676). It is the stable window's slot art
-    /// and `GetPetIcon`'s answer, and it sits at field 17 behind a locale block the schema types as
-    /// dwords — so a misread there returns an empty string, and an empty texture path draws WHITE
-    /// (decision 1046). Asserting real paths is what catches that.
+    /// Field 17 sits behind locale slots typed as dwords, so a column slip reads an empty path.
     #[test]
     fn every_shipped_family_carries_a_pet_icon() {
         let Some(mut chain) = chain() else { return };
@@ -350,12 +232,11 @@ mod tests {
             fams.icon(1),
             Some("Interface\\Icons\\Ability_Hunter_Pet_Wolf")
         );
-        // A warlock minion has one too — the stable never shows them, but `GetPetIcon` does.
+        // A warlock minion has one too, for `GetPetIcon`.
         assert!(fams
             .icon(15)
             .is_some_and(|i| i.starts_with("Interface\\Icons\\")));
 
-        // No real family is missing one, and none is a bare empty string masquerading as a path.
         for id in 1..=27 {
             let Some(f) = fams.get(id) else { continue };
             assert!(
@@ -364,7 +245,6 @@ mod tests {
                 f.name
             );
         }
-        // An unknown family is absent, not empty.
         assert_eq!(fams.icon(9999), None);
     }
 
@@ -373,7 +253,6 @@ mod tests {
         let Some(mut chain) = chain() else { return };
         let fams = load_creature_families(&mut chain).expect("families");
 
-        // Every real family ramps across the same 1 → 60 band.
         for (id, f) in (1..=27).filter_map(|id| fams.get(id).map(|f| (id, f))) {
             assert_eq!(
                 (f.min_scale_level, f.max_scale_level),
@@ -383,7 +262,7 @@ mod tests {
             );
         }
 
-        // A hunter family really does grow: Wolf 0.7 at level 1 → 1.0 at 60, linear between.
+        // Wolf: 0.7 at level 1 to 1.0 at 60, linear between.
         let wolf = fams.get(1).expect("Wolf");
         assert_eq!(wolf.name, "Wolf");
         assert!((wolf.scale_at(1).unwrap() - 0.7).abs() < 1e-6);
@@ -393,11 +272,11 @@ mod tests {
             (mid - (0.7 + 0.3 * 29.0 / 59.0)).abs() < 1e-6,
             "midpoint {mid} is not on the line"
         );
-        // …and the ramp CLAMPS at both ends rather than extrapolating.
+        // The ramp clamps at both ends.
         assert_eq!(wolf.scale_at(0), wolf.scale_at(1));
         assert_eq!(wolf.scale_at(255), wolf.scale_at(60));
 
-        // The warlock minions are flat — same band, `min == max`.
+        // The warlock minions are flat: `min == max`.
         for (id, want) in [(23, 0.5_f32), (16, 0.8), (15, 0.7), (17, 1.0), (19, 1.0)] {
             let f = fams.get(id).expect("warlock family");
             for level in [1, 30, 60] {
@@ -410,51 +289,40 @@ mod tests {
             }
         }
 
-        // The one degenerate row: no ramp, and NOT a NaN.
+        // Row 28's zero range: `None`, not NaN.
         let remote = fams.get(28).expect("Remote Control");
         assert_eq!(remote.scale_at(60), None);
 
-        // Unknown families (the wire's `0` for every non-pet) answer None, not a fabricated size.
+        // The wire's 0 and an id gap are unknown families.
         assert_eq!(fams.pet_scale(0, 60), None);
-        assert_eq!(fams.pet_scale(10, 60), None); // a real id-space gap
+        assert_eq!(fams.pet_scale(10, 60), None);
         assert!((fams.pet_scale(1, 60).unwrap() - 1.0).abs() < 1e-6);
     }
 
-    /// The real 5875 `CreatureFamily.dbc`, byte-anchored: 23 rows, the ids with their gaps, and
-    /// the two columns we read.
-    ///
-    /// **The name column is the trap.** Field 8 sits immediately after `petFoodMask` (7) and is
-    /// followed by seven zero locale slots — read one column early and every name is a *number*;
-    /// read one late and every name is empty. Both fail silently at runtime (a blank level line),
-    /// so the names are asserted verbatim, not merely for presence.
+    /// Names are asserted verbatim: a column early reads the food mask, a column late a zero slot.
     #[test]
     fn the_real_creature_families_name_every_pet() {
         let Some(mut chain) = chain() else { return };
         let f = load_creature_families(&mut chain).expect("load CreatureFamily.dbc");
         assert_eq!(f.len(), 23, "5875 ships 23 creature families");
 
-        // The hunter families, at both ends of the id range.
         assert_eq!(f.name(1), Some("Wolf"));
         assert_eq!(f.name(2), Some("Cat"));
         assert_eq!(f.name(7), Some("Carrion Bird"));
         assert_eq!(f.name(27), Some("Wind Serpent"));
-        // …the warlock minions, which is what the pet page's level line reads most often.
         assert_eq!(f.name(15), Some("Felhunter"));
         assert_eq!(f.name(16), Some("Voidwalker"));
         assert_eq!(f.name(17), Some("Succubus"));
         assert_eq!(f.name(19), Some("Doomguard"));
         assert_eq!(f.name(23), Some("Imp"));
 
-        // The id column really has gaps — 10/13/14/18/22 are absent from the shipped file, so a
-        // dense 1..=23 assumption would silently shift half the table.
+        // The id gaps: a dense 1..=23 read would shift half the table.
         for missing in [10, 13, 14, 18, 22] {
             assert_eq!(f.name(missing), None, "id {missing} is not in the file");
         }
-        // Family 0 is the wire's "no family", and it must be nil rather than the first row.
         assert_eq!(f.name(0), None);
     }
 
-    /// The eight food names, verbatim and in id order — the row set the mask indexes.
     #[test]
     fn the_real_pet_food_names_are_the_eight_diets() {
         let Some(mut chain) = chain() else { return };
@@ -476,13 +344,8 @@ mod tests {
         assert_eq!(n.name(9), None);
     }
 
-    /// **The join, on the real data** — the half neither file can check alone, and the one that
-    /// would fail silently as "a bear eats fish and cheese".
-    ///
-    /// Wolf, Bear, Boar and Turtle are **the binary's own positive controls** (wow-re's
-    /// `0x4bea10` carve, 2026-08-06); the rest are vanilla's documented diets, which is the
-    /// independent corroboration that `bit b → row b+1` is right (vmangos's
-    /// `1 << (FoodType - 1)` is the third).
+    /// Wolf, Bear, Boar and Turtle are the reference's own cases (`0x4bea10`); the rest are
+    /// vanilla's documented diets.
     #[test]
     fn the_shipped_masks_expand_to_vanillas_own_diets() {
         let Some(mut chain) = chain() else { return };
@@ -498,20 +361,15 @@ mod tests {
         assert_eq!(diet(9), ["Fungus", "Fruit"], "Gorilla");
         assert_eq!(diet(12), ["Cheese", "Fungus", "Fruit"], "Tallstrider");
         assert_eq!(diet(27), ["Fish", "Cheese", "Bread"], "Wind Serpent");
-        // Turtle (mask 178) is the control that PINS the bit width: it is the only family to set
-        // bit 7, and bit 7 → row 8 is what makes "Raw Fish" reachable at all.
+        // Turtle (mask 178) is the only family to set bit 7, row 8's "Raw Fish".
         assert_eq!(
             diet(21),
             ["Fish", "Fungus", "Fruit", "Raw Fish"],
             "Turtle — control"
         );
 
-        // **Exactly which families have an EMPTY diet**, because the pet page's diet tooltip
-        // depends on it: `BuildListString()` returns nil for an empty list and `format`'s "%s"
-        // errors on nil, so the icon is safe only while no HUNTER-tameable family has a zero mask.
-        // The shipped file's zero-mask set is the five warlock minions plus row 28 ("Remote
-        // Control") — no tameable beast among them. Asserted as an exact set, not a spot check: a
-        // future row with a zero mask is exactly the thing that would break that tooltip.
+        // The exact empty-diet set: the diet tooltip formats `BuildListString()`'s nil for an empty
+        // list and errors, so no tameable beast may join the five minions and row 28.
         let empty: Vec<u32> = {
             let mut v: Vec<u32> = fam
                 .0
@@ -529,8 +387,6 @@ mod tests {
         );
     }
 
-    /// The mask expansion's own edges, away from the shipped data: an unknown bit names no row
-    /// rather than panicking or inventing one, and bits past the table are ignored.
     #[test]
     fn mask_bits_past_the_table_are_ignored() {
         let mut names = HashMap::new();
@@ -540,7 +396,7 @@ mod tests {
 
         assert_eq!(n.for_mask(0), Vec::<&str>::new());
         assert_eq!(n.for_mask(0b101), ["Meat", "Cheese"]);
-        // Bit 1 names row 2, which this cut-down table doesn't have: skipped, not empty-stringed.
+        // Bit 1 names row 2, absent here: skipped.
         assert_eq!(n.for_mask(0b111), ["Meat", "Cheese"]);
         // Bit 31 is past `MAX_FOOD_BITS` entirely.
         assert_eq!(n.for_mask(0x8000_0001), ["Meat"]);
diff --git a/crates/benilla-formats/src/creature_sound.rs b/crates/benilla-formats/src/creature_sound.rs
index dcc82e29..c52d0846 100644
--- a/crates/benilla-formats/src/creature_sound.rs
+++ b/crates/benilla-formats/src/creature_sound.rs
@@ -1,27 +1,7 @@
-//! Creature voice: **CreatureDisplayInfo.SoundID → CreatureSoundData.dbc** (decision 0070
-//! slice 3) — the per-display voice kit set (exertion/wound/death/aggro/fidgets…).
-//!
-//! Layouts — VERIFIED against build 5875 (header + row decode, 2026-07-02):
-//! `CreatureSoundData` **406 × 30 × 120 B**: `ID, ExertionID, ExertionCriticalID, InjuryID,
-//! InjuryCriticalID, InjuryCrushingBlowID, DeathID, StunID, StandID, FootstepID (a
-//! FootstepTerrainLookup **class**, NOT a kit), AggroID, WingFlapID, WingGlideID, AlertID,
-//! Fidget[4], CustomAttack[4], NPCSoundID, LoopSoundID, CreatureImpactType (0 flesh · 1 stone ·
-//! 2 wood · 3 ethereal), JumpStartID, JumpEndID, PetAttackID, PetOrderID, PetDismissID`.
-//! Columns **27/28/29** are the pet's own voice (decision 2039): 27 and 28 are what the bark
-//! dispatcher `0x623a40` reaches at states 2 and 1 — `SMSG_PET_ACTION_SOUND`'s two selectors —
-//! and 29 is `SMSG_PET_DISMISS_SOUND`'s, resolved fresh by model id at `0x604140` rather than off
-//! the cached row, which is why a census over the cache's consumers missed it. The **names** here
-//! are the community's and stay INFERRED — a DBC carries no column names — but the shipped kits
-//! corroborate them: the four rows that populate 27/28 name `A_<demon>_KILL` and `A_<demon>_ORDER`.
-//! The column nothing reads is **22**, which is also empty on all 406 rows.
-//! Spot-check row 26: exertion 312/313, injury 315/316/0, death 314, stun 690, stand 317,
-//! footstep class 8, aggro 694, alert 1107 — all coherent kit-id ranges.
-//! The chain is `UNIT_FIELD_DISPLAYID` → `CreatureDisplayInfo.SoundID`, **falling back to
-//! `CreatureModelData.SoundID`** (col 13 of the 430 × 16 × 64 B table) when the display's own FK
-//! is 0 — the client's generic resolution (wow-re `benilla-pins.md` B11b; the earlier "no model
-//! fallback in 1.12" note here was wrong). The fallback is load-bearing: 10 261 of 10 534
-//! displays carry SoundID 0, and with the model link 10 533/10 534 resolve a row (byte-census
-//! 2026-07-03) — character displays reach footstep class 7 this way, as data, not client logic.
+//! Creature voice: `CreatureDisplayInfo.SoundID` to `CreatureSoundData.dbc`, 30 `u32` columns of
+//! per-display voice kits whose names are the community's, since a DBC carries none. Column 22
+//! (`NPCSoundID`) is empty on every row and unread. A display whose own `SoundID` is 0, nearly
+//! every one, resolves through `CreatureModelData.SoundID` (col 13), as the client does.
 
 use std::collections::HashMap;
 
@@ -31,8 +11,7 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 
 use crate::dbc::{parse, u32_at};
 
-/// One `CreatureSoundData` row — every field is a SoundEntries kit id (0 = none) except where
-/// noted.
+/// One `CreatureSoundData` row; every field is a `SoundEntries` kit id (0 for none) unless noted.
 pub struct CreatureVoice {
     /// Attack grunt `[normal, critical]`.
     pub exertion: [u32; 2],
@@ -42,8 +21,7 @@ pub struct CreatureVoice {
     pub stun: u32,
     /// Fired by the `$FDX` anim event.
     pub stand: u32,
-    /// `FootstepTerrainLookup.CreatureFootstepID` — the creature's footstep **class**, joined
-    /// against the terrain type (NOT a kit id).
+    /// The footstep class (`FootstepTerrainLookup.CreatureFootstepID`), not a kit id.
     pub footstep_class: u32,
     pub aggro: u32,
     /// Fired by `$WNG` / `$WGG`.
@@ -56,29 +34,23 @@ pub struct CreatureVoice {
     pub custom_attack: [u32; 4],
     /// A looping body sound (SoundEntries type 27).
     pub loop_sound: u32,
-    /// Melee impact material: 0 flesh · 1 stone · 2 wood · 3 ethereal (WeaponImpactSounds slot
-    /// class — consumed with combat impacts).
+    /// Melee impact material (`WeaponImpactSounds`): 0 flesh, 1 stone, 2 wood, 3 ethereal.
     pub impact_type: u32,
     pub jump_start: u32,
     pub jump_end: u32,
-    /// **Column 27** — the bark a pet gives when it takes an attack order
-    /// (`SMSG_PET_ACTION_SOUND` selector `PET_TALK_ATTACK`, the reference's bark state **2**,
-    /// read at `0x623ad3` as `[row+0x6c]`).
+    /// Column 27, the bark on an attack order: `SMSG_PET_ACTION_SOUND`'s `PET_TALK_ATTACK`, bark
+    /// state 2 of `0x623a40` (`0x623ad3` reads `[row+0x6c]`).
     pub pet_attack: u32,
-    /// **Column 28** — the bark a pet gives when it acknowledges an ordered spell
-    /// (`SMSG_PET_ACTION_SOUND` selector `PET_TALK_SPECIAL_SPELL`, the reference's bark state
-    /// **1**, read at `0x623ac8` as `[row+0x70]`).
+    /// Column 28, the bark acknowledging an ordered spell: `PET_TALK_SPECIAL_SPELL`, bark state 1
+    /// (`0x623ac8` reads `[row+0x70]`).
     pub pet_order: u32,
-    /// **Column 29** — what a dismissed pet says as it goes (`SMSG_PET_DISMISS_SOUND`'s handler
-    /// `0x604140`, read at `0x6041c4`/`0x6041dc` as `[row+0x74]`).
-    ///
-    /// Not a bark: it is off `0x623a40`'s table entirely, played at a bare world position with no
-    /// unit, no latch and no attach point — because by the time it sounds the pet is gone.
+    /// Column 29, `SMSG_PET_DISMISS_SOUND`'s parting line: `0x604140` reads `[row+0x74]`
+    /// (`0x6041c4`, `0x6041dc`) and plays it at a bare world position, since the pet is gone.
     pub pet_dismiss: u32,
 }
 
-/// display id → voice rows, joined through `CreatureDisplayInfo.SoundID`, plus the raw
-/// `CreatureModelData.SoundID` join the dismiss sound needs on its own.
+/// Voice rows by display id through `CreatureDisplayInfo.SoundID`, and by model id through
+/// `CreatureModelData.SoundID` for the dismiss sound.
 pub struct CreatureVoiceCatalog {
     display_to_sound: HashMap<u32, u32>,
     model_to_sound: HashMap<u32, u32>,
@@ -86,18 +58,14 @@ pub struct CreatureVoiceCatalog {
 }
 
 impl CreatureVoiceCatalog {
-    /// The voice set for a creature **display id** (the `NetEntity.display_id` the wire gives us).
+    /// The voice set for a creature display id (`UNIT_FIELD_DISPLAYID`).
     pub fn for_display(&self, display_id: u32) -> Option<&CreatureVoice> {
         self.rows.get(self.display_to_sound.get(&display_id)?)
     }
 
-    /// The voice set for a **`CreatureModelData` id**, through that table's own `SoundID`
-    /// (col 13) with no display in between.
-    ///
-    /// The odd one out, and deliberately so: every other caller starts from
-    /// `UNIT_FIELD_DISPLAYID`, but `SMSG_PET_DISMISS_SOUND` names a model directly and the
-    /// reference resolves it exactly this way (`0x604140`: `[[0xc0de68] + id*4] + 0x34` →
-    /// `[[0xc0de54] + sound*4]`) — no display step, no fallback.
+    /// The voice set for a `CreatureModelData` id through its own `SoundID` (col 13), with no
+    /// display step and no fallback: `SMSG_PET_DISMISS_SOUND` names a model, and `0x604140`
+    /// resolves it so (`[[0xc0de68] + id*4] + 0x34`, then `[[0xc0de54] + sound*4]`).
     pub fn for_model(&self, model_id: u32) -> Option<&CreatureVoice> {
         self.rows.get(self.model_to_sound.get(&model_id)?)
     }
@@ -135,7 +103,7 @@ fn cmd_schema() -> Schema {
     s
 }
 
-/// Read both tables off the patch chain into the joined catalog.
+/// Read the three tables off the patch chain into the joined catalog.
 pub fn load_creature_voice_catalog(chain: &mut Chain) -> Result<CreatureVoiceCatalog> {
     let bytes = chain
         .read_file("DBFilesClient\\CreatureSoundData.dbc")
@@ -194,7 +162,7 @@ pub fn load_creature_voice_catalog(chain: &mut Chain) -> Result<CreatureVoiceCat
         else {
             continue;
         };
-        // The display's own FK wins; 0 falls back to the model's (module docs — B11b).
+        // The display's own `SoundID` wins; 0 falls back to the model's.
         let sound = if sound != 0 {
             Some(sound)
         } else {
@@ -215,8 +183,6 @@ pub fn load_creature_voice_catalog(chain: &mut Chain) -> Result<CreatureVoiceCat
 mod tests {
     use super::*;
 
-    /// The join works on the real 5875 tables: display 26 resolves the byte-decoded row (death
-    /// kit 314, footstep class 8), and a majority of sound-linked displays resolve to a real row.
     #[test]
     fn real_creature_voice_resolves() {
         let data = crate::wow_data_or_skip!();
@@ -230,9 +196,7 @@ mod tests {
         assert_eq!(v.footstep_class, 8);
         assert_eq!(v.aggro, 694);
 
-        // The CreatureModelData fallback (B11b): the Elwynn wolf display (903) has
-        // CreatureDisplayInfo.SoundID 0 and resolves through its model's SoundID (43);
-        // the human-male character display (49) reaches footstep class 7 the same way.
+        // The model fallback: the Elwynn wolf (903) and a human male (49) have display `SoundID` 0.
         let wolf = cat.for_display(903).expect("wolf resolves via the model");
         assert_eq!(wolf.footstep_class, 8);
         let human = cat
@@ -240,20 +204,8 @@ mod tests {
             .expect("human male resolves via the model");
         assert_eq!(human.footstep_class, 7);
     }
-    /// **The pet voice columns are a warlock-demon surface, and the shipped data names them.**
-    ///
-    /// Exactly **four** of the 406 rows carry columns 27/28/29 — the Imp, Succubus, Doomguard and
-    /// Voidwalker voice rows — and the kits they name are `A_<demon>_KILL`, `A_<demon>_ORDER` and
-    /// `A_<demon>_DISMISS`. That naming is an *independent* confirmation of which column is
-    /// which: the reference sends `PET_TALK_ATTACK` to bark state 2 = column 27,
-    /// `PET_TALK_SPECIAL_SPELL` to state 1 = column 28, and `SMSG_PET_DISMISS_SOUND` to column 29
-    /// — and the data calls those three `_KILL`, `_ORDER` and `_DISMISS`, in that order, three
-    /// times over (decision 2039; it closes wow-re's open question about the names,
-    /// `feign-death-dyndead.md` §12).
-    ///
-    /// **A hunter pet is therefore silent on all three, faithfully** — its row's columns are 0,
-    /// so the reference reads a zero kit and plays nothing. The Felhunter has no kit in the file
-    /// at all. Skips without client data.
+    /// Only four rows carry columns 27-29, and their kits are named `_KILL`, `_ORDER` and
+    /// `_DISMISS` in column order; a hunter pet's are 0, so it is silent, as in the reference.
     #[test]
     fn only_the_four_demon_voices_carry_pet_barks() {
         let data = crate::wow_data_or_skip!();
@@ -276,8 +228,7 @@ mod tests {
             })
             .collect();
         carrying.sort_unstable();
-        // Casing is the file's own — `A_Imp_Dismiss` and `A_DOOMGUARD_DISMISS01` are how those two
-        // rows are written, and the lookup is case-insensitive anyway.
+        // Casing is the file's own; the kit lookup is case-insensitive.
         assert_eq!(
             carrying,
             vec![
@@ -308,8 +259,6 @@ mod tests {
             ],
         );
 
-        // Reachable from real displays, not orphan rows: the Imp's voice is the one 25 of them
-        // share, and the wolf a hunter tames carries none of the three.
         let imp = cat.for_display(904).expect("an imp display resolves");
         assert_eq!(
             (imp.pet_attack, imp.pet_order, imp.pet_dismiss),
@@ -321,9 +270,7 @@ mod tests {
             (0, 0, 0)
         );
 
-        // The dismiss sound's own join — `CreatureModelData.SoundID` with **no display step**
-        // (`0x604140`). The imp's model must reach the same row its displays do, or the packet
-        // would be silent for the one pet it exists for.
+        // The dismiss sound's model join (`0x604140`) reaches the imp's row too.
         let by_model = cat
             .for_model(
                 *cat.model_to_sound
diff --git a/crates/benilla-formats/src/creature_types.rs b/crates/benilla-formats/src/creature_types.rs
index c4994d90..55a8ae92 100644
--- a/crates/benilla-formats/src/creature_types.rs
+++ b/crates/benilla-formats/src/creature_types.rs
@@ -1,14 +1,6 @@
-//! CreatureType.dbc — the 13-row creature-class table (Beast, Humanoid, Critter, Totem, …).
-//!
-//! The one consumer today: the TAB-target scan's critter rejection (wow-re
-//! `targeting-nearest-and-autoacquire.md`: the scorer `0x494200` looks the candidate's creature
-//! type up in the cached table `[0xc0de2c]` and rejects when `row[+0x28] & 1` — **flag bit 0**).
-//! In the shipped 1.12 data only **Critter (8)** carries the bit (the "critter/totem/non-combat
-//! pet" gloss is later-era; see the real-chain test). A unit's creature type itself comes off
-//! the wire (`SMSG_CREATURE_QUERY_RESPONSE`), cached with its name.
-//!
-//! Record layout (1.12, 11 × u32-slot fields): id@0, name(8 locales + flags = 9 slots)@1..9,
-//! flags@10.
+//! `CreatureType.dbc`: each creature type's flags word (column 10). The TAB-target scorer
+//! (`0x494200`) looks a unit's type up in its cached table (`[0xc0de2c]`) and rejects it when
+//! `row[+0x28] & 1`. A unit's type comes from `SMSG_CREATURE_QUERY_RESPONSE`.
 
 use std::collections::HashMap;
 
@@ -20,16 +12,13 @@ use crate::Chain;
 
 const CREATURE_TYPE: &str = "DBFilesClient\\CreatureType.dbc";
 
-/// creature-type id → the row's flags dword. Query through [`CreatureTypeFlags::no_tab_target`].
+/// Creature type id → the row's flags word.
 #[derive(Debug, Default, Clone)]
 pub struct CreatureTypeFlags(HashMap<u32, u32>);
 
 impl CreatureTypeFlags {
-    /// Whether this creature type is excluded from TAB/nearest-enemy targeting — the client's
-    /// `flags & 1` test. In the shipped **1.12** data exactly ONE row carries the bit:
-    /// **Critter (8)** (real-chain verified below — Totem 11 does NOT; the "can't tab totems"
-    /// lore is a later-era flag change, not 5875 data). An unknown or missing type is targetable
-    /// (the client's out-of-range index skips the check).
+    /// Whether TAB targeting skips this type (`flags & 1`): in 1.12 data only Critter (8), not
+    /// Totem (11). An unknown type is targetable, as the client skips an out-of-range index.
     pub fn no_tab_target(&self, creature_type: u32) -> bool {
         self.0.get(&creature_type).is_some_and(|f| f & 1 != 0)
     }
@@ -72,10 +61,6 @@ pub fn load_creature_type_flags(chain: &mut Chain) -> Result<CreatureTypeFlags>
 mod tests {
     use super::*;
 
-    /// The shipped 1.12 data, read through the real chain when the install is present: **11**
-    /// rows (ids 1–11), and exactly one carries flag bit 0 — **Critter (8)**. Totem (11) does
-    /// NOT (verified against the real file; the critter/totem gloss from later expansions doesn't
-    /// hold for 5875 data). Beast (1) and Humanoid (7) are targetable.
     #[test]
     fn shipped_flags_mark_only_critter() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/creatures.rs b/crates/benilla-formats/src/creatures.rs
index e6e6212c..0d7b3c7c 100644
--- a/crates/benilla-formats/src/creatures.rs
+++ b/crates/benilla-formats/src/creatures.rs
@@ -1,24 +1,6 @@
-//! Creature display resolution: `displayId` → M2 model + skin textures + scale.
-//!
-//! An NPC's `UNIT_FIELD_DISPLAYID` indexes **CreatureDisplayInfo.dbc**, which gives a `ModelID`
-//! (into **CreatureModelData.dbc**, the `.mdx` path), a per-display scale, and up to three skin
-//! texture names. Creature M2s leave their `Monster1/2/3` texture slots blank and pull the skin
-//! from these names — the texture lives **in the same directory as the model** (wowdev.wiki). The
-//! effective render scale is `CreatureModelData.modelScale * CreatureDisplayInfo.creatureModelScale`.
-//!
-//! **Character-model NPCs.** A humanoid NPC (guard, questgiver, townsfolk) uses a `Character\…` body
-//! M2 — the same model a player wears — but its appearance is *not* on the wire (as a player's is);
-//! it lives in **CreatureDisplayInfoExtra.dbc**, reached via `CreatureDisplayInfo.ExtendedDisplayInfoID`
-//! (0 for a plain beast). That row supplies race/sex + the customization selectors and, in field 18, a
-//! **bake name** — a pre-composited body atlas the client ships under `Textures\BakedNpcTextures\` and
-//! loads directly (rather than compositing live like the local player). We surface it as
-//! [`NpcAppearance`]; the beast skin path ([`CreatureModel::textures`]) is untouched.
-//!
-//! Layouts verified against build 5875 (field counts from the file header, cross-checked with
-//! wowdev.wiki + vmangos `DBCStructure.h`): CreatureModelData = 16 fields (ID@0, ModelName@2,
-//! ModelScale@4, CollisionHeight@15); CreatureDisplayInfo = 12 fields (ID@0, ModelID@1, ExtendedDisplayInfoID@3, Scale@4,
-//! TextureVariation@6/7/8); CreatureDisplayInfoExtra = 19 fields (ID@0, Race@1, Sex@2, Skin@3, Face@4,
-//! HairStyle@5, HairColor@6, FacialHair@7, Equipment@8..17, BakeName@18).
+//! Creature display resolution: a `displayId` to its M2, skin textures and scale through
+//! `CreatureDisplayInfo` and `CreatureModelData`. A humanoid NPC's look is not on the wire: it
+//! comes from `CreatureDisplayInfoExtra` and a baked atlas under `Textures\BakedNpcTextures\`.
 
 use std::collections::HashMap;
 
@@ -32,45 +14,30 @@ const CREATURE_MODEL_DATA: &str = "DBFilesClient\\CreatureModelData.dbc";
 const CREATURE_DISPLAY_INFO: &str = "DBFilesClient\\CreatureDisplayInfo.dbc";
 const CREATURE_DISPLAY_INFO_EXTRA: &str = "DBFilesClient\\CreatureDisplayInfoExtra.dbc";
 
-/// A resolved creature: model path + effective scale + its (up to three) skin texture names, plus —
-/// for a character-model NPC — the [`NpcAppearance`] that skins its body.
+/// A resolved creature display: model, scale, skins and, for a humanoid NPC, its appearance.
 #[derive(Debug, Clone)]
 pub struct CreatureModel {
-    /// `.mdx` path (the M2 loader normalizes to `.m2`), e.g. `Creature\Basilisk\Basilisk.mdx`.
+    /// `.mdx` path (the M2 loader maps it to `.m2`), e.g. `Creature\Basilisk\Basilisk.mdx`.
     pub model_path: String,
     /// `CreatureModelData.modelScale * CreatureDisplayInfo.creatureModelScale`.
     pub scale: f32,
-    /// `textureVariation[0..2]` — bare names (no dir/extension); `None` where empty. The renderer
-    /// resolves a used one to `<dir-of-model_path>\<name>.blp` for the model's `Monster1/2/3` slots.
-    /// For a character-model NPC the body skin comes from [`Self::npc_appearance`]'s baked atlas
-    /// regardless; these slots are empty on ~98% of such rows and unused for the body on the rest
-    /// (wow-re-confirmed — a `Monster`-slot binding on a character M2 is a separate, untraced mechanism).
+    /// `textureVariation[0..2]`, bare names found beside the model, for its `Monster1/2/3` slots;
+    /// a humanoid NPC's body build (`0x5fb200`) never reads them.
     pub textures: [Option<String>; 3],
-    /// A character-model NPC's body appearance (from CreatureDisplayInfoExtra, via the display's
-    /// `ExtendedDisplayInfoID`). `None` for a plain beast/monster (ExtendedDisplayInfoID 0) — those
-    /// skin from [`Self::textures`], not here.
+    /// A character-model NPC's appearance; `None` for a plain creature (`ExtendedDisplayInfoID` 0).
     pub npc_appearance: Option<NpcAppearance>,
-    /// `CreatureDisplayInfo.BloodLevel` (+0x28) — **tier 1** of the reference's UnitBloodLevels
-    /// row resolve. Not a resolved key: the three tiers need the table to know which candidate
-    /// lands, so they live in [`crate::BloodCatalog::level_key`], which is what a consumer calls.
+    /// `CreatureDisplayInfo.BloodLevel` (+0x28), tier 1 of the reference's `UnitBloodLevels` row
+    /// resolve, which [`crate::BloodCatalog::level_key`] performs.
     pub blood_display: i32,
-    /// `CreatureModelData.BloodID` (+0x14) — **tier 2** of the same resolve. `−1` in 122 of the
-    /// 430 shipped models; that is *not* "bloodless", it is a tier-2 miss that falls through to
-    /// tier 3 (see [`crate::BloodCatalog::level_key`]).
+    /// `CreatureModelData.BloodID` (+0x14), tier 2 of the same resolve: `−1` is a miss that falls
+    /// through to tier 3, not bloodlessness.
     pub blood_model: i32,
-    /// `CreatureModelData.collisionHeight` — the unit's collision box height in **raw model units**
-    /// (multiply by the unit's render scale for world yards; see
-    /// [`CreatureCatalog::collision_height`], which is the accessor every consumer should use).
+    /// `CreatureModelData.collisionHeight`, in raw model units.
     pub collision_height: f32,
 }
 
-/// A character-model NPC's appearance, from **CreatureDisplayInfoExtra.dbc**. A humanoid NPC wears a
-/// `Character\…` body M2 whose skin is not on the wire; this carries what the client needs to render
-/// it: race/sex + the customization selectors (for the hair mesh + the geoset selection), the ten worn
-/// **equipment** display ids (the armor geosets + the helm/shoulder attach models), and a `bake_name`
-/// — the pre-composited body atlas the client ships under `Textures\BakedNpcTextures\` and loads
-/// directly. `skin`/`face` are already baked into that atlas; they're kept for completeness and for the
-/// live-composite fallback when a row carries no bake name.
+/// A character-model NPC's appearance, from `CreatureDisplayInfoExtra.dbc`. `skin` and `face` are
+/// already in the baked atlas; they serve the live composite when a row has no bake name.
 #[derive(Debug, Clone)]
 pub struct NpcAppearance {
     pub race: u8,
@@ -80,15 +47,10 @@ pub struct NpcAppearance {
     pub hair_style: u8,
     pub hair_color: u8,
     pub facial_hair: u8,
-    /// The ten worn-equipment `ItemDisplayInfo` display ids (fields 8..17), **bodyslot-indexed**:
-    /// `0` head · `1` shoulder · `2` shirt · `3` chest · `4` belt · `5` pants · `6` boots · `7` wrist ·
-    /// `8` gloves · `9` tabard (no cloak column — the row stops at bodyslot 9). `0` = the slot is
-    /// empty. Direct display ids (not item entries — no template round-trip): the head/shoulder ids
-    /// drive the helm/pauldron attach sub-models and the shirt..tabard ids drive the equipment geosets,
-    /// through the same `ItemDisplayInfo` catalog + geoset machinery the player wire path uses.
+    /// Worn `ItemDisplayInfo` ids (fields 8..17), 0 = empty, by body slot: head, shoulder, shirt,
+    /// chest, belt, pants, boots, wrist, gloves, tabard (no cloak column).
     pub equipment: [u32; 10],
-    /// The pre-baked body-atlas file name (bare, no dir) under `Textures\BakedNpcTextures\`; `None`
-    /// when field 18 is empty (then the body composites live from the fields above, like a player).
+    /// The baked body atlas under `Textures\BakedNpcTextures\`; `None` composites the body live.
     pub bake_name: Option<String>,
 }
 
@@ -96,24 +58,16 @@ pub struct NpcAppearance {
 #[derive(Debug, Clone)]
 struct DisplayRow {
     model_id: u32,
-    /// `ExtendedDisplayInfoID` — the CreatureDisplayInfoExtra key for a character-model NPC; 0 = none.
+    /// `ExtendedDisplayInfoID`: the `CreatureDisplayInfoExtra` key; 0 = none.
     extended_id: u32,
     scale: f32,
     textures: [Option<String>; 3],
-    /// `BloodLevel` (field 10) — a per-display UnitBloodLevels override. `0` in 10498 of the
-    /// 10534 shipped displays, and `0` is not a row of that table, so it falls through to the
-    /// model's `BloodID` (see [`CreatureModel::blood_display`]).
+    /// `BloodLevel` (field 10), a per-display `UnitBloodLevels` override; 0 names no row.
     blood_level: u32,
-    /// `SizeClass` (field 9, @+0x24) — the display's **size-class override**, read signed:
-    /// `−1` (1 791 of the 10 534 shipped rows) defers to the model's own
-    /// [`ModelRow::size_class`]. See [`CreatureCatalog::size_class`].
+    /// `SizeClass` (field 9, +0x24), the display's override, read signed: `−1` defers to the model.
     size_class: i32,
-    /// `CreatureModelAlpha` (field 5, @+0x14) — the display's **base render opacity**, 0..=255.
-    /// This is the `baseAlpha` of the reference's per-unit alpha product (`0x60d2d0`, the CGUnit
-    /// vtbl+0x6c getter: `CreatureDisplayInfo+0x14 × (1/255)`; wow-re `ghost-death-visuals.md`
-    /// §2.3) — an authored translucency 445 of the 10534 shipped displays carry (wisps, spirits,
-    /// ghosts; the modal non-opaque value is 128). Players are not on this chain (the getter
-    /// returns a flat 1.0 for them).
+    /// `CreatureModelAlpha` (field 5, +0x14), 0..=255: the `baseAlpha` of the reference's unit
+    /// alpha product (`0x60d2d0`, × 1/255), which is a flat 1.0 for players.
     model_alpha: u32,
 }
 
@@ -122,41 +76,28 @@ struct DisplayRow {
 struct ModelRow {
     path: String,
     scale: f32,
-    /// `Flags` (field 1) — see [`CreatureCatalog::breathes`] for the one bit we read.
+    /// `Flags` (field 1); bit 0x2 is the no-breath flag.
     flags: u32,
-    /// `SizeClass` (field 3, @+0x0c) — the model's own audible size, `0 Small · 1 Medium ·
-    /// 2 Large · 3 Giant · 4 Colossal`, and the fallback arm of [`CreatureCatalog::size_class`].
-    /// Reads signed for symmetry with the display override; every one of the 430 shipped rows is
-    /// in `0..=4`, so the fallback always answers.
+    /// `SizeClass` (field 3, +0x0c), 0 Small to 4 Colossal, read signed like the display's.
     size_class: i32,
-    /// `BloodID` — see [`CreatureModel::blood_model`]. Reads signed: `−1` in 122 of the 430
-    /// shipped rows, which the reference treats as a tier-2 miss, not as bloodlessness.
+    /// `BloodID`, read signed: `−1` is a tier-2 miss, not bloodlessness.
     blood: i32,
-    /// `FootprintTextureID` (field 6) — the `FootprintTextures.dbc` key. Reads signed: `−1`
-    /// (133 of 430 shipped rows) marks a model that leaves no prints.
+    /// `FootprintTextureID` (field 6), read signed: `−1` leaves no prints.
     footprint_texture: i32,
-    /// `FootprintTextureLength`/`Width` (fields 7/8), authored in **inches** — the client caches
-    /// them ×(1/36) into yards (byte-verified at `0x607a00`, wow-re mount-composition.md).
+    /// `FootprintTextureLength`/`Width` (fields 7/8), in inches (× 1/36 to yards, `0x607a00`).
     footprint_length: f32,
     footprint_width: f32,
-    /// `collisionHeight` (field 15), raw model units — see [`CreatureCatalog::collision_height`].
+    /// `collisionHeight` (field 15), raw model units.
     collision_height: f32,
-    /// `FoleyMaterialID` (field 10) — a `Material.dbc` id, and the whole of a *creature's* armor
-    /// foley (see [`CreatureCatalog::foley_material`]). `[unit+0xb3c]` is this row, and the
-    /// reference reads it at `+0x28`, which is field 10 on the 16-field 5875 record.
+    /// `FoleyMaterialID` (field 10): the reference reads `[unit+0xb3c]+0x28`, field 10 of 16.
     foley_material: u32,
-    /// `FootstepShakeSize` (field 11) and `DeathThudShakeSize` (field 12) — **`CameraShakes.dbc`
-    /// row ids**, 0 on a model that shakes nothing. Only 25 of the 430 shipped rows carry a
-    /// footstep shake, and the set is exactly the thumping-giant list (Ancients, kodos, sea and
-    /// mountain giants, titans, dragons, Anubisath, stone keeper, fel beast, Nian, Lord Kezzak,
-    /// bear) — see [`crate::CameraShakeCatalog`] and decision 1540.
+    /// `FootstepShakeSize`/`DeathThudShakeSize` (fields 11/12), `CameraShakes.dbc` ids; 0 = none.
     footstep_shake: u32,
     death_thud_shake: u32,
 }
 
-/// A display's footprint-decal parameters (see [`CreatureCatalog::footprint`]): the
-/// `FootprintTextures.dbc` key + the print rectangle in **yards** (length along the facing,
-/// width across), pre-scale.
+/// A footprint decal: the `FootprintTextures.dbc` key and the print size in yards (length along
+/// the facing, width across), before the unit's scale.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct FootprintParams {
     pub texture_id: u32,
@@ -164,61 +105,39 @@ pub struct FootprintParams {
     pub width: f32,
 }
 
-/// Display/model tables loaded from the DBCs, resolving `displayId` → [`CreatureModel`].
-///
-/// `Default` is the **empty** catalog — the same thing "the DBC failed to load" already means to
-/// every consumer (every lookup misses and the caller takes its documented fallback).
+/// The creature display tables; `Default` is empty, which consumers treat as a failed load.
 #[derive(Default)]
 pub struct CreatureCatalog {
-    /// CreatureDisplayInfo: displayId → row.
     display: HashMap<u32, DisplayRow>,
-    /// CreatureModelData: modelId → row.
     models: HashMap<u32, ModelRow>,
-    /// CreatureDisplayInfoExtra: extendedDisplayInfoId → character-model NPC appearance.
     extra: HashMap<u32, NpcAppearance>,
 }
 
 impl CreatureCatalog {
-    /// A display's own `creatureModelScale` column alone — the MOUNT scale law (byte-verified,
-    /// wow-re `mount-composition.md` / `0x613ef0`: a rendered mount = `OBJECT_FIELD_SCALE_X ×
-    /// CreatureDisplayInfo.creatureModelScale`; `CreatureModelData.modelScale` does NOT multiply
-    /// in, unlike [`CreatureModel::scale`]'s spawned-creature product). `None` when the display
-    /// id misses.
+    /// A display's own `creatureModelScale`, the mount scale law: a mount renders at
+    /// `OBJECT_FIELD_SCALE_X × creatureModelScale`, without `modelScale` (`0x613ef0`).
     pub fn display_scale(&self, display_id: u32) -> Option<f32> {
         self.display.get(&display_id).map(|r| r.scale)
     }
 
-    /// A display's **footstep camera-shake preset** — `CreatureModelData.FootstepShakeSize`, a
-    /// `CameraShakes.dbc` row id fired on each footfall of a heavy enough creature. `None` when
-    /// the display id misses or the model shakes nothing (405 of the 430 shipped models).
-    ///
-    /// The trigger, the evaluator and the distance falloff are decision 1540's; this is the
-    /// authored id and nothing more.
+    /// A display's footstep camera shake, a `CameraShakes.dbc` id (`FootstepShakeSize`).
     pub fn footstep_shake(&self, display_id: u32) -> Option<u32> {
         let row = self.display.get(&display_id)?;
         let id = self.models.get(&row.model_id)?.footstep_shake;
         (id != 0).then_some(id)
     }
 
-    /// A display's **death-thud camera-shake preset** — `CreatureModelData.DeathThudShakeSize`,
-    /// the one-off shake as the body lands. Same conventions as [`Self::footstep_shake`].
+    /// A display's camera shake as the body lands (`DeathThudShakeSize`).
     pub fn death_thud_shake(&self, display_id: u32) -> Option<u32> {
         let row = self.display.get(&display_id)?;
         let id = self.models.get(&row.model_id)?.death_thud_shake;
         (id != 0).then_some(id)
     }
 
-    /// A display's **audible size class** — `0 Small · 1 Medium · 2 Large · 3 Giant ·
-    /// 4 Colossal`, the axis [`crate::DeathThudCatalog`] picks the body-fall sample on.
-    ///
-    /// The reference's own two-step (`0x625500`): the **display's** `SizeClass` column wins, and
-    /// only its `−1` sentinel defers to the **model's**. That order matters — 8 743 of the 10 534
-    /// shipped displays override their model, so reading the model alone would mis-size most of
-    /// the world (every Small display sharing a Medium model, for one).
-    ///
-    /// `None` when either lookup misses, or when **both** rows read `−1`. No shipped row does, so
-    /// that arm exists to keep a broken/absent table silent rather than Small — the same thing
-    /// the reference's own unsigned `sizeClass >= 5` gate (`0x623744`) does with a `−1`.
+    /// A display's audible size class, 0 Small to 4 Colossal, the axis of
+    /// [`crate::DeathThudCatalog`]. The display's `SizeClass` wins and only its `−1` defers to the
+    /// model's (`0x625500`); `None` when both are `−1`, which the reference's unsigned `>= 5` gate
+    /// (`0x623744`) also silences.
     pub fn size_class(&self, display_id: u32) -> Option<u32> {
         let row = self.display.get(&display_id)?;
         let class = match row.size_class {
@@ -228,9 +147,7 @@ impl CreatureCatalog {
         u32::try_from(class).ok()
     }
 
-    /// Every `CreatureModelData` row that names a camera-shake preset: `(model id, path,
-    /// footstep id, death-thud id)`. The **census** view — the runtime reads
-    /// [`Self::footstep_shake`] by display id instead, because that is what a unit carries.
+    /// Every model row naming a shake: `(model id, path, footstep id, death-thud id)`.
     pub fn shaking_models(&self) -> impl Iterator<Item = (u32, &str, u32, u32)> + '_ {
         self.models
             .iter()
@@ -238,103 +155,59 @@ impl CreatureCatalog {
             .map(|(id, m)| (*id, m.path.as_str(), m.footstep_shake, m.death_thud_shake))
     }
 
-    /// Every `CreatureModelData` model path, unordered — the census surface for "is this M2 a
-    /// creature model?", which is what decides whether an animation event on it reaches
-    /// `CGUnit_C::HandleAnimEvent` at all.
+    /// Every model path: being a creature model decides whether an M2's animation events reach
+    /// `CGUnit_C::HandleAnimEvent`.
     pub fn model_paths(&self) -> impl Iterator<Item = &str> + '_ {
         self.models.values().map(|m| m.path.as_str())
     }
 
-    /// Every `CreatureModelData` row as `(model id, path, its own SizeClass)` — the **census**
-    /// view of the death-thud size axis. The runtime reads [`Self::size_class`] by *display* id
-    /// instead, because most displays override this column.
+    /// Every model row as `(model id, path, SizeClass)`; most displays override the column.
     pub fn sized_models(&self) -> impl Iterator<Item = (u32, &str, i32)> + '_ {
         self.models
             .iter()
             .map(|(id, m)| (*id, m.path.as_str(), m.size_class))
     }
 
-    /// Every display as `(display id, its model id)` — the census hop that lets an instrument roll
-    /// a per-display answer (a resolved size class, say) up onto the model that carries the M2.
+    /// Every display as `(display id, model id)`.
     pub fn display_models(&self) -> impl Iterator<Item = (u32, u32)> + '_ {
         self.display.iter().map(|(id, r)| (*id, r.model_id))
     }
 
-    /// A display's **spawned-creature render scale** — the product
-    /// `CreatureModelData.modelScale × CreatureDisplayInfo.creatureModelScale`, the same number
-    /// [`CreatureModel::scale`] carries, without the row's string clones.
-    ///
-    /// Almost nothing in the world reads this: the server folds it into `OBJECT_FIELD_SCALE_X` and
-    /// the client renders a unit at that field alone, so multiplying it again would square it
-    /// (`crate::entities::attach`'s note, wow-re `world_model_scale` `0x613ef0`). The **glue
-    /// screens are the exception** — the character-select pet has no wire object and therefore no
-    /// server scale, and the reference sizes it with exactly this product (`0x472dc6`
-    /// `fld [x+0x10]; fmul [y+0x10]` → a uniform `diag(S,S,S,1)`, wow-re `glue-select-model.md`
-    /// §A4). `None` when either DBC lookup misses.
+    /// `modelScale × creatureModelScale`. The server folds it into `OBJECT_FIELD_SCALE_X`, which
+    /// alone scales a unit (`0x613ef0`), so only the glue screens read this: the reference sizes
+    /// the serverless character-select pet by it (`0x472dc6`).
     pub fn model_scale(&self, display_id: u32) -> Option<f32> {
         let row = self.display.get(&display_id)?;
         let model = self.models.get(&row.model_id)?;
         Some(model.scale * row.scale)
     }
 
-    /// A display's **base render alpha** in `0.0..=1.0` — `CreatureDisplayInfo.CreatureModelAlpha`
-    /// / 255 ([`DisplayRow::model_alpha`]). The first factor of the unit alpha product the aura
-    /// CharProc nodes multiply into (`crate::aura_visual`). `None` for an unknown display; a known
-    /// display with no authored translucency reads `1.0`.
+    /// `CreatureModelAlpha / 255`, the first factor of the unit alpha product.
     pub fn display_base_alpha(&self, display_id: u32) -> Option<f32> {
         self.display
             .get(&display_id)
             .map(|r| f32::from(r.model_alpha.min(255) as u8) / 255.0)
     }
 
-    /// A display's **collision height** in raw model units — `CreatureModelData.collisionHeight`,
-    /// the per-unit `h` every depth line in the client is a fraction of (swim at `0.75·h`, splash at
-    /// `0.4·h`, the foam gate at `2·h`; wow-re has each byte-pinned against `CMovement+0xb4`). World
-    /// yards = this × the unit's render scale (`OBJECT_FIELD_SCALE_X`, which the server has already
-    /// folded the DBC scales into) — the caller multiplies, because only it knows the live scale.
-    ///
-    /// The column is **exactly the model's own MD20 collision-box Z extent**, verified against the
-    /// shipped client for all thirteen character models (`tests::collision_height_is_the_m2_box`) —
-    /// which is what settles the space: it is authored pre-scale, like the geometry it bounds.
-    /// `None` when either DBC lookup misses; callers fall back to the client's own ctor default
-    /// (`2.0277777`, `0x616fd8`).
+    /// `CreatureModelData.collisionHeight`, the `h` of every depth line (swim `0.75·h`, splash
+    /// `0.4·h`, foam gate `2·h`, read against `CMovement+0xb4`). It is the M2's collision-box Z
+    /// extent, pre-scale: the prism is this × `max(OBJECT_FIELD_SCALE_X, creatureModelScale)`
+    /// (`0x60b312` → `0x617501`). A miss takes the constructor default, `2.0277777` (`0x616fd8`).
     pub fn collision_height(&self, display_id: u32) -> Option<f32> {
         let row = self.display.get(&display_id)?;
         Some(self.models.get(&row.model_id)?.collision_height)
     }
 
-    /// The display's **foley material** — a `Material.dbc` id, the creature half of the footfall
-    /// rustle (`0x623610`: `[[unit+0xb3c]+0x28]` handed straight to `0x4584e0`). A *player* does
-    /// not come through here at all: its own override reads the equipped chest instead
-    /// (`0x62fa30`), so this is the answer for creatures — and, for a player wearing a
-    /// non-character display, the body it is actually wearing.
-    ///
-    /// `None` when either DBC lookup misses. `Some(0)` is the real "no material" the data
-    /// carries, and resolves to silence at [`crate::MaterialCatalog::foley_kit`].
-    ///
-    /// **In shipped 5875 data this column is 0 in every one of the 430 rows**, in both the base
-    /// archive's 333-row copy and the patched 430 (`tests::no_shipped_model_carries_a_foley`).
-    /// The creature branch of the foley is therefore inert against the real client's own files:
-    /// the armor rustle you hear is the *player* override's, and no NPC has one. Kept because it
-    /// is the reference's own path and one map lookup, and because a server shipping patched
-    /// DBCs would light it up — not because it does anything today. A future reader finding this
-    /// silent has found the data, not a bug.
+    /// A display's foley material (`Material.dbc`), the creature half of the footfall rustle:
+    /// `0x623610` hands `[[unit+0xb3c]+0x28]` to `0x4584e0`, while a player reads its chest
+    /// (`0x62fa30`). Every shipped row is 0, so an NPC's silent armor is the data, not a bug.
     pub fn foley_material(&self, display_id: u32) -> Option<u32> {
         let row = self.display.get(&display_id)?;
         Some(self.models.get(&row.model_id)?.foley_material)
     }
 
-    /// Does this display's model **breathe** — i.e. may it wear the `$BTH` hardcoded effects
-    /// (cold vapour, underwater bubbles, inebriated bubbles)?
-    ///
-    /// `CreatureModelData.Flags & 0x2` suppresses the whole family (wow-re
-    /// `object-layer/scratch/cold-breath-law.md` Q4, at `[unit+0xb3c]`): 99 of the 430 shipped
-    /// rows carry it — skeletons, ghosts, ghouls, zombies, banshees, every elemental, golems,
-    /// slimes, infernals, voidwalkers, succubi, spiders, frogs, crocodiles, turtles, totems. The
-    /// things that have no breath to see. Every player row is `0x4`, so players pass.
-    ///
-    /// An unknown display breathes — this catalog's degrade shape is "fall back to the common
-    /// case", and the common case is 331 of the 430 rows.
+    /// Whether the model may wear the `$BTH` breath effects: `CreatureModelData.Flags & 0x2`
+    /// suppresses them (`0x600003`, the row at `[unit+0xb3c]`); an unknown display breathes.
     pub fn breathes(&self, display_id: u32) -> bool {
         self.display
             .get(&display_id)
@@ -342,12 +215,8 @@ impl CreatureCatalog {
             .is_none_or(|m| m.flags & 0x2 == 0)
     }
 
-    /// A display's **footprint decal** parameters — `CreatureModelData` fields 6..=8 through the
-    /// display→model chain, sizes converted to **yards** (the client's own ×(1/36) inches→yards
-    /// cache, byte-verified at `0x607a00` for the mounted getter `0x607920`). `None` when either
-    /// lookup misses, the model authors `FootprintTextureID = −1` (no prints — 133 of 430 shipped
-    /// rows), or the print rectangle is degenerate (40 rows carry an id over a 0×0 size). World
-    /// yards = these × the unit's render scale — the caller multiplies, like `collision_height`.
+    /// A display's footprint decal, fields 6..=8, in yards (inches × 1/36, the client's cache at
+    /// `0x607a00` for the getter `0x607920`); `None` for a `−1` texture or a 0×0 print.
     pub fn footprint(&self, display_id: u32) -> Option<FootprintParams> {
         let row = self.display.get(&display_id)?;
         let model = self.models.get(&row.model_id)?;
@@ -360,11 +229,11 @@ impl CreatureCatalog {
         })
     }
 
-    /// Resolve an NPC display id to its model, or `None` if either DBC lookup misses.
+    /// Resolve an NPC display id to its model.
     pub fn model(&self, display_id: u32) -> Option<CreatureModel> {
         let row = self.display.get(&display_id)?;
         let model = self.models.get(&row.model_id)?;
-        // A non-zero ExtendedDisplayInfoID that resolves to an extra row ⇒ a character-model NPC.
+        // A non-zero `ExtendedDisplayInfoID` with an extra row marks a character-model NPC.
         let npc_appearance = (row.extended_id != 0)
             .then(|| self.extra.get(&row.extended_id).cloned())
             .flatten();
@@ -389,14 +258,13 @@ impl CreatureCatalog {
         self.display.is_empty()
     }
 
-    /// Number of character-model NPC appearance rows loaded (for logging/diagnostics). Zero here means
-    /// CreatureDisplayInfoExtra failed to load ⇒ humanoid NPCs stay untextured.
+    /// Number of appearance rows; 0 means `CreatureDisplayInfoExtra` failed to load.
     pub fn extra_len(&self) -> usize {
         self.extra.len()
     }
 }
 
-/// CreatureModelData.dbc — 16 fields in build 5875 (no `mountHeight`). We read ID, ModelName, scale.
+/// CreatureModelData.dbc: 16 fields in build 5875 (no `mountHeight`).
 pub(crate) fn creature_model_data_schema() -> Schema {
     let mut s = Schema::new("CreatureModelData");
     for (name, ty) in [
@@ -422,7 +290,7 @@ pub(crate) fn creature_model_data_schema() -> Schema {
     s
 }
 
-/// CreatureDisplayInfo.dbc — 12 fields in build 5875. We read ID, ModelID, scale, 3 skin textures.
+/// CreatureDisplayInfo.dbc: 12 fields in build 5875.
 pub(crate) fn creature_display_info_schema() -> Schema {
     let mut s = Schema::new("CreatureDisplayInfo");
     for (name, ty) in [
@@ -435,14 +303,11 @@ pub(crate) fn creature_display_info_schema() -> Schema {
         ("TextureVariation0", FieldType::String),
         ("TextureVariation1", FieldType::String),
         ("TextureVariation2", FieldType::String),
-        // **NOT `PortraitTextureName`** — 5875 has no such column, and reading field 9 as a
-        // string would resolve a size class into the string block. The client reads it as a
-        // signed int at `+0x24` and compares it to `-1` (`0x625509`); the shipped column takes
-        // exactly `{-1, 0, 1, 2, 3, 4}` across all 10 534 rows, `-1` on 1 791 of them.
+        // Not `PortraitTextureName` (absent in 5875): a signed size class, tested for -1 at
+        // `0x625509`.
         ("SizeClass", FieldType::UInt32),
         ("BloodLevel", FieldType::UInt32),
-        // Labeled BloodID in some third-party maps, but the 5875 values (33..188, dense) are the
-        // NPC sound-kit range, not blood ids — the blood override is BloodLevel above.
+        // Some maps label this BloodID, but its 5875 values (33..188) are NPC sound ids.
         ("NPCSoundID", FieldType::UInt32),
     ] {
         s.add_field(SchemaField::new(name, ty));
@@ -450,10 +315,7 @@ pub(crate) fn creature_display_info_schema() -> Schema {
     s
 }
 
-/// CreatureDisplayInfoExtra.dbc — 19 fields in build 5875 (`19 × 4 == 76`-byte records; field map
-/// cross-checked with vmangos `DBCStructure.h`). We read the appearance selectors, the 10 equipment
-/// columns (8..17 — `ItemDisplayInfo` display ids for the worn armor geosets + helm/shoulder attach),
-/// and the bake name.
+/// CreatureDisplayInfoExtra.dbc: 19 fields, 76-byte records in 5875 (vmangos `DBCStructure.h`).
 pub(crate) fn creature_display_info_extra_schema() -> Schema {
     let mut s = Schema::new("CreatureDisplayInfoExtra");
     for (name, ty) in [
@@ -492,11 +354,7 @@ pub fn load_creature_catalog(chain: &mut Chain) -> Result<CreatureCatalog> {
                         scale: f32_at(r, 4).unwrap_or(1.0),
                         flags: u32_at(r, 1).unwrap_or(0),
                         size_class: u32_at(r, 3).map_or(-1, |v| v as i32),
-                        // BloodID (field 5) reads signed: −1 in 122 of the 430 shipped rows.
-                        // That is a tier-2 MISS, not bloodlessness — the resolve falls through
-                        // to the records base (1850). Kept signed so the miss is visible.
                         blood: u32_at(r, 5).map_or(0, |v| v as i32),
-                        // FootprintTextureID reads signed too: −1 = no prints (see ModelRow docs).
                         footprint_texture: u32_at(r, 6).map_or(-1, |v| v as i32),
                         footprint_length: f32_at(r, 7).unwrap_or(0.0),
                         footprint_width: f32_at(r, 8).unwrap_or(0.0),
@@ -531,7 +389,6 @@ pub fn load_creature_catalog(chain: &mut Chain) -> Result<CreatureCatalog> {
                         scale: f32_at(r, 4).unwrap_or(1.0),
                         textures: [str_at(&rs, r, 6), str_at(&rs, r, 7), str_at(&rs, r, 8)],
                         blood_level: u32_at(r, 10).unwrap_or(0),
-                        // Signed: −1 is "no override", not a size class (see the field docs).
                         size_class: u32_at(r, 9).map_or(-1, |v| v as i32),
                         model_alpha: u32_at(r, 5).unwrap_or(255),
                     },
@@ -541,10 +398,7 @@ pub fn load_creature_catalog(chain: &mut Chain) -> Result<CreatureCatalog> {
         d
     };
 
-    // CreatureDisplayInfoExtra — the character-model NPC appearance table. Best-effort: a plain beast
-    // catalog is still useful without it (only humanoid NPCs need it), so a load failure degrades to an
-    // empty map (humanoid NPCs stay untextured) rather than sinking the whole catalog. The caller logs
-    // `extra_len()` so a `0` (unexpected — it ships in patch.MPQ) is visible.
+    // Best-effort: without it only humanoid NPCs lose their skins; the caller logs `extra_len()`.
     let extra = load_creature_display_info_extra(chain).unwrap_or_default();
 
     Ok(CreatureCatalog {
@@ -554,7 +408,7 @@ pub fn load_creature_catalog(chain: &mut Chain) -> Result<CreatureCatalog> {
     })
 }
 
-/// Load CreatureDisplayInfoExtra.dbc → `extendedDisplayInfoId` → [`NpcAppearance`].
+/// Load CreatureDisplayInfoExtra.dbc: `extendedDisplayInfoId` → [`NpcAppearance`].
 fn load_creature_display_info_extra(chain: &mut Chain) -> Result<HashMap<u32, NpcAppearance>> {
     let bytes = chain
         .read_file(CREATURE_DISPLAY_INFO_EXTRA)
@@ -577,10 +431,7 @@ fn load_creature_display_info_extra(chain: &mut Chain) -> Result<HashMap<u32, Np
                     hair_style: u32_at(r, 5).unwrap_or(0) as u8,
                     hair_color: u32_at(r, 6).unwrap_or(0) as u8,
                     facial_hair: u32_at(r, 7).unwrap_or(0) as u8,
-                    // fields 8..17 — the ten worn-equipment ItemDisplayInfo display ids, bodyslot-indexed
-                    // (0 head · 1 shoulder · 2 shirt … 9 tabard); `0` = the slot is empty.
                     equipment: std::array::from_fn(|i| u32_at(r, 8 + i).unwrap_or(0)),
-                    // field 18 — the baked body-atlas name.
                     bake_name: str_at(&rs, r, 18),
                 },
             );
@@ -593,10 +444,7 @@ fn load_creature_display_info_extra(chain: &mut Chain) -> Result<HashMap<u32, Np
 mod tests {
     use super::*;
 
-    /// **The blood-row tier populations** over the shipped tables — the measurement behind 1850.
-    /// `CreatureModelData.BloodID = −1` (122 of 430 models) is a tier-2 *miss*, not a bloodless
-    /// marker, so those displays fall through to the reference's tier-3 records base and bleed
-    /// RED. benilla read `−1` as bloodless and dropped the spurt on all 595 of them.
+    /// `BloodID = −1` is a tier-2 miss, so 595 displays reach tier 3 and bleed red.
     #[test]
     fn blood_row_tiers_over_the_shipped_displays() {
         let data = crate::wow_data_or_skip!();
@@ -604,8 +452,7 @@ mod tests {
         let cat = load_creature_catalog(&mut chain).expect("load creature catalog");
         let blood = crate::load_blood_catalog(&mut chain).expect("blood tables");
 
-        // A tier resolves iff its id names a real UnitBloodLevels row — which is exactly what
-        // `level_key` reports when the *other* tier is forced to miss.
+        // A tier resolves iff `level_key` finds its id with the other tier forced to miss.
         let resolves = |v: i32| {
             u32::try_from(v)
                 .ok()
@@ -632,18 +479,7 @@ mod tests {
         assert_eq!(tiers.iter().sum::<usize>(), cat.display.len());
     }
 
-    /// **Tier 3 is ordinary fauna, not an exotic tail** — the content proof behind 1859, and the
-    /// reason the records-base fallback cannot mean "no blood".
-    ///
-    /// Read the tier-3 population by its oddest members — elementals, skeletons, mecha-striders —
-    /// and the natural conclusion is that `BloodID = −1` marks a bloodless creature and the
-    /// fallback is a misread of the disassembly. The population says otherwise: it is *headed* by
-    /// Quilboar (42 displays), Mountain Giants (30), Crocolisks (27), Gnolls (25), Nagas (24) and
-    /// Trolls (17). A fallback that resolved to "no blood" would leave Razorfen, every gnoll camp
-    /// and every Stranglethorn troll bloodless — which is not the game anyone played. That is a
-    /// proof from shipped content, independent of any instruction decode, so the creatures are
-    /// named here: a future round that "simplifies" `level_key` back to two tiers fails saying
-    /// *which creature stopped bleeding*, not merely that a count moved.
+    /// Tier 3 is ordinary fauna, so its records base cannot mean no blood.
     #[test]
     fn the_tier_three_fallback_bleeds_red_on_ordinary_creatures() {
         let data = crate::wow_data_or_skip!();
@@ -651,9 +487,7 @@ mod tests {
         let cat = load_creature_catalog(&mut chain).expect("load creature catalog");
         let blood = crate::load_blood_catalog(&mut chain).expect("blood tables");
 
-        // Each authors `BloodID = −1` on a single, uniquely-pathed model row, and none of their
-        // displays carries a `BloodLevel` override — so every one reaches the resolve by tier 3
-        // alone, with no other tier able to account for the result.
+        // Each has `BloodID = −1` and no display override: tier 3 alone resolves it.
         for path in [
             r"Creature\Quillboar\QuillBoar.mdx",
             r"Creature\Crocodile\Crocodile.mdx",
@@ -685,7 +519,7 @@ mod tests {
             assert!(seen > 0, "{path} is missing from the shipped display table");
         }
 
-        // …and the row it lands on really draws — red, both facings, both sizes.
+        // The records-base row draws, both facings and both sizes.
         for (front, large) in [(true, false), (true, true), (false, false), (false, true)] {
             assert!(
                 blood.effect_id(1, 2, front, large).is_some(),
@@ -694,15 +528,8 @@ mod tests {
         }
     }
 
-    /// **`BloodID = −1` is unfilled data, not a "bloodless" marker** — the evidence that closes
-    /// the question 1850 left open (1859).
-    ///
-    /// Nine shipped models appear under **two** `CreatureModelData` rows for the same art and the
-    /// twins *disagree* about blood; in eight of the nine, one side of the disagreement is `−1`
-    /// (the ninth, FelBat, splits 1 vs 2). A Baby Murloc is a Baby
-    /// Murloc. If `−1` meant "this creature does not bleed", the same creature would bleed or not
-    /// depending on which of its two rows a display happened to name — so `−1` is an unspecified
-    /// value, and the reference's tier-3 records base is precisely the handler for one.
+    /// Nine models have two `CreatureModelData` rows that disagree about blood, eight with one side
+    /// `−1`: the value is unfilled, which tier 3 handles.
     #[test]
     fn the_minus_one_blood_id_is_unfilled_data() {
         let data = crate::wow_data_or_skip!();
@@ -732,9 +559,7 @@ mod tests {
             "the Baby Murloc pair is the clearest case and must be among them: {split:?}"
         );
 
-        // The same unfilled field, one level up: within a single creature family one model says
-        // −1 and its siblings name a colour. A "bloodless" reading would put bleeding quilboar
-        // warriors next to bloodless quilboar in the same Razorfen room.
+        // Within one creature family, one model says −1 and its siblings name a colour.
         let blood_of = |needle: &str| {
             cat.models
                 .values()
@@ -763,11 +588,7 @@ mod tests {
         }
     }
 
-    /// The footprint accessor on the **real** build-5875 DBCs: a display wearing the HumanMale
-    /// body resolves the Base boot print (`FootprintTextures` id 1) at the authored 12×10 inches
-    /// → 1/3 × 5/18 yards (the client's ×1/36 cache conversion, byte-verified at `0x607a00`);
-    /// a display whose model authors `FootprintTextureID = −1` resolves `None`. Guards the
-    /// schema columns (a shifted field would misread every print) and the inches→yards space.
+    /// HumanMale's Base boot print (id 1) is 12×10 inches, 1/3 × 5/18 yd; a `−1` model has none.
     #[test]
     fn footprints_resolve_on_real_data() {
         let data = crate::wow_data_or_skip!();
@@ -788,7 +609,6 @@ mod tests {
         assert_eq!(p.texture_id, 1, "the Base boot print");
         assert!((p.length - 12.0 / 36.0).abs() < 1e-6, "length {}", p.length);
         assert!((p.width - 10.0 / 36.0).abs() < 1e-6, "width {}", p.width);
-        // A −1 model (133 shipped rows) yields no print params through any display over it.
         let printless = cat
             .display
             .iter()
@@ -802,11 +622,6 @@ mod tests {
         assert_eq!(cat.footprint(printless), None);
     }
 
-    /// End-to-end on the **real** build-5875 DBCs: the `ExtendedDisplayInfoID` chain resolves
-    /// character-model NPCs (guards/townsfolk) to a CreatureDisplayInfoExtra appearance whose body is a
-    /// `Character\` M2 skinned by a pre-baked atlas that actually ships under `Textures\BakedNpcTextures\`.
-    /// Guards the extra schema (a shifted column would misread the bake name), the display→extra join, and
-    /// the baked-texture-path convention. Skips when the client data isn't present.
     #[test]
     fn character_model_npcs_resolve_a_shipped_baked_atlas() {
         let data = crate::wow_data_or_skip!();
@@ -818,8 +633,6 @@ mod tests {
             cat.extra_len()
         );
 
-        // Every display that resolves both an appearance and a bake name is definitively a character
-        // model — confirm the body path + that its baked atlas is a real, readable file.
         let mut verified = 0;
         for (&disp, row) in &cat.display {
             if row.extended_id == 0 {
@@ -850,25 +663,7 @@ mod tests {
         );
     }
 
-    /// The worn-equipment columns (fields 8..17) decode in bodyslot order, anchored on live
-    /// server-truth: the **Stormwind City Guard** (display 3167) carries a plate helm (slot 0), a
-    /// pauldron pair (slot 1), and boot/glove/tabard geosets (slots 6/8/9), with empty chest/wrist
-    /// (slots 3/7). These ids are the real `CreatureDisplayInfoExtra` values read off the build-5875
-    /// DBC; a shifted column or a wrong field offset would misread them. Skips without the client data.
-    /// **The size-class column, pinned against the shipped client.** The death-thud sound
-    /// (`benilla-app`'s `sound::death_thud`) picks its sample on this axis alone, so a shifted
-    /// field would re-size the whole world's body-falls silently.
-    ///
-    /// The three arms of `0x625500`, each on a row that exercises it:
-    /// - the **display override** wins — display 792 is a Gorilla (model 136, class `0` Small)
-    ///   overridden to `3` Giant, which is the whole reason the override exists;
-    /// - `−1` **defers to the model** — display 170 is a Sea Giant with no override and the
-    ///   model's `4` Colossal;
-    /// - and an ordinary agreeing row (the Ancient Protector, `3` Giant on both).
-    ///
-    /// The control is the human male at `1` Medium: a schema shift onto a neighbouring column
-    /// would have to keep *all four* of these, and the string-block column that used to be
-    /// misread here (field 9 was labelled `PortraitTextureName`) cannot.
+    /// The three arms of `0x625500`: an override, a `−1` deferral and an agreeing row.
     #[test]
     fn the_size_class_column_resolves_its_three_arms() {
         let data = crate::wow_data_or_skip!();
@@ -893,9 +688,7 @@ mod tests {
         assert_eq!(cat.size_class(49), Some(1), "HumanMale is Medium");
         assert_eq!(cat.size_class(0), None, "no such display");
 
-        // Every shipped display resolves, and inside the reference's own `0..=4` bound — so its
-        // unsigned `>= 5` gate never fires on this data, and no body-fall is silent for want of
-        // a size.
+        // Every display lands in `0..=4`, so the reference's unsigned `>= 5` gate never fires here.
         let mut n = 0;
         for &id in cat.display.keys() {
             let class = cat
@@ -910,15 +703,7 @@ mod tests {
         assert_eq!(n, 10_534, "the whole shipped display table");
     }
 
-    /// **The shake columns, pinned against the shipped client** (B298, decision 1540). Fields 11
-    /// and 12 are `CameraShakes.dbc` row ids, and the evidence that the map is right is not that
-    /// the names look plausible — it is that the census is *semantic*: 25 of 430 rows carry a
-    /// footstep shake and every one of them is a creature heavy enough to shake a camera, the
-    /// amplitude ranks by mass, and nothing dangles.
-    ///
-    /// The Ancient Protector is the reported row (Dolanaar's tree guardians, B298); the human male
-    /// is the control that must stay zero, since a schema shift would smear a neighbouring column
-    /// into these and give *everything* a shake.
+    /// Fields 11 and 12 are `CameraShakes.dbc` ids; 25 models, all heavy, carry a footstep shake.
     #[test]
     fn the_footstep_shake_columns_are_the_thumping_giants() {
         let data = crate::wow_data_or_skip!();
@@ -936,20 +721,18 @@ mod tests {
             Some(11),
             "Ancient Protector thud"
         );
-        // Display 1460 is Onu's Ancient of Lore (model 187) — the heavier row 2.
+        // Display 1460 is Onu's Ancient of Lore (model 187), the heavier row 2.
         assert_eq!(
             cat.footstep_shake(1460),
             Some(2),
             "Ancient of Lore footstep"
         );
 
-        // The control: a player body shakes nothing, at either column. If a schema shift walked
-        // these indices onto a neighbour, this is the assert that catches it.
+        // The control: a player body shakes nothing in either column.
         assert_eq!(cat.footstep_shake(49), None, "HumanMale leaves no thump");
         assert_eq!(cat.death_thud_shake(49), None, "nor a thud");
 
-        // The census, and the property that licenses the whole column map: every id a creature
-        // names must land on a real row of the 24-row table.
+        // Every id a creature names lands on a row of the 24-row table.
         let shakes = crate::load_camera_shakes(&mut chain).expect("load CameraShakes.dbc");
         let mut footstep = 0;
         for (_, path, foot, thud) in cat.shaking_models() {
@@ -975,7 +758,7 @@ mod tests {
         let npc = guard
             .npc_appearance
             .expect("display 3167 is a character-model NPC with an appearance row");
-        // 0 head · 1 shoulder · 2 shirt · 3 chest · 4 belt · 5 pants · 6 boots · 7 wrist · 8 gloves · 9 tabard.
+        // Body-slot order: head, shoulder, shirt, chest, belt, pants, boots, wrist, gloves, tabard.
         assert_eq!(
             npc.equipment,
             [14964, 7541, 7223, 0, 7224, 7225, 7255, 0, 7698, 6255],
@@ -983,21 +766,6 @@ mod tests {
         );
     }
 
-    /// **The column's space, pinned.** `CreatureModelData.collisionHeight` is not a derived or
-    /// hand-authored number: it is a verbatim copy of the model's own MD20 **collision-box** Z
-    /// extent, in raw model units. Asserted for all thirteen player-race body models against the
-    /// shipped client — which is what licenses [`CreatureCatalog::collision_height`]'s contract
-    /// that world yards = column × render scale (it is pre-scale, exactly like the geometry it
-    /// bounds), and pins field index 15 so a schema shift can't silently return garbage.
-    ///
-    /// Tauren Female is the load-bearing row: `modelScale` 1.25 with a 2.111 column. If the column
-    /// were authored post-`modelScale` the box would read 2.111/1.25 = 1.689, so this row alone
-    /// refutes the "divide the model scale out" reading (which is what vmangos's server-side
-    /// `Unit::UpdateModelData` does).
-    /// `CreatureModelData.Flags & 0x2` — the `$BTH` suppression (B233, decision 1149). The census
-    /// on the shipped table is 99 of 430 rows, and the split is semantic, not arbitrary: the
-    /// things with no breath to see. **Every player row passes** (they carry `0x4`), which is what
-    /// makes the flag safe to gate the reported case on.
     #[test]
     fn the_breathless_models_are_the_ones_with_no_breath() {
         let data = crate::wow_data_or_skip!();
@@ -1010,7 +778,6 @@ mod tests {
             "the shipped census: 99 of {} models suppress breath",
             cat.models.len()
         );
-        // Every playable race's own display breathes — the reported case.
         for (display_id, label) in [
             (49, "HumanMale"),
             (50, "HumanFemale"),
@@ -1020,7 +787,6 @@ mod tests {
         ] {
             assert!(cat.breathes(display_id), "{label} breathes");
         }
-        // …and the breathless: a skeleton, a water elemental, an infernal.
         for (display_id, label) in [
             (158, "Skeleton"),
             (110, "WaterElemental"),
@@ -1034,16 +800,7 @@ mod tests {
         );
     }
 
-    /// **The creature foley is dead data in 5875.** Every `CreatureModelData` row ships
-    /// `FoleyMaterialID = 0`, so `0x623610`'s branch resolves to silence for every NPC in the
-    /// game and the armor rustle is the player override's alone. Pinned as a test rather than a
-    /// comment because it is a *negative* that a future reader will otherwise re-derive by
-    /// wondering why NPCs are quiet — and because a shipped file that ever grows a nonzero here
-    /// should make this fail loudly rather than change the soundscape silently.
-    ///
-    /// The row alignment this rests on is checked in the same pass: field 11 (footstep shake)
-    /// is nonzero on exactly the 25 thumping-giant rows [`ModelRow`] documents, which would not
-    /// hold if the schema had slipped a column. Skips without client data.
+    /// Every shipped model has `FoleyMaterialID` 0; a data file that grows one fails here.
     #[test]
     fn no_shipped_model_carries_a_foley() {
         let data = crate::wow_data_or_skip!();
@@ -1062,8 +819,7 @@ mod tests {
             "shipped data grew a creature foley material: models {foleyed:?}"
         );
 
-        // The alignment guard: the neighbouring column is NOT uniformly zero, so a zero at
-        // field 10 is the data's own answer and not a schema that slid.
+        // Field 11 is not all zero, so the zero at field 10 is the data, not a slid schema.
         let shakers = cat
             .models
             .values()
@@ -1078,8 +834,7 @@ mod tests {
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_creature_catalog(&mut chain).expect("load creature catalog");
 
-        // (display id, label, the column's expected value). Display ids are the ChrRaces
-        // Male/FemaleDisplayId columns; Goblin shares one display across both sexes.
+        // (display id, label, expected column); ids from ChrRaces Male/FemaleDisplayId.
         let races: &[(u32, &str, f32)] = &[
             (49, "HumanMale", 2.031),
             (50, "HumanFemale", 1.913),
@@ -1122,7 +877,7 @@ mod tests {
             );
         }
 
-        // Not vacuous: the races must actually differ, or "one constant for everyone" would pass.
+        // Not vacuous: the races differ.
         let gnome = cat.collision_height(1564).unwrap();
         let nelf = cat.collision_height(55).unwrap();
         assert!(
@@ -1131,15 +886,8 @@ mod tests {
         );
     }
 
-    /// **Why the collision-prism FLOOR is invisible on shipped data** — and therefore why its
-    /// absence hid until a server override went looking for it (B311's triage, decision 1568).
-    ///
-    /// The real client's prism height is `CollisionHeight × max(SCALE_X, CreatureDisplayInfo.scale)`
-    /// (`0x60b312` → `0x617501`). vmangos folds `modelScale × displayScale` into `SCALE_X`, so the
-    /// floor can only bite where `modelScale < 1` would drag the product under the display column —
-    /// and **no shipped row scales below 1.0**. So on stock data `max` always picks `SCALE_X`, our
-    /// old `× SCALE_X` was bit-identical, and only a `creature_template.display_scale` override or
-    /// a shrink aura can separate the two.
+    /// vmangos folds both scales into `SCALE_X`, so the prism's `max(SCALE_X, display scale)` floor
+    /// bites only where `modelScale < 1`, and no shipped row is below 1.
     #[test]
     fn no_shipped_model_scales_below_one_so_the_prism_floor_is_inert_at_rest() {
         let data = crate::wow_data_or_skip!();
@@ -1156,23 +904,16 @@ mod tests {
             under.is_empty(),
             "a sub-1 modelScale would make the floor bite at rest: {under:?}"
         );
-        // Not vacuous: the column is really read, and really varies.
+        // Not vacuous: the column is read, and varies.
         assert!(
             cat.models.values().any(|m| m.scale > 1.0),
             "some row scales above 1.0, or this is asserting on a zeroed column"
         );
     }
 
-    /// **The shapeshift divergence, pinned in numbers** (decision 1574). The reference derives the
-    /// collision prism from `UNIT_FIELD_NATIVEDISPLAYID`, so a druid in a form keeps the druid's
-    /// depth lines. This asserts the two readings really differ on shipped data, and by how much —
-    /// a doc claiming "up to 0.72 yd" is worth nothing if the DBC rows drift under it.
-    ///
-    /// `h = collisionHeight × max(SCALE_X, CreatureDisplayInfo.scale)` on the row named. Player
-    /// `SCALE_X` starts at `modelScale × CDI.scale` and a shapeshift multiplies it by the form's
-    /// own factor (vmangos `GetShapeshiftDisplayInfo`: 1.0 for bear/moonkin/tree, 0.80 for
-    /// cat/travel/aquatic) — both live-confirmed by decision 0695's own probe (tauren bear
-    /// `h = 2.083 × 1.35`, tauren cat `SCALE_X 1.35 → 1.08`).
+    /// The prism comes from `UNIT_FIELD_NATIVEDISPLAYID`, so a druid in form keeps the druid's
+    /// depth lines, where the form's row would move the swim line up to 0.72 yd. A form scales
+    /// `SCALE_X` by 1.0 or 0.80 (vmangos `GetShapeshiftDisplayInfo`).
     #[test]
     fn a_shapeshift_moves_the_collision_prism_and_the_native_row_is_what_stops_it() {
         let data = crate::wow_data_or_skip!();
@@ -1208,28 +949,22 @@ mod tests {
             "worst swim-line divergence is {worst} yd, the doc says 0.72"
         );
 
-        // The direction flips with the form, which is why this can't be waved off as a constant
-        // offset: a night elf cat swims too EARLY, a tauren moonkin far too LATE.
+        // The sign flips with the form, so this is no constant offset.
         assert!(h(892, 0.80) < h(55, 0.80), "NElf cat: form row is shorter");
         assert!(
             h(15375, 1.35) > h(59, 1.35),
             "Tauren moonkin: form row is taller"
         );
 
-        // 0695's own live probe, reproduced from the DBCs: tauren bear h = 2.083 × 1.35.
+        // The tauren bear value seen live: h = 2.083 × 1.35.
         assert!(
             (h(2289, 1.35) - 2.083 * 1.35).abs() < 5e-3,
             "tauren bear form-derived h should reproduce 0695's observed 2.812"
         );
     }
 
-    /// **The Shore Strider, pinned** (B311, decision 1568). The reported giant's own chain and
-    /// numbers, recorded so nobody re-suspects the height: display 4945 → `CreatureModelData` 35,
-    /// `Creature\SeaGiant\SeaGiant.mdx`, column 2.083 over a display scale of 1.75 and a
-    /// `modelScale` of 1.0. Its prism is `2.083 × 1.75 = 3.645` yd under **both** the old
-    /// `× SCALE_X` reading and the corrected `× max(SCALE_X, displayScale)` — identical to the
-    /// float — so the height was never why it glided. The cause was the missing
-    /// `UNIT_FIELD_FLAGS` enter gate; this row is the control that says so.
+    /// The Shore Strider (display 4945, model 35): column 2.083 × display scale 1.75 = 3.645 yd
+    /// with or without the floor, since its `modelScale` is 1.0.
     #[test]
     fn the_shore_strider_prism_is_the_same_under_both_readings() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/dbc.rs b/crates/benilla-formats/src/dbc.rs
index 7362e3e9..5bc3b76a 100644
--- a/crates/benilla-formats/src/dbc.rs
+++ b/crates/benilla-formats/src/dbc.rs
@@ -1,8 +1,5 @@
-//! Small shared helpers for our typed DBC catalog loaders (creatures, game objects).
-//!
-//! DBC files carry no column types, so each loader supplies a [`Schema`] (field count must match the
-//! file header) and reads fields by index. Layouts are verified clean-room against build 5875 (the
-//! file header's `fieldCount × 4 == recordSize`, cross-checked with wowdev.wiki).
+//! Shared helpers for the typed DBC loaders. A DBC carries no column types, so each loader supplies
+//! a [`Schema`] whose field count must match the file header, and reads fields by index.
 
 use std::collections::HashMap;
 use std::io::Cursor;
@@ -12,7 +9,7 @@ use benilla_dbc::{DbcParser, FieldType, Record, RecordSet, Schema, SchemaField,
 
 use crate::Chain;
 
-/// Parse a DBC's bytes with `schema` into an owned record set (`what` names it for error messages).
+/// Parse a DBC with `schema`; `what` names the file in errors.
 pub(crate) fn parse(bytes: &[u8], schema: Schema, what: &str) -> Result<RecordSet> {
     let parser = DbcParser::parse(&mut Cursor::new(bytes))
         .map_err(|e| anyhow!("parsing {what} header: {e}"))?;
@@ -24,7 +21,7 @@ pub(crate) fn parse(bytes: &[u8], schema: Schema, what: &str) -> Result<RecordSe
         .map_err(|e| anyhow!("parsing {what} records: {e}"))
 }
 
-/// An unsigned field (accepts the int variants).
+/// An unsigned field, from either int variant: the schema tag only picks the decoding.
 pub(crate) fn u32_at(r: &Record, i: usize) -> Option<u32> {
     match r.get_value(i)? {
         Value::UInt32(v) => Some(*v),
@@ -33,7 +30,6 @@ pub(crate) fn u32_at(r: &Record, i: usize) -> Option<u32> {
     }
 }
 
-/// A float field.
 pub(crate) fn f32_at(r: &Record, i: usize) -> Option<f32> {
     match r.get_value(i)? {
         Value::Float32(v) => Some(*v),
@@ -41,9 +37,7 @@ pub(crate) fn f32_at(r: &Record, i: usize) -> Option<f32> {
     }
 }
 
-/// A signed field (accepts either int variant, mirroring [`u32_at`]'s leniency: the schema tag
-/// just picks how the parser decodes the same 4 raw bytes, so a column read as `UInt32` still
-/// round-trips through here bit-for-bit).
+/// A signed field; either int variant reads, bit for bit.
 pub(crate) fn i32_at(r: &Record, i: usize) -> Option<i32> {
     match r.get_value(i)? {
         Value::Int32(v) => Some(*v),
@@ -52,7 +46,7 @@ pub(crate) fn i32_at(r: &Record, i: usize) -> Option<i32> {
     }
 }
 
-/// A non-empty string field, resolved through the record set's string block.
+/// A string field from the string block; an empty string reads as `None`.
 pub(crate) fn str_at(rs: &RecordSet, r: &Record, i: usize) -> Option<String> {
     match r.get_value(i)? {
         Value::StringRef(StringRef(off)) => {
@@ -63,10 +57,7 @@ pub(crate) fn str_at(rs: &RecordSet, r: &Record, i: usize) -> Option<String> {
     }
 }
 
-/// `SpellIcon.dbc`: id → texture path (`Interface\Icons\…`, extensionless). 1033 records × 2
-/// fields (`ID(0)`, `TextureFilename(1, str)`) — verified against build 5875 (`spells.rs`'s own
-/// module doc). Shared by [`crate::spells`] (the action-bar catalog) and [`crate::skill_lines`]
-/// (a skill line's own tab icon) — one load, not two, since both just want id → path.
+/// `SpellIcon.dbc`: id → extensionless texture path (`Interface\Icons\…`).
 pub(crate) fn load_spell_icon_map(chain: &mut Chain) -> Result<HashMap<u32, String>> {
     let bytes = chain
         .read_file("DBFilesClient\\SpellIcon.dbc")
@@ -84,10 +75,8 @@ pub(crate) fn load_spell_icon_map(chain: &mut Chain) -> Result<HashMap<u32, Stri
     Ok(icons)
 }
 
-/// A minimal `ID(0) … Name(name_col) …` schema of `cols` u32-wide columns — the shape every
-/// "id → localized name" DBC has, since a string column is itself one u32 offset into the string
-/// block. Enough for the id→name reads; the loc block's other 7 slots and its flag mask stay
-/// anonymous `cN` columns.
+/// An id → name schema of `cols` four-byte columns (a string column is one offset); the other
+/// locale slots and the locale flag mask stay anonymous `cN` columns.
 pub(crate) fn id_name_schema(what: &str, name_col: usize, cols: usize) -> Schema {
     let mut s = Schema::new(what);
     for i in 0..cols {
@@ -100,9 +89,7 @@ pub(crate) fn id_name_schema(what: &str, name_col: usize, cols: usize) -> Schema
     s
 }
 
-/// Read an `ID → name` DBC through the patch chain into a map, skipping rows whose name is empty.
-/// Shared by every such table ([`crate::quest_headers`]'s AreaTable/QuestSort,
-/// [`crate::quest_info`]'s QuestInfo) — the layout differences are the two column numbers.
+/// Read an id → name DBC into a map, skipping rows whose name is empty (a hole, not a name).
 pub(crate) fn load_id_name_table(
     chain: &mut Chain,
     file: &str,
@@ -116,8 +103,6 @@ pub(crate) fn load_id_name_table(
     let rs = parse(&bytes, id_name_schema(what, name_col, cols), what)?;
     let mut out = HashMap::with_capacity(rs.records().len());
     for r in rs.records() {
-        // `str_at` already drops an empty string — a row whose name slot points at the string
-        // block's leading NUL is a hole, not a name.
         if let (Some(id), Some(name)) = (u32_at(r, 0), str_at(&rs, r, name_col)) {
             out.insert(id, name);
         }
diff --git a/crates/benilla-formats/src/death_thud.rs b/crates/benilla-formats/src/death_thud.rs
index 4dc6caf4..cfd25238 100644
--- a/crates/benilla-formats/src/death_thud.rs
+++ b/crates/benilla-formats/src/death_thud.rs
@@ -1,36 +1,9 @@
-//! The **death thud** — the body-fall impact a corpse makes as it lands, fired on the `$DTH`
-//! animation event (`0x6236e0`, the sibling of the same event's camera shake `0x625c30`).
-//!
-//! It rides the **same terrain chain the footsteps do** ([`crate::FootstepCatalog`]) — the
-//! surface under the unit → `TerrainType` → `TerrainType.SoundID` — and joins it against the
-//! creature's **size class** rather than its footstep class:
-//!
-//! ```text
-//! (CreatureDisplayInfo.SizeClass ?? CreatureModelData.SizeClass) × TerrainType.SoundID
-//!     → DeathThudLookups → SoundEntries (land | water)
-//! ```
-//!
-//! Layouts — VERIFIED against build 5875 (headers + row decodes, 2026-09-02):
-//! - `DeathThudLookups` **45 × 5 × 20 B**: `ID, SizeClass, TerrainTypeSoundID, SoundEntryID,
-//!   SoundEntryIDWater`.
-//! - `TerrainTypeSounds` **9 × 1 × 4 B**: a bare id enum, `1..=9`, and nothing else — the axis
-//!   `TerrainType.SoundID` and `FootstepTerrainLookup.TerrainSoundID` are both keyed on. It is
-//!   parsed for its **domain**: the reference bakes this table into a per-size-class array
-//!   dimensioned by it and bounds-checks `terrainSoundId >= count` before the lookup
-//!   (`0x623771`), and the census wants the empty columns as much as the full ones.
-//!
-//! **The five size classes are the five audible sizes**, and their kits name themselves:
-//! `0 Small · 1 Medium · 2 Large · 3 Giant · 4 Colossal` (`DeathThudSmallDirt` … through
-//! `DeathThudColossalWood`, all in `Sound\Effects\DeathImpacts`, one file each). So this is
-//! **not** a big-creature-only effect the way the camera shake is — every creature that carries a
-//! `$DTH` key thuds, and only the *sample* scales with the body. The water column is coarser: four
-//! kits (`DeathThudWaterSmall/Medium/Giant/Colossal`, `…\DeathImpacts\InWater`) shared across the
-//! whole terrain axis, since a splash does not care what is under the water.
-//!
-//! Only five of the nine terrain sounds carry the full class sweep (Dirt 1, Stone 3, Snow 4,
-//! Wood 5, Grass 6); the rest (Metallic 2, Leaves 7, Sand 8, Soggy 9) were filled in later against
-//! the *same* 25 kits — Metallic borrows Stone, Leaves borrows Dirt — and those rows carry a
-//! **water column of 0**, which is silence and not a fallback to land (see [`DeathThudCatalog::kit`]).
+//! The death thud a corpse makes as it lands, fired on the `$DTH` animation event (`0x6236e0`,
+//! beside the same event's camera shake `0x625c30`). `DeathThudLookups.dbc` joins the creature's
+//! size class (0 Small to 4 Colossal; the display's, else the model's) with the footsteps' terrain
+//! sound to a land and a water `SoundEntries` kit, so every creature with a `$DTH` key thuds.
+//! `TerrainTypeSounds.dbc` is read for its id domain, `1..=9`, which the reference sizes its baked
+//! array by and bounds-checks against (`0x623771`).
 
 use std::collections::{BTreeSet, HashMap};
 
@@ -44,37 +17,32 @@ use crate::dbc::{parse, u32_at};
 pub struct DeathThudCatalog {
     /// `(SizeClass, TerrainTypeSoundID)` → `(land kit, water kit)`.
     lookup: HashMap<(u32, u32), (u32, u32)>,
-    /// Every `TerrainTypeSounds.dbc` id, ascending — the lookup's terrain axis in full, including
-    /// the ids no `DeathThudLookups` row names.
+    /// Every `TerrainTypeSounds.dbc` id, including those no `DeathThudLookups` row names.
     terrain_sounds: BTreeSet<u32>,
 }
 
 impl DeathThudCatalog {
-    /// The `(land, water)` `SoundEntries` kits for a size class landing on a terrain-sound class.
-    /// `None` when the pair has no row — the reference's own answer for an out-of-domain index,
-    /// and silence.
+    /// The `(land, water)` `SoundEntries` kits for a size class landing on a terrain sound; a
+    /// pair with no row is silent, as in the reference.
     pub fn resolve(&self, size_class: u32, terrain_sound: u32) -> Option<(u32, u32)> {
         self.lookup.get(&(size_class, terrain_sound)).copied()
     }
 
-    /// The one kit that actually plays: the water column when the corpse is in liquid, the land
-    /// column otherwise. **A zero is silence, never a fallback to the other column** — the
-    /// reference plays whatever dword it read, and `SoundEntries` has no row 0, so the 18 rows
-    /// whose water column is 0 are simply mute in water.
+    /// The kit that plays, water in liquid and land otherwise. A `0` is silence, never the other
+    /// column: the reference plays the dword it read, and `SoundEntries` has no row 0.
     pub fn kit(&self, size_class: u32, terrain_sound: u32, in_water: bool) -> Option<u32> {
         let (land, water) = self.resolve(size_class, terrain_sound)?;
         let kit = if in_water { water } else { land };
         (kit != 0).then_some(kit)
     }
 
-    /// Every `TerrainTypeSounds` id, ascending — the census's column headings.
+    /// Every `TerrainTypeSounds` id, ascending.
     pub fn terrain_sounds(&self) -> impl Iterator<Item = u32> + '_ {
         self.terrain_sounds.iter().copied()
     }
 
-    /// Every size class a `DeathThudLookups` row names, ascending — the census's rows. The
-    /// shipped data is exactly `0..=4`, which is also why the reference's `sizeClass >= 5` gate
-    /// (`0x623744`) never fires on it.
+    /// Every size class a row names, ascending: `0..=4` in 5875, so the reference's
+    /// `sizeClass >= 5` gate (`0x623744`) never fires.
     pub fn size_classes(&self) -> BTreeSet<u32> {
         self.lookup.keys().map(|(sc, _)| *sc).collect()
     }
@@ -137,9 +105,7 @@ pub fn load_death_thud_catalog(chain: &mut Chain) -> Result<DeathThudCatalog> {
 mod tests {
     use super::*;
 
-    /// The shipped 5875 tables, decoded: the full 45-row join, the 9-id terrain domain, the five
-    /// size classes, and the two spot-checks that pin the column order (a swapped SizeClass /
-    /// TerrainTypeSoundID pair would still load, and would still be 45 rows).
+    /// The 5875 tables; the spot rows pin the column order, as a swapped pair still counts 45.
     #[test]
     fn real_death_thud_chain_resolves() {
         let data = crate::wow_data_or_skip!();
@@ -154,16 +120,13 @@ mod tests {
         );
         assert_eq!(cat.size_classes(), (0..=4).collect(), "Small..Colossal");
 
-        // Size class 0 (Small) on terrain sound 1 (Dirt) → `DeathThudSmallDirt` 907 /
-        // `DeathThudWaterSmall` 1266. Size class 4 (Colossal) on 6 (Grass) →
-        // `DeathThudColossalGrass` 928 / `DeathThudWaterColossal` 1269.
+        // Small on Dirt (`DeathThudSmallDirt`), Colossal on Grass (`DeathThudColossalGrass`).
         assert_eq!(cat.resolve(0, 1), Some((907, 1266)));
         assert_eq!(cat.resolve(4, 6), Some((928, 1269)));
         assert_eq!(cat.kit(4, 6, false), Some(928));
         assert_eq!(cat.kit(4, 6, true), Some(1269));
 
-        // The later-filled rows: Metallic (2) borrows the Stone kits, and its water column is 0 —
-        // silence in water, NOT a fall back to the land kit.
+        // Metallic (2) borrows the Stone kits and has no water kit: silent in water.
         assert_eq!(
             cat.resolve(0, 2),
             Some((910, 0)),
@@ -172,15 +135,13 @@ mod tests {
         assert_eq!(cat.kit(0, 2, true), None, "and nothing in water");
         assert_eq!(cat.kit(0, 2, false), Some(910));
 
-        // Out of domain both ways: terrain sound 0 is `TerrainType "None"`'s SoundID and is not a
-        // TerrainTypeSounds row at all; size class 5 is past the table.
+        // Terrain sound 0 (`TerrainType` "None") and size class 5 have no rows.
         assert_eq!(cat.resolve(0, 0), None);
         assert_eq!(cat.resolve(5, 1), None);
     }
 
-    /// Every terrain-sound id a `TerrainType` row names is a real `TerrainTypeSounds` row (or the
-    /// `0` of `"None"`), and every `DeathThudLookups` terrain axis value is one too — the join the
-    /// reference does by array index, checked as data.
+    /// The reference joins these tables by array index, so every terrain sound a `TerrainType` or
+    /// `DeathThudLookups` row names must be a `TerrainTypeSounds` row, or `0`.
     #[test]
     fn the_terrain_axis_agrees_across_the_three_tables() {
         let data = crate::wow_data_or_skip!();
@@ -195,8 +156,8 @@ mod tests {
                 "DeathThudLookups names terrain sound {terrain_sound}, which TerrainTypeSounds lacks"
             );
         }
-        // `TerrainType 10 "None"` is the unauthored default and its SoundID is 0 — not a row, and
-        // the reason a building's floor with no material makes no thud.
+        // `TerrainType` 10, "None", is the unauthored default: SoundID 0, so a floor with no
+        // material makes no thud.
         for terrain in 0..=10 {
             let sound = steps
                 .sound_class_of(terrain)
diff --git a/crates/benilla-formats/src/durability.rs b/crates/benilla-formats/src/durability.rs
index f7e2d82c..802fae26 100644
--- a/crates/benilla-formats/src/durability.rs
+++ b/crates/benilla-formats/src/durability.rs
@@ -1,24 +1,8 @@
-//! `DurabilityCosts.dbc` + `DurabilityQualities.dbc` — the client-side repair-cost tables.
-//!
-//! The 5875 client computes the *displayed* repair price itself (`0x5da330`, wrapped by
-//! `0x4faf30` — §5-verified in wow-re `system/ui/scratch/repair-machinery.md`):
-//!
-//! ```text
-//! perItem = round_nearest_even( max(1, round_half_away(
-//!               (maxDurability − durability)
-//!                 · DurabilityQualities[2·Quality + 1].mult   (float)
-//!                 · DurabilityCosts[ItemLevel].column         (int)  ))
-//!             · (1.0 − vendorReputationDiscount) )
-//! ```
-//!
-//! The `DurabilityCosts` column is picked by item class/subclass: WEAPON (class 2) reads the 21
-//! weapon columns (fields 1–21, byte `0x04 + subclass·4`), ARMOR (class 4) the 8 armor columns
-//! (fields 22–29, byte `0x58 + subclass·4`). Anything else costs nothing (never has durability).
-//!
-//! ⚠ The client's `2·Quality + 1` quality-row key differs from vmangos's `(Quality+1)·2` — the
-//! server may *charge* a different amount than the client *displays* (flagged INFERRED-boundary
-//! in the wow-re note; a live A/B at repair bring-up settles whether the DBC rows make them
-//! equivalent). We implement the client's verified key — benilla displays what 5875 displays.
+//! `DurabilityCosts.dbc` and `DurabilityQuality.dbc`, behind the repair price the reference
+//! computes itself (`0x5da330`, wrapped by `0x4faf30`): points lost × the quality row
+//! `2·Quality + 1` × the item level's weapon or armor column by subclass, rounded half away from
+//! zero to at least 1, then × `(1 - discount)` rounded half to even. vmangos keys the quality row
+//! `(Quality + 1)·2` (`Player.cpp:4996`), so its charge may differ from the price shown.
 
 use std::collections::HashMap;
 
@@ -33,16 +17,14 @@ const DURABILITY_QUALITIES: &str = "DBFilesClient\\DurabilityQuality.dbc";
 
 /// The two repair tables, id-keyed.
 pub struct DurabilityTables {
-    /// Row id (= item level) → the 29 per-point cost columns (21 weapon, then 8 armor).
+    /// Item level → the 29 per-point cost columns (21 weapon, then 8 armor).
     costs: HashMap<u32, Vec<u32>>,
     /// Row id → the quality multiplier (the client keys this with `2·Quality + 1`).
     qualities: HashMap<u32, f32>,
 }
 
 impl DurabilityTables {
-    /// The per-point integer cost column for an item's class/subclass at `item_level`, or `None`
-    /// when the item can't be repaired (not a weapon/armor, subclass out of the column range, or
-    /// the level row is missing).
+    /// The per-point cost for a class and subclass at `item_level`, `None` when unrepairable.
     fn column(&self, item_level: u32, class: u32, subclass: u32) -> Option<u32> {
         let row = self.costs.get(&item_level)?;
         let idx = match class {
@@ -53,10 +35,7 @@ impl DurabilityTables {
         row.get(idx).copied()
     }
 
-    /// The displayed repair cost for one item, in copper — the client's exact arithmetic (see the
-    /// module doc). `points_lost` = max − current durability; 0 lost (or an unrepairable item)
-    /// costs 0. `discount` is the vendor reputation discount (0.0 until benilla models
-    /// reputation), applied with the client's final round-to-nearest-even.
+    /// The displayed repair cost of one item in copper, after the vendor's reputation `discount`.
     pub fn repair_cost(
         &self,
         points_lost: u32,
@@ -76,14 +55,12 @@ impl DurabilityTables {
             return 0;
         };
         let base = f64::from(points_lost) * f64::from(mult) * f64::from(col);
-        // round_half_away for a positive value = floor(x + 0.5) (the client's ±0.5 + _ftol),
-        // then the max(1, …) floor.
+        // Half away from zero, as the reference's ±0.5 then `_ftol`, then at least 1.
         let per = ((base + 0.5).floor() as i64).max(1);
-        // The reputation-discount multiply ends in round-to-nearest-even.
+        // The discount multiply rounds half to even.
         let discounted = per as f64 * f64::from(1.0 - discount);
         let f = discounted.floor();
         let frac = discounted - f;
-        // Exact .5 goes to the even neighbour; anything else to the nearer.
         let up = frac > 0.5 || (frac == 0.5 && (f as i64) % 2 != 0);
         let rounded = if up { f + 1.0 } else { f };
         rounded.max(0.0) as u32
@@ -154,16 +131,13 @@ mod tests {
     #[test]
     fn per_item_cost_is_the_clients_arithmetic() {
         let t = tables();
-        // 10 points lost on a common (q1) sword at level 23: 10 · 0.6 · 4 = 24.
         assert_eq!(t.repair_cost(10, 23, 1, 2, 7, 0.0), 24);
-        // Mail gloves, 7 points: 7 · 0.6 · 2 = 8.4 → round-half-away → 8.
+        // Mail gloves, 7 points: 7 · 0.6 · 2 = 8.4, rounded to 8.
         assert_eq!(t.repair_cost(7, 23, 1, 4, 3, 0.0), 8);
-        // The max(1, …) floor: 1 point · 0.6 · … → 2.4 rounds to 2; a fractional sub-1 base
-        // still charges 1 (1 point on the 2/point mail with a tiny mult).
+        // A base under 1 still charges 1: 1 · 0.1 · 2 = 0.2.
         let mut t2 = tables();
         t2.qualities.insert(3, 0.1);
         assert_eq!(t2.repair_cost(1, 23, 1, 4, 3, 0.0), 1, "min 1 copper");
-        // Undamaged or unrepairable: free.
         assert_eq!(t.repair_cost(0, 23, 1, 2, 7, 0.0), 0);
         assert_eq!(t.repair_cost(10, 23, 1, 15, 0, 0.0), 0, "not weapon/armor");
         assert_eq!(t.repair_cost(10, 99, 1, 2, 7, 0.0), 0, "no level row");
@@ -176,8 +150,7 @@ mod tests {
         let mut row = vec![0u32; 29];
         row[7] = 1; // 1 copper/point so points == the pre-discount price
         t.costs.insert(23, row);
-        // A 50% discount (exactly representable): 41 → 20.5, the tie rounds to EVEN 20;
-        // 43 → 21.5 → 22; 42 → 21.0, no tie.
+        // Half off: 20.5 rounds to 20 and 21.5 to 22; 21.0 is no tie.
         assert_eq!(t.repair_cost(41, 23, 1, 2, 7, 0.5), 20);
         assert_eq!(t.repair_cost(43, 23, 1, 2, 7, 0.5), 22);
         assert_eq!(t.repair_cost(42, 23, 1, 2, 7, 0.5), 21);
diff --git a/crates/benilla-formats/src/elevators.rs b/crates/benilla-formats/src/elevators.rs
index 85098c7d..00e65ed6 100644
--- a/crates/benilla-formats/src/elevators.rs
+++ b/crates/benilla-formats/src/elevators.rs
@@ -1,24 +1,11 @@
-//! `TransportAnimation.dbc` — the type-11 TRANSPORT (elevator/lift/tram) keyframe paths, and the
-//! client's own cycle evaluator. Pure math, no Bevy, **WoW coordinates throughout**.
-//!
-//! A type-11 GameObject never streams a position: the server sends one anchor (the create
-//! movement block's `UPDATE_FLAG_TRANSPORT` u32, its `time-since-GO-create % period` clock) and
-//! the client animates the car itself — `target = (anchor + local_elapsed) % period`, bracket the
-//! two keyframes around `target`, lerp their **local offsets**, rotate the offset by the spawn's
-//! `GAMEOBJECT_ROTATION` quaternion, and add the stationary spawn position. The mechanism is
-//! byte-verified in `wow-5875-re` (`gameobject_path_eval` `0x5f6280` + the type-11 tick
-//! `0x5f5f10`, `system/object-layer/object-layer.md` §RF-0051 / `scratch/w2c1.md` §Q2-Q3;
-//! transcribed bit-exact in `crates/object-layer/src/gameobject.rs`); vmangos's
-//! `ElevatorTransport::Update` (`Transport.cpp:396-437`) is the same math on the server side,
-//! which is what keeps the two in sync. This module implements the *mechanism* idiomatically
-//! (f32, binary-search bracket); the x87 spill-pattern fidelity lives in wow-re.
-//!
-//! **7 fields:** `ID(0), TransportID(1), TimeIndex(2), PosX(3), PosY(4), PosZ(5), SequenceID(6)`
-//! — `TransportID` is the **gameobject_template entry** (not a display or path id), `TimeIndex`
-//! is cumulative ms, and the last frame's `TimeIndex` IS the cycle period (`0x5f6280` reads
-//! `segments[count-1].time` as its modulus; vmangos `TotalTime` likewise). `SequenceID` names the
-//! car M2's animation per span (162 moving / 164 stationary on the live rows) — not consumed
-//! here (deferred polish; the car still renders its idle).
+//! `TransportAnimation.dbc`, the keyframe paths of type-11 transports (elevators), and the
+//! reference's cycle evaluator over them, in WoW coordinates. The server sends one anchor, the
+//! create block's `UPDATE_FLAG_TRANSPORT` clock (time since creation, modulo the period), and the
+//! client animates the car: bracket the keyframes around `(anchor + elapsed) % period`, lerp their
+//! offsets, rotate by the spawn's `GAMEOBJECT_ROTATION` and add the spawn position (`0x5f6280`,
+//! ticked by `0x5f5f10`), as vmangos's `ElevatorTransport::Update` does (`Transport.cpp:396-435`).
+//! `TransportID` is the `gameobject_template` entry; `SequenceID`, the car's animation per span, is
+//! not read.
 
 use std::collections::HashMap;
 
@@ -30,29 +17,27 @@ use crate::Chain;
 
 const TRANSPORT_ANIMATION: &str = "DBFilesClient\\TransportAnimation.dbc";
 
-/// One `TransportAnimation.dbc` row — a keyframe on a type-11 transport's authored local path.
+/// One `TransportAnimation.dbc` row, a keyframe on a type-11 transport's local path.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ElevatorKeyframe {
-    /// Cumulative cycle time, ms. The path's last frame's `time_ms` is the cycle period.
+    /// Cumulative cycle time in ms; the last frame's is the period.
     pub time_ms: u32,
-    /// Local offset from the spawn point (WoW axes), **before** the spawn-rotation is applied.
+    /// Offset from the spawn point in WoW axes, before the spawn rotation.
     pub pos: [f32; 3],
 }
 
-/// `TransportAnimation.dbc` grouped by `TransportID` (= `gameobject_template` entry), each
-/// path's frames sorted by `TimeIndex`.
+/// `TransportAnimation.dbc` grouped by `TransportID`, each path's frames sorted by `TimeIndex`.
 pub struct ElevatorPaths {
     by_entry: HashMap<u32, Vec<ElevatorKeyframe>>,
 }
 
 impl ElevatorPaths {
-    /// A template entry's keyframes in time order, or `None` for a GO with no authored path.
-    /// A returned slice is never empty and always starts at `time_ms == 0` (load guarantees).
+    /// A template entry's keyframes in time order: at least two, the first at `time_ms == 0`.
     pub fn entry(&self, template_entry: u32) -> Option<&[ElevatorKeyframe]> {
         self.by_entry.get(&template_entry).map(Vec::as_slice)
     }
 
-    /// Number of distinct transport entries carrying a path.
+    /// The number of transport entries with a path.
     pub fn len(&self) -> usize {
         self.by_entry.len()
     }
@@ -62,7 +47,6 @@ impl ElevatorPaths {
     }
 }
 
-/// 7 fields per the module doc.
 fn schema() -> Schema {
     let mut s = Schema::new("TransportAnimation");
     for name in ["ID", "TransportID", "TimeIndex"] {
@@ -75,10 +59,9 @@ fn schema() -> Schema {
     s
 }
 
-/// Read `TransportAnimation.dbc` off the patch chain into an [`ElevatorPaths`]. Paths that could
-/// not drive a cycle (fewer than 2 frames, a zero period, or a first frame not at `t=0`) are
-/// dropped with the same silence the client affords them — a GO whose entry isn't here simply
-/// renders frozen at its spawn point.
+/// Read `TransportAnimation.dbc` off the patch chain, silently dropping, as the reference does, a
+/// path that cannot drive a cycle (under 2 frames, a zero period, a first frame past 0); its GO
+/// stays at its spawn point.
 pub fn load_elevator_paths(chain: &mut Chain) -> Result<ElevatorPaths> {
     let bytes = chain
         .read_file(TRANSPORT_ANIMATION)
@@ -105,21 +88,16 @@ pub fn load_elevator_paths(chain: &mut Chain) -> Result<ElevatorPaths> {
     Ok(ElevatorPaths { by_entry })
 }
 
-/// The path's cycle period, ms — the last keyframe's cumulative time (`0x5f6280`'s modulus).
+/// The cycle period in ms, the last keyframe's time (`0x5f6280`'s modulus).
 pub fn elevator_period_ms(frames: &[ElevatorKeyframe]) -> u32 {
     frames.last().map_or(1, |f| f.time_ms).max(1)
 }
 
-/// The client's type-11 cycle evaluator (`gameobject_path_eval` `0x5f6280`, mechanism form):
-/// world position of the car at `cycle_ms ∈ [0, period)`, given the spawn's stationary position
-/// and its `GAMEOBJECT_ROTATION` quaternion `(x, y, z, w)`. Also reports whether the bracketing
-/// span is in motion (the dock/depart edge for consumers' instruments).
-///
-/// The rotation is a plain quaternion rotation of the local offset — the binary builds the
-/// standard 3×3 of `q` row-major and combines transposed, which IS `R(q)·d` (wow-re
-/// `gameobject.rs:106-137`). vmangos reproduces it as `(d * q)` + a y sign flip
-/// (`Transport.cpp:426-428` "magical sign flip but it works"); the two agree on every live 1.12
-/// row with `x = y = 0` offsets and on pure-yaw spawn quats — the tests pin one worked case.
+/// The reference's type-11 evaluator (`0x5f6280`): the car's world position at `cycle_ms`, from
+/// the spawn position and its `GAMEOBJECT_ROTATION` quaternion `(x, y, z, w)`, and whether the
+/// bracketing span moves. The offset turns by `R(q)`, as the reference's transposed 3×3 does;
+/// vmangos's `d * q` with a y sign flip (`Transport.cpp:425-426`) agrees on the 1.12 data's
+/// vertical paths and pure-yaw spawns.
 pub fn elevator_sample(
     frames: &[ElevatorKeyframe],
     spawn_pos: [f32; 3],
@@ -130,8 +108,7 @@ pub fn elevator_sample(
     let period = elevator_period_ms(frames);
     let target = cycle_ms % period;
 
-    // Bracket: the last frame with `time_ms <= target` and its successor. `partition_point` on
-    // the sorted times replaces the binary's ring-cursor scan (same bracket, stateless).
+    // The reference's bracket, found by search rather than its ring cursor.
     let hi = frames.partition_point(|f| f.time_ms <= target);
     let (prev, next) = (frames[hi - 1], frames[hi.min(frames.len() - 1)]);
 
@@ -157,7 +134,7 @@ pub fn elevator_sample(
     )
 }
 
-/// `R(q)·v` — rotate a vector by a unit quaternion `(x, y, z, w)`.
+/// `R(q)·v` for a unit quaternion `(x, y, z, w)`.
 fn rotate_by_quat(v: [f32; 3], q: [f32; 4]) -> [f32; 3] {
     let [x, y, z, w] = q;
     // t = 2·(q.xyz × v); v' = v + w·t + q.xyz × t
@@ -204,26 +181,22 @@ mod tests {
     fn dwell_then_lerp_then_wrap() {
         let f = frames();
         let base = [100.0, 200.0, 50.0];
-        // Dwell window: both bracketing frames at the same offset -> parked, not moving.
         let (p, moving) = elevator_sample(&f, base, IDENT, 2500);
         assert_eq!(p, base);
         assert!(!moving);
-        // Mid-descent: t=7500 is halfway through the 5000->10000 span -> z offset -5.
+        // 7500 is halfway through the 5000 to 10000 span: z offset -5.
         let (p, moving) = elevator_sample(&f, base, IDENT, 7500);
         assert_eq!(p, [100.0, 200.0, 45.0]);
         assert!(moving);
-        // The cycle wraps at period (30000): cycle 30000 IS cycle 0.
         let (p0, _) = elevator_sample(&f, base, IDENT, 0);
         let (pw, _) = elevator_sample(&f, base, IDENT, 30000);
         assert_eq!(p0, pw);
-        // Just before wrap: nearly back at the spawn offset.
         let (p, moving) = elevator_sample(&f, base, IDENT, 29999);
         assert!(moving);
         assert!((p[2] - 50.0).abs() < 0.01, "z = {}", p[2]);
     }
 
-    /// One worked rotation case: a pure-yaw spawn quat (the only kind on live 1.12 spawn rows)
-    /// turning a lateral offset. q = 90° about +Z: (x, y) -> (-y, x).
+    /// A 90° yaw (1.12 transport spawns only yaw) turns `(x, y)` into `(-y, x)`.
     #[test]
     fn spawn_yaw_rotates_the_local_offset() {
         let half = std::f32::consts::FRAC_PI_4; // 90°/2
@@ -245,22 +218,19 @@ mod tests {
         );
     }
 
-    /// The real 5875 table: the Mesa Elevator pair + the Undercity elevator prove layout and the
-    /// load guarantees (sorted, t0 = 0, period = last frame). Skips without client data.
+    /// The 5875 table: layout and load guarantees on three real paths.
     #[test]
     fn real_transport_animation_layout_sanity() {
         let data = crate::wow_data_or_skip!();
         let mut chain = Chain::open(&data).expect("open patch chain");
         let paths = load_elevator_paths(&mut chain).expect("load TransportAnimation.dbc");
-        // The two Thunder Bluff Mesa Elevator cars (gameobject_template 4170/4171) and the
-        // Undercity elevator (152614) — verified against the extracted table this session.
+        // Thunder Bluff's Mesa Elevator cars are templates 4170 and 4171, Undercity's 152614.
         let top = paths.entry(4170).expect("Mesa Elevator 4170");
         assert_eq!(elevator_period_ms(top), 30033);
         assert_eq!(top[0].time_ms, 0);
         assert_eq!(top[0].pos, [0.0, 0.0, 0.0]);
         assert!(top.windows(2).all(|w| w[0].time_ms <= w[1].time_ms));
-        // The car travels on z only — x/y are authoring noise at ~2e-6 yd (the rotation
-        // question is moot for pure-vertical paths). Full descent: 61.24 yd.
+        // The car moves on z only (x and y are ~2e-6 yd of noise), 61.24 yd down.
         assert!(top
             .iter()
             .all(|f| f.pos[0].abs() < 1e-3 && f.pos[1].abs() < 1e-3));
@@ -268,7 +238,6 @@ mod tests {
         let bottom = paths.entry(4171).expect("Mesa Elevator 4171");
         assert_eq!(elevator_period_ms(bottom), 30000);
         assert!(paths.entry(152614).is_some(), "Undercity elevator");
-        // A no-path entry answers None (999999 is no template).
         assert!(paths.entry(999_999).is_none());
     }
 }
diff --git a/crates/benilla-formats/src/emit_timing.rs b/crates/benilla-formats/src/emit_timing.rs
index 0b42b1ad..3d5ee483 100644
--- a/crates/benilla-formats/src/emit_timing.rs
+++ b/crates/benilla-formats/src/emit_timing.rs
@@ -1,50 +1,36 @@
-//! Per-sequence **particle emission timing** — the FN1 bake of the emitter's per-frame-sampled
-//! M2Tracks: spawn rate `+0xdc` + enabled gate `+0x1dc` ([`EmitTiming`]) and the other nine
-//! emission parameters ([`EmitParams`]), one loop per FILE sequence slot. Split from
-//! [`crate::particles`] (the raw record parse) because it is the *runtime sampling* face:
-//! decision 0641's material-alpha structure, one channel over.
+//! Particle emitter tracks sampled per sequence: the spawn rate (`+0xdc`) and enabled gate
+//! (`+0x1dc`) in [`EmitTiming`], the other nine parameters in [`EmitParams`], each baked one loop
+//! per file sequence slot by the reference's key-window kernel (`0x713d50`).
 
 use benilla_m2::M2ScalarTrack;
 
 use crate::models::{bake_track, ScalarAnim, SeqSlot};
 
-/// Per-sequence **emission timing**: the emitter's two per-frame-sampled M2Tracks — spawn rate
-/// (`+0xdc`) and the enabled gate (`+0x1dc`) — baked one loop per FILE sequence slot through the
-/// FN1 kernel ([`crate::models::bake_track`]), exactly the material-alpha structure of decision
-/// 0641 one channel over. The reference's emitter phase of `m2_animate` samples both through the
-/// **playing** sequence's key window every frame and forces the spawn rate to 0 while the gate is
-/// off (wow-re `part-emission-rate-animated.md` §2/§3, byte-verified `0x717d90`/`0x718f32`).
-///
-/// The clock law rides the **baked loop** ([`crate::models::KeyAnim::wrap`]), decided from the
-/// slot at bake time: a **looping** sequence wraps its band (`t mod period` — a windowed gate
-/// re-fires every pass), a **clamped** one parks at the band end and holds the tail value (never
-/// aliasing back to the band start), and a gseq-tagged track always wraps on its own free clock
-/// whatever the playing sequence does. Consumers resolve `seq` from whatever clock they run: a
-/// placed doodad passes `None` (slot 0 — its one-time arm), an effect its armed slot, a
-/// unit/GameObject its live playing sequence.
+/// The spawn rate and enabled gate per file sequence slot. The reference's animate kernel
+/// (`0x714260`) samples both through the playing sequence's key window every frame, and the rate
+/// is 0 while the gate is off (`0x717d90`, `0x718f32`). A looping slot wraps its band, a clamped
+/// one holds its tail, a gseq-tagged track runs on its own clock; `None` or an unknown `seq` is
+/// slot 0.
 #[derive(Debug, Clone, Default)]
 pub struct EmitTiming {
-    /// Baked rate loop per file slot; `None` = the track keys nothing there (spawn rate 0).
+    /// Per file slot; `None` where the track keys nothing (rate 0).
     rate: Vec<Option<ScalarAnim>>,
-    /// Baked gate per file slot (step, 0/1); `None` = no gate authored — the loader default is
-    /// ON (`0x710092`: `block+0x14c = 1` for every emitter).
+    /// Per file slot, stepped 0 or 1; `None` is on, the loader default (`0x710092` sets
+    /// `block+0x14c = 1`).
     enabled: Vec<Option<ScalarAnim>>,
-    /// Per file slot: sequence flags bit 0 CLEAR = the band loops. Carried for [`Self::idx`]'s
-    /// slot count and the dump instruments' view — the *sampling* clock is the baked loop's own.
+    /// Per file slot: the band loops when sequence flags bit 0 is clear.
     looping: Vec<bool>,
 }
 
 impl EmitTiming {
-    /// Bake both tracks against every file sequence slot; `gseq` is the global-sequence duration
-    /// table. Each slot carries its own loop flag, which becomes the baked loop's clock.
+    /// Bake both tracks per file sequence slot; `gseq` is the global-sequence duration table.
     pub(crate) fn bake(
         rate: &M2ScalarTrack,
         enabled: &M2ScalarTrack,
         slots: &[SeqSlot],
         gseq: &[u32],
     ) -> Self {
-        // Keep every baked shape, constants included — this channel has no static fallback path,
-        // so a held value must survive the bake (`|_| false` on both predicates).
+        // Keep every shape, constants included (`|_| false` twice): there is no static fallback.
         let per_slot = |t: &M2ScalarTrack| -> Vec<Option<ScalarAnim>> {
             slots
                 .iter()
@@ -58,8 +44,6 @@ impl EmitTiming {
         }
     }
 
-    /// Resolve a consumer's sequence to a file slot: out-of-range / unknown degrades to slot 0
-    /// (the doodad lane's one-time arm, and the old single-band behaviour).
     fn idx(&self, seq: Option<usize>) -> usize {
         match seq {
             Some(i) if i < self.looping.len() => i,
@@ -67,9 +51,8 @@ impl EmitTiming {
         }
     }
 
-    /// Is the gate ON, `elapsed` seconds into sequence slot `seq`? A slot with no baked gate is
-    /// ON (the loader default). `shared_now` is the world's shared elapsed seconds — a
-    /// gseq-tagged gate routes to it ([`crate::models::KeyAnim::clock`]).
+    /// Whether the gate is on `elapsed` seconds into slot `seq`; `shared_now`, the world clock in
+    /// seconds, drives a gseq-tagged gate.
     pub fn emitting(&self, seq: Option<usize>, elapsed: f32, shared_now: f64) -> bool {
         self.enabled
             .get(self.idx(seq))
@@ -77,9 +60,8 @@ impl EmitTiming {
             .is_none_or(|a| a.sample_or(a.clock(elapsed, shared_now), 1.0) > 0.5)
     }
 
-    /// The spawn rate (particles/sec), `elapsed` seconds into sequence slot `seq`. A slot with no
-    /// baked rate spawns nothing. Floored at 0 (a track tail may legitimately go negative).
-    /// `shared_now` routes a gseq-tagged rate loop to the shared world clock.
+    /// Particles per second `elapsed` seconds into slot `seq`, floored at 0 as a track tail can go
+    /// negative; `shared_now` drives a gseq-tagged rate.
     pub fn rate(&self, seq: Option<usize>, elapsed: f32, shared_now: f64) -> f32 {
         self.rate
             .get(self.idx(seq))
@@ -88,8 +70,7 @@ impl EmitTiming {
             .max(0.0)
     }
 
-    /// The rate track's peak over every slot — the "can this emitter ever contribute" spawn gate
-    /// (a burst emitter keys `0 → peak → 0`, so its first key is 0 but it absolutely emits).
+    /// The rate's peak over every slot, for the spawn cull: a burst emitter's first key is 0.
     pub fn peak_rate(&self) -> f32 {
         self.rate
             .iter()
@@ -98,24 +79,10 @@ impl EmitTiming {
             .fold(0.0, f32::max)
     }
 
-    /// The **burst this emitter actually fires** on sequence slot `seq`, as
-    /// `(seconds into the slot, particle count)` — or `None` when it never fires one.
-    ///
-    /// The reference's burst gate is `enabled != 0 && sampledRate > 0`, both sampled from the
-    /// same clock in the same frame, and it triggers on that predicate's **rising edge**, emitting
-    /// `ftol(rate)` particles (wow-re `part-emission-burst-flag.md` §1, `0x718ed2`–`0x718ef6`;
-    /// benilla's `particles::accumulate_emission` runs the same rule). Both tracks are STEP, so
-    /// this walks a 60 Hz grid over the slot's keyed span — the same resolution a running frame
-    /// gives it — and reports the first instant the predicate holds.
-    ///
-    /// **`None` is a real shipped shape, not a parse failure.** An emitter whose enabled track
-    /// falls to 0 on the very keyframe its rate track rises off 0 never emits anything: the two
-    /// conditions are never true together. `Spells\\Strike_Impact_Chest.m2`'s gold flare emitter
-    /// is exactly that, and reading its [`Self::peak_rate`] as a particle count overstates the
-    /// effect by 50 particles that neither client draws.
-    ///
-    /// A gseq-tagged track is sampled against `shared_now = 0` — this is a static dump/inspection
-    /// face, not a running clock.
+    /// The first burst on slot `seq` as `(seconds in, particle count)`, on a 60 Hz grid: the
+    /// reference fires `ftol(rate)` particles on the rising edge of `enabled != 0 && rate > 0`
+    /// (`0x718ed2`-`0x718ef6`). `None` is a shipped shape: `Spells\\Strike_Impact_Chest.m2`'s gold
+    /// flare turns its gate off on the key its rate rises.
     pub fn first_burst(&self, seq: Option<usize>) -> Option<(f32, f32)> {
         let i = self.idx(seq);
         let span = |o: &Option<ScalarAnim>| -> f32 {
@@ -139,8 +106,7 @@ impl EmitTiming {
         }
     }
 
-    /// `Some(rate)` when every slot bakes the same single-key rate — the overwhelmingly common
-    /// shape, and the dump instruments' quiet case.
+    /// `Some(rate)` when every slot bakes the same single-key rate, the common shape.
     pub fn constant_rate(&self) -> Option<f32> {
         let mut it = self.rate.iter();
         let first = it.next()?.as_ref()?;
@@ -149,9 +115,7 @@ impl EmitTiming {
             .then_some(v)
     }
 
-    /// Per-slot read view for the dump instruments: `(looping, rate keys, enabled keys)`, one per
-    /// file sequence slot (`None` = the track keys nothing in that slot). Times are seconds from
-    /// the slot's band start — the values the runtime actually samples, not the raw file keys.
+    /// `(looping, rate keys, enabled keys)` per file slot, in seconds from the band start.
     #[allow(clippy::type_complexity)] // a read-only tuple view for the dumps
     pub fn slot_views(&self) -> Vec<(bool, Option<&[(f32, f32)]>, Option<&[(f32, f32)]>)> {
         fn keys(list: &[Option<ScalarAnim>], i: usize) -> Option<&[(f32, f32)]> {
@@ -180,15 +144,10 @@ impl EmitTiming {
     }
 }
 
-/// One frame's sampled emitter **parameters** — the nine per-frame-sampled scalar M2Tracks of the
-/// emitter record (bases `+0x34..+0x130`, every one except the rate/enabled pair). The reference's
-/// `m2_animate` emitter phase samples ALL ten scalar tracks into the per-emitter animation block
-/// (`[model+0x3d0]`, stride 0x16c — wow-re `part-emission-rate-animated.md` §1, the rate channel
-/// byte-verified as the template) and pushes them onto the live emitter through its setters each
-/// frame. **These are NOT constants**: `Frost_Nova_area` ramps its emission-sphere radius
-/// 0.19 → 13.2 yd with the expanding ring, `ArcaneExplosion_Base` 0 → 7.2 yd with the growing
-/// dome — flatten either to `value[0]` and every birth lands at the centre (the "born way too
-/// close" bug this type exists to fix).
+/// One frame's sample of the emitter's nine parameter tracks (`+0x34..+0x130`, all but rate and
+/// gate). The reference samples them every frame into the emitter's animation block
+/// (`[model+0x3d0]`, stride 0x16c) as it does the rate (`0x71850d`), and they animate:
+/// `Frost_Nova_area`'s emission sphere grows from 0.19 to 13.2 yd.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct ParamsNow {
     /// Initial particle speed (yards/sec).
@@ -199,17 +158,16 @@ pub struct ParamsNow {
     pub vertical_range: f32,
     /// Azimuthal spread, radians (sphere: longitude range; spline: scatter jitter).
     pub horizontal_range: f32,
-    /// Downward acceleration (yards/sec²) — a live per-frame emitter field (the integrator reads
-    /// it every frame, `0x7b2680`), so it samples here rather than baking per particle.
+    /// Downward acceleration (yards/sec²), read live every frame by the integrator (`0x7b2680`).
     pub gravity: f32,
-    /// Particle lifetime (seconds). The reference passes the CURRENT value into each spawn
-    /// (`life_param`, the kernels' `ebp+0xc`), so a birth captures it for life.
+    /// Particle lifetime (seconds); a birth keeps the value current at its spawn (the spawn
+    /// kernels' `ebp+0xc`).
     pub lifespan: f32,
-    /// Plane: full x-extent (±½ rect); sphere: MIN radius; spline: tMin.
+    /// Plane: full x-extent (±½ rect); sphere: minimum radius; spline: tMin.
     pub area_length: f32,
-    /// Plane: full y-extent; sphere: MAX radius; spline: tMax.
+    /// Plane: full y-extent; sphere: maximum radius; spline: tMax.
     pub area_width: f32,
-    /// zSource — velocity pivot at `(0, 0, z)` (0 = unused).
+    /// zSource: velocity pivot at `(0, 0, z)`, 0 for none.
     pub z_source: f32,
 }
 
@@ -230,14 +188,11 @@ impl Default for ParamsNow {
     }
 }
 
-/// The nine emitter parameter tracks, baked one loop per FILE sequence slot — the exact
-/// bake/clock/sampling law of [`EmitTiming`]'s rate channel (byte-verified there), applied to its
-/// nine sibling tracks. Sample once per sim frame on the emitter's clock and feed births/kill/
-/// integration the result ([`ParamsNow`]).
+/// The nine parameter tracks, baked per file sequence slot under [`EmitTiming`]'s law; sampled
+/// once per frame on the emitter's clock.
 #[derive(Debug, Clone, Default)]
 pub struct EmitParams {
-    /// Per-channel, per-slot baked loops, in [`ParamsNow`] field order; `None` = keyless there
-    /// (the channel default stands).
+    /// Per channel in [`ParamsNow`] field order, per slot; `None` holds the channel default.
     channels: [Vec<Option<ScalarAnim>>; 9],
 }
 
@@ -254,9 +209,7 @@ impl EmitParams {
         }
     }
 
-    /// Sample every channel `elapsed` seconds into sequence slot `seq` (same slot resolution as
-    /// [`EmitTiming`]: out-of-range degrades to slot 0). `shared_now` routes gseq-tagged
-    /// channels to the shared world clock.
+    /// Every channel `elapsed` seconds into slot `seq`, resolved as [`EmitTiming`] resolves it.
     pub fn sample(&self, seq: Option<usize>, elapsed: f32, shared_now: f64) -> ParamsNow {
         let d = ParamsNow::default();
         let at = |i: usize, default: f32| -> f32 {
@@ -282,10 +235,8 @@ impl EmitParams {
         }
     }
 
-    /// The lifespan channel's peak over every slot — the spawn-cull gate (an animated lifespan
-    /// may open at 0; an emitter is dead only if it NEVER exceeds 0). A keyless channel reads
-    /// the loader default; a keyed one folds its own keys ONLY (folding from the default would
-    /// mask an authored sub-1.0 peak).
+    /// The lifespan's peak over every slot, for the spawn cull. A keyless channel is the loader
+    /// default; a keyed one folds only its keys, so an authored peak under 1.0 is not masked.
     pub fn peak_lifespan(&self) -> f32 {
         let mut keys = self.channels[5]
             .iter()
@@ -298,8 +249,7 @@ impl EmitParams {
         keys.fold(0.0, f32::max)
     }
 
-    /// Constant channels from one [`ParamsNow`] — the test/tool constructor, and the shape every
-    /// pre-track consumer had.
+    /// Constant channels from one [`ParamsNow`], for tests and tools.
     pub fn constant(now: ParamsNow) -> Self {
         let ch = |v: f32| {
             vec![Some(ScalarAnim {
@@ -325,9 +275,7 @@ impl EmitParams {
         }
     }
 
-    /// Per-channel dump view: `(name, per-slot keys)` — `None` = keyless in that slot. The dump
-    /// instruments print any channel whose keys actually move (the view that would have shown
-    /// Frost Nova's 0.19 → 13.2 yd radius ramp instead of hiding it behind `value[0]`).
+    /// `(name, per-slot keys)` per channel.
     #[allow(clippy::type_complexity)] // a read-only tuple view for the dumps, like `slot_views`
     pub fn channel_views(&self) -> [(&'static str, Vec<Option<&[(f32, f32)]>>); 9] {
         const NAMES: [&str; 9] = [
@@ -366,8 +314,6 @@ mod tests {
         }
     }
 
-    /// File sequence slots as `(band, loops)` — the loop flag is the slot's CLOCK, so these tests
-    /// spell it per slot rather than carry a parallel array beside the bands.
     fn slots(spec: &[((u32, u32), bool)]) -> Vec<SeqSlot> {
         spec.iter()
             .enumerate()
@@ -379,9 +325,6 @@ mod tests {
             .collect()
     }
 
-    /// The STEP rate law: a `{0:0, 67:30}` track is silent before its 67 ms key — the burst
-    /// fires AT the key, full-count — and holds 30 after (moved here from the runtime's
-    /// `accumulate_emission` tests when the sampling moved into the bake).
     #[test]
     fn step_rate_is_silent_before_its_key_and_holds_after() {
         let t = EmitTiming::bake(
@@ -400,8 +343,7 @@ mod tests {
         assert!(t.emitting(None, 0.5, 0.0), "no gate track = always on");
     }
 
-    /// The LINEAR ramp law (the BloodSpurt shape `0 → 100 → 0`, interp 1): mid-ramp pours the
-    /// interpolated rate, and the self-closing tail really falls back to 0.
+    /// BloodSpurt's linear `0, 100, 0` rate (interp 1).
     #[test]
     fn lerp_ramp_interpolates_and_self_closes() {
         let t = EmitTiming::bake(
@@ -421,10 +363,6 @@ mod tests {
         assert_eq!(t.rate(None, 0.500, 0.0), 0.0, "the ramp self-closes");
     }
 
-    /// The per-sequence window law — the B27 shape, synthesized: an enabled gate authored ON
-    /// inside a clamped one-shot clip (slot 0) whose window in the idle loop (slot 1) resolves
-    /// to OFF. The old seq-0-only rebase parked the clamped clock at its end value; the bake
-    /// must read OFF at idle, run slot 0's window, and HOLD (not wrap) slot 0's tail.
     #[test]
     fn idle_window_is_off_and_a_clamped_clip_holds_its_tail() {
         // Absolute timeline: clip A (one-shot) band 1000..2000, idle band 2333..2667.
@@ -444,13 +382,11 @@ mod tests {
             ]),
             &[],
         );
-        // Idle (slot 1): the collapsed window (1,1) resolves to keys[1] = OFF — at every time,
-        // wrap included.
+        // Idle (slot 1): the collapsed window (1,1) is keys[1], off at every time.
         assert!(!t.emitting(Some(1), 0.0, 0.0));
         assert!(!t.emitting(Some(1), 0.25, 0.0));
         assert!(!t.emitting(Some(1), 400.0, 0.0));
-        // The one-shot clip (slot 0): ON at its start, OFF from 333 ms — and the clamped clock
-        // HOLDS that tail at/after the band end instead of aliasing back to the ON start.
+        // The clip (slot 0): on, off from 333 ms, and held off past the band end.
         assert!(t.emitting(Some(0), 0.1, 0.0));
         assert!(!t.emitting(Some(0), 0.5, 0.0));
         assert!(
@@ -461,9 +397,8 @@ mod tests {
             !t.emitting(Some(0), 5.0, 0.0),
             "parked long past the end: still off"
         );
-        // The later clip (slot 2): its degenerate window is the ON key.
+        // The later clip (slot 2): its degenerate window is the on key.
         assert!(t.emitting(Some(2), 0.05, 0.0));
-        // Unknown/out-of-range degrades to slot 0 (the doodad law).
         assert!(t.emitting(None, 0.1, 0.0));
         assert!(!t.emitting(Some(9), 0.5, 0.0));
         // The rate is a whole-track constant: same in every slot.
@@ -471,10 +406,7 @@ mod tests {
         assert_eq!(t.peak_rate(), 20.0);
     }
 
-    /// The ANIMATED-parameter law — Frost Nova's authored shape: the emission-sphere radius
-    /// (areaLength = areaWidth) lerps 0.19 → 13.2 yd over 667 ms and holds, riding the ring
-    /// outward; lifespan ramps beside it. `value[0]` flattening (the bug this bakes away) reads
-    /// 0.19 for ever and births the whole mist at the caster's feet.
+    /// Frost Nova's authored shape: the sphere radius lerps 0.19 to 13.2 yd over 667 ms and holds.
     #[test]
     fn animated_area_ramp_samples_mid_flight() {
         let area = track(1, &[(0, 0.1944), (667, 13.1967), (867, 13.1967)], &[]);
@@ -498,12 +430,11 @@ mod tests {
         assert!((at(0.2).lifespan - 0.6127).abs() < 5e-3, "lifespan rides");
         assert_eq!(at(0.5).emission_speed, 0.0, "keyless channel: default");
         assert!((p.peak_lifespan() - 0.8008).abs() < 1e-4);
-        // The clamped one-shot parks at its tail, never aliasing back to the tight opening.
+        // The clamped clip holds its tail.
         assert!((at(5.0).area_length - 13.1967).abs() < 1e-3);
     }
 
-    /// A LOOPING slot wraps its band — a windowed gate re-fires every pass (the precast hold's
-    /// pulsing hand flash), where a clamped slot would have parked.
+    /// A windowed gate re-fires every pass, as the precast hold's pulsing hand flash does.
     #[test]
     fn a_looping_band_wraps_its_gate_window() {
         let gate = track(0, &[(0, 1.0), (200, 0.0)], &[]);
@@ -521,16 +452,9 @@ mod tests {
         );
     }
 
-    /// **The dead-slot-0 shape** — `BlastedLandsLightningbolt01.m2`'s emitter 2, synthesized
-    /// (decision 0760, bug B63). Two sequences, both anim id 0: a variation chain. Slot 0 keys a
-    /// single 0 — a flat silence for its whole band — while the strike itself, `0 → 30 → 0`, is
-    /// keyed only in slot 1, which the arm's frequency-weighted roll reaches ~5 % of the time.
-    ///
-    /// A consumer that PINS slot 0 therefore emits **nothing at all, for ever**, on every
-    /// placement: the emitter builds, pools and ticks, and never births a particle. That is what
-    /// the placed-doodad lane did until it started passing the slot its own arm actually rolled.
-    /// `peak_rate()` folding across all slots is why such an emitter survives the spawn cull — it
-    /// looks alive to the build and is dead to the clock. `partslotscan` counts 947 of these.
+    /// `BlastedLandsLightningbolt01.m2`'s emitter 2: two variations of anim 0, the strike keyed
+    /// only in slot 1, which the arm's weighted roll picks about 5% of the time. A consumer pinned
+    /// to slot 0 never emits, yet `peak_rate` keeps the emitter past the spawn cull.
     #[test]
     fn a_burst_keyed_only_in_a_later_variation_is_silent_in_slot_0() {
         // Absolute timeline: slot 0's band 0..1333, slot 1's band 1367..2667 (the real model's).
@@ -551,7 +475,7 @@ mod tests {
             &slots(&[((0, 1333), true), ((1367, 2667), true)]),
             &[],
         );
-        // Slot 0 — what the old pinned consumer sampled. Silent across its whole band.
+        // Slot 0 is silent across its whole band.
         for s in [0.0, 0.3, 0.6, 0.9, 1.2] {
             assert_eq!(
                 t.rate(Some(0), s, 0.0),
@@ -564,7 +488,7 @@ mod tests {
             0.0,
             "`None` degrades to slot 0 — also silent"
         );
-        // Slot 1 — what the arm actually rolled. The strike is here, and only here.
+        // Slot 1 carries the strike.
         assert_eq!(t.rate(Some(1), 0.0, 0.0), 0.0, "slot 1 opens closed");
         assert_eq!(
             t.rate(Some(1), 0.316, 0.0),
@@ -572,7 +496,7 @@ mod tests {
             "the burst fires mid-band"
         );
         assert_eq!(t.rate(Some(1), 0.5, 0.0), 0.0, "and self-closes");
-        // The trap that hid it: the build-time cull sees a live emitter either way.
+        // The build-time cull still sees a live emitter.
         assert_eq!(
             t.peak_rate(),
             30.0,
diff --git a/crates/benilla-formats/src/emote_text.rs b/crates/benilla-formats/src/emote_text.rs
index dc7a332a..2c4c906f 100644
--- a/crates/benilla-formats/src/emote_text.rs
+++ b/crates/benilla-formats/src/emote_text.rs
@@ -1,40 +1,10 @@
-//! `EmotesText.dbc` × `EmotesTextData.dbc` — the **sentence** an `SMSG_TEXT_EMOTE` becomes
-//! ("Bob waves at you." / "You wave." / "Bob waves at Jane."), decision 1274.
+//! `EmotesText.dbc` joined with `EmotesTextData.dbc`: the sentence an `SMSG_TEXT_EMOTE` becomes
+//! ("Bob waves at you."). [`crate::emotes`] owns the same table's command, animation and voice
+//! columns; this module owns its 16 `EmoteText[]` columns and the strings they point into.
 //!
-//! The sibling module [`crate::emotes`] owns the same `EmotesText.dbc`'s *other* half — the
-//! `/command` name, the anim id, the voice kits. This one owns its 16 **`EmoteText[]`** columns and
-//! the localized-string table they point into, because the two are consumed by different arcs
-//! (audio+animation vs the chat log) and only one of them needs `EmotesTextData.dbc` at all.
-//!
-//! The law below is the real client's sole sentence composer, **`0x49b200`** — wow-re
-//! `system/ui/scratch/text-emote-composition.md`, re-read at the bytes for this implementation
-//! (`objdump 0x49b200..0x49b47c`), which is where the byte addresses in the comments come from.
-//!
-//! # The composer, in three parts
-//!
-//! **1 · A 4-bit column selector.** `index = gender | context`, where `context` is built from three
-//! facts and the *order of the tests matters* (`0x49b2c3`-`0x49b316`):
-//!
-//! | bit | test | meaning |
-//! |---|---|---|
-//! | `2` (`0x49b2c8`) | performer guid == the active player's | **you are the performer** — and this *skips* the bit-0 test |
-//! | `1` (`0x49b2f3`) | the wire's target name == your own name | **you are the target** (only ever tested when you are not the performer) |
-//! | `4` (`0x49b311`) | the wire's target name is empty | **untargeted** |
-//! | `8` (`0x49b31c`) | the performer's `NameCache` record `+0x13c == 1` (Female) | performer **gender** |
-//!
-//! Reachable columns are `{0,1,2,4,6} | gender` — 10 of the 16; 3/5/7/11/13/15 cannot be selected
-//! (bit 0 and bit 2 are mutually exclusive, and bit 1 skips bit 0's test). WAVE (id 101) in the
-//! shipped table: col0 "%s waves at %s.", col1 "%s waves at you.", col2 "You wave at %s.",
-//! col4 "%s waves.", col6 "You wave.", every other column 0.
-//!
-//! **2 · A four-rung fallback ladder** when the picked column has no non-empty string for the
-//! locale (`0x49b332`, `0x49b35e`, `0x49b38a`, `0x49b3c5`): `gender|ctx` → `ctx` → `gender|ctx'` →
-//! `ctx'`, where `ctx' = (ctx & !1) | 4` ("drop target-self, force untargeted"). All four empty ⇒
-//! **no chat line at all** (`0x49b4bd`), and the emote is anim + voice only.
-//!
-//! **3 · Four `SStrPrintf` sites**, picked by (performer-is-other) × (target-is-other), always
-//! performer-first (`0x49b3fa`-`0x49b479`). See [`EmoteLine`] for the self-target edge that falls
-//! out of the test order.
+//! The composer is the reference's `0x49b200`: a 4-bit column selector, a four-rung fallback when
+//! the column has no string for the locale, then one of four `SStrPrintf` sites, performer first.
+//! All four rungs empty means no chat line at all; the emote is then only an animation and a voice.
 
 use std::collections::HashMap;
 
@@ -47,63 +17,48 @@ use crate::Chain;
 const EMOTES_TEXT: &str = "DBFilesClient\\EmotesText.dbc";
 const EMOTES_TEXT_DATA: &str = "DBFilesClient\\EmotesTextData.dbc";
 
-/// `EmotesText.dbc`'s `EmoteText[]` width — the selector is 4 bits wide because this is 16.
+/// `EmoteText[]`'s width, which the 4-bit selector indexes.
 const FORMS: usize = 16;
 
-/// How many locale columns an `EmotesTextData.dbc` row carries in 5875 (`id + 8 strings + flags`
-/// = the 10 fields the loader's `cmp eax,0xa` at `0x544579` insists on). Same shape as
-/// [`crate::languages`]'s `Name_lang` block, and read the same way: the loader keeps every column,
-/// the app asks for the slot it wants (`[0xc0e080]`, 0 = enUS, the only one this install fills).
+/// Locale columns per `EmotesTextData.dbc` row: id, 8 strings and flags make the 10 fields the
+/// loader checks (`0x544579`); the client reads the slot named in `[0xc0e080]`.
 const LOCALES: usize = 8;
 
 /// The joined text-emote sentence tables.
 #[derive(Debug, Default, Clone)]
 pub struct EmoteTextCatalog {
-    /// `EmotesText.dbc` id → its 16 `EmoteText[]` columns (each an `EmotesTextData` id, 0 = none).
+    /// `EmotesText.dbc` id to its 16 `EmoteText[]` columns, each an `EmotesTextData` id or 0.
     forms: HashMap<u32, [u32; FORMS]>,
-    /// `EmotesTextData.dbc` id → its localized format strings, one per locale column.
     data: HashMap<u32, [Option<String>; LOCALES]>,
 }
 
-/// The facts `0x49b200` branches on, in the composer's own terms.
-///
-/// **`target_is_you` is only tested when you are not the performer** — the guid compare at
-/// `0x49b2c8` jumps past it — so [`EmoteTextCatalog::compose`] derives both facts here rather than
-/// trusting a caller to pre-clear one.
-///
-/// That branch order once looked like it meant "a self-emote renders *You wave at ⟨YourName⟩.*",
-/// and decision 1274 said so. **It does not** (corrected by 1282): the sending client zeroes a
-/// self-target before the packet is built (`DoEmote 0x5ef611`), so `target` arrives EMPTY for that
-/// action and the untargeted column wins — "You wave.". Vanilla has no reflexive form *and* no
-/// self-named one; the case simply never reaches this struct.
+/// The facts `0x49b200` branches on. A self-emote never names you as its target: the sending
+/// client clears a self-target before building the packet (`DoEmote`, `0x5ef611`), so it arrives
+/// untargeted and reads "You wave.".
 #[derive(Debug, Clone, Copy)]
 pub struct EmoteLine<'a> {
-    /// The performer's resolved name — the `%s` the reference fills from the `NameCache` record
-    /// pointer it passes as-is (`record+0` *is* the name).
+    /// The performer's resolved name, the `%s` the reference fills from its `NameCache` record.
     pub performer: &'a str,
-    /// The performer guid == the active player's (`0x49b2c8`).
+    /// The performer guid is the active player's (`0x49b2c8`).
     pub performer_is_you: bool,
-    /// The performer's sex is Female (`record+0x13c == 1`) — the `+8` on the column index.
+    /// The performer is female, `NameCache` record `+0x13c == 1`: `+8` on the column (`0x49b31c`).
     pub performer_female: bool,
-    /// The target's display name **as the server sent it** (the wire string, never round-tripped
-    /// through a name cache); empty = untargeted.
+    /// The target name as the wire carries it, never round-tripped through a name cache; empty is
+    /// untargeted (`0x49b311`).
     pub target: &'a str,
-    /// Your own name (`GetOwnName 0x609210`), compared case-insensitively against `target`
-    /// (`0x64a480`).
+    /// Your own name (`GetOwnName`, `0x609210`), compared case-insensitively with `target` at
+    /// `0x49b2f3` (`0x64a480`).
     pub your_name: &'a str,
 }
 
 impl EmoteTextCatalog {
-    /// The composed chat line for a text emote, or `None` when the ladder runs dry (the
-    /// reference's "no line at all" tail — the emote is still an animation and a voice).
-    ///
-    /// `locale` is the client's locale column; 0 (enUS) is the only one a 5875 enUS install fills.
+    /// The chat line for a text emote; `None` when the ladder runs dry (`0x49b4bd`). `locale` is
+    /// the client's locale column, 0 for enUS.
     pub fn compose(&self, text_id: u32, line: &EmoteLine, locale: usize) -> Option<String> {
         let forms = self.forms.get(&text_id)?;
 
         // ── the selector (`0x49b2c3`-`0x49b316`) ────────────────────────────────────────────────
-        // Both flags start "the other guy" and are cleared by the branch that fires — the order is
-        // load-bearing: matching the performer skips the target compare entirely.
+        // Order matters: matching the performer skips the target compare entirely.
         let (mut performer_is_other, mut target_is_other) = (true, true);
         let mut ctx = 0usize;
         if line.performer_is_you {
@@ -119,8 +74,7 @@ impl EmoteTextCatalog {
         let gender = usize::from(line.performer_female) * 8;
 
         // ── the ladder (`0x49b332` / `0x49b35e` / `0x49b38a` / `0x49b3c5`) ──────────────────────
-        // `ctx` is mutated in place by rung 3, exactly as the reference mutates `esi`, so rung 4
-        // reads the *corrected* context and not the original one.
+        // Rung 3 rewrites `ctx` in place, as the reference does `esi`, so rung 4 reads the new one.
         let template = self
             .template(forms, gender | ctx, locale)
             .or_else(|| self.template(forms, ctx, locale))
@@ -135,15 +89,12 @@ impl EmoteTextCatalog {
             (true, true) => fill(template, &[line.performer, line.target]),
             (true, false) => fill(template, &[line.performer]),
             (false, true) => fill(template, &[line.target]),
-            // Provably unreachable in the reference (clearing `target_is_other` requires the
-            // performer branch not to have fired); kept as the format's own no-arg case.
+            // Unreachable: clearing `target_is_other` needs the performer branch not to fire.
             (false, false) => fill(template, &[]),
         })
     }
 
-    /// One `EmoteText[index]` column resolved to a **non-empty** localized string, or `None` — the
-    /// reference's four rejections rolled into one (`index` past the array, the column's id absent
-    /// from `EmotesTextData`, the row's string blank for this locale).
+    /// One `EmoteText[index]` column's non-empty string for the locale, the ladder's rung test.
     fn template<'a>(
         &'a self,
         forms: &[u32; FORMS],
@@ -154,7 +105,7 @@ impl EmoteTextCatalog {
         self.data.get(&data_id)?.get(locale)?.as_deref()
     }
 
-    /// How many `EmotesText.dbc` rows carry a form table (169 in 5875).
+    /// `EmotesText.dbc` rows, 169 in 5875.
     pub fn len(&self) -> usize {
         self.forms.len()
     }
@@ -164,9 +115,8 @@ impl EmoteTextCatalog {
     }
 }
 
-/// `SStrPrintf` (`0x64a7f0`) reduced to what these templates actually use: replace each `%s` with
-/// the next argument, left to right. A template with more `%s` than arguments keeps the surplus
-/// verbatim — the reference would print stack garbage there, and no shipped row does it.
+/// `SStrPrintf` (`0x64a7f0`) reduced to the `%s` these templates use. Deviation: a surplus `%s`
+/// stays verbatim, where the reference would print stack garbage; no shipped row has one.
 fn fill(template: &str, args: &[&str]) -> String {
     let mut out = String::with_capacity(template.len() + 16);
     let mut rest = template;
@@ -181,8 +131,7 @@ fn fill(template: &str, args: &[&str]) -> String {
     out
 }
 
-/// `EmotesText.dbc` — `ID`, `Name`(str), `EmoteID`, `EmoteText[16]`; 19 fields × 4 = the 76-byte
-/// record the client's loader checks for.
+/// `EmotesText.dbc`: 19 fields, the 76-byte record the reference loader checks for.
 fn emotes_text_schema() -> Schema {
     let mut s = Schema::new("EmotesText");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -194,8 +143,8 @@ fn emotes_text_schema() -> Schema {
     s
 }
 
-/// `EmotesTextData.dbc` — `ID`, eight `Text_lang` strings, `Flags`; the classic 1.12
-/// `LocalizedString` block (10 fields × 4 = 40 bytes, the reader's own `cmp eax,0x28`).
+/// `EmotesTextData.dbc`: a 1.12 `LocalizedString` block, the 40-byte record the reader checks
+/// (`cmp eax,0x28`).
 fn emotes_text_data_schema() -> Schema {
     let mut s = Schema::new("EmotesTextData");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -231,8 +180,8 @@ pub fn load_emote_text_catalog(chain: &mut Chain) -> Result<EmoteTextCatalog> {
         let Some(id) = u32_at(r, 0) else { continue };
         let mut texts: [Option<String>; LOCALES] = Default::default();
         for (locale, slot) in texts.iter_mut().enumerate() {
-            // `str_at` already answers `None` for an empty string, which is the reference's
-            // "blank for this locale ⇒ take the next rung" test (`cmpb $0,(%edx)`).
+            // `str_at` answers `None` for an empty string: the reference's blank-means-next-rung
+            // test (`cmpb $0,(%edx)`).
             *slot = str_at(&rs, r, 1 + locale);
         }
         data.insert(id, texts);
@@ -245,9 +194,7 @@ pub fn load_emote_text_catalog(chain: &mut Chain) -> Result<EmoteTextCatalog> {
 mod tests {
     use super::*;
 
-    /// WAVE's five reachable enUS forms — the row wow-re's note pins, so a schema slip (a
-    /// column-index off-by-one, the wrong locale slot) shows up as the wrong sentence rather than
-    /// as a silent empty.
+    /// WAVE: a column or locale slip shows as the wrong sentence, never a silent empty.
     const WAVE: u32 = 101;
 
     fn line<'a>(performer: &'a str, target: &'a str, you: &'a str) -> EmoteLine<'a> {
@@ -268,13 +215,10 @@ mod tests {
         );
         assert_eq!(fill("%s waves at you.", &["Bob"]), "Bob waves at you.");
         assert_eq!(fill("You wave.", &["Bob"]), "You wave.");
-        // Surplus verbs stay literal rather than eating the rest of the template.
         assert_eq!(fill("%s waves at %s.", &["Bob"]), "Bob waves at %s.");
         assert_eq!(fill("", &["Bob"]), "");
     }
 
-    /// The real chain: this module is a join between two shipped tables plus a bit-selector, and a
-    /// synthetic fixture would only test the plumbing.
     #[test]
     fn the_shipped_tables_compose_waves_five_forms() {
         let data = crate::wow_data_or_skip!();
@@ -282,22 +226,22 @@ mod tests {
         let cat = load_emote_text_catalog(&mut chain).expect("load");
         assert_eq!(cat.len(), 169, "one form table per EmotesText row");
 
-        // ctx 0 — someone else waves at someone else.
+        // ctx 0: someone else waves at someone else.
         assert_eq!(
             cat.compose(WAVE, &line("Bob", "Jane", "Me"), 0).as_deref(),
             Some("Bob waves at Jane.")
         );
-        // ctx 1 — someone else waves at YOU (the target name matches your own).
+        // ctx 1: someone else waves at you (the target name matches your own).
         assert_eq!(
             cat.compose(WAVE, &line("Bob", "Me", "Me"), 0).as_deref(),
             Some("Bob waves at you.")
         );
-        // ctx 4 — someone else waves at nobody.
+        // ctx 4: someone else waves at nobody.
         assert_eq!(
             cat.compose(WAVE, &line("Bob", "", "Me"), 0).as_deref(),
             Some("Bob waves.")
         );
-        // ctx 2 — YOU wave at someone.
+        // ctx 2: you wave at someone.
         let mine = EmoteLine {
             performer_is_you: true,
             ..line("Me", "Jane", "Me")
@@ -306,7 +250,7 @@ mod tests {
             cat.compose(WAVE, &mine, 0).as_deref(),
             Some("You wave at Jane.")
         );
-        // ctx 6 — YOU wave at nobody.
+        // ctx 6: you wave at nobody.
         let mine = EmoteLine {
             performer_is_you: true,
             ..line("Me", "", "Me")
@@ -314,16 +258,8 @@ mod tests {
         assert_eq!(cat.compose(WAVE, &mine, 0).as_deref(), Some("You wave."));
     }
 
-    /// **The composer has no self-target case, because it can never be handed one** — and this
-    /// test exists to record that, since the shape of the code invites the opposite conclusion
-    /// (decision 1282, correcting 1274).
-    ///
-    /// The branch order is real: `0x49b2c8` matching the performer jumps past the target compare,
-    /// so if a self-emote *did* arrive with your own name in the target slot, this is what it
-    /// would render. It never arrives. The **send** side zeroes a self-target before the packet
-    /// exists (`DoEmote 0x5ef611`), so the server echoes an empty name and the untargeted column
-    /// wins — "You wave.", asserted just above. Reading this arm as "what a self-emote does" is
-    /// exactly the mistake 1274 made.
+    /// The branch order would render your own name for a self-target, but the send side clears a
+    /// self-target (`DoEmote`, `0x5ef611`), so the server echoes an empty name: "You wave.".
     #[test]
     fn the_self_named_target_form_is_unreachable_from_the_wire() {
         let data = crate::wow_data_or_skip!();
@@ -337,8 +273,7 @@ mod tests {
             cat.compose(WAVE, &me, 0).as_deref(),
             Some("You wave at Me.")
         );
-        // What the wire actually delivers for that same action — an EMPTY target — and therefore
-        // what a player really reads.
+        // What the wire delivers for that action: an empty target.
         let me = EmoteLine {
             performer_is_you: true,
             ..line("Me", "", "Me")
@@ -346,8 +281,7 @@ mod tests {
         assert_eq!(cat.compose(WAVE, &me, 0).as_deref(), Some("You wave."));
     }
 
-    /// The gender rung: WAVE has no female column, so `8|ctx` misses and rung 2 (`ctx` alone)
-    /// answers — a female performer must read exactly the same sentence, not nothing.
+    /// WAVE has no female column, so `8|ctx` misses and rung 2, `ctx` alone, answers.
     #[test]
     fn a_missing_female_column_falls_back_to_the_ungendered_one() {
         let data = crate::wow_data_or_skip!();
@@ -363,28 +297,19 @@ mod tests {
         );
     }
 
-    /// A locale column this install does not ship is empty everywhere, so the ladder runs dry and
-    /// the composer emits no line — the reference's `0x49b4bd` tail, not a panic and not a blank.
+    /// An unshipped locale is empty everywhere, so the ladder runs dry: no line (`0x49b4bd`).
     #[test]
     fn an_unshipped_locale_composes_nothing() {
         let data = crate::wow_data_or_skip!();
         let mut chain = Chain::open(&data).expect("open patch chain");
         let cat = load_emote_text_catalog(&mut chain).expect("load");
         assert_eq!(cat.compose(WAVE, &line("Bob", "Jane", "Me"), 5), None);
-        // …and so does an id with no row at all.
         assert_eq!(cat.compose(9999, &line("Bob", "Jane", "Me"), 0), None);
     }
 
-    /// The whole table, not one row. This is the check that would have caught B156's real shape —
-    /// "the sentence table is never consulted" reads identically to "this one emote has no text"
-    /// until you sweep all 169.
-    ///
-    /// **Exactly three rows are legitimately silent**, and naming them is the point: `SIT`(86)
-    /// points columns 4/6 at `EmotesTextData` rows 446/447, which exist but ship **blank in every
-    /// locale**, while `STAND`(141) and `TRAIN`(264) have all sixteen columns zero. The ladder
-    /// therefore runs dry for them and the reference prints nothing — which is what a vanilla
-    /// `/sit` does. Every other row must compose a `%s`-free sentence in all five reachable
-    /// contexts.
+    /// Three rows are silent as shipped: `SIT` (86) points columns 4 and 6 at `EmotesTextData`
+    /// rows 446 and 447, blank in every locale, and `STAND` (141) and `TRAIN` (264) have all
+    /// sixteen columns zero. Every other row composes a `%s`-free sentence in all five contexts.
     #[test]
     fn every_shipped_emote_composes_except_the_three_silent_rows() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/emotes.rs b/crates/benilla-formats/src/emotes.rs
index 27cefb42..06455408 100644
--- a/crates/benilla-formats/src/emotes.rs
+++ b/crates/benilla-formats/src/emotes.rs
@@ -1,30 +1,7 @@
-//! Emote audio data (decision 0070 slice 4): **EmotesText** (the `/wave` command table) joined
-//! to **EmotesTextSound** (the race/sex voice kits) and **Emotes** (anim emotes + their
-//! `EventSoundID`).
-//!
-//! Layouts — VERIFIED against build 5875 (headers + row decodes, 2026-07-02):
-//! - `EmotesText` **169 × 19 × 76 B**: `ID, Name(str, e.g. "WAVE"), EmoteID (→Emotes),
-//!   EmoteText[16]`. Spot-check: WAVE = id 101, emote 3.
-//! - `EmotesTextSound` **418 × 5 × 20 B**: `ID, EmotesTextID, RaceID, SexID (0 male / 1 female),
-//!   SoundID (→SoundEntries)`.
-//! - `Emotes` **78 × 7 × 28 B**: `ID, SlashCommand(str), AnimID, EmoteFlags, EmoteSpecProc,
-//!   EmoteSpecProcParam, EventSoundID (→SoundEntries)`. Spot-check row 2: ONESHOT_BOW, anim 66
-//!   (VERIFIED against vmangos `SharedDefines.h`'s `Emote` enum: `EMOTE_ONESHOT_BOW = 2`).
-//!
-//! `AnimID` (column 2) feeds both the one-shot anim-emote path (`SMSG_EMOTE`'s `Emotes.dbc` id) and
-//! the looping state-emote idle (`UNIT_NPC_EMOTESTATE`, the same id space) — [`EmoteSoundCatalog::anim`].
-//!
-//! `EmoteSpecProc`/`EmoteSpecProcParam` (columns 4/5) carry the **posture** half of the client's
-//! `DoEmote`: proc `1` means "this emote sets a stand state", and the param IS that state
-//! ([`EmoteSoundCatalog::posture_state`]) — the mechanism behind `/sit` (proc `2` is the looping
-//! state emote whose `EventSoundID` the `$ESD` event rings).
-//!
-//! `EmoteFlags` (column 3) feeds the **send-side posture-eligibility gate** — the only `EmoteFlags`
-//! consumer, byte-verified at the real client's `CheckEmoteEligible` (`0x47db40`, called from
-//! `DoEmote` `0x5ef560`): before `CMSG_TEXT_EMOTE` goes out, bit `0x0001` combined with a non-zero
-//! stand-state aborts the *entire* emote (no packet, no anim — a seated `/bow` does nothing).
-//! `wow-5875-re`'s `system/object-layer/scratch/emote-posture-gate.md` (commit `f9584b45`) is the
-//! authority; [`EmoteSoundCatalog::emote_flags`] promotes the raw bits for `crate::chat`'s gate.
+//! Emote data: `EmotesText` (`ID, Name, EmoteID, EmoteText[16]`, the `/wave` command table)
+//! joined to `EmotesTextSound` (`ID, EmotesTextID, RaceID, SexID, SoundID`, the voice kits)
+//! and `Emotes`, the anim emotes:
+//! `ID, SlashCommand, AnimID, EmoteFlags, EmoteSpecProc, EmoteSpecProcParam, EventSoundID`.
 
 use std::collections::HashMap;
 
@@ -34,39 +11,28 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 
 use crate::dbc::{parse, str_at, u32_at};
 
-/// The joined emote-audio tables.
+/// The joined emote tables.
 pub struct EmoteSoundCatalog {
-    /// Uppercased `EmotesText.Name` ("WAVE") → text-emote id — the `/command` send key.
+    /// Uppercased `EmotesText.Name` ("WAVE") to text-emote id.
     by_name: HashMap<String, u32>,
-    /// text-emote id → `Emotes.dbc` id (the anim the emote plays; 0 = chat-only).
+    /// Text-emote id to the `Emotes.dbc` id it plays, 0 for chat-only.
     text_emote: HashMap<u32, u32>,
-    /// `(text-emote id, race, sex)` → voice kit.
+    /// `(text-emote id, race, sex)` to voice kit.
     voice: HashMap<(u32, u32, u32), u32>,
-    /// `Emotes.dbc` id → its `EventSoundID` kit (0 = none).
     event_sound: HashMap<u32, u32>,
-    /// `Emotes.dbc` id → its `AnimID` (`AnimationData.dbc` id; 0 = none).
     anim: HashMap<u32, u32>,
-    /// `Emotes.dbc` id → its `EmoteFlags` (the send-side posture-eligibility gate bits).
     emote_flags: HashMap<u32, u32>,
-    /// `Emotes.dbc` id → its `EmoteSpecProc` (column 4). `2` marks a looping STATE emote whose
-    /// `EventSoundID` the `$ESD` anim event rings (the client's `row[+0x10] == 2` gate at the
-    /// `$ESD` handler `0x6239f0` — wow-re `sound/scratch/gather-sound-anim-events.md`).
+    /// `Emotes.dbc` id to its `EmoteSpecProc`; `2` is a looping state emote whose `EventSoundID`
+    /// the `$ESD` anim event rings (`0x6239f0` tests `row[+0x10] == 2`).
     spec_proc: HashMap<u32, u32>,
-    /// `Emotes.dbc` id → its `EmoteSpecProcParam` (column 5). For `EmoteSpecProc == 1` this is the
-    /// **stand state** the emote sets — see [`EmoteSoundCatalog::posture_state`].
+    /// `Emotes.dbc` id to its `EmoteSpecProcParam`, the stand state when `EmoteSpecProc` is 1.
     spec_proc_param: HashMap<u32, u32>,
-    /// The five **chat/interact gesture slots**, in [`GESTURE_FLAG_BITS`] order — see
-    /// [`EmoteSoundCatalog::gesture`].
+    /// The five gesture slots, in [`GESTURE_FLAG_BITS`] order.
     gesture: [Option<u32>; GESTURE_FLAG_BITS.len()],
 }
 
-/// The five `EmoteFlags` bits the client hard-codes to build its gesture table (`0x603a60`, wow-re
-/// `object-layer/scratch/chat-talk-gesture.md` §3), in slot order — **talk, question, exclamation,
-/// shout, laugh**. The *bits* are the fidelity fact: the client never names an `Emotes.dbc` id or an
-/// `AnimationData.dbc` id here, it scans the table for whichever row carries each bit. In the
-/// shipped 1.12.1 data each bit is carried by exactly one row (ids 1 / 6 / 5 / 22 / 11 → anims
-/// 60 / 65 / 64 / 81 / 70), but transcribing those numbers instead of the scan would bake content
-/// into code.
+/// The `EmoteFlags` bits the client scans `Emotes.dbc` for to build its gesture table
+/// (`0x603a60`), in slot order: talk, question, exclamation, shout, laugh. It names no row id.
 pub const GESTURE_FLAG_BITS: [u32; 5] = [0x08, 0x10, 0x20, 0x40, 0x100];
 
 impl EmoteSoundCatalog {
@@ -80,7 +46,7 @@ impl EmoteSoundCatalog {
         self.voice.get(&(text_id, race, sex)).copied()
     }
 
-    /// The anim emote a text emote plays (0/none for chat-only emotes).
+    /// The anim emote a text emote plays.
     pub fn text_emote(&self, text_id: u32) -> Option<u32> {
         self.text_emote.get(&text_id).copied().filter(|&e| e != 0)
     }
@@ -90,43 +56,33 @@ impl EmoteSoundCatalog {
         self.event_sound.get(&emote_id).copied().filter(|&k| k != 0)
     }
 
-    /// An `Emotes.dbc` id's `AnimID` (the `AnimationData.dbc` id it plays; `0`/absent = none).
-    /// Shared by the one-shot anim-emote path (`SMSG_EMOTE`) and the looping state-emote idle
-    /// (`UNIT_NPC_EMOTESTATE`) — both carry an `Emotes.dbc` id in the same id space.
+    /// The `AnimationData.dbc` id an `Emotes.dbc` id plays, for both `SMSG_EMOTE` one-shots and
+    /// the looping `UNIT_NPC_EMOTESTATE` idle, which share the id space.
     pub fn anim(&self, emote_id: u32) -> Option<u32> {
         self.anim.get(&emote_id).copied().filter(|&a| a != 0)
     }
 
-    /// The `Emotes.dbc` id in gesture slot `slot` — an index into [`GESTURE_FLAG_BITS`], which is
-    /// exactly the `code` the client's gesture dispatcher `0x60bb30` takes. `None` when no shipped
-    /// row carries that bit (the client's own "empty slot ⇒ no gesture" leg).
+    /// The `Emotes.dbc` id in gesture `slot`, the `code` the client's gesture dispatcher
+    /// `0x60bb30` takes; a slot no shipped row fills plays no gesture, as in the client.
     pub fn gesture(&self, slot: usize) -> Option<u32> {
         self.gesture.get(slot).copied().flatten()
     }
 
-    /// An `Emotes.dbc` id's raw `EmoteFlags` bits (`None` when the id isn't in the catalog; `0` is a
-    /// real, meaningful value — "no gate bits set" — so unlike [`Self::anim`]/[`Self::event_sound`]
-    /// it is *not* filtered out). Feeds `benilla::chat`'s send-side posture-eligibility gate — see
-    /// the module doc.
+    /// An `Emotes.dbc` id's raw `EmoteFlags`, `0` included. Bit `0x0001` with a non-zero stand
+    /// state aborts the whole emote before `CMSG_TEXT_EMOTE` is sent, so a seated `/bow` does
+    /// nothing (`0x47db40`, called from `DoEmote` `0x5ef560`).
     pub fn emote_flags(&self, emote_id: u32) -> Option<u32> {
         self.emote_flags.get(&emote_id).copied()
     }
 
-    /// An `Emotes.dbc` id's `EmoteSpecProc` (`None` when the id isn't in the catalog; `0` is a real
-    /// value, so not filtered). `2` = a looping state emote — the `$ESD` event-sound gate (see the
-    /// field doc).
+    /// An `Emotes.dbc` id's `EmoteSpecProc`, `0` included; `2` is a looping state emote.
     pub fn spec_proc(&self, emote_id: u32) -> Option<u32> {
         self.spec_proc.get(&emote_id).copied()
     }
 
-    /// The **stand state** a POSTURE emote sets: `EmoteSpecProcParam` gated on `EmoteSpecProc == 1`
-    /// (`None` for every other emote). This is the client's `DoEmote` state branch — wow-re
-    /// `object-layer/scratch/emote-posture-gate.md` §1: `if (rec.EmoteSpecProc == 1 && …)
-    /// SetStandState(rec.SpecProcParam)`, the same `0x5ed430` setter the sit key drives. The five
-    /// reachable rows: STATE_SIT(13)→1, STATE_SLEEP(12)→3, STATE_KNEEL(68)→8, STATE_STAND(26)→0,
-    /// STATE_AT_EASE(313)→2 — which is why `/sit` sits at all, since the *server* deliberately does
-    /// nothing for a STATE text emote (vmangos `ChatHandler.cpp` `HandleTextEmoteOpcode`: SIT /
-    /// SLEEP / KNEEL / NONE break out before `HandleEmote`).
+    /// The stand state a posture emote sets, `EmoteSpecProcParam` when `EmoteSpecProc` is 1, as
+    /// `DoEmote` (`0x5ef560`) feeds the sit key's setter `0x5ed430`. `/sit` rests on this alone:
+    /// the server does nothing for a state text emote (`ChatHandler.cpp` `HandleTextEmoteOpcode`).
     pub fn posture_state(&self, emote_id: u32) -> Option<u32> {
         (self.spec_proc.get(&emote_id).copied() == Some(1))
             .then(|| self.spec_proc_param.get(&emote_id).copied())
@@ -194,11 +150,9 @@ pub fn load_emote_sound_catalog(chain: &mut Chain) -> Result<EmoteSoundCatalog>
     let mut emote_flags = HashMap::with_capacity(rs.records().len());
     let mut spec_proc = HashMap::with_capacity(rs.records().len());
     let mut spec_proc_param = HashMap::with_capacity(rs.records().len());
-    // The gesture slots. The client walks the record array from the LAST index DOWN and its bit
-    // tests are an else-if chain, so a row carrying two of the bits lands only in the first
-    // matching slot and a duplicated bit resolves to the LOWEST array index. Iterating forward and
-    // letting an earlier row win reproduces both, without depending on either: no shipped row
-    // carries more than one of these bits, and none of them is duplicated.
+    // The client walks the rows from the last down with an else-if chain over the bits, so a row
+    // lands only in its first matching slot and a shared bit goes to the lowest index; iterating
+    // forward with the earlier row winning gives the same table.
     let mut gesture: [Option<u32>; GESTURE_FLAG_BITS.len()] = [None; GESTURE_FLAG_BITS.len()];
     for r in rs.records() {
         let Some(id) = u32_at(r, 0) else { continue };
@@ -241,10 +195,7 @@ pub fn load_emote_sound_catalog(chain: &mut Chain) -> Result<EmoteSoundCatalog>
 mod tests {
     use super::*;
 
-    /// The five gesture slots resolve off the REAL shipped `Emotes.dbc` — the check that the
-    /// flag-bit scan finds the right rows, and that each bit really is carried by exactly one of
-    /// them. The expected ids/anims are the byte-verified table in wow-re
-    /// `object-layer/scratch/chat-talk-gesture.md` §3; the *code* never names them.
+    /// The expected ids and anims are the table `0x603a60` builds from the shipped data.
     #[test]
     fn the_five_gesture_slots_scan_to_the_shipped_rows() {
         let data = crate::wow_data_or_skip!();
@@ -261,9 +212,7 @@ mod tests {
             assert_eq!(cat.gesture(slot), Some(emote_id), "{what} slot -> emote id");
             assert_eq!(cat.anim(emote_id), Some(anim_id), "{what} emote -> AnimID");
         }
-        // Each of the five bits is carried by exactly one shipped row, so the else-if chain and
-        // the walk direction cannot matter. If a patch ever broke this, the scan would silently
-        // pick a different row and the gestures would drift — so assert it, do not assume it.
+        // One shipped row per bit, so the walk order cannot matter.
         for bit in GESTURE_FLAG_BITS {
             let carriers = cat
                 .emote_flags
@@ -274,9 +223,6 @@ mod tests {
         }
     }
 
-    /// The joins hold on real 5875 data: WAVE resolves by name to the byte-decoded id 101 with
-    /// anim emote 3; some voice row exists for a human (race 1) male; the voice map carries the
-    /// male/female split (the survey's sample rows pair sexes per race).
     #[test]
     fn real_emote_chain_resolves() {
         let data = crate::wow_data_or_skip!();
@@ -285,9 +231,7 @@ mod tests {
         assert_eq!(cat.text_id("wave"), Some(101), "case-insensitive by name");
         assert_eq!(cat.text_emote(101), Some(3), "WAVE plays anim emote 3");
         assert_eq!(cat.anim(2), Some(66), "ONESHOT_BOW (id 2) plays AnimID 66");
-        // EmoteFlags for the director-verified posture-gate rows (emote-posture-gate.md §3), ids
-        // from vmangos `SharedDefines.h`'s `Emote` enum: BOW=2, CHEER=4, LAUGH=11, RUDE=14,
-        // APPLAUD=21, SALUTE=66.
+        // The posture-gate rows (`0x47db40`), ids from vmangos `SharedDefines.h`'s `Emote` enum.
         assert_eq!(cat.emote_flags(2), Some(0x4801), "ONESHOT_BOW EmoteFlags");
         assert_eq!(cat.emote_flags(4), Some(0x0800), "ONESHOT_CHEER EmoteFlags");
         assert_eq!(
@@ -306,8 +250,7 @@ mod tests {
             Some(0x0800),
             "ONESHOT_SALUTE EmoteFlags"
         );
-        // The $ESD gathering chain (decision 0562): STATE_WORK_NOSHEATHE_MINING (233) is a
-        // spec-proc-2 state emote carrying the MiningHit kit; its one-shot cousins carry proc 0.
+        // STATE_WORK_NOSHEATHE_MINING (233), a proc-2 state emote carrying the mining kit.
         assert_eq!(cat.spec_proc(233), Some(2), "mining state EmoteSpecProc");
         assert_eq!(
             cat.event_sound(233),
@@ -316,15 +259,12 @@ mod tests {
         );
         assert_eq!(cat.anim(233), Some(136), "mining state plays anim 136");
         assert_eq!(cat.spec_proc(2), Some(0), "ONESHOT_BOW EmoteSpecProc");
-        // The posture branch (`DoEmote`'s `EmoteSpecProc == 1` → `SetStandState(param)`): the four
-        // stand states a slash emote can reach, byte-decoded off the shipped table. The values are
-        // vmangos `UnitStandStateType` (STAND 0 · SIT 1 · SLEEP 3 · KNEEL 8).
+        // Stand states are vmangos `UnitStandStateType` values (STAND 0, SIT 1, SLEEP 3, KNEEL 8).
         assert_eq!(cat.posture_state(13), Some(1), "STATE_SIT sets SIT");
         assert_eq!(cat.posture_state(12), Some(3), "STATE_SLEEP sets SLEEP");
         assert_eq!(cat.posture_state(68), Some(8), "STATE_KNEEL sets KNEEL");
         assert_eq!(cat.posture_state(26), Some(0), "STATE_STAND sets STAND");
-        // A proc-2 state emote and a one-shot are NOT posture emotes, however tempting their param
-        // looks: the gate is the proc column, not the param's presence.
+        // The gate is the proc column, not the param's presence.
         assert_eq!(cat.posture_state(233), None, "mining state is proc 2");
         assert_eq!(cat.posture_state(2), None, "ONESHOT_BOW is proc 0");
         assert!(
diff --git a/crates/benilla-formats/src/environmental_damage.rs b/crates/benilla-formats/src/environmental_damage.rs
index bfc40513..17a95343 100644
--- a/crates/benilla-formats/src/environmental_damage.rs
+++ b/crates/benilla-formats/src/environmental_damage.rs
@@ -1,14 +1,6 @@
-//! **EnvironmentalDamage.dbc** — the environmental-damage feedback table: damage type →
-//! `SpellVisualKit` id, played on the victim when `SMSG_ENVIRONMENTALDAMAGELOG` arrives (the
-//! fall-landing dust puff and its five siblings).
-//!
-//! The byte-verified client shape (wow-re `sound/scratch/uisound-tables.md`): init `0x603900`
-//! zeroes a **6-slot table** (`[0xc4d8e4]`) and, for each record with `field1 < 6`, stores
-//! `slot[field1] = field2` — so field 1 is the `EnvironmentalDamageType` enum (0 exhausted ·
-//! 1 drowning · 2 fall · 3 lava · 4 slime · 5 fire; the wire's `damage_type`) and field 2 the
-//! kit id. Sole reader `0x624fcc` (in the 0x1FC consequence method `0x624f30`) bounds the kit id
-//! against `SpellVisualKit.dbc` and plays it. Build 5875 data: 0→871, 1→870, 2→**1066** (the
-//! "DustCloud Land" kit), 3→1064, 4→1065, 5→1067.
+//! `EnvironmentalDamage.dbc`: the `SpellVisualKit` played on the victim of
+//! `SMSG_ENVIRONMENTALDAMAGELOG` (read at `0x624fcc` in `0x624f30`), by the wire's `damage_type`:
+//! 0 exhausted, 1 drowning, 2 fall, 3 lava, 4 slime, 5 fire.
 
 use crate::Chain;
 use anyhow::{Context, Result};
@@ -18,14 +10,13 @@ use crate::dbc::{parse, u32_at};
 
 const ENVIRONMENTAL_DAMAGE: &str = "DBFilesClient\\EnvironmentalDamage.dbc";
 
-/// The 6-slot damage-type → `SpellVisualKit` table (the client's `[0xc4d8e4]`).
+/// The client's 6-slot damage type → kit table (`[0xc4d8e4]`).
 pub struct EnvironmentalDamageTable {
     kits: [u32; 6],
 }
 
 impl EnvironmentalDamageTable {
-    /// The `SpellVisualKit` id for a wire `damage_type` (0–5). `None` for an out-of-range type or
-    /// an empty slot — the client's `field1 < 6` init guard and zero-init respectively.
+    /// The kit for a wire `damage_type`; `None` past type 5 or for an empty slot.
     pub fn kit_id(&self, damage_type: u8) -> Option<u32> {
         self.kits
             .get(usize::from(damage_type))
@@ -34,7 +25,6 @@ impl EnvironmentalDamageTable {
     }
 }
 
-/// EnvironmentalDamage.dbc — 3 fields in build 5875: ID, the damage-type enum, the kit id.
 fn schema() -> Schema {
     let mut s = Schema::new("EnvironmentalDamage");
     for name in ["ID", "DamageType", "VisualKit"] {
@@ -43,8 +33,8 @@ fn schema() -> Schema {
     s
 }
 
-/// Load the table from the patch chain, exactly as the client's init `0x603900` fills its 6-slot
-/// store: zeroed slots, `slot[DamageType] = VisualKit` for each in-range record.
+/// Load the table as the client's init `0x603900` fills it: zeroed, then
+/// `slot[DamageType] = VisualKit` for each row whose type is below 6.
 pub fn load_environmental_damage(chain: &mut Chain) -> Result<EnvironmentalDamageTable> {
     let bytes = chain
         .read_file(ENVIRONMENTAL_DAMAGE)
@@ -52,7 +42,6 @@ pub fn load_environmental_damage(chain: &mut Chain) -> Result<EnvironmentalDamag
     table_from(&bytes)
 }
 
-/// The fill itself, split from the chain read so the golden test drives the identical path.
 fn table_from(bytes: &[u8]) -> Result<EnvironmentalDamageTable> {
     let rs = parse(bytes, schema(), "EnvironmentalDamage")?;
     let mut kits = [0u32; 6];
@@ -70,8 +59,7 @@ fn table_from(bytes: &[u8]) -> Result<EnvironmentalDamageTable> {
 mod tests {
     use super::*;
 
-    /// A hand-built WDBC with the real 5875 rows (verified via benilla-extract 2026-07-16) plus an
-    /// out-of-range type-9 row that must hit the `field1 < 6` init guard and load nowhere.
+    /// The shipped rows, plus a type-9 row that the range guard must skip.
     #[test]
     fn table_loads_by_damage_type_with_the_range_guard() {
         let rows: &[[u32; 3]] = &[
diff --git a/crates/benilla-formats/src/exhaustion.rs b/crates/benilla-formats/src/exhaustion.rs
index 3976ac5a..b77f0ef6 100644
--- a/crates/benilla-formats/src/exhaustion.rs
+++ b/crates/benilla-formats/src/exhaustion.rs
@@ -1,18 +1,7 @@
-//! Exhaustion.dbc — the rest-state table behind the client's rested-XP surface.
-//!
-//! The whole client contract is byte-carved in wow-re `system/ui/scratch/rested-xp-bindings.md`
-//! (decision 1087 is the benilla fold-back): `GetRestState 0x48d350` indexes this table
-//! **directly by the `PLAYER_BYTES_2` rest-state byte** (an ID→row-ptr array, `[0xc0dd78]`) and
-//! returns `(row.ID, row.name[locale], row.factor)`; `GetXPExhaustion 0x48d3f0` multiplies the
-//! rested pool by **row ID 1's factor, hard-coded** (2.0 in the shipped data — the "rested XP is
-//! double" law is this one f32, not a client constant). The names come from this file's string
-//! block, **not** GlobalStrings — which is why "Rested"/"Normal" localize with the install.
-//!
-//! Row layout (fieldCount 0xf / recordSize 0x3c, validated by the client loader `0x544da0`):
-//! `ID@0`, `Xp@1`, `Factor@2` (f32), `OutdoorHours@3`, `InnHours@4` (both unread by the
-//! bindings), `Name_Lang@5..12`, `NameFlags@13`, `Threshold@14`. Shipped 5875 rows: 1 "Rested"
-//! 2.0 · 2 "Normal" 1.0 · 3/4 "XXXTired" 1.0/0.5 · 5 "XXXExhausted" 0.25 — rows 3..5 are the
-//! never-shipped beta tiers FrameXML still carries dead branches for.
+//! `Exhaustion.dbc`: the rest states. `GetRestState` (`0x48d350`) indexes it by the
+//! `PLAYER_BYTES_2` rest-state byte (`[0xc0dd78]`) and returns the id, the name from this file's
+//! string block (not GlobalStrings) and the factor. `GetXPExhaustion` (`0x48d3f0`) scales the
+//! rested pool by row 1's factor, 2.0 in the data. Rows 3-5 are beta tiers never sent.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -22,14 +11,13 @@ use crate::Chain;
 
 const EXHAUSTION: &str = "DBFilesClient\\Exhaustion.dbc";
 
-/// One Exhaustion.dbc row as the rest bindings consume it.
+/// One rest state, as `GetRestState` returns it.
 pub struct ExhaustionRow {
-    /// The row ID — also exactly the wire's rest-state byte (the client indexes by it).
+    /// Also the wire's rest-state byte, which the client indexes by.
     pub id: u32,
-    /// The localized state name (`GetRestState`'s second return; enUS slot of this install).
+    /// The state name, from the enUS slot.
     pub name: String,
-    /// The XP multiplier (`GetRestState`'s third return; row 1's value is `GetXPExhaustion`'s
-    /// scale).
+    /// The XP multiplier.
     pub factor: f32,
 }
 
@@ -48,7 +36,7 @@ fn exhaustion_schema() -> Schema {
     s
 }
 
-/// Load Exhaustion.dbc from the patch chain — the rows for `UiScript::set_exhaustion_rows`.
+/// Load Exhaustion.dbc from the patch chain.
 pub fn load_exhaustion(chain: &mut Chain) -> Result<Vec<ExhaustionRow>> {
     let bytes = chain
         .read_file(EXHAUSTION)
@@ -69,10 +57,6 @@ pub fn load_exhaustion(chain: &mut Chain) -> Result<Vec<ExhaustionRow>> {
 mod tests {
     use super::load_exhaustion;
 
-    /// The shipped 5875 table, read as data rather than assumed — the same five rows the wow-re
-    /// dispatch extracted from the MPQs independently (rested-xp-bindings.md): the rested factor
-    /// really is 2.0-as-data, and the beta tiers really ship with placeholder names. Skips
-    /// without client data.
     #[test]
     fn the_shipped_rest_states_carry_the_rested_double() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/factions.rs b/crates/benilla-formats/src/factions.rs
index 979a6808..4bf41851 100644
--- a/crates/benilla-formats/src/factions.rs
+++ b/crates/benilla-formats/src/factions.rs
@@ -1,32 +1,12 @@
-//! Unit reaction: the FactionTemplate.dbc catalog + the client's faction-reaction comparator.
+//! Unit reaction: the `FactionTemplate.dbc` catalog and the 1.12 client's reaction comparator.
 //!
-//! A unit's `UNIT_FIELD_FACTIONTEMPLATE` indexes **FactionTemplate.dbc**; the real client decides
-//! hostile/neutral/friendly by comparing two of those rows with one pure function — the reaction
-//! comparator at `0x606640` (wow-5875-re object-layer, byte-verified disasm, §5-cross-checked). Every
-//! `UnitReaction`/`CanAttack`/`CanAssist` predicate bottoms out in it, and it's what colours nameplates
-//! and the ground selection ring (red/yellow/green). [`FactionTemplate::reaction_toward`] is that
-//! function, branch-for-branch.
+//! A unit's `UNIT_FIELD_FACTIONTEMPLATE` indexes `FactionTemplate.dbc`, and the reference's
+//! comparator `0x606640` turns two rows into hostile, neutral or friendly; every `UnitReaction`,
+//! `CanAttack` and `CanAssist` bottoms out in it. It is only the DBC half of `UnitReaction`
+//! (`0x6061e0`), whose group, charm, PvP-flag and sanctuary overrides need session state.
 //!
-//! Record layout verified by the offsets the comparator reads (0x38-byte rows = 14 × u32, matching
-//! vmangos `FactionTemplateEntry`): id@0, faction@1 (Faction.dbc id), flags@2, factionGroupMask@3,
-//! friendGroupMask@4, enemyGroupMask@5, enemies[4]@6..9, friends[4]@10..13 (both id lists
-//! 0-terminated).
-//!
-//! Also here: the **reputation identity** side of the decode — Faction.dbc's reputation slot,
-//! parent pointer and race/class-gated base values ([`FactionInfo`]), the standing→rank thresholds
-//! ([`reputation_rank`]), and the names of the wire flag byte's bits ([`faction_flags`]). The client
-//! checks `FactionHasReputation` *before* the comparator (`0x606530`): a reputation faction's NPCs
-//! colour by the player's rank, not by templates. The live standings are session state
-//! (`SMSG_INITIALIZE_FACTIONS`) and live with the net layer.
-//!
-//! Two consumers share that identity now — the reaction decode above, and the **reputation pane**
-//! (decision 1258, whose display law is `benilla-ui`'s `script::reputation`). Where both need the
-//! same number they take it from the same function here, so a rank the pane draws and a colour the
-//! nameplate paints can never disagree.
-//!
-//! Deliberately **not** here: the rest of the real `UnitReaction 0x6061e0` orchestration —
-//! same-object/group/guild shortcuts, charm resolution, PvP-flag + sanctuary overrides. Those need
-//! player/session state, not DBC rows; they land with the systems that own it.
+//! Also `Faction.dbc`'s reputation identity: the reference checks `FactionHasReputation` before the
+//! comparator (`0x606530`), so a reputation faction's NPCs colour by the player's rank.
 
 use std::collections::HashMap;
 
@@ -40,17 +20,14 @@ const FACTION_TEMPLATE: &str = "DBFilesClient\\FactionTemplate.dbc";
 const FACTION: &str = "DBFilesClient\\Faction.dbc";
 const FACTION_GROUP: &str = "DBFilesClient\\FactionGroup.dbc";
 
-/// One FactionTemplate.dbc row — exactly the fields the reaction comparator reads (plus `faction`,
-/// which the id-list scans compare against).
+/// One `FactionTemplate.dbc` row: the fields the reaction comparator reads.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct FactionTemplate {
-    /// The row's `Faction.dbc` id — what another template's `enemies`/`friends` lists name.
+    /// The row's `Faction.dbc` id, what another template's `enemies`/`friends` lists name.
     pub faction: u32,
     /// The faction-group bits this template belongs to (Player/Alliance/Horde/Monster).
     pub group_mask: u32,
-    /// Faction groups this template is friendly toward.
     pub friend_group_mask: u32,
-    /// Faction groups this template is hostile toward.
     pub enemy_group_mask: u32,
     /// Explicit enemy `Faction.dbc` ids, 0-terminated.
     pub enemies: [u32; 4],
@@ -58,9 +35,8 @@ pub struct FactionTemplate {
     pub friends: [u32; 4],
 }
 
-/// A unit's base reaction toward another, on the client's own scale (`0x606640` returns exactly
-/// these three; the extended reputation path widens the scale to 0..7, hence the gaps). The
-/// nameplate/ring palette thresholds on this scale: `<= 1` red, `>= 4` green, else yellow.
+/// A unit's base reaction toward another on the reference's scale: `0x606640` returns these three,
+/// and the reputation path widens the scale to 0..7, hence the gaps.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum Reaction {
     Hostile = 1,
@@ -69,16 +45,9 @@ pub enum Reaction {
 }
 
 impl FactionTemplate {
-    /// The real client's faction-template reaction comparator — `self`'s reaction toward `other`.
-    ///
-    /// Branch-for-branch the byte-verified `0x606640` (wow-5875-re object-layer w2d1, §5): enemy
-    /// group mask, then the enemies id list, then friendship *both ways* (self's friend mask/list
-    /// toward other, then other's friend mask/list toward self), else neutral. Hostility is only
-    /// ever **self's** — and that asymmetry is load-bearing: a player template is enemy-masked
-    /// against the whole Monster group (why you *may attack* a yellow beast), while a starter-zone
-    /// kobold's template carries no enemy data at all. Colour by the **unit's** reaction toward the
-    /// player — the direction the nameplate resolver `0x7cbaa0` verifiably calls (`this` = the unit)
-    /// — or every wild beast would wrongly read hostile red.
+    /// `self`'s reaction toward `other`, branch for branch `0x606640`. Hostility is only ever
+    /// `self`'s, so colour by the unit's reaction toward the player, as the nameplate resolver
+    /// `0x7cbaa0` does: a player template is enemy-masked against the whole Monster group.
     pub fn reaction_toward(&self, other: &FactionTemplate) -> Reaction {
         if self.enemy_group_mask & other.group_mask != 0 {
             return Reaction::Hostile;
@@ -117,53 +86,29 @@ impl FactionTemplate {
     }
 }
 
-/// One Faction.dbc row's reputation identity: the reputation-list slot plus the race/class-gated
-/// base values the client adds to the wire standing. Only rows with `rep_index >= 0` participate in
-/// reputation (`FactionHasReputation`, the client's `[faction+4] >= 0` check).
+/// One `Faction.dbc` row's reputation identity: its list slot and the race/class-gated base values
+/// the reference adds to the wire standing.
 #[derive(Debug, Clone, Copy)]
 pub struct FactionInfo {
-    /// `reputationIndex` — the slot into the `SMSG_INITIALIZE_FACTIONS` standings array; `-1` = this
-    /// faction has no reputation (reaction falls through to the template comparator).
+    /// `reputationIndex`, the slot in the `SMSG_INITIALIZE_FACTIONS` standings, or -1 for none
+    /// (`FactionHasReputation` tests `[faction+4] >= 0`).
     pub rep_index: i32,
-    /// `Faction.dbc` field 18 — `team` in mangos, `m_parentFactionID` in the later builds' WDB
-    /// names. The **parent pointer**: Stormwind/Ironforge/Darnassus/Gnomeregan Exiles all carry 469
-    /// (Alliance), the four Steamwheedle towns carry 169, the six battleground factions carry
-    /// 891/892, and `0` means no parent. It is the only tree edge 1.12's `Faction.dbc` has.
-    ///
-    /// It is the reputation pane's **grouping key**, but *not* what makes a row a header — that is
-    /// the wire flag byte's [`faction_flags::HEADER`] bit. The distinction matters because the
-    /// client synthesizes a header for a group key that has no header row yet, and because two of
-    /// the pane's headers (`0` "Other" and `-1` "Inactive") name no faction at all.
+    /// `Faction.dbc` field 18 (`team` in mangos): the parent faction, 0 for none, the only tree
+    /// edge the 1.12 table has and the reputation pane's grouping key. A row is a header by
+    /// [`faction_flags::HEADER`], not by being a parent.
     pub team: u32,
     race_masks: [u32; 4],
     class_masks: [u32; 4],
     base: [i32; 4],
-    /// Per-slot reputation flags — bit `0x4` (mangos `FACTION_FLAG_HIDDEN`) on the matched slot
-    /// suppresses the unit tooltip's faction-name line.
+    /// Per-slot `ReputationFlags`; `0x4` on the matched slot hides the unit tooltip's faction line.
     flags: [u32; 4],
 }
 
 impl FactionInfo {
-    /// The race/class-gated slot the **client** picks for a player of `race`/`class` (1-based ids),
-    /// or `None` if no slot fits.
-    ///
-    /// `None` is not merely "no base value": it is the reputation pane's **membership gate** — the
-    /// client's list build calls its add inside this loop's accept block (`0x4d5555`), so a faction
-    /// no slot fits is not in the player's list at all.
-    ///
-    /// Byte-verified at `0x4d5500`–`0x4d5564` (wow-5875-re
-    /// `system/ui/scratch/reputation-panel-law.md`), and it differs from vmangos's `GetIndexFitTo`
-    /// in **two** ways that this project got wrong first time by reading the emulator instead:
-    ///
-    /// 1. A slot with **both** masks zero is a **reject**, not a double wildcard (`0x4d550b`). Only
-    ///    one of the two may be zero-as-wildcard.
-    /// 2. The loop has **no early exit** — the **last** matching slot wins, not the first.
-    ///
-    /// On the shipped 1.12 `Faction.dbc` the distinction is invisible: over all 190 rows × 72 valid
-    /// race/class pairs, zero of the 13,680 evaluations disagree with the first-match rule (no row
-    /// has a both-zero slot with a non-zero base, and none has two matching slots with different
-    /// bases). It is written the client's way regardless, because a rule that is right only for the
-    /// data we happen to ship is not a rule — a patched DBC would diverge silently.
+    /// The slot the reference (`0x4d5500`..`0x4d5564`) picks for a `race`/`class`, both 1-based.
+    /// `None` also keeps the faction out of the reputation pane, whose list build adds a faction
+    /// only in this loop's accept block (`0x4d5555`). Unlike vmangos's `GetIndexFitTo`, a slot
+    /// with both masks zero is rejected (`0x4d550b`), and the last matching slot wins.
     pub fn slot_for(&self, race: u8, class: u8) -> Option<usize> {
         let race_mask = 1u32 << (race.max(1) - 1);
         let class_mask = 1u32 << (class.max(1) - 1);
@@ -175,32 +120,22 @@ impl FactionInfo {
         })
     }
 
-    /// The base reputation for a player of `race`/`class` — the [`Self::slot_for`] slot's value,
-    /// `0` if none fits. This is the term the wire standing EXCLUDES: the total a rank is taken
-    /// from is this plus the wire value (byte-verified at `0x4d6370`: `wire + base`, and each
-    /// addend has exactly one writer image-wide).
+    /// The base reputation for a player of `race`/`class`, 0 if no slot fits. The wire standing
+    /// excludes it: a rank is taken from `wire + base` (`0x4d6370`).
     pub fn base_for(&self, race: u8, class: u8) -> i32 {
         self.slot_for(race, class).map_or(0, |i| self.base[i])
     }
 
-    /// The DBC's **default** reputation flag byte for a player of `race`/`class` — the same slot
-    /// pick as [`Self::base_for`], reading the `ReputationFlags` column instead of the base
-    /// (vmangos `ReputationMgr::GetDefaultStateFlags`). `0` if no slot fits.
-    ///
-    /// **The client never reads this column** (a byte-verified negative — the flag byte it displays
-    /// from is entirely the wire's). It is the *server's* seed for a fresh character's per-slot
-    /// state, and it is read here only to say what a faction is by default: notably that exactly
-    /// the pane's five header factions carry [`faction_flags::HEADER`].
+    /// The `ReputationFlags` column for a player of `race`/`class`, 0 if no slot fits: the server's
+    /// seed for a new character's flag byte (vmangos `ReputationMgr::GetDefaultStateFlags`). The
+    /// reference never reads this column; the byte it displays is the wire's.
     pub fn default_flags_for(&self, race: u8, class: u8) -> u32 {
         self.slot_for(race, class).map_or(0, |i| self.flags[i])
     }
 
-    /// Whether the unit tooltip shows this faction's name to a player of `race`/`class` — the
-    /// byte loop in the unit builder `0x529fe0`: the FIRST of the four reputation slots that
-    /// matches decides, and it shows the line iff its flags lack the hidden bit `0x4`. The slot
-    /// match differs from [`Self::base_for`]'s in one spot the bytes insist on: a zero race mask
-    /// substitutes the CLASS mask as the match value, so a slot with both masks zero matches
-    /// nothing here (while `base_for` treats it as a wildcard). No matching slot → no line.
+    /// Whether the unit tooltip shows this faction's name to a player of `race`/`class`: the unit
+    /// builder `0x529fe0` takes the first matching slot, not the last, and shows the line unless
+    /// its flags carry `0x4`. A zero race mask matches on the class mask instead.
     pub fn tooltip_shows_for(&self, race: u8, class: u8) -> bool {
         let race_bit = 1u32 << (race.max(1) - 1);
         let class_bit = 1u32 << (class.max(1) - 1);
@@ -219,11 +154,9 @@ impl FactionInfo {
     }
 }
 
-/// Reputation rank thresholds (vanilla): total standing (base + wire) → rank `0..=7` (hated,
-/// hostile, unfriendly, neutral, friendly, honored, revered, exalted). The rank scale **is** the
-/// client's extended reaction scale — the ring/nameplate palette thresholds apply to it directly
-/// (`<= 1` red, `>= 4` green, else yellow). Rank widths from the bottom (−42000): 36000, 3000,
-/// 3000, 3000, 6000, 12000, 21000, 1000 (vmangos `PointsInRank`, matching the client).
+/// Total standing (base + wire) to rank 0..=7, hated to exalted, which is also the reference's
+/// extended reaction scale. Widths from −42000: 36000, 3000, 3000, 3000, 6000, 12000, 21000, 1000
+/// (vmangos `PointsInRank`).
 pub fn reputation_rank(total_standing: i32) -> u8 {
     match total_standing {
         i32::MIN..=-6001 => 0, // hated
@@ -237,54 +170,31 @@ pub fn reputation_rank(total_standing: i32) -> u8 {
     }
 }
 
-/// The per-slot reputation flag byte the server keeps for each of the player's factions and sends
-/// as the first field of every `SMSG_INITIALIZE_FACTIONS` entry.
-///
-/// **Named from the CLIENT's own reads, not from the emulators' enum** (wow-5875-re
-/// `system/ui/scratch/reputation-panel-law.md`, byte-verified: the thirteen accesses to the store at
-/// `0xb73294` are the complete image-wide population). That distinction is not pedantry — the two
-/// disagree on bit `0x08`, which every emulator calls `INVISIBLE_FORCED` and the client tests as
-/// **HEADER** (`entry.isHeader = (flags >> 3) & 1`, `0x4d5acb`). Believing the emulator's name gets
-/// the *right rows* on screen for the wrong reason (the five factions carrying it are exactly the
-/// pane's headers, so "hide these" and "these are headers" pick the same set) and then gets the
-/// header machinery wrong everywhere it matters.
-///
-/// The same bit layout appears in `Faction.dbc`'s four `ReputationFlags` columns, which is where the
-/// **server** seeds a slot's initial byte from (`ReputationMgr::GetDefaultStateFlags`). The client
-/// never reads that column — the byte it displays from is entirely the wire's.
-///
-/// Two of these the client also *writes*, optimistically, because neither send is acked: [`AT_WAR`]
-/// and [`INACTIVE`].
+/// The per-faction flag byte, the first field of each `SMSG_INITIALIZE_FACTIONS` entry, named from
+/// the reference's own reads of its store (`0xb73294`), not from the emulators' enum. The reference
+/// writes [`AT_WAR`] and [`INACTIVE`] itself, optimistically, since neither send is acked.
 pub mod faction_flags {
-    /// The faction is listed in the reputation pane at all. Off until the player first meets them;
-    /// the server lifts it and pushes `SMSG_SET_FACTION_VISIBLE`. The **only** flag gating list
-    /// membership.
+    /// Listed in the reputation pane, the only flag that gates membership; the server sets it on
+    /// first contact and sends `SMSG_SET_FACTION_VISIBLE`.
     pub const VISIBLE: u8 = 0x01;
     /// The player has declared war on this faction.
     pub const AT_WAR: u8 = 0x02;
-    /// Suppresses the auto-reveal on a standing change and the rank-change chat notification. It
-    /// does **not** hide the row: a faction with this bit and [`VISIBLE`] is listed normally.
+    /// Suppresses the standing-change auto-reveal and rank-change chat line; the row stays listed.
     pub const HIDDEN: u8 = 0x04;
-    /// **This row is a header.** Not "force-invisible" — see the module doc; the client's own test
-    /// is `(flags >> 3) & 1` at `0x4d5acb`. The five factions that carry it (Alliance, Horde,
-    /// Steamwheedle Cartel, and the two battleground blocs) are the pane's header rows.
+    /// The row is a header (`(flags >> 3) & 1`, `0x4d5acb`), a bit the emulators name
+    /// `INVISIBLE_FORCED`. The five factions carrying it are the pane's header rows.
     pub const HEADER: u8 = 0x08;
-    /// Overrides [`AT_WAR`]: war can never be declared, so the pane's box is disabled. Your own
-    /// side's city factions carry it.
+    /// Overrides [`AT_WAR`]: war can never be declared; your own side's cities carry it.
     pub const PEACE_FORCED: u8 = 0x10;
-    /// The player moved this faction to the pane's inactive bucket — which re-parents the row under
-    /// the synthetic "Inactive" header, rather than hiding it.
+    /// In the pane's inactive bucket, under the synthetic "Inactive" header rather than hidden.
     pub const INACTIVE: u8 = 0x20;
-    /// The two competing factions of a rival pair. **The 1.12 client never tests this bit** — it is
-    /// here to name the byte completely, not because anything reads it.
+    /// One of a rival pair; the 1.12 client never tests this bit.
     pub const RIVAL: u8 = 0x40;
 }
 
 impl Reaction {
-    /// A reputation rank (`0..=7`, [`reputation_rank`]) collapsed to the three-way scale, the way
-    /// the **nameplate** palette thresholds it (`0x7cbaa0`: `<= 1` hostile, `>= 4` friendly, else
-    /// neutral). The selection **ring** does *not* collapse — its own palette (`0x605960`) keys the
-    /// raw rank and has a distinct orange at rank 2 — so ring consumers use the rank directly.
+    /// A rank (0..=7) collapsed to three, as the nameplate palette `0x7cbaa0` does. The selection
+    /// ring's palette (`0x605960`) keys the raw rank instead, with its own orange at 2.
     pub fn from_rank(rank: u8) -> Reaction {
         match rank {
             0..=1 => Reaction::Hostile,
@@ -294,60 +204,44 @@ impl Reaction {
     }
 }
 
-/// FactionTemplate.dbc + Faction.dbc + FactionGroup.dbc loaded into id → row maps (the template id
-/// is what a unit's `UNIT_FIELD_FACTIONTEMPLATE` carries; the faction id is the template's
-/// `faction` field; the group names key by mask bit).
+/// `FactionTemplate.dbc`, `Faction.dbc` and `FactionGroup.dbc` as id-to-row maps.
 pub struct FactionCatalog {
     templates: HashMap<u32, FactionTemplate>,
     factions: HashMap<u32, FactionInfo>,
-    /// `1 << FactionGroup.MaskID` → the localized group Name ("Alliance", "Horde") — what
-    /// `GetZonePVPInfo`'s territory line formats (`0x48d540` reads FactionGroup.dbc Name of the
-    /// row whose bit ∈ the zone's FactionGroupMask; wow-re ui `zonetext-pvpinfo.md`).
+    /// `1 << MaskID` to the localized group name, `GetZonePVPInfo`'s territory line (`0x48d540`).
     group_names: HashMap<u32, String>,
-    /// The same key → FactionGroup.dbc's **`InternalName`** (field 2), which is English on every
-    /// locale where `Name0` is not. Kept beside the localized map rather than derived from it
-    /// because `UnitFactionGroup` returns BOTH and they are not interchangeable: its first return
-    /// names a TEXTURE — stock builds `"Interface\TargetingFrame\UI-PVP-"..factionGroup`
-    /// (`PlayerFrame.lua:68`, `TargetFrame.lua:198`, `PartyMemberFrame.lua:125`) and
-    /// `"…\Battleground-"..UnitFactionGroup("player")` (`BattlefieldFrame.lua:195`) — so a
-    /// localized string there is a path that does not exist. `HonorFrame.lua:68` compares it to
-    /// the literal `"Alliance"` for the same reason.
+    /// The same key to `InternalName` (field 2), English on every locale: `UnitFactionGroup`'s
+    /// first return, which stock FrameXML concatenates into texture paths (`PlayerFrame.lua:68`).
     group_internal_names: HashMap<u32, String>,
-    /// Faction id → the localized Name — what the item tooltip's "Requires <Faction> -
-    /// <Standing>" line prints.
+    /// Faction id to localized name, for the item tooltip's "Requires <Faction> - <Standing>".
     names: HashMap<u32, String>,
-    /// Faction id → the localized Description — the paragraph the reputation pane's detail popup
-    /// prints under the faction name. Absent for most rows: only the pane's own factions carry one.
+    /// Faction id to localized description, the reputation pane's detail paragraph; most have none.
     descriptions: HashMap<u32, String>,
 }
 
 impl FactionCatalog {
-    /// The template row for a `UNIT_FIELD_FACTIONTEMPLATE` id, or `None` for an id the DBC lacks.
+    /// The template row for a `UNIT_FIELD_FACTIONTEMPLATE` id.
     pub fn template(&self, id: u32) -> Option<&FactionTemplate> {
         self.templates.get(&id)
     }
 
-    /// The reputation identity of a `Faction.dbc` id, `Some` only when the faction actually has a
-    /// reputation slot — the client's `FactionHasReputation` (`0x605fc0`, `[faction+4] >= 0`). For
-    /// these factions unit reaction is the **player's reputation rank**, checked *before* the
-    /// template comparator (`0x606530`).
+    /// A `Faction.dbc` id's reputation identity, `Some` only with a reputation slot: the
+    /// reference's `FactionHasReputation` (`0x605fc0`), tested before the comparator (`0x606530`).
     pub fn reputation_faction(&self, faction_id: u32) -> Option<&FactionInfo> {
         self.factions.get(&faction_id).filter(|f| f.rep_index >= 0)
     }
 
-    /// The localized name of a `Faction.dbc` id — the reputation-requirement line's faction.
+    /// The localized name of a `Faction.dbc` id.
     pub fn faction_name(&self, faction_id: u32) -> Option<&str> {
         self.names.get(&faction_id).map(String::as_str)
     }
 
-    /// The localized description of a `Faction.dbc` id — the reputation pane's detail paragraph.
-    /// `None` where the DBC leaves it empty, which is most non-pane factions.
+    /// The localized description of a `Faction.dbc` id, the reputation pane's detail paragraph.
     pub fn faction_description(&self, faction_id: u32) -> Option<&str> {
         self.descriptions.get(&faction_id).map(String::as_str)
     }
 
-    /// Every faction that has a reputation slot, with its identity — the app builds the
-    /// player's faction → rank map from this (base + wire standing, ranked).
+    /// Every faction with a reputation slot, with its identity.
     pub fn reputation_factions(&self) -> impl Iterator<Item = (u32, &FactionInfo)> {
         self.factions
             .iter()
@@ -355,11 +249,9 @@ impl FactionCatalog {
             .map(|(&id, f)| (id, f))
     }
 
-    /// The localized FactionGroup name of the (first) group bit set in `mask` — "Alliance" for 2,
-    /// "Horde" for 4; `None` for an unowned mask. The `GetZonePVPInfo` territory-line lookup.
-    /// The **English** group name for a mask — FactionGroup.dbc's `InternalName`. This is the one
-    /// `UnitFactionGroup`'s FIRST return must carry, because callers concatenate it into a texture
-    /// path; [`Self::faction_group_name`] is the localized twin for the second return.
+    /// The English `InternalName` of the first group bit in `mask`: `UnitFactionGroup`'s first
+    /// return, which callers build texture paths from. [`Self::faction_group_name`] is the
+    /// localized second return and the `GetZonePVPInfo` territory name.
     pub fn faction_group_internal_name(&self, mask: u32) -> Option<&str> {
         (0..32)
             .map(|b| 1u32 << b)
@@ -376,19 +268,18 @@ impl FactionCatalog {
             .map(String::as_str)
     }
 
-    /// Number of template rows (for logging/diagnostics).
+    /// Number of template rows.
     pub fn len(&self) -> usize {
         self.templates.len()
     }
 
-    /// Whether no rows loaded.
     pub fn is_empty(&self) -> bool {
         self.templates.is_empty()
     }
 }
 
-/// FactionTemplate.dbc — 14 fields in build 5875 (`14 × 4 == 56`-byte records, the exact offsets the
-/// client comparator reads; cross-checked with vmangos `FactionTemplateEntry`).
+/// `FactionTemplate.dbc`: 14 fields, 56-byte rows at the offsets `0x606640` reads (vmangos
+/// `FactionTemplateEntry`).
 fn faction_template_schema() -> Schema {
     let mut s = Schema::new("FactionTemplate");
     for (name, ty) in [
@@ -410,9 +301,7 @@ fn faction_template_schema() -> Schema {
     s
 }
 
-/// Faction.dbc — 37 fields in build 5875 (`ID`, `reputationIndex`, 4× race masks, 4× class masks,
-/// 4× base values, 4× reputation flags, `team`, then 8+1 name and 8+1 description columns;
-/// cross-checked with vmangos `FactionEntry` and the file header). We read the reputation identity.
+/// `Faction.dbc`: 37 fields in build 5875 (vmangos `FactionEntry`).
 fn faction_schema() -> Schema {
     let mut s = Schema::new("Faction");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -441,9 +330,8 @@ fn faction_schema() -> Schema {
     s
 }
 
-/// FactionGroup.dbc — 12 fields in build 5875 (48-byte records: `ID`, `MaskID` (the bit index),
-/// an internal name, then the 8+1 localized Name block; layout per the `GetZonePVPInfo` reader
-/// `0x48d540` — MaskID@+0x4, Name@+0xc — wow-re ui `zonetext-pvpinfo.md`).
+/// `FactionGroup.dbc`: 12 fields, 48-byte rows; `MaskID` is a bit index, read by `0x48d540` at
+/// `+0x4` with the name at `+0xc`.
 fn faction_group_schema() -> Schema {
     let mut s = Schema::new("FactionGroup");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -456,7 +344,7 @@ fn faction_group_schema() -> Schema {
     s
 }
 
-/// Load FactionTemplate.dbc + Faction.dbc from the patch chain into a [`FactionCatalog`].
+/// Load the three faction tables off the patch chain.
 pub fn load_faction_catalog(chain: &mut Chain) -> Result<FactionCatalog> {
     let bytes = chain
         .read_file(FACTION_TEMPLATE)
@@ -502,12 +390,11 @@ pub fn load_faction_catalog(chain: &mut Chain) -> Result<FactionCatalog> {
                     flags: [at(14), at(15), at(16), at(17)],
                 },
             );
-            // Name0 (enUS) — column 19 after ID/RepIndex/4·race/4·class/4·base/4·flags/Team.
+            // Name0 (enUS), column 19: after the ID, the index, 16 slot columns and `Team`.
             if let Some(name) = crate::dbc::str_at(&rs, r, 19) {
                 names.insert(id, name);
             }
-            // Desc0 (enUS) — column 28, past the 8 name columns and their flag word. Empty for
-            // most rows, so this map is far smaller than `names` and is left unsized.
+            // Desc0 (enUS), column 28, past the name block; empty on most rows.
             if let Some(desc) = crate::dbc::str_at(&rs, r, 28) {
                 descriptions.insert(id, desc);
             }
@@ -524,8 +411,7 @@ pub fn load_faction_catalog(chain: &mut Chain) -> Result<FactionCatalog> {
         let (Some(mask_id), Some(name)) = (u32_at(r, 1), crate::dbc::str_at(&rs, r, 3)) else {
             continue;
         };
-        // Field 2 is `InternalName`, field 3 is `Name0` — see the schema above. Both are read
-        // because `UnitFactionGroup` returns the pair and only the localized half was kept before.
+        // Field 2 is `InternalName`, field 3 `Name0`; `UnitFactionGroup` returns both.
         if let Some(internal) = crate::dbc::str_at(&rs, r, 2) {
             group_internal_names.insert(1u32 << mask_id, internal);
         }
@@ -558,10 +444,7 @@ mod tests {
         }
     }
 
-    /// The comparator's full branch domain, in the byte order `0x606640` tests them: enemy mask,
-    /// enemies list (with its 0-terminator + 4-entry bound), friend mask (A), friends list (A),
-    /// friend mask (B toward A's group), friends list (B naming A), neutral fall-through — and
-    /// enemy-beats-friend precedence.
+    /// Every branch, in the order `0x606640` tests them, and enemy-beats-friend precedence.
     #[test]
     fn comparator_branch_domain() {
         let b = FactionTemplate {
@@ -569,42 +452,39 @@ mod tests {
             ..tpl(50)
         };
 
-        // (A.enemyGroupMask & B.group) != 0 → hostile.
         let a = FactionTemplate {
             enemy_group_mask: 0b0010,
             ..tpl(1)
         };
         assert_eq!(a.reaction_toward(&b), Reaction::Hostile);
 
-        // A.enemies[i] == B.faction → hostile (in the last slot: the loop scans all 4).
+        // A.enemies[i] == B.faction → hostile, found in the last of the four slots.
         let a = FactionTemplate {
             enemies: [7, 8, 9, 50],
             ..tpl(1)
         };
         assert_eq!(a.reaction_toward(&b), Reaction::Hostile);
 
-        // The enemies list is 0-terminated: a match *after* a 0 is never reached.
+        // The enemies list is 0-terminated: a match after a 0 is never reached.
         let a = FactionTemplate {
             enemies: [7, 0, 50, 0],
             ..tpl(1)
         };
         assert_eq!(a.reaction_toward(&b), Reaction::Neutral);
 
-        // (A.friendGroupMask & B.group) != 0 → friendly.
         let a = FactionTemplate {
             friend_group_mask: 0b0010,
             ..tpl(1)
         };
         assert_eq!(a.reaction_toward(&b), Reaction::Friendly);
 
-        // A.friends[i] == B.faction → friendly.
         let a = FactionTemplate {
             friends: [50, 0, 0, 0],
             ..tpl(1)
         };
         assert_eq!(a.reaction_toward(&b), Reaction::Friendly);
 
-        // (B.friendGroupMask & A.group) != 0 → friendly (friendship read both ways).
+        // Friendship is read both ways: B's friend mask covers A's group.
         let a = FactionTemplate {
             group_mask: 0b1000,
             ..tpl(1)
@@ -615,17 +495,15 @@ mod tests {
         };
         assert_eq!(a.reaction_toward(&b_friendly), Reaction::Friendly);
 
-        // B.friends[i] == A.faction → friendly.
         let b_names_a = FactionTemplate {
             friends: [1, 0, 0, 0],
             ..b
         };
         assert_eq!(tpl(1).reaction_toward(&b_names_a), Reaction::Friendly);
 
-        // Nothing matches → neutral.
         assert_eq!(tpl(1).reaction_toward(&b), Reaction::Neutral);
 
-        // Hostility is tested first: an enemy-mask hit wins over any friendship evidence.
+        // Hostility is tested first: an enemy-mask hit beats any friendship.
         let a = FactionTemplate {
             enemy_group_mask: 0b0010,
             friend_group_mask: 0b0010,
@@ -635,16 +513,8 @@ mod tests {
         assert_eq!(a.reaction_toward(&b_names_a), Reaction::Hostile);
     }
 
-    /// End-to-end on the **real** build-5875 DBC, in the direction the client colours by (the unit's
-    /// reaction toward the player — verified in the binary: the nameplate resolver `0x7cbaa0` calls
-    /// `unit->UnitReaction(activePlayer)`): a human player is faction template 1; Marshal Dughan (12)
-    /// reads friendly and the Chicken (31) neutral (the exact ring colours the wow-re apitrace
-    /// captured), a Defias Trapper (17) and mine Kobold Miner (26) hostile, and the starter-field
-    /// Kobold Vermin (25) **neutral** — the famous non-aggro yellow level-1 mob. That last one also
-    /// locks the direction: the *player's* template is enemy-masked against the whole Monster group,
-    /// so the reverse direction would wrongly read every yellow beast as hostile. Template ids are
-    /// the vmangos `creature_template.faction` rows. Guards the schema (a shifted column scrambles
-    /// every mask) and the comparator against ground truth.
+    /// Unit templates toward a human player (template 1), the direction `0x7cbaa0` colours by;
+    /// ids from vmangos `creature_template.faction`, expected colours from a reference capture.
     #[test]
     fn real_dbc_reactions_match_reference_capture() {
         let data = crate::wow_data_or_skip!();
@@ -679,15 +549,11 @@ mod tests {
             Reaction::Neutral,
             "Kobold Vermin (non-aggro starter kobold)"
         );
-        // The direction asymmetry itself: the player is hostile *toward* the vermin (attackable),
-        // while the vermin — what the ring colours by — is neutral toward the player.
+        // The player is hostile toward the vermin (attackable) while the vermin is neutral to it.
         assert_eq!(human_player.reaction_toward(tpl(25)), Reaction::Hostile);
 
-        // The reputation identity: Stormwind (faction 72, both guard templates 11 + 12 point at it)
-        // has reputation slot 19 with a human base of 4000 — friendly rank 4 at zero wire standing,
-        // which is why every Stormwind NPC is green to a human **before** any template comparison
-        // (even in GM mode — director-verified on the reference client). A critter faction (the
-        // Chicken's 28) has no reputation slot → the comparator path.
+        // Stormwind (faction 72) has slot 19 and a human base of 4000, friendly before any
+        // template comparison; the Chicken's faction 28 has no slot.
         let stormwind = cat
             .reputation_faction(72)
             .expect("Stormwind (72) has reputation");
@@ -695,26 +561,23 @@ mod tests {
         assert_eq!(stormwind.base_for(1, 1), 4000, "human base with Stormwind");
         assert_eq!(reputation_rank(stormwind.base_for(1, 1)), 4, "friendly");
         assert!(cat.reputation_faction(28).is_none(), "critter: no rep");
-        // Orc (race 2) base with Stormwind is hated (−42000): rank 0 → hostile red.
+        // Orc (race 2) base with Stormwind is hated (−42000): rank 0, hostile.
         assert_eq!(stormwind.base_for(2, 1), -42000);
         assert_eq!(reputation_rank(stormwind.base_for(2, 1)), 0);
 
-        // The unit tooltip's faction-name line (the `0x529fe0` tail): a Stormwind guard shows
-        // "Stormwind" to a human — the ref's Marshal McBride "Level 20 / Stormwind / PvP" shot.
+        // The unit tooltip (`0x529fe0`) shows "Stormwind" under a Stormwind guard to a human.
         assert_eq!(cat.faction_name(72), Some("Stormwind"));
         assert!(
             stormwind.tooltip_shows_for(1, 1),
             "Stormwind's matched slot is not rep-hidden for a human"
         );
-        // Players never get the line: the PLAYER,* factions carry no reputation slot, so the
-        // builder's rep-index gate drops it before the slot walk.
+        // Players never get the line: player factions have no reputation slot.
         assert!(
             cat.reputation_faction(tpl(1).faction).is_none(),
             "the human player faction has no reputation slot"
         );
     }
 
-    /// The rank thresholds (vanilla `PointsInRank`), exact at every boundary.
     #[test]
     fn reputation_rank_thresholds() {
         for (standing, rank) in [
@@ -737,7 +600,7 @@ mod tests {
         ] {
             assert_eq!(reputation_rank(standing), rank, "standing {standing}");
         }
-        // The palette mapping on the rank scale: <=1 red, >=4 green, else yellow.
+        // The nameplate's collapse: <= 1 hostile, >= 4 friendly, else neutral.
         assert_eq!(Reaction::from_rank(0), Reaction::Hostile);
         assert_eq!(Reaction::from_rank(1), Reaction::Hostile);
         assert_eq!(Reaction::from_rank(2), Reaction::Neutral);
@@ -746,10 +609,6 @@ mod tests {
         assert_eq!(Reaction::from_rank(7), Reaction::Friendly);
     }
 
-    /// The GameObject faction term (decision 0764), pinned on the real `FactionTemplate.dbc`: the
-    /// factions that shipped GameObjects actually carry, resolved **GO → player** (the direction
-    /// `0x606640` uses). A column slip here would silently blank ~7,563 shipped GO spawns, or fail
-    /// to blank them — so the two decisive rows are asserted by value. Skips without client data.
     #[test]
     fn real_gameobject_factions_resolve_toward_both_player_templates() {
         let data = crate::wow_data_or_skip!();
@@ -760,22 +619,17 @@ mod tests {
             cat.template(2).expect("Horde player template"),
         );
 
-        // 114 "monster" — what Deadmines' Factory Door and Stratholme's scenery portcullises carry.
-        // Hostile to BOTH sides, so `> 1` fails and the object is not highlightable for anyone.
+        // 114 "monster" (Deadmines' Factory Door): hostile to both, so no one can highlight it.
         let monster = cat.template(114).expect("FactionTemplate 114");
         assert_eq!(monster.reaction_toward(alliance), Reaction::Hostile);
         assert_eq!(monster.reaction_toward(horde), Reaction::Hostile);
 
-        // 35 — the levers/torches, and (the reason this matters) Arathi Basin's capture banners.
-        // FRIENDLY to both, so the faction gate must never touch them.
+        // 35 (levers, torches, Arathi Basin's banners): friendly to both, never gated.
         let usable = cat.template(35).expect("FactionTemplate 35");
         assert_eq!(usable.reaction_toward(alliance), Reaction::Friendly);
         assert_eq!(usable.reaction_toward(horde), Reaction::Friendly);
     }
 
-    /// The real 5875 FactionGroup table: the territory-line names resolve by mask bit — Alliance
-    /// mask 2, Horde mask 4, nothing for an unowned 0 (the `GetZonePVPInfo` lookup, wow-re ui
-    /// `zonetext-pvpinfo.md`). Skips without client data.
     #[test]
     fn real_faction_group_names_by_mask() {
         let data = crate::wow_data_or_skip!();
@@ -786,13 +640,6 @@ mod tests {
         assert_eq!(cat.faction_group_name(0), None);
     }
 
-    /// **`team` is the reputation pane's tree, on the real table.** 1.12's `Faction.dbc` has no
-    /// parent column — field 18 (`team`) is the only edge it carries — and every group the pane
-    /// draws a header for is a set of rows sharing one `team`. Asserted by value on the real DBC
-    /// because a one-column slip here would silently produce a flat list that still *renders*.
-    ///
-    /// The counts are the whole table's, so a future patch chain that changes them fails loudly
-    /// rather than quietly regrouping the pane. Skips without client data.
     #[test]
     fn real_reputation_factions_group_under_their_team() {
         let data = crate::wow_data_or_skip!();
@@ -813,9 +660,7 @@ mod tests {
         for id in [76 /* Orgrimmar */, 81, 68, 530] {
             assert_eq!(cat.reputation_faction(id).unwrap().team, 67, "faction {id}");
         }
-        // The Steamwheedle towns sit under the cartel itself (169) — a header that is also a
-        // reputation faction in its own right (slot 10), which is why "is a header" cannot be
-        // "has no reputation slot".
+        // The Steamwheedle towns sit under the cartel (169), a header with its own slot (10).
         for id in [21 /* Booty Bay */, 369, 470, 577] {
             assert_eq!(
                 cat.reputation_faction(id).unwrap().team,
@@ -824,15 +669,14 @@ mod tests {
             );
         }
         assert_eq!(cat.reputation_faction(169).unwrap().rep_index, 10);
-        // …and the parents themselves have no parent: they are the top of the tree.
         for id in [469, 67, 169] {
             assert_eq!(cat.reputation_faction(id).unwrap().team, 0, "faction {id}");
         }
-        // The pane's leftovers — Argent Dawn and the rest — carry no team at all.
+        // Argent Dawn and the other ungrouped factions carry no team.
         assert_eq!(cat.reputation_faction(529).unwrap().team, 0);
 
-        // Exactly five factions are named as a parent by somebody, and every one of them is a
-        // header the pane draws: Alliance, Horde, Steamwheedle Cartel, and the two BG blocs.
+        // Exactly five parents, each a pane header: Alliance, Horde, Steamwheedle Cartel and the
+        // two battleground blocs.
         let mut parents: Vec<u32> = cat
             .reputation_factions()
             .map(|(_, f)| f.team)
@@ -843,7 +687,6 @@ mod tests {
         parents.sort_unstable();
         assert_eq!(parents, [67, 169, 469, 891, 892]);
 
-        // The detail popup's paragraph comes off the same row, past the eight name columns.
         assert!(
             cat.faction_description(529)
                 .is_some_and(|d| d.starts_with("An organization focused on protecting Azeroth")),
diff --git a/crates/benilla-formats/src/footsteps.rs b/crates/benilla-formats/src/footsteps.rs
index ab609021..80b4d76f 100644
--- a/crates/benilla-formats/src/footsteps.rs
+++ b/crates/benilla-formats/src/footsteps.rs
@@ -1,27 +1,12 @@
-//! Footsteps: the terrain-type chain (decision 0070 slice 3) —
-//! `ground texture → GroundEffectTexture.TerrainType → TerrainType.SoundID ×
-//! CreatureSoundData.FootstepID → FootstepTerrainLookup → SoundEntries (dry | splash)`.
+//! Footsteps: ground texture → `GroundEffectTexture.TerrainType` → `TerrainType.SoundID`, joined
+//! with `CreatureSoundData.FootstepID` in `FootstepTerrainLookup` to a dry and a splash
+//! `SoundEntries` kit. `TerrainType.dbc` is `ID`, `Desc`, `FootstepSprayRun`, `FootstepSprayWalk`,
+//! `SoundID`, `Flags`: 11 rows, `SoundID` 1 to 9 (DustyGrass shares Grass's 6) and 0 for None.
 //!
-//! Layouts — VERIFIED against build 5875 (headers + row decodes, 2026-07-02):
-//! - `TerrainType` **11 × 6 × 24 B**: `ID, Desc(str), FootstepSprayRun, FootstepSprayWalk,
-//!   SoundID, Flags` — the full domain decoded: Dirt→1, Metallic→2, Stone→3, Snow→4, Wood→5,
-//!   Grass→6, Leaves→7, Sand→8, Soggy→9, DustyGrass→6, None→0.
-//! - `FootstepTerrainLookup` **179 × 5 × 20 B**: `ID, CreatureFootstepID, TerrainSoundID,
-//!   SoundID(dry), SoundIDSplash`. Spot-checks: class 8 × terrain-sound 2 (Metallic) →
-//!   650/1063; class 8 × 3 (Stone) → 653/1057.
-//! - `GroundEffectTexture` field 6 is the `TerrainType` FK (the clutter catalog reads the same
-//!   table for doodads and rightly skips doodad-less rows; footsteps need every row, so this
-//!   module re-reads it into its own map).
-//!
-//! Class semantics (data-verified 2026-07-02; class-0 gate byte-confirmed at `0x6233ec`,
-//! wow-re `benilla-pins.md` B11a): **class 7 is the humanoid/character class** — its ten rows
-//! are exactly the `CharacterMediumLarge*` kits; characters reach it through the ordinary
-//! display→sound data chain (`creature_sound`, the model fallback), never a code default.
-//! **Class 0 means "no footstep sounds"** — the client bails before any lookup; the lookup's
-//! class-0 rows are the Ancient Protector's stomps (kit 661), reached only by a *nonzero* class
-//! on its own row. A position with **no ground-effect layer is silent** — the client's sentinel
-//! is −1 and the kit lookup's signed bounds check rejects it (`0x458450`, B5-verified; the
-//! audible fingerprint is vanilla's famously quiet dirt roads).
+//! Class 7 is the character class (its rows are the `CharacterMediumLarge*` kits), reached through
+//! the display's sound data, never a code default. Class 0 means no footsteps: the reference bails
+//! before any lookup (`0x6233ec`). A position with no ground-effect layer is silent: its sentinel
+//! is -1, which the kit lookup's signed bounds check rejects (`0x458450`).
 
 use std::collections::HashMap;
 
@@ -35,19 +20,17 @@ use crate::dbc::{parse, str_at, u32_at};
 pub struct FootstepCatalog {
     /// `GroundEffectTexture` id → `TerrainType` id (every row, including doodad-less ones).
     effect_terrain: HashMap<u32, u32>,
-    /// `TerrainType` id → its `SoundID` class (the lookup's `TerrainSoundID` axis).
+    /// `TerrainType` id → its `SoundID` (the lookup's `TerrainSoundID` axis).
     terrain_sound: HashMap<u32, u32>,
-    /// `TerrainType` id → its `Flags` word. In the shipped 5875 data bit 0 is set on exactly
-    /// Snow (3) and Sand (7) — the leaves-footprints surfaces (the reporter-visible pair).
+    /// `TerrainType` id → its `Flags`; bit 0, the footprint bit, is set on Snow (3) and Sand (7).
     terrain_flags: HashMap<u32, u32>,
     /// `(CreatureFootstepID, TerrainSoundID)` → `(dry kit, splash kit)`.
     lookup: HashMap<(u32, u32), (u32, u32)>,
 }
 
 impl FootstepCatalog {
-    /// The `(dry, splash)` SoundEntries kits for a creature footstep class standing on the given
-    /// ground-effect layer. `None` = silence: no/unknown effect layer (the client's −1 sentinel,
-    /// module docs), or no lookup row for `(class, terrain)`.
+    /// The `(dry, splash)` `SoundEntries` kits for a footstep class on a ground-effect layer;
+    /// `None`, silence, for no layer or no row.
     pub fn resolve(&self, footstep_class: u32, effect_id: Option<u32>) -> Option<(u32, u32)> {
         self.resolve_terrain(
             footstep_class,
@@ -55,44 +38,35 @@ impl FootstepCatalog {
         )
     }
 
-    /// The same `(dry, splash)` answer from a `TerrainType` id **directly**, skipping the
-    /// `GroundEffectTexture` hop. This is the tail both legs of the client's down-ray share: the
-    /// ADT leg reaches a terrain id through the ground-effect layer, the WMO leg carries one in
-    /// the surface itself.
+    /// The same kits from a `TerrainType` id: the reference's down-ray reaches one through the
+    /// ground-effect layer on terrain and reads it off the surface in a WMO.
     pub fn resolve_terrain(&self, footstep_class: u32, terrain: u32) -> Option<(u32, u32)> {
         let sound_class = self.terrain_sound.get(&terrain).copied()?;
         self.lookup.get(&(footstep_class, sound_class)).copied()
     }
 
-    /// Does the ground under this effect layer take footprint decals? `TerrainType.Flags` bit 0
-    /// through the same effect→terrain chain the sounds ride (INTERIM reading, decision 1006:
-    /// bit 0 fits the shipped data — set on exactly Snow and Sand — pending the wow-re byte
-    /// verdict on the client's own gate). No/unknown effect layer = no prints.
+    /// Whether the ground under an effect layer takes footprints: `TerrainType.Flags` bit 0, the
+    /// bit the reference's footprint gate tests (`0x699e8e`). No layer, no prints.
     pub fn leaves_footprints(&self, effect_id: Option<u32>) -> bool {
         effect_id
             .and_then(|e| self.effect_terrain.get(&e))
             .is_some_and(|&t| self.terrain_leaves_footprints(t))
     }
 
-    /// The same `TerrainType.Flags` bit 0 gate from a terrain id **directly** — the form both legs
-    /// of the down-ray share, since the WMO leg carries a terrain id rather than an effect layer.
-    /// Set on exactly Snow (3) and Sand (7) in the shipped data; the unauthored WMO default
-    /// `10 "None"` is clear, which is why a building's floor takes no prints.
+    /// The footprint bit from a terrain id; the WMO default, 10 "None", is clear, so a building's
+    /// floor takes no prints.
     pub fn terrain_leaves_footprints(&self, terrain: u32) -> bool {
         self.terrain_flags
             .get(&terrain)
             .is_some_and(|flags| flags & 1 != 0)
     }
 
-    /// The `TerrainType` id under a ground-effect layer — the chain's first hop on its own.
-    /// Exposed for the `surface_here` probe, which has to show *where* the chain lands, and where
-    /// it falls off, not just the kit it ends at.
+    /// The `TerrainType` id under a ground-effect layer, the chain's first hop.
     pub fn terrain_of(&self, effect_id: u32) -> Option<u32> {
         self.effect_terrain.get(&effect_id).copied()
     }
 
-    /// A `TerrainType`'s `SoundID` — the `FootstepTerrainLookup` axis the kit is chosen on.
-    /// Companion to [`Self::terrain_of`]; the same map [`Self::resolve`] walks.
+    /// A `TerrainType`'s `SoundID`, the `FootstepTerrainLookup` axis.
     pub fn sound_class_of(&self, terrain: u32) -> Option<u32> {
         self.terrain_sound.get(&terrain).copied()
     }
@@ -178,10 +152,8 @@ pub fn load_footstep_catalog(chain: &mut Chain) -> Result<FootstepCatalog> {
     })
 }
 
-/// `FootprintTextures.dbc` — id → texture path (extensionless, e.g.
-/// `textures\Footsteps\BaseFootprint`), the table `CreatureModelData.FootprintTextureID`
-/// indexes. Shipped 5875 data: 6 rows (1 Base, 3 Cloven, 4 Bare, 5 Claw, 6 Hoof, 7 Paw), all
-/// 32×32 pure-black-RGB BLPs under a soft alpha — the print decal's ink.
+/// `FootprintTextures.dbc`, id → extensionless texture path (`textures\Footsteps\BaseFootprint`),
+/// the table `CreatureModelData.FootprintTextureID` indexes.
 pub fn load_footprint_textures(chain: &mut Chain) -> Result<HashMap<u32, String>> {
     let bytes = chain
         .read_file("DBFilesClient\\FootprintTextures.dbc")
@@ -204,10 +176,7 @@ pub fn load_footprint_textures(chain: &mut Chain) -> Result<HashMap<u32, String>
 mod tests {
     use super::*;
 
-    /// The full chain resolves on real 5875 data: a Metallic-terrain effect under footstep
-    /// class 8 yields the byte-decoded kits (650 dry / 1063 splash); the humanoid class 7
-    /// resolves the `CharacterMediumLarge*` kits (560 Dirt with no effect, 562 Grass on a
-    /// grass-terrain effect — the character-in-Elwynn case); an unknown class stays silent.
+    /// The chain on 5875 data: class 8 on Metallic, and the character class on dirt and grass.
     #[test]
     fn real_footstep_chain_resolves() {
         let data = crate::wow_data_or_skip!();
@@ -215,7 +184,7 @@ mod tests {
         let cat = load_footstep_catalog(&mut chain).expect("load footstep catalog");
         assert_eq!(cat.len(), 179, "all lookup rows load");
 
-        // Some effect whose terrain is Metallic (TerrainType 1 → sound class 2).
+        // An effect over Metallic (`TerrainType` 1, sound 2).
         let metallic = cat
             .effect_terrain
             .iter()
@@ -228,8 +197,6 @@ mod tests {
                 "class 8 on metallic → the byte-decoded row"
             );
         }
-        // The humanoid class (7): the dirt kit on a dirt-terrain effect, the grass kit on a
-        // grass one (class 0 is the Ancient Protector, module docs).
         let effect_with_sound_class = |sc: u32| {
             cat.effect_terrain
                 .iter()
@@ -250,15 +217,12 @@ mod tests {
                 "class 7 on grass → CharacterMediumLargeGrass"
             );
         }
-        // No ground-effect layer = silence (the −1 sentinel, B5); unknown class too.
+        // No ground-effect layer, or an unknown class, is silent.
         assert_eq!(cat.resolve(7, None), None);
         assert_eq!(cat.resolve(9999, None), None);
     }
 
-    /// The footprint gate on the real data: `TerrainType.Flags` bit 0 is set on exactly Snow (3)
-    /// and Sand (7) — an effect layer over either takes prints, every other terrain (and the
-    /// no-layer sentinel) doesn't. And `FootprintTextures.dbc` decodes its six shipped rows to
-    /// the `textures\Footsteps\*` ink paths.
+    /// The footprint bit on 5875 data, Snow and Sand only, and the six `FootprintTextures` rows.
     #[test]
     fn footprint_gate_and_textures_on_real_data() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/game_tips.rs b/crates/benilla-formats/src/game_tips.rs
index 0a61b267..aab28d94 100644
--- a/crates/benilla-formats/src/game_tips.rs
+++ b/crates/benilla-formats/src/game_tips.rs
@@ -1,22 +1,8 @@
-//! `GameTips.dbc` — the loading-screen "tip of the day" (decision 2077).
-//!
-//! The 74 one-line hints the reference draws over a loading screen, each already carrying its own
-//! `|cffffd100Tip:|r` prefix and a trailing `\r\n` or two in the data. Nothing in FrameXML reads
-//! them — `showGameTips`' only 1.12 mention there is
-//! `UIOptionsFrameCheckButtons["SHOW_TIPOFTHEDAY_TEXT"] = { index = 44, cvar = "showGameTips" }`
-//! and the tooltip string "Uncheck this to hide the tip of the day in the load screens", so the
-//! whole feature is engine-side.
-//!
-//! **The table is the reference's own growable array** at `[0xc0dcd0]` (data) / `[0xc0dcd4]`
-//! (count), stride `0x28` = this record size, filled by the DBC loader `0x545f90` from the run of
-//! per-table loaders at `0x5404bb`. `CGlueMgr::EnterWorld` (`0x46b500`) walks the count at
-//! `0x46b684` and stores the chosen slot back into the `gameTip` CVar.
-//!
-//! Layout — the real 5875 file (10883 bytes, **74** records × 10 × u32, 7903-byte string block):
-//! `ID(0), Text[8](1..8), TextMask(9)` — the ordinary 1.12 localized-string shape, and only the
-//! first locale slot is populated in this chain. **Record order is not id order** (the file opens
-//! on id 396 and closes on 412, ids 201..412 with no duplicates), which is why the index the
-//! reference persists is a *record* index into the file as loaded, never an id.
+//! `GameTips.dbc`: the loading-screen tips, each with its own `|cffffd100Tip:|r` prefix and a
+//! trailing `\r\n` in the data; FrameXML never reads them. The reference loads them in file order
+//! into one array (`[0xc0dcd0]`, count `[0xc0dcd4]`, loader `0x545f90`), and
+//! `CGlueMgr::EnterWorld` (`0x46b500`) stores the chosen record index, never an id, in the
+//! `gameTip` CVar. Record order is not id order: the file opens on id 396.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -26,21 +12,19 @@ use crate::dbc::{parse, str_at};
 
 const GAME_TIPS: &str = "DBFilesClient\\GameTips.dbc";
 
-/// The tips, in the file's own record order — the order the reference's array holds them in, and
-/// so the order its persisted index counts through.
+/// The tips in file record order, the order the persisted `gameTip` index counts through.
 #[derive(Clone, Debug, Default)]
 pub struct GameTipsCatalog {
     tips: Vec<String>,
 }
 
 impl GameTipsCatalog {
-    /// A catalog over rows given directly — for a test that must run without an install.
+    /// A catalog over given tips, for a test without an install.
     pub fn from_tips(tips: Vec<String>) -> Self {
         GameTipsCatalog { tips }
     }
 
-    /// The tip at a **record index**, or `None` when the index is past the table (an index read
-    /// back from a config file written by a different chain).
+    /// The tip at a record index; an index saved under another chain can fall past the table.
     pub fn get(&self, index: usize) -> Option<&str> {
         self.tips.get(index).map(String::as_str)
     }
@@ -68,9 +52,7 @@ pub fn load_game_tips(chain: &mut Chain) -> Result<GameTipsCatalog> {
     let rs = parse(&bytes, schema(), "GameTips")?;
     let mut tips = Vec::with_capacity(rs.records().len());
     for r in rs.records() {
-        // A row whose localized slot is empty is dropped rather than kept as a blank: the
-        // reference's array is what the index counts through, and a blank slot would be a
-        // loading screen with no tip on it for no reason a player could act on.
+        // A row with an empty text slot is dropped, not shown blank; the shipped file has none.
         match str_at(&rs, r, 1) {
             Some(text) if !text.trim().is_empty() => tips.push(text),
             _ => {}
@@ -83,8 +65,6 @@ pub fn load_game_tips(chain: &mut Chain) -> Result<GameTipsCatalog> {
 mod tests {
     use super::*;
 
-    /// The shipped table: 74 tips, in file order, each already carrying the reference's own
-    /// colour prefix. Skips without client data.
     #[test]
     fn the_real_table_is_seventy_four_tips_in_file_order() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/gameobjects.rs b/crates/benilla-formats/src/gameobjects.rs
index 567a7401..b637b391 100644
--- a/crates/benilla-formats/src/gameobjects.rs
+++ b/crates/benilla-formats/src/gameobjects.rs
@@ -1,11 +1,5 @@
-//! GameObject display resolution: `displayId` → world model path.
-//!
-//! A GameObject's `GAMEOBJECT_DISPLAYID` indexes **GameObjectDisplayInfo.dbc**, whose `modelName`
-//! column is a direct path — mostly `.mdx`/`.mdl` (M2: chests, mailboxes, doodads) with a few `.wmo`
-//! (large structures). Unlike creatures there's no model-data indirection or skins, so the catalog is
-//! just `displayId → path`; the renderer dispatches the path through [`crate::load_object_model`].
-//!
-//! Layout verified against build 5875: 12 fields (ID@0, modelName@1 string, Sound[10]@2..11).
+//! `GameObjectDisplayInfo.dbc`: a game object's `GAMEOBJECT_DISPLAYID` → a direct model path,
+//! with no model-data indirection or skins; mostly `.mdx`/`.mdl`, a few `.wmo`.
 
 use std::collections::HashMap;
 
@@ -23,29 +17,24 @@ pub struct GameObjectCatalog {
 }
 
 impl GameObjectCatalog {
-    /// The model path for a GameObject display id (`.mdx`/`.mdl`/`.wmo`), or `None`.
     pub fn model_path(&self, display_id: u32) -> Option<&str> {
         self.models.get(&display_id).map(String::as_str)
     }
 
-    /// Number of display entries (diagnostics).
     pub fn len(&self) -> usize {
         self.models.len()
     }
 
-    /// Whether the catalog is empty.
     pub fn is_empty(&self) -> bool {
         self.models.is_empty()
     }
 
-    /// Every `(displayId, model path)` pair, unordered — the corpus-sweep entry point for "which
-    /// models can a GameObject ever be, and which display ids reach each one".
+    /// Every `(displayId, model path)` pair, in no order.
     pub fn iter(&self) -> impl Iterator<Item = (u32, &str)> {
         self.models.iter().map(|(&id, p)| (id, p.as_str()))
     }
 }
 
-/// GameObjectDisplayInfo.dbc — 12 fields in build 5875: ID, modelName, then 10 sound refs.
 fn schema() -> Schema {
     let mut s = Schema::new("GameObjectDisplayInfo");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -71,23 +60,20 @@ pub fn load_gameobject_catalog(chain: &mut Chain) -> Result<GameObjectCatalog> {
     Ok(GameObjectCatalog { models })
 }
 
-/// The per-display **sound-kit slots** (`Sound0..9` — the other 10 columns of the same table):
-/// `{0 Stand, 1 Open, 2 Loop, 3 Close, 4 Destroy, 5 Opened, 6..9 Custom}` → SoundEntries.
-/// Loaded separately from the model catalog so the audio consumer doesn't reach into the
-/// renderer's cache (decision 0070); only displays with at least one non-zero slot are kept
-/// (most of the 1638 rows are silent props).
+/// Each display's ten `SoundEntries` slots (columns 2-11): 0 stand, 1 open, 2 loop, 3 close,
+/// 4 destroy, 5 opened, 6-9 custom. Only displays with a nonzero slot are kept.
 pub struct GameObjectSounds {
     sounds: HashMap<u32, [u32; 10]>,
 }
 
-/// The `Sound[10]` slot indices with recorded meanings (wowdev, vanilla family).
+/// `Sound[10]` slot indices, named as wowdev documents them.
 pub mod go_sound_slot {
     pub const OPEN: usize = 1;
     pub const CLOSE: usize = 3;
 }
 
 impl GameObjectSounds {
-    /// The 10 sound-kit slots for a display id; `None` when the display has no sounds at all.
+    /// A display's ten slots; `None` when every slot is zero.
     pub fn slots(&self, display_id: u32) -> Option<&[u32; 10]> {
         self.sounds.get(&display_id)
     }
diff --git a/crates/benilla-formats/src/garble.rs b/crates/benilla-formats/src/garble.rs
index d9b66e6c..aaa15f46 100644
--- a/crates/benilla-formats/src/garble.rs
+++ b/crates/benilla-formats/src/garble.rs
@@ -1,83 +1,49 @@
-//! **The chat language scramble** — the reference's `0x49b560`, reimplemented.
+//! The chat language scramble, the reference's `0x49b560`: the server sends foreign speech in
+//! plaintext beside a language id, and the client garbles it.
 //!
-//! When someone speaks a language your character does not know, the *server* sends the sentence in
-//! plaintext with a language id beside it and never rewrites it; turning it into gibberish is
-//! entirely the client's job (B262 — opposite-faction speech rendered perfectly readable because
-//! this step did not exist). This module is that step.
-//!
-//! **The mechanism is byte-verified** in wow-re `system/ui/scratch/chat-language-scramble.md` — a
-//! §5 trio on the kernel plus two independent pairs, with an emulated oracle that runs the binary's
-//! own bytes over the player's own `LanguageWords.dbc`. [`tests::the_reference_golden_vectors`]
-//! carries all 35 of that note's golden vectors verbatim; they are the oracle this file is graded
-//! against, and the note's own claim is that its prose is *sufficient* — a clean-room
-//! implementation written from it reproduced every vector byte for byte. So did this one.
-//!
-//! The shape, in one paragraph. The line is walked as an alternating sequence of separator runs and
-//! words. Each word is hashed once with `SStrHash` (case-folded, so `hello`/`Hello`/`HELLO` share a
-//! hash and therefore a substitute); the *same* hash decides both whether that particular word is
-//! understood (`hash % 300 < skill` — a **per-word, graduated** gate, not an all-or-nothing switch)
-//! and, when it is not, which replacement is drawn from the `(language, byte length)` bucket of
-//! `LanguageWords.dbc`. The source word's capitalisation is then stamped onto the replacement one
-//! character at a time. Nothing is random and nothing is stateful: the mapping is a pure function
-//! of the word's bytes, stable within a session and across sessions.
-//!
-//! **Three call sites in the reference, and the flags are what separate them** ([`Garble`]):
-//! chat (`0x49aa7c`, both flags off), the NPC gossip greeting (`0x4e22ab`, `keep_punct`), and
-//! readable item text (`0x4e35b0`, both). So the same language barrier covers gossip and books —
-//! benilla only wires chat today, but the routine is the whole routine, not the chat slice of it.
+//! The line alternates separator runs and words. Each word is hashed once with case-folded
+//! `SStrHash`; it is understood when `hash % 300 < skill`, and otherwise the same hash picks a
+//! substitute of its byte length from `LanguageWords.dbc`, which takes the source's case letter
+//! by letter. The result is a pure function of the word's bytes. The three call sites differ only
+//! in [`Garble`]'s flags and cap: chat (`0x49aa7c`), the gossip greeting (`0x4e22ab`), item text
+//! (`0x4e35b0`).
 
 use crate::LanguageWords;
 
-/// `SStrHash`'s mix table — the **16-dword** table at `0x80e4e0`, not Storm's public 0x500-entry
-/// crypt table. Both nibbles of a byte index these same sixteen entries and the mix is a
-/// **subtraction**, `T[hi] - T[lo]`.
+/// `SStrHash`'s 16-entry mix table (`0x80e4e0`), not Storm's 0x500-entry crypt table: a byte
+/// mixes as `T[hi] - T[lo]`.
 const HASH_TABLE: [u32; 16] = [
     0x486e26ee, 0xdcaa16b3, 0xe1918eef, 0x202dafdb, 0x341c7dc7, 0x1c365303, 0x40ef2d37, 0x65fd5e49,
     0xd6057177, 0x904ece93, 0x1c38024f, 0x98fd323b, 0xe3061ae7, 0xa39b0fa1, 0x9797f25f, 0xe4444563,
 ];
 
-/// Full fluency (`0x49b599 cmp esi,0x12c`). At or above this the line is copied verbatim without
-/// even being tokenized; below it every word runs the per-word gate.
+/// Full fluency (`0x49b599`): at or above it the line is copied untokenized.
 pub const FLUENT_SKILL: u32 = 300;
 
-/// The per-word understand test's modulus (`0x49b79c div ecx=0x12c`). It is the same 300 as
-/// [`FLUENT_SKILL`] and that is not a coincidence — it makes the surviving fraction of a line
-/// exactly `skill / 300`.
+/// The per-word test's modulus (`0x49b79c`), so a line keeps about `skill / 300` of its words.
 const UNDERSTAND_MODULUS: u32 = 300;
 
-/// How many bytes of a word are copied into the reference's `0x110`-byte scratch buffer and
-/// therefore hashed (`0x49b768`).
+/// The bytes of a word copied into the reference's scratch buffer and hashed (`0x49b768`).
 const MAX_HASHED_BYTES: usize = 0x100;
 
-/// The **length key**'s clamp (`0x49b7c1`) — a separate quantity from [`MAX_HASHED_BYTES`], and a
-/// re-implementation must keep them apart: a 45-byte word is hashed over all 45 bytes but looked up
-/// as if it were 18 long. The shipped table's longest word is 17, so this never binds against
-/// shipped content; it is the retry below that does the work for a long word.
+/// The lookup length's clamp (`0x49b7c1`), apart from [`MAX_HASHED_BYTES`]: a 45-byte word hashes
+/// all 45 bytes and is looked up at length 18.
 const MAX_LENGTH_KEY: usize = 0x12;
 
-/// The two flags `0x49b560` takes, plus the destination cap — i.e. which of the reference's three
-/// call sites this is.
+/// The flags and destination cap `0x49b560` takes, one set per call site.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Garble {
-    /// `keepAngle` — pass a `<…>` span through verbatim, opener and closer included. Set only on
-    /// readable item text (`0x4e3856`).
+    /// `keepAngle`: pass a `<…>` span through verbatim, brackets included.
     pub keep_angle: bool,
-    /// `keepPunct` — copy each separator's own bytes instead of collapsing the whole run to one
-    /// space. Set on gossip (`0x4e22ab`) and item text; **off on the chat path**, which is why
-    /// `"hello, world."` comes back `"kazum magan "` with a trailing space.
+    /// `keepPunct`: copy separators instead of collapsing each run to one space; off for chat, so
+    /// `"hello, world."` comes back with a trailing space.
     pub keep_punct: bool,
-    /// `dstSize` — the reference's destination buffer, **total size not remaining**. Output is
-    /// truncated to `dst_size - 1` bytes.
+    /// `dstSize`, the whole destination buffer: output stops at `dst_size - 1` bytes.
     pub dst_size: usize,
 }
 
 impl Garble {
-    /// The chat path (`0x49aa7c` in the display chokepoint `0x49a870`): both flags off, `0x800`.
-    ///
-    /// The cap cannot bind on real chat — vmangos refuses a `CMSG_MESSAGECHAT` body past 255 bytes
-    /// and no server-composed line approaches 2 KiB — but it is the reference's number and modelling
-    /// it costs nothing, so a hostile or merely odd line truncates where the real client truncates
-    /// instead of somewhere of our own invention.
+    /// Chat (`0x49aa7c`, in the display path `0x49a870`).
     pub const CHAT: Self = Self {
         keep_angle: false,
         keep_punct: false,
@@ -91,7 +57,7 @@ impl Garble {
         dst_size: 0x800,
     };
 
-    /// Readable item text — letters and books (`0x4e3856`, then `ITEM_TEXT_READY`).
+    /// Readable item text, letters and books (`0x4e3856`, then `ITEM_TEXT_READY`).
     pub const ITEM_TEXT: Self = Self {
         keep_angle: true,
         keep_punct: true,
@@ -99,13 +65,8 @@ impl Garble {
     };
 }
 
-/// `SStrHash` (`0x64af90`) as `0x49b560` calls it: **case-folded** (`caseSensitive = 0`) with a zero
-/// seed.
-///
-/// The fold is ASCII-only — `a`-`z` lift by 0x20 and `/` becomes `\` — so a Latin-1 accented capital
-/// and its lowercase form hash differently, exactly as they do in the reference. The walk stops at a
-/// NUL because the reference's does; a wire chat string cannot contain one, but a caller composing
-/// text locally could.
+/// `SStrHash` (`0x64af90`), case-folded with a zero seed as `0x49b560` calls it. The fold is
+/// ASCII-only (`a`-`z` up, `/` to `\`), and the walk stops at a NUL, both as the reference does.
 fn sstr_hash_folded(bytes: &[u8]) -> u32 {
     let mut s1: u32 = 0x7FED_7FED;
     let mut s2: u32 = 0xEEEE_EEEE;
@@ -135,14 +96,11 @@ fn sstr_hash_folded(bytes: &[u8]) -> u32 {
     }
 }
 
-/// The sentinel `0x41aab0` returns for a malformed lead or continuation byte. It is `> 0xff`, so
-/// [`is_word_char`] swallows a malformed run into the surrounding word rather than splitting on it —
-/// a quirk worth preserving rather than "fixing", since it decides tokenization.
+/// `0x41aab0`'s malformed-byte sentinel; above 0xff, so a malformed run stays inside its word.
 const MALFORMED: u32 = 0x8000_0000;
 
-/// The reference's UTF-8 decoder `0x41aab0`, which predates RFC 3629 and so accepts the **1–6 byte**
-/// forms. Returns `(codepoint, bytes consumed)`; consumes one byte on a malformed lead so the walk
-/// always advances.
+/// The reference's UTF-8 decoder (`0x41aab0`), which accepts 1 to 6 byte forms; returns the
+/// codepoint and the bytes consumed, one when malformed.
 fn decode(bytes: &[u8]) -> (u32, usize) {
     let b0 = bytes[0];
     let (mut cp, n) = match b0 {
@@ -166,12 +124,7 @@ fn decode(bytes: &[u8]) -> (u32, usize) {
     (cp, n)
 }
 
-/// A Latin-1 letter as `0x6c9c60` classifies one.
-///
-/// Transcribed from the note's reading of the table rather than from what Latin-1 "should" say:
-/// `0xDE` (thorn) is **not** in the accepted set even though `0xC0..=0xDD`, `0xDF` and
-/// `0xE0..=0xFF` around it are. It cannot affect an ASCII line, and guessing the table is a worse
-/// error than transcribing it.
+/// A Latin-1 letter as `0x6c9c60`'s table classifies one, which leaves out `0xDE` (thorn).
 fn is_latin1_letter(cp: u32) -> bool {
     matches!(cp, 0x41..=0x5a | 0x61..=0x7a)
         || matches!(cp, 0xc0..=0xdd if cp != 0xd7)
@@ -179,36 +132,23 @@ fn is_latin1_letter(cp: u32) -> bool {
         || matches!(cp, 0xe0..=0xff if cp != 0xf7)
 }
 
-/// The word-character predicate `0x49b940`.
-///
-/// Three consequences that decide output and that a re-implementation guesses wrong: **digits are
-/// word characters**, so `12345` is one token and gets substituted like a word; **an apostrophe
-/// never splits a word**, so `don't` is one token; and **every codepoint above Latin-1 is
-/// unconditionally a word character**, so CJK, Cyrillic and a malformed byte run are all swallowed
-/// into words.
+/// The word-character predicate (`0x49b940`): digits, the apostrophe and every codepoint above
+/// Latin-1 are word characters.
 fn is_word_char(cp: u32) -> bool {
     is_latin1_letter(cp) || (0x30..=0x39).contains(&cp) || cp == 0x27 || cp > 0xff
 }
 
-/// Rewrite `src` as `language` sounds to a listener with `skill` in it.
-///
-/// Returns the text unchanged when `language` is 0 (Universal — `Languages.dbc` has no row 0, so the
-/// reference checks this twice, in the caller *and* here) or when `skill >= 300`. Everything else
-/// goes word by word.
-///
-/// The caller owns the gates this routine does not: the addon sentinel, the chat types that force
-/// the language to 0, and the GM flag. See `benilla-app`'s chat feed.
+/// `src` as `language` sounds to a listener with `skill` in it; unchanged for language 0
+/// (Universal) or full skill. The addon, chat-type and GM gates are the caller's.
 pub fn garble(words: &LanguageWords, language: u32, skill: u32, src: &str, mode: Garble) -> String {
     let cap = mode.dst_size.saturating_sub(1);
     if language == 0 || skill >= FLUENT_SKILL {
-        // `SStrCopy(dst, src, dstSize)` at `0x49b5a1` — the whole line, untokenized, so a
-        // fluent listener does not even get separator runs collapsed.
+        // `SStrCopy` at `0x49b5a1`: untokenized, so separator runs stay as they are.
         return truncate_utf8(src, cap).to_string();
     }
     let Some(pool) = words.pool(language) else {
-        // A language with no rows cannot be garbled — the reference would find no node at any
-        // length and drop every word, emitting nothing. We keep the line instead: a missing pool
-        // is a broken install, and silently blanking chat is the worse failure.
+        // Deviation: a language with no words keeps the line, where the reference drops every
+        // word, because a missing pool is a broken install and blank chat would hide it.
         return truncate_utf8(src, cap).to_string();
     };
 
@@ -217,8 +157,7 @@ pub fn garble(words: &LanguageWords, language: u32, skill: u32, src: &str, mode:
     let mut i = 0;
     while i < bytes.len() {
         // --- separator run ---------------------------------------------------------------
-        // One space per *run* on the chat path, latched per outer iteration: a leading run, a
-        // trailing run, `"    "`, `", "`, `"!!!"` and a tab all collapse to exactly one space.
+        // Chat collapses each separator run, leading and trailing included, to one space.
         let mut emitted_space = false;
         while i < bytes.len() {
             let (cp, n) = decode(&bytes[i..]);
@@ -263,19 +202,13 @@ pub fn garble(words: &LanguageWords, language: u32, skill: u32, src: &str, mode:
         let word = &bytes[word_start..i.min(word_start + MAX_HASHED_BYTES)];
         let hash = sstr_hash_folded(word);
 
-        // The per-word gate. This is the correction that matters most: partial skill is **not**
-        // "garbled like skill 0". A word survives exactly when `hash % 300 < skill`, so the
-        // surviving fraction of a line is `skill / 300` and *which* words survive is fixed by their
-        // bytes — at skill 150 a pangram comes back half-plain, the same half every time.
+        // The per-word gate: which words survive partial skill is fixed by their bytes.
         if hash % UNDERSTAND_MODULUS < skill {
             push(&mut out, word, cap);
             continue;
         }
 
-        // The length key steps *down* on a miss, and a length-1 miss drops the word entirely —
-        // nothing is emitted for it, not even a space. Unreachable against shipped content (every
-        // language has a word at every length from 1 up to its own maximum), reachable against a
-        // trimmed table.
+        // A miss retries one length shorter; a miss at length 1 drops the word, space and all.
         let mut key = word.len().min(MAX_LENGTH_KEY);
         let substitute = loop {
             if let Some(s) = pool.nth_of_len(key, hash) {
@@ -291,14 +224,11 @@ pub fn garble(words: &LanguageWords, language: u32, skill: u32, src: &str, mode:
         };
         stamp_case(&mut out, word, substitute.as_bytes(), cap);
     }
-    // Every substitute is ASCII and every verbatim span is a whole-codepoint slice of `src`, so the
-    // only way out of UTF-8 is the `0x100` hash clamp or the destination cap splitting a multi-byte
-    // character. Both are the reference's own truncations; we keep them and repair the encoding
-    // rather than moving the cut.
+    // Only the reference's own cuts, the hash clamp and the cap, can split a codepoint here.
     String::from_utf8_lossy(&out).into_owned()
 }
 
-/// The chat path, which is the one benilla wires today.
+/// [`garble`] on the chat path.
 pub fn garble_chat(words: &LanguageWords, language: u32, skill: u32, src: &str) -> String {
     garble(words, language, skill, src, Garble::CHAT)
 }
@@ -309,16 +239,8 @@ fn push(out: &mut Vec<u8>, bytes: &[u8], cap: usize) {
     out.extend_from_slice(&bytes[..room.min(bytes.len())]);
 }
 
-/// `0x49b8b0` — stamp the source word's capitalisation onto the substitute.
-///
-/// Two things a reader gets wrong if this is described as "capitalisation is preserved". The case is
-/// decided **per character, from the source**, not first-letter-only and not from the substitute:
-/// `hEllO` → `kAzuM`. And a non-letter in the source (a digit, an apostrophe) is not upper, so it
-/// forces the substitute's character **lowercase**.
-///
-/// The emitted length is `min(len(source), len(substitute), budget)`. Those first two are usually
-/// equal because the lookup is length-keyed — but not after a retry, which is exactly the long-word
-/// case: a 20-byte word looked up at length 13 emits 13 bytes.
+/// `0x49b8b0`: each character takes the case of the source's at the same position (`hEllO` to
+/// `kAzuM`), a non-letter forcing lowercase, for the shorter of the two words.
 fn stamp_case(out: &mut Vec<u8>, source: &[u8], substitute: &[u8], cap: usize) {
     for (i, &s) in source.iter().enumerate() {
         if i >= substitute.len() || out.len() >= cap {
@@ -332,8 +254,8 @@ fn stamp_case(out: &mut Vec<u8>, source: &[u8], substitute: &[u8], cap: usize) {
     }
 }
 
-/// Truncate to at most `cap` bytes without splitting a codepoint — the verbatim paths' `SStrCopy`,
-/// which is a byte copy in the reference and cannot produce invalid UTF-8 for us.
+/// The verbatim paths' `SStrCopy`, at most `cap` bytes. Deviation: it stops at a codepoint
+/// boundary where the reference's byte copy can split one, because a `&str` must stay UTF-8.
 fn truncate_utf8(s: &str, cap: usize) -> &str {
     if s.len() <= cap {
         return s;
@@ -350,12 +272,8 @@ mod tests {
     use super::*;
     use crate::{load_language_words, Chain};
 
-    /// **The oracle.** Every one of the 35 golden vectors from wow-re
-    /// `system/ui/scratch/chat-language-scramble.md` §9, produced by emulating the reference's own
-    /// `0x49b560` over the shipped `LanguageWords.dbc` — not transcribed from a description of the
-    /// output, but the exact bytes the binary wrote.
-    ///
-    /// `(language, skill, input, expected)`.
+    /// `(language, skill, input, expected)`: the reference's `0x49b560` output, emulated over the
+    /// shipped `LanguageWords.dbc`.
     const GOLDEN: &[(u32, u32, &str, &str)] = &[
         (1, 0, "hello", "kazum"),
         (1, 0, "h", "o"),
@@ -420,10 +338,6 @@ mod tests {
         }
     }
 
-    /// No per-call state anywhere: the same call repeats identically, and so does the same word in
-    /// a different sentence. (The reference's own oracle proves the second half across separately
-    /// built emulator "sessions"; ours is a pure function, so within-process repetition is the
-    /// strongest form the property can take here.)
     #[test]
     fn the_mapping_is_a_pure_function_of_the_words_bytes() {
         let data = crate::wow_data_or_skip!();
@@ -438,27 +352,22 @@ mod tests {
             .map(|&(l, s, i, _)| garble_chat(&words, l, s, i))
             .collect();
         assert_eq!(first, again);
-        // The same word carries its substitute between sentences, not just within one — stated
-        // against the standalone result rather than a literal, so this asserts the *property*
-        // instead of re-recording whatever this file happens to produce.
+        // The same word keeps its substitute in another sentence.
         let alone = garble_chat(&words, 1, 0, "hello");
         assert_eq!(alone, "kazum", "the golden vector still anchors it");
         let in_sentence = garble_chat(&words, 1, 0, "well hello there");
         assert_eq!(in_sentence.split(' ').nth(1), Some(alone.as_str()));
     }
 
-    /// `SStrHash` is case-folded, which is *why* `hello`/`Hello`/`HELLO` share a substitute — the
-    /// case stamp only decides how it is printed.
     #[test]
     fn the_hash_folds_case_and_is_seeded_the_storm_way() {
         assert_eq!(sstr_hash_folded(b"hello"), sstr_hash_folded(b"HELLO"));
         assert_eq!(sstr_hash_folded(b"hello"), sstr_hash_folded(b"hEllO"));
         assert_ne!(sstr_hash_folded(b"hello"), sstr_hash_folded(b"world"));
-        // The empty string never reaches the table, so it returns the untouched seed.
+        // The empty string returns the untouched seed.
         assert_eq!(sstr_hash_folded(b""), 0x7FED_7FED);
     }
 
-    /// The tokenizer's three surprises, stated as tests so they cannot be "cleaned up" later.
     #[test]
     fn digits_apostrophes_and_high_codepoints_are_word_characters() {
         assert!(is_word_char(u32::from(b'7')));
@@ -470,8 +379,6 @@ mod tests {
         assert!(!is_word_char(u32::from(b'.')));
     }
 
-    /// The flags the other two call sites set. Chat collapses `", "` to one space; gossip keeps
-    /// both bytes; item text additionally passes a `<…>` span straight through.
     #[test]
     fn the_gossip_and_item_text_flags_change_the_separators_only() {
         let data = crate::wow_data_or_skip!();
@@ -486,14 +393,13 @@ mod tests {
             garble(&words, 1, 0, "hello <Name> world", Garble::ITEM_TEXT),
             "kazum <Name> magan"
         );
-        // Without `keep_angle` the span is just separators and a word, so the name garbles too.
+        // Without `keep_angle` the name garbles too.
         assert_ne!(
             garble(&words, 1, 0, "hello <Name> world", Garble::GOSSIP),
             "kazum <Name> magan"
         );
     }
 
-    /// The destination cap is the reference's, and it truncates rather than growing.
     #[test]
     fn the_destination_cap_truncates() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/gm_ticket_category.rs b/crates/benilla-formats/src/gm_ticket_category.rs
index f47e0d53..f33c1a4e 100644
--- a/crates/benilla-formats/src/gm_ticket_category.rs
+++ b/crates/benilla-formats/src/gm_ticket_category.rs
@@ -1,43 +1,8 @@
-//! GMTicketCategory.dbc — the ten trouble-ticket categories the Help window's "page a GM" list is
-//! built from, and the id each one submits as (decision 1673).
-//!
-//! This table is the answer to a question the shipped FrameXML makes look unanswerable. Its
-//! `HelpFrameGM_UpdateCategories(GetGMTicketCategories())` consumes the binding's varargs as
-//! `(key, text)` PAIRS, and `HELPFRAME_FRAMES`/`GENERAL_HELPFRAME` are keyed `1..10` with ten
-//! distinct titles — yet `GlobalStrings.lua` ships only `TICKET_TYPE1..4` ("Game Play",
-//! "Harassment", "Stuck", "Bug"). Those four are not this list: they feed the OpenTicket
-//! *dropdown*, which has no frame in 1.12 and whose `OnShow` call is commented out. The category
-//! list is DBC data, and it lines up with `GENERAL_HELPFRAME`'s keys row for row:
-//!
-//! | id | name |
-//! |---|---|
-//! | 1 | Stuck |
-//! | 2 | Behavior/Harassment |
-//! | 3 | Guild |
-//! | 4 | Item |
-//! | 5 | Environmental |
-//! | 6 | Non-Quest/Creep |
-//! | 7 | Quest/Quest NPC |
-//! | 8 | Technical |
-//! | 9 | Account/Billing |
-//! | 10 | Character |
-//!
-//! **benilla's own Help window no longer shows this list** (decision 1687): it goes straight from
-//! Home to the ticket box and files under 0, "uncategorised". The catalog still ships, because
-//! `GetGMTicketCategories()` is a real Era binding a third-party addon may call and because these
-//! ids are still what the *server* names a ticket by — an existing ticket's category arrives on
-//! `UPDATE_TICKET` and is echoed back on an edit.
-//!
-//! **The id is the wire value**, not just a list index: the clicked button stores it as
-//! `HelpFrameOpenTicket.ticketType`, and that is what `NewGMTicket(category, text)` puts in
-//! `CMSG_GMTICKET_CREATE`'s category field. So a catalog that renumbered on load would file every
-//! ticket under the wrong heading, silently — which is why this is an ordered id-keyed read of the
-//! file rather than a `Vec` indexed from zero.
-//!
-//! Record layout (10 rows in the shipped 5875 file, verified by loading it): `ID@0`,
-//! `Name_Lang@1..8`, `NameFlags@9` — the same 8-locale + mask shape as [`crate::itembagfamily`].
-//! Ids are 1..10 contiguous here, but nothing downstream may assume that: the ordered pairs are
-//! what the binding pushes, and the id is what the wire carries.
+//! `GMTicketCategory.dbc`, the ten categories of the Help window's GM list, which
+//! `GetGMTicketCategories()` pushes as `(id, name)` pairs in file order; the `TICKET_TYPE1..4`
+//! strings feed the OpenTicket dropdown, which 1.12 never shows. The id is the wire value: the
+//! clicked button stores it as `HelpFrameOpenTicket.ticketType` and `NewGMTicket` sends it as
+//! `CMSG_GMTICKET_CREATE`'s category, so the file's ids are kept, never renumbered.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -47,8 +12,7 @@ use crate::Chain;
 
 const GM_TICKET_CATEGORY: &str = "DBFilesClient\\GMTicketCategory.dbc";
 
-/// GMTicketCategory.dbc, in file order — the order `GetGMTicketCategories()` pushes them in, which
-/// is the order the ten `HelpFrameButton*` rows are painted in.
+/// `GMTicketCategory.dbc` in file order, the order `GetGMTicketCategories()` pushes.
 pub struct GmTicketCategoryCatalog {
     categories: Vec<GmTicketCategory>,
 }
@@ -56,9 +20,9 @@ pub struct GmTicketCategoryCatalog {
 /// One row: the wire category id and its localized display name.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct GmTicketCategory {
-    /// The id `CMSG_GMTICKET_CREATE` carries — see the module doc's warning about renumbering.
+    /// The id `CMSG_GMTICKET_CREATE` carries.
     pub id: u32,
-    /// The button label, from the active locale's `Name_Lang` slot.
+    /// The button label, from the enUS `Name_Lang` slot.
     pub name: String,
 }
 
@@ -68,7 +32,6 @@ impl GmTicketCategoryCatalog {
         &self.categories
     }
 
-    /// Row count, for the load log.
     pub fn len(&self) -> usize {
         self.categories.len()
     }
@@ -88,11 +51,8 @@ fn gm_ticket_category_schema() -> Schema {
     s
 }
 
-/// Load GMTicketCategory.dbc from the patch chain.
-///
-/// A row whose name is empty is skipped rather than pushed blank: the Help window paints one
-/// button per returned pair and an unnamed button is a dead click, not a category. The shipped
-/// 5875 file has no such row — this is a guard on a locale slot, not a modelled branch.
+/// Load `GMTicketCategory.dbc` from the patch chain. A row with an empty name is skipped, as it
+/// would paint a dead button; 5875 has none.
 pub fn load_gm_ticket_categories(chain: &mut Chain) -> Result<GmTicketCategoryCatalog> {
     let bytes = chain
         .read_file(GM_TICKET_CATEGORY)
@@ -113,10 +73,8 @@ pub fn load_gm_ticket_categories(chain: &mut Chain) -> Result<GmTicketCategoryCa
 mod tests {
     use super::*;
 
-    /// The shipped 5875 table, read as data rather than assumed. Pins **both** halves that matter:
-    /// the ids (which go on the wire) and the order (which is the painted order), plus the row-for-
-    /// row correspondence with `GENERAL_HELPFRAME`'s ten keys that the module doc tabulates.
-    /// Skips without client data.
+    /// The 5875 ids (the wire values) in file order (the painted order), matching
+    /// `GENERAL_HELPFRAME`'s ten keys.
     #[test]
     fn the_shipped_categories_are_the_ten_help_window_rows_in_order() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/ground_effects.rs b/crates/benilla-formats/src/ground_effects.rs
index 519121eb..6fe1c117 100644
--- a/crates/benilla-formats/src/ground_effects.rs
+++ b/crates/benilla-formats/src/ground_effects.rs
@@ -1,24 +1,9 @@
-//! Ground-effect doodads — the little grass tufts, weeds, flowers and pebbles scattered over the
-//! terrain. This is the dense ground clutter that makes the real client's outdoors look lush; without
-//! it our ground is bare texture.
+//! Ground-effect doodads: the grass tufts, weeds, flowers and pebbles scattered over the terrain.
 //!
-//! Mechanism (verified against build 5875 + wowdev.wiki ADT/v18, 2026-05-26):
-//! - Each terrain texture layer in an MCNK carries an `effectId` ([`benilla_adt`] `TextureLayer.effect_id`;
-//!   `0xFFFFFFFF` = none) that indexes [`GroundEffectTexture.dbc`].
-//! - [`GroundEffectTexture.dbc`] (5875: **7 fields / 28 B** — `ID, doodadId[4], density, sound`; no
-//!   per-doodad weights, those arrive in 6.0) gives up to four [`GroundEffectDoodad.dbc`] refs + a
-//!   `density` (0→8, the client caps ~24: amount, then coverage/grouping).
-//! - [`GroundEffectDoodad.dbc`] (5875: **3 fields / 12 B** — `ID, internalId, modelPath`) names the
-//!   model as a bare `*.mdl` filename; on disk in this client the real model is
-//!   `World\NoDXT\Detail\<stem>.m2` (an `MD20` M2 — verified `ElwGra01.m2` extracts and loads). These
-//!   models are **not in the MPQ listfile** but extract fine by exact path.
-//!
-//! Which cell gets which doodad set is **authored**, in two per-cell 8×8 grids in the MCNK header
-//! (decoded onto [`ChunkMesh::pred_tex`] / [`ChunkMesh::no_effect_doodad`]): `predominantTexture`
-//! (0x40) names the layer whose `effectId` applies, `noEffectDoodad` (0x50) hard-disables the cell.
-//! The exact intra-cell scatter positions are client-internal, so the renderer scatters
-//! deterministically at the authored density. This module owns the **data** (`effectId → (models,
-//! density)`) and the faithful per-cell [`scatter_ground_doodads`].
+//! An MCNK texture layer's `effectId` (`0xFFFFFFFF` none) indexes `GroundEffectTexture.dbc`, which
+//! gives four `GroundEffectDoodad.dbc` slots and a density. Which layer a cell uses is authored in
+//! two per-cell 8×8 grids in the MCNK header: `predominantTexture` (`0x40`) names the layer, and
+//! `noEffectDoodad` (`0x50`) disables the cell.
 
 use std::collections::HashMap;
 
@@ -31,77 +16,69 @@ use crate::terrain::ChunkMesh;
 
 const GROUND_EFFECT_TEXTURE: &str = "DBFilesClient\\GroundEffectTexture.dbc";
 const GROUND_EFFECT_DOODAD: &str = "DBFilesClient\\GroundEffectDoodad.dbc";
-/// Detail-doodad models live here; the DBC stores a bare `*.mdl` name, the on-disk file is `.m2`.
+/// Detail-doodad models: the DBC names a bare `*.mdl`, the file is `<stem>.m2` here, absent from
+/// the MPQ listfile but readable by exact path.
 const DETAIL_DIR: &str = "World\\NoDXT\\Detail\\";
 
-/// A "none" doodad slot. Vanilla 5875 uses **only `0xFFFFFFFF` (the wiki's "-1")** as the empty
-/// sentinel — `0` is a valid `internalId`, owned by `ElwFlo01.mdl` (the dark-red branched flower
-/// in Elwynn). Empirically: across `GroundEffectTexture.dbc` (12 742 rows × 4 slots = 50 968),
-/// 48 083 slots are `0xFFFFFFFF`, only 16 are `0`, and all 16 resolve to `ElwFlo01` — so `0` is
-/// definitely an id, not a sentinel. (Treating it as empty silently dropped every `ElwFlo01`
-/// placement, e.g. the slot-0 entry on the 12 Elwynn effects 507/720/734/741/747/753/761/765/
-/// 777/801/805/868.)
+/// The empty slot is `0xFFFFFFFF` alone: 0 is a real `internalId`, `ElwFlo01.mdl`'s, which 16
+/// shipped slots name.
 fn is_no_doodad(id: u32) -> bool {
     id == 0xFFFF_FFFF
 }
 
-/// The detail doodads + density for one `effectId` (a [`GroundEffectTexture.dbc`] row).
+/// One `GroundEffectTexture.dbc` row: the detail doodads and density for an `effectId`.
 #[derive(Clone, Debug)]
 pub struct GroundEffect {
-    /// The 4 `doodadId` slots in order, resolved to `World\NoDXT\Detail\*.m2` paths. `None` = an
-    /// empty slot (`0`/`-1`); the client treats those as "place nothing" so the slot pattern (incl.
-    /// duplicates) acts as the doodad weighting. Kept in slot order (not deduped) for that reason.
+    /// The four `doodadId` slots in order, resolved to model paths; `None` places nothing. Slot
+    /// order and duplicates are kept: the slot pattern is the weighting.
     pub doodads: [Option<String>; 4],
-    /// Authored density (`0`..~`24`): per-cell doodad count; higher = denser, then grouped.
+    /// Doodads per visited cell, up to about 24 as shipped.
     pub density: u32,
 }
 
 impl GroundEffect {
-    /// The non-empty resolved model paths (diagnostics; the placement uses [`Self::doodads`] directly).
+    /// The non-empty model paths, for diagnostics.
     pub fn models(&self) -> Vec<&str> {
         self.doodads.iter().filter_map(|d| d.as_deref()).collect()
     }
 }
 
-/// `effectId → GroundEffect` from the GroundEffect* DBCs. Query with [`GroundEffectCatalog::effect`].
+/// `effectId` to [`GroundEffect`], from the two ground-effect DBCs.
 pub struct GroundEffectCatalog {
     effects: HashMap<u32, GroundEffect>,
 }
 
 impl GroundEffectCatalog {
-    /// The doodads + density for a terrain layer's `effectId`, or `None` (no effect / no models).
+    /// A terrain layer's effect; a row that resolves no model is absent.
     pub fn effect(&self, effect_id: u32) -> Option<&GroundEffect> {
         self.effects.get(&effect_id)
     }
 
-    /// Number of effect rows that resolve to at least one model (diagnostics).
+    /// Effect rows that resolve at least one model.
     pub fn len(&self) -> usize {
         self.effects.len()
     }
 
-    /// Whether the catalog is empty.
     pub fn is_empty(&self) -> bool {
         self.effects.is_empty()
     }
 }
 
-/// One placed ground-clutter doodad: a small upright `World\NoDXT\Detail\*.m2` with a random heading.
-/// Unlike [`crate::Doodad`] (MDDF placement matrix) these stand straight with just a yaw, like a
-/// creature — so they get their own type to avoid the MDDF rotation convention.
+/// One placed ground-clutter doodad. It stands upright with only a yaw, unlike an MDDF
+/// [`crate::Doodad`] and its rotation convention.
 #[derive(Clone, Debug)]
 pub struct GroundDoodadPlacement {
     pub model: String,
-    /// Position in WoW world coords (X north, Y west, Z up), on the terrain surface.
+    /// WoW world coords (X north, Y west, Z up), on the terrain surface.
     pub position: [f32; 3],
-    /// Heading in radians about the up axis (random — clutter has no authored facing).
+    /// Radians about the up axis, random: clutter has no authored facing.
     pub yaw: f32,
-    /// Per-instance uniform scale, the client's random `[0.9, 1.1]` (`signed·0.1 + 1.0`).
+    /// Uniform scale, the reference's random `[0.9, 1.1]`.
     pub scale: f32,
 }
 
-/// The vanilla client's 256-byte detail-doodad noise table (a permutation of 0..255), recovered from
-/// `Marlamin/noggit-red`'s `ChunkAddDetailDoodads.cpp` (where it sits commented out beside an `'a'`
-/// placeholder). Drives [`BlizzardRandomizer`].
+/// The reference's detail-doodad noise table, a permutation of 0..255, as Noggit Red's
+/// `ChunkAddDetailDoodads.cpp` recovers it.
 #[rustfmt::skip]
 pub(crate) const GROUND_EFFECT_NOISE: [u8; 256] = [
     0x8e, 0x14, 0x27, 0x99, 0xfd, 0xaa, 0xc7, 0x08, 0xd5, 0xe6, 0x3e, 0x1f, 0xf6, 0xbb, 0x55, 0xda,
@@ -122,11 +99,8 @@ pub(crate) const GROUND_EFFECT_NOISE: [u8; 256] = [
     0x96, 0xd1, 0x64, 0x26, 0xd7, 0x45, 0xcc, 0x4f, 0xc8, 0xb0, 0xe9, 0xb5, 0x00, 0xd6, 0x31, 0xea,
 ];
 
-/// The vanilla client's detail-doodad PRNG (`FUN_004531e0` + the `FUN_0044ea80` seed-expand, a.k.a. the
-/// Noggit `BlizzardRandomizer`). Seeded **once per chunk** from the chunk's global coords; the same
-/// stream drives PASS-1 cell picks and PASS-2 positions/scale/yaw, so the layout is bit-exact to the
-/// client and reload-stable. The lane math (`shuffle`) reproduces the binary exactly — see
-/// [`scatter_ground_doodads`].
+/// The reference's detail-doodad PRNG (`0x4531e0`, seed expanded by `0x44ea80`), seeded once per
+/// chunk; one stream drives both scatter passes.
 struct BlizzardRandomizer {
     source: u32,
     seed: u32,
@@ -141,19 +115,16 @@ impl BlizzardRandomizer {
         Self { source, seed }
     }
 
-    /// Little-endian `u32` read at byte offset `i` of the noise table. The 4-byte read wraps past 255
-    /// (circular); the client's exact boundary behaviour at `i ≥ 253` is unconfirmed (rare, ~1%).
+    /// Little-endian `u32` at byte `i` of the noise table; the lanes keep `i` at most 251.
     fn noise32(i: u8) -> u32 {
         let b = |k: u8| GROUND_EFFECT_NOISE[i.wrapping_add(k) as usize] as u32;
         b(0) | (b(1) << 8) | (b(2) << 16) | (b(3) << 24)
     }
 
-    /// Advance and return the next `source`. (`rol(v, 0) == v`.)
+    /// Advance and return the next `source`.
     fn shuffle(&mut self) -> u32 {
-        // Per-lane index = byte − sub, and **when that goes negative add the lane's specific constant**
-        // (`0xf4/0xec/0xd4/0xbc`) — NOT a mod-256 wrap. This is the client's exact `FUN_004531e0` math
-        // (verified to the instruction); the result stays in `[0, 251]` so the 4-byte noise read is
-        // always in-bounds. (Using `wrapping_sub` diverges on ~11–16% of draws — see ground-effects.md.)
+        // A negative lane index adds the lane's own constant, not a mod-256 wrap (`0x4531e0`); the
+        // result stays in `[0, 251]`.
         let lane = |byte: u32, sub: i32, wrap: i32| -> u8 {
             let idx = (byte & 0xFF) as i32 - sub;
             (if idx < 0 { idx + wrap } else { idx }) as u8
@@ -172,56 +143,35 @@ impl BlizzardRandomizer {
         self.source
     }
 
-    /// A signed uniform float in `(-1, 1)` — the client's `genCoord` output used for in-cell position,
-    /// scale, and yaw: take the mantissa float in `[1, 2)`, then map by the roll's sign bit.
+    /// The reference's `genCoord`, for in-cell position, scale and yaw: a mantissa float in
+    /// `[1, 2)`, mapped by the roll's sign bit to `(0, 1]` or `[-1, 0)`.
     fn signed_unit(&mut self) -> f32 {
         let u = self.shuffle();
         let f = f32::from_bits((u & 0x007F_FFFF) | 0x3F80_0000); // [1, 2)
         if (u as i32) < 0 {
-            2.0 - f // (0, 1] → mapped to (−1, 0]
+            2.0 - f // (0, 1]
         } else {
-            f - 2.0 // [1, 2) → [−1, 0)  … together: (−1, 1)
+            f - 2.0 // [-1, 0)
         }
     }
 }
 
-/// The client's `frillDensity` CVar default — the number of (randomly-chosen, with-repeats) cells the
-/// client visits per chunk. It is **not** all 64 cells — that's what makes the real clutter patchy
-/// (some cells hit 2–3×, ~50 left bare) rather than an even carpet.
-///
-/// **Byte-read, not chosen**: `CVar::Register 0x63db90` at `0x68862e` passes name `0x8423d8`
-/// `"frillDensity"`, default string `0x864644` `"16"`, help "Terrain frill density", record
-/// `[0xc7f2f4]` (wow-re `re/cvar/cvar-register-sites.tsv` row 185). `SetWorldDetail 0x488dd0`
-/// writes 16/32/48 over it per slider stop, so a stop IS a multiple of this constant — which is
-/// why [`scatter_ground_doodads`] takes a multiplier and the CVar host converts at its edge
-/// ([`crate::ground_effects::FRILL_DENSITY_MAX`] is that conversion's other bound).
+/// The reference's `frillDensity` default (`CVar::Register` at `0x68862e`, record `[0xc7f2f4]`):
+/// cells visited per chunk, drawn with repeats, so clutter is patchy. `SetWorldDetail`
+/// (`0x488dd0`) writes 16, 32 or 48 per slider stop, hence the scatter's multiplier.
 pub const FRILL_DENSITY: u32 = 16;
 
-/// The top of the reference's own `frillDensity` range — its change callback `0x688de0` clamps the
-/// written value to `[1, 256]`, so this is the densest ground cover the real client will scatter
-/// (its renderer saturates first: `0x6b1d4b` computes the detail-doodad instance count as
-/// `frillDensity << 6` capped at `0x2000`, reached at 128). Named here because both the scatter's
-/// own clamp below and the `frillDensity` CVar arm in `benilla-app` have to agree on it.
+/// The top of the reference's `frillDensity` range: its change callback (`0x688de0`) clamps to
+/// `[1, 256]`, though the renderer saturates at 128 (`0x6b1d4b` caps `frillDensity << 6` at
+/// `0x2000` instances). The scatter's clamp and `benilla-world`'s `set_frill_density` share it.
 pub const FRILL_DENSITY_MAX: u32 = 256;
 
-/// Scatter ground-clutter doodads over one terrain chunk — a **bit-exact port of the client's
-/// `CMapChunk::CreateDetailDoodads`** (RE'd from `WoW.exe` @ `0x6bfc10`). One RNG stream per chunk,
-/// seeded by **global chunk coords**
-/// `(globalChunkY << 16) | globalChunkX`, then two passes:
-///
-/// - **PASS 1** picks `frillDensity` (×`density_scale`) random cells `(rng&7, rng&7)` — **with repeats,
-///   no dedup** (2 RNG draws each). This is the source of the reference's patchiness: cells drawn more
-///   than once get extra doodads, the ~50 unpicked cells stay bare.
-/// - **PASS 2** visits exactly those cells in order. Per cell: skip if [`ChunkMesh::no_effect_doodad`];
-///   the layer named by [`ChunkMesh::pred_tex`] (`predominantTexture`, **never** MCAL alpha) gives the
-///   MCLY `effectId` → its [`GroundEffect`]. Then spawn `density` doodads; per doodad the exact draw
-///   order is **rx, ry (always), then — only if the slot isn't empty — scale, yaw**. Slot is
-///   `(n + listIndex) & 3` of the effect's 4 `doodadId`s; an **empty (−1/None) slot places nothing**
-///   but still consumes the rx/ry draws (matching the client, so the stream stays aligned).
-///
-/// Empty-slot effects are *why bare-earth cells stay clear*: a layer whose effect is all-−1 resolves to
-/// `None` (we drop those from the catalog). `density_scale` (debug slider) scales the per-chunk cell
-/// count = the client's `frillDensity` lever.
+/// Scatter ground clutter over one terrain chunk, a port of the reference's
+/// `CMapChunk::CreateDetailDoodads` (`0x6bfc10`): one RNG stream per chunk, seeded by the global
+/// chunk coords `(globalChunkY << 16) | globalChunkX`; pass 1 picks `frillDensity` cells
+/// `(rng & 7, rng & 7)` with repeats, and pass 2 spawns `density` doodads in each, slot
+/// `(n + listIndex) & 3`, from the layer [`ChunkMesh::pred_tex`] names, never MCAL alpha.
+/// `density_scale` multiplies [`FRILL_DENSITY`].
 pub fn scatter_ground_doodads(
     chunk: &ChunkMesh,
     catalog: &GroundEffectCatalog,
@@ -237,23 +187,17 @@ pub fn scatter_ground_doodads(
     if frill == 0 {
         return Vec::new();
     }
-    // The chunk's 145 verts are MCVT's stride-17 interleave (B1):
-    // outer (r,c) @ r·17+c, inner (r,c) @ r·17+9+c. Outer = the corner grid; inner = each cell's
-    // CENTER vertex, carrying its own authored MCVT height (the bump that gives hilltops their
-    // rise). Clutter heights interpolate via the 4-triangle center-fan, NOT a 4-corner bilinear:
-    // matching the terrain mesh's subdivision so doodads sit flush on the surface (esp. over
-    // hilltops, where a bilinear interp would float them under the rising inner vertex).
+    // MCVT's stride-17 interleave: corner `(r, c)` at `r * 17 + c`, the cell's centre vertex at
+    // `r * 17 + 9 + c`.
     let outer = |row: usize, col: usize| chunk.positions[row * 17 + col];
     let inner = |row: usize, col: usize| chunk.positions[row * 17 + 9 + col];
     let n_layers = chunk.layer_textures.len();
 
-    // ONE RNG stream for the whole chunk, seeded by GLOBAL chunk coords (Y high, X low) — matches the
-    // client, so the patch layout is globally unique (never repeats per tile) and reload-stable.
     let global_x = tile_x * 16 + chunk.index_x;
     let global_y = tile_y * 16 + chunk.index_y;
     let mut rng = BlizzardRandomizer::new((global_y << 16) | (global_x & 0xFFFF));
 
-    // PASS 1: pick `frill` random cells (with repeats — do NOT dedup), 2 draws each.
+    // Pass 1: `frill` cells, two draws each, with repeats; never dedup.
     let cells: Vec<(usize, usize)> = (0..frill)
         .map(|_| {
             let col = (rng.shuffle() & 7) as usize; // cellX
@@ -262,27 +206,27 @@ pub fn scatter_ground_doodads(
         })
         .collect();
 
-    // PASS 2: visit exactly those cells in order; gate + spawn.
+    // Pass 2: those cells, in order.
     let mut out = Vec::new();
     for (list_index, &(row, col)) in cells.iter().enumerate() {
         let k = row * 8 + col;
         if chunk.no_effect_doodad[k] {
-            continue; // client's explicit "no clutter" mask (roads/clearings)
+            continue; // the authored no-clutter mask (roads, clearings)
         }
-        // Holes (B2): skip clutter over holed 2×2 blocks — the surface itself isn't drawn there.
+        // No clutter over a holed 2×2 block, where no surface is drawn.
         if chunk.holes & (1u16 << ((row >> 1) * 4 + (col >> 1))) != 0 {
             continue;
         }
         let layer = chunk.pred_tex[k] as usize;
         if layer >= n_layers {
-            continue; // names a non-existent layer
+            continue;
         }
         let Some(eff) = chunk
             .layer_effect_ids
             .get(layer)
             .and_then(|&eid| catalog.effect(eid))
         else {
-            continue; // effect is none / all-(−1)-slots → the cell stays bare
+            continue; // no effect, or none of its slots resolves: the cell stays bare
         };
         let density = if eff.density == 0 { 8 } else { eff.density };
         // Cell verts in our (row, col) frame: row steps south (-X), col steps east (-Y).
@@ -292,14 +236,14 @@ pub fn scatter_ground_doodads(
         let br = outer(row + 1, col + 1);
         let ctr = inner(row, col);
         for n in 0..density as usize {
-            // Exact client draw order: rx, ry ALWAYS consumed; scale/yaw only when a model is placed.
+            // The reference's draw order: rx and ry always, scale and yaw only for a placed model.
             let rx = rng.signed_unit();
             let ry = rng.signed_unit();
             let Some(model) = eff.doodads[(n + list_index) & 3].as_deref() else {
-                continue; // empty (−1) slot: places nothing, but rx/ry are already consumed
+                continue;
             };
             let scale = rng.signed_unit() * 0.1 + 1.0; // [0.9, 1.1]
-            let yaw = rng.signed_unit() * std::f32::consts::PI; // (−π, π)
+            let yaw = rng.signed_unit() * std::f32::consts::PI; // [-π, π]
             let (fx, fy) = ((rx + 1.0) * 0.5, (ry + 1.0) * 0.5);
             let position = fan_point(fx, fy, tl, tr, bl, br, ctr);
             out.push(GroundDoodadPlacement {
@@ -313,11 +257,8 @@ pub fn scatter_ground_doodads(
     out
 }
 
-/// Interpolate a point inside one MCNK cell at fractional `(fx, fy) ∈ [0, 1]²` (fx=east, fy=south)
-/// across the **4-triangle center-fan** the terrain mesh itself draws — barycentric over the wedge
-/// containing the point (CTR + two adjacent corners). The 4 wedges are bounded by the cell's two
-/// diagonals (`fy=fx` and `fy=1-fx`). Matches the visible terrain so doodads sit flush on hilltops
-/// (a 4-corner bilinear would sink them below the rising inner-center vertex).
+/// The point at `(fx, fy)` in `[0, 1]²` (east, south) of an MCNK cell, on the terrain's drawn
+/// 4-triangle centre fan; a corner bilinear would sink clutter under a raised centre vertex.
 fn fan_point(
     fx: f32,
     fy: f32,
@@ -330,17 +271,13 @@ fn fan_point(
     // (u, v, w) weights and the two corner vertices for the wedge.
     let (u, v, w, va, vb) = if fx + fy <= 1.0 {
         if fy <= fx {
-            // North wedge: (CTR, TL, TR) — u_ctr=2·fy, v_tl=1−fx−fy, w_tr=fx−fy
             (2.0 * fy, 1.0 - fx - fy, fx - fy, tl, tr)
         } else {
-            // West wedge: (CTR, BL, TL) — u_ctr=2·fx, v_bl=fy−fx, w_tl=1−fx−fy
             (2.0 * fx, fy - fx, 1.0 - fx - fy, bl, tl)
         }
     } else if fy >= fx {
-        // South wedge: (CTR, BR, BL) — u_ctr=2·(1−fy), v_br=fx+fy−1, w_bl=fy−fx
         (2.0 * (1.0 - fy), fx + fy - 1.0, fy - fx, br, bl)
     } else {
-        // East wedge: (CTR, TR, BR) — u_ctr=2·(1−fx), v_tr=fx−fy, w_br=fx+fy−1
         (2.0 * (1.0 - fx), fx - fy, fx + fy - 1.0, tr, br)
     };
     [
@@ -350,7 +287,6 @@ fn fan_point(
     ]
 }
 
-/// GroundEffectTexture.dbc — 5875: `ID, doodadId[4], density, sound` (7 fields).
 fn texture_schema() -> Schema {
     let mut s = Schema::new("GroundEffectTexture");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -362,7 +298,6 @@ fn texture_schema() -> Schema {
     s
 }
 
-/// GroundEffectDoodad.dbc — 5875: `ID, internalId, modelPath` (3 fields).
 fn doodad_schema() -> Schema {
     let mut s = Schema::new("GroundEffectDoodad");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -371,29 +306,20 @@ fn doodad_schema() -> Schema {
     s
 }
 
-/// Resolve a DBC doodad string (a bare `ElwGra01.mdl`) to its on-disk model `World\NoDXT\Detail\
-/// ElwGra01.m2`. Keeps only the file stem (defensive against any stray path) and forces `.m2`.
+/// A DBC doodad name, a bare `ElwGra01.mdl`, to its model `World\NoDXT\Detail\ElwGra01.m2`.
 fn resolve_model(dbc_name: &str) -> String {
     let file = dbc_name.rsplit(['\\', '/']).next().unwrap_or(dbc_name);
     let stem = file.rsplit_once('.').map(|(s, _)| s).unwrap_or(file);
     format!("{DETAIL_DIR}{stem}.m2")
 }
 
-/// Load the GroundEffect* DBCs from the patch chain into a [`GroundEffectCatalog`].
-///
-/// `key_by_internal_id` selects how `GroundEffectTexture.doodadId[k]` is matched to a
-/// `GroundEffectDoodad` row. **The faithful value is `true`:** the client (verified in `WoW.exe`)
-/// treats `doodadId[k]` as a **`GroundEffectDoodad.internalId`**
-/// (field 1) and indexes its model cache by it — NOT the DBC row `ID` (field 0). In 5875 the two
-/// differ by exactly one (`rowID = internalId + 1`), so keying by row ID is an off-by-one that picks
-/// the neighbouring species (e.g. the main Elwynn grass effect resolves a *flower* into slot 0 and
-/// shifts the grass). `false` reproduces that old bug for A/B comparison only.
+/// Load both ground-effect DBCs off the patch chain. The reference matches `doodadId` against
+/// `GroundEffectDoodad.internalId` (field 1), one less than the row `ID` in 5875: `true` is
+/// faithful, `false` keys by row `ID`, an off-by-one kept only for A/B comparison.
 pub fn load_ground_effect_catalog(
     chain: &mut Chain,
     key_by_internal_id: bool,
 ) -> Result<GroundEffectCatalog> {
-    // doodadId (an internalId) → resolved model path. Keyed by GroundEffectDoodad.internalId (field 1)
-    // when faithful; field 0 (row ID) is the legacy off-by-one path.
     let key_field = if key_by_internal_id { 1 } else { 0 };
     let doodads = {
         let bytes = chain
@@ -416,7 +342,6 @@ pub fn load_ground_effect_catalog(
     let mut effects = HashMap::with_capacity(rs.records().len());
     for r in rs.records() {
         let Some(id) = u32_at(r, 0) else { continue };
-        // Keep the 4 slots in order (not deduped): the client uses slot multiplicity as the weighting.
         let mut slots: [Option<String>; 4] = Default::default();
         for (i, slot) in slots.iter_mut().enumerate() {
             let d = u32_at(r, 1 + i).unwrap_or(0);
@@ -425,7 +350,7 @@ pub fn load_ground_effect_catalog(
             }
         }
         if slots.iter().all(Option::is_none) {
-            continue; // a "terrain type only" row (footsteps/sound, no doodads) — nothing to draw
+            continue; // a terrain-type row: footsteps and sound, no doodads
         }
         let density = u32_at(r, 5).unwrap_or(0);
         effects.insert(
@@ -457,8 +382,6 @@ mod tests {
 
     #[test]
     fn no_doodad_sentinels() {
-        // 0xFFFFFFFF is the only empty marker; `0` is the valid internalId of ElwFlo01 (see the
-        // function's doc-comment for the empirical tally that settles this).
         assert!(is_no_doodad(0xFFFF_FFFF));
         assert!(!is_no_doodad(0));
         assert!(!is_no_doodad(42));
@@ -478,7 +401,6 @@ mod tests {
 
     #[test]
     fn randomizer_is_deterministic_and_bounded() {
-        // Same seed → identical stream (clutter is stable every run).
         let (mut a, mut b) = (
             BlizzardRandomizer::new(0x0030_0020),
             BlizzardRandomizer::new(0x0030_0020),
@@ -486,12 +408,10 @@ mod tests {
         for _ in 0..1000 {
             assert_eq!(a.shuffle(), b.shuffle());
         }
-        // Different seeds diverge (different chunks ⇒ different layouts).
         assert_ne!(
             BlizzardRandomizer::new(1).shuffle(),
             BlizzardRandomizer::new(2).shuffle()
         );
-        // signed_unit stays in (-1, 1) — the client's genCoord range.
         let mut r = BlizzardRandomizer::new(12345);
         for _ in 0..10_000 {
             let c = r.signed_unit();
diff --git a/crates/benilla-formats/src/install.rs b/crates/benilla-formats/src/install.rs
index cc92210a..5d4117ff 100644
--- a/crates/benilla-formats/src/install.rs
+++ b/crates/benilla-formats/src/install.rs
@@ -1,64 +1,25 @@
-//! **Where the WoW install is** — THE ONE ANSWER (decision 1175).
+//! Where the WoW install is: the one resolver for the `Data` folder. The first candidate that
+//! exists wins:
 //!
-//! 0954 made every path benilla *writes* resolve through one module, on the grounds that a
-//! hand-built path is a place the rule can be got wrong. Its *input* path never got the same
-//! treatment: the string
-//! `PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../WoW/Data")` was hand-copied to 215+
-//! sites, alongside 11 bare `var("WOW_DATA")` reads and 271 copies of the same four-line "is it
-//! there? if not, skip" guard whose message had drifted into five variants. Every one of those is
-//! a place the release rule would have to be written again — and the first Windows build finds
-//! every place someone forgot. This module is the rule, written once.
+//! 1. `$WOW_DATA`. Set and empty (`WOW_DATA=`) means no install and ends the search, so the
+//!    no-install path runs on a machine that has one.
+//! 2. `<project folder>/WoW/Data`, `dev` builds only, from this crate's `CARGO_MANIFEST_DIR`.
+//! 3. `<exe dir>/Data`, then `<exe dir>/WoW/Data`, the release layouts.
 //!
-//! **The rule, in the director's words:** *everything should always assume that the wow/data
-//! folder is in the project folder or the folder the binary is run from.*
-//!
-//! It lives in `benilla-formats` because every consumer already depends on it — `benilla-app`,
-//! `benilla-assets`, `benilla-world`, and the two detached probes — and because this crate already
-//! owns [`crate::Chain`], the thing you open *with* the answer.
-//!
-//! ## Resolution order
-//!
-//! 1. **`$WOW_DATA`** — the explicit override, for a second install or a non-standard layout. Kept
-//!    because the director's rule is about what the client *assumes*, not about removing the
-//!    escape hatch; the sprawl was 11 reads of it, not the variable itself. **Set and empty**
-//!    (`WOW_DATA=`) means *there is no install*: the ladder stops there and returns nothing, which
-//!    is how a machine that has an install can still run the no-install path (decision 1451).
-//! 2. **`<project folder>/WoW/Data`** — `#[cfg(feature = "dev")]` only. Computed from **this
-//!    crate's** `CARGO_MANIFEST_DIR`, which lands on the same workspace root whichever crate is
-//!    asking, and is what the repo-root `WoW` symlink points at. Gated because a shipped binary
-//!    must not carry the build machine's source tree: that is the whole point of the record.
-//! 3. **`<exe dir>/Data`, then `<exe dir>/WoW/Data`** — the release convention. Drop benilla into
-//!    your WoW folder, or drop a `WoW/` folder beside benilla, and double-click. Both spellings
-//!    are cheap to accept and a player will try both.
-//!
-//! Every candidate must **exist** to be chosen, so a stale `$WOW_DATA` falls through to a real
-//! install rather than poisoning the run. [`wow_data`] returns `None` when none of them do — the
-//! honest answer, and the one [`wow_data_or_skip`] turns into a uniform test skip.
-//!
-//! **The feature-unification trap** (called out in the record, and the reason
-//! `scripts/gates.sh`'s `--no-default-features` line exists): `dev` is default-on here, so every
-//! dependent must declare `default-features = false` and re-export it, or a player build pulls
-//! candidate 2 back in through unification and the binary carries `/Users/…` after all. The gate
-//! is what catches getting this wrong; [`tests::a_player_build_carries_no_source_tree_path`] is
-//! what catches it here.
+//! `dev` is a default feature here, so every dependent declares `default-features = false` and
+//! re-exports it; otherwise feature unification puts the source-tree path in a player build.
+//! `scripts/gates.sh`'s player build and `tests::a_player_build_carries_no_source_tree_path`
+//! catch it.
 
 use std::path::{Path, PathBuf};
 
-/// The vanilla `Data` directory, or `None` when there is no install to be found.
-///
-/// See the module header for the resolution order and why each step is there. Cheap enough to call
-/// at a use site (three `is_dir` stats at worst) — there is deliberately no cache, because a
-/// `OnceLock` would freeze the answer across a `$WOW_DATA` change.
+/// The vanilla `Data` directory, or `None` when there is no install. Uncached, so a `$WOW_DATA`
+/// change is seen.
 pub fn wow_data() -> Option<PathBuf> {
     candidates().into_iter().find(|c| c.is_dir())
 }
 
-/// Every place [`wow_data`] looks, in order, whether or not it exists — the resolver's own
-/// explanation of itself.
-///
-/// Public because "no install found" is a message a human has to act on: the skip in
-/// [`wow_data_or_skip`] and any future first-run screen both want to say *where we looked*, not
-/// just that we failed.
+/// Every place [`wow_data`] looks, in order, whether or not it exists, for a "looked in" message.
 pub fn candidates() -> Vec<PathBuf> {
     candidates_from(
         std::env::var_os("WOW_DATA").map(PathBuf::from),
@@ -68,25 +29,13 @@ pub fn candidates() -> Vec<PathBuf> {
     )
 }
 
-/// [`candidates`] with the two environment facts passed in, so the ladder can be tested without
-/// touching the process environment.
-///
-/// That is not tidiness — it is the fix for a real flake. Once every test in the workspace resolves
-/// its install through this module, a test that *sets* `$WOW_DATA` poisons every other test running
-/// concurrently in the same process, and the failure moves around depending on scheduling. Before
-/// 1175 each test baked its own `CARGO_MANIFEST_DIR` path and was immune. The env read now happens
-/// in exactly one place that no test mutates; the wiring of that one read is covered out-of-process
-/// by `tests/wow_data_env.rs`.
+/// [`candidates`] with the environment passed in: a test that set `$WOW_DATA` would change the
+/// answer for every test running beside it. `tests/wow_data_env.rs` covers the real read.
 fn candidates_from(override_dir: Option<PathBuf>, exe_dir: Option<PathBuf>) -> Vec<PathBuf> {
     let mut out = Vec::with_capacity(4);
 
-    // 1 · the explicit override — and its EMPTY spelling. `WOW_DATA=` (set, no value) is the
-    // answer *there is no install*: it returns no candidates at all, so [`wow_data`] is `None`
-    // even in a dev build with the project folder sitting right there. It exists because the
-    // no-install boot path — which every player who unzips benilla into the wrong folder takes —
-    // was unreachable in any build we run on this machine, and rotted until it panicked on frame
-    // one (decision 1451). `scripts/gates.sh` runs the enforcer under it on every commit; a
-    // session can see what a player without data sees with `WOW_DATA= cargo play`.
+    // 1. The override; set and empty is no install at all, even in a dev build
+    // (`WOW_DATA= cargo play` runs as a player without data).
     if let Some(over) = override_dir {
         if over.as_os_str().is_empty() {
             return Vec::new();
@@ -94,17 +43,14 @@ fn candidates_from(override_dir: Option<PathBuf>, exe_dir: Option<PathBuf>) -> V
         out.push(over);
     }
 
-    // 2 · the project folder — dev builds only. `CARGO_MANIFEST_DIR` is THIS crate's, so it is the
-    // same workspace root for every caller, including the two detached probes. Walked with
-    // `ancestors` rather than joined with `../..` so the path prints readably in the "looked in"
-    // message a human has to act on.
+    // 2. The project folder, dev builds only: this crate's manifest dir, two levels up, is the
+    // workspace root for every caller.
     #[cfg(feature = "dev")]
     if let Some(root) = Path::new(env!("CARGO_MANIFEST_DIR")).ancestors().nth(2) {
         out.push(root.join("WoW/Data"));
     }
 
-    // 3 · beside the binary. `current_exe` fails only on exotic platforms and on a deleted exe;
-    // there is nothing to fall back to, so an error is simply "no candidate here".
+    // 3. Beside the binary; a failed `current_exe` adds nothing.
     if let Some(dir) = exe_dir {
         out.push(dir.join("Data"));
         out.push(dir.join("WoW/Data"));
@@ -113,20 +59,9 @@ fn candidates_from(override_dir: Option<PathBuf>, exe_dir: Option<PathBuf>) -> V
     out
 }
 
-/// The install, or **skip this test** — the one replacement for 271 hand-copied existence guards
-/// and the five skip messages they had drifted into.
-///
-/// Expands to an expression, so it reads as an ordinary binding:
-///
-/// ```ignore
-/// let data = wow_data_or_skip!();          // in a `-> ()` test
-/// let data = wow_data_or_skip!(None);      // in a helper returning Option
-/// ```
-///
-/// These tests read the **real** 1.12 install, which is gitignored and not on every machine
-/// (the contract: never commit Blizzard assets), so "no install" has always meant *pass without
-/// asserting* rather than *fail*. That is deliberately unchanged; what changes is that the message
-/// now names every path that was tried, so a machine where the tests silently do nothing says why.
+/// The install, or skip this test: `wow_data_or_skip!()` in a `-> ()` test,
+/// `wow_data_or_skip!(None)` in a helper returning `Option`. The skip names every path tried, and
+/// under `BENILLA_REQUIRE_DATA=1` it fails instead.
 #[macro_export]
 macro_rules! wow_data_or_skip {
     () => {
@@ -136,9 +71,86 @@ macro_rules! wow_data_or_skip {
         match $crate::wow_data() {
             Some(data) => data,
             None => {
-                eprintln!(
-                    "skipping: no WoW install found — looked in {:?}",
-                    $crate::candidates()
+                $crate::skipped("no WoW install found", &$crate::candidates());
+                return $ret;
+            }
+        }
+    };
+}
+
+/// A data-gated test's skip, printed; a panic under `BENILLA_REQUIRE_DATA=1`, which the gate sets
+/// where the data is, since libtest hides a passing test's stderr and a lost install reads green.
+#[doc(hidden)]
+pub fn skipped(what: &str, looked_in: &[PathBuf]) {
+    skipped_under(
+        std::env::var_os("BENILLA_REQUIRE_DATA").is_some_and(|v| !v.is_empty() && v != "0"),
+        what,
+        looked_in,
+    );
+    // `$BENILLA_SKIP_LOG`: libtest hides the line above, so the gate counts skips from this file.
+    if let Some(log) = std::env::var_os("BENILLA_SKIP_LOG").filter(|p| !p.is_empty()) {
+        use std::io::Write;
+        if let Ok(mut f) = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(log)
+        {
+            // One write per line: parallel tests append here, and a formatted write can interleave.
+            let _ = f.write_all(format!("{what}\n").as_bytes());
+        }
+    }
+}
+
+/// [`skipped`] with the switch passed in, testable without the process environment.
+fn skipped_under(required: bool, what: &str, looked_in: &[PathBuf]) {
+    let msg = format!("skipping: {what} — looked in {looked_in:?}");
+    assert!(
+        !required,
+        "{msg} — and BENILLA_REQUIRE_DATA is set: the gate resolved this data on this machine, \
+         so a skip here is a broken resolver or a missing link, not a missing install"
+    );
+    eprintln!("{msg}");
+}
+
+/// The third-party addon corpus the UI engine's real-addon tests run against, or `None`:
+/// `$BENILLA_ADDON_CORPUS`, then `<project folder>/wow-addons-vanilla` (`dev` only), a gitignored
+/// link beside `WoW`. Never a folder beside the checkout, which depends on where the checkout sits.
+pub fn addon_corpus() -> Option<PathBuf> {
+    addon_corpus_candidates().into_iter().find(|c| c.is_dir())
+}
+
+/// Every place [`addon_corpus`] looks, in order, whether or not it exists, for the skip message.
+pub fn addon_corpus_candidates() -> Vec<PathBuf> {
+    addon_corpus_candidates_from(std::env::var_os("BENILLA_ADDON_CORPUS").map(PathBuf::from))
+}
+
+/// [`addon_corpus_candidates`] with the environment passed in, like [`candidates_from`].
+fn addon_corpus_candidates_from(override_dir: Option<PathBuf>) -> Vec<PathBuf> {
+    let mut out = Vec::with_capacity(2);
+    if let Some(over) = override_dir {
+        out.push(over);
+    }
+    // The project folder, dev builds only, as the install's rung 2.
+    #[cfg(feature = "dev")]
+    if let Some(root) = Path::new(env!("CARGO_MANIFEST_DIR")).ancestors().nth(2) {
+        out.push(root.join("wow-addons-vanilla"));
+    }
+    out
+}
+
+/// The addon corpus, or skip this test, spelled and refused as [`wow_data_or_skip`] is.
+#[macro_export]
+macro_rules! addon_corpus_or_skip {
+    () => {
+        $crate::addon_corpus_or_skip!(())
+    };
+    ($ret:expr) => {
+        match $crate::addon_corpus() {
+            Some(root) => root,
+            None => {
+                $crate::skipped(
+                    "no vanilla addon corpus (set $BENILLA_ADDON_CORPUS)",
+                    &$crate::addon_corpus_candidates(),
                 );
                 return $ret;
             }
@@ -150,13 +162,11 @@ macro_rules! wow_data_or_skip {
 mod tests {
     use super::*;
 
-    /// No test in here touches the process environment — see [`candidates_from`] for why.
+    /// No test here touches the process environment (see [`candidates_from`]).
     fn probe(over: Option<&str>, exe: Option<&str>) -> Vec<PathBuf> {
         candidates_from(over.map(PathBuf::from), exe.map(PathBuf::from))
     }
 
-    /// The override leads, and beside-the-binary always follows in both spellings a player will
-    /// try — the release convention, and the only candidates a shipped binary has.
     #[test]
     fn the_ladder_is_override_then_project_folder_then_beside_the_binary() {
         let c = probe(Some("/opt/wow/Data"), Some("/games/benilla"));
@@ -167,7 +177,7 @@ mod tests {
             "{c:?}"
         );
 
-        // Both halves are optional and their absence must not shift the rest.
+        // Either input may be absent without shifting the rest.
         assert_eq!(
             probe(None, Some("/games/benilla")).last(),
             Some(&PathBuf::from("/games/benilla/WoW/Data"))
@@ -177,17 +187,14 @@ mod tests {
             .any(|p| p.starts_with("/games")));
     }
 
-    /// A candidate only wins if it EXISTS, so a stale `$WOW_DATA` falls through to a real install
-    /// rather than poisoning the run. Exercised through [`wow_data`]'s own filter.
     #[test]
     fn a_candidate_that_does_not_exist_is_never_chosen() {
         let tmp = std::env::temp_dir().join(format!("benilla-wd-{}", std::process::id()));
         std::fs::create_dir_all(tmp.join("Data")).unwrap();
         let ghost = tmp.join("nope");
 
-        // Which real candidate wins depends on the build (a dev build has the project folder
-        // ahead of the exe dir), so the assertion is the property, not the winner: never the
-        // ghost, always something that is actually there.
+        // The winner depends on the build (dev puts the project folder first), so assert only
+        // that it is not the ghost and exists.
         let chosen = candidates_from(Some(ghost.clone()), Some(tmp.clone()))
             .into_iter()
             .find(|c| c.is_dir());
@@ -204,9 +211,6 @@ mod tests {
         std::fs::remove_dir_all(&tmp).ok();
     }
 
-    /// `WOW_DATA=` — set and empty — is *there is no install*, and it outranks every other rung
-    /// including the dev build's project folder. Without it the no-install path is unreachable on
-    /// any machine that has an install, which is every machine this is developed on (1451).
     #[test]
     fn an_empty_override_means_there_is_no_install() {
         assert_eq!(
@@ -216,10 +220,7 @@ mod tests {
         );
     }
 
-    /// **The falsifier for the whole record, as a unit test.** A player build — `dev` off — must
-    /// not look anywhere inside the source tree that compiled it. If this fails, the project-folder
-    /// candidate came back through feature unification and `strings <binary> | grep /Users` will
-    /// find it too.
+    /// A failure here means feature unification put the project-folder rung in a player build.
     #[cfg(not(feature = "dev"))]
     #[test]
     fn a_player_build_carries_no_source_tree_path() {
@@ -233,8 +234,6 @@ mod tests {
         }
     }
 
-    /// The dev twin: with the feature on, the project folder IS a candidate — otherwise every
-    /// real-data test in the workspace silently turns into a skip and nobody notices.
     #[cfg(feature = "dev")]
     #[test]
     fn a_dev_build_looks_in_the_project_folder() {
@@ -249,4 +248,47 @@ mod tests {
             root.display()
         );
     }
+
+    #[cfg(feature = "dev")]
+    #[test]
+    fn the_corpus_ladder_is_override_then_the_project_folder_and_nothing_outside_it() {
+        let root = Path::new(env!("CARGO_MANIFEST_DIR"))
+            .ancestors()
+            .nth(2)
+            .unwrap();
+        let c = addon_corpus_candidates_from(Some(PathBuf::from("/opt/corpus")));
+        assert_eq!(
+            c,
+            vec![
+                PathBuf::from("/opt/corpus"),
+                root.join("wow-addons-vanilla")
+            ],
+            "{c:?}"
+        );
+        for c in addon_corpus_candidates_from(None) {
+            assert!(
+                c.starts_with(root),
+                "a corpus candidate outside the checkout ({}) — that is the resolver whose answer \
+                 moved when the pool did",
+                c.display()
+            );
+        }
+    }
+
+    #[cfg(not(feature = "dev"))]
+    #[test]
+    fn a_player_build_has_no_corpus_rung_of_its_own() {
+        assert_eq!(addon_corpus_candidates_from(None), Vec::<PathBuf>::new());
+    }
+
+    #[test]
+    fn a_skip_is_a_skip_where_nothing_requires_the_data() {
+        skipped_under(false, "no WoW install found", &[PathBuf::from("/nowhere")]);
+    }
+
+    #[test]
+    #[should_panic(expected = "BENILLA_REQUIRE_DATA is set")]
+    fn a_skip_is_refused_where_the_gate_says_the_data_is_present() {
+        skipped_under(true, "no WoW install found", &[PathBuf::from("/nowhere")]);
+    }
 }
diff --git a/crates/benilla-formats/src/item_random_properties.rs b/crates/benilla-formats/src/item_random_properties.rs
index 647d9e51..ec9028a9 100644
--- a/crates/benilla-formats/src/item_random_properties.rs
+++ b/crates/benilla-formats/src/item_random_properties.rs
@@ -1,36 +1,12 @@
-//! `ItemRandomProperties.dbc` — the **random-suffix** table: the "… of the Monkey" roll an item
-//! carries, and the enchants that roll actually grants.
-//!
-//! The client reads this table from two places, and both are one row lookup:
-//!
-//! - **the NAME.** `0x5d8b00(dst, size, itemEntry, randomPropertyId)` — the one item-name
-//!   formatter — joins the item-cache name with this row's locale-indexed suffix string through
-//!   `ITEM_SUFFIX_TEMPLATE` (`"%s %s"`), so a rolled green reads "Chipped Claw of the Bear". Its
-//!   two exits ARE the gate: a `randomPropertyId` that is `0`, negative, past the store's max id,
-//!   or resolves to a null/empty suffix takes the plain-name exit (`0x5d8ba5`); anything else
-//!   takes the suffix exit (`0x5d8b84`). Byte-verified, wow-re `ui/scratch/auction-house.md`.
-//! - **the ENCHANTS.** The item tooltip's own suffix mechanism `0x52b7bf–0x52b7fb` resolves the
-//!   same row from the tooltip's `+0x424` randomPropertyId and copies **five dwords from
-//!   `row+0x8..+0x18`** into the tooltip's session enchant slots 2..6 — which the enchant family
-//!   then prints, in white, exactly as if the item object had carried them (wow-re
-//!   `ui/scratch/tooltip-content-law.md` §1-ENCHANT §E5). That is why a looted or linked
-//!   random-property item shows its real stat lines and *not* the `<Random enchantment>`
-//!   placeholder: the placeholder is the no-roll-known arm, and a known roll fills the slots.
-//!
-//! An item OBJECT never needs this table for its enchants — the server writes the rolled ids into
-//! its own `ITEM_FIELD_ENCHANTMENT` slots 2..6 — but it still needs it for the NAME, off
-//! `ITEM_FIELD_RANDOM_PROPERTIES_ID`.
-//!
-//! ## Layout — VERIFIED against build 5875 (the shipped table dumped whole)
-//!
-//! | table | records | fields | record size |
-//! |---|---|---|---|
-//! | `ItemRandomProperties` | 2012 | 16 | 64 |
-//!
-//! Columns: `0` id · `1` the internal (unlocalized) name · `2`-`6` the **five
-//! `SpellItemEnchantment` ids** (byte offsets `0x8..0x18` — the exact five dwords the tooltip
-//! copies) · `7`-`14` the localized suffix `Name_Lang[8]` (byte offset `0x1c`, and `0x1c + 4*locale`
-//! is the string the name formatter reads) · `15` the name mask.
+//! `ItemRandomProperties.dbc`, the random-suffix table: the "of the Monkey" roll an item carries
+//! and the enchants it grants. The name formatter `0x5d8b00` joins name and suffix through
+//! `ITEM_SUFFIX_TEMPLATE` (`"%s %s"`), taking its plain-name exit (`0x5d8ba5`) for an id that is
+//! `0`, negative, past the table or suffix-less and its suffix exit (`0x5d8b84`) otherwise. The
+//! tooltip (`0x52b7bf`-`0x52b7fb`) copies the row's five enchant ids (`row+0x8..+0x18`) into its
+//! enchant slots 2..6 for `0x52c991` to print, so a linked item shows its stat lines, not
+//! `<Random enchantment>`. An item object carries its own enchants (`ITEM_FIELD_ENCHANTMENT`
+//! 2..6) and reads the table only for the name, off `ITEM_FIELD_RANDOM_PROPERTIES_ID`. The
+//! localized suffix is columns 7..14, read at `0x1c + 4*locale`.
 
 use std::collections::HashMap;
 
@@ -42,46 +18,37 @@ use crate::dbc::{parse, str_at, u32_at};
 
 const ITEM_RANDOM_PROPERTIES: &str = "DBFilesClient\\ItemRandomProperties.dbc";
 
-/// The five enchant slots a random-property row grants — and, one-for-one, the item's enchant
-/// slots **2..6** (slot 0 is the permanent enchant, slot 1 the temporary one; the suffix never
-/// touches either).
+/// The enchant slots a row grants, the item's enchant slots 2..6 (0 permanent, 1 temporary).
 pub const RANDOM_PROPERTY_SLOTS: usize = 5;
 
-/// The item-enchant slot the first random-property enchant lands in (`ITEM_FIELD_ENCHANTMENT`
-/// slot 2 — wow-re §1-SESSION: the session block's `+0x3d8` is slot 2, and §E5 copies the row's
-/// five dwords into `+0x3d8..+0x3e8`).
+/// The item-enchant slot the first random-property enchant lands in: `0x52b7e0`-`0x52b7fb`
+/// copies the row's five dwords to the tooltip session's `+0x3d8..+0x3e8`, slots 2..6.
 pub const RANDOM_PROPERTY_FIRST_SLOT: u8 = 2;
 
 /// One `ItemRandomProperties` row: the suffix the name takes, and the enchants the roll grants.
 #[derive(Clone, Debug, Default)]
 pub struct RandomProperty {
-    /// The locale-0 (enUS) suffix — `"of the Bear"`. Never empty: a row whose suffix string is
-    /// empty is the name formatter's plain-name exit, so it never reaches this map.
+    /// The enUS suffix (`"of the Bear"`), never empty: a suffix-less row is the formatter's
+    /// plain-name exit and is not loaded.
     pub suffix: String,
-    /// The row's five `SpellItemEnchantment` ids, in slot order (item enchant slots 2..6). `0`
-    /// where the row grants nothing — most rows carry one or two.
+    /// The five `SpellItemEnchantment` ids for enchant slots 2..6, `0` where the row grants none.
     pub enchants: [u32; RANDOM_PROPERTY_SLOTS],
 }
 
-/// `ItemRandomProperties.dbc`, keyed by id — the one load both consumers read (the name suffix and
-/// the tooltip's slots 2..6). One table, one loader: two would be how a schema drifts.
+/// `ItemRandomProperties.dbc` keyed by id, for the name suffix and the tooltip's enchants.
 pub struct RandomPropertyCatalog {
     rows: HashMap<u32, RandomProperty>,
 }
 
 impl RandomPropertyCatalog {
-    /// The row for a random-property id, or `None` when the id names none.
-    ///
-    /// Takes the id **signed**, because that is how the client gates it: `0x5d8b00` rejects `0`,
-    /// negative, and `> maxId` before it ever reads the row. A row that resolves but carries an
-    /// empty suffix is equally nothing (it never entered the map).
+    /// The row for a random-property id, taken signed because `0x5d8b00` gates it so: `0`,
+    /// negative and unknown ids name none.
     pub fn get(&self, id: i32) -> Option<&RandomProperty> {
         (id > 0).then(|| self.rows.get(&(id as u32)))?
     }
 
-    /// The suffixed display name — the client's `0x5d8b00`, whose whole law is its two exits:
-    /// `ITEM_SUFFIX_TEMPLATE` (`"%s %s"`) joined when the id resolves to a real suffix, the plain
-    /// name otherwise.
+    /// The display name as `0x5d8b00` builds it: `ITEM_SUFFIX_TEMPLATE` (`"%s %s"`) for a
+    /// resolved suffix, else the plain name.
     pub fn suffixed_name(&self, name: &str, id: i32) -> String {
         match self.get(id) {
             Some(row) => format!("{name} {}", row.suffix),
@@ -89,12 +56,12 @@ impl RandomPropertyCatalog {
         }
     }
 
-    /// Every row, `(id, row)` — the whole-table resolve the app pushes to the engine reads it.
+    /// Every row as `(id, row)`, for the whole-table push to the engine.
     pub fn iter(&self) -> impl Iterator<Item = (u32, &RandomProperty)> + '_ {
         self.rows.iter().map(|(&id, row)| (id, row))
     }
 
-    /// Build from explicit rows — tests and synthetic fixtures.
+    /// A catalog from explicit rows, for tests and fixtures.
     pub fn from_rows(rows: HashMap<u32, RandomProperty>) -> Self {
         RandomPropertyCatalog { rows }
     }
@@ -125,11 +92,8 @@ pub(crate) fn item_random_properties_schema() -> Schema {
     s
 }
 
-/// Load `ItemRandomProperties.dbc` off the patch chain.
-///
-/// A row with no locale-0 suffix is dropped at load — it is the name formatter's plain-name exit
-/// and grants a suffix to nothing, so keeping it would only invite a caller to print an empty
-/// `"Name "`. (The shipped table has none, and the drop is the client's own `cmp`, not a guess.)
+/// Load `ItemRandomProperties.dbc` off the patch chain, dropping a row with no enUS suffix, the
+/// formatter's plain-name exit.
 pub fn load_random_property_catalog(chain: &mut Chain) -> Result<RandomPropertyCatalog> {
     let bytes = chain
         .read_file(ITEM_RANDOM_PROPERTIES)
@@ -142,8 +106,7 @@ pub fn load_random_property_catalog(chain: &mut Chain) -> Result<RandomPropertyC
     let mut rows = HashMap::with_capacity(rs.records().len());
     for r in rs.records() {
         let Some(id) = u32_at(r, 0) else { continue };
-        // Field 7 = `Suffix0`, the enUS slot of the localized block — byte offset 0x1c, which is
-        // `0x1c + 4*locale` at locale 0, the string the name formatter reads.
+        // Field 7, `Suffix0`: the enUS string at `0x1c`, the one the name formatter reads.
         let Some(suffix) = str_at(&rs, r, 7) else {
             continue;
         };
@@ -165,13 +128,11 @@ mod tests {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_random_property_catalog(&mut chain).expect("load");
-        // 2012 rows in the shipped 1.12.1 table (dumped whole: 16 fields, 64-byte records).
         assert_eq!(
             cat.len(),
             2012,
             "every shipped row carries a locale-0 suffix"
         );
-        // Row 5 — the table's first: "of Intellect", one enchant (79).
         let row = cat.get(5).expect("row 5");
         assert_eq!(row.suffix, "of Intellect");
         assert_eq!(row.enchants, [79, 0, 0, 0, 0]);
diff --git a/crates/benilla-formats/src/item_sounds.rs b/crates/benilla-formats/src/item_sounds.rs
index 65a2cd15..19b70415 100644
--- a/crates/benilla-formats/src/item_sounds.rs
+++ b/crates/benilla-formats/src/item_sounds.rs
@@ -1,15 +1,6 @@
-//! `ItemGroupSounds.dbc` adapter — the per-item **pickup / put-down / use** sound groups
-//! (decision 0091: the bag-drag item sounds).
-//!
-//! Layout — VERIFIED byte-exact against build 5875 (wow-re
-//! `system/sound/scratch/item-pickup-place-sound.md`, §5 cross-checked): **5 fields × 4 = 20 B**
-//! per record (loader `0x5477d0` asserts fieldCount 5 @`0x547879`, recordSize 0x14 @`0x5478ae`):
-//! `{ id, kit[0], kit[1], kit[2], kit[3] }` — the kits are `SoundEntries.dbc` ids, indexed by the
-//! client's **gesture**: `kit[0]` pickup/grab, `kit[1]` put-down/place, `kit[2]` use/activate
-//! (`0x458024: mov ecx,[eax+4*ecx+0x4]`); `kit[3]` is unused by any caller. 24 rows in the real
-//! DBC. An item reaches its group through `ItemDisplayInfo.field11`
-//! ([`crate::items::ItemDisplay::group_sounds`]); a `0` kit slot means the gesture is silent —
-//! the client's play tail drops kit id 0.
+//! `ItemGroupSounds.dbc`: an item's pickup, put-down and use sounds. A row is an id and four
+//! `SoundEntries` ids indexed by the client's gesture (`0x458024`); no caller reads the fourth.
+//! An item reaches its group through `ItemDisplayInfo.field11`, and a 0 slot is silent.
 
 use std::collections::HashMap;
 
@@ -21,15 +12,14 @@ use crate::dbc::{parse, u32_at};
 
 const ITEM_GROUP_SOUNDS: &str = "DBFilesClient\\ItemGroupSounds.dbc";
 
-/// The client's gesture index into an [`ItemGroupSoundsCatalog`] row (the `ecx` every
-/// `SndInterfacePlayItemSound` caller passes — wow-re `item-pickup-place-sound.md`).
+/// The gesture index `SndInterfacePlayItemSound`'s callers pass in `ecx` (`0x457ff0`, `0x457fb0`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum ItemGesture {
-    /// `ecx = 0` — item grabbed onto the cursor.
+    /// Grabbed onto the cursor.
     Pickup = 0,
-    /// `ecx = 1` — item placed / put down / cursor cleared.
+    /// Placed, or the cursor cleared.
     PutDown = 1,
-    /// `ecx = 2` — item used/activated (only groups 1–6 populate it).
+    /// Used; only groups 1, 2 and 4-6 have a kit for it.
     Use = 2,
 }
 
@@ -39,9 +29,8 @@ pub struct ItemGroupSoundsCatalog {
 }
 
 impl ItemGroupSoundsCatalog {
-    /// The `SoundEntries` kit for a group's gesture — `None` when the group id is unknown or the
-    /// slot is `0` (both are the client's silent returns: the bounds/null checks at
-    /// `0x45800f`/`0x45801d`, and the play tail dropping kit 0).
+    /// The `SoundEntries` id for a group's gesture; an unknown group (`0x45800f`, `0x45801d`) or a
+    /// 0 slot plays nothing in the client.
     pub fn kit(&self, group: u32, gesture: ItemGesture) -> Option<u32> {
         self.groups
             .get(&group)
@@ -84,9 +73,7 @@ pub fn load_item_group_sounds(chain: &mut Chain) -> Result<ItemGroupSoundsCatalo
 mod tests {
     use super::*;
 
-    /// The real 5875 rows match the RE's corroboration decode (`item-pickup-place-sound.md`):
-    /// 24 groups; id 1 → kits [273, 274, 275, 0] (a group with a use kit), id 7 → [1185, 1202, 0, 0]
-    /// (a weapon/armor group, no use kit — its `Use` gesture resolves silent).
+    /// Shipped rows: group 1 has a use kit, group 7 (weapon and armor) has none.
     #[test]
     fn real_item_group_sounds_resolve() {
         let data = crate::wow_data_or_skip!();
@@ -102,9 +89,6 @@ mod tests {
         assert_eq!(cat.kit(999, ItemGesture::Pickup), None, "unknown group");
     }
 
-    /// The display→group→kit join holds on real data: every nonzero `ItemDisplayInfo.field11`
-    /// (`group_sounds`) is a valid group id — the RE's 20513/20513 corroboration, re-run through
-    /// our own two adapters.
     #[test]
     fn real_display_group_ids_all_resolve() {
         let data = crate::wow_data_or_skip!();
@@ -121,7 +105,7 @@ mod tests {
                 }
             }
         }
-        assert_eq!(nonzero, 20513, "the RE's nonzero field-11 count");
+        assert_eq!(nonzero, 20513, "the nonzero field-11 count");
         assert_eq!(valid, nonzero, "every nonzero group id resolves");
     }
 }
diff --git a/crates/benilla-formats/src/item_visuals.rs b/crates/benilla-formats/src/item_visuals.rs
index 2fa803e8..d551a3cd 100644
--- a/crates/benilla-formats/src/item_visuals.rs
+++ b/crates/benilla-formats/src/item_visuals.rs
@@ -1,47 +1,12 @@
-//! `ItemVisuals.dbc` + `ItemVisualEffects.dbc` + `SpellItemEnchantment`'s visual column — the
-//! **item / enchant glow chain** (decision 0805): the permanent weapon glows and the shaman/oil
-//! enchant visuals, as up to five `Spells\Enchantments\*.mdx` effect models per item.
+//! The item and enchant glow chain. An ItemVisuals id comes from the item's display
+//! (`ItemDisplayInfo` column 22) or its enchant (`SpellItemEnchantment` field 22); its row holds
+//! five `ItemVisualEffects` ids, each naming a glow model, and slot `i` hangs on the item model's
+//! attachment `i` (`0x479700` calls `0x712f70(glow, item, i)`). The loaders check each table's
+//! field count and record size (`0x548760`, `0x548530`, `0x54f6e0`).
 //!
-//! ## The chain
-//!
-//! Two sources name an **ItemVisuals id**, and both land in the same consumer:
-//!
-//! - the item's own **intrinsic** visual — `ItemDisplayInfo` column 22
-//!   ([`crate::ItemDisplay::item_visual`], record `+0x58`), and
-//! - the **enchant's** visual — `SpellItemEnchantment` field 22 (record `+0x58`), read off the
-//!   item's enchant slots.
-//!
-//! An ItemVisuals row is `{ id, effect[5] }`; each effect is an `ItemVisualEffects` id whose one
-//! payload column is the effect model's `.mdx` path. So one id = **up to five glow models**, one
-//! per slot, and the slot index *is* the M2 attachment id (0..4) they hang from on the item's own
-//! model (`0x479700`'s `0x712f70(glow, item, attachId = loop index)`).
-//!
-//! ## Layout — VERIFIED against build 5875 (both tables dumped whole)
-//!
-//! | table | records | fields | record size | columns |
-//! |---|---|---|---|---|
-//! | `ItemVisuals` | 34 | 6 | 24 | id + 5 `ItemVisualEffects` ids |
-//! | `ItemVisualEffects` | 35 | 2 | 8 | id + model `.mdx` path (string) |
-//! | `SpellItemEnchantment` | 1460 | 24 | 96 | id · effect[3] · pointsMin[3] · pointsMax[3] · arg[3] · name[8]+mask · **ItemVisual (22)** · flags |
-//!
-//! The wow-re §5 note `object-layer/scratch/item-visual-enchant.md` byte-pins the same shapes from
-//! the loaders' own `cmp fieldCount/recSize` asserts (`0x548760`/`0x548530`/`0x54f6e0`).
-//!
-//! ## The skip rules are the client's, applied here at load
-//!
-//! `0x479700` bounds-checks **twice**, signed, and both checks matter on the shipped data:
-//!
-//! - the ItemVisuals id: `jl` on negative, `jg` on `> maxId`, then a null-row test. **Five of the
-//!   365 visual-carrying displays carry `-1`** — they resolve to nothing.
-//! - each of the 5 effect ids, the same way — and **ItemVisuals row 28 carries two out-of-range
-//!   garbage dwords** (`90148992`, `455344256`) in slots 0 and 3, which the reference skips and so
-//!   do we (id 28 renders only its slot-4 `Sparkle_A`).
-//! - an **empty** path string (`cmpb $0,(%eax)`) is skipped before the load. Effect id 61 is
-//!   `Spells\Enchantments\` — a directory, not empty, so the reference *tries* it and the load
-//!   fails; no ItemVisuals row references it, so this is theory either way.
-//!
-//! Every one of those becomes a `None` slot in [`ItemVisualCatalog`], so a consumer sees only real
-//! model paths and can never spawn a glow the reference wouldn't.
+//! `0x479700` skips a visual or effect id that is negative, past the table's max id or a null
+//! row, and an empty model path; ItemVisuals row 28 ships two garbage effect ids. The catalog
+//! applies the same skips at load.
 
 use std::collections::HashMap;
 
@@ -55,28 +20,23 @@ const ITEM_VISUALS: &str = "DBFilesClient\\ItemVisuals.dbc";
 const ITEM_VISUAL_EFFECTS: &str = "DBFilesClient\\ItemVisualEffects.dbc";
 const SPELL_ITEM_ENCHANTMENT: &str = "DBFilesClient\\SpellItemEnchantment.dbc";
 
-/// The five effect slots an ItemVisuals row carries — and, one-for-one, the M2 attachment ids
-/// `0..4` on the item model each one hangs from.
+/// An ItemVisuals row's effect slots, which are also the item model's attachment ids 0..4.
 pub const ITEM_VISUAL_SLOTS: usize = 5;
 
-/// `ItemVisuals.dbc` joined with `ItemVisualEffects.dbc`: an ItemVisuals id → its five glow-model
-/// paths (raw `.mdx` references, as the DBC stores them — the app's `m2_url` owns the `.m2` swap),
-/// `None` where the slot is empty, out of range, or names an empty path.
+/// ItemVisuals id to its five glow-model paths, raw `.mdx` as stored; `None` where the reference
+/// skips the slot.
 pub struct ItemVisualCatalog {
     visuals: HashMap<u32, [Option<String>; ITEM_VISUAL_SLOTS]>,
 }
 
 impl ItemVisualCatalog {
-    /// The five glow-model slots for an ItemVisuals id, or `None` when the id names no row.
-    ///
-    /// Takes the id **signed**, because that is how the client reads it: `0x479700` tests `jl`
-    /// before its `maxId` compare, so `-1` (five shipped `ItemDisplayInfo` rows) and `0` name
-    /// nothing. `> 0` with no row is equally nothing.
+    /// The five slots for an ItemVisuals id, read signed as `0x479700` does, so `-1` and `0` name
+    /// nothing.
     pub fn effects(&self, visual_id: i32) -> Option<&[Option<String>; ITEM_VISUAL_SLOTS]> {
         (visual_id > 0).then(|| self.visuals.get(&(visual_id as u32)))?
     }
 
-    /// Build from an explicit map — tests and synthetic fixtures.
+    /// Build from an explicit map, for tests and fixtures.
     pub fn from_visuals(visuals: HashMap<u32, [Option<String>; ITEM_VISUAL_SLOTS]>) -> Self {
         ItemVisualCatalog { visuals }
     }
@@ -90,72 +50,42 @@ impl ItemVisualCatalog {
     }
 }
 
-/// `SpellItemEnchantment.dbc`'s consumer columns, from one load of the one table: the **visual**
-/// (field 22) an enchant glows with, the **name** (field 13, the enUS slot of the 1.12
-/// localized-string block) the item tooltip prints for it, and its **`Flags`** (field 23 —
-/// [`EnchantCatalog::binds_the_item`] and [`EnchantCatalog::tooltip_hides_name`]). Three lanes
-/// read this table — the weapon-glow chain (decision 0805), the tooltip's enchant line (decision
-/// 0915) and the item-bind confirms (decision 0928) — and one adapter serves all three: two
-/// loaders over one DBC is how a schema drifts.
-///
-/// Sparse on every axis: 102 of the 1460 rows carry a visual, and a row without a name simply has
-/// none. The rest of the table (effects, points, args) belongs to whoever needs it, not here.
+/// `SpellItemEnchantment.dbc`'s visual, enUS name and `Flags`, one load for the glow chain, the
+/// tooltip's enchant line and the bind confirms.
 pub struct EnchantCatalog {
     visuals: HashMap<u32, i32>,
     names: HashMap<u32, String>,
-    /// `Flags` (field 23) for **every** row the table carries, `0` included — so this map's key
-    /// set is also the reference's `enchantTable[id] != 0` ([`EnchantCatalog::has_row`]).
+    /// `Flags` for every row, 0 included, so its keys are the reference's `enchantTable[id] != 0`.
     flags: HashMap<u32, u32>,
 }
 
-/// `Flags & 0x1` — applying this enchant **binds the item to you**. Only two sites in the whole
-/// binary read this bit, and both ask that one question: the enchant-apply gate `0x495d60` @
-/// `495ea3` (`testb $0x1, 0x5c(%eax)` — the sole gate on the "Enchanting this item will bind it to
-/// you." confirm, event 402) and `0x5da2c0` @ `5da313`, which walks an item's seven live enchant
-/// slots asking whether it already carries one (and so has already been asked). 86 of the 1460
-/// shipped rows: the shaman weapon imbues, every rogue poison, Firestone, and the Zul'Gurub /
-/// Ahn'Qiraj head-and-leg enchants. The permanent profession enchants are NOT among them, and
-/// neither are sharpening stones, weightstones, oils or scopes.
+/// `Flags & 0x1`: applying the enchant binds the item. It is the only gate on the bind confirm,
+/// event 402 (`0x495d60`), and `0x5da2c0` reads it to ask whether an item already has one.
 const FLAG_BINDS_THE_ITEM: u32 = 0x1;
 
-/// `Flags & 0x2` — **suppress the tooltip line** for this enchant. The two item-tooltip enchant-line
-/// printers both open with it and return outright when it is set (`6290e4` and `62923e`, each
-/// `testb $0x2, 0x5c(...)` → `jne` straight to the function's `retl`), *before* they read the name
-/// at `+0x34`. 12 shipped rows, and they are one coherent family: the totem-granted weapon imbues
-/// (Flametongue Totem 1-4, Windfury Totem 1-3) plus the warlock Firestone 1-4 and Orb of Fire —
-/// buffs whose source is already visible elsewhere on screen. The *replace* confirm reads the name
-/// with no such gate (`4960d0`), so a suppressed enchant still names itself in that popup.
+/// `Flags & 0x2`: both tooltip enchant-line printers return before reading the name
+/// (`0x6290e4`, `0x62923e`), though the replace confirm still reads it (`0x4960d0`). Set on the
+/// totem imbues, Firestone and Orb of Fire.
 const FLAG_TOOLTIP_HIDES_NAME: u32 = 0x2;
 
 impl EnchantCatalog {
-    /// The ItemVisuals id an enchant glows with, or `None` for an enchant with no visual. The
-    /// value is signed for the same reason as [`ItemVisualCatalog::effects`] — one shipped row
-    /// carries `-1`.
+    /// The ItemVisuals id the enchant glows with; signed, as one shipped row carries `-1`.
     pub fn visual(&self, enchant_id: u32) -> Option<i32> {
         self.visuals.get(&enchant_id).copied()
     }
 
-    /// The enchant's display name as the table stores it — `"Agility +15"`, `"Crusader"`,
-    /// `"Stamina +7"`. `None` for an unknown id or a row with an empty name string.
+    /// The display name as stored (`"Agility +15"`, `"Crusader"`); `None` when empty.
     pub fn name(&self, enchant_id: u32) -> Option<&str> {
         self.names.get(&enchant_id).map(String::as_str)
     }
 
-    /// [`FLAG_BINDS_THE_ITEM`] — whether applying this enchant binds the item to you, the whole
-    /// predicate behind the reference's bind confirm (decision 0928). `false` for an unknown id,
-    /// which is also the reference's answer: it looks the row up first and skips on a miss.
-    ///
-    /// `+0x5c` is field 23, and the field-13 name column chain-locks it: the replace confirm reads
-    /// its two names at `4960d0`/`4960d4` as `0x34(%row,%locale,4)`, and `0x34/4 == 13` is exactly
-    /// [`Self::name`]'s column — so the eight localized name slots run 13..20, `NameFlags` is 21,
-    /// `ItemVisual` 22 (the glow lane's, and `5d9be1: movl 0x58(%eax)` confirms it), and `Flags`
-    /// 23. vmangos's own `SpellItemEnchantmentEntry` agrees field-for-field.
+    /// Whether applying the enchant binds the item ([`FLAG_BINDS_THE_ITEM`]); `false` for an
+    /// unknown id, as the reference skips a missing row.
     pub fn binds_the_item(&self, enchant_id: u32) -> bool {
         self.flag(enchant_id, FLAG_BINDS_THE_ITEM)
     }
 
-    /// [`FLAG_TOOLTIP_HIDES_NAME`] — whether the item tooltip must print NO line for this enchant.
-    /// The enchant-line lane gates on it (`crate::items::enchant_lines` in the app).
+    /// Whether the item tooltip prints no line for the enchant ([`FLAG_TOOLTIP_HIDES_NAME`]).
     pub fn tooltip_hides_name(&self, enchant_id: u32) -> bool {
         self.flag(enchant_id, FLAG_TOOLTIP_HIDES_NAME)
     }
@@ -164,16 +94,13 @@ impl EnchantCatalog {
         self.flags.get(&enchant_id).is_some_and(|f| f & bit != 0)
     }
 
-    /// Whether the id names a real row at all — the reference's `testl %eax,%eax` after every one
-    /// of its `enchantTable[id]` loads. Both confirms need it: an id that names nothing raises no
-    /// popup and blocks no bind.
+    /// Whether the id names a row, the reference's null test after each `enchantTable[id]`; a
+    /// missing row raises no confirm.
     pub fn has_row(&self, enchant_id: u32) -> bool {
         self.flags.contains_key(&enchant_id)
     }
 
-    /// Build from explicit maps — tests and synthetic fixtures. `flags` is field 23 per row and
-    /// doubles as the row census, so a fixture that only sets `names`/`visuals` must list its ids
-    /// there too for [`Self::has_row`] to see them.
+    /// Build from explicit maps, for tests; `flags` is also the row set [`Self::has_row`] reads.
     pub fn from_rows(
         visuals: HashMap<u32, i32>,
         names: HashMap<u32, String>,
@@ -186,37 +113,36 @@ impl EnchantCatalog {
         }
     }
 
-    /// Iterate `(enchant id, ItemVisuals id)` for the rows that carry one (order unspecified) —
-    /// the cross-table join checks read it.
+    /// `(enchant id, ItemVisuals id)` for the rows that carry one, in no order.
     pub fn iter_visuals(&self) -> impl Iterator<Item = (u32, i32)> + '_ {
         self.visuals.iter().map(|(k, v)| (*k, *v))
     }
 
-    /// How many enchants carry a glow — the glow lane's startup census.
+    /// How many enchants carry a glow.
     pub fn visual_count(&self) -> usize {
         self.visuals.len()
     }
 
-    /// How many enchants carry a printable name — the tooltip lane's.
+    /// How many enchants carry a name.
     pub fn name_count(&self) -> usize {
         self.names.len()
     }
 }
 
-/// `ItemVisuals.dbc` — 6 fields / 24-byte records in build 5875.
+/// `ItemVisuals.dbc`: 6 fields, 24-byte records.
 pub(crate) fn item_visuals_schema() -> Schema {
     let mut s = Schema::new("ItemVisuals");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
     for i in 0..ITEM_VISUAL_SLOTS {
         s.add_field(SchemaField::new(
             format!("Effect{i}"),
-            FieldType::UInt32, // signed in use — see the module doc's skip rules
+            FieldType::UInt32, // read signed, as the reference does
         ));
     }
     s
 }
 
-/// `ItemVisualEffects.dbc` — 2 fields / 8-byte records in build 5875.
+/// `ItemVisualEffects.dbc`: 2 fields, 8-byte records.
 pub(crate) fn item_visual_effects_schema() -> Schema {
     let mut s = Schema::new("ItemVisualEffects");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -224,10 +150,9 @@ pub(crate) fn item_visual_effects_schema() -> Schema {
     s
 }
 
-/// `SpellItemEnchantment.dbc` — 24 fields / 96-byte records in build 5875. Fields 13 (`Name0`)
-/// and 22 (`ItemVisual`) are read; the rest are typed to keep the field-count check exact. The
-/// eight `Name_Lang` slots + their mask are the 1.12 localized-string block (only `enUS`, the
-/// first, is filled).
+/// `SpellItemEnchantment.dbc`: 24 fields, 96-byte records. The reference reads the enUS name at
+/// `+0x34` (field 13, `0x4960d0`), the visual at `+0x58` (field 22, `0x5d9be1`) and `Flags` at
+/// `+0x5c` (field 23).
 pub(crate) fn spell_item_enchantment_schema() -> Schema {
     let mut s = Schema::new("SpellItemEnchantment");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -245,15 +170,13 @@ pub(crate) fn spell_item_enchantment_schema() -> Schema {
     s
 }
 
-/// Load `ItemVisuals.dbc` + `ItemVisualEffects.dbc` off the patch chain and join them into an
-/// [`ItemVisualCatalog`] — the client's per-slot skip rules (module doc) applied at load, so a
-/// resolved slot is always a real model path.
+/// Load and join `ItemVisuals.dbc` and `ItemVisualEffects.dbc`, applying the reference's skips.
 pub fn load_item_visual_catalog(chain: &mut Chain) -> Result<ItemVisualCatalog> {
     let bytes = chain
         .read_file(ITEM_VISUAL_EFFECTS)
         .with_context(|| format!("reading {ITEM_VISUAL_EFFECTS}"))?;
     let rs = parse(&bytes, item_visual_effects_schema(), "ItemVisualEffects")?;
-    // `str_at` already drops the empty string — the reference's own `cmpb $0,(%eax)` skip.
+    // `str_at` drops an empty path, as the reference skips one.
     let mut effects: HashMap<u32, String> = HashMap::with_capacity(rs.records().len());
     for r in rs.records() {
         let (Some(id), Some(model)) = (u32_at(r, 0), str_at(&rs, r, 1)) else {
@@ -280,8 +203,7 @@ pub fn load_item_visual_catalog(chain: &mut Chain) -> Result<ItemVisualCatalog>
     Ok(ItemVisualCatalog { visuals })
 }
 
-/// Load `SpellItemEnchantment.dbc`'s two consumer columns off the patch chain — one parse, both
-/// lanes (see [`EnchantCatalog`]).
+/// Load the [`EnchantCatalog`] from `SpellItemEnchantment.dbc`.
 pub fn load_enchant_catalog(chain: &mut Chain) -> Result<EnchantCatalog> {
     let bytes = chain
         .read_file(SPELL_ITEM_ENCHANTMENT)
@@ -296,13 +218,13 @@ pub fn load_enchant_catalog(chain: &mut Chain) -> Result<EnchantCatalog> {
     let mut flags = HashMap::with_capacity(rs.records().len());
     for r in rs.records() {
         let Some(id) = u32_at(r, 0) else { continue };
-        // Every row lands here, `Flags == 0` included — the map's key set IS the row census.
+        // Every row, `Flags == 0` included: the keys are the row set.
         flags.insert(id, u32_at(r, 23).unwrap_or(0));
         let visual = u32_at(r, 22).unwrap_or(0) as i32;
         if visual != 0 {
             visuals.insert(id, visual);
         }
-        // `str_at` drops the empty string, so a nameless row simply never lands.
+        // `str_at` drops an empty name.
         if let Some(name) = str_at(&rs, r, 13) {
             names.insert(id, name);
         }
@@ -318,8 +240,6 @@ pub fn load_enchant_catalog(chain: &mut Chain) -> Result<EnchantCatalog> {
 mod tests {
     use super::*;
 
-    /// The two glow tables as they actually ship, including both traps: row **28**'s two
-    /// out-of-range garbage slots and the reference's per-slot skip.
     #[test]
     fn real_item_visuals_join_their_effect_models() {
         let data = crate::wow_data_or_skip!();
@@ -327,7 +247,6 @@ mod tests {
         let cat = load_item_visual_catalog(&mut chain).expect("load ItemVisuals");
         assert_eq!(cat.len(), 34, "34 ItemVisuals rows in build 5875");
 
-        // The common shape: one effect repeated across all five attach slots.
         let all_blue = ["Spells\\Enchantments\\BlueGlow_Med.mdx"; ITEM_VISUAL_SLOTS];
         let got = cat.effects(2).expect("visual 2");
         assert_eq!(
@@ -336,7 +255,6 @@ mod tests {
             "visual 2 glows on every slot"
         );
 
-        // A single-slot shape — slot 3 only.
         let one = cat.effects(1).expect("visual 1");
         assert_eq!(
             one[3].as_deref(),
@@ -358,8 +276,7 @@ mod tests {
             Some("Spells\\Enchantments\\YellowGlow_Low.mdx")
         );
 
-        // **The garbage row.** Slots 0 and 3 hold 90148992 / 455344256 — far past the effect
-        // table's maxId (152) — and the reference's `jg` skips them.
+        // Row 28: slots 0 and 3 hold 90148992 and 455344256, past the effect table's max id (152).
         let junk = cat.effects(28).expect("visual 28");
         assert_eq!(
             junk.each_ref().map(|s| s.is_some()),
@@ -377,8 +294,6 @@ mod tests {
         assert!(cat.effects(9999).is_none(), "past maxId");
     }
 
-    /// The display half of the join, on real data: 365 of the 29 604 displays carry a visual, five
-    /// of them the unresolvable `-1`, and every other one resolves to at least one glow model.
     #[test]
     fn real_displays_carrying_a_visual_all_resolve() {
         let data = crate::wow_data_or_skip!();
@@ -415,9 +330,7 @@ mod tests {
         );
     }
 
-    /// The enchant half: `SpellItemEnchantment` field 22 lands in the ItemVisuals id space on
-    /// every shipped row but one (`-1`) — the independent corroboration that column 22 (record
-    /// `+0x58`) is the visual, and the three shaman weapon buffs to name it.
+    /// Every shipped field-22 value but one `-1` names an ItemVisuals row, which pins the column.
     #[test]
     fn real_enchant_visuals_resolve() {
         let data = crate::wow_data_or_skip!();
@@ -453,27 +366,20 @@ mod tests {
         assert_eq!(enchants.visual(929), None);
     }
 
-    /// The **name** column (field 13), on real data — the string the tooltip's enchant line
-    /// prints (decision 0915). Pinned on the case that opened the lane plus one of each other
-    /// shape, and on the two properties the consumer rests on: the name is stored in the table's
-    /// own word order (`"Agility +15"`, NOT a reformat), and it is independent of the visual
-    /// column — a glowing enchant and a plain +stat one both have one.
+    /// Names are stored in the table's own word order (`"Agility +15"`), glowing or not.
     #[test]
     fn real_enchant_names_read_off_the_table() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let enchants = load_enchant_catalog(&mut chain).expect("load SpellItemEnchantment");
 
-        // 2564 = the permanent weapon enchant on the director's Hatchet of Sundered Bone: a name
-        // AND a visual (125 → GreenGlow_Low), the two columns joined on one row.
+        // 2564, a permanent weapon enchant: a name and a visual (125, GreenGlow_Low) on one row.
         assert_eq!(enchants.name(2564), Some("Agility +15"));
         assert_eq!(enchants.visual(2564), Some(125));
-        // Named, no glow — the +stat family.
+        // Named, no glow: the +stat family.
         assert_eq!(enchants.name(241), Some("Weapon Damage +2"));
         assert_eq!(enchants.name(929), Some("Stamina +7"));
-        // Glow, and a name that is a proper noun rather than a stat phrase.
         assert_eq!(enchants.name(1900), Some("Crusader"));
-        // An id past the table names nothing at all.
         assert_eq!(enchants.name(999_999), None);
         assert!(
             enchants.name_count() > enchants.visual_count(),
@@ -481,26 +387,15 @@ mod tests {
         );
     }
 
-    /// The `Flags` column (field 23) as it actually ships — the two bits the reference reads, and
-    /// the shape of each one's set. Written the way the mapping was *settled*: the name column at
-    /// field 13 is chain-locked by the binary reading it as `0x34(%row,%locale,4)`, `ItemVisual`
-    /// at 22 by `5d9be1: movl 0x58(%eax)`, so `Flags` is 23 (`+0x5c`) — which is exactly what the
-    /// two `testb $0x1,0x5c` / `testb $0x2,0x5c` sites read.
-    ///
-    /// A column slip fails this hard, because both sets are *characterized*, not just counted: bit
-    /// 0's members are weapon imbues / poisons / raid enchants and bit 1's are exactly the twelve
-    /// totem-and-Firestone rows. This also pins the negative that surprised us and is worth not
-    /// re-learning: the permanent profession enchants (Agility +15, Crusader, Fiery Weapon) and
-    /// every consumable-applied enchant (stones, oils, scopes) have `Flags == 0`, so the bind
-    /// confirm does NOT fire for them.
+    /// Both bits' rows are named one by one, so a column slip fails.
     #[test]
     fn real_enchant_flags_column() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let e = load_enchant_catalog(&mut chain).expect("load SpellItemEnchantment");
 
-        // Bit 0 — the bind confirm's gate. 86 rows: the shaman imbues, the rogue poisons, the
-        // warlock Firestone, and the ZG/AQ head-and-leg enchants.
+        // Bit 0, the bind confirm's gate, on 86 rows: the shaman imbues, the rogue poisons,
+        // Firestone and the Zul'Gurub and Ahn'Qiraj head and leg enchants.
         for (id, name) in [
             (1u32, "Rockbiter 3"),
             (7, "Deadly Poison"),
@@ -510,7 +405,7 @@ mod tests {
         ] {
             assert!(e.binds_the_item(id), "{id} ({name}) must carry Flags & 1");
         }
-        // The negative half — the one that makes this bit counter-intuitive.
+        // Profession enchants and consumables (stones, oils, scopes) do not bind.
         for (id, name) in [
             (2564u32, "Agility +15"),
             (1900, "Crusader"),
@@ -525,7 +420,7 @@ mod tests {
             );
         }
 
-        // Bit 1 — the tooltip's name suppression. Exactly twelve rows, all one family.
+        // Bit 1, the tooltip line suppression: exactly twelve rows.
         let hidden: std::collections::BTreeSet<u32> =
             (0..3000).filter(|&id| e.tooltip_hides_name(id)).collect();
         assert_eq!(
@@ -535,11 +430,10 @@ mod tests {
                 .collect(),
             "the totem-granted imbues (Flametongue/Windfury Totem), Orb of Fire and Firestone 1-4"
         );
-        // Suppression is about the tooltip LINE, not the row: the names are still there, and the
-        // replace confirm reads them ungated (`4960d0`).
+        // The name stays, for the replace confirm.
         assert_eq!(e.name(124), Some("Flametongue Totem 1"));
 
-        // The row census the confirms gate on — present for a real id, absent past the table.
+        // The row set the confirms gate on.
         assert!(e.has_row(2564) && e.has_row(1) && !e.has_row(999_999));
     }
 }
diff --git a/crates/benilla-formats/src/itembagfamily.rs b/crates/benilla-formats/src/itembagfamily.rs
index 4bfeac10..d3b48740 100644
--- a/crates/benilla-formats/src/itembagfamily.rs
+++ b/crates/benilla-formats/src/itembagfamily.rs
@@ -1,21 +1,7 @@
-//! ItemBagFamily.dbc — the container-family names, i.e. what a specialised bag *accepts*:
-//! "Arrows", "Bullets", "Soul Shards", "Herbs", "Enchanting Supplies", "Engineering Supplies",
-//! "Keys".
-//!
-//! One consumer, and it is the reason this table exists here at all: the inventory error line's
-//! **reason 16** substitution (`ERR_WRONG_BAG_TYPE_SUBCLASS` = *"Only %s can be placed in
-//! that."*). wow-re `system/ui/scratch/inventory-change-failure-display.md` §6 carves the helper
-//! `0x5ede00(player, bagSlot)`: it resolves the named bag as an item, maps it through `0x5da050`
-//! into the `[0xc0dc38]` row table (bound `[0xc0dc3c]`), reads the localized name at
-//! `[row + 4*[0xc0e080] + 4]` — i.e. field 1 at the active locale — and calls
-//! `DisplayError(0x118, thatName)` itself. **Despite the errorId's `_SUBCLASS` name this is not
-//! ItemSubClass.dbc**: the row is keyed by the bag's `BagFamily`, which is what makes the line
-//! read "Only Arrows can be placed in that." for a quiver rather than naming the bag's own type.
-//!
-//! Record layout (8 rows in the shipped 5875 file, verified by loading it): `ID@0`,
-//! `Name_Lang@1..8`, `NameFlags@9`. **Ids are not contiguous** — 0,1,2,3,6,7,8,9, with 4 and 5
-//! absent — so this is an id-keyed lookup, never an index. Row 0's name is the literal string
-//! `"NONE"`; see [`ItemBagFamilyCatalog::name`].
+//! `ItemBagFamily.dbc`: what a specialised bag accepts ("Arrows", "Soul Shards", "Keys", …), the
+//! `%s` of inventory error reason 16, `ERR_WRONG_BAG_TYPE_SUBCLASS`. Despite that name the
+//! reference (`0x5ede00`) keys the row by the bag's `BagFamily`, not its subclass, through
+//! `0x5da050` into `[0xc0dc38]`. Ids skip 4 and 5, so this is keyed, never indexed.
 
 use std::collections::HashMap;
 
@@ -33,20 +19,14 @@ pub struct ItemBagFamilyCatalog {
 }
 
 impl ItemBagFamilyCatalog {
-    /// What family `id` is *called* — the `%s` of "Only %s can be placed in that."
-    ///
-    /// **Family 0 yields `None`**, not the row's literal `"NONE"`. 0 means "an ordinary item /
-    /// ordinary bag", so a resolved 0 would render "Only NONE can be placed in that." — the
-    /// caller wants the generic line there. Unreachable on this wire in practice (the server
-    /// only sends reason 16 for a *specialised* container mismatch), so this is a guard on a
-    /// nonsense string rather than a modelled branch.
+    /// The family's name; `None` for family 0, an ordinary bag, whose row reads "NONE". The
+    /// server sends reason 16 only for a specialised bag.
     pub fn name(&self, id: u32) -> Option<&str> {
         (id != 0)
             .then(|| self.names.get(&id).map(String::as_str))
             .flatten()
     }
 
-    /// Row count, for the load log.
     pub fn len(&self) -> usize {
         self.names.len()
     }
@@ -87,11 +67,6 @@ pub fn load_item_bag_families(chain: &mut Chain) -> Result<ItemBagFamilyCatalog>
 mod tests {
     use super::load_item_bag_families;
 
-    /// The shipped 5875 table, read as data rather than assumed: the ids our
-    /// `ItemInfo::bag_family` doc already names must each carry the family's *plural* spelling,
-    /// which is what makes "Only Arrows can be placed in that." read correctly. Also pins the
-    /// non-contiguity (4 and 5 absent) that makes this an id lookup, and family 0's guard.
-    /// Skips without client data.
     #[test]
     fn the_shipped_families_are_named_as_the_error_line_needs() {
         let data = crate::wow_data_or_skip!();
@@ -105,10 +80,9 @@ mod tests {
         assert_eq!(cat.name(7), Some("Enchanting Supplies"));
         assert_eq!(cat.name(8), Some("Engineering Supplies"));
         assert_eq!(cat.name(9), Some("Keys"), "the keyring family");
-        // 4 and 5 genuinely do not ship — the gap is why this is keyed, not indexed.
+        // 4 and 5 do not ship.
         assert_eq!(cat.name(4), None);
         assert_eq!(cat.name(5), None);
-        // Row 0 exists and is literally "NONE"; the accessor refuses it (see `name`).
         assert_eq!(cat.name(0), None, "family 0 must not render as \"NONE\"");
         assert_eq!(cat.len(), 8, "the whole shipped table");
     }
diff --git a/crates/benilla-formats/src/itemclass.rs b/crates/benilla-formats/src/itemclass.rs
index feec6417..2c353b05 100644
--- a/crates/benilla-formats/src/itemclass.rs
+++ b/crates/benilla-formats/src/itemclass.rs
@@ -1,22 +1,7 @@
-//! ItemClass.dbc — what an item's **class** is *called*: "Weapon", "Armor", "Container",
-//! "Trade Goods", "Quiver".
-//!
-//! One consumer, and it is what makes the table worth loading: `GetItemInfo`'s fifth return
-//! (`itemType`). **Byte-verified** at the registered binding `0x48e070`, which reads the cache
-//! record's class (`[record+0]`), bounds-checks it against the row count at `ds:0xc0dc28`,
-//! indexes the row array at `ds:0xc0dc24`, and pushes `[row + 4*[0xc0e080] + 0xc]` — field 3 at
-//! the active locale, i.e. `ClassName_Lang`. An out-of-range class, or a null row, pushes the
-//! empty string at `0x882748` instead (`0x48e236`).
-//!
-//! Record layout (16 rows in the shipped 5875 file, verified by loading it): `ClassID@0`,
-//! `SubClassMapID@1`, `Flags@2`, `ClassName_Lang@3..10`, `ClassNameFlags@11`. Ids are 0..=15 and
-//! contiguous, but this is keyed rather than indexed for the same reason every other catalog here
-//! is: a `class` value off the wire is data, not an index we control.
-//!
-//! Five of the sixteen names carry an `(OBSOLETE)` suffix in the shipped data (`Jewelry`,
-//! `Generic`, `Money`, `Permanent`, plus `Quiver`'s first two subclasses elsewhere). They are
-//! transcribed as-is: the reference pushes the row's string unfiltered, and an addon comparing
-//! against what the live client returns must see the same bytes.
+//! `ItemClass.dbc`: an item class's name, `GetItemInfo`'s fifth return (`itemType`). The binding
+//! (`0x48e070`) bounds the class by the row count (`0xc0dc28`), indexes the rows (`0xc0dc24`) and
+//! pushes the name unfiltered, `(OBSOLETE)` suffixes included, or "" when there is no row
+//! (`0x48e236`).
 
 use std::collections::HashMap;
 
@@ -34,13 +19,11 @@ pub struct ItemClassCatalog {
 }
 
 impl ItemClassCatalog {
-    /// What class `id` is *called* — `GetItemInfo`'s `itemType`. `None` for a class with no row,
-    /// which the reference renders as the empty string (see the module header).
+    /// The class's name; `None` where the reference pushes the empty string.
     pub fn name(&self, id: u32) -> Option<&str> {
         self.names.get(&id).map(String::as_str)
     }
 
-    /// Row count, for the load log.
     pub fn len(&self) -> usize {
         self.names.len()
     }
@@ -83,15 +66,7 @@ pub fn load_item_classes(chain: &mut Chain) -> Result<ItemClassCatalog> {
 mod tests {
     use super::load_item_classes;
 
-    /// The shipped 5875 table, read as data. The four names pinned here are the ones the corpus
-    /// asserts against *by hand*: `Bagnon_Core/localization.lua:94-95` ships
-    /// `BAGNON_ITEMTYPE_CONTAINER = "Container"` / `BAGNON_ITEMTYPE_QUIVER = "Quiver"` as the
-    /// values it expects `GetItemInfo`'s fifth return to have, and re-derives them at runtime from
-    /// items 4500 (a backpack) and 8218 (a quiver) — so these strings are the live client's own
-    /// answer, checked by an addon author against a real 1.12 realm.
-    ///
-    /// The `(OBSOLETE)` suffixes are pinned too: they are in the shipped bytes and the reference
-    /// does not strip them. Skips without client data.
+    /// Bagnon (`Bagnon_Core/localization.lua:94-95`) expects "Container" and "Quiver" here.
     #[test]
     fn the_shipped_classes_are_named_as_getiteminfo_returns_them() {
         let data = crate::wow_data_or_skip!();
@@ -105,10 +80,9 @@ mod tests {
         assert_eq!(cat.name(7), Some("Trade Goods"));
         assert_eq!(cat.name(11), Some("Quiver"), "Bagnon's own expectation");
         assert_eq!(cat.name(15), Some("Miscellaneous"));
-        // Transcribed, not tidied — the reference pushes the row string unfiltered.
+        // The reference pushes the row string unfiltered.
         assert_eq!(cat.name(3), Some("Jewelry(OBSOLETE)"));
         assert_eq!(cat.name(10), Some("Money(OBSOLETE)"));
-        // Past the table: no row, which the binding renders as "" (`0x48e236`).
         assert_eq!(cat.name(16), None);
         assert_eq!(cat.len(), 16, "the whole shipped table");
     }
diff --git a/crates/benilla-formats/src/items.rs b/crates/benilla-formats/src/items.rs
index 8762a1a1..85c3f773 100644
--- a/crates/benilla-formats/src/items.rs
+++ b/crates/benilla-formats/src/items.rs
@@ -1,28 +1,9 @@
-//! `ItemDisplayInfo.dbc` adapter — displayId → held-item / worn-equipment visual identity (decision
-//! 0072 slice 1: combat presence, held items via the display chain).
+//! `ItemDisplayInfo.dbc`: a display id to a held item's or worn equipment's visual identity. 23
+//! fields and 92-byte records in 5875, both checked by the reference loader (`0x547590`).
 //!
-//! Layout — **TRIPLE-VERIFIED** against build 5875 (`decisions/0072`: our raw dump
-//! `record_count=29604`; wow-re's `charactermodel` disasm; wow-re's independent dbc-node schema
-//! catalog): 23 fields / 92-byte records. Columns: `0` id (key) · `1`/`2` model name L/R (string) ·
-//! `3`/`4` model texture L/R (string) · `5` icon (string, unread — no consumer yet) · `6`-`8`
-//! geosetGroup[0..2] (u32) · `9` **flags** (u32 — the client's `ItemDisplayInfo_inmem[+0x24]`, of
-//! which only **bit 0** is read: the guild-emblem tabard, [`ItemDisplay::takes_guild_emblem`]) ·
-//! `10` the ranged-weapon `SpellVisual.dbc`
-//! id (u32 — the substitute visual a RANGED-attribute spell with no own visual borrows for its
-//! fire animation; byte-verified `0x60d493: mov eax,[eax+0x28]`, wow-re
-//! `throw-ranged-attack-anim.md`) · `11` the `ItemGroupSounds.dbc` id
-//! (u32 — the pickup/place sound group; byte-verified `0x458008: mov eax,[edx+0x2c]`, wow-re
-//! `system/sound/scratch/item-pickup-place-sound.md`, corroborated 20513/20513 valid ids on the
-//! real DBC) · `12`/`13` helm-vis (u32) · `14`-`21` the 8 body-region textures, in **ArmUpper,
-//! ArmLower, Hand, TorsoUpper, TorsoLower, LegUpper, LegLower, Foot** order (string) · `22` the
-//! **`ItemVisuals.dbc` id** — the item's intrinsic glow (i32; byte-verified `0x47a200: mov
-//! edx,[esi+0x58]`, the held-item attach handing it on — decision 0805,
-//! [`crate::ItemVisualCatalog`]).
-//!
-//! **Trap, load-bearing:** `model` and `model_texture` are **independently-resolved basenames** in
-//! the same `Item\ObjectComponents\<dir>\` folder — never derive one from the other. Real
-//! counter-example: the Worn Wooden Shield row carries model `Shield_Round_A_01.mdx` (→ `.m2` on
-//! disk) alongside texture `Buckler_Damaged_A_01Purple` (no relation to the model's own name).
+//! A row's model and texture are independently resolved basenames in the same
+//! `Item\ObjectComponents\<dir>\` folder; never derive one from the other. The Worn Wooden Shield
+//! pairs model `Shield_Round_A_01.mdx` with texture `Buckler_Damaged_A_01Purple`.
 
 use std::collections::HashMap;
 
@@ -35,123 +16,71 @@ use crate::models::model_path;
 
 const ITEM_DISPLAY_INFO: &str = "DBFilesClient\\ItemDisplayInfo.dbc";
 
-/// One `ItemDisplayInfo` row: the visual identity a held item or worn equipment display resolves to.
-///
-/// `model`/`model_texture` carry **no directory prefix** — the app layer owns the
-/// `Item\ObjectComponents\<dir>\` join, since `<dir>` depends on the item's inventory type (Weapon,
-/// Shield, Head, …), which isn't a column in this DBC.
+/// One `ItemDisplayInfo` row: the visual identity of a held item or worn equipment. Basenames carry
+/// no directory: the `Item\ObjectComponents\<dir>\` join belongs to the app, since `<dir>` follows
+/// the inventory type, which is not a column here.
 #[derive(Debug, Clone, Default)]
 pub struct ItemDisplay {
-    /// Left/right model basename (index 0/1), the existing `.mdx`→`.m2` normalizer applied
-    /// (lowercased, extension swapped) — see [`crate::models::model_path`]. No directory. `None` for
-    /// an empty column (most rows carry only the left slot; two-handed/dual visuals use both).
+    /// Left and right model basenames, normalized by [`crate::models::model_path`].
     pub model: [Option<String>; 2],
-    /// Left/right model-texture basename (index 0/1) — raw, **no extension** (the app appends
-    /// `.blp`) and **not** derived from [`Self::model`] (see the module trap note).
+    /// Left and right texture basenames, raw and extensionless; never derived from [`Self::model`].
     pub model_texture: [Option<String>; 2],
-    /// `geosetGroup[0..2]` — worn-equipment geoset selectors (robes etc.); `0` where unauthored.
-    /// Unused by held items.
+    /// Worn-equipment geoset selectors, 0 where unauthored.
     pub geoset_groups: [u32; 3],
-    /// The 8 body-region texture overrides this display paints on, in ArmUpper/ArmLower/Hand/
-    /// TorsoUpper/TorsoLower/LegUpper/LegLower/Foot order. `None` per-slot where this display
-    /// doesn't touch that region (most held-item rows: all 8 empty).
+    /// Body-region textures, in ArmUpper, ArmLower, Hand, TorsoUpper, TorsoLower, LegUpper,
+    /// LegLower, Foot order.
     pub region_textures: [Option<String>; 8],
-    /// A helm's `HelmetGeosetVisData` row ids — `[male, female]` (cols 12/13; VERIFIED wow-re
-    /// RF-0083: `ItemDisplayInfo_inmem[+0x30 + sex*4]`). `0` = no vis row (non-helm displays).
+    /// A helm's `HelmetGeosetVisData` rows, `[male, female]`, 0 for none (`0x4799a0` reads
+    /// `+0x30 + sex * 4`).
     pub helmet_vis: [u32; 2],
-    /// The inventory icon (col 5) as a ready `Interface\Icons\…` MPQ path, extensionless as the
-    /// DBC stores names (the BLP loader appends it). Unlike the model columns there is no
-    /// variable directory to join — the icon dir is fixed — so this one ships app-ready, same as
-    /// `SpellCatalog`'s icons. `None` on the ~26% of rows that are icon-less visual attachments.
-    /// Anchored on live server-truth pairings (vmangos `item_template.display_id`, the values the
-    /// real wire answers): Worn Shortsword 1542 → `INV_Sword_04`, Tough Jerky 2473 →
-    /// `INV_Misc_Food_16`, Worn Wooden Shield 18730 → `INV_Shield_09`, Hearthstone 6418 →
-    /// `INV_Misc_Rune_01`.
+    /// The inventory icon as an extensionless `Interface\Icons\…` path, ready to load.
     pub icon: Option<String>,
-    /// The `ItemGroupSounds.dbc` id (col 11) — the item's pickup/place/use sound group
-    /// ([`crate::item_sounds`]). `0` = no group (the display drags silently), matching the client's
-    /// bounds-check-and-return (`0x45800b`).
+    /// The `ItemGroupSounds.dbc` pickup and place sound group (`0x458008`); 0 is silent, as the
+    /// reference's bounds check returns (`0x45800b`).
     pub group_sounds: u32,
-    /// The ranged-weapon `SpellVisual.dbc` id (col 10) — the SUBSTITUTE visual a RANGED-attribute
-    /// spell with no own visual borrows from the equipped ranged weapon (the client's `0x60d450`
-    /// fallback: how Throw/Auto Shot get their fire clips — wow-re `throw-ranged-attack-anim.md`).
-    /// `0` on every non-ranged display; only three distinct nonzero ids exist across the real
-    /// table (thrown 98 · bow 5 · gun/rifle 224).
+    /// The `SpellVisual.dbc` id a ranged-attribute spell borrows from the equipped ranged weapon,
+    /// field by field where its own visual leaves a 0 (`VisualStages::merged_over_weapon`,
+    /// `0x60d450`, read at `0x60d493`).
     pub spell_visual: u32,
-    /// The flags word (col 9) — the client's `ItemDisplayInfo_inmem[+0x24]`. Only **bit 0** has a
-    /// reader in the image, and it means *this garment takes the wearer's guild emblem*
-    /// ([`Self::takes_guild_emblem`]); bit 1 appears on four chest/robe rows with no reader found.
-    /// Carried whole rather than as a bool so the unread bits stay visible.
+    /// The flags word, the reference's `+0x24`. Only bit 0 is read, [`Self::takes_guild_emblem`];
+    /// bit 1, set on four chest and robe rows, has no reader.
     pub flags: u32,
-    /// The `ItemVisuals.dbc` id (col 22) — the display's **intrinsic glow**: the permanent weapon
-    /// glows, resolved to up to five `Spells\Enchantments\*.mdx` models by
-    /// [`crate::ItemVisualCatalog`] (decision 0805). **Signed**, because the client reads it that
-    /// way (`0x4798c0`'s `jle` gate): `0` = none on 29 239 of the 29 604 rows, and **five shipped
-    /// rows carry `-1`**, which is also none.
+    /// The `ItemVisuals.dbc` id of the display's intrinsic weapon glow (`0x47a200`). Signed, as the
+    /// reference's `jle` gate reads it (`0x4798c0`): 0 and `-1` both mean none.
     pub item_visual: i32,
 }
 
 impl ItemDisplay {
-    /// The `HelmetGeosetVisData` row pair (`[male, female]`) this display hides hair / facial hair /
-    /// ears with — **only when the display is actually a worn helm**, i.e. it names a head model.
-    ///
-    /// The gate is the point. `helmet_vis` is authored on 1314 of the 29604 shipped rows, and **12
-    /// of those name no model at all** — jewellery-shaped rows (15676 is an
-    /// `INV_Jewelry_Amulet_01` icon with no mesh) that still carry a full hide mask. Nothing wears
-    /// them: with no `ModelName` there is no helm to attach and no helm to tuck hair under. But
-    /// `CreatureDisplayInfoExtra`'s head column points **126 character-model NPC displays** at
-    /// exactly those rows, and honouring the mask there strips the NPC's hairstyle to the bare
-    /// scalp (geoset 1), its ears to the tucked variant (701) and its earrings/beard to their
-    /// group bases — while 1.12.1 renders them in full (B93: Jubie Gadgetspring, display 7969 →
-    /// extra 5503 → head display **15676** → vis row **306** = `[446,478,510,222,238]`, every
-    /// column with the gnome bit `1<<7` set).
-    ///
-    /// **The gate is `ModelName[0]` alone** — on-disk column 1, the LEFT slot — VERIFIED at the
-    /// bytes (wow-re RF-0085, `0x4799c1`): the head-slot handler `0x4799a0` loads
-    /// `[[cc+0x4a8] + 4]` and `cmp byte ptr [ecx],0`, a **string-emptiness** test, jumping straight
-    /// to the epilogue `0x479b33` past the whole geoset-vis tail. Column 2 (the right slot) is
-    /// never consulted, and neither is the helm M2's load result — `0x4798c0`'s return is clobbered
-    /// untested, so this is decided synchronously off the DBC row, never off whether the model
-    /// resolved. On the shipped table the two readings coincide (41 rows fill only the right slot;
-    /// **none** of them carries a vis pair), which the test asserts rather than assumes.
+    /// The `HelmetGeosetVisData` pair this display hides hair and ears with, only when it names a
+    /// left model: the reference's head-slot handler (`0x4799a0`) tests `ModelName[0]` for an empty
+    /// string (`0x4799c1`) and skips the whole geoset-vis tail (`0x479b33`), never reading the
+    /// right slot or the model's load result. Twelve model-less rows carry a mask that 126 NPC head
+    /// displays point at, and the reference draws those NPCs' hair in full.
     pub fn worn_helm_vis(&self) -> Option<[u32; 2]> {
         self.model[0].is_some().then_some(self.helmet_vis)
     }
 
-    /// Whether this display is a **guild-emblem tabard** — the garment whose torso art the wearer's
-    /// guild tabard replaces (`flags & 1`, the client's `0x472ca4 test byte ptr [rec+0x24],1` on the
-    /// tabard equip slot). A tabard that clears the bit keeps its own `TorsoUpper`/`TorsoLower`
-    /// columns; one that sets it has those columns overwritten by the three
-    /// `Textures\GuildEmblems\` layers ([`crate::GuildEmblem`]) whenever the wearer's guild
-    /// identity is known.
-    ///
-    /// **Eleven** of the 29604 shipped rows carry a nonzero `flags`; **seven** set bit 0, and they
-    /// are exactly the tabard-shaped ones (Crusader ×2, Default ×2, Stromgard, Hillsbrad, and
-    /// **20621** — the row item 5976 *Guild Tabard* wears, the only one any 1.12.1 item template
-    /// points at). The other four set bit **1** on chest/robe rows (Samurai plate, the Horde robe
-    /// family) and nothing reads it.
+    /// Whether the wearer's guild emblem replaces this tabard's torso art (`flags & 1`, tested at
+    /// `0x472ca4` on the tabard slot). Seven shipped rows set it, all tabards.
     pub fn takes_guild_emblem(&self) -> bool {
         self.flags & FLAG_GUILD_EMBLEM_TABARD != 0
     }
 }
 
-/// [`ItemDisplay::flags`] bit 0 — see [`ItemDisplay::takes_guild_emblem`].
 const FLAG_GUILD_EMBLEM_TABARD: u32 = 0x1;
 
-/// `ItemDisplayInfo.dbc`, keyed by `displayId` (the id `ItemDisplayInfoID`/`UNIT_VIRTUAL_ITEM_SLOT_DISPLAY`
-/// resolve into — decision 0072).
+/// `ItemDisplayInfo.dbc` by display id, the id `ItemDisplayInfoID` and
+/// `UNIT_VIRTUAL_ITEM_SLOT_DISPLAY` name.
 pub struct ItemDisplayCatalog {
     displays: HashMap<u32, ItemDisplay>,
 }
 
 impl ItemDisplayCatalog {
-    /// Build a catalog from an explicit row map — for tests and synthetic fixtures, the twin of
-    /// `SpellCatalog::from_displays`. The live path is [`load_item_display_catalog`].
+    /// A catalog from an explicit row map, for tests and fixtures.
     pub fn from_displays(displays: HashMap<u32, ItemDisplay>) -> Self {
         ItemDisplayCatalog { displays }
     }
 
-    /// Look up a display id, or `None` if unknown.
     pub fn get(&self, display_id: u32) -> Option<&ItemDisplay> {
         self.displays.get(&display_id)
     }
@@ -164,19 +93,13 @@ impl ItemDisplayCatalog {
         self.displays.is_empty()
     }
 
-    /// Iterate `(displayId, row)` (order unspecified) — the cross-DBC join checks use it, and so
-    /// does the corpus sweep that has to name *which* display reaches a model
-    /// (`benilla-extract entityuvscan`). The id is carried because a census that cannot join back
-    /// to a row id answers "how many" and never "which one".
+    /// Every `(displayId, row)`, unordered.
     pub fn iter(&self) -> impl Iterator<Item = (u32, &ItemDisplay)> {
         self.displays.iter().map(|(&id, d)| (id, d))
     }
 }
 
-/// `ItemDisplayInfo.dbc` — 23 fields / 92-byte records in build 5875 (see the module doc for the
-/// column pins). Unpinned integer columns are still typed `UInt32` (matching the file's own record
-/// stride) even though nothing reads them, so the schema's field-count check against the real header
-/// stays exact.
+/// All 23 columns, the unread ones included, so the field-count check against the header is exact.
 pub(crate) fn item_display_info_schema() -> Schema {
     let mut s = Schema::new("ItemDisplayInfo");
     for (name, ty) in [
@@ -192,8 +115,6 @@ pub(crate) fn item_display_info_schema() -> Schema {
     ] {
         s.add_field(SchemaField::new(name, ty));
     }
-    // fields 9..14 (positional): 9 the flags word, 10 the ranged-weapon SpellVisual id, 11 the
-    // ItemGroupSounds id, 12/13 helm-vis.
     for name in [
         "Flags",
         "SpellVisualID",
@@ -219,8 +140,7 @@ pub(crate) fn item_display_info_schema() -> Schema {
     s
 }
 
-/// Build the catalog from an already-parsed record set — the testable core (no `Chain` needed);
-/// [`load_item_display_catalog`] is the chain-reading wrapper.
+/// The catalog from a parsed record set, testable without a chain.
 fn catalog_from_records(rs: RecordSet) -> ItemDisplayCatalog {
     let mut displays = HashMap::with_capacity(rs.records().len());
     for r in rs.records() {
@@ -274,9 +194,7 @@ pub fn load_item_display_catalog(chain: &mut Chain) -> Result<ItemDisplayCatalog
 mod tests {
     use super::*;
 
-    /// A minimal synthetic WDBC (20-byte header + fixed-width records + a string block) — the same
-    /// shape `benilla-dbc`'s own tests build, reproduced here so this adapter is testable without a
-    /// real client install.
+    /// A minimal synthetic WDBC: 20-byte header, fixed-width records, string block.
     fn build_wdbc(
         record_count: u32,
         field_count: u32,
@@ -303,13 +221,12 @@ mod tests {
         v.to_le_bytes()
     }
 
-    /// A growable string block: offset 0 is always `""` (an absent column resolves there); each
-    /// `push` appends a NUL-terminated string and returns its offset.
+    /// A string block whose offset 0 is `""`, where an absent column points.
     #[derive(Default)]
     struct StringBlock(Vec<u8>);
     impl StringBlock {
         fn new() -> Self {
-            Self(vec![0u8]) // offset 0 = ""
+            Self(vec![0u8])
         }
         fn push(&mut self, s: &str) -> u32 {
             let off = self.0.len() as u32;
@@ -319,29 +236,26 @@ mod tests {
         }
     }
 
-    /// The ammo-display **shape rule** on the real build-5875 rows (decision 0099 phase 5): a
-    /// projectile display carries its flight model in the **right** slot only (`Ammo\` dir) —
-    /// verified over every display a class-6 projectile item resolves to (17 rows, vmangos
-    /// `item_template`) — while a thrown weapon fills the **left** slot (`Weapon\` dir; the weapon
-    /// itself flies). The missile spawner keys its dir choice on that shape; the client keys the
-    /// same fork on the wire ammo block's InventoryType (`0x19`=THROWN, wow-re
-    /// `item-visual-enchant.md` §4) — identical output on every real row. Skips without client data.
+    /// A projectile display carries its flight model in the right slot (`Ammo\`), a thrown weapon
+    /// in the left (`Weapon\`). The missile spawner keys its folder on that shape; the reference
+    /// keys the same fork on the ammo's `InventoryType` (`0x19` thrown, `0x60ba30`), with the same
+    /// result on every shipped row.
     #[test]
     fn real_ammo_displays_carry_flight_models_right_thrown_left() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_item_display_catalog(&mut chain).expect("load ItemDisplayInfo");
 
-        // Rough Arrow's display: flight model + its object skin, right slot, left empty.
+        // Rough Arrow: flight model and skin in the right slot, the left empty.
         let arrow = cat.get(5996).expect("arrow display");
         assert_eq!(arrow.model, [None, Some("arrowflight_01.m2".into())]);
         assert_eq!(arrow.model_texture[1].as_deref(), Some("Arrow_A_01Brown"));
-        // Light Shot's display: the bullet pair.
+        // Light Shot: the bullet pair.
         let shot = cat.get(5998).expect("bullet display");
         assert_eq!(shot.model[1].as_deref(), Some("bulletflight_01.m2"));
 
-        // Balanced Throwing Dagger's display: the weapon model in the LEFT slot (it lives in
-        // `Item\ObjectComponents\Weapon\`, verified against the MPQ listing).
+        // Balanced Throwing Dagger: the weapon model, from `Item\ObjectComponents\Weapon\`, in the
+        // left slot.
         let thrown = cat.get(16752).expect("thrown display");
         assert_eq!(thrown.model[0].as_deref(), Some("thrown_1h_dagger_a_01.m2"));
         assert_eq!(
@@ -357,22 +271,22 @@ mod tests {
         let off_texture = strings.push("Buckler_Damaged_A_01Purple");
 
         let mut rec = Vec::with_capacity(RECORD_SIZE as usize);
-        rec.extend(u32le(18730)); // ID — the Worn Wooden Shield's real displayId
+        rec.extend(u32le(18730)); // ID: the Worn Wooden Shield's displayId
         rec.extend(u32le(off_model)); // ModelNameLeft
-        rec.extend(u32le(OFF_EMPTY)); // ModelNameRight — absent
+        rec.extend(u32le(OFF_EMPTY)); // ModelNameRight: absent
         rec.extend(u32le(off_texture)); // ModelTextureLeft
-        rec.extend(u32le(OFF_EMPTY)); // ModelTextureRight — absent
-        rec.extend(u32le(OFF_EMPTY)); // Icon — unread
+        rec.extend(u32le(OFF_EMPTY)); // ModelTextureRight: absent
+        rec.extend(u32le(OFF_EMPTY)); // Icon: absent
         rec.extend(u32le(1)); // GeosetGroup0
         rec.extend(u32le(0)); // GeosetGroup1
         rec.extend(u32le(0)); // GeosetGroup2
-        rec.extend(u32le(0)); // Unk9
-        rec.extend(u32le(0)); // Unk10
+        rec.extend(u32le(0)); // Flags
+        rec.extend(u32le(0)); // SpellVisualID
         rec.extend(u32le(21)); // ItemGroupSoundsID
         rec.extend(u32le(0)); // HelmVisMale
         rec.extend(u32le(0)); // HelmVisFemale
         for _ in 0..8 {
-            rec.extend(u32le(OFF_EMPTY)); // region textures — this row paints none
+            rec.extend(u32le(OFF_EMPTY)); // region textures: none
         }
         rec.extend(u32le(0)); // ItemVisualID
         assert_eq!(rec.len(), RECORD_SIZE as usize);
@@ -384,7 +298,7 @@ mod tests {
         assert_eq!(catalog.len(), 1);
         let display = catalog.get(18730).expect("displayId 18730 present");
 
-        // The model normalizer applied (lowercased, `.mdx` → `.m2`) — reused, not duplicated.
+        // The model normalizer applied: lowercased, `.mdx` to `.m2`.
         assert_eq!(
             display.model[0].as_deref(),
             Some("shield_round_a_01.m2"),
@@ -392,8 +306,7 @@ mod tests {
         );
         assert_eq!(display.model[1], None, "empty ModelNameRight column ⇒ None");
 
-        // The texture is an independently-resolved basename — NOT derived from the model name (the
-        // module-doc trap this test guards).
+        // The texture is resolved independently, never derived from the model name.
         assert_eq!(
             display.model_texture[0].as_deref(),
             Some("Buckler_Damaged_A_01Purple"),
@@ -414,7 +327,7 @@ mod tests {
 
     #[test]
     fn unknown_display_id_misses() {
-        let rec = vec![0u8; RECORD_SIZE as usize]; // ID 0, everything else empty/zero
+        let rec = vec![0u8; RECORD_SIZE as usize]; // ID 0, everything else empty or zero
         let bytes = build_wdbc(1, FIELD_COUNT, RECORD_SIZE, &rec, &StringBlock::new().0);
         let rs = parse(&bytes, item_display_info_schema(), "test").expect("synthetic DBC parses");
         let catalog = catalog_from_records(rs);
diff --git a/crates/benilla-formats/src/itemsets.rs b/crates/benilla-formats/src/itemsets.rs
index 37f7c7ae..5e18f742 100644
--- a/crates/benilla-formats/src/itemsets.rs
+++ b/crates/benilla-formats/src/itemsets.rs
@@ -1,11 +1,6 @@
-//! ItemSet.dbc — the item-set catalog behind the tooltip's SET block (wow-re
-//! `ui/scratch/tooltip-content-law.md` §22: set name "(owned/total)" gold, per-member lines
-//! pale-cream/gray, threshold bonuses green/gray via the `$`-token engine).
-//!
-//! Record layout per vmangos `ItemSetEntry` (`DBCStructure.h`, the 1.12 branch): id@0, the 8+1
-//! localized name block @1..9, itemId[17]@10..26 (0-padded), setSpellID[8]@27..34,
-//! setThreshold[8]@35..42 (each spell's required equipped count), requiredSkill@43,
-//! requiredSkillRank@44 — 45 fields.
+//! `ItemSet.dbc`: the item sets behind the item tooltip's set block (builder `0x52b650`), laid out
+//! as vmangos `ItemSetEntry` (`DBCStructure.h`): 17 item ids, then 8 spells and each one's
+//! required equipped count.
 
 use std::collections::HashMap;
 
@@ -17,10 +12,8 @@ use crate::Chain;
 
 const ITEM_SET: &str = "DBFilesClient\\ItemSet.dbc";
 
-/// One set: display name, the member item ids (nonzero of the 17 slots), the threshold bonuses
-/// (`(required equipped count, spell id)`, nonzero spells only, in the DBC's stored slot order
-/// — the tooltip sorts threshold-ascending at print time, like the client's qsort `0x52e5c0`),
-/// and the set-level skill requirement.
+/// One set. `bonuses` is `(required equipped count, spell id)` in stored slot order; the tooltip
+/// sorts it by count at print time, as the client's qsort `0x52e5c0` does.
 #[derive(Debug, Clone)]
 pub struct ItemSetInfo {
     pub name: String,
@@ -36,17 +29,15 @@ pub struct ItemSetCatalog {
 }
 
 impl ItemSetCatalog {
-    /// The set row for an item template's `itemset` id, or `None` for an id the DBC lacks.
+    /// The set for an item template's `itemset` id.
     pub fn set(&self, id: u32) -> Option<&ItemSetInfo> {
         self.sets.get(&id)
     }
 
-    /// Number of rows (for logging/diagnostics).
     pub fn len(&self) -> usize {
         self.sets.len()
     }
 
-    /// Whether no rows loaded.
     pub fn is_empty(&self) -> bool {
         self.sets.is_empty()
     }
@@ -108,11 +99,6 @@ pub fn load_item_sets(chain: &mut Chain) -> Result<ItemSetCatalog> {
 mod tests {
     use super::*;
 
-    /// Data-gated on the real 5875 DBC (172 rows): Vestments of the Devout (182, the priest
-    /// dungeon set) carries 8 members + its bonus ladder; Defias Leather (161) carries 5.
-    /// Bonuses load in the DBC's stored slot order (The Gladiator stores 3,2,5,4 — the tooltip
-    /// sorts at print time). Every skill-gated set carries a nonzero rank (the builder's
-    /// rank-0 format leg is data-empty). Skips without client data.
     #[test]
     fn item_sets_load_from_the_chain() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/itemsubclass.rs b/crates/benilla-formats/src/itemsubclass.rs
index fbb32b4b..7c07786d 100644
--- a/crates/benilla-formats/src/itemsubclass.rs
+++ b/crates/benilla-formats/src/itemsubclass.rs
@@ -1,18 +1,6 @@
-//! ItemSubClass.dbc — per `(class, subclass)`: the alternate-proficiency fields and the
-//! display gate the item tooltip's slot|type line reads (wow-re builder `0x52b650`, the
-//! `0xc0db90` row cache).
-//!
-//! The builder consumes exactly three fields beyond the key: **prerequisiteProficiency@2 /
-//! postrequisiteProficiency@3** (−1 = none; a weapon whose own subclass bit is missing from the
-//! player's proficiency mask is still usable when the alternate's bit is set — the slot cell's
-//! red instead of the type cell's), and **displayFlags@5** bit 0 (suppress the type name — the
-//! "Miscellaneous" family: rings, trinkets, shirts never print an armor type).
-//!
-//! Record layout (no id column; keyed by class+subclass, 28 fields): class@0, subClass@1,
-//! prerequisiteProficiency@2, postrequisiteProficiency@3, flags@4, displayFlags@5,
-//! weaponParrySeq@6, weaponReadySeq@7, weaponAttackSeq@8, weaponSwingSize@9, displayName
-//! 8+1 @10..18, verboseName 8+1 @19..27 — the offsets the builder reads (`[row+2]`, `[row+3]`,
-//! byte of `[row+5]`, `[row+locale+10]`) land on exactly this shape.
+//! `ItemSubClass.dbc` by `(class, subclass)`, 28 fields with no id column: the alternate
+//! proficiencies and the display gate the item tooltip's slot and type line reads (builder
+//! `0x52b650`, row cache `0xc0db90`), and the subclass names requirements are spelled with.
 
 use std::collections::HashMap;
 
@@ -23,56 +11,44 @@ use crate::dbc::{i32_at, parse, u32_at};
 use crate::Chain;
 
 const ITEM_SUB_CLASS: &str = "DBFilesClient\\ItemSubClass.dbc";
-/// The group-name table read *before* [`ITEM_SUB_CLASS`] whenever a whole subclass **mask** needs a
-/// name — see [`ItemSubClassCatalog::requirement_name`]. 11 fields (verified by loading the shipped
-/// file): `ClassID@0`, `Mask@1`, `Name_Lang@2..9`, `NameFlags@10`.
+/// The group names, read before [`ITEM_SUB_CLASS`] when a whole subclass mask needs a name.
 const ITEM_SUB_CLASS_MASK: &str = "DBFilesClient\\ItemSubClassMask.dbc";
 
 /// One row's tooltip-relevant fields.
 #[derive(Debug, Clone, Copy)]
 pub struct ItemSubClassInfo {
-    /// Alternate subclasses whose proficiency also permits use (−1 = none). The builder's
-    /// short-circuit: prerequisite wins when present; postrequisite is only consulted when
-    /// prerequisite is −1.
+    /// An alternate subclass whose proficiency also permits use, -1 for none.
     pub prerequisite_proficiency: i32,
     pub postrequisite_proficiency: i32,
-    /// Bit 0 = never print the type name on the slot|type line.
+    /// `Flags` (`[row+0x10]`), raw; `0x200` gates the auction house's inventory-slot rows
+    /// (`0x4cfb63`).
+    pub flags: u32,
+    /// Bit 0: never print the type name on the slot and type line.
     pub display_flags: u32,
-    /// `WeaponSwingSize@9` — the swinging weight, 0 light · 1 medium · 2 heavy, and the sole
-    /// input to the connecting swing's whoosh ([`crate::WeaponSwingCatalog`]). Meaningful on
-    /// class 2 only; the shipped weapon rows put daggers and fist weapons at light, every
-    /// two-hander plus polearms, staves and spears at heavy, and everything else at medium.
+    /// The swing weight, 0 light, 1 medium, 2 heavy, the sole input to a connecting swing's whoosh;
+    /// meaningful on class 2 only.
     pub weapon_swing_size: u32,
 }
 
-/// ItemSubClass.dbc keyed by `(class, subclass)`.
+/// `ItemSubClass.dbc` by `(class, subclass)`.
 pub struct ItemSubClassCatalog {
     rows: HashMap<(u32, u32), ItemSubClassInfo>,
-    /// The crafting book's header vocabulary (0437's TU-B fold-back): the resolved display name,
-    /// by the client's own byte law — **VerboseName** (`row + locale·4 + 0x4c`, enUS column 19)
-    /// when non-empty, else **DisplayName** (`+0x28`, column 10). "One-Handed Swords" over
-    /// "Sword"; plain "Cloth" where no verbose form exists.
+    /// The crafting book's header names (`0x4fca20`): the verbose name (`+0x4c`, column 19) when
+    /// non-empty, else the display name (`+0x28`, column 10).
     names: HashMap<(u32, u32), String>,
-    /// **DisplayName** alone (column 10) — the SINGULAR spelling. The two are not
-    /// interchangeable, and the reference picks between them by call site: the cast-fail line
-    /// `SPELL_FAILED_EQUIPPED_ITEM_CLASS` reads "Must have a **Wand** equipped" where the spell
-    /// tooltip's requirement line reads "Requires **Wands**" — both pinned by reference captures
-    /// of the same spell (Shoot 5019: class 2, submask bit 19).
+    /// The display name alone, the singular: the cast-fail line says "Must have a Wand equipped"
+    /// where the spell tooltip says "Requires Wands".
     display_names: HashMap<(u32, u32), String>,
-    /// Every `(class, subclass)` key in **file order** — the order the reference walks the rows in,
-    /// which decides both the comma-join's order and which row counts as "first"
-    /// ([`Self::requirement_name`] / [`Self::requirement_display_name`]).
+    /// Keys in file order, the reference's walk order, which sets the join's order and which row
+    /// is first.
     order: Vec<(u32, u32)>,
-    /// `ItemSubClassMask.dbc`: `(classId, mask, name)` — the group names that stand in for a whole
-    /// mask ("Melee Weapon" for the eleven melee weapon subclasses). Only 3 rows ship. Folded in
-    /// here rather than given its own catalog because it is stage 1 of one lookup, not a second
-    /// vocabulary.
+    /// `ItemSubClassMask.dbc`'s `(class, mask, name)`: one name for a whole mask, "Melee Weapon".
     mask_groups: Vec<(u32, u32, String)>,
 }
 
 impl ItemSubClassCatalog {
-    /// The alternate proficiency subclass for `(class, subclass)` — the builder's exact
-    /// sentinel walk: prerequisite if not −1, else postrequisite if not −1, else `None`.
+    /// The alternate proficiency subclass, the builder's walk: the prerequisite, then the
+    /// postrequisite. A weapon without its own proficiency is usable with the alternate's.
     pub fn proficiency_alt(&self, class: u32, subclass: u32) -> Option<u32> {
         let r = self.rows.get(&(class, subclass))?;
         [r.prerequisite_proficiency, r.postrequisite_proficiency]
@@ -81,45 +57,31 @@ impl ItemSubClassCatalog {
             .map(|v| v as u32)
     }
 
-    /// The swinging weight for `(class, subclass)` — `WeaponSwingSize`, the reference's
-    /// `0x623870` return: it reads the equipped item's class/subclass, looks the pair up in this
-    /// table and hands `[row+0x24]` straight to the swing-sound play. `None` for an unknown pair,
-    /// which is the reference's "not a weapon" answer — it returns *false* there and plays
-    /// nothing rather than defaulting to a weight.
+    /// `WeaponSwingSize` (`[row+0x24]`, returned by `0x623870`). An unknown pair is the reference's
+    /// "not a weapon", which plays nothing rather than defaulting to a weight.
     pub fn weapon_swing_size(&self, class: u32, subclass: u32) -> Option<u32> {
         Some(self.rows.get(&(class, subclass))?.weapon_swing_size)
     }
 
-    /// The subclass display name (verbose-first, the wow-re `tradeskill` node's byte law) — the
-    /// crafting book's group header text; `None` for an unknown key.
+    /// The crafting book's header name, verbose first (`0x4fca20`).
     pub fn name(&self, class: u32, subclass: u32) -> Option<&str> {
         self.names.get(&(class, subclass)).map(String::as_str)
     }
 
-    /// The SINGULAR subclass name (DisplayName only — [`Self::display_names`]); `None` for an
-    /// unknown key or an empty column.
+    /// The singular subclass name, the display name alone.
     pub fn display_name(&self, class: u32, subclass: u32) -> Option<&str> {
         self.display_names
             .get(&(class, subclass))
             .map(String::as_str)
     }
 
-    /// What a spell's equipped-item requirement is *called*, for `(class, subclass_mask)` — the
-    /// **plural/verbose** spelling the spell tooltip prints ("Requires Wands", "Requires Melee
-    /// Weapon"). `None` when nothing names it.
+    /// A spell's equipped-item requirement as the spell tooltip spells it, plural and verbose
+    /// ("Requires Wands"). The reference's lookup (`0x6e2380`) has two stages:
+    /// 1. `ItemSubClassMask.dbc` on exact whole-mask equality, so Parry's eleven melee subclasses
+    ///    (`0x2a5f3`) print "Melee Weapon".
+    /// 2. Otherwise every subclass the mask names, comma-joined in file order, by [`Self::name`].
     ///
-    /// The reference's law is two-stage (wow-re `tooltip-content-law.md` §3-EQUIPITEM, carved from
-    /// `0x6e2380` and its two call sites), and both stages matter for a mask with several bits set:
-    ///
-    /// 1. `ItemSubClassMask.dbc` on **exact whole-mask equality** — not "any bit", the entire mask.
-    ///    Three rows ship: `{2, 0x2a5f3, "Melee Weapon"}`, `{4, 0x60, "Shield"}`,
-    ///    `{2, 0x4000c, "Ranged Weapon"}`. This is why Parry (`0x2a5f3` = eleven melee subclasses)
-    ///    prints one group name rather than eleven weapon types.
-    /// 2. Otherwise every subclass the mask names, comma-joined in file order, each preferring
-    ///    VerboseName with a DisplayName fallback ([`Self::name`]).
-    ///
-    /// Only when stage 2 also finds nothing is the line absent. Note `0x6e2380` reads **only**
-    /// ItemSubClass.dbc — there is no ItemClass.dbc fallback on either path.
+    /// It reads only `ItemSubClass.dbc`, with no `ItemClass.dbc` fallback.
     pub fn requirement_name(&self, class: u32, mask: u32) -> Option<String> {
         self.mask_group(class, mask)
             .map(str::to_string)
@@ -134,9 +96,8 @@ impl ItemSubClassCatalog {
             })
     }
 
-    /// The **singular** spelling of the same requirement — what the `SPELL_FAILED_EQUIPPED_ITEM_CLASS`
-    /// cast-fail line says ("Must have a Wand equipped"). Same stage 1, but stage 2 takes only the
-    /// FIRST matching subclass and its DisplayName: never a join, never VerboseName.
+    /// The singular spelling the `SPELL_FAILED_EQUIPPED_ITEM_CLASS` line uses: the same stage 1,
+    /// then the first matching subclass's display name, never a join.
     pub fn requirement_display_name(&self, class: u32, mask: u32) -> Option<String> {
         self.mask_group(class, mask)
             .map(str::to_string)
@@ -147,7 +108,7 @@ impl ItemSubClassCatalog {
             })
     }
 
-    /// Stage 1: the `ItemSubClassMask.dbc` group name for an EXACT `(class, mask)` pair.
+    /// Stage 1: the group name for an exact `(class, mask)` pair.
     fn mask_group(&self, class: u32, mask: u32) -> Option<&str> {
         self.mask_groups
             .iter()
@@ -170,39 +131,34 @@ impl ItemSubClassCatalog {
             .is_some_and(|r| r.display_flags & 1 != 0)
     }
 
-    /// This subclass's raw `DisplayFlags` (`0` for an unknown key). Bit 0 is [`Self::hides_name`];
-    /// bit 1 marks a subclass the auction house's category filter does not offer; **bit 2 (`0x4`)
-    /// is the "this bag counts what is inside it" gate** — `GetInventoryItemCount` (`0x4c881a`–
-    /// `0x4c8826`) reads it before summing an equipped bag's contents, and in the shipped 1.12.1
-    /// file it is set on Soul Bag (1/1) and the whole Quiver class (11/0..3) and nowhere else.
-    /// The bits are served raw rather than as named predicates because each consumer owns the
-    /// meaning of the one it reads — the auction law lives in the auction module, not here.
+    /// The raw `Flags`, 0 for an unknown key.
+    pub fn flags(&self, class: u32, subclass: u32) -> u32 {
+        self.rows.get(&(class, subclass)).map_or(0, |r| r.flags)
+    }
+
+    /// The raw `DisplayFlags`, 0 for an unknown key. Bit 0 is [`Self::hides_name`]; bit 1 keeps a
+    /// subclass out of the auction house's category filter; bit 2 makes `GetInventoryItemCount`
+    /// count an equipped bag's contents (`0x4c881a`-`0x4c8826`), set on Soul Bag and every quiver.
     pub fn display_flags(&self, class: u32, subclass: u32) -> u32 {
         self.rows
             .get(&(class, subclass))
             .map_or(0, |r| r.display_flags)
     }
 
-    /// Every subclass id defined for `class`, ascending. The shipped table is small (72 rows
-    /// total), so the scan costs nothing and the alternative — assuming subclass ids are dense
-    /// from 0 — is false for several classes.
+    /// Every subclass id of `class` in file order, the order in which the auction house's scans
+    /// count the Nth matching row (`0x4cf9c0`, `0x4ce980`); ids are not dense from 0.
     pub fn subclasses_of(&self, class: u32) -> Vec<u32> {
-        let mut ids: Vec<u32> = self
-            .rows
-            .keys()
+        self.order
+            .iter()
             .filter(|(c, _)| *c == class)
-            .map(|(_, s)| *s)
-            .collect();
-        ids.sort_unstable();
-        ids
+            .map(|&(_, s)| s)
+            .collect()
     }
 
-    /// Number of rows (for logging/diagnostics).
     pub fn len(&self) -> usize {
         self.rows.len()
     }
 
-    /// Whether no rows loaded.
     pub fn is_empty(&self) -> bool {
         self.rows.is_empty()
     }
@@ -253,8 +209,7 @@ fn item_sub_class_mask_schema() -> Schema {
     s
 }
 
-/// Load ItemSubClass.dbc — plus the ItemSubClassMask.dbc group names, which are stage 1 of the same
-/// lookup ([`ItemSubClassCatalog::requirement_name`]) — from the patch chain.
+/// Load `ItemSubClass.dbc` and the `ItemSubClassMask.dbc` group names off the patch chain.
 pub fn load_item_sub_classes(chain: &mut Chain) -> Result<ItemSubClassCatalog> {
     let bytes = chain
         .read_file(ITEM_SUB_CLASS)
@@ -293,12 +248,12 @@ pub fn load_item_sub_classes(chain: &mut Chain) -> Result<ItemSubClassCatalog> {
             ItemSubClassInfo {
                 prerequisite_proficiency: i32_at(r, 2).unwrap_or(-1),
                 postrequisite_proficiency: i32_at(r, 3).unwrap_or(-1),
+                flags: u32_at(r, 4).unwrap_or(0),
                 display_flags: u32_at(r, 5).unwrap_or(0),
                 weapon_swing_size: u32_at(r, 9).unwrap_or(0),
             },
         );
-        // VerboseName enUS (col 19) first, DisplayName enUS (col 10) fallback — the struct doc's
-        // byte law. Empty both → no name row (the header renders blank, faithfully unlikely).
+        // The enUS verbose name (column 19) first, the display name (column 10) as fallback.
         let display = crate::dbc::str_at(&rs, r, 10).filter(|n| !n.is_empty());
         let name = crate::dbc::str_at(&rs, r, 19)
             .filter(|n| !n.is_empty())
@@ -323,8 +278,6 @@ pub fn load_item_sub_classes(chain: &mut Chain) -> Result<ItemSubClassCatalog> {
 mod tests {
     use super::*;
 
-    /// The header-name law on the real 5875 file (0446's TU-B fold-back): verbose-first,
-    /// display fallback. Skips without client data.
     #[test]
     fn real_subclass_names_resolve_verbose_first() {
         let data = crate::wow_data_or_skip!();
@@ -341,15 +294,14 @@ mod tests {
         assert_eq!(cat.name(99, 0), None);
     }
 
-    /// The two-stage equipped-item requirement law (§3-EQUIPITEM) against the real 5875 DBCs —
-    /// including the multi-bit case we used to give up on. Skips without client data.
+    /// The requirement lookup's two stages (`0x52eea7`-`0x52f10a`) on the shipped tables.
     #[test]
     fn real_requirement_names_take_the_group_before_the_join() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_item_sub_classes(&mut chain).expect("load the two DBCs");
 
-        // Stage 1 — the whole mask has a name of its own. All three shipped rows.
+        // Stage 1: the whole mask has a name; all three shipped rows.
         assert_eq!(
             cat.requirement_name(2, 0x0002_a5f3).as_deref(),
             Some("Melee Weapon"),
@@ -360,21 +312,21 @@ mod tests {
             cat.requirement_name(2, 0x0004_000c).as_deref(),
             Some("Ranged Weapon")
         );
-        // The group name is the same string in the singular arm — the stages share stage 1.
+        // The singular arm shares stage 1.
         assert_eq!(
             cat.requirement_display_name(2, 0x0002_a5f3).as_deref(),
             Some("Melee Weapon")
         );
 
-        // Stage 2, one bit — the two spellings diverge (Shoot 5019: class 2, bit 19).
+        // Stage 2, one bit: the spellings diverge (Shoot 5019: class 2, bit 19).
         assert_eq!(cat.requirement_name(2, 1 << 19).as_deref(), Some("Wands"));
         assert_eq!(
             cat.requirement_display_name(2, 1 << 19).as_deref(),
             Some("Wand")
         );
 
-        // Stage 2, several bits with no group row — joined for the tooltip, first-only for the
-        // cast-fail line. Daggers (15) + fist weapons (13) is not a shipped group.
+        // Stage 2, fist weapons (13) and daggers (15), no shipped group: joined for the tooltip,
+        // first only for the cast-fail line.
         let mask = (1 << 13) | (1 << 15);
         assert_eq!(
             cat.requirement_name(2, mask).as_deref(),
@@ -385,11 +337,8 @@ mod tests {
             Some("Fist Weapon")
         );
 
-        // Class 6 PROJECTILE — the lookup the cast-fail `0x31` NEED_EXOTIC_AMMO arm makes
-        // (`0x6e1e5e: mov ecx,0x6`, mask `1 << arg`), so "Requires exotic ammo: %s" names the
-        // ammo type. Only two of the five shipped rows are live in 1.12; the other three carry
-        // an `(OBSOLETE)` suffix in the data itself, and one is pinned below so a schema slip
-        // that silently shifted the class would be visible rather than merely returning `None`.
+        // Class 6, projectile: the cast-fail `0x31` NEED_EXOTIC_AMMO arm's lookup (`0x6e1e5e`,
+        // mask `1 << arg`). Three of the five shipped rows are `(OBSOLETE)` in the data itself.
         assert_eq!(
             cat.requirement_display_name(6, 1 << 2).as_deref(),
             Some("Arrow")
@@ -402,28 +351,22 @@ mod tests {
             cat.requirement_display_name(6, 1 << 4).as_deref(),
             Some("Thrown(OBSOLETE)")
         );
-        // Past the shipped rows — the arm's own decline (`0x6e1e6a: je 0x6e21d8`, the shared
-        // default), which is where an absent or wild wire word lands.
+        // Past the shipped rows: the arm declines (`0x6e1e6a`, to the shared default `0x6e21d8`).
         assert_eq!(cat.requirement_display_name(6, 1 << 5), None);
         assert_eq!(cat.requirement_display_name(6, 1 << 31), None);
 
-        // Nothing to name.
         assert_eq!(cat.requirement_name(2, 0), None);
         assert_eq!(cat.requirement_name(99, 1), None);
     }
 
-    /// Data-gated on the real 5875 DBC. Prints the live prereq/postreq and displayFlags rows so
-    /// a schema slip is visible, and pins the known shape. Skips without client data.
     #[test]
     fn item_sub_classes_load_from_the_chain() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_item_sub_classes(&mut chain).expect("ItemSubClass.dbc loads");
         assert!(!cat.is_empty());
-        // The live alt pairs come in prerequisite/postrequisite couples per weapon family:
-        // 2H Axe (2,1) ← 1H Axe via prerequisite, 1H Mace (2,4) → 2H Mace via POSTrequisite
-        // (the sentinel short-circuit's second leg), 2H Sword (2,8) ← 1H Sword, and Shield
-        // (4,6) ← Buckler. Print the full list so a schema slip is visible.
+        // The live pairs: 2H Axe (2, 1) to 1H Axe, 1H Mace (2, 4) to 2H Mace by postrequisite,
+        // 2H Sword (2, 8) to 1H Sword, Shield (4, 6) to Buckler.
         for ((c, sc), r) in {
             let mut v: Vec<_> = cat.rows.iter().map(|(&k, v)| (k, *v)).collect();
             v.sort_by_key(|&((c, sc), _)| (c, sc));
@@ -440,10 +383,8 @@ mod tests {
         assert_eq!(cat.proficiency_alt(2, 4), Some(5));
         assert_eq!(cat.proficiency_alt(2, 8), Some(7));
         assert_eq!(cat.proficiency_alt(4, 6), Some(5));
-        // Daggers stand alone — no other proficiency softens a dagger's red.
         assert_eq!(cat.proficiency_alt(2, 15), None);
-        // displayFlags bit 0: Miscellaneous armor (rings/trinkets/shirts) hides its type name;
-        // ordinary armor and weapons show theirs.
+        // Display flag bit 0: Miscellaneous armor hides its type name.
         assert!(cat.hides_name(4, 0));
         assert!(!cat.hides_name(4, 1), "Cloth prints");
         assert!(!cat.hides_name(2, 7), "Sword prints");
diff --git a/crates/benilla-formats/src/languages.rs b/crates/benilla-formats/src/languages.rs
index ede9500f..58034f31 100644
--- a/crates/benilla-formats/src/languages.rs
+++ b/crates/benilla-formats/src/languages.rs
@@ -1,29 +1,10 @@
-//! `Languages.dbc` × `ChrRaces.dbc` — the one join behind `GetDefaultLanguage()`.
+//! `Languages.dbc` joined with `ChrRaces.dbc` for `GetDefaultLanguage()`, and the
+//! `LanguageWords.dbc` substitution pools.
 //!
-//! The binding `0x49fcd0` (94 bytes; wow-re `ui/scratch/bag-language-combat-action-bindings.md`
-//! §2, §5-cross-checked) is a two-hop table walk and nothing else:
-//!
-//! ```text
-//! player race byte  ->  [0xc0dee0][race] + 0x20   =  base language id
-//!                   ->  [0xc0db48][id]  + 4 + 4·[0xc0e080]  =  the localized name
-//! ```
-//!
-//! `+0x20` on a `ChrRaces` record is byte offset 32, i.e. **field 8** — which the shipped 5875
-//! data confirms independently: field 8 reads **7 for Human/Dwarf/Night Elf/Gnome/Goblin and 1 for
-//! Orc/Undead/Tauren/Troll**, and `Languages.dbc` rows 7 and 1 are `Common` and `Orcish`. So the
-//! "default" language is the **faction** language, not the racial one — a Night Elf's default is
-//! Common, an Undead's is Orcish, and Darnassian/Gutterspeak are *additional* languages the
-//! `GetLanguageByIndex` family enumerates. (Field 9, its neighbour, is `CreatureType` = 7 Humanoid
-//! for every playable race — already anchored elsewhere in this crate's consumers, which is what
-//! makes the field-8 identification a cross-check rather than a count.)
-//!
-//! Verified against the real chain below: 13 language rows, 9 race rows, and the nine races
-//! resolving to exactly two distinct names.
-//!
-//! **Locale.** `[0xc0e080]` is the client's locale slot and only column 0 (enUS) is populated in
-//! this install — every other DBC catalog in this crate reads column 0 for the same reason. The
-//! loader keeps the whole locale row so a localized build has somewhere to go; the app asks for
-//! the slot it wants.
+//! The binding (`0x49fcd0`) is a two-hop walk: the race's `ChrRaces` record (`[0xc0dee0]`) at
+//! `+0x20`, field 8, names a language, whose `Languages` record (`[0xc0db48]`) holds the name at
+//! `+4 + 4 * locale` (`[0xc0e080]`). Field 8 is the faction language, Common or Orcish, never the
+//! racial one: Darnassian and Gutterspeak are extra languages `GetLanguageByIndex` lists.
 
 use std::collections::HashMap;
 
@@ -37,18 +18,16 @@ const LANGUAGES: &str = "DBFilesClient\\Languages.dbc";
 const CHR_RACES: &str = "DBFilesClient\\ChrRaces.dbc";
 const LANGUAGE_WORDS: &str = "DBFilesClient\\LanguageWords.dbc";
 
-/// How many locale columns a `Name_lang` block carries in 5875 (`Languages.dbc` is
-/// `ID + 8 names + NameFlags` = 10 fields).
+/// Locale columns in a 5875 `Name_lang` block.
 const LOCALES: usize = 8;
 
-/// race id → the localized name of that race's base language, one entry per locale column.
+/// Race id to its base language's name, per locale column.
 #[derive(Debug, Default, Clone)]
 pub struct DefaultLanguages(HashMap<u32, [Option<String>; LOCALES]>);
 
 impl DefaultLanguages {
-    /// The race's default chat language in `locale`'s column, or `None` — which is the reference's
-    /// own answer shape at three of its four failure edges (no such race row, a language id past
-    /// the table, a null record), all of which push **zero Lua values** rather than `nil`.
+    /// The race's default language name in `locale`'s column. `None` is the reference's answer at
+    /// three of its four failure edges, which push no Lua value at all, not `nil`.
     pub fn name(&self, race: u32, locale: usize) -> Option<&str> {
         self.0.get(&race)?.get(locale)?.as_deref()
     }
@@ -61,7 +40,6 @@ impl DefaultLanguages {
     }
 }
 
-/// `Languages.dbc` — `ID`, eight `Name_lang` strings, `NameFlags`.
 fn languages_schema() -> Schema {
     let mut s = Schema::new("Languages");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -72,9 +50,8 @@ fn languages_schema() -> Schema {
     s
 }
 
-/// `ChrRaces.dbc` — 29 fields in 5875. Only field 8 (`BaseLanguage`) is read here, so the rest are
-/// declared as plain dwords: the schema's field *count* is what has to match the header, and a
-/// string column read as a dword is just its unresolved offset.
+/// `ChrRaces.dbc`, 29 fields in 5875, all read as dwords: only the count must match the header,
+/// and only field 8 is used.
 fn chr_races_schema() -> Schema {
     let mut s = Schema::new("ChrRaces");
     for i in 0..29 {
@@ -83,19 +60,17 @@ fn chr_races_schema() -> Schema {
     s
 }
 
-/// The field 8 the binding reads at `record + 0x20` (module doc).
+/// `BaseLanguage`, which the binding reads at `record + 0x20`.
 const CHR_RACES_BASE_LANGUAGE: usize = 8;
 
-/// `Languages.dbc` as the client walks it — **row order**, `(ID, Name_lang[8])`. Row order is the
-/// order `GetNumLaguages`/`GetLanguageByIndex` count in (`0x49fb30`/`0x49fbe0` walk the store's
-/// rows and filter, wow-re `chat-language-scramble.md` §8), so this keeps it rather than keying
-/// by id.
+/// `Languages.dbc` in row order, the order `GetNumLanguages` and `GetLanguageByIndex` count in
+/// (`0x49fb30`, `0x49fbe0`).
 #[derive(Debug, Default, Clone)]
 pub struct Languages(Vec<(u32, [Option<String>; LOCALES])>);
 
 impl Languages {
-    /// `(id, name)` per row in row order, for `locale`; a row with no name in that locale is
-    /// skipped (the binding pushes `Name_lang[locale]` verbatim and a NULL would be `""`).
+    /// `(id, name)` per row for `locale`. A row with no name there is skipped, where the binding
+    /// would push `""`.
     pub fn names(&self, locale: usize) -> impl Iterator<Item = (u32, &str)> + '_ {
         self.0
             .iter()
@@ -140,7 +115,7 @@ pub fn load_languages(chain: &mut Chain) -> Result<Languages> {
     Ok(Languages(rows))
 }
 
-/// Load and join both tables into the race → language-name map.
+/// Load and join both tables into the race-to-language-name map.
 pub fn load_default_languages(chain: &mut Chain) -> Result<DefaultLanguages> {
     let lang_bytes = chain
         .read_file(LANGUAGES)
@@ -172,44 +147,20 @@ pub fn load_default_languages(chain: &mut Chain) -> Result<DefaultLanguages> {
     Ok(DefaultLanguages(out))
 }
 
-/// `LanguageWords.dbc` — the fake-word pool the client substitutes, word for word, when it renders
-/// speech in a language the listener's character does not know.
-///
-/// **The wire carries plaintext.** `SMSG_MESSAGECHAT` ships the real sentence plus a language id
-/// and the server never rewrites it (vmangos `ChatHandler.cpp`); turning it into gibberish is
-/// entirely the client's job, which is why an unmodelled garble step renders opposite-faction
-/// speech perfectly readable (B262). The reference's garble routine is `0x49b560`, called from the
-/// chat display chokepoint `0x49a870` at `0x49aa7c` — the same function whose `cmp edi,-0x1` at
-/// `0x49a89b` is the `LANG_ADDON` test.
-///
-/// **The shipped table**, read off this install's chain: **1481 rows x 3 fields, 12-byte records**
-/// — `ID`, `LanguageID`, `Word` — over **13 languages** (ids 1, 2, 3, 6-14, 33: the same id set
-/// `Languages.dbc` carries, minus none and plus none). Each language's pool is 79-128 words, and
-/// the words are authored in **runs of ascending length**, one to seventeen characters: Orcish
-/// opens `A N G O L` (one letter), then `Ha Ko No Mu Ag Ka Gi` (two), and so on. That authored
-/// shape is what makes a length index the natural read of the pool — a substitution that ignored
-/// length would have no use for a table built this way.
+/// `LanguageWords.dbc`, the fake words the client substitutes, word for word, when it renders
+/// speech in a language the listener's character does not know. The wire carries plaintext
+/// (vmangos `ChatHandler.cpp` never rewrites it): the garble is the client's, `0x49b560`, called
+/// from the chat display chokepoint `0x49a870` at `0x49aa7c`.
 #[derive(Debug, Default, Clone)]
 pub struct LanguageWords(HashMap<u32, LanguagePool>);
 
-/// One language's substitution pool: the words in file order, plus an index from word length to
-/// the rows of exactly that length.
-///
-/// The index is **shape, not policy**. Storing which words are one character long commits us to
-/// nothing about *how* the reference picks among them (exact-length match, a clamp at the longest
-/// authored word, buckets); every one of those rules reads this index. The rule itself is
-/// `0x49b560`'s and is filled in from the RE verdict, not guessed here.
+/// One language's words in file order, indexed by length.
 #[derive(Debug, Default, Clone)]
 pub struct LanguagePool {
     words: Vec<String>,
-    /// `by_len[n]` = indices into `words` of every word whose length is exactly `n` **bytes**; slot
-    /// 0 is always empty (the index build skips an empty word) and the vector runs to the longest
-    /// word this language authored.
-    ///
-    /// **Bytes, because the reference's index build takes `strlen`** (`0x4982c0`, a plain byte
-    /// `0x64a6f0`), and the length key it later matches is likewise a byte count. Every shipped word
-    /// is ASCII so the two agree in this table — but the key is compared against a *source* word,
-    /// which is arbitrary player text, and there the distinction is real.
+    /// `by_len[n]`: indices of the words exactly `n` bytes long; slot 0 is empty. Bytes, as the
+    /// reference's index build takes `strlen` (`0x4982c0`, `0x64a6f0`), and the source word it is
+    /// matched against is arbitrary player text.
     by_len: Vec<Vec<u32>>,
 }
 
@@ -219,8 +170,7 @@ impl LanguagePool {
         &self.words
     }
 
-    /// The words of exactly `len` bytes, in file order — empty when the language authored none
-    /// that long (and for `len` past its longest word).
+    /// The words of exactly `len` bytes, in file order.
     pub fn of_len(&self, len: usize) -> impl Iterator<Item = &str> {
         self.by_len
             .get(len)
@@ -235,17 +185,14 @@ impl LanguagePool {
         self.by_len.get(len).map_or(0, Vec::len)
     }
 
-    /// The longest word this language authored, in bytes (0 for an empty pool).
+    /// The longest word this language authored, in bytes.
     pub fn max_len(&self) -> usize {
         self.by_len.len().saturating_sub(1)
     }
 
-    /// The substitute the reference picks for a word of `len` bytes whose hash is `hash`:
-    /// `node.words[hash % node.count]` (`0x49b885`), over the candidates **in DBC row order** —
-    /// which is the order the index builder appends them in, so it is the order this pool holds.
-    ///
-    /// `None` means the language authored no word of that length, which is the caller's cue to step
-    /// the length key down and ask again.
+    /// The reference's substitute for a word of `len` bytes: `words[hash % count]` over that
+    /// length's words in row order (`0x49b885`). `None` means no word that long, and the caller
+    /// steps the length down and asks again.
     pub fn nth_of_len(&self, len: usize, hash: u32) -> Option<&String> {
         let bucket = self.by_len.get(len)?;
         let count = u32::try_from(bucket.len()).ok()?;
@@ -258,9 +205,8 @@ impl LanguagePool {
 }
 
 impl LanguageWords {
-    /// The substitution pool for a `Languages.dbc` id, or `None` for an id the table has no rows
-    /// for — which includes `0` (universal) and `-1` (`LANG_ADDON`), neither of which is ever
-    /// garbled.
+    /// A `Languages.dbc` id's pool. Universal (0) and `LANG_ADDON` (`-1`, tested at `0x49a89b`)
+    /// have none and are never garbled.
     pub fn pool(&self, language: u32) -> Option<&LanguagePool> {
         self.0.get(&language)
     }
@@ -274,7 +220,6 @@ impl LanguageWords {
     }
 }
 
-/// `LanguageWords.dbc` — `ID`, `LanguageID`, `Word`.
 fn language_words_schema() -> Schema {
     let mut s = Schema::new("LanguageWords");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -283,10 +228,7 @@ fn language_words_schema() -> Schema {
     s
 }
 
-/// Load the per-language substitution pools.
-///
-/// Word length is counted in **bytes**, which is what the reference's index build uses
-/// (`0x4982c0` takes `strlen`); see [`LanguagePool::by_len`].
+/// Load the per-language substitution pools, indexed by byte length.
 pub fn load_language_words(chain: &mut Chain) -> Result<LanguageWords> {
     let bytes = chain
         .read_file(LANGUAGE_WORDS)
@@ -316,52 +258,44 @@ pub fn load_language_words(chain: &mut Chain) -> Result<LanguageWords> {
 mod tests {
     use super::*;
 
-    /// The real chain, because the whole point of this module is a join between two shipped
-    /// tables — a synthetic fixture would only test the plumbing.
     #[test]
     fn the_shipped_tables_join_to_two_faction_languages() {
         let data = crate::wow_data_or_skip!();
         let mut chain = Chain::open(&data).expect("open patch chain");
         let langs = load_default_languages(&mut chain).expect("load");
 
-        // All nine `ChrRaces` rows resolve (the eight playable ones plus Goblin).
+        // All nine `ChrRaces` rows resolve: the eight playable races and the Goblin.
         assert_eq!(langs.len(), 9, "one entry per ChrRaces row");
-        // Alliance → Common, Horde → Orcish. This is the finding that makes the field-8
-        // identification falsifiable: if 8 were the *racial* language, Night Elf would read
-        // "Darnassian" and Undead "Gutterspeak".
+        // Alliance speaks Common, Horde Orcish; the racial language would give Darnassian.
         for race in [1, 3, 4, 7] {
             assert_eq!(langs.name(race, 0), Some("Common"), "race {race}");
         }
         for race in [2, 5, 6, 8] {
             assert_eq!(langs.name(race, 0), Some("Orcish"), "race {race}");
         }
-        // A race the table has no row for is `None` — the reference's "no such record" edge.
+        // No such race: the reference's no-record edge.
         assert_eq!(langs.name(99, 0), None);
-        // Only enUS is populated in this install; a higher locale column is empty, not a panic.
+        // An enUS install fills only column 0; another is empty, not a panic.
         assert_eq!(langs.name(1, 5), None);
     }
 
-    /// The garble pool, against the real chain for the same reason as above — the shape of the
-    /// shipped table *is* the finding, and a fixture would only test the parser.
     #[test]
     fn the_shipped_word_pools_cover_every_language_and_index_by_length() {
         let data = crate::wow_data_or_skip!();
         let mut chain = Chain::open(&data).expect("open patch chain");
         let words = load_language_words(&mut chain).expect("load");
 
-        // One pool per `Languages.dbc` row — the id sets match exactly, so no spoken language can
-        // reach the garble step and find nothing to substitute.
+        // One pool per `Languages.dbc` row, so no spoken language lacks one.
         assert_eq!(words.len(), 13, "one pool per language");
         let langs = load_default_languages(&mut chain).expect("load languages");
-        let _ = &langs; // the join above already asserts that table; here only the count matters.
+        let _ = &langs; // the join test asserts this table
         for id in [1, 2, 3, 6, 7, 8, 9, 10, 11, 12, 13, 14, 33] {
             assert!(words.pool(id).is_some(), "language {id} has no word pool");
         }
-        // 0 (universal) and the addon sentinel are absent by construction, never garbled.
+        // Universal (0) has no pool: it is never garbled.
         assert!(words.pool(0).is_none());
 
-        // Orcish (1), the shipped numbers: 100 words, the shortest one character, the longest
-        // thirteen, and the one-character run is the five vowels-and-consonants `A N G O L`.
+        // Orcish (1) as shipped: 100 words, one to thirteen bytes, five of length one.
         let orcish = words.pool(1).expect("orcish pool");
         assert_eq!(orcish.words().len(), 100);
         assert_eq!(orcish.max_len(), 13);
@@ -370,12 +304,11 @@ mod tests {
             orcish.of_len(1).collect::<Vec<_>>(),
             ["A", "N", "G", "O", "L"]
         );
-        // Nothing is authored at length zero, and asking past the longest word is empty, not a
-        // panic — the two edges any length rule will lean on.
+        // Length zero and past the longest word are empty, not a panic.
         assert_eq!(orcish.count_of_len(0), 0);
         assert_eq!(orcish.count_of_len(99), 0);
 
-        // Every pool is non-trivial and its length index accounts for every word it holds.
+        // Every pool holds at least 79 words, all of them in its length index.
         let mut total = 0;
         for id in [1, 2, 3, 6, 7, 8, 9, 10, 11, 12, 13, 14, 33] {
             let p = words.pool(id).expect("pool");
diff --git a/crates/benilla-formats/src/lib.rs b/crates/benilla-formats/src/lib.rs
index 18e767be..ad87a31e 100644
--- a/crates/benilla-formats/src/lib.rs
+++ b/crates/benilla-formats/src/lib.rs
@@ -1,12 +1,6 @@
-//! `benilla-formats` — adapters and CLI tooling over WoW 1.12.1 (build 5875) asset formats.
-//!
-//! Every asset format is **in-repo** (decision 0021): MPQ archives (`benilla-mpq`), BLP2 textures
-//! (`benilla-blp`), DBC tables (`benilla-dbc`), WDT tile tables (`benilla-wdt`), ADT terrain
-//! (`benilla-adt`), WMO buildings (`benilla-wmo`), and M2 models (`benilla-m2`). This crate adds our
-//! schema layer, the patch-chain helper ([`Chain`]), and the `benilla-extract` CLI, and keeps data in
-//! **raw WoW coordinates** (the Bevy transform lives in `benilla`).
-//!
-//! Phase 1: MPQ list/extract, BLP -> PNG, DBC -> CSV.
+//! `benilla-formats`: the schema layer over the 1.12.1 (build 5875) asset formats, the patch chain
+//! ([`Chain`]) and the `benilla-extract` CLI. Data stays in raw WoW coordinates; the Bevy transform
+//! lives in `benilla`.
 
 use std::io::Cursor;
 use std::path::Path;
@@ -14,19 +8,17 @@ use std::path::Path;
 use anyhow::{Context, Result};
 use benilla_dbc::{DbcParser, FieldType, Schema, SchemaField};
 
-/// The BLP texel forms, re-exported so a consumer of [`BlpMipChain`] can switch on
-/// [`BlpMipChain::texels`] without depending on `benilla-blp` directly.
+/// The BLP texel forms, re-exported for [`BlpMipChain::texels`].
 pub use benilla_blp::BlpTexels;
 
 mod chain;
 pub use chain::{Chain, ChainEntry};
-/// The UI texture table's other half — loose `.tga` art (addon folders; decision 1322).
+/// Loose `.tga` art, as addon folders ship it.
 mod tga;
 pub use tga::tga_to_rgba;
-/// Where the WoW install is — the one resolver (decision 1175). Paired with [`Chain`]: this says
-/// *where*, that opens it.
+/// Where the WoW install is; [`Chain`] opens it.
 mod install;
-pub use install::{candidates, wow_data};
+pub use install::{addon_corpus, addon_corpus_candidates, candidates, skipped, wow_data};
 mod characters;
 pub use characters::{
     equip_blits, equip_column, equip_region_candidates, equip_tex_dir, equip_tile, forearm_dressed,
@@ -70,7 +62,7 @@ pub use factions::{
 };
 mod creature_types;
 pub use creature_types::{load_creature_type_flags, CreatureTypeFlags};
-/// The chat language scramble — the reference's `0x49b560` (B262). Reads [`LanguageWords`].
+/// The chat language scramble, the reference's `0x49b560`.
 mod garble;
 pub use garble::{garble, garble_chat, Garble, FLUENT_SKILL};
 mod languages;
@@ -197,14 +189,14 @@ pub use spells::{
     cc_exemption, grants_immunity, load_shapeshift_forms, load_spell_cast_times,
     load_spell_catalog, load_spell_dispel_types, load_spell_durations, load_spell_radii,
     load_spell_ranges, min_max_range, substitute, CcExemption, FormRefusal, LearnAnnouncement,
-    OpenLock, ShapeshiftForm, SpellCastTime, SpellCastTimeCatalog, SpellCatalog, SpellDispelTypes,
-    SpellDisplay, SpellDuration, SpellDurationCatalog, SpellRadius, SpellRadiusCatalog, SpellRange,
-    SpellRangeCatalog, TokenContext, ATTR_CASTABLE_WHILE_DEAD, ATTR_NOT_IN_COMBAT,
-    ATTR_ONLY_STEALTHED, COMBAT_REACH_ADD, MELEE_RANGE_FLOOR, ON_NEXT_SWING_RANGE,
-    SPELL_ATTR_IS_TRADESKILL, SPELL_EFFECT_CREATE_ITEM, SPELL_EFFECT_ENCHANT_ITEM,
-    SPELL_EFFECT_ENCHANT_ITEM_TEMPORARY, SPELL_EFFECT_LEARN_PET_SPELL, SPELL_EFFECT_LEARN_SPELL,
-    SPELL_EFFECT_PROSPECTING, SPELL_EFFECT_SKILL_STEP, SPELL_EFFECT_SKINNING,
-    SPELL_EFFECT_TRADE_SKILL,
+    LearnEffect, OpenLock, ShapeshiftForm, SpellCastTime, SpellCastTimeCatalog, SpellCatalog,
+    SpellDispelTypes, SpellDisplay, SpellDuration, SpellDurationCatalog, SpellRadius,
+    SpellRadiusCatalog, SpellRange, SpellRangeCatalog, TokenContext, ATTR_CASTABLE_WHILE_DEAD,
+    ATTR_NOT_IN_COMBAT, ATTR_ONLY_STEALTHED, COMBAT_REACH_ADD, MELEE_RANGE_FLOOR,
+    ON_NEXT_SWING_RANGE, SPELL_ATTR_IS_TRADESKILL, SPELL_EFFECT_CREATE_ITEM,
+    SPELL_EFFECT_ENCHANT_ITEM, SPELL_EFFECT_ENCHANT_ITEM_TEMPORARY, SPELL_EFFECT_LEARN_PET_SPELL,
+    SPELL_EFFECT_LEARN_SPELL, SPELL_EFFECT_PROSPECTING, SPELL_EFFECT_SKILL_STEP,
+    SPELL_EFFECT_SKINNING, SPELL_EFFECT_TRADE_SKILL,
 };
 mod skill_lines;
 pub use skill_lines::{
@@ -290,18 +282,16 @@ pub use terrain::{
     adt_to_tile_mesh, area_id_at, find_tile_near, ground_effect_at, impassable_at, load_tile_mesh,
     load_tiles_around, mcsh_shadowed_at, terrain_height_at, triangle_z_at, ChunkMesh, Doodad,
     MapTiles, TileMesh, WmoInstance, ALPHA_MAP_SIZE, CHUNK_SIZE, SHADOW_MAP_SIZE, STORMWIND_XY,
-    TILE_SIZE,
+    TERRAIN_LAYER_TILES, TILE_SIZE,
 };
 mod wdl;
-/// World (x, y) ↔ ADT tile `(col, row)` — the same mapping the streamer uses to pick tiles
-/// (and the minimap uses to place its tile art, decision 0203: minimap `map<X>_<Y>.blp` names
-/// share the ADT index order, chain-verified — `AhnQiraj_27_46.adt` exists, the swap doesn't).
+/// World (x, y) to ADT tile `(col, row)`; minimap `map<X>_<Y>.blp` names use the same order.
 pub use benilla_wdt::{
     tile_to_world, world_to_chunk, world_to_tile, GlobalWmo, WdtFile, WdtReader, WowVersion,
 };
 pub use wdl::{WdlFile, WdlTileMesh};
 
-// The map arc (decision 0203), phase 0: the minimap tile hash catalog + the world-map DBCs.
+// The minimap tile hash catalog and the world-map DBCs.
 mod minimap_translate;
 pub use minimap_translate::{load_minimap_translate, MinimapTranslate};
 mod world_map_area;
@@ -338,39 +328,29 @@ pub use race_pvp_team::load_race_pvp_teams;
 mod zone_map;
 pub use zone_map::{load_zone_map, ZONE_MAP_EDGE};
 
-// The transport arc (decision 0438), phase 0: the taxi/transport path DBC adapter + timetable.
+// Taxi and transport paths, and the transport timetable.
 mod taxi;
 pub use taxi::{load_taxi_path_nodes, TaxiPathNode, TaxiPathNodes};
 mod transport_period;
 mod transports;
 pub use transports::{TransportSample, TransportTimetable};
-// The transport arc phase 3's second consumer: type-11 elevator/lift keyframe paths.
+// Type-11 elevator and lift keyframe paths.
 mod elevators;
 pub use elevators::{
     elevator_period_ms, elevator_sample, load_elevator_paths, ElevatorKeyframe, ElevatorPaths,
 };
 
-// The taxi arc (decision 0484), phase 1: the flight-master catalogs — node identity/position/
-// per-team mount (`TaxiNodes.dbc`) and the direct-hop fare table (`TaxiPath.dbc`). Distinct from
-// `taxi`/`TaxiPathNode.dbc` above, which carries a path's waypoints, not its node list or price.
+// The flight-master catalogs: nodes (`TaxiNodes.dbc`) and direct-hop fares (`TaxiPath.dbc`).
+// `taxi` above holds a path's waypoints.
 mod taxi_nodes;
 pub use taxi_nodes::{load_taxi_nodes, TaxiNode, TaxiNodes};
 mod taxi_path;
 pub use taxi_path::{load_taxi_paths, TaxiPath, TaxiPaths};
 
-/// The ten vanilla base content archives, **lowest priority first** — the reference mounter's
-/// table (`0x82e12c`) at its carved fixed priorities (`dbc.MPQ` = 0x36 … `model.MPQ` = 0x3f),
-/// reversed so [`Chain`]'s later-wins order reproduces them (decision 1300).
-///
-/// This is only the *base* set: `patch.MPQ`, the `patch-?.MPQ` archives, and the optional
-/// `speech2.MPQ` are **discovered**, not listed — the whole mount law lives in [`Chain::open`].
-/// `base.MPQ` is deliberately absent: the reference opens it once for `telemetry.dat` and closes
-/// it before the mounter runs, so its contents are unreachable as assets (wow-re, VERIFIED).
-///
-/// The base archives hold the bulk of the data but carry **no `(listfile)`**; the master
-/// `(listfile)` (and most overrides) live in the patch archives, which is why the chain — not a
-/// single archive — is the correct unit to read from. Verified against the build-5875 client
-/// (`patch.MPQ` listfile = 26,350 entries).
+/// The ten base archives, lowest priority first: the reference mounter's table (`0x82e12c`),
+/// priority 0x36 (`dbc.MPQ`) to 0x3f (`model.MPQ`), in [`Chain`]'s later-wins order. The patch
+/// archives and `speech2.MPQ` are found by [`Chain::open`]; `base.MPQ` is left out, as the
+/// reference closes it before mounting (`0x5aa2d0`).
 pub const VANILLA_BASE_ORDER: &[&str] = &[
     "dbc.MPQ",
     "speech.MPQ",
@@ -384,17 +364,12 @@ pub const VANILLA_BASE_ORDER: &[&str] = &[
     "model.MPQ",
 ];
 
-/// Open a [`Chain`] from either a single `.MPQ` file or a vanilla `Data` directory. Thin wrapper over
-/// [`Chain::open`], kept as the established entry point used across the crate and the CLI.
+/// [`Chain::open`] on one `.MPQ` file or a vanilla `Data` directory.
 pub fn open_chain(path: &Path) -> Result<Chain> {
     Chain::open(path)
 }
 
-/// Decode a BLP texture from raw archive bytes and write it as a PNG at `out`.
-///
-/// Returns the source `(width, height)`. Used by the `benilla-extract` CLI. **1.12 textures are BLP2**
-/// (DXT-compressed or paletted Raw1 — NOT BLP1; verified). Decoded in-repo by [`benilla_blp`]
-/// (decision 0021); mip level 0 (full resolution) is written.
+/// Write a BLP2 texture's level 0 (1.12 ships no BLP1) as a PNG at `out`; returns its size.
 pub fn blp_to_png(blp_bytes: &[u8], out: &Path) -> Result<(u32, u32)> {
     let (w, h, rgba) = blp_to_rgba(blp_bytes)?;
     image::RgbaImage::from_raw(w, h, rgba)
@@ -404,10 +379,8 @@ pub fn blp_to_png(blp_bytes: &[u8], out: &Path) -> Result<(u32, u32)> {
     Ok((w, h))
 }
 
-/// One authored mip level's texel census — what a sampler minifying onto this level actually
-/// reads. Split by the alpha byte because the renderer's multiply lanes (Mod2x, `2·src·dst`) read
-/// **no alpha**: a texel the author left transparent still modulates the scene by its colour, so
-/// the "outside" colour of a cut-out is a look-bearing fact, not padding.
+/// One authored mip level's texel census, split by alpha: the multiply blends (Mod2x,
+/// `2·src·dst`) read no alpha, so a transparent texel's colour still modulates the scene.
 #[derive(Debug, Clone, PartialEq)]
 pub struct BlpMipStats {
     pub level: u32,
@@ -416,18 +389,15 @@ pub struct BlpMipStats {
     /// Texels with alpha 0 (the authored "outside") and with alpha > 0 (the "inside").
     pub outside: usize,
     pub inside: usize,
-    /// `(min, mean, max)` of the RGB **luma** (`(r+g+b)/3`) over the outside / inside texels;
-    /// `None` when that class is empty.
+    /// `(min, mean, max)` luma, `(r+g+b)/3`, over the outside and the inside texels.
     pub outside_luma: Option<(u8, f32, u8)>,
     pub inside_luma: Option<(u8, f32, u8)>,
-    /// Texels whose luma is below 128 — under Mod2x each of these DARKENS the scene.
+    /// Texels with luma below 128, each of which darkens the scene under Mod2x.
     pub below_128: usize,
 }
 
-/// Census every authored mip level of an in-memory BLP (see [`BlpMipStats`]), decoding through the
-/// same [`benilla_blp::decode`] every CPU consumer uses. The "what does the far sampler see"
-/// instrument: a texture whose mip 0 reads neutral can still carry dark tail levels, and the tail
-/// is all a minified streak or sprite ever samples.
+/// [`BlpMipStats`] for every authored level, decoded as CPU consumers decode: a neutral level 0
+/// can hide dark tail levels, which are all a minified sprite samples.
 pub fn blp_mip_stats(blp_bytes: &[u8]) -> Result<Vec<BlpMipStats>> {
     let decoded =
         benilla_blp::decode(blp_bytes).map_err(|e| anyhow::anyhow!("decoding BLP: {e}"))?;
@@ -471,8 +441,7 @@ pub fn blp_mip_stats(blp_bytes: &[u8]) -> Result<Vec<BlpMipStats>> {
         .collect())
 }
 
-/// Write **every** authored mip level of a BLP as `<stem>.mip<N>.png` beside `out` (whose own
-/// path receives level 0, exactly as [`blp_to_png`] does), and return the per-level census.
+/// Write every authored level as `<stem>.mip<N>.png` beside `out`, level 0 at `out` itself.
 pub fn blp_mips_to_png(blp_bytes: &[u8], out: &Path) -> Result<Vec<BlpMipStats>> {
     let decoded =
         benilla_blp::decode(blp_bytes).map_err(|e| anyhow::anyhow!("decoding BLP: {e}"))?;
@@ -493,9 +462,7 @@ pub fn blp_mips_to_png(blp_bytes: &[u8], out: &Path) -> Result<Vec<BlpMipStats>>
     blp_mip_stats(blp_bytes)
 }
 
-/// Decode a BLP texture (raw bytes) to RGBA8: `(width, height, pixels)`.
-///
-/// For feeding GPU textures (the renderer) without a disk round-trip; mip level 0.
+/// Decode a BLP's level 0 to RGBA8: `(width, height, pixels)`.
 pub fn blp_to_rgba(blp_bytes: &[u8]) -> Result<(u32, u32, Vec<u8>)> {
     let decoded =
         benilla_blp::decode(blp_bytes).map_err(|e| anyhow::anyhow!("decoding BLP: {e}"))?;
@@ -516,47 +483,32 @@ pub fn read_texture_rgba(chain: &mut Chain, path: &str) -> Result<(u32, u32, Vec
     blp_to_rgba(&bytes)
 }
 
-/// A BLP's authored mip pyramid, mip-major, level 0 first.
-/// **Never empty**: the chain length is `BlpHeader::mipmaps_count().max(1)` — a no-mipmaps BLP (the
-/// count formula reports 0) still yields a 1-level chain (level 0), matching `benilla_blp::decode`'s
-/// own guarantee that `mips` is never empty (see [`blp_bytes_to_mip_chain`]).
-///
-/// [`texels`](Self::texels) says what the buffers hold. [`blp_bytes_to_mip_chain`] always decodes to
-/// `Rgba8Unorm`; [`blp_bytes_to_native_chain`] keeps DXTC blocks verbatim for a GPU that can eat
-/// them. A consumer that reads texels on the CPU must use the former (or check `texels`).
+/// A BLP's authored mip levels, level 0 first, never empty: a no-mipmaps BLP is one level.
+/// [`texels`](Self::texels) says whether they hold pixels or DXTC blocks.
 #[derive(Debug, Clone)]
 pub struct BlpMipChain {
-    /// Mip-0 dimensions; level i's dims are `(width >> i).max(1) × (height >> i).max(1)`.
+    /// Level 0's dimensions.
     pub width: u32,
     pub height: u32,
-    /// What every entry of `mips` holds — decoded pixels, or S3TC blocks.
+    /// What every level holds: decoded pixels or S3TC blocks.
     pub texels: BlpTexels,
-    /// One buffer per authored mip level, level 0 first. **Authored, not regenerated** —
-    /// the BLP's pre-baked mip levels are what the real 1.12 client uploads ("the BLP's own stored mip
-    /// chain is used verbatim — no client-side mip regeneration"). Using these instead of
-    /// CPU-resampling mip 0 in gamma byte space is the
-    /// C2 fix: gamma-byte averaging of texels darkens mid-tones (the historical "dim/cool"
-    /// terrain tone gap).
+    /// One buffer per authored level; the 1.12 client uploads the BLP's stored levels and never
+    /// regenerates them.
     pub mips: Vec<Vec<u8>>,
 }
 
 impl BlpMipChain {
-    /// Width × height of the mip level `i`, clamped to 1×1 minimum (wgpu / GL convention).
+    /// Level `i`'s size, at least 1×1.
     pub fn mip_size(&self, i: u32) -> (u32, u32) {
         ((self.width >> i).max(1), (self.height >> i).max(1))
     }
 
-    /// Are these levels CPU-readable `Rgba8Unorm` pixels? The guard for any consumer that indexes
-    /// into a level (resample, alpha stomp, colour read) — block bytes are not pixels.
+    /// Whether the levels are `Rgba8Unorm` pixels a CPU reader can index, not blocks.
     pub fn is_rgba8(&self) -> bool {
         !self.texels.is_block_compressed()
     }
 
-    /// This chain with every level decoded to `Rgba8Unorm`; a no-op if it already is.
-    ///
-    /// The escape hatch for a consumer that asked for the passthrough form and then could not use
-    /// it — it costs the decode it was trying to avoid, but it needs no second read of the file and
-    /// it cannot fail, so the caller is never left holding blocks it must not upload.
+    /// Every level decoded to `Rgba8Unorm` without rereading the file; a no-op if already so.
     pub fn into_rgba8(self) -> Self {
         if self.is_rgba8() {
             return self;
@@ -578,11 +530,7 @@ impl BlpMipChain {
     }
 }
 
-/// Decode every authored mip level of a BLP texture from the chain into `Rgba8Unorm` buffers.
-///
-/// One RGBA8 allocation per mip level (8 for a 256² with 8 mips). Caller is responsible for any
-/// further processing (concatenation, upload, BCn re-encode). The mip pyramid is the BLP's own,
-/// not regenerated — the C2-faithful behaviour.
+/// Read a texture from the chain and decode every authored level to `Rgba8Unorm`.
 pub fn read_texture_mip_chain(chain: &mut Chain, path: &str) -> Result<BlpMipChain> {
     let name = path.replace('/', "\\");
     let bytes = chain
@@ -591,8 +539,7 @@ pub fn read_texture_mip_chain(chain: &mut Chain, path: &str) -> Result<BlpMipCha
     blp_bytes_to_mip_chain(&bytes).with_context(|| format!("decoding texture '{name}'"))
 }
 
-/// Read a texture from the chain by internal path and keep its DXTC blocks verbatim —
-/// [`blp_bytes_to_native_chain`]'s chain-reading wrapper, the twin of [`read_texture_mip_chain`].
+/// Read a texture from the chain, keeping its DXTC blocks ([`blp_bytes_to_native_chain`]).
 pub fn read_texture_native_chain(chain: &mut Chain, path: &str) -> Result<BlpMipChain> {
     let name = path.replace('/', "\\");
     let bytes = chain
@@ -601,17 +548,10 @@ pub fn read_texture_native_chain(chain: &mut Chain, path: &str) -> Result<BlpMip
     blp_bytes_to_native_chain(&bytes).with_context(|| format!("decoding texture '{name}'"))
 }
 
-/// Decode every authored mip level of an **in-memory** BLP into `Rgba8Unorm` buffers — the BLP's own
-/// stored pyramid, used verbatim (no client-side regeneration; the C2-faithful behaviour). This is the
-/// bytes-in entry point used by the Bevy `AssetLoader`; [`read_texture_mip_chain`] is the
-/// chain-reading wrapper.
+/// Decode every authored level of an in-memory BLP to `Rgba8Unorm`, as stored.
 pub fn blp_bytes_to_mip_chain(bytes: &[u8]) -> Result<BlpMipChain> {
     let decoded = benilla_blp::decode(bytes).map_err(|e| anyhow::anyhow!("decoding BLP: {e}"))?;
-    // `decode` guarantees `mips` is never empty: it always decodes level 0 regardless of the
-    // authored mip-chain count (`benilla_blp::decode`, `n = chain.clamp(1, 16)`, so the loop that
-    // fills `mips` runs at least once) — a no-mipmaps BLP reports `mip_chain_count() == 0` but still
-    // carries `mips[0]`. Take at least that one level: the chain we return is never empty, so a
-    // mipmap-less BLP yields a 1-level chain here, not zero.
+    // A no-mipmaps BLP counts 0 levels, yet `decode` always fills `mips[0]`: take at least one.
     let (width, height, count) = (
         decoded.width,
         decoded.height,
@@ -631,17 +571,13 @@ pub fn blp_bytes_to_mip_chain(bytes: &[u8]) -> Result<BlpMipChain> {
     })
 }
 
-/// Every authored mip level of an in-memory BLP **with its DXTC blocks kept verbatim** — the form
-/// the reference client uploads (`glCompressedTexImage2DARB`; wow-re `system/image/image.md`).
-///
-/// Raw1/Raw3 BLPs have no block form and come back decoded, reporting
-/// [`BlpTexels::Rgba8Unorm`] — so a caller switches on [`BlpMipChain::texels`] rather than
-/// assuming. Levels are padded to whole blocks, so the concatenated chain is exactly what wgpu
-/// expects for the reported format.
+/// Every authored level of an in-memory BLP with its DXTC blocks kept, as the reference uploads
+/// them (`glCompressedTexImage2DARB`, `0x59f5b0`). Raw1 and Raw3 come back decoded; levels are
+/// padded to whole blocks.
 pub fn blp_bytes_to_native_chain(bytes: &[u8]) -> Result<BlpMipChain> {
     let decoded =
         benilla_blp::decode_native(bytes).map_err(|e| anyhow::anyhow!("decoding BLP: {e}"))?;
-    // Same floor-at-one reasoning as `blp_bytes_to_mip_chain`.
+    // At least one level, as in `blp_bytes_to_mip_chain`.
     let (width, height, count) = (
         decoded.width,
         decoded.height,
@@ -662,21 +598,12 @@ pub fn blp_bytes_to_native_chain(bytes: &[u8]) -> Result<BlpMipChain> {
     })
 }
 
-/// A hand-defined schema for a known 1.12 DBC, keyed by base filename, or `None`.
-///
-/// DBC files carry no column types, so the schema is ours to supply (from wowdev.wiki +
-/// the verified file header). Vanilla localized strings occupy **9 dwords** (8 locale
-/// offsets + 1 flags); only the enUS slot is populated in an enUS client. As we need more
-/// DBCs (Map, AreaTable, ...) add them here.
+/// Our schema for a known 1.12 DBC by base filename, as DBC files carry no column types. A
+/// localized string is 9 dwords: 8 locale offsets and a flags word.
 fn schema_for(dbc_name: &str) -> Option<Schema> {
     let base = dbc_name.rsplit(['/', '\\']).next().unwrap_or(dbc_name);
 
-    // Tables whose schema a typed loader in this crate already declares: reuse *that* constructor
-    // rather than re-transcribing the layout here, so a dump can never disagree with what the client
-    // actually reads (the six hand-written schemas below predate any loader for their table).
-    // The appearance family is registered because "which row does this NPC render from?" is a
-    // recurring question; the crate has ~30 more loader schemas that could join this list one line
-    // at a time as they are needed.
+    // A table with a typed loader reuses its schema, so a dump reads what the loader reads.
     for (name, ctor) in [
         (
             "CreatureDisplayInfo.dbc",
@@ -719,7 +646,7 @@ fn schema_for(dbc_name: &str) -> Option<Schema> {
     }
 
     if base.eq_ignore_ascii_case("TaxiNodes.dbc") {
-        // 16 fields (record_size 64), verified against build 5875.
+        // 16 fields, 64-byte records.
         let mut s = Schema::new("TaxiNodes");
         s.add_field(SchemaField::new("ID", FieldType::UInt32));
         s.add_field(SchemaField::new("MapID", FieldType::UInt32));
@@ -740,8 +667,7 @@ fn schema_for(dbc_name: &str) -> Option<Schema> {
     }
 
     if base.eq_ignore_ascii_case("AreaTable.dbc") {
-        // 25 fields (record_size 100), verified against build 5875 (the layout
-        // `area_table.rs` / `area_sound.rs` load from).
+        // 25 fields, 100-byte records, as `area_table.rs` and `area_sound.rs` load them.
         let mut s = Schema::new("AreaTable");
         s.add_field(SchemaField::new("ID", FieldType::UInt32));
         s.add_field(SchemaField::new("ContinentID", FieldType::UInt32));
@@ -771,8 +697,7 @@ fn schema_for(dbc_name: &str) -> Option<Schema> {
     }
 
     if base.eq_ignore_ascii_case("GameObjectDisplayInfo.dbc") {
-        // 12 fields (ID, ModelName, Sound[10]) — the layout `gameobjects.rs`'s own typed adapter
-        // loads from (verified build 5875).
+        // 12 fields, as `gameobjects.rs` loads them.
         let mut s = Schema::new("GameObjectDisplayInfo");
         s.add_field(SchemaField::new("ID", FieldType::UInt32));
         s.add_field(SchemaField::new("ModelName", FieldType::String));
@@ -784,7 +709,6 @@ fn schema_for(dbc_name: &str) -> Option<Schema> {
     }
 
     if base.eq_ignore_ascii_case("TaxiPath.dbc") {
-        // 4 fields: ID, FromTaxiNode, ToTaxiNode, Cost — verified build 5875.
         let mut s = Schema::new("TaxiPath");
         for name in ["ID", "FromTaxiNode", "ToTaxiNode", "Cost"] {
             s.add_field(SchemaField::new(name, FieldType::UInt32));
@@ -794,8 +718,7 @@ fn schema_for(dbc_name: &str) -> Option<Schema> {
     }
 
     if base.eq_ignore_ascii_case("TaxiPathNode.dbc") {
-        // 9 fields (ID, PathID, NodeIndex, MapID, LocX/Y/Z, Flags, Delay) — the layout
-        // `taxi.rs`'s own typed adapter loads from (decision 0438 phase 0, verified build 5875).
+        // 9 fields, as `taxi.rs` loads them.
         let mut s = Schema::new("TaxiPathNode");
         for name in ["ID", "PathID", "NodeIndex", "MapID"] {
             s.add_field(SchemaField::new(name, FieldType::UInt32));
@@ -811,10 +734,8 @@ fn schema_for(dbc_name: &str) -> Option<Schema> {
     }
 
     if base.eq_ignore_ascii_case("TransportAnimation.dbc") {
-        // 7 fields: ID, TransportID, TimeIndex, PosX, PosY, PosZ, SequenceID — matches vmangos's
-        // `TransportAnimationEntry` (`DBCStructure.h:709-718`), which only reads the middle five
-        // (TransportEntry/TimeSeg/X/Y/Z) but the row itself carries all 7 (its own `Id` and
-        // `MovementId` columns are commented out there, not absent from the file).
+        // 7 fields; vmangos's `TransportAnimationEntry` (`DBCStructure.h:709-718`) reads the
+        // middle five, leaving the first and last out.
         let mut s = Schema::new("TransportAnimation");
         s.add_field(SchemaField::new("ID", FieldType::UInt32));
         s.add_field(SchemaField::new("TransportID", FieldType::UInt32));
@@ -830,10 +751,8 @@ fn schema_for(dbc_name: &str) -> Option<Schema> {
     None
 }
 
-/// Parse a DBC (raw archive bytes) using our schema for it and write it as CSV with
-/// column headers. Returns `(record_count, field_count)`. Errors if we have no schema for
-/// the named DBC (with a hint), so a wrong/missing schema fails loudly rather than silently
-/// misaligning columns.
+/// Write a DBC as CSV through our schema for it, returning `(record_count, field_count)`; an error
+/// when there is no schema or its field count is wrong.
 pub fn dbc_to_csv(dbc_bytes: &[u8], dbc_name: &str, out: &Path) -> Result<(u32, u32)> {
     let mut cursor = Cursor::new(dbc_bytes);
     let parser =
@@ -868,8 +787,7 @@ pub fn dbc_to_csv(dbc_bytes: &[u8], dbc_name: &str, out: &Path) -> Result<(u32,
 mod tests {
     use super::*;
 
-    /// A minimal, complete BLP2 header (magic..=mip_sizes[16], 148 bytes) — mirrors the private
-    /// builder in `benilla_blp`'s own tests (that crate's helper isn't exported).
+    /// A complete 148-byte BLP2 header, magic through `mip_sizes[16]`.
     fn blp2_header(
         compression: u8,
         alpha_bits: u8,
@@ -899,12 +817,7 @@ mod tests {
         b
     }
 
-    /// THE VERIFIED LATENT PANIC, regression-pinned: a no-mipmaps BLP2 (`has_mipmaps = 0`) makes
-    /// `benilla_blp::decode` report `mip_chain_count() == 0`, which `blp_bytes_to_mip_chain` used to
-    /// take literally (`.take(0)`), returning an **empty** `mips` — `benilla-assets`' `world_art_image`
-    /// then panics on `chain.mips[0]`. `decode` itself always keeps level 0 regardless of the count
-    /// (see the comment on `blp_bytes_to_mip_chain`), so the fix is to floor the take at 1: this must
-    /// yield a 1-level chain, never an empty one.
+    /// `has_mipmaps = 0` counts 0 levels, and consumers index `mips[0]`.
     #[test]
     fn no_mipmap_blp_yields_a_one_level_chain_not_empty() {
         const HEADER_SIZE: usize = 148;
@@ -936,16 +849,9 @@ mod tests {
         assert_eq!(chain.mips[0].len(), 2 * 2 * 4);
     }
 
-    /// **B358 / B225, "black rain", pinned on the shipped asset.** `RainDrop01.blp` (16×128
-    /// DXT3) under-stores its sub-block levels — 16 bytes for the 2×16 level where the block grid
-    /// needs 64, 16 for the 1×8 where it needs 32 — and a decoder that zero-fills the difference
-    /// makes those levels three-quarters and half BLACK (an all-zero BC2 block is colour 0 at
-    /// alpha 0). The rain streak draws that texture under Mod2x, which reads no alpha, so a far
-    /// streak minifying onto levels 3–4 multiplied the scene toward black. The reference completes
-    /// a short level from the bytes that follow it in the file (`0x5a5780`), which for this asset
-    /// are the next levels' own grey blocks. This is the census the fix was judged by: every level
-    /// the sampler can reach stays inside the texture's authored neutral band, and level 3's second
-    /// block IS level 4's first — the reference's copy, byte for byte. Skips without the client data.
+    /// `RainDrop01.blp` (16×128 DXT3) stores 16 bytes for its 2×16 and 1×8 levels, which need 64
+    /// and 32. The reference completes a short level from the bytes after it (`0x5a5780`); a zero
+    /// fill would darken the Mod2x rain streak toward black.
     #[test]
     fn the_rain_streak_texture_is_neutral_on_every_level_the_sampler_reaches() {
         let data = crate::wow_data_or_skip!();
@@ -961,8 +867,7 @@ mod tests {
             native.mips.len() >= 5,
             "the tail levels are what this is about"
         );
-        // Level 3 (2×16) is four blocks wide-grid; the file stores one. Blocks 2–4 are the
-        // following levels' — block 2 is level 4's own first block.
+        // Level 3 (2×16) needs four blocks and stores one; its second is level 4's first.
         assert_eq!(native.mips[3].len(), 64);
         assert_eq!(
             &native.mips[3][16..32],
@@ -973,8 +878,7 @@ mod tests {
             native.mips[3][16..].iter().any(|&x| x != 0),
             "level 3's completion is never zero-filled"
         );
-        // And the look-bearing fact, as the Mod2x lane reads it: no texel on any level darkens
-        // the scene by more than the authored grey does (luma ≥ 120; the authored band is 125–164).
+        // No texel on any level falls below luma 120; the authored band is 125 to 164.
         let stats = blp_mip_stats(&bytes).expect("census");
         for s in &stats {
             for (class, luma) in [("outside", s.outside_luma), ("inside", s.inside_luma)] {
@@ -992,10 +896,6 @@ mod tests {
         }
     }
 
-    /// Every table the CSV dumper claims in its error hint really has a schema, and each dumps
-    /// against the **shipped** file — which is the only check that matters, because `with_schema`
-    /// rejects a field-count mismatch and `dbc_to_csv` would otherwise fail only when a session
-    /// reached for it mid-investigation. Skips without the client data.
     #[test]
     fn registered_dbc_schemas_dump_the_shipped_tables() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/light.rs b/crates/benilla-formats/src/light.rs
index abc5df50..3edc847e 100644
--- a/crates/benilla-formats/src/light.rs
+++ b/crates/benilla-formats/src/light.rs
@@ -1,21 +1,6 @@
-//! Authentic vanilla atmosphere from the client's lighting DBCs — so fog distance/color and
-//! sun/ambient tint come from Blizzard's authored data, not invented constants.
-//!
-//! Pipeline: [`Light.dbc`] gives a sphere per area (a world
-//! position via [`dbc_to_world`] + a radius in yards) and a `LightParams` id per weather condition;
-//! that id indexes the band tables — [`LightIntBand.dbc`] (18 color rows/param) and
-//! [`LightFloatBand.dbc`] (6 float rows/param) — each row a value over time-of-day. We sample the
-//! **clear-weather** param at a given time and return the fog/sun/ambient/sky values.
-//!
-//! **Verified against build 5875** (raw-byte decode cross-checked with wowdev.wiki, 2026-05-25):
-//! headers are Light = 12 fields/48 B (5 param refs), both bands = 34 fields/136 B
-//! (`ID, num, time[16], value[16]`). LightIntBand = 7668 = 426×18 rows and LightFloatBand =
-//! 2556 = 426×6 rows — i.e. exactly 18 int / 6 float rows per LightParams, confirming the band row
-//! id for param `P` (1-based), band index `b`: `(P-1)*per + b + 1` (== wiki `P*18−17` / `P*6−5`).
-//! The int-row→meaning map is the **vanilla** layout (rows 2–6 = the 5 sky stops, 7 = fog, 9 = sun),
-//! confirmed by the data itself (row 8 is flat gray = shadow-opacity slot, not a sun). The
-//! decoded values match our parser exactly (e.g. Northshire/global-light param 12 noon SkyMiddle
-//! = `(58,162,207)`).
+//! The atmosphere from the lighting DBCs: fog, sun, ambient and sky colours from authored data.
+//! `Light.dbc` gives a sphere per area and a `LightParams` id per weather slot; param `P` keys 18
+//! `LightIntBand` and 6 `LightFloatBand` rows, row `b` at id `(P − 1)·per + b + 1`.
 
 use std::collections::HashMap;
 
@@ -25,8 +10,8 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 use crate::dbc::{f32_at, parse, str_at, u32_at};
 use crate::Chain;
 
-mod atmosphere; // the resolved `Atmosphere` output type + the DBC row/field → meaning constants
-mod tables; // raw LightIntBand/FloatBand decode + time-of-day interpolation
+mod atmosphere;
+mod tables;
 
 pub use atmosphere::Atmosphere;
 use atmosphere::{
@@ -44,76 +29,45 @@ const FLOAT_BAND: &str = "DBFilesClient\\LightFloatBand.dbc";
 const LIGHT_PARAMS: &str = "DBFilesClient\\LightParams.dbc";
 const LIGHT_SKYBOX: &str = "DBFilesClient\\LightSkybox.dbc";
 
-/// World-unit scale factor on Light.dbc positions/radii (stored as yards × 36).
+/// `Light.dbc` positions and radii are inches: yards × 36.
 const POS_SCALE: f32 = 36.0;
 
-/// Light.dbc weather param slots: [0]=clear, [1]=clear-underwater, [2]=storm, [3]=storm-underwater,
-/// [4]=death.
+/// `Light.dbc` param slots: 0 clear, 1 clear underwater, 2 storm, 3 storm underwater, 4 death.
 const SLOT_CLEAR: usize = 0;
-/// `[1]` clear-underwater: the denser fog + cooler light the client switches to when the eye is
-/// submerged in **water** (VERIFIED apitrace WoW.18: ~38 yd teal fog + blue ambient/diffuse vs the
-/// ~1284 yd surface fog). Same band-row meanings as the clear slot, just a different `LightParams` id.
-/// Reached only by [`Submersion::Water`] — magma and slime never consult a zone slot at all
-/// (see [`PARAM_MAGMA`]).
+/// Denser fog and cooler light while the eye is under water; only the water kinds reach it,
+/// magma and slime take fixed rows ([`PARAM_MAGMA`]).
 const SLOT_CLEAR_UNDERWATER: usize = 1;
 const SLOT_STORM: usize = 2;
 const SLOT_STORM_UNDERWATER: usize = 3;
-/// The ghost-world profile — byte-VERIFIED (wow-re death-light.md): the client's ghost watcher
-/// writes slot index 4 into the active-slot global `[0xce9bb0]` and the day/night color-table
-/// rebuild consumes it INSTANTLY (per-frame rebuild, no blend). Selected while `ghost`, taking
-/// priority over weather/underwater exactly as the single global slot does.
+/// The ghost profile: the ghost watcher `0x5de9c0` writes slot 4 into the active-slot global
+/// `[0xce9bb0]`, and the colour-table rebuild takes it at once, with no blend, over all else.
 const SLOT_DEATH: usize = 4;
 
-/// The **fixed global `LightParams` rows** the reference uses for submersion in the two fullbright
-/// liquids — byte-VERIFIED (`0x6d2371` routes magma and slime to their own leg *before* the slot
-/// selection: magma at `0x6d23e1` reads row 7, slime at `0x6d239e` reads row 6, each guarded on the
-/// table's `maxId`). These are **zone-independent** and nothing in `Light.dbc` references them, which
-/// is why no position-keyed dump ever surfaced them: submersion in lava does not read the zone's
-/// underwater slot at all.
-///
-/// The shipped rows are exactly the vanilla look, which is the cross-check that earned this:
-/// magma fog `[200,52,0]` at **27 yd** with start fraction **−2.0** (67 % fiery orange at the eye),
-/// slime fog `[0,255,0]` at **50 yd** with **−1.0** (50 % green). There is no separate magma/slime
-/// fog constant anywhere in the binary (VERIFIED negative) — these two rows *are* the distinct look.
+/// The fixed global rows for submersion in slime (6) and magma (7): `0x6d2371` branches before
+/// the slot selection, to row 7 at `0x6d23e1` and row 6 at `0x6d239e`, each guarded on `maxId`.
+/// No `Light.dbc` row names them, and the binary has no other magma or slime fog.
 const PARAM_SLIME: u32 = 6;
 const PARAM_MAGMA: u32 = 7;
 
-/// The ocean depth ramp's floor — `0x81162c` = −30.0f. Below this the factors hold flat.
+/// The ocean depth ramp's floor, −30.0 at `0x81162c`; the factors hold flat below it.
 const OCEAN_RAMP_FLOOR: f32 = -30.0;
-/// The ramp's reciprocal, **as the binary stores it** — the f32 at `0x811628`, bit pattern
-/// `0xbd088889`.
-///
-/// Written from the bits rather than as a decimal on purpose. The decimal wow-re quotes
-/// (`−0.0333333351`) carries more digits than an f32 holds, so spelling it out is both a clippy
-/// `excessive_precision` error and a small lie about what is in the file; and rounding it to
-/// `−0.033_333_335` would read as a value someone chose. `from_bits` says the true thing: this
-/// constant is a bit pattern lifted out of the image. (It happens to equal `-1.0f32 / 30.0` — see
-/// [`Submersion::ocean_depth_factors`] for why that is not the point.)
+/// The ramp's reciprocal as the binary stores it, the f32 at `0x811628`, written from its bits
+/// (`0xbd088889`) because the decimal trips clippy's `excessive_precision`.
 const OCEAN_RAMP_RECIP: f32 = f32::from_bits(0xbd08_8889);
 
-/// What the camera eye is submerged in, if anything — the atmosphere selector. Water and ocean pick
-/// the zone's *underwater slot*; magma and slime replace the whole area blend with a fixed global row
-/// (see [`PARAM_MAGMA`]/[`PARAM_SLIME`]).
-///
-/// **Five states, because the reference has five.** `[0xc7f288] ∈ {0xf dry, 0 water, 1 ocean,
-/// 2 magma, 3 slime}` — and ocean is not a synonym for water. It is the only kind that runs the
-/// depth ramp ([`Submersion::ocean_depth_factors`]), which is gated on the **full unmasked dword
-/// `== 1`** at `0x6d2821` (not the nibble — `0x11` would pass a nibble test and must not). Every
-/// other consumer image-wide treats the two alike, so this enum forks in exactly one place, which
-/// is the shape of the finding.
-///
-/// Collapsing them, as we did until decision 1829, was not a small approximation: ocean is
-/// **96.8% of every wet sub-tile** in the shipped corpus (14 069 166 of 14 528 712). The state we
-/// were not modelling was essentially all open water.
+/// What the camera eye is submerged in. Water and ocean take the zone's underwater slot, magma
+/// and slime a fixed row. The reference's five states, `[0xc7f288]` ∈ {0xf dry, 0 water, 1 ocean,
+/// 2 magma, 3 slime}: only ocean runs the depth ramp, gated on the whole dword `== 1` at
+/// `0x6d2821` (a nibble test would pass 0x11); everything else treats ocean as water.
 #[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
 pub enum Submersion {
-    /// Dry — the ordinary clear/storm slot.
+    /// Dry: the ordinary clear or storm slot.
     #[default]
     Dry,
-    /// Under still water or rapids: the zone's own underwater `LightParams`, area-blended as usual.
+    /// Under still water or rapids: the zone's underwater `LightParams`, area-blended as usual.
     Water,
-    /// Under **ocean**: the same underwater slot as [`Self::Water`], plus the depth ramp. Comes
-    /// only from the ADT MCLQ per-subtile flags (`(b & 0x0f) & 3 == 1`); a WMO cannot author it.
+    /// Under ocean: the water slot plus the depth ramp. Only the ADT MCLQ per-subtile flags
+    /// author it (`(b & 0x0f) & 3 == 1`); a WMO cannot.
     Ocean,
     /// Under magma: the fixed global row, verbatim.
     Magma,
@@ -122,50 +76,23 @@ pub enum Submersion {
 }
 
 impl Submersion {
-    /// Submerged in **any** liquid.
+    /// Submerged in any liquid.
     pub fn any(self) -> bool {
         self != Submersion::Dry
     }
 
-    /// Submerged specifically in a WATER kind (water / ocean / rapids) — the predicate for the
-    /// consumers that are about water rather than about liquid: the `UnderWaterLoop` ambience bed and
-    /// the "Underwater" reverb-preference column.
-    ///
-    /// Deliberately NOT [`Self::any`]: whether the reference swaps the submerged ambience bed and the
-    /// reverb preset for **lava and slime** as well is unverified, and widening it silently on the way
-    /// past would be inventing a behaviour. The atmosphere is verified per kind; the audio is not.
-    ///
-    /// [`Submersion::Ocean`] belongs here with [`Submersion::Water`]: the split exists for the depth
-    /// ramp alone, and every other consumer — the underwater slot, the ambience bed, the reverb
-    /// column, the drift cloud's cell set — treats a sea exactly like a lake.
+    /// A water kind (water, ocean, rapids), for the `UnderWaterLoop` bed and the underwater reverb;
+    /// whether the reference swaps those for magma and slime too is untraced.
     pub fn is_water(self) -> bool {
         matches!(self, Submersion::Water | Submersion::Ocean)
     }
 
-    /// The **ocean depth ramp** — the one thing ocean does that water does not (wow-re
-    /// `lighting/scratch/submerged-atmosphere.md` §3, VERIFIED; decision 1829).
-    ///
-    /// Returns `(fac1, fac2)`, the multipliers on the committed light record's first and second
-    /// colour triples — `DNState+0x178 × fac1` and `DNState+0x174 × fac2`. `fac1` runs `1.0 → 0.5`
-    /// and `fac2` runs `1.0 → 0.75` over the first 30 yards of depth, so the fill darkens twice as
-    /// fast as the direct term and a deep sea goes flat as well as dim.
-    ///
-    /// **A multiply by the stored constant, not a divide by 30.** wow-re's note says
-    /// "`−0.0333333351f` is not exactly −1/30 — a bit-exact reimplementation must use the stored
-    /// f32, not `t/30.0`". The conclusion is right and the reason as stated is not, which matters
-    /// because it changes what you have to be careful about: `0xbd088889` **is** the nearest f32 to
-    /// −1/30, bit for bit. What differs is the *operation* — `t · recip` and `t / 30.0` round
-    /// differently, and they disagree inside the ramp's own range (at `t = −29` by 6e−8 in `k`).
-    /// So the thing to transcribe is the multiply, and the constant is incidental.
-    ///
-    /// The boundaries are exact, not near-misses: `k` reaches exactly `0.0` at −30 yd, so `fac1`
-    /// bottoms at exactly 0.5 and `fac2` at exactly 0.75.
-    ///
-    /// **Not the fog colour.** The binary commits this ramp to three slots, but the fog-colour one
-    /// (`0x6d28b0` → `DNState+0x70`) is dead: `0x66ff60` calls the tint and *then* calls `0x6cee30`,
-    /// whose `0x6cee76` unconditionally overwrites that slot from the band-derived colour. The
-    /// underwater murk colour reaches the screen through the LightParams slot switch we already
-    /// have; this ramp darkens two light bands and nothing else.
+    /// The ocean depth ramp (`0x6d2823`, behind the gate `0x6d2821`): `(fac1, fac2)` multiply the
+    /// light record's colour triples `DNState+0x178` and `DNState+0x174`, running 1.0 → 0.5 and
+    /// 1.0 → 0.75 over the first 30 yd of depth. Keep the multiply by the stored reciprocal:
+    /// `t / 30.0` rounds differently inside the range (at −29 yd, by 6e−8). The fog colour it also
+    /// writes (`0x6d28b0` → `DNState+0x70`) is overwritten from the bands: `0x66ff60` calls
+    /// `0x6cee30` after the tint, whose `0x6cee76` rewrites that slot.
     pub fn ocean_depth_factors(self, eye_z: f32) -> Option<(f32, f32)> {
         if self != Submersion::Ocean {
             return None;
@@ -175,8 +102,7 @@ impl Submersion {
         Some(((k + 1.0) * 0.5, k * 0.25 + 0.75))
     }
 
-    /// The fixed global `LightParams` row this submersion replaces the whole blend with, if any.
-    /// `None` for the dry and water-kind states, which go through the slot selection.
+    /// The fixed global `LightParams` row that replaces the whole blend, for magma and slime.
     fn fixed_param(self) -> Option<u32> {
         match self {
             Submersion::Magma => Some(PARAM_MAGMA),
@@ -186,11 +112,8 @@ impl Submersion {
     }
 }
 
-/// Pick the `LightParams` slot for the current ghost/weather/submersion state (see `SLOT_*`).
-/// Ghost wins outright — the client keeps ONE active slot, and the ghost watcher owns it while
-/// the flag is up. Only a **water kind** reaches the underwater slots (water or ocean alike — the
-/// slot switch does not distinguish them); the fullbright liquids never get here (their fixed row
-/// short-circuits the blend).
+/// The `LightParams` slot for the ghost, weather and submersion state: ghost wins outright, as
+/// the client keeps one active slot, and only a water kind reaches the underwater slots.
 fn weather_slot(ghost: bool, stormy: bool, underwater: bool) -> usize {
     if ghost {
         return SLOT_DEATH;
@@ -203,45 +126,28 @@ fn weather_slot(ghost: bool, stormy: bool, underwater: bool) -> usize {
     }
 }
 
-/// **The zero-match fallback record**, addressed by its `Light.dbc` **ID column** (not its row
-/// index) — wow-re `system/lighting/scratch/no-light-row-fallback.md`.
-///
-/// The client builds a per-map light array in `dn_light_array_build 0x6d6170` (`0x6d61a9 cmp
-/// [row+4], mapId`), and when **no row matches the map at all** its tail (`0x6d62b2`–`0x6d62c9`)
-/// writes `idMap[1]` — this record — into slot 0, unchecked. `dn_light_select 0x6d2d00` then
-/// no-ops (count ≤ 1 ⇒ empty blend heap) and the colour-table build commits that one record whole.
-/// The count is *seeded* at 1 (`0x6d6188 mov edi,1`), so the no-data white table (fog end 1e10) is
-/// the before-first-load state and is unreachable in world.
-///
-/// Shipped row 1 is the Azeroth global: map 0, `(0,0,0)`, falloff 0/0, params
-/// `(12, 13, 10, 11, 4)`. So a map with no `Light.dbc` row of its own — **Deeprun Tram (369) is the
-/// one that matters, and it is the only shipped map reachable in play with none** — renders under
-/// LightParams 12's ordinary six-key day curve, not under any invented constant.
+/// The zero-match fallback record, by `Light.dbc` ID. When no row matches the map, the light
+/// array build (`0x6d6170`, matching at `0x6d61a9`) writes record 1, the Azeroth global, into
+/// slot 0 (`0x6d62b2`..`0x6d62c9`) with the count seeded at 1 (`0x6d6188`), so `0x6d2d00` has
+/// nothing to blend. Deeprun Tram (369) is the one shipped map reachable in play that needs it.
 const FALLBACK_LIGHT_ID: u32 = 1;
 
 struct Light {
-    /// The row's own `Light.dbc` **ID column** — not its row index. Carried because the client's
-    /// zero-match fallback addresses one specific record *by id* ([`FALLBACK_LIGHT_ID`]).
+    /// The `Light.dbc` ID column, not the row index: the zero-match fallback names a record by id.
     id: u32,
     map: u32,
-    /// WoW net-protocol **world** coords (yards), converted from the DBC's mirrored/axis-swapped
-    /// inch frame via [`dbc_to_world`]. Meaningless when `global` (the sentinel was `(0,0,0)`).
+    /// World coordinates in yards (see [`dbc_to_world`]); meaningless when `global`.
     pos: [f32; 3],
-    /// Distance (yards) at which this light is at full strength; inside it `blendAlpha = 1`.
     falloff_start: f32,
     falloff_end: f32,
-    /// The continent's `(0,0,0)` fallback light — matches everywhere, lowest priority.
+    /// The continent's `(0,0,0)` light: matches everywhere, lowest priority.
     global: bool,
-    /// LightParams id per weather slot (see `SLOT_*`); 0 = unset.
+    /// `LightParams` id per slot (`SLOT_*`); 0 = unset.
     params: [u32; 5],
 }
 
-/// Convert a `Light.dbc` position to WoW net-protocol **world** coords (yards). The DBC stores
-/// continent coords as **inches** (yards × 36) in a mirrored, axis-swapped frame, so it is *not* a
-/// plain `/36`. Per wowdev.wiki `LightRec::ConvertDBToGameCoords` (the world-coord correction):
-/// `world.x = 17066.666 − z/36`, `world.y = 17066.666 − x/36`, `world.z = y/36`.
-/// `17066.666` = half the 34133⅓-yard map (32 tiles × 533⅓). Verified against decoded entries
-/// (e.g. Light #51 → `(-8480, 548, 81)`).
+/// A `Light.dbc` position to world yards: the DBC stores inches in a mirrored, axis-swapped frame
+/// (`LightRec::ConvertDBToGameCoords`), and 17066.666 is half the 34133⅓-yard map.
 fn dbc_to_world(x: f32, y: f32, z: f32) -> [f32; 3] {
     const MAP_HALF: f32 = 17066.666;
     [
@@ -256,23 +162,17 @@ pub struct LightCatalog {
     lights: Vec<Light>,
     int_bands: HashMap<u32, Band<u32>>,
     float_bands: HashMap<u32, Band<f32>>,
-    /// `LightParams.dbc` id → glow scalar (field [`LP_GLOW`]); the per-zone bloom composite weight.
+    /// `LightParams` id → glow ([`LP_GLOW`]), the per-zone bloom composite weight.
     light_params_glow: HashMap<u32, f32>,
-    /// `LightParams.dbc` id → `highlightSky` flag (field [`LP_HIGHLIGHT`]) as 0.0/1.0; gates the
-    /// per-zone dawn/dusk sky-dome warp.
+    /// `LightParams` id → `highlightSky` as 0.0/1.0, gating the dawn and dusk sky-dome warp.
     light_params_highlight: HashMap<u32, f32>,
-    /// `LightParams.dbc` id → water-blend alphas `[waterShallow, waterDeep, oceanShallow, oceanDeep]`
-    /// (fields 5–8). The from-above swatch's per-zone depth-alpha ramp endpoints.
+    /// `LightParams` id → the four water-blend alphas, the swatch's depth-alpha endpoints.
     light_params_water_alpha: HashMap<u32, [f32; 4]>,
-    /// `LightParams.dbc` id → `lightSkyboxID` (field [`LP_SKYBOX`]), kept only for the non-zero rows
-    /// — 5 of 426 in the shipped chain, every one of them the ghost sky.
+    /// `LightParams` id → `lightSkyboxID` ([`LP_SKYBOX`]), for its non-zero rows only.
     light_params_skybox: HashMap<u32, u32>,
-    /// `LightSkybox.dbc` id → the model it names, normalised to its chain path (`crate::models`'
-    /// `model_path`: lowercased, `.mdx` → the physical `.m2`) so both skybox sources hand the render
-    /// lane the same spelling and one model can never build twice under two names.
-    ///
-    /// Six rows in 5875; only id 3 (`DeathClouds.mdx`) is reachable from `LightParams` — the other
-    /// five are the WMO **MOSB** skyboxes, which this table does not drive (`crate::skybox`).
+    /// `LightSkybox.dbc` id → model chain path, spelled as a WMO MOSB skybox is so one model never
+    /// builds twice. Only id 3 (`DeathClouds.mdx`) is reachable from `LightParams`; the other five
+    /// rows are MOSB skyboxes.
     skyboxes: HashMap<u32, String>,
 }
 
@@ -295,10 +195,8 @@ fn light_schema() -> Schema {
     s
 }
 
-/// `LightParams.dbc` — 9 fields, 36 B/record. We only consume `glow` (field [`LP_GLOW`]); the rest are
-/// named for clarity (highlightSky flag, skybox/cloud ids, and the four water/ocean blend alphas we
-/// don't yet use). The `+0x0C` `cloudTypeID`/reserved slot is 0 in all 5875 records — the engine's glow
-/// is the *next* field (+0x10). Field types per wowdev + the byte-exact RE in `bloom-per-zone/`.
+/// `LightParams.dbc`: 9 fields, 36-byte records, types per the client's reader `0x589030`.
+/// `cloudTypeID` (+0x0C) is 0 in every 5875 record; the glow is +0x10.
 fn light_params_schema() -> Schema {
     let mut s = Schema::new("LightParams");
     for (n, t) in [
@@ -317,12 +215,8 @@ fn light_params_schema() -> Schema {
     s
 }
 
-/// The client's distance→strength ramp for an area light: `1` within `start`, falling linearly to
-/// `0` at `end` (and `0` beyond). Byte-VERIFIED (`dn_light_select 0x6d2d00`, wow-re
-/// `system/lighting/scratch/ctb.md`): `w = dist ≤ inner ? 1 : 1 − (dist−inner)/(outer−inner)`, with
-/// the containment gate `dist ≤ outer` — so a sphere entering at its outer radius enters at **w = 0**.
-/// That is what makes the area blend continuous across a sphere boundary, and it is the invariant
-/// decision 1104's water fix rests on.
+/// An area light's strength: 1 within `start`, linear to 0 at `end` (`0x6d2d00`, which admits a
+/// sphere only at `dist ≤ end`), so a sphere enters at 0 and the blend stays continuous.
 fn blend_alpha(dist: f32, start: f32, end: f32) -> f32 {
     if dist >= end {
         0.0
@@ -334,7 +228,7 @@ fn blend_alpha(dist: f32, start: f32, end: f32) -> f32 {
 }
 
 impl LightCatalog {
-    /// Read the three lighting DBCs off the patch chain.
+    /// Read the lighting DBCs off the patch chain.
     pub fn load(chain: &mut Chain) -> Result<Self> {
         let lights = {
             let bytes = chain
@@ -352,13 +246,11 @@ impl LightCatalog {
                     f32_at(r, 5),
                     f32_at(r, 6),
                 ) {
-                    // Fields 7..12 are the 5 LightParams refs (clear, clear-water, storm, …).
                     let mut params = [0u32; 5];
                     for (i, p) in params.iter_mut().enumerate() {
                         *p = u32_at(r, 7 + i).unwrap_or(0);
                     }
-                    // `(0,0,0)` is the continent-wide fallback sentinel — detect it on the raw
-                    // values (it does NOT survive the world transform).
+                    // `(0,0,0)` marks the global; test it raw, since the transform moves it.
                     let global = x == 0.0 && y == 0.0 && z == 0.0;
                     v.push(Light {
                         id,
@@ -406,12 +298,9 @@ impl LightCatalog {
                 if let Some(g) = f32_at(r, LP_GLOW) {
                     glow.insert(id, g);
                 }
-                // highlightSky is an int 0/1 flag; store 0.0/1.0 as the dawn/dusk-warp gate.
                 if let Some(h) = u32_at(r, LP_HIGHLIGHT) {
                     highlight.insert(id, if h != 0 { 1.0 } else { 0.0 });
                 }
-                // Water-blend alphas (fields 5–8). Stored only when all four parse; consumers fall back
-                // to the DEFAULT alphas otherwise. Per-zone the from-above swatch alpha ramp endpoints.
                 if let (Some(ws), Some(wd), Some(os), Some(od)) = (
                     f32_at(r, LP_WATER_SHALLOW_ALPHA),
                     f32_at(r, LP_WATER_DEEP_ALPHA),
@@ -420,8 +309,7 @@ impl LightCatalog {
                 ) {
                     water_alpha.insert(id, [ws, wd, os, od]);
                 }
-                // `lightSkyboxID`: 0 means "no skybox", which is 421 of the 426 rows — store only
-                // the live ones so a lookup miss and an explicit zero are the same answer.
+                // 0 is no skybox; storing only the others makes a miss and a 0 the same answer.
                 match u32_at(r, LP_SKYBOX) {
                     Some(0) | None => {}
                     Some(sky) => {
@@ -431,7 +319,6 @@ impl LightCatalog {
             }
             (glow, highlight, water_alpha, skybox)
         };
-        // `LightSkybox.dbc` — 6 records × 2 fields (`ID`, `Name`), the model each skybox id names.
         let skyboxes = {
             let bytes = chain
                 .read_file(LIGHT_SKYBOX)
@@ -460,15 +347,14 @@ impl LightCatalog {
         })
     }
 
-    /// Sample the atmosphere for `pos` (raw WoW yards) on `map` at `time` (half-minutes, 1440=noon).
-    /// `stormy` selects the rainy/snowy param slot over the clear one. Picks the most-local light
-    /// sphere containing `pos`, else the continent's global `(0,0,0)` light, else
-    /// [`Atmosphere::DEFAULT`].
+    /// The atmosphere at `pos` (world yards) on `map` at `time` (half-minutes, 1440 = noon): the
+    /// smallest sphere containing `pos`, else the map's global light, else record 1 on a map with
+    /// no rows, else [`Atmosphere::DEFAULT`]. `stormy` picks the storm slot.
     pub fn sample(&self, map: u32, pos: [f32; 3], time: u32, stormy: bool) -> Atmosphere {
         let Some(light) = self.pick_light(map, pos) else {
             return Atmosphere::DEFAULT;
         };
-        // Fall back to the clear slot if the requested weather slot is unset.
+        // An unset slot falls back to clear.
         let slot = if stormy { SLOT_STORM } else { SLOT_CLEAR };
         let param = match light.params[slot] {
             0 => light.params[SLOT_CLEAR],
@@ -485,9 +371,7 @@ impl LightCatalog {
         self.sample(map, pos, DAY / 2, false)
     }
 
-    /// Debug: print every `LightIntBand` row (0..18) and `LightFloatBand` row (0..6) for the clear
-    /// LightParams covering `pos`, sampled at `time`. Used to verify which rows hold which colors
-    /// (the five sky-gradient stops, sun/cloud colors, etc.) rather than guessing the layout.
+    /// Debug: print the band rows of the clear `LightParams` covering `pos`, at `time`.
     pub fn debug_bands(&self, map: u32, pos: [f32; 3], time: u32) {
         let Some(light) = self.pick_light(map, pos) else {
             println!("(no light covers this position)");
@@ -503,20 +387,14 @@ impl LightCatalog {
         self.debug_param(p, time);
     }
 
-    /// Resolve an explicitly named `LightParams` id at a time of day, with no position and no slot
-    /// selection — the machine-readable twin of [`Self::debug_param`]. The band-row id for params
-    /// `p`, sub `b` is `(p-1)*per + b + 1`, an **ID** and not a row ordinal: `LightParams` ids run
-    /// 1..499 with 73 gaps, so an ordinal keying reads another zone's bands for every group past the
-    /// first gap. Exposed so a test can pin a record above a gap.
+    /// One `LightParams` id at a time of day. Band rows key by id, not ordinal: the ids run 1..499
+    /// with 73 gaps.
     pub fn sample_params_id(&self, p: u32, time: u32) -> Option<Atmosphere> {
         (p >= 1 && self.has_param(p)).then(|| self.sample_param(p, time))
     }
 
-    /// Debug: [`Self::debug_bands`] for an explicitly named `LightParams` id, with no position and no
-    /// slot selection. The instrument for the rows **nothing in `Light.dbc` references**: magma and
-    /// slime submersion do not read a zone's underwater slot at all, they read the fixed global rows
-    /// 7 and 6 (VERIFIED `0x6d2371`, guards `maxId >= 7`/`>= 6`), which no position-keyed dump can
-    /// ever reach.
+    /// Debug: the band rows of a named `LightParams` id, such as the magma and slime rows 7 and 6
+    /// that only `0x6d2371` reads.
     pub fn debug_param(&self, p: u32, time: u32) {
         if p < 1 {
             println!("(LightParams ids are 1-based)");
@@ -552,38 +430,19 @@ impl LightCatalog {
         }
     }
 
-    /// The **ghost sky** for this position: the model `LightSkybox.dbc` names for the death
-    /// profile, or `None` when the chain's data does not name one.
-    ///
-    /// The caller gates on the `PLAYER_FLAGS` ghost bit — that bit is the *whole* condition, and it
-    /// is the reference's too. Byte-VERIFIED (wow-re `lighting/scratch/wmo-skybox.md` §3 +
-    /// `death-light.md`): the DBC skybox slot `[0xce9bb4]` is filled inside `dn_color_table_build
-    /// 0x6d2260` at `0x6d26cb`, **gated on the override cell `[0xce9bb0] != -1`**, which only
-    /// `0x6d4620` writes and only the ghost-bit selector `0x5de9c0` calls (`mov ecx,4` — param slot
-    /// [`SLOT_DEATH`]). So: ghost ⇒ this skybox; alive ⇒ none, with no other path into the table.
-    ///
-    /// **Read straight off slot 4, with no clear-slot fallback** — unlike the atmosphere's
-    /// `atmo_of`, which degrades an unset slot to [`SLOT_CLEAR`]. The reference resolves the row
-    /// with `0x6d6ab0(row, 4)` = `[row+0x2c]` and simply finds nothing if it is 0; degrading here
-    /// would instead read a slot that, in shipped data, never names a skybox at all.
-    ///
-    /// Resolved through [`pick_light`](Self::pick_light) so the sky comes from the same zone row
-    /// the water tint does. On 5875 data the choice is unobservable — all 374 `Light` rows reach
-    /// skybox **3** (`DeathClouds.mdx`) through slot 4 — but a chain that ever varied it would then
-    /// vary sky and zone together rather than drifting apart.
+    /// The ghost sky here, from slot 4 with no clear-slot fallback, as `0x6d6ab0(row, 4)` reads
+    /// `[row+0x2c]`. The ghost bit is the whole condition: the colour-table build `0x6d2260` fills
+    /// `[0xce9bb4]` at `0x6d26cb` only while `[0xce9bb0] != -1`, which only `0x6d4620` writes, for
+    /// the ghost selector `0x5de9c0` (`mov ecx,4`). The row is [`pick_light`](Self::pick_light)'s;
+    /// every shipped row's slot 4 names the same sky, `DeathClouds.mdx`.
     pub fn ghost_skybox(&self, map: u32, pos: [f32; 3]) -> Option<&str> {
         let light = self.pick_light(map, pos)?;
         let id = self.light_params_skybox.get(&light.params[SLOT_DEATH])?;
         self.skyboxes.get(id).map(String::as_str)
     }
 
-    /// Faithful **area-light blend** (step 2 isolation): replicates the real client's
-    /// `calculateLightParamBlends` + the sequential lerp in `getLightResultsFromDB`. Start from the
-    /// continent's global `(0,0,0)` light, then for every local light sphere covering `pos` (sorted by
-    /// `blendAlpha` descending) lerp the accumulated atmosphere toward that light by its `blendAlpha`
-    /// (`1` inside `falloffStart`, ramping to `0` at `falloffEnd`). Contrast with [`pick_light`], which
-    /// picks just the single most-local sphere — this tells us whether a faithful blend resolves a
-    /// **different** (e.g. redder) light at our spot than the single-sample approximation.
+    /// The reference's area-light blend: from the map's global light, lerp toward each local
+    /// sphere containing `pos` by its [`blend_alpha`], farthest first.
     pub fn sample_blended(
         &self,
         map: u32,
@@ -593,11 +452,8 @@ impl LightCatalog {
         submersion: Submersion,
         ghost: bool,
     ) -> Atmosphere {
-        // Magma/slime submersion replaces the WHOLE area blend with one fixed global row — the
-        // reference branches out at `0x6d2371`, before the slot selection, so there is no zone
-        // sphere blend and no storm lerp on this leg (see [`PARAM_MAGMA`]). Guarded on the row
-        // actually existing, matching the binary's own `maxId` guard: a chain without it falls
-        // through to the ordinary atmosphere rather than inventing one.
+        // Magma and slime replace the whole blend with one fixed row (`0x6d2371`, before the slot
+        // selection); without the row the chain falls through, as the `maxId` guard does.
         if let Some(p) = submersion.fixed_param() {
             if self.has_param(p) {
                 return self.sample_param(p, time);
@@ -605,8 +461,7 @@ impl LightCatalog {
         }
         let slot = weather_slot(ghost, stormy, submersion.is_water());
         let atmo_of = |l: &Light| -> Option<Atmosphere> {
-            // Fall back to the clear slot if the requested slot is unset for this light (e.g. a zone
-            // with no dedicated underwater param degrades to the above-water atmosphere).
+            // An unset slot falls back to clear.
             let param = match l.params[slot] {
                 0 => l.params[SLOT_CLEAR],
                 p => p,
@@ -614,17 +469,9 @@ impl LightCatalog {
             (param >= 1).then(|| self.sample_param(param, time))
         };
 
-        // Base = the continent global light (lowest priority, covers everywhere), else — when the
-        // map has **no `Light.dbc` row at all** — the client's zero-match tail fallback, record
-        // [`FALLBACK_LIGHT_ID`] (`0x6d62b2`; see its doc). Deeprun Tram (369) is the shipped map
-        // this is for: with the old invented default it rendered as a bright noon scene (fog
-        // [140,183,234] @ 1000 yd) instead of LightParams 12's own curve (fog [77,120,143] @ 500).
-        //
-        // Scoped to zero-match ON PURPOSE. Seven shipped maps (33/37/129/169/209/489/531) carry
-        // positioned rows but no `(0,0,0)` global; there the reference seeds count = 1 and fills
-        // slots 1.. with the positioned rows, leaving slot 0 unwritten — what it then blends
-        // against is NOT settled by the finding this rests on, so that case keeps the behaviour it
-        // has rather than inheriting a guess.
+        // The base: the map's global, else the zero-match record for a rowless map (`0x6d62b2`).
+        // The seven maps with rows but no global (33/37/129/169/209/489/531) start from `DEFAULT`:
+        // the reference leaves slot 0 unwritten there, and what it blends against is untraced.
         let map_has_no_light = !self.lights.iter().any(|l| l.map == map);
         let mut acc = self
             .lights
@@ -638,17 +485,8 @@ impl LightCatalog {
             .and_then(atmo_of)
             .unwrap_or(Atmosphere::DEFAULT);
 
-        // Collect every local sphere CONTAINING `pos` (`dist ≤ outer`), then apply them
-        // **farthest first** so the nearest lands last and dominates.
-        //
-        // The order is by DISTANCE, not by blend weight — byte-VERIFIED (`dn_light_select 0x6d2d00`,
-        // wow-re `ctb.md` + `merge.md`, the latter's ordering corrected by an emulator difftest
-        // oracle): the client pushes the in-radius rows into a **max-heap keyed on distance** and
-        // drains it root-first, calling `dn_record_overblend 0x6d30e0(dst, row, w)` for **every**
-        // entry including a lone one. Sorting by weight instead (what we did before decision 1104)
-        // inverts the pair whenever a wide sphere out-weighs a tight near one, and then the near
-        // zone's own palette gets *diluted* by its neighbour instead of overwriting it — the
-        // Stranglethorn river that read muddy yellow-green instead of LP 26's grey-green.
+        // Farthest first, so the nearest lands last: `0x6d2d00` drains a max-heap keyed on
+        // distance, not weight, calling `0x6d30e0(dst, row, w)` for every entry, a lone one too.
         let mut locals: Vec<(f32, &Light)> = self
             .lights
             .iter()
@@ -671,15 +509,8 @@ impl LightCatalog {
         acc
     }
 
-    /// Debug (step 2): dump every light sphere on `map` near `pos` — distance, falloff, `blendAlpha`,
-    /// and its clear-weather ambient + sun colors — then the faithful blended result vs the single
-    /// [`pick_light`] sample, so we can see whether the residual under-red lives in the **values**.
-    ///
-    /// Rows print **nearest first** but the blend applies them **farthest first** (see
-    /// [`Self::sample_blended`]) — the last row listed is the first one merged, and the top row wins.
-    /// The closing `water` lines are the river/lake and ocean swatch endpoints: a discontinuity there
-    /// across two nearby positions is the Tirisfal→Silverpine class of bug (decision 1104), and it is
-    /// invisible in the ambient/sun columns because the water rows are their own bands.
+    /// Debug: the spheres near `pos`, nearest first (the blend applies them farthest first), then
+    /// the blended result against the `pick_light` sample and the water swatch endpoints.
     pub fn debug_blend(&self, map: u32, pos: [f32; 3], time: u32) {
         let mut rows: Vec<(f32, f32, &Light)> = self
             .lights
@@ -747,8 +578,6 @@ impl LightCatalog {
             c(blended.ambient),
             c(blended.sun_diffuse)
         );
-        // The water swatch is what the liquid materials actually read (`WowLighting.water_*`), and it
-        // rides this same blend — print it so "the water popped here" is one command, not a session.
         println!(
             "  => water river: shallow {} a={:.2}  deep {} a={:.2}",
             c(blended.water_river[0]),
@@ -765,15 +594,7 @@ impl LightCatalog {
         );
     }
 
-    /// Debug: the **per-weather-slot** resolve at `pos` — for each of the five `Light.dbc` param
-    /// slots (clear / clear-underwater / storm / storm-underwater / death), which `LightParams` id
-    /// the picked sphere and the continent global each name, whether the slot is UNSET (and so falls
-    /// back to clear), and the fog/ambient/diffuse the blend actually resolves.
-    ///
-    /// The companion to [`Self::debug_bands`], which only ever dumps the clear slot: an underwater or
-    /// ghost atmosphere that reads wrong is either a slot the data leaves unset (→ we correctly show
-    /// the surface atmosphere) or a slot whose values we mis-consume, and those two look identical
-    /// from inside the game. This tells them apart in one command.
+    /// Debug: per slot, the `LightParams` ids the picked sphere and the global name, and the blend.
     pub fn debug_slots(&self, map: u32, pos: [f32; 3], time: u32) {
         const NAMES: [&str; 5] = [
             "clear",
@@ -814,8 +635,6 @@ impl LightCatalog {
             "slot", "picked", "global", "fog_end", "frac", "fog_color", "ambient", "diffuse"
         );
         for (slot, name) in NAMES.iter().enumerate() {
-            // The same UNSET→clear fallback both sample paths apply, reported per source so an
-            // "unset everywhere" slot is visibly distinct from one carrying real values.
             let show = |l: Option<&Light>| match l.map(|l| l.params[slot]) {
                 None => "     -".to_string(),
                 Some(0) => " unset".to_string(),
@@ -863,11 +682,8 @@ impl LightCatalog {
                 local = Some(l);
             }
         }
-        // Same zero-match tail as `sample_blended` (see [`FALLBACK_LIGHT_ID`]): a map with no row
-        // of its own resolves record 1. Kept in step deliberately — this is the single-sphere
-        // approximation the water tint reads, and a rowless map that answered one thing to the
-        // area blend and another here would tint its water off a different atmosphere than it fogs
-        // with (decision 0706's split, in miniature).
+        // The same zero-match tail as `sample_blended` ([`FALLBACK_LIGHT_ID`]), so a map with no
+        // rows resolves the same record on both paths.
         local.or(global).or_else(|| {
             (!any)
                 .then(|| self.lights.iter().find(|l| l.id == FALLBACK_LIGHT_ID))
@@ -875,8 +691,8 @@ impl LightCatalog {
         })
     }
 
-    /// Whether `LightParams` `p` actually has band rows in this chain — the client's `maxId` guard on
-    /// the fixed magma/slime rows. Checks the fog-colour row, which every real record carries.
+    /// Whether `LightParams` `p` has band rows in this chain, the client's `maxId` guard on the
+    /// fixed magma and slime rows; checks the fog-colour row, which every real record carries.
     fn has_param(&self, p: u32) -> bool {
         p >= 1
             && self
@@ -887,23 +703,12 @@ impl LightCatalog {
     fn sample_param(&self, p: u32, t: u32) -> Atmosphere {
         let ib = |b: u32| self.int_bands.get(&((p - 1) * 18 + b + 1));
         let fb = |b: u32| self.float_bands.get(&((p - 1) * 6 + b + 1));
-        // `d` survives only for the four `LightParams` **record fields** below (glow, highlightSky,
-        // the water alphas). Those are not band rows: their "missing" case is a record that failed
-        // to parse, not a keyless row, so they keep the record-level fallback. Every BAND row on
-        // this record takes the reference's zero-key constant instead.
+        // `d` serves only the record fields; a keyless band row takes the zero-key constant.
         let d = Atmosphere::DEFAULT;
-        // Fog distances carry the ×36 storage scale (yards = raw/36): Elwynn clear 18000→500 yd,
-        // storm 10000→278 yd. Byte-VERIFIED (0327, wow-re rf-weather-fog-veil Q2·LOAD): the client
-        // scales ONCE at DBC load — `0x53f504 → 0x6d6160 → 0x6d6100` runs `dn_array_scale_36`
-        // (`0x6d6090`, ×1/36 @0x7ff9d0) over each float-band record with `rowIndex % 6 == 0`, i.e.
-        // ONLY the sub-0 fog-END band; the sub-1 start FRACTION is never scaled. We apply the same
-        // /36 at sample time (a time-interp of scaled values ≡ the scale of the interp).
-        // A row with no keyframes commits the reference's own constant, never an invented one
-        // (`ZERO_KEY_SCALAR`/`ZERO_KEY_COLOR`, decision 1465). The `.filter(|v| v > 1.0)` that used
-        // to sit here substituted `d.fog_end` for an authored ZERO as well as for a keyless row —
-        // it is gone, and no shipped row lands in the (0, 1] yd window it also covered (checked
-        // across all 426 params: the only sub-1 values are the exact 0.0 that params 9 and 93
-        // author). `min(end − start, 0.001)` in the fog shaders is what keeps end = 0 finite.
+        // Only the fog end is stored × 36. The reference scales it once at load (`0x53f504` →
+        // `0x6d6160` → `0x6d6100` runs `0x6d6090`, × 1/36 at `0x7ff9d0`, on rows with
+        // `rowIndex % 6 == 0`); scaling the interpolated value here is the same. A 0 end (params 9
+        // and 93) stays 0, kept finite by the shaders' `max(end − start, 0.001)`.
         let fog_end = fb(FB_FOG_END)
             .and_then(|b| sample_float(b, t))
             .map(|v| v / POS_SCALE)
@@ -918,31 +723,17 @@ impl LightCatalog {
         };
         Atmosphere {
             fog_end,
-            // UNCLAMPED, negative under storm (Elwynn −0.5) — the negative start IS the constant
-            // near veil the reference shows in rain; clamping it to 0 was the veil-killing bug.
+            // Unclamped: negative under storm (Elwynn −0.5), the reference's near veil in rain.
             fog_start_frac,
             fog_color: col(IB_FOG_COLOR),
             sun_diffuse: col(IB_DIFFUSE),
             sun_color: col(IB_SUN_COLOR),
             ambient: col(IB_AMBIENT),
             sky: std::array::from_fn(|i| col(IB_SKY0 + i as u32)),
-            // Dedicated water-tint rows (RAW, no scale): 16/17 river/lake, 14/15 ocean — the 2-endpoint
-            // depth-swatch lerp (`FUN_0068a830`). These are real per-zone rows, NOT the sky gradient.
-            //
-            // ⚠ The zero-key arm is WIDEST here and least self-corroborating. 125/149/59/59 of the
-            // 426 params leave ocean-shallow/ocean-deep/river-shallow/river-deep unkeyed, and 53
-            // CLEAR-slot spheres on maps 0/1 are among them — so this is where black actually
-            // reaches player water. Unlike the cloud base (209 of 308 keyed rows are exactly
-            // `(0,0,0)`, not one is pale — black is that lane's modal authored value), only 3-10 of
-            // ~300 keyed water rows are black: a keyless water row answering black is out of family
-            // for the authored data. Both halves are byte-verified — the slot is black (1465) and
-            // the swatch builder reads the slot (0686) — so this is what the reference computes;
-            // what it LOOKS like in one of those 53 zones is the director's to judge, and this note
-            // is the pointer back if it reads wrong.
+            // Water-tint rows, the swatch endpoints (`0x68a830`). An unkeyed row is black, as in
+            // the reference; 53 clear-slot spheres on maps 0 and 1 leave one unkeyed.
             water_river: [col(IB_RIVER_SHALLOW), col(IB_RIVER_DEEP)],
             water_ocean: [col(IB_OCEAN_SHALLOW), col(IB_OCEAN_DEEP)],
-            // Per-zone water-blend alphas (static LightParams fields 5–8); fall back to the DEFAULT
-            // ramp endpoints when the record didn't carry them.
             water_river_alpha: self
                 .light_params_water_alpha
                 .get(&p)
@@ -953,15 +744,12 @@ impl LightCatalog {
                 .get(&p)
                 .map(|a| [a[2], a[3]])
                 .unwrap_or(d.water_ocean_alpha),
-            // Per-zone glow (static LightParams field, not a time band); fallback 0.5.
             glow: self.light_params_glow.get(&p).copied().unwrap_or(d.glow),
-            // Cloud density C (float sub-3) + the three cloud palette rows (int sub-10/11/12) —
-            // the coverage threshold and the visible dome's colors (wow-re cloud pipeline §3c/§4).
+            // Cloud density and the three cloud palette rows, gathered by `0x6d64d0`.
             cloud_density: fb(FB_CLOUD_DENSITY)
                 .and_then(|b| sample_float(b, t))
                 .unwrap_or(ZERO_KEY_SCALAR),
             cloud_colors: [col(IB_CLOUD_SUN), col(IB_CLOUD_SLOPE), col(IB_CLOUD_GBASE)],
-            // Per-zone highlightSky flag (static); gates the dawn/dusk dome warp. Fallback 0.0.
             highlight_sky: self
                 .light_params_highlight
                 .get(&p)
@@ -975,10 +763,6 @@ impl LightCatalog {
 mod ocean_tests {
     use super::*;
 
-    /// The ramp's shape: both factors are 1.0 at the surface, bottom out at 30 yards, and hold flat
-    /// below. `fac1` (the first light triple) halves; `fac2` (the second) only drops to 0.75 — the
-    /// fill darkens twice as fast as the direct term, which is what makes a deep sea read flat as
-    /// well as dim.
     #[test]
     fn the_ocean_ramp_runs_over_thirty_yards_and_then_holds() {
         let f = |z: f32| Submersion::Ocean.ocean_depth_factors(z).unwrap();
@@ -988,25 +772,16 @@ mod ocean_tests {
             (1.0, 1.0),
             "at the surface the ramp is the identity"
         );
-        // Above the surface clamps to the identity too — the ramp never brightens.
+        // Above the surface it clamps to the identity: the ramp never brightens.
         assert_eq!(f(12.0), (1.0, 1.0));
         let (a30, b30) = f(-30.0);
         assert!((a30 - 0.5).abs() < 1e-6 && (b30 - 0.75).abs() < 1e-6);
         assert_eq!(f(-100.0), (a30, b30), "below 30 yd it holds flat");
-        // Linear, and fac1 falls exactly twice as fast as fac2.
         let (a15, b15) = f(-15.0);
         assert!((a15 - 0.75).abs() < 1e-6 && (b15 - 0.875).abs() < 1e-6);
         assert!(((1.0 - a15) - 2.0 * (1.0 - b15)).abs() < 1e-6);
     }
 
-    /// GOLDEN — the binary's own constant, and the reason it has to be a MULTIPLY.
-    ///
-    /// wow-re's note warns that `−0.0333333351f` "is not exactly −1/30" and that a bit-exact port
-    /// must use the stored f32 rather than `t/30.0`. The warning is worth heeding and its stated
-    /// reason is not the real one: that bit pattern IS the nearest f32 to −1/30. The hazard is the
-    /// operation, not the operand — `t · recip` and `t / 30.0` round differently, and they disagree
-    /// *inside* the ramp's range, so a port that "simplifies" the multiply into a divide drifts.
-    /// This test pins both halves so neither can be tidied away.
     #[test]
     fn the_ramp_multiplies_by_the_binarys_own_reciprocal() {
         assert_eq!(OCEAN_RAMP_RECIP.to_bits(), 0xbd088889);
@@ -1015,22 +790,19 @@ mod ocean_tests {
             -1.0f32 / 30.0,
             "the constant itself is just the nearest f32 to -1/30"
         );
-        // …and yet the two forms are not interchangeable. -29 yd is a witness inside the range.
+        // −29 yd is a depth where the two forms differ.
         let t = -29.0f32;
         assert_ne!(
             1.0 - t * OCEAN_RAMP_RECIP,
             1.0 + t / 30.0,
             "multiply and divide must be observably different, or the warning is empty"
         );
-        // The boundaries land exactly, with no f32 residue to explain away.
         assert_eq!(
             Submersion::Ocean.ocean_depth_factors(-30.0).unwrap(),
             (0.5, 0.75)
         );
     }
 
-    /// The ramp is OCEAN'S ALONE — the gate is the full unmasked dword `== 1` (`0x6d2821`), and
-    /// every other state, still water included, is untouched at any depth.
     #[test]
     fn only_ocean_ramps() {
         for s in [
@@ -1046,9 +818,6 @@ mod ocean_tests {
         }
     }
 
-    /// The split exists for the ramp and nothing else: everywhere a *water kind* is the question,
-    /// ocean answers with water — the underwater LightParams slot, the ambience bed, the reverb
-    /// column. And neither takes a fixed global row, which is what magma and slime do.
     #[test]
     fn ocean_is_a_water_kind_everywhere_but_the_ramp() {
         assert!(Submersion::Ocean.is_water() && Submersion::Water.is_water());
@@ -1069,12 +838,10 @@ mod tests {
 
     #[test]
     fn dbc_to_world_matches_wiki_convertdbtogamecoords() {
-        // The `(0,0,0)` global sentinel maps to the map center (we special-case it before this).
+        // The `(0,0,0)` global sentinel maps to the map centre (the loader special-cases it).
         assert_eq!(dbc_to_world(0.0, 0.0, 0.0), [17066.666, 17066.666, 0.0]);
 
-        // Round-trip a known world point through the wiki inverse
-        // (DBC.x = (17066.666 − world.y)·36, DBC.y = world.z·36, DBC.z = (17066.666 − world.x)·36):
-        // applying `dbc_to_world` must recover the world coords. Light #51 → (-8480, 548, 81).
+        // Light #51 at (-8480, 548, 81), through the inverse transform and back.
         let world = [-8480.4f32, 548.3, 80.9];
         let dbc = [
             (17066.666 - world[1]) * POS_SCALE,
@@ -1094,9 +861,9 @@ mod tests {
 
     #[test]
     fn glow_defaults_blends_and_quantises() {
-        // Fallback = the binary's "no active world-light" 0.5.
+        // The binary's "no active world light" glow.
         assert_eq!(Atmosphere::DEFAULT.glow, 0.5);
-        // Glow blends across light spheres like the colours (Duskwood 0.50 ↔ a 0.85 area).
+        // Duskwood's 0.50 against a 0.85 area.
         let a = Atmosphere {
             glow: 0.50,
             ..Atmosphere::DEFAULT
@@ -1106,8 +873,7 @@ mod tests {
             ..Atmosphere::DEFAULT
         };
         assert!((a.lerp(&b, 0.5).glow - 0.675).abs() < 1e-6);
-        // The renderer quantises floor(glow·255)/255 — Elwynn's 0.65 → 165/255 = 0.647 (the
-        // apitrace composite weight), confirming LP_GLOW (field 4) is the right field.
+        // floor(glow·255)/255: Elwynn's 0.65 gives the reference's 165/255 composite weight.
         let q = |g: f32| (g * 255.0).floor() / 255.0;
         assert!((q(0.65) - 165.0 / 255.0).abs() < 1e-6);
         assert!((q(0.50) - 127.0 / 255.0).abs() < 1e-6); // Duskwood → 0.498
diff --git a/crates/benilla-formats/src/light/atmosphere.rs b/crates/benilla-formats/src/light/atmosphere.rs
index d823e28a..6587437a 100644
--- a/crates/benilla-formats/src/light/atmosphere.rs
+++ b/crates/benilla-formats/src/light/atmosphere.rs
@@ -1,174 +1,100 @@
-//! The resolved lighting **output type** ([`Atmosphere`]) + the DBC row/field → meaning map.
-//!
-//! `LightIntBand`/`LightFloatBand` rows and `LightParams` fields are just numbered slots; the
-//! constants here name which slot is which (the **vanilla** layout, VERIFIED — see the `light`
-//! module header). [`super::LightCatalog::sample`] reads these rows/fields into an [`Atmosphere`].
+//! The resolved lighting type, [`Atmosphere`], and the names of the `LightIntBand` and
+//! `LightFloatBand` rows and `LightParams` fields it is read from, in the vanilla layout.
 
-/// LightIntBand row indices (0-based within a param's 18 rows).
+/// `LightIntBand` row indices, 0-based within a param's 18 rows.
 pub(super) const IB_DIFFUSE: u32 = 0;
 pub(super) const IB_AMBIENT: u32 = 1;
-/// The five sky-gradient stops are rows 2..6: SkyColor0 (zenith) → SkyColor4 (horizon).
+/// The five sky-gradient stops, rows 2..6, zenith to horizon.
 pub(super) const IB_SKY0: u32 = 2;
 pub(super) const IB_FOG_COLOR: u32 = 7;
 pub(super) const IB_SUN_COLOR: u32 = 9;
-/// **Cloud layer palette rows** — byte-VERIFIED (wow-re `scratch/cloud-coverage-pipeline.md` §3c:
-/// the band gather `0x6d64d0` stores sub-10/11/12 at color-table slots 9/10/11 = `0xce9c30/34/38`,
-/// the three palettes the cloud dome builder `0x6cfb00` reads): sun-glow tint, gradient slope,
-/// gradient base.
+/// The cloud palette rows, sun-glow tint, gradient slope and gradient base: gathered by `0x6d64d0`
+/// into `0xce9c30/34/38` for the cloud dome builder `0x6cfb00`.
 pub(super) const IB_CLOUD_SUN: u32 = 10;
 pub(super) const IB_CLOUD_SLOPE: u32 = 11;
 pub(super) const IB_CLOUD_GBASE: u32 = 12;
-/// **Dedicated water-surface tint rows.** The from-above depth swatch is a plain 2-endpoint linear
-/// lerp of these IntBand colours, RAW (no scale), VERIFIED from WoW.exe `FUN_0068a830` (the body-colour
-/// swatch builder reads `gWorldLight+0xe0..+0xec` = these rows; golden-vector-matched to the apitrace
-/// swatch ≤1/255 over all 64 rows). Ocean = rows 14/15 (shallow/deep), river/lake = rows 16/17.
-/// NOT the sky gradient — the earlier "reflected sky × 0.711 via `FUN_0068c250`" conclusion fingered
-/// the WRONG builder (that fills a *separate* symmetric grey edge texture not bound on the water unit).
+/// The water-surface tint rows, ocean 14/15 and river/lake 16/17 (shallow, deep): the reference's
+/// swatch builder `FUN_0068a830` lerps them raw (`gWorldLight+0xe0..+0xec`), not the sky gradient.
 pub(super) const IB_OCEAN_SHALLOW: u32 = 14;
 pub(super) const IB_OCEAN_DEEP: u32 = 15;
 pub(super) const IB_RIVER_SHALLOW: u32 = 16;
 pub(super) const IB_RIVER_DEEP: u32 = 17;
-/// LightFloatBand row indices (within a param's 6 rows).
+/// `LightFloatBand` row indices, within a param's 6 rows.
 pub(super) const FB_FOG_END: u32 = 0;
 pub(super) const FB_FOG_START_MULT: u32 = 1;
-/// **Cloud density `C`** — byte-VERIFIED (wow-re `scratch/cloud-coverage-pipeline.md` §4: the
-/// scalar gather `0x6d64d0` stores float sub-3 at `0xce9c0c+0x58` = `[0xce9c64]`, the coverage
-/// threshold input `T = trunc((1−C)·255)`). Zeroed only in the degenerate no-light-record
-/// fallback — hence the 0.0 default.
+/// Cloud density `C`, gathered by `0x6d64d0` into `[0xce9c64]`: the coverage threshold is
+/// `T = trunc((1 − C)·255)`.
 pub(super) const FB_CLOUD_DENSITY: u32 = 3;
 
-/// LightParams.dbc field index of the **glow** scalar (the FFXGlow/bloom composite weight). VERIFIED
-/// from `WoW.exe` RE: the engine reads glow from record byte
-/// **+0x10 = field index 4**, NOT the wiki's labelled +0x0C `m_glow` (which is 0.0 in all 426 vanilla
-/// records). Byte-exact cross-check: LightParams 12 (EK default) field 4 = 0.65 → `floor(0.65·255)/255 =
-/// 0.647`, matching the apitrace composite weight. Per-zone (13 distinct values, 0.0–1.0 across zones).
+/// `LightParams.dbc` field of the glow, the bloom composite weight: the reference reads record byte
+/// `+0x10`, field 4, not the `+0x0C` the wiki labels `m_glow`, which is 0 in every vanilla row.
 pub(super) const LP_GLOW: usize = 4;
 
-/// `LightParams.dbc` field index of the **highlightSky** flag (record byte +0x04 = field index 1).
-/// VERIFIED from `WoW.exe` RE: the sky-dome
-/// colour fold `FUN_006d0f50` reads it as `params[0x14] = (float)*(int*)(LightSrc+4)` — an int 0/1
-/// flag that **gates the dawn/dusk sky-dome azimuthal warp** (Elwynn/Westfall = 1, Duskwood = 0).
-/// Stored as 0.0/1.0.
+/// `LightParams.dbc` field of the highlightSky flag, record byte `+0x04`: an int 0/1 the sky-dome
+/// fold `FUN_006d0f50` reads to gate the dawn/dusk azimuthal warp. Stored as 0.0/1.0.
 pub(super) const LP_HIGHLIGHT: usize = 1;
 
-/// `LightParams.dbc` field index of **lightSkyboxID** (record byte +0x08 = field index 2) — the
-/// `LightSkybox.dbc` row whose model replaces the whole celestial pass while it is active.
-///
-/// **In 5875 this field is the ghost sky and nothing else.** Byte-VERIFIED (wow-re
-/// `lighting/scratch/wmo-skybox.md` §3): the DBC skybox slot `[0xce9bb4]` is filled inside
-/// `dn_color_table_build 0x6d2260` at `0x6d26cb` **gated on `[0xce9bb0] != -1`** — the ghost
-/// override cell, written only by `0x6d4620` off the `PLAYER_FLAGS` ghost bit (`death-light.md`).
-/// The shipped data agrees exactly: of 426 `LightParams` rows only **5** carry a non-zero id, all
-/// of them **3 = `DeathClouds.mdx`**, and all 374 `Light.dbc` rows reach one through param slot
-/// **4** alone (slots 0–3 are uniformly 0). So there is no live non-ghost skybox to miss here.
+/// `LightParams.dbc` field of lightSkyboxID, record byte `+0x08`: the `LightSkybox.dbc` model that
+/// replaces the celestial pass. The reference fills `[0xce9bb4]` (`0x6d2260` at `0x6d26cb`) only
+/// while `0x6d4620` has set the ghost override `[0xce9bb0]`; the 5 non-zero rows are all
+/// `DeathClouds.mdx`.
 pub(super) const LP_SKYBOX: usize = 2;
 
-/// `LightParams.dbc` field indices of the **water-blend alphas** — the from-above swatch's depth-alpha
-/// ramp endpoints (`swatch.a = lerp(shallow, deep, V)`; the runtime reads these into `gWorldLight+0x114..`
-/// via `FUN_006b6b60`). Layout follows the glow shift: glow is field 4 (+0x10), so these are fields 5–8
-/// (+0x14..+0x20). Cross-check: LP 26 (Stranglethorn) `waterShallow` ≈ 0.85 matches the WoW.21 apitrace
-/// swatch alpha 216/255, and the area blend resolves LP 26 whole at that river (test
-/// `light_area_blend_order.rs`). If a future file disagrees, re-check the offset (cf. the glow
-/// +0x0C-vs-+0x10 trap).
+/// `LightParams.dbc` fields 5 to 8, after the glow: the water-blend alphas, the depth-alpha
+/// endpoints of the swatch (`swatch.a = lerp(shallow, deep, V)`, read by `FUN_006b6b60`).
 pub(super) const LP_WATER_SHALLOW_ALPHA: usize = 5;
 pub(super) const LP_WATER_DEEP_ALPHA: usize = 6;
 pub(super) const LP_OCEAN_SHALLOW_ALPHA: usize = 7;
 pub(super) const LP_OCEAN_DEEP_ALPHA: usize = 8;
 
-/// The reference's answer for a band row that exists but carries **no keyframes**
-/// (`numKeys == 0`) — the case 973 of the 7668 shipped `LightIntBand` rows and 132 of the 2556
-/// `LightFloatBand` rows are in, and the one this crate used to answer with an invented
-/// "neutral daytime" constant.
-///
-/// Byte-VERIFIED (decision 1465, wow-re `system/lighting/scratch/band-zero-key-contract.md`):
-/// the colour evaluator `0x6d62e0` early-outs *before* touching the key/value arrays — key-count
-/// load `0x6d62ec`, guard `0x6d62ef`/`0x6d62f4`, store `0x6d62f6 mov [edi], 0xff000000` — an
-/// immediate, so the slot is opaque **black**: not zero-alpha, not stale, not skipped, and the
-/// driver's copy into the colour table (`0x6d6643`/`0x6d664c` for sub-12) is unconditional.
-/// The scalar evaluator does the same at `0x6d6489`/`0x6d648e` with `fld [0x7ffd74]` = `+0.0f`.
-/// We keep only the RGB; the forced 0xff alpha has no consumer on this side.
-///
-/// This is NOT [`Atmosphere::DEFAULT`]'s job. That constant answers "there is no light record at
-/// all", which decision 0987 showed is unreachable in world (a rowless map takes `Light.dbc`
-/// record 1); the reference's own whole-record default is the pre-first-map-load white table at
-/// `0x6d22ce`. Using a *daytime palette* to fill a *single missing row* was the actual defect
-/// behind report B90: `LightParams` 36 (Blasted Lands) leaves the cloud gradient base
-/// (`IB_CLOUD_GBASE`) unkeyed, so the sky took a pale grey where the data says black — under a
-/// zone that authors cloud density 0.85, that is the whole sky.
+/// A band row with no keyframes (973 of the 7668 `LightIntBand` rows) commits opaque black: the
+/// reference's colour evaluator `0x6d62e0` stores the immediate `0xff000000` at `0x6d62f6` before
+/// reading any key, and the copy into the colour table (`0x6d6643`) is unconditional.
 pub const ZERO_KEY_COLOR: [f32; 3] = [0.0, 0.0, 0.0];
 
-/// The scalar half of [`ZERO_KEY_COLOR`] — a keyless `LightFloatBand` row commits `+0.0f`.
+/// A keyless `LightFloatBand` row commits `+0.0f` (`0x6d6489`, `fld [0x7ffd74]`).
 pub const ZERO_KEY_SCALAR: f32 = 0.0;
 
-/// Sampled atmosphere for a position + time of day. Distances are yards; colors are sRGB 0..1
-/// (feed straight into Bevy `Color::srgb`).
+/// The sampled atmosphere at a position and time of day: distances in yards, colours sRGB 0..1.
 #[derive(Clone, Copy, Debug)]
 pub struct Atmosphere {
-    /// Fog-end band value (FloatBand sub0) in **yards** (`raw/36` — Elwynn clear 18000→500, storm
-    /// 10000→278). Byte-VERIFIED (0327): the client applies the ×1/36 ONCE at DBC load
-    /// (`dn_array_scale_36 0x6d6090`, selector `rowIndex % 6 == 0` — the sub-0 distance band only).
-    /// The consumer pushes `min(fog_end, farclip)` (`dn_scene_fog 0x6cee30`), so the wall tracks
-    /// the view-distance slider only below the zone's value. Lerped verbatim across weather/area
-    /// blends, like the binary's `0x6d69d8`.
+    /// Fog end in yards, FloatBand sub 0 divided by 36 once at load (`0x6d6090`). The consumer
+    /// pushes `min(fog_end, farclip)` (`0x6cee30`); blends lerp it raw (`0x6d69d8`).
     pub fog_end: f32,
-    /// Fog-start **fraction** of the pushed fog end (FloatBand sub1), **raw and unclamped** — storm
-    /// params go negative (Elwynn storm −0.5), which is the mechanism behind the constant near veil:
-    /// `GL_FOG_START = frac × GL_FOG_END` with no clamp (`0x6cee6d`), so a negative start puts
-    /// `1 − 1/(1−frac)` fog at the eye. Lerped verbatim, like the binary's `0x6d69ed`.
+    /// Fog start as a fraction of the pushed end, FloatBand sub 1, unclamped (`0x6cee6d`), so a
+    /// storm's negative value puts fog at the eye; lerped raw (`0x6d69ed`).
     pub fog_start_frac: f32,
     pub fog_color: [f32; 3],
-    /// Global diffuse (the sun's warm direct tint; orange in daylight).
+    /// Global diffuse, the sun's direct tint.
     pub sun_diffuse: [f32; 3],
-    /// Sun disc / halo color (the cleaner near-white we drive the directional light with).
+    /// IntBand row 9: the sun disc and halo tint, also the specular colour.
     pub sun_color: [f32; 3],
     pub ambient: [f32; 3],
-    /// The five sky-dome gradient stops, zenith → horizon (`SkyColor0..4`): navy zenith, the strong
-    /// midday blue, light blue, pale cyan, pale horizon. All five matter — using only every other one
-    /// drops the saturated blue and washes the sky out.
+    /// The five sky-dome gradient stops, zenith to horizon (`SkyColor0..4`); all five are used.
     pub sky: [[f32; 3]; 5],
-    /// **River/lake water-surface tint** `[shallow, deep]` — IntBand rows 16/17, RAW. The from-above
-    /// depth swatch is a 2-endpoint linear lerp of these by the per-vertex depth `V` (built in
-    /// `benilla-formats::liquid` — river/lake `V = clamp(byte/42)`) (VERIFIED `WoW.exe FUN_0068a830`; see
-    /// [`IB_RIVER_SHALLOW`]). No `× 0.711` — these are the raw water rows.
+    /// River/lake tint `[shallow, deep]`, IntBand rows 16/17 raw, lerped by depth (`FUN_0068a830`).
     pub water_river: [[f32; 3]; 2],
-    /// **Ocean water-surface tint** `[shallow, deep]` — IntBand rows 14/15, RAW (same builder as
-    /// [`Atmosphere::water_river`], `param_6 = 0`). Ocean uses a gentler depth-byte ramp than rivers
-    /// (≈1.7 vs ≈8.5 byte/yd — the data's own slope), so its deep colour appears far from shore.
+    /// Ocean tint `[shallow, deep]`, IntBand rows 14/15 raw, from the same builder.
     pub water_ocean: [[f32; 3]; 2],
-    /// **River/lake water-blend alphas** `[shallow, deep]` — `LightParams.waterShallowAlpha`/
-    /// `waterDeepAlpha` (fields [`LP_WATER_SHALLOW_ALPHA`]/[`LP_WATER_DEEP_ALPHA`]). The depth swatch's
-    /// alpha ramp endpoints (`swatch.a = lerp(shallow, deep, V)`). Per-zone: Elwynn/Loch Modan shallow
-    /// ≈0.5, STV ≈0.85 (its shallows read pale from the colour, not transparency). Deep ≈1.0 everywhere.
+    /// River/lake blend alphas `[shallow, deep]`, `LightParams.waterShallowAlpha`/`waterDeepAlpha`.
     pub water_river_alpha: [f32; 2],
-    /// **Ocean water-blend alphas** `[shallow, deep]` — `LightParams.oceanShallowAlpha`/`oceanDeepAlpha`
-    /// (fields [`LP_OCEAN_SHALLOW_ALPHA`]/[`LP_OCEAN_DEEP_ALPHA`]). Shallow ≈0.75, deep ≈1.0.
+    /// Ocean blend alphas `[shallow, deep]`, `LightParams.oceanShallowAlpha`/`oceanDeepAlpha`.
     pub water_ocean_alpha: [f32; 2],
-    /// **FFXGlow / bloom composite weight** for this zone — `LightParams.glow` (field [`LP_GLOW`]),
-    /// raw `0.0..1.0`. The composite is `scene + glow·bloom²`; the real client quantises it to a byte
-    /// (`floor(glow·255)/255`) when it packs the composite-quad colour. Per-zone (Elwynn 0.65, Duskwood
-    /// 0.50, …); fallback 0.5.
+    /// The FFXGlow composite weight, `LightParams.glow`, raw 0..1: the composite is
+    /// `scene + glow·bloom²`, and the reference quantises glow to `floor(glow·255)/255`.
     pub glow: f32,
-    /// **highlightSky** flag for this zone (`LightParams.highlightSky`, field [`LP_HIGHLIGHT`]), as
-    /// 0.0/1.0. Gates the dawn/dusk sky-dome azimuthal warp (`FUN_006d0f50`): the warp strength is
-    /// `dawn_dusk_curve(dayfrac) × highlight_sky`, so highlightSky=0 zones (e.g. Duskwood) get no
-    /// warp at all. Per-zone, static (a LightParams record field, not a time band); fallback 0.0.
+    /// `LightParams.highlightSky` as 0.0/1.0, scaling the dawn/dusk dome warp (`FUN_006d0f50`).
     pub highlight_sky: f32,
-    /// **Cloud density `C`** (FloatBand sub-3, [`FB_CLOUD_DENSITY`]) — the coverage threshold
-    /// input `T = trunc((1−C)·255)`: 0 = a cloudless sky (the field quantizes to zero
-    /// everywhere), 1 = full overcast potential. Per-zone, per-time, and lerped across the
-    /// weather/area blends like every band.
+    /// Cloud density `C`, FloatBand sub 3: the coverage threshold is `T = trunc((1 − C)·255)`.
     pub cloud_density: f32,
-    /// **Cloud palette** `[sun-glow, slope, gbase]` (IntBand sub-10/11/12) — the visible cloud
-    /// dome's colors: per-texel `RGB = slope·p + gbase` plus a sun-aligned glow tinted by the
-    /// sun row (wow-re `cloud-coverage-pipeline.md` §3b/§3c).
+    /// Cloud palette `[sun-glow, slope, gbase]`, IntBand sub 10/11/12: per texel
+    /// `RGB = slope·p + gbase` plus the sun-aligned glow (`0x6cfb00`).
     pub cloud_colors: [[f32; 3]; 3],
 }
 
 impl Atmosphere {
-    /// Neutral daytime fallback for **no lighting data at all** — a chain with no `Light.dbc`, or a
-    /// catalog that failed to load. It is not reachable from a shipped install: every map resolves a
-    /// record (0987) and every record's 24 band rows exist, so a *row* with no keys takes
-    /// [`ZERO_KEY_COLOR`]/[`ZERO_KEY_SCALAR`] instead — this constant is never spliced into one.
+    /// A daytime fallback for no lighting data, unreachable from a shipped install (a keyless row
+    /// takes [`ZERO_KEY_COLOR`]); the reference's pre-load table is white (`0x6d22ce`).
     pub const DEFAULT: Atmosphere = Atmosphere {
         fog_end: 1000.0,
         fog_start_frac: 0.4,
@@ -183,20 +109,18 @@ impl Atmosphere {
             [0.68, 0.80, 0.93],
             [0.78, 0.86, 0.95],
         ],
-        // Daytime fallback water tints (used only when the DBC rows are absent): green shore → teal
-        // deep (river/lake), teal → deep-blue (ocean). Real values come from IntBand rows 16/17 / 14/15.
         water_river: [[0.27, 0.33, 0.14], [0.19, 0.31, 0.32]],
         water_ocean: [[0.10, 0.29, 0.34], [0.04, 0.16, 0.28]],
         water_river_alpha: [0.5, 1.0],
         water_ocean_alpha: [0.75, 1.0],
         glow: 0.5,          // the binary's "no active world-light" fallback
         highlight_sky: 0.0, // no dawn/dusk dome warp unless a zone sets the flag
-        // The degenerate no-light-record fallback force-zeroes C (`0x6d22ec`) — no clouds.
+        // The reference's no-light-record fallback zeroes `C` (`0x6d22ec`).
         cloud_density: 0.0,
         cloud_colors: [[1.0, 0.98, 0.9], [0.35, 0.38, 0.42], [0.75, 0.78, 0.82]],
     };
 
-    /// Linearly blend two atmospheres (`t=0`→`self`, `t=1`→`other`) — for smooth weather/time fades.
+    /// Linear blend: `t = 0` is `self`, `t = 1` is `other`.
     pub fn lerp(&self, other: &Atmosphere, t: f32) -> Atmosphere {
         let f = |a: f32, b: f32| a + (b - a) * t;
         let c = |a: [f32; 3], b: [f32; 3]| [f(a[0], b[0]), f(a[1], b[1]), f(a[2], b[2])];
diff --git a/crates/benilla-formats/src/light/tables.rs b/crates/benilla-formats/src/light/tables.rs
index 34bf9c7f..d1eecdab 100644
--- a/crates/benilla-formats/src/light/tables.rs
+++ b/crates/benilla-formats/src/light/tables.rs
@@ -1,7 +1,5 @@
-//! Low-level `LightIntBand`/`LightFloatBand` table decode + time-of-day interpolation. A [`Band`] is
-//! one row's parallel `(time, value)` pairs across the day; [`sample_color`]/[`sample_float`] lerp it
-//! at a given time (wrapping across midnight). The meaning of each row is in [`super::atmosphere`];
-//! this module is purely "parse the band tables + interpolate", no lighting-domain knowledge.
+//! `LightIntBand`/`LightFloatBand` decoding and time-of-day interpolation, wrapping across
+//! midnight.
 
 use std::collections::HashMap;
 
@@ -20,8 +18,7 @@ pub(super) struct Band<T> {
     values: Vec<T>,
 }
 
-/// The shared `LightIntBand`/`LightFloatBand` record schema: `ID, num, time[16], value[16]` (34
-/// fields, 136 B). `value` is `UInt32` for the int band, `Float32` for the float band.
+/// The shared band record: `ID, num, time[16], value[16]`, 34 fields, 136 bytes.
 pub(super) fn band_schema(name: &str, value: FieldType) -> Schema {
     let mut s = Schema::new(name);
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -44,14 +41,14 @@ fn decode_color(v: u32) -> [f32; 3] {
     ]
 }
 
-/// Find the segment of a band's time axis bracketing `t` (wrapping past the last entry to the
-/// first), returning `(i0, i1, frac)` for a lerp. Assumes `times` is non-empty and ascending.
+/// The `(i0, i1, frac)` segment bracketing `t`, wrapping from the last key to the first; `times`
+/// must be non-empty and ascending.
 fn segment(times: &[u32], t: u32) -> (usize, usize, f32) {
     let n = times.len();
     if n == 1 {
         return (0, 0, 0.0);
     }
-    // Wrap region: before the first or after the last entry interpolates last→first across midnight.
+    // Before the first key or after the last, interpolate last to first across midnight.
     if t < times[0] || t >= times[n - 1] {
         let span = times[0] + DAY - times[n - 1];
         if span == 0 {
@@ -145,8 +142,7 @@ mod tests {
 
     #[test]
     fn segment_wraps_across_midnight() {
-        // Two keyframes at 06:00 (720) and 18:00 (2160): a time before the first wraps from the
-        // last (interpolating across midnight), not clamps.
+        // Keys at 06:00 and 18:00 in half-minutes: 03:00 wraps from the last key, not clamps.
         let times = [720u32, 2160];
         let (i0, i1, f) = segment(&times, 360);
         assert_eq!((i0, i1), (1, 0));
diff --git a/crates/benilla-formats/src/liquid.rs b/crates/benilla-formats/src/liquid.rs
index 3daa2d57..5d6b4bd0 100644
--- a/crates/benilla-formats/src/liquid.rs
+++ b/crates/benilla-formats/src/liquid.rs
@@ -1,73 +1,36 @@
-//! MCLQ liquid surfaces → per-chunk water meshes (Phase E; Phase 1 = inland water).
+//! MCLQ liquid surfaces to per-chunk liquid meshes, in raw WoW coords (+X north, +Y west, +Z up).
 //!
-//! Vanilla liquid is **MCLQ** — per-MCNK, a 9×9 absolute-height grid + an 8×8 cell-flag grid
-//! (no WotLK MH2O), one 804-byte block per set liquid header bit. [`MclqChunk`] decodes it; we
-//! validated the output **byte-identical** to a hand-decode of the raw payload against
-//! `World\Maps\Azeroth\Azeroth_32_48.adt` (2026-05-31): per-vertex `height`, raw `tile_flags` and
-//! `min/max_height` all match (the on-disk `QLCM` magic sits at the offset; the payload — and the
-//! crate's parse — start 8 bytes in).
-//!
-//! Output is in **raw WoW coords** (+X north, +Y west, +Z up, yards), like [`crate::terrain`]; the
-//! renderer applies the WoW→Bevy transform and ports the `ocean0_s.bls` shader. We emit a flat
-//! surface (normal `(0,0,1)`) of 2 triangles per **wet** cell; dry cells (flag low-nibble `0xf`,
-//! whose verts carry the FLT_MAX sentinel height) are skipped.
-//!
-//! **The cell nibble is the type** (VERIFIED `0x6ba970`/`0x68d9b0`) — the MCNK header bits only say
-//! how many blocks a chunk carries, and their bit→type ordering was never byte-proven. Reading the
-//! type off the header instead is what kept every open-world lava surface in the game from
-//! rendering (Burning Steppes, Searing Gorge, Un'Goro) and what put the ocean texture on 28 coastal
-//! river blocks while dropping the sea beside them. `build_liquid_mesh` runs the cells first for
-//! exactly that reason.
+//! An MCNK carries one 804-byte MCLQ block per set liquid header bit, each a 9×9 absolute-height
+//! grid and an 8×8 cell-flag grid. Each wet cell is two triangles; a dry cell (nibble `0xf`,
+//! corners at the FLT_MAX sentinel) is skipped. The cell nibble is the liquid type (`0x6ba970`,
+//! `0x68d9b0`); the header bits only count the blocks.
 
 use benilla_adt::MclqChunk;
 
 use crate::terrain::{snap_to_lattice, UNIT_SIZE};
 
-/// Which animated texture set + render path a liquid surface uses (selects the frame set in
-/// `benilla`). The MCLQ (ADT) path emits Still/Ocean/Magma — the reference's three fixed ADT liquid
-/// queues; the WMO MLIQ path additionally emits Slime and Rapids (canals, fountains, the Ironforge
-/// lava, Undercity).
+/// A liquid's animated texture set and render path; ADT liquid is only Still, Ocean or Magma.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum LiquidKind {
-    /// Still water — `XTextures\river\lake_a.*` (30 frames). Lakes, ponds, slow rivers, WMO canals.
+    /// Still water, `XTextures\river\lake_a.*` (30 frames): lakes, ponds, slow rivers, WMO canals.
     Still,
-    /// Rapids — `XTextures\river\fast_a.*` (16 frames). Per-cell nibble `8`.
-    ///
-    /// **Nothing in the shipped 1.12.1 data selects it**: a sweep of every MCLQ cell on all 12
-    /// terrain maps and every one of the 302 MLIQ-bearing WMO groups finds nibbles `{1, 4, 6}` and
-    /// `{0, 2, 3, 4, 6, 7}` respectively — never `8`. Kept because the name table `0x86a000` really
-    /// does map slot 8 here and the WMO path binds the raw nibble, so authored data *could*; the ADT
-    /// path can't reach it either way (its river queue hard-codes texcache type 4).
+    /// Rapids, `XTextures\river\fast_a.*` (16 frames), nibble 8 in the name table `0x86a000`. No
+    /// shipped MCLQ or MLIQ cell carries 8, and the ADT path cannot reach it.
     Rapids,
-    /// Ocean — `XTextures\ocean\ocean_h.*` (30 frames). Coastal / sea tiles.
+    /// Ocean, `XTextures\ocean\ocean_h.*` (30 frames).
     Ocean,
-    /// Magma / lava — `XTextures\lava\lava.*`. Opaque and **unlit**: the animated texture IS the body,
-    /// with no depth LUT to modulate it by — but still **fogged**, like every liquid batch (VERIFIED
-    /// wow-re `liquid-render-state-sided.md` §3/§5, which corrected the earlier
-    /// `rf-water-liquid-type-texture-material.md` reading of the `0x68d890` vert-fill: its
-    /// `0x3f800000` is an up normal's Z, not a colour or alpha, and it is byte-identical in the river
-    /// and ocean fills).
-    ///
-    /// Reached from **both** paths: WMO MLIQ (the Ironforge Great Forge) and — since the ADT magma
-    /// queue landed — MCLQ, which is all the open-world lava there is: 124 chunks in Burning Steppes
-    /// and Searing Gorge, 4 in Un'Goro. Its UVs are authored per-vertex, not generated
-    /// ([`benilla_adt::LiquidVertex::texcoords`]).
+    /// Magma, `XTextures\lava\lava.*`: opaque and unlit, but fogged like every liquid batch, since
+    /// no liquid setup overrides the device's fog-on default (`0x593d18`). Both paths reach it; its
+    /// ADT UVs are authored per vertex ([`benilla_adt::LiquidVertex::texcoords`]).
     Magma,
-    /// Slime — `XTextures\slime\slime.*`. Its own texture on the magma render category, and **code-path
-    /// identical to magma** on the WMO side: one handler, no type-2-vs-3 branch anywhere (VERIFIED
-    /// wow-re `liquid-render-state-sided.md` §5).
-    ///
-    /// **WMO liquid only** (nibbles `3`/`7`) — Undercity, the Sludge Fields. Not a deferral: the
-    /// reference has no ADT queue for slime at all (VERIFIED — `0x68de40` dispatches only its three
-    /// queues, types 4/1/6), and no shipped MCLQ cell carries nibble 3 or 7 to feed one.
+    /// Slime, `XTextures\slime\slime.*`: magma's render path with its own texture (one handler,
+    /// `0x6b68f0`). WMO only (nibbles 3 and 7): the ADT dispatch `0x68de40` has no slime queue.
     Slime,
 }
 
 impl LiquidKind {
-    /// The liquid type from a per-tile MLIQ flag low nibble (`flag & 0xf`) — the VERIFIED reference
-    /// selection (wow-re `rf-water-liquid-type-texture-material.md`, name table `0x86a000`): the
-    /// nibble indexes the animated-texture table directly. `0xf` (and any unmapped value) = hole /
-    /// no liquid → `None`. `4` is a same-class `lake_a` variant of `0`; `6`/`7` of `2`/`3`.
+    /// The kind a WMO tile nibble selects: it indexes the animated-texture name table `0x86a000`
+    /// directly, with 4, 6 and 7 as variants of 0, 2 and 3.
     pub fn from_nibble(nibble: u8) -> Option<LiquidKind> {
         match nibble & 0xf {
             0 | 4 => Some(LiquidKind::Still),
@@ -75,122 +38,66 @@ impl LiquidKind {
             2 | 6 => Some(LiquidKind::Magma),
             3 | 7 => Some(LiquidKind::Slime),
             8 => Some(LiquidKind::Rapids),
-            _ => None, // 5, 9..=0xf — NULL name-table slots / the 0xf hole sentinel
+            _ => None, // 5, 9..=0xf: empty name-table slots and the 0xf hole
         }
     }
 
-    /// The kind an **ADT** (MCLQ) cell nibble selects — which is *not* [`Self::from_nibble`].
-    ///
-    /// The reference's ADT liquid render is **three fixed queues, each hard-coding its texcache
-    /// type**: `0x6851b0` → type 4 `lake_a` (`mov ecx,4` @`0x68db9d`), `0x685010` → type 1 `ocean_h`
-    /// (@`0x68dabb`), `0x6855a0` → type 6 `lava` (@`0x68dcab`). The cell nibble selects queue
-    /// *membership* — via the class `nibble & 3` — not the texture, so an ADT nibble 0 and 8 both
-    /// draw `lake_a`, and 2 and 6 both draw `lava`. **Slime has no ADT queue at all**: it renders
-    /// only on the WMO path, so class 3 is `None` here (VERIFIED wow-re
-    /// `rf-water-liquid-type-texture-material.md` + `terrain.md`).
-    ///
-    /// The WMO path is the type-faithful one — it binds `0x68aac0(raw nibble)` — and keeps
-    /// [`Self::from_nibble`].
+    /// The kind an ADT cell nibble selects, by its class `nibble & 3`: the reference draws ADT
+    /// liquid in three queues with fixed textures, `lake_a` (`0x6851b0`, `0x68db9d`), `ocean_h`
+    /// (`0x685010`, `0x68dabb`) and `lava` (`0x6855a0`, `0x68dcab`), and none for slime. The WMO
+    /// path binds the raw nibble instead (`0x68aac0`), as [`Self::from_nibble`] does.
     pub fn from_adt_nibble(nibble: u8) -> Option<LiquidKind> {
         match nibble & 3 {
             0 => Some(LiquidKind::Still),
             1 => Some(LiquidKind::Ocean),
             2 => Some(LiquidKind::Magma),
-            _ => None, // class 3 — slime, which the reference never dispatches from an ADT
+            _ => None, // class 3, slime: no ADT queue
         }
     }
 
-    /// Whether this kind renders as an **opaque, unlit** surface (the animated texture is the body
-    /// colour, no water swatch / depth ramp / N·L darkening) — magma and slime. Water/ocean use the
-    /// depth-swatch `ocean0_s.bls` path instead.
-    ///
-    /// "Fullbright" here means **unlit, not unfogged**: every liquid batch in the reference draws with
-    /// GL_FOG enabled, magma and slime included (wow-re `liquid-render-state-sided` §3/§5). Reading it
-    /// as "no fog" is what made a submerged slime surface a flat unshaded sheet.
+    /// Whether this kind is opaque and unlit, its texture the body colour (magma, slime); water and
+    /// ocean take the `ocean0_s.bls` depth-swatch path. Unlit is not unfogged (`0x593d18`).
     pub fn is_fullbright(self) -> bool {
         matches!(self, LiquidKind::Magma | LiquidKind::Slime)
     }
 }
 
-/// One liquid surface — an MCNK's MCLQ or a WMO group's MLIQ — as a **regular vertex grid** in raw
-/// WoW coords (+Z up), plus the triangle list the renderer draws.
-///
-/// The grid is the primary form: [`Self::grid`] gives its `[cols, rows]` vertex counts,
-/// `positions`/`uvs`/`depths` are that grid row-major (`j·cols + i`), and [`Self::wet`] says which
-/// of the `(cols−1)·(rows−1)` cells carry liquid. `indices` is the render derivative — 2 triangles
-/// per wet cell — so verts under dry cells stay present but unreferenced.
-///
-/// The queries (is this XY wet, how high is the surface here) read the **grid**, not the triangles:
-/// the reference samples the liquid height as a bilinear over the containing cell's four corners
-/// (VERIFIED `0x6b7500` `liquid_height_sample`, wow-re `system/terrain` — transcribed bit-exact
-/// there), which is a cell lookup, not a triangle search. Drawn two-sided (cull off), so winding
-/// is not load-bearing.
+/// One liquid surface, an MCNK's MCLQ or a WMO group's MLIQ: a regular vertex grid in raw WoW
+/// coords and the triangles over its wet cells. Queries read the grid, as the reference samples
+/// liquid height bilinearly over the containing cell's corners (`0x6b7500`). Drawn two-sided, as
+/// every reference liquid pass turns culling off (`0x6851da`, `0x6b6302`).
 #[derive(Debug, Clone)]
 pub struct LiquidMesh {
-    /// Vertex-grid dimensions `[cols, rows]` — the counts along the two grid axes, `cols` fastest.
-    /// MCLQ is always `[9, 9]`; MLIQ is the MLIQ header's `xverts`/`yverts` (Blackrock's magma is
-    /// `[55, 82]`). Every per-vertex array below is this grid, row-major.
+    /// Vertex counts `[cols, rows]`, cols fastest: `[9, 9]` for MCLQ, the header's
+    /// `xverts`/`yverts` for MLIQ. Every per-vertex array is this grid, row-major.
     pub grid: [u32; 2],
-    /// Per-**cell** liquid coverage, row-major over `(cols−1) × (rows−1)`: `true` where the tile
-    /// nibble says liquid (and, for MCLQ, its four corner heights are real). This is the source of
-    /// truth for containment — a liquid grid is sparse (nibble `0xf` = hole), so its bounding box
-    /// routinely spans dry ground it never touches (decision 0635).
+    /// Per-cell coverage over `(cols−1)·(rows−1)`: the nibble says liquid and, for MCLQ, the
+    /// corners are real. The containment truth, since the grid's bounds span dry cells.
     pub wet: Vec<bool>,
-    /// Per-**cell**, parallel to [`Self::wet`]: the MLIQ tile flag's **`0x80`** bit — "a neighbouring
-    /// group also claims this cell". Authored on **both** claimants, never on a cell only one group
-    /// covers (measured over `Stormwind.wmo`: 190 of 2685 wet cells, each claimed by exactly two
-    /// groups and flagged in both; zero overlap among the `0x80`-clear cells — wow-re
-    /// `terrain/scratch/wmo-liquid-shared-tile-gate.md`).
-    ///
-    /// The reference's strip builder emits a tile iff `(f & 0xf) != 0xf` **and** (`f & 0x80 == 0`
-    /// **or** this group won the gate) — a per-frame 2-colouring of the portal graph that lets
-    /// exactly ONE of the two claimants draw. Without it both surfaces draw, coplanar, and the
-    /// overlap band composites the translucent water twice: the visible line across the Stormwind
-    /// canals (B141's water half). Resolved model-wide in `benilla_assets::wmo`, not here — a group
-    /// file cannot see its neighbours.
-    ///
-    /// Always `false` on the ADT path: MCLQ has no such bit and no such overlap.
+    /// Per cell, the MLIQ tile flag's `0x80`: another group claims the cell too. The reference
+    /// draws it only for the group winning a per-frame 2-colouring of the portal graph, so the
+    /// translucent overlap draws once; applied in `benilla_assets::wmo`, `false` on the ADT path.
     pub shared: Vec<bool>,
-    /// Vertex positions `[x, y, z]` in WoW yards — `cols·rows` entries, row-major.
+    /// Vertex positions in WoW yards, `cols·rows` of them.
     pub positions: Vec<[f32; 3]>,
-    /// Texture UVs parallel to `positions`. No scroll for water.
-    ///
-    /// Generated cell-index UVs (`¼` per cell, tiling) for **water and ocean** — and for WMO liquid,
-    /// anchored to model space over the same period. **Magma is different**: its UVs are *authored*
-    /// per vertex and read straight off the MCLQ union bytes (`u = s · 3/256`), because the reference's
-    /// lava batch is single-stage with a reset texture matrix, so `tc0` is the vertex's own coord
-    /// rather than anything the client generates ([`benilla_adt::LiquidVertex::texcoords`]).
+    /// Texture UVs: generated at ¼ per cell for water and ocean (WMO liquid in model space, same
+    /// period); ADT magma's are authored per vertex (`u = s · 3/256`), since the reference's lava
+    /// batch is single-stage with a reset texture matrix.
     pub uvs: Vec<[f32; 2]>,
-    /// Per-vertex liquid swatch coord **V** `0..1` from the MCLQ `SVert` depth byte, parallel to
-    /// `positions`. River/lake = `clamp(byte/42)` (VERIFIED `c81768`, saturates ~5 yd); ocean =
-    /// `clamp(byte/255)` (VERIFIED `c7fcd8`, saturates ~148 yd — its own LUT, on its own authored
-    /// byte scale; see [`OCEAN_DEPTH_V_SATURATION`]). The reference uses
-    /// this single V to index the depth swatch for BOTH the body-colour band (shallow→deep water rows)
-    /// and the opacity ramp (`colorTex.a` = `127+2·row`, deeper = more opaque).
-    ///
-    /// **Zero on ADT magma, and read by nothing**: those union bytes are texture coords, not a depth
-    /// byte, and the reference's magma vert-fill reads no ramp at all (`0x68d890` — no LUT load,
-    /// unlike the river/ocean fills). The shader's fullbright branch returns before it ever samples
-    /// this, so the zero is a statement, not a value. (The WMO builder fills its own flat
-    /// `WMO_WATER_DEPTH_V` for every kind, magma and slime included — equally unread there.)
+    /// Per-vertex swatch coord V (0..1) from the MCLQ depth byte: `clamp(byte/42)` for river and
+    /// lake, `clamp(byte/255)` for ocean. The reference indexes the depth swatch with this one V
+    /// for both the body colour and the opacity ramp (`colorTex.a = 127 + 2·row`). 0 on ADT magma,
+    /// whose union bytes are texture coords and whose vert-fill (`0x68d890`) reads no ramp.
     pub depths: Vec<f32>,
-    /// Triangle indices into `positions` — 6 per wet cell, cells in row-major order. Derived from
-    /// [`Self::wet`]; the render form.
+    /// Triangle indices, 6 per wet cell in row-major order, derived from [`Self::wet`].
     pub indices: Vec<u32>,
-    /// The surface's **sound-class nibble** — the majority wet cell's low nibble (terrain), or
-    /// the `0x6ba970`-resolved nibble (WMO): `class = nibble & 3`, `FluidSpeed = nibble & 0xc`,
-    /// the key the above-water liquid ambient-loop system resolves through `SoundWaterType.dbc`
-    /// ([`crate::WaterSoundCatalog`]; wow-re `liquid-ambience-loop.md`, decision 0506). Carried
-    /// beside `kind` because the render kind collapses the river speeds (nibbles 0 and 4 both
-    /// draw `lake_a`) that the sound table splits (RiverStill 1111 vs RiverSlow 1112).
+    /// The sound nibble, class `& 3` and FluidSpeed `& 0xc`: the majority wet cell's (ADT) or the
+    /// `0x6ba970` one (WMO), keyed through `SoundWaterType.dbc` (`0x462a40`). Kept beside `kind`,
+    /// which merges the river speeds (nibbles 0 and 4) that the sound table splits.
     pub sound_nibble: u8,
-    /// **WMO only** — the MLIQ header's `materialId`, i.e. this pool's index into the owning root's
-    /// MOMT array. The reference's INTERIOR water kernel takes its whole body colour from
-    /// `MOMT[materialId].diffColor` (see `benilla_wmo::Material::diff_color`), so this is how a pool
-    /// finds its own colour; the group file alone cannot resolve it, because MOMT lives in the root.
-    /// `None` on the ADT path, which has no such index and no such lookup.
+    /// WMO only: the MLIQ header's `materialId`, an index into the root's MOMT, whose `diffColor`
+    /// is the reference's interior water body colour. `None` on the ADT path.
     pub material_id: Option<u16>,
-    /// The texture set / render path this surface uses.
     pub kind: LiquidKind,
 }
 
@@ -200,56 +107,24 @@ const GRID: usize = 9;
 const CELLS: usize = 8;
 /// Cell-flag low nibble meaning "dry / do not render".
 const DRY_NIBBLE: u8 = 0x0f;
-/// The scale the reference applies to a magma vertex's authored `u16` texture coords:
-/// `u = (s as i32 as f64 · TEXC) as f32`, `TEXC = 0x3c400000 = 3/256`. VERIFIED bit-exact at
-/// `WoW.exe 0x68d890` (`liquid_render_verts`), emulation-diffed over 60 randomized fills in wow-re
-/// `crates/terrain/tests/difftest/fills.rs`. Authored steps run ≈42 units per 4.167-yd cell, so one
-/// lava repeat spans ≈8.5 yd — twice the density of the ¼-per-cell water field.
+/// The reference's scale on a magma vertex's authored `u16` texcoords, `0x3c400000` (3/256):
+/// `u = (s as i32 as f64 · scale) as f32`, bit-exact to `0x68d890`.
 const MAGMA_TEXCOORD_SCALE: f32 = f32::from_bits(0x3c40_0000);
-/// Verts under no liquid carry FLT_MAX (`0x7F7FFFFF`) — `is_finite()` is TRUE for it, so gate on
-/// magnitude instead.
+/// Verts under no liquid carry FLT_MAX (`0x7F7FFFFF`), which is finite, so gate on magnitude.
 const HEIGHT_SENTINEL: f32 = 1.0e9;
-/// River/lake depth-byte at which the swatch coord `V` saturates to 1.0: `V = clamp(byte/42)`.
-/// VERIFIED from `WoW.exe` — the in-game river/lake water list (`FUN_0068d790`) reads the **steep**
-/// `DAT_00c81768` LUT, built by `FUN_0068c4c0` as `clamp((d/9)/4.6667) = clamp(d/42)` (constants
-/// `0x81028c=1/9`, `0x810380=1/4.6667` static-verified), and the live VBO confirms `V` is multiples
-/// of 1/42 saturating at 1.0. (The gentler `byte/255` = the `DAT_00c7fcd8` LUT on a DIFFERENT list
-/// `FUN_0068d690` that the from-above river path does not use — hence the river middle never reached
-/// the deep/teal swatch row until this. The river depth ramp is ≈8.5 byte/yd, so V saturates at ≈5 yd.)
+/// The river and lake depth byte at which V saturates, `clamp(byte/42)`: the LUT `0xc81768`, built
+/// by `0x68c4c0` as `clamp((d/9)/4.6667)` (`0x81028c`, `0x810380`) and read by the river fill
+/// `0x68d790`. About 5 yd of water.
 const RIVER_DEPTH_V_SATURATION: f32 = 42.0;
-/// Ocean depth-byte at which the swatch coord `V` saturates: `V = clamp(byte/255)`.
-/// VERIFIED — the ocean has its **own** LUT, not a missing one. `FUN_0068c4c0` builds
-/// `DAT_00c7fcd8[i] = min(i/255, 1.0)` (256 f32 entries, `fstp` @`0x68c57c`) beside the river's
-/// `c81768`, and the ocean vert-fill reads it at `0x68d718 fld [depth*4 + 0xc7fcd8]` exactly as the
-/// river fill reads its own at `0x68d818` — same shape, same `tc0 = (0.5, ramp[depthByte])`, only a
-/// different divisor (wow-re `terrain/scratch/rf81-liquid-color-lut-builder.md`, a §5 pair that
-/// converged byte-identically, corroborated independently by `water-shading-law.md` §5).
-///
-/// **The two divisors are not comparable, because the two depth bytes are not on one scale** — which
-/// is what made `/255` look 6× too slow beside the river's `/42`. Measured over every MCLQ block in
-/// Azeroth + Kalimdor (`examples/liquid_depth_census`, 17.4 M ocean and 0.55 M river wet vertices,
-/// each byte paired against its own geometric depth `surface − terrain`):
-///
-/// | | authored ramp | byte 255 is | V saturates at |
-/// |---|---|---|---|
-/// | river/lake | 8.96 byte/yd | 28 yd | byte 42 ≈ **4.7 yd** |
-/// | ocean | 1.72 byte/yd | 148 yd | byte 255 ≈ **148 yd** |
-///
-/// The artists authored the sea's byte **5.2× gentler per yard**, so the 6× gentler LUT lands the two
-/// ramps within ~15 % of each other in *yards of depth per unit of V*. `/42` on the ocean would be
-/// the correction applied twice. It is also not a subtle difference: **83.4 % of all ocean wet
-/// vertices are pinned at byte 255** — the open sea is authored fully deep, and the whole ramp is a
-/// shore band. (The river control reproduces its own independently-verified ≈8.5 byte/yd, which is
-/// what says the census measures what it claims to.)
+/// The ocean depth byte at which V saturates, `clamp(byte/255)`: the ocean's own LUT `0xc7fcd8`,
+/// built beside the river's (`0x68c57c`) and read by the ocean fill `0x68d690` at `0x68d718`, as
+/// the river fill reads its own at `0x68d818`. The divisors differ because the bytes do: over every
+/// Azeroth and Kalimdor MCLQ block (`examples/liquid_depth_census`) the sea is authored at 1.72
+/// byte/yd against the river's 8.96, and 83.4 % of ocean vertices sit at 255.
 const OCEAN_DEPTH_V_SATURATION: f32 = 255.0;
 
-/// `WOW_OCEAN_DEPTH_DIV=<divisor>` — override [`OCEAN_DEPTH_V_SATURATION`] for one run.
-///
-/// The ocean depth ramp is 97 % of the water in the world and its whole visible extent is the shore
-/// band, so "is this the right curve" is a question about a beach, and a **look** question — the
-/// director's to call, not ours to grade from a screenshot. This is the A/B: `WOW_OCEAN_DEPTH_DIV=42`
-/// puts the river's ramp on the sea (deep by ~24 yd of depth instead of ~148), so the two can be run
-/// side by side against `./run-ref-client.sh` at the same shoreline. Read once, at first use.
+/// `WOW_OCEAN_DEPTH_DIV=<divisor>` overrides [`OCEAN_DEPTH_V_SATURATION`] for one run, read once;
+/// 42 puts the river's ramp on the sea for a side-by-side at a shoreline.
 fn ocean_depth_v_divisor() -> f32 {
     static DIV: std::sync::OnceLock<f32> = std::sync::OnceLock::new();
     *DIV.get_or_init(|| {
@@ -261,24 +136,17 @@ fn ocean_depth_v_divisor() -> f32 {
     })
 }
 
-/// Build a flat liquid surface mesh from one parsed MCLQ **block** at MCNK origin `position` (the
-/// chunk header's raw WoW `[x, y, z]`). A chunk can hold more than one block — see [`MclqChunk`].
-///
-/// `None` when the block has no wet cell, or when its cells are slime, which the reference has no
-/// ADT queue for ([`LiquidKind::from_adt_nibble`]).
+/// Mesh one MCLQ block at the MCNK header's raw WoW `position`; `None` when no cell is wet or the
+/// cells are slime, which has no ADT queue.
 pub(crate) fn build_liquid_mesh(mclq: &MclqChunk, position: [f32; 3]) -> Option<LiquidMesh> {
     if mclq.vertices.len() < GRID * GRID || mclq.tile_flags.len() < CELLS * CELLS {
         return None;
     }
 
-    // ── Cells first, because the CELLS decide the kind. ──
-    // 2 tris per wet cell. Skip dry cells (low nibble 0xf) and any cell with a sentinel-height
-    // corner (belt-and-suspenders).
+    // ── Cells first: they decide the kind. ──
     let mut indices = Vec::with_capacity(CELLS * CELLS * 6);
     let mut wet = vec![false; CELLS * CELLS];
-    // Wet-cell nibble tally → the block's majority nibble, which is BOTH its render kind and its
-    // sound class (`LiquidMesh::sound_nibble`). Counted over genuinely-wet cells only, so it
-    // describes what is actually drawn.
+    // The majority nibble over drawn cells is both the render kind and the sound class.
     let mut nibble_counts = [0u32; 16];
     for row in 0..CELLS {
         for col in 0..CELLS {
@@ -290,8 +158,7 @@ pub(crate) fn build_liquid_mesh(mclq: &MclqChunk, position: [f32; 3]) -> Option<
             let tr = tl + 1;
             let bl = ((row + 1) * GRID + col) as u32;
             let br = bl + 1;
-            // Guard against a wet cell whose corner is the sentinel/NaN (data anomaly) — check the
-            // ORIGINAL heights, not the sanitized `positions`. Wet cells normally carry real heights.
+            // A wet cell with a sentinel or NaN corner is a data anomaly; skip it.
             if [tl, tr, bl, br].iter().any(|&i| {
                 let raw = mclq.vertices[i as usize].height;
                 !raw.is_finite() || raw.abs() >= HEIGHT_SENTINEL
@@ -299,8 +166,7 @@ pub(crate) fn build_liquid_mesh(mclq: &MclqChunk, position: [f32; 3]) -> Option<
                 continue;
             }
             nibble_counts[flag as usize] += 1;
-            // The cell is liquid AND its corners are real — the same gate the triangles pass, so
-            // the grid the queries read and the mesh the renderer draws can never disagree.
+            // One gate for `wet` and the triangles, so the queries and the drawing agree.
             wet[row * CELLS + col] = true;
             indices.extend_from_slice(&[tl, bl, br, tl, br, tr]);
         }
@@ -309,10 +175,7 @@ pub(crate) fn build_liquid_mesh(mclq: &MclqChunk, position: [f32; 3]) -> Option<
         return None;
     }
 
-    // The kind comes from the CELL NIBBLE — the VERIFIED type source (`0x6ba970`/`0x68d9b0`) — not
-    // from the MCNK header bits, whose bit→type ordering was never byte-proven and which mislabelled
-    // every two-block river-mouth chunk as ocean. In shipped data a block's wet cells are of one
-    // class throughout, so the majority is the block; the tally is what breaks a tie.
+    // The kind is the cells' nibble, not the header bits; a shipped block is one class throughout.
     let sound_nibble = nibble_counts
         .iter()
         .enumerate()
@@ -321,36 +184,24 @@ pub(crate) fn build_liquid_mesh(mclq: &MclqChunk, position: [f32; 3]) -> Option<
         .unwrap_or(0);
     let kind = LiquidKind::from_adt_nibble(sound_nibble)?;
 
-    // Depth-byte → swatch coord `V` divisor. BOTH are VERIFIED, and they are two LUTs built side by
-    // side in `FUN_0068c4c0`, not one law and one stand-in: river/lake `c81768` = `min(d/42, 1)` read
-    // by the river fill `FUN_0068d790`, ocean `c7fcd8` = `min(d/255, 1)` read by the ocean fill
-    // `FUN_0068d690`. They differ because the two authored depth bytes are on different scales — see
-    // [`OCEAN_DEPTH_V_SATURATION`] for the census that measures both.
     let depth_v_div = match kind {
         LiquidKind::Ocean => ocean_depth_v_divisor(),
         _ => RIVER_DEPTH_V_SATURATION,
     };
-    // Magma reads its UVs off the vertex and its depth off nothing at all (see `LiquidMesh::uvs` /
-    // `::depths`); every other kind generates cell-index UVs and ramps by the depth byte.
+    // Magma's UVs are authored and its depth unread; the rest generate UVs and ramp the depth byte.
     let authored_uvs = kind == LiquidKind::Magma;
     let [wx, wy, _wz] = position;
 
-    // 81 grid verts in raw WoW coords. Linear index `n`: row = n/9 (steps south, −X), col = n%9
-    // (steps east, −Y) — the same orientation as the MCVT outer grid, so the water lattice lines
-    // up with the terrain it sits in. Z is the MCLQ per-vertex absolute world height. Snap X/Y to
-    // the global lattice exactly as terrain does.
+    // Rows step south (−X) and columns east (−Y) like the MCVT outer grid, on the terrain's
+    // lattice; Z is the MCLQ absolute height.
     let mut positions = Vec::with_capacity(GRID * GRID);
     let mut uvs = Vec::with_capacity(GRID * GRID);
     let mut depths = Vec::with_capacity(GRID * GRID);
     for n in 0..GRID * GRID {
         let row = (n / GRID) as f32;
         let col = (n % GRID) as f32;
-        // Dry/no-liquid verts carry the FLT_MAX (0x7F7FFFFF) sentinel (and `is_finite()` is TRUE for
-        // it). They're never indexed (only wet cells emit tris), but they stay in `positions`, so a
-        // raw sentinel would blow the mesh AABB out to ~1e38 — which makes Bevy's visibility culling
-        // drop the whole chunk (the "partial water chunks vanish, fully-wet ocean is fine" bug, since
-        // only mixed-wet/dry chunks contain sentinels). Substitute the chunk's `min_height` for any
-        // non-finite/sentinel height so the AABB stays tight; the value is invisible (unreferenced).
+        // A dry vert's sentinel would stretch the AABB to ~1e38 and get a partly wet chunk culled;
+        // it takes `min_height`, unreferenced.
         let raw = mclq.vertices[n].height;
         let h = if raw.is_finite() && raw.abs() < HEIGHT_SENTINEL {
             raw
@@ -363,8 +214,7 @@ pub(crate) fn build_liquid_mesh(mclq: &MclqChunk, position: [f32; 3]) -> Option<
             h,
         ]);
         if authored_uvs {
-            // `u = (s as i32 as f64 · 3/256) as f32` — VERIFIED bit-exact `0x68d890`. Unsigned: the
-            // reference widens the u16 to i32, so 0xffff is 65535, never −1.
+            // Unsigned: the reference widens the `u16` to `i32`, so 0xffff is 65535, never −1.
             let [s, t] = mclq.vertices[n].texcoords();
             let scale = f64::from(MAGMA_TEXCOORD_SCALE);
             uvs.push([
@@ -374,10 +224,6 @@ pub(crate) fn build_liquid_mesh(mclq: &MclqChunk, position: [f32; 3]) -> Option<
             depths.push(0.0);
         } else {
             uvs.push([col * 0.25, row * 0.25]);
-            // SVert depth byte (water/ocean: union_data[0]) → swatch coord V (0..1). River/lake saturate
-            // at byte 42 (`clamp(byte/42)`, VERIFIED `c81768`) so the channel middle hits the deep/teal
-            // swatch row; ocean at /255 (see `depth_v_div`). The SAME V drives both the body-colour depth
-            // band and the opacity ramp on the shader side (one swatch row → colour + alpha).
             depths.push((mclq.vertices[n].depth_byte() as f32 / depth_v_div).clamp(0.0, 1.0));
         }
     }
@@ -397,12 +243,8 @@ pub(crate) fn build_liquid_mesh(mclq: &MclqChunk, position: [f32; 3]) -> Option<
 }
 
 impl LiquidMesh {
-    /// Drop the cells `keep` rejects (indexed like [`Self::wet`]), rebuilding [`Self::indices`].
-    /// The vertex arrays are left alone — a vertex no triangle references costs nothing to keep and
-    /// the grid stays addressable by cell index.
-    ///
-    /// This is how the MLIQ [`Self::shared`] gate is applied once the owning model can see every
-    /// group at once.
+    /// Drop the cells `keep` rejects (indexed like [`Self::wet`]) and rebuild [`Self::indices`];
+    /// the vertex grid stays whole. Applies [`Self::shared`] once the model has every group.
     pub fn retain_cells(&mut self, keep: impl Fn(usize) -> bool) {
         let (cols, rows) = (self.grid[0] as usize, self.grid[1] as usize);
         let (xt, yt) = (cols.saturating_sub(1), rows.saturating_sub(1));
@@ -438,7 +280,7 @@ mod tests {
 
     use super::*;
 
-    /// Every liquid mesh a real tile builds, with the MCNK origin each came from.
+    /// Every liquid mesh a real tile builds.
     fn tile_liquids(chain: &mut crate::Chain, map: &str, tx: u32, ty: u32) -> Vec<LiquidMesh> {
         let bytes = chain
             .read_file(&format!("World\\Maps\\{map}\\{map}_{tx}_{ty}.adt"))
@@ -455,8 +297,7 @@ mod tests {
             .collect()
     }
 
-    /// Whether a mesh's **wet** footprint covers a raw WoW `(x, y)`, and at what surface height —
-    /// the containment the swim/submersion queries do, done here off the grid directly.
+    /// The surface height where a mesh's wet cells cover a raw WoW `(x, y)`.
     fn wet_at(m: &LiquidMesh, x: f32, y: f32) -> Option<f32> {
         let cols = m.grid[0] as usize;
         for (c, _) in m.wet.iter().enumerate().filter(|(_, &w)| w) {
@@ -484,15 +325,8 @@ mod tests {
         None
     }
 
-    /// **B21 — "there should be lava here", `.go xyz -7845.99 -1065.50 123.60 0`.**
-    ///
-    /// Open-world lava is MCLQ magma, and the ADT mesher used to return `None` for it, so every
-    /// outdoor lava surface in the game was silently absent while Blackrock's (WMO MLIQ) rendered
-    /// fine — exactly the shape of the report. The pin is Burning Steppes, tile 33_46.
-    ///
-    /// This is the whole of it: a sweep of all 12 shipped terrain maps finds MCLQ magma on five
-    /// tiles only — 124 chunks across Burning Steppes/Searing Gorge and 4 in Un'Goro — and no MCLQ
-    /// slime anywhere at all.
+    /// Open-world lava is MCLQ magma: the pin, `.go xyz -7845.99 -1065.50 123.60 0` in Burning
+    /// Steppes (tile 33_46), stands on it.
     #[test]
     fn b21_burning_steppes_lava_builds_a_magma_surface_at_the_reported_pin() {
         let data = crate::wow_data_or_skip!();
@@ -505,7 +339,7 @@ mod tests {
             .collect();
         assert_eq!(magma.len(), 64, "Burning Steppes tile 33_46 magma chunks");
 
-        // The reported spot itself is wet, with lava — not merely "somewhere on this tile".
+        // The pin itself is on lava, not merely the tile.
         let (px, py, pz) = (-7845.99f32, -1065.50, 123.60);
         let hit = magma
             .iter()
@@ -516,24 +350,21 @@ mod tests {
             "lava surface {hit} sits at the reported eye height {pz}"
         );
 
-        // Fullbright + opaque, and carrying the lava-flow sound class (nibble 6: class 2 = magma,
-        // FluidSpeed 4 → LavaFlowLoop) — the whole magma contract, not just a mesh that exists.
+        // Nibble 6 is class 2 (magma) at FluidSpeed 4, the lava-flow loop.
         assert!(magma.iter().all(|m| m.kind.is_fullbright()));
         assert!(
             magma.iter().all(|m| m.sound_nibble == 6),
             "shipped ADT magma is nibble 6 throughout"
         );
-        // No ADT slime exists to build, and the reference has no queue for it if it did.
+        // No ADT slime ships, and the reference has no ADT queue for it.
         assert!(
             !meshes.iter().any(|m| m.kind == LiquidKind::Slime),
             "slime never renders from an ADT"
         );
     }
 
-    /// Lava's UVs are **authored per vertex**, not generated — and authored *world-continuously*, so
-    /// a chunk's east edge repeats its neighbour's west edge exactly. That continuity is the check
-    /// that the `u16 → ·3/256` read (VERIFIED `0x68d890`) is being applied to the right bytes in the
-    /// right order: get the scale wrong and it still tiles, get the *field* wrong and the seam shows.
+    /// Lava UVs are authored world-continuously, so a chunk's east edge repeats its neighbour's
+    /// west edge; reading the wrong bytes shows as a seam.
     #[test]
     fn magma_uvs_come_from_the_vertex_and_run_continuous_across_chunks() {
         let data = crate::wow_data_or_skip!();
@@ -556,7 +387,7 @@ mod tests {
             "magma UVs are authored, not the water cell-index UVs"
         );
 
-        // Two chunks adjacent along −Y: the west one's col-8 vertex column IS the east one's col-0.
+        // Two chunks adjacent along −Y: the west one's column 8 is the east one's column 0.
         let mut shared = 0;
         for a in &magma {
             for b in &magma {
@@ -564,7 +395,7 @@ mod tests {
                 if (pa[0] - pb[0]).abs() < 0.01 && (pa[1] - pb[1]).abs() < 0.01 {
                     for row in 0..9 {
                         let (ua, ub) = (a.uvs[row * 9 + 8], b.uvs[row * 9]);
-                        // Sentinel-height (dry) verts carry no authored coord — skip those.
+                        // Dry verts carry no authored coord.
                         if ua == [0.0, 0.0] || ub == [0.0, 0.0] {
                             continue;
                         }
@@ -580,12 +411,8 @@ mod tests {
         assert!(shared > 0, "no shared lava chunk edge found to check");
     }
 
-    /// **The sweep's second find: an MCNK can carry more than one MCLQ block**, one per set liquid
-    /// header bit (VERIFIED wow-re `adt-format.md`). 28 shipped Azeroth chunks are river mouths that
-    /// carry two — the stream *and* the sea beneath it — and reading only the first dropped the sea
-    /// while the old header-bit priority ("ocean wins") labelled the river block ocean.
-    ///
-    /// Hillsbrad's tile 33_33 is one. Both blocks must survive, each with its own kind and height.
+    /// An MCNK carries one MCLQ block per set liquid header bit (`0x6af7a3`); a river mouth, as on
+    /// Hillsbrad's tile 33_33, carries a stream over the sea.
     #[test]
     fn a_river_mouth_chunk_builds_both_its_river_and_its_sea() {
         let data = crate::wow_data_or_skip!();
@@ -617,8 +444,7 @@ mod tests {
                 .filter_map(|lq| build_liquid_mesh(lq, mcnk.header.position))
                 .collect();
             assert_eq!(built.len(), 2, "both blocks mesh");
-            // Disk order is header-bit order: bit 2 (river) then bit 3 (ocean) — and the KIND comes
-            // from each block's own cell nibble, so the river no longer reads as ocean.
+            // Disk order is header-bit order, bit 2 (river) then bit 3 (ocean).
             assert_eq!(built[0].kind, LiquidKind::Still, "block 0 is the stream");
             assert_eq!(built[1].kind, LiquidKind::Ocean, "block 1 is the sea");
             let sea = built[1].positions[built[1].indices[0] as usize][2];
@@ -627,19 +453,9 @@ mod tests {
                 river > sea + 1.0,
                 "the stream ({river}) sits above sea level ({sea})"
             );
-            // **The invariant that makes spawning both safe at a river mouth.**
-            // `liquid::liquid_at` resolves overlapping footprints by taking the LOWEST surface
-            // (decision 0634/0701 — the volume you are actually in when two are stacked). If a
-            // river cell and an ocean cell covered the same XY, the sea at z≈0 would win under a
-            // stream 5 yd above it and the player would read as dry while standing in the water.
-            // At every real river mouth the two blocks are authored **disjoint** — each cell
-            // belongs to exactly one — so they never compete for a position.
-            //
-            // Swept game-wide: 28 two-block chunks, and the only 4 whose cells overlap are in
-            // Kalimdor tile 26_54 (a flat −23.47 sheet under a full-chunk sea at 0.0, in the dead
-            // water off the south-west corner). That patch read the same way *before* multi-block
-            // parsing — the first block was all there was — so it is a named residual of the
-            // lowest-wins rule, not a regression. See the decision record.
+            // `benilla_world`'s `liquid_at` takes the lowest of stacked surfaces, so a cell wet in
+            // both would read the stream as dry; the blocks are authored disjoint. Only Kalimdor
+            // tile 26_54 has overlapping blocks, a sheet at −23.47 under open sea.
             for (cell, (&r, &o)) in built[0].wet.iter().zip(&built[1].wet).enumerate() {
                 assert!(
                     !(r && o),
@@ -650,11 +466,7 @@ mod tests {
         }
     }
 
-    /// Golden test against a real Elwynn tile: Crystal Lake area `Azeroth_32_48.adt` has 42 MCLQ
-    /// water chunks (all river/still, surface ≈ 143.99 yd). Skips when the client isn't present.
-    /// Every liquid mesh a real tile builds, **paired with the raw MCLQ block it came from** — so a
-    /// depth assertion can be made against the bytes on disk rather than against the mesh's own
-    /// arithmetic run backwards.
+    /// Every liquid mesh a real tile builds, paired with the raw MCLQ block it came from.
     fn tile_liquids_with_source(
         chain: &mut crate::Chain,
         map: &str,
@@ -676,16 +488,8 @@ mod tests {
             .collect()
     }
 
-    /// **The two depth divisors are two verified LUTs, not one law and one stand-in.** The ocean's
-    /// `/255` spent months labelled a placeholder on a misattributed address (`0x68d890` — the
-    /// *magma* vert-fill), so this pins both against real shipped data: an ocean tile off Baradin
-    /// Bay whose depth bytes run the full ramp, and Elwynn's rivers as the control.
-    ///
-    /// The V assertions read the **raw MCLQ depth byte**, never a byte recovered from the mesh's own
-    /// V (that would assert the arithmetic against itself and pass under any divisor). The shore-band
-    /// assertion is the one with teeth: the sea's byte is authored ~5× gentler per yard than a
-    /// river's, so putting the river's `/42` on the ocean saturates a shore band that should still
-    /// be ramping — which is exactly the look change this ramp is not.
+    /// The V assertions read the raw depth byte, never one recovered from the mesh's V, which would
+    /// pass under any divisor.
     #[test]
     fn each_liquid_kind_rides_its_own_verified_depth_divisor() {
         let data = crate::wow_data_or_skip!();
@@ -711,8 +515,7 @@ mod tests {
             }
         }
 
-        // The shore band exists and is NOT saturated — the whole point of the gentler divisor. Under
-        // `/42` every one of these mid-band verts would already read the deep row.
+        // Under `/42` every one of these mid-band verts would already read fully deep.
         let mid = raw.iter().filter(|&&b| (42..=200).contains(&b)).count();
         let pinned = raw.iter().filter(|&&b| b == u8::MAX).count();
         assert!(
@@ -725,7 +528,7 @@ mod tests {
              through (against {pinned} genuinely pinned-deep) — the look change the ocean ramp is not"
         );
 
-        // Control: rivers/lakes DO ride `/42`, and Elwynn's channel middles reach the deep row.
+        // Control: Elwynn's rivers ride `/42`, and their channel middles saturate.
         let river: Vec<(benilla_adt::MclqChunk, LiquidMesh)> =
             tile_liquids_with_source(&mut chain, "Azeroth", 32, 48)
                 .into_iter()
@@ -741,8 +544,7 @@ mod tests {
                     (*v - want).abs() < 1e-4,
                     "river V is clamp(byte/42) (VERIFIED `c81768`); byte {byte} gave V={v}"
                 );
-                // The teeth on the river side: a byte well under 255 already reads fully deep,
-                // which `/255` could never produce.
+                // A byte well under 255 reading fully deep, which `/255` could never produce.
                 saturated_below_255 |= (42..200).contains(&byte) && *v >= 0.999;
             }
         }
@@ -771,7 +573,6 @@ mod tests {
             }
         }
 
-        // 42 water chunks on this tile, every one still river water.
         assert_eq!(
             meshes.len(),
             42,
@@ -786,9 +587,7 @@ mod tests {
             assert_eq!(m.positions.len(), 81, "9×9 grid");
             assert_eq!(m.uvs.len(), 81, "uv per vertex");
             assert_eq!(m.depths.len(), 81, "depth per vertex");
-            // EVERY vertex (even unreferenced dry-cell verts) must be finite + sane, or the mesh AABB
-            // blows up (dry verts carry the FLT_MAX sentinel) and Bevy frustum-culls the whole chunk —
-            // the "partial water chunks vanish, fully-wet ocean is fine" bug.
+            // Even unreferenced verts stay finite, or the AABB blows up and the chunk is culled.
             for p in &m.positions {
                 assert!(
                     p[2].is_finite() && p[2].abs() < 10_000.0,
@@ -798,9 +597,7 @@ mod tests {
             }
             assert!(!m.indices.is_empty(), "at least one wet cell");
             assert_eq!(m.indices.len() % 6, 0, "2 tris per wet cell");
-            // Indices in range, and every referenced vertex has a finite, sane height — no
-            // FLT_MAX sentinel leaked in (the dry-cell gate worked). Elwynn water bodies sit at
-            // various elevations (Crystal Lake ≈ 144 yd, streams lower), all in a plausible band.
+            // Elwynn's water sits between 50 and 300 yd (Crystal Lake ≈ 144).
             assert!(m.indices.iter().all(|&i| (i as usize) < m.positions.len()));
             for &i in &m.indices {
                 let z = m.positions[i as usize][2];
@@ -813,8 +610,7 @@ mod tests {
                     "Elwynn water elevation {z} plausible"
                 );
             }
-            // Within one chunk a water surface is near-planar (a lake; a gentle stream slopes a
-            // little across the 33-yd chunk but not wildly).
+            // A chunk's surface is near-planar; a stream slopes a little across 33 yd.
             let zs: Vec<f32> = m
                 .indices
                 .iter()
diff --git a/crates/benilla-formats/src/loading_screen.rs b/crates/benilla-formats/src/loading_screen.rs
index 9de949e2..e180e532 100644
--- a/crates/benilla-formats/src/loading_screen.rs
+++ b/crates/benilla-formats/src/loading_screen.rs
@@ -1,13 +1,6 @@
-//! LoadingScreens.dbc loader: resolves a `LoadingScreenID` (the FK in `Map.dbc` field 38, see
-//! [`crate::MapCatalog::loading_screen_id`]) to the full-screen load-art **BLP path**.
-//!
-//! Layout — VERIFIED against build 5875 (raw-byte decode of extracted `DBFilesClient\
-//! LoadingScreens.dbc`, 2026-06-02): the WDBC header reports **40 records · 3 fields · 12 B/record**
-//! (3 × 4 = 12, and `20 + 40·12 + 2926 == 3426` file bytes). Fields = `(ID, Name string, FileName
-//! string)`; field 0 = id, field 2 = BLP path (e.g. `Interface\Glues\LoadingScreens\
-//! LoadScreenEasternKingdom.blp`). Open-world art is continent-wide — id 3 = Kalimdor, id 4 =
-//! Azeroth/EasternKingdom — the other 38 rows are per-instance. The art is a 512×512 square scene
-//! with the WoW logo composited in; the client stretch/crop-fills it to the screen.
+//! `LoadingScreens.dbc`: a `Map.dbc` `LoadingScreenID` (column 38) → the loading art's BLP path
+//! (column 2). The open world has one per continent (3 Kalimdor, 4 Eastern Kingdoms); the other
+//! rows are per instance.
 
 use std::collections::HashMap;
 
@@ -19,14 +12,12 @@ use crate::dbc::{parse, str_at, u32_at};
 
 const LOADING_SCREENS: &str = "DBFilesClient\\LoadingScreens.dbc";
 
-/// Resolved `LoadingScreenID → BLP path` map, built once at startup off the client's
-/// LoadingScreens.dbc.
+/// `LoadingScreenID` → BLP path.
 pub struct LoadingScreenCatalog {
     paths: HashMap<u32, String>,
 }
 
 impl LoadingScreenCatalog {
-    /// The load-art BLP path for `id` (a `Map.dbc` `LoadingScreenID`), or `None` if absent.
     pub fn path(&self, id: u32) -> Option<&str> {
         self.paths.get(&id).map(String::as_str)
     }
@@ -40,7 +31,6 @@ impl LoadingScreenCatalog {
     }
 }
 
-/// 3 fields: ID (0), Name string (1, unused), FileName string (2 = BLP path).
 fn schema() -> Schema {
     let mut s = Schema::new("LoadingScreens");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -70,9 +60,6 @@ mod tests {
     use super::*;
     use crate::load_map_catalog;
 
-    /// Golden test of the full Map.dbc→LoadingScreens.dbc→BLP FK chain against the real client.
-    /// Verified pairs (decoded 2026-06-02): mapId 0 (Azeroth) → 4 → EasternKingdom art; mapId 1
-    /// (Kalimdor) → 3 → Kalimdor art. Skips when the client isn't present.
     #[test]
     fn resolves_open_world_loading_art() {
         let data = crate::wow_data_or_skip!();
@@ -80,11 +67,9 @@ mod tests {
         let maps = load_map_catalog(&mut chain).expect("Map.dbc");
         let screens = load_loading_screens(&mut chain).expect("LoadingScreens.dbc");
 
-        // FK values (Map.dbc field 38).
         assert_eq!(maps.loading_screen_id(0), Some(4), "Azeroth → 4");
         assert_eq!(maps.loading_screen_id(1), Some(3), "Kalimdor → 3");
 
-        // FK → BLP path (LoadingScreens.dbc field 2).
         assert_eq!(
             screens.path(4),
             Some("Interface\\Glues\\LoadingScreens\\LoadScreenEasternKingdom.blp")
@@ -94,7 +79,6 @@ mod tests {
             Some("Interface\\Glues\\LoadingScreens\\LoadScreenKalimdor.blp")
         );
 
-        // End-to-end resolution for both continents.
         let resolve = |map_id| {
             maps.loading_screen_id(map_id)
                 .and_then(|id| screens.path(id))
diff --git a/crates/benilla-formats/src/lock.rs b/crates/benilla-formats/src/lock.rs
index 734fcddc..69478d79 100644
--- a/crates/benilla-formats/src/lock.rs
+++ b/crates/benilla-formats/src/lock.rs
@@ -1,21 +1,10 @@
-//! Lock.dbc — the requirements a lockable GameObject (or item) carries (decision 0239). A
-//! GameObject's template `lockId` (a type-specific slot of its query `data[]`) indexes this table;
-//! each lock has up to 8 requirement **slots**. Interacting with a locked object casts a *known*
-//! spell whose `SPELL_EFFECT_OPEN_LOCK` `EffectMiscValue` matches a **skill** slot's `LockType`
-//! index (mining / herbalism / lockpicking), or consumes the **item** slot's key. A `lockId` of 0,
-//! or a row whose every slot is empty, means "no lock" — the object opens by `CMSG_GAMEOBJ_USE`
-//! instead of a cast (the split the RE pinned; see `wow-5875-re` cursor-system.md §8).
+//! `Lock.dbc`: the requirements of a lockable GameObject or item, up to 8 slots per lock. Opening
+//! casts a known spell whose `SPELL_EFFECT_OPEN_LOCK` `EffectMiscValue` matches a skill slot's
+//! `LockType` index, or uses an item slot's key. A `lockId` of 0, or a row of empty slots, is no
+//! lock: the object opens by `CMSG_GAMEOBJ_USE` instead (the use handler `0x5f33e0`).
 //!
-//! Layout verified against build 5875 (mangos `LockEntry`, `DBCStructure.h`, and the RE's
-//! `[lockRec+0x24]` = `Index[0]` = column 9): **33 fields** — `ID@0`, `Type[8]@1..8`,
-//! `Index[8]@9..16`, `Skill[8]@17..24`, `Action[8]@25..32`.
-//!
-//! **`Action` is a gate, not a label** (decision 0752). Before the client's lock resolver
-//! (`0x5f83d0`) will even *consider* a slot, it asks `0x5f81d0(gameObject, Action[i])` — a
-//! predicate over the GameObject's own **state** and its `GO_FLAG_LOCKED` wire bit. See
-//! [`LockSlot::available`]. Skipping it is why "any locked door opens on right-click": nearly every
-//! keyed door in 5875 carries a spare `Quick Open` slot with `Action = 0`, and Action 0 means
-//! *"only when the object is NOT flagged locked"*.
+//! 33 fields: `ID`, `Type[8]`, `Index[8]`, `Skill[8]`, `Action[8]` (vmangos `LockEntry`; the
+//! reference reads `Index[0]` at `[lockRec+0x24]`, `0x5f84af`).
 
 use std::collections::HashMap;
 
@@ -26,70 +15,58 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 use crate::dbc::{parse, u32_at};
 
 const LOCK: &str = "DBFilesClient\\Lock.dbc";
-/// The file's column count (must equal the DBC header `field_count` — `benilla-dbc` enforces it).
+/// The column count, which `benilla-dbc` checks against the header.
 const LOCK_FIELDS: usize = 33;
 /// A lock has up to 8 requirement slots (`MAX_LOCK_CASE`).
 pub const MAX_LOCK_SLOTS: usize = 8;
 
-/// `Lock.dbc` `Type[i]` — a slot's key kind (mangos `LockKeyType`).
+/// `Type[i]`, a slot's key kind (vmangos `LockKeyType`): an empty slot.
 pub const LOCK_KEY_NONE: u32 = 0;
-/// The slot is opened by holding a **key item**; `LockSlot::index` is that item's entry.
+/// A key-item slot; `LockSlot::index` is the item's entry.
 pub const LOCK_KEY_ITEM: u32 = 1;
-/// The slot is opened by a **skill** (mining / herbalism / lockpicking); `LockSlot::index` is the
-/// `LockType.dbc` index the opener spell's `EffectMiscValue` must match, `LockSlot::skill` the
-/// required skill value.
+/// A skill slot; `LockSlot::index` is the `LockType.dbc` index the opening spell's
+/// `EffectMiscValue` must match, `LockSlot::skill` the skill value it needs.
 pub const LOCK_KEY_SKILL: u32 = 2;
 
-/// One of a lock's up-to-8 requirement slots. An all-zero slot is empty (unused).
+/// One requirement slot; an all-zero slot is empty.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub struct LockSlot {
-    /// `LOCK_KEY_NONE` / `LOCK_KEY_ITEM` / `LOCK_KEY_SKILL`.
+    /// `LOCK_KEY_NONE`, `LOCK_KEY_ITEM` or `LOCK_KEY_SKILL`.
     pub key_type: u32,
-    /// Key item entry (ITEM) or `LockType` index (SKILL); `0` when empty.
+    /// Key item entry (item) or `LockType` index (skill); 0 when empty.
     pub index: u32,
-    /// Required skill value (SKILL slots); `0` otherwise — and `0` does **not** mean "free": the
-    /// client substitutes `GAMEOBJECT_LEVEL × 5` for it (`0x5f84be`).
+    /// The skill value a skill slot needs. 0 is not free: the reference substitutes
+    /// `GAMEOBJECT_LEVEL * 5` (`0x5f84be`).
     pub skill: u32,
-    /// `Action[i]` — which *operation* this slot performs, and the gate on when it applies.
-    /// See [`LockSlot::available`].
+    /// The slot's operation, which gates when it applies ([`LockSlot::available`]).
     pub action: u32,
 }
 
-/// `GAMEOBJECT_STATE` (vmangos `GOState`) — the client mirrors it at `go+0x27c` and every gate
-/// below reads that mirror, not the wire (a chest's lid is opened client-side, so the two differ).
+/// `GAMEOBJECT_STATE` (vmangos `GOState`). The gates read the client's mirror at `go+0x27c`, not
+/// the wire: a chest's lid opens client-side, so the two differ.
 pub const GO_STATE_ACTIVE: u32 = 0;
 pub const GO_STATE_READY: u32 = 1;
 pub const GO_STATE_ACTIVE_ALTERNATIVE: u32 = 2;
 
 impl LockSlot {
-    /// Whether this slot applies to a GameObject right now — the client's per-slot gate
-    /// **`0x5f81d0(this = GO, Action[i])`**, byte-transcribed (decision 0752). Both legs of the
-    /// lock resolver `0x5f83d0` call it (`0x5f8450` for a SKILL slot, `0x5f8547` for a KEY slot)
-    /// and **skip the slot** when it answers false, so a gated-out slot can neither satisfy the
-    /// lock nor be opened.
-    ///
-    /// `go_state` is the client's stored state (`go+0x27c`, our `GoAnim::state`); `flag_locked` is
-    /// `GAMEOBJECT_FLAGS & GO_FLAG_LOCKED (0x2)`. The `Action` values are operations:
+    /// Whether this slot applies to a GameObject now: the reference's per-slot gate `0x5f81d0`.
+    /// Both legs of the lock resolver `0x5f83d0` skip a slot it refuses (`0x5f8450` for a skill
+    /// slot, `0x5f8547` for a key), so that slot can neither satisfy the lock nor open it.
+    /// `go_state` is the client's stored state (`go+0x27c`); `flag_locked` is `GO_FLAG_LOCKED`
+    /// (`0x2`) in `GAMEOBJECT_FLAGS`.
     ///
     /// | Action | operation | applies when |
     /// |--------|-----------|--------------|
-    /// | 0 | open | state READY **and** `GO_FLAG_LOCKED` **clear** (`0x5f8212..0x5f8220`) |
-    /// | 1 | unlock | state READY **and** `GO_FLAG_LOCKED` **set** (`0x5f822d..0x5f823a`) |
-    /// | 2 | close | state ACTIVE (`0x5f8247`) |
-    /// | 3 | (state-only) | state READY |
-    /// | 4 | (alt-state) | state ALTERNATIVE (`0x5f81ff`) |
-    /// | other | — | any state but ALTERNATIVE |
+    /// | 0 | open | READY and `GO_FLAG_LOCKED` clear (`0x5f8212`-`0x5f8220`) |
+    /// | 1 | unlock | READY and `GO_FLAG_LOCKED` set (`0x5f822d`-`0x5f823a`) |
+    /// | 2 | close | ACTIVE (`0x5f8247`) |
+    /// | 3 | | READY |
+    /// | 4 | | ALTERNATIVE (`0x5f81ff`) |
+    /// | other | | any state but ALTERNATIVE |
     ///
-    /// ALTERNATIVE (2) blocks every action but 4 (`0x5f81e1`).
-    ///
-    /// **This is the whole of the "any locked door opens on right-click" report.** The keyed doors
-    /// (Scholomance 1159, Shadowforge 680, Stratholme 879, SM 299, Deadmines 202 …) each carry a
-    /// spare `Quick Open` SKILL slot — `LockType 10`, `Skill 0`, **`Action 0`** — and *every*
-    /// character knows spell 6247 "Opening", which opens LockType 10 with an effect value of 100.
-    /// Without this gate that slot satisfies the lock and the door opens. With it, Action 0 is
-    /// refused the moment `GO_FLAG_LOCKED` is set — which every one of those doors sets. The
-    /// Searing Gorge gate (lock 84) was the reporter's counter-example precisely because it has no
-    /// `Action 0` slot at all: only the key (Action 1) and Pick Lock (Action 1).
+    /// ALTERNATIVE blocks every action but 4 (`0x5f81e1`). Without this gate a locked door opens
+    /// on right-click: keyed doors carry a spare Quick Open skill slot (`LockType` 10, skill 0,
+    /// Action 0) that spell 6247, Opening, which every character knows, satisfies.
     pub fn available(&self, go_state: u32, flag_locked: bool) -> bool {
         if self.action == 4 {
             return go_state == GO_STATE_ACTIVE_ALTERNATIVE;
@@ -109,30 +86,27 @@ impl LockSlot {
     }
 }
 
-/// `lockId → its 8 requirement slots`, from Lock.dbc.
+/// `lockId` to its 8 requirement slots.
 pub struct LockCatalog {
     locks: HashMap<u32, [LockSlot; MAX_LOCK_SLOTS]>,
 }
 
 impl LockCatalog {
-    /// Build a catalog from explicit rows — tests and tools; the game path is
-    /// [`load_lock_catalog`].
+    /// A catalog from explicit rows, for tests and tools.
     pub fn from_rows(rows: impl IntoIterator<Item = (u32, [LockSlot; MAX_LOCK_SLOTS])>) -> Self {
         Self {
             locks: rows.into_iter().collect(),
         }
     }
 
-    /// The 8 requirement slots for a `lockId`, or `None` if the id isn't in the table (treat as no
-    /// lock). A returned row may still be all-empty — [`LockCatalog::is_locked`] is the "must cast"
-    /// test.
+    /// A `lockId`'s slots; an absent id is no lock, and a row may still be all empty:
+    /// [`LockCatalog::is_locked`] is the must-cast test.
     pub fn slots(&self, lock_id: u32) -> Option<&[LockSlot; MAX_LOCK_SLOTS]> {
         self.locks.get(&lock_id)
     }
 
-    /// Whether a `lockId` names a real lock (present, with at least one non-empty slot) — i.e. the
-    /// object opens by a cast, not `CMSG_GAMEOBJ_USE`. A `0` id or an absent/all-empty row is "no
-    /// lock".
+    /// Whether the object opens by a cast rather than `CMSG_GAMEOBJ_USE`: a present row with at
+    /// least one non-empty slot.
     pub fn is_locked(&self, lock_id: u32) -> bool {
         lock_id != 0
             && self
@@ -158,7 +132,7 @@ fn schema() -> Schema {
     s
 }
 
-/// Load Lock.dbc from the patch chain into a [`LockCatalog`].
+/// Load `Lock.dbc` off the patch chain.
 pub fn load_lock_catalog(chain: &mut Chain) -> Result<LockCatalog> {
     let bytes = chain
         .read_file(LOCK)
@@ -183,9 +157,6 @@ pub fn load_lock_catalog(chain: &mut Chain) -> Result<LockCatalog> {
 mod tests {
     use super::*;
 
-    /// The Type/Index/Skill column offsets on the real build-5875 `Lock.dbc` — a column slip fails
-    /// loudly. Anchors: Copper Vein (lockId 38, a Mining node) and Silverleaf (lockId 29, an
-    /// Herbalism node), both skill 1 — the lowest of their profession. Skips without client data.
     #[test]
     fn real_lock_catalog_reads_skill_slots() {
         let data = crate::wow_data_or_skip!();
@@ -193,11 +164,8 @@ mod tests {
         let cat = load_lock_catalog(&mut chain).expect("load Lock.dbc");
         assert!(!cat.is_empty(), "Lock.dbc parsed empty");
 
-        // Copper Vein (gameobject_template 1731, chest.data0 = lockId 38): a MINING skill lock. The
-        // real row is `{Type[0]=2 SKILL, Index[0]=3 (Mining LockType), Skill[0]=0}` — `Type[0]` at
-        // col 1, `Index[0]` at col 9, `Skill[0]` at col 17; a column slip lands elsewhere. (Lock.dbc
-        // stores 0 in `Skill` for gathering nodes — the profession *spell* is the gate, not a value
-        // here; the server enforces the node's grey level.)
+        // Copper Vein (gameobject 1731, lock 38), Mining: `Type[0]` 2 at column 1, `Index[0]` 3 at
+        // column 9, and `Skill[0]` 0 at column 17, as on every gathering node.
         let vein = cat.slots(38).expect("lockId 38 (Copper Vein)");
         assert_eq!(
             vein[0].key_type, LOCK_KEY_SKILL,
@@ -217,8 +185,7 @@ mod tests {
             "a mining vein is a real lock (must cast, not USE)"
         );
 
-        // Silverleaf (gameobject_template 1617, lockId 29): an HERBALISM skill lock — LockType index
-        // 2, distinct from mining's 3.
+        // Silverleaf (gameobject 1617, lock 29), a Herbalism lock: `LockType` index 2.
         let herb = cat.slots(29).expect("lockId 29 (Silverleaf)");
         assert_eq!(
             herb[0].key_type, LOCK_KEY_SKILL,
@@ -227,14 +194,11 @@ mod tests {
         assert_eq!(herb[0].index, 2, "Herbalism is LockType index 2");
         assert_ne!(herb[0].index, vein[0].index, "herbalism ≠ mining LockType");
 
-        // A lockId of 0 is never a lock (opens by USE, not a cast).
         assert!(!cat.is_locked(0));
     }
 
-    /// The keyless-chest path: lockId 43 (Sunken Chest, Storage Chest, Worn Wooden Chest, …) is a
-    /// single SKILL slot naming LockType **13** — the one spell 6478 "Opening" opens, and "Opening"
-    /// is a default-known player spell, so any character can loot these. Confirms the routing matches
-    /// keyless chests (not just gathering nodes) to a spell the player already has. Skips without data.
+    /// Lock 43, the keyless chests: one skill slot naming `LockType` 13, which spell 6478, Opening,
+    /// known to every character, opens.
     #[test]
     fn real_lock_catalog_reads_keyless_chest() {
         let data = crate::wow_data_or_skip!();
@@ -246,32 +210,27 @@ mod tests {
             cat.is_locked(43),
             "even a keyless chest is a real lock (cast, not USE)"
         );
-        // The requirement sits in slot 1 here (slot 0 empty) — the routing must scan all 8 slots,
-        // not just slot 0. LockType 13 = the "Opening" the default spell 6478 provides.
+        // The requirement sits in slot 1, slot 0 empty: the routing must scan all 8 slots.
         assert_eq!(chest[1].key_type, LOCK_KEY_SKILL);
         assert_eq!(
             chest[1].index, 13,
             "the keyless-chest LockType spell 6478 opens"
         );
-        // …and it is an `Action 0` (open) slot, so it applies only to an unflagged object: the
-        // chest opens because chests do NOT carry GO_FLAG_LOCKED, not because Action is ignored.
+        // An Action 0 slot: the chest opens because chests carry no `GO_FLAG_LOCKED`.
         assert_eq!(chest[1].action, 0);
         assert!(chest[1].available(GO_STATE_READY, false));
         assert!(!chest[1].available(GO_STATE_READY, true));
     }
 
-    /// The `Action` column on the real 5875 `Lock.dbc`, on the two rows the "any locked door opens"
-    /// report turns on (decision 0752). A column slip here re-opens the bug silently, so both rows
-    /// are pinned by value. Skips without client data.
+    /// The `Action` column pinned by value on two door rows: a slip would let locked doors open.
     #[test]
     fn real_lock_catalog_reads_the_action_column() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_lock_catalog(&mut chain).expect("load Lock.dbc");
 
-        // Scholomance Door (gameobject_template 174626, door.data1 = lockId 1159; wire flags 34 =
-        // GO_FLAG_LOCKED|NODESPAWN). Five slots: the Skeleton Key, Pick Lock 280, and the three
-        // spares — `Quick Open`/`Quick Close`/`Blasting`.
+        // Scholomance Door (gameobject 174626, lock 1159, flags 34: `GO_FLAG_LOCKED | NODESPAWN`):
+        // the Skeleton Key, Pick Lock 280, and the spares Quick Open, Quick Close and Blasting.
         let scholo = cat.slots(1159).expect("lockId 1159 (Scholomance Door)");
         assert_eq!(
             (scholo[0].key_type, scholo[0].index, scholo[0].action),
@@ -298,9 +257,8 @@ mod tests {
             (LOCK_KEY_SKILL, 10, 0, 0),
             "slot 2 = Quick Open, no skill, Action 0 (open) — THE bug's slot"
         );
-        // The gate: on a GO_FLAG_LOCKED door, the Quick Open slot does not apply — so the
-        // universally-known "Opening" (6247) never gets to satisfy it. The key and Pick Lock legs
-        // do apply, which is exactly the pair the reference asks the player for.
+        // On a locked door Quick Open does not apply, so spell 6247 cannot satisfy it; the key and
+        // Pick Lock do.
         assert!(
             !scholo[2].available(GO_STATE_READY, true),
             "Quick Open is gated out by the flag"
@@ -314,9 +272,7 @@ mod tests {
             "Pick Lock still applies"
         );
 
-        // The Searing Gorge gate (gameobject_template 150137/150138, lockId 84) — the reporter's
-        // counter-example, and the reason the bug looked like "almost all doors". It carries no
-        // Action-0 slot at all, so it refused even before the gate existed.
+        // The Searing Gorge gate (gameobject 150137 and 150138, lock 84) has no Action 0 slot.
         let gorge = cat.slots(84).expect("lockId 84 (Searing Gorge gate)");
         assert_eq!(
             (gorge[0].key_type, gorge[0].index, gorge[0].action),
@@ -348,22 +304,17 @@ mod tests {
             skill: 0,
             action,
         };
-        // Action 0 (open): READY + not flagged locked.
         assert!(slot(0).available(GO_STATE_READY, false));
         assert!(!slot(0).available(GO_STATE_READY, true));
         assert!(!slot(0).available(GO_STATE_ACTIVE, false));
-        // Action 1 (unlock): READY + flagged locked — the exact mirror.
         assert!(slot(1).available(GO_STATE_READY, true));
         assert!(!slot(1).available(GO_STATE_READY, false));
         assert!(!slot(1).available(GO_STATE_ACTIVE, true));
-        // Action 2 (close): only while ACTIVE, flag irrelevant.
         assert!(slot(2).available(GO_STATE_ACTIVE, false));
         assert!(slot(2).available(GO_STATE_ACTIVE, true));
         assert!(!slot(2).available(GO_STATE_READY, false));
-        // Action 3: READY, flag irrelevant.
         assert!(slot(3).available(GO_STATE_READY, true));
         assert!(!slot(3).available(GO_STATE_ACTIVE, false));
-        // Action 4 is the ONLY action an ALTERNATIVE-state object admits, and it admits nothing else.
         assert!(slot(4).available(GO_STATE_ACTIVE_ALTERNATIVE, false));
         assert!(!slot(4).available(GO_STATE_READY, false));
         for action in [0, 1, 2, 3, 5, 19] {
@@ -372,7 +323,6 @@ mod tests {
                 "action {action} must not apply in the ALTERNATIVE state"
             );
         }
-        // An unmodelled action (≥5) falls through to "applies", in any state but ALTERNATIVE.
         assert!(slot(5).available(GO_STATE_ACTIVE, false));
         assert!(slot(5).available(GO_STATE_READY, true));
     }
diff --git a/crates/benilla-formats/src/lock_type.rs b/crates/benilla-formats/src/lock_type.rs
index 3ed64738..edccb34c 100644
--- a/crates/benilla-formats/src/lock_type.rs
+++ b/crates/benilla-formats/src/lock_type.rs
@@ -1,22 +1,8 @@
-//! LockType.dbc — the small table that names a lock's *interaction kind* (Herbalism, Mining, Pick
-//! Lock, Fishing, …), and — for the three that carry one — the **cursor** the client shows when you
-//! hover a GameObject wearing that lock (decision 0236; wow-re cursor-system.md §4/§4a). The world
-//! cursor's GameObject branch resolves a base-type GO's cursor by data: the GO template's `lockId` →
-//! [`crate::LockCatalog`] row → its **first** requirement slot's `LockType` index → *this* table's
-//! **CursorName** column. A non-empty CursorName (only `PickLock`/`GatherHerbs`/`Mine` in 5875) names
-//! the cursor BLP directly; an empty one (every other lock kind — a plain chest, a door, fishing)
-//! falls through to the generic **Interact** gear. `LockType.Id == 1` (Pick Lock) is additionally the
-//! "never grayed" case the classifier special-cases.
-//!
-//! The localized **Name** block (`Name@1..8` + flags, enUS at field 1 — `[lockTypeRow + locale*4 +
-//! 4]`, the exact read the lock-refusal toast performs at `0x5f34f9`) is the word the client fills
-//! into the client-local "Requires %s" error for an unopenable skill lock — "Requires Herbalism" /
-//! "Requires Mining" (wow-re cursor-system.md §8.8, decision 0545).
-//!
-//! Layout verified against build 5875 (byte-checked live: 19 records × 29 fields, record size 116):
-//! `ID@0`, then the localized `Name` block, and **`CursorName@28`** (`[lockTypeRow+0x70]`, the exact
-//! offset the RE pinned). Every field is 4 bytes, so the intervening columns are read as `UInt32`
-//! filler — only `ID`, `Name` (enUS), and `CursorName` are consumed here.
+//! `LockType.dbc`, a lock's interaction kind (Herbalism, Mining, Pick Lock, Fishing): its name and,
+//! for three kinds, the cursor shown over a GameObject wearing it (`0x5f3070`). The GO cursor
+//! resolves by data: template `lockId` → [`crate::LockCatalog`] row → its first slot's `LockType`
+//! index → `CursorName`, which names the cursor BLP, or when empty falls through to the Interact
+//! gear. `LockType` 1 (Pick Lock) is also the classifier's never-grayed case.
 
 use std::collections::HashMap;
 
@@ -27,36 +13,28 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 use crate::dbc::{parse, str_at, u32_at};
 
 const LOCK_TYPE: &str = "DBFilesClient\\LockType.dbc";
-/// The file's column count (must equal the DBC header `field_count` — `benilla-dbc` enforces it).
+/// The file's column count, which `benilla-dbc` checks against the header.
 const LOCK_TYPE_FIELDS: usize = 29;
-/// The **CursorName** column (`[lockTypeRow+0x70]` = field 28, VERIFIED both by the RE offset and by
-/// a live byte-dump of the 5875 file).
+/// `CursorName`, the `[row+0x70]` that `0x5f3070` reads.
 const CURSOR_NAME_FIELD: usize = 28;
-/// The localized **Name** block's enUS column (field 1 — the toast's `[lockTypeRow + locale*4 + 4]`
-/// with locale 0).
+/// The `Name` block's enUS column, the toast's `[row + locale*4 + 4]` at locale 0.
 const NAME_FIELD: usize = 1;
 
-/// `LockType.Id → CursorName` for the rows that carry one — the data half of the GameObject cursor —
-/// plus every row's localized `Name` (the lock-refusal toast's "Requires %s" fill).
-/// Only the three interaction kinds with a distinct cursor keep one (`PickLock`/`GatherHerbs`/`Mine`);
-/// every other row's CursorName is empty and simply absent here (→ the generic Interact gear).
+/// `LockType.Id` → `CursorName` for the three rows with one, plus every row's `Name`.
 pub struct LockTypeCatalog {
     cursors: HashMap<u32, String>,
     names: HashMap<u32, String>,
 }
 
 impl LockTypeCatalog {
-    /// The `Interface\Cursor\<name>.blp` stem for a `LockType` index, or `None` when that lock kind
-    /// carries no distinct cursor (→ the caller falls back to the Interact gear). The index is the
-    /// value the client reads straight out of the lock row's first requirement slot; a value that
-    /// isn't a real LockType id (e.g. a key-item entry, or `0` for an empty slot) simply misses.
+    /// The `Interface\Cursor\<name>.blp` stem for a `LockType` index, `None` for the Interact
+    /// gear. The index is the lock's raw first slot, so a key item or an empty `0` simply misses.
     pub fn cursor_name(&self, lock_type_id: u32) -> Option<&str> {
         self.cursors.get(&lock_type_id).map(String::as_str)
     }
 
-    /// The localized `Name` of a lock kind ("Herbalism", "Mining", "Pick Lock", …) — the word the
-    /// lock-refusal toast fills into "Requires %s" (wow-re cursor-system.md §8.8; the client falls
-    /// back to the literal `"UNKNOWN"` when the row is missing — that fallback is the caller's).
+    /// A lock kind's `Name` ("Herbalism"), filled into "Requires %s" (`0x5f34f9`); the caller
+    /// supplies the reference's `"UNKNOWN"` for a missing row.
     pub fn name(&self, lock_type_id: u32) -> Option<&str> {
         self.names.get(&lock_type_id).map(String::as_str)
     }
@@ -73,8 +51,7 @@ impl LockTypeCatalog {
 fn schema() -> Schema {
     let mut s = Schema::new("LockType");
     for i in 0..LOCK_TYPE_FIELDS {
-        // Only ID(0), Name-enUS(1) and CursorName(28) are read; the rest are 4-byte filler
-        // (localization columns) declared UInt32 so the record size still matches the file header.
+        // The unread columns are 4-byte filler, declared so the record size matches the header.
         let ty = if i == CURSOR_NAME_FIELD || i == NAME_FIELD {
             FieldType::String
         } else {
@@ -85,7 +62,7 @@ fn schema() -> Schema {
     s
 }
 
-/// Load LockType.dbc from the patch chain into a [`LockTypeCatalog`].
+/// Load `LockType.dbc` from the patch chain into a [`LockTypeCatalog`].
 pub fn load_lock_type_catalog(chain: &mut Chain) -> Result<LockTypeCatalog> {
     let bytes = chain
         .read_file(LOCK_TYPE)
@@ -109,21 +86,17 @@ pub fn load_lock_type_catalog(chain: &mut Chain) -> Result<LockTypeCatalog> {
 mod tests {
     use super::*;
 
-    /// The three cursor-bearing rows on the real build-5875 `LockType.dbc`, byte-anchored: a column
-    /// slip (or an off-by-one on the CursorName offset) lands on empty/other columns and fails loudly.
-    /// Skips without client data.
+    /// The 5875 rows: a column slip lands on another column and fails.
     #[test]
     fn real_lock_types_name_their_cursors() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_lock_type_catalog(&mut chain).expect("load LockType.dbc");
 
-        // The full cursor-bearing set in 5875 — Pick Lock (1), Herbalism (2), Mining (3).
         assert_eq!(cat.cursor_name(1), Some("PickLock"));
         assert_eq!(cat.cursor_name(2), Some("GatherHerbs"));
         assert_eq!(cat.cursor_name(3), Some("Mine"));
-        // Every other lock kind (Open, Fishing, Disarm Trap, …) carries no cursor → Interact gear.
-        assert_eq!(cat.cursor_name(5), None); // Open (the keyless-chest LockType 13 is likewise blank)
+        assert_eq!(cat.cursor_name(5), None); // Open; 13 is the keyless chest
         assert_eq!(cat.cursor_name(13), None);
         assert_eq!(cat.cursor_name(19), None); // Fishing
         assert_eq!(cat.cursor_name(0), None); // an empty lock slot's index
@@ -133,8 +106,7 @@ mod tests {
             "only three LockType rows carry a CursorName in 5875"
         );
 
-        // The localized Name column — the lock-refusal toast's "Requires %s" fill (decision 0545).
-        // A column slip here would print e.g. "Requires Herbs" (ResourceName@10) on screen.
+        // A slip to `ResourceName` (field 10) would print "Requires Herbs".
         assert_eq!(cat.name(1), Some("Pick Lock"));
         assert_eq!(cat.name(2), Some("Herbalism"));
         assert_eq!(cat.name(3), Some("Mining"));
diff --git a/crates/benilla-formats/src/macro_icons.rs b/crates/benilla-formats/src/macro_icons.rs
index df1f1dd7..d5661ea2 100644
--- a/crates/benilla-formats/src/macro_icons.rs
+++ b/crates/benilla-formats/src/macro_icons.rs
@@ -1,70 +1,41 @@
-//! The **macro icon chooser's catalog** — the list `GetNumMacroIcons`/`GetMacroIconInfo` serve.
-//!
-//! Byte-derived from the reference client's `BuildMacroIconList` (`0x4f0090`); the full RE note is
-//! `wow-5875-re` `system/ui/scratch/macro-icon-chooser.md`. The headline: **the chooser does not
-//! read `SpellIcon.dbc`**. It enumerates the files that actually exist under `Interface\Icons\`.
+//! The macro icon chooser's catalog, the list `GetNumMacroIcons`/`GetMacroIconInfo` serve. The
+//! reference's `BuildMacroIconList` (`0x4f0090`) enumerates the files under `Interface\Icons\`; it
+//! does not read `SpellIcon.dbc`.
 
 use anyhow::Result;
 
 use crate::Chain;
 
-/// The directory the chooser enumerates — and, at `GetMacroIconInfo`, the prefix it splices back on
-/// (`0x84c988`, spliced by `SStrPrintf("%s%s", …)` at `0x4f1a8d`). 16 characters, which is the
-/// literal count the client strips when it stores an entry.
+/// The directory the chooser enumerates and the prefix `GetMacroIconInfo` splices back on
+/// (`0x84c988`, at `0x4f1a8d`); the reference strips its 16 characters from each stored entry.
 const ICON_DIR: &str = "Interface\\Icons\\";
 
-/// The **macro icon chooser** list — every `Interface\Icons\` file whose name begins `Spell_` or
-/// `Ability_`, case-insensitively sorted and deduplicated, each as a full texture path.
+/// The chooser's list: every `Interface\Icons\` file whose name begins `Spell_` or `Ability_`,
+/// sorted and deduplicated without case, each as the full path `GetMacroIconInfo` returns.
 ///
-/// This is the *enumeration*, not a DBC scan, because that is what the client does
-/// (`BuildMacroIconList 0x4f0090`). It unions three sources: the `(listfile)` of every open
-/// `patch*.MPQ` plus `interface.MPQ` (name-table index 6, `0x82e12c`), read via `0x648fb0`; a disk
-/// scan of `SFileGetBasePath() + "Interface\Icons\"`; and a CWD-relative `Interface\Icons\` scan.
-/// We serve the archive half through [`Chain::list`] — a stock install has no loose `Interface\Icons`
-/// directory, so sources 2 and 3 contribute nothing and are not implemented. (They are how the
-/// reference lets a user drop a custom icon in; if we ever want that, it belongs here.)
-///
-/// Per entry the client keeps the name **after the 16-char prefix, with the extension stripped**,
-/// accepting only a last-dot extension in `{.blp, .tga}` and rejecting directories. It then
-/// `qsort`s case-insensitively (`0x4f0128`, comparator `0x4f05e0` = `SStrCmpI`) and adjacent-dedups
-/// walking down (`0x4f0140`–`0x4f01a4`) — so the dedup key is the whole stored name, folded for
-/// case, and `Foo.blp` beside `Foo.tga` collapses to one entry. **Sorted, not DBC row order**: the
-/// order the player scrolls is alphabetical.
-///
-/// We store the reassembled full path rather than the bare name. `GetMacroIconInfo` splices
-/// [`ICON_DIR`] back on anyway, so what Lua sees is identical, and every consumer here (the popup's
-/// `SetTexture`, `CreateMacro`'s saved texture) wants the whole path.
-///
-/// **Why this replaces a `SpellIcon.dbc` scan** (bug B221, decision 1053): the DBC names art that
-/// does not ship. Five of its chooser-eligible rows have no file under any name (`Ability_Temp`,
-/// `Spell_Holy_Invulnerable`, `Spell_Misc_Food_08`, `Spell_Orc_Omniscience`,
-/// `Ability_Hunter_BeastSooth`), and two more are malformed for a texture lookup
-/// (`Spells\Icon\Spell_Fire_Fire`, a different directory root; `Ability_Druid_Mangle.tga`, carrying
-/// a literal extension) — so the picker showed solid white cells where those landed. Enumerating
-/// the archive cannot produce a name with no file behind it: the defect class is gone by
-/// construction, not by an allow-list. On a stock 5875 install this yields **517** icons (the RE
-/// counts the same 517 off `patch.MPQ` 77 + `interface.MPQ` 443 = 520 raw, less 3 duplicate names).
+/// The reference unions the `(listfile)` of every open `patch*.MPQ` and `interface.MPQ` (name table
+/// index 6, `0x82e12c`, read via `0x648fb0`) with two loose-file scans of `Interface\Icons\`; only
+/// the archive half is built, as a stock install has no loose icons. Per entry it keeps the name
+/// after the prefix without a last-dot `.blp` or `.tga`, skipping directories, then `qsort`s with
+/// `SStrCmpI` (`0x4f0128`, comparator `0x4f05e0`) and drops adjacent duplicates
+/// (`0x4f0140`-`0x4f01a4`): the order is alphabetical, and a stock 5875 install yields 517 icons.
 pub fn load_macro_icons(chain: &mut Chain) -> Result<Vec<String>> {
     let mut names: Vec<String> = Vec::new();
     for entry in chain.list()? {
         let path = entry.name.replace('/', "\\");
-        // The prefix test is case-insensitive (`SStrCmpI`), as is everything else here: archive
-        // listfiles are not consistently cased.
+        // Case-insensitive (`SStrCmpI`), as listfiles are not consistently cased.
         if path.len() <= ICON_DIR.len()
             || !path.as_bytes()[..ICON_DIR.len()].eq_ignore_ascii_case(ICON_DIR.as_bytes())
         {
             continue;
         }
         let file = &path[ICON_DIR.len()..];
-        // Directories are rejected on `flags & 0x10`; the listfile's equivalent is a name that is
-        // still a path, i.e. anything in a SUBdirectory of Interface\Icons.
+        // The reference skips directories (`flags & 0x10`): here, a name in a subdirectory.
         if file.contains('\\') {
             continue;
         }
-        // Extension = the LAST dot, and only `.blp`/`.tga` are icons. `Foo.tga.blp` therefore
-        // stores as `Foo.tga` — which is exactly the entry that makes the reference's own picker
-        // carry an `Ability_Druid_Mangle.tga` beside `Ability_Druid_Mangle`… except that both
-        // resolve to the same art, so the CI dedup below cannot collapse them and both are shown.
+        // The last dot starts the extension, so `Foo.tga.blp` stores as `Foo.tga`: the reference's
+        // picker shows `Ability_Druid_Mangle.tga` beside `Ability_Druid_Mangle`.
         let Some((stem, ext)) = file.rsplit_once('.') else {
             continue;
         };
@@ -78,8 +49,7 @@ pub fn load_macro_icons(chain: &mut Chain) -> Result<Vec<String>> {
             names.push(stem.to_string());
         }
     }
-    // `qsort` by `SStrCmpI`, then adjacent-dedup walking down — the client's own two steps, in its
-    // own order (sorting first is what makes a single adjacent pass a complete dedup).
+    // Sort without case, then drop adjacent duplicates: the reference's two steps, in its order.
     names.sort_by_key(|n| n.to_ascii_lowercase());
     names.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
     Ok(names
diff --git a/crates/benilla-formats/src/maps.rs b/crates/benilla-formats/src/maps.rs
index 006dc44c..5bf7b94b 100644
--- a/crates/benilla-formats/src/maps.rs
+++ b/crates/benilla-formats/src/maps.rs
@@ -1,17 +1,6 @@
-//! Map.dbc loader: resolves a server-side `mapId` to its **MPQ directory name** (`0` →
-//! `"Azeroth"`, `1` → `"Kalimdor"`, `36` → `"DeadminesInstance"`, …) so the cross-map teleport
-//! handler can call `MapTiles::load(chain, dir)` for the new world.
-//!
-//! Layout — VERIFIED against build 5875 (`xxd` on extracted `DBFilesClient\Map.dbc`,
-//! 2026-05-29; field 38 confirmed 2026-06-02): the WDBC header reports **44 records · 42 fields
-//! · 168 B/record**. Load-bearing for us: `ID` (0), `Directory` (1), and **`LoadingScreenID`
-//! (38)** — an FK into `LoadingScreens.dbc` (see [`crate::LoadingScreenCatalog`]) selecting the
-//! map's full-screen load art. Verified empirically: field 38 ∈ the LoadingScreens id-set for 39
-//! of 44 maps (the 5 zeros are dev/test maps), with exact known pairs (mapId 0 `Azeroth` → 4,
-//! mapId 1 `Kalimdor` → 3, `DeadminesInstance` → 142). The remaining dwords are `MapName_loc`
-//! (9), `MapDescription0_loc` (9), `MapDescription1_loc` (9), plus a few ints we don't need.
-//! Reading them as `UInt32` placeholders is fine — DBC fields are 4 bytes regardless of declared
-//! type, so the schema only has to add up to 42 × 4 = 168.
+//! `Map.dbc`: a server `mapId` to its MPQ directory (`0` "Azeroth", `1` "Kalimdor", `36`
+//! "DeadminesInstance") for `MapTiles::load`, plus the columns the client reads per map. Records
+//! are 42 four-byte fields; `MapName` and the two descriptions are localized blocks of nine.
 
 use std::collections::HashMap;
 
@@ -23,72 +12,55 @@ use crate::dbc::{f32_at, parse, str_at, u32_at};
 
 const MAP: &str = "DBFilesClient\\Map.dbc";
 
-/// Field index of the `LoadingScreenID` FK (see module docs). 0 means "no art" (dev/test maps).
+/// Field index of `LoadingScreenID`, a `LoadingScreens.dbc` id; 0 on the dev and test maps.
 const LOADING_SCREEN_FIELD: usize = 38;
 
-/// Resolved per-map data, built once at startup off the client's Map.dbc.
+/// `Map.dbc`'s per-map data, keyed by map id.
 pub struct MapCatalog {
     dirs: HashMap<u32, String>,
-    /// `mapId → MapName_Lang[enUS]` (field 4, `+0x10` — the offset the binary's map-name reader
-    /// `0x4a65a0` uses against this same patch-2 layout). The world map's continent dropdown
-    /// displays THIS ("Eastern Kingdoms"), not the WorldMapArea art-folder string ("Azeroth") —
-    /// wow-re Q3 verdict, 2026-07-07.
+    /// `MapName_Lang[enUS]` (field 4, `+0x10`, read by `0x4a65a0`). The continent dropdown shows
+    /// this ("Eastern Kingdoms"), not the art folder ("Azeroth") (`GetMapContinents` `0x4a7ce0`).
     names: HashMap<u32, String>,
-    /// `mapId → LoadingScreenID` FK into `LoadingScreens.dbc` (only maps with a non-zero FK).
+    /// `LoadingScreenID`, for maps with a non-zero one.
     loading_screens: HashMap<u32, u32>,
-    /// `mapId → InstanceType` (field 2, `+0x8` — the offset the binary reads at `0x48a772`,
-    /// `0x495cb9` and `0x495d33`). VERIFIED by dumping the shipped patch-2 `Map.dbc`, 2026-08-30:
-    /// **0** none (Azeroth, Kalimdor, Deeprun Tram), **1** party dungeon (Deadmines, Scholomance),
-    /// **2** raid (Molten Core, Naxxramas), **3** battleground (Alterac Valley, Warsong Gulch) —
-    /// the same four the client's own `IsInInstance` string table spells `none`/`party`/`raid`/
-    /// `pvp` (`0x83de58`, indexed by this value with a `< 4` guard).
+    /// `InstanceType` (field 2, `+0x8`, read at `0x48a772`, `0x495cb9`, `0x495d33`): 0 none,
+    /// 1 party, 2 raid, 3 battleground, as `IsInInstance` spells them (`0x83de58`, guarded `< 4`).
     instance_types: HashMap<u32, u32>,
-    /// `mapId → ` the columns the battleground list and queue verbs read off the row
-    /// (see [`MapBattlegroundColumns`]) — every row, because the client resolves map 0 too.
+    /// The battleground columns of every row, since the client resolves map 0's too.
     battleground: HashMap<u32, MapBattlegroundColumns>,
 }
 
-/// The Map.dbc columns the client's battleground family reads by row offset (wow-re
-/// `battlefield-verb-family.md` §3.4, §3.6, §4.1, §5.2; decision 1974). Offsets are into the
-/// 168-byte record with the id at `+0x00`, so `+0x4·k` is field `k`. VERIFIED by dumping the
-/// shipped patch-2 `Map.dbc` (2026-09-04): Warsong Gulch `10, 60, 10, −1, (0, 0), span 10, group 1`;
-/// Arathi Basin `20, 60, 15, …, span 10, group 1`; Alterac Valley `51, 60, 40, −1, (0.74, 0.34),
-/// span 0, group 0`.
+/// The `Map.dbc` columns the battleground verbs read by row offset (`GetBattlefieldInfo`
+/// `0x4ab0b0`, the list handler `0x4aa6c0`); `+0x4·k` is field `k`.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct MapBattlegroundColumns {
-    /// Field 13 (`+0x34`) — the bracket base: the list and status handlers compute a bracket's
-    /// floor as `bracket · span + min_level` (§4.1). `GetBattlefieldInfo`'s third value.
+    /// Field 13 (`+0x34`), the bracket base and `GetBattlefieldInfo`'s third value.
     pub min_level: u32,
-    /// Field 14 (`+0x38`) — `GetBattlefieldInfo`'s fourth value.
+    /// Field 14 (`+0x38`), `GetBattlefieldInfo`'s fourth value.
     pub max_level: u32,
-    /// Field 15 (`+0x3c`) — the size a group join is checked against (`0x4a9f60`: both the party
-    /// count and the raid count must be `<=` this, else message 442 and nothing sent).
+    /// Field 15 (`+0x3c`): a group join needs both the party and the raid count `<=` this, else
+    /// message 442 and nothing sent (`0x4a9f60`).
     pub max_players: u32,
-    /// Field 16 (`+0x40`, signed) — `GetBattlefieldInfo`'s fifth value (`−1` on every shipped row).
+    /// Field 16 (`+0x40`, signed), `GetBattlefieldInfo`'s fifth value; `-1` on every battleground.
     pub field_16: i32,
-    /// Fields 17–18 (`+0x44`/`+0x48`, f32) — `GetBattlefieldInfo`'s sixth and seventh values.
+    /// Fields 17 and 18 (`+0x44`/`+0x48`, f32), `GetBattlefieldInfo`'s sixth and seventh values.
     pub field_17: f32,
     pub field_18: f32,
-    /// Fields 20 and 29 (`+0x50`, `+0x74`) — the two localized descriptions, indexed by the
-    /// client's faction-group index: `0` for a FactionTemplate mask with bit `0x4`, `1` for bit
-    /// `0x2` (§3.4). The shipped rows carry the SAME text in both, so nothing observable rides on
-    /// which side is which.
+    /// Fields 20 and 29 (`+0x50`, `+0x74`), the localized descriptions by faction-group index:
+    /// `0` for a `FactionTemplate` mask with bit `0x4`, `1` for bit `0x2` (`0x5efe00`).
     pub descriptions: [String; 2],
-    /// Field 39 (`+0x9c`) — the level-bracket span; `0` means one bracket and zeroed bounds.
+    /// Field 39 (`+0x9c`), the level-bracket span; `0` means one bracket and zeroed bounds.
     pub bracket_span: u32,
-    /// Field 40 (`+0xa0`) — non-zero when the battleground can be queued as a group
-    /// (`CanJoinBattlefieldAsGroup`, §3.6).
+    /// Field 40 (`+0xa0`), non-zero for a group queue (`CanJoinBattlefieldAsGroup` `0x4ac380`).
     pub group_queue: u32,
-    /// Field 41 (`+0xa4`, f32, the record's last) — `MinimapIconScale`, what
-    /// `GetBattlefieldMapIconScale()` answers for the active queue slot's map (wow-re
-    /// `worldmap-arrow-and-positions.md` §3.6; 1980). Shipped: `1.25` for Arathi Basin, `1.0`
-    /// for every other row read.
+    /// Field 41 (`+0xa4`, f32), `MinimapIconScale`: what `GetBattlefieldMapIconScale()` answers
+    /// for the active queue slot's map (`0x4ac3d0`).
     pub minimap_icon_scale: f32,
 }
 
 impl MapBattlegroundColumns {
-    /// The bracket's `(min, max)` for a wire bracket index (§4.1/§4.2): with a positive span,
-    /// `min = bracket · span + min_level` and `max = min(span + min − 1, 60)`; else both zero.
+    /// A wire bracket's `(min, max)` levels (`0x4aa6c0`/`0x4aa850`): with a span,
+    /// `min = bracket · span + min_level` and `max = min(span + min − 1, 60)`, else both zero.
     pub fn bracket_levels(&self, bracket: u8) -> (u32, u32) {
         if self.bracket_span == 0 {
             return (0, 0);
@@ -99,43 +71,33 @@ impl MapBattlegroundColumns {
 }
 
 impl MapCatalog {
-    /// MPQ directory name (the `Directory` column) for `map_id`, or `None` if the DBC has no
-    /// such row. Use with `MapTiles::load(chain, dir)`.
+    /// The MPQ directory name (`Directory`) for `map_id`, as `MapTiles::load(chain, dir)` takes it.
     pub fn directory(&self, map_id: u32) -> Option<&str> {
         self.dirs.get(&map_id).map(String::as_str)
     }
 
-    /// The localized display name (`MapName_Lang`, enUS) for `map_id` — "Eastern Kingdoms",
-    /// "Kalimdor", "The Deadmines", …
+    /// The enUS display name (`MapName_Lang`) for `map_id`, "Eastern Kingdoms".
     pub fn name(&self, map_id: u32) -> Option<&str> {
         self.names.get(&map_id).map(String::as_str)
     }
 
-    /// `LoadingScreenID` for `map_id` — the FK to resolve against [`crate::LoadingScreenCatalog`]
-    /// for the load-art BLP. `None` for dev/test maps that carry no screen. This is the same
-    /// mechanism for *every* map kind (open world, instance, battleground) — only the art row
-    /// differs.
+    /// `LoadingScreenID` for `map_id`, to resolve against [`crate::LoadingScreenCatalog`].
     pub fn loading_screen_id(&self, map_id: u32) -> Option<u32> {
         self.loading_screens.get(&map_id).copied()
     }
 
-    /// `InstanceType` for `map_id` (see [`MapCatalog::instance_types`]), or `None` for a map id
-    /// the DBC has no row for. The client treats a missing row as "not an instance" everywhere it
-    /// asks — it null-checks the record pointer first and takes the same branch as type 0.
+    /// `InstanceType` for `map_id`. The client treats a missing row as type 0 wherever it asks.
     pub fn instance_type(&self, map_id: u32) -> Option<u32> {
         self.instance_types.get(&map_id).copied()
     }
 
-    /// Whether `map_id` is a **party dungeon** (`InstanceType == 1`). This exact predicate — not
-    /// "is an instance" — is the one the reference's lockout bookkeeping runs on: `cmp [rec+8],1`
-    /// gates both what `SMSG_UPDATE_LAST_INSTANCE` records and both halves of
-    /// `CanShowResetInstances` (decision 1748).
+    /// Whether `map_id` is a party dungeon, the reference's lockout test rather than "is an
+    /// instance": `cmp [rec+8],1` gates `SMSG_UPDATE_LAST_INSTANCE` and `CanShowResetInstances`.
     pub fn is_party_dungeon(&self, map_id: u32) -> bool {
         self.instance_type(map_id) == Some(1)
     }
 
-    /// The battleground family's columns for `map_id` — every row has them (the client reads map
-    /// 0's when nothing was ever listed), `None` only for an id with no row.
+    /// The battleground columns for `map_id`; the client reads map 0's when nothing was listed.
     pub fn battleground(&self, map_id: u32) -> Option<&MapBattlegroundColumns> {
         self.battleground.get(&map_id)
     }
@@ -149,13 +111,10 @@ impl MapCatalog {
     }
 }
 
-/// Field index of the enUS `MapName_Lang` string (`+0x10`, see [`MapCatalog::names`]).
 const MAP_NAME_FIELD: usize = 4;
 
-/// Field index of `InstanceType` (`+0x8`, see [`MapCatalog::instance_types`]).
 const INSTANCE_TYPE_FIELD: usize = 2;
 
-/// The battleground family's columns (see [`MapBattlegroundColumns`]).
 const MIN_LEVEL_FIELD: usize = 13;
 const MAX_LEVEL_FIELD: usize = 14;
 const MAX_PLAYERS_FIELD: usize = 15;
@@ -168,10 +127,7 @@ const BRACKET_SPAN_FIELD: usize = 39;
 const GROUP_QUEUE_FIELD: usize = 40;
 const MINIMAP_ICON_SCALE_FIELD: usize = 41;
 
-/// 42 fields total; field 0 = ID, field 1 = Directory string, field 2 = InstanceType,
-/// field 4 = MapName (enUS), field 38 = LoadingScreenID (FK), plus the battleground columns
-/// ([`MapBattlegroundColumns`]). Remaining fields are placeholders (4-byte dwords; the schema only
-/// needs to total 168 B).
+/// The unread fields are `u32` placeholders: only the 42 × 4 = 168-byte record has to add up.
 fn map_schema() -> Schema {
     let mut s = Schema::new("Map");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -235,12 +191,10 @@ pub fn load_map_catalog(chain: &mut Chain) -> Result<MapCatalog> {
         if let Some(name) = str_at(&rs, r, MAP_NAME_FIELD).filter(|n| !n.is_empty()) {
             names.insert(id, name);
         }
-        // Every row's type is recorded, 0 included: "0" and "no such map" are different answers
-        // to `instance_type`, and the second is what a bad map id must give.
+        // Type 0 is recorded too, so `None` means only that no such map exists.
         if let Some(ty) = u32_at(r, INSTANCE_TYPE_FIELD) {
             instance_types.insert(id, ty);
         }
-        // 0 = "no loading screen" (dev/test maps); only record real FKs.
         if let Some(ls) = u32_at(r, LOADING_SCREEN_FIELD).filter(|&v| v != 0) {
             loading_screens.insert(id, ls);
         }
@@ -258,8 +212,6 @@ pub fn load_map_catalog(chain: &mut Chain) -> Result<MapCatalog> {
 mod tests {
     use super::*;
 
-    /// The battleground columns off the shipped patch-2 `Map.dbc`, and the bracket arithmetic the
-    /// list and status handlers run on them (wow-re `battlefield-verb-family.md` §4.1).
     #[test]
     fn the_battleground_columns_read_the_shipped_rows() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/material.rs b/crates/benilla-formats/src/material.rs
index ecc1e81d..e7777a05 100644
--- a/crates/benilla-formats/src/material.rs
+++ b/crates/benilla-formats/src/material.rs
@@ -1,24 +1,9 @@
-//! `Material.dbc` — the **armor foley**: the rustle a body makes as it moves, separate from the
-//! terrain footstep it lands on.
-//!
-//! A footfall is two sounds in the reference, not one. `$FSD` runs `0x623390`, whose *first* act
-//! after the three state gates is `call [vt+0x8c]` — the foley (`0x623610` for a unit,
-//! `0x62fa30` for a player) — and only then the terrain chain, which has gates of its own. So a
-//! creature whose footstep class is 0 still rustles, and the two sounds are on different buses
-//! (foley on the uncapped bus 0, the step on bus 9's cap of 6).
-//!
-//! Both foley paths converge on `0x4584e0`, which is this table: a `Material` **id** → the row's
-//! `+0x8` field → a `SoundEntries` kit, played positionally at the unit's feet **+2.0 yd**
-//! (`0x45851d fadd [0x801628]`) at volume 1.0.
-//!
-//! Layout — VERIFIED against the shipped build 5875 file (8 records × 3 fields × 12 B):
-//! `ID(0), Flags(1), FoleySoundID(2)`. The `+0x8` the binary reads is field 2 on a 12-byte
-//! record, and the `[row+4] & 1` flag test at `0x5d9a68` lands on field 1 — two independent
-//! offsets agreeing on the same three-column shape.
-//!
-//! **Only three of the eight materials make any sound**: chain (5) → 1005 `FoleySoundChain`,
-//! plate (6) → 1004 `FoleySoundPlate`, leather (8) → 1003 `FoleySoundLeather`. Metal, wood,
-//! liquid, jewelry and **cloth** carry 0 — a robed mage is silent, and that is data, not a gap.
+//! `Material.dbc`: the armor foley a body makes as it moves, and the flags behind weapon-impact
+//! sounds. A footfall is two sounds: `$FSD` (`0x623390`) plays the foley (`0x623610` for a unit,
+//! `0x62fa30` for a player) before the terrain step and its gates, so a creature of footstep class
+//! 0 still rustles; the foley is on the uncapped bus 0, the step on bus 9 (cap 6). `FoleySoundID`
+//! (row `+0x8`, read at `0x4584e0`) plays at the feet plus 2.0 yd (`0x45851d`, `[0x801628]`) at
+//! volume 1.0; only chain, plate and leather have one.
 
 use std::collections::HashMap;
 
@@ -31,43 +16,29 @@ use crate::Chain;
 /// `Material.dbc` keyed by id.
 pub struct MaterialCatalog {
     foley: HashMap<u32, u32>,
-    /// The `Flags` column — the *other* half of what this three-column table is for. It decides
-    /// the metal/wood split of every weapon impact ([`MaterialCatalog::is_metal`]) and, on a
-    /// player's chest, which armor slot the victim presents
-    /// ([`MaterialCatalog::armor_impact_slot`]).
+    /// The `Flags` column: the metal or wood side of a weapon impact and a chest's armor slot.
     flags: HashMap<u32, u32>,
 }
 
 impl MaterialCatalog {
-    /// The foley kit for a material id, or `None` when the material has no foley (five of the
-    /// eight shipped rows) or the id names no row. The reference's own two misses — a negative
-    /// id and an id past the table's max — land in the same place (`0x4584e6`/`0x4584ea`), so
-    /// callers need no sentinel of their own.
+    /// The foley kit for a material id; `None` for no foley or no row, where the reference's
+    /// negative and past-the-end misses (`0x4584e6`, `0x4584ea`) land too.
     pub fn foley_kit(&self, material: u32) -> Option<u32> {
         self.foley.get(&material).copied().filter(|&k| k != 0)
     }
 
-    /// Is this material **metal-bodied** — `Flags & 0x1`, the reference's `0x5d9a50`.
-    ///
-    /// It is the only thing that picks the metal vs wood half of `WeaponImpactSounds` (both the
-    /// weapon's own impact row and the victim's parry slot: `0x457e80` computes it, `0x457dc0`
-    /// asks it twice). The flag is set on metal (1), jewelry (4), chain (5) and plate (6) — so
-    /// it is genuinely "is this thing metal", not "is this thing not wood": leather, cloth and
-    /// liquid all read as non-metal, and so does an **unknown or absent material**, which is the
-    /// reference's answer for id 0 (no row) and the reason a guess of `material != WOOD` gets a
-    /// materialless creature weapon wrong.
+    /// Whether a material is metal-bodied, `Flags & 0x1` (`0x5d9a50`, tested at `0x5d9a68`): the
+    /// metal or wood half of `WeaponImpactSounds`, for the weapon's row and the parry slot
+    /// (`0x457e80`, asked twice by `0x457dc0`). Leather, cloth, liquid and an absent material
+    /// (id 0) are not metal, so this is not `material != WOOD`.
     pub fn is_metal(&self, material: u32) -> bool {
         self.flags.get(&material).is_some_and(|f| f & 0x1 != 0)
     }
 
-    /// The `WeaponImpactSounds` **target slot** a body wearing this material presents —
-    /// `0x62fb70`, the CGPlayer override of the victim's impact type, read off the same `Flags`
-    /// column: bit 1 → 2 (plate), else bit 2 → 1 (chain), else 0 (flesh).
-    ///
-    /// On the shipped table that is exactly plate → plate and chain → chain, with **leather and
-    /// cloth landing on flesh** — armor that does not ring. Creatures do not come through here:
-    /// their slot is a `CreatureSoundData` column remapped through `{0, 8, 7, 9}` (`0x6238f0`),
-    /// i.e. flesh/stone/wood/ethereal, a disjoint half of the same ten.
+    /// The `WeaponImpactSounds` target slot a player's chest material presents (`0x62fb70`):
+    /// `Flags` bit 1 gives 2 (plate), else bit 2 gives 1 (chain), else 0 (flesh), where leather and
+    /// cloth land. Creatures take theirs from `CreatureSoundData` through `{0, 8, 7, 9}`
+    /// (`0x6238f0`).
     pub fn armor_impact_slot(&self, material: u32) -> u32 {
         let Some(&flags) = self.flags.get(&material) else {
             return 0;
@@ -117,9 +88,8 @@ pub fn load_material_catalog(chain: &mut Chain) -> Result<MaterialCatalog> {
 mod tests {
     use super::*;
 
-    /// The shipped table, whose material ids are the same ones
-    /// `SMSG_ITEM_QUERY_SINGLE_RESPONSE` puts on the wire (1 metal · 2 wood · 5 chain · 6 plate ·
-    /// 7 cloth · 8 leather). Skips without client data.
+    /// The 5875 table, whose ids are the item query's materials (1 metal, 2 wood, 5 chain,
+    /// 6 plate, 7 cloth, 8 leather).
     #[test]
     fn real_materials_decode() {
         let data = crate::wow_data_or_skip!();
@@ -131,20 +101,19 @@ mod tests {
         assert_eq!(cat.foley_kit(6), Some(1004), "plate");
         assert_eq!(cat.foley_kit(8), Some(1003), "leather");
 
-        // Cloth is the load-bearing silence: a robe must not borrow leather's rustle.
+        // A robe must not borrow leather's rustle.
         assert_eq!(cat.foley_kit(7), None, "cloth");
         for quiet in [1, 2, 3, 4] {
             assert_eq!(cat.foley_kit(quiet), None, "material {quiet}");
         }
 
-        // Off the end of the table, and the "no material" id the wire sends for an empty slot.
+        // 0 is the wire's no-material id; 9 is past the table.
         assert_eq!(cat.foley_kit(0), None);
         assert_eq!(cat.foley_kit(9), None);
     }
 
-    /// The `Flags` column's two consumers, on the shipped table. **`is_metal` is not
-    /// `!= wood`**: leather and cloth are non-metal too, and so is a missing material — the case
-    /// a creature with no virtual-item info actually hits.
+    /// The `Flags` column on 5875; a missing material, as a creature without virtual-item info
+    /// has, is not metal.
     #[test]
     fn the_flags_column_splits_metal_and_names_the_armor_slot() {
         let data = crate::wow_data_or_skip!();
@@ -160,8 +129,6 @@ mod tests {
         assert!(!cat.is_metal(0), "an absent material is not metal");
         assert!(!cat.is_metal(99), "an unknown material is not metal");
 
-        // The armor slot a chest presents: plate rings as plate, chain as chain, everything
-        // else — leather and cloth included — as flesh.
         assert_eq!(cat.armor_impact_slot(6), 2, "plate");
         assert_eq!(cat.armor_impact_slot(5), 1, "chain");
         for flesh in [0, 1, 2, 3, 4, 7, 8, 99] {
diff --git a/crates/benilla-formats/src/minimap_translate.rs b/crates/benilla-formats/src/minimap_translate.rs
index aaeeffd3..d62803bd 100644
--- a/crates/benilla-formats/src/minimap_translate.rs
+++ b/crates/benilla-formats/src/minimap_translate.rs
@@ -1,21 +1,9 @@
-//! `textures\Minimap\md5translate.trs` — the minimap tile hash catalog: a plain-text index mapping
-//! each authored minimap tile name to the content-hashed filename actually stored under
-//! `textures\Minimap\` (Blizzard's dedup scheme — many tiles across zones/instances share one hash;
-//! decision 0203 phase 0).
-//!
-//! Format — VERIFIED against build 5875 (727 561 B, extracted via `benilla-extract` this session,
-//! 2026-07-07): CRLF-terminated text, 235 `dir: <Dir>` section headers, 8401 tab-separated data
-//! lines `<Dir>\<file>.blp\t<hash>.blp`. Every data line already repeats its full left-hand
-//! directory (checked exhaustively: all 8401 left-hand paths start, case-insensitively, with the
-//! preceding `dir:` header) — the header is cosmetic for parsing, so keying straight off the left
-//! column needs no header-tracking state. Two path shapes share the file and the same table,
-//! un-special-cased: **ADT tiles** (`<MapDir>\map<X>_<Y>.blp`, one per streamed terrain tile — e.g.
-//! `AhnQiraj\map27_46.blp`) and **WMO icon tiles** (`WMO\...\<name>_<n>_<row>_<col>.blp`, the
-//! minimap building-corner icons). All 8401 left-hand paths are unique case-insensitively.
-//!
-//! Verified example: `Azeroth\map32_48.blp → ea283abc0bf9637c3fad5e840a65b38b.blp`, and that hash is
-//! itself readable at `textures\Minimap\ea283abc0bf9637c3fad5e840a65b38b.blp` (decodes as a 256×256
-//! BLP2 — confirmed this session).
+//! `textures\Minimap\md5translate.trs`, the minimap tile index: each authored tile name to the
+//! content-hashed `.blp` stored under `textures\Minimap\`, tiles with the same art sharing a hash.
+//! CRLF text of `dir: <Dir>` headers and tab-separated `<Dir>\<file>.blp\t<hash>.blp` lines; every
+//! line repeats its full directory, so the headers are skipped. ADT tiles
+//! (`<MapDir>\map<X>_<Y>.blp`) and WMO interior tiles (`WMO\...\<name>_<group>_<X>_<Y>.blp`)
+//! share the table.
 
 use std::collections::HashMap;
 
@@ -27,26 +15,19 @@ const MD5_TRANSLATE: &str = "textures\\Minimap\\md5translate.trs";
 
 /// The parsed `md5translate.trs`: every left-hand path (lowercased) to its hashed `.blp` filename.
 pub struct MinimapTranslate {
-    /// `"<dir>\<file>.blp"` (lowercased) → the hashed filename on disk under `textures\Minimap\`
-    /// (e.g. `"ea283abc0bf9637c3fad5e840a65b38b.blp"`).
     entries: HashMap<String, String>,
 }
 
 impl MinimapTranslate {
-    /// The hashed minimap tile filename for `map_dir`'s ADT tile `(x, y)`, or `None` if this tile
-    /// was never authored (open ocean / unstreamed tiles have no minimap art). `map_dir` is
-    /// case-insensitive (MPQ path convention) — e.g. `tile("Azeroth", 32, 48)` resolves the
-    /// verified `ea283abc0bf9637c3fad5e840a65b38b.blp`. Join the result onto
-    /// `textures\Minimap\<hash>` to read the tile itself.
+    /// The hashed filename, under `textures\Minimap\`, of `map_dir`'s ADT tile `(x, y)` in any
+    /// case; `None` where no art was authored, as over open ocean.
     pub fn tile(&self, map_dir: &str, x: u32, y: u32) -> Option<&str> {
         let key = format!("{map_dir}\\map{x}_{y}.blp").to_ascii_lowercase();
         self.entries.get(&key).map(String::as_str)
     }
 
-    /// The hashed filename for an arbitrary logical tile path (case-insensitive, `\`-separated), or
-    /// `None` if unauthored — e.g. the WMO interior tiles
-    /// `wmo\KhazModan\Cities\Ironforge\ironforge_001_00_00.blp`. The ADT [`Self::tile`] is the
-    /// `map<x>_<y>` special case of this.
+    /// The hashed filename for any tile path (`\`-separated, any case), such as the WMO interior
+    /// tile `wmo\KhazModan\Cities\Ironforge\ironforge_001_00_00.blp`.
     pub fn get(&self, logical_path: &str) -> Option<&str> {
         self.entries
             .get(&logical_path.to_ascii_lowercase())
@@ -62,8 +43,7 @@ impl MinimapTranslate {
     }
 }
 
-/// Parse `md5translate.trs`'s text body (CRLF or LF line endings; a `dir:` header line is skipped
-/// — see the module doc, every data line already carries its full directory).
+/// Parse the text body, CRLF or LF, skipping the `dir:` headers.
 fn parse_trs(text: &str) -> HashMap<String, String> {
     let mut entries = HashMap::new();
     for raw in text.split('\n') {
@@ -115,8 +95,7 @@ mod tests {
         assert_eq!(cat.tile("Azeroth", 99, 99), None);
     }
 
-    /// Real chain: the verified Azeroth tile resolves, and the hashed file it names is itself
-    /// readable in the chain as a 256×256 BLP2. Skips without client data.
+    /// The 5875 file: an Azeroth tile resolves to a hash that reads as a 256×256 BLP.
     #[test]
     fn real_md5translate_resolves_azeroth_tile_and_hash_is_readable() {
         let data = crate::wow_data_or_skip!();
@@ -134,9 +113,8 @@ mod tests {
             crate::read_texture_rgba(&mut chain, &tile_path).expect("hashed tile decodes as BLP");
         assert_eq!((w, h), (256, 256));
 
-        // The WMO interior tile key format the minimap builds (`<stem>_<group>_<X>_<Y>.blp`, the
-        // stem being the `.wmo` path minus `World\` + extension) resolves case-insensitively against
-        // the real trs — the end-to-end link the interior renderer's tile lookup depends on.
+        // The interior key the minimap builds: the `.wmo` path without `World\` or extension,
+        // then `_<group>_<X>_<Y>.blp`.
         assert!(
             cat.get("wmo\\KhazModan\\Cities\\Ironforge\\ironforge_001_00_00.blp")
                 .is_some(),
diff --git a/crates/benilla-formats/src/models/anim.rs b/crates/benilla-formats/src/models/anim.rs
index dd42f83b..c0a5e574 100644
--- a/crates/benilla-formats/src/models/anim.rs
+++ b/crates/benilla-formats/src/models/anim.rs
@@ -1,68 +1,43 @@
-//! M2 skeleton + animation parsing (decision 0019): the rest skeleton (bones, parent + pivot) and
-//! every sequence's per-bone keyframe tracks, which the skinned-entity path turns into Bevy clips.
-//! Split out of the model parser as its own concern.
+//! M2 skeleton and animation parsing: the rest skeleton and each sequence's per-bone keyframes.
 
 use std::collections::HashMap;
 use std::io::Cursor;
 
 use anyhow::Result;
+use benilla_bytes::capped;
 use benilla_m2::parse_m2;
 
 use super::{le_f32, le_u16, le_u32};
 use crate::BoneSpin;
 
-/// One bone of a model's rest skeleton (decision 0019): its parent bone index (`-1` = root) and pivot
-/// point in **raw WoW model space** (the render boundary maps it to Bevy space). Vanilla M2 has no
-/// inverse-bind-matrix array — the rest pose is identity TRS and the **pivot encodes bind position**
-/// (VERIFIED wow-5875-re), so the skinned-entity path builds bone matrices pivot-relative up the chain.
+/// A rest-skeleton bone, raw WoW model space. Vanilla M2 has no inverse bind matrices: the rest
+/// pose is identity and the pivot is the bind position (`0x714260`).
 #[derive(Debug, Clone, Copy)]
 pub struct SkeletonBone {
     pub parent: i16,
     pub pivot: [f32; 3],
-    /// `KeyBoneID` (`-1` = none): 0/1 arms L/R, 2/3 shoulders L/R, … — the per-arm animation masks
-    /// find their subtree roots through it.
+    /// `KeyBoneID` (`-1` none; 0/1 left/right arm, 2/3 left/right shoulder, …): how the per-arm
+    /// masks find roots.
     pub key_bone: i16,
-    /// The bone's billboard arm (flags `0x08/0x10/0x20/0x40`), `None` for an ordinary bone — the
-    /// palette-level camera facing a rigged host applies per frame (children inherit it).
+    /// The billboard arm (flags `0x08/0x10/0x20/0x40`); children inherit it.
     pub billboard: Option<crate::BillboardKind>,
-    /// Bone flags `0x1/0x2/0x4` — how this bone's effective **parent matrix** is rebuilt from the
-    /// model's own root matrix before it composes (`None` for the ordinary bone). See
-    /// [`crate::ParentArm`]: the byte-verified `ignore parent translate / scale / rotate` trio.
-    /// Carried by 862 bones across 456 shipped models — the unskinned attach helpers
-    /// (HandArrow/Bullet: the nocked arrow lies flat along the facing instead of twisting with the
-    /// draw hand, wow-re `nocked-ammo-cancel.md` §E4) and, load-bearingly, **every vanilla player
-    /// mount's rider seat**, which is why a galloping horse's spine never rocks its rider.
+    /// Bone flags `0x1/0x2/0x4`: how the parent matrix is rebuilt ([`crate::ParentArm`]).
     pub parent_arm: Option<crate::ParentArm>,
 }
 
-/// A model's bone hierarchy — the rest skeleton the skinned-entity path turns into a joint-entity
-/// tree + inverse bind poses. Bones are in M2 file order; a vertex's `joints` index into this list.
-/// Empty for a boneless model.
+/// A model's bones in M2 file order, which a vertex's `joints` index.
 #[derive(Debug, Clone, Default)]
 pub struct Skeleton {
     pub bones: Vec<SkeletonBone>,
 }
 
 impl Skeleton {
-    /// The **billboard host** of `bone`: the index of the nearest bone at or above it in the parent
-    /// chain that authors a billboard arm (`bone` itself included), or `None` when the chain reaches
-    /// the root without one.
-    ///
-    /// This is the palette-level question, and the reason it has to be asked about ancestors and not
-    /// just the bone itself: a billboard bone's matrix ROWS are replaced with the camera basis about
-    /// its own pivot, and *`children multiply onto this`* (wow-re `billboard-bone-law.md`) — so every
-    /// descendant frame is camera-dependent even though only the ancestor carries the flag. Three
-    /// consumers ask it: a skinned vertex (which arm its geometry inherits), a **particle emitter**
-    /// (whose record position rides the replaced matrix — wow-re `part-anchoring-live-bone.md` §1
-    /// row 3), and a ribbon anchor.
-    ///
-    /// The nearest host is the whole answer: a nearer replacement discards the rows an outer one
-    /// wrote, and on a rest-pose chain the pivot-preserving translation rebuild reads the (identity)
-    /// pre-billboard matrix, so nothing above it survives either.
+    /// The nearest bone at or above `bone` with a billboard arm. Its rows become the camera basis
+    /// and children multiply onto it (`0x7151f9`), so every descendant is camera-dependent, emitter
+    /// positions too (`0x7190a9`); a nearer host discards what an outer one wrote.
     pub fn billboard_host(&self, bone: u16) -> Option<usize> {
         let mut i = usize::from(bone);
-        // Bounded by the bone count — M2 parents precede children, so this terminates on any
-        // well-formed file; the bound is the malformed-parent guard.
+        // Bounded by the bone count: the guard against a malformed parent cycle.
         for _ in 0..=self.bones.len() {
             let b = self.bones.get(i)?;
             if b.billboard.is_some() {
@@ -74,10 +49,7 @@ impl Skeleton {
     }
 }
 
-/// Parse the M2 bone hierarchy (parent + pivot per bone) into a [`Skeleton`]. Straight off
-/// `benilla-m2`'s bone parse (vanilla bone record stride 0x6c: parent i16 @+0x08, pivot C3 @+0x60,
-/// VERIFIED wow-5875-re). A separate byte-in entry point alongside [`parse_m2_render_submeshes`], so
-/// the asset loader builds the skeleton beside the meshes without changing that signature.
+/// Parse the bone hierarchy (stride `0x6c`: parent `+0x08`, pivot `+0x60`, as `0x714260` reads).
 pub fn parse_m2_skeleton(bytes: &[u8]) -> Result<Skeleton> {
     let format =
         parse_m2(&mut Cursor::new(bytes)).map_err(|e| anyhow::anyhow!("parsing M2: {e}"))?;
@@ -96,11 +68,7 @@ pub fn parse_m2_skeleton(bytes: &[u8]) -> Result<Skeleton> {
     Ok(Skeleton { bones })
 }
 
-/// One M2 attachment-point record (decision 0072 — held items): the attach id (`0` shield, `1`
-/// right hand, `2` left hand, sheath/hip/back pairs at `26..33`), the bone it rides, and its
-/// **raw WoW model-space** position (see `benilla_m2::M2Attachment` — the same shape, re-exposed
-/// here as the bytes-in entry point alongside [`parse_m2_skeleton`], so callers that only take
-/// `benilla-formats` don't need a direct `benilla-m2` dependency).
+/// One attachment point (`0` shield, `1`/`2` right/left hand), position in raw WoW model space.
 #[derive(Debug, Clone, Copy)]
 pub struct M2Attachment {
     pub id: u16,
@@ -108,15 +76,8 @@ pub struct M2Attachment {
     pub position: [f32; 3],
 }
 
-/// Parse the M2 attachment-point table **as the reference addresses it**: one entry per attach id
-/// the model's AttachLookup resolves (`benilla_m2::M2Model::attachment` — the `0x710310` bounds +
-/// `0xffff` sentinel), in id order, so a consumer keyed by id can simply match on
-/// [`M2Attachment::id`].
-///
-/// This is deliberately **not** the raw file table: ~5% of weapon models author several records
-/// under one id (both ends of a staff), and the lookup names exactly one of them — the other is
-/// unreachable in the reference and must be unreachable here (decision 0805). Records the lookup
-/// never names are therefore absent. Empty for a model with no attachment points.
+/// One attachment point per id the AttachLookup resolves (`0x710310`), in id order: of several
+/// records under one id, only the one the lookup names is reachable.
 pub fn parse_m2_attachments(bytes: &[u8]) -> Result<Vec<M2Attachment>> {
     let format =
         parse_m2(&mut Cursor::new(bytes)).map_err(|e| anyhow::anyhow!("parsing M2: {e}"))?;
@@ -125,9 +86,7 @@ pub fn parse_m2_attachments(bytes: &[u8]) -> Result<Vec<M2Attachment>> {
         .filter_map(|id| {
             let a = model.attachment(id as u16)?;
             Some(M2Attachment {
-                // The LOOKUP's id, not the record's own: the reference resolves `lookup[id]` and
-                // never re-reads the record's id field, so that is the id this point answers to.
-                // (They agree on every shipped model checked; this makes it true by construction.)
+                // The lookup's id: the reference never re-reads the record's own id field.
                 id: id as u16,
                 bone: a.bone,
                 position: a.position,
@@ -136,12 +95,8 @@ pub fn parse_m2_attachments(bytes: &[u8]) -> Result<Vec<M2Attachment>> {
         .collect())
 }
 
-/// One M2 animation-event **positional marker** (`benilla_m2::M2EventMarker` re-exposed as the
-/// bytes-in entry point, like [`M2Attachment`]): the 4CC, the bone it rides, and its **raw WoW
-/// model-space** position. The client resolves positions off this table by 4CC, first match
-/// (`0x7130e0`/`0x7131b0`) — the cast-release launch points `$CSL`/`$CSR`/`$CST` (casting hand
-/// left/right/two-hand, `0x60c9b0`'s cascade) and the ranged release `$BWR` ride it; the fire
-/// *times* are the per-sequence [`AnimEvent`] stream.
+/// An event record's position half, looked up by 4CC, first match (`0x7130e0`/`0x7131b0`): the
+/// cast-release points `$CSL`/`$CSR`/`$CST` (`0x60c9b0`) and the ranged release `$BWR`.
 #[derive(Debug, Clone, Copy)]
 pub struct EventMarker {
     /// The identifier 4CC, stored forward (`*b"$CSL"`).
@@ -150,9 +105,7 @@ pub struct EventMarker {
     pub position: [f32; 3],
 }
 
-/// Parse the M2 event table's positional markers (see [`EventMarker`]). Straight off
-/// `benilla-m2`'s already bone-range-checked parse, file order preserved (queries take the first
-/// ident match); empty for a model with no events.
+/// The event table's positional markers, in file order since lookups take the first match.
 pub fn parse_m2_event_markers(bytes: &[u8]) -> Result<Vec<EventMarker>> {
     let format =
         parse_m2(&mut Cursor::new(bytes)).map_err(|e| anyhow::anyhow!("parsing M2: {e}"))?;
@@ -168,22 +121,15 @@ pub fn parse_m2_event_markers(bytes: &[u8]) -> Result<Vec<EventMarker>> {
         .collect())
 }
 
-/// A bow M2's **bowstring anchors** — the `$WTT` (top) / `$WTB` (bottom) EVENT records the
-/// client's string drawer `0x611ff0` spans (wow-re `nocked-ammo-cancel.md` §G2: `0x7131b0` finds
-/// each marker, transforms its local position by its bone's live matrix, and a 2-segment line
-/// list runs top → middle → bottom). Each anchor is `(bone index, raw WoW model-space position)`
-/// — the limb-tip helper bones (8/9 on the standard bows), which the bow's own BowPull/BowRelease
-/// sequences bend. The markers are pure position records (no timestamps), which is why they never
-/// surface in the per-sequence [`AnimEvent`] stream.
+/// A bow's `$WTT`/`$WTB` event records, `(bone, position)`, which the string drawer `0x611ff0`
+/// spans top to bottom, each posed by its limb-tip bone (`0x7131b0`).
 #[derive(Clone, Copy)]
 pub struct StringAnchors {
     pub top: (u16, [f32; 3]),
     pub bottom: (u16, [f32; 3]),
 }
 
-/// Parse a model's `$WTT`/`$WTB` bowstring anchors from the raw M2 event table (stride 44:
-/// identifier 4CC @+0, bone @+8, position C3 @+12 — the same record `parse_m2_animations` reads
-/// timestamps from). `None` when either marker is absent (every non-bow model).
+/// The `$WTT`/`$WTB` anchors from the raw event table (stride 44); `None` unless both exist.
 pub fn parse_m2_string_anchors(b: &[u8]) -> Option<StringAnchors> {
     let (ev_count, ev_ofs) = (le_u32(b, 0x114) as usize, le_u32(b, 0x118) as usize);
     let (mut top, mut bottom) = (None, None);
@@ -213,12 +159,9 @@ pub fn parse_m2_string_anchors(b: &[u8]) -> Option<StringAnchors> {
     })
 }
 
-/// Parse a model's first `$CCH` marker — the fishing line's near anchor on the pole (wow-re
-/// `fishing-line.md` §2: the line builder scans the M2 **events** table for `$CCH` and composes
-/// its position through the bone's pose; the bobber authors one too but the reference never reads
-/// it). Returns `(bone index, raw WoW model-space position)`; `None` for a model with no `$CCH`.
-/// Exactly one weapon model in the 5875 chain authors it (`Misc_2H_FishingPole_A_01.m2` — the
-/// `scan_events` sweep), which is what lets the held-item attach key on presence alone.
+/// The first `$CCH` marker, `(bone, position)`: the fishing line's near end, found and posed by
+/// `0x7131b0`. The line reads only the pole's, though the bobber authors one; among weapons only
+/// the fishing pole does, so a held item keys on its presence.
 pub fn parse_m2_cch_marker(b: &[u8]) -> Option<(u16, [f32; 3])> {
     let (ev_count, ev_ofs) = (le_u32(b, 0x114) as usize, le_u32(b, 0x118) as usize);
     for e in 0..ev_count {
@@ -240,25 +183,16 @@ pub fn parse_m2_cch_marker(b: &[u8]) -> Option<(u16, [f32; 3])> {
     None
 }
 
-/// One row of the M2's baked **PlayableAnimationLookup** table (decision 0082 — missing-animation-clip
-/// resolution): re-exposed from `benilla-m2`'s [`benilla_m2::M2PlayableAnim`] (identical shape) as the
-/// bytes-in entry point alongside [`parse_m2_skeleton`]/[`parse_m2_attachments`], so callers that only
-/// take `benilla-formats` don't need a direct `benilla-m2` dependency.
+/// One row of the M2's PlayableAnimationLookup, the resolution of a clip the model lacks.
 #[derive(Debug, Clone, Copy)]
 pub struct PlayableAnim {
     /// The `AnimationData.dbc` id this model actually plays for the row's requested id.
     pub resolved_id: u16,
-    /// Direction/variant playback code — plumbed through, not yet applied (see
-    /// [`benilla_m2::M2PlayableAnim::dir_flags`]).
+    /// Direction/variant playback code; carried, not applied.
     pub dir_flags: u16,
 }
 
-/// Parse the M2's [`PlayableAnim`] table (decision 0082, wow-re `anim-id-resolution.md`,
-/// byte-verified `0x711bf0`): the model's own precomputed answer to "if the game requests
-/// `AnimationData.dbc` id X, which id do I actually play, and in which direction/variant" — the
-/// source `benilla-assets`' `ModelAnimations::resolve` PATH 1 reads. Straight off `benilla-m2`'s
-/// header array (`count@+0x2c`/`ofs@+0x30`); empty for a model with no table (a boneless/malformed
-/// M2), which the resolver then degrades to identity for.
+/// The [`PlayableAnim`] table (`0x711bf0`, header `+0x2c`/`+0x30`); none means identity.
 pub fn parse_m2_playable_animation_lookup(bytes: &[u8]) -> Result<Vec<PlayableAnim>> {
     let format =
         parse_m2(&mut Cursor::new(bytes)).map_err(|e| anyhow::anyhow!("parsing M2: {e}"))?;
@@ -273,27 +207,16 @@ pub fn parse_m2_playable_animation_lookup(bytes: &[u8]) -> Result<Vec<PlayableAn
         .collect())
 }
 
-/// Parse the M2's **AnimationLookup** table (header `count@+0x24`/`ofs@+0x28`) — `AnimationData.dbc`
-/// id → this model's first sequence slot for it, `0xffff` where it authors none. The table behind the
-/// reference's ownership predicate `0x711960`; see [`benilla_m2::M2Model::owns_animation`], which is
-/// what callers should normally use rather than indexing this by hand.
+/// The AnimationLookup (header `+0x24`/`+0x28`): `AnimationData.dbc` id to first sequence slot,
+/// `0xffff` for none, as the ownership test `0x711960` reads it (`M2Model::owns_animation`).
 pub fn parse_m2_animation_lookup(bytes: &[u8]) -> Result<Vec<u16>> {
     let format =
         parse_m2(&mut Cursor::new(bytes)).map_err(|e| anyhow::anyhow!("parsing M2: {e}"))?;
     Ok(format.model().animation_lookup.clone())
 }
 
-/// Every bone of `bytes` that **spins rigidly** in the sequence a loader arm plays — see
-/// [`BoneSpin`] for what that means and why each clause of the predicate is there. Keyed by M2 bone
-/// index, so a caller can look up the sole bone its batch is weighted to; empty for a model with no
-/// such bone, which is almost every model.
-///
-/// **The sequence is `anim_id == 0`** — the idle the reference arms by default (VERIFIED
-/// wow-5875-re, and the doodad host's load arm: bone 0, animation id 0, wow-re
-/// `doodad-anim-host.md` §4a). Selection is by id, never by record index ([`ModelAnimation`]'s own
-/// rule). Whether a *WMO skybox* is armed by that same path is NOT byte-pinned — both shipped
-/// skyboxes author exactly one sequence, so there is nothing else it could be playing, but a model
-/// with several would need the arming verified before this picked among them.
+/// The bones that spin rigidly ([`BoneSpin`]) in anim 0, which the load arms play (`0x70ebd0`,
+/// doodads `0x695100`). How a WMO skybox is armed is untraced; both shipped ones have one clip.
 pub fn m2_bone_spins(bytes: &[u8]) -> HashMap<u16, BoneSpin> {
     let mut out = HashMap::new();
     let Ok(skeleton) = parse_m2_skeleton(bytes) else {
@@ -306,20 +229,15 @@ pub fn m2_bone_spins(bytes: &[u8]) -> HashMap<u16, BoneSpin> {
     let (bone_count, bone_ofs) = (le_u32(bytes, 0x34) as usize, le_u32(bytes, 0x38) as usize);
     for keys in &seq.bones {
         let idx = keys.bone as usize;
-        // Rotation only, and enough keys to move: a translation or scale track on the same bone is
-        // still rigid but is not a spin about the pivot, and one key is a pose, not an animation.
+        // Rotation only and at least two keys: one key is a pose, not a spin.
         if keys.rotation.len() < 2 || !keys.translation.is_empty() || !keys.scale.is_empty() {
             continue;
         }
-        // Parentless: nothing above it can compose another motion in (see [`BoneSpin`]).
+        // Parentless: nothing above composes another motion in.
         let Some(bone) = skeleton.bones.get(idx).filter(|b| b.parent < 0) else {
             continue;
         };
-        // The rotation track's own `interp_type` word — bone record stride `0x6c`, rotation
-        // `M2Track` at `+0x28`, `interp_type` at its `+0x00` (the same offsets `parse_m2_animations`
-        // reads the track through, where `read_channel_track`'s `step` is `interp_type == 0`).
-        // Bounds-checked rather than leaning on `parse_m2_animations` having already validated the
-        // record: `le_u16` panics past the end, and the two readers' guards must not be coupled.
+        // The rotation track's `interp_type`, bounds-checked here: `le_u16` panics past the end.
         let interp = idx < bone_count
             && bone_ofs
                 .checked_add(idx * 0x6c + 0x28)
@@ -337,11 +255,8 @@ pub fn m2_bone_spins(bytes: &[u8]) -> HashMap<u16, BoneSpin> {
     out
 }
 
-/// One bone's keyframe tracks for an animation sequence (decision 0019), in **raw WoW model space**:
-/// translation/scale are `[f32;3]`, rotation is an uncompressed quaternion `[x,y,z,w]` (vanilla v256).
-/// Times are **seconds**, rebased to the sequence start so each clip runs `0..duration`. Only the
-/// channels the bone actually animates are non-empty; a bone absent from [`ModelAnimation::bones`]
-/// holds its bind pose.
+/// One bone's keys for a sequence, raw WoW model space, seconds from its start, rotations
+/// `[x, y, z, w]`; a bone absent from [`ModelAnimation::bones`] holds its bind pose.
 #[derive(Debug, Clone)]
 pub struct BoneKeys {
     pub bone: u16,
@@ -350,22 +265,15 @@ pub struct BoneKeys {
     pub scale: Vec<(f32, [f32; 3])>,
 }
 
-/// One bone channel driven by a **global sequence**: a free-running loop *independent* of the playing
-/// animation, wrapped at `period_ms` off the model's own clock (VERIFIED wow-5875-re `animation.md` /
-/// `doodad-anim-host.md`: global sequences loop with zero arming, clock = `[CM2Model+0x2c]+0xc` mod
-/// `globalSequences[gseq]`). Keys are absolute ms within `[0, period_ms]`, ascending. The canonical
-/// consumer is the character **eye blink** — an eyelid bone whose SCALE track holds `0` (lid retracted,
-/// eye open) for most of the loop and pops to `1` (lid full-size, eye shut) for ~100 ms.
+/// A bone channel on a global sequence, sampled at the scene clock less the instance's attach
+/// time, mod `period_ms` (`0x714352`). Keys are absolute ms, ascending.
 #[derive(Debug, Clone)]
 pub struct GlobalSeqChannel<T> {
     pub period_ms: u32,
     pub keys: Vec<(u32, T)>,
 }
 
-/// A bone's global-sequence-driven channels (any of translation/rotation/scale; each carries its own
-/// global sequence and thus its own period). Bones with no such channel are absent from the list. These
-/// are exactly the tracks [`parse_m2_animations`] drops (it reads only the playing sequence's band); the
-/// runtime samples these on the free clock and composes them over the sequence pose.
+/// A bone's global-sequence channels, composed over the sequence pose at runtime.
 #[derive(Debug, Clone)]
 pub struct GlobalSeqBone {
     pub bone: u16,
@@ -374,120 +282,65 @@ pub struct GlobalSeqBone {
     pub scale: Option<GlobalSeqChannel<[f32; 3]>>,
 }
 
-/// One animation **event keyframe**: a 4CC-tagged trigger on the sequence timeline (decision 0070
-/// slice 3 — the anim-driven sound/effect surface). Sound-relevant tags: `$SND`/`$DSL`/`$DSO`
-/// (play kit `data`), the footstep family (`$FL0..3`/`$FR`/`$RL`/`$RR`/`$SL`/`$SR`/`$BL`/`$BR` +
-/// `$FSD`), `$CSS` weapon swing, `$HIT` impact, `$DTH` death thud, `$FD1..4` fidgets,
-/// `$AH0..3` custom attacks, `$BTH` breath. Non-sound tags pass through untouched.
+/// One animation event key: a 4CC-tagged trigger on the sequence timeline.
 #[derive(Debug, Clone, Copy)]
 pub struct AnimEvent {
-    /// Seconds from the sequence start (same clock as the bone keys).
+    /// Seconds from the sequence start, as the bone keys.
     pub time: f32,
-    /// The identifier 4CC, stored forward (`*b"$FL0"`) — byte-verified on DireWolf.m2.
+    /// The identifier 4CC, stored forward (`*b"$FL0"`).
     pub ident: [u8; 4],
-    /// The payload — a SoundEntries id for `$SND`/`$DSL`/`$DSO`, else 0.
+    /// The payload: a SoundEntries id for `$SND`/`$DSL`/`$DSO`, else 0.
     pub data: u32,
-    /// The bone the record rides (`M2Event.bone` @+8) — the same field [`EventMarker`] carries,
-    /// here on the *fired* key so a consumer never has to re-find the record by 4CC. It cannot:
-    /// 75 shipped models author some 4CC more than once at different points, and **every player
-    /// character model authors `$CSD` six times** (one per emote clip), so a first-match table
-    /// scan answers the wrong point for five of the six.
+    /// The record's bone (`+8`), carried on the key because a 4CC repeats: every player model
+    /// authors `$CSD` six times, so a lookup by 4CC finds the wrong point.
     pub bone: u16,
-    /// The record's authored point (`M2Event.position` @+12), **raw WoW model space** — the same
-    /// convention [`EventMarker::position`] uses. The reference's event kernel (`0x719370`)
-    /// snapshots `placementMatrix · (boneMatrix[bone] · position)` by value into the callback
-    /// record every dispatcher then reads, so this is half of where the event *happens*, not just
-    /// when.
+    /// The record's point (`+12`); the event kernel (`0x719370`) snapshots
+    /// `placement · boneMatrix[bone] · position` into the callback record.
     pub position: [f32; 3],
 }
 
-/// One animation sequence's per-bone keyframes (decision 0019): its `AnimationData.dbc` id, duration,
-/// loop flag, and the bones that move. **Stand is `anim_id` 0** — the idle the real client arms by default
-/// (VERIFIED wow-5875-re) — but its *record index* is not fixed: Stand is `animationLookup[0]`, which is
-/// record 0 only for some models (a chicken's Stand is record 2, a horse's record 1; those models' record
-/// 0 is a different sequence). Consumers select always by `anim_id`, never by record index; walk (4),
-/// run (5), death, emotes, … are other ids.
+/// One sequence's per-bone keyframes. Stand is `anim_id` 0 (`0x70ebd0`) but not always record 0,
+/// so consumers select by `anim_id`.
 #[derive(Debug, Clone)]
 pub struct ModelAnimation {
     /// `AnimationData.dbc` id, the selection key (0 Stand, 4 Walk, 5 Run, 13 WalkBackwards, …).
     pub anim_id: u16,
-    /// This sequence's **file slot** — its index in the M2's own sequence array, which is NOT this
-    /// list's index (zero-duration sequences are dropped below). Load-bearing because the slot is
-    /// what indexes every track's per-sequence key ranges: the material-alpha bake keys its
-    /// per-sequence loops by it (`mat_anim::AlphaAnim::seq`), so a consumer that knows which clip
-    /// is playing can ask for that clip's authored batch visibility.
+    /// The file slot, which indexes every track's key ranges; zero-length sequences are dropped.
     pub seq_index: usize,
-    /// The sequence's **absolute time band** on the model's global keyframe timeline
-    /// (`M2Sequence` start @+0x04 / end @+0x08, ms) — the window every non-global-sequence track's
-    /// keys are selected from and rebased against ([`read_bone_track`], `key_anim::bake_track`).
-    /// Exposed because "which keys does this sequence actually see?" is unanswerable without it: a
-    /// track whose keys all sit in *other* sequences' bands holds a clamped value here, and which
-    /// value that is depends on where this band falls among them.
+    /// The absolute band (`M2Sequence` `+0x04`/`+0x08`, ms) sequence tracks are cut to.
     pub start_ms: u32,
     pub end_ms: u32,
     pub duration: f32,
     pub looping: bool,
-    /// The sequence's authored **design movement speed** (`M2Sequence.moveSpeed` @+0x0c, yd/s) — the
-    /// speed the locomotion was animated for. The real client scales a locomotion clip's playback rate
-    /// by `unitSpeed / (moveSpeed · modelScale)` (VERIFIED wow-5875-re `0x5fe2f0`: a §5-converged pair),
-    /// so a unit moving faster than the design speed cycles its legs proportionally faster — without it
-    /// a backpedal (slow design speed) played at 1× looks far too slow. `0.0` for a non-locomotion
-    /// sequence (idle/emote), which the selector leaves at rate 1×.
+    /// `moveSpeed` (`+0x0c`, yd/s): a locomotion clip plays at `unitSpeed / (moveSpeed · scale)`
+    /// (`0x5fe2f0`); `0.0` plays at 1×.
     pub move_speed: f32,
-    /// The sequence's **blend-in time** (`M2Sequence.blendTime` @+0x20, **seconds**) — how long the real
-    /// client cross-fades *into* this animation from the previous pose (VERIFIED wow-5875-re: op4 snapshots
-    /// the live pose `+0x98→+0xc4` and decays it over the blend-in, `rf29-playback-setters.md`). The spawn
-    /// site uses it as the cross-fade duration so a gait change eases instead of snapping (Walk/Run 0.25 s,
-    /// Stand 0.5 s, jump/sit transitions 0.15 s). `0.0` ⇒ an instant cut.
+    /// `blendTime` (`+0x20`, seconds): the cross-fade in from the live pose (`0x7121a0`).
     pub blend_time: f32,
-    /// The sequence's bounds-sphere **centre** — the `M2Sequence` CAaBox (min @+0x24, max @+0x30) centre,
-    /// **raw WoW model space**. The real client's mouse-pick broad phase tests the cursor ray against
-    /// exactly this sphere for the unit's *current* animation — world-placed + scaled, **no pad**
-    /// (VERIFIED wow-5875-re `0x7089c0`, the pick-volume RE) — before the per-triangle posed-mesh test.
+    /// The box centre (`+0x24`/`+0x30`): the pick broad phase tests this sphere for the current
+    /// animation, placed and scaled, no pad (`0x7089c0`).
     pub bounds_center: [f32; 3],
-    /// The sequence's bounds-sphere **radius** (`M2Sequence` @+0x3c, model-local yards). `0.0` ⇒
-    /// unauthored (the real client falls back to the header sphere).
+    /// The sphere radius (`+0x3c`); `0.0` falls back to the header sphere.
     pub bounds_radius: f32,
-    /// The sequence's CAaBox **min corner** (`M2Sequence` @+0x24), raw WoW model space — the box
-    /// [`Self::bounds_center`] is the centre of. The unit **blob shadow** sizes its projection box
-    /// from exactly this box for the *current* animation, clamped into ±5 per axis (VERIFIED
-    /// wow-5875-re `unit-blob-shadow.md`: `0x711a20` → clamp `0x6992c0`/`0x699250`).
+    /// The box's min corner (`+0x24`). The blob shadow sizes from the Stand sequence's box, clamped
+    /// to ±5 per axis (`0x711a20`, `0x6992c0`/`0x699250`).
     pub bounds_min: [f32; 3],
-    /// The sequence's CAaBox **max corner** (`M2Sequence` @+0x30). See [`Self::bounds_min`].
     pub bounds_max: [f32; 3],
-    /// The sequence's **variation frequency** (`M2Sequence.frequency` @+0x14) — this variation's
-    /// weight in the client's per-play roll (VERIFIED wow-5875-re `anim-id-resolution.md`: op4
-    /// with variationIdx −1 rolls `_rand()` (0..0x7fff) and walks the id's variation chain —
-    /// `roll < frequency` picks, else `roll -= frequency` and advance).
+    /// `frequency` (`+0x14`): this variation's weight in the per-play roll (`0x7121a0`).
     pub frequency: u16,
-    /// The sequence's **replay range** (`M2Sequence` minReplay @+0x18 / maxReplay @+0x1c) — the
-    /// client rolls a play count `R = max(1, min + ⌊rand·(max−min)/32768⌋)` at every arm (the
-    /// second `_rand` site in op4, `0x712692..0x7126cd`) and **multiplies it into the play
-    /// window** (`0x7126d8`): a clamp-flag one-shot runs its timeline `R` times before freezing;
-    /// a loop-flag sequence ignores it (VERIFIED wow-5875-re `loop-replay-fidget.md`). `(0, 0)`
-    /// (the overwhelming majority) rolls to `R = 1`.
+    /// The replay range (`+0x18`/`+0x1c`): each arm rolls a play count
+    /// `R = max(1, min + ⌊rand·(max−min)/32768⌋)` (`0x712692..0x7126cd`) into the play window
+    /// (`0x7126d8`); a looping sequence ignores it (`0x7145f1`).
     pub min_replay: u32,
     pub max_replay: u32,
     pub bones: Vec<BoneKeys>,
-    /// Event keyframes in this sequence's window, rebased like the bone keys (seconds from start).
+    /// Event keys in this sequence's band, seconds from its start.
     pub events: Vec<AnimEvent>,
 }
 
 impl ModelAnimation {
-    /// Does this sequence leave **every** bone at bind pose for its whole band — one key per
-    /// channel, and that key the identity (zero translation, unit-w rotation, unit scale)?
-    ///
-    /// The **render** content gate (decision 0130, consumed by `benilla_assets`' loader as
-    /// `ModelAnimations::first_seq`): looping such a sequence draws exactly the static mesh, so the
-    /// placed-doodad tier skips building a skin + `AnimationPlayer` for it — the ~90 % of placed
-    /// doodads `doodadscan` measured. It lives here, beside the parse, so the `benilla-extract`
-    /// census of what that gate costs the corpus (`idleslotscan`) asks the renderer's own question
-    /// instead of a hand-copied twin that can drift from it.
-    ///
-    /// It answers a question about **pixels only**, and is never a reason to treat the sequence as
-    /// absent: a consumer keyed on the sequence *identity* — the per-sequence emission, parameter
-    /// and material-alpha bakes — still needs the slot the instance is playing, and the reference
-    /// always has one armed (decision 0936, `ModelAnimations::idle_seq`).
+    /// Does every bone hold the identity for the whole band? Then the doodad gate builds no rig,
+    /// though the reference still arms the sequence and its other bakes still need it.
     pub fn is_rest_pose(&self) -> bool {
         const EPS: f32 = 1e-4;
         !self.bones.iter().any(|b| {
@@ -507,39 +360,27 @@ impl ModelAnimation {
     }
 }
 
-/// One bone-channel `M2Track`, read **once per model** rather than once per sequence: the v256 track
-/// (0x1c) is `interp_type`@0, `global_seq`@2, then three `M2Array`s — interpolation_ranges@0x04,
-/// **timestamps@0x0c**, **values@0x14** (each `{count u32, offset u32}`). Every sequence carves its
-/// own band out of this one shared key list ([`ChannelTrack::band`]), so re-reading the arrays per
-/// sequence was pure waste — HumanMale walked 143 sequences × 119 bones × 3 channels of headers to
-/// build 357 tracks' worth of keys.
+/// One bone-channel `M2Track` (`0x1c` bytes: interp `+0`, gseq `+2`, ranges `+0x04`, timestamps
+/// `+0x0c`, values `+0x14`), read once per model and sliced per sequence.
 struct ChannelTrack<T> {
-    /// `interp_type == 0`: hold each key until the next, no interpolation (the samplers' shared
-    /// `cmp word[track],0` dispatch — wow-re `eval.md` FN2/FN6).
+    /// `interp_type == 0`: hold each key, no interpolation (`0x713ea0`/`0x71af20`).
     step: bool,
-    /// Global-sequence id, `0xffff` for an ordinary sequence-timeline track.
+    /// Global-sequence id, `0xffff` for a sequence-timeline track.
     gseq: u16,
-    /// The per-sequence **key-index window** `(lo, hi)`, indexed by the sequence's FILE slot — the
-    /// array the reference's key search selects before it looks at a single timestamp (VERIFIED
-    /// wow-re `eval.md` FN1 `0x713d50` §1). Empty ⇒ the reference's own `[track+4]==0` fallback,
-    /// "search the whole key list".
+    /// Key-index windows `(lo, hi)` by file slot, which the key search selects first (`0x713d50`);
+    /// empty means the whole list (`[track+4] == 0`).
     ranges: Vec<(u32, u32)>,
-    /// `(absolute ms, value)` keys, file order — every sequence's keys concatenated on one
-    /// timeline (timestamps absolute, VERIFIED).
+    /// `(absolute ms, value)`: every sequence's keys on one timeline.
     keys: Vec<(u32, T)>,
 }
 
-/// One bone's three channel tracks, in the bone record's own order: translation `+0x0c`, rotation
-/// `+0x28`, scale `+0x44`.
 type BoneChannels = (
     ChannelTrack<[f32; 3]>,
     ChannelTrack<[f32; 4]>,
     ChannelTrack<[f32; 3]>,
 );
 
-/// Read one bone channel's `M2Track` whole (see [`ChannelTrack`]). `read_value` decodes one value at
-/// a byte offset; `stride` is its size. Out-of-range reads truncate the key list — real vanilla art
-/// relies on that tolerance.
+/// Read one `M2Track` whole; out-of-range reads truncate the keys, which vanilla art relies on.
 fn read_channel_track<T>(
     b: &[u8],
     track: usize,
@@ -585,37 +426,13 @@ fn read_channel_track<T>(
 }
 
 impl<T: super::key_anim::Lerp + PartialEq> ChannelTrack<T> {
-    /// This channel's keyframes for the sequence at file slot `slot`, spanning
-    /// `[start, end]` (absolute ms), rebased to seconds from the band start.
-    ///
-    /// In-band keys are selected by **absolute timestamp**, which is what the reference's search
-    /// resolves to: its window is `ranges[slot]`, and that window brackets the band's own keys in
-    /// every model of the 1.12.1 corpus (`benilla-extract bonescan`: 0 violations in 516 633 keyed
-    /// band-slots — the check that makes reading the window safe at all). Selecting *the window's
-    /// keys* as in-clip keys is the thing that never worked: `hi` routinely points at a key in a
-    /// later band 14–64 s away, which froze Chicken/Bear/Kobold at a garbage pose. It is a
-    /// **bracket**, not a key set.
-    ///
-    /// Its load-bearing use is the band **edges**, where the reference keeps sampling and a
-    /// truncated key list does not (wow-re `eval.md` FN1 `0x713d50`):
-    ///
-    /// - a band with **no keys of its own** still has an authored pose — the window resolves it,
-    ///   either outright (`lo >= hi` ⇒ `keys[lo]`, the degenerate `{lo, lo, 0}` result) or as the
-    ///   lerp across the bracketing pair. Leaving the track empty instead froze the bone at
-    ///   whatever the *previous* clip left it (decision 0133's tilt: a Stand-variation waist twist
-    ///   rode through the entire run);
-    /// - past the band's last key the reference keeps ramping toward `k1 = k0 + 1`, which is
-    ///   bounded by the TOTAL key count and not by the window — so a key belonging to a later
-    ///   sequence is a live lerp endpoint.
-    ///
-    /// A head/tail sample is emitted only when it differs from the edge key it would otherwise
-    /// hold, so the clips are unchanged wherever the reference and a plain hold agree — which,
-    /// measured, is everywhere but `Creature\Zombie`'s root translation (decision 0643).
-    ///
-    /// A **global-sequence** channel (`gseq != 0xffff`) runs on its own clock, not this band: a
-    /// lone key is a pure CONSTANT folded into every clip (how vanilla authors the stowed-weapon
-    /// attach-bone orientations — HumanMale bones 29/30/58–62), and a multi-key one belongs to
-    /// [`parse_m2_global_sequence_bones`] and the `GlobalSeqDrive` lane, so it is left out here.
+    /// The keys for file slot `slot` over the band `[start, end]` (absolute ms), in seconds from
+    /// its start. In-band keys go by timestamp; `ranges[slot]` is a bracket (its `hi` can sit in a
+    /// later band) that decides the edges, where the reference keeps sampling (`0x713d50`): an
+    /// empty band takes `keys[lo]` when `lo >= hi`, else the bracket's lerp, and past the last key
+    /// the lerp runs toward `k0 + 1`, bounded by the key count, not the window. An edge key is
+    /// added only where it differs from the held one. On a global sequence a lone key is a
+    /// constant in every clip; a multi-key one belongs to [`parse_m2_global_sequence_bones`].
     fn band(&self, slot: usize, start: u32, end: u32) -> Vec<(f32, T)> {
         if self.keys.is_empty() {
             return Vec::new();
@@ -640,8 +457,7 @@ impl<T: super::key_anim::Lerp + PartialEq> ChannelTrack<T> {
             .filter(|&(ts, _)| ts >= start && ts <= end)
             .collect();
         let Some(&(first_ms, first_v)) = in_band.first() else {
-            // An empty band: the window's value, held across it — two keys only when the bracket
-            // lerp actually moves within the band.
+            // An empty band holds the window's value; two keys only when the bracket lerp moves.
             let head = match at(start) {
                 Some(v) => v,
                 None => return Vec::new(),
@@ -664,19 +480,10 @@ impl<T: super::key_anim::Lerp + PartialEq> ChannelTrack<T> {
     }
 }
 
-/// The weapon-grip finger poses: each requested `bone`'s rotation **as the reference samples it at
-/// the HandsClosed frame** (`AnimationData` id 15), through the same window kernel every other
-/// channel uses ([`ChannelTrack::band`]).
-///
-/// This exists as its own entry point because the grip is not a *clip* — it is a pose lifted out of
-/// one frame and worn as a masked overlay over whatever animation is playing, so the weapon hand
-/// stays closed while the body runs (wow-re `hand-grip-mechanism.md`). HandsClosed is a 33 ms band
-/// that keys nothing of its own on the finger bones (HumanMale bone 102 is keyed at 43333/70000 ms,
-/// both curled, not the 60000 ms frame) — its `interpolation_ranges` pair brackets it, which is
-/// exactly the case the window rule resolves.
-///
-/// Returns `(bone, quat[x,y,z,w])` for the bones that carry a plain rotation track; empty if the
-/// model has no HandsClosed sequence.
+/// Each bone's rotation, `[x, y, z, w]`, as the reference samples it at the HandsClosed frame
+/// (`AnimationData` 15), through the key window: the grip overlay that keeps the weapon hand closed
+/// while the body animates (`CloseHand` `0x479660`). HandsClosed keys no finger bone; its window
+/// brackets it.
 pub fn hand_grip_finger_poses(bytes: &[u8], bones: &[u16]) -> Vec<(u16, [f32; 4])> {
     let b = bytes;
     if b.len() < 0x40 || &b[0..4] != b"MD20" {
@@ -684,7 +491,7 @@ pub fn hand_grip_finger_poses(bytes: &[u8], bones: &[u16]) -> Vec<(u16, [f32; 4]
     }
     let (seq_count, seq_ofs) = (le_u32(b, 0x1c) as usize, le_u32(b, 0x20) as usize);
     let (bone_count, bone_ofs) = (le_u32(b, 0x34) as usize, le_u32(b, 0x38) as usize);
-    // HandsClosed (anim id 15) → its FILE slot (what indexes the key windows) and frame start ms.
+    // HandsClosed's file slot, which indexes the key windows, and its start ms.
     let mut hands_closed = None;
     for s in 0..seq_count {
         let rec = seq_ofs + s * 0x44;
@@ -713,10 +520,9 @@ pub fn hand_grip_finger_poses(bytes: &[u8], bones: &[u16]) -> Vec<(u16, [f32; 4]
         if bi >= bone_count || bone_ofs + bi * 0x6c + 0x6c > b.len() {
             continue;
         }
-        // The bone's rotation M2Track (+0x28 in the 0x6c record), stride 16 (a 4×f32 quaternion).
         let tr = read_channel_track(b, bone_ofs + bi * 0x6c + 0x28, 16, quat);
         if tr.gseq != 0xffff || tr.keys.is_empty() {
-            continue; // a global-sequence track runs on its own clock — not this
+            continue; // a global-sequence track runs on its own clock
         }
         let last = tr.keys.len() - 1;
         let (lo, hi) = tr
@@ -731,15 +537,9 @@ pub fn hand_grip_finger_poses(bytes: &[u8], bones: &[u16]) -> Vec<(u16, [f32; 4]
     out
 }
 
-/// Parse **all** of a model's animation sequences into per-bone keyframes (decision 0019). Offsets
-/// VERIFIED against wow-5875-re: sequences @MD20 `0x1c`/`0x20` (stride 0x44; id@+0x00, start@+0x04,
-/// end@+0x08, flags@+0x10 with **bit0 SET ⇒ clamp/one-shot, CLEAR ⇒ loop**); bones @`0x34`/`0x38`
-/// (stride 0x6c; the three `M2Track`s at +0x0c/+0x28/+0x44). Empty for a model with no sequences;
-/// degenerate (zero-length) sequences are skipped.
-///
-/// Cost note: each sequence scans every bone track's full timestamp array (the time-band select), so
-/// this is `O(sequences · bones · keys)` — fine at async load for the bounded vanilla rigs, a candidate
-/// for a one-pass per-sequence key index if a packed-mob load ever shows up hot.
+/// Parse every sequence at the animate kernel's offsets (`0x714260`): sequences at MD20
+/// `0x1c`/`0x20` (stride `0x44`), bones at `0x34`/`0x38` (stride `0x6c`). Zero-length sequences
+/// are skipped.
 pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
     if b.len() < 0x40 || &b[0..4] != b"MD20" {
         return Vec::new();
@@ -755,15 +555,10 @@ pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
             le_f32(b, o + 12),
         ]
     };
-    // The model's event track (events @MD20 0x114/0x118 pre-Wrath, stride 44: identifier 4CC @+0,
-    // data @+4, bone @+8, position @+12, M2TrackBase @+24 whose timestamp M2Array sits @+0x0c —
-    // BYTE-VERIFIED on DireWolf.m2: 19 events, forward-stored tags `$CSS`/`$DTH`/`$FL0`…, absolute
-    // global-timeline ms). Read once here; each sequence below selects + rebases its window,
-    // exactly like the bone tracks.
+    // The event table (MD20 `0x114`/`0x118`, stride 44; the `M2TrackBase` at `+24` puts the
+    // absolute-ms timestamps at `+36`), read once and cut per sequence like the bone keys.
     let (ev_count, ev_ofs) = (le_u32(b, 0x114) as usize, le_u32(b, 0x118) as usize);
-    /// One `M2Event` record as the file holds it: the 4CC and payload, the bone and point the
-    /// kernel transforms (see [`AnimEvent::position`]), and the absolute global-timeline
-    /// timestamps each sequence below selects and rebases into its own band.
+    /// One `M2Event` record as the file holds it.
     struct EventRecord {
         ident: [u8; 4],
         data: u32,
@@ -771,7 +566,9 @@ pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
         position: [f32; 3],
         times: Vec<u32>,
     }
-    let mut model_events: Vec<EventRecord> = Vec::with_capacity(ev_count);
+    // Raw header counts: reservations cap at the bytes present, as a failed allocation aborts.
+    let mut model_events: Vec<EventRecord> =
+        Vec::with_capacity(capped(ev_count, 44, b.len().saturating_sub(ev_ofs)));
     for e in 0..ev_count {
         let erec = ev_ofs + e * 44;
         if erec + 44 > b.len() {
@@ -785,7 +582,7 @@ pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
         let bone = le_u32(b, erec + 8) as u16;
         let position = vec3(b, erec + 12);
         let (nts, ots) = (le_u32(b, erec + 36) as usize, le_u32(b, erec + 40) as usize);
-        let mut times = Vec::with_capacity(nts);
+        let mut times = Vec::with_capacity(capped(nts, 4, b.len().saturating_sub(ots)));
         for t in 0..nts {
             let o = ots + t * 4;
             if o + 4 > b.len() {
@@ -802,8 +599,6 @@ pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
         });
     }
 
-    // Every bone's three channel tracks, read ONCE: the key arrays are shared by every sequence,
-    // which only slices its own band out of them (`ChannelTrack::band`).
     let bone_tracks: Vec<BoneChannels> = (0..bone_count)
         .map_while(|i| {
             let brec = bone_ofs + i * 0x6c;
@@ -830,14 +625,8 @@ pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
             le_u32(b, rec + 0x08),
             le_u32(b, rec + 0x10),
         );
-        // M2Sequence.moveSpeed @+0x0c (f32, yd/s): the locomotion design speed the playback-rate scaler
-        // divides the unit's live speed by (VERIFIED wow-5875-re `0x711a20`/`0x5fe2f0`). `0.0` for a
-        // non-locomotion sequence.
         let move_speed = le_f32(b, rec + 0x0c);
-        // M2Sequence.blendTime @+0x20 (u32, ms → seconds): the cross-fade-in duration into this sequence.
         let blend_time = le_u32(b, rec + 0x20) as f32 / 1000.0;
-        // M2Sequence bounds: CAaBox min @+0x24 / max @+0x30, sphere radius @+0x3c — the mouse-pick
-        // broad-phase sphere for the model's current animation (wow-re pick-volume RE, `0x7089c0`).
         let (bmin, bmax) = (vec3(b, rec + 0x24), vec3(b, rec + 0x30));
         let bounds_center = [
             (bmin[0] + bmax[0]) * 0.5,
@@ -845,15 +634,13 @@ pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
             (bmin[2] + bmax[2]) * 0.5,
         ];
         let bounds_radius = le_f32(b, rec + 0x3c);
-        // M2Sequence.frequency @+0x14: this variation's weight in the per-play roll.
         let frequency = le_u16(b, rec + 0x14);
-        // M2Sequence minReplay/maxReplay @+0x18/+0x1c: the play-count roll's range.
         let (min_replay, max_replay) = (le_u32(b, rec + 0x18), le_u32(b, rec + 0x1c));
         let duration = end.saturating_sub(start) as f32 / 1000.0;
         if duration <= 0.0 {
             continue;
         }
-        let looping = flags & 1 == 0; // VERIFIED polarity: bit0 clear loops, set clamps
+        let looping = flags & 1 == 0; // bit 0 clear loops, set clamps
         let mut bones = Vec::new();
         for (i, tracks) in bone_tracks.iter().enumerate() {
             let (tr, rot, sc) = tracks;
@@ -869,7 +656,6 @@ pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
                 });
             }
         }
-        // This sequence's event keys: the same time-band select + rebase as the bone tracks.
         let mut events = Vec::new();
         for r in &model_events {
             for &ts in &r.times {
@@ -909,10 +695,8 @@ pub fn parse_m2_animations(b: &[u8]) -> Vec<ModelAnimation> {
     out
 }
 
-/// Read one bone track (`{interp, gseq, …, key{n,ofs}, val{n,ofs}}`) as a **global-sequence** channel —
-/// `None` unless it is tagged to a global sequence (`gseq != 0xffff`) with a non-zero period and >1 key.
-/// The single-key global track is the CONSTANT case (stowed-weapon rest quats) [`read_bone_track`]
-/// already folds into every clip; it is not a loop and is excluded here.
+/// One bone track as a global-sequence channel: `None` without a global sequence, a non-zero
+/// period and two keys (a lone key is a constant [`ChannelTrack::band`] folds into every clip).
 fn read_global_channel<T>(
     b: &[u8],
     track: usize,
@@ -932,9 +716,10 @@ fn read_global_channel<T>(
     let ts_o = le_u32(b, track + 0x10) as usize;
     let val_o = le_u32(b, track + 0x18) as usize;
     if n <= 1 {
-        return None; // a lone key is a constant channel, not a loop
+        return None; // a constant, not a loop
     }
-    let mut keys = Vec::with_capacity(n);
+    // `n` is a raw count; the timestamp array bounds how many keys the file holds.
+    let mut keys = Vec::with_capacity(capped(n, 4, b.len().saturating_sub(ts_o)));
     for k in 0..n {
         let (t_off, v_off) = (ts_o + k * 4, val_o + k * stride);
         if t_off + 4 > b.len() || v_off + stride > b.len() {
@@ -945,13 +730,8 @@ fn read_global_channel<T>(
     (keys.len() > 1).then_some(GlobalSeqChannel { period_ms, keys })
 }
 
-/// Parse every bone's **global-sequence** animation channels — the free-clock loops
-/// [`parse_m2_animations`] deliberately drops (it reads only the *playing* sequence's time band).
-/// A channel qualifies when its M2Track is tagged to a global sequence (`gseq != 0xffff`) with a
-/// non-zero period and more than one key. The canonical consumer is the character eye-blink (an eyelid
-/// bone's looping SCALE); resting fidget pulses ride the same mechanism. Global-sequence array at MD20
-/// `0x14/0x18` (VERIFIED), bones at `0x34/0x38` (stride `0x6c`), tracks translation `+0x0c` / rotation
-/// `+0x28` / scale `+0x44` (the shared v256 `M2Track`).
+/// Every bone's global-sequence channels, the free-clock loops [`parse_m2_animations`] leaves out
+/// (the eye blink's eyelid scale); global sequences at MD20 `0x14`/`0x18`.
 pub fn parse_m2_global_sequence_bones(b: &[u8]) -> Vec<GlobalSeqBone> {
     if b.len() < 0x40 || &b[0..4] != b"MD20" {
         return Vec::new();
@@ -1004,11 +784,31 @@ pub fn parse_m2_global_sequence_bones(b: &[u8]) -> Vec<GlobalSeqBone> {
 mod tests {
     use super::*;
 
-    /// The character eye-blink, straight off the real `HumanMale.m2`: exactly one global-sequence bone
-    /// (75, the eyelid), a **scale** channel on a real global sequence, whose keys hold `0` (lid gone,
-    /// eye open) at the loop start and pop to `1` (lid full, eye shut) ~33 ms later — the blink. Guards
-    /// the header offsets (global sequences `0x14/0x18`, bones `0x34/0x38`, scale track `+0x44`) and the
-    /// gseq-vs-in-band split against a silent regression. Skips when the client data isn't present.
+    #[test]
+    fn hostile_event_and_key_counts_reserve_only_what_the_file_holds() {
+        let mut b = vec![0u8; 0x11c];
+        b[0..4].copy_from_slice(b"MD20");
+        // u32::MAX events, of which exactly one is present …
+        b[0x114..0x118].copy_from_slice(&u32::MAX.to_le_bytes());
+        b[0x118..0x11c].copy_from_slice(&0x11cu32.to_le_bytes());
+        // … itself claiming u32::MAX timestamps at offset 0.
+        let mut ev = [0u8; 44];
+        ev[36..40].copy_from_slice(&u32::MAX.to_le_bytes());
+        b.extend_from_slice(&ev);
+        assert!(
+            parse_m2_animations(&b).is_empty(),
+            "no sequences ⇒ no clips, and no abort"
+        );
+
+        // A global-sequence track claiming u32::MAX keys walks the 7 that fit its own 28 bytes.
+        let mut track = [0u8; 0x1c];
+        track[0x0c..0x10].copy_from_slice(&u32::MAX.to_le_bytes());
+        let ch = read_global_channel(&track, 0, 4, &|_: u16| Some(1000u32), le_u32)
+            .expect("more than one key on a live global sequence is a channel");
+        assert_eq!(ch.keys.len(), 7);
+    }
+
+    /// `HumanMale.m2`'s one global-sequence bone, the eyelid (75), scales 0 (open) to 1 (shut).
     #[test]
     fn human_male_eyelid_blink_global_sequence() {
         let data = crate::wow_data_or_skip!();
@@ -1051,23 +851,8 @@ mod tests {
         );
     }
 
-    /// **The glue stage carries a whole bone matrix, not just a point** — a rotation on one shipped
-    /// scene and a scale on two.
-    ///
-    /// A `UI_*` background scene stands the character on its attachment 0, and five of the six
-    /// leave that bone unrotated because the scene's camera is authored looking straight down the
-    /// stage's +X, which a WoW model's default facing already faces. `UI_Human` is the exception:
-    /// its scene is a lifted chunk of Elwynn whose camera sits ~18° off that axis, and the author
-    /// aimed the character at it by parking a **constant −16.5° yaw** on the stage bone — two
-    /// identical quaternion keys on a global sequence, which is where a *constant* rotation lives
-    /// in vanilla M2 (the rest pose is identity rotations).
-    ///
-    /// Reading only the attachment point dropped that, and every Human on the character-select
-    /// screen stood angled away from the camera while every other race looked straight out (1533).
-    /// The same bone matrix also carries a **scale** on two scenes — 0.97 on both of UI_Human's
-    /// attachment bones, and on UI_Tauren 1.04 for the character with **0.7324** for the pet — so
-    /// dropping it drew the Tauren scene's pet a third too large. This pins both data the fix rests
-    /// on: skips without the client data.
+    /// `UI_Human` parks a constant −16.5° yaw on its stage bone to face its off-axis camera; stage
+    /// scales are 0.97 on `UI_Human`, 1.04 and 0.7324 (pet) on `UI_Tauren`.
     #[test]
     fn the_glue_stage_bones_carry_the_scenes_authored_rotation_and_scale() {
         let data = crate::wow_data_or_skip!();
@@ -1099,9 +884,8 @@ mod tests {
                     .bone
             };
             let gs_all = parse_m2_global_sequence_bones(&bytes);
-            // The **scale** half of the same bone matrix: the reference composes the whole thing
-            // (`T(att.pos) · parentBone[att.bone]`), so a stage that parks a scale resizes what
-            // stands on it. Two scenes do — and 1536 read them as unkeyed pivots.
+            // The reference composes the whole bone matrix (`T(att.pos) · parentBone[att.bone]`),
+            // so a parked scale resizes what stands on it.
             let scale_of = |bone: u16| -> f32 {
                 gs_all
                     .iter()
@@ -1126,8 +910,7 @@ mod tests {
                 .find(|a| a.id == 0)
                 .unwrap_or_else(|| panic!("UI_{token} has a stage attachment"));
 
-            // The stage bones are roots on every shipped scene, so the chain is one link; walking
-            // it anyway keeps the assertion honest if a scene ever nests one.
+            // Every shipped stage bone is a root; the walk covers a nested one.
             let gs = parse_m2_global_sequence_bones(&bytes);
             let mut yaw = 0.0_f32;
             let mut bone = stage.bone as i16;
@@ -1161,11 +944,8 @@ mod tests {
         }
     }
 
-    /// An empty band still poses the bone instead of dropping the track (decision 0133's tilt):
-    /// HumanMale bone 27 (waist) rot has 4 keys, all outside Run's band, and `ranges[Run] = (2, 3)`
-    /// brackets it — so the clip must carry the bracketed value as a constant, or a Stand-variation
-    /// twist rides through the entire run. And the guarantee that makes it total: on every sequence
-    /// of the model, any bone keyed *anywhere* stays keyed.
+    /// HumanMale's waist (bone 27) keys rotation only outside Run's band, which `ranges[Run]`
+    /// brackets as `(2, 3)`, so Run carries that value. A bone keyed anywhere is keyed in all.
     #[test]
     fn empty_band_poses_the_bone_and_never_drops_it() {
         let data = crate::wow_data_or_skip!();
@@ -1175,7 +955,6 @@ mod tests {
             .expect("read HumanMale.m2");
         let seqs = parse_m2_animations(&bytes);
 
-        // Run (anim 5): bone 27's rotation must be present as a lone constant key.
         let run = seqs
             .iter()
             .find(|s| s.anim_id == 5)
@@ -1192,7 +971,6 @@ mod tests {
         );
         assert_eq!(waist.rotation[0].0, 0.0);
 
-        // Totality: a bone keyed in ANY sequence is keyed in EVERY sequence (per channel family).
         let mut keyed = [
             std::collections::HashSet::new(),
             std::collections::HashSet::new(),
@@ -1228,16 +1006,8 @@ mod tests {
         }
     }
 
-    /// The one place in the whole 1.12.1 corpus where the file's key window and decision 0133's
-    /// nearest-key approximation disagree (`benilla-extract bonescan`: 9 of 210 368 empty band-slots,
-    /// all three `Creature\Zombie` models) — and it disagrees for a reason worth pinning.
-    ///
-    /// `Zombie.m2` bone 0 (the root) translation is a **step** track (`interp == 0`) with two keys:
-    /// `3333 = (0,0,0)` and `30000 = (0.0047, 0, 0)`. Walk's band `[26667, 27333]` keys nothing and
-    /// sits nearer the *second* key in time, so "nearest authored key" hands back a value the
-    /// reference has not stepped to yet — a key from the future. The reference searches `ranges[slot]
-    /// = (0, 1)`, takes `k0` = the last key at or before the time (key 0), and — being a step track —
-    /// copies it. Small in yards, wrong in direction, and only the file's own window gets it right.
+    /// `Zombie.m2`'s root translation steps from `(0,0,0)` (3333 ms) to `(0.0047,0,0)` (30000 ms);
+    /// Walk's empty band `[26667, 27333]` sits nearer the second, but `ranges` holds key 0.
     #[test]
     fn empty_band_takes_the_window_key_not_a_later_one() {
         let data = crate::wow_data_or_skip!();
@@ -1269,13 +1039,8 @@ mod tests {
         }
     }
 
-    /// The weapon grip, which now reads through the shared window kernel rather than its own key
-    /// scan: HandsClosed on `HumanMale.m2` is the 33 ms band `[60000, 60033]`, which keys nothing on
-    /// finger bone 102 — its window brackets it with the keys at 43333/70000 ms, both the same
-    /// curled quaternion, so the pose the overlay wears is that curl and not the rest pose. The
-    /// substitution is a measured no-op: across the eight playable-race models with a HandsClosed
-    /// sequence, all 460 finger-capable rotation tracks give the same quaternion under the old
-    /// at-or-before clamp and under the window (decision 0643).
+    /// HandsClosed on `HumanMale.m2` is the 33 ms band `[60000, 60033]`, which keys nothing on
+    /// finger bone 102; its window brackets it with the same curl at 43333 and 70000 ms.
     #[test]
     fn hand_grip_reads_the_curled_pose_through_the_window() {
         let data = crate::wow_data_or_skip!();
@@ -1295,12 +1060,7 @@ mod tests {
         }
     }
 
-    /// The invariant that makes reading `interpolation_ranges` safe at all, pinned on the model
-    /// decision 0133 named as the counter-example (`Bear`, which froze at a garbage pose when an
-    /// earlier parse treated the window's far bracket as a *playable in-clip key* — it is a
-    /// bracket, 14–64 s away). Two halves: no emitted keyframe may fall outside its own clip, and a
-    /// sequence that keys a bone must carry every one of that band's own keys. Corpus-wide the
-    /// first half is `bonescan`'s "band keys OUTSIDE their own ranges window: 0".
+    /// A key window's far bracket can sit 14–64 s away (`Bear`) and must not enter the clip.
     #[test]
     fn no_clip_carries_a_key_from_another_sequences_band() {
         let data = crate::wow_data_or_skip!();
@@ -1334,17 +1094,8 @@ mod tests {
         }
     }
 
-    /// **The billboard host of a particle emitter's bone chain** (decision 0813), on the two real
-    /// assets that opened it. `Field Marshal's Chain Spaulders` (display 32092 — nazriel's B118
-    /// item) authors a 4-bone chain whose only billboard bone is bone **1** (flags `0x08`,
-    /// spherical), with the two sparkle emitters hanging off its children 2 and 3. Neither emitter
-    /// bone carries the flag, so a consumer that asks only about the emitter's OWN bone sees an
-    /// ordinary rest-pose frame and puts the sparkle ~0.24 yd from where the reference draws it.
-    ///
-    /// Also pins the authoring pattern the offset is measured against: each emitter's record
-    /// `position` **is** its own bone's pivot, so `position − host.pivot` is the chain offset the
-    /// camera basis rotates. And the held torch — the other shipped case — is the same shape one
-    /// generation shallower (emitter on bone 10, host bone 2, a 0.097 yd offset).
+    /// `LShoulder_Mail_PVPAlliance_C_01.m2`: two sparkle emitters on bones 2 and 3 under billboard
+    /// bone 1, each at its own pivot ~0.24 yd from the host's; the held torch is bone 10 under 2.
     #[test]
     fn real_pvp_shoulder_emitters_ride_a_billboard_bone() {
         let data = crate::wow_data_or_skip!();
@@ -1378,7 +1129,6 @@ mod tests {
                 Some(1),
                 "so the host is their parent"
             );
-            // The record position IS the emitter bone's own pivot (the exporter's pattern).
             for c in 0..3 {
                 assert!(
                     (em.position[c] - skel.bones[bone].pivot[c]).abs() < 1e-3,
@@ -1387,8 +1137,6 @@ mod tests {
                     skel.bones[bone].pivot
                 );
             }
-            // …and it sits ~0.24 yd from the host pivot — the offset the camera basis rotates,
-            // i.e. how far a rest-pose placement misses by.
             let d: f32 = (0..3)
                 .map(|c| (em.position[c] - skel.bones[1].pivot[c]).powi(2))
                 .sum();
@@ -1398,7 +1146,6 @@ mod tests {
                 d.sqrt()
             );
         }
-        // The held torch: same mechanism, emitter on bone 10 under billboard bone 2.
         let torch = chain
             .read_file("Item\\ObjectComponents\\Weapon\\Club_1H_Torch_A_01.m2")
             .expect("read the torch");
@@ -1411,21 +1158,13 @@ mod tests {
             tskel.bones[2].billboard,
             Some(crate::BillboardKind::Spherical)
         );
-        // A bone with no billboard anywhere above it has no host (bone 0, the model root).
+        // Bone 0, the root, has no billboard above it; an out-of-range index is `None`.
         assert_eq!(skel.billboard_host(0), None);
-        // …and an out-of-range bone index is a `None`, never a panic.
         assert_eq!(skel.billboard_host(999), None);
     }
 
-    /// **An effect model can be pure camera-facing geometry with no emitters at all** — the premise
-    /// that makes a consumer's "keep the meshes, carry the emitters" split wrong on its own.
-    ///
-    /// `Spells\Enchantments\Sparkle_A.m2` is the shipped proof: **one** bone, spherical billboard
-    /// (flags `0x08`), **zero** particle emitters and zero ribbons — the whole model is a single
-    /// additive quad that faces the camera. `ItemVisuals` 28 hangs it on slot 4, and 10 of the 29604
-    /// `ItemDisplayInfo` rows carry that visual, so a preview path that drops billboard batches and
-    /// keeps only emitters renders *nothing whatsoever* for those items (the select-screen half of
-    /// `#bugs` B118). Pinned here because the mistake is invisible in code that reads correct.
+    /// `Sparkle_A.m2` (`ItemVisuals` 28) is one spherical-billboard bone and no emitters or
+    /// ribbons: a preview keeping only emitters draws nothing for it.
     #[test]
     fn a_real_item_glow_model_is_pure_billboard_geometry_with_no_emitters() {
         let data = crate::wow_data_or_skip!();
@@ -1457,21 +1196,8 @@ mod tests {
 
 #[cfg(test)]
 mod doodad_sound_tests {
-    /// **The humming lamp, off the real 5875 chain** — bug B345's diagnosis, pinned as data.
-    ///
-    /// `KalidarStreetLamp01.m2` is the shape the whole doodad-ambience class takes, and every
-    /// clause here is a claim the fix rests on:
-    ///
-    /// * it has **one** sequence, `AnimationData` id 0 (Stand), **looping** — so the marker on it
-    ///   is crossed once per cycle, for ever;
-    /// * that sequence is **rest-posed** — it keys no bone at all, so decision 0130's render
-    ///   content gate builds it no rig, which is correct about pixels and was never a statement
-    ///   about the clock. Gating the *event* track on that gate is what made the lamp silent;
-    /// * it carries exactly **one** event, `$DSL` at t = 0.000 with payload **3378** — the
-    ///   `SoundEntries` id of `NightElfStreetLampLoop`.
-    ///
-    /// If any of these stops holding, the fix's premise has moved and the test should fail loudly
-    /// rather than let the lamp go quiet again.
+    /// `KalidarStreetLamp01.m2`: one looping Stand keying no bone, so no rig, and one `$DSL` at
+    /// t = 0 (SoundEntries 3378): the event track must not follow the rig gate.
     #[test]
     fn the_lamps_hum_is_one_rest_posed_looping_dsl_key() {
         let data = crate::wow_data_or_skip!();
@@ -1497,19 +1223,9 @@ mod doodad_sound_tests {
         assert!(ev.time.abs() < 1e-6, "keyed at t = 0");
     }
 
-    /// **The pair that pins the one-handle-per-doodad slot.** `bellows.m2` keys TWO `$DSL` at
-    /// DIFFERENT times on one looping 2 s sequence — `BellowOut` at t = 0.000 and `BellowIN` at
-    /// t = 1.100, each about 1.18 s of audio.
-    ///
-    /// This looked like proof that `$DSL` could not mean "loop" — a pair of one-shots timed to
-    /// alternate. The RE says otherwise, and the real mechanism is better: a doodad holds exactly
-    /// ONE registration (`[CMapDoodadDef+0x168]`), and crossing a marker with a DIFFERENT id
-    /// releases the held one before registering the new (`0x69521d` → `0x461f80`). So both ARE
-    /// ordinary loops, and the slot is what makes them alternate — the pumping bellows. Every
-    /// `$DSL` loops and no flag is consulted (wow-re `sound/scratch/doodad-sound-emitters.md`).
-    ///
-    /// The guard is therefore on the eviction in `sound::anim_events`: without it both start and
-    /// both drone.
+    /// `bellows.m2` keys two `$DSL` at t = 0 and 1.1 on one 2 s loop. Each loops (`0x7a54d0`),
+    /// but a doodad holds one registration (`[CMapDoodadDef+0x168]`) and a marker with another id
+    /// releases it first (`0x69521d` → `0x461f80`), so the pair alternates (`sound::anim_events`).
     #[test]
     fn a_dsl_pair_on_one_cycle_alternates_through_one_slot() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/models/anim_summary.rs b/crates/benilla-formats/src/models/anim_summary.rs
index 31b672fa..8e6b1540 100644
--- a/crates/benilla-formats/src/models/anim_summary.rs
+++ b/crates/benilla-formats/src/models/anim_summary.rs
@@ -1,11 +1,5 @@
-//! Per-model **animation-channel summary** — how much of an M2 actually animates, across every
-//! channel family the renderer might ever drive (bone sequences, global-sequence bones, transparency/
-//! color tracks, texture transforms, particle/ribbon emitters). Split out of [`super::anim`] as its
-//! own concern: the rest of that module parses the skeleton + a *playing* sequence's keyframes for the
-//! render/skin path; this one is a read-only diagnostic over the *whole* model, built to ground the
-//! doodad-animation scope/perf decision (`benilla-extract m2anim`/`doodadscan`) — most placed doodads
-//! (trees, rocks, fences, wall props) carry zero animated channels and can render as static meshes
-//! forever, and this is the instrument that counts how many actually don't, and by which mechanism.
+//! An M2's animation-channel summary, telling a doodad that can render as a static mesh from one
+//! that animates, and by which channel (`benilla-extract m2anim`, `doodadscan`).
 
 use std::io::Cursor;
 
@@ -16,13 +10,8 @@ use crate::Chain;
 
 use super::{le_u32, model_path, parse_m2_animations, parse_m2_global_sequence_bones};
 
-/// Raw header read: the model's **texture-transform** (UV-animation) array count — MD20 `0x74`
-/// (count) / `0x78` (offset). VERIFIED wow-5875-re (`system/models/models.md`'s full 32-descriptor
-/// header field map labels this slot `texReplace@0x74`, and the element-def section separately
-/// confirms it IS the textureTransform array: "**textureTransform** (header `0x74`, runtime 0x98) =
-/// 3 M2Tracks translation(vec3) / rotation(quat) / scaling(vec3)" — a UV-space TRS animated over
-/// time). `benilla-m2` doesn't parse the track contents (no consumer yet), so this reads only the
-/// count: whether the model authors any UV animation at all.
+/// The texture-transform (UV animation) array count, MD20 `0x74` (count) / `0x78` (offset), as
+/// the header walk `0x71cdf0` reads it: whether the model authors any UV animation.
 pub fn m2_texture_transform_count(b: &[u8]) -> usize {
     if b.len() < 0x78 || &b[0..4] != b"MD20" {
         return 0;
@@ -30,13 +19,8 @@ pub fn m2_texture_transform_count(b: &[u8]) -> usize {
     le_u32(b, 0x74) as usize
 }
 
-/// Raw header read: the model's **ribbon emitter** array count — MD20 `0x134` (count) / `0x138`
-/// (offset), file stride `0xdc`. VERIFIED wow-5875-re (`system/models/models.md`: "ribbons@0x134" in
-/// the full header field map, corroborated by the emitter-def section's "**ribbon** (header `0x134`,
-/// file stride `0xdc`) → runtime `CRibbonEmitter`" and the loader's own copy loop, `0x70ebd0`
-/// `base+=0xdc @ ribbon 0x138`). Ribbon records aren't parsed here (deferred — wow-re item-12, the
-/// most version-variant MD20 record); the count alone says whether a model authors any trail effect
-/// (weapon glow trails, banner streamers).
+/// The ribbon emitter array count, MD20 `0x134` (count) / `0x138` (offset), file stride `0xdc`
+/// (the header walk `0x71cdf0`, the loader's copy loop `0x70ebd0`); the records are not parsed.
 pub fn m2_ribbon_emitter_count(b: &[u8]) -> usize {
     if b.len() < 0x138 || &b[0..4] != b"MD20" {
         return 0;
@@ -44,15 +28,12 @@ pub fn m2_ribbon_emitter_count(b: &[u8]) -> usize {
     le_u32(b, 0x134) as usize
 }
 
-/// One particle emitter's **bone linkage**: which bone hosts it, and whether that bone's *chain*
-/// (the bone itself or any ancestor — bone motion composes down the hierarchy) actually animates.
-/// The join that grounds emitter bone-follow (0130 phase 4): an emitter on a static chain sits at
-/// the rest pose forever, so only `chain_seq0 || chain_gseq` emitters can visibly move.
+/// A particle emitter's host bone, and whether that bone's chain (itself or any ancestor, since
+/// motion composes down the hierarchy) animates: an emitter on a static chain never moves.
 #[derive(Debug, Clone, Copy)]
 pub struct EmitterBoneLink {
     pub bone: u16,
-    /// The emitter's raw M2 flag word (`+0x04`) — carried for corpus inspection (which simulation-
-    /// space / render modes placed content actually authors), semantics live with the consumer.
+    /// The emitter's raw M2 flag word (`+0x04`).
     pub flags: u32,
     /// A bone in the chain carries a >1-key T/R/S track in sequence 0's band.
     pub chain_seq0: bool,
@@ -61,56 +42,39 @@ pub struct EmitterBoneLink {
 }
 
 impl EmitterBoneLink {
-    /// The emitter's host bone chain animates at all — its emission point moves off the rest pose.
     pub fn chain_animated(&self) -> bool {
         self.chain_seq0 || self.chain_gseq
     }
 }
 
-/// Per-model animation-channel summary (see the module doc).
+/// Per-model animation-channel summary.
 #[derive(Debug, Clone)]
 pub struct M2AnimSummary {
-    /// Sequence count (file order — record count in the `animations` M2Array).
     pub sequence_count: usize,
-    /// Sequence **0** (file order — the model's first-authored sequence, NOT necessarily
-    /// `AnimationData.dbc` id 0/Stand) has at least one bone with a >1-key T/R/S track inside its own
-    /// time band: the model visibly moves when this sequence plays/loops.
+    /// File sequence 0 (not necessarily Stand) has a multi-key bone track in its band.
     pub seq0_has_bone_motion: bool,
-    /// How many distinct bones carry a >1-key track (any of T/R/S) in sequence 0's band.
     pub seq0_animated_bone_count: usize,
-    /// How many sequences share sequence 0's `anim_id` — its **variation chain** length (file-order
-    /// contiguous, retail exporters). The real client's effective load arm rolls `variationIdx = −1`
-    /// (a frequency-weighted pick over this chain, wow-re `doodad-anim-host.md` §4a), so a count > 1
-    /// means instances of this model should NOT all play the same first-sequence variation.
+    /// Sequences sharing sequence 0's `anim_id`, its variation chain. The reference arms with
+    /// `variationIdx = −1`, a frequency-weighted pick over this chain (`0x695100`), so above 1 the
+    /// instances do not all play the same variation.
     pub seq0_variation_count: usize,
-    /// Every bone's **global-sequence** channel: `(bone, "T"/"R"/"S", period_ms)` — a free-running
-    /// loop independent of the playing sequence (see [`super::GlobalSeqBone`]); e.g. the character
-    /// eye-blink.
+    /// Bone global-sequence channels as `(bone, "T"/"R"/"S", period_ms)`, such as the eye-blink.
     pub global_seq_channels: Vec<(u16, &'static str, u32)>,
-    /// `M2Color` **alpha** tracks: `(total records, records with >1 key)`. A constant (≤1 key) track
-    /// never changes, so only the second number reflects real animation.
+    /// `M2Color` alpha tracks as `(total, time-varying)`.
     pub color_alpha_tracks: (usize, usize),
-    /// `M2Color` **RGB** tracks: `(total records, records with >1 key)`.
+    /// `M2Color` RGB tracks as `(total, multi-key)`.
     pub color_rgb_tracks: (usize, usize),
-    /// `M2TextureWeight` transparency tracks: `(total records, records with >1 key)`.
+    /// `M2TextureWeight` tracks as `(total, time-varying)`.
     pub transparency_tracks: (usize, usize),
-    /// Raw header count of the **texture-transform** (UV animation) array (see
-    /// [`m2_texture_transform_count`]) — presence-only, the track contents aren't parsed.
     pub texture_transform_count: usize,
-    /// Particle emitter count ([`crate::parse_m2_particle_emitters`]).
     pub particle_emitter_count: usize,
-    /// Each particle emitter's host bone + whether its chain animates (same order as the emitter
-    /// records; `len() == particle_emitter_count`). See [`EmitterBoneLink`].
+    /// Each emitter's [`EmitterBoneLink`], in emitter record order.
     pub emitter_bones: Vec<EmitterBoneLink>,
-    /// Raw header count of the **ribbon emitter** array (see [`m2_ribbon_emitter_count`]) —
-    /// presence-only, the records aren't parsed.
     pub ribbon_emitter_count: usize,
 }
 
 impl M2AnimSummary {
-    /// `true` iff **no** channel family animates anything: no seq-0 bone motion, no global-sequence
-    /// bones, no animated transparency/color, and no texture transforms/particles/ribbons authored at
-    /// all. Such a model can render as a permanently-static mesh with zero animation cost.
+    /// No channel animates, so the model can render as a static mesh.
     pub fn is_fully_static(&self) -> bool {
         !self.seq0_has_bone_motion
             && self.global_seq_channels.is_empty()
@@ -158,9 +122,8 @@ pub fn parse_m2_animation_summary(bytes: &[u8]) -> Result<M2AnimSummary> {
         }
     }
 
-    // The emitter → bone-chain join (0130 phase 4): which bones move (seq0 band / global
-    // sequence), then walk each emitter's bone up its parent chain — motion composes down the
-    // hierarchy, so an emitter on a static child of a swinging parent still moves.
+    // Which bones move (in sequence 0's band or on a global sequence), then each emitter's bone
+    // walked up its parent chain: an emitter on a static child of a swinging parent still moves.
     let seq0_bones: std::collections::HashSet<u16> = seqs
         .first()
         .map(|seq0| {
@@ -177,10 +140,10 @@ pub fn parse_m2_animation_summary(bytes: &[u8]) -> Result<M2AnimSummary> {
     let chain_flags = |bone: u16| -> (bool, bool) {
         let (mut seq0, mut gseq) = (false, false);
         let mut b = bone;
-        // Hop guard: a malformed parent loop can't spin us — a real chain is ≤ bone count deep.
+        // Bounded by the bone count, so a malformed parent loop cannot spin.
         for _ in 0..=skeleton.bones.len() {
             let Some(rec) = skeleton.bones.get(b as usize) else {
-                break; // out-of-range host bone (or -1 parent cast) — chain ends
+                break; // an out-of-range bone ends the chain
             };
             seq0 |= seq0_bones.contains(&b);
             gseq |= gseq_bones.contains(&b);
@@ -204,8 +167,7 @@ pub fn parse_m2_animation_summary(bytes: &[u8]) -> Result<M2AnimSummary> {
         })
         .collect();
 
-    // A track is "animated" iff it is genuinely time-varying — multi-key AND not all-equal (an
-    // all-equal multi-key track is a constant the renderer folds statically).
+    // Time-varying: more than one key, not all equal (an all-equal track is a folded constant).
     let count_animated = |tracks: &[benilla_m2::M2ScalarTrack]| -> (usize, usize) {
         (
             tracks.len(),
@@ -239,9 +201,7 @@ pub fn parse_m2_animation_summary(bytes: &[u8]) -> Result<M2AnimSummary> {
     })
 }
 
-/// Read an M2's animation-channel summary from the chain (see [`M2AnimSummary`]). Uses the same path
-/// normalisation as [`load_m2_mesh`](super::load_m2_mesh) so `.mdx`/`.mdl` doodad paths (MDDF/MODD)
-/// resolve identically.
+/// Read an M2's animation-channel summary from the chain, by model or doodad (`.mdx`/`.mdl`) path.
 pub fn load_m2_animation_summary(chain: &mut Chain, raw_path: &str) -> Result<M2AnimSummary> {
     let path = model_path(raw_path);
     let bytes = chain
@@ -255,9 +215,7 @@ pub fn load_m2_animation_summary(chain: &mut Chain, raw_path: &str) -> Result<M2
 mod tests {
     use super::*;
 
-    /// A minimal MD20 header (0x138 bytes — through the ribbon array descriptor) with the
-    /// texture-transform count at `0x74` and the ribbon count at `0x134` — the two raw header reads
-    /// [`m2_texture_transform_count`]/[`m2_ribbon_emitter_count`] guard against an offset regression.
+    /// A minimal MD20 header through the ribbon array, with the two counts set.
     fn header_with_counts(tex_transform_count: u32, ribbon_count: u32) -> Vec<u8> {
         let mut b = vec![0u8; 0x138];
         b[0..4].copy_from_slice(b"MD20");
@@ -287,9 +245,6 @@ mod tests {
         assert_eq!(m2_ribbon_emitter_count(&not_md20), 0);
     }
 
-    /// A hermetic (no real client data required) end-to-end check of [`parse_m2_animation_summary`]'s
-    /// static/dynamic classification: an all-zero-array header (no sequences, no bones, no emitters, no
-    /// transforms) must report fully static with every count at zero.
     #[test]
     fn empty_model_summary_is_fully_static() {
         let b = header_with_counts(0, 0);
diff --git a/crates/benilla-formats/src/models/art_extent.rs b/crates/benilla-formats/src/models/art_extent.rs
index acf57cab..d073547c 100644
--- a/crates/benilla-formats/src/models/art_extent.rs
+++ b/crates/benilla-formats/src/models/art_extent.rs
@@ -1,54 +1,8 @@
-//! The **art extent** of a glue scene — how far its art actually paints around its authored
-//! camera, measured off the geometry and the textures (decision 1619).
-//!
-//! Every `UI_<Race>` / `UI_MainMenu` diorama was composed for a 4:3 screen (1587: the Lua design
-//! space is `1024×768`), and its backdrop is *finite*: a sky card of some authored width, a ground
-//! plane that stops. A camera law that widens the view on a wide window (1587's hor+) keeps showing
-//! more of the diorama until the art runs out — and past that edge the frame is the render target's
-//! clear colour, which no taste calls a composition (B330: `UI_MainMenu`'s backdrop edges show at
-//! 16:9, `UI_Tauren`'s at ~2.24:1). The reference never shows that void only because it never
-//! widens; it zooms instead (0116/1543's diagonal-FOV law) and crops the character at 21:9 (B242).
-//!
-//! So the framing law needs one more authored fact per scene: **how wide is the art**. This module
-//! measures it. In camera 0's own tan-space — `x' = x/z`, `y' = y/z` in a right-handed eye frame,
-//! the space a projection's half-extents live in — it rasterises every batch that paints into a
-//! coverage grid and asks:
-//!
-//! - across the authored **vertical** opening (`±tan(fovy/2)` at 4:3), what horizontal half-width
-//!   does *every* row reach, left and right of the axis? → [`ArtExtent::half_w`]
-//! - across the authored **horizontal** opening, what vertical half-height does every column
-//!   reach? → [`ArtExtent::half_h`]
-//!
-//! The minimum over rows is the point: a sky card seen in perspective is a trapezoid on screen, and
-//! the frame runs out of it at the *narrow* row first (MainMenu's edges slant inward toward the
-//! top).
-//!
-//! **What counts as painted is the texel, not the batch.** An `Opaque` batch paints every pixel it
-//! covers. A `Blend`/`AlphaTest` batch paints where its texture's alpha would pass the reference's
-//! own alpha test — **`≥ 224/255`**, the 1.12 alpha-key reference (wow-re `models.md`, not Cata's
-//! 128) — sampled per pixel through the batch's UVs, perspective-correct, with its wrap/clamp mode.
-//! Both halves of that rule matter on the real art: the artists drew `UI_Human`'s street and its
-//! sky card as *blend* batches over opaque textures (so "opaque batches only" measured that scene
-//! at half its authored box), and `UI_NightElf`'s edges are an alpha-tested wall of trees over a
-//! sky card that ends at exactly 4:3 (so "opaque textures only" measured it a full step narrower
-//! than what is on screen). A cloud, a canopy, a ground shadow, `UI_Tauren`'s 0.55 corner vignette
-//! paint only where their texels pass, which is nowhere at their soft edges — the void this
-//! measures for. `Mod`/`Mod2x` only tint what is already drawn. Backfaces of single-sided batches
-//! are skipped the way the renderer skips them (`Face::Back` cull, CCW front — the model's own
-//! winding survives the axis remap, a proper rotation), so a ground plane seen from below does not
-//! count as sky.
-//!
-//! Because the rule reads textures, the measurement runs **offline**, off the chain: `benilla-
-//! extract glueextent` prints every scene's numbers, and the client carries them as
-//! [`shipped_glue_art_extent`] — a transcription of the shipped 1.12.1 art's authored width,
-//! pinned by [`tests::the_shipped_table_matches_the_measurement`], which re-measures every scene
-//! against the table. (A runtime probe at scene spawn would have to wait for every batch texture
-//! to land before it could answer, and until it answered the login gate would open with its void
-//! edges showing, then snap.)
-//!
-//! Positions are the M2's own model space (WoW axes, Z up) and so is the camera — nothing here
-//! needs the engine's frame. The consumer ([`benilla`]'s glue framing) turns the two numbers into a
-//! ceiling on 1587's law.
+//! The art extent of a glue scene: how far its art paints around camera 0, texel by texel. The
+//! glue framing widens past 4:3 (hor+) where the reference zooms on its diagonal-FOV law, and a
+//! diorama's art is finite, so past its edge the frame would show the clear colour. Reading
+//! textures makes this an offline measurement (`benilla-extract glueextent`), shipped as
+//! [`SHIPPED_GLUE_SCENES`]. Model space throughout (WoW axes, Z up).
 
 use std::collections::HashMap;
 use std::sync::Arc;
@@ -59,53 +13,24 @@ use super::records::M2PortraitCamera;
 use super::types::{ModelBlend, RenderSubmesh};
 use crate::Chain;
 
-/// How far a scene's art paints around its authored camera, as projection-space half-extents
-/// (tan units — the same space `tan(fov/2)` lives in).
-///
-/// `half_w` is measured across the authored 4:3 **vertical** opening, `half_h` across the authored
-/// **horizontal** one: each is the widest symmetric box of *that* shape the art still fills. A scene
-/// whose art does not even fill the authored box (an axis row with no painted pixel over it)
-/// reports `0.0` on that axis — the consumer clamps to the authored extent, never below it.
+/// The tan-space half-extents the art fills: `half_w` across the authored 4:3 vertical opening,
+/// `half_h` across the horizontal one, `0.0` where it does not fill even the authored box.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ArtExtent {
     pub half_w: f32,
     pub half_h: f32,
 }
 
-/// The authored aspect every glue composition was made for (1587, `1024×768`).
+/// The aspect every glue composition was made for, the `1024×768` design space.
 pub const GLUE_AUTHORED_ASPECT: f32 = 4.0 / 3.0;
 
-/// The 1.12 client's alpha-key reference: a texel passes its alpha test at `alpha ≥ 224`
-/// (wow-re `models.md` — `ALPHAREF` 224, `GEQUAL`). The one threshold this module paints by.
+/// The 1.12 client's alpha test passes a texel at `alpha ≥ 224` (`0x70c256`, `GEQUAL`).
 pub const ALPHA_KEY_REF: u8 = 224;
 
-/// The **shipped** scenes' measured extents and authored fovs — `benilla-extract glueextent` on
-/// the 1.12.1 (5875) chain, transcribed. Keyed by the scene token (`UI_<token>.m2`). The test
-/// re-measures them.
-///
-/// Read as aspects (`half_w / t0`, the window aspect past which the art runs out of width under
-/// the authored vertical): MainMenu 1.54 · Human 1.47 · Orc 1.57 · Dwarf 1.42 · NightElf 1.31 ·
-/// Scourge 1.57 · Tauren 1.46 — every one of the seven runs out **before 16:9**. Not one diorama
-/// was drawn wider than about 3:2; the reference never showed it because its diagonal law zooms
-/// from 4:3 onward.
-///
-/// `UI_NightElf` is the odd one on both axes, and honestly so: its sky card is exactly 4:3 wide,
-/// and its `half_h` is *inside* the authored box — the gaps between its tree-cutout leaves at the
-/// frame's sides paint nothing even at 4:3. Both are the artist's intent: it is a night scene, and
-/// what shows through is the page behind the scene, near-black, read as sky. The framing law never
-/// opens past the authored box on an axis the art does not reach, so the number costs nothing
-/// there.
-/// One degree in radians — the unit the `UI_*` cameras were dialled in. Every one of the seven
-/// authored fovs is a whole number of degrees, to the last bit of the `f32` the M2 carries
-/// (`benilla-extract glueextent`: 86°, 80°, 65°, 60°), so the table says so rather than
-/// transcribing decimals.
+/// One degree: every authored glue fov is a whole number of degrees, to the last `f32` bit.
 const DEG: f32 = std::f32::consts::PI / 180.0;
 
-/// One shipped glue scene, as the framing law needs it: the scene token, its authored camera-0
-/// **fov** ([`DEG`] — 86° on the gate, 80° on the human street, 65° on the four orc-family
-/// stages, 60° in the night elf grove), and the measured
-/// [`ArtExtent`]. The fov rides the table because the framing constant is derived from it
-/// ([`benilla`]'s `GLUE_BOX_ASPECT`) and both halves are re-measured by the same chain test.
+/// A shipped scene; its fov rides along because the app's `GLUE_BOX_ASPECT` derives from it.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ShippedGlueScene {
     pub token: &'static str,
@@ -113,8 +38,9 @@ pub struct ShippedGlueScene {
     pub art: ArtExtent,
 }
 
-/// The seven shipped scenes: the login gate plus the six race stages (Gnome shares Dwarf's,
-/// Troll shares Orc's). See [`ShippedGlueScene`].
+/// The seven shipped scenes (Gnome shares Dwarf's, Troll Orc's), re-measured by a chain test.
+/// Every one runs out of width before 16:9. `UI_NightElf`'s `half_h` is inside the authored box:
+/// the gaps between its tree cutouts paint nothing even at 4:3, and read as night sky.
 pub const SHIPPED_GLUE_SCENES: [ShippedGlueScene; 7] = [
     ShippedGlueScene {
         token: "MainMenu",
@@ -174,8 +100,7 @@ pub const SHIPPED_GLUE_SCENES: [ShippedGlueScene; 7] = [
     },
 ];
 
-/// The shipped scene's measured [`ArtExtent`] by token, `None` for a token that is not one of
-/// the seven `UI_*` dioramas (the consumer then keeps 1587's unbounded law).
+/// A shipped scene's measured [`ArtExtent`] by token; `None` for any other token.
 pub fn shipped_glue_art_extent(token: &str) -> Option<ArtExtent> {
     SHIPPED_GLUE_SCENES
         .iter()
@@ -183,8 +108,7 @@ pub fn shipped_glue_art_extent(token: &str) -> Option<ArtExtent> {
         .map(|s| s.art)
 }
 
-/// The authored **vertical** half-extent (tan units) of a glue camera's `fov` at 4:3 — the number
-/// 1587's law pins: `tan(fovy/2)` with `fovy = fov/√((4/3)²+1)`.
+/// A glue camera's authored vertical half-extent at 4:3, `tan(fovy/2)`, `fovy = fov/√((4/3)²+1)`.
 pub fn authored_half_height(fov: f32) -> f32 {
     (fov / (GLUE_AUTHORED_ASPECT * GLUE_AUTHORED_ASPECT + 1.0).sqrt() * 0.5).tan()
 }
@@ -192,10 +116,9 @@ pub fn authored_half_height(fov: f32) -> f32 {
 /// How a batch paints the pixels it covers.
 #[derive(Clone, Debug)]
 pub enum Coverage {
-    /// Every covered pixel is painted (an opaque batch, or a blend over a texture with no alpha
-    /// below the key).
+    /// Every covered pixel paints: an opaque batch, or a texture never below the key.
     Full,
-    /// Painted where the texture's alpha, sampled through the batch's UVs, is `≥` [`ALPHA_KEY_REF`].
+    /// Painted where the texture's alpha through the batch's UVs is `≥` [`ALPHA_KEY_REF`].
     Alpha(Arc<AlphaMap>),
 }
 
@@ -209,8 +132,7 @@ pub struct AlphaMap {
 }
 
 impl AlphaMap {
-    /// The alpha at `(u, v)` under the batch's wrap (`true`) or clamp-to-edge (`false`) modes,
-    /// nearest texel — the same texel the sampler's mip 0 would return at its centre.
+    /// The nearest texel's alpha at `(u, v)`, each axis wrapping (`true`) or clamping to the edge.
     fn sample(&self, u: f32, v: f32, wrap_x: bool, wrap_y: bool) -> u8 {
         let axis = |t: f32, n: u32, wrap: bool| -> u32 {
             let t = if wrap {
@@ -229,9 +151,8 @@ impl AlphaMap {
     }
 }
 
-/// The coverage rule with the chain in hand: `Opaque` → [`Coverage::Full`]; `Blend`/`AlphaTest`
-/// → the texture's alpha, read once per path (a texture that never dips below the key collapses
-/// to `Full`); no texture, or `Mod`/`Mod2x` → `None` (paints nothing that counts).
+/// The coverage rule off the chain: `Opaque` paints, `Blend`/`AlphaTest` paint by the texture's
+/// alpha (read once per path), and `Mod`/`Mod2x` or a missing texture count for nothing.
 pub struct CoverageReader<'c> {
     chain: &'c mut Chain,
     cache: HashMap<String, Option<Coverage>>,
@@ -245,7 +166,6 @@ impl<'c> CoverageReader<'c> {
         }
     }
 
-    /// How `sub` paints, or `None` when it counts for nothing.
     pub fn coverage(&mut self, sub: &RenderSubmesh) -> Result<Option<Coverage>> {
         match sub.blend {
             ModelBlend::Opaque => Ok(Some(Coverage::Full)),
@@ -277,11 +197,8 @@ impl<'c> CoverageReader<'c> {
     }
 }
 
-/// Measure a scene's [`ArtExtent`]: its batches, its authored camera, and how each batch paints
-/// (`coverage` — [`CoverageReader::coverage`] with the chain, or anything a test hands in).
-///
-/// Front faces only unless two-sided; triangles are clipped to the camera's own near plane,
-/// exactly as the render would clip them.
+/// Measure a scene's [`ArtExtent`]: the half-width every row reaches, the half-height every column
+/// does. The narrowest row decides, as a sky card in perspective is a trapezoid.
 pub fn glue_art_extent<'a>(
     subs: impl IntoIterator<Item = &'a RenderSubmesh>,
     cam: &M2PortraitCamera,
@@ -303,10 +220,8 @@ pub fn glue_art_extent<'a>(
     }
 }
 
-/// The coverage grid over the camera's tan-space: `x' ∈ ±X_SPAN·t0`, `y' ∈ ±Y_SPAN·t0`. The spans
-/// cover what the framing law can ask for — a wide window holds the width at the art's edge, and
-/// the widest edge any diorama has is under `2·t0`; a narrow window opens the height up to the
-/// art's, and `2.7·t0` is a 1:2 window.
+/// The coverage grid over tan-space, `x' ∈ ±X_SPAN·t0`, `y' ∈ ±Y_SPAN·t0`: no diorama's edge is
+/// as far out as `2·t0`, and `2.7·t0` of height is a 1:2 window.
 struct Grid {
     cells: Vec<bool>,
     /// Tan units per cell, both axes.
@@ -316,10 +231,7 @@ struct Grid {
     y_lo: f32,
 }
 
-/// Cells per axis. Even, so the axis (`x' = 0`, `y' = 0`) is a cell boundary and the run around
-/// it is read symmetrically. 2048 cells over `4.4·t0` is `0.0021·t0` per cell — 1.5 px at 1440p —
-/// and the reported extent is shortened by half a cell, so the quantisation only ever
-/// under-reports.
+/// Cells per axis, even so the axis is a cell boundary: `0.0021·t0` a cell, 1.5 px at 1440p.
 const CELLS: usize = 2048;
 const X_SPAN: f32 = 2.2;
 const Y_SPAN: f32 = 2.7;
@@ -337,7 +249,6 @@ impl Grid {
         }
     }
 
-    /// Rasterise every front-facing, near-clipped triangle of `sub` into the grid.
     fn paint_batch(&mut self, sub: &RenderSubmesh, frame: &EyeFrame, near: f32, cov: &Coverage) {
         for tri in sub.indices.as_chunks::<3>().0 {
             let Some(eye) = tri
@@ -421,9 +332,8 @@ impl Grid {
         }
     }
 
-    /// The largest half-extent along `axis` that every scanline across the authored opening
-    /// (`±opening` on the other axis) reaches on both sides of the axis. `0.0` if any scanline
-    /// leaves the axis unpainted. Shortened by half a cell, so quantisation under-reports.
+    /// The largest half-extent along `axis` that every scanline within `±opening` reaches on both
+    /// sides, `0.0` if any leaves the axis unpainted; half a cell short, so it never over-reports.
     fn half_extent(&self, axis: Axis, opening: f32) -> f32 {
         let (lines, cells_per_line, step, lo, line_step) = match axis {
             Axis::Row => (CELLS, CELLS, self.dx, self.y_lo, self.dy),
@@ -471,7 +381,6 @@ enum Axis {
     Column,
 }
 
-/// A projected vertex with what perspective-correct interpolation needs.
 #[derive(Clone, Copy)]
 struct Vert {
     x: f32,
@@ -486,26 +395,24 @@ fn edge(a: &Vert, b: &Vert, x: f32, y: f32) -> f32 {
     (b.x - a.x) * (y - a.y) - (b.y - a.y) * (x - a.x)
 }
 
-/// Twice the signed area of a projected triangle — positive for counter-clockwise.
+/// Twice the signed area of a projected triangle, positive for counter-clockwise.
 fn signed_area(t: &[Vert; 3]) -> f32 {
     edge(&t[0], &t[1], t[2].x, t[2].y)
 }
 
-/// Where ONE batch lands in the camera's tan-space — the per-batch diagnostic beside
-/// [`glue_art_extent`]: how many of its triangles face the camera (and so can paint), how many
-/// face away, and the box its front faces cover. `benilla-extract glueextent --batches` prints it,
-/// so a measured edge can be traced to the card that sets it.
+/// Where one batch lands in the camera's tan-space, to trace a measured edge to the card that
+/// sets it (`benilla-extract glueextent --batches`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct BatchFootprint {
     /// Triangles in front of the near plane that face the camera (or are two-sided).
     pub front: usize,
-    /// Single-sided triangles facing away — culled by the renderer, painting nothing.
+    /// Single-sided triangles facing away, which the renderer culls.
     pub back: usize,
     /// Clipped away entirely (behind the near plane).
     pub clipped: usize,
     /// The front faces' `x'` range, `None` with no front face.
     pub x: Option<(f32, f32)>,
-    /// …and `y'` range.
+    /// The front faces' `y'` range.
     pub y: Option<(f32, f32)>,
 }
 
@@ -561,11 +468,10 @@ pub fn batch_footprint(sub: &RenderSubmesh, cam: &M2PortraitCamera) -> BatchFoot
     fp
 }
 
-/// An eye-space vertex `(x, y, depth)` with its UV — the unit `clip_near` works on.
+/// An eye-space vertex `(x, y, depth)` with its UV.
 type EyeVert = ((f32, f32, f32), [f32; 2]);
 
-/// Clip an eye-space triangle against `depth = near` (keep `depth ≥ near`), fanning the resulting
-/// polygon (0, 3 or 4 vertices) back into triangles. UVs are interpolated with the position.
+/// Clip an eye-space triangle to `depth ≥ near`, fanning what is left back into triangles.
 fn clip_near(tri: &[EyeVert], near: f32) -> Vec<[EyeVert; 3]> {
     let inside = |p: &EyeVert| p.0 .2 >= near;
     let mut poly: Vec<EyeVert> = Vec::with_capacity(4);
@@ -592,12 +498,9 @@ fn clip_near(tri: &[EyeVert], near: f32) -> Vec<[EyeVert; 3]> {
     }
 }
 
-/// The camera's eye frame in model space: `right`, `up`, `forward` unit vectors + the eye.
-///
-/// Mirrors the engine's `Transform::looking_at(target, up)` with `up = roll about forward ⋅ +Z`
-/// (the glue booth's own rig): `forward = target − eye`, `right = forward × up`, `up' = right ×
-/// forward`. Model space is WoW's (Z up); the engine's remap is a proper rotation, so cross
-/// products — and with them winding — agree between the two frames.
+/// The camera's eye frame in model space, as the glue booth's `Transform::looking_at` rig builds
+/// it with `+Z` rolled about forward as up. The engine's axis remap is a proper rotation, so
+/// winding agrees between the two frames.
 struct EyeFrame {
     eye: [f32; 3],
     right: [f32; 3],
@@ -626,7 +529,6 @@ impl EyeFrame {
     }
 }
 
-/// WoW model space is Z-up.
 const WOW_UP: [f32; 3] = [0.0, 0.0, 1.0];
 
 // ---- small vector helpers (model space; no engine types in this crate) ----
@@ -683,12 +585,9 @@ mod tests {
         }
     }
 
-    /// An axis-aligned card facing the camera at depth `d`, spanning `±w` horizontally (world −Y
-    /// is screen right) and `±h` vertically (Z), wound CCW as seen from the camera, UVs
-    /// `(0,0)` at screen left-bottom to `(1,1)` at right-top.
+    /// A card facing the camera at depth `d`, `±w` wide (world −Y is screen right) and `±h` tall,
+    /// wound CCW from the camera, UVs `(0,0)` at screen left-bottom to `(1,1)` at right-top.
     fn card(d: f32, w: f32, h: f32, blend: ModelBlend, two_sided: bool) -> RenderSubmesh {
-        // Screen-right is −Y: corners in screen order (left-bottom, right-bottom, right-top,
-        // left-top) are y = +w, −w, −w, +w.
         RenderSubmesh {
             positions: vec![[d, w, -h], [d, -w, -h], [d, -w, h], [d, w, h]],
             uvs: vec![[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]],
@@ -731,8 +630,7 @@ mod tests {
 
     #[test]
     fn a_wide_card_reports_its_own_half_extents() {
-        // At depth 10, a card ±5 wide / ±4 tall projects to ±0.5 / ±0.4 — both larger than the
-        // authored box, so the measured extents are the card's.
+        // ±5 by ±4 at depth 10 projects to ±0.5 by ±0.4, both past the authored box.
         let sub = card(10.0, 5.0, 4.0, ModelBlend::Opaque, false);
         let ext = glue_art_extent([&sub], &cam(FOV), full);
         assert!((ext.half_w - 0.5).abs() < TOL, "half_w {}", ext.half_w);
@@ -741,7 +639,7 @@ mod tests {
 
     #[test]
     fn a_card_narrower_than_the_authored_box_reports_zero() {
-        // ±2 at depth 10 → ±0.2 < t0 = 0.309: the authored vertical opening is not even covered.
+        // ±2 at depth 10 is ±0.2, under t0 = 0.309: the authored opening is not even covered.
         let sub = card(10.0, 2.0, 2.0, ModelBlend::Opaque, false);
         let ext = glue_art_extent([&sub], &cam(FOV), full);
         assert_eq!(
@@ -770,9 +668,8 @@ mod tests {
 
     #[test]
     fn an_alpha_texture_paints_only_where_it_passes_the_key() {
-        // A ±5 card (±0.5 at depth 10) whose texture is opaque only across u ∈ [0.2, 0.8]: it
-        // paints ±0.3 — the rows read that band; and since ±0.3 is inside the authored ±0.413,
-        // a column of the box goes unpainted and the height reads 0.
+        // Opaque only across u ∈ [0.2, 0.8] of a ±0.5 card: ±0.3 wide, inside the authored
+        // ±0.413, so a column of the box goes unpainted and the height reads 0.
         let sub = card(10.0, 5.0, 4.0, ModelBlend::AlphaTest, false);
         let map = band(0.2, 0.8);
         let ext = glue_art_extent([&sub], &cam(FOV), |_| Some(Coverage::Alpha(map.clone())));
@@ -782,7 +679,6 @@ mod tests {
             ext.half_w
         );
         assert_eq!(ext.half_h, 0.0, "a column inside the box is unpainted");
-        // A band wider than the box (u ∈ [0.05, 0.95] → ±0.45) paints the full height.
         let map = band(0.05, 0.95);
         let ext = glue_art_extent([&sub], &cam(FOV), |_| Some(Coverage::Alpha(map.clone())));
         assert!((ext.half_h - 0.4).abs() < TOL, "half_h {}", ext.half_h);
@@ -795,9 +691,8 @@ mod tests {
 
     #[test]
     fn the_narrowest_row_wins() {
-        // A trapezoid: ±5 wide at the bottom, ±2.5 at the top (depth 10) — the frame's top row
-        // (y' = +t0 = 0.309, i.e. Z = 3.09) sees a half-width interpolated between the two:
-        // at Z = 3.09 of a ±4-tall card, w = 5 − 2.5·(3.09+4)/8 = 2.78 → 0.278.
+        // A trapezoid, ±5 wide at the bottom and ±2.5 at the top (depth 10): the frame's top row
+        // (y' = t0 = 0.309, Z = 3.09) sees w = 5 − 2.5·(3.09+4)/8 = 2.78, so 0.278.
         let mut sub = card(10.0, 5.0, 4.0, ModelBlend::Opaque, false);
         sub.positions[2] = [10.0, -2.5, 4.0];
         sub.positions[3] = [10.0, 2.5, 4.0];
@@ -815,10 +710,7 @@ mod tests {
     fn a_card_behind_the_camera_is_clipped_away_and_one_straddling_it_is_clipped_to_near() {
         let behind = card(-10.0, 5.0, 4.0, ModelBlend::Opaque, true);
         assert_eq!(glue_art_extent([&behind], &cam(FOV), full).half_w, 0.0);
-        // A ground plane running from behind the camera to far ahead, below the eye: its near
-        // clip leaves finite geometry, the projection stays finite, and the covered rows are the
-        // lower half only — so the *full* authored opening is not covered and the extent is 0,
-        // without any NaN or panic on the way.
+        // A ground plane from behind the eye to far ahead: finite, lower rows only, so 0.
         let mut ground = card(0.0, 50.0, 0.0, ModelBlend::Opaque, true);
         ground.positions = vec![
             [-5.0, 50.0, -1.0],
@@ -851,7 +743,6 @@ mod tests {
         assert!((ext.half_w - 0.5).abs() < TOL, "half_w {}", ext.half_w);
     }
 
-    /// Measure one shipped scene off the chain, the way the tool does.
     fn measure(chain: &mut Chain, token: &str) -> (ArtExtent, f32, f32) {
         let name = format!("Interface\\Glues\\Models\\UI_{token}\\UI_{token}.m2");
         let bytes = chain.read_file(&name).expect("read scene");
@@ -862,9 +753,6 @@ mod tests {
         (ext, cam.fov, authored_half_height(cam.fov))
     }
 
-    /// The transcription is the measurement: every shipped scene re-measures to the table's
-    /// numbers (within the grid's quantisation), every one covers (about) its authored 4:3 box
-    /// in width, and every one runs out of width before 16:9 — the fact the whole law rests on.
     #[test]
     fn the_shipped_table_matches_the_measurement() {
         let data = crate::wow_data_or_skip!();
@@ -878,7 +766,6 @@ mod tests {
                     && (ext.half_h - shipped.half_h).abs() < 2e-3,
                 "UI_{token}: measured {ext:?}, table {shipped:?}"
             );
-            // The fov rides the table because the glue framing constant is derived from it.
             assert!(
                 (fov - scene.fov).abs() < 1e-6,
                 "UI_{token}: camera 0 fov {fov}, table {}",
@@ -889,8 +776,6 @@ mod tests {
                 (GLUE_AUTHORED_ASPECT - 0.03..16.0 / 9.0).contains(&runs_out_at),
                 "UI_{token} covers up to aspect {runs_out_at:.3}"
             );
-            // Every stage but the night elves' fills its authored box top to bottom; theirs
-            // shows black night sky between the leaves at its sides (the table's doc).
             if token == "NightElf" {
                 assert!(
                     ext.half_h < t0,
diff --git a/crates/benilla-formats/src/models/bounds.rs b/crates/benilla-formats/src/models/bounds.rs
index a368f138..179de08c 100644
--- a/crates/benilla-formats/src/models/bounds.rs
+++ b/crates/benilla-formats/src/models/bounds.rs
@@ -1,8 +1,5 @@
-//! An M2's authored bounds ([`M2Bounds`]) — the header sphere/box, the vertex-derived radius our
-//! renderer computes, and the selection-ring **footprint** read from the model's Stand-animation
-//! bounding box (the exact model-local input the real client's living-unit selection ring uses).
-//! No render-batch concern here — just the bounds/measurement reads [`load_m2_bounds`]/
-//! [`parse_m2_bounds`] expose to placement + the selection ring.
+//! An M2's authored bounds ([`M2Bounds`]): the header sphere and box, and the Stand-sequence box
+//! reads that size the selection ring, the chat bubble and the camera pivot.
 
 use std::io::Cursor;
 
@@ -14,83 +11,44 @@ use crate::Chain;
 
 use super::model_path;
 
-/// An M2's authored bounds (read straight from the model header) alongside the vertex-derived radius
-/// our renderer currently computes — so the distance-fade size bucket can be checked against the value
-/// the reference's placement builder actually uses (`FUN_00694bc0` → `rec+0x68`). `sphere_radius` and
-/// `bbox_*` are in model-local yards (multiply by the placement scale for the world radius).
+/// An M2's authored bounds and the reads sized from them, in model-local yards before the
+/// placement scale.
 #[derive(Clone, Copy, Debug)]
 pub struct M2Bounds {
-    /// `M2Header.bounding_sphere_radius` — the authored bounding-sphere radius (the reference's source).
+    /// The authored bounding-sphere radius; times the placement scale it is the reference's
+    /// doodad radius `rec+0x68` (`0x6952a0`).
     pub sphere_radius: f32,
-    /// `M2Header.bounding_box_min/max` — the authored AABB; its centre is the sphere centre.
+    /// The authored box; its centre is the sphere's.
     pub bbox_min: [f32; 3],
     pub bbox_max: [f32; 3],
-    /// Max vertex distance from the model **origin** — what `build_model` currently uses as the radius.
+    /// The largest vertex distance from the model origin.
     pub vert_max_from_origin: f32,
-    /// The selection-ring **footprint** (model-local, pre-scale): `sqrt(0.5 · sqrt(dx² + dy²))`, where
-    /// `dx,dy` are the horizontal (X,Y) extents of the unit's **Stand** animation bounding box (the M2
-    /// sequence CAaBox). This is the exact model-local input the real client's living-unit selection ring
-    /// uses — byte-verified + Unicorn-emulated to the reference pixels (wow-re selection-ring RE,
-    /// `0x608e00`/`0x60aee0`): the ring's world radius = this × `OBJECT_FIELD_SCALE_X`. The nested sqrt is
-    /// a range-compressor (which is why the render-sphere never fit). Falls back to the header render-box
-    /// XY extents for a model with no animation sequences.
-    ///
-    /// A **degenerate** box — `max.x == min.x` *and* `max.y == min.y` — takes
-    /// [`DEGENERATE_RING_FOOTPRINT`] instead of the formula, which is the writer's own first branch
-    /// and not a floor of ours (decision 1658).
+    /// The selection ring's footprint: `sqrt(0.5 · sqrt(dx² + dy²))` over the Stand box's X and Y
+    /// extents, the reference's living-unit ring input (`0x608e00`/`0x60aee0`); the ring's world
+    /// radius is this × `OBJECT_FIELD_SCALE_X`. A model with no sequences uses the header box, and
+    /// a box with zero X and Y extents takes [`DEGENERATE_RING_FOOTPRINT`].
     pub ring_footprint: f32,
-    /// Model-space **Z** of attachment id 17 — the reference's follow-camera pivot height (wow-re
-    /// `follow-camera`: `feet + (attach17.z + 0.0972)·scale`). `None` for a model with no slot-17
-    /// attachment; the camera then falls back to a fraction of the box. See [`M2Bounds::pivot_z`].
+    /// Model-space Z of attachment 17, the reference's follow-camera pivot height (`0x50ca90`:
+    /// `feet + (attach17.z + 0.0972)·scale`); without one the camera uses a fraction of the box.
     pub pivot_z: Option<f32>,
-    /// The **Stand** animation box's vertical extent, `max.z − min.z` (model-local, pre-scale) — the
-    /// chat bubble's anchor height above the unit's feet (× model scale, + 0.7 yd).
-    ///
-    /// The same `0x711a20` query the selection ring above is sized from, taking the box's Z instead
-    /// of its XY: wow-re's chat-bubble anchor cross-check (2026-08-17) followed `0x4b0e38 call
-    /// 0x711a20` into the model layer and found it reading the **MD20 header image** — file bytes,
-    /// no bone matrix anywhere in the call tree — and returning `out+0x20 − out+0x14`, which is that
-    /// CAaBox's Z extent. Benilla anchored the bubble on the posed PlayerName attachment instead,
-    /// on a recorded INFERRED claim that `0x608640` and `0x711a20` were "both the head-region
-    /// attachment height"; that equivalence is **REFUTED** — they differ precisely on
-    /// animated-vs-static, `0x608640` reading the live posed palette (it bobs) and this reading a
-    /// file constant. The overhead *name* keeps `0x608640`; only the bubble takes this. See 1406.
-    ///
-    /// Falls back to the header render-box Z extent for a model with no sequences, like the ring.
+    /// The Stand box's Z extent, the chat bubble's anchor above the feet (times the scale, plus
+    /// 0.7 yd): `0x4b0e38` calls `0x711a20`, which reads the MD20 file image with no bone matrix
+    /// and returns `out+0x20 − out+0x14`. The overhead name instead uses `0x608640`, the live posed
+    /// attachment, which bobs. The header box's Z for a model with no sequences.
     pub stand_box_z: f32,
-    /// How far the camera's framing pivot drops when this body **swims** (model-local yards,
-    /// pre-scale): `StandSeq.bounds.max.z − SwimSeq.bounds.max.z`, floored at zero.
-    ///
-    /// The reference keeps **three** framing-pivot presets side by side (`cam+0x11c`/`+0x120`/
-    /// `+0x124`, rebuilt from the model by `0x50ca90`) and picks one per frame at `0x50f880`. All
-    /// three start from the same base — the `attach17.z + 0.0972222 [0x808ab0]` neck height
-    /// [`M2Bounds::pivot_z`] carries — and only the swim one is then pulled down, by exactly this:
-    /// `0x50ccf6 fsubr [esi+0x124]` subtracts `S · (box0.max.z − box42.max.z)`, where the two boxes
-    /// come from `0x711a20(model, 0)` and `0x711a20(model, 0x2a)` — the same `M2Sequence` `CAaBox`
-    /// query [`stand_box`] reads, on animation id **0** (Stand) and id **42** (Swim). Byte-decoded
-    /// and VERIFIED in wow-re `ui/scratch/water-band-discontinuity.md` §7, which measured
-    /// `+0x11c = +0x120 = 1.9002692` and `+0x124 = 1.5120120` off the shipped `HumanMale.m2` at
-    /// scale 1 — a drop of `0.3882572`, the number the fixture test pins.
-    ///
-    /// It is a **delta**, not a height, because that is the shape of the byte: the base is added to
-    /// all three presets at `0x50cc0c`–`0x50cc2e` and only `+0x124` is decremented, so a consumer
-    /// gets the swim preset as `pivot_height − this`, then the shared `[5/6, 15.0]` clamp
-    /// (`0x50ca90`, `0x50d00d`–`0x50d092`).
-    ///
-    /// **`0.0` when the model has no Swim sequence** — which is every non-character model, and the
-    /// reference's own answer too: `0x50cc67`–`0x50cd02` runs only when `0x711960` reports *both*
-    /// id 0 and id 42 present, so a body that cannot swim keeps the standing preset in every state.
-    ///
-    /// **The zoom pair is NOT built.** `0x50f880`'s other leg picks `+0x11c` (zoomed-in) or
-    /// `+0x120` (zoomed-out) on `cam+0x198 < 1.8315` — and on a scale-1 human the reference computes
-    /// those two *equal*, so nothing here yet says what makes them differ. benilla has one standing
-    /// preset and this drop; the threshold and whatever authors the zoomed pair apart are absent,
-    /// not stubbed.
+    /// How far the camera pivot drops while swimming: Stand's box `max.z` less Swim's, floored at
+    /// zero, and `0.0` without a Swim sequence. The reference adds the neck height
+    /// (`attach17.z + 0.0972222`, `0x808ab0`) to three presets, `cam+0x11c`/`+0x120`/`+0x124`
+    /// (`0x50cc0c`–`0x50cc2e`, built by `0x50ca90`), then lowers only the swim one by
+    /// `S · (box0.max.z − box42.max.z)` (`0x50ccf6`), and only when `0x711960` finds ids 0 and 42
+    /// (`0x50cc67`–`0x50cd02`); `0x50f880` picks a preset per frame, then the `[5/6, 15.0]` clamp
+    /// (`0x50d00d`–`0x50d092`). `HumanMale.m2` drops `0.3882572` at scale 1. The reference also
+    /// picks zoomed-in `+0x11c` or zoomed-out `+0x120` on `cam+0x198 < 1.8315`; benilla has one
+    /// standing preset, and what sets those two apart is untraced.
     pub swim_pivot_drop: f32,
 }
 
-/// Read an M2's authored bounds + the vertex-derived radius (see [`M2Bounds`]). Uses the same path
-/// normalisation as [`super::load_m2_mesh`] so `.mdx`/`.mdl` doodad paths resolve identically.
+/// Read an M2's bounds from the chain, by model or doodad (`.mdx`/`.mdl`) path.
 pub fn load_m2_bounds(chain: &mut Chain, raw_path: &str) -> Result<M2Bounds> {
     let path = model_path(raw_path);
     let bytes = chain
@@ -99,29 +57,16 @@ pub fn load_m2_bounds(chain: &mut Chain, raw_path: &str) -> Result<M2Bounds> {
     parse_m2_bounds(&bytes).with_context(|| format!("parsing M2 bounds {path}"))
 }
 
-/// The ring footprint the real client stores for a **degenerate** box — one whose X *and* Y extents
-/// are both exactly zero. Byte-read at `0x60af4f..0x60af67` (wow-re `selection-ring-scale.md`): the
-/// writer `0x60aee0` compares `max.x==min.x` and `max.y==min.y` and, when both hold, stores the
-/// literal `0x3f99999a` = **1.2** into `[unit+0xcf0]` without ever running the `sqrt(0.5·sqrt(dx²+dy²))`
-/// formula. wow-re recorded it as a branch that "never fires for real creatures", which is true of
-/// the four life-size units it measured and false of the whole trigger-creature family: an
-/// `InvisibleStalker` body authors all 135 sequence boxes at zero, so this **is** its ring — and the
-/// Naxxramas weapon mobs, whose visible self is the axe in that body's hand, are exactly where a
-/// player sees it. Ours read 0 and drew a ring the width of a coin (decision 1658).
-///
-/// It is the model-less fallback too: "no box to measure" and "a box that measures zero" are the
-/// same question, and this is the reference's answer to it.
+/// The ring footprint the reference stores for a box with zero X and Y extents: the writer
+/// `0x60aee0` stores the literal 1.2 (`0x3f99999a`) into `[unit+0xcf0]` without running the
+/// formula (`0x60af4f..0x60af67`). An `InvisibleStalker` body's sequence boxes are all zero, so
+/// this is its ring; the ring also takes it for a unit with no model.
 pub const DEGENERATE_RING_FOOTPRINT: f32 = 1.2;
 
-/// Resolve an animation **id** to its `M2Sequence` record index — the animation-lookup indirection
-/// every sequence-box read below goes through. The lookup array is at MD20 `0x24`(count)/`0x28`
-/// (offset), one `u16` per animation id; the sequence array it indexes is at `0x1c`/`0x20`. An id
-/// is NOT a record number (a chicken's record 0 is a flap, its Stand sits at index 2), and a model
-/// that simply does not author an animation is the common case, not an error: `None` for a missing
-/// lookup, an id past its end, the `0xffff` "absent" sentinel, or an index past the sequence array.
-///
-/// This is the client's own `0x711960(id)` presence test folded into the `0x711a20(id)` box query —
-/// the pair `0x50ca90` calls on ids 0 and 42 before it will build the swim preset at all.
+/// Resolve an animation id to its `M2Sequence` index through the lookup (MD20 `0x24`/`0x28`, a
+/// `u16` per id; sequences at `0x1c`/`0x20`). An id is not a record number: a chicken's record 0
+/// is a flap and its Stand is index 2. `None` for an absent id (`0xffff`) or one out of range:
+/// the reference's `0x711960` presence test folded into its `0x711a20` box query.
 fn seq_index(bytes: &[u8], anim_id: usize) -> Option<usize> {
     let anim_count = bytes.u32_at(0x1c)? as usize;
     let lookup_count = bytes.u32_at(0x24)? as usize;
@@ -135,18 +80,15 @@ fn seq_index(bytes: &[u8], anim_id: usize) -> Option<usize> {
     }
 }
 
-/// The byte offset of a resolved sequence record — stride `0x44` from the array at MD20 `0x20`,
-/// with the `CAaBox` at record `+0x24` (min `C3Vector` `+0x24`, max `C3Vector` `+0x30`, so `max.z`
-/// is `+0x38`).
+/// A sequence record's offset: stride `0x44` from MD20 `0x20`, its `CAaBox` min at `+0x24` and
+/// max at `+0x30`.
 fn seq_record(bytes: &[u8], idx: usize) -> Option<usize> {
     let anim_ofs = bytes.u32_at(0x20)? as usize;
     anim_ofs.checked_add(idx * 0x44)
 }
 
-/// The **Stand** sequence's record — animation id 0 through [`seq_index`], falling back to record 0
-/// for a model whose lookup is absent or points nowhere (the pre-existing behaviour the ring and
-/// the chat bubble are pinned to; every model that has sequences at all has *something* to stand on).
-/// `None` only when the model has no sequences.
+/// The Stand record: animation id 0 through [`seq_index`], else record 0; `None` only when the
+/// model has no sequences.
 fn stand_record(bytes: &[u8]) -> Option<usize> {
     if bytes.u32_at(0x1c)? as usize == 0 {
         return None;
@@ -154,45 +96,30 @@ fn stand_record(bytes: &[u8]) -> Option<usize> {
     seq_record(bytes, seq_index(bytes, 0).unwrap_or(0))
 }
 
-/// One sequence box's `max.z` — `rec+0x38`, the `out+0x20` field `0x711a20` returns (wow-re
-/// `water-band-discontinuity.md` §7). The camera's swim preset is the difference of two of these.
+/// One sequence box's `max.z`, `rec+0x38`: the `out+0x20` that `0x711a20` returns.
 fn seq_max_z(bytes: &[u8], anim_id: usize) -> Option<f32> {
     let rec = seq_record(bytes, seq_index(bytes, anim_id)?)?;
     bytes.f32_at(rec + 0x38)
 }
 
-/// Read the horizontal (X,Y) extents of the **Stand** animation's bounding box from a raw M2 — the input
-/// the real client's living-unit selection ring is sized from (wow-re selection-ring RE, `0x60aee0`).
-/// The animation `M2Sequence` array is at MD20 `0x1c`(count)/`0x20`(offset), stride `0x44`, with the
-/// sequence's `CAaBox` at record `+0x24` (min C3 `+0x24`, max C3 `+0x30`). Stand is animation **id 0**,
-/// whose *sequence index* is `animationLookup[0]` (array at `0x24`/`0x28`, `u16` each) — NOT necessarily
-/// record 0 (a chicken's record 0 is a flap, its Stand sits at index 2) — resolved by [`seq_index`].
-/// Returns `(dx, dy, dz)`, or `None` when the model has no sequences (caller falls back to the header
-/// box). VERIFIED: reproduces the reference ring radii to ~1 mm.
-///
-/// The Z extent joins the pair the ring needs because the chat bubble's anchor is the **same box**
-/// read on the other axis (1406) — one parse, one Stand-sequence resolution, two consumers, so the
-/// ring and the bubble can never drift onto different animations.
+/// The Stand box's `(dx, dy, dz)`, the input the reference's living-unit ring is sized from
+/// (`0x60aee0`); `None` without sequences. Z rides along because the chat bubble anchors on the
+/// same box, so the ring and the bubble never read different animations.
 fn stand_box(bytes: &[u8]) -> Option<(f32, f32, f32)> {
     let rec = stand_record(bytes)?;
-    // CAaBox @ rec+0x24: min C3 (+0x24), max C3 (+0x30). Horizontal (X,Y) extents; squared in the ring
-    // formula so an unsorted box is harmless.
+    // The ring squares dx and dy, so an unsorted box is harmless.
     let dx = bytes.f32_at(rec + 0x30)? - bytes.f32_at(rec + 0x24)?;
     let dy = bytes.f32_at(rec + 0x34)? - bytes.f32_at(rec + 0x28)?;
     let dz = bytes.f32_at(rec + 0x38)? - bytes.f32_at(rec + 0x2c)?;
     Some((dx, dy, dz))
 }
 
-/// `AnimationData` id **42** — Swim. The second box `0x50ca90` queries (`0x50ccde call 0x711a20`
-/// with `seq=0x2a`) when it builds the camera's swim framing-pivot preset.
+/// `AnimationData` id 42, Swim: the second box `0x50ca90` queries (`0x50ccde call 0x711a20`).
 const SWIM_ANIM_ID: usize = 42;
 
-/// The camera's swim pivot drop (see [`M2Bounds::swim_pivot_drop`]): `StandSeq.bounds.max.z −
-/// SwimSeq.bounds.max.z`, floored at zero, and `0.0` for any model missing either sequence — the
-/// reference's own both-present guard (`0x711960` on ids 0 and `0x2a` at `0x50cc43`/`0x50cc4f`).
-///
-/// Stand resolves through [`stand_record`], not [`seq_index`] alone, so the standing side of the
-/// subtraction is byte-for-byte the box the ring and the chat bubble already read.
+/// The camera's swim pivot drop ([`M2Bounds::swim_pivot_drop`]). The reference requires ids 0 and
+/// `0x2a` both present (`0x711960` at `0x50cc43`/`0x50cc4f`); here Stand resolves through
+/// [`stand_record`], the box the ring and the chat bubble read.
 fn swim_pivot_drop(bytes: &[u8]) -> f32 {
     let Some(stand_z) = stand_record(bytes).and_then(|rec| bytes.f32_at(rec + 0x38)) else {
         return 0.0;
@@ -203,8 +130,7 @@ fn swim_pivot_drop(bytes: &[u8]) -> f32 {
     (stand_z - swim_z).max(0.0)
 }
 
-/// Read an **in-memory** M2's authored bounds + vertex-derived radius (see [`M2Bounds`]). The bytes-in
-/// entry point for the Bevy `AssetLoader`; [`load_m2_bounds`] is the chain-reading wrapper.
+/// Read an in-memory M2's bounds, for the Bevy `AssetLoader`.
 pub fn parse_m2_bounds(bytes: &[u8]) -> Result<M2Bounds> {
     let format =
         parse_m2(&mut Cursor::new(bytes)).map_err(|e| anyhow::anyhow!("parsing M2: {e}"))?;
@@ -218,9 +144,7 @@ pub fn parse_m2_bounds(bytes: &[u8]) -> Result<M2Bounds> {
             (p.x * p.x + p.y * p.y + p.z * p.z).sqrt()
         })
         .fold(0.0_f32, f32::max);
-    // Selection-ring footprint: `sqrt(0.5 · sqrt(dx² + dy²))` of the Stand animation box's horizontal
-    // extents (the real client's living-unit ring input), falling back to the header render-box XY for a
-    // model with no animation sequences (the client's static-model path).
+    // The Stand box, or the header box for a model with no sequences (the reference's static path).
     let (rx, ry, rz) = stand_box(bytes).unwrap_or((
         h.bounding_box_max[0] - h.bounding_box_min[0],
         h.bounding_box_max[1] - h.bounding_box_min[1],
diff --git a/crates/benilla-formats/src/models/collision.rs b/crates/benilla-formats/src/models/collision.rs
index dd8e3133..60bd6881 100644
--- a/crates/benilla-formats/src/models/collision.rs
+++ b/crates/benilla-formats/src/models/collision.rs
@@ -1,5 +1,4 @@
-//! Collision-hull parsing: the coarse M2 bounding hull and the WMO group collision/camera-collision
-//! triangle gathers (the avian colliders the streamer bakes). Split out of the model parser.
+//! Collision geometry: the M2 collision hull and the WMO group gathers for walking and the camera.
 
 use std::collections::HashMap;
 use std::io::Cursor;
@@ -12,10 +11,8 @@ use crate::Chain;
 
 use super::model_path;
 
-/// Collision geometry in **raw model-local coords** — the same space as [`super::RenderSubmesh::positions`]
-/// (Z-up ≈ WoW axes). The benilla bake applies the *identical* placement transform the renderer
-/// uses, so the collider coincides with the visible model. `indices` is a triangle list into
-/// `positions`. Both vecs empty ⇒ the source carries no collision geometry (caller skips it).
+/// A collision triangle list in raw model-local coordinates, the space of
+/// [`super::RenderSubmesh::positions`]; empty when the source has no collision geometry.
 #[derive(Debug, Clone, Default)]
 pub struct CollisionMesh {
     pub positions: Vec<[f32; 3]>,
@@ -26,20 +23,14 @@ impl CollisionMesh {
     pub fn is_empty(&self) -> bool {
         self.indices.is_empty()
     }
-    /// Triangle count (`indices.len() / 3`).
     pub fn triangle_count(&self) -> usize {
         self.indices.len() / 3
     }
 }
 
-/// Decode an M2 doodad's **collision hull** — the coarse solid shape (trunk/walls) the client collides
-/// against, separate from and much smaller than the render mesh (verified: hull span ≪ render bbox, so
-/// you're blocked by the trunk but walk through the canopy). Source = the M2 header
-/// `bounding_{vertices,triangles}` arrays (raw bytes in `raw_data`): vertices are `C3Vector` (12 B),
-/// triangles a `u16` index list — one collision normal per face, which we don't need (parry derives
-/// face normals). The Legion `PCOL` `collision_mesh_data` is always absent in 1.12. A doodad with no
-/// hull (`nBoundingTriangles == 0` — many small props) returns an empty mesh: **collide-iff-hull** is
-/// the sole gate (verified). Validated 2026-06-02.
+/// An M2 doodad's collision hull, the header's `bounding_vertices` (`C3Vector`) and
+/// `bounding_triangles` (`u16` indices): a coarse solid far smaller than the render mesh, so the
+/// trunk blocks and the canopy does not. A doodad with no hull does not collide.
 pub fn load_m2_collision_hull(chain: &mut Chain, raw_path: &str) -> Result<CollisionMesh> {
     let path = model_path(raw_path);
     let bytes = chain
@@ -48,9 +39,7 @@ pub fn load_m2_collision_hull(chain: &mut Chain, raw_path: &str) -> Result<Colli
     parse_m2_collision_hull(&bytes).with_context(|| format!("parsing M2 {path}"))
 }
 
-/// Parse an M2 doodad's collision hull straight from its file bytes (the byte-fed twin of
-/// [`load_m2_collision_hull`], for the asset-loader path that already holds the bytes). Empty mesh ⇒
-/// no hull (`nBoundingTriangles == 0`). See [`load_m2_collision_hull`] for the format details.
+/// [`load_m2_collision_hull`] from file bytes already in hand; empty when there is no hull.
 pub fn parse_m2_collision_hull(bytes: &[u8]) -> Result<CollisionMesh> {
     let format =
         parse_m2(&mut Cursor::new(bytes)).map_err(|e| anyhow::anyhow!("parsing M2 hull: {e}"))?;
@@ -76,41 +65,26 @@ pub fn parse_m2_collision_hull(bytes: &[u8]) -> Result<CollisionMesh> {
         .iter()
         .map(|c| u32::from(u16::from_le_bytes([c[0], c[1]])))
         .collect();
-    // Guard (verified true on every real 1.12 hull): whole triangles, all indices in range. Bail to
-    // "no hull" rather than emit broken geometry if a future/odd file violates it.
+    // Every 1.12 hull has whole triangles and in-range indices; anything else counts as no hull.
     if indices.is_empty() || !indices.len().is_multiple_of(3) || indices.iter().any(|&i| i >= n) {
         return Ok(CollisionMesh::default());
     }
     Ok(CollisionMesh { positions, indices })
 }
 
-/// MOPY per-face flags (1.12) and the two collision gather masks — both **VERIFIED** from `WoW.exe` 5875
-/// (objdump; see wow-5875-re `system/collision/collision.md` → "The WMO per-face MOPY collision mask").
-/// The skip predicate is a pure function of a 32-bit collision *class* word built per query; the two
-/// classes benilla reproduces, one collider mesh each:
-///   - **WALKING / movement** (the player body): skip a face **iff `flags & 0x04`** (DETAIL/decal). Reject
-///     mask `0x84` from class word `0x10_0111` (collision `0x6315f0`); WMO BSP leaf `0x6bc700`.
-///   - **CAMERA / LOS** (third-person occlusion): skip a face **iff `flags & 0x02`** (NOCAMCOLLIDE). It does
-///     NOT exclude DETAIL, so the camera collides with visible decals/overhangs the player walks *under*
-///     (e.g. forge pipes). Reject mask `0x82` from class word `0x10_0171` (ui `0x50e570`).
-///
-/// So the difference is exactly: walking drops DETAIL; the camera instead drops NOCAMCOLLIDE. (The older
-/// `FUN_006bca50` citation was a superseded prototype lead, corrected
-/// when wow-re took ownership of the WMO leaf.)
+/// MOPY `DETAIL`, the face bit the walking gather skips. The reference builds a reject mask from a
+/// per-query class word: walking, `0x10_0111` (`0x6315f0`), gives `0x84`, tested at the box-query
+/// leaf `0x6bca50`; camera and line of sight, `0x10_0171` (`0x50e570`), give `0x82`, tested at
+/// the segment-query leaf `0x6bc700`. The same code builds both masks, and `0x80` is the query's
+/// transient visited bit, so walking skips `DETAIL` and the camera `NOCAMCOLLIDE`.
 const MOPY_DETAIL: u8 = 0x04;
-/// The bit the **camera/LOS** gather excludes — NOCAMCOLLIDE, the faces the third-person camera passes
-/// through. See [`MOPY_DETAIL`] for the full walking-vs-camera mask derivation.
+/// MOPY `NOCAMCOLLIDE`, the face bit the camera and line-of-sight gather skips.
 const MOPY_NOCAMCOLLIDE: u8 = 0x02;
 
-/// Decode a WMO's **collidable triangles** — the faces the client collides against — flattened across
-/// every group file into one mesh in **raw WMO-local coords** (same space as [`load_wmo`]'s render
-/// submeshes; the benilla bake reuses the identical MODF placement transform). Selection = the
-/// binary-VERIFIED client filter: a face collides **iff `(flags & 0x04 DETAIL) == 0`** (exclude
-/// render-only decals only) — the walking-gather mask 0x84 read from `WoW.exe` 5875 (`FUN_006bca50`,
-/// 3 agents/objdump). This is *more* inclusive than the old
-/// server-vmap-extractor rule `COLLISION || (RENDER && !DETAIL)`, which wrongly dropped the
-/// flags-0x00 / 0x40-only faces the real client collides. *(Whole-group skips — mogpFlags
-/// unreachable/antiportal — are a later refinement; including all rendered groups is safe for ground-snap.)*
+/// A WMO's walking-collidable triangles across every group file, in raw WMO-local coordinates: a
+/// face collides unless it is `DETAIL` ([`MOPY_DETAIL`]). Wider than the vmangos vmap rule
+/// `COLLISION || (RENDER && !DETAIL)`: faces with flags `0x00` or only `0x40` collide too. Every
+/// group is gathered, with no whole-group skip by MOGP flags.
 pub fn load_wmo_collision_tris(chain: &mut Chain, raw_path: &str) -> Result<CollisionMesh> {
     let root_path = raw_path.to_ascii_lowercase();
     let bytes = chain
@@ -133,11 +107,7 @@ pub fn load_wmo_collision_tris(chain: &mut Chain, raw_path: &str) -> Result<Coll
     Ok(CollisionMesh { positions, indices })
 }
 
-/// Accumulate one WMO **group** file's *walking*-collidable triangles (raw WMO-local coords) into
-/// `positions`/`indices` — the player-body gather: a face collides **unless** it's a DETAIL/decal face
-/// (`flags & 0x04`). The byte-fed unit shared by [`load_wmo_collision_tris`] (chain) and the asset
-/// loader (which already holds each group's bytes). See [`accumulate_wmo_group_camera_collision`] for
-/// the camera/LOS gather, which keeps DETAIL but drops NOCAMCOLLIDE instead.
+/// Append one WMO group file's walking-collidable triangles: every face but `DETAIL`.
 pub fn accumulate_wmo_group_collision(
     group_bytes: &[u8],
     positions: &mut Vec<[f32; 3]>,
@@ -146,10 +116,8 @@ pub fn accumulate_wmo_group_collision(
     accumulate_wmo_group_faces(group_bytes, MOPY_DETAIL, 0, positions, indices);
 }
 
-/// Accumulate one WMO **group** file's *camera/LOS*-collidable triangles (raw WMO-local coords): the
-/// third-person-camera gather — a face collides **unless** it's NOCAMCOLLIDE (`flags & 0x02`). Unlike
-/// the walking gather it keeps DETAIL faces (visible decals/overhangs like forge pipes), so the camera
-/// can't slip behind them. See [`accumulate_wmo_group_collision`] and [`MOPY_DETAIL`].
+/// Append one WMO group file's camera and line-of-sight triangles: every face but `NOCAMCOLLIDE`,
+/// so a `DETAIL` overhang the player walks under (forge pipes) still stops the camera.
 pub fn accumulate_wmo_group_camera_collision(
     group_bytes: &[u8],
     positions: &mut Vec<[f32; 3]>,
@@ -158,11 +126,8 @@ pub fn accumulate_wmo_group_camera_collision(
     accumulate_wmo_group_faces(group_bytes, MOPY_NOCAMCOLLIDE, 0, positions, indices);
 }
 
-/// Accumulate one WMO **group** file's *camera-only* triangles — the faces the camera collides with
-/// but the walking gather drops: DETAIL (`flags & 0x04`) set, NOCAMCOLLIDE (`flags & 0x02`) clear.
-/// Exactly the camera gather minus the walking gather, kept as its own set so the down-ray's
-/// camera-void fallback (decision 0692) can race it *after* the faithful walking leg has missed,
-/// without double-counting the faces the walking leg already saw.
+/// Append one WMO group file's camera-only triangles (`DETAIL` set, `NOCAMCOLLIDE` clear): the
+/// camera set minus the walking set, for the down-ray's fallback once the walking leg misses.
 pub fn accumulate_wmo_group_camera_only_collision(
     group_bytes: &[u8],
     positions: &mut Vec<[f32; 3]>,
@@ -177,11 +142,8 @@ pub fn accumulate_wmo_group_camera_only_collision(
     );
 }
 
-/// Shared WMO group-face gather: accumulate every triangle whose MOPY flags don't intersect `skip_mask`
-/// (and carry all of `require_mask`, when non-zero), remapping verts to a compact subset *per group*
-/// (equal local indices in different groups are distinct verts). A group that doesn't parse is skipped.
-/// The two collision audiences differ only in `skip_mask` — `0x04` DETAIL for walking, `0x02`
-/// NOCAMCOLLIDE for the camera (see [`MOPY_DETAIL`]); the camera-only set requires DETAIL on top.
+/// Append every triangle whose MOPY flags miss `skip_mask` and carry all of `require_mask`, its
+/// vertices remapped per group (the same index in two groups is two vertices).
 fn accumulate_wmo_group_faces(
     group_bytes: &[u8],
     skip_mask: u8,
diff --git a/crates/benilla-formats/src/models/key_anim.rs b/crates/benilla-formats/src/models/key_anim.rs
index 7537d8e3..b1531047 100644
--- a/crates/benilla-formats/src/models/key_anim.rs
+++ b/crates/benilla-formats/src/models/key_anim.rs
@@ -1,18 +1,7 @@
-//! The generic keyed-loop bake shared by the material-alpha (`mat_anim`) and texture-transform
-//! (`tex_anim`) channels: ONE kernel-faithful sampler (k0 = last key ≤ t, step holds, linear
-//! lerps, clamp past the last key — no wrap-lerp) and ONE clock resolution (gseq wrap vs
-//! per-sequence band rebase), so the byte-verified sampling semantics (wow-re `eval.md`, and the
-//! step-boundary fix) live in exactly one place.
-//!
-//! **A track bakes per SEQUENCE, not once.** A sequence-timeline track keys on one absolute
-//! timeline that every sequence carves a band out of, so "the loop this track plays" is a question
-//! about *which sequence is playing* — the reference re-reads it every frame from the playing
-//! sequence's own key window (wow-re `eval.md` FN1 `0x713d50`: window = `ranges[seqSlot]`, and a
-//! collapsed window `lo >= hi` resolves to the single key `keys[lo]`). Baking only the first
-//! sequence's band was correct for a placed doodad — which arms `animations[0]` once and loops it
-//! forever — and wrong for anything that changes sequence, i.e. every creature: a voidwalker's two
-//! upper armour pieces are weight `0` in Stand/Walk/Run and `1` only in Death, and a seq-0-only
-//! bake freezes whichever value Stand happened to hold.
+//! The keyed-loop bake shared by the material-alpha and texture-transform channels: one sampler,
+//! after the reference's key search `0x713d50`, and one clock resolution. A sequence track bakes
+//! per sequence, since its keys lie on one timeline that every sequence slices a band from and the
+//! reference reads the playing sequence's own key window (`ranges[seqSlot]`) every frame.
 
 use benilla_m2::M2Track;
 
@@ -51,10 +40,8 @@ impl Lerp for [f32; 4] {
     }
 }
 
-/// The sequence a sequence-timeline track bakes against: the model's **file** sequence slot (which
-/// is what indexes the track's [`M2Track::ranges`] — NOT an index into a filtered animation list),
-/// that sequence's absolute `(start_ms, end_ms)` band, and whether the band LOOPS (sequence flags
-/// bit 0 CLEAR) — which is the baked loop's clock law, see [`KeyAnim::wrap`].
+/// The sequence a track bakes against: the file slot that indexes [`M2Track::ranges`], its
+/// absolute `(start_ms, end_ms)` band, and whether it loops (sequence flags bit 0 clear).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) struct SeqSlot {
     pub index: usize,
@@ -62,52 +49,31 @@ pub(crate) struct SeqSlot {
     pub looping: bool,
 }
 
-/// One baked keyed loop, seconds: sample at `t mod period` / `min(t, period)` per [`Self::wrap`]
-/// (linear or step per [`Self::step`]), holding the first/last key outside the keyed span.
-/// `period == 0` ⇒ a constant (single key).
+/// One baked keyed loop in seconds, holding its end keys outside the keyed span; `period == 0` is
+/// a constant.
 #[derive(Clone, Debug, PartialEq)]
 pub struct KeyAnim<V> {
-    /// Loop period (secs): the global sequence's duration, or the sequence band's length.
-    /// `0.0` for a constant.
+    /// Seconds: the global sequence's duration or the band's length, `0.0` for a constant.
     pub period: f32,
     /// Step interpolation (`interp == 0`): hold each key until the next; else linear.
     pub step: bool,
-    /// **The clock law**, decided at bake time from what this loop is baked against — never by the
-    /// consumer, which is how it used to be got wrong. `true` = WRAP (`t mod period`): a global
-    /// sequence (its own free-running clock) or a sequence band whose sequence loops, where the
-    /// modulo is the kernel's own re-fire of a windowed track every pass. `false` = CLAMP
-    /// (`min(t, period)`): a band whose sequence is one-shot, where the animation clock parks at
-    /// (or just past) the band end and the track must hold its TAIL value there.
-    ///
-    /// The distinction is only ever visible at the very end of a one-shot clip — and that is
-    /// exactly where it is load-bearing, because Bevy's `ActiveAnimation::update` returns early on
-    /// completion *without* its own modulo, so a finished `RepeatAnimation::Never` clip parks at
-    /// `seek_time >= clip_duration == period`. Wrapping that aliases the end of the animation back
-    /// onto its **opening** value: an elemental's Death sequence fades every batch to alpha 0 and
-    /// then — one frame later, for ever — snapped back to a fully opaque body frozen in mid-air.
+    /// Fixed at bake time: `true` wraps (`t mod period`), for a global sequence or a looping
+    /// sequence's band, whose window the kernel re-fires every pass; `false` clamps
+    /// (`min(t, period)`), for a one-shot band that must hold its tail. A finished Bevy
+    /// `RepeatAnimation::Never` clip parks at or past `period` without its modulo, where a wrap
+    /// would snap a Death fade-out back to its opening value.
     pub wrap: bool,
-    /// **Which clock feeds the loop** — the other half of the clock law, also decided at bake
-    /// time. `true` = a global-sequence loop: the reference's cursor is
-    /// `(sceneClock − instanceAttachTime) % duration` (wow-re `gseq-anchor.md`, byte-verified:
-    /// one free-running per-scene ms clock, snapshotted ONCE per model instance at attach —
-    /// `CM2Model+0x68`). Per-INSTANCE anchoring, stamped at attach; sequence tracks instead
-    /// re-arm their cursor at every play. `false` = a sequence-band loop: clocked by the host's
-    /// playing-clip time. Consumers route via [`Self::clock`], passing their instance's anchored
-    /// gseq cursor — the spell-fx lane passes the raw scene clock (its pooled-instance
-    /// emulation). Decisions 0855/0856: sampling a gseq loop on a per-play clock pinned every
-    /// Arcane Intellect cast's twinkles to phase 0 (clustered, low, identical cast to cast).
+    /// A global-sequence loop, whose reference cursor is `(sceneClock − attachTime) % duration`
+    /// (`0x71437b`), the attach time stamped once per model instance (`0x70ea00`,
+    /// `CM2Model+0x68`); a band loop instead runs on the host's clip time, re-armed every play.
     pub gseq: bool,
     /// `(secs from loop start, value)`, time-ascending.
     pub keys: Vec<(f32, V)>,
 }
 
 impl<V> KeyAnim<V> {
-    /// The sampling time for this loop, given the caller's two clocks: `band_t` — the host's
-    /// playing-clip / spawn-age seconds (the per-play arm cursor) — and `gseq_now`, the
-    /// instance's global-sequence cursor (`sceneClock − attachTime`; the spell-fx pool lane
-    /// passes the raw scene clock — see [`Self::gseq`]). A gseq loop reads `gseq_now`
-    /// (pre-wrapped in f64, so a long-uptime cursor keeps millisecond precision through the f32
-    /// narrowing); everything else keeps its band clock.
+    /// The sampling time: a gseq loop reads `gseq_now`, the instance's cursor, wrapped in f64 to
+    /// keep millisecond precision; any other reads `band_t`, the clip or spawn-age seconds.
     pub fn clock(&self, band_t: f32, gseq_now: f64) -> f32 {
         if self.gseq && self.period > 0.0 {
             (gseq_now % f64::from(self.period)) as f32
@@ -118,9 +84,8 @@ impl<V> KeyAnim<V> {
 }
 
 impl<V: Lerp> KeyAnim<V> {
-    /// Sample at `elapsed` seconds on this loop's own clock ([`Self::wrap`]); `empty` is the
-    /// channel's identity for the keyless case (the bake never emits that — each channel's
-    /// `sample` supplies it).
+    /// Sample at `elapsed` seconds; `empty` is the channel's identity for a keyless loop, which
+    /// the bake never emits.
     pub(crate) fn sample_or(&self, elapsed: f32, empty: V) -> V {
         let wrap = self.wrap;
         let Some(&(t0, v0)) = self.keys.first() else {
@@ -137,7 +102,7 @@ impl<V: Lerp> KeyAnim<V> {
         if t <= t0 {
             return v0;
         }
-        // k0 = the last key with time ≤ t (the kernel's search), mirroring `BoneScaleAnim::sample`.
+        // k0: the last key at or before t, the kernel's search.
         let mut k0 = 0;
         for (i, &(tk, _)) in self.keys.iter().enumerate() {
             if tk <= t {
@@ -159,20 +124,11 @@ impl<V: Lerp> KeyAnim<V> {
     }
 }
 
-/// The reference's own track read at absolute time `t_ms`, for the key window `[lo, hi]` — the
-/// transcription of wow-re `eval.md` FN1 (`0x713d50`) + the scalar sampler's two-way interp
-/// dispatch (`0x71af20`, `cmp word[track],0`):
-///
-/// - a **collapsed window** (`lo >= hi`) resolves to `keys[lo]` outright — the degenerate
-///   `{lo, lo, 0.0}` result, and the reason a band that keys nothing still has an authored value;
-/// - otherwise `k0` = the last key in the window at or before `t_ms` (clamped up to `lo`), `k1 =
-///   k0 + 1`, and the value is `keys[k0]` for a step track or past the last key, else the lerp.
-///
-/// **One named deviation:** the reference computes the fraction unclamped, so a `t_ms` outside
-/// `[ts[k0], ts[k1]]` extrapolates. That can only arise from a window whose brackets don't contain
-/// the band, and an extrapolated *fix16 factor* lands outside `[0, 1]` — where a negative value
-/// would cull the batch (`A <= 0`) on a data quirk rather than on authoring. We clamp the fraction
-/// to `[0, 1]`, i.e. hold at the bracket instead of running past it.
+/// The reference's track read at `t_ms` over the key window `[lo, hi]` (`0x713d50`, interp
+/// dispatch `0x71af20`): `keys[lo]` for a collapsed window (`lo >= hi`), else the last window key
+/// at or before `t_ms`, held for a step track or past the last key, else lerped toward the next.
+/// Deviation: the fraction is clamped to `[0, 1]`; the reference extrapolates, which for a window
+/// whose brackets miss the band can push a fix16 factor negative and cull the batch on a quirk.
 pub(super) fn sample_window<V: Lerp>(
     keys: &[(u32, V)],
     step: bool,
@@ -205,45 +161,18 @@ pub(super) fn sample_window<V: Lerp>(
     Some(V::lerp(va, vb, f))
 }
 
-/// Bake one typed track to a [`KeyAnim`] for one sequence, or `None` when it contributes nothing
-/// the static path doesn't already handle. `proj` maps the on-disk key value into the baked domain
-/// (identity for scalars; vec3 → the UV xy). The two predicates name the channel's semantics:
-///
-/// - `drop_constant(c)`: a **whole-track** constant `c` vanishes — because `c` is the channel
-///   identity, or because the caller's *static* path already folded it away (the alpha combine's
-///   constant-0 cull). Judged on the whole track, which is what that static path looked at.
-/// - `is_identity(v)`: `v` contributes nothing at runtime — applied to a **band** that bakes down
-///   to a constant, where the static path has NOT looked. A held non-identity value still bakes,
-///   including a held alpha 0, which must keep hiding the batch every frame of that sequence.
-///
-/// `gseq_durations` is the model's global-sequence table (ms); `seq` the sequence to bake for
-/// (see [`SeqSlot`]). A `gseq`-tagged track ignores `seq` entirely — it runs on the global
-/// sequence's own free clock, the same loop in every animation.
-/// One baked loop **per file sequence slot** — the shape a channel needs when its track is keyed
-/// differently in different sequences, which the reference reads as a matter of course (it samples
-/// the *playing* sequence's own key window every frame, `ranges[seqSlot]`; wow-re `eval.md` FN1
-/// `0x713d50`) and benilla's UV/tint lanes did not.
-///
-/// Its whole reason to exist is [`Self::uniform`]. The UV and tint loops are consumed through a
-/// registry keyed by MATERIAL, which is shared by every instance of a batch and so has no sequence
-/// to key on — a design that is exactly right while every slot bakes the same loop, and silently
-/// wrong when they don't. `uniform()` is the question "may this batch keep the shared lane?", asked
-/// once at bake time instead of assumed: `Some` ⇒ yes, and the consumer carries one loop as before;
-/// `None` ⇒ the batch's animation depends on which sequence its instance is playing, so it needs a
-/// per-instance consumer (decision 1408).
-///
-/// The corpus population is small and real (`benilla-extract uvslotscan`): 22 of the 32 multi-slot
-/// UV batch-channels ship a **dead slot 0** beside a live later slot — the BRM lava bubbles keying
-/// their whole flipbook inside the 50 %-weighted variation 1, bug B98.
+/// One baked loop per file sequence slot, for a track keyed differently per sequence. The UV and
+/// tint lanes share one loop per material, which has no sequence to key on; [`Self::uniform`]
+/// tells whether a batch can stay there. A dead slot 0 beside a live later slot is common (22 of
+/// the 32 multi-slot UV batch-channels, `benilla-extract uvslotscan`).
 #[derive(Clone, Debug, PartialEq)]
 pub struct SeqLoops<V> {
-    /// One entry per **file** sequence slot, `None` where that slot's key window moves nothing.
+    /// One entry per file sequence slot, `None` where that slot's key window moves nothing.
     per_seq: Vec<Option<KeyAnim<V>>>,
 }
 
 impl<V: PartialEq> SeqLoops<V> {
-    /// Build from one entry per file sequence slot; `None` when no slot animates at all (the
-    /// overwhelming majority — the caller then carries no set).
+    /// `None` when no slot animates, the common case.
     pub fn new(per_seq: Vec<Option<KeyAnim<V>>>) -> Option<Self> {
         per_seq
             .iter()
@@ -251,9 +180,8 @@ impl<V: PartialEq> SeqLoops<V> {
             .then_some(Self { per_seq })
     }
 
-    /// The one loop every slot bakes to, or `None` when the slots disagree — including the
-    /// asymmetric case a dead slot 0 makes (`None` in one slot, a loop in another), which is the
-    /// whole population this type was added for.
+    /// The loop every slot bakes to, or `None` when the slots disagree, a dead slot beside a live
+    /// one included: then the batch needs a per-instance consumer.
     pub fn uniform(&self) -> Option<&KeyAnim<V>> {
         let first = self.per_seq.first()?;
         self.per_seq
@@ -263,24 +191,23 @@ impl<V: PartialEq> SeqLoops<V> {
             .flatten()
     }
 
-    /// This batch's loop in sequence slot `seq` — slot 0 when unknown or out of range, the same
-    /// degrade [`super::mat_anim::AlphaAnim::seq`] makes and for the same reason (a consumer with
-    /// no live sequence is one that arms slot 0 and never leaves it).
+    /// The loop in slot `seq`, slot 0 when unknown or out of range.
     pub fn seq(&self, seq: Option<usize>) -> Option<&KeyAnim<V>> {
         seq.and_then(|i| self.per_seq.get(i))
             .or_else(|| self.per_seq.first())?
             .as_ref()
     }
 
-    /// Every slot's loop, file order — the census instrument's read
-    /// (`benilla-extract uvslotscan`), which asks this type rather than a hand-rolled twin of the
-    /// sampler (the `idleslotscan` rule: an instrument that re-implements the gate can drift from
-    /// it).
+    /// Every slot's loop in file order, for `benilla-extract uvslotscan`.
     pub fn slots(&self) -> &[Option<KeyAnim<V>>] {
         &self.per_seq
     }
 }
 
+/// Bake one track to a [`KeyAnim`] for one sequence, or `None` when it adds nothing the static
+/// path does not. `drop_constant` drops a whole-track constant (the identity, or one the static
+/// path folded); `is_identity` drops a band that holds the identity, so a held alpha 0 still bakes
+/// and keeps hiding the batch. A `gseq` track ignores `seq`: one loop in every animation.
 pub(crate) fn bake_track<T: Copy, V: Lerp + PartialEq>(
     track: &M2Track<T>,
     gseq_durations: &[u32],
@@ -294,8 +221,7 @@ pub(crate) fn bake_track<T: Copy, V: Lerp + PartialEq>(
     }
     let keys: Vec<(u32, V)> = track.keys.iter().map(|&(t, v)| (t, proj(v))).collect();
     let step = track.interp == 0;
-    // A constant has no clock at all (`period == 0` short-circuits the sampler), so `wrap` and
-    // `gseq` are arbitrary — `true`/`false` keep it the identity value it has always been.
+    // A constant has no clock (`period == 0`), so `wrap` and `gseq` are arbitrary.
     let constant = |v: V| KeyAnim {
         period: 0.0,
         step,
@@ -303,8 +229,7 @@ pub(crate) fn bake_track<T: Copy, V: Lerp + PartialEq>(
         gseq: false,
         keys: vec![(0.0, v)],
     };
-    // An all-equal track is a constant in every band: dropped when the static path owns it, else a
-    // period-0 key. Judged before the band split, because that is the shape the static path tested.
+    // An all-equal track is a constant in every band, judged whole as the static path judged it.
     let (_, first) = keys[0];
     if keys.iter().all(|&(_, v)| v == first) {
         if drop_constant(first) {
@@ -313,8 +238,7 @@ pub(crate) fn bake_track<T: Copy, V: Lerp + PartialEq>(
         return Some(constant(first));
     }
     if track.gseq != 0xffff {
-        // Global-sequence clock: keys are already loop-relative ms; wrap on the table duration
-        // (a 0/absent duration degrades to the last key's time — a defensive clamp, not observed).
+        // Keys are loop-relative ms, wrapped on the table duration (else the last key's time).
         let period_ms = gseq_durations
             .get(track.gseq as usize)
             .copied()
@@ -323,16 +247,14 @@ pub(crate) fn bake_track<T: Copy, V: Lerp + PartialEq>(
         return Some(KeyAnim {
             period: period_ms as f32 / 1000.0,
             step,
-            // A global sequence runs its own free clock, the same loop in every animation — it
-            // always wraps, whatever the playing sequence's own loop flag says.
+            // A global sequence always wraps, whatever the playing sequence's loop flag says.
             wrap: true,
             gseq: true,
             keys: keys.iter().map(|&(t, v)| (t as f32 / 1000.0, v)).collect(),
         });
     }
-    // Sequence-timeline track: rebuild the function the reference samples across THIS sequence's
-    // band. Its key window is the track's own per-sequence `(lo, hi)` pair; an absent ranges array
-    // is the reference's `[track+4] == 0` fallback — search the whole key list.
+    // A sequence track reads this slot's `(lo, hi)` window; with no ranges array, the whole key
+    // list (the reference's `[track+4] == 0` fallback).
     let SeqSlot {
         index,
         band,
@@ -346,12 +268,11 @@ pub(crate) fn bake_track<T: Copy, V: Lerp + PartialEq>(
     let at = |t: u32| sample_window(&keys, step, lo, hi, t);
     let head = at(start)?;
     if end <= start {
-        // A zero-length band samples one instant — nothing to loop.
+        // A zero-length band samples one instant.
         return (!is_identity(head)).then(|| constant(head));
     }
-    // The band's own keys, plus both endpoints: the reference's function on `[start, end]` is
-    // piecewise between consecutive keys, so sampling it AT the keys (and at the band edges, where
-    // it is mid-segment toward an out-of-band bracket) reproduces it exactly.
+    // The band's keys plus both edges: the reference's function is piecewise between keys, so
+    // sampling there reproduces it exactly.
     let mut baked: Vec<(f32, V)> = vec![(0.0, head)];
     for (k, &(t, v)) in keys.iter().enumerate() {
         if k >= lo && k <= hi && t > start && t < end {
@@ -361,15 +282,14 @@ pub(crate) fn bake_track<T: Copy, V: Lerp + PartialEq>(
     if let Some(tail) = at(end) {
         baked.push(((end - start) as f32 / 1000.0, tail));
     }
-    // A band the track never actually moves through is a constant hold — the ordinary case for a
-    // batch authored to appear in one animation and hide in every other.
+    // A band the track never moves through is a constant hold.
     if baked.iter().all(|&(_, v)| v == head) {
         return (!is_identity(head)).then(|| constant(head));
     }
     Some(KeyAnim {
         period: ((end - start) as f32 / 1000.0).max(0.001),
         step,
-        // The band's own loop flag IS this loop's clock: a one-shot sequence holds its tail.
+        // A one-shot sequence holds its tail.
         wrap: looping,
         gseq: false,
         keys: baked,
@@ -390,10 +310,6 @@ mod tests {
         }
     }
 
-    /// The whole point of the type: **an asymmetric pair is not uniform.** A dead slot 0 beside a
-    /// live slot 1 is the shape 22 of the corpus's 32 multi-slot UV batch-channels ship, and the
-    /// shared-material lane must be refused for it — a `uniform()` that only compared the *present*
-    /// loops would wave the BRM lava bubbles straight back through (bug B98).
     #[test]
     fn a_dead_slot_zero_beside_a_live_slot_is_not_uniform() {
         let set = SeqLoops::new(vec![None, Some(loop_of(3.3, &[(0.0, 0.0), (1.0, 0.6)]))])
@@ -403,8 +319,6 @@ mod tests {
         assert!(set.seq(Some(1)).is_some(), "slot 1 is the animation");
     }
 
-    /// The population the shared lane was built for, and keeps: every slot the same loop. `uniform`
-    /// hands back that loop, so the caller carries one and nothing changes.
     #[test]
     fn matching_slots_collapse_to_the_one_shared_loop() {
         let l = loop_of(1.0, &[(0.0, 0.0), (1.0, 1.0)]);
@@ -412,9 +326,6 @@ mod tests {
         assert_eq!(set.uniform(), Some(&l));
     }
 
-    /// Two loops that differ are refused even though both are live — the DIFFERS class, where the
-    /// slot-0 pin renders a real but *wrong* animation rather than a frozen one
-    /// (`Deterrence_State_Base` tints red→blue in Stand and green→red in Hold).
     #[test]
     fn differing_live_slots_are_not_uniform_either() {
         let set = SeqLoops::new(vec![
@@ -425,15 +336,11 @@ mod tests {
         assert!(set.uniform().is_none());
     }
 
-    /// Nothing anywhere ⇒ no set at all: the caller carries nothing, as it always has for the
-    /// ~98.6 % of batches with no texture transform.
     #[test]
     fn a_set_with_no_live_slot_is_no_set() {
         assert!(SeqLoops::<f32>::new(vec![None, None]).is_none());
     }
 
-    /// An out-of-range or unknown sequence degrades to slot 0 — the same rule `AlphaAnim::seq`
-    /// makes, so a consumer with no live sequence reads what a slot-0-arming consumer would.
     #[test]
     fn an_unknown_sequence_degrades_to_slot_zero() {
         let l = loop_of(1.0, &[(0.0, 0.0), (1.0, 1.0)]);
diff --git a/crates/benilla-formats/src/models/m2_batches.rs b/crates/benilla-formats/src/models/m2_batches.rs
index a9c1d111..40043970 100644
--- a/crates/benilla-formats/src/models/m2_batches.rs
+++ b/crates/benilla-formats/src/models/m2_batches.rs
@@ -1,9 +1,5 @@
-//! The M2 render-batch assembly loop: [`parse_m2_render_submeshes`] walks a parsed M2's skin
-//! batches building one [`RenderSubmesh`] each — resolving its texture/blend/render-flags, baking the
-//! batch's `alpha_anim` (decision 0130 phase 2, via [`mat_anim`](super::mat_anim)) and `uv_anim`
-//! (phase 3, via [`tex_anim`](super::tex_anim)), and splitting a batch across billboard bones so each
-//! glow card rotates about its own pivot. [`load_m2_mesh`]/[`load_m2_mesh_skinned`] are the
-//! chain-reading entry points that feed it.
+//! M2 render-batch assembly: one [`RenderSubmesh`] per skin batch, split across billboard bones so
+//! each card turns about its own pivot.
 
 use std::io::Cursor;
 
@@ -24,7 +20,6 @@ use super::{
     RenderSubmesh,
 };
 
-/// Directory portion of an internal path (everything before the last separator), `""` if none.
 fn parent_dir(path: &str) -> &str {
     match path.rfind(['\\', '/']) {
         Some(i) => &path[..i],
@@ -32,15 +27,14 @@ fn parent_dir(path: &str) -> &str {
     }
 }
 
-/// Resolve a batch's texture to a `.blp` path. `Hardcoded` textures carry their own filename;
-/// `Monster1/2/3` are blank in the M2 and come from the creature's skin variations (resolved to
-/// `<model-dir>\<name>.blp`), falling back to any embedded filename.
+/// A batch's `.blp`: `Monster1/2/3` come from the creature's skin variations
+/// (`<model-dir>\<name>.blp`), else the embedded filename.
 fn resolve_texture(
     tex: &benilla_m2::M2Texture,
     dir: &str,
     skins: &[Option<String>],
 ) -> (Option<String>, Option<u8>, Option<CharSkinSlot>, bool) {
-    // Texture type 14 is the ICON slot — `ReplaceIconTexture`'s target (decision 2008).
+    // Texture type 14 is the icon slot, `ReplaceIconTexture`'s target.
     let icon_slot = matches!(tex.texture_type, M2TextureType::Other(14));
     let embedded = {
         let f = tex.filename.string.to_string_lossy();
@@ -52,11 +46,8 @@ fn resolve_texture(
             .and_then(|o| o.clone())
             .map(|name| format!("{dir}\\{name}.blp"))
     };
-    // Character runtime texture slots — no embedded path; the client fills them per-player from the
-    // appearance (decisions 0041 / 0044 / 0045) or, for `Object`, from the runtime-bound item/cape
-    // skin (decision 0072). M2 texture type 1 = the composited body atlas; type 2 = the object skin;
-    // type 6 = the hair-mesh texture; type 8 = the extra skin (the tauren fur BLP). Flagged so the
-    // spawn site can swap in the right material.
+    // Character slots with no embedded path, filled per player at spawn: type 1 the body atlas,
+    // 2 the object skin (item or cape), 6 the hair texture, 8 the extra skin (tauren fur).
     let char_slot = match tex.texture_type {
         M2TextureType::Other(1) => Some(CharSkinSlot::Body),
         M2TextureType::Other(2) => Some(CharSkinSlot::Object),
@@ -64,8 +55,7 @@ fn resolve_texture(
         M2TextureType::Other(8) => Some(CharSkinSlot::SkinExtra),
         _ => None,
     };
-    // Skin slots resolve to the variation if supplied, else the (usually empty) embedded name; the slot
-    // is reported so a skin-less load can fill it at spawn.
+    // The skin slot is reported so a skin-less load can fill it at spawn.
     match tex.texture_type {
         M2TextureType::Monster1 => (variation(0).or(embedded), Some(0), None, false),
         M2TextureType::Monster2 => (variation(1).or(embedded), Some(1), None, false),
@@ -74,9 +64,7 @@ fn resolve_texture(
     }
 }
 
-/// A fix16 visibility track's **static** value: `None` if time-varying (can't decide visibility at
-/// build time), else `Some(constant)` — an empty track (0 keys) means the factor doesn't apply, so
-/// it reads as `1.0`. Used to fold a batch's colour-alpha / transparency-weight into the cull test.
+/// A visibility track's static value: `None` if time-varying, `1.0` for an empty track.
 fn track_constant(track: &benilla_m2::M2ScalarTrack) -> Option<f32> {
     if track.keys.is_empty() {
         return Some(1.0);
@@ -84,9 +72,7 @@ fn track_constant(track: &benilla_m2::M2ScalarTrack) -> Option<f32> {
     track.constant()
 }
 
-/// Normalise a vertex's 4 raw M2 bone weights (`u8`, summing ~255) to `f32` summing to 1.0 — what the
-/// GPU skin blend expects. A vertex with no weight (sum 0, e.g. a stray static vertex) binds fully to
-/// bone 0 so it rides the root rather than collapsing to the origin.
+/// The 4 raw `u8` weights as `f32` summing to 1; a weightless vertex binds wholly to bone 0.
 fn normalize_weights(w: [u8; 4]) -> [f32; 4] {
     let sum = w.iter().map(|&x| f32::from(x)).sum::<f32>();
     if sum <= 0.0 {
@@ -100,14 +86,8 @@ fn normalize_weights(w: [u8; 4]) -> [f32; 4] {
     ]
 }
 
-/// Read bone `bone_idx`'s **scale** track (M2Track<C3Vector> at `bone + 0x44`) as a global-sequence
-/// [`BoneScaleAnim`], straight from the raw M2 bytes. Returns `None` unless the track has >1 keys AND is
-/// tagged to a global sequence (`gseq != 0xffff`) — the always-looping pulse case (see [`BoneScaleAnim`]).
-///
-/// MD20/bone offsets VERIFIED against wow-5875-re (`fields.md`: bones `count@0x34/ofs@0x38`, stride
-/// `0x6c`, scale track `+0x44`; global sequences `count@0x14/ofs@0x18`) and the real `Lamppost.m2`. The
-/// 28-byte vanilla M2Track tail: `interp@0`, `gseq@0x2`, `key{count@0xc, ofs@0x10}`, `val{count@0x14,
-/// ofs@0x18}` (C3Vector values, stride 12) — the same track shape the particle emission tracks use.
+/// Bone `bone_idx`'s scale track (`+0x44`) as a global-sequence [`BoneScaleAnim`], at the offsets
+/// `0x714260` reads; `None` for a sequence track or fewer than two keys.
 fn parse_bone_scale_anim(bytes: &[u8], bone_idx: usize) -> Option<BoneScaleAnim> {
     let bone_count = bytes.u32_at(0x34)? as usize;
     let bones_ofs = bytes.u32_at(0x38)? as usize;
@@ -118,16 +98,15 @@ fn parse_bone_scale_anim(bytes: &[u8], bone_idx: usize) -> Option<BoneScaleAnim>
     let interp = bytes.u16_at(track)? != 0;
     let gseq = bytes.u16_at(track + 0x02)?;
     if gseq == 0xffff {
-        return None; // armed-animation track, not a global-sequence loop — out of scope here
+        return None; // a sequence track, not a global-sequence loop
     }
     let nkeys = bytes.u32_at(track + 0x0c)? as usize;
     let ts_ofs = bytes.u32_at(track + 0x10)? as usize;
     let nval = bytes.u32_at(track + 0x14)? as usize;
     let val_ofs = bytes.u32_at(track + 0x18)? as usize;
     if nkeys <= 1 || nval < nkeys {
-        return None; // static (≤1 key) — nothing to animate
+        return None; // static: nothing to animate
     }
-    // Resolve the global-sequence duration this track loops over.
     let gseq_count = bytes.u32_at(0x14)? as usize;
     let gseq_o = bytes.u32_at(0x18)? as usize;
     if gseq as usize >= gseq_count {
@@ -154,14 +133,8 @@ fn parse_bone_scale_anim(bytes: &[u8], bone_idx: usize) -> Option<BoneScaleAnim>
     })
 }
 
-/// Read bone `bone_idx`'s **translation** track (M2Track<C3Vector> at `bone + 0x0c`) restricted to
-/// one sequence's absolute time `band`, rebased to it as a loop: the window an arm plays on the
-/// bone — anim 0 is the client's one-time load arm (the questgiver `?` marker's bob), anim 190 the
-/// marker's raised variant (wow-re `questgiver-marker.md` Q4 / `doodad-anim-host.md`). Returns
-/// `None` unless the track is a **sequence** track (`gseq == 0xffff` — the gseq case is the
-/// armed-free loop `parse_bone_scale_anim` handles for scale) holding >1 key inside the band.
-/// Offsets as [`parse_bone_scale_anim`]; the translation track sits at bone `+0x0c` (VERIFIED
-/// wow-5875-re `fields.md`: the three `M2Track`s at `+0x0c/+0x28/+0x44`).
+/// Bone `bone_idx`'s translation track (`+0x0c`) cut to one sequence's `band` as a loop (the
+/// questgiver bob: anim 0 on load, 190 raised, `0x6076c0`); `None` under two keys in the band.
 fn parse_bone_seq_translation(
     bytes: &[u8],
     bone_idx: usize,
@@ -177,7 +150,7 @@ fn parse_bone_seq_translation(
     let track = bones_ofs.checked_add(bone_idx * 0x6c)?.checked_add(0x0c)?;
     let interp = bytes.u16_at(track)? != 0;
     if bytes.u16_at(track + 0x02)? != 0xffff {
-        return None; // a global-sequence loop — not the armed-sequence case
+        return None; // a global-sequence loop
     }
     let nkeys = bytes.u32_at(track + 0x0c)? as usize;
     let ts_ofs = bytes.u32_at(track + 0x10)? as usize;
@@ -186,8 +159,7 @@ fn parse_bone_seq_translation(
     if nval < nkeys {
         return None;
     }
-    // The flat timestamp array concatenates every sequence's keys on one absolute timeline
-    // (`read_bone_track`'s law) — keep only this band's, rebased to its start.
+    // Every sequence's keys share one absolute timeline: keep this band's, rebased to its start.
     let mut keys = Vec::new();
     for k in 0..nkeys {
         let t = bytes.u32_at(ts_ofs.checked_add(k * 4)?)?;
@@ -201,7 +173,7 @@ fn parse_bone_seq_translation(
         ));
     }
     if keys.len() <= 1 {
-        return None; // static in this band — nothing to animate
+        return None; // static in this band
     }
     Some(BoneScaleAnim {
         duration_ms,
@@ -210,14 +182,12 @@ fn parse_bone_seq_translation(
     })
 }
 
-/// Load an M2 model from the chain, split into renderable submeshes (one per skin batch). Doodads
-/// pass no skins; creatures use [`load_m2_mesh_skinned`] to fill their `Monster1/2/3` slots.
+/// Load an M2 from the chain as render submeshes; creatures use [`load_m2_mesh_skinned`].
 pub fn load_m2_mesh(chain: &mut Chain, raw_path: &str) -> Result<Vec<RenderSubmesh>> {
     load_m2_mesh_skinned(chain, raw_path, &[])
 }
 
-/// Like [`load_m2_mesh`], but fills the model's `Monster1/2/3` texture slots from `skins`
-/// (CreatureDisplayInfo `textureVariation` names, in order).
+/// [`load_m2_mesh`] with `Monster1/2/3` filled from `skins` (`CreatureDisplayInfo` variations).
 pub fn load_m2_mesh_skinned(
     chain: &mut Chain,
     raw_path: &str,
@@ -231,9 +201,7 @@ pub fn load_m2_mesh_skinned(
     parse_m2_render_submeshes(&bytes, &dir, skins).with_context(|| format!("parsing M2 {path}"))
 }
 
-/// [`crate::m2_bone_spins`] for a model in the patch chain — the shape [`load_m2_mesh`]'s callers
-/// already use, so a lane wanting both reads the file through the same normalisation rather than
-/// threading bytes across the boundary.
+/// [`crate::m2_bone_spins`] for a model read from the chain.
 pub fn load_m2_bone_spins(
     chain: &mut Chain,
     raw_path: &str,
@@ -245,10 +213,7 @@ pub fn load_m2_bone_spins(
     Ok(crate::m2_bone_spins(&bytes))
 }
 
-/// The model's billboard bones that are **not** rigidly separable — the population the card split
-/// declines to claim, read through the renderer's own predicate so the census can't drift from it
-/// (`benilla-extract bbscan`'s `SEAM` column). Empty for a model with no billboard bones, and for
-/// one whose every card is an ordinary detached quad.
+/// The billboard bones the card split declines as not rigidly separable.
 pub fn non_separable_billboard_bones(bytes: &[u8]) -> Vec<u16> {
     let Ok(format) = parse_m2(&mut Cursor::new(bytes)) else {
         return Vec::new();
@@ -267,21 +232,9 @@ pub fn non_separable_billboard_bones(bytes: &[u8]) -> Vec<u16> {
         .collect()
 }
 
-/// Per bone: may the per-batch card split claim it? `true` for every non-billboard bone (the split
-/// never looks at those) and for a billboard bone whose geometry is rigidly **separable** — see the
-/// call site for why that condition is the whole difference between a card and a torn flap.
-///
-/// Separable means both halves of "nothing else moves with it":
-///
-/// 1. **No partial weight.** Every vertex with any influence from the bone is influenced *only* by
-///    it (weight 255/255). A 50/50 vertex is half a rigid body's worth of motion, which no rigid
-///    group can produce.
-/// 2. **No shared triangle.** Every triangle touching such a vertex has all three fully on the same
-///    bone — otherwise the triangle spans the bone and its static neighbour, and rigidly moving it
-///    rips it off whatever it was welded to. Checked over the whole skin, not per batch: a flap's
-///    seam ring routinely lands in the *body's* batch while its tip sits in the billboard one
-///    (`LShoulder_Plate_PVPAlliance_A_01`, bone 1 — 5 pure vertices in one batch, 8 seam vertices
-///    in another), so a batch-local test would call it separable and tear it anyway.
+/// Per bone: may the card split claim it? Yes for a non-billboard bone, and for a billboard bone
+/// that (1) wholly owns every vertex it influences and (2) every triangle touching one, checked
+/// over the whole skin, since a flap's seam ring can sit in another batch than its tip.
 fn separable_billboard_bones(
     model: &benilla_m2::M2Model,
     tris: &[u16],
@@ -293,7 +246,7 @@ fn separable_billboard_bones(
             *s = false;
         }
     };
-    // (1) any partial weight on a bone disqualifies it outright.
+    // (1) Any partial weight on a bone disqualifies it.
     for v in &model.vertices {
         for i in 0..4 {
             let w = v.bone_weights[i];
@@ -302,15 +255,14 @@ fn separable_billboard_bones(
             }
         }
     }
-    // The bone a vertex is *wholly* on, if any — the only vertex a rigid group can own.
+    // The bone a vertex is wholly on, if any.
     let sole_bone = |g: usize| -> Option<usize> {
         let v = model.vertices.get(g)?;
         (0..4)
             .find(|&i| v.bone_weights[i] == u8::MAX)
             .map(|i| v.bone_indices[i] as usize)
     };
-    // (2) a triangle whose vertices don't all sit wholly on one bone disqualifies every bone it
-    // touches — including the hard (weight-1 vs weight-1) straddle that check (1) can't see.
+    // (2) A triangle not wholly on one bone denies every bone it touches, hard straddles too.
     for t in tris.as_chunks::<3>().0 {
         let g: Vec<usize> = t
             .iter()
@@ -319,7 +271,7 @@ fn separable_billboard_bones(
         let [a, b, c] = g[..] else { continue };
         let (sa, sb, sc) = (sole_bone(a), sole_bone(b), sole_bone(c));
         if sa.is_some() && sa == sb && sb == sc {
-            continue; // wholly one bone: a rigid group can own this triangle
+            continue; // wholly on one bone
         }
         for &v in &[a, b, c] {
             let Some(vert) = model.vertices.get(v) else {
@@ -335,10 +287,7 @@ fn separable_billboard_bones(
     separable
 }
 
-/// Parse an **in-memory** M2 into render submeshes. `dir` is the model's directory (to resolve its
-/// relative texture references); `skins` fill the `Monster1/2/3` texture slots (creature variations).
-/// The bytes-in entry point used by the Bevy `AssetLoader`; [`load_m2_mesh_skinned`] is the
-/// chain-reading wrapper.
+/// An in-memory M2 as render submeshes; `dir` resolves texture paths, `skins` fill `Monster1/2/3`.
 pub fn parse_m2_render_submeshes(
     bytes: &[u8],
     dir: &str,
@@ -360,7 +309,7 @@ pub fn parse_m2_render_submeshes(
             [1.0, 1.0, 1.0, 1.0], // M2 has no MOCV; cleared below so no ATTRIBUTE_COLOR is emitted
         )
     };
-    // `triangles` are local indices into `indices` (→ global vertex). A submesh owns a slice of it.
+    // `triangles` index into `indices`, which index the global vertices.
     let lookup = skin.indices();
     let tris = skin.triangles();
     let global = |t_range: std::ops::Range<usize>| -> Vec<u32> {
@@ -373,38 +322,14 @@ pub fn parse_m2_render_submeshes(
             .collect()
     };
 
-    // **Which billboard bones the per-batch card split is allowed to claim.**
-    //
-    // A card is a RIGID body: the split below pulls a billboard bone's triangles out as their own
-    // submesh and the renderer rotates that whole group about the bone's pivot. The reference has
-    // no card concept at all — it skins every vertex through the bone palette (`m2_vertex_skin`
-    // `0x71a460`), where a billboard bone's camera-replaced matrix (wow-re `billboard-bone-law.md`
-    // §5) is simply one more matrix in a per-vertex weighted blend. The two agree exactly when — and
-    // only when — the bone's geometry is rigidly **separable**: nothing shares a vertex or a
-    // triangle with the rest of the model.
-    //
-    // Where it isn't, a rigid group cannot express the answer *at all*, and the failure is not a
-    // small error: a vertex weighted half to the flap and half to the body has to be placed wholly
-    // on one side, so a flap authored welded to its model is **torn in two** — the free half
-    // sweeping with the camera, the welded half frozen, a detached triangle between them and a
-    // z-fight where the swung half grazes the body. That is the Field Marshal pauldron the director
-    // reported (decision 0839): its two spikes each ride a spherical bone through a 50/50 seam ring.
-    //
-    // So the split takes only the separable bones, and everything else stays ordinary geometry —
-    // whole, in one submesh. On a **rigged** spawn that submesh is the skinned form, so the joint
-    // palette (which already applies the same billboard replacement, `billboard_joint_palette`)
-    // reproduces the reference exactly; on a rig-less spawn the flap holds still instead of bending.
-    // Corpus-wide this claims 16 models of 9691 (236 vertices) — `benilla-extract bbscan`'s SEAM
-    // column — so every ordinary glow card is untouched.
+    // A split card turns rigidly about its pivot, while the reference skins every vertex through
+    // the palette (`0x71a460`), a billboard bone's camera-replaced matrix (`0x7151f9`) one more
+    // weight. The two agree only for a rigidly separable bone; the rest stay whole, skinned on a
+    // rigged spawn (`billboard_joint_palette`).
     let separable = separable_billboard_bones(model, tris, lookup);
 
-    // Every sequence's (anim id, absolute time band, loops): entry stride 0x44, anim id u16 at
-    // +0x00, band start/end u32 at +0x04/+0x08, flags u32 at +0x10 (bit 0 CLEAR = the band loops —
-    // the same read `particles` makes for the emission-timing bake). The first entry's band is the
-    // loop a placed doodad's one-time arm plays; sequence-timeline colour/weight tracks bake
-    // against it (`mat_anim`); the full list feeds the billboard bones' per-sequence translation
-    // loops. The loop flag is the baked loop's CLOCK (`KeyAnim::wrap`) — reading the band without
-    // it is what left a one-shot Death band wrapping back onto its opening alpha.
+    // Every sequence's (anim id, absolute band, loops). The loop flag is the baked loop's clock
+    // (`KeyAnim::wrap`): a one-shot such as Death must not wrap back to its opening alpha.
     let seq_bands: Vec<(u16, (u32, u32), bool)> = {
         let (n, o) = (le_u32(bytes, 0x1c) as usize, le_u32(bytes, 0x20) as usize);
         (0..n)
@@ -420,8 +345,7 @@ pub fn parse_m2_render_submeshes(
             })
             .collect()
     };
-    // The same list as the bake's addressing unit: file slot + band + clock. The slot is what
-    // indexes a track's per-sequence key ranges, so it must stay the FILE order — no filtering.
+    // File slot, band and clock; the slot indexes key ranges, so this keeps file order.
     let seq_slots: Vec<SeqSlot> = seq_bands
         .iter()
         .enumerate()
@@ -431,8 +355,7 @@ pub fn parse_m2_render_submeshes(
             looping,
         })
         .collect();
-    // Slot 0 — the loop a placed doodad's one-time arm plays, and the only band the shared-material
-    // UV/tint registries can key on (see `tex_anim::bake_uv_anim`).
+    // Slot 0: the one band the shared-material UV and tint registries key on.
     let seq0_slot = seq_slots.first().copied();
 
     let sections = skin.submeshes();
@@ -451,7 +374,7 @@ pub fn parse_m2_render_submeshes(
             .texture_lookup_table
             .get(batch.texture_combo_index as usize)
             .and_then(|&ti| model.textures.get(ti as usize));
-        // The record's address mode (`flags & 0x1/0x2`). Absent record ⇒ repeat, the old default.
+        // The record's address mode (`flags & 0x1/0x2`); repeat without a record.
         let (wrap_x, wrap_y) = tex_record.map_or((true, true), |t| (t.wrap_x, t.wrap_y));
         let (texture, skin_slot, char_slot, icon_slot) = tex_record
             .map(|t| resolve_texture(t, dir, skins))
@@ -460,45 +383,28 @@ pub fn parse_m2_render_submeshes(
         let blend = match material.map(|m| m.blend_mode.bits()) {
             Some(0) | None => ModelBlend::Opaque,
             Some(1) => ModelBlend::AlphaTest,
-            // Modes 5/6 are the MULTIPLY blends (wow-re `m2-depth-blend-state`, the DAT_00811fe0
-            // remap): 5 Mod → DST_COLOR/ZERO, 6 Mod2x → DST_COLOR/SRC_COLOR — the ARMORREFLECT
-            // weapon/armor sheen layers. Collapsing them into alpha-Blend painted the reflect
-            // texture OVER the blade instead of modulating it (decision 0528).
+            // Modes 5/6 multiply (the `0x811fe0` remap): 5 Mod is `DST_COLOR/ZERO`, 6 Mod2x
+            // `DST_COLOR/SRC_COLOR`, the ARMORREFLECT sheen layers.
             Some(5) => ModelBlend::Mod,
             Some(6) => ModelBlend::Mod2x,
             Some(_) => ModelBlend::Blend,
         };
-        // M2 blend mode 3 (NoAlphaAdd) / 4 (Add) are **additive** — the renderer adds the batch's colour
-        // instead of mixing the background in (glow cards, coronae). Verified: the lamppost glow card
-        // (GLOW32.BLP, warm amber) carries blend mode 4.
+        // Blend modes 3 (NoAlphaAdd) and 4 (Add) add the batch's colour (glow cards, coronae).
         let additive = matches!(material.map(|m| m.blend_mode.bits()), Some(3) | Some(4));
-        // M2 render flag 0x04 = "Two-sided (no backface culling)" (wowdev.wiki M2 § Render flags).
-        // Unset ⇒ the real client backface-culls this batch (visible from one side only).
+        // Render flag 0x04: two-sided; without it the reference culls back faces.
         let two_sided = material.is_some_and(|m| m.flags.bits() & 0x04 != 0);
-        // **Where this batch's texture coordinates come from** — the two-hop
-        // `texCoordSet(+0x12) → texture_unit_lookup(0x9c)`, gated exactly as the reference gates it
-        // at `0x70b8bd` (`<= 2` = a vertex UV channel, higher = a GENERATED environment
-        // coordinate). Stage 0 only: we bind one texture per batch, and the reference tests the
-        // stage's own slot. An env batch authors no usable UVs at all, so the renderer must derive
-        // them — see `RenderSubmesh::env_map`.
+        // `texCoordSet (+0x12) → texture_unit_lookup (0x9c)` above 2 is a generated environment
+        // coordinate, as the reference gates it at `0x70b8bd`; stage 0 only, one texture a batch.
         let env_map = model.stage_is_env_mapped(batch, 0);
-        // M2 render flag 0x01 = "Unlit" — lighting disabled, so the batch shows at full texture
-        // brightness regardless of sun/ambient: lamp glass, window panes, glow cards. Reuses the same
-        // fullbright `emissive` path as WMO self-illuminated glass. Verified: the lantern/wagon glass
-        // batches (ElwynnLantern01.blp) carry 0x01; their bodies carry 0x00.
+        // Render flag 0x01, unlit: full texture brightness (lamp glass, glow cards).
         let emissive = material.is_some_and(|m| m.flags.bits() & 0x01 != 0);
-        // M2 render flags **0x10 (no depth-write)** / **0x08 (no depth-test)** — the real client keys
-        // per-batch depth state on these bits, NOT on the blend mode (VERIFIED, wow-re
-        // `m2-depth-blend-state`): every batch writes depth + tests LEQUAL unless its own bit clears it.
+        // Render flags 0x10 (no depth write) and 0x08 (no depth test): the reference keys depth
+        // state on these bits, not on the blend mode (`0x70c190`).
         let no_depth_write = material.is_some_and(|m| m.flags.bits() & 0x10 != 0);
         let no_depth_test = material.is_some_and(|m| m.flags.bits() & 0x08 != 0);
-        // The batch's fog COLOUR policy (wow-re rf-weather-emission-timeline ROUND 4, byte-cited): the
-        // M2 batch state setter `0x70baf0` disables fog outright when render flag 0x02 is set
-        // (`0x70bb24`); otherwise the fog colour follows the blend mode via the policy table
-        // `DAT_811fc4 = {1,1,1,2,2,3,4}` dispatched at `0x70bddf`/jump table `0x70c17c` — blend modes
-        // 0/1/2 (opaque/alphakey/alpha) fog toward the scene colour, 3/4 (Add/AddAlpha) toward BLACK
-        // (an additive batch FADES under a veil instead of gaining grey — the storm-veil level-up fix),
-        // 5 (Mod) toward WHITE, 6 (Mod2x) toward GREY. Fog start/end stay the scene values regardless.
+        // Fog colour (setter `0x70baf0`): off under render flag 0x02 (`0x70bb24`), else by blend
+        // mode from `DAT_811fc4 = {1,1,1,2,2,3,4}` (`0x70bddf`, jump table `0x70c17c`): modes
+        // 0/1/2 the scene colour, 3/4 black, 5 white, 6 grey.
         let fog_policy = match material {
             Some(m) if m.flags.bits() & 0x02 != 0 => FogPolicy::Off,
             Some(m) => match m.blend_mode.bits() {
@@ -509,17 +415,13 @@ pub fn parse_m2_render_submeshes(
             },
             None => FogPolicy::Scene,
         };
-        // Static visibility cull (VERIFIED, wow-re `m2-alpha-combine-cull`): the real client multiplies
-        // a per-batch alpha `A = instanceAlpha · colorAlpha · transparencyWeight` and **skips the batch
-        // when `A ≤ 0`** — *before* the blend mode is even read, so it culls even an Opaque batch. A
-        // constant-0 colour-alpha or transparency-weight track is therefore invisible every frame: e.g.
-        // `OrgrimmarFloatingEmbers`' 84-yd emitter box (weight track `[0.0]`). Drop it at build time
-        // (instanceAlpha is 1 here; the runtime doodad-fade alpha is the renderer's separate concern).
-        // Animated tracks (>1 key) can't be decided statically, so we keep them.
+        // Static cull (`0x707b3a`): the reference skips any batch, opaque too, whose
+        // `instanceAlpha · colorAlpha · transparencyWeight ≤ 0`; a constant-0 track is dropped here
+        // (`OrgrimmarFloatingEmbers`' box), as instance alpha is 1 at build.
         let color_alpha = if (batch.color_index as usize) < model.color_alpha_tracks.len() {
             track_constant(&model.color_alpha_tracks[batch.color_index as usize])
         } else {
-            Some(1.0) // colorIndex out of range (incl. 0xffff = none) ⇒ colour factor not applied
+            Some(1.0) // colorIndex out of range (0xffff is none): no colour factor
         };
         let weight = if batch.texture_count != 0 {
             model
@@ -528,25 +430,17 @@ pub fn parse_m2_render_submeshes(
                 .and_then(|&t| model.transparency_tracks.get(t as usize))
                 .map_or(Some(1.0), track_constant)
         } else {
-            Some(1.0) // textureCount 0 ⇒ transparency factor not applied (verified gate)
+            Some(1.0) // textureCount 0: no transparency factor
         };
         if let (Some(c), Some(w)) = (color_alpha, weight) {
             if c * w <= 0.0 {
-                continue; // constant-invisible batch — the real client never draws it
+                continue; // constant-invisible: the reference never draws it
             }
         }
-        // The runtime half of the same combine (decision 0130 phase 2): whatever the static test
-        // above could NOT fold away — a time-varying colour-alpha/weight loop, or a dimming non-1
-        // constant — bakes to an [`AlphaAnim`] the app samples per instance on the model clock.
-        //
-        // Baked **once per sequence**: the tracks key on one absolute timeline that every sequence
-        // carves a band out of, and the reference re-reads them from the *playing* sequence's key
-        // window each frame. Baking only band 0 was right for a placed doodad (one arm, looped
-        // forever) and wrong for every creature — a batch authored to appear only on death reads
-        // its Stand value forever, so we draw geometry the reference hides.
+        // What the static cull cannot fold away bakes to an `AlphaAnim`, one per sequence, as the
+        // reference reads the playing sequence's key window each frame.
         let alpha_anim = {
             let color_track = model.color_alpha_tracks.get(batch.color_index as usize);
-            // textureCount 0 ⇒ transparency factor not applied (verified gate).
             let weight_track = (batch.texture_count != 0)
                 .then(|| {
                     model
@@ -568,52 +462,34 @@ pub fn parse_m2_render_submeshes(
                 .collect();
             AlphaAnim::new(per_seq)
         };
-        // The batch's UV-animation loop (decision 0130 phase 3): batch combo → texAnimLookup →
-        // translation track, on the same clocks. Carried on the submesh; the renderer applies it.
+        // The UV loop: batch combo → `texAnimLookup` → translation track, on the same clocks.
         let uv_anim = tex_anim::bake_uv_anim(model, batch.texture_transform_combo_index, seq0_slot);
-        // …and the per-sequence set, carried ONLY when the slots disagree — the shared-material
-        // registry cannot key on a sequence, so a batch whose loop depends on which one is playing
-        // needs a per-instance consumer instead (decision 1408). `uniform()` asks that once here
-        // rather than leaving it assumed; every batch whose slots agree keeps `uv_anim` alone and
-        // the lane it has always taken.
+        // Per sequence only when the slots disagree: the shared registry cannot key on one.
         let uv_seq = tex_anim::bake_uv_seqs(model, batch.texture_transform_combo_index, &seq_slots)
             .filter(|set| set.uniform().is_none());
-        // The rotation and scaling channels, per slot (decision 2019): consumed only by a lane
-        // that owns its materials per instance (the UI model tiles), so they are carried whole.
+        // Rotation and scaling per slot, for lanes owning a material per instance (UI model tiles).
         let uv_rot_seq =
             tex_anim::bake_uv_rot_seqs(model, batch.texture_transform_combo_index, &seq_slots);
         let uv_scale_seq =
             tex_anim::bake_uv_scale_seqs(model, batch.texture_transform_combo_index, &seq_slots);
-        // The batch's animated RGB tint (the M2Color colour track's runtime half): only a
-        // time-varying track bakes — a `Some` here *replaces* the static vertex tint below (a
-        // spell effect's white-hot flash cooling to red would otherwise freeze on its first key).
+        // The animated M2Color tint: only a time-varying track bakes, replacing the vertex tint.
         let rgb_track = model.color_rgb_tracks.get(batch.color_index as usize);
         let rgb_anim =
             rgb_track.and_then(|t| mat_anim::bake_rgb_anim(t, &model.global_sequences, seq0_slot));
         let rgb_seq = rgb_track
             .and_then(|t| mat_anim::bake_rgb_seqs(t, &model.global_sequences, &seq_slots))
             .filter(|set| set.uniform().is_none());
-        // M2 billboard bones: a batch's vertices ride billboard bones (glow cards, chains) that the
-        // real client re-orients to the camera each frame — **each bone independently, about its own
-        // pivot**. One batch often packs several such cards: a candelabra's candle glows share a single
-        // glow-texture batch, each quad skinned to its own per-candle bone. So we **split the batch
-        // into one submesh per billboard bone** (its pivot the rotation centre). Collapsing them onto a
-        // single pivot (the old first-vertex approach) swings the off-pivot cards in arcs as the camera
-        // turns, and the scale pulse slides them — the candelabra "glows flung across the room" bug.
-        // Triangles not on a billboard bone stay one ordinary submesh, so non-billboard batches and a
-        // lamppost's single glow are unchanged (one group).
+        // The reference turns each billboard bone to the camera about its own pivot, and a batch
+        // can hold cards on several bones (a candelabra's glows): one submesh per billboard bone.
         let make_billboard = |bone_idx: usize| -> Option<Billboard> {
             let bone = model.bones.get(bone_idx)?;
             Some(Billboard {
                 pivot: [bone.pivot.x, bone.pivot.y, bone.pivot.z],
                 bone: bone_idx as u16,
                 kind: BillboardKind::from_bone_flags(bone.flags.bits())?,
-                // The glow-card pulse: this bone's global-sequence scale track (e.g. the lamppost's
-                // 0.86…1.04 breathe over its 1333 ms global sequence). `None` for a static card.
+                // The glow-card pulse: the bone's global-sequence scale track.
                 scale_anim: parse_bone_scale_anim(bytes, bone_idx),
-                // The bone's per-sequence translation loops (the questgiver bob: anim 0 low,
-                // anim 190 raised) — carried on the batch; only the marker spawn site arms one
-                // (see the field doc).
+                // Per-sequence translation loops (the questgiver bob: anim 0 low, 190 raised).
                 seq_translations: seq_bands
                     .iter()
                     .filter_map(|&(id, band, _)| {
@@ -622,9 +498,7 @@ pub fn parse_m2_render_submeshes(
                     .collect(),
             })
         };
-        // A vertex's primary bone, but only when it is a billboard bone (else `None` → the ordinary
-        // group). Group this batch's triangles (chunks of 3 global indices) by that key, in first-
-        // appearance order and preserving triangle order within each group.
+        // A vertex's primary bone if a separable billboard bone; `None` is the ordinary group.
         let primary_billboard_bone = |g: u32| -> Option<usize> {
             let b = model.vertices.get(g as usize)?.bone_indices[0] as usize;
             (model.bones.get(b).is_some_and(|bone| bone.is_billboard())
@@ -640,22 +514,15 @@ pub fn parse_m2_render_submeshes(
                 groups.push((key, tri.to_vec()));
             }
         }
-        // M2Color tint (header 0x54, the colour record's RGB track @ +0x00, selected by
-        // `texUnit.colorIndex`): the per-batch colour the real client multiplies into the vertex
-        // colour. A **constant** track bakes into this batch's vertex colours — dedup-safe (per-mesh,
-        // not per-material) and the model shader already folds `ATTRIBUTE_COLOR` into `base_color` →
-        // `albedo` on every path incl. the fullbright glow cards. **Load-bearing for additive glows on
-        // a neutral glow texture**: the Orgrimmar bonfire's base glow is `GenericGlow_Alpha_128` (a
-        // white-cored radial, no colour of its own), its warmth living entirely in this M2Color
-        // `(0.93,0.66,0.10)` — without it the additive draw washes the bright core to white.
-        // `0xffff`/out-of-range ⇒ no tint (the common case). A **time-varying** track instead rides
-        // `rgb_anim` above (the vertex bake is skipped — the two would double-apply); the render side
-        // seeds the material tint at the first key, so a lane that doesn't animate materials shows
-        // exactly the old static bake. RGB only; alpha stays 1.0 — batch visibility/transparency is
-        // already governed by the alpha-combine cull, the transparency weight, and the runtime doodad
-        // fade, so folding the (possibly animated) M2Color alpha in here too would double-count.
+        // M2Color (header `0x54`, by `texUnit.colorIndex`), which the reference multiplies into the
+        // vertex colour: a constant bakes in here, RGB only, as its alpha is already in the cull
+        // and `alpha_anim`. It is all the warmth of a glow on a neutral texture (the Orgrimmar
+        // bonfire's `GenericGlow_Alpha_128`).
         let color_tint: Option<[f32; 4]> = match &rgb_anim {
             Some(_) => None,
+            // Mod and Mod2x discard the M2Color RGB (`0x70c507`/`0x70c5b8` zero the tint·M2Color
+            // term), so their vertex colours stay untinted.
+            None if matches!(blend, ModelBlend::Mod | ModelBlend::Mod2x) => None,
             None => model
                 .color_rgb_tracks
                 .get(batch.color_index as usize)
@@ -673,10 +540,7 @@ pub fn parse_m2_render_submeshes(
                 emissive,
             );
             sub.billboard = bone.and_then(make_billboard);
-            // …and the other side of the same gate: this batch holds geometry on a billboard bone
-            // the split REFUSED, so no rigid placement of it is right and the lane must skin it to
-            // bend it (decision 0841). Read off the same `separable` table the key above is gated
-            // on, so the renderer's "is this a card" and "is this welded" can never disagree.
+            // Geometry on a billboard bone the split refused, by the same `separable` table.
             sub.welded_billboard = globals.iter().any(|&g| {
                 let v = &model.vertices[g as usize];
                 (0..4).any(|i| {
@@ -686,24 +550,18 @@ pub fn parse_m2_render_submeshes(
                         && !separable.get(b).copied().unwrap_or(false)
                 })
             });
-            sub.env_map = env_map; // texture_unit_lookup > 2 → the runtime generates this stage's UVs
-            sub.additive = additive; // M2 blend mode 3/4 → additive (glow cards)
-            sub.no_depth_write = no_depth_write; // M2 render flag 0x10
-            sub.no_depth_test = no_depth_test; // M2 render flag 0x08
-            sub.fog_policy = fog_policy; // render flag 0x02 / the per-blend fog table
-            sub.skin_slot = skin_slot; // so a skin-less load can fill this batch at spawn
-            sub.geoset_id = section.id; // the skinSectionId — character geoset selection keys on it
-                                        // …and the section INDEX, which is a different question: `geoset_id` says which
-                                        // geoset a compositor may show, this says which TRIANGLES this batch draws. Two
-                                        // batches sharing it are coplanar by construction — see `RenderSubmesh::section`.
+            sub.env_map = env_map;
+            sub.additive = additive;
+            sub.no_depth_write = no_depth_write;
+            sub.no_depth_test = no_depth_test;
+            sub.fog_policy = fog_policy;
+            sub.skin_slot = skin_slot;
+            sub.geoset_id = section.id;
             sub.section = Some(batch.skin_section_index);
-            sub.wrap_x = wrap_x; // texture record flags 0x1/0x2 — clamp is a silhouette decision
+            sub.wrap_x = wrap_x;
             sub.wrap_y = wrap_y;
-            sub.char_slot = char_slot; // character runtime slot (body/hair) — filled per-player at spawn
-            sub.icon_slot = icon_slot; // texture type 14 — `ReplaceIconTexture`'s slot (decision 2008)
-                                       // Skeletal skin binding (decision 0019), per local vertex in `globals` order: the M2
-                                       // vertex's 4 bone indices (global bone-array indices → joint indices directly) + their
-                                       // normalised weights. The skinned-mesh builder uploads these; the static mesh ignores them.
+            sub.char_slot = char_slot;
+            sub.icon_slot = icon_slot;
             sub.joints = globals
                 .iter()
                 .map(|&g| {
@@ -721,13 +579,12 @@ pub fn parse_m2_render_submeshes(
                 .map(|&g| normalize_weights(model.vertices[g as usize].bone_weights))
                 .collect();
 
-            // Tint via vertex colours when the batch carries an M2Color; else none — M2 has no MOCV, so
-            // an empty vec means the renderer skips ATTRIBUTE_COLOR and the texture shows untinted.
+            // No tint leaves the vec empty, so the renderer emits no `ATTRIBUTE_COLOR`.
             match color_tint {
                 Some(c) => sub.vertex_colors = vec![c; sub.positions.len()],
                 None => sub.vertex_colors.clear(),
             }
-            sub.alpha_anim = alpha_anim.clone(); // every billboard-split group shares the batch's loops
+            sub.alpha_anim = alpha_anim.clone();
             sub.uv_anim = uv_anim.clone();
             sub.uv_seq = uv_seq.clone();
             sub.uv_rot_seq = uv_rot_seq.clone();
@@ -737,18 +594,8 @@ pub fn parse_m2_render_submeshes(
             out.push(sub);
         }
     }
-    // Invisible interaction-zone placeholder (the `SpellObject_InvisibleTrap` class — Fire-Festival
-    // fury zones, rallying-cry triggers, tonk-game consoles…): a flat (degenerate render box) quad
-    // whose every batch is **opaque** and textured solely with the engine utility-white `WHITE1.BLP`.
-    // The real 1.12 client DRAWS this mesh, but at per-instance render alpha ≈0 (the doodad-fade alpha
-    // slot drives it to ~0 here) so it is invisible — VERIFIED by a reference apitrace (wow-re
-    // `object-layer/scratch/go-render-gate.md`, the firing-4 capstone: drawn alpha-blended at
-    // α=8.5e-05). What *drives* that ≈0 alpha is an un-RE'd world-scene-render detail (open handoff),
-    // so benilla reproduces the observed invisibility by recognising the placeholder asset and dropping
-    // its geometry. Scoped tight on purpose: verified against all 1602 GameObject display models, ONLY
-    // this placeholder matches — visible flat decals (orc sleep mats, pentagram circles, AQ door runes)
-    // carry real textures + Blend/AlphaTest and are kept. Empirical stop-gap, not the client mechanism
-    // (decision 0030).
+    // The invisible `SpellObject_InvisibleTrap` placeholder, which the reference draws at alpha ≈0
+    // (8.5e-05 in a trace) from an untraced source; this drops its geometry instead.
     if is_white1_placeholder(
         model.header.bounding_box_min,
         model.header.bounding_box_max,
@@ -759,12 +606,8 @@ pub fn parse_m2_render_submeshes(
     Ok(out)
 }
 
-/// The invisible-interaction-zone placeholder fingerprint: a model with a **degenerate render box**
-/// (zero extent on some axis — a flat quad) whose **every** render batch is opaque and textured solely
-/// with the engine utility-white `WHITE1.BLP` (`SpellObject_InvisibleTrap` & kin). Such a model is the
-/// real client's invisible-by-near-zero-alpha placeholder, drawn but unseen; benilla drops its geometry
-/// to match. Returns `false` for an empty batch set, a 3D box, or any non-opaque / non-`WHITE1` batch
-/// (so visible flat decals are kept). See the call site + decision 0030.
+/// A flat render box whose every batch is opaque `WHITE1.BLP`: no GameObject model but the
+/// placeholder matches, and textured flat decals stay.
 fn is_white1_placeholder(bbox_min: [f32; 3], bbox_max: [f32; 3], subs: &[RenderSubmesh]) -> bool {
     if subs.is_empty() {
         return false;
@@ -780,26 +623,9 @@ fn is_white1_placeholder(bbox_min: [f32; 3], bbox_max: [f32; 3], subs: &[RenderS
         })
 }
 
-/// How far a model's own **transparent-pass batches** sort from its origin, model-local yards —
-/// the bound the renderer's owner-last draw-order rung is sized from (decisions 0719/0721).
-///
-/// The reference draws a model's emitters in their own bracket *after* that model's batches; we put
-/// both in one distance-sorted transparent list, so an effect has to be biased past every batch of
-/// its owner — and no further, or it also jumps other models' transparents. What it must clear is
-/// therefore the farthest point any of those batches SORTS at, and a batch sorts at its own
-/// bind-pose AABB **centre**, not at its farthest vertex.
-///
-/// That distinction is the whole reason this function exists rather than reading
-/// [`super::M2Bounds::vert_max_from_origin`]. Measured over the 1.12.1 corpus's 967 at-risk models,
-/// swapping the vertex bound for this one drops 83 models past the rung ceiling to 46 and moves 144
-/// models down to rung 1 — a waterfall's single long batch drags the vertex bound to hundreds of
-/// yards while every batch centre sits a few yards from the origin.
-///
-/// Only transparent-pass batches count: an opaque or alpha-tested batch is binned in `Opaque3d` /
-/// `AlphaMask3d` and settles against the effect by depth, never by list order. The blend test
-/// mirrors the renderer's own (`benilla::model_render::model_material`), where `additive` forces the
-/// transparent pass whatever the authored blend word says. A model with no transparent batch at all
-/// returns `0.0` — nothing of its own can paint over its effects, and rung 1 still holds the law.
+/// How far a model's transparent batches sort from its origin, yards: the reference draws a
+/// model's emitters after its batches, which one sorted list gets by biasing past them. A batch
+/// sorts at its bind-pose box centre, not [`super::M2Bounds::vert_max_from_origin`].
 pub fn m2_owner_reach(subs: &[RenderSubmesh]) -> f32 {
     subs.iter()
         .filter(|s| {
@@ -818,58 +644,29 @@ pub fn m2_owner_reach(subs: &[RenderSubmesh]) -> f32 {
                     hi[k] = hi[k].max(p[k]);
                 }
             }
-            // Distance from the origin, so the raw-WoW/Bevy axis question doesn't arise: the two
-            // frames differ by a signed axis permutation, which preserves length.
+            // A length, so the same in WoW and Bevy axes (a signed axis permutation apart).
             let c: [f32; 3] = std::array::from_fn(|k| 0.5 * (lo[k] + hi[k]));
             (c[0] * c[0] + c[1] * c[1] + c[2] * c[2]).sqrt()
         })
         .fold(0.0f32, f32::max)
 }
 
-/// The **owner-last** draw-order rung for an effect whose owner reaches `reach_world` world yards:
-/// the `Transparent3d` depth bias that puts it after every transparent batch of its own model and
-/// no further (`benilla::particles::owner_last_bias` is the one caller that applies it; `emdump`
-/// and `benilla-extract fxordercensus` print it).
-///
-/// It lives here, beside [`m2_owner_reach`], because a rung computed three times in three crates
-/// drifts three ways — and this is the number the survey tools have to print to be worth reading.
-///
-/// Snapped to the next whole yard **above** the reach, for two reasons. Bevy folds
-/// `depth_bias as i32` into the material's *pipeline key*, so a free-floating float would specialize
-/// a fresh pipeline per distinct model radius; and `≥` has to become `>`, or a batch centred exactly
-/// at the reach ties with the effect and the order falls back to whatever the queue emitted.
-/// `floor + 1` does both. Over-biasing costs only ordering against OTHER models' transparents within
-/// the rung, so the rounding goes up; under-biasing reinstates the defect.
+/// The `Transparent3d` depth bias sorting an effect after its owner's transparent batches and no
+/// further: the next whole yard above the reach, since Bevy keys pipelines on `depth_bias as i32`
+/// and a batch centred at the reach must not tie.
 pub fn owner_last_rung(reach_world: f32) -> f32 {
-    // The ceiling keeps this rung far below every rung in `benilla::sky_order`'s ladder (the
-    // nearest, the ground-fx one, is four orders of magnitude up). 46 corpus models reach past it
-    // — Maraudon's waterfalls, the Dire Maul vortex, the glue screens, whose transparent batches
-    // spread 30–780 yd from their origin. Those keep the interleave: biasing an effect past a
-    // 200-yard owner would put it in front of every transparent surface in the zone, which is the
-    // worse of the two errors (decision 0721).
+    // Deviation: owners past the ceiling (Maraudon's waterfalls, the glue screens) keep the
+    // interleave with their emitters, because a bias past a 200-yard owner would jump every
+    // transparent surface in the zone.
     const MAX_RUNG: f32 = 32.0;
     (reach_world.max(0.0).floor() + 1.0).min(MAX_RUNG)
 }
 
-/// The FINITE set of rung values a mesh-shard **material** may carry — the quantization of
-/// [`owner_last_rung`] for the one lane where the rung rides `StandardMaterial::depth_bias` and
-/// is therefore a *pipeline-key axis* (bevy folds `depth_bias as i32` into the key; benilla
-/// decision 0837). The quad-particle lane applies its rung at queue time and keeps the exact
-/// value; the 3-D-shard lane materializes it, and 32 integer rungs × every reachable blend state
-/// is an open key space no warm pass can pre-compile — each first-seen combination was a
-/// synchronous render-thread pipeline compile mid-spell-cast. A closed bucket set is compilable
-/// behind the loading cover by construction (`benilla::pipe_warm` iterates exactly this array).
-///
-/// Bucket choice: rounding UP is the blessed error direction (decision 0721 — over-biasing only
-/// costs ordering against other models' transparents inside the delta), and the buckets are
-/// spaced so the common case stays tight: spell-kit owners are small (rung ≤ 4 — the corpus
-/// census `benilla-extract shardcensus` is the ground truth), so most shards take the first
-/// bucket and at worst a few yards of over-bias; the tail rides the coarser rungs.
+/// The rungs a mesh-shard material may carry, a pipeline-key axis through `depth_bias`: a closed
+/// set `pipe_warm` compiles behind the loading cover. Most spell-kit owners fit the first.
 pub const OWNER_RUNG_BUCKETS: [f32; 3] = [4.0, 12.0, 32.0];
 
-/// Snap an [`owner_last_rung`] value UP to its material bucket (see [`OWNER_RUNG_BUCKETS`]).
-/// Total for any input: values past the last bucket (impossible — `owner_last_rung` caps at the
-/// same 32) still return it, so the key space stays closed no matter what.
+/// Snap a rung up to its bucket, the last one past the end, so the key space stays closed.
 pub fn owner_last_rung_bucket(rung: f32) -> f32 {
     for b in OWNER_RUNG_BUCKETS {
         if rung <= b {
@@ -879,24 +676,9 @@ pub fn owner_last_rung_bucket(rung: f32) -> f32 {
     OWNER_RUNG_BUCKETS[OWNER_RUNG_BUCKETS.len() - 1]
 }
 
-/// **Which of a model's textures a given sequence actually shows**, resolved to `.blp` paths in
-/// batch order.
-///
-/// A model can carry several alternative arts as separate batches and let the *played sequence*
-/// choose between them — one M2Color alpha track per batch, each stepping its own layer to 1.0 in
-/// its own sequence's band and holding 0.0 everywhere else. `Interface\Minimap\Rotating-MinimapArrow`
-/// is built exactly that way: six layers, four of them the four rim-arrow arts (decision 1519). That
-/// is invisible from the batch list alone, which just shows six textures, so this answers the
-/// question the batch list can't: play sequence `N`, see what.
-///
-/// The evaluation is the reference's, and both halves matter. A track's keys live on the model's
-/// **global** timeline with a per-sequence key *window* ([`benilla_m2::M2Track::ranges`]), so a
-/// sequence's value is searched inside its own window, not across every key; and these tracks are
-/// authored `interp = 0` (**step**), so a band that keys nothing holds the last key at or before it
-/// — which is how three of four layers stay at 0.0 through a band they never touch. A batch counts
-/// as shown when both its colour alpha and its texture-weight evaluate nonzero at the band's start.
-///
-/// `None` if the model doesn't parse, has no skin, or authors no sequence with that id.
+/// The textures sequence `anim_id` shows, in batch order: a model can hold alternative arts whose
+/// M2Color alpha steps to 1 only in their own band (`Rotating-MinimapArrow`). Each track holds its
+/// last key at or before the band, searched in the sequence's key window as the reference does.
 pub fn m2_sequence_visible_textures(bytes: &[u8], anim_id: u16) -> Option<Vec<String>> {
     let format = parse_m2(&mut Cursor::new(bytes)).ok()?;
     let model = format.model();
@@ -905,8 +687,7 @@ pub fn m2_sequence_visible_textures(bytes: &[u8], anim_id: u16) -> Option<Vec<St
         .into_iter()
         .find(|a| a.anim_id == anim_id)?;
 
-    // Step-evaluate one track inside this sequence's own key window. An empty window (`lo >= hi`)
-    // degenerates to `keys[lo]`, the same value the reference's key search lands on there.
+    // An empty window (`lo >= hi`) gives `keys[lo]`, as the reference's key search does.
     let at_band_start = |track: &benilla_m2::M2ScalarTrack| -> f32 {
         let (lo, hi) = track
             .ranges
@@ -957,10 +738,7 @@ pub fn m2_sequence_visible_textures(bytes: &[u8], anim_id: u16) -> Option<Vec<St
 mod tests {
     use super::*;
 
-    /// The bucket law: total, never under the exact rung (a shard may never sort under its
-    /// sibling quad cloud, which keeps the exact value), monotonic, always a member of the
-    /// closed set — and the set's ceiling is [`owner_last_rung`]'s own cap, so no reachable
-    /// rung escapes the warmed key space.
+    /// A bucket never sorts under the exact rung, which its sibling quad cloud keeps.
     #[test]
     fn owner_rung_buckets_cover_every_reachable_rung() {
         let max = OWNER_RUNG_BUCKETS[OWNER_RUNG_BUCKETS.len() - 1];
@@ -976,15 +754,12 @@ mod tests {
             );
             prev = b;
         }
-        // The set itself is sorted ascending — the snap-up scan relies on it.
+        // The snap-up scan relies on the set ascending.
         assert!(OWNER_RUNG_BUCKETS.windows(2).all(|w| w[0] < w[1]));
     }
 
-    /// The tauren body, straight off the real client data: its M2 type-8 (extra skin — the fur)
-    /// batches must surface as [`CharSkinSlot::SkinExtra`] parts, in both authored flavors — the
-    /// opaque single-sided fur core and the alpha-cut two-sided fringe cards — so the spawn site can
-    /// bind the CharSections `_Extra` BLP per flavor. Unmapped, these batches carry no texture and
-    /// draw flat white (the "cows are white" bug).
+    /// `TaurenMale.m2`'s type-8 fur, opaque core and alpha-cut two-sided fringe alike, surfaces as
+    /// [`CharSkinSlot::SkinExtra`]; unmapped, it draws flat white.
     #[test]
     fn tauren_fur_batches_carry_the_skin_extra_slot() {
         let data = crate::wow_data_or_skip!();
@@ -1018,11 +793,7 @@ mod tests {
         );
     }
 
-    /// The Whirlwind Axe (display 22734 → `Axe_2H_Horde_C_01.m2`), straight off the real client
-    /// data: three batches — handle + blade on the runtime Object skin, and the blade's
-    /// ARMORREFLECT layer as **Mod2x** (material `{flags 0x10, blendMode 6}` — the multiply blend,
-    /// decision 0528) with no depth write and NOT additive. Collapsing mode 6 into alpha-Blend is
-    /// exactly the "flat pale blade" regression this pins against.
+    /// `Axe_2H_Horde_C_01.m2`'s ARMORREFLECT layer is material `{flags 0x10, blendMode 6}`.
     #[test]
     fn whirlwind_axe_reflect_layer_is_mod2x() {
         let data = crate::wow_data_or_skip!();
@@ -1055,15 +826,8 @@ mod tests {
         assert!(reflect.no_depth_write, "render flag 0x10");
     }
 
-    /// The Field Marshal pauldron (`LShoulder_Plate_PVPAlliance_A_01.m2`), the director's report:
-    /// its two little spikes each ride a spherical-billboard bone through a **50/50 seam ring**, so
-    /// neither bone is rigidly separable and neither may be split into a card. The whole model must
-    /// come out as ONE welded batch — the spikes' own vertices, the seam ring, and the body.
-    ///
-    /// The seam ring is the point. Bone 1's five fully-weighted vertices sat in their own batch
-    /// while its eight 50/50 vertices sat in the *body's*, so the split saw a clean card, tore the
-    /// spike off the shoulder and swung it with the camera (decision 0839). A batch-local
-    /// separability test would still see a clean card here; only the model-wide one catches it.
+    /// `LShoulder_Plate_PVPAlliance_A_01.m2`'s spikes ride billboard bones through 50/50 seam rings
+    /// that sit in the body's batch, so only a model-wide test sees the weld.
     #[test]
     fn a_welded_billboard_spike_is_never_split_into_a_card() {
         let data = crate::wow_data_or_skip!();
@@ -1076,8 +840,7 @@ mod tests {
             "a welded bone is never claimed by the card split"
         );
         assert_eq!(subs[0].positions.len(), 152, "every vertex is present");
-        // …and the welded batch really does carry the seam — otherwise this test would still pass
-        // on a build that simply dropped the spikes.
+        // The seam is present, or a build that dropped the spikes would pass.
         let seam = subs[0]
             .weights
             .iter()
@@ -1087,23 +850,15 @@ mod tests {
             seam, 16,
             "the two 8-vertex 50/50 seam rings are in the mesh"
         );
-        // …and the batch SAYS it is welded — the other half of the same gate, and the flag a lane
-        // reads to decide it must skin this model (decision 0841). A build where the split key and
-        // this flag disagreed would draw the spikes rigid and call it fine.
         assert!(
             subs[0].welded_billboard,
             "the welded batch announces itself to the render lanes"
         );
-        // The renderer's predicate, read directly: both billboard bones are the denied ones.
         let bytes = chain.read_file(path).expect("read the m2");
         assert_eq!(non_separable_billboard_bones(&bytes), vec![1, 2]);
     }
 
-    /// The counter-anchor: an ordinary **detached** glow card is untouched by that rule. The PVP
-    /// two-hander's two hilt glows are 4-vertex quads wholly on their own spherical bone, sharing
-    /// no triangle with the blade — exactly the shape the card split exists for, and 4372 of the
-    /// corpus's billboard batches are like this. If separability ever over-denies, this is what
-    /// goes dark first.
+    /// `Sword_2H_PVPAlliance_A_01.m2`'s hilt glows are 4-vertex quads wholly on their own bones.
     #[test]
     fn a_detached_glow_card_is_still_split_out() {
         let data = crate::wow_data_or_skip!();
@@ -1127,13 +882,8 @@ mod tests {
         );
     }
 
-    /// The questgiver `?` marker, straight off the real client data: ONE cylindrical-billboard
-    /// bone with a 3-key translation bob per sequence — anim **0** (the load arm's low bob) and
-    /// anim **190**, the authored **raised** bob the client arms while the unit shows an overhead
-    /// name (wow-re `questgiver-marker.md` Q4; m2bones-probed key values: anim 0 spans WoW z
-    /// 0.000→−0.089, anim 190 z +0.517→+0.427 — same key COUNT, different values, which is
-    /// exactly how the earlier "seq 190 = same bob" count-only probe went wrong). Guards the
-    /// band-restricted translation bake end-to-end.
+    /// The questgiver `?` bobs z 0.000 → −0.089 in anim 0 and +0.517 → +0.427 in anim 190, the
+    /// raised bob the client arms under an overhead name (`0x6076c0`).
     #[test]
     fn questionmark_marker_batch_carries_both_bob_loops() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/models/mat_anim.rs b/crates/benilla-formats/src/models/mat_anim.rs
index de14e816..681a8316 100644
--- a/crates/benilla-formats/src/models/mat_anim.rs
+++ b/crates/benilla-formats/src/models/mat_anim.rs
@@ -1,53 +1,35 @@
-//! The animated **material-alpha** bake (decision 0130 phase 2): each M2 batch's colour-alpha and
-//! transparency-weight tracks, baked to loopable second-domain keys the runtime samples per instance
-//! — **one loop per sequence**, because which loop plays is a function of the playing animation.
-//!
-//! Byte ground (wow-re `m2-alpha-combine-cull.md`, VERIFIED): the per-batch alpha is
-//! `A = instanceAlpha × colors[colorIndex].alpha × transparency[transLookup[idx]].weight`, both
-//! tracks animation-evaluated each frame; `A ≤ 0` skips the batch before the blend mode is read, and
-//! an Opaque batch with `0 < A < 1` is **promoted to a blended draw** (that note's original "stays
-//! opaque" was refuted at the bytes on 2026-07-31 — wow-re `m2-blend-promotion-zfill.md` §1;
-//! benilla implements the promotion, decisions 0831/0842). Clocks (wow-re
-//! `eval.md`/`doodad-anim-host.md`): a `gseq`-tagged track wraps `global_sequences[gseq]`; an
-//! ordinary track keys inside the **playing** sequence's absolute time band — for a placed doodad
-//! that is the file-order-first sequence looping forever, but a creature changes sequence constantly
-//! and its batches' visibility changes with it (a voidwalker's upper armour pair is weight 0 in
-//! Stand/Walk/Run and 1 only in Death).
-//!
-//! The sampler + clock resolution live in [`super::key_anim`] (shared with the texture-transform
-//! bake); this module owns only the alpha channel's semantics.
+//! The material-alpha bake: each M2 batch's colour-alpha and transparency-weight tracks as loops
+//! the runtime samples per instance, one per sequence. The reference's per-batch alpha is
+//! `instanceAlpha × colors[colorIndex].alpha × transparency[transLookup[idx]].weight`, both tracks
+//! evaluated every frame (`0x707680`); `A ≤ 0` skips the batch before its blend mode is read, and
+//! an opaque batch with `0 < A < 1` draws blended (`0x70c20f`).
 
 use benilla_m2::{M2ScalarTrack, M2Vec3Track};
 
 use super::key_anim::{bake_track, KeyAnim, SeqLoops, SeqSlot};
 
-/// One baked scalar loop, seconds — see [`KeyAnim`]. The alpha channels' instantiation.
+/// One baked scalar loop, the alpha channels' [`KeyAnim`].
 pub type ScalarAnim = KeyAnim<f32>;
 
 impl KeyAnim<f32> {
-    /// Sample at `elapsed` seconds on the loop clock (`1.0` — the multiplicative identity — for a
-    /// defensively-empty loop the bake never emits).
+    /// Sample at `elapsed` seconds; `1.0` for an empty loop.
     pub fn sample(&self, elapsed: f32) -> f32 {
         self.sample_or(elapsed, 1.0)
     }
 }
 
-/// One baked RGB tint loop — the M2Color **colour** track's instantiation (the per-batch tint the
-/// real client multiplies into the vertex colour, animation-evaluated like the alpha).
+/// One baked RGB loop, the `M2Color` tint the reference multiplies into the vertex colour.
 pub type RgbAnim = KeyAnim<[f32; 3]>;
 
 impl KeyAnim<[f32; 3]> {
-    /// Sample at `elapsed` seconds on the loop clock (white — the tint identity — for a
-    /// defensively-empty loop the bake never emits).
+    /// Sample at `elapsed` seconds; white for an empty loop.
     pub fn sample(&self, elapsed: f32) -> [f32; 3] {
         self.sample_or(elapsed, [1.0, 1.0, 1.0])
     }
 }
 
-/// A batch's animated-alpha pair **for one sequence**: the colour-alpha factor and the
-/// transparency-weight factor — multiplied together (and by the instance alpha) at sample time, per
-/// the verified combine. Either side absent ⇒ that factor is constant `1` (or already baked/culled
-/// statically) in this sequence.
+/// A batch's two alpha factors in one sequence, multiplied at sample time; an absent factor is 1
+/// or was folded statically.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AlphaSeq {
     pub color: Option<ScalarAnim>,
@@ -55,9 +37,8 @@ pub struct AlphaSeq {
 }
 
 impl AlphaSeq {
-    /// The combined factor at `elapsed` seconds into this sequence, with `shared_now` the world's
-    /// shared elapsed seconds — each factor routes to its own clock ([`KeyAnim::clock`]: a gseq
-    /// loop reads the shared clock, a band loop the sequence time).
+    /// The combined factor `elapsed` seconds into this sequence, `shared_now` being the instance's
+    /// global-sequence cursor; each factor takes its own clock ([`KeyAnim::clock`]).
     pub fn sample(&self, elapsed: f32, shared_now: f64) -> f32 {
         let at = |a: &ScalarAnim| a.sample(a.clock(elapsed, shared_now));
         let c = self.color.as_ref().map_or(1.0, at);
@@ -65,30 +46,24 @@ impl AlphaSeq {
         c * w
     }
 
-    /// Nothing to evaluate — both factors are the identity in this sequence.
     fn is_empty(&self) -> bool {
         self.color.is_none() && self.weight.is_none()
     }
 }
 
-/// A batch's animated alpha across the **whole model**: one [`AlphaSeq`] per sequence, indexed by
-/// the model's **file** sequence slot (the same slot [`benilla_m2::M2Track::ranges`] is indexed by,
-/// and the one [`crate::ModelAnimation::seq_index`] carries to the runtime).
-///
-/// Per-sequence and not per-model because the reference re-reads the tracks from the *playing*
-/// sequence's key window every frame: the same batch is hidden in Stand and drawn in Death. A
-/// consumer that doesn't know which sequence is playing (a placed doodad, which arms
-/// `animations[0]` once and loops it forever) passes `None` and gets slot 0 — the old behaviour,
-/// still correct there.
+/// A batch's animated alpha for the whole model, one [`AlphaSeq`] per file sequence slot (the
+/// slot [`benilla_m2::M2Track::ranges`] and [`crate::ModelAnimation::seq_index`] use), since the
+/// reference reads the playing sequence's window every frame: hidden in Stand, drawn in Death.
+/// A consumer that passes no sequence reads slot 0; the placed-doodad lane does, on its spawn
+/// clock. The reference reads bone 0's armed sequence, which for a placed doodad is animation id
+/// 0, its variation re-rolled every play window (`0x7121a0`).
 #[derive(Clone, Debug, PartialEq)]
 pub struct AlphaAnim {
     per_seq: Vec<AlphaSeq>,
 }
 
 impl AlphaAnim {
-    /// Build from one entry per file sequence slot, or `None` if no sequence animates either factor
-    /// (the overwhelming majority of batches — the caller then carries no anim at all). Public so a
-    /// consumer's tests can build the shape the bake emits without a real M2.
+    /// `None` when no sequence animates either factor, the common case.
     pub fn new(per_seq: Vec<AlphaSeq>) -> Option<Self> {
         per_seq
             .iter()
@@ -96,9 +71,7 @@ impl AlphaAnim {
             .then_some(Self { per_seq })
     }
 
-    /// This batch's factors in sequence slot `seq` (slot 0 when unknown / out of range — the
-    /// doodad lane's one-time arm, and the safe degrade for a model whose sequence list and track
-    /// ranges disagree).
+    /// This batch's factors in slot `seq`, slot 0 when unknown or out of range.
     pub fn seq(&self, seq: Option<usize>) -> &AlphaSeq {
         const IDENTITY: &AlphaSeq = &AlphaSeq {
             color: None,
@@ -109,23 +82,17 @@ impl AlphaAnim {
             .unwrap_or(IDENTITY)
     }
 
-    /// The combined factor `elapsed` seconds into sequence slot `seq` (`shared_now` = the world's
-    /// shared elapsed seconds, for the gseq-clocked factors).
+    /// The combined factor `elapsed` seconds into slot `seq` ([`AlphaSeq::sample`]).
     pub fn sample(&self, seq: Option<usize>, elapsed: f32, shared_now: f64) -> f32 {
         self.seq(seq).sample(elapsed, shared_now)
     }
 
-    /// Every file sequence slot's pair, file order — the census instrument's read
-    /// (`benilla-extract entityuvscan`), the twin of [`SeqLoops::slots`] and there for the same
-    /// reason: an instrument that re-implements the per-slot walk can drift from the one the
-    /// runtime takes. Without it a sweep cannot even tell how many slots a batch was baked across,
-    /// because [`Self::seq`] degrades an out-of-range slot to slot 0 rather than refusing it.
+    /// Every slot's pair in file order, for `benilla-extract entityuvscan`.
     pub fn slots(&self) -> &[AlphaSeq] {
         &self.per_seq
     }
 
-    /// Whether ANY sequence can drive this batch's alpha to zero — i.e. whether the batch is ever
-    /// culled. The spawn-side gate for "does this part need a live sampler at all".
+    /// Whether any sequence can drive the alpha to zero, culling the batch.
     pub fn ever_hides(&self) -> bool {
         self.per_seq.iter().any(|s| {
             [s.color.as_ref(), s.weight.as_ref()]
@@ -136,12 +103,9 @@ impl AlphaAnim {
     }
 }
 
-/// Bake one scalar track to a [`ScalarAnim`], or `None` when it contributes nothing the static path
-/// doesn't already handle: no keys (factor doesn't apply), a constant 1 (identity), or a constant
-/// ≤ 0 (the static cull already dropped the batch). A dimming constant IS kept — the real combine
-/// dims the batch by it, which the static vertex bake never did — and a band-empty track holding a
-/// non-1 value bakes that hold, **including a held 0** (the batch must stay hidden every frame; the
-/// static cull never saw it because the full track isn't constant).
+/// Bake one scalar track, or `None` with no keys, a constant 1, or a constant ≤ 0 (the static cull
+/// already dropped the batch). A dimming constant is kept, and a band holding a non-1 value bakes
+/// that hold, a held 0 included: the static cull never saw it.
 pub(super) fn bake_scalar_anim(
     track: &M2ScalarTrack,
     gseq_durations: &[u32],
@@ -157,11 +121,9 @@ pub(super) fn bake_scalar_anim(
     )
 }
 
-/// Bake one M2Color **RGB** track to an [`RgbAnim`], or `None` unless the track genuinely varies
-/// inside the model's clock (a spell effect's white-hot flash cooling to red). Constants — and
-/// band-empty/single-key holds — stay `None` so the **static vertex-colour bake** (`m2_batches`,
-/// decision 0029) keeps owning them unchanged; only a time-varying track moves the tint to the
-/// animated material channel (and skips the vertex bake, so the two never double-apply).
+/// Bake one `M2Color` RGB track only when it varies in time: constants and holds stay with the
+/// static vertex-colour bake in `m2_batches`, which a varying track skips, so the two never
+/// double-apply.
 pub(super) fn bake_rgb_anim(
     track: &M2Vec3Track,
     gseq_durations: &[u32],
@@ -170,11 +132,8 @@ pub(super) fn bake_rgb_anim(
     bake_track(track, gseq_durations, seq, |v| v, |_| true, |_| true)
 }
 
-/// The per-sequence form of [`bake_rgb_anim`] — same shape, same reason as
-/// [`super::tex_anim::bake_uv_seqs`]. The tint channel is pinned to slot 0 by the same line and
-/// breaks the same way: `uvslotscan` finds `Spells\\Deterrence_State_Base.m2` tinting
-/// **red→blue in Stand and green→red in Hold**, so the slot-0 pin renders a *wrong colour* there,
-/// not merely a frozen one (decision 1408).
+/// [`bake_rgb_anim`] per file sequence slot, for a tint keyed differently per sequence
+/// (`Spells\\Deterrence_State_Base.m2` goes red to blue in Stand, green to red in Hold).
 pub(super) fn bake_rgb_seqs(
     track: &M2Vec3Track,
     gseq_durations: &[u32],
@@ -192,12 +151,7 @@ pub(super) fn bake_rgb_seqs(
 mod tests {
     use super::*;
 
-    /// The Stormwind mage portal, straight off the real client data: its shimmer is authored as
-    /// animated transparency-weight tracks (3 of its 4 records are time-varying — `doodadscan`'s
-    /// material-channel listing), so `parse_m2_render_submeshes` must emit at least one batch with a
-    /// live weight loop whose sampled value actually varies. Guards the whole bake chain — the full
-    /// scalar-track parse (benilla-m2), the transLookup two-hop, the gseq/band clock resolution —
-    /// against a silent regression. Skips when the client data isn't present.
+    /// The Stormwind mage portal's shimmer is transparency weight, 3 of its 4 tracks time-varying.
     #[test]
     fn mage_portal_bakes_a_time_varying_weight_loop() {
         let data = crate::wow_data_or_skip!();
@@ -217,7 +171,6 @@ mod tests {
             "the portal's shimmer batches carry time-varying weight loops"
         );
         let w = animated[0];
-        // The loop genuinely moves: two samples a quarter-period apart differ.
         let (a, b) = (w.sample(0.0), w.sample(w.period * 0.25));
         assert!(
             (a - b).abs() > 1e-3,
@@ -230,16 +183,9 @@ mod tests {
         );
     }
 
-    /// **B138 — Zul'Farrak's troll gate drew its own ruin on top of itself** (decision 1460).
-    /// `TanarisTrollGate.m2` is ONE file holding TWO gates: the intact one
-    /// (`TANARISTROLLGATE.BLP`) and its burnt twin (`TANARISTROLLGATEBURNT.BLP`), plus a tiki-mask
-    /// batch for each. Which pair draws is authored entirely in the M2Color alpha keys — `+1.0`
-    /// (`0x7fff`) for the copy this sequence shows, `−1.0` (`0x8001`) for the copy it hides — and a
-    /// negative alpha is what trips the reference's `A ≤ 0` batch cull. Decoded UNSIGNED, `0x8001`
-    /// reads `+1.00006`: both gates drew, interpenetrating everywhere, and the pair z-fought until
-    /// the door swung open and pulled them apart. So the carve is per sequence slot: **Closed (0)**
-    /// shows the intact gate and hides the burnt one, **Destroy (3)** does the reverse — and the two
-    /// tiki-mask batches, which share a texture, are never both visible. Skips without client data.
+    /// `TanarisTrollGate.m2` holds an intact gate and its burnt twin, each with a tiki mask. Its
+    /// `M2Color` alpha keys are `0x7fff` (+1.0) on the copy a sequence shows and `0x8001` (−1.0) on
+    /// the one it hides; only a signed decode lets the `A ≤ 0` cull hide it.
     #[test]
     fn troll_gate_never_draws_its_burnt_twin_at_the_same_time() {
         let data = crate::wow_data_or_skip!();
@@ -248,8 +194,7 @@ mod tests {
             .read_file("World\\Kalimdor\\Tanaris\\ActiveDoodads\\TrollGate\\TanarisTrollGate.m2")
             .expect("read TanarisTrollGate.m2");
         let subs = super::super::parse_m2_render_submeshes(&bytes, "", &[]).expect("parse");
-        // Sequence slots are FILE order (what the track ranges index): 0 Closed, 1 Open, 2 Opened,
-        // 3 Destroy, 4 Close.
+        // File slots: 0 Closed, 1 Open, 2 Opened, 3 Destroy, 4 Close.
         let (closed, destroy) = (Some(0), Some(3));
         let alpha_of = |tex: &str, seq| -> Vec<f32> {
             subs.iter()
@@ -293,8 +238,6 @@ mod tests {
                 .all(|&a| a > 0.0),
             "…and the burnt copy shows"
         );
-        // The mask twin is the same duplication one texture further in: two batches, one texture,
-        // and exactly one of them visible in any sequence.
         for seq in [closed, destroy] {
             let masks = alpha_of("BM_TROLL_TIKI03.BLP", seq);
             assert_eq!(
@@ -310,13 +253,8 @@ mod tests {
         }
     }
 
-    /// Battle Shout's ground model, straight off the real client data: six additive crescent
-    /// quads whose whole look is material animation — staggered colour-alpha pulses, dimming
-    /// weight constants (0.3/0.2/0.4), and RGB tracks cooling white→red over the 0.9 s clip.
-    /// Every batch must bake a time-varying colour-alpha loop AND a time-varying RGB loop, with
-    /// the static vertex tint skipped (the material channel owns it — a first-key vertex bake
-    /// would freeze four of six crescents white). Guards the RGB half of the bake chain end to
-    /// end. Skips when the client data isn't present.
+    /// Battle Shout's six additive crescents: staggered alpha pulses, dimming weight constants
+    /// (0.2 to 0.4), and RGB tracks cooling from white to red over the 0.9 s clip.
     #[test]
     fn battle_shout_base_bakes_alpha_and_rgb_loops() {
         let data = crate::wow_data_or_skip!();
@@ -349,7 +287,6 @@ mod tests {
                 rgb.period > 0.0 && rgb.keys.len() > 1,
                 "batch {i}: RGB varies"
             );
-            // The authored cool-down: red-dominant by mid-life on every crescent.
             let mid = rgb.sample(rgb.period * 0.5);
             assert!(
                 mid[0] > 0.6 && mid[1] < 0.1 && mid[2] < 0.1,
@@ -362,15 +299,8 @@ mod tests {
         }
     }
 
-    /// **B16 — the voidwalker's floating armour.** Straight off the real client data: skin batches
-    /// 0 and 1 (two 95-vertex shoulder pieces at z≈2.99/2.59) carry transparency weight **0** in
-    /// every ordinary sequence and 1 only in Death/131/132 — authored to appear on death. Their
-    /// twins at z≈1.46 are weight 1 throughout, so drawing all four reads as armour floating above
-    /// the body, which is exactly what the reporter saw.
-    ///
-    /// Pins the whole per-sequence chain: the ranges parse (benilla-m2), the per-slot bake, and the
-    /// combine. Before it, the bake read sequence 0's band once and the runtime had no way to ask a
-    /// different sequence — so the pair drew in every animation.
+    /// The voidwalker's skin batches 0 and 1, two shoulder pieces above the body, have weight 0 in
+    /// every ordinary sequence and 1 only in Death/131/132; their twins on the body always draw.
     #[test]
     fn voidwalker_hides_its_death_only_armour_in_every_other_sequence() {
         let data = crate::wow_data_or_skip!();
@@ -379,8 +309,8 @@ mod tests {
             .read_file("Creature\\VoidWalker\\VoidWalker.m2")
             .expect("read VoidWalker.m2");
         let subs = super::super::parse_m2_render_submeshes(&bytes, "", &[]).expect("parse");
-        // File slots, from `benilla-extract m2seq`: 0 = Stand (3333..6000 ms), 1 = Walk, 2 = Run,
-        // 5/6 = the Stand variations, 10 = Death (anim 1, 43333..46333 ms).
+        // File slots (`benilla-extract m2seq`): 0 Stand (3333..6000 ms), 1 Walk, 2 Run, 5/6 the
+        // Stand variations, 10 Death (anim 1, 43333..46333 ms).
         const STAND: usize = 0;
         const DEATH: usize = 10;
         for batch in [0, 1] {
@@ -388,7 +318,6 @@ mod tests {
                 .alpha_anim
                 .as_ref()
                 .unwrap_or_else(|| panic!("batch {batch} carries the weight track"));
-            // Hidden for the WHOLE Stand loop, not merely at t=0.
             for step in 0..16u16 {
                 let t = 2.667 * f32::from(step) / 16.0;
                 assert_eq!(
@@ -404,7 +333,6 @@ mod tests {
                     "batch {batch}, sequence {slot}"
                 );
             }
-            // Death brings it in — the authored reason the geometry exists at all.
             let peak = (0..32u16)
                 .map(|s| a.sample(Some(DEATH), 3.0 * f32::from(s) / 32.0, 0.0))
                 .fold(0.0f32, f32::max);
@@ -413,7 +341,6 @@ mod tests {
                 "batch {batch} appears during Death (peak {peak})"
             );
         }
-        // The body twins the reference DOES draw while standing stay drawn.
         for batch in [4, 5] {
             let drawn = subs[batch]
                 .alpha_anim
@@ -421,12 +348,9 @@ mod tests {
                 .is_none_or(|a| a.sample(Some(STAND), 0.5, 0.0) > 0.0);
             assert!(drawn, "batch {batch} draws in Stand");
         }
-        // **The nearest-key trap.** Batch 2 (the 271-vertex body) keys 1.0 at 3333 ms and 0.0 at
-        // 44200 ms on a STEP track, and the Stand *variations* (slots 5/6, 23333..29333 ms) key
-        // nothing — they sit nearer the 0. Clamping to the nearest authored key would hide the
-        // whole body in every variation, attack and emote; the reference's window says key 0, so
-        // it stays visible. This is the assertion that fails if the empty-band rule regresses to
-        // "nearest".
+        // Batch 2, the body, is a step track keyed 1.0 at 3333 ms and 0.0 at 44200 ms. The Stand
+        // variations (23333..29333 ms) key nothing and sit nearer the 0, but the reference's window
+        // says key 0, so the body stays visible.
         let body = subs[2].alpha_anim.as_ref();
         for slot in [5, 6, 7, 8, 9, 12] {
             let v = body.map_or(1.0, |a| a.sample(Some(slot), 0.5, 0.0));
@@ -437,16 +361,9 @@ mod tests {
         }
     }
 
-    /// **B20 — the banshee.** Same shape, different model: render batches **20–25** are weight 0
-    /// in every sequence a live banshee ever plays and only come in across the Death band — among
-    /// them a 57-vertex piece parked 1.18 yd to the SIDE of the body, which drawn permanently is
-    /// precisely the reported "parts floating in the air". Two of the six are further dimmed by a
-    /// constant-0.4 colour alpha, so they never reach full even on death.
-    ///
-    /// Indices are render batches (a billboard batch splits per bone, so this list runs longer than
-    /// the skin list — `benilla-extract m2alpha` prints both views). The test re-checks each one's
-    /// identity by vertex count so a change in batch ordering fails loudly instead of quietly
-    /// asserting about some other geometry.
+    /// The banshee's render batches 20 to 25 are weight 0 in every live sequence and come in across
+    /// Death. Render, not skin, indices (a billboard batch splits per bone; `benilla-extract
+    /// m2alpha` shows both), each re-checked by its vertex count.
     #[test]
     fn banshee_hides_its_death_only_batches() {
         let data = crate::wow_data_or_skip!();
@@ -456,10 +373,9 @@ mod tests {
             .expect("read Banshee.m2");
         let subs = super::super::parse_m2_render_submeshes(&bytes, "", &[]).expect("parse");
         assert_eq!(subs.len(), 26, "the banshee's render batch list");
-        // Slots from `m2seq`: 0 = Stand (10000..13333 ms), 3 = Walk, 4 = Run, 12 = Death.
+        // File slots (`m2seq`): 0 Stand (10000..13333 ms), 3 Walk, 4 Run, 12 Death.
         const LIVE: [usize; 12] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
         const DEATH: usize = 12;
-        // (render batch, vertex count) — the identity re-check.
         for (batch, verts) in [(20, 57), (21, 60), (22, 4), (23, 4), (24, 4), (25, 4)] {
             assert_eq!(subs[batch].positions.len(), verts, "batch {batch} identity");
             let a = subs[batch]
@@ -481,10 +397,8 @@ mod tests {
                 .fold(0.0f32, f32::max);
             assert!(peak > 0.3, "batch {batch} appears on death (peak {peak})");
         }
-        // Everything the reference DOES draw on a live banshee stays drawn — the fix must not turn
-        // into a wholesale hide. Batch 8 is the one authored exception among these: the
-        // `BITCHFACE5.BLP` face, weight 0 while standing and pulsed to 0.6 by the attack/emote
-        // sequences — the scream face, not a bug.
+        // Everything else draws while standing but batch 8, the `BITCHFACE5.BLP` scream face:
+        // weight 0 standing, pulsed to 0.6 by the attack and emote sequences.
         for (i, sub) in subs.iter().enumerate().take(20).filter(|(i, _)| *i != 8) {
             let v = sub
                 .alpha_anim
@@ -519,9 +433,7 @@ mod tests {
         }
     }
 
-    /// The same track with explicit per-sequence key windows — the array the reference's search
-    /// indexes by the playing sequence's file slot, and the only thing that says what a band with
-    /// no keys of its own holds.
+    /// The same track with per-sequence key windows, which the reference indexes by file slot.
     fn ranged(interp: u16, keys: &[(u32, f32)], ranges: &[(u32, u32)]) -> M2ScalarTrack {
         M2ScalarTrack {
             interp,
@@ -531,8 +443,7 @@ mod tests {
         }
     }
 
-    /// Bake against a **looping** sequence file slot `index` with band `band`. The clamped clock
-    /// (the one-shot band that must hold its tail) is [`a_clamped_band_holds_its_faded_tail`].
+    /// Bake against looping file slot `index` over `band`.
     fn bake_at(t: &M2ScalarTrack, index: usize, band: (u32, u32)) -> Option<ScalarAnim> {
         bake_scalar_anim(
             t,
@@ -545,7 +456,7 @@ mod tests {
         )
     }
 
-    /// Bake against a **clamped** (one-shot) sequence file slot — the Death-band shape.
+    /// Bake against a one-shot file slot, the Death-band shape.
     fn bake_at_clamped(t: &M2ScalarTrack, index: usize, band: (u32, u32)) -> Option<ScalarAnim> {
         bake_scalar_anim(
             t,
@@ -558,9 +469,6 @@ mod tests {
         )
     }
 
-    /// The bake's contribution gate: keyless and constant-1 tracks vanish; a dimming constant is
-    /// kept as period-0 (the combine the static vertex bake never applied); constant-0 is the
-    /// static cull's job, not a runtime anim.
     #[test]
     fn bake_keeps_only_what_the_static_path_cannot_do() {
         assert_eq!(bake_scalar_anim(&track(0xffff, 1, &[]), &[], None), None);
@@ -577,8 +485,6 @@ mod tests {
         assert_eq!(dim.sample(123.0), 0.4);
     }
 
-    /// A gseq-tagged track wraps the global-sequence duration — the fire-flicker shape: value
-    /// pulses over a 1.5 s loop regardless of any playing sequence.
     #[test]
     fn gseq_track_wraps_the_table_duration() {
         let a = bake_scalar_anim(
@@ -592,11 +498,6 @@ mod tests {
         assert!((a.sample(1.5 + 0.375) - 0.6).abs() < 1e-4); // wraps
     }
 
-    /// The clock router (decision 0855): a gseq loop reads the SHARED world clock — the
-    /// reference's free-running Phase B cursor, no per-instance arming — pre-wrapped in f64 so a
-    /// long-uptime `shared_now` keeps precision; a band loop keeps the host's clip time. Sampling
-    /// a gseq loop on a spawn-anchored clock is the Arcane Intellect sparkle bug: every cast's
-    /// twinkles land at phase 0.
     #[test]
     fn gseq_loops_read_the_shared_clock() {
         let g = bake_scalar_anim(
@@ -606,7 +507,7 @@ mod tests {
         )
         .unwrap();
         assert!(g.gseq);
-        // band_t (first arg) is ignored; the shared clock decides the phase (mid-ramp → 0.6).
+        // band_t is ignored; the gseq cursor decides the phase (mid-ramp, 0.6).
         assert!((g.sample(g.clock(0.0, 1500.375)) - 0.6).abs() < 1e-3);
         let b = ranged(1, &[(1000, 0.0), (1500, 1.0)], &[(0, 1)]);
         let b = bake_at(&b, 0, (1000, 2000)).unwrap();
@@ -618,8 +519,6 @@ mod tests {
         );
     }
 
-    /// A sequence-timeline track keeps only the first sequence's band, rebased to seconds — keys
-    /// belonging to other sequences (outside the band) don't bleed in.
     #[test]
     fn sequence_track_bakes_one_band_at_a_time() {
         // Keys 0..2; sequence 0's window is keys 0-1, sequence 1's is keys 1-2.
@@ -631,19 +530,16 @@ mod tests {
         let a = bake_at(&t, 0, (1000, 2000)).unwrap();
         assert_eq!(a.period, 1.0);
         assert!((a.sample(0.25) - 0.5).abs() < 1e-6);
-        // Past the band's last key the value keeps ramping toward the NEXT key — the reference
-        // takes `k1 = k0 + 1` bounded only by the total key count, never by the window's `hi`
-        // (wow-re `eval.md` FN1 §4/§5), so key 2 at 5000 ms is a live lerp endpoint here even
-        // though it belongs to a later sequence. It never wrap-lerps back to key 0.
+        // Past the band's last key the value ramps on toward key 2 of a later sequence: the
+        // reference bounds `k1 = k0 + 1` by the key count, not the window's `hi` (`0x713d50`).
         let expect = 1.0 + (0.3 - 1.0) * (1900.0 - 1500.0) / (5000.0 - 1500.0);
         assert!(
             (a.sample(0.9) - expect).abs() < 1e-4,
             "got {} want {expect}",
             a.sample(0.9)
         );
-        // A different sequence over the same track reads a different window entirely: band 1 opens
-        // mid-segment (the 1.0→0.3 ramp is 5/7 of the way through at 4000 ms) and closes on key 2.
-        // Sampled just under the period — at exactly `period` the loop has already wrapped.
+        // Band 1 opens mid-segment (5/7 along the 1.0 to 0.3 ramp at 4000 ms) and closes on key 2,
+        // sampled just under the period, where the loop has not yet wrapped.
         let b = bake_at(&t, 1, (4000, 5000)).unwrap();
         assert!((b.sample(0.0) - 0.5).abs() < 1e-4, "got {}", b.sample(0.0));
         assert!(
@@ -653,10 +549,6 @@ mod tests {
         );
     }
 
-    /// **The per-sequence bake, and the bug it fixes.** One track, two bands: a batch keyed 0 in
-    /// the first sequence and 1 in the second (the voidwalker armour shape — hidden while standing,
-    /// shown on death). Baking band 0 and calling it the model's answer freezes the batch hidden
-    /// in every animation; each band must bake its own value.
     #[test]
     fn each_sequence_bakes_its_own_band() {
         let t = ranged(
@@ -668,41 +560,33 @@ mod tests {
         assert_eq!(stand.sample(0.0), 0.0, "hidden for the whole first band");
         assert_eq!(stand.sample(0.9), 0.0);
         let death = bake_at(&t, 1, (4000, 5000));
-        // Constant 1 in that band is the identity — nothing to animate, the batch just draws.
         assert_eq!(death, None, "the second band is a plain visible batch");
     }
 
-    /// A band that keys nothing holds `keys[ranges[slot].lo]` — the reference's collapsed key
-    /// window (`lo >= hi` ⇒ the degenerate `{lo, lo, 0}` result, wow-re `eval.md` FN1). Including a
-    /// held **0**, which must keep hiding the batch every frame of that sequence: the static cull
-    /// never saw it, because the full track isn't constant.
+    /// A band that keys nothing holds `keys[ranges[slot].lo]`, the reference's collapsed window
+    /// (`lo >= hi`, `0x713d50`).
     #[test]
     fn band_empty_track_holds_its_bracket_key() {
-        // Slot 1's window has collapsed onto key 0 (value 0) — the band is hidden.
+        // Slot 1's window has collapsed onto key 0, value 0.
         let t = ranged(1, &[(100, 0.0), (5000, 1.0)], &[(0, 1), (0, 0)]);
         let a = bake_at(&t, 1, (1000, 2000)).unwrap();
         assert_eq!(a.period, 0.0);
         assert_eq!(a.sample(42.0), 0.0);
-        // A collapsed window onto a 1 contributes nothing — the batch simply draws.
         let one = ranged(1, &[(100, 1.0), (5000, 0.3)], &[(0, 1), (0, 0)]);
         assert_eq!(bake_at(&one, 1, (1000, 2000)), None);
     }
 
-    /// The bracket-key rule is NOT "the nearest authored key": a **step** track whose band sits
-    /// between a 1 and a later 0 holds the 1, because the window's low index is the search result
-    /// for every time in the band. Nearest-key would pick the 0 and hide a batch the reference
-    /// draws — measured on `VoidWalker.m2`, where it hides the whole 271-vertex body in every
-    /// Stand variation, attack and emote.
+    /// A step track whose band sits between a 1 and a later 0 holds the 1: the window's low index
+    /// is the search result for every time in the band.
     #[test]
     fn empty_band_uses_the_window_low_key_not_the_nearest() {
         let t = ranged(0, &[(3333, 1.0), (44200, 0.0)], &[(0, 1), (0, 1)]);
-        // Band 23333..26000 keys nothing and sits NEARER the 0 — but the window says key 0.
+        // Band 23333..26000 keys nothing and sits nearer the 0.
         let a = bake_at(&t, 1, (23333, 26000));
         assert_eq!(a, None, "the batch stays visible (constant 1 = identity)");
     }
 
-    /// No ranges array at all is the reference's `[track+4] == 0` fallback: the window is the whole
-    /// key list, so the band samples the track's ordinary value at its own times.
+    /// No ranges array is the reference's `[track+4] == 0` fallback: the whole key list.
     #[test]
     fn missing_ranges_search_the_whole_key_list() {
         let t = track(0xffff, 0, &[(0, 1.0), (10_000, 0.0)]);
@@ -710,19 +594,8 @@ mod tests {
         assert_eq!(a.sample(0.5), 0.0, "past the last key: hold it");
     }
 
-    /// **The Death-band clock** — the AirElemental shape, synthesized. A one-shot (clamped) band
-    /// whose transparency steps `1 → 0` partway through: the body dissolves, and the clock then
-    /// PARKS at (or just past) the band end for the whole life of the corpse. The baked loop must
-    /// hold that faded tail there.
-    ///
-    /// It used to wrap. Bevy's `ActiveAnimation::update` returns early once a
-    /// `RepeatAnimation::Never` clip completes — *before* its own modulo — so a finished Death clip
-    /// parks at `seek_time >= clip_duration == period`, and `t mod period` aliased that straight
-    /// back onto the band's opening value: one frame after the elemental had fully dissolved, its
-    /// whole body snapped back to full opacity and stayed there, frozen in mid-air, until the
-    /// server destroyed the corpse. 74 models author an aliasing Death band (elementals, voidwalker,
-    /// shade, ghost, wisp, banshee, lich, Ragnaros, Thunderaan, the totems…), 327 an aliasing
-    /// one-shot band of any kind.
+    /// A one-shot band whose weight steps 1 to 0: the clock parks at or just past the band end for
+    /// the corpse's life, and the loop must hold the faded tail there.
     #[test]
     fn a_clamped_band_holds_its_faded_tail() {
         // Band 43333..46333 (3 s), the elemental's Death; the body's weight steps to 0 at 867 ms.
@@ -744,8 +617,6 @@ mod tests {
         assert_eq!(a.sample(600.0), 0.0, "still gone a corpse-decay later");
     }
 
-    /// The same band authored as a LOOPING sequence keeps the modulo wrap — the kernel re-fires a
-    /// windowed track every pass, which is what makes a cyclic flicker cycle.
     #[test]
     fn a_looping_band_still_wraps() {
         let t = ranged(0, &[(3333, 1.0), (44200, 0.0)], &[(0, 1)]);
@@ -755,9 +626,7 @@ mod tests {
         assert_eq!(a.sample(3.0), 1.0, "second pass: the window re-fires");
     }
 
-    /// The real `AirElemental.m2`, straight off the client data — the model the bug was reported
-    /// on. Its Death band (file slot 10) fades every body batch to 0, and the parked clock must
-    /// still read 0 there. Skips when the client data isn't present.
+    /// `AirElemental.m2`'s Death band fades the body to 0, and the parked clock must still read 0.
     #[test]
     fn air_elemental_death_leaves_no_opaque_body() {
         let data = crate::wow_data_or_skip!();
@@ -766,7 +635,7 @@ mod tests {
             .read_file("Creature\\AirElemental\\AirElemental.m2")
             .expect("read AirElemental.m2");
         let subs = super::super::parse_m2_render_submeshes(&bytes, "", &[]).expect("parse");
-        // Slot 10 = anim id 1 (Death), clamped, band 43333..46333 → period exactly 3.0 s.
+        // Slot 10 is anim id 1 (Death), one-shot, band 43333..46333: a period of exactly 3.0 s.
         const DEATH: usize = 10;
         let faded: Vec<usize> = subs
             .iter()
@@ -795,7 +664,6 @@ mod tests {
         }
     }
 
-    /// Step interpolation holds each key until the next (the kernel's `interp == 0` leg).
     #[test]
     fn step_tracks_hold_between_keys() {
         let a = bake_scalar_anim(&track(0, 0, &[(0, 0.2), (1000, 1.0)]), &[2000], None).unwrap();
@@ -814,8 +682,6 @@ mod tests {
         })
     }
 
-    /// The combined pair multiplies its two factors — the verified combine's track half — and an
-    /// all-identity model bakes to no anim at all.
     #[test]
     fn alpha_anim_multiplies_color_and_weight() {
         let both = AlphaAnim::new(vec![AlphaSeq {
@@ -827,9 +693,6 @@ mod tests {
         assert_eq!(AlphaAnim::new(vec![AlphaSeq::default()]), None);
     }
 
-    /// Sequence addressing: each slot samples its own pair, an unknown/out-of-range slot degrades
-    /// to slot 0 (the doodad lane's one-time arm), and `ever_hides` reports whether ANY sequence
-    /// can cull the batch.
     #[test]
     fn alpha_anim_addresses_by_sequence_slot() {
         let a = AlphaAnim::new(vec![
diff --git a/crates/benilla-formats/src/models/mod.rs b/crates/benilla-formats/src/models/mod.rs
index 5c6d327a..636b1b3c 100644
--- a/crates/benilla-formats/src/models/mod.rs
+++ b/crates/benilla-formats/src/models/mod.rs
@@ -1,16 +1,5 @@
-//! Model loading — the shared `models` module face (decision 0021).
-//!
-//! Parsing is delegated to `benilla-m2` (M2) / `benilla-wmo` (WMO). Both produce a list of
-//! [`RenderSubmesh`] — one per render batch, each with its own (remapped) vertices, texture, and blend
-//! mode. M2 models and WMO groups are split into batches that each have their own material (a tree =
-//! opaque trunk + alpha leaves; a building = many wall/floor/roof textures), so they render separately
-//! or the wrong texture/blend lands on parts of the model. Vertices are model space (Z-up ≈ WoW axes).
-//!
-//! Split by concern: this file keeps the top-level dispatch ([`load_object_model`]) + the byte/remap
-//! helpers the submodules share; [`types`] holds the shared render types ([`RenderSubmesh`],
-//! [`ModelBlend`], billboard/light data), [`m2_batches`] the M2 render-batch assembly loop, [`bounds`]
-//! the authored-bounds/selection-ring reads, [`anim`] skeleton + animation, [`wmo`] the WMO parse, and
-//! [`collision`] the collision hulls.
+//! Model loading over `benilla-m2` and `benilla-wmo`: a model becomes one [`RenderSubmesh`] per
+//! render batch, each with its own vertices, texture and blend, in model space (Z up, WoW axes).
 
 use std::collections::HashMap;
 
@@ -44,11 +33,8 @@ pub use tex_anim::{rotation_2x2, uv_transform, UvAnim, UvRotAnim};
 pub use types::*;
 pub use wmo::*;
 
-/// Build a submesh from a stream of global vertex indices, remapping to a local vertex subset so
-/// each batch is a compact standalone mesh. `vertex` fetches `(position, normal, uv, colour)` for a
-/// global index. Also returns, parallel to the submesh's local vertices, each one's **global** index
-/// — so the M2 path can fill the per-vertex skin binding ([`RenderSubmesh::joints`]) afterward (the
-/// skin lives on the M2 vertex, not in the geometry closure, and WMO has none).
+/// Build a compact submesh from global vertex indices. Also returns each local vertex's global
+/// index, from which the M2 path fills [`RenderSubmesh::joints`].
 fn remap_submesh(
     global_indices: impl Iterator<Item = u32>,
     vertex: impl Fn(u32) -> ([f32; 3], [f32; 3], [f32; 2], [f32; 4]),
@@ -81,45 +67,45 @@ fn remap_submesh(
             uvs,
             indices,
             texture,
+            // The per-batch fields start at their defaults; the M2 and WMO paths set their own.
             skin_slot: None,
-            geoset_id: 0, // set by the caller per batch (the M2 path; WMO leaves it 0)
-            char_slot: None, // set by the caller per batch (M2 only)
-            icon_slot: false, // set by the caller per batch (M2 texture type 14)
+            geoset_id: 0,
+            char_slot: None,
+            icon_slot: false,
             blend,
-            // Repeat is the pre-0763 behaviour and stays WMO's; the M2 batch loop overrides both
-            // from the texture record's own flags.
+            // WMO keeps repeat; the M2 batch loop sets both from the texture record's flags.
             wrap_x: true,
             wrap_y: true,
             two_sided,
             vertex_colors,
-            joints: Vec::new(), // M2 path fills these from `globals`; WMO leaves them empty
-            weights: Vec::new(), //
+            joints: Vec::new(),
+            weights: Vec::new(),
             interior,
             emissive,
-            sidn: None, // set by the WMO path from MOMT SIDN (0x10) + its authored colour
-            window: false, // set by the WMO path from MOMT WINDOW (0x20)
-            additive: false, // set by the M2 path from the blend mode (3/4)
-            no_depth_write: false, // set by the M2 path from render flag 0x10 (WMO keeps standard depth)
-            no_depth_test: false,  // set by the M2 path from render flag 0x08
-            fog_policy: FogPolicy::Scene, // refined by the M2 path (flag 0x02 + the blend table); WMO batches fog with the scene
-            billboard: None,              // set by the M2 path after detecting the batch's bone
-            welded_billboard: false,      // set by the M2 path from the separability gate (0839)
-            alpha_anim: None, // set by the M2 path from the batch's colour/weight tracks
-            uv_anim: None,    // set by the M2 path from the batch's texture transform
-            uv_seq: None,     // …and its per-sequence set, when the slots disagree (1408)
+            sidn: None,
+            window: false,
+            additive: false,
+            no_depth_write: false,
+            no_depth_test: false,
+            fog_policy: FogPolicy::Scene,
+            billboard: None,
+            welded_billboard: false,
+            alpha_anim: None,
+            uv_anim: None,
+            uv_seq: None,
             uv_rot_seq: None,
             uv_scale_seq: None,
-            rgb_anim: None,  // set by the M2 path from the batch's colour RGB track
-            rgb_seq: None,   // …ditto (1408)
-            wmo_batch: None, // set by the WMO path from the MOGP batch-section counts
-            env_map: false,  // set by the M2 path from texture_unit_lookup[texCoordSet] > 2
-            section: None,   // set by the M2 path from the batch's skin_section_index
+            rgb_anim: None,
+            rgb_seq: None,
+            wmo_batch: None,
+            env_map: false,
+            section: None,
         },
         globals,
     )
 }
 
-/// Normalize a model path for the chain: lowercase (case-insensitive lookup), `.mdx`/`.mdl` → `.m2`.
+/// Normalize a model path for the chain: lowercase, with `.mdx`/`.mdl` as `.m2`.
 pub(crate) fn model_path(raw: &str) -> String {
     let lower = raw.to_ascii_lowercase();
     match lower
@@ -131,9 +117,8 @@ pub(crate) fn model_path(raw: &str) -> String {
     }
 }
 
-/// Panicking little-endian readers, kept **only** for raw offset walks that predate the decision-0064
-/// migration to `benilla_bytes::ByteExt` — [`anim`]'s bone/track walk, [`anim_summary`]'s header
-/// reads, and [`m2_batches`]'s sequence-0 time-band lookup all still import these three.
+/// Panicking little-endian reads at a byte offset, for the raw walks not on
+/// `benilla_bytes::ByteExt`.
 pub(crate) fn le_u16(b: &[u8], o: usize) -> u16 {
     u16::from_le_bytes([b[o], b[o + 1]])
 }
@@ -144,9 +129,7 @@ pub(crate) fn le_f32(b: &[u8], o: usize) -> f32 {
     f32::from_le_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]])
 }
 
-/// Load a world model by path, dispatching on extension: `.wmo` → [`load_wmo`], otherwise
-/// (`.mdx`/`.mdl`/`.m2`) → [`load_m2_mesh`]. Used for GameObject display models, which are mostly M2
-/// with a few WMO.
+/// Load a GameObject display model by path: a `.wmo` through [`load_wmo`], anything else as an M2.
 pub fn load_object_model(chain: &mut Chain, raw_path: &str) -> Result<Vec<RenderSubmesh>> {
     if raw_path.to_ascii_lowercase().ends_with(".wmo") {
         load_wmo(chain, raw_path)
diff --git a/crates/benilla-formats/src/models/records.rs b/crates/benilla-formats/src/models/records.rs
index 36e55930..47bf857c 100644
--- a/crates/benilla-formats/src/models/records.rs
+++ b/crates/benilla-formats/src/models/records.rs
@@ -1,24 +1,13 @@
-//! Raw **authored-record reads** straight off the model bytes — the cosmetic MD20 arrays
-//! `benilla-m2` deliberately skips (it parses only the render path) plus the WMO root's MOLT
-//! lights: M2 dynamic lights (decision 0016), the WMO fixture lights, and the model's authored
-//! **portrait camera** (the unit-frame bake's framing source). Each is a small header-offset walk
-//! over the vanilla record shape, byte-verified in wow-5875-re; all positions stay raw WoW model
-//! space (the render boundary bakes to Bevy space).
+//! Authored records off the raw model bytes, in raw WoW model space: M2 lights (which `benilla-m2`
+//! does not read), the WMO root's MOLT lights, and the M2 camera table.
 
 use benilla_bytes::ByteExt;
 
-/// An M2 **light** (MD20 lights array, byte-verified against wow-5875-re
-/// `models/scratch/m2-dynamic-lights.md`). A `light_type == 1` (point) light on a placed prop
-/// (campfire/torch/brazier/candle/forge) is committed by the real client as a hardware `GL_LIGHT` with
-/// the fixed attenuation `1 / (0.7·d + 0.03·d²)` — constant term 0, so intensity peaks hard at the
-/// source: the tight interior "hot-spot" (decision 0016). It lights every lit surface — terrain, M2
-/// doodads/NPCs, and WMO walls/floors (decision 0273; the committed light is diffuse-only, its ambient
-/// and specular are zero *on world props* — the glue background scenes DO author their ambient
-/// through one dedicated ambient-only light, so both track pairs are parsed). `position` is model
-/// space (WoW axes), relative to `bone` (`-1` = model origin); the spawn site applies the prop
-/// transform. Colour/intensity are each track's representative (first) value — per-frame flicker is
-/// a later refinement; the authored attenuation start/end are parsed for a cull hint, but the GL
-/// curve is fixed and ignores them.
+/// An M2 light (the MD20 lights array, loaded by `0x70ebd0`), `position` relative to `bone` (`-1`
+/// for the origin). The reference commits a point light on a placed prop as a hardware `GL_LIGHT`
+/// with the fixed attenuation `1 / (0.7·d + 0.03·d²)`, diffuse only; the glue scenes light their
+/// ambient through an ambient-only light, so both pairs are read. Colour and intensity are each
+/// track's first value, where the reference animates them; the attenuation range is a cull hint.
 #[derive(Debug, Clone, Copy)]
 pub struct M2Light {
     pub light_type: u16,
@@ -30,45 +19,30 @@ pub struct M2Light {
     pub diffuse_intensity: f32,
     pub attenuation_start: f32,
     pub attenuation_end: f32,
-    /// The light **bone's local +Z axis in model space** at the track origin (first rotation keys
-    /// composed up the parent chain) — a DIRECTIONAL light's direction basis. The byte law (wow-re
-    /// `glue/scratch/glue-model-lighting.md §3`, correcting `m2-dynamic-lights.md §2`): the gather
-    /// reads **row 2 of the light bone's pose matrix** — never the def position, which is the
-    /// POINT branch's input only — and the on-surface **to-light** vector nets to
-    /// `normalize(Bz·BM_rot)`. `[0,0,1]` for a boneless/rotationless chain (identity pose).
+    /// The light bone's +Z axis in model space at the track origin, a directional light's basis:
+    /// `0x718a76` reads row 2 of the bone's pose matrix, never the def position.
     pub bone_z: [f32; 3],
-    /// The **ON-gating** verdict (wow-re `m2-dynamic-lights.md` §9.4, VERIFIED mechanism): both
-    /// runtime gate bytes load as `1`, and the per-frame animate loop rewrites the visibility byte
-    /// **only when the visibility track has keys** (`716413`: zero keys ⇒ sample skipped ⇒ the load
-    /// default 1 stands). So a light is dark iff its asset ships a first visibility key of literally
-    /// `0`. `true` = exactly that shape (never cast it); `false` = keyless, or a nonzero first key.
-    /// The track's values are **bytes** (`71646d: +0xec = visibilityValue[k0]`), not floats.
+    /// Both runtime gate bytes load as 1 and the animate loop rewrites the visibility byte only
+    /// when the track has keys (`0x716413`), so a light is dark only when its first visibility key
+    /// is 0. The values are bytes (`0x71646d`: `+0xec = visibilityValue[k0]`).
     pub visibility_off: bool,
 }
 
 impl M2Light {
-    /// `type == 1` — an omnidirectional point light (the hot-spot caster). Type 0 (directional) feeds the
-    /// ambient accumulator, not a discrete GL light (decision 0016 / wow-5875-re m2-dynamic-lights).
+    /// A point light; type 0 feeds the ambient accumulator, not a GL light (`0x71bc70`).
     pub fn is_point(&self) -> bool {
         self.light_type == 1
     }
 
-    /// The spawn gate: a **point** light whose visibility track doesn't hold it dark (§9.4). Every
-    /// site that turns authored M2 lights into scene lights filters on this.
+    /// The spawn gate: a point light its visibility track does not hold dark.
     pub fn casts(&self) -> bool {
         self.is_point() && !self.visibility_off
     }
 }
 
-/// A WMO **MOLT** light (root chunk; byte-verified against real assets — Goldshire inn/forge, Northshire
-/// Abbey carry 10/3/42 of them). The artists place omni (`light_type == 0`) lights at the interior
-/// fixtures (fireplaces, forge, candles, chandeliers); they are warm-coloured, and each wall fixture
-/// doodad gets a companion MOLT at its flames (NSabbey: one per candelabra, ~3.4 yd above the MODD
-/// origin). At runtime 1.12 commits them into the scene dynamic-light DB every frame for every visible
-/// WMO (wow-re `wmo-molt-runtime`), lighting terrain, doodads/NPCs, and the building's own surfaces
-/// over their baked MOCV (decision 0273 — confirmed live in the reference GL trace: an NSabbey batch
-/// drew under `colour × intensity` point lights at the fixed 0/0.7/0.03 falloff). `position` is WMO
-/// model space (WoW axes). SMOLight stride 0x30.
+/// A WMO MOLT light (`SMOLight`, stride `0x30`), in WMO model space. The 1.12 client commits them
+/// to the scene's dynamic lights every frame for every visible WMO (`0x695c00`, `0x71b650`), as
+/// `colour × intensity` point lights at the fixed 0/0.7/0.03 falloff over the baked MOCV.
 #[derive(Debug, Clone, Copy)]
 pub struct WmoLight {
     pub light_type: u8,
@@ -81,16 +55,13 @@ pub struct WmoLight {
 }
 
 impl WmoLight {
-    /// `type == 0` — an omnidirectional (point) MOLT light: the interior fixture lights. (1 = spot,
-    /// 2 = directional, 3 = ambient — none seen in the vanilla human interiors audited.)
+    /// An omni light, the interior fixtures' type (1 is spot, 2 directional, 3 ambient).
     pub fn is_omni(&self) -> bool {
         self.light_type == 0
     }
 }
 
-/// First value of a vanilla 28-byte M2Track (values `count@0x14`, `ofs@0x18`) as `f32` / `C3Vector`.
-/// The representative (static-or-first-key) value — enough to place + colour a light; per-frame track
-/// evaluation (the flame flicker) is layered on later. `None` if the track is empty / out of bounds.
+/// The first value of a 28-byte M2Track (values `count@0x14`, `ofs@0x18`).
 fn track_first_f32(bytes: &[u8], track: usize) -> Option<f32> {
     let nval = bytes.u32_at(track + 0x14)? as usize;
     let ofs = bytes.u32_at(track + 0x18)? as usize;
@@ -99,9 +70,6 @@ fn track_first_f32(bytes: &[u8], track: usize) -> Option<f32> {
     }
     bytes.f32_at(ofs)
 }
-/// First value of a vanilla 28-byte M2Track whose values are **bytes** — the light visibility track
-/// ([`M2Light::visibility_off`]). `None` for a keyless track (which the animate loop leaves at the
-/// load default, i.e. ON).
 fn track_first_u8(bytes: &[u8], track: usize) -> Option<u8> {
     let nval = bytes.u32_at(track + 0x14)? as usize;
     let ofs = bytes.u32_at(track + 0x18)? as usize;
@@ -133,7 +101,7 @@ fn quat_mul(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
     ]
 }
 
-/// `q · (0,0,1) · q⁻¹` — the +Z axis rotated by `q`, expanded closed-form.
+/// `q · (0,0,1) · q⁻¹`, the +Z axis rotated by `q`, in closed form.
 fn quat_rotate_z(q: [f32; 4]) -> [f32; 3] {
     let [x, y, z, w] = q;
     [
@@ -143,8 +111,6 @@ fn quat_rotate_z(q: [f32; 4]) -> [f32; 3] {
     ]
 }
 
-/// First key of a vanilla 28-byte M2Track whose values are `[x,y,z,w]` f32 quaternions (the v256
-/// bone-rotation key shape). `None` if the track is empty / out of bounds.
 fn track_first_quat(bytes: &[u8], track: usize) -> Option<[f32; 4]> {
     let nval = bytes.u32_at(track + 0x14)? as usize;
     let ofs = bytes.u32_at(track + 0x18)? as usize;
@@ -159,18 +125,15 @@ fn track_first_quat(bytes: &[u8], track: usize) -> Option<[f32; 4]> {
     ])
 }
 
-/// A bone's **model-space +Z axis at the track origin**: first rotation keys composed up the
-/// parent chain (`global = parent ∘ local`), applied to `(0,0,1)`. Vanilla bone table
-/// `count@0x34`/`ofs@0x38`, record stride `0x6c`: flags `u32@4` (bit `0x04` = keep the model
-/// root's orientation — stop inheriting), parent `i16@8`, rotation M2Track `@0x28`. Rotationless
-/// chains yield `[0,0,1]` (the identity pose — vanilla's rest skeleton is pure translations).
-/// Sequence-0 *animation* of a light bone's rotation is not tracked (no UI_* scene authors one).
+/// A bone's model-space +Z at the track origin, its first rotation keys composed up the parent
+/// chain. Bone table `count@0x34`/`ofs@0x38`, stride `0x6c`: flags `u32@4` (`0x04` keeps the
+/// root's orientation), parent `i16@8`, rotation `@0x28`. Rotation animation is not applied.
 fn bone_z_axis(bytes: &[u8], bone: i16) -> [f32; 3] {
     let (Some(count), Some(ofs)) = (bytes.u32_at(0x34), bytes.u32_at(0x38)) else {
         return [0.0, 0.0, 1.0];
     };
     let (count, ofs) = (count as usize, ofs as usize);
-    // Collect local rotations leaf→root, cycle-guarded by the bone count.
+    // Local rotations leaf to root, bounded by the bone count.
     let mut chain: Vec<[f32; 4]> = Vec::new();
     let mut idx = bone;
     for _ in 0..=count {
@@ -194,13 +157,10 @@ fn bone_z_axis(bytes: &[u8], bone: i16) -> [f32; 3] {
     quat_rotate_z(q)
 }
 
-/// One M2 light record at a bounds-checked `rec` (the loop below already proved `rec + 0xd4 <=
-/// bytes.len()`), so these reads can only fail on a header/offset bug — treated as "stop", not panic.
-/// Offsets byte-verified in wow-5875-re `models/scratch/m2-dynamic-lights.md §1`: `type@0`, `bone@2`,
-/// `position@4`, then 7 × `0x1c` M2Tracks — ambient colour/intensity `@0x10`/`@0x2c`, diffuse
-/// colour/intensity `@0x48`/`@0x64`, attenuation start/end `@0x80`/`@0x9c`, visibility `@0xb8`. We
-/// take diffuse (colour+intensity) + attenuation + the visibility gate ([`M2Light::visibility_off`],
-/// byte-valued); ambient is a later refinement.
+/// One M2 light record at a bounds-checked `rec`, as the reference reads it (`0x718960`,
+/// `0x714260`): `type@0`, `bone@2`, `position@4`, then seven `0x1c` M2Tracks: ambient colour and
+/// intensity `@0x10`/`@0x2c`, diffuse `@0x48`/`@0x64`, attenuation `@0x80`/`@0x9c`, visibility
+/// `@0xb8`.
 fn read_m2_light(bytes: &[u8], rec: usize) -> Option<M2Light> {
     let bone = bytes.u16_at(rec + 0x02)? as i16;
     Some(M2Light {
@@ -222,10 +182,7 @@ fn read_m2_light(bytes: &[u8], rec: usize) -> Option<M2Light> {
     })
 }
 
-/// Parse the M2 **lights** array straight from the raw bytes (MD20 `count@0x11c`, `ofs@0x120`, record
-/// stride `0xd4`, see [`read_m2_light`]). `benilla-m2` deliberately parses only the render path and
-/// skips the cosmetic chunks (lights/particles/tex-anims), so we read the vanilla light record here
-/// (decision 0016).
+/// The M2 lights array (MD20 `count@0x11c`, `ofs@0x120`, stride `0xd4`).
 pub fn parse_m2_lights(bytes: &[u8]) -> Vec<M2Light> {
     let (Some(count), Some(ofs)) = (bytes.u32_at(0x11c), bytes.u32_at(0x120)) else {
         return Vec::new();
@@ -239,59 +196,39 @@ pub fn parse_m2_lights(bytes: &[u8]) -> Vec<M2Light> {
         };
         match read_m2_light(bytes, rec) {
             Some(light) => out.push(light),
-            None => break, // unreachable given the guard above; defensive, not a panic
+            None => break, // unreachable after the guard above
         }
     }
     out
 }
 
-/// The model's authored **portrait camera** — the MD20 camera the real 1.12 client renders every
-/// unit-frame portrait through (VERIFIED, wow-re `system/ui/scratch/portrait-render.md` §4,
-/// corrected verdict `aa186e79`): the bake at `0x524f60` selects camera `cameraLookup[0]` and
-/// builds `lookAt(position, target, up-from-roll)` + the gxumath *diagonal-FOV* perspective
-/// (`0x5c3cc0`, half-angle `(fov/2)/√(aspect²+1)`) at the portrait path's fixed `aspect = 4/3` —
-/// net vertical half-angle `0.3·fov` with a 3:4 anamorphic squeeze. The framing is per-model
-/// *authored data* — each artist calibrated camera 0 to their own geometry, which is why every
-/// ref portrait (human, wolf, rabbit) crops identically tight. No engine-side yaw or
-/// normalization exists on top of it. All fields raw WoW model space / radians.
+/// The model's portrait camera, which the 1.12 client renders every unit-frame portrait through:
+/// the bake at `0x524f60` takes camera `cameraLookup[0]` and builds `lookAt(position, target,
+/// up-from-roll)` with the diagonal-FOV perspective (`0x5c3cc0`, half-angle `(fov/2)/√(aspect²+1)`)
+/// at a fixed 4:3, a vertical half-angle of `0.3·fov`, with nothing on top. Model space, radians.
 #[derive(Debug, Clone, Copy)]
 pub struct M2PortraitCamera {
-    /// FOV in radians (record `+0x04`), copied verbatim into the projection build (`0x70ebd0` →
-    /// `0x5c3cc0`) — a **diagonal** opening angle in the client's convention, NOT fovy (the
-    /// vertical half-angle at the portrait's 4/3 aspect is `0.3·fov`).
+    /// The diagonal opening angle, not fovy (`0x70ebd0` to `0x5c3cc0`).
     pub fov: f32,
-    /// Far clip plane (`+0x08`).
     pub far_clip: f32,
-    /// Near clip plane (`+0x0c`).
     pub near_clip: f32,
-    /// Camera eye: `position_base (+0x2c)` plus the position track's first key (`+0x10`) — portrait
-    /// cameras are static in practice (one key or none), so key 0 *is* the evaluated value.
+    /// The eye, like `target` its base plus its track's first key; `roll` is a first key alone.
     pub position: [f32; 3],
-    /// Look target: `target_base (+0x54)` plus the target track's first key (`+0x38`).
     pub target: [f32; 3],
-    /// Roll about the view axis (radians), the roll track's first key (`+0x60`); `0.0` when unkeyed.
     pub roll: f32,
 }
 
-/// Parse the M2's **portrait camera** straight from the raw bytes: cameras `count@0x124`/`ofs@0x128`
-/// (stride `0x7c`), selected via `cameraLookup[0]` (`count@0x12c`/`ofs@0x130`, u16 entries) — exactly
-/// the real client's selection (see [`M2PortraitCamera`]). `None` when the model carries no camera
-/// table / no lookup slot 0 (some props and a few creatures — the caller falls back to heuristic
-/// framing). The `0xffff` "none" sentinel and a malformed lookup both fall out as an out-of-range
-/// index, which [`parse_m2_camera`] answers with `None`.
+/// The portrait camera, `cameraLookup[0]` (`count@0x12c`/`ofs@0x130`) into the camera table
+/// (`count@0x124`/`ofs@0x128`, stride `0x7c`) as the reference selects it; `None` without one,
+/// the `0xffff` sentinel included.
 pub fn parse_m2_portrait_camera(bytes: &[u8]) -> Option<M2PortraitCamera> {
     let idx = *benilla_m2::parse_camera_lookup(bytes).first()? as usize;
     parse_m2_camera(bytes, idx)
 }
 
-/// One camera record by **table index** — the glue screens' `Model:SetCamera(idx)` path (the
-/// create/select background scenes carry exactly one camera whose *lookup* slot holds the 0xffff
-/// none sentinel, so the portrait selection above sees nothing; the client indexes the table
-/// directly there). Same record read as the portrait camera.
-/// This is the **key-0 reduction** of [`benilla_m2::parse_cameras`], which is the one place the
-/// record's offsets are written down. A pane/portrait camera is static in practice — one key or
-/// none — so key 0 *is* its evaluated value; a camera whose tracks actually move over time (the
-/// `Cameras\*.m2` cinematic fly-bys) is sampled through the parsed record instead, never here.
+/// One camera record by table index, the glue screens' `Model:SetCamera(idx)` path: their one
+/// camera has the `0xffff` sentinel in its lookup slot, so the client indexes the table directly.
+/// Key 0 of each track; a moving camera is sampled through [`M2PaneCamera::at`].
 pub fn parse_m2_camera(bytes: &[u8], index: usize) -> Option<M2PortraitCamera> {
     let cam = benilla_m2::parse_cameras(bytes).into_iter().nth(index)?;
     let base_plus_key = |base: [f32; 3], track: &benilla_m2::M2Vec3SplineTrack| {
@@ -308,19 +245,14 @@ pub fn parse_m2_camera(bytes: &[u8], index: usize) -> Option<M2PortraitCamera> {
     })
 }
 
-/// One SMOLight record at a bounds-checked `r` (the loop below already proved `r + 0x30 <= b.len()`):
-/// type@0, useAtten@1, colour(BGRA)@4, position@8, intensity@0x14, **attenStart@0x28, attenEnd@0x2c**.
-/// The runtime-consumed disk attenuation fields sit at the record's TAIL, not right after the
-/// intensity — `+0x18..+0x28` hold four other floats (≈0, −0, −1, −0.5 on every vanilla light
-/// audited). Verified two ways: wow-re `trace-forensics-abbey-interior-d3d` §4 fitted the reference's
-/// fold window at exactly the `+0x28/+0x2c` values (NSabbey MOLT[10] 3.3333/4.7222; MOLT[40]/[41]
-/// end 5.5556), and the abbey file carries those numbers at `+0x28/+0x2c` while `+0x18/+0x1c` read
-/// ≈0/−0 (an earlier read of `+0x18/+0x1c` shipped zeros — dormant while nothing consumed them).
+/// One `SMOLight` at a bounds-checked `r`: type@0, useAtten@1, colour (BGRA)@4, position@8,
+/// intensity@0x14, attenStart@0x28, attenEnd@0x2c. The attenuation the reference uses is the
+/// tail; `+0x18..+0x28` hold four other floats (≈0, −0, −1, −0.5 on every vanilla light).
 fn read_wmo_light(b: &[u8], r: usize) -> Option<WmoLight> {
     Some(WmoLight {
         light_type: b.u8_at(r)?,
         use_atten: b.u8_at(r + 1)? != 0,
-        // CImVector is BGRA in memory; recover RGB.
+        // CImVector is BGRA in memory.
         color: [
             f32::from(b.u8_at(r + 6)?) / 255.0,
             f32::from(b.u8_at(r + 5)?) / 255.0,
@@ -333,21 +265,10 @@ fn read_wmo_light(b: &[u8], r: usize) -> Option<WmoLight> {
     })
 }
 
-/// Parse a WMO root's **MOLT** lights straight from the chunk bytes (`benilla-wmo` doesn't expose
-/// them). Scans the flat root chunk list for `MOLT` (magic stored reversed, `TLOM`) and reads each
-/// 0x30-byte SMOLight (see [`read_wmo_light`]). NOTE: the chunk walk must NOT stop at a zero-size
-/// chunk — `MOVV(0)`/`MOVB(0)` sit right before MOLT in vanilla roots (a bug there once hid MOLT
-/// entirely). `root_bytes` is the raw WMO **root** file.
-///
-/// Hand-rolled rather than `benilla_bytes::chunks()` (decision 0064): the two disagree on what a
-/// record's bound is once a chunk's declared `size` is trusted past this walk. `chunks()` clamps a
-/// chunk's *payload slice* to the buffer end and the record loop would then be bounds-checked against
-/// that clamped slice; this scan instead advances `o` by the *unclamped* `data + size` (so a corrupt
-/// size can push `o` past `b.len()`, which the `while` guard catches next iteration) and, for the
-/// matched MOLT chunk, bounds each record against the **whole buffer** (`r + 0x30 <= b.len()`), not
-/// against `size`. Both give identical records for well-formed input (the case this function is
-/// proven against), but they are not the same algorithm, so this stays hand-rolled per the migration
-/// guidance rather than being forced onto `chunks()`.
+/// A WMO root file's MOLT lights, which `benilla-wmo` does not expose: the chunk list scanned for
+/// `MOLT` (stored reversed, `TLOM`). The walk must not stop at a zero-size chunk: `MOVV(0)` and
+/// `MOVB(0)` sit right before MOLT in vanilla roots. Hand-rolled, not `benilla_bytes::chunks()`:
+/// each record is bounded by the whole buffer, not by a clamped chunk payload.
 pub fn parse_wmo_lights(root_bytes: &[u8]) -> Vec<WmoLight> {
     let b = root_bytes;
     let mut o = 0usize;
@@ -365,7 +286,7 @@ pub fn parse_wmo_lights(root_bytes: &[u8]) -> Vec<WmoLight> {
                 };
                 match read_wmo_light(b, r) {
                     Some(light) => out.push(light),
-                    None => break, // unreachable given the filter above; defensive, not a panic
+                    None => break, // unreachable after the filter above
                 }
             }
             return out;
@@ -382,9 +303,7 @@ pub fn parse_wmo_lights(root_bytes: &[u8]) -> Vec<WmoLight> {
 mod tests {
     use super::*;
 
-    /// Build a minimal buffer holding a 2-bone chain (root rotated 90° about +X, child 90° about
-    /// +Z locally) with the vanilla layout: bone table `count@0x34`/`ofs@0x38`, stride 0x6c,
-    /// rotation track @+0x28 (values `count@+0x14`/`ofs@+0x18`, keys `[x,y,z,w]` f32).
+    /// A 2-bone chain: the root turned 90° about +X, the child 90° about its own +Z.
     fn two_bone_chain() -> Vec<u8> {
         let mut b = vec![0u8; 0x400];
         let put_u32 =
@@ -412,10 +331,8 @@ mod tests {
         b
     }
 
-    /// GOLDEN — the directional-direction law's rotation walk: `global = parent ∘ local`, applied
-    /// to +Z. Root alone: 90° about +X sends +Z → −Y. The child's local 90° about +Z does not move
-    /// its own +Z axis, so the chained result equals the root's — proving the composition order
-    /// (a local-first walk would differ for the mirrored case below).
+    /// Root alone: 90° about +X sends +Z to −Y. The child's turn about +Z leaves its own +Z, so
+    /// the chain gives the root's axis.
     #[test]
     fn bone_z_axis_composes_parent_then_local() {
         let b = two_bone_chain();
@@ -425,41 +342,30 @@ mod tests {
         for (c, r) in child.iter().zip(root) {
             assert!((c - r).abs() < 1e-6, "child {child:?} vs root {root:?}");
         }
-        // No rotation keys anywhere → identity +Z.
+        // No rotation keys anywhere: identity +Z.
         assert_eq!(bone_z_axis(&vec![0u8; 0x400], 0), [0.0, 0.0, 1.0]);
     }
 }
 
-/// One record of the file's **camera table**, by RAW table index — what `Model:SetCamera(n)`
-/// selects on a `<Model>` widget.
-///
-/// The selection is **raw**: `0x76cec0` reads the count off `MD20+0x124` and the record at
-/// `[model+0x3c4] + idx·0x84 + 0x80`, and **`cameraLookup` is not consulted** on that path (wow-re
-/// `ui/scratch/modelframe-camera-law.md` §2.1 — the sibling pair that *does* consult it,
-/// `0x713500`/`0x713540`, has its one call site at the portrait bake). So the index decides and
-/// [`Self::camera_type`] never does; it is carried because a reader will otherwise assume the
-/// opposite.
-///
-/// [`Self::still`] is the rest rig — the record's bases plus each track's first key. That is the
-/// whole answer for every model a `<Model>` pane can name: wow-re's census over all 9691 `.m2` of
-/// the composite found every character/creature/interface camera's position/target/roll track
-/// carrying exactly one key of `(0,0,0)`/`0` (§7). [`Self::at`] is the general case — the
-/// `Cameras\*.m2` fly-bys, whose Bézier paths a widget would sample like any other track.
+/// One camera table record by raw index, what `Model:SetCamera(n)` selects on a `<Model>` widget:
+/// `0x76cec0` reads the count off `MD20+0x124` and the record at `[model+0x3c4] + idx·0x84 + 0x80`
+/// without consulting `cameraLookup` (only `0x713500`/`0x713540` do, for the portrait bake), so
+/// the index decides and [`Self::camera_type`] never does. Every shipped character, creature and
+/// interface camera is its [`Self::still`] rig, each track one key of zero; [`Self::at`] samples
+/// the `Cameras\*.m2` fly-bys.
 #[derive(Debug, Clone)]
 pub struct M2PaneCamera {
-    /// The record's `type` word (`+0x00`): `0` = portrait, `1` = "characterinfo", `-1` on every
-    /// shipped fly-by and on the six glue scenes. Never selected on — see the type docs.
+    /// The `type` word (`+0x00`): 0 portrait, 1 characterinfo, -1 on every shipped fly-by and the
+    /// six glue scenes.
     pub camera_type: i32,
-    /// The rig at rest: bases + each track's first key, raw WoW model space.
+    /// The rig at rest: the bases plus each track's first key.
     pub still: M2PortraitCamera,
-    /// The authored tracks, kept **only when one of them actually moves** (more than one distinct
-    /// key) — otherwise `still` is the camera at every instant and there is nothing to sample.
+    /// The authored tracks, kept only when one moves (more than one distinct key).
     pub tracks: Option<Box<M2CameraTracks>>,
 }
 
-/// A moving camera's three authored tracks plus their bases — the publish pass's inputs
-/// (`0x718960` `[0x718b60, 0x718c3a)`): `eye = position_base + positions(t)`,
-/// `target = target_position_base + target(t)`, `roll = roll(t)`.
+/// A moving camera's tracks and bases, the publish pass's inputs (`0x718960`,
+/// `[0x718b60, 0x718c3a)`): `eye = position_base + positions(t)`, likewise the target.
 #[derive(Debug, Clone)]
 pub struct M2CameraTracks {
     pub positions: benilla_m2::M2Vec3SplineTrack,
@@ -470,13 +376,9 @@ pub struct M2CameraTracks {
 }
 
 impl M2PaneCamera {
-    /// The rig at absolute file-timeline `ms` — [`Self::still`] for a static camera, the sampled
-    /// tracks for a moving one. Raw WoW model space, radians.
-    ///
-    /// The sampler is [`benilla_m2::M2Track::sample_ms`], the reference's own four-way cubic
-    /// `interp` dispatch (STEP/LINEAR/BÉZIER/HERMITE) with both ends clamped — the fly-bys author
-    /// BÉZIER. `ms` is the model's animation clock, which for a widget pane is its private scene
-    /// clock resolved through the armed sequence's band (the pane's play head plus the band start).
+    /// The rig at absolute file-timeline `ms`, through [`benilla_m2::M2Track::sample_ms`] (the
+    /// reference's four-way `interp` dispatch, both ends clamped; the fly-bys author Bézier). A
+    /// pane's `ms` is its play head plus the armed sequence's band start.
     pub fn at(&self, ms: u32) -> M2PortraitCamera {
         let Some(t) = self.tracks.as_deref() else {
             return self.still;
@@ -494,11 +396,8 @@ impl M2PaneCamera {
     }
 }
 
-/// Parse the whole camera table, in file order — the raw index space `Model:SetCamera(n)` walks.
-/// Empty for the overwhelming majority of models (9225 of the composite's 9691).
-///
-/// This is the table read of [`parse_m2_camera`]'s single-record reduction; both go through
-/// [`benilla_m2::parse_cameras`], which is the one place the `0x7c` record layout is written down.
+/// The whole camera table in file order, the index space of `Model:SetCamera(n)`; empty for most
+/// models. The `0x7c` record layout lives in [`benilla_m2::parse_cameras`].
 pub fn parse_m2_pane_cameras(bytes: &[u8]) -> Vec<M2PaneCamera> {
     benilla_m2::parse_cameras(bytes)
         .into_iter()
@@ -518,9 +417,7 @@ pub fn parse_m2_pane_cameras(bytes: &[u8]) -> Vec<M2PaneCamera> {
                 target: base_plus(cam.target_base, &cam.target),
                 roll: cam.roll.keys.first().map_or(0.0, |(_, k)| k.value),
             };
-            // A track that never leaves its first key is the still rig at every instant; keeping
-            // it would cost a sample per frame to reproduce a constant. Every shipped
-            // character/creature/interface camera lands here (wow-re camera-law §7).
+            // A track that never leaves its first key is the still rig at every instant.
             let moves = |n: usize, same: bool| n > 1 && !same;
             let v3_moves = |t: &benilla_m2::M2Vec3SplineTrack| {
                 let first = key0(t);
diff --git a/crates/benilla-formats/src/models/tex_anim.rs b/crates/benilla-formats/src/models/tex_anim.rs
index 699b61bf..8199628d 100644
--- a/crates/benilla-formats/src/models/tex_anim.rs
+++ b/crates/benilla-formats/src/models/tex_anim.rs
@@ -1,59 +1,41 @@
-//! The **texture-transform** (UV-animation) bake (decision 0130 phase 3): each M2 batch's texture
-//! transform — batch `textureTransformComboIndex` (texUnit `+0x16`) → texAnimLookup (header `0xac`,
-//! `0xffff`/out-of-range = none) → the record's **translation** track, baked to a loopable UV-offset
-//! loop on the same clocks as the material-alpha bake (gseq wrap / seq-0 band).
-//!
-//! The translation channel is what the world's shared-material lane consumes: the full 7968-model
-//! 1.12 corpus sweep found 281 of 286 transforms translation-keyed, and every rotation/scaling
-//! user is a UI/spell-effect/goober model — **zero placed world doodads**. The rotation and
-//! scaling channels bake per file sequence slot ([`bake_uv_rot_seqs`] / [`bake_uv_scale_seqs`],
-//! decision 2019) for the lanes that own their materials per instance — the UI model tiles, whose
-//! cooldown indicator is four quadrant quads turned by their rotation tracks. The baked values are
-//! the tracks' raw numbers; the law that composes them is [`uv_transform`], and the shader is its
-//! twin.
+//! The texture-transform (UV animation) bake: a batch's `textureTransformComboIndex` (texUnit
+//! `+0x16`) goes through texAnimLookup (header `0xac`, `0xffff` for none) to a transform whose
+//! tracks bake on the material-alpha bake's clocks. Translation feeds the world's shared-material
+//! lane; rotation and scaling, authored only by UI, spell-effect and gameobject models, bake per
+//! file sequence slot for lanes that own a material per instance (the UI cooldown indicator's
+//! four quadrants). The values stay raw; [`uv_transform`] composes them.
 
 use benilla_m2::M2Model;
 
 use super::key_anim::{bake_track, KeyAnim, SeqLoops, SeqSlot};
 
-/// One baked UV-offset loop, seconds — see [`KeyAnim`]. The texture-transform translation
-/// channel's instantiation: values are the track's raw `(x, y)`.
+/// One baked UV-offset loop, the translation channel's [`KeyAnim`] of raw `(x, y)`.
 pub type UvAnim = KeyAnim<[f32; 2]>;
 
 impl KeyAnim<[f32; 2]> {
-    /// The UV offset at `elapsed` seconds on the loop clock (`[0, 0]` — the additive identity —
-    /// for a defensively-empty loop the bake never emits).
+    /// The UV offset at `elapsed` seconds; `[0, 0]` for an empty loop.
     pub fn sample(&self, elapsed: f32) -> [f32; 2] {
         self.sample_or(elapsed, [0.0, 0.0])
     }
 }
 
-/// One baked texture-transform **rotation** loop — the raw quaternion keys, component-lerped
-/// (see [`bake_uv_rot_seqs`]).
+/// One baked rotation loop of raw quaternion keys, component-lerped ([`bake_uv_rot_seqs`]).
 pub type UvRotAnim = KeyAnim<[f32; 4]>;
 
 impl KeyAnim<[f32; 4]> {
-    /// The raw quaternion at `elapsed` seconds on the loop clock (the identity `(0, 0, 0, 1)`
-    /// for a defensively-empty loop the bake never emits).
+    /// The raw quaternion at `elapsed` seconds; the identity for an empty loop.
     pub fn sample(&self, elapsed: f32) -> [f32; 4] {
         self.sample_or(elapsed, [0.0, 0.0, 0.0, 1.0])
     }
 }
 
-/// `(x, y)` within a hair of zero — the offset that moves nothing.
 fn is_zero(v: [f32; 2]) -> bool {
     v[0].abs() < 1e-6 && v[1].abs() < 1e-6
 }
 
-/// Bake the batch's UV-offset loop, or `None` when the batch has no texture transform (the
-/// overwhelmingly common case), the looked-up record is absent (`0xffff` sentinel falls out of the
-/// bounds check), or its translation track never moves the UVs.
-///
-/// Deliberately **one sequence**, unlike the material-alpha bake next door: a UV loop is consumed
-/// through a shared per-MATERIAL registry (`doodad_anim::UvAnimMaterials` — one uniform for every
-/// instance of a batch), which has no per-instance sequence to key on. Making it per-sequence needs
-/// that registry to become per-instance first; every UV-animating model measured is a scroll that
-/// runs the same in every sequence, so nothing observable rests on it (recorded, not assumed).
+/// Bake the batch's UV-offset loop for one sequence, or `None` without a transform or when its
+/// translation never moves. One loop, because the shared per-material registry it feeds
+/// (`UvAnimMaterials`) has no sequence to key on; [`bake_uv_seqs`] covers slots that differ.
 pub(super) fn bake_uv_anim(
     model: &M2Model,
     combo_index: u16,
@@ -71,15 +53,8 @@ pub(super) fn bake_uv_anim(
     )
 }
 
-/// Bake the batch's UV-offset loop **for every file sequence slot** — the per-sequence form of
-/// [`bake_uv_anim`], and the answer to the question that function's own doc used to settle by
-/// measurement ("every UV-animating model measured is a scroll that runs the same in every
-/// sequence"). `benilla-extract uvslotscan` re-ran that measurement and it is false: 22 of the 32
-/// multi-slot UV batch-channels in the 1.12 corpus have a **dead slot 0** beside a live later slot.
-///
-/// `None` when no slot animates at all. The caller keeps [`bake_uv_anim`]'s slot-0 loop for the
-/// shared-material lane and reaches for this only when [`SeqLoops::uniform`] declines (decision
-/// 1408).
+/// [`bake_uv_anim`] per file sequence slot, `None` when no slot animates. The caller keeps the
+/// shared lane's loop and takes this only when [`SeqLoops::uniform`] declines.
 pub(super) fn bake_uv_seqs(
     model: &M2Model,
     combo_index: u16,
@@ -104,22 +79,18 @@ pub(super) fn bake_uv_seqs(
     )
 }
 
-/// A rotation quaternion within a hair of the identity `(0, 0, 0, 1)`.
 fn is_quat_identity(q: [f32; 4]) -> bool {
     q[0].abs() < 1e-6 && q[1].abs() < 1e-6 && q[2].abs() < 1e-6 && (q[3] - 1.0).abs() < 1e-6
 }
 
-/// A scale within a hair of `(1, 1)`.
 fn is_scale_identity(v: [f32; 2]) -> bool {
     (v[0] - 1.0).abs() < 1e-6 && (v[1] - 1.0).abs() < 1e-6
 }
 
-/// Bake the batch's texture-transform **rotation** loop per file sequence slot — the raw
-/// quaternion keys, **component-lerped and never normalised**, which is what the reference does
-/// (`0x713ea0` lerps each component and `0x7bddb0` consumes the result as is: between two 22.5°
-/// keys `|q|` dips to cos 11.25° and the block is a rotation with a slight shrink — wow-re
-/// `modelframe-texanim-and-sequence-law.md` §3.4). `None` when the transform is absent or its
-/// rotation never leaves the identity.
+/// Bake the batch's rotation loop per file sequence slot: the raw quaternion keys lerped per
+/// component and never normalised, as the reference does (`0x713ea0` lerps, `0x7bddb0` uses the
+/// result as is, so between two 22.5° keys `|q|` dips to cos 11.25° and the block shrinks a
+/// little). `None` when the rotation never leaves the identity.
 pub(super) fn bake_uv_rot_seqs(
     model: &M2Model,
     combo_index: u16,
@@ -144,8 +115,8 @@ pub(super) fn bake_uv_rot_seqs(
     )
 }
 
-/// Bake the batch's texture-transform **scaling** loop per file sequence slot (`(x, y)` of the
-/// track's vec3). `None` when the transform is absent or its scale never leaves `(1, 1)`.
+/// Bake the batch's scaling loop (the vec3's `(x, y)`) per file sequence slot; `None` when the
+/// scale never leaves `(1, 1)`.
 pub(super) fn bake_uv_scale_seqs(
     model: &M2Model,
     combo_index: u16,
@@ -170,17 +141,11 @@ pub(super) fn bake_uv_scale_seqs(
     )
 }
 
-/// **The texture transform's law**, from the file to the texel (wow-re
-/// `modelframe-texanim-and-sequence-law.md` §3.4, VERIFIED trio-convergent):
-///
-/// > `uv' = R_q((uv + t − p) ⊙ s) + p`, `p = (½, ½)`
-///
-/// — the translation is added first, the scale is applied about the pivot, then the rotation
-/// about the pivot. `R_q` is the standard active rotation of the raw (unnormalised) quaternion;
-/// for the z-only quaternions every shipped UI asset authors, `c = 1 − 2z²`, `s = 2zw`, and
-/// `+θ` turns counter-clockwise in the `u`-right / `v`-up frame. A quaternion with x/y components
-/// would turn the plane out of itself; this reads its z-rotation alone (the shipped population
-/// has none). `wow_model.wgsl`'s UV fold is this function's twin: keep the two in step.
+/// The texture transform, `uv' = R_q((uv + t − p) ⊙ s) + p` with `p = (½, ½)` (`0x715f25`):
+/// translate, scale about the pivot, then rotate about it. `R_q`, the raw quaternion's rotation,
+/// is read here as its z-rotation alone, `c = 1 − 2z²`, `s = 2zw`, `+θ` counter-clockwise with `u`
+/// right and `v` up: no shipped rotation has x or y components. `wow_model.wgsl`'s UV fold must
+/// stay in step.
 pub fn uv_transform(uv: [f32; 2], t: [f32; 2], q: [f32; 4], s: [f32; 2]) -> [f32; 2] {
     let (c, sn) = rotation_2x2(q);
     let dx = (uv[0] + t[0] - 0.5) * s[0];
@@ -188,8 +153,7 @@ pub fn uv_transform(uv: [f32; 2], t: [f32; 2], q: [f32; 4], s: [f32; 2]) -> [f32
     [0.5 + dx * c - dy * sn, 0.5 + dx * sn + dy * c]
 }
 
-/// The `(cos, sin)` of a raw quaternion's z-rotation, as the reference's matrix builder yields
-/// them — `1 − 2z²`, `2zw`, unnormalised (see [`uv_transform`]).
+/// The `(cos, sin)` of a raw quaternion's z-rotation as the reference builds them, unnormalised.
 pub fn rotation_2x2(q: [f32; 4]) -> (f32, f32) {
     let (z, w) = (q[2], q[3]);
     (1.0 - 2.0 * z * z, 2.0 * z * w)
@@ -200,10 +164,8 @@ mod tests {
     use super::*;
     use benilla_m2::M2Vec3Track;
 
-    /// The law's handedness, on the note's own worked example: `θ = +90°` (`z = w = √½`),
-    /// `p = (½, ½)`, no translation, unit scale — `(1, 0.5) ↦ (0.5, 1.0)`, a counter-clockwise
-    /// turn in the `u`-right / `v`-up frame; and a `z < 0` key (every key of the cooldown model)
-    /// turns the other way.
+    /// `θ = +90°` (`z = w = √½`) takes `(1, 0.5)` to `(0.5, 1.0)`, counter-clockwise; a `z < 0`
+    /// key, as in every key of the cooldown model, turns the other way.
     #[test]
     fn the_uv_law_turns_counter_clockwise_for_a_positive_z() {
         let r = std::f32::consts::FRAC_1_SQRT_2;
@@ -217,17 +179,16 @@ mod tests {
             (cw[0] - 0.5).abs() < 1e-6 && (cw[1] - 0.0).abs() < 1e-6,
             "{cw:?}"
         );
-        // Identity in, identity out — the static path's whole population.
+        // Identity in, identity out.
         let id = uv_transform([0.2, 0.7], [0.0, 0.0], [0.0, 0.0, 0.0, 1.0], [1.0, 1.0]);
         assert!((id[0] - 0.2).abs() < 1e-6 && (id[1] - 0.7).abs() < 1e-6);
-        // A translation is added BEFORE the pivoted rotation: `(uv + t − p)` turns.
+        // The translation is added before the pivoted rotation: `(uv + t − p)` turns.
         let tr = uv_transform([0.5, 0.5], [0.5, 0.0], [0.0, 0.0, r, r], [1.0, 1.0]);
         assert!(
             (tr[0] - 0.5).abs() < 1e-6 && (tr[1] - 1.0).abs() < 1e-6,
             "{tr:?}"
         );
-        // The lerped, unnormalised midpoint between 0° and 45° keys shrinks: |q| < 1 ⇒ the
-        // block's scale is below 1 (the note's cos 11.25° effect, at a coarser pair here).
+        // The unnormalised midpoint of 0° and 45° keys has `|q| < 1`, so the block shrinks.
         let (c, sn) = rotation_2x2([
             0.0,
             0.0,
@@ -237,10 +198,8 @@ mod tests {
         assert!((c * c + sn * sn).sqrt() < 1.0);
     }
 
-    /// The cooldown indicator's own rotation tracks, straight off the client data: transform 0's
-    /// keys turn `0 → −90°` over the first 250 ms of sequence 0 (`z` from 0 to `−√½`) and hold
-    /// there to the sequence's end; sequence 1's window is the identity throughout (its keys at
-    /// 1167 and 2167 ms are both `(0, 0, 0, 1)`). Skips without client data.
+    /// The cooldown indicator's transform 0 turns 0 to −90° over sequence 0's first 250 ms (`z`
+    /// from 0 to `−√½`) and holds; sequence 1's keys at 1167 and 2167 ms are both the identity.
     #[test]
     fn the_cooldown_indicators_rotation_bakes_per_sequence() {
         let data = crate::wow_data_or_skip!();
@@ -268,7 +227,7 @@ mod tests {
             "held to the end: {:?}",
             at(0.9)
         );
-        // The lerp between the 0 and 62 ms keys is component-wise on the raw quaternion.
+        // Between the 0 and 62 ms keys, a per-component lerp of the raw quaternion.
         let mid = at(0.031);
         assert!(mid[2] < 0.0 && mid[2] > -r);
         assert!(subs[0].uv_scale_seq.is_none(), "no scale track");
@@ -285,7 +244,7 @@ mod tests {
     }
 
     fn bake(t: &M2Vec3Track, gseq: &[u32], seq0: Option<(u32, u32)>) -> Option<UvAnim> {
-        // Slot 0 as the UV lane meets it: the loop a placed doodad's one-time arm plays.
+        // Slot 0, looping, as the UV lane bakes it.
         let slot = seq0.map(|band| SeqSlot {
             index: 0,
             band,
@@ -294,8 +253,7 @@ mod tests {
         super::super::key_anim::bake_track(t, gseq, slot, |v| [v[0], v[1]], is_zero, is_zero)
     }
 
-    /// A keyless or never-moving track vanishes; a constant non-zero offset is kept period-0 (a
-    /// static UV shift the vertex data doesn't carry).
+    /// A constant non-zero offset is a static UV shift the vertex data does not carry.
     #[test]
     fn bake_drops_the_identity_and_keeps_a_static_shift() {
         assert_eq!(bake(&track(0xffff, 1, &[]), &[], None), None);
@@ -312,8 +270,7 @@ mod tests {
         assert_eq!(shift.sample(77.0), [0.25, 0.5]); // z discarded
     }
 
-    /// The fountain shape (gseq clock): a 2-key linear ramp wrapping the global-sequence duration —
-    /// the offset accumulates to a full texture period each loop.
+    /// The fountain shape: a 2-key ramp over the global-sequence duration, one texture per loop.
     #[test]
     fn gseq_scroll_wraps_and_lerps() {
         let a = bake(
@@ -328,10 +285,7 @@ mod tests {
         assert!((a.sample(1.333 + 0.1)[1] - a.sample(0.1)[1]).abs() < 1e-4);
     }
 
-    /// The real Elwynn waterfall, straight off the client data: both batches carry seq-0-band
-    /// translation loops (V-scroll, −1.0 and −2.0 per loop — the 2× foam layer), wired batch →
-    /// texAnimLookup → transform. Guards the whole chain: the vec3-track parse (benilla-m2), the
-    /// 0xac lookup slot, the combo two-hop, and the band-clock bake. Skips without client data.
+    /// The Elwynn waterfall's two batches scroll V by −1.0 and −2.0 per loop (the foam layer).
     #[test]
     fn elwynn_waterfall_bakes_two_v_scroll_loops() {
         let data = crate::wow_data_or_skip!();
@@ -352,7 +306,6 @@ mod tests {
                 "the V offset moves over the loop ({v0:?} vs {v1:?})"
             );
         }
-        // The two layers scroll at different rates (the −1.0 vs −2.0 authoring).
         let (e0, e1) = (
             anims[0].keys.last().unwrap().1[1],
             anims[1].keys.last().unwrap().1[1],
diff --git a/crates/benilla-formats/src/models/types.rs b/crates/benilla-formats/src/models/types.rs
index 889120c6..154eb3a3 100644
--- a/crates/benilla-formats/src/models/types.rs
+++ b/crates/benilla-formats/src/models/types.rs
@@ -1,48 +1,30 @@
-//! The shared render types every model source (M2 batches, WMO groups) produces: [`RenderSubmesh`]
-//! (one per render batch) and the material/animation bits it carries — [`ModelBlend`],
-//! [`CharSkinSlot`], [`BillboardKind`]/[`Billboard`], and the billboard glow-card pulse
-//! ([`BoneScaleAnim`]). No parsing lives here — just the shapes [`m2_batches`](super::m2_batches) and
-//! [`wmo`](super::wmo) both build.
+//! The render types every model source (M2 batches, WMO groups) produces, one per render batch.
 
 use super::key_anim::SeqLoops;
 use super::mat_anim::{AlphaAnim, RgbAnim};
 use super::tex_anim::UvAnim;
 
-/// How a submesh blends — maps the model's blend mode to the renderer's alpha handling.
+/// How a submesh blends: the model's blend mode mapped to the renderer's alpha handling.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum ModelBlend {
-    /// Fully opaque (trunks, walls, floors).
     Opaque,
-    /// Alpha-tested cutout (leaf canopies, fences, windows).
     AlphaTest,
-    /// Alpha-blended / additive.
+    /// Alpha-blended or additive.
     Blend,
-    /// Multiplicative — `out = src·dst` (GL `DST_COLOR/ZERO`; byte-verified wow-re
-    /// `m2-depth-blend-state`: M2 mode 5 → EGxBlend 4; WMO MOMT mode 4, direct index). Darkens/tints
-    /// what's already drawn; the blend equation reads NO alpha, so these batches cannot alpha-fade
-    /// (decision 0528).
+    /// `out = src·dst` (GL `DST_COLOR/ZERO`; `0x811fe0`: M2 mode 5 → EGxBlend 4; WMO MOMT mode 4).
+    /// The equation reads no alpha, so these batches cannot alpha-fade.
     Mod,
-    /// 2× multiplicative — `out = 2·src·dst` (GL `DST_COLOR/SRC_COLOR`; M2 mode 6 → EGxBlend 5; WMO
-    /// mode 5, direct index). Neutral at mid-grey, brightens above it: the weapon/armor ARMORREFLECT
-    /// sheen layer. Same no-alpha law as [`Self::Mod`] (decision 0528).
+    /// `out = 2·src·dst` (GL `DST_COLOR/SRC_COLOR`; M2 mode 6 → EGxBlend 5; WMO mode 5), neutral at
+    /// mid-grey: the ARMORREFLECT sheen. No alpha either.
     Mod2x,
 }
 
-/// A character body texture the client supplies at runtime from the player's appearance — the M2
-/// texture record carries the *type* but no embedded filename, so the spawn site swaps a per-player
-/// material onto the batches that carry the slot.
-/// - `Body` (M2 texture type 1) — the composited body atlas: base skin + face/facial-hair/pelvis
-///   overlays (decisions 0041 / 0044).
-/// - `Hair` (M2 texture type 6) — the hair-mesh texture, a single CharSections `sectionType 3`
-///   `TextureName[0]` BLP keyed by hairStyle + hairColor (decision 0045).
-/// - `Object` (M2 texture type 2) — the runtime-bound **object skin**: on a weapon/shield M2 this is
-///   the item's own texture (`ItemDisplayInfo`'s model-texture column, decision 0072); on a
-///   character body model this same type is the cape slot. Which meaning applies depends on the
-///   model wearing the batch, not on the type alone — the spawn site resolves it per-consumer.
-/// - `SkinExtra` (M2 texture type 8) — the standalone **extra skin** BLP: CharSections `sectionType 0`
-///   `TextureName[1]` keyed by skinColor (`…Skin00_NN_Extra.blp`), loaded plain (never composited —
-///   the client's dedicated extra-texture loader is a bare TextureCreate). Only fur races author it:
-///   the tauren body binds its head/leg fur batches to this slot instead of the body atlas.
+/// A character texture the client supplies at runtime (the record has a type, no filename):
+/// - `Body` (type 1): the composited body atlas;
+/// - `Hair` (type 6): CharSections `sectionType 3` `TextureName[0]` by hair style and colour;
+/// - `Object` (type 2): the item's texture on a weapon or shield, the cape on a body;
+/// - `SkinExtra` (type 8): CharSections `sectionType 0` `TextureName[1]` by skin colour,
+///   uncomposited (fur).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum CharSkinSlot {
     Body,
@@ -51,27 +33,21 @@ pub enum CharSkinSlot {
     SkinExtra,
 }
 
-/// How a billboarded bone tracks the camera (M2 bone billboard flags). The cylindrical arms keep
-/// one authored axis and rebuild the in-plane pair from the camera — WHICH axis is kept is part
-/// of the authored look (the frost-armor sheets ride a lock-Z bone so they stay upright while
-/// spinning to face the viewer), so the three lock bits stay distinct here.
+/// How a billboard bone tracks the camera (M2 bone flags); a cylindrical kind keeps one axis.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BillboardKind {
-    /// Spherical (`0x08`) — faces the camera fully (glow cards, coronae).
+    /// Spherical (`0x08`): faces the camera fully (glow cards, coronae).
     Spherical,
-    /// Cylindrical lock-X (`0x10`) — keeps the bone's X axis (chains, ropes).
+    /// Cylindrical lock-X (`0x10`): keeps the bone's X axis (chains, ropes).
     LockX,
     /// Cylindrical lock-Y (`0x20`).
     LockY,
-    /// Cylindrical lock-Z (`0x40`) — keeps model up (the questgiver `?` marker, the frost-armor
-    /// sheets): spins about the vertical to face the viewer.
+    /// Cylindrical lock-Z (`0x40`): stays upright, turning to the viewer (the questgiver `?`).
     LockZ,
 }
 
 impl BillboardKind {
-    /// The kind an M2 bone's flag word authors, `None` for an ordinary bone — THE mapping, shared
-    /// by the batch splitter and the skeleton bake. `0x08` wins over a (never-seen) combined lock
-    /// bit, matching the palette replacement's own dispatch order.
+    /// The kind a bone's flags author; `0x08` wins over a lock bit, as the palette dispatch orders.
     pub fn from_bone_flags(bits: u32) -> Option<Self> {
         if bits & 0x08 != 0 {
             Some(Self::Spherical)
@@ -87,47 +63,33 @@ impl BillboardKind {
     }
 }
 
-/// How a bone's **effective parent matrix** is rewritten before it composes — M2 bone flag bits
-/// `0x1/0x2/0x4`, the standard `ignore parent translate / scale / rotate` trio.
-///
-/// The reference tests `flags & 7` on every non-root bone (`m2_animate` `0x714961`) and, when any
-/// of the three is set, takes a ~950-byte arm (`0x71496d`–`0x714d0c`) that rebuilds that bone's
-/// parent matrix out of the **model's own root matrix** — pivot-preserved — *and then falls into
-/// the billboard selector unchanged*. It is not an escape hatch from anything: it changes the
-/// INPUT the billboard law is applied to (wow-re `billboard-bone-law.md` §9.1, byte-verified).
-///
-/// The three legs are proven from the binary, matching the standard names: `0x1` at `0x714c92`,
-/// `0x2` at `0x714bdb`, `0x4` at `0x714a6e` alone / `0x714a18` combined with `0x2`.
+/// Bone flags `0x1/0x2/0x4`, ignore parent translate/scale/rotate: for a non-root bone with
+/// `flags & 7` (`0x714961`) the reference rebuilds the parent matrix from the model root, pivot
+/// kept (`0x71496d..0x714d0c`), then billboards as usual. Legs: `0x1` at `0x714c92`, `0x2` at
+/// `0x714bdb`, `0x4` at `0x714a6e` alone and `0x714a18` with `0x2`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ParentArm {
-    /// `0x1` — the bone's frame is placed at the model root's origin instead of at the pivot its
-    /// animated parent carried it to.
+    /// `0x1`: the frame sits at the model root's origin, not the animated parent's pivot.
     pub ignore_translate: bool,
-    /// What `flags & 0x6` does to the parent's basis.
     pub basis: ParentBasis,
 }
 
-/// The `flags & 0x6` leg of [`ParentArm`] — what happens to the parent matrix's three basis
-/// vectors. (The reference works in row-major/row-vector form, so its "row K" is our column K:
-/// both name the image of model basis vector K, which is what every leg operates on.)
+/// The `flags & 0x6` leg: the parent's basis vectors (the reference's row K is our column K).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ParentBasis {
-    /// `flags & 6 == 0` (so `flags & 7 == 1` alone): the parent's basis is kept as-is.
+    /// `flags & 6 == 0`: the parent's basis as-is.
     Keep,
-    /// `flags & 6 == 2` — ignore parent scale: each basis vector is normalized, direction kept.
+    /// `flags & 6 == 2`, ignore parent scale: each basis vector normalized.
     UnitNormalize,
-    /// `flags & 6 == 4` — ignore parent rotation: the ROOT's direction with the parent's
-    /// magnitude (`0x714a6e`'s per-axis `|P_k| / |R_k|` ratio).
+    /// `flags & 6 == 4`, ignore parent rotation: root directions, parent lengths (`0x714a6e`).
     RootDirection,
-    /// `flags & 6 == 6` — ignore parent rotation AND scale: the root's basis outright
-    /// (`0x714a18`). Every vanilla player mount's rider seat is this or [`Self::RootDirection`],
-    /// which is why the saddle translates with the gallop and never rotates.
+    /// `flags & 6 == 6`: the root's basis (`0x714a18`). Every player mount's rider seat is this or
+    /// [`Self::RootDirection`], so the saddle never rotates.
     RootBasis,
 }
 
 impl ParentArm {
-    /// The arm an M2 bone's flag word authors, `None` when `flags & 7 == 0` (the ordinary bone,
-    /// which goes straight to the billboard selector — `je 0x714d0f`).
+    /// The arm a bone's flags author; `None` goes straight to the billboard selector (`0x714d0f`).
     pub fn from_bone_flags(bits: u32) -> Option<Self> {
         if bits & 0x7 == 0 {
             return None;
@@ -144,27 +106,20 @@ impl ParentArm {
     }
 }
 
-/// A bone **scale track driven by a global sequence** — the looping "breathe" pulse a glow card rides.
-/// VERIFIED mechanism: the Lamppost glow card sits on a spherical-billboard bone whose scale track
-/// (`interp=1`, `gseq=0`) oscillates `0.86 … 1.04` over the model's 1333 ms global sequence, so the
-/// card grows/shrinks — read as a brightness pulse. The clock is the `m2_animate` Phase-B rule
-/// (wow-5875-re): `gseq_time = elapsed_ms % duration`, then a linear lerp between adjacent keys. Only
-/// **global-sequence** tracks are captured here (they loop with zero arming, the static-doodad case);
-/// a `gseq == 0xffff` track needs the armed-animation machinery we don't run for static props.
+/// A bone scale track on a global sequence, the pulse a glow card rides (the lamppost's
+/// `0.86..1.04` over 1333 ms), sampled at the scene clock less the instance's attach time, mod the
+/// duration (`0x714352`).
 #[derive(Debug, Clone)]
 pub struct BoneScaleAnim {
-    /// Global-sequence loop length (ms). Sampling wraps at this period.
     pub duration_ms: u32,
-    /// Linear interpolation between keys (`interp != 0`); `false` = step.
+    /// Linear interpolation between keys (`interp != 0`); `false` steps.
     pub interp: bool,
-    /// `(timestamp_ms, scale_xyz)` keyframes, in file order (ascending time).
+    /// `(timestamp_ms, scale_xyz)`, time-ascending.
     pub keys: Vec<(u32, [f32; 3])>,
 }
 
 impl BoneScaleAnim {
-    /// Sample the scale at `time_ms` (wrapped into `[0, duration_ms)`), linearly interpolating between
-    /// the bracketing keys (or stepping when `interp == false`). Mirrors `m2_track_search` + the linear
-    /// sampler leg for the static-doodad / global-sequence case.
+    /// The scale at `time_ms` mod the duration, by the key search `0x713d50` and its linear leg.
     pub fn sample(&self, time_ms: u32) -> [f32; 3] {
         let n = self.keys.len();
         if n == 0 {
@@ -174,7 +129,6 @@ impl BoneScaleAnim {
         if t <= self.keys[0].0 {
             return self.keys[0].1;
         }
-        // Last key whose timestamp is ≤ t (keys are time-ascending).
         let mut k = 0;
         while k + 1 < n && self.keys[k + 1].0 <= t {
             k += 1;
@@ -197,59 +151,31 @@ impl BoneScaleAnim {
     }
 }
 
-/// A bone that **spins rigidly**: a parentless bone whose armed sequence keys ROTATION only, so every
-/// vertex weighted wholly to it moves as a rigid body about the pivot — `T(pivot) · R(t) · T(−pivot)`
-/// — with no skinning palette and no joint hierarchy involved.
-///
-/// This is the same "rigidly separable bone ⇒ per-batch transform" reading the billboard card split
-/// already makes ([`Billboard`], and `separable_billboard_bones`' two conditions), applied to an
-/// authored rotation instead of a camera-facing one. It is a **narrow** claim on purpose, and every
-/// clause is load-bearing:
-///
-/// - **Parentless.** With a parent, the bone's world motion is its parent's chain composed with its
-///   own, which is not a single rigid transform unless the whole chain is static. A parented bone is
-///   simply not collected — it holds its bind pose, the conservative failure.
-/// - **Rotation only.** A translation or scale track on the same bone would still be rigid, but the
-///   pivot-conjugated form below would be wrong, so those bones are not collected either.
-/// - **Wholly-weighted geometry** is the caller's half: a vertex split between this bone and another
-///   is half a rigid body's worth of motion, which no rigid transform can produce.
-///
-/// The population this exists for: `CavernsOfTimeSky.m2`'s three asteroid belts (bones 1/2/3, each
-/// parentless, each keying rotation alone over one 66.667 s loop — 25°, 90° and a full 360°), whose
-/// four batches are each `[bone@1.00]` across every vertex (`benilla-extract m2batch`).
+/// A parentless bone whose armed sequence keys rotation only: geometry wholly on it turns rigidly,
+/// `T(pivot) · R(t) · T(−pivot)`, with no palette (`CavernsOfTimeSky.m2`'s asteroid belts). Whole
+/// weighting is the caller's check.
 #[derive(Debug, Clone, PartialEq)]
 pub struct BoneSpin {
-    /// The bone's pivot, model space (WoW axes) — the rotation centre.
+    /// The rotation centre, WoW model space.
     pub pivot: [f32; 3],
-    /// The armed sequence's duration (**seconds**). Sampling wraps at this period.
+    /// The armed sequence's length in seconds.
     pub duration: f32,
-    /// Linear interpolation between keys; `false` = step (the track's `interp_type == 0`). Read from
-    /// the rotation track's own header word because [`BoneKeys`] — this collector's source for the
-    /// keys themselves — deliberately drops it, and a step track lerped is a real divergence
-    /// (`benilla-extract bonescan`'s recorded residual). There is no reason to reproduce that here.
+    /// `false` steps (`interp_type == 0`), read from the track header as `BoneKeys` lacks it.
     pub interp: bool,
-    /// `(seconds, [x, y, z, w])` keyframes, rebased to the sequence start, time-ascending. The
-    /// quaternion is raw WoW model space — conjugate it into the render basis at the use site.
+    /// `(seconds, [x, y, z, w])`, time-ascending, raw WoW model space.
     pub keys: Vec<(f32, [f32; 4])>,
 }
 
 impl BoneSpin {
-    /// Sample the rotation at `time` seconds (wrapped into `[0, duration)`), **slerping** between the
-    /// bracketing keys — the rotation analogue of [`BoneScaleAnim::sample`], with the same search,
-    /// the same step leg, and the same clamp past the final key.
-    ///
-    /// Clamping rather than wrapping around to key 0 is what the track actually says: an M2 track's
-    /// keys live inside the sequence band and the client interpolates within it, so a loop whose last
-    /// key is not its first snaps at the wrap. That is authored — `CavernsOfTimeSky` bone 1 runs 0° →
-    /// 25° and snaps back — and inventing a wrap-around segment would be us animating, not the file.
+    /// The rotation at `time` mod the duration, slerped as [`BoneScaleAnim::sample`] lerps. Past
+    /// the last key it clamps, so a loop snaps back as authored (`CavernsOfTimeSky` bone 1).
     pub fn sample(&self, time: f32) -> [f32; 4] {
         const IDENTITY: [f32; 4] = [0.0, 0.0, 0.0, 1.0];
         let n = self.keys.len();
         if n == 0 {
             return IDENTITY;
         }
-        // `rem_euclid` rather than `%`: a negative cursor (a clock read before the anchor) must land
-        // inside the loop, not mirror onto its first key.
+        // `rem_euclid`, not `%`: a cursor read before the anchor must land inside the loop.
         let t = if self.duration > 0.0 {
             time.rem_euclid(self.duration)
         } else {
@@ -272,12 +198,7 @@ impl BoneSpin {
     }
 }
 
-/// Shortest-arc spherical interpolation of two quaternions, on plain arrays.
-///
-/// Hand-rolled because `benilla-formats` deliberately carries no math crate — the render basis (and
-/// with it `glam`) starts at `benilla-assets`. Two guards earn their place: negating `b` when the dot
-/// is negative takes the SHORT way round (without it a 360° track's second half spins backwards), and
-/// falling back to a normalised lerp for near-parallel keys avoids `acos`'s vanishing `sin` denominator.
+/// Shortest-arc slerp on plain arrays (`benilla-formats` carries no math crate).
 fn slerp(a: [f32; 4], b: [f32; 4], t: f32) -> [f32; 4] {
     let mut dot = (0..4).map(|i| a[i] * b[i]).sum::<f32>();
     let mut b = b;
@@ -305,39 +226,22 @@ fn slerp(a: [f32; 4], b: [f32; 4], t: f32) -> [f32; 4] {
     q
 }
 
-/// A batch attached to an M2 **billboard bone**: the real client re-orients the bone to the camera
-/// every frame (so the card is visible from all sides and tracks the viewer). `pivot` is the bone's
-/// pivot in model space (WoW axes) — the point the card rotates about.
+/// A batch on an M2 billboard bone, turned to the camera about `pivot` (WoW model space).
 #[derive(Debug, Clone)]
 pub struct Billboard {
     pub pivot: [f32; 3],
-    /// The billboard bone's index in the model's bone table — the joint the card rides on an
-    /// animated host (the swinging lamp, the mount's lights). The pivot above is this bone's.
+    /// The joint the card rides on an animated host (a swinging lamp).
     pub bone: u16,
     pub kind: BillboardKind,
-    /// The billboard bone's global-sequence scale animation (the looping glow-card pulse), if any.
-    /// `None` for a static billboard bone.
     pub scale_anim: Option<BoneScaleAnim>,
-    /// The billboard bone's **translation** loops, one per sequence that keys it: `(anim id, the
-    /// keys inside that sequence's band, rebased to it)`. Same keyed-Vec3-loop shape as
-    /// [`BoneScaleAnim`] (values are offsets, WoW axes, not scales). The client's one-time load arm
-    /// plays anim **0** (the questgiver `?` marker's bob); the marker re-arms anim **190** — the
-    /// authored *raised* bob — while the unit shows an overhead name (wow-re `questgiver-marker.md`
-    /// Q4). A sequence whose band holds ≤1 key gets no entry; a global-sequence track gets none at
-    /// all. Only the **marker spawn site arms these** today; placed doodads' cards stay static-pivot
-    /// (the billboard half of the 0130 phase-4 bone-ride work owns that arming).
+    /// Translation loops `(anim id, band keys)`: anim 0 the questgiver bob, 190 its raised form
+    /// under an overhead name (`0x6076c0`). Only the marker spawn site arms them.
     pub seq_translations: Vec<(u16, BoneScaleAnim)>,
 }
 
-/// A WMO group render batch's **MOBA section** — the first `transBatchCount` batches of a group are
-/// TRANS, then `intBatchCount` INT, then EXT (MOGP header counts at `+0x28/+0x2a/+0x2c`, right after
-/// the byte-verified portal-ref span; cross-checked against NSabbey groups 1/3, whose per-class batch
-/// index counts match the reference client's observed draws batch-for-batch). The class picks an
-/// interior group's lighting law (wow-re `trace-forensics-abbey-interior-d3d` §2, observed on the
-/// abbey at close range): **INT draws once, UNLIT — pure `tex × MOCV`, no exterior light, no
-/// points**; **TRANS draws as a per-vertex MOCV-**alpha** lerp between the day/night-lit surface and
-/// that unlit bake** (the reference does it as two passes; one pass computes the same product);
-/// **EXT takes the ordinary exterior day/night law**.
+/// A WMO group batch's MOBA section (the TRANS, INT, EXT runs of MOGP `+0x28/+0x2a/+0x2c`). In an
+/// interior group INT draws unlit `tex × MOCV`, TRANS lerps by MOCV alpha from the lit surface to
+/// that bake, and EXT is lit as outdoors, as captures of the reference show.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum WmoBatchClass {
     Trans,
@@ -345,13 +249,9 @@ pub enum WmoBatchClass {
     Ext,
 }
 
-/// The batch's fog COLOUR policy — the per-blend fog table of the M2 batch state setter
-/// (`0x70baf0`, table `DAT_811fc4` dispatched at `0x70bddf`; wow-re rf-weather-emission-timeline
-/// ROUND 4): opaque/alpha-key/alpha fog toward the scene day-night colour; Add/AddAlpha toward
-/// BLACK (an additive batch FADES with distance/veil instead of adding grey — the storm-veil
-/// level-up fix); Mod toward WHITE; Mod2x toward GREY-128. Render flag 0x02 (`0x70bb24`) — or a
-/// dead scene fog — disables fog outright. Discriminants are the shader encoding (Scene = 0 so
-/// every non-M2 material defaults to the ordinary scene fog).
+/// The fog colour of the batch state setter (`0x70baf0`, table `DAT_811fc4` at `0x70bddf`): the
+/// scene's, black for Add, white for Mod, grey for Mod2x, off under render flag 0x02 (`0x70bb24`).
+/// Discriminants are the shader encoding.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
 pub enum FogPolicy {
     #[default]
@@ -362,237 +262,121 @@ pub enum FogPolicy {
     Off = 4,
 }
 
-/// One render batch: self-contained geometry + its material.
+/// One render batch: self-contained geometry and its material.
 #[derive(Debug, Clone)]
 pub struct RenderSubmesh {
     pub positions: Vec<[f32; 3]>,
-    /// Authored per-vertex normals (model space, parallel to `positions`). WoW lights foliage with
-    /// these soft outward normals; recomputing flat per-face normals makes crossed canopy planes
-    /// catch the sun harshly. Empty only if the source had none (then the renderer recomputes).
+    /// Authored normals: WoW lights foliage by these soft normals, where flat ones light crossed
+    /// canopies harshly. Empty if the source has none, and the renderer computes them.
     pub normals: Vec<[f32; 3]>,
     pub uvs: Vec<[f32; 2]>,
     pub indices: Vec<u32>,
-    /// Texture (`.blp`) for this batch, if any. `None` for an unfilled creature skin slot — see
-    /// [`Self::skin_slot`], which the spawn site uses to fill it from the display's variation.
+    /// `None` for an unfilled creature skin slot ([`Self::skin_slot`]).
     pub texture: Option<String>,
-    /// The creature skin variation this batch draws from (`Some(0/1/2)` ⇒ `Monster1/2/3`), so a caller
-    /// that loaded the model without skins (the doodad/asset-loader path) can fill the texture at spawn
-    /// from `CreatureDisplayInfo`. `None` for a hardcoded/embedded texture (most M2s; all WMOs).
+    /// `Monster1/2/3` as `Some(0/1/2)`, for a skin-less load to fill at spawn.
     pub skin_slot: Option<u8>,
-    /// The batch's `skinSectionId` (geoset / mesh-part ID) — `group*100 + variant`. The character
-    /// compositor selects which geosets are visible by this (hide all but the chosen hair/facial/body
-    /// variants); `0` for a model with a single unnamed geoset (most creatures, all doodads/WMO).
+    /// The `skinSectionId` (`group*100 + variant`) the character compositor shows geosets by.
     pub geoset_id: u16,
-    /// A character body texture the client fills at runtime from the appearance ([`CharSkinSlot`]) — the
-    /// M2 record carries the texture *type* but no embedded path, so the spawn site swaps a per-player
-    /// material onto this batch. `None` for everything that carries its own texture (most M2s, all WMOs).
     pub char_slot: Option<CharSkinSlot>,
     pub blend: ModelBlend,
-    /// Sampler address mode from the M2 texture record's `flags` (`0x1` = repeat U, `0x2` = repeat V;
-    /// clear = **clamp to edge**). Not a tiling detail — a *silhouette* one. Content authors a cutout
-    /// card's UVs deliberately outside `0..1` so the margin clamps to the texture's transparent border
-    /// and the card fades to nothing; sampled with repeat instead, that margin wraps into the opaque
-    /// middle of the sheet and draws as solid geometry with a hard seam at the wrap (decision 0763,
-    /// bugs B52/B96). `true`/`true` for WMO, which carries its own material flags and keeps today's
-    /// behaviour.
+    /// Address mode from the texture record (`0x1` repeat U, `0x2` repeat V, else clamp): a cutout
+    /// card's margin must clamp to its transparent border, not wrap into the opaque middle. WMO
+    /// always repeats.
     pub wrap_x: bool,
     pub wrap_y: bool,
-    /// Render both faces (no backface culling)? From the M2 material's `0x04` flag (WMO: kept `true`
-    /// for now). When `false` the batch is single-sided like the real client — visible from one side.
+    /// M2 material flag `0x04` or MOMT UNCULLED `0x04`; without it the reference culls back faces.
     pub two_sided: bool,
-    /// Per-vertex **skeletal skin binding** (decision 0019), parallel to `positions`: the 4 bone
-    /// indices each vertex is weighted to. They are **global M2 bone-array indices**, used directly as
-    /// joint indices (the skinned-entity path builds one joint entity per bone, in order). **Empty**
-    /// for WMO and for the static doodad/GameObject mesh (which never skins); populated by the M2 path.
+    /// Per-vertex skin: 4 global M2 bone indices, used as joint indices; empty for WMO.
     pub joints: Vec<[u16; 4]>,
-    /// Per-vertex skin **weights** (normalised to sum 1.0), parallel to [`Self::joints`]. Empty when
-    /// `joints` is.
+    /// Summing to 1, parallel to [`Self::joints`].
     pub weights: Vec<[f32; 4]>,
-    /// Per-vertex **MOCV** colour (RGBA, alpha forced 1.0), parallel to `positions`. WMO groups carry
-    /// it — the baked shade. On EXTERIOR groups it modulates the lit factor (`tex × MOCV × (ambient +
-    /// sun·N·L)`); on INTERIOR groups (see [`Self::interior`]) it *is* the lighting — the reference runs
-    /// the FFP with the directional sun off, so the baked MOCV carries the room. **Empty** for M2 (no
-    /// MOCV) and for WMO groups lacking it → the renderer treats absent colour as white (no tint).
+    /// Per-vertex colour. WMO: the MOCV bake, modulating light outdoors and being the light
+    /// indoors ([`Self::interior`]), its alpha lighting data on interior TRANS/INT batches and 1
+    /// elsewhere. M2: the constant M2Color tint. Empty is untinted.
     pub vertex_colors: Vec<[f32; 4]>,
-    /// This batch belongs to a WMO **interior** group. The real 1.12.1 client branches the per-group
-    /// render path on `groupFlags & 0x48` (binary-verified at `0x6b3f90`): the EXTERIOR/"exterior-lit"
-    /// bits `0x8 | 0x40`. With neither set (`== 0`) the group is a true interior, lit by its baked MOCV
-    /// with the directional sun **off**; with either set it takes the exterior (sun N·L) path. The exact
-    /// gx-layer combine is not yet byte-pinned (the gx FFP functions aren't decompiled), so the interior
-    /// combine + this branch direction are confirmed *visually*, not from the binary, for now. Always
-    /// `false` for M2.
+    /// A WMO interior-group batch: with neither exterior bit of `groupFlags & 0x48` (`0x6b3f90`),
+    /// lit by its MOCV with the sun off. The combine is matched to captures; its gx layer is
+    /// untraced.
     pub interior: bool,
-    /// This batch is **unlit** — rendered without scene lighting so it shows at full texture
-    /// brightness. For **M2** it's the material `UNLIT (0x01)` flag (lamp glass, window panes, glow
-    /// cards). For **WMO** it's MOMT `UNLIT (0x01)` on an **exterior-group** batch only — the
-    /// exterior drawer keys lighting per material (`rs 0xE = !(flags & 1)`, unlit ⇒ `tex × white`),
-    /// while the interior drawer IGNORES the flag: lit/unlit there is dictated by the batch section
-    /// alone ([`Self::wmo_batch`]). Byte law: wow-re `wmo-lit-selector` §1.2/§1.3.
+    /// Unlit: M2 material flag `0x01`, or MOMT `0x01` on exterior WMO batches only; the interior
+    /// drawer (`0x6b5190`) ignores it and lights by section, the exterior one (`0x6b4f10`) per
+    /// material.
     pub emissive: bool,
-    /// This batch's texture record is **type 14 — the icon slot**: no file of its own, filled at
-    /// runtime by `Model:ReplaceIconTexture` (`0x710ec0` swaps every type-14 handle on the
-    /// instance). The shipped user is `Interface\ItemAnimations\ForcedBackpackItem.m2`, the
-    /// bag buttons' item-push card, whose one batch is the pushed item's icon (decision 2008).
-    /// `false` for every other batch and all of WMO.
+    /// Texture type 14, filled by `Model:ReplaceIconTexture` (`0x710ec0`), as on the bag buttons'
+    /// item-push card `ForcedBackpackItem.m2`.
     pub icon_slot: bool,
-    /// The MOMT **SIDN** (`0x10` — self-illum day/night) authored colour, RGB gamma bytes: the
-    /// windows-glow-at-night mechanism. The real client scales it per frame by the night fraction
-    /// (1 overnight, 0 all day, ramping 20:30→21:30 and 06:00→07:00) and binds it as the GL material
-    /// EMISSION, which the FFP adds **inside** the lit sum before the texture modulate —
-    /// `tex × (lit + sidn·night)`. A GL_LIGHTING term, so it contributes on LIT lanes only (dead on
-    /// an unlit INT batch, and under `UNLIT` where lighting is off). `None` for M2 and non-SIDN WMO
-    /// materials. Byte law: wow-re `wmo-interior-night-light` §3/§4, updater `0x6b4090`.
+    /// MOMT SIDN (`0x10`) colour, RGB gamma bytes: the windows' night glow. The reference scales it
+    /// by the night fraction (ramping 20:30→21:30 and 06:00→07:00) into the GL emission inside the
+    /// lit sum, `tex × (lit + sidn·night)`, so lit batches only (`0x6b4090`).
     pub sidn: Option<[u8; 3]>,
-    /// MOMT **WINDOW** (`0x20`): in the **interior** drawer this batch swaps GL_LIGHT0 to the
-    /// brighter interior pair — ambient AND diffuse = the midpoint of the Direct and Ambient
-    /// day/night bands (ambient +16/255, saturating) — install → draw → restore, per batch. The
-    /// exterior drawer has no WINDOW machinery, so the flag only acts on interior-group batches.
-    /// This is the bright warm pane seen from inside a building (wow-re `wmo-interior-night-light`
-    /// §2, derivation `0x6d37e0`). `false` for M2.
+    /// MOMT WINDOW (`0x20`): the interior drawer lights the batch by the midpoint of the Direct and
+    /// Ambient bands (ambient +16/255), per batch (`0x6d37e0`).
     pub window: bool,
-    /// This batch blends **additively** — its colour is *added* to the framebuffer rather than mixed
-    /// with it (M2 blend mode `3` NoAlphaAdd / `4` Add). Glow cards, coronae, magic effects. Rendering
-    /// these as ordinary alpha-blend lets the (cool, at night) background bleed *through* and mute the
-    /// warm glow; additive preserves the authored hue. `false` for everything else (incl. all WMO for now).
+    /// M2 blend mode 3 or 4 (glow cards); alpha-blended instead, the background mutes the hue.
     pub additive: bool,
-    /// M2 render-flag **0x10 — disable depth write** for this batch. The real 1.12 client writes depth
-    /// for *every* batch (opaque or transparent) **unless** this bit is set (VERIFIED, wow-re
-    /// `m2-depth-blend-state`); benilla otherwise blanket-disables depth-write for the whole transparent
-    /// pass, so a model's own transparent cards bleed through / flicker from some angles. `false` for WMO
-    /// (its depth state is the standard opaque/transparent pass).
+    /// M2 render flag `0x10`; without it the reference writes depth for every batch (`0x70c190`).
     pub no_depth_write: bool,
-    /// M2 render-flag **0x08 — disable depth test** for this batch (it draws over everything, ignoring
-    /// occlusion). Rare; `false` for WMO.
+    /// M2 render flag `0x08`: drawn over everything.
     pub no_depth_test: bool,
-    /// The batch's fog COLOUR policy ([`FogPolicy`]) — `Scene` for WMO and every non-M2 batch.
     pub fog_policy: FogPolicy,
-    /// Set when this batch sits on an M2 **billboard bone** — the renderer faces it to the camera each
-    /// frame (around the bone pivot). `None` for ordinary geometry and all WMO batches.
     pub billboard: Option<Billboard>,
-    /// This batch holds geometry bound to a billboard bone the card split **refused** — one whose mesh
-    /// is welded to the rest of the model (`separable_billboard_bones`, decision 0839). No rigid
-    /// placement of such a batch exists: the reference blends it per vertex, so a lane that wants the
-    /// flap to bend must draw the **skinned** form through a joint palette (decision 0841). A lane
-    /// that draws it static gets it whole and still. `false` for every ordinary batch — including
-    /// every separable card, which is split out and faced rigidly — and for all WMO batches.
+    /// Geometry on a billboard bone the card split refused: the reference blends it per vertex, so
+    /// only a skinned draw bends it.
     pub welded_billboard: bool,
-    /// The batch's **animated material alpha** (decision 0130 phase 2): its time-varying colour-alpha
-    /// and/or transparency-weight loops, baked by [`mat_anim`](super::mat_anim). `None` when both
-    /// factors are static (baked/culled at build) — the overwhelming majority. The runtime multiplies
-    /// the sampled value into the instance's render alpha, per the verified combine (wow-re
-    /// `m2-alpha-combine-cull`).
+    /// Time-varying colour-alpha and transparency-weight loops ([`mat_anim`](super::mat_anim)),
+    /// multiplied into the render alpha as the reference combines them (`0x707680`).
     pub alpha_anim: Option<AlphaAnim>,
-    /// The batch's **UV-animation** loop (decision 0130 phase 3): the texture transform's
-    /// translation track baked by [`tex_anim`](super::tex_anim) — the raw `(x, y)` offset over the loop
-    /// clock. `None` for the ~98.6% of models with no texture transform, and for all WMO batches.
+    /// The texture transform's translation loop ([`tex_anim`](super::tex_anim)), raw `(x, y)`.
     pub uv_anim: Option<UvAnim>,
-    /// The batch's UV loop **per file sequence slot**, carried ONLY when the slots disagree — i.e.
-    /// when [`Self::uv_anim`]'s single loop cannot be right for every instance, because which loop
-    /// applies depends on which sequence that instance is playing (decision 1408, bug B98: the BRM
-    /// lava bubbles key their whole flipbook inside the 50 %-weighted variation 1, so slot 0 — the
-    /// only slot the shared-material registry can read — is a dead hold). `None` for every batch
-    /// whose slots agree, which is the shared lane unchanged.
+    /// The UV loop per file sequence slot, only when the slots disagree (BRM's lava bubbles key
+    /// their flipbook in variation 1, leaving slot 0 a dead hold).
     pub uv_seq: Option<SeqLoops<[f32; 2]>>,
-    /// The batch's texture-transform **rotation** loop per file sequence slot — the raw
-    /// quaternion keys ([`tex_anim::bake_uv_rot_seqs`](super::tex_anim::bake_uv_rot_seqs),
-    /// decision 2019), for the lanes that own a material per instance (the UI model tiles;
-    /// the cooldown indicator's sweep is this channel). `None` for a transform that never
-    /// rotates — every placed world doodad — and all of WMO.
+    /// The texture transform's rotation per slot, for lanes owning a material per instance (the UI
+    /// model tiles, the cooldown sweep).
     pub uv_rot_seq: Option<SeqLoops<[f32; 4]>>,
-    /// The batch's texture-transform **scaling** loop per file sequence slot (`(x, y)`), on the
-    /// same rule as [`Self::uv_rot_seq`].
+    /// The scaling loop per slot, as [`Self::uv_rot_seq`].
     pub uv_scale_seq: Option<SeqLoops<[f32; 2]>>,
-    /// The batch's **animated RGB tint** (the M2Color colour track, time-varying only — a spell
-    /// effect's white-hot flash cooling to red): baked by [`mat_anim`](super::mat_anim). When
-    /// `Some`, the static vertex-colour tint is **skipped** for this batch (the two would
-    /// double-apply); the renderer carries the tint on the material instead, seeded at the first
-    /// key and animated where the lane runs material animation. `None` for constant/keyless tints
-    /// (the static vertex bake, decision 0029) — the overwhelming majority.
+    /// The time-varying M2Color tint ([`mat_anim`](super::mat_anim)), carried on the material; the
+    /// static vertex tint is then skipped so the two never double-apply.
     pub rgb_anim: Option<RgbAnim>,
-    /// The tint twin of [`Self::uv_seq`], on the same rule and for the same reason.
+    /// The tint counterpart of [`Self::uv_seq`].
     pub rgb_seq: Option<SeqLoops<[f32; 3]>>,
-    /// The batch's MOBA section for WMO group batches ([`WmoBatchClass`] — TRANS / INT / EXT, the
-    /// per-class lighting law of an interior group). `None` for every M2 batch.
     pub wmo_batch: Option<WmoBatchClass>,
-    /// The M2 **skin-section index** this batch draws (`SkinBatch::skin_section_index`) — `None`
-    /// for every WMO batch, which has no such concept.
-    ///
-    /// Two batches of one model that name the SAME section rasterize the **same triangles**: a base
-    /// layer and the shine/reflect layer authored over it (`ARMORREFLECT3` on the ballista's bolt
-    /// heads and shields, `BALISTASHINE02` on the loose bolts — 264 sections across 221 world
-    /// doodads, `m2_shared_section`). The reference draws both from one vertex array under
-    /// depth-write + LEQUAL, so the later one wins the coplanar tie **exactly** (wow-re
-    /// `m2-depth-blend-state`). We only match that while both take the same vertex-transform path,
-    /// which is why the consolidators refuse a batch whose section they cannot take whole — see
-    /// `terrain_stream::spawn::assemble`.
+    /// The M2 skin section drawn. Two batches on one section rasterize the same triangles (a sheen
+    /// over its base); the reference draws both from one vertex array under LEQUAL, the later
+    /// winning exactly (`0x70c190`), so consolidators refuse a section they cannot take whole.
     pub section: Option<u16>,
-    /// This batch's texture coordinates are **GENERATED, not authored** — a sphere-map environment
-    /// coordinate derived per frame from the view-space reflection vector, not the vertex UVs
-    /// ([`benilla_m2::M2Model::stage_is_env_mapped`]: `texture_unit_lookup[texCoordSet] > 2`).
-    ///
-    /// The renderer must compute `uv = normalize(P − 2(P·N)N).xy · 0.5 + 0.5` in view space
-    /// instead of reading [`Self::uvs`], because on such a batch **there are no UVs to read**: the
-    /// artist leaves the whole mesh at a single point (`GnomeSubwayGlass.m2` — all 330 vertices at
-    /// exactly `(0,0)`) precisely because the runtime supplies them. Drawing it from the vertex
-    /// data paints the entire surface in one corner texel of a reflection sheet — the Deeprun Tram
-    /// glass tube's flat yellow (`AKGNOMEREFLECT.BLP` texel 0,0 = `225,221,142`, doubled by its
-    /// Mod2x blend). `false` for every WMO batch and for the M2 batches that name a real UV channel.
+    /// Texture coordinates generated as a view-space sphere map, not read from [`Self::uvs`]
+    /// (`texture_unit_lookup[texCoordSet] > 2`): `uv = normalize(P − 2(P·N)N).xy · 0.5 + 0.5`.
+    /// Such a mesh parks its UVs at one point (`GnomeSubwayGlass.m2`).
     pub env_map: bool,
 }
 
-/// A render batch that is a single flat **ground-plane quad**: four vertices sharing one authored
-/// horizontal plane at or hovering just above z = 0 (model space, WoW axes — the plane the
-/// model's owner stands on; hover ≤ [`GROUND_HOVER_MAX`]), forming an axis-aligned rectangle in
-/// model XY, every vertex fully weighted to one bone. This is the authoring pattern of
-/// ground-ring spell effects — Battle Shout's six crescents at exactly z = 0, Consecration's burn
-/// disc hovering at 0.207: flat quads at the owner's feet that bones slide, spin, and scale
-/// outward, and that sloped terrain buries per-pixel under a normal depth test (the batches
-/// author depth-test ON). The `groundscan` sweep (2026-07-14 z=0, 2026-07-31 hover; full 5875
-/// chain) measures the population: 128 of the 139 z=0 flat batches under `Spells\` plus the 108
-/// hovering discs are exactly this shape. The entity fx lane re-renders such parts as projected
-/// surface decals (`benilla::ground_fx`) so they drape the terrain like the selection ring does.
+/// A flat ground-plane quad: four vertices on one horizontal plane at or just above z = 0 (hover
+/// ≤ [`GROUND_HOVER_MAX`]), an axis-aligned XY rectangle wholly on one bone, as ground-ring spells
+/// author them (Battle Shout's crescents). The reference draws them as geometry slopes bury.
+/// Deviation: the fx lane redraws them as projected decals (`ground_fx`) so they drape the terrain.
 #[derive(Debug, Clone, Copy)]
 pub struct GroundQuad {
-    /// The M2 bone (global bone-array index) all four vertices skin to — the quad's animated
-    /// slide/spin/scale rides this joint. The consumer must pose corners through the joint's
-    /// matrix × the bone's inverse bindpose, exactly the skinned-vertex path.
+    /// Posed through the joint's matrix × the bone's inverse bind pose, as a skinned vertex.
     pub bone: u16,
-    /// The corners in **model space (WoW axes, z = 0)**, in bilinear rect order:
-    /// `(min_x, min_y)`, `(max_x, min_y)`, `(min_x, max_y)`, `(max_x, max_y)`.
+    /// WoW model space, in bilinear order: `(min_x, min_y)`, `(max_x, min_y)`, `(min_x, max_y)`,
+    /// `(max_x, max_y)`.
     pub corners: [[f32; 3]; 4],
-    /// The authored UV at each corner, parallel to [`Self::corners`].
     pub uvs: [[f32; 2]; 4],
-    /// The batch's **static M2Color tint** — the constant colour-track bake that rides
-    /// [`RenderSubmesh::vertex_colors`] on the mesh path — or white when the batch authors none.
-    ///
-    /// A decal consumer re-renders this quad from the corners and never touches its vertex buffer,
-    /// so without carrying the tint here the batch's whole colour is lost. That is load-bearing
-    /// exactly where `m2_batches` says it is: spell ground art is authored on the NEUTRAL
-    /// `GENERICGLOW*` radials, whose warmth lives entirely in this constant — `Flare_State_Base`'s
-    /// two 13.89-yd washes are white sheets tinted `(0.992, 0.467, 0.0)`, and an untinted additive
-    /// draw of them is a blown-white pool where the reference lays a dim orange one. A
-    /// *time-varying* track instead rides [`RenderSubmesh::rgb_anim`] and clears the vertex bake,
-    /// so this is white there and the two never double-apply.
+    /// The static M2Color tint, white when none: a decal redraws the quad from its corners, and
+    /// spell ground art on neutral `GENERICGLOW*` radials has no other colour.
     pub tint: [f32; 3],
 }
 
-/// Vertices further than this from the quad's own plane disqualify a batch as ground-plane flat
-/// (the real population authors exact planes; the epsilon only absorbs float noise).
+/// Vertices further than this from the quad's plane disqualify it; the art authors exact planes.
 const GROUND_FLAT_EPS: f32 = 0.01;
 
-/// The highest authored **hover** (uniform plane z, model space) a flat quad may sit at and
-/// still be the ground-plane shape. z = 0 is the majority authoring (Battle Shout's crescents);
-/// a minority hovers the disc just above the owner's ground plane to dodge terrain z-fighting.
-/// The `groundscan` hover census (2026-07-31, 5875 chain, `Spells\`) measures the population:
-/// 108 quad-shaped batches hover between 0.014 and 0.518 (the paladin aura/seal rings,
-/// Consecration's 0.207 disc, Flamestrike's 0.097 burn), then clear air up to 1.389 — the two
-/// `GreaterHeal_Low_Base` mid-body glow planes, which must NOT drape to the ground. 1.0 splits
-/// the gap.
+/// The highest plane z still ground-plane: hovering discs sit at 0.014..0.518, and the next plane,
+/// `GreaterHeal_Low_Base`'s mid-body glow at 1.389, must not drape.
 const GROUND_HOVER_MAX: f32 = 1.0;
 
-/// The empty batch — test scaffolding (a picker or dress test wants *a* `RenderSubmesh`, not a
-/// meaningful one). No geometry, `Opaque`, WMO-style repeat sampling; every flag at its
-/// nothing-authored value.
+/// The empty batch, for test scaffolding: nothing authored, `Opaque`, repeat sampling.
 impl Default for RenderSubmesh {
     fn default() -> Self {
         Self {
@@ -637,44 +421,22 @@ impl Default for RenderSubmesh {
 }
 
 impl RenderSubmesh {
-    /// Is this a **billboard card authored back-to-front** — one flat plane whose normal sits in the
-    /// −X half-space the billboard law points *away* from the camera?
-    ///
-    /// The billboard arm aims bone-local **+X** at the viewer (wow-re `billboard-bone-law.md` §2;
-    /// M2 bones carry no bind rotation, so bone-local == model space here), and 279 of the corpus's
-    /// 4424 billboard batches are wound and normalled the other way — the camera only ever sees the
-    /// card's back. The reference skins the normal through the same billboard-replaced palette row
-    /// as the position (`m2_vertex_skin 0x71a460`) and never flips one per face, so on those cards
-    /// its `max(N·L, 0)` runs off a normal pointing away from the viewer and the card's shading
-    /// swings with the CAMERA: bare ambient when the sun is behind you, full sun when you look into
-    /// it. Consumers light such a card off the side it presents instead (decision 0788).
-    ///
-    /// The planarity half is load-bearing: 3-D billboard geometry (the questgiver `?`'s 353 verts)
-    /// carries normals pointing every way, and flipping just its −X ones would gut its shading.
-    /// A card authored edge-on to the camera axis has no facing to correct, matching
-    /// `bbfacescan`'s away/edge-on split.
+    /// A billboard card authored back to front: one plane with its normal in the −X half-space,
+    /// away from the viewer the billboard arm aims bone-local +X at (`0x71547c`; M2 bones have no
+    /// bind rotation, so bone-local is model space). The reference skins that normal unflipped
+    /// through the same palette row (`0x71a460`). Deviation: consumers light such a card off the
+    /// side it presents, because the reference's shading of it is inverted and follows the camera.
     pub fn billboard_card_faces_away(&self) -> bool {
         self.billboard.is_some() && self.plane_normal().is_some_and(|n| n[0] < -Self::EDGE_ON_X)
     }
 
-    /// A normal whose |x| is under this is edge-on to the billboard law's camera axis: it faces
-    /// neither toward the viewer nor away, so there is nothing to decide.
+    /// A normal with |x| under this is edge-on to the camera axis: no facing to decide.
     const EDGE_ON_X: f32 = 1e-3;
 
-    /// The single plane every authored vertex normal of this batch shares — `None` when they do
-    /// not, i.e. the batch is **3-D geometry**, not a card.
-    ///
-    /// This is the gate that separates the two things a "billboard batch" can be, and getting it
-    /// wrong is expensive in both directions. A flat card has one facing, so which way it points
-    /// decides whether the reference ever shows it (decision 0629) and which side to light
-    /// (decision 0788). A closed solid — the questgiver `?`'s 353 verts, a pauldron's little
-    /// spike — has normals pointing every way: no single facing exists, backface culling can never
-    /// hide it, and a per-batch normal flip would gut its shading. Sampling *one* triangle of such
-    /// a batch and reporting the answer as the batch's facing is how decision 0836 concluded the
-    /// reference culls a shoulder flap it in fact draws.
+    /// The one plane every authored normal shares; `None` for 3-D geometry (the questgiver `?`),
+    /// which has no single facing.
     pub fn plane_normal(&self) -> Option<[f32; 3]> {
-        /// Cosine floor for "these two normals are the same plane" — one authored card, allowing
-        /// for unnormalised//soft-averaged authoring.
+        /// Cosine floor for "same plane", allowing for soft-averaged normals.
         const SAME_PLANE_COS: f32 = 0.999;
         let unit = |n: &[f32; 3]| {
             let l = (n[0] * n[0] + n[1] * n[1] + n[2] * n[2]).sqrt();
@@ -689,21 +451,13 @@ impl RenderSubmesh {
             .then_some(n0)
     }
 
-    /// Detect the flat **ground-plane quad** shape ([`GroundQuad`]) — `None` for everything that
-    /// isn't exactly it: more than four vertices, vertices off one shared horizontal plane, a
-    /// plane hovering above [`GROUND_HOVER_MAX`], a multi-bone or partial-weight skin, or corners
-    /// that don't form an axis-aligned XY rectangle. Billboard batches never match (their
-    /// geometry is camera-facing by construction, not ground-lying). Deliberately strict: the 11
-    /// `OTHER-FLAT` spell batches the population sweep found (Fist of Justice, IceNuke impact)
-    /// stay on the ordinary render path rather than stretch this shape.
+    /// The flat ground-plane quad, strictly: other flat spell batches (Fist of Justice, the IceNuke
+    /// impact) stay on the ordinary path.
     pub fn ground_quad(&self) -> Option<GroundQuad> {
         self.ground_quad_hover(GROUND_HOVER_MAX).map(|(q, _)| q)
     }
 
-    /// [`Self::ground_quad`] with the hover ceiling as a parameter, returning the plane's
-    /// authored z alongside the quad — the census entry point (`groundscan` passes `INFINITY` to
-    /// measure the whole hover population with the renderer's own shape test, so the instrument
-    /// cannot drift from the mechanism).
+    /// [`Self::ground_quad`] under any hover ceiling, with the plane's z (for `groundscan`).
     pub fn ground_quad_hover(&self, max_hover: f32) -> Option<(GroundQuad, f32)> {
         if self.billboard.is_some()
             || self.positions.len() != 4
@@ -713,9 +467,7 @@ impl RenderSubmesh {
         {
             return None;
         }
-        // One shared horizontal plane, at or hovering just above the owner's ground level. The
-        // corners keep their authored z: the decal projection drapes them onto the receiving
-        // surface regardless, exactly as it flattens the z = 0 majority.
+        // One horizontal plane; the corners keep their authored z, as the decal drapes them anyway.
         let hover = self.positions.iter().map(|p| p[2]).sum::<f32>() / 4.0;
         if !(-GROUND_FLAT_EPS..=max_hover).contains(&hover)
             || self
@@ -735,7 +487,7 @@ impl RenderSubmesh {
         {
             return None;
         }
-        // Axis-aligned rectangle: every vertex sits on a corner of the XY bounding box.
+        // An axis-aligned rectangle: every vertex on a corner of the XY bounding box.
         let (mut min, mut max) = ([f32::MAX; 2], [f32::MIN; 2]);
         for p in &self.positions {
             for a in 0..2 {
@@ -760,7 +512,7 @@ impl RenderSubmesh {
             } else if (p[0] - max[0]).abs() <= eps[0] {
                 1
             } else {
-                return None; // an x between the extremes — not a rectangle corner
+                return None; // an x between the extremes: not a corner
             };
             let sy = if (p[1] - min[1]).abs() <= eps[1] {
                 0
@@ -771,14 +523,13 @@ impl RenderSubmesh {
             };
             let slot = sy * 2 + sx;
             if filled[slot] {
-                return None; // two vertices on one corner — degenerate
+                return None; // two vertices on one corner
             }
             filled[slot] = true;
             corners[slot] = *p;
             uvs[slot] = *uv;
         }
-        // The batch's constant M2Color, straight off the vertex bake it would have drawn with
-        // (all four are the same colour — see [`GroundQuad::tint`]); white when it authors none.
+        // The constant M2Color off the vertex bake, which all four share; white when none.
         let tint = self
             .vertex_colors
             .first()
diff --git a/crates/benilla-formats/src/models/wmo/group.rs b/crates/benilla-formats/src/models/wmo/group.rs
index da92d364..c021d972 100644
--- a/crates/benilla-formats/src/models/wmo/group.rs
+++ b/crates/benilla-formats/src/models/wmo/group.rs
@@ -1,5 +1,5 @@
-//! WMO **group**-file parsing: the MOGP header + sub-chunks (doodad/light refs, footprint faces)
-//! and the render-batch → [`RenderSubmesh`] build against a parsed root.
+//! WMO group-file parsing: the MOGP header and sub-chunks, and the render batches built into
+//! [`RenderSubmesh`]es against a parsed root.
 
 use std::io::Cursor;
 
@@ -10,117 +10,52 @@ use super::{find_wmo_chunk, WmoRoot};
 use crate::liquid::{LiquidKind, LiquidMesh};
 use crate::models::{remap_submesh, ModelBlend, RenderSubmesh, WmoBatchClass};
 
-/// The MLIQ grid vertex spacing (world yards between adjacent grid vertices) — the reference's
-/// `[0x810cc0]` = `4.166666507720947` (`0x40855555`), VERIFIED wow-re. The liquid render dispatch
-/// `0x6b62e0` branches on the type nibble: **water** → `0x6b6420`/`0x6b6630`, magma/slime → `0x6b68f0`
-/// (wow-re `rf-mliq-liquid-uv-texgen.md`; the earlier `0x6b68f0` "water kernel" label was the magma
-/// path). Either kernel places grid vertex `(i, j)` at `base + (i·STEP, j·STEP)`.
+/// MLIQ grid spacing in yards, the reference's `[0x810cc0]` (`0x40855555`): the water
+/// (`0x6b6420`/`0x6b6630`) and magma/slime (`0x6b68f0`) kernels both place vertex `(i, j)` at
+/// `base + (i·STEP, j·STEP)`.
 const MLIQ_CELL_STEP: f32 = f32::from_bits(0x4085_5555);
 
-/// Yards per water-texture repeat: **one repeat per grid cell**, `MLIQ_CELL_STEP` ≈ 4.167 yd.
-///
-/// The reference's water kernel `0x6b6630` writes `u = (float)i`, `v = (float)j` — the raw integer
-/// tile indices, from loop counters that both start at a literal 0 (VERIFIED wow-re
-/// `liquid-uv-scroll-law.md`, a six-agent §5). One repeat per cell means every surface boundary
-/// lands on an exact repeat boundary, so a neighbour restarting at 0 is invisible: the seam-free
-/// look is the *scale*.
-///
-/// **This used to be `4 ×` that**, i.e. every WMO water surface in the game carried a texture four
-/// times too large, on a mechanism that was later refuted — the earlier note claimed seamlessness
-/// came from a world-anchored `GL_TEXTURE` matrix at transform index 8, but index 8 is the
-/// world/modelview transform and the water arms push no texture matrix at all. Decision 1271 carried
-/// the correction and deliberately did not apply it, the look being the director's call; B136 and
-/// the director's "Stormwind water seems too rough on the surface" are that call. The 4× cost more
-/// than size: it is exactly **two mip levels**, so the surface sat on mip 0 across the whole near
-/// field and never reached the authored chain that drops the sheet's peak ripple alpha 255 → 136 →
-/// 68 → a flat 51. Measured at the Stormwind canal before the fix, near water and mid-distance water
-/// had the same ripple contrast (σ 15.9 vs 15.2) — the ripple was not attenuating with distance at
-/// all.
-///
-/// We still anchor each vertex's UV to its **model-space position** rather than emitting the raw
-/// `(i, j)`. At one repeat per cell the two agree wherever surfaces are cell-aligned (they differ by
-/// a whole number of repeats, which `Repeat` wrapping erases), and where they are *not* aligned the
-/// position anchor is the one that does not seam.
-///
-/// Magma/slime have a separate correction still pending: the reference reads their `st` from the
-/// MLIQ vertex's authored `int16` pair × `1/256` (`movsx`, `0x6b6993`), which we do not parse at all
-/// and generate over this period instead.
+/// Yards per water-texture repeat: one per grid cell, as the reference's water kernel `0x6b6630`
+/// writes `u = (float)i`, `v = (float)j`. Deviation: the UV comes from the model-space position,
+/// not each surface's own `(i, j)`, because the two agree on cell-aligned surfaces and the position
+/// never seams where they are not. Magma and slime use this period too; the reference reads their
+/// UV from the vertex's authored `int16` pair × 1/256 (`0x6b6993`), which is not parsed.
 const MLIQ_UV_PERIOD: f32 = MLIQ_CELL_STEP;
 
-/// The **opacity ramp coordinate** fed to a WMO water vertex: its authored byte, normalised.
-///
-/// WMO liquid carries no bathymetry, so there is nothing to ramp by depth the way ADT MCLQ water is
-/// ramped — and the reference does not try. It indexes a 256-entry alpha ramp with the vertex's own
-/// byte 0 (`0x6b64c6 movzx`), and that ramp is a plain **linear** lerp between the zone's river
-/// shallow and deep alphas: `LUT[i] = (c0·256 + i·(c1 − c0)) >> 8`, rebuilt per frame, which for the
-/// static-init endpoints (0.5, 1.0) runs 127 → 191 → 254. **Not** the ADT path's
-/// `1.6·(i/63)^8` curve; the two systems do not even share a delivery mechanism (the ADT ramp is
-/// uploaded as a GPU texture and never CPU-indexed). VERIFIED wow-re
-/// `terrain/scratch/water-shading-law.md` §11 — including the refutation of a first reading that had
-/// the step sign-extended as a byte and the ramp *decreasing*.
-///
-/// So `byte / 255` is exactly the lerp coordinate our shader already applies to the shallow/deep
-/// alpha pair off the shared light buffer, and passing it through the existing per-vertex channel
-/// reproduces the reference's LUT without a second mechanism.
-///
-/// This replaces a hard `1.0` — the deep, fully-opaque endpoint, pinned for every WMO pool in the
-/// game because we believed those bytes were flow data. That pin is why Blackfathom's Pool of
-/// Ask'ar rendered as a sheet you cannot see through where the real client shows 9–15 yd of bottom
-/// (B136), and it was documented as "tunable; the exact shore LUT is deferred".
+/// A WMO water vertex's opacity-ramp coordinate, its authored byte 0 normalised: the reference
+/// indexes a linear LUT between the zone's river shallow and deep alphas with it (`0x6b64c6`,
+/// built by `0x6b6b60`), not the ADT `1.6·(i/63)^8` curve, and the shader's lerp reproduces it.
 fn wmo_water_alpha_v(opacity_byte: u8) -> f32 {
     f32::from(opacity_byte) / 255.0
 }
 
-/// MOGP `groupLiquid`'s sentinel: **this group holds no liquid of its own**. Any other value is the
-/// whole-group submersion override — see [`WmoGroupHeader::group_liquid`].
+/// MOGP `groupLiquid` for a group with no liquid of its own; any other value is the whole-group
+/// submersion override.
 pub const NO_GROUP_LIQUID: u32 = 0xf;
 
-/// The per-group fields the visibility pass reads from a **group file**'s MOGP header: the group
-/// `flags` (offset `0x08`) and the group's slice into [`super::WmoPortals::refs`]
-/// (`portal_ref_start` @ `0x24`, `portal_ref_count` @ `0x26`). VERIFIED layout (`grp+0x10` flags,
-/// `+0x2c`/`+0x30` ref span seeded from MOGP `+0x24`/`+0x26`). `None` if the bytes aren't a
-/// parseable group.
+/// A group's MOGP header fields. `flags` sits at `0x08` and the portal-ref slice at `0x24`/`0x26`,
+/// which the reference copies to `grp+0x10` and `+0x2c`/`+0x30`.
 #[derive(Debug, Clone, Copy)]
 pub struct WmoGroupHeader {
-    /// MOGP group flags. `& 0x8` = EXTERIOR (the outdoor bit the flood defers on); `& 0x48 == 0` =
-    /// a true interior group (see [`super::WmoGroupInfo`]).
+    /// `0x8` is exterior, the bit the portal flood defers on; `& 0x48 == 0` is interior.
     pub flags: u32,
-    /// First index into [`super::WmoPortals::refs`] for this group's portals.
+    /// First index of this group's portals in [`super::WmoPortals::refs`].
     pub portal_ref_start: u16,
-    /// Number of portal refs for this group.
     pub portal_ref_count: u16,
-    /// MOGP `uniqueID` @ `0x38` — this group's `WMOAreaTable.WMOGroupID` key (byte-verified
-    /// 2026-07-03: Chapel_000 interior → 478, matching its WMOAreaTable CAVE/ambience row).
-    /// `0` when the header is too short to carry it.
+    /// MOGP `uniqueID` at `0x38`, the group's `WMOAreaTable.WMOGroupID` key; 0 for a short header.
     pub area_table_id: u32,
-    /// MOGP fog indices @ `0x30` — four indices into the root's [`super::WmoFog`] table, walked by
-    /// the client's interior-fog selector (`0x69de20`, wow-re `rf-weather-emission-timeline`
-    /// ROUND 5). Offset pinned empirically against the Goldshire inn (its groups carry `[1,0,0,0]` /
-    /// `[0,0,0,0]` here — valid indices into its 2-record MFOG — while `uniqueID @0x38` and the
-    /// no-liquid sentinel `@0x34` self-validate the layout; see `tests/wmo_fogs.rs`).
-    /// `[0; 4]` when the header is too short to carry them.
+    /// MOGP fog indices at `0x30` into the root's [`super::WmoFog`] records, walked by the
+    /// reference's interior-fog selector `0x69de20`; the offset is fixed empirically
+    /// (`tests/wmo_fogs.rs`). Zero if the header is short.
     pub fog_indices: [u8; 4],
-    /// MOGP `groupLiquid` @ `0x34` — and `0xf` on all but **13 of the 5220 shipped group files**,
-    /// where it means "this group holds no liquid of its own".
-    ///
-    /// The other value is the client's **whole-group submersion override**: `0x6b9f10` reads it
-    /// first and, when it is not `0xf`, returns an unconditional hit — the raw value as the liquid
-    /// type, height `FLT_MAX`, **no Z compare and no MLIQ test at all**. That is how a flooded
-    /// tunnel or an underwater cave reads wet with no liquid grid in the file, and all 13 carry no
-    /// `MLIQ` chunk (census reproduced with our own reader; wow-re
-    /// `models/scratch/wmo-liquid-scoping.md` §5).
-    ///
-    /// [`super::wmo_group_liquid_mesh`] already reads the same word for a different purpose — it
-    /// overrides the *kind* of a grid that exists. This field is the other half: the groups where
-    /// there is no grid to override.
-    ///
-    /// `0xf` when the header is too short to carry it, which reads as "no liquid" — the safe way
-    /// round, since the override only ever adds water.
+    /// MOGP `groupLiquid` at `0x34`: [`NO_GROUP_LIQUID`] on all but 13 of the 5220 shipped group
+    /// files. Any other value makes the reference's `0x6b9f10` report the whole group submerged in
+    /// that liquid type, height `FLT_MAX`, with no Z or MLIQ test; none of the 13 has an MLIQ. A
+    /// short header reads as no liquid.
     pub group_liquid: u32,
 }
 
-/// Read one WMO **group** file's MOGP header fields used by the visibility pass (see
-/// [`WmoGroupHeader`]). The MOGP super-chunk's payload begins with the 68-byte group header.
+/// Read a group file's [`WmoGroupHeader`]; the MOGP payload opens with the 68-byte header.
 pub fn wmo_group_header(group_bytes: &[u8]) -> Option<WmoGroupHeader> {
     let mogp = find_wmo_chunk(group_bytes, b"PGOM")?; // MOGP
     if mogp.len() < 0x28 {
@@ -144,51 +79,33 @@ pub fn wmo_group_header(group_bytes: &[u8]) -> Option<WmoGroupHeader> {
     })
 }
 
-/// One interior WMO group's raw render triangles + per-vertex baked MOCV + per-triangle MOPY flags —
-/// the face set the interior FOOTPRINT sample walks. Its live consumer is the **GameObject M2**:
-/// the entity light node's env-update attach (`0x6717d0` → `0x69e4c0`, the entity twin of the
-/// ADT-MDDF `0x6a8410`) down-rays the group RENDER mesh (`MOVT`/`MOVI`/`MOPY`) under the object and
-/// bakes the hit's barycentric MOCV — floor-168/cap-96 — as its committed light (wow-re
-/// `wmo-lit-selector.md`; trace-decisive on the abbey INNBENCH draws, diffuse max exactly 168).
-/// `None` for a non-group, an exterior group, or a group without baked colours (never a footprint
-/// source). (First built for decision 0290's MODD reading, deleted by 0306 when MODD props turned
-/// out to use their own baked colour — resurrected now that the chain's true consumer is pinned.)
+/// An interior group's render triangles, per-vertex MOCV and per-triangle MOPY: the faces a game
+/// object's light attach (`0x6717d0` → `0x69e4c0`) down-rays, taking the hit's barycentric MOCV
+/// (floor 168, cap 96) as its light.
 #[derive(Clone)]
 pub struct FootprintTris {
-    /// Vertex positions, WMO model space (WoW axes).
+    /// Vertex positions, WMO model space.
     pub positions: Vec<[f32; 3]>,
-    /// Triangle list into [`Self::positions`] (MOVI order — MOPY is parallel per triangle).
+    /// Triangle list in MOVI order; the MOPY vectors run parallel, one entry per triangle.
     pub indices: Vec<u16>,
-    /// Per-vertex baked MOCV as RGB bytes, parallel to positions (bytes, not 0–1: the floor/cap
-    /// arithmetic is exact u8 fixed-point).
+    /// Per-vertex MOCV RGB, kept as bytes because the floor/cap arithmetic is exact u8 fixed-point.
     pub mocv: Vec<[u8; 3]>,
-    /// Per-TRIANGLE MOPY flags (`indices.len() / 3` entries). Bit `0x1` on the hit face selects the
-    /// day/night exterior colours as the object's base instead of the MOCV sample (§11's binary
-    /// selector).
+    /// Per-triangle MOPY flags; `0x1` on the hit face selects the day/night exterior colours
+    /// instead of the MOCV sample (`0x6b9a50`).
     pub mopy_flags: Vec<u8>,
-    /// Per-TRIANGLE MOPY **material id** (parallel to [`Self::mopy_flags`]) — the index into the
-    /// ROOT's MOMT, and through it the face's `TerrainType` (`WmoRoot::material_ground_types`).
-    /// This is the footstep surface's WMO leg: the client's material ray reads exactly this byte
-    /// off the hit face (`0x6a26fc`, wow-re `wmo-footstep-surface.md`).
-    ///
-    /// `0xFF` occurs on disk and is not an index — those faces all carry MOPY flag `0x08` and are
-    /// already dropped by [`FOOTPRINT_REJECT`] before anything can sample them. Consumers still
-    /// bounds-check: the client does not, the shipped assets simply never break the invariant.
+    /// Per-triangle MOPY material id, an index into the root's MOMT; the reference's footstep ray
+    /// reads it off the hit face (`0x6a26fc`). The on-disk `0xFF` non-index occurs only on faces
+    /// [`FOOTPRINT_REJECT`] drops; consumers still bounds-check.
     pub mopy_material: Vec<u8>,
 }
 
-/// The footprint ray's per-face MOPY reject mask (wow-re `unit-light-combine-storm.md`, the BSP
-/// face walk `0x6b92b0`/`0x6bc370`): a face with COLLISION `0x08` or VISITED `0x80` set is never a
-/// footprint candidate. This is what keeps a floor authored as coplanar layers (a RENDER|DETAIL
-/// sheet over a COLLISION sheet, observed on the Goldshire forge + inn) from being a per-position
-/// coin toss: only the render layer survives, so the sample is deterministic and regional.
+/// The footprint ray's MOPY reject mask (the reference's BSP walk `0x6b92b0`/`0x6bc370`): a
+/// collision (`0x08`) or visited (`0x80`) face is never a candidate, so of a floor's coplanar
+/// render and collision sheets only the render one is sampled.
 const FOOTPRINT_REJECT: u8 = 0x88;
 
-/// Parse one WMO **group**'s bytes into its footprint-sample face set ([`FootprintTris`]).
-/// `None` unless the bytes are a group, the group is INTERIOR (`flags & 0x48 == 0`), and it carries
-/// MOCV parallel to its positions. Faces matching [`FOOTPRINT_REJECT`] are dropped here (the
-/// client rejects them per-ray inside the BSP walk; the set is static, so filtering at build is
-/// equivalent and free).
+/// A group's [`FootprintTris`], `None` unless it is an interior group with MOCV parallel to its
+/// positions. Rejected faces drop at build: the set is static, so this equals the per-ray reject.
 pub fn wmo_group_footprint_tris(group_bytes: &[u8]) -> Option<FootprintTris> {
     let Ok(ParsedWmo::Group(group)) = parse_wmo(&mut Cursor::new(group_bytes)) else {
         return None;
@@ -225,13 +142,8 @@ pub fn wmo_group_footprint_tris(group_bytes: &[u8]) -> Option<FootprintTris> {
     })
 }
 
-/// Find a sub-chunk of a group file's **MOGP** super-chunk by on-disk (reversed) magic. The MOGP
-/// payload is the 0x44-byte group header followed by ordinary `[magic][size][data]` sub-chunks
-/// (MOPY/MOVT/…/MODR/MOLR); this walks them.
-///
-/// Clamps the last sub-chunk to the payload end for the same reason [`find_wmo_chunk`] does — and it
-/// is the same file: once MOGP itself is clamped to EOF, the sub-chunk that ran to the old declared
-/// end is now the short one, so a break here would just move `Undercity_144`'s loss one level down.
+/// Find a MOGP sub-chunk by its reversed magic, past the `0x44`-byte header. The last one clamps to
+/// the payload end as in [`find_wmo_chunk`], since a clamped MOGP leaves its last sub-chunk short.
 fn find_mogp_subchunk<'a>(group_bytes: &'a [u8], magic: &[u8; 4]) -> Option<&'a [u8]> {
     let mogp = find_wmo_chunk(group_bytes, b"PGOM")?;
     let mut off = 0x44usize; // past the fixed group header
@@ -248,11 +160,8 @@ fn find_mogp_subchunk<'a>(group_bytes: &'a [u8], magic: &[u8; 4]) -> Option<&'a
     None
 }
 
-/// A group's **MODR** doodad references: the MODD indices this group instantiates. This is the
-/// faithful doodad→group OWNERSHIP relation — the real client creates a WMO doodad per (MODD index,
-/// referencing group) from exactly this list (`0x695aa0` loops `group+0xe8`/count `+0x144`), and the
-/// owning group's interior class + MOLR light list decide the doodad's lighting (wow-re
-/// `trace-forensics-abbey-interior-d3d` §1.1/§4). Empty when the group has no MODR (no doodads).
+/// A group's MODR list, the MODD indices it owns: the reference creates one doodad per (index,
+/// group) from it (`0x695aa0`), lit by that group's interior class and MOLR lights.
 pub fn wmo_group_doodad_refs(group_bytes: &[u8]) -> Vec<u16> {
     find_mogp_subchunk(group_bytes, b"RDOM")
         .map(|c| {
@@ -265,11 +174,8 @@ pub fn wmo_group_doodad_refs(group_bytes: &[u8]) -> Vec<u16> {
         .unwrap_or_default()
 }
 
-/// A group's **MOLR** light references: the MOLT indices whose lights this group folds into its own
-/// doodads' committed light (`0x695c00` builds the per-group active-light list from exactly this; a
-/// group WITHOUT an MOLR chunk provably lights its doodads with nothing — the abbey's group 3 has
-/// none, and the director's stand receives zero point light, its own flame 3.7 yd away included).
-/// Empty when the group has no MOLR.
+/// A group's MOLR list, the MOLT lights its doodads receive (`0x695c00`); a group without one
+/// gives its doodads no point light at all.
 pub fn wmo_group_light_refs(group_bytes: &[u8]) -> Vec<u16> {
     find_mogp_subchunk(group_bytes, b"RLOM")
         .map(|c| {
@@ -282,18 +188,9 @@ pub fn wmo_group_light_refs(group_bytes: &[u8]) -> Vec<u16> {
         .unwrap_or_default()
 }
 
-/// Build one WMO **group**'s MLIQ liquid surface as a [`LiquidMesh`] in **WMO model space** (WoW
-/// axes, yards) — the flat animated water/lava/slime the group embeds (Stormwind's canals, the
-/// Ironforge lava, dungeon pools). `None` when the group carries no `MLIQ`, or the grid has no wet
-/// tiles / an unmapped type. The placement transform lifts the mesh into the world at spawn.
-///
-/// Faithful model (VERIFIED wow-re `rf-water-liquid-type-texture-material.md` + `rf-mliq-liquid-uv-texgen.md`;
-/// the render dispatch is `0x6b62e0`, water kernels `0x6b6420`/`0x6b6630`): grid vertex `(i, j)` sits
-/// at `base + (i·STEP, j·STEP, heights[j·xverts + i])`; a
-/// tile renders iff its flag low nibble `!= 0xf` (`0xf` = hole); the type is the group's
-/// `groupLiquid` override when set, else the per-tile nibble, mapped to a texture via
-/// [`LiquidKind::from_nibble`]. The whole surface takes ONE resolved kind (the reference resolves a
-/// single type per surface — `0x6ba970`), with per-tile hole membership.
+/// A group's MLIQ surface as a [`LiquidMesh`] in WMO model space, as the reference's dispatch
+/// `0x6b62e0` draws it: vertex `(i, j)` at `base + (i·STEP, j·STEP, heights[j·xverts + i])`, a
+/// tile drawn unless its low nibble is `0xf`, and one kind for the whole surface (`0x6ba970`).
 pub fn wmo_group_liquid_mesh(group_bytes: &[u8]) -> Option<LiquidMesh> {
     let Ok(ParsedWmo::Group(group)) = parse_wmo(&mut Cursor::new(group_bytes)) else {
         return None;
@@ -302,8 +199,7 @@ pub fn wmo_group_liquid_mesh(group_bytes: &[u8]) -> Option<LiquidMesh> {
     build_wmo_liquid_mesh(&lq, group.group_liquid)
 }
 
-/// Build the [`LiquidMesh`] for a parsed [`WmoLiquid`] grid + its group's `groupLiquid` override.
-/// Split out so a unit test can exercise it without synthesising a full group file.
+/// The [`LiquidMesh`] for a parsed [`WmoLiquid`] grid and its group's `groupLiquid`.
 fn build_wmo_liquid_mesh(lq: &WmoLiquid, group_liquid: u32) -> Option<LiquidMesh> {
     let (xv, yv, xt, yt) = (
         lq.xverts as usize,
@@ -311,7 +207,6 @@ fn build_wmo_liquid_mesh(lq: &WmoLiquid, group_liquid: u32) -> Option<LiquidMesh
         lq.xtiles as usize,
         lq.ytiles as usize,
     );
-    // The grid must be tile-consistent (`xtiles = xverts − 1`) and carry its full vertex/tile arrays.
     if xv < 2 || yv < 2 || xt + 1 != xv || yt + 1 != yv {
         return None;
     }
@@ -319,8 +214,7 @@ fn build_wmo_liquid_mesh(lq: &WmoLiquid, group_liquid: u32) -> Option<LiquidMesh
         return None;
     }
 
-    // Resolve ONE kind for the whole surface: the `groupLiquid` override when set (`!= 0xf`), else
-    // the first wet tile's nibble (`0x6ba970` returns the first non-hole nibble). Unmapped ⇒ None.
+    // One kind per surface: the `groupLiquid` override, else the first wet nibble (`0x6ba970`).
     let type_nibble = if group_liquid != NO_GROUP_LIQUID {
         (group_liquid & 0xf) as u8
     } else {
@@ -328,24 +222,19 @@ fn build_wmo_liquid_mesh(lq: &WmoLiquid, group_liquid: u32) -> Option<LiquidMesh
         first_wet
     };
     let kind = LiquidKind::from_nibble(type_nibble)?;
-    // Fullbright kinds read no ramp at all (their sheet IS the body), and their leading four vertex
-    // bytes are an authored int16 UV pair rather than an opacity — so the byte is meaningless there
-    // and the channel stays 0, a statement rather than a value.
+    // Fullbright kinds read no ramp and their vertex bytes are a UV pair: the channel stays 0.
     let water = !kind.is_fullbright();
 
-    // 2 tris per wet tile (low nibble `!= 0xf`). Winding is irrelevant (drawn two-sided). Built
-    // BEFORE the vertices because which vertices the triangles actually reference is what decides
-    // the substitution below.
+    // Two triangles per wet tile, drawn two-sided; built first, as `drawn` decides the fill below.
     let mut indices = Vec::with_capacity(xt * yt * 6);
     let mut wet = vec![false; xt * yt];
-    // The `0x80` "a neighbour also claims this cell" bit — kept per cell, gated model-wide later
-    // (see `LiquidMesh::shared`).
+    // `0x80`: a neighbour also claims the cell (gated model-wide in `LiquidMesh::shared`).
     let mut shared = vec![false; xt * yt];
     let mut drawn = vec![false; xv * yv];
     for ty in 0..yt {
         for tx in 0..xt {
             if lq.tile_flags[ty * xt + tx] & 0xf == 0xf {
-                continue; // hole — no liquid on this tile
+                continue; // a hole
             }
             wet[ty * xt + tx] = true;
             shared[ty * xt + tx] = lq.tile_flags[ty * xt + tx] & 0x80 != 0;
@@ -363,9 +252,7 @@ fn build_wmo_liquid_mesh(lq: &WmoLiquid, group_liquid: u32) -> Option<LiquidMesh
         return None; // grid present but every tile a hole
     }
 
-    // The height every **unreferenced** vertex is filled with — see the loop below. The lowest
-    // drawn height, so the substitute can never push the AABB past the geometry that is really
-    // there. `indices` is non-empty by the check above, so at least one drawn height exists.
+    // An undrawn vertex takes the lowest drawn height, so it never stretches the AABB.
     let fill_z = (0..xv * yv)
         .filter(|&n| drawn[n] && lq.heights[n].is_finite())
         .map(|n| lq.heights[n])
@@ -376,21 +263,9 @@ fn build_wmo_liquid_mesh(lq: &WmoLiquid, group_liquid: u32) -> Option<LiquidMesh
         lq.base[2]
     };
 
-    // Grid vertices (row-major `j·xverts + i`), WMO model space. Every vertex is emitted — hole
-    // corners included — so the tile indices line up.
-    //
-    // **A hole corner's authored height is not a height.** MLIQ carries a full `xverts × yverts`
-    // height array whether or not a tile is wet, and the shipped files leave the hole interiors at
-    // a literal `0.0`: Blackfathom g007 has 186 of 868 (its water sits at model z −58.28) and even
-    // Stormwind's canal g099 has 36 of 108 (water at −6.48). Emitting those verbatim is invisible in
-    // the draw — no triangle references them — but it stretches the Bevy mesh AABB from the flat
-    // sheet all the way to model z 0, i.e. 58 yd of phantom vertical extent on that one pool, and
-    // every AABB consumer (frustum culling first) then reasons about a box that is mostly nothing.
-    // (The comment that used to sit here claimed the opposite — "the AABB stays tight because WMO
-    // liquid heights are real, flat values" — which is false on both files above. The MCLQ path has
-    // always substituted for its own `FLT_MAX` sentinel for exactly this reason; WMO liquid needed
-    // the same treatment against a different degenerate value, and the robust test is *is this
-    // vertex drawn*, not *does its height look wrong*.)
+    // Every grid vertex is emitted, row-major, so the tile indices line up. An undrawn vertex's
+    // authored height is not a height: shipped files leave hole interiors at 0.0 (Blackfathom g007
+    // has 186 of 868, its water at z −58.28), which would stretch the AABB to z 0.
     let mut positions = Vec::with_capacity(xv * yv);
     let mut uvs = Vec::with_capacity(xv * yv);
     let mut depths = Vec::with_capacity(xv * yv);
@@ -407,13 +282,7 @@ fn build_wmo_liquid_mesh(lq: &WmoLiquid, group_liquid: u32) -> Option<LiquidMesh
             } else {
                 0.0
             });
-            // UV from the vertex's MODEL-SPACE position, NOT its per-surface tile index. A per-surface
-            // `(i·¼, j·¼)` resets to 0 at each surface's origin; a surface's tile count is arbitrary
-            // (Stormwind g099 is 11 tiles = 2.75 repeats), so that reset lands mid-texture and SEAMS at
-            // every surface boundary. Dividing the shared model-space position by the repeat period
-            // ties all of a WMO's MLIQ surfaces to ONE continuous UV field, so grid-aligned neighbours
-            // tile seamlessly. (Same per-cell ¼ step as before — `i·STEP/period = i·¼` — plus the
-            // `base/period` offset that couples the surfaces.)
+            // UV from the model-space position, one field for all surfaces (`MLIQ_UV_PERIOD`).
             uvs.push([mx / MLIQ_UV_PERIOD, my / MLIQ_UV_PERIOD]);
         }
     }
@@ -425,40 +294,32 @@ fn build_wmo_liquid_mesh(lq: &WmoLiquid, group_liquid: u32) -> Option<LiquidMesh
         uvs,
         depths,
         indices,
-        // The `0x6ba970`-resolved nibble (groupLiquid override / first wet tile) IS the WMO
-        // surface's sound class — the ambient-loop key (see `LiquidMesh::sound_nibble`).
+        // The resolved nibble is also the surface's ambient-sound key.
         sound_nibble: type_nibble,
-        // How an interior pool finds its body colour: MOMT lives in the ROOT, so the group file
-        // cannot resolve it and the spawner does (see `liquid::surface::spawn_wmo_liquids`).
+        // The body colour's MOMT index; MOMT is in the root, so the spawner resolves it.
         material_id: Some(lq.material_id),
         kind,
     })
 }
 
-/// Where the bright-doorway fade stops: a vertex `≥ 6.6667` yd from every exterior-neighbour portal
-/// keeps its authored bake (`[0x811110]`, VERIFIED off `.rdata`).
+/// The bright-doorway fade's reach in yards (`[0x811110]`): a vertex farther from every exterior
+/// portal keeps its bake.
 const DOORWAY_FADE_REACH: f32 = 6.666_666_5;
 
-/// The per-yard fade slope: `t = 1 − 0.15·dist` (`[0x7ffd6c]`, VERIFIED).
+/// The fade's per-yard slope, `t = 1 − 0.15·dist` (`[0x7ffd6c]`).
 const DOORWAY_FADE_SLOPE: f64 = 0.15;
 
-/// The plane epsilon inside the distance kernel (`0x6c4240`): a vertex within `1/6` yd of a portal's
-/// plane reports distance **0** — the "standing in the doorway" case, which whitens outright.
+/// The distance kernel's plane epsilon in yards (`0x6c4240`): a vertex this close to a portal's
+/// plane, inside its outline, is at distance 0 and whitens outright.
 const PORTAL_PLANE_EPS: f32 = 1.0 / 6.0;
 
-/// The reference's float→fixed magic bias: the f32 sum's BIT pattern is shifted `>> 14`, never
-/// numerically converted, so the byte falls out of the mantissa's low byte (`[0x8029cc]`).
+/// The reference's float-to-fixed bias (`[0x8029cc]`): the f32 sum's bit pattern `>> 14` is the
+/// byte, never a numeric conversion.
 const FIXED_BIAS: f64 = 512.0;
 
-/// Distance from a model-space point to one portal polygon, the reference's kernel (`0x6c4240`):
-/// **0** when the point projects *through the opening* — inside the polygon and within
-/// [`PORTAL_PLANE_EPS`] of its plane — otherwise the minimum distance to the polygon's edge segments.
-///
-/// The containment half is what keeps a doorway's plane from reaching across a room. A portal plane is
-/// infinite; several of these openings are not doorways at all but whole ceilings (Dire Maul's sunken
-/// courtyard joins its sky through a 283×154 yd quad), so "on the plane" alone would whiten geometry
-/// tens of yards from any opening. Points on the plane but *outside* the outline fall through to the
-/// edge distance, which is the reference's own fallback and is never smaller than the truth.
+/// Distance from a point to a portal polygon, the reference's kernel `0x6c4240`: 0 inside the
+/// outline within [`PORTAL_PLANE_EPS`] of the plane, else the nearest edge distance. The outline
+/// test matters: some portals are whole ceilings (Dire Maul's courtyard, 283×154 yd).
 fn portal_distance(p: [f32; 3], poly: &[[f32; 3]], plane: [f32; 4]) -> f32 {
     let n = [plane[0], plane[1], plane[2]];
     let pd = n[0] * p[0] + n[1] * p[1] + n[2] * p[2] + plane[3];
@@ -495,42 +356,20 @@ fn portal_distance(p: [f32; 3], poly: &[[f32; 3]], plane: [f32; 4]) -> f32 {
     }
 }
 
-/// One byte through the reference's fixed-point white-lerp: `((255 − ch)·t + ch + 512)` as f32, whose
-/// **bit pattern** shifted `>> 14` is the new byte (`0x6c43d0`, byte-verified against `WoW.exe`).
+/// One byte of the white-lerp (`0x6c43d0`): the bits of `(255 − ch)·t + ch + 512` as f32, `>> 14`.
 fn white_lerp_byte(ch: u8, t: f64) -> u8 {
     let chf = f64::from(ch);
     let s = ((255.0 - chf) * t + chf + FIXED_BIAS) as f32;
     ((s.to_bits() >> 14) & 0xff) as u8
 }
 
-/// **FixColorVertexAlpha** (`0x6c43d0`, wow-re `wmo-group-lighting.md §4`) — the bright-doorway portal
-/// fade, run once per group *before* it is ever drawn, in place over its MOCV buffer.
-///
-/// This is not a nicety: a WMO's short transition corridors are authored with **no usable bake at
-/// all** — Dire Maul's five entrance passages floor their walkway at MOCV `(10,10,40,α=0)`, a near-black
-/// navy — because the runtime fade is what lights them. Skip it and the interior TRANS law renders
-/// exactly what the file says: `tex × (10,10,40)` at lit-factor 1, a black floor between lit walls
-/// (the director's Dire Maul entrance report). The floor's four corners sit *on* the doorway portal
-/// polygons, so the fade takes them to white and the quad interpolates lit end to end.
-///
-/// The mechanism:
-/// 1. **Distance**: per vertex, the minimum [`portal_distance`] over this group's portal refs whose
-///    **neighbour group is exterior** (`MOGI.flags & 0x48 != 0`). Portals to interior neighbours
-///    whiten nothing — the fade is specific to interior↔exterior openings, observed live. A group
-///    with no such portal is untouched.
-/// 2. **Branches**: `dist == 0` ⇒ the slot goes white-opaque outright; `dist < 6.6667` **and** the
-///    authored alpha is 0 ⇒ RGB white-lerped by `t = 1 − 0.15·dist` with alpha `t·255`; else untouched.
-///
-/// **The MOPY pre-pass (`0x6c41e0`) is deliberately NOT run**, on live evidence over the static read.
-/// §4 records it as forcing `alpha = 0xFF` on every triangle with `MOPY.flags & 1 == 0` — but it is
-/// gated (`DAT_00ca8064 == 0`), and the reference's own D3D capture of the abbey
-/// (`trace-forensics-abbey-interior-d3d.md` §2) shows the uploaded MOCV pool **byte-exact against the
-/// file except for the whitened set** — 678/678 and 496/506 vertices identical, alphas included. A
-/// pre-pass that had run would have rewritten hundreds of alphas in that same buffer (372 of g003's
-/// 506 by this reader's count). It costs nothing here either way: the pre-pass can only *suppress* the
-/// partial-lerp branch, never the `dist == 0` whitening the dark corridors depend on.
-///
-/// A group without MOCV, or without an exterior-neighbour portal, is left exactly as authored.
+/// The reference's bright-doorway fade, FixColorVertexAlpha (`0x6c43d0`), run once per group in
+/// place over its MOCV before any draw; transition corridors are authored near-black and rely on
+/// it. Per vertex, `dist` is the nearest [`portal_distance`] over portals to exterior neighbours
+/// (`MOGI.flags & 0x48 != 0`): at 0 the vertex goes white-opaque, under [`DOORWAY_FADE_REACH`] with
+/// alpha 0 it is white-lerped by `t = 1 − 0.15·dist` with alpha `t·255`, else it is untouched. The
+/// MOPY pre-pass `0x6c41e0` is gated (`DAT_00ca8064`) and a reference capture shows it unrun, so it
+/// is not run here.
 fn fix_color_vertex_alpha(
     colors: &mut [Color],
     group: &WmoGroup,
@@ -540,7 +379,7 @@ fn fix_color_vertex_alpha(
     let portals = root.portals();
     let infos = root.group_infos();
     let (start, count) = (header_refs.0 as usize, header_refs.1 as usize);
-    // The doorway set: portals of THIS group whose far side is an exterior (daylit) group.
+    // This group's portals whose far side is an exterior group.
     let doors: Vec<(Vec<[f32; 3]>, [f32; 4])> = portals
         .refs
         .get(start..start + count)
@@ -590,12 +429,7 @@ fn fix_color_vertex_alpha(
     }
 }
 
-/// The group's MOCV **as the renderer uploads it** — the authored buffer with the bright-doorway fade
-/// already applied (see [`fix_color_vertex_alpha`]), BGRA bytes parallel to the group's vertices.
-/// `None` when the bytes aren't a group or carry no MOCV parallel to their positions.
-///
-/// The seam the `wmo_mocv` instrument reads: a batch that censuses black in the file and white here
-/// is a transition corridor the fade lights; black in both is a genuinely dark room.
+/// The group's MOCV as the renderer uploads it, BGRA, with the doorway fade applied.
 pub fn wmo_group_fixed_colors(group_bytes: &[u8], root: &WmoRoot) -> Option<Vec<[u8; 4]>> {
     let Ok(ParsedWmo::Group(group)) = parse_wmo(&mut Cursor::new(group_bytes)) else {
         return None;
@@ -604,9 +438,7 @@ pub fn wmo_group_fixed_colors(group_bytes: &[u8], root: &WmoRoot) -> Option<Vec<
     Some(colors.iter().map(|c| [c.b, c.g, c.r, c.a]).collect())
 }
 
-/// The group's MOCV **exactly as authored**, BGRA bytes parallel to its vertices — the before to
-/// [`wmo_group_fixed_colors`]'s after. `None` when the bytes aren't a group or carry no MOCV parallel
-/// to their positions.
+/// The group's MOCV as authored, BGRA.
 pub fn wmo_group_raw_colors(group_bytes: &[u8]) -> Option<Vec<[u8; 4]>> {
     let Ok(ParsedWmo::Group(group)) = parse_wmo(&mut Cursor::new(group_bytes)) else {
         return None;
@@ -615,32 +447,21 @@ pub fn wmo_group_raw_colors(group_bytes: &[u8]) -> Option<Vec<[u8; 4]>> {
     Some(colors.iter().map(|c| [c.b, c.g, c.r, c.a]).collect())
 }
 
-/// The group's MOCV as a buffer **parallel to its positions**, or `None` if it has no usable bake.
-///
-/// The length test cannot be plain equality. A WMO's last chunk is allowed to run past EOF and clamp
-/// (decision 0972), and when the clamped chunk is MOCV the buffer comes back a whole *record* short:
-/// `Undercity_144.wmo` holds 1159 of its declared 1160 colour bytes, so `chunks_exact(4)` yields 289
-/// colours for 290 vertices. Demanding equality threw away **289 good colours over one missing byte**
-/// and fell the whole group back to untinted white — a corridor lit `tex × 1.0` inside a city whose
-/// every other interior surface is multiplied by a dark bake (decision 0977).
-///
-/// So a shortfall inside one record's worth is padded from the last complete colour; anything larger
-/// is a genuinely broken bake and still reads `None`, because padding hundreds of vertices from one
-/// sample would invent lighting rather than recover it.
+/// The group's MOCV parallel to its positions. A MOCV clamped at EOF comes back one colour short
+/// (`Undercity_144.wmo` holds 1159 of 1160 bytes) and is padded from the last colour; a larger
+/// shortfall is a broken bake and reads `None`.
 fn parallel_colors(group: &WmoGroup) -> Option<Vec<Color>> {
     let (have, want) = (group.vertex_colors.len(), group.vertex_positions.len());
     if have == want {
         return Some(group.vertex_colors.clone());
     }
-    // `want - have == 1` is the clamped-tail case and the only shortfall we reconstruct.
     let last = (have + 1 == want).then(|| group.vertex_colors.last().copied())??;
     let mut colors = group.vertex_colors.clone();
     colors.push(last);
     Some(colors)
 }
 
-/// Shared body of [`wmo_group_fixed_colors`] and the submesh build: clone the authored MOCV and run
-/// the fade over it. `None` when the group carries no MOCV parallel to its positions.
+/// The authored MOCV with the doorway fade run over it.
 fn fixed_colors(group: &WmoGroup, group_bytes: &[u8], root: &WmoRoot) -> Option<Vec<Color>> {
     let mut colors = parallel_colors(group)?;
     let refs =
@@ -649,24 +470,19 @@ fn fixed_colors(group: &WmoGroup, group_bytes: &[u8], root: &WmoRoot) -> Option<
     Some(colors)
 }
 
-/// Build the render submeshes for one WMO **group** (its bytes), resolving textures/materials against
-/// `root`. Empty if the bytes aren't a parseable group. The bytes-in entry point for the Bevy
-/// `AssetLoader`; [`super::load_wmo`] is the chain-reading wrapper.
+/// Build one group's render submeshes against `root`; empty if the bytes are not a group.
 pub fn wmo_group_submeshes(group_bytes: &[u8], root: &WmoRoot) -> Result<Vec<RenderSubmesh>> {
     let Ok(ParsedWmo::Group(group)) = parse_wmo(&mut Cursor::new(group_bytes)) else {
         return Ok(Vec::new());
     };
-    // The bright-doorway fade runs ONCE per group, over the group's own MOCV buffer, before any draw
-    // reads it (`0x6b3f90` gates it on the group's `+0xbc` done-byte). We load a group once, so the
-    // once-gate is the load itself: fix the colours here and every batch below sees the fixed buffer.
+    // The reference fades once per group, gated on its `+0xbc` done-byte (`0x6b3f90`); a group
+    // loads once, so the load is the gate.
     let colors = fixed_colors(&group, group_bytes, root).unwrap_or_default();
     let ParsedWmo::Root(root) = &root.parsed else {
         anyhow::bail!("WmoRoot is not a root");
     };
-    // The MOGP batch-section counts (`+0x28/+0x2a/+0x2c`, after the byte-verified portal-ref span):
-    // MOBA batches are laid out TRANS, then INT, then EXT — the class decides an interior group's
-    // per-batch lighting law (see [`WmoBatchClass`]). Absent/short header ⇒ everything reads EXT
-    // (the conservative exterior law).
+    // MOGP `+0x28`/`+0x2a`: MOBA batches run TRANS, then INT, then EXT, the class deciding an
+    // interior group's lighting; a short header reads all EXT.
     let (trans_n, int_n) = find_wmo_chunk(group_bytes, b"PGOM")
         .filter(|m| m.len() >= 0x2c)
         .map_or((0usize, 0usize), |m| {
@@ -677,11 +493,9 @@ pub fn wmo_group_submeshes(group_bytes: &[u8], root: &WmoRoot) -> Result<Vec<Ren
         });
     let mut out = Vec::new();
     {
-        // WMO groups carry MONR normals + MOCV colours (parallel to positions); fall back when absent.
         let has_normals = group.vertex_normals.len() == group.vertex_positions.len();
         let has_colors = colors.len() == group.vertex_positions.len();
-        // Interior iff neither the EXTERIOR (0x8) nor exterior-lit (0x40) bit is set — the same
-        // `groupFlags & 0x48 == 0` test the real client branches on (RenderSubmesh::interior).
+        // Neither exterior (`0x8`) nor exterior-lit (`0x40`): the reference's interior test.
         let interior = (group.flags & 0x48) == 0;
         let vertex = |g: u32| {
             let p = &group.vertex_positions[g as usize];
@@ -693,10 +507,8 @@ pub fn wmo_group_submeshes(group_bytes: &[u8], root: &WmoRoot) -> Result<Vec<Ren
                 .texture_coords
                 .get(g as usize)
                 .map_or([0.0, 0.0], |t| [t.u, t.v]);
-            // MOCV is BGRA; RGB is the per-vertex shade multiplier, and the REAL alpha rides along —
-            // on an interior TRANS batch it is the lit↔bake lerp factor (the FixColorVertexAlpha
-            // product, applied above); every other batch class forces it opaque below (alpha encodes
-            // blend/unused there — the exterior alpha→0xFF fixup). Absent → white.
+            // MOCV RGB is the shade multiplier; the alpha rides along and is forced opaque below
+            // where it is not lighting data. No MOCV is white.
             let c = colors.get(g as usize).map_or([1.0, 1.0, 1.0, 1.0], |c| {
                 [
                     c.r as f32 / 255.0,
@@ -736,36 +548,21 @@ pub fn wmo_group_submeshes(group_bytes: &[u8], root: &WmoRoot) -> Result<Vec<Ren
             let blend = match material.map(|m| m.blend_mode) {
                 Some(0) | None => ModelBlend::Opaque,
                 Some(1) => ModelBlend::AlphaTest,
-                // MOMT.blendMode is a DIRECT EGxBlend index (no M2-style remap — wow-re
-                // `wmo-batch-blend-depth-state`): 4 = Mod (DST_COLOR/ZERO), 5 = Mod2x
-                // (DST_COLOR/SRC_COLOR). Decision 0528.
+                // `MOMT.blendMode` indexes EGxBlend directly, no M2 remap (`0x6b500f`): 4 is Mod
+                // (DST_COLOR/ZERO), 5 Mod2x (DST_COLOR/SRC_COLOR).
                 Some(4) => ModelBlend::Mod,
                 Some(5) => ModelBlend::Mod2x,
                 Some(_) => ModelBlend::Blend,
             };
-            // The MOMT window/glass flags, each its own mechanism (wow-re `wmo-lit-selector` §1,
-            // `wmo-interior-night-light` §2/§4 — byte-verified):
-            //   UNLIT (0x01)  — the EXTERIOR drawer turns lighting off per material → `tex × white`
-            //                   fullbright (the inn's always-lit outside panes, MM_ELWYNN_WND_EXT).
-            //                   The INTERIOR drawer ignores it — lit/unlit there is dictated by the
-            //                   batch section alone, so `emissive` stays false on interior groups.
-            //   SIDN (0x10)   — the authored night-glow emissive colour, ramped by the night
-            //                   fraction and added inside the lit sum (the abbey's stained glass
-            //                   glowing after dusk). Lit lanes only; carried with its colour.
-            //   WINDOW (0x20) — interior-drawer batches swap to the brighter midpoint light (the
-            //                   warm pane seen from inside — MM_ELWYNN_WND_INT, MM_STAINED_01).
+            // MOMT flags (drawers `0x6b4f10`/`0x6b5190`, SIDN updater `0x6b4090`): UNLIT `0x01`
+            // draws an exterior batch fullbright and is ignored by the interior drawer; SIDN `0x10`
+            // adds the night-glow colour inside the lit sum; WINDOW `0x20` gives an interior batch
+            // the brighter midpoint light.
             let flags = material.map_or(0, |m| m.flags);
             let emissive = !interior && flags & 0x01 != 0;
-            // UNCULLED (0x04): the real client backface-culls every WMO batch unless this MOMT
-            // flag is set — byte-verified at the render-state write (wow-re models.md: bit 0x04
-            // inverted → EGxRs 0x14 GL_CULL_FACE; default cull ON, GL_BACK/CCW) — the same law the
-            // M2 path already honours. This used to be hardcoded two-sided ("buildings aren't the
-            // canopy issue"), and a building IS the canopy issue: 1.12 authors both-sides-visible
-            // cloth as the SAME faces twice with reversed winding (one copy per side — B38's tent
-            // awning, `wmo_doubled`), each meant to be culled from its wrong side. Drawing them
-            // two-sided rasterises both copies into an ulp-level depth tie, and the per-pixel
-            // winner is floating-point noise — the B38 flicker/latch (decision 0680).
-            // WMO has no skeleton, so the per-vertex skin (`_globals`) is unused.
+            // UNCULLED `0x04`: without it the reference back-face culls the batch (`0x6b4fd7`,
+            // `0x6b52bf`). Two-sided cloth is authored as the same faces twice with reversed
+            // winding, so drawing both sides z-fights. A WMO has no skeleton: the skin is unused.
             let (mut submesh, _globals) = remap_submesh(
                 global_indices.into_iter(),
                 vertex,
@@ -781,17 +578,14 @@ pub fn wmo_group_submeshes(group_bytes: &[u8], root: &WmoRoot) -> Result<Vec<Ren
                 .flatten();
             submesh.window = flags & 0x20 != 0;
             if !has_normals {
-                submesh.normals.clear(); // no MONR → let the renderer recompute flat normals
+                submesh.normals.clear(); // no MONR: the renderer computes flat normals
             }
             if !has_colors {
-                submesh.vertex_colors.clear(); // no MOCV → empty (white, no tint)
+                submesh.vertex_colors.clear(); // no MOCV: untinted
             }
-            // The MOCV **alpha** is per-vertex LIGHTING data on interior batches: a TRANS batch
-            // reads it as the lit↔bake lerp factor, an INT batch as the ×4 self-illumination mask
-            // (the reference's interior pixel shader `tex·MOCV·(1 + 4·a)` — the inn's fireplace
-            // surround bakes α≈100, the portal-seam whitening 255). Exterior batches encode
-            // blend/unused state there — force those opaque so bevy's vertex-colour fold can't
-            // perturb their alpha semantics (the shader un-folds coverage for the interior lanes).
+            // MOCV alpha is lighting data on interior batches: TRANS reads it as the lit-to-bake
+            // lerp factor, INT as the self-illumination mask (the reference's
+            // `tex·MOCV·(1 + 4·a)`). Elsewhere it is blend state, forced opaque.
             if !(interior && matches!(class, WmoBatchClass::Trans | WmoBatchClass::Int)) {
                 for c in &mut submesh.vertex_colors {
                     c[3] = 1.0;
@@ -819,7 +613,7 @@ mod tests {
             base: [100.0, 200.0, -3.0],
             material_id: 0,
             heights: vec![-3.0; 6],
-            // Byte 0 per vertex — the authored opacity index (see `wmo_water_alpha_v`).
+            // Byte 0 per vertex, the authored opacity index.
             opacity: vec![0, 51, 102, 153, 204, 255],
             tile_flags: vec![0x44, 0x0f], // wet (type 4 + fishable), hole
         };
@@ -827,11 +621,9 @@ mod tests {
         assert_eq!(m.kind, LiquidKind::Still);
         assert_eq!(m.positions.len(), 6); // full 3×2 grid emitted
         assert_eq!(m.indices.len(), 6); // one wet tile → 2 tris → 6 indices
-                                        // Grid vertex (i=1, j=0) sits at base + (1·STEP, 0, height).
         assert!((m.positions[1][0] - (100.0 + MLIQ_CELL_STEP)).abs() < 1e-3);
         assert_eq!(m.positions[0], [100.0, 200.0, -3.0]);
-        // Opacity is the vertex's OWN authored byte, normalised — not a pinned deep endpoint.
-        // Before this, every WMO pool in the game was rendered at a hard 1.0 (fully opaque).
+        // Opacity is the vertex's own authored byte, normalised.
         for (n, &v) in m.depths.iter().enumerate() {
             assert!(
                 (v - f32::from(lq.opacity[n]) / 255.0).abs() < 1e-6,
@@ -839,16 +631,11 @@ mod tests {
                 lq.opacity[n]
             );
         }
-        // The wet tile is the LEFT one (indices reference the left cell's 4 corners: 0,1,3,4).
+        // The wet tile is the left one, corners 0, 1, 3 and 4.
         assert!(m.indices.iter().all(|&i| [0u32, 1, 3, 4].contains(&i)));
     }
 
-    /// Two grid-aligned WMO liquid surfaces (a canal split across groups) must share ONE continuous
-    /// UV field, so the animated water texture doesn't seam at the boundary. Surface B begins exactly
-    /// where A's last column sits (base offset by 2·STEP in X), so the vertex they share in model space
-    /// must get the SAME UV in both — the property a per-surface `(i, j)` reset would break wherever
-    /// surfaces are NOT cell-aligned (each
-    /// surface restarted at UV 0, and an arbitrary tile count put that restart mid-texture → the seam).
+    /// Surface B starts at A's last column (2·STEP east), so their shared vertex must get one UV.
     #[test]
     fn adjacent_surfaces_share_a_continuous_uv_field() {
         let base = [100.0, 200.0, -3.0];
@@ -863,7 +650,6 @@ mod tests {
             opacity: Vec::new(),
             tile_flags: vec![0x44, 0x44], // both tiles wet
         };
-        // B's origin column coincides with A's rightmost column (one 2-tile span east).
         let b = WmoLiquid {
             xverts: 3,
             yverts: 2,
@@ -877,16 +663,13 @@ mod tests {
         };
         let ma = build_wmo_liquid_mesh(&a, 0xf).unwrap();
         let mb = build_wmo_liquid_mesh(&b, 0xf).unwrap();
-        // A's rightmost-bottom vertex (i=2, j=0 → index 2) and B's leftmost-bottom (i=0, j=0 → index 0)
-        // are the same model-space point; their UVs must match (no seam).
+        // A's vertex (2, 0) and B's (0, 0) are the same point.
         let (ua, ub) = (ma.uvs[2], mb.uvs[0]);
         assert!(
             (ua[0] - ub[0]).abs() < 1e-4 && (ua[1] - ub[1]).abs() < 1e-4,
             "seam: shared-vertex UVs differ A={ua:?} B={ub:?}"
         );
-        // The field is position-derived, and it steps exactly ONE repeat per cell — the reference's
-        // `u = (float)i` (`0x6b6630`). This used to assert ¼, i.e. a texture 4x too large; correcting
-        // it is what took the ripple off mip 0 across the whole near field (`MLIQ_UV_PERIOD`).
+        // One repeat per cell, the reference's `u = (float)i` (`0x6b6630`).
         assert!((ma.uvs[1][0] - ma.uvs[0][0] - 1.0).abs() < 1e-4);
     }
 
@@ -908,7 +691,6 @@ mod tests {
         assert_eq!(m.kind, LiquidKind::Magma);
         assert!(m.depths.iter().all(|&v| v == 0.0)); // fullbright ⇒ depth V unused
 
-        // A grid where every tile is a hole → no mesh.
         let all_holes = WmoLiquid {
             tile_flags: vec![0x0f],
             ..lq
@@ -918,13 +700,11 @@ mod tests {
 
     #[test]
     fn reads_group_header_flags_and_portal_ref_span() {
-        // A 68-byte MOGP header: flags @0x08, portal_ref_start @0x24, portal_ref_count @0x26.
         let mut hdr = vec![0u8; 68];
         hdr[8..12].copy_from_slice(&0x8u32.to_le_bytes()); // EXTERIOR
         hdr[0x24..0x26].copy_from_slice(&5u16.to_le_bytes());
         hdr[0x26..0x28].copy_from_slice(&3u16.to_le_bytes());
         hdr[0x30..0x34].copy_from_slice(&[2, 0, 0, 0]); // fog indices
-                                                        // Group file: MVER then MOGP(super-chunk = header + (no) sub-chunks).
         let mut group = Vec::new();
         group.extend(chunk(b"REVM", &17u32.to_le_bytes()));
         group.extend(chunk(b"PGOM", &hdr));
@@ -941,9 +721,7 @@ mod tests {
         );
     }
 
-    /// The whole-group submersion override at MOGP `0x34`, and the two ways a header can fail to
-    /// carry one. `0` is a live value (all 13 shipped groups that set it say `0` = water), so the
-    /// sentinel has to be spelled out rather than defaulted to zero.
+    /// All 13 shipped overrides are `0`, water, so the no-liquid sentinel cannot be zero.
     #[test]
     fn reads_the_whole_group_liquid_override() {
         let group_with = |liquid: u32| {
@@ -955,7 +733,7 @@ mod tests {
             group
         };
 
-        // The shipped case: water, over the whole group, with no MLIQ anywhere in the file.
+        // The shipped case: the whole group is water, with no MLIQ.
         let flooded = wmo_group_header(&group_with(0)).expect("group header");
         assert_eq!(flooded.group_liquid, 0);
         assert_ne!(flooded.group_liquid, NO_GROUP_LIQUID);
@@ -968,8 +746,7 @@ mod tests {
             NO_GROUP_LIQUID
         );
 
-        // A header truncated before 0x34 reads as "no liquid" — the safe way round, since the
-        // override only ever adds water and a short header is not evidence of a flooded room.
+        // A header short of 0x34 reads as no liquid.
         let mut short = Vec::new();
         short.extend(chunk(b"REVM", &17u32.to_le_bytes()));
         short.extend(chunk(b"PGOM", &[0u8; 0x30]));
diff --git a/crates/benilla-formats/src/models/wmo/mod.rs b/crates/benilla-formats/src/models/wmo/mod.rs
index 6def47ca..f5c46240 100644
--- a/crates/benilla-formats/src/models/wmo/mod.rs
+++ b/crates/benilla-formats/src/models/wmo/mod.rs
@@ -1,7 +1,5 @@
-//! WMO (building) parsing, split along the file boundary the format itself draws: [`root`] parses
-//! the root file's shared tables (materials, doodads, group infos, portals, fogs), [`group`] parses
-//! a group file (header, refs, render batches) against a parsed root. This module keeps the shared
-//! chunk-finder and the chain-reading entry point.
+//! WMO (building) parsing: [`root`] parses the root file's shared tables, [`group`] a group file
+//! against a parsed root.
 
 mod group;
 mod root;
@@ -13,8 +11,7 @@ use anyhow::{Context, Result};
 
 use crate::Chain;
 
-/// Load a WMO (building) from the chain: its root + every group file, flattened into submeshes
-/// (one per group render batch). `raw_path` is the MWMO root path (`.wmo`).
+/// Load a WMO's root and every group file from the chain, one submesh per group render batch.
 pub fn load_wmo(chain: &mut Chain, raw_path: &str) -> Result<Vec<super::RenderSubmesh>> {
     let root_path = raw_path.to_ascii_lowercase();
     let bytes = chain
@@ -33,16 +30,9 @@ pub fn load_wmo(chain: &mut Chain, raw_path: &str) -> Result<Vec<super::RenderSu
     Ok(out)
 }
 
-/// Find a top-level WMO chunk's data slice by its **on-disk (reversed) magic** — WMO/ADT store the
-/// FourCC reversed (`MODN` → `NDOM`). Top-level root chunks are laid out flat from byte 0
-/// (`[magic:4][size:u32 LE][data:size]`), so a linear walk locates any of them.
-///
-/// **The last chunk clamps to EOF; it never rejects the file.** The reference's walk "reads chunks
-/// while the 8-byte header is in-bounds and clamps the last chunk to EOF (never requires exact
-/// tiling)" — wow-re `models.md`, "WMO chunk-structure contract", whose own worked example is the
-/// file this rule exists for: `Undercity_144.wmo`'s MOGP declares one byte more than the file holds.
-/// Abandoning the walk there cost that group its MOGP entirely — flags, portal-ref span, area, fog,
-/// doodad and light refs — which dead-ended the portal flood at B26's doorway (decision 0972).
+/// Find a top-level WMO chunk's data by its on-disk magic, which WMO stores reversed (`MODN` is
+/// `NDOM`). As in the reference's walk (`0x6c3a60`/`0x6c3f80`), the last chunk clamps to EOF and
+/// never rejects the file: `Undercity_144.wmo`'s MOGP declares one byte more than the file holds.
 pub(crate) fn find_wmo_chunk<'a>(bytes: &'a [u8], magic: &[u8; 4]) -> Option<&'a [u8]> {
     let mut off = 0usize;
     while off + 8 <= bytes.len() {
@@ -53,9 +43,7 @@ pub(crate) fn find_wmo_chunk<'a>(bytes: &'a [u8], magic: &[u8; 4]) -> Option<&'a
             bytes[off + 7],
         ]) as usize;
         let data_start = off + 8;
-        // Saturating, then clamped: a garbage size can overflow, and an over-declared one is real
-        // data the reference tolerates. Either way `data_end >= data_start`, so the slice is valid
-        // and `off` still advances by at least 8 — the walk terminates.
+        // Saturating, then clamped: `data_end >= data_start` for any size, so the walk advances.
         let data_end = data_start.saturating_add(size).min(bytes.len());
         if &bytes[off..off + 4] == magic {
             return Some(&bytes[data_start..data_end]);
@@ -68,7 +56,7 @@ pub(crate) fn find_wmo_chunk<'a>(bytes: &'a [u8], magic: &[u8; 4]) -> Option<&'a
 /// Synthetic-chunk builders shared by the [`root`]/[`group`] test modules.
 #[cfg(test)]
 mod test_bytes {
-    /// Build one top-level WMO chunk: the FourCC stored **reversed**, a `u32 LE` size, then `data`.
+    /// One top-level WMO chunk: the reversed FourCC, a `u32` LE size, then `data`.
     pub(super) fn chunk(reversed_magic: &[u8; 4], data: &[u8]) -> Vec<u8> {
         let mut out = Vec::with_capacity(8 + data.len());
         out.extend_from_slice(reversed_magic);
diff --git a/crates/benilla-formats/src/models/wmo/root.rs b/crates/benilla-formats/src/models/wmo/root.rs
index 81e9df8d..6cecbb8e 100644
--- a/crates/benilla-formats/src/models/wmo/root.rs
+++ b/crates/benilla-formats/src/models/wmo/root.rs
@@ -1,5 +1,5 @@
-//! WMO **root**-file parsing: the shared tables a group resolves against — doodads (MODS/MODN/MODD),
-//! group infos (MOGI), the portal graph (MOPV/MOPT/MOPR), fog records (MFOG) — plus the root id.
+//! WMO root-file parsing: the shared tables a group resolves against, doodads (MODS/MODN/MODD),
+//! group infos (MOGI), portals (MOPV/MOPT/MOPR) and fogs (MFOG), plus the root id.
 
 use std::io::Cursor;
 
@@ -8,70 +8,50 @@ use benilla_wmo::{parse_wmo, ParsedWmo};
 
 use super::find_wmo_chunk;
 
-/// A placed WMO **doodad** (an MODD entry): an M2 prop the WMO root positions *inside* itself —
-/// candle stands, banners, braziers, chandeliers — as opposed to geometry baked into the WMO mesh
-/// (pews, walls). Resolved + in WMO model space (WoW axes, Z up); compose with the WMO instance's
-/// world transform at spawn (`benilla_assets::coords::wmo_doodad_local`).
+/// A placed WMO doodad (an MODD entry): an M2 prop in WMO model space (WoW axes, Z up), composed
+/// with the instance's world transform at spawn (`benilla_assets::coords::wmo_doodad_local`).
 #[derive(Debug, Clone)]
 pub struct WmoDoodad {
-    /// M2 path (MMDX-style, `.mdx`/`.mdl`); `m2_url`/`load_m2_mesh` normalize it to `.m2`. Empty ⇒
-    /// the MODN name offset didn't resolve (skipped at spawn).
+    /// The M2 path as authored (`.mdx`/`.mdl`), normalized to `.m2` by the loaders; empty when the
+    /// MODN offset does not resolve.
     pub model: String,
-    /// Position in WMO model space (WoW axes).
     pub position: [f32; 3],
-    /// Orientation quaternion `(x, y, z, w)` in WMO model space.
+    /// Orientation quaternion, `(x, y, z, w)`.
     pub orientation: [f32; 4],
     /// Uniform scale.
     pub scale: f32,
-    /// The MODD entry's **baked colour** (`+0x24`, BGRA on disk → stored `[r, g, b, a]`): the WMO
-    /// baker's authored local-lighting product for this placement. For an INTERIOR-group doodad this
-    /// IS the slot-0 base light — the real client copies it at doodad create into the diffuse word
-    /// (floor-raised to HSV value 112) and the ambient word (capped to max 96), never running any
-    /// footprint/attach sample (byte-verified `0x694e90` create → `6950de call 0x6a77e0(&MODD.colour,
-    /// …, 0x70, …, 0x60)`; wow-re `trace-forensics-abbey-interior-d3d` §1.1 — the abbey stands'
-    /// decoded diffuse words equal these bytes verbatim).
+    /// The baked colour at `+0x24`, BGRA on disk, stored RGBA: an interior doodad's base light, set
+    /// at create as diffuse (HSV value ≥ 112) and ambient (≤ 96), with no footprint sample
+    /// (`0x694e90`, `0x6a77e0`).
     pub color: [u8; 4],
 }
 
-/// A WMO **doodad set** (an MODS entry): a contiguous range `[start, start+count)` into the
-/// [`WmoRoot::doodads`] list. Set 0 is the global set (always shown); a placement's MODF
-/// `doodad_set` field selects one *additional* set to show by index.
+/// A doodad set (an MODS entry), the range `[start, start + count)` of [`WmoRoot::doodads`]. Set 0
+/// always shows; a placement's MODF `doodad_set` adds one more.
 #[derive(Debug, Clone, Copy)]
 pub struct WmoDoodadSet {
     pub start: u32,
     pub count: u32,
 }
 
-/// Per-WMO-**group** info from the root's MOGI chunk: the group's interior/exterior class and its
-/// axis-aligned bounding box (WMO model space, WoW axes). A placed MODD doodad's class comes from
-/// its OWNING group (the MODR reference that instantiates it — see [`super::wmo_group_doodad_refs`]);
-/// moving ENTITIES classify by the position-cast face down-ray instead (the client's own indoor
-/// bit — never these boxes, whose authored bounds can float above their own floor polys). The box
-/// is a loose AABB approximation of the group's true BSP/portal volume.
+/// A group's MOGI entry: its interior class and loose bounding box, WMO model space. A doodad's
+/// class is its owning group's (the MODR list holding it); a moving entity's is the reference's
+/// down-ray indoor bit, never these boxes, which can float above the group's floor.
 #[derive(Debug, Clone, Copy)]
 pub struct WmoGroupInfo {
-    /// `groupFlags & 0x48 == 0` — neither EXTERIOR (`0x8`) nor exterior-lit (`0x40`): a true interior
-    /// group. The same test the client branches on at `0x6b3f90` and that [`crate::models::RenderSubmesh::interior`] uses.
+    /// `groupFlags & 0x48 == 0`: neither exterior (`0x8`) nor exterior-lit (`0x40`), the test at
+    /// `0x6b3f90` and in [`crate::models::RenderSubmesh::interior`].
     pub interior: bool,
-    /// `groupFlags & 0x40000` — **SHOW_SKYBOX**: this group draws the root's [`WmoRoot::skybox`] model
-    /// in place of the `Light.dbc` gradient dome. The bit's identity is a corpus correlation
-    /// (`benilla-extract skyboxscan`): across the 5875 chain it appears on a group **iff** its root
-    /// carries a non-empty MOSB — Stratholme's city shell sets it on 61 of 83 groups (its open streets,
-    /// which are authored as INTERIOR groups), while the sibling dungeon `Stratholme.wmo` (MOSB empty)
-    /// sets it on none of 92.
+    /// `groupFlags & 0x40000`: draw [`WmoRoot::skybox`] instead of the `Light.dbc` dome. A corpus
+    /// correlation (`benilla-extract skyboxscan`): only roots with a non-empty MOSB set it.
     pub show_skybox: bool,
-    /// Group bounding-box min, WMO model space (WoW axes).
     pub bbox_min: [f32; 3],
-    /// Group bounding-box max, WMO model space (WoW axes).
     pub bbox_max: [f32; 3],
 }
 
-/// A parsed WMO **root**: the shared material/texture tables the group submeshes resolve against,
-/// plus the resolved doodad tables (sets + placed props). Build with [`parse_wmo_root`], then feed
-/// each group file's bytes to [`super::wmo_group_submeshes`]. The Bevy WMO `AssetLoader`
-/// orchestrates the root + group reads; the chain-reading equivalent is [`super::load_wmo`].
+/// A parsed WMO root, the tables [`super::wmo_group_submeshes`] resolves each group against.
 pub struct WmoRoot {
-    /// The raw parse — the group-side batch build reads the material/texture tables through it.
+    /// The raw parse, whose material and texture tables the group batch build reads.
     pub(super) parsed: ParsedWmo,
     doodads: Vec<WmoDoodad>,
     doodad_sets: Vec<WmoDoodadSet>,
@@ -90,29 +70,24 @@ impl WmoRoot {
         }
     }
 
-    /// The root's placed doodads (MODD), names resolved, indexable by the ranges in [`Self::doodad_sets`].
+    /// The placed doodads (MODD) with names resolved; [`Self::doodad_sets`] index into it.
     pub fn doodads(&self) -> &[WmoDoodad] {
         &self.doodads
     }
 
-    /// The root's doodad sets (MODS) — ranges into [`Self::doodads`].
+    /// The doodad sets (MODS), ranges into [`Self::doodads`].
     pub fn doodad_sets(&self) -> &[WmoDoodadSet] {
         &self.doodad_sets
     }
 
-    /// The root's per-group info (MOGI) — interior flag + bounding box, for classifying which placed
-    /// doodads are interior (see [`WmoGroupInfo`]).
+    /// Per-group info (MOGI), in group order.
     pub fn group_infos(&self) -> &[WmoGroupInfo] {
         &self.group_infos
     }
 
-    /// Per-material **`TerrainType.dbc` id** (MOMT+0x20), indexed by the MOPY per-face material id
-    /// — what walking on each material sounds like, shared root-wide across every group.
-    ///
-    /// The footstep chain's WMO leg (decision 1161): the client's down-ray arbitrates terrain
-    /// against a building's collision faces, and when the building wins it re-rays that group's
-    /// RENDER faces and resolves `MOPY[face].material_id → MOMT[id]+0x20` (`0x6a26c0`, wow-re
-    /// `wmo-footstep-surface.md`).
+    /// Per-material `TerrainType.dbc` id (MOMT `+0x20`), the footstep sound, indexed by MOPY face
+    /// material. When the down-ray hits a building, the reference re-rays that group's render
+    /// faces and reads `MOMT[MOPY[face].material_id] + 0x20` (`0x6a26c0`).
     pub fn material_ground_types(&self) -> Vec<u32> {
         match &self.parsed {
             ParsedWmo::Root(r) => r.materials.iter().map(|m| m.ground_type).collect(),
@@ -120,10 +95,8 @@ impl WmoRoot {
         }
     }
 
-    /// Per-material MOMT `diffColor` (`+0x1C`), RGB 0..1. Read for one consumer: an **interior**
-    /// WMO liquid pool's body colour is `MOMT[MLIQ.materialId].diffColor`, taken raw, because the
-    /// reference's interior water kernel runs unlit with no pixel shader (wow-re
-    /// `terrain/scratch/water-shading-law.md`). Indexed by [`LiquidMesh::material_id`].
+    /// Per-material MOMT `diffColor` (`+0x1C`), RGB 0..1, by [`LiquidMesh::material_id`]: an
+    /// interior liquid's raw body colour, the reference's interior water being unlit (`0x6b6420`).
     pub fn material_diff_colors(&self) -> Vec<[f32; 3]> {
         match &self.parsed {
             ParsedWmo::Root(r) => r
@@ -142,27 +115,23 @@ impl WmoRoot {
         }
     }
 
-    /// The root's portal graph (MOPV/MOPT/MOPR) — the data that drives per-group visibility culling
-    /// (see [`WmoPortals`]). Empty for WMOs with no portals (most single-group props).
+    /// The portal graph (MOPV/MOPT/MOPR); empty for most single-group props.
     pub fn portals(&self) -> &WmoPortals {
         &self.portals
     }
 
-    /// The root's fog records (MFOG) — indexed by a group header's [`super::WmoGroupHeader::fog_indices`]
-    /// (see [`WmoFog`] for what's pinned vs pending about their consumption).
+    /// The fog records (MFOG), indexed by [`super::WmoGroupHeader::fog_indices`].
     pub fn fogs(&self) -> &[WmoFog] {
         &self.fogs
     }
 
-    /// The root's **MOSB** skybox model — the M2 a [`WmoGroupInfo::show_skybox`] group draws instead of
-    /// the `Light.dbc` gradient dome. `None` when the chunk is absent or holds only the empty string
-    /// (the overwhelming majority: five roots in the whole 5875 chain author one).
+    /// The MOSB skybox model a [`WmoGroupInfo::show_skybox`] group draws; five 5875 roots have one.
     pub fn skybox(&self) -> Option<&str> {
         self.skybox.as_deref()
     }
 }
 
-/// Parse a WMO **root** file from bytes. `Err` if the bytes aren't a WMO root.
+/// Parse a WMO root file.
 pub fn parse_wmo_root(bytes: &[u8]) -> Result<WmoRoot> {
     let parsed =
         parse_wmo(&mut Cursor::new(bytes)).map_err(|e| anyhow::anyhow!("parsing WMO root: {e}"))?;
@@ -185,9 +154,7 @@ pub fn parse_wmo_root(bytes: &[u8]) -> Result<WmoRoot> {
     })
 }
 
-/// Parse the root's **MOSB** chunk — a single null-terminated model path, or the 4 zero bytes that
-/// stand for "no skybox" (which is what almost every root carries). Returned normalized to `.m2`, the
-/// extension the loaders take; the chunk itself names the authoring-time `.mdx`.
+/// MOSB: one NUL-terminated `.mdx` path, or four zero bytes for none; returned as `.m2`.
 fn parse_skybox(bytes: &[u8]) -> Option<String> {
     let mosb = find_wmo_chunk(bytes, b"BSOM")?;
     let end = mosb.iter().position(|&b| b == 0).unwrap_or(mosb.len());
@@ -198,9 +165,8 @@ fn parse_skybox(bytes: &[u8]) -> Option<String> {
     Some(crate::models::model_path(raw))
 }
 
-/// Parse the root's **MOGI** group table (`[flags:u32][bbox:6×f32][nameOff:i32]`, stride 32) into the
-/// per-group interior flag + bounding box used to classify placed doodads (see [`WmoGroupInfo`]). The
-/// flags here mirror the per-group MOGP header flags ([`crate::models::RenderSubmesh::interior`] reads the latter).
+/// MOGI, stride 32: `flags: u32, bbox: 6 × f32, nameOff: i32`; the flags mirror each group's MOGP
+/// header flags.
 fn parse_wmo_group_infos(bytes: &[u8]) -> Vec<WmoGroupInfo> {
     let Some(mogi) = find_wmo_chunk(bytes, b"IGOM") else {
         return Vec::new();
@@ -221,26 +187,20 @@ fn parse_wmo_group_infos(bytes: &[u8]) -> Vec<WmoGroupInfo> {
         .collect()
 }
 
-/// The WMO root's **portal graph** — the three root chunks that drive per-group visibility culling
-/// (`wow-5875-re` `system/models/models.md` → "WMO portal-based visibility culling", VERIFIED against
-/// `WoW.exe` 5875). All coordinates are WMO model space (WoW axes, Z up), the same space as
-/// [`WmoGroupInfo`] bounds. A group references its portals through a slice of [`Self::refs`] given by
-/// the group header's `portal_ref_start`/`portal_ref_count` ([`super::wmo_group_header`]).
+/// The portal graph in WMO model space, driving per-group visibility (the reference's `0x6b41c0`).
+/// A group's portals: [`Self::refs`] from its header's `portal_ref_start`, `portal_ref_count` long.
 #[derive(Debug, Clone, Default)]
 pub struct WmoPortals {
-    /// **MOPV** — the portal polygon vertices, pooled; a portal indexes a contiguous run via
-    /// [`WmoPortalInfo::start_vertex`]/[`WmoPortalInfo::count`].
+    /// MOPV: the pooled portal polygon vertices.
     pub vertices: Vec<[f32; 3]>,
-    /// **MOPT** — one entry per portal: its vertex run + separating plane.
+    /// MOPT: one entry per portal.
     pub infos: Vec<WmoPortalInfo>,
-    /// **MOPR** — portal references: per-group edges of the portal graph (which portal joins which
-    /// neighbouring group, and on which side of the plane that neighbour lies).
+    /// MOPR: the graph's edges, each a portal from a group to a neighbour.
     pub refs: Vec<WmoPortalRef>,
 }
 
-/// One **MOPT** portal (20 bytes on disk): a polygon (a run of [`WmoPortals::vertices`]) plus the
-/// plane it lies in. `plane` is `[nx, ny, nz, dist]` — a unit normal and the signed plane offset, so a
-/// point `p` is at signed distance `normal·p + dist` from the portal.
+/// One MOPT portal, 20 bytes: a run of [`WmoPortals::vertices`] and its plane `[nx, ny, nz, dist]`,
+/// a point's signed distance being `normal·p + dist`.
 #[derive(Debug, Clone, Copy)]
 pub struct WmoPortalInfo {
     pub start_vertex: u16,
@@ -248,9 +208,8 @@ pub struct WmoPortalInfo {
     pub plane: [f32; 4],
 }
 
-/// One **MOPR** portal reference (8 bytes on disk): an edge in a group's portal slice. `portal`
-/// indexes [`WmoPortals::infos`]; `group` is the neighbouring group reached through it; `side`
-/// (`±1`) orients the plane test — the camera must be on the `side`-facing half-space to enter.
+/// One MOPR reference, 8 bytes: `portal` indexes [`WmoPortals::infos`], `group` is the neighbour
+/// behind it, and `side` (±1) is the half-space the camera must be in to enter.
 #[derive(Debug, Clone, Copy)]
 pub struct WmoPortalRef {
     pub portal: u16,
@@ -258,11 +217,9 @@ pub struct WmoPortalRef {
     pub side: i16,
 }
 
-/// Parse the root's portal chunks (**MOPV**/**MOPT**/**MOPR**) into the portal graph. Absent chunks
-/// yield empty vecs (a WMO with no portals — most single-group props). Strides/field offsets are
-/// VERIFIED from the client's consumer in `WoW.exe` 5875 (parser `0x6c3a60`): MOPV stride `0xc`
-/// (`C3Vector`), MOPT stride `0x14` (`u16 start, u16 count, C4Plane`), MOPR stride `0x8`
-/// (`u16 portal, u16 group, i16 side, u16 filler`).
+/// Parse MOPV/MOPT/MOPR at the strides the reference's root parser `0x6c3a60` reads: MOPV `0xc`
+/// (`C3Vector`), MOPT `0x14` (`u16 start, u16 count, C4Plane`), MOPR `0x8` (`u16 portal,
+/// u16 group, i16 side, u16 filler`). An absent chunk is empty.
 pub fn parse_wmo_portals(bytes: &[u8]) -> WmoPortals {
     let f = |b: &[u8], i: usize| f32::from_le_bytes([b[i], b[i + 1], b[i + 2], b[i + 3]]);
     let u16 = |b: &[u8], i: usize| u16::from_le_bytes([b[i], b[i + 1]]);
@@ -310,36 +267,31 @@ pub fn parse_wmo_portals(bytes: &[u8]) -> WmoPortals {
     }
 }
 
-/// One **MFOG** fog record (48 bytes on disk — stride `0x30` VERIFIED as the client's own
-/// (`wow-5875-re` ledger: `CMapObj+0x158` mfog_ptr, stride `0x30`)). Fields are the verbatim
-/// v17 on-disk layout; *which* record an interior group selects and how the client consumes
-/// `start_scalar` are the round-5 Q-G carve (`rf-weather-emission-timeline`) — parse now,
-/// apply only once pinned. Position/radii are WMO model space, same as [`WmoGroupInfo`] bounds.
+/// One MFOG fog record, the v17 on-disk layout at the reference's stride `0x30` (root parser
+/// `0x6c3a60`, `CMapObj+0x158`), read field for field. Position and radii are WMO model space.
 #[derive(Debug, Clone, Copy)]
 pub struct WmoFog {
     pub flags: u32,
-    /// Fog sphere centre, WMO model space (WoW axes).
+    /// Fog sphere centre.
     pub pos: [f32; 3],
-    /// Inner radius — full fog inside this.
+    /// Inner radius: full fog inside it.
     pub radius_inner: f32,
-    /// Outer radius — no fog influence beyond this.
+    /// Outer radius: no fog influence beyond it.
     pub radius_outer: f32,
-    /// Land fog end distance (world units from the eye).
+    /// Land fog end, world units from the eye.
     pub fog_end: f32,
-    /// Land fog start, as a scalar of `fog_end` per the v17 layout (client transform pending Q-G).
+    /// Land fog start, as a fraction of `fog_end`.
     pub fog_start_scalar: f32,
-    /// Land fog colour — raw on-disk dword (`u32 LE`; byte-order decode deferred to the fold).
+    /// Land fog colour, the raw on-disk dword.
     pub color: u32,
-    /// Underwater fog end distance.
     pub uw_fog_end: f32,
-    /// Underwater fog start scalar.
+    /// Underwater fog start, as a fraction of `uw_fog_end`.
     pub uw_fog_start_scalar: f32,
-    /// Underwater fog colour — raw on-disk dword.
+    /// Underwater fog colour, the raw on-disk dword.
     pub uw_color: u32,
 }
 
-/// Parse the root's **MFOG** fog records (stride 48). Absent chunk yields an empty vec — but note
-/// every shipped 5875 root carries at least one MFOG record (the "null fog", huge `fog_end`).
+/// Parse the MFOG records; every 5875 root carries at least one, a null fog with a huge `fog_end`.
 pub fn parse_wmo_fogs(bytes: &[u8]) -> Vec<WmoFog> {
     let Some(mfog) = find_wmo_chunk(bytes, b"GOFM") else {
         return Vec::new();
@@ -364,9 +316,7 @@ pub fn parse_wmo_fogs(bytes: &[u8]) -> Vec<WmoFog> {
         .collect()
 }
 
-/// The root's `MOHD.wmoID` @ `0x20` — the `WMOAreaTable.WMOID` key for the whole building
-/// (byte-verified 2026-07-03: NSabbey.wmo → 59, the abbey rows; Chapel.wmo → 656). `0` when
-/// the header is too short (no 5875 root is).
+/// `MOHD.wmoID` at `0x20`, the building's `WMOAreaTable.WMOID` key; 0 for a short header.
 pub fn wmo_root_id(root_bytes: &[u8]) -> u32 {
     find_wmo_chunk(root_bytes, b"DHOM")
         .filter(|mohd| mohd.len() >= 0x24)
@@ -374,15 +324,11 @@ pub fn wmo_root_id(root_bytes: &[u8]) -> u32 {
         .unwrap_or(0)
 }
 
-/// Parse the root's doodad tables straight from the raw bytes: MODS (sets), MODN (name blob), MODD
-/// (defs). We parse these three small fixed-layout chunks ourselves rather than via `benilla-wmo`
-/// because an MODD's name is a **byte offset into the MODN blob**, which a split-on-NUL `Vec<String>`
-/// discards — so we read the blob + offsets directly. Records: MODS = 32 B
-/// (`name[20]`, `start:u32`, `count:u32`, pad), MODD = 40 B (`nameOff+flags:u32`, `pos:3×f32`,
-/// `quat:4×f32`, `scale:f32`, `color:4×u8`).
+/// Parse MODS (32 B: `name[20], start: u32, count: u32, pad`), MODN and MODD (40 B: `nameOff +
+/// flags: u32, pos: 3×f32, quat: 4×f32, scale: f32, color: 4×u8`) from the raw bytes: an MODD name
+/// is a byte offset into MODN, which `benilla-wmo`'s split `Vec<String>` loses.
 fn parse_wmo_doodads(bytes: &[u8]) -> (Vec<WmoDoodad>, Vec<WmoDoodadSet>) {
     let modn = find_wmo_chunk(bytes, b"NDOM").unwrap_or(&[]);
-    // Resolve a MODN byte offset → the NUL-terminated M2 path at that offset.
     let resolve = |off: usize| -> String {
         if off >= modn.len() {
             return String::new();
@@ -404,7 +350,7 @@ fn parse_wmo_doodads(bytes: &[u8]) -> (Vec<WmoDoodad>, Vec<WmoDoodadSet>) {
                 position: [f(4), f(8), f(12)],
                 orientation: [f(16), f(20), f(24), f(28)],
                 scale: f(32),
-                // The baked colour at +0x24 — CImVector is BGRA in memory; store as RGBA.
+                // `CImVector` at `+0x24` is BGRA; stored RGBA.
                 color: [rec[38], rec[37], rec[36], rec[39]],
             });
         }
@@ -430,18 +376,15 @@ mod tests {
 
     #[test]
     fn parses_portal_vertices_infos_and_refs() {
-        // MOPV: 3 vertices.
         let mut mopv = Vec::new();
         for v in [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]] {
             mopv.extend(f3(v));
         }
-        // MOPT: one portal — startVertex 0, count 3, plane (0,0,1, -2.5).
         let mut mopt = Vec::new();
         mopt.extend_from_slice(&0u16.to_le_bytes());
         mopt.extend_from_slice(&3u16.to_le_bytes());
         mopt.extend(f3([0.0, 0.0, 1.0]));
         mopt.extend_from_slice(&(-2.5f32).to_le_bytes());
-        // MOPR: two refs — (portal 0, group 1, side +1), (portal 0, group 7, side -1).
         let mut mopr = Vec::new();
         for (p, g, s) in [(0u16, 1u16, 1i16), (0, 7, -1)] {
             mopr.extend_from_slice(&p.to_le_bytes());
@@ -480,7 +423,7 @@ mod tests {
 
     #[test]
     fn parses_mfog_records() {
-        // Two 48-byte MFOG records: a "null fog" (huge end) and a room fog.
+        // A null fog (huge end) and a room fog.
         let mut mfog = Vec::new();
         for (pos, r_in, r_out, end, start_scalar, color) in [
             (
diff --git a/crates/benilla-formats/src/npc_greeting.rs b/crates/benilla-formats/src/npc_greeting.rs
index 35e9284c..8aee5568 100644
--- a/crates/benilla-formats/src/npc_greeting.rs
+++ b/crates/benilla-formats/src/npc_greeting.rs
@@ -1,28 +1,9 @@
-//! NPC greeting voice — the vocal an NPC plays when the player interacts with it ("Greetings,
-//! traveler", race/sex/personality-flavored). A per-**display** property, distinct from the
-//! creature-body vocals of [`crate::creature_sound`]:
-//!
-//! Chain — VERIFIED against build 5875, twice over: this session's raw DBC decode (2026-07-04)
-//! AND the wow-re §5 byte proof (`wow-5875-re/system/sound/scratch/npc-greeting.md`, `68cccdd1`
-//! — the loaders check exactly these layouts: NPCSounds `0x54afa0` cols==5/recsize==0x14,
-//! CreatureDisplayInfo `0x542e90` cols==12/recsize==0x30; the play path reads row`+0x2c`):
-//! `UNIT_FIELD_DISPLAYID` → `CreatureDisplayInfo.dbc` **field[11]** (the last field, `NPCSoundID`)
-//! → `NPCSounds.dbc` row → **field[1]** (`hello`) / **field[2]** (`goodbye`) / **field[3]**
-//! (`pissed`, the variation-overflow line) — each a `SoundEntries` kit id, played through the
-//! shared kit player. NOT the `CreatureSoundData.NPCSoundID` the older wowdev notes suggest: that
-//! column (field 22) is **0/406 in 1.12** — entirely unused, and the wow-re proof confirms
-//! CreatureSoundData is not on the greeting path at all.
-//!
-//! Byte-census of the real tables:
-//! - `CreatureDisplayInfo.dbc`: 10534 × 12 fields. field[11] is nonzero on **4509** displays, and
-//!   **every** nonzero value (4509/4509) is a valid `NPCSounds` id (distinct 147/156). A beast
-//!   display (e.g. id 26) carries field[11]=0 → no greeting; only humanoid/character displays greet.
-//! - `NPCSounds.dbc`: 156 × 5 fields (recsize 20), layout `{id(0), hello(1), goodbye(2), pissed(3),
-//!   ack(4)}`. `hello` is set on all 156 rows; `goodbye` on 118; `pissed` on 120; `ack` is **0 on
-//!   every row** in 1.12 (and the binary never reads it — wow-re). The kits are all `SoundEntries`
-//!   type 17 (NPC greeting), flags `0x20` (no-duplicates), distance-cutoff 45 yd — a 3D world
-//!   emitter at the NPC, not a 2D sound (wow-re §4: `FSOUND_3D_SetAttributes` with the unit's
-//!   position).
+//! The NPC greeting voice, a per-display property apart from the body vocals of
+//! [`crate::creature_sound`]: `UNIT_FIELD_DISPLAYID` → `CreatureDisplayInfo.dbc` field 11
+//! (`NPCSoundID`, row `+0x2c`; loader `0x542e90`, 12 columns) → `NPCSounds.dbc` (`0x54afa0`: `ID`,
+//! `hello`, `goodbye`, `pissed`, and `ack`, 0 on every row and never read). Each is a
+//! `SoundEntries` kit of type 17, no-duplicates (`0x20`), cut off at 45 yd, a 3D emitter at the NPC
+//! (`0x7a5b10`). `CreatureSoundData.NPCSoundID` is not on the path (`0x60c3b0`, `0x623910`).
 
 use std::collections::HashMap;
 
@@ -35,27 +16,26 @@ use crate::dbc::{parse, u32_at};
 /// The greeting kit set for one NPC (each a `SoundEntries` kit id; `0` = none).
 #[derive(Clone, Copy, Debug)]
 pub struct NpcGreeting {
-    /// `NPCSounds.hello` — the greeting played on interact / target enter.
+    /// `NPCSounds.hello`, played on a left-click select (`0x60c270`) and once when an interaction
+    /// window opens (`0x60c3b0(1)`).
     pub hello: u32,
-    /// `NPCSounds.goodbye` — the farewell, played when the tracked interaction unit clears
-    /// (wow-re: `0x60c3b0(0)` on mouseover/target leave — no discrete gossip-close callback).
+    /// `NPCSounds.goodbye`, played when the interaction window closes to nothing (`0x60c3b0(0)`),
+    /// not when it swaps to another NPC.
     pub goodbye: u32,
-    /// `NPCSounds.pissed` — the annoyed line the variation-overflow branch plays once repeat
-    /// interacts have cycled past the hello kit's variations (wow-re: `0x623910`'s overflow reads
-    /// row`+0xc`).
+    /// `NPCSounds.pissed`: after five left-click hellos its variations play in turn, then the
+    /// cycle restarts (`0x623910` reads row `+0xc`).
     pub pissed: u32,
 }
 
-/// display id → greeting pair, joined `CreatureDisplayInfo.field[11]` → `NPCSounds`.
+/// Display id → greeting kits, joined through `CreatureDisplayInfo` field 11 → `NPCSounds`.
 pub struct NpcGreetingCatalog {
     display_to_sound: HashMap<u32, u32>,
     rows: HashMap<u32, NpcGreeting>,
 }
 
 impl NpcGreetingCatalog {
-    /// The greeting for a creature **display id** (the [`crate`] wire `display_id`), or `None` when
-    /// the display carries no `NPCSoundID` (beasts and most non-character models) or the referenced
-    /// `NPCSounds` row is missing.
+    /// The greeting for a display id; `None` for a display without an `NPCSoundID`, as beasts and
+    /// most non-character models are.
     pub fn for_display(&self, display_id: u32) -> Option<&NpcGreeting> {
         self.rows.get(self.display_to_sound.get(&display_id)?)
     }
@@ -69,7 +49,6 @@ impl NpcGreetingCatalog {
     }
 }
 
-/// `NPCSounds.dbc` — 5 uint32 fields.
 fn npcsounds_schema() -> Schema {
     let mut s = Schema::new("NPCSounds");
     for i in 0..5 {
@@ -78,7 +57,6 @@ fn npcsounds_schema() -> Schema {
     s
 }
 
-/// `CreatureDisplayInfo.dbc` — 12 fields (field[11] = `NPCSoundID`).
 fn cdi_schema() -> Schema {
     let mut s = Schema::new("CreatureDisplayInfo");
     for i in 0..12 {
@@ -129,9 +107,7 @@ pub fn load_npc_greeting_catalog(chain: &mut Chain) -> Result<NpcGreetingCatalog
 mod tests {
     use super::*;
 
-    /// The join works on the real 5875 tables: all 156 `NPCSounds` rows load, thousands of
-    /// displays resolve a greeting, a known character display resolves to a real greeting kit, and
-    /// a beast display (26, `NPCSoundID` 0) has no greeting.
+    /// The 5875 join: character displays resolve their kits, a beast display (26) has none.
     #[test]
     fn real_npc_greeting_resolves() {
         let data = crate::wow_data_or_skip!();
@@ -139,19 +115,18 @@ mod tests {
         let cat = load_npc_greeting_catalog(&mut chain).expect("load npc greetings");
         assert_eq!(cat.len(), 156, "all NPCSounds rows load");
 
-        // Display 793 → NPCSoundID 50 → {hello 5977, goodbye 5978, pissed 5979} (byte-decoded).
+        // Display 793 is `NPCSoundID` 50.
         let g = cat.for_display(793).expect("display 793 greets");
         assert_eq!(g.hello, 5977);
         assert_eq!(g.goodbye, 5978);
         assert_eq!(g.pissed, 5979);
 
-        // Display 89 → NPCSoundID 161 → {hello 7094, no goodbye, pissed 7095}.
+        // Display 89 is `NPCSoundID` 161, which has no goodbye.
         let g = cat.for_display(89).expect("display 89 greets");
         assert_eq!(g.hello, 7094);
         assert_eq!(g.goodbye, 0);
         assert_eq!(g.pissed, 7095);
 
-        // A beast model display carries NPCSoundID 0 → no greeting.
         assert!(
             cat.for_display(26).is_none(),
             "beast display does not greet"
diff --git a/crates/benilla-formats/src/page_text_material.rs b/crates/benilla-formats/src/page_text_material.rs
index 91a67f26..fadf0408 100644
--- a/crates/benilla-formats/src/page_text_material.rs
+++ b/crates/benilla-formats/src/page_text_material.rs
@@ -1,21 +1,7 @@
-//! `PageTextMaterial.dbc` — the book-frame material lookup (decision 1105).
-//!
-//! A readable carries a material *id* (a book item template's `PageMaterial`, a
-//! `GAMEOBJECT_TYPE_TEXT` object's template `data[2]`); the reference resolves it to a **basename**
-//! through this table and hands that string to Lua as `ItemTextGetMaterial()`, which paints the
-//! four corner textures from `Interface\ItemTextFrame\ItemText-<basename>-TopLeft` … and picks the
-//! page's font/text colour (`ItemTextFrame.lua` l.63-104). `"Parchment"` is the special one: the
-//! Lua hides the corner art for it, and it is also the substitute when the getter returns nothing.
-//!
-//! **The resolve is byte-verified** (`ItemTextGetMaterial 0x4e39f0`): the GameObject leg calls
-//! `0x5f5950` — template-attribute `0x11` → the type's `data[]` slot → the id — then bounds-checks
-//! `0 < id <= [0xc0da20]` against the DBC's id-indexed table `[0xc0da1c]` and returns `[row+4]`,
-//! the row's **second** field. Out of range, or `id <= 0`, pushes `nil` (→ the Lua's Parchment).
-//!
-//! The 5875 schema was read byte-level from the real file (VERIFIED at decision time): WDBC header
-//! `record_count = 6`, `field_count = 2`, `record_size = 8`, string block 48 bytes — two 4-byte
-//! fields, the second a string ref. The six rows are `1 Parchment · 2 Stone · 3 Marble · 4 Silver ·
-//! 5 Bronze · 6 Valentine`.
+//! `PageTextMaterial.dbc`: a readable's material id (a book's `PageMaterial`, a text object's
+//! `data[2]`) → the basename `ItemTextGetMaterial()` (`0x4e39f0`) hands to Lua, which paints the
+//! `ItemText-<basename>-*` corners and picks the text colour (`ItemTextFrame.lua:63-104`). An id
+//! outside `0 < id <= [0xc0da20]` returns nil, which the Lua shows as "Parchment", without corners.
 
 use std::collections::HashMap;
 
@@ -33,24 +19,21 @@ pub struct PageTextMaterialCatalog {
 }
 
 impl PageTextMaterialCatalog {
-    /// A catalog from `(id, basename)` rows — the shipped six are 1 Parchment · 2 Stone · 3 Marble
-    /// · 4 Silver · 5 Bronze · 6 Valentine (wow-re quest-material-reward-spell-bindings.md §1).
+    /// A catalog from `(id, basename)` rows. The file ships 1 Parchment, 2 Stone, 3 Marble,
+    /// 4 Silver, 5 Bronze, 6 Valentine.
     pub fn from_rows(rows: &[(u32, &str)]) -> Self {
         Self {
             by_id: rows.iter().map(|&(id, n)| (id, n.to_string())).collect(),
         }
     }
 
-    /// The basename for a material id, or `None` for `0`/an id the table doesn't carry — the
-    /// reference's own `nil`, which `ItemTextFrame.lua` substitutes with "Parchment" (and then
-    /// hides the corner art, since Parchment has none).
+    /// The basename for a material id; `None` where the reference returns `nil`.
     pub fn name(&self, id: u32) -> Option<&str> {
         self.by_id.get(&id).map(String::as_str)
     }
 }
 
-/// Load `PageTextMaterial.dbc` into an id → basename map (see the module doc for the verified
-/// schema).
+/// Load `PageTextMaterial.dbc` from the patch chain.
 pub fn load_page_text_material_catalog(chain: &mut Chain) -> Result<PageTextMaterialCatalog> {
     let bytes = chain
         .read_file(PAGE_TEXT_MATERIAL)
diff --git a/crates/benilla-formats/src/particles.rs b/crates/benilla-formats/src/particles.rs
index 1c45f331..faebdbf8 100644
--- a/crates/benilla-formats/src/particles.rs
+++ b/crates/benilla-formats/src/particles.rs
@@ -1,40 +1,7 @@
-//! Vanilla (build 5875 / MD20 v256) M2 **particle emitter** parsing — read straight from raw bytes.
-//!
-//! `benilla-m2` parses only the render path and deliberately skips the cosmetic chunks, so the
-//! particle emitters are read here. The post-vanilla `M2ParticleEmitter` (with `texture_file_data_ids`,
-//! `enable_encryption`, WoD flag bits) does not match 1.12; the vanilla layout is a fixed
-//! **0x1f8-byte** record. The byte layout is from `wow-5875-re` (`FUN_0070ebd0` @ `0x70ebd0`,
-//! `m2-decomp.c`) and **difftested** here against `ElwynnCampfire.m2` (see `tests/`):
-//!
-//! ```text
-//! header array : count @ MD20+0x13c, ptr @ MD20+0x140         record stride 0x1f8
-//! +0x04 flags(u32)  +0x08 position(C3Vector)  +0x14 bone(u16)  +0x16 texture(u16, index→M2 textures)
-//! +0x28 blendingType(u8)  +0x2a emitterType(u16:1=Plane,2=Sphere,3=Spline)
-//! +0x2c particleType(u16:0=head,1=tail,2=both)  +0x30 tileRows(u16)  +0x32 tileCols(u16)
-//! +0x34.. ten emission M2Tracks (vanilla 28-byte track; the runtime uses value[0] of each):
-//!   +0x34 emissionSpeed  +0x50 speedVariation  +0x6c verticalRange  +0x88 horizontalRange
-//!   +0xa4 gravity  +0xc0 lifespan  +0xdc emissionRate  +0xf8 areaLength  +0x114 areaWidth
-//!   +0x130 zSource
-//! +0x14c.. baked over-life color/opacity/scale/cell ramps (see `OverLife`).
-//! +0x17c tailTime(f32, SECONDS — the tail streak's length is velocity·tailTime)
-//! +0x180 twinkleSpeed  +0x184 twinklePercent  +0x188/+0x18c twinkleScale{min,max}
-//! +0x190 inheritScale(f32)  +0x194 drag(f32, plain scalar — the velocity decay)
-//! +0x198 spin(f32, rad/s quad rotation)
-//! +0x1c4..+0x1d0 followSpeed1/followScale1/followSpeed2/followScale2 (the follow-delta line)
-//! +0x1dc enabled(M2Track<u8>, step) — the emission ON/OFF gate, closing the record at 0x1f8.
-//! ```
-//!
-//! The two keyed tracks here (emission rate, enabled) bake **one loop per sequence** into
-//! [`EmitTiming`] through the same FN1 kernel as the material alpha (`models::key_anim`,
-//! decision 0641): the reference samples both per frame through the *playing* sequence's own key
-//! window (`0x713d50` — wow-re `part-emission-rate-animated.md` §2/§3), so what an emitter does
-//! is a function of which sequence its model instance is playing. A quest GameObject authors its
-//! explosion inside one-shot clips and an OFF window in every idle sequence; baking only
-//! sequence 0's band parked that choreography at its end value forever (bug B27).
-//!
-//! The record tail (+0x180..) is the wow-re `part-simspace-fields.md` §5-verified map (their
-//! `ac915a7d`): the loader `0x70ebd0` remaps file+0x188/+0x18c → runtime twinkleScale min/max
-//! (delta = max − min at rt+0x1c0), NOT a size multiplier — see [`ParticleEmitterDef::twinkle`].
+//! Vanilla (MD20 v256) M2 particle emitters, read from raw bytes because `benilla-m2` skips them:
+//! fixed 0x1f8-byte records (array at MD20+0x13c/+0x140) at the reference loader's offsets
+//! (`0x70ebd0`). Rate and enabled bake one loop per sequence into [`EmitTiming`], since the
+//! reference samples both in the playing sequence's key window (`0x713d50`).
 
 use std::io::Cursor;
 
@@ -44,8 +11,7 @@ use benilla_m2::{parse_m2, M2ScalarTrack};
 use crate::emit_timing::{EmitParams, EmitTiming};
 use crate::models::SeqSlot;
 
-/// Emitter spawn shape (file `emitterType` @ +0x2a). Only `Plane` is needed for campfires/torches;
-/// `Sphere` (e.g. dust clouds) and `Spline` follow.
+/// Emitter spawn shape, file `emitterType` (+0x2a): 1 plane, 2 sphere, 3 spline.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ParticleShape {
     Plane,
@@ -53,63 +19,31 @@ pub enum ParticleShape {
     Spline,
 }
 
-/// How a particle batch blends (file `blendingType` @ +0x28 = the M2/EGxBlend enum). Additive is the
-/// flame/glow case (the campfire is `4`); mod/mod2x still fold to alpha (rare for the props we
-/// render, and they will get their own path when a model needs them).
+/// Particle blend, file `blendingType` (+0x28), the M2 blend enum. Mod (5) and mod2x (6) have no
+/// modulate path yet and draw as `Alpha`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum ParticleBlend {
-    /// `3` NoAlphaAdd / `4` Add — `(SRC_ALPHA, ONE)`. Flames, glows, embers. No depth write/sort.
+    /// `4` Add, `(SRC_ALPHA, ONE)`, and `3` NoAlphaAdd, which the reference draws `(ONE, ONE)`
+    /// (EGxBlend 10): no depth write or sort. Flames and glows.
     Add,
-    /// `2` Alpha — `(SRC_ALPHA, ONE_MINUS_SRC_ALPHA)`. Smoke.
+    /// `2` Alpha: `(SRC_ALPHA, ONE_MINUS_SRC_ALPHA)`. Smoke.
     Alpha,
-    /// `1` AlphaKey — blending **OFF**, depth-write ON, and the fixed-function **alpha test**
-    /// `GEQUAL 224/255` carving the texture's silhouette out of the quad. The chip/debris family:
-    /// solid little rocks, bone shards, ice splinters, each authored as a shape on a
-    /// fully-transparent field.
-    ///
-    /// Every step is byte-verified in wow-re (see [`ParticleBlend::Opaque`] for the shared half):
-    /// the emitter's own blend field decides its list at `0x7085db` (`cmp word[rec+0x28],1; ja` —
-    /// mode ≤ 1 **and** instance alpha ≥ 0.99999 lands in the `+0x4c` **opaque** list, i.e. pass 0,
-    /// `part-flush-emitter-depth.md` §1), pass 0 takes promotion-table row 0
-    /// `0x811fe0 = {0,1,2,10,3,4,5}` so mode 1 stays **EGxBlend 1**
-    /// (`m2-blend-promotion-zfill.md` §1), EGxBlend 0/1 → `glDisable(GL_BLEND)`
-    /// (`0x59d563`, `egxrs-depth-blend-states.md`), and `0x70c256` sets the ref from the RAW mode —
-    /// `round(instanceAlpha × 224.0)`, `[0x812034] = 224.0f` — never from the pass
-    /// (`m2-blend-promotion-zfill.md` §2). Depth-write stays ON because the synthetic material only
-    /// sets its z-write-off bit for `blendMode > 1` (`0x70d8f1`, `part-scene-multipliers.md` §0).
-    ///
-    /// Folding this into `Opaque` — no discard at all — paints the transparent field solid: the
-    /// Lesser Rock Elemental's debris (`PARTROCK.BLP`, 31 % of its texels at α = 0) came out as
-    /// flat pale squares instead of tumbling chips.
+    /// `1` AlphaKey, for chips and debris: alpha test `GEQUAL round(instanceAlpha × 224)` from the
+    /// raw mode (`0x70c256`, 224.0 at `[0x812034]`). Mode ≤ 1 at alpha ≥ 0.99999 joins the opaque
+    /// list (`0x7085db`), whose promotion row `0x811fe0` keeps it EGxBlend 1, blending off
+    /// (`0x59d563`); z-write goes off only above mode 1 (`0x70d8f1`).
     AlphaKey,
-    /// `0` Opaque — blending OFF, depth-write ON, and **no** alpha test (`0x70c237`'s mode-0 arm
-    /// sets ref 0, which `0x59d5b9` turns into `glDisable(GL_ALPHA_TEST)`). Genuinely rare for
-    /// particles; the fallback for an out-of-range blend byte too.
+    /// `0` Opaque: blending off, depth write on, no alpha test (the mode-0 arm of `0x70c237` sets
+    /// ref 0, which `0x59d5b9` turns into `glDisable(GL_ALPHA_TEST)`). Also any unknown byte.
     Opaque,
 }
 
-/// One segment's integer **flipbook cell ramp** — the authored `(begin, end)` pair and the
-/// `(base, span)` the reference derives from it at load (`0x7b9da0` head / `0x7b9de0` tail, both
-/// pure-integer; wow-re `part-cell-flipbook-ramp.md` §2).
-///
-/// The two build arms are deliberately **asymmetric**, and that asymmetry is the whole mechanism:
-/// the ramp covers `N = |end − begin| + 1` cells, each getting `1/N` of the segment, travelling in
-/// the **authored direction**.
-///
-/// ```text
-/// end >= begin : base = begin,      span = end − begin + 1   (forward)
-/// end <  begin : base = begin + 1,  span = end − begin − 1   (NEGATIVE — plays backwards)
-/// ```
-///
-/// **A decreasing pair is legal, shipped, and means "run the flipbook in reverse"** — four models
-/// author one (`DwarvenBrazier01`'s settling flame, `ShadowWordSilence_Breath`'s 32-frame reverse
-/// sweep). There is no swap and no clamp anywhere on the reference's path; an earlier reading here
-/// clamped into `[begin, end]`, which both mangled the reverse ramps and panicked outright on them
-/// (decision 0685).
+/// One segment's flipbook cell ramp: the authored `(begin, end)` and the `(base, span)` the
+/// reference derives at load (`0x7b9da0` head, `0x7b9de0` tail), `|end − begin| + 1` cells in the
+/// authored direction. A decreasing pair is shipped and plays backwards; nothing swaps or clamps.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct CellRamp {
-    /// The authored pair, verbatim (the reference archives it at `rec+0x3c/+0x40` and never reads
-    /// it back — kept here because it is what a dump should show).
+    /// The authored pair, stored at `rec+0x3c/+0x40` and never read back by the reference.
     pub begin: u16,
     pub end: u16,
     base: i32,
@@ -117,7 +51,7 @@ pub struct CellRamp {
 }
 
 impl CellRamp {
-    /// Build from an authored `(begin, end)` pair — `0x7b9da0`'s two arms, verbatim.
+    /// From an authored pair, by `0x7b9da0`'s two arms.
     pub fn new(begin: u16, end: u16) -> Self {
         let (b, e) = (i32::from(begin), i32::from(end));
         let (base, span) = if e >= b {
@@ -133,62 +67,43 @@ impl CellRamp {
         }
     }
 
-    /// The cell index at segment fraction `t` — **`t` must already carry the endpoint inset** (and
-    /// the repeat wrap, if any); see [`OverLife::sample`].
-    ///
-    /// `floor(base + span·t) & 0xFF`. The mask is the reference's mod-256 wrap (its fast-floor
-    /// idiom `bits(x + 512.0) >> 14` yields a byte), **not** a clamp into the authored range or the
-    /// atlas — bounding the index is the atlas walk's business, and it only masks the column.
+    /// The cell at segment fraction `t` (inset and repeat already applied, [`OverLife::sample`]):
+    /// `floor(base + span·t) & 0xFF`, the reference's mod-256 wrap, not a clamp.
     pub fn sample(&self, t: f32) -> u16 {
-        // Saturating float→int (NaN → 0) rather than the reference's raw mantissa read: a `mid` of
-        // 0 or 1 makes the reference's own segment span 1/0 and walks NaN into this floor, and we
-        // will not reproduce a fault. No shipped emitter authors that mid (corpus-swept).
+        // Deviation: NaN floors to 0 where the reference reads the raw mantissa, because we do not
+        // reproduce its divide by zero on a `mid` of 0 or 1; no shipped emitter authors one.
         let v = self.base as f32 + self.span as f32 * t;
         ((v.floor() as i32) & 0xFF) as u16
     }
 }
 
-/// The baked **over-life** ramps (record tail, +0x14c..) sampled by a particle's normalized age `u =
-/// age/lifespan`. Colour and size are **3-key ramps** evaluated as two linear segments split at
-/// [`Self::mid`]: key0→key1 over `u∈[0,mid]`, then key1→key2 over `u∈[mid,1]`. The flipbook cells
-/// are a different shape — a `(begin, end)` [`CellRamp`] **per segment**, and there are two
-/// independent sets of them (head quad, tail streak). Byte layout + math verified in `wow-5875-re`
-/// (`FUN_0070ebd0` builder, `FUN_007b9b10` evaluator, `part-cell-flipbook-ramp.md`) and difftested
-/// against `ElwynnCampfire.m2`. These drive the believable flame fade / grow / flicker.
+/// The over-life ramps (+0x14c..) at normalized age `u = age / lifespan`: colour and size are
+/// 3-key ramps split at [`Self::mid`] into two linear segments, with a [`CellRamp`] per segment
+/// for the head and the tail (built at `0x70ebd0`, evaluated at `0x7b9b10`).
 #[derive(Debug, Clone, Copy)]
 pub struct OverLife {
-    /// Normalized age (`+0x14c`) splitting the two ramp segments. The reference's split is
-    /// **inclusive toward segment A** (`age > lifespan·mid` is the only way into B).
+    /// Normalized age (+0x14c) splitting the segments; only `age > lifespan·mid` enters B.
     pub mid: f32,
-    /// RGBA keys k0/k1/k2 (`+0x150/+0x154/+0x158`, packed BGRA u32 → linear 0..1). The **A** channel
-    /// is the particle's additive weight (its over-life opacity); there is no separate alpha array.
+    /// RGBA keys (+0x150/+0x154/+0x158, packed BGRA); A is the over-life opacity.
     pub color: [[f32; 4]; 3],
-    /// Uniform particle size keys k0/k1/k2 (`+0x15c/+0x160/+0x164`, yards).
+    /// Size keys (+0x15c/+0x160/+0x164), yards.
     pub scale: [f32; 3],
-    /// The **head** quad's flipbook ramp, per segment: A (`+0x168/+0x16a`), B (`+0x16e/+0x170`).
+    /// The head quad's ramp per segment: A (+0x168/+0x16a), B (+0x16e/+0x170).
     pub head_cells: [CellRamp; 2],
-    /// The **tail** streak's own, independent flipbook ramp: A (`+0x174/+0x176`), B
-    /// (`+0x178/+0x17a`). The reference emits two cell indices per particle and the tail quad reads
-    /// this one — a model whose tail ramp differs from its head ramp animates the streak
-    /// separately (wow-re `part-cell-flipbook-ramp.md` §4, correcting `part-quad-tail-twinkle.md`).
+    /// The tail streak's own ramp: A (+0x174/+0x176), B (+0x178/+0x17a), read at `0x7b304e`.
     pub tail_cells: [CellRamp; 2],
-    /// Per-segment flipbook **repeat count** (`+0x16c`/`+0x172`, `fild`-converted at load). `1.0`
-    /// (the ctor default, and what nearly all content authors) is one pass; anything else cycles
-    /// the cell ramp `fmod(t·repeat, 1.0)` times across the segment. Colour and size do not cycle.
+    /// Flipbook repeats per segment (+0x16c/+0x172): unless 1.0, the cells cycle `fract(t·repeat)`.
     pub repeat: [f32; 2],
 }
 
-/// One evaluation of the over-life ramps — the reference's `0x7b9b10` writes exactly these four
-/// outputs (colour, **two** cell indices, size) from one call.
+/// One evaluation of the over-life ramps: the four outputs of the reference's `0x7b9b10`.
 #[derive(Debug, Clone, Copy)]
 pub struct OverLifeSample {
-    /// Linear RGBA; the A channel is the particle's over-life opacity/additive weight.
+    /// Linear RGBA; A is the over-life opacity.
     pub color: [f32; 4],
     /// Half-extent in yards.
     pub size: f32,
-    /// Atlas cell for the head quad.
     pub head_cell: u16,
-    /// Atlas cell for the tail streak (independent of [`Self::head_cell`]).
     pub tail_cell: u16,
 }
 
@@ -196,35 +111,25 @@ impl OverLife {
     /// Sample every ramp at normalized age `u` (0..1).
     pub fn sample(&self, u: f32) -> OverLifeSample {
         let u = u.clamp(0.0, 1.0);
-        // A `mid` of 0 divides by zero in the reference (§7 of the wow-re note: it walks NaN into
-        // the sampler); no shipped emitter authors one, and we refuse to reproduce the fault.
+        // Deviation: `mid` is clamped to [1e-3, 1] because a 0 divides by zero in the reference
+        // (`0x7b9cf0`, walking NaN into the sampler); no shipped emitter authors one.
         let mid = self.mid.clamp(1e-3, 1.0);
         let (k0, k1, t, seg) = if u <= mid {
             (0, 1, u / mid, 0)
         } else {
             (1, 2, (u - mid) / (1.0 - mid).max(1e-3), 1)
         };
-        // **The endpoint inset, and it is the only normalized time the reference has.** `0x7b9b10`
-        // computes `t·0.99 + 0.005` once, over its own `age` argument slot, and every consumer
-        // reloads that slot — all four colour channels, the size, and both cell ramps (verified
-        // instruction by instruction, wow-re `part-cell-flipbook-ramp.md` §3a "scope of the
-        // inset"). So a particle at a segment's start sits **0.5 % along** its colour and size
-        // ramps, never exactly on the authored key, and 99.5 % at the end.
-        //
-        // For the CELLS the inset is not a rounding artefact but load-bearing: co-designed with
-        // the ramp's ±1, it is the only thing making `cell(0) == begin` and `cell(1) == end` hold
-        // in BOTH directions (a raw `t` floors one past the end going forward, one past the begin
-        // going backward). Exact while `0.005·N < 1` — 200 cells; the largest shipped atlas is 8×8.
+        // The reference's only normalized time: `0x7b9b10` computes `t·0.99 + 0.005` once for every
+        // ramp. With the cell ramp's ±1 it gives `cell(0) == begin` and `cell(1) == end` either
+        // way (exact below 200 cells; the largest shipped atlas is 8×8).
         let t = t.clamp(0.0, 1.0) * 0.99 + 0.005;
         let mut color = [0.0; 4];
         for (c, slot) in color.iter_mut().enumerate() {
             *slot = self.color[k0][c] + (self.color[k1][c] - self.color[k0][c]) * t;
         }
         let size = self.scale[k0] + (self.scale[k1] - self.scale[k0]) * t;
-        // The repeat count cycles the FLIPBOOK ONLY — an explicit verified negative, and visible in
-        // the reference's own ordering: colour and size are computed and stored out before the
-        // `rec+0x50 != 1.0` branch is even evaluated, and the wrapped coefficient never becomes `t`
-        // (§3b). So a 5× swarm emitter flaps its wings five times while fading exactly once.
+        // The repeat cycles the cells only: colour and size are stored before the `rec+0x50 != 1.0`
+        // branch (`0x7b9bcc`).
         let ct = if self.repeat[seg] != 1.0 {
             (t * self.repeat[seg]).fract()
         } else {
@@ -239,23 +144,20 @@ impl OverLife {
     }
 }
 
-/// A SPLINE (type-3) emitter's authored curve: a flattened **cubic Bézier chain** (K segments,
-/// `3K+1` control points: `P, out-tangent, in-tangent, P, …`), **arc-length parameterized** — the
-/// reference computes per-segment arc lengths into a knot array at load (`0x7b9a80` →
-/// `0x4532e0`; the knots are NOT on disk) and the spawn kernel's `t ∈ [0,1]` walks the chain by
-/// normalized arc length (wow-re `part-spline-file-layout.md` + `part-shape-kernels.md` §3). Our
-/// per-segment length is a 16-chord subdivision (the reference's `0x453e50` method is untraced —
-/// any smooth-curve length approximation lands within a fraction of a percent).
+/// A spline (type 3) emitter's curve: a cubic Bézier chain (`3K+1` points: P, out, in, P, …)
+/// walked by normalized arc length, whose knots the reference computes at load (`0x7b9a80` →
+/// `0x4532e0`) for the spawn kernel `0x7b9500`. A segment's length here is a 16-chord sum; the
+/// reference's method (`0x453e50`) is untraced.
 #[derive(Debug, Clone)]
 pub struct SplineData {
     /// Control points, model-local WoW axes (`3K+1`, from file+0x1d4/+0x1d8).
     pub points: Vec<[f32; 3]>,
-    /// Cumulative normalized arc length at each segment boundary (`K+1` entries, 0 → 1).
+    /// Cumulative normalized arc length at each segment boundary (`K+1` entries, 0 to 1).
     knots: Vec<f32>,
 }
 
 impl SplineData {
-    /// Build from the raw control points (must be `3K+1`; returns `None` below one segment).
+    /// From `3K+1` raw control points.
     pub fn new(points: Vec<[f32; 3]>) -> Option<Self> {
         let k = points.len().checked_sub(1)? / 3;
         if k == 0 || points.len() != 3 * k + 1 {
@@ -304,7 +206,6 @@ impl SplineData {
         std::array::from_fn(|c| (0..4).map(|i| w[i] * p[i][c]).sum())
     }
 
-    /// Locate `(segment, local u)` for a normalized arc fraction `t`.
     fn locate(&self, t: f32) -> (usize, f32) {
         let k = self.knots.len() - 1;
         let seg = self.knots[1..k]
@@ -315,8 +216,7 @@ impl SplineData {
         (seg, ((t - a) / (b - a).max(1e-6)).clamp(0.0, 1.0))
     }
 
-    /// The curve point at arc fraction `t` — first/last control point outside `[0,1]` (the
-    /// reference's `0x453390` clamp legs).
+    /// The point at arc fraction `t`, clamped to the end points outside [0, 1] (`0x453390`).
     pub fn eval(&self, t: f32) -> [f32; 3] {
         if t <= 0.0 {
             return self.points[0];
@@ -328,159 +228,95 @@ impl SplineData {
         Self::bezier(&self.points[3 * seg..3 * seg + 4], u)
     }
 
-    /// The (unnormalized) curve tangent at arc fraction `t` (the reference's `0x453420` leg —
-    /// its caller renormalizes).
+    /// The unnormalized tangent at arc fraction `t` (`0x453420`; its caller renormalizes).
     pub fn tangent(&self, t: f32) -> [f32; 3] {
         let (seg, u) = self.locate(t.clamp(0.0, 1.0));
         Self::bezier_deriv(&self.points[3 * seg..3 * seg + 4], u)
     }
 }
 
-/// One parsed vanilla M2 particle emitter, reduced to what the renderer needs. Positions/vectors are in
-/// **model-local** space (WoW axes, Z up) — compose with the instance world transform at spawn.
+/// One vanilla M2 particle emitter, positions and vectors model-local (WoW axes, Z up).
 #[derive(Debug, Clone)]
 pub struct ParticleEmitterDef {
     pub flags: u32,
-    /// Emitter origin, model-local. (Bone-follow @ +0x14 is deferred — static props sit on the root.)
     pub position: [f32; 3],
     pub bone: u16,
     pub shape: ParticleShape,
     pub blend: ParticleBlend,
-    /// Does the scene's light multiply this emitter's quads? See [`lit_of`] for the byte law — it
-    /// needs the RAW blend field, which [`ParticleBlend`] collapses (5/6 fold to `Alpha`), so the
-    /// verdict is baked here at parse rather than re-derived downstream.
+    /// Whether the scene light multiplies the quads (`lit_of`, from the raw blend byte).
     pub lit: bool,
-    /// **Geometry model** (file+0x18 count / +0x1c offset, an `M2Array<char>` path — wow-re
-    /// `part-model-particles.md`): when it names a resolvable `.m2`, this emitter spawns tiny
-    /// 3-D MODEL instances instead of billboard quads (Whirlwind's blades, Cone of Cold's
-    /// shards, the cyclones). `None` when unauthored.
+    /// Geometry model (+0x18, an `M2Array<char>` path, `0x7b1c80`): spawns models, not quads.
     pub geometry_model: Option<String>,
-    /// **Recursion model** (file+0x20 / +0x24 — wow-re `part-child-recursion.md`): the named
-    /// model's OWN particle emitters (capped at 4) become CHILD emitters driven once per live
-    /// parent particle per frame at the particle's position (Fire Blast's impact sparks, bomb
-    /// explosions). `None` when unauthored.
+    /// Recursion model (+0x20, `0x7b5dd0`, `0x7b5b9f`): up to 4 of its emitters run as children,
+    /// driven once per live parent particle per frame at that particle's position.
     pub recursion_model: Option<String>,
-    /// Particle texture (`.blp` path, as embedded in the M2 textures table). `None` if unresolved.
+    /// Particle texture, the `.blp` path from the M2 textures table.
     pub texture: Option<String>,
-    /// Texture atlas size for cell animation (`1×1` = a single static cell). **Both are non-zero
-    /// powers of two**: the reference's setter (`0x7b4ed0`) demands it — it derives `log2(cols)`
-    /// and the two reciprocals — and on a bad pair writes *none* of its five fields, leaving the
-    /// ctor's `1×1`. [`parse_m2_particle_emitters`] mirrors that fallback, so the atlas walk can
-    /// mask instead of divide. No shipped emitter trips it (corpus-swept, decision 0685).
+    /// Atlas rows (and `tile_cols` columns), both non-zero powers of two: on a bad pair the
+    /// reference's setter `0x7b4ed0` writes nothing and keeps its 1×1, and so does the parse.
     pub tile_rows: u16,
     pub tile_cols: u16,
-    /// 0 = head (camera quad), 1 = tail (speed-stretched), 2 = both. We render head first.
+    /// 0 head (camera-facing quad), 1 tail (velocity streak), 2 both.
     pub head_tail: u8,
-    /// The two per-frame-sampled emission tracks — spawn rate (`+0xdc`) and the ON/OFF gate
-    /// (`+0x1dc`) — baked **one loop per sequence** ([`EmitTiming`]).
+    /// Spawn rate (+0xdc) and the on/off gate (+0x1dc), baked one loop per sequence.
     pub timing: EmitTiming,
-    /// The other NINE emission M2Tracks (speed, speedVar, latitude, longitude, gravity, lifespan,
-    /// areaLength, areaWidth, zSource — bases `+0x34..+0x130`), baked the same way and sampled by
-    /// the sim **each frame on the emitter's clock** ([`EmitParams`]). These animate for real:
-    /// Frost Nova rides its emission radius 0.19 → 13.2 yd out with the expanding ring, Arcane
-    /// Explosion 0 → 7.2 yd with the growing dome — the retired `value[0]` flatten birthed both
-    /// entirely at the caster's feet (decision 0844).
+    /// The other nine emission tracks (+0x34..+0x130), baked the same way and sampled each frame
+    /// on the emitter's clock: they animate, so `value[0]` alone is wrong.
     pub params: EmitParams,
-    /// Velocity **drag** (file +0x194; a plain scalar, not a track — the builder copies it straight to
-    /// the runtime emitter's `+0x1e0` at `m2-decomp.c:8950`, *outside* the ten track setters). Each
-    /// frame the runtime applies `vel −= min(dt·drag, 1)·vel` (verified `particle_integrate` @
-    /// `0x7b2680`, step 4) — exponential
-    /// velocity decay that caps a particle's total travel near `speed/drag`. Load-bearing for props
-    /// that author a *fast, long-lived, zero-gravity* jet and rely on drag to contain it: e.g.
-    /// `CandelabraTallWall01` (speed 0.56, life 6, gravity 0, **drag 10** → a ~0.06 yd flicker; with
-    /// no drag the same particle coasts 3.3 yd to the ceiling). 0 = no drag.
+    /// Velocity drag (+0x194, a scalar copied to runtime +0x1e0 at `0x70ffdd`): each frame, after
+    /// gravity, `vel −= min(dt·drag, 1)·vel` (`0x7b2680`).
     pub drag: f32,
-    /// **Tail time** (file +0x17c, seconds — wow-re `part-quad-tail-twinkle.md`, their `65b8305b`):
-    /// a tail-mode particle (`head_tail` 1/2) renders a velocity-projected streak of world length
-    /// `|velocity| · tail_time`, trailing behind the motion; file flag `0x400` additionally clamps
-    /// the time to the particle's age (the streak grows from zero at birth).
+    /// Tail time (+0x17c, seconds; the quad writer's tail block `0x7b3041`): a tail particle draws
+    /// a streak `|velocity| · tail_time` long behind its motion.
     pub tail_time: f32,
-    /// **Tumble** — the model particles' angular-velocity range (file +0x19c min / +0x1a8 max,
-    /// C3Vectors, rad/s — wow-re `part-model-particles.md` §b): each birth rolls a body-frame
-    /// spin vector. The reference's roll carries a VERIFIED original-client asymmetry — only X
-    /// honors `min + u·range`; Y and Z multiply a raw `[1,2)` mantissa by their range alone
-    /// (their min is loaded but never read) — which a fidelity consumer must replicate.
+    /// Model particles' spin range (+0x19c min, +0x1a8 max, rad/s), rolled per birth at
+    /// `0x7b2420`: X takes `min + u·range`; Y and Z a raw [1, 2) mantissa × range, ignoring min.
     pub angular_velocity_min: [f32; 3],
     pub angular_velocity_max: [f32; 3],
-    /// **Emitter-motion inherit scale** (file +0x190 → runtime +0x1c4 — wow-re
-    /// `part-emitter-motion.md` §1, byte-verified `0x70ff71/0x70ff77`; closes the field the old
-    /// tail map left "?"): scales the inherited velocity a flag-0x40 emitter feeds its births
-    /// (see [`Self::inherits_emitter_motion`]).
+    /// Scales a flag-0x40 emitter's inherited velocity (+0x190, runtime +0x1c4 at
+    /// `0x70ff71`/`0x70ff77`).
     pub inherit_scale: f32,
-    /// **Follow pairs** (file +0x1c4..+0x1d0 — wow-re `part-emitter-motion.md` §2, the
-    /// `0x7b5d30` setter): two authored (emitter speed → follow fraction) samples defining the
-    /// follow-delta response line; see [`Self::follow_line`].
+    /// Two (emitter speed, follow fraction) samples (+0x1c4..+0x1d0) for [`Self::follow_line`].
     pub follow_speed1: f32,
     pub follow_scale1: f32,
     pub follow_speed2: f32,
     pub follow_scale2: f32,
-    /// **Twinkle** — the per-frame flicker modulation (file +0x180/+0x184/+0x188/+0x18c; wow-re
-    /// `part-simspace-fields.md`, byte-verified in the quad writer `0x7b2a50`). The rendered half-
-    /// size is the over-life scale ramp × a **gated** twinkle multiplier:
-    /// `min ≠ max ⇒ noise(speed·age)·(max − min) + min`, **skipped entirely when `min == max`**
-    /// (a degenerate range — `{0,0}` and `{1,1}` alike burn steady at ramp size; the kobold candle's
-    /// `{0,0}` is NOT size zero). This corrects the old `scale_base + rand·scale_variation` reading,
-    /// which inflated every `{1,1}` flame 1–2× and collapsed `{0,0}` to invisible.
+    /// Twinkle (+0x180..+0x18c; the quad writer `0x7b2a50`): the half-size is the over-life size
+    /// times [`Self::twinkle`], a multiplier skipped when `min == max`, so `{0,0}` burns steady at
+    /// ramp size. The loader `0x70ebd0` keeps min and the delta `max − min` (`rt+0x1c0`).
     pub twinkle_speed: f32,
-    /// Fraction of frames the particle draws at all while twinkling (the reference's separate
-    /// draw-gate; exact byte condition thin — consumers may treat `≥ 1` / `0` as always-draw).
+    /// Below 1, a frame whose twinkle noise exceeds it draws no quad (`0x7b2adc`).
     pub twinkle_percent: f32,
     pub twinkle_min: f32,
     pub twinkle_max: f32,
-    /// SPLINE (type-3) curve data — `Some` only when the record authors a valid Bézier chain
-    /// (file+0x1d4 count / +0x1d8 offset, `N = 3·⌊count/3⌋+1` C3Vectors — wow-re
-    /// `part-spline-file-layout.md`, VERIFIED). For splines the generic emission fields are
-    /// **repurposed** (each setter reads its track's `values[0]`): `area_length`/`area_width`
-    /// = **tMin/tMax** (the spawned arc-fraction window, clamped [0,1]), `vertical_range` =
-    /// the **tangent-spin range ψ** (birth velocity = +Z rotated about the local tangent by
-    /// S11·ψ), `horizontal_range` = the **scatter** (a `U01·scatter` position jitter along the
-    /// velocity), and the rate track's `values[0]` doubles as the load-time arcScale (a
-    /// one-frame transient — the per-frame rate sample overwrites it; we always sample the
-    /// track, so it needs no separate field).
+    /// Spline curve (+0x1d4 count, +0x1d8 offset, `3·⌊count/3⌋ + 1` points, `0x7b9a80`). A spline
+    /// repurposes the tracks' `values[0]`: `area_length`/`area_width` are the spawn window in
+    /// [0, 1], `vertical_range` a spin ψ about the tangent (birth velocity +Z turned by S11·ψ),
+    /// `horizontal_range` a `U01·scatter` jitter along the velocity, and the rate a load-time arc
+    /// scale that the first per-frame rate sample overwrites.
     pub spline: Option<SplineData>,
-    /// Quad **spin** (file +0x198 → runtime +0x18c): the billboard rotates in-plane by
-    /// `angle = spin · age` (rad; fcos/fsin @ `0x7b2ddc` in the quad writer). 0 = no rotation.
-    /// A **negative** spin is the author's alternating-direction switch: the writer negates the
-    /// (negative) angle on half the particles (pointer-bit-5 hash, `0x7b2dda`), counter-rotating
-    /// the cloud — vanilla's only rotation randomizer (the record has no phase/variance field).
+    /// Quad spin (+0x198, runtime +0x18c): rotation `spin · age` rad (`0x7b2ddc`); a negative spin
+    /// reverses on half the particles (a pointer-bit-5 hash, `0x7b2dda`).
     pub spin: f32,
-    /// Baked over-life ramps (color/opacity/size/cell) — see [`OverLife`].
     pub over_life: OverLife,
 }
 
 impl ParticleEmitterDef {
-    /// File flag `0x10` (→ runtime `0x100` — the loader's flag word is a **non-identity remap**,
-    /// wow-re `part-simspace-fields.md` corrections `1f40db0b`, byte block `0x70faf8–0x70fc44`):
-    /// **the storage-space choice, and so the ride-vs-trail switch** (wow-re
-    /// `part-emitter-motion.md` §2c, byte-settled). SET ⇒ the spawn stores raw emitter-LOCAL
-    /// pos/vel and the draw folds the live emitter matrix back in every frame: the whole cloud
-    /// rides the emitter rigidly, rotation and all (the chandelier's candle flames ride the swing;
-    /// a carried torch is flagged for it). CLEAR ⇒ the spawn bakes pos/vel into WORLD and the draw
-    /// never re-applies the emitter matrix: each particle **hangs where it was born**, so a moving
-    /// host lays a trail `host speed × particle lifetime` long.
-    ///
-    /// This doc said the opposite until 1578 — "a moving model carries its flame; there is NO
-    /// world-frozen trail mode" was the reading two earlier RE rounds built on a null test (a
-    /// kobold's 0.2 s candle smear, too small to see), and `part-emitter-motion.md` §2c refuted it
-    /// with the spawn/draw pairing plus a 7860-emitter corpus census.
+    /// File flag 0x10 (runtime 0x100; the flag remap `0x70faf8`..`0x70fc44` is not the identity).
+    /// Set, particles live emitter-local and the draw re-applies the live emitter matrix, so the
+    /// cloud rides the emitter; clear, the spawn bakes them into world space, so a moving host lays
+    /// a trail (spawn `0x7b8a9a`, draw `0x7b3ef9`).
     pub fn model_space(&self) -> bool {
         self.flags & 0x10 != 0
     }
-    /// File flag `0x4000` (→ runtime `0x40000` — wow-re `part-emitter-motion.md` §2/§2b,
-    /// §5-resolved): live particles keep exactly **[`Self::follow_line`]'s fraction (≤ 1) of
-    /// the emitter's per-frame world motion** — at saturation the trail rides the emitter
-    /// rigidly, below it lags toward a world-frozen trail; it never leads. (The reference's
-    /// baseline for this content class is world-frozen — its emitter motion folds into the
-    /// emitter matrix — and its `+fraction·Δ` add recovers the ride; over an anchor-riding
-    /// store the same observable is a `(fraction−1)·Δ` move.) The hunter missiles author it
-    /// (19 emitters / 15 spell models).
+    /// File flag 0x4000 (runtime 0x40000, added at `0x7b2744`): live particles move by
+    /// [`Self::follow_line`]'s fraction (≤ 1) of the emitter's per-frame motion; a store already
+    /// riding the emitter moves by `(fraction − 1)·Δ`.
     pub fn follow_emitter(&self) -> bool {
         self.flags & 0x4000 != 0
     }
-    /// The follow-delta response line (the reference's load-time `0x7b5d30`): `(slope,
-    /// intercept)` of the line through the two authored `(speed, fraction)` samples, so the
-    /// per-frame fraction is `clamp(slope·|Δpos|/dt + intercept, 0, 1)`. `None` when the two
-    /// speeds coincide (the reference zeroes both — no follow response).
+    /// `(slope, intercept)` through the two follow samples (`0x7b5d30`): the per-frame fraction is
+    /// `clamp(slope·|Δpos|/dt + intercept, 0, 1)`. Equal speeds give no response.
     pub fn follow_line(&self) -> Option<(f32, f32)> {
         ((self.follow_speed2 - self.follow_speed1).abs() >= 1e-6).then(|| {
             let slope = (self.follow_scale2 - self.follow_scale1)
@@ -488,86 +324,59 @@ impl ParticleEmitterDef {
             (slope, self.follow_scale1 - slope * self.follow_speed1)
         })
     }
-    /// File flag `0x40` (→ runtime `0x400` — wow-re `part-emitter-motion.md` §1, VERIFIED):
-    /// births inherit the emitter's recent motion. The emitter keeps a ~30 Hz inherit-velocity
-    /// vector — at each trigger (accumulated dt > 1/30 s), `oneFrameΔ · ((1/30)/accum) ·
-    /// inherit_scale`, zeroed while no particles are live — and each birth adds
-    /// `(1 + S11·speed_variation) · inherit` to its velocity (the shape kernels' closing
-    /// block). The enchant hands / Bloodlust / Death Wish family authors it (70 emitters / 33
-    /// spell models).
+    /// File flag 0x40 (runtime 0x400, `0x7b53ce`): births inherit the emitter's motion. Past each
+    /// 1/30 s of accumulated dt the inherit velocity becomes
+    /// `oneFrameΔ · ((1/30) / accum) · inherit_scale`, 0 while no particle lives, and each birth
+    /// adds `(1 + S11·speed_variation) · inherit` to its velocity.
     pub fn inherits_emitter_motion(&self) -> bool {
         self.flags & 0x40 != 0
     }
-    /// File flag `0x20` (→ runtime `0x200`): the rendered particle size is multiplied by the
-    /// emitter transform's scale magnitude. Torches/campfires author it; without it an
-    /// instance-scaled prop scales its particle *positions* only.
+    /// File flag 0x20 (runtime 0x200): particle size scales with the emitter transform's scale;
+    /// without it an instance-scaled prop scales only its particle positions.
     pub fn scale_size_by_instance(&self) -> bool {
         self.flags & 0x20 != 0
     }
-    /// File flag `0x100` on a **sphere** emitter (→ runtime `0x4000`, mapped only when the type
-    /// word is 2): birth velocity is straight `+Z` instead of radial through the shell point.
+    /// File flag 0x100 on a sphere (runtime 0x4000, mapped only for type 2): birth velocity is
+    /// straight +Z instead of radial.
     pub fn sphere_up(&self) -> bool {
         self.flags & 0x100 != 0
     }
-    /// File flag `0x80` on a **sphere** emitter (→ runtime `0x800` — like [`Self::sphere_up`]
-    /// the loader maps it only when the type word is 2, so a plane's authored `0x80` is dead
-    /// data): kill the particle the frame its motion turns AWAY from the emitter origin — the
-    /// integrator's tail tests `dot(stepVelocity, updatedPos) > 0` and returns dead (`0x7b2680`,
-    /// the `rt 0x800` branch). The suction containment: every corpus author pairs it with a
-    /// NEGATIVE emission speed (Blink/Conjure/Detect Magic converge inward), and the kill is
-    /// what stops the stream at the centre instead of letting it spray out the far side.
+    /// File flag 0x80 on a sphere (runtime 0x800, mapped only for type 2): a particle dies the
+    /// frame `dot(stepVelocity, updatedPos) > 0` (`0x7b2680`).
     pub fn kill_outbound(&self) -> bool {
         self.shape == ParticleShape::Sphere && self.flags & 0x80 != 0
     }
-    /// File flag `0x400` (→ runtime `0x10000`): a tail streak's `tail_time` is clamped to the
-    /// particle's age — the streak grows from zero at birth instead of popping in full-length.
+    /// File flag 0x400 (runtime 0x10000): the tail streak's `tail_time` is clamped to the
+    /// particle's age, so the streak grows from zero at birth.
     pub fn tail_clamps_to_age(&self) -> bool {
         self.flags & 0x400 != 0
     }
-    /// File flag `0x200` (→ runtime `0x8000` — wow-re `part-model-particles.md` §b): each
-    /// tumble axis's rolled angular velocity is independently sign-flipped with probability ½
-    /// (three extra draws) — the model particles' spin-direction randomizer.
+    /// File flag 0x200 (runtime 0x8000, tested in the spawn `0x7b2420`): each tumble axis's
+    /// angular velocity flips sign with probability ½.
     pub fn tumble_random_sign(&self) -> bool {
         self.flags & 0x200 != 0
     }
-    /// File flag `0x2000` (→ runtime `0x20000` — wow-re `part-groundsnap-zhook.md`, VERIFIED):
-    /// the **at-spawn ground snap**. Once, at each birth (anchored mode only — the shape
-    /// kernels call the hook `0x7b2140` inside their bit-0x100-CLEAR branch), the client
-    /// probes **20 yd straight down** for terrain OR WMO/doodad geometry (`0x672b60` →
-    /// `0x6aa160`, flags 0x100111); on a hit the particle's up-coordinate becomes `surfaceZ +
-    /// its birth over-life SIZE` (the sampler's float leg is the scale ramp — `0x7b9e20`
-    /// writes bank+0x24/+0x28 from file+0x15c/0x160/0x164 — so the quad stands ON the surface
-    /// by its half-extent). No surface within 20 yd leaves the spawn position untouched. NOT a
-    /// per-frame clamp, NOT terrain-only. Fire/Frost Nova, the ground fogs (37 emitters / 17
-    /// spell models).
+    /// File flag 0x2000 (runtime 0x20000): once per birth in anchored mode (hook `0x7b2140`), the
+    /// client probes 20 yd down for terrain, WMO or doodad geometry (`0x672b60` → `0x6aa160`,
+    /// flags 0x100111); on a hit the quad stands on the surface, its height the surface plus its
+    /// birth size (`0x7b9e20`).
     pub fn ground_snap(&self) -> bool {
         self.flags & 0x2000 != 0
     }
-    /// File flag `0x8000` (bit 15): the emission model is a **one-shot BURST**, not continuous.
-    /// The reference's per-frame emitter pass branches on this bit (`0x718ec8`): a burst emitter
-    /// gets a rising-edge trigger — the frame `(enabled && rate > 0)` first turns true it requests
-    /// ONE spawn of `ftol(rate · density · LOD)` particles (`0x7b5c50` → the spawn driver's
-    /// self-clearing burst branch `0x7b55ae`/`0x7b563d`) — and the continuous-enable bit is
-    /// skipped, so the `rate·dt` pour can never run for it. Re-arms only when the gate falls
-    /// (a looping clip's next pass). This flag is why the Feint/Eviscerate impact's plume and
-    /// crescents are over ~0.5 s while the same-shaped `Eviscerate_Cast_Hands` flame (bit clear)
-    /// pours for its whole 1.6 s clip (wow-re `part-emission-burst-flag.md`, byte-arbitrated).
+    /// File flag 0x8000, a one-shot burst (`0x718ec8`): when `enabled && rate > 0` first holds it
+    /// spawns `ftol(rate · density · LOD)` particles once (`0x7b5c50` → `0x7b55ae`/`0x7b563d`),
+    /// never pours `rate·dt`, and re-arms only when the gate falls.
     pub fn burst(&self) -> bool {
         self.flags & 0x8000 != 0
     }
-    /// File flag `0x1000` (→ runtime `0x2000`): the head quad does NOT billboard — it lies flat
-    /// in the emitter's model-space XY plane, carried by the live model→world matrix (the
-    /// community "XYQuad"; the impact crescents, state rings, fish-school splash rings).
-    /// Byte-pinned end to end in wow-re: corners = the ±1 XY unit square (z = 0) × the draw
-    /// matrix — camera-independent, unit half-extent exactly like the billboard corner table —
-    /// and quad spin is Rodrigues about the quad-plane normal (consumption
-    /// `part-quad-tail-twinkle.md` §3, builder semantics `part-tiled-corner-builder.md`, both
-    /// VERIFIED).
+    /// File flag 0x1000 (runtime 0x2000): the head quad lies flat in the emitter's model XY plane,
+    /// the ±1 unit square times the live draw matrix, spinning about its normal (`0x7b2c25`,
+    /// corner table `0x7b41a3`).
     pub fn xy_quad(&self) -> bool {
         self.flags & 0x1000 != 0
     }
-    /// The gated twinkle size multiplier, given a noise sample `noise ∈ [0,1)` from the caller's
-    /// LUT (indexed off `twinkle_speed · age`): identity when the range is degenerate.
+    /// The gated twinkle size multiplier for a noise sample in [0, 1) from the caller's LUT at
+    /// `twinkle_speed · age`: 1 when `min == max`.
     pub fn twinkle(&self, noise: f32) -> f32 {
         if (self.twinkle_max - self.twinkle_min).abs() < 1e-6 {
             1.0
@@ -594,10 +403,8 @@ fn le_vec3(b: &[u8], o: usize) -> [f32; 3] {
     [le_f32(b, o), le_f32(b, o + 4), le_f32(b, o + 8)]
 }
 
-/// Read one raw vanilla M2Track (28 bytes at `track`) into the shared typed shape — **absolute**
-/// key timestamps plus the per-sequence `ranges` windows the FN1 bake indexes. `benilla-m2` skips
-/// the cosmetic chunks, so the two emitter timing tracks are lifted here; `elem`/`read` decode one
-/// value (`f32`, or the enabled gate's `u8` projected to 0/1).
+/// One raw 28-byte vanilla M2Track at `track`: absolute key times and the per-sequence `ranges`;
+/// `read` decodes one `elem`-byte value.
 fn read_raw_track(
     b: &[u8],
     track: usize,
@@ -639,34 +446,19 @@ fn read_raw_track(
 fn blend_of(v: u8) -> ParticleBlend {
     match v {
         3 | 4 => ParticleBlend::Add,
-        2 | 5 | 6 => ParticleBlend::Alpha, // 5/6 (mod/mod2x) fold to alpha until a model needs them
+        2 | 5 | 6 => ParticleBlend::Alpha, // 5/6 (mod/mod2x): no modulate path yet
         1 => ParticleBlend::AlphaKey,
         _ => ParticleBlend::Opaque,
     }
 }
 
-/// `DAT_00811fa8` — the reference's per-blend-mode lighting table, indexed by the emitter's RAW
-/// blend field (file+0x28): the multiply/modulate modes light nothing, every other mode does
-/// (wow-re `part-scene-multipliers.md` §1, VERIFIED at `0x70bb0a`).
+/// The reference's per-blend lighting table (`0x811fa8`, read at `0x70bb0a`), indexed by the raw
+/// blend byte: the mod modes light nothing.
 const LIGHTING_BY_BLEND: [bool; 7] = [true, true, true, true, true, false, false];
 
-/// Does the reference draw this emitter's quads **LIT** by the scene?
-///
-/// A particle emitter has no material of its own: the reference *synthesizes* an `M2Material` from
-/// the file record every draw (`0x70d8b0`) and runs it through the SAME batch state producer as an
-/// ordinary mesh submesh, so `GL_LIGHTING` (EGxRs id `0x0e`) is decided exactly as it is for a
-/// mesh. Byte-verified at `0x70baf0` @`0x70bb00` (wow-re `part-scene-multipliers.md` §1):
-///
-/// ```text
-/// lit  ⇔  (file+0x04 bit 0x1 CLEAR)  AND  DAT_00811fa8[file+0x28] ≠ 0
-/// ```
-///
-/// **File bit `0x1` is the UNLIT flag** — the *inverse* of the wowdev-wiki lore ("0x1 = affected by
-/// lighting"), and matching the M2 render-flag `0x01 = unlit` convention everywhere else in the
-/// format. That polarity is the whole point: the fire/spell corpus authors `0x1` and stays bright at
-/// night, while the ambient environment sheets that CLEAR it — waterfall spray, chimney smoke,
-/// blown dust and snow — are shaded by the world's own light like the geometry they sit against.
-/// Rendering those unlit puts a full-white foam sheet in a shaded jungle (the Zul'Gurub waterfall).
+/// Whether the reference lights this emitter's quads: its synthesized per-draw material
+/// (`0x70d8b0`) decides `GL_LIGHTING` as a mesh's does (`0x70baf0`, at `0x70bb00`), lit iff file
+/// bit 0x1 is clear and `0x811fa8[blend]` is set. Bit 0x1 is unlit; wowdev has it inverted.
 fn lit_of(flags: u32, blend_byte: u8) -> bool {
     flags & 0x1 == 0
         && LIGHTING_BY_BLEND
@@ -683,11 +475,9 @@ fn shape_of(v: u16) -> ParticleShape {
     }
 }
 
-/// Parse the vanilla M2's particle emitters from its file bytes. Texture indices are resolved against
-/// the M2 textures table (parsed by `benilla-m2`; the particle *records* are read here). Returns an
-/// empty vec if the model has no emitters or isn't a parseable M2.
+/// The vanilla M2's particle emitters, textures resolved through `benilla-m2`'s textures table;
+/// empty for a model with none or a file that is not MD20.
 pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef>> {
-    // Texture names come from `benilla-m2`'s textures table.
     let textures: Vec<Option<String>> = match parse_m2(&mut Cursor::new(bytes)) {
         Ok(fmt) => fmt
             .model()
@@ -715,10 +505,8 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
         return Ok(Vec::new());
     }
 
-    // Every FILE sequence slot's band + loop flag (entry stride 0x44: band start/end @ +0x04/+0x08,
-    // flags @ +0x10, bit 0 CLEAR = loops) — the addressing unit the per-sequence timing bake needs,
-    // the same walk as `m2_batches`. A sequence-less model gets one synthetic whole-timeline slot
-    // so an authored track still bakes (raw timestamps, the pre-sequence degenerate).
+    // Each sequence's band and loop flag (flags bit 0 clear loops); a model with none gets one
+    // whole-timeline slot so its tracks still bake.
     let mut seq_slots: Vec<SeqSlot> = {
         let (n, o) = (le_u32(bytes, 0x1c) as usize, le_u32(bytes, 0x20) as usize);
         (0..n)
@@ -739,8 +527,7 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
             looping: true,
         });
     }
-    // The global-sequence duration table (header +0x14/+0x18) — a gseq-tagged timing track loops
-    // on its own free clock, same law as every other channel.
+    // Global-sequence durations (header +0x14/+0x18): a gseq-tagged track loops on its own clock.
     let gseq: Vec<u32> = {
         let (n, o) = (le_u32(bytes, 0x14) as usize, le_u32(bytes, 0x18) as usize);
         (0..n)
@@ -748,7 +535,6 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
             .collect()
     };
 
-    // Decode a packed BGRA `CImVector` color key → linear RGBA 0..1 (A = over-life opacity).
     let color_key = |o: usize| -> [f32; 4] {
         let v = le_u32(bytes, o);
         [
@@ -765,8 +551,7 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
         let tex_index = le_u16(bytes, e + 0x16) as usize;
         let texture = textures.get(tex_index).cloned().flatten();
         let shape = shape_of(le_u16(bytes, e + 0x2a));
-        // The two per-emitter model paths (`M2Array<char>`, offset pre-fixup = file-relative):
-        // geometry (model particles) and recursion (child emitters).
+        // The geometry and recursion model paths (`M2Array<char>`, file-relative offsets).
         let model_path = |cnt_off: usize| -> Option<String> {
             let n = le_u32(bytes, e + cnt_off) as usize;
             let ofs = le_u32(bytes, e + cnt_off + 4) as usize;
@@ -780,8 +565,6 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
         };
         let geometry_model = model_path(0x18);
         let recursion_model = model_path(0x20);
-        // SPLINE control points (file+0x1d4/+0x1d8, raw M2Array dwords): the reference copies
-        // N = 3·⌊count/3⌋+1 C3Vectors — the flattened cubic Bézier chain.
         let spline = (shape == ParticleShape::Spline)
             .then(|| {
                 let q = le_u32(bytes, e + 0x1d4) as usize;
@@ -793,8 +576,6 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
                 SplineData::new((0..n).map(|p| le_vec3(bytes, ofs + p * 12)).collect())
             })
             .flatten();
-        // ROWS @+0x30 / COLUMNS @+0x32, both required non-zero powers of two — the reference's
-        // `0x7b4ed0` bails on a bad pair having written nothing, leaving its ctor's 1×1.
         let tiles = match (le_u16(bytes, e + 0x30), le_u16(bytes, e + 0x32)) {
             (r, c) if r.is_power_of_two() && c.is_power_of_two() => (r, c),
             _ => (1, 1),
@@ -811,10 +592,8 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
                 le_f32(bytes, e + 0x160),
                 le_f32(bytes, e + 0x164),
             ],
-            // The +0x168..+0x17b block is TEN u16s, read `{head A, head B, tail A, tail B}` with a
-            // repeat count wedged after each head pair — not the eight that wowdev's
-            // `lifespanUVAnim[3]/decayUVAnim[3]/tailUVAnim[2]` naming implies (wow-re
-            // `part-cell-flipbook-ramp.md` §1; +0x17c is already the tail LENGTH dword).
+            // Ten u16s at +0x168..+0x17b (`0x70ebd0`), a repeat count after each head pair, not
+            // the eight wowdev's `*UVAnim` names imply.
             head_cells: [
                 CellRamp::new(le_u16(bytes, e + 0x168), le_u16(bytes, e + 0x16a)),
                 CellRamp::new(le_u16(bytes, e + 0x16e), le_u16(bytes, e + 0x170)),
@@ -848,8 +627,6 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
                 &seq_slots,
                 &gseq,
             ),
-            // The nine parameter tracks, full-key ([`EmitParams`] field order — bases 0x1c apart,
-            // the emitter phase's own walk). NOT `value[0]`: several effects animate them.
             params: EmitParams::bake(
                 [
                     &read_raw_track(bytes, e + 0x34, 4, le_f32),  // speed
@@ -889,38 +666,25 @@ pub fn parse_m2_particle_emitters(bytes: &[u8]) -> Result<Vec<ParticleEmitterDef
 mod tests {
     use super::*;
 
-    /// **File bit 0x1 is UNLIT, not "lit"** — the polarity this whole mechanism turns on, and the
-    /// one the community table gets backwards (wowdev: "0x1 = affected by lighting"; the binary
-    /// forces `GL_LIGHTING` OFF on that bit, wow-re `part-scene-multipliers.md` §1 @`0x70bb00`).
-    /// Inverting it would light exactly the wrong 95% of the corpus: every fire and spell effect
-    /// would go dim at night while the environment sheets stayed full-white cutouts — a change
-    /// that "works" on any single model you happen to check first.
     #[test]
     fn bit_one_is_the_unlit_flag_and_mod_blends_never_light() {
-        // The Zul'Gurub / Elwynn waterfall: bit 0x1 CLEAR, blend 2 (alpha) ⇒ the scene lights it.
+        // The Elwynn waterfall: bit 0x1 clear, blend 2 (alpha), so the scene lights it.
         assert!(
             lit_of(0x0002, 2),
             "an emitter that CLEARS 0x1 takes the light"
         );
-        // The Orgrimmar bonfire's flame (0x29) and smoke (0x21): both SET 0x1 ⇒ both unlit, which
-        // is what keeps a campfire bright at night.
+        // The Orgrimmar bonfire's flame (0x29) and smoke (0x21) set 0x1, so both are unlit.
         assert!(!lit_of(0x0029, 4), "0x1 set: unlit, whatever the blend");
         assert!(!lit_of(0x0021, 2));
-        // `DAT_00811fa8` = {1,1,1,1,1,0,0}: the multiply modes light nothing even with 0x1 clear —
-        // a lit modulate would darken twice, once through the light and once through the blend.
         for blend in 0u8..=4 {
             assert!(lit_of(0x0000, blend), "blend {blend} lights");
         }
         assert!(!lit_of(0x0000, 5), "Mod never lights");
         assert!(!lit_of(0x0000, 6), "Mod2x never lights");
-        // A blend byte past the table is not a panic and not a silent "unlit" — the reference
-        // indexes a 7-entry table it never overruns, and every such value already folds to
-        // `Opaque`, which lights.
+        // A byte past the 7-entry table folds to `Opaque`, which lights.
         assert!(lit_of(0x0000, 7));
     }
 
-    /// The real corpus, at the emitter the director reported: the waterfall's ONE emitter clears
-    /// bit 0x1 and blends alpha, so it must come back LIT — the asset-side half of the foam fix.
     #[test]
     fn the_waterfall_emitter_is_lit() {
         let data = crate::wow_data_or_skip!();
@@ -937,9 +701,8 @@ mod tests {
         assert!(defs[0].lit, "the spray sheet is shaded by the world");
     }
 
-    /// The spline chain is **arc-length** parameterized: two straight segments of length 1 and
-    /// 3 (control points at exact thirds, so the cubic degenerates to linear) put the segment
-    /// boundary at t = 0.25, not 0.5 — plus the reference's outside-[0,1] clamp legs.
+    /// Straight segments of 1 and 3 yd (control points at thirds, so each cubic is linear) put
+    /// the boundary at t = 0.25, not 0.5.
     #[test]
     fn spline_chain_is_arc_length_parameterized() {
         let x = |v: f32| [v, 0.0, 0.0];
@@ -962,10 +725,7 @@ mod tests {
         assert!(SplineData::new(vec![x(0.0)]).is_none(), "below one segment");
     }
 
-    /// The real `BloodSpurt.m2` (decision 0140 fold-back — the melee impact flash): 4 emitters,
-    /// and the three the old `value[0]` bake silently killed are **keyed bursts** — the starflash
-    /// (STARFLASH_GREY, additive) rates 0→20→0 over the first 133 ms. Pins the burst keys and
-    /// that the spray (emitter 0) still reads its constant-equivalent first key of 100/s.
+    /// `BloodSpurt.m2`, the melee impact flash: emitters 1 to 3 are keyed bursts.
     #[test]
     fn real_blood_spurt_emitters_are_keyed_bursts() {
         let data = crate::wow_data_or_skip!();
@@ -975,10 +735,9 @@ mod tests {
             .expect("read BloodSpurt.m2");
         let defs = parse_m2_particle_emitters(&bytes).expect("parse emitters");
         assert_eq!(defs.len(), 4);
-        // Emitter 0 — the red spray: starts hot (100/s at t=0), the old bake's one working case.
+        // Emitter 0, the red spray: 100/s at t = 0.
         assert_eq!(defs[0].timing.rate(None, 0.0, 0.0), 100.0);
-        // Emitter 3 — the starflash: additive, STARFLASH texture, burst-keyed (first key 0,
-        // peak 20/s inside the 67–100 ms window, dead again by 133 ms).
+        // Emitter 3, the starflash: first key 0, 20/s within 67..100 ms, 0 again by 133 ms.
         let flash = &defs[3];
         assert!(flash
             .texture
@@ -989,21 +748,16 @@ mod tests {
         assert_eq!(flash.timing.peak_rate(), 20.0);
         assert_eq!(flash.timing.rate(None, 0.080, 0.0), 20.0);
         assert_eq!(flash.timing.rate(None, 0.200, 0.0), 0.0);
-        // Emitters 1/2 — the glowball droplets, same burst shape, peaks 200.
+        // Emitters 1 and 2, the glowball droplets: the same burst shape, peaking at 200.
         assert_eq!(defs[1].timing.peak_rate(), 200.0);
         assert_eq!(defs[2].timing.peak_rate(), 200.0);
-        // The spray's enabled track cuts emission at 500 ms — exactly where its rate track goes
-        // negative (the authored tail the old always-on read let the floor-at-0 hide).
+        // The spray's enabled track cuts emission at 500 ms, where its rate track goes negative.
         assert!(defs[0].timing.emitting(None, 0.4, 0.0));
         assert!(!defs[0].timing.emitting(None, 0.6, 0.0));
     }
 
-    /// The real `Feint_Impact_Chest.m2` (the Eviscerate/Feint impact) — the BURST-flag split
-    /// that bounds its visible burst at ~0.5 s on the reference: plume (e0) and crescents (e3)
-    /// author file flag 0x8000 (one-shot burst — a single `ftol(rate)` puff at their 67 ms key),
-    /// lava (e1) and dust (e2) are continuous, choreographed by their enabled windows. The
-    /// cast-side `Eviscerate_Cast_Hands.m2` is the counter-case: the same 1.6 s asset shape with
-    /// bit 15 clear — a continuous pour for the whole clip.
+    /// `Feint_Impact_Chest.m2`: the plume (e0) and crescents (e3) set flag 0x8000, one puff at
+    /// their 67 ms key; `Eviscerate_Cast_Hands.m2` has the same 1.6 s shape with the flag clear.
     #[test]
     fn real_feint_impact_authors_burst_emitters() {
         let data = crate::wow_data_or_skip!();
@@ -1019,8 +773,7 @@ mod tests {
         assert!(!impact[1].burst(), "lava pours (enabled window 0–333 ms)");
         assert!(!impact[2].burst(), "dust pours (enabled window 67–200 ms)");
         assert!(impact[3].burst(), "crescents are a one-shot burst");
-        // The STEP rate law that arms the burst count: silent before the 67 ms key, the full
-        // value at it, held past it (where the burst latch keeps it from ever mattering).
+        // A step rate: 0 before the 67 ms key, its full value from it on.
         assert_eq!(impact[0].timing.rate(None, 0.050, 0.0), 0.0);
         assert_eq!(impact[0].timing.rate(None, 0.067, 0.0), 30.0);
         assert_eq!(impact[0].timing.rate(None, 1.500, 0.0), 30.0);
@@ -1036,11 +789,7 @@ mod tests {
         );
     }
 
-    /// The real `FlameStrike_Area.m2` — the spline-record law on real content (the
-    /// `part-spline-file-layout.md` corpus caveat, resolved): e2..e5 are type-3 emitters whose
-    /// control-point counts land exactly on the `3K+1` flattened-Bézier law (16 and 19), with
-    /// the repurposed fields reading sanely (t window [0,1], no spin/scatter — the fire
-    /// columns sit ON their authored descent curves with zero birth velocity).
+    /// `FlameStrike_Area.m2`'s four fire columns: type-3 chains of 16 and 19 points, no spin.
     #[test]
     fn real_flamestrike_authors_spline_chains() {
         let data = crate::wow_data_or_skip!();
@@ -1065,7 +814,6 @@ mod tests {
             assert_eq!(now.area_width, 1.0, "tMax");
             assert_eq!(now.vertical_range, 0.0, "no tangent spin");
             assert!(d.burst(), "one puff of standing flames");
-            // The chain starts high (the authored descent) — a sane, in-model coordinate.
             assert!(
                 (5.0..15.0).contains(&s.points[0][2]),
                 "z {}",
@@ -1075,11 +823,8 @@ mod tests {
         }
     }
 
-    /// The real `Fire_Cast_Hand.m2` (spell 133's "go" flash) and `MoltenBlast_Impact_Chest.m2`
-    /// (its impact): the authored choreography this parse exists to carry. Cast hand: constant
-    /// rates, enabled for exactly the first 200 ms of the clip. Impact emitter 0 (the plume
-    /// burst): rate ramps 0→60 across the first 133 ms — a full second late under the old raw
-    /// global-timeline read (seq 0 spans [1000, 2600]).
+    /// Fireball (spell 133): the cast flash is on for its clip's first 200 ms and the impact plume
+    /// ramps 0 → 60 over 133 ms of clip time, though seq 0 spans [1000, 2600] of the file.
     #[test]
     fn real_fireball_effects_rebase_to_clip_time() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/pet_stats.rs b/crates/benilla-formats/src/pet_stats.rs
index 82781d71..9a38d6cd 100644
--- a/crates/benilla-formats/src/pet_stats.rs
+++ b/crates/benilla-formats/src/pet_stats.rs
@@ -1,39 +1,8 @@
-//! `PetPersonality.dbc` + `PetLoyalty.dbc` — the two tables behind a hunter pet's happiness and
-//! loyalty readouts (decision 1005; wow-re `ui/scratch/pet-action-bar-api.md` §11b).
-//!
-//! **`GetPetHappiness` does its own thresholding.** The client does not hand Lua a raw happiness
-//! number for the UI to bucket — it returns a **pre-bucketed 1/2/3** plus the two numbers that
-//! bucket implies, from a three-column-triple row (`0x4be947`–`0x4be9c3`):
-//!
-//! ```text
-//! rec = <table>[personalityId]           ; missing/out-of-range -> FALLBACK rec = <table>[1]
-//! raw = UNIT_FIELD_POWER5                ; the happiness power
-//! esi = 0; while (esi < 3 && raw >= rec[0x28 + 4*esi]) esi++      ; the three thresholds
-//! ret1 = esi                             ; 0..3
-//! ret2 = rec[0x30 + 4*esi] * 100.0f      ; damage percentage   (esi >= 1)
-//! ret3 = rec[0x3c + 4*esi]               ; loyalty rate        (esi >= 1, may be NEGATIVE)
-//! ```
-//!
-//! **Which `.dbc` backs it was NOT carved** — wow-re records `[0xc0d9e0]`/`[0xc0d9e4]` only as an
-//! anonymous BSS `{indexTable, maxId}` pair, and the dispatch that produced the carve glossed the
-//! index as a *creature family*. That gloss is wrong, and the file settles it: `CreatureFamily.dbc`
-//! has a **0x48-byte** record — the read at `rec+0x48` would run off the end — and every dword from
-//! `0x28` up is zero in all 23 rows. `PetPersonality.dbc` is a 0x4c-byte record whose last nine
-//! columns are exactly the three triples, at exactly those offsets:
-//!
-//! | id | thresholds `0x28` | damage `0x34` | loyalty rate `0x40` |
-//! |---|---|---|---|
-//! | 1 | 0 / 333000 / 666000 | 0.75 / 1.00 / 1.25 | −10 / 5 / 20 |
-//! | 3 | 0 / 250000 / 750000 | 0.00 / 1.00 / 1.25 | −1 / 0 / 2 |
-//!
-//! Row 1 is vanilla's documented pet-happiness behaviour on the nose — unhappy pets deal 75%
-//! damage, content 100%, happy 125%, against a happiness power that runs 0…1,000,000 in thirds —
-//! which is the independent corroboration that this is the table and row 1 is the row live pets
-//! use. (See [`PetPersonalities::for_pet`] for what is still open: *which field* selects the row.)
-//!
-//! `PetLoyalty.dbc` is the plain half: 8 rows, `ID` + the localized `Name` block, read at
-//! `[[0xc0d9f4][lvl] + 4*locale + 4]` — i.e. `Name` enUS is field 1, the same shape every other
-//! localized table here uses.
+//! `PetPersonality.dbc` and `PetLoyalty.dbc`, behind a hunter pet's happiness and loyalty
+//! readouts. `GetPetHappiness` buckets on its own (`0x4be947`-`0x4be9c3`), counting the row's
+//! thresholds the happiness power (`UNIT_FIELD_POWER5`) meets. Its store, `[0xc0d9e0]`/`[0xc0d9e4]`
+//! (rows and max id), is `PetPersonality.dbc` (loader `0x54bce0`), whose `0x4c`-byte rows end in
+//! the three triples; `GetPetLoyalty` reads `PetLoyalty.dbc` at `[[0xc0d9f4][lvl] + 4*locale + 4]`.
 
 use std::collections::HashMap;
 
@@ -46,61 +15,48 @@ use crate::dbc::{f32_at, parse, str_at, u32_at};
 const PET_PERSONALITY: &str = "DBFilesClient\\PetPersonality.dbc";
 const PET_LOYALTY: &str = "DBFilesClient\\PetLoyalty.dbc";
 
-/// `PetPersonality.dbc`'s column count (the DBC header's `field_count`; `benilla-dbc` enforces it).
+/// `PetPersonality.dbc`'s column count, which `benilla-dbc` checks against the header.
 const PERSONALITY_FIELDS: usize = 19;
-/// `PetLoyalty.dbc`'s column count.
 const LOYALTY_FIELDS: usize = 10;
-/// The localized `Name` block's enUS column — field 1 in both files, and the `+4` in the client's
-/// own `[row + 4*locale + 4]`.
+/// The enUS `Name` column in both files, the `+4` in the client's `[row + 4*locale + 4]`.
 const NAME_FIELD: usize = 1;
 
-/// The first threshold column: byte `0x28` = field 10.
 const THRESHOLD_FIELD: usize = 0x28 / 4;
-/// The first damage-percentage column: byte `0x34` = field 13.
 const DAMAGE_FIELD: usize = 0x34 / 4;
-/// The first loyalty-rate column: byte `0x40` = field 16.
 const LOYALTY_RATE_FIELD: usize = 0x40 / 4;
 
-/// The personality id the client falls back to when it cannot resolve one (`0x4be96c`: `rec` null
-/// or the index out of range ⇒ `rec = indexTable[1]`). Not a benilla convention — the reference's
-/// own second chance, and the row every live pet is observed to use.
+/// The personality the client falls back to when the id is out of range or its row is missing
+/// (`0x4be96c`), "Personality: Standard".
 pub const FALLBACK_PERSONALITY: u32 = 1;
 
-/// One `PetPersonality` row's three parallel triples, indexed by the happiness bucket.
-///
-/// The triples are **1-based against the bucket**: bucket 1 reads slot 0. Bucket 0 never indexes
-/// them at all — the client jumps straight to the shared `(100.0, 0.0)` tail — which is why
-/// [`PetHappiness`] carries the numbers rather than the caller doing the offset arithmetic.
+/// One `PetPersonality` row's triples, read 1-based: bucket 1 reads slot 0, bucket 0 reads none.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct PetPersonality {
     /// The three ascending happiness thresholds the raw power is counted against.
     pub thresholds: [u32; 3],
-    /// Damage multiplier per bucket, as stored (`0.75` = 75%). The binding scales by 100.
+    /// Damage multiplier per bucket as stored (`0.75` is 75%).
     pub damage: [f32; 3],
-    /// Loyalty gain rate per bucket. **May be negative** — an unhappy pet loses loyalty.
+    /// Loyalty gain rate per bucket, negative for an unhappy pet.
     pub loyalty_rate: [f32; 3],
 }
 
 /// What `GetPetHappiness` answers: the bucket plus the two numbers it selects.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct PetHappiness {
-    /// `0..=3`. **`0` is not the failure case** — the client pushes it as the number `0` and takes
-    /// the same tail as a gate failure, and the shipped `PetFrame.lua` has no branch for it, so the
-    /// icon keeps whatever texcoords it had. Keep it distinct from "no answer at all".
+    /// `0..=3`. `0` is a number, not the failure case: the client pushes `0` with the failure's
+    /// tail, and `PetFrame.lua`, with no branch for it, keeps the icon's old texcoords.
     pub bucket: u32,
-    /// Return 2 — the damage percentage, already scaled by the client's own `100.0f`
-    /// (`[0x806b10]`). `100.0` for bucket 0.
+    /// The damage percentage, times the client's `100.0f` (`[0x806b10]`); `100.0` for bucket 0.
     pub damage_percentage: f32,
-    /// Return 3 — the loyalty rate, unscaled and possibly negative. `0.0` for bucket 0.
+    /// The loyalty rate, unscaled and possibly negative; `0.0` for bucket 0.
     pub loyalty_rate: f32,
 }
 
 impl PetPersonality {
-    /// Bucket a raw happiness power and pick the row's two numbers — `0x4be981`'s count loop and
-    /// the two indexed reads after it, transcribed.
+    /// Bucket a raw happiness power and pick the row's two numbers (`0x4be981`).
     pub fn happiness(&self, raw: u32) -> PetHappiness {
         let bucket = self.thresholds.iter().take_while(|&&t| raw >= t).count();
-        // Bucket 0 shares the gate-failure tail (`0x4be9a8 je 0x4be9e9`) rather than indexing.
+        // Bucket 0 takes the gate-failure tail (`0x4be9a8 je 0x4be9e9`) instead of indexing.
         let Some(i) = bucket.checked_sub(1) else {
             return PetHappiness {
                 bucket: 0,
@@ -120,17 +76,9 @@ impl PetPersonality {
 pub struct PetPersonalities(HashMap<u32, PetPersonality>);
 
 impl PetPersonalities {
-    /// The row for a pet whose personality id is `id`, with the client's own fallback applied.
-    ///
-    /// **`id` is `None` today, always, and that is a recorded gap rather than an oversight.** The
-    /// client selects the row with `0x605600(pet)` = `[[pet+0xb30]+0x24]` — a field of its cached
-    /// creature template — and wow-re has carved neither which template field `+0x24` is nor which
-    /// table it indexes. Passing `None` takes the reference's *own* out-of-range path
-    /// ([`FALLBACK_PERSONALITY`]), which is what every live pet is observed to land on: the file
-    /// ships two rows, ids 1 and 3, and row 1 alone reproduces vanilla's 75/100/125% damage.
-    ///
-    /// So the shape is right and the numbers are right; when the selector is carved, this call
-    /// gains an argument and nothing else moves.
+    /// The row for personality `id`, or the client's fallback row. The reference keys this table
+    /// by `[[pet+0xb30]+0x24]` (`0x605600`), a field of the cached creature-query record whose
+    /// wire source is untraced, so callers pass `None` and get row 1.
     pub fn for_pet(&self, id: Option<u32>) -> Option<&PetPersonality> {
         id.and_then(|i| self.0.get(&i))
             .or_else(|| self.0.get(&FALLBACK_PERSONALITY))
@@ -145,13 +93,12 @@ impl PetPersonalities {
     }
 }
 
-/// `PetLoyalty.dbc`: loyalty level → its localized name.
+/// `PetLoyalty.dbc`: loyalty level to its localized name.
 pub struct PetLoyaltyNames(HashMap<u32, String>);
 
 impl PetLoyaltyNames {
-    /// The name for a loyalty level, or `None` — which is `GetPetLoyalty`'s **nil**, and it is nil
-    /// for level `0` as well as for anything past the table (`0x4be700`'s bound against
-    /// `[0xc0d9f8]`, plus `lua_pushstring`'s own NULL→nil).
+    /// The name for a loyalty level. `None` is `GetPetLoyalty`'s nil, for level `0` and past the
+    /// table (`0x4be700` bounds it against `[0xc0d9f8]`).
     pub fn name(&self, level: u32) -> Option<&str> {
         (level != 0).then(|| self.0.get(&level).map(String::as_str))?
     }
@@ -172,8 +119,7 @@ fn personality_schema() -> Schema {
             NAME_FIELD => FieldType::String,
             i if (DAMAGE_FIELD..DAMAGE_FIELD + 3).contains(&i) => FieldType::Float32,
             i if (LOYALTY_RATE_FIELD..LOYALTY_RATE_FIELD + 3).contains(&i) => FieldType::Float32,
-            // ID, the rest of the localization block, and the three thresholds (which the client
-            // compares as integers against an integer power field).
+            // ID, the rest of the name block, and the thresholds, compared as integers.
             _ => FieldType::UInt32,
         };
         s.add_field(SchemaField::new(format!("F{i}"), ty));
@@ -242,9 +188,6 @@ mod tests {
         Some(crate::open_chain(&data).expect("open chain"))
     }
 
-    /// The real 5875 `PetPersonality.dbc`, byte-anchored. A column slip here is silent and
-    /// catastrophic — the thresholds and the damage triple are adjacent, so reading one for the
-    /// other yields plausible-looking numbers and a pet that is permanently "unhappy".
     #[test]
     fn the_real_personality_rows_carry_vanillas_own_happiness_numbers() {
         let Some(mut chain) = chain() else { return };
@@ -263,21 +206,18 @@ mod tests {
         let three = t.for_pet(Some(3)).expect("id 3");
         assert_eq!(three.thresholds, [0, 250_000, 750_000]);
 
-        // The client's own fallback, and the reason it is load-bearing for us: an unresolved
-        // personality is the ONLY path we take today, and it must land on row 1.
+        // The client's fallback, the path every caller takes, lands on row 1.
         assert_eq!(t.for_pet(None), t.for_pet(Some(1)));
         assert_eq!(t.for_pet(Some(999)), t.for_pet(Some(1)));
     }
 
-    /// The bucket loop against the shipped row 1, at the boundaries — and the ×100 scaling, which
-    /// is the client's and not the UI's.
     #[test]
     fn the_bucket_loop_counts_thresholds_met() {
         let Some(mut chain) = chain() else { return };
         let t = load_pet_personalities(&mut chain).expect("load");
         let p = *t.for_pet(None).expect("fallback row");
 
-        // Happiness runs 0..1_000_000 in thirds. Every reachable raw value buckets 1..3.
+        // Happiness runs 0..1_000_000 in thirds, so every reachable value buckets 1..3.
         for (raw, bucket, dmg) in [
             (0, 1, 75.0),
             (332_999, 1, 75.0),
@@ -297,9 +237,7 @@ mod tests {
         assert_eq!(p.happiness(1_000_000).loyalty_rate, 20.0);
     }
 
-    /// Bucket 0 is structurally reachable (a row whose first threshold is above the raw value) and
-    /// is NOT the failure case: it answers the number `0` with the same `(100.0, 0.0)` tail a gate
-    /// failure uses. A re-implementation that folded it into nil would hide the pet frame.
+    /// Bucket 0 is reachable only through a row whose first threshold is above the raw value.
     #[test]
     fn bucket_zero_is_a_number_not_a_failure() {
         let p = PetPersonality {
@@ -312,13 +250,7 @@ mod tests {
         assert_eq!((h.damage_percentage, h.loyalty_rate), (100.0, 0.0));
     }
 
-    /// The eight real loyalty names, verbatim, and the two nil cases the binding must reproduce.
-    ///
-    /// **The shipped strings carry a `"(Loyalty Level N) "` prefix** — developer annotation left in
-    /// the data, and the client pushes the column with no stripping whatsoever
-    /// (`lua_pushstring` of `[row + 4*locale + 4]`). So that prefix is what the pet paper doll
-    /// shows, and trimming it here would be a "tidier than the reference" divergence. Levels 7 and
-    /// 8 are `"Loyalty Cap"` and `"Unused"`: the ladder players actually climb is 1–6.
+    /// The paper doll shows the shipped `"(Loyalty Level N) "` prefix: the client never strips it.
     #[test]
     fn the_real_loyalty_levels_are_named_verbatim() {
         let Some(mut chain) = chain() else { return };
diff --git a/crates/benilla-formats/src/quest_headers.rs b/crates/benilla-formats/src/quest_headers.rs
index d0f2ad98..02e1320c 100644
--- a/crates/benilla-formats/src/quest_headers.rs
+++ b/crates/benilla-formats/src/quest_headers.rs
@@ -1,12 +1,5 @@
-//! Quest-log **header names**: the quest template's `ZoneOrSort` → the section title the list
-//! groups under ("Northshire Valley", "Warlock", …).
-//!
-//! The 1.12 client resolves the sign split the same way: **positive** = an `AreaTable.dbc` id
-//! (the zone/subzone name), **negative** = a `QuestSort.dbc` id (class/profession/seasonal sort
-//! names). Layouts:
-//! - `AreaTable.dbc` 25 × u32 cols: `ID(0) … AreaName(11)` + loc block (the audio catalog's
-//!   `area_sound.rs` documents the head; only ID + name matter here).
-//! - `QuestSort.dbc` 10 × u32 cols: `ID(0), SortName(1)` + the rest of the loc block.
+//! Quest log header names. As in the 1.12 client, a quest's `ZoneOrSort` is an `AreaTable.dbc` id
+//! when positive and a negated `QuestSort.dbc` id (class, profession, seasonal) when negative.
 
 use std::collections::HashMap;
 
@@ -15,18 +8,15 @@ use anyhow::Result;
 use crate::chain::Chain;
 use crate::dbc::load_id_name_table;
 
-/// The resolved `ZoneOrSort → name` lookup ([`load_quest_header_names`]).
+/// `ZoneOrSort` → header name.
 #[derive(Debug, Default)]
 pub struct QuestHeaderNames {
-    /// `AreaTable.ID → AreaName` (positive ZoneOrSort).
     zones: HashMap<u32, String>,
-    /// `QuestSort.ID → SortName` (negative ZoneOrSort, negated).
     sorts: HashMap<u32, String>,
 }
 
 impl QuestHeaderNames {
-    /// The header title for a quest's `ZoneOrSort`, or `None` for an id neither table knows
-    /// (including 0 — the caller picks its own fallback bucket).
+    /// The header title; `None` for 0 or an unknown id, where the caller picks its own bucket.
     pub fn resolve(&self, zone_or_sort: i32) -> Option<&str> {
         if zone_or_sort > 0 {
             self.zones.get(&(zone_or_sort as u32)).map(String::as_str)
diff --git a/crates/benilla-formats/src/quest_info.rs b/crates/benilla-formats/src/quest_info.rs
index 2c1aaf7a..7d4218e7 100644
--- a/crates/benilla-formats/src/quest_info.rs
+++ b/crates/benilla-formats/src/quest_info.rs
@@ -1,45 +1,12 @@
-//! Quest-log **tag names**: the quest template's `Type` → the parenthesised suffix a quest-log row
-//! carries after its title — `(Elite)`, `(Dungeon)`, `(Raid)`, `(PvP)`.
-//!
-//! `QuestInfo.dbc` on 5875 (read here through the client's own patch chain — it ships in
-//! `patch-2.MPQ`) is **7 records × 10 u32 fields, record size 40**: `ID(0)`, `Name(1)`, the 7
-//! remaining loc-block slots, and the loc flag mask at col 9 — the same `ID … Name … loc` shape
-//! `QuestSort.dbc` has, so it reads through the same [`crate::dbc::load_id_name_table`].
-//!
-//! **The whole table**, in file order — these seven ids are the entire tag vocabulary a 1.12
-//! client can render, and they are SPARSE, so the lookup is by id and never by row index:
-//!
-//! | ID | Name |
-//! |----|------|
-//! | 1  | `Elite` |
-//! | 21 | `Life` |
-//! | 41 | `PvP` |
-//! | 62 | `Raid` |
-//! | 81 | `Dungeon` |
-//! | 82 | `World Event` |
-//! | 83 | `Legendary` |
-//!
-//! Note `1 = "Elite"`, not the later expansions' `"Group"` — a 1.12 group quest reads `(Elite)`.
-//!
-//! The key is [`benilla_protocol::messages::QuestTemplate::quest_type`], the 5th `u32` of
-//! `SMSG_QUEST_QUERY_RESPONSE` (vmangos writes `pQuest->GetType()` there, and its
-//! `quest_template.Type` carries exactly these sparse ids). A quest with `Type == 0` — the great
-//! majority — names no row and takes no tag.
-//!
-//! All of that is **§5-verified against the binary** (wow-re `ui/scratch/questlog-title-tag.md`):
-//! `0x4df930` reads the cached template's `+0x10`, bounds-checks it against the table's maxId
-//! (`0xc0d9d0`) and indexes `0xc0d9cc` with no arithmetic on the id; type `0` passes the bounds
-//! and dies on the zero-filled slot, which reaches Lua as `nil` because `lua_pushstring` tail-jumps
-//! to `lua_pushnil` on NULL. **Read this path through the patch chain and nowhere else:** the base
-//! `dbc.MPQ` copy has only four rows (PvP, Life, Elite, Raid; maxId 62), so a truncated chain
-//! silently loses Dungeon, World Event and Legendary while looking right on everything else — the
-//! fixture test's row-count assert is what stands between us and that.
-//!
-//! **The `Type` field has a second reader in the client, and it is not a tag:** the
-//! `PLAYER_QUEST_LOG` field watcher (`0x5dde6b`/`0x5ddf02`) tests it against `1` and fires
-//! TriggerTutorial 40 when an *Elite* quest is accepted. Nothing else renders this table
-//! (`0xc0d9cc` has one reader image-wide), so the tag belongs to the quest-log row and to nothing
-//! else — but `+0x10` is not "the tag id".
+//! Quest-log tag names: the quest template's `Type` → the suffix after a quest-log title.
+//! `QuestInfo.dbc` (`ID`, the `Name` loc-string) holds the sparse ids 1 Elite (not the later
+//! "Group"), 21 Life, 41 PvP, 62 Raid, 81 Dungeon, 82 World Event and 83 Legendary; `Type` 0, most
+//! quests, has no tag. `GetQuestLogTitle` (`0x4df930`) reads it through `0x4df2a0`: the cached
+//! template's `+0x10` (the 5th `u32` of `SMSG_QUEST_QUERY_RESPONSE`), bounds-checked against the
+//! max id (`0xc0d9d0`), indexes `0xc0d9cc` directly, and a missing row reaches Lua as `nil`. The
+//! full table ships in `patch-2.MPQ`; `dbc.MPQ` has only PvP, Life, Elite and Raid. `Type`'s one
+//! other reader, the `PLAYER_QUEST_LOG` watcher (`0x5dde6b`, `0x5ddf02`), fires tutorial 40 when an
+//! Elite quest is accepted.
 
 use std::collections::HashMap;
 
@@ -48,25 +15,22 @@ use anyhow::Result;
 use crate::chain::Chain;
 use crate::dbc::load_id_name_table;
 
-/// The resolved `Type → tag name` lookup ([`load_quest_tag_names`]).
+/// `Type` → tag name.
 #[derive(Debug, Default)]
 pub struct QuestTagNames(HashMap<u32, String>);
 
 impl QuestTagNames {
-    /// The tag for a quest template's `Type`, or `None` for a type the table doesn't name —
-    /// which includes `0`, the untagged majority. The caller renders nothing for `None`; it must
-    /// not substitute an empty string, because the reference's row Lua branches on the tag's
-    /// presence, not on its length.
+    /// The tag for a quest `Type`. `None` must reach Lua as `nil`, never `""`: the reference's
+    /// quest-log row tests the tag's presence.
     pub fn resolve(&self, quest_type: u32) -> Option<&str> {
         self.0.get(&quest_type).map(String::as_str)
     }
 
-    /// How many tags the table names — the load's own sanity check (5875 ships 7).
+    /// How many tags the table names (7 in 5875).
     pub fn len(&self) -> usize {
         self.0.len()
     }
 
-    /// Whether the table named nothing at all.
     pub fn is_empty(&self) -> bool {
         self.0.is_empty()
     }
diff --git a/crates/benilla-formats/src/race_pvp_team.rs b/crates/benilla-formats/src/race_pvp_team.rs
index 23dfbe7c..d3e3614d 100644
--- a/crates/benilla-formats/src/race_pvp_team.rs
+++ b/crates/benilla-formats/src/race_pvp_team.rs
@@ -1,29 +1,8 @@
-//! `ChrRaces.dbc` → the **PvP team digit** — `0x5efe00`, the second `%d` of
-//! `PVP_RANK_<rank>_<team>`.
-//!
-//! The engine never asks a unit what faction template it is *currently* carrying for this; it asks
-//! what RACE it is, and walks the race's own table:
-//!
-//! ```text
-//! 5efe06  movzx eax, BYTE PTR [[obj+0x110]+0x78]   ; UNIT_FIELD_BYTES_0 byte 0 = race
-//!         -> ChrRaces  [0xc0dee0][race]   +0x08    ; field 2 = FactionTemplate id
-//!         -> FactionTemplate [0xc0dd3c][id] +0x0c  ; field 3 = factionGroupMask
-//! 5efe42  test al,4 ; je ...                       ; mask & 4 -> 0 (Horde)
-//! 5efe49  and al,2 ; …                             ; mask & 2 -> 1 (Alliance), else -1
-//! 5efe54  (any bound/NULL failure)                 -> -1
-//! ```
-//!
-//! (wow-re `system/ui/scratch/honor-panel-law.md` §3.11, VERIFIED; the `0`/`1` assignment is
-//! settled there against the shipped `FactionGroup.dbc` and `GlobalStrings.lua`, not inferred.)
-//!
-//! **This is not `UnitFactionGroup`**, which reads the live `UNIT_FIELD_FACTIONTEMPLATE`
-//! (`0x5166b8`/`0x5166be`) and so genuinely loses its side under GM mode. Confusing the two is
-//! report B378 / decision 2227.
-//!
-//! Loaded only by [`crate::race_pvp_team::load_race_pvp_teams`]'s one consumer — the test that
-//! pins `ui_unit::race_pvp_team`'s frozen table to the shipped tables. The runtime answer is that
-//! table: nine constant rows of a 2006 file are not worth a DBC resource threaded through every
-//! unit snapshot, but they are worth a test that fails if the file ever disagrees.
+//! `ChrRaces.dbc` → the PvP team digit, the second `%d` of `PVP_RANK_<rank>_<team>` (`0x5efe00`):
+//! race → `ChrRaces` column 2 (`[0xc0dee0]`) → that FactionTemplate's group mask (`[0xc0dd3c]`);
+//! mask & 4 is 0 (Horde), mask & 2 is 1 (Alliance), else -1. It reads the race, unlike
+//! `UnitFactionGroup`, whose live faction template (`0x5166b8`) loses its side under GM mode. The
+//! runtime uses a frozen copy, `ui_unit::race_pvp_team`; this loader backs the test that pins it.
 
 use std::collections::HashMap;
 
@@ -35,16 +14,12 @@ use crate::Chain;
 
 const CHR_RACES: &str = "DBFilesClient\\ChrRaces.dbc";
 
-/// Every `ChrRaces.dbc` row's team digit, by race id — `0` Horde, `1` Alliance, `-1` no side.
-///
-/// The map holds one entry per row the file actually has (nine in 5875, ids 1–9); a race id with
-/// no row is the engine's `-1` tail and is simply absent here.
+/// Each `ChrRaces.dbc` row's team digit by race id; a race without a row (-1) is absent.
 pub fn load_race_pvp_teams(chain: &mut Chain) -> Result<HashMap<u8, i8>> {
     let bytes = chain
         .read_file(CHR_RACES)
         .with_context(|| format!("reading {CHR_RACES}"))?;
-    // 29 columns in 5875; the string columns are declared here only so the field count matches —
-    // this loader reads none of them. Same schema as `crate::characters`' creation catalog.
+    // The string columns are declared only so the field count matches; none is read.
     let mut schema = Schema::new("ChrRaces");
     for i in 0..29 {
         let ty = match i {
@@ -63,8 +38,7 @@ pub fn load_race_pvp_teams(chain: &mut Chain) -> Result<HashMap<u8, i8>> {
         let Ok(race) = u8::try_from(race) else {
             continue;
         };
-        // `0x5efe42`'s order: the Horde bit is tested FIRST, so a hypothetical row carrying both
-        // side bits would read Horde. Reproduced rather than tidied.
+        // The Horde bit is tested first (`0x5efe42`), so a row with both bits reads Horde.
         let team = match factions.template(template).map(|t| t.group_mask) {
             Some(m) if m & 4 != 0 => 0,
             Some(m) if m & 2 != 0 => 1,
diff --git a/crates/benilla-formats/src/race_sound.rs b/crates/benilla-formats/src/race_sound.rs
index 51282de3..7b97942d 100644
--- a/crates/benilla-formats/src/race_sound.rs
+++ b/crates/benilla-formats/src/race_sound.rs
@@ -1,12 +1,5 @@
-//! `ChrRaces.dbc` — the race-keyed **exploration sound** (decision 0829): the jingle the real
-//! client plays on every `SMSG_EXPLORATION_EXPERIENCE`, resolved race → `ChrRaces` row →
-//! column 3 (`+0xc`) → SoundEntries kit. Byte-verified in wow-re
-//! (`system/net/net.md` § "SMSG_EXPLORATION_EXPERIENCE": handler case tail `0x5e41d2`, race byte
-//! → row `[0xc0dee0][race]` → `+0xc` → play tail `0x458850`); the column's canonical *name*
-//! ("ExplorationSoundID") is community lore, the offset and mechanism are the verified part.
-//!
-//! Layout — 29 columns (strings at 15, 26–28; the same schema
-//! [`crate::characters`]'s creation catalog parses): only `ID` (0) and column 3 are read here.
+//! `ChrRaces.dbc` column 3: the sound the client plays on `SMSG_EXPLORATION_EXPERIENCE`, by the
+//! player's race (`0x5e41d2`: row `[0xc0dee0][race]`, offset `0xc`, played at `0x458850`).
 
 use std::collections::HashMap;
 
@@ -18,14 +11,12 @@ use crate::dbc::{parse, u32_at};
 
 const CHR_RACES: &str = "DBFilesClient\\ChrRaces.dbc";
 
-/// Race id (`ChrRaces` row id — the descriptor's `UNIT_FIELD_BYTES_0` race byte) → the
-/// exploration-sound SoundEntries kit (rows with 0 are absent).
+/// Race (the `UNIT_FIELD_BYTES_0` race byte) → exploration `SoundEntries` id; a 0 is absent.
 pub struct ExplorationSoundCatalog {
     by_race: HashMap<u32, u32>,
 }
 
 impl ExplorationSoundCatalog {
-    /// The discovery jingle's kit for `race`, or `None` (unknown race, or a 0 field).
     pub fn kit(&self, race: u32) -> Option<u32> {
         self.by_race.get(&race).copied()
     }
@@ -69,8 +60,6 @@ pub fn load_exploration_sound_catalog(chain: &mut Chain) -> Result<ExplorationSo
 mod tests {
     use super::*;
 
-    /// The real 5875 table: every playable race (1–8) carries a nonzero exploration kit.
-    /// Skips without client data.
     #[test]
     fn real_chr_races_exploration_kits() {
         let data = crate::wow_data_or_skip!();
@@ -81,8 +70,7 @@ mod tests {
             eprintln!("race {race}: exploration kit {kit:?}");
             assert!(kit.is_some(), "race {race} has no exploration sound");
         }
-        // Frozen facts of the file: the playable races' kits are the contiguous SoundEntries
-        // block 4140–4147 (Human 4140, Orc 4141 — the misparse guard for the column position).
+        // The shipped kits run 4140-4147; Human and Orc guard the column position.
         assert_eq!(cat.kit(1), Some(4140));
         assert_eq!(cat.kit(2), Some(4141));
     }
diff --git a/crates/benilla-formats/src/ribbons.rs b/crates/benilla-formats/src/ribbons.rs
index 71d8bbb4..cbce5373 100644
--- a/crates/benilla-formats/src/ribbons.rs
+++ b/crates/benilla-formats/src/ribbons.rs
@@ -1,15 +1,11 @@
-//! Vanilla (build 5875 / MD20 v256) M2 **ribbon emitter** parsing — the weapon trails, wisp
-//! streamers, and spell-missile trails. Read straight from raw bytes, like `particles`.
-//!
-//! Byte layout is wow-5875-re's transcription-ready spec (`system/models/scratch/
-//! ribbon-emitter-spec.md`, their `9c862186` — a §5 pair over the MD20 relocation fixup + the
-//! ctor/render reads; closes the models item-12 remainder for the ribbon record):
+//! M2 ribbon emitters (weapon trails, wisp streamers, missile trails), read from raw bytes in the
+//! reference's layout (relocation fixup `0x71ef40`):
 //!
 //! ```text
 //! header array : count @ MD20+0x134, ptr @ MD20+0x138        record stride 0xdc
 //! +0x04 boneIndex(u16)  +0x08 position(C3Vector, bone-local)
 //! +0x14 textureIndices(M2Array<u16> → M2 textures)  +0x1c materialIndices(M2Array<u16> → the
-//!       M2 render-flags table @MD20+0x84, stride 4: flags u16 + blend u16 — the blend source)
+//!       M2 render-flags table @MD20+0x84, stride 4: flags u16, blend u16)
 //! +0x24 colorTrack(M2Track<C3Vector>)  +0x40 alphaTrack(M2Track<fixed16>)
 //! +0x5c heightAboveTrack(M2Track<f32>)  +0x78 heightBelowTrack(M2Track<f32>)
 //! +0x94 edgesPerSecond(f32)  +0x98 edgeLifetime(f32, clamped ≥ 0.25)  +0x9c gravity(f32)
@@ -17,38 +13,16 @@
 //! +0xa4 texSlotTrack(M2Track<u16>)  +0xc0 visibilityTrack(M2Track<u8>)
 //! ```
 //!
-//! The **look tracks** (color, alpha, heightAbove/Below) parse as full keyed tracks through the
-//! shared [`crate::value_track`] kernel, band-rebased like the particle emission tracks — the
-//! one-shot spell effects key them: `HolySmite_Low_Chest.m2` flares its slash ribbons' height
-//! `0 → 0.167 → 0` over 267 ms and fades their alpha `1 → 0`, so the old value[0] bake read a
-//! permanent zero height and Smite's impact slash never drew (the 0141 lesson, surfaced).
-//! `texSlot` stays value[0]-baked (constant in the shipped corpus).
+//! Color, alpha and the two heights are keyed tracks rebased onto the first sequence's band;
+//! `texSlot` is its first value, constant in the shipped files. The visibility track sets the
+//! enable byte `block+0xbc` (ctor `0x71b34c` 0, loader `0x70f80e` 1, then every frame at
+//! `0x7176ee`/`0x717714` in `0x714260`; nothing else writes it, and `0x718960` only reads it), and
+//! a cleared byte skips the ribbon's whole draw (`0x7080c2`, `0x708263`). It keys inside a
+//! sequence: `G_FrostTrap.m2` lights its upper streamers 200 ms into `Custom0`.
 //!
-//! The **visibility** gate track (`+0xc0`) parses as [`RibbonVisibility`]: the keys of every
-//! sequence, band-local, sampled **step** (a `u8` track is never blended, so both of the
-//! reference's sampler arms copy the same raw `values[k0]`). It is the source of the enable byte
-//! `block+0xbc` — ctor `0x71b34c` = 0, loader default `0x70f80e` = 1, then written every frame
-//! from the sampled value at `0x7176ee` / `0x717714` inside `0x714260`; `0x718960` only reads it,
-//! and no equipment/attach/sheathe writer exists anywhere in the binary. Clearing it **kills the
-//! whole ribbon's draw** (`0x7080c2` → the collect loop's continue at `0x708263`). wow-re
-//! `ribbon-emitter-spec.md` §6/§7, settled by the dispatch behind decision 1017: §7 previously
-//! left the writer OPEN and *guessed* the equip/attach route, and decision 1013 unwound the whole
-//! mechanism on the strength of that guess.
-//!
-//! The thrown weapon keys its flight trail OFF in Stand (worn in the hand) and Impact (landed),
-//! ON only in InFlight. Keeping the keys — rather than the old band-start bool per sequence — is
-//! not tidiness: shipped ribbons **do** key the gate mid-sequence. `G_FrostTrap.m2` lights its
-//! low rig 534 ms into Spawn (`867` inside the `333..1067` band) and its twelve upper streamers
-//! 200 ms into `Custom0` (`4200` inside `4000..5400`) — so a placed trap shows the low rig alone
-//! and the upper twelve fire only when it springs.
-//!
-//! **NOT transcribed**, both narrow, both recorded so the next reader knows they are open: the
-//! reference gates re-sampling on `timestamps.count > Model+0x8c`, which is 0 on an instance's
-//! first frame and 1 after — so a **single-key** track samples once and then latches, where we
-//! re-answer every frame (same result for a constant track, which is that whole population). And
-//! its key window is `interpolationRanges[rangeIdx]` with `rangeIdx` the **emitter's own bone's**
-//! active slot, not the model's, `lo >= hi` returning `lo` unsearched; we window by the playing
-//! sequence's band, which agrees wherever the ribbon's bone plays what the model plays.
+//! The reference samples a single-key track once and latches it, where this resamples every frame
+//! (the same for a constant track), and windows keys by the emitter bone's active sequence, where
+//! this uses the model's (the same wherever the bone plays the model's sequence).
 
 use std::io::Cursor;
 
@@ -74,8 +48,7 @@ fn le_f32(b: &[u8], o: usize) -> f32 {
     f32::from_le_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]])
 }
 
-/// value[0] of a vanilla 0x1c M2Track whose values have `elem_size` bytes, decoded by `read`.
-/// Track tail: values `{count @ +0x14, offset @ +0x18}`. `default` when empty/out-of-range.
+/// The first value of a 0x1c-byte M2Track (values count @ +0x14, offset @ +0x18), or `default`.
 fn track_first<T>(
     b: &[u8],
     track: usize,
@@ -94,66 +67,50 @@ fn track_first<T>(
     read(b, ofs)
 }
 
-/// One parsed vanilla M2 ribbon emitter, reduced to what the renderer needs. Positions are
-/// **bone-local** (WoW axes) — the runtime transforms through the host bone's live matrix each
-/// frame, exactly like a particle emitter's origin.
+/// One M2 ribbon emitter, as the renderer needs it.
 #[derive(Debug, Clone)]
 pub struct RibbonEmitterDef {
     pub bone: u16,
-    /// Emission origin in the host bone's frame (the reference multiplies it by the bone matrix
-    /// per frame — `0x718960`).
+    /// The origin in the host bone's frame, times the bone matrix every frame (`0x718960`).
     pub position: [f32; 3],
-    /// Trail texture (`.blp` path via `textureIndices[0]` → the M2 textures table). `None` if
-    /// unresolved (the consumer skips the ribbon).
+    /// `textureIndices[0]`'s path; `None` if unresolved, and the ribbon is skipped.
     pub texture: Option<String>,
-    /// Blend mode from `materialIndices[0]` → the M2 render-flags entry's blend u16 (the same
-    /// EGxBlend folding as particle/batch blends).
+    /// `materialIndices[0]`'s render-flags blend, folded into a `ParticleBlend`.
     pub blend: ParticleBlend,
-    /// The RAW authored blend u16 behind [`Self::blend`] (`None` when the material index does not
-    /// resolve). The fold is lossy, so a census cannot say *which* mode a folded ribbon authored
-    /// without it — and re-walking the material array downstream is how the two readings drift.
+    /// The raw blend behind the lossy [`Self::blend`] fold, when the material resolves.
     pub blend_mode: Option<u16>,
     /// Trail tint (colorTrack, RGB 0..1, keyed on the clip clock; constant white when unkeyed).
     pub color: ValueTrack<[f32; 3]>,
-    /// Trail opacity (alphaTrack, **int16** fix16/32767, keyed — the slash's fade-out; constant
-    /// 1.0 when unkeyed).
+    /// Trail opacity (alphaTrack, int16 / 32767; constant 1.0 when unkeyed).
     pub alpha: ValueTrack,
-    /// Cross-section half-widths (yards) above/below the bone path, keyed — the slash's
-    /// flare-and-collapse. Sampled at edge-commit time (each edge keeps the width it was born
-    /// with; the reference stores the vertex pair per edge).
+    /// Half-widths (yards) above and below the path; each edge keeps the width it was born with.
     pub height_above: ValueTrack,
     pub height_below: ValueTrack,
-    /// Edge spawn rate (edges/second) — with `edge_lifetime`, sizes the ring.
+    /// Edges per second; with `edge_lifetime`, sizes the ring.
     pub edges_per_second: f32,
-    /// Edge age-out (seconds) — the reference clamps to ≥ 0.25 at load; so do we.
+    /// Edge lifetime in seconds, clamped to at least 0.25 at load as the reference does.
     pub edge_lifetime: f32,
     /// Downward sag applied to live edges (the reference's `2·g·dt` per-frame term).
     pub gravity: f32,
-    /// Texture atlas tiling (1×1 = the whole texture) + the (baked) slot index.
+    /// Texture atlas tiling (1×1 is the whole texture) and the slot index.
     pub tile_rows: u16,
     pub tile_cols: u16,
     pub tex_slot: u16,
-    /// The `+0xc0` **enable** track, per sequence and keyed within it (see the module doc).
-    /// `None` = no gate — keyless, global-seq-clocked, or ON everywhere (the always-on majority:
-    /// enchant trails, wisps). `Some(v)` = the trail goes dark somewhere, and the consumer must
-    /// sample [`RibbonVisibility::at`] against the sequence its host is playing, every frame.
+    /// The `+0xc0` enable track, `None` when always on; otherwise [`RibbonVisibility::at`] is
+    /// sampled on the host's playing sequence every frame.
     pub visible: Option<RibbonVisibility>,
 }
 
-/// A ribbon's `+0xc0` enable track, resolved per sequence: for each `AnimationData.dbc` id the
-/// model authors, the gate's step keys inside that sequence's band, rebased to **band-local
-/// seconds**. Entry 0 of each list is the value the band opens on (the nearest-previous key at
-/// the band start), so a sample never has to look outside the sequence.
+/// The `+0xc0` enable track per `AnimationData.dbc` id: step keys in band-local seconds, the
+/// first being the value the band opens on.
 #[derive(Debug, Clone, PartialEq)]
 pub struct RibbonVisibility {
     by_anim: std::collections::HashMap<u16, Vec<(f32, bool)>>,
 }
 
 impl RibbonVisibility {
-    /// Whether the trail emits during `anim` at `t` seconds into the clip. Step
-    /// (nearest-previous) — the track's own `interp == 0`, which is what every shipped gate
-    /// carries. A sequence this model doesn't author falls back to `Stand`(0)'s answer, then to
-    /// the reference's load default: **enabled** (`0x70f80e` writes `block+0xbc = 1`).
+    /// Whether the trail emits `t` seconds into `anim`, stepped. An unauthored sequence takes
+    /// Stand's answer, and without one the load default, on (`0x70f80e`).
     pub fn at(&self, anim: u16, t: f32) -> bool {
         let Some(keys) = self.by_anim.get(&anim).or_else(|| self.by_anim.get(&0)) else {
             return true;
@@ -171,22 +128,14 @@ impl RibbonVisibility {
     }
 }
 
-/// Parse a ribbon's `+0xc0` gate track (`M2Track<u8>`, sequence-timeline) into a
-/// [`RibbonVisibility`]: per `anim_id`, the keys that fall inside that sequence's band, rebased to
-/// band-local seconds, preceded by the nearest-previous value at the band start. `None` when there
-/// is nothing to gate:
-///
-/// - a keyless / out-of-range track (the reference's enabled-at-load default), or
-/// - a **global-sequence** clock (`gseq != 0xffff`) — a free-running loop, not per-sequence, or
-/// - a track that resolves ON at every key of every sequence (a keyed-but-always-on author).
-///
-/// Sequences: MD20 count @ `0x1c`, offset @ `0x20`, stride `0x44` — `anim_id` @ +0, band `[start,
-/// end]` @ +4/+8 (the same walk as [`crate::value_track::seq0_band`], one sequence wider).
+/// The `+0xc0` gate track as a [`RibbonVisibility`]; `None` when keyless, on a global-sequence
+/// clock, or on everywhere. Sequences: MD20 count @ `0x1c`, offset @ `0x20`, stride `0x44`, with
+/// `anim_id` @ +0 and the band's start and end @ +4 and +8.
 fn visibility_by_anim(bytes: &[u8], vis_track: usize) -> Option<RibbonVisibility> {
     if vis_track + 0x1c > bytes.len() {
         return None;
     }
-    // gseq != 0xffff: a global-sequence free clock, not keyed per animation — leave it always-on.
+    // A global-sequence clock is not per animation: treated as always on.
     if le_u16(bytes, vis_track + 0x02) != 0xffff {
         return None;
     }
@@ -196,7 +145,7 @@ fn visibility_by_anim(bytes: &[u8], vis_track: usize) -> Option<RibbonVisibility
     let vofs = le_u32(bytes, vis_track + 0x18) as usize;
     let n = tn.min(vn);
     if n == 0 || tofs + n * 4 > bytes.len() || vofs + n > bytes.len() {
-        return None; // keyless → the always-on default
+        return None; // keyless: the always-on default
     }
     let keys: Vec<(u32, bool)> = (0..n)
         .map(|i| (le_u32(bytes, tofs + i * 4), bytes[vofs + i] != 0))
@@ -214,8 +163,7 @@ fn visibility_by_anim(bytes: &[u8], vis_track: usize) -> Option<RibbonVisibility
         }
         let anim = le_u16(bytes, s);
         let (start, end) = (le_u32(bytes, s + 4), le_u32(bytes, s + 8));
-        // The band opens on the nearest-previous key (M2 step interpolation); before the first
-        // key, the first key's value; keyless-safe default ON.
+        // The band opens on the nearest-previous key, or the first key before any.
         let opening = keys
             .iter()
             .take_while(|&&(t, _)| t <= start)
@@ -223,8 +171,7 @@ fn visibility_by_anim(bytes: &[u8], vis_track: usize) -> Option<RibbonVisibility
             .or(keys.first())
             .is_some_and(|&(_, v)| v);
         let mut band: Vec<(f32, bool)> = vec![(0.0, opening)];
-        // …then every key strictly inside the band, band-local. `G_FrostTrap`'s streamers live
-        // entirely here — their whole ON window opens 200 ms into the trigger sequence.
+        // Then each change strictly inside the band, band-local.
         for &(t, v) in keys.iter().filter(|&&(t, _)| t > start && t <= end) {
             let local = (t - start) as f32 / 1000.0;
             if band.last().is_some_and(|&(_, prev)| prev != v) {
@@ -232,19 +179,17 @@ fn visibility_by_anim(bytes: &[u8], vis_track: usize) -> Option<RibbonVisibility
             }
         }
         any_off |= band.iter().any(|&(_, v)| !v);
-        by_anim.entry(anim).or_insert(band); // variations share an id — the head sequence wins
+        by_anim.entry(anim).or_insert(band); // variations share an id; the first wins
     }
-    // Nothing dark anywhere ⇒ effectively always-on: no gate to carry.
+    // Never dark: no gate.
     any_off.then_some(RibbonVisibility { by_anim })
 }
 
-/// Parse an M2's ribbon emitters (see the module doc). Empty when the model has none or isn't a
-/// parseable M2.
+/// An M2's ribbon emitters; empty when it has none or is not a parseable M2.
 pub fn parse_m2_ribbon_emitters(bytes: &[u8]) -> Result<Vec<RibbonEmitterDef>> {
     if bytes.len() < HDR_PTR + 4 || &bytes[0..4] != b"MD20" {
         return Ok(Vec::new());
     }
-    // Texture paths from `benilla-m2`'s textures table (same source as particle textures).
     let textures: Vec<Option<String>> = match parse_m2(&mut Cursor::new(bytes)) {
         Ok(fmt) => fmt
             .model()
@@ -264,10 +209,14 @@ pub fn parse_m2_ribbon_emitters(bytes: &[u8]) -> Result<Vec<RibbonEmitterDef>> {
     };
     let count = le_u32(bytes, HDR_COUNT) as usize;
     let base = le_u32(bytes, HDR_PTR) as usize;
+    // `count` sizes the reservation, so a hostile one is refused; 256 is far past any shipped
+    // model, and checking it first keeps `count * STRIDE` from overflowing.
+    if count == 0 || count > 256 || base + count * STRIDE > bytes.len() {
+        return Ok(Vec::new());
+    }
     let rf_count = le_u32(bytes, HDR_RENDER_FLAGS) as usize;
     let rf_base = le_u32(bytes, HDR_RENDER_FLAGS + 4) as usize;
-    // The first sequence's absolute time band — the keyed look tracks rebase onto it
-    // (`value_track::seq0_band`; the same window the particle tracks use).
+    // The first sequence's band, which the keyed look tracks rebase onto, as particle tracks do.
     let band = seq0_band(bytes);
     let mut out = Vec::with_capacity(count);
     for i in 0..count {
@@ -292,15 +241,9 @@ pub fn parse_m2_ribbon_emitters(bytes: &[u8]) -> Result<Vec<RibbonEmitterDef>> {
                 .filter(|&m| m < rf_count && rf_base + m * 4 + 4 <= bytes.len())
                 .map(|m| le_u16(bytes, rf_base + m * 4 + 2))
         };
-        // The fold, MEASURED against the corpus by `benilla-extract ribbonscan` (176 models, 590
-        // ribbons): Add(4) 527 · Alpha(2) 51 · Mod2x(6) 12. Nothing authors 0, 1 or 5, so the
-        // AlphaKey arm below is the law rather than a live case — but it is the law, and the
-        // particle side proved what folding it into `Opaque` costs.
-        //
-        // KNOWN GAP, deliberately not fixed here: those 12 Mod2x ribbons fall into `Opaque` and
-        // render with no blend at all, while a Mod2x PARTICLE folds the other way (to `Alpha`).
-        // `ParticleBlend` cannot express Mod/Mod2x, so straightening it means widening that enum
-        // and re-verifying both lanes — its own change, not a rider on the AlphaKey fix.
+        // Shipped ribbons author Add (4) 527 times, Alpha (2) 51 and Mod2x (6) 12
+        // (`benilla-extract ribbonscan`). `ParticleBlend` has no Mod2x, so those 12 fold to
+        // `Opaque` and draw unblended, where the reference multiplies.
         let blend = match blend_mode {
             Some(3 | 4) => ParticleBlend::Add,
             Some(2) => ParticleBlend::Alpha,
@@ -321,9 +264,7 @@ pub fn parse_m2_ribbon_emitters(bytes: &[u8]) -> Result<Vec<RibbonEmitterDef>> {
             color: track_keys_with(bytes, e + 0x24, [1.0; 3], band, 12, |b, o| {
                 [le_f32(b, o), le_f32(b, o + 4), le_f32(b, o + 8)]
             }),
-            // fix16 keys are SIGNED (`movsx`, wow-re `tracks.md` flavour (c) — the same decode as
-            // `benilla_m2::track_fix16`; the ribbon spec calls the stride-2 values int16 outright,
-            // `ribbon-emitter-spec.md` +0x40). The strip's own draw clamps a negative to 0 below.
+            // fix16 keys are signed (`movsx` at `0x717933`); the draw clamps a negative to 0.
             alpha: track_keys_with(bytes, e + 0x40, 1.0, band, 2, |b, o| {
                 f32::from(le_u16(b, o) as i16) / 32767.0
             }),
@@ -345,10 +286,18 @@ pub fn parse_m2_ribbon_emitters(bytes: &[u8]) -> Result<Vec<RibbonEmitterDef>> {
 mod tests {
     use super::*;
 
-    /// [`RibbonVisibility::at`]'s sampling law, on a hand-built gate: STEP (nearest-previous, the
-    /// track's own `interp == 0`), the band-opening entry answers before the first in-band key,
-    /// and a sequence the model doesn't author falls back to `Stand`(0) and then to the
-    /// reference's enabled-at-load default.
+    #[test]
+    fn a_hostile_ribbon_count_yields_nothing_not_an_abort() {
+        let mut b = vec![0u8; HDR_PTR + 4];
+        b[0..4].copy_from_slice(b"MD20");
+        b[HDR_COUNT..HDR_COUNT + 4].copy_from_slice(&u32::MAX.to_le_bytes());
+        assert!(parse_m2_ribbon_emitters(&b).unwrap().is_empty());
+        // A plausible count whose table the file cannot hold is refused too.
+        b[HDR_COUNT..HDR_COUNT + 4].copy_from_slice(&3u32.to_le_bytes());
+        b[HDR_PTR..HDR_PTR + 4].copy_from_slice(&((HDR_PTR + 4) as u32).to_le_bytes());
+        assert!(parse_m2_ribbon_emitters(&b).unwrap().is_empty());
+    }
+
     #[test]
     fn visibility_samples_step_and_falls_back_to_stand() {
         let vis = RibbonVisibility {
@@ -359,26 +308,20 @@ mod tests {
             .into_iter()
             .collect(),
         };
-        // Step within the band: dark, lit, dark — and lit right ON the key, not after it.
         assert!(!vis.at(153, 0.0));
         assert!(!vis.at(153, 0.199));
         assert!(vis.at(153, 0.2), "step: the key's value takes effect AT it");
         assert!(vis.at(153, 1.399));
         assert!(!vis.at(153, 1.4));
-        // A sequence this gate doesn't list borrows Stand(0)'s answer…
         assert!(!vis.at(147, 0.0), "unlisted sequence borrows Stand");
-        // …and with no Stand either, the load default stands: enabled.
         let no_stand = RibbonVisibility {
             by_anim: [(153u16, vec![(0.0, false)])].into_iter().collect(),
         };
         assert!(no_stand.at(147, 0.0), "no answer at all ⇒ the load default");
     }
 
-    /// The real `HolySmite_Low_Chest.m2` (Smite's impact): its yellow slash IS its two ribbon
-    /// emitters, whose look tracks are KEYED inside the seq band [3300, 4433] — height flares
-    /// `0 → 0.167 → 0` over the first 267 ms and alpha fades `1 → 0` by 467 ms. The old
-    /// value[0] bake read a permanent zero height, so the slash never spawned (the director's
-    /// "we have the glitter but not the slash"). Pins the band rebase and the keyed samples.
+    /// Smite's impact slash is two ribbons keyed inside the band [3300, 4433]: height 0 to 0.167
+    /// and back over 267 ms, alpha 1 to 0 by 467 ms.
     #[test]
     fn real_holy_smite_slash_ribbons_are_keyed_flares() {
         let data = crate::wow_data_or_skip!();
@@ -389,22 +332,17 @@ mod tests {
         let defs = parse_m2_ribbon_emitters(&bytes).expect("parse ribbons");
         assert_eq!(defs.len(), 2);
         for r in &defs {
-            // Height: born at 0 (the value[0] trap), flaring to 0.167 yd at 200 ms clip time.
             assert_eq!(r.height_above.first(), 0.0, "value[0] bake = no slash");
             assert!((r.height_above.peak() - 0.167).abs() < 1e-3);
             assert!((r.height_above.sample_ms(200.0) - 0.167).abs() < 1e-3);
             assert_eq!(r.height_above.sample_ms(400.0), 0.0, "collapsed by 267 ms");
             assert_eq!(r.height_below.keys, r.height_above.keys, "symmetric slash");
-            // Alpha: full through the flare, gone by 467 ms.
             assert_eq!(r.alpha.sample_ms(0.0), 1.0);
             assert!(r.alpha.sample_ms(600.0) < 1e-6);
-            // Band rebase happened: every key sits on the 0-based clip clock, inside the
-            // 1133 ms clip.
+            // Rebased: every key is inside the 1133 ms clip.
             assert!(r.height_above.keys.iter().all(|&(t, _)| t <= 1133));
             assert_eq!(r.color.first(), [1.0; 3]);
-            // Smite's slash is a one-shot flash, not visibility-gated per sequence — the trail is
-            // ON wherever it plays (its alpha, above, does the fade). So it must carry NO gate,
-            // or the spawn site would wrongly darken it against a Stand default.
+            // Always on, its alpha doing the fade: no gate to darken it against Stand.
             assert_eq!(
                 r.visible, None,
                 "an always-on slash carries no visibility gate"
@@ -412,10 +350,6 @@ mod tests {
         }
     }
 
-    /// The thrown dagger's flight trail is **visibility-gated per sequence** (`+0xc0`): its ribbon
-    /// is dark in Stand (worn in the hand) and Impact (landed), lit only in InFlight (flying). This
-    /// is the seam the multi-sequence gate closes — the worn item resting in Stand shows no trail;
-    /// the InFlight missile does. Pins the per-sequence resolve against the shipped asset.
     #[test]
     fn real_thrown_dagger_trail_is_lit_only_in_flight() {
         let data = crate::wow_data_or_skip!();
@@ -434,16 +368,8 @@ mod tests {
         assert!(!vis.at(191, 0.0), "Impact (landed): dark");
     }
 
-    /// The placed **Frost Trap** — the model that proved the gate is keyed *inside* a sequence,
-    /// not constant across it (decisions 1011/1017). Its sixteen ribbons split in two: four low
-    /// ones on bones 45–48 at model z 0.129 that light 534 ms into Spawn and stay lit through
-    /// Closed — the tuft a placed trap shows, riding up off the crown on the verified `+g·t²` —
-    /// and twelve upper ones on bones 33–44 at z ≈ 1.55 that are dark in **every** rest state and
-    /// light only 200 ms into `Custom0`, when the trap springs.
-    ///
-    /// A band-start-only read answers "dark" for `Custom0` too, so the upper rig would never fire;
-    /// an ungated consumer draws all sixteen for ever, which is half of the tall column the
-    /// director reported (the other half was gravity's sign — see `benilla::ribbons`).
+    /// `G_FrostTrap.m2`: four low ribbons light 534 ms into Spawn and stay lit through Closed;
+    /// twelve upper ones are dark at rest and light 200 ms into `Custom0`, when the trap springs.
     #[test]
     fn real_frost_trap_upper_streamers_light_only_inside_the_trigger() {
         let data = crate::wow_data_or_skip!();
@@ -454,16 +380,14 @@ mod tests {
         let defs = parse_m2_ribbon_emitters(&bytes).expect("parse ribbons");
         assert_eq!(defs.len(), 16, "the frost trap authors sixteen trails");
 
-        // Ribbons 0..4: the low swirl at the trap's base. Dark as Spawn opens, lit 534 ms in
-        // (key 867 inside the 333..1067 band), and lit for all of Closed — what a placed trap shows.
+        // Ribbons 0..4: key 867 inside Spawn's 333..1067 band.
         for r in &defs[0..4] {
             let v = r.visible.as_ref().expect("the low swirl IS gated");
             assert!(!v.at(145, 0.0), "Spawn opens dark");
             assert!(v.at(145, 0.6), "…and lights 534 ms in");
             assert!(v.at(147, 0.0), "Closed: lit — the placed trap's swirl");
         }
-        // Ribbons 4..16: the upper streamers. Dark in every rest state; lit only 200 ms into the
-        // trigger (key 4200 inside the 4000..5400 band) — the column, and only when sprung.
+        // Ribbons 4..16: key 4200 inside the trigger's 4000..5400 band.
         for r in &defs[4..16] {
             let v = r.visible.as_ref().expect("the upper streamers ARE gated");
             assert!(!v.at(147, 0.0), "Closed: dark — no column on a placed trap");
diff --git a/crates/benilla-formats/src/server_messages.rs b/crates/benilla-formats/src/server_messages.rs
index 80f1382d..25ce625d 100644
--- a/crates/benilla-formats/src/server_messages.rs
+++ b/crates/benilla-formats/src/server_messages.rs
@@ -1,31 +1,8 @@
-//! `ServerMessages.dbc` — the five sentences the server can say to everybody at once.
-//!
-//! `SMSG_SERVER_MESSAGE` carries a **row id and a fill**, never a finished line: the client indexes
-//! this table by the packet's `messageType` (`0x49dfbb`, the store at `[0xc0d990]`), takes the
-//! row's localized text as a **format string**, and fills its `%s` with the packet's own text
-//! (`snprintf(buf, 0x400, rowText, packetText)` at `0x49dff0`). A packet with an empty text copies
-//! the row verbatim instead (`0x49dfc8` tests the first byte, `0x64a5a0` copies) — which is what
-//! rows 4 and 5 need, having no `%s` at all.
-//!
-//! Layout — the real 5875 file (326 bytes, 5 records × **10 × u32** cols, 106-byte string block):
-//! `ID(0), Text[8](1..8), TextMask(9)`. The whole shipped table, verbatim:
-//!
-//! | ID | enUS text | vmangos sends it with |
-//! |---|---|---|
-//! | 1 | `[SERVER] Shutdown in %s` | `secsToTimeString(remaining)` |
-//! | 2 | `[SERVER] Restart in %s` | `secsToTimeString(remaining)` |
-//! | 3 | `%s` | the operator's own text |
-//! | 4 | `[SERVER] Shutdown cancelled` | `""` |
-//! | 5 | `[SERVER] Restart cancelled` | `""` |
-//!
-//! The ids are vmangos's `enum ServerMessageType` (`src/game/World.h:62`) exactly, and its comment
-//! on that enum is the single word `ServerMessages.dbc` — the server is reading this file's ids out
-//! of the client's own data.
-//!
-//! **The row-missing arm is part of the mechanism, not an error path.** A type with no row renders
-//! through the client's own fallback format `"[%d]: %s"` (`0x844864`, read out of the image), so an
-//! unknown broadcast still reaches the player with its type visible rather than being dropped.
-//! [`ServerMessagesCatalog::compose`] is that whole decision in one function.
+//! `ServerMessages.dbc`, the five sentences the server can say to everyone. `SMSG_SERVER_MESSAGE`
+//! carries a row id and a fill: the client indexes this table by `messageType` (`0x49dfbb`, store
+//! `[0xc0d990]`) and fills the row's `%s` with the packet's text (`snprintf(buf, 0x400, …)` at
+//! `0x49dff0`), or copies the row when the text is empty (`0x49dfc8`, `0x64a5a0`). The ids are
+//! vmangos's `ServerMessageType` (`World.h:62`).
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -42,12 +19,12 @@ pub struct ServerMessagesCatalog {
 }
 
 impl ServerMessagesCatalog {
-    /// A catalog over rows given directly — for a test that must run without an install.
+    /// A catalog of given rows, for tests without an install.
     pub fn from_rows(rows: Vec<(u32, String)>) -> Self {
         ServerMessagesCatalog { rows }
     }
 
-    /// The localized format string for a `messageType`, if the table has that row.
+    /// The format string for a `messageType`.
     pub fn text(&self, message_type: u32) -> Option<&str> {
         self.rows
             .iter()
@@ -63,15 +40,11 @@ impl ServerMessagesCatalog {
         self.rows.len()
     }
 
-    /// The line `SMSG_SERVER_MESSAGE` becomes — the client's `0x49dfab`–`0x49e030` in full.
+    /// The line `SMSG_SERVER_MESSAGE` becomes (`0x49dfab`-`0x49e030`): a row and a fill format, a
+    /// row alone is copied, and no row falls back to the reference's `"[%d]: %s"` (`0x844864`).
     ///
-    /// Three arms, in the reference's own order: a row plus a non-empty fill formats; a row plus an
-    /// empty fill copies the row (so `[SERVER] Restart cancelled` never grows a stray tail); no row
-    /// falls back to `"[%d]: %s"` with the raw type.
-    ///
-    /// The substitution is `replacen(.., 1)` because the reference's is `snprintf` with **one**
-    /// vararg: a row carrying two `%s` would fill the second with stack garbage, and filling only
-    /// the first is the closest honest thing. No shipped row has two.
+    /// Deviation: a row with two `%s` fills only the first, because the reference's one-argument
+    /// `snprintf` fills the second with stack garbage; no shipped row has two.
     pub fn compose(&self, message_type: u32, fill: &str) -> String {
         match self.text(message_type) {
             Some(row) if !fill.is_empty() => row.replacen("%s", fill, 1),
@@ -109,9 +82,6 @@ pub fn load_server_messages_catalog(chain: &mut Chain) -> Result<ServerMessagesC
 mod tests {
     use super::*;
 
-    /// The real shipped table, row for row — the module doc's table asserted rather than trusted,
-    /// because these five strings are the whole vocabulary of a server shutdown. Skips without
-    /// client data.
     #[test]
     fn the_real_table_is_the_five_documented_rows() {
         let data = crate::wow_data_or_skip!();
@@ -140,7 +110,6 @@ mod tests {
         ])
     }
 
-    /// A countdown: the row is the format, the packet is the fill.
     #[test]
     fn a_countdown_fills_its_row() {
         assert_eq!(
@@ -150,22 +119,17 @@ mod tests {
         assert_eq!(shipped().compose(3, "back in five"), "back in five");
     }
 
-    /// A cancellation carries no fill, and the row is already a whole sentence — the reference
-    /// copies rather than formats, so nothing is appended and no `%s` survives.
     #[test]
     fn a_cancellation_copies_its_row_whole() {
         assert_eq!(shipped().compose(5, ""), "[SERVER] Restart cancelled");
     }
 
-    /// A row-less type still reaches the player, through the client's own `"[%d]: %s"`.
     #[test]
     fn an_unknown_type_falls_back_to_the_bracketed_form() {
         assert_eq!(shipped().compose(9, "something new"), "[9]: something new");
     }
 
-    /// The empty-fill test is on the FILL, not on whether the row has a `%s`: a row with a `%s` and
-    /// no fill copies verbatim, leaving the token visible — which is what the reference does, and
-    /// what no shipped row can actually reach (rows 1/2/3 always come with text).
+    /// The reference tests the fill, not the row: a `%s` row with no fill is copied, token and all.
     #[test]
     fn an_empty_fill_never_formats() {
         assert_eq!(shipped().compose(1, ""), "[SERVER] Shutdown in %s");
diff --git a/crates/benilla-formats/src/sheathe.rs b/crates/benilla-formats/src/sheathe.rs
index af6be105..17629b25 100644
--- a/crates/benilla-formats/src/sheathe.rs
+++ b/crates/benilla-formats/src/sheathe.rs
@@ -1,14 +1,8 @@
-//! `SheatheSoundLookups.dbc` — the draw/stow sound table (the client's runtime
-//! `AUSHEATHSOUNDHASH`; wow-re sound node, wave2-CD).
-//!
-//! Layout — VERIFIED against build 5875 (header + full dump with SoundEntries name joins,
-//! 2026-07-03): **33 × 7 × 28 B**: `ID(0), ItemClass(1), ItemSubclass(2), Material(3),
-//! _col4(4), SheatheSound(5), UnsheatheSound(6)`. The data forms three families:
-//! shields (class 4, subclasses 5/6, material 0 → kits 696/701 `SHEATHINGSHIELD*`), metal
-//! weapons (class 2 × subclasses 0–14, material 1 → 698/700 `SHEATHINGMETALWEAPON*`) and wood
-//! weapons (material 2 → 697/699 `SHEATHINGWOODWEAPON*`), plus one material-0 weapon default
-//! row (→ wood). Column 4 is 0 on shield rows and 1 on weapon rows — meaning unrecorded,
-//! unused here.
+//! `SheatheSoundLookups.dbc`, the draw and stow sounds (the reference's `AUSHEATHSOUNDHASH`, entry
+//! alloc `0x45d3a0`): `ID`, `ItemClass`, `ItemSubclass`, `Material`, an unidentified column (0 on
+//! shields, 1 on weapons), `SheatheSound`, `UnsheatheSound`. Three families: shields (class 4,
+//! material 0), metal weapons (class 2, material 1) and wood weapons (material 2), plus a
+//! material-0 weapon row that rings wood.
 
 use std::collections::HashMap;
 
@@ -21,7 +15,7 @@ use crate::Chain;
 /// One row's kit pair.
 #[derive(Clone, Copy)]
 pub struct SheatheSounds {
-    /// Stowing the item (SoundEntries kit).
+    /// The `SoundEntries` kit for stowing the item.
     pub sheathe: u32,
     /// Drawing it.
     pub unsheathe: u32,
@@ -33,16 +27,11 @@ pub struct SheatheSoundCatalog {
 }
 
 impl SheatheSoundCatalog {
-    /// The kit pair for an item. **`material` is the load-bearing argument** — the weapon rows
-    /// agree within a material and differ across one, so the class/subclass only choose the
-    /// *family* (weapon vs shield). Callers pass the item's real `Material` off the wire; it is
-    /// never inferred from the subclass, which carries no material information (decision 0882).
-    ///
-    /// Falls back to any material carried for that `(class, subclass)` — this is what lands a
-    /// shield, whose own rows hold material 0 as a don't-care, on the shield pair — and then to
-    /// the class's subclass-0 row: the 5875 table only covers weapon subclasses 0–14, so daggers
-    /// (15) and other stragglers ring like a generic weapon of their material (INTERIM — the
-    /// client's hash-miss behavior is unrecorded).
+    /// The kit pair for an item, decided by its real `Material` off the wire (never one guessed
+    /// from the subclass), the class choosing only weapon or shield. A missing material falls back
+    /// to any row of the `(class, subclass)`, landing a shield on its material-0 rows, then to the
+    /// class's subclass 0, as the table covers weapon subclasses 0-14: a dagger (15) rings as a
+    /// weapon of its material. The reference's behaviour on a miss is untraced.
     pub fn get(&self, class: u32, subclass: u32, material: u32) -> Option<SheatheSounds> {
         [subclass, 0]
             .iter()
@@ -95,9 +84,7 @@ pub fn load_sheathe_sound_catalog(chain: &mut Chain) -> Result<SheatheSoundCatal
 mod tests {
     use super::*;
 
-    /// The real 5875 table: a metal 1H sword (2/7/1) draws with 700 and stows with 698; a
-    /// shield (4/6) hits the shield pair; the material fallback resolves an unknown material.
-    /// Skips without client data.
+    /// The 5875 table: a metal sword (2/7/1), a wood staff, a shield (4/6) and the fallbacks.
     #[test]
     fn real_sheathe_sounds_decode() {
         let data = crate::wow_data_or_skip!();
@@ -114,35 +101,27 @@ mod tests {
         let shield = cat.get(4, 6, 0).expect("shield");
         assert_eq!((shield.sheathe, shield.unsheathe), (696, 701));
 
-        // Daggers (15) have NO row in 5875 — they fall back to the class's subclass-0 metal
-        // pair (and an unlisted material to the material chain).
+        // Daggers (15) have no row and fall back to subclass 0.
         let dagger = cat.get(2, 15, 1).expect("dagger falls back to subclass 0");
         assert_eq!((dagger.sheathe, dagger.unsheathe), (698, 700));
         assert!(cat.get(2, 15, 7).is_some(), "weird material still resolves");
     }
 
-    /// **The material is the whole key; the subclass is inert** (decision 0882). Every weapon row
-    /// of a material carries the same kit pair, so a bow (subclass 2, sitting in the middle of the
-    /// weapon range) rings by what it is *made of* — and the reference client's own `itemcache.wdb`
-    /// puts every bow, crossbow and wand at material 2 (wood) while guns and thrown are metal.
-    /// Ringing a bow on the metal pair — which a "staves and polearms are the wooden ones" guess
-    /// does — is the director-reported wrong sound. Skips without client data.
+    /// Every weapon row of a material carries the same pair, so a bow rings by what it is made of:
+    /// the reference's item cache has bows, crossbows and wands at material 2 (wood), guns and
+    /// thrown at metal.
     #[test]
     fn the_kit_pair_is_decided_by_material_alone() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_sheathe_sound_catalog(&mut chain).expect("load sheathe sounds");
 
-        // A bow is wood, and wood rings 697/699 — never the metal 698/700 pair.
         let bow = cat.get(2, 2, 2).expect("wood bow");
         assert_eq!((bow.sheathe, bow.unsheathe), (697, 699));
 
-        // The same subclass at the other material is the metal pair: subclass carries no
-        // information here, which is exactly why it must not be used to infer the material.
         let metal = cat.get(2, 2, 1).expect("metal row for the same subclass");
         assert_eq!((metal.sheathe, metal.unsheathe), (698, 700));
 
-        // …and that holds across every weapon subclass the table covers.
         for subclass in 0..=14 {
             assert_eq!(
                 cat.get(2, subclass, 2).map(|p| (p.sheathe, p.unsheathe)),
@@ -156,9 +135,7 @@ mod tests {
             );
         }
 
-        // A shield's real material is whatever its armor row says (1 metal and 6 plate both occur
-        // in the reference cache); its DBC rows carry material 0 as a don't-care, and the
-        // fallback chain lands them on the shield pair regardless.
+        // Shields come as metal (1) or plate (6) in the reference's item cache.
         for material in [0, 1, 6] {
             let shield = cat
                 .get(4, 6, material)
diff --git a/crates/benilla-formats/src/skill_lines/mod.rs b/crates/benilla-formats/src/skill_lines/mod.rs
index 4fc76ed3..a92ae483 100644
--- a/crates/benilla-formats/src/skill_lines/mod.rs
+++ b/crates/benilla-formats/src/skill_lines/mod.rs
@@ -1,67 +1,17 @@
-//! `SkillLine.dbc` + `SkillLineAbility.dbc` loader — spell id → skill line → {name, icon}, the
-//! spellbook's tab source (decision 0216 §8: "tabs = the class skill lines of known spells").
+//! The skill tables: a spell's skill line, a line's name and icon, and the per-race/class routing
+//! the spellbook tabs and the skills pane read. Columns follow vmangos `DBCfmt.h`/`DBCStructure.h`,
+//! which parse the same 5875 files.
 //!
-//! Layout — VERIFIED against the **vmangos server source**
-//! (`vmangos-src/src/game/Database/DBCStructure.h`'s `SkillLineEntry`/`SkillLineAbilityEntry`
-//! structs + `DBCfmt.h`'s `SkillLinefmt`/`SkillLineAbilityfmt` format strings): vmangos parses
-//! these two tables straight off the same build-5875 client data benilla reads, so its struct
-//! layout — not an empirical guess, not even wow-re's own notes (none exist for these two tables,
-//! grepped `system/dbc`) — is the strongest ground available, the same standing this codebase
-//! already gives vmangos's wire handlers (decision 0216's own citations of `ItemHandler.cpp`/
-//! `Player.cpp`).
-//!
-//! `SkillLine.dbc` — `SkillLinefmt = "nixssssssssxxxxxxxxxxi"` (22 fields, 88 B/record):
-//! `id`(0, indexed) · `categoryId`(1, int32) · `skillCostID`(2, unused) · the 8-locale
-//! `displayName_lang` block (3..10, enUS first ⇒ **NameEnUs = column 3**) + its flags word (11) ·
-//! the 8-locale `description_lang` block (12..19; enUS **column 12** = the skills pane's
-//! detail-pane body, `GetSkillLineInfo`'s 13th return) + its flags word (20) ·
-//! **`spellIcon` = column 21** (a `SpellIcon.dbc` id — [`crate::dbc::load_spell_icon_map`], the
-//! same table `spells.rs`'s action-bar catalog joins against).
-//!
-//! `SkillLineAbility.dbc` — `SkillLineAbilityfmt = "niiiixxiiiiixxi"` (15 fields, 60 B/record):
-//! `id`(0, indexed) · **`skillId` = column 1** · **`spellId` = column 2** · `racemask`(3) ·
-//! `classmask`(4) · `req_skill_value`(7; 5-6 unused: `racemaskNot`/`classmaskNot`, always 0 this
-//! build) · `forward_spellid`(8) · `learnOnGetSkill`(9) · `max_value`(10) · `min_value`(11) ·
-//! `reqtrainpoints`(14; 12-13 unused). Read into one [`SlaInfo`] per spell (a spell can carry
-//! more than one row across race/class variants; the FIRST row wins, deterministic by file
-//! order — [`SkillLineCatalog::spell_to_line`]'s long-standing convention), except
-//! `forward_spellid`, which takes the first **non-zero** across the spell's rows to match
-//! vmangos's own `SpellMgr::GetSpellBookSuccessorSpellId` exactly (identical on this build:
-//! probed, 44 spells carry more than one row and not one disagrees on the column). `max_value`/
-//! `min_value` are the recipe-difficulty trivial ranks (TrivialSkillLineRankHigh/Low): pinned on
-//! the raw 5875 file this session — Bolt of Linen Cloth 2963 → (line 197, req 1, low 25,
-//! high 50), Minor Healing Potion 2330 → (171, 1, 55, 95), which reproduces its known classic
-//! orange 1 / yellow 55 / green 75 / gray 95 progression under the color law TU-C confirmed at
-//! the bytes (decision 0446).
-//!
-//! `SkillRaceClassInfo.dbc` — `SkillRaceClassInfofmt = "diiiiiix"` (8 fields, 32 B/record):
-//! `id`(0) · **`skillId` = column 1** · **`raceMask` = column 2** · **`classMask` = column 3** ·
-//! **`flags` = column 4** · **`reqLevel` = column 5** · `skillTierId`(6) ·
-//! **`skillCostID` = column 7**. This is
-//! the table the client's spellbook tab classifier routes through (decision 0228): a spell's skill
-//! line is looked up here for the player's race+class, and if the matching row's `flags` bit `0x80`
-//! (`SKILL_FLAG_DISPLAY_SORTED`, cmangos `DBCEnums.h`) is set — or no row matches — the spell's tab
-//! is **General** (key 0) instead of the line's own tab. Byte-verified: wow-re
-//! `system/ui/scratch/spellbook-book-build.md` §3 (`0x6ddf90(skillLine, class, race) → variant`;
-//! `(int8)[variant+0x10] < 0 → key 0`; `[variant+4]` = skillId, `[variant+0x10]` = flags — the
-//! struct offsets confirm the column read). The `flags`/`raceMask`/`classMask` semantics follow
-//! vmangos `DBCStructure.h`'s `SkillRaceClassInfoEntry`; the row-match (first row whose masks
-//! admit the race/class) is the standard classic semantics, validated against the real build-5875
-//! data by [`SkillLineCatalog::spell_tab`]'s tests.
-//!
-//! `SkillLineCategory.dbc` — byte-checked on the raw 5875 file (a struct-unpack dump: 8 records ×
-//! 11 fields, 44 B/record): `id`(0) · the 8-locale `name` block (enUS ⇒ **column 1**) + flags(9) ·
-//! **`displayOrder` = column 10** — the skills pane's header vocabulary and group order (decision
-//! 0437 phase 4): Class Skills(7, order 2) · Professions(11, 3) · Secondary(9, 4) · Weapon(6, 5) ·
-//! Armor(8, 6) · Languages(10, 7); `Attributes`(5, 1) never carries player rows, and
-//! `Not Displayed`(12, 8) is a header like any other — **not** a hide bucket, whatever its name
-//! suggests: the client drops `GENERIC (DND)` by its `SkillRaceClassInfo.flags & 0x2`, never by its
-//! category (decision 1091). A skill line's own `categoryId` is `SkillLine.dbc` column 1 (the
-//! `SkillLinefmt` layout above).
-//!
-//! Skill line ids are stable, well-known constants across the whole classic tool ecosystem
-//! (vmangos `SharedDefines.h`'s `SkillType` enum, itself commented "Data from SpellLine.dbc (1.12.1
-//! checked)") — Frost=6, Fire=8, … — cross-checked directly by this module's own real-data tests.
+//! - `SkillLine.dbc`, `SkillLinefmt = "nixssssssssxxxxxxxxxxi"`.
+//! - `SkillLineAbility.dbc`, `SkillLineAbilityfmt = "niiiixxiiiiixxi"`: one row per spell, the
+//!   first in file order, except `forward_spellid`, the first non-zero across the spell's rows as
+//!   in vmangos's `SpellMgr::GetSpellBookSuccessorSpellId`.
+//! - `SkillRaceClassInfo.dbc`, `SkillRaceClassInfofmt = "diiiiiix"`: the row admitting the
+//!   player's race and class, which the reference resolves at `0x6ddf90`; here the first such row.
+//!   With flag `0x80`, or with no such row, a spell's tab is General.
+//! - `SkillLineCategory.dbc`, 11 fields read off the raw file: the skills-pane headers in
+//!   `displayOrder`. `Not Displayed` (12) is an ordinary header; the reference hides
+//!   `GENERIC (DND)` by `SkillRaceClassInfo.flags & 0x2`, not by category.
 
 use std::collections::HashMap;
 
@@ -88,10 +38,7 @@ const COL_SLA_FORWARD_SPELL: usize = 8;
 const COL_SLA_TRIVIAL_HIGH: usize = 10;
 const COL_SLA_TRIVIAL_LOW: usize = 11;
 
-/// Hard stop on a rank-chain walk ([`SkillLineCatalog::highest_known_rank`]). The real build-5875
-/// data is acyclic and its longest chain is **9** hops (Heroic Strike 78 → … → 25286, probed over
-/// every one of the 406 chained spells), so this only ever fires on edited/corrupt DBCs — where a
-/// wrong answer beats a hung frame.
+/// Cap on a rank-chain walk; the 5875 data is acyclic, 9 hops at most, so only a bad DBC hits it.
 const MAX_RANK_CHAIN: usize = 16;
 
 const SKILL_LINE_CATEGORY: &str = "DBFilesClient\\SkillLineCategory.dbc";
@@ -107,70 +54,41 @@ const COL_SRCI_FLAGS: usize = 4;
 const COL_SRCI_MIN_LEVEL: usize = 5;
 const COL_SRCI_COST_INDEX: usize = 7;
 
-/// `SkillRaceClassInfo.flags` bit `0x80` — cmangos `DBCEnums.h`'s `SKILL_FLAG_DISPLAY_SORTED`. The
-/// spellbook tab classifier reads it as the low byte's sign (`(int8) < 0`): set ⇒ the skill line's
-/// spells sort into the **General** tab rather than the line's own (decision 0228). Real
-/// build-5875 data for a human warrior: set on `Racial - Human`, `GENERIC (DND)`, the proficiency/
-/// language/riding lines; clear on the class combat lines (`Arms`/`Fury`/`Protection`).
+/// Flag `0x80` (cmangos `SKILL_FLAG_DISPLAY_SORTED`), which the tab classifier reads as the low
+/// byte's sign: the line's spells go to the General tab.
 const SKILL_FLAG_DISPLAY_SORTED: u32 = 0x80;
 
-/// `SkillRaceClassInfo.flags` bit `0x20` — vmangos `DBCEnums.h`'s `SKILL_FLAG_UNLEARNABLE`
-/// ("Skill can be unlearned"): the skills pane's unlearn-button gate, and the exact bit the
-/// server's own `CMSG_UNLEARN_SKILL` handler enforces (vmangos `SkillHandler.cpp` — a request
-/// for a line without it is dropped and anticheat-flagged, so the client must never offer it).
+/// Flag `0x20` (vmangos `SKILL_FLAG_UNLEARNABLE`), the unlearn button's gate: the server drops and
+/// flags a `CMSG_UNLEARN_SKILL` for a line without it (`SkillHandler.cpp`).
 const SKILL_FLAG_UNLEARNABLE: u32 = 0x20;
 
-/// `SkillRaceClassInfo.flags` bit `0x1` — a line the Skills tab lists even at **rank 0** (the list
-/// build's `0x4d2cb0` untrained gate). Unnamed in the mangos enums; named here for what the bytes
-/// do.
+/// Flag `0x1`: the Skills tab lists the line even at rank 0 (`0x4d2cb0`); unnamed in mangos.
 const SKILL_FLAG_ALWAYS_DISPLAY: u32 = 0x1;
 
-/// `SkillRaceClassInfo.flags` bit `0x2` — the Skills tab **drops the line entirely**
-/// (`4d2d9f test dl,0x2`, wow-re `skillframe-display-list.md`). mangos names this bit
-/// `SKILL_FLAG_NO_SKILLUP_MESSAGE` from a different call site; in the display list it is a hide
-/// bit, and it is what keeps `Dual Wield`, the racial lines, the per-mount riding lines and
-/// `GENERIC (DND)` off the real client's pane. mangos's "different call site" is the skill-up
-/// message watcher — the bit is half of [`SkillRaceClass::skill_up_silent`]'s `0x402` mask.
+/// Flag `0x2`: the Skills tab drops the line (`0x4d2d9f`); it also silences skill-ups, hence
+/// mangos's name, `SKILL_FLAG_NO_SKILLUP_MESSAGE`.
 const SKILL_FLAG_HIDDEN: u32 = 0x2;
 
-/// `SkillRaceClassInfo.flags` bit `0x4` — an untrained (rank 0) line becomes visible once the
-/// player reaches the row's `reqLevel`. Also one of the two bits gating the client's step-cost
-/// lookup; unnamed in the mangos enums.
+/// Flag `0x4`: an untrained line shows from the row's `reqLevel`; unnamed in mangos.
 const SKILL_FLAG_TRAINABLE_AT_LEVEL: u32 = 0x4;
 
-/// `SkillRaceClassInfo.flags` bit `0x400` — vmangos `DBCEnums.h`'s `SKILL_FLAG_MONO_VALUE` (a
-/// single-rank line). The real client's `GetSkillLineInfo` **overrides** its `skillMaxRank` return
-/// to `1` whenever the admitting row carries this bit, whatever the player's own skill descriptor
-/// says (wow-re `system/tradeskill/scratch/skillframe-seed-abandon.md`: `0x4d3610`, the
-/// `4d38b1 test ah,0x4` branch). That override is why a class skill the server reports as `300/300`
-/// draws as `SkillFrame.lua`'s gray, rank-text-less "proficiency" bar in the real client — the Lua
-/// gate is `skillMaxRank == 1`, and the DBC, not the wire, is what puts it there. Real build-5875
-/// data for a night-elf hunter: set on `Beast Mastery`/`Marksmanship`/`Survival` (0x410), `Dual
-/// Wield`/`Night Elf Racial`/the per-mount riding lines (0x492); clear on every weapon line, the
-/// armor proficiencies, the languages, `Riding` and the professions.
+/// Flag `0x400` (vmangos `SKILL_FLAG_MONO_VALUE`): `GetSkillLineInfo` returns `skillMaxRank` 1
+/// whatever the descriptor says (`0x4d3610`), so `SkillFrame.lua` draws a proficiency bar.
 const SKILL_FLAG_MONO_VALUE: u32 = 0x400;
 
-/// One skill line's display identity (`SkillLine.dbc`) — a spellbook tab's name + icon, and the
-/// skills pane's grouping key.
+/// A skill line's display: the spellbook tab's name and icon, and its skills-pane category.
 #[derive(Clone, Debug, PartialEq)]
 pub struct SkillLineInfo {
     pub name: String,
-    /// `categoryId` (column 1) — the [`SkillLineCategory`](Self) bucket the skills pane groups
-    /// this line under ([`SkillLineCatalog::category`]); 0 when absent.
+    /// `categoryId`, column 1: the skills-pane group ([`SkillLineCatalog::category`]).
     pub category_id: u32,
-    /// The tab icon's MPQ path (`Interface\Icons\…`, extensionless); `None` when the line's
-    /// `spellIcon` id is 0/unresolved (render the fallback question mark, the spell catalog's own
-    /// convention).
+    /// The tab icon's extensionless path (`Interface\Icons\…`), from `spellIcon`, column 21.
     pub icon: Option<String>,
-    /// `description_lang` enUS (column 12) — the skills pane's detail-pane body
-    /// (`GetSkillLineInfo`'s 13th return). Professions carry the trade's flavor sentence, weapon
-    /// lines the shared "Higher weapon skill increases your chance to hit."; empty when the row
-    /// has none.
+    /// enUS `description_lang`, column 12: `GetSkillLineInfo`'s 13th return.
     pub description: String,
 }
 
-/// One `SkillRaceClassInfo.dbc` row: which race/class it admits, plus everything the client reads
-/// off it ([`SkillRaceClass`], the caller-facing half).
+/// One `SkillRaceClassInfo.dbc` row: the race and class masks, and its [`SkillRaceClass`].
 #[derive(Clone, Copy, Debug)]
 struct SrciRow {
     race_mask: u32,
@@ -178,121 +96,81 @@ struct SrciRow {
     row: SkillRaceClass,
 }
 
-/// The `SkillRaceClassInfo.dbc` row the client resolved for a given skill line × race × class —
-/// the whole of what its Skills-tab display law reads (wow-re
-/// `system/tradeskill/scratch/skillframe-display-list.md`: the list build `0x4d2cb0` and
-/// `GetSkillLineInfo 0x4d3610`). Copy-cheap; obtained from
-/// [`SkillLineCatalog::race_class`].
+/// The `SkillRaceClassInfo.dbc` fields the reference's Skills tab reads for a line, race and class
+/// (the list build `0x4d2cb0`, `GetSkillLineInfo` `0x4d3610`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct SkillRaceClass {
-    /// `flags` (column 4) — the bit field the predicates below read.
+    /// `flags`, column 4.
     pub flags: u32,
-    /// `reqLevel` (column 5) — the player level at which a not-yet-trained line starts showing
-    /// (only consulted with [`SKILL_FLAG_TRAINABLE_AT_LEVEL`]).
+    /// `reqLevel`, column 5: the level an untrained `0x4` line starts showing at.
     pub min_level: u32,
-    /// `skillCostID` (column 7) — `GetSkillLineInfo`'s 12th return is this **plus one**
-    /// (`0x4d3a06`). Inert on this build: every branch that would paint from it is repainted by
-    /// the normal-skill/proficiency branches after it.
+    /// `skillCostID`, column 7: `GetSkillLineInfo`'s 12th return is this plus one (`0x4d3a06`).
     pub cost_index: u32,
 }
 
 impl SkillRaceClass {
-    /// Whether the Skills tab drops this line **entirely** — `flags & 0x2`, the client's own
-    /// `4d2d9f test dl,0x2 / jne` in the list build. This is what makes `Dual Wield`, the racial
-    /// lines, the per-mount riding lines and `GENERIC (DND)` invisible in the real client even
-    /// though the server sends them like any other skill.
+    /// Whether the Skills tab drops the line: this keeps `Dual Wield`, the racials, the riding
+    /// lines and `GENERIC (DND)` off the pane though the server sends them like any other.
     pub fn hidden(self) -> bool {
         self.flags & SKILL_FLAG_HIDDEN != 0
     }
 
-    /// Whether this is a **single-rank** line — `flags & 0x400`, which makes the client's
-    /// `GetSkillLineInfo` report `skillMaxRank = 1` whatever the descriptor says
-    /// ([`SKILL_FLAG_MONO_VALUE`]).
+    /// Whether the line is single-rank ([`SKILL_FLAG_MONO_VALUE`]).
     pub fn mono(self) -> bool {
         self.flags & SKILL_FLAG_MONO_VALUE != 0
     }
 
-    /// Whether a change to this line prints **no** skill-up chat line — the real client's
-    /// rank-watcher gate (`0x5de180`, wow-re tradeskill TU-E): the message is skipped when the
-    /// resolved row's flag word at `+0x10` carries `0x402` =
-    /// [`SKILL_FLAG_MONO_VALUE`]`|`[`SKILL_FLAG_HIDDEN`]. On the real build-5875 data the mask
-    /// cuts the table exactly along the historically attested line: every class spec line
-    /// (`0x410`), the racials / `Dual Wield` / `GENERIC (DND)` / the per-mount riding lines
-    /// (`0x492`) and `Fist Weapons` (`0x082`) are silent — which is why a real 1.12 ding
-    /// announces no skill at all, the level-up movers being all flagged — while the other weapon
-    /// lines, `Defense`, the armor proficiencies, professions/secondary, `Lockpicking`,
-    /// `Poisons` and the languages (`0x080`/`0x0a0`) announce. The table identity is settled at
-    /// the bytes (1309's dispatch, a unanimous wow-re §5 — the corrected TU-E carries the full
-    /// chain): the flag test `0x5de358` reads the **untouched return of the `0x6ddf90`
-    /// SkillRaceClassInfo resolve**, never a `SkillLine.dbc` field — TU-E's original prose had
-    /// conflated the two adjacent row pointers.
+    /// Whether a rank change prints no skill-up line: the reference's watcher (`0x5de180`) skips it
+    /// when the flags carry `0x402`, tested at `0x5de358` on the row `0x6ddf90` resolves, never on
+    /// a `SkillLine.dbc` field.
     pub fn skill_up_silent(self) -> bool {
         self.flags & (SKILL_FLAG_MONO_VALUE | SKILL_FLAG_HIDDEN) != 0
     }
 
-    /// Whether the line can be unlearned — `flags & 0x20` ([`SKILL_FLAG_UNLEARNABLE`]). The
-    /// client ANDs this with a nonzero skill **step**; that half lives with the descriptor, at
-    /// the feed.
+    /// Whether the line can be unlearned; the reference also requires a nonzero skill step, which
+    /// the descriptor carries.
     pub fn unlearnable(self) -> bool {
         self.flags & SKILL_FLAG_UNLEARNABLE != 0
     }
 
-    /// Whether a line the player holds at **rank 0** still gets a row, for a player at
-    /// `player_level` — the list build's own gate (`0x4d2cb0`): shown outright with
-    /// [`SKILL_FLAG_ALWAYS_DISPLAY`], else only when it is [`SKILL_FLAG_TRAINABLE_AT_LEVEL`] and
-    /// the player has reached [`Self::min_level`]. A line at rank ≥ 1 never consults this.
+    /// Whether a rank-0 line gets a row at `player_level` (`0x4d2cb0`); a trained line never asks.
     pub fn displays_untrained(self, player_level: u32) -> bool {
         self.flags & SKILL_FLAG_ALWAYS_DISPLAY != 0
             || (self.flags & SKILL_FLAG_TRAINABLE_AT_LEVEL != 0 && player_level >= self.min_level)
     }
 }
 
-/// One spell's `SkillLineAbility.dbc` row (module doc columns; first row wins across race/class
-/// variants): the skill line it belongs to, the rank required to learn it, and the trivial ranks
-/// the crafting book's difficulty colors band against (the color law TU-C confirmed at the bytes,
-/// decision 0446).
+/// A spell's `SkillLineAbility.dbc` row: its line, required rank, and the trivial ranks the
+/// crafting book's difficulty colours band on (`0x4fca20`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct SlaInfo {
-    /// `skillId` (column 1) — the owning skill line.
+    /// `skillId`, column 1.
     pub skill_id: u32,
-    /// `req_skill_value` (column 7) — the line rank required to learn/use the ability.
+    /// `req_skill_value`, column 7: the line rank the ability needs.
     pub req_skill_value: u32,
-    /// `forward_spellid` (column 8) — the **next rank** of this ability, or 0 when it has none.
-    /// This column is the whole rank-chain graph: 406 of the 4753 spells carry it, and they are
-    /// exactly the abilities the server supersedes (vmangos gates every `SMSG_SUPERCEDED_SPELL`
-    /// it sends on `GetSpellBookSuccessorSpellId`, `Player::AddSpell`) — the warrior/rogue
-    /// physical lines, the profession tier openers, weapon skills. Caster nukes/heals carry 0:
-    /// their ranks all stay known and castable, which is what makes vanilla down-ranking work.
+    /// `forward_spellid`, column 8: the next rank, or 0. Only the abilities the server supersedes
+    /// carry it (vmangos `Player::AddSpell`); caster ranks carry 0 and all stay castable.
     pub forward_spell_id: u32,
-    /// `min_value` (column 11) — TrivialSkillLineRankLow: yellow at-or-above, orange below.
+    /// `min_value`, column 11: yellow from here, orange below.
     pub trivial_low: u32,
-    /// `max_value` (column 10) — TrivialSkillLineRankHigh: gray at-or-above; green at-or-above
-    /// the low/high midpoint. Both 0 on non-recipe rows (class abilities, the openers).
+    /// `max_value`, column 10: gray from here, green from the low/high midpoint; 0 on non-recipes.
     pub trivial_high: u32,
 }
 
-/// `SkillLine.dbc` × `SkillLineAbility.dbc` × `SkillRaceClassInfo.dbc`, joined: a spell's skill
-/// line, a line's display, and the per-race/class tab routing (the General collapse).
+/// The skill tables joined: a spell's line, a line's display, and the per-race/class routing.
 pub struct SkillLineCatalog {
     lines: HashMap<u32, SkillLineInfo>,
     abilities: HashMap<u32, SlaInfo>,
-    /// `SkillLineCategory.dbc`: id → (enUS name, displayOrder) — the skills pane's headers.
+    /// `SkillLineCategory.dbc`: id to (enUS name, displayOrder).
     categories: HashMap<u32, (String, u32)>,
-    /// skill line id → its `SkillRaceClassInfo` rows (empty when the DBC failed to load — then
-    /// [`Self::spell_tab`] skips the General collapse and keeps each line its own tab).
+    /// Skill line id to its `SkillRaceClassInfo` rows; empty if the DBC failed to load.
     race_class: HashMap<u32, Vec<SrciRow>>,
-    /// The `forward_spellid` graph inverted: next rank → the rank before it. Injective on the
-    /// real build-5875 data (probed: not one of the 406 chained spells is the successor of two
-    /// different predecessors), so a spell has at most one previous rank and
-    /// [`Self::chain_head`]'s walk is unambiguous.
+    /// `forward_spellid` inverted, next rank to previous; injective on the 5875 data.
     rank_prev: HashMap<u32, u32>,
 }
 
 impl SkillLineCatalog {
-    /// Build a catalog holding only a spell→line map — for tests and synthetic fixtures
-    /// ([`crate::SpellCatalog::from_displays`]'s sibling). The live path is
-    /// [`load_skill_line_catalog`]; everything but [`Self::spell_to_line`]/[`Self::ability`]
-    /// answers empty.
+    /// A catalog of spell-to-line pairs only, for tests and fixtures.
     pub fn from_spell_lines(pairs: impl IntoIterator<Item = (u32, u32)>) -> Self {
         Self {
             abilities: pairs
@@ -322,14 +200,12 @@ impl SkillLineCatalog {
         self.abilities.get(&spell_id).map(|a| a.skill_id)
     }
 
-    /// A spell's full `SkillLineAbility` row ([`SlaInfo`]) — the crafting book's difficulty and
-    /// requirement source (0437).
+    /// A spell's `SkillLineAbility` row.
     pub fn ability(&self, spell_id: u32) -> Option<&SlaInfo> {
         self.abilities.get(&spell_id)
     }
 
-    /// The **next rank** of `spell_id` ([`SlaInfo::forward_spell_id`]), or `None` when the ability
-    /// doesn't rank up this way — vmangos's `SpellMgr::GetSpellBookSuccessorSpellId`.
+    /// The next rank of `spell_id`, as vmangos's `SpellMgr::GetSpellBookSuccessorSpellId`.
     pub fn rank_successor(&self, spell_id: u32) -> Option<u32> {
         self.abilities
             .get(&spell_id)
@@ -337,9 +213,7 @@ impl SkillLineCatalog {
             .filter(|&id| id != 0)
     }
 
-    /// The **first** rank of `spell_id`'s chain — walk [`Self::rank_prev`] back to the spell that
-    /// nothing forwards to. `spell_id` itself when it heads its own chain (including the common
-    /// case of no chain at all).
+    /// The first rank of `spell_id`'s chain, `spell_id` itself when it has none.
     fn chain_head(&self, spell_id: u32) -> u32 {
         let mut head = spell_id;
         for _ in 0..MAX_RANK_CHAIN {
@@ -351,17 +225,46 @@ impl SkillLineCatalog {
         head
     }
 
-    /// The **highest rank of `spell_id`'s ability that `known` contains** — the rank an action-bar
-    /// slot pointing at `spell_id` must actually hold. `None` when no rank of the chain is known
-    /// (an empty book, or an ability the character never learned): the caller leaves the slot
-    /// alone rather than pointing it somewhere arbitrary.
-    ///
-    /// Walks the whole chain from its head, not just forward from `spell_id`, so it answers for a
-    /// *downgrade* (the bar holds rank 5, the book was pushed back to rank 4) as well as the
-    /// ordinary rank-up. The server only ever keeps one rank of a chained ability active
-    /// (vmangos `Player::AddSpell` marks the old one `active = false` and it drops out of
-    /// `SMSG_INITIAL_SPELLS`), so in practice at most one rank is ever known and "highest" is
-    /// simply "the one".
+    /// Whether a higher rank of `spell_id` is known, the reference's `KnownHigherRank`
+    /// (`0x60c8d0`); the trainer's colouring and state re-evaluator OR it with plain known-ness.
+    pub fn higher_rank_known(
+        &self,
+        spell_id: u32,
+        known: &std::collections::BTreeSet<u32>,
+    ) -> bool {
+        let mut cur = spell_id;
+        for _ in 0..MAX_RANK_CHAIN {
+            let Some(next) = self.rank_successor(cur) else {
+                return false;
+            };
+            if known.contains(&next) {
+                return true;
+            }
+            cur = next;
+        }
+        false
+    }
+
+    /// A catalog of ability rows only, for tests.
+    pub fn from_abilities(abilities: impl IntoIterator<Item = (u32, SlaInfo)>) -> Self {
+        let abilities: HashMap<u32, SlaInfo> = abilities.into_iter().collect();
+        let rank_prev = abilities
+            .iter()
+            .filter(|(_, a)| a.forward_spell_id != 0)
+            .map(|(id, a)| (a.forward_spell_id, *id))
+            .collect();
+        Self {
+            abilities,
+            lines: HashMap::new(),
+            categories: HashMap::new(),
+            race_class: HashMap::new(),
+            rank_prev,
+        }
+    }
+
+    /// The highest known rank of `spell_id`'s chain, the rank an action-bar slot must hold. It
+    /// walks from the chain's head, so a downgrade resolves too; the server keeps one rank of a
+    /// chain active (vmangos `Player::AddSpell`).
     pub fn highest_known_rank(
         &self,
         spell_id: u32,
@@ -381,31 +284,22 @@ impl SkillLineCatalog {
         best
     }
 
-    /// The spellbook **tab** a spell lands in for a character of `race`/`class` (1-based unit
-    /// bytes): the spell's skill line, unless that line routes to General (decision 0228). Returns
-    /// `0` (the General tab) when the spell has no skill line, no `SkillRaceClassInfo` row admits
-    /// this race/class, or the matching row carries [`SKILL_FLAG_DISPLAY_SORTED`]; the line's own
-    /// id otherwise. With `race`/`class` `0` or out of range (unknown character), or when no
-    /// `SkillRaceClassInfo` data loaded, the collapse is skipped — the raw skill line is returned.
+    /// The spellbook tab for a spell and a 1-based `race`/`class`: its skill line, or 0 for
+    /// General. An unknown race or class, or no routing data, keeps the raw line.
     pub fn spell_tab(&self, spell_id: u32, race: u8, class: u8) -> u32 {
         let Some(line) = self.spell_to_line(spell_id) else {
             return 0; // no skill line → General
         };
-        // No character context, or no routing data — keep the raw line (pre-collapse behavior).
         if self.race_class.is_empty() || !(1..=32).contains(&race) || !(1..=32).contains(&class) {
             return line;
         }
         match self.srci_row(line, race, class) {
-            // A matching row without the sort flag keeps the line's own tab.
             Some(r) if r.row.flags & SKILL_FLAG_DISPLAY_SORTED == 0 => line,
-            // The sort flag, or no admitting row for this race/class → General.
             _ => 0,
         }
     }
 
-    /// The first `SkillRaceClassInfo` row of `line_id` admitting a 1-based `race`/`class` (mask
-    /// `0` admits all) — the standard classic row-match ([`Self::spell_tab`]'s own, factored out
-    /// for [`Self::abandonable`]). `None` for out-of-range race/class or no admitting row.
+    /// The first row of `line_id` admitting `race`/`class`; a zero mask admits all.
     fn srci_row(&self, line_id: u32, race: u8, class: u8) -> Option<&SrciRow> {
         if !(1..=32).contains(&race) || !(1..=32).contains(&class) {
             return None;
@@ -420,53 +314,38 @@ impl SkillLineCatalog {
         })
     }
 
-    /// Whether `line_id` can be unlearned by a character of `race`/`class` (1-based unit bytes):
-    /// the admitting `SkillRaceClassInfo` row carries [`SKILL_FLAG_UNLEARNABLE`] (`0x20`) — the
-    /// skills pane's unlearn-button predicate, and byte-for-byte the server's own gate (vmangos
-    /// `SkillHandler.cpp`). `false` with no routing data, unknown race/class, or no admitting
-    /// row — a missing button beats offering an unlearn the server would anticheat-flag.
+    /// Whether `race`/`class` can unlearn `line_id`, the server's own gate (`SkillHandler.cpp`);
+    /// false when unresolved, as the server flags a refused unlearn.
     pub fn abandonable(&self, line_id: u32, race: u8, class: u8) -> bool {
         self.race_class(line_id, race, class)
             .is_some_and(SkillRaceClass::unlearnable)
     }
 
-    /// The `SkillRaceClassInfo` row the client resolves for `line_id` × `race`/`class` (1-based
-    /// unit bytes) — [`SkillRaceClass`], the whole of what the Skills tab's display law reads.
-    /// `None` when no row admits this character: the real client's list build drops such a line
-    /// outright (`0x4d2cb0`'s `!srci → continue`), so a caller building the pane must too.
+    /// The row the reference resolves for `line_id`, `race` and `class`; with none, its list build
+    /// drops the line (`0x4d2cb0`), and so must the pane.
     pub fn race_class(&self, line_id: u32, race: u8, class: u8) -> Option<SkillRaceClass> {
         self.srci_row(line_id, race, class).map(|r| r.row)
     }
 
-    /// Whether `line_id` is a **single-rank** line for `race`/`class` (1-based unit bytes): the
-    /// admitting `SkillRaceClassInfo` row carries [`SKILL_FLAG_MONO_VALUE`] (`0x400`), so the
-    /// client's `GetSkillLineInfo` reports its `skillMaxRank` as `1` no matter what the server's
-    /// descriptor holds — and the skills pane draws it as a proficiency (gray bar, no rank text).
-    /// `false` with no routing data, unknown race/class, or no admitting row: a line we can't
-    /// classify keeps the server's own numbers rather than being silently blanked.
+    /// Whether `line_id` is single-rank for `race`/`class`; unresolved keeps the server's numbers.
     pub fn mono_value(&self, line_id: u32, race: u8, class: u8) -> bool {
         self.race_class(line_id, race, class)
             .is_some_and(SkillRaceClass::mono)
     }
 
-    /// Whether a rank change in `line_id` prints the skill-up / skill-gained chat line for a
-    /// character of `race`/`class` (1-based unit bytes) — [`SkillRaceClass::skill_up_silent`],
-    /// inverted. `false` with no admitting row: the real watcher skips the message when its
-    /// `SkillRaceClassInfo` resolve comes back empty too (`0x5de352 je`, the same taken branch as
-    /// the flag test — 1309's §5 chain, decision 1314), so a line this character can't legally
-    /// hold stays silent however it got into the block.
+    /// Whether a rank change in `line_id` prints a skill-up line for `race`/`class`; with no
+    /// admitting row the reference stays silent too (`0x5de352`).
     pub fn announces_skill_ups(&self, line_id: u32, race: u8, class: u8) -> bool {
         self.race_class(line_id, race, class)
             .is_some_and(|rc| !rc.skill_up_silent())
     }
 
-    /// A skill line's display (name + tab icon), by id.
+    /// A skill line's display, by id.
     pub fn line(&self, line_id: u32) -> Option<&SkillLineInfo> {
         self.lines.get(&line_id)
     }
 
-    /// A `SkillLineCategory.dbc` row's `(name, displayOrder)` — the skills pane's header for a
-    /// line's [`SkillLineInfo::category_id`]; `None` for 0/unknown.
+    /// A `SkillLineCategory.dbc` row's `(name, displayOrder)`, a skills-pane header.
     pub fn category(&self, category_id: u32) -> Option<(&str, u32)> {
         self.categories
             .get(&category_id)
@@ -517,8 +396,7 @@ fn skill_line_category_schema() -> Schema {
     s
 }
 
-/// Load `SkillLineCategory.dbc` — id → (name, displayOrder). Missing/unparseable degrades to an
-/// empty map (the skills pane then renders one flat group).
+/// `SkillLineCategory.dbc`; an unreadable file gives an empty map and the pane one flat group.
 fn load_categories(chain: &mut Chain) -> HashMap<u32, (String, u32)> {
     let mut map = HashMap::new();
     let Ok(bytes) = chain.read_file(SKILL_LINE_CATEGORY) else {
@@ -548,8 +426,7 @@ fn skill_race_class_info_schema() -> Schema {
     s
 }
 
-/// The `SkillRaceClassInfo.dbc` rows keyed by skill line — the General-collapse routing table. A
-/// missing/unparseable file returns an empty map (the caller degrades to "each line its own tab").
+/// `SkillRaceClassInfo.dbc` rows by skill line; an unreadable file gives an empty map.
 fn load_race_class_info(chain: &mut Chain) -> HashMap<u32, Vec<SrciRow>> {
     let mut map: HashMap<u32, Vec<SrciRow>> = HashMap::new();
     let bytes = match chain.read_file(SKILL_RACE_CLASS_INFO) {
@@ -623,9 +500,7 @@ pub fn load_skill_line_catalog(chain: &mut Chain) -> Result<SkillLineCatalog> {
             (u32_at(r, COL_SLA_SKILL_ID), u32_at(r, COL_SLA_SPELL_ID))
         {
             let forward_spell_id = u32_at(r, COL_SLA_FORWARD_SPELL).unwrap_or(0);
-            // First row wins (module doc): deterministic by file order. 44 of the 4753 spells
-            // carry more than one row (race/class variants) — every spell probed by the tests
-            // below has exactly one.
+            // The first row in file order wins.
             let slot = abilities.entry(spell_id).or_insert(SlaInfo {
                 skill_id,
                 req_skill_value: u32_at(r, COL_SLA_REQ_SKILL_VALUE).unwrap_or(0),
@@ -633,8 +508,7 @@ pub fn load_skill_line_catalog(chain: &mut Chain) -> Result<SkillLineCatalog> {
                 trivial_low: u32_at(r, COL_SLA_TRIVIAL_LOW).unwrap_or(0),
                 trivial_high: u32_at(r, COL_SLA_TRIVIAL_HIGH).unwrap_or(0),
             });
-            // …except the rank link, which takes the first NON-ZERO across the spell's rows —
-            // vmangos's `GetSpellBookSuccessorSpellId` scans all of them (module doc).
+            // Except the rank link: the first non-zero across the rows, as vmangos scans them all.
             if slot.forward_spell_id == 0 {
                 slot.forward_spell_id = forward_spell_id;
             }
diff --git a/crates/benilla-formats/src/skill_lines/tests.rs b/crates/benilla-formats/src/skill_lines/tests.rs
index 7741d492..f4b7d5b2 100644
--- a/crates/benilla-formats/src/skill_lines/tests.rs
+++ b/crates/benilla-formats/src/skill_lines/tests.rs
@@ -1,11 +1,9 @@
-//! The catalog's tests — the real-data pins (skip without client data) and the
-//! synthetic rank-chain cases. Split from `mod.rs` for size only (one concern, two files).
+//! Skill-line catalog tests: real-data pins, which skip without client data, and synthetic rank
+//! chains.
 
 use super::*;
 
-/// Resolve real spells to their real skill lines on the build-5875 data, cross-checked
-/// against vmangos `SharedDefines.h`'s `SkillType` enum (Frost=6, Fire=8 — the module doc's
-/// own citation). Skips without client data.
+/// Line ids as vmangos `SharedDefines.h`'s `SkillType` has them (Frost 6, Fire 8).
 #[test]
 fn real_skill_line_catalog_resolves_known_spells() {
     let data = crate::wow_data_or_skip!();
@@ -32,12 +30,9 @@ fn real_skill_line_catalog_resolves_known_spells() {
     assert_eq!(frost.name, "Frost");
     assert!(frost.icon.is_some(), "the Frost tab has an icon");
 
-    // An unknown spell id has no line.
     assert_eq!(cat.spell_to_line(0), None);
 
-    // The description column (12): a profession line carries the flavor sentence, a weapon
-    // line is blank — a column slip lands on another locale (empty for enUS data) or the
-    // name flags word (a parse error) and fails loudly.
+    // Column 12: a profession's own flavour sentence, the weapon lines' shared one.
     let smithing = cat.line(164).expect("Blacksmithing resolves");
     assert!(
         smithing.description.to_lowercase().contains("blacksmith"),
@@ -51,12 +46,7 @@ fn real_skill_line_catalog_resolves_known_spells() {
     );
 }
 
-/// The General collapse on real build-5875 `SkillRaceClassInfo.dbc` (decision 0228), traced on
-/// concrete spells for a human warrior (race 1, class 1) vs. a human mage (race 1, class 8):
-/// class-native combat lines keep their own tab, racials collapse to General, and a cross-class
-/// spell (a warrior's cheated Fireball) collapses to General while the SAME spell keeps its Fire
-/// tab for a mage — the class/race dependence, the whole point of the routing. Skips without
-/// client data.
+/// A human warrior against a human mage: one Fireball is General for the first, Fire for the other.
 #[test]
 fn real_spell_tab_collapses_general_by_race_and_class() {
     let data = crate::wow_data_or_skip!();
@@ -66,8 +56,7 @@ fn real_spell_tab_collapses_general_by_race_and_class() {
     const WARRIOR: u8 = 1;
     const MAGE: u8 = 8;
 
-    // Warrior class abilities keep their own class-line tabs (flag clear for a warrior):
-    // Charge/Heroic Strike/Rend on Arms (26), Battle Shout on Fury (256).
+    // Charge, Heroic Strike and Rend on Arms (26), Battle Shout on Fury (256).
     for (id, line) in [(100u32, 26u32), (78, 26), (772, 26), (6673, 256)] {
         assert_eq!(cat.spell_to_line(id), Some(line));
         assert_eq!(
@@ -77,7 +66,7 @@ fn real_spell_tab_collapses_general_by_race_and_class() {
         );
     }
 
-    // A human racial (Perception, line 754 "Racial - Human") collapses to General (0).
+    // Perception, on line 754 `Racial - Human`.
     assert_eq!(cat.spell_to_line(20600), Some(754));
     assert_eq!(
         cat.spell_tab(20600, HUMAN, WARRIOR),
@@ -85,8 +74,7 @@ fn real_spell_tab_collapses_general_by_race_and_class() {
         "a human racial routes to General"
     );
 
-    // Fireball (Fire line 8): class-dependent. A warrior has no Fire race/class row → General;
-    // a mage has one, flag clear → its own Fire tab. Same spell, different tab by class.
+    // A warrior has no Fire row; a mage's has no sort flag.
     assert_eq!(cat.spell_to_line(133), Some(8));
     assert_eq!(
         cat.spell_tab(133, HUMAN, WARRIOR),
@@ -99,15 +87,11 @@ fn real_spell_tab_collapses_general_by_race_and_class() {
         "a mage's Fireball keeps its Fire tab"
     );
 
-    // Unknown character (race/class 0): the collapse is skipped — the raw line stands.
+    // Race and class 0 keep the raw line.
     assert_eq!(cat.spell_tab(133, 0, 0), 8);
 }
 
-/// The skill-up message gate on the real build-5875 `SkillRaceClassInfo.dbc` (decision 1309,
-/// bugs B19/B245): `flags & 0x402` silences exactly the lines the 1.11/1.12 archives show
-/// silent. Expected flags read straight off the raw file this session (a struct-unpack
-/// dump): the B245 shot's announced-but-shouldn't-be lines for a night-elf hunter, the
-/// announce controls, and the class dependence. Skips without client data.
+/// `flags & 0x402` silences the lines 1.12 shows silent; expected flags read off the raw file.
 #[test]
 fn real_skill_up_announce_gate_matches_the_archives() {
     let data = crate::wow_data_or_skip!();
@@ -118,9 +102,7 @@ fn real_skill_up_announce_gate_matches_the_archives() {
     const WARRIOR: u8 = 1;
     const HUNTER: u8 = 3;
 
-    // The B245 shot, verbatim — GENERIC (DND), Survival, Night Elf Racial and Marksmanship
-    // all announced on one ding — plus the hunter's other 0x402-flagged rows (raw flags
-    // 0x492 hidden / 0x410 mono).
+    // A night-elf hunter's 0x402 rows: raw flags 0x492 (hidden) and 0x410 (mono).
     for (id, name) in [
         (183u32, "GENERIC (DND)"),
         (51, "Survival"),
@@ -134,7 +116,7 @@ fn real_skill_up_announce_gate_matches_the_archives() {
             "{name} ({id}) must be silent"
         );
     }
-    // The lines skill-ups exist FOR (raw flags 0x080/0x0a0): weapons, Defense, secondary.
+    // Raw flags 0x080/0x0a0: weapons, Defense, secondary skills.
     for (id, name) in [
         (43u32, "Swords"),
         (95, "Defense"),
@@ -147,39 +129,32 @@ fn real_skill_up_announce_gate_matches_the_archives() {
             "{name} ({id}) must announce"
         );
     }
-    // The class dependence: a warrior's own spec line is silent too (Arms 26, raw 0x410) —
-    // B19's "magic skill-ups" generalized to every class's spec lines.
+    // A warrior's own spec line is silent too (Arms 26, raw 0x410).
     assert!(
         !cat.announces_skill_ups(26, HUMAN, WARRIOR),
         "Arms must be silent"
     );
-    // Fist Weapons (473, raw 0x082): the one silent WEAPON line — the 0x2 half of the mask
-    // alone, corroborated by vmangos giving exactly this line SKILL_RANGE_MONO.
+    // Fist Weapons (473, raw 0x082), the one silent weapon line, on the 0x2 bit alone.
     assert!(
         !cat.announces_skill_ups(473, HUMAN, WARRIOR),
         "Fist Weapons must be silent"
     );
-    // No admitting row (a mage-only line for a warrior): the real watcher's empty resolve takes
-    // the same skip branch as the flag test (`0x5de352` — decision 1314).
+    // No admitting row (a mage line for a warrior): the reference skips too (`0x5de352`).
     assert!(
         !cat.announces_skill_ups(6, HUMAN, WARRIOR),
         "a row-less line is silent"
     );
 }
 
-/// The `SlaInfo` columns on the real build-5875 `SkillLineAbility.dbc` (0437) — expected
-/// values read straight off the raw file's rows this session (a struct-unpack dump, module
-/// doc): recipes carry the trivial ranks, the profession openers carry zeros. A column slip
-/// fails loudly. Skips without client data.
+/// Expected values read off the raw file's rows.
 #[test]
 fn real_skill_line_ability_reads_requirement_and_trivial_ranks() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_skill_line_catalog(&mut chain).expect("load skill lines");
 
-    // Recipes: (spell, line, req, trivial_low, trivial_high) — raw rows, module doc.
-    // 2963 Bolt of Linen Cloth (Tailoring 197), 2330 Minor Healing Potion (Alchemy 171),
-    // 2538 Charred Wolf Meat (Cooking 185), 3920 Crafted Light Shot (Engineering 202).
+    // Bolt of Linen Cloth (Tailoring), Minor Healing Potion (Alchemy), Charred Wolf Meat
+    // (Cooking), Crafted Light Shot (Engineering).
     for (spell, line, req, low, high) in [
         (2963u32, 197u32, 1u32, 25u32, 50u32),
         (2330, 171, 1, 55, 95),
@@ -199,8 +174,7 @@ fn real_skill_line_ability_reads_requirement_and_trivial_ranks() {
         );
     }
 
-    // The openers (effect-47 window spells) sit on their line with zero trivial ranks:
-    // 3908 Tailoring → 197, 7411 Enchanting → 333.
+    // The Tailoring and Enchanting openers carry zero trivial ranks.
     for (spell, line) in [(3908u32, 197u32), (7411, 333)] {
         let sla = cat.ability(spell).expect("opener has an SLA row");
         assert_eq!(
@@ -210,9 +184,7 @@ fn real_skill_line_ability_reads_requirement_and_trivial_ranks() {
     }
 }
 
-/// `SkillLineCategory.dbc` + the line→category join on the real build-5875 files (0437 phase
-/// 4) — expected values read straight off the raw dump (module doc). Skips without client
-/// data.
+/// Expected values read off the raw `SkillLineCategory.dbc`.
 #[test]
 fn real_skill_categories_name_and_order_the_pane_groups() {
     let data = crate::wow_data_or_skip!();
@@ -225,8 +197,7 @@ fn real_skill_categories_name_and_order_the_pane_groups() {
     assert_eq!(cat.category(9), Some(("Secondary Skills", 4)));
     assert_eq!(cat.category(6), Some(("Weapon Skills", 5)));
     assert_eq!(cat.category(10), Some(("Languages", 7)));
-    // Category 12 is a real row like any other — NOT a hide bucket: the client's list build
-    // drops `GENERIC (DND)` by its `flags & 0x2`, never by its category (decision 1091).
+    // Category 12 is an ordinary header, not a hide bucket.
     assert_eq!(cat.category(12), Some(("Not Displayed", 8)));
     assert_eq!(cat.category(0), None);
 
@@ -241,35 +212,28 @@ fn real_skill_categories_name_and_order_the_pane_groups() {
     }
 }
 
-/// `SkillRaceClassInfo.flags & 0x20` on the real build-5875 file: professions and secondary
-/// skills are abandonable, class/weapon/language lines are not — the unlearn button's real
-/// data split (a human warrior, race 1 / class 1). Skips without client data.
+/// For a human warrior (race 1, class 1), primary professions are abandonable; secondary skills
+/// and class, weapon and language lines are not.
 #[test]
 fn real_abandonable_split_professions_yes_weapons_no() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_skill_line_catalog(&mut chain).expect("load skill lines");
 
-    // PRIMARY professions carry 0xA0 (0x80 sort | 0x20 unlearnable) — the red circle-slash:
-    // Blacksmithing, Tailoring, Engineering, Alchemy, Enchanting, Leatherworking, Skinning.
+    // Primary professions carry 0xA0: Blacksmithing, Tailoring, Engineering, Alchemy,
+    // Enchanting, Leatherworking, Skinning.
     for line in [164u32, 197, 202, 171, 333, 165, 393] {
         assert!(cat.abandonable(line, 1, 1), "line {line} is abandonable");
     }
-    // SECONDARY skills (First Aid/Fishing/Cooking) are 0x80 only — famously NOT droppable in
-    // 1.12 — and class school (Fire: no human-warrior row at all) / weapon / Defense /
-    // language / riding lines aren't either.
+    // First Aid, Fishing, Cooking carry 0x80 alone; Fire has no human-warrior row; then weapon,
+    // Defense, language and riding lines.
     for line in [129u32, 356, 185, 8, 43, 95, 98, 762] {
         assert!(!cat.abandonable(line, 1, 1), "line {line} is not");
     }
-    // Unknown race/class → no button (the conservative arm).
     assert!(!cat.abandonable(164, 0, 0));
 }
 
-/// `SkillRaceClassInfo.flags & 0x400` on the real build-5875 file (a night-elf hunter, race 4
-/// / class 3): the class talent lines, Dual Wield, the racial and the per-mount riding lines
-/// are MONO — the client reports their `skillMaxRank` as 1 and the pane draws them as gray
-/// proficiencies — while every weapon line, armor proficiency, language, `Riding` and
-/// profession keeps its real rank. Skips without client data.
+/// `flags & 0x400` for a night-elf hunter (race 4, class 3).
 #[test]
 fn real_mono_value_split_class_lines_yes_weapons_no() {
     let data = crate::wow_data_or_skip!();
@@ -288,14 +252,10 @@ fn real_mono_value_split_class_lines_yes_weapons_no() {
     ] {
         assert!(!cat.mono_value(line, 4, 3), "line {line} keeps its rank");
     }
-    // Unknown race/class → keep the server's numbers (the conservative arm).
     assert!(!cat.mono_value(50, 0, 0));
 }
 
-/// `SkillRaceClassInfo.flags & 0x2` on the real build-5875 file — the bit that keeps a line
-/// off the Skills tab entirely (decision 1091; wow-re `0x4d2cb0`'s `4d2d9f test dl,0x2`), plus
-/// the `reqLevel` column the untrained gate reads. A night-elf hunter, race 4 / class 3.
-/// Skips without client data.
+/// `flags & 0x2` and the `reqLevel` column for a night-elf hunter (race 4, class 3).
 #[test]
 fn real_hidden_lines_are_the_ones_the_reference_client_never_lists() {
     let data = crate::wow_data_or_skip!();
@@ -303,23 +263,19 @@ fn real_hidden_lines_are_the_ones_the_reference_client_never_lists() {
     let cat = load_skill_line_catalog(&mut chain).expect("load skill lines");
     let row = |line: u32| cat.race_class(line, 4, 3).expect("an admitting row");
 
-    // Dual Wield, Night Elf Racial, Tiger Riding, GENERIC (DND) — all 0x492, all absent from
-    // the real client's pane however high the server ranks them.
+    // Dual Wield, Night Elf Racial, Tiger Riding, GENERIC (DND): all 0x492.
     for line in [118u32, 126, 150, 183] {
         assert!(row(line).hidden(), "line {line} never gets a row");
     }
-    // Everything the ref does list: the class lines, weapons, armor, languages, Riding.
+    // What the reference lists: class lines, weapons, armor, languages, Riding.
     for line in [50u32, 51, 163, 44, 95, 162, 413, 414, 415, 98, 762, 129] {
         assert!(!row(line).hidden(), "line {line} is listed");
     }
 
-    // reqLevel (column 5) reads for real: Mail 40, Dual Wield 20.
     assert_eq!(row(413).min_level, 40, "Mail");
     assert_eq!(row(118).min_level, 20, "Dual Wield");
-    // The untrained gate is all but inert on this build's data, and the test says so: NO row
-    // in the whole file carries 0x1, and exactly ONE carries 0x4 (line 493, reqLevel 0 — a
-    // line `SkillLine.dbc` doesn't even have). So a rank-0 line is simply never listed; a
-    // `reqLevel` on its own does nothing without 0x4.
+    // No row carries 0x1 and only line 493 carries 0x4, so a rank-0 line is otherwise never
+    // listed.
     assert!(
         !row(413).displays_untrained(60),
         "Mail at rank 0 stays off the pane at any level — 0x80 carries neither gate bit"
@@ -328,20 +284,17 @@ fn real_hidden_lines_are_the_ones_the_reference_client_never_lists() {
         row(493).displays_untrained(0),
         "the single 0x4 row shows from level 0 (its reqLevel is 0)"
     );
-    // No admitting row at all → the caller drops the line (the client's own `!srci → continue`).
     assert_eq!(cat.race_class(118, 0, 0), None);
 }
 
-/// The `forward_spellid` rank graph on the real build-5875 file — the action bar's
-/// rank-normalization source (decision 0883). Skips without client data.
+/// The `forward_spellid` chains the action bar normalises ranks along.
 #[test]
 fn real_rank_chains_resolve_the_highest_known_rank() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_skill_line_catalog(&mut chain).expect("load skill lines");
 
-    // Sinister Strike ranks 1..8 — the chain the bug report walked (a level-60 rogue whose
-    // saved bar still held rank 1 while the book held only rank 8).
+    // Sinister Strike ranks 1 to 8: a saved bar can hold rank 1 while the book holds rank 8.
     const SS: [u32; 8] = [1752, 1757, 1758, 1759, 1760, 8621, 11293, 11294];
     for pair in SS.windows(2) {
         assert_eq!(
@@ -353,35 +306,60 @@ fn real_rank_chains_resolve_the_highest_known_rank() {
         );
     }
     assert_eq!(cat.rank_successor(11294), None, "rank 8 tops the chain");
-    // Warrior Charge (100 → 6178 → 11578) and Heroic Strike's 9 ranks — the two physical
-    // families the director named.
+    // Charge (100, 6178, 11578) and Heroic Strike's last link.
     assert_eq!(cat.rank_successor(100), Some(6178));
     assert_eq!(cat.rank_successor(6178), Some(11578));
     assert_eq!(cat.rank_successor(11567), Some(25286));
 
-    // From ANY rank, knowing only rank 8, the answer is rank 8 — the walk starts at the
-    // chain head, so it works downward as well as upward.
+    // Knowing only rank 8, every rank resolves to it: the walk starts at the chain head.
     let top: std::collections::BTreeSet<u32> = [11294].into_iter().collect();
     for id in SS {
         assert_eq!(cat.highest_known_rank(id, &top), Some(11294), "from {id}");
     }
-    // Knowing an intermediate rank resolves to it, not to the top of the chain.
     let mid: std::collections::BTreeSet<u32> = [1759].into_iter().collect();
     assert_eq!(cat.highest_known_rank(1752, &mid), Some(1759));
     assert_eq!(cat.highest_known_rank(11294, &mid), Some(1759));
-    // No rank of the chain known → no answer (the caller leaves the slot alone).
     assert_eq!(cat.highest_known_rank(1752, &Default::default()), None);
 
-    // Caster nukes carry NO forward link — every rank stays known and castable, which is what
-    // makes vanilla down-ranking work, and what keeps normalization off them. Fireball r1/r2,
-    // Frostbolt r1, Healing Touch r1, Renew r1, Immolate r1, Lightning Bolt r1.
+    // Caster spells carry no forward link: Fireball ranks 1 and 2, and rank 1 of Frostbolt,
+    // Healing Touch, Renew, Immolate and Lightning Bolt.
     for id in [133u32, 143, 116, 5185, 139, 348, 403] {
         assert_eq!(cat.rank_successor(id), None, "spell {id} is not chained");
         let known: std::collections::BTreeSet<u32> = [id].into_iter().collect();
         assert_eq!(cat.highest_known_rank(id, &known), Some(id));
     }
-    // A spell with no `SkillLineAbility` row at all (the auto-attack) is its own chain.
+    // Auto-attack has no `SkillLineAbility` row and is its own chain.
     let attack: std::collections::BTreeSet<u32> = [6603].into_iter().collect();
     assert_eq!(cat.rank_successor(6603), None);
     assert_eq!(cat.highest_known_rank(6603, &attack), Some(6603));
 }
+
+/// `KnownHigherRank` (`0x60c8d0`) walks forward only; the spell itself does not count.
+#[test]
+fn a_higher_rank_is_known_only_forward_along_the_chain() {
+    use std::collections::BTreeSet;
+    let row = |forward| SlaInfo {
+        skill_id: 1,
+        req_skill_value: 0,
+        forward_spell_id: forward,
+        trivial_low: 0,
+        trivial_high: 0,
+    };
+    // 10 → 11 → 12.
+    let cat = SkillLineCatalog::from_abilities([(10, row(11)), (11, row(12)), (12, row(0))]);
+    let known = |ids: &[u32]| ids.iter().copied().collect::<BTreeSet<u32>>();
+    assert!(cat.higher_rank_known(10, &known(&[12])));
+    assert!(cat.higher_rank_known(10, &known(&[11])));
+    assert!(
+        !cat.higher_rank_known(10, &known(&[10])),
+        "the spell itself is not a higher rank"
+    );
+    assert!(
+        !cat.higher_rank_known(12, &known(&[10, 11])),
+        "nothing is forward of the top rank"
+    );
+    assert!(
+        !cat.higher_rank_known(99, &known(&[10, 11, 12])),
+        "an unchained spell has no chain"
+    );
+}
diff --git a/crates/benilla-formats/src/sound_entries.rs b/crates/benilla-formats/src/sound_entries.rs
index 2a4f704d..affa4b27 100644
--- a/crates/benilla-formats/src/sound_entries.rs
+++ b/crates/benilla-formats/src/sound_entries.rs
@@ -1,16 +1,9 @@
-//! SoundEntries.dbc loader — the central **sound-kit** table every audio trigger resolves through
-//! (decision 0070): a kit = up to 10 weighted variation files + volume/flags/distance parameters.
-//! Kits are playable by id and **by name** (the client's `PlaySoundByName`, RE `0x458030`, is a
-//! name-hash into this table — the Lua `PlaySound("igMainMenuOpen")` path).
+//! `SoundEntries.dbc`, the sound-kit table every audio trigger resolves through: up to 10
+//! weighted variation files with volume, flags and distances. Kits play by id or by name:
+//! `PlaySoundByName` (`0x458030`), behind Lua's `PlaySound`, hashes the name into this table.
 //!
-//! Layout — VERIFIED against build 5875 (xxd + row decode of the extracted file, 2026-07-02): the
-//! WDBC header reports **4623 records · 29 fields · 116 B/record**. Fields:
-//! `ID(0), SoundType(1), Name(2, str), File[10](3..12, str), Freq[10](13..22),
-//! DirectoryBase(23, str), Volume(24, f32), Flags(25), MinDistance(26, f32),
-//! DistanceCutoff(27, f32), EAXDef(28)`. Spot-checked on row 3: `type 1 "Invisibility Impact",
-//! "Dispel_Low_Base.wav" ×1, dir "Sound\Spells", vol 1.0, flags 0, min 8, cutoff 45, EAX 2`.
-//! NOTE the wowdev-wiki 5875 struct claims a 30-column layout (separate `maxDistance` +
-//! `soundEntriesAdvancedID`) — it is **wrong**; trust this byte-verified one (decision 0070).
+//! 29 fields and 116-byte records in 5875. The wowdev wiki's 30-column layout, with separate
+//! `maxDistance` and `soundEntriesAdvancedID` columns, does not fit this build.
 
 use std::collections::HashMap;
 
@@ -22,12 +15,9 @@ use crate::dbc::{f32_at, parse, str_at, u32_at};
 
 const SOUND_ENTRIES: &str = "DBFilesClient\\SoundEntries.dbc";
 
-/// `Flags` bits observed in the 5875 data (domain: 0/1/0x20/0x21/0x22/0x200/0x201/0x220/0x400/
-/// 0x420). The DBC word is copied **raw** into the runtime kit flag word (`0x45c139`, wow-re
-/// `benilla-pins.md` B2, VERIFIED) and the two variation gates read separate bits: `0x400` =
-/// pitch variation (`0x458da0`), `0x800` = volume variation (`0x458c60`). No 5875 kit sets
-/// `0x800` — volume variation is dormant in this build's data. `0x20` no-duplicates, `0x200`
-/// looping (0.5.3-era wowdev meanings, behavior-consistent).
+/// `Flags` bits, copied raw into the runtime kit (`0x45c139`): `0x400` varies pitch (`0x458da0`),
+/// `0x800` volume (`0x458c60`), though no 5875 kit sets it. `0x20` no-duplicates and `0x200`
+/// looping are the wiki's 0.5.3 meanings, consistent with behaviour.
 pub mod sound_kit_flags {
     pub const NO_DUPLICATES: u32 = 0x20;
     pub const LOOPING: u32 = 0x200;
@@ -35,39 +25,35 @@ pub mod sound_kit_flags {
     pub const VARY_VOLUME: u32 = 0x800;
 }
 
-/// One sound kit: the resolved variation list + the playback parameters the kit player consumes.
+/// One sound kit: its resolved variations and playback parameters.
 pub struct SoundKit {
     pub id: u32,
-    /// `SoundType` — the kit's category (1 spells, 2 UI, 3 footsteps, … 28 zone music, 50 zone
-    /// ambience). Drives the volume-category pick and the specialized runtime caches.
+    /// The kit's category (1 spells, 2 UI, 3 footsteps, 28 zone music, 50 zone ambience), which
+    /// picks the volume category.
     pub sound_type: u32,
-    /// The `PlaySoundByName` key (e.g. `"igMainMenuOpen"`, `"LevelUp"`).
+    /// The `PlaySoundByName` key (`"igMainMenuOpen"`, `"LevelUp"`).
     pub name: String,
-    /// Variation files as `(full MPQ path, weight)` — `DirectoryBase\File[i]` joined here so
-    /// consumers never re-derive paths; only non-empty slots, weight from the matching `Freq[i]`.
+    /// Non-empty variations as `(MPQ path, Freq[i] weight)`, `DirectoryBase` and `File[i]` joined
+    /// as the reference joins them.
     pub files: Vec<(String, u32)>,
-    /// Base volume `[0,1]` (the per-shot variation math scales this — wow-re `0x458c60`).
+    /// Base volume in `[0, 1]`, scaled by the per-shot variation (`0x458c60`).
     pub volume: f32,
     pub flags: u32,
     /// Full-volume radius fed to the backend's min/max rolloff (FMOD `Sample_SetMinMaxDistance`).
     pub min_distance: f32,
-    /// Selection/cull radius: the `d² < cutoff²` audibility gate + per-frame virtualization
-    /// (wow-re `0x45cdf0`/`0x7a5000`). `0` = non-positional (no 3D cull).
+    /// The audibility radius, `d² < cutoff²`, also the per-frame virtualization cull (`0x45cdf0`,
+    /// `0x7a5000`); 0 is non-positional.
     pub distance_cutoff: f32,
-    /// `SoundSamplePreferences.dbc` FK — the per-channel EAX wet send (0/1/2 in the data;
-    /// 2 072 kits carry 0, 2 549 carry 2, 2 carry 1). **`0` means dry, not "default"**: that DBC
-    /// holds only ids 1 and 2, so the client's id-indexed slot lookup (`0x45cdc0`) returns NULL
-    /// and `FSOUND_Reverb_SetChannelProperties` (`0x7a5bf0`) skips before it even tests the
-    /// 3D-open flag. Authored dryness — and it is how NPC voice lines stay out of an interior's
-    /// reverb: **all 275 `SoundType 17` rows are `EAXDef 0`** (creature barks split 706 wet /
-    /// 285 dry). wow-re `reverb-default-and-eax-hardware.md`; benilla decision 1155.
+    /// The `SoundSamplePreferences.dbc` row for the channel's EAX send. 0 is dry, not a default:
+    /// that table holds only 1 and 2, so the slot lookup (`0x45cdc0`) returns null and
+    /// `FSOUND_Reverb_SetChannelProperties` (`0x7a5bf0`) skips. Every NPC voice kit is 0.
     pub eax_def: u32,
 }
 
-/// All kits, resolvable by id or (case-insensitively) by name.
+/// All kits, resolvable by id or, ignoring case, by name.
 pub struct SoundKitCatalog {
     kits: HashMap<u32, SoundKit>,
-    /// Lowercased `Name` → id — the client's name lookup is a case-insensitive hash.
+    /// Lowercased `Name` to id: the reference's name hash ignores case.
     by_name: HashMap<String, u32>,
 }
 
@@ -76,7 +62,7 @@ impl SoundKitCatalog {
         self.kits.get(&id)
     }
 
-    /// `PlaySoundByName` parity: resolve a kit by its `Name` column, case-insensitive.
+    /// A kit by its `Name`, ignoring case, as `PlaySoundByName` finds it.
     pub fn by_name(&self, name: &str) -> Option<&SoundKit> {
         self.by_name
             .get(&name.to_ascii_lowercase())
@@ -91,8 +77,7 @@ impl SoundKitCatalog {
         self.kits.is_empty()
     }
 
-    /// An empty catalog for consumers' pure-logic unit tests (selector state machines that need
-    /// a catalog-shaped owner but no data).
+    /// An empty catalog for consumers' unit tests.
     pub fn empty_for_tests() -> Self {
         Self {
             kits: HashMap::new(),
@@ -101,7 +86,6 @@ impl SoundKitCatalog {
     }
 }
 
-/// 29 fields — module docs carry the verified layout.
 fn sound_entries_schema() -> Schema {
     let mut s = Schema::new("SoundEntries");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -122,29 +106,15 @@ fn sound_entries_schema() -> Schema {
     s
 }
 
-/// Join one variation's `DirectoryBase` and `File[i]` into the path the archive is asked for —
-/// **the reference's own rule, byte-for-byte** (`0x45be10`, the sole caller `0x45c167` inside the
-/// `SOUNDDEFINITION` loader; wow-re `sound/scratch/soundentries-path-join.md`).
+/// `DirectoryBase` and `File[i]` joined as the reference does (`0x45be10`, called only from
+/// `0x45c167` in the `SOUNDDEFINITION` loader): `"%s%s%s"` over dir, separator and file, with no
+/// separator when the dir is empty or already ends in `\`. Nothing below normalizes further: the
+/// archive hash (`0x6549a0`) folds case and maps `/` to `\` but keeps leading and doubled
+/// separators, and there is no loose-file fallback for a single leading `\`.
 ///
-/// The client formats `"%s%s%s"` over `(dir, sep, file)` and chooses `sep` with exactly two tests:
-/// it is the empty string when `DirectoryBase` is **NULL/empty**, and when `SStrChrR(dir, '\')`
-/// says the directory **already ends in a separator**; otherwise it is `"\"`. That is the whole
-/// normalization in the client, at this layer or any other — and it has to be spelled here,
-/// because the archive layer below rescues nothing: `HashString` folds ASCII `a`–`z` to upper and
-/// maps `/` → `\` per character into the hash, and does **not** strip a leading separator, collapse
-/// a doubled one, or touch a trailing one (wow-re `mpq.md`, an evidenced absence — the hash loop
-/// read end to end). There is no loose-file fallback either: `SFileOpenFileEx`'s disk diversion
-/// takes `\\`, `X:` and a flag WoW's own startup clears, never a single leading `\`.
-///
-/// **27 of the 5875 data's 8961 variations do not resolve, and the reference cannot play them
-/// either** — 17 are simply absent from the archives (`GhostMusic01/02`, `mOgreFidget3`, and ids
-/// 195/196, where `mHumanFemaleWoundVoxA.wav` was authored across two `File` cells as
-/// `mHumanFemaleWoundVoxA` and `wav`), and the other 10 are kit **8940 `Ashbringer`**, whose
-/// `DirectoryBase` is `\Sound\Creature\Ashbringer\`: the client suppresses the *trailing*
-/// separator and then emits the *leading* one verbatim, so the path it opens
-/// (`\Sound\Creature\Ashbringer\ASH_SPEAK_01.wav`) misses in every archive although the asset is
-/// there. The Ashbringer's speak lines are dead data in the real client, and are meant to stay
-/// dead here: a leading-separator strip would be a deviation, not a fix.
+/// So the reference cannot play 27 of the 8961 shipped variations, and neither does this: 17 are
+/// absent from the archives, and 10 are kit 8940 `Ashbringer`, whose `DirectoryBase` starts with
+/// `\`. Stripping that separator would be a deviation, not a fix.
 fn join_variation(dir: &str, file: &str) -> String {
     if dir.is_empty() || dir.ends_with('\\') {
         format!("{dir}{file}")
@@ -153,7 +123,7 @@ fn join_variation(dir: &str, file: &str) -> String {
     }
 }
 
-/// Read SoundEntries.dbc off the patch chain into a [`SoundKitCatalog`].
+/// Read `SoundEntries.dbc` off the patch chain.
 pub fn load_sound_kit_catalog(chain: &mut Chain) -> Result<SoundKitCatalog> {
     let bytes = chain
         .read_file(SOUND_ENTRIES)
@@ -199,10 +169,6 @@ pub fn load_sound_kit_catalog(chain: &mut Chain) -> Result<SoundKitCatalog> {
 mod tests {
     use super::*;
 
-    /// End-to-end on the **real** build-5875 table: the byte-verified 29-field layout parses all
-    /// 4623 kits; the spot-checked row (ID 3) reads back exactly; the `PlaySoundByName` lookup is
-    /// case-insensitive; and a kit's joined `DirectoryBase\File` path is a real, readable chain
-    /// file (guards the path join against a shifted column). Skips without client data.
     #[test]
     fn real_sound_entries_parse_and_resolve() {
         let data = crate::wow_data_or_skip!();
@@ -210,7 +176,7 @@ mod tests {
         let cat = load_sound_kit_catalog(&mut chain).expect("load sound kits");
         assert_eq!(cat.len(), 4623, "all 5875 SoundEntries rows load");
 
-        // The row decoded byte-by-byte while pinning the layout (module docs).
+        // Kit 3, decoded by hand from the file's bytes.
         let kit = cat.get(3).expect("kit 3 exists");
         assert_eq!(kit.name, "Invisibility Impact");
         assert_eq!(kit.sound_type, 1);
@@ -225,7 +191,7 @@ mod tests {
         assert_eq!(kit.distance_cutoff, 45.0);
         assert_eq!(kit.eax_def, 2);
 
-        // Name lookup, case-insensitive (the client name-hash ignores case).
+        // The name lookup ignores case.
         let ui = cat.by_name("IGMINIMAPZOOMIN").expect("UI kit by name");
         assert_eq!(ui.id, 823);
         assert_eq!(ui.sound_type, 2, "type 2 = UI");
@@ -240,18 +206,14 @@ mod tests {
         );
     }
 
-    /// The `EAXDef` census the reverb send is gated on (decision 1155, bug B236). `EAXDef 0` is a
-    /// NULL `SoundSamplePreferences` slot in the client, i.e. a channel that never receives reverb
-    /// properties — so this is the authored line between wet and dry, and it must not drift.
-    /// Skips without client data.
+    /// The `EAXDef` census the reverb send is gated on: 0 is the reference's null slot, a channel
+    /// that never gets reverb.
     #[test]
     fn real_sound_entries_eaxdef_census() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_sound_kit_catalog(&mut chain).expect("load sound kits");
 
-        // Only three values exist, and `SoundSamplePreferences.dbc` has rows 1 and 2 only — so 0
-        // is "no row", never "row zero".
         let mut n = [0usize; 3];
         for k in cat.kits.values() {
             assert!(k.eax_def <= 2, "kit {} has EAXDef {}", k.id, k.eax_def);
@@ -263,8 +225,8 @@ mod tests {
             "the 5875 EAXDef census"
         );
 
-        // The load-bearing one: NPC voice lines (`SoundType 17`, what `NPCSounds.dbc` references)
-        // are dry to a kit — this is why the Thunderbrew Distillery's NPCs carry no echo.
+        // NPC voice lines (`SoundType` 17, which `NPCSounds.dbc` names) are all dry, so NPCs in a
+        // reverberant interior carry no echo.
         let voices: Vec<_> = cat.kits.values().filter(|k| k.sound_type == 17).collect();
         assert_eq!(voices.len(), 275, "the type-17 NPC voice rows");
         assert!(
@@ -272,8 +234,7 @@ mod tests {
             "every NPC voice kit is authored dry"
         );
 
-        // The control: creature barks are a genuine mix, so the gate is not a no-op that happens
-        // to silence everything.
+        // The control: creature barks mix wet and dry.
         let barks: Vec<_> = cat.kits.values().filter(|k| k.sound_type == 10).collect();
         assert!(
             barks.iter().any(|k| k.eax_def != 0) && barks.iter().any(|k| k.eax_def == 0),
@@ -281,11 +242,8 @@ mod tests {
         );
     }
 
-    /// The join's three legs, in the reference's own order (`0x45be10`): an empty directory emits
-    /// the file verbatim (26 shipped rows, e.g. 1103 `WyvernWingFlap`, whose variations are
-    /// themselves full paths), a directory that already ends in a separator gets none added, and
-    /// everything else gets exactly one. A **leading** separator is carried through untouched —
-    /// the client normalizes nothing there, and neither do we.
+    /// An empty directory emits the file alone (26 shipped rows, 1103 `WyvernWingFlap` among them,
+    /// whose variations are full paths); a leading separator is kept, as the reference keeps it.
     #[test]
     fn the_variation_join_is_the_reference_s_separator_rule() {
         assert_eq!(
@@ -307,16 +265,10 @@ mod tests {
         );
     }
 
-    /// **Every kit path this loader builds, asked of the real chain.** The numbers are the
-    /// reference's own: the binary's join resolves 8934 of 8961 variations, and the 27 it does not
-    /// are authentic dead data. An unconditional `format!("{dir}\\{file}")` — what this loader did
-    /// before the join was derived — resolves exactly three fewer, and those three are whole kits:
-    /// 1519 `TaxiNodeDiscovered`, 2988 `Unarmed Small`, 3412 `Pirate Agro` each carry one variation
-    /// and a `DirectoryBase` that already ends in a separator, so every one of them was silent.
-    ///
-    /// The test pins both sides — what resolves and what is *meant* not to — so neither a
-    /// regression nor an over-eager "fix" of the Ashbringer can land quietly. Skips without client
-    /// data.
+    /// Every kit path asked of the real chain: the reference's join resolves 8934 of 8961
+    /// variations, and the 27 it misses are dead in the reference too. An unconditional separator
+    /// would also silence kits 1519, 2988 and 3412, each one variation under a `DirectoryBase`
+    /// that ends in `\`.
     #[test]
     fn real_sound_entries_paths_resolve_exactly_as_the_reference_s_do() {
         let data = crate::wow_data_or_skip!();
@@ -341,8 +293,7 @@ mod tests {
             "variations that resolve — the binary's own count; {dead:?}"
         );
 
-        // The ten that are one kit, and the one kit that is therefore silent — in the reference
-        // too (its `DirectoryBase` opens with a separator the client passes straight through).
+        // Ten belong to kit 8940, silent in the reference too.
         let ashbringer: Vec<_> = dead.iter().filter(|(id, ..)| *id == 8940).collect();
         assert_eq!(ashbringer.len(), 10, "every ASH_SPEAK line misses");
         assert!(
@@ -350,11 +301,10 @@ mod tests {
             "the asset ships — it is the authored path that cannot reach it"
         );
 
-        // …and the other 17 are ordinary absent assets, spread across kits that mostly still play.
+        // The other 17 are absent assets, in kits that mostly still play.
         assert_eq!(dead.len() - ashbringer.len(), 17, "absent assets: {dead:?}");
 
-        // No OTHER kit is fully silent through a path benilla built. 8588 is, and is meant to be:
-        // its single variation is simply not in the archives.
+        // Only 8588, whose one variation is absent, and 8940 have nothing playable.
         let silent: Vec<u32> = cat
             .kits
             .values()
diff --git a/crates/benilla-formats/src/sound_provider.rs b/crates/benilla-formats/src/sound_provider.rs
index a230c5e4..7465e478 100644
--- a/crates/benilla-formats/src/sound_provider.rs
+++ b/crates/benilla-formats/src/sound_provider.rs
@@ -1,23 +1,7 @@
-//! `SoundProviderPreferences.dbc` — the zone reverb presets (EAX listener properties).
-//!
-//! Layout — VERIFIED against build 5875 (header + full row dump, 2026-07-03): **38 × 24 × 96 B**:
-//! `ID(0), Description(1,str), Flags(2), EAXEnvironmentSelection(3), EAXDecayTime(4,f),
-//! EAX2EnvironmentSize(5,f), EAX2EnvironmentDiffusion(6,f), EAX2Room(7,i), EAX2RoomHF(8,i),
-//! EAX2DecayHFRatio(9,f), EAX2Reflections(10,i), EAX2ReflectionsDelay(11,f), EAX2Reverb(12,i),
-//! EAX2ReverbDelay(13,f), EAX2RoomRolloff(14,f), EAX2AirAbsorption(15,f), EAX3RoomLF(16,i),
-//! EAX3DecayLFRatio(17,f), EAX3EchoTime(18,f), EAX3EchoDepth(19,f), EAX3ModulationTime(20,f),
-//! EAX3ModulationDepth(21,f), EAX3HFReference(22,f), EAX3LFReference(23,f)`.
-//! External cross-check: rows 66–92 are the canonical EAX preset table (`PRESET_GENERIC` decay
-//! 1.49 s, Room −1000 mB, Reflections −2602 mB @ 0.007 s, Reverb 200 mB @ 0.011 s — the published
-//! EAX SDK values, byte-exact), which pins every column's meaning independently of the wiki.
-//! Levels are **millibels** (dB × 100), times in seconds.
-//!
-//! Who references these: `AreaTable` cols 5/6 (dry/underwater — in 1.12 only 8 areas carry a dry
-//! pref, all dungeon floors; 568 carry underwater pref 11) and `WMOAreaTable` cols 4/5 (the real
-//! payload: ~4 000 interior group rows, CAVE/AUDITORIUM/ARENA — wired when WMO interior
-//! containment lands). The struct carries the EAX2 core the mixer's reverb consumes; the EAX3
-//! extras (cols 16–23) are near-constant defaults in 1.12 and stay unparsed until a backend uses
-//! them.
+//! `SoundProviderPreferences.dbc`: the EAX reverb presets that `AreaTable` columns 5 and 6 (dry,
+//! underwater) and `WMOAreaTable` columns 4 and 5 point at. Levels are millibels, times seconds;
+//! rows 66-92 carry the EAX SDK's published presets byte for byte, which pins the column meanings.
+//! The EAX3 columns (16-23) are near-constant in 1.12 and not parsed.
 
 use std::collections::HashMap;
 
@@ -27,27 +11,27 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 use crate::dbc::{f32_at, parse, str_at, u32_at};
 use crate::Chain;
 
-/// One reverb preset — EAX2 listener properties, in EAX units (mB levels, seconds).
+/// One reverb preset's EAX2 listener properties.
 pub struct SoundProvider {
     pub id: u32,
-    /// Preset name ("PRESET_CAVE", "Underwater", …) — debug/display only.
+    /// "PRESET_CAVE", "Underwater", …; for display only.
     pub name: String,
     pub flags: u32,
-    /// Reverberation decay time, seconds (EAX range 0.1–20).
+    /// Decay time in seconds (EAX range 0.1-20).
     pub decay_time: f32,
-    /// Master room effect level, mB (−10000..0).
+    /// Room effect level in mB (-10000..0).
     pub room: i32,
-    /// Room effect high-frequency level, mB (−10000..0) — the muffle of the wet signal.
+    /// Room high-frequency level in mB (-10000..0), the muffle of the wet signal.
     pub room_hf: i32,
-    /// High-frequency to overall decay ratio (0.1–2; <1 = highs die faster).
+    /// High-frequency to overall decay ratio (0.1-2); below 1 the highs die faster.
     pub decay_hf_ratio: f32,
-    /// Early-reflections level, mB (−10000..1000).
+    /// Early reflections level in mB (-10000..1000).
     pub reflections: i32,
-    /// Late-reverberation level, mB (−10000..2000).
+    /// Late reverberation level in mB (-10000..2000).
     pub reverb: i32,
-    /// Environment diffusion (0–1; low = echoey, high = smooth).
+    /// Environment diffusion (0-1): low is echoey, high is smooth.
     pub env_diffusion: f32,
-    /// Apparent room size, meters-ish (EAX environment size, 1–100).
+    /// EAX environment size (1-100), roughly metres.
     pub env_size: f32,
 }
 
@@ -143,9 +127,7 @@ pub fn load_sound_provider_catalog(chain: &mut Chain) -> Result<SoundProviderCat
 mod tests {
     use super::*;
 
-    /// The real 5875 table: PRESET_GENERIC (67) carries the published EAX SDK values and the
-    /// Underwater preset (11) the aggressive HF kill — the two rows the column map hangs on.
-    /// Skips without client data.
+    /// PRESET_GENERIC (67) carries the published EAX SDK values; Underwater (11) cuts all highs.
     #[test]
     fn real_provider_table_decodes() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/sound_water.rs b/crates/benilla-formats/src/sound_water.rs
index 331ffcfc..abffebdc 100644
--- a/crates/benilla-formats/src/sound_water.rs
+++ b/crates/benilla-formats/src/sound_water.rs
@@ -1,12 +1,6 @@
-//! `SoundWaterType.dbc` — the liquid-class → ambient-loop-kit map of the **above-water liquid
-//! ambient-loop system** (wow-re `liquid-ambience-loop.md`, §5-verified; benilla decision 0506):
-//! the continuous ocean/river/lava/slime sound the client plays near liquid. The driver reads the
-//! nearest wet cell's MCLQ low nibble as `class = nibble & 3`, `speed = nibble >> 2`, and resolves
-//! the kit **data-driven** through this table (store `[0xc0d898]`; not hardcoded ids): 16-byte
-//! records `ID, SoundType(class), FluidSpeed(4·speed), SoundEntriesID`.
-//!
-//! 5875 content: river 0/4/8 → 1111 RiverStill / 1112 RiverSlow / 1113 RiverFast; ocean → 1114
-//! at every speed; magma 0→3072 LavaPoolLoop, 4/8→3052 LavaFlowLoop; slime → 3880 SlimeLoop.
+//! `SoundWaterType.dbc`: the loop the client plays near liquid (`0x462a40`, table `[0xc0d898]`),
+//! keyed by the nearest wet cell's MCLQ low nibble: class `nibble & 3` and `FluidSpeed`
+//! `nibble & 0xc`, four times the speed.
 
 use std::collections::HashMap;
 
@@ -22,9 +16,7 @@ pub struct WaterSoundCatalog {
 }
 
 impl WaterSoundCatalog {
-    /// The loop kit for an MCLQ/MLIQ cell low nibble (`class = nibble & 3`, `FluidSpeed =
-    /// nibble & 0xc` — the nibble packs `class + 4·speed`). `None` for a nibble the table
-    /// doesn't cover (incl. the `0xf` dry sentinel).
+    /// The loop for an MCLQ or MLIQ cell's low nibble; `None` for one the table lacks, like `0xf`.
     pub fn kit_for_nibble(&self, nibble: u8) -> Option<u32> {
         let n = u32::from(nibble & 0xf);
         self.by_key.get(&(n & 3, n & 0xc)).copied()
@@ -68,9 +60,6 @@ pub fn load_water_sound_catalog(chain: &mut Chain) -> Result<WaterSoundCatalog>
 mod tests {
     use super::*;
 
-    /// The real 5875 table, end to end: every wet nibble resolves, and the mapping matches the
-    /// §5's byte-cited dispatch (river split by authored speed, ocean uniform, magma pool/flow).
-    /// Skips without client data.
     #[test]
     fn real_table_resolves_every_wet_nibble() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/spell_focus.rs b/crates/benilla-formats/src/spell_focus.rs
index cd57dac6..969d8eb2 100644
--- a/crates/benilla-formats/src/spell_focus.rs
+++ b/crates/benilla-formats/src/spell_focus.rs
@@ -1,11 +1,6 @@
-//! SpellFocusObject.dbc — the table naming the world object a spell must be cast NEAR (an Anvil, a
-//! Forge, a Cooking Fire): the crafting book's "Requires: …" line resolves a recipe's
-//! `Spell.dbc RequiresSpellFocus` id here (decision 0437). The proximity *check* is the server's
-//! (`Spell::CheckCast`'s focus search) — the client only names the requirement.
-//!
-//! Layout byte-checked on the raw 5875 file this session (a struct-unpack dump: 138 records × 10
-//! fields, record size 40): `ID@0` · the 8-locale `Name` block (enUS first ⇒ **Name = column 1**) ·
-//! its flags word (9). Anchor rows: 1 "Anvil" · 2 "Loom" · 3 "Forge" · 4 "Cooking Fire".
+//! `SpellFocusObject.dbc`: the object a spell must be cast near (Anvil, Forge, …), named by the
+//! crafting book's "Requires:" line from `Spell.dbc` `RequiresSpellFocus`. The server does the
+//! proximity check (`Spell::CheckCast`); the client only names it.
 
 use std::collections::HashMap;
 
@@ -19,14 +14,13 @@ const SPELL_FOCUS_OBJECT: &str = "DBFilesClient\\SpellFocusObject.dbc";
 const SPELL_FOCUS_FIELDS: usize = 10;
 const COL_NAME_ENUS: usize = 1;
 
-/// `SpellFocusObject.Id → Name` — the "Requires: Anvil" vocabulary.
+/// `SpellFocusObject` id → its enUS name.
 pub struct SpellFocusCatalog {
     names: HashMap<u32, String>,
 }
 
 impl SpellFocusCatalog {
-    /// The display name for a `RequiresSpellFocus` id, or `None` for 0/unknown (no requirement
-    /// line at all).
+    /// The name for a `RequiresSpellFocus` id; `None` for 0, which draws no requirement line.
     pub fn name(&self, focus_id: u32) -> Option<&str> {
         self.names.get(&focus_id).map(String::as_str)
     }
@@ -73,9 +67,6 @@ pub fn load_spell_focus_catalog(chain: &mut Chain) -> Result<SpellFocusCatalog>
 mod tests {
     use super::*;
 
-    /// The profession-focus rows on the real build-5875 file, byte-anchored (module doc's dump):
-    /// a column slip lands on another locale/flags column and fails loudly. Skips without client
-    /// data.
     #[test]
     fn real_spell_focus_names_the_profession_objects() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/spell_mechanic.rs b/crates/benilla-formats/src/spell_mechanic.rs
index aa474587..30f0f282 100644
--- a/crates/benilla-formats/src/spell_mechanic.rs
+++ b/crates/benilla-formats/src/spell_mechanic.rs
@@ -1,17 +1,6 @@
-//! SpellMechanic.dbc — the vocabulary that fills `SPELL_FAILED_PREVENTED_BY_MECHANIC`'s `%s`,
-//! turning "Can't do that while %s" into "Can't do that while stunned" (decision 1948).
-//!
-//! It is the crowd-control ladder's other half: the exemption scan (decision 1941) reports the
-//! blocking aura's mechanic as an **id**, and this names it. Without the table the arm's refusal
-//! displayed its template with the specifier unfilled, which is the loose end 1941 recorded.
-//!
-//! The reference reads the same store (`0xc0d7c4`) from `0x6e2190`, the `0x8d` argument arm
-//! (wow-re `cast-fail-strings.md` line 120).
-//!
-//! Layout byte-checked on the raw 5875 file (a struct-unpack dump: **27 records × 10 fields,
-//! record size 40**, string block 246) — the same shape as `SpellFocusObject.dbc`: `ID@0` · the
-//! 8-locale `Name` block (enUS first ⇒ **Name = column 1**) · its flags word (9). Anchor rows:
-//! 5 "fleeing" · 7 "rooted" · 12 "stunned" · 17 "polymorphed".
+//! `SpellMechanic.dbc`: the `%s` of `SPELL_FAILED_PREVENTED_BY_MECHANIC` ("Can't do that while
+//! %s"), naming the blocking aura's mechanic. The reference reads this table (`0xc0d7c4`) in
+//! `0x6e2190`, its `0x8d` argument arm.
 
 use std::collections::HashMap;
 
@@ -25,18 +14,13 @@ const SPELL_MECHANIC: &str = "DBFilesClient\\SpellMechanic.dbc";
 const SPELL_MECHANIC_FIELDS: usize = 10;
 const COL_NAME_ENUS: usize = 1;
 
-/// `SpellMechanic.Id → Name` — the "Can't do that while stunned" vocabulary.
-///
-/// The names are **lower-case and adjectival** in the shipped data ("stunned", "asleep",
-/// "polymorphed"), which is what makes them read as the tail of that sentence rather than as a
-/// title. Nothing here capitalises them; the reference does not either.
+/// Mechanic id → name, lower-case in the data ("stunned") and left so, as the reference does.
 pub struct SpellMechanicCatalog {
     names: HashMap<u32, String>,
 }
 
 impl SpellMechanicCatalog {
-    /// The display name for a mechanic id, or `None` for 0/unknown — which is exactly the case
-    /// the refusal treats as "no mechanic named", falling back to the arm's own reason.
+    /// The name for a mechanic id; `None` for 0, where the refusal falls back to its own reason.
     pub fn name(&self, mechanic_id: u32) -> Option<&str> {
         self.names.get(&mechanic_id).map(String::as_str)
     }
@@ -83,12 +67,7 @@ pub fn load_spell_mechanic_catalog(chain: &mut Chain) -> Result<SpellMechanicCat
 mod tests {
     use super::*;
 
-    /// The rows the crowd-control ladder actually names, on the real build-5875 file. A column
-    /// slip lands on another locale or the flags word and fails loudly. Skips without client data.
-    ///
-    /// The four ids here are the ones decision 1941's arms can report, cross-checked against the
-    /// `Spell.dbc` mechanic columns pinned in `spell_catalog`: Fear's `Mechanic` is 5, Frost Nova's
-    /// `EffectMechanic[1]` is 7, Polymorph's is 17.
+    /// Fear's `Mechanic` is 5, Frost Nova's `EffectMechanic[1]` 7, Polymorph's 17.
     #[test]
     fn real_spell_mechanic_names_the_crowd_control_rows() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/spell_visual/chain_effects.rs b/crates/benilla-formats/src/spell_visual/chain_effects.rs
index 288c7e5c..50b27e6c 100644
--- a/crates/benilla-formats/src/spell_visual/chain_effects.rs
+++ b/crates/benilla-formats/src/spell_visual/chain_effects.rs
@@ -1,110 +1,8 @@
-//! `SpellChainEffects.dbc` — the **beam/arc** half of the spell-visual family (decision 0955):
-//! Chain Lightning's lightning, Drain Life's rope of soul, Mind Flay's mana beam, C'Thun's eye
-//! beam, Chain Heal's arc. A whole rendering system that hangs off one `SpellVisualKit` column
-//! group we were already reading and one CharProc key we were throwing away.
-//!
-//! ## How a spell reaches a beam
-//!
-//! `Spell.dbc` → `SpellVisual` → the stage's `SpellVisualKit` → one of the kit's four **CharProc**
-//! slots whose type is [`char_proc_type::CHAIN_CHANNEL`](super::char_proc_type::CHAIN_CHANNEL) (0)
-//! or [`CHAIN_CAST`](super::char_proc_type::CHAIN_CAST) (12) → that slot's params → **this table**.
-//! There is no other path: `SpellChainEffects` has exactly one consumer in the whole binary
-//! (`0x6ecbd0 CreateChainVisual`), reached through one wrapper (`0x6ecb90`) from one call site
-//! (`0x60db6d`, inside the CharProc dispatcher `0x60d7c0`).
-//!
-//! The dispatcher's own translation table settles which keys get there. It is a two-level switch —
-//! a 16-byte type→case table at **`0x60dc20`** feeding a 9-entry address table at **`0x60dbfc`** —
-//! and reading it byte-for-byte gives, for CharProcType 0..15:
-//!
-//! ```text
-//! 0→case0  1→case1  2..5→default  6→case2  7→default  8→case3  9,10→default
-//! 11→case4  12→case0  13→case5  14→case6  15→case7
-//! cases: [0x60da79, 0x60d840, 0x60da55, 0x60d80a, 0x60db7e, 0x60d8df, 0x60d972, 0x60d9e8, 0x60dbdd]
-//! ```
-//!
-//! which reproduces the three keys already verified elsewhere (1 → `0x60d840` tint, 11 →
-//! `0x60db7e` anim-rate, 14 → `0x60d972` alpha — `crate::spell_visual::char_proc_type`) and shows
-//! **0 and 12 both routing to case 0, `0x60da79`** — the beam case, whose tail is the
-//! `CreateChainVisual` call. That is why [`super::char_proc_slot`] may not fold type `0` to "empty":
-//! type 0 is the channel beam, and folding it away silently discarded 34 of the 48 live beams in
-//! the shipped table.
-//!
-//! ## The params (`0x60db19`–`0x60db6d`)
-//!
-//! Three of the slot's four param columns are read, each through the client's **small-int decode**
-//! `bits(param + 512.0f) >> 14 & 0xff` — the same idiom already pinned at `0x5d55c0` for the
-//! dynobject shard index ([`super::char_proc_small_int`]):
-//!
-//! | column | decoded to |
-//! |---|---|
-//! | `CharParamZero` | the **`SpellChainEffects` id** — this table's key |
-//! | `CharParamOne`  | the **beam count**, clamped to `≤ 3` by `0x6ecbd0` ([`CHAIN_MAX_BEAMS`]) |
-//! | `CharParamTwo`  | a **boolean flag** (`setne`), stored at the beam node's `+0x48` |
-//!
-//! **The decode is corroborated by prediction, not just by reading:** run it over all 68 type-0/12
-//! slots in the shipped `SpellVisualKit.dbc` and every one of the 48 non-zero results lands on a
-//! real row of this 18-row table — no misses, no out-of-range — and each names the *right* texture:
-//! Drain Mana and Mind Flay → `ManaBeam`, Drain Soul → `Beam_Purple`, Drain Life and Health Funnel
-//! → `SoulBeam`, Chain Heal → `HealBeam`, Chain Lightning → `Lightning`, Shrink Ray →
-//! `ManaBurnBeam`, C'Thun's Eye Beam → `SoulBeam`. The other 20 decode to id `0`, which has no row
-//! — the client's own bounds check (`jl` / `cmp maxId` / null-row test at `0x6ecc0e`–`0x6ecc30`)
-//! no-ops them, so they are padding and [`ChainProc`] reports them as absent.
-//!
-//! The shipped split is a *data* convention, not a code fork: type 0 appears on **channel**-stage
-//! kits with the flag decoding to 1, type 12 on **cast**-stage kits with the flag decoding to 0.
-//! The dispatcher itself cannot tell them apart, so a consumer keys off [`ChainProc::flag`], never
-//! off the type constant's name.
-//!
-//! ## Layout — VERIFIED against build 5875
-//!
-//! **18 records × 8 fields × 32 B** (header dumped from the extracted file; wow-re
-//! `system/dbc/scratch/spellvisual-schema.md` records the same shape from the loader's own
-//! field-count assert, plus the client-DB globals `records 0xc0d848 / idIndex 0xc0d850 /
-//! maxId 0xc0d854`, loader `0x54e980`). Ids are `1..=13, 15, 17..=20` — note `14` and `16` are
-//! absent, so an id is a lookup, never an index.
-//!
-//! **The columns — VERIFIED** (wow-re `system/spell/scratch/chain-beam-law.md`, the §5 dispatched
-//! with 0955; 4 agents, every contested point re-read at the bytes). Two of the community names
-//! this module first carried were **wrong**, and both mattered:
-//!
-//! | field | name | meaning |
-//! |---|---|---|
-//! | 1 | `AvgSegLen` | segment length, with a floor: `n = trunc(len / field1 + 2.0)` segments, `n+1` points (`0x7af713`, the `2.0f` at `0x801628`) — so even a 1-yard beam gets 2 segments |
-//! | 2 | `Width` | **HALF**-width — the visible ribbon is `2 × field2` yards |
-//! | 3 | `NoiseScale` | jitter amplitude as a **fraction of beam length** (`len × field3`), **re-rolled every frame** (`0x7b0950` dirties the geometry per frame), with a `0.75/0.25` advection blend against the previous roll |
-//! | 4 | ~~`TexCoordScale`~~ **`ScrollPeriod`** | **not a scale at all** — the scroll **period in seconds**: `phase = fmod(phase + dt, field4)` (`0x7af9d7`), `u = -(phase / field4)` (`0x7b055f`). A **negative** value reverses the scroll direction, magnitude unchanged — which is why the four *drain* rows ship `-0.5`: the texture flows back toward the caster |
-//! | 5 | ~~`SegDuration`~~ **`BoltLife`** (ms) | how long ONE HOP burns — `Bolt[i].end = Bolt[i].start + field5` (`0x6ec9eb`) — and the whole object's expiry, `now + boltCount × field5` (`0x6ecd30`). Per **hop**, not per subdivision segment. The client also stores a seconds-scaled copy (`× 0.001f`, the constant at `0x801360`) which it then **never reads** |
-//! | 6 | ~~`SegDelay`~~ **`BoltStagger`** (ms) | the delay between HOPS lighting up — `Bolt[i].start = t0 + i × field6` (`0x6ec9da`), its one consumer. It never reaches the *renderer*, which is what makes it look dead from the geometry side; it is what makes a 3-hop Chain Lightning arc **outward** rather than appearing all at once |
-//! | 7 | `Texture` | the beam's texture |
-//!
-//! The beam is **never tinted**: its colour word is always `0xFFFFFFFF`. Render state, settled
-//! against wow-re's own verified `EGxRs` map: **additive `SRC_ALPHA/ONE`, two-sided, depth-write
-//! OFF, fog off, emissive white, alpha-test `GEQUAL 1/255`**.
-//!
-//! **Geometry:** a chain is one polyline of `count+1` **nodes** and `count` **hops** running
-//! **caster → t1 → t2 → t3**, never a fan and never one beam per target (the client's own `Bolt`
-//! records name `idxA = i`, `idxB = i+1`). Each hop is then subdivided on its own by field 1. The
-//! endpoints are **re-resolved from the live units every frame** (`0x6ec460`), so a beam tracks a
-//! moving caster and a moving target. The caster's end anchors at its `$CSL` attachment or,
-//! failing that, `0.75 × modelHeight × modelScale` (`0x6ec6f0`); every other endpoint anchors at
-//! an M2 attachment resolved from the spell's own `SpellVisual` field 9 — the **same
-//! dest-attachment ordinal the missile uses** ([`MISSILE_ATTACH_TABLE`]) — with attachment 34 as
-//! the fallback.
-//!
-//! **Lifetime** is the flag's, and only the flag's: a beam is dead when `flag == 0 && now >=
-//! expiry`. So a **cast** beam (flag 0) self-terminates after `hopCount × BoltLife`, and a
-//! **channel** beam (flag 1) never expires by time at all — it ends only when the owning kit node
-//! is swept (`LightningObject::Stop 0x6ece10`, one caller image-wide).
-//!
-//! **The strand count is not a variation knob.** All three strands are constructed from
-//! byte-identical arguments — no seed, no index, no stagger. They differ only in heap identity,
-//! and so in the draws each takes from the shared PRNG. (Construction VERIFIED; that this is what
-//! produces the braided look is INFERRED.)
-//!
-//! Id **15** is degenerate — width, noise, scroll period and both timings are all `0`, with only
-//! `AvgSegLen = 5.0` and a texture. No shipped kit reaches it. Read the table with
-//! `benilla-extract <Data> chaincensus`, which prints it alongside every kit that draws a beam;
-//! it is also what caught a hand-decode of `SegDelay` being wrong.
+//! `SpellChainEffects.dbc`: the beams of Chain Lightning, Drain Life, Mind Flay, Chain Heal. A kit
+//! reaches it only through a CharProc slot of type 0 or 12, both of which the dispatcher
+//! (`0x60d7c0`, table `0x60dc20`) routes to one case (`0x60da79`) and on to `CreateChainVisual`
+//! (`0x6ecbd0`). Ids skip 14 and 16, so an id is a lookup, never an index.
+//! `benilla-extract <Data> chaincensus` prints the table with every kit that draws a beam.
 
 use std::collections::HashMap;
 
@@ -117,60 +15,51 @@ use crate::Chain;
 const SPELL_CHAIN_EFFECTS: &str = "DBFilesClient\\SpellChainEffects.dbc";
 const SPELL_CHAIN_EFFECTS_FIELDS: usize = 8;
 
-/// The client's own clamp on a chain proc's beam count (`0x6ecbd0`: `cmp esi,0x3` → `jbe` →
-/// `mov [ebp+0x14],3`). Only one shipped kit asks for more than one beam — 6397 "Chain Burn",
-/// which asks for exactly 3.
+/// The client's clamp on a chain proc's beam count (`0x6ecbd0`); only kit 6397, Chain Burn, asks
+/// for more than one.
 pub const CHAIN_MAX_BEAMS: u32 = 3;
 
-/// One `SpellChainEffects.dbc` row — the shape and animation of one beam. Every column's meaning
-/// is VERIFIED (module docs); two of the community names were wrong and are not used here.
+/// One row: the shape and animation of one beam. Fields 4-6 are not what their community names
+/// (`TexCoordScale`, `SegDuration`, `SegDelay`) say.
 #[derive(Debug, Clone, PartialEq)]
 pub struct ChainEffect {
-    /// Field 1 — the target length of one segment. The subdivision has a floor of two:
-    /// `segments = trunc(length / avg_seg_len + 2.0)`, points = `segments + 1`.
+    /// Field 1: the target segment length; a hop gets `trunc(length / this + 2.0)` segments, so
+    /// never fewer than two (`0x7af713`).
     pub avg_seg_len: f32,
-    /// Field 2 — the beam's **half**-width; the drawn ribbon spans `2 × this` yards.
+    /// Field 2: the half-width; the ribbon spans twice this in yards.
     pub half_width: f32,
-    /// Field 3 — per-joint jitter amplitude as a **fraction of the beam's length**, re-rolled
-    /// **every frame** and blended `0.75` previous / `0.25` new. `0.001` on the beams that read as
-    /// ropes, `0.04`/`0.05` on the lightnings.
+    /// Field 3: the jitter amplitude as a fraction of the beam's length, re-rolled every frame
+    /// (`0x7b0950`) and blended 0.75 old to 0.25 new; 0.01 on most rows, 0.04 on Chain Lightning's.
     pub noise_scale: f32,
-    /// Field 4 — the texture **scroll period in seconds** (`u = -(phase / this)`, `phase`
-    /// advancing by `dt` modulo this). **Negative reverses the direction**, magnitude unchanged —
-    /// the four drain rows ship `-0.5`, flowing the texture back toward the caster.
+    /// Field 4: the texture's scroll period in seconds, `u = -(phase / this)` with `phase`
+    /// advancing by `dt` modulo this (`0x7af9d7`). A negative period reverses the scroll: four
+    /// rows, the drains among them, ship -0.5, flowing back toward the caster.
     pub scroll_period_s: f32,
-    /// Field 5 — milliseconds. How long **one hop** burns (`Bolt.end = Bolt.start + this`), and
-    /// through it the whole beam's expiry, `now + hops × this`. Binds **only a one-shot (cast)
-    /// beam** — a channel beam ignores it and lives until swept.
+    /// Field 5: how long one hop burns in ms (`0x6ec9eb`), and so the beam's expiry,
+    /// `now + hops × this` (`0x6ecd30`); a channel beam ignores it and lives until swept.
     pub bolt_life_ms: u32,
-    /// Field 6 — milliseconds. The **stagger between hops**: hop `i` lights at `t0 + i × this`
-    /// (`0x6ec9da`, its one consumer), so a 3-hop cast arcs outward instead of appearing whole.
-    /// `200` on most rows, `300` on id 1, `0` on the three rows no kit reaches. Irrelevant to a
-    /// single-hop beam, and to a channel beam (whose per-hop window is bypassed entirely).
+    /// Field 6: the stagger between hops in ms, hop `i` lighting at `t0 + i × this` (`0x6ec9da`),
+    /// so a 3-hop cast arcs outward; a channel beam bypasses it.
     pub bolt_stagger_ms: u32,
-    /// Field 7 — the beam's texture, as the DBC stores it (`Textures\SpellChainEffects\*.blp`).
+    /// Field 7: the texture path as stored (`Textures\SpellChainEffects\*.blp`).
     pub texture: String,
 }
 
-/// A kit's chain CharProc, decoded — what [`super::VisualKit::chain_proc`] yields.
+/// A kit's chain CharProc, its params read through [`super::char_proc_small_int`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ChainProc {
-    /// `CharParamZero` decoded — the [`ChainEffect`] id. Never `0`: an id that names no row is
-    /// the client's own no-op, and this type is only built for a slot that decodes to a real id.
+    /// `CharParamZero`, the [`ChainEffect`] id; never 0, as the client no-ops an id with no row
+    /// (`0x6ecc0e`).
     pub effect_id: u32,
-    /// `CharParamOne` decoded, clamped to [`CHAIN_MAX_BEAMS`] as `0x6ecbd0` clamps it. `0` is
-    /// possible on the shipped table and means the client draws nothing (`jbe` straight out).
+    /// `CharParamOne`, clamped to [`CHAIN_MAX_BEAMS`]; the client draws nothing for 0.
     pub beams: u32,
-    /// `CharParamTwo` decoded to a bool, exactly as the client's `setne` does. `true` on every
-    /// channel-stage kit, `false` on every cast-stage one — the only thing that actually
-    /// distinguishes the two chain proc types (module docs).
+    /// `CharParamTwo` as a bool (`setne`): set on channel-stage kits, clear on cast-stage ones, and
+    /// the only real difference between the two chain types.
     pub flag: bool,
-    /// The proc's type key as the table stores it — `0` or `12`. Kept for instruments and for
-    /// the record; behaviour must key off [`Self::flag`], since the dispatcher does not fork.
+    /// The stored type, 0 or 12; behaviour keys off [`Self::flag`], as the dispatcher never forks.
     pub ty: i32,
 }
 
-/// `SpellChainEffects.dbc` — 8 fields / 32-byte records in build 5875.
 fn chain_effects_schema() -> Schema {
     let mut s = Schema::new("SpellChainEffects");
     let mut add = |name: &str, ty| s.add_field(SchemaField::new(name.to_string(), ty));
@@ -186,9 +75,8 @@ fn chain_effects_schema() -> Schema {
     s
 }
 
-/// Read `SpellChainEffects.dbc` off the patch chain. A row with an empty texture string is kept —
-/// the constructor never reads the texture, so a textureless row is the renderer's problem, not
-/// the loader's, and dropping it here would hide a data fact.
+/// Read `SpellChainEffects.dbc`; a textureless row stays, as the client's constructor never reads
+/// the texture.
 pub(super) fn load(chain: &mut Chain) -> Result<HashMap<u32, ChainEffect>> {
     let bytes = chain
         .read_file(SPELL_CHAIN_EFFECTS)
diff --git a/crates/benilla-formats/src/spell_visual/mod.rs b/crates/benilla-formats/src/spell_visual/mod.rs
index 3ccf6e1b..85fff58d 100644
--- a/crates/benilla-formats/src/spell_visual/mod.rs
+++ b/crates/benilla-formats/src/spell_visual/mod.rs
@@ -1,89 +1,8 @@
-//! `SpellVisual.dbc` + `SpellVisualKit.dbc` + `SpellVisualEffectName.dbc` +
-//! `SpellChainEffects.dbc` — the per-lifecycle-stage kit chain a cast plays
-//! (decision 0099 phase 2's data plane; schemas pinned by decision 0107, the chain table by 0955).
-//!
-//! Layout — VERIFIED against build 5875 (WDBC header dump of the extracted files, 2026-07-04;
-//! wow-re `system/dbc/scratch/spellvisual-schema.md` @ commit `ff91e7eb`, corroborated by vmangos
-//! `DBCStructure.h:613-640` `SpellVisualEntry` and our own header bytes):
-//!
-//! - **SpellVisual**: 2165 records × 16 fields × 64 B, all-`u32` (a 1-byte empty string block).
-//!   Field 0 = id; **field 1 = precastKit · field 2 = castKit · field 3 = impactKit · field 4 =
-//!   stateKit · field 5 = channelKit** — each a `SpellVisualKit` id, `0` = no kit at that stage.
-//!   The missile block (decision 0099 phase 4, wow-re `spell-visual-lifecycle.md` §Q4 — every
-//!   consumption byte-cited in the client's missile spawn `0x60a3d0`): **field 7 = the missile's
-//!   `SpellVisualEffectName` id** (`<1` → the ammo/weapon model; unresolvable → the client's
-//!   literal `Spells\ErrorCube.mdx`), **field 9 = the destination-attachment ordinal** (an index
-//!   into [`MISSILE_ATTACH_TABLE`], the client's `0x860a18` — dumped in wow-re
-//!   `spell-visual-apply.md` §5), and **field 10 = the missile's in-flight LOOP sound**
-//!   ([`SoundEntries`] id — Fireball's `FireMissileLoop`, the thrown dagger's `WeaponLoop`; the
-//!   client's per-missile loop handle `CMissile+0x44`, wow-re `w2f1.md`). Field 6 (`hasMissile`)
-//!   is never read by the missile spawn (its gate is `Spell.dbc` Speed alone) — its ONE reader
-//!   is the GO dest one-shot's suppressor ([`VisualStages::missile_gate`], 0797); field 8
-//!   (`missilePathType`) is dead-by-absence; **fields 11/12/13 are the dest-anchored block**
-//!   ([`VisualStages::area_gate`]/[`VisualStages::area_effect`]/[`VisualStages::area_kit`] —
-//!   wow-re `dynobject-visual-machine.md`, 0797). Stage
-//!   semantics (decision 0107 verdict 2): the stage sets *lifetime policy* only —
-//!   every populated slot on a reached row fires, precast persisting (reaped spell-id-keyed)
-//!   while cast/impact self-terminate.
-//! - **SpellVisualKit**: 1772 records × 35 fields × 140 B, all-`u32`. Field 0 = id; **field 2 =
-//!   the `AnimationData.dbc` animation id** (fed to the same `PlayAnimation` one-shot/overlay
-//!   route as melee swings — decision 0107 verdict 3); **field 13 = a `SoundEntries.dbc` id**;
-//!   **fields 3–11 are the nine `SpellVisualEffectName` emitter slots** (attach-point VFX —
-//!   decision 0099 phase 3, read here since that phase). Each slot's attach tag is a compile-time
-//!   immediate in the client's slot loop (`0x60edf0`, byte-cited push sites — wow-re
-//!   `spell-visual-apply.md` §1.3) and a **direct M2 `AttachmentID`**: in kit-field order,
-//!   [`KIT_SLOT_TAGS`]. **Field 12 (`kit+0x30`) is a TENTH effect slot** — read here as
-//!   [`VisualKit::world_effect`] (decision 0848): wow-re pinned its consumer as "the missile
-//!   slot" (`0x60edf0` plays it inline via `0x61fcf0`, a `CEffect`-family node stamped with a
-//!   missile marker — `spell-visual-apply.md` §1.4), but the shipped table's population is
-//!   **body/ground state models**, never projectiles: the aura-state family the nine slots miss
-//!   (Frost Nova's kit 285 → `Frost_Nova_state.mdx`, Net's 744 → `Net_State.mdx`, Entangling
-//!   Roots' 66, Web's 746) plus caster-feet rings on cast/impact kits (Thunderclap's 349,
-//!   Flamestrike's 420, Vanish's 389). Same `CEffect` lifecycle as the nine (spell-id-tagged on
-//!   the unit's `+0xb4` list, the stage sets lifetime — §1.5). Placement is byte-pinned (wow-re
-//!   `kit30-effect-slot.md`, folded back 0850): no bone — a one-time **world plant** at the
-//!   owner's position/facing/scale, [`WORLD_EFFECT_TAG`]. **Field 14 is the kit's CAMERA SHAKE**
-//!   ([`VisualKit::shake`]) — a `SpellEffectCameraShakes.dbc` **group** id, not the "visual-group
-//!   fallback" earlier notes called it: 58 shipped kits carry one and all 58 values land on that
-//!   table's nine sparse ids, `Spell.dbc` 12816 is literally named *"Idom Rool Camera Shake"*, and
-//!   the set reads as nothing else (kit 356 = War Stomp/Thunder Clap/Kodo Stomp, kit 348 = the
-//!   Knockdown/Slam/Charge impacts, kit 138 = every summon). **Fields 15–34 are the four
-//!   `CharProc` slots** — the
-//!   *character* half of a kit (the body's own alpha/tint, as opposed to the attach-point emitters):
-//!   five parallel 4-element arrays, `CharProcType[4]` @+0x3c then `CharParamZero/One/Two/Three[4]`
-//!   @+0x4c/+0x5c/+0x6c/+0x7c (wow-re `spellvisual-schema.md`, byte-pinned: all 20 consumed by the
-//!   dispatcher `0x60d7c0`, which `lea edi,[kit+0x6c]` walks four times reading `[edi-0x30]` as the
-//!   type key). Read here as [`VisualKit::char_procs`]; the type semantics are
-//!   [`char_proc_type`]'s.
-//! - **SpellVisualEffectName**: 5 fields × 20 B. Field 0 = id; field 1 = a name string — a debug
-//!   label, and the lookup key for the client's boot-time HARDCODED-effect matcher (`0x61f5b0`
-//!   over a 14-string table: loot art, footsteps, breath, level-up…; wow-re
-//!   `loot-corpse-effect.md` + `levelup-ding.md`) — the `"HARDCODED *"` rows load into
-//!   [`SpellVisualCatalog::hardcoded_effect`]'s name→path map (two consumers today: the corpse
-//!   sparkle and the level-up ding); **field 2 = the effect model's `.mdx` path** (the
-//!   column every consumer reads — fields 3/4 are dead-by-absence, wow-re
-//!   `spellvisual-schema.md`; the emitter *scale* comes from kit CharProc params × the quality
-//!   tier, never from this table).
-//! - **SpellChainEffects**: 18 records × 8 fields × 32 B — the **beam/arc** geometry a kit's chain
-//!   `CharProc` draws (Chain Lightning's lightning, Drain Life's rope, C'Thun's eye beam). Its own
-//!   module: [`chain_effects`], decision 0955.
-//!
-//! **The none-sentinel, found empirically here (not pinned in the wow-re note):** on the real
-//! table, "no value" for both field 2 (anim) and field 13 (sound) is written as **either `0` or
-//! `0xFFFFFFFF`**, not consistently one or the other. Scanning all 1772 kits: 41 carry anim `0`,
-//! 875 carry anim `0xFFFFFFFF`, 856 carry a real id (max 203, inside `AnimationData.dbc`'s 208
-//! rows). Restricting to the 1433 kits actually reachable from a live `spell_template` visual
-//! chain doesn't change the picture (692 are `-1` vs 26 `0` vs 715 real) — the `-1` form is the
-//! majority for **impact**-stage kits specifically (966/1200: most magic impacts carry no body
-//! reaction) while **cast**-stage kits are majority real (1168/1347: most casts do animate).
-//! `sound` (field 13) shows the same dual encoding on a handful of rows (5 kits carry
-//! `0xFFFFFFFF` alongside 647 carrying plain `0`). [`VisualKit::anim_id`]/[`VisualKit::sound`]
-//! fold both forms to `None` so no consumer ever sees the raw sentinels.
-//!
-//! **Verified chain (Fireball, spell 133 → visual 67):** precast 30 / cast 38 / impact 286 /
-//! state 0 / channel 0; kit 38 (cast) → anim 53 (`AnimationData` "SpellCastDirected") / sound
-//! 1484; kit 286 (impact) → anim 9 (`AnimationData` "CombatWound" — a hit-reaction anim on the
-//! target, corroborating decision 0107's wound-flinch ids 8–10) / sound 1507.
+//! `SpellVisual.dbc`, `SpellVisualKit.dbc`, `SpellVisualEffectName.dbc` and
+//! `SpellChainEffects.dbc`: what a cast shows at each stage (the client's loaders `0x5508e0`,
+//! `0x550690` and `0x550460`; vmangos `SpellVisualEntry`, `DBCStructure.h:613-640`). A stage sets
+//! lifetime only: every populated slot of a reached kit fires, precast persists until reaped by
+//! spell id, and cast and impact end on their own.
 
 use std::collections::HashMap;
 
@@ -104,81 +23,47 @@ const SPELL_VISUAL_EFFECT_NAME: &str = "DBFilesClient\\SpellVisualEffectName.dbc
 const SPELL_VISUAL_FIELDS: usize = 16;
 const SPELL_VISUAL_KIT_FIELDS: usize = 35;
 
-/// The nine kit emitter slots' attach tags, **in kit-field order** (fields 3–11 ↔ this array's
-/// indices 0–8). Byte-pinned compile-time immediates in the client's slot loop (wow-re
-/// `spell-visual-apply.md` §1.3), each a **direct M2 `AttachmentID`**: Head(0x14), Chest(0x22),
-/// Base(0x13), LeftHand(0x15), RightHand(0x16), Breath(0x11), Special1–3(0x17–0x19).
+/// Each emitter slot's M2 `AttachmentID`, kit fields 3-11 in order, as the client's slot loop
+/// (`0x60edf0`) pushes them: head, chest, base, left hand, right hand, breath, special 1-3.
 pub const KIT_SLOT_TAGS: [u16; 9] = [0x14, 0x22, 0x13, 0x15, 0x16, 0x11, 0x17, 0x18, 0x19];
 
-/// The sentinel tag [`VisualKit::effects`] yields for [`VisualKit::world_effect`] (kit field
-/// 12) — the client's own **−1**: `0x61fcf0` passes no attach tag at all (`0x61fd23: push -1`,
-/// `node+0x24` stays the ctor's −1), which in the placement walk `0x620be0` skips the entire
-/// bone pipeline and instead triggers a **one-time world plant** (`0x620c86`): transform =
-/// `translate(owner position) × yaw(owner facing) × scale(owner scale)`, baked at spawn — the
-/// model does NOT ride a bone and does not turn with the unit afterwards (wow-re
-/// `kit30-effect-slot.md`, §5 byte-arbitrated; decision 0848). Consumers key on this tag to
-/// plant in world space rather than attach.
+/// The tag for kit field 12, the client's -1: `0x61fcf0` passes no attach tag (`0x61fd23`), so the
+/// placement walk (`0x620be0`) plants the model once in world space at the owner's position, facing
+/// and scale (`0x620c86`); it rides no bone and does not turn with the unit.
 pub const WORLD_EFFECT_TAG: u16 = u16::MAX;
 
-/// The missile **destination-attachment** ordinal table — the client's `0x860a18`, dumped
-/// byte-for-byte (wow-re `spell-visual-apply.md` §5, 11 live entries): [`KIT_SLOT_TAGS`] in
-/// kit-field order plus `0xf`/`0x10` at ordinals 9/10. `SpellVisual` field 9 indexes here to the
-/// M2 attach tag the missile homes to on a live target ([`VisualStages::missile_attach`]).
+/// The client's missile destination attachments (`0x860a18`): `SpellVisual` field 9 indexes it
+/// for the M2 attachment the missile homes to on a live target.
 pub const MISSILE_ATTACH_TABLE: [u16; 11] = [
     0x14, 0x22, 0x13, 0x15, 0x16, 0x11, 0x17, 0x18, 0x19, 0xf, 0x10,
 ];
 
-/// The DBC's alternate "no value" encoding for a foreign-key-ish column (module docs) — folded to
-/// `None` alongside plain `0`.
+/// The data writes "no value" in an id column as 0 or as this, inconsistently; both read `None`.
 const NONE_SENTINEL: u32 = u32::MAX;
 
-/// The four parallel `CharProc` slots a `SpellVisualKit` row carries (module docs; the client's
-/// dispatcher `0x60d7c0` walks exactly four).
+/// `CharProc` slots per kit; the dispatcher (`0x60d7c0`) walks exactly four.
 pub const KIT_CHAR_PROCS: usize = 4;
 
-/// One of a kit's four `CharProc` slots: a **type key + its four float params**, the character-half
-/// of a kit (the body's own render properties, not an attach-point emitter). The client's dispatcher
-/// `0x60d7c0` switches on [`Self::ty`] through a byte translation table (`0x60dc20`) into a 9-case
-/// jump table (`0x60dbfc`); each case reads whichever params it wants — the alpha and tint procs
-/// both read `params[0]` (wow-re `ghost-death-visuals.md` §2.3).
+/// One `CharProc` slot, a type key and four float params. The dispatcher (`0x60d7c0`) switches on
+/// the type through a byte table (`0x60dc20`) into nine cases (`0x60dbfc`), each reading the params
+/// it wants.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct CharProc {
-    /// `CharProcType[i]` — the dispatch key ([`char_proc_type`] names the ones we model). Never a
-    /// none-sentinel: an empty slot is `None` at the [`VisualKit::char_procs`] level.
+    /// `CharProcType[i]`; never -1, as an empty slot is `None` in the kit.
     pub ty: i32,
-    /// `CharParamZero/One/Two/Three[i]`, in that order — float columns (the client loads them with
-    /// `fld` and rounds where it wants an integer, as the tint proc does with its packed RGB).
+    /// `CharParamZero..Three[i]`: floats the client loads with `fld`, rounding for an integer.
     pub params: [f32; 4],
 }
 
 impl CharProc {
-    /// Param `i` through the client's **small-int decode** — see [`char_proc_small_int`]. The
-    /// procs that want an integer out of a float column all use this one idiom.
     pub fn small_int(&self, i: usize) -> u32 {
         char_proc_small_int(self.params[i])
     }
 
-    /// This slot decoded as the **weapon swing trail** proc, or `None` when it is not one.
-    ///
-    /// The dispatcher's type-8 arm (`0x60d80a`–`0x60d83b`) is three `_ftol` calls and two stores,
-    /// and it is the one proc that uses **plain truncation** rather than
-    /// [`char_proc_small_int`] — so this decode must not borrow that idiom:
-    ///
-    /// ```text
-    /// 60d80a  fld [edi-0x20] ; call 0x40a2b0    ; ftol(CharParamZero)
-    /// 60d812  fld [edi+0x10] ; call 0x40a2b0    ; ftol(CharParamThree)
-    /// 60d823  shl eax,0x18 ; or ecx,eax
-    /// 60d828  mov [esi+0xd1c],ecx               ; unit+0xd1c = zero | (three << 24)
-    /// 60d82e  fld [edi]      ; call 0x40a2b0    ; ftol(CharParamTwo)
-    /// 60d835  mov [esi+0xd20],eax               ; unit+0xd20 = two
-    /// ```
-    ///
-    /// `CharParamOne` is **not read by this arm** — stated because every shipped type-8 row
-    /// carries `20.0` there and a reader will look for its use (wow-re `charproc8-weapon-trail.md`
-    /// §1).
-    ///
-    /// `None` for a zero duration: `0x5fe494 cmp eax,edi` / `je 0x5fe4b7` is the reference's own
-    /// test, and a zero-duration arm fires nothing.
+    /// This slot as a weapon swing trail. The type-8 arm (`0x60d80a`) truncates with `_ftol`, not
+    /// the small-int decode: `unit+0xd1c = zero | three << 24`, `unit+0xd20 = two`. `CharParamOne`
+    /// is not read; it holds 20.0 on 22 of the 34 trail kits and 0 to 25 on the rest. A zero
+    /// duration fires nothing (`0x5fe494`), so it reads as `None`.
     pub fn as_weapon_trail(&self) -> Option<TrailProc> {
         if self.ty != char_proc_type::WEAPON_TRAIL {
             return None;
@@ -191,10 +76,8 @@ impl CharProc {
         })
     }
 
-    /// This slot decoded as a chain/beam proc, or `None` when it is not one — either the type key
-    /// is not a chain key, or it is but `CharParamZero` decodes to `0`, which names no
-    /// `SpellChainEffects` row and is how the shipped table writes an unused slot (`chain`'s
-    /// module docs; the client's own null-row test at `0x6ecc2e` is the same no-op).
+    /// This slot as a beam; `None` too when `CharParamZero` decodes to 0, which names no row and is
+    /// how the data writes an unused slot (the client's null-row test, `0x6ecc2e`).
     pub fn as_chain(&self) -> Option<ChainProc> {
         if !char_proc_type::is_chain(self.ty) {
             return None;
@@ -209,36 +92,27 @@ impl CharProc {
     }
 }
 
-/// The client's decode of a small integer stored in a `CharProc` **float** param column:
-/// `bits(param + 512.0f) >> 14 & 0xff`. Adding 512 forces the exponent, parking the integer part
-/// in known mantissa bits; the shift and mask lift it back out. Byte-pinned at `0x5d55c0` (the
-/// dynobject shard index, wow-re `dynobject-visual-machine.md`) and used identically by the chain
-/// proc for all three of its integer params (`0x60db19`–`0x60db6d`, decision 0955).
-///
-/// The client applies **no bounds check** of its own — `mov cl,al` takes the byte and indexes with
-/// it — so callers clamp or bounds-test as the consumer requires.
+/// The client's read of a small integer from a `CharProc` float param:
+/// `bits(param + 512.0) >> 14 & 0xff`, where adding 512 fixes the exponent so the integer sits in
+/// known mantissa bits. Used for the dynobject shard index (`0x5d55c0`) and the chain proc's params
+/// (`0x60db19`); the client does no bounds check, so callers must.
 pub fn char_proc_small_int(param: f32) -> u32 {
     (param + 512.0).to_bits() >> 14 & 0xff
 }
 
-/// A [`char_proc_type::WEAPON_TRAIL`] slot decoded — the two words the dispatcher latches onto the
-/// unit (`unit+0xd1c` / `unit+0xd20`) and the trail object copies into its `SWING` record
-/// (`+0x608` / `+0x60c`).
+/// A decoded weapon trail: the two words latched on the unit (`unit+0xd1c`, `unit+0xd20`) and
+/// copied into the trail's `SWING` record (`+0x608`, `+0x60c`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct TrailProc {
-    /// `ftol(CharParamZero) | (ftol(CharParamThree) << 24)` — a packed **`0xAARRGGBB`**, kept as
-    /// the one dword the reference actually stores. Every shipped `CharParamZero` is a
-    /// `0x00RRGGBB` under `2^24`, so the OR never collides; read the channels through [`Self::rgb`]
-    /// and [`Self::alpha`] rather than re-deriving the shifts.
+    /// `0xAARRGGBB`, the dword the reference stores; every shipped `CharParamZero` is below 2^24,
+    /// so the OR never collides.
     pub packed: u32,
-    /// `ftol(CharParamTwo)` — how long the trail keeps **appending**, in milliseconds. Never `0`
-    /// (that is the reference's own no-fire test, so it decodes to `None`). 600 on the ordinary
-    /// melee kits, 1000 on Charge, **10000** on Whirlwind's whole spin.
+    /// How long the trail keeps appending, in ms: 600 on ordinary melee kits, 1000 on Charge,
+    /// 10000 on Whirlwind.
     pub duration_ms: u32,
 }
 
 impl TrailProc {
-    /// The trail's colour, `[R, G, B]` — kit 324's `0xf82929` is `[248, 41, 41]`.
     pub fn rgb(&self) -> [u8; 3] {
         [
             (self.packed >> 16) as u8,
@@ -247,83 +121,55 @@ impl TrailProc {
         ]
     }
 
-    /// The trail's starting alpha, `0..=255`. `100` on every shipped row (≈ 39 %) — and it is a
-    /// *clock* as much as an opacity: the fade rate, the retained segment count and the
-    /// termination test are all `alpha`-derived (wow-re `charproc8-weapon-trail.md` §8).
+    /// The starting alpha, 100 on 19 of the 34 trail kits; the fade rate, the segment count and
+    /// the end test all derive from it (`0x6c6560`).
     pub fn alpha(&self) -> u8 {
         (self.packed >> 24) as u8
     }
 }
 
-/// The `CharProc` type keys benilla models, by name. The full key space is the dispatcher's 9 cases
-/// (`0x60d7c0`); these are the ones a live 5875 **state** kit uses — every other key is either
-/// cast-stage-only or unused by the shipped table (see `charprocs` in `benilla-extract`).
+/// The `CharProc` type keys benilla models, out of the dispatcher's nine cases (`0x60d7c0`).
 pub mod char_proc_type {
-    /// **Body TINT** (`0x60d840`): `round(params[0])` is a packed `0x00RRGGBB`, OR'd with
-    /// `0xff000000` into the tint node (`node+0x7c`), list `unit+0xce0`. Per-frame the head node's
-    /// RGB goes `×1/255` into `model+0x184/188/18c` (the ghost's pale blue-white `0xFF8CB9FD`).
+    /// Body tint (`0x60d840`): `round(params[0])` is `0x00RRGGBB`, stored with alpha `0xff` in a
+    /// node on `unit+0xce0`; each frame the head node's RGB / 255 goes to `model+0x184..0x18c`.
     pub const TINT: i32 = 1;
-    /// **Body TRANSLUCENCY** (`0x60d972`): `params[0]` is this aura's alpha factor, stored in a
-    /// spell-id-keyed node (`node+0x78`) on the unit's list `unit+0xb50`. The unit's effective alpha
-    /// is `baseAlpha × Π(node alphas)` (`0x60d180`), ramped to over 1000 ms by
-    /// `StartAlphaFade 0x614f80`. Stealth's 0.3 and the ghost aura's 0.5 are both this proc.
+    /// Body translucency (`0x60d972`): `params[0]` is the aura's alpha factor, in a spell-keyed
+    /// node linked at the head of `unit+0xb50`. The unit's alpha is `baseAlpha` times the head
+    /// node's factor alone, never a product over the list (`0x60d180`), ramped over 1000 ms
+    /// (`0x614f80`). Stealth's 0.3 and the ghost's 0.5 are this proc.
     pub const ALPHA: i32 = 14;
-    /// **Body ANIMATION RATE** (`0x60db7e`) — the freeze. `params[0]` is a playback *rate*, written
-    /// straight onto the unit's model clocks by `SetBoneAnimSpeed 0x712910`: the mount's bone 0
-    /// (`[unit+0xdc]`, `-1`), the body's **key-bone 4** (SpineLow — the upper-body split track that
-    /// carries cast/emote one-shots) when the model has one (`0x711d20(4)` gates it), and the body's
-    /// bone 0 (`-1`). The previous rates are saved in the node (`+0x60`/`+0x64`/`+0x68`) and written
-    /// back when it expires with the aura (`0x6203e0`, gated on the node's own `+0x2c & 0x4`).
-    ///
-    /// The rate is the per-bone `+0xb0` the animation clock multiplies its window by
-    /// (`timebase.md` §2: `t = trunc(f32(window) × rate) + bias`), and **arming an animation never
-    /// touches it** — op4 `0x7121a0`'s success leg writes `+0xa4`/cursors and leaves `+0xb0` alone
-    /// (only its disarm leg and `0x712910` write it). So the value persists across every re-arm for
-    /// the aura's whole life, and `0x712910` re-bases `bias` so the *current frame* is preserved
-    /// across the rate change: **rate 0 holds the pose exactly where it was.**
-    ///
-    /// 15 kits carry it; 14 ship `params[0] = 0` — Ice Block (kit 3709), Freeze, Freeze Solid,
-    /// Flash Freeze, Petrify, Encage, Stilled. Kit 1744 (Stoned / Petrification / Thadius Spawn)
-    /// ships `8947848.0` = `0x888888`, which reads like a packed grey that landed in the rate
-    /// column; it is passed through, not special-cased.
+    /// Body animation rate (`0x60db7e`), the freeze: `SetBoneAnimSpeed` (`0x712910`) sets
+    /// `params[0]` as the rate of the mount's bone 0, the body's key bone 4 when it has one
+    /// (`0x711d20`) and the body's bone 0, re-basing so the current frame holds. Arming an
+    /// animation never resets it (`0x7121a0`), so rate 0 holds the pose for the aura's life; the
+    /// old rates return when the node expires (`0x6203e0`). Of the 15 kits a live spell reaches,
+    /// 14 ship 0 (Ice Block, Freeze, Petrify, …) and kit 1744 ships 8947848.0 (`0x888888`),
+    /// passed through as is.
     pub const ANIM_RATE: i32 = 11;
 
-    /// **Weapon SWING TRAIL** (`0x60d80a`) — the ribbon a melee ability smears between its
-    /// weapon model's `$WTB` and `$WTT` event markers. The arm is a **latch on the unit**, not a
-    /// same-call effect: the proc writes `unit+0xd1c` (the packed colour) and `unit+0xd20` (the
-    /// duration in ms), and the unit's **next** `PlayAnimation` (`0x5fe2f0`, the field's sole
-    /// reader at `0x5fe48e`) hands both to each of its two weapon-hand trail objects and clears
-    /// the duration — so it fires exactly once per arm. See [`CharProc::as_weapon_trail`] and
-    /// wow-re `charproc8-weapon-trail.md`.
-    ///
-    /// 34 of the 1772 kits carry it and for **18 of them it is the entire visual** — kit 324
-    /// (Heroic Strike / Overpower / Mortal Strike / Bloodthirst / Rend, 218 spells), 3050
-    /// (Hamstring), 557 (Sunder Armor) name no emitter slot at all, so a client without this proc
-    /// renders nothing for them beyond the swing animation.
+    /// Weapon swing trail (`0x60d80a`), the ribbon between a weapon's `$WTB` and `$WTT` markers.
+    /// It latches on the unit: the next `PlayAnimation` (`0x5fe2f0`, reading at `0x5fe48e`) hands
+    /// it to both weapon-hand trails and clears it, so it fires once per arm. For 21 of the 34
+    /// kits carrying it (Heroic Strike's 324, Hamstring's 3050, Sunder's 557) it is the whole
+    /// visual: they fill no effect slot.
     pub const WEAPON_TRAIL: i32 = 8;
 
-    /// **Chain / beam visual**, the key the shipped table uses on **channel**-stage kits — Drain
-    /// Life's rope, Mind Flay's mana beam, Health Funnel, C'Thun's eye beam. Both this and
-    /// [`CHAIN_CAST`] land on the same dispatcher case (`0x60da79`); the name records the data's
-    /// convention, and behaviour keys off [`ChainProc::flag`](crate::ChainProc::flag). See the
-    /// `chain_effects` module docs for the whole mechanism (decision 0955).
+    /// A beam, as the data keys it on channel-stage kits (Drain Life, Mind Flay). It reaches the
+    /// same dispatcher case as [`CHAIN_CAST`] (`0x60da79`); behaviour keys off
+    /// [`ChainProc::flag`](crate::ChainProc::flag).
     pub const CHAIN_CHANNEL: i32 = 0;
-    /// **Chain / beam visual**, the key the shipped table uses on **cast**-stage kits — Chain
-    /// Lightning, Chain Heal, Chain Burn, Shrink Ray, the elemental Weakness debuffs. See
-    /// [`CHAIN_CHANNEL`].
+    /// A beam, as the data keys it on cast-stage kits (Chain Lightning, Chain Heal).
     pub const CHAIN_CAST: i32 = 12;
 
-    /// Whether this type key reaches the beam case. **Both** chain keys do, and the dispatcher's
-    /// translation table (`0x60dc20`) draws no distinction between them — so every consumer asks
-    /// this rather than comparing against one constant.
+    /// Whether this type reaches the beam case. Both chain keys do (`0x60dc20`), so ask this rather
+    /// than compare with one constant.
     pub fn is_chain(ty: i32) -> bool {
         ty == CHAIN_CHANNEL || ty == CHAIN_CAST
     }
 }
 
-/// One `SpellVisual.dbc` row: the five lifecycle-stage `SpellVisualKit` ids a cast may fire
-/// through (`0` = no kit at that stage, this crate's usual absent-FK convention) + the missile
-/// block's live columns (model, dest-attach, flight sound — module docs; phase 4).
+/// One `SpellVisual.dbc` row: the kit ids for the five stages (fields 1-5, 0 for none), then the
+/// missile and dest-anchored columns.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct VisualStages {
     pub precast: u32,
@@ -331,77 +177,38 @@ pub struct VisualStages {
     pub impact: u32,
     pub state: u32,
     pub channel: u32,
-    /// Field 7: the projectile's `SpellVisualEffectName` id (`0` here covers the client's `<1`
-    /// ammo-fallback gate — the raw column is never negative on the real table). The missile
-    /// *exists* whenever `Spell.dbc` Speed > 0, model or not.
+    /// Field 7: the missile's `SpellVisualEffectName` id; 0 flies the ammo or weapon model, and an
+    /// id with no row the client's `Spells\ErrorCube.mdx` (`0x60a3d0`). A missile exists whenever
+    /// `Spell.dbc` Speed > 0, whatever this holds.
     pub missile_model: u32,
-    /// Field 9: the destination-attachment ordinal — index [`MISSILE_ATTACH_TABLE`] for the M2
-    /// attach tag the missile homes to on a live target.
+    /// Field 9: the index into [`MISSILE_ATTACH_TABLE`].
     pub missile_attach: u32,
-    /// Field 10: the `SoundEntries.dbc` id the missile sounds while it travels — a LOOPING whoosh
-    /// on the thrown/ranged projectiles (the thrown dagger's `WeaponLoop.wav`, id 3318), the
-    /// client's per-missile loop handle (`CMissile+0x44`, wow-re `w2f1.md`; its volume is proximity
-    /// -shaped by `0x61d790`). `None` = the row names no flight sound. Rung by
-    /// `crate::entities::missile`, stopped when the projectile arrives.
+    /// Field 10: the `SoundEntries.dbc` loop the missile plays in flight (`CMissile+0x44`, its
+    /// volume shaped by distance at `0x61d790`), stopped when it arrives.
     pub missile_sound: Option<u32>,
-    /// Field 14: the `SoundEntries.dbc` id the `$TRD` anim event rings at the work/craft strike
-    /// keyframe — the client's `$TRD` handler `0x62faa0` resolves the in-flight spell's visual to
-    /// this 16-dword row and plays its dword 14 (`[row+0x38]`, wow-re
-    /// `sound/scratch/gather-sound-anim-events.md`; decision 0562). Mining's visual 93 carries
-    /// 1143 "Mining Impact" (the pick clang), Herb's 91 carries 1142, the smithing crafts' 395
-    /// carries 1143 (the hammer). `None` = no strike sound.
+    /// Field 14: the `SoundEntries.dbc` id the `$TRD` anim event plays at a craft's strike frame
+    /// (`0x62faa0`), such as mining's pick clang, sound 1143.
     pub strike_sound: Option<u32>,
-    /// Field 6 (`+0x18`): the missile gate the dest one-shot checks — `SMSG_SPELL_GO` spawns a
-    /// CEffect at the packet's DEST point only when this is **0** and [`Self::area_effect`] is
-    /// set (the client's `0x6e8088`–`0x6e8143`; wow-re `spell-go-dest-effect.md`). Nonzero =
-    /// the missile owns the arrival, no dest one-shot.
+    /// Field 6: `SMSG_SPELL_GO` spawns the dest one-shot at the packet's dest only when this is 0
+    /// and [`Self::area_effect`] is set (`0x6e8088`); the missile spawn ignores it.
     pub missile_gate: u32,
-    /// Field 11 (`+0x2c`): the gate on a DynamicObject's **own** `.mdx` (visual A) — the model
-    /// resolve at `0x5d57c0` requires this ≠ 0 before reading [`Self::area_effect`] (wow-re
-    /// `dynobject-visual-machine.md`).
+    /// Field 11: a DynamicObject shows its own model only when this is nonzero (`0x5d57c0`).
     pub area_gate: u32,
-    /// Field 12 (`+0x30`): the `SpellVisualEffectName` id of the **dest-anchored model** — a
-    /// DynamicObject's own `.mdx` (visual A, gated by [`Self::area_gate`]) and the GO dest
-    /// one-shot's model (gated by [`Self::missile_gate`] == 0). NOT the kit table.
+    /// Field 12: a `SpellVisualEffectName` id, not a kit: a DynamicObject's own model and the dest
+    /// one-shot's.
     pub area_effect: u32,
-    /// Field 13 (`+0x34`): the `SpellVisualKit` id of the **area kit** — a DynamicObject's
-    /// emitter chain (`0x5d55c0`: CharProcType scan for 9 → the hardcoded shard-model table)
-    /// and its looping area sound (the kit's own field-13 SoundEntries). `0` = none.
+    /// Field 13: a DynamicObject's kit, for its emitters (`0x5d55c0` scans it for CharProc type 9)
+    /// and its looping sound.
     pub area_kit: u32,
 }
 
 impl VisualStages {
-    /// The client's **ranged weapon-visual merge** — a per-FIELD zero-fill, not a per-row
-    /// fallback (`0x60d450`, byte-read end to end for decision 0986; this SUPERSEDES 0370's
-    /// row-level reading, whose disassembly stopped at the null-own-visual arm).
-    ///
-    /// The resolver reaches the fill from **both** arms, and they converge on one block:
-    ///
-    /// ```text
-    /// 60d4b4  test esi,esi ; jne 0x60d555   ; esi = the spell's OWN SpellVisual row
-    /// 60d4bc  xor eax,eax                   ; -- null-own arm: zero outKit ...
-    /// 60d4c6  rep stosd                     ;    ... then fall through into the fill
-    /// 60d555  rep movsd                     ; -- own arm: copy the OWN row into outKit ...
-    /// 60d561  jmp 0x60d4d2                  ;    ... and jump INTO the same fill
-    /// 60d4d2  test ebx,ebx ; je 0x60d54c    ; ebx = the WEAPON's SpellVisual row (0 if none)
-    /// 60d4d6..60d54c                        ; per field: `if out.F == 0 { out.F = weapon.F }`
-    /// ```
-    ///
-    /// So a RANGED-attribute spell (`Attributes & 0x2`) that **has** its own visual still borrows
-    /// the equipped ranged weapon's row for every slot its own row leaves at zero. That is how a
-    /// hunter shot animates at all: Serpent Sting (visual 3179), Multi-Shot (567), Arcane Shot
-    /// (3299), Aimed/Concussive (3180), Viper/Scorpid Sting (3181/3219) and Volley (3300) every
-    /// one carry `precast = cast = 0` beside a populated impact + missile block, and take
-    /// **LoadBow (kit 7) → AttackBow (kit 164)** off the bow's `ItemDisplayInfo` col-10 visual 5
-    /// (thrown → 98, gun → 224). Read as a row-level fallback they got no caster fire clip at all.
-    ///
-    /// The merged set is exactly the client's eight sites. The two it pointedly does NOT touch are
-    /// [`Self::state`] and [`Self::channel`] (`+0x10`/`+0x14`), nor the dest-anchored
-    /// `+0x2c/+0x30/+0x34` block. Field 8 (`missilePathType`, `+0x20`) is merged there too; it is
-    /// dead-by-absence, so this struct does not carry it.
-    ///
-    /// The missile pair is the one non-uniform site (`60d4fd`–`60d517`): the gate is written as a
-    /// **literal 1**, not the weapon's own value, and the model only comes across with it.
+    /// The client's ranged weapon-visual merge (`0x60d450`): a ranged spell (`Attributes & 0x2`)
+    /// fills each field its own row leaves 0 from the equipped ranged weapon's row. State, channel
+    /// and the dest-anchored fields are never merged, and the missile gate comes across as a
+    /// literal 1, bringing the model with it. Hunter shots animate this way: Multi-Shot and the
+    /// stings carry precast = cast = 0 and take LoadBow (kit 7) and AttackBow (kit 164) from the
+    /// bow's `ItemDisplayInfo` column-10 visual, 5 on most bows.
     #[must_use]
     pub fn merged_over_weapon(&self, weapon: &VisualStages) -> VisualStages {
         let fill = |own: u32, w: u32| if own == 0 { w } else { own };
@@ -410,7 +217,7 @@ impl VisualStages {
         out.cast = fill(self.cast, weapon.cast); // 60d4e3
         out.impact = fill(self.impact, weapon.impact); // 60d4f0
         if self.missile_gate == 0 && weapon.missile_gate != 0 {
-            out.missile_gate = 1; // 60d50b — the literal, not the weapon's value
+            out.missile_gate = 1; // 60d50b: the literal, not the weapon's value
             out.missile_model = weapon.missile_model; // 60d512
         }
         out.missile_attach = fill(self.missile_attach, weapon.missile_attach); // 60d525
@@ -420,75 +227,53 @@ impl VisualStages {
     }
 }
 
-/// One `SpellVisualKit.dbc` row's body-animation + sound + the nine attach-point emitter slots
-/// (the columns consumed through decision 0099 phase 3; see the module doc for what remains).
-// No `Eq`: the `CharProc` params are floats (the client's own `fld` columns).
+/// One `SpellVisualKit.dbc` row.
+// No `Eq`: the `CharProc` params are floats.
 #[derive(Debug, Clone, Copy, Default, PartialEq)]
 pub struct VisualKit {
-    /// The `AnimationData.dbc` id this kit plays on the unit (`None` = no animation for this kit
-    /// — see the module doc's none-sentinel finding; common on impact kits).
+    /// Field 2: the `AnimationData.dbc` id played on the unit.
     pub anim_id: Option<u16>,
-    /// The `SoundEntries.dbc` kit id this stage rings (`None` = silent).
+    /// Field 13: the `SoundEntries.dbc` id.
     pub sound: Option<u32>,
-    /// The nine emitter slots (kit fields 3–11): each a `SpellVisualEffectName` id, in kit-field
-    /// order — slot `i` attaches at [`KIT_SLOT_TAGS`]`[i]`. Both none-sentinels fold to `None`
-    /// like [`Self::anim_id`]. Iterate populated slots via [`Self::effects`].
+    /// Fields 3-11: `SpellVisualEffectName` ids, slot `i` attaching at [`KIT_SLOT_TAGS`]`[i]`.
     pub effect_slots: [Option<u32>; 9],
-    /// Kit field 12 (`kit+0x30`) — the **tenth effect slot** (module docs; decision 0848). The
-    /// client plays it inline in `PlaySpellVisualKit` via `0x61fcf0`, same `CEffect` lifecycle as
-    /// the nine bone-attach slots. On the shipped table it carries the kit's body/ground **state
-    /// model** — the frozen ice, the net, the roots, the Thunderclap ring — never a projectile
-    /// (the real missile is `SpellVisual` field 7's, [`VisualStages::missile_model`]). Folded
-    /// into [`Self::effects`] at [`WORLD_EFFECT_TAG`].
+    /// Field 12, a tenth effect slot the client plays inline (`0x61fcf0`) as a `CEffect` node
+    /// marked as a world plant (`node+0x2c | 0x2`), with the nine slots' lifecycle (`0x614150`).
+    /// The data puts state models here (Frost Nova's ice, Net, Entangling Roots) and caster-feet
+    /// rings (Thunderclap), never a projectile.
     pub world_effect: Option<u32>,
-    /// Kit field 14 (`kit+0x38`) — the **`SpellEffectCameraShakes.dbc` group** this kit shakes the
-    /// camera with (`None` = no shake). Community name `ShakeID`; the value is a *group* id, never a
-    /// `CameraShakes` row id — see [`crate::SpellShakeGroup`]. 58 of the 1772 shipped kits carry
-    /// one, and every value lands on the group table's nine sparse ids `{3, 4, 5, 6, 7, 26, 66}`.
+    /// Field 14: a `SpellEffectCameraShakes.dbc` group id, never a `CameraShakes` row
+    /// ([`crate::SpellShakeGroup`]); all 58 shipped values land on that table.
     pub shake: Option<u32>,
-    /// The four `CharProc` slots (kit fields 15–34, transposed out of the five parallel arrays).
-    /// An unfilled slot is `None` — see [`char_proc_slot`] for the sentinel law; iterate the filled
-    /// ones via [`Self::char_procs`]. **Two consumers, two halves of the same table:** the *body*
-    /// procs an aura's state kit installs (type 14 translucency / type 1 tint — `benilla`'s
-    /// `aura_visual`, decision 0806), and the **dynobj emitter chain**, which scans for the FIRST
-    /// type **9** slot — there `params[0]` encodes the shard-model table index (the exact small-int
-    /// decode `bits(params[0] + 512.0) >> 14 & 0xff`, `0x5d55c0`) and `params[1]` is the emit rate
-    /// the graphics-quality factor multiplies (wow-re `dynobject-visual-machine.md`, decision 0797).
+    /// Fields 15-34, transposed out of five parallel arrays. The dynobject emitter takes the first
+    /// type-9 slot: `params[0]` is its shard model index, `params[1]` the emit rate the graphics
+    /// quality scales (`0x6eb930`).
     pub char_proc_slots: [Option<CharProc>; KIT_CHAR_PROCS],
 }
 
 impl VisualKit {
-    /// The filled `CharProc` slots, in slot order. The client walks all four unconditionally and
-    /// lets the dispatch table drop the unnamed keys; we drop the empty *slots* here and leave the
-    /// key switch to the consumer.
+    /// The filled `CharProc` slots, in slot order.
     pub fn char_procs(&self) -> impl Iterator<Item = CharProc> + '_ {
         self.char_proc_slots.iter().flatten().copied()
     }
 
-    /// The `params[0]` of this kit's first `CharProc` slot of type `ty`, if any — the shape both
-    /// modelled procs want (a single float: the alpha factor, the packed tint).
+    /// `params[0]` of the first slot of type `ty`: the alpha factor or the packed tint.
     pub fn char_proc_param(&self, ty: i32) -> Option<f32> {
         self.char_procs().find(|p| p.ty == ty).map(|p| p.params[0])
     }
 
-    /// This kit's weapon-trail proc — the **first** slot that decodes to one, matching the
-    /// dispatcher's in-order walk (no shipped kit carries two type-8 slots). `None` when the kit
-    /// arms no trail. See [`char_proc_type::WEAPON_TRAIL`].
+    /// The first slot that decodes as a weapon trail; no shipped kit has two.
     pub fn trail_proc(&self) -> Option<TrailProc> {
         self.char_procs().find_map(|p| p.as_weapon_trail())
     }
 
-    /// This kit's chain/beam proc — the **first** slot that decodes to one, matching the client's
-    /// dispatcher walk (it runs every slot in order; no shipped kit carries two). `None` when the
-    /// kit draws no beam. See [`chain_effects`] for the mechanism (decision 0955).
+    /// The first slot that decodes as a beam; no shipped kit has two.
     pub fn chain_proc(&self) -> Option<ChainProc> {
         self.char_procs().find_map(|p| p.as_chain())
     }
 
-    /// The populated emitter slots as `(M2 attachment id, SpellVisualEffectName id)` pairs, in
-    /// kit-field order — the client fires **all** populated slots at **every** stage (stage sets
-    /// lifetime policy only, wow-re `spell-visual-apply.md` §1.3) — then [`Self::world_effect`]
-    /// last, under the [`WORLD_EFFECT_TAG`] world-plant sentinel (decisions 0848/0850).
+    /// `(attachment id, effect id)` for each populated slot in field order, then the world effect
+    /// at [`WORLD_EFFECT_TAG`]; the client fires them all at every stage (`0x60edf0`).
     pub fn effects(&self) -> impl Iterator<Item = (u16, u32)> + '_ {
         self.effect_slots
             .iter()
@@ -498,38 +283,24 @@ impl VisualKit {
     }
 }
 
-/// `SpellVisual.dbc` × `SpellVisualKit.dbc` × `SpellVisualEffectName.dbc`, each kept in its own
-/// id space (three different tables' keys — never conflate them, mirroring
-/// [`crate::AreaSoundCatalog`]'s per-table map split).
+/// The spell visual tables, each in its own id space.
 pub struct SpellVisualCatalog {
     visuals: HashMap<u32, VisualStages>,
     kits: HashMap<u32, VisualKit>,
-    /// `SpellVisualEffectName` id → the effect model's `.mdx` path (field 2 — the table's one
-    /// column the kit slots consume).
+    /// `SpellVisualEffectName` id → model path (field 2).
     effect_paths: HashMap<u32, String>,
-    /// The `"HARDCODED *"`-named rows, name → (record id, path) — the client's engine-spawned effect set,
-    /// resolved BY NAME once at boot exactly like this (`0x61f5b0` matches a 14-string baked
-    /// table against the name column: loot art, footsteps, breath, level-up…; wow-re
-    /// `loot-corpse-effect.md` + `levelup-ding.md`). Three consumers today: "HARDCODED Loot Art"
-    /// (id 14 → `Particles\LootFX.mdl`, the corpse sparkle), "HARDCODED Unit Level Up"
-    /// (id 21 → `Spells\LevelUp\LevelUp.mdl`, the ding) and "HARDCODED Mount Poof"
-    /// (id 1185 → `Spells\DruidMorph_Impact_Base.mdx`, the mount-up cloud — decision 0927).
+    /// The `"HARDCODED *"` rows, name → (id, path): the effects the engine spawns itself, which the
+    /// client resolves by name at boot against 14 baked strings (`0x61f5b0`).
     hardcoded: HashMap<String, (u32, String)>,
-    /// `SpellChainEffects` id → the beam's geometry/animation row ([`chain_effects`], decision 0955).
-    /// Reached only through a kit's [`VisualKit::chain_proc`].
     chain_effects: HashMap<u32, ChainEffect>,
 }
 
 impl SpellVisualCatalog {
-    /// Build a catalog from explicit visual/kit tables — for tests and synthetic fixtures (the
-    /// [`crate::SpellCatalog::from_displays`] convention). The live path is
-    /// [`load_spell_visual_catalog`]. Carries no effect paths and no hardcoded rows.
+    /// A catalog from explicit tables, for tests; no effect paths, hardcoded rows or beams.
     pub fn from_tables(visuals: HashMap<u32, VisualStages>, kits: HashMap<u32, VisualKit>) -> Self {
         Self::from_tables_with_paths(visuals, kits, HashMap::new())
     }
 
-    /// [`Self::from_tables`] plus effect paths, for fixtures exercising the kit → effect-model
-    /// chain. The live path is [`load_spell_visual_catalog`].
     pub fn from_tables_with_paths(
         visuals: HashMap<u32, VisualStages>,
         kits: HashMap<u32, VisualKit>,
@@ -544,20 +315,15 @@ impl SpellVisualCatalog {
         }
     }
 
-    /// Seed one `SpellChainEffects` row, for fixtures exercising the beam chain. The live path is
-    /// [`load_spell_visual_catalog`].
+    /// Seed one `SpellChainEffects` row, for tests.
     #[must_use]
     pub fn with_chain_effect(mut self, id: u32, effect: ChainEffect) -> Self {
         self.chain_effects.insert(id, effect);
         self
     }
 
-    /// Seed one `"HARDCODED …"` name → (record id, model path), for fixtures exercising the
-    /// engine-spawned effects (the loot sparkle, the level-up ding, the mount poof). The live
-    /// path is the boot name-resolve inside [`load_spell_visual_catalog`], which is what
-    /// `0x61f5b0` does. The **id** is carried because it is half the reference's same-slot
-    /// replace key (`0x6208e0`; decision 2057) — an engine-spawned effect dedups exactly like a
-    /// kit slot's.
+    /// Seed one `"HARDCODED …"` row, for tests. The id matters: it is half the reference's
+    /// same-slot replace key (`0x6208e0`), so an engine-spawned effect dedups like a kit slot's.
     #[must_use]
     pub fn with_hardcoded(mut self, name: &str, id: u32, path: &str) -> Self {
         self.hardcoded
@@ -565,12 +331,11 @@ impl SpellVisualCatalog {
         self
     }
 
-    /// A `SpellVisual.dbc` row's stage kits by its id (`Spell.dbc` column 115, `spells::SpellDisplay::visual`).
+    /// A `SpellVisual.dbc` row by id, `Spell.dbc` column 115.
     pub fn stages(&self, visual_id: u32) -> Option<&VisualStages> {
         self.visuals.get(&visual_id)
     }
 
-    /// A `SpellVisualKit.dbc` row by its id (one of [`VisualStages`]'s five fields).
     pub fn kit(&self, kit_id: u32) -> Option<&VisualKit> {
         self.kits.get(&kit_id)
     }
@@ -584,28 +349,23 @@ impl SpellVisualCatalog {
         self.visuals.is_empty()
     }
 
-    /// Every loaded `SpellVisual` row as `(id, stages)`, unordered — for whole-table census
-    /// instruments (`benilla-extract shakecensus` walks it to find which effect models a
-    /// **DynamicObject** can host). Runtime consumers resolve one by id through [`Self::stages`].
+    /// Every `SpellVisual` row as `(id, stages)`, in no order, for whole-table census tools.
     pub fn visuals(&self) -> impl Iterator<Item = (u32, &VisualStages)> + '_ {
         self.visuals.iter().map(|(id, s)| (*id, s))
     }
 
-    /// Every loaded `SpellVisualKit` id, ascending — for whole-table census instruments
-    /// (`benilla-extract charprocs`). Runtime consumers resolve a kit by id through [`Self::kit`].
+    /// Every `SpellVisualKit` id, ascending, for whole-table census tools.
     pub fn kit_ids(&self) -> impl Iterator<Item = u32> + '_ {
         let mut ids: Vec<u32> = self.kits.keys().copied().collect();
         ids.sort_unstable();
         ids.into_iter()
     }
 
-    /// The number of `SpellVisualKit` rows loaded.
     pub fn kit_len(&self) -> usize {
         self.kits.len()
     }
 
-    /// A `SpellVisualEffectName` id's effect-model `.mdx` path (one of a kit's
-    /// [`VisualKit::effects`] slot values). `None` for an unknown id or an empty path.
+    /// A `SpellVisualEffectName` id's model path; an empty path reads as `None`.
     pub fn effect_path(&self, effect_id: u32) -> Option<&str> {
         self.effect_paths
             .get(&effect_id)
@@ -613,11 +373,8 @@ impl SpellVisualCatalog {
             .filter(|p| !p.is_empty())
     }
 
-    /// An engine-spawned hardcoded effect's `(record id, model path)`, by the client's own baked
-    /// name string ([`SpellVisualCatalog::hardcoded`]). Mirrors the client's boot name-resolve
-    /// (`0x61f5b0`, stricmp-family — hence the case-insensitive compare over the tiny set);
-    /// `None` when the shipped table names no such row. The id rides along because every consumer
-    /// hands it to the same-slot replace (`0x6208e0`, decision 2057).
+    /// An engine-spawned effect's `(id, model path)` by its baked name, compared without case as
+    /// the client's boot resolve (`0x61f5b0`) does.
     pub fn hardcoded_effect(&self, name: &str) -> Option<(u32, &str)> {
         self.hardcoded
             .iter()
@@ -626,20 +383,16 @@ impl SpellVisualCatalog {
             .filter(|(_, p)| !p.is_empty())
     }
 
-    /// The `"HARDCODED Loot Art"` row — the lootable-corpse sparkle, riding the shared hardcoded
-    /// map (one name-resolve mechanism for the whole engine-spawned set).
+    /// The lootable-corpse sparkle, `"HARDCODED Loot Art"`.
     pub fn loot_art_effect(&self) -> Option<(u32, &str)> {
         self.hardcoded_effect("HARDCODED Loot Art")
     }
 
-    /// A `SpellChainEffects` row by its id — the beam a kit's [`VisualKit::chain_proc`] names.
-    /// `None` for an id with no row, which is exactly the client's own null-row no-op and is how
-    /// the shipped table's padding slots resolve ([`chain_effects`]).
+    /// A `SpellChainEffects` row by id; `None` is the client's null-row no-op.
     pub fn chain_effect(&self, id: u32) -> Option<&ChainEffect> {
         self.chain_effects.get(&id)
     }
 
-    /// The number of `SpellChainEffects` rows loaded (18 on the shipped table).
     pub fn chain_effect_len(&self) -> usize {
         self.chain_effects.len()
     }
@@ -653,8 +406,7 @@ fn n_u32_schema(name: &str, fields: usize) -> Schema {
     s
 }
 
-/// `SpellVisualEffectName`'s 5-field schema: id · name (string — the HARDCODED-effect lookup
-/// key) · model `.mdx` path (string) · two dead columns (module docs).
+/// `SpellVisualEffectName`: id, name, model path, and two columns the client never reads.
 fn effect_name_schema() -> Schema {
     let mut s = Schema::new("SpellVisualEffectName");
     for i in 0..5 {
@@ -668,10 +420,8 @@ fn effect_name_schema() -> Schema {
     s
 }
 
-/// `SpellVisualKit`'s 35-field schema: fields 0–14 are the ids/FKs (`u32`), **15–18 the signed
-/// `CharProcType` keys** and **19–34 the four float param arrays** — the client loads the params
-/// with `fld` (wow-re `spellvisual-schema.md`), so they are typed here rather than bit-cast at
-/// every read.
+/// `SpellVisualKit`: fields 0-14 are ids, 15-18 the signed `CharProcType` keys and 19-34 the
+/// float params, which the dispatcher (`0x60d7c0`) loads with `fld`.
 fn kit_schema() -> Schema {
     let mut s = Schema::new("SpellVisualKit");
     for i in 0..SPELL_VISUAL_KIT_FIELDS {
@@ -685,25 +435,15 @@ fn kit_schema() -> Schema {
     s
 }
 
-/// Kit field 15 — `CharProcType[0]`, the first of the four type keys (@+0x3c).
+/// Kit field 15, `CharProcType[0]` (`+0x3c`).
 const CHAR_PROC_TYPE_FIELD: usize = 15;
-/// Kit field 19 — `CharParamZero[0]`, the first param column (@+0x4c); `CharParamOne/Two/Three[0]`
-/// follow every [`KIT_CHAR_PROCS`] fields (@+0x5c/+0x6c/+0x7c).
+/// Kit field 19, `CharParamZero[0]` (`+0x4c`); `CharParamOne..Three[0]` follow at every
+/// [`KIT_CHAR_PROCS`] fields (`+0x5c`, `+0x6c`, `+0x7c`).
 const CHAR_PROC_PARAM_FIELD: usize = CHAR_PROC_TYPE_FIELD + KIT_CHAR_PROCS;
 
-/// One kit's `CharProc` slot `i`, transposed out of the five parallel arrays.
-///
-/// **The empty-slot sentinel is `-1`, and `0` is a REAL key** (corrected by decision 0955). This
-/// used to fold `<= 0` to `None`, on the premise that "the dispatcher's translation table sends
-/// everything it doesn't name to the no-op case". The table names `0`: reading `0x60dc20`
-/// byte-for-byte, type **0 routes to case 0 (`0x60da79`) — the chain/beam case**, the same case
-/// type 12 reaches. Folding it away silently discarded **34 of the 48 live beams** in the shipped
-/// table, which is the whole of B161 ("Chain Lightning has no chain effect") and every missing
-/// drain/channel beam with it.
-///
-/// A type-`0` slot that is genuinely padding still costs nothing: its `CharParamZero` decodes to
-/// `0`, which names no `SpellChainEffects` row, and both the client (`0x6ecc2e`'s null-row test)
-/// and [`CharProc::as_chain`] no-op it. 20 of the 54 shipped type-0 slots are that case.
+/// Kit `CharProc` slot `i`. The empty slot is -1; 0 is a real key, the channel beam, which the
+/// dispatcher's table (`0x60dc20`) routes to its beam case (`0x60da79`). A type-0 slot that is
+/// padding decodes `CharParamZero` to 0, which the client's null-row test (`0x6ecc2e`) no-ops.
 fn char_proc_slot(r: &benilla_dbc::Record, i: usize) -> Option<CharProc> {
     let ty = i32_at(r, CHAR_PROC_TYPE_FIELD + i)?;
     if ty < 0 {
@@ -716,12 +456,11 @@ fn char_proc_slot(r: &benilla_dbc::Record, i: usize) -> Option<CharProc> {
     Some(CharProc { ty, params })
 }
 
-/// Fold the DBC's dual none-encoding (module docs) to `Option<u32>`.
 fn some_unless_none(v: u32) -> Option<u32> {
     (v != 0 && v != NONE_SENTINEL).then_some(v)
 }
 
-/// Read `SpellVisual.dbc` + `SpellVisualKit.dbc` off the patch chain.
+/// Read the four spell visual tables off the patch chain.
 pub fn load_spell_visual_catalog(chain: &mut Chain) -> Result<SpellVisualCatalog> {
     let sv_bytes = chain
         .read_file(SPELL_VISUAL)
@@ -798,9 +537,7 @@ pub fn load_spell_visual_catalog(chain: &mut Chain) -> Result<SpellVisualCatalog
     for r in sven_set.records() {
         let Some(id) = u32_at(r, 0) else { continue };
         if let Some(path) = str_at(&sven_set, r, 2) {
-            // The engine-spawned set is looked up by the name column — keep exactly the rows
-            // the client's own boot name-resolve can hit (the "HARDCODED " prefix; its
-            // matchers are stricmp-family, so lookups compare case-insensitively).
+            // Only the rows the client's boot resolve can hit, those named "HARDCODED …".
             if let Some(name) = str_at(&sven_set, r, 1).filter(|n| n.starts_with("HARDCODED ")) {
                 hardcoded.insert(name, (id, path.clone()));
             }
diff --git a/crates/benilla-formats/src/spell_visual/tests.rs b/crates/benilla-formats/src/spell_visual/tests.rs
index ddd377ef..21d837ff 100644
--- a/crates/benilla-formats/src/spell_visual/tests.rs
+++ b/crates/benilla-formats/src/spell_visual/tests.rs
@@ -1,13 +1,8 @@
-//! Tests for the spell-visual DBC family — the tables `super` loads, exercised against
-//! synthetic WDBCs and against the real 5875 client data (those skip when it is absent).
-//! Lifted out of `mod.rs` whole when that file outgrew its budget; two `#[cfg(test)]`
-//! modules merged into this one file scope.
+//! Tests for the spell visual tables, on synthetic WDBCs and on the installed data.
 
 use super::*;
 
-/// A minimal synthetic WDBC (20-byte header + fixed-width u32 records, no strings — both
-/// tables are all-`u32`) — the same shape `benilla-dbc`'s own tests build (`items.rs`
-/// reproduces it too), so this adapter is testable without a real client install.
+/// A WDBC of u32 records with an empty string block.
 fn build_wdbc(record_count: u32, field_count: u32, records: &[u8]) -> Vec<u8> {
     let record_size = field_count * 4;
     assert_eq!(records.len(), (record_count * record_size) as usize);
@@ -25,8 +20,7 @@ fn u32le(v: u32) -> [u8; 4] {
     v.to_le_bytes()
 }
 
-/// One `SpellVisual` row: id, the five stage kits, then the missile block — field 7 (model
-/// effect id) and field 9 (dest-attach ordinal) live, the rest zeroed to fill 16 fields.
+/// One `SpellVisual` row: id, the five stage kits, fields 7 and 9; the rest zero.
 fn spell_visual_row(
     id: u32,
     precast: u32,
@@ -51,13 +45,11 @@ fn spell_visual_row(
     rec
 }
 
-/// One `SpellVisualKit` row: id, an unpinned field 1, anim (field 2), nine zeroed emitter
-/// slots (3..11), the world-effect slot (field 12), sound (field 13), then zeroed trailing
-/// columns to fill 35 fields.
+/// One `SpellVisualKit` row: id, anim (field 2), world effect (12), sound (13); the rest zero.
 fn spell_visual_kit_row(id: u32, anim: u32, sound: u32, world: u32) -> Vec<u8> {
     let mut rec = Vec::new();
     rec.extend(u32le(id));
-    rec.extend(u32le(0)); // field 1, unpinned
+    rec.extend(u32le(0)); // field 1
     rec.extend(u32le(anim)); // field 2
     for _ in 3..12 {
         rec.extend(u32le(0)); // fields 3..11 (9 emitter slots)
@@ -72,10 +64,7 @@ fn spell_visual_kit_row(id: u32, anim: u32, sound: u32, world: u32) -> Vec<u8> {
 
 #[test]
 fn header_shape_matches_the_pinned_layout() {
-    // A single-row file of each still has to satisfy the pinned field/record-size shape —
-    // exercises the schema's own field-count check against a header lying about it would be
-    // a separate (missing) test; this one just guards our row builders stay in lock-step with
-    // SPELL_VISUAL_FIELDS/SPELL_VISUAL_KIT_FIELDS.
+    // The row builders stay in step with the field counts.
     let sv = spell_visual_row(1, 0, 0, 0, 0, 0, 0, 0);
     assert_eq!(sv.len(), SPELL_VISUAL_FIELDS * 4, "64B record");
     let svk = spell_visual_kit_row(1, 0, 0, 0);
@@ -130,8 +119,7 @@ fn parses_stage_kits_and_zero_means_no_kit_at_that_stage() {
             missile_attach: 1,
             missile_sound: None,
             strike_sound: None,
-            // The synthetic row builder writes 0 into field 6 and the dest-anchored block
-            // (the REAL Fireball row's missile_gate = 1 is pinned in the real-data test).
+            // The builder writes 0 to field 6 and the dest-anchored block.
             ..Default::default()
         }
     );
@@ -182,12 +170,10 @@ fn kit_anim_and_sound_fold_both_none_sentinels_to_none() {
     assert_eq!(kits[&2], VisualKit::default(), "0xFFFFFFFF = none too");
 }
 
-/// The emitter-slot surface: kit-field order maps to [`KIT_SLOT_TAGS`], both none-sentinels
-/// fold out, and `effects()` yields only the populated pairs.
 #[test]
 fn kit_effect_slots_pair_with_their_attach_tags() {
     let kit = VisualKit {
-        // Fireball's precast shape: LeftHand (slot index 3) + RightHand (slot index 4).
+        // Fireball's precast: left hand (slot 3) and right hand (slot 4).
         effect_slots: [
             None,
             None,
@@ -209,13 +195,11 @@ fn kit_effect_slots_pair_with_their_attach_tags() {
     assert_eq!(VisualKit::default().effects().count(), 0);
 }
 
-/// The tenth slot (field 12, decision 0848) rides `effects()` after the nine, at the interim
-/// Base anchor — one iterator, so every kit consumer (the aura-state watcher, kit pushes,
-/// cast/impact plays) picks it up without knowing it exists.
+/// Field 12 follows the nine slots in `effects()`, at [`WORLD_EFFECT_TAG`].
 #[test]
 fn kit_world_effect_joins_effects_at_base() {
     let kit = VisualKit {
-        // Frost Nova's state-kit shape: Head sparkle (slot 0) + the feet ice in field 12.
+        // Frost Nova's state kit: the head sparkle (slot 0) and the feet ice in field 12.
         effect_slots: [Some(54), None, None, None, None, None, None, None, None],
         world_effect: Some(284),
         ..Default::default()
@@ -227,9 +211,6 @@ fn kit_world_effect_joins_effects_at_base() {
     );
 }
 
-/// End-to-end on the real build-5875 tables: the byte-verified header shape (2165×16/64B ·
-/// 1772×35/140B) and the full Fireball chain (module doc's "Verified chain") — a schema drift
-/// or column slip fails loudly. Skips without client data.
 #[test]
 fn real_spell_visual_chain_resolves_fireball() {
     let data = crate::wow_data_or_skip!();
@@ -238,7 +219,7 @@ fn real_spell_visual_chain_resolves_fireball() {
     assert_eq!(cat.len(), 2165, "all 5875 SpellVisual rows load");
     assert_eq!(cat.kit_len(), 1772, "all 5875 SpellVisualKit rows load");
 
-    // Fireball (spell 133) → visual 67 (spells.rs's column-115 pin).
+    // Fireball, spell 133, is visual 67.
     let stages = cat.stages(67).expect("Fireball's SpellVisual row");
     assert_eq!(
         *stages,
@@ -250,20 +231,16 @@ fn real_spell_visual_chain_resolves_fireball() {
             channel: 0,
             missile_model: 365,
             missile_attach: 1,
-            // Field 10: the fireball's in-flight loop (SoundEntries 3011 → FireMissileLoop.wav).
+            // SoundEntries 3011 is FireMissileLoop.wav.
             missile_sound: Some(3011),
             strike_sound: None,
-            // Field 6 set = a missile owns the arrival: the GO dest one-shot gate is closed
-            // (0797); the dest-anchored columns are empty on a projectile nuke.
+            // Set: the missile owns the arrival, so there is no dest one-shot.
             missile_gate: 1,
             area_gate: 0,
             area_effect: 0,
             area_kit: 0,
         }
     );
-    // The gathering/work strike sounds (decision 0562): Mining's visual 93 carries the pick
-    // clang in field 14 (SoundEntries 1143 "Mining Impact" = MiningHitA-E), Herb's 91 the
-    // search rustle (1142) - the $TRD anim event's operands.
     assert_eq!(
         cat.stages(93).and_then(|s| s.strike_sound),
         Some(1143),
@@ -275,10 +252,7 @@ fn real_spell_visual_chain_resolves_fireball() {
         "Herb Gathering's visual carries the field-14 rustle"
     );
 
-    // A basic thrown attack borrows the equipped weapon's substitute visual (98 — the thrown
-    // dagger's ItemDisplayInfo col 10): no missile MODEL (it flies the weapon itself) but a
-    // flight loop in field 10 (SoundEntries 3318 → WeaponLoop.wav) — the whoosh the projectile
-    // carries while it travels.
+    // Visual 98 is the thrown dagger's `ItemDisplayInfo` column 10; 3318 is WeaponLoop.wav.
     let thrown = cat
         .stages(98)
         .expect("the thrown-weapon substitute SpellVisual");
@@ -291,8 +265,6 @@ fn real_spell_visual_chain_resolves_fireball() {
         Some(3318),
         "the thrown weapon's flight loop"
     );
-    // The missile chain (phase 4): field 7 → the projectile's own model, field 9 → the
-    // chest attach the missile homes to (ordinal 1 → 0x22).
     assert_eq!(
         cat.effect_path(stages.missile_model),
         Some("Spells\\Fireball_Missile_Low.mdx"),
@@ -303,8 +275,7 @@ fn real_spell_visual_chain_resolves_fireball() {
         "Fireball homes onto the target's chest"
     );
 
-    // The engine-spawned hardcoded set resolves by the client's own baked names — the ding
-    // (row 21, byte-verified `0x61f5b0`/`0x8618e0`, decision 0304's §5 fold-back).
+    // The ding resolves by the client's baked name (`0x61f5b0`, `0x8618e0`).
     assert_eq!(
         cat.hardcoded_effect("HARDCODED Unit Level Up"),
         Some((21, "Spells\\LevelUp\\LevelUp.mdl")),
@@ -331,8 +302,6 @@ fn real_spell_visual_chain_resolves_fireball() {
     );
     assert_eq!(impact_kit.sound, Some(1507));
 
-    // The precast kit's emitter slots (phase 3): effect 287 on both hands, and its
-    // SpellVisualEffectName path — the glowing-hands chain end to end.
     let precast_kit = cat.kit(stages.precast).expect("precast kit");
     assert_eq!(
         precast_kit.effects().collect::<Vec<_>>(),
@@ -345,10 +314,6 @@ fn real_spell_visual_chain_resolves_fireball() {
         "SpellVisualEffectName field 2 = the effect model path"
     );
 
-    // The tenth slot (field 12, decision 0848) on the real table — the root/snare state
-    // family the nine slots miss. Frost Nova (spell 122 → visual 17): state kit 285's feet
-    // ice; Net (spell 6533 → visual 683): state kit 744's net wrap, a kit with NO ordinary
-    // slots at all.
     let frost_nova_state = cat
         .kit(cat.stages(17).expect("Frost Nova's visual").state)
         .expect("Frost Nova's state kit");
@@ -367,7 +332,6 @@ fn real_spell_visual_chain_resolves_fireball() {
         "the net wrap is the kit's ONLY effect — invisible without field 12"
     );
     assert_eq!(cat.effect_path(594), Some("Spells\\Net_State.mdx"));
-    // The impact kit's chest burst — the phase-4 arrival hand-off will play this.
     assert_eq!(
         cat.kit(stages.impact)
             .unwrap()
@@ -378,27 +342,21 @@ fn real_spell_visual_chain_resolves_fireball() {
     );
 }
 
-/// The real 5875 `SpellVisualEffectName`: the boot-time HARDCODED name matcher's one consumed
-/// row — `"HARDCODED Loot Art"` is id 14 → `Particles\LootFX.mdl` (values pre-checked against
-/// the raw DBC bytes), and the `.m2` it names ships in the chain, so the lootable-corpse
-/// sparkle can actually load (wow-re `loot-corpse-effect.md`). Skips without client data.
+/// The lootable-corpse sparkle's row (`0x6005d0`) names a model that ships.
 #[test]
 fn real_effect_name_table_resolves_the_loot_art_row() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_visual_catalog(&mut chain).expect("load the visual catalog");
     assert_eq!(cat.loot_art_effect(), Some((14, "Particles\\LootFX.mdl")));
-    // The model the row names ships in the chain (consumers rewrite .mdl → .m2 to load it).
+    // Consumers load an `.mdl` path as `.m2`.
     assert!(
         chain.read_file("Particles\\LootFX.m2").is_ok(),
         "LootFX.m2 must ship in the chain"
     );
 }
 
-/// The dest-anchored chain on the REAL data — 0797's mandatory per-spell data check (the
-/// wow-re read pinned the GATE; whether each spell passes it is a table fact). Skips
-/// without client data. Every value here corroborates the live vmangos wire capture:
-/// Blizzard's dynobj RADIUS was 8.0 (row 14), Flamestrike's 5.0 (row 8).
+/// The gate is the client's (`0x5d57c0`); whether each spell passes it is data.
 #[test]
 fn ground_aoe_chain_reads_the_dest_anchored_block() {
     let data = crate::wow_data_or_skip!();
@@ -407,8 +365,7 @@ fn ground_aoe_chain_reads_the_dest_anchored_block() {
     let visuals = load_spell_visual_catalog(&mut chain).expect("visuals");
     let radii = crate::load_spell_radii(&mut chain).expect("radii");
 
-    // Blizzard 10 → visual 259: both visuals — its own model AND a type-9 shard emitter
-    // whose table index decodes to 0 (the same model), rate 5/s, sound 7.
+    // Blizzard (10, visual 259): its own model and a type-9 shard emitter, index 0, 5 per second.
     let d = catalog.get(10).unwrap();
     assert_eq!((d.visual, d.effect_radius_index), (259, [14, 0, 0]));
     assert_eq!(
@@ -430,8 +387,7 @@ fn ground_aoe_chain_reads_the_dest_anchored_block() {
     let proc = k.char_procs().find(|p| p.ty == 9).unwrap();
     assert_eq!((proc.params[0], proc.params[1]), (0.0, 5.0));
 
-    // Flamestrike 2120 → visual 33: its own model + sound, NO type-9 proc (a burning
-    // patch has no falling shards) — the emitter half is data-absent, not code-gated.
+    // Flamestrike (2120, visual 33): its own model and sound, and no type-9 emitter in the data.
     let d = catalog.get(2120).unwrap();
     assert_eq!((d.visual, d.effect_radius_index), (33, [8, 8, 0]));
     assert_eq!(radii.get(8).map(|r| r.radius), Some(5.0), "the wire radius");
@@ -448,7 +404,7 @@ fn ground_aoe_chain_reads_the_dest_anchored_block() {
     assert_eq!(k.sound, Some(3077));
     assert!(k.char_procs().all(|p| p.ty != 9));
 
-    // Rain of Fire 5740 → visual 329: shard-table index 1 (its own model again), rate 5/s.
+    // Rain of Fire (5740, visual 329): shard index 1, 5 per second.
     let v = visuals.stages(catalog.get(5740).unwrap().visual).unwrap();
     assert_eq!((v.missile_gate, v.area_gate, v.area_effect), (0, 1, 448));
     let proc = visuals
@@ -458,16 +414,11 @@ fn ground_aoe_chain_reads_the_dest_anchored_block() {
         .find(|p| p.ty == 9)
         .unwrap();
     assert_eq!((proc.params[0], proc.params[1]), (1.0, 5.0));
-
-    // All three pass the GO dest one-shot gate (field 6 == 0 ∧ field 12 ≠ 0) — the burst
-    // fires for each; Fireball (missile_gate 1, pinned in the loader test above) does not.
 }
 
-// ── The chain/beam table (decision 0955) ──────────────────────────────────────────────────────
+// ── The chain/beam table ──────────────────────────────────────────────────────
 
-/// The small-int decode, on the exact values the shipped table ships. This is the load-bearing
-/// arithmetic — get it wrong and every beam resolves to the wrong texture (or to none) — so it is
-/// pinned against hand-computed IEEE bits rather than against itself.
+/// Pinned against hand-computed IEEE bits, not against itself.
 #[test]
 fn char_proc_small_int_recovers_the_integer() {
     // 1.0 + 512.0 = 513.0 = 0x44004000; >>14 = 0x11001; &0xff = 1.
@@ -476,14 +427,11 @@ fn char_proc_small_int_recovers_the_integer() {
     for n in 0..=255u32 {
         assert_eq!(char_proc_small_int(n as f32), n, "round-trips every byte");
     }
-    // The decode truncates rather than rounds — it reads the integer part out of the mantissa.
+    // It truncates, reading the integer part out of the mantissa.
     assert_eq!(char_proc_small_int(3.9), 3);
 }
 
-/// `SpellChainEffects.dbc` as it actually ships: 18 rows, the gaps at 14/16, and the two rows the
-/// director's report turns on — id 1 (Chain Lightning's `Lightning`, the one row whose hops
-/// stagger by 300 ms rather than 200) and id 8 (Drain Life's `SoulBeam`, one of the four
-/// negative-period drains).
+/// Rows 1 (Chain Lightning) and 8 (Drain Life) as the file ships them.
 #[test]
 fn real_chain_effects_table() {
     let data = crate::wow_data_or_skip!();
@@ -533,19 +481,14 @@ fn real_chain_effects_table() {
     assert!(cat.chain_effect(21).is_none());
 }
 
-/// **The regression that IS decision 0955.** The chain `CharProc` reaches its beam on the real
-/// table, for both keys — and every live chain slot resolves to a real row.
-///
-/// The old `char_proc_slot` folded type `0` to "empty", so 34 of the 48 live beams (every channel
-/// beam in the game) never existed as far as this crate was concerned. A regression here reads as
-/// "Drain Life has no beam again".
+/// Both chain keys reach their beams; folding type 0 to empty would lose every channel beam.
 #[test]
 fn real_chain_procs_resolve_to_their_beams() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_visual_catalog(&mut chain).expect("load spell visuals");
 
-    // Chain Lightning (spell 421 → visual 36) — cast kit 321, type 12, one beam, flag clear.
+    // Chain Lightning (spell 421, visual 36): cast kit 321, type 12, one beam, flag clear.
     let cl = cat.kit(321).expect("kit 321").chain_proc().expect("a beam");
     assert_eq!(cl.ty, char_proc_type::CHAIN_CAST);
     assert_eq!((cl.effect_id, cl.beams, cl.flag), (1, 1, false));
@@ -554,14 +497,12 @@ fn real_chain_procs_resolve_to_their_beams() {
         Some("Textures\\SpellChainEffects\\Lightning.blp")
     );
 
-    // Drain Life (spell 689 → visual 177) — channel kit 402, type 0, flag SET. This is the one
-    // the `<= 0` sentinel used to swallow whole.
+    // Drain Life (spell 689, visual 177): channel kit 402, type 0, flag set.
     let dl = cat.kit(402).expect("kit 402").chain_proc().expect("a beam");
     assert_eq!(dl.ty, char_proc_type::CHAIN_CHANNEL);
     assert_eq!((dl.effect_id, dl.beams, dl.flag), (8, 1, true));
 
-    // The named cast-stage others, each predicting its own texture — the corroboration that the
-    // decode is the mechanism and not a coincidence that fits Chain Lightning.
+    // Each kit's decoded id names its own texture.
     for (kit, effect, texture) in [
         (3169u32, 2u32, "HealBeam.blp"),     // Chain Heal
         (430, 4, "ManaBeam.blp"),            // Drain Mana / Mind Flay (channel)
@@ -570,7 +511,7 @@ fn real_chain_procs_resolve_to_their_beams() {
         (2509, 6, "ManaBurnBeam.blp"),       // Shrink Ray
         (6480, 18, "SoulBeam.blp"),          // C'Thun's Eye Beam
         (6567, 7, "ShockLightning.blp"),     // the Feugen/Stalagg chains
-        (6397, 3, "DrainManaLightning.blp"), // Chain Burn — the one 3-beam kit
+        (6397, 3, "DrainManaLightning.blp"), // Chain Burn, the one 3-beam kit
     ] {
         let p = cat
             .kit(kit)
@@ -594,8 +535,7 @@ fn real_chain_procs_resolve_to_their_beams() {
         "Chain Burn is the only kit asking for more than one beam"
     );
 
-    // The whole-table census — the shape the census instrument prints, asserted so a schema slip
-    // or a sentinel regression is a number that moved.
+    // The whole-table census, as `chaincensus` prints it.
     let (mut slots, mut live, mut padding) = (0, 0, 0);
     for id in cat.kit_ids() {
         let kit = cat.kit(id).expect("kit");
@@ -621,17 +561,13 @@ fn real_chain_procs_resolve_to_their_beams() {
     );
 }
 
-/// **Every live beam's texture actually exists on the patch chain.** The renderer (decision 0964)
-/// loads these by path, and a path that resolves to nothing draws an invisible beam — a failure no
-/// geometry test can see and no gate can catch. Cheapest possible guard against "the whole lane is
-/// right and the screen is empty".
+/// A texture path that resolves to nothing draws an invisible beam.
 #[test]
 fn real_chain_effect_textures_resolve_on_the_patch_chain() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_visual_catalog(&mut chain).expect("load spell visuals");
-    // Only the rows a shipped kit can actually reach: an unreachable row's texture is nobody's
-    // problem (id 15 is degenerate anyway).
+    // Only the rows a shipped kit reaches.
     let mut reached: Vec<u32> = cat
         .kit_ids()
         .filter_map(|id| Some(cat.kit(id)?.chain_proc()?.effect_id))
@@ -648,9 +584,7 @@ fn real_chain_effect_textures_resolve_on_the_patch_chain() {
     }
 }
 
-/// The padding case, isolated: a type-0 slot whose `CharParamZero` is `0` is not a beam — the
-/// client's own null-row test no-ops it, and so must we. Kit 2089 (Death & Decay, Ritual of Doom)
-/// ships four of them.
+/// A type-0 slot whose `CharParamZero` is 0 is no beam; kit 2089 (Death and Decay) ships four.
 #[test]
 fn real_zero_param_chain_slots_are_padding() {
     let data = crate::wow_data_or_skip!();
@@ -667,17 +601,15 @@ fn real_zero_param_chain_slots_are_padding() {
     assert!(kit.chain_proc().is_none(), "…but none of them is a beam");
 }
 
-/// [`VisualStages::merged_over_weapon`] — the `60d4d2`–`60d54c` fill, field by field: a populated
-/// slot survives, an empty one takes the weapon's, and the two the client pointedly skips
-/// (`state`/`channel`) stay empty however loud the weapon's row is.
+/// The client's fill (`60d4d2`-`60d54c`), field by field.
 #[test]
 fn the_weapon_merge_fills_only_the_empty_slots() {
     let weapon = VisualStages {
         precast: 7,
         cast: 164,
         impact: 1947,
-        state: 999,   // +0x10 — never merged
-        channel: 998, // +0x14 — never merged
+        state: 999,   // +0x10, never merged
+        channel: 998, // +0x14, never merged
         missile_gate: 1,
         missile_model: 42,
         missile_attach: 3,
@@ -719,30 +651,26 @@ fn the_weapon_merge_fills_only_the_empty_slots() {
         "neither is the dest-anchored block"
     );
 
-    // The missile pair's own arm: an own row with NO missile takes the weapon's — and the gate is
-    // written as the literal 1 (`60d50b`), not the weapon's value.
+    // A row with no missile takes the weapon's, the gate as a literal 1 (`60d50b`).
     let no_missile = VisualStages::default().merged_over_weapon(&VisualStages {
         missile_gate: 5,
         missile_model: 42,
         ..Default::default()
     });
     assert_eq!((no_missile.missile_gate, no_missile.missile_model), (1, 42));
-    // …and a weapon with no missile never plants one.
+    // A weapon with no missile gives none.
     let neither = VisualStages::default().merged_over_weapon(&VisualStages::default());
     assert_eq!((neither.missile_gate, neither.missile_model), (0, 0));
 }
 
-/// The real 5875 tables, end to end: every live hunter shot leaves both body-kit slots empty, so
-/// the bow's own visual 5 is the only source of a draw/release clip — and the merge lands
-/// **LoadBow (105) → AttackBow (46)** on each while its impact + missile survive untouched. The
-/// pin behind bug B153; a data change that filled these rows would make the merge a no-op and
-/// this test would say so.
+/// Every live hunter shot leaves both body kits empty, so its draw and release clips come from
+/// the bow's visual.
 #[test]
 fn real_hunter_shots_take_the_bows_load_and_release_clips() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_visual_catalog(&mut chain).expect("load spell visuals");
-    // `ItemDisplayInfo` col 10 for every bow (wow-re `throw-ranged-attack-anim.md`'s table).
+    // Visual 5, the `ItemDisplayInfo` column 10 of most bows.
     let bow = *cat.stages(5).expect("the bow's substitute visual 5");
     assert_eq!(
         (bow.precast, bow.cast),
@@ -779,14 +707,11 @@ fn real_hunter_shots_take_the_bows_load_and_release_clips() {
             "visual {spell_visual} keeps its own projectile"
         );
     }
-    // The kit ids resolve to the AnimationData rows the caster actually plays.
     assert_eq!(cat.kit(7).and_then(|k| k.anim_id), Some(105), "LoadBow");
     assert_eq!(cat.kit(164).and_then(|k| k.anim_id), Some(46), "AttackBow");
 }
 
-/// The type-8 arm's decode is **plain truncation** (`_ftol` at `0x40a2b0`), not the small-int
-/// idiom every other integer-carrying param uses — a slot decoded the wrong way yields a colour
-/// of 0 and a duration of 0, i.e. silently no trail at all.
+/// The type-8 arm truncates (`_ftol`, `0x40a2b0`); the small-int decode would give no trail.
 #[test]
 fn a_weapon_trail_proc_decodes_by_truncation() {
     // Kit 324's shipped row: Zero = 16263465 (`0xf82929`), One = 20, Two = 600, Three = 100.
@@ -809,7 +734,7 @@ fn a_weapon_trail_proc_decodes_by_truncation() {
     );
 }
 
-/// `0x5fe494 cmp eax,edi ; je` — a zero duration fires nothing, so it is not a trail.
+/// A zero duration fires nothing (`0x5fe494`).
 #[test]
 fn a_zero_duration_trail_proc_is_no_trail() {
     let proc = CharProc {
@@ -819,8 +744,6 @@ fn a_zero_duration_trail_proc_is_no_trail() {
     assert!(proc.as_weapon_trail().is_none());
 }
 
-/// Only type 8 reaches the arm — `VisualKit::trail_proc` must not answer for a tint or an alpha
-/// proc whose `params[2]` happens to be nonzero.
 #[test]
 fn only_type_eight_arms_a_trail() {
     for ty in [
diff --git a/crates/benilla-formats/src/spells/cast_times.rs b/crates/benilla-formats/src/spells/cast_times.rs
index 7b0dca16..ccbc15da 100644
--- a/crates/benilla-formats/src/spells/cast_times.rs
+++ b/crates/benilla-formats/src/spells/cast_times.rs
@@ -1,21 +1,7 @@
-//! `SpellCastTimes.dbc` — the base/per-level/minimum cast time (ms) a spell's `CastingTimeIndex`
-//! column ([`crate::spells::SpellDisplay::casting_time_index`]) resolves against. Feeds the
-//! level-scaled cast-time formula — `Spell_C::GetCastTime 0x6e3340`, byte-confirmed by the
-//! 2026-07-10 wow-re §5 cross-check (`wave-cooldown.md`, wow-re commit `f2c563c9`): it reads
-//! CastingTimeIndex `[SpellRec+0x48]`, resolves this table's recordsById at `[0xc0d878]`, scales
-//! base/perLevel floored to the row minimum, and applies spell-mod op `0xa`
-//! (SPELLMOD_CASTING_TIME). The row layout is settled independently (WoWDBDefs'
-//! `1.0.0.3980`–`1.12.3.6141` layout `$id$ID<32> Base<32> PerLevel<32> Minimum<32>`, covering
-//! build 5875 — cross-checked against the real extracted file below).
-//!
-//! **Row layout** — pinned on the extracted 5875 file (52 records × 4 fields, 16 B/record):
-//! `ID(0)`, `Base(1)` = the ms a flat 1.12 tooltip shows, `PerLevel(2, **signed**` — a handful of
-//! rows shrink cast time per caster level, e.g. row 10 = `{1000, -100, 500}`), `Minimum(3)` = the
-//! floor the level scaling clamps to. Row 1 = `{0, 0, 0}` — the client's universal **instant**
-//! sentinel; every non-cast-time spell's `CastingTimeIndex` points here (Frost Armor, Battle
-//! Shout, Fire Blast, Auto Shot — all probed). Row 16 = `{1500, 0, 1500}` — Fireball rank 1
-//! (spell 133)'s real cast time, cross-checked end-to-end against the local vmangos
-//! `spell_template` (`castingTimeIndex` 16 for entry 133).
+//! `SpellCastTimes.dbc`: the cast time a spell's `CastingTimeIndex`
+//! ([`crate::spells::SpellDisplay::casting_time_index`]) resolves to in `Spell_C::GetCastTime`
+//! (`0x6e3340`), before spell-mod op `0xa` (`SPELLMOD_CASTING_TIME`). Row 1, `{0, 0, 0}`, is the
+//! instant sentinel every spell without a cast time points at.
 
 use std::collections::HashMap;
 
@@ -25,25 +11,22 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 
 use crate::dbc::{i32_at, parse, u32_at};
 
-/// One `SpellCastTimes.dbc` row (module doc's row law).
+/// One `SpellCastTimes.dbc` row, in ms.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct SpellCastTime {
-    /// The cast time a flat (level-independent) tooltip render shows, ms. `0` = instant.
+    /// The cast time a level-independent tooltip shows; 0 is instant.
     pub base_ms: u32,
-    /// Signed ms added per caster level above the spell's `BaseLevel` (can be negative — cast
-    /// time shrinking as the caster levels); `0` for the overwhelming majority of rows.
+    /// Added per caster level above the spell's `BaseLevel`; negative on a few rows (row 10).
     pub per_level_ms: i32,
     /// The floor the level-scaled cast time clamps to.
     pub minimum_ms: u32,
 }
 
 impl SpellCastTime {
-    /// The level-scaled cast time, ms — `Spell_C::GetCastTime 0x6e3340`'s walk over this row
-    /// (module docs): `base + perLevel·(casterLevel − baseLevel)`, floored to the row minimum
-    /// and to zero. `base_level` is the `SpellRec+0x70` column the client scales against
-    /// ([`crate::spells::SpellDisplay::base_level`] — the DBC's `baseLevel`, col 28, not its
-    /// `spellLevel`, col 29). Spellmod op `0xa` (SPELLMOD_CASTING_TIME) is the caller's
-    /// concern — no downstream consumer models spellmods yet.
+    /// The level-scaled cast time (`0x6e3340`): `base + perLevel·(casterLevel − baseLevel)`,
+    /// floored to the row minimum and to zero. `base_level` is the DBC's `baseLevel`
+    /// ([`crate::spells::SpellDisplay::base_level`]), not `spellLevel`. Spell-mod op `0xa` is not
+    /// applied.
     pub fn resolved_ms(&self, caster_level: u32, base_level: u32) -> u32 {
         let delta = i64::from(caster_level.saturating_sub(base_level));
         let scaled = i64::from(self.base_ms) + i64::from(self.per_level_ms) * delta;
@@ -74,7 +57,7 @@ impl SpellCastTimeCatalog {
 const SPELL_CAST_TIMES: &str = "DBFilesClient\\SpellCastTimes.dbc";
 const SPELL_CAST_TIMES_FIELDS: usize = 4;
 
-/// Load `SpellCastTimes.dbc` off the patch chain ([`SpellCastTime`]'s row law).
+/// Load `SpellCastTimes.dbc` off the patch chain.
 pub fn load_spell_cast_times(chain: &mut Chain) -> Result<SpellCastTimeCatalog> {
     let bytes = chain
         .read_file(SPELL_CAST_TIMES)
@@ -106,9 +89,6 @@ pub fn load_spell_cast_times(chain: &mut Chain) -> Result<SpellCastTimeCatalog>
 mod tests {
     use super::*;
 
-    /// `GetCastTime 0x6e3340`'s scaling walk on the module doc's own probe rows: the instant
-    /// sentinel stays 0, a flat row ignores level, and the signed per-level row shrinks down to
-    /// its minimum floor (never below, never negative).
     #[test]
     fn resolved_ms_scales_and_floors() {
         let instant = SpellCastTime {
@@ -125,8 +105,7 @@ mod tests {
         };
         assert_eq!(fireball.resolved_ms(60, 1), 1500);
 
-        // Row 10's real shape {1000, -100, 500}: at spell level it reads base, then shrinks
-        // 100 ms/level until the 500 floor catches it.
+        // Row 10's shape: 100 ms less per level above the spell's, floored at 500.
         let scaling = SpellCastTime {
             base_ms: 1000,
             per_level_ms: -100,
@@ -145,27 +124,24 @@ mod tests {
         assert_eq!(floorless.resolved_ms(60, 1), 0);
     }
 
-    /// `SpellCastTimes.dbc` on the real data — the module doc's own probe rows. Skips without
-    /// client data.
     #[test]
     fn real_spell_cast_times_read_the_probed_rows() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let times = load_spell_cast_times(&mut chain).expect("load SpellCastTimes");
 
-        // Row 1: the universal instant sentinel.
+        // Row 1: the instant sentinel.
         let instant = times.get(1).expect("row 1");
         assert_eq!(
             (instant.base_ms, instant.per_level_ms, instant.minimum_ms),
             (0, 0, 0)
         );
 
-        // Row 16: Fireball rank 1's real cast time (vmangos spell_template.castingTimeIndex==16
-        // for entry 133).
+        // Row 16: Fireball rank 1, spell 133 (vmangos `spell_template.castingTimeIndex`).
         let fireball = times.get(16).expect("row 16");
         assert_eq!(fireball.base_ms, 1500);
 
-        // Row 10: a level-scaling row — the signed per_level_ms actually goes negative.
+        // Row 10: a level-scaling row with a negative per-level term.
         let scaling = times.get(10).expect("row 10");
         assert_eq!(
             (scaling.base_ms, scaling.per_level_ms, scaling.minimum_ms),
diff --git a/crates/benilla-formats/src/spells/catalog_tests.rs b/crates/benilla-formats/src/spells/catalog_tests.rs
index 3b6fed88..ca4de226 100644
--- a/crates/benilla-formats/src/spells/catalog_tests.rs
+++ b/crates/benilla-formats/src/spells/catalog_tests.rs
@@ -1,17 +1,9 @@
-//! Data-gated regression tests for [`super::load_spell_catalog`] — every column pin documented in
-//! `spells/mod.rs`'s module doc, exercised end-to-end against the real build-5875 `Spell.dbc` (and,
-//! for the tooltip-arc columns, the new `SpellCastTimes.dbc`/`SpellDuration.dbc` catalogs). Split
-//! out of `mod.rs` purely for file size — this is still `crate::spells`'s own test suite, not a
-//! separate concern. Every test skips (passes) without `<repo>/WoW/Data`.
+//! The spell catalog's column pins, checked end to end against the real 5875 `Spell.dbc`.
 
 use super::*;
 
-/// The learn-spell hop (decision 0247): a class trainer offers a LEARN *wrapper* spell, not the
-/// ability — the wire id is never in `SkillLineAbility`, so the tree must hop through the taught
-/// spell to group it. Probed on real 5875 data: the warrior wrappers resolve to their abilities
-/// (Heroic Strike 78 via 1605, Charge 100 via 1738, Rend 772 via 1423, Battle Shout 6673 via
-/// 6674), the wrappers themselves carry no skill line, and the taught abilities do. This is the
-/// exact failure that emptied the trainer tree until the hop landed. Skips without client data.
+/// A trainer's learn wrapper is never in `SkillLineAbility`, so the tree groups it by the spell
+/// it teaches: Heroic Strike 78 via 1605, Charge 100 via 1738, Battle Shout 6673 via 6674.
 #[test]
 fn real_learn_spell_hop_resolves_the_taught_ability() {
     let data = crate::wow_data_or_skip!();
@@ -42,17 +34,14 @@ fn real_learn_spell_hop_resolves_the_taught_ability() {
     }
 }
 
-/// The attribute columns + the ranged gate on the real build-5875 `Spell.dbc` — a column slip
-/// fails loudly. Values are the vmangos `spell_template` rows the module doc's pin used.
-/// Skips without client data.
+/// Values from the vmangos `spell_template` rows.
 #[test]
 fn real_spell_catalog_reads_ranged_attributes() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // Auto Shot: SPELL_ATTR_RANGED (0x2, in 0x50012) + auto-repeat (0x20). No visual — the
-    // missile is the wire ammo.
+    // Auto Shot: ranged (0x2) and auto-repeat (0x20); no visual, the wire ammo is the missile.
     let auto_shot = cat.get(75).expect("Auto Shot");
     assert_eq!(auto_shot.attributes, 0x50012);
     assert_eq!(auto_shot.attributes_ex2, 0x20);
@@ -66,21 +55,19 @@ fn real_spell_catalog_reads_ranged_attributes() {
     assert_eq!(shoot.attributes_ex2, 0x20);
     assert!(shoot.ranged_attack());
 
-    // Throw: ranged-attribute but not auto-repeat — still arms the ranged stance.
+    // Throw: ranged but not auto-repeat, and still arms the ranged stance.
     let throw = cat.get(2764).expect("Throw");
     assert_eq!(throw.attributes, 0x410012);
     assert_eq!(throw.attributes_ex2, 0);
     assert!(throw.ranged_attack());
 
-    // Fireball: neither bit — a plain cast never arms ranged.
+    // Fireball: neither bit.
     let fireball = cat.get(133).expect("Fireball");
     assert_eq!(fireball.attributes, 0x10000);
     assert_eq!(fireball.attributes_ex2, 0);
     assert!(!fireball.ranged_attack());
 
-    // Effect[0] (column 61): the auto-attack 6603 "Attack" carries SPELL_EFFECT_ATTACK (78) —
-    // the client's own melee-substitution trigger (decision 0231); an ordinary spell doesn't.
-    // A column slip on Effect[0] fails here.
+    // Effect[0] (column 61): 6603 "Attack" carries SPELL_EFFECT_ATTACK (78).
     let attack = cat.get(6603).expect("Attack");
     assert_eq!(
         attack.effects[0], 78,
@@ -94,22 +81,15 @@ fn real_spell_catalog_reads_ranged_attributes() {
     );
 }
 
-/// The aura-bar display filter on the real build-5875 `Spell.dbc` (decisions 0268 + 0385): the
-/// warrior stances carry `SPELL_ATTR_EX_NO_AURA_ICON` and the internal proc auras (Defensive
-/// State 5301/5302) carry `SPELL_ATTR_DO_NOT_DISPLAY` (`0x80`) — the two bits the reference's
-/// cache builder (`PlayerAuras_Update 0x4e4170`) refuses a slot for (its `Attributes` read is
-/// byte-width) — while the everyday warrior buff (Battle Shout), an ordinary long buff
-/// (Power Word: Fortitude), and the uncancelable world buff Echoes of Lordaeron (`Attributes`
-/// dword sign bit, which is NOT a display filter) stay visible. The exact attribute values pin
-/// columns 6/7 — a column slip fails loudly. Skips without client data.
+/// The buff bar's cache builder (`PlayerAuras_Update` `0x4e4170`) refuses `NO_AURA_ICON` and
+/// `DO_NOT_DISPLAY` (0x80), reading `Attributes` as a byte (columns 6 and 7).
 #[test]
 fn real_spell_catalog_hides_stances_from_the_aura_bar() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // The stances: Battle carries NO_AURA_ICON | CAST_WHEN_LEARNED, the other two just
-    // NO_AURA_ICON (extracted Spell.dbc, cross-checked against vmangos spell_template).
+    // Battle Stance carries NO_AURA_ICON | CAST_WHEN_LEARNED, the other two NO_AURA_ICON alone.
     let battle = cat.get(2457).expect("Battle Stance");
     assert_eq!(battle.attributes_ex, 0x9000_0000);
     assert!(battle.hidden_from_aura_bar());
@@ -120,9 +100,7 @@ fn real_spell_catalog_hides_stances_from_the_aura_bar() {
     assert_eq!(berserker.attributes_ex, 0x1000_0000);
     assert!(berserker.hidden_from_aura_bar());
 
-    // The internal proc auras: Defensive State 5302 rides a visible wire slot (not passive)
-    // but carries `SPELL_ATTR_DO_NOT_DISPLAY`, so the reference never shows it (director's
-    // report, 2026-07-14: it showed on our bar, sometimes with its timer).
+    // Defensive State 5302 rides a visible wire slot, but DO_NOT_DISPLAY keeps it off the bar.
     let def_state = cat.get(5302).expect("Defensive State");
     assert_eq!(def_state.attributes, 0x2000_0190);
     assert!(def_state.hidden_from_aura_bar());
@@ -130,32 +108,24 @@ fn real_spell_catalog_hides_stances_from_the_aura_bar() {
     assert_eq!(def_state_dnd.attributes, 0x1d0);
     assert!(def_state_dnd.hidden_from_aura_bar());
 
-    // The auras a warrior actually watches stay on the bar.
     let shout = cat.get(6673).expect("Battle Shout");
     assert!(!shout.hidden_from_aura_bar());
     let fortitude = cat.get(1243).expect("Power Word: Fortitude");
     assert!(!fortitude.hidden_from_aura_bar());
 
-    // The dword sign bit (`SPELL_ATTR_NO_AURA_CANCEL`) is NOT a display filter — the cache
-    // builder's `Attributes` read is byte-width (decision 0385). Echoes of Lordaeron is
-    // uncancelable yet displays on the reference; the sign-bit transcription would hide it.
+    // The dword sign bit (`NO_AURA_CANCEL`) filters nothing: Echoes of Lordaeron still shows.
     let echoes = cat.get(1386).expect("Echoes of Lordaeron");
     assert_eq!(echoes.attributes, 0x8800_0100);
     assert!(!echoes.hidden_from_aura_bar());
 }
 
-/// `rank`/`passive` on the real build-5875 `Spell.dbc` — the module doc's own probe spells
-/// (every rank of Fireball, plus Frost Armor/Corruption/Fire Blast) all carry their literal
-/// "Rank N" subtext, and a representative passive (a weapon-skill spell, `SPELL_ATTR_PASSIVE`
-/// module doc) reads `passive == true` while an ordinary active spell reads `false`. Skips
-/// without client data.
 #[test]
 fn real_spell_catalog_reads_rank_and_passive() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // Fireball's first three ranks — even rank 1 carries the literal "Rank 1" (module doc).
+    // Fireball's first three ranks; even rank 1 carries the literal "Rank 1".
     assert_eq!(cat.get(133).unwrap().rank.as_deref(), Some("Rank 1"));
     assert_eq!(cat.get(143).unwrap().rank.as_deref(), Some("Rank 2"));
     assert_eq!(cat.get(145).unwrap().rank.as_deref(), Some("Rank 3"));
@@ -163,8 +133,7 @@ fn real_spell_catalog_reads_rank_and_passive() {
     assert_eq!(cat.get(172).unwrap().rank.as_deref(), Some("Rank 1")); // Corruption
     assert_eq!(cat.get(2136).unwrap().rank.as_deref(), Some("Rank 1")); // Fire Blast
 
-    // None of the above are passive; a weapon-skill spell (One-Handed Swords, id 201 —
-    // `SPELL_ATTR_PASSIVE`'s own probe set) is.
+    // None of the above is passive; a weapon skill (One-Handed Swords, 201) is.
     assert!(!cat.get(133).unwrap().passive);
     assert!(
         cat.get(201).unwrap().passive,
@@ -172,18 +141,13 @@ fn real_spell_catalog_reads_rank_and_passive() {
     );
 }
 
-/// The spellbook add-gate on the real build-5875 `Spell.dbc` (decision 0227; the wow-re §5's
-/// own concrete probe spells): displayable player spells pass, and the three hidden classes —
-/// a language, an armor proficiency, a weapon proficiency (all `Attributes 0xC0`) — fail. A
-/// column slip on castUI (3) or the gate bits fails loudly. Skips without client data.
 #[test]
 fn real_spell_catalog_gates_the_spellbook() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // Shown: Fireball's ranks, Frostbolt, Polymorph — ordinary cast spells (bit 0x80 clear,
-    // castUI 0).
+    // Shown: Fireball's ranks, Frostbolt, Polymorph (0x80 clear, castUI 0).
     for id in [133, 143, 145, 116, 118] {
         let d = cat.get(id).unwrap_or_else(|| panic!("spell {id}"));
         assert!(
@@ -195,8 +159,7 @@ fn real_spell_catalog_gates_the_spellbook() {
         assert_eq!(d.cast_ui, 0, "an ordinary spell reads castUI 0");
     }
 
-    // Hidden: a language, cloth/leather armor proficiency, a weapon proficiency — each
-    // `0xC0 = PASSIVE | DO_NOT_DISPLAY`, so `in_spellbook()` is false.
+    // Hidden: a language, armor and weapon proficiencies, each `0xC0 = PASSIVE | DO_NOT_DISPLAY`.
     for (id, what) in [
         (668u32, "Language: Common"),
         (9078, "Cloth"),
@@ -213,18 +176,14 @@ fn real_spell_catalog_gates_the_spellbook() {
     }
 }
 
-/// `open_lock_type` on the real Spell.dbc — the OPEN_LOCK effect (col 61 == 0x21) and its
-/// `LockType` (EffectMiscValue, col 106). Cross-verifies with `Lock.dbc`: a Copper Vein's skill
-/// slot names LockType index 3, and spell 2575 "Mining" opens exactly that. A column slip on
-/// either 61 or 106 breaks the match. Skips without client data.
+/// The OPEN_LOCK effect (column 61 == 0x21) and its `LockType` (`EffectMiscValue`, column 106): a
+/// Copper Vein's `Lock.dbc` skill slot names LockType 3, which Mining (2575) opens.
 #[test]
 fn real_spell_catalog_reads_open_lock_types() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // The gathering/lockpick openers carry SPELL_EFFECT_OPEN_LOCK; `open_lock_type` is the
-    // LockType they open — the same indices Lock.dbc's skill slots name (mining vein → 3).
     assert_eq!(
         cat.get(2575).unwrap().open_lock_type(),
         Some(3),
@@ -240,19 +199,14 @@ fn real_spell_catalog_reads_open_lock_types() {
         Some(1),
         "Pick Lock opens LockType 1"
     );
-    // A plain damage spell opens no lock (Effect[0] is not OPEN_LOCK).
     assert_eq!(
         cat.get(133).unwrap().open_lock_type(),
         None,
         "Fireball opens no lock"
     );
 
-    // **B247's data fact** (decision 1312): `LockType 13` "Open Kneeling" — what lock 43 carries,
-    // and with it every ground container from the Hyacinth Mushroom up — has TWO shipped openers
-    // that `playercreateinfo_spell` grants to every race/class, and one of them wears Blizzard's
-    // own placeholder name. The lock resolver returns the FIRST sufficient match in the
-    // known-spell array's order, so which of these it reaches is what the cast bar prints; this
-    // pins the ambiguity to the data instead of leaving it a surprise.
+    // LockType 13 (lock 43, the ground containers) has two openers every character knows; the
+    // resolver takes the first sufficient one in known-spell order, and the cast bar prints it.
     assert_eq!(cat.get(6478).unwrap().open_lock_type(), Some(13));
     assert_eq!(cat.get(6478).unwrap().name, "Opening");
     assert_eq!(cat.get(22810).unwrap().open_lock_type(), Some(13));
@@ -262,11 +216,8 @@ fn real_spell_catalog_reads_open_lock_types() {
         "the placeholder is Blizzard's own Spell.dbc string, not a formatting bug of ours"
     );
 
-    // ...and the attribute that says never to show it. `AttributesEx3 & 0x4`
-    // (`SPELL_ATTR_EX3_NO_CASTING_BAR_TEXT`) is what the cast bar must honour — 22810 carries it,
-    // 6478 does not, and that ONE bit is the only column separating two otherwise byte-identical
-    // rows. Exactly three rows in the shipped file carry it, so the whole set is pinned here: a
-    // fourth appearing means the data is not what this law was derived from.
+    // The cast bar shows no name for `AttributesEx3 & 0x4` (`SPELL_ATTR_EX3_NO_CASTING_BAR_TEXT`),
+    // the one column separating 22810 from 6478; three shipped rows carry it.
     assert!(cat.get(22810).unwrap().no_casting_bar_text());
     assert!(!cat.get(6478).unwrap().no_casting_bar_text());
     let silent: Vec<u32> = {
@@ -284,9 +235,8 @@ fn real_spell_catalog_reads_open_lock_types() {
         "6477 Opening / 22810 Opening - No Text / 26380 zzOLDSummon Mouth Tentacle Visual"
     );
 
-    // The totem (tool) and reagent columns the pre-send possession check reads (decision 0552;
-    // the ref's `0x6e4000` at SpellRec+0xA0/+0xA8 = cols 40-41 / 42-49+50-57). A column slip
-    // here silently breaks "Requires Mining Pick" / "Missing reagent: …".
+    // The tool and reagent columns the pre-send possession check reads (`0x6e4000`): totems at
+    // columns 40-41, reagents at 42-49 with their counts at 50-57.
     assert_eq!(
         cat.get(2575).unwrap().totems,
         [2901, 0],
@@ -306,30 +256,27 @@ fn real_spell_catalog_reads_open_lock_types() {
     assert_eq!(cat.get(133).unwrap().totems, [0, 0]);
 }
 
-/// The two `Effect[0]` values the client latches at spell-learn time (`0x4b25e0` → `[0xb700e4]` /
-/// `[0xb700e8]`, decision 0752), pinned against the shipped file: the cursor's skin leg refuses to
-/// show the knife unless one of them is present in the book, so a wrong constant would silently
-/// re-open the "everyone sees the skinning cursor" report — or, worse, hide it from skinners.
-/// Skips without client data.
+/// The two `Effect[0]` values the client latches at learn time (`0x4b25e0` into `[0xb700e4]` and
+/// `[0xb700e8]`); the cursor's skin leg shows the knife only when one of them is in the book.
 #[test]
 fn real_spell_catalog_pins_the_skin_latch_effects() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // Skinning (8613) — `0x4b2623: cmp [esi+0xf4], 0x5f`.
+    // Skinning (8613): `0x4b2623: cmp [esi+0xf4], 0x5f`.
     assert_eq!(
         cat.get(8613).unwrap().effects[0],
         crate::SPELL_EFFECT_SKINNING,
         "Skinning carries SPELL_EFFECT_SKINNING (95 == 0x5f)"
     );
-    // Remove Insignia (22027) — the `[0xb700e8]` half, `0x4b2632: cmp [esi+0xf4], 0x74`.
+    // Remove Insignia (22027), the `[0xb700e8]` half: `0x4b2632: cmp [esi+0xf4], 0x74`.
     assert_eq!(
         cat.get(22027).unwrap().effects[0],
         0x74,
         "Remove Insignia carries SPELL_EFFECT_SKIN_PLAYER_CORPSE (116 == 0x74)"
     );
-    // Nothing an ordinary caster starts with does — the latch stays empty for a non-skinner.
+    // Nothing an ordinary caster starts with does, so a non-skinner's latch stays empty.
     assert_ne!(
         cat.get(133).unwrap().effects[0],
         crate::SPELL_EFFECT_SKINNING
@@ -340,42 +287,30 @@ fn real_spell_catalog_pins_the_skin_latch_effects() {
     );
 }
 
-/// The **skill an opener provides** on the real Spell.dbc — the left-hand side of the client's lock
-/// satisfaction test (`0x5f850f`; decision 0752, level term corrected by wow-re
-/// `openlock-spell-store-order.md` §4a). This walk decides whether a right-click opens a lock at
-/// all, so its inputs (maxLevel 27 · baseLevel 28 · EffectDieSides 64 · EffectBaseDice 67 ·
-/// EffectDicePerLevel 70 · EffectRealPointsPerLevel 73 · EffectBasePoints 76) are pinned by
-/// *result*, against anchors whose right answers are known from the game rather than the file —
-/// the below-cap rows are §4a's own discriminating table (the values the refuted caster-level
-/// reading could not produce). Skips without client data.
+/// The left side of the client's lock test (`0x5f850f`), with the player's skill as the level
+/// term (`0x5ea690`). Its columns (27, 28, 64, 67, 70, 73, 76) are pinned by result, against
+/// values known from the game; the below-cap rows are the ones a caster-level term would miss.
 #[test]
 fn real_spell_catalog_computes_the_lock_skill_an_opener_provides() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // Pick Lock (1804): `4 + 1 + 5.0×(skill/5 − 1)` — the skill itself, exactly: a capped rogue
-    // provides 300, and a 150-skill rogue provides 150 (§4a's discriminator; the old reading
-    // said 300 for both at level 60).
+    // Pick Lock (1804): `4 + 1 + 5.0×(skill/5 − 1)`, the skill itself.
     assert_eq!(cat.get(1804).unwrap().open_lock_skill(300), Some(300));
     assert_eq!(cat.get(1804).unwrap().open_lock_skill(225), Some(225));
     assert_eq!(cat.get(1804).unwrap().open_lock_skill(150), Some(150));
-    // Mining (2575) / Herb Gathering (2366): `−1 + 1 + 5.0×(skill/5)` — the skill, quoted at
-    // baseLevel 0, so they do not lose the first rung the way Pick Lock does. 1 Mining provides
-    // 0 — the level-60-with-1-Mining bug (decision 1320) is the 300 the old reading put here.
+    // Mining (2575), Herb Gathering (2366): `−1 + 1 + 5.0×(skill/5)`; 1 Mining provides 0.
     assert_eq!(cat.get(2575).unwrap().open_lock_skill(300), Some(300));
     assert_eq!(cat.get(2575).unwrap().open_lock_skill(100), Some(100));
     assert_eq!(cat.get(2575).unwrap().open_lock_skill(1), Some(0));
     assert_eq!(cat.get(2366).unwrap().open_lock_skill(300), Some(300));
-    // Small / Large Seaforium Charge (4056 / 4075): flat `149 + 1` = 150 and `249 + 1` = 250 — and
-    // lock 92 asks for `Blasting 150`. The charge exists to open exactly that door, so the equality
-    // is the cross-check: a column slip anywhere in the walk breaks it. Skill-independent — the
-    // caster's Engineering changes nothing.
+    // Seaforium Charges (4056, 4075): a flat 150 and 250; lock 92 asks for Blasting 150.
     assert_eq!(cat.get(4056).unwrap().open_lock_skill(0), Some(150));
     assert_eq!(cat.get(4056).unwrap().open_lock_skill(300), Some(150));
     assert_eq!(cat.get(4075).unwrap().open_lock_skill(0), Some(250));
-    // The universally-known "Opening"/"Closing" family is flat 100 at every skill — which is why
-    // the Action gate, not the value test, is what keeps them off a padlocked door (decision 0752).
+    // The "Opening"/"Closing" family every character knows is a flat 100, so the Action gate,
+    // not the value test, keeps them off a padlocked door.
     for id in [3365, 6233, 6246, 6247, 6477, 6478, 21651, 21652] {
         assert_eq!(
             cat.get(id).unwrap().open_lock_skill(0),
@@ -384,21 +319,17 @@ fn real_spell_catalog_computes_the_lock_skill_an_opener_provides() {
         );
         assert_eq!(cat.get(id).unwrap().open_lock_skill(300), Some(100));
     }
-    // A spell with no OPEN_LOCK effect provides nothing.
     assert_eq!(cat.get(133).unwrap().open_lock_skill(300), None);
 }
 
-/// The cooldown/cost/range columns on the real build-5875 `Spell.dbc`, pinned 2026-07-10
-/// against the vmangos `spell_template` rows (MAX(build) ≤ 5875 per entry — the module's
-/// established cross-check). A slip on any of columns 2/19/20/31/32/36/156/157/158 fails
-/// loudly. Skips without client data.
+/// Values from vmangos `spell_template`, each entry at its highest build up to 5875.
 #[test]
 fn real_spell_catalog_reads_cooldown_cost_and_range_columns() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // Fireball r1: no cooldown, the ordinary GCD (133/1500), 30 mana, 35yd range row.
+    // Fireball r1: no cooldown, the ordinary GCD (category 133, 1500 ms), 30 mana, range row 35.
     let fireball = cat.get(133).unwrap();
     assert_eq!(
         (
@@ -416,7 +347,7 @@ fn real_spell_catalog_reads_cooldown_cost_and_range_columns() {
     assert_eq!(fireball.range_index, 35);
     assert!(!fireball.cooldown_on_event());
 
-    // Charge: category 44 with a 15 s category cooldown, rage (1), NO GCD pair, range row 95.
+    // Charge: category 44 with a 15 s category cooldown, rage (1), no GCD pair, range row 95.
     let charge = cat.get(100).unwrap();
     assert_eq!(
         (
@@ -433,8 +364,7 @@ fn real_spell_catalog_reads_cooldown_cost_and_range_columns() {
     assert_eq!(charge.power_type, 1, "Charge costs rage");
     assert_eq!(charge.range_index, 95);
 
-    // Feign Death: a 30 s own-spell RecoveryTime and SPELL_ATTR_COOLDOWN_ON_EVENT (bit 25 of
-    // attributes 0x2151400 — the on-hold family).
+    // Feign Death: a 30 s RecoveryTime and SPELL_ATTR_COOLDOWN_ON_EVENT (bit 25 of 0x2151400).
     let feign = cat.get(5384).unwrap();
     assert_eq!(feign.recovery_ms, 30_000);
     assert!(
@@ -446,24 +376,20 @@ fn real_spell_catalog_reads_cooldown_cost_and_range_columns() {
     let loh = cat.get(633).unwrap();
     assert_eq!((loh.category, loh.category_recovery_ms), (56, 3_600_000));
 
-    // ManaCostPercentage's own nonzero probe rows (the flat sample was all-zero): 370
-    // Purge r1 = 10, 527 Dispel Magic r1 = 18.
+    // ManaCostPercentage: Purge r1 (370) is 10, Dispel Magic r1 (527) 18.
     assert_eq!(cat.get(370).unwrap().mana_cost_pct, 10);
     assert_eq!(cat.get(527).unwrap().mana_cost_pct, 18);
 }
 
-/// The cast-arm targeting columns ([`COL_TARGETS`] 13 / [`COL_IMPLICIT_TARGET_A1`] 82) on the
-/// real build-5875 `Spell.dbc` — each row chosen to pin a distinct switch arm or `Targets`
-/// bit (values cross-checked against the `0x6e5250` arm map, wow-re `wave-cast.md`). Skips
-/// without client data.
+/// [`COL_TARGETS`] (13) and [`COL_IMPLICIT_TARGET_A1`] (82): one row per `0x6e5250` arm or bit.
 #[test]
 fn real_spell_catalog_reads_cast_targeting_columns() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // The implicit-target enum: 6 = single enemy (hostile bit), 1 = self, 21 = single
-    // friend (assist bit), 20 = party-around-caster (a no-op arm → mask stays 0).
+    // Implicit targets: 6 single enemy (hostile bit), 1 self, 21 single friend (assist bit), 20
+    // party around the caster (a no-op arm, so the mask stays 0).
     assert_eq!(cat.get(133).unwrap().implicit_target_a1, 6, "Fireball");
     assert_eq!(cat.get(7302).unwrap().implicit_target_a1, 1, "Ice Armor");
     assert_eq!(cat.get(5384).unwrap().implicit_target_a1, 1, "Feign Death");
@@ -478,16 +404,15 @@ fn real_spell_catalog_reads_cast_targeting_columns() {
         "Battle Shout"
     );
 
-    // The `Targets` seed mask: 0 for ordinary casts; Resurrection carries the corpse-ally
-    // bit 15, Skinning unit bit 1 + the requires-explicit-selection gate bit 10.
+    // The `Targets` seed mask: 0 for ordinary casts; Resurrection carries the corpse-ally bit 15,
+    // Skinning unit bit 1 and the requires-explicit-selection bit 10.
     assert_eq!(cat.get(133).unwrap().targets, 0);
     assert_eq!(cat.get(6673).unwrap().targets, 0);
     assert_eq!(cat.get(2006).unwrap().targets, 0x8000, "Resurrection");
     assert_eq!(cat.get(8613).unwrap().targets, 0x402, "Skinning");
 }
 
-/// The usable-walk columns (§2a) on the real build-5875 data — one pinned row per gate
-/// family — plus the form-gate law over the real form flags. Skips without client data.
+/// The usable walk's columns (`0x6e3d60`), one row per gate family, and the real form flags.
 #[test]
 fn real_spell_catalog_reads_usable_walk_columns() {
     let data = crate::wow_data_or_skip!();
@@ -495,9 +420,9 @@ fn real_spell_catalog_reads_usable_walk_columns() {
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
     let forms = load_shapeshift_forms(&mut chain).expect("load SpellShapeshiftForm");
 
-    // Claw: cat form (1) required. Ambush: stealth form (30) + a dagger equipped + the
-    // only-stealthed attribute. Execute: battle/berserker stances + a melee weapon +
-    // the target's healthless-20% aura state. Revenge: the caster's defense state.
+    // Claw: cat form (1). Ambush: stealth (form 30), a dagger and the only-stealthed attribute.
+    // Execute: battle or berserker stance and the target's below-20% aura state. Revenge: the
+    // caster's defense state.
     let claw = cat.get(1082).unwrap();
     assert_eq!(claw.stances, 0x1);
     let ambush = cat.get(8676).unwrap();
@@ -514,17 +439,15 @@ fn real_spell_catalog_reads_usable_walk_columns() {
     assert_eq!((execute.stances, execute.target_aura_state), (0x50000, 2));
     assert_eq!(cat.get(6572).unwrap().caster_aura_state, 1, "Revenge");
 
-    // Leg 5, the combo-point gate (0869): Overpower carries NO aura state — its window rides
-    // `AttributesEx` b20 (`FINISHING_MOVE_DAMAGE`) exactly like the rogue/druid finishers, which
-    // is why the aura-state legs alone left it permanently lit. Every rank, the finishers with
-    // it, and the neighbouring warrior abilities as the control.
+    // The combo-point gate (`0x6e3e7a`): Overpower has no aura state; its window rides
+    // `AttributesEx` bit 20 (`FINISHING_MOVE_DAMAGE`) like the finishers.
     for rank in [7384, 7887, 11584, 11585] {
         let op = cat.get(rank).unwrap();
         assert!(op.needs_combo_points(), "Overpower {rank}");
         assert_eq!(
             (op.caster_aura_state, op.target_aura_state),
             (0, 0),
-            "Overpower {rank} has no aura-state gate — leg 5 is all that holds it"
+            "Overpower {rank} has no aura-state gate — the combo-point gate is all that holds it"
         );
     }
     for finisher in [
@@ -556,16 +479,13 @@ fn real_spell_catalog_reads_usable_walk_columns() {
     );
     assert_eq!(cat.get(130).unwrap().reagents[0], (17056, 1), "Slow Fall");
 
-    // The form flags: warrior Battle Stance (17) is a *stance* (flags1 bit 0), druid Cat
-    // Form (1) is a true shapeshift — the actAsShifted fork's data.
+    // Battle Stance (17) is a stance (flags1 bit 0), Cat Form (1) a true shapeshift.
     assert!(forms.get(&17).unwrap().is_stance());
     assert!(!forms.get(&1).unwrap().is_stance());
-    // The bonus-bar column still reads through the richer row (Cat → page 1).
     assert_eq!(forms.get(&1).unwrap().bonus_bar, 1);
 
-    // The form-gate law on the real rows: Claw usable in cat, not unshifted; Fireball
-    // usable unshifted AND in Battle Stance (a stance), not in Cat Form (a shapeshift);
-    // Execute usable in Battle (17), not in Defensive (18).
+    // Claw in cat only; Fireball unshifted and in a stance, not in Cat Form; Execute in Battle
+    // (17), not in Defensive (18).
     assert!(claw.usable_in_form(1, false));
     assert!(!claw.usable_in_form(0, false));
     let fireball = cat.get(133).unwrap();
@@ -575,10 +495,9 @@ fn real_spell_catalog_reads_usable_walk_columns() {
     assert!(execute.usable_in_form(17, true));
     assert!(!execute.usable_in_form(18, true));
 
-    // Ghost Wolf on the real rows (the shaman lockout, verified 2026-07-31): form 16 is a true
-    // shapeshift and cancelable; the spell carries NOT_SHAPESHIFT (bit 16) AND the stance-bar
-    // exclusion (ex2 0x2 — the shipped carrier: a shaman gets no stance bar). In the form,
-    // an ordinary spell refuses 0x3d; a form-requiring spell out of its form refuses 0x56.
+    // Ghost Wolf: form 16 is a cancelable true shapeshift; the spell carries NOT_SHAPESHIFT (bit
+    // 16) and the stance-bar exclusion (`AttributesEx2 & 0x2`: a shaman gets no stance bar). In
+    // the form an ordinary spell refuses 0x3d; a form spell out of its form refuses 0x56.
     let ghost_wolf = cat.get(2645).unwrap();
     assert_eq!(ghost_wolf.shapeshift_form, Some(16));
     assert_ne!(ghost_wolf.attributes & 0x1_0000, 0);
@@ -605,15 +524,12 @@ fn real_spell_catalog_reads_usable_walk_columns() {
     assert_eq!(FormRefusal::NotShapeshift.reason(), 0x3d);
     assert_eq!(FormRefusal::OnlyShapeshift.reason(), 0x56);
 
-    // The active-action toggle's raw-column gate (wow-re shapeshift-plaincast-toggle.md):
-    // Ghost Wolf carries a nonzero ActiveIconID, so its button press-again cancels; Battle
-    // Stance carries 0, which is what keeps a stance un-cancelable on the plain paths.
+    // The active-action toggle (`0x4e563c`): Ghost Wolf's nonzero ActiveIconID lets a second
+    // press cancel it; Battle Stance's 0 keeps a stance up on the plain paths.
     assert_ne!(ghost_wolf.active_icon_id, 0);
     assert_eq!(cat.get(2457).unwrap().active_icon_id, 0, "Battle Stance");
 
-    // The form's AttackIconID column (field 13, `0x4e6870`'s `+0x34` read — wow-re
-    // `action-spell-icon-apis.md` §3.3), resolved through SpellIcon.dbc at load: Cat Form
-    // carries its own attack face, Ghost Wolf's column is 0 → the weapon fall-through.
+    // AttackIconID (column 13, `0x4e6870`): Cat Form has its own, Ghost Wolf's 0 means the weapon.
     assert_eq!(
         forms.get(&1).unwrap().attack_icon.as_deref(),
         Some("Interface\\Icons\\Ability_Druid_CatFormAttack")
@@ -621,10 +537,6 @@ fn real_spell_catalog_reads_usable_walk_columns() {
     assert_eq!(wolf_row.attack_icon, None);
 }
 
-/// The tooltip-arc columns (decision 0274 P2) on the real build-5875 `Spell.dbc`, pinned
-/// 2026-07-10: description/aura-description text, DurationIndex/CastingTimeIndex/ProcChance,
-/// and the per-effect arrays — end-to-end through the new [`load_spell_cast_times`]/
-/// [`load_spell_durations`] catalogs. Skips without client data.
 #[test]
 fn real_spell_catalog_reads_tooltip_columns() {
     let data = crate::wow_data_or_skip!();
@@ -633,9 +545,7 @@ fn real_spell_catalog_reads_tooltip_columns() {
     let cast_times = load_spell_cast_times(&mut chain).expect("load SpellCastTimes");
     let durations = load_spell_durations(&mut chain).expect("load SpellDuration");
 
-    // Fireball r1: the description's own opening line, and its real DoT-tail duration — it is
-    // NOT an "instant, no duration" spell (the description literally says "over $d": a 2 s
-    // apply-aura tick, effect slot 1, running the full 4 s tail).
+    // Fireball r1 has a real 4 s damage-over-time tail ("over $d"), a 2 s tick in effect slot 1.
     let fireball = cat.get(133).unwrap();
     assert!(
         fireball
@@ -673,8 +583,7 @@ fn real_spell_catalog_reads_tooltip_columns() {
         "Fireball's periodic-damage tail: SPELL_AURA_PERIODIC_DAMAGE ticking every 2s"
     );
 
-    // Frost Armor: a real 30-minute buff, an instant cast, a nonempty short aura blurb, and its
-    // own description names the exact chill-proc spell (6136) its EffectTriggerSpell[1] holds.
+    // Frost Armor: 30 minutes, instant, its description naming the chill proc 6136.
     let frost_armor = cat.get(168).unwrap();
     assert!(frost_armor
         .aura_description
@@ -693,16 +602,13 @@ fn real_spell_catalog_reads_tooltip_columns() {
         "the chill proc the description text itself names"
     );
 
-    // Fire Blast: a direct-damage spell with no aura component at all — empty aura text, no
-    // duration row.
+    // Fire Blast has no aura: no aura text and no duration row.
     let fire_blast = cat.get(2136).unwrap();
     assert_eq!(fire_blast.aura_description, None);
     assert_eq!(fire_blast.duration_index, 0);
     assert!(durations.get(0).is_none(), "no row 0 in SpellDuration.dbc");
 
-    // Auto Shot / Feign Death: the signed EffectBasePoints sentinel (-1, weapon-damage/no
-    // fixed roll) actually round-trips through i32 — a column slip to unsigned would read
-    // 4294967295 here instead.
+    // Auto Shot and Feign Death: the signed EffectBasePoints sentinel -1, no fixed roll.
     assert_eq!(cat.get(75).unwrap().effect_base_points[0], -1, "Auto Shot");
     assert_eq!(
         cat.get(5384).unwrap().effect_base_points[0],
@@ -711,18 +617,9 @@ fn real_spell_catalog_reads_tooltip_columns() {
     );
 }
 
-/// The combat-initiation classes on the real build-5875 `Spell.dbc` — the three accessor masks
-/// the cast seam's queue/attack-start logic keys on ([`SpellDisplay::on_next_swing`] `0x404`,
-/// [`SpellDisplay::initiates_auto_attack`] adding `AttributesEx & 0x200`, and its GO-deferred
-/// complement [`SpellDisplay::initiates_auto_attack_at_go`] on `AttributesEx2 & 0x100000`),
-/// pinned against the vmangos `spell_template` rows read at decision time (2026-07-14). A column
-/// slip or a mask slip fails loudly. Skips without client data.
-///
-/// **The bit20 column is why this test was rewritten** (decision 1593). It used to assert
-/// `attributes_ex2 & 0x100000 == 0` *for each of the ten spells listed here* and read that as
-/// "no spell carries the bit, so the deferred GO-time start is unbuilt". Ten warrior/mage rows
-/// are not a census: the real file carries it on 36. The census below is the check that claim
-/// needed, and it is now the thing that would catch the bit going dormant for real.
+/// The attack-start masks, rows from vmangos: [`SpellDisplay::on_next_swing`] (`0x404`),
+/// [`SpellDisplay::initiates_auto_attack`] (adding `AttributesEx & 0x200`) and
+/// [`SpellDisplay::initiates_auto_attack_at_go`] (`AttributesEx2 & 0x100000`).
 #[test]
 fn real_spell_catalog_classifies_combat_initiation() {
     let data = crate::wow_data_or_skip!();
@@ -737,12 +634,11 @@ fn real_spell_catalog_classifies_combat_initiation() {
         (772, "Rend", false, true, false),           // Ex 0x8000200
         (7386, "Sunder Armor", false, true, false),  // Ex 0x8000200
         (1464, "Slam", false, true, false),          // Ex 0x8000200
-        (100, "Charge", false, false, false),        // Ex 0x400 — neither bit, and bit20 CLEAR
+        (100, "Charge", false, false, false),        // Ex 0x400: neither bit, bit 20 clear
         (6673, "Battle Shout", false, false, false), // Ex 0x0
         (6603, "Attack", false, false, false),       // the auto-attack pseudo-spell itself
         (133, "Fireball", false, false, false),      // an ordinary cast
-        // The GO-deferred class: bit20 SET, so the send-time tail is suppressed and the start
-        // waits for `SMSG_SPELL_GO` (`0x6e83c0`). Every stealth opener and positional strike.
+        // The GO-deferred class: bit 20 set, so the attack starts at `SMSG_SPELL_GO` (`0x6e83c0`).
         (53, "Backstab", false, false, true), // Attributes 0x50010, Ex 0x8000200, Ex2 0x100000
         (703, "Garrote", false, false, true),
         (8676, "Ambush", false, false, true),
@@ -750,12 +646,9 @@ fn real_spell_catalog_classifies_combat_initiation() {
         (5221, "Shred", false, false, true),
         (6785, "Ravage", false, false, true),
         (9005, "Pounce", false, false, true),
-        (20271, "Judgement", false, false, true), // Ex 0x0 — bit20 is its ONLY initiation bit
-        // The hunter's instant shots (bug B280): `Attributes 0x00010002` (ranged slot),
-        // `AttributesEx 0`, `AttributesEx2 0x00020000` — bit 17, vmangos
-        // `SPELL_ATTR_EX2_DO_NOT_RESET_COMBAT_TIMERS`, the shot-weaving bit, and NOT bit 20.
-        // So no client attack-start of either kind fires for them; casting one does not begin
-        // Auto Shot, which is what 0994 §4 recorded and what this pins in data.
+        (20271, "Judgement", false, false, true), // Ex 0x0: bit 20 is its only initiation bit
+        // The hunter's instant shots carry `AttributesEx2` bit 17 (`DO_NOT_RESET_COMBAT_TIMERS`),
+        // not bit 20, and no other initiation bit, so neither attack start fires for them.
         (1978, "Serpent Sting", false, false, false),
         (3044, "Arcane Shot", false, false, false),
         (2643, "Multi-Shot", false, false, false),
@@ -784,17 +677,14 @@ fn real_spell_catalog_classifies_combat_initiation() {
             "{name} ({id}) initiates_auto_attack_at_go (Ex2 {:#x})",
             d.attributes_ex2
         );
-        // The two halves are mutually exclusive by construction — bit20 suppresses the send-time
-        // tail — so no spell may ever start the attack twice.
+        // Bit 20 suppresses the send-time start, so no spell starts the attack twice.
         assert!(
             !(d.initiates_auto_attack() && d.initiates_auto_attack_at_go()),
             "{name} ({id}) may not start the auto-attack at BOTH the send and the GO"
         );
     }
 
-    // The census the old ten-row assertion stood in for. 36 rows carry bit20 in the shipped file,
-    // and every one of them is a stealth opener, a positional strike or Judgement — the class
-    // whose attack-start has to wait for the server to resolve the strike.
+    // 36 shipped rows carry bit 20, every one an opener, a positional strike or Judgement.
     let deferred: Vec<(u32, &str)> = cat
         .iter()
         .filter(|(_, d)| d.initiates_auto_attack_at_go())
@@ -827,18 +717,15 @@ fn real_spell_catalog_classifies_combat_initiation() {
     );
 }
 
-/// **`modalNextSpell` — `Spell.dbc` column 38** on the real build-5875 file (decision 1597, bug
-/// B280). This is the column that makes casting a hunter shot start Auto Shot, so a column slip
-/// here is a silently-broken hunter; and the shape of the census is itself the evidence that the
-/// column is the one wow-re named — non-zero on 57 of 22357 rows, 52 of those naming spell 75.
-/// Skips without client data.
+/// `modalNextSpell`, column 38, which `0x6e7447` reads to start Auto Shot after a hunter shot:
+/// nonzero on 57 of 22357 rows, 52 of them naming spell 75.
 #[test]
 fn real_spell_catalog_reads_modal_next_spell() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // Rank 1 of each hunter shot, and the two spells that terminate the chain.
+    // Rank 1 of each hunter shot.
     for (id, name, next) in [
         (1978u32, "Serpent Sting", 75u32),
         (3044, "Arcane Shot", 75),
@@ -849,7 +736,7 @@ fn real_spell_catalog_reads_modal_next_spell() {
         (3043, "Scorpid Sting", 75),
         (3674, "Black Arrow", 75),
         (14274, "Distracting Shot", 75),
-        // Auto Shot's own column 38 is 0 — the chain is one hop, and cannot loop.
+        // Auto Shot's own column 38 is 0: the chain is one hop and cannot loop.
         (75, "Auto Shot", 0),
         // A melee strike and an ordinary cast carry nothing here.
         (78, "Heroic Strike", 0),
@@ -864,9 +751,6 @@ fn real_spell_catalog_reads_modal_next_spell() {
         );
     }
 
-    // The census — and the reason to believe the column map. A wrong column would not land on a
-    // 57-row population that is 91 % one value, and that value the spell every one of those rows
-    // exists to resume.
     let chained: Vec<(u32, u32)> = cat
         .iter()
         .filter(|(_, d)| d.modal_next_spell != 0)
@@ -883,7 +767,7 @@ fn real_spell_catalog_reads_modal_next_spell() {
         to_auto_shot, 52,
         "52 of the 57 name Auto Shot (the rest: three (TEST) bow shot rows → 59, two Minigun → 23675)"
     );
-    // Nothing points at a spell that would chain onward — the one-hop property, in data.
+    // Nothing points at a spell that chains onward: one hop, in data.
     for &(id, next) in &chained {
         let onward = cat.get(next).map(|d| d.modal_next_spell).unwrap_or(0);
         assert!(
@@ -893,11 +777,7 @@ fn real_spell_catalog_reads_modal_next_spell() {
     }
 }
 
-/// The crafting columns (decision 0437) on the real build-5875 `Spell.dbc`: `EffectItemType`
-/// (103-105) and `RequiresSpellFocus` (15), cross-checked against the live vmangos
-/// `spell_template` rows queried at pin time (2963 → creates 2996, 2738 → 2845, 3920 → 8067 with
-/// BasePoints[0]=199; 2538 Charred Wolf Meat → focus 4 Cooking Fire; 2738 Copper Axe → focus 1 Anvil).
-/// A column slip fails loudly. Skips without client data.
+/// `EffectItemType` (columns 103-105) and `RequiresSpellFocus` (15); values from vmangos.
 #[test]
 fn real_crafting_columns_read_created_item_and_focus() {
     let data = crate::wow_data_or_skip!();
@@ -911,7 +791,7 @@ fn real_crafting_columns_read_created_item_and_focus() {
         (2330, 118, 0),
         (2738, 2845, 1), // Blacksmithing needs the Anvil (focus 1)
         (3920, 8067, 0),
-        (2538, 2679, 4),
+        (2538, 2679, 4), // Cooking needs a Cooking Fire (focus 4)
     ] {
         let d = cat.get(spell).expect("recipe in the catalog");
         assert_eq!(
@@ -922,7 +802,7 @@ fn real_crafting_columns_read_created_item_and_focus() {
         assert_eq!(d.requires_spell_focus, focus, "spell {spell} focus");
     }
 
-    // Crafted Light Shot's 200-per-craft: BasePoints[0]=199, DieSides[0]=1 → made = 199+1.
+    // Crafted Light Shot makes 200 a craft: BasePoints 199 plus DieSides 1.
     let shots = cat.get(3920).expect("Crafted Light Shot");
     assert_eq!(shots.effect_base_points[0], 199);
     assert_eq!(shots.effect_die_sides[0], 1);
@@ -938,11 +818,9 @@ fn real_crafting_columns_read_created_item_and_focus() {
     }
 }
 
-/// The two tooltip-law reads added for the 2026-07-25 spellbook reports (decision 0620), on pure
-/// data — no client install needed.
 #[test]
 fn the_tooltip_gates_read_effect_and_mask() {
-    // §3.4: the cast|cooldown line goes on the ATTRIBUTE bit or on Effect[0] ∈ {47, 78}.
+    // `0x52eb15`: the cast and cooldown line is omitted for the passive bit or Effect[0] 47 or 78.
     let plain = SpellDisplay::default();
     assert!(!plain.tooltip_omits_cast_line());
     let attribute_passive = SpellDisplay {
@@ -950,7 +828,7 @@ fn the_tooltip_gates_read_effect_and_mask() {
         ..Default::default()
     };
     assert!(attribute_passive.tooltip_omits_cast_line());
-    // 6603 "Attack"'s shape: Effect[0] = 78, attributes 0x10 (NOT the passive bit).
+    // 6603 "Attack"'s shape: Effect[0] 78, attributes 0x10, not the passive bit.
     let auto_attack = SpellDisplay {
         effects: [78, 0, 0],
         attributes: 0x10,
@@ -963,27 +841,11 @@ fn the_tooltip_gates_read_effect_and_mask() {
         ..Default::default()
     };
     assert!(trade_skill.tooltip_omits_cast_line());
-
-    // §3-EQUIPITEM's naming rule moved to `ItemSubClassCatalog::requirement_name`, where the
-    // vocabulary it reads lives — see `itemsubclass::tests` for its coverage against the real DBCs.
 }
 
-/// The **main-hand auto-pick** family (`Attributes & 0x200`, decision 1552), against the real
-/// 5875 file. `ArmCast 0x6e5250` reads this bit to skip the item-targeting cursor and bind the
-/// equipped main hand instead, so the client's behaviour rests on the family being exactly what
-/// the app assumes: a set of temporary weapon imbues, each already an item-target spell.
-///
-/// **vmangos is not the authority for this census and gets it wrong.** Its `spell_template` keeps
-/// a row per *build*: mage Feedback (13896, 19271-19275) and druid Omen of Clarity carried this
-/// exact shape — effect 54, `Targets 0x10`, `Attributes 0x50200` — at builds 4375/4449, and both
-/// had been rewritten into plain auras with the bit CLEAR by build 5302. A `GROUP BY entry` over
-/// that table hands back the early row and inflates the family to 28. The shipped file is the
-/// authority, and it says four names.
-///
-/// The app's resolver takes the shortcut of only handling a word the item arm fully discharges
-/// (`Targets` exactly `0x10`). That is byte-equivalent only while no row mixes the attribute with
-/// another target bit — which is what the `0x10` assertion below pins. If a row ever does, this
-/// fails here rather than silently sending an unbound cast.
+/// The main-hand auto-pick family (`Attributes & 0x200`): `ArmCast` (`0x6e5250`) binds the
+/// equipped main hand instead of arming the item cursor. vmangos keeps a row per build, so a
+/// `GROUP BY entry` also returns pre-5302 Feedback and Omen of Clarity rows and counts 28.
 #[test]
 fn real_main_hand_autopick_family() {
     let data = crate::wow_data_or_skip!();
@@ -1007,8 +869,7 @@ fn real_main_hand_autopick_family() {
             "spell {id} ({}) is not a temporary weapon enchant",
             d.name
         );
-        // The auto-pick bypasses `0x495d60` entirely, so an equipped-item gate on one of these
-        // rows would be a gate the client never runs. None carries one.
+        // The auto-pick bypasses `0x495d60`, so an equipped-item gate here would never run.
         assert_eq!(
             (
                 d.equipped_item_subclass_mask,
@@ -1030,25 +891,16 @@ fn real_main_hand_autopick_family() {
         ],
         "in 5875 the family is the four shaman weapon imbues and nothing else"
     );
-    // Windfury TOTEM is not in it — it is a totem summon with no target word at all. Worth
-    // pinning because the report that prompted 1552 named it (ledger B308), and the fix would
-    // look wrong if it had ever needed one.
+    // Windfury Totem is not in it: a totem summon with no target word at all.
     let wf_totem = cat.get(8512).expect("Windfury Totem");
     assert!(!wf_totem.targets_main_hand_item());
     assert_eq!(wf_totem.targets, 0, "a totem summon binds nothing");
 }
 
-/// **The prospecting leg of `0x495d60` is dead on 5875 data** — the fact two cast-failure
-/// argument arms rest on not being written (decision 2292). That validator's effect loop has a
-/// third leg past the two enchant ones: `0x495df1 jne 0x495f36` falls into
-/// `0x495f39 cmp DWORD PTR [eax],0x7f`, and inside it sit the only image-wide raises of
-/// `SPELL_FAILED_PROSPECT_NEED_MORE` (`0x49614e`) and `SPELL_FAILED_MIN_SKILL` (`0x496128`).
-/// vmangos sends neither reason from anywhere, so if no shipped spell carries
-/// [`SPELL_EFFECT_PROSPECTING`] there is no route to either message at all — and none does.
-///
-/// This lives in the formats crate rather than beside the arms because it is a claim about the
-/// **data**: if a data set ever ships a prospecting spell, this fails and names the two arms that
-/// just came alive. Skips without client data.
+/// `0x495d60`'s third effect leg (`0x495df1 jne 0x495f36` into `0x495f39`, effect `0x7f`) holds
+/// the only raises of `SPELL_FAILED_PROSPECT_NEED_MORE` (`0x49614e`) and `SPELL_FAILED_MIN_SKILL`
+/// (`0x496128`); vmangos sends neither, so with no shipped [`SPELL_EFFECT_PROSPECTING`] spell
+/// neither message can appear.
 #[test]
 fn real_prospecting_effect_is_absent_from_5875() {
     let data = crate::wow_data_or_skip!();
@@ -1071,7 +923,7 @@ fn real_prospecting_effect_is_absent_from_5875() {
             );
         }
     }
-    // The scan covering nothing would pass just as quietly, so pin the shape of the file too.
+    // A scan that read nothing would pass too, so pin the row count.
     assert_eq!(
         slots,
         22357 * 3,
@@ -1079,16 +931,9 @@ fn real_prospecting_effect_is_absent_from_5875() {
     );
 }
 
-/// The item-target family and its gate columns (decision 0923), against the real 5875 file. The
-/// reference's `TargetingWantsItem 0x6e6330` is `flag_word & 0x4010`, and on shipped data those
-/// two bits are **never** mixed with a unit bit — the whole family is `Targets` exactly `0x10`
-/// (the enchant/poison/stone/scope arm, this slice) or exactly `0x4000` (the OPEN_LOCK arm, whose
-/// lock machinery is a separate one). That disjointness is what lets the resolver fork on the
-/// bare word instead of running the reference's bind walk to exhaustion.
-///
-/// The gate columns are the three `0x495d60` reads, pinned on rows whose answer is checkable by
-/// eye: an armor enchant names its `InventoryType` slot (bracer → 9, chest → 5 | robe 20) while a
-/// weapon enchant/poison names a class+subclass instead and leaves the type mask 0.
+/// `TargetingWantsItem` (`0x6e6330`) is `flag_word & 0x4010`, bits that never mix with a unit
+/// bit on shipped data: `Targets` is exactly `0x10` (enchants, poisons, stones, scopes) or
+/// `0x4000` (OPEN_LOCK), so the resolver forks on the bare word. `0x495d60` reads the gate columns.
 #[test]
 fn real_item_target_family_and_its_gate_columns() {
     let data = crate::wow_data_or_skip!();
@@ -1120,13 +965,9 @@ fn real_item_target_family_and_its_gate_columns() {
     );
     assert_eq!(locked_only, 103, "Targets == 0x4000 — the OPEN_LOCK family");
 
-    // The OPEN_LOCK family's **implicit arm**, which is what turns its bare `0x4000` into the word
-    // both click seams read (decision 0939). The app's `cast_target_mask` ORs `0x800` for arm 23
-    // and `TF_UNIT` for arm 25, so this census is the data behind "a lock word is `0x4000` or
-    // `0x4800`, and either way `& 0x4010` and `& 0x4800` are *both* nonzero" — the overlap that
-    // lets one armed cursor answer the bag click and the world click. Pick Lock 1804 is one of the
-    // 100 (live-probed: it arms `0x4000` and both seams take it). If this distribution moves, the
-    // seam that stops being reachable fails here first.
+    // The OPEN_LOCK implicit arm: `cast_target_mask` ORs `0x800` for arm 23 and `TF_UNIT` for arm
+    // 25, so a lock word is `0x4000` or `0x4800`, nonzero under both `& 0x4010` and `& 0x4800`,
+    // and one armed cursor answers both the bag click and the world click.
     let mut arms = std::collections::BTreeMap::<u32, usize>::new();
     for (_, d) in cat.iter().filter(|(_, d)| d.targets == 0x4000) {
         *arms.entry(d.implicit_target_a1).or_default() += 1;
@@ -1145,8 +986,7 @@ fn real_item_target_family_and_its_gate_columns() {
         arms.get(&23).copied().unwrap_or(0) >= 100,
         "the family is overwhelmingly arm 23, whose overlay is TARGET_FLAG_GAMEOBJECT: {arms:?}"
     );
-    // And no row in the whole file reaches the GameObject seam by `Targets` alone — bit 11 is
-    // something the implicit arm puts on the word, never a column value.
+    // Bit 11 comes only from the implicit arm, never from the `Targets` column.
     assert_eq!(
         cat.iter().filter(|(_, d)| d.targets & 0x800 != 0).count(),
         0,
@@ -1158,7 +998,7 @@ fn real_item_target_family_and_its_gate_columns() {
     assert_eq!(bracer.targets, 0x10);
     assert_eq!(bracer.equipped_item_class, 4);
     assert_eq!(bracer.equipped_item_inventory_type_mask, 1 << 9);
-    // Chest enchant: CHEST(5) or ROBE(20) — the mask that makes a cloth robe legal.
+    // Chest enchant: CHEST(5) or ROBE(20), so a cloth robe is legal.
     let chest = cat.get(7443).unwrap();
     assert_eq!(
         chest.equipped_item_inventory_type_mask,
@@ -1175,11 +1015,8 @@ fn real_item_target_family_and_its_gate_columns() {
         (2, 0x2a5f3, 0)
     );
 
-    // The reference's gate walks all THREE effect slots looking for an enchant effect
-    // (`0x495d60`'s loop, `495de4`–`496050`); [`SpellDisplay`] carries only slot 0. That is
-    // byte-equivalent on shipped data and this is why: across the whole item-target family, not
-    // one row puts its enchant effect anywhere but slot 0. Read raw, since the catalog itself
-    // only keeps `effects[0]`.
+    // The reference walks all three effect slots for an enchant (`0x495de4`-`0x496050`), while
+    // `SpellDisplay` keeps slot 0: no item-target row has its enchant elsewhere. Read raw.
     let raw = chain.read_file(SPELL).expect("Spell.dbc");
     let set = parse(&raw, spell_schema(), "Spell.dbc").expect("parse Spell.dbc");
     let is_enchant = |e: u32| {
@@ -1195,25 +1032,20 @@ fn real_item_target_family_and_its_gate_columns() {
         assert!(
             is_enchant(effects[0]) || !(is_enchant(effects[1]) || is_enchant(effects[2])),
             "spell {} hides its enchant effect outside slot 0 ({effects:?}) — the one-slot read \
-             in `ui_action::targeting::item_target_refusal` would miss it",
+             in `spell::targeting::item_bind_verdict` would miss it",
             u32_at(r, 0).unwrap_or(0)
         );
     }
 }
 
-/// The 0948 §5's flagged data questions, pinned on the real 5875 data (`gcd-power-gate.md`
-/// §2.1): the SpellCategory flags-bit-0x2 wildcard set is EXACTLY {351} — wand Shoot's category
-/// (the whole-bar swing sweep the store's wildcard leg implements) — and the `{cat=0, time≠0}`
-/// GCD-source shape (which would arm a category-0 GCD node matching every category-0 press) has
-/// NO player-castable carrier: every such row is an NPC/internal spell. A data change here means
-/// the store's predicates need re-judging, loudly.
+/// `GetCooldownInfo` (`0x6e13e0`): the `SpellCategory` flags `0x2` wildcard is wand Shoot's
+/// category 351, the whole-bar swing sweep the cooldown store's wildcard leg implements.
 #[test]
 fn gcd_wildcard_and_shape_corners_hold_on_the_real_data() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("catalog");
 
-    // The wildcard set: exactly wand Shoot's 351, resolved onto the display at load.
     let shoot = cat.get(5019).expect("wand Shoot");
     assert_eq!(shoot.category, 351);
     assert!(
@@ -1232,8 +1064,8 @@ fn gcd_wildcard_and_shape_corners_hold_on_the_real_data() {
         );
     }
 
-    // Scroll of Armor's spell: the {cat≠0, time=0} shape the corrected refusal predicate now
-    // locks during a GCD (the pressed spell's own time is never consulted).
+    // Scroll of Armor's spell: the {cat≠0, time=0} shape, which a GCD locks, since the pressed
+    // spell's own time is never consulted.
     let scroll = cat.get(8091).expect("Scroll of Armor's spell");
     assert_eq!(
         (scroll.start_recovery_category, scroll.start_recovery_ms),
@@ -1241,19 +1073,15 @@ fn gcd_wildcard_and_shape_corners_hold_on_the_real_data() {
     );
 }
 
-/// The cost columns on the REAL 5875 data (decision 1074, B192): the health power type
-/// (−2 as `0xFFFFFFFE`), Bloodrage's pct-only shape, Health Funnel's `manaPerSecond`, the cast
-/// cell's attr rows, and the verified NEGATIVE that keeps columns 33/35 unparsed. Skips without
-/// client data.
+/// The health power type is -2, read as `0xFFFFFFFE`.
 #[test]
 fn real_spell_catalog_cost_columns() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = crate::load_spell_catalog(&mut chain).expect("Spell.dbc");
 
-    // Life Tap, EVERY rank: health type and NO cost columns at all — the client's own file,
-    // against the folk memory of a printed health cost (that is 2.x's change; 1.12 carries the
-    // trade in the description text). The cost cell stays EMPTY, which is the reference render.
+    // Life Tap, every rank: health type and no cost at all, so the cost cell stays empty; 1.12
+    // states the trade in the description.
     for id in [1454u32, 1455, 1456, 11687, 11688, 11689] {
         let d = cat.get(id).unwrap();
         assert_eq!(
@@ -1267,7 +1095,7 @@ fn real_spell_catalog_cost_columns() {
             "Life Tap {id}"
         );
     }
-    // Bloodrage: pct-ONLY health cost — the resolved-cost law's health-pool lane (B192).
+    // Bloodrage: a percentage-only health cost.
     let bloodrage = cat.get(2687).unwrap();
     assert_eq!(
         (
@@ -1277,18 +1105,16 @@ fn real_spell_catalog_cost_columns() {
         ),
         (0xFFFF_FFFE, 0, 20)
     );
-    // Health Funnel: flat health + per-second — the `_PER_TIME` composite's live customer — and
-    // channeled, so its cast cell reads "Channeled".
+    // Health Funnel: flat health plus per second (the `_PER_TIME` line), and channeled.
     let funnel = cat.get(755).unwrap();
     assert_eq!(
         (funnel.power_type, funnel.mana_cost, funnel.mana_per_second),
         (0xFFFF_FFFE, 11, 5)
     );
     assert!(funnel.tooltip_channeled());
-    // The cast cell's attr arms at their pinned rows: Heroic Strike (next melee, rage 150 wire =
-    // "15 Rage" displayed), Auto Shot and Throw (the ranged bit ALONE — Throw is not
-    // auto-repeat and still reads "Attack speed"), Mind Flay (channeled mana), Judgement
-    // (pct-only mana — the resolved flat number, never a percentage line).
+    // The cast cell's attribute arms: Heroic Strike (next melee; 150 on the wire is "15 Rage"),
+    // Auto Shot and Throw (the ranged bit alone, so Throw reads "Attack speed"), Mind Flay
+    // (channeled), Judgement (percentage-only mana, shown as the resolved number).
     let hs = cat.get(78).unwrap();
     assert_eq!((hs.power_type, hs.mana_cost), (1, 150));
     assert!(hs.on_next_swing());
@@ -1307,11 +1133,9 @@ fn real_spell_catalog_cost_columns() {
         (0, 0, 6)
     );
 
-    // The column scan, both verdicts pinned: `manaPerSecondPerLevel` (35) is all-zero across
-    // the whole file — the verified negative that keeps it unparsed — while `manaCostPerlevel`
-    // (33) is real: exactly 72 nonzero rows, all creature-cast spells (Dark Offering's is even
-    // in the health lane), which is why the per-level term is modeled in `power_cost` but
-    // dormant for player tooltips. (1074)
+    // `manaPerSecondPerLevel` (column 35) is zero on every row, so it stays unparsed;
+    // `manaCostPerlevel` (33) is nonzero on 72 creature spells, so `power_cost` applies it though
+    // no player tooltip shows it.
     let bytes = chain.read_file(super::SPELL).expect("reading Spell.dbc");
     let rs = super::parse(&bytes, super::spell_schema(), "Spell.dbc").expect("Spell.dbc");
     let mut per_level_rows = 0u32;
@@ -1340,30 +1164,10 @@ fn real_spell_catalog_cost_columns() {
     );
 }
 
-/// **The language join — and the shipped-data anomaly it uncovered.**
-///
-/// `Languages.dbc` carries no skill column and three of the thirteen name pairs do not match
-/// (Dwarvish/Dwarven, Demonic/Demon Tongue, Kalimag/Old Tongue), so the only route from a chat
-/// line's language id to the skill that gates it is the **spell** whose `Effect_1` is
-/// `SPELL_EFFECT_LANGUAGE` (wow-re `chat-language-scramble.md` §8, `0x4b2656`).
-///
-/// The mechanism is byte-verified; what it *does against shipped 5875 content* is this test's
-/// subject, and it is not what the mechanism alone suggests. **Fourteen spells declare a language
-/// and they cover only nine of the thirteen**: 813/814/815/816/817 all declare **7 (Common)**
-/// rather than their own, four of them named "(NYI)". So Demonic, Titan, Thalassian and Kalimag are
-/// unreachable through the client's own join and render fully garbled to everyone — correct 1.12.1
-/// behaviour, and the reason a language→spell map built over the whole DBC would be wrong (last row
-/// wins, so language 7 would resolve to Old Tongue and every character's Common would garble).
-///
-/// Walking the gate's *second* hop finishes the picture: of the nine, Draconic's declaring spell has
-/// no `SkillLineAbility` row, so the set a character can ever understand is exactly the **eight
-/// player languages**. Every flavour language garbles for everyone, always.
-///
-/// The pairs below are cross-checked where an independent source exists: **vmangos's
-/// `lang_description[]`** (`src/game/ObjectMgr.cpp`) hand-lists the same spell ids, so agreement on
-/// the nine is a real control — and its disagreement on 813–817's *language* is exactly the point,
-/// since the server picks a language to send while the client reads the DBC to decide what it
-/// renders.
+/// A chat language reaches its skill only through the spell whose `Effect_1` is
+/// `SPELL_EFFECT_LANGUAGE` (`0x4b2656`). On 5875, 813-817 all declare Common (7), so Demonic,
+/// Titan, Thalassian and Kalimag garble for everyone, and a language-to-spell map would resolve
+/// Common to Old Tongue; vmangos's `lang_description[]` (`ObjectMgr.cpp:84`) gives them their own.
 #[test]
 fn the_language_declaring_spells_cover_nine_of_thirteen_languages() {
     let data = crate::wow_data_or_skip!();
@@ -1371,27 +1175,25 @@ fn the_language_declaring_spells_cover_nine_of_thirteen_languages() {
     let spells = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
     let skills = crate::skill_lines::load_skill_line_catalog(&mut chain).expect("load skill lines");
 
-    // (spell, declared language, the spell's SkillLine.dbc id) — every SPELL_EFFECT_LANGUAGE row in
-    // 5875. Spell ids cross-check against vmangos `lang_description[]`; the languages are ours.
+    // (spell, declared language, SkillLine.dbc id): every SPELL_EFFECT_LANGUAGE row but 25674.
     const DECLARED: &[(u32, u32, u32)] = &[
         (668, 7, 98),     // Common
         (669, 1, 109),    // Orcish
         (670, 3, 115),    // Taurahe
         (671, 2, 113),    // Darnassian
         (672, 6, 111),    // Dwarvish
-        (813, 7, 137),    // "Thalassian (NYI)" — declares COMMON
-        (814, 7, 138),    // "Draconic (NYI)"   — declares COMMON
-        (815, 7, 139),    // Demon Tongue       — declares COMMON
-        (816, 7, 140),    // "Titan (NYI)"      — declares COMMON
-        (817, 7, 141),    // "Old Tongue (NYI)" — declares COMMON
+        (813, 7, 137),    // "Thalassian (NYI)", declaring Common
+        (814, 7, 138),    // "Draconic (NYI)", declaring Common
+        (815, 7, 139),    // Demon Tongue, declaring Common
+        (816, 7, 140),    // "Titan (NYI)", declaring Common
+        (817, 7, 141),    // "Old Tongue (NYI)", declaring Common
         (7340, 13, 313),  // Gnomish
         (7341, 14, 315),  // Troll
         (17737, 33, 673), // Gutterspeak
     ];
 
-    // The fourteenth: "Lesser Draconic (Language)" declares Draconic (11) correctly — and has **no
-    // `SkillLineAbility` row at all**, so the gate's second hop dead-ends and Draconic can never be
-    // understood either. Language 11 is reachable in the table and still always garbled.
+    // The fourteenth, "Lesser Draconic (Language)", declares Draconic (11) but has no
+    // `SkillLineAbility` row, so the gate's second hop dead-ends and Draconic always garbles.
     assert_eq!(spells.declared_language(25674), Some(11));
     assert_eq!(skills.spell_to_line(25674), None);
 
@@ -1414,10 +1216,7 @@ fn the_language_declaring_spells_cover_nine_of_thirteen_languages() {
         );
     }
 
-    // **The set a character can ever understand** — what the chat gate actually sees once both hops
-    // are walked. It is exactly the eight *player* languages, which is the result that makes the
-    // whole shipped arrangement coherent: every flavour language (Demonic, Titan, Thalassian,
-    // Kalimag, Draconic) always renders garbled, to everyone, in 1.12.1.
+    // Both hops walked, only the eight player languages can ever be understood.
     let understandable: std::collections::BTreeSet<u32> = spells
         .declared_languages()
         .filter(|(spell, _)| skills.spell_to_line(*spell).is_some())
@@ -1433,13 +1232,8 @@ fn the_language_declaring_spells_cover_nine_of_thirteen_languages() {
     assert_eq!(spells.declared_language(133), None); // Fireball
 }
 
-/// The hostility classifier ([`SpellDisplay::is_harmful`] — the client's `0x6ea280 == 2`) on the
-/// real 5875 rows, both routes: the enemy implicit target in slot A (Fireball 133, Charge 100,
-/// Sunder Armor 7386 — all `A[0] = 6`), an enemy area reached only through slot B (Frost Nova
-/// 122: `A[0] = 22` caster coordinates, `B[0] = 15` src-area enemy — harmful through B alone),
-/// and the helpful/neutral rows that must not flinch their target (Renew 139 and Healing Touch
-/// 5185 = 21 single friend, Arcane Intellect 1459 = 21, Battle Shout 6673 = 20 party area).
-/// Skips without client data.
+/// [`SpellDisplay::is_harmful`], the client's `0x6ea280 == 2`: an enemy implicit target in slot A
+/// (6), or only in slot B as Frost Nova's (A 22, the caster's spot; B 15, a source-area enemy).
 #[test]
 fn real_is_harmful_pins() {
     let data = crate::wow_data_or_skip!();
@@ -1479,23 +1273,15 @@ fn real_is_harmful_pins() {
     }
 }
 
-/// **The channel bar's naming law on the real build-5875 `Spell.dbc`** (decision 2284) — the two
-/// bits `SpellChannelStart 0x6e7550` tests, and the population that makes the default the
-/// interesting half.
-///
-/// The cast bar names its spell unless a bit forbids it; the channel bar says "Channeling" unless
-/// a bit permits it. Exactly **9** of the 323 channeled rows permit it and **2** suppress the bar
-/// outright, so "Channeling" is what a player sees for essentially every channel in the game.
-/// A column slip, or a bit read off the wrong `AttributesEx*`, fails here. Skips without client
-/// data.
+/// `SpellChannelStart` (`0x6e7550`): unlike the cast bar, the channel bar says "Channeling" unless
+/// a bit lets it name the spell, as 9 of the 323 channeled rows do; 2 suppress the bar.
 #[test]
 fn real_channel_bar_name_law() {
     let data = crate::wow_data_or_skip!();
     let mut chain = crate::open_chain(&data).expect("open chain");
     let cat = load_spell_catalog(&mut chain).expect("load Spell/SpellIcon");
 
-    // The generic leg — every rank of Blizzard, plus the other channels a player meets daily.
-    // These are the rows that read the literal word, and Blizzard is the one that prompted 2284.
+    // The generic leg: every rank of Blizzard and other everyday channels.
     for id in [
         10u32, 6141, 8427, 10185, 10186, 10187, // Blizzard, all six ranks
         5143,  // Arcane Missiles
@@ -1513,8 +1299,7 @@ fn real_channel_bar_name_law() {
         assert!(!d.no_channel_bar(), "{id} {:?} still shows a bar", d.name);
     }
 
-    // The named leg — the sharpest control wow-re names: Fishing and Mind Flay take opposite
-    // legs of the same `0x6e75a1`, and vanilla really does print one name and one generic word.
+    // The named leg: Fishing and Mind Flay take opposite legs of the same `0x6e75a1`.
     for (id, name) in [
         (7620u32, "Fishing"),
         (18248, "Fishing"),
@@ -1525,7 +1310,7 @@ fn real_channel_bar_name_law() {
         assert_eq!(d.name, name);
     }
 
-    // The suppressor — a total one, and the only two rows that carry it.
+    // The suppressor, on these two rows only.
     for id in [24322u32, 24323] {
         assert!(
             cat.get(id).expect("Blood Siphon").no_channel_bar(),
@@ -1533,7 +1318,6 @@ fn real_channel_bar_name_law() {
         );
     }
 
-    // The population, which is the law's real shape: the opt-ins are a rounding error.
     let channeled: Vec<_> = cat.iter().filter(|(_, d)| d.tooltip_channeled()).collect();
     assert_eq!(channeled.len(), 323, "channeled rows in the shipped file");
     assert_eq!(
@@ -1551,19 +1335,9 @@ fn real_channel_bar_name_law() {
     );
 }
 
-/// The talent spell-modifier gate's two columns — `SpellFamilyName` 160 and the `SpellFamilyFlags`
-/// pair 161/162 — against the shipped 5875 `Spell.dbc`.
-///
-/// Three things are asserted, and each would catch a different slip. The **family histogram** is
-/// the column pin: the eleven nonzero values are exactly the vmangos `SpellFamilyNames` set, and
-/// their counts are the shipped file's own (a one-column slip lands on 159/163, neither of which
-/// looks like this). The **popcount census** is what makes the reader's 64-iteration walk
-/// load-bearing rather than defensive — 322 rows set more than one bit, and the highest index in
-/// the whole table is 35, so the HIGH dword is live. The **three worked spells** pin the join
-/// direction: 4987 sets 12 and 33, which a low-dword-only read or a swapped pair both get wrong.
-///
-/// Numbers from wow-re `system/spell/scratch/spellmod-table-law.md` (Provenance), re-measured here
-/// off the file this catalog actually loads. Skips without client data.
+/// `SpellFamilyName` (160) and the `SpellFamilyFlags` pair (161-162): the eleven nonzero families
+/// are vmangos's `SpellFamilyNames`, 322 rows set several bits and the top bit is 35, so the high
+/// dword is live, and Cleanse (4987, bits 12 and 33) pins the pair's order.
 #[test]
 fn real_spell_family_columns_carry_the_modifier_gate() {
     let data = crate::wow_data_or_skip!();
@@ -1609,8 +1383,7 @@ fn real_spell_family_columns_carry_the_modifier_gate() {
     );
     assert_eq!(max_bit, 35, "the highest family bit index in the file");
 
-    // The three worked examples. Frostbolt spans one dword, Cleanse spans BOTH, Cure Poison lives
-    // entirely in the high one.
+    // Frostbolt spans one dword, Cleanse both, Cure Poison only the high one.
     for (id, family, bits) in [
         (116u32, 3u32, &[5u32, 19, 20, 30][..]),
         (4987, 10, &[12, 33]),
diff --git a/crates/benilla-formats/src/spells/dispel_types.rs b/crates/benilla-formats/src/spells/dispel_types.rs
index c78a9140..6338cd1e 100644
--- a/crates/benilla-formats/src/spells/dispel_types.rs
+++ b/crates/benilla-formats/src/spells/dispel_types.rs
@@ -1,23 +1,8 @@
-//! `SpellDispelType.dbc` — the name of a spell's dispel class, and the flag that decides whether
-//! the class is *named at all*.
-//!
-//! Two consumers read exactly this table: the **aura tooltip's right column** ("Magic" on Ice
-//! Armor — wow-re `tooltip-content-law.md` §3-BUFF, the aura builder `0x52f880`), and the
-//! `debuffType` return of `UnitAura`/`UnitDebuff`, which FrameXML's `DebuffTypeColor` keys the
-//! debuff border tint on. Both take the name from this row; neither hard-codes it.
-//!
-//! **The gate is `[+0x28]`, not the id.** A row is named only when its `+0x28` field is nonzero —
-//! byte-verified in wow-re, and confirmed here on the shipped file: the 11 records are `{0 "",
-//! 1 Magic, 2 Curse, 3 Disease, 4 Poison, 5 Stealth, 6 Invisibility, 7 All(M+C+D+P), 8 "Special -
-//! npc only", 9 Frenzy, 10 ZG Trinkets}` and `[+0x28]` reads **1 for ids 1–4 and 0 for every
-//! other row**. So Stealth and Invisibility have names in the file yet print nothing — the flag,
-//! not the string, is what withholds them.
-//!
-//! Record layout (11 records × 12 fields × 4 B = 0x30 stride, read off the extracted file):
-//! `ID@0`, `Name_Lang@1..8` (enUS at 1; every other locale is empty on 5875), `NameFlags@9`
-//! (`0x007F007E`, `0x003F007E` on the last two rows), the gate at `@10` (= `+0x28`), and `@11` —
-//! a second string column holding the *same* string as the name, populated on exactly the same
-//! four rows. Whatever `@11` is for, it is not what the tooltip reads; `@10` is.
+//! `SpellDispelType.dbc`: the dispel class name the aura tooltip (`0x52f880`) shows and
+//! `UnitAura`/`UnitDebuff` return as `debuffType`, which FrameXML's `DebuffTypeColor` keys the
+//! debuff border on. A row is named only when column 10 (`+0x28`) is nonzero (`0x52f906`): on 5875
+//! that is ids 1-4, so Stealth and Invisibility carry names that never print. Column 11 repeats
+//! the name on those four rows; the tooltip does not read it.
 
 use std::collections::HashMap;
 
@@ -27,16 +12,14 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 
 use crate::dbc::{parse, str_at, u32_at};
 
-/// The named dispel classes, by `Spell.dbc` `Dispel` id — a row whose `[+0x28]` gate is 0 is
-/// **absent**, so a lookup miss is exactly "this class is not named" (see the module doc).
+/// The named dispel classes by `Spell.dbc` `Dispel` id; a row the gate withholds is absent.
 #[derive(Default)]
 pub struct SpellDispelTypes {
     names: HashMap<u32, String>,
 }
 
 impl SpellDispelTypes {
-    /// The dispel class's name ("Magic"/"Curse"/"Disease"/"Poison" on 5875), or `None` when the
-    /// spell has no dispel class (`dispel == 0`) or its class is one the gate withholds.
+    /// The class name; `None` for no dispel class (0) or one the gate withholds.
     pub fn name(&self, dispel: u32) -> Option<&str> {
         self.names.get(&dispel).map(String::as_str)
     }
@@ -50,7 +33,7 @@ impl SpellDispelTypes {
     }
 }
 
-/// Load `SpellDispelType.dbc` off the patch chain, keeping only the rows the `[+0x28]` gate names.
+/// Load `SpellDispelType.dbc` off the patch chain, keeping only the rows the gate names.
 pub fn load_spell_dispel_types(chain: &mut Chain) -> Result<SpellDispelTypes> {
     let bytes = chain
         .read_file("DBFilesClient\\SpellDispelType.dbc")
@@ -82,9 +65,6 @@ pub fn load_spell_dispel_types(chain: &mut Chain) -> Result<SpellDispelTypes> {
 mod tests {
     use super::*;
 
-    /// The whole shipped table, and the gate that is the point of it: ids 1–4 name themselves,
-    /// and Stealth/Invisibility/Frenzy — which DO carry strings in the file — do not. Skips
-    /// without client data.
     #[test]
     fn real_dispel_types_name_only_what_the_gate_allows() {
         let data = crate::wow_data_or_skip!();
@@ -94,7 +74,7 @@ mod tests {
         assert_eq!(types.name(2), Some("Curse"));
         assert_eq!(types.name(3), Some("Disease"));
         assert_eq!(types.name(4), Some("Poison"));
-        // Named in the file, withheld by the gate — the whole reason we read `[+0x28]`.
+        // Named in the file, withheld by the gate.
         assert_eq!(types.name(5), None, "Stealth");
         assert_eq!(types.name(6), None, "Invisibility");
         assert_eq!(types.name(9), None, "Frenzy");
diff --git a/crates/benilla-formats/src/spells/display.rs b/crates/benilla-formats/src/spells/display.rs
index 4e534b93..a6d69f04 100644
--- a/crates/benilla-formats/src/spells/display.rs
+++ b/crates/benilla-formats/src/spells/display.rs
@@ -1,347 +1,189 @@
-//! `SpellDisplay` — one spell's display + usable-walk surface (the column pins its fields
-//! read are documented on `spells/mod.rs`'s module header, which this file's every intra-doc
-//! link points back to). Split out of `mod.rs` purely for file size — still `crate::spells`'s
-//! own type, not a separate concern.
+//! `SpellDisplay`: one spell's `Spell.dbc` row and the client predicates over it.
 
 use super::*;
 
-/// A spell's `SPELL_EFFECT_OPEN_LOCK` effect (decision 0752) — which `LockType` it opens, and
-/// which of the three effect slots carries it (so the value walk reads the right column of the
-/// per-effect arrays).
+/// A spell's `SPELL_EFFECT_OPEN_LOCK` effect: the `LockType` it opens and the slot it is in.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct OpenLock {
-    /// `EffectMiscValue` — the `LockType.dbc` index this spell opens (pick-lock 1, herbalism 2,
-    /// mining 3, "Quick Open" 10, "Open Kneeling" 13, blasting 16 …).
+    /// `EffectMiscValue`: the `LockType.dbc` id, such as pick lock 1, herbalism 2, mining 3.
     pub lock_type: u32,
     /// Which of `Effect[0..3]` is the OPEN_LOCK one.
     pub effect: usize,
 }
 
-/// One spell's display identity.
+/// One spell's `Spell.dbc` row, as the display, tooltip and cast gates read it.
 pub struct SpellDisplay {
     pub name: String,
-    /// `SpellNameSubtext` enUS (column 129, module docs) — "Rank N" for most leveled spells, a
-    /// bare descriptor ("Racial", "Passive", …) for some, or absent for a handful of unranked
-    /// spells. `None` when the column is empty ([`crate::dbc::str_at`]'s own empty-means-absent
-    /// contract) — the spellbook slot then shows no second line at all.
+    /// `SpellNameSubtext` enUS (column 129): "Rank N", even "Rank 1", or a word such as "Racial".
     pub rank: Option<String>,
-    /// The icon texture's MPQ path (`Interface\Icons\…`, extensionless as the DBC stores it);
-    /// `None` when the spell's icon id is 0/unknown (render the fallback question mark).
+    /// The icon's MPQ path, without extension; `None` for icon 0 or an id not in `SpellIcon.dbc`.
     pub icon: Option<String>,
-    /// `SpellVisual.dbc` id (column 115, module docs) — `0` = no visual chain (a silent cast).
-    /// Resolve through [`crate::SpellVisualCatalog`] for the lifecycle-stage kits.
+    /// `SpellVisual.dbc` id (column 115); 0 is a silent cast.
     pub visual: u32,
-    /// The projectile travel speed, world units/sec (column 37, module docs). `0` = instant
-    /// impact (decision 0099's `Speed==0` gate — no missile phase).
+    /// Projectile speed (column 37) in world units per second; 0 is an instant impact.
     pub speed: f32,
-    /// `Attributes` (column 6, module docs) — consumed by [`Self::ranged_attack`] (`0x2`),
-    /// [`Self::targets_main_hand_item`] (`0x200`), [`Self::in_spellbook`] (`0x20`/`0x80`),
-    /// [`Self::cooldown_on_event`] (bit 25), and the aura-bar display filter
-    /// [`Self::hidden_from_aura_bar`] (`0x80`).
+    /// `Attributes` (column 6).
     pub attributes: u32,
-    /// **`School`** (column 1, `SpellRec+0x4`) — the spell's magic school as an INDEX, not a mask.
-    /// The crowd-control exemption's school arm shifts it (`1 << School`) before testing it against
-    /// an immunity effect's `EffectMiscValue`, which is a mask (decision 1946).
+    /// `School` (column 1): an index; immunity tests `1 << School` against a school mask.
     pub school: u32,
-    /// **`Mechanic`** (column 5, `SpellRec+0x14`) — the `SpellMechanic.dbc` id for the spell as a
-    /// whole. Read by the crowd-control ladder twice over: the mechanic-immunity arm compares it,
-    /// and it is the fallback value the scanner reports when a blocking aura's own
-    /// `EffectMechanic` is 0 — which is what names the `0x8d` "Can't do that while %s" line.
+    /// `Mechanic` (column 5): the whole spell's `SpellMechanic.dbc` id.
     pub mechanic: u32,
-    /// `AttributesEx` (column 7, `SpellRec+0x1c`) — only bit `0x10000000` is consumed
-    /// ([`Self::hidden_from_aura_bar`]'s `SPELL_ATTR_EX_NO_AURA_ICON` half).
+    /// `AttributesEx` (column 7).
     pub attributes_ex: u32,
-    /// `AttributesEx2` (column 8, module docs) — bit `0x20` is consumed by
-    /// [`Self::ranged_attack`], bit 19 (`0x0008_0000`, allow-while-not-shapeshifted) by the form
-    /// gate [`Self::form_refusal`]; the stance-bar admission bits (`0x2`/`0x10`) are read raw by
-    /// `benilla::ui_shapeshift`.
+    /// `AttributesEx2` (column 8).
     pub attributes_ex2: u32,
-    /// `AttributesEx3` (column 9, `SpellRec+0x24`) — bit `0x8000` is consumed
-    /// ([`Self::melee_white_damage`]), and bits `0x400` / `0x1000000` are the equipped-item
-    /// search's **hand restriction** (main-hand-only / off-hand-only), which is where
-    /// `0x5f0c50`'s slot mask comes from (decision 1903).
+    /// `AttributesEx3` (column 9). Bits `0x400` and `0x1000000` limit the equipped-item search to
+    /// the main or the off hand (`0x5f0c50`).
     pub attributes_ex3: u32,
-    /// **`SpellFamilyName`** (column 160, `SpellRec+0x280`) — which class's talent tree may modify
-    /// this spell. `0` on 18243 of the 22357 shipped rows (creature and world spells); the rest
-    /// carry a `SpellFamilyNames` value, which for a player spell is its own class's.
-    ///
-    /// The first two of `GetSpellModifiers 0x6e6b30`'s three conjunct gates read it and nothing
-    /// else: `!= 0` (`6e6b38`), then `== [0xcecaac]`, the local player's own class family
-    /// (`6e6b46` — [`crate::ChrClasses::spell_family`]). A spell that fails either takes no
-    /// modifier at all, which is how a mage's talent stays off a warrior's ability and off every
-    /// item/creature spell in the file. wow-re `system/spell/scratch/spellmod-table-law.md` §5.1.
+    /// `SpellFamilyName` (column 160): `GetSpellModifiers` (`0x6e6b30`) applies nothing unless it
+    /// is nonzero and equals the local player's class family (`[0xcecaac]`, `0x6e6b46`).
     pub spell_family: u32,
-    /// **`SpellFamilyFlags`** (columns 161/162, `SpellRec+0x284`/`+0x288`) — the 64-bit bit-set
-    /// naming which of its family's modifier rows this spell subscribes to, low dword first.
-    ///
-    /// `GetSpellModifiers` walks **all 64 bits** with no early break and SUMS one cell per set bit
-    /// out of each table (`6e6b72`–`6e6ba6`), so a multi-bit spell accumulates several — and the
-    /// high dword is genuinely live rather than unused width: measured on the shipped 5875 file,
-    /// 1794 rows set exactly one bit, **322 set more than one**, and the highest bit index in the
-    /// whole table is **35**. Frostbolt 116 sets 5/19/20/30, Cleanse 4987 sets 12 **and 33** (it
-    /// needs both dwords), Cure Poison 526 sets 35 alone.
+    /// `SpellFamilyFlags` (columns 161-162, low dword first): the modifier rows that apply, one
+    /// summed cell per set bit over all 64; Cleanse 4987 sets bits 12 and 33.
     pub spell_family_flags: u64,
-    /// **`PreventionType`** (column 165, `SpellRec+0x294`) — which crowd-control flag refuses this
-    /// spell **locally**, before any packet: `1` = silence, `2` = pacify, `0` = neither. The
-    /// client's CC validator `0x6094f0` (called from `TryCast 0x6e4b60`, bailing at `0x6e4f42`)
-    /// reads it per spell — so `UNIT_FLAG_SILENCED` does **not** stop everything, only the rows
-    /// that declare `1`. The STUNNED arm above it carries no such gate and refuses every spell.
-    ///
-    /// **Column pinned twice** (decision 1903): the byte offset `0x294 / 4 = 165` on a 173-field,
-    /// 692-byte record, and the shipped data itself — its neighbour 164 is `DmgClass` and takes
-    /// four values where this takes three, which **Auto Shot (75)** separates decisively at
-    /// `DmgClass = 3` (RANGED) with `PreventionType = 2`. Fireball 133 → 1, Heroic Strike 78 → 2,
-    /// Attack 6603 → 0.
+    /// `PreventionType` (column 165): 1 silence, 2 pacify, 0 neither; the crowd control that
+    /// refuses the spell locally (`0x6094f0`, from `TryCast` `0x6e4b60`). A stun refuses all.
     pub prevention_type: u32,
-    /// **`modalNextSpell`** (`Spell.dbc` column 38, `SpellRec + 0x98`) — the spell this one makes
-    /// the client cast **by itself**, one server round-trip later, with no user input and no addon.
-    /// `0` for all but 57 of the 22357 shipped rows.
-    ///
-    /// `HandleCastResult 0x6e7330` — the `SMSG_CAST_RESULT` (0x130) handler — reads it for the
-    /// spell the reply names, **on success as well as failure** (`0x6e7356 cmp [ebp+0xf],0x2` /
-    /// `0x6e735a jne` sends a non-failure straight to the same block the failure path falls into
-    /// at `0x6e73eb`), provided the reply is for the in-flight cast (`0x6e7408` vs `[0xceca88]`).
-    /// Then, at `0x6e7447`:
-    ///
-    /// - `0` → nothing happens (`0x6e744f je`);
-    /// - `== [0xceac30]`, the **running** auto-repeat → the pending-cast record is re-armed and
-    ///   nothing is cast (`0x6e745d`) — which is why a second sting does not restart Auto Shot or
-    ///   reset its swing timer;
-    /// - otherwise → the client **casts it** (`0x6e74aa call 0x6e5a90` → `TryCast`), at the null
-    ///   target guid, through the ordinary ladder.
-    ///
-    /// **This is how a hunter starts shooting.** Every rank of every hunter shot — Serpent Sting,
-    /// Arcane Shot, Multi-Shot, Concussive Shot, Aimed Shot, Viper/Scorpid Sting, Black Arrow,
-    /// Distracting Shot — carries **75 (Auto Shot)** here, and Auto Shot's own column 38 is `0`, so
-    /// the chain is exactly one hop and cannot loop. The only other non-zero values in the shipped
-    /// file are three "(TEST) bow shot" rows → 59 and two `Minigun` rows → 23675 (self-referential,
-    /// absorbed by the equal-branch).
-    ///
-    /// wow-re `spell/scratch/modalnext-chain-cast.md` (§5 round, 7 agents + orchestrator byte
-    /// arbitration); benilla decision 1597. It **corrects** the reading in 0994 §4 — the client
-    /// really does not start the repeat from the sting's *own* send, and then starts it from a
-    /// *second cast it issues itself*.
+    /// `modalNextSpell` (column 38): cast by the client itself (`0x6e74aa`), at no target, when
+    /// `SMSG_CAST_RESULT` for this in-flight spell arrives, success or failure (`0x6e7330`); if
+    /// it is the running auto-repeat, that is only re-armed (`0x6e745d`). Every hunter shot
+    /// names 75, Auto Shot: that is how shooting starts.
     pub modal_next_spell: u32,
-    /// `Attributes & 0x40` (`SPELL_ATTR_PASSIVE`, module docs) — the spellbook's gray-and-refuse
-    /// gate (consumed by `benilla-ui/src/script/spellbook.rs`, decision 0216 §8).
+    /// `Attributes & 0x40`, `SPELL_ATTR_PASSIVE`: the spellbook grays it.
     pub passive: bool,
-    /// `castUI` (column 3, `SpellRec+0xc`, module docs) — the third of the spellbook add-gate's
-    /// three exclusions ([`Self::in_spellbook`]). Nonzero keeps the spell out of the book; reads
-    /// 0 for every ordinary player spell.
+    /// `castUI` (column 3): nonzero keeps the spell out of the spellbook; 0 on ordinary spells.
     pub cast_ui: u32,
-    /// `Effect[3]` (column 61 == [`COL_EFFECT_1`], module docs) — each effect's type. Slot 0 is what
-    /// almost every consumer wants (the auto-attack gate [`Self::is_melee_auto_attack`], the
-    /// tradeskill/enchant/duel classifications); the trainer's icon law is the one caller that scans
-    /// all three, hunting a learn-wrapper effect in any slot (wow-re
-    /// `system/ui/scratch/spell-icon-substitution-law.md` §1, `0x4d8fed`'s three-slot loop). Carried
-    /// as the `[T; 3]` array every other per-effect column already uses — it was a lone `effect_1`
-    /// until that scan needed the siblings.
+    /// `Effect[3]` (columns 61-63); the trainer's icon scans all three (`0x4d8fed`).
     pub effects: [u32; 3],
-    /// This spell's `SPELL_EFFECT_OPEN_LOCK` effect, or `None` if it opens no lock. The GameObject
-    /// interact-cast (decisions 0239/0752) matches it against a lock slot across the player's known
-    /// spells: "Opening" for keyless chests, "Mining"/"Herb Gathering"/"Pick Lock" for skill locks.
-    /// The skill it *provides* is [`Self::open_lock_skill`].
+    /// The `SPELL_EFFECT_OPEN_LOCK` effect the GameObject interact-cast matches against a lock.
     pub open_lock: Option<OpenLock>,
-    /// `baseLevel` (column 28, `SpellRec+0x70`; **not** `spellLevel`, column 29 `+0x74` — wow-re
-    /// `openlock-spell-store-order.md` §4a pinned the split) — the level the effect values are
-    /// quoted at: the effect-value walk subtracts it, floored at 0 (`0x6e3826`), and the
-    /// cast-time scaling reads the same column (`0x6e3340`).
+    /// `baseLevel` (column 28, not `spellLevel`): the level effect values are quoted at, read by
+    /// the effect-value walk (`0x6e3854`) and the cast-time scaling (`0x6e3340`).
     pub base_level: u32,
-    /// `maxLevel` (column 27, `SpellRec+0x6c`) — caps the skill-derived level term in
-    /// [`Self::open_lock_skill`] at `maxLevel × 5` (`0x5ea6e3`); `0` = uncapped.
+    /// `maxLevel` (column 27): caps an opener's skill at `maxLevel × 5`, unless 0 (`0x5ea6e3`).
     pub max_level: u32,
-    /// `spellLevel` (column 29, `SpellRec+0x74`) — the DBC's actual spellLevel. One consumer:
-    /// the Beast Training rank comparator, whose recorded law names `+0x74` (`benilla-ui`
-    /// `craft.rs`). Everything level-scaled here reads [`Self::base_level`] instead.
+    /// `spellLevel` (column 29), read only by the Beast Training rank comparator.
     pub spell_level: u32,
-    /// `Dispel` (column 4, `SpellRec+0x10`) — the `SpellDispelType.dbc` id. The reference client
-    /// reads exactly this field for `GetPlayerBuffDispelType` / `UnitDebuff`'s third return
-    /// (byte-verified, decision 0257). Name it through [`crate::SpellCatalog::dispel_name`] — the
-    /// id alone does not say whether the class is named (`SpellDispelType.dbc`'s `[+0x28]` gate).
+    /// `Dispel` (column 4): the `SpellDispelType.dbc` id, as `UnitDebuff`'s third return.
     pub dispel: u32,
-    /// `Category` (column 2, [`COL_CATEGORY`]) — the shared-cooldown category; `0` = none.
+    /// `Category` (column 2): the shared-cooldown category; 0 is none.
     pub category: u32,
-    /// Whether [`Self::category`]'s `SpellCategory.dbc` row carries the flags-bit-`0x2`
-    /// "matches every query" wildcard (`GetCooldownInfo 0x6e13e0`'s category leg,
-    /// `gcd-power-gate.md` §2) — resolved at catalog load. Only wand Shoot's category 351 in
-    /// the 5875 data: its running swing cooldown sweeps EVERY button.
+    /// The category's `SpellCategory.dbc` flags carry `0x2`, matching every cooldown query
+    /// (`GetCooldownInfo` `0x6e13e0`); true only for wand Shoot's 351, whose swing sweeps the bar.
     pub category_wildcard: bool,
-    /// `RecoveryTime` ms (column 19) — the spell's own cooldown.
+    /// `RecoveryTime` (column 19): the spell's own cooldown in ms.
     pub recovery_ms: u32,
-    /// `InterruptFlags` ([`COL_INTERRUPT_FLAGS`]) — what breaks this spell's cast. Ordinary
-    /// timed casts carry `0xf`; the movement bit (`0x1`, vmangos
-    /// `SPELL_INTERRUPT_FLAG_MOVEMENT`) gates the cast bar's local self-cancel
-    /// (`benilla::ui_cast`, where the client-side semantics are documented).
+    /// `InterruptFlags` (column 21): what breaks the cast; `0xf` on timed casts, `0x1` movement.
     pub interrupt_flags: u32,
-    /// `AuraInterruptFlags` ([`COL_AURA_INTERRUPT_FLAGS`]) — what breaks this spell's applied
-    /// aura (the food/drink "sit still" bits live here). The cast-initiation moving gate
-    /// (`0x609de3`, wow-re `moving-cast-gate.md`; decision 0862) reads its `0x18`
-    /// (MOVING|TURNING) bits as one of the three "would movement matter" arms. `0` for most
-    /// direct casts.
+    /// `AuraInterruptFlags` (column 22): what breaks the applied aura, such as food's sit-still
+    /// bits. The cast-start moving gate reads its `0x18`, moving or turning (`0x609de3`).
     pub aura_interrupt_flags: u32,
-    /// `ChannelInterruptFlags` ([`COL_CHANNEL_INTERRUPT_FLAGS`]) — what breaks this spell's
-    /// running channel; the bits live in the *aura*-interrupt space (vmangos tests it with
-    /// `AURA_INTERRUPT_MOVING_CANCELS`), not `InterruptFlags`'. `0` for non-channels.
+    /// `ChannelInterruptFlags` (column 23): what breaks the channel, in aura-interrupt bits.
     pub channel_interrupt_flags: u32,
-    /// `CategoryRecoveryTime` ms (column 20) — the category's shared cooldown.
+    /// `CategoryRecoveryTime` (column 20): the category's shared cooldown in ms.
     pub category_recovery_ms: u32,
-    /// `StartRecoveryCategory` (column 157) — the GCD category (133 for ordinary spells).
+    /// `StartRecoveryCategory` (column 157): the global cooldown's category, usually 133.
     pub start_recovery_category: u32,
-    /// `StartRecoveryTime` ms (column 158) — the GCD duration (1500 for ordinary spells; 0 = no GCD).
+    /// `StartRecoveryTime` (column 158): the global cooldown in ms, usually 1500; 0 for none.
     pub start_recovery_ms: u32,
-    /// `powerType` (column 31) — 0 mana, 1 rage, 3 energy (vmangos `Powers`); **health is the
-    /// signed −2 stored as `0xFFFFFFFE`** (Life Tap, Bloodrage, Health Funnel), which is why every
-    /// consumer treats "negative or ≥ 5" as the health lane (the ref's own fallback fork, 1074).
+    /// `powerType` (column 31): 0 mana, 1 rage, 3 energy; health is -2, stored as `0xFFFFFFFE`
+    /// (Life Tap, Health Funnel), and the reference reads negative, or 5 and up, as health.
     pub power_type: u32,
-    /// `manaCost` (column 32) — the flat cast cost in `power_type`'s unit.
+    /// `manaCost` (column 32): the flat cost in `power_type`'s unit.
     pub mana_cost: u32,
-    /// `ManaCostPercentage` (column 156) — percent of base mana added to the flat cost (Judgement
-    /// and kin); 0 for most spells.
+    /// `ManaCostPercentage` (column 156): percent of base mana added to the flat cost.
     pub mana_cost_pct: u32,
-    /// `manaCostPerlevel` (column 33) — the per-level cost term (`0x6e31b0`'s
-    /// `(level − spellLevel) · perLevel`; 1074). 72 nonzero rows in the 5875 file, every one a
-    /// creature-cast spell (Dark Offering's health lane among them) — dormant for player
-    /// tooltips, modeled because the law and the data both carry it.
+    /// `manaCostPerlevel` (column 33): the per-level cost term of `GetPowerCost` (`0x6e31b0`).
     pub mana_cost_per_level: u32,
-    /// `manaPerSecond` (column 34) — the per-second maintenance component; the tooltip cost
-    /// cell's `_PER_TIME` composite ("11 Health, plus 5 per sec" — Health Funnel; 1074). The
-    /// sibling `manaPerSecondPerLevel` (35) is all-zero across the whole 5875 file
-    /// ([`catalog_tests`]'s column scan — a verified negative) and stays unparsed.
+    /// `manaPerSecond` (column 34): the tooltip's "plus N per sec"; column 35 is 0 on every row.
     pub mana_per_second: u32,
-    /// `rangeIndex` (column 36) — the `SpellRange.dbc` row ([`SpellRangeCatalog`]).
+    /// `rangeIndex` (column 36): the `SpellRange.dbc` row.
     pub range_index: u32,
-    /// `Targets` (column 13, [`COL_TARGETS`]) — the `TARGET_FLAG_*` seed mask of the cast-arm's
-    /// targeting flag_word. `0` for ordinary casts (the implicit-target switch supplies the bits).
+    /// `Targets` (column 13): the `TARGET_FLAG_*` seed of the cast arm's targeting word.
     pub targets: u32,
-    /// `EffectImplicitTargetA[0]` (column 82, [`COL_IMPLICIT_TARGET_A1`]) — the implicit-target
-    /// enum the cast-arm's switch adjusts the flag_word by (and the usable walk's
-    /// CanAttack/CanAssist fork inside the TargetAuraState leg keys on: 6 = enemy, 21 = friend).
+    /// `EffectImplicitTargetA[0]` (column 82): the cast arm's switch adjusts the targeting word
+    /// by it, and the usable walk's target-aura-state leg forks on it (6 enemy, 21 friend).
     pub implicit_target_a1: u32,
-    /// `EffectImplicitTargetA[3]` (columns 82–84, [`COL_IMPLICIT_TARGET_A1`]) and
-    /// `EffectImplicitTargetB[3]` (columns 85–87, [`COL_IMPLICIT_TARGET_B1`]) — every effect's
-    /// implicit-target pair, the input of [`Self::is_harmful`] (the client's hostility classifier
-    /// walks all three slots, A then B). Slot 0 of A is also [`Self::implicit_target_a1`].
+    /// `EffectImplicitTargetA[3]` (columns 82-84), then `EffectImplicitTargetB[3]` (85-87).
     pub effect_implicit_target_a: [u32; 3],
     pub effect_implicit_target_b: [u32; 3],
-    /// `Stances` (column 11) — forms the spell is *explicitly* castable in, `1 << (form-1)` each
-    /// (the form gate [`Self::usable_in_form`]). 0 = no form requirement of its own.
+    /// `Stances` (column 11): forms the spell may be cast in, `1 << (form - 1)` each; 0 is none.
     pub stances: u32,
-    /// `StancesNot` (column 12) — forms the spell is explicitly forbidden in.
+    /// `StancesNot` (column 12): forms the spell may not be cast in.
     pub stances_not: u32,
-    /// `CasterAuraState` (column 16) — required caster aura-state index (`1 << (n-1)` against
-    /// `UNIT_FIELD_AURASTATE`); 0 = none. Revenge's defense state (1).
+    /// `CasterAuraState` (column 16): state n needs bit `1 << (n - 1)` of the caster's
+    /// `UNIT_FIELD_AURASTATE`; 0 is none.
     pub caster_aura_state: u32,
-    /// `TargetAuraState` (column 17) — required aura-state index on the CURRENT TARGET; 0 =
-    /// none. The one target-dependent usable leg (§2a leg 10): Execute's healthless-20% (2).
+    /// `TargetAuraState` (column 17): the current target's required aura state (`0x6e3f58`).
     pub target_aura_state: u32,
-    /// `Totem[2]` (columns 40-41) — tool items that must be PRESENT (not consumed): fishing
-    /// pole-less fishing, blacksmith hammers. 0 = unused slot.
+    /// `Totem[2]` (columns 40-41): tools that must be carried, not consumed, such as a hammer.
     pub totems: [u32; 2],
-    /// `Reagent[8]`/`ReagentCount[8]` (columns 42-49/50-57) as (item entry, count) pairs —
-    /// consumed materials. Entry 0 = unused slot.
+    /// `Reagent[8]` and `ReagentCount[8]` (columns 42-49, 50-57): consumed items and counts.
     pub reagents: [(u32, u32); 8],
-    /// `EquippedItemClass` (column 58, signed) — the item class a worn item must match (2 =
-    /// weapon for Auto Shot's bow); `-1` = no requirement.
+    /// `EquippedItemClass` (column 58, signed): the item class a worn item must be; -1 is none.
     pub equipped_item_class: i32,
-    /// `EquippedItemSubClassMask` (column 59) — `1 << subclass` mask refining
-    /// [`Self::equipped_item_class`] (`0x4000c` = bows|guns|crossbows).
+    /// `EquippedItemSubClassMask` (column 59): the allowed subclasses, `1 << subclass` each.
     pub equipped_item_subclass_mask: u32,
-    /// `EquippedItemInventoryTypeMask` (column 60, `SpellRec+0xf0`) — a `1 << InventoryType` mask,
-    /// the third and last leg of the reference's item-target gate (`0x495d60` @ `495e4d`; the two
-    /// before it are [`Self::equipped_item_class`]/[`Self::equipped_item_subclass_mask`] at
-    /// `495e10`). `0` = no requirement. This is the leg that decides a Crude Scope goes on a gun
-    /// and not a chestpiece; a mismatch is the client's own local "Invalid target" (`0x0a`).
+    /// `EquippedItemInventoryTypeMask` (column 60): `1 << InventoryType` each; the item-target
+    /// gate's last leg (`0x495d60`), whose mismatch is the local "Invalid target" (`0x0a`).
     pub equipped_item_inventory_type_mask: u32,
-    /// `RequiresSpellFocus` ([`COL_REQUIRES_SPELL_FOCUS`]) — the `SpellFocusObject.dbc` object
-    /// that must be nearby (1 Anvil, 3 Forge, 4 Cooking Fire — [`crate::spell_focus`]); 0 = none.
-    /// The crafting book's "Requires: …" line (0437).
+    /// `RequiresSpellFocus` (column 15): the `SpellFocusObject.dbc` object needed nearby.
     pub requires_spell_focus: u32,
-    /// The `SpellShapeshiftForm.dbc` form id this spell shifts into — the `EffectMiscValue` of
-    /// its first `SPELL_AURA_MOD_SHAPESHIFT` apply-aura effect — or `None` for a non-form spell.
-    /// The stance bar's admission + isActive keys (wow-re `shapeshift-bar-api.md`, VERIFIED).
+    /// The `SpellShapeshiftForm.dbc` form: the first `SPELL_AURA_MOD_SHAPESHIFT` effect's
+    /// `EffectMiscValue`, which the stance bar keys on (`0x4b2810`, `0x4b475c`).
     pub shapeshift_form: Option<u32>,
-    /// `StanceBarOrder` ([`COL_STANCE_BAR_ORDER`], signed) — the stance bar's sort key
-    /// (ascending, negative last, spell id tiebreak).
+    /// `StanceBarOrder` (column 166, signed): the stance bar's sort key, negative last.
     pub stance_bar_order: i32,
-    /// `ActiveIconID`'s resolved texture path ([`COL_ACTIVE_ICON_ID`]) — shown on the stance
-    /// button while this form is active, when present (druid forms); `None` falls back to `icon`.
+    /// `ActiveIconID`'s texture, shown on the stance button while the form is active.
     pub active_icon: Option<String>,
-    /// `ActiveIconID` raw ([`COL_ACTIVE_ICON_ID`]) — the plain-path active-action toggle's gate
-    /// (`0x4e55f0`/`0x4b36f0` test the COLUMN, not the resolved texture; wow-re
-    /// `shapeshift-plaincast-toggle.md`): a nonzero id marks the spell press-again-to-cancel
-    /// while its own aura is live (`benilla::ui_action::toggle`).
+    /// `ActiveIconID` (column 118) as stored: nonzero makes a second press cancel the spell's
+    /// live aura. The client tests the id, not the texture (`0x4e55f0`, `0x4b36f0`).
     pub active_icon_id: u32,
-    /// `Description` enUS (column 138, module docs) — the tooltip body, raw `$`-token text
-    /// un-substituted (decision 0274 P2's engine resolves the tokens; this is the source text).
-    /// `None` when the column is empty.
+    /// `Description` enUS (column 138): the tooltip body, its `$` tokens unsubstituted.
     pub description: Option<String>,
-    /// `AuraDescription` enUS (column 147, module docs) — the buff/debuff-icon tooltip text (a
-    /// shorter restatement of the periodic/ongoing effect); `None` when empty (most direct-damage/
-    /// direct-effect spells with no aura component, e.g. Fire Blast).
+    /// `AuraDescription` enUS (column 147): the buff or debuff icon's tooltip.
     pub aura_description: Option<String>,
-    /// `DurationIndex` (column 30, module docs) — the [`SpellDurationCatalog`] row. `0` resolves to
-    /// no row (an instant-hit spell with no periodic/aura tail).
+    /// `DurationIndex` (column 30): the `SpellDuration.dbc` row; 0 for no duration.
     pub duration_index: u32,
-    /// `CastingTimeIndex` (column 18, module docs) — the [`SpellCastTimeCatalog`] row. Row 1 is the
-    /// universal instant sentinel (`0` ms).
+    /// `CastingTimeIndex` (column 18): the `SpellCastTimes.dbc` row; row 1 is instant.
     pub casting_time_index: u32,
-    /// `ProcChance` (column 25, module docs) — percent chance to trigger on the proc event
-    /// `procFlags` names (not read here); vmangos's own `101` sentinel means "always, no roll".
+    /// `ProcChance` (column 25): percent; vmangos reads 101 as always, with no roll.
     pub proc_chance: u32,
-    /// `EffectBasePoints[3]` (column 76, module docs, **signed**) — each effect's roll floor.
-    /// `-1` is the weapon-damage/no-fixed-roll sentinel (Auto Shot, Feign Death).
+    /// `EffectBasePoints[3]` (columns 76-78, signed): each roll's floor; -1 on weapon damage.
     pub effect_base_points: [i32; 3],
-    /// `EffectDieSides[3]` (column 64, module docs, **signed**) — each effect's die size; the roll
-    /// is `base_points + 1 ..= base_points + die_sides` (`die_sides <= 1` collapses to a flat value).
+    /// `EffectDieSides[3]` (columns 64-66, signed): with n dice, the value runs base + n to
+    /// base + sides × n (`0x6e3800`), n being `EffectBaseDice` plus its per-level term.
     pub effect_die_sides: [i32; 3],
-    /// `EffectBaseDice[3]` (column 67, module docs).
+    /// `EffectBaseDice[3]` (columns 67-69).
     pub effect_base_dice: [i32; 3],
-    /// `EffectAmplitude[3]` ms (column 94, module docs) — a periodic effect's tick period; `0` =
-    /// not periodic.
+    /// `EffectAmplitude[3]` (columns 94-96): a periodic effect's tick in ms; 0 is not periodic.
     pub effect_amplitude: [u32; 3],
-    /// `EffectApplyAuraName[3]` (column 91 == [`COL_EFFECT_APPLY_AURA_1`]) — each effect's
-    /// `SpellAuraDefines` aura-type enum; `0` = not an apply-aura effect. Slot 0 is also read via
-    /// [`Self::shapeshift_form`]'s derivation.
+    /// `EffectApplyAuraName[3]` (columns 91-93): each effect's aura type; 0 is not an aura.
     pub effect_apply_aura: [u32; 3],
-    /// **`EffectMechanic[0..2]`** (columns 79–81, `SpellRec+0x13c`) — the per-effect
-    /// `SpellMechanic.dbc` id. The mechanic-immunity arm accepts a match against *either* this or
-    /// [`Self::mechanic`], and the scanner prefers this one when naming the blocking mechanic.
+    /// `EffectMechanic[3]` (columns 79-81): each effect's `SpellMechanic.dbc` id. Immunity
+    /// matches it or [`Self::mechanic`]; the `0x8d` "Can't do that while %s" line prefers it.
     pub effect_mechanic: [u32; 3],
-    /// `EffectRadiusIndex[3]` (column 88, module docs) — each effect's `SpellRadius.dbc` row (not
-    /// loaded by this crate yet); `0` = no radius (a single-target effect).
+    /// `EffectRadiusIndex[3]` (columns 88-90): each effect's `SpellRadius.dbc` row; 0 is none.
     pub effect_radius_index: [u32; 3],
-    /// `EffectChainTarget[3]` (column 100, module docs) — extra chain/jump targets beyond the
-    /// primary; `0` for the overwhelming majority of spells (thinnest-evidence pin — module docs).
+    /// `EffectChainTarget[3]` (columns 100-102): extra chain targets beyond the first.
     pub effect_chain_targets: [u32; 3],
-    /// `EffectMultipleValue[3]` (column 97, module docs, f32) — a chain/multi-target falloff
-    /// multiplier; `0.0` for most effects.
+    /// `EffectMultipleValue[3]` (columns 97-99, float): the chain or multi-target falloff.
     pub effect_multiple_value: [f32; 3],
-    /// `EffectTriggerSpell[3]` (column 109 == [`COL_EFFECT_TRIGGER_1`]) — each effect's triggered
-    /// spell id (a proc, a learn-wrapper's taught ability, Frost Armor's `$6136` chill proc); `0` =
-    /// no trigger.
+    /// `EffectTriggerSpell[3]` (columns 109-111): each effect's triggered spell, 0 for none.
     pub effect_trigger_spell: [u32; 3],
-    /// `EffectItemType[3]` ([`COL_EFFECT_ITEM_TYPE_1`]) — the item entry a
-    /// `SPELL_EFFECT_CREATE_ITEM` effect creates (the crafting book's product, 0437); `0` = none.
+    /// `EffectItemType[3]` (columns 103-105): the item a `SPELL_EFFECT_CREATE_ITEM` effect makes.
     pub effect_item_type: [u32; 3],
-    /// `EffectMiscValue[3]` (column 106 == [`COL_EFFECT_MISC_1`], **signed**) — each effect's
-    /// misc payload. For an effect-47 opener, slot 0 is the **window routing key** (wow-re
-    /// `tradeskill` node, VERIFIED at `0x6e4bd7`: `!= 0` → the CraftFrame — Enchanting 3, Beast
-    /// Training 1 — else the TradeSkillFrame). The OPEN_LOCK/shapeshift slots are already
-    /// exposed derived ([`Self::open_lock`]/[`Self::shapeshift_form`]); this is the raw
-    /// array.
+    /// `EffectMiscValue[3]` (columns 106-108, signed). On a trade-skill opener (effect 47),
+    /// slot 0 picks the window: nonzero the CraftFrame, 0 the TradeSkillFrame (`0x6e4bd7`).
     pub effect_misc_value: [i32; 3],
-    /// `EffectDicePerLevel[3]` ([`COL_EFFECT_DICE_PER_LEVEL_1`]) — the integer per-level term of
-    /// the effect-value walk (`0x6e3871`); `0` on every 5875 opener.
+    /// `EffectDicePerLevel[3]` (columns 70-72): the integer per-level term (`0x6e3871`).
     pub effect_dice_per_level: [i32; 3],
-    /// `EffectRealPointsPerLevel[3]` ([`COL_EFFECT_REAL_POINTS_PER_LEVEL_1`]) — the float
-    /// per-level term (`0x6e3889`). `5.0` on Pick Lock / Mining / Herb Gathering, which is what
-    /// makes their provided lock skill track the 5×level profession cap.
+    /// `EffectRealPointsPerLevel[3]` (columns 73-75): the float per-level term (`0x6e3889`); 5.0
+    /// on Pick Lock, Mining and Herb Gathering, so the skill they provide tracks the player's.
     pub effect_real_points_per_level: [f32; 3],
 }
 
-/// Hand-rolled so `equipped_item_class` defaults to the data's own "no requirement" (`-1`) —
-/// a derived 0 would be a *real* class requirement, silently tripping the usable walk's
-/// equipped-item leg on every synthetic/`..Default::default()` spell.
+/// Written out so `equipped_item_class` defaults to -1, no requirement: 0 is a real class.
 impl Default for SpellDisplay {
     fn default() -> Self {
         SpellDisplay {
@@ -424,44 +266,20 @@ impl Default for SpellDisplay {
     }
 }
 
-// The dispel-class NAME (the aura tooltip's right column, and the `debuffType` the debuff border
-// tints by) is not derivable from [`SpellDisplay::dispel`] alone: `SpellDispelType.dbc` carries
-// both the string and the `[+0x28]` gate that decides whether a class is named at all. It lives on
-// the catalog that loads that file — [`crate::SpellCatalog::dispel_name`].
-
 impl SpellDisplay {
-    /// The `LockType` this spell opens, if any — [`Self::open_lock`]'s index alone.
+    /// The `LockType` this spell opens, if any.
     pub fn open_lock_type(&self) -> Option<u32> {
         self.open_lock.map(|o| o.lock_type)
     }
 
-    /// The **skill value this spell provides** to a lock, given the player's skill in the
-    /// spell's own line — the client's effect-value *min* (`0x6e3800`) put through its caller's
-    /// rounding (`0x6e3760`: `round(2x ∓ 0.5) >> 1`), and the left-hand side of the lock
-    /// resolver's satisfaction test (`0x5f850f`: `cmp eax,esi; jge`). `None` when the spell
-    /// opens no lock.
-    ///
-    /// **The level term IS the player's skill** (wow-re `openlock-spell-store-order.md` §4a,
-    /// byte-verified 2026-08-14, overturning `cursor-system.md` §8.8's "no player skill block is
-    /// read anywhere in the chain" — and this doc's own earlier "never the player's skill block"
-    /// gloss with it): `0x6e3800`'s level call (`0x6e384d → 0x6e3130`) resolves the CGPlayer
-    /// vtable slot `+0xa8` = `0x5ea690`, which reads `PLAYER_SKILL_INFO` for the spell's
-    /// SkillLineAbility line — value **plus** bonuses (`0x5ea56d`/`0x5ea578`/`0x5ea580`) —
-    /// clamps it to `maxLevel × 5` (`0x5ea6e3`), and returns it `/5` (`0x6e3195`). So:
-    /// `Δ = max(0, min(skill, maxLevel·5)/5 − baseLevel)`. Pick Lock 1804 at skill 300 → `4 +
-    /// 1 + 5.0·(60−1)` = **300**; at skill 150 → **150**. Mining 2575 → exactly the skill. The
-    /// flat spells are unchanged: Small Seaforium Charge 4056 → `149 + 1` = **150**, the
-    /// "Opening" family flat 100.
-    ///
-    /// The old reading fed the **caster level** here — indistinguishable at skill cap (where
-    /// `skill/5 == level`, which is how it survived every at-cap cross-check) and wrong
-    /// everywhere else: a level-60 with 1 Mining satisfied a 300-skill vein. `skill_value = 0`
-    /// (line unknown, or the player lacks it) is the fail-closed leg — the opener provides only
-    /// its flat terms.
+    /// The lock skill this spell provides (`0x5f850f`), from the player's skill in its line:
+    /// the effect value (`0x6e3800`) with its caller's rounding (`0x6e3760`). Its level term is
+    /// that skill with its bonuses (`0x5ea690`), not the caster's level; a skill of 0 leaves only
+    /// the flat terms.
     pub fn open_lock_skill(&self, skill_value: u32) -> Option<i32> {
         let e = self.open_lock?.effect;
-        // `0x5ea6e3`: skill capped at maxLevel·5 (0 = uncapped); `0x6e3195`: /5 (integer);
-        // `0x6e3826`: baseLevel subtraction, floored at 0.
+        // The skill capped at maxLevel·5, 0 uncapped (`0x5ea6e3`), integer /5 (`0x6e3195`), less
+        // baseLevel floored at 0 (read at `0x6e3854`, subtracted at `0x6e385b`-`0x6e385f`).
         let capped = if self.max_level > 0 {
             skill_value.min(self.max_level * 5)
         } else {
@@ -482,22 +300,9 @@ impl SpellDisplay {
         Some((doubled.round_ties_even() as i32) >> 1)
     }
 
-    /// The client's ranged-stance gate, verbatim: `AttributesEx2 & 0x20` (auto-repeat: Auto Shot,
-    /// wand Shoot) **or** `Attributes & 0x2` (uses the ranged slot: every Shoot variant, Throw).
-    /// Byte-verified in wow-re (`SpellRec+0x20&0x20 || +0x18&0x2` — the test every ranged trigger
-    /// runs: the `SMSG_SPELL_START` stance/ammo sites `0x6e78b6`/`0x6e78f3` and the local cast-send
-    /// site `0x6e5930`).
-    /// The client's spell-hostility classifier `Spell_C::GetSpellVisualState` (`0x6ea280`),
-    /// reduced to its `== 2` answer — **"this spell targets enemies"** — which is the gate on the
-    /// victim's **wound flinch after a spell impact** (the instant-hit loop `0x6e8bf0` @
-    /// `0x6e8c7b`, and the reflect impact `0x6e8cb0` @ `0x6e8cf1`; decision 2058). Byte-read
-    /// 2026-09-07 off `WoW.exe`: `Targets & 0x100` (the ally flag) ⇒ 1, never harmful; else
-    /// `Targets & 0x80` (the enemy flag) ⇒ 2; else, for each of the three effects, A then B, an
-    /// implicit target in the byte tables `0x6ea338` / `0x6ea378` (identical) marked `0` ⇒ 2 —
-    /// the set is `{2, 6, 15, 16, 24, 28, 53, 54}`, exactly the ids the modern enum names
-    /// `*_ENEMY` (nearby enemy, target enemy, the two enemy areas, the two enemy cones, the enemy
-    /// dest, the channeled enemy area). The function's remaining passes decide 1 (helpful) vs 0
-    /// and can never yield 2, so this predicate is the whole `== 2` truth.
+    /// The hostility classifier `0x6ea280` reduced to "targets enemies", the gate on the victim's
+    /// flinch at a spell impact (`0x6e8c7b`, `0x6e8cf1`): the ally flag `0x100` wins, then the
+    /// enemy flag `0x80`, then an enemy A or B implicit target (tables `0x6ea338`/`0x6ea378`).
     pub fn is_harmful(&self) -> bool {
         const ENEMY_TARGETS: [u32; 8] = [2, 6, 15, 16, 24, 28, 53, 54];
         if self.targets & 0x100 != 0 {
@@ -512,178 +317,88 @@ impl SpellDisplay {
         })
     }
 
+    /// The ranged-stance gate, `AttributesEx2 & 0x20` or `Attributes & 0x2`, as tested at
+    /// `0x6e78b6`/`0x6e78f3` (`SMSG_SPELL_START`) and `0x6e5930` (the cast send).
     pub fn ranged_attack(&self) -> bool {
         self.attributes_ex2 & ATTR_EX2_AUTO_REPEAT != 0 || self.attributes & ATTR_RANGED != 0
     }
 
-    /// **This cast aims itself at the equipped main hand** — `Attributes & 0x200`
-    /// ([`ATTR_TARGET_MAIN_HAND_ITEM`]), the client's own auto-pick for a weapon imbue.
-    ///
-    /// `ArmCast 0x6e5250` resolves the cast's candidate guid from ONE of three places, and this
-    /// bit picks the first: for a **player** caster (`6e5361`: `[[caster+8]+8] >> 4 & 1`, the
-    /// typemask-`0x10` test) carrying the bit (`6e5371: test ah,0x2`), the candidate is the
-    /// player's inventory slot table entry 15 — `[player+0x1d3c][15]`, `EQUIPMENT_SLOT_MAINHAND`
-    /// (`6e5385`–`6e538e`, the `+0x78/+0x7c` guid pair; the table is wow-re's pinned
-    /// `[player+0x1d38]` count / `[player+0x1d3c]` array, bounds-checked at `6e5376`). Only if
-    /// the bit is clear does the walk fall to the explicit guid, then to the current selection
-    /// (`6e5393`/`6e539f`).
-    ///
-    /// So a spell carrying it never raises the item-targeting cursor over an equipped weapon:
-    /// the imbue binds and sends on the press. Exactly 22 rows of the shipped 5875 `Spell.dbc`
-    /// carry the bit, four distinct names — **Rockbiter / Flametongue / Frostbrand / Windfury
-    /// Weapon**, every rank of the shaman's weapon imbues and nothing else — and every one is
-    /// `Targets == 0x10` with an `ENCHANT_ITEM_TEMPORARY` effect (censused against the real file
-    /// in `catalog_tests.rs`, which also records why vmangos answers 28). Decision 1552.
+    /// `Attributes & 0x200`: the cast aims itself at the equipped main hand, so a weapon imbue
+    /// binds on the press with no item cursor (`ArmCast` `0x6e5250`, for a player caster). Only
+    /// the shaman weapon imbues carry it.
     pub fn targets_main_hand_item(&self) -> bool {
         self.attributes & ATTR_TARGET_MAIN_HAND_ITEM != 0
     }
 
-    /// The auto-repeat attribute **alone** (`AttributesEx2 & 0x20`) — the narrower gate on the
-    /// client's local auto-repeat state bit (`[+0xd58] & 0x200`, written only at the local
-    /// cast-send `0x6e593b`), which drives the shooter's standing Load/Hold idle. `Throw` is
-    /// ranged but not auto-repeat — it never sets this.
+    /// `AttributesEx2 & 0x20` alone: the cast send sets the client's auto-repeat state from it
+    /// (`0x6e593b`), which drives the shooter's Load/Hold idle. Throw is ranged, not auto-repeat.
     pub fn auto_repeat(&self) -> bool {
         self.attributes_ex2 & ATTR_EX2_AUTO_REPEAT != 0
     }
 
-    /// `AttributesEx3 & 0x400000` — `SPELL_ATTR_EX3_CASTING_CANCELS_AUTOREPEAT`: a *running*
-    /// auto-repeat carrying this bit is cancelled when any new cast begins (the client's
-    /// `0x60959e` test on the **cached** spell, wow-re `nocked-ammo-cancel.md` §Q-B-5). Exactly
-    /// ONE of the 22357 `Spell.dbc` records has it — wand Shoot 5019; Auto Shot (75) survives
-    /// new casts, which is how hunter shot-weaving works at all.
+    /// `AttributesEx3 & 0x400000`: a running auto-repeat with this bit ends when any new cast
+    /// begins (`0x60959e`). Only wand Shoot 5019 has it; Auto Shot survives, so hunters weave.
     pub fn casting_cancels_autorepeat(&self) -> bool {
         self.attributes_ex3 & 0x0040_0000 != 0
     }
 
-    /// The ranged-slot attribute **alone** (`Attributes & 0x2`) — the client's weapon-visual
-    /// fallback gate (`0x60d46a`): a ranged-slot spell whose own `SpellVisual` resolves to nothing
-    /// borrows the equipped ranged weapon's `ItemDisplayInfo` visual for its fire animation —
-    /// how Throw/Auto Shot/wand Shoot animate at all (byte-verified, wow-re
-    /// `throw-ranged-attack-anim.md`; every one of them has `SpellVisual1 = 0`).
+    /// `Attributes & 0x2` alone: a ranged-slot spell with no `SpellVisual` borrows the ranged
+    /// weapon's `ItemDisplayInfo` visual (`0x60d46a`), which is how Throw and the shots animate.
     pub fn ranged_slot(&self) -> bool {
         self.attributes & ATTR_RANGED != 0
     }
 
-    /// `AttributesEx3 & 0x8000` — this spell's damage numbers render **melee-white**, not
-    /// spell-gold: the second half of the combat-text color law's `B` bit (byte-verified: the
-    /// emitter `0x6128b0` tests `sign(byte[SpellRec+0x25])` = bit 15 of the `+0x24` word, wow-re
-    /// `combattext-color-law.md`; the "no record ⇒ melee" half lives at the call sites). On the
-    /// real 5875 DBC the bit is set on exactly the ranged basic shots — Auto Shot 75, Shoot Bow
-    /// 2480, Throw 2764, wand Shoot 5019 — whose damage ships as spell packets yet floats white
-    /// (vmangos delivers them via `SMSG_SPELLNONMELEEDAMAGELOG`; the modern name is
-    /// `SPELL_ATTR3_NORMAL_RANGED_ATTACK`). Decision 0376.
+    /// `AttributesEx3 & 0x8000`: damage floats melee white, not spell gold (`0x6128b0`); set on
+    /// the basic ranged shots (Auto Shot, Shoot Bow, Throw, wand Shoot).
     pub fn melee_white_damage(&self) -> bool {
         self.attributes_ex3 & ATTR_EX3_NORMAL_RANGED_ATTACK != 0
     }
 
-    /// `AttributesEx3 & 0x4` — **the casting bar shows no name for this spell**
-    /// ([`ATTR_EX3_NO_CASTING_BAR_TEXT`], `SPELL_ATTR_EX3_NO_CASTING_BAR_TEXT`). The cast-bar feed
-    /// hands `SPELLCAST_START`/`SPELLCAST_CHANNEL_START` an empty name string when this is set, so
-    /// the bar fills and sweeps with a blank label.
-    ///
-    /// Only the *name* is suppressed, and only on the bar: the spell still casts, still animates,
-    /// and its failures still name it. Three shipped rows carry the bit; the one that reached a
-    /// player is 22810 **"Opening - No Text"**, the internal opener for `LockType 13` ground
-    /// containers, whose own name spells out what the attribute is for (decision 1312, B247).
+    /// `AttributesEx3 & 0x4`: `SPELLCAST_START` gets an empty name, a blank cast bar label
+    /// (`0x6e7a2d`, the one test of this bit); the channel bar never reads it.
     pub fn no_casting_bar_text(&self) -> bool {
         self.attributes_ex3 & ATTR_EX3_NO_CASTING_BAR_TEXT != 0
     }
 
-    /// `AttributesEx3 & 0x2000` — **this spell shows no channel bar at all**
-    /// ([`ATTR_EX3_NO_CHANNEL_BAR`]). The channel handler `0x6e7550` tests it before it composes
-    /// anything (`0x6e7595 test ch,0x20` → `jne` the return), so `SPELLCAST_CHANNEL_START` never
-    /// fires and the frame is never shown.
-    ///
-    /// A **different** suppression from [`Self::no_casting_bar_text`]'s and a total one: that bit
-    /// blanks the cast bar's *label* and still draws the bar; this one removes the event. The two
-    /// live one nibble apart in the same column and are easy to conflate — the channel path never
-    /// reads bit 2 at all (`0x6e7a2d` is the only bit-2 test on `SpellRec+0x24` image-wide, wow-re
-    /// `wave-cast.md`'s twice-run census).
-    ///
-    /// Both shipped rows are 24322/24323 "Blood Siphon", the Hakkar encounter's drain.
+    /// `AttributesEx3 & 0x2000`: no channel bar; the handler `0x6e7550` returns at `0x6e7595`
+    /// before `SPELLCAST_CHANNEL_START`. Only Blood Siphon, 24322 and 24323, carries it.
     pub fn no_channel_bar(&self) -> bool {
         self.attributes_ex3 & ATTR_EX3_NO_CHANNEL_BAR != 0
     }
 
-    /// `AttributesEx & 0x2000_0000` — **the channel bar prints this spell's own name**
-    /// ([`ATTR_EX_CHANNEL_BAR_OWN_NAME`]); cleared, it prints the GlobalStrings word `CHANNELING`.
-    /// `0x6e759a test DWORD PTR [SpellRec+0x1c],0x20000000` — set takes `Name[locale]`
-    /// (`0x6e75a9`), clear takes `FrameScript_GetText(0x870dd0 = "CHANNELING")` (`0x6e75bc`).
-    ///
-    /// This is the whole of the channel bar's naming law, and it is the reverse default of the
-    /// cast bar's: a cast bar names its spell unless told not to, a channel bar says "Channeling"
-    /// unless told to name it. Nine of the 323 channeled rows in the shipped 5875 file opt in —
-    /// the four Fishing ranks, Cannibalize, Dream Vision, Using Control Console and the two
-    /// (suppressed) Blood Siphons. Blizzard, Arcane Missiles, Mind Flay, Drain Life/Soul/Mana,
-    /// Rain of Fire, Hurricane, Tranquility, Evocation and First Aid all read the generic word.
+    /// `AttributesEx & 0x2000_0000` (`0x6e759a`): the channel bar shows the spell's own name
+    /// (`0x6e75a9`), else `CHANNELING` (`0x6e75bc`); nine channels set it, Fishing among them.
     pub fn channel_bar_own_name(&self) -> bool {
         self.attributes_ex & ATTR_EX_CHANNEL_BAR_OWN_NAME != 0
     }
 
-    /// The ranged-shot cooldown pad's gate (`0x6e2b60` at `0x6e2c2c`–`0x6e2c47`, byte-verified —
-    /// wow-re `ranged-cooldown-sweep.md`): on the caster's own SPELL_GO self-insert, a
-    /// `Attributes & 0x2` spell WITHOUT `AttributesEx2 & 0x20000`
-    /// (`SPELL_ATTR_EX2_DO_NOT_RESET_COMBAT_TIMERS`) adds the caster's live
-    /// `UNIT_FIELD_RANGEDATTACKTIME` to its category recovery — how the Throw / wand Shoot
-    /// button sweeps the weapon's speed with `Spell.dbc` recovery all zero and no server packet
-    /// (the category-0 Auto Shot inserts the same timer but no read can surface it).
+    /// `Attributes & 0x2` without `AttributesEx2 & 0x20000`: the caster's `SMSG_SPELL_GO` adds
+    /// `UNIT_FIELD_RANGEDATTACKTIME` to its category cooldown locally (`0x6e2b60`).
     pub fn ranged_speed_cooldown(&self) -> bool {
         self.attributes & ATTR_RANGED != 0
             && self.attributes_ex2 & ATTR_EX2_DO_NOT_RESET_COMBAT_TIMERS == 0
     }
 
-    /// Whether this spell appears in the spellbook — the client's book **add-gate**, byte-verified
-    /// (decision 0227; wow-re `system/ui/scratch/spellbook-book-build.md`, `CGPlayer_C::AddSpell
-    /// 0x5e9c20` → the classify+append `0x4b25b0`). A known spell is kept OUT of the book when any
-    /// of three gates trips: `Attributes & 0x80` (`SPELL_ATTR_DO_NOT_DISPLAY` — every language,
-    /// armor/weapon proficiency, and hidden racial passive), `Attributes & 0x20`
-    /// (`SPELL_ATTR_IS_TRADESKILL` — professions divert to a name-only path, no book slot), or
-    /// `castUI != 0`. Concrete: Fireball 133 (`Attributes 0x10000`, castUI 0) is shown;
-    /// Language:Common 668 / Cloth 9078 / One-Handed Axes 196 (all `0xC0 = PASSIVE|DO_NOT_DISPLAY`)
-    /// are hidden. Passive-but-shown spells exist (a passive is NOT itself a book gate); only the
-    /// three bits above hide a spell.
+    /// The spellbook's add gate (`AddSpell` `0x5e9c20`, `0x4b25b0`): a spell stays out for
+    /// `Attributes` `0x80` or `0x20`, or a nonzero `castUI`; passive alone does not hide it.
     pub fn in_spellbook(&self) -> bool {
         self.attributes & (ATTR_DO_NOT_DISPLAY | SPELL_ATTR_IS_TRADESKILL) == 0 && self.cast_ui == 0
     }
 
-    /// Whether this spell appears in the **pet's** book — a *different* add-gate from
-    /// [`Self::in_spellbook`]'s, and deliberately narrower (decision 1032). `0x4b2f90`, the pet
-    /// book's whole append routine, tests the record's existence and then exactly one bit:
-    ///
-    /// ```text
-    /// 0x4b2fa8  mov dl, byte ptr [rec + 0x18]     ; Attributes, byte 0
-    /// 0x4b2fab  test dl, dl
-    /// 0x4b2fad  js  <drop>                        ; the SIGN of the byte = 0x80 = DO_NOT_DISPLAY
-    /// 0x4b2fb4  [0xb6f098 + 4*count++] = spellId
-    /// ```
-    ///
-    /// No `IS_TRADESKILL` leg and no `castUI` leg — the player book's other two gates simply are
-    /// not there. Reusing `in_spellbook` here would be a guess that happens to agree on every
-    /// vmangos pet list today and would diverge the moment one didn't.
+    /// The pet book's add gate (`0x4b2f90`) tests only `Attributes & 0x80`, as the sign of its
+    /// low byte (`0x4b2fad`); it has none of [`Self::in_spellbook`]'s other two legs.
     pub fn in_pet_book(&self) -> bool {
         self.attributes & ATTR_DO_NOT_DISPLAY == 0
     }
 
-    /// The **melee auto-attack** — `Effect[0] == SPELL_EFFECT_ATTACK (78)`, the client's own
-    /// effect-type trigger for the equipped-weapon icon substitution (decision 0231; wow-re
-    /// `attack-icon-substitution.md`, resolvers `0x4b3f8a`/`0x4e59de`). In 1.12 the only spell
-    /// carrying it is 6603 "Attack" (its `SpellIconID` → the `Temp` placeholder the client never
-    /// shows, substituting the main-hand weapon icon instead).
+    /// `Effect[0] == SPELL_EFFECT_ATTACK` (78): the client's trigger for showing the main-hand
+    /// weapon's icon instead (`0x4b3f8a`, `0x4e59de`). In 1.12 only 6603 "Attack" carries it.
     pub fn is_melee_auto_attack(&self) -> bool {
         self.effects[0] == SPELL_EFFECT_ATTACK
     }
 
-    /// The spell **tooltip's** passive gate (wow-re `tooltip-content-law.md` §3.4): the
-    /// CastTime|Cooldown line is skipped whole for `Attributes & 0x40` **or**
-    /// `Effect[0] ∈ {0x2f, 0x4e}` — `SPELL_EFFECT_TRADE_SKILL` (the profession book entries) and
-    /// `SPELL_EFFECT_ATTACK` (6603 "Attack"). Wider than [`Self::passive`], which is the
-    /// spellbook's own gray-and-refuse gate and must keep reading the attribute alone.
-    ///
-    /// The law's note writes the field as "iconID `[+0xf4]`"; the offset is Effect[0]
-    /// (`0xf4/4 == 61` — the same `[SpellRec+0xf4]` the byte-verified auto-attack resolvers
-    /// compare against `0x4e`). Confirmed on the shipped data: 6603 "Attack" carries
-    /// `Effect[0] = 78` with `Attributes = 0x10`, and the reference's spellbook hover shows it
-    /// with NO cast-time line.
+    /// The tooltip skips its cast-time and cooldown line for a passive or `Effect[0]` 47 or 78
+    /// (`0x52eb15`-`0x52eb45`); [`Self::passive`] must keep reading the attribute alone.
     pub fn tooltip_omits_cast_line(&self) -> bool {
         self.passive
             || matches!(
@@ -692,22 +407,14 @@ impl SpellDisplay {
             )
     }
 
-    /// The spell **tooltip's** range gate — the two attribute tests the builder runs BEFORE it
-    /// ever calls `GetMinMaxRange 0x6e3480` (`0x52e9a5`: `Attributes & 0x404`, the on-next-swing
-    /// pair; `0x52e9b2`: `AttributesEx3 & 0x40000000`), each jumping straight past the cell.
-    /// The third absence case is not an attribute — it is a resolved `max <= 0`, which is what
-    /// the 11 777 self-only rows produce and is by far the dominant one (wow-re
-    /// `tooltip-globalstring-key-resolves.md` §A3, VERIFIED).
-    ///
-    /// So a Heroic Strike or a Backstab shows **no range cell at all** — not a melee wording.
+    /// No tooltip range cell: tested before `GetMinMaxRange` (`0x6e3480`), an on-next-swing spell
+    /// (`0x52e9a5`) or `AttributesEx3` bit 30 (`0x52e9b2`); after it, a max of 0 (`0x52e9ed`).
     pub fn tooltip_omits_range_line(&self) -> bool {
         self.on_next_swing() || self.attributes_ex3 & 0x4000_0000 != 0
     }
 
-    /// The cooldown getter's HEAD exclusion (`GetCooldownInfo 0x6e13e0` @ `6e1439`/`6e1442`,
-    /// wow-re `gcd-power-gate.md` §2, §5-verified): `Effect[0] ∈ {0x4e ATTACK, 0x2f TRADE_SKILL}`
-    /// returns "no cooldown" unconditionally — the reason the Attack and profession buttons never
-    /// show a pie AND their presses can never be cooldown-refused.
+    /// `GetCooldownInfo` (`0x6e13e0`) reports no cooldown for `Effect[0]` 78 (attack) or 47
+    /// (trade skill): those buttons never show one and are never refused by one.
     pub fn cooldown_query_excluded(&self) -> bool {
         matches!(
             self.effects[0],
@@ -715,173 +422,88 @@ impl SpellDisplay {
         )
     }
 
-    // The equipped-item requirement's NAME used to be decided here, by a
-    // `single_equipped_subclass` that answered only for a one-bit mask — a placeholder standing in
-    // for the uncarved `0x6e2380`. `0x6e2380` is carved now, and it reads only ItemSubClass.dbc,
-    // behind an ItemSubClassMask.dbc group lookup that names a wide mask in one word. The whole
-    // rule (both spellings, both call sites) lives with the vocabulary it reads:
-    // [`crate::ItemSubClassCatalog::requirement_name`].
-
-    /// The **ranged** icon-substitution gate — `Attributes & 0x2` AND `AttributesEx2 & 0x20`,
-    /// both bits (decision 0231's deferred ranged case; wow-re `attack-icon-substitution.md` §5,
-    /// byte-verified: the paired tests at `0x4b3f99`/`0x4b3f9f` and `0x4e5a2e`/`0x4e5a34` gate the
-    /// call into the ranged helper `0x4e6990`). Auto Shot 75 and wand Shoot 5019 carry both;
-    /// Throw 2764 carries only `0x2` and keeps its own icon.
+    /// The ranged icon substitution needs `Attributes & 0x2` and `AttributesEx2 & 0x20` both
+    /// (`0x4b3f99`, `0x4e5a2e`): Auto Shot and wand Shoot show the weapon's icon, Throw its own.
     pub fn ranged_icon_substitution(&self) -> bool {
         self.attributes & ATTR_RANGED != 0 && self.attributes_ex2 & ATTR_EX2_AUTO_REPEAT != 0
     }
 
-    /// `SPELL_ATTR_COOLDOWN_ON_EVENT` (Attributes bit 25) — the cooldown record is stored **on
-    /// hold** (timers parked) until `SMSG_COOLDOWN_EVENT` starts it ([`ATTR_COOLDOWN_ON_EVENT`]).
+    /// `SPELL_ATTR_COOLDOWN_ON_EVENT`: the cooldown is held until `SMSG_COOLDOWN_EVENT`.
     pub fn cooldown_on_event(&self) -> bool {
         self.attributes & ATTR_COOLDOWN_ON_EVENT != 0
     }
 
-    /// A **combo-point consumer** (`AttributesEx` bits 20/22, [`ATTR_EX_FINISHING_MOVE`]) — the
-    /// usable walk's leg 5 greys it while the caster's combo-point byte is 0 (decision 0869). The
-    /// rogue/druid finishers, and Overpower.
+    /// A finisher (`AttributesEx` bit 20 or 22): unusable with no combo points (`0x6e3e7a`).
     pub fn needs_combo_points(&self) -> bool {
         self.attributes_ex & ATTR_EX_FINISHING_MOVE != 0
     }
 
-    /// The on-next-swing class (`Attributes & 0x404`, [`ATTR_ON_NEXT_SWING`]) — the spell queues
-    /// on the server's melee slot and fires on the next swing instead of casting. The client's
-    /// one mask for the class: the already-casting exemption (a queued one never blocks another
-    /// cast), the queued-melee slot tracking, and the range law's self-cast short-circuit all
-    /// test exactly these bits.
+    /// `Attributes & 0x404`: queued on the server's melee slot for the next swing, not cast.
     pub fn on_next_swing(&self) -> bool {
         self.attributes & ATTR_ON_NEXT_SWING != 0
     }
 
-    /// The tooltip cast cell's "Attack speed" arm — `Attributes & 0x2` ALONE (the byte test at
-    /// `0x52ec1c`: `test al,0x2`; 1074), NOT [`Self::ranged_attack`]'s or-pair: Throw carries
-    /// only `0x2` and still reads "Attack speed" in its cell.
+    /// The tooltip's "Attack speed" arm: `Attributes & 0x2` alone (`0x52ec1c`), so Throw too.
     pub fn tooltip_on_next_ranged(&self) -> bool {
         self.attributes & ATTR_RANGED != 0
     }
 
-    /// The tooltip cast cell's "Channeled" arm — `AttributesEx & 0x44` (`SPELL_ATTR_EX_CHANNELED`
-    /// both variants), the byte test at `0x52ec27` (`test [rec+0x1c],0x44`; wow-re
-    /// `tooltip-content-law.md` §3.4, folded as 1074). Distinct from
-    /// [`Self::channel_interrupt_flags`], which is the *running* channel's break mask.
+    /// The tooltip cast cell's "Channeled" arm: `AttributesEx & 0x44` (`0x52ec27`).
     pub fn tooltip_channeled(&self) -> bool {
         self.attributes_ex & ATTR_EX_CHANNELED != 0
     }
 
-    /// Whether *casting* this spell turns on the melee auto-attack **at the send** —
-    /// `Spell_C::TryCast`'s post-send tail (`6e51b5`), byte-verified whole by the 2026-07-14
-    /// wow-re §5 (`combat-feel-law.md` @ c445713b): fires the attack entry `0x6131a0` iff the
-    /// cast committed+sent this call (`[0xcead5c] == spell_id`), the rec passes
-    /// `[ebp-2] = 0x6e5200 && Ex2-bit20 CLEAR`, and no attack is already running (`0x60ecb0`).
-    /// With `0x6e5200 = (Attr & 0x404) || (AttrEx & 0x200) || (AttrEx2 & 0x100000)`, the
-    /// bit20-clear exclusion reduces the send-time law to exactly this: on-next-swing
-    /// (the queued strike needs swings to fire at all) or [`ATTR_EX_INITIATES_COMBAT`]
-    /// (Rend, Sunder Armor, Slam), and not [`ATTR_EX2_INITIATE_COMBAT_POST_CAST`] (whose
-    /// GO-deferred start we don't build — dormant by data). **Path-independent**: action
-    /// button, spellbook, and `CastSpellByName` all share the one `TryCast` tail — 1.12 has
-    /// no macro-side opt-out.
+    /// Casting this starts melee auto-attack at the send unless one runs (`TryCast` tail
+    /// `0x6e51b5`): predicate `0x6e5200` with `AttributesEx2` bit 20 clear, so an on-next-swing
+    /// or `INITIATES_COMBAT` spell. Every cast path shares the tail; there is no macro opt-out.
     pub fn initiates_auto_attack(&self) -> bool {
         (self.attributes & ATTR_ON_NEXT_SWING != 0
             || self.attributes_ex & ATTR_EX_INITIATES_COMBAT != 0)
             && self.attributes_ex2 & ATTR_EX2_INITIATE_COMBAT_POST_CAST == 0
     }
 
-    /// Whether *this spell's own `SMSG_SPELL_GO`* turns on the melee auto-attack — the **deferred**
-    /// half of the same law, [`Self::initiates_auto_attack`]'s exact complement.
-    /// `HandleSpellGo 0x6e7a70` @ `0x6e83c0` (re-read at the bytes for 1593):
+    /// This spell's own `SMSG_SPELL_GO` starts melee auto-attack (`0x6131a0`) at its first hit
+    /// target: `AttributesEx2` bit 20, the complement of [`Self::initiates_auto_attack`]
+    /// (`0x6e83c0`).
     ///
-    /// ```text
-    /// 6e83c0  call 0x6e5230(rec); test al,al; jne 6e83da   ; AttrEx2 bit20 SET -> start
-    /// 6e83cb  call 0x6e5200(rec); test al,al; je  6e8407   ; else the triad must hold
-    /// 6e83d4  test byte[rec+0x54],0x8; je 6e8407           ; ...AND rec+0x54 bit3
-    /// 6e83da  lea ecx,[esi+0xc48]; call 0x47bf60; or eax,edx; jne 6e8407  ; NOT already attacking
-    /// 6e83e9  hitCount>0 ? guid = hits[0] : (0,0)          ; [ebp-0x20] count, [ebp-0x1c] array
-    /// 6e8402  call 0x6131a0(ecx=caster, guid)              ; START MELEE AUTO-ATTACK
-    /// ```
-    ///
-    /// **Only the bit20 leg is modelled**, deliberately — and the §5 that closed B280 measured the
-    /// other one rather than leaving it to the argument below. `rec+0x54` is `Spell.dbc` **column
-    /// 21, `InterruptFlags`** (VERIFIED position; bit 3's *semantics* stay INFERRED), which is
-    /// [`Self::interrupt_flags`] — so we could build the leg today. Its live set in the shipped
-    /// file is **8 rows, 3 names** (Slam, Shield Slam, Polymorphic Ray) and is **disjoint from the
-    /// 36** bit20 rows, so every one of them passes `0x6e5200` with bit20 CLEAR and therefore
-    /// started its attack at the *send* ([`Self::initiates_auto_attack`]); by their GO the
-    /// reference's `[+0xc48]` is set and `0x6e83e7` refuses. Unreachable-in-effect, measured, not
-    /// assumed. Modelling it would also be actively *wrong* here: our engaged mirror is the
-    /// server-echoed `Engaged`, not a local lock, so a leg the reference silences with `[+0xc48]`
-    /// would fire a second `CMSG_ATTACKSWING` on our side.
-    ///
-    /// The 36 spells that reach this and nothing else are the stealth openers and positional
-    /// strikes — Backstab, Garrote, Ambush, Cheap Shot, Shred, Ravage, Pounce — plus Judgement:
-    /// exactly the class whose attack must wait for the server to say the strike landed.
+    /// Only this leg is built: the handler's other, `0x6e5200` with `InterruptFlags` bit 3
+    /// (`0x6e83d4`), never fires, as its rows already attack from the send (`0x6e83e7`). Built
+    /// here, it would send a second `CMSG_ATTACKSWING`: our engaged state is the server's echo.
     pub fn initiates_auto_attack_at_go(&self) -> bool {
         self.attributes_ex2 & ATTR_EX2_INITIATE_COMBAT_POST_CAST != 0
     }
 
-    /// Hidden from the player's buff bar — the cache-builder's **display filter**
-    /// (`PlayerAuras_Update 0x4e4170`'s append pass, sites `0x4e42b6`–`0x4e42c8`). The `Attributes`
-    /// clause is a **byte-width** read — `mov cl,[SpellRec+0x18]; test cl,cl; js` — so it tests
-    /// bit `0x80` (`SPELL_ATTR_DO_NOT_DISPLAY`), NOT the dword sign bit that wow-re's
-    /// `aura-display-pipeline.md` §3 originally transcribed (decision 0385 corrects 0268; vmangos
-    /// corroborates: `SpellDefines.h:799` "not visible in spellbook or aura bar"). The other
-    /// clause is `SpellRec+0x1c & 0x10000000` (`SPELL_ATTR_EX_NO_AURA_ICON`). The aura stays live
-    /// on the wire and in `UNIT_FIELD_AURA` — the reference just never admits it to the display
-    /// cache, so `GetPlayerBuff` cannot return it. Warrior stances (the `AttributesEx` clause) and
-    /// internal proc auras like Defensive State 5302 (the `0x80` clause) are the everyday cases.
+    /// Hidden from the buff bar (`0x4e4170`, `0x4e42b6`-`0x4e42c8`): `Attributes` read as a byte,
+    /// so `0x80` and not the dword's sign, or `AttributesEx & 0x10000000`. The aura stays live;
+    /// `GetPlayerBuff` never returns it: warrior stances, Defensive State 5302.
     pub fn hidden_from_aura_bar(&self) -> bool {
         self.attributes & ATTR_DO_NOT_DISPLAY != 0 || self.attributes_ex & ATTR_EX_NO_AURA_ICON != 0
     }
 
-    /// A **tracking** spell — any of the three `EffectApplyAuraName` slots is
-    /// `TRACK_CREATURES`/`TRACK_RESOURCES`/`TRACK_STEALTHED` ([`TRACKING_AURA_TYPES`], the
-    /// byte-verified `{0x2c,0x2d,0x97}` test at `SpellRec+0x16c..+0x174`). A tracking aura is
-    /// excluded from **every** aura display — the player-cache rebuild skips it *before* the
-    /// insert (so the buff bar never shows Find Minerals), and `IsAuraDisplayable 0x519860`
-    /// hides it from other units' rows the same way. Instead, the rebuild records the last
-    /// visible tracking spell for `GetTrackingTexture` — the minimap's `MiniMapTrackingFrame`
-    /// icon (its one consumer; `benilla::ui_aura` mirrors the whole law).
+    /// A tracking spell (`EffectApplyAuraName` 44, 45 or 151): never in an aura display
+    /// (`0x519860`); the player's last one feeds `GetTrackingTexture`, the minimap icon.
     pub fn tracking_aura(&self) -> bool {
         self.effect_apply_aura
             .iter()
             .any(|a| TRACKING_AURA_TYPES.contains(a))
     }
 
-    /// The spell's `Stances` mask is an **allow-list, not a requirement** — `AttributesEx2`
-    /// bit 19. Two independent consumers test exactly this bit: the form gate `0x612480` (which
-    /// [`Self::form_refusal`] transcribes) and, separately, the spell tooltip's required-form
-    /// line at `52f115` (wow-re §3-REQFORM) — the builder duplicates the test inline rather than
-    /// calling the gate, so one predicate here keeps our two callers from drifting the way they
-    /// did in 1483.
-    ///
-    /// 5875 leans on this hard, and reading `Stances != 0` as "requires a form" without it is
-    /// simply wrong: every Shadowform-castable priest spell carries `Stances` bit 27 (Inner Fire,
-    /// Psychic Scream, Shadow Word: Pain, Power Word: Shield…), every Spirit-of-Redemption-castable
-    /// heal carries bit 31 (Flash Heal, Renew, Prayer of Healing), and the 52 balance-druid spells
-    /// castable in Moonkin carry bit 30 (Wrath, Moonfire, Starfire, Thorns…) — the mask records
-    /// "may ALSO be cast in that form". All 244 of them carry bit 19; **none** of the 274 spells
-    /// that genuinely require a form (the warrior stances, the druid forms, the stealth openers)
-    /// does. So this is the clean separator between the two readings of one column.
+    /// `AttributesEx2` bit 19: `Stances` lists forms the spell may also be cast in, not forms it
+    /// needs. The form gate `0x612480` and the tooltip's form line (`0x52f115`) both test it; no
+    /// spell that truly needs a form (stances, druid forms, stealth openers) carries it.
     pub fn form_mask_is_permissive(&self) -> bool {
         self.attributes_ex2 & ATTR_EX2_ALLOW_WHILE_NOT_SHAPESHIFTED != 0
     }
 
-    /// The shapeshift-form gate as a boolean — the usable walk's leg 6. See
-    /// [`Self::form_refusal`], the reason-carrying transcription this wraps.
+    /// The form gate as a boolean, the usable walk's form leg (`0x6e3ec6`).
     pub fn usable_in_form(&self, form: u8, form_is_stance: bool) -> bool {
         self.form_refusal(form, form_is_stance).is_none()
     }
 
-    /// The shapeshift-form gate — `0x612480` (wow-re §2a: reads the caster form, builds
-    /// `1 << (form-1)`, tests **StancesNot** then **Stances**, then the Attributes-bit-16 /
-    /// AttributesEx2-bit-19 composition), which both the usable walk's leg 6 and the TryCast
-    /// requirement validator (`0x6094f0`, the leg right after the mounted block) run. The
-    /// composition over the form's stance flag — and the reason split — is the vmangos
-    /// corroboration (`SpellEntry::GetErrorAtShapeshiftedCast`, `SpellEntry.cpp` — anchored to
-    /// exactly the byte-named fields): a *stance*-flagged form (warrior stances, stealth —
-    /// `SpellShapeshiftForm.flags1 & 1`) does not count as "shapeshifted", so ordinary spells
-    /// stay usable in it; a true shapeshift (cat, bear, Ghost Wolf) blocks NOT_SHAPESHIFT
-    /// spells; and a form-requiring spell out of its form is refused unless AttributesEx2
-    /// bit 19 waives the requirement. `None` = castable in this form.
+    /// The shapeshift-form gate `0x612480` (usable walk `0x6e3ec6`, cast check `0x6094f0`):
+    /// `StancesNot`, then `Stances`, then `Attributes` bit 16 and `AttributesEx2` bit 19. A form
+    /// flagged as a stance (warrior stances, stealth) does not count as shapeshifted, and the
+    /// refusal reasons split as in vmangos's `SpellEntry::GetErrorAtShapeshiftedCast`.
     pub fn form_refusal(&self, form: u8, form_is_stance: bool) -> Option<FormRefusal> {
         let stance_bit = if form == 0 { 0 } else { 1u32 << (form - 1) };
         if self.stances_not & stance_bit != 0 {
@@ -891,8 +513,7 @@ impl SpellDisplay {
             return None;
         }
         if form != 0 && !form_is_stance {
-            // A true shapeshift: NOT_SHAPESHIFT spells are blocked (0x3d); a spell needing
-            // some other form is too (0x56).
+            // A true shapeshift, not a stance.
             if self.attributes & ATTR_NOT_SHAPESHIFT != 0 {
                 Some(FormRefusal::NotShapeshift)
             } else if self.stances != 0 {
@@ -901,23 +522,14 @@ impl SpellDisplay {
                 None
             }
         } else if self.stances != 0 && !self.form_mask_is_permissive() {
-            // Unshifted (or a stance): a form-requiring spell is refused here unless waived.
+            // Unshifted or in a stance: a form requirement holds unless bit 19 waives it.
             Some(FormRefusal::OnlyShapeshift)
         } else {
             None
         }
     }
-    /// The spell's name with its rank subtext appended **the way the client composes it** —
-    /// `"%s (%s)"` (the literal at `0x8468b0`, read out of the reference image) when [`Self::rank`]
-    /// is a non-empty string, and the bare name when it is not.
-    ///
-    /// Two surfaces build this string and both reach the same literal, so it is one method rather
-    /// than a copy each: the trainer window's prerequisite-ability list
-    /// (`GetTrainerServiceAbilityReq`, wow-re `system/ui/scratch/trainer-requirement.md`) and the
-    /// learn announcement's argText (`0x4b2963`'s empty-subtext test, then either
-    /// `0x4b2982 call 0x64a7f0` — `SStrPrintf(buf, 0x200, "%s (%s)", name, subtext)` — or
-    /// `0x4b29a0 call 0x64a5a0`, the plain copy). The format is a property of the spell record,
-    /// so it belongs with the record.
+    /// The name and rank as the client composes them, `"%s (%s)"` (`0x8468b0`), or the bare name
+    /// when the rank is empty; the trainer (`0x4d96e0`) and the learn line (`0x4b2982`) use it.
     pub fn ranked_name(&self) -> String {
         match self.rank.as_deref() {
             Some(rank) if !rank.is_empty() => format!("{} ({})", self.name, rank),
@@ -925,81 +537,21 @@ impl SpellDisplay {
         }
     }
 
-    /// **Which line the client prints in chat when this spell is learned**, or `None` for one it
-    /// learns silently (decision 2243).
-    ///
-    /// The announcement is the tail of the spell-added registrar `0x4b25b0` — the same function
-    /// whose head sets the known-spell bit and whose gates [`Self::in_spellbook`] models — and it
-    /// runs only when the registrar's `edx` flag is set. That flag is **not** an "announce" flag,
-    /// though this is the leg benilla uses it for: at `0x4b2b4f` it gates the book re-sort +
-    /// `SPELLS_CHANGED`, `LEARNED_SPELL_IN_TAB` and tutorial trigger 40 atomically with the chat
-    /// line, which is why the login drain fires one batched `0x4b2fd0(1,0)` rather than one per
-    /// spell. It is the **live-mutation** flag; decision 2246 names the legs still unbuilt. That flag is the whole
-    /// reason logging in is silent while a trainer purchase is not: the `SMSG_INITIAL_SPELLS`
-    /// drain replays the book through `AddSpell` with it **clear** (`0x5deaa4 push 0x1;
-    /// 0x5deaa6 push 0x0` — arg3 is the flag `AddSpell` forwards as `edx` at `0x5e9c5c`), while
-    /// `SMSG_LEARNED_SPELL`'s handler passes `1` (`0x5e61c0` -> `AddSpell(id, slot, 1, 1)`) and
-    /// `SMSG_SUPERCEDED_SPELL`'s reaches the registrar through the supersede pair `0x4b2f50`,
-    /// which hardcodes `mov edx,0x1` at `0x4b2f61`. **So a rank-up announces too** — and the
-    /// unlearn half of that same pair (`0x4b2c50`) contains no `DisplayError` call at all, which
-    /// is why a rank-up prints one line and not two, and why `SMSG_REMOVED_SPELL` prints nothing.
-    ///
-    /// The three-way itself is `0x4b2909`, reading `Attributes` (`SpellRec+0x18`) and nothing
-    /// else:
-    ///
-    /// ```text
-    /// 0x4b290f  test al,al / js  <out>      ; 0x80 DO_NOT_DISPLAY -> no line at all
-    /// 0x4b2917  test al,0x20 / je <below>   ; 0x20 IS_TRADESKILL  -> id 0x39 ERR_LEARN_RECIPE_S
-    /// 0x4b294a  and eax,0x10                ; 0x10 ABILITY
-    /// 0x4b29a9  setne al / add eax,0x37     ; -> 0x37 ERR_LEARN_SPELL_S or 0x38 ERR_LEARN_ABILITY_S
-    /// ```
-    ///
-    /// The recipe arm pushes the **bare** name (`0x4b292c`, `SpellRec+0x1e0`) and returns from the
-    /// function outright; the other two push [`Self::ranked_name`]. Every one of the three ids is
-    /// a `MsgKind::Chat` row carrying chat type `10` (`CHAT_MSG_SYSTEM`) in the message catalog,
-    /// so all three are chat lines, never `UIErrorsFrame` toasts.
-    ///
-    /// Note what the block does **not** read: the spell's power type, its school, its class, and
-    /// its `SPELL_ATTR_PASSIVE` bit are all irrelevant — a passive is announced like anything
-    /// else unless it also carries `DO_NOT_DISPLAY`, which in the shipped data it usually does.
-    /// Whether the client announces **unlearning** this spell — *"You have unlearned %s."*
-    /// (`ERR_SPELL_UNLEARNED_S`, message id `0x14a`), with the bare localized name and no rank
-    /// (decision 2246).
-    ///
-    /// A **different** gate set from [`Self::learn_announcement`]'s, in a different function, and
-    /// not guessable from it — which is how decision 2243 came to claim, with a byte citation,
-    /// that the reference never prints an unlearn line at all. It does. The claim came from
-    /// bounding `RemoveSpell 0x5e9fe0` at the `ret 0x8` at `0x5ea28f`; that `ret` is a *block*
-    /// end, and `0x5ea292` is a live branch target past it — the function really runs to
-    /// `0x5ea2ba`, and the announce is in the part 2243 never read.
-    ///
-    /// Four gates, all silent, taken in the binary's order:
-    ///
-    /// ```text
-    /// 0x5ea03a  sete cl                      ; announce := (suppress == 0)  — the caller's arg
-    /// 0x5ea03d  test al,0x20 / je 0x5ea172   ; IS_TRADESKILL falls into the container path,
-    /// 0x5ea170  xor ecx,ecx                  ;   whose join ZEROES the flag -> silent
-    /// 0x5ea17a  jle 0x5ea292                 ; castUI > 0 takes the castUI-container walk and
-    ///                                        ;   rejoins at 0x5ea245 -> silent (0x5ea292 has
-    ///                                        ;   exactly ONE entry, this one)
-    /// 0x5ea29b  js 0x5ea248                  ; DO_NOT_DISPLAY -> silent
-    /// 0x5ea2ab  push 0x14a / call 0x496720   ; else the line, with SpellRec+0x1e0 (name only)
-    /// ```
-    ///
-    /// `suppress` is the caller's, not the record's, so it is not modelled here: benilla's only
-    /// producer is `SMSG_REMOVED_SPELL` (`0x5e43e3`, `suppress = 0`), and the rank-up path that
-    /// passes `1` (`0x5e6392`) does not reach this function on our side at all.
-    ///
-    /// Note `castUI` gates the *unlearn* line and **not** the learn line — the learn block tests
-    /// it only afterwards, at `0x4b29bf`, to decide the book slot. A spell with `castUI > 0`
-    /// therefore announces when it is learned and says nothing when it is taken away. That
-    /// asymmetry is the reference's, not an oversight here.
+    /// Whether removing this spell prints "You have unlearned %s." (`0x14a`) with the bare name:
+    /// `RemoveSpell` (`0x5e9fe0`) is silent for `IS_TRADESKILL` (`0x5ea170`), a nonzero `castUI`
+    /// (`0x5ea17a`) or `DO_NOT_DISPLAY` (`0x5ea29b`). The learn line ignores `castUI`. The
+    /// caller's suppress flag is clear for `SMSG_REMOVED_SPELL` (`0x5e43e3`), set on a rank-up
+    /// (`0x5e6392`).
     pub fn announces_unlearn(&self) -> bool {
         self.attributes & SPELL_ATTR_IS_TRADESKILL == 0
             && self.cast_ui == 0
             && self.attributes & ATTR_DO_NOT_DISPLAY == 0
     }
 
+    /// The chat line a learn prints, off `Attributes` alone (`0x4b2909`): none for `0x80`, the
+    /// recipe line for `0x20`, else ability for `0x10` or spell; passive is not read. The block
+    /// runs only on a live learn: the `SMSG_INITIAL_SPELLS` replay leaves its flag clear
+    /// (`0x5deaa4`); `SMSG_LEARNED_SPELL` (`0x5e61c0`) and a rank-up (`0x4b2f61`) set it.
     pub fn learn_announcement(&self) -> Option<LearnAnnouncement> {
         if self.attributes & ATTR_DO_NOT_DISPLAY != 0 {
             return None;
@@ -1015,36 +567,29 @@ impl SpellDisplay {
     }
 }
 
-/// A [`SpellDisplay::learn_announcement`] verdict — which of the three `ERR_LEARN_*` chat lines
-/// the client prints when the spell is learned. The key each one names, and whether the argText
-/// carries the rank, is the caller's to map (`benilla::net::apply::spells`): the ids live in the
-/// message catalog, which is a UI-layer table, not a `Spell.dbc` fact.
+/// Which `ERR_LEARN_*` line a learn prints; all three are system chat lines, not UI errors.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum LearnAnnouncement {
-    /// Message id `0x37` — `ERR_LEARN_SPELL_S`, "You have learned a new spell: %s."
+    /// `0x37` `ERR_LEARN_SPELL_S`, "You have learned a new spell: %s."
     Spell,
-    /// Message id `0x38` — `ERR_LEARN_ABILITY_S`, "You have learned a new ability: %s."
-    /// (`Attributes & 0x10`, `SPELL_ATTR_ABILITY`.)
+    /// `0x38` `ERR_LEARN_ABILITY_S`, "You have learned a new ability: %s.", for `0x10`.
     Ability,
-    /// Message id `0x39` — `ERR_LEARN_RECIPE_S`, "You have learned how to create a new item: %s."
-    /// (`Attributes & 0x20`, `SPELL_ATTR_IS_TRADESKILL`.) Its argText is the **bare** name: the
-    /// reference's recipe arm never reaches the rank-subtext composer.
+    /// `0x39` `ERR_LEARN_RECIPE_S`, "You have learned how to create a new item: %s.", for `0x20`;
+    /// the name is bare, never ranked.
     Recipe,
 }
 
-/// A [`SpellDisplay::form_refusal`] verdict — which cast-fail reason `0x612480` writes.
+/// A [`SpellDisplay::form_refusal`] verdict: the cast-fail reason `0x612480` writes.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum FormRefusal {
-    /// `SPELL_FAILED_NOT_SHAPESHIFT` (0x3d, "Can't do that while shapeshifted"): blocked by the
-    /// current form — a StancesNot hit, or a NOT_SHAPESHIFT spell in a true shapeshift.
+    /// `SPELL_FAILED_NOT_SHAPESHIFT` (0x3d): a `StancesNot` hit, or a no-shapeshift spell in one.
     NotShapeshift,
-    /// `SPELL_FAILED_ONLY_SHAPESHIFT` (0x56, "Must be in %s"): the spell requires a form the
-    /// caster is not in.
+    /// `SPELL_FAILED_ONLY_SHAPESHIFT` (0x56, "Must be in %s"): not in a required form.
     OnlyShapeshift,
 }
 
 impl FormRefusal {
-    /// The wire/cast-fail reason byte (the `SPELL_FAILED_*` table index).
+    /// The `SPELL_FAILED_*` reason byte.
     pub fn reason(self) -> u8 {
         match self {
             FormRefusal::NotShapeshift => 0x3d,
@@ -1057,9 +602,6 @@ impl FormRefusal {
 mod tests {
     use super::*;
 
-    /// The `0x6ea280 == 2` predicate on synthetic rows: the two `Targets` flags outrank the
-    /// implicit-target walk (ally wins over everything, enemy wins next), and the walk reads all
-    /// three effects' A and B slots against the byte tables' enemy set.
     #[test]
     fn is_harmful_follows_the_client_classifier() {
         let mut d = SpellDisplay::default();
@@ -1082,9 +624,6 @@ mod tests {
         assert!(!d.is_harmful(), "the ally flag short-circuits the walk");
     }
 
-    /// The learn announcement's three-way at `0x4b2909`, read off `Attributes` alone — and its
-    /// one silent case. The bit order is the binary's: `DO_NOT_DISPLAY` is tested first and wins
-    /// over a row that also declares `IS_TRADESKILL`, which in turn wins over `ABILITY`.
     #[test]
     fn learn_announcement_reads_the_three_attribute_bits_in_the_clients_order() {
         let mut d = SpellDisplay::default();
@@ -1131,9 +670,6 @@ mod tests {
         );
     }
 
-    /// The unlearn line's four gates (`0x5e9fe0`'s block at `0x5ea292`) — a different set from
-    /// the learn block's, in a different function. `castUI` is the one that is easy to miss: it
-    /// silences the unlearn and does nothing to the learn.
     #[test]
     fn announces_unlearn_is_not_the_mirror_of_the_learn_gates() {
         let mut d = SpellDisplay::default();
@@ -1165,9 +701,7 @@ mod tests {
         );
     }
 
-    /// `"%s (%s)"` (`0x8468b0`) versus the bare copy, keyed on the rank subtext being a non-empty
-    /// string — the reference tests the first BYTE of the subtext (`0x4b2963 cmp BYTE PTR [eax],0x0`),
-    /// so a present-but-empty column is the bare name, not `"Name ()"`.
+    /// The reference tests the subtext's first byte (`0x4b2963`), so an empty rank is no rank.
     #[test]
     fn ranked_name_appends_the_subtext_only_when_there_is_one() {
         let mut d = SpellDisplay {
diff --git a/crates/benilla-formats/src/spells/duration.rs b/crates/benilla-formats/src/spells/duration.rs
index f38e2b6a..d0d78cbe 100644
--- a/crates/benilla-formats/src/spells/duration.rs
+++ b/crates/benilla-formats/src/spells/duration.rs
@@ -1,20 +1,7 @@
-//! `SpellDuration.dbc` — the base/per-level/max duration (ms) a spell's `DurationIndex` column
-//! ([`crate::spells::SpellDisplay::duration_index`]) resolves against. Feeds the duration
-//! formula — `Spell_C::GetDuration 0x6ea000`, byte-confirmed by the 2026-07-10 wow-re §5
-//! cross-check (`wave-cooldown.md`, wow-re commit `f2c563c9`): it reads DurationIndex
-//! `[SpellRec+0x78]`, resolves this table's recordsById at `[0xc0d828]`, and applies spell-mod
-//! op `1` (SPELLMOD_DURATION). The row layout is settled independently (WoWDBDefs'
-//! `1.0.0.3980`–`1.12.3.6141` layout `$id$ID<32> Duration<32> DurationPerLevel<32>
-//! MaxDuration<32>`, covering build 5875 — cross-checked against the real extracted file below).
-//!
-//! **Row layout** — pinned on the extracted 5875 file (82 records × 4 fields, 16 B/record): `ID(0)`,
-//! `Duration(1)` = the ms a flat 1.12 tooltip shows, `DurationPerLevel(2)`, `MaxDuration(3)`. All
-//! three are **signed**: row 21 = `{-1, 0, -1}` — the client's "permanent, until cancelled"
-//! sentinel (a stance/passive-style aura with no timer; [`SpellDuration::is_permanent`]) — and a
-//! few rows (e.g. 427) carry a negative base with a nonzero per-level term for level-scaling
-//! formulas this crate doesn't evaluate; the raw triple is carried faithfully. Row 30 =
-//! `{1_800_000, 0, 1_800_000}` — Frost Armor (spell 168)'s real 30-minute duration, cross-checked
-//! end-to-end against the local vmangos `spell_template` (`durationIndex` 30 for entry 168).
+//! `SpellDuration.dbc`: the duration a spell's `DurationIndex`
+//! ([`crate::spells::SpellDisplay::duration_index`]) resolves to in `Spell_C::GetSpellDuration`
+//! (`0x6ea000`), before spell-mod op 1 (`SPELLMOD_DURATION`). All three columns are signed: a few
+//! rows (427) pair a negative base with a per-level term this crate does not evaluate.
 
 use std::collections::HashMap;
 
@@ -24,21 +11,20 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 
 use crate::dbc::{i32_at, parse, u32_at};
 
-/// One `SpellDuration.dbc` row (module doc's row law).
+/// One `SpellDuration.dbc` row, in ms.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct SpellDuration {
-    /// The duration a flat (level-independent) tooltip render shows, ms. `-1` = permanent
-    /// ([`Self::is_permanent`]).
+    /// The duration a level-independent tooltip shows; -1 is permanent.
     pub base_ms: i32,
-    /// Signed ms added per caster level above the spell's `BaseLevel`; `0` for most rows.
+    /// Added per caster level above the spell's `BaseLevel`; 0 for most rows.
     pub per_level_ms: i32,
     /// The ceiling the level-scaled duration clamps to.
     pub max_ms: i32,
 }
 
 impl SpellDuration {
-    /// The client's "permanent, no timer" sentinel (`base_ms == -1`) — a stance or passive-style
-    /// aura that lasts until cancelled, not a countdown.
+    /// The permanent sentinel, `base_ms == -1`; the client tests `Duration < 0` and
+    /// `DurationPerLevel <= 0` (`0x4e456e`-`0x4e457a`), which agrees on the shipped rows only.
     pub fn is_permanent(&self) -> bool {
         self.base_ms == -1
     }
@@ -51,7 +37,7 @@ pub struct SpellDurationCatalog {
 }
 
 impl SpellDurationCatalog {
-    /// Test-only seeding (the token engine's unit tests build tiny catalogs).
+    /// Test-only seeding for the token engine's tests.
     #[cfg(test)]
     pub(crate) fn insert_for_tests(&mut self, index: u32, base_ms: i32) {
         self.durations.insert(
@@ -80,7 +66,7 @@ impl SpellDurationCatalog {
 const SPELL_DURATION: &str = "DBFilesClient\\SpellDuration.dbc";
 const SPELL_DURATION_FIELDS: usize = 4;
 
-/// Load `SpellDuration.dbc` off the patch chain ([`SpellDuration`]'s row law).
+/// Load `SpellDuration.dbc` off the patch chain.
 pub fn load_spell_durations(chain: &mut Chain) -> Result<SpellDurationCatalog> {
     let bytes = chain
         .read_file(SPELL_DURATION)
@@ -113,16 +99,13 @@ pub fn load_spell_durations(chain: &mut Chain) -> Result<SpellDurationCatalog> {
 mod tests {
     use super::*;
 
-    /// `SpellDuration.dbc` on the real data — the module doc's own probe rows. Skips without
-    /// client data.
     #[test]
     fn real_spell_durations_read_the_probed_rows() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let durations = load_spell_durations(&mut chain).expect("load SpellDuration");
 
-        // Row 30: Frost Armor's real 30-minute duration (vmangos spell_template.durationIndex==30
-        // for entry 168).
+        // Row 30: Frost Armor, spell 168 (vmangos `spell_template.durationIndex`).
         let frost_armor = durations.get(30).expect("row 30");
         assert_eq!(
             (
@@ -145,23 +128,12 @@ mod tests {
 
         assert_eq!(durations.len(), 82, "5875 ships 82 SpellDuration rows");
 
-        // Row 427 is the reason [`SpellDuration::is_permanent`]'s one-field test is not obviously
-        // safe: it carries a NEGATIVE base (`-600_000`) with a positive per-level term, and the
-        // client's own permanence test is the two-field `Duration < 0 && DurationPerLevel <= 0`
-        // (byte-verified at `0x4e456e`-`0x4e457a`, the buff cache's `untilCancelled` derivation —
-        // see `benilla::ui_aura`). Row 427 must therefore read NOT permanent under both.
+        // Row 427: a negative base with a positive per-level term, permanent under neither test.
         let scaling = durations.get(427).expect("row 427");
         assert_eq!((scaling.base_ms, scaling.per_level_ms), (-600_000, 60_000));
         assert!(!scaling.is_permanent());
     }
 
-    /// The shared helper against the **client's own** predicate, over every shipped row.
-    ///
-    /// `is_permanent()` tests one field (`base_ms == -1`); the binary tests two
-    /// (`Duration < 0 && DurationPerLevel <= 0`, `0x4e456e`-`0x4e457a`). Those are different
-    /// functions in general — a row like `{-5, 0}` would split them — so "they agree" is a fact
-    /// about the shipped 5875 data, not a theorem, and it is exactly the kind of fact that a data
-    /// change would silently invalidate. Assert it on the real file rather than assume it.
     #[test]
     fn is_permanent_matches_the_clients_two_field_test_on_every_shipped_row() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/spells/forms.rs b/crates/benilla-formats/src/spells/forms.rs
index 1988530b..9e14f06a 100644
--- a/crates/benilla-formats/src/spells/forms.rs
+++ b/crates/benilla-formats/src/spells/forms.rs
@@ -1,7 +1,5 @@
-//! `SpellShapeshiftForm.dbc` — bonus bars + the form gate's stance flag: the per-form
-//! `BonusActionBar` page the action bar flips to on shifting, and the `flags1` stance bit
-//! ([`ShapeshiftForm::is_stance`]) [`crate::spells::SpellDisplay::usable_in_form`] reads to tell a
-//! true shapeshift (blocks NOT_SHAPESHIFT spells) from a stance (doesn't).
+//! `SpellShapeshiftForm.dbc`: the per-form rows the action bar, the form gate, the spell tooltip
+//! and tracking read.
 
 use std::collections::HashMap;
 
@@ -16,58 +14,40 @@ const SHAPESHIFT_FORM: &str = "DBFilesClient\\SpellShapeshiftForm.dbc";
 /// One `SpellShapeshiftForm.dbc` row's consumed fields.
 #[derive(Clone, Debug, Default)]
 pub struct ShapeshiftForm {
-    /// **BonusActionBar** (field 1) — the stance page the bar flips to (0 = none).
+    /// `BonusActionBar` (column 1): the page the action bar flips to, 0 for none.
     pub bonus_bar: u32,
-    /// **Name** (the locstring at fields 2..10; enUS slot) — "Battle Stance", "Cat Form" —
-    /// the `SPELL_REQUIRED_FORM` "Requires %s" cell of the spell tooltip (the 0276 line law §3.6).
+    /// The enUS name (column 2), the tooltip's `SPELL_REQUIRED_FORM` "Requires %s"
+    /// (`0x52f10a`-`0x52f2ae`).
     pub name: String,
-    /// `flags1` (field 11, vmangos `SpellShapeshiftFormEntry`). Bit 0 = the form is a *stance*
-    /// (warrior stances, stealth): it does NOT count as "shapeshifted" for the form gate —
-    /// vmangos `SHAPESHIFT_FLAG_STANCE`, the `actAsShifted` fork of
-    /// [`SpellDisplay::usable_in_form`].
+    /// `flags1` (column 11): bit 0 marks a stance, bit 1 blocks cancelling the active form.
     pub flags: u32,
-    /// **creatureType** (field 12, int32 — the byte-carved `+0x30` read, wow-re
-    /// `track-predicates.md`): the form's creature-type OVERRIDE. The client's creature-type
-    /// resolver (`0x605570`) reads a shapeshifted unit's type from HERE before the creature
-    /// template or race table — a cat-form druid is a Beast (1) to the minimap tracking
-    /// predicates. `<= 0` reads Humanoid (the resolver's fallback; vmangos's own row comment).
-    /// Consumed by the tracking dots (decision 0564).
+    /// `creatureType` (column 12): the form's creature-type override, which the resolver
+    /// (`0x605570`) reads before the creature template or race, so a cat-form druid tracks as a
+    /// Beast; `<= 0` falls back to Humanoid.
     pub creature_type: i32,
-    /// **AttackIconID** (field 13, the byte-carved `+0x34` read — wow-re
-    /// `action-spell-icon-apis.md` §3.3): the form's own attack icon, resolved through
-    /// `SpellIcon.dbc` at load. The Attack action's icon resolver (`0x4e6870`) serves the
-    /// CURRENT form's icon before the main-hand weapon's, on both the action bar and the
-    /// spellbook. `None` = column 0, no form icon — fall through to the weapon (5875 data:
-    /// warrior stances and bear forms carry one; Ghost Wolf and Moonkin are 0).
+    /// `AttackIconID` (column 13) through `SpellIcon.dbc`: the Attack action shows the current
+    /// form's icon before the main-hand weapon's (`0x4e6870`); `None` falls through to the weapon.
     pub attack_icon: Option<String>,
 }
 
 impl ShapeshiftForm {
-    /// `flags1 & 1` — see [`ShapeshiftForm::flags`].
+    /// A stance (vmangos `SHAPESHIFT_FLAG_STANCE`: warrior stances, Stealth), which the form gate
+    /// ([`crate::spells::SpellDisplay::usable_in_form`]) does not count as shapeshifted.
     pub fn is_stance(&self) -> bool {
         self.flags & 1 != 0
     }
 
-    /// Clicking this form's stance button while it is ACTIVE cancels the form aura
-    /// (`CMSG_CANCEL_AURA`) — unless `flags1` bit `0x2` blocks it (`CastShapeshiftForm
-    /// 0x4b4810`'s guard at `0x4b4963`, wow-re `shapeshift-bar-api.md` VERIFIED: active + bit
-    /// set = silent no-op). 5875: the warrior stances carry `0x7` (blocked — you never cancel
-    /// OUT of a stance); druid forms (0x70/0x50), Stealth (0x1), Moonkin (0x41), Shadowform
-    /// (0x9), Ghost Wolf (0x40) all cancel.
+    /// Clicking the active form's button cancels its aura (`CMSG_CANCEL_AURA`) unless bit `0x2`
+    /// makes it a silent no-op (`CastShapeshiftForm` `0x4b4810`, guard at `0x4b4963`); the
+    /// warrior stances (`0x7`) set it on 5875.
     pub fn cancelable(&self) -> bool {
         self.flags & 0x2 == 0
     }
 }
 
-/// `SpellShapeshiftForm.dbc` → form id → the consumed row ([`ShapeshiftForm`]).
-///
-/// **BonusActionBar** is the client's own bar mapping (wow-re, byte-verified 2026-07-02:
-/// `GetBonusBarOffset 0x4e7620` returns a cached global that the `UPDATE_BONUS_ACTIONBAR`
-/// handler `0x4e4fc0` fills by indexing this DBC by the player's shapeshift form and reading
-/// `rec->field[1]` — data, not a stance switch). 5875 values: Cat(1)→1, Bear(5)/DireBear(8)→3,
-/// Battle(17)→1, Defensive(18)→2, Berserker(19)→3, Stealth(30)→1, everything else 0.
-/// **flags1** feeds the form gate (`0x612480`, [`SpellDisplay::usable_in_form`]).
-/// 32 records × 14 fields (56 B), verified on the extracted file.
+/// Load `SpellShapeshiftForm.dbc` by form id. The bonus bar is data, not a stance switch:
+/// `GetBonusBarOffset` (`0x4e7620`) returns what the `UPDATE_BONUS_ACTIONBAR` handler (`0x4e4fc0`)
+/// read from column 1 for the player's form. `flags1` feeds the form gate (`0x612480`).
 pub fn load_shapeshift_forms(chain: &mut Chain) -> Result<HashMap<u32, ShapeshiftForm>> {
     let bytes = chain
         .read_file(SHAPESHIFT_FORM)
@@ -75,15 +55,13 @@ pub fn load_shapeshift_forms(chain: &mut Chain) -> Result<HashMap<u32, Shapeshif
     let mut schema = Schema::new("SpellShapeshiftForm");
     for i in 0..14 {
         match i {
-            // Field 2: the name locstring's enUS slot (fields 2..10 = 8 locales + flag word).
+            // Column 2: the enUS slot of the name locstring (2..10, eight locales and a flag word).
             2 => schema.add_field(SchemaField::new("Name", FieldType::String)),
             _ => schema.add_field(SchemaField::new(format!("F{i}"), FieldType::UInt32)),
         }
     }
     let set = parse(&bytes, schema, "SpellShapeshiftForm.dbc")?;
-    // The AttackIconID column resolves through SpellIcon.dbc like a spell's own icon does
-    // (`0x4e6870`'s `0x4e68af`–`0x4e68da` id → path hop). 1033 tiny records — loading the map
-    // here keeps every call site's signature (six of them) untouched.
+    // AttackIconID resolves through SpellIcon.dbc like a spell's own icon (`0x4e68af`-`0x4e68da`).
     let icons = crate::dbc::load_spell_icon_map(chain)?;
     let mut map = HashMap::new();
     for r in set.records() {
diff --git a/crates/benilla-formats/src/spells/immunity.rs b/crates/benilla-formats/src/spells/immunity.rs
index eb5ca3ad..f3dcee3b 100644
--- a/crates/benilla-formats/src/spells/immunity.rs
+++ b/crates/benilla-formats/src/spells/immunity.rs
@@ -1,55 +1,33 @@
-//! The crowd-control **exemption** — `0x6e9ca0`'s aura scan and `0x6e9d70`'s immunity matcher
-//! (decision 1946; wow-re `equipped-item-and-cc-cast-gates.md` §2.3/§2.4, byte-verified).
-//!
-//! Each of the six crowd-control arms in the cast validator asks this before it refuses: *does one
-//! of the caster's own auras grant immunity to the thing blocking me?* The answer is not a flag
-//! lookup — it is a join between two `Spell.dbc` records, the spell **being cast** and the aura
-//! **doing the blocking**, and the question it really asks is "is the spell I am casting an
-//! immunity that covers this aura?" — Ice Block cast while stunned, and its kin.
-//!
-//! **Its ordinary answer is "no", and that is the point.** The matcher's first gate is
-//! `AttributesEx` bit 15 on the *cast*, which is clear on essentially every ordinary spell — so a
-//! normal cast falls out immediately and the arm refuses. What the scan changes is *which message*
-//! the refusal carries, and the rare real exemption.
+//! The crowd-control exemption each of the cast validator's six crowd-control arms checks before
+//! refusing: does the spell being cast grant immunity to the aura blocking it (Ice Block while
+//! stunned)? The scan is `0x6e9ca0`, the matcher `0x6e9d70`, whose first gate, `AttributesEx` bit
+//! 15 on the cast, is clear on almost every spell, so the scan mostly picks the refusal's message.
 
 use super::SpellDisplay;
 
-/// `SPELL_EFFECT_APPLY_AURA` — the only effect kind the matcher's loop considers (`6e9da0`).
+/// The only effect kind the matcher's loop considers (`0x6e9da0`).
 const SPELL_EFFECT_APPLY_AURA: u32 = 6;
 
-/// `AttributesEx` bit 15 on the CAST spell, which must be **set** for any immunity to be
-/// considered (`6e9d81`). INFERRED `SPELL_ATTR_EX_DISPEL_AURAS_ON_IMMUNITY`.
+/// `AttributesEx` bit 15, which the cast must carry for any immunity to count (`0x6e9d81`);
+/// inferred as `SPELL_ATTR_EX_DISPEL_AURAS_ON_IMMUNITY`.
 const ATTR_EX_DISPELS_ON_IMMUNITY: u32 = 0x0000_8000;
 
-/// `Attributes` bit 29 on the BLOCKING aura, which must be **clear** (`6e9d89`). INFERRED
-/// `SPELL_ATTR_UNAFFECTED_BY_INVULNERABILITY` — an aura that says "no immunity touches me".
+/// `Attributes` bit 29, which the blocking aura must not carry (`0x6e9d89`); inferred as
+/// `SPELL_ATTR_UNAFFECTED_BY_INVULNERABILITY`.
 const ATTR_UNAFFECTED_BY_INVULNERABILITY: u32 = 0x2000_0000;
 
-/// `AttributesEx2` bit 26 on the BLOCKING aura — the school arm's own veto (`6e9dcd`).
+/// `AttributesEx2` bit 26 on the blocking aura vetoes the school arm (`0x6e9dcd`).
 const ATTR_EX2_NO_SCHOOL_IMMUNITY: u32 = 0x0400_0000;
 
-/// The four immunity aura types the matcher switches on, all on the **cast** spell's own effects.
-/// Its window is 38..=77 (`6e9dac`'s `sub 0x26 ; cmp 0x27`); every value inside it that is not one
-/// of these four falls through to the next effect.
+/// The four immunity aura types the matcher switches on, read off the cast's own effects
+/// (`0x6e9dac`); any other value moves on to the next effect.
 const AURA_STATE_IMMUNITY: u32 = 38;
 const AURA_SCHOOL_IMMUNITY: u32 = 39;
 const AURA_DISPEL_IMMUNITY: u32 = 41;
 const AURA_MECHANIC_IMMUNITY: u32 = 77;
 
-/// **The matcher** (`0x6e9d70`) — does `cast` grant immunity to effect `aura_effect` of `aura`?
-///
-/// Two head gates, then a four-way switch over the cast's own `APPLY_AURA` effects:
-///
-/// | cast `EffectApplyAuraName[j]` | accepts when |
-/// |---|---|
-/// | 38 STATE | `cast.EffectMiscValue[j] == aura.EffectApplyAuraName[i]` |
-/// | 39 SCHOOL | the aura lacks `AttributesEx2` bit 26 **and** `cast.EffectMiscValue[j] & (1 << aura.School)` |
-/// | 41 DISPEL | `cast.EffectMiscValue[j] == aura.Dispel` |
-/// | 77 MECHANIC | `cast.EffectMiscValue[j] == aura.Mechanic` **or** `== aura.EffectMechanic[i]` |
-///
-/// Note the asymmetry the school arm carries: `School` is an **index** and `EffectMiscValue` a
-/// **mask**, so it shifts before testing. Getting that backwards silently makes every school
-/// immunity match school 0 and nothing else.
+/// The matcher (`0x6e9d70`): does `cast` grant immunity to effect `aura_effect` of `aura`? The
+/// school arm shifts because `School` is an index and `EffectMiscValue` a mask.
 pub fn grants_immunity(cast: &SpellDisplay, aura: &SpellDisplay, aura_effect: usize) -> bool {
     if cast.attributes_ex & ATTR_EX_DISPELS_ON_IMMUNITY == 0 {
         return false;
@@ -62,8 +40,8 @@ pub fn grants_immunity(cast: &SpellDisplay, aura: &SpellDisplay, aura_effect: us
         if cast.effects[j] != SPELL_EFFECT_APPLY_AURA {
             return false;
         }
-        // `EffectMiscValue` is signed in the DBC; every comparison here is against an unsigned id
-        // or a mask, so a negative value simply matches nothing.
+        // `EffectMiscValue` is signed: a negative one reads as `u32::MAX`, which equals no id but
+        // sets every school bit.
         let misc = cast.effect_misc_value[j];
         let misc_u = u32::try_from(misc).unwrap_or(u32::MAX);
         match cast.effect_apply_aura[j] {
@@ -83,29 +61,17 @@ pub fn grants_immunity(cast: &SpellDisplay, aura: &SpellDisplay, aura_effect: us
 /// What one arm's scan concluded.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub struct CcExemption {
-    /// **The arm is skipped and the cast proceeds.** True only when at least one aura of the
-    /// wanted type was found *and* every matching effect the scan reached was accepted.
+    /// The arm is skipped: an aura of the wanted type was found and every match accepted.
     pub exempt: bool,
-    /// The blocking aura's mechanic, when one was rejected — `EffectMechanic[i]` if non-zero, else
-    /// the aura's `Mechanic`. `0` means nothing was written, and the arm refuses with its **own**
-    /// reason rather than the generic "Can't do that while %s".
+    /// The rejected aura's mechanic (`EffectMechanic[i]`, else `Mechanic`), which makes the
+    /// refusal "Can't do that while %s"; 0 means the arm refuses with its own reason.
     pub mechanic: u32,
 }
 
-/// **The scanner** (`0x6e9ca0`) — walk the caster's aura slots for an aura of `wanted_aura_type`
-/// and ask [`grants_immunity`] about each matching effect.
-///
-/// Three outcomes, and the middle one is the whole reason the arms carry two reason codes:
-///
-/// - **exempt** — a matching aura existed and every matching effect was accepted;
-/// - **not exempt, mechanic written** — a matching aura was *rejected*; the refusal names its
-///   mechanic (the `0x8d` line). The scan **stops at the first rejection**;
-/// - **not exempt, mechanic 0** — no aura of that type at all.
-///
-/// `aura_ids` must be the **raw** `UNIT_FIELD_AURA` slot ids: the reference does not consult
-/// `UNIT_FIELD_AURAFLAGS` here, does not skip an "inactive" slot, and reads no duration, stack or
-/// caster state. Any non-zero, in-range id counts — which is why this takes ids rather than the
-/// filtered slot view the buff bar uses.
+/// The scanner (`0x6e9ca0`): asks [`grants_immunity`] about each `wanted_aura_type` effect on the
+/// caster's auras and stops at the first rejection, whose mechanic names the refusal (`0x8d`,
+/// `PREVENTED_BY_MECHANIC`). `aura_ids` are the raw `UNIT_FIELD_AURA` slots: the reference reads
+/// no aura flags, duration, stacks or caster, so any nonzero known id counts.
 pub fn cc_exemption<'a>(
     cast: &SpellDisplay,
     aura_ids: impl IntoIterator<Item = u32>,
@@ -118,7 +84,7 @@ pub fn cc_exemption<'a>(
             continue;
         }
         let Some(aura) = spell(id) else {
-            continue; // out of range for the id table — the reference's own bound test
+            continue; // out of the id table's range: the reference's own bound test
         };
         for i in 0..3 {
             if aura.effect_apply_aura[i] != wanted_aura_type {
@@ -172,21 +138,17 @@ mod tests {
         d
     }
 
-    /// **The two head gates**, which are why an ordinary cast is never exempt: the CAST must carry
-    /// `AttributesEx` bit 15, and the blocking AURA must not carry `Attributes` bit 29.
     #[test]
     fn an_ordinary_cast_grants_no_immunity() {
         let stun = aura(12, 12, 0, 0);
-        // A mechanic immunity that matches — but with bit 15 clear it never even looks.
+        // A matching mechanic immunity, but with bit 15 clear it never looks.
         let mut ordinary = immunity(AURA_MECHANIC_IMMUNITY, 12);
         ordinary.attributes_ex = 0;
         assert!(!grants_immunity(&ordinary, &stun, 0));
 
-        // With the bit set it matches…
         let real = immunity(AURA_MECHANIC_IMMUNITY, 12);
         assert!(grants_immunity(&real, &stun, 0));
 
-        // …unless the aura declares itself unaffected by invulnerability.
         let stubborn = SpellDisplay {
             attributes: ATTR_UNAFFECTED_BY_INVULNERABILITY,
             ..aura(12, 12, 0, 0)
@@ -194,10 +156,9 @@ mod tests {
         assert!(!grants_immunity(&real, &stubborn, 0));
     }
 
-    /// The four arms, each on its own field of the blocking aura.
     #[test]
     fn each_immunity_arm_reads_its_own_field() {
-        // 77 MECHANIC — matches the aura's `Mechanic` OR its per-effect `EffectMechanic[i]`.
+        // 77 MECHANIC: the aura's `Mechanic` or its `EffectMechanic[i]`.
         assert!(grants_immunity(
             &immunity(AURA_MECHANIC_IMMUNITY, 12),
             &aura(12, 12, 0, 0),
@@ -214,7 +175,7 @@ mod tests {
             0
         ));
 
-        // 41 DISPEL — the aura's `Dispel`.
+        // 41 DISPEL: the aura's `Dispel`.
         let magic = SpellDisplay {
             dispel: 1,
             ..aura(12, 12, 0, 0)
@@ -230,15 +191,14 @@ mod tests {
             0
         ));
 
-        // 38 STATE — the aura's own `EffectApplyAuraName[i]`.
+        // 38 STATE: the aura's `EffectApplyAuraName[i]`.
         assert!(grants_immunity(
             &immunity(AURA_STATE_IMMUNITY, 12),
             &aura(12, 0, 0, 0),
             0
         ));
 
-        // 39 SCHOOL — **`School` is an index and `EffectMiscValue` a mask**, so the arm shifts.
-        // A frost aura (school 4) is covered by a mask with bit 4 set, not by the value 4.
+        // 39 SCHOOL: a frost aura (school 4) is covered by mask bit 4, not by the value 4.
         let frost = aura(12, 12, 0, 4);
         assert!(grants_immunity(
             &immunity(AURA_SCHOOL_IMMUNITY, 1 << 4),
@@ -249,7 +209,6 @@ mod tests {
             !grants_immunity(&immunity(AURA_SCHOOL_IMMUNITY, 4), &frost, 0),
             "the raw index must not match — that is the bug this shift exists to avoid"
         );
-        // …and the aura can veto the school arm specifically.
         let unschooled = SpellDisplay {
             attributes_ex2: ATTR_EX2_NO_SCHOOL_IMMUNITY,
             ..frost
@@ -261,7 +220,6 @@ mod tests {
         ));
     }
 
-    /// **The scanner's three outcomes** — and the middle one is why every arm carries two reasons.
     #[test]
     fn the_scan_reports_exempt_rejected_or_absent() {
         let stun = aura(12, 0, 9, 0); // EffectMechanic 9, so a rejection names 9
@@ -272,7 +230,7 @@ mod tests {
             _ => None,
         };
 
-        // No aura of that type at all: not exempt, nothing named — the arm uses its OWN reason.
+        // No aura of that type: nothing named, so the arm uses its own reason.
         assert_eq!(
             cc_exemption(&plain, [0, 0, 0], 12, lookup),
             CcExemption {
@@ -281,8 +239,7 @@ mod tests {
             }
         );
 
-        // A matching aura, rejected: the arm reports the blocking MECHANIC, which turns its
-        // message into "Can't do that while %s".
+        // A matching aura, rejected: its mechanic makes the message "Can't do that while %s".
         assert_eq!(
             cc_exemption(&plain, [100], 12, lookup),
             CcExemption {
@@ -291,7 +248,6 @@ mod tests {
             }
         );
 
-        // A matching aura, accepted: EXEMPT — the arm is skipped and the cast goes out.
         assert_eq!(
             cc_exemption(&ice_block, [100], 12, lookup),
             CcExemption {
@@ -300,14 +256,13 @@ mod tests {
             }
         );
 
-        // An id the catalog does not know is skipped, exactly as the reference's bound test does.
+        // An unknown id is skipped, as the reference's bound test does.
         assert_eq!(
             cc_exemption(&ice_block, [999], 12, lookup),
             CcExemption::default()
         );
     }
 
-    /// The mechanic the scan names prefers the per-effect column and falls back to the spell's.
     #[test]
     fn the_named_mechanic_prefers_the_per_effect_column() {
         let plain = SpellDisplay::default();
diff --git a/crates/benilla-formats/src/spells/mod.rs b/crates/benilla-formats/src/spells/mod.rs
index fe8055c3..21fef33f 100644
--- a/crates/benilla-formats/src/spells/mod.rs
+++ b/crates/benilla-formats/src/spells/mod.rs
@@ -1,115 +1,17 @@
-//! Spell.dbc + SpellIcon.dbc loader — the spell **display** catalog the action bar reads
-//! (decision 0068 slice 1): a spell id resolves to its name and its icon's BLP path.
+//! `Spell.dbc` joined with `SpellIcon.dbc`: a spell id resolves to the display record the action
+//! bar, spellbook, tooltips and cast gates read.
 //!
-//! Layout — VERIFIED against build 5875 (empirical column derivation on the extracted files,
-//! 2026-07-02): `Spell.dbc` is 22357 records × **173 fields** (692 B — matches wow-re's
-//! byte-verified container fact, `system/dbc`). The two columns this catalog reads were pinned
-//! by resolving known spells against the data: **SpellIconID = column 117** (78 "Heroic Strike" →
-//! icon 856 `Ability_Rogue_Ambush`, 6673 "Battle Shout" → icon 456 `Ability_Warrior_BattleShout`;
-//! both hit column 117 uniquely) and **SpellName enUS = column 120** (all probe spells resolve
-//! their known name there and nowhere else — the head of the 8-locale + flags name block,
-//! 120..128). `SpellIcon.dbc` is 1033 records × 2 fields: `ID(0), TextureFilename(1, str)` — paths
-//! like `Interface\Icons\Ability_Rogue_Ambush` (no extension; the BLP loader appends it).
+//! A `Spell.dbc` record is 173 fields, 692 bytes (the loader's header checks, `0x55007e`,
+//! `0x5500bb`), and the client's `SpellRec` holds the row as stored: offset = column × 4, so
+//! `SpellVisual` is `+0x1cc` (column 115) and the name `+0x1e0` (column 120). The client's reads
+//! agree, such as Speed `+0x94` at `0x6e814b`, `Attributes` and `AttributesEx2` at `0x6e5922` and
+//! `0x6e591c`, `castUI` at `0x4b29bf`. Most columns were also matched by value against the
+//! vmangos `spell_template` of build 5875: only column 115 equals `spellVisual1` on 1309 rows.
 //!
-//! **SpellVisualID = column 115 · projectile Speed (f32) = column 37** (decision 0107's phase-2
-//! data plane) — pinned empirically, 2026-07-04, against the local vmangos `mangos.spell_template`
-//! (`spellVisual1`/`speed`, build ≤ 5875) cross-checked column-by-column over the extracted
-//! `Spell.dbc`: for every nonzero `spellVisual1` in `spell_template` (1309 rows sampled, ids
-//! 1..2000), column 115 is the **only** u32 column that matches, and for every nonzero `speed`
-//! (61 rows), column 37 is the only f32 column that matches — both unique across all 173 columns.
-//! Column 37 also matches wow-re's `SpellRec+0x94` lead bit-for-bit (`0x94 / 4 == 37`); the
-//! `+0x1e0` visual-id lead does **not** hold raw (`0x1e0 / 4 == 120`, already pinned above as the
-//! name string), confirming the in-memory record isn't a raw row copy for that field — column 115
-//! is the empirical column, not a translated offset. Spot-check (Fireball, entry 133):
-//! `spell_template` gives `spellVisual1=67, speed=24.0`; `Spell.dbc` row 133 reads column 115 = 67,
-//! column 37 = 24.0. `spellVisual2` (the DB's second visual column) is 0 for all but one spell in
-//! the whole table — not read here. `speed == 0` means an instant-impact spell (decision 0099's
-//! `Speed==0` gate — no missile phase); `visual == 0` means no `SpellVisual.dbc` row (silent cast).
-//!
-//! **Attributes = column 6 · AttributesEx2 = column 8** (decision 0099 phase 5's ranged-stance
-//! gate) — pinned the same way, 2026-07-05: over every `spell_template` row with a nonzero
-//! attribute word (2700 spells, ids ≤ 4000, each at its `MAX(build) ≤ 5875` row), column 6 is the
-//! **only** column matching `attributes` (runner-up 49/2700) and column 8 the only one matching
-//! `attributesEx2` — and both agree with wow-re's byte-verified in-memory reads (`SpellRec+0x18` /
-//! `+0x20`: `0x18/4 == 6`, `0x20/4 == 8`; the record layout is raw this early, before the
-//! translated tail that broke the `+0x1e0` lead above). Only two bits are consumed — the client's
-//! ranged gate, [`SpellDisplay::ranged_attack`]; `Attributes` bit `0x40` — `SPELL_ATTR_PASSIVE`
-//! (vmangos `SpellDefines.h`) — for [`SpellDisplay::passive`] (decision 0216 §8); and the
-//! spellbook **add-gate** [`SpellDisplay::in_spellbook`] (decision 0227) — `Attributes` bit `0x80`
-//! (`SPELL_ATTR_DO_NOT_DISPLAY`), bit `0x20` (`SPELL_ATTR_IS_TRADESKILL`), and **castUI = column
-//! 3** (`SpellRec+0xc`, `0xc/4 == 3` — raw this early like columns 6/8). castUI was pinned by the
-//! same wow-re byte read that pinned the gate (`system/ui/scratch/spellbook-book-build.md`, the
-//! 2026-07-08 §5), not an empirical column derivation; it reads 0 for every ordinary player spell
-//! (Fireball 133), so it is exercised only as a gate that never trips on the shown set.
-//!
-//! **SpellNameSubtext enUS = column 129** (decision 0216 §8) — pinned empirically the same way as
-//! the name column: NameEnUs's own locale block runs `120..127` (8 locales) `+128` (the name's
-//! flags word), so the very next `LocalizedString` head at `129` was the candidate; confirmed
-//! against six real spells spanning the whole rank range (Fireball 133/143/145 → "Rank 1"/"Rank
-//! 2"/"Rank 3", Frost Armor 168 → "Rank 1", Corruption 172 → "Rank 1", Fire Blast 2136 → "Rank
-//! 1") — every one resolves at column 129 and nowhere else in `118..146`. Notably even a spell's
-//! FIRST rank carries the literal text "Rank 1" (the ref's `SpellButton_UpdateButton` shows
-//! whatever `subSpellName` answers, unconditionally — no "hide Rank 1" special case, matching
-//! `SpellBookFrame.lua:379-402`).
-//!
-//! **Description enUS = column 138 · AuraDescription enUS = column 147** (decision 0274 P2, the
-//! tooltip arc) — the loc-block arithmetic predicts both exactly: NameSubtext's own 9-dword block
-//! (129 enUS + 130..136 the other 7 locales + 137 flags) is immediately followed by a Description
-//! block (138 enUS .. 146 flags), then an AuraDescription block (147 enUS .. 155 flags), landing
-//! *exactly* on the already-pinned `ManaCostPercentage = 156` (129 + 9 + 9 + 9 == 156) — two
-//! independently-verified anchors 27 columns apart with no room for anything else. Confirmed by
-//! content, not just arithmetic: read against every `spell_template` row carrying description/
-//! auraDescription text on the local vmangos DB (14278 spells), column 138 matches 13243/13258
-//! (99.89%) and column 147 matches 4215/4225 (99.76%) of the nonempty rows verbatim (raw,
-//! un-substituted `$`-token text) — the same noise floor the *already-shipped* name(120)/
-//! nameSubtext(129) pins show against this same DB (14260/14278, 6015/6020: a handful of
-//! vmangos-only QA/test spells diverge from the shipped client file, not a column slip). Spot
-//! checks: Fireball 133 → "Hurls a fiery ball that causes $s1 Fire damage…"; Frost Armor 168's aura
-//! text → "Increases Armor by $s1 and may slow attackers."; Fire Blast 2136 (a direct-damage spell
-//! with no aura) → empty aura text.
-//!
-//! **DurationIndex = column 30 · CastingTimeIndex = column 18 · ProcChance = column 25** — pinned
-//! empirically 2026-07-10 against the local vmangos `spell_template` (every entry at its own
-//! `MAX(build) ≤ 5875` row, the module's established cross-check, ~22357 spells): each is the
-//! *unique* column (of all 173) matching its named vmangos field on every nonzero-valued row —
-//! `durationIndex` 11350/11350, `castingTimeIndex` 22354/22354, `procChance` 22129/22129, all
-//! 100%. End-to-end confirmation through the new [`crate::SpellCastTimeCatalog`]/
-//! [`crate::SpellDurationCatalog`]: Fireball 133 → CastingTimeIndex 16 → `SpellCastTimes.dbc` row
-//! 16 → 1500 ms; Frost Armor 168 → DurationIndex 30 → `SpellDuration.dbc` row 30 → 1,800,000 ms
-//! (30 min) — both match this arc's own independently-stated expectation. This pin surfaced a
-//! conflict with wow-re's then-current `wave-cooldown.md`, which labeled `[rec+0x48]` (== column
-//! 18) *DurationIndex*; the dispatched wow-re §5 cross-check (2026-07-10, wow-re commit
-//! `f2c563c9`) **byte-confirmed this module and corrected the note** — the mislabel ran deeper
-//! than one offset: `Spell_C::GetCastTime` is `0x6e3340` (`6e336e: mov eax,[edi+0x48]` —
-//! CastingTimeIndex → `SpellCastTimes` recordsById `[0xc0d878]`, spell-mod op `0xa` =
-//! SPELLMOD_CASTING_TIME), the real `Spell_C::GetDuration` is `0x6ea000` (`6ea016: mov
-//! eax,[edi+0x78]` — DurationIndex → `SpellDuration` recordsById `[0xc0d828]`, spell-mod op `1` =
-//! SPELLMOD_DURATION), and `0x6e31b0` — the note's old "GetCastTime" — is `GetPowerCost`. The
-//! in-memory SpellRec is a direct on-disk row image this deep (offset = column×4, anchored by
-//! the verified neighbours `+0x4c`/col19 and `+0x90`/col36), so the byte reads and this
-//! empirical map agree exactly: `0x48/4 == 18`, `0x78/4 == 30`.
-//!
-//! **Per-effect arrays** (each `[3]`, one slot per effect — pinned the same value-match way, same
-//! cross-check population, 2026-07-10): `EffectDieSides` 64-66 (die roll, **signed**),
-//! `EffectBaseDice` 67-69, `EffectBasePoints` 76-78 (the roll's floor, **signed** — Auto Shot 75 /
-//! Feign Death 5384 both carry `-1`, a weapon-damage/no-fixed-roll sentinel), `EffectRadiusIndex`
-//! 88-90 (`SpellRadius.dbc` row; Battle Shout 6673 carries 9, its "$a1 yards" party radius),
-//! `EffectApplyAuraName` 91-93 (== the already-pinned [`COL_EFFECT_APPLY_AURA_1`]; 9612/9614,
-//! 2488/2490, 595/595 — reused, not re-derived), `EffectAmplitude` 94-96 (periodic-tick ms;
-//! Fireball 133's DoT tail ticks every 2000 ms), `EffectMultipleValue` 97-99 (f32),
-//! `EffectChainTarget` 100-102 (100/101 at 113/10 nonzero samples, 100%; 102 has only *one*
-//! nonzero row in the whole table — entry 26044, `1,1,1` across 100-102 — but lands exactly on the
-//! consecutive-triple pattern every other array here confirms; flagged as the thinnest-evidence pin
-//! of the batch), `EffectTriggerSpell` 109-111 (== the already-pinned [`COL_EFFECT_TRIGGER_1`];
-//! Frost Armor 168's own description text names the exact spell its `EffectTriggerSpell[1]`
-//! resolves to — `$6136s2%`/`$6136s1%`, `6136` read straight off column 110). All match 100% except
-//! `Effect[0]`/`Effect[1]`/`EffectApplyAuraName[0]`/`EffectApplyAuraName[1]`, which match all but 2
-//! rows each (the same 4 vmangos test entries — 11094/13043/11189/28332 — whose DB row diverges
-//! from the shipped client file; not a column slip).
-//!
-//! Remaining columns (targeting/school-specific secondary fields, item-set data) stay dropped
-//! until a consumer exists — the bar/book/tooltip want a face and a description, not a full spell
-//! simulator (we render and speak the protocol; the server simulates).
+//! A localized string is eight locale dwords and a flags dword: name 120-128, subtext 129-137,
+//! description 138-146, aura description 147-155, then `ManaCostPercentage` at 156. The
+//! per-effect fields are `[3]` arrays in consecutive columns from `Effect` at 61.
+//! `SpellIcon.dbc` is `ID`, `TextureFilename` (no extension).
 
 mod cast_times;
 mod dispel_types;
@@ -145,104 +47,41 @@ use crate::dbc::{f32_at, i32_at, parse, str_at, u32_at};
 const SPELL: &str = "DBFilesClient\\Spell.dbc";
 
 const SPELL_FIELDS: usize = 173;
-/// `Category` (`SpellRec+0x8`, `0x8/4 == 2` — raw like columns 3/6/8): the shared-cooldown
-/// category (`SpellCategory.dbc` id) — potions 4, Aimed Shot 2, … `0` = no category. Pinned
-/// empirically 2026-07-10 against the vmangos `spell_template` rows (12 spells incl. Charge
-/// cat 44, Taunt 82, Lay on Hands 56, Hunter's Mark 411, wand Shoot 351 — all match column 2).
+/// `Category` (`+0x8`): the shared-cooldown `SpellCategory.dbc` id, such as potions 4.
 const COL_CATEGORY: usize = 2;
 const COL_CAST_UI: usize = 3;
-/// `RecoveryTime` (`SpellRec+0x4c`, `0x4c/4 == 19`) / `CategoryRecoveryTime` (`+0x50`, 20) — the
-/// spell's own cooldown ms and its category's shared cooldown ms, the two inputs of the client's
-/// `StartCooldown 0x6e2c60` + the `SMSG_SPELL_COOLDOWN` handler `0x6e9460` (wow-re
-/// `wave-cooldown.md`/`wave-handlers.md`, VERIFIED). Same 12-spell empirical pin as
-/// [`COL_CATEGORY`] (Feign Death 30000 rec, Charge 15000 catRec, Lay on Hands 3600000 catRec).
+/// `RecoveryTime` (`+0x4c`) and `CategoryRecoveryTime` (`+0x50`), in ms, read by `StartCooldown`
+/// (`0x6e2c60`) and the `SMSG_SPELL_COOLDOWN` handler (`0x6e9460`).
 const COL_RECOVERY_TIME: usize = 19;
 const COL_CATEGORY_RECOVERY_TIME: usize = 20;
-/// `InterruptFlags` (21, `SpellRec+0x54`) / `AuraInterruptFlags` (22, `SpellRec+0x58`) /
-/// `ChannelInterruptFlags` (23, `SpellRec+0x5c`) — what breaks a cast / a live aura / a running
-/// channel. Pinned empirically 2026-07-17 by the module's established cross-check (every vmangos
-/// `spell_template` row at its `MAX(build) ≤ 5875`): column 21 is the **unique** column matching
-/// `interruptFlags` on all 6389 nonzero rows, column 22 unique on all 582 nonzero
-/// `auraInterruptFlags` rows, column 23 unique on all 343 nonzero `channelInterruptFlags` rows,
-/// and the raw-row arithmetic agrees (offset = column×4, chain-locked between the verified
-/// neighbors `+0x50`/col 20 and col 25). Spot checks: Fireball 133 interrupt `0xf`, channel 0;
-/// Arcane Missiles 5143 channel `0x7c0c`; First Aid 746 interrupt 0, channel `0x3c0e`. Consumed
-/// by the cast bar's local self-cancel (`benilla::ui_cast`) and the cast-initiation moving gate
-/// (`benilla::ui_action`, decision 0862), where the bit semantics are documented.
+/// The three interrupt masks (`+0x54`, `+0x58`, `+0x5c`): cast, applied aura, running channel.
 const COL_INTERRUPT_FLAGS: usize = 21;
 const COL_AURA_INTERRUPT_FLAGS: usize = 22;
 const COL_CHANNEL_INTERRUPT_FLAGS: usize = 23;
-/// `powerType` (31) / `manaCost` (32) / `ManaCostPercentage` (156) — the cast-cost triple
-/// `IsUsableAction`'s not-enough-power verdict reads. Same empirical pin (Taunt/Charge pwr 1 =
-/// rage; Pyroblast cost 125; pct pinned on its own nonzero rows 370/475/526/527/528 → 10/10/9/18/15).
+/// The cost triple (`powerType`, `manaCost`, `ManaCostPercentage`) `IsUsableAction` checks.
 const COL_POWER_TYPE: usize = 31;
 const COL_MANA_COST: usize = 32;
 const COL_MANA_COST_PCT: usize = 156;
-/// `manaCostPerlevel` (33) / `manaPerSecond` (34) — the vmangos field order between `manaCost`
-/// 32 and `manaPerSecondPerLevel` 35. The per-level column is `0x6e31b0`'s
-/// `(level − spellLevel) · perLevel` term (72 nonzero rows, all creature spells); the
-/// per-second column is the tooltip's `_PER_TIME` composite (Health Funnel 755 reads 5).
-/// Column 35 is all-zero across the whole 5875 file (the catalog test's scan) and stays
-/// unparsed. (1074)
 const COL_MANA_COST_PER_LEVEL: usize = 33;
 const COL_MANA_PER_SECOND: usize = 34;
-/// `rangeIndex` (`SpellRec+0x90`, `0x90/4 == 36`) — the `SpellRange.dbc` row the byte-verified
-/// `GetMinMaxRange 0x6e3480` resolves (wow-re `wave-cooldown.md`). Same empirical pin (Auto
-/// Shot/Aimed Shot 114, Throw 74, Charge 95, Fireball 35).
+/// `rangeIndex` (`+0x90`), resolved by `GetMinMaxRange` (`0x6e3480`).
 const COL_RANGE_INDEX: usize = 36;
-/// `modalNextSpell` — `Spell.dbc` **column 38** (`SpellRec + 0x98`): a spell the client casts **by
-/// itself**, with no user input, when the server's `SMSG_CAST_RESULT` for this spell arrives. See
-/// [`SpellDisplay::modal_next_spell`] for the whole law and the shipped-file census.
-///
-/// The column's position is chain-locked the same way the interrupt trio's is (offset = column×4,
-/// between the verified `+0x90` = 36 rangeIndex and `+0xf4` = 61 Effect[0]); the name is wow-re's
-/// (`modalnext-chain-cast.md` §3/§11) and the community's. This repo's own reason to trust it is
-/// the distribution: non-zero on 57 of 22357 rows, and 52 of those 57 name spell **75, Auto Shot**,
-/// every one of them a hunter shot. A column that fell where this one falls by accident could not
-/// look like that.
+/// `modalNextSpell` (`+0x98`): 52 of its 57 nonzero rows are hunter shots naming Auto Shot.
 const COL_MODAL_NEXT_SPELL: usize = 38;
-/// `StartRecoveryCategory` (`SpellRec+0x274`, `0x274/4 == 157`) / `StartRecoveryTime` (`+0x278`,
-/// 158) — the **global-cooldown** pair `StartGlobalCooldown 0x6e2de0` reads at the local
-/// cast-send (`0x6e58fb`, wow-re `wave-cast.md`, VERIFIED). Category 133 / 1500 ms for ordinary
-/// spells; 0/0 for the GCD-free (Attack, Auto Shot, wand Shoot). Same 12-spell empirical pin.
+/// `StartRecoveryCategory` (`+0x274`) and `StartRecoveryTime` (`+0x278`): the global cooldown
+/// `StartGlobalCooldown` (`0x6e2de0`) starts at the cast send (`0x6e58fb`).
 const COL_START_RECOVERY_CATEGORY: usize = 157;
 const COL_START_RECOVERY_TIME: usize = 158;
-/// `PreventionType` (`SpellRec+0x294`, `0x294/4 == 165`) — see [`SpellDisplay::prevention_type`]
-/// for the two-way pin that separates it from its `DmgClass` neighbour at 164.
 const COL_PREVENTION_TYPE: usize = 165;
-/// `SpellFamilyName` (`SpellRec+0x280`, `0x280/4 == 160`) / `SpellFamilyFlags` low+high
-/// (`+0x284`/`+0x288`, 161/162) — the talent spell-modifier gate and its row selector, read by
-/// `GetSpellModifiers 0x6e6b30` at `6e6b38`/`6e6b46` and `6e6b83` (wow-re
-/// `system/spell/scratch/spellmod-table-law.md` §5). See [`SpellDisplay::spell_family`] and
-/// [`SpellDisplay::spell_family_flags`]; the shipped-file anchors are in
-/// [`catalog_tests`].
 const COL_SPELL_FAMILY_NAME: usize = 160;
 const COL_SPELL_FAMILY_FLAGS_LOW: usize = 161;
-/// `Targets` (`SpellRec+0x34`, `0x34/4 == 13`) — the wire `TARGET_FLAG_*` seed mask the cast-arm
-/// loads into its targeting flag_word (`0x6e525a`, wow-re `wave-cast.md`, VERIFIED). Empirical
-/// pin against the binder's bit semantics: Resurrection 2006 = `0x8000` (corpse-ally bit 15),
-/// Skinning 8613 = `0x402` (unit bit 1 + requires-explicit-selection bit 10), ground AoEs carry
-/// `0x40` (dest location), enchant/poison rows `0x10` (item). `0` for ordinary casts.
+/// `Targets` (`+0x34`): the seed the cast arm loads into its targeting word (`0x6e525a`).
 const COL_TARGETS: usize = 13;
-/// `EffectImplicitTargetA[0]` (`SpellRec+0x148`, `0x148/4 == 82`) — the implicit-target enum the
-/// cast-arm's 62-case switch keys on (jump-table `0x6e5484`) to set/clear individual flag_word
-/// bits. Empirical pin against the switch arms: Fireball 133 / Charge 100 = 6 (→ hostile bit 7),
-/// Ice Armor 7302 / Feign Death 5384 = 1 (self — clears bit 10), Arcane Intellect 1459 / Lesser
-/// Heal 2050 = 21 (→ assist bit 8), Battle Shout 6673 = 20 (party-area — a no-op arm).
+/// `EffectImplicitTargetA[0]` (`+0x148`), the key of the cast arm's 62-case switch (`0x6e5484`).
 const COL_IMPLICIT_TARGET_A1: usize = 82;
-/// `EffectImplicitTargetB[0]` (`SpellRec+0x154`, `0x154/4 == 85`) — the second implicit-target
-/// column, walked beside A by the hostility classifier `0x6ea280` ([`SpellDisplay::is_harmful`]).
-/// Empirical pin: Frost Nova 122 carries A = 22 (caster coordinates) and B = 15 (src-area enemy)
-/// — harmful through B alone.
+/// `EffectImplicitTargetB[0]` (`+0x154`), walked beside A by the classifier `0x6ea280`.
 const COL_IMPLICIT_TARGET_B1: usize = 85;
-/// The usable-walk columns (`IsSpellUsableNow 0x6e3d60`'s §2a gate table, wow-re
-/// `action-button-state-api.md`, byte-verified 2026-07-10; column = SpellRec-offset/4).
-/// Empirical pins on the real 5875 data: Claw 1082 Stances `0x1` (cat = form 1), Ambush 8676
-/// Stances `0x20000000` (stealth = form 30) + EquippedItemClass 2 / SubClassMask `0x8000`
-/// (dagger), Execute 5308 TargetAuraState 2 (healthless-20%) + Stances `0x50000`
-/// (battle/berserker), Revenge 6572 CasterAuraState 1 (defense), Auto Shot 75 EquippedItemClass
-/// 2 / SubClassMask `0x4000c` (bows/guns/crossbows), Slow Fall 130 Reagent[0] 17056 ×1
-/// (Light Feather).
+/// The usable walk's gate columns (`IsSpellUsableNow` `0x6e3d60`).
 const COL_STANCES: usize = 11;
 const COL_STANCES_NOT: usize = 12;
 const COL_CASTER_AURA_STATE: usize = 16;
@@ -252,437 +91,243 @@ const COL_REAGENT_1: usize = 42;
 const COL_REAGENT_COUNT_1: usize = 50;
 const COL_EQUIPPED_ITEM_CLASS: usize = 58;
 const COL_EQUIPPED_ITEM_SUBCLASS_MASK: usize = 59;
-/// `EquippedItemInventoryTypeMask` — chain-locked between `COL_EQUIPPED_ITEM_SUBCLASS_MASK`
-/// (`SpellRec+0xec`) and `COL_EFFECT_1` (`+0xf4`), i.e. exactly the `+0xf0` the reference's
-/// item-target gate reads at `0x495d60` @ `495e4d`. Decision 0923.
+/// `EquippedItemInventoryTypeMask` (`+0xf0`), read by the item-target gate `0x495d60`.
 const COL_EQUIPPED_ITEM_INVENTORY_TYPE_MASK: usize = 60;
-/// `RequiresSpellFocus` (`SpellRec+0x3c`, `0x3c/4 == 15` — the run the pinned neighbors chain-lock:
-/// `Stances` 11-12, `Targets` 13, `CasterAuraState` 16). A `SpellFocusObject.dbc` id that must be
-/// nearby to cast (1 Anvil, 3 Forge, 4 Cooking Fire — [`crate::spell_focus`]); 0 = none. Verified
-/// against live vmangos `spell_template` rows on the real 5875 file (catalog_tests).
 const COL_REQUIRES_SPELL_FOCUS: usize = 15;
-/// `Dispel` — the `SpellDispelType.dbc` id (`SpellRec+0x10`; the byte offset chain-locks it to
-/// `COL_CAST_UI` at `+0xc` and `COL_ATTRIBUTES` at `+0x18`). Decision 0257.
 const COL_DISPEL: usize = 4;
-/// `School` (`SpellRec+0x4`, `0x4/4 == 1`) — see [`SpellDisplay::school`].
 const COL_SCHOOL: usize = 1;
-/// `Mechanic` (`SpellRec+0x14`, `0x14/4 == 5`) — see [`SpellDisplay::mechanic`].
 const COL_MECHANIC: usize = 5;
-/// `EffectMechanic[0]` (`SpellRec+0x13c`, `0x13c/4 == 79`) — see [`SpellDisplay::effect_mechanic`].
 const COL_EFFECT_MECHANIC_1: usize = 79;
 const COL_ATTRIBUTES: usize = 6;
-/// `AttributesEx` (`SpellRec+0x1c` — chain-locked between `COL_ATTRIBUTES` at `+0x18` and
-/// `COL_ATTRIBUTES_EX2` at `+0x20`).
 const COL_ATTRIBUTES_EX: usize = 7;
 const COL_ATTRIBUTES_EX2: usize = 8;
-/// `AttributesEx3` (`SpellRec+0x24` — the next word in the same chain-locked run). Consumed by
-/// [`SpellDisplay::melee_white_damage`]'s bit 15.
 const COL_ATTRIBUTES_EX3: usize = 9;
 const COL_SPEED: usize = 37;
-/// `Effect[0]` (`SpellRec+0xf4`, `0xf4/4 == 61` — raw this early, like columns 6/8/37): the
-/// spell's first effect type. The action bar / spellbook auto-attack icon substitution keys on it
-/// (decision 0231): `Effect[0] == SPELL_EFFECT_ATTACK (78)` is the melee auto-attack, verified at
-/// the bytes in wow-re (`system/ui/scratch/attack-icon-substitution.md`, resolvers `0x4b3f8a` /
-/// `0x4e59de` both `cmp [SpellRec+0xf4], 0x4e`).
 const COL_EFFECT_1: usize = 61;
-/// `EffectMiscValue[0]` (column 106). The Spell.dbc effect block is 15 parallel `[3]` arrays from
-/// `Effect@61`; `EffectMiscValue` is the 16th, at `61 + 15×3 = 106` — cross-checked by `SpellVisual`
-/// landing at its known column 115 (`106 + 3×3`). For a `SPELL_EFFECT_OPEN_LOCK` effect this is the
-/// `LockType` index the spell opens (mining = 3, herbalism = 2, per `Lock.dbc`).
+/// `EffectMiscValue[0]`, `61 + 15 × 3`: the 16th `[3]` array from `Effect`.
 const COL_EFFECT_MISC_1: usize = 106;
-/// `EffectTriggerSpell[0]` — column 109 (`61 + 3×16`, past the 16 effect-array blocks: the three
-/// `Effect`s at 61 are followed by die/base/aura/misc/etc. blocks, `EffectMiscValue` at 106 then
-/// `EffectTriggerSpell` at 109, `SpellVisual` at 115). For a `SPELL_EFFECT_LEARN_SPELL` effect this is
-/// the taught spell.
+/// `EffectTriggerSpell[0]`, `61 + 16 × 3`.
 const COL_EFFECT_TRIGGER_1: usize = 109;
-/// `SpellEffects` value `36` — `SPELL_EFFECT_LEARN_SPELL`: a trainer's learn wrapper carries it, and
-/// its `EffectTriggerSpell` is the ability the player ends up with (decision 0247's taught spell).
+/// `SPELL_EFFECT_LEARN_SPELL`: teaches its `EffectTriggerSpell`, as a trainer's wrapper does.
 pub const SPELL_EFFECT_LEARN_SPELL: u32 = 36;
-/// `SpellEffects` value `57` — `SPELL_EFFECT_LEARN_PET_SPELL`, the learn wrapper's pet twin. The
-/// trainer's **icon** law accepts either in its three-slot wrapper scan (byte-verified: the paired
-/// `cmp ecx,0x24` / `cmp ecx,0x39` at `0x4d8ff5`/`0x4d8ffa`, wow-re
-/// `system/ui/scratch/spell-icon-substitution-law.md` §1). [`SpellCatalog::learned_spell`]'s
-/// **display** hop deliberately stays 36-only — that is decision 0247's verified grouping hop, and
-/// widening it is a separate question nothing has asked.
+
+/// One learn effect, in the slot order the trainer's state re-evaluator reads (`0x4d7d40`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LearnEffect {
+    /// `SPELL_EFFECT_LEARN_SPELL`: teaches `EffectTriggerSpell`.
+    Spell(u32),
+    /// `SPELL_EFFECT_SKILL_STEP`: raises skill line `skill` (`EffectMiscValue`) to `step`,
+    /// `EffectBasePoints + EffectDieSides`.
+    SkillStep { skill: u32, step: u32 },
+    /// `SPELL_EFFECT_LEARN_PET_SPELL`: teaches the pet `EffectTriggerSpell`.
+    PetSpell(u32),
+}
+/// `SPELL_EFFECT_LEARN_PET_SPELL`: the trainer's icon accepts it or 36 in any slot (`0x4d8ff5`),
+/// but [`SpellCatalog::learned_spell`] follows 36 only.
 pub const SPELL_EFFECT_LEARN_PET_SPELL: u32 = 57;
-/// `SpellEffects` value `44` — `SPELL_EFFECT_SKILL_STEP`: the effect that raises a profession's
-/// *potential* (Apprentice → Journeyman → …). It is the whole of what a **tradeskill trainer's**
-/// display tree partitions on — the builder tests the WIRE spell's three effect slots for it and
-/// reads nothing else (`0x4d77b6`, decision 1124; benilla-app's `ui_trainer::law::service_group` is
-/// the transcription).
+/// `SPELL_EFFECT_SKILL_STEP`: raises a profession's cap; a tradeskill trainer's tree partitions
+/// on it alone, in the wire spell's three slots (`0x4d77b6`).
 pub const SPELL_EFFECT_SKILL_STEP: u32 = 44;
 
-/// `SpellEffects` value `SPELL_EFFECT_OPEN_LOCK` — the lock-opening effect the GameObject
-/// interact-cast matches (decision 0239; RE `cursor-system.md` §8, the client's
-/// `cmp [SpellRec+0xf4], 0x21`). A spell carrying it opens the `LockType` its `EffectMiscValue` names.
+/// `SPELL_EFFECT_OPEN_LOCK`, which the GameObject interact-cast matches (`0x5f84a1`).
 const SPELL_EFFECT_OPEN_LOCK: u32 = 0x21;
-/// `baseLevel` — column 28 (`SpellRec+0x70`), the level term the effect-value walk subtracts at
-/// `0x6e3826`/`0x6e3854` and the cast-time scaling's base (`0x6e3340`). **Not** the DBC's
-/// `spellLevel` (column 29, `+0x74`) — nothing here reads that one; the field carried that name
-/// for a while (wow-re `openlock-spell-store-order.md` §4a pinned the split at the bytes).
-/// Pinned by value on the extracted 5875 file: Pick Lock 1804 and Fireball rank 1 read `1`, the
-/// professions' openers `0`.
+/// `baseLevel` (`+0x70`, not `spellLevel`), read by the effect-value walk at `0x6e3854`.
 const COL_BASE_LEVEL: usize = 28;
-/// `maxLevel` — column 27 (`SpellRec+0x6c`), the cap on the skill-derived level term in an
-/// opener's value: the player's skill is clamped to `maxLevel × 5` at `0x5ea6e3` before the
-/// `/5` (`0x6e3195`); `0` = uncapped (the professions' openers read 0 here, and their §4a table
-/// rows would compute 0 under an unconditional clamp). Same wow-re record.
+/// `maxLevel` (`+0x6c`): 0 is uncapped, as on the profession openers, not a cap of 0.
 const COL_MAX_LEVEL: usize = 27;
-/// `spellLevel` — column 29 (`SpellRec+0x74`), the DBC's actual spellLevel. Parsed for the ONE
-/// consumer whose recorded law names `+0x74` (the Beast Training rank comparator,
-/// `benilla-ui` `craft.rs`); before [`COL_BASE_LEVEL`]'s rename that consumer was silently fed
-/// column 28.
 const COL_SPELL_LEVEL: usize = 29;
-/// `EffectApplyAuraName[0]` (column 91, `61 + 10×3` — tenth of the effect-`[3]` blocks; pinned on
-/// the extracted 5875 file: every form spell — Battle Stance 2457, Bear 5487, Cat 768, Stealth
-/// 1784, Moonkin 24858 — carries `36` here, and columns 94-96 don't). The stance bar's
-/// admission key (wow-re `shapeshift-bar-api.md`, VERIFIED): `== SPELL_AURA_MOD_SHAPESHIFT`.
+/// `EffectApplyAuraName[0]`, `61 + 10 × 3`; the stance bar admits by it (`0x4b2810`).
 const COL_EFFECT_APPLY_AURA_1: usize = 91;
-/// `AuraType` value `36` — `SPELL_AURA_MOD_SHAPESHIFT` (vmangos `SpellAuraDefines.h`): the aura
-/// that changes the form byte; its `EffectMiscValue` is the `SpellShapeshiftForm.dbc` form id.
+/// `SPELL_AURA_MOD_SHAPESHIFT`: its `EffectMiscValue` is the `SpellShapeshiftForm.dbc` id.
 const SPELL_AURA_MOD_SHAPESHIFT: u32 = 36;
 const COL_ICON_ID: usize = 117;
-/// `ActiveIconID` (column 118, `SpellRec+0x1d8` — right after `SpellIconID`, wow-re
-/// `shapeshift-bar-api.md` VERIFIED): the icon shown while the spell's form is ACTIVE, when
-/// nonzero (druid forms carry icon 122, the "dismiss form" paw; warrior stances carry 0).
+/// `ActiveIconID` (`+0x1d8`, read at `0x4b4754`): druid forms carry 122, the dismiss paw.
 const COL_ACTIVE_ICON_ID: usize = 118;
-/// `StanceBarOrder` (column 166, `SpellRec+0x298`, SIGNED — wow-re `shapeshift-bar-api.md`
-/// VERIFIED: the stance-bar sort comparator `0x4b2bb0` orders ascending by it, `-1` last, spell
-/// id as the tiebreak). Pinned on the extracted file: Battle 0 / Defensive 1 / Berserker 2,
-/// Bear 0 / Aquatic 1 / Cat 2 / Travel 3 / Moonkin 4, Stealth −1.
+/// `StanceBarOrder` (`+0x298`, signed): `0x4b2bb0` sorts ascending, -1 last, ties by spell id;
+/// Stealth is -1.
 const COL_STANCE_BAR_ORDER: usize = 166;
 const COL_VISUAL_ID: usize = 115;
 const COL_NAME_ENUS: usize = 120;
 const COL_NAME_SUBTEXT_ENUS: usize = 129;
-/// `Description` enUS (module docs — the loc-block arithmetic + content match).
 const COL_DESCRIPTION_ENUS: usize = 138;
-/// `AuraDescription` enUS (module docs).
 const COL_AURA_DESCRIPTION_ENUS: usize = 147;
 
-/// `DurationIndex` (`SpellRec+0x78`, `0x78/4 == 30` — byte-confirmed by the wow-re §5, module
-/// docs: `Spell_C::GetDuration 0x6ea000`'s own read). `0` = no row (an instant-hit spell with no
-/// periodic/aura tail — Fire Blast 2136).
+/// `DurationIndex` (`+0x78`): `Spell_C::GetSpellDuration` (`0x6ea000`) looks it up at `0xc0d828`.
 const COL_DURATION_INDEX: usize = 30;
-/// `CastingTimeIndex` (`SpellRec+0x48`, `0x48/4 == 18` — byte-confirmed by the wow-re §5, module
-/// docs: `Spell_C::GetCastTime 0x6e3340`'s own read).
+/// `CastingTimeIndex` (`+0x48`): `Spell_C::GetCastTime` (`0x6e3340`) looks it up at `0xc0d878`.
 const COL_CASTING_TIME_INDEX: usize = 18;
-/// `ProcChance` (module docs) — percent, `101` is vmangos's own "always proc, no roll" convention
-/// on top of the DBC's raw 0-100 scale (carried through unexamined; not a client-side reinterpretation).
 const COL_PROC_CHANCE: usize = 25;
 
-/// The per-effect `[3]` arrays feeding the $-token tooltip engine (decision 0274 P2) — each column
-/// is that family's slot-0 entry; slots 1/2 are `+1`/`+2` (module docs' consecutive-triple law,
-/// confirmed for every array below). `EffectDieSides`/`EffectBasePoints` are **signed** (a roll's
-/// floor can be negative, and `-1` is the weapon-damage/no-fixed-roll sentinel — Auto Shot,
-/// Feign Death); the rest are their natural unsigned/float DBC type.
+/// The per-effect `[3]` arrays, each constant slot 0; die sides and base points are signed.
 const COL_EFFECT_DIE_SIDES_1: usize = 64;
 const COL_EFFECT_BASE_DICE_1: usize = 67;
-/// `EffectDicePerLevel[0]` — column 70 (`SpellRec+0x118`), the integer per-level term of the
-/// effect-value walk (decision 0752).
 const COL_EFFECT_DICE_PER_LEVEL_1: usize = 70;
-/// `EffectRealPointsPerLevel[0]` — column 73 (`SpellRec+0x124`), the **float** per-level term:
-/// 5.0 on every profession opener, 0.6 on Fireball rank 1 — the two anchors that pin the column.
 const COL_EFFECT_REAL_POINTS_PER_LEVEL_1: usize = 73;
 const COL_EFFECT_BASE_POINTS_1: usize = 76;
 const COL_EFFECT_RADIUS_INDEX_1: usize = 88;
 const COL_EFFECT_AMPLITUDE_1: usize = 94;
 const COL_EFFECT_MULTIPLE_VALUE_1: usize = 97;
 const COL_EFFECT_CHAIN_TARGETS_1: usize = 100;
-/// `EffectItemType[0]` — column 103, the `[3]` block between `EffectChainTarget` (100-102) and
-/// `EffectMiscValue` (106-108) in the module docs' parallel-array walk. The item entry a
-/// `SPELL_EFFECT_CREATE_ITEM` effect creates — the crafting book's product (0437). Verified
-/// against live vmangos rows on the real 5875 file (catalog_tests: 2963 → 2996 Bolt of Linen
-/// Cloth, 2738 → 2845 Copper Axe).
 const COL_EFFECT_ITEM_TYPE_1: usize = 103;
-// `EffectApplyAuraName[0]` reuses [`COL_EFFECT_APPLY_AURA_1`] (91) and `EffectTriggerSpell[0]`
-// reuses [`COL_EFFECT_TRIGGER_1`] (109) — both already pinned above for the shapeshift/learn-spell
-// hops; the tooltip arc exposes the full `[3]` array off the same columns instead of re-deriving.
 
-/// `AttributesEx3` bit `0x8000` — damage renders melee-white (`SPELL_ATTR3_NORMAL_RANGED_ATTACK`;
-/// the combat-text emitter's `B`-bit flip, wow-re `combattext-color-law.md`).
+/// `SPELL_ATTR3_NORMAL_RANGED_ATTACK`: damage floats melee white (`0x6128b0`).
 const ATTR_EX3_NORMAL_RANGED_ATTACK: u32 = 0x8000;
-/// `AttributesEx3` bit `0x4` — **the cast bar shows no name for this spell**
-/// (`SPELL_ATTR_EX3_NO_CASTING_BAR_TEXT`, vmangos `Spells/SpellDefines.h:907`). Decision 1312.
-///
-/// Exactly three rows in the shipped 5875 file carry it, and one of them is *named after the bit*:
-/// 6477 "Opening", **22810 "Opening - No Text"**, 26380 "zzOLDSummon Mouth Tentacle Visual". That
-/// placeholder name is not a string benilla was ever meant to render — it is Blizzard's own note
-/// to themselves about what this attribute does to the spell, and it reached a player's screen
-/// because we printed the name unconditionally.
+/// `SPELL_ATTR_EX3_NO_CASTING_BAR_TEXT` (vmangos `SpellDefines.h:907`).
 const ATTR_EX3_NO_CASTING_BAR_TEXT: u32 = 0x4;
-/// `AttributesEx3` bit 13 (`0x2000`) — **this spell shows no CHANNEL bar at all**. The channel
-/// handler's own suppressor, and a *total* one: `0x6e7595 test ch,0x20` on `[SpellRec+0x24]`
-/// (`ch` = bits 8-15, so bit 13 — not [`ATTR_EX3_NO_CASTING_BAR_TEXT`]'s bit 2) jumps straight to
-/// the return, so `SPELLCAST_CHANNEL_START` never fires. Exactly two rows in the shipped 5875 file
-/// carry it, both 24322/24323 "Blood Siphon".
+/// `AttributesEx3` bit 13: `0x6e7595` tests it as `0x20` in the word's second byte.
 const ATTR_EX3_NO_CHANNEL_BAR: u32 = 0x2000;
-/// `AttributesEx` bit 29 (`0x2000_0000`) — **the channel bar prints this spell's own name**
-/// instead of the generic word. `0x6e759a test DWORD PTR [SpellRec+0x1c],0x20000000`: set ⇒
-/// `Name[locale]`, clear ⇒ the GlobalStrings value of `CHANNELING`. Nine of the 323 channeled rows
-/// in the shipped file set it — the four Fishing ranks (7620/7731/7732/18248), 20578 Cannibalize,
-/// 11403 Dream Vision, 24937 Using Control Console and the two Blood Siphons (which the suppressor
-/// above hides anyway). Every other channel — Blizzard, Arcane Missiles, Mind Flay, Drain Life,
-/// Rain of Fire, Hurricane, Tranquility, Evocation, First Aid — reads "Channeling".
+/// `AttributesEx` bit 29: the channel bar names the spell, not "Channeling" (`0x6e759a`).
 const ATTR_EX_CHANNEL_BAR_OWN_NAME: u32 = 0x2000_0000;
-/// `Attributes` bit `0x2` — the "uses the ranged slot" attribute (mangos `SPELL_ATTR_RANGED`).
-/// One half of the client's ranged-stance gate (module docs).
+/// `SPELL_ATTR_RANGED`: the spell uses the ranged slot.
 const ATTR_RANGED: u32 = 0x2;
-/// `Attributes` bit 9 (`0x200`) — **this cast targets the equipped main hand, without asking**
-/// (`SPELL_ATTR0_TARGET_MAINHAND_ITEM`). vmangos leaves the bit unnamed (`SPELL_ATTR_UNK9`)
-/// because it is a purely *client-side* targeting instruction: the server only ever sees the
-/// resolved item guid. The law is `ArmCast 0x6e5250`'s candidate leg (`6e536e`–`6e5391`), read by
-/// [`SpellDisplay::targets_main_hand_item`]; decision 1552.
+/// `Attributes` bit 9: target the equipped main hand. vmangos leaves it unnamed
+/// (`SPELL_ATTR_UNK9`): the server only sees the resolved item guid.
 const ATTR_TARGET_MAIN_HAND_ITEM: u32 = 0x200;
-/// `AttributesEx2` bit `0x20` — the auto-repeat attribute (mangos `SPELL_ATTR_EX2_AUTO_REPEAT`);
-/// the other half of the gate. Auto Shot and wand Shoot carry it.
+/// `SPELL_ATTR_EX2_AUTO_REPEAT`: Auto Shot and wand Shoot.
 const ATTR_EX2_AUTO_REPEAT: u32 = 0x20;
-/// `AttributesEx2` bit `0x20000` — `SPELL_ATTR_EX2_DO_NOT_RESET_COMBAT_TIMERS` (vmangos
-/// `SpellDefines.h`). Its absence on a ranged spell opts the cast into the ranged-speed cooldown
-/// pad ([`SpellDisplay::ranged_speed_cooldown`]).
 const ATTR_EX2_DO_NOT_RESET_COMBAT_TIMERS: u32 = 0x20000;
-/// `Attributes` bit `0x40` — `SPELL_ATTR_PASSIVE` (vmangos `SpellDefines.h`'s `SpellAttributes`
-/// enum, `0x00000040 // 6`): the spellbook's own passive gate ([`SpellDisplay::passive`]). The
-/// ref's `SpellButton_UpdateButton` reads `IsSpellPassive` to gray the name/highlight art
-/// (`SpellBookFrame.lua:379-390`) — a passive is real player state (a permanent weapon-skill/
-/// stance-derived buff), never something the player casts, so the engine's `CastSpell` binding
-/// (decision 0216 §8, `benilla-ui/src/script/spellbook.rs`) refuses it outright rather than
-/// sending a doomed cast the server would just reject.
+/// `SPELL_ATTR_PASSIVE`: the spellbook grays the spell (`SpellBookFrame.lua:379-390`).
 const ATTR_PASSIVE: u32 = 0x40;
-/// `Attributes` bit `0x10` — `SPELL_ATTR_ABILITY` (cmangos `SpellDefines.h`). The **only** thing
-/// the 1.12 client reads it for is the learn announcement's wording: `0x4b29a9 setne al` /
-/// `0x4b29b3 add eax,0x37` picks message id `0x37` `ERR_LEARN_SPELL_S` when the bit is clear and
-/// `0x38` `ERR_LEARN_ABILITY_S` when it is set. See [`SpellDisplay::learn_announcement`].
+/// `SPELL_ATTR_ABILITY`, read by the 1.12 client only to word the learn line (`0x4b29a9`).
 const ATTR_ABILITY: u32 = 0x10;
-/// `Attributes` bit `0x80` — `SPELL_ATTR_DO_NOT_DISPLAY` (cmangos `SpellDefines.h`: "Hidden in
-/// Spellbook, Aura Icon, Combat Log"): THE spellbook add-gate (decision 0227) AND the `Attributes`
-/// half of the aura-bar display filter ([`SpellDisplay::hidden_from_aura_bar`] — the cache
-/// builder's byte-width read at `0x4e42b6` tests exactly this bit). Every language, armor/weapon
-/// proficiency, hidden racial passive, and internal proc aura (Defensive State 5302) carries it.
+/// `SPELL_ATTR_DO_NOT_DISPLAY`: languages, proficiencies, hidden racials, internal proc auras.
 const ATTR_DO_NOT_DISPLAY: u32 = 0x80;
-/// `Attributes` bit `0x20` — `SPELL_ATTR_IS_TRADESKILL` (cmangos `SpellDefines.h`): profession /
-/// recipe spells the client diverts to a name-only path, never a book slot (decision 0227). See
-/// [`SpellDisplay::in_spellbook`].
-///
-/// Public because four separate surfaces test this one bit and each had grown its own copy of the
-/// literal: the spellbook's add-gate here, the TradeSkill and Craft admission filters, and — since
-/// the trainer TOOLTIP law landed — the gate that decides whether a trainer service renders an ITEM
-/// tooltip instead of a spell one (`SetTrainerService 0x5338b0` at `0x533a1b`, and again inside the
-/// spell builder's own redirect at `0x52e6d2`).
+/// `SPELL_ATTR_IS_TRADESKILL`: a profession or recipe spell, kept out of the book; a trainer
+/// service with it shows an item tooltip (`SetTrainerService` `0x5338b0` at `0x533a1b`).
 pub const SPELL_ATTR_IS_TRADESKILL: u32 = 0x20;
-/// `AttributesEx` bit `0x10000000` — vmangos `SPELL_ATTR_EX_NO_AURA_ICON` ("Client doesn't display
-/// these spells in aura bar"): the other display-filter bit. All three warrior stances carry it
-/// (extracted 5875 `Spell.dbc`: 2457 `AttributesEx 0x90000000`, 71/2458 `0x10000000`).
+/// `SPELL_ATTR_EX_NO_AURA_ICON`: hidden from the aura bar, as all three warrior stances are.
 const ATTR_EX_NO_AURA_ICON: u32 = 0x1000_0000;
 
-/// `SpellEffects` value `78` — `SPELL_EFFECT_ATTACK` (cmangos `SpellEffectDefines.h`): the melee
-/// auto-attack effect. The only spell carrying it in 1.12 is 6603 "Attack", so the client's
-/// effect-type trigger and a hardcoded-6603 trigger are behaviourally identical — but the client
-/// checks the effect (decision 0231), so [`SpellDisplay::is_melee_auto_attack`] does too.
+/// `SPELL_EFFECT_ATTACK`: only 6603 "Attack" has it, but the client tests the effect, not the id.
 const SPELL_EFFECT_ATTACK: u32 = 78;
 
-/// The three **tracking** aura types (`EffectApplyAuraName` values, vmangos `SpellAuraDefines.h`):
-/// `SPELL_AURA_TRACK_CREATURES` 44, `SPELL_AURA_TRACK_RESOURCES` 45, `SPELL_AURA_TRACK_STEALTHED`
-/// 151 — byte-verified as the client's own set `{0x2c,0x2d,0x97}`, tested against the three
-/// `EffectApplyAuraName` dwords at `SpellRec+0x16c..+0x174` in BOTH aura display filters: the
-/// player-cache rebuild's Pass 2 (`0x4e42xx`, which also records the matching spell for
-/// `GetTrackingTexture`) and the shared `IsAuraDisplayable 0x519860` (`0x5198c2`–`0x5198d3`)
-/// the `UnitBuff`/`UnitDebuff` walks call (wow-re `ui/scratch/aura-display-pipeline.md` §3/§9a).
-/// See [`SpellDisplay::tracking_aura`].
+/// The tracking aura types, which no aura display shows (`IsAuraDisplayable` `0x519860`).
 const TRACKING_AURA_TYPES: [u32; 3] = [44, 45, 151];
 
-/// `Attributes` bits `0x4` + `0x400` — the two ON_NEXT_SWING attributes (vmangos
-/// `SPELL_ATTR_ON_NEXT_SWING_NO_DAMAGE` / `SPELL_ATTR_ON_NEXT_SWING`). The client always tests
-/// them as ONE mask (`SpellRec+0x18 & 0x404` — the already-casting exemption `6e4d97`, the
-/// self-cast range short-circuit `0x6e34fb`, the attribute predicate `0x6e5200`; wow-re
-/// `wave-cast.md`): a spell of this class doesn't cast — it queues on the server's melee slot
-/// and fires on the caster's next swing (Heroic Strike 78 carries `0x4`, Raptor Strike 2973
-/// `0x404`, Cleave 845 `0x4`). See [`SpellDisplay::on_next_swing`].
+/// The on-next-swing pair `0x4` and `0x400`, always tested as one mask (`0x6e34fb`, `0x6e5200`).
 const ATTR_ON_NEXT_SWING: u32 = 0x404;
-/// `AttributesEx` bit `0x200` — vmangos `SPELL_ATTR_EX_INITIATES_COMBAT` ("Enables Auto-Attack").
-/// The server only reads it for pet AI (vmangos `Spell.cpp:4377`); the player-facing "casting
-/// this starts my auto-attack" is client-side (one leg of predicate `0x6e5200`, read by
-/// `TryCast`'s post-send tail `6e51b5` → the attack entry `0x6131a0`; byte-verified §5, wow-re
-/// `combat-feel-law.md` @ c445713b). Rend/Sunder Armor/Slam/Sinister Strike carry it; Heroic
-/// Strike and Charge do not.
+/// `SPELL_ATTR_EX_INITIATES_COMBAT`: casting starts auto-attack, on the client (`0x6e5200`); the
+/// server reads it only for pet AI (vmangos `Spell.cpp:4377`).
 const ATTR_EX_INITIATES_COMBAT: u32 = 0x200;
-/// `AttributesEx` bits 0x4|0x40 — the two CHANNELED variants, tested as one mask by the tooltip's
-/// cast cell (`0x52ec27`: `test [rec+0x1c],0x44` → "Channeled"; 1074).
+/// `AttributesEx` `0x4` or `0x40`: the two channeled variants, tested as one mask (`0x52ec27`).
 const ATTR_EX_CHANNELED: u32 = 0x44;
-/// `AttributesEx2` bit `0x100000` — vmangos `SPELL_ATTR_EX2_INITIATE_COMBAT_POST_CAST` ("Client
-/// will send CMSG_ATTACK_SWING after SMSG_SPELL_GO"). The §5-verified send-tail predicate
-/// EXCLUDES it (`[ebp-2] = 0x6e5200 && Ex2-bit20 CLEAR`): a bit20 spell defers its attack-start
-/// to the `SMSG_SPELL_GO` handler (`0x6e83c0`) instead of starting at send. Both halves are
-/// built — [`SpellDisplay::initiates_auto_attack`] is the send-time one, and
-/// [`SpellDisplay::initiates_auto_attack_at_go`] the deferred one.
-///
-/// This doc used to say "no spell benilla meets carries it, so the deferred path stays unbuilt".
-/// That was a proof by absence over the ten warrior/rogue spells `catalog_tests.rs` happened to
-/// list. The real 5875 `Spell.dbc` carries the bit on **36 rows** — every rank of Backstab,
-/// Garrote, Ambush, Cheap Shot, Shred, Ravage and Pounce, plus Judgement 20271 — i.e. every
-/// stealth opener and positional strike in the game, whose attack must wait for the server to
-/// resolve it. The census is the test beside this now (decision 1593, bug B280's sweep).
+/// `SPELL_ATTR_EX2_INITIATE_COMBAT_POST_CAST`: auto-attack starts at the spell's `SMSG_SPELL_GO`
+/// (`0x6e83c0`), not at the send: the stealth openers, positional strikes and Judgement.
 const ATTR_EX2_INITIATE_COMBAT_POST_CAST: u32 = 0x0010_0000;
 
-/// `Attributes` bit 25 (`0x0200_0000`) — `SPELL_ATTR_COOLDOWN_ON_EVENT` (vmangos; "disabled while
-/// active"). The client's cooldown machinery stores such a spell's record **on hold** — timers
-/// parked until `SMSG_COOLDOWN_EVENT` starts them (the `bl = (SpellRec+0x18 >> 0x19) & 1` read in
-/// the `SMSG_SPELL_COOLDOWN` handler `0x6e9460`, wow-re `wave-handlers.md`, VERIFIED). Stealth,
-/// Shield Wall — the "cooldown begins when the effect ends" family.
+/// `SPELL_ATTR_COOLDOWN_ON_EVENT`: held by the `SMSG_SPELL_COOLDOWN` handler (`0x6e9460`).
 const ATTR_COOLDOWN_ON_EVENT: u32 = 0x0200_0000;
 
-/// The usable-walk attribute gates (§2a legs 1/6/7/8; names = vmangos `SpellDefines.h`,
-/// bit positions = the byte-verified reads in `IsSpellUsableNow 0x6e3d60`):
-/// bit 23 — castable while dead (leg 1's waiver);
-/// bit 17 — only while stealthed, tested against `UNIT_FIELD_BYTES_1` byte 3's CREEP flag
-/// (leg 7's `[+0x110]+0x213 & 2`; vmangos `UNIT_VIS_FLAGS_CREEP`, set by the stealth aura);
-/// bit 16 — not while shapeshifted (a form-gate input, [`SpellDisplay::usable_in_form`]);
-/// bit 28 — only out of combat, tested against `UNIT_FLAG_IN_COMBAT` (leg 8's unit-flag b19).
+/// The usable walk's attribute gates (`0x6e3d60`): bit 23 castable while dead (`0x6e3dbd`), bit
+/// 17 only while stealthed (`0x6e3ee3`, the creep flag), bit 16 not while shapeshifted, bit 28
+/// only out of combat (`0x6e3f01`).
 pub const ATTR_CASTABLE_WHILE_DEAD: u32 = 0x0080_0000;
 pub const ATTR_ONLY_STEALTHED: u32 = 0x0002_0000;
 const ATTR_NOT_SHAPESHIFT: u32 = 0x0001_0000;
 pub const ATTR_NOT_IN_COMBAT: u32 = 0x1000_0000;
-/// `AttributesEx2` bit 19 — the form requirement is waived while unshifted (vmangos
-/// `SPELL_ATTR_EX2_ALLOW_WHILE_NOT_SHAPESHIFTED`; a form-gate input).
+/// `SPELL_ATTR_EX2_ALLOW_WHILE_NOT_SHAPESHIFTED`: waives the form requirement while unshifted.
 const ATTR_EX2_ALLOW_WHILE_NOT_SHAPESHIFTED: u32 = 0x0008_0000;
-/// The **combo-point consumers** — `AttributesEx` bits 20 and 22 (vmangos
-/// `SPELL_ATTR_EX_FINISHING_MOVE_DAMAGE` / `_DURATION`, both commented "Uses combo points"; the
-/// pair `SpellEntry::NeedsComboPoints` tests). The usable walk's leg 5 reads exactly this pair
-/// (wow-re §2a: "AttributesEx b20/b22") before consulting the caster's combo-point byte —
-/// [`SpellDisplay::needs_combo_points`], decision 0869. In 5875 the set is the six rogue/druid
-/// finishers (Eviscerate, Expose Armor, Ferocious Bite, Kidney Shot, Rip, Rupture, Slice and
-/// Dice) **plus Overpower**, whose own `AttributesEx` bit 30 vmangos names `COMBO_ON_BLOCK` and
-/// annotates, in one word, "Overpower".
+/// The combo-point consumers, `AttributesEx` bits 20 and 22 (vmangos `NeedsComboPoints`), read
+/// by the usable walk at `0x6e3e7a`: the rogue and druid finishers, and Overpower.
 const ATTR_EX_FINISHING_MOVE: u32 = 0x0050_0000;
-/// `SpellEffects` value `47` — `SPELL_EFFECT_TRADE_SKILL`: the usable walk's early-out
-/// (`0x6e3d99`, `Effect[0]==0x2f` ⇒ usable, skipping every gate). Also the crafting book's open
-/// key (0437): `Spell_C::TryCast 0x6e4b60` branches on `Effect[0]==0x2f` and opens the window
-/// client-side, never sending the cast (wow-re `wave-cast.md`, VERIFIED).
+/// `SPELL_EFFECT_TRADE_SKILL`: usable with no other gate (`0x6e3d99`), and `TryCast`
+/// (`0x6e4b60`) opens the crafting window itself instead of sending the cast.
 pub const SPELL_EFFECT_TRADE_SKILL: u32 = 47;
-/// `SpellEffects` value `24` — `SPELL_EFFECT_CREATE_ITEM` (vmangos `SharedDefines.h`): a recipe's
-/// product effect; its `EffectItemType` slot is the created item entry (0437).
+/// `SPELL_EFFECT_CREATE_ITEM`: a recipe's product, its `EffectItemType`.
 pub const SPELL_EFFECT_CREATE_ITEM: u32 = 24;
-/// `SpellEffects` value `95` — `SPELL_EFFECT_SKINNING` (vmangos `SharedDefines.h`,
-/// `Spell::EffectSkinning`): the corpse-gathering cast the Skin cursor's right-click resolves
-/// through (0437's gathering finish). Byte-confirmed as the client's own discriminator: the
-/// spell-learn path latches a spell with this `Effect[0]` into `[0xb700e4]`
-/// (`0x4b2623: cmp [esi+0xf4], 0x5f` — `0x5f == 95`), and the cursor's skin leg requires that latch
-/// (decision 0752).
+/// `SPELL_EFFECT_SKINNING`: learning a spell with it as `Effect[0]` latches it at `0xb700e4`
+/// (`0x4b2623`), and the Skin cursor requires that latch.
 pub const SPELL_EFFECT_SKINNING: u32 = 95;
-/// `SpellEffects` value `39` — `SPELL_EFFECT_LANGUAGE`: the effect that makes a spell *be* a
-/// language. Its `EffectMiscValue_1` is the `Languages.dbc` id, which is how a language reaches a
-/// skill line at all — see [`SpellCatalog::language_spell`].
+/// `SPELL_EFFECT_LANGUAGE`: its `EffectMiscValue` is the `Languages.dbc` id.
 pub const SPELL_EFFECT_LANGUAGE: u32 = 39;
 
-/// `SpellEffects` values `53`/`54` — `SPELL_EFFECT_ENCHANT_ITEM` (permanent) /
-/// `SPELL_EFFECT_ENCHANT_ITEM_TEMPORARY` (vmangos `SharedDefines.h`): the item-targeted craft
-/// casts the CraftFrame sends with `TARGET_FLAG_ITEM` (0437 phase 3).
+/// The permanent and temporary enchants, cast by the CraftFrame with `TARGET_FLAG_ITEM`.
 pub const SPELL_EFFECT_ENCHANT_ITEM: u32 = 53;
 pub const SPELL_EFFECT_ENCHANT_ITEM_TEMPORARY: u32 = 54;
 
-/// `SpellEffects` value `127` — `SPELL_EFFECT_PROSPECTING`, and **no 5875 spell carries it**
-/// (pinned by `real_prospecting_effect_is_absent_from_5875`). It is named here because the
-/// absence is load-bearing rather than incidental: the item-target validator `0x495d60` has a
-/// third leg past its two enchant ones, gated on exactly this value (`0x495f39: cmp [eax],0x7f`),
-/// and that leg holds the only raise sites image-wide for the cast-failure reasons `0x84`
-/// PROSPECT_NEED_MORE (`0x49614e`) and `0x90` MIN_SKILL (`0x496128`). The server sends neither
-/// reason either, so on this build both messages are unreachable — which is why
-/// `ui_action::cast_fail` models neither arm (decision 2292).
-///
-/// **The number is the binary's own, not a later build's enum ported backwards.** `TryCast
-/// 0x6e4b60` carries a matched pair of `Effect[0]` gates two instructions apart:
-/// `0x6e4ca2 cmp eax,0x63` (99) raises `SPELL_FAILED_DISENCHANT_WHILE_LOOTING` (`0x6e4cbb`), and
-/// `0x6e4cd4 cmp [edx+0xf4],0x7f` raises `SPELL_FAILED_PROSPECT_WHILE_LOOTING` (`0x6e4cee`). That
-/// pairing names 99 ↔ disenchant and 127 ↔ prospect in 5875's own hand — and makes `0x83` dead
-/// on the same grounds as `0x84`/`0x90`, while its sibling `0x82` stays live (effect 99 ships).
-///
-/// The **code** is live and only the **data** is absent: 127 is handled in three reachable places
-/// (`0x495f39`, `0x6e4cd4`, and the effect classifier `0x6e3b80`'s 128-entry case table at
-/// `0x6e3bdc`, which maps it to the default arm). Nothing here is dead-stripped — 5875 ships
-/// prospecting with no prospecting spell to reach it.
+/// `SPELL_EFFECT_PROSPECTING`: handled by the client (`0x495f39`, `0x6e4cd4`, `0x6e3bdc`) but on
+/// no 5875 spell, so the cast-fail reasons only its legs raise, `0x83`, `0x84` and `0x90`, never
+/// show. The number is this build's own: `TryCast` pairs 99 with disenchant (`0x6e4ca2`) and 127
+/// with prospect (`0x6e4cd4`).
 pub const SPELL_EFFECT_PROSPECTING: u32 = 127;
 
-/// `Spell.dbc` × `SpellIcon.dbc`, joined: spell id → name + icon path, plus the **learn-spell map**
-/// (a `SPELL_EFFECT_LEARN_SPELL` spell → the spell it teaches). Vanilla trainers offer a *learn*
-/// spell — a thin wrapper whose only effect is "teach spell X" — not the ability itself; the ability
-/// (with its skill line, its real icon) is the taught spell. [`Self::learned_spell`] follows that hop
-/// so callers can resolve the ability from the trainer's wire id (decision 0247's `taughtSpell`).
+/// `Spell.dbc` joined with `SpellIcon.dbc`, plus the learn-spell map: a trainer offers a learn
+/// wrapper, and [`Self::learned_spell`] follows it to the ability it teaches.
 pub struct SpellCatalog {
     spells: HashMap<u32, SpellDisplay>,
     learned_spell: HashMap<u32, u32>,
-    /// Spell id → the `Languages.dbc` id its `Effect_1` declares
-    /// ([`SpellCatalog::declared_language`]).
+    /// Learn effects in slot order, for spells that have any.
+    learn_effects: HashMap<u32, Vec<LearnEffect>>,
+    /// Spell id to the `Languages.dbc` id its first effect declares.
     declared_language: HashMap<u32, u32>,
     dispel_types: SpellDispelTypes,
 }
 
 impl SpellCatalog {
-    /// Build a catalog from an explicit display map — for tests and synthetic fixtures. The live
-    /// path is [`load_spell_catalog`]. Carries no learn-spell map (synthetic ids teach nothing) and
-    /// no dispel table, so [`Self::dispel_name`] answers `None` for everything.
+    /// A catalog from explicit displays, for tests: no learn-spell map and no dispel table, so
+    /// [`Self::dispel_name`] is always `None`.
     pub fn from_displays(spells: HashMap<u32, SpellDisplay>) -> Self {
+        Self::from_displays_and_effects(spells, HashMap::new())
+    }
+
+    /// [`Self::from_displays`] with a learn-effect table, for the trainer tests.
+    pub fn from_displays_and_effects(
+        spells: HashMap<u32, SpellDisplay>,
+        learn_effects: HashMap<u32, Vec<LearnEffect>>,
+    ) -> Self {
+        let learned_spell = learn_effects
+            .iter()
+            .filter_map(|(id, effects)| {
+                effects.iter().find_map(|e| match e {
+                    LearnEffect::Spell(taught) => Some((*id, *taught)),
+                    _ => None,
+                })
+            })
+            .collect();
         Self {
             spells,
-            learned_spell: HashMap::new(),
+            learned_spell,
+            learn_effects,
             declared_language: HashMap::new(),
             dispel_types: SpellDispelTypes::default(),
         }
     }
 
+    /// A spell's learn effects in slot order, empty for a plain ability.
+    pub fn learn_effects(&self, id: u32) -> &[LearnEffect] {
+        self.learn_effects.get(&id).map_or(&[], Vec::as_slice)
+    }
+
     pub fn get(&self, id: u32) -> Option<&SpellDisplay> {
         self.spells.get(&id)
     }
 
-    /// The name of a spell's dispel class — the aura tooltip's right column and the `debuffType`
-    /// the debuff border tints by. `None` when the spell has no class or the class is one
-    /// `SpellDispelType.dbc`'s `[+0x28]` gate withholds (see [`dispel_types`]).
+    /// The dispel class's name, for the aura tooltip and the debuff border's `debuffType`; `None`
+    /// when `SpellDispelType.dbc`'s `[+0x28]` gate withholds it.
     pub fn dispel_name(&self, display: &SpellDisplay) -> Option<&str> {
         self.dispel_types.name(display.dispel)
     }
 
-    /// Every loaded spell `(id, display)`, unordered — the corpus instruments' walk
-    /// (`benilla-extract partcensus` attributes effect models back to the spells that play them).
+    /// Every loaded spell, unordered.
     pub fn iter(&self) -> impl Iterator<Item = (u32, &SpellDisplay)> + '_ {
         self.spells.iter().map(|(id, s)| (*id, s))
     }
 
-    /// The spell a `SPELL_EFFECT_LEARN_SPELL` spell teaches (`None` if `id` teaches nothing — i.e. it
-    /// is a plain ability, not a learn wrapper). The trainer's wire id is a learn spell; the ability
-    /// (its skill line, its display) is what this resolves to (decision 0247's taught-spell hop).
+    /// The ability a learn wrapper teaches, which resolves a trainer's wire id.
     pub fn learned_spell(&self, id: u32) -> Option<u32> {
         self.learned_spell.get(&id).copied()
     }
 
-    /// The language a spell **declares** — its `Effect_1 == 39` (`SPELL_EFFECT_LANGUAGE`) slot's
-    /// `EffectMiscValue_1`, or `None` for a spell that is not a language.
-    ///
-    /// This is the direction the reference works in, and the direction matters. `0x4b25b0` runs on
-    /// **spell add** and stores `[0xb700ac][EffectMiscValue_1] = spellId`, so the client's
-    /// language→spell table only ever holds languages *this character has learned*, and a later
-    /// learn overwrites an earlier one on the same language id (wow-re
-    /// `system/ui/scratch/chat-language-scramble.md` §8). Exposing spell→language lets the caller
-    /// fold that table over its own known-spell set and get the reference's answer; exposing
-    /// language→spell over the whole DBC would not, and the shipped data is why:
-    ///
-    /// **Five of the fourteen language spells declare language 7 (Common), not their own.** In
-    /// 5875's `Spell.dbc`, 813 Thalassian, 814 Draconic, 815 Demon Tongue, 816 Titan and 817 Old
-    /// Tongue all carry `EffectMiscValue_1 = 7`, and four of the five are named "(NYI)". Two
-    /// consequences a re-implementation must not smooth over:
-    ///
-    /// - **Languages 8, 9, 10 and 12 are unreachable** — no shipped spell declares them, so the
-    ///   client's table never gets an entry and Demonic / Titan / Thalassian / Kalimag are *always*
-    ///   fully garbled for every character. That is correct 1.12.1 behaviour, not a gap.
-    /// - **A warlock's Demon Tongue (815) overwrites Common's entry**, so their Common is gated on
-    ///   their Demon Tongue skill. Unobservable — every language skill a character holds is 300 —
-    ///   but it is the reference's behaviour and falls out of the fold for free.
-    ///
-    /// Language 11 (Draconic) *is* reachable, via 25674 "Lesser Draconic (Language)", the one spell
-    /// that declares it correctly.
+    /// The `Languages.dbc` id a spell declares: `EffectMiscValue_1` when `Effect_1` is 39. The
+    /// client fills its language table (`0xb700ac`) on spell add (`0x4b25b0`), a later learn
+    /// overwriting, so fold this over the known spells. Five language spells (813-817) declare
+    /// Common (7): languages 8, 9, 10 and 12 are always garbled, and a warlock's Demon Tongue
+    /// takes Common's entry. Both are 1.12.1 behaviour.
     pub fn declared_language(&self, spell: u32) -> Option<u32> {
         self.declared_language.get(&spell).copied()
     }
 
-    /// Every `(spell id, language id)` pair a shipped spell declares — for the fold above, and for
-    /// the tests that pin the shipped anomaly.
+    /// Every `(spell, language)` pair a shipped spell declares.
     pub fn declared_languages(&self) -> impl Iterator<Item = (u32, u32)> + '_ {
         self.declared_language.iter().map(|(s, l)| (*s, *l))
     }
@@ -696,12 +341,8 @@ impl SpellCatalog {
     }
 }
 
-/// Schema: 173 fields, all u32 except the ones we read as what they are (Speed/EffectMultipleValue
-/// as f32; the name/name-subtext/description/aura-description block heads as strings; the rest of
-/// each loc block stays u32 — unread). `EffectBasePoints`/`EffectDieSides` are genuinely signed but
-/// read through [`i32_at`] regardless of the schema tag (a raw dword's bits don't change between
-/// the `UInt32`/`Int32` variants — only which `_at` helper a caller reaches for), so they stay
-/// untagged here like every other unread-as-a-type integer column.
+/// 173 fields, `u32` but for the floats (`Speed`, the two float effect arrays) and the four enUS
+/// string heads; the signed columns stay `u32`, as [`i32_at`] reads the same bits.
 fn spell_schema() -> Schema {
     let mut s = Schema::new("Spell");
     for i in 0..SPELL_FIELDS {
@@ -741,10 +382,8 @@ fn spell_schema() -> Schema {
 pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
     let icons = crate::dbc::load_spell_icon_map(chain)?;
     let dispel_types = load_spell_dispel_types(chain)?;
-    // The SpellCategory "matches every query" wildcard set (`GetCooldownInfo 0x6e13e0`'s category
-    // leg, `6e1563`/`6e1567`: a category row whose Flags carry bit `0x2` contributes to ANY
-    // queried spell — wow-re `gcd-power-gate.md` §2). In the 5875 data exactly one row carries
-    // it: category 351, wand Shoot's — the whole-bar wand-swing sweep (pinned in catalog_tests).
+    // Categories whose `SpellCategory.dbc` flags carry `0x2` match every cooldown query
+    // (`GetCooldownInfo` `0x6e13e0`); only wand Shoot's 351 does.
     let wildcard_categories: std::collections::HashSet<u32> = {
         let bytes = chain
             .read_file("DBFilesClient\\SpellCategory.dbc")
@@ -770,12 +409,11 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
     let spells_set = parse(&spell_bytes, spell_schema(), "Spell.dbc")?;
     let mut spells: HashMap<u32, SpellDisplay> = HashMap::new();
     let mut learned_spell: HashMap<u32, u32> = HashMap::new();
+    let mut learn_effects: HashMap<u32, Vec<LearnEffect>> = HashMap::new();
     let mut declared_language: HashMap<u32, u32> = HashMap::new();
     for r in spells_set.records() {
         let Some(id) = u32_at(r, 0) else { continue };
-        // The learn-spell hop (decision 0247): a SPELL_EFFECT_LEARN_SPELL effect's EffectTriggerSpell
-        // is the ability this spell teaches — the trainer offers the learn wrapper, the taught spell
-        // carries the skill line + the real display. First LEARN effect wins.
+        // The learn-spell hop: the first LEARN_SPELL effect's trigger is the taught ability.
         for i in 0..3 {
             if u32_at(r, COL_EFFECT_1 + i) == Some(SPELL_EFFECT_LEARN_SPELL) {
                 if let Some(taught) = u32_at(r, COL_EFFECT_TRIGGER_1 + i).filter(|&t| t != 0) {
@@ -784,10 +422,31 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
                 }
             }
         }
-        // The language declaration (wow-re `chat-language-scramble.md` §8). **Effect slot 0 only**
-        // — the reference dispatches on `Effect_1` alone (`[SpellRec+0xf4]`) and reads
-        // `EffectMiscValue_1` (`+0x1a8`); it does not scan the other two slots the way the learn
-        // hop above does.
+        // Learn effects in slot order; a SKILL_STEP's step is base points plus die sides.
+        let effects: Vec<LearnEffect> = (0..3)
+            .filter_map(|i| {
+                let trigger = || u32_at(r, COL_EFFECT_TRIGGER_1 + i).filter(|&t| t != 0);
+                match u32_at(r, COL_EFFECT_1 + i)? {
+                    SPELL_EFFECT_LEARN_SPELL => trigger().map(LearnEffect::Spell),
+                    SPELL_EFFECT_LEARN_PET_SPELL => trigger().map(LearnEffect::PetSpell),
+                    SPELL_EFFECT_SKILL_STEP => {
+                        let skill = i32_at(r, COL_EFFECT_MISC_1 + i).filter(|&m| m > 0)? as u32;
+                        let value = i32_at(r, COL_EFFECT_BASE_POINTS_1 + i).unwrap_or(0)
+                            + i32_at(r, COL_EFFECT_DIE_SIDES_1 + i).unwrap_or(0);
+                        Some(LearnEffect::SkillStep {
+                            skill,
+                            step: value.max(0) as u32,
+                        })
+                    }
+                    _ => None,
+                }
+            })
+            .collect();
+        if !effects.is_empty() {
+            learn_effects.insert(id, effects);
+        }
+        // The language declaration (`0x4b2656`) reads slot 0 only, `+0xf4` and `+0x1a8`, unlike
+        // the learn hop's scan of all three.
         if u32_at(r, COL_EFFECT_1) == Some(SPELL_EFFECT_LANGUAGE) {
             if let Some(lang) = i32_at(r, COL_EFFECT_MISC_1).filter(|&l| l > 0) {
                 declared_language.insert(id, lang as u32);
@@ -801,8 +460,7 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
         let visual = u32_at(r, COL_VISUAL_ID).unwrap_or(0);
         let speed = f32_at(r, COL_SPEED).unwrap_or(0.0);
         let attributes = u32_at(r, COL_ATTRIBUTES).unwrap_or(0);
-        // The per-effect `[3]` arrays (module docs) — computed once so the shapeshift-form
-        // derivation below can reuse `effect_apply_aura` instead of re-reading the columns.
+        // Read once; the shapeshift-form derivation below reuses `effect_apply_aura`.
         let effect_apply_aura: [u32; 3] =
             std::array::from_fn(|i| u32_at(r, COL_EFFECT_APPLY_AURA_1 + i).unwrap_or(0));
         let effect_trigger_spell: [u32; 3] =
@@ -826,8 +484,7 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
                 }),
                 prevention_type: u32_at(r, COL_PREVENTION_TYPE).unwrap_or(0),
                 spell_family: u32_at(r, COL_SPELL_FAMILY_NAME).unwrap_or(0),
-                // Low dword first: bit `i >= 32` lives in column 162, which the reference reads as
-                // `[edi + 4*(i>>5) + 0x284]` — the same little-endian pair this join makes.
+                // Low dword first: the reference reads bit i at `[rec + 4 * (i >> 5) + 0x284]`.
                 spell_family_flags: u64::from(u32_at(r, COL_SPELL_FAMILY_FLAGS_LOW).unwrap_or(0))
                     | u64::from(u32_at(r, COL_SPELL_FAMILY_FLAGS_LOW + 1).unwrap_or(0)) << 32,
                 passive: attributes & ATTR_PASSIVE != 0,
@@ -836,10 +493,7 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
                 base_level: u32_at(r, COL_BASE_LEVEL).unwrap_or(0),
                 max_level: u32_at(r, COL_MAX_LEVEL).unwrap_or(0),
                 spell_level: u32_at(r, COL_SPELL_LEVEL).unwrap_or(0),
-                // Scan the three effects for OPEN_LOCK and take that effect's LockType (its
-                // EffectMiscValue) together with the value inputs the lock resolver compares
-                // against the slot's requirement (decision 0752). Most openers carry it on
-                // Effect[0], but the scan is cheap.
+                // The first OPEN_LOCK effect, in any slot, and its `EffectMiscValue` LockType.
                 open_lock: (0..3).find_map(|i| {
                     (u32_at(r, COL_EFFECT_1 + i)? == SPELL_EFFECT_OPEN_LOCK).then(|| OpenLock {
                         lock_type: u32_at(r, COL_EFFECT_MISC_1 + i).unwrap_or(0),
@@ -848,9 +502,7 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
                 }),
                 dispel: u32_at(r, COL_DISPEL).unwrap_or(0),
                 category: u32_at(r, COL_CATEGORY).unwrap_or(0),
-                // The category row's flags-bit-0x2 "matches every query" mark (only wand Shoot's
-                // 351 in the 5875 data) — resolved at load so the cooldown store's category leg
-                // reads it off the record it armed (`gcd-power-gate.md` §2).
+                // Resolved at load, read off the armed record (`0x6e1563`).
                 category_wildcard: u32_at(r, COL_CATEGORY)
                     .is_some_and(|c| wildcard_categories.contains(&c)),
                 recovery_ms: u32_at(r, COL_RECOVERY_TIME).unwrap_or(0),
@@ -892,8 +544,7 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
                 equipped_item_inventory_type_mask: u32_at(r, COL_EQUIPPED_ITEM_INVENTORY_TYPE_MASK)
                     .unwrap_or(0),
                 requires_spell_focus: u32_at(r, COL_REQUIRES_SPELL_FOCUS).unwrap_or(0),
-                // The stance-bar keys (wow-re shapeshift-bar-api.md): the first MOD_SHAPESHIFT
-                // effect's MiscValue is the form id; order/active-icon read raw.
+                // The first MOD_SHAPESHIFT effect's `EffectMiscValue` is the form (`0x4b4690`).
                 shapeshift_form: (0..3).find_map(|i| {
                     (effect_apply_aura[i] == SPELL_AURA_MOD_SHAPESHIFT)
                         .then(|| u32_at(r, COL_EFFECT_MISC_1 + i).unwrap_or(0))
@@ -949,6 +600,7 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
     Ok(SpellCatalog {
         spells,
         learned_spell,
+        learn_effects,
         declared_language,
         dispel_types,
     })
@@ -957,3 +609,48 @@ pub fn load_spell_catalog(chain: &mut Chain) -> Result<SpellCatalog> {
 #[cfg(test)]
 #[path = "catalog_tests.rs"]
 mod tests;
+
+#[cfg(test)]
+mod learn_effect_tests {
+    use super::*;
+
+    /// A trainer's wrapper carries the learn effect and the step `0x4d7d40` compares.
+    #[test]
+    fn the_openers_skill_steps_read_off_the_real_file() {
+        let data = crate::wow_data_or_skip!();
+        let mut chain = crate::open_chain(&data).expect("open chain");
+        let cat = load_spell_catalog(&mut chain).expect("Spell.dbc");
+        let blacksmithing = 164;
+        for (wrapper, taught, step) in [
+            (2020, 2018, 1),
+            (2021, 3100, 2),
+            (3539, 3538, 3),
+            (9786, 9785, 4),
+        ] {
+            assert_eq!(
+                cat.learn_effects(wrapper),
+                &[
+                    LearnEffect::Spell(taught),
+                    LearnEffect::SkillStep {
+                        skill: blacksmithing,
+                        step
+                    }
+                ],
+                "wrapper {wrapper}"
+            );
+        }
+        // Mining's opener: base −1 + die 1 on the LEARN slot is not a step; the SKILL_STEP slot is.
+        assert_eq!(
+            cat.learn_effects(2581),
+            &[
+                LearnEffect::Spell(2575),
+                LearnEffect::SkillStep {
+                    skill: 186,
+                    step: 1
+                }
+            ]
+        );
+        // A plain ability teaches nothing.
+        assert!(cat.learn_effects(2383).is_empty(), "Find Herbs");
+    }
+}
diff --git a/crates/benilla-formats/src/spells/radius.rs b/crates/benilla-formats/src/spells/radius.rs
index 5dd5b2bf..edf9b150 100644
--- a/crates/benilla-formats/src/spells/radius.rs
+++ b/crates/benilla-formats/src/spells/radius.rs
@@ -1,8 +1,5 @@
-//! `SpellRadius.dbc` — the `$a` token's yard source (`EffectRadiusIndex` →
-//! [`crate::spells::SpellDisplay::effect_radius_index`]; the 0276 verdict pins the token's read
-//! as `[+0x160]` → SpellRadius.dbc). Pinned on the extracted 5875 file: 24 records × 4 fields
-//! `{id, radius f32, radiusPerLevel f32, radiusMax f32}` — row 13 = 10.0 yd (the classic
-//! Arcane Explosion radius), row 8 = 5.0, row 10 = 30.0.
+//! `SpellRadius.dbc`: the yards behind the `$a` token, by `EffectRadiusIndex`
+//! ([`crate::spells::SpellDisplay::effect_radius_index`]).
 
 use std::collections::HashMap;
 
@@ -31,8 +28,7 @@ impl SpellRadiusCatalog {
         self.rows.get(&index)
     }
 
-    /// Fixture constructor — tests (the [`crate::SpellCatalog::from_displays`] convention).
-    /// The live path is [`load_spell_radii`].
+    /// Fixture constructor for tests; the live path is [`load_spell_radii`].
     pub fn from_rows(rows: HashMap<u32, SpellRadius>) -> Self {
         Self { rows }
     }
@@ -76,8 +72,7 @@ pub fn load_spell_radii(chain: &mut Chain) -> Result<SpellRadiusCatalog> {
 mod tests {
     use super::*;
 
-    /// `SpellRadius.dbc` on the real data — the module doc's own probe rows. Skips without
-    /// client data.
+    /// Row 13 is Arcane Explosion's 10 yd.
     #[test]
     fn real_spell_radii_read_the_probed_rows() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/spells/ranges.rs b/crates/benilla-formats/src/spells/ranges.rs
index 910ffaf3..ed3737b5 100644
--- a/crates/benilla-formats/src/spells/ranges.rs
+++ b/crates/benilla-formats/src/spells/ranges.rs
@@ -1,6 +1,5 @@
-//! `SpellRange.dbc` — the `GetMinMaxRange 0x6e3480` inputs a spell's `rangeIndex` column
-//! ([`crate::spells::SpellDisplay::range_index`]) resolves against: a min/max yard pair per row,
-//! plus a melee-family flag whose branch substitutes the combat-reach sum for the authored pair.
+//! `SpellRange.dbc`, by `rangeIndex` ([`crate::spells::SpellDisplay::range_index`]), and
+//! `GetMinMaxRange` (`0x6e3480`): a spell's cast range in yards.
 
 use std::collections::HashMap;
 
@@ -10,11 +9,7 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 
 use crate::dbc::{f32_at, parse, u32_at};
 
-/// One `SpellRange.dbc` row — the `GetMinMaxRange 0x6e3480` inputs (wow-re `wave-cooldown.md`,
-/// VERIFIED: min f32 `+0x4`, max f32 `+0x8`, flags `+0xc` with **bit 0 = melee**, whose branch
-/// substitutes the combat-reach sum floored at 5.0 for the authored pair). Pinned on the extracted
-/// 5875 file (28 records × 22 fields): row 2 = {0, 5, flags 1} (melee), 114 = {8, 35} (Auto Shot),
-/// 95 = {8, 25} (Charge), 35 = {0, 35} (Fireball).
+/// One `SpellRange.dbc` row, in yards.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct SpellRange {
     pub min: f32,
@@ -24,70 +19,33 @@ pub struct SpellRange {
 }
 
 impl SpellRange {
-    /// The melee-range family (flags bit 0) — `GetMinMaxRange`'s reach-sum branch.
+    /// Flags bit 0: `GetMinMaxRange` takes the reach sum instead of the row's pair.
     pub fn is_melee(&self) -> bool {
         self.flags & 1 != 0
     }
 }
 
-/// The pad the melee arm adds to the two reaches — `[0x80b058]`, byte-exact `1.3333334`
-/// (`0x3faa_aaab`). The same constant `CanLootNow 0x5ec110` uses inline for the loot/skin reach.
+/// The pad the melee arm adds to the two reaches, `[0x80b058]`; `CanLootNow` (`0x5ec110`) pads the
+/// loot reach by the same value.
 pub const COMBAT_REACH_ADD: f32 = f32::from_bits(0x3faa_aaab);
-/// The melee arm's FLOOR — `[0x80a1e8]`. A reach sum *below* it is replaced by it (the "cap 5.0"
-/// gloss is inverted; byte-checked at `0x6e35bf`).
+/// The melee arm's floor, not a cap, `[0x80a1e8]`: a lower reach sum is raised to it (`0x6e35bf`).
 pub const MELEE_RANGE_FLOOR: f32 = 5.0;
-/// The on-next-swing short-circuit's max — `[0x8118d4]`, `0x6e3504`.
+/// The on-next-swing short-circuit's max, `[0x8118d4]` (`0x6e3504`).
 pub const ON_NEXT_SWING_RANGE: f32 = 100.0;
 
-/// `GetMinMaxRange 0x6e3480` — a spell's `{min, max}` cast range, the ONE home for the reach
-/// arithmetic every consumer shares (the action bar's out-of-range red, the spell tooltip's range
-/// cell). Transcribed from wow-re's diff-gated `crates/spell/src/cooldown.rs::spell_minmax_range`
-/// (`PRIMITIVE:spell_minmax_range`), including its 53-bit intermediates: the binary keeps the reach
-/// sums on the x87 stack and stores `f32` only at the end, so the additions are `f64` here.
+/// `GetMinMaxRange` (`0x6e3480`): a spell's `{min, max}` cast range, summed in `f64` because the
+/// client keeps the reach sums on the x87 stack and stores `f32` only at the end. On-next-swing
+/// spells (`Attributes & 0x404`, `0x6e34fb`) short-circuit to `(0, 100)`. The melee arm sums the
+/// target's reach, else the caster's own a second time, and reads the auto-attack target itself
+/// (`attack_target_guid`, `0x6e356a`), so a caller with no explicit target passes that unit's
+/// reach. Given a target, the ranged arm pads the max, and the min only when nonzero (the
+/// `fcomp`-vs-0.0 guard), so a min-0 spell never refuses `TOO_CLOSE`. `None`: no row, or the self
+/// row (id 1, `{0, 0}`).
 ///
-/// - **on-next-swing** (`Attributes & 0x404`, `0x6e34fb`): `(0, 100)` — the self-cast
-///   short-circuit, before the row is even read.
-/// - **melee** (`SpellRange` flags bit 0): `min = 0`; `max = reach + caster_reach + 1.3333334`,
-///   replaced by `5.0` when it does not exceed it.
-/// - **ranged**: the authored row pair, padded by `caster_reach + reach` when a target resolves —
-///   the max unconditionally, the min ONLY when the row's min is already nonzero (the
-///   `fcomp`-vs-0.0 guard: a min-0 spell must never grow a min range, or point-blank casts refuse
-///   TOO_CLOSE — decision 0426).
-///
-/// `reach` is the TARGET's when one resolves and the **caster's own** otherwise — the binary
-/// doubles the caster's reach rather than assuming a default body (`target_reach.unwrap_or(
-/// caster_reach)` in the transcription; benilla defaulted the missing side to a flat `1.5` until
-/// this moved here, which diverged for every non-default reach). **A caller with no explicit
-/// target still owes the auto-attack one**: the melee arm resolves `[caster+0xc48]`
-/// (`attack_target_guid`) itself at `0x6e356a` and uses that unit's reach, which is why the spell
-/// tooltip's melee cell moves while you are swinging at something big (wow-re
-/// `tooltip-damage-matrix-and-container-slots.md` §D4.2b). Passing it as `target_reach` is how a
-/// caller models that; only with neither does the caster's own reach stand in twice.
-///
-/// Two decomp legs are deliberately UNMODELED (0426), and **neither is target-gated the way an
-/// earlier reading here claimed**: the PvP `max += 2.6667` bonus (`0x6e3648`, gated on both
-/// units' `[unit+0x118]+0x40 & 0x200d` through the un-RE'd `0x5fc350`) is reachable from the
-/// melee arm even with no target argument, because that arm sets the target register itself; and
-/// the `Attributes & 2` leg (`0x6e36aa`) is not an "inspect" arm and touches the target nowhere —
-/// it is `max *= RangedModRange(item template +0x118) · 0.01` for whatever sits in
-/// EQUIPMENT_SLOT_RANGED, for a player caster.
-///
-/// **That second one is NOT the data no-op it was twice recorded as** (decision 2161). Scoped by
-/// the client's own slot-17 mask (`0x809200` gives bit 17 to InventoryTypes 15/25/26/28 and no
-/// others), `item_template.range_mod` is 100 on all 515 bows/guns/crossbows/wands/thrown — but
-/// **0 on all 19 shipped RELICS**: every Druid idol, Paladin libram and Shaman totem
-/// (InventoryType 28, ordinary player gear) carries a zero there, alongside nine NPC "Monster -"
-/// wands and three oddments. The gate never tests the item's class, so a relic in the ranged slot
-/// would collapse `max` to 0 and make the caller suppress the **whole** `SPELL_RANGE` cell.
-///
-/// It stays unmodelled anyway, and for the honest reason rather than the false one: whether a
-/// stock client ever *builds* a bit-1 spell's range cell for a relic-wearing player is a question
-/// about the builder's callers, not about this function — none of the 192 `Attributes & 2` rows
-/// is a spell a relic class learns, so the only route is an addon's `SetHyperlink`. wow-re has
-/// that scoped as a caller census; `ItemInfo::ranged_mod_range` is already on the wire here, so
-/// modelling it is a small change the moment the census says it is reachable.
-///
-/// `None` = no range to test: no row, or the self row (id 1, `{0, 0}`).
+/// Not applied: the PvP `max += 2.6667` (`0x6e3648`, gated by `0x5fc350`), and for a player the
+/// `Attributes & 2` scale (`0x6e36aa`), `max *= RangedModRange · 0.01` of the ranged-slot item,
+/// which a relic (range mod 0, InventoryType 28, admitted by `0x809200`) would zero, though no
+/// spell a relic class learns carries the bit.
 pub fn min_max_range(
     spell: &crate::spells::SpellDisplay,
     row: Option<&SpellRange>,
@@ -123,7 +81,7 @@ pub fn min_max_range(
     Some((min, (f64::from(row.max) + pad) as f32))
 }
 
-/// `SpellRange.dbc`, by row id ([`SpellDisplay::range_index`]).
+/// `SpellRange.dbc`, by row id ([`crate::spells::SpellDisplay::range_index`]).
 #[derive(Default)]
 pub struct SpellRangeCatalog {
     ranges: HashMap<u32, SpellRange>,
@@ -146,7 +104,7 @@ impl SpellRangeCatalog {
 const SPELL_RANGE: &str = "DBFilesClient\\SpellRange.dbc";
 const SPELL_RANGE_FIELDS: usize = 22;
 
-/// Load `SpellRange.dbc` off the patch chain ([`SpellRange`]'s row law).
+/// Load `SpellRange.dbc` off the patch chain.
 pub fn load_spell_ranges(chain: &mut Chain) -> Result<SpellRangeCatalog> {
     let bytes = chain
         .read_file(SPELL_RANGE)
@@ -179,9 +137,6 @@ pub fn load_spell_ranges(chain: &mut Chain) -> Result<SpellRangeCatalog> {
 mod tests {
     use super::*;
 
-    /// The `GetMinMaxRange 0x6e3480` transcription: melee reach floor, the no-target reach
-    /// DOUBLING, the ranged reach pad on both bounds, the self-cast short-circuit, and the
-    /// rangeless self row.
     #[test]
     fn min_max_range_follows_the_byte_law() {
         let spell = |range_index: u32, attributes: u32| crate::spells::SpellDisplay {
@@ -194,23 +149,20 @@ mod tests {
             max: 5.0,
             flags: 1,
         };
-        // Two naked-reach units (1.5 + 1.5 + 1.3333334 = 4.333) floor at 5.0…
+        // Two 1.5-reach units (4.333) floor at 5.0,
         let d = spell(2, 0);
         assert_eq!(
             min_max_range(&d, Some(&melee), 1.5, Some(1.5)),
             Some((0.0, MELEE_RANGE_FLOOR))
         );
-        // …a big pair (4 + 4 + 1.3333334) exceeds it.
+        // a 4.0 pair (9.333) clears it.
         let (_, max) = min_max_range(&d, Some(&melee), 4.0, Some(4.0)).unwrap();
         assert!((max - 9.3333).abs() < 1e-3);
-        // With NO target the caster's own reach stands in for the missing side — the binary
-        // doubles it, so a 4.0-reach caster reads the same 9.333 alone as it does against an
-        // equal-reach target. (A flat 1.5 fallback would have said 6.833.)
+        // With no target the caster's reach counts twice, as in the client: 9.333 alone too.
         let (_, max) = min_max_range(&d, Some(&melee), 4.0, None).unwrap();
         assert!((max - 9.3333).abs() < 1e-3);
 
-        // Charge's 8–25 row pads both bounds by the BARE reach sum (no 1.3333 — melee-only)
-        // against a unit target.
+        // Charge's 8-25 row pads both bounds by the bare reach sum; the 1.3333 is melee-only.
         let charge_row = SpellRange {
             min: 8.0,
             max: 25.0,
@@ -220,8 +172,7 @@ mod tests {
         assert!((min - (8.0 + 3.0)).abs() < 1e-3);
         assert!((max - (25.0 + 3.0)).abs() < 1e-3);
 
-        // A min-0 row (Fireball's 0–35) pads the max only — the fcomp-vs-0.0 guard keeps the
-        // min at zero, so a point-blank cast never reads a min range.
+        // Fireball's 0-35 row pads the max only: the fcomp-vs-0.0 guard keeps the min at zero.
         let fireball_row = SpellRange {
             min: 0.0,
             max: 35.0,
@@ -231,20 +182,18 @@ mod tests {
         assert_eq!(min, 0.0);
         assert!((max - 38.0).abs() < 1e-3);
 
-        // No unit target: the row's raw bounds, unpadded — the shape the spell tooltip's own
-        // call (`target = NULL` at `0x52e9c2`) always takes.
+        // No target, as the tooltip calls it (`target = NULL`, `0x52e9c2`): the raw bounds.
         assert_eq!(
             min_max_range(&d, Some(&charge_row), 1.5, None),
             Some((8.0, 25.0))
         );
 
-        // The self-cast attribute short-circuits to a flat 100 without touching the row.
+        // The on-next-swing attribute short-circuits to 100 without reading the row.
         assert_eq!(
             min_max_range(&spell(1, 0x400), None, 1.5, None),
             Some((0.0, ON_NEXT_SWING_RANGE))
         );
 
-        // The self row (0, 0, no melee flag) resolves to no range at all.
         let self_row = SpellRange {
             min: 0.0,
             max: 0.0,
@@ -253,9 +202,7 @@ mod tests {
         assert_eq!(min_max_range(&d, Some(&self_row), 1.5, None), None);
     }
 
-    /// `SpellRange.dbc` on the real data — the byte law's own probe rows (`GetMinMaxRange
-    /// 0x6e3480`): row 2 is the melee family (flags bit 0), 114 = Auto Shot's 8–35, 95 =
-    /// Charge's 8–25. Skips without client data.
+    /// Row 2 is the melee family, 114 Auto Shot's 8-35, 95 Charge's 8-25.
     #[test]
     fn real_spell_ranges_read_the_byte_laws_rows() {
         let data = crate::wow_data_or_skip!();
@@ -273,9 +220,7 @@ mod tests {
         let charge = ranges.get(95).expect("row 95");
         assert_eq!((charge.min, charge.max), (8.0, 25.0));
 
-        // A min-0 nuke row reads a true 0.0 min (row 4: Shadow Bolt, Frostbolt, wand Shoot) —
-        // the fcomp-vs-0.0 guard's input, so the min/max field mapping can't silently shift
-        // (0426: a manufactured min range refused point-blank casts).
+        // Row 4 (Shadow Bolt, Frostbolt, wand Shoot) reads a true 0.0 min, the guard's input.
         let nuke = ranges.get(4).expect("row 4");
         assert_eq!((nuke.min, nuke.max), (0.0, 30.0));
         assert!(!nuke.is_melee());
diff --git a/crates/benilla-formats/src/spells/tokens.rs b/crates/benilla-formats/src/spells/tokens.rs
index a3318312..86f620e8 100644
--- a/crates/benilla-formats/src/spells/tokens.rs
+++ b/crates/benilla-formats/src/spells/tokens.rs
@@ -1,28 +1,10 @@
-//! The spell-description **$-token engine** (decision 0274 P2) — the substitution the real
-//! client runs over `Spell.dbc` Description/AuraDescription text (and item trigger lines), with
-//! the value formulas byte-verified by the 0276 fold-back (wow-re `tooltip-content-law.md`,
-//! `0x5075f0 → 0x507710`, the effect-value core `0x6e3800`):
-//!
-//! - `$s` (and `$m`/`$M`): `MIN = BasePoints + BaseDice`, `MAX = BasePoints + DieSides·BaseDice`
-//!   — the general n-dice rule (the common `BaseDice = 1` case reduces to `base+1 … base+dieSides`).
-//!   `$s` prints one value when `MIN == MAX`, else `"MIN to MAX"`. The byte law also carries a
-//!   per-level term (`DicePerLevel·max(0, casterLevel − spellLevel)` inside both bounds, plus an
-//!   uncaptured `RealPointsPerLevel` float term); those columns aren't parsed yet — INTERIM the
-//!   flat value, which is exact for the overwhelming majority of 1.12 rows (per-level dice are
-//!   rare). Values print sign-absolute: the client shows "causes 12 damage", not "-12".
-//! - `$o`: the over-time total `perTick · duration / period` (period = `EffectAmplitude`,
-//!   defaulting 5000 ms when 0 — the byte default).
-//! - `$d`: the duration via `SpellDuration.dbc` — "until cancelled" when permanent; whole
-//!   seconds/minutes/hours text (INTERIM shape pending the `0x52fa50` formatter's pin).
-//! - `$t` period seconds · `$a` radius yards (`SpellRadius.dbc`) · `$h` proc chance · `$x` chain
-//!   targets · `$e` the multiple-value float · `$r` range yards · `$u` stack/charge count
-//!   (unparsed — leaves the token in place, a visible fold-back flag).
-//! - Cross-spell refs `$<id><token><idx>` (e.g. `$1234s1`) resolve through the caller's lookup.
-//! - `$/N;`/`$*N;` divide/multiply the following token's value by N.
-//! - `$l<singular>:<plural>;` picks by the last substituted numeric value; `$g<m>:<f>;` renders
-//!   the first (male) form until a caster-gender input exists.
-//!
-//! Unknown tokens pass through untouched (visible, greppable) rather than vanishing.
+//! The spell-description `$`-token engine the 1.12 client runs over `Spell.dbc` description and
+//! aura text (`0x5075f0` → `0x507710`), effect values from `0x6e3800`. Values are the flat term:
+//! the reference's per-level terms (`DicePerLevel·max(0, casterLevel − baseLevel)` on the dice,
+//! and `RealPointsPerLevel`) are not applied. Values print unsigned, as the client's do, and an
+//! `EffectAmplitude` of 0 is the reference's 5000 ms period (`$t`, `$o`). `$g` always takes the
+//! first form, as there is no gender input, and `$r`, `$u` and any unknown or unresolved token
+//! stay raw.
 
 use super::{SpellDisplay, SpellDurationCatalog, SpellRadiusCatalog};
 
@@ -31,28 +13,16 @@ pub struct TokenContext<'a> {
     pub durations: &'a SpellDurationCatalog,
     pub radii: &'a SpellRadiusCatalog,
     pub lookup: &'a dyn Fn(u32) -> Option<&'a SpellDisplay>,
-    /// The player's home-bind AREA name ("Goldshire") — the `$z` token (the hearthstone text
-    /// "Returns you to $z."). Fed from `SMSG_BINDPOINTUPDATE`'s areaId through AreaTable.dbc;
-    /// `None` (no bind seen yet) leaves the token raw, like any unresolved token.
+    /// The `$z` token: the home-bind area's name, from `SMSG_BINDPOINTUPDATE`'s area id through
+    /// `AreaTable.dbc`; `None` leaves the token raw.
     pub home_area: Option<&'a str>,
-    /// **Resolve a `GlobalStrings` key and fill its `%d` holes** — the caller's job, because both
-    /// halves of it live on the other side of this crate's boundary: the string table is the
-    /// script VM's and the one shared printf-family filler is `benilla_ui::strings::fill`
-    /// (decision 2045). This crate has no business depending on either, so the split is that the
-    /// token engine picks the KEY and the NUMBERS and the caller renders them.
-    ///
-    /// Integer holes only, and the signature says so on purpose: every key reached through here
-    /// is one of the `INT_SPELL_*` family, which exists precisely because these values are
-    /// integers. The float twins (`SPELL_DURATION_SEC = "%.2f sec"`,
-    /// `SPELL_POINTS_SPREAD_TEMPLATE = "%.1f to %.1f"`) are a *different* set of keys for a
-    /// different path, and reaching for one of those would print "14.0 to 22.0" where the client
-    /// prints "14 to 22".
-    ///
-    /// `None` (key absent, or no table at all) leaves the token raw, like any unresolved token.
+    /// Resolves a `GlobalStrings` key and fills its `%d` holes; the caller owns the string table.
+    /// Integer holes only: the keys that take numbers are `INT_SPELL_*` ones, whose float twins
+    /// would print "14.0 to 22.0" for "14 to 22". `None` leaves the token raw.
     pub text: &'a dyn Fn(&str, &[i64]) -> Option<String>,
 }
 
-/// The byte-verified effect bounds (`0x6e3800`, flat term): `(min, max)`.
+/// The effect's `(min, max)`, flat term only (`0x6e3800`).
 fn effect_bounds(d: &SpellDisplay, slot: usize) -> (i64, i64) {
     let base = i64::from(*d.effect_base_points.get(slot).unwrap_or(&0));
     let dice = i64::from(*d.effect_base_dice.get(slot).unwrap_or(&0));
@@ -60,27 +30,15 @@ fn effect_bounds(d: &SpellDisplay, slot: usize) -> (i64, i64) {
     (base + dice, base + sides * dice)
 }
 
-/// A spell's duration in ms (flat term; -1 = permanent, None = no duration row).
+/// A spell's duration in ms, flat term only; -1 is permanent.
 fn duration_ms(d: &SpellDisplay, ctx: &TokenContext) -> Option<i64> {
     let row = ctx.durations.get(d.duration_index)?;
     Some(i64::from(row.base_ms))
 }
 
-/// Whole-unit duration text — the `INT_SPELL_DURATION_*` family, largest unit that fits, with
-/// `SPELL_DURATION_UNTIL_CANCELLED` for the permanent sentinel.
-///
-/// **The words were ours and two of them were wrong.** This read "N hours"; 1.12 says
-/// `INT_SPELL_DURATION_HOURS_P1 = "%d hrs"`. The sentence "N hours" *does* exist in
-/// GlobalStrings — as `LASTONLINE_HOURS_P1`, the friends list's last-seen column — which is
-/// exactly the trap decision 2045 describes: a text search finds a key, and it is the wrong key
-/// for this call site. It also had no days arm at all, so a two-day aura read "48 hrs".
-///
-/// The ladder is the one `0x52fa50` walks (byte-pinned for the aura line as wow-re §3-BUFF, and
-/// implemented for that surface in `benilla_ui::script::tooltip::duration_text`) and the plural
-/// pick is `GetText`'s: the bare token at exactly one, the `_P1` twin otherwise. Only HOURS ships
-/// a twin in this family, so the other three fall back to the bare token — which is the same
-/// fallback `plural_template` takes, and the reason `INT_SPELL_DURATION_MIN` reads "1 min" and
-/// "9 min" alike.
+/// The duration in the largest whole `INT_SPELL_DURATION_*` unit, the ladder `0x52fa50` walks,
+/// or `SPELL_DURATION_UNTIL_CANCELLED` when permanent. The plural pick is `GetText`'s, the `_P1`
+/// twin unless exactly one; only HOURS ships one, so the others fall back to the bare key.
 fn duration_text(ms: i64, ctx: &TokenContext) -> Option<String> {
     if ms < 0 {
         return (ctx.text)("SPELL_DURATION_UNTIL_CANCELLED", &[]);
@@ -102,12 +60,8 @@ fn duration_text(ms: i64, ctx: &TokenContext) -> Option<String> {
         .or_else(|| (ctx.text)(&key, &[n]))
 }
 
-/// The min–max spread of an effect's points — `INT_SPELL_POINTS_SPREAD_TEMPLATE` ("%d to %d").
-///
-/// **The `INT_` twin, not `SPELL_POINTS_SPREAD_TEMPLATE`.** Both read the same shape in enUS and
-/// the float one is spelled `"%.1f to %.1f"`, so reaching for it would print "14.0 to 22.0" where
-/// Fireball rank 1 says "14 to 22". `effect_bounds` is integral by construction (base + dice ×
-/// sides, all `i32` columns), which is what makes the integer key the right one here.
+/// `INT_SPELL_POINTS_SPREAD_TEMPLATE` ("%d to %d"), not the float `SPELL_POINTS_SPREAD_TEMPLATE`,
+/// which would print "14.0 to 22.0" where Fireball rank 1 says "14 to 22".
 fn spread_text(min: i64, max: i64, ctx: &TokenContext) -> Option<String> {
     (ctx.text)("INT_SPELL_POINTS_SPREAD_TEMPLATE", &[min, max])
 }
@@ -121,7 +75,7 @@ fn trim_float(v: f64) -> String {
     }
 }
 
-/// One token's substituted text + the numeric value the `$l` plural picker keys on.
+/// One token's text and the numeric value the `$l` plural picker keys on.
 fn token_value(
     letter: char,
     slot: usize,
@@ -196,21 +150,19 @@ fn token_value(
             Some((trim_float(v), v))
         }
         'z' => {
-            // Player state, not spell data: the home-bind area name (see TokenContext).
+            // Player state, not spell data: the home-bind area name.
             let name = ctx.home_area?;
             Some((name.to_string(), 0.0))
         }
         'r' => {
-            // The range's max yards — resolved by the caller's range catalog at view-build time
-            // would be cleaner, but the token is rare in descriptions; the display carries the
-            // index only, so leave unresolved here (pass through).
+            // Left raw: the display carries only the range index.
             None
         }
         _ => None,
     }
 }
 
-/// Substitute every `$`-token in `text` against `spell` (byte-verified formulas, module doc).
+/// Substitute every `$`-token in `text` against `spell`.
 pub fn substitute(text: &str, spell: &SpellDisplay, ctx: &TokenContext) -> String {
     let bytes = text.as_bytes();
     let mut out = String::with_capacity(text.len());
@@ -225,7 +177,7 @@ pub fn substitute(text: &str, spell: &SpellDisplay, ctx: &TokenContext) -> Strin
         }
         let start = i;
         i += 1;
-        // $/N; or $*N; — scale the next token.
+        // `$/N;` or `$*N;` scales the next token.
         let mut scale = 1.0f64;
         if i < bytes.len() && (bytes[i] == b'/' || bytes[i] == b'*') {
             let op = bytes[i];
@@ -268,7 +220,7 @@ pub fn substitute(text: &str, spell: &SpellDisplay, ctx: &TokenContext) -> Strin
                                 b
                             }
                         }
-                        _ => a, // $g: the male form until a caster-gender input exists
+                        _ => a, // $g: the first form, as there is no gender input
                     };
                     out.push_str(pick);
                     i = i + 1 + end + 1;
@@ -276,20 +228,23 @@ pub fn substitute(text: &str, spell: &SpellDisplay, ctx: &TokenContext) -> Strin
                 }
             }
         }
-        // The token letter + its optional 1-based slot digit.
+        // The token letter and its optional 1-based slot digit.
         let Some(&letter_b) = bytes.get(i) else {
             out.push('$');
             continue;
         };
         let letter = letter_b as char;
         if !letter.is_ascii_alphabetic() {
-            out.push_str(&text[start..i + 1]);
-            i += 1;
+            // Not a token: keep `$` and the next char raw, stepping by its UTF-8 width (`$é`).
+            let ch_len = utf8_len(letter_b);
+            out.push_str(&text[start..i + ch_len]);
+            i += ch_len;
             continue;
         }
         i += 1;
         let slot = if i < bytes.len() && bytes[i].is_ascii_digit() {
-            let s = (bytes[i] - b'1') as usize;
+            // `$s0` is a 1-based slot below 1: saturate to slot 0 rather than wrap.
+            let s = bytes[i].saturating_sub(b'1') as usize;
             i += 1;
             s.min(2)
         } else {
@@ -310,7 +265,7 @@ pub fn substitute(text: &str, spell: &SpellDisplay, ctx: &TokenContext) -> Strin
                 last_value = val;
                 out.push_str(&sub);
             }
-            None => out.push_str(&text[start..i]), // unknown token: keep raw (fold-back flag)
+            None => out.push_str(&text[start..i]), // unknown token: keep raw
         }
     }
     out
@@ -330,13 +285,7 @@ mod tests {
     use super::*;
     use crate::spells::SpellDisplay;
 
-    /// The string table these tests resolve against — **deliberately not the shipped wording**.
-    ///
-    /// What is under test here is which KEY the engine reaches for and which numbers fill it,
-    /// never what the sentence says (decision 2045). A fixture that echoed the real strings would
-    /// pass on a *wrong* key wherever two of them agree in English, which is exactly how
-    /// `LASTONLINE_HOURS_P1`'s wording came to be spelled into the duration ladder in the first
-    /// place. It is also the idiom `benilla_ui::script::tests::tooltip` uses for the same reason.
+    /// Deliberately unlike the shipped wording, so a wrong key cannot pass by reading the same.
     fn text(key: &str, args: &[i64]) -> Option<String> {
         let n = |i: usize| args.get(i).copied().unwrap_or_default();
         Some(match key {
@@ -365,12 +314,6 @@ mod tests {
         }
     }
 
-    /// **The duration ladder picks its key by unit and by plural**, and the plural rule is
-    /// `GetText`'s: the bare token at exactly one, the `_P1` twin otherwise. Only HOURS ships a
-    /// twin, so the other three units read the same at one as at nine.
-    ///
-    /// The days arm is here because the reference's ladder has one and this file did not — a
-    /// two-day aura used to read as an hour count.
     #[test]
     fn the_duration_ladder_picks_unit_then_plural() {
         let mut durations = SpellDurationCatalog::default();
@@ -408,8 +351,8 @@ mod tests {
         None
     }
 
-    /// The byte formula: base 13, dice 1, sides 9 → "14 to 22" (Fireball rank 1's shape); a
-    /// diceless effect prints one value.
+    /// Base 13 and one 9-sided die give "14 to 22", Fireball rank 1's shape; a diceless effect
+    /// prints one value.
     #[test]
     fn s_token_bounds() {
         let durations = SpellDurationCatalog::default();
@@ -435,8 +378,6 @@ mod tests {
         );
     }
 
-    /// $o totals per-tick over the duration; $d prints the duration; $t the period; the $/N
-    /// scale divides; $l picks plural by the last value.
     #[test]
     fn overtime_duration_period_scale_plural() {
         let mut durations = SpellDurationCatalog::default();
@@ -457,12 +398,11 @@ mod tests {
         );
         assert_eq!(
             substitute("Restores $/2;s1 health: $l point:points;.", &d, &c),
-            // 3/2 rounds to 2 (min==max==3 scaled by 0.5 → 2, rounded); plural picks "points"
+            // 3 halved is 1.5, which rounds to 2; the plural picks "points"
             "Restores 2 health: points.".to_string()
         );
     }
 
-    /// Cross-spell refs resolve through the lookup; unknown tokens pass through visibly.
     #[test]
     fn cross_spell_and_unknown_tokens() {
         let durations = SpellDurationCatalog::default();
@@ -487,7 +427,6 @@ mod tests {
             "as strong as 100 hits"
         );
         assert_eq!(substitute("stacks $u times", &d, &c), "stacks $u times");
-        // $z — the home-bind area (the hearthstone's "Returns you to $z."); raw when unfed.
         assert_eq!(
             substitute("Returns you to $z.", &d, &c),
             "Returns you to Goldshire."
@@ -504,4 +443,20 @@ mod tests {
             "Returns you to $z."
         );
     }
+
+    #[test]
+    fn a_dollar_before_a_multibyte_char_passes_through_on_the_char_boundary() {
+        let durations = SpellDurationCatalog::default();
+        let radii = SpellRadiusCatalog::default();
+        let d = SpellDisplay {
+            effect_base_points: [13, 24, 0],
+            effect_base_dice: [1, 0, 0],
+            effect_die_sides: [9, 0, 0],
+            ..Default::default()
+        };
+        let c = ctx(&durations, &radii, &none_lookup);
+        assert_eq!(substitute("coûte $é or $…!", &d, &c), "coûte $é or $…!");
+        assert_eq!(substitute("$é", &d, &c), "$é");
+        assert_eq!(substitute("$s0", &d, &c), "<14..22>");
+    }
 }
diff --git a/crates/benilla-formats/src/stable_slot_prices.rs b/crates/benilla-formats/src/stable_slot_prices.rs
index 16fefd0c..ada45d84 100644
--- a/crates/benilla-formats/src/stable_slot_prices.rs
+++ b/crates/benilla-formats/src/stable_slot_prices.rs
@@ -1,15 +1,7 @@
-//! `StableSlotPrices.dbc` — the hunter stable's purchase-ladder price table (decision 1676).
-//!
-//! **2 rows × 2 `u32` columns** (`ID`, price in copper), read out of the real 5875 `dbc.MPQ` this
-//! session: row 1 = `500` (5 silver), row 2 = `50000` (5 gold). That is the whole table — there is
-//! no sentinel tail and no third row, which is the [`super::bank_bag_slot_prices`] ladder's one
-//! structural difference from this one (that table ships 12 rows of which only 6 are reachable).
-//!
-//! **Two slots is corroborated three ways**, which is why nothing here hardcodes the cap: the DBC
-//! has two rows, vmangos's `MAX_PET_STABLES` is 2 (`src/game/Objects/Pet.h:37`), and the reference
-//! UI's `NUM_PET_STABLE_SLOTS` is 2 (`PetStable.lua:1`). The client's job is only to price the
-//! *next* slot; `CMSG_BUY_STABLE_SLOT` carries no index at all — the server buys
-//! `m_stableSlots + 1` itself (`NPCHandler.cpp:704-729`) — so a row id here IS a slot number.
+//! `StableSlotPrices.dbc`: the copper price of each hunter stable slot, two rows (5 silver, 5 gold)
+//! with no sentinel tail, matching vmangos `MAX_PET_STABLES` (`Objects/Pet.h:37`) and the stock
+//! `NUM_PET_STABLE_SLOTS` (`PetStable.lua:1`). `CMSG_BUY_STABLE_SLOT` carries no index: the server
+//! buys `m_stableSlots + 1` itself (`NPCHandler.cpp:704-729`), so a row id is a slot number.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -24,11 +16,8 @@ const STABLE_SLOT_PRICES: &str = "DBFilesClient\\StableSlotPrices.dbc";
 pub struct StableSlotPrices(HashMap<u32, u32>);
 
 impl StableSlotPrices {
-    /// The cost of the *next* stable slot, given `purchased_count` already bought (slot
-    /// `purchased_count + 1`, 1-based to match the DBC's row ids). `None` past the table — which is
-    /// the "both slots owned" state the reference reads by comparing `GetNumStableSlots()` against
-    /// `NUM_PET_STABLE_SLOTS` and hiding the purchase button outright (`PetStable.lua:196-199`).
-    /// The absence is a data fact, not a cap this reader knows.
+    /// The price of slot `purchased_count + 1`; `None` once both are owned, where the stock UI
+    /// hides the purchase button (`PetStable.lua:196-199`).
     pub fn next_slot_price(&self, purchased_count: u8) -> Option<u32> {
         self.0.get(&(u32::from(purchased_count) + 1)).copied()
     }
@@ -57,7 +46,6 @@ pub fn load_stable_slot_prices(chain: &mut Chain) -> Result<StableSlotPrices> {
     table_from(&bytes)
 }
 
-/// The parse itself, split from the chain read so the golden test drives the identical path.
 fn table_from(bytes: &[u8]) -> Result<StableSlotPrices> {
     let rs = parse(bytes, schema(), "StableSlotPrices")?;
     let mut prices = HashMap::with_capacity(rs.records().len());
@@ -73,9 +61,7 @@ fn table_from(bytes: &[u8]) -> Result<StableSlotPrices> {
 mod tests {
     use super::*;
 
-    /// A hand-built WDBC carrying the real 5875 table, byte for byte as `dbc.MPQ` ships it
-    /// (extracted and dumped this session: 37 bytes total — a 20-byte header, two 8-byte records,
-    /// and a 1-byte string block holding the empty string).
+    /// The shipped 37-byte file: a 20-byte header, two 8-byte records, a 1-byte string block.
     fn synthesize() -> Vec<u8> {
         let rows: &[[u32; 2]] = &[[1, 500], [2, 50_000]];
         let mut dbc = Vec::new();
@@ -93,21 +79,15 @@ mod tests {
         dbc
     }
 
-    /// The shipped ladder, as the window prices it: a hunter who owns nothing is quoted 5 silver,
-    /// one who owns a slot is quoted 5 gold, and one who owns both is quoted nothing at all.
     #[test]
     fn the_shipped_ladder_prices_each_next_slot() {
         let t = table_from(&synthesize()).expect("parse");
         assert_eq!(t.len(), 2, "5875 ships exactly two stable slots");
         assert_eq!(t.next_slot_price(0), Some(500));
         assert_eq!(t.next_slot_price(1), Some(50_000));
-        // Past the table: the purchase button is hidden here, and a `None` is what says so.
         assert_eq!(t.next_slot_price(2), None);
     }
 
-    /// The real file, when there is an install to read it from. The synthesized golden above is
-    /// what the logic is tested against; this is the tripwire that the golden still *matches the
-    /// shipped bytes* — a silent divergence would otherwise price the window wrong forever.
     #[test]
     fn the_golden_matches_the_installed_table() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/stationery.rs b/crates/benilla-formats/src/stationery.rs
index fe00d67a..a4f97fad 100644
--- a/crates/benilla-formats/src/stationery.rs
+++ b/crates/benilla-formats/src/stationery.rs
@@ -1,21 +1,7 @@
-//! `Stationery.dbc` — the mail-window's letter-backdrop lookup (decision 0544).
-//!
-//! A mail carries a `stationery` id on the wire (`SMSG_MAIL_LIST_RESULT`); the reference client
-//! resolves that id to a texture *basename* through this table and paints the open-letter backdrop
-//! from `Interface\Stationery\<basename>1` (left half) + `<basename>2` (right half) — see
-//! `MailFrame.lua`'s `OpenMail_Update` (`STATIONERY_PATH..texture.."1"/"2"`).
-//!
-//! The 5875 schema was read byte-level from the real `patch.MPQ` file (VERIFIED at decision time):
-//! WDBC header `record_count = 5`, `field_count = 4`, `record_size = 16`, string block 62 bytes —
-//! four 4-byte fields, the third a string ref: `{ID, ItemID, Texture, Flags}`. Fields 1 and 3
-//! were filler until wow-re carved the send side (`ui/scratch/stationery-bindings.md`, 1970):
-//! `ItemID` is the stationery ITEM the player buys or carries to use the paper, and `Flags & 1`
-//! marks the one always available (`41 Default Stationery`, BuyPrice 0). The client's usable list
-//! is `(Flags & 1 || the player carries ItemID) && the item's template is cached`, sorted by
-//! BuyPrice ascending — the `GetNumStationeries`/`GetStationeryInfo` surface. The verified rows:
-//! `1/41 → STATIONERYTEST`, `61 → GMSTATIONERY`, `62 → AUCTIONSTATIONERY`, `64 → STATIONERY_VAL`
-//! (both target BLPs exist in the archive; MPQ path lookup is case-insensitive, so the uppercase
-//! DBC string resolves the mixed-case file).
+//! `Stationery.dbc`: a mail's `stationery` id (`SMSG_MAIL_LIST_RESULT`) → the texture basename
+//! `OpenMail_Update` paints as `Interface\Stationery\<basename>1` and `2`, the left and right
+//! halves. The send side lists a row when its item's template is cached and either `Flags & 1`
+//! (`0x4aca2a`) or the player carries its `ItemID` (`0x4aca1c`); the list sorts by buy price.
 
 use std::collections::HashMap;
 
@@ -27,39 +13,32 @@ use crate::dbc::{parse, str_at, u32_at};
 
 const STATIONERY: &str = "DBFilesClient\\Stationery.dbc";
 
-/// `MAIL_STATIONERY_DEFAULT` — vmangos stores every player mail with this id (the client's
-/// stationery choice is discarded server-side, decision 0544). Its verified texture basename is the
-/// [`StationeryCatalog::DEFAULT_TEXTURE`] fallback.
+/// vmangos `MAIL_STATIONERY_DEFAULT`; the server stores every player mail with it.
 pub const STATIONERY_DEFAULT: u32 = 41;
 
-/// One `Stationery.dbc` row (the module doc's four columns).
+/// One `Stationery.dbc` row.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct StationeryRow {
     /// The stationery id a mail carries on the wire and `SelectStationery` stores.
     pub id: u32,
-    /// The stationery item — bought or carried to use this paper.
+    /// The item that makes this paper usable when carried.
     pub item: u32,
-    /// The texture basename (the `Interface\Stationery\<basename>N` stem).
     pub texture: String,
     /// `& 1`: always available, carried or not.
     pub flags: u32,
 }
 
-/// `Stationery.dbc`: stationery id → texture basename (the `Interface\Stationery\<basename>N` stem),
-/// and the rows whole for the send side's usable list.
+/// Stationery id → texture basename, plus the rows for the send side's list.
 pub struct StationeryCatalog {
     rows: Vec<StationeryRow>,
     by_id: HashMap<u32, String>,
 }
 
 impl StationeryCatalog {
-    /// The verified basename of the default stationery (id 41) — the fallback when a mail's id is
-    /// missing from the table or the DBC failed to load. VERIFIED against the real file's string
-    /// block (id 41's actual `Texture` value), NOT an assumed constant.
+    /// Id 41's `Texture` in the shipped file, the fallback for an unknown id or a failed load.
     pub const DEFAULT_TEXTURE: &'static str = "STATIONERYTEST";
 
-    /// The texture basename for a stationery id, falling back to [`Self::DEFAULT_TEXTURE`] for any
-    /// id the table doesn't carry (unknown/AH/creature stationery still renders a valid backdrop).
+    /// The basename for a stationery id, or [`Self::DEFAULT_TEXTURE`] for one the table lacks.
     pub fn texture(&self, id: u32) -> &str {
         self.by_id
             .get(&id)
@@ -67,8 +46,7 @@ impl StationeryCatalog {
             .unwrap_or(Self::DEFAULT_TEXTURE)
     }
 
-    /// The texture basename for a stationery id the table carries — `None` for an id gap, which
-    /// is what `GetSelectedStationeryTexture` answers with (no default there).
+    /// The basename with no fallback, as `GetSelectedStationeryTexture` answers.
     pub fn texture_of(&self, id: u32) -> Option<&str> {
         self.by_id.get(&id).map(String::as_str)
     }
@@ -79,7 +57,7 @@ impl StationeryCatalog {
     }
 }
 
-/// Load `Stationery.dbc` into an id → basename map (see the module doc for the verified schema).
+/// Load `Stationery.dbc` from the patch chain.
 pub fn load_stationery_catalog(chain: &mut Chain) -> Result<StationeryCatalog> {
     let bytes = chain
         .read_file(STATIONERY)
diff --git a/crates/benilla-formats/src/talents.rs b/crates/benilla-formats/src/talents.rs
index e2dbe412..62f30d8a 100644
--- a/crates/benilla-formats/src/talents.rs
+++ b/crates/benilla-formats/src/talents.rs
@@ -1,36 +1,10 @@
-//! `Talent.dbc` + `TalentTab.dbc` loader — the vanilla talent trees' data plane (decision 0304):
-//! each class's three tabs, and each tab's talents with grid position, rank spells, and
-//! prerequisites. The window ([`benilla`]'s ui_talent) renders these; the learn click sends
-//! `CMSG_LEARN_TALENT` with a row id from here.
+//! `Talent.dbc` and `TalentTab.dbc`: each class's three talent tabs, and each tab's talents with
+//! grid seat, rank spells and prerequisites; `CMSG_LEARN_TALENT` carries a row id from here. The
+//! columns are vmangos's `TalentEntry` and `TalentTabEntry` (`DBCStructure.h`).
 //!
-//! Layout — VERIFIED against the **vmangos server source** (`DBCStructure.h`'s
-//! `TalentEntry`/`TalentTabEntry` + `DBCfmt.h`'s format strings), the same standing as
-//! [`crate::skill_lines`]: vmangos parses these tables off the same build-5875 client data.
-//!
-//! `Talent.dbc` — `TalentEntryfmt = "niiiiiiiixxxxixxixxxi"` (21 fields, 84 B/record):
-//! `id`(0, indexed) · **`tabId` = column 1** (a `TalentTab.dbc` id) · **`row` = column 2**
-//! (tier, 0-based) · **`col` = column 3** (0-based) · **`rankSpell[5]` = columns 4–8** (the
-//! spell taught per rank; 0 = the talent has fewer ranks; columns 9–12 are the enum's unused
-//! rank slots) · **`prereqTalent` = column 13** (14–15 unused prereq slots) · **`prereqRank` =
-//! column 16** (0-based; 17–18 unused) · **flags = column 19** (bit 0 = the Lua API's
-//! `isExceptional` — the client's `TalentRec+0x4c` bit0 read, wow-re `ui/scratch/talent-api.md`)
-//! · **`requiredSpell` = column 20**.
-//!
-//! `TalentTab.dbc` — `TalentTabEntryfmt = "nxxxxxxxxxxxiix"` (15 fields, 60 B/record):
-//! `id`(0, indexed) · the 8-locale `name_lang` block (1..8, enUS first ⇒ **NameEnUs = column
-//! 1**) + its flags word (9) · `spellIcon`(10, unused by the 1.12 window) · **`raceMask` =
-//! column 11** (511 = all races this build) · **`classMask` = column 12** · `orderIndex`(13 —
-//! **never read by the client**: the shipped data ties the mage's Arcane/Fire at 0, raw-dump
-//! verified) · **`backgroundFile` = column 14** (a string: the
-//! `Interface\TalentFrame\<base>-{TopLeft,TopRight,BottomLeft,BottomRight}` art base).
-//!
-//! **Order is the law here** (byte-verified — the 0305 fold-back, wow-re `talent-api.md`):
-//! `GetTalentInfo(tab, index)` indexes the tab's talents by **native DBC row order**
-//! (`TalentTabInfo[+0xC] + (index−1)*0x54`, a contiguous per-tab block — never a (tier, column)
-//! re-sort), and a class's tabs come in **raw file order** among rows matching BOTH raceMask and
-//! classMask (`0x4f2e50`). The shipped 1.12 data happens to author every tab's block in
-//! (tier, column) order (27/27 tabs) — a coincidence the real-data test documents, not a rule
-//! this reader imposes.
+//! Order matters: `GetTalentInfo(tab, index)` indexes a tab's talents in native row order
+//! (`TalentTabInfo[+0xC] + (index−1)*0x54`), never a (tier, column) sort, and a class's tabs come
+//! in file order among rows matching both masks (`0x4f2e50`), never by `orderIndex` (column 13).
 
 use std::collections::HashMap;
 
@@ -62,7 +36,7 @@ const COL_TT_BACKGROUND: usize = 14;
 /// The vanilla rank ceiling (`MAX_TALENT_RANK`, vmangos `DBCStructure.h`).
 pub const MAX_TALENT_RANK: usize = 5;
 
-/// One `Talent.dbc` row — a talent's grid seat, rank spells, and prerequisites.
+/// One `Talent.dbc` row: a talent's grid seat, rank spells and prerequisites.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Talent {
     pub id: u32,
@@ -74,50 +48,45 @@ pub struct Talent {
     pub col: u32,
     /// The spell taught at each rank; a talent with `n` ranks fills exactly the first `n`.
     pub ranks: [u32; MAX_TALENT_RANK],
-    /// Prerequisite talent id (0 = none) + the rank (0-based) it must be learned to. In the
-    /// shipped 1.12 data every prerequisite lives in the same tab (asserted by the real-data
-    /// test) — the reference frame only ever draws same-tab arrows.
+    /// Prerequisite talent id (0 for none) and the 0-based rank it needs. Every shipped
+    /// prerequisite is in the same tab, the only arrows the reference frame draws.
     pub prereq_talent: u32,
     pub prereq_rank: u32,
     /// A spell that must be known regardless of talents (0 = none).
     pub required_spell: u32,
-    /// Flags bit 0 — the Lua API's `isExceptional` (an activatable-ability talent; the
-    /// client's tooltip builder branches on it).
+    /// Flags bit 0 (`TalentRec+0x4c`), the Lua API's `isExceptional`: an activatable ability.
     pub exceptional: bool,
 }
 
 impl Talent {
-    /// How many ranks this talent actually has (the count of populated rank spells).
+    /// How many ranks this talent has, the count of populated rank spells.
     pub fn max_rank(&self) -> u32 {
         self.ranks.iter().take_while(|&&s| s != 0).count() as u32
     }
 }
 
-/// One `TalentTab.dbc` row — a class page's identity.
+/// One `TalentTab.dbc` row, a class page.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct TalentTabInfo {
     pub id: u32,
     pub name: String,
-    /// `raceMask`/`classMask` — bit `1 << (race/class − 1)`; the client admits a tab only when
-    /// BOTH match (511 = every race in the shipped data).
+    /// `raceMask` and `classMask`, bit `1 << (id − 1)`; the client admits a tab only when both
+    /// match (511 is every race in the shipped data).
     pub race_mask: u32,
     pub class_mask: u32,
-    /// The `Interface\TalentFrame\<background>-…` art base ("MageFire", …).
+    /// The `Interface\TalentFrame\<background>-…` art base ("MageFire").
     pub background: String,
 }
 
-/// The joined talent data plane: tabs by class, talents by tab.
+/// Talent tabs by class and talents by tab.
 pub struct TalentCatalog {
     tabs: Vec<TalentTabInfo>,
-    /// tab id → its talents in **native DBC row order** — the byte-verified enumeration
-    /// `GetTalentInfo` indexes by (module doc; never re-sorted).
+    /// Tab id to its talents in native row order, the order `GetTalentInfo` indexes.
     by_tab: HashMap<u32, Vec<Talent>>,
 }
 
 impl TalentCatalog {
-    /// A race+class's tabs (unit bytes, 1-based) in **raw file order** — the byte-verified tab
-    /// law (module doc: `0x4f2e50` filters on BOTH masks and never reads `orderIndex`; file
-    /// order alone reproduces the canonical Arcane/Fire/Frost page order).
+    /// A race and class's tabs (unit bytes, 1-based) in file order, as `0x4f2e50` filters them.
     pub fn tabs_for_class(&self, race: u8, class: u8) -> Vec<&TalentTabInfo> {
         if !(1..=32).contains(&class) || !(1..=32).contains(&race) {
             return Vec::new();
@@ -130,13 +99,12 @@ impl TalentCatalog {
             .collect()
     }
 
-    /// A tab's talents in native DBC row order — the display/index order (byte-verified, see
-    /// [`TalentCatalog::by_tab`]).
+    /// A tab's talents in native row order, the display and index order.
     pub fn talents_in_tab(&self, tab_id: u32) -> &[Talent] {
         self.by_tab.get(&tab_id).map(Vec::as_slice).unwrap_or(&[])
     }
 
-    /// One talent by id (the prereq-arrow resolve).
+    /// One talent by id, for resolving a prerequisite arrow.
     pub fn talent(&self, tab_id: u32, talent_id: u32) -> Option<&Talent> {
         self.talents_in_tab(tab_id)
             .iter()
@@ -174,7 +142,7 @@ fn talent_tab_schema() -> Schema {
     s
 }
 
-/// Load the talent data plane off the patch chain.
+/// Load both tables off the patch chain.
 pub fn load_talent_catalog(chain: &mut Chain) -> Result<TalentCatalog> {
     let tab_bytes = chain
         .read_file(TALENT_TAB)
@@ -212,7 +180,7 @@ pub fn load_talent_catalog(chain: &mut Chain) -> Result<TalentCatalog> {
             required_spell: u32_at(r, COL_T_REQUIRED_SPELL).unwrap_or(0),
             exceptional: u32_at(r, COL_T_FLAGS).unwrap_or(0) & 1 != 0,
         };
-        // Native row order preserved — the enumeration law (module doc); never sorted.
+        // Native row order, never sorted.
         by_tab.entry(t.tab).or_default().push(t);
     }
 
@@ -223,11 +191,6 @@ pub fn load_talent_catalog(chain: &mut Chain) -> Result<TalentCatalog> {
 mod tests {
     use super::*;
 
-    /// The real build-5875 tables, structurally (skips without client data): the mage's three
-    /// canonical pages in order with their art bases, and the whole table's grid/rank/prereq
-    /// invariants — every talent seats inside the 4-wide/≤8-tier grid, rank arrays are
-    /// prefix-shaped, and every prerequisite resolves within its own tab (the reference frame
-    /// only draws same-tab arrows, so cross-tab data would falsify the renderer's assumption).
     #[test]
     fn real_talent_tables_hold_the_grid_and_prereq_invariants() {
         let data = crate::wow_data_or_skip!();
@@ -239,8 +202,6 @@ mod tests {
             cat.len()
         );
 
-        // The mage pages (class 8): Arcane, Fire, Frost in raw file order (the byte-verified
-        // tab law — orderIndex is dead data), with their art bases.
         const HUMAN: u8 = 1;
         const MAGE: u8 = 8;
         let tabs = cat.tabs_for_class(HUMAN, MAGE);
@@ -254,13 +215,12 @@ mod tests {
                 .collect::<Vec<_>>(),
             vec!["MageArcane", "MageFire", "MageFrost"]
         );
-        // Every tab admits all races this build (raceMask 511) — the both-masks filter is
-        // exercised structurally: a race bit outside 511 admits nothing.
+        // Every shipped tab's raceMask is 511, so race 10 admits nothing.
         assert!(
             cat.tabs_for_class(10, MAGE).is_empty(),
             "race bit 10 is outside 511"
         );
-        // Every class (unit class bytes 1..=9, no class 10 in vanilla, druid = 11) has pages.
+        // Every class has pages; vanilla's classes are 1-5, 7-9 and 11 (druid).
         for class in [1u8, 2, 3, 4, 5, 7, 8, 9, 11] {
             let n = cat.tabs_for_class(HUMAN, class).len();
             assert_eq!(n, 3, "class {class} has three talent pages, got {n}");
@@ -269,9 +229,6 @@ mod tests {
         for tabs in cat.tabs_for_class(HUMAN, MAGE) {
             let talents = cat.talents_in_tab(tabs.id);
             assert!(!talents.is_empty());
-            // The shipped data authors every tab's NATIVE row order in (row, col) order — the
-            // 27/27 coincidence the module doc records (the reader imposes no sort; if a future
-            // patch chain broke this, the client (and we) would show the authored order).
             let seats: Vec<(u32, u32)> = talents.iter().map(|t| (t.row, t.col)).collect();
             let mut sorted = seats.clone();
             sorted.sort();
@@ -282,7 +239,6 @@ mod tests {
             );
         }
 
-        // Whole-table invariants.
         let all_ids: std::collections::HashSet<u32> =
             cat.by_tab.values().flatten().map(|t| t.id).collect();
         for t in cat.by_tab.values().flatten() {
diff --git a/crates/benilla-formats/src/taxi.rs b/crates/benilla-formats/src/taxi.rs
index 03a62e55..3bf8dc3e 100644
--- a/crates/benilla-formats/src/taxi.rs
+++ b/crates/benilla-formats/src/taxi.rs
@@ -1,19 +1,7 @@
-//! `TaxiPathNode.dbc` — a taxi/transport path's ordered waypoints (map + world position, a
-//! station-stop flag, and a stop delay). Every flight path AND every `MO_TRANSPORT`
-//! (boat/zeppelin, decision 0438) is one `TaxiPath.dbc` id whose nodes live here, keyed by
-//! `TaxiPath.dbc`'s id (this table's `PathID` column) — `TaxiPath.dbc` itself only carries the
-//! `(fromNode, toNode, cost)` triple for the flight-master UI and is not adapted separately yet.
-//!
-//! **9 fields (verified this session, raw-parsed against build 5875):**
-//! `ID(0), PathID(1), NodeIndex(2), MapID(3), LocX(4), LocY(5), LocZ(6), Flags(7), Delay(8)` —
-//! matching vmangos's own `TaxiPathNodeEntry` column comments (`DBCStructure.h:696-707`,
-//! `m_ID/m_PathID/m_NodeIndex/m_ContinentID/m_LocX/m_LocY/m_LocZ/m_flags/m_delay`) field-for-field.
-//! A path's nodes are **not** confined to one continent: path 302 (Orgrimmar–Undercity) has 36
-//! nodes spanning `MapID` `{1, 0}` (Kalimdor, Azeroth) — the map-change itself is where the
-//! transport timetable builder (`crate::transports`) inserts a teleport keyframe, never a spline
-//! segment. `Flags == 2` marks a station stop (vmangos `KeyFrame::IsStopFrame`, exact equality,
-//! not a bitmask test) and pairs with a nonzero `Delay` (seconds) at that node: path 302 stops
-//! twice, 60 s each; path 285 (27 nodes) stops at node indexes 4 and 20.
+//! `TaxiPathNode.dbc`, the ordered waypoints of every flight path and every `MO_TRANSPORT` (boat,
+//! zeppelin), keyed by `TaxiPath.dbc` id; the layout is vmangos's `TaxiPathNodeEntry`
+//! (`DBCStructure.h:696-707`). A path can cross maps (302, Orgrimmar to Undercity, spans 1 and 0),
+//! and the transport timetable (`crate::transports`) turns a map change into a teleport keyframe.
 
 use std::collections::HashMap;
 
@@ -25,26 +13,23 @@ use crate::Chain;
 
 const TAXI_PATH_NODE: &str = "DBFilesClient\\TaxiPathNode.dbc";
 
-/// One `TaxiPathNode.dbc` row — a single waypoint on a taxi/transport path.
+/// One `TaxiPathNode.dbc` row, a waypoint on a taxi or transport path.
 #[derive(Clone, Copy, Debug)]
 pub struct TaxiPathNode {
-    /// The row's own id (`ID`) — a global waypoint id, not meaningful outside this table.
+    /// The row's own id, meaningless outside this table.
     pub id: u32,
-    /// `TaxiPath.dbc` id this node belongs to (the catalog's key).
+    /// The `TaxiPath.dbc` id this node belongs to.
     pub path_id: u32,
-    /// Ordinal position within the path, `0`-based — the catalog sorts each path's nodes by
-    /// this field, so the stored `Vec` order already matches path traversal order.
+    /// 0-based position in the path, the order the catalog stores each path in.
     pub node_index: u32,
     /// The map this node's `pos` is expressed in (`Map.dbc` id).
     pub map_id: u32,
     /// World position `(x, y, z)` on `map_id`.
     pub pos: [f32; 3],
-    /// Raw `actionFlag`. Bit `1` (`flags & 2`) marks a station stop — the client tests it as a
-    /// bitmask (`0x5f4e37`, wow-re §5 2026-07-17; vmangos's `IsStopFrame` uses `== 2`, identical
-    /// on the live data); bit `0` (`flags & 1`) marks a map-change/teleport trigger in the
-    /// transport timetable builder.
+    /// Raw `actionFlag`: `& 2` marks a station stop (the reference tests the bit at `0x5f4e37`,
+    /// vmangos `== 2`, the same on the shipped data) and `& 1` a teleport (`TransportMgr.cpp:134`).
     pub flags: u32,
-    /// Stop delay in whole seconds — only meaningful when `flags == 2`; `0` otherwise.
+    /// Stop delay in whole seconds, set on stops only.
     pub delay: u32,
 }
 
@@ -54,7 +39,7 @@ pub struct TaxiPathNodes {
 }
 
 impl TaxiPathNodes {
-    /// A path's nodes, in `NodeIndex` order, or `None` if the path id is unknown.
+    /// A path's nodes in `NodeIndex` order.
     pub fn path(&self, path_id: u32) -> Option<&[TaxiPathNode]> {
         self.paths.get(&path_id).map(Vec::as_slice)
     }
@@ -64,7 +49,7 @@ impl TaxiPathNodes {
         self.paths.iter().map(|(&id, nodes)| (id, nodes.as_slice()))
     }
 
-    /// Number of distinct paths (not the total node count).
+    /// The number of paths, not nodes.
     pub fn len(&self) -> usize {
         self.paths.len()
     }
@@ -74,7 +59,6 @@ impl TaxiPathNodes {
     }
 }
 
-/// 9 fields per the module doc.
 fn schema() -> Schema {
     let mut s = Schema::new("TaxiPathNode");
     for name in ["ID", "PathID", "NodeIndex", "MapID"] {
@@ -89,8 +73,7 @@ fn schema() -> Schema {
     s
 }
 
-/// Read `TaxiPathNode.dbc` off the patch chain into a [`TaxiPathNodes`], each path's `Vec`
-/// sorted by `NodeIndex`.
+/// Read `TaxiPathNode.dbc` off the patch chain into a [`TaxiPathNodes`].
 pub fn load_taxi_path_nodes(chain: &mut Chain) -> Result<TaxiPathNodes> {
     let bytes = chain
         .read_file(TAXI_PATH_NODE)
@@ -126,9 +109,7 @@ pub fn load_taxi_path_nodes(chain: &mut Chain) -> Result<TaxiPathNodes> {
 mod tests {
     use super::*;
 
-    /// The real 5875 table proves the layout and the two pinned paths from the module doc: path
-    /// 302 (Orgrimmar–Undercity, 36 nodes spanning maps `{0,1}`, two `Flags==2` stops at 60 s
-    /// each) and path 285 (27 nodes, stops at indexes 4 and 20). Skips without client data.
+    /// The 5875 layout on path 302 (Orgrimmar to Undercity, two 60 s stops) and path 285.
     #[test]
     fn real_taxi_path_node_layout_sanity() {
         let data = crate::wow_data_or_skip!();
@@ -142,7 +123,6 @@ mod tests {
 
         let path302 = cat.path(302).expect("path 302 exists");
         assert_eq!(path302.len(), 36, "path 302 has 36 nodes");
-        // sorted by node_index
         for w in path302.windows(2) {
             assert!(
                 w[0].node_index < w[1].node_index,
diff --git a/crates/benilla-formats/src/taxi_nodes.rs b/crates/benilla-formats/src/taxi_nodes.rs
index 6855eb2f..8e95a07b 100644
--- a/crates/benilla-formats/src/taxi_nodes.rs
+++ b/crates/benilla-formats/src/taxi_nodes.rs
@@ -1,22 +1,7 @@
-//! `TaxiNodes.dbc` — every flight-master node: its map + world position, display name, and the
-//! per-team taxi-mount creature template it rides (decision 0484 phase 1). Loaded whole at
-//! startup, id-keyed — the taxi map's node list and the "which node am I nearest" resolve
-//! through this catalog. `TaxiPath.dbc` (`crate::taxi_path`) carries the direct-hop fare table
-//! between node pairs; `TaxiPathNode.dbc` (`crate::taxi`) carries a path's actual waypoints —
-//! three different tables, three different jobs.
-//!
-//! **16 fields (verified this session, raw-parsed against build 5875, matching vmangos's own
-//! `TaxiNodesEntry`, `DBCStructure.h:789-799`):** `ID(0), MapID(1), X(2), Y(3), Z(4)`, the
-//! 9-dword localized-name block (`Name_lang` 8 locale strings, columns 5-12, + a flags dword at
-//! 13 — the same loc-string shape `AreaPOI`/`AreaTable` use), then `MountCreatureID[2]` at
-//! columns 14-15 — **horde first, alliance second** (vmangos's own field comment:
-//! "horde[14]-alliance[15]"). Both are `CreatureTemplate` **entries**, not display ids — the
-//! taxi mount's actual look resolves through the normal creature-template chain, same as any
-//! other NPC (NOT a `CreatureDisplayInfo` id directly).
-//!
-//! Verified against the live table: id 2 is "Stormwind, Elwynn" on map 0, with `mount_horde = 0`
-//! / `mount_alliance = 541` — a human-city node offers no Horde service and a nonzero Alliance
-//! one, exactly as expected.
+//! `TaxiNodes.dbc`, every flight-master node: its map and position, name, and the taxi mount each
+//! team rides from it. The layout is vmangos's `TaxiNodesEntry` (`DBCStructure.h:789-799`): `ID`,
+//! `MapID`, `X`, `Y`, `Z`, the `Name` loc-string (5-13), then `MountCreatureID[2]`, Horde first.
+//! The mounts are `creature_template` entries, not display ids, resolved like any NPC's.
 
 use std::collections::HashMap;
 
@@ -28,23 +13,20 @@ use crate::Chain;
 
 const TAXI_NODES: &str = "DBFilesClient\\TaxiNodes.dbc";
 
-/// One `TaxiNodes.dbc` row — a flight-master node.
+/// One `TaxiNodes.dbc` row, a flight-master node.
 #[derive(Clone, Debug)]
 pub struct TaxiNode {
-    /// The row's own id — what `SMSG_SHOWTAXINODES`'s known-mask and `CMSG_ACTIVATETAXI`'s
-    /// node fields name.
+    /// The id `SMSG_SHOWTAXINODES`'s known-mask and `CMSG_ACTIVATETAXI`'s nodes name.
     pub id: u32,
     /// The map this node's `pos` is expressed in (`Map.dbc` id).
     pub map_id: u32,
     /// World position `(x, y, z)` on `map_id`.
     pub pos: [f32; 3],
-    /// The enUS display name (locale slot 0) — the taxi map's node label.
+    /// The enUS name (locale slot 0), the taxi map's node label.
     pub name: String,
-    /// `CreatureTemplate` entry of the taxi mount a Horde rider takes off from this node, `0` =
-    /// no Horde service here (e.g. an Alliance city node).
+    /// The `creature_template` entry of a Horde rider's taxi mount here, `0` for no Horde service.
     pub mount_horde: u32,
-    /// `CreatureTemplate` entry of the taxi mount an Alliance rider takes off from this node,
-    /// `0` = no Alliance service here.
+    /// The `creature_template` entry of an Alliance rider's taxi mount here, `0` for none.
     pub mount_alliance: u32,
 }
 
@@ -58,8 +40,7 @@ impl TaxiNodes {
         self.rows.get(&id)
     }
 
-    /// Every row, in no particular order — the taxi map's node list iterates this, filtered by
-    /// the known-mask and continent.
+    /// Every row, in no particular order.
     pub fn rows(&self) -> impl Iterator<Item = &TaxiNode> {
         self.rows.values()
     }
@@ -73,7 +54,6 @@ impl TaxiNodes {
     }
 }
 
-/// 16 fields per the module doc.
 fn schema() -> Schema {
     let mut s = Schema::new("TaxiNodes");
     s.add_field(SchemaField::new("ID", FieldType::UInt32));
@@ -122,11 +102,7 @@ pub fn load_taxi_nodes(chain: &mut Chain) -> Result<TaxiNodes> {
 mod tests {
     use super::*;
 
-    /// The real 5875 table proves the layout and the pinned Stormwind row: 85 nodes total, id 2
-    /// is "Stormwind, Elwynn" on map 0 (Eastern Kingdoms), with a nonzero Alliance mount (541)
-    /// and no Horde mount (0) — a human-city node offers Alliance-only service. Values dumped
-    /// from the real DBC this session (`dbc_to_csv` + a raw byte cross-check), not guessed.
-    /// Skips without client data.
+    /// The 5875 layout on Stormwind's node, which serves the Alliance only.
     #[test]
     fn real_taxi_nodes_layout_sanity() {
         let data = crate::wow_data_or_skip!();
@@ -143,7 +119,7 @@ mod tests {
             "Stormwind's Alliance gryphon mount template"
         );
 
-        // Sentinel Hill (Westfall), the other end of the pinned TaxiPath test's hop.
+        // The other end of the hop the `TaxiPath` test pins.
         let sentinel_hill = cat.get(4).expect("node 4 exists");
         assert_eq!(sentinel_hill.name, "Sentinel Hill, Westfall");
     }
diff --git a/crates/benilla-formats/src/taxi_path.rs b/crates/benilla-formats/src/taxi_path.rs
index 3d1a267b..95635a3b 100644
--- a/crates/benilla-formats/src/taxi_path.rs
+++ b/crates/benilla-formats/src/taxi_path.rs
@@ -1,14 +1,6 @@
-//! `TaxiPath.dbc` — the direct-hop fare table between two flight-master nodes: `(from, to, cost)`
-//! triples the flight-master UI walks to price a route (decision 0484 phase 1). Distinct from
-//! `TaxiPathNode.dbc` (`crate::taxi`), which carries a path's actual waypoints — this table is
-//! the coarse "does a direct hop from A to B exist, and what does it cost" lookup phase 2's route
-//! computation needs; a multi-hop trip chains several of these rows.
-//!
-//! **4 fields (verified this session, matching vmangos's own `TaxiPathEntry`,
-//! `DBCStructure.h:688-694`):** `ID(0), FromTaxiNode(1), ToTaxiNode(2), Price(3)`.
-//!
-//! Verified against the live table: id 6 is the direct hop `TaxiNodes` 2 ("Stormwind, Elwynn")
-//! → 4 ("Sentinel Hill, Westfall"), cost 110 copper.
+//! `TaxiPath.dbc`: the direct hops between flight-master nodes and their fares, laid out as vmangos
+//! `TaxiPathEntry` (`DBCStructure.h:688-694`); a multi-hop trip chains several. The waypoints are
+//! `TaxiPathNode.dbc`'s.
 
 use std::collections::HashMap;
 
@@ -20,20 +12,17 @@ use crate::Chain;
 
 const TAXI_PATH: &str = "DBFilesClient\\TaxiPath.dbc";
 
-/// One `TaxiPath.dbc` row — a direct hop between two flight-master nodes.
+/// One direct hop between two flight-master nodes.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct TaxiPath {
     pub id: u32,
     pub from: u32,
     pub to: u32,
-    /// Fare in copper for this one hop, undiscounted — vmangos applies the reputation discount
-    /// server-side before charging; the wire's `TaxiPath.dbc` copy never carries a discounted
-    /// figure.
+    /// The undiscounted fare in copper; vmangos applies the reputation discount when it charges.
     pub cost: u32,
 }
 
-/// `TaxiPath.dbc` rows keyed by `ID`, plus a `(from, to)` lookup for the route computation
-/// phase 2 needs.
+/// `TaxiPath.dbc` rows by id, plus a `(from, to)` lookup.
 pub struct TaxiPaths {
     rows: HashMap<u32, TaxiPath>,
     by_pair: HashMap<(u32, u32), u32>,
@@ -44,17 +33,14 @@ impl TaxiPaths {
         self.rows.get(&id)
     }
 
-    /// The direct hop from `from` to `to`, if `TaxiPath.dbc` carries one. The table is
-    /// directed — a two-way route is two separate rows, one per direction — so this only ever
-    /// matches the exact order asked for.
+    /// The direct hop from `from` to `to`; the table is directed, one row per direction.
     pub fn between(&self, from: u32, to: u32) -> Option<&TaxiPath> {
         self.by_pair
             .get(&(from, to))
             .and_then(|id| self.rows.get(id))
     }
 
-    /// Every direct hop leaving `node`, in no particular order — a route search expands a node
-    /// through this (phase 2).
+    /// Every direct hop leaving `node`, in no order.
     pub fn paths_from(&self, node: u32) -> impl Iterator<Item = &TaxiPath> {
         self.rows.values().filter(move |p| p.from == node)
     }
@@ -68,7 +54,6 @@ impl TaxiPaths {
     }
 }
 
-/// 4 fields per the module doc.
 fn schema() -> Schema {
     let mut s = Schema::new("TaxiPath");
     for name in ["ID", "FromTaxiNode", "ToTaxiNode", "Cost"] {
@@ -98,10 +83,7 @@ pub fn load_taxi_paths(chain: &mut Chain) -> Result<TaxiPaths> {
 mod tests {
     use super::*;
 
-    /// The real 5875 table proves the layout and the pinned Stormwind→Sentinel Hill hop: 287
-    /// rows total, id 6 is the direct `2 → 4` hop at cost 110. Cross-checked with
-    /// [`crate::taxi_nodes::tests::real_taxi_nodes_layout_sanity`]'s node names. Skips without
-    /// client data.
+    /// Hop 6 runs Stormwind (node 2) to Sentinel Hill (node 4) for 110 copper.
     #[test]
     fn real_taxi_path_layout_sanity() {
         let data = crate::wow_data_or_skip!();
@@ -114,7 +96,6 @@ mod tests {
         assert_eq!(hop.cost, 110);
         assert!(hop.cost > 0, "a real hop always carries a nonzero fare");
 
-        // paths_from surfaces the same row when walking node 2's outgoing hops.
         assert!(cat.paths_from(2).any(|p| p.to == 4 && p.cost == 110));
     }
 }
diff --git a/crates/benilla-formats/src/terrain.rs b/crates/benilla-formats/src/terrain.rs
index 6c7420ca..d333096d 100644
--- a/crates/benilla-formats/src/terrain.rs
+++ b/crates/benilla-formats/src/terrain.rs
@@ -1,19 +1,9 @@
-//! ADT terrain → per-chunk triangle meshes (Phase 2 + Phase 6 splat).
+//! ADT terrain to per-chunk triangle meshes, in raw WoW world coords (+X north, +Y west, +Z up).
 //!
-//! Output is in **raw WoW world coords** (+X north, +Y west, +Z up, yards); the renderer
-//! (`benilla`) applies the WoW→Bevy transform. Each MCNK contributes one [`ChunkMesh`]
-//! built as the binary's **145-vertex center-fan** (B1): 81 outer verts (9×9 corner grid) + 64 inner
-//! center verts (8×8 at +½-cell horizontal in both planar axes), each cell rendered as 4
-//! triangles fanning from its center to its 4 corners. Each inner vertex carries its **own**
-//! authored MCVT center height (independent sample, NOT a corner average — dropping it was
-//! the "flattened hilltops" defect). Holes (B2, `MCNK+0x3C`) omit a 2×2-cell block from the
-//! index buffer; the underlying verts stay (unreferenced).
-//!
-//! Vertex layout mirrors MCVT's on-disk **stride-17 interleave** (row r: 9 outer then 8 inner;
-//! final row 9 outer only): outer `(r,c)` for r,c ∈ 0..=8 is at `r·17+c`; inner `(r,c)` for
-//! r,c ∈ 0..=7 is at `r·17+9+c`. Positions, normals (MCNR `[X,Y,Z]` raw, no swap), and
-//! 0..1 UVs are parallel arrays in this order — the renderer splats up to 4 layers using a
-//! per-chunk RGBA alpha map (R/G/B = layers 1/2/3 opacity).
+//! Each MCNK is the reference's 145-vertex centre fan: 81 outer corner verts and 64 inner verts at
+//! the cell centres, each inner one with its own authored MCVT height, and four triangles per cell
+//! fanning from the centre. The arrays keep MCVT's stride-17 order: outer `(r,c)` at `r·17+c`,
+//! inner at `r·17+9+c`. A hole (`MCNK+0x3C`) omits a 2×2-cell block's triangles; its verts stay.
 
 use std::io::Cursor;
 
@@ -30,95 +20,60 @@ pub const SHADOW_MAP_SIZE: u32 = 64;
 
 /// Yards per ADT tile (1/64 of a map edge).
 pub const TILE_SIZE: f32 = 533.333_3;
-/// Yards per MCNK chunk (16×16 chunks per tile) — also the grid the impassable-chunk wall runs on
-/// (decision 1266), which is why it is public.
+/// Yards per MCNK chunk (16×16 per tile), also the grid the impassable-chunk wall runs on.
 pub const CHUNK_SIZE: f32 = TILE_SIZE / 16.0;
-/// Yards between adjacent outer-grid vertices (9×9 grid spans one chunk).
-/// `pub(crate)` so the liquid mesher shares the exact same lattice spacing.
+/// Yards between adjacent outer-grid vertices; the liquid mesher shares the lattice.
 pub(crate) const UNIT_SIZE: f32 = CHUNK_SIZE / 8.0;
 
-/// World (x, y) of Stormwind, from `TaxiNodes.dbc` — a handy anchor for "Elwynn".
+/// World (x, y) of Stormwind, from `TaxiNodes.dbc`.
 pub const STORMWIND_XY: (f32, f32) = (-8840.56, 489.7);
 
-/// One MCNK chunk as an indexed triangle mesh in **raw WoW coords**, plus texturing data.
-///
-/// Vertex arrays (`positions`, `normals`, `uvs`) hold **145 entries** in MCVT's stride-17 order:
-/// outer `(r,c)` at `r·17+c` (r,c ∈ 0..=8), inner `(r,c)` at `r·17+9+c` (r,c ∈ 0..=7). The
-/// index buffer is the 4-triangle center-fan per cell (`(CTR,TL,BL),(CTR,BL,BR),(CTR,BR,TR),
-/// (CTR,TR,TL)`), 256 tris / 768 indices for a chunk with no holes.
+/// Ground-texture repeats per chunk, one per cell: the reference's fixed 8, not a setting.
+pub const TERRAIN_LAYER_TILES: f32 = 8.0;
+
+/// One MCNK as an indexed triangle mesh in raw WoW coords, plus its texturing data.
 #[derive(Debug, Clone)]
 pub struct ChunkMesh {
-    /// Vertex positions `[x, y, z]` in WoW yards — 145 entries (81 outer + 64 inner). See the
-    /// type-level doc for the stride-17 layout.
+    /// Vertex positions in WoW yards, 145 in stride-17 order.
     pub positions: Vec<[f32; 3]>,
-    /// Per-vertex normals (unit, WoW coords) decoded from MCNR, one per [`Self::positions`] entry.
-    /// Authored continuously across chunk borders, so using these instead of recomputing per-chunk
-    /// removes the lighting seams at MCNK boundaries. Empty if the chunk had no MCNR data.
+    /// Unit normals from MCNR, authored continuous across chunk borders; empty without MCNR.
     pub normals: Vec<[f32; 3]>,
-    /// Per-vertex texture coordinates (0..1 across the chunk; outer at `(c/8, r/8)`, inner at
-    /// `((c+½)/8, (r+½)/8)`). Renderers scale `× tex_tiles` (=8 per the binary) for layer
-    /// sampling and use the raw 0..1 for alpha/shadow.
+    /// Texture coords, 0..1 across the chunk; the layers scale them by [`TERRAIN_LAYER_TILES`].
     pub uvs: Vec<[f32; 2]>,
-    /// Triangle-list indices into `positions` (4-tri center-fan/cell, holed blocks omitted).
+    /// Triangle-list indices: four fan triangles per cell, holed blocks omitted.
     pub indices: Vec<u32>,
-    /// Low-res hole bitmap (`u16 @ MCNK+0x3C`). Bit `n = (cellY>>1)·4 + (cellX>>1)` set ⇒ that
-    /// 2×2 block of the 8×8 cells is missing (caves/doorways). The mesher already omits the
-    /// matching index ranges; downstream consumers (e.g. clutter) re-test it to skip placing
-    /// surface decoration over a hole.
+    /// Low-res hole bitmap (`MCNK+0x3C`): bit `(cellY>>1)·4 + (cellX>>1)` drops that 2×2 block.
     pub holes: u16,
-    /// MTEX filename of the chunk's base (layer 0) texture, if the chunk has layers.
     pub base_texture: Option<String>,
-    /// MTEX filenames of all texture layers (1–4), layer 0 first. The renderer blends layers
-    /// 1..n over layer 0 using [`Self::alpha_map`].
+    /// MTEX filenames of the layers (up to 4), layer 0 first.
     pub layer_textures: Vec<String>,
-    /// Per-layer `effectId` (MCLY), aligned with [`Self::layer_textures`]: a `GroundEffectTexture.dbc`
-    /// reference selecting the ground-clutter doodads for that layer (`0xFFFFFFFF` = none).
+    /// Per-layer MCLY `effectId`, a `GroundEffectTexture.dbc` id (`0xFFFFFFFF` for none).
     pub layer_effect_ids: Vec<u32>,
-    /// Packed RGBA alpha map (`ALPHA_MAP_SIZE`²), R/G/B = opacity of layers 1/2/3 across the
-    /// chunk (0..1 UV). `None` when the chunk has ≤1 layer (nothing to blend).
+    /// RGBA alpha map (`ALPHA_MAP_SIZE`²), R/G/B for layers 1/2/3; `None` with a single layer.
     pub alpha_map: Option<Vec<u8>>,
-    /// Pre-baked terrain shadow map from MCSH: one byte per texel over a `SHADOW_MAP_SIZE`² grid
-    /// (`255` = in shadow, `0` = lit), row-major over the chunk's 0..1 UV. This is WoW's **static**
-    /// terrain shadowing (baked at map-compile time); `None` when the chunk has no MCSH.
+    /// The baked MCSH shadow, a byte per texel over `SHADOW_MAP_SIZE`² (255 shadowed, 0 lit).
     pub shadow: Option<Vec<u8>>,
-    /// `predominantTexture` (MCNK 0x40, `uint2[8][8]`): for each 8×8 cell, the texture **layer
-    /// index** (0..3) whose MCLY `effectId` selects that cell's ground-clutter doodads. Row-major,
-    /// `k = row*8 + col` — same frame as the vertex grid (row steps south, col east). This is the
-    /// client's *authoritative* per-cell doodad-layer map; verified to match the alpha layout
-    /// cell-for-cell (`examples/clutter_probe`).
+    /// `predominantTexture` (MCNK `0x40`, 2 bits per cell): the layer whose `effectId` picks each
+    /// cell's clutter, `k = row*8 + col`.
     pub pred_tex: [u8; 64],
-    /// `noEffectDoodad` (MCNK 0x50, `uint1[8][8]`): `true` ⇒ the client draws **no** clutter on that
-    /// cell (e.g. paved roads/clearings). Same `k = row*8 + col` indexing as [`Self::pred_tex`].
-    ///
-    /// ⚠️ wow-adt 0.6.4 mislabels both grids for vanilla: it splits the 16-byte predominantTexture
-    /// into `pred_tex[8]` + `no_effect_doodad[8]` and calls the *real* noEffectDoodad `unknown_8bytes`.
-    /// We reconstruct the correct grids from those preserved bytes (see `adt_to_tile_mesh`).
+    /// `noEffectDoodad` (MCNK `0x50`, 1 bit per cell): no clutter on that cell. The ADT header's
+    /// names for these two grids mislead; `adt_to_tile_mesh` reassembles them.
     pub no_effect_doodad: [bool; 64],
-    /// This chunk's `(IndexX, IndexY)` within the 16×16 tile grid (MCNK header). Needed to seed the
-    /// ground-clutter PRNG by global chunk position (`scatter_ground_doodads`), matching the client.
+    /// The chunk's `(IndexX, IndexY)` in its tile, which seeds the reference's clutter PRNG.
     pub index_x: u32,
     pub index_y: u32,
-    /// `AreaTable.dbc` id of this chunk (MCNK +0x34) — the zone/subzone under the player's feet;
-    /// drives zone music/ambience/reverb selection (decision 0070).
+    /// The chunk's `AreaTable.dbc` id (MCNK `+0x34`), the zone or subzone underfoot.
     pub area_id: u32,
-    /// MCNK header flag bit 1 ([`benilla_adt::MCNK_IMPASSABLE`]): this chunk is authored
-    /// **impassable** — the ADT-level invisible wall the reference stops a mover at (report B129,
-    /// decision 1266). A header bit, so it covers the whole 33.333 yd chunk: the wall runs the
-    /// chunk grid, not the terrain relief.
+    /// MCNK flag bit 1 ([`benilla_adt::MCNK_IMPASSABLE`]): an invisible wall over the whole chunk
+    /// at every height, where the reference stops a mover.
     pub impassable: bool,
-    /// The chunk's MCLQ liquid surfaces — flat meshes built alongside the terrain (see
-    /// [`crate::liquid`]). Empty on a dry chunk; **more than one** where the MCNK carries more than
-    /// one liquid block, as the 28 shipped river-mouth chunks do (a stream over the sea).
+    /// The chunk's MCLQ liquid surfaces, one per block; a river mouth has a stream and a sea.
     pub liquids: Vec<crate::liquid::LiquidMesh>,
 }
 
 impl ChunkMesh {
-    /// Sample the baked MCSH terrain shadow at a **raw WoW-space** position (X north, Y west): the same
-    /// per-texel lookup the terrain shader and clutter use, so a doodad/unit standing here inherits the
-    /// ground's static shade. Returns `Some(true)` = shadowed, `Some(false)` = lit, and `None` when the
-    /// position is outside this chunk's footprint (caller tries the next chunk). A chunk with no MCSH map
-    /// is fully lit. Coord math mirrors the vertex grid: NW corner is `positions[0]`, +X is north (south
-    /// distance = `nw_x − x`), +Y is west (east distance = `nw_y − y`), both `0..1` across the chunk.
+    /// Whether a raw WoW position is in this chunk's MCSH shadow, by the texel the terrain shader
+    /// samples; `None` off the chunk's footprint, and a chunk with no MCSH is lit.
     pub fn mcsh_shadowed_at(&self, wow: [f32; 3]) -> Option<bool> {
         let nw = *self.positions.first()?;
         let south = (nw[0] - wow[0]) / TILE_SIZE * 16.0;
@@ -127,7 +82,7 @@ impl ChunkMesh {
             return None;
         }
         let Some(shadow) = self.shadow.as_ref() else {
-            return Some(false); // inside this chunk but no MCSH → lit
+            return Some(false); // inside this chunk, no MCSH: lit
         };
         let n = SHADOW_MAP_SIZE as usize;
         let row = ((south * n as f32) as usize).min(n - 1);
@@ -135,11 +90,8 @@ impl ChunkMesh {
         Some(shadow.get(row * n + col).copied().unwrap_or(0) >= 128)
     }
 
-    /// The `GroundEffectTexture` id under a **raw WoW-space** position, `None` when the position
-    /// is outside this chunk (or the cell's layer carries no effect). Uses the chunk's own
-    /// `predominantTexture` per-cell layer map — the client's authoritative per-cell selector
-    /// (the same grid the ground clutter scatters by) — then that layer's MCLY `effectId`.
-    /// Feeds the footstep terrain-type chain (decision 0070 slice 3).
+    /// The `GroundEffectTexture` id under a raw WoW position: the `effectId` of the cell's
+    /// `predominantTexture` layer, the grid the clutter scatters by.
     pub fn ground_effect_at(&self, wow: [f32; 3]) -> Option<u32> {
         let nw = *self.positions.first()?;
         let south = (nw[0] - wow[0]) / TILE_SIZE * 16.0;
@@ -154,9 +106,7 @@ impl ChunkMesh {
         (effect != u32::MAX).then_some(effect)
     }
 
-    /// The chunk's `AreaTable` id if the **raw WoW-space** position lies inside its footprint,
-    /// else `None` (caller tries the next chunk). Same containment math as
-    /// [`Self::mcsh_shadowed_at`].
+    /// The chunk's `AreaTable` id if the raw WoW position is on its footprint.
     pub fn area_at(&self, wow: [f32; 3]) -> Option<u32> {
         let nw = *self.positions.first()?;
         let south = (nw[0] - wow[0]) / TILE_SIZE * 16.0;
@@ -168,10 +118,7 @@ impl ChunkMesh {
         }
     }
 
-    /// Is the **raw WoW-space** position inside this chunk's footprint, and is the chunk flagged
-    /// [`benilla_adt::MCNK_IMPASSABLE`]? `None` = outside (caller tries the next chunk). Same
-    /// containment math as [`Self::area_at`] — and the same reason it is a *footprint* test and not
-    /// a height test: the flag has no z extent, so the answer is the same at every altitude.
+    /// Whether the chunk is impassable, `None` off its footprint; the flag has no height.
     pub fn impassable_at(&self, wow: [f32; 3]) -> Option<bool> {
         let nw = *self.positions.first()?;
         let south = (nw[0] - wow[0]) / TILE_SIZE * 16.0;
@@ -179,14 +126,9 @@ impl ChunkMesh {
         ((0.0..=1.0).contains(&south) && (0.0..=1.0).contains(&east)).then_some(self.impassable)
     }
 
-    /// The terrain surface height (WoW `z`) under a **raw WoW-space** column, by exact interpolation
-    /// of the covering center-fan triangle. `None` when the column lies outside this chunk's footprint
-    /// (caller tries the next chunk) **or falls in an MCNK hole**.
-    ///
-    /// The hole case is load-bearing, not an edge case: a hole is how a mine/cave entrance is cut out
-    /// of the ground, and it carries no triangle in [`Self::indices`] — so the query misses exactly
-    /// where the client's terrain probe misses, handing that column to the WMO interior below it. Any
-    /// implementation that interpolated a height across a hole would seal the entrance shut.
+    /// The terrain height under a raw WoW column, interpolated on the covering fan triangle. `None`
+    /// off the footprint or in a hole: a cave mouth's column goes to the WMO below it, where the
+    /// reference's terrain probe misses too.
     pub fn height_at(&self, wow: [f32; 3]) -> Option<f32> {
         let nw = *self.positions.first()?;
         let south = (nw[0] - wow[0]) / TILE_SIZE * 16.0;
@@ -194,10 +136,8 @@ impl ChunkMesh {
         if !(0.0..=1.0).contains(&south) || !(0.0..=1.0).contains(&east) {
             return None;
         }
-        // The covering cell, then only its four fan triangles — the same corners, centre,
-        // order and hole rule the index buffer was built from (`adt_to_tile_mesh`), so the
-        // answer is the walk's answer without the walk: a column used to test up to 256
-        // triangles, and the sun-flare march asks ~96 columns a frame (decision 1979).
+        // Only the covering cell's four fan triangles, with the corners, order and hole rule
+        // `adt_to_tile_mesh` indexes, so the answer is the full walk's.
         if self.positions.len() == 145 {
             let row = ((south * 8.0) as u32).min(7);
             let col = ((east * 8.0) as u32).min(7);
@@ -227,13 +167,8 @@ impl ChunkMesh {
     }
 }
 
-/// The `z` of triangle `tri` (WoW coords, Z up) at column `(x, y)`, or `None` when `(x, y)` falls
-/// outside the triangle's XY projection (or the triangle is vertical / degenerate in XY).
-///
-/// Barycentric interpolation — for a **vertical** ray this IS the exact ray-vs-triangle test: a
-/// vertical face projects to a degenerate XY sliver, and a vertical ray is parallel to it anyway.
-/// Shared by the WMO current-group down-ray (its Leg A walking-collision faces) and the ADT terrain
-/// probe that races it, so the two legs of the client's arbitration can never drift apart.
+/// The `z` of `tri` at column `(x, y)`, `None` outside its XY projection or for a vertical face.
+/// Shared by the WMO down-ray and the terrain probe, the two legs of the reference's arbitration.
 pub fn triangle_z_at(tri: &[[f32; 3]; 3], x: f32, y: f32) -> Option<f32> {
     let (a, b, c) = (tri[0], tri[1], tri[2]);
     let det = (b[1] - c[1]) * (a[0] - c[0]) + (c[0] - b[0]) * (a[1] - c[1]);
@@ -249,31 +184,24 @@ pub fn triangle_z_at(tri: &[[f32; 3]; 3], x: f32, y: f32) -> Option<f32> {
     Some(l1 * a[2] + l2 * b[2] + l3 * c[2])
 }
 
-/// The `AreaTable` id under a raw WoW-space position, given **one tile's** chunks; `None` when the
-/// position lies outside every chunk (a different tile — same containment contract as
-/// [`mcsh_shadowed_at`]). The zone/subzone driving music/ambience/reverb (decision 0070).
+/// The `AreaTable` id under a raw WoW position, from one tile's chunks; `None` off the tile.
 pub fn area_id_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<u32> {
     chunks.iter().find_map(|c| c.area_at(wow))
 }
 
-/// Is a raw WoW-space position over an **impassable** MCNK, given **one tile's** chunks? `None`
-/// when the position lies outside every chunk (a different tile — the same containment contract as
-/// [`area_id_at`]), which a caller must read as "unknown", never as "passable": the chunk on the
-/// far side of a tile seam is exactly where B129's wall is authored.
+/// Whether a raw WoW position is over an impassable MCNK of one tile. `None` off the tile means
+/// unknown, never passable: walls are authored right across tile seams.
 pub fn impassable_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<bool> {
     chunks.iter().find_map(|c| c.impassable_at(wow))
 }
 
-/// The `GroundEffectTexture` id under a raw WoW-space position, given **one tile's** chunks;
-/// `None` when outside every chunk or when the containing cell's layer has no effect (footstep
-/// consumers fall back to the Dirt default either way).
+/// The `GroundEffectTexture` id under a raw WoW position, from one tile's chunks.
 pub fn ground_effect_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<u32> {
     chunks.iter().find_map(|c| c.ground_effect_at(wow))
 }
 
-/// The terrain surface height (WoW `z`) under a raw WoW-space column, given **one tile's** chunks;
-/// `None` when the column lies outside every chunk (a different tile) or falls in an MCNK hole.
-/// The terrain leg of the client's down-ray arbitration (see [`ChunkMesh::height_at`]).
+/// The terrain height under a raw WoW column from one tile's chunks, `None` off the tile or in a
+/// hole: the terrain leg of the reference's down-ray arbitration.
 pub fn terrain_height_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<f32> {
     match chunk_at(chunks, wow) {
         Some(c) => c.height_at(wow),
@@ -281,13 +209,9 @@ pub fn terrain_height_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<f32> {
     }
 }
 
-/// The one MCNK of a full 16×16 tile that covers `wow`'s column — arithmetic on the tile's
-/// north-west corner, not a walk. A tile's chunks are in MCIN order (row-major: row = the
-/// south step along WoW x, column = the east step along y), and every chunk's first vertex is
-/// its own north-west corner, so chunk 0's is the tile's. `None` when the slice is not a full
-/// tile or its first chunk carries no geometry — the callers fall back to the linear walk,
-/// which is what every column lookup used to be: 256 bounds tests per call, and the flare
-/// oracle alone asks ~96 times a frame (decision 1979's floor).
+/// The MCNK of a full tile that covers `wow`'s column, by arithmetic: chunks are in MCIN order
+/// (rows step south along x, columns east along y), and chunk 0's first vertex is the tile's
+/// north-west corner. `None` sends the caller to the linear walk.
 fn chunk_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<&ChunkMesh> {
     if chunks.len() != 256 {
         return None;
@@ -301,15 +225,10 @@ fn chunk_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<&ChunkMesh> {
     chunks.get(row as usize * 16 + col as usize)
 }
 
-/// Is a raw WoW-space position in MCSH terrain shadow, given **one tile's** chunks? `Some(true)` when the
-/// containing chunk's MCSH bit is set, `Some(false)` when the containing chunk is lit (or has no shadow
-/// map), and **`None` when the position lies outside every chunk in `chunks`** — i.e. it belongs to a
-/// different tile. Returning `None` rather than defaulting to lit is load-bearing: an MDDF doodad that
-/// straddles a tile edge is listed in *every* tile it touches, but only the tile that CONTAINS its origin
-/// can answer; the caller must take the `Some` from that tile and never let a straddle-tile miss
-/// masquerade as "lit". (The real client sidesteps this with a global world→chunk MCSH lookup, `0x69b350`
-/// — `models/scratch/m2-interior-doodad-base-light.md §6`.) Feeds the model lobe's `sun_scale` (the
-/// faithful per-instance terrain-shade, 2.5 sunlit / 0.5 shaded — wow-re byte-verified).
+/// Whether a raw WoW position is in MCSH shadow, from one tile's chunks; `None` off the tile,
+/// never "lit": a doodad straddling tiles is listed in each, and only its origin's tile answers,
+/// as the reference's global world-to-chunk lookup (`0x69b350`) does. It picks a map doodad's
+/// static shade, 1.0 lit or 0.5 shadowed; the 2.5 lit value belongs to an entity's light node.
 pub fn mcsh_shadowed_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<bool> {
     match chunk_at(chunks, wow) {
         Some(c) => c.mcsh_shadowed_at(wow),
@@ -317,42 +236,40 @@ pub fn mcsh_shadowed_at(chunks: &[ChunkMesh], wow: [f32; 3]) -> Option<bool> {
     }
 }
 
-/// A placed M2 doodad (tree/bush/prop): which model, and where, in **raw WoW world coords**.
+/// A placed M2 doodad (tree, bush, prop): which model, and where, in raw WoW world coords.
 #[derive(Debug, Clone)]
 pub struct Doodad {
     /// MMDX model path (`.mdx`); `load_m2_mesh` normalizes it to `.m2`.
     pub model: String,
     /// Position in WoW world coords (X north, Y west, Z up), converted from MDDF.
     pub position: [f32; 3],
-    /// Euler rotation in **degrees** (X, Y, Z); Y is the heading about the up axis.
+    /// Euler rotation in degrees (X, Y, Z); Y is the heading about the up axis.
     pub rotation: [f32; 3],
     /// Uniform scale (MDDF stores it ×1024).
     pub scale: f32,
-    /// MDDF uniqueId — stable per placement, identical across the ADT tiles a doodad straddles, so
-    /// the streamer can spawn it once and refcount it (the client's own dedup, `FUN_00694bc0`).
+    /// MDDF uniqueId, shared by every tile a doodad straddles; the reference dedups by it
+    /// (`0x694bc0`).
     pub unique_id: u32,
 }
 
-/// A placed WMO (building) — which model, and where, in **raw WoW world coords**.
+/// A placed WMO (building): which model, and where, in raw WoW world coords.
 #[derive(Debug, Clone)]
 pub struct WmoInstance {
     /// MWMO root path (`.wmo`); `load_wmo` loads its group files too.
     pub model: String,
     /// Position in WoW world coords (X north, Y west, Z up), converted from MODF.
     pub position: [f32; 3],
-    /// Euler rotation in **degrees** (X, Y, Z); Y is the heading about the up axis.
+    /// Euler rotation in degrees (X, Y, Z); Y is the heading about the up axis.
     pub rotation: [f32; 3],
-    /// MODF uniqueId — stable per placement, identical across the ADT tiles a building straddles
-    /// (Stormwind spans 6 tiles), so the streamer dedups it instead of spawning 6× (`FUN_00694bc0`).
+    /// MODF uniqueId, the same in every tile a building straddles, deduped by it (`0x694bc0`).
     pub unique_id: u32,
-    /// MODF doodad-set index: which *additional* WMO doodad set to show beyond the always-on global
-    /// set 0 (selects interior-prop variants — e.g. an inn's furnished vs empty rooms).
+    /// MODF doodad-set index: the set shown beside the always-on set 0.
     pub doodad_set: u16,
-    /// MODF name-set index — the placement's `WMOAreaTable.NameSetID` naming/audio variant.
+    /// MODF name-set index, the placement's `WMOAreaTable.NameSetID`.
     pub name_set: u16,
 }
 
-/// One ADT tile's terrain: its per-MCNK chunk meshes + placed doodads + buildings.
+/// One ADT tile: its chunk meshes, placed doodads and buildings.
 #[derive(Debug, Clone)]
 pub struct TileMesh {
     pub chunks: Vec<ChunkMesh>,
@@ -361,21 +278,13 @@ pub struct TileMesh {
 }
 
 impl TileMesh {
-    /// Total vertices across all chunks.
     pub fn vertex_count(&self) -> usize {
         self.chunks.iter().map(|c| c.positions.len()).sum()
     }
 }
 
-/// Snap an X/Y world coordinate to the global terrain vertex lattice (`MAP_CENTER − n·UNIT_SIZE`).
-///
-/// Each MCNK stores its own corner position as `f32`, which carries ~1–2 mm of per-chunk rounding.
-/// So a vertex shared by two adjacent chunks (or tiles) — computed from each one's header + offset —
-/// doesn't come out bit-identical, leaving the edges fractionally misaligned: hairline cracks that
-/// show the sky through the terrain, and z-fighting where the coplanar edge triangles overlap (a
-/// shimmering seam visible at any zoom). Real vertices lie on the lattice to <0.0005 unit, so
-/// snapping (computed in `f64`) collapses each shared vertex to the *same* coordinate → watertight.
-/// `pub(crate)` so the liquid mesher snaps its grid to the same lattice as the terrain it sits in.
+/// Snap an X/Y world coordinate to the global vertex lattice (`MAP_CENTER − n·UNIT_SIZE`): each
+/// MCNK's `f32` corner is off by a millimetre or two, which cracks and z-fights shared edges.
 pub(crate) fn snap_to_lattice(coord: f32) -> f32 {
     let map_center = 32.0_f64 * 1600.0 / 3.0; // 64-tile map; TILE_SIZE = 1600/3 yd
     let unit = (1600.0_f64 / 3.0) / 128.0; // 128 vertex-units per tile edge
@@ -387,7 +296,7 @@ pub(crate) fn snap_to_lattice(coord: f32) -> f32 {
 pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
     let mut cursor = Cursor::new(adt_bytes);
     let parsed = parse_adt(&mut cursor).map_err(|e| anyhow::anyhow!("parsing ADT: {e}"))?;
-    // benilla-adt only produces vanilla monolithic root ADTs (no Cata+ split files).
+    // A vanilla ADT is always one monolithic root.
     let ParsedAdt::Root(root) = parsed;
 
     let mut chunks = Vec::new();
@@ -398,34 +307,24 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
         if mcvt.heights.len() < 145 {
             continue;
         }
-        // wow-adt 0.6.4's world_position() mis-orders vanilla axes; the raw `position` field
-        // is already WoW [X(north), Y(west), Z(up)].
+        // The header's `position` is already WoW `[X north, Y west, Z up]`.
         let [wx, wy, wz] = mcnk.header.position;
 
-        // MCNR normals parallel MCVT 1:1 (same 145-entry stride-17 grid). The disk byte order is
-        // already WoW `[X, Y, Z]` with no swap (qa3-adt: geometric dot 0.999 vs ~0.4 for the
-        // `[X, Z, Y]` interpretation). The `wow-adt` crate's `to_normalized()` is buggy and
-        // returns `[b0, b2, b1]`; our `[x, z, y] = …; [x, y, z]` swap below cancels the crate's
-        // swap, recovering the true raw `[X, Y, Z]` order. Output verified vs the mesh's own
-        // geometric normals (avg dot 0.99). Skipped if the chunk has no MCNR.
+        // MCNR is one normal per MCVT vertex, disk bytes already WoW `[X, Y, Z]`; `to_normalized`
+        // returns `[b0, b2, b1]`, which the destructure below undoes.
         let mcnr = mcnk.normals.as_ref().filter(|n| n.normals.len() >= 145);
 
-        // 145 verts in MCVT's stride-17 interleave: row r (0..8) emits 9 outer at indices
-        // `r·17+(0..9)` then 8 inner at `r·17+9+(0..8)`; the final outer row 8 has no inner
-        // companion. Outer (r,c) sits at chunk-local `(r·UNIT, c·UNIT, h)`, inner (r,c) at
-        // `((r+½)·UNIT, (c+½)·UNIT, h_inner)` — the **+½-cell offset is horizontal only**, and
-        // each inner vertex carries its OWN authored MCVT center height (the binary's B1).
+        // Each row's 9 outer verts, then its 8 inner ones half a cell in, horizontally only; the
+        // last row has no inner verts.
         let mut positions = Vec::with_capacity(145);
         let mut normals = Vec::with_capacity(if mcnr.is_some() { 145 } else { 0 });
         let mut uvs = Vec::with_capacity(145);
         for row in 0..9u32 {
-            // Outer row (9 verts at the corner grid).
             for col in 0..9u32 {
                 let idx = (row * 17 + col) as usize;
                 let h = mcvt.heights[idx];
                 positions.push([
-                    // Snap X/Y to the global lattice so shared chunk/tile edge vertices coincide
-                    // exactly (no hairline cracks / z-fight seams); Z stays the MCVT height.
+                    // X/Y snap so shared edge verts coincide; Z stays the MCVT height.
                     snap_to_lattice(wx - row as f32 * UNIT_SIZE), // WoW X (north): rows step south
                     snap_to_lattice(wy - col as f32 * UNIT_SIZE), // WoW Y (west): columns step east
                     wz + h,                                       // WoW Z (up): height over base
@@ -434,17 +333,13 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
                     let [x, z, y] = mcnr.normals[idx].to_normalized();
                     normals.push([x, y, z]);
                 }
-                // 0..1 per chunk; outer at integer/8.
                 uvs.push([col as f32 / 8.0, row as f32 / 8.0]);
             }
-            // Inner row (8 verts at the cell centers) — skipped after the final outer row.
             if row < 8 {
                 for col in 0..8u32 {
                     let idx = (row * 17 + 9 + col) as usize;
                     let h = mcvt.heights[idx];
-                    // No lattice-snap on inner: each inner vertex is per-chunk-private (the
-                    // adjacent chunk has no twin at the same (x, y)), so the seam concern doesn't
-                    // apply and we'd just move it off its authored position by the rounding error.
+                    // Not snapped: no other chunk shares an inner vert.
                     positions.push([
                         wx - (row as f32 * UNIT_SIZE + UNIT_SIZE / 2.0),
                         wy - (col as f32 * UNIT_SIZE + UNIT_SIZE / 2.0),
@@ -454,20 +349,13 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
                         let [x, z, y] = mcnr.normals[idx].to_normalized();
                         normals.push([x, y, z]);
                     }
-                    // Inner at +½ in both axes (qb4): `((c+½)/8, (r+½)/8)`.
                     uvs.push([(col as f32 + 0.5) / 8.0, (row as f32 + 0.5) / 8.0]);
                 }
             }
         }
 
-        // 4-triangle center-fan per cell, hole-aware (B1 + B2). For cell (r, c) ∈ 0..8²:
-        //   TL = outer(r,c) @ r·17+c           TR = outer(r,c+1) @ r·17+c+1
-        //   BL = outer(r+1,c) @ (r+1)·17+c     BR = outer(r+1,c+1) @ (r+1)·17+c+1
-        //   CTR = inner(r,c) @ r·17+9+c
-        // Fan winding (CCW from above, +Z normal in WoW = front-face up in Bevy under the det-+1
-        // transform; matches the existing 2-tri winding the engine already accepts).
-        // Holes: u16 @ MCNK+0x3C, bit `n=(r>>1)·4+(c>>1)` set ⇒ omit the 2×2 block of fans (verts
-        // remain — unreferenced is fine). 1.12 has no high-res holes.
+        // Four fan triangles per cell, CCW from above (front face up in Bevy under the det +1
+        // transform); a set hole bit drops its 2×2 block, and 1.12 has no high-res holes.
         let holes = mcnk.header.holes_low_res;
         let mut indices = Vec::with_capacity(8 * 8 * 12);
         for row in 0..8u32 {
@@ -489,8 +377,7 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
             }
         }
 
-        // All layers (layer 0 first): texture name (resolved through MTEX) + its ground-effect id,
-        // kept together so the two parallel vecs stay index-aligned even if a layer is dropped.
+        // Name and effect id together, so the two vecs stay aligned when a layer is dropped.
         let layers: Vec<(String, u32)> = mcnk
             .layers
             .as_ref()
@@ -510,9 +397,7 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
         let layer_effect_ids: Vec<u32> = layers.iter().map(|(_, e)| *e).collect();
         let base_texture = layer_textures.first().cloned();
 
-        // Pack layers 1..3 alpha into one RGBA map for the splat shader. Vanilla uses 4-bit
-        // (small) alpha maps and the renderer convention of duplicating the last row/col
-        // (`fix_alpha`); big-alpha (8-bit) was introduced post-1.12.
+        // Layers 1..3 into one RGBA map; 1.12 alpha is 4-bit, last row and column duplicated.
         let alpha_map = (layer_textures.len() > 1).then(|| {
             CombinedAlphaMap::new(
                 mcnk, /* has_big_alpha */ false, /* fix_alpha */ true,
@@ -521,8 +406,6 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
             .to_vec()
         });
 
-        // MCSH baked shadow → one byte per texel (255 = shadowed, 0 = lit), row-major over the
-        // chunk's 0..1 UV. `is_shadowed(x, y)` unpacks the 1-bit/texel, LSB-first map for us.
         let shadow = mcnk.shadow.as_ref().map(|sh| {
             let n = SHADOW_MAP_SIZE as usize;
             let mut out = vec![0u8; n * n];
@@ -536,11 +419,8 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
             out
         });
 
-        // Authored ground-effect placement grids (see `ChunkMesh::pred_tex`). wow-adt mislabels
-        // these for vanilla, but the raw bytes survive: predominantTexture (0x40-0x4F) =
-        // `pred_tex` ++ `no_effect_doodad`; the real noEffectDoodad (0x50-0x57) = `unknown_8bytes`.
-        // Decode per wowdev ADT/v18: predTex = 2 bits/cell, noEffect = 1 bit/cell, both LSB-first
-        // row-major (`k = row*8 + col`), confirmed against the alpha map by `examples/clutter_probe`.
+        // predominantTexture (`0x40..0x4F`) is the header's `pred_tex` then `no_effect_doodad`,
+        // and noEffectDoodad (`0x50..0x57`) its `unknown_8bytes`: 2 and 1 bits per cell, LSB first.
         let h = &mcnk.header;
         let mut pt16 = [0u8; 16];
         pt16[..8].copy_from_slice(&h.pred_tex);
@@ -553,8 +433,6 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
             no_effect_doodad[k] = (ned8[k / 8] >> (k % 8)) & 0x1 == 1;
         }
 
-        // MCLQ liquid surfaces (lake/river/ocean/lava), built on the same lattice as this chunk's
-        // terrain — one mesh per liquid block the MCNK carries. See `crate::liquid`.
         let liquids: Vec<_> = mcnk
             .liquids
             .iter()
@@ -586,9 +464,7 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
         anyhow::bail!("ADT produced no terrain chunks (no MCVT height data?)");
     }
 
-    // Doodad placements. MDDF positions are in a corner-origin space; convert to WoW world coords
-    // (verified against the tile's MCNK position range): X = 32·TILE − mddf.z, Y = 32·TILE −
-    // mddf.x, Z = mddf.y. Scale is stored ×1024. `name_id` indexes the MMDX list directly.
+    // MDDF positions are corner-origin: X = 32·TILE − mddf.z, Y = 32·TILE − mddf.x, Z = mddf.y.
     const MAP_CENTER: f32 = 32.0 * TILE_SIZE;
     let doodads = root
         .doodad_placements
@@ -609,7 +485,7 @@ pub fn adt_to_tile_mesh(adt_bytes: &[u8]) -> Result<TileMesh> {
         })
         .collect();
 
-    // WMO (building) placements — same MODF→world transform as doodads; scale is unused in vanilla.
+    // MODF takes the same transform; its scale is unused in 1.12.
     let wmos = root
         .wmo_placements
         .iter()
@@ -653,8 +529,7 @@ fn tile_exists(wdt: &WdtFile, x: u32, y: u32) -> bool {
         .is_some_and(|t| t.has_adt)
 }
 
-/// Find an existing ADT tile near a world (x, y) on `map`, spiraling out if the exact tile
-/// is missing. Returns `(tile_x, tile_y)` matching the `Map_<x>_<y>.adt` naming.
+/// The existing ADT tile at a world (x, y) on `map`, else the first one spiralling out 4 tiles.
 pub fn find_tile_near(
     chain: &mut Chain,
     map: &str,
@@ -682,8 +557,7 @@ pub fn find_tile_near(
     anyhow::bail!("no existing ADT tile near world ({world_x}, {world_y}) on map {map}")
 }
 
-/// A map's tile index (its WDT), parsed once and kept so a renderer can stream tiles in and out as
-/// the player moves — without re-reading the WDT every frame.
+/// A map's tile index (its WDT), parsed once for streaming.
 pub struct MapTiles {
     map: String,
     wdt: WdtFile,
@@ -709,10 +583,7 @@ impl MapTiles {
         benilla_wdt::world_to_tile(world_x, world_y)
     }
 
-    /// Coords of every **existing** ADT tile within `radius` tiles of a world `(x, y)`, **sorted
-    /// nearest-first** (by squared tile-grid distance to the centre tile). The streamer loads the
-    /// first not-yet-loaded entry, so nearest-first ⇒ the tile you're about to see in loads before the
-    /// far ones — no "drove past the boundary into an unloaded tile" pop-in.
+    /// Every existing ADT tile within `radius` tiles of a world `(x, y)`, nearest first.
     pub fn existing_in_radius(&self, world_x: f32, world_y: f32, radius: u32) -> Vec<(u32, u32)> {
         let (cx, cy) = benilla_wdt::world_to_tile(world_x, world_y);
         let r = radius as i32;
@@ -743,9 +614,6 @@ pub fn load_tile_mesh(chain: &mut Chain, map: &str, tile_x: u32, tile_y: u32) ->
 }
 
 /// Load every existing ADT tile within `radius` tiles of the world (x, y) on `map`.
-///
-/// Returns `((tile_x, tile_y), tile)` for each tile that exists and parses. Meshes use
-/// absolute world coords, so neighboring tiles abut seamlessly.
 pub fn load_tiles_around(
     chain: &mut Chain,
     map: &str,
@@ -768,7 +636,7 @@ pub fn load_tiles_around(
             if !tile_exists(&wdt, tx, ty) {
                 continue;
             }
-            // Skip (rather than fail the whole load on) the occasional unparseable tile.
+            // An unparseable tile is skipped, not fatal.
             if let Ok(mesh) = load_tile_mesh(chain, map, tx, ty) {
                 out.push(((tx, ty), mesh));
             }
@@ -785,8 +653,7 @@ pub fn load_tiles_around(
 mod tests {
     use super::*;
 
-    /// A one-chunk mesh with `positions`/`indices` and every other field inert — enough to exercise
-    /// the footprint + hole logic of [`ChunkMesh::height_at`].
+    /// A chunk with only `positions` and `indices` set.
     fn chunk(positions: Vec<[f32; 3]>, indices: Vec<u32>) -> ChunkMesh {
         ChunkMesh {
             positions,
@@ -811,9 +678,7 @@ mod tests {
 
     #[test]
     fn height_at_interpolates_inside_and_misses_holes_and_off_footprint() {
-        // NW corner at positions[0]; +X is south-distance, +Y is east-distance across the chunk. Two
-        // quads (four tris) tented to z=10 at the shared middle edge, with the SOUTH half of the chunk
-        // left UN-indexed — an MCNK hole (a cave mouth), verts present but no triangle references them.
+        // The north half is one quad rising to z=10 at the middle; the south half is a hole.
         let nw = [0.0, 0.0, 0.0];
         let mid_x = nw[0] - CHUNK_SIZE * 0.5; // half a chunk south
         let far_x = nw[0] - CHUNK_SIZE; // the chunk's south edge
@@ -826,7 +691,6 @@ mod tests {
             [far_x, nw[1], 0.0],  // 4: SW
             [far_x, far_y, 0.0],  // 5: SE
         ];
-        // North half only (verts 0,1,2,3) — the south half (4,5) is the hole.
         let indices = vec![0, 1, 2, 1, 3, 2];
         let c = chunk(positions, indices);
 
@@ -836,7 +700,7 @@ mod tests {
             .height_at([quarter_x, nw[1] - CHUNK_SIZE * 0.5, 0.0])
             .unwrap();
         assert!((z - 5.0).abs() < 0.01, "ridge midpoint ≈ 5, got {z}");
-        // A column over the un-indexed south half — the hole — has no surface: the mine mouth.
+        // A column over the hole has no surface.
         assert_eq!(
             c.height_at([far_x + 1.0, nw[1] - CHUNK_SIZE * 0.5, 0.0]),
             None
@@ -845,17 +709,12 @@ mod tests {
         assert_eq!(c.height_at([quarter_x, far_y - 5.0, 0.0]), None);
     }
 
-    /// The real 5875 map set: which maps have terrain and which are a single global WMO
-    /// (decision 0688). 20 of the 43 shipped WDTs author **zero** ADT tiles — on those maps the
-    /// global WMO is the entire world, and a client that ignores it renders a void you fall
-    /// through. Skips without client data.
+    /// 20 of the 43 shipped WDTs author no ADT tiles: their global WMO is the whole map.
     #[test]
     fn real_wdts_split_into_adt_maps_and_wmo_only_maps() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
 
-        // A WMO-only map, an ADT map, and the one map whose placement is NOT identity — the three
-        // cases the streamer has to tell apart.
         let jail = read_wdt(&mut chain, "StormwindJail").expect("StormwindJail.wdt");
         let g = jail
             .global_wmo()
@@ -864,7 +723,6 @@ mod tests {
             g.model.to_ascii_lowercase(),
             "world\\wmo\\dungeon\\az_stormwindprisons\\stormwindjail.wmo"
         );
-        // Authored at the world origin, unrotated: the placement the whole dungeon hangs off.
         assert_eq!(g.position, [0.0, 0.0, 0.0]);
         assert_eq!(g.rotation, [0.0, 0.0, 0.0]);
         assert!(
@@ -872,8 +730,7 @@ mod tests {
             "a WMO-only map authors no ADT tiles at all"
         );
 
-        // Deadmines is the control: the reports that opened 0688 said it alone kept you standing,
-        // and this is why — it ships real terrain, so the missing global-WMO branch never bit.
+        // Deadmines, the control, ships real terrain and no global WMO.
         let deadmines = read_wdt(&mut chain, "DeadminesInstance").expect("DeadminesInstance.wdt");
         assert!(deadmines.global_wmo().is_none());
         let tiles = (0..64)
@@ -882,9 +739,7 @@ mod tests {
             .count();
         assert_eq!(tiles, 36, "Deadmines ships 36 ADT tiles");
 
-        // Dire Maul is the reason the rotation column is read rather than assumed: it is the only
-        // shipped map placed at a heading, and dropping it would spin the dungeon 180° about the
-        // origin — every room mirrored onto the wrong side of the map.
+        // Dire Maul is the only shipped map placed at a heading, 180° about the origin.
         let dm = read_wdt(&mut chain, "DireMaul").expect("DireMaul.wdt");
         assert_eq!(
             dm.global_wmo().expect("WMO-only").rotation,
@@ -892,21 +747,14 @@ mod tests {
         );
     }
 
-    /// B129's pin, from the shipped bytes: the reference stops you 1.46 yd east of
-    /// `.go xyz -6601.98 -531.87 335.60 0`, and this is the wall — the MCNK immediately east is
-    /// flagged [`benilla_adt::MCNK_IMPASSABLE`] while the one under the pin is not.
-    ///
-    /// The numbers are the point. A regression that dropped the flag, or read the neighbouring bit,
-    /// would leave the pin's own chunk reading the same and only the *other* side of the seam wrong
-    /// — so the test pins both sides, the seam they straddle, and the band's size. Skips without
-    /// client data.
+    /// The reference stops a mover 1.46 yd east of `.go xyz -6601.98 -531.87 335.60 0`: the MCNK
+    /// there is flagged [`benilla_adt::MCNK_IMPASSABLE`] and the pin's own is not.
     #[test]
     fn the_b129_pin_stands_one_chunk_west_of_an_impassable_band() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
 
-        // The pin, and a step east across the chunk boundary at y = -533.333 (one tile seam too:
-        // the flagged chunk is column 0 of Azeroth_33_44, which is why a single-tile view misses it).
+        // A step east crosses the chunk boundary at y = -533.333, a tile seam too.
         let pin = [-6601.98, -531.87, 335.60];
         let east = [-6601.98, -535.0, 335.60];
         assert_eq!(crate::world_to_tile(pin[0], pin[1]), (32, 44));
@@ -925,13 +773,11 @@ mod tests {
             Some(true),
             "the chunk 1.46 yd east is the wall"
         );
-        // The containment contract: a tile answers only for its own footprint. A caller that read
-        // `None` as "passable" would walk straight through every wall authored across a seam.
+        // A tile answers only for its own footprint.
         assert_eq!(impassable_at(&here.chunks, east), None);
         assert_eq!(impassable_at(&next.chunks, pin), None);
 
-        // Not one stray chunk but an authored ribbon: Searing Gorge's rim (area 51) crosses this
-        // tile, and the far side of the map's tiles carry none of it.
+        // Searing Gorge's rim (area 51) crosses this tile as a ribbon; the pin's tile has none.
         assert_eq!(
             next.chunks.iter().filter(|c| c.impassable).count(),
             48,
@@ -939,15 +785,11 @@ mod tests {
         );
         assert_eq!(here.chunks.iter().filter(|c| c.impassable).count(), 0);
     }
-    /// The cell lookup must answer exactly like the raw triangle walk it replaced, height and
-    /// MCSH alike — sampled off-border across four real tiles (Elwynn and Stormwind), so a
-    /// wrong row/column convention, an off-by-one at an edge or a mishandled hole fails here,
-    /// not under a foot.
+    /// Height and MCSH alike, sampled off-border across four Elwynn and Stormwind tiles.
     #[test]
     fn the_chunk_index_answers_exactly_like_the_walk() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
-        // The raw walk the cell lookup replaced: every triangle of every chunk, in index order.
         let walk = |chunks: &[ChunkMesh], wow: [f32; 3]| {
             chunks.iter().find_map(|c| {
                 c.indices.as_chunks::<3>().0.iter().find_map(|t| {
diff --git a/crates/benilla-formats/src/text_filter_lists.rs b/crates/benilla-formats/src/text_filter_lists.rs
index d1bc701c..3b5c4878 100644
--- a/crates/benilla-formats/src/text_filter_lists.rs
+++ b/crates/benilla-formats/src/text_filter_lists.rs
@@ -1,28 +1,11 @@
-//! `ChatProfanity.dbc` + `SpamMessages.dbc` — the two shipped pattern lists behind 1.12's
-//! `profanityFilter` and `spamFilter` (decision 2077; wow-re `system/ui/scratch/text-filter-law.md`).
-//!
-//! **They are regular expressions, not word lists.** The reference compiles every row with PCRE
-//! (`0x71fba0` → `pcre_compile 0x720250`, options `0x2801` = CASELESS | UTF8 | NO_UTF8_CHECK) at
-//! startup — one linear pass, `0x402b7f → 0x6c91a0`, no reload path — and a row that fails to
-//! compile is **skipped** rather than stored, so the live count is the number that compiled. On the
-//! shipped data none fails.
-//!
-//! This module only *reads* the rows. Translating a pattern into something a modern engine runs, and
-//! the mask/predicate laws over them, are the client's (`benilla_app::text_filter`).
-//!
-//! **The archive matters, and it is the easy thing to get wrong.** Both files must resolve through
-//! the ordinary priority walk, not out of `dbc.MPQ`: `ChatProfanity` is **2289** rows in `patch.MPQ`
-//! against 1512 in `dbc.MPQ`, and `dbc.MPQ` carries no `SpamMessages` at all. Neither filename holds
-//! a locale (`"DBFilesClient\ChatProfanity.dbc"` `0x858348`, `"DBFilesClient\SpamMessages.dbc"`
-//! `0x859a84`, both literal, neither with a `%s`), so a locale build overrides them one layer down,
-//! at the archive — which is exactly what [`crate::Chain`] already does.
-//!
-//! Layout: 2 × u32 — `{ID(0), Pattern(1)}`, and the pattern is a *plain* string column, not the
-//! eight-slot localized shape (the list is multi-language in one table: of ChatProfanity's 2289
-//! rows 850 are ASCII, the rest carry high bytes — Korean, Chinese, French).
-//!
-//! The two lists are **disjoint in practice**: the spam list is 28 gold-seller URL patterns, each
-//! letter separated by `\s*` to defeat spacing.
+//! `ChatProfanity.dbc` and `SpamMessages.dbc`, the lists behind 1.12's `profanityFilter` and
+//! `spamFilter`: an id and a plain-string pattern, one table for every language. The reference
+//! compiles each row once at startup as a PCRE (`0x402b7f` → `0x6c91a0`; `0x71fba0` →
+//! `pcre_compile` `0x720250`, CASELESS | UTF8 | NO_UTF8_CHECK) and skips one that fails, which no
+//! shipped row does; `benilla_app::text_filter` compiles and applies them. Both come through the
+//! patch chain: `dbc.MPQ` has 1512 `ChatProfanity` rows to `patch.MPQ`'s 2289 and no
+//! `SpamMessages`, and the names carry no locale (`0x858348`, `0x859a84`), so a locale build
+//! overrides them at the archive.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -33,8 +16,8 @@ use crate::dbc::{parse, str_at, u32_at};
 const CHAT_PROFANITY: &str = "DBFilesClient\\ChatProfanity.dbc";
 const SPAM_MESSAGES: &str = "DBFilesClient\\SpamMessages.dbc";
 
-/// One row: the DBC id (for diagnostics — a failed compile names it, as the reference's own
-/// `"…filter expression: \"%s\" (record ID %d)"` does) and its raw PCRE pattern.
+/// One row: its id, which a failed compile names as the reference's error does, and its raw
+/// PCRE pattern.
 #[derive(Clone, Debug)]
 pub struct FilterPattern {
     pub id: u32,
@@ -56,9 +39,8 @@ fn load(chain: &mut Chain, path: &str, name: &str) -> Result<Vec<FilterPattern>>
     let rs = parse(&bytes, schema(name), name)?;
     let mut out = Vec::with_capacity(rs.records().len());
     for r in rs.records() {
-        // **File order is the list order**, and the mask law depends on it: patterns apply in list
-        // order, not text order, so the row a sentence's *later* word matches can take the earlier
-        // mask characters. Never sort.
+        // File order is the list order, which masking depends on: patterns apply in list order,
+        // not text order. Never sort.
         let (Some(id), Some(pattern)) = (u32_at(r, 0), str_at(&rs, r, 1)) else {
             continue;
         };
@@ -70,15 +52,13 @@ fn load(chain: &mut Chain, path: &str, name: &str) -> Result<Vec<FilterPattern>>
     Ok(out)
 }
 
-/// `ChatProfanity.dbc` — the masker's list, in file order.
+/// `ChatProfanity.dbc`, the masker's list, in file order.
 pub fn load_chat_profanity(chain: &mut Chain) -> Result<Vec<FilterPattern>> {
     load(chain, CHAT_PROFANITY, "ChatProfanity")
 }
 
-/// `SpamMessages.dbc` — the spam predicate's shipped list, in file order.
-///
-/// The reference scans this list **then** a second, server-pushed one (SMSG `0x332`, handler
-/// `0x49e6e0`), which starts empty and stays empty unless the server sends it. vmangos never does.
+/// `SpamMessages.dbc`, the spam predicate's list, in file order. The reference then scans a
+/// second list the server can push (SMSG `0x332`, handler `0x49e6e0`); vmangos never sends one.
 pub fn load_spam_messages(chain: &mut Chain) -> Result<Vec<FilterPattern>> {
     load(chain, SPAM_MESSAGES, "SpamMessages")
 }
@@ -87,9 +67,7 @@ pub fn load_spam_messages(chain: &mut Chain) -> Result<Vec<FilterPattern>> {
 mod tests {
     use super::*;
 
-    /// The shipped lists, measured — the row counts wow-re's oracle run compiled the binary's own
-    /// PCRE over, and the proof that the priority walk picked the right archive (the `dbc.MPQ`
-    /// copies are 1512 rows and *absent* respectively). Skips without client data.
+    /// The row counts the reference's PCRE compiles, which only the patched archives give.
     #[test]
     fn the_lists_come_off_the_priority_walk_at_their_patched_sizes() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/tga.rs b/crates/benilla-formats/src/tga.rs
index a70bae75..5e649934 100644
--- a/crates/benilla-formats/src/tga.rs
+++ b/crates/benilla-formats/src/tga.rs
@@ -1,39 +1,17 @@
-//! TGA (Targa) decoder — the OTHER half of the reference's UI texture table.
+//! TGA decoding, the other half of the reference's UI texture lookup: `TextureCreate` tries
+//! `{".tga", ".blp"}` (`0x835248`), and while 1.12 ships its UI art as BLP, addons ship TGAs. The
+//! reference's `0x5a3a30` dispatches on `imageType`: 1 and 9 (colour-mapped, raw or RLE) to
+//! `0x5a39d0` through the palette at `0x5a3820`, 2 to `0x5a3c80`, 10 to `0x5a3d70`.
 //!
-//! `TextureCreate`'s extension table is `{".tga", ".blp"}` (`0x835248`; see
-//! `world_assets::sprite_candidates` in benilla-assets), so every UI sprite reference is two
-//! candidate files and one of them is a TGA. Inside the MPQs that arm is a near-no-op — 1.12 ships
-//! its UI art as BLP — but **addon folders are where TGAs actually live**: BLP tooling was rare in
-//! 2006 and the ecosystem shipped loose `.tga` art constantly, so the loose-file resolve
-//! (decision 1322) is what finally makes this decoder load-bearing.
+//! Deviation: grayscale types 3 and 11 decode where the reference refuses them, because no shipped
+//! or addon file is one and removing working code would buy nothing.
 //!
-//! **The reference's own dispatch is the spec, and ours used to be its mirror image.** `0x5a3a30`
-//! forks on `imageType` as `{1/9 → 0x5a39d0 (colour-mapped, raw or RLE, expanded through the
-//! palette at 0x5a3820); 2 → 0x5a3c80; 10 → 0x5a3d70; 3/11 → unsupported}` (wow-re
-//! `image/scratch/re-wave1.md`). This decoder refused 1/9 — on a doc comment asserting *"none have
-//! surfaced in the corpus"*, which was false — and accepted the two the client refuses.
-//!
-//! Three colour-mapped TGAs are in the 219-addon corpus, all 8-bit indices into a 256-entry
-//! 24-bit palette: `FonzAppraiser/img/icon_disable.tga` (type 1, drawn by
-//! `mods/gui/minimap.lua:45`), `FuBar_WeaponRebuffFu/icon.tga` (type 9, RLE — the plugin's whole
-//! icon, reached through FuBarPlugin's `Interface\AddOns\%s\icon`) and
-//! `FonzSummon/img/icon_disable.tga` (type 1, shipped but unreferenced). Each drew **nothing**,
-//! with a `warn!` on a terminal, and `SetTexture` still answered `1` because the resolvability
-//! probe tests existence rather than decode — so the failure was invisible from Lua as well as on
-//! screen (decision 2128).
-//!
-//! Types 3/11 (grayscale, raw/RLE) stay supported although the reference refuses them: no corpus
-//! or client file is one, so this is a superset a decoder cannot be feature-detected on, and
-//! removing working code with zero demand buys nothing. Stated rather than implied.
-//!
-//! [`tga_to_rgba`] validates the header before touching pixels, so it is safe to use as a
-//! *fallback* decoder on bytes of uncertain format (TGA has no magic; the caller sniffs `BLP2`
-//! first and only then tries this — a non-TGA almost always fails the type/depth/size checks).
+//! [`tga_to_rgba`] checks the header before the pixels, so it can serve as the fallback after a
+//! failed `BLP2` sniff: TGA has no magic.
 
 use anyhow::{bail, Result};
 
-/// Decode a TGA to RGBA8: `(width, height, pixels)` — top-down row order, like
-/// [`crate::blp_to_rgba`].
+/// Decode a TGA to RGBA8 `(width, height, pixels)`, rows top-down like [`crate::blp_to_rgba`].
 pub fn tga_to_rgba(bytes: &[u8]) -> Result<(u32, u32, Vec<u8>)> {
     let Some(header) = bytes.get(..18) else {
         bail!("TGA: truncated header ({} bytes)", bytes.len());
@@ -56,8 +34,7 @@ pub fn tga_to_rgba(bytes: &[u8]) -> Result<(u32, u32, Vec<u8>)> {
     };
     let paletted = matches!(image_type, 1 | 9);
     let grayscale = matches!(image_type, 3 | 11);
-    // A colour-mapped image's "pixel" is an INDEX; the palette entry's own width is separate, and
-    // both are needed before the stream can be read (`0x5a3b40`'s offset arithmetic uses each).
+    // A colour-mapped pixel is an index, its palette entry a width of its own (`0x5a3b40`).
     let bytes_per_pixel = match (bpp, paletted, grayscale) {
         (8, true, _) => 1,
         (24, false, false) => 3,
@@ -76,9 +53,8 @@ pub fn tga_to_rgba(bytes: &[u8]) -> Result<(u32, u32, Vec<u8>)> {
         bail!("TGA: implausible dimensions {width}x{height}");
     }
 
-    // Skip the id field and (for a truecolor image that still carries one) the color map. For a
-    // colour-mapped image the map is not skipped past — it is READ, and the reference reads it at
-    // exactly this offset (`0x5a3b40`: `entryBytes*colorMapLength + idLength + 0x12`).
+    // The pixels start after the id field and any colour map, which a colour-mapped image reads
+    // on the way (`0x5a3b40`: `entryBytes * colorMapLength + idLength + 0x12`).
     let map_bytes = if color_map_type == 1 {
         color_map_len * map_entry_bytes
     } else {
@@ -100,8 +76,8 @@ pub fn tga_to_rgba(bytes: &[u8]) -> Result<(u32, u32, Vec<u8>)> {
     let pixel_count = (width as usize) * (height as usize);
     let mut pixels = Vec::with_capacity(pixel_count * bytes_per_pixel);
     if rle {
-        // RLE packets: header bit 7 = run (one pixel, repeated count times), else raw
-        // (count pixels follow); count = low 7 bits + 1. Runs may NOT cross the image end.
+        // An RLE packet's bit 7 marks a run of one pixel, else `count` raw pixels follow; `count`
+        // is the low 7 bits plus 1.
         let mut at = 0usize;
         while pixels.len() < pixel_count * bytes_per_pixel {
             let Some(&packet) = data.get(at) else {
@@ -135,8 +111,8 @@ pub fn tga_to_rgba(bytes: &[u8]) -> Result<(u32, u32, Vec<u8>)> {
         pixels.extend_from_slice(px);
     }
 
-    // BGR(A)/gray → RGBA, honouring the descriptor's origin bits (bit 5: top-origin, bit 4:
-    // right-origin — TGA's default is bottom-left, our output is top-down left-to-right).
+    // BGR(A) or gray → RGBA. Descriptor bit 5 is a top origin, bit 4 a right one; TGA's default
+    // is bottom-left.
     let top_down = descriptor & 0x20 != 0;
     let right_first = descriptor & 0x10 != 0;
     let mut rgba = vec![0u8; pixel_count * 4];
@@ -151,18 +127,16 @@ pub fn tga_to_rgba(bytes: &[u8]) -> Result<(u32, u32, Vec<u8>)> {
             let s = (src_y * width as usize + src_x) * bytes_per_pixel;
             let d = (y * width as usize + x) * 4;
             if paletted {
-                // `0x5a3820`: `src = palette + (index - firstIndex) * entryBytes`, then a memcpy
-                // of one entry. `firstIndex` is the header's colour-map ORIGIN — almost always 0,
-                // and the arithmetic is wrong without it on the images where it is not.
+                // `0x5a3820`: `palette + (index - firstIndex) * entryBytes`, `firstIndex` being
+                // the header's colour-map origin (almost always 0).
                 let idx = (pixels[s] as usize).wrapping_sub(color_map_origin);
                 let e = idx * map_entry_bytes;
                 let Some(entry) = palette.get(e..e + map_entry_bytes) else {
                     bail!("TGA: colour index {} is outside the map", pixels[s]);
                 };
                 rgba[d..d + 4].copy_from_slice(&match map_entry_bytes {
-                    // 15/16-bit entries are ARRRRRGG GGGBBBBB little-endian; 16-bit spends the top
-                    // bit on alpha, 15-bit leaves it unused, and both replicate the high bits down
-                    // so that a full channel reads 0xff rather than 0xf8.
+                    // 15/16-bit entries are `ARRRRRGG GGGBBBBB` little-endian, the top bit alpha
+                    // only at 16; the high bits replicate down so a full channel reads 0xff.
                     2 => {
                         let v = u16::from_le_bytes([entry[0], entry[1]]);
                         let c = |shift: u32| {
@@ -207,7 +181,7 @@ pub fn tga_to_rgba(bytes: &[u8]) -> Result<(u32, u32, Vec<u8>)> {
 mod tests {
     use super::*;
 
-    /// A minimal COLOUR-MAPPED TGA: header + palette + index stream.
+    /// A minimal colour-mapped TGA: header, palette, index stream.
     fn tga_paletted(
         image_type: u8,
         w: u16,
@@ -231,12 +205,8 @@ mod tests {
         out
     }
 
-    /// **Colour-mapped TGAs decode** — types 1 and 9, the two the reference's dispatch sends to
-    /// `0x5a39d0` and this decoder used to refuse outright (decision 2128).
-    ///
-    /// The shape is the corpus's own: 8-bit indices into a 24-bit palette, which is what all three
-    /// of `FonzAppraiser/img/icon_disable.tga`, `FuBar_WeaponRebuffFu/icon.tga` and
-    /// `FonzSummon/img/icon_disable.tga` are.
+    /// Types 1 and 9, which the reference sends to `0x5a39d0`, in the addons' shape: 8-bit
+    /// indices into a 24-bit palette.
     #[test]
     fn colour_mapped_images_decode_through_the_palette() {
         // Palette as BGR: entry 0 red, entry 1 green, entry 2 blue.
@@ -254,12 +224,11 @@ mod tests {
             ]
         );
 
-        // Type 9 is the same image RLE'd — the run operates on INDEX bytes, not on expanded
-        // pixels, which is the half a naive port gets wrong.
+        // Type 9 is the same image RLE'd; the runs are over index bytes, not expanded pixels.
         let rle = tga_paletted(9, 2, 2, &pal, 24, &[0x02, 0, 1, 2, 0x80, 0]);
         assert_eq!(tga_to_rgba(&rle).unwrap().2, rgba);
 
-        // An index the map cannot answer is LOUD, not a silent black pixel.
+        // An index outside the map is an error, not a black pixel.
         let bad = tga_paletted(1, 1, 1, &pal, 24, &[9]);
         assert!(tga_to_rgba(&bad)
             .unwrap_err()
@@ -267,7 +236,7 @@ mod tests {
             .contains("outside the map"));
     }
 
-    /// A minimal TGA: 18-byte header + pixels.
+    /// A minimal TGA: an 18-byte header and pixels.
     fn tga(image_type: u8, w: u16, h: u16, bpp: u8, descriptor: u8, data: &[u8]) -> Vec<u8> {
         let mut out = vec![0u8; 18];
         out[2] = image_type;
@@ -281,15 +250,14 @@ mod tests {
 
     #[test]
     fn uncompressed_32bit_bottom_origin_flips_and_swizzles() {
-        // 2 wide × 2 tall, bottom-up rows: file row 0 is the image's BOTTOM row.
-        // Bottom row: blue, green; top row: red, half-alpha white — as BGRA.
+        // Bottom-up rows, as BGRA: blue, green at the bottom; red, half-alpha white on top.
         let px = [
             255, 0, 0, 255, /* blue */ 0, 255, 0, 255, /* green */
             0, 0, 255, 255, /* red */ 255, 255, 255, 128, /* white a=128 */
         ];
         let (w, h, rgba) = tga_to_rgba(&tga(2, 2, 2, 32, 0, &px)).unwrap();
         assert_eq!((w, h), (2, 2));
-        // Top-down output: row 0 = red, white; row 1 = blue, green — as RGBA.
+        // Top-down output, as RGBA: red, white, then blue, green.
         assert_eq!(
             rgba,
             vec![
@@ -309,7 +277,7 @@ mod tests {
 
     #[test]
     fn rle_run_and_raw_packets_expand() {
-        // 4×1 top-origin: a run of 3 red + a raw packet of 1 green (BGR, 24-bit).
+        // 4×1 top-origin: a run of 3 red and a raw packet of 1 green (BGR, 24-bit).
         let data = [0x82, 0, 0, 255, 0x00, 0, 255, 0];
         let (w, _, rgba) = tga_to_rgba(&tga(10, 4, 1, 24, 0x20, &data)).unwrap();
         assert_eq!(w, 4);
@@ -332,7 +300,7 @@ mod tests {
     fn garbage_and_unsupported_types_are_loud_misses() {
         assert!(tga_to_rgba(b"BLP2xxxxxxxxxxxxxxxxxx").is_err()); // a BLP is not a TGA
         assert!(tga_to_rgba(&[0u8; 4]).is_err()); // truncated header
-        assert!(tga_to_rgba(&tga(1, 2, 2, 8, 0, &[0; 32])).is_err()); // color-mapped
+        assert!(tga_to_rgba(&tga(1, 2, 2, 8, 0, &[0; 32])).is_err()); // colour-mapped, no map
         assert!(tga_to_rgba(&tga(2, 2, 2, 16, 0, &[0; 32])).is_err()); // 16-bit
         assert!(tga_to_rgba(&tga(2, 2, 2, 32, 0, &[0; 4])).is_err()); // truncated pixels
     }
diff --git a/crates/benilla-formats/src/transport_period.rs b/crates/benilla-formats/src/transport_period.rs
index 431cf3c4..8092a5f2 100644
--- a/crates/benilla-formats/src/transport_period.rs
+++ b/crates/benilla-formats/src/transport_period.rs
@@ -1,37 +1,17 @@
-//! The real client's own MO_TRANSPORT cycle-period bookkeeping (`WoW.exe` `0x5f4cc0` + its
-//! arc-time solver `0x5f9120`), transcribed step-for-step from `wow-5875-re`'s byte-verified
-//! findings — the 2026-07-17 §5 gold validation reproduced **all nine** live transport paths'
-//! server-sniff periods bit-exact by emulating this exact recipe natively
-//! (`wow-5875-re` `system/object-layer/scratch/transport-anchor-timetable.md` §TU-B(5),
-//! `tests/difftest/transport_period.rs`). The wire anchor is a raw server-uptime-scale clock, so
-//! the `% period` amplifies any Δms by the whole cycle count — the period must be *exact*, not
-//! close (decision 0438 §3). vmangos pins its DB periods to sniffs of THIS computation, so
-//! matching the client is matching the server.
+//! The reference's `MO_TRANSPORT` cycle period (`0x5f4cc0` with its arc-time solver `0x5f9120`),
+//! transcribed step for step: it reproduces all nine transport paths' sniffed periods bit-exact,
+//! and must, as the wire anchor is a server-uptime clock whose `% period` multiplies any error by
+//! the cycle count. vmangos's periods are sniffs of this computation.
 //!
-//! Layout facts this transcription rests on (all byte-cited in wow-re):
-//! - Legs split when the row's map changes OR the previous row has `Flags & 1`; **every** row of
-//!   the path lands in a leg — the leg's first and last points are Catmull-Rom guard points the
-//!   travel never lands on (curve eval samples segment `seg` over `P[seg..seg+4]`, interpolating
-//!   `P[seg+1] → P[seg+2]`; `n_seg = count − 3`, built only when `count > 3` — wow-re
-//!   `rf52-curve-construction.md`).
-//! - Per-segment arc length = 20 sub-chords of the cubic eval, **f32-narrowing accumulate**, the
-//!   sample parameter itself an f32 stepped by 0.05 (`0x453760`); cumulative distance = f64 sum
-//!   of the f32 segment lengths (`0x453300`); the cached leg total narrows to f32 (`0x4532e0`'s
-//!   `fstp dword`).
-//! - Span times: a span runs stop→stop *including leg start/end as mid-cruise boundaries* — the
-//!   first span charges one ramp (the decel into the first stop), interior spans two (the full
-//!   trapezoid), the final span one (the accel out); a leg with no stops is pure cruise `d/v`.
-//!   Each span's time is rounded to ms **individually** (`round_ftol`) and accumulated as
-//!   integer — the per-span rounding is exactly what a whole-path float accumulation misses.
-//! - `period = Σ leg durations + Σ stop delays (Delay × 1000, integer)`; stops are counted once,
-//!   and a stop flag on a leg's *first* row is ignored (the point list is still empty when the
-//!   stop check runs — `0x5f4cc0`'s `local_1c != 0` gate).
+//! A leg ends where the map changes or the previous row has `Flags & 1`; its first and last points
+//! are Catmull-Rom guards the travel never reaches. A span runs stop to stop, a leg's ends counting
+//! as mid-cruise, and each span rounds to ms on its own before the integer sum, which a float sum
+//! over the path would miss. The period adds every stop's `Delay × 1000`.
 
 use crate::taxi::TaxiPathNode;
 
-/// The client's position-basis matrix `0xb05e10` — the uniform Catmull-Rom (tension 0.5) basis,
-/// rows as Horner coefficients highest-degree-first (row `i` weights control point `P[seg+i]`).
-/// Decoded from the static-init immediates at `0x453fa0` (wow-re §TU-B(3)).
+/// The reference's basis `0xb05e10` (set at `0x453fa0`): uniform Catmull-Rom, tension 0.5, row
+/// `i` the Horner coefficients, highest degree first, that weight `P[seg+i]`.
 const CR_BASIS: [[f32; 4]; 4] = [
     [-0.5, 1.0, -0.5, 0.0],
     [1.5, -2.5, 0.0, 1.0],
@@ -39,8 +19,7 @@ const CR_BASIS: [[f32; 4]; 4] = [
     [0.5, -0.5, 0.0, 0.0],
 ];
 
-/// `0x453620` `BasisWeight`: the cubic basis polynomial in Horner form, f64-internal, returned
-/// unrounded to the evaluator.
+/// `0x453620`: the basis cubic in Horner form, computed in f64 and returned unrounded.
 fn basis_weight(coeff: &[f32; 4], t: f32) -> f64 {
     let t = f64::from(t);
     let mut w = f64::from(coeff[0]);
@@ -50,10 +29,9 @@ fn basis_weight(coeff: &[f32; 4], t: f32) -> f64 {
     w
 }
 
-/// `0x453580` cubic point evaluator: `out = Σ wᵢ·Pᵢ` over 4 consecutive control points, with the
-/// **asymmetric** per-component narrowing the bytes show — the x product stays f64 into its add,
-/// the y/z products narrow to f32 first (`fstp dword` temp), and every component's accumulator
-/// re-narrows to f32 each step (wow-re `curvemath/src/spline.rs::eval_point_body`).
+/// `0x453580`: `Σ wᵢ·Pᵢ` over 4 control points, narrowing asymmetrically: the x product stays f64
+/// into its add, the y and z products narrow to f32 first, and every accumulator narrows to f32
+/// each step.
 fn eval_point_cubic(cps: &[[f32; 3]], t: f32) -> [f32; 3] {
     let mut out = [0.0f32; 3];
     for (i, p) in cps.iter().take(4).enumerate() {
@@ -67,8 +45,8 @@ fn eval_point_cubic(cps: &[[f32; 3]], t: f32) -> [f32; 3] {
     out
 }
 
-/// `0x453760` arc-length integrator: 20 sub-chords at an f32 parameter stepped by 0.05, chord
-/// length `sqrt((dz²+dy²)+dx²)` f64-internal, the accumulator narrowing to f32 every step.
+/// `0x453760`: 20 sub-chords at an f32 parameter stepped by 0.05, each `sqrt((dz²+dy²)+dx²)` in
+/// f64, the sum narrowing to f32 every step.
 fn seg_arc_length(cps: &[[f32; 3]]) -> f32 {
     let mut prev = eval_point_cubic(cps, 0.0);
     let mut acc = 0.0f32;
@@ -86,9 +64,8 @@ fn seg_arc_length(cps: &[[f32; 3]]) -> f32 {
     acc
 }
 
-/// `0x453300` knot-sum: the cumulative distance of point index `idx` from the leg's travel start
-/// = the pure-f64 sum of the first `idx − 1` per-segment f32 lengths (the guard-point shift makes
-/// this exactly point `idx`'s distance — segment 0 spans `P[1] → P[2]`).
+/// `0x453300`: point `idx`'s distance from the leg's start, the f64 sum of the first `idx - 1`
+/// f32 segment lengths (segment 0 spans `P[1]` → `P[2]`).
 fn knot_sum(seg_len: &[f32], idx: usize) -> f64 {
     let mut acc = 0.0f64;
     for &k in seg_len.iter().take(idx.saturating_sub(1)) {
@@ -97,8 +74,7 @@ fn knot_sum(seg_len: &[f32], idx: usize) -> f64 {
     acc
 }
 
-/// `·1000` then round-half-away-from-zero then truncate — the client's `__ftol` rounding idiom
-/// (wow-re `object_layer/taxi_spline.rs::round_ftol`, diffed bit-exact).
+/// Seconds to ms, rounded half away from zero: the reference's `__ftol` idiom (`0x40a2b0`).
 fn round_ftol(t: f64) -> i32 {
     let scaled = t * 1000.0;
     let adj = if scaled > 0.0 {
@@ -109,10 +85,9 @@ fn round_ftol(t: f64) -> i32 {
     adj.trunc() as i32
 }
 
-/// `0x5f9120` per-span arc time (wow-re `taxi_spline.rs::arc_time_ms`, diffed bit-exact): the
-/// constant-acceleration solve over the span's distance `d = p − l`, with the client's own
-/// f32/f64 mixing (`A` and `B` stored f32, the discriminant compare on the *live* f64 `B`).
-/// `first` = the leg's first span (one ramp: leg start is mid-cruise); otherwise two ramps.
+/// `0x5f9120`: a span's constant-acceleration time over `d = p - l`, `A` and `B` stored as f32
+/// but compared on the live f64 `B`. A leg's `first` span has one ramp, as its start is
+/// mid-cruise; later spans have two.
 fn arc_time_ms(p: f64, l: f32, speed: f32, accel: f32, first: bool) -> i32 {
     let d = p - f64::from(l);
     let a = (f64::from(speed) / f64::from(accel)) as f32;
@@ -132,9 +107,8 @@ fn arc_time_ms(p: f64, l: f32, speed: f32, accel: f32, first: bool) -> i32 {
     round_ftol(t)
 }
 
-/// `0x5f9120` block 2, the leg's final span (`taxi_spline.rs::arc_time_ms_final`): with no stop
-/// processed the whole leg is pure cruise `d/v` (no ramps — both ends are mid-cruise); after a
-/// stop it's the one-ramp form (the accel out of the last stop).
+/// `0x5f9120` block 2, a leg's last span: pure cruise `d/v` when the leg had no stop, else one
+/// ramp out of the last stop.
 fn arc_time_ms_final(p: f32, l: f32, speed: f32, accel: f32, first: bool) -> i32 {
     let d = f64::from(p) - f64::from(l);
     let t: f64 = if first {
@@ -153,8 +127,7 @@ fn arc_time_ms_final(p: f32, l: f32, speed: f32, accel: f32, first: bool) -> i32
 
 /// One closed leg's contribution: `(span-time sum, Σ its stop delays)`.
 fn close_leg(points: &[[f32; 3]], stops: &[(usize, i32)], speed: f32, accel: f32) -> (i32, i32) {
-    // BuildArcLen only runs for count > 3 (`0x4532e0`'s gate); a shorter leg keeps a zero
-    // seg-table and zero cached total, so every span solves over d = 0.
+    // Segments exist only past 3 points (`0x4532e0`); a shorter leg solves every span over d = 0.
     let (seg_len, total) = if points.len() > 3 {
         let n_seg = points.len() - 3;
         let seg_len: Vec<f32> = (0..n_seg).map(|s| seg_arc_length(&points[s..])).collect();
@@ -166,27 +139,26 @@ fn close_leg(points: &[[f32; 3]], stops: &[(usize, i32)], speed: f32, accel: f32
 
     let mut duration = 0i32;
     let mut delays = 0i32;
-    let mut l = 0.0f32; // the running span-start distance ([ebp+0x10], an f32 slot)
+    let mut l = 0.0f32; // the span start, an f32 slot (`[ebp+0x10]`)
     let mut processed = 0usize;
     for &(pt_idx, delay_ms) in stops {
         delays += delay_ms;
-        // A stop on the leg's last point (or the guard) has no span of its own (`0x5f9120`'s
-        // `count − 1 <= idx` break) — its delay still counts in the period.
+        // A stop on the leg's last point or guard has no span (`0x5f9120`'s `count - 1 <= idx`
+        // break), but its delay counts.
         if pt_idx + 1 >= points.len() {
             break;
         }
         let p = knot_sum(&seg_len, pt_idx);
         duration += arc_time_ms(p, l, speed, accel, processed == 0);
-        l = p as f32; // the solver's `fst dword` — the next span's start narrows to f32
+        l = p as f32; // the next span's start narrows to f32 (`fst dword`)
         processed += 1;
     }
     duration += arc_time_ms_final(total, l, speed, accel, processed == 0);
     (duration, delays)
 }
 
-/// The full client period for one transport path, ms — `0x5f4cc0`'s `handler+0x3c`, bit-exact
-/// (gold-gated against the nine server-sniff values by `transports.rs`' calibration test).
-/// `None` for an empty path.
+/// One transport path's period in ms, `0x5f4cc0`'s `handler+0x3c`; the `transports` calibration
+/// test pins it to the nine sniffed values.
 pub(crate) fn client_period_ms(nodes: &[TaxiPathNode], speed: f32, accel: f32) -> Option<u32> {
     if nodes.is_empty() || accel <= 0.0 {
         return None;
@@ -204,9 +176,8 @@ pub(crate) fn client_period_ms(nodes: &[TaxiPathNode], speed: f32, accel: f32) -
             stops.clear();
             leg_map = node.map_id;
         }
-        // The stop check runs before the point append: a stop flag on the leg's first row is
-        // ignored (`0x5f4cc0`, the `local_1c != 0` gate). The client tests `Flags & 2` as a
-        // bitmask (`0x5f4e37`) and multiplies the delay as an integer.
+        // The stop check precedes the append, so a stop on a leg's first row is ignored
+        // (`0x5f4cc0`'s `local_1c != 0` gate); `Flags & 2` is a bitmask test (`0x5f4e37`).
         if node.flags & 2 != 0 && !points.is_empty() {
             stops.push((points.len(), node.delay as i32 * 1000));
         }
diff --git a/crates/benilla-formats/src/transports/mod.rs b/crates/benilla-formats/src/transports/mod.rs
index a1db8360..787ae5e2 100644
--- a/crates/benilla-formats/src/transports/mod.rs
+++ b/crates/benilla-formats/src/transports/mod.rs
@@ -1,78 +1,32 @@
-//! `MO_TRANSPORT` timetable builder + cycle sampler (decision 0438 phase 0) — pure math, no Bevy,
-//! **WoW coordinates throughout** (the Bevy transform is the consumer's job).
+//! `MO_TRANSPORT` timetable builder and cycle sampler: pure math in WoW coordinates, transcribing
+//! vmangos's path builder `TransportMgr::GenerateWaypoints` (`TransportMgr.cpp:105-334`), its mover
+//! `ShipTransport::Update`/`CalculateSegmentPos` (`Transport.cpp:283-380`) and its Catmull-Rom
+//! splines (`Movement/spline/spline.cpp`).
 //!
-//! This transcribes the structural skeleton of vmangos's own transport-path builder and mover:
-//! - `TransportMgr::GenerateWaypoints` (`/Users/sam/wre/vmangos-src/src/game/Transports/
-//!   TransportMgr.cpp:105-334`) — the keyframe list, the map-change/teleport skip dance, the
-//!   per-leg Catmull-Rom splines, the `DistSinceStop`/`DistUntilStop` modular walks, the
-//!   four-regime `TimeTo` trapezoid, and the `ArriveTime`/`DepartureTime` accumulation.
-//! - `ShipTransport::Update` + `CalculateSegmentPos` (`.../Transport.cpp:283-380`) — the
-//!   stateless "where on the path is `progress % period`" query, [`TransportTimetable::sample`].
-//! - The spline machinery (`.../Movement/spline/spline.cpp`): `s_catmullRomCoeffs` (:61-65) is
-//!   transcribed as closed-form blending polynomials in [`catmull_rom_weights`] /
-//!   [`catmull_rom_deriv_weights`] (verified by hand-expanding the `Vector4 * Matrix4` row-vector
-//!   product — standard Catmull-Rom basis functions, tau = 0.5); `SegLengthCatmullRom` (:159-177,
-//!   `STEPS_PER_SEGMENT` chord samples) is [`Leg::seg_length`]; `InitCatmullRom`'s non-cyclic
-//!   virtual endpoints (:238-268 — the **first** virtual point is `lerp(c0, c1, -1)`, i.e.
-//!   `2·c0 − c1`; the **last** is a plain **duplicate** of the final real control, not
-//!   extrapolated) are [`Leg::control`].
-//!
-//! **The whole-path orientation spline collapses to a closed form.** `GenerateWaypoints` builds a
-//! second, separate Catmull-Rom spline over the *entire* raw path (with hand-computed virtual
-//! endpoints, `TransportMgr.cpp:120-127`) purely to read `InitialOrientation` off
-//! `evaluate_derivative(i, t=0)` for every kept node. Expanding `s_catmullRomCoeffs`' derivative
-//! weights at `t=0` gives `[-0.5, 0, 0.5, 0]` — only the two *interior* control points survive (the
-//! virtual endpoints' weight is always zero at `t=0`, and are in fact never even reached within the
-//! nodes this loop visits). So `InitialOrientation(i) = atan2(path[i+1].y − path[i−1].y,
-//! path[i+1].x − path[i−1].x) + π`, using the **raw, unfiltered** node array — no spline object
-//! needed. See `orientation_at` below.
-//!
-//! **Timing-mode calibration is the point of this module.** vmangos's own computed periods do
-//! **not** match the real client's — the server DB-overrides them (`transports` table,
-//! `TransportMgr.cpp:63-79`, "load period override from db since our algorithm is not perfect").
-//! The client's per-span arc-length time is transcribed bit-exact in `wow-5875-re`
-//! (`crates/object-layer/src/taxi_spline.rs`: `arc_time_ms`, closed-form constant-acceleration
-//! kinematics with `round_ftol` — ×1000, round-half-away-from-zero, truncate). [`TimeMode`] (private —
-//! not public API) selects between vmangos's own f32-seconds accumulation (`Mode::Vmangos`,
-//! transcribing `TransportMgr.cpp:297-325` exactly) and a client-closed-form per-span accumulation
-//! (`Mode::ClientForms`); the arc-length chord-sampling density (`STEPS_PER_SEGMENT` — vmangos uses
-//! 3, its own comment notes "client's value is 20") is a second calibration knob. The `tests`
-//! module builds all nine live transports under every (mode × steps) combination against the
-//! server's actually-effective (DB-pinned) periods and reports a table — see decision 0438 phase 0.
-//!
-//! **The cycle length itself is past calibration:** [`TransportTimetable::build`] pins its period
-//! to the real client's own bookkeeping, transcribed in [`crate::transport_period`] and gold-gated
-//! bit-exact against all nine server-sniff values (the 2026-07-17 wow-re §5 verdict). The sample
-//! table between the pins stays vmangos-mode (internally consistent windows + easing); porting the
-//! client's true per-leg tick evaluation is the recorded follow-on.
+//! The period is the reference's own ([`crate::transport_period`]); vmangos's computed periods do
+//! not match it, which is why the server overrides them from its DB (`TransportMgr.cpp:63-79`).
+//! Between stops the sample follows vmangos's accumulation; the reference's per-leg tick
+//! evaluation is not ported.
 
 use std::f32::consts::PI;
 
 use crate::taxi::TaxiPathNode;
 
-/// A transport's position/heading at one instant of its cycle — WoW coordinates, ready for the
-/// Bevy consumer's own coordinate transform.
+/// A transport's position and heading at one instant of its cycle, in WoW coordinates.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct TransportSample {
-    /// The map this `pos` is expressed in (can differ from the timetable's "home" map — a
-    /// transport crosses continents mid-cycle).
+    /// The map of `pos`, which changes as a transport crosses continents.
     pub map: u32,
-    /// World position `(x, y, z)`.
     pub pos: [f32; 3],
-    /// Facing, radians, normalized to `[0, 2π)` — `atan2(dir.y, dir.x) + π`
-    /// (`Transport.cpp:349`).
+    /// Radians in `[0, 2π)`, `atan2(dir.y, dir.x) + π` (`Transport.cpp:349`).
     pub heading: f32,
-    /// `false` while parked at a station stop (or the zero-width instant at a non-stop
-    /// keyframe); `true` while under way.
+    /// False while parked at a stop or on a keyframe's zero-width instant.
     pub moving: bool,
 }
 
-/// A single kept keyframe — one surviving `TaxiPathNode` after the map-change/teleport skip dance
-/// (`TransportMgr.cpp:128-152`), with every quantity [`TransportTimetable::sample`] needs from
-/// `GenerateWaypoints`. `IsStopFrame`/`Teleport` themselves aren't stored: `sample` recovers both
-/// from the derived timestamps/distances alone (a non-stop frame's `[arrive, depart)` window is
-/// always zero-width; a teleport frame's `next_dist_from_prev` is always `0` — see their doc
-/// comments below) rather than carrying redundant state.
+/// A keyframe that survives the map-change skip (`TransportMgr.cpp:128-152`), with what `sample`
+/// needs. Stop and teleport are implicit: a non-stop window is zero-width, and a teleport's
+/// `next_dist_from_prev` is 0.
 #[derive(Debug, Clone)]
 struct Frame {
     map_id: u32,
@@ -80,21 +34,18 @@ struct Frame {
     initial_orientation: f32,
     dist_since_stop: f32,
     dist_until_stop: f32,
-    /// The distance of the segment from this frame *to the next* — `0` for a teleport frame (no
-    /// continuous travel across a jump) and for the path's final frame.
+    /// Arc length to the next frame; 0 for a teleport frame and the last frame.
     next_dist_from_prev: f32,
     time_from: f32,
     time_to: f32,
     departure_time: u32,
     next_arrive_time: u32,
-    /// Which [`Leg`] (and which 0-based control-point position within it) this frame's outbound
-    /// spline segment is evaluated on.
+    /// The [`Leg`] and control index of this frame's outbound segment.
     leg: usize,
     local_index: usize,
 }
 
-/// A raw kept node, pre-derived-quantities — the map-change dance's output, source data for
-/// [`Frame`] and both timing modes.
+/// A kept node before the derived quantities.
 #[derive(Debug, Clone, Copy)]
 struct RawFrame {
     map_id: u32,
@@ -105,19 +56,16 @@ struct RawFrame {
     teleport: bool,
 }
 
-/// One spline leg: a maximal run of keyframes between teleport boundaries (a leg's last member is
-/// always a teleport frame, or the path's final frame). Non-cyclic Catmull-Rom
-/// (`InitCatmullRom`'s non-cyclic branch) over `controls`, with virtual endpoints computed
-/// on-demand by [`Leg::control`] rather than stored.
+/// A run of keyframes ending at a teleport or the path's end: a non-cyclic Catmull-Rom spline
+/// (`InitCatmullRom`).
 #[derive(Debug, Clone)]
 struct Leg {
     controls: Vec<[f32; 3]>,
 }
 
 impl Leg {
-    /// The control point at raw (possibly out-of-range) index `i`, extending with vmangos's
-    /// non-cyclic virtual endpoints: `i < 0` → `2·c0 − c1` (extrapolated); `i >= len` → a
-    /// **duplicate** of the last real control (not extrapolated) — `spline.cpp:262-265`.
+    /// Control `i` with vmangos's virtual endpoints (`spline.cpp:262-265`): before the start
+    /// `2·c0 − c1`, past the end a duplicate of the last control, not extrapolated.
     fn control(&self, i: isize) -> [f32; 3] {
         let n = self.controls.len();
         if i < 0 {
@@ -131,8 +79,7 @@ impl Leg {
         }
     }
 
-    /// Position on segment `k` (0-based, connecting `controls[k]` to `controls[k+1]`) at `t ∈
-    /// [0, 1]` — `SplineBase::EvaluateCatmullRom`.
+    /// Position on segment `k` at `t` in `[0, 1]` (`SplineBase::EvaluateCatmullRom`).
     fn evaluate_percent(&self, k: usize, t: f32) -> [f32; 3] {
         catmull_rom_eval(
             self.control(k as isize - 1),
@@ -143,7 +90,7 @@ impl Leg {
         )
     }
 
-    /// Derivative on segment `k` at `t` — `SplineBase::EvaluateDerivativeCatmullRom`.
+    /// Derivative on segment `k` at `t` (`SplineBase::EvaluateDerivativeCatmullRom`).
     fn evaluate_derivative(&self, k: usize, t: f32) -> [f32; 3] {
         catmull_rom_derivative(
             self.control(k as isize - 1),
@@ -154,9 +101,8 @@ impl Leg {
         )
     }
 
-    /// Arc length of segment `k`, approximated by `steps` evenly-spaced chords —
-    /// `SplineBase::SegLengthCatmullRom` (`spline.cpp:159-177`), `length_type` is `double` there
-    /// (`Movement::Spline<double>`), matched here.
+    /// Arc length of segment `k` over `steps` chords, summed in `f64` as
+    /// `SplineBase::SegLengthCatmullRom` does (`spline.cpp:159-177`).
     fn seg_length(&self, k: usize, steps: u32) -> f64 {
         let mut cur = self.control(k as isize); // t=0 evaluates to exactly controls[k]
         let mut total = 0.0f64;
@@ -187,9 +133,8 @@ fn dist64(a: [f32; 3], b: [f32; 3]) -> f64 {
     (dx * dx + dy * dy + dz * dz).sqrt()
 }
 
-/// The vmangos `s_catmullRomCoeffs` matrix (`spline.cpp:61-65`), expanded by hand as the `t³ t² t
-/// 1` row-vector times the matrix (`C_Evaluate`'s `Vector4 weights(tvec * matr)`) into the four
-/// classic Catmull-Rom (τ = 0.5) blending polynomials — verified by direct expansion, not assumed.
+/// vmangos's `s_catmullRomCoeffs` (`spline.cpp:61-65`) expanded as `t³ t² t 1` times the matrix:
+/// the Catmull-Rom blending polynomials, τ = 0.5.
 fn catmull_rom_weights(t: f32) -> [f32; 4] {
     let (t2, t3) = (t * t, t * t * t);
     [
@@ -200,8 +145,7 @@ fn catmull_rom_weights(t: f32) -> [f32; 4] {
     ]
 }
 
-/// `d/dt` of [`catmull_rom_weights`] — `C_Evaluate_Derivative`'s `3t² 2t 1 0` row vector times the
-/// same matrix.
+/// `d/dt` of [`catmull_rom_weights`]: `C_Evaluate_Derivative`'s `3t² 2t 1 0` times the matrix.
 fn catmull_rom_deriv_weights(t: f32) -> [f32; 4] {
     let t2 = t * t;
     [
@@ -234,7 +178,7 @@ fn catmull_rom_derivative(
     blend(p0, p1, p2, p3, catmull_rom_deriv_weights(t))
 }
 
-/// Wrap to `[0, 2π)` — `Geometry::NormalizeOrientation`.
+/// Wrap to `[0, 2π)`, as `Geometry::NormalizeOrientation`.
 fn normalize_orientation(o: f32) -> f32 {
     let tau = std::f32::consts::TAU;
     let wrapped = o % tau;
@@ -245,28 +189,18 @@ fn normalize_orientation(o: f32) -> f32 {
     }
 }
 
-/// The timing-accumulation variant — see the module doc's "Timing-mode calibration". Not public
-/// API: [`TransportTimetable::build`] picks one default; the calibration test in this module's
-/// `#[cfg(test)]` sweeps all of them, including `Vmangos` — hence the `cfg_attr` below: outside
-/// `cargo test`, `build`'s hardcoded default is the only caller, so plain `cargo build` never
-/// constructs it.
+/// How keyframe times accumulate: `build` uses `Vmangos`, the calibration tests sweep both.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum TimeMode {
-    /// vmangos's own `TransportMgr.cpp:297-325`: a running `f32` seconds accumulator, truncated
-    /// to ms once per keyframe. **The sample-table default** — windows and easing from one
-    /// accumulation (see [`TransportTimetable::build`]).
+    /// vmangos's `f32` seconds, truncated to ms per keyframe (`TransportMgr.cpp:297-325`).
     Vmangos,
-    /// The real client's constant-acceleration closed form (`wow-5875-re`'s `taxi_spline`),
-    /// applied once per stop-to-stop span and rounded with `round_ftol`, accumulated as integer
-    /// ms. Interior timestamps are distance-linear — a period-calibration device (the golden
-    /// sweep), NOT a sampling table; constructed only by the calibration tests.
+    /// The reference's closed form (`0x5f9120`) per stop-to-stop span, in integer ms. Interior
+    /// times are distance-linear, so it only calibrates periods; only the tests build it.
     #[cfg_attr(not(test), allow(dead_code))]
     ClientForms,
 }
 
-/// `·1000.0` then round-half-away-from-zero then truncate — `wow-5875-re`'s
-/// `object_layer::taxi_spline::round_ftol` (the client's own `__ftol` rounding idiom, `fcom
-/// 0.0;test ah,0x41` → `±0.5`), transcribed exactly.
+/// Seconds to ms, `±0.5` then truncated, as the reference's `__ftol` idiom (`0x40a2b0`).
 fn round_ftol(t: f64) -> i32 {
     let scaled = t * 1000.0;
     let adj = if scaled > 0.0 {
@@ -277,11 +211,9 @@ fn round_ftol(t: f64) -> i32 {
     adj.trunc() as i32
 }
 
-/// The client's "both ramps present" closed form for a stop-to-stop span of distance `d_span`
-/// (`wow-5875-re::object_layer::taxi_spline::arc_time_ms`'s `!first` branch: `if 2B < D { (D −
-/// 2B)/v + 2A } else { 2·√(D/a) }`, `A = v/a` stored `f32`, `B = ½·v·A` kept live `f64` for the
-/// branch compare but stored `f32` for the arithmetic — the exact f32/f64 mixing `taxi_spline.rs`
-/// diffs), rounded to ms via [`round_ftol`].
+/// A stop-to-stop span's time in ms, the reference's `0x5f9120` `!first` branch:
+/// `if 2B < D { (D − 2B)/v + 2A } else { 2·√(D/a) }`, with `A = v/a` stored `f32` and `B = ½·v·A`
+/// compared in `f64` but stored `f32`; the mixed precision is the reference's.
 fn span_time_ms(d_span: f32, speed: f32, accel: f32) -> u32 {
     if accel <= 0.0 {
         return 0;
@@ -289,9 +221,9 @@ fn span_time_ms(d_span: f32, speed: f32, accel: f32) -> u32 {
     let d = f64::from(d_span);
     let v = f64::from(speed);
     let a_param = f64::from(accel);
-    let a: f32 = (v / a_param) as f32; // A, stored f32 (the client's own precision loss)
-    let b_live = 0.5 * v * f64::from(a); // B kept live (f64) — the branch compare uses this
-    let b: f32 = b_live as f32; // B stored f32 — the arithmetic reads this
+    let a: f32 = (v / a_param) as f32; // A, stored f32 as the reference does
+    let b_live = 0.5 * v * f64::from(a); // B in f64, for the branch compare
+    let b: f32 = b_live as f32; // B stored f32, for the arithmetic
     let t: f64 = if b_live < 0.5 * d {
         (d - 2.0 * f64::from(b)) / v + 2.0 * f64::from(a)
     } else {
@@ -304,10 +236,8 @@ fn delay_ms(secs: f32) -> u32 {
     (secs * 1000.0).round().max(0.0) as u32
 }
 
-/// Mode V: vmangos's own accumulation, transcribed exactly (`TransportMgr.cpp:297-325`) —
-/// including the "add the previous frame's `TimeTo`, then subtract this frame's own `TimeTo` back
-/// off when it isn't a stop" pattern (the running-estimate-plus-correction trick that gives
-/// continuous-looking per-frame timestamps from a per-frame "time to the far stop" quantity).
+/// vmangos's accumulation (`TransportMgr.cpp:297-325`): add the previous frame's `TimeTo`, and at
+/// a non-stop frame subtract its own.
 fn accumulate_vmangos(raws: &[RawFrame], time_to: &[f32]) -> (Vec<u32>, Vec<u32>, Vec<u32>, u32) {
     let n = raws.len();
     let mut arrive = vec![0u32; n];
@@ -338,22 +268,9 @@ fn accumulate_vmangos(raws: &[RawFrame], time_to: &[f32]) -> (Vec<u32>, Vec<u32>
     (arrive, depart, next_arrive, period)
 }
 
-/// Mode C: per-stop-to-stop-span time from the client's closed form ([`span_time_ms`]),
-/// accumulated as integer ms; delays enter as exact `delay·1000`. A span's *boundary* timestamps
-/// (at its two stop frames) are exact by construction — that's what the golden gate needs.
-/// Interior (non-stop) frame timestamps are apportioned by cumulative distance within the span, a
-/// phase-0 simplification: only the period (a boundary quantity) is gated this round; the
-/// client's true per-point interior scheme is phase-1 work (see the module doc).
-///
-/// **The path's own start/end fragments (frame 0 to the first stop; the last stop to the final
-/// frame) are not self-contained spans** — frame 0 and the final frame are both mid-cruise, not
-/// at rest (the path is cyclic: the true journey between the *last* stop and the *first* stop
-/// runs last_stop → final frame → [the period wrap, zero distance] → frame 0 → first_stop, one
-/// continuous two-ramp span). Treating the two fragments as independent fresh spans (each
-/// wrongly assumed to start/end at rest) double-charges roughly one full `accel_time` across the
-/// period — the ~30 s-off-of-30 s-`accel_time` bug this comment is pinned against. `leading_dist`
-/// / `trailing_dist` / `d_wrap` below reconstruct that one true wrap span; both fragments are
-/// timed off its single [`span_time_ms`] total, at their own distance fraction of it.
+/// Integer-ms times from [`span_time_ms`] per stop-to-stop span, exact at the stops; interior
+/// frames are apportioned by distance, not by the reference's per-point scheme. The fragments
+/// before the first stop and after the last are one span across the wrap, not two from rest.
 fn accumulate_client_forms(
     raws: &[RawFrame],
     dist_from_prev: &[f32],
@@ -373,8 +290,7 @@ fn accumulate_client_forms(
         .collect();
 
     if stops.is_empty() {
-        // Degenerate (no station stop anywhere on the path) — not expected for a real transport;
-        // a defensive fallback treating the whole cyclic path as one wrap span, no delays.
+        // No stop at all: the whole cyclic path is one wrap span.
         let d_total: f32 = dist_from_prev[1..].iter().sum();
         let t_total = i64::from(span_time_ms(d_total, speed, accel));
         let mut cum = 0.0f32;
@@ -406,8 +322,7 @@ fn accumulate_client_forms(
     let d_wrap = leading_dist + trailing_dist;
     let t_wrap = i64::from(span_time_ms(d_wrap, speed, accel));
 
-    // Leading fragment (frame 0 is clock-zero by definition; arrive[0] stays its `vec![0; n]`
-    // default): every frame up to and including first_stop, at the wrap span's rate.
+    // The leading fragment, frame 0 at clock zero, at the wrap span's rate.
     let mut cum = 0.0f32;
     for k in 1..=first_stop {
         cum += dist_from_prev[k];
@@ -420,7 +335,7 @@ fn accumulate_client_forms(
     }
     depart[first_stop] = arrive[first_stop] + delay_ms(raws[first_stop].delay_secs);
 
-    // Interior stop-to-stop spans, in order — each is a genuine, self-contained two-ramp span.
+    // Interior spans, each two-ramp and self-contained.
     for w in stops.windows(2) {
         let (b_prev, b_next) = (w[0], w[1]);
         let depart_prev = i64::from(depart[b_prev]);
@@ -440,7 +355,7 @@ fn accumulate_client_forms(
         }
     }
 
-    // Trailing fragment (last_stop to the final frame) — the wrap span's tail, same rate.
+    // The trailing fragment, the wrap span's tail.
     let depart_last = i64::from(depart[last_stop]);
     let mut cum = 0.0f32;
     for k in (last_stop + 1)..n {
@@ -463,12 +378,10 @@ fn accumulate_client_forms(
     (arrive, depart, next_arrive, period)
 }
 
-/// A `MO_TRANSPORT`'s full cyclic timetable, built once per `taxiPathId` — the timekeeping half of
-/// decision 0438 phase 0. See the module doc for provenance.
+/// A `MO_TRANSPORT`'s cyclic timetable, built once per `taxiPathId`.
 #[derive(Debug, Clone)]
 pub struct TransportTimetable {
-    /// The full cycle length, ms — `progress % period_ms` is the transport's position in its
-    /// loop (decision 0438 §3).
+    /// Cycle length in ms; `progress % period_ms` is the position in the loop.
     pub period_ms: u32,
     frames: Vec<Frame>,
     legs: Vec<Leg>,
@@ -479,25 +392,17 @@ pub struct TransportTimetable {
 }
 
 impl TransportTimetable {
-    /// Build a transport's timetable from its `TaxiPathNode` rows (sorted by `node_index`) and
-    /// its `gameobject_template` `data1`/`data2` (`moveSpeed`/`accelRate`, as `f32`). `None` if
-    /// the path is too short to have an interior (fewer than 3 nodes — the first and last are
-    /// always teleport-arrival cells with no travel of their own).
+    /// Build from `TaxiPathNode` rows sorted by `node_index` and the `gameobject_template`
+    /// `data1`/`data2` (`moveSpeed`, `accelRate`). The first and last nodes are never travelled,
+    /// so fewer than 3 is `None`.
     pub fn build(nodes: &[TaxiPathNode], move_speed: f32, accel_rate: f32) -> Option<Self> {
-        // Vmangos-mode accumulation for the SAMPLE table: its u32 windows and the float
-        // trapezoid easing derive from one accumulation, so `sample()` is internally consistent.
-        // ClientForms apportions interior timestamps linearly by distance (a period-calibration
-        // device, per its doc) — feeding those windows to the trapezoid easing made the boat
-        // stick at segment ends and leap when the window flipped (the director's "ship lagged
-        // into Booty Bay", measured at up to 15,000 yd/s spikes by the speed-profile probe).
-        // Arc sampling stays at the client's 20 chord steps (`spline.h:61`).
+        // Vmangos mode, so windows and easing come from one accumulation: ClientForms windows
+        // under the trapezoid easing make a ship stick at segment ends and then leap. 20 chord
+        // steps, the client's (`spline.h:61`).
         let mut tt =
             Self::build_with_variant(nodes, move_speed, accel_rate, TimeMode::Vmangos, 20)?;
-        // The cycle LENGTH self-pins to the real client's own bookkeeping (`transport_period`,
-        // gold-gated bit-exact against all nine server-sniff periods — the 2026-07-17 wow-re §5
-        // verdict). The wire anchor is a raw server-uptime-scale clock, so `% period` amplifies
-        // any Δms by the whole cycle count; vmangos pins its DB periods to sniffs of the same
-        // client computation, so this IS the server's period — no consumer-side table needed.
+        // The reference's period (`transport_period`), which vmangos's DB periods are sniffs of;
+        // `% period` on the server-uptime anchor multiplies any error by the cycle count.
         if let Some(period) =
             crate::transport_period::client_period_ms(nodes, move_speed, accel_rate)
         {
@@ -506,29 +411,15 @@ impl TransportTimetable {
         Some(tt)
     }
 
-    /// **The cycle instant this path first stands on `map_id`, searching forward from
-    /// `from_cycle_ms` and wrapping** — the client-side answer to "the server says this transport
-    /// has just crossed onto that continent; where in my own timetable is that?"
-    ///
-    /// A client computes a transport's position from its own path clock, anchored whenever the
-    /// object's CREATE block last arrived, so that clock is free to drift from the server's about
-    /// *when* a crossing happens (measured live at 32–144 ms on the 1.12 fleet). The server does
-    /// re-anchor it on arrival — `Map::SendInitSelf` sends the ridden transport's create first,
-    /// which is why `SendInitTransports` then skips it — but that lands a round trip after the
-    /// worldport ack, and a consumer that must place a rider *in the worldport frame* has nothing
-    /// to place them through until it does. This is that answer: the instant our own timetable
-    /// puts the transport on the map the server just named.
-    ///
-    /// Returns the frame's **arrival** instant (the start of its window), so the sample lands at
-    /// the head of the destination leg rather than mid-travel. `None` if no keyframe lies on
-    /// `map_id` at all — the caller has misidentified the transport.
+    /// The arrival instant of the first frame on `map_id`, scanning from the frame `from_cycle_ms`
+    /// is in and wrapping. A worldport places a rider with it until the server re-anchors the
+    /// transport's clock, a round trip after the ack (`Map::SendInitSelf`).
     pub fn first_cycle_on_map(&self, from_cycle_ms: u32, map_id: u32) -> Option<u32> {
         let n = self.frames.len();
         if n == 0 {
             return None;
         }
-        // The frame `from_cycle_ms` currently sits in — the scan starts there so a clock already
-        // on the destination leg answers "right here" instead of a whole cycle away.
+        // Start at the current frame: a clock already on the map answers here.
         let start = self
             .frames
             .iter()
@@ -543,17 +434,12 @@ impl TransportTimetable {
             })
     }
 
-    /// Whether any of the cycle's keyframes lies on `map_id` — i.e. this transport exists on
-    /// that map for part of its loop. The cross-map worldport (decision 0455) keeps such a
-    /// transport alive through the map switch (its clock is one continuous domain over the
-    /// whole loop; the per-frame tick already resolves which legs render on which map).
+    /// Whether any keyframe is on `map_id`; a worldport keeps such a transport across the switch.
     pub fn touches_map(&self, map_id: u32) -> bool {
         self.frames.iter().any(|f| f.map_id == map_id)
     }
 
-    /// The calibration entry point (not public API — see the module doc). Mirrors
-    /// `TransportMgr::GenerateWaypoints` phase for phase; each phase is commented with its
-    /// vmangos source line range.
+    /// `TransportMgr::GenerateWaypoints` phase by phase, with a chosen time mode and chord count.
     fn build_with_variant(
         nodes: &[TaxiPathNode],
         move_speed: f32,
@@ -566,8 +452,7 @@ impl TransportTimetable {
             return None;
         }
 
-        // Phase A: the map-change/teleport skip dance (TransportMgr.cpp:128-152). First/last raw
-        // nodes are teleport-arrival cells, never visited (loop bound `1..n_raw-1`).
+        // Phase A: the map-change skip (`TransportMgr.cpp:128-152`), end nodes never visited.
         let mut raws: Vec<RawFrame> = Vec::new();
         let mut map_change = false;
         for i in 1..n_raw - 1 {
@@ -582,18 +467,16 @@ impl TransportTimetable {
                 }
                 map_change = true;
             } else {
-                // The whole-path orientation spline collapses to a central difference at t=0
-                // (module doc) — using the RAW, unfiltered neighbors, regardless of whether they
-                // themselves survive the skip dance.
+                // vmangos's whole-path spline derivative at t = 0 is this central difference of
+                // the raw neighbours, kept or not (`TransportMgr.cpp:120-127`).
                 let (prev, nxt) = (nodes[i - 1].pos, nodes[i + 1].pos);
                 let initial_orientation =
                     normalize_orientation((nxt[1] - prev[1]).atan2(nxt[0] - prev[0]) + PI);
                 raws.push(RawFrame {
                     map_id: node.map_id,
                     pos: node.pos,
-                    // The CLIENT tests the stop flag as a bitmask (`test byte[row+0x1c], 0x2`
-                    // @0x5f4e37 — the 2026-07-17 wow-re §5); vmangos's `IsStopFrame` uses exact
-                    // `== 2`. Identical on the live data (flags ∈ {0, 2}) — we follow the client.
+                    // The reference tests the stop bit as a mask (`0x5f4e37`), vmangos's
+                    // `IsStopFrame` as `== 2`; the data only holds 0 and 2.
                     is_stop: node.flags & 2 != 0,
                     delay_secs: node.delay as f32,
                     initial_orientation,
@@ -604,14 +487,11 @@ impl TransportTimetable {
         if raws.is_empty() {
             return None;
         }
-        // Last to first is always "teleport", even for closed paths (GenerateWaypoints, after
-        // the main loop).
+        // The last frame always teleports, even on a closed path (`GenerateWaypoints`).
         raws.last_mut().unwrap().teleport = true;
         let n = raws.len();
 
-        // Phase B: legs — a new leg starts right after every teleport=true frame (a teleport
-        // frame is always the last member of its own leg, matching the vmangos `extra`-point
-        // dance without needing to replicate its raw-pointer bookkeeping — see the module doc).
+        // Phase B: a new leg starts after every teleport frame.
         let mut leg_of = vec![0usize; n];
         let mut local_index_of = vec![0usize; n];
         let mut leg_controls: Vec<Vec<[f32; 3]>> = vec![Vec::new()];
@@ -632,9 +512,7 @@ impl TransportTimetable {
             .map(|controls| Leg { controls })
             .collect();
 
-        // Phase D: DistFromPrev / NextDistFromPrev (TransportMgr.cpp:192-234) — arc length of the
-        // segment ending at (resp. starting at) each frame, `0` for a leg's first member (resp.
-        // teleport frames and the path's last frame).
+        // Phase D: `DistFromPrev`, `NextDistFromPrev` (`TransportMgr.cpp:192-234`).
         let mut dist_from_prev = vec![0.0f32; n];
         for j in 0..n {
             if local_index_of[j] > 0 {
@@ -651,7 +529,7 @@ impl TransportTimetable {
             };
         }
 
-        // firstStop / lastStop (TransportMgr.cpp:213-222).
+        // `firstStop`, `lastStop` (`TransportMgr.cpp:213-222`).
         let mut first_stop: Option<usize> = None;
         let mut last_stop: Option<usize> = None;
         for (j, r) in raws.iter().enumerate() {
@@ -662,7 +540,7 @@ impl TransportTimetable {
         }
         let (first_stop, last_stop) = (first_stop.unwrap_or(0), last_stop.unwrap_or(0));
 
-        // Phase E: DistSinceStop / DistUntilStop, the two modular walks (TransportMgr.cpp:237-256).
+        // Phase E: `DistSinceStop`, `DistUntilStop` (`TransportMgr.cpp:237-256`).
         let mut dist_since_stop = vec![0.0f32; n];
         let mut tmp = 0.0f32;
         for i in 0..n {
@@ -685,9 +563,7 @@ impl TransportTimetable {
             }
         }
 
-        // Phase F: per-frame TimeTo, the four-regime trapezoid (TransportMgr.cpp:260-284) — pure
-        // kinematics, shared by both timing modes (only the Arrive/Departure accumulation, Phase
-        // H, is mode-dependent — see the module doc).
+        // Phase F: `TimeTo`, the four-regime trapezoid (`TransportMgr.cpp:260-284`).
         let accel_dist = 0.5 * move_speed * move_speed / accel_rate;
         let accel_time = move_speed / accel_rate;
         let mut time_to = vec![0.0f32; n];
@@ -711,7 +587,7 @@ impl TransportTimetable {
             };
         }
 
-        // Phase G: TimeFrom (TransportMgr.cpp:287-295).
+        // Phase G: `TimeFrom` (`TransportMgr.cpp:287-295`).
         let mut time_from = vec![0.0f32; n];
         let mut segment_time = 0.0f32;
         for i in 0..n {
@@ -722,9 +598,7 @@ impl TransportTimetable {
             time_from[j] = segment_time - time_to[j];
         }
 
-        // Phase H: Arrive/Departure + period — the calibrated variant. `_arrive_time` (per-frame
-        // arrival) isn't retained on [`Frame`]: `sample` only ever needs `departure_time` (a
-        // window's start) and `next_arrive_time` (its end) — see the `Frame` doc.
+        // Phase H: arrivals, departures and the period, by mode; `sample` needs no arrival.
         let (_arrive_time, departure_time, next_arrive_time, period_ms) = match mode {
             TimeMode::Vmangos => accumulate_vmangos(&raws, &time_to),
             TimeMode::ClientForms => {
@@ -760,18 +634,8 @@ impl TransportTimetable {
         })
     }
 
-    /// Pin the cycle length to the exact period — **the server's own move**
-    /// (`TransportMgr.cpp:63-79`: vmangos overrides its computed `pathTime` with the DB-sniffed
-    /// per-build client value, stretching the final keyframe's departure), mirrored here.
-    /// [`Self::build`] applies it with the client-transcribed period ([`crate::transport_period`],
-    /// bit-exact against all nine server-sniff values — the 2026-07-17 wow-re §5 verdict): the
-    /// wire anchor is a *raw* server-uptime-scale clock, so a Δms period error is amplified by
-    /// the whole `floor(progress/period)` cycle count at every `% period` — days of uptime turn
-    /// a 20 ms mismatch into minutes of phase error.
-    ///
-    /// A longer pin parks the transport at its final keyframe for the extra slice (exactly
-    /// vmangos's stretch); a shorter one truncates the final approach at wrap ([`Self::sample`]
-    /// clamps into the last window). Both deltas are tens of ms — invisible either way.
+    /// Pin the period as vmangos pins its DB value (`TransportMgr.cpp:63-79`): a longer one parks
+    /// the transport at its last keyframe, a shorter one cuts the final approach at the wrap.
     fn override_period(&mut self, period_ms: u32) {
         if period_ms == 0 || period_ms == self.period_ms {
             return;
@@ -785,9 +649,8 @@ impl TransportTimetable {
         self.period_ms = period_ms;
     }
 
-    /// The transport's position/heading at `cycle_ms` (`progress % period_ms`) —
-    /// `ShipTransport::Update` + `CalculateSegmentPos` (`Transport.cpp:283-380`), done
-    /// statelessly (no persistent "current frame" — a fresh search every call).
+    /// Position and heading at `cycle_ms` (`progress % period_ms`), as `ShipTransport::Update` and
+    /// `CalculateSegmentPos` compute them (`Transport.cpp:283-380`), with no state between calls.
     pub fn sample(&self, cycle_ms: u32) -> TransportSample {
         let n = self.frames.len();
         if n == 0 {
@@ -800,9 +663,7 @@ impl TransportTimetable {
         }
         let cycle_ms = cycle_ms.min(self.period_ms.saturating_sub(1));
 
-        // The first frame whose window `[ArriveTime, NextArriveTime)` contains cycle_ms — the
-        // union of its stop window `[Arrive, Depart)` and its outbound travel window `[Depart,
-        // NextArrive)`.
+        // The frame whose `[ArriveTime, NextArriveTime)`, stop then travel, holds `cycle_ms`.
         let idx = self
             .frames
             .iter()
@@ -811,9 +672,7 @@ impl TransportTimetable {
         let frame = &self.frames[idx];
 
         if cycle_ms < frame.departure_time || frame.next_dist_from_prev <= 0.0 {
-            // Waiting at a stop, the zero-width instant at a non-stop keyframe, or (defensively)
-            // a teleport's zero-width travel window — teleports never have a real outbound
-            // window (see the `next_dist_from_prev` doc on `Frame`).
+            // At a stop, on a keyframe's instant, or on a teleport's zero-length travel.
             return TransportSample {
                 map: frame.map_id,
                 pos: frame.pos,
@@ -822,8 +681,8 @@ impl TransportTimetable {
             };
         }
 
-        // Moving toward the next frame — CalculateSegmentPos (Transport.cpp:353-380): distance
-        // from the *nearer* stop, under the same four-regime trapezoid as the build-time TimeTo.
+        // Moving: distance from the nearer stop under the same trapezoid as `TimeTo`
+        // (`Transport.cpp:353-380`).
         let now = cycle_ms as f32 * 0.001;
         let since_departure = now - frame.departure_time as f32 * 0.001;
         let time_since_stop = frame.time_from + since_departure;
diff --git a/crates/benilla-formats/src/transports/tests.rs b/crates/benilla-formats/src/transports/tests.rs
index 73438d99..4e5f8cd0 100644
--- a/crates/benilla-formats/src/transports/tests.rs
+++ b/crates/benilla-formats/src/transports/tests.rs
@@ -1,7 +1,5 @@
-//! The nine-golden calibration + gold gates for the transport timetable (decision 0438 phase
-//! 0): the mode × chord-steps period report against the server's effective (DB-pinned) periods,
-//! and the bit-exactness gate on the client-transcribed period (`crate::transport_period`) that
-//! lets [`TransportTimetable::build`] self-pin. Needs the vanilla client data (skips otherwise).
+//! Transport timetable tests against the nine live transports' server periods; they skip without
+//! client data.
 
 use super::*;
 use crate::taxi::load_taxi_path_nodes;
@@ -12,14 +10,12 @@ struct Golden {
     period_ms: u32,
     move_speed: f32,
     accel_rate: f32,
-    /// A real build sniff (vs. a `build 0` fallback row) — the task's distinguished subset.
+    /// A sniffed row, not a `build 0` fallback.
     sniffed: bool,
 }
 
-/// The nine live transports' server-effective (DB-pinned) periods — vmangos `transports`
-/// table, build-≤5875 row selected, and `gameobject_template` `data1`/`data2`, both read this
-/// session (decision 0438's data-model survey). All moveSpeed=30/accelRate=1 except Naxxramas
-/// (181056), moveSpeed=1/accelRate=1.
+/// The nine live transports' periods from vmangos's `transports` table (the build ≤ 5875 row) and
+/// their `gameobject_template` `data1`/`data2`.
 const GOLDENS: &[Golden] = &[
     Golden {
         entry: 20808,
@@ -98,11 +94,8 @@ const GOLDENS: &[Golden] = &[
 const MODES: &[(&str, TimeMode)] = &[("V", TimeMode::Vmangos), ("C", TimeMode::ClientForms)];
 const STEPS_VARIANTS: &[u32] = &[3, 10, 20, 100];
 
-/// Builds every one of the nine live transports' timetables under every (mode × arc-length
-/// chord-sampling) combination and reports computed-vs-golden period for each. This is the
-/// calibration report the phase-0 gate needs, not a pass/fail bit: the goldens pin **which**
-/// variant is the real client's algorithm (decision 0438 phase 0), so only loose sanity is
-/// asserted here — a period > 0, and the *best* variant per path within 5% of golden.
+/// A report of every mode and chord count against the goldens; it only asserts that each path's
+/// best variant is within 5%.
 #[test]
 fn nine_period_calibration_report() {
     let data = crate::wow_data_or_skip!();
@@ -194,11 +187,7 @@ fn nine_period_calibration_report() {
     }
 }
 
-/// The bit-exactness gate for the client-transcribed period (`transport_period`): all nine
-/// live transports must reproduce their server-sniff golden **exactly** — this is what lets
-/// [`TransportTimetable::build`] self-pin its cycle length instead of consulting a hardcoded
-/// server table (the 2026-07-17 wow-re §5 gold validation, decision 0438 §3's exactness
-/// requirement).
+/// `transport_period` must reproduce every golden exactly, since `build` pins its period to it.
 #[test]
 fn client_period_bit_exact() {
     let data = crate::wow_data_or_skip!();
@@ -227,9 +216,7 @@ fn client_period_bit_exact() {
     );
 }
 
-/// [`TransportTimetable::touches_map`] answers exactly the raw path's map set — the cross-map
-/// worldport's spare predicate (decision 0455) rests on it — and the premise itself holds: at
-/// least one of the nine live transports really does cross continents mid-cycle.
+/// Also proves that at least one live transport crosses continents.
 #[test]
 fn touches_map_matches_the_paths_map_set() {
     let data = crate::wow_data_or_skip!();
@@ -260,17 +247,8 @@ fn touches_map_matches_the_paths_map_set() {
     );
 }
 
-/// [`TransportTimetable::first_cycle_on_map`] — the seam's re-anchor target (decision 2026).
-///
-/// Two properties, on every cross-continent path in the fleet, because the fleet's seams are not
-/// alike: one path changes map mid-cycle, another only at the cycle wrap (path 241's map-1 legs are
-/// frames 0..22 and its map-0 legs are the tail, so "cross to Kalimdor" *is* the wrap), and a
-/// re-anchor that only handled the interior case would leave exactly the reported ferry broken.
-///
-/// 1. From anywhere in the cycle, the answer is an instant that really does sample on the asked-for
-///    map — that is the whole contract, and it is what the rider's world pose is composed through.
-/// 2. Asking from an instant already on that map returns an instant on it too (the caller's
-///    already-there short-circuit rests on the map agreeing, not on the number).
+/// From any instant, the answer samples on the asked-for map, on every cross-continent path:
+/// path 241 reaches map 1 only across the cycle wrap.
 #[test]
 fn first_cycle_on_map_lands_on_that_map() {
     let data = crate::wow_data_or_skip!();
@@ -289,8 +267,7 @@ fn first_cycle_on_map_lands_on_that_map() {
             continue;
         }
         crossed += 1;
-        // Probe from 64 instants spread across the whole cycle — every leg, both continents, and
-        // the frames either side of the wrap.
+        // 64 instants across the cycle, both sides of the wrap included.
         for k in 0..64u32 {
             let from = (u64::from(tt.period_ms) * u64::from(k) / 64) as u32;
             for &m in &maps {
@@ -315,7 +292,7 @@ fn first_cycle_on_map_lands_on_that_map() {
                 );
             }
         }
-        // A map the path never visits has no answer at all.
+        // A map the path never visits.
         assert_eq!(tt.first_cycle_on_map(0, 9999), None);
     }
     assert!(
diff --git a/crates/benilla-formats/src/unit_blood.rs b/crates/benilla-formats/src/unit_blood.rs
index c11e84fa..4586c91f 100644
--- a/crates/benilla-formats/src/unit_blood.rs
+++ b/crates/benilla-formats/src/unit_blood.rs
@@ -1,29 +1,16 @@
-//! **UnitBlood.dbc / UnitBloodLevels.dbc** — the melee blood-spurt tables (decision 0137 phase 3).
+//! `UnitBlood.dbc` and `UnitBloodLevels.dbc`, the melee blood-spurt tables.
 //!
-//! The byte-verified chain (wow-re `melee-blood-spurt.md`, `0x624530 → 0x625010`): a melee hit with
-//! `HitInfo & 0x2`, nonzero damage, and victimState ∈ {1,4} resolves the victim's blood id
-//! ([`BloodCatalog::level_key`]: the `CreatureDisplayInfo.BloodLevel` override, else
-//! `CreatureModelData.BloodID`, else **UnitBloodLevels' file row 0** — the tier-3 fallback 1850
-//! restored) → a **UnitBloodLevels** row, whose three columns are the bloodID per
-//! `violenceLevel` (0–2) — the
-//! vanilla censorship table: a red-blooded creature at violence 1 bleeds *green*, at 0 nothing —
-//! → a **UnitBlood** row whose first four fields are `SpellVisualEffectName` ids. Column order
-//! pinned empirically from the effect names (`Combat Blood Spurt <Front|Back> <Small|Large> <color>`,
-//! 12/12 rows consistent): **[FrontSmall, FrontLarge, BackSmall, BackLarge]** — front/back from
-//! `sign(victimForward · (attackerPos − victimPos))`, Large on the *crushing* bit `HitInfo & 0x2000`
-//! (not crit — crit `0x80` belongs to the wound flinch).
+//! The chain (`0x624530`, `0x625010`): a melee hit with `HitInfo & 0x2`, nonzero damage and
+//! victim state 1 or 4 resolves the victim's blood id ([`BloodCatalog::level_key`]), whose
+//! `UnitBloodLevels` row names a `UnitBlood` row per violence level: the censorship table, where
+//! red blood turns green at violence 1 and vanishes at 0. That row's first four fields are
+//! `SpellVisualEffectName` ids in front-small, front-large, back-small, back-large order (read
+//! from the effect names): front or back by `sign(victimForward · (attackerPos − victimPos))`,
+//! large on the crushing bit `HitInfo & 0x2000`, not the crit bit `0x80`, the wound flinch's.
 //!
-//! **Fields 5–9 are the row's ground-splat decal textures, and they are DEAD in 1.12.1**
-//! (`textures\BloodSplats\…`, [`BloodCatalog::splats`]; wow-re `ground-blood-splat-dead.md`,
-//! decision 1850). Not "unimplemented" — *absent*: no instruction in the image reads
-//! `UnitBloodRecord + 0x14 … +0x24`, and the string `"BloodSplat"` occurs nowhere in `WoW.exe`,
-//! though all twelve `.blp` ship in `texture.MPQ` and the DBC resolves them. Data shipped, art
-//! shipped, code gone. The only ground decal in 1.12.1 that takes a DBC string column is the
-//! footprint. So there is no trigger, no placement and no fade to be faithful to, and the accessor
-//! exists to pin the finding, not to feed a lane: the shipped table names **four** textures per
-//! row and leaves the fifth column empty in all three (red / green / black), so a reader takes the
-//! non-empty prefix, never a fixed five. Drawing them at all would be a benilla embellishment —
-//! the director's call, not a fidelity gap.
+//! Fields 5 to 9 are ground-splat textures 1.12.1 never reads: no instruction touches
+//! `UnitBloodRecord + 0x14` to `+0x24` and the string `"BloodSplat"` is absent from the binary,
+//! though the textures ship. [`BloodCatalog::splats`] exists to pin that, not to feed a renderer.
 
 use std::collections::HashMap;
 
@@ -36,57 +23,32 @@ use crate::dbc::{parse, str_at, u32_at};
 const UNIT_BLOOD: &str = "DBFilesClient\\UnitBlood.dbc";
 const UNIT_BLOOD_LEVELS: &str = "DBFilesClient\\UnitBloodLevels.dbc";
 
-/// The two blood tables, resolving `(blood id, violence level, front, crushing)` → the spurt's
-/// `SpellVisualEffectName` id (whose path the spell-visual catalog resolves like any kit effect).
+/// Both blood tables: `(blood id, violence, front, crushing)` to the spurt's
+/// `SpellVisualEffectName` id.
 pub struct BloodCatalog {
-    /// UnitBloodLevels: id → the bloodID per violence level 0/1/2 (`0` = no blood at that level).
+    /// `UnitBloodLevels` id to the `UnitBlood` id per violence level 0 to 2; 0 is no blood.
     levels: HashMap<u32, [u32; 3]>,
-    /// The id of UnitBloodLevels' **file row 0** — the records base the reference's tier-3
-    /// fallback returns ([`BloodCatalog::level_key`]). `1` in the shipped table (ids 1/2/3, so
-    /// this is emphatically *not* `idIndex[0]`, which is NULL). `None` for an empty table.
+    /// The id of `UnitBloodLevels`' first file row, the records base the reference's third tier
+    /// returns: 1 as shipped, and not `idIndex[0]`, which is null.
     default_level: Option<u32>,
-    /// UnitBlood: id → the row's spurt effects + ground-splat textures.
     rows: HashMap<u32, BloodRow>,
 }
 
-/// One `UnitBlood.dbc` row: the four spurt `SpellVisualEffectName` ids and the row's ground-splat
-/// decal textures.
 struct BloodRow {
     /// `[FrontSmall, FrontLarge, BackSmall, BackLarge]` effect ids.
     effects: [u32; 4],
-    /// The non-empty ground-splat textures, in column order (`textures\BloodSplats\…`,
-    /// extensionless). Four in every shipped row; the fifth column is empty throughout.
+    /// The non-empty ground-splat textures in column order, extensionless; four in every shipped
+    /// row.
     splats: Vec<String>,
 }
 
 impl BloodCatalog {
-    /// The victim's **UnitBloodLevels key**, by the reference's three-tier fallback — the display
-    /// resolve `0x60afb0`, which stores the resulting row pointer at `[unit+0xb48]` and is the only
-    /// place blood ids are turned into a row (wow-re `melee-blood-spurt.md` §c,
-    /// `ground-blood-splat-dead.md` §Q9):
-    ///
-    /// 1. `CreatureDisplayInfo.BloodLevel` (`display_blood`), else
-    /// 2. `CreatureModelData.BloodID` (`model_blood`), else
-    /// 3. **UnitBloodLevels' file row 0** — id `1`, the RED row, in the shipped table.
-    ///
-    /// A tier "fails" on `< 0`, on `> maxId`, **or** on an `idIndex` slot that holds no row —
-    /// which a [`HashMap`] miss covers exactly. That third tier is the load-bearing one: 595 of
-    /// the 10534 shipped displays (5.6 %) reach it, because `BloodID = −1` is a tier-2 *miss*,
-    /// not a bloodless marker. Reading `−1` as "bloodless" is what benilla did until 1850, and
-    /// it silently dropped the spurt on every one of those 595.
-    ///
-    /// **The content proves tier 3 on its own** (1859), which matters because reading a
-    /// `setle/dec/and` correctly is a thing one can be wrong about, and this is not. The tier-3
-    /// population is headed by Quilboar, Mountain Giants, Crocolisks, Gnolls and Naga Sirens —
-    /// `Crocodile.mdx` being the *only* crocolisk model, so "no blood" here means no crocolisk in
-    /// the game ever bleeds. `−1` is **unspecified**, not *none*, and it splits families that
-    /// share a directory: `QuillBoar` is `−1` beside `QuillBoarWarrior` at `1`, `GnollMelee`
-    /// beside `GnollCaster`, `Troll\TrollMelee` beside `Troll\Troll`. It even splits a single
-    /// creature — eight models ship the same art under two `CreatureModelData` rows whose blood
-    /// ids disagree with one side `−1` (a Baby Murloc is both `1` and `−1`).
-    ///
-    /// `None` only for an empty table — no shipped display is bloodless by this chain. A unit
-    /// still ends up with no blood at violence 0, where every row's column is `0`.
+    /// The victim's `UnitBloodLevels` key by the reference's three tiers (`0x60afb0`, which stores
+    /// the row at `[unit+0xb48]`): `CreatureDisplayInfo.BloodLevel`, else
+    /// `CreatureModelData.BloodID`, else `UnitBloodLevels`' first file row, the red one. A tier
+    /// misses on `< 0`, on `> maxId` or on an empty `idIndex` slot. `BloodID` -1 is a miss, not
+    /// bloodless: 595 of the 10534 shipped displays reach the third tier, Quilboar, Crocolisks and
+    /// Gnolls among them.
     pub fn level_key(&self, display_blood: i32, model_blood: i32) -> Option<u32> {
         let resolves = |v: i32| {
             u32::try_from(v)
@@ -98,12 +60,8 @@ impl BloodCatalog {
             .or(self.default_level)
     }
 
-    /// The spurt effect for a victim: `blood_id` is the victim's UnitBloodLevels key — what
-    /// [`Self::level_key`] resolved, which for shipped data is always a real row — `violence` the
-    /// gore level (0–2, clamped), `front`/`large` the hit geometry/weight. `None` = no spurt:
-    /// censored away at this violence level (every row's column is `0` at violence 0), or a key
-    /// that names no row. The `<= 0` guard below is defensive, not a "bloodless model" case:
-    /// 1850 found that no shipped display resolves to one.
+    /// The spurt for a victim's [`Self::level_key`] at a violence level (0 to 2, clamped); `None`
+    /// where the level censors it, as every row does at violence 0, or the key names no row.
     pub fn effect_id(
         &self,
         blood_id: i32,
@@ -121,18 +79,14 @@ impl BloodCatalog {
         Some(row.effects[idx]).filter(|&id| id != 0)
     }
 
-    /// The **ground-splat decal textures** for a victim — the same row resolve as
-    /// [`Self::effect_id`] (`blood id → UnitBloodLevels[violence] → UnitBlood row`), so a censored
-    /// violence level drops the splat exactly as it drops the spurt. The slice is the row's non-empty texture columns in column order: extensionless
-    /// `textures\BloodSplats\…` paths, four per row in the shipped table. Empty = no splat.
+    /// The ground-splat textures for a victim, through the same censored row as
+    /// [`Self::effect_id`].
     pub fn splats(&self, blood_id: i32, violence: usize) -> &[String] {
         self.row(blood_id, violence).map_or(&[], |r| &r.splats)
     }
 
-    /// The victim's resolved `UnitBlood` row: the [`Self::level_key`] blood id keyed through the
-    /// violence-level censorship table (`GetUnitBloodRecord 0x60a390`). `None` for a violence
-    /// level this creature yields no blood at, for a row the table doesn't carry, or — the
-    /// defensive arm — for a non-positive key no resolve produces.
+    /// The `UnitBlood` row through the censorship table (`GetUnitBloodRecord`, `0x60a390`). The
+    /// non-positive guard is defensive: no resolve produces such a key.
     fn row(&self, blood_id: i32, violence: usize) -> Option<&BloodRow> {
         if blood_id <= 0 {
             return None;
@@ -144,13 +98,12 @@ impl BloodCatalog {
         self.rows.get(&level)
     }
 
-    /// Row counts (levels, rows) for logging/diagnostics.
+    /// Row counts, levels then rows, for diagnostics.
     pub fn len(&self) -> (usize, usize) {
         (self.levels.len(), self.rows.len())
     }
 }
 
-/// UnitBloodLevels.dbc — 4 fields in build 5875: ID + the three per-violence-level bloodIDs.
 fn unit_blood_levels_schema() -> Schema {
     let mut s = Schema::new("UnitBloodLevels");
     for name in ["ID", "Violence0", "Violence1", "Violence2"] {
@@ -159,8 +112,6 @@ fn unit_blood_levels_schema() -> Schema {
     s
 }
 
-/// UnitBlood.dbc — 10 fields in build 5875: ID, the four spurt `SpellVisualEffectName` ids, and
-/// five ground-splat texture strings (four named + one empty in every shipped row).
 fn unit_blood_schema() -> Schema {
     let mut s = Schema::new("UnitBlood");
     for name in ["ID", "FrontSmall", "FrontLarge", "BackSmall", "BackLarge"] {
@@ -175,15 +126,15 @@ fn unit_blood_schema() -> Schema {
     s
 }
 
-/// Load both blood tables from the patch chain into a [`BloodCatalog`].
+/// Load both blood tables off the patch chain.
 pub fn load_blood_catalog(chain: &mut Chain) -> Result<BloodCatalog> {
     let (levels, default_level) = {
         let bytes = chain
             .read_file(UNIT_BLOOD_LEVELS)
             .with_context(|| format!("reading {UNIT_BLOOD_LEVELS}"))?;
         let rs = parse(&bytes, unit_blood_levels_schema(), "UnitBloodLevels")?;
-        // File order matters here and nowhere else: tier 3 returns the RECORDS BASE, so the
-        // fallback id is row 0's, read before the rows go into the (unordered) map.
+        // File order matters here alone: the third tier returns the records base, row 0, so its
+        // id is read before the rows go into the unordered map.
         let default_level = rs.records().first().and_then(|r| u32_at(r, 0));
         let mut m = HashMap::with_capacity(rs.records().len());
         for r in rs.records() {
@@ -217,8 +168,7 @@ pub fn load_blood_catalog(chain: &mut Chain) -> Result<BloodCatalog> {
                             u32_at(r, 3).unwrap_or(0),
                             u32_at(r, 4).unwrap_or(0),
                         ],
-                        // `str_at` drops the empty columns, so a row keeps only the textures it
-                        // actually names — the fifth column throughout the shipped table.
+                        // `str_at` drops empty columns: a row keeps only the textures it names.
                         splats: (5..10).filter_map(|i| str_at(&rs, r, i)).collect(),
                     },
                 );
@@ -237,17 +187,15 @@ pub fn load_blood_catalog(chain: &mut Chain) -> Result<BloodCatalog> {
 mod tests {
     use super::*;
 
-    /// The real 5875 tables, end to end: a red-blooded creature (blood 1 — HumanMale's) at max
-    /// violence spurts RED (effect 109 front-small = `Particles\BloodSpurts\BloodSpurt.mdl`,
-    /// 55 back-large); at violence 1 the same creature is CENSORED to green (row 2's ids); at 0
-    /// nothing. Pins the empirically-derived column order against the shipped data.
+    /// Blood 1, the human male's: red at violence 2 (effect 109 is
+    /// `Particles\BloodSpurts\BloodSpurt.mdl`), green at 1, nothing at 0.
     #[test]
     fn real_blood_tables_resolve_the_censorship_chain() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let blood = load_blood_catalog(&mut chain).expect("blood tables");
 
-        // Max violence: true colors, all four quadrants of row 1 (red).
+        // Violence 2: all four spurts of row 1, red.
         assert_eq!(
             blood.effect_id(1, 2, true, false),
             Some(109),
@@ -268,22 +216,20 @@ mod tests {
             Some(55),
             "back large red"
         );
-        // Violence 1: red is censored to green (UnitBloodLevels row 1 → bloodID 2).
+        // Violence 1: censored to green, `UnitBlood` row 2.
         assert_eq!(
             blood.effect_id(1, 1, true, false),
             Some(183),
             "censored green"
         );
-        // Violence 0: no blood at all; the defensive non-positive guard yields nothing either.
+        // Violence 0 gives nothing, and so does a non-positive key.
         assert_eq!(blood.effect_id(1, 0, true, false), None);
         assert_eq!(blood.effect_id(-1, 2, true, false), None);
         assert_eq!(blood.effect_id(0, 2, true, false), None);
     }
 
-    /// The **three-tier row resolve** (`0x60afb0`), the bug 1850 fixed: a display whose
-    /// `BloodLevel` is `0` and whose model's `BloodID` is `−1` is NOT bloodless — both tiers miss
-    /// and tier 3 hands back UnitBloodLevels' file row 0, id 1, the RED row. Pinned end to end
-    /// against the shipped creature tables, including the population that reaches each tier.
+    /// The three-tier resolve (`0x60afb0`): a `BloodLevel` of 0 and a `BloodID` of -1 both miss,
+    /// and the third tier returns the red row, id 1.
     #[test]
     fn the_blood_row_resolve_falls_through_to_the_records_base() {
         let data = crate::wow_data_or_skip!();
@@ -301,7 +247,7 @@ mod tests {
             Some(2),
             "tier 2: 0 is not a row of the table"
         );
-        // Tier 3 — the 595-display case. `-1` is a MISS, not a bloodless marker.
+        // Tier 3: `-1` is a miss, not a bloodless marker.
         assert_eq!(
             blood.level_key(0, -1),
             Some(1),
@@ -317,13 +263,11 @@ mod tests {
             Some(1),
             "tier 3: both tiers out of range"
         );
-        // …and a tier-3 unit really does spurt, which is exactly what benilla dropped before.
+        // A tier-3 unit spurts.
         assert_eq!(blood.effect_id(1, 2, true, false), Some(109));
     }
 
-    /// The ground-splat columns of the same three rows: **four** textures each, colour-matched to
-    /// the row the violence level selects — red at max, the censored green one rung down, nothing
-    /// at 0 — and the fifth column empty throughout, so the shipped slice is length 4, never 5.
+    /// Four ground splats per row, never five, coloured by the row the violence level selects.
     #[test]
     fn real_blood_tables_carry_four_ground_splats_per_row() {
         let data = crate::wow_data_or_skip!();
@@ -340,10 +284,10 @@ mod tests {
             ],
             "red blood at max violence"
         );
-        // Censored one rung down: the same creature's splats go green (row 2), matching the spurt.
+        // Violence 1: green, row 2, as the spurt.
         assert!(blood.splats(1, 1).iter().all(|p| p.contains("Green")));
         assert_eq!(blood.splats(1, 1).len(), 4);
-        // Row 3 is the black-blood row; violence 0 (and the defensive guard) splat nothing.
+        // Row 3 is black; violence 0 and a non-positive key splat nothing.
         assert!(blood.splats(3, 2).iter().all(|p| p.contains("Black")));
         assert!(blood.splats(1, 0).is_empty());
         assert!(blood.splats(-1, 2).is_empty());
diff --git a/crates/benilla-formats/src/value_track.rs b/crates/benilla-formats/src/value_track.rs
index 69b1a5f9..b39643b5 100644
--- a/crates/benilla-formats/src/value_track.rs
+++ b/crates/benilla-formats/src/value_track.rs
@@ -1,21 +1,8 @@
-//! The keyed **M2Track sampler kernel** shared by the cosmetic-record parsers (`particles`,
-//! `ribbons`): `(timestamp ms, value)` key lists read off the vanilla 28-byte track, rebased from
-//! the global timeline onto the first sequence's band, sampled on a 0-based clip clock.
-//!
-//! **Track timestamps are the vanilla global timeline.** A sequence-timeline track
-//! (`gseq == 0xffff`) keys inside each sequence's absolute `[start, end]` band (the same law as
-//! bone keys, `models/anim.rs`) — an effect model whose seq 0 spans `[1000, 2600]` authors its
-//! impact burst at 1000 ms, *the first instant of the clip*. Keyed tracks are therefore
-//! **rebased to the first sequence's band** at parse ([`rebase_keys_to_band`]), so a runtime
-//! clock of seconds-since-spawn samples them directly. First-sequence only: the effect/doodad
-//! load-arm plays exactly that sequence; multi-sequence gating (a creature emitter keyed per gait
-//! band) has no driving model yet and stays a named seam.
-//!
-//! History: the particle emission params were once `value[0]`-baked, which silenced every keyed
-//! burst (`BloodSpurt.m2` rates its starflash `0 → 20 → 0`; decisions 0137/0140/0141). The ribbon
-//! look tracks repeated the exact trap — `HolySmite_Low_Chest.m2` keys its slash ribbons' height
-//! `0 → 0.167 → 0`, so the value[0] bake read a permanent zero and Smite's impact slash never
-//! drew. One kernel, both lanes, so the next keyed track can't be silently constant-folded.
+//! The keyed M2Track sampler shared by the particle and ribbon parsers. Sequence-timeline keys
+//! (`gseq == 0xffff`) sit in each sequence's absolute `[start, end]` band, as bone keys do: an
+//! effect whose sequence 0 spans `[1000, 2600]` bursts at 1000 ms, its first instant. Parsing
+//! rebases them onto sequence 0's band, the one an effect or doodad plays, so seconds since spawn
+//! sample them directly; a model keying an emitter per sequence is sampled on sequence 0 alone.
 
 fn le_u16(b: &[u8], o: usize) -> u16 {
     u16::from_le_bytes([b[o], b[o + 1]])
@@ -24,10 +11,9 @@ fn le_u32(b: &[u8], o: usize) -> u32 {
     u32::from_le_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]])
 }
 
-/// A value the keyed-track sampler can hold and lerp — `f32` scalars (emission rate, ribbon
-/// alpha/heights) and `[f32; 3]` triples (the ribbon colour track's C3Vector).
+/// A value a track can hold and lerp: `f32` scalars and the ribbon colour track's `[f32; 3]`.
 pub trait TrackValue: Copy {
-    /// The empty-track fallback (defensive — the parsers always fall back to a constant key).
+    /// The empty-track value; the parsers fall back to a constant key instead.
     const ZERO: Self;
     fn lerp(a: Self, b: Self, t: f32) -> Self;
 }
@@ -46,22 +32,14 @@ impl TrackValue for [f32; 3] {
     }
 }
 
-/// A keyed M2Track, reduced to `(timestamp ms, value)` pairs — enough to sample the **burst**
-/// emitters the one-shot combat effects are authored with (0137/0140 fold-back: `BloodSpurt.m2`'s
-/// starflash + glowball emitters key their rate `0 → 200 → 0` over the first 133 ms; a `value[0]`
-/// bake reads 0 and they never emit at all). The ribbon look tracks (colour/alpha/heights) ride
-/// the same kernel — `HolySmite_Low_Chest.m2` keys its slash ribbons' height `0 → 0.167 → 0`, the
-/// same value[0]-reads-0 trap. Keys are sampled with linear interpolation, **end-clamped** — no
-/// loop wrap: every looping ambient prop in the shipped corpus authors a constant (single-key)
-/// value, so a wrap clock has no driving model yet; a persistent looping model with a keyed track
-/// would hold its last key (the documented seam).
+/// A keyed M2Track as `(timestamp ms, value)` pairs. Burst emitters key their rate
+/// (`BloodSpurt.m2` goes `0 → 200 → 0` over 133 ms), so the first key alone reads 0. No loop
+/// wrap: the last key holds, and every looping ambient prop in the shipped corpus keys a constant.
 #[derive(Debug, Clone, Default)]
 pub struct ValueTrack<V = f32> {
     /// `(timestamp ms, value)` keys, in file order (ascending timestamps).
     pub keys: Vec<(u32, V)>,
-    /// The M2Track's interpolation word (`+0x00`): 0 = STEP (`values[k0]`), else linear. The
-    /// corpus splits cleanly on it — burst emitters author 0 (the full count arms AT the key),
-    /// continuous ramps author 1 (the pour envelope lerps). [`Self::sampled_ms`] dispatches on it.
+    /// Interpolation word (`+0x00`): 0 steps (`values[k0]`), as burst emitters author, else lerps.
     pub interp: u16,
 }
 
@@ -74,19 +52,13 @@ impl<V: TrackValue> ValueTrack<V> {
         }
     }
 
-    /// The first key's value — the old `value[0]` load-time bake, kept for the constant-track
-    /// parameters and diagnostics.
+    /// The first key's value, for constant-track parameters and diagnostics.
     pub fn first(&self) -> V {
         self.keys.first().map_or(V::ZERO, |&(_, v)| v)
     }
 
-    /// STEP-sample at `ms` since clip start: the nearest-previous key's value — the first key's
-    /// before the first, the last **held** past the end. This is the interp-0 leg of the
-    /// reference sampler ([`Self::sampled_ms`] dispatches here) — a Feint plume keyed
-    /// `{0:0, 67:30}` interp 0 is *silent* until 67 ms, then 30, exactly what arms its burst
-    /// count. (The old "the rate sampler never lerps" reading died with
-    /// `part-emission-rate-animated.md`: interp≠0 tracks lerp, and the corpus authors its
-    /// continuous ramps that way.)
+    /// Step-sample at `ms` since clip start, the reference sampler's interp-0 leg: the
+    /// nearest-previous key, the first before the first, the last held past the end.
     pub fn step_ms(&self, ms: f32) -> V {
         let mut v = self.keys.first().map_or(V::ZERO, |&(_, v)| v);
         for &(t, val) in &self.keys {
@@ -99,13 +71,9 @@ impl<V: TrackValue> ValueTrack<V> {
         v
     }
 
-    /// Sample as the reference's per-frame track sampler does (`0x71af20` → `0x713d50`, wow-re
-    /// `part-emission-rate-animated.md` §2/§4, VERIFIED + emulated): STEP (`values[k0]`) when the
-    /// track's [`Self::interp`] word is 0, else LINEAR between the bracketing keys — **held** at
-    /// the last key past the end, and extrapolated **backward** (negative fraction) below the
-    /// first key (the sampler does not clamp there). Raw file values — a rate track may go
-    /// negative (`BloodSpurt.m2` emitter 0 ends at −100, and the back-extrapolation can dip
-    /// below the first key); the consumer floors at 0 exactly like the `SetEmissionRate` guard.
+    /// Sample as the reference's per-frame sampler does (`0x71af20` → `0x713d50`, lerp at
+    /// `0x71af76`): step at interp 0, else lerp, held past the last key and extrapolated backward
+    /// below the first. Raw values may go negative; the consumer floors at 0 (`SetEmissionRate`).
     pub fn sampled_ms(&self, ms: f32) -> V {
         if self.interp == 0 {
             return self.step_ms(ms);
@@ -114,8 +82,7 @@ impl<V: TrackValue> ValueTrack<V> {
         if n <= 1 {
             return self.first();
         }
-        // The bracketing pair: the segment whose start is the last key at/before `ms` — the
-        // FIRST segment below the first key (negative fraction), a hold on the last key.
+        // The segment starting at the last key at or before `ms`; below the first key, the first.
         let k = self
             .keys
             .iter()
@@ -130,9 +97,7 @@ impl<V: TrackValue> ValueTrack<V> {
         V::lerp(v0, v1, (ms - t0 as f32) / span)
     }
 
-    /// Sample at `ms` since clip start: linear between neighbouring keys, clamped to the first/last
-    /// key outside the keyed span. Raw file values — a rate track may go negative at its tail
-    /// (`BloodSpurt.m2` emitter 0 ends at −100); the consumer floors at 0.
+    /// Sample at `ms` since clip start: linear between keys, clamped outside them; values are raw.
     pub fn sample_ms(&self, ms: f32) -> V {
         let Some(&(t0, v0)) = self.keys.first() else {
             return V::ZERO;
@@ -152,27 +117,23 @@ impl<V: TrackValue> ValueTrack<V> {
 }
 
 impl ValueTrack<f32> {
-    /// The track's peak value — the "can this ever contribute" gate (a burst emitter's
-    /// `value[0]` is 0; its peak is not — same for a slash ribbon's height).
+    /// The track's peak, whether it can ever contribute (a burst's first key is 0, its peak not).
     pub fn peak(&self) -> f32 {
         self.keys.iter().fold(f32::MIN, |m, &(_, v)| m.max(v))
     }
 }
 
-/// Rebase one keyed track from the vanilla global timeline onto a sequence's `[start, end]` band
-/// (clip-relative ms): in-band keys shift by `−start`; of the keys at/before `start` only the
-/// last survives, collapsed to `t = 0` (it IS the value the band starts on, per the
-/// nearest-previous sampling law); of the keys at/after `end` only the first survives, clamped
-/// to `t = end − start` (the value the band ends on). Matches the reference sampling a track
-/// with the sequence clock, expressed on a 0-based clip clock.
+/// Rebase a track from the global timeline onto a sequence's `[start, end]` band: in-band keys
+/// shift by `-start`, the last key at or before `start` becomes `t = 0`, and the first at or
+/// after `end` closes the band at `end - start`.
 pub(crate) fn rebase_keys_to_band<V: Copy>(keys: &mut Vec<(u32, V)>, start: u32, end: u32) {
     if keys.is_empty() || (start == 0 && keys.last().is_some_and(|&(t, _)| t <= end)) {
-        return; // already 0-based in-band — the common ambient-prop shape
+        return; // already 0-based and in band, the common ambient-prop shape
     }
     let mut out: Vec<(u32, V)> = Vec::with_capacity(keys.len());
     for &(t, v) in keys.iter() {
         if t <= start {
-            // Collapse everything at/before the band start to the t=0 key (last one wins).
+            // Collapse everything at or before the band start to the t=0 key (last one wins).
             match out.first_mut() {
                 Some(first) if first.0 == 0 => *first = (0, v),
                 _ => out.insert(0, (0, v)),
@@ -187,9 +148,7 @@ pub(crate) fn rebase_keys_to_band<V: Copy>(keys: &mut Vec<(u32, V)>, start: u32,
     *keys = out;
 }
 
-/// The **first sequence's absolute time band** (sequences @ `0x1c/0x20`, stride `0x44`, start @
-/// +4 / end @ +8 — the same walk as `models/anim.rs`): the window keyed tracks are rebased onto.
-/// A sequence-less model keeps raw timestamps (band = whole timeline).
+/// The first sequence's absolute time band; a sequence-less model gets the whole timeline.
 pub(crate) fn seq0_band(bytes: &[u8]) -> (u32, u32) {
     let (n_seq, o_seq) = (le_u32(bytes, 0x1c) as usize, le_u32(bytes, 0x20) as usize);
     if n_seq > 0 && o_seq + 0x44 <= bytes.len() {
@@ -199,8 +158,7 @@ pub(crate) fn seq0_band(bytes: &[u8]) -> (u32, u32) {
     }
 }
 
-/// A vanilla M2Track's key sub-arrays: `(gseq, n, timestamps offset, values offset)` — `None` if
-/// the track is out of range or keyless.
+/// A vanilla M2Track's `(gseq, n, timestamps offset, values offset)`.
 fn track_arrays(b: &[u8], track: usize) -> Option<(u16, usize, usize, usize)> {
     if track + 0x1c > b.len() {
         return None;
@@ -214,11 +172,8 @@ fn track_arrays(b: &[u8], track: usize) -> Option<(u16, usize, usize, usize)> {
     (n > 0 && tofs + n * 4 <= b.len()).then_some((gseq, n, tofs, vofs))
 }
 
-/// Read a vanilla M2Track's full `(timestamp ms, value)` key list: timestamps `{count @ +0x0c,
-/// offset @ +0x10}` zipped with values `{count @ +0x14, offset @ +0x18}` (paired up to the
-/// shorter count — equal in well-formed files), each value `elem` bytes decoded by `read`.
-/// Sequence-timeline keys are rebased to `band` (module doc; a global-sequence-tagged track keeps
-/// its own free clock and is left as-is). Empty/out-of-range → a constant track at `default`.
+/// Read an M2Track's keys, `elem`-byte values decoded by `read`; sequence keys are rebased to
+/// `band`, global-sequence ones keep their clock, and an empty or truncated track is `default`.
 pub(crate) fn track_keys_with<V: TrackValue>(
     b: &[u8],
     track: usize,
@@ -249,8 +204,6 @@ pub(crate) fn track_keys_with<V: TrackValue>(
 mod tests {
     use super::*;
 
-    /// The sampling law: linear between keys, end-clamped, raw values (negatives pass through —
-    /// the consumer floors).
     #[test]
     fn value_track_samples_linear_and_clamps() {
         let t = ValueTrack {
@@ -271,8 +224,6 @@ mod tests {
         assert_eq!(ValueTrack::<f32>::default().sample_ms(10.0), 0.0);
     }
 
-    /// The step law: nearest-previous key, first value before the first, held past the last —
-    /// the emission-rate sampler (`values[k0]`, no lerp).
     #[test]
     fn step_sampling_holds_nearest_previous() {
         let t = ValueTrack {
@@ -290,9 +241,6 @@ mod tests {
         assert_eq!(ValueTrack::<f32>::default().step_ms(10.0), 0.0);
     }
 
-    /// The reference sampler law ([`ValueTrack::sampled_ms`]): interp 0 steps, interp 1 lerps
-    /// with hold-last and BACKWARD extrapolation below the first key (no clamp there — the
-    /// `0x713d50` negative-fraction edge; the rate consumer's `> 0` floor absorbs the dip).
     #[test]
     fn sampled_ms_dispatches_on_the_interp_word() {
         let step = ValueTrack {
@@ -322,7 +270,6 @@ mod tests {
         assert_eq!(single.sampled_ms(500.0), 40.0, "single key holds");
     }
 
-    /// The vec3 instantiation (the ribbon colour track): per-channel lerp, same clamp law.
     #[test]
     fn vec3_track_lerps_per_channel() {
         let t = ValueTrack {
@@ -337,9 +284,6 @@ mod tests {
         assert_eq!(t.sample_ms(500.0), [0.0, 1.0, 0.5]);
     }
 
-    /// The band rebase: keys before the band collapse to their last value at t=0, in-band keys
-    /// shift, keys past the end clamp to the band length, and an already-0-based track is
-    /// untouched.
     #[test]
     fn band_rebase_collapses_and_shifts() {
         // MoltenBlast_Impact_Chest em0's shape: seq band [1000, 2600], burst keyed at its start.
diff --git a/crates/benilla-formats/src/vocal_ui_sounds.rs b/crates/benilla-formats/src/vocal_ui_sounds.rs
index 4426aba1..f05fb54d 100644
--- a/crates/benilla-formats/src/vocal_ui_sounds.rs
+++ b/crates/benilla-formats/src/vocal_ui_sounds.rs
@@ -1,37 +1,12 @@
-//! `VocalUISounds.dbc` — the **error speech** lines: the "I can't do that" family your character
-//! says aloud in their own race and gender voice when the client refuses something (decision 1815).
+//! `VocalUISounds.dbc`, the error speech a character says in its own race and sex voice when the
+//! client refuses something. One row per `(race, line)`, the line being the message catalog's
+//! `type_tag` (the record's `+0x0c`), so a refusal reaching `CGGameUI::DisplayError` names it.
 //!
-//! One row per `(race, line)`; the *line* is the message catalog's own `type_tag`
-//! ([`benilla_ui::messages::MessageRecord::type_tag`], the record's `+0x0c`), so a refusal that
-//! reaches `CGGameUI::DisplayError` already names its voice line. Its `0x44` value is the "no
-//! speech, play the named cue instead" sentinel — which is exactly the table's width, and exactly
-//! one past the shipped file's largest `VocalUIEnum` (67).
-//!
-//! Layout — VERIFIED against build 5875 (`WoW/Data/patch.MPQ`, decoded 2026-09-01): the WDBC header
-//! reports **533 records · 7 fields · 28 B/record**, matching the `imul ebx,ebx,0x1c` stride the
-//! reference's table builder walks with (`0x45813d`). Fields, read off that builder's own loads:
-//!
-//! | field | offset | what | where the reference reads it |
-//! |---|---|---|---|
-//! | 0 | `+0x00` | `ID` | — |
-//! | 1 | `+0x04` | [`VocalUiSound::line`] (`VocalUIEnum`), kept only when `< 0x44` | `0x45815c`/`0x45815f` |
-//! | 2 | `+0x08` | [`VocalUiSound::race`] | `0x45816b` (equality against the player's race) |
-//! | 3 | `+0x0c` | [`VocalUiSound::normal`]`[0]` — male | `0x458173` → `[0xb06240 + line*12]` |
-//! | 4 | `+0x10` | [`VocalUiSound::normal`]`[1]` — female | `0x458180` → `[0xb06570 + line*12]` |
-//! | 5 | `+0x14` | [`VocalUiSound::pissed`]`[0]` — male | `0x458190` → `[0xb06244 + line*12]` |
-//! | 6 | `+0x18` | [`VocalUiSound::pissed`]`[1]` — female | `0x4581a3` → `[0xb06574 + line*12]` |
-//!
-//! The sex grouping is the load-bearing half of that decode and it is doubly confirmed: the two
-//! sex blocks sit `0x330` = `0x44 * 12` bytes apart, and the shipped data's own kit **names** agree
-//! row for row — line 0 resolves `HumanMale_InventoryFull` / `HumanFemale_InventoryFull`, and
-//! message id 0 (`ERR_INV_FULL`) carries `type_tag` 0.
-//!
-//! **A sound id here can be `0` or `0xFFFF_FFFF`, and both mean "nothing".** The reference stores
-//! the raw field and lets its id-indexed kit lookup (`0x45cda0`: `cmp ecx,count; jae → NULL`) turn
-//! both into a miss — `-1` unsigned is past the count, and slot 0 of the table is empty because
-//! `SoundEntries` has no id 0. 190 of the file's 1 066 normal ids are `-1` and 8 are `0`; a
-//! `(race, sex, line)` with no kit is simply silent. [`VocalUiSound::normal_kit`] is that filter,
-//! written once so no consumer re-derives it.
+//! Layout: 7 `u32` fields in 28-byte records (the builder `0x45813d` strides `0x1c`): `ID`, the
+//! line (`0x45815c`), the race (`0x45816b`), the male and female kits (`0x458173`, `0x458180`, to
+//! `[0xb06240 + line*12]` and `[0xb06570 + line*12]`), then the annoyed pair (`0x458190`,
+//! `0x4581a3`, to `[0xb06244 + line*12]` and `[0xb06574 + line*12]`). A kit id of `0` or
+//! `0xFFFF_FFFF` misses in the kit lookup (`0x45cda0`), so that line is silent.
 
 use crate::Chain;
 use anyhow::{Context, Result};
@@ -41,40 +16,33 @@ use crate::dbc::{parse, u32_at};
 
 const VOCAL_UI_SOUNDS: &str = "DBFilesClient\\VocalUISounds.dbc";
 
-/// How many error-speech lines the reference's table holds — `0x44`, the bound its builder
-/// (`0x45815f cmp eax,0x44; jge`) and its player (`0x45829c cmp edi,0x44; jge`) both test, and the
-/// width of each of the two sex blocks. Also the message catalog's "no speech" sentinel: a
-/// `type_tag` of exactly `0x44` means *play the record's named cue instead*.
+/// The reference table's line count, the bound its builder (`0x45815f`) and player (`0x45829c`)
+/// test. A `type_tag` of exactly `0x44` means no speech: play the record's named cue instead.
 pub const VOCAL_UI_LINES: usize = 0x44;
 
-/// One `VocalUISounds.dbc` row — the kits one race says one line with, per sex.
+/// One `VocalUISounds.dbc` row: the kits one race says one line with, per sex.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct VocalUiSound {
     pub id: u32,
-    /// `VocalUIEnum` — the message catalog's `type_tag`. Always `< VOCAL_UI_LINES` in a row this
-    /// loader kept; the reference drops the others at table-build time and so do we.
+    /// `VocalUIEnum`, the message catalog's `type_tag`; the builder drops `VOCAL_UI_LINES` and up.
     pub line: u32,
     /// `ChrRaces` id (the descriptor's `UNIT_FIELD_BYTES_0` race byte).
     pub race: u32,
     /// The line's ordinary delivery, by sex (`0` male, `1` female). `0`/`-1` = none.
     pub normal: [u32; 2],
-    /// The **annoyed** delivery, by sex — what the reference escalates to after four consecutive
-    /// plays of the same line. Every one of the shipped file's 1 066 ids is absent from
-    /// `SoundEntries.dbc`, so this column is **dormant in 5875's data**; it is carried because the
-    /// mechanism reads it, not because anything can be heard from it.
+    /// The annoyed delivery by sex, played after four consecutive plays of the same line; no
+    /// shipped id is in `SoundEntries.dbc`, so it is never heard in 5875.
     pub pissed: [u32; 2],
 }
 
 impl VocalUiSound {
-    /// The kit for this row's ordinary line at `sex`, with the reference's own two misses folded
-    /// in (`0` and `-1` both resolve to no kit — module doc). `sex` past 1 is `None`: the
-    /// reference refuses those at its own front door (`0x458254`/`0x45825b`).
+    /// The ordinary line's kit at `sex`, `0` and `-1` folded to none. The reference refuses a
+    /// `sex` past 1 at its entry (`0x458254`/`0x45825b`).
     pub fn normal_kit(&self, sex: u32) -> Option<u32> {
         kit(self.normal, sex)
     }
 
-    /// The annoyed line's kit at `sex` — [`Self::normal_kit`]'s twin (and, on 5875's data, always
-    /// a kit that resolves to nothing; see [`Self::pissed`]).
+    /// The annoyed line's kit at `sex`, folded the same way.
     pub fn pissed_kit(&self, sex: u32) -> Option<u32> {
         kit(self.pissed, sex)
     }
@@ -85,17 +53,14 @@ fn kit(pair: [u32; 2], sex: u32) -> Option<u32> {
     (id != 0 && id != u32::MAX).then_some(id)
 }
 
-/// The whole table, as rows. Consumers build the reference's per-race lookup from it
-/// (`benilla_app::sound::vocal`); this crate stays the file's reader and nothing more.
+/// The whole table as rows, from which consumers build the reference's per-race lookup.
 pub struct VocalUiSoundCatalog {
     rows: Vec<VocalUiSound>,
 }
 
 impl VocalUiSoundCatalog {
-    /// Every kept row, in **file order** — which matters: the reference builds its table by
-    /// walking the file *backwards* (`0x458140`), so on a duplicate `(race, line)` the
-    /// lowest-indexed row is the one left standing. A consumer that folds these in order gets the
-    /// same answer. (5875's file has no duplicate pair, so this is a rule with no live case.)
+    /// Every kept row in file order. The reference builds its table walking the file backwards
+    /// (`0x458140`), so on a duplicate `(race, line)` the lowest-indexed row wins.
     pub fn rows(&self) -> &[VocalUiSound] {
         &self.rows
     }
@@ -144,10 +109,6 @@ pub fn load_vocal_ui_sounds(chain: &mut Chain) -> Result<VocalUiSoundCatalog> {
 mod tests {
     use super::*;
 
-    /// The real 5875 file, and the facts the decode rests on: its shape, its `VocalUIEnum` domain
-    /// (dense `0..=67`, one short of the sentinel), and the **sex column order** — read back
-    /// through `SoundEntries` names, which is the check that would have caught a transposed pair.
-    /// Skips without client data.
     #[test]
     fn real_vocal_ui_sounds_decode_with_the_sexes_the_right_way_round() {
         let data = crate::wow_data_or_skip!();
@@ -160,8 +121,7 @@ mod tests {
         assert_eq!(lines.iter().copied().max(), Some(67));
         assert_eq!(lines.len(), VOCAL_UI_LINES, "the enum is dense 0..=0x43");
 
-        // Human (race 1), line 0 = the message catalog's `ERR_INV_FULL` tag. Male and female must
-        // land on their own voices — the whole point of the `+0x0c`/`+0x10` pair.
+        // Human (race 1), line 0, the message catalog's `ERR_INV_FULL` tag.
         let human_inv_full = cat
             .rows()
             .iter()
@@ -186,7 +146,6 @@ mod tests {
             "sex past 1 has no voice"
         );
 
-        // The naming law holds across races and lines, so a column slip anywhere shows up here.
         for (race, prefix) in [(3u32, "Dwarf"), (6, "Tauren"), (8, "Troll")] {
             let row = cat
                 .rows()
@@ -204,11 +163,6 @@ mod tests {
         }
     }
 
-    /// **The annoyed column is dormant in 5875** — every one of its ids is absent from
-    /// `SoundEntries.dbc`, so the reference's escalation has nothing to escalate *to* and the
-    /// ordinary line plays every time. Asserted rather than assumed, because the play state
-    /// machine's whole observable behaviour turns on it (`benilla_app::sound::vocal`). Skips
-    /// without client data.
     #[test]
     fn the_annoyed_column_resolves_to_nothing_in_this_build() {
         let data = crate::wow_data_or_skip!();
@@ -226,8 +180,7 @@ mod tests {
             live, 0,
             "an annoyed line resolved — 1815's dormancy is over"
         );
-        // The control: the ordinary column is mostly live, so the sweep above is testing the data
-        // and not a broken lookup.
+        // The control: the ordinary column is mostly live, so the sweep above tests the data.
         let normal_live = cat
             .rows()
             .iter()
diff --git a/crates/benilla-formats/src/wdl.rs b/crates/benilla-formats/src/wdl.rs
index 602f0d47..fc50afe3 100644
--- a/crates/benilla-formats/src/wdl.rs
+++ b/crates/benilla-formats/src/wdl.rs
@@ -1,18 +1,10 @@
-//! WDL (low-detail distant terrain) loader + coarse mesher.
+//! WDL, the low-detail distant terrain: loader and coarse mesher. One `.wdl` per map holds the
+//! whole 64×64-tile world at one height per MCNK, the horizon the reference draws beyond the
+//! streamed tiles out to `horizonfarclip`, unlit, untextured, vertex-white and fogged.
 //!
-//! One `.wdl` per map holds the **whole 64×64-tile world** at a single height sample per MCNK — the
-//! horizon geometry the reference draws BEYOND the streamed high-detail tiles (out to `horizonfarclip`),
-//! unlit + untextured + vertex-white + fogged into the haze. RE'd from apitrace WoW.8 + the real file.
-//!
-//! Layout — VERIFIED against `World\Maps\Azeroth\Azeroth.wdl` (770730 B, 2026-05-30):
-//!   `MVER` (version **18**) · `MAOF` (4096 `u32` tile offsets, `[tile_y][tile_x]`) · per present tile
-//!   `MARE` (1090 B = 17×17 outer + 16×16 inner `int16` absolute heights, yards). No `MWMO`/`MWID`/
-//!   `MODF`, no `MAHO` in vanilla Azeroth (low-detail WMOs + holes are out of scope for v1).
-//!
-//! The mesh is in **raw WoW world coords** (X north, Y west, Z up, yards) like [`crate::terrain`], with
-//! the same per-cell 4-tri **center-fan** — but at `CHUNK_SIZE` (one MCNK) spacing instead of
-//! `UNIT_SIZE`, so one WDL tile = a single MCNK's topology scaled ×16 (545 verts / 3072 indices, the
-//! exact draw the apitrace shows). The renderer applies the WoW→Bevy transform.
+//! Layout: `MVER` (version 18), `MAOF` (4096 `u32` tile offsets, `[tile_y][tile_x]`), then per
+//! present tile a `MARE` of 17×17 outer and 16×16 inner `int16` heights; vanilla Azeroth has no
+//! `MWMO`/`MWID`/`MODF` or `MAHO`. The mesh is raw WoW world coordinates (X north, Y west, Z up).
 
 use std::io::{Cursor, Read, Seek, SeekFrom};
 
@@ -21,35 +13,31 @@ use anyhow::{bail, Context, Result};
 
 use crate::terrain::TILE_SIZE;
 
-/// One MCNK's worth of horizon detail: 16 cells per tile edge, so the outer grid is 17×17 corners and
-/// the inner grid is 16×16 cell centers — identical to an MCNK but at tile scale.
+/// 16 cells a tile edge: 17×17 corners and 16×16 cell centres, an MCNK's grid at tile scale.
 const OUTER_EDGE: usize = 17;
 const INNER_EDGE: usize = 16;
-const OUTER_N: usize = OUTER_EDGE * OUTER_EDGE; // 289
-const INNER_N: usize = INNER_EDGE * INNER_EDGE; // 256
-/// MARE body = (289 + 256) `int16` = 1090 bytes (VERIFIED).
+const OUTER_N: usize = OUTER_EDGE * OUTER_EDGE;
+const INNER_N: usize = INNER_EDGE * INNER_EDGE;
 const MARE_BYTES: usize = (OUTER_N + INNER_N) * 2;
-/// One MCNK edge in yards (the WDL outer-grid spacing). `TILE_SIZE / 16`.
 const CHUNK_SIZE: f32 = TILE_SIZE / 16.0;
-/// World coord of tile (0,0)'s origin (max-X, max-Y) corner — the 64-tile map is centred on the origin.
+/// World coordinate of tile (0, 0)'s max-X, max-Y corner; the 64-tile map is centred on the origin.
 const MAP_OFFSET: f64 = 32.0 * (TILE_SIZE as f64);
 
 /// A map's parsed WDL: the present tiles' low-detail heightmaps, indexed by MAOF position.
 pub struct WdlFile {
-    /// 64×64, indexed `[tile_y * 64 + tile_x]` (the on-disk MAOF order); `None` where the map has no
-    /// tile. `tile_x`/`tile_y` match `Map_<tile_x>_<tile_y>.adt` and `benilla_wdt::world_to_tile`.
+    /// 64×64 in MAOF order, `[tile_y * 64 + tile_x]`, with `tile_x`/`tile_y` as in
+    /// `Map_<tile_x>_<tile_y>.adt` and `benilla_wdt::world_to_tile`; `None` where the map has none.
     tiles: Vec<Option<MareTile>>,
 }
 
-/// One tile's low-detail heightmap: 17×17 outer (corner) then 16×16 inner (cell-center) `int16`
-/// heights, in yards (absolute world Z). Both grids are row-major.
+/// One tile's absolute heights in yards: 17×17 corners, then 16×16 cell centres, row-major.
 struct MareTile {
     outer: [i16; OUTER_N],
     inner: [i16; INNER_N],
 }
 
-/// A coarse WDL tile mesh in raw WoW world coords: positions + a 4-tri-per-cell center-fan index
-/// buffer. No normals (unlit) and no UVs (untextured) — the reference draws this vertex-white + fogged.
+/// A coarse WDL tile mesh in raw WoW world coordinates, with no normals or UVs: the reference
+/// draws it unlit, vertex-white and fogged.
 pub struct WdlTileMesh {
     /// 545 verts: 289 outer (`[r*17+c]`) then 256 inner (`[289 + r*16+c]`).
     pub positions: Vec<[f32; 3]>,
@@ -57,8 +45,7 @@ pub struct WdlTileMesh {
     pub indices: Vec<u32>,
 }
 
-/// MAOF/tiles index for tile `(tile_x, tile_y)`. Row-major over `tile_y` (the on-disk `[y][x]` order),
-/// matching `benilla_wdt`'s tile addressing so the WDL present-set lines up with the WDT's.
+/// The MAOF index of a tile, row-major over `tile_y` as on disk and in `benilla_wdt`.
 fn tile_index(tile_x: u32, tile_y: u32) -> usize {
     tile_y as usize * 64 + tile_x as usize
 }
@@ -88,20 +75,10 @@ impl WdlFile {
         (0..4096u32).filter_map(move |i| self.tiles[i as usize].as_ref().map(|_| (i % 64, i / 64)))
     }
 
-    /// Present WDL tiles forming a Chebyshev **window** around a world `(x, y)`: every present tile
-    /// within `radius` tiles, **the centre one included** — the reference's far walk (`0x683040`)
-    /// visits a camera-centred ±3-tile window of the distant grid with no exclusion, and so must ours.
-    ///
-    /// There used to be a `skip_inner` parameter, and the renderer passed 0 — dropping the camera's
-    /// OWN tile, on the reasoning that a 533 yd tile sits entirely inside the far-clip wall and would
-    /// be discarded anyway. That holds only near the default `farclip` of 777. **Drop the view
-    /// distance below a tile — the vanilla range reaches down to 177 — and most of the camera's own
-    /// tile lies BEYOND the wall, where it is the only thing that can draw the near horizon.** Its
-    /// absence is then a gap between the detailed terrain and the distant hills, right above the
-    /// horizon line, through which the sky pours (decision 0684 — the director's Weazel's Crater
-    /// report at view distance 320). The parameter is gone rather than defaulted so the hole cannot
-    /// come back: what bounds the band on the near side is the far band's near plane in `wdl.wgsl`,
-    /// and nothing else.
+    /// Present tiles within a Chebyshev `radius` of world `(x, y)`, the centre tile included, as
+    /// the reference's far walk (`0x683040`) visits a ±3-tile window. Below a tile of view distance
+    /// (vanilla goes down to 177) the camera's own tile draws the near horizon, and without it sky
+    /// shows through; the far band's near plane in `wdl.wgsl` alone bounds that side.
     pub fn tiles_in_ring(&self, world_x: f32, world_y: f32, radius: u32) -> Vec<(u32, u32)> {
         let (cx, cy) = benilla_wdt::world_to_tile(world_x, world_y);
         let r = radius as i32;
@@ -120,21 +97,18 @@ impl WdlFile {
         out
     }
 
-    /// Build the coarse center-fan mesh for tile `(tile_x, tile_y)`, or `None` if it's absent.
-    ///
-    /// Vertex X/Y are derived from the **global** lattice index (`tile·16 + local`) computed in `f64`,
-    /// so a shared edge between adjacent WDL tiles is bit-identical → watertight, no hairline seam.
+    /// The coarse centre-fan mesh of tile `(tile_x, tile_y)`. Vertex X/Y come from the global
+    /// lattice index in `f64`, so neighbouring tiles share bit-identical edges.
     pub fn tile_mesh(&self, tile_x: u32, tile_y: u32) -> Option<WdlTileMesh> {
         if tile_x >= 64 || tile_y >= 64 {
             return None;
         }
         let tile = self.tiles[tile_index(tile_x, tile_y)].as_ref()?;
         let cs = CHUNK_SIZE as f64;
-        // Lattice position for a global row/col index (X north decreases with row, Y west with col).
+        // Lattice position of a global row/col index (X north falls with row, Y west with col).
         let lat = |global: f64| (MAP_OFFSET - global * cs) as f32;
 
         let mut positions = Vec::with_capacity(OUTER_N + INNER_N);
-        // Outer 17×17 corners.
         for r in 0..OUTER_EDGE {
             for c in 0..OUTER_EDGE {
                 positions.push([
@@ -144,7 +118,6 @@ impl WdlFile {
                 ]);
             }
         }
-        // Inner 16×16 cell centers (+½ cell in both planar axes).
         for r in 0..INNER_EDGE {
             for c in 0..INNER_EDGE {
                 positions.push([
@@ -155,9 +128,8 @@ impl WdlFile {
             }
         }
 
-        // 4-triangle center-fan per cell, mirroring terrain.rs's winding (CCW from above → front-face
-        // up under the det-+1 WoW→Bevy transform). For cell (r, c) ∈ 0..16²:
-        //   TL=outer(r,c)  TR=outer(r,c+1)  BL=outer(r+1,c)  BR=outer(r+1,c+1)  CTR=inner(r,c)
+        // Four-triangle centre fan per cell, wound CCW from above like the terrain so it faces up
+        // after the WoW-to-Bevy transform.
         let inner_base = OUTER_N as u32;
         let mut indices = Vec::with_capacity(INNER_EDGE * INNER_EDGE * 12);
         for r in 0..INNER_EDGE as u32 {
@@ -178,15 +150,11 @@ impl WdlFile {
         Some(WdlTileMesh { positions, indices })
     }
 
-    /// The drawn WDL surface height (absolute WoW `z`) under world `(x, y)` — interpolated over the
-    /// SAME 4-triangle center-fan [`Self::tile_mesh`] builds, so a query agrees exactly with the
-    /// rendered horizon silhouette (`height_at` at a mesh vertex's `x, y` returns that vertex's
-    /// `z`). `None` where the map has no WDL tile. The far leg of the lens-flare occlusion march
-    /// (benilla `sun::follow`), beyond the detailed-terrain ring.
+    /// The drawn WDL height (absolute WoW `z`) under world `(x, y)`, interpolated over the same
+    /// centre fan [`Self::tile_mesh`] builds, so it matches the rendered horizon exactly.
     pub fn height_at(&self, world_x: f32, world_y: f32) -> Option<f32> {
         let cs = CHUNK_SIZE as f64;
-        // Global lattice coords — the inverse of `tile_mesh`'s `lat`: row grows along −X (north →
-        // south), col along −Y. 64 tiles × 16 cells = 1024 cells per axis.
+        // Global lattice coordinates, the inverse of `tile_mesh`'s `lat`: 1024 cells per axis.
         let gr = (MAP_OFFSET - f64::from(world_x)) / cs;
         let gc = (MAP_OFFSET - f64::from(world_y)) / cs;
         if !(0.0..1024.0).contains(&gr) || !(0.0..1024.0).contains(&gc) {
@@ -195,15 +163,11 @@ impl WdlFile {
         let (cell_r, cell_c) = (gr as usize, gc as usize);
         let tile = self.tiles[tile_index((cell_c / 16) as u32, (cell_r / 16) as u32)].as_ref()?;
         let (r, c) = (cell_r % 16, cell_c % 16);
-        // The cell's corner + center heights (outer 17×17, inner 16×16 — same addressing as the mesh).
         let h = |rr: usize, cc: usize| f64::from(tile.outer[rr * OUTER_EDGE + cc]);
         let (tl, tr) = (h(r, c), h(r, c + 1));
         let (bl, br) = (h(r + 1, c), h(r + 1, c + 1));
         let ctr = f64::from(tile.inner[r * INNER_EDGE + c]);
-        // Fractional position inside the cell: `v` down the rows (toward BL), `u` across the cols
-        // (toward TR). The center-fan splits the cell into 4 triangles meeting at (0.5, 0.5); pick
-        // the fan by which quadrant-diagonal region holds (u, v), then interpolate linearly along
-        // the outer edge and blend toward the center — the exact plane of that fan triangle.
+        // `v` runs down the rows, `u` across; the cell's diagonals pick the fan triangle.
         let (v, u) = (gr - cell_r as f64, gc - cell_c as f64);
         let (a, b, t, s) = if v <= u && v <= 1.0 - u {
             (tl, tr, u, v) // north fan (CTR, TR, TL): edge TL→TR at v = 0
@@ -214,10 +178,7 @@ impl WdlFile {
         } else {
             (tr, br, v, 1.0 - u) // east fan: edge TR→BR at u = 1
         };
-        // On the fan's plane: at edge distance `s` ∈ [0, 0.5] between the outer edge (s = 0) and the
-        // center (s = 0.5), the edge lerp `a→b` at parameter `t` blends toward CTR. The edge-parallel
-        // coordinate compresses toward the apex: lerp param `(t − s) / (1 − 2s)` spans the shrinking
-        // cross-section (degenerate only exactly at the apex, where the height is CTR).
+        // `s` runs 0 at the outer edge to 0.5 at the centre, where the edge parameter degenerates.
         let height = if s >= 0.5 {
             ctr
         } else {
@@ -228,12 +189,11 @@ impl WdlFile {
     }
 }
 
-/// Read one IFF chunk header: 4-byte magic (stored reversed on disk) + `u32` LE size. Returns the
-/// de-reversed magic (e.g. `b"MARE"`) and the body size.
+/// Read one IFF chunk header: the magic, stored reversed on disk, and the `u32` LE body size.
 fn read_chunk_header(cur: &mut Cursor<&[u8]>) -> Result<([u8; 4], u32)> {
     let mut magic = [0u8; 4];
     cur.read_exact(&mut magic)?;
-    magic.reverse(); // on-disk is little-endian fourCC, i.e. reversed
+    magic.reverse();
     let mut size = [0u8; 4];
     cur.read_exact(&mut size)?;
     Ok((magic, u32::from_le_bytes(size)))
@@ -242,7 +202,6 @@ fn read_chunk_header(cur: &mut Cursor<&[u8]>) -> Result<([u8; 4], u32)> {
 fn parse_wdl(bytes: &[u8]) -> Result<WdlFile> {
     let mut cur = Cursor::new(bytes);
 
-    // MVER (version 18 in vanilla).
     let (magic, size) = read_chunk_header(&mut cur)?;
     if &magic != b"MVER" {
         bail!("expected MVER first, got {:?}", magic);
@@ -255,7 +214,7 @@ fn parse_wdl(bytes: &[u8]) -> Result<WdlFile> {
     }
     cur.seek(SeekFrom::Current(size as i64 - 4))?; // skip any MVER tail (none in vanilla)
 
-    // Skip any optional low-detail-WMO chunks (MWMO/MWID/MODF — absent in vanilla Azeroth) until MAOF.
+    // Skip to MAOF past any low-detail WMO chunks.
     let offsets = loop {
         let (magic, size) = read_chunk_header(&mut cur)?;
         if &magic == b"MAOF" {
@@ -310,7 +269,7 @@ mod tests {
 
     #[test]
     fn tile_index_is_row_major_over_y() {
-        // The apitrace WDL tile was (tile_x=34, tile_y=48) -> 48*64+34.
+        // A tile from a trace of the reference: (tile_x=34, tile_y=48) -> 48*64+34.
         assert_eq!(tile_index(34, 48), 48 * 64 + 34);
         assert_eq!(tile_index(0, 0), 0);
         assert_eq!(tile_index(63, 63), 4095);
@@ -322,17 +281,13 @@ mod tests {
         assert_eq!(INNER_N, 256);
         assert_eq!(MARE_BYTES, 1090);
         assert_eq!(OUTER_N + INNER_N, 545); // verts per tile
-                                            // 16×16 cells × 4 tris × 3 indices = 3072 (the apitrace draw count).
+                                            // 16×16 cells × 4 tris × 3: the reference's draw count.
         assert_eq!(INNER_EDGE * INNER_EDGE * 12, 3072);
-        // One WDL cell spans one MCNK.
         assert!((CHUNK_SIZE - TILE_SIZE / 16.0).abs() < 1e-3);
     }
 
-    /// `height_at` must agree with the RENDERED surface — sample it at every `tile_mesh` vertex
-    /// position (outer corners + inner fan centers) of a synthetic bumpy tile and require the
-    /// vertex's own height back. Skips the tile's south/east boundary lattice lines (those verts
-    /// belong to the absent neighbour tile in this synthetic file; real MARE data duplicates
-    /// shared edges).
+    /// The tile's last corner row and column belong to the absent neighbour tile in this synthetic
+    /// file, so they are skipped.
     #[test]
     fn height_at_matches_the_drawn_mesh_exactly() {
         let mut tiles: Vec<Option<MareTile>> = (0..4096).map(|_| None).collect();
@@ -364,7 +319,6 @@ mod tests {
                 p[2]
             );
         }
-        // Unauthored tile → None (never "ground at 0").
         assert_eq!(wdl.height_at(0.0, 0.0), None);
     }
 }
diff --git a/crates/benilla-formats/src/weapon_impact.rs b/crates/benilla-formats/src/weapon_impact.rs
index e129ce97..a74ec2d3 100644
--- a/crates/benilla-formats/src/weapon_impact.rs
+++ b/crates/benilla-formats/src/weapon_impact.rs
@@ -1,28 +1,7 @@
-//! `WeaponImpactSounds.dbc` — the melee impact kit table (decision 0075).
-//!
-//! Layout — VERIFIED against build 5875 (header + full row dump with SoundEntries name joins,
-//! 2026-07-03): **30 × 23 × 92 B**: `ID(0), WeaponSubClassID(1), Metal(2),
-//! ImpactSound[10](3..12), CritImpactSound[10](13..22)`. Column 2 is the weapon's own material
-//! variant (subclasses appear twice — e.g. `Mace1H_*` at 0 vs `Mace1HMetal_*` at 1 — and it
-//! selects the parry family: metal weapons carry `*ParryMetal*` kits). The ten slots, pinned by
-//! the kit names on rows 1–3 (`Axe1H_ArmorFlesh`, `Shield Metal Impact`,
-//! `1hParryMetalHitMetal`, `Axe1H_HitStone`, `Ethereal_1H`…):
-//!
-//! | slot | target |
-//! |---|---|
-//! | 0 | flesh (`*_ArmorFlesh`) |
-//! | 1 | chain armor |
-//! | 2 | plate armor |
-//! | 3 | shield, metal (block) |
-//! | 4 | shield, wood (block) |
-//! | 5 | parry vs a metal weapon |
-//! | 6 | parry vs a wood weapon |
-//! | 7 | wood creature (`CreatureImpactType` 2) |
-//! | 8 | stone creature (`CreatureImpactType` 1) |
-//! | 9 | ethereal creature (`CreatureImpactType` 3) |
-//!
-//! The runtime mirror is the client's `AUIMPACTSOUNDARRAY` (wow-re sound node: 10 per-row slots,
-//! well-known kits like `Combat_Miss_1H` cached separately at `0x4575b0`).
+//! `WeaponImpactSounds.dbc`: the melee impact sounds, ten normal and ten critical kits per weapon
+//! subclass and material (column 2; a metal weapon carries the metal parry kits), which the client
+//! reads as `AUIMPACTSOUNDARRAY` (`0x587450`). Slots 7-9 are wood, stone and ethereal creatures,
+//! `CreatureImpactType` 2, 1 and 3.
 
 use std::collections::HashMap;
 
@@ -32,7 +11,7 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 use crate::dbc::{parse, u32_at};
 use crate::Chain;
 
-/// The impact-slot indices (module docs — pinned by the 5875 kit names).
+/// The ten target slots, as the shipped kit names pin them.
 pub mod impact_slot {
     pub const FLESH: usize = 0;
     pub const CHAIN: usize = 1;
@@ -52,16 +31,14 @@ pub struct WeaponImpactRow {
     pub crit: [u32; 10],
 }
 
-/// `(WeaponSubClassID, metal)` → the impact kits. The item-weapon subclass ids (0 Axe1H,
-/// 1 Axe2H, … 7 Sword1H, 13 Fist/unarmed, 15 Dagger) all carry rows.
+/// `(WeaponSubClassID, metal)` → the impact kits.
 pub struct WeaponImpactCatalog {
     rows: HashMap<(u32, bool), WeaponImpactRow>,
 }
 
 impl WeaponImpactCatalog {
-    /// The row for a weapon subclass, preferring the given material variant and falling back to
-    /// the other (a few subclasses have only one). `None` when the subclass has no row at all
-    /// (wands, thrown — no melee impact).
+    /// The row for a subclass in the given material, else in the other, as some have only one;
+    /// wands and thrown have none.
     pub fn get(&self, subclass: u32, metal: bool) -> Option<&WeaponImpactRow> {
         self.rows
             .get(&(subclass, metal))
@@ -112,9 +89,6 @@ pub fn load_weapon_impact_catalog(chain: &mut Chain) -> Result<WeaponImpactCatal
 mod tests {
     use super::*;
 
-    /// The real 5875 table decodes to the byte-verified row 1 (Axe1H metal: flesh 171 / crit
-    /// 172, stone 3206, parry-metal 1002) and the unarmed row; the material fallback resolves a
-    /// single-variant subclass from either flag. Skips without client data.
     #[test]
     fn real_weapon_impacts_decode() {
         let data = crate::wow_data_or_skip!();
@@ -131,7 +105,7 @@ mod tests {
         let unarmed = cat.get(13, true).expect("Fist/unarmed");
         assert_ne!(unarmed.impact[impact_slot::FLESH], 0);
 
-        // Fallback: bows (2) only have a non-metal row; asking for metal still resolves.
+        // Bows (2) have only a non-metal row.
         assert!(cat.get(2, true).is_some());
     }
 }
diff --git a/crates/benilla-formats/src/weapon_swing.rs b/crates/benilla-formats/src/weapon_swing.rs
index 06b534fe..4f497ae7 100644
--- a/crates/benilla-formats/src/weapon_swing.rs
+++ b/crates/benilla-formats/src/weapon_swing.rs
@@ -1,21 +1,7 @@
-//! `WeaponSwingSounds2.dbc` — the *connecting* melee swing's whoosh, by weapon weight.
-//!
-//! The reference builds a flat six-slot cache out of this file at load
-//! (`0x45cb00`: a reverse walk over the 16-byte records writing
-//! `cache[(critical != 0) + swingType*2] = SoundEntriesID`, bounded `swingType < 3` and
-//! `critical < 2`), and the play site indexes it with exactly that arithmetic
-//! (`0x457f8d lea eax,[eax+ecx*2]`, `0x457f91 mov edx,[eax*4 + 0xb06bd4]`). This catalog is that
-//! cache, built the same way, so a file whose rows moved would still land where the reference
-//! puts them.
-//!
-//! Layout — VERIFIED against the shipped build 5875 file (6 records × 4 fields × 16 B, one-byte
-//! string block): `ID(0), SwingType(1), Critical(2), SoundEntriesID(3)`. The six rows are the
-//! full cross product, and the kits they name are `LightWeaponNormal/Critical` (233/234),
-//! `MediumWeaponNormal/Critical` (235/236) and `HeavyWeaponNormal/Critical` (237/238) — the
-//! `mWooshSmall*` / `mWooshMedium*` / `mWooshLarge*` samples.
-//!
-//! **The weight is not a heuristic**: `swingType` is `ItemSubClass.WeaponSwingSize` for the
-//! swinging weapon's `(class 2, subclass)` — see [`crate::ItemSubClassCatalog::weapon_swing_size`].
+//! `WeaponSwingSounds2.dbc`: the whoosh of a connecting melee swing. The reference loads it
+//! (`0x45cb00`) into a six-slot cache (`0xb06bd4`) at `critical + swingType * 2`, and the play site
+//! (`0x457f8d`) indexes it the same way; this catalog is that cache. `swingType` is the weapon's
+//! `ItemSubClass.WeaponSwingSize`: 0 light, 1 medium, 2 heavy.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -23,8 +9,7 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 use crate::dbc::{parse, u32_at};
 use crate::Chain;
 
-/// How many `swingType` values the reference's cache holds — `0x457f63 cmp ecx,3 / jge` bails
-/// above this, and the loader's own `cmp edi,3 / jge` refuses to write past it.
+/// The reference's `swingType` bound: the play site (`0x457f63`) and the loader both stop at 3.
 const SWING_TYPES: usize = 3;
 
 /// The six-slot swing-kit cache (`0xb06bd4`), indexed `critical + swingType*2`.
@@ -33,9 +18,7 @@ pub struct WeaponSwingCatalog {
 }
 
 impl WeaponSwingCatalog {
-    /// The kit for a swing of `swing_type` (0 light · 1 medium · 2 heavy), critical or not.
-    /// `None` above the reference's ceiling — its play site *returns without playing anything*
-    /// on `swingType >= 3`, so an out-of-range weight is silence, never a fallback to light.
+    /// The kit for a swing; the reference plays nothing for `swingType >= 3`, never a light swing.
     pub fn kit(&self, swing_type: u32, critical: bool) -> Option<u32> {
         let slot = usize::try_from(swing_type).ok()?;
         if slot >= SWING_TYPES {
@@ -64,7 +47,7 @@ pub fn load_weapon_swing_catalog(chain: &mut Chain) -> Result<WeaponSwingCatalog
     for r in rs.records() {
         let g = |i: usize| u32_at(r, i).unwrap_or(0);
         let (swing_type, critical) = (g(1), g(2));
-        // The loader's own bounds, kept verbatim: a row outside them is dropped, not clamped.
+        // The reference loader's bounds: a row outside them is dropped, not clamped.
         if swing_type as usize >= SWING_TYPES || critical >= 2 {
             continue;
         }
@@ -77,8 +60,6 @@ pub fn load_weapon_swing_catalog(chain: &mut Chain) -> Result<WeaponSwingCatalog
 mod tests {
     use super::*;
 
-    /// The shipped table: the full 3 × 2 cross product, on the six `mWoosh*` kits. Skips without
-    /// client data.
     #[test]
     fn real_weapon_swing_sounds_decode() {
         let data = crate::wow_data_or_skip!();
@@ -93,8 +74,6 @@ mod tests {
         assert_eq!(cat.kit(2, true), Some(238), "HeavyWeaponCritical");
     }
 
-    /// Above the reference's `swingType < 3` ceiling there is no sound at all — `0x457f60`
-    /// returns before touching the cache. Nothing to skip: the bound is ours, not the file's.
     #[test]
     fn a_weight_past_the_ceiling_is_silence_not_a_fallback() {
         let cat = WeaponSwingCatalog {
@@ -102,7 +81,7 @@ mod tests {
         };
         assert_eq!(cat.kit(3, false), None);
         assert_eq!(cat.kit(u32::MAX, true), None);
-        // …and a slot the file never filled reads as absent rather than kit 0.
+        // A slot the file never filled reads as absent, not as kit 0.
         let sparse = WeaponSwingCatalog {
             cache: [233, 0, 0, 0, 0, 0],
         };
diff --git a/crates/benilla-formats/src/wmo_area.rs b/crates/benilla-formats/src/wmo_area.rs
index 2af22f7b..1b1f3862 100644
--- a/crates/benilla-formats/src/wmo_area.rs
+++ b/crates/benilla-formats/src/wmo_area.rs
@@ -1,20 +1,7 @@
-//! `WMOAreaTable.dbc` — the per-building (and per-group) audio identity: what a WMO interior
-//! sounds like (decision 0075). This is where 1.12's interior soundscape actually lives: the
-//! Northshire Abbey monk chant is this table's whole-WMO row → `ZoneIntroMusicTable` 221, and
-//! ~4 000 group rows carry interior reverb/ambience (the terrain `AreaTable` path covers only
-//! open ground).
-//!
-//! Layout — VERIFIED against build 5875 (header + row/string decodes, 2026-07-03):
-//! **21115 × 20 × 80 B**: `ID(0), WMOID(1), NameSetID(2), WMOGroupID(3, −1 = whole-WMO default),
-//! SoundProviderPref(4), SoundProviderPrefUnderwater(5), AmbienceID(6), ZoneMusic(7),
-//! IntroSound(8), Flags(9), … AreaName enUS(11), … locale-mask(19)` (col 10 is another locale
-//! slot, empty in this data; enUS at 11 pinned by clean NUL-preceded string starts —
-//! "Lion's Pride Inn", "Cathedral of Light").
-//!
-//! Join keys, byte-verified against the real files: `WMOID` = the root's `MOHD.wmoID`
-//! (NSabbey.wmo → 59), `WMOGroupID` = each group file's `MOGP.uniqueID` @ 0x38 (Chapel_000 →
-//! 478), `NameSetID` = the ADT placement's `MODF.nameSet` (one abbey model serves Northshire /
-//! Tyr's Hand by name set).
+//! `WMOAreaTable.dbc`, a WMO interior's audio identity per building and per group; the Northshire
+//! Abbey chant is its whole-WMO row's `ZoneIntroMusicTable` 221. Rows key on the root's
+//! `MOHD.wmoID`, the placement's `MODF.nameSet` and each group's `MOGP.uniqueID` (`+0x38`), with
+//! `WMOGroupID` `-1` for the whole-WMO row; the enUS `AreaName` is column 11 of 20.
 
 use std::collections::HashMap;
 
@@ -24,65 +11,53 @@ use benilla_dbc::{FieldType, Schema, SchemaField};
 use crate::dbc::{parse, str_at, u32_at};
 use crate::Chain;
 
-/// One WMO area row — the audio fields (all 0 = none/inherit).
+/// One `WMOAreaTable` row's audio fields, `0` for none or inherit.
 #[derive(Clone)]
 pub struct WmoArea {
-    /// The DBC row ID (col 0) — the client's indoor **dedup key** (`[0x86860c]`,
-    /// wow-re `zonetext-indoor-bit.md` (d)): while the player stays in a WMO area with the same
-    /// row id, the zone-text updater is skipped entirely.
+    /// The row id, the client's indoor dedup key (`[0x86860c]`): while it stays the same, the
+    /// zone-text update is skipped.
     pub id: u32,
-    /// `SoundProviderPreferences` FKs, `[dry, underwater]`.
+    /// `SoundProviderPreferences` ids, `[dry, underwater]`.
     pub sound_provider: [u32; 2],
-    /// `SoundAmbience.dbc` FK.
+    /// `SoundAmbience.dbc` id.
     pub ambience: u32,
-    /// `ZoneMusic.dbc` FK.
+    /// `ZoneMusic.dbc` id.
     pub zone_music: u32,
-    /// `ZoneIntroMusicTable.dbc` FK — the entry fanfare (the abbey's monk chant).
+    /// `ZoneIntroMusicTable.dbc` id, the entry fanfare.
     pub intro_sound: u32,
-    /// `AreaTable.dbc` FK — the WORLD area this WMO group counts as (0 = none). The client's
-    /// GetAreaID resolver (wow-re 0x670250) reads this when the down-ray keeps the WMO over the
-    /// terrain chunk, so an indoor city (Ironforge/Undercity) reports its own area, not the
-    /// enclosing zone's. Feeds the minimap/world-map zone and interior sound.
+    /// The `AreaTable.dbc` area this group counts as (0 = none), read by the area resolver
+    /// `0x670250` when the down-ray keeps the WMO over the terrain: Ironforge reports its own area.
     pub area_table_id: u32,
-    /// The interior's display name (enUS; empty for unnamed rows).
+    /// The interior's enUS display name, empty for an unnamed row.
     pub name: String,
 }
 
-/// The table keyed for the runtime lookup: exact group rows + whole-WMO defaults.
+/// The table keyed for the runtime lookup: exact group rows and whole-WMO defaults.
 pub struct WmoAreaCatalog {
-    /// `(WMOID, NameSetID, WMOGroupID)` → row (group-specific).
+    /// `(WMOID, NameSetID, WMOGroupID)` to its group row.
     groups: HashMap<(u32, u32, u32), WmoArea>,
-    /// `(WMOID, NameSetID)` → the `WMOGroupID == −1` whole-WMO row.
+    /// `(WMOID, NameSetID)` to the `WMOGroupID == −1` whole-WMO row.
     defaults: HashMap<(u32, u32), WmoArea>,
 }
 
 impl WmoAreaCatalog {
-    /// The hit group's OWN row, **exact key** — the zone-text chain's **query B** (`0x69d8f0` →
-    /// bsearch `0x7ccd30`, wow-re `zonetext-indoor-bit.md` (d)/(d-ii): a single exact
-    /// `(WMOID, NameSetID, WMOGroupID)` search, **no NameSetID retry, no default fallback, no
-    /// overlay**): its name re-populates the subzone slot (an unnamed/missing row leaves the
-    /// slot as the override set it).
+    /// The hit group's own row by exact key, the zone-text chain's second query (`0x69d8f0`, one
+    /// bsearch at `0x7ccd30` with no name-set retry, default fallback or overlay): its name, if
+    /// any, refills the subzone slot.
     pub fn group_row(&self, wmo_id: u32, name_set: u32, group_id: u32) -> Option<&WmoArea> {
         self.groups.get(&(wmo_id, name_set, group_id))
     }
 
-    /// The whole-WMO `WMOGroupID == −1` row, **exact key** (same single-search law) — the
-    /// zone-text chain's **query A** (`0x69d830` → `0x7ccde0`, `push 0xffffffff`): its name
-    /// overrides the ZONE slot only when non-empty and different from the current subzone (the
-    /// inn splash; skipped at the abbey, whose default name equals its yard subzone). An
-    /// EXISTING-but-unnamed row falls back to an AreaTable name (the caller's job — it needs the
-    /// area catalog); a MISSING row never overrides.
+    /// The whole-WMO row by exact key, the zone-text chain's first query (`0x69d830` to
+    /// `0x7ccde0`, `push 0xffffffff`): a name unlike the subzone overrides the zone slot, an
+    /// unnamed row falls back to an `AreaTable` name, and a missing row never overrides.
     pub fn default_row(&self, wmo_id: u32, name_set: u32) -> Option<&WmoArea> {
         self.defaults.get(&(wmo_id, name_set))
     }
 
-    /// Resolve a WMO interior's audio identity as a **field-level overlay**: the group row's
-    /// nonzero fields over the whole-WMO (−1) default's. Data demands this — the abbey's chant
-    /// (`IntroSound` 221), music (204) and ambience (26) all live on its −1 row while the group
-    /// rows the player actually stands in ("Main Hall" 1934…) are near-empty; a row-level pick
-    /// returned the zeros and silenced the abbey (director-caught, 2026-07-03). Name-set
-    /// fallback to 0 when the placement's set has no rows (INTERIM — the client's name-set miss
-    /// behavior is unrecorded; set-0 rows exist for every audio-carrying WMO).
+    /// A WMO interior's audio, the group row's non-zero fields over the whole-WMO row's: the
+    /// abbey's chant, music and ambience sit on its whole-WMO row. A name set without rows falls
+    /// back to set 0; the reference's handling of that miss is untraced.
     pub fn resolve(&self, wmo_id: u32, name_set: u32, group_id: u32) -> Option<WmoArea> {
         let (group, default) = [name_set, 0]
             .iter()
@@ -189,43 +164,33 @@ pub fn load_wmo_area_catalog(chain: &mut Chain) -> Result<WmoAreaCatalog> {
 mod tests {
     use super::*;
 
-    /// The real 5875 table resolves the two byte-verified anchors: the abbey's whole-WMO monk
-    /// chant (WMO 59 → intro 221 "Sacred01") and the chapel's interior group row (WMO 656 group
-    /// 478 → CAVE reverb 75 + ambience 50). Skips without client data.
     #[test]
     fn real_wmo_area_resolves_abbey_and_chapel() {
         let data = crate::wow_data_or_skip!();
         let mut chain = crate::open_chain(&data).expect("open chain");
         let cat = load_wmo_area_catalog(&mut chain).expect("load WMOAreaTable");
-        // 21115 rows, 21105 distinct (wmo, nameset, group) keys — 10 exact-duplicate keys are
-        // editor debris in the 5875 data (e.g. WMO 556 nameset 1 rows appear twice).
+        // 21115 rows but 21105 distinct (wmo, nameset, group) keys: the shipped data repeats 10.
         assert_eq!(cat.len(), 21105, "all distinct rows load");
 
-        // NSabbey (59): any interior group falls back to the whole-WMO row = the monk chant.
+        // NSabbey (59): an unknown group falls back to the whole-WMO row, the monk chant.
         let abbey = cat.resolve(59, 0, 9999).expect("abbey default row");
         assert_eq!(abbey.intro_sound, 221, "Sacred01 intro");
 
-        // AreaTableID (field 10) — the WORLD area a WMO group counts as. The abbey model is reused;
-        // its nameset-0 "Main Hall" (group 1934) sits at Alexston Farmstead (area 219), proving the
-        // column parses real AreaTable ids (not the all-zero Flags at field 9). This is what lets an
-        // indoor city report its own area — a raw scan finds 186 group rows → Ironforge (1537) and
-        // 219 → Undercity (1497).
+        // The reused abbey model's "Main Hall" (group 1934) sits at Alexston Farmstead (area 219).
         assert_eq!(
             cat.resolve(59, 0, 1934).unwrap().area_table_id,
             219,
             "the group's AreaTableID resolves (field 10, not the zeroed field 9)"
         );
 
-        // The overlay (the director-caught silence): standing in the abbey's "Main Hall"
-        // (group 1934, a near-empty row) must still hear the whole-WMO identity.
+        // The overlay: the near-empty "Main Hall" row still hears the whole-WMO identity.
         let hall = cat.resolve(59, 0, 1934).expect("Main Hall");
         assert_eq!(hall.intro_sound, 221, "the chant reaches the hall");
         assert_eq!(hall.zone_music, 204);
         assert_eq!(hall.ambience, 26);
         assert_eq!(hall.name, "Main Hall", "the group's own name wins");
 
-        // Chapel (656) interior group 478: CAVE reverb + interior ambience overlaying the
-        // whole-WMO row's underwater pref; no music anywhere on this WMO.
+        // Chapel (656) group 478: cave reverb and ambience over the whole-WMO underwater preset.
         let chapel = cat.resolve(656, 0, 478).expect("chapel group row");
         assert_eq!(chapel.sound_provider, [75, 11]);
         assert_eq!(chapel.ambience, 50);
diff --git a/crates/benilla-formats/src/world_map_area.rs b/crates/benilla-formats/src/world_map_area.rs
index 776c201f..a9e5ccc9 100644
--- a/crates/benilla-formats/src/world_map_area.rs
+++ b/crates/benilla-formats/src/world_map_area.rs
@@ -1,18 +1,6 @@
-//! `WorldMapArea.dbc` — the world-map projection basis: for each map-UI "area" (a continent as a
-//! whole, or one zone/instance's own map), the art folder under `Interface\WorldMap\<name>\` and
-//! the world-coordinate rect that folder's texture covers (decision 0203's `map_proj`, phase 2,
-//! reads this rect to lerp between world space and normalized map UV space).
-//!
-//! Layout — VERIFIED against build 5875 (header + full 51-row decode, cross-checked against
-//! vmangos's `WorldMapAreaEntry` (`src/game/Database/DBCStructure.h:737`), 2026-07-07): **51 × 8 ×
-//! 32 B**: `ID(0), MapID(1), AreaID(2, 0 = the continent-wide row), AreaName(3, string — the
-//! `Interface\WorldMap\<name>\` folder), LocLeft(4), LocRight(5), LocTop(6), LocBottom(7)` (4×
-//! `f32`). vmangos's own struct skips `ID` (commented out, unused server-side) and names the loc
-//! quad `y1/y2/x1/x2`; every other field lines up 1:1. Byte-exact on the two rows that matter for
-//! phase 2's continent basis: id 14 → `(mapId 0, areaId 0, "Azeroth", [16000.0, -19199.9, 7466.6,
-//! -16000.0])`, id 13 → `(mapId 1, areaId 0, "Kalimdor", ...)`; a zone row, id 4 → `(mapId 1,
-//! areaId 14, "Durotar", [-1962.5, -7250.0, 1808.3, -1716.7])`, whose `AreaName` is confirmed (this
-//! session) to be a real `Interface\WorldMap\Durotar\Durotar1.blp` art folder in the chain.
+//! `WorldMapArea.dbc`, the world map's projection basis: for each continent or zone map, the art
+//! folder under `Interface\WorldMap\<name>\` and the world rect its texture covers (vmangos's
+//! `WorldMapAreaEntry`, `DBCStructure.h:737`).
 
 use std::collections::HashMap;
 
@@ -24,28 +12,26 @@ use crate::Chain;
 
 const WORLD_MAP_AREA: &str = "DBFilesClient\\WorldMapArea.dbc";
 
-/// One `WorldMapArea.dbc` row: a map-UI "area" (continent or zone) and the world rect its
-/// `Interface\WorldMap\<name>\` art covers.
+/// One `WorldMapArea.dbc` row: a continent or zone map and the world rect its art covers.
 #[derive(Clone, Debug)]
 pub struct WorldMapArea {
-    /// `Map.dbc` id this row belongs to.
+    /// The `Map.dbc` id.
     pub map_id: u32,
-    /// `AreaTable.dbc` id for a zone row; `0` for the continent-wide row (Azeroth/Kalimdor/…).
+    /// `AreaTable.dbc` id of a zone row, `0` for the continent-wide one.
     pub area_id: u32,
     /// The `Interface\WorldMap\<name>\` art folder (also the client-visible internal name).
     pub name: String,
-    /// World-coordinate rect this area's map art covers (vmangos: `y1/y2/x1/x2` — WoW's world X is
-    /// "top/bottom", world Y is "left/right"; see the module doc for the verified sample values).
+    /// The world rect the art covers: left and right are world Y, top and bottom world X (vmangos's
+    /// `y1/y2/x1/x2`).
     pub loc_left: f32,
     pub loc_right: f32,
     pub loc_top: f32,
     pub loc_bottom: f32,
 }
 
-/// `WorldMapArea.dbc` rows keyed by `ID` — the id `WorldMapOverlay.worldMapAreaId` joins against.
-/// File order is preserved ([`WorldMapAreaCatalog::iter`]): the client's continent index IS the
-/// on-disk order of the areaId==0 rows (Kalimdor before Azeroth in 5875 — wow-re Q1(d) verdict,
-/// the builder `0x4a5d00` walks rows in file order).
+/// `WorldMapArea.dbc` rows keyed by `ID`, the id `WorldMapOverlay.worldMapAreaId` joins. File order
+/// is kept: the reference's continent index is the file order of the `AreaID` 0 rows (Kalimdor
+/// first in 5875), as its builder `0x4a5d00` walks them.
 pub struct WorldMapAreaCatalog {
     by_id: HashMap<u32, WorldMapArea>,
     /// Row ids in on-disk record order.
@@ -53,14 +39,12 @@ pub struct WorldMapAreaCatalog {
 }
 
 impl WorldMapAreaCatalog {
-    /// The row for `id` (the `WorldMapArea.dbc` primary key), or `None`.
+    /// The row for `id`.
     pub fn get(&self, id: u32) -> Option<&WorldMapArea> {
         self.by_id.get(&id)
     }
 
-    /// The continent-wide row (`area_id == 0`) for `map_id` — the "world" projection basis
-    /// (decision 0203, `map_proj`'s continent mode). Exactly one such row per continent in 5875
-    /// (Azeroth id 14, Kalimdor id 13).
+    /// The continent-wide row (`area_id == 0`) for `map_id`, one per continent in 5875.
     pub fn continent(&self, map_id: u32) -> Option<(u32, &WorldMapArea)> {
         self.by_id
             .iter()
@@ -68,8 +52,7 @@ impl WorldMapAreaCatalog {
             .map(|(&id, a)| (id, a))
     }
 
-    /// All rows as `(id, row)`, in **file order** — the order the client's continent index is
-    /// built in (see the struct doc). Zone consumers re-sort by display name anyway.
+    /// Every row as `(id, row)`, in file order.
     pub fn iter(&self) -> impl Iterator<Item = (u32, &WorldMapArea)> {
         self.file_order
             .iter()
@@ -85,7 +68,6 @@ impl WorldMapAreaCatalog {
     }
 }
 
-/// 8 fields: `ID, MapID, AreaID, AreaName, LocLeft, LocRight, LocTop, LocBottom`.
 fn schema() -> Schema {
     let mut s = Schema::new("WorldMapArea");
     for name in ["ID", "MapID", "AreaID"] {
@@ -149,9 +131,7 @@ pub fn load_world_map_area_catalog(chain: &mut Chain) -> Result<WorldMapAreaCata
 mod tests {
     use super::*;
 
-    /// The real 5875 table: the continent rows (Azeroth/Kalimdor) plus Durotar's verified rect,
-    /// and the zone row's `name` really is a `Interface\WorldMap\<name>\` art folder in the chain
-    /// (proving `AreaName` is the art folder, not just a label). Skips without client data.
+    /// The 5875 table: both continents, Durotar's rect, and `AreaName` naming a real art folder.
     #[test]
     fn real_world_map_area_has_continents_and_durotar_and_art_folder() {
         let data = crate::wow_data_or_skip!();
@@ -167,7 +147,6 @@ mod tests {
         assert_eq!((kalimdor.map_id, kalimdor.area_id), (1, 0));
         assert_eq!(kalimdor.name, "Kalimdor");
 
-        // `continent()` resolves the same two rows by map_id alone.
         let (azeroth_id, _) = cat.continent(0).expect("Azeroth via continent(0)");
         assert_eq!(azeroth_id, 14);
         let (kalimdor_id, _) = cat.continent(1).expect("Kalimdor via continent(1)");
@@ -181,7 +160,6 @@ mod tests {
         assert!((durotar.loc_top - 1808.3).abs() < 0.1);
         assert!((durotar.loc_bottom - (-1716.7)).abs() < 0.1);
 
-        // The zone row's name really is the `Interface\WorldMap\<name>\` art folder.
         let art = format!("Interface\\WorldMap\\{0}\\{0}1.blp", durotar.name);
         assert!(
             chain.contains(&art),
diff --git a/crates/benilla-formats/src/world_map_continent.rs b/crates/benilla-formats/src/world_map_continent.rs
index 4c50df9c..51fea1ea 100644
--- a/crates/benilla-formats/src/world_map_continent.rs
+++ b/crates/benilla-formats/src/world_map_continent.rs
@@ -1,17 +1,6 @@
-//! `WorldMapContinent.dbc` — one row per continent (Azeroth, Kalimdor) framing the continent-level
-//! map art: which ADT tile-grid span it covers, its placement offset/scale in the shared world-map
-//! coordinate space, and the taxi-map's own bounding rect (decision 0203 phase 2's continent view).
-//!
-//! **Client-only: vmangos carries no struct for this table** (never loaded server-side). Layout
-//! **VERIFIED against the 5875 binary** (wow-re Q2 verdict, 2026-07-07, recorded in
-//! `system/ui/scratch/geometry.md` "Worldmap data model"): **2 × 13 × 52 B** —
-//! `ID(0), MapID(1)`; fields 2-5 = ADT tile bounds (ints; the world-map builder `0x4a5d00`
-//! converts them to each continent's normalized-UV sheet rect — the world-level click AABB;
-//! `map_proj::continent_sheet_rect` transcribes the kernel); fields 6/7 = the per-axis
-//! world-sheet offsets and field 8 = the scale, exactly the values `0x4a72b0`/`0x4a7360`
-//! world-mode read at record `+0x18/+0x1c/+0x20` (5875: EK `{14.5, −7.0, 0.75}`, Kalimdor
-//! `{−19.0, −0.32249799, 0.75}`); fields 9-12 = the taxi-map world rect, **unused** by all four
-//! projection functions.
+//! `WorldMapContinent.dbc`: each continent's ADT tile bounds and its place on the world map sheet,
+//! read by the builder `0x4a5d00` and the world-mode projections `0x4a72b0` and `0x4a7360`.
+//! vmangos does not load it.
 
 use std::collections::HashMap;
 
@@ -23,26 +12,24 @@ use crate::Chain;
 
 const WORLD_MAP_CONTINENT: &str = "DBFilesClient\\WorldMapContinent.dbc";
 
-/// One `WorldMapContinent.dbc` row (all fields decomp-verified — see the module doc).
+/// One `WorldMapContinent.dbc` row.
 #[derive(Clone, Debug)]
 pub struct WorldMapContinent {
-    /// `Map.dbc` id (`0` = Azeroth, `1` = Kalimdor in 5875).
+    /// `Map.dbc` id: 0 Azeroth, 1 Kalimdor.
     pub map_id: u32,
-    /// ADT tile-grid column bounds — the `0x4a5d00` sheet-rect kernel's inputs (see module doc).
+    /// ADT tile column bounds, which `0x4a5d00` turns into the continent's sheet rect.
     pub left_boundary: u32,
     pub right_boundary: u32,
-    /// ADT tile-grid row bounds.
+    /// ADT tile row bounds.
     pub top_boundary: u32,
     pub bottom_boundary: u32,
-    /// The continent's world-sheet offsets — the `f` terms of the world-mode projections
-    /// (`0x4a7360`: `u = offset_x/62.625 + 0.5 − wy·k·scale`), x → the u axis, y → v.
+    /// World-sheet offsets, x on the u axis and y on v
+    /// (`0x4a7360`: `u = offset_x/62.625 + 0.5 - wy·k·scale`).
     pub offset_x: f32,
     pub offset_y: f32,
-    /// The world-sheet scale the projections multiply by (`0.75` on both 5875 rows — there is
-    /// no separate world-level zoom variable).
+    /// The world-sheet scale, 0.75 on both rows; there is no separate world zoom.
     pub scale: f32,
-    /// The taxi-map's own bounding rect in world units — carried for the future taxi layer;
-    /// unused by the map projections.
+    /// The taxi map's rect in world units; no map projection reads it.
     pub taxi_min: (f32, f32),
     pub taxi_max: (f32, f32),
 }
@@ -66,8 +53,6 @@ impl WorldMapContinentCatalog {
     }
 }
 
-/// 13 fields: `ID, MapID, LeftBoundary, RightBoundary, TopBoundary, BottomBoundary, OffsetX,
-/// OffsetY, Scale, TaxiMinX, TaxiMinY, TaxiMaxX, TaxiMaxY` (see the module doc for confidence).
 fn schema() -> Schema {
     let mut s = Schema::new("WorldMapContinent");
     for name in [
@@ -148,8 +133,6 @@ pub fn load_world_map_continent_catalog(chain: &mut Chain) -> Result<WorldMapCon
 mod tests {
     use super::*;
 
-    /// The real 5875 table: exactly the two verified rows (Azeroth mapId 0, Kalimdor mapId 1),
-    /// byte-exact on every field. Skips without client data.
     #[test]
     fn real_world_map_continent_has_azeroth_and_kalimdor() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/world_map_overlay.rs b/crates/benilla-formats/src/world_map_overlay.rs
index 5800652a..b0f45a9a 100644
--- a/crates/benilla-formats/src/world_map_overlay.rs
+++ b/crates/benilla-formats/src/world_map_overlay.rs
@@ -1,20 +1,6 @@
-//! `WorldMapOverlay.dbc` — the per-area zoomed-in overlay art: for a `WorldMapArea` row, up to four
-//! `AreaTable` sub-regions plus the texture (and its placement/hit-rect) that draws over the base
-//! map when a sub-region is discovered or its highlight is hovered (decision 0203 phase 3's
-//! discovery overlays + phase 2's `map_proj` overlay hit-test).
-//!
-//! Layout — VERIFIED against build 5875 (header + full 526-row decode, cross-checked against
-//! vmangos's *commented-out* `WorldMapOverlayEntry` (`src/game/Database/DBCStructure.h:752` — the
-//! struct only keeps `ID`/`areatableID[4]`, the rest is server-unused and left as index comments)
-//! and independently against a community reference struct for the same build, 2026-07-07: **526 ×
-//! 17 × 68 B**: `ID(0), WorldMapAreaID(1), AreaID[4](2-5), MapPointX(6), MapPointY(7),
-//! TextureName(8, string), TextureWidth(9), TextureHeight(10), OffsetX(11), OffsetY(12),
-//! HitRectTop(13), HitRectLeft(14), HitRectBottom(15), HitRectRight(16)`. Sanity-checked over all
-//! 526 rows: `HitRectTop < HitRectBottom` holds for 525/526, `HitRectLeft < HitRectRight` holds for
-//! all 526, and `TextureWidth`/`TextureHeight` track the hit-rect span's rough magnitude — all
-//! consistent with the field identities above. `MapPointX`/`MapPointY` are `0` on **every** row in
-//! this data (matches vmangos's own `// to implement [?]` note on the struct: authored but unused
-//! in 1.12).
+//! `WorldMapOverlay.dbc`: the textures drawn over a `WorldMapArea`'s map when one of up to four
+//! `AreaTable` sub-regions is discovered or hovered, with their placement and hit rect. vmangos
+//! keeps only the id and area columns (`WorldMapOverlayEntry`, `DBCStructure.h:752`).
 
 use std::collections::HashMap;
 
@@ -26,18 +12,17 @@ use crate::Chain;
 
 const WORLD_MAP_OVERLAY: &str = "DBFilesClient\\WorldMapOverlay.dbc";
 
-/// One `WorldMapOverlay.dbc` row: a sub-region's overlay texture + placement.
+/// One overlay: a sub-region's texture and placement.
 #[derive(Clone, Debug)]
 pub struct WorldMapOverlay {
-    /// `WorldMapArea.dbc` id this overlay draws over.
+    /// The `WorldMapArea.dbc` id this overlay draws over.
     pub world_map_area_id: u32,
-    /// Up to 4 `AreaTable.dbc` ids this overlay's highlight covers (`0` = unused slot).
+    /// The `AreaTable.dbc` ids the highlight covers; 0 is an empty slot.
     pub area_id: [u32; 4],
-    /// Always `0` in 5875 — an authored-but-unused map-point (see the module doc).
+    /// 0 on every shipped row.
     pub map_point_x: u32,
     pub map_point_y: u32,
-    /// The overlay texture's base name (no path/extension) under
-    /// `Interface\WorldMap\<WorldMapArea name>\`.
+    /// A basename under `Interface\WorldMap\<WorldMapArea name>\`.
     pub texture_name: String,
     pub texture_width: u32,
     pub texture_height: u32,
@@ -49,14 +34,12 @@ pub struct WorldMapOverlay {
     pub hit_rect_right: u32,
 }
 
-/// `WorldMapOverlay.dbc` rows grouped by `WorldMapAreaID` — the join key against
-/// [`crate::WorldMapAreaCatalog`].
+/// `WorldMapOverlay.dbc` rows grouped by `WorldMapAreaID`.
 pub struct WorldMapOverlayCatalog {
     by_area: HashMap<u32, Vec<WorldMapOverlay>>,
 }
 
 impl WorldMapOverlayCatalog {
-    /// The overlays for `world_map_area_id`, or an empty slice if none.
     pub fn for_area(&self, world_map_area_id: u32) -> &[WorldMapOverlay] {
         self.by_area
             .get(&world_map_area_id)
@@ -73,7 +56,6 @@ impl WorldMapOverlayCatalog {
     }
 }
 
-/// 17 fields per the module doc.
 fn schema() -> Schema {
     let mut s = Schema::new("WorldMapOverlay");
     for name in ["ID", "WorldMapAreaID"] {
@@ -140,9 +122,6 @@ pub fn load_world_map_overlay_catalog(chain: &mut Chain) -> Result<WorldMapOverl
 mod tests {
     use super::*;
 
-    /// The real 5875 table: Teldrassil's `WorldMapArea` id (41) carries overlays with non-empty
-    /// texture names (e.g. the "Bane Thillhollow"/"Darnassus" sub-zone highlights). Skips without
-    /// client data.
     #[test]
     fn real_world_map_overlay_has_nonempty_textures_for_teldrassil() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/src/world_state_ui.rs b/crates/benilla-formats/src/world_state_ui.rs
index 78df2158..527a0756 100644
--- a/crates/benilla-formats/src/world_state_ui.rs
+++ b/crates/benilla-formats/src/world_state_ui.rs
@@ -1,42 +1,9 @@
-//! `WorldStateUI.dbc` — the rows behind the always-up PvP status readout and the battleground
-//! scoreboard's columns (`GetNumWorldStateUI` / `GetWorldStateUIInfo`).
+//! `WorldStateUI.dbc`, the rows behind the always-up PvP readout and the battleground scoreboard's
+//! columns (`GetNumWorldStateUI`, `GetWorldStateUIInfo` `0x4c5a70`). It is client-only: vmangos
+//! sends only world-state values, and which are shown, where and with what label is this table's.
 //!
-//! **Client-only: vmangos carries no struct for this table.** The server's whole contribution is
-//! the world-state *values* (`SMSG_INIT_WORLD_STATES` / `SMSG_UPDATE_WORLD_STATE`,
-//! [`crate::messages::world_state`](benilla_protocol) on the wire); which of them are *displayed*,
-//! where, and with what label is entirely this file's.
-//!
-//! Layout pinned by inspection of the shipped 5875 file (2026-08-25): **20 × 39 × 156 B**. The
-//! field boundaries are not assumed from a later build's schema — they are proven by the
-//! localized-string signature, which could have come out otherwise: a loc block in this era is
-//! nine dwords (the enUS string + seven other-locale slots + a flags dword), and a census of all
-//! 20 rows finds fields 5-11, 14-20 and 27-33 **uniformly zero** with 12, 21 and 34 each holding a
-//! locale-flags mask (`0x3F00BE` and two siblings). That fixes three loc blocks at 4-12, 13-21 and
-//! 26-34, and everything between them follows:
-//!
-//! `ID(0), MapID(1), AreaID(2), Icon(3, a path string), Text_lang(4-12), Tooltip_lang(13-21),
-//! <unread>(22), StateVariable(23), Type(24), DynamicIcon(25, a path string),
-//! DynamicTooltip_lang(26-34), ExtendedUI(35, a token string), ExtendedUIStateVariable[3](36-38)`.
-//!
-//! Those names are the **binary's**, confirmed 2026-08-25 by wow-re's carve of the loader and the
-//! two bindings (`system/ui/scratch/worldstate-ui-law.md`): the loader's own dimension asserts
-//! (`0x553a9e cmp eax,0x27`, `0x553ad6 cmp eax,0x9c`) fix 39 columns of 156 bytes, and
-//! `GetWorldStateUIInfo 0x4c5a70` reads exactly `+0x0c` Icon, `+0x10` Text, `+0x34` Tooltip,
-//! `+0x5c` StateVariable, `+0x64` DynamicIcon, `+0x68` DynamicTooltip, `+0x8c` ExtendedUI,
-//! `+0x90/94/98` the three extended ids. **Field 22 (`+0x58`) is written by the loader and read by
-//! nothing** — none of the table's four consumers touch it — so it is not carried here; its
-//! shipped values are `0` on the three Eastern Plaguelands rows and `-1` on the other seventeen.
-//!
-//! The shipped rows read exactly as that naming predicts: the Eastern Plaguelands pair carries
-//! `Icon = Interface\WorldStateFrame\{Alliance,Horde}Tower` with `StateVariable = "Towers
-//! Controlled: %2327w"` — the same world-state macro grammar the NPC-text expander already
-//! speaks, over the two ids vmangos's `OutdoorPvPEP` pushes; Warsong Gulch's two carry a
-//! `DynamicIcon` of the *enemy* flag with `WorldState` 2338/2339, the "flag has been picked up"
-//! keys; and Alterac Valley's `Type = 2` rows are the scoreboard's column headers, not an
-//! always-up readout.
-//!
-//! What the client *does* with these rows — which it admits, and how [`WorldStateUiRow::text`]
-//! becomes a displayed string — is [`crate::world_state_ui`](benilla_app)'s, not this module's.
+//! Layout: 39 fields of 156 bytes (the loader asserts both, `0x553a9e`, `0x553ad6`), each
+//! localized string nine dwords; field 22 (`+0x58`) is loaded and never read, so not carried.
 
 use anyhow::{Context, Result};
 use benilla_dbc::{FieldType, Schema, SchemaField};
@@ -49,66 +16,48 @@ const WORLD_STATE_UI: &str = "DBFilesClient\\WorldStateUI.dbc";
 /// One `WorldStateUI.dbc` row.
 #[derive(Clone, Debug)]
 pub struct WorldStateUiRow {
-    /// `Map.dbc` id this row belongs to — `0`/`1` for the two outdoor-PvP continents, otherwise a
-    /// battleground map (30 Alterac Valley, 489 Warsong Gulch, 529 Arathi Basin).
+    /// The row's `Map.dbc` id: a continent for world PvP, else a battleground map.
     pub map_id: u32,
-    /// `AreaTable.dbc` id narrowing the row within its map, or `0` for the whole map. Only the
-    /// outdoor rows use it: `139` (Eastern Plaguelands) and `1377` (Silithus).
+    /// The `AreaTable.dbc` id narrowing the row within its map (world PvP only), `0` for all of it.
     pub area_id: u32,
-    /// The static icon's texture path (`Interface\WorldStateFrame\AllianceTower`), empty when the
-    /// row draws no icon.
+    /// The static icon's texture path (`Interface\WorldStateFrame\AllianceTower`), or empty.
     pub icon: String,
-    /// The label, as authored — a format string in the `%<id>w` world-state grammar
-    /// (`"Towers Controlled: %2327w"`, `"Bases: %1779w  Resources: %1776w/%1780w"`), or plain text
-    /// on the scoreboard-column rows (`"Graveyards Assaulted"`). This is the **only** column the
-    /// client expands; every other string below is handed to Lua verbatim.
+    /// The label: a `%<id>w` world-state format (`"Towers Controlled: %2327w"`), or plain text on
+    /// a scoreboard column. The only string the client expands; the rest reach Lua verbatim.
     pub text: String,
     /// The tooltip line (`"Alliance Towers Controlled"`).
     pub tooltip: String,
-    /// `StateVariable` (+0x5c) — the world-state id whose *value* the client returns as the row's
-    /// `uiState`, or `0` for "no state", which the binding answers as the constant `1.0`. Set on
-    /// three rows: `2338`/`2339` on the Warsong Gulch pair (the "enemy flag picked up" keys that
-    /// swap in [`Self::dynamic_icon`]) and `2426` on the Eastern Plaguelands progress row.
+    /// `StateVariable` (`+0x5c`), the world-state id whose value the client returns as the row's
+    /// `uiState`; `0` is no state, which the binding answers as `1.0`.
     pub state_variable: u32,
-    /// `Type` (+0x60) — which list the row belongs to, and the builder's third gate:
-    ///
-    /// - **0** — always-up, unconditional. The four Warsong Gulch / Arathi Basin status rows.
-    /// - **1** — always-up, but only while the player has joined a **zone-dependent defense**
-    ///   chat channel ([`crate::chat_channel_flags`]' `ZONE_DEP | DEFENSE`, which is row 22 alone
-    ///   in the shipped table). The five world-PvP rows: Eastern Plaguelands' three and
-    ///   Silithus's two.
-    /// - **2** — a battleground **scoreboard column**, which never enters the always-up list at
-    ///   all; it is built by a different handler off the same table.
+    /// `Type` (`+0x60`), which list the row joins: `0` always up; `1` always up only while the
+    /// player is in a zone-dependent defense channel (`ZONE_DEP | DEFENSE`, LocalDefense alone),
+    /// the world-PvP rows; `2` a scoreboard column, built by another handler.
     pub ui_type: u32,
-    /// The alternate icon shown while [`Self::state_variable`] is live — the enemy flag, on the two
-    /// Warsong Gulch rows that have one. Empty elsewhere.
+    /// The icon shown instead while [`Self::state_variable`] is live: the enemy flag, on the two
+    /// Warsong Gulch rows that have one.
     pub dynamic_icon: String,
     /// The tooltip that goes with [`Self::dynamic_icon`] (`"Horde flag has been picked up"`).
     pub dynamic_tooltip: String,
-    /// A token naming an extra UI widget the row drives — `"CAPTUREPOINT"`, on exactly one row
-    /// (the Eastern Plaguelands progress bar). Empty elsewhere.
+    /// A token naming an extra widget the row drives: `"CAPTUREPOINT"`, on the Eastern
+    /// Plaguelands progress row alone.
     pub extended_ui: String,
-    /// The world-state **ids** that widget reads — the binding answers their resolved *values*.
-    /// Nonzero on exactly one row: id 138 carries `(2427, 2428, 0)`, so the whole extended-UI
-    /// mechanism in 1.12 exists for Eastern Plaguelands' capture-point progress bar alone.
+    /// The world-state ids that widget reads; the binding answers their values.
     pub extended_ui_state: [u32; 3],
 }
 
-/// `WorldStateUI.dbc` rows in **file order**, with their ids.
+/// `WorldStateUI.dbc` rows in file order, with their ids.
 pub struct WorldStateUiCatalog {
     rows: Vec<(u32, WorldStateUiRow)>,
 }
 
 impl WorldStateUiCatalog {
-    /// A catalog over rows given directly — for a caller that needs a table of exactly known
-    /// shape (the consumer's gate tests build one-row ones, so that "no init yet ⇒ empty readout"
-    /// is asserted rather than hoped for).
+    /// A catalog over rows given directly, for tests that need a table of known shape.
     pub fn from_rows(rows: Vec<(u32, WorldStateUiRow)>) -> Self {
         Self { rows }
     }
 
-    /// Every row in file order. Order is kept because a UI list built from this table is indexed
-    /// by position, and the table's own order is the only one that is not an invention.
+    /// Every row in file order, the order a UI list built from the table is indexed by.
     pub fn rows(&self) -> impl Iterator<Item = (u32, &WorldStateUiRow)> {
         self.rows.iter().map(|(id, row)| (*id, row))
     }
@@ -122,8 +71,6 @@ impl WorldStateUiCatalog {
     }
 }
 
-/// 39 fields; the three loc blocks are nine dwords each (see the module doc for how their bounds
-/// were proven rather than assumed).
 fn schema() -> Schema {
     let mut s = Schema::new("WorldStateUI");
     for name in ["ID", "MapID", "AreaID"] {
@@ -141,7 +88,7 @@ fn schema() -> Schema {
     };
     loc(&mut s, "Text");
     loc(&mut s, "Tooltip");
-    // +0x58: the loader writes it, no consumer reads it. Named for what is known about it.
+    // +0x58: loaded, never read.
     for name in ["UnreadCol22", "StateVariable", "Type"] {
         s.add_field(SchemaField::new(name, FieldType::UInt32));
     }
@@ -193,10 +140,6 @@ pub fn load_world_state_ui_catalog(chain: &mut Chain) -> Result<WorldStateUiCata
 mod tests {
     use super::*;
 
-    /// The real 5875 table proves the layout — and each assertion below could have failed if a
-    /// field boundary were off by one, because every one of them is a *string* landing where a
-    /// number would garble it, or a number landing in a range only that column occupies.
-    /// Skips without client data.
     #[test]
     fn real_world_state_ui_layout_sanity() {
         let data = crate::wow_data_or_skip!();
@@ -211,7 +154,7 @@ mod tests {
                 .unwrap_or_else(|| panic!("row {id}"))
         };
 
-        // ── The Eastern Plaguelands pair: report B190's own subject.
+        // ── The Eastern Plaguelands pair.
         let alliance = by_id(136);
         assert_eq!((alliance.map_id, alliance.area_id), (0, 139));
         assert_eq!(alliance.icon, "Interface\\WorldStateFrame\\AllianceTower");
@@ -221,7 +164,6 @@ mod tests {
         let horde = by_id(137);
         assert_eq!(horde.icon, "Interface\\WorldStateFrame\\HordeTower");
         assert_eq!(horde.text, "Towers Controlled: %2328w");
-        // Type 1 — the world-PvP kind, gated on the zone-defense channel by its consumer.
         assert_eq!((alliance.ui_type, horde.ui_type), (1, 1));
         assert_eq!(
             (alliance.state_variable, horde.state_variable),
@@ -248,15 +190,14 @@ mod tests {
         assert_eq!(ws_alliance.text, "%1581w/%1601w");
         assert_eq!(ws_alliance.ui_type, 0, "unconditional always-up");
 
-        // ── An Alterac Valley scoreboard column: type 2, no icon path of the WorldStateFrame
-        // kind, plain text rather than a macro.
+        // ── An Alterac Valley scoreboard column: type 2, plain text rather than a format.
         let graveyards = by_id(63);
         assert_eq!(graveyards.map_id, 30);
         assert_eq!(graveyards.ui_type, 2);
         assert_eq!(graveyards.text, "Graveyards Assaulted");
         assert!(!graveyards.text.contains('%'));
 
-        // ── Whole-table shape, each number a fact that could have come out otherwise.
+        // ── Whole-table shape.
         let mut with_area = 0;
         let mut with_macro = 0;
         for (_, row) in cat.rows() {
diff --git a/crates/benilla-formats/src/zone_map.rs b/crates/benilla-formats/src/zone_map.rs
index 01bcead1..80199c8e 100644
--- a/crates/benilla-formats/src/zone_map.rs
+++ b/crates/benilla-formats/src/zone_map.rs
@@ -1,15 +1,7 @@
-//! `Interface\WorldMap\<Continent>.zmp` — the continent area bitmap: a 128×128 grid of
-//! `AreaTable.dbc` row ids (16384 little-endian u32, row-major, exactly 65536 bytes) covering the
-//! whole 64×64-ADT world at half-ADT granularity. The client's world-map hover/click resolves a
-//! cursor cell to a zone through it (`0x4a6ec0`; the loader `0x4a5d00` remaps cells to
-//! WorldMapArea ids at load — benilla's remap lives with the catalog build, `ui_world_map`).
-//!
-//! Mechanism VERIFIED by wow-re (Q1 §5 cross-check, 2026-07-07, recorded in
-//! `system/ui/scratch/geometry.md` "Worldmap data model"): path format string @0x845374
-//! (`Interface\WorldMap\%s.zmp`, `%s` = the continent WorldMapArea row's AreaName), 0x10000 bytes
-//! read raw into the record. Corroborated against the shipped file this session: Azeroth.zmp's
-//! cell at the recorded index law for Goldshire's world position holds 12 = Elwynn Forest.
-//! 5875 ships `Azeroth.zmp` + `Kalimdor.zmp` (and a dead `Expansion01.zmp`).
+//! `Interface\WorldMap\<AreaName>.zmp` (`0x845374`), named by the continent's `WorldMapArea` row:
+//! a 128×128 row-major grid of `AreaTable.dbc` ids over the 64×64-tile world, two cells per tile
+//! edge. The world map resolves the cell under the cursor to a zone through it (`0x4a6ec0`); the
+//! loader (`0x4a5d00`) remaps cells to `WorldMapArea` ids.
 
 use anyhow::{bail, Context, Result};
 
@@ -18,9 +10,8 @@ use crate::chain::Chain;
 /// Cells per grid edge (half-ADT: 128 cells over 64 tiles).
 pub const ZONE_MAP_EDGE: usize = 128;
 
-/// Load `Interface\WorldMap\<area_name>.zmp` — 16384 raw `AreaTable.dbc` ids, row-major.
-/// A continent without a shipped bitmap is an error (the client leaves its grid zeroed; callers
-/// decide whether that's tolerable).
+/// Load `Interface\WorldMap\<area_name>.zmp` as raw `AreaTable.dbc` ids. A missing file is an
+/// error here, where the client leaves its grid zeroed.
 pub fn load_zone_map(chain: &mut Chain, area_name: &str) -> Result<Vec<u32>> {
     let path = format!("Interface\\WorldMap\\{area_name}.zmp");
     let bytes = chain
@@ -45,9 +36,7 @@ pub fn load_zone_map(chain: &mut Chain, area_name: &str) -> Result<Vec<u32>> {
 mod tests {
     use super::*;
 
-    /// The real Azeroth bitmap: the Goldshire cell (index by the byte law: col from wy=60, row
-    /// from wx=−9450 ⇒ cell 12735) holds Elwynn Forest's AreaTable id — the end-to-end pin of
-    /// path, layout, and index law against shipped data. Skips without client data.
+    /// Cell 12735 is Goldshire: row from wx = -9450, column from wy = 60.
     #[test]
     fn real_azeroth_zone_map_goldshire_cell() {
         let data = crate::wow_data_or_skip!();
diff --git a/crates/benilla-formats/tests/billboards.rs b/crates/benilla-formats/tests/billboards.rs
index ef18b866..160dd95e 100644
--- a/crates/benilla-formats/tests/billboards.rs
+++ b/crates/benilla-formats/tests/billboards.rs
@@ -1,11 +1,8 @@
-//! Regression: an M2 batch that packs several billboard glow cards on different bones must be split
-//! into one submesh per billboard bone, each centred on its own bone pivot — so the renderer rotates
-//! each card about its own candle (faces the camera in place) instead of swinging the whole cluster
-//! about a single pivot. See decision 0028. Skips (passes) when the client isn't present.
+//! An M2 batch of billboard cards on several bones splits into one submesh per bone, centred on
+//! that bone's pivot, so each card turns to the camera in place.
 
 use benilla_formats::{load_m2_mesh, open_chain, RenderSubmesh};
 
-/// The geometric centre of a submesh's vertices (model space).
 fn geom_center(s: &RenderSubmesh) -> [f32; 3] {
     let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
     for p in &s.positions {
@@ -25,8 +22,7 @@ fn geom_center(s: &RenderSubmesh) -> [f32; 3] {
 fn candelabra_glow_cards_split_per_bone() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
-    // CandelabraTallWall01 has five candles; all five glow cards share one additive glow-texture batch,
-    // each quad skinned to its own per-candle billboard bone.
+    // Five candles: one additive glow batch, each card's quad skinned to its own billboard bone.
     let subs = load_m2_mesh(
         &mut chain,
         "World\\Generic\\PassiveDoodads\\Lights\\CandelabraTallWall01.m2",
@@ -44,10 +40,8 @@ fn candelabra_glow_cards_split_per_bone() {
     let mut pivots: Vec<[f32; 3]> = Vec::new();
     for c in &cards {
         let bb = c.billboard.as_ref().unwrap();
-        // Each split card is a single quad (4 verts / 2 tris) …
         assert_eq!(c.positions.len(), 4, "a glow card is one quad (4 verts)");
         assert_eq!(c.indices.len(), 6, "a glow card is one quad (2 tris)");
-        // … centred on its OWN bone pivot, so it faces the camera and pulses in place (no swing/slide).
         let ctr = geom_center(c);
         let d = [
             ctr[0] - bb.pivot[0],
@@ -63,7 +57,6 @@ fn candelabra_glow_cards_split_per_bone() {
         pivots.push(bb.pivot);
     }
 
-    // The five pivots are five distinct candle positions (no two cards collapsed onto one bone).
     for (i, a) in pivots.iter().enumerate() {
         for b in &pivots[i + 1..] {
             let spread = (a[1] - b[1]).abs() + (a[2] - b[2]).abs();
diff --git a/crates/benilla-formats/tests/blob_shadow_box.rs b/crates/benilla-formats/tests/blob_shadow_box.rs
index 7d604767..d432616d 100644
--- a/crates/benilla-formats/tests/blob_shadow_box.rs
+++ b/crates/benilla-formats/tests/blob_shadow_box.rs
@@ -1,11 +1,5 @@
-//! Pins the unit blob shadow's box source against real build-5875 assets: the shadow sizes from
-//! the **current animation's** `M2Sequence` CAaBox (wow-re `unit-blob-shadow.md`, `0x711a20` — the
-//! same sequence-record box the pick volume and the ring's Stand-footprint read), so
-//! `ModelAnimation::bounds_min/max` must round-trip the raw record. The Stand-box horizontal
-//! extents of the four reference-traced creatures are already pinned by
-//! `selection_ring_radius.rs` *through* the nested-sqrt footprint; this asserts the **box itself**
-//! (the shadow consumes it raw: clamp ±5, scale, AA-bound — no compression). Skips when the
-//! gitignored client data isn't present.
+//! The unit blob shadow sizes from the Stand sequence's `M2Sequence` box (`0x711a20`), used raw
+//! (clamped to ±5, then scaled), so `ModelAnimation::bounds_min/max` must round-trip the record.
 
 use benilla_formats::{open_chain, parse_m2_animations};
 
@@ -14,8 +8,7 @@ fn stand_box_extents_match_reference() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open chain");
 
-    // (model, Stand-box horizontal extents (dx, dy) — the wow-re selection-ring RE's measured
-    // table, read straight off the real sequence records).
+    // (model, Stand box dx, dy), measured off the real sequence records.
     let cases = [
         ("Creature\\Chicken\\Chicken.m2", 0.532_f32, 0.382_f32),
         ("Character\\Human\\Male\\HumanMale.m2", 0.913, 1.080),
@@ -23,7 +16,7 @@ fn stand_box_extents_match_reference() {
     for (path, dx, dy) in cases {
         let bytes = chain.read_file(path).expect(path);
         let anims = parse_m2_animations(&bytes);
-        // Stand (anim id 0)'s head variation — the box the idle shadow projects.
+        // Stand's first variation: the box the shadow always projects.
         let stand = anims
             .iter()
             .find(|a| a.anim_id == 0)
@@ -39,12 +32,10 @@ fn stand_box_extents_match_reference() {
             "{path}: Stand box dy {:.3} != reference {dy}",
             bmax[1] - bmin[1]
         );
-        // The box is a real volume: a degenerate Z extent would zero the shadow's vertical reach.
         assert!(
             bmax[2] > bmin[2],
             "{path}: Stand box has no vertical extent"
         );
-        // And the centre derives from the same corners (the sphere fields already shipped).
         for i in 0..3 {
             assert!(
                 ((bmin[i] + bmax[i]) * 0.5 - stand.bounds_center[i]).abs() < 1e-4,
diff --git a/crates/benilla-formats/tests/blp_alpha.rs b/crates/benilla-formats/tests/blp_alpha.rs
index dd12995a..d717eef5 100644
--- a/crates/benilla-formats/tests/blp_alpha.rs
+++ b/crates/benilla-formats/tests/blp_alpha.rs
@@ -1,7 +1,5 @@
-//! Regression: a BLP2 texture with an unknown `alpha_type` byte must still decode. Real 1.12-era
-//! particle/effect art (e.g. `particles/dust1.blp` — palettized, `alpha_bits == 0`, but a stale
-//! `alpha_type == 2`) used to abort the whole decode in `wow_blp`; our fork falls back to no-alpha.
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! A BLP2 with a stale `alpha_type` still decodes: `particles/dust1.blp` is palettized with
+//! `alpha_bits == 0` and `alpha_type == 2`, and `alpha_bits` alone governs its alpha.
 
 use benilla_formats::{blp_to_rgba, open_chain};
 
diff --git a/crates/benilla-formats/tests/camera_swim_pivot_drop.rs b/crates/benilla-formats/tests/camera_swim_pivot_drop.rs
index 2433410f..2c4494d4 100644
--- a/crates/benilla-formats/tests/camera_swim_pivot_drop.rs
+++ b/crates/benilla-formats/tests/camera_swim_pivot_drop.rs
@@ -1,40 +1,14 @@
-//! Pins the camera's **swim** framing-pivot preset against real build-5875 assets — the third
-//! sibling of `selection_ring_radius` and `chat_bubble_anchor_height`, reading the same
-//! `M2Sequence` `CAaBox` those two read, on a second animation.
-//!
-//! The reference keeps three framing-pivot presets and picks one per frame at `0x50f880`:
-//!
-//! ```text
-//! swimming (MOVEFLAG 0x200000) -> cam+0x124        ; the swim preset
-//! else cam+0x198 < 1.8315      -> cam+0x11c        ; zoomed in    -- NOT BUILT
-//! else                            cam+0x120        ; zoomed out   -- NOT BUILT
-//! ```
-//!
-//! All three are rebuilt from the model by `0x50ca90` off one shared base — the
-//! `attach17.z + 0.0972` neck height — and only `+0x124` is then pulled down:
-//!
-//! ```text
-//! 50cccf  call 0x711a20(model, seq=0)     ; Stand
-//! 50ccde  call 0x711a20(model, seq=0x2a)  ; Swim (42)
-//! 50ccf6  fsubr [esi+0x124]               ; +0x124 -= S * (Stand.max.z - Swim.max.z)
-//! ```
-//!
-//! byte-decoded and VERIFIED in wow-re `ui/scratch/water-band-discontinuity.md` §7, which measured
-//! the shipped Human Male at scale 1 as `+0x11c = +0x120 = 1.9002692` and `+0x124 = 1.5120120`.
-//! That pair — and only that pair — is a number read off the binary; everything else below is
-//! measured off the shipped M2s, pinned so the id-42 lookup cannot quietly stop resolving.
-//!
-//! The Human Male standing side comes out 1.900247 here rather than 1.9002692 because benilla
-//! ships the base constant as `0.0972` while the reference's `[0x808ab0]` is `0.0972222` — 0.02 mm,
-//! and *not* part of this feature, which is why the presets get a 1e-4 window and the drop itself
-//! (a pure box difference, no constant in it) gets 1e-5.
-//!
-//! Skips when the gitignored client data isn't present.
+//! The camera's swim framing pivot. Per frame `0x50f880` picks one of three presets: `cam+0x124`
+//! while swimming (movement flag `0x200000`), else `cam+0x11c` or `cam+0x120` split on
+//! `cam+0x198 < 1.8315`, a pair benilla serves with one standing height. `0x50ca90` builds all
+//! three from `attach17.z + 0.0972` and lowers only `+0x124`, by `S * (Stand.max.z - Swim.max.z)`
+//! over the `0x711a20` boxes of sequences 0 and 42 (`0x50cccf`, `0x50ccde`, `0x50ccf6`). For the
+//! Human Male at scale 1 the binary gives `+0x11c = +0x120 = 1.9002692`, `+0x124 = 1.5120120`.
 
 use benilla_formats::{load_m2_bounds, open_chain};
 
-/// The base the reference adds to all three presets — `attach17.z + 0.0972222 [0x808ab0]`, as
-/// benilla's own display builder rounds it (`entities::display::build_parts`).
+/// The presets' base above attachment 17: `0.0972222` in the reference (`[0x808ab0]`), `0.0972`
+/// in `entities::display::build_parts`. The 0.02 mm gap is why the presets get a 1e-4 window.
 const PIVOT_BASE: f32 = 0.0972;
 
 #[test]
@@ -46,7 +20,6 @@ fn the_swim_preset_is_the_stand_minus_swim_sequence_box_delta() {
         .expect("bounds HumanMale");
     let standing = b.pivot_z.expect("HumanMale authors attachment 17") + PIVOT_BASE;
 
-    // The one number read off the binary: 1.9002692 − 1.5120120.
     assert!(
         (b.swim_pivot_drop - 0.3882572).abs() < 1e-5,
         "HumanMale swim_pivot_drop {:.7} should be the reference's 1.9002692 − 1.5120120 = 0.3882572",
@@ -68,18 +41,13 @@ fn the_drop_is_per_model_and_zero_for_a_body_with_no_swim_sequence() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open chain");
 
-    // (model, the drop measured off the shipped M2). Character models only for the non-zero rows:
-    // the drop is `Stand.max.z − Swim.max.z`, and how far a race's swim pose sinks below its stand
-    // pose is authored per skeleton — a night elf barely dips, a tauren drops nearly half a yard.
-    // A single-model pin would pass just as happily on a lookup that always resolved record 0.
+    // (model, the drop measured off the shipped M2); how far the swim pose sinks is per skeleton.
     let cases = [
         ("Character\\Human\\Male\\HumanMale.mdx", 0.3882571_f32),
         ("Character\\Tauren\\Male\\TaurenMale.mdx", 0.4236124),
         ("Character\\NightElf\\Female\\NightElfFemale.mdx", 0.1288066),
-        // No Swim sequence at all: the chicken's animation lookup is 17 entries long, so id 42 is
-        // past its end and no record carries that id. This is the reference's own both-present
-        // guard (`0x711960` on 0 and 0x2a at `0x50cc43`/`0x50cc4f`) — a body that cannot swim keeps
-        // the standing preset in every state.
+        // No Swim sequence: the reference's both-present guard (`0x711960` on 0 and 0x2a at
+        // `0x50cc43`/`0x50cc4f`) keeps the standing preset.
         ("Creature\\Chicken\\Chicken.mdx", 0.0),
     ];
 
@@ -90,9 +58,6 @@ fn the_drop_is_per_model_and_zero_for_a_body_with_no_swim_sequence() {
             "{path}: swim_pivot_drop {:.7} should be {drop:.7}",
             b.swim_pivot_drop
         );
-        // A drop is a drop: never negative, and never so large it would put the swim preset under
-        // the model's feet. Both hold for every shipped body; either failing means the id-42
-        // lookup landed on the wrong record.
         let standing = b.pivot_z.map(|z| z + PIVOT_BASE).unwrap_or(0.0);
         assert!(
             b.swim_pivot_drop >= 0.0 && b.swim_pivot_drop < standing,
diff --git a/crates/benilla-formats/tests/chain.rs b/crates/benilla-formats/tests/chain.rs
index 0f7d0763..3291976c 100644
--- a/crates/benilla-formats/tests/chain.rs
+++ b/crates/benilla-formats/tests/chain.rs
@@ -1,7 +1,4 @@
-//! Integration test against the real client at `<repo>/WoW/Data` (gitignored).
-//!
-//! Skips (passes) when the client isn't present, so CI without assets stays green.
-//! Document: place a legally-owned 1.12.1 client's `Data` dir at the repo root `WoW/`.
+//! Integration tests over the patch chain of a real 1.12.1 install.
 
 use benilla_formats::{open_chain, Chain};
 
@@ -28,18 +25,14 @@ fn reads_spell_dbc_from_vanilla_chain() {
 fn resolves_and_reads_across_archive_types() {
     let data = benilla_formats::wow_data_or_skip!();
 
-    // One `Chain` (the `&self` AssetReader backend and the `&mut` streaming loaders are now the same
-    // type) must resolve and read across archive kinds — DBC (dbc/patch.MPQ), a UI BLP, and a
-    // base-archive M2 with no per-archive listfile (resolved by name hash). Non-empty reads pin
-    // cross-archive resolution and the whole-file (no-PTCH) invariant for these files.
+    // A DBC, a UI BLP, and an M2 from a base archive with no listfile, found by name hash.
     let chain = open_chain(&data).expect("open vanilla patch chain");
 
     for path in [
         "DBFilesClient/Spell.dbc",
         "DBFilesClient/TaxiNodes.dbc",
         "Interface/Icons/Spell_Holy_ArcaneIntellect.blp",
-        // Physical .m2 in a listfile-less base archive (references use .mdx; the .mdx→.m2 remap is a
-        // loader concern, so the reader gets the on-disk path) — proves base-archive resolution.
+        // The on-disk name: the `.mdx` -> `.m2` remap belongs to the loaders, not the reader.
         "Creature\\Kobold\\Kobold.m2",
     ] {
         assert!(chain.contains(path), "chain should resolve {path}");
@@ -55,9 +48,8 @@ fn culls_constant_zero_alpha_m2_batches() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // OrgrimmarFloatingEmbers' only render batch is an 84-yd box with a transparency-weight track of
-    // 0.0 — a particle-emitter anchor the real client never draws (it culls batches at alpha ≤ 0,
-    // verified). It must be culled, leaving the model with no render geometry (its 3 emitters remain).
+    // The embers' only batch is an 84-yd box with a constant 0.0 transparency weight, an emitter
+    // anchor the reference never draws: it culls a batch at alpha <= 0.
     let embers = benilla_formats::load_m2_mesh(
         &mut chain,
         "world/kalimdor/orgrimmar/passivedoodads/orgrimmarbonfire/orgrimmarfloatingembers.m2",
@@ -69,16 +61,12 @@ fn culls_constant_zero_alpha_m2_batches() {
         embers.len()
     );
 
-    // Control — a normal lamppost keeps every batch (body + glow cards), proving the zero-alpha cull
-    // doesn't over-cull visible geometry.
     let lamppost = benilla_formats::load_m2_mesh(
         &mut chain,
         "world/azeroth/elwynn/passivedoodads/lamppost/lamppost.m2",
     )
     .expect("mesh lamppost");
-    // Five batches: body + glass + two billboard cards (the spherical additive glow and the cylindrical
-    // top-flame) split out from their mixed batch onto their own bones, so each faces the camera about
-    // its own pivot (decision 0028). The point here is the alpha-cull leaves every visible batch intact.
+    // Body, glass, and two billboard cards split off their mixed batch onto their own bones.
     assert_eq!(lamppost.len(), 5, "a normal prop keeps all its batches");
 }
 
@@ -87,21 +75,8 @@ fn trigger_creature_models_carry_no_render_geometry() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // How an invisible **trigger creature** hides in the real client (decision 1403, bug B13): its
-    // model draws nothing. No unit flag, no DBC column — a swept census of all 411 shipped
-    // `CreatureModelData` paths found exactly these three, by two different routes:
-    //
-    //   InvisibleStalker        — `nVertices == 0`: no geometry authored at all (80 bones,
-    //                             135 animations, and not one vertex).
-    //   InvisibleStalkerNoName  — one 4-vertex batch whose transparency track is a constant
-    //                             `0.000`, so the verified zero-alpha cull takes it.
-    //   Creature_SpellPortal    — `nVertices == 0`, like the stalker.
-    //
-    // Between them they back 8 `CreatureDisplayInfo` rows and 154 vmangos creature templates — the
-    // Scarab Wall's "Anachronos Quest Trigger Invisible" and Yojamba Isle's "Zandalarian Event
-    // Generator" among them. If any of these ever comes back non-empty, the attach path stops
-    // being able to tell "this model draws nothing" from "we have no model" and the debug cube
-    // returns as a black slab over all 154.
+    // A trigger creature hides by its model drawing nothing: the stalker and the portal author no
+    // vertices, and NoName's one batch has a constant 0.0 transparency track.
     for path in [
         "creature/invisiblestalker/invisiblestalker.m2",
         "creature/invisiblestalker/invisiblestalkernoname.m2",
@@ -116,8 +91,6 @@ fn trigger_creature_models_carry_no_render_geometry() {
         );
     }
 
-    // Control — an ordinary creature on the same path keeps its geometry, so "empty" is a property
-    // of these three models and not of the creature lane.
     let chicken = benilla_formats::load_m2_mesh(&mut chain, "creature/chicken/chicken.m2")
         .expect("mesh chicken");
     assert!(
@@ -131,12 +104,8 @@ fn the_trigger_creature_still_carries_the_attachments_its_visible_self_rides() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // Decision 1656: a trigger creature draws nothing *and is not therefore empty*. The
-    // Naxxramas weapon mobs (`Unholy Axe`/`Swords`/`Staff`, creature_template 16194/16215/16216,
-    // all display 15294) ARE an `InvisibleStalker` body — the model above, `nVertices == 0` —
-    // whose entire visible self hangs off its attachment points: the weapon on HandRight, the
-    // name plate on PlayerName. If either of these ever stops resolving, the mobs go back to
-    // being a bare name on the floor, and nothing in the render lane would say so.
+    // The Naxxramas weapon mobs (display 15294) are this body, seen only through its attachments:
+    // the weapon on HandRight, the name plate on PlayerName.
     let bytes = chain
         .read_file("Creature\\InvisibleStalker\\InvisibleStalker.m2")
         .expect("read InvisibleStalker.m2");
@@ -156,8 +125,6 @@ fn the_trigger_creature_still_carries_the_attachments_its_visible_self_rides() {
         name.position
     );
 
-    // And the bounds really are degenerate, which is why the plate CANNOT come from the fallback
-    // (`feet + scale × bbox_z × 1.25` = feet) and must come from the attachment above.
     let bounds = benilla_formats::load_m2_bounds(
         &mut chain,
         "Creature\\InvisibleStalker\\InvisibleStalker.mdx",
@@ -175,10 +142,8 @@ fn suppresses_white1_invisible_trap_placeholder() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // The `SpellObject_InvisibleTrap` placeholder (GameObject displayId 1287 — Fire-Festival fury zones,
-    // rallying-cry triggers, …): a flat opaque quad textured with the engine utility-white WHITE1.BLP.
-    // The real client draws it at per-instance alpha ≈0 (invisible); benilla recognises the placeholder
-    // and drops its geometry (decision 0030). It must reduce to zero render batches.
+    // GameObject display 1287: a flat opaque quad on `WHITE1.BLP` that the reference draws at
+    // per-instance alpha ~0, so the loader drops it.
     let trap = benilla_formats::load_m2_mesh(
         &mut chain,
         "world/generic/passivedoodads/traps/spellobject_invisibletrap.m2",
@@ -190,9 +155,7 @@ fn suppresses_white1_invisible_trap_placeholder() {
         trap.len()
     );
 
-    // Control — a *visible* flat decal that shares the trap's degenerate render box but carries a real
-    // texture + AlphaTest (an orc bedroll). It must NOT be suppressed: the fingerprint is opaque+WHITE1,
-    // not flatness, so genuine ground decals are kept.
+    // A flat decal with a real texture: the fingerprint is opaque on `WHITE1`, not flatness.
     let mat = benilla_formats::load_m2_mesh(
         &mut chain,
         "world/azeroth/burningsteppes/passivedoodads/orcsleepmats/orcsleepmat01.m2",
@@ -213,10 +176,7 @@ fn decodes_a_blp_icon_to_png() {
         .read_file("Interface/Icons/Spell_Holy_ArcaneIntellect.blp")
         .expect("read spell icon BLP");
 
-    // Keyed by pid, like every other temp path in the workspace: eight pool slots run
-    // `cargo test --workspace` concurrently, and a FIXED shared name means one run's
-    // cleanup deletes the file another is about to read. That is not hypothetical — the
-    // taxi twin below reddened a land gate exactly that way (decision 1918).
+    // Keyed by pid: concurrent test runs would otherwise delete each other's file.
     let out = std::env::temp_dir().join(format!("benilla-fmt-icon-{}.png", std::process::id()));
     let (w, h) = benilla_formats::blp_to_png(&bytes, &out).expect("decode BLP -> PNG");
 
@@ -268,9 +228,7 @@ fn meshes_an_elwynn_terrain_tile() {
         tile.vertex_count() <= 256 * 145,
         "<= 256 chunks * (81 outer + 64 inner) = 145 verts/chunk (center-fan)"
     );
-    // Hilltop sanity (B1): every chunk should carry the 64 inner center verts, and at least one
-    // tile-wide cell must have its center vertex deviate by > 1 yd from the corner-mean — that's
-    // the authored hilltop bump we used to flatten. Catches a regression to the old 81-vert mesher.
+    // Rows of 9 outer and 8 inner vertices alternate, 17 to a pair.
     let mut hilltop_dev = 0.0f32;
     for c in &tile.chunks {
         assert_eq!(c.positions.len(), 145, "chunk = 81 outer + 64 inner verts");
@@ -311,9 +269,7 @@ fn meshes_an_elwynn_terrain_tile() {
         }
     }
 
-    // Bounds sanity — guards against the MCNK axis-scramble bug.
-    // One tile spans ~533 yds in X and Y; tile 31_48's world X is negative; Z holds plausible
-    // terrain heights (a leaked horizontal axis would blow the Z span way past this).
+    // A tile is 533.33 yd square; a scrambled MCNK axis would blow the Z span.
     let span = |i: usize| mx[i] - mn[i];
     assert!(
         (500.0..540.0).contains(&span(0)) && (500.0..540.0).contains(&span(1)),
@@ -332,7 +288,6 @@ fn meshes_an_elwynn_terrain_tile() {
         span(2)
     );
 
-    // Texturing data: some chunk should reference a base-layer .blp from MTEX.
     assert!(
         tile.chunks.iter().any(|c| c
             .base_texture
@@ -341,8 +296,6 @@ fn meshes_an_elwynn_terrain_tile() {
         "expected a base-layer .blp texture on some chunk"
     );
 
-    // Multi-layer splat data (Phase 6): Elwynn blends grass/dirt/road, so some chunk should have
-    // >1 layer and a non-trivial packed alpha map.
     let multilayer = tile
         .chunks
         .iter()
@@ -395,8 +348,7 @@ fn terrain_chunks_carry_unit_upward_mcnr_normals() {
                 "decoded normal should be ~unit, got len {len:.3} for {n:?}"
             );
             checked += 1;
-            // WoW Z is up; ground normals point outward/up. If the X/Z/Y decode were wrong, "up"
-            // would land in a different component and this would collapse — so it pins the axis.
+            // WoW Z is up; a wrong X/Z/Y decode would put "up" in another component.
             if n[2] > 0.5 {
                 up += 1;
             }
@@ -409,28 +361,10 @@ fn terrain_chunks_carry_unit_upward_mcnr_normals() {
     );
 }
 
-/// Every terrain triangle must wind **CCW seen from above** in WoW space — the invariant that lets
-/// the renderer draw terrain single-sided (backface-culled), which is what the real 1.12.1 client
-/// does: its terrain-chunk pass never touches `EGxRs 0x14`, so it inherits the device baseline
-/// `CULL_FACE = 1`, and the ground is see-through from underneath (decision 0960). Flip a fan's
-/// winding and the world would vanish when viewed from *above* instead — a catastrophic, silent
-/// regression no other test here would catch, since winding changes nothing about positions,
-/// seams, or heights.
-///
-/// Two forms of the same law:
-///
-/// 1. **Exact.** Terrain is a heightfield on a fixed XY lattice, so the sign of a triangle's
-///    geometric-normal Z is the sign of its XY-projected signed area — independent of the authored
-///    heights. (The reference builds its vertices the same way: `0x6b0e50` writes X and Y from the
-///    grid indices and only Z from MCVT.) No shipped triangle may violate this.
-/// 2. **Near-total.** wow-re's coordinate-system-free statement of the same convention: the emitted
-///    winding is the one whose right-hand-rule normal agrees with the vertex's own MCNR normal.
-///    Worth keeping because it survives a change of frame — but it is *not* exact on shipped data
-///    and must not be asserted as if it were: wow-re derived it against flat ground, where MCNR is
-///    exactly `(0,0,1)`, and on this Elwynn tile 4 of 196368 triangle-vertex pairs disagree (worst
-///    cos −0.48, on a hillside). Those are authored outliers, not a decode fault — a decode fault
-///    would be systematic, not 4-in-200k. A genuine winding flip turns ~every pair negative, which
-///    the 0.01% ceiling below still catches loudly.
+/// Terrain winds CCW seen from above, so it draws backface-culled as the reference does: its chunk
+/// pass never sets `EGxRs 0x14` and inherits `CULL_FACE = 1`. Exact on the XY lattice (`0x6b0e50`
+/// takes X and Y from the grid, only Z from MCVT); against the authored MCNR normals it holds bar
+/// outliers, 4 of 196368 pairs on this tile, hence the 0.01% ceiling.
 #[test]
 fn terrain_fans_wind_ccw_seen_from_above() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -452,9 +386,8 @@ fn terrain_fans_wind_ccw_seen_from_above() {
                 [b[0] - a[0], b[1] - a[1], b[2] - a[2]],
                 [c[0] - a[0], c[1] - a[1], c[2] - a[2]],
             );
-            // Form 1 — Z of u×v: positive ⇔ CCW viewed down the +Z (up) axis.
+            // The Z of u × v, positive for CCW seen from above.
             min_nz = min_nz.min(u[0] * v[1] - u[1] * v[0]);
-            // Form 2 — does u×v agree with each of the three authored MCNR normals?
             if let Some(normals) = shading {
                 let n = [
                     u[1] * v[2] - u[2] * v[1],
@@ -496,9 +429,7 @@ fn terrain_is_watertight_at_chunk_seams() {
     let tile =
         benilla_formats::load_tile_mesh(&mut chain, "Azeroth", tx, ty).expect("mesh the tile");
 
-    // Bucket every vertex by quantized XY (0.25-yd buckets only group truly-coincident verts, since
-    // the grid spacing is ~4.17 yd). A vertex shared by adjacent chunks must come out *bit-identical*
-    // in X/Y after lattice snapping — otherwise the fractional misalignment reopens the seam.
+    // 0.25-yd XY buckets group only coincident vertices: the grid step is 4.17 yd.
     use std::collections::HashMap;
     let mut buckets: HashMap<(i64, i64), Vec<[f32; 3]>> = HashMap::new();
     for c in &tile.chunks {
@@ -590,9 +521,7 @@ fn resolves_creature_models_from_dbcs() {
         catalog.len()
     );
 
-    // Scan display ids; many should resolve. Prove at least one resolved creature model that ships
-    // in this client actually meshes (not every CreatureModelData path is present on disk). Scale 0
-    // is valid — many low-id displays are invisible trigger NPCs — so we only require most positive.
+    // Not every `CreatureModelData` path ships; scale 0 is valid (many low ids are trigger NPCs).
     let (mut resolved, mut positive_scale, mut meshed) = (0u32, 0u32, false);
     for id in 1..6000u32 {
         let Some(m) = catalog.model(id) else { continue };
@@ -636,7 +565,6 @@ fn resolves_gameobject_models_from_dbc() {
         catalog.len()
     );
 
-    // Every resolved path is a model; prove at least one meshes (dispatches .mdx/.mdl/.m2 vs .wmo).
     let mut meshed = false;
     for id in 1..3000u32 {
         let Some(path) = catalog.model_path(id).map(str::to_string) else {
@@ -661,9 +589,7 @@ fn loads_classic_models_with_cosmetic_chunks() {
     let data = benilla_formats::wow_data_or_skip!();
 
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
-    // These vanilla M2s aborted `parse_m2` with "failed to fill whole buffer" on stock wow-m2 0.6.4
-    // (malformed particle-emitter / light / texture-animation chunks — warcraft-rs#56). Our patched
-    // fork degrades those cosmetic chunks to empty, so geometry now loads. They must mesh.
+    // Their particle, light and texture-animation chunks are malformed; the geometry still loads.
     for path in [
         "Creature\\Kobold\\Kobold.mdx",
         "Creature\\Imp\\Imp.mdx",
@@ -675,7 +601,6 @@ fn loads_classic_models_with_cosmetic_chunks() {
     }
 }
 
-/// Span (max−min) per axis of a point set; `[0;3]` if empty.
 fn span3(ps: &[[f32; 3]]) -> [f32; 3] {
     if ps.is_empty() {
         return [0.0; 3];
@@ -695,9 +620,7 @@ fn decodes_m2_collision_hulls() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // Golden vectors hand-verified against the raw bytes 2026-06-02. The
-    // hull is a coarse TRUNK, far smaller than the render canopy — the "blocked by trunk, walk through
-    // leaves" shape. Exact tri/vert counts fire if a wow-m2 bump changes the bounding-array decode.
+    // Counts read off the raw bytes. The hull is a coarse trunk, far smaller than the canopy.
     let pine = benilla_formats::load_m2_collision_hull(
         &mut chain,
         "World\\Azeroth\\Elwynn\\PassiveDoodads\\Trees\\ElwynnTree01\\ElwynnPine01.mdx",
@@ -740,7 +663,6 @@ fn decodes_m2_collision_hulls() {
         "ElwynnTreeCanopy01 hull = 30 verts"
     );
 
-    // Sanity: the hull is much smaller than the rendered model's authored bbox (trunk vs full canopy).
     let bounds = benilla_formats::load_m2_bounds(
         &mut chain,
         "World\\Azeroth\\Elwynn\\PassiveDoodads\\Trees\\ElwynnTreeCanopy01.mdx",
@@ -759,11 +681,8 @@ fn filters_wmo_collidable_triangles_by_mopy() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // Golden vector: the binary-verified client filter (collide iff `!(flags & 0x04 DETAIL)`,
-    // WoW.exe 5875 — collision.md §F) selects exactly 5114 collidable tris from the Goldshire Inn. (On
-    // this fixture that equals the old `COLLISION||(RENDER&&!DETAIL)` count — every non-DETAIL face here
-    // is also COLLISION-or-RENDER; the rules diverge only on flags-0x00/0x40-only faces, absent here.)
-    // Pins both the filter clause and the wow-wmo group decode.
+    // The reference's walking query skips a face iff `MOPY.flags & 0x04` (DETAIL): reject mask
+    // `0x84`, tested at its box-query leaf `0x6bca50` (from `0x6b91c0`, `0x6bc1c0`).
     let inn = benilla_formats::load_wmo_collision_tris(
         &mut chain,
         "World\\wmo\\Azeroth\\Buildings\\GoldshireInn\\GoldshireInn.wmo",
@@ -784,7 +703,6 @@ fn filters_wmo_collidable_triangles_by_mopy() {
         "inn collidable bbox should be building-sized, got {s:?}"
     );
 
-    // A bridge is ~entirely collision surface (you walk across the deck): elwynnwidebridge = 100%.
     let bridge = benilla_formats::load_wmo_collision_tris(
         &mut chain,
         "World\\wmo\\Azeroth\\Collidable Doodads\\Elwynn\\WideBridge\\ElwynnWideBridge.wmo",
@@ -801,12 +719,9 @@ fn derives_the_wmo_window_glass_law_from_momt() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // Golden vectors for the three MOMT window/glass mechanisms (wow-re `wmo-lit-selector` §1,
-    // `wmo-interior-night-light` §2/§4). The Goldshire Inn authors both window kinds:
-    //   mat 5  MM_ELWYNN_WND_EXT__01, flags 0x11 (UNLIT|SIDN), exterior groups only → the unlit
-    //          fullbright pane (SIDN inert under lighting-off), sidn colour still carried;
-    //   mat 21 MM_ELWYNN_WND_INT__01, flags 0x28 (WINDOW), interior groups' EXT section → lit by
-    //          the interior midpoint light, never fullbright, no SIDN colour.
+    // The MOMT glass mechanisms: the exterior UNLIT drawer `0x6b4f10`, the interior WINDOW drawer
+    // `0x6b5190` and the SIDN night ramp `0x6b4090`. The inn's mat 5 is flags 0x11 (UNLIT, SIDN)
+    // in exterior groups; mat 21 is 0x28 (WINDOW) in interior groups, lit, never fullbright.
     let inn = benilla_formats::load_wmo(
         &mut chain,
         "World\\wmo\\Azeroth\\Buildings\\GoldshireInn\\GoldshireInn.wmo",
@@ -848,9 +763,7 @@ fn derives_the_wmo_window_glass_law_from_momt() {
         );
     }
 
-    // The SIDN colour is a CImVector — BGRA on disk. Shadowfang's stained glass authors an
-    // ASYMMETRIC colour (disk bytes 216,231,250,255), so this pins the BGRA→RGB decode: a warm
-    // cream (250,231,216), not a cool blue — a swizzle bug can't pass.
+    // SIDN is a BGRA `CImVector`: Shadowfang's glass is disk bytes 216,231,250,255.
     let sfk = benilla_formats::load_wmo(
         &mut chain,
         "World\\wmo\\Dungeon\\LD_ShadowFang\\LD_ShadowFang.wmo",
@@ -868,21 +781,17 @@ fn reads_authentic_atmosphere_from_light_dbc() {
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
     let cat = benilla_formats::LightCatalog::load(&mut chain).expect("load Light DBCs");
 
-    // Northshire (Human start) on Azeroth resolves to the continent's global daytime light.
+    // Northshire resolves to Azeroth's global light 1, clear LightParams 12.
     let a = cat.sample_noon(0, [-8949.95, -132.49, 83.5]);
 
-    // Fog bands are RAW (no /36 — that scale is positions-only; wow-re `rf-weather-fog-veil.md`):
-    // the client pushes `min(raw, farclip)`, so these huge land values resolve to the view distance.
-    // Must have read real bands, not fallen back to the default.
     assert_ne!(
         a.fog_end,
         benilla_formats::Atmosphere::DEFAULT.fog_end,
         "got the fallback atmosphere — Light bands didn't resolve"
     );
 
-    // Exact verified ground truth (2026-05-25): Northshire → global light #1 → clear LightParams 12.
-    // Decoded independently from the raw DBC bytes and cross-checked vs wowdev.wiki; locking these
-    // pins the band index formula, the row→meaning map, the color decode, AND the light selection.
+    // Decoded off the raw DBC bytes. Fog end is stored ×36 and scaled once at DBC load by
+    // `0x6d6090`; the start fraction is never scaled.
     let to255 = |c: [f32; 3]| {
         [
             (c[0] * 255.0).round() as i32,
@@ -928,17 +837,15 @@ fn reads_authentic_atmosphere_from_light_dbc() {
     );
 }
 
-/// Elwynn's STORM param (k2 = LightParams 10) at midday — the §5-verified endpoints from wow-re's
-/// `rf-weather-fog-veil.md` (decoded off the real DBCs and byte-traced through the blend). The
-/// load-bearing pin is the **negative fog-start fraction**: −0.5, UNCLAMPED — the mechanism behind
-/// the reference's constant ~33% near veil under rain. A clamp regression here silently kills the veil.
+/// Elwynn's storm param, LightParams 10, at noon. Its fog start fraction is -0.5 and the reference
+/// never clamps it (`0x6cee6d`): the negative start is the constant ~33% near veil under rain.
 #[test]
 fn reads_elwynn_storm_fog_endpoints() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
     let cat = benilla_formats::LightCatalog::load(&mut chain).expect("load Light DBCs");
 
-    // Northshire, noon, storm slot (Elwynn global light #1 → storm LightParams 10, single-stop bands).
+    // Northshire at noon, time 1440 of 2880, storm slot; its bands are single-stop.
     let s = cat.sample(0, [-8949.95, -132.49, 83.5], 1440, true);
     assert!(
         (s.fog_end - 277.8).abs() < 1.0,
@@ -978,11 +885,8 @@ fn reads_map_directories_from_map_dbc() {
         "expected ≥40 Map.dbc rows, got {}",
         cat.len()
     );
-    // Canonical IDs — pin the schema so a field-count drift can't silently break the directory
-    // column (which would silently make every cross-map teleport pick the wrong terrain).
     assert_eq!(cat.directory(0), Some("Azeroth"));
     assert_eq!(cat.directory(1), Some("Kalimdor"));
-    // Deadmines instance — a dungeon, proves dungeons resolve too.
     assert_eq!(cat.directory(36), Some("DeadminesInstance"));
 }
 
@@ -991,14 +895,13 @@ fn decodes_azeroth_wdl_against_apitrace_ground_truth() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // Eastern Kingdoms distant-terrain heightmap.
     let wdl = benilla_formats::WdlFile::load(&mut chain, "Azeroth").expect("load Azeroth.wdl");
 
-    // VERIFIED by walking the real file (2026-05-30): MVER=18, 687 present tiles.
+    // Counted off the file: MVER 18, 687 tiles present.
     assert_eq!(wdl.present_count(), 687, "Azeroth.wdl present-tile count");
 
-    // Golden vector tied to apitrace WoW.8: the 2nd WDL tile drawn that frame spanned world
-    // X[-9066.7,-8533.3] Y[-1600,-1066.7] (= tile_x 34, tile_y 48) with vertex heights 54..349.
+    // From a reference frame capture: tile (34, 48) spans X -9066.7..-8533.3 and
+    // Y -1600..-1066.7, with vertex heights 54..349.
     assert!(
         wdl.is_present(34, 48),
         "apitrace tile (34,48) must be present"
@@ -1011,14 +914,12 @@ fn decodes_azeroth_wdl_against_apitrace_ground_truth() {
         "3072 indices (16x16 cells x 4 tris)"
     );
 
-    // Heights (world Z) — exact int16 from the file; must match the captured VB range.
     let zs: Vec<f32> = mesh.positions.iter().map(|p| p[2]).collect();
     let zmin = zs.iter().copied().fold(f32::INFINITY, f32::min);
     let zmax = zs.iter().copied().fold(f32::NEG_INFINITY, f32::max);
     assert_eq!(zmin, 54.0, "tile (34,48) min height (apitrace VB)");
     assert_eq!(zmax, 349.0, "tile (34,48) max height (apitrace VB)");
 
-    // Planar extent — one ADT tile (533.33 yd) on each axis, matching the captured VB span.
     let xs: Vec<f32> = mesh.positions.iter().map(|p| p[0]).collect();
     let ys: Vec<f32> = mesh.positions.iter().map(|p| p[1]).collect();
     let span = |v: &[f32]| {
@@ -1035,20 +936,15 @@ fn decodes_azeroth_wdl_against_apitrace_ground_truth() {
         "Y span ~533.33, got {}",
         span(&ys)
     );
-    // Max-X/-Y corner = tile origin (matches wow_wdt::tile_to_world(34,48)).
+    // The max-X, max-Y corner is the tile origin, `benilla_wdt::tile_to_world(34, 48)`.
     let xmax = xs.iter().copied().fold(f32::NEG_INFINITY, f32::max);
     let ymax = ys.iter().copied().fold(f32::NEG_INFINITY, f32::max);
     assert!((xmax - (-8533.3)).abs() < 0.5, "tile origin X, got {xmax}");
     assert!((ymax - (-1066.7)).abs() < 0.5, "tile origin Y, got {ymax}");
 }
 
-/// The two **fixed global `LightParams` rows** magma and slime submersion read (`light::PARAM_MAGMA`
-/// / `PARAM_SLIME`, byte-VERIFIED `0x6d2371`), pinned against the shipped client.
-///
-/// This is the cross-check that earned the finding rather than merely repeating it: nothing in
-/// `Light.dbc` references rows 6 or 7, so no position-keyed sample can reach them and no zone can
-/// vouch for them. What vouches for them is that they decode to *exactly* the vanilla lava and slime
-/// view — dense fiery orange and dense pure green — which a wrong pair of row numbers would not.
+/// Magma and slime submersion read the fixed global `LightParams` rows 7 and 6 (`0x6d2371`), which
+/// no `Light.dbc` row references; they decode to the dense orange and green views.
 #[test]
 fn magma_and_slime_submersion_read_the_fixed_global_light_params() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -1062,12 +958,10 @@ fn magma_and_slime_submersion_read_the_fixed_global_light_params() {
         ]
     };
 
-    // Two positions on different continents whose CLEAR atmospheres differ — the fixed rows must be
-    // identical at both, because they are zone-independent. This is the property that separates "a
-    // fixed global row" from "a zone underwater slot that happens to look right at one pin".
+    // Two continents with different clear atmospheres: a fixed row reads the same at both.
     let pins = [
-        (0u32, [-7531.21f32, -1123.64, 172.58]), // Blackrock Mountain (the B24/B68 lava pin)
-        (1u32, [-5075.53f32, -2063.09, -50.10]), // Thousand Needles (the B68 water pin)
+        (0u32, [-7531.21f32, -1123.64, 172.58]), // Blackrock Mountain, in lava
+        (1u32, [-5075.53f32, -2063.09, -50.10]), // Thousand Needles, in water
     ];
     for kind in [
         benilla_formats::Submersion::Magma,
@@ -1088,8 +982,7 @@ fn magma_and_slime_submersion_read_the_fixed_global_light_params() {
         );
     }
 
-    // Magma → row 7. Dense fiery orange, and the shortest fog in the client: 972/36 = 27 yd, with a
-    // −2.0 start fraction putting `1 − 27/(27+54)` = 67 % of it at the eye itself.
+    // Row 7, the client's shortest fog: end 972/36 = 27 yd, start -2.0, so 67% at the eye.
     let magma = cat.sample_blended(
         0,
         pins[0].1,
@@ -1115,7 +1008,7 @@ fn magma_and_slime_submersion_read_the_fixed_global_light_params() {
         magma.fog_start_frac
     );
 
-    // Slime → row 6. Pure green at 1800/36 = 50 yd, −1.0 start = 50 % at the eye.
+    // Row 6: end 1800/36 = 50 yd, start -1.0, so 50% at the eye.
     let slime = cat.sample_blended(
         0,
         pins[0].1,
@@ -1141,8 +1034,7 @@ fn magma_and_slime_submersion_read_the_fixed_global_light_params() {
         slime.fog_start_frac
     );
 
-    // And the whole point: neither is the zone's own underwater atmosphere. At the Thousand Needles
-    // pin the water murk is the olive-brown LP 203 — being in lava there must not show it.
+    // Neither is the zone's water murk, LightParams 203 at the Thousand Needles pin.
     let water = cat.sample_blended(
         1,
         pins[1].1,
@@ -1161,7 +1053,6 @@ fn magma_and_slime_submersion_read_the_fixed_global_light_params() {
         to255(slime.fog_color),
         "slime must not inherit the zone's water murk"
     );
-    // Dry is different again — the guard against "everything resolved to one fallback".
     let dry = cat.sample_blended(
         1,
         pins[1].1,
@@ -1177,19 +1068,15 @@ fn magma_and_slime_submersion_read_the_fixed_global_light_params() {
     );
 }
 
-/// The far band's tile window **contains the camera's own tile** (decision 0684). Dropping it was
-/// invisible at the default view distance — a 533 yd tile sits inside a 777 yd wall, so it would
-/// have been discarded anyway — and a hole above the horizon at any lower one, where the own tile is
-/// the only thing that draws the near horizon. The director found it at view distance 320 in
-/// Weazel's Crater; this pins the window at the coordinates they reported.
+/// The far band's tile window contains the camera's own tile: below the default view distance that
+/// tile is all that draws the near horizon.
 #[test]
 fn the_wdl_window_contains_the_cameras_own_tile() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
     let wdl = benilla_formats::WdlFile::load(&mut chain, "Kalimdor").expect("load Kalimdor.wdl");
 
-    // Weazel's Crater, Thousand Needles — the report's spot. The client's debug panel read
-    // `tile 39,42` standing there, which is what `world_to_tile` must agree on.
+    // Weazel's Crater, Thousand Needles.
     let (x, y) = (-5841.9_f32, -3802.4);
     let own = benilla_wdt::world_to_tile(x, y);
     assert_eq!(own, (39, 42), "the reported tile for Weazel's Crater");
@@ -1200,7 +1087,7 @@ fn the_wdl_window_contains_the_cameras_own_tile() {
         window.contains(&own),
         "the camera's own WDL tile must be in the window — without it the near horizon is a hole"
     );
-    // And it is a full (2r+1)² window, not a ring: every present tile within the radius.
+    // A full (2r+1)² window, not a ring: every present tile within the radius.
     let expected = (-5i32..=5)
         .flat_map(|dy| (-5i32..=5).map(move |dx| (own.0 as i32 + dx, own.1 as i32 + dy)))
         .filter(|&(tx, ty)| (0..64).contains(&tx) && (0..64).contains(&ty))
@@ -1209,26 +1096,13 @@ fn the_wdl_window_contains_the_cameras_own_tile() {
     assert_eq!(window.len(), expected, "every present tile in the window");
 }
 
-/// A **tombstoned path must never fall through to the live copy a base archive still holds.**
-///
-/// `patch.MPQ` deletes 26 paths that `model.MPQ` and friends still carry in full — cut content the
-/// 1.12.1 client does not load (decision 0246). The failure this pins is silent and points the
-/// wrong way: a chain that resolved *past* the delete-marker would serve `OgreMage.m2`'s 386 KB as
-/// if it were current, looking entirely healthy while rendering a model the reference never draws.
-/// Until now the property was held by a comment in `Chain::read` and nothing else.
-///
-/// Found by comparing our corpus census against wow-re's: their chain over-enumerated by exactly
-/// these 26, because `list` took the winning listfile entry whatever its flags. Ours already
-/// filtered — the point of this test is that it stays that way.
-///
-/// Non-vacuous by construction: each name is first read straight out of the base archive that still
-/// holds it, so the test fails loudly if the pairing ever stops being a real tombstone-over-content
-/// case rather than passing on an absent file.
+/// `patch.MPQ` deletes 26 paths that base archives still carry in full, cut content the 1.12
+/// client never loads; a deleted path must not fall through to the base copy.
 #[test]
 fn tombstoned_paths_never_fall_through_to_the_base_copy() {
     let data = benilla_formats::wow_data_or_skip!();
 
-    // Tombstoned by `patch.MPQ`; still present, in full, in `model.MPQ` (measured: 386416 / 437456).
+    // Deleted by `patch.MPQ`, whole in `model.MPQ` (386416 and 437456 bytes).
     const DELETED: [&str; 2] = [
         "Creature\\OgreMage\\OgreMage.m2",
         "Creature\\OgreWarlord\\OgreWarlord.m2",
@@ -1244,7 +1118,6 @@ fn tombstoned_paths_never_fall_through_to_the_base_copy() {
         .collect();
 
     for name in DELETED {
-        // The positive control: the content really is still there to be served by mistake.
         let live = base
             .read(name)
             .unwrap_or_else(|e| panic!("{name} must still exist in model.MPQ: {e}"));
@@ -1254,7 +1127,6 @@ fn tombstoned_paths_never_fall_through_to_the_base_copy() {
             live.len()
         );
 
-        // And the composite refuses it on all three paths.
         assert!(!chain.contains(name), "{name} is deleted from the chain");
         let err = chain
             .read(name)
@@ -1271,16 +1143,9 @@ fn tombstoned_paths_never_fall_through_to_the_base_copy() {
     }
 }
 
-/// The WMO **skybox** pair, against the shipped Stratholme files (`crate::models::wmo`,
-/// `benilla::skybox`): a root's MOSB model and the per-group `0x40000` gate that asks for it.
-///
-/// The sibling roots are the whole point of the fixture. `Stratholme_B` is the burning **city** — it
-/// names `StratholmeSkybox.m2` *and* 61 of its 83 groups set the bit, which is why the reference's
-/// sky in King's Square is a painted red sky and not map 329's khaki `Light.dbc` gradient.
-/// `Stratholme.wmo` is the **dungeon** next door: no MOSB, and not one of its 92 groups sets the bit.
-/// A regression that drops either half (the chunk parse, or the flag) shows up here as one of the two
-/// halves going quiet, and the two together are what keeps the gate off the chunk alone — four 1.12
-/// roots name a skybox no group ever asks for (`benilla-extract skyboxscan`).
+/// A WMO root's MOSB skybox and the per-group `0x40000` flag that asks for it: the Stratholme city
+/// root names one and 61 of 83 groups ask, the dungeon root names none. Four 1.12 roots name a
+/// skybox no group asks for, so the gate is the flag, not the chunk.
 #[test]
 fn reads_the_skybox_and_its_per_group_gate() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -1322,21 +1187,16 @@ fn reads_the_skybox_and_its_per_group_gate() {
     );
 }
 
-/// **The footstep chain's WMO leg, on the shipped bytes** (decision 1161, bug B236's sequel).
-///
-/// `MOMT+0x20` is a `TerrainType.dbc` id, and this is the evidence for that claim rather than a
-/// format doc: across every root WMO in the archive the dword only ever takes ids the table
-/// actually has, and `10 "None"` — the unauthored default — dominates. The Kharanos inn is the
-/// reported case: it authors `None` on all 20 materials, so the reference gives a walker its
-/// generic dry kit and NO footprint, where reading the ADT beneath the floor gives snow and snow
-/// prints.
+/// `MOMT+0x20` is a `TerrainType.dbc` id: every root WMO's values are table ids, mostly 10 "None".
+/// The Kharanos inn authors `None` on all 20 materials, so a walker there gets the generic dry step
+/// and no footprint, not the snow of the ADT beneath.
 #[test]
 fn wmo_ground_type_is_a_terrain_type_id() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
     let cat = benilla_formats::load_footstep_catalog(&mut chain).expect("footstep catalog");
 
-    // The Kharanos inn ("Thunderbrew Distillery" is the AREA name; the model is snow_Inn).
+    // The Kharanos inn: "Thunderbrew Distillery" is the area's name, the model is snow_Inn.
     let inn = chain
         .read_file("World\\wmo\\KhazModan\\Buildings\\Dwarven_Inn\\snow_Inn\\Snow_Inn.wmo")
         .expect("the Kharanos inn root");
@@ -1348,7 +1208,7 @@ fn wmo_ground_type_is_a_terrain_type_id() {
         "every Kharanos inn material is the unauthored `None`: {ground:?}"
     );
 
-    // `None` is not silence — it is a real row, and it is the quiet generic step.
+    // `None` is a real row: the quiet generic step.
     assert_eq!(
         cat.sound_class_of(10),
         Some(0),
@@ -1373,7 +1233,7 @@ fn wmo_ground_type_is_a_terrain_type_id() {
         "class 7 on snow: CharacterMediumLargeSnow — what the ADT-only chain wrongly played inside"
     );
 
-    // The value-domain argument, over every root WMO in the archive: nothing outside the table.
+    // Every root WMO in the archive (group files end in `_NNN`): no value outside the table.
     let roots: Vec<String> = chain
         .list()
         .expect("chain listing")
@@ -1416,18 +1276,10 @@ fn wmo_ground_type_is_a_terrain_type_id() {
     assert_eq!(multi, 121, "roots authoring more than one surface");
 }
 
-/// The **ghost sky** — `LightParams.lightSkyboxID` → `LightSkybox.dbc` → a model the chain can
-/// actually read. Pins all three joints of a path that was parsed and then dropped on the floor:
-/// the field was named in the schema and had zero consumers, so nothing caught that the table it
-/// indexes was never loaded at all.
-///
-/// The reference reaches this table only through the ghost override (`0x6d26cb`, gated on
-/// `[0xce9bb0] != -1`; wow-re `lighting/scratch/wmo-skybox.md` §3 + `death-light.md`), and the
-/// shipped data matches that gate exactly: 5 of 426 `LightParams` rows carry a non-zero id, all of
-/// them 3 = `DeathClouds.mdx`, reached from param slot **4** of every one of the 374 `Light` rows.
-/// So the answer is the same everywhere, which is what the spread of positions below asserts —
-/// including Deeprun Tram, the shipped map with no `Light` row of its own (it must still find the
-/// sky through the zero-match fallback row, not come back bare).
+/// The ghost sky: `LightParams.lightSkyboxID` -> `LightSkybox.dbc` -> a readable model. The
+/// reference reads it only through the ghost override (`0x6d26cb`, gated on `[0xce9bb0] != -1`).
+/// 5 of 426 `LightParams` rows carry an id, all 3 (`DeathClouds.mdx`), from param slot 4 of all
+/// 374 `Light` rows, so it resolves the same everywhere, Deeprun Tram's fallback row included.
 #[test]
 fn resolves_the_ghost_skybox_everywhere() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -1451,9 +1303,7 @@ fn resolves_the_ghost_skybox_everywhere() {
         );
     }
 
-    // The path is normalised to what the chain actually holds: the DBC authors `.mdx`, the archive
-    // ships `.m2`. Reading it here is the half that a name-only assert would miss — the render lane
-    // hands this exact string to `load_m2_mesh`.
+    // The DBC authors `.mdx`; the path is normalised to the `.m2` the archive ships.
     let bytes = chain
         .read_file(DEATH_CLOUDS)
         .expect("the ghost sky model the DBC names must be readable from the chain");
diff --git a/crates/benilla-formats/tests/chat_bubble_anchor_height.rs b/crates/benilla-formats/tests/chat_bubble_anchor_height.rs
index 8d4ca2af..29ecbc5f 100644
--- a/crates/benilla-formats/tests/chat_bubble_anchor_height.rs
+++ b/crates/benilla-formats/tests/chat_bubble_anchor_height.rs
@@ -1,28 +1,6 @@
-//! Pins the **chat bubble's** anchor height against real build-5875 assets — the sibling of
-//! `selection_ring_radius`, reading the same Stand-animation box on the other axis.
-//!
-//! The reference anchors the bubble at
-//!
-//! ```text
-//! worldZ = unit.z + (StandBox.max.z − StandBox.min.z) × modelScale + 0.7
-//! ```
-//!
-//! where the extent comes from `0x4b0e38 call 0x711a20` — which wow-re's anchor cross-check
-//! (2026-08-17) followed into the model layer and found reading the **MD20 header image**: file
-//! bytes, no bone matrix anywhere in the call tree, returning that CAaBox's Z. The scaled product
-//! is latched at `bubble+0x354` behind a parity guard, so it is queried once per chat line.
-//!
-//! Benilla shipped the bubble on the **posed PlayerName attachment** instead (the `0x608640`
-//! chain), on a recorded INFERRED claim that the two calls were equivalent — "both the head-region
-//! attachment height, model-scaled". They are not: they differ precisely on animated-vs-static.
-//! This test exists so that claim cannot come back by accident, and so the two heights stay
-//! distinguishable — they are close enough (2.01 vs 2.21 on a human male) that an eye cannot tell
-//! them apart on a human (2.01 vs 2.21) — which is exactly how the wrong one shipped. On a chicken
-//! they are not close at all (0.44 vs 0.81): Blizzard floats the *name* anchor well clear of a small
-//! model's head, while the bubble hugs the model. That spread is why the pair is pinned per model
-//! rather than as a single fudge factor. Decision 1406.
-//!
-//! Skips when the gitignored client data isn't present.
+//! The chat bubble anchors at `unit.z + (Stand.max.z - Stand.min.z) * modelScale + 0.7`
+//! (`0x4b0c30`): the Stand sequence box read from the file image (`0x4b0e38 call 0x711a20`),
+//! latched once per chat line at `bubble+0x354`, not the posed PlayerName attachment (`0x608640`).
 
 use benilla_formats::{load_m2_bounds, open_chain};
 
@@ -31,12 +9,8 @@ fn stand_box_z_is_the_bubble_anchor_height_and_not_the_attachment() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open chain");
 
-    // (model, the Stand box's Z extent, the PlayerName attachment-18 Z benilla used to anchor on).
-    // Both read straight out of the shipped M2s; the pair is the point — a test that only pinned
-    // the first would pass just as happily on the wrong source.
-    // All four numbers are read out of the shipped M2s, not estimated: the Stand box from the
-    // `M2Sequence` CAaBox at `animationLookup[0]` (record 0 for the human, record **2** for the
-    // chicken, whose record 0 is a flap), the attachment from the attachment table's id 18.
+    // (model, Stand box Z extent, attachment 18's Z), read off the shipped M2s. The Stand box is
+    // `animationLookup[0]`'s record: 0 for the human, 2 for the chicken, whose record 0 is a flap.
     let cases = [
         (
             "Character\\Human\\Male\\HumanMale.mdx",
@@ -53,16 +27,12 @@ fn stand_box_z_is_the_bubble_anchor_height_and_not_the_attachment() {
             "{path}: stand_box_z {:.4} should be the Stand CAaBox Z extent {stand_z}",
             b.stand_box_z
         );
-        // The two sources are genuinely different values, so a regression to the attachment cannot
-        // slip through the bound above.
         assert!(
             (b.stand_box_z - attach_z).abs() > 0.02,
             "{path}: stand_box_z {:.4} must not be the posed-attachment height {attach_z} — those \
              are the two mechanisms 1406 separated",
             b.stand_box_z
         );
-        // It is a height, and it is not the all-animation vertex box (which on a character runs far
-        // over the head — the reason that box is wrong for anything head-shaped).
         assert!(
             b.stand_box_z > 0.0,
             "{path}: a Stand box has positive height"
diff --git a/crates/benilla-formats/tests/ground_quad.rs b/crates/benilla-formats/tests/ground_quad.rs
index 262397bc..9d8c1d95 100644
--- a/crates/benilla-formats/tests/ground_quad.rs
+++ b/crates/benilla-formats/tests/ground_quad.rs
@@ -1,11 +1,5 @@
-//! Pins the ground-plane-quad detector ([`RenderSubmesh::ground_quad`]) against real build-5875
-//! assets — the shape the ground-fx decal lane (`benilla::ground_fx`) re-renders as projected
-//! surface decals. Battle Shout's cast-base model is the canonical population member (verified by
-//! hand off the raw M2, 2026-07-14: 24 vertices, all at z = 0 exactly, six 4-vert quads each
-//! fully weighted to one of bones {1, 2, 3, 5, 6, 7}, rect −0.776..0.212 × ±0.494); a character
-//! body model must detect NOTHING (its one incidentally-flat batch, if any, is not this shape at
-//! the base anchor — and regressing a body part into a decal would be spectacular). Skips when
-//! the gitignored client data isn't present.
+//! `RenderSubmesh::ground_quad`: the flat quads the ground-fx lane re-renders as projected decals.
+//! Battle Shout's cast base authors six 4-vertex quads at z = 0, each fully weighted to one bone.
 
 use benilla_formats::{open_chain, parse_m2_render_submeshes};
 
@@ -25,7 +19,7 @@ fn battle_shout_crescents_detect_as_ground_quads() {
             .ground_quad()
             .expect("every crescent batch is a ground quad");
         bones.push(quad.bone);
-        // The authored rect (raw M2 vertex table): x ∈ [−0.776, 0.212], y ∈ [−0.494, 0.494].
+        // The authored rect, read off the raw M2 vertex table.
         assert!((quad.corners[0][0] + 0.776).abs() < 1e-3, "min x");
         assert!((quad.corners[3][0] - 0.212).abs() < 1e-3, "max x");
         assert!((quad.corners[0][1] + 0.494).abs() < 1e-3, "min y");
@@ -36,12 +30,9 @@ fn battle_shout_crescents_detect_as_ground_quads() {
     assert_eq!(bones, [1, 2, 3, 5, 6, 7], "one quad per slide bone");
 }
 
-/// The HOVER population (the `groundscan` hover census, 2026-07-31): Consecration authors its
-/// 23-yard burn disc at z = 0.097 and its center glow at 0.207 — flat, uniform-z, just above the
-/// ground plane to dodge terrain z-fighting. Both must detect (the widened ceiling,
-/// `GROUND_HOVER_MAX`), with the authored hover preserved on the corners; and Flamestrike's model
-/// must decal exactly its two flat discs while its 3-D flame column, ribbons, and billboard glow
-/// stay off the lane.
+/// A disc authored just above the ground, under `GROUND_HOVER_MAX`, detects with its hover kept:
+/// Consecration's burn disc at z = 0.097, its glow at 0.207. Of Flamestrike's batches only the two
+/// flat discs detect.
 #[test]
 fn hovering_discs_detect_as_ground_quads() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -93,14 +84,9 @@ fn character_model_detects_no_ground_quads() {
     );
 }
 
-/// The quad's **static M2Color tint** ([`benilla_formats::GroundQuad::tint`]) — the constant the
-/// mesh path draws through its vertex-colour bake, which a decal consumer has no vertex buffer to
-/// carry. The Flare's ground wash is the case that named it: two 13.89-yd quads on the NEUTRAL
-/// `GENERICGLOW*` radials, whose entire colour is the constant `(0.992, 0.467, 0.0)` — drawn
-/// untinted, an additive pool of them blows white instead of laying down dim orange. Battle
-/// Shout's crescents are the other side of the same gate: their colour VARIES (white→red over the
-/// clip), so it rides `rgb_anim`, the vertex bake is cleared, and this must read white — that is
-/// what keeps the two from double-applying.
+/// `GroundQuad::tint` carries a static M2Color, which a decal has no vertex buffer for: the Flare's
+/// two 13.89-yd washes on neutral `GENERICGLOW*` radials are all `(0.992, 0.467, 0.0)`. An animated
+/// colour rides `rgb_anim` and the tint stays white, so the two never double-apply.
 #[test]
 fn ground_quads_carry_their_static_m2color_tint() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -116,12 +102,10 @@ fn ground_quads_carry_their_static_m2color_tint() {
         assert!((q.tint[0] - 0.992).abs() < 1e-3, "warm red: {:?}", q.tint);
         assert!((q.tint[1] - 0.467).abs() < 1e-3, "warm green: {:?}", q.tint);
         assert!(q.tint[2] < 1e-3, "no blue at all: {:?}", q.tint);
-        // 13.89 yd across — the wash the tint has to colour.
         let span = q.corners[3][0] - q.corners[0][0];
         assert!((span - 13.89).abs() < 0.02, "wash span {span}");
     }
 
-    // The animated twin: colour varies, so it rides `rgb_anim` and the vertex bake is cleared.
     let bytes = chain
         .read_file("Spells\\BattleShout_Cast_Base.m2")
         .expect("Battle Shout cast-base model");
diff --git a/crates/benilla-formats/tests/helm_vis_wants_a_helm.rs b/crates/benilla-formats/tests/helm_vis_wants_a_helm.rs
index 492e61c2..9f54642a 100644
--- a/crates/benilla-formats/tests/helm_vis_wants_a_helm.rs
+++ b/crates/benilla-formats/tests/helm_vis_wants_a_helm.rs
@@ -1,21 +1,12 @@
-//! B93 — a `HelmetGeosetVisData` hide mask only applies when the head display is a **worn helm**,
-//! i.e. it names a model. Real-data difftest against the shipped 1.12.1 DBCs, end to end from the
-//! NPC's `CreatureDisplayInfoExtra` row to the geosets her body renders. Skips when the client
-//! isn't present.
-//!
-//! The reported case is **Jubie Gadgetspring** (vmangos creature 8678 → `CreatureDisplayInfo`
-//! 7969 → extra **5503**): a gnome female whose head column names display **15676**, an
-//! `INV_Jewelry_Amulet_01` row with **no model** and a full hide mask (`HelmVisFemale` **306** =
-//! `[446, 478, 510, 222, 238]`, every column carrying the gnome bit `1 << 7`). 1.12.1 renders her
-//! pigtails, her long ears and her earrings; honouring the mask strips all three.
+//! A `HelmetGeosetVisData` hide mask applies only when the head display is a worn helm, one that
+//! names a model. Jubie Gadgetspring (display 7969, extra 5503) wears head display 15676, a
+//! model-less amulet row with a full gnome mask; the reference shows her hair, ears and earrings.
 
 use benilla_formats::{
     load_creature_catalog, load_item_display_catalog, open_chain, CharacterGeosets, EquipGeosets,
 };
 
-/// Jubie's `CreatureDisplayInfo` id — the chain's entry point.
 const JUBIE_DISPLAY: u32 = 7969;
-/// The amulet-shaped `ItemDisplayInfo` row her head column names.
 const AMULET_DISPLAY: u32 = 15676;
 
 #[test]
@@ -24,7 +15,6 @@ fn a_modelless_head_display_is_not_a_worn_helm() {
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
     let items = load_item_display_catalog(&mut chain).expect("ItemDisplayInfo");
 
-    // 1. The defect only exists if the shipped row really is model-less AND masked.
     let amulet = items.get(AMULET_DISPLAY).expect("display 15676 exists");
     assert!(
         amulet.model.iter().all(Option::is_none),
@@ -36,14 +26,12 @@ fn a_modelless_head_display_is_not_a_worn_helm() {
         [248, 306],
         "display {AMULET_DISPLAY} still carries a HelmetGeosetVisData pair"
     );
-    // 2. …and we now refuse to read it as a helm.
     assert_eq!(
         amulet.worn_helm_vis(),
         None,
         "a model-less display is not a worn helm"
     );
 
-    // 3. A real helm still hides what it should — the change must not disarm the mechanism.
     let (_, helm) = items
         .iter()
         .find(|(_, d)| d.model[0].is_some() && d.helmet_vis != [0, 0])
@@ -54,9 +42,7 @@ fn a_modelless_head_display_is_not_a_worn_helm() {
         "a modelled helm keeps its vis pair"
     );
 
-    // 4. The blast radius, pinned: of the 1314 rows that author a vis pair, exactly 12 leave the
-    //    LEFT model slot empty. If the shipped data ever changes, this test says so rather than the
-    //    change silently growing.
+    // Of the 1314 rows with a vis pair, 12 leave the left model slot empty.
     let masked = items.iter().filter(|(_, d)| d.helmet_vis != [0, 0]).count();
     let masked_modelless = items
         .iter()
@@ -64,10 +50,8 @@ fn a_modelless_head_display_is_not_a_worn_helm() {
         .count();
     assert_eq!((masked, masked_modelless), (1314, 12));
 
-    // 5. The gate is `ModelName[0]` alone (wow-re RF-0085, `0x4799c1`), not "either slot". 41 rows
-    //    fill only the RIGHT slot; none of them carries a vis pair, so the two readings coincide on
-    //    the shipped table — assert that rather than assume it, because the day one diverges the
-    //    reference's answer is the left slot's.
+    // The reference gates on `ModelName[0]` alone (`0x4799c1`); the 41 rows that fill only the
+    // right slot carry no vis pair.
     let right_only = items
         .iter()
         .filter(|(_, d)| d.model[0].is_none() && d.model[1].is_some())
@@ -110,8 +94,7 @@ fn jubie_keeps_her_hair_ears_and_earrings() {
         ..EquipGeosets::default()
     };
     let set = geosets.visible_geosets(npc.race, npc.sex, npc.hair_style, npc.facial_hair, &eg);
-    // CharHairGeosets (7,1,1) → 3 · CharacterFacialHairStyles (7,1,2) geoset200 3 → 203 · the
-    // ear region keeps its 702 default. All three are what the reference shows.
+    // CharHairGeosets (7,1,1) gives 3, CharacterFacialHairStyles (7,1,2) gives 203, ears keep 702.
     for want in [3u16, 203, 702] {
         assert!(set.contains(&want), "geoset {want} is on, got {set:?}");
     }
@@ -122,9 +105,7 @@ fn jubie_keeps_her_hair_ears_and_earrings() {
         );
     }
 
-    // The counterfactual — the shipped mask, honoured — is exactly the reported picture: bare
-    // scalp, no earrings, tucked ears. This is what the bug looked like, asserted so a regression
-    // has to walk past it.
+    // The mask, honoured: a bare scalp, no earrings and tucked ears.
     let broken = geosets.visible_geosets(
         npc.race,
         npc.sex,
diff --git a/crates/benilla-formats/tests/item_icons.rs b/crates/benilla-formats/tests/item_icons.rs
index 4126aec5..8b97374d 100644
--- a/crates/benilla-formats/tests/item_icons.rs
+++ b/crates/benilla-formats/tests/item_icons.rs
@@ -1,7 +1,4 @@
-//! Asset-gated fixture: the ItemDisplayInfo **icon** column against the real 5875 data — pins
-//! col 5 (see `src/items.rs`) to display ids the local vmangos DB actually pairs with known
-//! items, so a schema drift or column slip fails loudly. The model/geoset columns have their own
-//! synthetic tests in the adapter. Skips (passes) without `<repo>/WoW/Data`.
+//! The `ItemDisplayInfo` icon column (5), pinned to the display ids vmangos gives known items.
 
 use benilla_formats::{load_item_display_catalog, open_chain};
 
@@ -16,8 +13,7 @@ fn item_icons_resolve_known_display_ids() {
         catalog.len()
     );
 
-    // The icon-column derivation anchors, now as regressions — display ids straight from the
-    // server's item_template (the values the live wire answers for these items).
+    // Display ids from vmangos `item_template`.
     for (item, display_id, icon) in [
         ("Worn Shortsword", 1542, "Interface\\Icons\\INV_Sword_04"),
         ("Tough Jerky", 2473, "Interface\\Icons\\INV_Misc_Food_16"),
diff --git a/crates/benilla-formats/tests/light_area_blend_order.rs b/crates/benilla-formats/tests/light_area_blend_order.rs
index decc0fec..2cf61f13 100644
--- a/crates/benilla-formats/tests/light_area_blend_order.rs
+++ b/crates/benilla-formats/tests/light_area_blend_order.rs
@@ -1,27 +1,10 @@
-//! **The water swatch rides the area blend, and the blend applies spheres farthest-first.**
-//!
-//! Two halves of one law, byte-VERIFIED in wow-re (`system/lighting/scratch/ctb.md` §`0x6d2d00`
-//! + `scratch/merge.md`, the latter's drain reading corrected by an emulator difftest oracle):
-//!
-//! 1. `dn_light_select 0x6d2d00` pushes every `Light.dbc` row with `dist ≤ outer` into a **max-heap
-//!    keyed on DISTANCE** and drains it root-first — so the farthest light merges first and the
-//!    **nearest lands last and dominates**. A point inside the tightest sphere's inner radius
-//!    therefore resolves that sphere's `LightParams` **exactly**, whatever else overlaps it.
-//! 2. `dn_record_overblend 0x6d30e0` merges **all 18 colour slots** of the gather record per light —
-//!    its step-9 loop `+0x34..+0x40` is precisely IntBand rows 14–17, the ocean/river swatch. The
-//!    water tint is an ordinary band; the client has no single-sphere pick anywhere in that path.
-//!
-//! Both were wrong before decision 1104, and the two errors hid each other. Ordering by blend
-//! *weight* let a wide distant sphere land last and dilute a zone that fully contained the camera —
-//! which made the blended water read muddy, which is what the `pick_light` water split was
-//! introduced to dodge. The split then made the tint **discontinuous**: `pick_light` switches at a
-//! tighter sphere's *outer* radius, exactly where that sphere's own weight is still zero, so the
-//! Tirisfal→Silverpine border snapped green water to near-black brown in a single step (the
-//! director's report) while ambient, sun and fog crossed it without a flicker.
+//! The area blend applies spheres farthest-first and carries the water swatch. `0x6d2d00` heaps
+//! every `Light.dbc` row within its outer radius by distance and drains the farthest first, so the
+//! nearest merges last and dominates. `0x6d30e0` merges all 18 colour slots per light, the water
+//! swatch among them (IntBand rows 14-17, its step-9 loop `+0x34..+0x40`): no single-sphere pick.
 
 use benilla_formats::{Chain, LightCatalog, Submersion};
 
-/// Eastern Kingdoms.
 const MAP_EK: u32 = 0;
 /// Half-minutes; 1440 = noon.
 const NOON: u32 = 1440;
@@ -40,10 +23,8 @@ fn blend(cat: &LightCatalog, pos: [f32; 3]) -> benilla_formats::Atmosphere {
     cat.sample_blended(MAP_EK, pos, NOON, false, Submersion::Dry, false)
 }
 
-/// The director's two `.go` pins, 16 yd apart across the Tirisfal → Silverpine border. Light 4
-/// (falloff 985→1437 yd, `LightParams` 40) *enters* between them — at pin B the eye is 1434 yd out,
-/// three yards inside its outer radius, where its blend weight is 0.006. The area blend must
-/// therefore barely move; the old `pick_light` swatch instead switched wholesale to LP 40's rows.
+/// Two points 16 yd apart across the Tirisfal-Silverpine border. Light 4 (falloff 985-1437 yd,
+/// `LightParams` 40) enters between them: at the second the eye is 1434 yd out, weight 0.006.
 #[test]
 fn water_swatch_does_not_snap_at_the_tirisfal_silverpine_border() {
     let Some(cat) = catalog() else { return };
@@ -64,14 +45,12 @@ fn water_swatch_does_not_snap_at_the_tirisfal_silverpine_border() {
         );
     }
 
-    // The exact swatch on the Tirisfal side, so a future re-derivation moves this on purpose.
     assert_eq!(
         rgb(a.water_river[0]),
         [82, 93, 46],
         "river shallow at pin A"
     );
     assert_eq!(rgb(a.water_river[1]), [60, 88, 89], "river deep at pin A");
-    // The `pick_light` answers the old code committed — the snap, in both its endpoints.
     assert_ne!(
         rgb(b.water_river[1]),
         [35, 28, 37],
@@ -79,11 +58,8 @@ fn water_swatch_does_not_snap_at_the_tirisfal_silverpine_border() {
     );
 }
 
-/// Inside the tightest sphere's inner radius the nearest light merges **last** at weight 1, which is
-/// a full replace — so the blend equals that sphere's `LightParams` outright, even with two wider
-/// spheres also covering the point (here Light 31 / `LightParams` 46 reaches it at weight 0.195).
-/// Sorting the merge by weight instead put that 0.195 last and smeared 20% of a distant zone's
-/// palette over a zone the camera stands in the middle of.
+/// Inside the nearest sphere's inner radius it merges last at weight 1, a full replace, though two
+/// wider spheres also reach the point (Light 31, `LightParams` 46, at weight 0.195).
 #[test]
 fn the_nearest_sphere_dominates_where_it_is_at_full_weight() {
     let Some(cat) = catalog() else { return };
@@ -99,15 +75,14 @@ fn the_nearest_sphere_dominates_where_it_is_at_full_weight() {
         rgb(picked.water_river[0]),
         "river shallow"
     );
-    // LightParams 40's own rows, off the shipped bands — the identity, not just the agreement.
+    // LightParams 40's own rows, off the shipped bands.
     assert_eq!(rgb(blended.ambient), [80, 63, 79]);
     assert_eq!(rgb(blended.water_river[0]), [82, 64, 49]);
     assert_eq!(rgb(blended.water_river[1]), [35, 28, 37]);
 }
 
-/// The Stranglethorn anchor the `pick_light` split was built on (apitrace WoW.21: the river swatch
-/// reads `LightParams` 26 exactly, alpha 216/255). It never needed a pick — Light 9 covers the river
-/// at full weight, so the faithful nearest-last blend commits LP 26 whole.
+/// A reference frame capture reads Stranglethorn's river swatch as `LightParams` 26 exactly, alpha
+/// 216/255: Light 9 covers the river at full weight, so the blend commits it whole.
 #[test]
 fn the_stranglethorn_river_swatch_is_lightparams_26() {
     let Some(cat) = catalog() else { return };
diff --git a/crates/benilla-formats/tests/light_no_row_fallback.rs b/crates/benilla-formats/tests/light_no_row_fallback.rs
index b63ee709..b8bc78f0 100644
--- a/crates/benilla-formats/tests/light_no_row_fallback.rs
+++ b/crates/benilla-formats/tests/light_no_row_fallback.rs
@@ -1,24 +1,10 @@
-//! **A map with no `Light.dbc` row of its own falls back to record ID 1, not to an invention.**
-//!
-//! `Light.dbc` carries rows for 26 map ids; **Deeprun Tram (369) has none** — not even the
-//! falloff-0 `(0,0,0)` global that maps 0/1 carry. The client handles that in
-//! `dn_light_array_build 0x6d6170`: the per-map filter (`0x6d61a9 cmp [row+4], mapId`) matches
-//! nothing, and the tail (`0x6d62b2`–`0x6d62c9`) writes `idMap[1]` — the record whose **ID column**
-//! is 1, not row-index 1 — into slot 0. `dn_light_select 0x6d2d00` then no-ops (count ≤ 1 ⇒ empty
-//! blend heap) and the colour table commits that record whole. (wow-re
-//! `system/lighting/scratch/no-light-row-fallback.md`.)
-//!
-//! Row 1 is the Azeroth global → LightParams **12**, whose bands are an ordinary six-key day curve.
-//! Before this was wired, benilla substituted a hardcoded bright noon (fog `[140,183,234]` at
-//! 1000 yd) and the Tram's undersea stretch rendered as a daylight scene against the reference's
-//! deep blue. The numbers below are read straight off the shipped DBC — LightParams 12 → int bands
-//! 199..216 (sub-0 diffuse, sub-1 ambient, sub-7 fog) and float bands 67..72 (sub-0 fog end in
-//! inches, sub-1 start fraction) — so they pin the *identity of the record*, which is the part that
-//! was wrong.
+//! A map with no `Light.dbc` row falls back to the record whose id is 1. For Deeprun Tram (369)
+//! the per-map filter of `0x6d6170` matches nothing (`0x6d61a9`), the tail writes `idMap[1]` into
+//! slot 0 (`0x6d62b2`-`0x6d62c9`), `0x6d2d00` has nothing to blend, and that record, the Azeroth
+//! global with `LightParams` 12 (int bands 199..216, float bands 67..72), commits whole.
 
 use benilla_formats::{Chain, LightCatalog, Submersion};
 
-/// `Map.dbc` id of Deeprun Tram — the WMO-only map with no `Light.dbc` row.
 const MAP_DEEPRUN_TRAM: u32 = 369;
 /// Half-minutes; 1440 = noon.
 const NOON: u32 = 1440;
@@ -29,7 +15,7 @@ fn deeprun_tram_takes_light_record_1_not_an_invented_default() {
     let mut chain = Chain::open(&data).expect("open vanilla patch chain");
     let cat = LightCatalog::load(&mut chain).expect("load Light/LightParams/*Band");
 
-    // The Tram's own position is irrelevant — nothing covers it, which is the whole point.
+    // The position is irrelevant: no row covers any point of the map.
     let tram = cat.sample_blended(
         MAP_DEEPRUN_TRAM,
         [25.0, -1256.0, -117.0],
@@ -59,10 +45,7 @@ fn deeprun_tram_takes_light_record_1_not_an_invented_default() {
         tram.fog_start_frac
     );
 
-    // The fallback is a RECORD LOOKUP, not a per-map constant: every map with no row of its own
-    // lands on the same record, regardless of id or sample position. (Deliberately not compared
-    // against map 0 sampled at its origin — local Azeroth spheres cover that point and blend over
-    // the global, so it resolves [62,96,102], not the bare record.)
+    // Every map with no row lands on the same record, whatever its id or position.
     let other_rowless = cat.sample_blended(
         4242,
         [9000.0, -1000.0, 60.0],
@@ -77,7 +60,6 @@ fn deeprun_tram_takes_light_record_1_not_an_invented_default() {
         "any map with no Light.dbc row takes the same record 1"
     );
 
-    // And it is a real day curve, not a frozen constant: midnight differs from noon.
     let midnight = cat.sample_blended(
         MAP_DEEPRUN_TRAM,
         [25.0, -1256.0, -117.0],
@@ -93,18 +75,15 @@ fn deeprun_tram_takes_light_record_1_not_an_invented_default() {
     );
 }
 
-/// The scoping guard for the fix: the seven shipped maps that carry positioned rows but **no**
-/// `(0,0,0)` global are a *different* case, and one the byte finding does not settle (the reference
-/// seeds the array count at 1 and fills slots 1.. with the positioned rows, leaving slot 0
-/// unwritten). They must not be swept into the record-1 fallback on the strength of a guess.
+/// Seven maps have positioned rows but no `(0,0,0)` global: the reference fills slots 1.. and
+/// leaves slot 0 unwritten, an effect not traced, so they stay out of the record-1 fallback.
 #[test]
 fn maps_with_positioned_rows_but_no_global_are_left_alone() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = Chain::open(&data).expect("open vanilla patch chain");
     let cat = LightCatalog::load(&mut chain).expect("load Light/LightParams/*Band");
 
-    // Map 169 (Emerald Dream) carries 4 rows, none of them a global. Sampled far from all of them,
-    // it must NOT come back as record 1's atmosphere.
+    // Map 169 (Emerald Dream): 4 rows, none a global, sampled far from all of them.
     let far = cat.sample_blended(169, [0.0, 0.0, 0.0], NOON, false, Submersion::Dry, false);
     let tram = cat.sample_blended(
         MAP_DEEPRUN_TRAM,
diff --git a/crates/benilla-formats/tests/light_zero_key_band.rs b/crates/benilla-formats/tests/light_zero_key_band.rs
index 5ca418df..88345d33 100644
--- a/crates/benilla-formats/tests/light_zero_key_band.rs
+++ b/crates/benilla-formats/tests/light_zero_key_band.rs
@@ -1,28 +1,15 @@
-//! **A band row with no keyframes commits the reference's constant — black, or `+0.0` — never an
-//! invented daytime value.**
-//!
-//! 973 of the 7668 shipped `LightIntBand` rows and 132 of the 2556 `LightFloatBand` rows carry
-//! `numKeys == 0`. The colour evaluator `0x6d62e0` early-outs before touching the key arrays
-//! (count load `0x6d62ec`, guard `0x6d62ef`/`0x6d62f4`, store `0x6d62f6 mov [edi], 0xff000000`) and
-//! the scalar one does the same at `0x6d6489`/`0x6d648e` with `fld [0x7ffd74]` = `+0.0f`; both
-//! stores are immediates, and the copy into the colour table is unconditional — so the answer is
-//! not stale, not skipped, and not a static initialiser. (wow-re
-//! `system/lighting/scratch/band-zero-key-contract.md`; decision 1465.)
-//!
-//! benilla used to answer every one of those rows out of `Atmosphere::DEFAULT`, a hand-written
-//! "neutral daytime" palette meant for *no lighting data at all*. Report **B90** is what that cost:
-//! `LightParams` 36 (Blasted Lands / the Tainted Scar) leaves the cloud gradient base unkeyed, so
-//! the cloud layer took a pale grey `[0.75, 0.78, 0.82]` where the data says black — and the zone
-//! authors cloud density 0.85, so that layer *is* the sky there. The reporter saw pure white.
+//! A band row with no keyframes commits the reference's constant, black or `+0.0`: the colour
+//! evaluator `0x6d62e0` stores `0xff000000` (guard `0x6d62ef`, store `0x6d62f6`), the scalar one
+//! `+0.0f` (`0x6d6489`, `fld [0x7ffd74]`), and both copy on unconditionally. 973 of 7668
+//! `LightIntBand` rows and 132 of 2556 `LightFloatBand` rows are keyless.
 
 use benilla_formats::{Chain, LightCatalog, ZERO_KEY_COLOR, ZERO_KEY_SCALAR};
 
 /// Half-minutes; 1440 = noon.
 const NOON: u32 = 1440;
-/// Blasted Lands' clear-weather `LightParams` — the B90 record. Its `LightIntBand` sub-12
-/// (cloud gradient base) is id `(36-1)*18 + 13 = 643`, `numKeys = 0`.
+/// Blasted Lands' clear `LightParams`; its cloud gradient base, `LightIntBand` 643, has no keys.
 const PARAMS_BLASTED_LANDS: u32 = 36;
-/// Elwynn / the Azeroth global — the control. Its sub-12 is authored, and authored *black*.
+/// The Azeroth global's clear `LightParams`; its cloud gradient base is keyed, and black.
 const PARAMS_ELWYNN: u32 = 12;
 
 fn params(id: u32) -> Option<benilla_formats::Atmosphere> {
@@ -41,13 +28,11 @@ fn the_blasted_lands_cloud_base_is_black_not_a_pale_invention() {
         return;
     };
 
-    // The defect: this used to be `[0.75, 0.78, 0.82]`.
     assert_eq!(
         atmo.cloud_colors[2], ZERO_KEY_COLOR,
         "sub-12 is keyless for LightParams 36 — the cloud gradient base must be black"
     );
-    // Its two neighbours ARE authored, and must be untouched by the change: this is what proves the
-    // fix reads the row rather than blanking the palette.
+    // Its authored neighbours: the row is read, not the palette blanked.
     let rgb = |c: [f32; 3]| c.map(|v| (v * 255.0).round() as i32);
     assert_eq!(
         rgb(atmo.cloud_colors[0]),
@@ -59,7 +44,6 @@ fn the_blasted_lands_cloud_base_is_black_not_a_pale_invention() {
         [0, 34, 88],
         "sub-11 gradient slope"
     );
-    // And the density that makes this zone show the defect at all.
     assert!(
         (atmo.cloud_density - 0.85).abs() < 1e-6,
         "Blasted Lands authors C = 0.85 (Elwynn's is 0.50): near-total overcast"
@@ -72,13 +56,11 @@ fn an_authored_black_and_a_keyless_row_agree_which_is_why_the_data_reads_as_it_d
         return;
     };
 
-    // Elwynn's sub-12 has keys — and they are (0,0,0). 209 of the 308 keyed gbase rows are exactly
-    // that, 288 have max channel < 64, and NOT ONE is pale. A pale fallback was never plausible.
+    // 209 of the 308 keyed cloud-base rows are (0,0,0), and 288 have every channel under 64.
     assert_eq!(
         elwynn.cloud_colors[2], ZERO_KEY_COLOR,
         "LightParams 12 authors its cloud base as black"
     );
-    // The control that must not move: Elwynn's authored slope/sun.
     let rgb = |c: [f32; 3]| c.map(|v| (v * 255.0).round() as i32);
     assert_eq!(
         rgb(elwynn.cloud_colors[1]),
@@ -95,8 +77,7 @@ fn an_authored_black_and_a_keyless_row_agree_which_is_why_the_data_reads_as_it_d
 
 #[test]
 fn a_keyless_scalar_row_is_zero_not_a_thousand_yards() {
-    // LightParams 95 is a clear-underwater slot on map 269 whose fog-end AND fog-start rows are
-    // both keyless. The old `.filter(|v| v > 1.0)` turned that into 1000 yd of daylight fog.
+    // LightParams 95, a clear-underwater slot on map 269, has keyless fog-end and fog-start rows.
     let Some(atmo) = params(95) else { return };
     assert_eq!(
         atmo.fog_end, ZERO_KEY_SCALAR,
@@ -108,10 +89,8 @@ fn a_keyless_scalar_row_is_zero_not_a_thousand_yards() {
 
 #[test]
 fn a_params_id_above_the_id_gaps_still_reads_its_own_bands() {
-    // `LightParams` ids run 1..499 across 426 records — 73 gaps. The band-row id is derived from the
-    // params **ID** (`(p-1)*18 + b + 1`), so keying that lookup by row *position* would hand every
-    // group past the first gap another zone's bands, and the zero-key arm would then be firing on
-    // the wrong record entirely. 499 is the very last id; these are its own authored rows.
+    // `LightParams` ids run 1..499 over 426 records, and a band-row id derives from the params id,
+    // `(p-1)*18 + b + 1`, not its row position. 499 is the last id.
     let Some(atmo) = params(499) else { return };
     let rgb = |c: [f32; 3]| c.map(|v| (v * 255.0).round() as i32);
     assert_eq!(rgb(atmo.ambient), [75, 97, 124], "sub-1");
@@ -119,7 +98,6 @@ fn a_params_id_above_the_id_gaps_still_reads_its_own_bands() {
     assert_eq!(rgb(atmo.fog_color), [107, 114, 136], "sub-7");
     assert_eq!(rgb(atmo.sky[0]), [54, 56, 73], "sub-2");
     assert_eq!(rgb(atmo.sky[4]), [117, 124, 149], "sub-6");
-    // ...and its own keyless rows still answer black, on a record reached through the gaps.
     assert_eq!(atmo.cloud_colors[2], ZERO_KEY_COLOR, "sub-12 keyless");
     assert!(
         (atmo.fog_end - 14000.0 / 36.0).abs() < 1e-3,
diff --git a/crates/benilla-formats/tests/m2_anim_events.rs b/crates/benilla-formats/tests/m2_anim_events.rs
index 26eec6ff..2a4073da 100644
--- a/crates/benilla-formats/tests/m2_anim_events.rs
+++ b/crates/benilla-formats/tests/m2_anim_events.rs
@@ -1,10 +1,5 @@
-//! M2 anim-event regression test against real vanilla creatures (decision 0070 slice 3).
-//!
-//! Guards the event-track parse (events @MD20 0x114, stride 44, timestamps on the global
-//! sequence timeline — byte-verified on DireWolf.m2): every event key must land inside its
-//! sequence's `[0, duration]` window after the rebase, footstep tags must exist on walking
-//! creatures, and the identifier bytes must be forward-stored printable `$xxx` tags (a reversed
-//! read would produce `xxx$`). Skips when the client isn't present.
+//! M2 events: the table at MD20 `0x114`, 44 bytes a record, its keys timed on the global sequence
+//! timeline and rebased into each sequence; tags are stored forward, `$xxx`.
 
 use benilla_formats::{open_chain, parse_m2_animations};
 
@@ -49,17 +44,9 @@ fn creature_anim_events_parse_within_sequences() {
     }
 }
 
-/// **A fired key carries its OWN record's `(bone, position)`, not the tag's first match**
-/// (decision 1904). The reference's M2 event kernel `0x719370` snapshots
-/// `placementMatrix · (boneMatrix[event.bone] · event.position)` by value into the callback record
-/// every dispatcher reads, so *where* a key fires is a property of the record, and a consumer that
-/// re-finds the tag in the marker table by 4CC answers the wrong point wherever a model authors
-/// that tag twice.
-///
-/// It authors it twice a lot: **every player character model carries six `$CSD` records**, one per
-/// emote clip, each on its own bone. Pinned against `HumanMale.m2` — if the parse ever collapsed
-/// the records (or dropped the two new fields back to zero), the emote voices would all speak from
-/// the first one's bone.
+/// A fired key carries its own record's bone and position, not the tag's first match: the event
+/// kernel `0x719370` snapshots `placementMatrix · (boneMatrix[event.bone] · event.position)` into
+/// the callback record. Every player model authors six `$CSD` records, one per emote clip.
 #[test]
 fn a_fired_key_carries_its_own_records_bone_and_point() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -67,7 +54,6 @@ fn a_fired_key_carries_its_own_records_bone_and_point() {
     let model = "Character\\Human\\Male\\HumanMale.m2";
     let bytes = chain.read(model).expect("model bytes");
 
-    // The table's own records, and the per-sequence keys that fire them.
     let markers = benilla_formats::parse_m2_event_markers(&bytes).expect("event markers");
     let csd_records: Vec<_> = markers.iter().filter(|m| &m.ident == b"$CSD").collect();
     assert_eq!(
@@ -83,8 +69,6 @@ fn a_fired_key_carries_its_own_records_bone_and_point() {
         "{model}: the six records are distinct — a first-match lookup cannot stand in for them"
     );
 
-    // Every fired `$CSD` key must name one of those records, and across the model's sequences the
-    // keys must reach MORE THAN ONE of them — which is exactly what a by-4CC resolve could not do.
     let anims = parse_m2_animations(&bytes);
     let mut fired: std::collections::BTreeSet<(u16, [u32; 3])> = Default::default();
     for a in &anims {
diff --git a/crates/benilla-formats/tests/m2_authored_box_is_the_animated_extent.rs b/crates/benilla-formats/tests/m2_authored_box_is_the_animated_extent.rs
index d51941ee..623cdc39 100644
--- a/crates/benilla-formats/tests/m2_authored_box_is_the_animated_extent.rs
+++ b/crates/benilla-formats/tests/m2_authored_box_is_the_animated_extent.rs
@@ -1,18 +1,6 @@
-//! The birds that blink out when you turn the camera (decision 1259).
-//!
-//! `World\critter\birds\Bird01.m2` is the model that separates a **bind-pose** bound from an
-//! **all-animation** one. Its geometry is a single 1.2 × 1.8 × 0.23 yd bird, modelled once at the
-//! origin — and its only sequence keys bone 0 with a translation track that flies that bird 64 yd
-//! along X and 17 yd along Y, a slow circuit over the treetops. A placed doodad's submesh entity
-//! keeps its transform at the placement origin and lets the joint palette move the vertices, so a
-//! bound derived from the bind-pose mesh describes a 1-yd box the bird has long since left: turn the
-//! camera until that box exits the frustum and the bird vanishes while still on screen.
-//!
-//! The authored header box is the fix's source, and this pins that it really is the animated extent
-//! — off the shipped file, so the premise can't rot. What consumes it (`m2_anim_bound` → the
-//! per-submesh `Aabb` of an animated placement) is pinned by `benilla-world`'s own unit tests.
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! An M2's authored header box is its animated extent, not its bind pose: `Bird01.m2` is one small
+//! bird at the origin whose only sequence flies bone 0 64 yd along X, so a bound taken from the
+//! vertices culls the bird while it is still on screen.
 
 use benilla_formats::{open_chain, parse_m2_animations, parse_m2_bounds};
 
@@ -24,8 +12,6 @@ fn the_birds_authored_box_covers_a_flight_path_its_bind_pose_never_hints_at() {
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
     let bytes = chain.read_file(BIRD).expect("Bird01.m2 in the chain");
 
-    // 1. The mechanism: bone 0 — the root every other bone hangs off — is keyed with a translation
-    //    track tens of yards wide. Without this the model would need no special bound at all.
     let anims = parse_m2_animations(&bytes);
     let root = anims
         .iter()
@@ -45,10 +31,8 @@ fn the_birds_authored_box_covers_a_flight_path_its_bind_pose_never_hints_at() {
         hi[0] - lo[0]
     );
 
-    // 2. The premise: the AUTHORED header box is that flight path, not the bird. Its half-diagonal
-    //    is the reference's own cull radius (`rec+0x68` = `bounding_sphere_radius × scale`,
-    //    wow-5875-re `terrain/scratch/doodad-emitter-drawset-gate.md` §1c) — so a ~35 yd sphere
-    //    around a 0.6 yd body is what the real client tests, and it never blinks.
+    // The reference culls on the authored sphere, `rec+0x68` = `bounding_sphere_radius × scale`
+    // (`0x682ef0` -> `0x686b80`), about 35 yd around this bird.
     let b = parse_m2_bounds(&bytes).expect("Bird01 bounds");
     let box_x = b.bbox_max[0] - b.bbox_min[0];
     assert!(
@@ -61,8 +45,7 @@ fn the_birds_authored_box_covers_a_flight_path_its_bind_pose_never_hints_at() {
         b.sphere_radius
     );
 
-    // 3. …and the bind pose is not remotely it: the vertex extent — the box Bevy's
-    //    `calculate_bounds` derives, and what a placed submesh was culled with — is one small bird.
+    // The vertex extent, the box Bevy's `calculate_bounds` derives, is one small bird.
     let model = benilla_m2::parse_m2(&mut std::io::Cursor::new(&bytes[..])).expect("parse Bird01");
     let (mut vlo, mut vhi) = ([f32::MAX; 3], [f32::MIN; 3]);
     for v in &model.model().vertices {
@@ -79,7 +62,6 @@ fn the_birds_authored_box_covers_a_flight_path_its_bind_pose_never_hints_at() {
         widest < 3.0,
         "the bind-pose geometry is one small bird, widest axis {widest} yd"
     );
-    // The gap IS the bug: the authored box reaches this far past the bind-pose box.
     let slack = (0..3).fold(0.0f32, |s, a| {
         s.max(vlo[a] - b.bbox_min[a]).max(b.bbox_max[a] - vhi[a])
     });
diff --git a/crates/benilla-formats/tests/m2_billboard.rs b/crates/benilla-formats/tests/m2_billboard.rs
index bba4a02c..4ae467fc 100644
--- a/crates/benilla-formats/tests/m2_billboard.rs
+++ b/crates/benilla-formats/tests/m2_billboard.rs
@@ -1,5 +1,4 @@
-//! Difftest M2 billboard-bone detection against the real Lamppost: its glow card (GLOW32.BLP) rides a
-//! spherical billboard bone (flag 0x08); its post does not. Skips when the client isn't present.
+//! The Lamppost's glow card rides a spherical billboard bone (flag 0x08); its post does not.
 
 use benilla_formats::{load_m2_mesh, open_chain, BillboardKind};
 
@@ -13,7 +12,6 @@ fn lamppost_glow_is_spherical_billboard() {
     )
     .expect("load Lamppost");
 
-    // The glow card is a billboard; at least one batch (the post) is not.
     let spherical = subs
         .iter()
         .filter_map(|s| s.billboard.as_ref())
@@ -30,9 +28,7 @@ fn lamppost_glow_is_spherical_billboard() {
     );
     eprintln!("lamppost billboard pivot = {:?}", bb.pivot);
 
-    // The glow card's spherical billboard bone carries a global-sequence SCALE pulse (the "breathe"):
-    // 5 keys oscillating ~0.86..1.04 over the 1333 ms global sequence. This is what makes the lamppost
-    // glow pulse in the reference. Verified against the real Lamppost.m2 (bone[4] scale track, gseq 0).
+    // The glow's pulse: bone 4's scale track on global sequence 0, 5 keys, 0.86..1.04.
     let anim = bb
         .scale_anim
         .as_ref()
@@ -40,7 +36,6 @@ fn lamppost_glow_is_spherical_billboard() {
     assert_eq!(anim.duration_ms, 1333, "global sequence loop length (ms)");
     assert_eq!(anim.keys.len(), 5, "scale keyframe count");
     assert!(anim.interp, "the scale track interpolates (interp != 0)");
-    // It is a genuine pulse: the sampled scale varies over the loop, and stays in a sane breathe range.
     let samples: Vec<f32> = (0..anim.duration_ms)
         .step_by(33)
         .map(|t| anim.sample(t)[0])
@@ -56,7 +51,6 @@ fn lamppost_glow_is_spherical_billboard() {
         hi - lo > 0.1,
         "the pulse has visible amplitude, got {lo}..{hi}"
     );
-    // Uniform scale (x == y == z) at an arbitrary phase — a billboard card scales evenly.
     let s = anim.sample(700);
     assert!(
         (s[0] - s[1]).abs() < 1e-6 && (s[1] - s[2]).abs() < 1e-6,
diff --git a/crates/benilla-formats/tests/m2_billboard_card_face.rs b/crates/benilla-formats/tests/m2_billboard_card_face.rs
index 5346fae7..630585e5 100644
--- a/crates/benilla-formats/tests/m2_billboard_card_face.rs
+++ b/crates/benilla-formats/tests/m2_billboard_card_face.rs
@@ -1,19 +1,11 @@
-//! Difftest the **billboard-card lit-face** shape (decision 0788) against real content: which
-//! billboard batches are authored back-to-front against the law's `+X`-at-the-viewer, and — the
-//! load-bearing half — which must NOT be touched.
-//!
-//! `RenderSubmesh::billboard_card_faces_away` decides whether a consumer turns a card's normals
-//! round so it is lit off the face it presents. Get it wrong in the permissive direction and 3-D
-//! billboard geometry loses its shading; get it wrong in the strict direction and the cards go on
-//! swinging warm/cool with the camera. Both sides are pinned here on the shipped assets. Skips
-//! when the client isn't present.
+//! `RenderSubmesh::billboard_card_faces_away`: a flat billboard card whose normals sit on the −X
+//! side, away from the viewer its bone turns `+X` to, is lit off the face it presents; 3-D
+//! billboard geometry keeps its normals.
 
 use benilla_formats::{load_m2_mesh, open_chain, BillboardKind};
 
-/// The hanging shop sign — the report this shape came from. Its two "chains" are not chain geometry
-/// at all but a pair of 4-vert lock-Z billboard cards on a tiled chain texture, each authored with
-/// its whole plane's normal on the −X side, i.e. facing away from the viewer the law points them at.
-/// The sign body is ordinary geometry and must stay untouched.
+/// The shop sign's two chains are 4-vertex lock-Z billboard cards on a tiled chain texture, each
+/// plane's normal on the −X side; the sign body is ordinary geometry.
 #[test]
 fn the_shop_signs_chain_cards_face_away_and_its_body_is_untouched() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -50,9 +42,8 @@ fn the_shop_signs_chain_cards_face_away_and_its_body_is_untouched() {
     );
 }
 
-/// The negative that matters: the questgiver `?` marker is a lock-Z billboard too, but its geometry
-/// is 3-D (hundreds of verts, normals pointing every way round it). A rule that flipped every −X
-/// normal on a billboard batch would gut its shading, so the shape demands ONE plane.
+/// The questgiver `?` marker is a lock-Z billboard too, but 3-D, its normals pointing every way:
+/// only a single plane counts as a card.
 #[test]
 fn the_questgiver_marker_is_3d_billboard_geometry_not_a_card() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -78,9 +69,7 @@ fn the_questgiver_marker_is_3d_billboard_geometry_not_a_card() {
     }
 }
 
-/// The shape's remaining arms, on synthetic normals (no assets needed): an EDGE-ON card has no
-/// facing to correct, the already-correct majority is untouched, degenerate normals never flip,
-/// and a non-billboard batch is out of scope however it is normalled.
+/// The rule's other arms, on synthetic normals.
 #[test]
 fn the_shape_ignores_edge_on_correct_and_degenerate_batches() {
     use benilla_formats::{Billboard, ModelBlend, RenderSubmesh};
@@ -134,7 +123,6 @@ fn the_shape_ignores_edge_on_correct_and_degenerate_batches() {
         card(vec![[-1.0, 0.0, 0.0]; 4], true).billboard_card_faces_away(),
         "the away-facing card (the control) flips"
     );
-    // Soft/averaged authoring: unnormalised and a hair off plane — still one card.
     assert!(
         card(vec![[-0.98, 0.01, -0.02], [-1.02, -0.01, 0.01]], true).billboard_card_faces_away(),
         "a soft-normal card is still one plane"
diff --git a/crates/benilla-formats/tests/m2_bone_spin.rs b/crates/benilla-formats/tests/m2_bone_spin.rs
index 48e9112c..243e0b3a 100644
--- a/crates/benilla-formats/tests/m2_bone_spin.rs
+++ b/crates/benilla-formats/tests/m2_bone_spin.rs
@@ -1,22 +1,14 @@
-//! The **rigid bone spin** collector (`m2_bone_spins`) and its sampler — the mechanism that turns
-//! Caverns of Time's asteroid belts without a skinning palette (decision 1264's deferred half).
-//!
-//! Two halves, deliberately separate: the sampler is pure arithmetic and is pinned on synthetic
-//! keys, and the collector is pinned against the real shipped art, because what it has to get right
-//! is not arithmetic — it is *which* bones qualify. Both shipped skyboxes are asserted, including
-//! the one that must yield nothing: a predicate that accidentally admitted every bone would still
-//! look correct on the model that has motion.
+//! The rigid bone spin collector (`m2_bone_spins`) and its sampler, which turn Caverns of Time's
+//! asteroid belts without a skinning palette.
 
 use benilla_formats::{load_m2_bone_spins, m2_bone_spins, BoneSpin, Chain};
 
-/// `[x, y, z, w]` for a rotation of `deg` about +Z — the axis-agnostic half of the sampler tests.
 fn about_z(deg: f32) -> [f32; 4] {
     let h = deg.to_radians() * 0.5;
     [0.0, 0.0, h.sin(), h.cos()]
 }
 
-/// The angle (degrees) of a quaternion about its axis, sign-normalised — what a test can compare
-/// without caring which of `q`/`−q` the slerp produced.
+/// A quaternion's angle about its axis in degrees, the same for `q` and `-q`.
 fn angle_deg(q: [f32; 4]) -> f32 {
     let w = q[3].abs().clamp(0.0, 1.0);
     2.0 * w.acos().to_degrees()
@@ -31,11 +23,8 @@ fn spin(keys: Vec<(f32, [f32; 4])>, duration: f32, interp: bool) -> BoneSpin {
     }
 }
 
-/// The sampler's four legs: hold before the first key, slerp between a bracket, clamp past the
-/// last, and wrap at the duration. The clamp is the one worth stating out loud — an M2 track's keys
-/// live inside the sequence band and the client interpolates within it, so a loop whose last key
-/// differs from its first *snaps* at the wrap. Inventing a wrap-around segment would be us
-/// animating rather than the file.
+/// Past the last key the sampler clamps: the reference interpolates only within the sequence band,
+/// so a loop whose last key differs from its first snaps at the wrap.
 #[test]
 fn the_sampler_holds_slerps_clamps_and_wraps() {
     let s = spin(
@@ -64,9 +53,7 @@ fn the_sampler_holds_slerps_clamps_and_wraps() {
     );
 }
 
-/// A step track (`interp_type == 0`) holds each key until the next. Our rig lane lerps these — a
-/// recorded divergence (`benilla-extract bonescan`) — and there is no reason to reproduce it in new
-/// code when the track's own header word is right there.
+/// A step track (`interp_type == 0`) holds each key until the next.
 #[test]
 fn a_step_track_holds_its_key() {
     let s = spin(
@@ -78,8 +65,7 @@ fn a_step_track_holds_its_key() {
     assert!((angle_deg(s.sample(2.0)) - 90.0).abs() < 1e-3);
 }
 
-/// The shortest-arc negation in the slerp. Without it a bracket whose keys dot negative takes the
-/// LONG way round — which on a belt authored as a full turn reads as a section spinning backwards.
+/// Keys whose quaternions dot negative slerp the short way round.
 #[test]
 fn the_slerp_takes_the_short_way_round() {
     // 350° and 0° are 10° apart, but their quaternions dot negative.
@@ -89,18 +75,14 @@ fn the_slerp_takes_the_short_way_round() {
         true,
     );
     let mid = angle_deg(s.sample(0.5));
-    // 355° about +Z is 5° about −Z — either reading is ≤10° from both ends. The long way round
-    // would put the midpoint ~175° away.
     assert!(
         !(15.0..=345.0).contains(&mid),
         "midpoint took the long arc: {mid}°"
     );
 }
 
-/// The real asset. `CavernsOfTimeSky.m2` authors exactly three spinning bones — the asteroid belts,
-/// one 66.667 s loop, 25° / 90° / 360° of turn — and bone 0, which carries the other 17 batches,
-/// must NOT be among them (it has no track at all, and a collector that admitted it would rotate the
-/// entire painted sky).
+/// `CavernsOfTimeSky.m2` spins three bones, the asteroid belts, over one 66.667 s loop (25°, 90°,
+/// 360°); bone 0, which carries the other 17 batches, has no track.
 #[test]
 fn the_caverns_of_time_sky_spins_exactly_its_three_belt_bones() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -131,16 +113,14 @@ fn the_caverns_of_time_sky_spins_exactly_its_three_belt_bones() {
             angle_deg(s.keys[0].1) < 1e-2,
             "bone {bone}: the loop opens unrotated"
         );
-        // The authored total turn, read at the last key. 360° comes back as 0° through `acos`
-        // (the quaternion is back at identity), which is itself the thing to assert.
+        // The total turn at the last key; 360° reads back as 0°, the identity.
         let last = angle_deg(s.keys.last().expect("keyed").1);
         let expect = if turn >= 360.0 { 0.0 } else { turn };
         assert!(
             (last - expect).abs() < 0.5,
             "bone {bone}: expected {expect}° at the final key, got {last}°"
         );
-        // The pivot is a few yards off the model origin — which is exactly why the placement has to
-        // conjugate by it rather than rotate about the origin (the eye sits AT the origin).
+        // The pivot sits yards off the origin, where the eye is, so the spin conjugates by it.
         let d = (s.pivot[0].powi(2) + s.pivot[1].powi(2) + s.pivot[2].powi(2)).sqrt();
         assert!(
             (2.0..5.0).contains(&d),
@@ -149,9 +129,7 @@ fn the_caverns_of_time_sky_spins_exactly_its_three_belt_bones() {
     }
 }
 
-/// The other shipped skybox has no animation at all, and the collector must say so. This is the
-/// half that catches a predicate gone loose: `StratholmeSkybox` is three static opaque batches, and
-/// anything it returns here is a bone the file never keys.
+/// `StratholmeSkybox` is three static opaque batches: nothing spins.
 #[test]
 fn the_stratholme_sky_spins_nothing() {
     let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-formats/tests/m2_cold_breath.rs b/crates/benilla-formats/tests/m2_cold_breath.rs
index 519a7af9..ecdf27fb 100644
--- a/crates/benilla-formats/tests/m2_cold_breath.rs
+++ b/crates/benilla-formats/tests/m2_cold_breath.rs
@@ -1,28 +1,15 @@
-//! The cold-breath puff, pinned against the shipped assets (`#bugs` B233, decision 1149).
-//!
-//! B233 was reported as a **player character in Dun Morogh** with no visible breath, and the fix
-//! rests on three asset facts that a mechanism note alone cannot establish — the trap decision
-//! 0705 names, where a verified mechanism turns out not to *apply* to the thing in front of you:
-//!
-//! 1. the trigger exists on the reported model — `HumanMale.m2` authors a **`$BTH` event on
-//!    animation id 0 (Stand)**, so an idle player fires one every loop with no timer of ours;
-//! 2. the attach tag the client passes, **`0x11` = AttachmentID 17**, resolves on that model to a
-//!    bone at the **mouth**, not the base — the difference between vapour at the face and a cloud
-//!    at the feet;
-//! 3. the asset the DBC names is a **one-shot emitter**, so the client's end-of-clip terminator is
-//!    the right lifetime for it (`FxStage::OneShot`, as the mount poof uses).
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! The cold-breath puff: `HumanMale.m2` keys a `$BTH` event on Stand, so an idle player fires one
+//! every loop; its attach tag `0x11` (AttachmentID 17) is a bone at the mouth; and the puff model
+//! is one-shot, so the end-of-clip terminator is its lifetime.
 
 use benilla_formats::{open_chain, parse_m2_animations, parse_m2_attachments};
 
 const HUMAN_MALE: &str = "Character\\Human\\Male\\HumanMale.m2";
-/// `SpellVisualEffectName` row 107 (`"HARDCODED Breath Cold"`) names `Particles\ColdBreath.mdl`;
-/// the loader's own extension swap makes that the shipped `.m2`.
+/// `SpellVisualEffectName` 107, "HARDCODED Breath Cold", names `Particles\ColdBreath.mdl`, which
+/// ships as `.m2`.
 const COLD_BREATH: &str = "Particles\\ColdBreath.m2";
-/// The `$BTH` family's attach tag — `DAT_0080c968[3]`, a raw M2 `AttachmentID`.
+/// The `$BTH` family's attach tag, `DAT_0080c968[3]`: a raw M2 `AttachmentID`.
 const BREATH_ATTACH: u16 = 0x11;
-/// `AnimationData.dbc` id 0 = Stand.
 const STAND: u16 = 0;
 
 #[test]
@@ -33,7 +20,6 @@ fn the_idle_player_keys_bth_and_attaches_it_at_the_mouth() {
         .read_file(HUMAN_MALE)
         .expect("HumanMale is in the chain");
 
-    // (1) The trigger, on the animation an idle player is actually in.
     let anims = parse_m2_animations(&bytes);
     let stand = anims
         .iter()
@@ -51,8 +37,7 @@ fn the_idle_player_keys_bth_and_attaches_it_at_the_mouth() {
         "Stand keys exactly one $BTH; got {bth:?} over a {:.3}s clip",
         stand.duration
     );
-    // 0.667 s into a 2.667 s loop: the clip is comfortably longer than ColdBreath's own 1.5 s, so
-    // consecutive puffs never overlap on an idling player and the overlap guard never bites.
+    // 0.667 s into a 2.667 s loop, longer than the 1.5 s puff, so puffs never overlap.
     assert!(
         (bth[0] - 0.667).abs() < 0.01,
         "the $BTH key sits at 0.667s, got {:.3}s",
@@ -64,15 +49,13 @@ fn the_idle_player_keys_bth_and_attaches_it_at_the_mouth() {
         stand.duration
     );
 
-    // (2) The attach point: tag 0x11 through the model's OWN AttachLookup (the `0x710310`
-    // indirection — the tag is an id, never an array index), landing at the mouth.
+    // The tag is an attachment id, never an index, resolved through the AttachLookup (`0x710310`).
     let attachments = parse_m2_attachments(&bytes).expect("parse attachments");
     let breath = attachments
         .iter()
         .find(|a| a.id == BREATH_ATTACH)
         .expect("HumanMale authors attachment 0x11");
-    // The head attach (id 11) is the neighbour that makes "mouth" mean something: the breath point
-    // sits just below it and forward of it, on the face — not at the unit base (z ≈ 0).
+    // The mouth sits just below and forward of the head attachment, id 11.
     let head = attachments
         .iter()
         .find(|a| a.id == 11)
@@ -94,9 +77,6 @@ fn the_idle_player_keys_bth_and_attaches_it_at_the_mouth() {
         "the breath rides a real bone, not the model root"
     );
 
-    // (3) The puff itself: a single non-looping sequence, so the end-of-clip terminator is the
-    // right lifetime. (`Particles\Bubbles.m2`, the underwater sibling, LOOPS — which is why it
-    // needs the client's replace-on-respawn dedup and this one does not.)
     let breath_bytes = chain
         .read_file(COLD_BREATH)
         .expect("ColdBreath.m2 is in the chain");
diff --git a/crates/benilla-formats/tests/m2_color.rs b/crates/benilla-formats/tests/m2_color.rs
index c4d5409b..6b994147 100644
--- a/crates/benilla-formats/tests/m2_color.rs
+++ b/crates/benilla-formats/tests/m2_color.rs
@@ -1,8 +1,5 @@
-//! Regression: an M2 batch that references an M2Color (`texUnit.colorIndex != 0xffff`) must carry that
-//! colour's RGB as a per-vertex tint, so the model shader multiplies it into the texture. Load-bearing
-//! for additive glow cards drawn with a neutral glow texture — the Orgrimmar bonfire's base glow
-//! (`GenericGlow_Alpha_128`, a white-cored radial) gets its warmth *only* from this M2Color; without it
-//! the additive draw washes the bright core to white. See decision 0029. Skips when the client is absent.
+//! A batch with an M2Color (`texUnit.colorIndex != 0xffff`) carries its RGB as a per-vertex tint:
+//! the Orgrimmar bonfire's glow on the neutral `GenericGlow_Alpha_128` gets its warmth only there.
 
 use benilla_formats::{load_m2_mesh, open_chain};
 
@@ -16,7 +13,6 @@ fn bonfire_glow_carries_warm_m2color_tint() {
     )
     .expect("load OrgrimmarBonfire01.m2");
 
-    // The additive billboard glow card (GenericGlow) references M2Color[0] = warm fire-orange.
     let glow = subs
         .iter()
         .find(|s| s.additive && s.billboard.is_some())
@@ -27,8 +23,7 @@ fn bonfire_glow_carries_warm_m2color_tint() {
         "the glow card's M2Color must be baked as a per-vertex tint"
     );
     let c = glow.vertex_colors[0];
-    // Authored M2Color RGB ≈ (0.925, 0.663, 0.098): warm (R ≫ B), not the neutral/white it'd be without
-    // the tint. Asserting the shape (warm) rather than exact bytes keeps this robust.
+    // M2Color[0] as authored.
     assert!(
         (c[0] - 0.925).abs() < 0.02 && (c[1] - 0.663).abs() < 0.02 && (c[2] - 0.098).abs() < 0.02,
         "glow tint should be the authored warm fire-orange, got {c:?}"
@@ -38,7 +33,6 @@ fn bonfire_glow_carries_warm_m2color_tint() {
         "glow tint must be distinctly warm (R≫G≫B), got {c:?}"
     );
 
-    // The wood/rock batches don't reference an M2Color (colorIndex 0xffff) → no baked tint.
     let untinted = subs
         .iter()
         .filter(|s| !s.additive && s.vertex_colors.is_empty())
diff --git a/crates/benilla-formats/tests/m2_emissive.rs b/crates/benilla-formats/tests/m2_emissive.rs
index abb21139..1b10c7c6 100644
--- a/crates/benilla-formats/tests/m2_emissive.rs
+++ b/crates/benilla-formats/tests/m2_emissive.rs
@@ -1,6 +1,5 @@
-//! Difftest the M2 UNLIT (0x01) → `emissive` detection against the real GeneralLantern03: its glass
-//! batch (ElwynnLantern01.blp, material flags 0x05) is self-lit; its body batch (flags 0x00) is not.
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! The M2 material flag UNLIT (0x01) is `emissive`: GeneralLantern03's glass (flags 0x05) is
+//! self-lit, its body (0x00) is not.
 
 use benilla_formats::{load_m2_mesh, open_chain};
 
diff --git a/crates/benilla-formats/tests/m2_entity_mat_anim.rs b/crates/benilla-formats/tests/m2_entity_mat_anim.rs
index 70017487..37ccb8bd 100644
--- a/crates/benilla-formats/tests/m2_entity_mat_anim.rs
+++ b/crates/benilla-formats/tests/m2_entity_mat_anim.rs
@@ -1,21 +1,11 @@
-//! The **entity** corpus's material animation (decision 2295) — the four shapes the unit /
-//! GameObject / held-item lane has to serve, each pinned on the asset that makes it unavoidable.
-//!
-//! Decision 0130 phase 3 built the texture transform for placed doodads and left every other lane
-//! off it; 2282 put the spell effects on; this file is the entity lane's turn, and it exists for
-//! the same reason 2282's does — *the premise that a lane needs no channel is a measurement, and an
-//! unmeasured one is how a channel gets quietly dropped.* `benilla-extract entityuvscan` is the
-//! census; these are the four rows of it a reader has to be able to check by hand.
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! The material animation shapes the unit, GameObject and held-item lane serves, each on the asset
+//! that needs it.
 
 use benilla_formats::{open_chain, parse_m2_render_submeshes};
 
-/// The whole entity corpus's widest case: **a creature, on a global sequence.** Every wind
-/// elemental in the game is this model, and 26 of its 32 batches slide a full sheet across
-/// themselves on a free-running clock — which is the one case where a shared material uniform is
-/// not a compromise but exactly what the reference does (0136 choice 1: the reference clocks a
-/// global-sequence loop on one per-scene ms cursor).
+/// Every wind elemental is this model, and 26 of its 32 batches slide a full sheet on a global
+/// sequence. The reference clocks a global sequence on one per-scene ms cursor, so a shared
+/// material is exact.
 #[test]
 fn a_creature_scrolls_on_a_global_sequence() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -35,8 +25,6 @@ fn a_creature_scrolls_on_a_global_sequence() {
         live.iter().all(|a| a.gseq),
         "every one rides a GLOBAL sequence — no host, no play head, a shared clock is faithful"
     );
-    // A full sheet per loop: the batches slide u by 1.0 over their period, which is what makes the
-    // shell read as moving air rather than as a painted band.
     for a in &live {
         let (lo, hi) = a
             .keys
@@ -44,21 +32,18 @@ fn a_creature_scrolls_on_a_global_sequence() {
             .fold((f32::MAX, f32::MIN), |(lo, hi), (_, v)| {
                 (lo.min(v[0]), hi.max(v[0]))
             });
-        // A whole sheet, to the key quantization the exporter left behind (one batch ends at
-        // 1.0017): what matters is that a full repeat passes under the geometry each loop.
+        // To the keys' quantization: one batch ends at 1.0017.
         assert!(
             (hi - lo - 1.0).abs() < 5e-3,
             "a whole sheet of U per loop: [{lo}, {hi}]"
         );
     }
-    // Nothing here is per-sequence, so these batches keep the shared, deduped material.
+    // Nothing is per-sequence, so the shared material serves.
     assert!(subs.iter().all(|s| s.uv_seq.is_none()));
 }
 
-/// **A batch that rotates and never translates.** Both of the corpus's two live on GameObjects,
-/// and both answer `None` on the channel a reader checks first — so a lane whose predicate is
-/// `uv_anim.is_some()`, or whose row carries only a translation, drops them without a trace. This
-/// is `UvLoops::animates`' whole reason for existing, and 2019's affine row's.
+/// The corpus's two batches that rotate and never translate, both on GameObjects: `uv_anim` alone
+/// misses them.
 #[test]
 fn a_gameobject_batch_rotates_with_no_translation_at_all() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -85,11 +70,8 @@ fn a_gameobject_batch_rotates_with_no_translation_at_all() {
     }
 }
 
-/// **The slots disagree, so no shared material can be right.** `BloodOfHeroes` authors its five
-/// bubble sheets twice over one animation id — file slot 0 holds them still, slot 1 sweeps them —
-/// at `freq` 16384/16383, so its 114 placements bubble independently of each other. That is
-/// 1408's population reached from the entity side: the instance needs a material of its own, and
-/// the row has to read whichever slot the instance is playing.
+/// `BloodOfHeroes` authors its five bubble sheets in two slots of one animation id, slot 0 still
+/// and slot 1 sweeping, so each instance needs its own material reading the slot it plays.
 #[test]
 fn a_gameobjects_slots_bake_different_loops() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -119,8 +101,6 @@ fn a_gameobjects_slots_bake_different_loops() {
             live.period
         );
     }
-    // The pool itself is a sixth batch with no transform at all — so what was missing was never
-    // "the blood pool", it was the bubbling.
     assert_eq!(
         subs.iter().filter(|s| s.uv_seq.is_none()).count(),
         1,
@@ -128,21 +108,10 @@ fn a_gameobjects_slots_bake_different_loops() {
     );
 }
 
-/// **And slot 1 is REACHABLE — the other half of the same asset's story.** A per-sequence UV loop
-/// only ever runs if the arm picks that sequence, so "slot 1 sweeps the sheet" is half a fact: the
-/// bubbling is live exactly as often as the weighted variation walk lands on take 1.
-///
-/// The pool's two takes are one `Stand` (`AnimationData.dbc` id 0) chain — and a GameObject whose
-/// model owns *none* of the door-family ids collapses its substate to Stand and re-arms it every
-/// window, with a fresh `variationIdx = -1` roll each time (wow-re `gameobject-anim-arm.md`
-/// §6c/§6d; `crate::go_anim`'s rest arm). So these two frequencies are the duty cycle of every
-/// blood pool in the Plaguelands: `roll < 16384` takes the still sheet, `16384..=32766` takes the
-/// bubbling one, and the single leftover draw (`32767`) exhausts the chain back to the head — the
-/// authored convention, frequencies summing to 32767 against 32768 outcomes.
-///
-/// It is pinned here rather than left to arithmetic because the failure it guards is silent: an
-/// asset re-read that dropped `frequency` to 0, or a walk that took the head, would leave this
-/// file's neighbour above passing unchanged while every pool in the game went still.
+/// Slot 1 plays as often as the variation walk lands on it. A GameObject owning none of the
+/// door-family ids re-arms Stand every window with a fresh roll (`0x5f3a52`, `0x5f4167`), so the
+/// two frequencies are the duty cycle: `roll < 16384` is still, `16384..=32766` bubbles, and the
+/// leftover 32767 exhausts the chain back to the head.
 #[test]
 fn the_bubbling_take_is_half_the_pools_duty_cycle() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -159,7 +128,7 @@ fn the_bubbling_take_is_half_the_pools_duty_cycle() {
     );
     assert!(
         seqs.iter().all(|s| s.anim_id == 0),
-        "both takes are Stand — which is what the §2c collapse-to-0 leg arms"
+        "both takes are Stand — which is what the collapse-to-0 leg arms"
     );
     let freqs: Vec<u16> = seqs.iter().map(|s| s.frequency).collect();
     assert_eq!(
@@ -167,8 +136,7 @@ fn the_bubbling_take_is_half_the_pools_duty_cycle() {
         vec![16_384, 16_383],
         "the still sheet and the bubbling one, at even odds"
     );
-    // The walk is `roll < freq` (strict, unsigned) node by node, else `roll -= freq` — so the
-    // counts below ARE the duty cycle, not an approximation of it.
+    // The walk: `roll < freq`, strict and unsigned, node by node, else `roll -= freq`.
     let bubbling = (0u32..32_768)
         .filter(|&roll| {
             let mut roll = roll;
@@ -185,11 +153,8 @@ fn the_bubbling_take_is_half_the_pools_duty_cycle() {
     );
 }
 
-/// **The same shape on the TINT channel**, and worse: four of the corpus's five animated entity
-/// tints bake *nothing* in file slot 0, so `rgb_anim` is `None` for them and a shared material can
-/// only ever seed white however faithfully it is ticked. `G_FreezingTrap` is the one with play
-/// frequency — the hunter's trap, whose glow card is meant to pulse blue-white as it arms, on the
-/// `Custom0` clip the server rings.
+/// Four of the corpus's five animated entity tints key nothing in slot 0, so `rgb_anim` is `None`:
+/// the hunter's freezing trap pulses its glow card only on the `Custom0` clip the server plays.
 #[test]
 fn a_gameobjects_tint_is_keyed_in_a_later_slot_alone() {
     let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-formats/tests/m2_env_map.rs b/crates/benilla-formats/tests/m2_env_map.rs
index 19d9b8a9..96584045 100644
--- a/crates/benilla-formats/tests/m2_env_map.rs
+++ b/crates/benilla-formats/tests/m2_env_map.rs
@@ -1,16 +1,6 @@
-//! Difftest the M2 **generated-texcoord** (environment-map) detection against real art — the
-//! `texCoordSet(+0x12) → texture_unit_lookup(0x9c)` two-hop the reference gates at `0x70b8bd`
-//! (`<= 2` = a vertex UV channel, higher = a generated env coordinate).
-//!
-//! Both halves matter, and only real art proves them. The Deeprun Tram's glass tube is the
-//! **positive**: it authors `texture_unit_lookup = [-1]` and, precisely because the runtime is
-//! meant to supply the coordinates, leaves **every one of its 330 vertices at exactly (0,0)** — so
-//! a renderer that misses the flag paints the whole tube in one corner texel of a reflection sheet
-//! (`AKGNOMEREFLECT.BLP` texel 0,0 = 225,221,142, doubled by the batch's Mod2x blend: the flat
-//! yellow). The weapon rack is the **discriminator**: the same model carries both kinds, so a
-//! parse that simply answered "env" everywhere would pass the first assert and fail here.
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! Generated (environment-map) texcoords: `texCoordSet` (`+0x12`) indexes `texture_unit_lookup`
+//! (`0x9c`), and the reference takes a value above 2 as generated (`0x70b8bd`). The Deeprun Tram's
+//! glass authors `[-1]` and leaves all 330 vertices' UVs at (0, 0).
 
 use benilla_formats::{load_m2_mesh, open_chain};
 
@@ -29,8 +19,6 @@ fn tram_glass_batches_generate_their_texcoords() {
         subs.iter().all(|s| s.env_map),
         "every GnomeSubwayGlass batch authors texture_unit_lookup = -1 (generated texcoords)"
     );
-    // The half that makes the flag load-bearing rather than cosmetic: there is no fallback here,
-    // because the authored UVs carry no information at all.
     for s in &subs {
         assert!(
             s.uvs.iter().all(|uv| uv[0] == 0.0 && uv[1] == 0.0),
@@ -49,8 +37,7 @@ fn weapon_rack_splits_env_from_uv_batches() {
     )
     .expect("load GeneralWeaponrack01");
 
-    // `texture_unit_lookup = [0, -1]`: the rack/blade batches name UV channel 0, the two
-    // ARMORREFLECT sheen layers (`texCoordSet 1`) generate theirs.
+    // `texture_unit_lookup = [0, -1]`: the body reads UV channel 0, the sheen layers generate.
     let env: Vec<&str> = subs
         .iter()
         .filter(|s| s.env_map)
diff --git a/crates/benilla-formats/tests/m2_global_seq_constant.rs b/crates/benilla-formats/tests/m2_global_seq_constant.rs
index 60f6cab7..0f54b2d6 100644
--- a/crates/benilla-formats/tests/m2_global_seq_constant.rs
+++ b/crates/benilla-formats/tests/m2_global_seq_constant.rs
@@ -1,16 +1,9 @@
-//! Global-sequence CONSTANT channel regression test (the floating-stowed-sword bug, 2026-07-03).
-//!
-//! Vanilla art authors the stowed-weapon attach-bone orientations as **global-sequence** tracks with a
-//! single key at t=0 (HumanMale bones 29/30 hips, 58–62 back family — the blade-down / shield-on-back
-//! quaternions), on global-seq 0, which is itself 0 ms long: a pure constant. The parser used to skip
-//! every global-sequence track ("deferred"), leaving those joints at identity, so a stowed sword lay
-//! horizontal through the body. The constant must now reach **every** sequence's keyframe set. Skips
-//! when the client isn't present.
+//! The stowed-weapon attach bones (HumanMale 29 and 30 at the hips, 58 to 62 on the back) are
+//! oriented by one key on global sequence 0, itself 0 ms long: a constant every sequence carries.
 
 use benilla_formats::{open_chain, parse_m2_animations};
 
-/// The hip-sheath attach bone (attachment id 32 → bone 29) and its authored constant rotation,
-/// verified by direct dump of the real file (decision 0072's attach survey).
+/// The hip-sheath attach bone (attachment 32) and its authored constant rotation.
 const HIP_BONE: u16 = 29;
 const HIP_QUAT: [f32; 4] = [0.382, 0.063, -0.922, 0.0];
 
diff --git a/crates/benilla-formats/tests/m2_go_arm_book.rs b/crates/benilla-formats/tests/m2_go_arm_book.rs
index 3f8470ad..b722a22a 100644
--- a/crates/benilla-formats/tests/m2_go_arm_book.rs
+++ b/crates/benilla-formats/tests/m2_go_arm_book.rs
@@ -1,22 +1,7 @@
-//! Every book in the world opened and closed constantly (`#bugs` B36) — because the loader-idle
-//! seed armed the model's **file-order-first** sequence, and on a book that sequence is the *Close
-//! motion*, not the closed pose.
-//!
-//! `G_BookOpenMediumBrown.m2` is the model that makes this unmissable. Its four sequences are the
-//! whole door family — Close(146) / Closed(147) / Open(148) / Opened(149) — authored in **that**
-//! order, so file-order-0 is a 0.333 s motion that sweeps bone 0 from the open angle to the closed
-//! one. Every one of the four carries `flags` bit 0 clear, i.e. the kernel loops it forever (wow-re
-//! `gameobject-anim-arm.md` §3, `0x714585`). Looping the Close motion is therefore a book that snaps
-//! open and swings shut three times a second, for ever — exactly what was reported.
-//!
-//! The reference arms **animation id 0 (Stand)** resolved through the model's own
-//! `playableAnimationLookup` (§1, byte-verified `0x71019b`), and this book's table sends id 0 to
-//! **147 Closed** — a two-key band whose keys are both identity, i.e. a still, shut book.
-//!
-//! The DuelingFlag test next door pins the same seed law on a model whose first sequence is a
-//! *Spawn*; this one pins it where the wrong pick is a **motion**, which is the visually loudest
-//! failure and the one a whole class of GameObjects (every `World\Goober\` door-family prop) shares.
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! A GameObject's idle is animation id 0 through its `playableAnimationLookup` (`0x71019b`), not
+//! its first sequence. The book authors the door family in the order Close (146), Closed, Open,
+//! Opened, all looping (`flags` bit 0 clear, `0x714585`), and its table sends id 0 to 147 Closed,
+//! a still shut book; its first sequence is the 0.333 s Close sweep.
 
 use benilla_formats::{
     open_chain, parse_m2_animation_lookup, parse_m2_animations, parse_m2_playable_animation_lookup,
@@ -35,20 +20,17 @@ fn the_book_idle_resolves_to_closed_not_the_close_motion() {
     let bytes = chain.read_file(BOOK).expect("the book M2 is in the chain");
     let anims = parse_m2_animations(&bytes);
 
-    // 1. File order really does lead with the Close MOTION — without this the test proves nothing.
     assert_eq!(
         anims.first().map(|a| a.anim_id),
         Some(CLOSE),
         "the model's FIRST sequence is the Close motion, not a rest pose — the whole point"
     );
 
-    // 2. That first sequence loops (bit 0 clear), so arming it is a permanent flap, not a one-shot.
     assert!(
         anims[0].looping,
         "Close is a looping band — arming it is what made the book cycle for ever"
     );
 
-    // 3. The loader's seed resolves to Closed through the model's own table.
     let playable = parse_m2_playable_animation_lookup(&bytes).expect("playable lookup");
     let idle_id = playable.first().map_or(0, |p| p.resolved_id);
     assert_eq!(
@@ -56,13 +38,8 @@ fn the_book_idle_resolves_to_closed_not_the_close_motion() {
         "playableAnimationLookup[0] resolves to Closed — the seed the reference arms"
     );
 
-    // 4. The pose each band actually holds, as the viewer would see it. This is the assertion that
-    //    catches the bug coming back even if the id plumbing is rewritten. Bone 0's rotation is a
-    //    pure x-axis quaternion: x ≈ 0 is the shut book, x ≈ 0.69 (≈ 87°) the open one.
-    //
-    //    Closed's band (533..633 ms) has NO keys of its own — the authored keys sit at 500 and 667,
-    //    both identity — so the window rule (decision 0643) resolves it to a single constant key.
-    //    One key here is the *correct* answer, not a missing one: the band genuinely doesn't move.
+    // Bone 0 turns about x: x ≈ 0 is shut, x ≈ 0.69 (87°) open. Closed's band (533..633 ms) has no
+    // keys of its own, so the window rule makes the identity keys at 500 and 667 one constant.
     let root_rot = |id: u16| -> Vec<[f32; 4]> {
         anims
             .iter()
@@ -81,8 +58,6 @@ fn the_book_idle_resolves_to_closed_not_the_close_motion() {
         );
     }
 
-    //    Close, by contrast, sweeps: it starts at the open angle and lands shut. Looping *that* is
-    //    the flapping book — so both halves of the claim are pinned, not just the one we fixed.
     let close_motion = root_rot(CLOSE);
     let (lo, hi) = close_motion
         .iter()
@@ -94,10 +69,7 @@ fn the_book_idle_resolves_to_closed_not_the_close_motion() {
         "Close must swing from open ({hi}) to shut ({lo}) — that sweep, looped, IS the reported bug"
     );
 
-    // 5. Closed is a non-BIND pose, which is what keeps the book on the skinned path at all: its
-    //    two cover bones sit at ±2.5° while bind has them square. If the idle ever stopped counting
-    //    as "differs from bind" the book would drop to the static mesh — silently, because the
-    //    difference is small enough to pass an eyeball and large enough to be the wrong book.
+    // Closed tilts its two cover bones 2.5° off bind, which keeps the book on the skinned path.
     let closed_seq = anims
         .iter()
         .find(|a| a.anim_id == CLOSED)
@@ -116,9 +88,7 @@ fn the_book_idle_resolves_to_closed_not_the_close_motion() {
         "Closed must pose bones off bind (the covers), got {tilted}"
     );
 
-    // 6. The ownership table the GameObject arm's missing-sequence remap branches on (the
-    //    reference's `0x711960`): this model owns the whole door family and nothing beyond it, so
-    //    no remap leg is reachable here and the arm plays the LUT id directly.
+    // The ownership table the missing-sequence remap branches on (`0x711960`): the door family.
     let lookup = parse_m2_animation_lookup(&bytes).expect("animation lookup");
     let owns = |id: u16| lookup.get(id as usize).is_some_and(|&s| s != 0xffff);
     for id in [CLOSE, CLOSED, OPEN, 149] {
diff --git a/crates/benilla-formats/tests/m2_go_crate_lid.rs b/crates/benilla-formats/tests/m2_go_crate_lid.rs
index 79e1d14e..b2ed6037 100644
--- a/crates/benilla-formats/tests/m2_go_crate_lid.rs
+++ b/crates/benilla-formats/tests/m2_go_crate_lid.rs
@@ -1,34 +1,18 @@
-//! The ammo crate the director looted was **stuck open/closing** — the lid springing to 75° and
-//! swinging shut, ~1.5 times a second, for ever (decision 1151). The model is why the symptom is
-//! that loud, and why "hold the motion's last frame" was never enough on its own.
-//!
-//! `G_Crate01.m2` is the door family, textbook: **bone 8** is the lid, and the four sequences are
-//! Open(148) 0° → 75°, Opened(149) holding 75°, Close(146) 75° → 0°, Closed(147) holding 0°. Every
-//! one of them carries `flags` bit 0 **clear**, i.e. the kernel wraps its band for ever (wow-re
-//! `gameobject-anim-arm.md` §3, `0x714585`) — so the loop bit says nothing about how long a
-//! transition lasts, and a consumer that reads it as "should this clip repeat?" arms the Close
-//! sweep on an endless loop the moment the loot window closes.
-//!
-//! What ends a swing in the real client is the **object layer**: the completion callback fires once
-//! at the arm's baked window (span × replay `R`, the loop bit ignored) and slot 14 `0x5f4120`
-//! advances substate 4 Close → 1 Closed (§2d). This file pins the asset facts that law rests on —
-//! the loop bits, `R = 1`, and that Close's last frame *is* the Closed pose — so the fix can't be
-//! undone by "the clip says it loops".
-//!
-//! The `G_BookOpenMediumBrown` test next door pins the seed law on the same family; this one pins
-//! the **transition** law. Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! A door-family transition ends on the object layer, not the loop bit: the completion callback
+//! fires once at the arm's window (span × replay `R`), and slot 14 `0x5f4120` advances Close to
+//! Closed. `G_Crate01.m2`'s lid runs Open 0° to 75°, Opened, Close 75° to 0°, Closed, and all four
+//! loop (`flags` bit 0 clear, `0x714585`).
 
 use benilla_formats::{open_chain, parse_m2_animation_lookup, parse_m2_animations};
 
-/// The quest ammo crate the report came off — GameObject type 3 CHEST, `world/goober/g_crate01.m2`.
+/// A quest ammo crate, GameObject type 3 (CHEST).
 const CRATE: &str = "World\\Goober\\G_Crate01.m2";
 /// `AnimationData.dbc`: 146 Close (motion), 147 Closed (rest), 148 Open (motion), 149 Opened (rest).
 const CLOSE: u16 = 146;
 const CLOSED: u16 = 147;
 const OPEN: u16 = 148;
 const OPENED: u16 = 149;
-/// The crate's **lid** bone — the only bone the door family moves (bones 0/1 are the static body,
-/// 9.. the destruction shards). Read off `benilla-extract m2bones`.
+/// The lid, the only bone the door family moves (0 and 1 are the body, 9.. the shards).
 const LID_BONE: u16 = 8;
 
 #[test]
@@ -46,8 +30,7 @@ fn the_crate_lid_transition_is_bounded_by_the_window_not_the_loop_bit() {
             .unwrap_or_else(|| panic!("the crate authors animation id {id}"))
     };
 
-    // 1. The whole door family is authored, so no §2c remap leg is reachable: the arm plays the
-    //    LUT id directly and the test below is about the *transition*, nothing else.
+    // The whole family is authored, so the remap leg (`0x5f3972`) never runs.
     let lookup = parse_m2_animation_lookup(&bytes).expect("animation lookup");
     for id in [CLOSE, CLOSED, OPEN, OPENED] {
         assert!(
@@ -56,20 +39,15 @@ fn the_crate_lid_transition_is_bounded_by_the_window_not_the_loop_bit() {
         );
     }
 
-    // 2. **Every** one of the four has `flags` bit 0 clear — the kernel loops them all, rest poses
-    //    and motions alike. So "does this clip loop?" cannot be the question a transition asks:
-    //    reading the bit here arms the Close sweep for ever, which IS the report.
     for id in [CLOSE, CLOSED, OPEN, OPENED] {
         assert!(
             seq(id).looping,
             "id {id} is a bit-0-clear band — the kernel wraps it, so only the object layer's \
-             §2d advance can end a transition"
+             completion advance can end a transition"
         );
     }
 
-    // 3. …and the window that advance fires at is exactly ONE pass: `R = max(1, min + roll)` with
-    //    an empty replay range rolls to 1 (wow-re §3, `0x712692..0x7126cd`). One window is the
-    //    whole swing — there is no second pass to model.
+    // `R = max(1, min + roll)`, and an empty replay range rolls 1 (`0x712692`..`0x7126cd`).
     for id in [CLOSE, CLOSED, OPEN, OPENED] {
         let s = seq(id);
         assert_eq!(
@@ -79,8 +57,7 @@ fn the_crate_lid_transition_is_bounded_by_the_window_not_the_loop_bit() {
         );
     }
 
-    // 4. The poses themselves, as the viewer sees them. The lid's rotation is a pure −Y quaternion:
-    //    |y| ≈ 0 is shut, |y| ≈ 0.61 (75°) is fully open.
+    // The lid turns about −Y: |y| ≈ 0 is shut, |y| ≈ 0.61 (75°) open.
     let lid = |id: u16| -> Vec<[f32; 4]> {
         seq(id)
             .bones
@@ -95,22 +72,18 @@ fn the_crate_lid_transition_is_bounded_by_the_window_not_the_loop_bit() {
         })
     };
 
-    // Close sweeps open → shut. Looping THAT is a lid that springs to 75° and slams, 1.5×/s.
     let (lo, hi) = span(&lid(CLOSE));
     assert!(
         lo < 1e-3 && hi > 0.5,
         "Close must sweep from open (|y| {hi}) to shut (|y| {lo}) — that sweep, looped, is the \
          reported bug"
     );
-    // Open is the mirror sweep — the other half of the cycle the loot window straddles.
     let (lo, hi) = span(&lid(OPEN));
     assert!(
         lo < 1e-3 && hi > 0.5,
         "Open must sweep from shut (|y| {lo}) to open (|y| {hi})"
     );
-    // The rest poses genuinely rest, and each is the pose its motion lands on — which is why
-    // holding a finished motion's last frame reads correctly, and why the §2d advance onto the
-    // rest sequence is invisible rather than a pop.
+    // Each rest pose is where its motion lands, so the `0x5f4120` advance onto it is seamless.
     for q in lid(CLOSED) {
         assert!(q[1].abs() < 1e-3, "Closed holds the SHUT lid, got {}", q[1]);
     }
diff --git a/crates/benilla-formats/tests/m2_go_rookery_egg.rs b/crates/benilla-formats/tests/m2_go_rookery_egg.rs
index be4f1bb6..f0eb6c8f 100644
--- a/crates/benilla-formats/tests/m2_go_rookery_egg.rs
+++ b/crates/benilla-formats/tests/m2_go_rookery_egg.rs
@@ -1,35 +1,17 @@
-//! UBRS's Rookery Eggs "don't play their animation when you walk close" (bug B140, decision 1404).
-//!
-//! The egg is `gameobject_template` 175124, a **TRAP** with radius 3 and one charge: walk inside it
-//! and vmangos spends the charge, casts the whelp-spawner, and — because the spawn rows carry
-//! `animprogress = 100` — sends `SMSG_GAMEOBJECT_DESPAWN_ANIM` (`GameObject.cpp:654-656` →
-//! `WorldObject::SendObjectDeSpawnAnim`) immediately followed by `SMSG_DESTROY_OBJECT`. The real
-//! client arms substate 12 off that packet (wow-re `gameobject-anim-arm.md` §2c: code table
-//! `0x80b0e0[6]` = 12, LUT `0x8607e4[12]` = **157 Despawn**) and *pins* the object so the destroy
-//! waits for the play (`go-display-sound-events.md` §6d).
-//!
-//! This file pins the two asset facts that whole law rests on, because both are the kind of thing a
-//! plausible reading gets wrong:
-//!
-//! 1. **The hatch is 157 Despawn, and it is unreachable from the §243 state machine.** The model
-//!    authors the door family (146..149) too — so a reader that only ever consults
-//!    `GAMEOBJECT_STATE` finds sequences, arms one, and looks correct while never playing the
-//!    animation anyone reported. Substate 1 (`state = 1`, `animprogress = 100`) resolves to 147
-//!    Closed, a 0.333 s near-static hold; the hatch is eight times longer and lives on the other,
-//!    disjoint arm channel.
-//! 2. **The window the pin has to outlast is real time.** 157 is ~2.667 s — the entire visible
-//!    event happens *after* the server has told the client the object is gone, which is why a
-//!    client without the pin shows nothing at all rather than something clipped.
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! The Rookery Egg (`gameobject_template` 175124) is a one-charge trap: entering its 3-yd radius
+//! makes vmangos send `SMSG_GAMEOBJECT_DESPAWN_ANIM`, since its spawn rows carry
+//! `animprogress = 100`, then `SMSG_DESTROY_OBJECT` (`GameObject.cpp:654-656`). The reference
+//! arms substate 12 off it (`0x80b0e0[6]` = 12, `0x8607e4[12]` = 157 Despawn) and pins the object
+//! (`0x4683e0`) so the destroy waits for the 2.667 s hatch, which the `SetGoState` machine
+//! (`0x5f8bd0`) never reaches: it holds 147 Closed.
 
 use benilla_formats::{open_chain, parse_m2_animation_lookup, parse_m2_animations};
 
-/// `GameObjectDisplayInfo.dbc` row **3891** (the Rookery Egg's `displayId`) → this model.
+/// `GameObjectDisplayInfo` 3891, the egg's display.
 const EGG: &str = "World\\Goober\\G_DragonEggFreeze.m2";
-/// `AnimationData.dbc` 157 Despawn — the one-shot channel's code 6.
+/// Despawn, the one-shot channel's code 6.
 const DESPAWN: u16 = 157;
-/// 147 Closed — what substate 1 (the spawn state) holds instead.
+/// Closed, what substate 1 (the spawn state) holds.
 const CLOSED: u16 = 147;
 
 #[test]
@@ -45,17 +27,13 @@ fn the_rookery_egg_keys_its_hatch_in_despawn_not_in_the_state_family() {
             .unwrap_or_else(|| panic!("the egg authors animation id {id}"))
     };
 
-    // 1. The model OWNS 157 — slot 15 pre-gates the one-shot channel on exactly this
-    //    (`0x5f423d`/`0x711960`), and takes no §2c remap, so an unowned id would simply play
-    //    nothing. This is the check that says the packet has somewhere to land.
+    // The one-shot channel plays only an id the model owns, with no remap (`0x5f423d`, `0x711960`).
     let lookup = parse_m2_animation_lookup(&bytes).expect("animation lookup");
     assert!(
         lookup.get(DESPAWN as usize).is_some_and(|&s| s != 0xffff),
         "the egg owns 157 Despawn"
     );
 
-    // 2. The hatch's window — what the destroy pin has to hold the object alive for. Half a
-    //    second of slack either side: the assertion is "seconds, not frames", not a float pin.
     let hatch = seq(DESPAWN);
     assert!(
         (2.0..3.5).contains(&hatch.duration),
@@ -67,9 +45,6 @@ fn the_rookery_egg_keys_its_hatch_in_despawn_not_in_the_state_family() {
         "it is a clamp band: one window, then the object goes"
     );
 
-    // 3. …and it is where the CONTENT is. The state family's rest pose is a near-static hold; the
-    //    hatch moves an order of magnitude more. A client that only reads `GAMEOBJECT_STATE` arms
-    //    the left-hand column for ever and renders an egg that never hatches — the report.
     let keys = |id: u16| -> usize {
         seq(id)
             .bones
@@ -84,9 +59,7 @@ fn the_rookery_egg_keys_its_hatch_in_despawn_not_in_the_state_family() {
         keys(CLOSED),
     );
 
-    // 4. One pass. `R = max(1, min + roll)` with an empty replay range rolls to 1 (wow-re
-    //    `loop-replay-fidget.md`), so the completion — and the pin's release — lands at one band
-    //    length, which is what `release_despawn_pin` models.
+    // `R = max(1, min + roll)`, and an empty replay range rolls 1 (`0x7126be`).
     assert_eq!(
         (hatch.min_replay, hatch.max_replay),
         (0, 0),
diff --git a/crates/benilla-formats/tests/m2_idle_anim.rs b/crates/benilla-formats/tests/m2_idle_anim.rs
index c25329cf..0a434759 100644
--- a/crates/benilla-formats/tests/m2_idle_anim.rs
+++ b/crates/benilla-formats/tests/m2_idle_anim.rs
@@ -1,14 +1,9 @@
-//! Animation-keyframe regression test against real vanilla creatures (decision 0019).
-//!
-//! Guards the bug that froze most creatures in Milestone B: a per-sequence keyframe window pulled in a
-//! keyframe from a *later* sequence (14–64 s away), which inflated the Bevy clip's duration and made
-//! the whole animation crawl. We now select keys by absolute timestamp within each sequence's band, so
-//! every keyframe of every sequence must land inside `[0, duration]`. Skips when the client isn't present.
+//! Keys are selected by absolute timestamp within each sequence's band, so every key of every
+//! sequence lands inside `[0, duration]`.
 
 use benilla_formats::{open_chain, parse_m2_animations, ModelAnimation};
 
-/// A spread of vanilla creatures: simple (rabbit/chicken) through rigged humanoid-ish (kobold/murloc),
-/// covering the ones that animated *and* the ones that froze before the fix.
+/// Simple rigs (rabbit, chicken) through humanoid ones (kobold, murloc).
 const CREATURES: &[&str] = &[
     "Creature\\Rabbit\\Rabbit.m2",
     "Creature\\Chicken\\Chicken.m2",
@@ -28,15 +23,14 @@ fn creature_animation_keyframes_stay_within_their_sequence() {
     let mut checked = 0;
     for path in CREATURES {
         let Ok(bytes) = chain.read_file(path) else {
-            continue; // a model not in this install — skip
+            continue; // not in this install
         };
         let anims = parse_m2_animations(&bytes);
         assert!(
             !anims.is_empty(),
             "{path}: a creature should have sequences"
         );
-        // Every creature must carry a Stand (AnimationData id 0) somewhere — the records are NOT
-        // ordered by id (e.g. Rabbit's record 0 is Walk), so the idle is found by id, not position.
+        // Records are not ordered by id (Rabbit's record 0 is Walk): the idle is found by id.
         let ids: Vec<u16> = anims.iter().map(|a| a.anim_id).collect();
         assert!(
             ids.contains(&0),
@@ -48,8 +42,6 @@ fn creature_animation_keyframes_stay_within_their_sequence() {
                 "{path}: anim {} has no duration",
                 anim.anim_id
             );
-            // No keyframe may sit past its sequence: a key beyond `duration` is the cross-sequence leak
-            // that froze creatures (it stretched a clip to many seconds). Small epsilon for rounding.
             let max_t = max_key_time(anim);
             assert!(
                 max_t <= anim.duration + 1e-3,
@@ -66,7 +58,6 @@ fn creature_animation_keyframes_stay_within_their_sequence() {
     );
 }
 
-/// The latest keyframe time across every bone/channel of the animation (0.0 if it has no keys).
 fn max_key_time(anim: &ModelAnimation) -> f32 {
     let mut max = 0.0_f32;
     for b in &anim.bones {
diff --git a/crates/benilla-formats/tests/m2_lights.rs b/crates/benilla-formats/tests/m2_lights.rs
index e48dd03e..e779640e 100644
--- a/crates/benilla-formats/tests/m2_lights.rs
+++ b/crates/benilla-formats/tests/m2_lights.rs
@@ -1,6 +1,4 @@
-//! M2 light-block parse — byte-level check against a real Elwynn campfire, the dynamic point-light
-//! "hot-spot" caster (decision 0016). Pins the vanilla `0xd4` record stride and the diffuse-colour track
-//! offset. Skips when the client isn't present.
+//! The M2 light block: `0xd4` bytes a record, the diffuse-colour track at `0x48`.
 
 use benilla_formats::{parse_m2_lights, Chain};
 
@@ -21,8 +19,6 @@ fn elwynn_campfire_has_one_warm_point_light() {
         "campfire light is type 1 (point), got type {}",
         l.light_type
     );
-    // The authored warm-orange diffuse pins the 0xd4 record stride AND the 0x48 diffuse-colour track
-    // offset (independently cross-checked ≈ (0.71, 0.20, 0.00) — a garbled stride would not land here).
     let d = l.diffuse_color;
     assert!(
         (d[0] - 0.71).abs() < 0.03 && (d[1] - 0.20).abs() < 0.03 && d[2] < 0.05,
@@ -30,10 +26,8 @@ fn elwynn_campfire_has_one_warm_point_light() {
     );
 }
 
-/// The **held torch** — the light an NPC carries into the world (`Club_1H_Torch_A_01.m2`, the model
-/// `ItemDisplayInfo` 12236 / item 1906 "Monster - Torch" resolves to). Pins the one asset the entity
-/// carried-light path exists for: a `type==1` point light on bone 9, up the shaft, warm, `×3`
-/// intensity, and — the gate — a visibility track whose first key is nonzero, so it CASTS.
+/// The torch an NPC carries (`ItemDisplayInfo` 12236, item 1906 "Monster - Torch"): a point light
+/// on bone 9 up the shaft, at intensity 3, whose visibility track's first key is nonzero: it casts.
 #[test]
 fn held_torch_casts_one_warm_point_light_up_the_shaft() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -59,9 +53,8 @@ fn held_torch_casts_one_warm_point_light_up_the_shaft() {
     );
 }
 
-/// The **dark** shape (wow-re `m2-dynamic-lights.md` §9.4): a `type==1` light whose visibility track
-/// ships a static `0` key never casts. 11 of the corpus's 85 point lights are this — mostly spell
-/// impact VFX — so the gate is not academic; before it, every one of them lit the world.
+/// A point light whose visibility track is a static `0` key never casts (`0x716413`): 11 of the
+/// corpus's 85, mostly spell impacts.
 #[test]
 fn a_static_zero_visibility_key_reads_as_dark() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -86,6 +79,5 @@ fn a_static_zero_visibility_key_reads_as_dark() {
 
 #[test]
 fn too_short_yields_no_lights() {
-    // No MD20 lights array header → empty, no panic.
     assert!(parse_m2_lights(&[0u8; 16]).is_empty());
 }
diff --git a/crates/benilla-formats/tests/m2_loader_idle_is_stand.rs b/crates/benilla-formats/tests/m2_loader_idle_is_stand.rs
index 31c368e7..72d1c2a4 100644
--- a/crates/benilla-formats/tests/m2_loader_idle_is_stand.rs
+++ b/crates/benilla-formats/tests/m2_loader_idle_is_stand.rs
@@ -1,24 +1,13 @@
-//! The loader-idle seed is **Stand**, not the file-order-first sequence (the floating duel-flag
-//! bug, 2026-07-25 — decision 0637).
-//!
-//! `DuelingFlag.m2` is the model that separates the two readings. Its sequence table is authored
-//! **Spawn(145) / Stand(0) / Despawn(157)** — file order 0 is the *Spawn*, not the idle — and its
-//! geometry is modelled in the air: the bind pose sits at z ≈ +8.9…+14.7, and bone 0's translation
-//! track is what plants it (`t=700 → −9.124`, held to `t=5333`). So arming file-order-0 and looping
-//! it flies the flag 9 yards up every 3.3 s, while arming Stand holds it planted — which is what
-//! the reference does (wow-re `gameobject-anim-arm.md` §1, byte-verified `0x71019b`: the loader
-//! arms animation id 0 resolved through the model's own `playableAnimationLookup`).
-//!
-//! This test pins the three facts the fix rests on, straight off the shipped file. Skips (passes)
-//! when the client isn't present at `<repo>/WoW/Data`.
+//! The loader's idle is animation id 0 through the model's `playableAnimationLookup` (`0x71019b`),
+//! not its first sequence. `DuelingFlag.m2` authors Spawn (145), Stand, Despawn (157), and models
+//! the flag in the air (bind z 8.9 to 14.7): Stand's bone 0 track plants it.
 
 use benilla_formats::{open_chain, parse_m2_animations, parse_m2_playable_animation_lookup};
 
 const DUEL_FLAG: &str = "World\\Generic\\PassiveDoodads\\DuelingFlag\\DuelingFlag.m2";
-/// `AnimationData.dbc`: 0 = Stand, 145 = Spawn, 157 = Despawn.
 const STAND: u16 = 0;
 const SPAWN: u16 = 145;
-/// Bone 0's planted height (raw WoW z, the value both keys bracketing the Stand band carry).
+/// Bone 0's planted z, which both keys bracketing the Stand band carry.
 const PLANTED_Z: f32 = -9.124369;
 
 #[test]
@@ -30,14 +19,12 @@ fn the_duel_flag_idle_resolves_to_stand_and_sits_planted() {
         .expect("DuelingFlag.m2 in the chain");
     let anims = parse_m2_animations(&bytes);
 
-    // 1. File order really does lead with Spawn — without this the test proves nothing.
     assert_eq!(
         anims.first().map(|a| a.anim_id),
         Some(SPAWN),
         "the model's FIRST sequence is Spawn, not Stand — the whole point of this model"
     );
 
-    // 2. The loader's seed resolves to Stand through the model's own table.
     let playable = parse_m2_playable_animation_lookup(&bytes).expect("playable lookup");
     let idle_id = playable.first().map_or(0, |p| p.resolved_id);
     assert_eq!(
@@ -45,9 +32,6 @@ fn the_duel_flag_idle_resolves_to_stand_and_sits_planted() {
         "playableAnimationLookup[0] resolves to Stand"
     );
 
-    // 3. Stand holds the flag IN THE GROUND: bone 0's translation over the Stand band is the
-    //    constant −9.124 (both bracketing keys carry it), not the bind pose it would sit at with
-    //    no clip. This is the assertion that actually catches the bug coming back.
     let stand = anims
         .iter()
         .find(|a| a.anim_id == STAND)
@@ -70,14 +54,7 @@ fn the_duel_flag_idle_resolves_to_stand_and_sits_planted() {
         );
     }
 
-    // 4. Stand's AUTHORED bounds describe the planted flag — ground to tip — and emphatically NOT
-    //    the bind pose (z +8.9..+14.7). This is the mouseover picker's volume for the armed idle
-    //    (entity M2 parts carry `NoFrustumCulling` — the view cull is the body ROOT's per-object
-    //    election, never a per-part box; the "≈1e7 entity render bounds" reading behind 0648 was
-    //    refuted by wow-re's `outdoor-object-pass-election.md` — decision 1473).
-    //    The bind-pose `Aabb` Bevy would derive sits a whole model-height ABOVE the geometry that
-    //    draws — as a cull box it hid the planted flag from every ground-level camera, and as a
-    //    pick box it would put the hover target in the sky.
+    // Stand's authored box, the idle's mouseover pick volume, is the planted flag, ground to tip.
     assert!(
         stand.bounds_min[2] > -1.0 && stand.bounds_min[2] < 0.5,
         "Stand's authored min z should sit at the ground, got {}",
diff --git a/crates/benilla-formats/tests/m2_playable_animation_lookup.rs b/crates/benilla-formats/tests/m2_playable_animation_lookup.rs
index 7a3d62a9..7f13417f 100644
--- a/crates/benilla-formats/tests/m2_playable_animation_lookup.rs
+++ b/crates/benilla-formats/tests/m2_playable_animation_lookup.rs
@@ -1,8 +1,5 @@
-//! Pins the M2 **PlayableAnimationLookup** table parse (decision 0082 — missing-animation-clip
-//! resolution) against a real build-5875 model. `nPlayableAnimationLookup` is byte-verified (wow-re
-//! `anim-id-resolution.md`) to be a fixed 203 across the entire retail 1.12.1 M2 corpus; row 6 is the
-//! note's own decisive example (`playableAnimationLookup[6] = 0x00030001`). Skips when the gitignored
-//! client data isn't present.
+//! The M2 `playableAnimationLookup`, which resolves an animation id the model lacks: 203 rows in
+//! every shipped M2, sized to `AnimationData.dbc`'s playable set.
 
 use benilla_formats::{open_chain, parse_m2_playable_animation_lookup};
 
@@ -15,38 +12,26 @@ fn humanmale_playable_animation_lookup_matches_the_byte_verified_shape() {
         .expect("read m2");
     let pal = parse_m2_playable_animation_lookup(&bytes).expect("parse playable animation lookup");
 
-    // `nPlayableAnimationLookup` is a fixed 203 across the retail corpus (wow-re empirical
-    // cross-check) — the array is sized to `AnimationData.dbc`'s playable set, identically for every
-    // model regardless of its own sequence count.
     assert_eq!(pal.len(), 203);
 
-    // Identity entries: HumanMale actually plays Stand(0)/Death(1)/WalkBackwards(3)/Walk(4)/Run(5)
-    // itself, so each row maps back to its own id with no direction code.
+    // HumanMale authors Stand, Death, WalkBackwards, Walk and Run, so they map to themselves.
     for id in [0u16, 1, 3, 4, 5] {
         let row = pal[id as usize];
         assert_eq!(row.resolved_id, id, "row {id} should be identity");
         assert_eq!(row.dir_flags, 0, "row {id} should carry no dir-flags code");
     }
 
-    // The RE note's own decisive empirical proof (`anim-id-resolution.md` §4, "the DECISIVE
-    // empirical fact"): row 6 packs `0x00030001` — resolved id 1 (Death), dir-flags code 3 — computed
-    // by hand-replaying the DBC Fallback walk (row 6: Fallback=1, Flags=0x28) and shown bit-for-bit
-    // identical to this baked entry. The single strongest real-asset anchor for the whole mechanism.
+    // Row 6 packs `0x00030001`, Death with dir-flags 3, which the DBC Fallback walk (`0x711bf0`)
+    // over row 6 (Fallback 1, Flags 0x28) reproduces.
     assert_eq!(pal[6].resolved_id, 1, "row 6 -> Death, the DBC-walk proof");
     assert_eq!(pal[6].dir_flags, 3, "row 6's direction/variant code");
 
-    // A genuine fallback entry away from the DBC-walk showcase row: HumanMale plays every attack
-    // (2H/1H/unarmed all present), so pick a row known to fall back rather than resolve to itself —
-    // row 32 substitutes AttackUnarmed(16) for whatever id 32 requests.
     assert_eq!(pal[32].resolved_id, 16, "row 32 substitutes AttackUnarmed");
 }
 
-/// The **prowl clips** the stealth gait branch asks for (`creature_anim::select`'s `STEALTH_WALK` /
-/// `STEALTH_STAND`, RF-0057's `[[110]+0x213]&2` branches): a player model authors both, and a
-/// creature model may author NEITHER — in which case the same baked lookup the real client indexes
-/// steps 119 down to Walk and 120 to Stand. That asymmetry is why the selector's stealth branch needs
-/// no model-capability check of its own, and why a prowling druid cat shows its ordinary walk on the
-/// reference client too.
+/// The stealth clips, 119 StealthWalk and 120 StealthStand: a player model authors both, and where
+/// a creature authors neither the baked lookup steps them to Walk and Stand, so a prowling druid
+/// cat walks as usual in the reference too.
 #[test]
 fn the_stealth_clips_are_authored_by_players_and_absent_from_the_druid_cat() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -55,7 +40,6 @@ fn the_stealth_clips_are_authored_by_players_and_absent_from_the_druid_cat() {
         parse_m2_playable_animation_lookup(&chain.read(path).expect("read m2")).expect("parse pal")
     };
 
-    // Rogue/druid bodies: StealthWalk(119) and StealthStand(120) resolve to themselves.
     for model in [
         "character\\human\\male\\humanmale.m2",
         "character\\nightelf\\female\\nightelffemale.m2",
@@ -65,7 +49,6 @@ fn the_stealth_clips_are_authored_by_players_and_absent_from_the_druid_cat() {
         assert_eq!(p[120].resolved_id, 120, "{model} authors StealthStand");
     }
 
-    // Cat form authors neither — the baked walk lands on Walk / Stand.
     let cat = pal("creature\\druidcat\\druidcat.m2");
     assert_eq!(cat[119].resolved_id, 4, "cat StealthWalk -> Walk");
     assert_eq!(cat[120].resolved_id, 0, "cat StealthStand -> Stand");
diff --git a/crates/benilla-formats/tests/m2_portrait_camera.rs b/crates/benilla-formats/tests/m2_portrait_camera.rs
index 111f6323..0beff8ce 100644
--- a/crates/benilla-formats/tests/m2_portrait_camera.rs
+++ b/crates/benilla-formats/tests/m2_portrait_camera.rs
@@ -1,7 +1,5 @@
-//! M2 portrait-camera parse — byte-level check against real character/creature models. Pins the
-//! vanilla camera record stride (`0x7c`) + the `cameraLookup[0]` selection (wow-re
-//! `system/ui/scratch/portrait-render.md` §4: the unit-frame portrait renders through exactly this
-//! authored camera). Skips when the client isn't present.
+//! M2 cameras: `0x7c` bytes a record (built at `0x70f270`); the unit-frame portrait renders
+//! through `cameraLookup[0]` (`0x713540`).
 
 use benilla_formats::{parse_m2_portrait_camera, Chain};
 
@@ -18,10 +16,7 @@ fn character_and_creature_portrait_cameras_parse_sane() {
         let cam = parse_m2_portrait_camera(&bytes)
             .unwrap_or_else(|| panic!("{path}: no portrait camera"));
         eprintln!("{path}: {cam:?}");
-        // Structural sanity that a garbled stride/offset could not land on: a usable perspective
-        // (fov in a plausible authored range, near < far), the camera off the target, and the rig
-        // in front of the model (WoW models author facing +X; a portrait camera sits +X of its
-        // subject looking back).
+        // Models face +X, so a portrait camera sits +X of its subject, looking back.
         assert!(
             cam.fov > 0.1 && cam.fov < 1.6,
             "{path}: fov {} outside plausible authored range",
@@ -39,9 +34,8 @@ fn character_and_creature_portrait_cameras_parse_sane() {
             "{path}: camera not in front of the model (Δx {dx})"
         );
     }
-    // Numeric regression pin — HumanMale's authored rig (fov exactly π/4; eye head-height, in
-    // front and off to the model's right — why the ref portrait faces viewer-left; target on the
-    // head center). A wrong stride or a swapped base/track offset cannot land on all nine.
+    // HumanMale's authored rig: fov π/4, the eye at head height, in front and to the model's
+    // right (so the portrait faces viewer-left), the target on the head's centre.
     let bytes = reader
         .read("Character\\Human\\Male\\HumanMale.m2")
         .expect("read HumanMale.m2");
@@ -65,17 +59,11 @@ fn character_and_creature_portrait_cameras_parse_sane() {
 
 #[test]
 fn too_short_yields_no_camera() {
-    // No MD20 camera array header → None, no panic.
     assert!(parse_m2_portrait_camera(&[0u8; 16]).is_none());
 }
 
-/// **The model-frame pane camera** — raw `cameras[1]`, the rig a 1.12 `<PlayerModel>` widget renders
-/// through (wow-re `system/ui/scratch/modelframe-camera-law.md`: `0x505b30` → the chooser `0x505890`
-/// takes a literal index 1, NOT `cameraLookup`; decision 1089).
-///
-/// Byte-level regression pin against the numbers the RE reports, read here independently through our
-/// own parser — the two agreeing is the cross-check. The universal clips (`near = 8/36`,
-/// `far = 1000/36`) come along because a wrong stride would land on neither.
+/// A `<PlayerModel>` pane renders through raw `cameras[1]`: the chooser `0x505890`, from
+/// `0x505b30`, takes index 1, not `cameraLookup`. Every record's clips are 8/36 and 1000/36.
 #[test]
 fn pane_cameras_match_the_authored_records() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -127,9 +115,7 @@ fn pane_cameras_match_the_authored_records() {
         assert!(close(cam.roll, 0.0), "{path}: roll {}", cam.roll);
     }
 
-    // The standoff is AUTHORED per model, which is the whole point: nothing normalizes a pane, so a
-    // gnome's camera sits ~2.2yd out and a boar's ~4.9. If these ever converged, some engine-side
-    // fit would have crept back in.
+    // The standoff is authored per model, never normalized: a gnome's ~2.2 yd, a boar's ~4.9.
     let x = |path: &str| {
         let bytes = reader.read(path).expect("read model");
         benilla_formats::parse_m2_camera(&bytes, 1)
diff --git a/crates/benilla-formats/tests/m2_sequence_bounds.rs b/crates/benilla-formats/tests/m2_sequence_bounds.rs
index cf275b65..6ebd404f 100644
--- a/crates/benilla-formats/tests/m2_sequence_bounds.rs
+++ b/crates/benilla-formats/tests/m2_sequence_bounds.rs
@@ -1,8 +1,5 @@
-//! Pins the per-sequence bounds-sphere parse (`M2Sequence` CAaBox @+0x24/+0x30, radius @+0x3c) on
-//! real build-5875 unit models. This sphere is the mouse-pick **broad phase** for the model's
-//! current animation (wow-re pick-volume RE `bd630be`, `0x7089c0` — §5-verified): if it parsed as
-//! zero or a sliver, the faithful pick would reject clicks the reference accepts. Skips when the
-//! gitignored client data isn't present.
+//! The `M2Sequence` bounds (box at `+0x24` and `+0x30`, radius at `+0x3c`): the sphere is the
+//! mouse pick's broad phase for the current animation (`0x7089c0`).
 
 use benilla_formats::{open_chain, parse_m2_animations};
 
@@ -11,9 +8,7 @@ fn stand_sequence_bounds_sphere_is_body_scale() {
     let data = benilla_formats::wow_data_or_skip!();
     let chain = open_chain(&data).expect("open chain");
 
-    // (model, Stand bounds-sphere radius read off the real files). Note the chicken: its sphere
-    // (0.30) is *smaller* than its ring footprint (0.57) — the ring's nested-sqrt inflates small
-    // extents — so no ring-relative bound holds in general; the parsed values themselves are the pin.
+    // (model, Stand sphere radius read off the file).
     for (path, radius) in [
         ("Creature\\Chicken\\Chicken.mdx", 0.304_f32),
         ("Creature\\Horse\\Horse.mdx", 2.019),
@@ -35,8 +30,7 @@ fn stand_sequence_bounds_sphere_is_body_scale() {
             "{path}: Stand bounds sphere {:.3}, expected {radius:.3}",
             stand.bounds_radius
         );
-        // The centre sits above the feet (positive raw-WoW Z), inside the sphere — a zeroed/garbage
-        // box would fail one of these.
+        // The centre sits above the feet (positive raw Z) and within the sphere's reach.
         assert!(stand.bounds_center[2] > 0.0 && stand.bounds_center[2] < stand.bounds_radius * 2.0);
     }
 }
diff --git a/crates/benilla-formats/tests/m2_shared_section.rs b/crates/benilla-formats/tests/m2_shared_section.rs
index fa05f6cb..a149885a 100644
--- a/crates/benilla-formats/tests/m2_shared_section.rs
+++ b/crates/benilla-formats/tests/m2_shared_section.rs
@@ -1,24 +1,12 @@
-//! Difftest **`RenderSubmesh::section`** against real art — the fact the consolidator gate in
-//! `terrain_stream::spawn::assemble` rests on: two batches naming one M2 skin section draw the
-//! SAME triangles, so they are coplanar and must never be split across vertex-transform lanes.
-//!
-//! `Ballista.m2` is the positive, and it is the model the defect was reported on: its bolt head
-//! (section 7) and its shields (section 10) each carry a base batch **plus** an
-//! `ARMORREFLECT3` shine batch — additive, render flag `0x10` (no depth write), env-mapped. Every
-//! one of those three facts is a consolidator exclusion, so before the gate the base rode the
-//! retained/merged lane while the shine stayed on the entity path, and the pair's depths agreed
-//! only to a few ULPs: a per-pixel coin flip that re-rolled with the camera.
-//!
-//! `HumanTentMedium.m2` is the discriminator — a doodad whose every section is drawn once, which a
-//! parse that answered "shared" everywhere would fail.
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! `RenderSubmesh::section`: two batches naming one M2 skin section draw the same triangles, so
+//! they are coplanar and `terrain_stream::spawn::assemble` keeps them on one vertex-transform lane.
+//! The Ballista's bolt head and shields each add an `ARMORREFLECT3` shine that is additive,
+//! env-mapped and render flag `0x10`, each a consolidator exclusion.
 
 use benilla_formats::{load_m2_mesh, open_chain, RenderSubmesh};
 
-/// The union of the facts the consolidators exclude on: `static_gx::divert` refuses env-mapped and
-/// depth-flagged batches, the merge lane refuses additive ones. A batch answering `true` can never
-/// leave the entity path, whatever its siblings do.
+/// What the consolidators exclude: `static_gx::divert` refuses env-mapped and depth-flagged
+/// batches, the merge lane additive ones.
 fn refusable(s: &RenderSubmesh) -> bool {
     s.env_map || s.no_depth_write || s.no_depth_test || s.additive
 }
@@ -33,14 +21,11 @@ fn the_ballista_authors_a_coplanar_shine_over_its_bolt_head_and_shields() {
     )
     .expect("load Ballista");
 
-    // Every M2 batch names its section; the field exists to be compared, so `None` here would make
-    // the gate a silent no-op on the whole M2 population.
     assert!(
         subs.iter().all(|s| s.section.is_some()),
         "every M2 batch carries its skin-section index"
     );
 
-    // The two shared sections, and the split inside each: one plain base, one refusable shine.
     let mut shared = 0;
     for section in [7u16, 10] {
         let batches: Vec<&RenderSubmesh> =
@@ -56,8 +41,6 @@ fn the_ballista_authors_a_coplanar_shine_over_its_bolt_head_and_shields() {
             "exactly one of section {section}'s two batches is a consolidator exclusion — that \
              asymmetry is the defect the assemble gate closes"
         );
-        // The shine layer's own three facts, so a parse regression on any one of them red-bars
-        // here rather than silently re-opening the split.
         let shine = batches.iter().find(|s| refusable(s)).unwrap();
         assert!(shine.env_map, "the shine batch generates its texcoords");
         assert!(shine.no_depth_write, "…carries render flag 0x10");
diff --git a/crates/benilla-formats/tests/m2_swipe_claw_trail.rs b/crates/benilla-formats/tests/m2_swipe_claw_trail.rs
index 2c89832e..0a6e23b0 100644
--- a/crates/benilla-formats/tests/m2_swipe_claw_trail.rs
+++ b/crates/benilla-formats/tests/m2_swipe_claw_trail.rs
@@ -1,30 +1,12 @@
-//! The druid's Swipe leaves no claw trail (decision 2282) — and, like the lava bubbles next door,
-//! the asset says why in one number: **this model's whole visible existence is its texture
-//! transform.**
-//!
-//! `Spells\SwipeCaster.m2` — Swipe's `cast` kit (`SpellVisual` 189 → kit 182 →
-//! `SpellVisualEffectName` 215) — is two 51-vertex strips, three per batch, each rigidly skinned to
-//! one bone that sweeps it through the arc. Their UVs are authored `u ∈ [0.945, 1.944]` against a
-//! sheet the file addresses **CLAMP**, whose border texels are fully transparent. At the
-//! translation track's first key the strips therefore sample the sheet's transparent right edge
-//! along their whole length and draw *nothing at all*; the 1.5 s U-scroll is what drags the claw
-//! across them.
-//!
-//! So a consumer that renders this model's geometry, rig, alpha loops and particles but not its
-//! texture transform renders a correct-looking blood spray and no trail — which is exactly what
-//! benilla's spell-effect lane did, on 0271's recorded premise that "no effect model in the
-//! current corpus needs it". This file pins the three facts that make that premise false, so the
-//! effect lane's UV channel can never be quietly dropped again.
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! Swipe's cast model (`SpellVisual` 189, kit 182, `SpellVisualEffectName` 215) shows only through
+//! its texture transform: its strips' UVs sit at u 0.945..1.944 on a CLAMP sheet with a transparent
+//! border, so they draw nothing until the 1.5 s U scroll drags the claw across them.
 
 use benilla_formats::{open_chain, parse_m2_render_submeshes, uv_transform};
 
 const SWIPE: &str = "Spells\\SwipeCaster.m2";
 
-/// The u extent the batch's authored UVs cover once the loop's offset at `t` is folded in, by the
-/// verified law (wow-re `m2-texanim-uv` §1: `uv' = R·S·((uv + t) − p) + p`, and with no rotation
-/// or scaling authored here that is a pure `uv + t`).
+/// The u extent of the UVs offset by `t` under `uv' = R·S·((uv + t) − p) + p` (`0x714260`).
 fn u_span_at(uvs: &[[f32; 2]], offset: [f32; 2]) -> (f32, f32) {
     uvs.iter()
         .map(|&uv| uv_transform(uv, offset, [0.0, 0.0, 0.0, 1.0], [1.0, 1.0])[0])
@@ -40,8 +22,6 @@ fn the_swipe_claw_trail_is_nothing_but_its_uv_scroll() {
 
     assert_eq!(subs.len(), 2, "the two claw-strip batches");
     for (i, s) in subs.iter().enumerate() {
-        // 1. Every batch animates its texture transform, on the SHARED spelling (one sequence, so
-        //    the slots cannot disagree and 1408's per-slot set is rightly absent).
         let uv = s
             .uv_anim
             .as_ref()
@@ -51,7 +31,6 @@ fn the_swipe_claw_trail_is_nothing_but_its_uv_scroll() {
             "batch {i}: one sequence, so no per-slot set"
         );
 
-        // 2. The scroll is a near-whole-sheet sweep along U, and it runs the length of the clip.
         let (first, last) = (
             uv.keys.first().expect("keys").1,
             uv.keys.last().expect("keys").1,
@@ -66,13 +45,8 @@ fn the_swipe_claw_trail_is_nothing_but_its_uv_scroll() {
             uv.period
         );
 
-        // 3. The sheet is CLAMP-addressed on U — which is what turns the scroll from a nicety into
-        //    the whole visual. A repeat-addressed strip would show *something* at every offset.
         assert!(!s.wrap_x, "batch {i}: U is authored CLAMP");
 
-        // 4. …and so, frozen at the first key, the strip sits entirely at or past the sheet's right
-        //    edge: clamped, every one of its texels is the border. Scrolled to the last key it
-        //    covers the sheet instead. This pair IS the bug and its fix, in the asset's own numbers.
         let frozen = u_span_at(&s.uvs, first);
         assert!(
             frozen.0 > 0.94,
@@ -85,8 +59,7 @@ fn the_swipe_claw_trail_is_nothing_but_its_uv_scroll() {
         );
     }
 
-    // 5. The border really is empty, so "clamped to the edge" means "invisible" and not "a stripe
-    //    of colour". `BloodSpurtSmall01` is a 16×16 blob with a fully transparent frame.
+    // The claw sheet: a 16×16 blob with a fully transparent frame.
     let blp = chain
         .read_file("Spells\\BloodSpurtSmall01.blp")
         .expect("the claw sheet is in the chain");
diff --git a/crates/benilla-formats/tests/m2_uv_anim_variation.rs b/crates/benilla-formats/tests/m2_uv_anim_variation.rs
index 34ee1eda..25367549 100644
--- a/crates/benilla-formats/tests/m2_uv_anim_variation.rs
+++ b/crates/benilla-formats/tests/m2_uv_anim_variation.rs
@@ -1,21 +1,7 @@
-//! The BRM lava bubbles' animation is frozen (bug B98, decision 1408) — and the asset says why in
-//! one number: **every one of this model's animated channels is keyed inside file sequence slot 1,
-//! and slot 1 is a 50 %-weighted variation of animation id 0.**
-//!
-//! `BlackrockStatueLavaBubble.m2` is placed 15 times inside `Blackrock.wmo`. It authors two
-//! sequences, both animation id 0 with frequencies 16384/16383 — so the reference re-rolls between
-//! them every play-window (wow-re `doodad-anim-host.md` §5, decision 0768) and two placements are
-//! on different slots at the same instant. Slot 0 is a dead hold: its bone-scale window is two
-//! identity keys and its texture-transform window is two zero keys. Slot 1 is the whole animation:
-//! the bubbles swell 1.0 → 2.785 while the sprite's V offset flips by 0.605.
-//!
-//! benilla baked the UV loop against slot 0 and only slot 0, through a registry keyed by MATERIAL —
-//! shared by every instance of the batch, so there is no sequence to key on. On this model that
-//! bakes to `None`: no registration, no table row, no scroll, on every placement, for ever. This
-//! file pins both halves of that — the dead slot 0 and the live slot 1 — so the per-sequence set
-//! can never silently collapse back to one loop.
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! The Blackrock lava bubble keys all its animation in file sequence slot 1, a 50% variation of
+//! animation id 0: both sequences are id 0 at frequencies 16384 and 16383, re-rolled every play
+//! window (`0x6951b0`). Slot 0 holds still; slot 1 swells the bubbles to 2.785 and flips the V
+//! offset by 0.605.
 
 use benilla_formats::{open_chain, parse_m2_animations, parse_m2_render_submeshes};
 
@@ -30,8 +16,6 @@ fn the_lava_bubble_keys_its_whole_uv_flipbook_in_variation_one() {
         .read_file(BUBBLE)
         .expect("the bubble M2 is in the chain");
 
-    // 1. Two sequences, both animation id 0 — a variation chain, not a state machine. The roll is
-    //    per placement and per window, so no single slot can be "the" one to bake.
     let anims = parse_m2_animations(&bytes);
     assert_eq!(anims.len(), 2, "two sequences");
     assert!(
@@ -44,7 +28,6 @@ fn the_lava_bubble_keys_its_whole_uv_flipbook_in_variation_one() {
         anims.iter().map(|a| a.frequency).collect::<Vec<_>>()
     );
 
-    // 2. The bones say it first: slot 0 holds bind pose, slot 1 swells past 2.7×.
     let peak = |slot: usize| {
         anims[slot]
             .bones
@@ -55,9 +38,6 @@ fn the_lava_bubble_keys_its_whole_uv_flipbook_in_variation_one() {
     assert!((peak(0) - 1.0).abs() < 1e-3, "slot 0 is a rest hold");
     assert!(peak(1) > 2.5, "slot 1 is the swell (peak {})", peak(1));
 
-    // 3. …and the UV channel agrees, which is the half benilla renders. Every batch carries a
-    //    per-sequence set — the bake's own "the slots disagree, this batch cannot take the shared
-    //    lane" verdict — whose slot 0 is empty and whose slot 1 moves.
     let subs = parse_m2_render_submeshes(&bytes, "", &[]).expect("parse");
     assert_eq!(subs.len(), 5, "five bubbles, five batches");
     for (i, sub) in subs.iter().enumerate() {
@@ -89,8 +69,6 @@ fn the_lava_bubble_keys_its_whole_uv_flipbook_in_variation_one() {
         );
     }
 
-    // 4. And the pre-1408 read — the shared lane's slot-0 bake — is `None` on every batch. This is
-    //    the defect stated as an assertion: nothing to register, so nothing ever scrolled.
     assert!(
         subs.iter().all(|s| s.uv_anim.is_none()),
         "the slot-0 bake yields nothing on any batch — the frozen sprite B98 reported"
diff --git a/crates/benilla-formats/tests/particle_burst_gate.rs b/crates/benilla-formats/tests/particle_burst_gate.rs
index 51de70f0..63a8e236 100644
--- a/crates/benilla-formats/tests/particle_burst_gate.rs
+++ b/crates/benilla-formats/tests/particle_burst_gate.rs
@@ -1,22 +1,6 @@
-//! The **burst gate**, pinned against a shipped asset whose gate never opens.
-//!
-//! A burst emitter fires on the rising edge of `enabled != 0 && sampledRate > 0`, both tracks
-//! sampled from the same clock in the same frame (wow-re `part-emission-burst-flag.md` §1,
-//! `0x718ed2`–`0x718ef6`). `Spells\Strike_Impact_Chest.m2` — the gold flare every warrior ability
-//! impact plays (kit 437 → `SpellVisualEffectName` 416, attached at the target's chest `0x22`) —
-//! carries two burst emitters, and **only one of them ever emits**:
-//!
-//! - #0 (`WEAPON\FLARE.BLP`): the enabled track steps `1 → 0` at the exact keyframe the rate track
-//!   steps `0 → 50`. The two conditions are never true together, so it fires nothing, ever.
-//! - #1 (`FirePlume64.blp`): gate held ON by a single key, rate `0 → 30 → 0`. It fires once.
-//!
-//! This is here because the *instrument* got it wrong first: the `m2part` dump derived a burst
-//! count from `peak_rate()` alone and reported "burst of ~50 particles" for #0, which put a
-//! diagnosis of "our impact bursts are too big" 2.7x over on particle count before anyone noticed.
-//! An emitter that never fires is a real shipped shape, not a parse failure, and the reader must
-//! be able to see the difference.
-//!
-//! Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! A burst emitter fires on the rising edge of `enabled != 0 && sampledRate > 0`, both sampled on
+//! one clock in one frame (`0x718ed2`-`0x718ef6`). Of the warrior impact flare's two (kit 437),
+//! #0's enabled track steps to 0 on the key its rate steps to 50, so only #1 ever fires.
 
 use benilla_formats::{open_chain, parse_m2_particle_emitters};
 
diff --git a/crates/benilla-formats/tests/particles.rs b/crates/benilla-formats/tests/particles.rs
index 7b407590..489eee71 100644
--- a/crates/benilla-formats/tests/particles.rs
+++ b/crates/benilla-formats/tests/particles.rs
@@ -1,5 +1,4 @@
-//! Difftest the vanilla M2 particle-emitter parser against the real `ElwynnCampfire.m2` (the
-//! Goldshire-area campfire). Skips (passes) when the client isn't present at `<repo>/WoW/Data`.
+//! The M2 particle-emitter parser against shipped models.
 
 use benilla_formats::{
     open_chain, parse_m2_particle_emitters, CellRamp, OverLife, ParticleBlend, ParticleShape,
@@ -15,8 +14,7 @@ fn campfire_emitters_match_real_bytes() {
 
     let emitters = parse_m2_particle_emitters(&bytes).expect("parse emitters");
 
-    // The campfire has exactly two additive plane emitters: a wide slow glow/smoke plume and a fast
-    // narrow flame with a 4×4 cell flicker. These values are read straight off the real file.
+    // Two additive plane emitters, a slow glow plume and a fast 4×4-flipbook flame, off the file.
     assert_eq!(emitters.len(), 2, "campfire has two emitters");
 
     for e in &emitters {
@@ -30,7 +28,6 @@ fn campfire_emitters_match_real_bytes() {
             .expect("ambient prop rates are constant tracks");
         assert!(rate > 0.0 && rate.is_finite());
         assert!(now.horizontal_range > 6.0, "campfire emits in a full ring");
-        // Texture resolves to a real .blp via the M2 textures table.
         assert!(
             e.texture.as_deref().is_some_and(|t| !t.is_empty()),
             "emitter texture resolves, got {:?}",
@@ -38,7 +35,6 @@ fn campfire_emitters_match_real_bytes() {
         );
     }
 
-    // Glow/smoke plume: wide 20° cone, long life, low rate, single cell.
     let glow = &emitters[0];
     let glow_now = glow.params.sample(None, 0.0, 0.0);
     assert!(
@@ -54,7 +50,6 @@ fn campfire_emitters_match_real_bytes() {
     assert_eq!((glow.tile_rows, glow.tile_cols), (1, 1));
     assert!(glow_now.vertical_range > 0.3, "glow has a wide cone");
 
-    // Flame: short life, high rate, narrow cone, 4×4 cell animation.
     let flame = &emitters[1];
     let flame_now = flame.params.sample(None, 0.0, 0.0);
     assert!(
@@ -77,11 +72,7 @@ fn campfire_emitters_match_real_bytes() {
         "flame is a tight upward jet"
     );
 
-    // Drag (file +0x194): the velocity-decay term the verified integrator applies as
-    // `vel −= min(dt·drag, 1)·vel`. The campfire's smoke/glow plume carries a gentle 0.5 (contained
-    // column); its short-lived flame carries 0.0 (a free upward jet). Read straight off the real
-    // bytes — the candelabra props instead author a strong 10.0 and rely on it to stay a flicker
-    // (decision 0027).
+    // Drag, file `+0x194`, decays velocity as `vel -= min(dt·drag, 1)·vel`.
     assert!(
         (glow.drag - 0.5).abs() < 1e-3,
         "campfire glow drag ~0.5, got {}",
@@ -93,8 +84,6 @@ fn campfire_emitters_match_real_bytes() {
         flame.drag
     );
 
-    // Over-life ramps (verified tail). Dump the sampled color/size/cell across life, and assert the
-    // believability invariants: a fading additive weight (A) and a sensible size in yards.
     eprintln!("campfire emitters OK:");
     for (i, e) in emitters.iter().enumerate() {
         let ol = &e.over_life;
@@ -121,14 +110,12 @@ fn campfire_emitters_match_real_bytes() {
             );
         }
 
-        // Sizes are finite, non-negative, and small (campfire props are ~sub-yard to a couple yards).
         for s in ol.scale {
             assert!(
                 s.is_finite() && (0.0..8.0).contains(&s),
                 "emitter {i} scale {s} sane"
             );
         }
-        // Color/alpha keys are valid 0..1.
         for k in ol.color {
             for ch in k {
                 assert!(
@@ -143,7 +130,6 @@ fn campfire_emitters_match_real_bytes() {
         );
     }
 
-    // The glow/smoke plume fades out: its additive weight (alpha) at end-of-life is below its peak.
     let glow_ol = &emitters[0].over_life;
     let a_start = glow_ol.sample(0.0).color[3];
     let a_end = glow_ol.sample(1.0).color[3];
@@ -152,7 +138,6 @@ fn campfire_emitters_match_real_bytes() {
         "glow alpha should not rise over life ({a_start} -> {a_end})"
     );
 
-    // The flame's cell index advances across its 4×4 atlas over life (the flicker animation).
     let flame_ol = &emitters[1].over_life;
     let cell_start = flame_ol.sample(0.0).head_cell;
     let cell_end = flame_ol.sample(1.0).head_cell;
@@ -162,28 +147,20 @@ fn campfire_emitters_match_real_bytes() {
     );
 }
 
-/// The flipbook **cell ramp**, against the reference's own emulated output (wow-re
-/// `part-cell-flipbook-ramp.md` §5 — `emu.call(0x7b9da0)` to build the record, `emu.call(0x7b9b10)`
-/// to sample it). Two properties, and the second is the one that crashed us (decision 0685):
-///
-/// 1. **The endpoint law** — `cell(0) == begin` and `cell(1) == end`, EXACTLY, in both directions.
-///    That is what the `±1` in the build arms and the evaluator's `0.99·t + 0.005` inset exist to
-///    buy; either one alone is off by one at an endpoint.
-/// 2. **A DECREASING pair plays the flipbook backwards** — it is not swapped, not clamped, not
-///    sign-normalized. Shipped data authors it, so a `clamp(begin, end)` here is both wrong and
-///    (in Rust) a panic.
+/// The flipbook cell ramp against the reference's output (`0x7b9da0` builds it, `0x7b9b10` samples
+/// it): `cell(0) == begin` and `cell(1) == end` exactly, by the build's `±1` and the
+/// `0.99·t + 0.005` inset together, and a decreasing pair plays backwards.
 #[test]
 fn cell_ramp_matches_the_reference_including_backwards() {
     let at = |begin: u16, end: u16| {
         let r = CellRamp::new(begin, end);
-        // The sample points the wow-re oracle tabulates, through the same inset the evaluator
-        // applies (u = 0, ¼, ½, ¾, 1 of the segment).
+        // u = 0, ¼, ½, ¾ and 1, through the evaluator's inset.
         [0.0_f32, 0.25, 0.5, 0.75, 1.0]
             .map(|t| r.sample(t * 0.99 + 0.005))
             .to_vec()
     };
 
-    // Forward, and the three inverted pairs the shipped corpus actually authors.
+    // Forward, and the three inverted pairs the shipped corpus authors.
     assert_eq!(at(0, 15), vec![0, 4, 8, 11, 15], "ascending 0..15");
     assert_eq!(at(6, 5), vec![6, 6, 6, 5, 5], "DwarvenBrazier01 (6,5)");
     assert_eq!(
@@ -193,17 +170,13 @@ fn cell_ramp_matches_the_reference_including_backwards() {
     );
     assert_eq!(at(15, 0), vec![15, 11, 8, 4, 0], "ShadowWordSilence (15,0)");
 
-    // The endpoint law over every direction and the degenerate equal pair.
     for (b, e) in [(0, 15), (8, 16), (31, 16), (15, 0), (6, 5), (7, 7), (0, 63)] {
         let r = CellRamp::new(b, e);
         assert_eq!(r.sample(0.005), b, "cell(u=0) == begin for ({b},{e})");
         assert_eq!(r.sample(0.995), e, "cell(u=1) == end for ({b},{e})");
     }
 
-    // …and END-TO-END through `OverLife::sample`, which is where the inset is actually applied.
-    // Asserting the law on `CellRamp` alone passes even with the inset deleted (it feeds one in
-    // itself) — a mutation check caught exactly that hole. The reference has ONE normalized time
-    // and every consumer reloads it, so the endpoints must land on a whole-life sample too.
+    // Through `OverLife::sample`, where the inset is applied.
     let ol = OverLife {
         mid: 0.5,
         color: [[1.0; 4]; 3],
@@ -224,11 +197,8 @@ fn cell_ramp_matches_the_reference_including_backwards() {
     );
 }
 
-/// Colour and size ride the **same inset** as the cells — `0x7b9b10` computes `t·0.99 + 0.005`
-/// once, into its own `age` slot, and all four colour channels and the size reload that slot
-/// (wow-re `part-cell-flipbook-ramp.md` §3a). So a particle never sits exactly on an authored key:
-/// it starts 0.5 % into the ramp and ends 0.5 % short. Lerping on a raw `t` is wrong at both ends
-/// of both segments — a small error, but a systematic one, and free to get right.
+/// Colour and size ride the cells' inset: `0x7b9b10` stores `t·0.99 + 0.005` once and every
+/// channel reloads it, so a particle starts 0.5% into its ramp and ends 0.5% short.
 #[test]
 fn colour_and_size_ride_the_same_inset() {
     let ol = OverLife {
@@ -239,7 +209,7 @@ fn colour_and_size_ride_the_same_inset() {
         tail_cells: [CellRamp::new(0, 0); 2],
         repeat: [1.0; 2],
     };
-    // Segment A runs 0 → 100 over u ∈ [0, 0.5]; at u=0 the inset puts us 0.5 % along it.
+    // Segment A runs 0 to 100 over u in [0, 0.5].
     let start = ol.sample(0.0);
     assert!(
         (start.size - 0.5).abs() < 1e-4,
@@ -251,7 +221,6 @@ fn colour_and_size_ride_the_same_inset() {
         "colour takes the same inset: got {}",
         start.color[0]
     );
-    // …and 99.5 % of the way at the segment's end, not 100 %.
     let end = ol.sample(0.5);
     assert!(
         (end.size - 99.5).abs() < 1e-3,
@@ -260,9 +229,7 @@ fn colour_and_size_ride_the_same_inset() {
     );
 }
 
-/// The crash reported from Winterspring (B88): `DwarvenBrazier01`'s settling flame authors the
-/// inverted segment-B pair `(6,5)`, which the old `idx.clamp(begin, end)` met with a panic —
-/// `clamp` requires `min <= max`. Sampling the real record across life must simply work.
+/// `DwarvenBrazier01`'s settling flame authors the inverted segment-B pair `(6, 5)`.
 #[test]
 fn inverted_ramp_on_real_data_does_not_panic() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -289,10 +256,8 @@ fn inverted_ramp_on_real_data_does_not_panic() {
     }
 }
 
-/// The per-segment flipbook **repeat count** (file +0x16c/+0x172): `fmod(t·repeat, 1.0)` cycles the
-/// cell ramp that many times across the segment. 18 shipped emitters author one — all of them the
-/// druid Insect Swarm visuals, whose insects flap by cycling a 5- or 8-pass flipbook. A reader that
-/// ignores the field runs the sheet exactly once and the swarm never flaps.
+/// The per-segment flipbook repeat count (file `+0x16c`, `+0x172`) cycles the cell ramp by
+/// `fmod(t·repeat, 1.0)`; the 18 shipped emitters that author one are the Insect Swarm visuals.
 #[test]
 fn repeat_count_cycles_the_flipbook() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -304,7 +269,6 @@ fn repeat_count_cycles_the_flipbook() {
     let ol = &emitters[0].over_life;
     assert_eq!(ol.repeat, [5.0, 5.0], "the swarm authors a 5× cycle");
 
-    // Five passes across segment A means the cell index resets five times: count the drops.
     let mid = ol.mid;
     let mut drops = 0;
     let mut prev = ol.sample(0.0).head_cell;
@@ -321,17 +285,14 @@ fn repeat_count_cycles_the_flipbook() {
     );
 }
 
-/// The record-tail **twinkle** fields (wow-re `part-simspace-fields.md`, their `ac915a7d`):
-/// file +0x188/+0x18c are twinkleScale **{min, max}** — a GATED per-frame size flicker, skipped
-/// when the range is degenerate — NOT a spawn-time size multiplier. The discriminating real-data
-/// case is the kobold candle: it authors `{0, 0}` and burns in the reference client, which the old
-/// `base + rand·variation` reading collapsed to size zero (the director's "candles not burning").
+/// File `+0x188` and `+0x18c` are twinkleScale `{min, max}`, a per-frame size flicker skipped when
+/// the range is degenerate (`0x7b2a50`), not a spawn-time multiplier: the kobold candle authors
+/// `{0, 0}` and burns in the reference.
 #[test]
 fn twinkle_fields_gate_not_scale() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // Kobold candle: twinkle {0,0} — degenerate range, the multiplier must be identity.
     let kobold = parse_m2_particle_emitters(
         &chain
             .read_file("Creature\\Kobold\\Kobold.m2")
@@ -346,13 +307,11 @@ fn twinkle_fields_gate_not_scale() {
         1.0,
         "degenerate {{0,0}} twinkle is identity — the candle burns at ramp size"
     );
-    // Its base size is the over-life ramp alone — nonzero at mid-life.
     assert!(
         candle.over_life.sample(0.5).size > 0.0,
         "the candle flame's over-life size ramp is nonzero"
     );
 
-    // Campfire glow plume: twinkle {0, 1} — an active flicker range; samples lerp min..max.
     let campfire = parse_m2_particle_emitters(
         &chain
             .read_file("World\\Azeroth\\Elwynn\\PassiveDoodads\\Campfire\\ElwynnCampfire.m2")
@@ -362,16 +321,12 @@ fn twinkle_fields_gate_not_scale() {
     let glow = &campfire[0];
     assert_eq!((glow.twinkle_min, glow.twinkle_max), (0.0, 1.0));
     assert_eq!(glow.twinkle(0.25), 0.25, "active range lerps min..max");
-    // A degenerate NON-ZERO range is also identity ({1,1} torches burn steady, not 1–2× inflated).
     assert!(glow.twinkle_percent.is_finite() && glow.twinkle_speed.is_finite());
 }
 
-/// The file→runtime flag remap (wow-re `part-simspace-fields.md` corrections `1f40db0b`, loader
-/// block `0x70faf8–0x70fc44`): the space switch is FILE bit 0x10 (→ rt 0x100), the size-by-scale
-/// enable FILE 0x20 (→ rt 0x200) — pinned on real content whose behavior the reference shows:
-/// the kobold candle (0x01) is carried with no trail and un-flagged for both; the swinging
-/// chandelier's candle flames (0x11/0x15) are model-space (they rigidly ride the swing); the
-/// campfire (0x21/0x29) scales its flame size with the placement.
+/// The file-to-runtime flag remap (`0x70faf8`-`0x70fc44`): file bit 0x10 (runtime 0x100) is model
+/// space, file 0x20 (runtime 0x200) scales size by the placement. The chandelier's flames (0x11,
+/// 0x15) ride its swing; the campfire (0x21, 0x29) scales.
 #[test]
 fn flag_remap_reads_the_file_bits() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -408,12 +363,8 @@ fn flag_remap_reads_the_file_bits() {
     );
 }
 
-/// **The B27 pin, at the real bytes** — `G_BarrelExplode.m2` (GameObject 20737, "Keenly
-/// Disguised Barrel"): all 7 emitters author their explosion inside the one-shot clips
-/// (slot 0 = anim 157, slot 3 = anim 150 Destroy) and an OFF window in both idle sequences
-/// (slot 1 = Stand, slot 2 = anim 147 Closed). The reference shows a quiet barrel at rest; the
-/// old seq-0-only rebase parked the clamped explode clock at its end value and the barrel
-/// burned permanently at 748 live particles.
+/// `G_BarrelExplode.m2` (GameObject 20737): all 7 emitters fire inside the one-shot clips (slot 0,
+/// anim 157; slot 3, anim 150 Destroy) and are off in both idles (slot 1 Stand, slot 2 Closed).
 #[test]
 fn barrel_explode_emitters_are_off_at_rest_and_fire_in_their_clips() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -427,7 +378,6 @@ fn barrel_explode_emitters_are_off_at_rest_and_fire_in_their_clips() {
     assert_eq!(emitters.len(), 7, "the barrel authors seven emitters");
     for (i, e) in emitters.iter().enumerate() {
         assert!(e.timing.peak_rate() > 0.0, "emitter {i} can emit");
-        // OFF through both idle windows — Stand (slot 1) and Closed (slot 2), at any time.
         for slot in [1usize, 2] {
             for t in [0.0f32, 0.1, 0.3, 5.0] {
                 assert!(
@@ -436,12 +386,9 @@ fn barrel_explode_emitters_are_off_at_rest_and_fire_in_their_clips() {
                 );
             }
         }
-        // The one-shot explode clip (slot 0, anim 157, 1 s clamped): the choreography fires
-        // somewhere inside it…
+        // The explode clip, slot 0, runs 1 s and clamps.
         let fires = (0..100).any(|k| e.timing.emitting(Some(0), k as f32 * 0.01, 0.0));
         assert!(fires, "emitter {i} fires inside the explode clip");
-        // …and the clamped clock PARKS OFF at/after the clip end — the exact end state the old
-        // rebase got wrong (it clamped a later clip's ON key onto the band end).
         assert!(
             !e.timing.emitting(Some(0), 1.0, 0.0),
             "emitter {i} must be off at the clip end"
@@ -451,21 +398,15 @@ fn barrel_explode_emitters_are_off_at_rest_and_fire_in_their_clips() {
             "emitter {i} must stay off parked past the clip"
         );
     }
-    // The Destroy clip (slot 3, anim 150) fires the explosion too — the quest's actual payoff.
     let destroy_fires = emitters
         .iter()
         .any(|e| (0..100).any(|k| e.timing.emitting(Some(3), k as f32 * 0.01, 0.0)));
     assert!(destroy_fires, "the Destroy clip plays the explosion");
 }
 
-/// The debris family's blend: file `blendingType` **1 is AlphaKey**, not Opaque — the fold that
-/// painted the Lesser Rock Elemental's rock chips as flat pale squares.
-///
-/// Pinned on the elemental because it is the one CREATURE in the corpus that authors mode 1 (a
-/// `partcensus` sweep finds 26 such emitters in 8 models, the other 7 all `Spells\`). The
-/// distinction is load-bearing: mode 1 draws with blending OFF but under `glAlphaFunc(GEQUAL,
-/// 224/255)`, which carves `PARTROCK.BLP`'s silhouette out of the quad; mode 0 has no alpha test
-/// at all, and nothing in 1.12.1 authors it.
+/// Particle `blendingType` 1 is AlphaKey, not Opaque: blending off under `glAlphaFunc(GEQUAL,
+/// 224/255)`, which cuts `PARTROCK.BLP`'s silhouette. The earth elemental is the one creature that
+/// authors it, and nothing in 1.12.1 authors mode 0.
 #[test]
 fn earth_elemental_debris_is_alphakey_not_opaque() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -488,7 +429,6 @@ fn earth_elemental_debris_is_alphakey_not_opaque() {
     assert_eq!(emitters[12].blend, ParticleBlend::AlphaKey);
     assert_eq!(emitters[11].blend, ParticleBlend::Alpha);
 
-    // Nothing on this model — nor anywhere in the shipped corpus — is mode 0.
     assert!(
         !emitters.iter().any(|e| e.blend == ParticleBlend::Opaque),
         "no emitter here folds to Opaque"
diff --git a/crates/benilla-formats/tests/quest_tag_names.rs b/crates/benilla-formats/tests/quest_tag_names.rs
index 68b34da7..3c2ca665 100644
--- a/crates/benilla-formats/tests/quest_tag_names.rs
+++ b/crates/benilla-formats/tests/quest_tag_names.rs
@@ -1,7 +1,5 @@
-//! Asset-gated fixture: `QuestInfo.dbc` against the real 5875 data — pins the whole 7-row tag
-//! vocabulary and the `ID(0)/Name(1)` columns of its 10-column loc-block layout, so a schema drift
-//! or column slip fails loudly instead of quietly blanking every quest-log tag. Skips (passes)
-//! without `<repo>/WoW/Data`.
+//! `QuestInfo.dbc`, the quest tag vocabulary: seven rows, `ID` at column 0 and `Name` at column 1
+//! of a 10-column loc-block layout.
 
 use benilla_formats::{load_quest_tag_names, open_chain};
 
@@ -11,8 +9,7 @@ fn quest_tag_names_are_the_whole_5875_vocabulary() {
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
     let tags = load_quest_tag_names(&mut chain).expect("load quest tag names");
 
-    // The complete table — 5875 ships exactly these seven, and the ids are sparse (so the lookup
-    // must be by id, never by row index).
+    // The whole table. The ids are sparse, so lookup is by id, never by row index.
     let want = [
         (1, "Elite"),
         (21, "Life"),
@@ -22,21 +19,16 @@ fn quest_tag_names_are_the_whole_5875_vocabulary() {
         (82, "World Event"),
         (83, "Legendary"),
     ];
-    // The row count is the load-bearing assert, not a tidiness one. The client resolves this
-    // path to **patch-2.MPQ**; the base `dbc.MPQ` copy has only FOUR rows (PvP, Life, Elite,
-    // Raid, unordered, maxId 62), so a chain that stopped short of the patch would answer `None`
-    // for exactly Dungeon / World Event / Legendary and look perfectly correct on everything
-    // else (wow-re `ui/scratch/questlog-title-tag.md`).
+    // The chain resolves this path to `patch-2.MPQ`; the base `dbc.MPQ` copy has only four rows.
     assert_eq!(tags.len(), want.len(), "QuestInfo.dbc row count");
     for (id, name) in want {
         assert_eq!(tags.resolve(id), Some(name), "QuestInfo id {id}");
     }
 
-    // 1.12 says "Elite" where later expansions say "Group" — the string a group quest's row shows.
+    // 1.12 says "Elite" where later expansions say "Group".
     assert_eq!(tags.resolve(1), Some("Elite"));
 
-    // Type 0 is the untagged majority, and it must resolve to nothing rather than a row.
+    // Type 0 is the untagged majority.
     assert_eq!(tags.resolve(0), None);
-    // An id past the table (a later expansion's Escort/Heroic/Dungeon-tier ids) names nothing.
     assert_eq!(tags.resolve(84), None);
 }
diff --git a/crates/benilla-formats/tests/ribbons.rs b/crates/benilla-formats/tests/ribbons.rs
index 4c7f0709..78431568 100644
--- a/crates/benilla-formats/tests/ribbons.rs
+++ b/crates/benilla-formats/tests/ribbons.rs
@@ -1,5 +1,4 @@
-//! Difftest the vanilla M2 ribbon-emitter parser against real trail-carrying models (wow-5875-re
-//! `ribbon-emitter-spec.md` field map). Skips (passes) when the client isn't present.
+//! The M2 ribbon-emitter parser against shipped trail-carrying models.
 
 use benilla_formats::{open_chain, parse_m2_ribbon_emitters};
 
@@ -8,7 +7,6 @@ fn ribbon_records_match_real_bytes() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open vanilla patch chain");
 
-    // The red wisp — three streamers trailing an animated creature.
     let wisp =
         parse_m2_ribbon_emitters(&chain.read_file("Creature\\WISP\\WispRed.m2").unwrap()).unwrap();
     assert_eq!(wisp.len(), 3, "WispRed authors three ribbons");
@@ -43,7 +41,7 @@ fn ribbon_records_match_real_bytes() {
         }
     }
 
-    // The Thunderblade — a weapon whose enchant trail rides the item root.
+    // A weapon whose enchant trail rides the item root.
     let blade = parse_m2_ribbon_emitters(
         &chain
             .read_file("ITEM\\ObjectComponents\\WEAPON\\Sword_1H_Thunderblade_A_01.m2")
@@ -53,7 +51,6 @@ fn ribbon_records_match_real_bytes() {
     assert_eq!(blade.len(), 3, "Thunderblade authors three ribbons");
     assert!(blade.iter().all(|r| r.texture.is_some()));
 
-    // A ribbon-less model parses to empty (the overwhelming majority).
     let torch = parse_m2_ribbon_emitters(
         &chain
             .read_file("World\\Generic\\PassiveDoodads\\Lights\\Torch.m2")
diff --git a/crates/benilla-formats/tests/selection_ring_radius.rs b/crates/benilla-formats/tests/selection_ring_radius.rs
index d198cdba..64b0d3e8 100644
--- a/crates/benilla-formats/tests/selection_ring_radius.rs
+++ b/crates/benilla-formats/tests/selection_ring_radius.rs
@@ -1,24 +1,7 @@
-//! Pins the selection-ring radius against the **pixel-measured reference** on real build-5875 assets.
-//!
-//! The reference client sizes a **living unit's** ground selection ring (draw `0x608e00`, sizer
-//! `0x60aee0`) as:
-//!
-//! ```text
-//! ring_radius = OBJECT_FIELD_SCALE_X × sqrt( 0.5 · sqrt(dx² + dy²) )
-//! ```
-//!
-//! where `dx,dy` are the horizontal (X,Y) extents of the unit's **Stand** animation bounding box (the M2
-//! `M2Sequence` CAaBox), Stand being animation **id 0** via `animationLookup[0]`. This was byte-traced
-//! *and* Unicorn-emulated in wow-re (`system/object-layer/scratch/selection-ring-scale.md`) and
-//! reproduces the reference apitrace's measured ring radii to ~1 mm. It is NOT the render bounding sphere
-//! (`0xCC`) — that (`0x5d6fe0`, `[unit+0x2b0]`) is the *corpse* decal; the render sphere over-sized tall
-//! humans and under-sized the squat chicken because it folds in height, whereas the nested-sqrt footprint
-//! compresses range.
-//!
-//! [`M2Bounds::ring_footprint`] is the model-local (pre-scale) part; the world radius is it ×
-//! `OBJECT_FIELD_SCALE_X`. The four creatures below were the ones captured in the reference trace, drawn
-//! life-size (scale ≈ 1.0), so `ring_footprint` ≈ the measured world radius. Skips when the gitignored
-//! client data isn't present.
+//! A living unit's selection ring (draw `0x608e00`, sizer `0x60aee0`) has radius
+//! `OBJECT_FIELD_SCALE_X * sqrt(0.5 * sqrt(dx² + dy²))` over the Stand sequence box's horizontal
+//! extents (`animationLookup[0]`). The render sphere (`0xCC`) sizes the corpse decal instead
+//! (`0x5d6fe0`, `[unit+0x2b0]`). `M2Bounds::ring_footprint` is the pre-scale part.
 
 use benilla_formats::{load_m2_bounds, open_chain};
 
@@ -27,8 +10,7 @@ fn ring_footprint_matches_reference_pixels() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = open_chain(&data).expect("open chain");
 
-    // (model, ring radius measured from the reference apitrace at scale 1.0). The Stand-box footprint
-    // must reproduce these; a header-render-box or render-sphere source does not.
+    // (model, ring radius measured off a reference frame capture at scale 1).
     let cases = [
         ("Creature\\Chicken\\Chicken.mdx", 0.572_f32),
         ("Character\\Human\\Female\\HumanFemale.mdx", 0.731),
@@ -44,8 +26,6 @@ fn ring_footprint_matches_reference_pixels() {
              sqrt(0.5·sqrt(dx²+dy²)))",
             b.ring_footprint
         );
-        // Guard against a regression to the (wrong) corpse-path render-sphere source: for all four it is
-        // far off (0.5×sphere = 0.33 / 1.19 / 1.39 / 1.96), so it can't sneak past the bound above.
         assert!(
             (b.ring_footprint - 0.5 * b.sphere_radius).abs() > 0.05,
             "{path}: ring_footprint must not coincide with the corpse-path 0.5×renderSphere"
@@ -53,15 +33,9 @@ fn ring_footprint_matches_reference_pixels() {
     }
 }
 
-/// The sizer's **other** branch: a box whose X and Y extents are both exactly zero takes the
-/// literal 1.2 (`0x60af4f..0x60af67`, `0x3f99999a`) and never reaches the formula.
-///
-/// wow-re recorded this branch as one that "never fires for real creatures" — true of the four
-/// life-size units it measured, false of the whole trigger-creature family. `InvisibleStalker`
-/// authors **all 135** of its sequence boxes at zero, so 1.2 is its ring, and the Naxxramas weapon
-/// mobs (an `InvisibleStalker` body holding a visible axe, display 15294 at scale 2.25 ⇒ a 2.7 yd
-/// ring) are exactly where a player meets it. We computed `sqrt(0.5·sqrt(0))` = 0 and drew a ring
-/// the width of a coin — the director's A/B against the reference is what caught it. Decision 1658.
+/// A box whose X and Y extents are both zero takes the literal 1.2 (`0x60af4f`..`0x60af67`,
+/// `0x3f99999a`): `InvisibleStalker` authors all 135 sequence boxes at zero, so the Naxxramas
+/// weapon mobs on its body (display 15294, scale 2.25) ring at 2.7 yd.
 #[test]
 fn a_degenerate_stand_box_rings_at_the_reference_constant() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -69,9 +43,7 @@ fn a_degenerate_stand_box_rings_at_the_reference_constant() {
 
     let path = "Creature\\InvisibleStalker\\InvisibleStalker.mdx";
     let b = load_m2_bounds(&mut chain, path).unwrap_or_else(|e| panic!("bounds {path}: {e}"));
-    // The premise: this model really is the degenerate case, on the header box and the Stand box
-    // alike (0 vertices ⇒ nothing to bound). If Blizzard had authored a box here the constant
-    // below would be the wrong answer, so pin the input, not just the output.
+    // No vertices, so nothing is bounded, the header box and the Stand box alike.
     assert_eq!(
         (b.bbox_min, b.bbox_max, b.sphere_radius),
         ([0.0; 3], [0.0; 3], 0.0),
diff --git a/crates/benilla-formats/tests/spell_catalog.rs b/crates/benilla-formats/tests/spell_catalog.rs
index fc2ab09e..e435b089 100644
--- a/crates/benilla-formats/tests/spell_catalog.rs
+++ b/crates/benilla-formats/tests/spell_catalog.rs
@@ -1,7 +1,5 @@
-//! Asset-gated fixture: the Spell/SpellIcon join against the real 5875 data — pins the derived
-//! columns (SpellIconID = 117, SpellName enUS = 120, SpellVisualID = 115, Speed = 37; see
-//! `src/spells.rs` docs) to known spells, so a schema drift or column slip fails loudly. Skips
-//! (passes) without `<repo>/WoW/Data`.
+//! `Spell.dbc` columns pinned on known spells: SpellIconID 117, the enUS SpellName 120,
+//! SpellVisualID 115 and Speed 37.
 
 use benilla_formats::{load_spell_catalog, open_chain};
 
@@ -16,7 +14,6 @@ fn spell_catalog_resolves_known_spells() {
         catalog.len()
     );
 
-    // The column-derivation probes, now as regressions.
     let hs = catalog.get(78).expect("Heroic Strike");
     assert_eq!(hs.name, "Heroic Strike");
     assert_eq!(
@@ -35,14 +32,8 @@ fn spell_catalog_resolves_known_spells() {
     assert_eq!(attack.name, "Attack");
     assert!(attack.icon.is_some(), "auto-attack has an icon");
 
-    // The visual/speed column pins (decision 0107 data plane), cross-checked against the local
-    // vmangos `spell_template` (`spellVisual1`/`speed`) — see `src/spells.rs` docs for the method.
-    // **`PreventionType` (column 165)** — which crowd-control flag refuses the spell LOCALLY
-    // (decision 1903): 1 silence, 2 pacify, 0 neither. Pinned here because the column has an
-    // adjacent look-alike: 164 is `DmgClass`, which takes the same 0/1/2 on every one of these
-    // rows. **Auto Shot separates them decisively** — it is `DmgClass = 3` (RANGED), a value
-    // `PreventionType` never takes, so a one-column slip fails this test rather than passing
-    // quietly. (The byte offset `SpellRec+0x294 / 4 = 165` is the other half of the pin.)
+    // `PreventionType`, column 165 (`SpellRec+0x294`): 1 silence, 2 pacify, 0 neither. Column
+    // 164, `DmgClass`, also runs 0 to 2 on these rows, except Auto Shot's 3.
     assert_eq!(
         catalog.get(133).expect("Fireball").prevention_type,
         1,
@@ -65,10 +56,7 @@ fn spell_catalog_resolves_known_spells() {
          distinguishable from 165 at all"
     );
 
-    // **The crowd-control exemption's three columns** (decision 1946): `School` 1, `Mechanic` 5,
-    // `EffectMechanic[0..2]` 79–81. Pinned against spells whose values are common knowledge, and
-    // the per-effect pair is the convincing half — Frostbolt carries its SNARE on effect 0 and
-    // Frost Nova its ROOT on effect 1, which no neighbouring column would reproduce.
+    // The crowd-control exemption's columns: `School` 1, `Mechanic` 5, `EffectMechanic` 79-81.
     assert_eq!(catalog.get(133).expect("Fireball").school, 2, "fire");
     assert_eq!(catalog.get(116).expect("Frostbolt").school, 4, "frost");
     assert_eq!(catalog.get(585).expect("Smite").school, 1, "holy");
@@ -105,6 +93,7 @@ fn spell_catalog_resolves_known_spells() {
         "Frost Nova's root is MECHANIC_ROOT, on effect 1 — not effect 0"
     );
 
+    // Visual and speed as vmangos `spell_template` has them (`spellVisual1`, `speed`).
     let fireball = catalog.get(133).expect("Fireball");
     assert_eq!(fireball.visual, 67, "Fireball's SpellVisual id");
     assert_eq!(fireball.speed, 24.0, "Fireball's projectile speed");
@@ -123,8 +112,7 @@ fn shapeshift_bonus_bars_match_the_verified_table() {
     let data = benilla_formats::wow_data_or_skip!();
     let mut chain = benilla_formats::open_chain(&data).expect("open vanilla patch chain");
     let forms = benilla_formats::load_shapeshift_forms(&mut chain).expect("load shapeshift rows");
-    // The complete 5875 non-zero BonusActionBar set (wow-re byte-verified: SpellShapeshiftForm
-    // field 1, the exact lookup GetBonusBarOffset's cached global is filled from).
+    // Every non-zero BonusActionBar, field 1, which GetBonusBarOffset reads (`0x4e4fc0`).
     let expect = [(1, 1), (5, 3), (8, 3), (17, 1), (18, 2), (19, 3), (30, 1)];
     let nonzero = forms.values().filter(|f| f.bonus_bar != 0).count();
     assert_eq!(nonzero, expect.len(), "exactly the seven non-zero rows");
@@ -135,16 +123,13 @@ fn shapeshift_bonus_bars_match_the_verified_table() {
             "form {form}"
         );
     }
-    // flags1 (the form gate's stance bit): warrior stances + stealth are stances; cat is a
-    // true shapeshift.
+    // flags1's stance bit: warrior stances and stealth are stances, cat is a shapeshift.
     for stance in [17u32, 18, 19, 30] {
         assert!(forms.get(&stance).unwrap().is_stance(), "form {stance}");
     }
     assert!(!forms.get(&1).unwrap().is_stance(), "cat is a shapeshift");
-    // flags1 bit 0x2 (the stance bar's toggle-cancel BLOCK, wow-re shapeshift-bar-api.md): the
-    // three warrior stances carry it (0x7 — clicking the active stance is a silent no-op); the
-    // cancelable forms don't (Cat 0x70, Bear/DireBear 0x50, Ghost Wolf 0x40, Shadowform 0x9,
-    // Stealth 0x1, Moonkin 0x41 — probed on the extracted file).
+    // flags1 bit 0x2 blocks the stance bar's toggle-cancel (`0x4b4963`): the warrior stances
+    // (0x7) carry it, so clicking the active one does nothing.
     for stance in [17u32, 18, 19] {
         assert!(
             !forms.get(&stance).unwrap().cancelable(),
@@ -159,9 +144,8 @@ fn shapeshift_bonus_bars_match_the_verified_table() {
     }
 }
 
-/// The stance-bar Spell.dbc columns (wow-re shapeshift-bar-api.md; column pins probed on the
-/// extracted 5875 file, decision 0270): the MOD_SHAPESHIFT form id, the signed StanceBarOrder
-/// (Stealth's −1 sorts last), and the druid forms' ActiveIconID. Skips without client data.
+/// The stance bar's Spell.dbc columns: the MOD_SHAPESHIFT form id, the signed StanceBarOrder that
+/// `0x4b2bb0` sorts by (Stealth's -1 last), and the ActiveIconID `0x4b45c0` reads.
 #[test]
 fn stance_bar_spell_columns_match_the_probed_values() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -181,17 +165,15 @@ fn stance_bar_spell_columns_match_the_probed_values() {
         assert_eq!(d.shapeshift_form, Some(form), "spell {spell} form");
         assert_eq!(d.stance_bar_order, order, "spell {spell} order");
     }
-    // ActiveIconID: druid forms carry the dismiss-paw (icon 122 resolves); warrior stances 0.
+    // Druid forms carry the dismiss-paw ActiveIconID, 122; warrior stances carry 0.
     assert!(catalog.get(5487).unwrap().active_icon.is_some(), "bear");
     assert!(catalog.get(2457).unwrap().active_icon.is_none(), "battle");
-    // A non-form spell reads none of it.
     let fireball = catalog.get(133).unwrap();
     assert_eq!(fireball.shapeshift_form, None);
 }
 
-/// AttributesEx3 (column 9) bit 15 — `SPELL_ATTR3_NORMAL_RANGED_ATTACK`, the combat-text
-/// melee-white flip (decision 0376): set on exactly the ranged basic shots, clear on melee
-/// abilities and true spells.
+/// AttributesEx3 (column 9) bit 15, `SPELL_ATTR3_NORMAL_RANGED_ATTACK`, turns combat text
+/// melee-white: it is set on the ranged basic shots only.
 #[test]
 fn melee_white_damage_marks_the_ranged_basic_shots() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -204,8 +186,7 @@ fn melee_white_damage_marks_the_ranged_basic_shots() {
             "spell {id} should carry AttributesEx3 & 0x8000"
         );
     }
-    // Heroic Strike (a melee ability — its yellow rides the ATTACKERSTATEUPDATE spell-id rider,
-    // not this bit), Fireball, and Attack itself: all clear.
+    // Heroic Strike, Fireball, Attack. A melee ability's yellow rides the spell id, not this bit.
     for id in [78u32, 133, 6603] {
         assert!(
             !catalog.get(id).unwrap().melee_white_damage(),
diff --git a/crates/benilla-formats/tests/transport_speed_profile.rs b/crates/benilla-formats/tests/transport_speed_profile.rs
index 4865ebce..36cac130 100644
--- a/crates/benilla-formats/tests/transport_speed_profile.rs
+++ b/crates/benilla-formats/tests/transport_speed_profile.rs
@@ -1,22 +1,7 @@
-//! The transport speed-profile probe (decision 0438's reconciliation instrument, director report
-//! 2026-07-17: "ship lagged a bit on the way into Booty Bay").
-//!
-//! Samples the Ratchet–Booty Bay boat's timetable at 60 Hz across its whole cycle and measures the
-//! finite-difference speed. Root-caused the report same day: ClientForms-mode u32 windows
-//! (distance-linear interior timestamps) fed the trapezoid easing — seconds of disagreement, so
-//! the boat pinned at segment ends and leapt on window flips (65 spikes, max 15,009 yd/s, one
-//! 59 s crawl). `build()` now uses the internally-consistent Vmangos accumulation for the sample
-//! table; this test stays as the smooth-motion regression gate. Anomaly classes:
-//! - **speed spikes ≫ cruise (30 yd/s)** at segment boundaries → inter-segment position
-//!   discontinuities (the integer arrive/depart times disagreeing with the float easing) — reads
-//!   as stutter;
-//! - **smooth but modulated speed** (swings well above/below cruise inside segments, worst on
-//!   curves) → the Catmull-Rom *parameter* fraction standing in for an *arc-length* fraction —
-//!   reads as the boat surging/dragging through bends;
-//! - **neither** → the lag wasn't the timetable (frame hitches from Booty Bay's asset streaming
-//!   are the next suspect).
-//!
-//! Run: `cargo test -p benilla-formats --test transport_speed_profile -- --nocapture`
+//! Samples the Ratchet-Booty Bay boat's timetable at 60 Hz over its whole cycle and measures the
+//! finite-difference speed against its 30 yd/s cruise. A spike at a segment boundary is a position
+//! discontinuity; a smooth swing through a bend is the spline parameter standing in for arc length.
+//! `--nocapture` prints the profile.
 
 use benilla_formats::{load_taxi_path_nodes, open_chain, TransportTimetable};
 
@@ -32,8 +17,7 @@ fn ratchet_booty_bay_speed_profile() {
     let nodes = load_taxi_path_nodes(&mut chain).expect("taxi nodes");
     let path = nodes.path(241).expect("path 241 (Ratchet–Booty Bay)");
     let tt = TransportTimetable::build(path, 30.0, 1.0).expect("timetable");
-    // The build self-pins its period to the client-transcribed bookkeeping (bit-exact, wow-re
-    // §5 2026-07-17); this cross-checks the pin landed for the path under measurement.
+    // The build pins its period to the reference's own bookkeeping, bit-exact.
     assert_eq!(tt.period_ms, 350_818, "path 241's self-pinned period");
 
     let step_ms = 16u32; // ~60 Hz
@@ -81,7 +65,7 @@ fn ratchet_booty_bay_speed_profile() {
             format!(" — first 10: {:?}", &spikes[..spikes.len().min(10)])
         }
     );
-    // Cluster the slow samples into runs so the report reads as "windows", not thousands of rows.
+    // Cluster the slow samples into runs.
     let mut slow_runs: Vec<(u32, u32, f32)> = Vec::new(); // (start, end, min_speed)
     for &(t, v) in &slow_underway {
         match slow_runs.last_mut() {
@@ -104,11 +88,9 @@ fn ratchet_booty_bay_speed_profile() {
         );
     }
 
-    // The structural assertion: a window/easing inconsistency reads as a position jump traversed
-    // in one 16 ms step — hundreds to thousands of yd/s (the pre-fix table measured 15,009).
-    // Healthy motion peaks ~51 yd/s (the Catmull-Rom parameter-vs-arc-length artifact through one
-    // sharp bend, ~1.5 s per cycle — a known, bounded residual pending the wow-re per-point-table
-    // verdict, decision 0439).
+    // A discontinuity crosses in one 16 ms step at hundreds of yd/s. Smooth motion peaks near
+    // 51 yd/s through one sharp bend: the table between stops is vmangos-mode, the spline parameter
+    // standing in for arc length, and the reference's per-leg evaluation is not ported.
     assert!(
         max_speed < 100.0,
         "position discontinuity: {max_speed:.1} yd/s at cycle {max_speed_at} ms"
diff --git a/crates/benilla-formats/tests/wmo_chunk_overrun.rs b/crates/benilla-formats/tests/wmo_chunk_overrun.rs
index ef02ccc4..11b0bed0 100644
--- a/crates/benilla-formats/tests/wmo_chunk_overrun.rs
+++ b/crates/benilla-formats/tests/wmo_chunk_overrun.rs
@@ -1,26 +1,11 @@
-//! **The last chunk clamps to EOF.** A WMO's chunk stream is not guaranteed to tile its file
-//! exactly, and the reference tolerates the slop: its walk "reads chunks while the 8-byte header is
-//! in-bounds and clamps the last chunk to EOF (never requires exact tiling)" — wow-re `models.md`,
-//! "WMO chunk-structure contract" (VERIFIED, with a 6332-file corpus oracle), whose own worked
-//! example is the single file in the game that needs the rule: `Undercity_144.wmo`'s MOGP declares
-//! one byte more than the file holds.
-//!
-//! We used to `break` there and hand the caller nothing. That cost g144 its whole MOGP — flags,
-//! portal-ref span, area id, fog, doodad and light refs — and since the portal flood reaches a
-//! neighbour only through a group's ref span, the group became a **dead end**: g144 is the short
-//! corridor joining g95 and g152, so the rooms past it culled from either side and you saw sky
-//! through the doorway (B26, decision 0972).
-//!
-//! Two oracles, because the bug had two halves. The corpus sweep is the one that generalises: it is
-//! the same shape as the reference's own "0 rejected" oracle, and it fails for a *new* file as well
-//! as for this one. The byte pins on g144 catch a clamp that silently returns the wrong slice.
-//! Skips when the client isn't present.
+//! A WMO's last chunk clamps to EOF: the reference's walk (`0x6c3a60`) reads chunks while the
+//! 8-byte header is in bounds and never requires exact tiling. The one shipped file that needs it
+//! is `Undercity_144.wmo`, whose MOGP declares one byte past the end.
 
 use benilla_formats::{parse_wmo_root, wmo_group_header, Chain};
 
-/// The file the rule exists for. Its MOGP header must come back whole, with the exact values the
-/// raw bytes carry at MOGP+0x08 (flags) and MOGP+0x24/0x26 (the portal-ref span) — the two fields
-/// whose loss dead-ended the flood.
+/// g144 is the corridor joining g95 and g152, and its portal-ref span (MOGP `+0x24`, `+0x26`) is
+/// the portal flood's only way through.
 #[test]
 fn undercity_144_mogp_survives_its_one_byte_overrun() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -29,8 +14,6 @@ fn undercity_144_mogp_survives_its_one_byte_overrun() {
         .read("World\\wmo\\Lorderon\\Undercity\\Undercity_144.wmo")
         .expect("read Undercity_144");
 
-    // The overrun is a property of the shipped file — if this ever stops holding, the test below is
-    // no longer exercising the clamp and the rest of this file is decoration.
     let declared =
         u32::from_le_bytes([bytes[0x10], bytes[0x11], bytes[0x12], bytes[0x13]]) as usize;
     assert_eq!(
@@ -45,9 +28,8 @@ fn undercity_144_mogp_survives_its_one_byte_overrun() {
     assert_eq!(h.portal_ref_count, 2, "MOGP+0x26 portal-ref count");
 }
 
-/// The general oracle, mirroring the reference's own: **every** WMO in the corpus yields the chunk
-/// its loader needs — a root parses, a group gives up its MOGP header. This is what makes the rule a
-/// contract rather than a one-file patch; `wmo_chunk_census --all` is the same sweep with a readout.
+/// Every WMO in the corpus yields the chunk its loader needs: a root parses, a group gives up its
+/// MOGP header.
 #[test]
 fn every_wmo_in_the_corpus_yields_its_loader_chunk() {
     let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-formats/tests/wmo_doorway_fade.rs b/crates/benilla-formats/tests/wmo_doorway_fade.rs
index 976c5f4d..0b40cbeb 100644
--- a/crates/benilla-formats/tests/wmo_doorway_fade.rs
+++ b/crates/benilla-formats/tests/wmo_doorway_fade.rs
@@ -1,21 +1,11 @@
-//! **FixColorVertexAlpha** — the bright-doorway portal fade, pinned to the reference's own live
-//! capture (wow-re `trace-forensics-abbey-interior-d3d.md` §2) and to the building the fade is
-//! load-bearing for (Dire Maul's entrance corridors).
-//!
-//! The capture is an unusually exact oracle. It read the abbey's uploaded MOCV vertex buffers back
-//! off the D3D stream and diffed them against the file: **678/678 vertices byte-identical in group 1,
-//! 496/506 in group 3** — the fade is the whole difference, and it is exactly 10 vertices, all at the
-//! one portal whose far side is an EXTERIOR group, all hard-set to `(255,255,255,255)`. Interior↔
-//! interior portals whiten nothing, "including vertices AT portal corners".
-//!
-//! That single pair of counts pins every part of the mechanism at once — the exterior-neighbour gate,
-//! the containment half of the distance kernel (an infinite-plane test whitens 12 here, not 10), and
-//! the absence of the MOPY alpha pre-pass (which would rewrite 372 of group 3's alphas and blow the
-//! "byte-identical" finding apart). Skips when the client isn't present.
+//! FixColorVertexAlpha, the portal fade: MOCV vertices at a portal whose far side is an exterior
+//! group turn `(255, 255, 255, 255)`, interior-to-interior portals whiten nothing, and there is no
+//! MOPY alpha pre-pass. A capture of the reference's uploaded MOCV for the Northshire abbey matches
+//! the file in all 678 vertices of group 1 and in 496 of 506 in group 3.
 
 use benilla_formats::{parse_wmo_root, wmo_group_fixed_colors, Chain};
 
-/// How many of a group's MOCV slots the fade rewrites, and the mean luminance before → after.
+/// (slots the fade rewrites, slot count, mean luminance before, after) for one group.
 fn fade_census(reader: &Chain, stem: &str, gi: u32) -> (usize, usize, f32, f32) {
     let root_bytes = reader.read(&format!("{stem}.wmo")).expect("read root");
     let root = parse_wmo_root(&root_bytes).expect("parse root");
@@ -36,7 +26,6 @@ fn fade_census(reader: &Chain, stem: &str, gi: u32) -> (usize, usize, f32, f32)
     )
 }
 
-/// The abbey, against the D3D capture: group 1 untouched, group 3 rewritten in exactly 10 slots.
 #[test]
 fn abbey_matches_the_reference_capture() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -57,18 +46,16 @@ fn abbey_matches_the_reference_capture() {
         "the capture read 496/506 byte-exact — the fade's whole footprint is 10 slots \
          (an infinite-plane distance test rewrites 12; the MOPY pre-pass would rewrite 372)"
     );
-    // Those 10 were already near-white in the file (225..254) — the fade is a seam touch-up here,
-    // not a lighting change. Anything that moves this group's mean has over-fired.
+    // Those 10 are near-white in the file already (225..254).
     assert!(
         (before - after).abs() < 0.5,
         "abbey g003 mean luminance moved {before} → {after}"
     );
 }
 
-/// Dire Maul's entrance corridors — why the fade is not optional. Each of the five short transition
-/// passages floors its walkway at MOCV `(10,10,40, α=0)`, a near-black navy the interior TRANS law
-/// renders literally: a black floor between lit walls (the director's report, 2026-08-04). The floor
-/// quad's corners sit *in* the doorway portals, so the fade takes them white.
+/// Dire Maul's five entrance corridors author their walkway at MOCV `(10, 10, 40)`, alpha 0, which
+/// the interior TRANS lighting renders near-black; its corners sit in the doorway portals, so the
+/// fade takes them white.
 #[test]
 fn dire_maul_entrance_corridor_floors_are_lit() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -84,16 +71,12 @@ fn dire_maul_entrance_corridor_floors_are_lit() {
         let raw = benilla_formats::wmo_group_raw_colors(&gbytes).expect("MOCV");
         let fixed = wmo_group_fixed_colors(&gbytes, &root).expect("MOCV");
 
-        // The authored walkway: the near-black navy, alpha 0 — the "unlit, the fade lights me" bake.
         let dark = raw.iter().filter(|c| **c == [40, 10, 10, 0]).count();
         assert!(
             dark >= 4,
             "g{gi:03} should author its walkway quad at BGRA (40,10,10,0); found {dark} such slots"
         );
-        // After the fade every one of them reads white: `tex × white` at full lit weight. Not always
-        // *exactly* 255 — a corner a couple of centimetres off the portal plane takes the partial
-        // lerp at `t ≈ 0.997` and lands on 254 — so the assertion is "no longer dark", which is the
-        // claim that matters. 13 → ~255 luminance is the whole bug.
+        // A corner just off the portal plane takes the partial lerp at t ≈ 0.997 and lands on 254.
         for (i, (r, f)) in raw.iter().zip(&fixed).enumerate() {
             if *r == [40, 10, 10, 0] {
                 assert!(
diff --git a/crates/benilla-formats/tests/wmo_fogs.rs b/crates/benilla-formats/tests/wmo_fogs.rs
index 1d395772..f44b5e43 100644
--- a/crates/benilla-formats/tests/wmo_fogs.rs
+++ b/crates/benilla-formats/tests/wmo_fogs.rs
@@ -1,8 +1,5 @@
-//! WMO MFOG + group fog-index parse — byte check against the Goldshire inn (the interior-fog
-//! fold's reference building, wow-re `rf-weather-emission-timeline` ROUND 5). Pins the MFOG
-//! record decode AND the MOGP fog-index disk offset (`0x30` — an earlier from-memory `0x40`
-//! guess read zeros there; the `uniqueID @0x38` / no-liquid `@0x34` neighbours self-validate
-//! the layout). Skips when the client isn't present.
+//! WMO MFOG records, and the MOGP fog indices: four bytes at `+0x30`, before the no-liquid word at
+//! `+0x34` and `uniqueID` at `+0x38`.
 
 use benilla_formats::{parse_wmo_fogs, wmo_group_header, Chain};
 
@@ -14,8 +11,7 @@ fn goldshire_inn_fogs_and_group_indices() {
         .read("World\\wmo\\Azeroth\\Buildings\\GoldshireInn\\GoldshireInn.wmo")
         .expect("read GoldshireInn.wmo");
 
-    // Two MFOG records: the WMO default (the selector's seed, record 0) and a denser room fog.
-    // Both are the warm tavern cream the storm veil must fade toward indoors.
+    // Record 0 is the WMO default, the selector's seed; record 1 is a denser room fog.
     let fogs = parse_wmo_fogs(&root);
     assert_eq!(fogs.len(), 2, "inn should carry 2 MFOG records");
     assert!((fogs[0].fog_end - 194.44444).abs() < 1e-3);
@@ -25,8 +21,7 @@ fn goldshire_inn_fogs_and_group_indices() {
     assert!((fogs[1].fog_end - 83.333336).abs() < 1e-3);
     assert_eq!(fogs[1].color, 0xfffdcf9e);
 
-    // Group fog indices at disk +0x30: the tavern rooms point at record 1, the rest at the
-    // default. area_table_id doubles as the layout's self-check (893.. = the inn's rows).
+    // The tavern rooms point at record 1, the rest at the default; 893.. are the inn's area rows.
     let group = |gi: u32| {
         let bytes = reader
             .read(&format!(
diff --git a/crates/benilla-formats/tests/wmo_lights.rs b/crates/benilla-formats/tests/wmo_lights.rs
index 1ec6c63f..c453657d 100644
--- a/crates/benilla-formats/tests/wmo_lights.rs
+++ b/crates/benilla-formats/tests/wmo_lights.rs
@@ -1,6 +1,5 @@
-//! WMO MOLT light parse — byte check against the Goldshire blacksmith's 3 warm forge lights. Pins the
-//! chunk walk *past* zero-size chunks (`MOVV(0)`/`MOVB(0)` sit right before MOLT — a walk that stops
-//! there finds nothing) and the SMOLight field offsets. Skips when the client isn't present.
+//! WMO MOLT lights, `0x30` bytes a record with a BGRA colour; the chunk walk steps past the
+//! zero-size `MOVV` and `MOVB` that precede MOLT.
 
 use benilla_formats::{parse_wmo_lights, Chain};
 
@@ -13,8 +12,6 @@ fn goldshire_blacksmith_has_three_warm_omni_lights() {
         .expect("read GoldshireBlacksmith.wmo");
 
     let lights = parse_wmo_lights(&bytes);
-    // 3 MOLT lights (the forge). A chunk walk that breaks at MOVV(0)/MOVB(0) — which precede MOLT —
-    // would find 0; this is the regression guard for that bug.
     assert_eq!(lights.len(), 3, "blacksmith should have 3 MOLT lights");
     for l in &lights {
         assert!(
@@ -22,8 +19,7 @@ fn goldshire_blacksmith_has_three_warm_omni_lights() {
             "forge MOLT lights are type 0 (omni), got {}",
             l.light_type
         );
-        // The forge glow is warm orange — RGB(255,140,37) ≈ (1.0, 0.55, 0.145). Pins the BGRA decode
-        // and the 0x30 stride (a garbled offset would not land on a warm colour).
+        // RGB (255, 140, 37).
         let c = l.color;
         assert!(
             c[0] > 0.9 && c[1] > 0.4 && c[1] < 0.7 && c[2] < 0.25,
diff --git a/crates/benilla-formats/tests/wmo_liquid.rs b/crates/benilla-formats/tests/wmo_liquid.rs
index 8515a89f..89070dc3 100644
--- a/crates/benilla-formats/tests/wmo_liquid.rs
+++ b/crates/benilla-formats/tests/wmo_liquid.rs
@@ -1,7 +1,5 @@
-//! WMO MLIQ liquid-surface build — byte check against Stormwind's canals (the reference building
-//! for WMO-embedded water; its city is one 306-group WMO, 22 of whose groups carry `MLIQ`). Pins
-//! the SMOLiquidHeader decode, the `xtiles = xverts − 1` grid, the per-tile hole nibble (`0xf`), and
-//! the lake_a (nibble 4) type resolution. Skips when the client isn't present.
+//! WMO MLIQ liquid surfaces: an `xverts × yverts` grid with one tile fewer each way, and a per-tile
+//! type nibble where `0xf` is a hole and 4 is lake_a.
 
 use benilla_formats::{wmo_group_liquid_mesh, Chain, LiquidKind};
 
@@ -10,8 +8,7 @@ fn stormwind_canal_group_builds_still_water() {
     let data = benilla_formats::wow_data_or_skip!();
     let reader = Chain::open(&data).expect("open vanilla patch chain");
 
-    // Group 099 is a canal segment: MLIQ header xverts=12 yverts=9 (12×9 = 108 verts), 11×8 = 88
-    // tiles of which 52 are wet (nibble 4 = lake_a) and 36 are holes (nibble 0xf).
+    // A canal segment: 12×9 vertices, 11×8 tiles, 52 of them wet and 36 holes.
     let g099 = reader
         .read("World\\wmo\\Azeroth\\Buildings\\Stormwind\\Stormwind_099.wmo")
         .expect("read Stormwind_099.wmo");
@@ -25,7 +22,6 @@ fn stormwind_canal_group_builds_still_water() {
         52 * 6,
         "52 wet tiles → 2 tris each; the 36 hole tiles are skipped"
     );
-    // Every index is in range and every vertex height is a sane, finite value (flat canal water).
     assert!(mesh
         .indices
         .iter()
@@ -37,7 +33,6 @@ fn stormwind_canal_group_builds_still_water() {
         );
     }
 
-    // Group 000 is dry masonry — no MLIQ, so no liquid mesh.
     let g000 = reader
         .read("World\\wmo\\Azeroth\\Buildings\\Stormwind\\Stormwind_000.wmo")
         .expect("read Stormwind_000.wmo");
@@ -47,15 +42,9 @@ fn stormwind_canal_group_builds_still_water() {
     );
 }
 
-/// A hole corner's authored height is not a height, and it must not reach the mesh AABB.
-///
-/// MLIQ carries a full `xverts × yverts` height array whether or not a tile is wet, and the shipped
-/// files leave the hole interiors at a literal `0.0`. Emitted verbatim those are invisible in the
-/// draw — no triangle references them — but they stretch the Bevy mesh AABB from the flat sheet all
-/// the way to model z 0. Measured on the two files below: Blackfathom's Pool of Ask'ar had 186 of
-/// 868 such vertices and an AABB spanning 58.28 yd around a sheet with **zero** vertical extent;
-/// Stormwind's canal g099 had 36 of 108 and spanned 6.48 yd. The builder now fills every
-/// undrawn vertex with the lowest drawn height, so both collapse to flat.
+/// MLIQ carries a height for every vertex, wet or not, and the shipped files leave hole interiors
+/// at `0.0`; the builder gives every undrawn vertex the lowest drawn height, so the mesh bounds
+/// stay on the sheet (186 of 868 such vertices in Blackfathom's pool, 36 of 108 in the canal).
 #[test]
 fn hole_corner_heights_never_reach_the_mesh_bounds() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -76,7 +65,7 @@ fn hole_corner_heights_never_reach_the_mesh_bounds() {
             .unwrap_or_else(|e| panic!("read {path}: {e}"));
         let mesh = wmo_group_liquid_mesh(&group).unwrap_or_else(|| panic!("{path} carries water"));
 
-        // Both pools are dead flat, so EVERY emitted vertex — drawn or not — must sit on the sheet.
+        // Both pools are flat, so every vertex, drawn or not, sits on the sheet.
         let (lo, hi) = mesh
             .positions
             .iter()
@@ -89,7 +78,6 @@ fn hole_corner_heights_never_reach_the_mesh_bounds() {
             "{path}: mesh z spans [{lo}..{hi}], expected the flat sheet at {surface_z}"
         );
 
-        // …and the drawn geometry is unchanged by the substitution: the sheet is still the sheet.
         for &i in &mesh.indices {
             let z = mesh.positions[i as usize][2];
             assert!(
@@ -100,17 +88,9 @@ fn hole_corner_heights_never_reach_the_mesh_bounds() {
     }
 }
 
-/// The two reported sites take **different** water arms, and each carries the inputs its arm reads.
-///
-/// `0x6b62e0`'s category 0 splits on the owning group's `MOGP.flags & 0x48`, and the two halves are
-/// genuinely different renderers — the exterior one binds `MapObjExtWater0.bls` and lights a vertex
-/// normal, the interior one is fixed-function, unlit, and takes its whole body colour from
-/// `MOMT[materialId].diffColor`. B136 (Blackfathom) and the director's "Stormwind water seems too
-/// rough" land on opposite arms, which is the whole reason one shader could not be right for both.
-///
-/// Pins the two inputs a wrong offset would silently corrupt: the pool's `materialId` (so the body
-/// colour is looked up in the right MOMT slot) and the per-vertex opacity byte (which we read as
-/// nothing at all until 2026-08-20, rendering every WMO pool at a pinned, fully-opaque 1.0).
+/// `0x6b62e0`'s category 0 splits on the group's `MOGP.flags & 0x48`: the exterior arm binds
+/// `MapObjExtWater0.bls` and lights a vertex normal; the interior arm is fixed-function, unlit, and
+/// takes its body colour from `MOMT[materialId].diffColor`. Each pool carries a per-vertex opacity.
 #[test]
 fn the_two_water_arms_carry_their_own_inputs() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -149,9 +129,7 @@ fn the_two_water_arms_carry_their_own_inputs() {
              from exactly this index"
         );
 
-        // The opacity channel is per-vertex and really varies: a constant here would mean we were
-        // reading a byte nothing authors (or the wrong byte). Blackfathom's pool spans 202 distinct
-        // values; Stormwind's canals are 91% a single one, so only the range is asserted in common.
+        // Blackfathom's opacity spans 202 values, the canal's is 91% one: only the range is shared.
         let (lo, hi) = mesh
             .depths
             .iter()
@@ -167,12 +145,8 @@ fn the_two_water_arms_carry_their_own_inputs() {
     }
 }
 
-/// One texture repeat per grid cell — the WMO water UV scale, and the fix for "too rough".
-///
-/// The reference's `0x6b6630` writes `u = (float)i, v = (float)j`, raw tile indices from loop
-/// counters that start at a literal 0, so one repeat spans one 4.167 yd cell. We had a quarter of
-/// that: a texture 4x too large, which is exactly two mip levels, so the near field never reached
-/// the authored chain that flattens the ripple with distance.
+/// WMO water repeats its texture once per 4.167-yd grid cell: `0x6b6630` writes `u = i, v = j`
+/// from loop counters that start at 0.
 #[test]
 fn wmo_water_repeats_once_per_grid_cell() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -181,7 +155,7 @@ fn wmo_water_repeats_once_per_grid_cell() {
         .read("World\\wmo\\Azeroth\\Buildings\\Stormwind\\Stormwind_099.wmo")
         .expect("read Stormwind_099.wmo");
     let mesh = wmo_group_liquid_mesh(&g099).expect("group 099 carries water");
-    // Adjacent columns of the 12-wide grid are one cell apart, so exactly one repeat apart.
+    // The grid is 12 vertices wide, so index 12 starts the next row.
     let du = mesh.uvs[1][0] - mesh.uvs[0][0];
     assert!(
         (du - 1.0).abs() < 1e-4,
diff --git a/crates/benilla-formats/tests/wmo_mocv_short_tail.rs b/crates/benilla-formats/tests/wmo_mocv_short_tail.rs
index 2d3e3aed..abe30fb0 100644
--- a/crates/benilla-formats/tests/wmo_mocv_short_tail.rs
+++ b/crates/benilla-formats/tests/wmo_mocv_short_tail.rs
@@ -1,20 +1,9 @@
-//! **A MOCV one record short is still a bake.** The companion to `wmo_chunk_overrun`: clamping the
-//! last chunk to EOF (decision 0972) is only half the tolerance, because the chunk that clamps in
-//! `Undercity_144.wmo` *is* MOCV — 1159 of its declared 1160 bytes, so the colour buffer parses to
-//! 289 entries for 290 vertices.
-//!
-//! The reader then demanded MOCV be exactly parallel to the positions and returned `None` otherwise,
-//! which threw away 289 good colours over one missing byte. An interior batch draws `tex × MOCV`, and
-//! absent colour renders as white, so that corridor lit at full brightness and untinted inside a city
-//! whose every other interior surface is multiplied by a dark bake — the pale, cold arch in the
-//! director's shot, against a reference that shows it warm and lantern-lit (decision 0977).
-//!
-//! Skips when the client isn't present.
+//! A MOCV one record short is still a bake: in `Undercity_144.wmo` the chunk that clamps to EOF is
+//! MOCV, 1159 of its declared 1160 bytes, and the reader pads its 289 colours to the 290 vertices.
 
 use benilla_formats::{parse_wmo_root, wmo_group_raw_colors, Chain};
 
-/// Walk a group file's MOGP sub-chunks (payload clamped to EOF, as the loader does) and return the
-/// declared byte length of `tag`, plus how many of those bytes the file actually holds.
+/// (declared, present) byte lengths of the MOGP sub-chunk `tag`, the payload clamped to EOF.
 fn subchunk(group: &[u8], tag: &[u8; 4]) -> Option<(usize, usize)> {
     let mogp_size =
         u32::from_le_bytes([group[0x10], group[0x11], group[0x12], group[0x13]]) as usize;
@@ -40,8 +29,7 @@ fn subchunk(group: &[u8], tag: &[u8; 4]) -> Option<(usize, usize)> {
     None
 }
 
-/// The file the tolerance exists for: MOCV is its clamped tail, and the bake it carries is the warm
-/// orange the reference renders — not the white an absent bake falls back to.
+/// The bake is the warm orange the reference renders, not the white of an absent bake.
 #[test]
 fn undercity_144_keeps_its_bake_despite_a_short_mocv() {
     let data = benilla_formats::wow_data_or_skip!();
@@ -50,8 +38,6 @@ fn undercity_144_keeps_its_bake_despite_a_short_mocv() {
         .read("World\\wmo\\Lorderon\\Undercity\\Undercity_144.wmo")
         .expect("read Undercity_144");
 
-    // The data fact this rests on: MOVT holds 290 vertices; MOCV declares 290 colours and the file
-    // is one byte short of them. If the shipped file ever changes, this stops testing the tail.
     let (movt_declared, _) = subchunk(&g, b"TVOM").expect("MOVT");
     let (mocv_declared, mocv_present) = subchunk(&g, b"VCOM").expect("MOCV");
     assert_eq!(movt_declared / 12, 290, "MOVT vertex count");
@@ -72,8 +58,7 @@ fn undercity_144_keeps_its_bake_despite_a_short_mocv() {
         290,
         "the buffer must come back parallel to the vertices"
     );
-    // BGRA on the wire. The authored bake here is warm orange — the thing that was being replaced by
-    // white, and the whole visible symptom.
+    // BGRA on disk.
     let [b, gr, r, _a] = raw[0];
     assert!(
         r > 200 && gr > 100 && gr < 200 && b < 120,
@@ -81,10 +66,8 @@ fn undercity_144_keeps_its_bake_despite_a_short_mocv() {
     );
 }
 
-/// The tolerance must stay **narrow**. Exactly one group in the corpus has a MOCV that is not a whole
-/// number of records parallel to its positions; if that count grows, either the reader regressed or
-/// the padding is masking a real parse bug, and either way padding hundreds of vertices from one
-/// sample would invent lighting rather than recover it.
+/// Exactly one group in the corpus has a MOCV that is not whole and parallel to its positions, so
+/// the padding covers that one file.
 #[test]
 fn only_one_group_in_the_corpus_has_a_short_mocv() {
     let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-formats/tests/wow_data_env.rs b/crates/benilla-formats/tests/wow_data_env.rs
index 1b3d022e..c378f840 100644
--- a/crates/benilla-formats/tests/wow_data_env.rs
+++ b/crates/benilla-formats/tests/wow_data_env.rs
@@ -1,13 +1,6 @@
-//! `$WOW_DATA` still wins — the one env read in [`benilla_formats::wow_data`], covered.
-//!
-//! **Why this is an integration test and not a unit test** (decision 1175): setting `$WOW_DATA` is
-//! process-global, and since the sweep every test in the workspace resolves its install through
-//! that one read. A unit test that mutates it poisons whatever else is running in the same test
-//! binary, and the victim moves around with the thread scheduling — which is exactly what happened
-//! before this was pulled out. Cargo gives each integration-test file its own process, and this
-//! file holds one test, so the mutation can only reach itself.
-//!
-//! The ladder itself is unit-tested purely, against `candidates_from`.
+//! `$WOW_DATA` leads the install ladder of [`benilla_formats::wow_data`]. Setting it is
+//! process-global and every test resolves its install through it, so this one test has a file, and
+//! so a process, of its own.
 
 #[test]
 fn the_override_is_read_and_wins() {
diff --git a/crates/benilla-formats/tests/wow_data_none.rs b/crates/benilla-formats/tests/wow_data_none.rs
index 597c8af3..7aba991e 100644
--- a/crates/benilla-formats/tests/wow_data_none.rs
+++ b/crates/benilla-formats/tests/wow_data_none.rs
@@ -1,14 +1,6 @@
-//! `WOW_DATA=` — set and empty — means **there is no install**, through the real env read.
-//!
-//! The ladder's own logic is unit-tested purely against `candidates_from`; this covers the wiring,
-//! which is the half a pure test cannot see. It is its own file for the reason the sibling
-//! `wow_data_env.rs` explains: setting `$WOW_DATA` is process-global, every test in the workspace
-//! now resolves its install through that one read, and cargo gives each integration-test file its
-//! own process — so one mutating test per file can only reach itself.
-//!
-//! What it protects (decision 1451): a dev build on a machine with an install cannot otherwise
-//! reach the no-install boot path, so nothing exercised it and it rotted into a frame-one panic.
-//! This spelling is what `scripts/gates.sh` runs the engine enforcer under.
+//! `WOW_DATA=`, set and empty, means there is no install even where one exists: the spelling
+//! `scripts/gates.sh` runs the engine enforcer under to reach the no-install boot path. Setting it
+//! is process-global, so this test has a file, and so a process, of its own.
 
 #[test]
 fn an_empty_override_means_no_install() {
diff --git a/crates/benilla-m2/Cargo.toml b/crates/benilla-m2/Cargo.toml
index 3840f2f3..2d8b10ec 100644
--- a/crates/benilla-m2/Cargo.toml
+++ b/crates/benilla-m2/Cargo.toml
@@ -3,7 +3,7 @@ name = "benilla-m2"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "M2 (MD20) model reader for WoW 1.12.1 (build 5875) — in-repo, decision 0021"
+description = "M2 (MD20) model reader for WoW 1.12.1 (build 5875)"
 
 [lints]
 workspace = true
diff --git a/crates/benilla-m2/examples/dump_attach.rs b/crates/benilla-m2/examples/dump_attach.rs
index 5685233e..7399a4eb 100644
--- a/crates/benilla-m2/examples/dump_attach.rs
+++ b/crates/benilla-m2/examples/dump_attach.rs
@@ -1,7 +1,6 @@
-//! Session probe: dump an M2's attachment table (+ each attach bone's parent/pivot) —
-//! `cargo run -p benilla-m2 --example dump_attach <file.m2>`. Extract the file first via
-//! `mpqx` (benilla-mpq). Built for the nocked-ammo RE round (decision 2273 follow-up), kept
-//! because "which attach ids does this model actually have" keeps coming up.
+//! Dump an M2's attachments and event markers with their bone's parent:
+//! `cargo run -p benilla-m2 --example dump_attach <file.m2>`, extracted first with `mpqx`
+//! (benilla-formats).
 
 use std::io::Cursor;
 
diff --git a/crates/benilla-m2/examples/dump_skin.rs b/crates/benilla-m2/examples/dump_skin.rs
index 1ed6e927..1471e353 100644
--- a/crates/benilla-m2/examples/dump_skin.rs
+++ b/crates/benilla-m2/examples/dump_skin.rs
@@ -1,7 +1,6 @@
-//! Session probe: dump an M2's skin-0 sections/batches with material + texture resolution —
-//! `cargo run -p benilla-m2 --example dump_skin <file.m2>`. Extract the file first via `mpqx`
-//! (benilla-mpq). Built for the bowstring round (decision 2273 follow-up), kept because "why is
-//! this submesh (not) rendering" keeps coming up.
+//! Dump an M2's textures, materials and skin-0 sections and batches:
+//! `cargo run -p benilla-m2 --example dump_skin <file.m2>`, extracted first with `mpqx`
+//! (benilla-formats).
 
 use std::io::Cursor;
 
diff --git a/crates/benilla-m2/examples/dump_verts.rs b/crates/benilla-m2/examples/dump_verts.rs
index 4b608dc5..398e31bf 100644
--- a/crates/benilla-m2/examples/dump_verts.rs
+++ b/crates/benilla-m2/examples/dump_verts.rs
@@ -1,6 +1,5 @@
-//! Session probe: dump an M2's vertices (position / UV / bone binding) plus bone table —
-//! `cargo run -p benilla-m2 --example dump_verts <file.m2>`. Built for the bowstring round:
-//! find which triangles form the string and how they're textured/bound.
+//! Dump an M2's bones and vertices (position, UV, bone binding):
+//! `cargo run -p benilla-m2 --example dump_verts <file.m2>`.
 
 use std::io::Cursor;
 
diff --git a/crates/benilla-m2/src/lib.rs b/crates/benilla-m2/src/lib.rs
index ecab2523..bc0214c2 100644
--- a/crates/benilla-m2/src/lib.rs
+++ b/crates/benilla-m2/src/lib.rs
@@ -1,27 +1,6 @@
-//! An M2 (MD20) model reader for **WoW 1.12.1 (build 5875)** — in-repo, replacing the `wow-m2` fork
-//! (decision 0021), scoped to the **render path** the renderer consumes.
-//!
-//! Vanilla `.m2` files are MD20 version **256/257**: a fixed header of `M2Array`s (each a `count` +
-//! file `offset`), then the referenced arrays, with the **skin profile(s) embedded** in the same file.
-//! We read only what the mesh builder needs — vertices, textures, materials (render flags), bones
-//! (pivot + flags), the texture-lookup table, and skin profile 0 (indices / triangles / submeshes /
-//! batches) — and deliberately **skip the cosmetic chunks** (particle emitters, lights, texture
-//! animations). That sidesteps exactly what the `wow-m2` fork patched: those chunks can be malformed
-//! in Classic art and abort a full parse; benilla-formats parses lights/particles itself from raw
-//! bytes, so we never touch them here.
-//!
-//! Proven against `wow-m2` over real models during the decision-0021 migration (oracle test in git
-//! history); the creature/GameObject mesh + cosmetic-chunk-model golden tests in benilla-formats pin
-//! it end-to-end on every run.
-//!
-//! Byte access goes through `benilla-bytes` (decision 0064): every read is bounds-checked and a
-//! truncated array/record is a typed [`Error::Truncated`], never a panic; header-driven `Vec`
-//! reservations are capped by what the input could actually hold, so a corrupt count can no longer
-//! OOM-abort the process before the first bounds-checked read ever runs.
-//!
-//! Split by concern: this file keeps the public re-export surface and the top-level [`parse_m2`]
-//! entry + MD20 header walk; `model` holds the plain parsed-record types, `track` the M2Track
-//! scalar/vector readers, `skin` the embedded skin-profile decoder, and `error` the parse error type.
+//! An M2 (MD20) model reader for WoW 1.12.1. Vanilla models are MD20 version 256 or 257: a header
+//! of `M2Array`s (`count`, file `offset`), the arrays they name, and the embedded skin profiles.
+//! Particle emitters and lights are not read here; benilla-formats reads them from the raw bytes.
 
 mod error;
 mod model;
@@ -48,8 +27,7 @@ use benilla_bytes::{capped, ByteExt};
 use error::Result;
 use track::{track_fix16, track_quat, track_spline_f32, track_spline_vec3, track_vec3_timed};
 
-/// Read a `C3Vector` (3×f32) at `o`, bounds-checked. `None` iff any of the three reads would run
-/// past the end — callers map that to their own [`Error::Truncated`].
+/// A `C3Vector` (3×f32) at `o`.
 fn rd_c3(b: &[u8], o: usize) -> Option<C3> {
     Some(C3 {
         x: b.f32_at(o)?,
@@ -58,7 +36,7 @@ fn rd_c3(b: &[u8], o: usize) -> Option<C3> {
     })
 }
 
-/// Parse an MD20 model (v256/257). `cursor` position is ignored; the file starts at the header.
+/// Parse an MD20 model; the cursor's position is ignored.
 pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
     let b: &[u8] = cursor.get_ref();
     if b.len() < 8 || &b[0..4] != b"MD20" {
@@ -69,8 +47,7 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         return Err(Error::UnsupportedVersion(version));
     }
 
-    // Walk the header reading the M2Array `(count, offset)` pairs we need (8 bytes each), applying the
-    // pre-Wrath version conditionals. Layout order per wowdev ADT/M2 + the reference.
+    // Walk the header's `(count, offset)` M2Arrays, 8 bytes each, pre-Wrath layout.
     let arr = |p: usize| -> Result<(u32, u32)> {
         Ok((
             b.u32_at(p).ok_or(Error::Truncated)?,
@@ -85,15 +62,10 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
     p += 8;
     let _anim = arr(p)?;
     p += 8;
-    // AnimationLookup (header `+0x24`/`+0x28`): `AnimationData.dbc` id → this model's first sequence
-    // slot for it, `0xffff` where the model doesn't author it. The reference's "does this model own
-    // animation id X" predicate (`0x711960`) is exactly a bounds-checked read of this table, so it is
-    // parsed rather than inferred from the sequence list — see [`M2Model::owns_animation`].
+    // AnimationLookup (`+0x24`), which the reference's ownership test `0x711960` reads.
     let animation_lookup_arr = arr(p)?;
     p += 8;
-    // PlayableAnimationLookup (decision 0082, header `+0x2c`/`+0x30`, pre-Wrath only — dropped past
-    // version 263, which `parse_m2`'s own top guard already excludes, so this is unconditional on any
-    // version that reaches here; the `if` stays for documentation).
+    // PlayableAnimationLookup (`+0x2c`): pre-Wrath only, as is every version admitted above.
     let playable_animation_lookup_arr = if (256..=263).contains(&version) {
         let v = arr(p)?;
         p += 8;
@@ -134,23 +106,16 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
     p += 8;
     let texture_lookup_table = arr(p)?;
     p += 8;
-    // header 0x9c: texture_unit_lookup — the **env-vs-UV mapping table**. `texUnit.texture_coord_combo_index`
-    // (+0x12) indexes it; a value `< 3` names a UV channel, `>= 3` (real art: `0xffff`) is a
-    // *generated* environment coordinate (wow-re `m2-texanim-uv` §`0x70b8bd`, models.md §944).
-    //
-    // The three lookup slots here follow wow-re's *stride-pin reconciliation* (renderFlags pinned
-    // at 0x84 ⇒ texLookup 0x94 · texUnitLookup 0x9c · transLookup 0xa4 · texAnimLookup 0xac), NOT
-    // the stale one-slot-early labels in models.md's field-map line. Byte-proof on real art:
-    // ElwynnTallWaterfall01 (2 transforms, batch combos 0/1) has [0,1] at 0xac, and
-    // StormwindMagePortal01 (4 weight tracks) has the identity [0,1,2,3] at 0xa4 with [0] at 0x9c
-    // — reading 0x9c as the transparency lookup silently dropped the portal's combo-1..3 tracks.
+    // header 0x9c: texture_unit_lookup, a stage's UV channel or environment coordinate. These
+    // three lookups sit where the reference's header walk `0x71cdf0` puts them, not a slot
+    // earlier: StormwindMagePortal01 has [0] at 0x9c and its weight lookup [0,1,2,3] at 0xa4.
     let texture_unit_lookup_arr = arr(p)?;
     p += 8;
-    // header 0xa4: transparency_lookup (u16) — `weight_combo_index` indexes it to reach a weight track.
+    // header 0xa4: transparency_lookup (u16), `weight_combo_index` to a weight track.
     let transparency_lookup_arr = arr(p)?;
     p += 8;
-    // header 0xac: texture_animation_lookup (u16) — `texture_transform_combo_index` (texUnit
-    // +0x16) indexes it to reach a texture transform (wow-re rf72 `0x70b897`); 0xffff = none.
+    // header 0xac: texture_animation_lookup (u16), `texture_transform_combo_index` to a texture
+    // transform (`0x70b897`); 0xffff is none.
     let tex_anim_lookup_arr = arr(p)?;
     p += 8;
     // Authored bounds: AABB (min C3, max C3) then sphere radius.
@@ -167,7 +132,7 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
     p += 12;
     let bounding_sphere_radius = b.f32_at(p).ok_or(Error::Truncated)?;
     p += 4;
-    // The collision box (min C3 + max C3) + collision sphere radius — the tight collision hull (28 bytes).
+    // The collision box and sphere radius: the tight hull.
     let collision_box_min = read_box(p)?;
     p += 12;
     let collision_box_max = read_box(p)?;
@@ -178,18 +143,15 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
     p += 8;
     let bounding_vertices = arr(p)?;
     p += 8;
-    // Continue the header to the attachments block: boundingNormals, then attachments + attachLookup.
     let _bounding_normals = arr(p)?;
     p += 8;
     let attachments = arr(p)?;
     p += 8;
     let attach_lookup = arr(p)?;
     p += 8;
-    // header 0x114: the animation-event table (the `$CSL`/`$BWR`/`$SND`… records) — the positional
-    // markers are kept below; the per-sequence fire keys are `benilla-formats`' concern.
+    // header 0x114: the animation events (`$CSL`, `$BWR`, `$SND`…); only their positions are read.
     let events = arr(p)?;
-    // The follow-camera pivot height source (wow-re `follow-camera`, `0x50cbc0`): attachment **id 17**'s
-    // model-space Z. `None` if the model has no slot-17 attachment (caller falls back to the vertex box).
+    // The follow camera's pivot height (`0x50cbc0`): attachment id 17's model-space Z.
     let pivot_attach_z = attachment_z(b, 17, attachments, attach_lookup);
 
     // --- read the arrays we keep ---
@@ -197,11 +159,7 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         b.bytes_at(start, len).ok_or(Error::Truncated)
     };
 
-    // Vertices: 48 bytes each. The reservation is capped by what the file could actually hold
-    // (decision 0064, `benilla_bytes::capped`): a corrupt/hostile `vertices.0` count can then at
-    // worst reserve the input's own size, never OOM-abort the process before the loop reaches its
-    // first bounds-checked read. The loop below still walks the *real* declared count — a short
-    // file fails cleanly at `get(..)?` instead.
+    // Vertices: 48 bytes each. The reservation is capped by the file; a short file fails at `get`.
     let vert_avail = b.len().saturating_sub(vertices.1 as usize);
     let mut verts = Vec::with_capacity(capped(vertices.0 as usize, 48, vert_avail));
     for i in 0..vertices.0 as usize {
@@ -224,13 +182,8 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
     for i in 0..textures.0 as usize {
         let t = get(textures.1 as usize + i * 16, 16)?;
         let ttype = M2TextureType::from_u32(t.u32_at(0).ok_or(Error::Truncated)?);
-        // `+0x04` — the ADDRESS MODE, and it decides silhouettes, not just tiling. Bit 0 = repeat U,
-        // bit 1 = repeat V; clear = clamp to edge. Content authors a cutout card's UVs *outside*
-        // `0..1` deliberately, so the border clamps to the texture's transparent edge and the card
-        // fades out to nothing — sampled with repeat instead, those margins wrap around into the
-        // opaque middle of the sheet and draw as solid geometry, with a hard seam where u crosses
-        // the wrap. This field was documented in this very comment and read by nobody until B52
-        // (the Dun Morogh snow-firs) was traced to it; decision 0763.
+        // `+0x04`, the address mode: bit 0 repeats U, bit 1 V, clear clamps to edge. Cutout cards
+        // put UVs outside `0..1` to clamp to their transparent edge; repeated, they draw solid.
         let tflags = t.u32_at(4).ok_or(Error::Truncated)?;
         let (fcount, fofs) = (
             t.u32_at(8).ok_or(Error::Truncated)? as usize,
@@ -258,9 +211,8 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         });
     }
 
-    // Bones: 108 bytes each in v256 — header 12 (id i32, flags u32, parent i16, submesh u16; vanilla
-    // has NO boneNameCRC field, unlike TBC+), then 3×28 pre-Wrath tracks, then pivot C3. flags @4,
-    // pivot @96. The reference zeroes NaN pivot components (a corruption guard); mirror it.
+    // Bones: 108 bytes in v256: key bone i32, flags u32, parent i16, submesh u16 (no boneNameCRC in
+    // vanilla), three 28-byte tracks, pivot C3 @96. The reference zeroes a NaN pivot component.
     let bones_avail = b.len().saturating_sub(bones.1 as usize);
     let mut bone_list = Vec::with_capacity(capped(bones.0 as usize, 108, bones_avail));
     for i in 0..bones.0 as usize {
@@ -283,16 +235,17 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         });
     }
 
-    // Attachments: 48 bytes each (id u32 @0, bone u32 @4, position C3 @8; a 28-byte visibility
-    // M2Track follows and is skipped — see [`M2Attachment`]). `id`/`bone` are narrowed to `u16`; a
-    // record whose id/bone doesn't fit, or whose bone indexes past `bone_list` (now fully parsed
-    // above), is dropped rather than kept malformed — real attachment ids run ≤ 36, so this never
-    // drops legitimate data.
+    // Attachments: 48 bytes (id, bone, position C3 @8, a skipped track). A record whose id or bone
+    // overflows `u16`, or whose bone is out of range, is dropped; real ids stop at 36.
+    let att_count = attachments.0 as usize;
     let att_avail = b.len().saturating_sub(attachments.1 as usize);
-    let mut attachment_list = Vec::with_capacity(capped(attachments.0 as usize, 48, att_avail));
-    // A dropped record shifts the emitted indices, and the AttachLookup below indexes the FILE's
-    // records — so the translation is carried here rather than reconstructed later.
-    let mut emitted_at = vec![0xffffu16; attachments.0 as usize];
+    // The table must fit the file first: `emitted_at` below is sized from the raw count.
+    if capped(att_count, 48, att_avail) < att_count {
+        return Err(Error::Truncated);
+    }
+    let mut attachment_list = Vec::with_capacity(att_count);
+    // AttachLookup indexes the file's records; a dropped one shifts ours, so map file to emitted.
+    let mut emitted_at = vec![0xffffu16; att_count]; // proven to fit above
     for (i, emitted) in emitted_at.iter_mut().enumerate() {
         let a = get(attachments.1 as usize + i * 48, 48)?;
         let id = a.u32_at(0).ok_or(Error::Truncated)?;
@@ -312,12 +265,9 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         });
     }
 
-    // AttachLookup (header `+0x10c`): attachment **id** → the one record it resolves to. This is
-    // the reference's only id→record map (`0x710310`: `id >= count` ⇒ the `0xffff` sentinel, else
-    // `lookup[id]`) and it is emphatically NOT a scan of the table — shipped weapons author
-    // several records under one id (`Stave_2H_Long_D_05`: eight records, ids 0-3 twice, one at
-    // each end of the staff) and the lookup names exactly one, leaving the other unreachable.
-    // Stored translated into emitted-list indices, `0xffff` where the id resolves to nothing.
+    // AttachLookup (`+0x10c`): attachment id to its one record, the reference's only id map
+    // (`0x710310`). Shipped weapons repeat ids (`Stave_2H_Long_D_05`: 0-3 twice) and the lookup
+    // names one. Stored as emitted indices, `0xffff` for none.
     let lk_avail = b.len().saturating_sub(attach_lookup.1 as usize);
     let mut attach_lookup_list = Vec::with_capacity(capped(attach_lookup.0 as usize, 2, lk_avail));
     for i in 0..attach_lookup.0 as usize {
@@ -327,9 +277,8 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         attach_lookup_list.push(emitted_at.get(raw as usize).copied().unwrap_or(0xffff));
     }
 
-    // Event markers: 44 bytes each (identifier 4CC @0, data u32 @4, bone u32 @8, position C3 @12;
-    // a 20-byte enabled M2TrackBase follows and is skipped). Same bone-range discipline as the
-    // attachments above; kept in file order (queries take the first ident match).
+    // Event markers: 44 bytes (4CC, data u32, bone u32 @8, position C3 @12, a skipped 20-byte
+    // track), dropped like attachments, kept in file order.
     let ev_avail = b.len().saturating_sub(events.1 as usize);
     let mut event_markers = Vec::with_capacity(capped(events.0 as usize, 44, ev_avail));
     for i in 0..events.0 as usize {
@@ -350,7 +299,7 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         });
     }
 
-    // AnimationLookup: one u16 each — the id → sequence-slot table `owns_animation` reads.
+    // AnimationLookup: one u16 each.
     let al_avail = b.len().saturating_sub(animation_lookup_arr.1 as usize);
     let mut animation_lookup =
         Vec::with_capacity(capped(animation_lookup_arr.0 as usize, 2, al_avail));
@@ -362,7 +311,7 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         );
     }
 
-    // PlayableAnimationLookup (decision 0082): one dword each, low16 resolved id / high16 dir flags.
+    // PlayableAnimationLookup: one dword each, low16 resolved id / high16 dir flags.
     let pal_avail = b
         .len()
         .saturating_sub(playable_animation_lookup_arr.1 as usize);
@@ -392,25 +341,21 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         );
     }
 
-    // Each M2Color (stride 0x38) is an RGB **colour** track @ +0x00 (C3Vector keys) + an **alpha**
-    // track @ +0x1c (fix16); each M2TextureWeight (stride 0x1c) is a single **weight** track. The
-    // alpha/weight values gate batch visibility (a constant 0 hides the batch — wow-re
-    // `m2-alpha-combine-cull`); the RGB is the per-batch tint multiplied into the vertex colour.
-    // `track_fix16`/`track_vec3_timed` bounds-check internally and return an empty key list for
-    // an out-of-range track (kept exactly — real art relies on that "no keys" tolerance); the
-    // reservation for the *outer* per-record `Vec` is capped the same way as the arrays above.
+    // M2Color (stride 0x38): an RGB track @ +0x00 and a fix16 alpha track @ +0x1c. M2TextureWeight
+    // (stride 0x1c): one weight track. An out-of-range track reads as no keys, so these loops run
+    // over the records the file holds, never the raw count.
     let colors_avail = b.len().saturating_sub(colors_arr.1 as usize);
     let colors_cap = capped(colors_arr.0 as usize, 0x38, colors_avail);
     let mut color_alpha_tracks = Vec::with_capacity(colors_cap);
     let mut color_rgb_tracks = Vec::with_capacity(colors_cap);
-    for i in 0..colors_arr.0 as usize {
+    for i in 0..colors_cap {
         color_alpha_tracks.push(track_fix16(b, colors_arr.1 as usize + i * 0x38 + 0x1c));
         color_rgb_tracks.push(track_vec3_timed(b, colors_arr.1 as usize + i * 0x38));
     }
     let transparency_avail = b.len().saturating_sub(transparency_arr.1 as usize);
     let transparency_cap = capped(transparency_arr.0 as usize, 0x1c, transparency_avail);
     let mut transparency_tracks = Vec::with_capacity(transparency_cap);
-    for i in 0..transparency_arr.0 as usize {
+    for i in 0..transparency_cap {
         transparency_tracks.push(track_fix16(b, transparency_arr.1 as usize + i * 0x1c));
     }
     let tulookup_avail = b.len().saturating_sub(texture_unit_lookup_arr.1 as usize);
@@ -437,13 +382,12 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         );
     }
 
-    // Each M2TextureTransform (header 0x74, stride 0x54) is 3 back-to-back M2Tracks — translation
-    // (C3Vector) @+0x00, rotation (quaternion) @+0x1c, scaling (C3Vector) @+0x38 (wow-re models.md
-    // element table). Same "no keys" tolerance as the colour/weight tracks above.
+    // M2TextureTransform (stride 0x54): translation @+0x00, rotation @+0x1c, scaling @+0x38
+    // (`0x70ebd0`), bounded by the file like the colour tracks.
     let ttf_avail = b.len().saturating_sub(tex_anim_arr.1 as usize);
-    let mut texture_transforms =
-        Vec::with_capacity(capped(tex_anim_arr.0 as usize, 0x54, ttf_avail));
-    for i in 0..tex_anim_arr.0 as usize {
+    let ttf_cap = capped(tex_anim_arr.0 as usize, 0x54, ttf_avail);
+    let mut texture_transforms = Vec::with_capacity(ttf_cap);
+    for i in 0..ttf_cap {
         let base = tex_anim_arr.1 as usize + i * 0x54;
         texture_transforms.push(M2TextureTransform {
             translation: track_vec3_timed(b, base),
@@ -462,9 +406,7 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         );
     }
 
-    // Global-sequence durations (header `0x14` count / `0x18` offset, u32 ms each): the free-running
-    // loop clocks a `gseq`-tagged track wraps on (`t mod global_sequences[gseq]`). Bounds-tolerant
-    // like the tracks: a truncated table yields what fits.
+    // Global-sequence durations (`0x14`, u32 ms): the clocks `gseq` tracks wrap on.
     let gseq_arr = (
         b.u32_at(0x14).ok_or(Error::Truncated)?,
         b.u32_at(0x18).ok_or(Error::Truncated)?,
@@ -478,9 +420,7 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
         global_sequences.push(ms);
     }
 
-    // Collision hull: raw bytes (triangles = count×2 u16, vertices = count×12 C3Vector). Many props
-    // carry none (count 0) → empty. `get(..)` is already bounds-checked before the `to_vec()`, so a
-    // corrupt count fails at the checked slice, never at an unbounded allocation.
+    // The collision hull, raw: triangle indices (u16) and vertices (C3Vector).
     let bt_bytes = get(
         bounding_triangles.1 as usize,
         bounding_triangles.0 as usize * 2,
@@ -533,17 +473,8 @@ pub fn parse_m2(cursor: &mut Cursor<&[u8]>) -> Result<M2Format> {
     })
 }
 
-/// Parse the MD20 **camera** array — header `count@0x124` / `offset@0x128`, stride `0x7c` (see
-/// [`M2Camera`] for the byte-verified field map).
-///
-/// **The one reader for those offsets.** [`parse_m2`] fills [`M2Model::cameras`] with it, and
-/// callers that want a camera *without* paying for a whole model parse (the portrait/pane framing
-/// on the asset-load path, the cinematic fly-bys) call it directly — so the record layout is
-/// written down once. The header offsets are absolute rather than walked because every version
-/// [`parse_m2`] accepts (256–263) carries the identical array order up to this point.
-///
-/// Bounds-tolerant throughout: a truncated table yields the records that fit, and a model with no
-/// camera array yields an empty `Vec` (the overwhelmingly common case).
+/// Parse the MD20 camera array (header `0x124`, stride `0x7c`) alone; the offset is absolute, as
+/// versions 256–263 agree up to it. A truncated table yields the records that fit.
 pub fn parse_cameras(b: &[u8]) -> Vec<M2Camera> {
     let (Some(count), Some(ofs)) = (b.u32_at(0x124), b.u32_at(0x128)) else {
         return Vec::new();
@@ -552,8 +483,7 @@ pub fn parse_cameras(b: &[u8]) -> Vec<M2Camera> {
     let mut out = Vec::with_capacity(capped(count as usize, 0x7c, avail));
     for i in 0..count as usize {
         let rec = ofs as usize + i * 0x7c;
-        // A record is read whole or not at all — a file whose camera array is cut short yields the
-        // records that fit, never a half-read one with default tracks standing in for the tail.
+        // A record is read whole or not at all.
         if rec.checked_add(0x7c).is_none_or(|end| end > b.len()) {
             break;
         }
@@ -565,8 +495,6 @@ pub fn parse_cameras(b: &[u8]) -> Vec<M2Camera> {
         ) else {
             break;
         };
-        // The bases are plain `[f32; 3]` (not `C3`) so they add to their track's sampled value
-        // componentwise, the way the reference's publish pass composes them.
         let (Some(position_base), Some(target_base)) = (
             rd_c3(b, rec + 0x2c).map(|c| [c.x, c.y, c.z]),
             rd_c3(b, rec + 0x54).map(|c| [c.x, c.y, c.z]),
@@ -588,8 +516,7 @@ pub fn parse_cameras(b: &[u8]) -> Vec<M2Camera> {
     out
 }
 
-/// Parse the MD20 **CameraLookup** table — header `count@0x12c` / `offset@0x130`, `u16` entries.
-/// See [`M2Model::camera_lookup`] for what it selects.
+/// Parse the MD20 CameraLookup (header `0x12c`, `u16` each); see [`M2Model::camera_lookup`].
 pub fn parse_camera_lookup(b: &[u8]) -> Vec<u16> {
     let (Some(count), Some(ofs)) = (b.u32_at(0x12c), b.u32_at(0x130)) else {
         return Vec::new();
@@ -605,11 +532,7 @@ pub fn parse_camera_lookup(b: &[u8]) -> Vec<u16> {
     out
 }
 
-/// The model-space **Z** of an M2 attachment selected by **attachment id** (not array index) — the
-/// follow-camera pivot reads id 17 this way. `attachments`/`lookup` are the header `(count, offset)`
-/// pairs; the id → array-index map (`lookup`, `u16` each) picks the record, whose `position` C3 sits at
-/// `+8` (vanilla stride 48: `id u32 · bone u32 · position C3 · animate M2Track`). `None` when the id has
-/// no lookup slot or the record/bytes are out of range.
+/// Attachment `id`'s model-space Z through the lookup, from the file's `(count, offset)` pairs.
 fn attachment_z(b: &[u8], id: usize, attachments: (u32, u32), lookup: (u32, u32)) -> Option<f32> {
     if id >= lookup.0 as usize {
         return None;
@@ -620,7 +543,7 @@ fn attachment_z(b: &[u8], id: usize, attachments: (u32, u32), lookup: (u32, u32)
         return None;
     }
     let rec = attachments.1 as usize + idx * 48;
-    // position C3 at rec+8 → its Z is rec+16.
+    // `position` is at +8 of the 48-byte record, so its Z is at +16.
     b.f32_at(rec + 16)
 }
 
diff --git a/crates/benilla-m2/src/model.rs b/crates/benilla-m2/src/model.rs
index 08036101..6bc8a864 100644
--- a/crates/benilla-m2/src/model.rs
+++ b/crates/benilla-m2/src/model.rs
@@ -1,6 +1,4 @@
-//! The plain M2 data types: the parsed record shapes (vertices, textures, materials, bones,
-//! attachments, the authored bounds) and the top-level [`M2Model`]/[`M2Format`] the parser
-//! (`crate::parse_m2`, in `lib.rs`) builds.
+//! The parsed M2 record types and the [`M2Model`] that `crate::parse_m2` builds.
 
 use std::ffi::CString;
 
@@ -22,8 +20,7 @@ pub struct C2 {
     pub y: f32,
 }
 
-/// M2 texture purpose. Vanilla uses `Hardcoded` (the `filename` is the real path) or the `Monster*`
-/// skin slots (filename usually empty; the slot is filled from the creature's display variation).
+/// M2 texture type: `Hardcoded` names its file; `Monster*` slots take the creature display's skins.
 #[derive(Clone, Copy, PartialEq, Eq)]
 pub enum M2TextureType {
     Hardcoded,
@@ -45,8 +42,7 @@ impl M2TextureType {
     }
 }
 
-/// The texture's filename, kept as a `CString` so callers can `.string.to_string_lossy()` (matching
-/// the reference's shape).
+/// A texture's filename.
 pub struct M2ArrayString {
     pub string: CString,
 }
@@ -54,7 +50,7 @@ pub struct M2ArrayString {
 /// One M2 texture definition.
 pub struct M2Texture {
     pub texture_type: M2TextureType,
-    /// Address mode on U (`flags & 0x1`): set = the sampler REPEATS, clear = it CLAMPS to edge.
+    /// Address mode on U (`flags & 0x1`): set repeats, clear clamps to edge.
     pub wrap_x: bool,
     /// Address mode on V (`flags & 0x2`).
     pub wrap_y: bool,
@@ -93,17 +89,12 @@ impl M2BoneFlags {
     }
 }
 
-/// One M2 bone. The render path reads billboard flags + pivot; the skeletal-animation path also needs
-/// the **parent index** (`-1` = root) to compose bone matrices up the tree and to build the joint
-/// hierarchy + inverse bind poses (decision 0019). Vanilla bone record is stride 108: keyBoneId i32
-/// @+0x00, flags @+0x04, parent i16 @+0x08, pivot C3 @+0x60 (no boneNameCRC, unlike TBC+).
+/// One M2 bone: keyBoneId i32 @+0x00, flags @+0x04, parent i16 @+0x08, pivot C3 @+0x60.
 pub struct M2Bone {
-    /// The bone's `KeyBoneID` (`-1` = none): the semantic anchor table — 0/1 arms L/R, 2/3
-    /// shoulders L/R, 4 spine-low, 5 waist, 6 head… The per-arm animation masks resolve their
-    /// subtree roots through it.
+    /// `KeyBoneID`, `-1` for none: 0/1 arms L/R, 2/3 shoulders L/R, 4 spine low, 5 waist, 6 head…
     pub key_bone: i16,
     pub flags: M2BoneFlags,
-    /// Parent bone index, or `-1` for a root bone (vanilla bone record `+0x08`).
+    /// Parent bone index, `-1` for a root.
     pub parent: i16,
     pub pivot: C3,
 }
@@ -114,10 +105,8 @@ impl M2Bone {
     }
 }
 
-/// One M2 vertex (48 bytes on disk). Layout: position C3 @0, bone_weights [u8;4] @0x0c,
-/// bone_indices [u8;4] @0x10, normal C3 @0x14, tex_coords C2 @0x20 (a second UV @0x28 we skip). The
-/// weights + indices are the 4-bone skin binding the skeletal-animation path uploads (decision 0019);
-/// the static render path uses only `bone_indices[0]` (billboard glow-card pivot).
+/// One M2 vertex, 48 bytes: position @0, weights @0x0c, indices @0x10, normal @0x14, UV @0x20,
+/// and an unread second UV @0x28.
 pub struct M2Vertex {
     pub position: C3,
     /// Per-vertex bone influence weights (`/255`), paired with [`Self::bone_indices`].
@@ -127,10 +116,7 @@ pub struct M2Vertex {
     pub tex_coords: C2,
 }
 
-/// Lookup tables + collision geometry read from the header. The renderer uses the texture-combo →
-/// texture mapping; benilla-formats reads the collision hull from the two `bounding_*` byte blocks
-/// (the MD20 `boundingVertices` are `C3Vector`s = 12 bytes; `boundingTriangles` are `u16` = 2 bytes —
-/// kept as raw bytes so callers slice them as they need).
+/// The texture lookup table and the collision hull's raw bytes.
 pub struct M2RawData {
     pub texture_lookup_table: Vec<u16>,
     /// Collision-hull triangle indices, raw bytes (`count × 2`, `u16` each).
@@ -139,12 +125,8 @@ pub struct M2RawData {
     pub bounding_vertices: Vec<u8>,
 }
 
-/// The authored bounds from the MD20 header. Two boxes: the **bounding** box (+ sphere radius) is the
-/// render/cull volume (the all-animation vertex extent — large); the **collision** box (+ sphere radius)
-/// is the tight collision hull (~the body). The **render sphere** sizes the *unit* selection ring
-/// (`0.5 × radius × scale`, the client's cached `[unit+0x2b0]`, wow-re selection-circle RE) and drives
-/// render culling; the **collision box** is the *GameObject* ring's source (wow-re `0x711a20`/`0x713700`)
-/// — parsed here for that path.
+/// The MD20 header's authored bounds: the bounding box and sphere are the render and cull volume
+/// over every animation, the collision box and sphere the tight hull.
 pub struct M2Header {
     pub bounding_box_min: [f32; 3],
     pub bounding_box_max: [f32; 3],
@@ -154,105 +136,68 @@ pub struct M2Header {
     pub collision_sphere_radius: f32,
 }
 
-/// One row of the M2's baked **PlayableAnimationLookup** table (decision 0082, wow-re
-/// `anim-id-resolution.md`, byte-verified `0x711bf0`): the model's own precomputed answer to "if the
-/// game requests `AnimationData.dbc` id X, which id do I actually play, and in which
-/// direction/variant". Header `count@+0x2c`/`offset@+0x30` (pre-Wrath M2 only — the array is dropped
-/// past version 263), stride 4 (one dword per row): low16 = the resolved id, high16 = a
-/// direction/variant playback code. `nPlayableAnimationLookup` is a fixed **203** across the entire
-/// retail 1.12.1 corpus (VERIFIED, wow-re empirical cross-check) — the per-model table is a baked
-/// cache of the `AnimationData.dbc` Fallback-column walk (PATH 2, below), frozen against that model's
-/// actual sequence set at export (a chicken lacking Attack2H bakes `[18] = [17] = 16`).
+/// A PlayableAnimationLookup row (`0x711bf0`, header `+0x2c`): the id this model plays for a
+/// requested `AnimationData.dbc` id, and a direction code. Every 1.12.1 model has 203 rows.
 #[derive(Clone, Copy)]
 pub struct M2PlayableAnim {
-    /// The `AnimationData.dbc` id this model actually plays for the row's requested id.
+    /// The `AnimationData.dbc` id this model plays for the row's requested id.
     pub resolved_id: u16,
-    /// Direction/variant playback code — **not yet consumed** by benilla (decision 0082 flags its
-    /// exact playback semantics, wow-re `~0x7126d2`, as untraced; carried here for a future slice).
+    /// The direction or variant playback code (near `0x7126d2`); parsed, not applied: the
+    /// reference's use of it is untraced.
     pub dir_flags: u16,
 }
 
-/// One M2 attachment-point record (vanilla stride 48: `id u32 @+0`, `bone u32 @+4`, `position C3 @+8`,
-/// then a 28-byte visibility `M2Track` we skip). `id`/`bone` are narrowed to `u16` — safe on real data
-/// (attachment ids run ≤ 36; `bone` is checked against the bone array during parse) — and any record
-/// that doesn't fit, or whose bone is out of the model's bone-array range, is dropped rather than kept
-/// malformed.
-///
-/// Empirical ground truth (direct dump of `HumanMale.m2`, `decisions/0072`): on character models the
-/// attachment `position` equals its bone's pivot — the attach bones are leaves sitting exactly at the
-/// attach point, so `position` and the bone pivot agree. Known ids: `0` shield (left forearm), `1`
-/// right hand, `2` left hand, `26`/`27` right/left back sheath, `28` shield back, `30`/`31` lower-back
-/// pair, `32`/`33` hip pair.
+/// One attachment point: a 48-byte vanilla record, `id` and `bone` narrowed to `u16`. On character
+/// models `position` equals the attach bone's pivot. Ids: 0 shield (left forearm), 1 right hand,
+/// 2 left hand, 26/27 right/left back sheath, 28 shield back, 30/31 lower back, 32/33 hips.
 #[derive(Clone, Copy)]
 pub struct M2Attachment {
     pub id: u16,
     pub bone: u16,
-    /// Model-space position, **raw WoW space** — matches how [`M2Bone::pivot`] is stored; the WoW→Bevy
-    /// bake happens at the render boundary (`benilla-assets`).
+    /// Model-space position, raw WoW axes like [`M2Bone::pivot`].
     pub position: [f32; 3],
 }
 
-/// One M2 **animation-event marker** (vanilla stride 44: `identifier 4CC @+0`, `data u32 @+4`,
-/// `bone u32 @+8`, `position C3 @+12`, then a 20-byte enabled `M2TrackBase` we skip — its
-/// per-sequence fire keys surface through `benilla-formats`' per-sequence event stream instead).
-/// This is the record's **positional half**: the client's `0x7130e0`/`0x7131b0` scan exactly this
-/// table by 4CC and transform `position` by `bone`'s live matrix — the cast-release launch points
-/// `$CSL`/`$CSR`/`$CST` (casting hand left/right/two-hand), the bow anchors `$WTT`/`$WTB`, the
-/// ranged release `$BWR`. Idents are NOT unique per model (character models carry six `$CSD`
-/// records, one per voice payload); the client's queries take the first match. A record whose
-/// `bone` doesn't fit `u16` or indexes past the bone array is dropped rather than kept malformed.
+/// The positional half of an animation-event record: the reference (`0x7130e0`, `0x7131b0`) finds
+/// one by 4CC, first match, and moves `position` by `bone`'s matrix. Cast launch points
+/// `$CSL`/`$CSR`/`$CST`, bow anchors `$WTT`/`$WTB`, ranged release `$BWR`.
 #[derive(Clone, Copy)]
 pub struct M2EventMarker {
     /// The identifier 4CC, stored forward (`*b"$CSL"`).
     pub ident: [u8; 4],
     pub bone: u16,
-    /// Model-space position, **raw WoW space** — same convention as [`M2Attachment::position`].
+    /// Model-space position, raw WoW axes.
     pub position: [f32; 3],
 }
 
-/// One M2 **texture transform** (header `0x74`, file stride `0x54`): 3 back-to-back M2Tracks —
-/// `translation` (C3Vector) @`+0x00`, `rotation` (quaternion) @`+0x1c`, `scaling` (C3Vector)
-/// @`+0x38` (wow-re `models.md` element table, runtime `[model+0x98]`). Sampled per frame these
-/// drive UV animation — flowing waterfalls, scrolling energy fields. How the sampled TRS is
-/// *applied* at draw (texture matrix vs CPU UVs, pivot/composition convention) is under RE in
-/// wow-re; parsed and carried here, not yet consumed.
+/// One M2 texture transform (header `0x74`, stride `0x54`, loaded at `0x70ebd0`), its UV-animation
+/// tracks at `+0x00`, `+0x1c`, `+0x38`; this crate only carries the parsed tracks.
 pub struct M2TextureTransform {
     pub translation: M2Vec3Track,
     pub rotation: M2QuatTrack,
     pub scaling: M2Vec3Track,
 }
 
-/// One M2 **camera** record (header `cameras` @`0x124`, file stride `0x7c`) — the authored
-/// eye/target path a `Cameras\*.m2` cinematic fly-by *is*, and the same record the portrait bake
-/// and the `<Model>` panes frame themselves with.
-///
-/// Field map VERIFIED at the reference's M2 load `0x70ebd0` + the publish pass `0x718960` (wow-re
-/// `ui.md` §"The `Model` / `PlayerModel` pane camera", `models.md` §182):
-/// `type@+0x00 · fov@+0x04 · farClip@+0x08 · nearClip@+0x0c · positions@+0x10 ·
-/// position_base@+0x2c · target@+0x38 · target_position_base@+0x54 · roll@+0x60`. The load copies
-/// only fov/far/near into the runtime `CCamera`; the tracks are evaluated by the animate kernel and
-/// **published against the bases** — `eye = position_base + positions(t)`,
-/// `target = target_position_base + target(t)`, `roll = roll(t)` — so a keyless track leaves the
-/// base as the value. Character and creature models author a single `(0,0,0)` key on all three
-/// (their pane camera is a frozen constant); the fly-bys are the case the tracks exist for.
+/// One M2 camera record (header `0x124`, stride `0x7c`, loaded at `0x70ebd0`): a `Cameras\*.m2`
+/// fly-by's path, and the framing of the portrait bake and `<Model>` panes. The publish pass
+/// `0x718960` adds each track to its base (`eye = position_base + positions(t)`), so a keyless
+/// track leaves the base.
 #[derive(Clone)]
 pub struct M2Camera {
-    /// The record's `type` word. `0` = portrait, `1` = "characterinfo" (the `<PlayerModel>` pane's
-    /// raw index 1); every shipped `Cameras\*.m2` fly-by authors `-1`.
+    /// The `type` word (`+0x00`): 0 portrait, 1 the `<PlayerModel>` pane, `-1` on every fly-by.
     pub camera_type: i32,
-    /// **Diagonal** field of view, radians — the reference's `camera_view_lookat` `0x7ac640` takes
-    /// the half-angle as `θ = (fov/2)/√(aspect²+1)`, *not* `fov/2` (wow-re
-    /// `ui/scratch/portrait-projection-aspect.md`). All ten fly-bys author `0.7854` (45°).
+    /// Diagonal field of view, radians (`+0x04`): `0x7ac640` takes the half-angle as
+    /// `(fov/2)/√(aspect²+1)`, not `fov/2`.
     pub fov: f32,
-    /// Far clip as authored (`+0x08`). Every fly-by carries `27.777779` (= 1000/36).
+    /// Far clip (`+0x08`); every fly-by carries `27.777779` (1000/36).
     pub far_clip: f32,
-    /// Near clip as authored (`+0x0c`). Every fly-by carries `0.22222222` (= 8/36).
+    /// Near clip (`+0x0c`); every fly-by carries `0.22222222` (8/36).
     pub near_clip: f32,
-    /// The eye path, relative to [`Self::position_base`].
+    /// The eye path (`+0x10`), relative to [`Self::position_base`].
     pub positions: M2Vec3SplineTrack,
     /// The eye's base position, model space (`+0x2c`).
     pub position_base: [f32; 3],
-    /// The look-at path, relative to [`Self::target_base`].
+    /// The look-at path (`+0x38`), relative to [`Self::target_base`].
     pub target: M2Vec3SplineTrack,
     /// The look-at base position, model space (`+0x54`).
     pub target_base: [f32; 3],
@@ -260,143 +205,80 @@ pub struct M2Camera {
     pub roll: M2ScalarSplineTrack,
 }
 
-/// The parsed model (render subset).
+/// The parsed model.
 pub struct M2Model {
     pub vertices: Vec<M2Vertex>,
     pub textures: Vec<M2Texture>,
     pub materials: Vec<M2Material>,
-    /// Per-`M2Color` **alpha** track (full [`M2ScalarTrack`]: interp + gseq tag + timed keys), one
-    /// per color record (header `0x54`). A `texUnit.colorIndex` (direct) selects one; no keys ⇒ the
-    /// factor doesn't apply. The alpha governs batch visibility (a constant 0 hides the batch) and,
-    /// time-varying, the animated material combine (wow-re `m2-alpha-combine-cull`).
+    /// Each `M2Color`'s alpha track (header `0x54`), picked directly by a batch's `colorIndex`; no
+    /// keys means no factor. It gates visibility and feeds the material combine (`0x707680`).
     pub color_alpha_tracks: Vec<M2ScalarTrack>,
-    /// Per-`M2Color` **RGB colour** track (full [`M2Vec3Track`]: interp + gseq tag + timed
-    /// `C3Vector` keys, the colour record's `+0x00` track), one per record. Selected by the same
-    /// `texUnit.colorIndex`. This is the per-batch tint the real client multiplies into the vertex
-    /// colour — load-bearing for additive glow cards drawn with a *neutral* glow texture (e.g.
-    /// `GenericGlow_Alpha_128`), whose warmth lives entirely here; dropping it renders the glow
-    /// grey/white. Time-varying tracks (e.g. a spell effect's white-hot flash cooling to red) carry
-    /// their timestamps so the render side can animate the tint. No keys ⇒ no tint.
+    /// Each `M2Color`'s RGB track: the batch tint multiplied into the vertex colour, none without
+    /// keys. Neutral glow cards (`GenericGlow_Alpha_128`) take all their colour from it.
     pub color_rgb_tracks: Vec<M2Vec3Track>,
-    /// Per-`M2TextureWeight` **weight** track (full [`M2ScalarTrack`]), one per record (header
-    /// `0x64`). Selected via `texUnit.weight_combo_index → transparency_lookup → here` (two-hop).
+    /// Each `M2TextureWeight`'s weight track (header `0x64`), via [`Self::transparency_lookup`].
     pub transparency_tracks: Vec<M2ScalarTrack>,
-    /// The transparency lookup table (header `0xa4`, u16): `weight_combo_index` indexes this to reach
-    /// [`Self::transparency_tracks`] (verified two-hop, wow-re `m2-alpha-combine-cull`).
+    /// The transparency lookup (header `0xa4`, u16): `weight_combo_index` to
+    /// [`Self::transparency_tracks`] (`0x707b19`–`0x707b26`).
     pub transparency_lookup: Vec<u16>,
-    /// The **texture-unit lookup** table (header `0x9c`, u16): `texture_coord_combo_index` (texUnit
-    /// `+0x12`) indexes this to decide where a stage's texture coordinates come from. A value
-    /// `< 3` names one of the vertex UV channels; **`>= 3` (real art: `0xffff`) is a *generated*
-    /// environment coordinate** — the model authors no usable UVs for that stage and the runtime
-    /// derives them from the view-space reflection vector. See
-    /// [`M2Model::stage_is_env_mapped`].
+    /// The texture-unit lookup (header `0x9c`), by `texture_coord_combo_index`: a UV channel or a
+    /// generated environment coordinate (see [`Self::stage_is_env_mapped`]).
     pub texture_unit_lookup: Vec<u16>,
-    /// The texture-transform records (see [`M2TextureTransform`]), selected via
-    /// `texture_transform_combo_index → texture_transform_lookup → here`.
+    /// The texture transforms, reached through [`Self::texture_transform_lookup`].
     pub texture_transforms: Vec<M2TextureTransform>,
-    /// The texture-animation lookup table (header `0xac`, u16): `texture_transform_combo_index`
-    /// (texUnit `+0x16`, wow-re rf72 `0x70b897`) indexes this to reach
-    /// [`Self::texture_transforms`]; `0xffff` = no animation.
+    /// The texture-animation lookup (header `0xac`, u16): `texture_transform_combo_index`
+    /// (`0x70b897`) to [`Self::texture_transforms`], `0xffff` for none.
     pub texture_transform_lookup: Vec<u16>,
-    /// Global-sequence durations (header `0x14/0x18`, ms): the free-running loop clocks
-    /// `gseq`-tagged tracks wrap on.
+    /// Global-sequence durations (header `0x14`, ms): the clocks `gseq` tracks wrap on.
     pub global_sequences: Vec<u32>,
     pub bones: Vec<M2Bone>,
-    /// The authored camera records (header `0x124`) — see [`M2Camera`]. Empty for the overwhelming
-    /// majority of models; a `Cameras\*.m2` fly-by carries exactly one.
+    /// The camera records (header `0x124`): one in a `Cameras\*.m2` fly-by, none in most models.
     pub cameras: Vec<M2Camera>,
-    /// The **CameraLookup** table (header `0x12c`, u16): a camera *purpose* index → the slot in
-    /// [`Self::cameras`] that serves it. The portrait bake selects through it (`cameraLookup[0]`,
-    /// `0x525266`); the `<Model>` pane indexes [`Self::cameras`] raw instead (wow-re
-    /// `ui/scratch/modelframe-camera-law.md`). Carried so a selection can be written the way the
-    /// reference writes it rather than assumed 1:1.
+    /// CameraLookup (header `0x12c`): a camera purpose to its [`Self::cameras`] slot. The portrait
+    /// bake reads it (`0x525266`); the `<Model>` pane indexes cameras directly (`0x76cec0`).
     pub camera_lookup: Vec<u16>,
     pub raw_data: M2RawData,
     pub header: M2Header,
-    /// Model-space **Z** of attachment id 17 — the reference's follow-camera pivot height (wow-re
-    /// `follow-camera`, `0x50cbc0`: the camera targets `feet + (attach17.z + 0.0972)·scale`). `None` when
-    /// the model has no slot-17 attachment (a non-character model → the camera falls back to the box).
+    /// Model-space Z of attachment id 17, the follow camera's pivot height (`0x50cbc0` targets
+    /// `feet + (z + 0.0972)·scale`).
     pub pivot_attach_z: Option<f32>,
-    /// The full attachment-point table (see [`M2Attachment`]) — every record whose id/bone fit `u16`
-    /// and whose bone indexes into [`Self::bones`]. `pivot_attach_z` above is the id-17 special case
-    /// kept as its own field (the camera pivot's one historical consumer). **Records are addressed
-    /// by ATTACH ID through [`Self::attachment`], never by scanning this table** (see
-    /// [`Self::attach_lookup`]).
+    /// The surviving attachment records; address them by id via [`Self::attachment`], never scan.
     pub attachments: Vec<M2Attachment>,
-    /// The model's **AttachLookup** (header `+0x10c`), translated into [`Self::attachments`]
-    /// indices: row `i` is the record attachment **id** `i` resolves to, `0xffff` for none. Read
-    /// it through [`Self::attachment`], which is the reference's `0x710310` — bounds check and
-    /// sentinel included.
+    /// AttachLookup (header `+0x10c`) as [`Self::attachments`] indices, `0xffff` for none.
     pub attach_lookup: Vec<u16>,
-    /// The animation-event table's **positional markers** (see [`M2EventMarker`]) — every record
-    /// whose bone fits `u16` and indexes into [`Self::bones`], in file order (queries take the
-    /// first ident match, the client's `0x7130e0` scan order). The cast-release launch points
-    /// (`$CSL`/`$CSR`/`$CST`), the ranged release (`$BWR`), the bow anchors, the sound/impact tags'
-    /// anchor points.
+    /// The animation-event markers in file order; a query takes the first ident match (`0x7130e0`).
     pub event_markers: Vec<M2EventMarker>,
-    /// The model's **AnimationLookup** (header `+0x24`/`+0x28`): row `i` is the file slot of this
-    /// model's first sequence for `AnimationData.dbc` id `i`, or `0xffff` where it authors none.
-    /// This is the table behind the reference's ownership predicate — see [`M2Model::owns_animation`].
-    /// Note the table is *short*: a model's `nAnimationLookup` stops just past the highest id it
-    /// authors, so an id beyond the end reads as the out-of-bounds sentinel, i.e. **not owned**.
+    /// AnimationLookup (header `+0x24`): row `i` is the first sequence slot for
+    /// `AnimationData.dbc` id `i`, `0xffff` for none; it ends past the highest authored id.
     pub animation_lookup: Vec<u16>,
-    /// The model's baked **PlayableAnimationLookup** (decision 0082 — see [`M2PlayableAnim`]): row `i`
-    /// is the model's own precomputed substitute for requested `AnimationData.dbc` id `i`. Empty for a
-    /// version past 263 (the array is dropped) or a model whose header couldn't be read that far — the
-    /// resolver degrades to identity in that case.
+    /// The PlayableAnimationLookup: row `i` is the model's substitute for requested id `i`.
     pub playable_animation_lookup: Vec<M2PlayableAnim>,
-    /// Embedded skin-profile array `(count, file_offset)` — `parse_embedded_skin` reads from here.
+    /// The embedded skin profiles' `(count, file_offset)`.
     pub(crate) views: (u32, u32),
     pub(crate) version: u32,
 }
 
 impl M2Model {
-    /// **Are this batch's stage-`stage` texture coordinates GENERATED (environment-mapped) rather
-    /// than read from the vertex UVs?**
-    ///
-    /// The reference's gate, at `0x70b8bd` (`cmp word[ [MD20+0xa0][texCoordSet + stage] ], 0x2; jbe`
-    /// — wow-re `m2-texanim-uv` §2, models.md §936/§944): a [`Self::texture_unit_lookup`] entry
-    /// `<= 2` names a vertex UV channel, anything higher (real art authors `0xffff`) is a
-    /// **generated environment coordinate**. Such a stage can never be `textureTransform`-driven,
-    /// and the shipped vertex program writes it as the sphere-map remap of the view-space
-    /// reflection vector — `uv = normalize(P − 2(P·N)N).xy · 0.5 + 0.5`, the `(0.5,0,0,0.5 /
-    /// 0,0.5,0,0.5)` matrix wow-re byte-derived at `0x70b8d0`.
-    ///
-    /// **An out-of-range index reads as env-mapped**, matching the reference: `0x70b8bd` indexes
-    /// the table unguarded and falls through to the same `else` branch that writes the env remap.
-    /// That is also the only safe direction — a model whose art relies on generated coordinates
-    /// authors *no usable UVs at all* (`GnomeSubwayGlass.m2`: all 330 vertices at exactly
-    /// `(0,0)`), so mistaking env for UV paints the whole mesh in a single corner texel.
+    /// Whether `batch`'s stage `stage` takes generated environment coordinates: the reference's
+    /// gate `0x70b8bd` treats a [`Self::texture_unit_lookup`] entry above 2 (art: `0xffff`), and an
+    /// out-of-range index, as the sphere map of the view-space reflection (`0x70b8d0`), which no
+    /// texture transform drives.
     pub fn stage_is_env_mapped(&self, batch: &crate::SkinBatch, stage: u16) -> bool {
         let idx = batch.texture_coord_combo_index as usize + stage as usize;
         self.texture_unit_lookup.get(idx).is_none_or(|&v| v > 2)
     }
 
-    /// **Does this model author `AnimationData.dbc` id `anim_id`?** — the reference's `0x711960`,
-    /// byte-for-byte: a bounds-checked read of [`Self::animation_lookup`] (`0x710310` returns the
-    /// `0xffff` sentinel for an out-of-range index) compared against `0xffff`.
-    ///
-    /// This is the predicate the GameObject animation arm branches on when the substate's animation
-    /// id is missing from the model (wow-re `gameobject-anim-arm.md` §2c's four-way remap), so it
-    /// must answer exactly as the reference does — including for an id past the table's end, which
-    /// is **not owned** even if some later mechanism could reach a sequence carrying it.
+    /// Whether the model authors `AnimationData.dbc` id `anim_id`: the reference's `0x711960`, a
+    /// bounds-checked [`Self::animation_lookup`] read, so an id past the end is not owned.
     pub fn owns_animation(&self, anim_id: u16) -> bool {
         self.animation_lookup
             .get(anim_id as usize)
             .is_some_and(|&slot| slot != 0xffff)
     }
 
-    /// **The attachment record an attach id resolves to** — the reference's `0x710310` +
-    /// `0x712f70` pair, byte-for-byte: a bounds-checked [`Self::attach_lookup`] read
-    /// (`id >= count` ⇒ the `0xffff` sentinel) and then the record it names. `None` where the id
-    /// has no record, which is how the reference behaves too: `0x712f70` stores the sentinel and
-    /// every consumer of that field (`0x7140aa`, `0x718668`, `0x719266`) tests `cmp 0xffff; je`
-    /// and skips the child, so an unresolvable id hangs **nothing** rather than falling back to
-    /// the model origin.
-    ///
-    /// Never scan [`Self::attachments`] for a matching id instead: on the ~5% of weapon models
-    /// that author duplicate ids the two disagree, and the lookup is the authority (decision
-    /// 0805).
+    /// The record attach id `id` resolves to through [`Self::attach_lookup`] (`0x710310`,
+    /// `0x712f70`). An unresolved id hangs nothing: its users (`0x7140aa`, `0x718668`, `0x719266`)
+    /// skip the sentinel. A scan of [`Self::attachments`] disagrees where weapons repeat ids.
     pub fn attachment(&self, id: u16) -> Option<&M2Attachment> {
         let idx = *self.attach_lookup.get(id as usize)?;
         (idx != 0xffff)
@@ -405,7 +287,7 @@ impl M2Model {
     }
 }
 
-/// Holds the parsed model (mirrors the reference's `parse_m2(..).model()` shape).
+/// Holds the parsed model.
 pub struct M2Format {
     pub(crate) model: M2Model,
 }
diff --git a/crates/benilla-m2/src/skin.rs b/crates/benilla-m2/src/skin.rs
index 81be601b..817ff04a 100644
--- a/crates/benilla-m2/src/skin.rs
+++ b/crates/benilla-m2/src/skin.rs
@@ -1,18 +1,14 @@
-//! Embedded skin-profile parsing: [`Skin`]/[`SkinSection`]/[`SkinBatch`] and
-//! [`M2Model::parse_embedded_skin`], which decodes one of the model's embedded skin profiles
-//! (indices / triangles / submeshes / batches) by file offset.
+//! Embedded skin profiles: indices, triangles, submeshes and batches.
 
 use benilla_bytes::{capped, ByteExt};
 
 use crate::error::{Error, Result};
 use crate::model::M2Model;
 
-/// One skin submesh section (we keep the triangle range the renderer iterates, plus the section's
-/// `skinSectionId` — the geoset/mesh-part ID the character compositor selects visibility by).
+/// One skin submesh: its triangle range and geoset id.
 pub struct SkinSection {
-    /// `skinSectionId` (mesh-part / geoset ID): `group*100 + variant`. For a character model this is
-    /// what geoset selection toggles (hide all but the chosen hair/facial-hair/body variants); `0` for a
-    /// model with a single unnamed geoset (most creatures/doodads).
+    /// `skinSectionId`, the geoset id `group*100 + variant` that character geoset selection
+    /// toggles; 0 on a single-geoset model.
     pub id: u16,
     pub triangle_start: u16,
     pub triangle_count: u16,
@@ -20,26 +16,23 @@ pub struct SkinSection {
 
 /// One skin draw batch (section + material + texture-combo references).
 pub struct SkinBatch {
-    /// Batch flags (texUnit `+0x00`) — kept raw, unclassified. Read by the diagnostic dumps while
-    /// we carve which bits the reference's batch path actually reads; the renderer ignores them.
+    /// Batch flags (texUnit `+0x00`), raw; the renderer ignores them.
     pub flags: u16,
-    /// Shader / render-order selector (texUnit `+0x02`), same status as [`Self::flags`].
+    /// Shader or render-order selector (texUnit `+0x02`), raw; the renderer ignores it.
     pub shader_id: u16,
     pub skin_section_index: u16,
     pub texture_combo_index: u16,
-    /// Index into [`crate::M2Model::texture_unit_lookup`] → where this stage's texture coordinates
-    /// come from (a UV channel, or a generated environment coordinate). texUnit `+0x12`
-    /// (wow-re rf72 `0x70b8a4`).
+    /// Index into [`crate::M2Model::texture_unit_lookup`], the stage's coordinate source (texUnit
+    /// `+0x12`, `0x70b8a4`).
     pub texture_coord_combo_index: u16,
     pub material_index: u16,
-    /// Direct index into [`crate::M2Model::color_alpha_tracks`] (`0xffff` = none). texUnit `+0x08`.
+    /// Index into [`crate::M2Model::color_alpha_tracks`], `0xffff` for none (texUnit `+0x08`).
     pub color_index: u16,
-    /// Index into [`crate::M2Model::transparency_lookup`] → a transparency track. texUnit `+0x14`.
+    /// Index into [`crate::M2Model::transparency_lookup`] (texUnit `+0x14`).
     pub weight_combo_index: u16,
-    /// Texture count (texUnit `+0x0e`); `0` ⇒ the transparency factor is not applied (verified gate).
+    /// Texture count (texUnit `+0x0e`); at 0 the transparency factor is not applied.
     pub texture_count: u16,
-    /// Index into [`crate::M2Model::texture_transform_lookup`] → a texture transform (UV
-    /// animation). texUnit `+0x16` (wow-re rf72, `0x70b897`).
+    /// Index into [`crate::M2Model::texture_transform_lookup`] (texUnit `+0x16`, `0x70b897`).
     pub texture_transform_combo_index: u16,
 }
 
@@ -66,9 +59,8 @@ impl Skin {
 }
 
 impl M2Model {
-    /// Decode embedded skin profile `index` from the original file `bytes`. The skin profiles are an
-    /// array of 44-byte `M2View` headers at `views.offset`; each references its indices / triangles /
-    /// submeshes / batches by file offset.
+    /// Decode embedded skin profile `index` from the file `bytes`: one of the 44-byte `M2View`
+    /// headers, each naming its arrays by file offset.
     pub fn parse_embedded_skin(&self, bytes: &[u8], index: usize) -> Result<Skin> {
         let (count, ofs) = self.views;
         if index >= count as usize {
@@ -87,9 +79,7 @@ impl M2Model {
         let (n_sub, o_sub) = rd_arr(vp + 24)?;
         let (n_bat, o_bat) = rd_arr(vp + 32)?;
 
-        // `bytes_at(o, n * 2)` bounds-checks the whole run before any element is read, so — unlike
-        // the header-driven reservations above — `n` is already provably within the file's own size
-        // once this succeeds; no separate `capped()` needed for the `Vec::with_capacity(n)` below.
+        // `bytes_at` checks the whole run first, so `n` needs no `capped`.
         let read_u16s = |n: usize, o: usize| -> Result<Vec<u16>> {
             let slice = bytes.bytes_at(o, n * 2).ok_or(Error::Truncated)?;
             let mut v = Vec::with_capacity(n);
@@ -101,12 +91,9 @@ impl M2Model {
         let indices = read_u16s(n_idx, o_idx)?;
         let triangles = read_u16s(n_tri, o_tri)?;
 
-        // M2SkinSection: 32 bytes pre-Wrath (v<260), 48 with the later centre-bounds; indexStart @8,
-        // indexCount @10 are the triangle range either way.
+        // M2SkinSection: 32 bytes before v260, 48 from it; the triangle range is @8 and @10.
         let sec = if self.version < 260 { 32 } else { 48 };
-        // Reservations capped (decision 0064): `n_sub`/`n_bat` come straight from the M2View header,
-        // unvalidated, and the loops below check bounds only per-element — same shape as the header
-        // arrays above, so the same guard applies.
+        // `n_sub` and `n_bat` are unvalidated, so the reservations are capped.
         let sub_avail = bytes.len().saturating_sub(o_sub);
         let mut submeshes = Vec::with_capacity(capped(n_sub, sec, sub_avail));
         for i in 0..n_sub {
@@ -119,10 +106,7 @@ impl M2Model {
                 triangle_count: s.u16_at(10).ok_or(Error::Truncated)?,
             });
         }
-        // M2TextureUnit (batch): 24 bytes — skinSectionIndex@4, colorIndex@8, materialIndex@0xa,
-        // textureCount@0xe, textureComboIndex@0x10, textureCoordComboIndex@0x12 (the env-vs-UV
-        // source), weightComboIndex@0x14 (the visibility-factor refs), textureTransformComboIndex@0x16
-        // (UV animation).
+        // M2TextureUnit, a batch: 24 bytes.
         let bat_avail = bytes.len().saturating_sub(o_bat);
         let mut batches = Vec::with_capacity(capped(n_bat, 24, bat_avail));
         for i in 0..n_bat {
diff --git a/crates/benilla-m2/src/tests.rs b/crates/benilla-m2/src/tests.rs
index b0c62ce4..a492e739 100644
--- a/crates/benilla-m2/src/tests.rs
+++ b/crates/benilla-m2/src/tests.rs
@@ -1,11 +1,9 @@
 use super::*;
 
-// The field walk in `parse_m2` reads M2Arrays up through the event table (the last read, at
-// header offset 0x114) and stops there — the fixture header covers exactly that walk.
+// The header through the event table at 0x114, as far as `parse_m2` walks.
 const HEADER_LEN: usize = 284;
 
-// Byte offsets of the M2Arrays this parser reads, matching the field walk in `parse_m2` for a
-// v256 (pre-Wrath) header.
+// v256 header offsets of the M2Arrays under test.
 const OFS_PLAYABLE_ANIM_LOOKUP: usize = 44;
 const OFS_TEX_ANIM: usize = 0x74;
 const OFS_TEX_UNIT_LOOKUP: usize = 0x9c;
@@ -17,8 +15,7 @@ const OFS_VIEWS: usize = 76;
 const OFS_ATTACHMENTS: usize = 260;
 const OFS_EVENTS: usize = 276;
 
-/// A minimal v256 MD20 header: the magic + version, every M2Array zeroed (count 0, offset 0).
-/// Callers patch specific arrays with [`set_arr`] and append payload bytes after `HEADER_LEN`.
+/// A v256 MD20 header with every M2Array empty; tests patch arrays with [`set_arr`].
 fn header() -> Vec<u8> {
     let mut b = vec![0u8; HEADER_LEN];
     b[0..4].copy_from_slice(b"MD20");
@@ -69,12 +66,8 @@ fn m2track(interp: u16, gseq: u16, ts: (u32, u32), vals: (u32, u32)) -> Vec<u8>
     t
 }
 
-/// **A fix16 key is SIGNED.** Real art authors "hide me" as `0x8001` — `−32767`, i.e. `−1.0` —
-/// which read unsigned decodes to `+1.00006` and sails through the reference's `A ≤ 0` batch cull.
-/// `TanarisTrollGate.m2` switches between its intact gate and its burnt twin with exactly these
-/// ±1 keys, so reading them unsigned drew both copies at once (B138, decision 1460). Both records
-/// that carry a fix16 track — the M2Color **alpha** (header `0x54`, stride `0x38`, track @ `+0x1c`)
-/// and the M2TextureWeight (header `0x64`, stride `0x1c`) — share the decode, so both are checked.
+/// `TanarisTrollGate.m2` swaps its intact and burnt gates with these ±1 keys. Both fix16 records
+/// are checked: the M2Color alpha (header `0x54`, track @ `+0x1c`) and the M2TextureWeight.
 #[test]
 fn a_negative_fix16_key_decodes_signed() {
     let mut b = header();
@@ -82,14 +75,14 @@ fn a_negative_fix16_key_decodes_signed() {
     b.extend(0u32.to_le_bytes());
     b.extend(333u32.to_le_bytes());
     let val_ofs = b.len() as u32;
-    b.extend(0x7fffu16.to_le_bytes()); // +1.0 — "draw me"
-    b.extend(0x8001u16.to_le_bytes()); // −1.0 — "hide me"
-                                       // One M2Color: a keyless RGB track @ +0x00, then the 2-key alpha track @ +0x1c.
+    b.extend(0x7fffu16.to_le_bytes()); // +1.0, drawn
+    b.extend(0x8001u16.to_le_bytes()); // −1.0, hidden
+                                       // One M2Color: a keyless RGB track, then the alpha track.
     let color_ofs = b.len() as u32;
     b.extend(m2track(0, 0xffff, (0, 0), (0, 0)));
     b.extend(m2track(1, 0xffff, (2, ts_ofs), (2, val_ofs)));
     set_arr(&mut b, 0x54, 1, color_ofs);
-    // One M2TextureWeight: the same keys again, so the weight side is covered too.
+    // One M2TextureWeight with the same keys.
     let weight_ofs = b.len() as u32;
     b.extend(m2track(1, 0xffff, (2, ts_ofs), (2, val_ofs)));
     set_arr(&mut b, 0x64, 1, weight_ofs);
@@ -128,8 +121,7 @@ fn texture_transform_translation_track_decodes() {
             b.extend(c.to_le_bytes());
         }
     }
-    // One M2TextureTransform record (stride 0x54): a 2-key gseq-0 translation track, then keyless
-    // rotation + scaling tracks.
+    // One M2TextureTransform: a 2-key gseq-0 translation, then keyless rotation and scaling.
     let rec_ofs = b.len() as u32;
     b.extend(m2track(1, 0, (2, ts_ofs), (2, val_ofs)));
     b.extend(m2track(0, 0xffff, (0, 0), (0, 0)));
@@ -156,11 +148,7 @@ fn texture_transform_translation_track_decodes() {
     assert!(t.scaling.keys.is_empty());
 }
 
-/// The three adjacent u16 lookup slots must not be confused: texUnitLookup@0x9c ·
-/// transLookup@0xa4 · texAnimLookup@0xac (wow-re stride-pin reconciliation; models.md's field-map
-/// *line* labels them one slot early). Shaped like the real StormwindMagePortal01 header — [0] at
-/// 0x9c, the identity [0,1,2,3] at 0xa4, [0xffff] at 0xac — where reading 0x9c as the transparency
-/// lookup silently dropped the combo-1..3 weight tracks.
+/// Shaped like StormwindMagePortal01's header: [0] at 0x9c, [0,1,2,3] at 0xa4, [0xffff] at 0xac.
 #[test]
 fn transparency_lookup_reads_0xa4_not_the_texture_unit_lookup_at_0x9c() {
     let mut b = header();
@@ -186,9 +174,7 @@ fn transparency_lookup_reads_0xa4_not_the_texture_unit_lookup_at_0x9c() {
 fn playable_animation_lookup_decodes_low16_high16() {
     let mut b = header();
     let pal_ofs = b.len() as u32;
-    // Row 0: identity, no dir flags. Row 1: HumanMale's real byte-verified example
-    // (`playableAnimationLookup[6] = 0x00030001`, wow-re `anim-id-resolution.md` §4) — resolved
-    // id 1, dir-flags code 3.
+    // Row 1 is HumanMale's `playableAnimationLookup[6] = 0x00030001`: id 1, code 3.
     b.extend(0u32.to_le_bytes());
     b.extend(0x0003_0001u32.to_le_bytes());
     set_arr(&mut b, OFS_PLAYABLE_ANIM_LOOKUP, 2, pal_ofs);
@@ -211,7 +197,7 @@ fn bone_record(pivot: [f32; 3]) -> Vec<u8> {
 }
 
 fn attachment_record(id: u32, bone: u32, position: [f32; 3]) -> Vec<u8> {
-    let mut b = vec![0u8; 48]; // id+bone+position (20 bytes) + the skipped 28-byte visibility track
+    let mut b = vec![0u8; 48]; // id, bone, position (20 bytes), the skipped 28-byte track
     b[0..4].copy_from_slice(&id.to_le_bytes());
     b[4..8].copy_from_slice(&bone.to_le_bytes());
     b[8..12].copy_from_slice(&position[0].to_le_bytes());
@@ -223,7 +209,7 @@ fn attachment_record(id: u32, bone: u32, position: [f32; 3]) -> Vec<u8> {
 #[test]
 fn attachments_parse_and_skip_out_of_range_records() {
     let mut b = header();
-    // Two bones, so a valid attachment bone index is 0 or 1.
+    // Two bones, so a valid bone index is 0 or 1.
     let bones_ofs = b.len() as u32;
     b.extend(bone_record([0.0, 0.0, 0.0]));
     b.extend(bone_record([1.0, 1.0, 1.0]));
@@ -244,7 +230,7 @@ fn attachments_parse_and_skip_out_of_range_records() {
 }
 
 fn event_record(ident: &[u8; 4], bone: u32, position: [f32; 3]) -> Vec<u8> {
-    let mut b = vec![0u8; 44]; // ident+data+bone+position (24 bytes) + the skipped 20-byte track
+    let mut b = vec![0u8; 44]; // ident, data, bone, position (24 bytes), the skipped 20-byte track
     b[0..4].copy_from_slice(ident);
     b[8..12].copy_from_slice(&bone.to_le_bytes());
     b[12..16].copy_from_slice(&position[0].to_le_bytes());
@@ -301,16 +287,43 @@ fn one_vertex_decodes_all_fields() {
 
 #[test]
 fn hostile_vertex_count_errs_cleanly_not_oom() {
-    // The bug this migration fixes: `vertices.0` is read straight off the file with no relation
-    // to the buffer's actual size. Pre-0064, `Vec::with_capacity(vertices.0 as usize)` tried to
-    // reserve `u32::MAX * 48` bytes up front and aborted the process. Post-0064 the reservation
-    // is capped by the remaining input (here: zero bytes after the header), so this returns an
-    // ordinary `Err` from the first bounds-checked read instead.
+    // `u32::MAX` vertices must fail at the first read, not reserve `u32::MAX * 48` bytes.
     let mut b = header();
     set_arr(&mut b, OFS_VERTICES, u32::MAX, HEADER_LEN as u32);
     assert!(matches!(parse(&b), Err(Error::Truncated)));
 }
 
+#[test]
+fn hostile_attachment_count_errs_cleanly_not_oom() {
+    // `emitted_at` is sized from the count, so a table the file cannot hold is refused first.
+    let mut b = header();
+    set_arr(&mut b, OFS_ATTACHMENTS, u32::MAX, HEADER_LEN as u32);
+    assert!(matches!(parse(&b), Err(Error::Truncated)));
+}
+
+#[test]
+fn hostile_track_record_counts_walk_only_what_the_file_holds() {
+    // The colour (0x54), weight (0x64) and texture-transform (0x74) readers never fail, so the
+    // file bounds their loops, not the count.
+    let mut b = header();
+    set_arr(&mut b, 0x54, u32::MAX, HEADER_LEN as u32);
+    set_arr(&mut b, 0x64, u32::MAX, HEADER_LEN as u32);
+    set_arr(&mut b, OFS_TEX_ANIM, u32::MAX, HEADER_LEN as u32);
+    let fmt = parse(&b).expect("lenient blocks never fail the parse");
+    let m = fmt.model();
+    assert!(m.color_alpha_tracks.is_empty());
+    assert!(m.color_rgb_tracks.is_empty());
+    assert!(m.transparency_tracks.is_empty());
+    assert!(m.texture_transforms.is_empty());
+    // A count that overshoots a partly-present block yields exactly the whole records in it.
+    let mut b = header();
+    let ofs = b.len() as u32;
+    b.extend(m2track(0, 0xffff, (0, 0), (0, 0))); // one whole 0x1c weight record …
+    b.extend(vec![0u8; 0x10]); // … and part of a second
+    set_arr(&mut b, 0x64, 5, ofs);
+    assert_eq!(parse(&b).unwrap().model().transparency_tracks.len(), 1);
+}
+
 #[test]
 fn truncated_vertex_record_errs_cleanly() {
     let mut b = header();
@@ -323,20 +336,18 @@ fn truncated_vertex_record_errs_cleanly() {
 fn hostile_shapes_do_not_panic() {
     assert!(matches!(parse(&[]), Err(Error::NotMd20)));
     assert!(matches!(parse(&[0u8; 7]), Err(Error::NotMd20)));
-    // A recognizable magic with an unsupported version.
     let mut b = vec![0u8; HEADER_LEN];
     b[0..4].copy_from_slice(b"MD20");
     b[4..8].copy_from_slice(&999u32.to_le_bytes());
     assert!(matches!(parse(&b), Err(Error::UnsupportedVersion(999))));
-    // A header truncated mid-array.
     assert!(matches!(
         parse(&header()[..HEADER_LEN - 4]),
         Err(Error::Truncated)
     ));
 }
 
-/// Build a full synthetic MD20 file with one embedded skin profile (one index, one triangle, one
-/// submesh, one batch) so `parse_embedded_skin` has something real to decode.
+/// An MD20 file with one embedded skin profile: three indices, three triangle indices, one
+/// submesh, one batch.
 fn model_with_one_skin() -> Vec<u8> {
     let mut b = header();
     let vp = HEADER_LEN as u32; // M2View header right after the fixed header
@@ -401,7 +412,7 @@ fn embedded_skin_out_of_range_index_errs() {
 
 #[test]
 fn hostile_submesh_count_errs_cleanly_not_oom() {
-    // Same OOM-abort shape as the vertex case, but inside `parse_embedded_skin`'s M2View arrays.
+    // The vertex case, in `parse_embedded_skin`'s M2View arrays.
     let mut b = model_with_one_skin();
     let vp = HEADER_LEN; // M2View header offset (see `model_with_one_skin`)
     let end = b.len() as u32;
@@ -415,8 +426,7 @@ fn hostile_submesh_count_errs_cleanly_not_oom() {
 
 // --- cameras (header 0x124/0x128) + the cubic samplers ---------------------------------------
 
-/// The camera array sits past [`HEADER_LEN`], so camera fixtures carry a header long enough to
-/// hold `cameras`@`0x124` and `cameraLookup`@`0x12c`.
+/// A header long enough for `cameras`@`0x124` and `cameraLookup`@`0x12c`, past [`HEADER_LEN`].
 const CAM_HEADER_LEN: usize = 0x134;
 const OFS_CAMERAS: usize = 0x124;
 const OFS_CAMERA_LOOKUP: usize = 0x12c;
@@ -430,8 +440,7 @@ fn cam_header() -> Vec<u8> {
 /// One fixture key: `(ms, value, in_tan, out_tan)`.
 type SplineKeyFixture = (u32, [f32; 3], [f32; 3], [f32; 3]);
 
-/// Append a cubic `C3Vector` track's payload and return the 28 track bytes pointing at it, laid
-/// out `{value, inTan, outTan}` per the 0x24 key.
+/// Append a cubic `C3Vector` track's `{value, inTan, outTan}` keys and return the track's 28 bytes.
 fn spline_vec3_track(b: &mut Vec<u8>, interp: u16, keys: &[SplineKeyFixture]) -> Vec<u8> {
     let times_ofs = b.len() as u32;
     for (ms, ..) in keys {
@@ -457,9 +466,8 @@ fn spline_vec3_track(b: &mut Vec<u8>, interp: u16, keys: &[SplineKeyFixture]) ->
     t
 }
 
-/// A one-camera model whose position track carries the two keys `interp` will be sampled between:
-/// `value 0 → 3` on X with tangents `out[k0] = 1`, `in[k1] = 2` — four numbers chosen so the four
-/// interpolation legs land on four *different* answers.
+/// A one-camera model whose position track runs X from 0 to 3 over 1000 ms, with
+/// `outTan[k0] = 1` and `inTan[k1] = 2`.
 fn model_with_one_camera(interp: u16) -> Vec<u8> {
     let mut b = cam_header();
     let rec = b.len() as u32;
@@ -514,8 +522,7 @@ fn camera_record_fields_and_lookup_parse() {
 
 #[test]
 fn cubic_sampler_takes_all_four_interp_legs() {
-    // Between `value 0` and `value 3`, with `outTan[k0] = 1` and `inTan[k1] = 2`, at the exact
-    // midpoint. Hand-computed from the bases in `M2Track::sample_ms`:
+    // At the midpoint, hand-computed from the bases in `M2Track::sample_ms`:
     //   step   → value[k0]                                              = 0
     //   linear → 0 + (3−0)·0.5                                          = 1.5
     //   Bézier → 0.125·0 + 0.375·1 + 0.375·2 + 0.125·3                  = 1.5
diff --git a/crates/benilla-m2/src/track.rs b/crates/benilla-m2/src/track.rs
index 74ee8658..05e2b812 100644
--- a/crates/benilla-m2/src/track.rs
+++ b/crates/benilla-m2/src/track.rs
@@ -1,35 +1,21 @@
-//! M2Track readers: the typed [`M2Track`] (with the [`M2ScalarTrack`] / [`M2Vec3Track`] /
-//! [`M2QuatTrack`] aliases) plus the track-parsing helpers the header walk (`crate::parse_m2`)
-//! calls for the M2Color, M2TextureWeight, and M2TextureTransform tracks.
+//! M2Track readers and the cubic track sampler.
 
 use benilla_bytes::ByteExt;
 
-/// One typed `M2Track`, fully read: the interpolation type, the global-sequence tag, the
-/// per-sequence key **ranges**, and the keys as **absolute global-timeline milliseconds** paired
-/// with values. The v256 track (stride `0x1c`): `interp`@0, `global_seq`@2, interpolation_ranges
-/// `M2Array`@`0x04/0x08`, timestamps `M2Array`@`0x0c/0x10` (u32 ms), values `M2Array`@`0x14/0x18`.
-/// A sequence-timeline track (`gseq == 0xffff`) keys inside each sequence's absolute time band; a
-/// global-sequence track loops on `global_sequences[gseq]`'s own clock (wow-re
-/// `eval.md`/`doodad-anim-host.md`). Key count is `min(timestamps, values)` — vanilla art
-/// occasionally pads one array.
+/// One `M2Track` (v256, `0x1c` bytes): `interp`@0, `gseq`@2, then ranges, timestamps (u32 ms) and
+/// values as `(count, offset)` pairs @`0x04`, `0x0c`, `0x14`. Keys are absolute timeline ms: a
+/// sequence track keys inside each sequence's band, a `gseq` track loops on its global sequence
+/// (`0x713d50`). The key count is `min(timestamps, values)`, as vanilla art pads one array.
 #[derive(Clone, Debug)]
 pub struct M2Track<V> {
-    /// Interpolation type: `0` = step (nearest-previous key), nonzero = linear (wow-re `eval.md`:
-    /// the scalar sampler's `cmp word[track],0` two-way dispatch).
+    /// `0` step (the previous key), nonzero linear: the scalar sampler's two-way test (`0x71af20`).
     pub interp: u16,
     /// Global-sequence index, `0xffff` = an ordinary sequence-timeline track.
     pub gseq: u16,
-    /// The per-sequence **key-index window** `(lo, hi)`, one entry per sequence in file order —
-    /// the array the reference's key search indexes by the playing sequence's slot before it ever
-    /// looks at a timestamp (VERIFIED wow-re `eval.md` FN1 `0x713d50` §1: `[track+8][idx*8+{0,4}]`;
-    /// an empty array is the `[track+4]==0` fallback, "search the whole key list").
-    ///
-    /// These are **brackets**, not the playable key set: `hi` routinely points at a key in a LATER
-    /// sequence's band, which is why selecting in-clip keys through this window instead of by
-    /// timestamp froze creatures at a garbage pose (benilla decision 0133). Its load-bearing use is
-    /// the other one — a band that keys nothing resolves to `keys[lo]` (`lo >= hi` ⇒ the degenerate
-    /// `{lo, lo, 0}` result), so this array says *exactly* what the reference holds there instead
-    /// of leaving it to a nearest-key approximation.
+    /// The per-sequence key-index window `(lo, hi)`, one per sequence in file order, which the
+    /// reference's key search reads before any timestamp (`0x713d50`; empty means search all
+    /// keys). Brackets, not the clip's keys: `hi` often lands in a later sequence's band. A band
+    /// with no keys resolves to `keys[lo]`.
     pub ranges: Vec<(u32, u32)>,
     /// `(absolute ms, value)` keys, file order (time-ascending within a band).
     pub keys: Vec<(u32, V)>,
@@ -46,25 +32,23 @@ impl<V> Default for M2Track<V> {
     }
 }
 
-/// A scalar (`fix16`, `0..=1`) track — the M2Color **alpha** and M2TextureWeight **weight** tracks.
+/// A scalar track: the M2Color alpha and the M2TextureWeight weight.
 pub type M2ScalarTrack = M2Track<f32>;
-/// A `C3Vector` track — the M2TextureTransform **translation** / **scaling** tracks.
+/// A `C3Vector` track: the M2Color RGB and the texture-transform translation and scaling.
 pub type M2Vec3Track = M2Track<[f32; 3]>;
-/// A quaternion (4×f32, raw v256 floats) track — the M2TextureTransform **rotation** track.
+/// A quaternion track (4×f32): the texture-transform rotation.
 pub type M2QuatTrack = M2Track<[f32; 4]>;
 
 impl<V: Copy + PartialEq> M2Track<V> {
-    /// All key values equal (or a single key): the track is a constant — `Some(value)`; `None` for a
-    /// keyless or genuinely time-varying track.
+    /// The track's value when every key holds the same one.
     pub fn constant(&self) -> Option<V> {
         let (_, first) = *self.keys.first()?;
         self.keys.iter().all(|&(_, v)| v == first).then_some(first)
     }
 }
 
-/// Read one `M2Track<V>` (see [`M2Track`]): the shared `interp`/`gseq`/timestamp walk with a
-/// per-value reader. Out-of-range reads yield an empty key list (= "no keys", the factor/transform
-/// does not apply) — real art relies on that tolerance.
+/// Read one `M2Track<V>` with a per-value reader. An out-of-range track reads as no keys, a
+/// tolerance real art needs.
 fn track_read<V>(
     b: &[u8],
     track_ofs: usize,
@@ -86,9 +70,8 @@ fn track_read<V>(
     let keys = (0..n)
         .map_while(|i| b.u32_at(to + i * 4).zip(read_val(b, vo + i * val_size)))
         .collect();
-    // The per-sequence `(lo, hi)` key-index windows (`M2Array`@0x04/0x08, 8-byte entries) — see
-    // [`M2Track::ranges`]. A short/absent array reads as empty, which is the reference's own
-    // `[track+4] == 0` "no ranges" fallback.
+    // The `(lo, hi)` windows, 8 bytes each; an unreadable array is empty, the reference's
+    // no-ranges case.
     let ranges = match b.u32_at(track_ofs + 0x04).zip(b.u32_at(track_ofs + 0x08)) {
         Some((rn, ro)) => (0..rn as usize)
             .map_while(|i| {
@@ -110,32 +93,22 @@ fn rd_vec3(b: &[u8], o: usize) -> Option<[f32; 3]> {
     Some([b.f32_at(o)?, b.f32_at(o + 4)?, b.f32_at(o + 8)?])
 }
 
-/// Read a scalar `fix16` track (**`int16`**/32767 values). Used for the colour-**alpha** and
-/// transparency-**weight** tracks that gate batch visibility and drive the animated material combine.
-///
-/// **The key is SIGNED** — `movsx`, not `movzx` (VERIFIED, wow-re `system/animation/scratch/tracks.md`
-/// flavour (c): `dest = (f32)(int16 P[k0]) * (1/0x7fff)`, bytes `movsx edx,word[P+k0*2]; fild;
-/// fmul [0x811610]; fstp dest` at `0x715b2f`–`0x715b46`, dispatched at the M2Color-alpha site
-/// `0x715b21` (`colors[]` stride 0x38, track @ +0x1c) and the transparency-weight site `0x715ce2`).
-/// Read unsigned, the authored "hide me" key `0x8001` decodes as `+1.00006` instead of `−1.0`, so a
-/// batch the reference culls (`A ≤ 0`, wow-re `m2-alpha-combine-cull`) draws at full alpha instead:
-/// that is how Zul'Farrak's troll gate drew its BURNT twin on top of its intact self and z-fought
-/// (B138, decision 1460). Values outside `[0, 1]` are the artist's own encoding, not a data quirk —
-/// the combine consumes them as signed floats and the cull tests `≤ 0`.
+/// Read a `fix16` scalar track, `int16 / 32767`. The key is signed (`movsx`, then `fmul` by the
+/// `1/0x7fff` at `0x811610`, `0x715b2f`–`0x715b46`; from the colour alpha `0x715b21` and the weight
+/// `0x715ce2`): art authors `0x8001` (−1.0) to hide a batch, which the cull (`A ≤ 0`,
+/// `0x707b3a`–`0x707b5c`) drops. Values outside `[0, 1]` are authored, not noise.
 pub(crate) fn track_fix16(b: &[u8], track_ofs: usize) -> M2ScalarTrack {
     track_read(b, track_ofs, 2, |b, o| {
         b.u16_at(o).map(|v| f32::from(v as i16) / 32767.0)
     })
 }
 
-/// Read a timed `C3Vector` (3×f32) track — the texture-transform **translation**/**scaling**
-/// tracks and the M2Color **RGB** track.
+/// Read a `C3Vector` (3×f32) track.
 pub(crate) fn track_vec3_timed(b: &[u8], track_ofs: usize) -> M2Vec3Track {
     track_read(b, track_ofs, 12, rd_vec3)
 }
 
-/// Read a timed quaternion (4×f32, raw v256 floats — vanilla does not compress quat keys) track —
-/// the texture-transform **rotation** track.
+/// Read a quaternion track: 4×f32, as vanilla does not compress quaternion keys.
 pub(crate) fn track_quat(b: &[u8], track_ofs: usize) -> M2QuatTrack {
     track_read(b, track_ofs, 16, |b, o| {
         Some([
@@ -147,17 +120,10 @@ pub(crate) fn track_quat(b: &[u8], track_ofs: usize) -> M2QuatTrack {
     })
 }
 
-/// One key of a **cubic** M2 track — the reference's `M2SplineKey<T>`: the value plus its in/out
-/// tangents, `{value@+0, in_tan@+1·sizeof(T), out_tan@+2·sizeof(T)}` (VERIFIED wow-re
-/// `animation/scratch/kern-inner.md` §2a: the vec3 key is stride `0x24`
-/// `{value@+0, inTan@+0xc, outTan@+0x18}`, the scalar-float key stride `0xc`
-/// `{value@+0, inTan@+4, outTan@+8}`).
-///
-/// **The wide key is the stride whatever `interp` says.** The reference's cubic element loops
-/// address every key as `payload + k*0x24` (`0x716b51`) / `payload + k*0xc` (`0x7173cc`) *before*
-/// the four-way interp dispatch, and the STEP/LINEAR legs then read the `value` sub-field of that
-/// same wide key. Real art relies on it: `Cameras\FlyByDwarf.m2`'s roll track is authored
-/// `interp = 0` and still carries a 12-byte key.
+/// One key of a cubic track: the value, then the in and out tangents, each `sizeof(T)` apart. The
+/// wide key is the stride whatever `interp` says: the reference addresses keys as `k*0x24`
+/// (`0x716b51`) or `k*0xc` (`0x7173cc`) before dispatching, and step and linear read its `value`
+/// (`Cameras\FlyByDwarf.m2`'s roll track is `interp = 0` with 12-byte keys).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct M2SplineKey<V> {
     pub value: V,
@@ -165,18 +131,17 @@ pub struct M2SplineKey<V> {
     pub out_tan: V,
 }
 
-/// A cubic `C3Vector` track — the M2Camera **position**/**target** tracks.
+/// A cubic `C3Vector` track: the M2Camera position and target.
 pub type M2Vec3SplineTrack = M2Track<M2SplineKey<[f32; 3]>>;
-/// A cubic scalar-float track — the M2Camera **roll** track.
+/// A cubic scalar track: the M2Camera roll.
 pub type M2ScalarSplineTrack = M2Track<M2SplineKey<f32>>;
 
-/// A value a cubic track can hold: the four basis weights are scalars, so the leaf only has to
-/// know how to build `Σ wᵢ·Pᵢ` componentwise.
+/// A value a cubic track can hold.
 pub trait CubicValue: Copy {
     /// `w0·p0 + w1·p1 + w2·p2 + w3·p3`.
     fn combine(w: [f32; 4], p: [Self; 4]) -> Self;
-    /// The LINEAR leg, in the reference's own form `a + (b − a)·t` (`0x716cf1`) — not the
-    /// algebraically equal `(1−t)·a + t·b`, which rounds differently in f32.
+    /// The linear leg in the reference's form `a + (b − a)·t` (`0x716cf1`), which rounds
+    /// differently in f32 from `(1−t)·a + t·b`.
     fn lerp(a: Self, b: Self, t: f32) -> Self;
 }
 
@@ -199,26 +164,16 @@ impl CubicValue for [f32; 3] {
 }
 
 impl<V: CubicValue> M2Track<M2SplineKey<V>> {
-    /// Sample this cubic track at absolute global-timeline `ms`, **end-clamped** at both ends.
+    /// Sample at absolute timeline `ms`, clamped at both ends, by the cubic loops' four-way
+    /// `interp` dispatch (the bone loops have only two):
     ///
-    /// The four-way `interp` dispatch is the reference's own, and it is the *cubic element loops'*
-    /// dispatch — not the two-way `cmp word[track],0; jne <linear>` the bone/TRS loops collapse to
-    /// (VERIFIED wow-re `animation/scratch/tracks.md` deviation #2: the switch is per-loop, by
-    /// track type). Byte-verified bases, `kern-inner.md` §2a(i)/(ii) with `t` the key-interval
-    /// fraction:
+    /// - `0` step: `value[k0]` (`0x716b5f`).
+    /// - `1` linear (`0x716cf1`).
+    /// - `2` Bézier over `{value[k0], outTan[k0], inTan[k1], value[k1]}` (`0x716c41`), what every
+    ///   `Cameras\*.m2` fly-by authors for position and target.
+    /// - `3` Hermite over `value[k0]`, `outTan[k0]`, `value[k1]`, `inTan[k1]` (`0x716b9e`).
     ///
-    /// - `0` **STEP** — `value[k0]`, no tangent read (`0x716b5f`).
-    /// - `1` **LINEAR** — `value[k0] + (value[k1] − value[k0])·t` (`0x716cf1`).
-    /// - `2` **BÉZIER** — the cubic Bernstein basis over control points
-    ///   `{value[k0], outTan[k0], inTan[k1], value[k1]}`: `B0 = (1−t)³`, `B1 = 3t(1−t)²`,
-    ///   `B2 = 3t²(1−t)`, `B3 = t³` (`0x716c41`). This is what every shipped `Cameras\*.m2`
-    ///   fly-by authors on its position and target tracks.
-    /// - `3` **HERMITE** — `h00·value[k0] + h10·outTan[k0] + h01·value[k1] + h11·inTan[k1]` with
-    ///   `h00 = 2t³−3t²+1`, `h10 = t³−2t²+t`, `h01 = 3t²−2t³`, `h11 = t³−t²` (`0x716b9e`).
-    ///
-    /// Note which tangent each control point comes from: the **outgoing** tangent of the key
-    /// being left and the **incoming** tangent of the key being entered. Swapping them looks
-    /// almost right and drifts wrong exactly where the path curves hardest.
+    /// A span takes the out tangent of the key it leaves and the in tangent of the key it enters.
     pub fn sample_ms(&self, ms: u32) -> Option<V> {
         let first = self.keys.first()?;
         let last = self.keys.last()?;
@@ -276,12 +231,12 @@ fn rd_spline<V>(
     })
 }
 
-/// Read a cubic `C3Vector` track (key stride `0x24`) — the M2Camera position/target tracks.
+/// Read a cubic `C3Vector` track (key stride `0x24`).
 pub(crate) fn track_spline_vec3(b: &[u8], track_ofs: usize) -> M2Vec3SplineTrack {
     track_read(b, track_ofs, 0x24, |b, o| rd_spline(b, o, 12, rd_vec3))
 }
 
-/// Read a cubic scalar-float track (key stride `0xc`) — the M2Camera roll track.
+/// Read a cubic scalar track (key stride `0xc`).
 pub(crate) fn track_spline_f32(b: &[u8], track_ofs: usize) -> M2ScalarSplineTrack {
     track_read(b, track_ofs, 0xc, |b, o| {
         rd_spline(b, o, 4, |b, o| b.f32_at(o))
diff --git a/crates/benilla-mpq/Cargo.toml b/crates/benilla-mpq/Cargo.toml
index 1f9dd5c5..936a5941 100644
--- a/crates/benilla-mpq/Cargo.toml
+++ b/crates/benilla-mpq/Cargo.toml
@@ -3,17 +3,13 @@ name = "benilla-mpq"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "Read-only MPQ archive reader for WoW 1.12.1 (build 5875) — in-repo, decision 0021"
+description = "Read-only MPQ archive reader for WoW 1.12.1 (build 5875)"
 
 [lints]
 workspace = true
 
 [dependencies]
-# Bounds-checked byte readers + the allocation-cap guard (decision 0064). MPQ migrates minimally: the
-# hand-rolled rd_u16/rd_u32 move to ByteExt and the header/block-table/sector allocations get capped;
-# nothing else here changes (this crate is StormLib-pinned and deliberately not churned further).
+# Bounds-checked byte readers and the allocation cap on the header, block table and sectors.
 benilla-bytes = { path = "../benilla-bytes" }
-# zlib/inflate for the ZLIB (0x02) sector codec. miniz_oxide backend (pure Rust); no C, no archive
-# writing. Any other codec the differential pass turns up in real 1.12.1 data (e.g. PKWARE-DCL 0x08)
-# gets vendored alongside; `decompress` errors loudly on an unknown method so nothing is missed.
+# Inflate for the ZLIB (0x02) sector codec, on its pure-Rust miniz_oxide backend.
 flate2 = "1.1"
diff --git a/crates/benilla-mpq/examples/mpqcat.rs b/crates/benilla-mpq/examples/mpqcat.rs
index 8c2939df..13f448ad 100644
--- a/crates/benilla-mpq/examples/mpqcat.rs
+++ b/crates/benilla-mpq/examples/mpqcat.rs
@@ -1,15 +1,13 @@
-//! `mpqcat` — write one file out of an MPQ to stdout. The instrument for reading the real client's
-//! own data (FrameXML, GlobalStrings, a BLP header) when a fidelity question needs the source
-//! rather than a memory of it. Several decision records cite an external `mpqx` for this; nothing
-//! in the workspace could do it until now, so every lookup was a hunt.
+//! `mpqcat`: write one file out of an MPQ to stdout, to read the client's own data (FrameXML,
+//! GlobalStrings, a BLP header).
 //!
 //! ```text
-//! cargo run -q -p benilla-mpq --example mpqcat -- <archive.MPQ> 'Interface\FrameXML\MacroFrame.xml'
+//! cargo run -q -p benilla-mpq --example mpqcat -- <archive.MPQ> 'Interface\FrameXML\UIParent.lua'
 //! ```
 //!
-//! Archive names are the client's own backslash paths. A miss is an error, not empty output — the
-//! same file often lives in several archives (patch beats interface beats base), and "not here"
-//! and "here but empty" are answers you must be able to tell apart.
+//! Names are the client's backslash paths. A miss is an error, not empty output: the same file
+//! often lives in several archives (patch over interface over base), and "not here" must read
+//! apart from "here but empty".
 use std::io::Write;
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
diff --git a/crates/benilla-mpq/src/crypto.rs b/crates/benilla-mpq/src/crypto.rs
index bd1b587b..5210eb8c 100644
--- a/crates/benilla-mpq/src/crypto.rs
+++ b/crates/benilla-mpq/src/crypto.rs
@@ -1,15 +1,8 @@
-//! The Storm (MPQ) crypto primitives — byte-exact with the real client.
-//!
-//! Three pieces, all driven by one statically-generated 0x500-entry table:
-//! - [`hash_string`] — Blizzard's string hash, used for hash-table indexing (`TABLE_OFFSET`), the two
-//!   filename verifiers (`NAME_A`/`NAME_B`), and table/file keys (`FILE_KEY`).
-//! - [`decrypt_block`] — the in-place table/sector decryptor.
-//!
-//! 1.12.1 archives carry **no encrypted files** (verified across the real `Data/`), so only the hash
-//! and block *tables* are ever decrypted. The known StormLib vectors are pinned as tests below.
+//! The Storm (MPQ) crypto, byte-exact with the client: the string hash and the block decryptor,
+//! both over one 0x500-entry table. 1.12.1 archives carry no encrypted files, so only the hash and
+//! block tables are ever decrypted.
 
-/// The MPQ encryption table (0x500 u32s), generated by the StormLib seed walk. `const fn` so it's
-/// baked into the binary, identical to the table the client builds at runtime.
+/// The 0x500-entry encryption table, built at compile time by the seed walk the client runs.
 const fn encryption_table() -> [u32; 0x500] {
     let mut table = [0u32; 0x500];
     let mut seed: u32 = 0x0010_0001;
@@ -32,20 +25,20 @@ const fn encryption_table() -> [u32; 0x500] {
 
 static TABLE: [u32; 0x500] = encryption_table();
 
-/// Hash-type selectors (the table-quadrant offsets the client uses).
+/// Hash-type selectors: the table-quadrant offsets the client uses.
 pub mod hash_type {
     /// Hash-table slot index.
     pub const TABLE_OFFSET: u32 = 0x000;
-    /// Filename verifier A (stored in the hash entry).
+    /// Filename verifier A, stored in the hash entry.
     pub const NAME_A: u32 = 0x100;
-    /// Filename verifier B (stored in the hash entry).
+    /// Filename verifier B, stored in the hash entry.
     pub const NAME_B: u32 = 0x200;
-    /// File / table decryption key.
+    /// File and table decryption key.
     pub const FILE_KEY: u32 = 0x300;
 }
 
-/// Blizzard's string hash. Normalizes `/`→`\` and ASCII-uppercases (matching the client's
-/// `AsciiToUpper` table, which only folds `a`–`z`), then runs the seed mix.
+/// Blizzard's string hash: `/` reads as `\`, and only `a`-`z` are uppercased, as the client's
+/// `AsciiToUpper` table does.
 pub fn hash_string(name: &str, kind: u32) -> u32 {
     let mut seed1: u32 = 0x7FED_7FED;
     let mut seed2: u32 = 0xEEEE_EEEE;
@@ -64,8 +57,7 @@ pub fn hash_string(name: &str, kind: u32) -> u32 {
     seed1
 }
 
-/// Decrypt a block of `u32`s in place with `key` (the StormLib block cipher). A zero key is a no-op,
-/// as in the client. Used for the hash/block tables; file data is never encrypted in 1.12.1.
+/// Decrypt `u32`s in place with `key`; a zero key is a no-op, as in the client.
 pub fn decrypt_block(data: &mut [u32], mut key: u32) {
     if key == 0 {
         return;
@@ -83,8 +75,7 @@ pub fn decrypt_block(data: &mut [u32], mut key: u32) {
     }
 }
 
-/// Test-only inverse of [`decrypt_block`] — lets the reader's round-trip tests (here and in `lib`)
-/// build the encrypted hash/block tables a real archive stores. Same walk, XOR on the plaintext side.
+/// The inverse of [`decrypt_block`], for tests that build the encrypted tables an archive stores.
 #[cfg(test)]
 pub(crate) fn encrypt_block(data: &mut [u32], mut key: u32) {
     let mut seed: u32 = 0xEEEE_EEEE;
@@ -104,7 +95,6 @@ pub(crate) fn encrypt_block(data: &mut [u32], mut key: u32) {
 mod tests {
     use super::*;
 
-    /// StormLib's canonical vectors — these pin our table + hash to the real client byte-for-byte.
     #[test]
     fn hash_vectors_match_stormlib() {
         assert_eq!(
@@ -128,7 +118,6 @@ mod tests {
         assert_eq!(a, b);
     }
 
-    /// decrypt∘encrypt round-trips (encrypt is the same walk with the xor on the other side).
     #[test]
     fn decrypt_inverts_encrypt() {
         let key = hash_string("(hash table)", hash_type::FILE_KEY);
diff --git a/crates/benilla-mpq/src/lib.rs b/crates/benilla-mpq/src/lib.rs
index 8b40451b..3dbbb41f 100644
--- a/crates/benilla-mpq/src/lib.rs
+++ b/crates/benilla-mpq/src/lib.rs
@@ -1,38 +1,14 @@
-//! A read-only MPQ archive reader for **WoW 1.12.1 (build 5875)** — in-repo, replacing `wow-mpq`
-//! (decision 0021).
+//! A read-only MPQ reader for the 1.12.1 `Data/` chain: format V1/V2, every file `COMPRESS`-flagged
+//! and sectored, no encrypted or single-unit files, no PTCH patches. Anything else is a hard error.
 //!
-//! Deliberately narrow to what the real `Data/` chain actually is (verified by probing every archive):
-//! format **V1/V2**, every file `COMPRESS`-flagged and **sectored**, **no encrypted files**, **no
-//! single-unit**, **no PTCH** incremental patches. So this does header parse → hash/block **table**
-//! decrypt → name lookup → sectored read (per-sector inflate). It does *not* write archives, decrypt
-//! file data, verify signatures, or load the `(attributes)` table — the wasteful per-open parse that
-//! motivated 0021. Anything outside the verified envelope is a hard error, never a silent guess.
+//! The patch archives carry delete markers (flag `0x02000000`, size 0): the path is deleted from
+//! the composite chain. [`Archive::contains`] reports one present and [`Archive::read_file`]
+//! refuses it with [`Error::NotFound`], so a chain walker asks [`Archive::is_delete_marker`] and
+//! stops there.
 //!
-//! **Delete-markers.** The patch archives *do* carry file tombstones — a block entry flagged
-//! `MPQ_FILE_DELETE_MARKER` (`0x02000000`), `size == 0`, meaning "this path is deleted from the
-//! composite; do not use any lower-priority archive's copy." (`patch.MPQ` uses these to remove stock
-//! FrameXML it replaces with backported addons — decision 0246.) These are **not** readable files:
-//! [`Archive::read_file`] refuses one with [`Error::NotFound`] rather than returning the empty buffer
-//! a naive `size == 0` stored-read would (the silent mislead that cost 0246 a day), and
-//! [`Archive::is_delete_marker`] lets the chain walker see a tombstone and stop instead of falling
-//! through. A delete-marked entry still *exists* in the hash table, so [`Archive::contains`] reports
-//! it present — the chain must consult [`Archive::is_delete_marker`] to tell "deleted" from "readable".
-//!
-//! ## Concurrency
-//! The parsed [`Index`] (header offsets + decrypted hash/block tables) is immutable, so [`Archive`] is
-//! a cheap `Arc` handle that is `Send + Sync` and `Clone`. [`Archive::read_file`] is `&self`: it opens
-//! a **fresh** OS file handle for the read, so concurrent reads share no seek state and need no lock.
-//! Opening the handle is a cheap syscall; the expensive table parse happens once, in [`Archive::open`].
-//!
-//! Correctness was proven by a differential pass against `wow-mpq` over real archives — 37,971 reads
-//! byte-identical across all 13 (decision 0021; the throwaway oracle test is in git history). The
-//! `benilla-formats` loaders now exercise this reader end-to-end against real data on every run.
-//!
-//! Byte access goes through `benilla-bytes` (decision 0064), migrated minimally: the local rd_u16/
-//! rd_u32 are gone in favor of `ByteExt`, and every allocation sized from a header/block-table count
-//! or a sector length — all attacker-controllable in a hostile archive — is capped by what the
-//! archive file could actually hold (`capped`), so a lying header fails with [`Error::Corrupt`]
-//! instead of aborting the allocator. Nothing else here changes.
+//! [`Archive`] is a cheap `Arc` handle; each read opens its own file handle, so reads need no lock.
+//! Every allocation sized from a header count or a sector length is capped by the file's size, so
+//! a lying header fails with [`Error::Corrupt`].
 
 use std::fs::File;
 use std::io::{self, Read, Seek, SeekFrom};
@@ -44,24 +20,22 @@ use benilla_bytes::{capped, ByteExt};
 mod crypto;
 use crypto::{decrypt_block, hash_string, hash_type};
 
-/// `MPQ\x1A` — the archive header signature (little-endian u32).
+/// `MPQ\x1A` as a little-endian `u32`: the archive header signature.
 const SIGNATURE: u32 = 0x1A51_504D;
-/// `MPQ\x1B` — the user-data header signature (some archives offset the real header past it).
+/// `MPQ\x1B`: a user-data header, which points past itself to the real one.
 const USERDATA_SIGNATURE: u32 = 0x1B51_504D;
 
-// Block-table entry flags (only the ones the 1.12.1 envelope can present; others are asserted absent).
 const FLAG_IMPLODE: u32 = 0x0000_0100;
 const FLAG_COMPRESS: u32 = 0x0000_0200;
 const FLAG_ENCRYPTED: u32 = 0x0001_0000;
 const FLAG_SINGLE_UNIT: u32 = 0x0100_0000;
-/// A patch-archive tombstone: the path is deleted from the composite chain (size 0). Recognised so a
-/// tombstone reads as [`Error::NotFound`], not an empty buffer (decision 0246).
+/// A patch archive's delete marker (size 0): the path is deleted from the composite chain.
 const FLAG_DELETE_MARKER: u32 = 0x0200_0000;
 const FLAG_EXISTS: u32 = 0x8000_0000;
 
 /// Hash-table sentinels.
-const HASH_EMPTY: u32 = 0xFFFF_FFFF; // slot never used — stop probing
-const HASH_DELETED: u32 = 0xFFFF_FFFE; // slot deleted — skip, keep probing
+const HASH_EMPTY: u32 = 0xFFFF_FFFF; // never used: ends the probe
+const HASH_DELETED: u32 = 0xFFFF_FFFE; // deleted: skip, keep probing
 
 /// One decrypted hash-table entry (16 bytes on disk).
 #[derive(Clone, Copy)]
@@ -71,8 +45,7 @@ struct HashEntry {
     block_index: u32,
 }
 
-/// One decrypted block-table entry (16 bytes on disk). The on-disk `compressed_size` (word 1) is
-/// skipped — sector sizes come from the offset table, so it's never needed for reading.
+/// One decrypted block-table entry (16 bytes on disk).
 #[derive(Clone, Copy)]
 struct BlockEntry {
     file_pos: u32,
@@ -80,39 +53,33 @@ struct BlockEntry {
     flags: u32,
 }
 
-/// The immutable, parsed-once index of an archive: where the data starts, the sector size, and the
-/// decrypted hash/block tables. Shared behind an `Arc` so [`Archive`] clones are cheap and reads borrow
-/// it without locking.
+/// An archive's index, parsed once and immutable, shared behind an `Arc`.
 struct Index {
     path: PathBuf,
-    /// Byte offset of the MPQ header within the file (0 for vanilla, but found, not assumed).
+    /// Byte offset of the MPQ header in the file: 0 in 1.12 data, but found, not assumed.
     archive_offset: u64,
-    /// `512 << block_size` — the uncompressed sector size.
+    /// The uncompressed sector size, `512 << block_size`.
     sector_size: usize,
     hash_table: Vec<HashEntry>,
     block_table: Vec<BlockEntry>,
 }
 
-/// An open MPQ archive: a cheap, `Clone`, `Send + Sync` handle over a shared [`Index`]. Reads open a
-/// fresh OS handle, so they are `&self` and lock-free.
+/// An open MPQ archive, a cheap `Clone + Send + Sync` handle.
 #[derive(Clone)]
 pub struct Archive {
     index: Arc<Index>,
 }
 
-/// Errors a read can produce. Anything outside the verified 1.12.1 envelope (encrypted file, unknown
-/// codec, …) surfaces here rather than being papered over.
+/// A read error; anything outside the 1.12.1 envelope surfaces here.
 #[derive(Debug)]
 pub enum Error {
     Io(io::Error),
     NotMpq,
     NotFound(String),
-    /// A file or codec shape the 1.12.1 envelope shouldn't contain — investigate, don't guess.
+    /// A file or codec shape 1.12.1 data does not contain.
     Unsupported(String),
     Decompress(String),
-    /// A header/block-table count or sector length claims more than the archive file could possibly
-    /// hold. Caught by the capped reservations (decision 0064) before the allocator would; a corrupt
-    /// or truncated archive, not a coding bug.
+    /// A count or length claims more than the archive file holds: a corrupt or truncated archive.
     Corrupt(String),
 }
 
@@ -138,7 +105,6 @@ impl From<io::Error> for Error {
 
 type Result<T> = std::result::Result<T, Error>;
 
-/// Reinterpret a byte buffer (length a multiple of 4) as a `Vec<u32>` (little-endian) for table decrypt.
 fn to_u32s(bytes: &[u8]) -> Vec<u32> {
     bytes
         .as_chunks::<4>()
@@ -148,40 +114,30 @@ fn to_u32s(bytes: &[u8]) -> Vec<u32> {
         .collect()
 }
 
-/// Bytes actually available in the archive file from `pos` to EOF, clamped into `usize`. Table counts
-/// and sector lengths are attacker-controllable header/block-table values (decision 0064); every
-/// reservation sized from one of them is capped against this, so a lying value reserves at most the
-/// archive's own size and the mismatch surfaces as a clean [`Error::Corrupt`], never an allocator abort.
+/// Bytes from `pos` to EOF, saturating: the cap for every reservation sized from a header value.
 fn avail_from(file_len: u64, pos: u64) -> usize {
     usize::try_from(file_len.saturating_sub(pos)).unwrap_or(usize::MAX)
 }
 
 impl Archive {
-    /// Open and index an archive: find the header, then read+decrypt the hash and block tables. The
-    /// file handle used here is dropped on return; reads reopen their own.
+    /// Open an archive: find the header, then read and decrypt the hash and block tables.
     pub fn open(path: impl AsRef<Path>) -> Result<Self> {
         let path = path.as_ref().to_path_buf();
         let mut file = File::open(&path)?;
         let file_len = file.metadata()?.len();
 
-        // Find the header. Vanilla archives put it at 0, but the format allows a user-data header
-        // first, so scan 512-aligned boundaries for the `MPQ\x1A` signature (resolving `MPQ\x1B`).
         let archive_offset = find_header(&mut file, file_len)?;
 
-        // Read the 32-byte V1 header prefix (V2/V3/V4 only extend it; the V1 fields are all we need —
-        // every real table offset fits in u32, so the V2 hi-block table is irrelevant here).
+        // The 32-byte V1 header: later versions only extend it, and every 1.12 table offset fits
+        // a `u32`, so the V2 hi-block table is never needed.
         file.seek(SeekFrom::Start(archive_offset))?;
         let mut hdr = [0u8; 32];
         file.read_exact(&mut hdr)?;
-        // Every field below is a fixed offset within a buffer that was just `read_exact`'d to exactly
-        // 32 bytes, so `u16_at`/`u32_at` can only return `None` if that invariant is somehow broken —
-        // map it to `Error::NotMpq` (a header we can't decode isn't a valid one) rather than trust it.
         let signature = hdr.u32_at(0).ok_or(Error::NotMpq)?;
         debug_assert_eq!(signature, SIGNATURE);
         let block_size_shift = hdr.u16_at(14).ok_or(Error::NotMpq)?;
-        // The shift is a raw header u16: unchecked, a corrupt value ≥ 55 overflows the `usize`
-        // shift (a panic in debug, a masked shift in release — both wrong). 23 (512 B << 23 = 4 GiB
-        // sectors) is already far beyond any real archive (1.12 data uses 3 → 4 KiB sectors).
+        // A raw header `u16`, capped before `512 << shift` can overflow; 1.12 data uses 3 (4 KiB
+        // sectors), and 23 is already 4 GiB.
         if block_size_shift > 23 {
             return Err(Error::Corrupt(format!(
                 "block size shift {block_size_shift} exceeds the sanity cap"
@@ -217,20 +173,17 @@ impl Archive {
         })
     }
 
-    /// Whether the archive holds `name` (case-insensitive; `/` and `\` equivalent). No I/O.
+    /// Whether the archive holds `name`, case-insensitive with `/` and `\` alike. No I/O.
     pub fn contains(&self, name: &str) -> bool {
         self.index.find(name).is_some()
     }
 
-    /// The uncompressed size of `name`, if present. No I/O (read from the block table).
+    /// The uncompressed size of `name`, from the block table.
     pub fn file_size(&self, name: &str) -> Option<u32> {
         self.index.find(name).map(|b| b.file_size)
     }
 
-    /// Whether `name`'s entry is a **delete-marker** (a patch tombstone) rather than a readable file.
-    /// [`Archive::contains`] is still `true` for one (the hash entry exists); the chain walker calls
-    /// this to tell "the client deleted this path" (stop, don't fall through) from "readable file"
-    /// (decision 0246). No I/O.
+    /// Whether `name` is a delete marker: a chain walker stops there instead of falling through.
     pub fn is_delete_marker(&self, name: &str) -> bool {
         self.index
             .find(name)
@@ -242,8 +195,7 @@ impl Archive {
         &self.index.path
     }
 
-    /// Read and decompress a file by its internal path. `/` or `\`; case-insensitive. `&self`: opens a
-    /// fresh OS handle, so concurrent reads need no lock.
+    /// Read and decompress a file by its internal path (`/` or `\`, case-insensitive).
     pub fn read_file(&self, name: &str) -> Result<Vec<u8>> {
         let idx = &self.index;
         let block = idx.find(name).ok_or_else(|| Error::NotFound(name.into()))?;
@@ -251,13 +203,11 @@ impl Archive {
         if block.flags & FLAG_EXISTS == 0 {
             return Err(Error::NotFound(name.into()));
         }
-        // A delete-marker is a tombstone, not a file: `size == 0` with no data. Reading it as a
-        // stored 0-byte file would hand back an empty buffer that looks like a real (empty) file —
-        // the silent mislead of 0246. It is "not found" (the composite deleted this path).
+        // A delete marker is not an empty file: the composite deleted this path.
         if block.flags & FLAG_DELETE_MARKER != 0 {
             return Err(Error::NotFound(name.into()));
         }
-        // The verified 1.12.1 envelope: no encrypted files, no single-unit. Refuse rather than guess.
+        // Outside the 1.12.1 envelope: refuse rather than guess.
         if block.flags & FLAG_ENCRYPTED != 0 {
             return Err(Error::Unsupported(format!("encrypted file {name}")));
         }
@@ -271,25 +221,24 @@ impl Archive {
         let compressed = block.flags & (FLAG_COMPRESS | FLAG_IMPLODE) != 0;
         let implode_only = block.flags & FLAG_IMPLODE != 0 && block.flags & FLAG_COMPRESS == 0;
 
+        let file_len = file.metadata()?.len();
+        let avail = avail_from(file_len, file_pos);
+
         if !compressed {
-            // Stored: raw bytes, exactly file_size.
+            // Stored: exactly `file_size` raw bytes, refused up front if the file cannot hold them.
+            if capped(file_size, 1, avail) < file_size {
+                return Err(Error::Corrupt(format!(
+                    "{name}: stored size ({file_size}) larger than the archive"
+                )));
+            }
             file.seek(SeekFrom::Start(file_pos))?;
-            let mut out = vec![0u8; file_size];
+            let mut out = vec![0u8; file_size]; // proven <= avail above
             file.read_exact(&mut out)?;
             return Ok(out);
         }
 
-        // Sectored read. The offset table is `sector_count + 1` u32s at file_pos; sector offsets are
-        // absolute from file_pos, so a SECTOR_CRC table (present only on the patch archives) sits
-        // between the offset table and the first sector and is skipped for free.
-        //
-        // `file_size` (hence `sector_count`) and each sector's `comp_len` all come from the
-        // block-table entry / on-disk offset table — the same attacker-controllable-header shape as
-        // the hash/block tables (decision 0064). Cap every reservation below by what the archive file
-        // could actually hold from `file_pos` on, so a corrupt entry fails cleanly instead of the
-        // allocator aborting.
-        let file_len = file.metadata()?.len();
-        let avail = avail_from(file_len, file_pos);
+        // Sectored: `sector_count + 1` offsets at `file_pos`, measured from it, so the patch
+        // archives' SECTOR_CRC table between them and the first sector is skipped for free.
         let sector_count = file_size.div_ceil(idx.sector_size);
         let otab_len = sector_count.checked_add(1).ok_or_else(|| {
             Error::Corrupt(format!("{name}: sector count overflow ({sector_count})"))
@@ -327,22 +276,26 @@ impl Archive {
                     "{name}: sector {i} length ({comp_len}) larger than the archive"
                 )));
             }
+            // Each earlier sector yielded at most its own `want` (`decompress` is bounded), so
+            // `out.len() <= file_size` and this cannot wrap.
             let want = (file_size - out.len()).min(idx.sector_size); // last sector may be short
+            if comp_len == 0 {
+                return Err(Error::Corrupt(format!("{name}: sector {i} is empty")));
+            }
 
             file.seek(SeekFrom::Start(file_pos + start))?;
             let mut raw = vec![0u8; comp_len]; // proven <= avail above
             file.read_exact(&mut raw)?;
 
             if comp_len >= want {
-                // Not actually compressed (a sector that wouldn't shrink is stored verbatim).
+                // A sector that would not shrink is stored verbatim.
                 out.extend_from_slice(&raw[..want]);
             } else if implode_only {
-                // IMPLODE files carry no per-sector method byte. (Verified absent in 1.12.1; kept for
-                // completeness so the shape is explicit rather than a silent fall-through.)
+                // IMPLODE sectors carry no method byte; 1.12.1 data has none.
                 out.extend_from_slice(&decompress(0x08, &raw, want, name)?);
             } else {
-                // COMPRESS: leading byte is the codec mask, rest is the payload.
-                let method = raw[0];
+                // COMPRESS: the leading byte is the codec mask, the rest the payload.
+                let method = raw[0]; // non-empty: refused above
                 out.extend_from_slice(&decompress(method, &raw[1..], want, name)?);
             }
         }
@@ -377,8 +330,8 @@ impl Index {
     }
 }
 
-/// Scan 512-aligned boundaries for the MPQ header, resolving a `MPQ\x1B` user-data header to the real
-/// one it points at. Returns the byte offset of the `MPQ\x1A` header.
+/// The `MPQ\x1A` header's offset: the first 512-aligned match, or where a `MPQ\x1B` user-data
+/// header points.
 fn find_header(file: &mut File, file_len: u64) -> Result<u64> {
     let mut off = 0u64;
     while off + 4 <= file_len {
@@ -390,7 +343,7 @@ fn find_header(file: &mut File, file_len: u64) -> Result<u64> {
         match u32::from_le_bytes(sig) {
             SIGNATURE => return Ok(off),
             USERDATA_SIGNATURE => {
-                // user-data header: u32 sig, u32 user_data_size, u32 header_offset (relative to here).
+                // User-data header: u32 sig, u32 user_data_size, u32 header_offset from here.
                 let mut rest = [0u8; 8];
                 file.read_exact(&mut rest)?;
                 let header_offset = u32::from_le_bytes([rest[4], rest[5], rest[6], rest[7]]) as u64;
@@ -409,10 +362,7 @@ fn read_hash_table(
     count: usize,
     file_len: u64,
 ) -> Result<Vec<HashEntry>> {
-    // `count` is a header u32 (decision 0064): cap the reservation by what the archive could actually
-    // hold from `pos` on, so a lying header can at worst reserve the file's own size. If the capped
-    // reservation had to shrink below `count`, the header is lying (or the file is truncated) — fail
-    // cleanly here rather than let the entry-building loop below index past a short `words`.
+    // A `count` the file cannot hold is refused before the loop indexes past a short `words`.
     let avail = avail_from(file_len, pos);
     let cap = capped(count, 16, avail);
     if cap < count {
@@ -420,7 +370,7 @@ fn read_hash_table(
             "hash table: header claims {count} entries, only room for {cap} in the archive"
         )));
     }
-    let mut bytes = vec![0u8; cap * 16]; // == count * 16, proven <= avail above — never a wild reserve
+    let mut bytes = vec![0u8; cap * 16]; // == count * 16, proven <= avail above
     file.seek(SeekFrom::Start(pos))?;
     file.read_exact(&mut bytes)?;
     let mut words = to_u32s(&bytes);
@@ -431,7 +381,7 @@ fn read_hash_table(
             HashEntry {
                 name_a: words[o],
                 name_b: words[o + 1],
-                // words[o+2] packs locale(u16)+platform(u16); 1.12.1 data is locale-neutral, ignore.
+                // words[o + 2] is locale and platform, unread: 1.12.1 data is locale-neutral.
                 block_index: words[o + 3],
             }
         })
@@ -444,7 +394,7 @@ fn read_block_table(
     count: usize,
     file_len: u64,
 ) -> Result<Vec<BlockEntry>> {
-    // Same treatment as `read_hash_table` above: `count` is an attacker-controllable header u32.
+    // A `count` the file cannot hold is refused, as in `read_hash_table`.
     let avail = avail_from(file_len, pos);
     let cap = capped(count, 16, avail);
     if cap < count {
@@ -465,7 +415,7 @@ fn read_block_table(
             let o = i * 4;
             BlockEntry {
                 file_pos: words[o],
-                // words[o + 1] = compressed_size on disk; unused (offset table sizes sectors).
+                // words[o + 1] is compressed_size, unread: the offset table sizes the sectors.
                 file_size: words[o + 2],
                 flags: words[o + 3],
             }
@@ -473,14 +423,15 @@ fn read_block_table(
         .collect())
 }
 
-/// Decompress one sector payload by its MPQ codec mask. 1.12.1 uses ZLIB (and store, handled by the
-/// caller); any other mask is an error so the differential pass flags it for us to add deliberately.
+/// Decompress one sector by its codec mask; 1.12.1 data uses zlib alone.
 fn decompress(method: u8, data: &[u8], expected: usize, name: &str) -> Result<Vec<u8>> {
     match method {
         0x02 => {
             use flate2::read::ZlibDecoder;
             let mut out = Vec::with_capacity(expected);
+            // Bounded: a sector inflating past its slot would wrap the caller's next `want`.
             ZlibDecoder::new(data)
+                .take(expected as u64)
                 .read_to_end(&mut out)
                 .map_err(|e| Error::Decompress(format!("{name}: zlib: {e}")))?;
             Ok(out)
@@ -496,9 +447,7 @@ mod tests {
     use super::*;
     use std::sync::atomic::{AtomicU32, Ordering};
 
-    /// A unique path under the OS temp dir — no `tempfile` dependency (decision 0064 keeps the leaf
-    /// crates dependency-light), so uniqueness is hand-rolled: pid + a per-process counter, enough to
-    /// never collide across parallel `cargo test` threads in this crate.
+    /// A unique temp path (pid and a counter), so parallel tests never collide.
     fn temp_path(tag: &str) -> PathBuf {
         static COUNTER: AtomicU32 = AtomicU32::new(0);
         let n = COUNTER.fetch_add(1, Ordering::Relaxed);
@@ -510,7 +459,7 @@ mod tests {
         ))
     }
 
-    /// Build a minimal 32-byte V1 MPQ header (unused fields zeroed) at the start of a buffer.
+    /// A minimal 32-byte V1 MPQ header, unused fields zeroed.
     fn header(
         block_size_shift: u16,
         hash_table_pos: u32,
@@ -528,8 +477,7 @@ mod tests {
         h
     }
 
-    /// Write `bytes` to a fresh temp file, run `Archive::open` on it, and remove the file afterwards
-    /// regardless of the outcome.
+    /// `Archive::open` over `bytes` in a temp file, removed whatever the outcome.
     fn open_temp(tag: &str, bytes: &[u8]) -> Result<Archive> {
         let path = temp_path(tag);
         std::fs::write(&path, bytes).expect("write temp archive");
@@ -540,9 +488,7 @@ mod tests {
 
     #[test]
     fn open_rejects_hash_table_count_bigger_than_the_file() {
-        // A header claiming u32::MAX hash-table entries in a 40-byte file: pre-0064 this would have
-        // tried `vec![0u8; u32::MAX as usize * 16]` (~68 GiB) and aborted the allocator. It must now
-        // return a clean `Error::Corrupt` instead.
+        // u32::MAX hash-table entries in a 40-byte file, ~68 GiB if the reservation were uncapped.
         let hdr = header(0, 32, 32, u32::MAX, 0);
         let mut bytes = hdr.to_vec();
         bytes.extend_from_slice(&[0u8; 8]); // pad past the header so `pos` (32) is in-bounds
@@ -567,8 +513,7 @@ mod tests {
 
     #[test]
     fn open_accepts_a_valid_archive_with_empty_tables() {
-        // The boundary case the cap must not reject: zero-entry tables pointing exactly at EOF. Proves
-        // the new cap logic doesn't disturb a legitimately-shaped (if degenerate) archive.
+        // Zero-entry tables pointing exactly at EOF: the boundary the cap must not reject.
         let hdr = header(0, 32, 32, 0, 0);
         let archive =
             open_temp("empty_tables", &hdr).expect("a well-formed empty-table archive must open");
@@ -576,8 +521,7 @@ mod tests {
         assert_eq!(archive.file_size("anything"), None);
     }
 
-    /// Like [`open_temp`] but leaves the backing file on disk so [`Archive::read_file`] (which reopens
-    /// the archive by path) works; returns the path for the caller to remove.
+    /// Like [`open_temp`], but the file stays for `read_file`, which reopens it by path.
     fn open_temp_kept(tag: &str, bytes: &[u8]) -> (Archive, PathBuf) {
         let path = temp_path(tag);
         std::fs::write(&path, bytes).expect("write temp archive");
@@ -585,12 +529,15 @@ mod tests {
         (archive, path)
     }
 
-    /// Build a minimal V1 archive holding exactly one entry (`name`) with the given block `flags` and
-    /// stored `data`. Tables are encrypted with the real keys so the reader's decrypt round-trips
-    /// them — enough to exercise flag handling (delete-marker vs. a plain stored file).
+    /// A minimal V1 archive holding one stored entry, its tables encrypted with the real keys.
     fn archive_with_one_entry(name: &str, flags: u32, data: &[u8]) -> Vec<u8> {
+        archive_with_one_block(name, flags, data, data.len() as u32)
+    }
+
+    /// [`archive_with_one_entry`] with `file_size` set apart from the data: a lying block table.
+    fn archive_with_one_block(name: &str, flags: u32, data: &[u8], file_size: u32) -> Vec<u8> {
         use crypto::{encrypt_block, hash_type};
-        const HASH_SLOTS: u32 = 4; // power of two — the reader masks with len-1
+        const HASH_SLOTS: u32 = 4; // a power of two: the reader masks with len - 1
         let hash_pos = 32u32;
         let block_pos = hash_pos + HASH_SLOTS * 16;
         let data_pos = block_pos + 16; // one 16-byte block entry
@@ -601,11 +548,11 @@ mod tests {
         hash[slot * 4] = hash_string(name, hash_type::NAME_A);
         hash[slot * 4 + 1] = hash_string(name, hash_type::NAME_B);
         hash[slot * 4 + 2] = 0; // locale | platform
-        hash[slot * 4 + 3] = 0; // → block index 0
+        hash[slot * 4 + 3] = 0; // block index 0
         encrypt_block(&mut hash, hash_string("(hash table)", hash_type::FILE_KEY));
 
         // Block table (plaintext): one entry pointing at the trailing data.
-        let mut block = vec![data_pos, data.len() as u32, data.len() as u32, flags];
+        let mut block = vec![data_pos, data.len() as u32, file_size, flags];
         encrypt_block(
             &mut block,
             hash_string("(block table)", hash_type::FILE_KEY),
@@ -619,8 +566,7 @@ mod tests {
         bytes
     }
 
-    /// The builder is honest: a plain stored (EXISTS-only) entry reads its bytes back and is not a
-    /// delete-marker — so the negative result in the next test can't be a broken-archive artifact.
+    /// The control for the delete-marker test: the same builder's plain entry reads back.
     #[test]
     fn stored_entry_reads_its_bytes() {
         let (arc, path) = open_temp_kept(
@@ -633,10 +579,6 @@ mod tests {
         let _ = std::fs::remove_file(&path);
     }
 
-    /// A delete-marker (`EXISTS | DELETE_MARKER`, size 0) is a tombstone, not an empty file: it is
-    /// still `contains`ed (the hash entry exists) and flagged `is_delete_marker`, but `read_file`
-    /// refuses it with `NotFound` rather than handing back an empty buffer (decision 0246 — the silent
-    /// mislead that made the trainer arc quote a stale, deleted stock file).
     #[test]
     fn delete_marker_is_not_a_readable_empty_file() {
         let name = "Interface\\FrameXML\\ClassTrainerFrame.xml";
@@ -646,8 +588,7 @@ mod tests {
         );
         assert!(arc.contains(name), "the hash entry exists");
         assert!(arc.is_delete_marker(name), "flagged as a tombstone");
-        // The file is present on disk, so a NotFound here is the tombstone guard firing — not a
-        // missing backing file.
+        // The backing file exists, so NotFound here is the delete-marker guard.
         match arc.read_file(name) {
             Err(Error::NotFound(_)) => {}
             other => panic!("expected NotFound for a tombstone, got {other:?}"),
@@ -657,10 +598,74 @@ mod tests {
 
     #[test]
     fn avail_from_never_underflows_when_pos_exceeds_file_len() {
-        // `pos` derived from a corrupt header can point past EOF; the helper must saturate to 0
-        // rather than wrap `file_len - pos` around to a huge usize.
         assert_eq!(avail_from(10, 100), 0);
         assert_eq!(avail_from(100, 10), 90);
         assert_eq!(avail_from(0, 0), 0);
     }
+
+    /// Two equal consecutive offsets name a zero-length sector, with no codec byte to read.
+    #[test]
+    fn an_empty_sector_is_refused_not_indexed() {
+        // One 8-byte file, one sector: offsets [8, 8].
+        let mut data = Vec::new();
+        data.extend_from_slice(&8u32.to_le_bytes());
+        data.extend_from_slice(&8u32.to_le_bytes());
+        let (arc, path) = open_temp_kept(
+            "empty_sector",
+            &archive_with_one_entry("a.bin", FLAG_EXISTS | FLAG_COMPRESS, &data),
+        );
+        match arc.read_file("a.bin") {
+            Err(Error::Corrupt(_)) => {}
+            other => panic!("expected Error::Corrupt for an empty sector, got {other:?}"),
+        }
+        let _ = std::fs::remove_file(&path);
+    }
+
+    #[test]
+    fn an_over_inflating_sector_cannot_run_the_output_past_file_size() {
+        use flate2::{write::ZlibEncoder, Compression};
+        use std::io::Write;
+        // A COMPRESS sector as stored: the 0x02 (zlib) codec byte, then the stream.
+        let zlib = |raw: &[u8]| {
+            let mut e = ZlibEncoder::new(vec![0x02u8], Compression::default());
+            e.write_all(raw).unwrap();
+            e.finish().unwrap()
+        };
+        // 612 bytes: a full 512-byte sector (shift 0) and a 100-byte tail; sector 0 inflates to
+        // 1000 bytes, twice its slot.
+        let s0 = zlib(&[0u8; 1000]);
+        let s1 = zlib(&[7u8; 100]);
+        let otab_len = 12u32;
+        let mut data = Vec::new();
+        data.extend_from_slice(&otab_len.to_le_bytes());
+        data.extend_from_slice(&(otab_len + s0.len() as u32).to_le_bytes());
+        data.extend_from_slice(&(otab_len + (s0.len() + s1.len()) as u32).to_le_bytes());
+        data.extend_from_slice(&s0);
+        data.extend_from_slice(&s1);
+        let (arc, path) = open_temp_kept(
+            "over_inflate",
+            &archive_with_one_block("a.bin", FLAG_EXISTS | FLAG_COMPRESS, &data, 612),
+        );
+        let out = arc
+            .read_file("a.bin")
+            .expect("a bounded inflate reads cleanly");
+        assert_eq!(out.len(), 612);
+        assert!(out[..512].iter().all(|&b| b == 0));
+        assert!(out[512..].iter().all(|&b| b == 7));
+        let _ = std::fs::remove_file(&path);
+    }
+
+    /// `Corrupt`, not the read's `Io`, pins that the guard fires before the buffer is sized.
+    #[test]
+    fn a_stored_size_larger_than_the_archive_is_refused_before_allocating() {
+        let (arc, path) = open_temp_kept(
+            "stored_overflow",
+            &archive_with_one_block("a.txt", FLAG_EXISTS, b"hello", u32::MAX),
+        );
+        match arc.read_file("a.txt") {
+            Err(Error::Corrupt(_)) => {}
+            other => panic!("expected Error::Corrupt for a lying stored size, got {other:?}"),
+        }
+        let _ = std::fs::remove_file(&path);
+    }
 }
diff --git a/crates/benilla-protocol/Cargo.toml b/crates/benilla-protocol/Cargo.toml
index 93046597..7bc71d87 100644
--- a/crates/benilla-protocol/Cargo.toml
+++ b/crates/benilla-protocol/Cargo.toml
@@ -14,11 +14,10 @@ clap.workspace = true
 benilla-srp = { path = "../benilla-srp" }
 flate2 = "1.0"
 sha1.workspace = true
-# `SessionEventKind` — the fieldless twin of `SessionEvent`, the key the app's packet-handler
-# table dispatches on (decision 2305). A derive, so the two can never drift apart.
+# Derives `SessionEventKind`, `SessionEvent`'s fieldless twin that the handler table keys on.
 strum = { version = "0.26", features = ["derive"] }
 
 [dev-dependencies]
-# The SRP probes re-derive the handshake by hand (to vary what `benilla-srp` fixes) — examples only.
+# The SRP probe example re-derives the handshake by hand, to vary what `benilla-srp` fixes.
 num-bigint = "0.4.6"
 rand = "0.8.6"
diff --git a/crates/benilla-protocol/examples/addon_chat_probe.rs b/crates/benilla-protocol/examples/addon_chat_probe.rs
index 587a513d..f221ec21 100644
--- a/crates/benilla-protocol/examples/addon_chat_probe.rs
+++ b/crates/benilla-protocol/examples/addon_chat_probe.rs
@@ -1,37 +1,16 @@
-//! Live probe (decision 1029, B215): **what an addon broadcast actually looks like on the wire.**
-//!
-//! 1.12.1 has no addon opcode — `SendAddonMessage` rides the ordinary chat lanes and the sentinel
-//! `language = LANG_ADDON` (`0xFFFFFFFF`) is the *only* thing separating "a hunter addon telling
-//! the party its version" from "someone talking". benilla rendered whatever arrived, so a partied
-//! real-client player's Quiver ping printed as `[Party] [Soreen]: Quiver VERSION:3.1.4`. The gate
-//! that fixes it keys on that one field, so that one field had to be proved end-to-end against a
-//! live vmangos rather than argued from folk memory of the lane.
-//!
-//! What it asserts, on the reported lane (`CHAT_MSG_PARTY`) and on the other lane addon traffic
-//! commonly uses (`CHAT_MSG_CHANNEL`):
-//!
-//! - an addon send comes back out of the server with `language == LANG_ADDON` **intact** (the
-//!   relay does not normalise it away — `BuildChatPacket` is handed `Language(packet.lang)`
-//!   verbatim, `Handlers/ChatHandler.cpp:488`);
-//! - its `chat_type` is the **ordinary lane's** type byte, not some addon-specific value: there is
-//!   nothing in the type field to filter on;
-//! - the `prefix` TAB `payload` text survives byte-for-byte (addon chat skips `SanitizeChatMessage`
-//!   entirely, `ChatHandler.cpp:49`, so the tab is not stripped);
-//! - the control — a plain line on the same lane — comes back with the character's real tongue, so
-//!   a language-keyed gate cannot swallow speech.
+//! Live probe: what an addon broadcast looks like on the wire. 1.12.1 has no addon opcode;
+//! `SendAddonMessage` rides the ordinary chat lanes on their ordinary type byte, and only
+//! `language == LANG_ADDON` (`0xFFFFFFFF`) marks it. vmangos relays the language verbatim
+//! (`ChatHandler.cpp:488`) and skips `SanitizeChatMessage` for addon chat
+//! (`ChatHandler.cpp:49`), so the prefix TAB survives.
 //!
 //! Run: `cargo run -p benilla-protocol --example addon_chat_probe -- probeN pprobeN [probeM
-//! pprobeM] [host]`. With one account it runs the CHANNEL case alone (the server echoes a channel
-//! line back to its own sender, so one session is a complete round trip). With two it also runs
-//! the PARTY case, which needs a real group: the first account invites the second, the second
-//! accepts, and the addon line goes out over `/p`. **Use `probe8`/`probe9` for the second
-//! identity** — those two accounts sit above `WT_MAX_SLOTS`, so no live session's slot owns them
-//! (decision 0530's slot-keyed rule).
+//! pprobeM] [host]`. One account runs the CHANNEL case; a second adds the PARTY case, and must be
+//! an account nobody else is logged in on, since a login kicks the current holder.
 //!
-//! Server prerequisites, both checked by the probe's own output rather than assumed:
-//! `AddonChannel = 1` (off ⇒ the server silently drops every addon send) and
-//! `AllowTwoSide.Interaction.Channel = 0` (on ⇒ `Channel::Say` rewrites the language to
-//! `LANG_UNIVERSAL` and the CHANNEL case would report a false negative).
+//! Needs `AddonChannel = 1` (off drops every addon send) and
+//! `AllowTwoSide.Interaction.Channel = 0` (on, `Channel::Say` rewrites the language to
+//! `LANG_UNIVERSAL`).
 
 use std::time::{Duration, Instant};
 
@@ -42,17 +21,14 @@ use benilla_protocol::messages::{
 };
 use benilla_protocol::{ServerPacket, WorldSession, WORLD_PORT};
 
-/// The channel the CHANNEL case talks over. A custom name (not General/Trade) so the probe never
-/// touches a real channel, and so its own membership is the only membership.
+/// A private channel, so the probe's own membership is the only one.
 const PROBE_CHANNEL: &str = "benillaaddonprobe";
 
-/// The addon payload under test — the reported one, verbatim: prefix `Quiver`, TAB, the version
-/// string a real Quiver 3.1.4 broadcasts.
+/// What a real Quiver 3.1.4 broadcasts: this prefix, a TAB, then the body.
 const ADDON_PREFIX: &str = "Quiver";
 const ADDON_BODY: &str = "VERSION:3.1.4";
 
-/// The slot's probe character: `probe4` → `Probefour` (decision 0530's
-/// `probeN`/`pprobeN`/`Probe<N-spelled>` convention).
+/// The probe account's character: `probe4` plays `Probefour`.
 fn probe_char_name(user: &str) -> Option<String> {
     let n: usize = user.strip_prefix("probe")?.parse().ok()?;
     let spelled = [
@@ -63,8 +39,7 @@ fn probe_char_name(user: &str) -> Option<String> {
 }
 
 fn login(host: &str, user: &str, pass: &str) -> Result<(WorldSession, String)> {
-    let name =
-        probe_char_name(user).context("account must be a slot-keyed probeN (decision 0530)")?;
+    let name = probe_char_name(user).context("account must be a probeN")?;
     let logon = benilla_protocol::logon(host, user, pass)?;
     let addr = logon
         .realms
@@ -80,11 +55,8 @@ fn login(host: &str, user: &str, pass: &str) -> Result<(WorldSession, String)> {
     session.player_login(character.guid)?;
     session.set_active_mover(character.guid)?;
     session.set_read_timeout(Some(Duration::from_millis(200)))?;
-    // Wait for `SMSG_LOGIN_VERIFY_WORLD` before sending anything else. Every `STATUS_LOGGEDIN`
-    // opcode is dropped **silently** until `_player->IsInWorld()` (vmangos
-    // `WorldSession::ProcessPackets`, `Server/WorldSession.cpp:568-577`: no reply, no log, just
-    // `break`) — a channel join issued into the login flood vanishes, and the only symptom is a
-    // `NOT_MEMBER` on the next say, which reads like a permissions problem rather than a race.
+    // Until the player is in world the server silently drops every `STATUS_LOGGEDIN` opcode
+    // (`WorldSession.cpp:568-577`); a lost join only shows later, as `NOT_MEMBER` on the say.
     if !wait_for(&mut session, 30, |p| {
         matches!(p, ServerPacket::LoginVerifyWorld { .. })
     }) {
@@ -92,17 +64,14 @@ fn login(host: &str, user: &str, pass: &str) -> Result<(WorldSession, String)> {
             "{name} never got SMSG_LOGIN_VERIFY_WORLD — not in world, every send would be dropped"
         );
     }
-    // Start ungrouped, always. `CMSG_GROUP_DISBAND` is a no-op when we have no group (vmangos
-    // `HandleGroupDisbandOpcode` returns immediately), so this is free — and without it a run that
-    // died before its teardown leaves the character in a group forever, after which every later
-    // invite is answered `SMSG_PARTY_COMMAND_RESULT` instead of forming a party. That is a probe
-    // that fails for a reason having nothing to do with what it tests.
+    // Start ungrouped: a group left by a crashed run turns every invite into
+    // `SMSG_PARTY_COMMAND_RESULT`. Disbanding with no group is a no-op.
     session.group_disband()?;
     println!("probe: logged in {name} ({user}) — in world, ungrouped");
     Ok((session, name))
 }
 
-/// A read timeout on a quiet socket — the normal case, and the one recv error that is not news.
+/// A read timeout on a quiet socket, the one expected recv error.
 fn is_timeout(e: &anyhow::Error) -> bool {
     e.chain().any(|c| {
         c.downcast_ref::<std::io::Error>().is_some_and(|io| {
@@ -114,10 +83,7 @@ fn is_timeout(e: &anyhow::Error) -> bool {
     })
 }
 
-/// Drain until `done` says the thing we were waiting for arrived, or `secs` elapse. Every step of
-/// the setup waits on the **server's own acknowledgement** rather than a sleep: the login flood
-/// runs for seconds and a channel join issued into it is answered `NOT_MEMBER` when the say lands
-/// first — a sleep long enough to hide that is a sleep that will be too short on a loaded server.
+/// Drain until a packet satisfies `done`, or `secs` elapse.
 fn wait_for(
     session: &mut WorldSession,
     secs: u64,
@@ -152,18 +118,13 @@ struct Seen {
     text: String,
 }
 
-/// Drain `session` for up to `secs`, keeping every `SMSG_MESSAGECHAT` whose text is one of ours.
-/// Read timeouts are the normal case (a quiet socket), never an error.
-///
-/// `WOW_ADDON_PROBE_TRACE=1` names every packet that goes past — the affordance that turns "the
-/// line never arrived" into "the *join* was refused", which is the only interesting way this probe
-/// fails.
+/// Drain for `secs`, keeping each `SMSG_MESSAGECHAT` whose text is in `wanted`.
+/// `WOW_ADDON_PROBE_TRACE=1` prints every packet that goes past.
 fn collect(session: &mut WorldSession, secs: u64, wanted: &[&str]) -> Vec<Seen> {
     let trace = std::env::var("WOW_ADDON_PROBE_TRACE").is_ok();
     let mut seen = Vec::new();
     let deadline = Instant::now() + Duration::from_secs(secs);
     while Instant::now() < deadline {
-        // A recv error here is a read timeout on a quiet socket — the normal case, not news.
         let Ok(packet) = session.recv() else { continue };
         if trace {
             println!("probe:   .. {}", packet.name());
@@ -198,8 +159,8 @@ fn collect(session: &mut WorldSession, secs: u64, wanted: &[&str]) -> Vec<Seen>
     seen
 }
 
-/// Assert one lane's pair: the addon line arrives with `LANG_ADDON` on the lane's own type byte and
-/// its tab intact, and the control line arrives on the same type byte with a real tongue.
+/// Judge one lane: the addon line carries `LANG_ADDON`, the lane's own type byte and its TAB;
+/// the control line carries the same type byte and a real language.
 fn judge(lane: &str, expect_type: u8, addon_text: &str, control_text: &str, seen: &[Seen]) -> bool {
     let mut ok = true;
     let mut check = |label: &str, cond: bool| {
@@ -260,7 +221,7 @@ fn main() -> Result<()> {
         [a, b, ..] => (a.clone(), b.clone()),
         _ => bail!("{usage}"),
     };
-    // The optional second identity, then the optional host — told apart by the `probe` prefix.
+    // An optional second account, then an optional host, told apart by the `probe` prefix.
     let second = match args.get(2) {
         Some(u) if u.starts_with("probe") => Some((u.clone(), args.get(3).context(usage)?.clone())),
         _ => None,
@@ -272,15 +233,12 @@ fn main() -> Result<()> {
 
     let addon_text = format!("{ADDON_PREFIX}\t{ADDON_BODY}");
     let mut all_ok = true;
-    // The "be the other client in a running benilla's party" mode: instead of driving both sides,
-    // wait to be invited, accept, and broadcast. This is how the app-side gate is closed against
-    // the *symptom* — a benilla started with `WOW_PROBE_CHAT="/invite <this character>"` pulls the
-    // probe into its party and then has to not render what the probe says.
+    // Await-invite mode: wait to be invited, accept and broadcast, so a benilla started with
+    // `WOW_PROBE_CHAT="/invite <this character>"` gets a party member whose addon talks.
     let await_invite = std::env::var("WOW_ADDON_PROBE_AWAIT_INVITE").is_ok();
 
     // ── 1 · the CHANNEL lane, single session ──────────────────────────────────────────────────
-    // `Channel::SendToAll` (vmangos `Chat/Channel.cpp:777-785`) writes to every member INCLUDING
-    // the sender, so one account is a complete send→relay→receive round trip.
+    // `Channel::SendToAll` includes the sender (`Channel.cpp:777-785`): one session round-trips.
     let (mut a, name_a) = login(&host, &user_a, &pass_a)?;
     if await_invite {
         println!("probe: — PARTY lane — {name_a} waits to be invited (60s)");
@@ -297,8 +255,7 @@ fn main() -> Result<()> {
         let party_control = "party control line";
         a.send_addon_message(CHAT_TYPE_PARTY, None, &addon_text)?;
         a.send_chat_kind(CHAT_TYPE_PARTY, None, party_control)?;
-        // Party chat echoes to its own sender (`Group::BroadcastPacket` takes no ignore guid), so
-        // even as the talker the probe still sees the relayed wire and can judge it.
+        // Party chat echoes to its sender (`Group::BroadcastPacket` takes no ignore guid).
         let seen = collect(&mut a, 8, &[&addon_text, party_control]);
         all_ok &= judge("PARTY", CHAT_MSG_PARTY, &addon_text, party_control, &seen);
         a.group_disband()?;
@@ -331,7 +288,7 @@ fn main() -> Result<()> {
     );
     a.leave_channel(PROBE_CHANNEL)?;
 
-    // ── 2 · the PARTY lane, the reported case — needs a real group, so a second identity ──────
+    // ── 2 · the PARTY lane, two sessions ──────────────────────────────────────────────────────
     match second {
         None => println!(
             "probe: — PARTY lane — SKIPPED (pass a second probe account to run the reported case)"
@@ -346,8 +303,8 @@ fn main() -> Result<()> {
                 bail!("PARTY lane: {name_b} never saw SMSG_GROUP_INVITE — is {name_a} already grouped?");
             }
             b.group_accept()?;
-            // The group is only real once the server pushes the roster to BOTH sides; `/p` from A
-            // before A's own `SMSG_GROUP_LIST` lands is dropped by `if (!group) return`.
+            // Wait for the roster on both sides: a `/p` sent before the sender's own
+            // `SMSG_GROUP_LIST` is dropped by `if (!group) return`.
             if !wait_for(&mut b, 20, |p| matches!(p, ServerPacket::GroupList { .. })) {
                 bail!("PARTY lane: {name_b} accepted but never got SMSG_GROUP_LIST");
             }
@@ -359,8 +316,6 @@ fn main() -> Result<()> {
             let party_control = "party control line";
             a.send_addon_message(CHAT_TYPE_PARTY, None, &addon_text)?;
             a.send_chat_kind(CHAT_TYPE_PARTY, None, party_control)?;
-            // B is the *other* client — exactly the reported situation (a partied real client's
-            // addon talking at us).
             let seen = collect(&mut b, 5, &[&addon_text, party_control]);
             all_ok &= judge("PARTY", CHAT_MSG_PARTY, &addon_text, party_control, &seen);
 
diff --git a/crates/benilla-protocol/examples/cooldown_probe.rs b/crates/benilla-protocol/examples/cooldown_probe.rs
index 53333283..6764e2fc 100644
--- a/crates/benilla-protocol/examples/cooldown_probe.rs
+++ b/crates/benilla-protocol/examples/cooldown_probe.rs
@@ -1,19 +1,13 @@
-//! Diagnostic probe: measure the server's ACTUAL cooldown window for Charge (spell 100,
-//! `recoveryTime 0 / category 44 / categoryRecoveryTime 15000`) against the client-rendered
-//! 15 s sweep — the "I can charge before the indicator is up" report.
+//! Diagnostic probe: the server's cooldown window for Charge (spell 100: `recoveryTime 0`,
+//! category 44, `categoryRecoveryTime 15000`) against the client's 15 s sweep. It charges a
+//! Northshire Kobold Vermin (entry 6), then recasts every 200 ms. vmangos checks the cooldown
+//! first in `CheckCast` (`Spell.cpp:5369`), so the first result other than
+//! `SPELL_FAILED_NOT_READY` (60), or a second `SMSG_SPELL_GO`, marks the server's cooldown end
+//! relative to the first GO.
 //!
-//! Flow: log in the slot's probe warrior (`Probe<N-spelled>`), `.learn 100`, teleport into the Northshire kobold
-//! cluster, Battle Stance, pick a Kobold Vermin (entry 6) from the create stream, Charge it,
-//! then spam re-casts every 200 ms. vmangos checks the cooldown at the TOP of `CheckCast`
-//! (`Spell.cpp:5369`), so the flip from `SPELL_FAILED_NOT_READY` (60) to any other code (or a
-//! second `SMSG_SPELL_GO`) timestamps the server's cooldown end relative to the first GO.
-//!
-//! Run: `cargo run -p benilla-protocol --example cooldown_probe -- probeN pprobeN [host]` — the
-//! slot-keyed probe account (method.md "The local vmangos server"; NEVER `one`, the director's
-//! account — a probe login there kicks their live session). Two caveats: this is a COMBAT probe,
-//! so it runs director-supervised (method.md: no unattended combat probes), and `.learn` is
-//! SEC_DEVELOPER (5); probe accounts are gmlevel 6 (SEC_ADMINISTRATOR), so it lands. The vmangos
-//! console for the run and restore it after.
+//! Run: `cargo run -p benilla-protocol --example cooldown_probe -- probeN pprobeN [host]` on a
+//! probe account with a warrior (a login kicks whoever is on the account); `.learn` needs
+//! gmlevel 5 (`SEC_DEVELOPER`).
 
 use std::time::{Duration, Instant};
 
@@ -43,10 +37,10 @@ fn main() -> Result<()> {
     let mut args = std::env::args().skip(1);
     let user = args
         .next()
-        .context("usage: cooldown_probe -- <probeN> <pprobeN> [host] (slot-keyed account)")?;
+        .context("usage: cooldown_probe -- <probeN> <pprobeN> [host] (a probe account)")?;
     let pass = args
         .next()
-        .context("usage: cooldown_probe -- <probeN> <pprobeN> [host] (slot-keyed account)")?;
+        .context("usage: cooldown_probe -- <probeN> <pprobeN> [host] (a probe account)")?;
     let host = args.next().unwrap_or_else(|| "localhost".into());
 
     let logon = benilla_protocol::logon(&host, &user, &pass)?;
@@ -107,7 +101,7 @@ fn main() -> Result<()> {
         _ => {}
     };
 
-    // World-enter settle, then arm the character: learn Charge, stance, teleport to the kobolds.
+    // Let the world-enter flood settle first.
     drain(&mut session, &mut kobolds, 3.0, &mut quiet)?;
     session.set_selection(self_guid)?;
     session.send_chat(".learn 100")?;
@@ -137,8 +131,7 @@ fn main() -> Result<()> {
         println!("charging kobold {guid:#x}…");
         session.set_selection(guid)?;
         session.cast_spell(CHARGE, Some(guid))?;
-        // The anchor is stamped INSIDE the watch, at GO decode — the drain window runs its full
-        // length regardless, and a window-end stamp would smear the anchor by up to 1.5 s.
+        // Stamp the anchor at GO decode: the drain runs its full 1.5 s regardless.
         let mut verdict: Option<(bool, Instant)> = None;
         let mut watch = |_t: f64, ev: SessionEvent| match ev {
             SessionEvent::SpellGo {
diff --git a/crates/benilla-protocol/examples/faction_probe.rs b/crates/benilla-protocol/examples/faction_probe.rs
index 49f55137..3c1f9632 100644
--- a/crates/benilla-protocol/examples/faction_probe.rs
+++ b/crates/benilla-protocol/examples/faction_probe.rs
@@ -1,11 +1,8 @@
-//! Diagnostic probe: stream object creates and print each unit's decoded
-//! `UNIT_FIELD_FACTIONTEMPLATE` (+ level/display id as sanity anchors), to check the descriptor
-//! decode against the server DB's `creature_template.faction`.
+//! Diagnostic probe: prints each streamed unit's `UNIT_FIELD_FACTIONTEMPLATE`, with level and
+//! display id, to check the descriptor decode against `creature_template.faction`.
 //!
-//! Run: `cargo run -p benilla-protocol --example faction_probe -- probeN pprobeN [host]`
-//! — the slot-keyed probe account (method.md "The local vmangos server"). The account is a
-//! REQUIRED arg with no default: a default was once `one`, the director's account, where a
-//! probe login kicks their live session (decision 0530).
+//! Run: `cargo run -p benilla-protocol --example faction_probe -- probeN pprobeN [host]`. The
+//! account has no default, because a login kicks whoever is on the account.
 
 use std::time::{Duration, Instant};
 
@@ -16,10 +13,10 @@ fn main() -> Result<()> {
     let mut args = std::env::args().skip(1);
     let user = args
         .next()
-        .context("usage: faction_probe -- <probeN> <pprobeN> [host] (slot-keyed account)")?;
+        .context("usage: faction_probe -- <probeN> <pprobeN> [host] (a probe account)")?;
     let pass = args
         .next()
-        .context("usage: faction_probe -- <probeN> <pprobeN> [host] (slot-keyed account)")?;
+        .context("usage: faction_probe -- <probeN> <pprobeN> [host] (a probe account)")?;
     let host = args.next().unwrap_or_else(|| "localhost".into());
 
     let logon = benilla_protocol::logon(&host, &user, &pass)?;
diff --git a/crates/benilla-protocol/examples/horde_chat_probe.rs b/crates/benilla-protocol/examples/horde_chat_probe.rs
index 0e72ffd4..f8beb134 100644
--- a/crates/benilla-protocol/examples/horde_chat_probe.rs
+++ b/crates/benilla-protocol/examples/horde_chat_probe.rs
@@ -1,19 +1,16 @@
-//! Live probe: verify the faction-language mechanism end-to-end against the local vmangos — a
-//! HORDE character's say must echo back (the server accepted the tongue), a dot-command must
-//! answer (it survived the pre-parse `KnowsLanguage` gate), and the split-writer path must carry
-//! the tongue too. Run: `cargo run -p benilla-protocol --example horde_chat_probe -- probeN
-//! pprobeN [host]` — the slot-keyed probe account (method.md "The local vmangos server"; it
-//! once hardcoded the retired shared `three` identity, decision 0530). Creates the orc
-//! `Orc<N-spelled>` on this account on first run (names are realm-unique, so the orc keys to
-//! the slot too). Exists because a hardcoded-Common send silently ate every Horde character's
-//! chat and commands (decision 0392) — this is the one-shot regression check for that whole path.
+//! Live probe: a Horde character's chat reaches vmangos in its own language. A say must echo
+//! back, a dot-command must answer (it passes the pre-parse `KnowsLanguage` gate), and the split
+//! writer must carry the language too. The server drops a say in a language the character does
+//! not know, answering only `SMSG_NOTIFICATION`.
+//!
+//! Run: `cargo run -p benilla-protocol --example horde_chat_probe -- probeN pprobeN [host]`.
+//! Creates the orc `Orc<N-spelled>` on the account on first run.
 
 use anyhow::{bail, Context, Result};
 use benilla_protocol::messages::{CharCreateReq, CHAR_CREATE_NAME_IN_USE, CHAR_CREATE_SUCCESS};
 use benilla_protocol::{ServerPacket, WorldSession, WORLD_PORT};
 
-/// The slot's Horde character name: `probe4` → `Orcfour` (letters only — digits are not legal
-/// in character names, and realm-wide name uniqueness means each slot needs its own orc).
+/// The account's orc: `probe4` plays `Orcfour`. Names are letters only and realm-unique.
 fn orc_name(user: &str) -> Option<String> {
     let n: usize = user.strip_prefix("probe")?.parse().ok()?;
     let spelled = [
@@ -27,13 +24,12 @@ fn main() -> Result<()> {
     let mut args = std::env::args().skip(1);
     let user = args
         .next()
-        .context("usage: horde_chat_probe -- <probeN> <pprobeN> [host] (slot-keyed account)")?;
+        .context("usage: horde_chat_probe -- <probeN> <pprobeN> [host] (a probe account)")?;
     let pass = args
         .next()
-        .context("usage: horde_chat_probe -- <probeN> <pprobeN> [host] (slot-keyed account)")?;
+        .context("usage: horde_chat_probe -- <probeN> <pprobeN> [host] (a probe account)")?;
     let host = args.next().unwrap_or_else(|| "localhost".into());
-    let orc = orc_name(&user)
-        .context("account must be a slot-keyed probeN (method.md \"The local vmangos server\")")?;
+    let orc = orc_name(&user).context("account must be a probeN (the `probe` skill)")?;
 
     let logon = benilla_protocol::logon(&host, &user, &pass)?;
     let addr = logon
@@ -45,7 +41,7 @@ fn main() -> Result<()> {
 
     let mut characters = session.char_enum()?;
     if !characters.iter().any(|c| c.name == orc) {
-        // Orc (race 2) warrior male — the Horde case under test.
+        // Race 2 orc, class 1 warrior, gender 0 male.
         let req = CharCreateReq {
             name: orc.clone(),
             race: 2,
@@ -71,11 +67,9 @@ fn main() -> Result<()> {
     session.player_login(orc.guid)?;
     session.set_active_mover(orc.guid)?;
 
-    // 1. A plain say must be ACCEPTED: the server echoes our own say back (own sends are never
-    //    locally echoed in vanilla). Pre-fix, a Horde say sent Common and the server dropped it
-    //    with only an SMSG_NOTIFICATION.
+    // 1. An accepted say comes back from the server; the 1.12 client never echoes it locally.
     session.send_chat("orcish probe line")?;
-    // 2. A dot-command must survive the language gate: `.gps` answers with system messages.
+    // 2. A dot-command passes the language gate: `.gps` answers with system messages.
     session.send_chat(".gps")?;
 
     let mut say_echoed = false;
@@ -93,8 +87,7 @@ fn main() -> Result<()> {
                     say_echoed = true;
                     println!("probe: SAY ECHOED (language {})", m.language);
                 }
-                // CHAT_MSG_SYSTEM = 0x0a on the inbound u8 field. Only the `.gps` answer counts
-                // (the login MOTD is also SYSTEM — it must not satisfy the command check).
+                // `CHAT_MSG_SYSTEM` is 0x0a; the text check skips the login MOTD, also SYSTEM.
                 if m.chat_type == 0x0a && m.text.contains("Map:") {
                     system_reply = true;
                     println!("probe: .gps REPLY: {:?}", m.text);
@@ -109,8 +102,7 @@ fn main() -> Result<()> {
         }
     }
 
-    // 3. The same through the SPLIT writer — the path the benilla app actually sends on
-    //    (`into_split` must carry the tongue across).
+    // 3. The same through the split writer the app sends on; `into_split` keeps the language.
     let (mut reader, mut writer) = session.into_split()?;
     writer.send_chat("orcish writer line")?;
     let mut writer_echoed = false;
diff --git a/crates/benilla-protocol/examples/login_refusal_probe.rs b/crates/benilla-protocol/examples/login_refusal_probe.rs
index 250afd6d..9ca7a0af 100644
--- a/crates/benilla-protocol/examples/login_refusal_probe.rs
+++ b/crates/benilla-protocol/examples/login_refusal_probe.rs
@@ -1,30 +1,17 @@
-//! Live probe: what a **refused character login** actually looks like on the wire, and what it
-//! leaves behind.
+//! Live probe: what a refused character login looks like on the wire, and what it leaves. It
+//! checks that `SMSG_CHARACTER_LOGIN_FAILED` (0x41) arrives with result `1`
+//! (`HandlePlayerLoginOpcode`), which the 1.12 client reads as `CHAR_LOGIN_NO_WORLD` ("World
+//! server is down"); that the session stays `STATUS_AUTHED` and still serves `CMSG_CHAR_ENUM`;
+//! and that a valid pick then works on the same socket.
 //!
-//! benilla used to send `CMSG_PLAYER_LOGIN` and declare itself in the world in the same breath, so
-//! `SMSG_CHARACTER_LOGIN_FAILED` (0x41) reached nothing — a refusal left the client on a loading
-//! screen that could never clear. The fix rests on three facts about the server, and this pins all
-//! three against the local vmangos:
-//!
-//! 1. the refusal **arrives**, with its result byte — vmangos sends a bare `1`
-//!    (`WorldSession::HandlePlayerLoginOpcode`'s `loginFailedPacket->result = 1`), which the
-//!    reference's table reads as `CHAR_LOGIN_NO_WORLD`, "World server is down";
-//! 2. the **session survives** it — still `STATUS_AUTHED`, still able to serve `CMSG_CHAR_ENUM`;
-//! 3. a **second, valid pick still works** on the same socket, so a refusal costs the player a
-//!    click and not a reconnect.
-//!
-//! The refusal is provoked by the one guard that needs no server state: `!packet.guid.IsPlayer()`.
-//! A creature-typed guid is refused immediately and touches nothing else.
-//!
-//! Needs the local vmangos up; account `two`/`ptwo` (the account-X/password-pX convention).
+//! A creature guid trips the stateless `!packet.guid.IsPlayer()` guard. Needs the local vmangos
+//! and account `two`/`ptwo`.
 
 use std::time::Duration;
 
 use benilla_protocol::{logon, messages::ServerPacket, WorldSession, WORLD_PORT};
 
-/// A guid the server cannot read as a player: vmangos's `ObjectGuid::IsPlayer()` tests the high
-/// type nibble, and `0xF130…` is `HIGHGUID_UNIT`. Nothing on the server is looked up by it — the
-/// guard rejects before any lookup — so the probe cannot disturb a real character.
+/// A `HIGHGUID_UNIT` guid (`0xF130…`): `ObjectGuid::IsPlayer()` rejects it before any lookup.
 const NOT_A_PLAYER: u64 = 0xF130_0000_0000_0001;
 
 fn connect(user: &str, pass: &str) -> anyhow::Result<WorldSession> {
diff --git a/crates/benilla-protocol/examples/make_account.rs b/crates/benilla-protocol/examples/make_account.rs
index 442c7052..998db832 100644
--- a/crates/benilla-protocol/examples/make_account.rs
+++ b/crates/benilla-protocol/examples/make_account.rs
@@ -1,6 +1,5 @@
-//! Dev helper: print SQL to create a vmangos account, computing the SRP6 verifier/salt with
-//! `benilla-srp`. vmangos stores `v`/`s` as big-endian hex, while we compute
-//! little-endian, so we reverse. Usage:
+//! Dev helper: prints the SQL that creates a vmangos account, with the SRP6 verifier and salt
+//! from `benilla-srp`. vmangos stores `v` and `s` as big-endian hex; we compute little-endian.
 //!
 //! ```text
 //! cargo run -p benilla-protocol --example make_account -- <user> <pass> \
diff --git a/crates/benilla-protocol/examples/park_probe.rs b/crates/benilla-protocol/examples/park_probe.rs
index f6ca599b..3badbb46 100644
--- a/crates/benilla-protocol/examples/park_probe.rs
+++ b/crates/benilla-protocol/examples/park_probe.rs
@@ -1,12 +1,8 @@
-//! Live probe (decision 0193): the character-select park behaviors benilla's glue layer rests on.
+//! Live probe: the character-select park behaviours the glue screens rely on. A logout ends in
+//! `SMSG_LOGOUT_COMPLETE` and a reconnect re-serves the roster; a socket parked at character
+//! select for 130 s still logs in, since vmangos does not kick a quiet authenticated socket.
 //!
-//! 1) the logout round-trip — login, logout, confirm `SMSG_LOGOUT_COMPLETE`, reconnect, confirm
-//!    the roster re-serves (the app's drop-and-reconnect relist);
-//! 2) idle tolerance — park an authenticated socket at character select for 130 s, then log in
-//!    (verified 2026-07-07: vmangos does NOT kick a quiet parked socket, so the glue screen needs
-//!    no keep-alive ping).
-//!
-//! Needs the local vmangos up; account `two`/`ptwo` (the account-X/password-pX convention).
+//! Needs the local vmangos and account `two`/`ptwo`.
 
 use std::time::Duration;
 
@@ -42,7 +38,7 @@ fn main() -> anyhow::Result<()> {
     println!("PASS: SMSG_LOGOUT_COMPLETE received");
     drop(s);
 
-    // Fresh cycle re-serves the roster (the app's drop-and-reconnect relist).
+    // A fresh connection re-serves the roster, as the app's relist does.
     let mut s = connect(user, pass)?;
     let n = s.char_enum()?.len();
     println!("PASS: post-logout reconnect roster has {n} chars");
@@ -55,7 +51,7 @@ fn main() -> anyhow::Result<()> {
     std::thread::sleep(Duration::from_secs(130));
     match s.player_login(chars[0].guid).and_then(|()| {
         s.set_active_mover(chars[0].guid)?;
-        // Prove the world actually streams: wait for any post-login packet.
+        // Any post-login packet shows the world streams.
         s.set_read_timeout(Some(Duration::from_secs(5)))?;
         s.recv().map(|p| p.name())
     }) {
diff --git a/crates/benilla-protocol/examples/seed_classes.rs b/crates/benilla-protocol/examples/seed_classes.rs
index 0a95279b..2ef3dd60 100644
--- a/crates/benilla-protocol/examples/seed_classes.rs
+++ b/crates/benilla-protocol/examples/seed_classes.rs
@@ -1,71 +1,44 @@
-//! Dev helper: put an account into the standard **full class set** — one character of every vanilla
-//! class, optionally levelled, geared, specced and parked in its own capital. Headless: a bare
-//! `WorldSession`, no Bevy app and no window, so one process dresses a whole nine-body account.
+//! Dev helper: gives an account one character of every class, optionally levelled, geared,
+//! specced and parked in its capital, over a headless `WorldSession`.
 //!
 //! ```text
 //! cargo run -p benilla-protocol --example seed_classes -- <user> <pass> <Prefix> [flags]
-//!   --wipe            delete EVERY existing character on the account first (see the warning below)
+//!   --wipe            delete every character on the account first, irreversibly
 //!   --level <n>       `.character level n` + `.learn all_myclass` (all class spells + talents)
 //!   --tier <t>        `.character premade gear <role>-<t>` + `.character premade spec <spec>`;
 //!                     `<t>` is `phase6-bis` (Naxx BiS), `preraid-bis`, or `r14` (rank-14 PvP
-//!                     kit, custom templates 901–909 — decision 0825), role is per class below
+//!                     kit, custom templates 901–909), role is per class below
 //!   --home            `.tele` each body to its own race's capital
 //!   --spread <a|b>    which race spread to use (default `a`)
-//!   --reload-templates  make the server re-read the premade tables before dressing (see below)
+//!   --reload-templates  make the server re-read the premade tables before dressing
 //!   --host <h>        default `localhost`
 //!
-//! # the director's two accounts, rebuilt as geared 60s:
 //! … -- one pone One --wipe --level 60 --tier phase6-bis --home --spread a
-//! … -- two ptwo Two --wipe --level 60 --tier phase6-bis --home --spread b
 //! ```
 //!
-//! Without `--wipe` it is idempotent **by class** — classes the account already has are skipped — so
-//! it tops an account up to the full nine. Creating characters needs no GM level; the state flags do,
-//! and that is where this silently half-applies if the account is short: **`.character premade
-//! gear|spec` needs gmlevel 4 and `--level`'s two commands need 5**, and that level lives in
-//! `realmd.account_access`, *not* `account.gmlevel` (see method.md, "The local vmangos server").
-//! Every server reply is echoed as `server says — …`, so a refusal is visible rather than silent.
+//! Without `--wipe` it skips classes the account already has. Creating needs no GM level;
+//! `.character premade gear|spec` needs 4 and `--level` needs 5, read from
+//! `realmd.account_access`, not `account.gmlevel`. Both factions on one account need
+//! `AllowTwoSide.Accounts = 1`, or a Horde create fails `CHAR_CREATE_PVP_TEAMS_VIOLATION` (0x33).
 //!
-//! **`--wipe` deletes characters irreversibly, hand-made ones included.** It is deliberately not the
-//! default, and it names each body and its level as it goes. Both factions on one account needs
-//! `AllowTwoSide.Accounts = 1` in mangosd.conf — otherwise the Horde creates (shaman is Horde-only)
-//! come back `CHAR_CREATE_PVP_TEAMS_VIOLATION` (0x33).
+//! Dressing is not idempotent: `.character premade gear` adds a fresh copy of the set on every
+//! run, so re-dress only behind `--wipe`. `.learn all_myclass` also grants a Horde mage the
+//! ungated Alliance city teleports, so a Horde mage ends on 74 spells and an Alliance one on 68.
 //!
-//! Spell counts do **not** match across two accounts' same-class bodies, and that is not a
-//! half-applied `.learn all_myclass`: an Alliance mage ends on 68 spells and a Horde one on 74,
-//! because the command grants every spell the class *can* learn and the Alliance city
-//! teleports/portals carry no gate that stops a Horde mage — so the Horde body collects all twelve
-//! while the Alliance body gets only its own six. Each still has its own faction's full set.
-//!
-//! **Creating is idempotent; dressing is NOT.** `.character premade gear` *adds* a fresh copy of the
-//! set every time it runs — it does not diff against what is worn. Dress an already-dressed body and
-//! the second set lands in its bags, and any slot whose first-pass item is still equipped keeps the
-//! duplicate in the backpack instead: observed as a warrior left with an empty finger2 and ten spare
-//! epics, because both rings wanted finger1. So re-dress only behind `--wipe`; to fix a body that was
-//! dressed twice, wipe and rebuild it rather than unpicking the bags.
-//!
-//! **`--reload-templates`:** the world server caches the premade tables at startup and has no
-//! reload command, so a template edited in the DB is invisible to `.character premade gear` until
-//! the next restart. `.character premade savegear <name>` re-reads them all as a side effect
-//! (`CharacterCommands.cpp` → `LoadPlayerPremadeTemplates`; decision 0818's in-band trick), so this
-//! flag sends `.character premade savegear zz-seed-reload` as the first command of the first body
-//! dressed. The junk template it saves (the naked just-created body) is inert — no role a bot would
-//! pick, self-naming, safe to leave or delete from `player_premade_item_template` later.
+//! The server caches the premade tables at startup with no reload command, but
+//! `.character premade savegear <name>` re-reads them (`LoadPlayerPremadeTemplates`), so
+//! `--reload-templates` saves an inert `zz-seed-reload` template before the first dressing.
 
 use std::time::{Duration, Instant};
 
 use anyhow::{bail, Context, Result};
 use benilla_protocol::{logon, messages, ServerPacket, WorldSession, WORLD_PORT};
 
-/// `CHAT_MSG_SYSTEM` on the inbound `SMSG_MESSAGECHAT` type byte — every dot-command's
-/// success/refusal text arrives as one of these.
+/// The inbound `SMSG_MESSAGECHAT` type byte every dot-command reply arrives on.
 const CHAT_MSG_SYSTEM: u8 = 0x0a;
 
-/// Per class: the premade templates that make a level-60 body of that class make sense. `role` joins
-/// the `--tier` (`dps` + `phase6-bis` → `dps-phase6-bis`, a `player_premade_item_template.name`);
-/// `spec` is a verbatim `player_premade_spell_template.name` (specs carry no tier suffix — there is
-/// one per role at 60). Every name here was read off this deploy's world DB, and the roles spread
-/// plate/mail/cloth and tank/heal/dps across the nine rather than making nine damage dealers.
+/// Per class: the gear role, joined to `--tier` into a `player_premade_item_template.name`
+/// (`dps-phase6-bis`), and a verbatim `player_premade_spell_template.name`, which has no tier.
 const CLASSES: [(u8, &str, &str, &str); 9] = [
     // class, name, gear role, spec template
     (1, "warrior", "dps", "fury-dw-pve"),
@@ -79,10 +52,8 @@ const CLASSES: [(u8, &str, &str, &str); 9] = [
     (11, "druid", "tank", "feral-bear-pve"),
 ];
 
-/// `(race, gender)` per class, indexed to match [`CLASSES`]. Two spreads exist so two accounts can
-/// hold **eighteen distinct** race/class/gender bodies instead of the same nine twice; each spread on
-/// its own still covers all eight races, and every pair is a legal 1.12 combination (paladin is
-/// Human/Dwarf only, shaman Orc/Tauren/Troll, druid Night Elf/Tauren).
+/// `(race, gender)` per class, indexed like [`CLASSES`]; each spread covers all eight races in
+/// legal 1.12 pairs (paladin Human/Dwarf, shaman Orc/Tauren/Troll, druid Night Elf/Tauren).
 const SPREAD_A: [(u8, u8); 9] = [
     (1, 0), // human warrior
     (3, 0), // dwarf paladin
@@ -95,7 +66,7 @@ const SPREAD_A: [(u8, u8); 9] = [
     (6, 0), // tauren druid
 ];
 
-/// The second spread — no race/class pair shared with [`SPREAD_A`].
+/// The second spread, sharing no race/class pair with [`SPREAD_A`].
 const SPREAD_B: [(u8, u8); 9] = [
     (3, 0), // dwarf warrior
     (1, 0), // human paladin
@@ -108,8 +79,7 @@ const SPREAD_B: [(u8, u8); 9] = [
     (4, 1), // night elf druid
 ];
 
-/// Race id → (display name, the `game_tele` name of its capital). Gnomes ride with the dwarves:
-/// Gnomeregan is a dungeon, and `game_tele` has no gnome capital row.
+/// Race id → (display name, `game_tele` capital); gnomes have no capital row and use Ironforge.
 fn race_info(id: u8) -> Option<(&'static str, &'static str)> {
     Some(match id {
         1 => ("Human", "Stormwind"),
@@ -191,11 +161,7 @@ fn connect(o: &Opts) -> Result<WorldSession> {
     WorldSession::connect(&addr, &o.user, l.session_key)
 }
 
-/// Read inbound packets for `window`, echoing every system-chat line — the server's own
-/// success/refusal text for a dot-command, and the only thing separating a command that worked from
-/// one that was silently refused. A read-timeout tick is the expected quiet case rather than an
-/// error (the convention [`WorldSession::logout`]'s own poll loop uses), so draining runs to the
-/// deadline either way.
+/// Read for `window`, printing every system-chat line, the server's reply to a dot-command.
 fn drain(s: &mut WorldSession, window: Duration) {
     let deadline = Instant::now() + window;
     while Instant::now() < deadline {
@@ -212,8 +178,7 @@ fn main() -> Result<()> {
     let mut s = connect(&o)?;
 
     // ── 1 · wipe ──
-    // Blocking reads for the whole character-select phase: char_enum/create/delete each loop on
-    // `recv` until their own reply lands, so a read timeout here surfaces as a hard error.
+    // Blocking reads: enum, create and delete loop on `recv`, where a read timeout is an error.
     s.set_read_timeout(None)?;
     let have = s.char_enum()?;
     println!("account {}: {} existing character(s)", o.user, have.len());
@@ -266,10 +231,8 @@ fn main() -> Result<()> {
     }
 
     // ── 3 · dress each body ──
-    // The re-enum is load-bearing, not a formality: `player_login` takes each character's chat
-    // tongue from the roster it last saw, and vmangos DROPS chat — dot-commands included — spoken in
-    // a language the character doesn't know. Skip it and every Horde body's commands vanish
-    // silently (decision 0392).
+    // Re-enum first: `player_login` takes the chat language from the last roster, and vmangos
+    // drops chat, dot-commands included, in a language the character does not know.
     let roster = s.char_enum()?;
     let mut dressed = 0usize;
     if o.level.is_some() || o.tier.is_some() || o.home {
@@ -281,14 +244,12 @@ fn main() -> Result<()> {
             let (_, capital) = race_info(o.spread[i].0).context("spread holds a known race")?;
             let mut steps = Vec::new();
             if o.reload && dressed == 0 {
-                // Must run before the first `.character premade gear` — the server's template
-                // cache predates any DB edit this seeding is meant to pick up (see module doc).
+                // Before the first `.character premade gear`, which reads the cached templates.
                 steps.push(".character premade savegear zz-seed-reload".into());
             }
             if let Some(l) = o.level {
-                // Level before gear (a premade template only levels *up*), spells after the level
-                // they belong to, and the premade spec after `all_myclass` so a real talent tree
-                // wins over its every-talent state — the order the rig established (decision 0651).
+                // Order matters: level before gear (a premade only levels up), spells after the
+                // level, and the premade spec after `all_myclass` so its talent tree wins.
                 steps.push(format!(".character level {l}"));
                 steps.push(".learn all_myclass".into());
             }
diff --git a/crates/benilla-protocol/examples/srp_encoding_probe.rs b/crates/benilla-protocol/examples/srp_encoding_probe.rs
index 23e8d1ed..4b591095 100644
--- a/crates/benilla-protocol/examples/srp_encoding_probe.rs
+++ b/crates/benilla-protocol/examples/srp_encoding_probe.rs
@@ -1,22 +1,16 @@
-//! Probe: **how does realmd feed the SRP6 big numbers to SHA-1** — fixed width, or minimal length?
-//!
-//! The 1.12.1 client hashes `A`, `B`, `K`, the salt, the `H(N)⊕H(g)` constant and `M1` at their
-//! *declared* widths, zero-padded in the high bytes (`wow-5875-re` `srp6_client_session`, byte-exact
-//! from `WoW.exe` `0x5d3650`). vmangos feeds the same values as `BigNumber`s
-//! (`SHA1::Generator::UpdateData(BigNumber const&)` → `AsByteArray()` with `minSize = 0`), which
-//! **drops high-order zero bytes**. The two agree only while no value happens to have one — and
-//! disagree, silently, when one does. cmangos is identical (`Sha1Hash::UpdateBigNumbers`).
-//!
-//! This probe forces each case against a live realmd so the disagreement is observed, not argued:
+//! Probe: whether realmd feeds the SRP6 big numbers to SHA-1 at fixed width or minimal length.
+//! The 1.12 client hashes `A`, `B`, `K`, the salt, `H(N)⊕H(g)` and `M1` at their declared
+//! widths, zero-padded in the high bytes (`0x5d3650`). vmangos hashes them as `BigNumber`s
+//! (`AsByteArray()` with `minSize = 0`), dropping high-order zero bytes, so the two disagree
+//! whenever a value has one; cmangos does the same (`Sha1Hash::UpdateBigNumbers`).
 //!
 //! ```text
 //! cargo run --release -p benilla-protocol --example srp_encoding_probe -- --user one --pass pone
 //! ```
 //!
-//! `--stress N` instead runs N ordinary handshakes at the client-faithful (fixed-width) encoding and
-//! reports the observed failure rate. realmd locks an IP out for 60 s after `WrongPass.MaxAttempts`
-//! (default 10) failures inside that window and then answers `0x08 WOW_FAIL_DB_BUSY`; the probe
-//! drains the window rather than counting the lockout as a proof failure.
+//! `--stress N` runs N ordinary fixed-width handshakes and reports the failure rate, waiting out
+//! realmd's lockout: 60 s after `WrongPass.MaxAttempts` (default 10) failures, during which it
+//! answers `0x08 WOW_FAIL_DB_BUSY`.
 
 use std::net::TcpStream;
 use std::time::Duration;
@@ -35,9 +29,9 @@ const THROTTLE_MAX: u32 = 10;
 /// How a big number is serialized into the SHA-1 stream.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum Enc {
-    /// The client's law: the value's full declared width, zero-padded in the high bytes.
+    /// The 1.12 client: the full declared width, zero-padded in the high bytes.
     Fixed,
-    /// vmangos' law: `BigNumber::AsByteArray()` — high-order zero bytes dropped.
+    /// vmangos: `BigNumber::AsByteArray()`, high-order zero bytes dropped.
     Minimal,
 }
 
@@ -73,9 +67,8 @@ fn to_fixed_le_32(v: &BigUint) -> [u8; 32] {
     out
 }
 
-/// WoW's `SHA1_Interleave` **as vmangos computes it** — all 32 bytes of `S`, no trimming
-/// (`SRP6::HashSessionKey`, `S.AsByteArray(32)`). benilla matches this today; the real client instead
-/// strips low-order zero bytes of `S` first, which is its own (separately recorded) divergence.
+/// `SHA1_Interleave` as vmangos computes it, over all 32 bytes of `S` (`SRP6::HashSessionKey`);
+/// the 1.12 client strips the low-order zero bytes of `S` first.
 fn interleave(s: &[u8; 32]) -> [u8; 40] {
     let mut even = [0u8; 16];
     let mut odd = [0u8; 16];
@@ -102,7 +95,7 @@ struct Attempt {
 }
 
 impl Attempt {
-    /// Which hashed values carry a high-order zero byte — i.e. where the two encodings differ.
+    /// The hashed values with a high-order zero byte, where the two encodings differ.
     fn short_values(&self) -> Vec<&'static str> {
         let mut v = Vec::new();
         if self.a_pub[31] == 0 {
@@ -130,7 +123,7 @@ impl Attempt {
     }
 }
 
-/// What realmd said, and — when it accepted — whose `M2` encoding its reply matches.
+/// What realmd said and, on acceptance, which encoding its `M2` matches.
 enum Outcome {
     Accepted { m2_fixed: bool, m2_minimal: bool },
     Refused(u8),
@@ -161,24 +154,22 @@ impl Outcome {
 /// What the ephemeral search is aiming for.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Want {
-    /// Whatever the first draw gives — an ordinary handshake.
+    /// Whatever the first draw gives: an ordinary handshake.
     Any,
-    /// Nothing short — the case both encodings agree on.
+    /// Nothing short: the case both encodings agree on.
     Clean,
     /// `A` with a zero high byte.
     ShortA,
     /// `K` with a zero high byte.
     ShortK,
-    /// `M1` with a zero high byte — realmd accepts, but hashes a 19-byte `M1` into its `M2`.
+    /// `M1` with a zero high byte: realmd accepts, but hashes a 19-byte `M1` into its `M2`.
     ShortM1,
-    /// `B` with a zero high byte. Not searchable: `B` is the server's, so the caller redials until
-    /// one turns up, and the ephemeral is then drawn clean so `B` is the only short value.
+    /// `B` with a zero high byte: the server's draw, so the caller redials; the rest draw clean.
     ShortB,
 }
 
 impl Want {
-    /// Does a draw of this shape satisfy the search? Every case wants exactly its own value short
-    /// and the others long, so each verdict isolates one divergence.
+    /// Each case wants exactly its own value short, so each verdict isolates one divergence.
     fn accepts(self, a_short: bool, k_short: bool, m1_short: bool) -> bool {
         match self {
             Want::Any => true,
@@ -219,7 +210,7 @@ fn compute(
         let a = BigUint::from_bytes_le(&priv_key) + BigUint::from(n.bits());
         let a_pub = to_fixed_le_32(&g.modpow(&a, &n));
 
-        // Reject on the A-shape we are not after before paying for the second modpow.
+        // Reject a wrong `A` shape before paying for the second modpow.
         let a_short = a_pub[31] == 0;
         if want != Want::Any && a_short != (want == Want::ShortA) {
             continue;
@@ -250,7 +241,7 @@ fn compute(
     None
 }
 
-/// `H( SHA1(N) XOR SHA1(g) )`, little endian — a constant for WoW's fixed `N`/`g`.
+/// `SHA1(N) XOR SHA1(g)`, little endian: a constant for the fixed `N` and `g`.
 fn xor_hash(generator: u8, large_safe_prime: &[u8; 32]) -> [u8; 20] {
     let hn = sha1(&[large_safe_prime]);
     let hg = sha1(&[&[generator]]);
@@ -261,7 +252,6 @@ fn xor_hash(generator: u8, large_safe_prime: &[u8; 32]) -> [u8; 20] {
     out
 }
 
-/// One full realmd exchange.
 fn handshake(
     host: &str,
     user: &str,
@@ -276,8 +266,7 @@ fn handshake(
     auth::write_logon_challenge(&mut s, user, BUILD).context("sending logon challenge")?;
     let reply = auth::read_challenge_reply(&mut s).context("reading logon challenge reply")?;
 
-    // `B` is not ours to choose: drop the connection — sending no proof, so realmd records nothing —
-    // and let the caller redial until the server hands one of the shape we want.
+    // A wrong-shape `B` drops the connection before any proof, so realmd records no failure.
     if want != Want::Any && (reply.server_public_key[31] == 0) != (want == Want::ShortB) {
         return Err(anyhow!("this connection's B is not the wanted shape"));
     }
@@ -300,7 +289,7 @@ fn handshake(
     Ok((attempt, outcome))
 }
 
-/// Redial until the search finds the wanted shape (`B` is the server's draw, so `ShortB` needs many).
+/// Redial until the wanted shape turns up; `ShortB` needs many, `B` being the server's draw.
 fn until(
     host: &str,
     user: &str,
@@ -369,8 +358,8 @@ fn main() -> Result<()> {
         }
     }
 
-    // The end-to-end gate: run the shipped `logon` — the code the client actually uses — and count
-    // what comes back. Anything but a clean sweep means the ephemeral guarantee is not holding.
+    // `--logon N` runs the shipped `logon` N times; every handshake must succeed, or its
+    // ephemeral guarantee is not holding.
     if logons > 0 {
         println!("logon: {logons} full handshakes through benilla_protocol::logon\n");
         let (mut ok, mut failed) = (0u32, 0u32);
@@ -380,7 +369,7 @@ fn main() -> Result<()> {
                 Err(e) => {
                     failed += 1;
                     println!("  #{i}: {e:#}");
-                    // Do not walk into realmd's lockout while reporting a real regression.
+                    // Stay clear of realmd's lockout.
                     std::thread::sleep(Duration::from_secs(7));
                 }
             }
@@ -402,8 +391,7 @@ fn main() -> Result<()> {
                 std::thread::sleep(Duration::from_secs(61)); // drain realmd's lockout window
                 window_failures = 0;
             }
-            // `Want::Any` with one try: the first ephemeral is used whatever its shape, and whatever
-            // `B` the server sends is kept — an ordinary handshake.
+            // `Want::Any` with one try: an ordinary handshake, whatever the shapes of `A` and `B`.
             match handshake(&host, &user, &pass, Enc::Fixed, Want::Any, 1) {
                 Ok((a, v)) => {
                     let short = a.short_values();
@@ -443,8 +431,8 @@ fn main() -> Result<()> {
     }
 
     println!("realmd at {host}:{AUTH_PORT}, account {user}");
-    // The `H(N)⊕H(g)` constant is hashed as a BigNumber too. It is fixed for WoW's N/g — if its high
-    // byte were zero, *every* fixed-width login would fail, not one in sixty.
+    // `H(N)⊕H(g)` is hashed as a BigNumber too; it is constant, so a zero high byte would fail
+    // every fixed-width login.
     let xh = xor_hash(7, &benilla_srp::LARGE_SAFE_PRIME_LITTLE_ENDIAN);
     println!(
         "H(N)^H(g) high byte = {:#04x} (non-zero, so the constant is unambiguous)",
diff --git a/crates/benilla-protocol/examples/version_check_probe.rs b/crates/benilla-protocol/examples/version_check_probe.rs
index dd59749f..0300f38b 100644
--- a/crates/benilla-protocol/examples/version_check_probe.rs
+++ b/crates/benilla-protocol/examples/version_check_probe.rs
@@ -1,28 +1,16 @@
-//! `version_check_probe` — the B241 instrument (decision 1263): does this realmd enforce
-//! `StrictVersionCheck`, and does our logon proof satisfy it?
+//! `version_check_probe`: whether a realmd enforces `StrictVersionCheck`, and whether our logon
+//! proof satisfies it. It runs the handshake twice, differing only in the proof's `crc_hash`:
+//! twenty zeros, which a strict realmd refuses with `WOW_FAIL_VERSION_INVALID` (0x09, shown as
+//! `AUTH_VERSION_MISMATCH`, "Wrong client version"), and the computed `SHA1(A ‖ H)`
+//! ([`auth::version_proof`]). A non-strict server accepts both.
 //!
-//! Runs the same handshake **twice against the same server**, differing only in the proof packet's
-//! `crc_hash`:
+//! With an install directory it also derives that install's own digest the way the 1.12 client
+//! does, HMAC-SHA1 keyed by the challenge over five binaries, and says whether it is the stock
+//! one. Deviation: benilla always sends the published constant instead, since an install without
+//! those binaries could never answer for itself.
 //!
-//! - **zeros** — what benilla sent for its whole life before 1263. A strict realmd answers this with
-//!   `WOW_FAIL_VERSION_INVALID` (0x09) and logs *"tried to login with modified client!"*; 0x09 is the
-//!   code our login screen renders as `AUTH_VERSION_MISMATCH` / "Wrong client version", which is
-//!   exactly how B241 was reported.
-//! - **computed** — `SHA1(A ‖ H)` with the integrity digest for our build and OS
-//!   ([`auth::version_proof`]).
-//!
-//! A non-strict server accepts both arms (it never looks), so the probe reports *what the server
-//! enforces* as much as what we send. That is the point: it is the A/B that closes B241 and the one
-//! to run against any server a strict-mode rejection is reported from.
-//!
-//! Give it an **install directory** as a fourth argument and it also derives that install's own
-//! integrity digest the way the real client does — HMAC-SHA1 keyed by the challenge over five
-//! binaries (decision 1265, mechanism in wow-re `system/net/scratch/logon-integrity-hash.md`) — and
-//! says whether it is the stock one. Diagnostic only: benilla always sends the published constant,
-//! so a patched `WoW.exe` shows up here without changing a single login.
-//!
-//! Usage: `cargo run -p benilla-protocol --example version_check_probe -- <host[:port]> <user> <pass> [install-dir]`
-//! (the local strict-mode realmd of decision 1263 is `127.0.0.1:3725`; the ordinary one is 3724.)
+//! Usage: `cargo run -p benilla-protocol --example version_check_probe -- <host[:port]> <user>
+//! <pass> [install-dir]`. The local strict-mode realmd is `127.0.0.1:3725`, the ordinary one 3724.
 
 use std::net::TcpStream;
 use std::path::{Path, PathBuf};
@@ -36,10 +24,9 @@ use sha1::{Digest, Sha1};
 /// Which `crc_hash` the arm puts in the proof packet.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Arm {
-    /// Twenty zeros — pre-1263 benilla. Forced by handing the writer a `crc_salt` we hold no digest
-    /// for, which is precisely the "no answer" path.
+    /// Twenty zeros, forced by handing the writer a `crc_salt` we hold no digest for.
     Zeros,
-    /// `SHA1(A ‖ H)` for the salt the server actually sent.
+    /// `SHA1(A ‖ H)` for the salt the server sent.
     Computed,
 }
 
@@ -52,14 +39,13 @@ impl Arm {
     }
 }
 
-/// One full handshake, sending `arm`'s `crc_hash`. `Ok(None)` = accepted, `Ok(Some(code))` = the
-/// server's `WOW_FAIL_*` byte.
+/// One full handshake with `arm`'s `crc_hash`: `None` when accepted, else the `WOW_FAIL_*` byte.
 fn attempt(host: &str, port: u16, user: &str, pass: &str, arm: Arm) -> Result<Option<u8>> {
     let user_n = NormalizedString::new(user).map_err(|e| anyhow!("invalid username: {e}"))?;
     let pass_n = NormalizedString::new(pass).map_err(|e| anyhow!("invalid password: {e}"))?;
 
-    // Redial past an ambiguously-serialized `B` exactly as `logon` does, so a 0x04 here means a bad
-    // password and never an encoding coin-flip (see `benilla-srp`, "Encoding-unambiguous handshakes").
+    // Redial past a width-unstable `B`, as `logon` does, so a 0x04 here is a bad password and
+    // never the SHA-1 encoding disagreement.
     for _ in 0..8 {
         let mut stream = TcpStream::connect((host, port))
             .with_context(|| format!("connecting to {host}:{port}"))?;
@@ -104,9 +90,8 @@ fn attempt(host: &str, port: u16, user: &str, pass: &str, arm: Arm) -> Result<Op
     Err(anyhow!("eight dials, every `B` ambiguous — try again"))
 }
 
-/// The five files the real client hashes, **in this order** — `ChecksumExecutables` at `0x5b1170`,
-/// walking the `char*` table at `0x85def0` (wow-re `system/net/scratch/logon-integrity-hash.md`).
-/// Order is load-bearing: exactly 1 of the 120 permutations reproduces the published digest.
+/// The five files the 1.12 client hashes, in this order (`ChecksumExecutables` at `0x5b1170`, the
+/// table at `0x85def0`); no other of the 120 orders gives the published digest.
 const SCANNED: [&str; 5] = [
     "WoW.exe",
     "fmod.dll",
@@ -115,9 +100,8 @@ const SCANNED: [&str; 5] = [
     "unicows.dll",
 ];
 
-/// HMAC-SHA1 with the 16-byte `crc_salt` as the key — the framing the client uses (`rep stos` of
-/// 64×`0x36` / 64×`0x5c`, salt XORed into both, `0x5b117e`–`0x5b11b6`). No long-key shortening,
-/// because the key is always the 16-byte salt; the client has no such step either.
+/// HMAC-SHA1 keyed by the 16-byte `crc_salt`, framed as the client does (`0x5b117e`–`0x5b11b6`);
+/// the key is always 16 bytes, so there is no long-key step, as in the client.
 fn hmac_sha1(key: &[u8; 16], msg: &[u8]) -> [u8; 20] {
     let mut ipad = [0x36u8; 64];
     let mut opad = [0x5cu8; 64];
@@ -134,11 +118,8 @@ fn hmac_sha1(key: &[u8; 16], msg: &[u8]) -> [u8; 20] {
     outer.finalize().into()
 }
 
-/// Derive `H` from a 1.12.1 install the way the real client does, and say what it means. Purely a
-/// diagnostic: benilla sends the published constant for its build and OS (decision 1265), never this.
-/// A file that cannot be read is **skipped**, contributing no bytes — the client's own behaviour
-/// (four early-outs at `0x5b11eb`/`0x5b1212`/`0x5b121f`/`0x5b1246`), and the reason a Data-only
-/// install could never answer this challenge for itself.
+/// Derive `H` from an install the way the 1.12 client does. An unreadable file contributes no
+/// bytes, as in the client (`0x5b11eb`, `0x5b1212`, `0x5b121f`, `0x5b1246`).
 fn report_install(install_dir: &Path, crc_salt: &[u8; 16]) {
     println!("\n  install {}", install_dir.display());
     let mut msg = Vec::new();
@@ -158,8 +139,7 @@ fn report_install(install_dir: &Path, crc_salt: &[u8; 16]) {
     let h = hmac_sha1(crc_salt, &msg);
     let hex: String = h.iter().map(|b| format!("{b:02X}")).collect();
     println!("    H = {hex}");
-    // What we actually send is `SHA1(A ‖ H)`, so compare the digests through that: equal proofs for
-    // one `A` means equal `H`.
+    // Compare through `SHA1(A ‖ H)`, what we send: equal proofs for one `A` mean equal `H`.
     let a = [0u8; 32];
     let matches = {
         let mut sha = Sha1::new();
@@ -196,8 +176,8 @@ fn main() -> Result<()> {
     };
     let (host, port) = host_port(&host_arg, AUTH_PORT);
 
-    // Report the challenge itself first: our digest is only valid for the one salt every mangos-family
-    // realmd sends, so a server issuing anything else explains a `zeros` result on the computed arm.
+    // Our digest holds only for the one salt every mangos-family realmd sends; under any other,
+    // the computed arm sends zeros too.
     let mut stream =
         TcpStream::connect((host, port)).with_context(|| format!("connecting to {host}:{port}"))?;
     stream.set_read_timeout(Some(Duration::from_secs(10)))?;
diff --git a/crates/benilla-protocol/src/auth.rs b/crates/benilla-protocol/src/auth.rs
index a95b7e37..29d5c108 100644
--- a/crates/benilla-protocol/src/auth.rs
+++ b/crates/benilla-protocol/src/auth.rs
@@ -1,9 +1,6 @@
-//! The realmd (login) wire protocol — 1.12.1 uses **login protocol version 3**. In-repo replacement
-//! for `wow_login_messages` (decision 0021), scoped to the three exchanges [`crate::logon`] performs:
-//! logon challenge, logon proof, and realm list. Login packets are *not* header-encrypted (unlike the
-//! world protocol) and each is self-delimiting, so we read them in request/response order.
-//!
-//! Opcodes: `CMD_AUTH_LOGON_CHALLENGE = 0x00`, `CMD_AUTH_LOGON_PROOF = 0x01`, `CMD_REALM_LIST = 0x10`.
+//! The realmd (login) wire protocol, version 3 in 1.12.1: logon challenge, logon proof and realm
+//! list, the three exchanges [`crate::logon`] performs. Login packets are not header-encrypted and
+//! each is self-delimiting, so they are read in request/response order.
 
 use std::io::{Read, Write};
 use std::net::Ipv4Addr;
@@ -21,18 +18,15 @@ const CMD_REALM_LIST: u8 = 0x10;
 const PROTOCOL_VERSION_THREE: u8 = 3;
 const GAME_NAME_WOW: u32 = 0x0057_6f57; // "WoW\0" little-endian
 const PLATFORM_X86: u32 = 0x0078_3836; // "x86\0"
-                                       // The OS/platform tags ride the wire *reversed*: the real client stores them as little-endian u32s,
-                                       // so `0x0057696e` writes the bytes `n i W \0`, and realmd reverses them back (`AuthSocket.cpp`:
-                                       // `std::reverse(m_os.begin(), m_os.end())`). vmangos accepts exactly "Win" and "OSX"
-                                       // (`WorldSocket::HandleAuthSession`) and fails the session on anything else.
+                                       // Tags are little-endian u32s, so they reach the
+                                       // wire reversed (`0x0057696e` is `n i W \0`) and
+                                       // realmd reverses them back. vmangos fails a session
+                                       // on anything but "Win" or "OSX".
 const OS_WINDOWS: u32 = 0x0057_696e; // "Win\0"
 const OS_MACOS: u32 = 0x004F_5358; // "OSX\0"
 
-/// The OS tag for the host we are actually running on. We hardcoded Windows on every platform,
-/// which is plainly false on a Mac — and servers act on this field: vmangos picks `WardenWin` vs
-/// `WardenMac` from it, and realmd validates the build against it (`FindBuildInfo(build, os,
-/// platform)`). There was never a 1.12 Linux client, so every non-Mac host keeps saying Windows —
-/// the closest true thing we can say.
+/// The host's OS tag: `OSX` on macOS, else `Win`, as there was no 1.12 Linux client. Servers act
+/// on it: vmangos picks `WardenWin` or `WardenMac`, and realmd checks the build (`FindBuildInfo`).
 const fn client_os() -> u32 {
     if cfg!(target_os = "macos") {
         OS_MACOS
@@ -42,11 +36,9 @@ const fn client_os() -> u32 {
 }
 const LOCALE_EN_US: u32 = 0x656e_5553; // "enUS"
 
-/// A non-success auth result byte from the server (challenge or proof stage), typed so the app can
-/// map the code to the client's own `AUTH_*` glue string (decision 0539). Rides [`crate::logon`]'s
-/// `anyhow` chain — `err.downcast_ref::<AuthReject>()` recovers the code through the contexts.
-/// vmangos note (its `AuthCodes.h`, verified): unknown account AND wrong password both arrive as
-/// 0x04 (`WOW_FAIL_UNKNOWN_ACCOUNT`) — the client locks out after an 0x05, so the server avoids it.
+/// A non-success auth result byte, typed so the app can map it to its `AUTH_*` glue string; it
+/// survives [`crate::logon`]'s `anyhow` contexts via `downcast_ref`. vmangos answers an unknown
+/// account and a wrong password alike with 0x04 (`WOW_FAIL_UNKNOWN_ACCOUNT`, `AuthCodes.h`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AuthReject {
     /// The grunt result byte (`WOW_FAIL_*`).
@@ -67,13 +59,12 @@ pub struct ChallengeReply {
     pub generator: u8,
     pub large_safe_prime: [u8; 32],
     pub salt: [u8; 32],
-    /// The 16-byte version challenge the client answers with `crc_hash` — see [`version_proof`].
-    /// Not an SRP6 input; it seeds the client's binary-integrity digest.
+    /// The version challenge answered by `crc_hash` ([`version_proof`]); not an SRP6 input.
     pub crc_salt: [u8; 16],
 }
 
-/// Send `CMD_AUTH_LOGON_CHALLENGE_Client`. `account_name` must already be uppercased (it is what the
-/// SRP6 hashes use). `build` is the client build (5875).
+/// Send `CMD_AUTH_LOGON_CHALLENGE_Client`. `account_name` must be uppercased, as the SRP6 hashes
+/// use it; `build` is 5875.
 pub fn write_logon_challenge(
     w: &mut impl Write,
     account_name: &str,
@@ -102,7 +93,7 @@ pub fn write_logon_challenge(
     w.write_all(&packet)
 }
 
-/// Read the challenge reply, returning the SRP6 inputs (or erroring on a non-success result).
+/// Read the challenge reply; a non-success result is an [`AuthReject`].
 pub fn read_challenge_reply(r: &mut impl Read) -> Result<ChallengeReply> {
     let opcode = read_u8(r)?;
     if opcode != CMD_AUTH_LOGON_CHALLENGE {
@@ -129,14 +120,12 @@ pub fn read_challenge_reply(r: &mut impl Read) -> Result<ChallengeReply> {
         .try_into()
         .map_err(|_| anyhow::anyhow!("large safe prime was {prime_len} bytes, expected 32"))?;
     let salt = read_array::<32>(r)?;
-    // Consume the rest of the packet so the stream stays aligned for the next message — login packets
-    // are NOT length-framed, so leftover bytes desync the very next read. crc_salt[16] feeds the
-    // integrity proof (not SRP6); security_flag (+ the PIN block if set) is unused but must still be
-    // read off.
+    // Read to the end: login packets are not length-framed, so leftover bytes desync the next
+    // read. `security_flag` and the PIN block are unused but must be consumed.
     let crc_salt = read_array::<16>(r)?;
     let security_flag = read_u8(r)?;
     if security_flag & 0x01 != 0 {
-        // PIN: pin_grid_seed (u32) + pin_salt[16]. (vmangos sends security_flag = 0; handled anyway.)
+        // PIN: pin_grid_seed (u32) + pin_salt[16]; vmangos always sends security_flag 0.
         let _pin_grid_seed = read_u32_le(r)?;
         let _pin_salt = read_array::<16>(r)?;
     }
@@ -149,50 +138,34 @@ pub fn read_challenge_reply(r: &mut impl Read) -> Result<ChallengeReply> {
     })
 }
 
-// --- the version (client-integrity) proof ---------------------------------------------------------
+// --- the version (client-integrity) proof --------------------------------------------------------
 //
-// The proof packet's `crc_hash` answers the challenge's `crc_salt`: the real client scans its own
-// binaries under that salt into a 20-byte digest `H`, and sends `SHA1(A ‖ H)`. realmd recomputes the
-// same expression from a stored `H` and rejects a mismatch as a *modified client*
-// (vmangos `AuthSocket::VerifyVersion`, cmangos ditto — byte-identical implementations). We sent
-// twenty zeros here for the project's whole life, which is invisible until a server turns the check
-// on: `StrictVersionCheck = 1` then answers a correct password with `WOW_FAIL_VERSION_INVALID` (0x09,
-// our login screen's "Wrong client version") — B241. Note vmangos's own shipped
-// `realmd.conf.example` sets 1, so this is a *default* on a fresh repack, not exotic hardening.
+// The proof's `crc_hash` answers the challenge's `crc_salt`: the 1.12 client hashes its own
+// binaries under that salt into a 20-byte digest `H` and sends `SHA1(A ‖ H)`. realmd recomputes it
+// from a stored `H` (`AuthSocket::VerifyVersion`) and, under `StrictVersionCheck = 1` (the shipped
+// `realmd.conf.example` value), refuses a mismatch with `WOW_FAIL_VERSION_INVALID` (0x09).
 
-/// The 16-byte `crc_salt` every mangos-family realmd sends — a **constant, not a nonce** (vmangos
-/// `realmd/AuthSocket.cpp:65` and cmangos `realmd/AuthSocket.cpp:187`, two independent copies of the
-/// same bytes). The whole scheme rests on that: because every server issues the same challenge, the
-/// client's answer is a per-build constant a server can store without owning the client.
+/// The `crc_salt` every mangos-family realmd sends: a constant, not a nonce (vmangos
+/// `AuthSocket.cpp:65`, cmangos `AuthSocket.cpp:187`), so the answer is a per-build constant.
 const MANGOS_VERSION_CHALLENGE: [u8; 16] = [
     0xba, 0xa3, 0x1e, 0x99, 0xa0, 0x0b, 0x21, 0x57, 0xfc, 0x37, 0x3f, 0xb3, 0x69, 0xcd, 0xd2, 0xf1,
 ];
 
-/// `H` for build 5875 under [`MANGOS_VERSION_CHALLENGE`], Windows client. Cross-checked between two
-/// independent emulator lineages: vmangos ships it as DB data (`sql/migrations/20221117065844_logon.sql`,
-/// `allowed_clients` row `1,12,1,'',5875,'Win','x86'`), cmangos as a hardcoded table
-/// (`realmd/RealmList.cpp`, `ExpectedRealmdClientBuilds`) — byte-identical.
+/// `H` for the build 5875 Windows client under [`MANGOS_VERSION_CHALLENGE`]: vmangos's
+/// `allowed_clients` row (`20221117065844_logon.sql`), identical to cmangos's `RealmList.cpp`.
 const INTEGRITY_HASH_5875_WINDOWS: [u8; 20] = [
     0x95, 0xed, 0xb2, 0x7c, 0x78, 0x23, 0xb3, 0x63, 0xcb, 0xdd, 0xab, 0x56, 0xa3, 0x92, 0xe7, 0xcb,
     0x73, 0xfc, 0xca, 0x20,
 ];
 
-/// `H` for build 5875 under [`MANGOS_VERSION_CHALLENGE`], Mac client — same two sources, and the one
-/// we must answer with on macOS, where [`client_os`] says `OSX` (vmangos keys its lookup on the os
-/// field, cmangos picks `MacHash` off the same field).
+/// The same for the Mac client, sent on macOS because servers pick `H` by the OS tag.
 const INTEGRITY_HASH_5875_MACOS: [u8; 20] = [
     0x8d, 0x17, 0x3c, 0xc3, 0x81, 0x96, 0x1e, 0xeb, 0xab, 0xf3, 0x36, 0xf5, 0xe6, 0x67, 0x5b, 0x10,
     0x1b, 0xb5, 0x13, 0xe5,
 ];
 
-/// The 20-byte integrity digest to answer `crc_salt` with, or `None` when we have no answer for that
-/// salt.
-///
-/// We hold `H` only for the one salt above, so a server that issues a *different* one gets zeros
-/// rather than a stale constant. That is not defensive padding: replaying a constant computed for
-/// another challenge is exactly the tell a randomised challenge would be looking for, and it cannot
-/// pass anyway. (No server in the mangos family randomises it — a per-connection salt would make
-/// their own stored hashes useless — so this branch is the honest answer to a hypothetical, and free.)
+/// The integrity digest `H` for `crc_salt`, known only for [`MANGOS_VERSION_CHALLENGE`].
+/// Deviation: a stored constant, not a hash of the install, which may lack the five binaries.
 fn integrity_hash(crc_salt: &[u8; 16]) -> Option<[u8; 20]> {
     if *crc_salt != MANGOS_VERSION_CHALLENGE {
         return None;
@@ -204,9 +177,8 @@ fn integrity_hash(crc_salt: &[u8; 16]) -> Option<[u8; 20]> {
     })
 }
 
-/// The proof packet's `crc_hash`: `SHA1(A ‖ H)` over the wire bytes of `A` (realmd hashes `lp->A`
-/// as received, so this is the same 32 bytes we put in the packet). Twenty zeros when we have no
-/// `H` for this salt — the pre-B241 behaviour, which a non-strict server ignores.
+/// The proof's `crc_hash`: `SHA1(A ‖ H)` over `A`'s wire bytes (realmd hashes `lp->A` as
+/// received), or twenty zeros for an unknown salt, which only a strict server refuses.
 pub fn version_proof(crc_salt: &[u8; 16], client_public_key: &[u8; 32]) -> [u8; 20] {
     match integrity_hash(crc_salt) {
         Some(h) => {
@@ -219,9 +191,7 @@ pub fn version_proof(crc_salt: &[u8; 16], client_public_key: &[u8; 32]) -> [u8;
     }
 }
 
-/// Send `CMD_AUTH_LOGON_PROOF_Client`. `crc_salt` is the challenge's — the packet's `crc_hash` is
-/// computed here ([`version_proof`]) rather than passed in, so no caller can forget it. No telemetry
-/// keys, no security flag.
+/// Send `CMD_AUTH_LOGON_PROOF_Client`, computing `crc_hash` from the challenge's `crc_salt`.
 pub fn write_logon_proof(
     w: &mut impl Write,
     client_public_key: &[u8; 32],
@@ -238,7 +208,7 @@ pub fn write_logon_proof(
     w.write_all(&packet)
 }
 
-/// Read the proof reply, returning the server's proof `M2` (or erroring on a non-success result).
+/// Read the proof reply: the server's `M2`, or an [`AuthReject`].
 pub fn read_proof_reply(r: &mut impl Read) -> Result<[u8; 20]> {
     let opcode = read_u8(r)?;
     if opcode != CMD_AUTH_LOGON_PROOF {
@@ -246,7 +216,7 @@ pub fn read_proof_reply(r: &mut impl Read) -> Result<[u8; 20]> {
     }
     let result = read_u8(r)?;
     if result != 0 {
-        // A wrong password fails HERE (the server can't verify M1): vmangos answers 0x04.
+        // A wrong password fails here, where `M1` does not verify: vmangos answers 0x04.
         return Err(AuthReject { code: result }.into());
     }
     let server_proof = read_array::<20>(r)?;
@@ -261,32 +231,18 @@ pub fn write_realm_list_request(w: &mut impl Write) -> std::io::Result<()> {
     w.write_all(&packet)
 }
 
-/// The three **magic populations** the reference's realm-list parser rewrites, and the flag bit
-/// each one stands in for: `(population as sent, population rewritten to, flag OR'd)`.
-///
-/// Only bits `0x01`/`0x02`(/`0x04`) are real server flags on the wire. Recommended, New and Full
-/// travel as *populations* — the parser recognises the exact float, replaces it, and ORs in the bit
-/// the load band later reads. Compared by bit pattern because that is what the binary compares, and
-/// because it says plainly that these are sentinels rather than a numeric range.
-///
-/// VERIFIED, wow-re `system/glue/scratch/realm-list-bindings.md` §5 (the parser is `0x5b2230`).
+/// The magic populations the 1.12 realm-list parser (`0x5b2230`) rewrites, as `(population sent,
+/// population rewritten, flag OR'd)`: Recommended, New and Full travel as these exact float bit
+/// patterns, not as wire flags.
 pub(crate) const MAGIC_POPULATIONS: [(u32, u32, u8); 3] = [
-    (0x4416_0000, 0x0000_0000, 0x20), // 600.0 → 0.0    — Recommended
-    (0x4348_0000, 0x3a83_126f, 0x40), // 200.0 → 0.001  — New
-    (0x43c8_0000, 0x4100_0000, 0x80), // 400.0 → 8.0    — Full
+    (0x4416_0000, 0x0000_0000, 0x20), // 600.0 → 0.0,   Recommended
+    (0x4348_0000, 0x3a83_126f, 0x40), // 200.0 → 0.001, New
+    (0x43c8_0000, 0x4100_0000, 0x80), // 400.0 → 8.0,   Full
 ];
 
-/// Read `CMD_REALM_LIST_Server` into the advertised realms.
-///
-/// **Every per-realm field is kept.** The flags byte, the category byte and the realm id were
-/// read-and-dropped for as long as benilla connected to `realms.first()` without ever drawing a
-/// list; the realm-list screen displays or groups on all three, and the population is the input to
-/// the load band rather than a string to print.
-///
-/// **And the population is rewritten on the way in** — see [`MAGIC_POPULATIONS`]. This has to
-/// happen *here*, in the parser, exactly as the reference does it: the realm-list screen computes a
-/// mean over every realm's population, and a realm advertised as Recommended arrives carrying
-/// `600.0`, which would drag that mean far enough to mislabel every other row on the list.
+/// Read `CMD_REALM_LIST_Server` into the advertised realms, rewriting [`MAGIC_POPULATIONS`] here
+/// as the reference parser does: the realm-list screen averages every realm's population, and an
+/// unswapped Recommended `600.0` would skew that mean for every row.
 pub fn read_realm_list(r: &mut impl Read) -> Result<Vec<RealmInfo>> {
     let opcode = read_u8(r)?;
     if opcode != CMD_REALM_LIST {
@@ -324,7 +280,7 @@ pub fn read_realm_list(r: &mut impl Read) -> Result<Vec<RealmInfo>> {
             id,
         });
     }
-    let _footer_padding = read_u16_le(r)?; // consume so the stream stays aligned (see challenge reply)
+    let _footer_padding = read_u16_le(r)?; // consume so the stream stays aligned
     Ok(realms)
 }
 
@@ -332,9 +288,6 @@ pub fn read_realm_list(r: &mut impl Read) -> Result<Vec<RealmInfo>> {
 mod tests {
     use super::*;
 
-    /// The OS/platform tags are reversed on the wire (the real client's little-endian u32s), and a
-    /// server that reads anything but "Win"/"OSX" fails the session — so pin the byte order, not
-    /// just the constant. Reversing the wire bytes must spell the tag.
     #[test]
     fn os_tags_reverse_to_the_names_servers_match_on() {
         let spelled = |tag: u32| {
@@ -347,7 +300,6 @@ mod tests {
         assert_eq!(spelled(PLATFORM_X86), "x86");
     }
 
-    /// We advertise the host we actually run on — Windows everywhere except macOS.
     #[test]
     fn client_os_follows_the_host() {
         if cfg!(target_os = "macos") {
@@ -362,10 +314,7 @@ mod tests {
         std::array::from_fn(|i| (i as u8).wrapping_mul(7).wrapping_add(9))
     }
 
-    /// Known answers, computed *outside* this crate (Python `hashlib`) from realmd's own expression
-    /// `SHA1(A ‖ H)` and the emulator-sourced `H`. A regression here means either constant moved or
-    /// the hash grew an extra input — both of which read as "modified client" to a strict server and
-    /// are otherwise invisible until someone tries to log in.
+    /// Expected digests computed outside this crate (Python `hashlib`) as `SHA1(A ‖ H)`.
     #[test]
     fn version_proof_matches_the_realmd_expression() {
         let expected = if cfg!(target_os = "macos") {
@@ -380,7 +329,6 @@ mod tests {
         );
     }
 
-    /// A salt we hold no `H` for is answered with zeros, not with the constant for another salt.
     #[test]
     fn an_unknown_version_challenge_is_answered_with_zeros() {
         let mut salt = MANGOS_VERSION_CHALLENGE;
@@ -388,8 +336,7 @@ mod tests {
         assert_eq!(version_proof(&salt, &test_public_key()), [0u8; 20]);
     }
 
-    /// The proof packet carries the answer at the offset realmd reads it from: `opcode · A[32] ·
-    /// M1[20] · crc_hash[20] · num_keys · security_flag`, 75 bytes total.
+    /// `opcode · A[32] · M1[20] · crc_hash[20] · num_keys · security_flag`, 75 bytes.
     #[test]
     fn the_proof_packet_carries_the_version_proof() {
         let a = test_public_key();
@@ -408,12 +355,6 @@ mod tests {
         assert_eq!(&packet[73..], &[0, 0]);
     }
 
-    /// Every per-realm field the wire carries survives the read.
-    ///
-    /// The flags byte, the category byte and the realm id were read into `_`-prefixed locals and
-    /// dropped for as long as nothing drew a realm list; the population was stringified on the way
-    /// in. All four are load-bearing for the realm-list screen, so pin the byte layout *and* the
-    /// capture — a field silently going back to `_` is the failure this catches.
     #[test]
     fn the_realm_list_keeps_every_field_the_wire_carries() {
         let mut body = Vec::new();
@@ -446,13 +387,7 @@ mod tests {
         assert_eq!(r.id, 9);
     }
 
-    /// **Recommended / New / Full arrive as populations, not as flags**, and the parser swaps them
-    /// before anyone can average the number.
-    ///
-    /// This is the one place it can be done. The realm list's load band is computed from a mean
-    /// over every realm's population, so a single realm advertised as Recommended (600.0) sitting
-    /// unswapped in a list of realms at ~1.0 drags the mean past every other row and relabels the
-    /// whole screen. The rewritten values are the reference's own, bit for bit.
+    /// The rewritten values are the reference parser's own, bit for bit.
     #[test]
     fn the_three_magic_populations_become_flags_and_are_rewritten() {
         let one = |pop: f32| {
diff --git a/crates/benilla-protocol/src/bin/benilla-auth.rs b/crates/benilla-protocol/src/bin/benilla-auth.rs
index 5313f6a8..b1c02f3a 100644
--- a/crates/benilla-protocol/src/bin/benilla-auth.rs
+++ b/crates/benilla-protocol/src/bin/benilla-auth.rs
@@ -1,4 +1,4 @@
-//! `benilla-auth` — Phase 3 CLI: SRP6 logon against a vanilla realmd, print the realm list.
+//! `benilla-auth`: SRP6 logon against a vanilla realmd, printing the realm list.
 //!
 //! Example: `cargo run --bin benilla-auth -- one pone localhost`
 
@@ -32,9 +32,7 @@ fn main() -> Result<()> {
         println!("no realms advertised");
     }
     for (i, realm) in logon.realms.iter().enumerate() {
-        // Every field the wire carries: the three that used to be dropped (flags, category,
-        // realm id) are what the realm-list screen greys rows out and groups tabs by, and the
-        // population is the raw float the load band is computed FROM, not the word it shows.
+        // Every field the wire carries; the population is the raw float the load band comes from.
         println!(
             "[Realm {}] {} @ {} — type {} flags {:#04x} pop {} chars {} category {} id {}",
             i + 1,
diff --git a/crates/benilla-protocol/src/bin/benilla-world/main.rs b/crates/benilla-protocol/src/bin/benilla-world/main.rs
index 0068f7f1..4f33a2c1 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/main.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/main.rs
@@ -1,11 +1,10 @@
-//! `benilla-world` — Phase 4 CLI: log in to realmd, connect to the world server (`mangosd`), enter the
-//! world as a character, and stream/tally the object updates the server pushes.
+//! `benilla-world`: logs in to realmd, enters the world server as a character, and tallies the
+//! updates it pushes; the `--<probe>` flags live-verify one wire each.
 //!
 //! Example: `cargo run -p benilla-protocol --bin benilla-world -- one pone localhost`
 //!
-//! If the account has no character yet, one is created (`--create <name>`, Human Warrior) so
-//! `CMSG_PLAYER_LOGIN` has something to log in. The realmd host is a positional arg; the world server
-//! address defaults to whatever the realm list advertises (override with `--world`).
+//! An account with no character gets a Human Warrior (`--create <name>`). The world address
+//! defaults to the realm list's (`--world` overrides).
 
 mod probes;
 mod world;
@@ -48,228 +47,135 @@ struct Cli {
     /// How many seconds to stream packets after entering the world.
     #[arg(long, default_value_t = 10)]
     seconds: u64,
-    /// After streaming, walk this many yards forward, then log out and re-enum to confirm the server
-    /// persisted the new position. Omit to just observe (read-only).
+    /// After streaming, walk this many yards forward, log out, and check the server saved the move.
     #[arg(long)]
     walk: Option<f32>,
-    /// Live-verify the name-query pair: ask our own name (`CMSG_NAME_QUERY`) and the first streamed
-    /// creature's template name (`CMSG_CREATURE_QUERY`, entry from its guid), and require both answers
-    /// to arrive and parse.
+    /// Live-verify `CMSG_NAME_QUERY` (our own name) and `CMSG_CREATURE_QUERY` (the first creature).
     #[arg(long)]
     query_names: bool,
-    /// Live-verify the spell/action wire: require `SMSG_INITIAL_SPELLS` + `SMSG_ACTION_BUTTONS` to
-    /// arrive and parse at login, then send one `CMSG_CAST_SPELL` (Battle Shout 6673 if known, else
-    /// the first known spell) and require an `SMSG_CAST_RESULT` verdict (ok *or* a failure reason —
-    /// either proves the round trip).
+    /// Live-verify `SMSG_INITIAL_SPELLS` and `SMSG_ACTION_BUTTONS` at login, then require an
+    /// `SMSG_CAST_RESULT` for a self cast, a ground cast and a targeted cast.
     #[arg(long)]
     spells: bool,
-    /// Capture the dest-anchored effect wire for a ground cast of this spell id (the B132
-    /// follow-up instrument): GM-learn it + GM-fill mana, cast at own feet (mask 0x40), and dump
-    /// every DynamicObject create raw (labeled `DYNAMICOBJECT_*` fields), the SPELL_GO, and the
-    /// removal edge with its lifetime. Pair with `--seconds 25`+ so a channel + its object's whole
-    /// life fits the window. Needs a GM account (the deploy's probes are gmlevel 6).
+    /// Capture a ground cast of this spell id at our feet (target mask 0x40): every DynamicObject
+    /// create, the SPELL_GO and the removal. Needs GM; pair with `--seconds 25`.
     #[arg(long)]
     groundfx: Option<u32>,
-    /// Live-verify the melee-swing wire (decision 0073): GM-teleport (`.go xyz`) onto a Northshire
-    /// Kobold Vermin spawn, `CMSG_ATTACKSWING` the nearest streamed creature, and require ≥1
-    /// `SMSG_ATTACKERSTATEUPDATE` to arrive and decode (attacker/victim/hitInfo/damage). Needs a GM
-    /// account (the deploy's probes are gmlevel 6).
+    /// Live-verify melee: teleport to the Northshire kobolds, `CMSG_ATTACKSWING` the nearest
+    /// creature and require an `SMSG_ATTACKERSTATEUPDATE`. Needs GM.
     #[arg(long)]
     attack: bool,
-    /// Live-verify `CMSG_USE_ITEM`: use the item in this 1-based backpack slot (the wire's bag
-    /// 255 with player-array slot 23…) and require the server to react — a stack-count values
-    /// delta or a destroy on that item's guid (consumed), or an explicit cast-result refusal.
+    /// Live-verify `CMSG_USE_ITEM` on this 1-based backpack slot (wire bag 255, slot 22 + n):
+    /// require a stack delta, a destroy, or a cast-result refusal.
     #[arg(long)]
     use_pack_slot: Option<u8>,
-    /// Live-verify `CMSG_OPEN_ITEM`: `.additem` a Small Barnacled Clam (entry 7973 — LOOTABLE,
-    /// LockID 0, the director's own case), find it in the backpack, and run the fork a bag
-    /// right-click makes for an *openable* item — `CMSG_OPEN_ITEM(bagIndex, slot)`, never
-    /// `CMSG_USE_ITEM` (a clam has no on-use spell, so the use goes nowhere) — requiring
-    /// `SMSG_LOOT_RESPONSE` on the **item's own guid**. Releases the window and subtracts the copy
-    /// afterwards. Needs a GM account (the deploy's probes are gmlevel 6).
+    /// Live-verify `CMSG_OPEN_ITEM` on an added Small Barnacled Clam (7973, lootable, no lock),
+    /// requiring `SMSG_LOOT_RESPONSE` on the item's own guid. A bag right-click on an openable
+    /// item sends this, never `CMSG_USE_ITEM`. Needs GM.
     #[arg(long)]
     open_item: bool,
-    /// Send a `/say` line right after entering the world — the GM dot-command channel
-    /// (`.additem 3732`, `.repairitems`, …) for setting up probe scenarios. Repeatable; the lines go
-    /// out in order (e.g. `--say ".modify money 5000000" --say ".go creature 1"`).
+    /// Say this line after entering the world, e.g. a GM dot-command; repeatable, sent in order.
     #[arg(long)]
     say: Vec<String>,
-    /// Live-verify `CMSG_AUTOEQUIP_ITEM`: equip the item in this 1-based backpack slot and
-    /// require the server to react — a self values delta landing that item's guid in an
-    /// equipment INV slot, or a decoded `SMSG_INVENTORY_CHANGE_FAILURE` refusal.
+    /// Live-verify `CMSG_AUTOEQUIP_ITEM` on this 1-based backpack slot: require the item in an
+    /// equipment slot or an `SMSG_INVENTORY_CHANGE_FAILURE`.
     #[arg(long)]
     equip_pack_slot: Option<u8>,
-    /// Live-verify `CMSG_SWAP_INV_ITEM` (the backpack pick/place/swap wire): swap the two 1-based
-    /// backpack slots `A:B` (the wire's bag 255, player-array slots 23+A-1 / 23+B-1), await the
-    /// self values delta, and assert the two slots' item guids exchanged — then swap back and assert
-    /// the original layout is restored (leaves the character exactly as found). Slot A must be
-    /// occupied; B may be empty (an empty destination is a move on this wire).
+    /// Live-verify `CMSG_SWAP_INV_ITEM` on 1-based backpack slots `A:B`, then swap back. A must be
+    /// occupied; an empty B makes it a move.
     #[arg(long, value_parser = parse_slot_pair)]
     swap_pack_slots: Option<(u8, u8)>,
-    /// Live-verify the vendor wire (decision 0081 phase 4): auto-find the nearest streamed
-    /// vendor NPC (`UNIT_NPC_FLAG_VENDOR`), `CMSG_LIST_INVENTORY` it and require an
-    /// `SMSG_LIST_INVENTORY` to arrive and parse (N rows), then `CMSG_BUY_ITEM` the cheapest row and
-    /// require a reaction — the purchased item arriving (`ItemCreate`/values), the vendor stock
-    /// updating (`SMSG_BUY_ITEM`), *or* a decoded `SMSG_BUY_FAILED` (all prove the round trip). Also
-    /// reads our `PLAYER_FIELD_COINAGE` (the money accessor) at login and confirms any coinage delta
-    /// lands on that field. No GM needed — it uses whatever vendor streams in range.
+    /// Live-verify the vendor wire on the nearest vendor: `CMSG_LIST_INVENTORY`, then buy the
+    /// cheapest row and require the item, a stock update or `SMSG_BUY_FAILED`. No GM needed.
     #[arg(long)]
     vendor: bool,
-    /// Live-verify the solo-loot wire (decision 0084 §1): select a target (nearest streamed
-    /// creature within range of the `--attack` teleport spot, or `--loot-guid` if given),
-    /// GM-kill it (`.damage 10000`), wait for `UNIT_DYNFLAG_LOOTABLE`, then `CMSG_LOOT` it,
-    /// require `SMSG_LOOT_RESPONSE` to arrive and parse, `CMSG_AUTOSTORE_LOOT_ITEM` every row,
-    /// `CMSG_LOOT_MONEY` if it carried gold, and `CMSG_LOOT_RELEASE` — requiring
-    /// `SMSG_LOOT_RELEASE_RESPONSE` to close it. Prints every loot-related packet decoded. Needs a
-    /// GM account (the deploy's probes are gmlevel 6).
+    /// Live-verify solo loot: GM-kill the nearest creature (or `--loot-guid`), loot every row and
+    /// the money, and require `SMSG_LOOT_RELEASE_RESPONSE`. Needs GM.
     #[arg(long)]
     loot: bool,
-    /// Skip the nearest-creature search for `--loot` and loot this guid directly (decimal or
-    /// `0x`-prefixed hex).
+    /// Loot this guid for `--loot` (decimal or `0x` hex) instead of the nearest creature.
     #[arg(long, value_parser = parse_guid)]
     loot_guid: Option<u64>,
-    /// Live-verify the questgiver wire (decision 0088): GM-teleport onto Marshal McBride (Northshire,
-    /// entry 197), `CMSG_GOSSIP_HELLO` him, `CMSG_QUESTGIVER_QUERY_QUEST` the target quest and require
-    /// `SMSG_QUESTGIVER_QUEST_DETAILS` to parse, `CMSG_QUESTGIVER_ACCEPT_QUEST` it and confirm the
-    /// quest id lands in the player descriptor's `PLAYER_QUEST_LOG` fields, GM-complete it
-    /// (`.quest complete`), then `CMSG_QUESTGIVER_COMPLETE_QUEST` → `_REQUEST_REWARD` → `_CHOOSE_REWARD`
-    /// requiring `SMSG_QUESTGIVER_QUEST_COMPLETE` (XP/money) + a `PLAYER_FIELD_COINAGE` delta. Uses
-    /// quest 7 "Kobold Camp Cleanup" (McBride gives + takes it; XP 170, money 25c). Needs a GM
-    /// account (the deploy's probes are gmlevel 6).
+    /// Live-verify the questgiver wire with quest 783, from Deputy Willem (823) to Marshal McBride
+    /// (197): details, accept, GM-complete, reward, requiring `SMSG_QUESTGIVER_QUEST_COMPLETE` and
+    /// an XP delta. Needs GM.
     #[arg(long)]
     quest: bool,
-    /// Live-verify the quest-LOG wire (decision 0109 — the questgiver wire's deferred second
-    /// slice): GM-teleport onto Marshal McBride (entry 197 — gives *and* takes quest 7 "Kobold
-    /// Camp Cleanup", VERIFIED live against `mangos.creature_questrelation` /
-    /// `creature_involvedrelation`, both rows pointing at 197; objective is 10× creature entry 6,
-    /// `quest_template.ReqCreatureOrGOId1/Count1`), accept quest 7, `CMSG_QUEST_QUERY` it and
-    /// require `SMSG_QUEST_QUERY_RESPONSE` to parse into the title plus a real
-    /// (`required_count > 0`) objective — the fat template parser's live golden, distinct from the
-    /// giver-panel `SMSG_QUESTGIVER_QUEST_DETAILS` [`Self::quest`] already exercises. Then poll the
-    /// player descriptor for the `PLAYER_QUEST_LOG` slot the accept landed in, GM-complete it
-    /// (`.quest complete 7`) and require the slot's count-state field to gain the `COMPLETE` state
-    /// byte, then `CMSG_QUESTLOG_REMOVE_QUEST` that slot and require its id field to clear to `0`
-    /// (no ack SMSG on this wire — the field clear *is* the confirmation). Needs a GM account (the
-    /// deploy's probes are gmlevel 6).
+    /// Live-verify the quest log with quest 7 (10 kills of entry 6, from Marshal McBride):
+    /// `CMSG_QUEST_QUERY` must parse a real objective, `.quest complete 7` must set the slot's
+    /// `COMPLETE` byte, and `CMSG_QUESTLOG_REMOVE_QUEST` must clear the slot, which has no ack.
+    /// Needs GM.
     #[arg(long)]
     questlog: bool,
-    /// Live-verify the timed-quest COUNTDOWN chain (decision 1150, B234): GM-add a quest with a
-    /// `LimitTime`, read its `PLAYER_QUEST_LOG` slot's raw timer field (an absolute unix stamp,
-    /// not a duration), ask `CMSG_QUERY_TIME` for the server's own clock, and require the
-    /// subtraction to land inside the template's own `limit_time` window. The one leg no offline
-    /// test can cover: two independent packets whose epochs must agree. Needs a GM account (the
-    /// deploy's probes are gmlevel 6).
+    /// Live-verify a timed quest: its `PLAYER_QUEST_LOG` timer is an absolute unix stamp, and
+    /// minus `CMSG_QUERY_TIME`'s server clock it must fall inside the template's `limit_time`.
+    /// Needs GM.
     #[arg(long)]
     questtimer: bool,
-    /// Live-verify the quest-STARTER item wire (decision 0664): `.additem` the Northshire Gift
-    /// Voucher (entry 14646, starts quest 5805 "Welcome!"), find it in the backpack, and run the
-    /// fork a bag right-click makes for an item whose template carries a non-zero `StartQuest` —
-    /// `CMSG_QUESTGIVER_QUERY_QUEST` addressed to the **item's own guid** (never `CMSG_USE_ITEM`,
-    /// which the server refuses with `EQUIP_ERR_ITEM_NOT_FOUND`, the red "The item was not found."
-    /// line) — requiring `SMSG_QUESTGIVER_QUEST_DETAILS`, then `CMSG_QUESTGIVER_ACCEPT_QUEST` on
-    /// the same guid, requiring BOTH the quest id landing in `PLAYER_QUEST_LOG` and the starter
-    /// item being destroyed. Cleans up after itself (`.quest remove`). Needs a GM account (the
-    /// deploy's probes are gmlevel 6).
+    /// Live-verify a quest-starter item, the Northshire Gift Voucher (14646, quest 5805): a bag
+    /// right-click sends `CMSG_QUESTGIVER_QUERY_QUEST` to the item's guid, never `CMSG_USE_ITEM`
+    /// (refused with `EQUIP_ERR_ITEM_NOT_FOUND`); accepting must log the quest and keep the item,
+    /// which 5805 requires. Needs GM.
     #[arg(long)]
     quest_item: bool,
-    /// Live-verify the force-speed-change wire: GM `.modify speed 1.5` (self-targeted), require
-    /// `SMSG_FORCE_RUN_SPEED_CHANGE` to arrive and parse (flat speed 10.5 = 1.5 × the 7.0 base),
-    /// ack it (`CMSG_FORCE_RUN_SPEED_CHANGE_ACK` echoing counter + exact speed with our live pose),
-    /// then `.modify speed 1` and require a SECOND change (counter incremented, speed 7.0) on a
-    /// still-live stream. A malformed ack body throws in the server's parser and drops the session
-    /// (the `--charge` precedent), so survival through both round trips is the wire proof. Needs a
-    /// GM account (the deploy's probes are gmlevel 6).
+    /// Live-verify `SMSG_FORCE_RUN_SPEED_CHANGE` via `.modify speed 1.5` (10.5 = 1.5 × 7.0) and
+    /// back to 1, acking each. A malformed ack drops the session, so surviving both is the proof.
+    /// Needs GM.
     #[arg(long)]
     speed: bool,
 
-    /// Live-verify what the server sends when a teleport DISMOUNTS you (B213, decision 1478):
-    /// `.aura 458` (Brown Horse — a real `SPELL_AURA_MOUNTED` holder, unlike `.modify mount`),
-    /// require the mounted `SMSG_FORCE_RUN_SPEED_CHANGE`, then `.go xyz` into Ragefire Chasm
-    /// (map 389 — a dungeon, so `MapEntry::IsMountAllowed()` is false) and require, in this order:
-    /// `SMSG_NEW_WORLD`, our own create block on the new map **still carrying the mount's** run
-    /// speed (vmangos sends it from `Map::Add` → `SendInitSelf`), and then the strip's
-    /// `SMSG_FORCE_RUN_SPEED_CHANGE` back at 7.0 — printing the gap between the two. Both are
-    /// written by one `HandleMoveWorldportAckOpcode` call, which is why a client draining its
-    /// socket once a frame sees them in a single drain. Leaves the character unmounted and back on
-    /// map 0. Needs a GM account (the deploy's probes are gmlevel 6); pair with `--seconds 30`+.
+    /// Live-verify a dismounting teleport: `.aura 458` (Brown Horse, a real mount aura, unlike
+    /// `.modify mount`), then `.go xyz` into Ragefire Chasm (map 389, no mounts). Requires
+    /// `SMSG_NEW_WORLD`, our create block still at mounted speed, then
+    /// `SMSG_FORCE_RUN_SPEED_CHANGE` back to 7.0, both written by one
+    /// `HandleMoveWorldportAckOpcode`. Needs GM; pair with `--seconds 30`.
     #[arg(long)]
     mount_tele: bool,
 
-    /// Live-verify the aura wire (decision 0255 phase 1): GM-apply Mark of the Wild (1126, a
-    /// cancelable buff) and Shadow Word: Pain (589, a periodic-damage DoT, unambiguously negative)
-    /// to ourselves with explicit durations via `.aura`, then require — from the *live* descriptor
-    /// — that both land in `UNIT_FIELD_AURA` (proving the field index), in the correct half (buffs
-    /// 0–31, debuffs 32–47), with the `AURAFLAGS` cancelable nibble bit set only on the buff, the
-    /// `AURALEVELS` byte equal to our own level, and a stack of 1 (the `count - 1` wire bias). Also
-    /// requires an `SMSG_UPDATE_AURA_DURATION` for each aura's own slot carrying the duration we
-    /// asked for, and asserts it arrived **before** the descriptor delta that names the slot (the
-    /// ordering the aura model depends on). Leaves the character as found (`.unaura` both). Needs a
-    /// GM account (the deploy's probes are gmlevel 6).
+    /// Live-verify auras: `.aura` Mark of the Wild (1126) and Shadow Word: Pain (589), requiring
+    /// each in `UNIT_FIELD_AURA` (buffs 0–31, debuffs 32–47) with the cancelable flag on the buff
+    /// only, our level, a stack of 1 (wire `count - 1`), and its `SMSG_UPDATE_AURA_DURATION`
+    /// before the descriptor delta. Needs GM.
     #[arg(long)]
     aura: bool,
 
-    /// Live-verify the questgiver STATUS wire (the overhead `!`/`?` markers' data):
-    /// teleport onto Marshal McBride, `CMSG_QUESTGIVER_STATUS_QUERY` his guid, and require an
-    /// `SMSG_QUESTGIVER_STATUS` answer for him — printing the dialog status BEFORE and AFTER a
-    /// `.quest remove 7` (unaccepted quest 7 should read AVAILABLE=5). Needs a GM account.
+    /// Live-verify `SMSG_QUESTGIVER_STATUS` for Marshal McBride after `.quest remove 7`, so an
+    /// unaccepted quest 7 reads AVAILABLE (5). Needs GM.
     #[arg(long)]
     giverstatus: bool,
 
-    /// Live-verify the world-state table's two wires (`SMSG_INIT_WORLD_STATES` /
-    /// `SMSG_UPDATE_WORLD_STATE` — what the NPC-text `$<n>w`/`$<n>e` tokens read): teleport to
-    /// Elwynn, hop to Stormwind to force a zone-change init, and `.debug send worldstate` one
-    /// synthetic pair to require back. Prints every state received. Needs a **SEC_DEVELOPER**
-    /// account: `.debug send worldstate` is gmlevel 5, under the 6 the slot-keyed probe
-    /// accounts carry (decision 0450), so the update leg needs a temporary grant.
+    /// Live-verify `SMSG_INIT_WORLD_STATES` (a zone change into Stormwind) and
+    /// `SMSG_UPDATE_WORLD_STATE` (`.debug send worldstate`, which needs gmlevel 5).
     #[arg(long)]
     worldstate: bool,
 
-    /// Live-verify the Charge wire (warrior Charge rank 1, spell 100): GM `.learn 100`, teleport to
-    /// open ground near the Northshire kobold camp ([`CHARGE_TP`]), pick a creature at charge range
-    /// (8–25 yd), `CMSG_SET_SELECTION` + `CMSG_CAST_SPELL` 100 at it — then require an
-    /// `SMSG_MONSTER_MOVE` addressed to **our own guid**, proving Charge drives the caster through
-    /// the same server spline machinery as any creature (not a teleport / not a knockback). Prints
-    /// the self spline in full (facing kind, duration, waypoints, flying bit) so the ride + the
-    /// `CMSG_MOVE_SPLINE_DONE` ack it obliges can be built from the real numbers. Needs a GM warrior
-    /// (any slot-keyed probe account, gmlevel 6).
+    /// Live-verify Charge (spell 100): charge a creature 8–25 yd away and require an
+    /// `SMSG_MONSTER_MOVE` for our own guid, the same server spline as any creature's; prints it
+    /// in full. Needs a GM warrior.
     #[arg(long)]
     charge: bool,
 
-    /// Live-verify the death-arc slice-1 wire (decision 0308): GM-kill self (`.die`), require the
-    /// death signals (health force-flushed to 0, the death root), release
-    /// (`CMSG_REPOP_REQUEST`), require the full ghost transition — unroot, the water-walk grant,
-    /// `SMSG_CORPSE_RECLAIM_DELAY`, `PLAYER_FLAGS_GHOST`, the corpse object streaming in, the
-    /// graveyard teleport — query the corpse (`MSG_CORPSE_QUERY`), then GM-revive (`.revive`) to
-    /// leave the character alive. Recommend `--seconds 45`: the `.die`→repop→revive round trip
-    /// itself completes in ~10s, but the reclaim delay is only ever observed as a packet value
-    /// (never awaited), and the slack keeps a slow local server from truncating the ghost phase.
-    /// Needs a GM account (the deploy's probes are gmlevel 6).
+    /// Live-verify death: `.die`, release, then the ghost transition (unroot, water walk,
+    /// `SMSG_CORPSE_RECLAIM_DELAY`, `PLAYER_FLAGS_GHOST`, the corpse, the graveyard teleport),
+    /// `MSG_CORPSE_QUERY` and `.revive`. Pair with `--seconds 45`. Needs GM.
     #[arg(long)]
     death: bool,
 
-    /// Live-verify the self-resurrect wire (decision 1746): arm a shaman's Reincarnation with GM
-    /// commands (`.cooldown`, `.learn 20608`, `.additem 17030` — vmangos's gate asks no class
-    /// question), die and **stay dead-unreleased** (the DEATH dialog's state, where the soulstone
-    /// button lives), require `PLAYER_SELF_RES_SPELL` to arrive carrying the effect spell 21169,
-    /// send `CMSG_SELF_RES`, and require both that the field clears and that we stand back up
-    /// without ever having been a ghost. Recommend `--seconds 30`. Needs a GM account; leaves the
-    /// character alive. Mutually exclusive with `--death`/`--spirit`, which release the spirit.
+    /// Live-verify `CMSG_SELF_RES`: arm Reincarnation (`.learn 20608`, `.additem 17030`; vmangos
+    /// checks no class), die unreleased, require `PLAYER_SELF_RES_SPELL` 21169, then stand up
+    /// without becoming a ghost. Pair with `--seconds 30`. Needs GM; excludes `--death` and
+    /// `--spirit`, which release.
     #[arg(long)]
     self_res: bool,
 
-    /// Live-verify the spirit-healer res + the 25% durability loss's wire (director-reported:
-    /// "durability still 100% after spirit-healer rez"): GM-repair to a full baseline, die and
-    /// release (the --death staging), teleport onto the graveyard's Spirit Healer, send
-    /// `CMSG_SPIRIT_HEALER_ACTIVATE`, and require BOTH the res (the ghost flag clears) and the
-    /// post-activate `ITEM_FIELD_DURABILITY` values-deltas the loss must push — the exact packets
-    /// the app's tooltip line feeds from. Recommend `--seconds 45`. Needs a GM account; leaves the
-    /// character alive and re-repaired.
+    /// Live-verify the spirit-healer res: die, release, `CMSG_SPIRIT_HEALER_ACTIVATE`, requiring
+    /// the ghost flag to clear and the 25% durability loss as `ITEM_FIELD_DURABILITY` deltas.
+    /// Pair with `--seconds 45`. Needs GM.
     #[arg(long)]
     spirit: bool,
 }
 
-/// Parse a `--loot-guid` value: decimal, or `0x`-prefixed hex (as `benilla-world`'s own `guid
-/// {:#x}` printouts read out).
+/// Parse a `--loot-guid` value: decimal, or `0x`-prefixed hex.
 fn parse_guid(s: &str) -> Result<u64, String> {
     if let Some(hex) = s.strip_prefix("0x").or_else(|| s.strip_prefix("0X")) {
         u64::from_str_radix(hex, 16).map_err(|e| e.to_string())
@@ -294,12 +200,11 @@ fn parse_slot_pair(s: &str) -> Result<(u8, u8), String> {
 fn main() -> Result<()> {
     let cli = Cli::parse();
 
-    // 1. realmd logon → session key + realm list (Phase 3).
+    // 1. realmd logon: session key and realm list.
     let logon = benilla_protocol::logon(&cli.host, &cli.username, &cli.password)?;
     println!("authenticated as '{}'", cli.username);
 
-    // 2. Resolve the world address: explicit override, else the first advertised realm, else fall
-    //    back to the auth host on the default world port.
+    // 2. The world address: the override, else the first realm's, else the auth host's.
     let world_addr = match (&cli.world, logon.realms.first()) {
         (Some(addr), _) => addr.clone(),
         (None, Some(realm)) => {
@@ -345,29 +250,26 @@ fn main() -> Result<()> {
         character.name, character.guid, character.level, character.map,
     );
 
-    // 5. Enter the world, then claim movement control (vmangos ignores MSG_MOVE_* until we're the
-    //    confirmed mover — the real client sends CMSG_SET_ACTIVE_MOVER on login).
+    // 5. Enter the world and claim the mover: vmangos ignores `MSG_MOVE_*` until then, and the
+    //    1.12 client sends `CMSG_SET_ACTIVE_MOVER` on login.
     session.player_login(character.guid)?;
     session.set_active_mover(character.guid)?;
 
-    // 6. Stream packets, tallying opcodes and folding the decoded `SessionEvent`s into a local entity
-    //    map so we can read nearby entities' positions out of the stream.
+    // 6. Stream packets, tallying opcodes and tracking entity positions.
     session.set_read_timeout(Some(Duration::from_secs(2)))?;
     let deadline = Instant::now() + Duration::from_secs(cli.seconds);
 
-    // The shared world state every probe reads (identity, entity tracker, item/vendor stores, the
-    // session-keeping acks); the DeathArc scenario machinery is staged when --death/--spirit is set.
+    // The world state every probe reads; the death arc is staged for the three death probes.
     let mut world = World::new(character);
     if cli.death || cli.spirit || cli.self_res {
         world.death_arc = Some(DeathArc {
-            // --self-res tests the dead-UNRELEASED state, so the arc must not repop on its own.
+            // --self-res needs the dead, unreleased state, so the arc must not repop.
             hold_release: cli.self_res,
             ..DeathArc::default()
         });
     }
 
-    // The probe registry: one entry per flag, in today's stream-loop/verify block order (so poll,
-    // on_event, verify, and output order are preserved). Adding a probe is one push here.
+    // One probe per flag; registry order is the poll, on_event, verify and output order.
     let mut probes: Vec<Box<dyn Probe>> = Vec::new();
     if cli.attack {
         probes.push(Box::new(Attack::default()));
@@ -441,8 +343,8 @@ fn main() -> Result<()> {
         probes.push(Box::new(WorldState::default()));
     }
 
-    // Pre-stream staging: the DeathArc first (its `.revive` + teleport lead --spirit's `.repairitems`),
-    // then every probe's stage in registry order, then the `--say` lines (after all staging, as today).
+    // Staging order: the death arc (its `.revive` and teleport precede --spirit's `.repairitems`),
+    // each probe in registry order, then the `--say` lines.
     world.stage(&mut session)?;
     for probe in probes.iter_mut() {
         let mut cx = Ctx {
@@ -494,10 +396,7 @@ fn main() -> Result<()> {
     // Report the entities we decoded, with raw WoW coordinates.
     let self_guid = world.self_guid;
     println!("\n--- tracked {} entit(ies) ---", world.tracked.len());
-    // Every `EntityKind`, or the dump silently drops a whole class of streamed object. `Corpse`
-    // was missing from here since 1706 gave TYPEID_CORPSE its own variant: a hardcoded list is not
-    // a `match`, so nothing warned, and a streamed body simply never appeared in the census (found
-    // by 1723, alongside the same omission in the --death corpse capture).
+    // Every `EntityKind`: this list is not a `match`, so a new variant must be added by hand.
     for kind in [
         EntityKind::Player,
         EntityKind::Unit,
@@ -553,9 +452,8 @@ fn main() -> Result<()> {
         probe.verify(&mut cx)?;
     }
 
-    // 7. Optional: prove we can drive our own movement server-side. Walk forward, log out (which
-    //    saves the character), then re-enum and compare the persisted position. Terminal — it ends
-    //    the session, so it runs last.
+    // 7. Optional walk, then log out (which saves the character) and compare the saved position.
+    //    It ends the session, so it runs last.
     if let Some(yards) = cli.walk {
         let self_entity = world.tracked.get(&self_guid);
         let start = self_entity.map(|t| t.position).unwrap_or(world.spawn_pos);
@@ -609,9 +507,8 @@ fn main() -> Result<()> {
     Ok(())
 }
 
-/// Walk the active player `yards` forward along `orientation`, sending a realistic
-/// start→heartbeat→stop sequence at run speed, and return the destination. WoW orientation 0 faces
-/// +X; forward is `(cos o, sin o, 0)`. Coordinates are raw WoW yards.
+/// Walk `yards` forward as start, heartbeats and stop at run speed, returning the destination.
+/// Orientation 0 faces +X, so forward is `(cos o, sin o, 0)`, in raw WoW yards.
 fn walk_forward(
     session: &mut WorldSession,
     start: [f32; 3],
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/attack.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/attack.rs
index 858a1166..37fca7f2 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/attack.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/attack.rs
@@ -1,5 +1,5 @@
-//! `--attack`: melee-swing wire (decision 0073). GM-teleport onto a Northshire Kobold Vermin, swing
-//! the nearest creature, require ≥1 `SMSG_ATTACKERSTATEUPDATE`.
+//! `--attack`: the melee-swing wire. Teleports onto a Northshire Kobold Vermin, swings at the
+//! nearest creature and requires an `SMSG_ATTACKERSTATEUPDATE`.
 
 use anyhow::{bail, Context, Result};
 use benilla_protocol::{guid, EntityKind};
@@ -14,9 +14,7 @@ pub(crate) struct Attack {
 
 impl Probe for Attack {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // --loot reuses this teleport spot to guarantee a killable creature in range when no
-        // explicit --loot-guid was given; avoid sending it twice if both flags are set (the shared
-        // `attack_tp_staged` flag — attack/loot/DeathArc all key off it).
+        // --loot and the death arc share this teleport; `attack_tp_staged` sends it once.
         if !cx.world.attack_tp_staged {
             cx.session.send_chat(ATTACK_TP)?;
             cx.world.attack_tp_staged = true;
@@ -26,9 +24,7 @@ impl Probe for Attack {
     }
 
     fn poll(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Swing at the nearest creature once we've landed (the port repopulates `tracked` around the
-        // kobold spawn; anything within 20 yd of the landing point is a candidate — the nearest is
-        // the kobold we landed on, in melee reach).
+        // Once landed, swing at the nearest creature within 20 yd: the kobold we stand on.
         if self.attack_target.is_none() {
             if let Some(pos) = cx.world.attack_pos {
                 let nearest = cx
@@ -54,8 +50,6 @@ impl Probe for Attack {
     }
 
     fn verify(&mut self, cx: &mut Ctx) -> Result<()> {
-        // --attack verdict: the port must have landed, the swing gone out, and at least one completed
-        // swing decoded — the full decision-0073 trigger chain against the live server.
         if cx.world.attack_pos.is_none() {
             bail!("--attack: the GM teleport never arrived (is the account gmlevel ≥ 2?)");
         }
@@ -67,11 +61,8 @@ impl Probe for Attack {
             bail!("--attack: swung at {target:#x} but no SMSG_ATTACKERSTATEUPDATE decoded");
         }
         println!("✅ attack: {swings_seen} SMSG_ATTACKERSTATEUPDATE swing(s) decoded (target {target:#x}).");
-        // The refusals are REPORTED, never required: this probe lands on top of its kobold, so the
-        // server has no reason to send one. They are surfaced because before decision 2037 they
-        // were dropped silently, and a run that does provoke one should say so rather than swallow
-        // it again. Eliciting one on purpose needs a target out of melee reach whose hostility we
-        // can be sure of, which a live server does not hand us (2037's remainder 4).
+        // Refusals are reported, never required: the probe stands on its kobold, so the server has
+        // no cause to send one.
         let refusals = &cx.world.swing_refusals;
         if refusals.is_empty() {
             println!(
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/aura.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/aura.rs
index 5ae2e33c..8d88869c 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/aura.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/aura.rs
@@ -1,6 +1,6 @@
-//! `--aura`: the aura wire (decision 0255 phase 1). GM-apply a buff + a DoT with explicit durations,
-//! require both in `UNIT_FIELD_AURA` (correct half, cancelable nibble, level byte, stack bias), and
-//! require an `SMSG_UPDATE_AURA_DURATION` per aura ordered BEFORE the descriptor delta that names it.
+//! `--aura`: the aura wire. Applies a buff and a DoT with set durations, requires both in
+//! `UNIT_FIELD_AURA` (half, cancelable bit, level byte, stack bias), and requires each one's
+//! `SMSG_UPDATE_AURA_DURATION` to arrive before the descriptor delta that names it.
 
 use std::time::{Duration, Instant};
 
@@ -9,17 +9,15 @@ use benilla_protocol::{decode, ObjectFields, ServerPacket, SessionEvent};
 
 use crate::probes::{Ctx, Probe};
 
-// --aura: two spells with opposite sign, applied to ourselves by the GM `.aura <spell> <seconds>`
-// command (`ChatHandler::HandleAuraCommand` → `HandleAuraHelper`, `UnitCommands.cpp:997-1051`;
-// with no selection it targets the caster — `ChatHandler::GetSelectedUnit`, `Chat.cpp:2621-2622`).
-/// Mark of the Wild — positive, and lacks `SPELL_ATTR_NO_AURA_CANCEL`, so the wire's cancelable bit
-/// must be set. Lands in the positive half (slots 0–31).
+// `.aura <spell> <seconds>` (`UnitCommands.cpp:997-1051`) targets the caster when nothing is
+// selected (`Chat.cpp:2621-2622`).
+/// Mark of the Wild: positive, without `SPELL_ATTR_NO_AURA_CANCEL`, so cancelable (slots 0–31).
 const AURA_BUFF_SPELL: u32 = 1126;
-/// Shadow Word: Pain — `SPELL_AURA_PERIODIC_DAMAGE`, unambiguously negative however it is applied.
-/// Lands in the negative half (slots 32–47) and must NOT be cancelable.
+/// Shadow Word: Pain, `SPELL_AURA_PERIODIC_DAMAGE`, negative however applied: slots 32–47, not
+/// cancelable.
 const AURA_DEBUFF_SPELL: u32 = 589;
 const AURA_BUFF_SECONDS: u32 = 300;
-/// Short: this one ticks damage on us, and we want it gone even if the cleanup `.unaura` is missed.
+/// Short, since it damages us and must expire even if the cleanup `.unaura` is missed.
 const AURA_DEBUFF_SECONDS: u32 = 15;
 
 pub(crate) struct Aura;
@@ -28,13 +26,9 @@ impl Probe for Aura {
     fn verify(&mut self, cx: &mut Ctx) -> Result<()> {
         let self_guid = cx.world.self_guid;
         let self_level = cx.world.self_level;
-        // --aura: live-verify the aura descriptor block + SMSG_UPDATE_AURA_DURATION (decision 0255).
-        // Nothing here trusts a field index: the probe *searches* the decoded slots for the spell ids it
-        // asked for, so a wrong `FIELD_UNIT_AURA` fails as "never appeared" rather than passing on
-        // garbage.
-        // Start from the LOGIN snapshot, not an empty store: a values delta only carries *changed*
-        // fields, so a delta-only view would silently hide auras the server restored at login from
-        // `character_aura` (they persist across logout) — and then misreport which slots are free.
+        // The probe searches the decoded slots for its spell ids, so a wrong field index fails as
+        // "never appeared". Start from the login snapshot: deltas carry only changed fields, and
+        // auras restored from `character_aura` at login would otherwise be invisible.
         let mut fields = cx.world.self_fields.clone().unwrap_or_default();
         let session = &mut *cx.session;
         let dump = |label: &str, f: &ObjectFields| {
@@ -58,8 +52,8 @@ impl Probe for Aura {
         };
         dump("at login (restored from character_aura)", &fields);
 
-        // Clean slate, so a re-run measures a fresh apply and not a leftover refresh. `.unaura`
-        // zeroes the slot, which reaches us as an explicit `0` in the next delta.
+        // A clean slate, so a re-run measures a fresh apply. `.unaura` zeroes the slot, which
+        // arrives as an explicit `0` in the next delta.
         session.send_chat(&format!(".unaura {AURA_BUFF_SPELL}"))?;
         session.send_chat(&format!(".unaura {AURA_DEBUFF_SPELL}"))?;
         let settle = Instant::now() + Duration::from_secs(3);
@@ -74,10 +68,9 @@ impl Probe for Aura {
             }
         }
         dump("after .unaura of both probe spells", &fields);
-        // Whatever survives is not ours to touch (a warrior's Battle Stance, 2457, permanently owns
-        // slot 0). Nothing may report a duration for these while we watch: the server sends
-        // `SMSG_UPDATE_AURA_DURATION` only on apply/refresh, and never at all for a permanent aura —
-        // which is precisely the reference's "until cancelled" (an occupied slot with no timer).
+        // Survivors are not ours (Battle Stance, 2457, owns slot 0) and must report no duration:
+        // the server sends `SMSG_UPDATE_AURA_DURATION` only on apply or refresh, never for a
+        // permanent aura, which the 1.12 client shows as "until cancelled".
         let untouched: Vec<u8> = fields.unit_auras().map(|a| a.slot).collect();
 
         println!("\nGM: .aura {AURA_BUFF_SPELL} {AURA_BUFF_SECONDS} (Mark of the Wild)");
@@ -85,10 +78,8 @@ impl Probe for Aura {
         session.send_chat(&format!(".aura {AURA_BUFF_SPELL} {AURA_BUFF_SECONDS}"))?;
         session.send_chat(&format!(".aura {AURA_DEBUFF_SPELL} {AURA_DEBUFF_SECONDS}"))?;
 
-        // Record the arrival ORDER of the first duration packet against the values delta that first
-        // names the buff's spell in its slot — both indexed by PACKET arrival, the axis the ordering
-        // claim is actually about. `SMSG_UPDATE_AURA_DURATION` has no `SessionEvent` yet (nothing in
-        // the app consumes it until phase 2), so the probe reads the `ServerPacket` directly.
+        // Index the first duration packet and the first delta naming the buff by packet arrival;
+        // `SMSG_UPDATE_AURA_DURATION` is read off the `ServerPacket`, before decode.
         let mut durations: Vec<(u8, u32)> = Vec::new();
         let (mut seq, mut first_duration_at, mut buff_field_at) = (0usize, None, None);
         let drain_until = Instant::now() + Duration::from_secs(8);
@@ -124,10 +115,8 @@ impl Probe for Aura {
             .context(
                 "--aura: spell 1126 never appeared in UNIT_FIELD_AURA. Either the descriptor field \
                  index is wrong, or the GM `.aura` command was refused — it needs gmlevel >= 4 \
-                 (VERIFIED vmangos `Chat/Chat.cpp:1229`: SEC_BASIC_ADMIN, which is 4 in \
-                 `shared/Common.h:142`), and the slot-keyed probe accounts are gmlevel 6, so this \
-                 probe cannot run as `probeN` without a temporary grant (method.md, decision 0450's \
-                 precedent for --worldstate).",
+                 (vmangos `Chat/Chat.cpp:1229`: SEC_BASIC_ADMIN, which is 4 in \
+                 `shared/Common.h:142`).",
             )?;
         let debuff = auras
             .iter()
@@ -135,7 +124,6 @@ impl Probe for Aura {
             .copied()
             .context("--aura: spell 589 never appeared in UNIT_FIELD_AURA")?;
 
-        // The halves, the nibble, the level byte, the stack bias — each a distinct packing claim.
         ensure!(
             buff.is_helpful() && buff.slot < 32,
             "buff landed in the debuff half (slot {})",
@@ -170,8 +158,7 @@ impl Probe for Aura {
             debuff.stacks
         );
 
-        // Durations: keyed by slot, carrying what we asked for. `.aura` sets an exact duration, and
-        // the packet is sent immediately, so allow only for a tick of decay.
+        // `.aura` sets an exact duration and the packet goes out at once: allow 2 s of decay.
         for (label, aura, asked) in [
             ("buff", buff, AURA_BUFF_SECONDS),
             ("debuff", debuff, AURA_DEBUFF_SECONDS),
@@ -203,19 +190,18 @@ impl Probe for Aura {
         ensure!(
             d < v,
             "SMSG_UPDATE_AURA_DURATION arrived AFTER the descriptor delta (seq {d} vs {v}) — \
-             decision 0255's slot-keyed buffering is built on the opposite order"
+             the app's slot-keyed buffering is built on the opposite order"
         );
         println!("✅ duration packet precedes the descriptor delta (event {d} before {v})");
 
-        // Durations are apply/refresh EDGES, not a stream — the client counts down locally from
-        // here (the cast bar's model). An untouched slot must never have reported one.
+        // Durations are apply/refresh edges, not a stream; the client counts down locally.
         if let Some(&slot) = untouched
             .iter()
             .find(|s| durations.iter().any(|(d, _)| d == *s))
         {
             bail!(
                 "--aura: slot {slot} reported a duration without being (re)applied — durations are \
-                 not the apply/refresh edges decision 0255's client-side countdown assumes"
+                 not the apply/refresh edges the client-side countdown assumes"
             );
         }
         println!(
@@ -224,8 +210,8 @@ impl Probe for Aura {
             untouched.len()
         );
 
-        // Leave the character as found. The drain matters: `character_aura` persists across logout,
-        // so exiting before the server processes these would save the probe's buffs onto the char.
+        // Clean up, then drain: `character_aura` persists across logout, so an unprocessed
+        // `.unaura` would leave the probe's auras on the character.
         session.send_chat(&format!(".unaura {AURA_BUFF_SPELL}"))?;
         session.send_chat(&format!(".unaura {AURA_DEBUFF_SPELL}"))?;
         let settle = Instant::now() + Duration::from_secs(3);
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/charge.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/charge.rs
index aad30f08..ba1c80f7 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/charge.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/charge.rs
@@ -1,6 +1,6 @@
-//! `--charge`: warrior Charge (spell 100). GM `.learn 100`, teleport near the kobold camp, cast
-//! Charge at a creature 8–25 yd out, and require an `SMSG_MONSTER_MOVE` for our OWN guid (Charge is
-//! a self spline) — then ack the spline (`CMSG_MOVE_SPLINE_DONE`) and prove the stream survives.
+//! `--charge`: warrior Charge (spell 100) at a creature 8–25 yd out must bring an
+//! `SMSG_MONSTER_MOVE` for our own guid (a self spline), and the session must survive our
+//! `CMSG_MOVE_SPLINE_DONE` ack.
 
 use std::time::{Duration, Instant};
 
@@ -9,22 +9,17 @@ use benilla_protocol::{guid, EntityKind, SessionEvent};
 
 use crate::probes::{Ctx, Probe};
 
-/// The `--charge` probe spot: open ground ~18 yd west of the kobold camp ([`crate::world::ATTACK_TP`]),
-/// so the camp's kobolds stream in at charge range (8–25 yd) while we land *outside* the immediate
-/// aggro cluster — Charge refuses to fire while the caster is in combat, so we must cast before a
-/// kobold closes and engages us.
+/// Open ground about 18 yd west of the kobold camp: kobolds in charge range but outside aggro,
+/// since Charge refuses to fire while the caster is in combat.
 const CHARGE_TP: &str = ".go xyz -8798.71 -164.568 81.94";
 
 #[derive(Default)]
 pub(crate) struct Charge {
     charge_target: Option<u64>,
-    /// The pending self-spline ack: (endpoint, splineId, when-to-send). Captured from the self
-    /// `SMSG_MONSTER_MOVE`, sent after the ride's duration elapses — the round-trip that proves our
-    /// `CMSG_MOVE_SPLINE_DONE` wire is right (a malformed body drops the session).
+    /// The pending self-spline ack: (endpoint, splineId, when to send).
     charge_ack: Option<([f32; 3], u32, Instant)>,
     charge_acked: bool,
-    /// `World::total` snapshotted when the ack went out; `verify` reads `total - total_at_ack` as the
-    /// "packets after the ack" count (the old per-packet `msgs_after_ack` tally, exactly).
+    /// `World::total` when the ack went out, so `verify` can count the packets after it.
     total_at_ack: Option<u32>,
 }
 
@@ -37,10 +32,8 @@ impl Probe for Charge {
     }
 
     fn poll(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Fire Charge at a creature in range once we've landed. Charge needs the target 8–25 yd out,
-        // so pick the *farthest* streamed creature inside that band (maximises the odds of a valid
-        // range, and keeps clear of a kobold already on top of us). One shot — the first packet the
-        // server sends back for our own guid is the whole proof.
+        // Once landed, charge the farthest creature inside Charge's 8–25 yd band, clear of any
+        // kobold already on us. One shot.
         if self.charge_target.is_none() {
             if let Some(pos) = cx.world.attack_pos {
                 let pick = cx
@@ -58,9 +51,8 @@ impl Probe for Charge {
                     .filter(|(_, _, d)| (8.0..=25.0).contains(d))
                     .max_by(|a, b| a.2.total_cmp(&b.2));
                 if let Some((guid, tpos, dist)) = pick {
-                    // Face the target first — Charge refuses a target that isn't in front (reason 124,
-                    // SPELL_FAILED_UNIT_NOT_INFRONT). Report our facing with a Stop at the landing spot
-                    // (WoW orientation = atan2(Δy, Δx)), then select + cast.
+                    // Face it first: Charge refuses a target not in front (124,
+                    // `SPELL_FAILED_UNIT_NOT_INFRONT`). Orientation is `atan2(Δy, Δx)`.
                     let orientation = (tpos[1] - pos[1]).atan2(tpos[0] - pos[0]);
                     cx.session.stop(pos, orientation)?;
                     cx.session.set_selection(guid)?;
@@ -72,9 +64,8 @@ impl Probe for Charge {
                 }
             }
         }
-        // Ack the self-spline once its ride would have finished (`CMSG_MOVE_SPLINE_DONE` at the
-        // endpoint). The server holds a player mover as spline-pending until this arrives; a surviving
-        // stream afterward is the live proof the ack wire parses.
+        // Ack at the endpoint once the ride is over: the server holds a player mover
+        // spline-pending until `CMSG_MOVE_SPLINE_DONE` arrives.
         if let Some((endpoint, spline_id, at)) = self.charge_ack {
             if !self.charge_acked && Instant::now() >= at {
                 cx.session.move_spline_done(endpoint, 0.0, spline_id)?;
@@ -99,9 +90,7 @@ impl Probe for Charge {
             ..
         } = ev
         {
-            // Queue the SPLINE_DONE ack for once the ride would have finished:
-            // the endpoint is the last waypoint; send after `duration_ms` (+ a
-            // margin) so we don't ack a spline the server still thinks is running.
+            // Ack at the last waypoint after `duration_ms` plus a margin, never mid-spline.
             if *guid == cx.world.self_guid && self.charge_ack.is_none() && !*stop {
                 if let Some(&endpoint) = path.last() {
                     let at = Instant::now() + Duration::from_millis(u64::from(*duration_ms) + 200);
@@ -113,8 +102,6 @@ impl Probe for Charge {
     }
 
     fn verify(&mut self, cx: &mut Ctx) -> Result<()> {
-        // --charge verdict: the port must have landed, a target been found in range and Charge cast, and
-        // — the whole point — the server must have driven us with an SMSG_MONSTER_MOVE for our OWN guid.
         if cx.world.attack_pos.is_none() {
             bail!("--charge: the GM teleport never arrived (is the account gmlevel ≥ 2?)");
         }
@@ -126,8 +113,7 @@ impl Probe for Charge {
             bail!("--charge: cast Charge at {target:#x} but the server sent NO SMSG_MONSTER_MOVE for our guid (check the CAST_RESULT reason above — combat / range / stance)");
         }
         println!("✅ charge: {self_moves} self SMSG_MONSTER_MOVE — Charge drives the caster via a server spline (target {target:#x}).");
-        // The ack half: we sent CMSG_MOVE_SPLINE_DONE at the endpoint; a malformed body throws in the
-        // server's parser and drops us, so a stream that keeps flowing afterward is the live proof.
+        // A malformed ack body drops the session, so traffic after the ack proves it parsed.
         if self.charge_acked {
             let msgs_after_ack = cx.world.total
                 - self
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/death.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/death.rs
index f3e69a92..fe904c0a 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/death.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/death.rs
@@ -1,6 +1,6 @@
-//! `--death`: the death-arc slice-1 wire (decision 0308). The shared [`crate::world::DeathArc`] runs
-//! the die → release → ghost transition; this probe adds the corpse query, the self-revive cleanup,
-//! and the post-revive not-found re-query, then asserts the whole arc in wire order.
+//! `--death`: the death wire. [`crate::world::DeathArc`] runs die, release and the ghost
+//! transition; this probe adds the corpse query, a GM revive and a post-revive re-query that must
+//! find nothing, then checks the whole arc in wire order.
 
 use anyhow::{bail, Context, Result};
 use benilla_protocol::{EntityKind, SessionEvent};
@@ -12,22 +12,18 @@ pub(crate) struct Death {
     corpse_query_sent: bool,
     corpse_answer: Option<(bool, i32, [f32; 3], u32)>,
     revive_sent: bool,
-    /// The post-revive corpse re-query — the app's marker-drop mechanism (the server's own
-    /// "corpse gone" push is LOOTER-gated, vmangos Map.cpp:3617-3629, so a PvE res never sends
-    /// one; the client must re-ask and hear not-found). Director-reported: the map tombstone
-    /// survived a spirit-healer res before this was mirrored.
+    /// The post-revive corpse re-query: the server's "corpse gone" push goes only to looters
+    /// (`Map.cpp:3617-3629`), so after a PvE res the client must re-ask and hear not-found.
     post_revive_query_sent: bool,
     corpse_gone: Option<bool>,
     corpse_create: Option<(u64, [f32; 3])>,
-    /// The corpse descriptor's interaction bits at create: `(CORPSE_FIELD_FLAGS, owner, bones,
-    /// lootable, insignia)` — decision 1723's inputs, read off the wire rather than assumed.
+    /// The corpse descriptor at create: `(CORPSE_FIELD_FLAGS, owner, bones, lootable, insignia)`.
     corpse_flags: Option<(u32, u64, bool, bool, bool)>,
 }
 
 impl Probe for Death {
     fn poll(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Once we're a released ghost AND the graveyard teleport has landed, ask where our corpse
-        // is — the corpse-run marker's own source (decision 0308 §5).
+        // A released ghost at the graveyard asks where its corpse is (the corpse-run marker).
         if !self.corpse_query_sent {
             if let Some(arc) = &cx.world.death_arc {
                 if arc.ghost_seen && arc.graveyard_pos.is_some() {
@@ -37,9 +33,7 @@ impl Probe for Death {
                 }
             }
         }
-        // Once the corpse-query answer is in, GM-revive so the round trip leaves the character
-        // alive (cleanup, not part of the wire under test — a real player would corpse-run +
-        // CMSG_RECLAIM_CORPSE instead).
+        // Then GM-revive as cleanup; a real player corpse-runs and sends `CMSG_RECLAIM_CORPSE`.
         if !self.revive_sent && self.corpse_answer.is_some() {
             cx.session.send_chat(".revive")?;
             println!("sent GM: .revive (self-revive)");
@@ -48,8 +42,7 @@ impl Probe for Death {
                 arc.revive_initiated = true;
             }
         }
-        // Once revived, re-ask where the corpse is: the answer MUST be not-found (the corpse
-        // unbinds at SpawnCorpseBones) — the round trip the app's unghost-edge marker drop rides.
+        // Once revived, the re-query must find nothing: the corpse unbinds at `SpawnCorpseBones`.
         if !self.post_revive_query_sent {
             if let Some(arc) = &cx.world.death_arc {
                 if arc.revived_seen {
@@ -71,23 +64,13 @@ impl Probe for Death {
                 fields,
                 ..
             } => {
-                // --death: the corpse streams in once we've released (decision 0308 §4).
-                //
-                // **It is `EntityKind::Corpse`, not `Other`** — and this line said `Other` from
-                // 0308 until 1723 found it. 1706 gave TYPEID_CORPSE its own `EntityKind` variant;
-                // the compiler enumerated every `match` on the enum and corrected them, but this
-                // is an `==`, so it stayed silent and the probe's corpse capture quietly stopped
-                // firing: the arc would have bailed "the corpse object never streamed" on a wire
-                // that was perfectly correct. An instrument that fails closed after a refactor is
-                // the expensive kind (the contract §5 — the instruments are part of the codebase).
+                // The corpse streams in after release as `EntityKind::Corpse`; an `==` here, unlike
+                // a `match`, gets no compiler help if the variant changes.
                 let repop_sent = cx.world.death_arc.as_ref().is_some_and(|a| a.repop_sent);
                 if repop_sent && self.corpse_create.is_none() && *kind == EntityKind::Corpse {
                     self.corpse_create = Some((*guid, *position));
-                    // The descriptor bits the client's whole corpse interaction hangs off
-                    // (decision 1723): BONES picks the model, DYNAMIC_FLAGS bit 0 is the only
-                    // thing that opens the `CMSG_LOOT` route, FLAGS bit 5 is the PvP insignia the
-                    // skin leg reads. Printed rather than asserted — what vmangos actually sets on
-                    // a plain PvE death is a fact worth having in the log, not a pass/fail.
+                    // BONES picks the model, DYNAMIC_FLAGS bit 0 alone opens `CMSG_LOOT`, FLAGS
+                    // bit 5 is the PvP insignia. Printed, not asserted.
                     self.corpse_flags = Some((
                         fields.corpse_flags(),
                         fields.corpse_owner().unwrap_or(0),
@@ -132,9 +115,7 @@ impl Probe for Death {
             .as_ref()
             .expect("death_arc present when --death is set");
 
-        // --death verdict (decision 0308 slice 1): every signal in the release→ghost→corpse arc, in
-        // wire order — `bail!` on the first one that never arrived, so a partial run points straight
-        // at the phase that broke.
+        // Every signal of the arc in wire order, bailing on the first one missing.
         let death_pos = arc.death_pos.context(
             "--death: `.die` never dropped our health to 0 — is the account gmlevel ≥ 2?",
         )?;
@@ -153,9 +134,7 @@ impl Probe for Death {
         if !arc.ghost_seen {
             bail!("--death: PLAYER_FLAGS_GHOST (bit 0x10, field 190) never set");
         }
-        // Full 3D distance: the corpse/graveyard/query checks below all compare against where we
-        // died, and elevation is as telling as the ground plane (a graveyard directly below/above
-        // death, or a corpse object mis-z'd, are both real wire bugs — not noise to filter out).
+        // 3D distance from where we died: a wrong z is as much a wire bug as a wrong x or y.
         let dist3 = |a: [f32; 3], b: [f32; 3]| {
             ((a[0] - b[0]).powi(2) + (a[1] - b[1]).powi(2) + (a[2] - b[2]).powi(2)).sqrt()
         };
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/equip_pack_slot.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/equip_pack_slot.rs
index b2dd2884..fa35de9e 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/equip_pack_slot.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/equip_pack_slot.rs
@@ -1,5 +1,5 @@
-//! `--equip-pack-slot`: `CMSG_AUTOEQUIP_ITEM` on a 1-based backpack slot; require a server reaction
-//! (the guid landing in an equipment INV slot, or a decoded refusal), then swap it home.
+//! `--equip-pack-slot`: `CMSG_AUTOEQUIP_ITEM` on a 1-based backpack slot must land the item in an
+//! equipment slot or draw a refusal; the item is then swapped home.
 
 use std::time::{Duration, Instant};
 
@@ -18,7 +18,6 @@ impl Probe for EquipPackSlot {
         let session = &mut *cx.session;
         let n = self.n;
 
-        // --equip-pack-slot: auto-equip a real bag item and require a server reaction.
         let sf = world
             .self_fields
             .as_mut()
@@ -36,7 +35,7 @@ impl Probe for EquipPackSlot {
         session.auto_equip_item(255, 23 + n0)?;
         let drain_until = Instant::now() + Duration::from_secs(5);
         let mut verdict: Option<String> = None;
-        // The equipment INV slot the item landed in (Some once equipped) — so we can restore it.
+        // The equipment slot the item landed in, for the restore.
         let mut equipped_slot: Option<u8> = None;
         while Instant::now() < drain_until && verdict.is_none() {
             let Ok(msg) = session.recv() else { continue };
@@ -67,10 +66,8 @@ impl Probe for EquipPackSlot {
         let v = verdict.context("no reaction to CMSG_AUTOEQUIP_ITEM within 5s")?;
         println!("✅ auto-equip: {v}.");
 
-        // Restore: if we actually equipped it, SWAP_INV_ITEM the equipment slot back to the source
-        // backpack slot — moves the item home (and whatever it displaced back into place), leaving
-        // the character exactly as found. (The wire's both-slots-on-the-player addressing spans
-        // equipment 0-18 ↔ backpack 23-38.)
+        // Swap the equipment slot back to the backpack slot, which also returns anything it
+        // displaced. Player slots: equipment 0-18, backpack 23-38.
         if let Some(slot) = equipped_slot {
             println!(
                 "restoring: CMSG_SWAP_INV_ITEM equipment slot {slot} → backpack slot {}",
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/giverstatus.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/giverstatus.rs
index ff8768ca..d445e4f4 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/giverstatus.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/giverstatus.rs
@@ -1,5 +1,5 @@
-//! `--giverstatus`: the questgiver STATUS wire (the overhead `!`/`?` markers' data). Teleport onto
-//! Marshal McBride, `CMSG_QUESTGIVER_STATUS_QUERY` him, require an `SMSG_QUESTGIVER_STATUS` answer.
+//! `--giverstatus`: the questgiver status wire behind the overhead `!`/`?` markers.
+//! `CMSG_QUESTGIVER_STATUS_QUERY` on Marshal McBride must draw an `SMSG_QUESTGIVER_STATUS`.
 
 use std::time::{Duration, Instant};
 
@@ -12,10 +12,7 @@ pub(crate) struct GiverStatus;
 
 impl Probe for GiverStatus {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Same cleanup-then-teleport pattern as --quest (idempotent across re-runs); McBride is
-        // both giver and ender for quest 7, so one teleport (already onto him) suffices. Shared with
-        // --questlog: the `mcbride_staged` flag makes the two GM lines go out exactly once for a
-        // co-run, matching today's single `cli.questlog || cli.giverstatus` staging block.
+        // Shared with --questlog: `mcbride_staged` sends the cleanup and teleport once.
         if !cx.world.mcbride_staged {
             cx.session
                 .send_chat(&format!(".quest remove {QUESTLOG_ID}"))?;
@@ -32,10 +29,8 @@ impl Probe for GiverStatus {
         let world = &mut *cx.world;
         let session = &mut *cx.session;
 
-        // --giverstatus: live-verify the questgiver STATUS wire — the overhead `!`/`?` markers'
-        // data plane (CMSG_QUESTGIVER_STATUS_QUERY → SMSG_QUESTGIVER_STATUS, vmangos
-        // QuestHandler.cpp:36-77). Quest 7 was `.quest remove`d in the preamble, so McBride should
-        // answer AVAILABLE(5) for a fresh log.
+        // Quest 7 was removed in staging, so McBride answers AVAILABLE, 5
+        // (`QuestHandler.cpp:36-77`).
         let mcbride = world
             .tracked
             .iter()
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/groundfx.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/groundfx.rs
index 02e625da..fc1f744c 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/groundfx.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/groundfx.rs
@@ -1,11 +1,7 @@
-//! `--groundfx <spell_id>`: capture the **dest-anchored effect wire** a ground cast produces —
-//! the instrument for the B132 follow-up ("the cast lands but nothing shows"). GM-learn the
-//! spell, GM-fill mana (any class can then channel it), cast it at our own feet through the same
-//! `cast_spell_at_dest` body the client's world-click commit sends, and dump raw everything the
-//! server anchors at the point: every `DynamicObject` create (all `DYNAMICOBJECT_*` fields,
-//! labeled per vmangos `UpdateFields_1_12_1.h`), the `SPELL_GO`, and the removal edge with its
-//! measured lifetime. Run with `--seconds 25`+ so a channeled spell's whole life fits the window
-//! (Blizzard 10 channels 8 s and its object outlives the channel).
+//! `--groundfx <spell_id>`: the effect wire of a ground cast. Learns the spell, fills mana, casts
+//! it at our feet with the body a world click sends (`cast_spell_at_dest`), and dumps every
+//! `DynamicObject` create, the `SPELL_GO` and the removal with its lifetime. Blizzard (spell 10)
+//! channels 8 s and its object outlives the channel, so run with `--seconds 25`.
 
 use std::time::Instant;
 
@@ -40,18 +36,16 @@ fn dyn_field_is_f32(index: u16) -> bool {
     matches!(index, 4 | 10..=14)
 }
 
-/// `UNIT_FIELD_POWER1` (mana) for 1.12.1 — `OBJECT_END(6) + 0x11` (vmangos
-/// `UpdateFields_1_12_1.h:50`). The mana-ack gate below watches this on the self guid.
+/// `UNIT_FIELD_POWER1` (mana): `OBJECT_END` (6) + 0x11 (`UpdateFields_1_12_1.h:50`).
 const FIELD_UNIT_POWER1: u16 = 6 + 0x11;
 
 pub(crate) struct GroundFx {
     spell: u32,
     staged: bool,
     known: bool,
-    /// Set when the self unit's `UNIT_FIELD_POWER1` echoes the GM fill — BOTH chat commands
-    /// (`.learn`, `.modify mana`) execute deferred, and each needs its own server-side evidence
-    /// before the cast: a cast in the learn's batch is dropped as unknown (decision 0792's trap),
-    /// and one in the mana fill's batch refuses with no-power (observed live, reason 77).
+    /// Set once our `UNIT_FIELD_POWER1` shows the fill. `.learn` and `.modify mana` run deferred:
+    /// a cast before the learn lands is dropped as unknown, one before the fill fails with no
+    /// power (reason 77).
     mana_seen: bool,
     cast_sent: Option<Instant>,
     /// DynamicObject creates seen: (guid, seen-at, spell id from field 9).
@@ -77,10 +71,8 @@ impl GroundFx {
 
 impl Probe for GroundFx {
     fn poll(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Stage once the book is in: GM-learn the spell (skipped if already known — a prior run's
-        // leftover) and fill a mana pool any class can spend (the probe char may be a warrior).
-        // Both chat commands execute DEFERRED server-side, so the cast waits for the
-        // SMSG_LEARNED_SPELL ack (the same trap the --spells dest phase hit, decision 0792).
+        // Once the spell book is in, learn the spell unless known and fill mana, which any class
+        // can spend; the cast then waits for `SMSG_LEARNED_SPELL`.
         if !self.staged {
             let Some(book) = &cx.world.spell_book else {
                 return Ok(());
@@ -113,8 +105,7 @@ impl Probe for GroundFx {
             SessionEvent::SpellLearned { spell_id } if *spell_id == self.spell => {
                 self.known = true;
             }
-            // The mana-ack gate: the self unit's POWER1 showing a real pool — either the login
-            // create (a mage arrives full) or the `.modify mana` echo (the warrior's fill).
+            // The mana gate: our POWER1 shows a real pool, at login or after `.modify mana`.
             SessionEvent::ObjectCreate { guid, fields, .. }
             | SessionEvent::ObjectValues { guid, fields }
                 if *guid == cx.world.self_guid && !self.mana_seen =>
@@ -127,8 +118,7 @@ impl Probe for GroundFx {
                     println!("groundfx: self mana visible — the cast gate is open");
                 }
             }
-            // vmangos sends UPDATEFLAG_HAS_POSITION on every dynobj create, so the position is
-            // always live here. Field 9 (SPELLID) is dumped with the rest raw.
+            // Every vmangos dynobj create has `UPDATEFLAG_HAS_POSITION`, so the position is real.
             SessionEvent::ObjectCreate {
                 guid,
                 kind: EntityKind::DynamicObject,
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/loot.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/loot.rs
index 2c3431f1..28c3f948 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/loot.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/loot.rs
@@ -1,6 +1,6 @@
-//! `--loot`: the solo-loot wire (decision 0084 §1). Select a target, GM-kill it, wait for the
-//! lootable dynamic flag, teleport onto the corpse, `CMSG_LOOT`, AUTOSTORE every row, LOOT_MONEY if
-//! it carried gold, then LOOT_RELEASE — printing every loot-related packet decoded.
+//! `--loot`: the solo-loot wire. GM-kills a target, waits for it to turn lootable, teleports onto
+//! the corpse, then `CMSG_LOOT`, stores every row, takes the money and releases, printing every
+//! loot packet.
 
 use std::time::{Duration, Instant};
 
@@ -16,9 +16,7 @@ pub(crate) struct Loot {
 
 impl Probe for Loot {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // --loot reuses the --attack teleport spot to guarantee a killable creature in range when no
-        // explicit --loot-guid was given; avoid sending it twice if both flags are set (the shared
-        // `attack_tp_staged` flag — attack/loot/DeathArc all key off it).
+        // Without --loot-guid, use the --attack teleport for a creature in range; sent once.
         if self.loot_guid.is_none() && !cx.world.attack_tp_staged {
             cx.session.send_chat(ATTACK_TP)?;
             cx.world.attack_tp_staged = true;
@@ -32,20 +30,8 @@ impl Probe for Loot {
         let session = &mut *cx.session;
         let self_guid = world.self_guid;
 
-        // --loot: kill + loot a creature end-to-end (decision 0084 §1). Select the target (explicit
-        // --loot-guid, or the nearest streamed creature to the --attack teleport spot), GM-kill it
-        // (a GM `.damage` acts on the selected unit regardless of range), wait for the corpse's
-        // lootable dynamic flag, GM-teleport directly onto the (now-stationary) corpse — `--attack`'s
-        // ~20yd melee-swing search is far looser than the actual loot-range check
-        // (`Player::GetMaxLootDistance`, VERIFIED vmangos `Player.cpp:15472-15476`, a tight
-        // combat-reach distance), and Northshire's mobs wander enough that "nearest at landing" is
-        // routinely just outside it by the time the kill lands — then CMSG_LOOT it, decode the
-        // response, AUTOSTORE every row, LOOT_MONEY if it carried gold, then LOOT_RELEASE. Prints
-        // every loot-related packet decoded.
-        // Candidate targets: the explicit --loot-guid, or the nearest few streamed creatures. A
-        // list, not one — the nearest creature can be a corpse a previous run already looted
-        // (dead until respawn, so `.damage` does nothing and it never goes lootable); trying the
-        // next-nearest instead makes back-to-back probe runs reliable.
+        // `.damage` hits the selected unit at any range. The nearest three creatures are tried,
+        // since the nearest may be a corpse an earlier run already looted.
         let candidates: Vec<u64> = if let Some(g) = self.loot_guid {
             vec![g]
         } else {
@@ -69,8 +55,7 @@ impl Probe for Loot {
             bail!("--loot: no creature streamed in (try --loot-guid)");
         }
 
-        // Kill candidates until one shows the corpse's lootable dynamic flag (UNIT_DYNFLAG_LOOTABLE,
-        // bit 0x1 — VERIFIED vmangos `SharedDefines.h:1153`).
+        // Kill until one turns lootable: `UNIT_DYNFLAG_LOOTABLE` 0x1 (`SharedDefines.h:1153`).
         let mut target = 0u64;
         let mut lootable = false;
         for &candidate in &candidates {
@@ -108,12 +93,9 @@ impl Probe for Loot {
         }
         println!("✅ {target:#x} is lootable (UNIT_DYNFLAG_LOOTABLE set)");
 
-        // Reposition directly onto the (now-stationary) corpse before looting — see the block
-        // comment above for why "nearest at landing" isn't reliably in loot range. The tracked
-        // position itself can lag where the creature actually died (a mid-spline kill reports the
-        // spline's last waypoint, not the death spot), and `GetMaxLootDistance` is combat-reach
-        // tight — so on a TOO_FAR refusal, drain (refreshing tracked positions) and retry with the
-        // updated spot instead of failing the run on instrument flakiness.
+        // Teleport onto the corpse: loot range is combat reach (`Player.cpp:15472-15476`), and a
+        // mid-spline kill leaves the tracked position at the spline's last waypoint, so a TOO_FAR
+        // refusal retries from the refreshed spot.
         let mut response: Option<(u8, u32, Vec<benilla_protocol::messages::LootItem>)> = None;
         let mut loot_refusal: Option<u8> = None;
         for attempt in 1..=3 {
@@ -149,8 +131,7 @@ impl Probe for Loot {
             loot_refusal = None;
             session.loot(target)?;
 
-            // Drain for SMSG_LOOT_RESPONSE (either shape), keeping tracked positions fresh so a
-            // retry teleports to the corpse's *corrected* spot.
+            // Drain for either `SMSG_LOOT_RESPONSE` shape, refreshing positions for a retry.
             let drain_until = Instant::now() + Duration::from_secs(5);
             while Instant::now() < drain_until && response.is_none() && loot_refusal.is_none() {
                 let Ok(msg) = session.recv() else { continue };
@@ -179,10 +160,8 @@ impl Probe for Loot {
                             }
                             response = Some((loot_type, gold, items));
                         }
-                        // The master-loot candidate list rides the window OPEN, ahead of the
-                        // response it belongs to, and it is the one part of the master-loot arc
-                        // that cannot be staged from a single probe account (decision 1675). It
-                        // is printed unconditionally — it carries no loot guid to match on.
+                        // The master-loot list arrives ahead of its response and carries no loot
+                        // guid, so it is printed unconditionally.
                         SessionEvent::LootMasterList { candidates } => {
                             println!(
                                 "SMSG_LOOT_MASTER_LIST: {} eligible looter(s)",
@@ -225,8 +204,7 @@ impl Probe for Loot {
         let (loot_type, gold, items) =
             response.context("--loot: no SMSG_LOOT_RESPONSE arrived within 5s")?;
 
-        // AUTOSTORE every row, watching for the LOOT_REMOVED + ITEM_PUSH_RESULT + bag ItemCreate
-        // each one drives.
+        // Store every row; each drives LOOT_REMOVED, ITEM_PUSH_RESULT and a bag ItemCreate.
         let mut removed_slots: Vec<u8> = Vec::new();
         let mut pushes: Vec<benilla_protocol::messages::ItemPushResult> = Vec::new();
         let mut items_created: Vec<u64> = Vec::new();
@@ -286,25 +264,9 @@ impl Probe for Loot {
             items_created.len()
         );
 
-        // LOOT_MONEY, only if the response actually carried gold.
-        //
-        // Live-verified departure from the pin: this vmangos build never sends
-        // SMSG_LOOT_MONEY_NOTIFY for a solo (ungrouped) looter — `LootHandler.cpp`'s
-        // `HandleLootMoneyOpcode` comments out `player->SendLootMoneyNotify(pLoot->gold)` for the
-        // non-group branch ("in wotlk and after this should be sent for solo looting too") and
-        // applies the money silently via `Player::LootMoney` (a `PLAYER_FIELD_COINAGE` delta)
-        // instead. Only `SMSG_LOOT_CLEAR_MONEY` fires. So the pass criterion here is CLEAR_MONEY +
-        // a coinage delta on our own guid, with the notify event accepted too (group loot, or a
-        // future server that un-comments it).
-        //
-        // `NotifyMoneyRemoved` (CLEAR_MONEY) sends immediately; `LootMoney`'s
-        // `PLAYER_FIELD_COINAGE` write reaches us on the ordinary dirty-field broadcast tick, not
-        // synchronously with CLEAR_MONEY. NOTE the loot flow guarantees *unrelated* self values
-        // updates in the same window (the server toggles `UNIT_FLAG_LOOTING` on us at
-        // `SendLoot`/release) — so "a self values update arrived" is NOT "the coinage delta
-        // arrived"; only an actual change of `player_money()` counts (the original drain exited on
-        // the flags-only update, read an unchanged purse, and mis-reported the money as lost —
-        // the DB was always correct).
+        // vmangos sends no `SMSG_LOOT_MONEY_NOTIFY` to a solo looter (commented out in
+        // `HandleLootMoneyOpcode`): `SMSG_LOOT_CLEAR_MONEY` comes at once and the money as a later
+        // `PLAYER_FIELD_COINAGE` delta. The notify still counts, for group loot.
         if gold > 0 {
             let money_before = world.self_fields.as_ref().and_then(|sf| sf.player_money());
             println!(
@@ -332,9 +294,8 @@ impl Probe for Loot {
                         SessionEvent::ObjectValues { guid: g, fields } if g == self_guid => {
                             if let Some(sf) = &mut world.self_fields {
                                 sf.merge(fields);
-                                // Only a *changed* purse is the coinage delta — the loot flow also
-                                // pushes flags-only self updates (UNIT_FLAG_LOOTING), and treating
-                                // those as "the money arrived" mis-reads an unchanged purse as lost.
+                                // Only a changed purse counts: the loot flow also pushes
+                                // flags-only self updates (`UNIT_FLAG_LOOTING`).
                                 if sf.player_money() != money_before {
                                     money_after = sf.player_money();
                                 }
@@ -371,7 +332,6 @@ impl Probe for Loot {
             println!("(no gold on this corpse — skipping CMSG_LOOT_MONEY)");
         }
 
-        // RELEASE.
         println!("sending CMSG_LOOT_RELEASE");
         session.loot_release(target)?;
         let mut released = false;
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/mod.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/mod.rs
index 82b199f2..a3200306 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/mod.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/mod.rs
@@ -1,20 +1,17 @@
-//! The probe registry: one file per `--flag` scenario, each a self-contained [`Probe`] with a
-//! uniform lifecycle. Registration order (in `main`) = today's stream-loop/verify block order, so
-//! output and execution order are preserved.
+//! The probes: one file per `--flag` scenario, each a [`Probe`] run in registration order.
 
 use anyhow::Result;
 use benilla_protocol::{SessionEvent, WorldSession};
 
 use crate::world::World;
 
-/// What a [`Probe`]'s lifecycle methods borrow: the live session (to send) + the shared [`World`].
+/// What a [`Probe`]'s lifecycle methods borrow: the live session and the shared [`World`].
 pub(crate) struct Ctx<'a> {
     pub session: &'a mut WorldSession,
     pub world: &'a mut World,
 }
 
-/// One scripted wire-verification scenario. Registered from a `--flag`; the pump drives every
-/// registered probe through this lifecycle in registration order.
+/// One scripted wire-verification scenario, driven through this lifecycle in registration order.
 pub(crate) trait Probe {
     /// One-time pre-stream staging (GM teleports, cleanup commands).
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
@@ -26,37 +23,30 @@ pub(crate) trait Probe {
         let _ = cx;
         Ok(())
     }
-    /// Every decoded event, AFTER [`World::on_event`] has processed it.
+    /// Every decoded event, after [`World::on_event`] has processed it.
     fn on_event(&mut self, ev: &SessionEvent, cx: &mut Ctx) -> Result<()> {
         let _ = (ev, cx);
         Ok(())
     }
-    /// Post-stream: assertions + follow-up round trips (each block's bespoke drains move verbatim).
+    /// Post-stream: assertions and follow-up round trips.
     fn verify(&mut self, cx: &mut Ctx) -> Result<()> {
         let _ = cx;
         Ok(())
     }
 }
 
-// Quest consts shared by more than one probe (put here rather than `pub(super)` in quest.rs
-// because giverstatus/questlog re-use them and neither is quest.rs's child).
+// Quest constants shared by several probes.
 
-/// Marshal McBride's teleport spot — the `--quest` turn-in NPC, and the `--questlog`/`--giverstatus`
-/// stage target (McBride is quest 7's giver *and* ender).
+/// Onto Marshal McBride, the `--quest` turn-in NPC and quest 7's giver and ender.
 pub(crate) const QUEST_TURNIN_TP: &str = ".go xyz -8902.59 -162.606 82.0223"; // onto Marshal McBride
-pub(crate) const QUEST_TURNIN_ENTRY: u32 = 197; // Marshal McBride — takes 783
-/// `PLAYER_QUEST_LOG_1_1` UpdateField index for 1.12.1 (UNIT_END 188 + 0xA), 3 fields per slot ×
-/// 20 slots (vmangos `UpdateFields_1_12_1.h:128`).
+pub(crate) const QUEST_TURNIN_ENTRY: u32 = 197; // Marshal McBride, who takes 783
+/// `PLAYER_QUEST_LOG_1_1`: `UNIT_END` (188) + 0xA, 3 fields per slot for 20 slots
+/// (`UpdateFields_1_12_1.h:128`).
 pub(crate) const FIELD_PLAYER_QUEST_LOG_1_1: u16 = 198;
 
-/// The `--questlog` probe target: quest 7 "Kobold Camp Cleanup" — Marshal McBride (entry 197, the
-/// same NPC [`QUEST_TURNIN_TP`]/[`QUEST_TURNIN_ENTRY`] already land on) is *both* giver and ender
-/// (VERIFIED live against the running vmangos: `mangos.creature_questrelation` and
-/// `creature_involvedrelation` each carry exactly one row for quest 7, both `197`). Its one
-/// objective — kill 10 of creature entry 6 (Kobold) — is a real `required_count > 0` slot, unlike
-/// 783's report-only "A Threat Within" the `--quest` probe turns in; a GM `.quest complete`
-/// substitutes for the grind, same as `--quest`. Shared with `--giverstatus`, which `.quest remove`s
-/// it in staging so McBride reads AVAILABLE for a fresh log.
+/// Quest 7 "Kobold Camp Cleanup": Marshal McBride (197) gives and takes it
+/// (`creature_questrelation`, `creature_involvedrelation`), and its objective, 10 kills of entry
+/// 6, is a real counted slot, unlike 783's report-only "A Threat Within".
 pub(crate) const QUESTLOG_ID: u32 = 7;
 
 mod attack;
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/mount_tele.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/mount_tele.rs
index 731d9cf4..eab01b8d 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/mount_tele.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/mount_tele.rs
@@ -1,19 +1,11 @@
-//! `--mount-tele`: **what the server actually sends when a teleport dismounts you** — B213's wire.
+//! `--mount-tele`: what the server sends when a teleport dismounts you. vmangos strips the mount
+//! in `HandleMoveWorldportAckOpcode` right after the destination's own create block
+//! (`Map::Add` → `SendInitSelf`, then `RemoveSpellsCausingAura(SPELL_AURA_MOUNTED)` unless
+//! `IsMountAllowed`), so the two arrive back to back in one tick.
 //!
-//! The report: mount up, teleport somewhere that forbids mounting, and the auto-dismount leaves the
-//! mount's run speed on your feet. vmangos does that strip inside the worldport ack handler, three
-//! statements after the destination map's own create block goes out
-//! (`MovementHandler.cpp` `HandleMoveWorldportAckOpcode`: `Map::Add` → `SendInitSelf`, then
-//! `if (!mEntry->IsMountAllowed()) RemoveSpellsCausingAura(SPELL_AURA_MOUNTED)`), so the two land
-//! back to back in one tick. Reading the source says they *should*; this probe measures that they
-//! *do*, on the running deploy, and prints the gap.
-//!
-//! The scenario: `.aura` a real mount spell on open ground (a genuine `SPELL_AURA_MOUNTED` holder —
-//! `.modify mount` sets a display id with no aura and would never be stripped), require the mounted
-//! `SMSG_FORCE_RUN_SPEED_CHANGE`, then `.go xyz` into a dungeon map and require, in order: the
-//! `SMSG_NEW_WORLD`, a self create block still carrying the **mounted** run speed, and the
-//! dismount's `SMSG_FORCE_RUN_SPEED_CHANGE` back at base. Needs a GM account (the deploy's probes
-//! are gmlevel 6).
+//! Mounts with `.aura` on open ground, then `.go xyz` into a dungeon, and requires in order
+//! `SMSG_NEW_WORLD`, a self create block still at the mounted run speed, and the dismount's
+//! `SMSG_FORCE_RUN_SPEED_CHANGE` back to base, printing the gap. Needs GM.
 
 use std::time::Instant;
 
@@ -23,24 +15,21 @@ use benilla_protocol::{SessionEvent, SpeedKind};
 use crate::probes::{Ctx, Probe};
 use crate::world::ATTACK_TP;
 
-/// Brown Horse (the 60% apprentice mount): `SPELL_AURA_MOUNTED` + `SPELL_AURA_MOD_INCREASE_MOUNTED_SPEED`,
-/// so `.aura` on it produces the same holder a real mount cast would — the one
-/// `RemoveSpellsCausingAura(SPELL_AURA_MOUNTED)` goes looking for.
+/// Brown Horse (60%): `SPELL_AURA_MOUNTED` + `SPELL_AURA_MOD_INCREASE_MOUNTED_SPEED`, so `.aura`
+/// makes the holder a real mount cast would; `.modify mount` sets only a display id.
 const MOUNT_SPELL: u32 = 458;
 
 /// Ragefire Chasm. A dungeon, and not one of `MapEntry::IsMountAllowed`'s four exceptions
 /// (Zul'Gurub, Zul'Farrak, AQ Ruins, Caverns of Time), so arriving there strips the mount.
 const DUNGEON_MAP: u32 = 389;
 
-/// Inside Ragefire Chasm's entrance. The landing spot does not matter — the packets we want are
-/// sent by the arrival itself — but a real one keeps the character somewhere sane if a run is
-/// interrupted before the exit teleport in `verify`.
+/// Inside Ragefire Chasm's entrance, a sane place to be stranded if a run is interrupted.
 const DUNGEON_TP: &str = ".go xyz 3.0 -14.0 -18.0 389";
 
-/// 1.12.1's base run speed (yd/s) — the value the strip must come back to.
+/// The 1.12 base run speed (yd/s), which the strip restores.
 const BASE_RUN: f32 = 7.0;
 
-/// The map the scenario has to start on — open ground where a mount is allowed.
+/// The starting map: open ground where a mount is allowed.
 const OUTDOOR_MAP: u32 = 0;
 
 #[derive(Default)]
@@ -60,11 +49,9 @@ pub(crate) struct MountTele {
 
 impl Probe for MountTele {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Get onto open ground and clean of any leftover holder FIRST — an interrupted earlier run
-        // can leave the character mounted inside the dungeon, and from there the scenario's own
-        // teleport is a same-map port that sends no `SMSG_NEW_WORLD` at all. The map id is
-        // explicit for the same reason `verify`'s exit is (`.go xyz`'s map argument defaults to
-        // the map you are standing on). Mounting waits for the arrival, in `poll`.
+        // Unmount and go outdoors first: from inside the dungeon the scenario's teleport would be
+        // a same-map port, which sends no `SMSG_NEW_WORLD`. `.go xyz` defaults to the current map,
+        // so the map id is explicit.
         cx.session.send_chat(&format!(".unaura {MOUNT_SPELL}"))?;
         cx.session
             .send_chat(&format!("{ATTACK_TP} {OUTDOOR_MAP}"))?;
@@ -74,9 +61,8 @@ impl Probe for MountTele {
 
     fn on_event(&mut self, ev: &SessionEvent, cx: &mut Ctx) -> Result<()> {
         match ev {
-            // The mount landed: its speed change is our cue to teleport. Gate on the *tracked*
-            // self like `--speed` does — World only acks once our pose is known, and an unacked
-            // change is one vmangos has not applied yet.
+            // The mounted speed change cues the teleport, gated on a tracked self: `World` acks
+            // only once our pose is known, and vmangos applies no change before its ack.
             SessionEvent::ForceSpeedChange {
                 guid, kind, speed, ..
             } if *guid == cx.world.self_guid && *kind == SpeedKind::Run => {
@@ -84,8 +70,7 @@ impl Probe for MountTele {
                     return Ok(());
                 }
                 if self.ported {
-                    // Post-arrival: the first Run change after the destination's create block is
-                    // the dismount we came for.
+                    // After arrival, the first Run change after the create block is the dismount.
                     if self.create_after.is_some() && self.strip_after.is_none() {
                         self.strip_after = Some((*speed, Instant::now()));
                     }
@@ -94,15 +79,13 @@ impl Probe for MountTele {
                     println!("mounted: run {speed} yd/s — teleporting into map {DUNGEON_MAP}");
                 }
             }
-            // `SMSG_LOGIN_VERIFY_WORLD` decodes to this too, so login itself announces map 0 —
-            // gate on having actually sent the teleport, or the whole scenario latches onto the
-            // login and every later check reads the wrong packets.
+            // `SMSG_LOGIN_VERIFY_WORLD` also decodes to this: gate on the teleport being sent.
             SessionEvent::Worldport { map_id, .. } if self.ported && self.arrived.is_none() => {
                 self.arrived = Some((*map_id, Instant::now()));
                 println!("SMSG_NEW_WORLD: map {map_id}");
             }
-            // Our own create on the destination map — sent by `Map::Add` → `SendInitSelf`, before
-            // the strip. Its LIVING block is the speed set the client seeds a fresh entity with.
+            // Our create on the new map, from `SendInitSelf` before the strip; its LIVING block
+            // seeds a fresh entity's speeds.
             SessionEvent::ObjectCreate { guid, speeds, .. }
                 if *guid == cx.world.self_guid && self.ported && self.arrived.is_some() =>
             {
@@ -117,8 +100,7 @@ impl Probe for MountTele {
     }
 
     fn poll(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Mount only once the staging teleport has actually landed us outdoors — proving the run's
-        // starting state from a packet rather than assuming it (`method.md` step 6).
+        // Mount only once the staging teleport has landed us outdoors.
         if !self.mount_requested && cx.world.self_map == OUTDOOR_MAP {
             self.mount_requested = true;
             cx.session.send_chat(&format!(".aura {MOUNT_SPELL}"))?;
@@ -135,17 +117,13 @@ impl Probe for MountTele {
     }
 
     fn verify(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Leave the character as found before asserting: a failed run must not strand it in a
-        // dungeon on a mount. The exit names map 0 explicitly — `.go xyz`'s map argument is
-        // OPTIONAL and defaults to the map you are standing on, so the bare [`ATTACK_TP`] would
-        // port us to Northshire's coordinates *inside Ragefire Chasm*.
+        // Restore before asserting. The exit names map 0: `.go xyz` defaults to the current map,
+        // so a bare `ATTACK_TP` would land on Northshire's coordinates inside Ragefire Chasm.
         cx.session.send_chat(&format!(".unaura {MOUNT_SPELL}"))?;
         cx.session
             .send_chat(&format!("{ATTACK_TP} {OUTDOOR_MAP}"))?;
-        // …and stay on the wire long enough to ACK that exit port. A far teleport the client never
-        // acks does not happen: dropping the session here would leave the probe character standing
-        // in a dungeon for the next run to find. Bounded, and only advisory — `stage` recovers from
-        // a stranded character anyway, so a quiet stream here is not a failure.
+        // Stay to ack the exit port: a far teleport the client never acks does not happen.
+        // Advisory only, since `stage` recovers a stranded character.
         let until = Instant::now() + std::time::Duration::from_secs(5);
         while Instant::now() < until && cx.world.self_map != OUTDOOR_MAP {
             match cx.session.recv() {
@@ -184,8 +162,8 @@ impl Probe for MountTele {
         ensure!(
             (create_run - mounted).abs() < 0.01,
             "--mount-tele: the destination's create block should still carry the MOUNTED run \
-             speed ({mounted}), got {create_run} — the strip would then precede the create and \
-             B213's ordering would not be this one"
+             speed ({mounted}), got {create_run} — the strip would then precede the create, \
+             the opposite of the order this probe expects"
         );
         ensure!(
             (strip_run - BASE_RUN).abs() < 0.01,
@@ -196,15 +174,14 @@ impl Probe for MountTele {
             "\n--mount-tele PASS: arrived on map {map}; create block carried the mount's \
              {create_run} yd/s, the dismount's SMSG_FORCE_RUN_SPEED_CHANGE followed {} µs later \
              at {strip_run} yd/s.\n  Both packets are written by one HandleMoveWorldportAckOpcode \
-             call, so a client that drains its socket once a frame sees them in ONE drain — which \
-             is what B213 (decision 1478) turns on.",
+             call, so a client that drains its socket once a frame sees them in ONE drain.",
             gap.as_micros()
         );
         Ok(())
     }
 }
 
-/// `Option::ok_or_else` with the probe's message shape, so each `verify` line reads as one claim.
+/// `Option::ok_or_else` with a message, so each `verify` line reads as one claim.
 trait EnsureSome<T> {
     fn ensure_some(&self, msg: &str) -> Result<T>;
 }
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/open_item.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/open_item.rs
index e425fe0f..19283d31 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/open_item.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/open_item.rs
@@ -1,13 +1,7 @@
-//! `--open-item`: the openable-item wire — the fork a bag right-click makes when the clicked
-//! item's template carries the LOOTABLE bit (`ItemInfo::openable`). The client does NOT send
-//! `CMSG_USE_ITEM` for such an item (a clam has no on-use spell at all, so the use goes nowhere —
-//! the director's "there is no way to open clams"): it sends `CMSG_OPEN_ITEM(bagIndex, slot)`, and
-//! the server answers `SMSG_LOOT_RESPONSE` **on the item's own guid**, i.e. a loot window over a
-//! thing in your bag rather than a corpse in the world.
-//!
-//! This probe proves the whole round trip against the live server: add a clam, open it by bag
-//! position, require a loot response carrying rows on that guid, then release the window and
-//! subtract the copy so the character is left as found.
+//! `--open-item`: the openable-item wire. A bag right-click on an item whose template carries
+//! LOOTABLE (`ItemInfo::openable`) sends `CMSG_OPEN_ITEM(bagIndex, slot)`, never `CMSG_USE_ITEM`,
+//! and the server answers `SMSG_LOOT_RESPONSE` on the item's own guid. Adds a clam, opens it,
+//! releases the window and removes the clam.
 
 use std::time::{Duration, Instant};
 
@@ -16,9 +10,7 @@ use benilla_protocol::{decode, SessionEvent};
 
 use crate::probes::{Ctx, Probe};
 
-/// The probe target: "Small Barnacled Clam" (entry 7973) — the director's own case. Template
-/// `Flags` carries LOOTABLE (`0x4`) with `LockID = 0`, so it is openable the moment it exists: no
-/// key, no lockpicking, no rigging. Its `item_loot_template` rows are what come back.
+/// Small Barnacled Clam: `Flags` has LOOTABLE (0x4) and `LockID` is 0, so it opens as is.
 const ITEM_ENTRY: u32 = 7973;
 
 pub(crate) struct OpenItem;
@@ -34,8 +26,7 @@ impl Probe for OpenItem {
         let world = &mut *cx.world;
         let session = &mut *cx.session;
 
-        // 1) Find the clam in the backpack, and remember WHICH slot — the wire addresses the item
-        // by position (bag 255 + the absolute player-array slot), never by guid.
+        // 1) Find the clam: the wire addresses it by position (bag 255, player slot), not guid.
         let sf = world
             .self_fields
             .as_ref()
@@ -56,8 +47,7 @@ impl Probe for OpenItem {
             slot0 + 1
         );
 
-        // 2) The fork's own packet. A loot response on the ITEM's guid is the proof: nothing else
-        // in the protocol opens a loot window over a bag position.
+        // 2) Open it: nothing else opens a loot window on a bag item's own guid.
         session.open_item(255, wire_slot)?;
         let drain_until = Instant::now() + Duration::from_secs(5);
         let mut verdict: Option<Result<String, String>> = None;
@@ -100,7 +90,7 @@ impl Probe for OpenItem {
             .map_err(|e| anyhow::anyhow!("--open-item: {e}"))?;
         println!("✅ open item: {v}");
 
-        // 3) Close the window again — an abandoned loot session would follow the character.
+        // 3) Close the window, or the loot session stays with the character.
         session.loot_release(item_guid)?;
         let until = Instant::now() + Duration::from_secs(2);
         while Instant::now() < until {
@@ -114,7 +104,7 @@ impl Probe for OpenItem {
             }
         }
 
-        // Leave the probe character as found (the clam survives an un-emptied open).
+        // Remove the clam, which survives an open that is not emptied.
         session.send_chat(&format!(".additem {ITEM_ENTRY} -1"))?;
         println!("cleanup: .additem {ITEM_ENTRY} -1");
         Ok(())
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/query_names.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/query_names.rs
index 64277e86..121450ad 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/query_names.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/query_names.rs
@@ -1,5 +1,5 @@
-//! `--query-names`: the name-query pair. Ask our own name (`CMSG_NAME_QUERY`) at staging and the
-//! first streamed creature's template name (`CMSG_CREATURE_QUERY`), require both to arrive and parse.
+//! `--query-names`: the name-query pair. `CMSG_NAME_QUERY` for our own name and
+//! `CMSG_CREATURE_QUERY` for the first streamed creature must both be answered and parse.
 
 use anyhow::{bail, Context, Result};
 use benilla_protocol::{guid, EntityKind};
@@ -40,8 +40,7 @@ impl Probe for QueryNames {
     }
 
     fn verify(&mut self, cx: &mut Ctx) -> Result<()> {
-        // --query-names verdict: both answers must have arrived and parsed (the creature one only if a
-        // creature streamed in at all).
+        // The creature answer is required only if a creature streamed in.
         let own = cx
             .world
             .player_name_answer
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/quest.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/quest.rs
index 7142bd87..fe579feb 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/quest.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/quest.rs
@@ -1,6 +1,5 @@
-//! `--quest`: accept + turn in a real quest end-to-end (decision 0088). GM-teleport onto Deputy
-//! Willem, run the full questgiver wire (details → accept → complete → request/offer reward → choose
-//! reward → quest-complete), verified against `PLAYER_QUEST_LOG` + `PLAYER_XP`.
+//! `--quest`: accepts and turns in a real quest over the whole questgiver wire (details, accept,
+//! complete, reward, quest-complete), checked against `PLAYER_QUEST_LOG` and `PLAYER_XP`.
 
 use std::time::{Duration, Instant};
 
@@ -9,30 +8,21 @@ use benilla_protocol::{decode, guid, EntityKind, SessionEvent, WorldSession};
 
 use crate::probes::{Ctx, Probe, FIELD_PLAYER_QUEST_LOG_1_1, QUEST_TURNIN_ENTRY, QUEST_TURNIN_TP};
 
-/// A per-event handler passed to the `--quest` probe's `drain_quest` pump: it inspects each decoded
-/// [`SessionEvent`] and returns `Some(msg)` to stop the drain early (the match landed) or `None` to
-/// keep pumping.
+/// A `drain_quest` handler: `Some(msg)` stops the drain, `None` keeps pumping.
 type QuestEventHandler = Box<dyn FnMut(&SessionEvent) -> Option<String>>;
 
-/// The `--quest` probe target: Northshire's opening quest 783 "A Threat Within" — no prerequisite,
-/// no kill/collect objective (a "report to McBride" quest, so it's completable the instant it's
-/// accepted, no GM objective-grind needed). Given by Deputy Willem (entry 823, at
-/// -8933.5 -136.5 83.4) and turned in at Marshal McBride (entry 197, at -8902.6 -162.6 82.0) — both
-/// a few yards apart in the Abbey, so one teleport streams both. Rewards 40 XP (no money), so the
-/// grant is verified on `PLAYER_XP`.
+/// Quest 783 "A Threat Within": no prerequisite and no objective, from Deputy Willem (823) to
+/// Marshal McBride (197), a few yards apart in the Abbey. It rewards 40 XP and no money.
 const QUEST_GIVER_TP: &str = ".go xyz -8933.54 -136.523 83.4466"; // onto Deputy Willem
-const QUEST_GIVER_ENTRY: u32 = 823; // Deputy Willem — gives 783
+const QUEST_GIVER_ENTRY: u32 = 823; // Deputy Willem, who gives 783
 const QUEST_ID: u32 = 783;
 
 pub(crate) struct Quest;
 
 impl Probe for Quest {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Clean slate so the accept is a real fresh accept (idempotent across probe re-runs), then
-        // teleport onto the giver (Deputy Willem) so he streams AND is in interaction range (the
-        // accept's CanInteractWithQuestGiver distance gate — ~5yd — is stricter than QUERY_QUEST).
-        // McBride streams too (~30yd away, within object-stream range); the turn-in teleports onto
-        // him later.
+        // Remove the quest for a fresh accept, then stand on Willem: the accept's
+        // `CanInteractWithQuestGiver` gate (about 5 yd) is stricter than QUERY_QUEST's.
         cx.session.send_chat(&format!(".quest remove {QUEST_ID}"))?;
         cx.session.send_chat(QUEST_GIVER_TP)?;
         println!("sent GM: .quest remove {QUEST_ID}; teleport onto Willem {QUEST_GIVER_TP}");
@@ -44,10 +34,7 @@ impl Probe for Quest {
         let session = &mut *cx.session;
         let self_guid = world.self_guid;
 
-        // --quest: accept + turn in a real quest end-to-end (decision 0088). McBride streamed in after
-        // the QUEST_TP; run the full questgiver wire against him.
-        // A short blocking drain helper: pump packets up to `secs`, folding self-descriptor deltas
-        // into `self_fields`, and hand each decoded event to `f`; stop early when `f` returns Some.
+        // Pump for up to `secs`, folding self deltas into `self_fields`, until `f` returns `Some`.
         let drain_quest = |session: &mut WorldSession,
                            sf: &mut Option<benilla_protocol::messages::ObjectFields>,
                            secs: u64,
@@ -72,9 +59,7 @@ impl Probe for Quest {
             None
         };
 
-        // Find the giver (Deputy Willem) + the turn-in NPC (Marshal McBride) among the streamed
-        // creatures (each guid carries its template entry in bits 24–47). Both stand in the Abbey a
-        // few yards from the teleport spot.
+        // Find Willem and McBride by entry, which a creature guid carries in bits 24–47.
         let find_npc = |entry: u32| {
             world
                 .tracked
@@ -113,9 +98,8 @@ impl Probe for Quest {
         .context("--quest: no SMSG_QUESTGIVER_QUEST_DETAILS for quest 783 within 5s")?;
         println!("✅ details: {details}");
 
-        // 2) Accept at the giver, then confirm the quest id landed in a PLAYER_QUEST_LOG slot of our
-        // descriptor (id field 198 + 3·i, over 20 slots). Poll ~6s — the values delta can trail the
-        // GOSSIP_COMPLETE that closes the interaction.
+        // 2) Accept, then find the quest id in a `PLAYER_QUEST_LOG` slot (field 198 + 3·i, 20
+        // slots), polling 6 s since the delta can trail the closing GOSSIP_COMPLETE.
         println!("giver: CMSG_QUESTGIVER_ACCEPT_QUEST");
         session.questgiver_accept_quest(willem, QUEST_ID)?;
         let quest_in_log = |sf: &Option<benilla_protocol::messages::ObjectFields>| {
@@ -138,19 +122,16 @@ impl Probe for Quest {
         if in_log {
             println!("✅ accept: quest {QUEST_ID} is in the player descriptor's PLAYER_QUEST_LOG (field-confirmed)");
         } else {
-            // The quest-log UpdateFields are the deferred log slice; a solo accept's low-priority
-            // values delta may not stream inside the poll window. Not fatal — the turn-in below can
-            // only produce QUEST_COMPLETE if the accept took, so it's the authoritative check.
+            // Not fatal: the delta may miss the window, and the turn-in only completes if the
+            // accept took.
             println!(
                 "ℹ️  accept: quest {QUEST_ID} not observed in a PLAYER_QUEST_LOG field within the poll \
                  window (the log UpdateFields are a deferred slice); the turn-in below is authoritative"
             );
         }
 
-        // 3) Mark the quest COMPLETE server-side. "A Threat Within" is a talk-to-McBride quest — its
-        // status stays INCOMPLETE until the ender interaction, and CHOOSE_REWARD's CanRewardQuest
-        // gate requires COMPLETE — so GM-complete it (fair per the brief; grinding is impractical
-        // and this one has no grindable objective anyway). Print the server's reply and let it apply.
+        // 3) GM-complete it: a talk-to quest stays INCOMPLETE until the ender interaction, and
+        // CHOOSE_REWARD's `CanRewardQuest` requires COMPLETE.
         session.send_chat(&format!(".quest complete {QUEST_ID}"))?;
         println!("GM: .quest complete {QUEST_ID} (letting it apply…)");
         drain_quest(
@@ -165,13 +146,12 @@ impl Probe for Quest {
             }),
         );
 
-        // Teleport onto McBride so the turn-in is in interaction range (his guid is already known
-        // from the giver-spot stream; only our position needs to change). Drain until the port acks.
+        // Teleport onto McBride for interaction range; his guid is already known.
         session.send_chat(QUEST_TURNIN_TP)?;
         println!("moving to McBride: {QUEST_TURNIN_TP}");
         drain_quest(session, &mut world.self_fields, 3, Box::new(|_| None));
 
-        // Turn in at McBride: COMPLETE_QUEST → REQUEST_ITEMS(complete) or straight to OFFER_REWARD.
+        // Turn in at McBride: COMPLETE_QUEST answers REQUEST_ITEMS, or OFFER_REWARD directly.
         println!("turn-in: CMSG_QUESTGIVER_HELLO + CMSG_QUESTGIVER_COMPLETE_QUEST({QUEST_ID})");
         session.questgiver_hello(mcbride)?;
         session.questgiver_complete_quest(mcbride, QUEST_ID)?;
@@ -196,9 +176,8 @@ impl Probe for Quest {
         .context("--quest: no REQUEST_ITEMS/OFFER_REWARD after COMPLETE_QUEST within 5s")?;
         println!("✅ progress: {progress}");
 
-        // 4) Reach the reward panel. When the quest has required items the progress panel came back
-        // above; its Continue → REQUEST_REWARD → OFFER_REWARD. When it has none (783), COMPLETE_QUEST
-        // *already* answered with OFFER_REWARD, so the reward panel is reached — skip REQUEST_REWARD.
+        // 4) With required items, the progress panel's Continue sends REQUEST_REWARD for
+        // OFFER_REWARD; without them (783), COMPLETE_QUEST already answered OFFER_REWARD.
         if !progress.contains("OFFER_REWARD") {
             println!("turn-in: CMSG_QUESTGIVER_REQUEST_REWARD");
             session.questgiver_request_reward(mcbride, QUEST_ID)?;
@@ -225,8 +204,7 @@ impl Probe for Quest {
             );
         }
 
-        // 5) Finish: CHOOSE_REWARD (index 0 — no choice rewards) → QUEST_COMPLETE + the XP grant via
-        // UPDATE_OBJECT. Quest 783 rewards 40 XP (no money), so the grant is verified on PLAYER_XP.
+        // 5) CHOOSE_REWARD (index 0, no choices) brings QUEST_COMPLETE and the XP delta.
         let xp_before = world.self_fields.as_ref().and_then(|sf| sf.player_xp());
         println!("turn-in: CMSG_QUESTGIVER_CHOOSE_REWARD (choice 0)");
         session.questgiver_choose_reward(mcbride, QUEST_ID, 0)?;
@@ -242,8 +220,8 @@ impl Probe for Quest {
                     c.money,
                     c.items.len()
                 )),
-                // Diagnostics: the server re-offers the reward if it rejected the choice, or offers
-                // the next quest in the chain (783 → 7) after a successful reward.
+                // Diagnostics: a rejected choice re-offers the reward, and a success offers the
+                // chain's next quest (783, then 7).
                 SessionEvent::QuestOffer(o) => {
                     eprintln!("   (diag) OFFER_REWARD again for quest {}", o.quest_id);
                     None
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/quest_item.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/quest_item.rs
index df97d5f6..324c6683 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/quest_item.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/quest_item.rs
@@ -1,13 +1,6 @@
-//! `--quest-item`: the quest-STARTER item wire (decision 0664) — the fork a bag right-click makes
-//! when the clicked item's template carries a non-zero `StartQuest`. The client does NOT send
-//! `CMSG_USE_ITEM` for such an item (the server refuses that with `EQUIP_ERR_ITEM_NOT_FOUND`, the
-//! red "The item was not found." line): it sends `CMSG_QUESTGIVER_QUERY_QUEST` addressed to the
-//! **item's own guid**, and accepts against that same guid.
-//!
-//! This probe proves the whole item-as-questgiver round trip against the live server: add the item,
-//! query its quest from the item guid, require `SMSG_QUESTGIVER_QUEST_DETAILS`, accept from the same
-//! guid, and require the quest to land in `PLAYER_QUEST_LOG` with the starter kept-or-consumed as
-//! the quest's own `ReqItemId`/`SrcItemId` dictate (vmangos `Player::AddQuest`).
+//! `--quest-item`: an item with a non-zero `StartQuest` is its own questgiver. The client sends
+//! `CMSG_QUESTGIVER_QUERY_QUEST` and the accept to the item's guid, never `CMSG_USE_ITEM`, which
+//! the server refuses with `EQUIP_ERR_ITEM_NOT_FOUND`.
 
 use std::time::{Duration, Instant};
 
@@ -16,16 +9,11 @@ use benilla_protocol::{decode, SessionEvent, WorldSession};
 
 use crate::probes::{Ctx, Probe, FIELD_PLAYER_QUEST_LOG_1_1};
 
-/// A per-event handler for this probe's drain pump: it inspects each decoded [`SessionEvent`] and
-/// returns `Some(msg)` to stop the drain early (the match landed) or `None` to keep pumping — the
-/// `--quest` probe's own shape.
+/// A drain handler: `Some(msg)` stops the drain early, `None` keeps pumping.
 type QuestEventHandler = Box<dyn FnMut(&SessionEvent) -> Option<String>>;
 
-/// The probe target: "Northshire Gift Voucher" (entry 14646), which starts quest 5805 "Welcome!" —
-/// picked because it is takeable by the probe body as it stands (`MinLevel` 1, no prerequisite
-/// quest, no race/class gate, item `RequiredLevel` 0 — VERIFIED live against
-/// `mangos.item_template` ⋈ `quest_template`), so no rigging is needed. Non-equippable
-/// (`inventory_type` 0) and spell-less, like all but five of the 215 quest-starters in 1.12.
+/// "Northshire Gift Voucher", starter of quest 5805 "Welcome!": level 1, no prerequisite and no
+/// race or class gate, so any character can take it. Not equippable and carries no spell.
 const ITEM_ENTRY: u32 = 14646;
 const QUEST_ID: u32 = 5805;
 
@@ -33,8 +21,7 @@ pub(crate) struct QuestItem;
 
 impl Probe for QuestItem {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // A clean slate so the accept is a real fresh accept across re-runs, then hand ourselves
-        // the starter item (`verify` subtracts it again at the end).
+        // Drop the quest so every run accepts it fresh; `verify` removes the item again.
         cx.session.send_chat(&format!(".quest remove {QUEST_ID}"))?;
         cx.session.send_chat(&format!(".additem {ITEM_ENTRY}"))?;
         println!("sent GM: .quest remove {QUEST_ID}; .additem {ITEM_ENTRY}");
@@ -46,9 +33,6 @@ impl Probe for QuestItem {
         let session = &mut *cx.session;
         let self_guid = world.self_guid;
 
-        // Pump packets up to `secs`, folding self-descriptor deltas into `self_fields` and handing
-        // each decoded event to `f`; stop early when `f` returns Some. (The `--quest` probe's own
-        // drain, which is a closure over its locals and so can't simply be shared.)
         let drain = |session: &mut WorldSession,
                      sf: &mut Option<benilla_protocol::messages::ObjectFields>,
                      secs: u64,
@@ -73,7 +57,7 @@ impl Probe for QuestItem {
             None
         };
 
-        // 1) Find the starter item in the backpack — the guid IS the questgiver on this wire.
+        // 1) Find the starter in the backpack: its guid is the questgiver on this wire.
         let sf = world
             .self_fields
             .as_ref()
@@ -89,7 +73,7 @@ impl Probe for QuestItem {
             })?;
         println!("\nquest-starter item {ITEM_ENTRY}: guid {item_guid:#x} (the giver on this wire)");
 
-        // 2) The fork's own packet: QUERY_QUEST addressed to the ITEM guid → DETAILS.
+        // 2) QUERY_QUEST on the item guid answers with `SMSG_QUESTGIVER_QUEST_DETAILS`.
         println!("CMSG_QUESTGIVER_QUERY_QUEST({QUEST_ID}) on the item guid");
         session.questgiver_query_quest(item_guid, QUEST_ID)?;
         let details = drain(
@@ -110,12 +94,8 @@ impl Probe for QuestItem {
         )?;
         println!("✅ details: {details}");
 
-        // 3) Accept against the same item guid: the quest must land in the log, and the starter
-        // must survive — vmangos `Player::AddQuest`'s "remove start item if not need" destroys a
-        // `TYPEID_ITEM` giver ONLY when the quest neither requires it (`ReqItemId`) nor names it
-        // `SrcItemId`, and this one is both (`quest_template` 5805: `SrcItemId = ReqItemId1 =
-        // 14646` — the voucher IS the turn-in). Asserting the retention pins the branch as firmly
-        // as a destroy would, and keeps the probe's item deterministic across re-runs.
+        // 3) Accept on the same guid. vmangos `Player::AddQuest` keeps an item giver the quest
+        // requires or names `SrcItemId`, and 5805 does both, so the starter must survive.
         println!("CMSG_QUESTGIVER_ACCEPT_QUEST({QUEST_ID}) on the item guid");
         session.questgiver_accept_quest(item_guid, QUEST_ID)?;
         let mut destroyed = false;
@@ -160,13 +140,9 @@ impl Probe for QuestItem {
              the quest's own required turn-in)"
         );
 
-        // 4) The director's second click (decision 0669): the starter is still in the bag while
-        // the quest is in the log, so clicking it again re-sends the same QUERY. vmangos'
-        // `HandleQuestgiverQueryQuestOpcode` has NO status gate — it answers with the DETAILS
-        // again, which is why the panel legitimately re-opens — and the accept behind it is what
-        // fails: `CanTakeQuest` → `SatisfyQuestStatus` → `SendCanTakeQuestResponse`
-        // (`SMSG_QUESTGIVER_QUEST_INVALID`) with `INVALIDREASON_QUEST_ALREADY_ON` = 13 = 0x0d.
-        // That 13 is the code the client maps to `ERR_QUEST_ALREADY_ON` — pin BOTH halves here.
+        // 4) Click again while on the quest: `HandleQuestgiverQueryQuestOpcode` has no status gate,
+        // so DETAILS returns, and the accept is refused with `SMSG_QUESTGIVER_QUEST_INVALID` reason
+        // 13 (`INVALIDREASON_QUEST_ALREADY_ON`, shown as `ERR_QUEST_ALREADY_ON`).
         println!("\nsecond click while ON the quest — QUERY then ACCEPT again");
         session.questgiver_query_quest(item_guid, QUEST_ID)?;
         let reopened = drain(
@@ -182,7 +158,7 @@ impl Probe for QuestItem {
         )
         .context(
             "--quest-item: the re-query got no DETAILS — this server DOES gate the query by \
-             quest status, so the panel would not re-open (decision 0669 expects vmangos' \
+             quest status, so the panel would not re-open (the probe expects vmangos's \
              ungated handler)",
         )?;
         println!("✅ the panel legitimately re-opens: DETAILS {reopened}");
@@ -207,8 +183,7 @@ impl Probe for QuestItem {
         );
         println!("✅ refusal: QUEST_INVALID reason 13 → ERR_QUEST_ALREADY_ON (the ref's 0x5dbca0)");
 
-        // Leave the probe character as found: drop the quest and the copy staging added (this
-        // starter survives the accept, so without the subtract every run would litter one).
+        // Leave the character as found; the starter survives the accept, so remove it too.
         session.send_chat(&format!(".quest remove {QUEST_ID}"))?;
         session.send_chat(&format!(".additem {ITEM_ENTRY} -1"))?;
         drain(session, &mut world.self_fields, 2, Box::new(|_| None));
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/questlog.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/questlog.rs
index cb3bad08..1168fb64 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/questlog.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/questlog.rs
@@ -1,6 +1,5 @@
-//! `--questlog`: the quest-LOG wire (decision 0109). Accept quest 7 at McBride, `CMSG_QUEST_QUERY`
-//! it (the fat template parser's live golden), poll the `PLAYER_QUEST_LOG` slot, GM-complete it and
-//! require the COMPLETE state byte, then `CMSG_QUESTLOG_REMOVE_QUEST` and require the id field to clear.
+//! `--questlog`: accept quest 7 at McBride, query its template, GM-complete it and require the
+//! slot's complete bit, then abandon it and require the slot's id field to clear.
 
 use std::time::{Duration, Instant};
 
@@ -17,10 +16,7 @@ pub(crate) struct QuestLog;
 
 impl Probe for QuestLog {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Same cleanup-then-teleport pattern as --quest (idempotent across re-runs); McBride is
-        // both giver and ender for quest 7, so one teleport (already onto him) suffices. Shared with
-        // --giverstatus: the `mcbride_staged` flag makes the two GM lines go out exactly once for a
-        // co-run, matching today's single `cli.questlog || cli.giverstatus` staging block.
+        // Shared with --giverstatus: `mcbride_staged` keeps these GM lines to one send per run.
         if !cx.world.mcbride_staged {
             cx.session
                 .send_chat(&format!(".quest remove {QUESTLOG_ID}"))?;
@@ -38,8 +34,7 @@ impl Probe for QuestLog {
         let session = &mut *cx.session;
         let self_guid = world.self_guid;
 
-        // --questlog: live-verify the quest-LOG wire (decision 0109) against quest 7 "Kobold Camp
-        // Cleanup" — McBride streamed in and we're in interaction range from the preamble teleport.
+        // The staging teleport lands on McBride, so he is streamed and in interaction range.
         let mcbride = world
             .tracked
             .iter()
@@ -52,8 +47,7 @@ impl Probe for QuestLog {
             )?;
         println!("\nMarshal McBride: guid {mcbride:#x}");
 
-        // 1) Query + accept quest 7 at McBride (he's both giver and ender — copies --quest's
-        // hello → query → accept flow, minus the separate turn-in NPC).
+        // 1) Hello, query and accept quest 7 at McBride, who also ends it.
         println!("giver: CMSG_QUESTGIVER_HELLO + CMSG_QUESTGIVER_QUERY_QUEST({QUESTLOG_ID})");
         session.questgiver_hello(mcbride)?;
         session.questgiver_query_quest(mcbride, QUESTLOG_ID)?;
@@ -75,8 +69,7 @@ impl Probe for QuestLog {
 
         println!("giver: CMSG_QUESTGIVER_ACCEPT_QUEST");
         session.questgiver_accept_quest(mcbride, QUESTLOG_ID)?;
-        // Let the accept settle (its values delta can trail the GOSSIP_COMPLETE that closes the
-        // interaction) before asking for the template/slot below.
+        // The accept's values delta can trail the GOSSIP_COMPLETE that closes the interaction.
         let drain_until = Instant::now() + Duration::from_secs(3);
         while Instant::now() < drain_until {
             let Ok(msg) = session.recv() else { continue };
@@ -91,9 +84,7 @@ impl Probe for QuestLog {
             }
         }
 
-        // 2) The template: CMSG_QUEST_QUERY → SMSG_QUEST_QUERY_RESPONSE — the fat parser's live
-        // golden (hand-built fixtures already cover the wire traps; this proves the real byte
-        // stream). Require the title and at least one real (required_count > 0) objective.
+        // 2) CMSG_QUEST_QUERY: the template parser against the live server's bytes.
         println!("CMSG_QUEST_QUERY({QUESTLOG_ID})");
         session.quest_query(QUESTLOG_ID)?;
         let mut template: Option<benilla_protocol::messages::QuestTemplate> = None;
@@ -148,10 +139,8 @@ impl Probe for QuestLog {
             "✅ template: title matches '{QUESTLOG_TITLE}', ≥1 objective with required_count > 0."
         );
 
-        // 3) Slot state: find which PLAYER_QUEST_LOG slot the accept landed in (same poll pattern
-        // --quest uses for its soft accept check, made a hard requirement here), then GM-complete
-        // it and require the slot's count-state field (id-field + 1) to gain the COMPLETE state
-        // byte (bit 0x01 at byte 3 — `count_state & 0xFF00_0000` gains `0x01 << 24`).
+        // 3) Find the accept's PLAYER_QUEST_LOG slot, GM-complete it, and require the slot's
+        // count-state field (id field + 1) to gain the complete bit, 0x01 in its top byte.
         let find_slot = |sf: &Option<benilla_protocol::messages::ObjectFields>| {
             sf.as_ref().and_then(|sf| {
                 (0..benilla_protocol::messages::PLAYER_QUEST_LOG_SLOTS)
@@ -183,8 +172,7 @@ impl Probe for QuestLog {
         )?;
         println!("quest {QUESTLOG_ID} occupies PLAYER_QUEST_LOG slot {slot}");
 
-        // The count-state word itself (id-field + 1) — read raw so we can print the exact
-        // before/after bytes, not just the decoded [`QuestLogSlot::state`].
+        // Raw rather than decoded, so the exact before and after bytes print.
         let count_state_word = |sf: &Option<benilla_protocol::messages::ObjectFields>| {
             sf.as_ref().and_then(|sf| {
                 sf.raw_fields()
@@ -233,8 +221,7 @@ impl Probe for QuestLog {
              complete ({before_word:#010x} → {after_word:#010x})."
         );
 
-        // 4) Abandon: CMSG_QUESTLOG_REMOVE_QUEST(slot) — no ack SMSG exists on this wire (decision
-        // 0109); the descriptor's id field clearing to 0 IS the confirmation.
+        // 4) CMSG_QUESTLOG_REMOVE_QUEST has no reply; the slot's id field clearing is the ack.
         println!("CMSG_QUESTLOG_REMOVE_QUEST(slot {slot})");
         session.questlog_remove_quest(slot)?;
         let mut cleared = false;
@@ -261,17 +248,17 @@ impl Probe for QuestLog {
             bail!(
                 "--questlog: slot {slot}'s PLAYER_QUEST_LOG id field never cleared to 0 within \
                  8s after CMSG_QUESTLOG_REMOVE_QUEST (no ack SMSG exists on this wire — the field \
-                 clear IS the confirmation, decision 0109)"
+                 clear IS the confirmation)"
             );
         }
         println!(
             "✅ abandon: slot {slot}'s PLAYER_QUEST_LOG id field cleared to 0 (no ack SMSG on \
-             this wire — the field update is the confirmation, decision 0109)."
+             this wire — the field update is the confirmation)."
         );
 
         println!(
             "\n✅ --questlog PASS: template parsed, slot {slot} tracked → COMPLETE → abandoned \
-             (id field cleared) — the quest-log wire verified end to end (decision 0109)."
+             (id field cleared) — the quest-log wire verified end to end."
         );
         Ok(())
     }
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/questtimer.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/questtimer.rs
index 378c1d07..59594c93 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/questtimer.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/questtimer.rs
@@ -1,24 +1,7 @@
-//! `--questtimer`: the timed-quest countdown's whole wire chain, live (decision 1150, B234).
-//!
-//! The countdown is not on the wire as a duration anywhere. The server writes a timed quest's
-//! deadline into the quest-log slot's third field as an **absolute unix stamp** — `time(nullptr) +
-//! limitTime`, vmangos `Player::AddQuest` — and the client is expected to subtract its own sample
-//! of the server's clock, taken with `CMSG_QUERY_TIME`. Two independent readings, one subtraction,
-//! and nothing in the client can tell you it got either one wrong: a mis-decoded field or a missing
-//! clock both produce a number that *looks* like a countdown.
-//!
-//! So this probe reads both ends against the running server and checks the subtraction lands where
-//! the quest template says it must:
-//!
-//! 1. `.quest remove` then `.quest add` [`TIMED_QUEST`] (idempotent across re-runs).
-//! 2. Poll the descriptor for the slot the quest landed in and read its **raw** timer field.
-//! 3. `CMSG_QUERY_TIME` for the server's wall clock.
-//! 4. Assert the subtraction implies the quest was added *just now*, and print the countdown.
-//!
-//! Step 4 is what makes this more than a decode check. The probe added the quest itself seconds
-//! ago, so the remaining time must sit just under the template's full limit — not merely somewhere
-//! inside it. A wrong epoch misses that window by decades, a seconds/milliseconds slip by 1000×,
-//! and a clock that never arrived by more than the run's own length.
+//! `--questtimer`: the timed-quest countdown. The server writes the deadline into the quest-log
+//! slot's third field as an absolute unix time, `time(nullptr) + limitTime` (vmangos
+//! `Player::AddQuest`), and the countdown is that minus the server clock from `CMSG_QUERY_TIME`.
+//! The probe adds the quest itself, so the remaining time must sit just under the full limit.
 
 use std::time::{Duration, Instant};
 
@@ -28,19 +11,13 @@ use benilla_protocol::SessionEvent;
 
 use crate::probes::{Ctx, Probe, FIELD_PLAYER_QUEST_LOG_1_1};
 
-/// "Iverron's Antidote" (Teldrassil) — `quest_template.LimitTime = 300`, min level 2, and no
-/// prerequisite a GM `.quest add` cares about. Chosen because 5 minutes is long enough that the
-/// remaining time is unambiguously mid-window while the probe runs, and short enough that a
-/// seconds/milliseconds mix-up would fall outside it immediately.
+/// "Iverron's Antidote" (Teldrassil): `LimitTime` 300, min level 2, and no prerequisite that a
+/// GM `.quest add` checks.
 const TIMED_QUEST: u32 = 3522;
-/// [`TIMED_QUEST`]'s `quest_template.LimitTime` (read from the running deploy's `mangos` DB). Not
-/// on the wire in 1.12 — `SMSG_QUEST_QUERY_RESPONSE` has no such field, and vmangos reads
-/// `GetLimitTime()` only server-side in `Player::AddQuest` — so it is a constant here rather than a
-/// second packet's answer.
+/// [`TIMED_QUEST`]'s `quest_template.LimitTime`. No 1.12 packet carries it, not even
+/// `SMSG_QUEST_QUERY_RESPONSE`; vmangos reads it only in `Player::AddQuest`.
 const LIMIT_TIME_SECS: u32 = 300;
-/// How much wall time the probe allows between its `.quest add` and the read below. Generous
-/// against a slow login and a full stream window, and still ~100× tighter than any of the failure
-/// modes it is bounding (a wrong epoch, a seconds/milliseconds slip, a clock that never arrived).
+/// Seconds allowed between the `.quest add` and the read, generous for a slow login.
 const ADD_TO_READ_SLACK: f64 = 120.0;
 
 #[derive(Default)]
@@ -69,8 +46,7 @@ impl Probe for QuestTimer {
         let Ctx { session, world } = cx;
         let self_guid = world.self_guid;
 
-        // 1) The slot. Poll the descriptor the same way `--questlog` does — the accept's field
-        // update can trail the chat ack by a beat.
+        // 1) The slot, polled: its field update can trail the GM command's chat ack.
         let find_slot = |sf: &Option<benilla_protocol::messages::ObjectFields>| {
             sf.as_ref().and_then(|sf| {
                 (0..benilla_protocol::messages::PLAYER_QUEST_LOG_SLOTS)
@@ -106,8 +82,7 @@ impl Probe for QuestTimer {
              poll window (is `.quest add` refused for this character?)",
         )?;
 
-        // The timer field raw (id-field + 2), beside the decoded view, so a decode that reads the
-        // wrong field of the triple is visible as a mismatch rather than a plausible number.
+        // Raw timer field (id field + 2) beside the decoded one, so a wrong-field decode shows.
         let raw_timer = world
             .self_fields
             .as_ref()
@@ -135,8 +110,7 @@ impl Probe for QuestTimer {
             );
         }
 
-        // 2) The server's wall clock. Asked for here rather than leaning on a login-time send, so
-        // the probe is self-contained and the round trip itself is what's under test.
+        // 2) The server's wall clock, asked for here so the round trip itself is under test.
         session.query_time()?;
         let deadline = Instant::now() + Duration::from_secs(5);
         let asked_at = Instant::now();
@@ -160,18 +134,8 @@ impl Probe for QuestTimer {
             at.elapsed().as_secs_f64()
         );
 
-        // 3) The subtraction, against a window the probe's own actions bound tightly on BOTH
-        // sides. `.quest add` ran seconds ago in `stage`, so the server wrote
-        // `now + LIMIT_TIME_SECS` seconds ago — the remaining time must therefore sit just under
-        // the full limit, not merely somewhere inside it. That tight upper bound is what makes
-        // this a real check: a wrong epoch is out by decades, a seconds/milliseconds slip by
-        // 1000×, and an absent or stale clock by more than the run's own length.
-        //
-        // (The limit is a constant because 1.12's `SMSG_QUEST_QUERY_RESPONSE` does not carry
-        // `LimitTime` — verified against the parsed body's field list and vmangos, which reads
-        // `GetLimitTime()` only in `Player::AddQuest`. Its provenance is the DB row cited on
-        // [`TIMED_QUEST`]; if content ever changes it, this probe fails loudly rather than
-        // quietly passing.)
+        // 3) A wrong epoch misses this window by decades, a seconds/milliseconds slip by a factor
+        // of 1000, an absent or stale clock by more than the run's length.
         let remaining = f64::from(raw_timer) - now;
         let elapsed_since_add = f64::from(LIMIT_TIME_SECS) - remaining;
         if !(0.0..=ADD_TO_READ_SLACK).contains(&elapsed_since_add) {
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/self_res.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/self_res.rs
index e6b6415d..99a11d41 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/self_res.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/self_res.rs
@@ -1,54 +1,36 @@
-//! `--self-res`: the self-resurrect wire (decision 1746) — `PLAYER_SELF_RES_SPELL` arriving at the
-//! death, `CMSG_SELF_RES` spending it, and the field zeroing as we stand back up.
-//!
-//! The whole mechanism is one private descriptor field and one bodyless opcode, so the only way to
-//! be sure of either is to watch a real death. The shared [`crate::world::DeathArc`] does the dying
-//! — with `hold_release` set, because the button being tested lives on the DEATH dialog and that
-//! dialog only exists *before* the release.
-//!
-//! **Reincarnation, not a soulstone**, because a soulstone needs a second character casting on us
-//! while a shaman's passive needs only what a GM account can grant itself: vmangos's
-//! `Player::SelectResurrectionSpellId` gates the Reincarnation arm on `HasSpell(20608)` +
-//! `IsSpellReady(21169)` + `HasItemCount(17030, 1)` and asks **no class question**, so the staging
-//! below arms it on whatever body the slot's probe account has. The two paths converge one line
-//! later — both write their effect id into the same field — so the field, the send and the
-//! resurrection are the same wire either way.
+//! `--self-res`: `PLAYER_SELF_RES_SPELL` arrives at death, the bodyless `CMSG_SELF_RES` spends it,
+//! and the field zeroes as we stand. The death holds its release: the button lives on the DEATH
+//! dialog, which exists only before release. Reincarnation stands in for a soulstone: vmangos
+//! `Player::SelectResurrectionSpellId` arms it with no class check, into the same field.
 
 use anyhow::{bail, Context, Result};
 use benilla_protocol::SessionEvent;
 
 use crate::probes::{Ctx, Probe};
 
-/// Reincarnation's learnable passive — the `HasSpell` half of the server's gate.
+/// Reincarnation's learnable passive, the `HasSpell` half of the server's gate.
 const REINCARNATION_PASSIVE: u32 = 20608;
-/// Reincarnation's *effect* spell — what the server writes into `PLAYER_SELF_RES_SPELL`, and what
-/// `Spell.dbc` names **"Reincarnation"** (the DEATH dialog's button text).
+/// Reincarnation's effect: the `PLAYER_SELF_RES_SPELL` value, named on the DEATH dialog's button.
 const REINCARNATION_EFFECT: u32 = 21169;
-/// Ankh — the reagent the same gate counts.
+/// Ankh, the reagent the same gate counts.
 const ITEM_ANKH: u32 = 17030;
 
 #[derive(Default)]
 pub(crate) struct SelfRes {
-    /// The first non-zero `PLAYER_SELF_RES_SPELL` seen, and whether we were already at 0 health
-    /// when it landed — the ordering question the DEATH dialog's `OnShow` read depends on.
+    /// The first non-zero `PLAYER_SELF_RES_SPELL`, and whether health was already 0 when it came:
+    /// the DEATH dialog's `OnShow` reads the field.
     self_res_spell: Option<u32>,
     self_res_after_death: bool,
     sent: bool,
-    /// `PLAYER_SELF_RES_SPELL` read back as zero *after* the send — the server spending it.
+    /// `PLAYER_SELF_RES_SPELL` read back as zero after the send: the server spent it.
     field_cleared: bool,
-    /// Health back above 0 after the send, without ever having been a ghost.
     revived_without_releasing: bool,
 }
 
 impl Probe for SelfRes {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Arm the passive path. Reincarnation has a one-hour cooldown and a **successful run is
-        // what sets it**, so without this the probe passes once and then fails for an hour — which
-        // is exactly what it did, and the failure reads as "the server refused the gate" rather
-        // than "you already proved this". `.cooldown clear` (not `.cooldown`, which is a bare
-        // subcommand table and silently does nothing) removes all of the selected unit's
-        // cooldowns; with nothing selected `ChatHandler::GetSelectedUnit` falls back to self.
-        // The Ankh goes in every run because the resurrection spends it.
+        // A success starts Reincarnation's one-hour cooldown and spends the Ankh. Bare `.cooldown`
+        // does nothing; `.cooldown clear` with nothing selected clears our own.
         cx.session.send_chat(".cooldown clear")?;
         cx.session
             .send_chat(&format!(".learn {REINCARNATION_PASSIVE}"))?;
@@ -61,8 +43,7 @@ impl Probe for SelfRes {
     }
 
     fn poll(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Spend it once the death has landed AND the field has arrived — the same two facts the
-        // DEATH dialog's button2 waits on (`HasSoulstone()` non-nil while the popup is up).
+        // Dead, field set: the DEATH dialog offers button2 while `HasSoulstone()` is non-nil.
         let died = cx
             .world
             .death_arc
@@ -83,8 +64,7 @@ impl Probe for SelfRes {
         if *guid != cx.world.self_guid {
             return Ok(());
         }
-        // Read the DELTA for the arrival, not the merged store: the question is which packet
-        // carried the field, and a merged read cannot tell "arrived now" from "arrived earlier".
+        // The delta, not the merged store: only the delta says which packet carried the field.
         if let Some(spell) = fields.player_self_res_spell() {
             if self.self_res_spell.is_none() {
                 self.self_res_spell = Some(spell);
@@ -103,8 +83,8 @@ impl Probe for SelfRes {
                 );
             }
         } else if self.sent && !self.field_cleared {
-            // Zero and absent are the same `None` here, so the clear is only meaningful once the
-            // MERGED store also reads none — an unrelated delta must not be mistaken for it.
+            // A delta without the field also reads `None`, so the clear counts only once the
+            // merged store reads none too.
             if cx
                 .world
                 .self_fields
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/speed.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/speed.rs
index 6e807a4d..8281cca1 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/speed.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/speed.rs
@@ -1,6 +1,5 @@
-//! `--speed`: the force-speed-change wire. GM `.modify speed 1.5`, require + ack
-//! `SMSG_FORCE_RUN_SPEED_CHANGE`, then `.modify speed 1` and require a SECOND change on a still-live
-//! stream (a malformed ack drops the session, so surviving both round trips is the proof).
+//! `--speed`: ack two `SMSG_FORCE_RUN_SPEED_CHANGE`s from `.modify speed`; a malformed ack drops
+//! the session, so surviving both round trips is the proof.
 
 use anyhow::{ensure, Result};
 use benilla_protocol::{SessionEvent, SpeedKind};
@@ -21,10 +20,8 @@ impl Probe for Speed {
 
     fn on_event(&mut self, ev: &SessionEvent, cx: &mut Ctx) -> Result<()> {
         if let SessionEvent::ForceSpeedChange { guid, .. } = ev {
-            // Fires after World has acked + recorded the change. World acks only when our pose is
-            // known (`tracked.get(guid)` Some, else it skips the arm entirely and never records) —
-            // mirror that guard (self + tracked-present) here so the second `.modify` is suppressed
-            // in exactly the same pose-missing case the old in-arm `continue` suppressed it.
+            // Runs after World's ack, which World sends only with our pose tracked; the same
+            // guard holds the second `.modify` back when there was no ack.
             if *guid == cx.world.self_guid
                 && cx.world.tracked.contains_key(guid)
                 && !self.second_sent
@@ -38,9 +35,7 @@ impl Probe for Speed {
     }
 
     fn verify(&mut self, cx: &mut Ctx) -> Result<()> {
-        // --speed verdict: two changes, both Run, the flat speeds the GM rates imply (1.5×7.0 then
-        // 1.0×7.0), and an incremented counter — proof both acks were parsed (a malformed body drops
-        // the session before the second round trip could complete).
+        // Base run speed is 7.0 yd/s, so the rates 1.5 and 1 give 10.5 then 7.0.
         let speed_changes_seen = &cx.world.speed_changes_seen;
         ensure!(
             speed_changes_seen.len() >= 2,
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/spells.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/spells.rs
index 2eb0f3e5..f302208b 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/spells.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/spells.rs
@@ -1,6 +1,5 @@
-//! `--spells`: the spell/action wire. Require `SMSG_INITIAL_SPELLS` + `SMSG_ACTION_BUTTONS` at
-//! login, cast one spell (self, then packed-guid targeted), require a `SMSG_CAST_RESULT` verdict,
-//! and read our inventory back out of the descriptor as the round-trip evidence.
+//! `--spells`: require `SMSG_INITIAL_SPELLS` and `SMSG_ACTION_BUTTONS` at login, then a
+//! `SMSG_CAST_RESULT` for a self cast, a ground cast and a packed-guid targeted cast.
 
 use std::time::{Duration, Instant};
 
@@ -9,9 +8,8 @@ use benilla_protocol::{decode, guid, EntityKind, SessionEvent};
 
 use crate::probes::{Ctx, Probe};
 
-/// The dest-cast phase's spell: 4054 "Rough Dynamite" — dest-targeted (`Targets = 0x40`), zero
-/// mana, no reagents/totems, no equipped-item requirement, no aura state (live `spell_template`
-/// sweep, decision 0792) — castable by ANY class the probe character happens to be, once GM-learnt.
+/// "Rough Dynamite": dest-targeted (`Targets = 0x40`), no mana, reagent, equipment or aura state,
+/// so any class can cast it once GM-learnt.
 const DEST_SPELL: u32 = 4054;
 
 #[derive(Default)]
@@ -20,21 +18,15 @@ pub(crate) struct Spells {
     targeted_cast_sent: Option<(u32, u64)>,
     dest_cast_sent: Option<[f32; 3]>,
     dest_learn_sent: bool,
-    /// Set by `SMSG_LEARNED_SPELL` naming [`DEST_SPELL`] — the gate the dest cast waits behind.
-    /// The `.learn` chat command executes DEFERRED on the server (past the session's opcode
-    /// batch), so a cast sent in the same batch beats it and is silently dropped as unknown
-    /// ("casts spell 4054 which he shouldn't have" — observed live, 2026-07-30).
+    /// Set by `SMSG_LEARNED_SPELL` for [`DEST_SPELL`]. The server runs `.learn` after the
+    /// session's opcode batch, so a cast in the same batch is dropped as unknown.
     dest_spell_known: bool,
 }
 
 impl Probe for Spells {
     fn poll(&mut self, cx: &mut Ctx) -> Result<()> {
-        // Cast once both the book and the bar are known. The pick must be an *active* spell —
-        // vmangos silently drops a cast of a passive (HandleCastSpellOpcode returns before any
-        // CAST_RESULT), and the book mixes proficiencies/passives in. A spell the player slotted
-        // on the action bar is active by construction (6603 auto-attack excluded: it's the
-        // attack toggle, not a cast); Battle Shout 6673 is the fallback. Either verdict (ok or a
-        // failure reason like no-rage/bad-target) proves the round trip.
+        // `HandleCastSpellOpcode` drops a passive with no CAST_RESULT, so pick a bar spell,
+        // skipping auto-attack 6603 (a toggle, not a cast), else Battle Shout 6673.
         if self.cast_sent.is_none() {
             if let (Some(book), Some(bar)) = (&cx.world.spell_book, &cx.world.bar_spells) {
                 let spell = bar
@@ -51,16 +43,10 @@ impl Probe for Spells {
                 }
             }
         }
-        // Phase 3 (decision 0792): the GROUND cast — mask 0x40 + three f32 WoW coords, the body
-        // the targeting cursor's world-click commit sends. GM-learn the classless DEST_SPELL,
-        // wait for the server's own `SMSG_LEARNED_SPELL` ack (the chat command executes deferred
-        // — a cast in the same batch is dropped as unknown), then cast at our own feet
-        // (`self_pose` — distance 0, always in range, always LOS). Routed to `dest_verdict` by
-        // spell id, so it can't collide with phase 2's positional slot. Gated like phase 2 on
-        // the phase-1 verdict (the book/bar round trip is proven).
+        // Phase 3, the ground cast: mask 0x40 and three f32 coords, the targeting cursor's world
+        // click body, cast at our own feet so it is always in range and line of sight.
         if self.dest_cast_sent.is_none() && cx.world.cast_verdict.is_some() {
-            // A prior run's deferred .learn may already have stuck — the login book then
-            // carries the spell and no fresh SMSG_LEARNED_SPELL will ever fire.
+            // A prior run's learn is already in the login book; no SMSG_LEARNED_SPELL will come.
             if !self.dest_spell_known
                 && cx
                     .world
@@ -86,11 +72,8 @@ impl Probe for Spells {
                 self.dest_cast_sent = Some(pos);
             }
         }
-        // Phase 2: once the self-cast AND the ground cast are answered, cast the bar spell AT
-        // the first streamed creature — the mask-2 + PACKED-guid target block. Ordered AFTER the
-        // dest phase deliberately: `.learn` executes deferred and resolves the SELECTION, so a
-        // creature selected here before the command ran turned the learn into "Player not
-        // found!" (observed live, 2026-07-30 — the `.cheat god` re-target trap, method.md).
+        // Phase 2, mask 2 with a packed guid. It runs after the ground cast: the deferred `.learn`
+        // acts on the selection and fails with "Player not found!" on a creature.
         if self.targeted_cast_sent.is_none() && cx.world.dest_verdict.is_some() {
             if let Some(spell) = self.cast_sent {
                 if let Some((&guid, _)) = cx
@@ -110,9 +93,7 @@ impl Probe for Spells {
     }
 
     fn on_event(&mut self, ev: &SessionEvent, _cx: &mut Ctx) -> Result<()> {
-        // The dest phase's learn ack: the book already carrying the spell (a prior probe run's
-        // leftover) counts the same — `SMSG_INITIAL_SPELLS` is handled at the gate below instead,
-        // since the book arrives before the learn is ever sent.
+        // The dest phase's learn ack; `poll` checks a login book that already has the spell.
         if let SessionEvent::SpellLearned { spell_id } = ev {
             if *spell_id == DEST_SPELL {
                 self.dest_spell_known = true;
@@ -125,7 +106,7 @@ impl Probe for Spells {
         let world = &mut *cx.world;
         let session = &mut *cx.session;
 
-        // --spells inventory readout: what the server says One is actually holding.
+        // Inventory readout: what the server says the character holds.
         if let Some(sf) = &world.self_fields {
             let slot_entry = |guid: Option<u64>| {
                 guid.filter(|g| *g != 0)
@@ -188,8 +169,7 @@ impl Probe for Spells {
                 };
                 println!("  {label:<10} {text}");
             };
-            // Equipment names resolve through the PUBLIC visible-item entries (item objects
-            // have no decode path yet — a named gap; the private INV guids prove presence).
+            // Names come from the public visible-item entries; private INV guids show presence.
             for slot in [15u8, 16, 17] {
                 if let Some(e) = sf.player_visible_item_entry(slot) {
                     if !world.item_names.contains_key(&e) {
@@ -213,7 +193,6 @@ impl Probe for Spells {
             println!("(no self descriptor captured — inventory readout skipped)");
         }
 
-        // --spells verdict: book + bar must have arrived and parsed; the cast must have been answered.
         let book = world
             .spell_book
             .clone()
@@ -243,9 +222,8 @@ impl Probe for Spells {
             (Some(e), _) => bail!("no SMSG_ITEM_QUERY_SINGLE_RESPONSE for entry {e}"),
             (None, _) => println!("(no item-kind button on the bar to item-query)"),
         }
-        // --spells dest-cast verdict (decision 0792): the wire shape must not merely parse — the
-        // cast must be ACCEPTED. A missing verdict means the body desynced the server's reader
-        // (the CMSG was dropped or the session died); a refusal names the CheckCast reason.
+        // The ground cast must be accepted: no verdict means the body desynced the server's
+        // reader, and a refusal carries the `CheckCast` reason.
         match (self.dest_cast_sent, &world.dest_verdict) {
             (Some(pos), Some((_, true, _))) => {
                 println!(
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/spirit.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/spirit.rs
index beb48c6b..da5c887d 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/spirit.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/spirit.rs
@@ -1,7 +1,5 @@
-//! `--spirit`: the spirit-healer res + the 25% durability loss's wire (decision 0318). Repair to a
-//! full baseline (the [`crate::world::DeathArc`] dies + releases), teleport onto the graveyard's
-//! Spirit Healer, `CMSG_SPIRIT_HEALER_ACTIVATE`, and require BOTH the res (ghost flag clears) and
-//! the post-activate `ITEM_FIELD_DURABILITY` deltas the loss must push.
+//! `--spirit`: `CMSG_SPIRIT_HEALER_ACTIVATE` must clear the ghost flag and push the 25%
+//! durability loss as `ITEM_FIELD_DURABILITY` deltas.
 
 use std::collections::HashMap;
 use std::time::{Duration, Instant};
@@ -11,9 +9,7 @@ use benilla_protocol::{guid, EntityKind, ObjectFields, SessionEvent};
 
 use crate::probes::{Ctx, Probe};
 
-/// The merged per-item descriptor stores (create seed + every values-delta — the same shape the
-/// app's `Items` store holds), the durability baseline snapshotted at activate time, and the raw
-/// post-activate durability deltas the verdict requires.
+/// Per-item merged descriptors, the durability baseline at activate time, and the deltas after.
 #[derive(Default)]
 pub(crate) struct Spirit {
     healer: Option<(u64, [f32; 3])>,
@@ -27,18 +23,16 @@ pub(crate) struct Spirit {
 
 impl Probe for Spirit {
     fn stage(&mut self, cx: &mut Ctx) -> Result<()> {
-        // A full-durability baseline (`.repairitems`, vmangos `Chat.cpp:1297` SEC_GAMEMASTER):
-        // every post-activate delta must then read as a DROP, idempotent across probe re-runs
-        // (each spirit res costs a real 25%).
+        // Full durability, so each post-activate delta reads as a drop; `.repairitems` needs
+        // SEC_GAMEMASTER (vmangos `Chat.cpp:1297`).
         cx.session.send_chat(".repairitems")?;
         println!("sent GM: .repairitems (full-durability baseline)");
         Ok(())
     }
 
     fn poll(&mut self, cx: &mut Ctx) -> Result<()> {
-        // --spirit: once we're a released ghost and the graveyard's Spirit Healer has streamed,
-        // teleport onto it — the repop spot can land outside the activate's interaction gate
-        // (vmangos `GetNPCIfCanInteractWith`, INTERACTION_DISTANCE 5 yd).
+        // Teleport onto the healer: the repop spot can be outside the activate's 5 yd
+        // interaction gate (vmangos `GetNPCIfCanInteractWith`).
         if !self.healer_tp_sent
             && cx
                 .world
@@ -53,12 +47,9 @@ impl Probe for Spirit {
                 self.healer_tp_sent = true;
             }
         }
-        // --spirit: standing on the healer, snapshot the durability baseline (the merged item
-        // stores: create seed + the `.repairitems` deltas) and ask for the res — the XP_LOSS
-        // popup's accept. The 2s settle after the teleport ack lets the server PROCESS the ack
-        // first: the movement-ack and world-packet queues are separate, and an activate racing
-        // its own teleport ack is range-checked from the PRE-teleport spot (>5 yd → silently
-        // refused; live-observed on the first probe run).
+        // On the healer, snapshot the baseline and send the XP_LOSS popup's accept. The server
+        // queues movement acks apart from world packets, so an activate sent too soon after the
+        // teleport is range-checked from the old spot and silently refused; hence the 2 s wait.
         if !self.activate_sent {
             if let (Some((hg, hp)), Some(landed)) = (self.healer, self.healer_tp_landed) {
                 let (pos, _) = cx.world.self_pose();
@@ -92,10 +83,8 @@ impl Probe for Spirit {
 
     fn on_event(&mut self, ev: &SessionEvent, cx: &mut Ctx) -> Result<()> {
         match ev {
-            // --spirit: the graveyard's Spirit Healer advertises UNIT_NPC_FLAG_SPIRITHEALER (0x20 —
-            // vmangos `UnitDefines.h:662`, the flag `GetNPCIfCanInteractWith` gates the activate on).
-            // It only streams to ghosts, so it can't appear before release. (The capture condition is
-            // the arm guard so the whole match reads as one dispatch — clippy's collapsible_match.)
+            // `UNIT_NPC_FLAG_SPIRITHEALER` 0x20 (`UnitDefines.h:662`), which the activate's gate
+            // checks; the healer streams only to ghosts.
             SessionEvent::ObjectCreate {
                 guid,
                 kind,
@@ -112,11 +101,7 @@ impl Probe for Spirit {
                 self.healer = Some((*guid, *position));
             }
             SessionEvent::ItemCreate { guid, fields, .. } => {
-                // --spirit: seed/overlay the item's merged store (the app's `Items`
-                // discipline) — the durability baseline reads off these. The print
-                // is the created-semantics live proof: a broken item's create OMITS
-                // its zero `DURABILITY` word, and the pair must still read `0/max`
-                // (the director's "100% on broken gear" bug).
+                // A broken item's create omits its zero `DURABILITY`; it must still read `0/max`.
                 if let Some((d, m)) = fields
                     .item_durability()
                     .zip(fields.item_max_durability())
@@ -136,9 +121,7 @@ impl Probe for Spirit {
                     }
                 }
             }
-            // --spirit: an item values-delta — the durability wire under test. Log
-            // every `ITEM_FIELD_DURABILITY` it carries (post-activate ones are the
-            // verdict's evidence) and merge into the item's store.
+            // Item values deltas: the post-activate durability ones are the verdict's evidence.
             SessionEvent::ObjectValues { guid, fields } if guid::is_item(*guid) => {
                 if let Some(d) = fields.item_durability() {
                     if self.activate_sent {
@@ -162,10 +145,7 @@ impl Probe for Spirit {
                     }
                 }
             }
-            // The old Teleport arm's `else if cli.spirit … healer_tp_landed` branch. Its condition is
-            // equivalent to the else-if: `healer_tp_sent` can only become true after `graveyard_pos`
-            // is Some (the healer-TP poll requires it), so this and World's graveyard capture (the
-            // other branch) are temporally disjoint. (Folded into the arm guard — collapsible_match.)
+            // `healer_tp_sent` follows World's graveyard capture, so this is the healer teleport.
             SessionEvent::Teleport { guid, .. }
                 if *guid == cx.world.self_guid
                     && self.healer_tp_sent
@@ -184,8 +164,7 @@ impl Probe for Spirit {
         let healer_tp_sent = self.healer_tp_sent;
         let session = &mut *cx.session;
 
-        // Cleanup before judging: the res left the character alive at 75% — a GM repair keeps
-        // re-runs (and the shared GM character's gear) clean. Fire-and-forget; the stream is done.
+        // Repair before judging, so the 25% loss does not carry into the next run.
         session.send_chat(".repairitems")?;
 
         if !self.activate_sent {
@@ -195,7 +174,7 @@ impl Probe for Spirit {
             );
         }
         if !revived_seen {
-            // Don't leave the shared GM character a ghost (live-observed: the first run did).
+            // Do not leave the shared GM character a ghost.
             session.send_chat(".revive")?;
             bail!(
                 "--spirit: CMSG_SPIRIT_HEALER_ACTIVATE never cleared the ghost flag — the res didn't land (a cleanup .revive was sent)"
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/swap_pack_slots.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/swap_pack_slots.rs
index 12f84f7f..15346cbf 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/swap_pack_slots.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/swap_pack_slots.rs
@@ -1,6 +1,5 @@
-//! `--swap-pack-slots`: `CMSG_SWAP_INV_ITEM` (the backpack pick/place/swap wire). Swap two 1-based
-//! backpack slots, assert the exchange, then swap back and assert the original layout (leaves the
-//! character as found).
+//! `--swap-pack-slots`: `CMSG_SWAP_INV_ITEM` swaps two 1-based backpack slots, then swaps them
+//! back so the character is left as found.
 
 use std::time::{Duration, Instant};
 
@@ -20,8 +19,7 @@ impl Probe for SwapPackSlots {
         let session = &mut *cx.session;
         let (a, b) = (self.a, self.b);
 
-        // --swap-pack-slots: swap two backpack slots, assert the exchange landed, then swap back and
-        // assert the original layout is restored (leaves the character as found).
+        // Backpack slots are player-array slots from 23 (`INVENTORY_SLOT_ITEM_START`).
         let sf = world
             .self_fields
             .as_mut()
@@ -38,8 +36,6 @@ impl Probe for SwapPackSlots {
              CMSG_SWAP_INV_ITEM src {wire_a} dst {wire_b}"
         );
 
-        // A closure would borrow `session` + `sf` at once; inline the drain so the borrows don't
-        // overlap. Await until both slots read their expected guids (or 5s).
         session.swap_inv_item(wire_a, wire_b)?;
         let mut settled = false;
         let drain_until = Instant::now() + Duration::from_secs(5);
@@ -64,7 +60,6 @@ impl Probe for SwapPackSlots {
         }
         println!("✅ swap: slots {a}↔{b} exchanged in the descriptor (guids confirmed).");
 
-        // Swap back and require the original layout to return.
         session.swap_inv_item(wire_a, wire_b)?;
         let mut restored = false;
         let drain_until = Instant::now() + Duration::from_secs(5);
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/use_pack_slot.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/use_pack_slot.rs
index deccaa37..6a8410fe 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/use_pack_slot.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/use_pack_slot.rs
@@ -1,5 +1,5 @@
-//! `--use-pack-slot`: `CMSG_USE_ITEM` on a 1-based backpack slot; require a server reaction — a
-//! stack-count delta, a destroy on the item's guid, or an explicit cast-result refusal.
+//! `--use-pack-slot`: `CMSG_USE_ITEM` on a 1-based backpack slot must draw a stack-count delta,
+//! a destroy of the item, or a cast-result refusal.
 
 use std::time::{Duration, Instant};
 
@@ -18,7 +18,7 @@ impl Probe for UsePackSlot {
         let session = &mut *cx.session;
         let n = self.n;
 
-        // --use-pack-slot: poke a real item and require a server reaction on its guid.
+        // Bag 255 (`INVENTORY_SLOT_BAG_0`) is the player's own array; the backpack is slots 23-38.
         let sf = world
             .self_fields
             .as_ref()
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/vendor.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/vendor.rs
index d8a76eb9..25c2b334 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/vendor.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/vendor.rs
@@ -1,6 +1,5 @@
-//! `--vendor`: the vendor wire (decision 0081 phase 4). Auto-find the nearest streamed vendor,
-//! `CMSG_LIST_INVENTORY` it, buy the cheapest row, and require a reaction — plus confirm the money
-//! accessor (`PLAYER_FIELD_COINAGE`) reads and that a coinage delta lands on that field.
+//! `--vendor`: list the nearest vendor, buy its cheapest row and require a reaction; a coinage
+//! delta confirms the `PLAYER_FIELD_COINAGE` accessor.
 
 use std::time::{Duration, Instant};
 
@@ -9,8 +8,8 @@ use benilla_protocol::{decode, SessionEvent};
 
 use crate::probes::{Ctx, Probe};
 
-/// vmangos `INTERACTION_DISTANCE` (`Objects/ObjectDefines.h:24`) — the range every NPC service
-/// opcode is gated on, silently.
+/// vmangos `INTERACTION_DISTANCE` (`Objects/ObjectDefines.h:24`): every NPC service opcode past
+/// it is silently ignored.
 const INTERACTION_DISTANCE: f32 = 5.0;
 
 pub(crate) struct Vendor;
@@ -21,8 +20,6 @@ impl Probe for Vendor {
         let session = &mut *cx.session;
         let self_guid = world.self_guid;
 
-        // --vendor: list the nearest streamed vendor and buy its cheapest row; also confirm the money
-        // accessor (`PLAYER_FIELD_COINAGE`) reads and that any coinage delta lands on that field.
         let sf = world
             .self_fields
             .as_mut()
@@ -36,7 +33,7 @@ impl Probe for Vendor {
         );
 
         let self_pos = world.tracked.get(&self_guid).map(|t| t.position);
-        // The nearest advertised vendor (2D distance from us; z ignored — Northshire is ~flat here).
+        // Nearest by 2D distance; Northshire is nearly flat.
         let vendor = self_pos.and_then(|p| {
             world
                 .vendors
@@ -48,12 +45,8 @@ impl Probe for Vendor {
             "no UNIT_NPC_FLAG_VENDOR creature streamed in range (fresh Northshire spawn has none — \
              re-run with a longer --seconds after moving toward a vendor, or grant GM to teleport)",
         )?;
-        // The server refuses SILENTLY past interaction range, so an out-of-range send looks exactly
-        // like a broken wire: no packet, a 5s drain, "nothing arrived". Name the real cause here
-        // instead of leaving it to be re-diagnosed. VERIFIED vmangos `INTERACTION_DISTANCE = 5.0f`
-        // (`Objects/ObjectDefines.h:24`), checked by `Player::CanInteractWithNPC`'s last gate
-        // (`Objects/Player.cpp:2556`) — a 3D check with both bounding radii allowed for, so this 2D
-        // screen is approximate and deliberately generous.
+        // The server's check (`Player::CanInteractWithNPC`, `Objects/Player.cpp:2556`) is 3D and
+        // allows for both bounding radii, so this 2D screen is only approximate.
         if dist > INTERACTION_DISTANCE {
             bail!(
                 "nearest vendor {vendor_guid:#x} is {dist:.1} yd away; vmangos refuses \
@@ -70,7 +63,6 @@ impl Probe for Vendor {
         );
         session.list_inventory(vendor_guid)?;
 
-        // Drain for the vendor's stock list.
         let mut items: Option<Vec<benilla_protocol::messages::VendorItem>> = None;
         let drain_until = Instant::now() + Duration::from_secs(5);
         while Instant::now() < drain_until && items.is_none() {
@@ -104,8 +96,7 @@ impl Probe for Vendor {
             bail!("the vendor listed 0 rows — can't exercise a buy");
         }
 
-        // Buy the cheapest priced, in-stock row (price > 0; current_count 0 = sold out — a limited
-        // row we already drained; 0xFFFF_FFFF = unlimited, always buyable), one stack.
+        // `current_count` 0 is sold out and 0xFFFF_FFFF unlimited.
         let cheapest = rows
             .iter()
             .filter(|r| r.price > 0 && r.current_count != 0)
@@ -117,10 +108,7 @@ impl Probe for Vendor {
         );
         session.buy_item(vendor_guid, cheapest.entry, 1)?;
 
-        // Drain for a reaction: the item arriving, the stock updating, a coinage delta on exactly the
-        // COINAGE field, or a decoded refusal — any one proves the round trip. Keep draining the full
-        // window (not stopping at the first) so a coinage delta — the strongest evidence, it confirms
-        // the accessor *index* — is captured even when the item-create lands first in the same batch.
+        // Keep draining past the first reaction: the coinage delta can trail the item create.
         let mut round_trip: Option<String> = None;
         let mut coinage_delta: Option<String> = None;
         let drain_until = Instant::now() + Duration::from_secs(5);
diff --git a/crates/benilla-protocol/src/bin/benilla-world/probes/worldstate.rs b/crates/benilla-protocol/src/bin/benilla-world/probes/worldstate.rs
index 7cb17b50..fe2dcce6 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/probes/worldstate.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/probes/worldstate.rs
@@ -1,28 +1,10 @@
-//! `--worldstate`: the world-state table's two wires, end to end against the live server.
+//! `--worldstate`: `.debug send worldstate <id> <value>` must come back as that exact
+//! `SMSG_UPDATE_WORLD_STATE` pair, and a zone change must re-send `SMSG_INIT_WORLD_STATES`
+//! (`Player::UpdateZone`, `Player.cpp:6660`), which cannot be requested.
 //!
-//! Both are worth a live run for different reasons. `SMSG_UPDATE_WORLD_STATE` is *deterministic* —
-//! `.debug send worldstate <id> <value>` makes the server send one pair we chose, so the probe can
-//! require that exact pair back and a wrong reader shows up as a mismatch rather than a plausible
-//! number. `SMSG_INIT_WORLD_STATES` is the one with real parse risk (two leading dwords, a `u16`
-//! count, a run of pairs, a `(0,0)` terminator that *is* counted) and it can't be requested — so
-//! the probe forces one by teleporting across a zone boundary, which is what makes vmangos re-send
-//! it (`Player::UpdateZone` → `SendInitWorldStates`, `Player.cpp:6660`).
-//!
-//! **The update leg needs a temporary grant.** `.debug send worldstate` sits in
-//! `debugSendCommandTable` at **SEC_DEVELOPER = 5** (vmangos `Chat.cpp:323`) — one above the
-//! gmlevel 6 the slot-keyed probe accounts carry (decisions 0450/0651). Without it the server answers
-//! *"This command is not available to you."* in chat and sends no packet, and the probe fails on
-//! the update leg while the init leg still passes.
-//!
-//! The effective level lives in **`realmd.account_access`**, not `realmd.account.gmlevel` —
-//! mangosd reads the former (rows per `RealmID`, plus a `-1` catch-all) and ignores the latter for
-//! command gating. Grant, run, revert, with the account offline:
-//!
-//! ```text
-//! UPDATE realmd.account_access SET gmlevel=5 WHERE id=<account id>;   -- both rows
-//! cargo run -p benilla-protocol --bin benilla-world -- probeN pprobeN --worldstate --seconds 16
-//! UPDATE realmd.account_access SET gmlevel=3 WHERE id=<account id>;   -- put it straight back
-//! ```
+//! The command needs SEC_DEVELOPER, 5 (vmangos `Chat.cpp:323`); below it the server only refuses
+//! in chat. The level is read from `realmd.account_access` (a row per `RealmID` and a `-1` row),
+//! not `realmd.account.gmlevel`: grant both rows with the account offline, then revert.
 
 use std::time::{Duration, Instant};
 
@@ -31,22 +13,18 @@ use benilla_protocol::SessionEvent;
 
 use crate::probes::{Ctx, Probe};
 
-/// Northshire (zone 9, Elwynn Forest) — the same spot the quest probes stage on.
+/// Northshire, zone 9 (Elwynn Forest).
 const ELWYNN_TP: &str = ".go xyz -8902.59 -162.606 82.0223";
-/// Stormwind's Trade District (zone 1519) — a different zone on the same map, so the hop from
-/// [`ELWYNN_TP`] is a genuine `UpdateZone` and forces a fresh `SMSG_INIT_WORLD_STATES`.
+/// Stormwind's Trade District, zone 1519 on the same map, so the hop is a real zone change.
 const STORMWIND_TP: &str = ".go xyz -8913.0 554.0 93.8";
-/// How long to sit in Elwynn before hopping, so the first zone's init has landed and the second is
-/// unambiguously a *second* packet.
+/// Time in Elwynn before the hop, so the second init is clearly a second packet.
 const HOP_AFTER: Duration = Duration::from_secs(4);
 
-/// A synthetic `(id, value)` no real content uses, so a match proves our reader and not a
-/// coincidence with a live Silithus/AQ counter.
+/// A synthetic `(id, value)` no real content uses.
 const PROBE_ID: u32 = 0xBEEF;
 const PROBE_VALUE: u32 = 1_234_567;
 
-/// One received `SMSG_INIT_WORLD_STATES`: the packet's `(map, zone)` scope and its pair run
-/// verbatim — terminator included, which [`WorldState::verify`] asserts on.
+/// One `SMSG_INIT_WORLD_STATES`: its `(map, zone)` scope and its pairs, terminator included.
 struct Init {
     map: u32,
     zone: u32,
@@ -75,7 +53,6 @@ impl Probe for WorldState {
             return Ok(());
         }
         self.hopped = true;
-        // The zone hop (forces an init) and the one deterministic pair, back to back.
         cx.session.send_chat(STORMWIND_TP)?;
         cx.session
             .send_chat(&format!(".debug send worldstate {PROBE_ID} {PROBE_VALUE}"))?;
@@ -122,8 +99,7 @@ impl Probe for WorldState {
         if self.inits.is_empty() {
             bail!("no SMSG_INIT_WORLD_STATES arrived — the zone hop should have forced one");
         }
-        // The terminator is counted by the server and read by us: a well-formed init ends on (0,0).
-        // Assert it rather than assume, since dropping it would be the natural "helpful" bug.
+        // The server counts the (0,0) terminator, so a parsed init must end on it.
         for init in &self.inits {
             if init.states.last() != Some(&(0, 0)) {
                 bail!(
diff --git a/crates/benilla-protocol/src/bin/benilla-world/world.rs b/crates/benilla-protocol/src/bin/benilla-world/world.rs
index 89b75817..8ff6e66f 100644
--- a/crates/benilla-protocol/src/bin/benilla-world/world.rs
+++ b/crates/benilla-protocol/src/bin/benilla-world/world.rs
@@ -1,7 +1,4 @@
-//! The shared world state every probe reads: the entity tracker, the merged self descriptor, the
-//! item/vendor stores, the opcode tally — plus the session-keeping acks (teleport, force-speed, the
-//! granted movement-mode family) that keep *any* session alive regardless of probe mix, and the shared
-//! [`DeathArc`] scenario machinery (`--death`/`--spirit` both read it, so neither owns it).
+//! The state every probe shares, the acks that keep any session alive, and the [`DeathArc`].
 
 use std::collections::{BTreeMap, HashMap};
 use std::time::Instant;
@@ -12,9 +9,8 @@ use benilla_protocol::{
     SpeedKind, WorldSession,
 };
 
-/// A Kobold Vermin spawn in Northshire (mangos `creature` guid 79992) — the `--attack` teleport
-/// target: hostile, level 1, melee-reach the moment we land on it. Lives here (not in a probe)
-/// because attack staging, loot staging, and the [`DeathArc`] staging all teleport to it.
+/// A Kobold Vermin spawn in Northshire (`creature` guid 79992): hostile, level 1, in melee reach
+/// on landing. Attack, loot and death staging all teleport here.
 pub(crate) const ATTACK_TP: &str = ".go xyz -8780.71 -164.568 81.94";
 
 /// One entity decoded from the stream, as `benilla-world` reports it (raw WoW coords).
@@ -24,10 +20,7 @@ pub(crate) struct Tracked {
     pub(crate) orientation: f32,
 }
 
-/// The shared die→release→ghost→corpse scenario machinery (decision 0308 slice 1). Created when
-/// `--death` or `--spirit` is set; both probes read it, so neither owns it. The staging is in
-/// [`World::stage`]; the die/release pumps in [`World::poll`]; the ghost/graveyard/reclaim evidence
-/// in [`World::on_event`].
+/// The shared die, release, ghost and corpse sequence the death probes read.
 #[derive(Default)]
 pub(crate) struct DeathArc {
     pub(crate) die_sent: bool,
@@ -40,13 +33,10 @@ pub(crate) struct DeathArc {
     pub(crate) ghost_seen: bool,
     pub(crate) graveyard_pos: Option<[f32; 3]>,
     pub(crate) reclaim_delay_ms: Option<u32>,
-    /// Set when the death probe sends `.revive` OR the spirit probe sends the healer activate — the
-    /// ghost-clear check keys off this instead of either probe's own flag, so the two are decoupled.
+    /// Set by `.revive` (death) or the healer activate (spirit); the ghost-clear check needs it.
     pub(crate) revive_initiated: bool,
     pub(crate) revived_seen: bool,
-    /// **Stop at dead-unreleased** — `--self-res` sets it, and nothing else does (decision 1746).
-    /// The soulstone button lives on the DEATH dialog, which only exists *before* the release; an
-    /// arc that repops on its own would walk straight past the state under test.
+    /// Stop dead and unreleased for `--self-res`: the DEATH dialog exists only until release.
     pub(crate) hold_release: bool,
 }
 
@@ -56,18 +46,16 @@ pub(crate) struct World {
     pub(crate) self_name: String,
     pub(crate) self_level: u8,
     pub(crate) self_map: u32,
-    /// The `SMSG_CHAR_ENUM` spawn pose, the [`Self::self_pose`] fallback before our own create streams.
+    /// The `SMSG_CHAR_ENUM` spawn pose, used until our own create streams.
     pub(crate) spawn_pos: [f32; 3],
     pub(crate) tracked: HashMap<u64, Tracked>,
-    /// Our own descriptor fields (equipment/pack slots are PRIVATE-flagged — sent only for our own
-    /// player) merged across the create + every values delta.
+    /// Our merged descriptor; its private equipment and pack slots are sent only to us.
     pub(crate) self_fields: Option<ObjectFields>,
     pub(crate) item_entries: HashMap<u64, u32>,
     pub(crate) item_stacks: HashMap<u64, u32>,
     pub(crate) item_names: HashMap<u32, String>,
-    /// Streamed NPCs that advertise UNIT_NPC_FLAG_VENDOR, by guid → position.
     pub(crate) vendors: HashMap<u64, [f32; 3]>,
-    /// The last same-map teleport landing point (the `--attack`/`--charge`/`--loot`/`--death` spot).
+    /// The last same-map teleport landing point, whichever probe's staging sent it.
     pub(crate) attack_pos: Option<[f32; 3]>,
     /// Every self force-speed change seen (kind, counter, flat speed).
     pub(crate) speed_changes_seen: Vec<(SpeedKind, u32, f32)>,
@@ -79,21 +67,17 @@ pub(crate) struct World {
     pub(crate) item_answer: Option<(u32, Option<String>)>,
     pub(crate) cast_verdict: Option<(u32, bool, Option<u8>)>,
     pub(crate) targeted_verdict: Option<(u32, bool, Option<u8>)>,
-    /// The `--spells` dest-cast phase's spell (decision 0792): a `SMSG_CAST_RESULT` naming it
-    /// routes to [`Self::dest_verdict`] instead of the positional pair above — the dest phase
-    /// runs concurrently with the targeted phase, so position alone can't route it.
+    /// The `--spells` ground-cast spell, whose `SMSG_CAST_RESULT` goes to [`Self::dest_verdict`].
     pub(crate) dest_spell: Option<u32>,
     pub(crate) dest_verdict: Option<(u32, bool, Option<u8>)>,
     pub(crate) swings_seen: u32,
-    /// The refusals the server answered a swing with, by arm — `--attack`'s phase 2 verdict. The
-    /// wire has no reason byte, so the arm IS the reason.
+    /// Swing refusals: the wire has no reason byte, the opcode is the reason.
     pub(crate) swing_refusals: Vec<AttackSwingError>,
     pub(crate) self_moves: u32,
     pub(crate) tally: BTreeMap<String, u32>,
     pub(crate) total: u32,
     pub(crate) death_arc: Option<DeathArc>,
-    /// Shared staging flags: the ATTACK_TP (attack/loot/DeathArc all want it) and the McBride
-    /// teleport (questlog/giverstatus both want it) each go out once, set by whichever stages first.
+    /// Shared teleports go out once: whichever probe stages first sets the flag.
     pub(crate) attack_tp_staged: bool,
     pub(crate) mcbride_staged: bool,
 }
@@ -139,10 +123,7 @@ impl World {
         }
     }
 
-    /// Our tracked pose, for the movement acks the server expects while dead/ghost (root,
-    /// water-walk): the probe holds still throughout the arc, so any recent `tracked` position is
-    /// truthful — fall back to the SMSG_CHAR_ENUM spawn pose for the sliver of time before our own
-    /// ObjectCreate has streamed.
+    /// Our pose for movement acks: the probe holds still, so the tracked position is current.
     pub(crate) fn self_pose(&self) -> ([f32; 3], f32) {
         match self.tracked.get(&self.self_guid) {
             Some(t) => (t.position, t.orientation),
@@ -150,26 +131,19 @@ impl World {
         }
     }
 
-    /// Count a received packet: one per `recv`, before decode (the opcode tally + total).
+    /// Count a received packet, once per `recv` and before decode.
     pub(crate) fn tally_packet(&mut self, msg: &ServerPacket) {
         self.total += 1;
         *self.tally.entry(msg.name()).or_default() += 1;
     }
 
-    /// One-time pre-stream staging for the [`DeathArc`]. Called BEFORE the probes' stage loop, so
-    /// for `--spirit` the order is preserved: the arc's `.revive` + teleport, then spirit's
-    /// `.repairitems`.
+    /// The [`DeathArc`]'s staging. It runs before the probes' own, so the arc's `.revive` and
+    /// teleport precede `--spirit`'s `.repairitems`.
     pub(crate) fn stage(&mut self, session: &mut WorldSession) -> Result<()> {
         if self.death_arc.is_some() {
-            // Stage AWAY from any graveyard first (the kobold spot the other probes use): dying AT a
-            // graveyard makes the release teleport a 0-yd no-op and the >20-yd graveyard assertion
-            // reads it as a missing port (live-observed: a cleanup `.revive` leaves the character at
-            // the graveyard, and the next `.die` there re-pops in place). The `.die` itself goes out
-            // in-loop, once this staging teleport has landed. The `.revive` first is defensive: a
-            // prior aborted run can leave the character a ghost (live-observed), and the arc under
-            // test must start from alive (it's a no-op on a living character).
+            // Die away from any graveyard: a death at one re-pops in place, and the graveyard
+            // check reads that as a missing port. `.revive` first: a prior run may leave a ghost.
             session.send_chat(".revive")?;
-            // The ATTACK_TP is the shared teleport — mark it staged so attack/loot don't re-send it.
             session.send_chat(ATTACK_TP)?;
             self.attack_tp_staged = true;
             println!("sent GM: .revive (defensive); teleport (death staging): {ATTACK_TP}");
@@ -180,16 +154,13 @@ impl World {
     /// Every pump iteration, before recv: the [`DeathArc`] die/release steps.
     pub(crate) fn poll(&mut self, session: &mut WorldSession) -> Result<()> {
         if let Some(arc) = &mut self.death_arc {
-            // --death/--spirit: kill ourselves once the staging teleport has landed (`.die` with
-            // nothing selected targets the caster).
+            // `.die` with nothing selected kills the caster; sent once the staging teleport lands.
             if !arc.die_sent && self.attack_pos.is_some() {
                 session.send_chat(".die")?;
                 println!("sent GM: .die (self-kill)");
                 arc.die_sent = true;
             }
-            // --death: once we've hit 0 health AND the server has force-rooted us (the wire doesn't
-            // guarantee which arrives first — see the MoveRoot/ObjectValues arms below), release the
-            // spirit: the RELEASE SPIRIT button's `CMSG_REPOP_REQUEST` (decision 0308 §1).
+            // Release spirit (`CMSG_REPOP_REQUEST`) once dead and rooted, in whichever order.
             if !arc.hold_release && !arc.repop_sent && arc.died_at.is_some() && arc.rooted_seen {
                 session.repop_request()?;
                 println!("sent CMSG_REPOP_REQUEST (release spirit)");
@@ -199,8 +170,7 @@ impl World {
         Ok(())
     }
 
-    /// Every decoded event, before the probes' `on_event`: the ungated narration/evidence + the
-    /// unconditional session-keeping acks + the [`DeathArc`] evidence.
+    /// Each decoded event, before the probes' `on_event`: logging, session acks, death evidence.
     pub(crate) fn on_event(&mut self, ev: &SessionEvent, session: &mut WorldSession) -> Result<()> {
         match ev {
             SessionEvent::ObjectCreate {
@@ -214,8 +184,7 @@ impl World {
                 if *guid == self.self_guid {
                     self.self_fields = Some(fields.clone());
                 }
-                // A vendor advertises UNIT_NPC_FLAG_VENDOR (0x4 — NOT 0x80, which is
-                // INNKEEPER in 1.12; VERIFIED vmangos `UnitDefines.h:659`) in NPC_FLAGS.
+                // `UNIT_NPC_FLAG_VENDOR` is 0x4; in 1.12 0x80 is innkeeper (`UnitDefines.h:659`).
                 if *kind == EntityKind::Unit && fields.unit_npc_flags() & 0x4 != 0 {
                     self.vendors.insert(*guid, *position);
                 }
@@ -237,10 +206,8 @@ impl World {
                     .insert(*guid, fields.item_stack_count().unwrap_or(1));
             }
             SessionEvent::ObjectValues { guid, fields } if *guid == self.self_guid => {
-                // --death: the server force-flushes UNIT_FIELD_HEALTH the instant we
-                // die — a values delta carrying an EXPLICIT 0 (not merely absent) is
-                // the death instant itself. Must be read off `fields` (this delta)
-                // before the merge below moves it.
+                // The server flushes an explicit UNIT_FIELD_HEALTH 0 at the instant of death; read
+                // it off this delta, before the merge below.
                 let pose = self.self_pose();
                 if let Some(arc) = &mut self.death_arc {
                     if arc.died_at.is_none() && fields.unit_health() == Some(0) {
@@ -255,10 +222,8 @@ impl World {
                 }
                 if let Some(sf) = &mut self.self_fields {
                     sf.merge(fields.clone());
-                    // PLAYER_FLAGS_GHOST (bit 0x10, field 190) sets at release and
-                    // clears at revive — read off the MERGED store, not this delta
-                    // alone: a delta that doesn't touch PLAYER_FLAGS reads as an
-                    // absent field on `fields`, not "still whatever it last was".
+                    // PLAYER_FLAGS_GHOST (0x10, field 190) sets at release and clears at revive.
+                    // Read the merged store: a delta without PLAYER_FLAGS reads as absent.
                     if let Some(arc) = &mut self.death_arc {
                         if !arc.ghost_seen && sf.player_is_ghost() {
                             arc.ghost_seen = true;
@@ -326,7 +291,6 @@ impl World {
                         b.slot, b.action, b.kind
                     );
                 }
-                // Item-query the first item-kind button (T2 wire groundwork), once.
                 if self.item_asked.is_none() {
                     if let Some(b) = buttons.iter().find(|b| b.kind == 0x80) {
                         session.item_query(b.action, 0)?;
@@ -372,9 +336,8 @@ impl World {
                 counter,
                 speed,
             } if *guid == self.self_guid => {
-                // Ack with our live (streamed) pose — a zeroed fallback would ask the
-                // server to relocate us to (0,0,0), so no known pose means no ack (the
-                // post-stream ensure then fails loudly instead).
+                // The ack carries our pose and a zeroed one would move us to (0,0,0), so with no
+                // streamed pose there is no ack.
                 let Some(t) = self.tracked.get(guid) else {
                     println!(
                         "force {kind:?} speed change before our own create streamed — cannot ack"
@@ -394,12 +357,8 @@ impl World {
                 );
                 self.speed_changes_seen.push((*kind, *counter, *speed));
             }
-            // A cross-map port. Unacked, `HandleMoveWorldportAckOpcode` never runs, so the
-            // destination map streams NOTHING — no self create, and none of the arrival's own
-            // side effects (`--mount-tele`'s subject: the mount strip a map that forbids mounting
-            // performs right there). The tracked set is deliberately NOT purged here: the ack for
-            // whatever the arrival sends needs a pose, and ours is the landing point the packet
-            // just gave us.
+            // Until acked, `HandleMoveWorldportAckOpcode` never runs and the new map streams
+            // nothing. Keep the tracked set: acks after arrival need our pose, the landing point.
             SessionEvent::Worldport {
                 map_id,
                 position,
@@ -428,11 +387,9 @@ impl World {
                 position,
                 ..
             } if *guid == self.self_guid => {
-                // Ack the same-map port (the server freezes our movement otherwise).
+                // Ack the same-map port; the server freezes our movement until we do.
                 session.teleport_ack(*guid, *counter)?;
                 self.attack_pos = Some(*position);
-                // Move our tracked self to the landing point so range-based picks (the
-                // --vendor nearest-vendor search) measure from where we actually are.
                 if let Some(t) = self.tracked.get_mut(guid) {
                     t.position = *position;
                 }
@@ -440,11 +397,7 @@ impl World {
                     "teleported to ({:.1}, {:.1}, {:.1}) — ack sent",
                     position[0], position[1], position[2]
                 );
-                // --death: the graveyard port after release rides this same event —
-                // record it without duplicating the ack above. The spirit probe's
-                // healer_tp_landed capture (the old else-if branch) now lives in its own
-                // on_event: `healer_tp_sent` can only become true after `graveyard_pos` is
-                // Some (the healer-TP poll requires it), so the two are temporally disjoint.
+                // The graveyard port after release is this same event, already acked above.
                 if let Some(arc) = &mut self.death_arc {
                     if arc.repop_sent && arc.graveyard_pos.is_none() {
                         arc.graveyard_pos = Some(*position);
@@ -526,11 +479,8 @@ impl World {
                     }
                 }
             }
-            // **A granted mover mode** (root / water-walk / feather-fall / hover — decision 0866)
-            // must be acked with the echoed counter + our current pose, or the server never applies
-            // the change and observers never see it. Unconditional session-keeping (like
-            // teleport/force-speed): a mode granted outside the death arc would otherwise go
-            // un-acked, and the real client always acks.
+            // Root, water walk, feather fall and hover need an ack echoing the counter with our
+            // pose, or the server never applies them; the 1.12 client always acks.
             SessionEvent::MoveMode {
                 guid,
                 counter,
@@ -538,12 +488,9 @@ impl World {
                 apply,
             } if *guid == self.self_guid => {
                 let pose = self.self_pose();
-                // The ack's MovementInfo must carry the applied mode's own bit: for root the server
-                // KICKS one without it (vmangos `HandleMoveRootAck:715-723`; live-verified — the
-                // flags-0 ack drew "movement info does not have rooted movement flag" in
-                // Movement.log and the root never confirmed, so release sent no unroot), and for the
-                // other three the word IS the mover's new flags. This probe holds no mover state of
-                // its own, so the applied bit alone is the honest word.
+                // The ack's MovementInfo must carry the mode's own bit: vmangos kicks a player
+                // whose root ack lacks it (`HandleMoveRootAck`, MovementHandler.cpp:722-729). For
+                // the other modes the word becomes the mover's flags; the probe keeps no others.
                 let flags = if *apply { mode.flag() } else { 0 };
                 session.move_mode_ack(*guid, *counter, *mode, *apply, flags, pose)?;
                 if let Some(arc) = &mut self.death_arc {
diff --git a/crates/benilla-protocol/src/events.rs b/crates/benilla-protocol/src/events.rs
index 96504d2c..30a058ca 100644
--- a/crates/benilla-protocol/src/events.rs
+++ b/crates/benilla-protocol/src/events.rs
@@ -1,13 +1,4 @@
-//! Decoded session events — the codec's typed output.
-//!
-//! `benilla-protocol` decodes the world stream into a flat list of [`SessionEvent`]s; the running
-//! world model (which entities exist, where they are, the clock) is the **app's** job (the ECS), not
-//! the codec's. One `SMSG_(COMPRESSED_)UPDATE_OBJECT` fans out into many create/move/remove events; a
-//! `SMSG_MONSTER_MOVE` becomes a path the app turns into a spline; the clock packet becomes a time
-//! sample the app advances. Only primitives + the coarse [`EntityKind`] classification cross this
-//! boundary.
-//!
-//! Coordinates stay **raw WoW** (the `benilla` boundary applies `bevy = (-y, z, -x)`).
+//! Decoded session events; coordinates stay raw WoW, which the app maps to `bevy = (-y, z, -x)`.
 
 use crate::messages::{
     ActionButton, AttackSwingError, AttackerState, AuctionBidderNotification, AuctionCommandTail,
@@ -26,36 +17,28 @@ use crate::messages::{
     TradeStatusExtended, TrainerSpell, TransportPose, VendorItem, WhoResults, XpGain,
 };
 
-/// Coarse entity classification, free of wire types so the app can branch on it without depending on
-/// the message layer. Part of the codec's output vocabulary (carried on [`SessionEvent::ObjectCreate`]).
+/// Coarse entity classification, free of wire types, carried on [`SessionEvent::ObjectCreate`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum EntityKind {
     Player,
     Unit,
     GameObject,
-    /// A `TYPEID_DYNAMICOBJECT` (6) create — the invisible anchor a ground-targeted spell's
-    /// area effect hangs on (Blizzard's storm, Flamestrike's burn). Carries no display id; its
-    /// visual resolves through the spell chain (`DYNAMICOBJECT_SPELLID`), not a model field.
+    /// `TYPEID_DYNAMICOBJECT` (6): an area effect's anchor, drawn via `DYNAMICOBJECT_SPELLID`.
     DynamicObject,
-    /// A `TYPEID_CORPSE` (7) create — a dead player's remains: a fresh body while the owner is a
-    /// ghost, or the **bone pile** it converts to once released/looted. It renders as the dead
-    /// player (decision 1706): the character-model chain, dressed from the corpse's own
-    /// `CORPSE_FIELD_BYTES_*` + `CORPSE_FIELD_ITEM` snapshot.
+    /// `TYPEID_CORPSE` (7): a dead player's body or bone pile, drawn as the player from its
+    /// `CORPSE_FIELD_BYTES_*` and `CORPSE_FIELD_ITEM`.
     Corpse,
     Other,
 }
 
-/// Which character-management verb produced a [`SessionEvent::CharActionResult`] — so the screen can
-/// phrase the outcome ("created"/"deleted") and map the `WorldResult` code against the right family.
+/// Which character verb a [`SessionEvent::CharActionResult`] answers, and so which code family.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum CharAction {
     Create,
     Delete,
 }
 
-/// A unit's 6 movement speeds (yd/s), decoded from its `LIVING` block. The animation selector keys its
-/// walk-vs-run boundary on `walk` (2× it → run, RF-0057); the net bridge extrapolates a remote mover
-/// between movement packets at `run`/`run_back`/`swim` and turns it in place at `turn_rate` (rad/s).
+/// A unit's six movement speeds from its `LIVING` block: yd/s, except `turn_rate` in rad/s.
 #[derive(Debug, Clone, Copy, Default, PartialEq)]
 pub struct MoveSpeeds {
     pub walk: f32,
@@ -67,7 +50,6 @@ pub struct MoveSpeeds {
 }
 
 impl MoveSpeeds {
-    /// From the wire order `[walk, run, run_back, swim, swim_back, turn_rate]` (RF-0058).
     fn from_wire(s: [f32; 6]) -> Self {
         Self {
             walk: s[0],
@@ -80,63 +62,40 @@ impl MoveSpeeds {
     }
 }
 
-/// Where a login attempt currently is — the IO thread emits these as it walks the pre-roster
-/// sequence (decision 0539), and the login screen's connecting dialog quotes the matching
-/// `LOGIN_STATE_*` glue string for each.
+/// A login attempt's pre-roster stage; the connecting dialog shows its `LOGIN_STATE_*` string.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum LoginStage {
     /// Dialing the auth server (`LOGIN_STATE_CONNECTING`).
     Connecting,
     /// SRP6 challenge/proof in flight (`LOGIN_STATE_AUTHENTICATING`).
     Authenticating,
-    /// Realm picked; the world-socket handshake + char enum (`LOGIN_STATE_HANDSHAKING`).
+    /// Realm picked; the world-socket handshake and char enum (`LOGIN_STATE_HANDSHAKING`).
     Handshaking,
 }
 
-/// **How a world session ended** — the fact [`SessionEvent::Disconnected`] carries alongside its
-/// reason string, and the one the client's whole post-session behaviour hangs on (decision 1262).
-///
-/// The two are not shades of the same thing. A logout is a door the player walked through, and the
-/// roster on the other side of it is the character-select screen they asked for. A loss is a door
-/// that slammed: the reference's engine fires `DISCONNECTED_FROM_SERVER`, and its `GlueParent.lua`
-/// answers `SetGlueScreen("login")` + `GlueDialog_Show("DISCONNECTED")` — back to the account
-/// screen, one Okay button, no retry. Before this the app told them apart by comparing the reason
-/// *string* to `"logged out"`, which is how "the session died" and "the session ended" came to share
-/// one code path.
+/// How a world session ended. On a loss the reference fires `DISCONNECTED_FROM_SERVER` and
+/// `GlueParent.lua` returns to the login screen; a logout returns to character select.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SessionEnd {
-    /// A clean, client-initiated logout the server confirmed (`SMSG_LOGOUT_COMPLETE`). The IO
-    /// thread cycles the connection and a fresh [`SessionEvent::CharacterList`] follows — the
-    /// teardown here is bookkeeping between two halves of one continuous session.
+    /// A logout the server confirmed (`SMSG_LOGOUT_COMPLETE`); a fresh roster follows.
     LoggedOut,
-    /// The stream died under us: a socket error, an EOF, or a post-roster handshake failure. A
-    /// **displacement kick is exactly this** and carries nothing else — vmangos's
-    /// `WorldSession::KickPlayer` is a bare `CloseSocket()`, no packet (verified in
-    /// `vmangos-core/src/game/Server/WorldSession.cpp`), so "another client took the account" and
-    /// "the server went away" are the same event on the wire and get the same answer.
+    /// The stream died: a socket error, an EOF or a post-roster handshake failure. A displacement
+    /// kick is this too: vmangos `WorldSession::KickPlayer` only closes the socket, no packet.
     Lost,
 }
 
-/// **Who refused the login, and with which byte.**
-///
-/// A login crosses two servers and each has its own result enum. They overlap numerically and mean
-/// unrelated things — 0x0C is `AUTH_LOGON_FAILED_SUSPENDED` to realmd and `AUTH_OK` to the world
-/// server — so a bare `Option<u8>` could not say what it held, and the screen could not look up the
-/// right authored string from it. It used to be exactly that bare byte: the realmd code rode it and
-/// the world code was formatted into the reason string and lost, which is why every world-side
-/// refusal reached the player as a generic "Unable to connect".
+/// Which server refused the login, and its result byte. The two enums overlap: 0x0C is
+/// `AUTH_LOGON_FAILED_SUSPENDED` to realmd but `AUTH_OK` to the world server.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum LoginRefusal {
-    /// realmd's logon-proof `AuthLogonResult` (`crate::AuthReject`) — bad password, banned, …
+    /// realmd's logon-proof `AuthLogonResult` (`crate::AuthReject`).
     Logon(u8),
-    /// The world server's `SMSG_AUTH_RESPONSE` code (`crate::WorldAuthReject`, the
-    /// `messages::AUTH_*` block) — session expired, server shutting down, …
+    /// The world server's `SMSG_AUTH_RESPONSE` code (`crate::WorldAuthReject`).
     World(u8),
 }
 
 impl LoginRefusal {
-    /// The raw byte, for logging. Deliberately not a `From`/`Into`: the whole point of the type is
-    /// that the byte alone is ambiguous, so getting it back should look like a narrowing.
+    /// The raw byte, for logging only: without its server it is ambiguous.
     pub fn byte(self) -> u8 {
         match self {
             LoginRefusal::Logon(b) | LoginRefusal::World(b) => b,
@@ -144,437 +103,257 @@ impl LoginRefusal {
     }
 }
 
-/// One decoded event from the world stream. Carries only primitives + the coarse [`EntityKind`]
-/// classification — no wire types leak to the app, and no running state lives here.
-///
-/// [`SessionEventKind`] is its fieldless twin (one variant per variant, derived): the key the
-/// app's packet-handler table dispatches on, as the reference's table is keyed by opcode.
+/// One decoded world-stream event; its fieldless twin [`SessionEventKind`] keys the handler table.
 #[derive(Debug, Clone, strum::EnumDiscriminants)]
 #[strum_discriminants(
     name(SessionEventKind),
     derive(Hash, PartialOrd, Ord, strum::EnumIter, strum::IntoStaticStr)
 )]
 pub enum SessionEvent {
-    /// A login attempt progressed to `stage` (decision 0539) — IO-thread-emitted, like
-    /// [`Self::CharacterList`], never wire-decoded.
+    /// A login attempt reached `stage`; emitted by the IO thread, never wire-decoded.
     LoginStage { stage: LoginStage },
-    /// **The realms this account may enter** (`CMD_REALM_LIST`), and the IO thread's third park.
-    ///
-    /// Emitted the moment the SRP6 logon succeeds, *before* any world socket is dialed: which
-    /// realm to dial is the answer this park is waiting for. Like [`Self::CharacterList`] it is a
-    /// pure IO-thread emit and the thread blocks on its channel until the app answers — the app
-    /// owns the policy (a remembered realm, `WOW_REALM`, or the player on the realm-list screen),
-    /// exactly as it owns the character pick.
-    ///
-    /// Re-emitted on every refresh while the screen is up (the reference re-requests the list
-    /// every 5 s) and again when the player asks to change realm, so the app never has to cache a
-    /// list across parks.
+    /// The account's realms (`CMD_REALM_LIST`); the IO thread blocks for the app's pick. Re-sent on
+    /// each refresh (the reference re-requests every 5 s) and on a realm change.
     RealmList { realms: Vec<crate::RealmInfo> },
-    /// **We are queued for a full realm** (`SMSG_AUTH_RESPONSE(AUTH_WAIT_QUEUE)`) — a wait, not
-    /// an outcome. Emitted once per queue packet while the world handshake is parked; the attempt
-    /// is still live and ends normally with a roster (admitted) or a failure. `position` is `None`
-    /// when the packet carried no readable one. `realm` is the realm we are queued for, so the
-    /// screen can name it without waiting for the roster that is on the far side of the queue.
+    /// Queued for a full realm (`AUTH_WAIT_QUEUE`), per queue packet: a wait, not an outcome.
     LoginQueued {
         position: Option<u32>,
         realm: Option<String>,
     },
-    /// A login attempt failed before the roster (decision 0539): `code` is the server's auth
-    /// result byte ([`crate::auth::AuthReject`]) when the server *refused* us, `None` for a
-    /// transport failure (dial/handshake error). The IO thread is re-parked pre-logon; the app
-    /// decides whether to resubmit (transport, with intent) or surface the dialog (refusal).
-    /// `terminal` marks a failure that *retrying cannot fix* even though it carries no auth code —
-    /// the server is simply unusable by this client (e.g. [`crate::WardenRequired`]). The app must
-    /// surface `reason` and stop, never fold it into the paced-resubmit path.
+    /// A login failed before the roster; `refusal` is `None` for a transport failure. A `terminal`
+    /// one ([`crate::WardenRequired`]) no retry can fix: show `reason` and stop.
     LoginFailed {
         refusal: Option<LoginRefusal>,
         reason: String,
         terminal: bool,
-        /// Set when the failure was the **dial itself** — the socket never opened — carrying which
-        /// of the two reasons it was and the address it was aimed at (decision 1667's follow-up).
-        /// `None` for every other transport failure (a handshake that got a socket and then broke)
-        /// and for every server refusal, which have a `code` instead.
+        /// `Some` only when the socket never opened: which dial failure, and the address.
         dial: Option<crate::DialFailure>,
     },
-    /// The account's character roster (`SMSG_CHAR_ENUM`): the world socket is authenticated and
-    /// parked at character select. The IO thread emits this each connection cycle, then waits for
-    /// the app's pick (its pick channel) before `CMSG_PLAYER_LOGIN` moves the session into the world.
-    /// `realm` is the auth realm-list entry this session connected to (the select screen's realm
-    /// name + type banner) — `None` only when the packet arrives outside the IO thread's own emit
-    /// (the raw [`crate::decode`] path has no auth context).
+    /// The roster (`SMSG_CHAR_ENUM`); the IO thread then blocks for the app's pick before
+    /// `CMSG_PLAYER_LOGIN`. `realm` is `None` on the raw [`crate::decode`] path, which has no auth.
     CharacterList {
         characters: Vec<Character>,
         realm: Option<crate::RealmInfo>,
     },
-    /// The result of a character create or delete the IO thread serviced in place while parked at
-    /// select (`SMSG_CHAR_CREATE` / `SMSG_CHAR_DELETE` result byte — decision 0423). On a successful
-    /// create/delete a fresh [`Self::CharacterList`] is emitted *before* this, so the roster is
-    /// already up to date when the screen shows the outcome. `code` is the raw `WorldResult`
-    /// (`CHAR_CREATE_SUCCESS`, a `CHAR_NAME_*` code, …) for the app to map to its status text.
+    /// `SMSG_CHAR_CREATE`/`_DELETE`'s raw `WorldResult`; on success a fresh roster comes first.
     CharActionResult { action: CharAction, code: u8 },
-    /// We are in the world: `self_guid` is our player, `name` its character name. The IO thread emits
-    /// this first, before any object updates.
+    /// We are in the world; the IO thread emits this before any object update.
     Connected {
         self_guid: u64,
         name: String,
-        /// The account's accumulated **rested billing minutes**, from the `SMSG_AUTH_RESPONSE`
-        /// that admitted this session — what `GetBillingTimeRested()` reports (decision 1820).
-        /// Rides the connect event because that is the only moment it ever arrives: the reference
-        /// keeps it in a process-lifetime global written once by the auth parser.
+        /// Rested billing minutes for `GetBillingTimeRested()`, sent once, at auth.
         billing_time_rested: u32,
-        /// The tutorial bank, when `SMSG_TUTORIAL_FLAGS` landed during the login handshake
-        /// (decision 1976); `None` when it will arrive in the world stream instead.
+        /// `SMSG_TUTORIAL_FLAGS` if it came during the handshake; `None` if it comes in-world.
         tutorial_flags: Option<Vec<u8>>,
-        /// The addons `SMSG_ADDON_INFO` hid from the Lua index space, or **`None` when the server
-        /// never answered our addon block** (decision 2175) — and the two are different: an empty
-        /// list is a reply that hid nothing, `None` is the state in which the reference's
-        /// `GetNumAddOns()` answers 0. It rides the connect event for the same reason the billing
-        /// minutes do: the reply lands during the handshake and nothing downstream can ask again.
+        /// The addons `SMSG_ADDON_INFO` hid. `None` is no reply at all, where the reference's
+        /// `GetNumAddOns()` answers 0; an empty list is a reply that hid nothing.
         addon_info: Option<Vec<String>>,
     },
-    /// The server **refused** the character we picked (`SMSG_CHARACTER_LOGIN_FAILED`) — we are not
-    /// in the world and never were, whatever [`Self::Connected`] said a moment ago.
-    ///
-    /// It arrives on the world stream, *after* the IO thread has optimistically announced the
-    /// connection (the pick is sent and the entry begins in the same breath, decision 0777 — the
-    /// destination tiles start streaming a whole round-trip before the server's snap). So this is
-    /// an entry being *revoked*, and the app answers it the way it answers a logout: tear the
-    /// half-built entry down, go back to character select, and say why. The IO thread cycles the
-    /// connection behind that, and a fresh [`Self::CharacterList`] follows.
-    ///
-    /// `result` is the server's raw byte — a **1-based reason index** the reference maps through a
-    /// six-entry jump table onto its `CHAR_LOGIN_*` strings. Mapping it to something a player can
-    /// read is the glue layer's job ([`crate::messages::ServerPacket::CharacterLoginFailed`] has
-    /// the wire law).
+    /// Our pick was refused (`SMSG_CHARACTER_LOGIN_FAILED`) after [`Self::Connected`] was sent;
+    /// `result` is a 1-based index into the reference's six `CHAR_LOGIN_*` strings.
     CharacterLoginFailed { result: u8 },
-    /// The server confirmed our logout (`SMSG_LOGOUT_COMPLETE`) — we are back at character select.
-    /// The IO thread cycles the connection immediately; a fresh [`Self::CharacterList`] follows.
+    /// Logout confirmed (`SMSG_LOGOUT_COMPLETE`); a fresh [`Self::CharacterList`] follows.
     LoggedOut,
-    /// The server answered `CMSG_LOGOUT_REQUEST` (`SMSG_LOGOUT_RESPONSE`) — and this is where the
-    /// camp countdown comes from (decision 0674). `reason` non-zero is a refusal (vmangos: 1 in
-    /// combat, 3 jumping/falling, 2 GM-frozen) and nothing further happens; `reason == 0` starts a
-    /// logout that is either `instant` — [`Self::LoggedOut`] follows at once (resting, on a taxi,
-    /// or a GM account) — or a 20-second server-side timer the client narrates.
+    /// `SMSG_LOGOUT_RESPONSE`. A non-zero `reason` refuses: 1 in combat, 2 GM-frozen, 3 falling
+    /// (vmangos). Zero starts the 20 s camp timer, or with `instant` (resting, taxi, GM) logs out.
     LogoutResponse { reason: u32, instant: bool },
     /// The server dropped a pending logout at our `CMSG_LOGOUT_CANCEL` (`SMSG_LOGOUT_CANCEL_ACK`).
     LogoutCancelled,
-    /// The session ended; carries a human-readable reason and **how** it ended ([`SessionEnd`]).
+    /// The session ended; `reason` is human-readable.
     Disconnected { reason: String, end: SessionEnd },
-    /// An object entered range / was created: a unit, player, or GameObject at a raw-WoW pose. Carries
-    /// the interpreted spawn identity (`display_id`/`scale`, decoded per object type here so the app
-    /// needn't know the wire layout) plus the full descriptor `fields` mask the ECS seeds its per-object
-    /// store from (decision 0061).
+    /// A placed object entered view, its spawn identity decoded per object type.
     ObjectCreate {
         guid: u64,
         kind: EntityKind,
-        /// The model display id (`UNIT_FIELD_DISPLAYID` / `GAMEOBJECT_DISPLAYID`), interpreted per type;
-        /// `None` when absent/zero. Present raw in `fields` too, but decoded here (unit-vs-GameObject).
+        /// The type's own display-id field; `None` when absent or zero.
         display_id: Option<u32>,
         position: [f32; 3],
         orientation: f32,
-        /// `OBJECT_FIELD_SCALE_X` — the per-object size multiplier (see [`object_scale`]). `1.0` when
-        /// absent; for a GameObject this *is* its size (no DBC scale column in 5875).
+        /// `OBJECT_FIELD_SCALE_X`, the complete render scale; `1.0` when absent.
         scale: f32,
-        /// The unit's 6 movement speeds from its `LIVING` block; `None` for a GameObject. Seeds the
-        /// animation selector's walk-vs-run boundary (RF-0057) and the net bridge's remote-mover
-        /// extrapolation. (Movement-block data, not a descriptor field — hence not in `fields`.)
+        /// From the `LIVING` block, so not in `fields`; `None` for a GameObject.
         speeds: Option<MoveSpeeds>,
-        /// The **live mover state** this unit is already in as it streams into view — its
-        /// `MOVEMENTFLAGS` word and swim pitch ([`MoverState`]); `None` for a GameObject. The
-        /// reference applies both from the create block (byte-VERIFIED — wow-5875-re
-        /// `system/collision/scratch/create-block-swim-pitch.md`; the flags through the very same
-        /// `0x75a07dff` merge a relayed `MSG_MOVE_*` uses, the pitch through the shared pose commit
-        /// `0x7c6420`), and it does so *before* the model or its render callback exist — so a unit
-        /// that comes into view mid-motion is already in that motion on its first drawn frame. We
-        /// used to drop the whole word: a player who swam into view rendered level and untilted
-        /// until their next relay packet, and an idle floater — who sends none — stayed level for
-        /// as long as they floated.
+        /// Flags and swim pitch the unit streams in with, applied by the reference before its model
+        /// exists: the flags via the relay's `0x75a07dff` merge, the pitch via `0x7c6420`.
         mover: Option<MoverState>,
-        /// A transport GameObject's (`UPDATE_FLAG_TRANSPORT`) path-progress anchor — `Some` only for a
-        /// type-15/type-11 transport create (a boat/zeppelin/elevator). Decision 0438's cycle anchor:
-        /// `anchor = this value`, `t₀ = Instant::now()` on create/re-create; per frame `progress =
-        /// anchor + elapsed_ms`, position = `timetable(progress % period)`.
+        /// `UPDATE_FLAG_TRANSPORT`'s path progress in ms, only on a type-11/15 transport create;
+        /// progress is this plus elapsed ms; position is `timetable(progress % period)`.
         transport_progress: Option<u32>,
-        /// This object's own rider pose on a transport (`MOVEFLAG_ON_TRANSPORT` in its `LIVING` block) —
-        /// `Some` when a freshly-created unit/player is standing on a boat/zeppelin/elevator at create
-        /// time, local to that transport's frame (decision 0438).
+        /// Its rider pose, local to the transport, when created with `MOVEFLAG_ON_TRANSPORT`.
         transport: Option<TransportPose>,
-        /// The path this unit was **already walking** when it streamed into view
-        /// (`MOVEFLAG_SPLINE_ENABLED` in its `LIVING` block) — the same travel-order polyline as
-        /// [`Self::MonsterMove`], plus the milliseconds of it the server has already ridden, so the app
-        /// can join the walk mid-path. Dropping it is what froze every creature that happened to be in
-        /// motion at first sight, until its next `MonsterMove` teleported it forward (decision 0708).
+        /// The path it was already walking (`MOVEFLAG_SPLINE_ENABLED`), with the ms already ridden.
         spline: Option<CreateSpline>,
-        /// The object's full descriptor field set from the create mask — health/level/appearance/
-        /// customization and everything else. The ECS seeds its `ObjectStore` from this, then merges
-        /// later [`Self::ObjectValues`] deltas into it (decision 0061).
+        /// The full descriptor from the create mask; later [`Self::ObjectValues`] merge into it.
         fields: ObjectFields,
     },
-    /// An item or container entered our view: our own inventory streaming in at login, a looted drop,
-    /// a traded bag. A pure **descriptor** object — its create block carries no pose (wire-verified:
-    /// vmangos sends `UPDATEFLAG_ALL` + a constant, nothing spatial), so it never becomes a scene
-    /// entity. The app seeds its item store from `fields` and merges later [`Self::ObjectValues`] /
-    /// removes by guid, exactly like the scene store. Which *slot* holds the item is not here — that
-    /// lives in the owning player/bag descriptor (`PLAYER_FIELD_INV_SLOT`/`PACK_SLOT`,
-    /// `CONTAINER_FIELD_SLOT`) as this guid.
+    /// An item or container: a pose-less descriptor (vmangos sends `UPDATEFLAG_ALL` and a
+    /// constant); its slot is in the owner's `PLAYER_FIELD_*_SLOT` or `CONTAINER_FIELD_SLOT`.
     ItemCreate {
         guid: u64,
-        /// `true` for a container (a bag — its fields carry `CONTAINER_FIELD_SLOT_*` contents),
-        /// `false` for a plain item.
         container: bool,
-        /// The item's full descriptor set: `OBJECT_FIELD_ENTRY` (→ the template for name/icon via
-        /// `ITEM_QUERY_SINGLE`), stack count, durability, enchants; container slots when `container`.
+        /// The full descriptor; `OBJECT_FIELD_ENTRY` is the template for `CMSG_ITEM_QUERY_SINGLE`.
         fields: ObjectFields,
     },
-    /// An existing object moved to a new authoritative pose (supersedes any active path). From an
-    /// `SMSG_UPDATE_OBJECT` movement block — a one-off correction/relocation, not live locomotion.
+    /// An update-object movement block: a one-off authoritative pose that supersedes any path.
     ObjectMove {
         guid: u64,
         position: [f32; 3],
         orientation: f32,
     },
-    /// A relayed *player* movement packet (`MSG_MOVE_*`): the mover's authoritative pose plus its live
-    /// CMovement `moveFlags`. This is how another player's continuous walking/turning/strafing reaches
-    /// us (creatures move via [`Self::MonsterMove`] splines instead). The app snaps to `position` and
-    /// extrapolates from `flags` between packets so motion stays smooth at the ~2 Hz relay rate.
-    /// `fall_time` (ms airborne) + `jump` (the ballistic launch) are present while `JUMPING` is set, so
-    /// the app replays a jump as one arc instead of stair-stepping its height (decision 0053).
-    /// `transport` is `Some` while `MOVEFLAG_ON_TRANSPORT` is set: the mover's local pose on the named
-    /// transport, for an observed rider to re-anchor through that transport's live matrix (decision
-    /// 0438) rather than snap to `position` as a world coordinate.
+    /// A relayed player move (`MSG_MOVE_*`, about 2 Hz): `fall_time` is ms airborne, `jump` rides
+    /// with `JUMPING`, `transport` is deck-local with `MOVEFLAG_ON_TRANSPORT`.
     UnitMove {
         guid: u64,
         position: [f32; 3],
         orientation: f32,
         flags: u32,
-        /// The swim pitch (radians, +up) — the mover's 3D travel angle while `MOVEFLAG_SWIMMING`
-        /// is set (`0.0` otherwise): the wire tail exists so observers can integrate a swimmer's
-        /// vertical between packets (the client's swim velocity basis adds pitch, `0x7c5880`).
+        /// Swim pitch in radians, up positive, `0.0` unless `MOVEFLAG_SWIMMING`; the reference's
+        /// swim velocity basis includes it (`0x7c5880`).
         pitch: f32,
-        /// The `MovementInfo` time word — vmangos's own ms clock stamped at receipt (`stime`
-        /// = `WorldTimer::getMSTime()` in `MovementInfo::Read`, relayed verbatim by `Write`), one
-        /// coherent server clock across all movers. The reference schedules a remote's apply off the
-        /// *deltas* between consecutive stamps — replay paced by the sender's own cadence, wow-re
-        /// `remote-apply-timing.md`; the app mirrors that per unit (decisions 0601/0615).
+        /// vmangos's ms clock stamped at receipt (`MovementInfo::Read`), one clock for all movers;
+        /// the reference paces a remote's apply by the deltas between consecutive stamps.
         time: u32,
-        /// **What this packet's opcode means on top of the pose** — heartbeat, teleport, root, or
-        /// nothing at all ([`crate::messages::RelayVerb`], decision 2064). Twenty-three opcodes
-        /// share this one body and one client handler; three of them are more than narration, and
-        /// the enum is exactly those three.
+        /// What the opcode adds to the pose: a heartbeat, a teleport, a root, or nothing.
         verb: crate::messages::RelayVerb,
         fall_time: u32,
         jump: Option<JumpInfo>,
         transport: Option<TransportPose>,
     },
-    /// A descriptor `Values` update: the fields this packet changed (`UpdateFields`; WoW resends only
-    /// what changed, so a health-only hit carries just that), for the ECS to merge into the object's
-    /// store (decision 0061). Emitted from `Object::Values`; a create's *initial* fields ride on
-    /// [`Self::ObjectCreate`] instead. Never empty (the codec drops an empty delta).
+    /// A descriptor `Values` delta, only the changed fields; never empty (the codec drops those).
     ObjectValues { guid: u64, fields: ObjectFields },
-    /// Objects that left our view range (the update-object `OutOfRange` block). They still exist
-    /// server-side — the real client demotes them to a staging table for cheap re-create.
+    /// Left view range (`OutOfRange`); the reference keeps them in a staging table for re-create.
     ObjectsRemoved(Vec<u64>),
-    /// One object destroyed outright (`SMSG_DESTROY_OBJECT` — a corpse decaying ahead of respawn, a
-    /// despawn): it ceases to exist. The real client frees it on the spot — an **instant pop**, no
-    /// fade-out; the only lifecycle fade is the appear-fade on a fresh create (wow-re object-layer,
-    /// selection-death-clear RE). The corpse → destroy → fresh-create-on-respawn sequence is why a
-    /// respawn never stands the old corpse up.
+    /// `SMSG_DESTROY_OBJECT`: the reference frees it at once, no fade; a respawn is a fresh create.
     ObjectDestroyed(u64),
-    /// The server asked us to play a cinematic (`SMSG_TRIGGER_CINEMATIC`): a character's
-    /// first-ever login (the race intro) or a GameObject camera. The app must answer
-    /// `CMSG_COMPLETE_CINEMATIC` when it ends — or immediately, to skip — because vmangos anchors
-    /// object visibility to the flying cinematic camera while one runs unacked
-    /// (`Player::UpdateCinematic`): the world around the body despawns until the ack arrives.
+    /// `SMSG_TRIGGER_CINEMATIC`. Until `CMSG_COMPLETE_CINEMATIC` vmangos anchors visibility to the
+    /// cinematic camera (`Player::UpdateCinematic`), despawning the world around the body.
     CinematicTriggered { cinematic_id: u32 },
-    /// A server-dictated movement path: the unit traverses `path` — the full travel-order polyline
-    /// `[start, …waypoints…, endpoint]` — at constant (arc-length) speed over `duration_ms`. Every
-    /// waypoint is carried, so a curved patrol reads as its real path, not a straight `start → endpoint`
-    /// shortcut. A `Stop` / zero-duration / <2-point move clears the path (`path` empty).
-    /// `MSG_MOVE_TIME_SKIPPED` — an observed mover reported that its own client skipped `lag_ms`
-    /// of movement simulation. **Not a pose**: nothing about where the unit is has changed, only
-    /// how far its clock has run. The app advances that mover's relay-chain wire stamp by it, the
-    /// reference's `[CMovement+0xac] += lag` (`0x603b40` → `0x601560` → `0x61ab90`). Ignoring it
-    /// leaves our copy of the chain permanently short, so the mover's next real packet reads as a
-    /// step `lag` too large and is scheduled that much late. Decision 1935.
+    /// `MSG_MOVE_TIME_SKIPPED`: not a pose. The mover's relay stamp advances by `lag_ms`, as the
+    /// reference's `[CMovement+0xac] += lag` (`0x603b40`), or its next packet is scheduled late.
     MoveTimeSkipped { guid: u64, lag_ms: u32 },
+    /// A server path: `path` is the travel-order polyline from `start`, walked at constant speed
+    /// over `duration_ms`; a stop, a zero duration or fewer than two points leaves it empty.
     MonsterMove {
         guid: u64,
-        /// `SMSG_MONSTER_MOVE_TRANSPORT` only: the transport whose frame `start` and every `path`
-        /// point are expressed in — deck-local offsets, composed through the transport's live pose
-        /// rather than read as world coordinates. `None` = the ordinary absolute path. A packet
-        /// naming a transport is also the *attach* signal: the unit rides that deck from here
-        /// (decision 1936).
+        /// `SMSG_MONSTER_MOVE_TRANSPORT`: `start`/`path` are deck-local, and the unit now rides it.
         transport: Option<u64>,
         start: [f32; 3],
-        /// The server's per-move spline counter — echoed in `CMSG_MOVE_SPLINE_DONE` when this spline
-        /// drives our own player (Charge/knockback/taxi); ignored for a creature's walk.
+        /// Echoed in `CMSG_MOVE_SPLINE_DONE` when the spline drives our own player.
         spline_id: u32,
         path: Vec<[f32; 3]>,
-        /// The dictated final facing (`moveType` 2/3/4), applied as a snap. [`MonsterMoveFacing::None`]
-        /// for a plain move — the unit faces its travel direction along the path. This is how a
-        /// creature re-faces **without walking** (aggro/scripted/emote), the "won't turn to face me" fix.
+        /// The final facing (`moveType` 2/3/4), snapped; how a creature turns without walking.
         facing: MonsterMoveFacing,
         stop: bool,
         duration_ms: u32,
-        /// `true` ⇒ a 3-D flight path (keep the spline's Z); `false` ⇒ a ground walk whose Z the app
-        /// re-derives from the terrain under the unit (see the renderer's creature ground-clamp).
-        /// The re-derive is world-space and so does not apply to a `transport` path: there is no
-        /// terrain under a deck, and the wire Z is already the deck-local height (decision 1936).
+        /// Ground walks take Z from the terrain; flights and `transport` paths keep the wire Z.
         flying: bool,
-        /// `SPLINEFLAG_RUNMODE` — the path is travelled at run speed. Its **absence** forces
-        /// `MOVEFLAG_WALK_MODE` on for the unit the spline moves (decision 1758).
+        /// `SPLINEFLAG_RUNMODE`; its absence forces `MOVEFLAG_WALK_MODE` on the moved unit.
         run_mode: bool,
     },
-    /// Same-map teleport (`MSG_MOVE_TELEPORT_ACK`): the app snaps our player + echoes the ack.
+    /// Same-map teleport (`MSG_MOVE_TELEPORT_ACK`): the app snaps our player and echoes the ack.
     Teleport {
         guid: u64,
         counter: u32,
         position: [f32; 3],
         orientation: f32,
     },
-    /// Cross-map worldport (`SMSG_NEW_WORLD`, `needs_ack = true`) or the initial-login map
-    /// announcement (`SMSG_LOGIN_VERIFY_WORLD`, `needs_ack = false`): load the new map's ADTs.
-    /// While a pending transfer named a transport, `position`/`orientation` are **boat-local**
-    /// (decision 0455 — vmangos `SendNewWorld` sends `GetTransportPos()` when riding).
+    /// `SMSG_NEW_WORLD` (acked) or the login `SMSG_LOGIN_VERIFY_WORLD`. After a transfer that
+    /// named a transport the pose is boat-local (vmangos `SendNewWorld` sends `GetTransportPos()`).
     Worldport {
         map_id: u32,
         position: [f32; 3],
         orientation: f32,
         needs_ack: bool,
     },
-    /// The far-teleport preamble (`SMSG_TRANSFER_PENDING`): a worldport to `map_id` follows.
-    /// `transport_entry` is set iff the player rides that transport through the transfer — the
-    /// signal that the coming [`Self::Worldport`] carries boat-local coordinates (decision 0455).
+    /// `SMSG_TRANSFER_PENDING`: a worldport follows, boat-local when `transport_entry` is set.
     TransferPending {
         map_id: u32,
         transport_entry: Option<u32>,
     },
-    /// `SMSG_TRANSFER_ABORTED`: the announced transfer will not happen (map full, no instance);
-    /// clears the pending-transfer latch.
+    /// `SMSG_TRANSFER_ABORTED`: the announced transfer is off (map full, no instance).
     TransferAborted { reason: u8 },
     /// The server in-game clock (`SMSG_LOGIN_SETTIMESPEED`): drives time-of-day lighting.
     TimeSpeed {
         hours: u8,
         minutes: u8,
-        /// Monotonic day count (`year·372 + month·31 + day` of the packed server date) — the
-        /// celestial moon-phase precession input.
+        /// `year·372 + month·31 + day` of the packed server date; the moon phase's input.
         day_serial: u32,
         timescale: f32,
     },
-    /// The server's **wall clock** in unix-epoch seconds (`SMSG_QUERY_TIME_RESPONSE`, answering our
-    /// `CMSG_QUERY_TIME`) — not [`Self::TimeSpeed`]'s in-game day/night clock, a different quantity
-    /// with a different consumer. This one dates the absolute stamps the server writes into
-    /// descriptor fields: a timed quest's deadline is `time(nullptr) + limitTime`, so the quest
-    /// countdown is a subtraction against *this* number (decision 1150).
+    /// The server's wall clock in unix seconds (`SMSG_QUERY_TIME_RESPONSE`), the base of absolute
+    /// descriptor stamps: a timed quest's deadline is `time(nullptr) + limitTime`.
     ServerUnixTime { unix_time: u32 },
-    /// The player's hearthstone bind point (`SMSG_BINDPOINTUPDATE`): the AreaTable id the
-    /// `$z` token names ("Returns you to <area>.").
+    /// The hearthstone bind (`SMSG_BINDPOINTUPDATE`): the AreaTable id the `$z` token names.
     BindPoint { area: u32 },
-    /// The player's open GM ticket, or `None` for the ordinary "you have no ticket" answer
-    /// (`SMSG_GMTICKET_GETTICKET`; decision 1673). **Every one of these is an answer, including a
-    /// `None`** — the Help window re-polls every 10 minutes and must re-fire `UPDATE_TICKET` each
-    /// time even when nothing changed, so the consumer counts these rather than diffing them.
+    /// `SMSG_GMTICKET_GETTICKET`, `None` for no ticket. The Help window re-polls every 10 minutes
+    /// and fires `UPDATE_TICKET` on each answer, changed or not: count these, never diff them.
     GmTicket { ticket: Option<Box<GmTicket>> },
-    /// The answer to filing a ticket (`SMSG_GMTICKET_CREATE`): 2 = created, 3 = refused,
-    /// 1 = one already exists (vmangos never sends 1 and sometimes sends nothing at all).
+    /// `SMSG_GMTICKET_CREATE`: 2 created, 3 refused, 1 already exists (vmangos never sends 1, and
+    /// sometimes sends nothing at all).
     GmTicketCreated { response: u32 },
     /// The answer to editing a ticket (`SMSG_GMTICKET_UPDATETEXT`): 4 = saved, 5 = refused.
     GmTicketUpdated { response: u32 },
-    /// The answer to abandoning a ticket (`SMSG_GMTICKET_DELETETICKET`): 9 = deleted. Also arrives
-    /// unsolicited when a GM runs `.ticket delete`.
+    /// `SMSG_GMTICKET_DELETETICKET`: 9 = deleted; also unasked on a GM's `.ticket delete`.
     GmTicketDeleted { response: u32 },
-    /// Whether the petition queue is taking tickets (`SMSG_GMTICKETSYSTEMSTATUS`): 1 = yes.
-    /// Drives `UPDATE_GM_STATUS`, and through it the Help window's "page a GM" gate.
+    /// `SMSG_GMTICKETSYSTEMSTATUS`: 1 = the queue takes tickets; drives `UPDATE_GM_STATUS`.
     GmTicketSystemStatus { status: i32 },
-    /// A GM touched the ticket (`SMSG_GM_TICKET_STATUS_UPDATE`): 1 = updated, 2 = closed,
-    /// 3 = a survey is offered. vmangos never sends it; cmangos makes it the notification model.
+    /// `SMSG_GM_TICKET_STATUS_UPDATE`: 1 updated, 2 closed, 3 survey; vmangos never sends it.
     GmTicketStatusUpdate { status: u32 },
-    /// An innkeeper is asking whether to make this your home (`SMSG_BINDER_CONFIRM`) — the
-    /// question the `CONFIRM_BINDER` dialog puts on screen. `binder` is the innkeeper's guid, and
-    /// it must be echoed in `CMSG_BINDER_ACTIVATE` for the bind to happen at all (decision 1331).
+    /// `SMSG_BINDER_CONFIRM`, the `CONFIRM_BINDER` dialog; echo `binder` in `CMSG_BINDER_ACTIVATE`.
     BinderConfirm { binder: u64 },
-    /// Someone is asking to summon us (`SMSG_SUMMON_REQUEST`) — the question the `CONFIRM_SUMMON`
-    /// dialog puts on screen (decision 1747). `summoner` is the guid to echo in
-    /// `CMSG_SUMMON_RESPONSE` and the one the dialog names; `zone` is the **summoner's**
-    /// `AreaTable` id, the place the dialog says you would be pulled to; `delay_ms` is how long
-    /// the server will hold the offer before auto-declining it. Accepting is the only packet in
-    /// the flow — declining sends nothing (there is no decline opcode).
+    /// `SMSG_SUMMON_REQUEST`: `zone` is the summoner's AreaTable id, `delay_ms` the auto-decline
+    /// hold. Accepting sends `CMSG_SUMMON_RESPONSE`; there is no decline opcode.
     SummonRequest {
         summoner: u64,
         zone: u32,
         delay_ms: u32,
     },
-    /// A class trainer is asking whether to unlearn every talent (`MSG_TALENT_WIPE_CONFIRM`,
-    /// inbound) — the question the `CONFIRM_TALENT_WIPE` dialog puts on screen, carrying the
-    /// `trainer` to answer with and the `cost` in copper its money frame shows. Answering means
-    /// sending the SAME opcode back with the guid; declining sends nothing (decision 1580).
+    /// `MSG_TALENT_WIPE_CONFIRM`, `cost` in copper; accepting echoes it, declining sends nothing.
     TalentWipeConfirm { trainer: u64, cost: u32 },
-    /// A pet trainer is asking whether to unlearn the pet's skills (`SMSG_PET_UNLEARN_CONFIRM`) —
-    /// the `CONFIRM_PET_UNLEARN(cost)` dialog's question, the talent-wipe twin for a pet
-    /// (decision 1963). Answering sends `CMSG_PET_UNLEARN` with the guid; declining sends nothing.
+    /// `SMSG_PET_UNLEARN_CONFIRM`: accept with `CMSG_PET_UNLEARN`; declining sends nothing.
     PetUnlearnConfirm { trainer: u64, cost: u32 },
     /// The instance-boot clock (`SMSG_RAID_GROUP_ONLY`): a positive delay arms it
-    /// (`INSTANCE_BOOT_START`), zero clears it (`INSTANCE_BOOT_STOP`) and names `reason` 1/2 on
-    /// screen (decision 1963).
+    /// (`INSTANCE_BOOT_START`), zero clears it (`INSTANCE_BOOT_STOP`) and shows `reason` 1 or 2.
     RaidGroupOnly { delay_ms: u32, reason: u32 },
-    /// A battleground spirit healer's next resurrection wave (`SMSG_AREA_SPIRIT_HEALER_TIME`):
-    /// arms `GetAreaSpiritHealerTime` and fires `AREA_SPIRIT_HEALER_IN_RANGE` for the cached
-    /// healer (decision 1963).
+    /// A spirit healer's next resurrection wave (`SMSG_AREA_SPIRIT_HEALER_TIME`): arms
+    /// `GetAreaSpiritHealerTime` and fires `AREA_SPIRIT_HEALER_IN_RANGE`.
     AreaSpiritHealerTime { healer: u64, ms: u32 },
-    /// One battleground queue slot's state (`SMSG_BATTLEFIELD_STATUS`), the client's three-slot
-    /// queue that `AcceptBattlefieldPort` answers out of (decision 1963).
+    /// One of the client's three battleground queue slots (`SMSG_BATTLEFIELD_STATUS`).
     BattlefieldStatus(crate::messages::BattlefieldStatus),
-    /// The battleground scoreboard (`MSG_PVP_LOG_DATA`), rows in wire order — the app resolves
-    /// the names, derives each row's team and pushes the sorted board (decision 1972).
+    /// The battleground scoreboard (`MSG_PVP_LOG_DATA`), rows in wire order, unsorted.
     PvpLogData(crate::messages::PvpLogData),
-    /// The battleground instance list (`SMSG_BATTLEFIELD_LIST`): the battlemaster, the map, the
-    /// bracket and the instance ids — fires `BATTLEFIELDS_SHOW` (decision 1974).
+    /// The battleground instance list (`SMSG_BATTLEFIELD_LIST`); fires `BATTLEFIELDS_SHOW`.
     BattlefieldList(crate::messages::BattlefieldList),
-    /// The battleground teammates' positions and the flag carrier
-    /// (`MSG_BATTLEGROUND_PLAYER_POSITIONS`), raw world floats (decision 1980).
+    /// Teammate and flag-carrier positions (`MSG_BATTLEGROUND_PLAYER_POSITIONS`), raw WoW.
     BattlefieldPositions(crate::messages::BattlefieldPositions),
-    /// `MSG_TABARDVENDOR_ACTIVATE` — the vendor whose designer opens (decision 1977).
+    /// `MSG_TABARDVENDOR_ACTIVATE`: the vendor whose tabard designer opens.
     TabardVendorActivate(u64),
-    /// `MSG_SAVE_GUILD_EMBLEM` — the save's result row (decision 1977).
+    /// `MSG_SAVE_GUILD_EMBLEM`: the save's result row.
     SaveGuildEmblemResult(u32),
-    /// A group join's verdict (`SMSG_GROUP_JOINED_BATTLEGROUND`): `0xFFFFFFFE` deserters, a map id
-    /// joined, anything else the generic failure — three message lines, no state (decision 1974).
+    /// `SMSG_GROUP_JOINED_BATTLEGROUND`: `0xFFFFFFFE` deserters, a map id joined, else the
+    /// generic failure; a message line each, no state.
     GroupJoinedBattleground { result: u32 },
-    /// A player joined or left the battleground (`SMSG_BATTLEGROUND_PLAYER_JOINED` / `_LEFT`):
-    /// printed once the name cache resolves the guid (decision 1974).
+    /// `SMSG_BATTLEGROUND_PLAYER_JOINED`/`_LEFT`, printed once the name cache has the guid.
     BattlegroundPlayer { guid: u64, joined: bool },
-    /// The meeting-stone queue state (`SMSG 0x295`): the area queued for and a status byte
-    /// (decision 1963).
+    /// The meeting-stone queue state (`SMSG 0x295`): the area queued for and a status byte.
     MeetingStoneSetQueue { area: u32, status: u8 },
-    /// One of the meeting stone's four display-only replies (`0x297/0x298/0x299/0x2BB`): a chat
-    /// line each, no state, no event (decision 1974).
+    /// One of the meeting stone's four chat-line-only replies (`0x297/0x298/0x299/0x2BB`).
     MeetingStoneNotice(crate::messages::MeetingStoneNotice),
-    /// The account's tutorial bank (`SMSG_TUTORIAL_FLAGS`): the raw bytes, both of the client's
-    /// banks copied from them (decision 1976).
+    /// The tutorial bank bytes (`SMSG_TUTORIAL_FLAGS`); the client copies both its banks from them.
     TutorialFlags(Vec<u8>),
-    /// The bind took (`SMSG_PLAYERBOUND`): `area` is the AreaTable id we are now bound in, the
-    /// same one [`Self::BindPoint`] carries in the packet beside it.
+    /// The bind took (`SMSG_PLAYERBOUND`); `area` matches the [`Self::BindPoint`] sent beside it.
     PlayerBound { binder: u64, area: u32 },
-    /// The player's equip proficiencies for one item class (`SMSG_SET_PROFICIENCY`, at login +
-    /// on train): the subclass bitmask the item tooltip's slot-line red compares against
-    /// (the client's `0xc4d4a0[class]` store).
+    /// One item class's subclass mask (`SMSG_SET_PROFICIENCY`), the reference's `0xc4d4a0[class]`.
     Proficiency { item_class: u32, subclass_mask: u32 },
-    /// The player's reputation store (`SMSG_INITIALIZE_FACTIONS`, once at login): `(flags, standing)`
-    /// per reputation-list slot, indexed by `Faction.dbc`'s `reputationIndex`. The standing excludes
-    /// the DBC race/class base — consumers add it before ranking. Drives the reputation branch of
-    /// unit reaction (a reputation faction's NPCs colour by the player's rank, not faction templates).
+    /// `SMSG_INITIALIZE_FACTIONS` at login: `(flags, standing)` per `Faction.dbc`
+    /// `reputationIndex`. The standing excludes the DBC race/class base; add it before ranking.
     Reputations { standings: Vec<(u8, i32)> },
-    /// Mid-session reputation deltas (`SMSG_SET_FACTION_STANDING`): `(reputationListId,
-    /// standing)` per changed slot — same standing convention as [`Self::Reputations`].
+    /// `SMSG_SET_FACTION_STANDING`: `(reputationListId, standing)` per slot, base excluded.
     ReputationDelta { standings: Vec<(u32, i32)> },
-    /// One reputation-list slot just became visible in the pane (`SMSG_SET_FACTION_VISIBLE`) — the
-    /// server's "you have now met these people". Carries no standing; it only lifts the slot's
-    /// visible flag, which is what decides whether the pane lists the row at all.
+    /// `SMSG_SET_FACTION_VISIBLE`: sets the slot's visible flag, which decides if it is listed.
     ReputationVisible { list_id: u32 },
-    /// A player character's identity (`SMSG_NAME_QUERY_RESPONSE`, answering our `CMSG_NAME_QUERY`).
-    /// Unit names are **not** descriptor fields on the 1.12 wire — they arrive only through this
-    /// query pair (players) and [`Self::CreatureName`] (creatures); the app caches them by guid/entry
-    /// (decision 0068 §3's query-cache seam). An unknown guid answers with an empty `name`.
+    /// `SMSG_NAME_QUERY_RESPONSE`: names are never descriptor fields in 1.12, only query answers.
+    /// An unknown guid answers with an empty `name`.
     PlayerName {
         guid: u64,
         name: String,
@@ -582,47 +361,32 @@ pub enum SessionEvent {
         gender: u32,
         class: u32,
     },
-    /// A pet's display name (`SMSG_PET_NAME_QUERY_RESPONSE`), keyed by **pet number** — the third
-    /// naming path, alongside [`Self::PlayerName`] and [`Self::CreatureName`], and the only one a
-    /// pet can use: its guid carries a pet number where a creature carries its template entry
-    /// ([`crate::guid::pet_number`]), so a creature query for it can only miss. The name is the
-    /// pet's own — a hunter pet's custom name, or the creature name for anything summoned. There is
-    /// no miss shape: the server stays silent when the pet is gone or the number disagrees.
+    /// `SMSG_PET_NAME_QUERY_RESPONSE`, keyed by the pet number its guid carries in place of an
+    /// entry ([`crate::guid::pet_number`]). There is no miss reply: the server stays silent.
     PetName { pet_number: u32, name: String },
-    /// A creature template's display name (`SMSG_CREATURE_QUERY_RESPONSE`). Keyed by template
-    /// `entry` (shared by every spawn of that template), not by spawn guid. `name` is `None` when
-    /// the server flagged the entry unknown; `subname` is the tooltip line ("Stable Master", …).
+    /// `SMSG_CREATURE_QUERY_RESPONSE`, keyed by template `entry`. An unknown entry has a `None`
+    /// `name`, and every other field then reads `None`, `0` or `false`.
     CreatureName {
         entry: u32,
         name: Option<String>,
         subname: Option<String>,
-        /// The template's `CreatureType.dbc` id (Beast, Humanoid, Critter, …) — the TAB-target
-        /// critter/totem filter's input. `None` on a server miss.
+        /// `CreatureType.dbc` id; the TAB-target critter/totem filter reads it.
         creature_type: Option<u32>,
-        /// The template's `CreatureFamily.dbc` id (Wolf, Cat, Imp, …) — `UnitCreatureFamily`'s
-        /// word and, through that row's pet-food mask, the diet tooltip (decision 1062). `0` for
-        /// everything that is neither a tameable beast nor a warlock minion, and `0` on a miss.
+        /// `CreatureFamily.dbc` id for `UnitCreatureFamily` and the diet tooltip; `0` is none.
         pet_family: u32,
-        /// Elite rank 0..4 (the unit tooltip's rank word, decision 0276). `0` on a miss.
+        /// Elite rank 0..4, the unit tooltip's rank word.
         rank: u32,
-        /// The template type flags — bit `0x10` hides the tooltip's faction-name line. `0` on a miss.
+        /// Bit `0x10` hides the tooltip's faction-name line.
         type_flags: u32,
-        /// The template's model (`CreatureDisplayInfo.dbc` id) — 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). `0` when the template ships none, and `0` on a miss.
+        /// `CreatureDisplayInfo.dbc` id, to draw a creature with no world object (a stabled pet).
         display_id: u32,
-        /// The civilian flag (the tooltip's green CIVILIAN line). `false` on a miss.
+        /// The tooltip's green CIVILIAN line.
         civilian: bool,
-        /// The racial-leader flag (the tooltip's white LEADER line). `false` on a miss.
+        /// The tooltip's white LEADER line.
         racial_leader: bool,
     },
-    /// A GameObject template's type/display/name/`data[24]` head (`SMSG_GAMEOBJECT_QUERY_RESPONSE`,
-    /// answering our `CMSG_GAMEOBJECT_QUERY`) — the ask-once GO template lookup, decision 0236.
-    /// Keyed by template `entry` (shared by every spawn of that template), not spawn guid. `data[24]`
-    /// is the type-specific raw tail (e.g. a chest's lockId lives at a type-specific slot); resolving
-    /// a slot is a later consumer's job. On a server miss (unknown entry) this still fires, with
-    /// `type_id`/`display_id` zeroed, `name` empty, and `data` all zero — the flattened-field twin of
-    /// how [`Self::CreatureName`] answers a miss with `None`s.
+    /// `SMSG_GAMEOBJECT_QUERY_RESPONSE`, keyed by template `entry`; `data` is the type-specific
+    /// raw tail. An unknown entry still fires, every field zero or empty.
     GameObjectInfo {
         entry: u32,
         type_id: u32,
@@ -630,137 +394,100 @@ pub enum SessionEvent {
         name: String,
         data: [i32; 24],
     },
-    /// A GameObject plays a one-shot **Custom** animation (`SMSG_GAMEOBJECT_CUSTOM_ANIM`):
-    /// the client arms GO substate `8 + anim_id` — AnimationData ids 153..156 (Custom0..3),
-    /// `anim_id >= 4` rejected at the consumer (wow-re `gameobject-anim-arm.md` §step 8).
-    /// The load-bearing sender is the fishing bobber's bite (`anim_id 0`, the splash;
-    /// decision 1086).
+    /// `SMSG_GAMEOBJECT_CUSTOM_ANIM`: the reference arms substate `8 + anim_id`, AnimationData
+    /// 153..156 (Custom0..3), and rejects `anim_id >= 4`. A fishing bobber's bite sends 0.
     GameObjectCustomAnim { guid: u64, anim_id: u32 },
-    /// An object plays its one-shot **Despawn** animation, then goes away
-    /// (`SMSG_GAMEOBJECT_DESPAWN_ANIM`): the client arms substate 12 — AnimationData **157
-    /// Despawn** — and holds the object alive across the `SMSG_DESTROY_OBJECT` that follows in
-    /// the same server tick, for the length of that play (decision 1404). UBRS's Rookery Eggs
-    /// hatch on this packet; a totem's death and a DynamicObject's expiry send it too, and those
-    /// carry nothing armable, so the consumer falls back to the ordinary instant destroy.
+    /// `SMSG_GAMEOBJECT_DESPAWN_ANIM`: the reference arms substate 12 (AnimationData 157 Despawn)
+    /// and keeps the object alive through the same-tick `SMSG_DESTROY_OBJECT` while it plays.
     GameObjectDespawnAnim { guid: u64 },
-    /// The fishing channel ended with nothing hooked (`SMSG_FISH_NOT_HOOKED`, empty body):
-    /// the red `ERR_FISH_NOT_HOOKED` toast (decision 1086).
+    /// `SMSG_OPEN_CONTAINER`: the reference fires `BAG_OPEN` with 0 for our own guid (the
+    /// backpack), 1..10 for a bag-cache slot, and nothing for a miss.
+    OpenContainer { item: u64 },
+    /// Our own stand state (`SMSG_STANDSTATE_UPDATE`), applied ungated through the setter a
+    /// volunteered change uses (reference: `0x603e50` → `0x6127b0`).
+    StandStateUpdate { state: u8 },
+    /// Nothing hooked (`SMSG_FISH_NOT_HOOKED`, empty body): the red `ERR_FISH_NOT_HOOKED` line.
     FishNotHooked,
-    /// The hooked fish got away — the fishing-skill roll failed on the bobber click
-    /// (`SMSG_FISH_ESCAPED`, empty body): the red `ERR_FISH_ESCAPED` toast (decision 1086).
+    /// The fish got away on the bobber click (`SMSG_FISH_ESCAPED`, empty body): `ERR_FISH_ESCAPED`.
     FishEscaped,
     /// A server-pushed 2D sound kit (`SMSG_PLAY_SOUND`): BG events, quest/zone scripts.
     PlaySound { sound_id: u32 },
     /// A server-pushed music kit for the music channel (`SMSG_PLAY_MUSIC`).
     PlayMusic { music_id: u32 },
-    /// A server-pushed 3D sound kit at a source object (`SMSG_PLAY_OBJECT_SOUND`) — e.g. the
-    /// fishing-bobber splash. The guid positions the emitter.
+    /// A server-pushed 3D sound kit at object `guid` (`SMSG_PLAY_OBJECT_SOUND`).
     PlayObjectSound { sound_id: u32, guid: u64 },
-    /// The zone's weather state (`SMSG_WEATHER`): `sound_id` is a SoundEntries loop kit
-    /// (8533..8558 rain/snow/sandstorm, 0 = clear); `weather_type`/`grade`/`instant` also feed
-    /// the weather visuals when they exist.
+    /// The zone's weather (`SMSG_WEATHER`); `sound_id` is a SoundEntries loop, 8533..8558, 0 clear.
     Weather {
         weather_type: u32,
         grade: f32,
         sound_id: u32,
         instant: bool,
     },
-    /// A nearby unit's chat emote (`SMSG_TEXT_EMOTE`): the `EmotesText.dbc` id; the guid names
-    /// the performer (voice race/sex resolve from its descriptor). `target_name` is the wire's
-    /// target display name, empty when untargeted — the sentence-form selector, decision 1274.
+    /// A chat emote (`SMSG_TEXT_EMOTE`, `EmotesText.dbc`); empty `target_name` means untargeted.
     TextEmote {
         guid: u64,
         text_emote: u32,
         target_name: String,
     },
-    /// A unit's anim emote (`SMSG_EMOTE`): the `Emotes.dbc` id (drives the anim + its
-    /// `EventSoundID`).
+    /// A unit's anim emote (`SMSG_EMOTE`): an `Emotes.dbc` id, its anim and its `EventSoundID`.
     Emote { guid: u64, emote_id: u32 },
-    /// The player's spell book (`SMSG_INITIAL_SPELLS`, once at login): the known spell ids,
-    /// widened from the wire's `u16`s, plus the active-cooldown list (the seed of the
-    /// cooldown store — decision 0137 phase 4).
+    /// The spell book at login (`SMSG_INITIAL_SPELLS`), ids widened from `u16`, and live cooldowns.
     SpellBook {
         spell_ids: Vec<u32>,
         cooldowns: Vec<crate::messages::SpellCooldown>,
     },
-    /// The player's saved action bar (`SMSG_ACTION_BUTTONS`, once at login): the occupied slots
-    /// (0..119; 0–11 = the main bar). Feeds the FrameXML action bar (decision 0068 slice 1).
+    /// The saved action bar at login (`SMSG_ACTION_BUTTONS`): slots 0..119, 0..11 the main bar.
     ActionButtons { buttons: Vec<ActionButton> },
-    /// A spell added to the book after login (`SMSG_LEARNED_SPELL`): trainer/quest/level-up, widened
-    /// from the wire `u16`. The first post-login spell-book mutation (decision 0237).
+    /// A spell learned after login (`SMSG_LEARNED_SPELL`), widened from the wire `u16`.
     SpellLearned { spell_id: u32 },
-    /// A spell taken back out of the book (`SMSG_REMOVED_SPELL`), widened from the wire `u16`:
-    /// a talent wipe, an abandoned profession, a GM `.unlearn`. Every rank of every talent arrives
-    /// as one of these after a respec, and until decision 1584 none of them did.
+    /// A spell unlearned (`SMSG_REMOVED_SPELL`), widened from `u16`; a respec sends one per rank.
     SpellRemoved { spell_id: u32 },
-    /// A rank-up (`SMSG_SUPERCEDED_SPELL`): the new rank replaces the old in the book and on the
-    /// action bar. Both ids widened from the wire `u16`.
+    /// A rank-up (`SMSG_SUPERCEDED_SPELL`) in book and bar; both ids widened from `u16`.
     SpellSuperceded {
         old_spell_id: u32,
         new_spell_id: u32,
     },
-    /// The server's verdict on our cast (`SMSG_CAST_RESULT`): `reason` is the failure code when
-    /// `success` is false (the client's error-text table keys on it), and `arg` the reason-specific
-    /// argument word that fills that message's `%s` — a `SpellFocusObject.dbc` id for
-    /// `REQUIRES_SPELL_FOCUS`, an `AreaTable.dbc` id for `REQUIRES_AREA`
-    /// ([`crate::messages::CastOutcome::Failed`]).
+    /// Our cast's verdict (`SMSG_CAST_RESULT`); `arg` fills its `%s`: a `SpellFocusObject.dbc` id
+    /// for `REQUIRES_SPELL_FOCUS`, an `AreaTable.dbc` id for `REQUIRES_AREA`.
     CastResult {
         spell_id: u32,
         success: bool,
         reason: Option<u8>,
         arg: Option<u32>,
     },
-    /// The pet action bar's whole state (`SMSG_PET_SPELLS`, decision 0982) — or its **teardown**,
-    /// which is the same event carrying a zero `pet_guid`. Server-authoritative: this is not a
-    /// delta, it is the bar, and every visible pet-bar change arrives through it.
+    /// The whole pet bar (`SMSG_PET_SPELLS`), never a delta; a zero `pet_guid` tears it down.
     PetSpells(Box<PetSpells>),
-    /// The pet's react/command state alone (`SMSG_PET_MODE`) — a state change with no bar edit
-    /// behind it (the reaction buttons' usual wire).
+    /// The pet's react/command state alone (`SMSG_PET_MODE`), with no bar edit.
     PetMode(PetMode),
     /// A refused pet order (`SMSG_PET_ACTION_FEEDBACK`): one reason code for the red error line.
     PetActionFeedback { reason: u8 },
-    /// The pet's cast refusal (`SMSG_PET_CAST_FAILED`) — [`Self::CastResult`]'s vocabulary, but
-    /// the caster is the pet, so it never touches OUR cast state.
+    /// The pet's cast refusal (`SMSG_PET_CAST_FAILED`); it never touches our own cast state.
     PetCastFailed { spell_id: u32, reason: Option<u8> },
-    /// A refused tame / Call Pet / Revive Pet (`SMSG_PET_TAME_FAILURE`): one
-    /// `PetTameFailureReason` byte, whose text is a `PETTAME_*` GlobalStrings key filling
-    /// `ERR_TAME_FAILED`.
+    /// A refused tame, Call Pet or Revive Pet (`SMSG_PET_TAME_FAILURE`): the reason's
+    /// `PETTAME_*` string fills `ERR_TAME_FAILED`.
     PetTameFailure { reason: u8 },
-    /// A refused pet rename (`SMSG_PET_NAME_INVALID`) — no payload; the reference raises
-    /// `ERR_INVALID_PETNAME` on the strength of the opcode alone.
+    /// A refused pet rename (`SMSG_PET_NAME_INVALID`, empty body): `ERR_INVALID_PETNAME`.
     PetNameInvalid,
-    /// The pet's loyalty hit zero and it ran away (`SMSG_PET_BROKEN`) — no payload;
-    /// `ERR_PET_BROKEN`.
+    /// The pet ran away at zero loyalty (`SMSG_PET_BROKEN`, empty body): `ERR_PET_BROKEN`.
     PetBroken,
-    /// The pet's voice (`SMSG_PET_ACTION_SOUND`) — one of two talk selectors on a named unit,
-    /// resolved against that unit's own `CreatureSoundData` row.
+    /// The pet's voice (`SMSG_PET_ACTION_SOUND`): a talk selector into its `CreatureSoundData` row.
     PetActionSound { pet_guid: u64, talk: u32 },
-    /// A dismissed pet's parting sound (`SMSG_PET_DISMISS_SOUND`) — a `CreatureModelData` id and
-    /// the raw WoW point to play its column-29 kit at. No guid, because the pet has gone.
+    /// A dismissed pet's sound (`SMSG_PET_DISMISS_SOUND`): the `CreatureModelData` column-29 kit.
     PetDismissSound { model_id: u32, position: [f32; 3] },
-    /// An item template's display head (`SMSG_ITEM_QUERY_SINGLE_RESPONSE`, answering our
-    /// `CMSG_ITEM_QUERY_SINGLE`). Keyed by template entry; `None` = the server doesn't know it
-    /// (undiscovered) — cached negative, like an unknown creature entry. Boxed for the same reason
-    /// as [`crate::messages::ServerPacket::ItemQueryResponse`]: the full item template is wide, and
-    /// this is one variant among many tiny, hot ones.
+    /// `SMSG_ITEM_QUERY_SINGLE_RESPONSE`, by entry; `None` is unknown. Boxed, being wide.
     ItemTemplate {
         entry: u32,
         info: Option<Box<ItemInfo>>,
     },
-    /// One inbound chat line (`SMSG_MESSAGECHAT`) — say/yell/system/NPC/channel. System lines
-    /// (type `0x0A`) carry GM command feedback. Carries the sender's `chat_tag` (AFK/DND/GM) for
-    /// the `<AFK>`/`<DND>`/`<GM>` name-prefix the real chat frame renders.
+    /// One chat line (`SMSG_MESSAGECHAT`); system lines (type `0x0A`) carry GM command feedback.
     Chat(crate::messages::ChatMessage),
-    /// A channel join/leave/error/moderation notice (`SMSG_CHANNEL_NOTIFY`) — `tail` is the payload
-    /// selected by `notice` (see [`ChannelNoticeTail`]).
+    /// A channel notice (`SMSG_CHANNEL_NOTIFY`); `notice` selects the `tail` payload.
     ChannelNotify {
         notice: u8,
         channel: String,
         tail: ChannelNoticeTail,
     },
-    /// A channel's member roster (`SMSG_CHANNEL_LIST`, answering our `CMSG_CHANNEL_LIST`): `(guid,
-    /// memberFlags)` per row (owner/moderator/voiced/muted/custom/mic-muted — vmangos
-    /// `Chat/Channel.h:119-130`).
+    /// A channel roster (`SMSG_CHANNEL_LIST`), member flags per vmangos `Chat/Channel.h:119-130`.
     ChannelList {
         channel: String,
         flags: u8,
@@ -770,89 +497,62 @@ pub enum SessionEvent {
     ChatPlayerNotFound { name: String },
     /// A cross-faction whisper was refused (`SMSG_CHAT_WRONG_FACTION`); empty body.
     ChatWrongFaction,
-    /// A server notice (`SMSG_NOTIFICATION`) — pre-formatted text the real client flashes in the
-    /// red UIErrorsFrame ("You do not know that language", trade refusals, and kin).
+    /// A server notice (`SMSG_NOTIFICATION`) the reference flashes in UIErrorsFrame.
     Notification { text: String },
-    /// An area trigger refused (`SMSG_AREA_TRIGGER_MESSAGE`) — pre-formatted text explaining why a
-    /// portal or instance entrance did nothing ("You must be at least level 58 to enter…", "You
-    /// cannot enter … while in ghost form."). The reference sends it to the same system-message
-    /// sink as [`Self::Notification`].
+    /// Why an area trigger refused (`SMSG_AREA_TRIGGER_MESSAGE`), shown as a notification.
     AreaTriggerMessage { text: String },
-    /// A shutdown/restart countdown or an operator broadcast (`SMSG_SERVER_MESSAGE`): the
-    /// `ServerMessages.dbc` row id and the text that fills its `%s`. The reference resolves the row
-    /// itself and shows the formatted line as `CHAT_MSG_SYSTEM`.
+    /// A shutdown countdown or a broadcast (`SMSG_SERVER_MESSAGE`): a `ServerMessages.dbc` row
+    /// and its `%s`, shown as `CHAT_MSG_SYSTEM`.
     ServerMessage { message_type: u32, text: String },
-    /// An area is under attack by enemy players (`SMSG_ZONE_UNDER_ATTACK`): one `AreaTable.dbc`
-    /// id. Becomes a `CHAT_MSG_CHANNEL` line on the joined **defense** channels, not a system line.
+    /// `SMSG_ZONE_UNDER_ATTACK`: an `AreaTable.dbc` id, shown on the joined defense channels.
     ZoneUnderAttack { area_id: u32 },
-    /// A world-defense broadcast (`SMSG_DEFENSE_MESSAGE` — the EPL tower captures): the zone it is
-    /// about, and the server-composed text. [`Self::ZoneUnderAttack`]'s destination exactly.
+    /// A defense broadcast (`SMSG_DEFENSE_MESSAGE`), shown where [`Self::ZoneUnderAttack`] is.
     DefenseMessage { zone_id: u32, text: String },
-    /// A trial account hit its whisper cap (`SMSG_CHAT_RESTRICTED`); empty body. The reference
-    /// answers it with `DisplayError(0x1c3)` and reads nothing off the wire.
+    /// A trial account's whisper cap (`SMSG_CHAT_RESTRICTED`, empty body): `DisplayError(0x1c3)`.
     ChatRestricted,
-    /// Answers `/played` (`SMSG_PLAYED_TIME`, our `CMSG_PLAYED_TIME`): total played time + time
-    /// since the last level-up, both in seconds.
+    /// `/played` (`SMSG_PLAYED_TIME`): total and this-level played time, in seconds.
     PlayedTime { total: u32, level: u32 },
-    /// The server's `/random` broadcast (`MSG_RANDOM_ROLL`): the rolled range, the result, and the
-    /// roller's guid.
+    /// A `/random` broadcast (`MSG_RANDOM_ROLL`).
     RandomRoll {
         min: u32,
         max: u32,
         roll: u32,
         guid: u64,
     },
-    /// The server refused an inventory operation (`SMSG_INVENTORY_CHANGE_FAILURE` — equip level,
-    /// proficiency, bag full, …): the UI error line's inventory vocabulary, the equip twin of
-    /// [`Self::CastResult`]'s failure path. `required_level` rides only on the level refusal.
+    /// A refused inventory operation (`SMSG_INVENTORY_CHANGE_FAILURE`), never `EQUIP_ERR_OK`.
     InventoryFailure {
         reason: u8,
         required_level: Option<u32>,
         item_guid: u64,
-        /// The destination bag's ABSOLUTE player slot — the `%s` source of reason 16's
-        /// "Only Arrows can be placed in that."; 255 = the player's own array (no bag to name).
+        /// The destination bag's absolute player slot, reason 16's `%s`; 255 is the player's own.
         bag_slot: u8,
     },
-    /// A unit began melee auto-attack (`SMSG_ATTACKSTART` — including the echo of our own
-    /// `CMSG_ATTACKSWING`).
+    /// A unit began melee auto-attack (`SMSG_ATTACKSTART`), our own included.
     AttackStart { attacker: u64, victim: u64 },
     /// A unit stopped melee auto-attack (`SMSG_ATTACKSTOP`).
     AttackStop { attacker: u64, victim: u64 },
-    /// One completed melee swing (`SMSG_ATTACKERSTATEUPDATE`) — the attacker's swing-animation
-    /// trigger (decision 0073: one packet = one swing, no client timer).
+    /// One melee swing (`SMSG_ATTACKERSTATEUPDATE`): one packet is one swing, no client timer.
     AttackerState(AttackerState),
-    /// The server refused our melee swing — `SMSG_ATTACKSWING_NOTINRANGE`/`_BADFACING`/
-    /// `_DEADTARGET`/`_CANT_ATTACK`, in the three arms the reference wires
-    /// ([`crate::messages::AttackSwingError`]). Self-only: the server sends these to the swinging
-    /// player alone.
+    /// Our melee swing was refused (`SMSG_ATTACKSWING_*`); sent to the swinger alone.
     AttackSwingError(AttackSwingError),
-    /// The server forced our attack to stop (`SMSG_CANCEL_COMBAT`) — the swing family's fourth
-    /// arm, whose handler is arm 4's body verbatim: StopAttack, no message.
+    /// The server stopped our attack (`SMSG_CANCEL_COMBAT`): the reference stops, no message.
     CancelCombat,
-    /// The target resisted our Feign Death (`SMSG_FEIGN_DEATH_RESISTED`) — one red line,
-    /// `ERR_FEIGN_DEATH_RESISTED` ("Resisted"), with no state behind it.
+    /// Feign Death resisted (`SMSG_FEIGN_DEATH_RESISTED`): one red line, no state.
     FeignDeathResisted,
-    /// A creature flared at someone (`SMSG_AI_REACTION`): reaction 2 = HOSTILE (sent on every
-    /// creature melee-attack start), 0 = ALERT (stealth pre-aggro detection); any other value is
-    /// a no-op. Pure audio in the client — the aggro/alert vocals (decision 0280).
+    /// `SMSG_AI_REACTION`: 2 hostile (each creature melee start), 0 alert (stealth detection),
+    /// anything else a no-op; the reference only plays the vocal.
     AiReaction { unit: u64, reaction: u32 },
-    /// A unit began a non-triggered cast (`SMSG_SPELL_START`), instants included (`cast_time_ms ==
-    /// 0`) — the precast trigger the phase-2 casting animation loop builds on (decision 0099 phase
-    /// 1). `target` is the explicit unit target, when the spell's target block carries one.
+    /// A non-triggered cast began (`SMSG_SPELL_START`), instants included with `cast_time_ms` 0.
     SpellStart {
         caster: u64,
         spell_id: u32,
         cast_flags: u16,
         cast_time_ms: u32,
         target: Option<u64>,
-        /// The nocked-ammo display id (the `CAST_FLAG_AMMO` tail, ranged spells only) — feeds the
-        /// caster's worn ammo model (the client's `0x60ba30` @ START `0x6e78b6`, any caster;
-        /// wow-re `nocked-ammo-cancel.md`). `None` when the flag is clear.
+        /// The `CAST_FLAG_AMMO` tail: nocked ammo for any caster (`0x60ba30` from `0x6e78b6`).
         ammo_display_id: Option<u32>,
     },
-    /// The cast launched (`SMSG_SPELL_GO`): hit/miss lists + (for a ranged spell) the ammo display
-    /// id for the projectile visual. The server schedules impact itself off `Spell.dbc` Speed —
-    /// nothing about missile travel rides this packet.
+    /// The cast launched (`SMSG_SPELL_GO`); the server times impact off `Spell.dbc` Speed itself.
     SpellGo {
         caster: u64,
         spell_id: u32,
@@ -860,176 +560,130 @@ pub enum SessionEvent {
         hits: Vec<u64>,
         misses: Vec<(u64, u8)>,
         target: Option<u64>,
-        /// The GameObject an open-lock cast launched at (`TARGET_FLAG_GAMEOBJECT`) — opens a chest lid /
-        /// locked door (decision 2271). `None` for a unit spell.
+        /// The GameObject an open-lock cast targets (`TARGET_FLAG_GAMEOBJECT`), a chest or door.
         go_target: Option<u64>,
-        /// The ground point a dest-targeted cast launched at (`TARGET_FLAG_DEST_LOCATION`), raw
-        /// WoW coords — where a ground AOE's launch-side visual belongs (the B132 follow-up;
-        /// the persistent effect anchors to the DynamicObject create instead). `None` otherwise.
+        /// The ground point (`TARGET_FLAG_DEST_LOCATION`, raw WoW); the lasting effect is a
+        /// DynamicObject.
         dest: Option<[f32; 3]>,
         ammo_display_id: Option<u32>,
-        /// The **cast item's** guid when the packet's first guid names one (an item use — potion,
-        /// scroll: `item_or_caster != caster`); `None` for a plain spell cast. The item-use
-        /// cooldown keys on it (decision 0137 phase 4 — the client resolves its SPELLCAST item
-        /// the same way).
+        /// The cast item when the first guid is not the caster; the item cooldown keys on it.
         item_caster: Option<u64>,
     },
-    /// The hop list for a caster's **beam** (`SMSG_SPELL_UPDATE_CHAIN_TARGETS`, decision 0955):
-    /// the units a chain/beam visual runs through, caster → t1 → t2 → …. The client's own array
-    /// (`unit+0xd44`) is filled from this and from nothing else, and is consumed once by the next
-    /// chain `CharProc` — so this is an edge, not a state.
-    ///
-    /// vmangos sends it only for **channeled** spells. The cast-stage chains get their hops from
-    /// [`Self::SpellGo`]'s hit list instead — which is the reference's own second producer
-    /// (`0x6e800d` inside its SPELL_GO handler fills the same array), not a divergence.
+    /// A channeled beam's hops (`SMSG_SPELL_UPDATE_CHAIN_TARGETS`), consumed once by the next chain
+    /// `CharProc`; the reference fills that `unit+0xd44` array from spell-go hits too (`0x6e800d`).
     SpellChainTargets {
         caster: u64,
         spell_id: u32,
         targets: Vec<u64>,
     },
-    /// An observed cast was interrupted/cancelled (`SMSG_SPELL_FAILED_OTHER`) — ends the caster's
-    /// `Casting` state seam the same as a [`Self::SpellGo`].
+    /// An observed cast was interrupted or cancelled (`SMSG_SPELL_FAILED_OTHER`).
     SpellFailedOther { caster: u64, spell_id: u32 },
-    /// Our own cast was pushed back by damage (`SMSG_SPELL_DELAYED`) — the cast bar slides its
-    /// window out by `delay_ms` instead of finishing early (decision 0256).
+    /// Our cast was pushed back by damage (`SMSG_SPELL_DELAYED`); its end moves out by `delay_ms`.
     SpellDelayed { caster: u64, delay_ms: u32 },
-    /// Stop our own ranged auto-repeat visual (`SMSG_CANCEL_AUTO_REPEAT`, self-only). No
-    /// ranged-attack consumer exists yet (decision 0099 phase 5).
+    /// Stop our own ranged auto-repeat (`SMSG_CANCEL_AUTO_REPEAT`, self-only).
     CancelAutoRepeat,
-    /// Server-pushed cooldowns (`SMSG_SPELL_COOLDOWN`) for `caster` (the player or pet): pairs of
-    /// `(spell_id, cooldown_ms)`, where `0` ms means "use the spell's own Spell.dbc recovery
-    /// times" (decision 0137 phase 4; the school-lockout / pet path — a normal cast's cooldown is
-    /// client-tracked).
+    /// `SMSG_SPELL_COOLDOWN` for the player or pet: `(spell_id, cooldown_ms)`, 0 ms meaning the
+    /// spell's own `Spell.dbc` recovery; a normal cast's cooldown is client-tracked.
     SpellCooldowns {
         caster: u64,
         cooldowns: Vec<(u32, u32)>,
     },
     /// Put an item instance on the client's fixed 30 s use cooldown (`SMSG_ITEM_COOLDOWN`).
     ItemCooldown { item_guid: u64, spell_id: u32 },
-    /// `SMSG_ITEM_TIME_UPDATE` — the seconds left on one duration-limited item instance (a
-    /// conjured stone, a holiday gift, a timed quest item). The item's own `ITEM_FIELD_DURATION`
-    /// carries the same number and is sent to the owner, but vmangos's writer says outright that
-    /// the field is not what the client displays from (`Item::SendTimeUpdate`,
-    /// `Objects/Item.cpp:1094`) — same shape as the enchant countdown (decision 0920).
-    /// `seconds == 0` = expired / no timer. Decision 1933.
+    /// `SMSG_ITEM_TIME_UPDATE`: seconds left on a timed item, 0 when expired. The client shows
+    /// this, not `ITEM_FIELD_DURATION` (vmangos `Item::SendTimeUpdate`, `Objects/Item.cpp:1094`).
     ItemTime { item_guid: u64, seconds: u32 },
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE` — the seconds left on one item's TEMPORARY enchant, in the
-    /// named enchant slot. The **only** feed for the tooltip's countdown: the item's own
-    /// `ITEM_FIELD_ENCHANTMENT` duration field is never read for it (wow-re
-    /// `ui/scratch/tooltip-content-law.md` §E3; decision 0920). `seconds == 0` = expired.
+    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE`: seconds left on a temporary enchant, 0 when expired; the
+    /// tooltip countdown's only feed, never the `ITEM_FIELD_ENCHANTMENT` duration.
     ItemEnchantTime {
         item_guid: u64,
         slot: u32,
         seconds: u32,
     },
-    /// One cell of a talent spell-modifier table, absolutely (`SMSG_SET_FLAT_SPELL_MODIFIER` /
-    /// `SMSG_SET_PCT_SPELL_MODIFIER`): `flat` picks the table, `mask_bit` is the spell's
-    /// `SpellFamilyFlags` **bit index** (the row) and `op` the SpellModOp (the column). Neither
-    /// byte is bounded on the wire — the consumer (`benilla::spell_mods`) refuses an out-of-range
-    /// pair rather than reproducing the reference's own overrun. `value` is **absolute**, not a
-    /// delta; the wire shape and the `bit * 29 + op` index law are on
-    /// [`crate::messages::ServerPacket::SpellModifier`].
+    /// A talent spell-modifier cell (`SMSG_SET_FLAT_SPELL_MODIFIER`/`_PCT_`), absolute: row
+    /// `mask_bit`, a `SpellFamilyFlags` bit, column `op`, neither bounded on the wire. Deviation:
+    /// `benilla::spell_mods` refuses an out-of-range pair, because the reference would overrun it.
     SpellModifier {
         flat: bool,
         mask_bit: u8,
         op: u8,
         value: i32,
     },
-    /// Start an on-hold (`SPELL_ATTR_COOLDOWN_ON_EVENT`) cooldown's parked timers now
-    /// (`SMSG_COOLDOWN_EVENT`).
+    /// Start an on-hold (`SPELL_ATTR_COOLDOWN_ON_EVENT`) cooldown now (`SMSG_COOLDOWN_EVENT`).
     CooldownEvent { spell_id: u32, caster: u64 },
     /// Remove one spell's cooldown record (`SMSG_CLEAR_COOLDOWN`).
     ClearCooldown { spell_id: u32, caster: u64 },
     /// Wipe every cooldown for `caster` (`SMSG_COOLDOWN_CHEAT`, the GM reset).
     CooldownCheat { caster: u64 },
-    /// Our own channeled cast opened (`MSG_CHANNEL_START`, self-only — no guid on the wire). The
-    /// cast bar's channel-open edge (decision 0137).
+    /// Our own channel opened (`MSG_CHANNEL_START`, self-only, no guid on the wire).
     ChannelStart { spell_id: u32, duration_ms: u32 },
-    /// Our own channel's remaining time (`MSG_CHANNEL_UPDATE`, self-only); `0` = the channel is
-    /// over — natural end and interrupt alike (decision 0137).
+    /// A channel's time left (`MSG_CHANNEL_UPDATE`, self-only); 0 is over, natural or interrupted.
     ChannelUpdate { remaining_ms: u32 },
-    /// How long one of **our own** auras has left (`SMSG_UPDATE_AURA_DURATION`), keyed by its
-    /// `UNIT_FIELD_AURA` slot. Self-only, never sent for a permanent aura, and it arrives *before*
-    /// the descriptor delta that names the slot's spell — so the aura feed buffers it by slot and
-    /// joins on the spell present when it lands (decisions 0255/0257).
+    /// Time left on one of our auras by `UNIT_FIELD_AURA` slot (`SMSG_UPDATE_AURA_DURATION`),
+    /// never for a permanent one. It arrives before the delta naming the slot's spell.
     AuraDuration { slot: u8, remaining_ms: u32 },
-    /// Play a spell-visual kit on a unit outside the normal cast sequence (`SMSG_PLAY_SPELL_VISUAL`
-    /// — eat/drink kits, a channel-kit refresh workaround). No VFX consumer yet (decision 0099
-    /// phase 3).
+    /// A spell-visual kit outside the cast sequence (`SMSG_PLAY_SPELL_VISUAL`), such as eat/drink.
     PlaySpellVisual { unit: u64, kit_id: u32 },
-    /// Non-melee (spell) damage dealt (`SMSG_SPELLNONMELEEDAMAGELOG`) — decision 0137 phase 2's
-    /// floating-combat-text data feed.
+    /// Spell damage dealt (`SMSG_SPELLNONMELEEDAMAGELOG`).
     SpellDamageLog(SpellDamageLog),
-    /// Periodic (DoT/HoT/regen) aura ticks (`SMSG_PERIODICAURALOG`) — decision 0137 phase 2.
+    /// Periodic aura ticks: DoT, HoT, regen (`SMSG_PERIODICAURALOG`).
     PeriodicAuraLog(PeriodicAuraLog),
-    /// A direct heal landing (`SMSG_SPELLHEALLOG`) — decision 0578's center-combat-text feed.
+    /// A direct heal (`SMSG_SPELLHEALLOG`).
     SpellHealLog(SpellHealLog),
-    /// An instant power gain (`SMSG_SPELLENERGIZELOG`) — decision 0578.
+    /// An instant power gain (`SMSG_SPELLENERGIZELOG`).
     SpellEnergizeLog(SpellEnergizeLog),
-    /// A damage-shield (Thorns-style) return hit (`SMSG_SPELLDAMAGESHIELD`) — decision 0137 phase 2.
+    /// A damage-shield (Thorns-style) return hit (`SMSG_SPELLDAMAGESHIELD`).
     DamageShield(DamageShield),
-    /// Environmental damage taken — fall/drowning/fatigue/lava/slime/fire
-    /// (`SMSG_ENVIRONMENTALDAMAGELOG`): the client-side feedback trigger (the fall-landing dust
-    /// kit via `EnvironmentalDamage.dbc`).
+    /// Environmental damage (`SMSG_ENVIRONMENTALDAMAGELOG`); kit from `EnvironmentalDamage.dbc`.
     EnvironmentalDamageLog(EnvironmentalDamageLog),
-    /// A spell cast's per-target miss list (`SMSG_SPELLLOGMISS`) — decision 0137 phase 2.
+    /// A cast's per-target miss list (`SMSG_SPELLLOGMISS`).
     SpellLogMiss(SpellLogMiss),
-    /// The killing blow (`SMSG_PARTYKILLLOG`) — the "You have slain %s!" line's only source
-    /// (decision 1703).
+    /// The killing blow (`SMSG_PARTYKILLLOG`), the only source of "You have slain %s!".
     PartyKillLog(PartyKillLog),
-    /// An instant kill (`SMSG_SPELLINSTAKILLLOG`) — decision 1703.
+    /// An instant kill (`SMSG_SPELLINSTAKILLLOG`).
     SpellInstaKillLog(SpellInstaKillLog),
-    /// A proc the target resisted (`SMSG_PROCRESIST`) — decision 1703.
+    /// A proc the target resisted (`SMSG_PROCRESIST`).
     ProcResist(SpellOutcomeLog),
-    /// A target immune to the spell (`SMSG_SPELLORDAMAGE_IMMUNE`) — decision 1703.
+    /// A target immune to the spell (`SMSG_SPELLORDAMAGE_IMMUNE`).
     SpellOrDamageImmune(SpellOutcomeLog),
-    /// The auras a dispel removed (`SMSG_SPELLDISPELLOG`) — decision 1703.
+    /// The auras a dispel removed (`SMSG_SPELLDISPELLOG`).
     SpellDispelLog(SpellDispelLog),
-    /// The auras a dispel failed to remove (`SMSG_DISPEL_FAILED`) — decision 1703.
+    /// The auras a dispel failed to remove (`SMSG_DISPEL_FAILED`).
     DispelFailed(DispelFailed),
-    /// An enchant landing on or fading from an item (`SMSG_ENCHANTMENTLOG`) — decision 1703.
+    /// An enchant landing on or fading from an item (`SMSG_ENCHANTMENTLOG`).
     EnchantmentLog(EnchantmentLog),
-    /// What a cast's effects did (`SMSG_SPELLLOGEXECUTE`) — decision 1703.
+    /// What a cast's effects did (`SMSG_SPELLLOGEXECUTE`).
     SpellLogExecute(SpellLogExecute),
-    /// An XP award, kill or non-kill (`SMSG_LOG_XPGAIN`) — decision 0137 phase 2.
+    /// An XP award, kill or non-kill (`SMSG_LOG_XPGAIN`).
     XpGain(XpGain),
-    /// A first visit to an area (`SMSG_EXPLORATION_EXPERIENCE`) — the discovered area id + its
-    /// XP award; the "Discovered …" chat line's data (decision 0828).
+    /// A first visit to an area and its XP (`SMSG_EXPLORATION_EXPERIENCE`), the "Discovered" line.
     ExplorationXp(ExplorationXp),
-    /// Our own ding (`SMSG_LEVELUP_INFO`, self-addressed only) — decision 0304.
+    /// Our own level-up (`SMSG_LEVELUP_INFO`, self-only).
     LevelUp(LevelUpInfo),
-    /// A gossip menu opened on an NPC (`SMSG_GOSSIP_MESSAGE`, answering our `CMSG_GOSSIP_HELLO`):
-    /// `text_id` drives a follow-up [`crate::messages::npc_text_query`] for the greeting body;
-    /// `options` are the selectable lines (icon + coded flag + label). `quests` are the quest-option
-    /// rows riding the same packet — `(quest_id, dialog-status icon, title)`; the gossip window lists
-    /// them and a click sends `CMSG_QUESTGIVER_QUERY_QUEST` (decision 0088).
+    /// A gossip menu (`SMSG_GOSSIP_MESSAGE`): `text_id` is the greeting for
+    /// [`crate::messages::npc_text_query`]; `quests` rows are `(quest_id, icon, level, title)`.
     GossipMenu {
         npc: u64,
         text_id: u32,
         options: Vec<GossipOption>,
         quests: Vec<(u32, u32, u32, String)>,
     },
-    /// A questgiver dialog status for one NPC (`SMSG_QUESTGIVER_STATUS`) — the `!`/`?` marker's
-    /// [`crate::messages::dialog_status`] value. Stored per guid now; the world marker is a later
-    /// slice (decision 0088).
+    /// An NPC's `!`/`?` marker (`SMSG_QUESTGIVER_STATUS`), a [`crate::messages::dialog_status`].
     QuestGiverStatus { npc: u64, status: u32 },
     /// The greeting panel: an NPC's offered/active quest rows (`SMSG_QUESTGIVER_QUEST_LIST`).
     QuestGreeting(QuestGiverList),
-    /// The accept panel: full quest text + rewards on offer (`SMSG_QUESTGIVER_QUEST_DETAILS`).
+    /// The accept panel: quest text and rewards on offer (`SMSG_QUESTGIVER_QUEST_DETAILS`).
     QuestDetail(QuestDetails),
-    /// The progress panel: "bring me these" text + required items/money + completability
-    /// (`SMSG_QUESTGIVER_REQUEST_ITEMS`).
+    /// The progress panel: what to bring (`SMSG_QUESTGIVER_REQUEST_ITEMS`).
     QuestProgress(QuestRequestItems),
-    /// The reward panel: turn-in text + rewards to grant (`SMSG_QUESTGIVER_OFFER_REWARD`).
+    /// The reward panel: turn-in text and rewards to grant (`SMSG_QUESTGIVER_OFFER_REWARD`).
     QuestOffer(QuestOfferReward),
-    /// The turn-in result: XP/money granted + fixed items (`SMSG_QUESTGIVER_QUEST_COMPLETE`).
+    /// The turn-in result: XP, money and fixed items granted (`SMSG_QUESTGIVER_QUEST_COMPLETE`).
     QuestComplete(QuestComplete),
-    /// The full quest template (`SMSG_QUEST_QUERY_RESPONSE`, answering our `CMSG_QUEST_QUERY`) —
-    /// the quest log's ask-once detail source, cached by `quest_id`.
+    /// The full quest template (`SMSG_QUEST_QUERY_RESPONSE`), asked once and cached by id.
     QuestTemplate(Box<QuestTemplate>),
-    /// A kill/use objective ticked (`SMSG_QUESTUPDATE_ADD_KILL`) — the "Kobold Vermin slain: 3/10"
-    /// toast. `entry` carries the raw creature/GO encoding (GO = `(−id)|0x80000000`); the durable
-    /// count also lands in the `PLAYER_QUEST_LOG` slot's counter field, this is the announce line.
+    /// A kill objective ticked (`SMSG_QUESTUPDATE_ADD_KILL`), the announce line only; a GO
+    /// `entry` is `(-id)|0x80000000`, and the durable count is in the `PLAYER_QUEST_LOG` slot.
     QuestObjectiveKill {
         quest_id: u32,
         entry: u32,
@@ -1038,297 +692,202 @@ pub enum SessionEvent {
     },
     /// An item-collection objective toast (`SMSG_QUESTUPDATE_ADD_ITEM`).
     QuestObjectiveItem { item_id: u32, count: u32 },
-    /// Every objective on the quest is complete (`SMSG_QUESTUPDATE_COMPLETE`) — the "Quest
-    /// completed" line; the slot's state byte carries the durable fact.
+    /// All objectives done (`SMSG_QUESTUPDATE_COMPLETE`), a line only; the slot state is durable.
     QuestObjectivesComplete { quest_id: u32 },
-    /// The quest failed (`SMSG_QUESTUPDATE_FAILED` / `_FAILEDTIMER` — `timed` picks which).
+    /// The quest failed (`SMSG_QUESTUPDATE_FAILED`, or `_FAILEDTIMER` when `timed`).
     QuestFailed { quest_id: u32, timed: bool },
-    /// The log refused a new quest — no free slot (`SMSG_QUESTLOG_FULL`).
+    /// The log refused a new quest: no free slot (`SMSG_QUESTLOG_FULL`).
     QuestLogFull,
-    /// One party member's verdict on a quest WE shared (`MSG_QUEST_PUSH_RESULT`) — decision 1733.
-    /// `member` is the member the verdict is about (never the sharer; see the direction trap on
-    /// [`crate::messages::QuestPushResult`]), and fills the `%s` of the `ERR_QUEST_PUSH_*` line.
+    /// A member's verdict on a quest we shared (`MSG_QUEST_PUSH_RESULT`). `member` is that
+    /// member, never the sharer ([`crate::messages::QuestPushResult`]); it fills the `%s`.
     QuestPushResult { member: u64, msg: QuestShareMsg },
-    /// A party member started a `QUEST_FLAGS_PARTY_ACCEPT` (escort) quest and the server is asking
-    /// whether we want it too (`SMSG_QUEST_CONFIRM_ACCEPT`) — the `QUEST_ACCEPT` confirm box.
+    /// A member's escort quest offered to us too (`SMSG_QUEST_CONFIRM_ACCEPT`).
     QuestConfirmAccept(QuestConfirmAccept),
-    /// The giver won't OFFER the quest (`SMSG_QUESTGIVER_QUEST_INVALID`): one `QuestFailedReason`
-    /// msg code and no quest id — vmangos' `SendCanTakeQuestResponse`, the answer to a query or an
-    /// accept that fails `CanTakeQuest` ("already on that quest", "not high enough level").
+    /// The giver won't offer the quest (`SMSG_QUESTGIVER_QUEST_INVALID`): a reason, no quest id
+    /// (vmangos `SendCanTakeQuestResponse` on a failed `CanTakeQuest`).
     QuestGiverInvalid { reason: u32 },
-    /// A quest the giver DID offer failed on accept (`SMSG_QUESTGIVER_QUEST_FAILED`): the
-    /// `{questId, reason}` pair, whose line names the quest. Kept apart from
-    /// [`Self::QuestGiverInvalid`] because the reference reads the two packets with two different
-    /// handlers and two different message tables (decision 0669).
+    /// An offered quest failed on accept (`SMSG_QUESTGIVER_QUEST_FAILED`); the reference reads it
+    /// with a different handler and message table from [`Self::QuestGiverInvalid`].
     QuestGiverFailed { quest_id: u32, reason: u32 },
-    /// The gossip window closes (`SMSG_GOSSIP_COMPLETE`) — no menu is open server-side any more.
+    /// The gossip window closes (`SMSG_GOSSIP_COMPLETE`); no menu is open server-side.
     GossipComplete,
-    /// A guard's directions (`SMSG_GOSSIP_POI`): drop a marker at that spot on the minimap and the
-    /// world map. Volunteered by a gossip option carrying an `action_poi_id` — never requested.
+    /// A guard's directions (`SMSG_GOSSIP_POI`): a map marker sent for an `action_poi_id` option.
     GossipPoi(crate::messages::GossipPoi),
-    /// The greeting record for a gossip menu (`SMSG_NPC_TEXT_UPDATE`, answering our
-    /// `CMSG_NPC_TEXT_QUERY`) — all 8 blocks, **undrawn**: which line greets you depends on the
-    /// NPC's gender and a die roll, so the app draws it when the frame opens
-    /// (`messages::gossip::select_greeting`). `$N` and friends are client-substituted tokens still
-    /// in the strings.
+    /// All 8 greeting blocks, undrawn (`SMSG_NPC_TEXT_UPDATE`): the pick depends on the NPC's
+    /// gender and a roll as the frame opens; `$N` and its kin are still unsubstituted.
     NpcGreeting {
         text_id: u32,
         blocks: Vec<crate::messages::NpcTextBlock>,
     },
-    /// A vendor's stock (`SMSG_LIST_INVENTORY`, answering our `CMSG_LIST_INVENTORY`): entry, icon,
-    /// price, and remaining stock per row (`current_count == 0xFFFF_FFFF` = unlimited).
+    /// A vendor's stock (`SMSG_LIST_INVENTORY`); `current_count == 0xFFFF_FFFF` is unlimited.
     VendorInventory { vendor: u64, items: Vec<VendorItem> },
-    /// A trainer's service list (`SMSG_TRAINER_LIST`, reached via the gossip trainer option): the
-    /// wire services (each a spell id + cost + green/red/gray state + level/skill/ability gates), the
-    /// window-framing `trainer_type` (0 class · 1 mount · 2 tradeskill · 3 pet), and the greeting
-    /// title. The app resolves each service to name/icon through its spell catalog (decision 0237).
+    /// Trainer list (`SMSG_TRAINER_LIST`); `trainer_type` 0 class, 1 mount, 2 tradeskill, 3 pet.
     TrainerList {
         trainer: u64,
         trainer_type: u32,
         services: Vec<TrainerSpell>,
         greeting: String,
     },
-    /// Forget a player's cached name (`SMSG_INVALIDATE_PLAYER`, decision 1689) — the name cache's
-    /// only explicit eviction for a player, and the safety valve a *persisted* cache needs.
+    /// Forget a player's cached name (`SMSG_INVALIDATE_PLAYER`), the cache's only eviction.
     InvalidatePlayer { guid: u64 },
-    /// A stable master's pet list (`MSG_LIST_STABLED_PETS`, decision 1676) — the current pet and
-    /// the stabled ones, each already carrying its rebased client slot (`0` = current), plus how
-    /// many stable slots the player has **bought**. Arrives unprompted when the gossip stable
-    /// option is chosen (that is how the window opens) and again in answer to our own refresh send.
-    ///
-    /// Read the rows **by slot, never by position**: the current-pet row is absent for a petless
-    /// hunter, so `pets[0]` is not necessarily slot 0.
+    /// The stable list (`MSG_LIST_STABLED_PETS`), unasked on the gossip option and on refresh;
+    /// slots are rebased, 0 the current pet. Read by slot: a petless hunter has no slot-0 row.
     ListStabledPets {
         npc: u64,
         num_stable_slots: u8,
         pets: Vec<StabledPet>,
     },
-    /// The answer to every stable verb (`SMSG_STABLE_RESULT`, decision 1676) — one
-    /// [`crate::messages::stable_result`] code and nothing else. No success carries an updated
-    /// list, so repainting the window takes a fresh `MSG_LIST_STABLED_PETS` send.
+    /// Every stable verb's answer (`SMSG_STABLE_RESULT`), a [`crate::messages::stable_result`];
+    /// no success carries a list, so repaint with a fresh `MSG_LIST_STABLED_PETS`.
     StableResult { result: u8 },
-    /// A trainer taught a service (`SMSG_TRAINER_BUY_SUCCEEDED`, answering `CMSG_TRAINER_BUY_SPELL`):
-    /// confirmation only — the spell itself arrives via `SMSG_LEARNED_SPELL` (already in the book).
-    /// The app re-requests `CMSG_TRAINER_LIST` on this to repaint the bought row green→gray (decision
-    /// 0237: the server never auto-resends the list on a buy).
+    /// A purchase took (`SMSG_TRAINER_BUY_SUCCEEDED`); the server never resends the list itself.
     TrainerBuySucceeded { trainer: u64, spell_id: u32 },
-    /// A trainer refused a purchase (`SMSG_TRAINER_BUY_FAILED`): `error` is a
-    /// [`crate::messages::train_fail`] code (0 unavailable · 1 not-enough-money · 2 not-enough-skill).
-    /// Surfaces on the trainer window's error line.
+    /// A refused purchase (`SMSG_TRAINER_BUY_FAILED`), `error` a [`crate::messages::train_fail`].
     TrainerBuyFailed {
         trainer: u64,
         spell_id: u32,
         error: u32,
     },
-    /// A vendor's stock updated after a purchase (`SMSG_BUY_ITEM`). The purchased item itself
-    /// arrives through the normal item-create + inventory-slot update path, already handled.
+    /// A vendor's stock after a purchase (`SMSG_BUY_ITEM`); the item comes by the normal create.
     VendorBuyResult {
         vendor: u64,
         slot: u32,
         new_count: u32,
         purchase_count: u32,
     },
-    /// A sell was refused (`SMSG_SELL_ITEM`'s error path — a success sends no packet at all).
-    /// `reason` is a `SellResult` code ([`crate::messages::sell_result`]).
+    /// A refused sale (`SMSG_SELL_ITEM`, a [`crate::messages::sell_result`]); a success is silent.
     VendorSellFailed {
         vendor: u64,
         item_guid: u64,
         reason: u8,
     },
-    /// A purchase was refused (`SMSG_BUY_FAILED`). `reason` is a `BuyResult` code
-    /// ([`crate::messages::buy_result`]).
+    /// A refused purchase (`SMSG_BUY_FAILED`), `reason` a [`crate::messages::buy_result`].
     VendorBuyFailed {
         vendor: u64,
         item_entry: u32,
         reason: u8,
     },
-    /// The bank window opens (`SMSG_SHOW_BANK`), answering our `CMSG_BANKER_ACTIVATE` — or
-    /// arriving unprompted for the `GOSSIP_OPTION_BANKER` gossip option, so a handler must not
-    /// assume it always follows our own activate. The vault contents are already in the player
-    /// descriptor (decision 0604); this only opens the window.
+    /// The bank opens (`SMSG_SHOW_BANK`), also unasked via gossip; contents are in the descriptor.
     ShowBank { banker: u64 },
-    /// A bank-slot purchase was refused (`SMSG_BUY_BANK_SLOT_RESULT`). `result` is a `BankSlotResult`
-    /// code ([`crate::messages::bank_slot_result`]); a successful buy sends no packet, visible only
-    /// as the `PLAYER_BYTES_2` bank-bag-count byte advancing + the coinage drop.
+    /// A refused bank-slot purchase (`SMSG_BUY_BANK_SLOT_RESULT`); a success sends nothing, only
+    /// the `PLAYER_BYTES_2` bag count and the coinage change.
     BuyBankSlotResult { result: u32 },
-    /// A loot window opened (`SMSG_LOOT_RESPONSE`'s normal shape), answering our `CMSG_LOOT`:
-    /// `loot_type` is a `loot::loot_type` code, `items` the row list (quest rows ride the same
-    /// list, `slot = items.len() + i`). A row still under a group roll arrives with
-    /// `slot_type == ROLL_ONGOING` (decision 0591); under master loot every row vmangos shows a
-    /// group member arrives `slot_type == MASTER` (decision 1675).
+    /// A loot window opened (`SMSG_LOOT_RESPONSE`); quest rows follow the normal ones. A row under
+    /// a group roll is `ROLL_ONGOING`; under master loot, vmangos marks a member's rows `MASTER`.
     LootResponse {
         guid: u64,
         loot_type: u8,
         gold: u32,
         items: Vec<LootItem>,
     },
-    /// The server refused to open the loot window (`SMSG_LOOT_RESPONSE`'s error shape — didn't
-    /// kill it, too far, not standing, …). `error` is a `loot::loot_error` code.
+    /// A refused loot window (`SMSG_LOOT_RESPONSE`'s error shape), a `loot::loot_error` code.
     LootError { guid: u64, error: u8 },
-    /// One loot-window row was taken, by anyone (`SMSG_LOOT_REMOVED`) — the UI clears that row.
+    /// A loot row was taken, by anyone (`SMSG_LOOT_REMOVED`).
     LootRemoved { slot: u8 },
-    /// Our share of the loot's coin pile (`SMSG_LOOT_MONEY_NOTIFY`), answering our
-    /// `CMSG_LOOT_MONEY`.
+    /// Our share of the coin (`SMSG_LOOT_MONEY_NOTIFY`), answering `CMSG_LOOT_MONEY`.
     LootMoneyNotify { amount: u32 },
     /// The coin line disappears for every current looter (`SMSG_LOOT_CLEAR_MONEY`).
     LootClearMoney,
     /// The loot window closes (`SMSG_LOOT_RELEASE_RESPONSE`), answering our `CMSG_LOOT_RELEASE`.
     LootReleaseResponse { guid: u64 },
-    /// A group roll opened on one drop (`SMSG_LOOT_START_ROLL`) — the app allocates a client-side
-    /// `rollID` for it and raises a `GroupLootFrame` (decision 0591).
+    /// A group roll opened on one drop (`SMSG_LOOT_START_ROLL`); its `rollID` is client-allocated.
     LootStartRoll(LootStartRoll),
-    /// One roller's vote or dice result (`SMSG_LOOT_ROLL`) — the chat announcement line. The
-    /// `(roll_number, roll_type)` pair is overloaded; `LootRoll::is_dice`/`vote` disentangle it.
+    /// A vote or dice (`SMSG_LOOT_ROLL`); `LootRoll::is_dice`/`vote` split the overloaded pair.
     LootRoll(LootRoll),
-    /// A group roll resolved (`SMSG_LOOT_ROLL_WON`) — closes that roll's frame.
+    /// A group roll resolved (`SMSG_LOOT_ROLL_WON`), closing its frame.
     LootRollWon(LootRollWon),
-    /// Everyone passed (`SMSG_LOOT_ALL_PASSED`) — closes that roll's frame; the item returns to
-    /// the corpse for ordinary looting.
+    /// Everyone passed (`SMSG_LOOT_ALL_PASSED`); the item returns to ordinary looting.
     LootAllPassed(LootAllPassed),
-    /// The group members eligible to receive an item from the loot window that is opening
-    /// (`SMSG_LOOT_MASTER_LIST`) — it arrives *before* the `LootResponse` it belongs to, because
-    /// the server sends it from inside `SendLoot` (decision 1675).
+    /// Master-loot candidates (`SMSG_LOOT_MASTER_LIST`), sent by `SendLoot` before its response.
     LootMasterList { candidates: Vec<u64> },
-    /// An item landed in our bags — looted or received from an NPC (`SMSG_ITEM_PUSH_RESULT`);
-    /// drives the "You receive loot: …" chat line.
+    /// An item landed in our bags (`SMSG_ITEM_PUSH_RESULT`): the "You receive loot" line.
     ItemPushResult(ItemPushResult),
-    /// The keepalive echo (`SMSG_PONG`): the sequence number of the `CMSG_PING` it answers. The app
-    /// matches it against the ping clock (shared with the write thread's 30 s sender) to measure
-    /// the round-trip time shown in the debug panel.
+    /// The keepalive echo (`SMSG_PONG`) of a 30 s `CMSG_PING`, matched by `sequence`.
     Pong { sequence: u32 },
-    /// The server changed one of our mover's speeds (`SMSG_FORCE_*_SPEED_CHANGE` — an aura
-    /// slow/haste, a mount, GM `.modify speed`) and awaits the matching ack. The app must (1) apply
-    /// `speed` to the mover's [`MoveSpeeds`] entry for `kind`, and (2) answer
-    /// `CMSG_FORCE_*_SPEED_CHANGE_ACK` echoing `counter` + the exact `speed` with a live
-    /// `MovementInfo` — unacked, the server force-resolves after ~4 s and flags its anticheat
-    /// (`Unit::CheckPendingMovementChanges`), so every speed change desyncs without this.
+    /// Our speed changed (`SMSG_FORCE_*_SPEED_CHANGE`): ack `counter`, the exact `speed` and a live
+    /// `MovementInfo`, or vmangos flags anticheat in about 4 s (`CheckPendingMovementChanges`).
     ForceSpeedChange {
         guid: u64,
         kind: crate::messages::SpeedKind,
         counter: u32,
         speed: f32,
     },
-    /// A speed change on a unit we do NOT control (`SMSG_SPLINE_SET_*_SPEED` /
-    /// `MSG_MOVE_SET_*_SPEED` — an observed player mounting up, a hastened creature). Apply to the
-    /// unit's [`MoveSpeeds`] entry for `kind`; **no ack** (decision 0441). The MOVE_SET flavour's
-    /// accompanying pose arrives as its own [`Self::UnitMove`].
+    /// Another unit's speed (`SMSG_SPLINE_SET_*_SPEED`/`MSG_MOVE_SET_*_SPEED`), no ack.
     SpeedChanged {
         guid: u64,
         kind: crate::messages::SpeedKind,
         speed: f32,
     },
-    /// The server's answer to our (dis)mount attempt (`SMSG_MOUNTRESULT` /
-    /// `SMSG_DISMOUNTRESULT`, split by `mount`): a raw result code (OK = 10 mounting / 3
-    /// dismounting; the failure codes are red-error-line material — a P2 trimming, decision 0441).
+    /// `SMSG_MOUNTRESULT` (or `_DISMOUNTRESULT` if not `mount`): OK is 10 mounting, 3 dismounting.
     MountResult { mount: bool, code: u32 },
-    /// A nearby rider hit the mounted flourish (`SMSG_MOUNTSPECIAL_ANIM`): play MountSpecial(94)
-    /// on that unit's mount. Our own guid may arrive too — whether the sender gets the echo
-    /// is a server-config detail (vmangos's non-broadcaster delivery echoes; the optional
-    /// per-player broadcaster does not) — so the app self-suppresses it on receive and plays
-    /// its own flourish locally at send time.
+    /// A rider's flourish (`SMSG_MOUNTSPECIAL_ANIM`): MountSpecial (94) on its mount. Whether our
+    /// own echo arrives depends on vmangos's broadcaster, so the app plays ours at send instead.
     MountSpecial { guid: u64 },
-    /// The server handed us — or took from us — the reins of a unit (`SMSG_CLIENT_CONTROL_UPDATE`).
-    ///
-    /// `mover` is the unit being spoken about, **not** necessarily a new subject: when the server
-    /// takes control away it names *us*, with `allow_move = false`. So the two questions the app
-    /// asks of this are different — "is this about me?" (`mover == self guid`) and "may that unit
-    /// move?" — and conflating them gets the mind-controlled *victim*'s case backwards.
-    ///
-    /// Answering with `CMSG_SET_ACTIVE_MOVER` is not optional when control is granted: vmangos
-    /// discards every `MSG_MOVE_*` for a mover it has not confirmed.
+    /// Control of a unit granted or taken (`SMSG_CLIENT_CONTROL_UPDATE`). Taking it names us with
+    /// `allow_move = false`, so "about me" and "may move" are separate questions. A grant needs
+    /// `CMSG_SET_ACTIVE_MOVER`: vmangos drops every `MSG_MOVE_*` for an unconfirmed mover.
     ClientControl { mover: u64, allow_move: bool },
-    /// A packet the codec dropped on the floor: `unparseable = false` means **no parse arm exists**
-    /// for the opcode at all (it fell through to `ServerPacket::Other` — a wire-coverage gap);
-    /// `true` means a parser exists but errored on this body (the reader skipped it to keep the
-    /// stream aligned). The app tallies these per opcode (the debug panel's dropped-opcode
-    /// instrument): a silently-ignored opcode is how a whole wire family — a speed change, a
-    /// compressed-moves batch — goes unnoticed for months.
+    /// A dropped packet: `unparseable` is false when no parse arm exists
+    /// (`ServerPacket::Other`), true when its parser errored and the body was skipped.
     PacketDropped { opcode: u16, unparseable: bool },
-    /// Where our corpse is (`MSG_CORPSE_QUERY`'s answer, after our empty-body request): feeds the
-    /// map corpse markers and the corpse-run range gate (decision 0308 §5). `found == false` also
-    /// arrives UNPROMPTED when the corpse converts to bones — it means "drop the marker".
-    /// `display_map`/`position` are where to walk toward (dungeon-entrance-adjusted);
-    /// `corpse_map` is the corpse's real map.
+    /// Where our corpse is (`MSG_CORPSE_QUERY`); `found == false` also comes unasked when it turns
+    /// to bones. `display_map`/`position` are entrance-adjusted, `corpse_map` the real map.
     CorpseQuery {
         found: bool,
         display_map: i32,
         position: [f32; 3],
         corpse_map: u32,
     },
-    /// Milliseconds until our corpse can be reclaimed (`SMSG_CORPSE_RECLAIM_DELAY` — at release
-    /// and at login-while-dead; 30 s base, 60/120 s on repeated deaths). Feeds
-    /// `GetCorpseRecoveryDelay` and the RECOVER_CORPSE popup's StartDelay gate.
+    /// Corpse reclaim delay (`SMSG_CORPSE_RECLAIM_DELAY`): 30 s, 60 or 120 s on repeated deaths.
     CorpseReclaimDelay { delay_ms: u32 },
-    /// The 10% natural-death durability loss landed (`SMSG_DURABILITY_DAMAGE_DEATH`, empty
-    /// body — sent beside the item-field deltas): the red
-    /// "Your equipped items suffer a 10% durability loss." error line's cue.
+    /// The 10% death durability loss (`SMSG_DURABILITY_DAMAGE_DEATH`, empty body): the red line.
     DurabilityDamageDeath,
-    /// Someone offered to resurrect us (`SMSG_RESURRECT_REQUEST`). `name` is EMPTY for a player
-    /// caster (resolve via the guid name cache); `sickness`/`has_timer` pick the reference popup
-    /// variant. Answered by `CMSG_RESURRECT_RESPONSE` (accept/decline).
+    /// A resurrect offer (`SMSG_RESURRECT_REQUEST`), answered by `CMSG_RESURRECT_RESPONSE`.
+    /// `name` is empty for a player caster; `sickness`/`has_timer` pick the popup variant.
     ResurrectRequest {
         caster: u64,
         name: String,
         sickness: bool,
         has_timer: bool,
     },
-    /// The spirit healer asks for the confirm (`SMSG_SPIRIT_HEALER_CONFIRM`, from the server's
-    /// gossip spirit-healer option): fires the CONFIRM_XP_LOSS popup; its Accept sends
-    /// `CMSG_SPIRIT_HEALER_ACTIVATE` back with this guid.
+    /// The spirit healer's `CONFIRM_XP_LOSS` popup (`SMSG_SPIRIT_HEALER_CONFIRM`); accepting sends
+    /// `CMSG_SPIRIT_HEALER_ACTIVATE` with `npc`.
     SpiritHealerConfirm { npc: u64 },
-    /// **A granted mover mode changed** — root, water-walk, feather-fall or hover (the ack'd
-    /// movement-mode family, decision 0866). Must be acked with the echoed `counter` (+ our current
-    /// `MovementInfo`), or the server never applies it and observers never see the change. The app
-    /// also **applies the mode to its own mover**: each one changes how the mover behaves — see
-    /// [`crate::messages::MoveMode`] for what each does.
+    /// Our root, water-walk, feather-fall or hover changed. Ack with `counter` and our
+    /// `MovementInfo`, or the server never applies it and observers never see it.
     MoveMode {
         guid: u64,
         counter: u32,
         mode: crate::messages::MoveMode,
         apply: bool,
     },
-    /// **Some unit's movement mode changed** — the `SMSG_SPLINE_MOVE_*` twelve (decision 1780),
-    /// the observer half of [`Self::MoveMode`]'s family. Nothing to ack; `guid` is any unit, and on
-    /// vmangos it is one the server is driving itself (a creature), which is precisely the case the
-    /// ack'd family structurally cannot reach. `apply` is always the direction of the mode's
-    /// `MOVEMENTFLAGS` bit ([`crate::messages::SplineMode::flag`]).
-    ///
-    /// The app folds it into that unit's granted-mode word, which the animation selector, the
-    /// creature ground clamp and the remote dead-reckon all read — the reference does the same and
-    /// then re-runs the unit's gait selector on the spot (`0x6014ec`), which is what makes the
-    /// family *visual* rather than bookkeeping.
+    /// Any unit's movement mode (the twelve `SMSG_SPLINE_MOVE_*`), no ack; on vmangos, a unit the
+    /// server drives. `apply` sets the mode's `MOVEMENTFLAGS` bit, and the reference then re-runs
+    /// the unit's gait selector (`0x6014ec`).
     SplineMoveMode {
         guid: u64,
         mode: crate::messages::SplineMode,
         apply: bool,
     },
-    /// **A knockback aimed at our own mover** (`SMSG_MOVE_KNOCK_BACK`, decision 1702) — the server
-    /// hands the controlling client a ballistic launch and lets it fly the arc itself; nothing about
-    /// it is a spline or a teleport. `launch` is the packet's quad as the jump tail it becomes:
-    /// world-XY direction (`cos_angle`, `sin_angle`), horizontal speed (`xy_speed`), and the
-    /// take-off vertical speed (`zspeed`, **down-positive** — negative is upward, decision 0054).
-    ///
-    /// Must be acked with the echoed `counter` and a `MovementInfo` whose jump tail is exactly this
-    /// quad, or the server logs a cheat and observers never see the knockback at all
-    /// ([`crate::messages::opcode::SMSG_MOVE_KNOCK_BACK`]).
+    /// A knockback on our mover (`SMSG_MOVE_KNOCK_BACK`): a launch we fly ourselves, `zspeed`
+    /// down-positive. Ack with `counter` and exactly this jump tail, or vmangos logs a cheat and
+    /// observers never see it.
     KnockBack {
         guid: u64,
         counter: u32,
         launch: crate::messages::JumpInfo,
     },
-    /// Someone invited us to their group (`SMSG_GROUP_INVITE`) — the invite popup.
+    /// Someone invited us to their group (`SMSG_GROUP_INVITE`): the invite popup.
     GroupInvite { inviter: String },
     /// An invite we sent was declined (`SMSG_GROUP_DECLINE`).
     GroupDecline { name: String },
-    /// We were removed from our group (`SMSG_GROUP_UNINVITE`, empty body) — kicked or left.
+    /// We were removed from our group (`SMSG_GROUP_UNINVITE`, empty body), kicked or left.
     GroupUninvited,
     /// The group's leader changed (`SMSG_GROUP_SET_LEADER`).
     GroupLeaderChanged { name: String },
     /// The group disbanded outright (`SMSG_GROUP_DESTROYED`, empty body).
     GroupDestroyed,
-    /// The full roster (`SMSG_GROUP_LIST`, sent on every membership change): `members` excludes
-    /// the recipient's own row (`own_flags` carries theirs); `loot` is `None` for the empty "you
-    /// left" shape and whenever the fetched list has no other members.
+    /// The full roster (`SMSG_GROUP_LIST`), without our own row; `loot` is `None` when alone.
     GroupList {
         group_type: u8,
         own_flags: u8,
@@ -1336,52 +895,44 @@ pub enum SessionEvent {
         leader: u64,
         loot: Option<GroupLootInfo>,
     },
-    /// The server's verdict on a group command we issued — invite/leave
-    /// (`SMSG_PARTY_COMMAND_RESULT`); `operation` is a [`crate::messages::party_operation`] code,
-    /// `result` a [`crate::messages::party_result`] code, `member` the named player (may be empty).
+    /// A group command's verdict (`SMSG_PARTY_COMMAND_RESULT`): a
+    /// [`crate::messages::party_operation`] and a [`crate::messages::party_result`] code.
     PartyCommandResult {
         operation: u32,
         member: String,
         result: u32,
     },
-    /// A party/raid member's live stats for the frame (`SMSG_PARTY_MEMBER_STATS`/`_FULL` — `full`
-    /// distinguishes the delta form from the ask-once full form our own
-    /// [`crate::messages::request_party_member_stats`] pulls, and the offline-miss reply).
+    /// A member's stats (`SMSG_PARTY_MEMBER_STATS`, or the asked-for `_FULL` form when `full`).
     PartyMemberStats {
         guid: u64,
         full: bool,
         info: Box<PartyMemberStatsInfo>,
     },
-    /// Someone pinged the minimap (`MSG_MINIMAP_PING`) — the group ping marker.
+    /// Someone pinged the minimap (`MSG_MINIMAP_PING`): the group ping marker.
     MinimapPing { guid: u64, x: f32, y: f32 },
-    /// One raid-target icon changed (`MSG_RAID_TARGET_UPDATE`, delta shape) — `guid == 0` clears it.
+    /// One raid-target icon changed (`MSG_RAID_TARGET_UPDATE`, delta shape); `guid == 0` clears it.
     RaidTargetSet { icon: u8, guid: u64 },
-    /// The full current raid-target icon set (`MSG_RAID_TARGET_UPDATE`, full-list shape) — only
-    /// currently-set icons are present.
+    /// The set raid-target icons (`MSG_RAID_TARGET_UPDATE`, full-list shape).
     RaidTargetList { entries: Vec<(u8, u64)> },
     /// The raid leader started a ready check (`MSG_RAID_READY_CHECK`, empty body).
     ReadyCheckRequest,
-    /// One member's ready-check answer, forwarded to the leader only (`MSG_RAID_READY_CHECK`,
-    /// non-empty body).
+    /// A member's ready-check answer, to the leader only (`MSG_RAID_READY_CHECK`, with a body).
     ReadyCheckAnswer { guid: u64, ready: u8 },
-    /// Our saved raid lockouts (`SMSG_RAID_INSTANCE_INFO`) — the Raid tab's Raid Info panel
-    /// (decision 1549). Replaces the list wholesale; empty is the normal answer.
+    /// Our saved raid lockouts (`SMSG_RAID_INSTANCE_INFO`), replacing the list; empty is normal.
     RaidInstanceInfo {
         entries: Vec<crate::messages::RaidInstanceEntry>,
     },
-    // ── The instance/raid lockout family (decision 1748) ────────────────────────────────────
-    //
-    // Four of these become a `CHAT_MSG_SYSTEM` line the client composes itself out of
-    // GlobalStrings; two are pure bookkeeping behind `CanShowResetInstances()`. The map NAME is
-    // never on the wire — the app resolves the id through `Map.dbc`.
+    // ── Instance lockouts ─────────────────────────────────────────────────────────────────
+    // Four become client-composed `CHAT_MSG_SYSTEM` lines and two feed `CanShowResetInstances()`;
+    // the map name is never on the wire, only a `Map.dbc` id.
     /// A raid lockout's welcome/countdown line (`SMSG_RAID_INSTANCE_MESSAGE`).
     RaidInstanceMessage {
         message: crate::messages::RaidInstanceMessage,
     },
-    /// We just became permanently saved to the instance we are in (`SMSG_INSTANCE_SAVE_CREATED`).
-    /// `flag` is the wire value: vmangos always sends 0, and 1 is the reference's debug wrapper.
+    /// We are now saved to this instance (`SMSG_INSTANCE_SAVE_CREATED`); vmangos always sends
+    /// `flag` 0, and 1 is the reference's debug wrapper.
     InstanceSaveCreated { flag: u32 },
-    /// An instance reset took (`SMSG_INSTANCE_RESET`) — `map` is the `Map.dbc` id.
+    /// An instance reset took (`SMSG_INSTANCE_RESET`); `map` is a `Map.dbc` id.
     InstanceReset { map: u32 },
     /// An instance reset was refused (`SMSG_INSTANCE_RESET_FAILED`).
     InstanceResetFailed {
@@ -1391,139 +942,94 @@ pub enum SessionEvent {
     UpdateLastInstance { map: u32 },
     /// Whether we hold any permanent bind (`SMSG_UPDATE_INSTANCE_OWNERSHIP`).
     UpdateInstanceOwnership { owns: bool },
-    /// A duel challenge (`SMSG_DUEL_REQUESTED`, decision 0633) — delivered to challenger and
-    /// challenged alike. `arbiter` is the duel-flag GameObject that identifies the duel and is
-    /// echoed on accept/cancel; `challenger` equal to our own guid means we are the one asking.
+    /// A duel challenge (`SMSG_DUEL_REQUESTED`), sent to both sides; `arbiter` is the flag object
+    /// echoed on accept or cancel, and `challenger` is us when we asked.
     DuelRequested { arbiter: u64, challenger: u64 },
-    /// We left the duel-flag bubble (`SMSG_DUEL_OUTOFBOUNDS`) — the 10 s forfeit timer runs.
+    /// We left the duel-flag bubble (`SMSG_DUEL_OUTOFBOUNDS`): the 10 s forfeit timer runs.
     DuelOutOfBounds,
-    /// We are back inside the bubble (`SMSG_DUEL_INBOUNDS`) — the forfeit timer is cleared.
+    /// We are back inside the bubble (`SMSG_DUEL_INBOUNDS`); the forfeit timer is cleared.
     DuelInBounds,
     /// The duel ended (`SMSG_DUEL_COMPLETE`). `started` is false only when it never began.
     DuelComplete { started: bool },
-    /// The duel's outcome line (`SMSG_DUEL_WINNER`), broadcast to everyone nearby: `fled` picks
-    /// the retreat template over the knockout one.
+    /// The duel's outcome line (`SMSG_DUEL_WINNER`), to all nearby; `fled` picks the retreat one.
     DuelWinner {
         fled: bool,
         winner: String,
         loser: String,
     },
-    /// Start the duel countdown (`SMSG_DUEL_COUNTDOWN`) — already in whole seconds.
+    /// Start the duel countdown (`SMSG_DUEL_COUNTDOWN`), already in whole seconds.
     DuelCountdown { seconds: u32 },
-    /// Another player's honor stats came back (`MSG_INSPECT_HONOR_STATS` reply, decision 1512) —
-    /// the inspect window's Honor tab. Arrives only in answer to our own ask, and a *refused* ask
-    /// is answered with silence (the server returns without sending), so a consumer must not
-    /// treat "no event yet" as "the data is coming".
+    /// Another player's honor stats (`MSG_INSPECT_HONOR_STATS`); a refused ask gets no reply.
     InspectHonorStats(InspectHonorStats),
-    /// A kill paid out honor (`SMSG_PVP_CREDIT`) — the honor-gain chat line and floating combat
-    /// text. Also fires for a **dishonorable** kill, where `honor` is negative.
+    /// A kill paid out honor (`SMSG_PVP_CREDIT`); a dishonorable kill's `honor` is negative.
     PvpCredit(PvpCredit),
-    /// One mirror timer started, or was wholly re-stated (`SMSG_START_MIRROR_TIMER`, decision
-    /// 0874) — the breath / fatigue bars. There is no separate update opcode: the server re-sends
-    /// this whole packet whenever direction, remaining time or frozen state changes, so a
-    /// consumer must treat it as idempotent re-statement, not only as a first appearance.
+    /// A breath or fatigue bar started or restated (`SMSG_START_MIRROR_TIMER`): with no update
+    /// opcode the server resends it on any change, so treat it as idempotent.
     MirrorTimerStart(MirrorTimerStart),
-    /// Freeze/unfreeze one running mirror timer (`SMSG_PAUSE_MIRROR_TIMER`). vmangos never sends
-    /// it on purpose — see [`crate::messages::opcode::SMSG_PAUSE_MIRROR_TIMER`].
+    /// Freeze or unfreeze a mirror timer (`SMSG_PAUSE_MIRROR_TIMER`). vmangos never sends it: the
+    /// stock `MirrorTimer.lua` errors on one.
     MirrorTimerPause { kind: u32, paused: bool },
-    /// One mirror timer is over (`SMSG_STOP_MIRROR_TIMER`) — hide its bar. Sent both when the
-    /// condition ends *well* (surfacing refills the bar to full, and the server stops it there)
-    /// and when it stops applying at all (death, leaving the water).
+    /// A mirror timer is over (`SMSG_STOP_MIRROR_TIMER`): refilled, or its condition ended.
     MirrorTimerStop { kind: u32 },
-    /// The whole friend list (`SMSG_FRIEND_LIST`, decision 0668) — pushed unasked at login and
-    /// again for every `CMSG_FRIEND_LIST`. Always the complete list, never a delta, so it
-    /// replaces whatever is held. Names are NOT on the wire (see [`crate::messages::social`]);
-    /// the consumer resolves them through its name cache.
+    /// The whole friend list (`SMSG_FRIEND_LIST`), replacing what is held; no names on the wire.
     FriendList { friends: Vec<FriendEntry> },
-    /// The whole ignore list (`SMSG_IGNORE_LIST`) — the same replace-everything shape, guids only.
+    /// The whole ignore list (`SMSG_IGNORE_LIST`), replacing what is held; guids only.
     IgnoreList { guids: Vec<u64> },
-    /// One friend/ignore result (`SMSG_FRIEND_STATUS`): both the ack for an add/remove **and**
-    /// the broadcast a friend's login/logout sends to everyone listing them. The
-    /// [`friend_result`](crate::messages::friend_result) code says which, and carries the
-    /// presence tail for the two online flavours.
+    /// A friend/ignore result (`SMSG_FRIEND_STATUS`): an add/remove ack or a friend's login or
+    /// logout broadcast; the [`friend_result`](crate::messages::friend_result) code says which.
     FriendStatus(FriendStatusUpdate),
-    /// A `/who` answer (`SMSG_WHO`) — at most 49 rows, plus the true match total.
+    /// A `/who` answer (`SMSG_WHO`): at most 49 rows, plus the true match total.
     WhoResults(WhoResults),
-    /// One guild's public identity (`SMSG_GUILD_QUERY_RESPONSE`) — name, its ten rank names,
-    /// tabard. The guild twin of the name query: an ask-once cache fill keyed by guild id, so a
-    /// consumer holds these by [`GuildQueryResponse::guild_id`] and a roster row or a chat line
-    /// can name its guild late rather than never.
+    /// A guild's name, ten rank names and tabard (`SMSG_GUILD_QUERY_RESPONSE`), cached by id.
     GuildQueryResponse(GuildQueryResponse),
-    /// The whole guild (`SMSG_GUILD_ROSTER`) — MOTD, info text, per-rank rights, every member.
-    /// Always a complete snapshot, never a delta, so it *replaces* whatever is held; the server
-    /// re-sends it for anything worth showing (a note edit, a rank-rights change, a promotion).
+    /// The whole guild (`SMSG_GUILD_ROSTER`), a complete snapshot that replaces what is held.
     GuildRoster(GuildRoster),
-    /// One thing that happened in the guild (`SMSG_GUILD_EVENT`) — a
-    /// [`guild_event`](crate::messages::guild_event) id plus its already-formatted arguments. The
-    /// arguments are the display text; the optional guid rides only on the sign-on/off pair.
+    /// A guild event (`SMSG_GUILD_EVENT`): a [`guild_event`](crate::messages::guild_event) id and
+    /// its display-text arguments; a guid rides only on sign-on/off.
     GuildEvent(GuildEventNotice),
-    /// The server's verdict on a guild verb we sent (`SMSG_GUILD_COMMAND_RESULT`). Carry the
-    /// command tag through to the display: it is what tells the two meanings of result `0x08`
-    /// apart (see [`guild_command_error`](crate::messages::guild_command_error)).
+    /// A guild verb's verdict (`SMSG_GUILD_COMMAND_RESULT`); its command tag tells result `0x08`'s
+    /// two meanings apart ([`guild_command_error`](crate::messages::guild_command_error)).
     GuildCommandResult(GuildCommandResult),
-    /// Somebody asked us into their guild (`SMSG_GUILD_INVITE`) — the popup. Answered with
-    /// `CMSG_GUILD_ACCEPT`/`_DECLINE`, neither of which says *which* invitation it means, so the
-    /// pending invitation is the consumer's own state.
+    /// A guild invite (`SMSG_GUILD_INVITE`); `CMSG_GUILD_ACCEPT`/`_DECLINE` do not name it.
     GuildInvite { inviter: String, guild: String },
-    /// The player we invited turned it down (`SMSG_GUILD_DECLINE`) — delivered to the inviter only.
+    /// The player we invited declined (`SMSG_GUILD_DECLINE`), sent to the inviter only.
     GuildDecline { name: String },
-    /// The guild's "founded on / N members / N accounts" summary (`SMSG_GUILD_INFO`) — a separate
-    /// ask from the roster, sharing no fields with it.
+    /// The guild's founding date, member and account counts (`SMSG_GUILD_INFO`).
     GuildInfo(GuildInfo),
-    /// A guild registrar's charter list (`SMSG_PETITION_SHOWLIST`) — what opens the registrar
-    /// window. Always one row at 1.12; `npc` is the registrar every later verb names.
+    /// A registrar's charter list (`SMSG_PETITION_SHOWLIST`), opening its window; one row in 1.12.
     PetitionShowList(PetitionShowList),
-    /// Who has signed a charter (`SMSG_PETITION_SHOW_SIGNATURES`). **Two meanings in one packet**:
-    /// the answer to our own ask, or somebody offering us theirs — a consumer tells them apart by
-    /// whether `owner` is us, and nothing else does.
-    ///
-    /// It carries neither the proposed guild's name nor the signature requirement. Those live only
-    /// on [`Self::PetitionQueryResponse`], keyed by `petition_id` — the same two-caches shape the
-    /// guild roster has with [`Self::GuildQueryResponse`].
+    /// A charter's signers (`SMSG_PETITION_SHOW_SIGNATURES`): our own ask or an offer to sign, told
+    /// apart only by whether `owner` is us; name and requirement are in the petition query.
     PetitionShowSignatures(PetitionShowSignatures),
-    /// The verdict on one signature (`SMSG_PETITION_SIGN_RESULTS`). Sent to **both** the signer and
-    /// the charter's owner on success, and both copies name the *signer*, so a consumer cannot tell
-    /// which copy it holds from the packet alone.
+    /// A signature's verdict (`SMSG_PETITION_SIGN_RESULTS`); on success signer and owner each get
+    /// a copy naming the signer, the same bytes.
     PetitionSignResults(PetitionSignResults),
-    /// A petition's record (`SMSG_PETITION_QUERY_RESPONSE`) — the proposed guild name and the
-    /// signature requirement. The lazy cache fill behind the charter window's title.
+    /// A petition's guild name and signature requirement (`SMSG_PETITION_QUERY_RESPONSE`).
     PetitionQueryResponse(PetitionQueryResponse),
-    /// The verdict on a turn-in (`SMSG_TURN_IN_PETITION_RESULTS`) — a bare code, with no charter
-    /// named. **Silence is a real outcome**: a name collision answers with an
-    /// [`Self::GuildCommandResult`] and no results packet at all.
+    /// A turn-in's bare code (`SMSG_TURN_IN_PETITION_RESULTS`); a name collision sends only a
+    /// [`Self::GuildCommandResult`].
     TurnInPetitionResults { result: u32 },
-    /// Somebody declined our charter (`MSG_PETITION_DECLINE`) — their guid, delivered to the
-    /// charter's owner only.
+    /// Somebody declined our charter (`MSG_PETITION_DECLINE`), sent to the owner only.
     PetitionDeclined { player: u64 },
-    /// A charter rename that took (`MSG_PETITION_RENAME`) — the server's echo, sent only on
-    /// success. A rejected name arrives as a [`Self::GuildCommandResult`] instead.
+    /// A charter rename took (`MSG_PETITION_RENAME`); a rejected one is a guild command result.
     PetitionRenamed(PetitionRename),
-    /// The taxi map (`SMSG_SHOWTAXINODES`, decision 0484): `flightmaster` is the NPC the menu
-    /// opened on, `nearest_node` the node it sits at, `known_mask` the full known-node bitmask
-    /// ([`TaxiMask::is_known`]). The wire's window-framing constant carries no state and is
-    /// dropped here.
+    /// The taxi map (`SMSG_SHOWTAXINODES`); `nearest_node` is the flight master's own node.
     TaxiNodesShown {
         flightmaster: u64,
         nearest_node: u32,
         known_mask: TaxiMask,
     },
-    /// A taxi node's known status (`SMSG_TAXINODE_STATUS`) — answers
-    /// `CMSG_TAXINODE_STATUS_QUERY`, and also rides a first-visit "learn" alongside
-    /// [`Self::NewTaxiPath`] (vmangos `SendLearnNewTaxiNode`). `guid` names the flight master
-    /// asked about; `known` is whether the nearest node to it is now in our taxi mask.
+    /// Whether the flight master's nearest node is known (`SMSG_TAXINODE_STATUS`); also sent with
+    /// [`Self::NewTaxiPath`] on a first visit (vmangos `SendLearnNewTaxiNode`).
     TaxiNodeStatus { guid: u64, known: bool },
-    /// The server's verdict on `CMSG_ACTIVATETAXI`/`CMSG_ACTIVATETAXIEXPRESS`
-    /// (`SMSG_ACTIVATETAXIREPLY`): `code` is a [`crate::messages::taxi_reply`] value — `0` OK,
-    /// everything else a refusal (no flight starts, and no mount/spline packets follow).
+    /// A flight request's verdict (`SMSG_ACTIVATETAXIREPLY`), a [`crate::messages::taxi_reply`]:
+    /// 0 is OK; a refusal starts no flight and sends no mount or spline.
     ActivateTaxiReply { code: u32 },
-    /// `SMSG_NEW_TAXI_PATH` — empty body, rides a first-visit "learn" alongside
-    /// [`Self::TaxiNodeStatus`]. No payload to carry; modelled so the wire isn't silently dropped.
+    /// `SMSG_NEW_TAXI_PATH`, empty, sent with [`Self::TaxiNodeStatus`] on a first visit.
     NewTaxiPath,
-    /// `SMSG_MAIL_LIST_RESULT` — the inbox page, answering `CMSG_GET_MAIL_LIST` (decision 0544
-    /// P0's wire layer; the inbox/open-mail window is P1).
+    /// The inbox (`SMSG_MAIL_LIST_RESULT`), answering `CMSG_GET_MAIL_LIST`.
     MailList { mails: Vec<MailListEntry> },
-    /// `SMSG_SEND_MAIL_RESULT` — the verdict on a send/take-money/take-item/return/delete action;
-    /// `equip_error`/`item` are the two mutually-exclusive conditional tails (decision 0544).
+    /// A mail action's verdict (`SMSG_SEND_MAIL_RESULT`); `equip_error`/`item` are exclusive tails.
     SendMailResult {
         mail_id: u32,
         action: u32,
@@ -1531,85 +1037,63 @@ pub enum SessionEvent {
         equip_error: Option<u32>,
         item: Option<(u32, u32)>,
     },
-    /// `SMSG_PAGE_TEXT_QUERY_RESPONSE` — one page of a book, answering `CMSG_PAGE_TEXT_QUERY`.
-    /// The ask-once page cache both readables reach: a readable item template's `PageText` and a
-    /// `GAMEOBJECT_TYPE_TEXT` object's `data[0]` (decision 1105). `next_page_id == 0` ends the
-    /// chain; vmangos pushes the whole chain in answer to the first query.
+    /// One book page (`SMSG_PAGE_TEXT_QUERY_RESPONSE`), for items and `GAMEOBJECT_TYPE_TEXT`;
+    /// `next_page_id == 0` ends it, and vmangos pushes the whole chain on the first query.
     PageText {
         page_id: u32,
         text: String,
         next_page_id: u32,
     },
-    /// `SMSG_ITEM_TEXT_QUERY_RESPONSE` — a letter's body text, answering `CMSG_ITEM_TEXT_QUERY`
-    /// (a mail's nonzero `item_text_id` triggers the ask-once fetch; decision 0544).
+    /// A letter's body (`SMSG_ITEM_TEXT_QUERY_RESPONSE`), for a mail's non-zero `item_text_id`.
     MailItemText { text_id: u32, text: String },
-    /// `SMSG_RECEIVED_MAIL` — a mail arrived (instant for text-only, on the delivery timer's
-    /// expiry otherwise). `seconds` is the delay until it is "waiting", in the pending-mail
-    /// countdown's units (vmangos only ever sends `0.0` = now; decision 0913).
+    /// A mail arrived (`SMSG_RECEIVED_MAIL`); `seconds` of delay, always `0.0` from vmangos.
     ReceivedMail { seconds: f32 },
-    /// `MSG_QUERY_NEXT_MAIL_TIME`'s reply (same opcode as our empty-body request): `0.0` = unread
-    /// mail waiting, `-86400.0` = none. Drives `HasNewMail()`/`UPDATE_PENDING_MAIL` (decision 0544
-    /// P3).
+    /// `MSG_QUERY_NEXT_MAIL_TIME`'s reply: `0.0` unread mail, `-86400.0` none; for `HasNewMail()`.
     NextMailTime { seconds: f32 },
-    /// `MSG_AUCTION_HELLO`'s reply — the auctioneer we greeted plus its `AuctionHouse.dbc` row
-    /// (1..7, the deposit/cut rates). This packet, not our send, is what opens the auction window
-    /// (decision 1511 P0's wire layer; the window itself is a later phase).
+    /// `MSG_AUCTION_HELLO`'s reply, which opens the auction window: the auctioneer and its
+    /// `AuctionHouse.dbc` row (1..7, the deposit and cut rates).
     AuctionHello { auctioneer: u64, house_id: u32 },
-    /// `SMSG_AUCTION_COMMAND_RESULT` — the verdict on a sell/cancel/bid, keyed by `action`
-    /// ([`crate::messages::auction_action`]) and `error` ([`crate::messages::auction_error`]);
-    /// `tail` is the conditional payload the error selects. `auction_id` is `0` on most failures,
-    /// and several refusals send no packet at all (decision 1511).
+    /// A sell, cancel or bid verdict (`SMSG_AUCTION_COMMAND_RESULT`); `error` selects `tail`,
+    /// `auction_id` is 0 on most failures, and several refusals send nothing.
     AuctionCommandResult {
         auction_id: u32,
         action: u32,
         error: u32,
         tail: AuctionCommandTail,
     },
-    /// `SMSG_AUCTION_LIST_RESULT` — a Browse page (max 50 rows). `total_count` is the pre-cap
-    /// match count the pager needs, and it rides at the END of the wire body.
+    /// A Browse page (`SMSG_AUCTION_LIST_RESULT`), at most 50 rows; `total_count` is pre-cap.
     AuctionListResult {
         auctions: Vec<AuctionListEntry>,
         total_count: u32,
     },
-    /// `SMSG_AUCTION_OWNER_LIST_RESULT` — the Auctions tab page (our own listings). Same frame
-    /// and record as [`Self::AuctionListResult`].
+    /// The Auctions tab page, our own listings (`SMSG_AUCTION_OWNER_LIST_RESULT`).
     AuctionOwnerListResult {
         auctions: Vec<AuctionListEntry>,
         total_count: u32,
     },
-    /// `SMSG_AUCTION_BIDDER_LIST_RESULT` — the Bid tab page. Same frame and record as
-    /// [`Self::AuctionListResult`]; the server emits the explicitly-refreshed ids first and then
-    /// our live bids, so one row can appear twice in a page.
+    /// The Bids tab page (`SMSG_AUCTION_BIDDER_LIST_RESULT`): refreshed ids first, then live bids,
+    /// so a row can appear twice.
     AuctionBidderListResult {
         auctions: Vec<AuctionListEntry>,
         total_count: u32,
     },
-    /// `SMSG_AUCTION_BIDDER_NOTIFICATION` — we won, or we were outbid (`bid_or_zero == 0` means
-    /// **won**, not "no bid").
+    /// We won or were outbid (`SMSG_AUCTION_BIDDER_NOTIFICATION`); `bid_or_zero == 0` means won.
     AuctionBidderNotification(AuctionBidderNotification),
-    /// `SMSG_AUCTION_OWNER_NOTIFICATION` — our own auction sold or took a bid. A deliberately
-    /// different shape from the bidder notice: no house id, guid fourth, and an all-zero
-    /// `bidder_guid` is the "sold" signal.
+    /// Our auction sold or took a bid (`SMSG_AUCTION_OWNER_NOTIFICATION`); `bidder_guid` 0 is sold.
     AuctionOwnerNotification(AuctionOwnerNotification),
-    /// `SMSG_AUCTION_REMOVED_NOTIFICATION` — an auction we had bid on was cancelled by its seller.
+    /// The seller cancelled an auction we bid on (`SMSG_AUCTION_REMOVED_NOTIFICATION`).
     AuctionRemovedNotification {
         auction_id: u32,
         item_entry: u32,
         random_property_id: i32,
     },
-    /// `SMSG_TRADE_STATUS` — one pulse of the player-trade state machine (open/accept/cancel/
-    /// complete + the refusal reasons). The app drives the trade window and the auto-`BEGIN_TRADE`
-    /// reply off this (decision 0592; the window itself is P1).
+    /// One step of the trade state machine (`SMSG_TRADE_STATUS`), refusals included.
     TradeStatus { status: TradeStatus },
-    /// `SMSG_TRADE_STATUS_EXTENDED` — the item/gold snapshot for one window side (our own or the
-    /// partner's, per [`TradeStatusExtended::their_window`]); pushed whenever that side changes.
-    /// Boxed (~460 bytes) so it doesn't bloat every `SessionEvent`.
+    /// One trade side's items and gold (`SMSG_TRADE_STATUS_EXTENDED`), boxed at about 460 bytes.
     TradeStatusExtended { state: Box<TradeStatusExtended> },
-    /// The world-state table changed. `SMSG_INIT_WORLD_STATES` carries the whole table for a zone
-    /// (`states` is the wire run verbatim, terminator pair included); `SMSG_UPDATE_WORLD_STATE`
-    /// arrives as a one-entry `states` with `scope: None`, so both wires land on one event and the
-    /// app has a single write path — the reference likewise funnels both into the one setter.
-    /// `scope` is the init packet's `(map, zone)` dwords; nothing consumes them yet.
+    /// World states: `SMSG_INIT_WORLD_STATES` with its `(map, zone)` scope and the wire run
+    /// verbatim, terminator included, or `SMSG_UPDATE_WORLD_STATE` as one entry with no scope.
+    /// The reference funnels both into one setter too.
     WorldStates {
         scope: Option<(u32, u32)>,
         states: Vec<(u32, u32)>,
@@ -1617,7 +1101,7 @@ pub enum SessionEvent {
 }
 
 impl SessionEventKind {
-    /// Every kind, in declaration order — for a census that asks "who handles each?".
+    /// Every kind, in declaration order.
     pub fn all() -> impl Iterator<Item = Self> {
         <Self as strum::IntoEnumIterator>::iter()
     }
@@ -1625,26 +1109,14 @@ impl SessionEventKind {
 
 /// The result of polling the reader for the next packet's events.
 pub enum Poll {
-    /// A packet decoded into these events. `events` is **empty** for an opcode we parse but do not
-    /// model — a third outcome, distinct from both "decoded into something" and [`Poll::Skipped`],
-    /// and until decision 0624 it was invisible from outside: no event, no skip, and the inbound
-    /// census counted it like any other packet. A relayed move landing in an unmodelled opcode was
-    /// therefore indistinguishable from one that never arrived. `opcode` rides along so the net
-    /// thread can name what actually came off the wire.
-    ///
-    /// `tail` is how many body bytes the decoder left unconsumed
-    /// ([`crate::messages::parse_server_with_tail`]): a length-framed body lets a decoder shorter
-    /// than the server's layout succeed silently, and this is the one number that shows it. An
-    /// instrument, not a verdict — the packet decoded, its events are real, and the tail is
-    /// announced (once per opcode) rather than turned into a [`Poll::Skipped`].
+    /// A decoded packet; `events` is empty for an opcode parsed but not modelled. `tail` counts
+    /// body bytes left unread, which shows a decoder shorter than the server's layout.
     Events {
         opcode: u16,
         events: Vec<SessionEvent>,
         tail: usize,
     },
-    /// An unparseable packet was skipped — kept the stream aligned, not an error. Carries the
-    /// opcode (for the app's dropped-packet tally) and a short description (opcode + error + a hex
-    /// preview) so the net thread can log *which* packet was dropped.
+    /// An unparseable packet, skipped to keep the stream aligned; `reason` has a hex preview.
     Skipped { opcode: u16, reason: String },
 }
 
diff --git a/crates/benilla-protocol/src/events/decode.rs b/crates/benilla-protocol/src/events/decode.rs
index df2fa473..77473b8d 100644
--- a/crates/benilla-protocol/src/events/decode.rs
+++ b/crates/benilla-protocol/src/events/decode.rs
@@ -1,6 +1,4 @@
-//! The [`ServerPacket`]→[`SessionEvent`] mapping: [`decode`]'s per-packet fan-out plus the
-//! object-list interpretation ([`decode_objects`] and the spawn-identity readers). Pure functions
-//! of the packet — no I/O, no state; the running world model stays the app's.
+//! The [`ServerPacket`] to [`SessionEvent`] mapping: pure functions of the packet, no state.
 
 use crate::messages::{CastOutcome, MovementBlock, Object, ObjectFields, ObjectType, ServerPacket};
 use crate::wire::Vector3d;
@@ -11,32 +9,10 @@ fn v3(v: Vector3d) -> [f32; 3] {
     [v.x, v.y, v.z]
 }
 
-/// **Who cast it** — the caster slot of `SMSG_SPELL_START`/`SMSG_SPELL_GO`, corrected for the one
-/// case where vmangos leaves that slot EMPTY.
-///
-/// Both packets carry a guid pair: slot 1 is *the cast item's guid when one is in play, else the
-/// caster's own* (`WriteGuidHelper(data, m_CastItem)` / `else … m_caster`, `Spell.cpp:4475-4477` and
-/// `4509-4511`), slot 2 is the caster. But slot 2 is written from **`m_casterUnit`**
-/// (`Spell.cpp:4479`, `Spell.cpp:4513`) — and `m_casterUnit` is a `Unit*` that the GameObject
-/// constructor never sets: `Spell::Spell(GameObject*, …)` initialises `m_caster(caster),
-/// m_casterGo(caster)` and leaves the default `Unit* const m_casterUnit = nullptr` (`Spell.cpp:102`,
-/// `Spell.h:368`) standing. `WriteGuidHelper(data, nullptr)` writes `ObjectGuid().WriteAsPacked()`
-/// (`Spell.cpp:4441-4453`) — a lone zero mask byte — so **every spell a GameObject casts arrives
-/// with caster guid 0**.
-///
-/// That is not a rare shape. `GameObject::Use` keeps `WorldObject* spellCaster = this` for a
-/// `GAMEOBJECT_TYPE_SPELLCASTER` (22) and casts through the GameObject overload
-/// (`GameObject.cpp`, `spellCaster->ToGameObject()` → `new Spell(pGo, …)`): the Priest's
-/// **Lightwell** (GO 181102, spell 7001 "Lightwell Renew" on the clicker) is the canonical one, and
-/// a guid the index can never hold cost that cast its whole visual body — the impact kit, its sound
-/// and its effect model — because [`crate::events::SessionEvent::SpellGo`]'s consumer resolves the
-/// caster before it plays anything. Slot 1 already carries the answer whenever slot 2 is empty:
-/// with no cast item it IS `m_caster`, GameObject included. So an empty caster slot falls back to
-/// it, which also stops the object being mistaken for a **cast item** by the `item_caster`
-/// derivation below (they are equal, so nothing is derived).
-///
-/// A Unit caster can never reach this: `Spell::Spell(Unit*, …)` sets `m_casterUnit(caster)`
-/// (`Spell.cpp:60`) and a live `Unit*` has a non-zero guid.
+/// The caster of `SMSG_SPELL_START`/`SMSG_SPELL_GO`. vmangos writes the caster slot from
+/// `m_casterUnit`, null for a GameObject caster (`Spell.cpp:102`, `Spell.cpp:4479`), so a
+/// GameObject's spell (Lightwell, GO 181102) arrives as 0; the first slot then holds the caster
+/// itself, as it does whenever no item is cast (`Spell.cpp:4475-4477`).
 fn spell_caster(item_or_caster: u64, caster_slot: u64) -> u64 {
     if caster_slot == 0 {
         item_or_caster
@@ -45,14 +21,12 @@ fn spell_caster(item_or_caster: u64, caster_slot: u64) -> u64 {
     }
 }
 
-/// Decode one server packet into zero or more [`SessionEvent`]s. Pure: no I/O, no state. Packets the
-/// client doesn't model yield an empty list.
+/// Decode one server packet into zero or more [`SessionEvent`]s. No wildcard arm: a new
+/// `ServerPacket` variant must be a compile error here, never a silent no-op.
 pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
     match packet {
         ServerPacket::UpdateObject { objects } => decode_objects(objects),
-        // A batch is only a transport: unwrap it in order and decode each move exactly as if it had
-        // arrived on its own (decision 0624). Order matters — the replay queue in
-        // `net::motion` reconstructs a mover's arc from packet order.
+        // In order, each move as if alone: the app rebuilds a mover's arc from packet order.
         ServerPacket::CompressedMoves { packets } => packets.into_iter().flat_map(decode).collect(),
         ServerPacket::CharEnum { characters } => vec![SessionEvent::CharacterList {
             characters,
@@ -214,6 +188,8 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
                 bag_slot,
             }]
         }
+        // Reason 0 is `EQUIP_ERR_OK`, which vmangos sends too (`Player.cpp:11688`): no failure.
+        ServerPacket::InventoryChangeFailure { .. } => Vec::new(),
         ServerPacket::AttackStart { attacker, victim } => {
             vec![SessionEvent::AttackStart { attacker, victim }]
         }
@@ -247,9 +223,7 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
                 go_target: s.targets.go_target,
                 dest: s.targets.dest.map(|d| [d.x, d.y, d.z]),
                 ammo_display_id: s.ammo_display_id,
-                // Against the RESOLVED caster, not the raw slot: a GameObject's cast puts its own
-                // guid in slot 1, and comparing that with the empty slot 2 would label the object
-                // an item and route the cast down the item-use lane.
+                // Against the resolved caster: a GameObject's own guid in slot 1 is not an item.
                 item_caster: (s.item_or_caster != caster).then_some(s.item_or_caster),
             }]
         }
@@ -367,7 +341,7 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
             entry,
             count,
             required,
-            guid: _, // the killed unit's guid — no consumer (the toast keys on the entry)
+            guid: _, // the killed unit; the toast keys on the entry
         } => vec![SessionEvent::QuestObjectiveKill {
             quest_id,
             entry,
@@ -600,8 +574,7 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
             arbiter,
             challenger,
         }],
-        // The instance/raid lockout family (decision 1748) — straight relays; the ownership flag
-        // is narrowed to a bool here because the reference's own reader is a `test eax,eax`.
+        // Lockouts; ownership narrows to a bool: the reference reads it with `test eax,eax`.
         ServerPacket::RaidInstanceMessage { message } => {
             vec![SessionEvent::RaidInstanceMessage { message }]
         }
@@ -878,16 +851,10 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
             ) = match info {
                 Some(i) => (
                     Some(i.name),
-                    // An EMPTY wire subname is NO subname (vmangos sends "" for creatures
-                    // without one; the client renders no line for it — the nameplate
-                    // builder's verified shape, 0x608f50). Mapped here, once, so no consumer
-                    // ever sees a present-but-empty tooltip/nameplate line.
+                    // An empty subname is none: the reference draws no line for it (`0x608f50`).
                     Some(i.subname).filter(|s| !s.is_empty()),
                     Some(i.creature_type),
-                    // NOT wrapped in an `Option` like the type beside it: family `0` already
-                    // means "this template has no family", which is exactly what a miss means
-                    // too, so both answer the same `0` rather than two shapes for one state
-                    // (`CreatureFamily.dbc` has no row 0 — decision 1062).
+                    // Not an `Option`: `CreatureFamily.dbc` has no row 0, so 0 means none.
                     i.pet_family,
                     i.rank,
                     i.type_flags,
@@ -944,10 +911,15 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
         ServerPacket::GameObjectDespawnAnim { guid } => {
             vec![SessionEvent::GameObjectDespawnAnim { guid }]
         }
+        ServerPacket::OpenContainer { item } => vec![SessionEvent::OpenContainer { item }],
+        ServerPacket::StandStateUpdate { state } => {
+            vec![SessionEvent::StandStateUpdate { state }]
+        }
+        // Nothing: the reference's `0x5e7d70` discards the echoed guid, and the inspect window
+        // reads the target's `PLAYER_VISIBLE_ITEM_*` fields. Parsed so no tally calls it dropped.
+        ServerPacket::Inspect { .. } => Vec::new(),
         ServerPacket::FishNotHooked => vec![SessionEvent::FishNotHooked],
         ServerPacket::FishEscaped => vec![SessionEvent::FishEscaped],
-        // The keepalive echo: the io layer matches the sequence against its ping clock to compute
-        // the round-trip time (the codec is stateless, so the timing lives with the sender).
         ServerPacket::Pong { sequence } => vec![SessionEvent::Pong { sequence }],
         ServerPacket::ForceSpeedChange {
             guid,
@@ -963,9 +935,7 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
         ServerPacket::SplineSpeedChange { guid, kind, speed } => {
             vec![SessionEvent::SpeedChanged { guid, kind, speed }]
         }
-        // The MOVE_SET flavour is a speed change AND a fresh authoritative pose in one packet
-        // (decision 0441) — surface both; they land in the same drain, so extrapolation resumes
-        // from the new pose at the new speed either way.
+        // `MSG_MOVE_SET_*_SPEED` is a speed and a fresh pose: emit both, for the same drain.
         ServerPacket::MoveSetSpeed {
             guid,
             kind,
@@ -986,8 +956,7 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
                 flags,
                 pitch,
                 time,
-                // A speed change carries a fresh pose, and nothing more: the opcode's meaning is
-                // the speed, which rides its own event beside this one.
+                // The opcode's meaning is the speed, carried by its own event: the pose is plain.
                 verb: crate::messages::RelayVerb::Pose,
                 fall_time,
                 jump,
@@ -1010,8 +979,7 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
             nearest_node,
             known,
         } => {
-            // The leading word is the client parser's own conditional gate (0496 §claim-1): a
-            // zero-gated body carries no menu — no event. vmangos always sends 1.
+            // The reference parser gates on this word: zero carries no menu; vmangos sends 1.
             if window == 0 {
                 vec![]
             } else {
@@ -1116,20 +1084,21 @@ pub fn decode(packet: ServerPacket) -> Vec<SessionEvent> {
             scope: None,
             states: vec![(id, value)],
         }],
-        // An opcode with NO parse arm at all — surface it so the app can tally the coverage gap
-        // (the debug panel's dropped-opcode instrument); the silent fall-through hid whole wire
-        // families. Parsed-but-unmodelled packets (the `_` below) stay deliberate no-ops.
+        // No parse arm at all: surfaced for the app's dropped-opcode tally.
         ServerPacket::Other { opcode } => vec![SessionEvent::PacketDropped {
             opcode,
             unparseable: false,
         }],
-        _ => Vec::new(),
+        // Handshake-only: `world::session` consumes these before the world loop reaches here.
+        ServerPacket::AuthChallenge { .. }
+        | ServerPacket::AuthResponse { .. }
+        | ServerPacket::CharCreate { .. }
+        | ServerPacket::CharDelete { .. }
+        | ServerPacket::AddonInfo { .. } => Vec::new(),
     }
 }
 
-/// Fan one object-update packet's object list out into create/move/remove/values events. Consumes the
-/// list so each object's descriptor `mask` moves into its event as the ECS store seed/delta (decision
-/// 0061) — no clone.
+/// Fan an object-update list out into create/move/remove/values events, moving each mask.
 fn decode_objects(objects: Vec<Object>) -> Vec<SessionEvent> {
     let mut out = Vec::new();
     for object in objects {
@@ -1140,9 +1109,7 @@ fn decode_objects(objects: Vec<Object>) -> Vec<SessionEvent> {
                 movement,
                 mask,
             } => {
-                // Items/containers are descriptor-only creates — no pose to interpret, no scene
-                // presence. Route them whole into the item event before the placement gate below
-                // (which would otherwise silently drop a position-less create, fields and all).
+                // Items have no pose: route them before the placement gate, which would drop them.
                 if matches!(object_type, ObjectType::Item | ObjectType::Container) {
                     out.push(SessionEvent::ItemCreate {
                         guid,
@@ -1151,8 +1118,6 @@ fn decode_objects(objects: Vec<Object>) -> Vec<SessionEvent> {
                     });
                     continue;
                 }
-                // Interpret the spawn identity + placement from the mask (borrow), then move the whole
-                // mask into the create event as the object's initial descriptor store.
                 if let Some((position, orientation)) =
                     create_placement(object_type, &mask, &movement)
                 {
@@ -1187,9 +1152,7 @@ fn decode_objects(objects: Vec<Object>) -> Vec<SessionEvent> {
             Object::OutOfRange { guids } => {
                 out.push(SessionEvent::ObjectsRemoved(guids));
             }
-            // `Values` carries UpdateFields-only changes (no position) — descriptor deltas (health on a
-            // hit, an appearance byte, a door's state). Emit the whole non-empty delta for the ECS to
-            // merge into the object's store; interpretation is the consumer's, per named accessor.
+            // `Values`: a descriptor delta with no position.
             Object::Values { guid, mask } => {
                 if !mask.is_empty() {
                     out.push(SessionEvent::ObjectValues { guid, fields: mask });
@@ -1202,7 +1165,6 @@ fn decode_objects(objects: Vec<Object>) -> Vec<SessionEvent> {
     out
 }
 
-/// Coarse classification of a decoded object from its `TypeId`.
 fn entity_kind(t: ObjectType) -> EntityKind {
     match t {
         ObjectType::Player => EntityKind::Player,
@@ -1214,21 +1176,10 @@ fn entity_kind(t: ObjectType) -> EntityKind {
     }
 }
 
-/// The display id from a create packet — units, **players**, GameObjects **and corpses** all carry
-/// one. A player's body model resolves through the same CreatureDisplayInfo→CreatureModelData chain
-/// as a creature's: the 1.12 client has no race/sex→path resolver, CGPlayer inherits CGUnit's
-/// displayId model-build (decision 0041), so we route `Player` alongside `Unit`. A corpse's
-/// `CORPSE_FIELD_DISPLAY_ID` is the dead player's own body display (vmangos writes
-/// `GetNativeDisplayId()` straight in), so it resolves down that identical chain — the reference's
-/// `0x5d6700` does exactly this lookup (decision 1706).
-///
-/// **A bone pile's display id is deliberately still reported here.** The client ignores it (it
-/// builds `<Race><Sex>DeathSkeleton` from the BYTES instead), but that is a *model-resolution* law,
-/// not a wire fact — the field is present and it is what it is, and the fork lives where models are
-/// resolved (`entities::corpse`). Reporting `None` here would also blind the live-display differ to
-/// a flesh→bones flag flip, which the reference reacts to with a full model reload.
-///
-/// Cast from the wire `i32`; `0`/absent → `None`.
+/// A create's display id. A player resolves like a unit (the 1.12 client's `CGPlayer` inherits
+/// `CGUnit`'s display build); a corpse's is the player's native display (reference: `0x5d6700`).
+/// A bone pile's id is still reported: `entities::corpse` swaps in `<Race><Sex>DeathSkeleton`,
+/// and `None` would hide the flesh-to-bones flip the reference reloads the model on.
 fn display_id(t: ObjectType, mask: &ObjectFields) -> Option<u32> {
     match t {
         ObjectType::Unit | ObjectType::Player => {
@@ -1243,17 +1194,11 @@ fn display_id(t: ObjectType, mask: &ObjectFields) -> Option<u32> {
     }
 }
 
-/// The per-object scale (`OBJECT_FIELD_SCALE_X`) units/players/GameObjects carry — the *complete*
-/// render scale that multiplies the raw model's native size. The real client sizes any object by this
-/// field alone (verified `world_model_scale` `0x613ef0`); for a unit the server has already folded the
-/// CreatureDisplayInfo/CreatureModelData scale into it (vmangos `Unit::GetScaleForDisplayId`), so it is
-/// *not* multiplied again client-side. Defaults to `1.0` when absent or non-positive (the server always
-/// sends a positive value on create).
+/// `OBJECT_FIELD_SCALE_X`, the complete render scale: the reference sizes by it alone (`0x613ef0`),
+/// and vmangos already folds the display scale in (`Unit::GetScaleForDisplayId`).
 fn object_scale(t: ObjectType, mask: &ObjectFields) -> f32 {
     let raw = match t {
-        // A corpse joins them: `OBJECT_FIELD_SCALE_X` is an OBJECT-block field and vmangos sets it
-        // (`Corpse::Create` → `SetObjectScale(DEFAULT_OBJECT_SCALE)`), so the same one-field law
-        // sizes it (decision 1706).
+        // vmangos sets a corpse's scale too (`Corpse::Create` → `SetObjectScale`).
         ObjectType::Unit | ObjectType::Player | ObjectType::GameObject | ObjectType::Corpse => {
             mask.object_scale_x()
         }
@@ -1262,17 +1207,9 @@ fn object_scale(t: ObjectType, mask: &ObjectFields) -> f32 {
     raw.filter(|s| *s > 0.0).unwrap_or(1.0)
 }
 
-/// Where a freshly-created object sits: GameObjects from UpdateFields (`GAMEOBJECT_POS_*`) — falling
-/// back to the movement block's `HAS_POSITION` pose when those fields were never sent at all — everything
-/// else straight from the movement block.
-///
-/// The fallback exists for transports: vmangos never sets `GAMEOBJECT_POS_*` on a boat/zeppelin/elevator
-/// (it sends the stationary spawn point in the movement block's `HAS_POSITION` slot instead — decision
-/// 0438 "the wire"). Gated on [`ObjectFields::gameobject_pos_sent`] rather than
-/// `gameobject_position().or(..)`: a create block's absent-is-zero fold
-/// (`ObjectFields`'s "created" semantics) means `gameobject_position()` reads `Some((0,0,0), 0)` even
-/// when nothing was sent, so a plain `.or` never falls through. An ordinary GameObject sends at least
-/// one non-zero `GAMEOBJECT_POS_*` axis virtually always, so this never changes its placement.
+/// A create's pose: a GameObject's `GAMEOBJECT_POS_*` when sent, else the movement block, since
+/// vmangos never sets those fields on a transport. Gate on `gameobject_pos_sent`, not `.or`: a
+/// create reads absent fields as zero, so `gameobject_position()` is `Some` even when unsent.
 fn create_placement(
     object_type: ObjectType,
     mask: &ObjectFields,
diff --git a/crates/benilla-protocol/src/guid.rs b/crates/benilla-protocol/src/guid.rs
index 9c16e366..9c64f84d 100644
--- a/crates/benilla-protocol/src/guid.rs
+++ b/crates/benilla-protocol/src/guid.rs
@@ -1,73 +1,53 @@
-//! GUID bit-layout decode for 1.12.1 — the wire's object identity, `[high:16][entry:24][counter:24]`
-//! for entry-carrying types and `[high:16][counter:48-usable-as-32]` for the rest (VERIFIED vmangos
-//! `ObjectGuid.h`: `GetHigh` = bits 48–63, `GetEntry` = bits 24–47 masked to 24 bits, gated on the
-//! high value carrying an entry at all).
-//!
-//! The one load-bearing consumer today: `CMSG_CREATURE_QUERY` wants the creature's **template entry**,
-//! which the client recovers from the guid exactly this way — the u64→entry extraction is the same
-//! stable bijection decision 0068's mapping layer relies on for modern string GUIDs later.
+//! The 1.12.1 guid bit layout (vmangos `ObjectGuid.h`): `[high:16][entry:24][counter:24]` for
+//! the families that carry a template entry, `[high:16][counter:48]` (32 bits used) for the rest.
 
-/// `HIGHGUID_PLAYER` — a player character's guid high part.
+/// `HIGHGUID_PLAYER`.
 pub const HIGH_PLAYER: u16 = 0x0000;
-/// `HIGHGUID_ITEM` == `HIGHGUID_CONTAINER` — items and bags share the marker (a bag *is* an item).
+/// `HIGHGUID_ITEM`, which is also `HIGHGUID_CONTAINER`: a bag is an item.
 pub const HIGH_ITEM: u16 = 0x4000;
 /// `HIGHGUID_GAMEOBJECT`.
 pub const HIGH_GAMEOBJECT: u16 = 0xF110;
-/// `HIGHGUID_UNIT` — a spawned creature.
+/// `HIGHGUID_UNIT`: a spawned creature.
 pub const HIGH_UNIT: u16 = 0xF130;
 /// `HIGHGUID_PET`.
 pub const HIGH_PET: u16 = 0xF140;
-/// `HIGHGUID_MO_TRANSPORT` — a boat/zeppelin (`GAMEOBJECT_TYPE_MO_TRANSPORT`, template type 15): the
-/// WMO-modeled transports that sail scripted taxi-path routes. VERIFIED vmangos `ObjectGuid.h:77`.
+/// `HIGHGUID_MO_TRANSPORT` (`ObjectGuid.h:77`): a boat or zeppelin, gameobject type 15.
 pub const HIGH_MO_TRANSPORT: u16 = 0x1FC0;
-/// `HIGHGUID_TRANSPORT` — an elevator (`GAMEOBJECT_TYPE_TRANSPORT`, template type 11): the M2-modeled,
-/// `TransportAnimation.dbc`-driven lifts. VERIFIED vmangos `ObjectGuid.h:72`.
+/// `HIGHGUID_TRANSPORT` (`ObjectGuid.h:72`): an elevator, gameobject type 11.
 pub const HIGH_TRANSPORT: u16 = 0xF120;
 
-/// The guid's high 16 bits (`GetHigh`, vmangos `ObjectGuid.h`) — the object-family tag.
+/// The high 16 bits, the object-family tag (`GetHigh`).
 pub fn high(guid: u64) -> u16 {
     ((guid >> 48) & 0xFFFF) as u16
 }
 
-/// A (non-zero) player-character guid.
+/// A non-zero player-character guid.
 pub fn is_player(guid: u64) -> bool {
     guid != 0 && high(guid) == HIGH_PLAYER
 }
 
-/// A creature or pet guid (`IsCreatureOrPet`) — both are `TYPEID_UNIT` to every consumer. They are
-/// **not** interchangeable for naming: only the creature half carries a template entry (see
-/// [`entry`] and [`pet_number`]).
+/// A creature or pet guid (`IsCreatureOrPet`); only a creature's carries a template entry.
 pub fn is_creature_or_pet(guid: u64) -> bool {
     matches!(high(guid), HIGH_UNIT | HIGH_PET)
 }
 
-/// A pet guid (`IsPet`) — a summoned or charmed unit, whose guid's middle field is a **pet number**
-/// and not a creature template entry. See [`pet_number`].
+/// A pet guid (`IsPet`), whose middle field is a pet number, not a template entry.
 pub fn is_pet(guid: u64) -> bool {
     high(guid) == HIGH_PET
 }
 
-/// A pet guid's **pet number** — the per-pet id `CMSG_PET_NAME_QUERY` is keyed by, and the value the
-/// server matches against `CharmInfo::GetPetNumber()` before it will answer at all.
-///
-/// It occupies the same guid bits 24–47 that a creature's template entry does, because vmangos
-/// composes a pet with `Object::_Create(guidlow, petNumber, HIGHGUID_PET)` (`Objects/Pet.cpp:2250`,
-/// from `Pet::Create(guidlow, pos, cinfo, petNumber)`): the shared `_Create`'s `entry` parameter is
-/// fed the pet number, **not** `cinfo->entry`. That is why [`entry`] answers `None` for this family —
-/// the slot is occupied, just not by a template id, and a `CMSG_CREATURE_QUERY` for it can only miss.
+/// The pet number in bits 24-47, fed in as `_Create`'s entry (`Objects/Pet.cpp:2250`): the key
+/// of `CMSG_PET_NAME_QUERY`, answered only when it matches `CharmInfo::GetPetNumber()`.
 pub fn pet_number(guid: u64) -> Option<u32> {
     is_pet(guid).then_some(((guid >> 24) & 0xFF_FFFF) as u32)
 }
 
-/// A (non-zero) item or container guid (`IsItem` — containers included). Items carry **no** entry
-/// in the guid; the entry lives in the descriptor (`OBJECT_FIELD_ENTRY`).
+/// A non-zero item or container guid (`IsItem`); the entry is only in `OBJECT_FIELD_ENTRY`.
 pub fn is_item(guid: u64) -> bool {
     guid != 0 && high(guid) == HIGH_ITEM
 }
 
-/// Either transport guid family — a boat/zeppelin (`HIGH_MO_TRANSPORT`) or an elevator
-/// (`HIGH_TRANSPORT`). The two are composed differently (see [`entry`]) but both name "a transport" to
-/// every other consumer (the create-routing gate, the rider wire tail).
+/// Either transport family: a boat or zeppelin, or an elevator.
 pub fn is_transport(guid: u64) -> bool {
     matches!(high(guid), HIGH_MO_TRANSPORT | HIGH_TRANSPORT)
 }
@@ -76,34 +56,10 @@ pub fn is_gameobject(guid: u64) -> bool {
     high(guid) == HIGH_GAMEOBJECT
 }
 
-/// The embedded template entry, for the guid families that carry one. Two different layouts, both
-/// VERIFIED against vmangos:
-///
-/// - Creatures/GameObjects/**elevators** (`HIGH_UNIT`/`HIGH_GAMEOBJECT`/
-///   `HIGH_TRANSPORT`) use the standard `[high:16][entry:24][counter:24]` layout — vmangos's
-///   class-internal `HasEntry` switch returns `true` for these (`ObjectGuid.h:223-240`), and an
-///   elevator composes exactly like an ordinary GameObject: `GameObject::Create` calls
-///   `Object::_Create(guidlow, goinfo->id, HIGHGUID_TRANSPORT)` for a `GAMEOBJECT_TYPE_TRANSPORT`
-///   template (`Objects/GameObject.cpp:207`, reached via `ElevatorTransport::Create` →
-///   `GenericTransport::Create` → the same `GameObject::Create`) — `goinfo->id` (the template entry)
-///   rides bits 24–47, the spawn's own DB-assigned low guid rides bits 0–23.
-/// - **Boats/zeppelins** (`HIGH_MO_TRANSPORT`) carry **no** entry part at all: vmangos's
-///   `DoesGuidHaveEntryPart`/`HasEntry` both return `false` for `HIGHGUID_MO_TRANSPORT`
-///   (`ObjectGuid.h:87-104`, `223-240`). `ShipTransport::Create` calls `Object::_Create(guidlow, 0,
-///   HIGHGUID_MO_TRANSPORT)` (`Transports/Transport.cpp:65`) where `guidlow` is the
-///   `gameobject_template` entry itself, threaded in from `TransportMgr::CreateTransport(uint32
-///   entry, …)` (`TransportMgr.cpp:364,400`: `trans->Create(entry, frameItr)`). The `ObjectGuid`
-///   3-arg ctor folds `entry`(=0 here) and `counter`(=guidlow) into ONE 32-bit low field when the
-///   family has no entry part (`ObjectGuid.h:123`: `counter | (entry << 24) | (hi << 48)`) — so the
-///   template entry rides the **full low 32 bits**, recovered the same way `GetCounter`'s
-///   `hasEntry=false` branch does (`ObjectGuid.h:157-165`: mask `0xFFFF_FFFF`, not the 24-bit entry
-///   slot the other families use). Masking to 24 bits here would silently truncate a >16.7M template
-///   id — none exist today, but the 32-bit mask is what vmangos actually does, so that's what we do.
-///
-/// `None` for players/items/corpses/dynamic objects (no entry part, and not composed like a transport
-/// either) — and `None` for **pets**, whose entry-shaped slot holds a pet number instead
-/// ([`pet_number`]): `HasEntry` is `true` for the family, but what vmangos stores there is not a
-/// template id, so answering with it would hand every caller a creature entry that cannot resolve.
+/// The template entry: bits 24-47 for creatures, gameobjects and elevators (`HasEntry`,
+/// `ObjectGuid.h:223-240`; `GameObject.cpp:207`), the full low 32 bits for boats and zeppelins,
+/// whose template entry is passed as the counter (`Transport.cpp:65`, `ObjectGuid.h:123`). `None`
+/// for pets although `HasEntry` is true: their slot holds the pet number.
 pub fn entry(guid: u64) -> Option<u32> {
     match high(guid) {
         HIGH_MO_TRANSPORT => Some((guid & 0xFFFF_FFFF) as u32),
@@ -116,14 +72,13 @@ pub fn entry(guid: u64) -> Option<u32> {
 mod tests {
     use super::*;
 
-    /// Compose a guid the way vmangos does: `counter | (entry << 24) | (high << 48)`.
+    /// Composes a guid as the vmangos ctor does (`ObjectGuid.h:123`).
     fn compose(high: u16, entry: u32, counter: u32) -> u64 {
         u64::from(counter) | (u64::from(entry) << 24) | (u64::from(high) << 48)
     }
 
     #[test]
     fn creature_guid_decodes_high_and_entry() {
-        // A Northshire creature: entry 69 (Diseased Young Wolf), counter 12345.
         let g = compose(HIGH_UNIT, 69, 12345);
         assert_eq!(high(g), HIGH_UNIT);
         assert!(is_creature_or_pet(g));
@@ -165,9 +120,6 @@ mod tests {
         assert_eq!(entry(g), Some(0xFF_FFFF));
     }
 
-    /// A pet's entry-shaped slot is its PET NUMBER — `Pet::Create` feeds `_Create`'s `entry`
-    /// parameter `petNumber`, not `cinfo->entry` (`Objects/Pet.cpp:2250`). Asking
-    /// `CMSG_CREATURE_QUERY` for it is what left NPC-summoned pets nameless, so `entry` must refuse.
     #[test]
     fn a_pet_carries_a_pet_number_not_a_template_entry() {
         let g = compose(HIGH_PET, 137, 4242);
@@ -175,32 +127,20 @@ mod tests {
         assert!(is_creature_or_pet(g));
         assert_eq!(pet_number(g), Some(137));
         assert_eq!(entry(g), None, "a pet's slot is not a template entry");
-        // ...and only a pet answers `pet_number`.
         assert_eq!(pet_number(compose(HIGH_UNIT, 137, 4242)), None);
     }
 
-    /// An elevator (`HIGHGUID_TRANSPORT`, 0xF120) composes exactly like an ordinary GameObject —
-    /// `Object::_Create(guidlow, goinfo->id, HIGHGUID_TRANSPORT)` (`GameObject.cpp:207`): the DB spawn's
-    /// own low guid in `counter`, the `gameobject_template` entry in the standard entry slot.
     #[test]
     fn elevator_guid_decodes_high_and_entry() {
-        // The Undercity/Ironforge-style elevator template entry 900 (a real GAMEOBJECT_TYPE_TRANSPORT
-        // id range), DB spawn low guid 4242.
         let g = compose(HIGH_TRANSPORT, 900, 4242);
         assert_eq!(high(g), HIGH_TRANSPORT);
         assert!(is_transport(g));
         assert_eq!(entry(g), Some(900));
     }
 
-    /// A boat/zeppelin (`HIGHGUID_MO_TRANSPORT`, 0x1FC0) composes the OTHER way —
-    /// `Object::_Create(guidlow, 0, HIGHGUID_MO_TRANSPORT)` (`Transport.cpp:65`) where `guidlow` is
-    /// itself the `gameobject_template` entry (`TransportMgr::CreateTransport`'s `entry` param threaded
-    /// straight through, `TransportMgr.cpp:364,400`): the entry rides the FULL low 32 bits, not the
-    /// 24-bit entry slot the standard families use — composed here with `entry=0` per the ctor
-    /// (`ObjectGuid.h:123`), matching `entry()`'s `HIGH_MO_TRANSPORT` mask.
     #[test]
     fn mo_transport_guid_decodes_high_and_entry() {
-        // The Menethil-Theramore ferry's real gameobject_template entry, 176495.
+        // The Grom'Gol-Undercity zeppelin's template entry, which the ctor takes as the counter.
         let g = compose(HIGH_MO_TRANSPORT, 0, 176_495);
         assert_eq!(high(g), HIGH_MO_TRANSPORT);
         assert!(is_transport(g));
@@ -209,8 +149,7 @@ mod tests {
             Some(176_495),
             "the template entry rides the full low 32 bits, not bits 24-47"
         );
-        // The naive `(guid >> 24) & 0xFFFFFF` extraction the other families use would find nothing
-        // useful here — pin that the two layouts genuinely differ, not just that our helper works.
+        // The 24-bit entry slot does not hold it: the two layouts really differ.
         assert_ne!(((g >> 24) & 0xFF_FFFF) as u32, 176_495);
     }
 
diff --git a/crates/benilla-protocol/src/lib.rs b/crates/benilla-protocol/src/lib.rs
index 2ee97c18..985b73c8 100644
--- a/crates/benilla-protocol/src/lib.rs
+++ b/crates/benilla-protocol/src/lib.rs
@@ -1,10 +1,5 @@
-//! `benilla-protocol` — WoW 1.12.1 (build 5875) auth + world wire protocol.
-//!
-//! Auth/SRP6 and the world header crypto come from `benilla-srp`; message (de)serialization is
-//! in-repo ([`auth`] for the realmd login protocol, [`world`]/[`events`] for the world protocol) —
-//! decision 0021. 1.12.1 uses **login protocol version 3**. This crate owns the session logic; the
-//! async↔ECS bridge lives in `benilla`. Phase 3: SRP6 logon + realm
-//! list.
+//! The WoW 1.12.1 (build 5875) wire protocol: [`auth`] for realmd (login protocol version 3),
+//! [`world`] and [`events`] for the world server. SRP6 and the header crypto are `benilla-srp`'s.
 
 pub mod auth;
 pub mod events;
@@ -33,19 +28,15 @@ use std::net::TcpStream;
 use anyhow::{anyhow, Context, Result};
 use benilla_srp::{NormalizedString, PublicKey, SrpClientChallenge, SESSION_KEY_LENGTH};
 
-/// The realmd (auth/login) server port — the stock one a vmangos `realmd` listens on, which our
-/// deploy maps straight through (`3724:3724` in the compose file at `vmangos-deploy`).
+/// The port a stock vmangos `realmd` listens on.
 pub const AUTH_PORT: u16 = 3724;
 /// The 1.12.1 client build we present to the server.
 pub const CLIENT_BUILD: u16 = 5875;
-/// How many logon challenges [`logon`] will ask for while looking for a `B` both serialization
-/// conventions read the same way (see the redial comment there). One dial in ~137 comes back
-/// ambiguous, so eight is already a probability of about 10⁻¹⁷ of running out.
+/// Challenges [`logon`] draws for an unambiguous `B`; one in ~137 is not, so all 8 fail ~10⁻¹⁷.
 const MAX_CHALLENGE_DIALS: u32 = 8;
 
-/// Split an optional `:port` off a host string (`play.example.com:3724`). A bare host — or one
-/// whose suffix isn't a port, e.g. a raw IPv6 address like `::1` — comes back intact with
-/// `default`.
+/// Splits an optional `:port` off a host; one without a numeric port, a raw IPv6 address
+/// included, comes back whole with `default`.
 pub fn host_port(host: &str, default: u16) -> (&str, u16) {
     match host.rsplit_once(':') {
         Some((h, p)) if !h.contains(':') => match p.parse::<u16>() {
@@ -56,17 +47,8 @@ pub fn host_port(host: &str, default: u16) -> (&str, u16) {
     }
 }
 
-/// The dial never got a socket — **and which of the two reasons it was**.
-///
-/// This distinction only started mattering when the realmlist became something a player types
-/// (decision 1667). Before that the address was a constant and "Unable to connect" could only mean
-/// one thing; afterwards it means either *you typed a name that does not exist* or *the address is
-/// fine and nothing is answering on it*, and a player with no way to tell them apart edits a
-/// correct address over and over. That is exactly what the first live use of the editor produced.
-///
-/// The split is drawn where it is honest — resolution and connection are two separate operations,
-/// so we do them separately rather than reading tea leaves out of one `io::Error` (a DNS failure
-/// surfaces as `ErrorKind::Uncategorized` on macOS, so the kind cannot carry this).
+/// A dial that got no socket, split by step: the name did not resolve, or nothing answered (one
+/// `io::Error` cannot tell them apart; macOS reports a failed lookup as `Uncategorized`).
 #[derive(Debug, Clone)]
 pub struct DialFailure {
     /// What we tried to reach, as the player would recognise it (`host:port`).
@@ -87,13 +69,8 @@ impl std::fmt::Display for DialFailure {
 
 impl std::error::Error for DialFailure {}
 
-/// Resolve `host:port` and open a socket to it, reporting the two failures apart ([`DialFailure`]).
-///
-/// `to_socket_addrs` is the resolution step on its own; an empty result is a name that resolved to
-/// no addresses, which is as much a "cannot find it" as an outright lookup error. Connecting to the
-/// resolved list (rather than to `(host, port)` again) also means the OS does not repeat the
-/// lookup, and that every address the name carries is tried — the `localhost` → `::1` then
-/// `127.0.0.1` case on a machine whose server binds only IPv4.
+/// Resolves, then tries every resolved address in turn: `localhost` gives `::1` first, and a
+/// server may bind only IPv4.
 fn dial(host: &str, port: u16) -> Result<TcpStream> {
     use std::net::ToSocketAddrs;
     let address = format!("{host}:{port}");
@@ -122,71 +99,42 @@ fn dial(host: &str, port: u16) -> Result<TcpStream> {
     })
 }
 
-/// A realm as advertised by the auth server's realm list — **every** field the wire carries.
-///
-/// Three of them used to be dropped on the floor (`_flag`, `_category`, `_realm_id`) and
-/// `population` was stringified on arrival, which was survivable only while benilla connected to
-/// `realms.first()` and never drew a list. The realm-list screen needs all of them, and it needs
-/// the population as the float it is.
+/// A realm from realmd's realm list, with every field the wire carries.
 #[derive(Debug, Clone)]
 pub struct RealmInfo {
     pub name: String,
     /// `host:port` of the world server, as the client would connect to it.
     pub address: String,
-    /// The population float — **not** what the realm list displays. The displayed word
-    /// (`Low`/`Medium`/`High`/`Full`/…) is a *band* computed against the mean and standard
-    /// deviation of **every** realm; see `realm_select::load` on the app side.
-    ///
-    /// Already **rewritten** if the server sent one of the three sentinel values — see
-    /// [`auth::MAGIC_POPULATIONS`]. What is stored here is what the reference's own parser would
-    /// hold, which is the only value it is safe to average.
+    /// The population, sentinels already rewritten as the reference parser does
+    /// ([`auth::MAGIC_POPULATIONS`]); the list shows a band against all realms' mean and deviation.
     pub population: f32,
-    /// How many characters this account has on that realm — a genuine count, printed by the list as
-    /// `"(3)"`. (The client's realm record keeps it at `[realm+0x130]`; wow-re's earlier band sweep
-    /// had read that offset as the realm type, which is really the dword at `[+0x04]` below.)
+    /// This account's character count there, shown as `"(3)"` (client realm record `+0x130`).
     pub characters: u8,
-    /// The realm **type** — the join key for the game-type columns, *not* an enumeration to match
-    /// on directly. `GetRealmInfo` resolves `(pvp, rp)` by scanning `Cfg_Configs.dbc` for the row
-    /// whose `RealmType` equals this; `realm_select::load::pvp_rp` is that table.
+    /// The realm type (record `+0x04`), a join key, not an enum: `GetRealmInfo` takes `(pvp, rp)`
+    /// from the `Cfg_Configs.dbc` row whose `RealmType` equals it.
     pub realm_type: u32,
-    /// The realm-flags byte — the client's realm record `[realm+0x08]`.
-    ///
-    /// **Only `0x01` (invalid) and `0x02` (offline) — plus `0x04` — actually travel on the wire.**
-    /// The `0x20`/`0x40`/`0x80` sentinels that mean Recommended / New / Full are *synthesized on
-    /// arrival* from the magic populations the server sends instead, exactly as the reference's
-    /// parser does it ([`auth::MAGIC_POPULATIONS`]) — so this byte is the client's view of the
-    /// flags, not the server's.
+    /// The realm flags as the client holds them (record `+0x08`): the wire carries only `0x01`
+    /// invalid, `0x02` offline and `0x04`; `0x20`/`0x40`/`0x80` (Recommended, New, Full) are
+    /// synthesized from the magic populations ([`auth::MAGIC_POPULATIONS`]).
     pub flags: u8,
-    /// The wire's category (timezone) byte — the realm list's category tabs group on it. Matched
-    /// against a category id by **equality**; it is not an index into anything.
+    /// The category (timezone) byte the list's tabs group on, matched by equality, not an index.
     pub category: u8,
     /// The wire's realm id.
     pub id: u8,
 }
 
-/// Result of a successful logon: the SRP6 session key (carried into the world server), the realms,
-/// and the **still-open realmd socket** the list was read from.
-///
-/// The socket is kept because the realm list is not a one-shot: the reference's `RealmList.lua`
-/// re-requests it every `REALM_LIST_REFRESH_TIME` (5 s) for as long as its window is open, which
-/// is how a realm going offline or filling up shows up without a re-login. [`Logon::refresh_realms`]
-/// is that request. It is private so the only thing anyone can do with the connection is ask it
-/// the one question it still answers.
+/// A successful logon: the SRP6 session key, the realms, and the realmd socket, kept open because
+/// the reference's `RealmList.lua` re-requests the list every `REALM_LIST_REFRESH_TIME` (5 s).
 pub struct Logon {
     pub session_key: [u8; SESSION_KEY_LENGTH],
     pub realms: Vec<RealmInfo>,
-    /// `None` once a refresh has failed — the list we hold is then the last word, and we stop
-    /// asking rather than retrying a dead socket every five seconds.
+    /// `None` once a refresh has failed; the held list is then final.
     stream: Option<TcpStream>,
 }
 
 impl Logon {
-    /// Re-request the realm list on the realmd connection — the reference's `RequestRealmList`.
-    ///
-    /// Returns whether the list was refreshed. A failed refresh **drops the connection and keeps
-    /// the realms we already have**: a stale list the player can still pick from beats an empty
-    /// one, and realmd closing an idle socket is ordinary. Bounded by `timeout` so a park that
-    /// calls this can never block on a server that accepted the request and said nothing.
+    /// The reference's `RequestRealmList`: re-reads the list, keeping the old one and dropping
+    /// the socket on failure (realmd closes idle sockets); `timeout` bounds a silent server.
     pub fn refresh_realms(&mut self, timeout: std::time::Duration) -> bool {
         let Some(stream) = self.stream.as_mut() else {
             return false;
@@ -208,20 +156,14 @@ impl Logon {
         }
     }
 
-    /// Whether the realmd connection is still up, i.e. whether [`Self::refresh_realms`] can do
-    /// anything. Lets a caller stop scheduling refreshes rather than calling into a no-op.
+    /// Whether the realmd socket is still up, so [`Self::refresh_realms`] can do anything.
     pub fn realmd_live(&self) -> bool {
         self.stream.is_some()
     }
 }
 
-/// Perform the full SRP6 logon against a vanilla `realmd` and fetch the realm list.
-///
-/// Flow: logon challenge → server challenge (B, g, N, salt) → SRP6 → logon proof → verify the
-/// server's proof (M2) → request + read the realm list.
+/// The full SRP6 logon against a vanilla `realmd`, then the realm list.
 pub fn logon(host: &str, username: &str, password: &str) -> Result<Logon> {
-    // `host` may carry an explicit `:port` (`WOW_HOST=play.example.com:3724`); bare hosts get
-    // [`AUTH_PORT`].
     let (host, port) = host_port(host, AUTH_PORT);
 
     let username_n =
@@ -229,14 +171,9 @@ pub fn logon(host: &str, username: &str, password: &str) -> Result<Logon> {
     let password_n =
         NormalizedString::new(password).map_err(|e| anyhow!("invalid password: {e}"))?;
 
-    // 1-2. Logon challenge → the server's SRP6 inputs. The account name is sent uppercased (matching
-    // the SRP6 calculation).
-    //
-    // `B` is the one hashed value benilla does not draw, and ~1 in 137 of them is one the client and
-    // the mangos family serialize differently — a correct password answered with 0x04 (see
-    // `benilla-srp`, "Encoding-unambiguous handshakes"). Redial for a fresh `B` when that lands: the
-    // challenge is abandoned before any proof goes out, and realmd counts nothing at this stage for a
-    // known account (`AuthSocket::_HandleLogonChallenge`), so a redial is free and invisible.
+    // The account name goes uppercased, as SRP6 hashes it. About one `B` in 137 serializes
+    // differently in the client and mangos (a right password gets 0x04), so redial for a fresh
+    // one; realmd counts nothing before the proof (`AuthSocket::_HandleLogonChallenge`).
     let (mut stream, reply, server_public_key) = {
         let mut dialed = None;
         for _ in 0..MAX_CHALLENGE_DIALS {
@@ -253,12 +190,10 @@ pub fn logon(host: &str, username: &str, password: &str) -> Result<Logon> {
                 break;
             }
         }
-        // Every dial ran out ambiguous (p ≈ 10⁻¹⁷): send the last anyway rather than inventing a
-        // failure the server never gave us.
+        // All ambiguous: go on with the last, since only the server can say it fails.
         dialed.expect("MAX_CHALLENGE_DIALS is non-zero")
     };
 
-    // 3. SRP6 (WoW flavor) — compute A, M1, and the session key.
     let challenge = SrpClientChallenge::new(
         username_n,
         password_n,
@@ -268,7 +203,6 @@ pub fn logon(host: &str, username: &str, password: &str) -> Result<Logon> {
         reply.salt,
     );
 
-    // 4. Logon proof.
     auth::write_logon_proof(
         &mut stream,
         challenge.client_public_key(),
@@ -277,14 +211,12 @@ pub fn logon(host: &str, username: &str, password: &str) -> Result<Logon> {
     )
     .context("sending logon proof")?;
 
-    // 5. Verify the server's proof (M2); on success we hold the session key.
     let server_proof = auth::read_proof_reply(&mut stream).context("reading logon proof reply")?;
     let client = challenge
         .verify_server_proof(server_proof)
         .map_err(|e| anyhow!("server proof mismatch (wrong password?): {e}"))?;
     let session_key = *client.session_key();
 
-    // 6. Realm list.
     auth::write_realm_list_request(&mut stream).context("requesting realm list")?;
     let realms = auth::read_realm_list(&mut stream).context("reading realm list")?;
 
@@ -301,7 +233,6 @@ mod host_port_tests {
 
     #[test]
     fn explicit_port_splits() {
-        // Explicit port beats the default — they differ so the assert can tell them apart.
         assert_eq!(
             host_port("play.example.com:5000", AUTH_PORT),
             ("play.example.com", 5000)
diff --git a/crates/benilla-protocol/src/messages/action_bar.rs b/crates/benilla-protocol/src/messages/action_bar.rs
index 8e0ec41b..c5481dc9 100644
--- a/crates/benilla-protocol/src/messages/action_bar.rs
+++ b/crates/benilla-protocol/src/messages/action_bar.rs
@@ -1,43 +1,29 @@
-//! Action-bar messages — the 120-slot bar's packing, the login snapshot, and the one-slot write.
-//! Split out of `messages/spells.rs` (decision 0640); mirrored by `world::writer::action_bar`.
-//!
-//! The bar is **client-authoritative** (decisions 0216 §7 / 0218 §4): the server stores 120 packed
-//! `u32`s and hands them back at login, and the client sends one `CMSG_SET_ACTION_BUTTON` per local
-//! slot mutation. There is no server-side edit in normal play, so `SMSG_ACTION_BUTTONS` is a
-//! login-only packet in practice — which is why the whole family is three items.
-//!
-//! The **visibility** of the four extra bars is the opposite arrangement and shares this file only
-//! because it shares the subject: it is one server-owned byte the client can post but never write
-//! locally. See [`set_actionbar_toggles`].
+//! Action-bar messages: the 120-slot login snapshot, the one-slot write, and the bar toggles.
+//! The bar is client-authoritative: the server stores the slots, sends them at login, and takes
+//! one `CMSG_SET_ACTION_BUTTON` per local change.
 
 use std::io::{self};
 
 use crate::wire::read_u32_le;
 
-/// Action-button kind byte (bits 24–31 of the packed slot word — vmangos `Player.h`
-/// `ActionButtonType`): a spell id, a macro id, or an item id in the low 24 bits.
+/// The action-button kind, bits 24-31 of a slot word (`ActionButtonType`, vmangos `Player.h`).
 pub const ACTION_KIND_SPELL: u8 = 0x00;
 pub const ACTION_KIND_MACRO: u8 = 0x40;
 pub const ACTION_KIND_ITEM: u8 = 0x80;
 
-/// One *occupied* action-bar slot from `SMSG_ACTION_BUTTONS`. The wire is 120 packed `u32`s
-/// (`MAX_ACTION_BUTTONS`, vmangos `MasterPlayer::SendInitialActionButtons`) — `action` in bits
-/// 0–23, `kind` in bits 24–31 (`ACTION_BUTTON_ACTION/TYPE`, `Player.h`); a zero word is an empty
-/// slot and is not surfaced.
+/// An occupied slot of `SMSG_ACTION_BUTTONS`, 120 packed `u32`s
+/// (`MasterPlayer::SendInitialActionButtons`); a zero word is an empty slot.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ActionButton {
     /// The bar slot index (0..119). Slots 0–11 are the main bar's buttons 1–12.
     pub slot: u8,
     /// The spell/macro/item id (bits 0–23).
     pub action: u32,
-    /// The kind byte (bits 24–31): [`ACTION_KIND_SPELL`]/[`ACTION_KIND_MACRO`]/[`ACTION_KIND_ITEM`]
-    /// (0x01 "click?" exists in the enum, carried raw if it ever appears).
+    /// The kind byte (bits 24-31), an `ACTION_KIND_*`; the enum's 0x01 ("click?") is carried raw.
     pub kind: u8,
 }
 
-/// Read `SMSG_ACTION_BUTTONS`: packed `u32` per slot to end-of-body (the server sends exactly 120;
-/// reading to the boundary keeps us robust to a different count). Zero words (empty slots) are
-/// dropped; occupied slots surface as [`ActionButton`]s.
+/// Reads slot words to the end of the body (the server sends 120), dropping empty ones.
 pub(super) fn read_action_buttons(r: &mut &[u8]) -> io::Result<Vec<ActionButton>> {
     let mut buttons = Vec::new();
     let mut slot: u32 = 0;
@@ -55,12 +41,8 @@ pub(super) fn read_action_buttons(r: &mut &[u8]) -> io::Result<Vec<ActionButton>
     Ok(buttons)
 }
 
-/// Body of `CMSG_SET_ACTION_BUTTON` (VERIFIED vmangos `WorldPackets::Misc::SetActionButton::
-/// ReadFromWorldPacket`, `Server/Packets/Misc.cpp:87-90`; opcode 296 `Opcodes_1_12_1.h:299`):
-/// `button u8` + `packetData u32` (`action | kind<<24`, [`ActionButton`]'s own packing) — 5
-/// bytes. `packed == 0` clears the slot (`HandleSetActionButtonOpcode`'s `!packet.packetData`
-/// branch calls `removeActionButton`, never sent back over the wire — decision 0216 §7/0218 §4:
-/// the client sends ONE of these per local slot mutation, a drag-swap is two sends, never atomic).
+/// `CMSG_SET_ACTION_BUTTON` (296): `button u8`, `packetData u32` packed as in [`ActionButton`]
+/// (`Server/Packets/Misc.cpp:87-90`). Zero clears the slot (no reply); a drag-swap is two sends.
 pub fn set_action_button(button: u8, packed: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(5);
     body.push(button);
@@ -68,29 +50,11 @@ pub fn set_action_button(button: u8, packed: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_SET_ACTIONBAR_TOGGLES` (opcode [`super::opcode::CMSG_SET_ACTIONBAR_TOGGLES`]):
-/// **one `u8`**, and nothing else — VERIFIED at the bytes, wow-re
-/// `system/ui/scratch/action-bar-toggles.md` §3. `SetActionBarToggles 0x4e76e0` builds a stack
-/// `CDataStore`, appends the opcode with `PutUInt32 0x418190` and the byte with `PutUInt8
-/// 0x418070`, and sends; those two appends are the only ones between construction and send, and
-/// `NetClient::Send 0x5379b3` computes the payload length as `size − read` = **5** — the
-/// independent confirmation that 4 + 1 is the whole frame.
-///
-/// **The byte is server-owned; this is a post, not a write.** No instruction in the real client
-/// stores to `PLAYER_FIELD_BYTES` byte 2 (§4.1: displacement `0x102a` occurs exactly once
-/// image-wide and it is the *read* inside `GetActionBarToggles`) — the cell only ever moves through
-/// the generic `SMSG_UPDATE_OBJECT` value-apply. So the sender's own field copy still holds the old
-/// value until the server echoes, and nothing is notified when it does (§4.2: all 49 field-change
-/// registrations at `0x468070` were enumerated and none sits at an offset ≥ `0x1000`). Read it back
-/// with [`super::ObjectFields::player_action_bar_toggles`].
-///
-/// **Only the low nibble is reachable.** The real binding accumulates from zero and ORs at most
-/// bits 0..3 (§2), so a value it produces is always `0x00..=0x0f` and a `Set` *destroys* whatever
-/// the server held in the high nibble. This encoder does not mask: what the caller packed is what
-/// goes on the wire, and the four-bit law belongs where the packing happens (the Lua binding).
-///
-/// The bit→bar meaning is **not** the binary's — it is bar-agnostic (§7), and naming the bars here
-/// would put a FrameXML convention in the protocol layer.
+/// `CMSG_SET_ACTIONBAR_TOGGLES`: one `u8`, the whole body (`SetActionBarToggles 0x4e76e0`).
+/// The byte is server-owned: the reference never writes its copy (`PLAYER_FIELD_BYTES` byte 2),
+/// which changes only when `SMSG_UPDATE_OBJECT` echoes it, with no change event; read it with
+/// [`super::ObjectFields::player_action_bar_toggles`]. The reference packs only bits 0..3, so a
+/// set clears the high nibble; this encoder does not mask. Bits name bars only in FrameXML.
 pub fn set_actionbar_toggles(toggles: u8) -> Vec<u8> {
     vec![toggles]
 }
diff --git a/crates/benilla-protocol/src/messages/addons.rs b/crates/benilla-protocol/src/messages/addons.rs
index 7edb9576..97e8d64f 100644
--- a/crates/benilla-protocol/src/messages/addons.rs
+++ b/crates/benilla-protocol/src/messages/addons.rs
@@ -1,75 +1,19 @@
-//! The **addon-info block** at the tail of `CMSG_AUTH_SESSION` — what the client tells the world
-//! server about its *secure* addons (decision 1497).
+//! The addon-info block ending `CMSG_AUTH_SESSION`, written by `0x51d910` after the 20-byte
+//! proof: a `u32` uncompressed size, then a zlib (RFC1950) stream to the end of the packet.
+//! Uncompressed, it is one record per addon whose `.toc` sets `## Secure:` non-zero, enabled or
+//! not, with no count or trailer: `CString` name, `u8` flags (`.pub` byte 0), `u32` CRC-32 of the
+//! 256 modulus bytes (`.pub` bytes 1..=256), `u32` CRC-32 of the `.url` string (0 if none).
 //!
-//! Every 1.12.1 logon carries one of these. It is not optional decoration: it is the last field of
-//! the auth packet, and a server reads it before the session exists. benilla used to send a
-//! `decompressed_size = 0` + zlib-of-nothing stub, which **no real client can produce** — and
-//! cmangos-classic kicks the session for it (B277). See [`addon_block`] for the shape and
-//! [`STOCK_SECURE_ADDONS`] for what a stock install actually sends.
-//!
-//! ## Where the shape comes from
-//!
-//! VERIFIED in `WoW.exe` (5875) — wow-5875-re `system/net/scratch/cmsg-auth-session-addon-block.md`.
-//! The writer is `0x51d910`, called once, from `HandleAuthChallenge` (`0x5b4143`) straight after the
-//! 20-byte SHA-1 proof. It appends:
-//!
-//! ```text
-//! u32   uncompressed_size    ; byte length of the buffer below
-//! u8[]  zlib stream          ; RFC1950 framing (deflateInit_ windowBits +15), runs to end of packet
-//! ```
-//!
-//! and the uncompressed buffer is a **bare concatenation** — no leading count, no trailer —
-//! of one record per secure addon:
-//!
-//! ```text
-//! CString name          ; NUL-terminated
-//! u8      flags         ; byte 0 of the addon's own .pub signature file
-//! u32     modulus_crc   ; CRC-32 of the 256 modulus bytes (.pub bytes 1..=256)
-//! u32     url_crc       ; CRC-32 of the addon's .url string; 0 when it has none
-//! ```
-//!
-//! **Which** addons: exactly those whose `.toc` declares `## Secure:` non-zero — enable/disable
-//! state is not consulted. On a stock install that is precisely the twelve `Blizzard_*` built-ins
-//! and nothing else, because no third-party 1.12 addon declares `## Secure`. A client with *zero*
-//! secure addons appends **nothing at all** (not a zero dword) — the writer returns before the
-//! local store exists.
-//!
-//! ## Why the emulators disagree about it, and why it matters
-//!
-//! Both vmangos and cmangos reject `size == 0` with the same comment ("empty addon packet … can't
-//! be received from real client") — that judgement is *correct*, and matched the binary all along.
-//! What differs is the consequence:
-//!
-//! - vmangos `WorldSocket.cpp:447` — `if (BuildAddonPacket(...)) SendPacket(addonPacket);`. A
-//!   rejection just means no `SMSG_ADDON_INFO` goes back; the session lives. That is the only
-//!   reason benilla's stub ever worked.
-//! - cmangos-classic `WorldSocket.cpp:562` — `if (!ReadAddonInfo(...)) { … "sent bad addon info.
-//!   Kicking."; return false; }`. Same rejection, session killed. Not config-gated: the check is in
-//!   the anticheat module *and* in `NullSessionAnticheat`, so it runs with the anticheat off.
-//!
-//! cmangos's two readers also disagree with each other on field order — its anticheat module reads
-//! `name, u8, u32, u32` (right, matching the binary) and its `NullSessionAnticheat` reads
-//! `name, u32, u32, u8` (wrong, but the same nine bytes, so it parses without throwing).
+//! With no secure addons the client appends nothing. Both emulators refuse a zero size: vmangos
+//! then skips `SMSG_ADDON_INFO` (`WorldSocket.cpp:447`), cmangos-classic kicks the session
+//! (`WorldSocket.cpp:562`).
 
-/// CRC-32 of the stock Blizzard public-key modulus — what a stock, unmodified addon's `.pub`
-/// hashes to, and the value every emulator calls the "standard addon CRC". A server that sees it
-/// knows it need not push the 256-byte modulus back in `SMSG_ADDON_INFO`.
-///
-/// VERIFIED: `zlib.crc32` of the 256 modulus bytes in this install's `Blizzard_*.pub` files, which
-/// are byte-identical to the `modulus`/`tdata` array carried in vmangos and cmangos alike.
+/// CRC-32 of the stock Blizzard public-key modulus, the emulators' "standard addon CRC"; a server
+/// seeing it does not send the 256-byte modulus back in `SMSG_ADDON_INFO`.
 pub const STANDARD_MODULUS_CRC: u32 = 0x4C1C_776D;
 
-/// **Which addons `SMSG_ADDON_INFO` hid** — the reply's `status` bytes paired back against the
-/// records we sent (decision 2175).
-///
-/// The reply carries no names: the client re-walks its own `## Secure:` list in the same order it
-/// sent it, so record *i* is `sent[i]`. A `status` of **2** is what makes the reference set
-/// `[rec+0x29] = 1` (`0x51db84`) and drop the addon from the Lua index space — on a stock install
-/// that is all twelve, which is why the AddOns list shows only the player's own addons.
-///
-/// A reply with **more** records than we sent is truncated to what we sent, and one with fewer
-/// simply says nothing about the rest: both are the server disagreeing with us about the block,
-/// and neither is worth failing a login over.
+/// The addons `SMSG_ADDON_INFO` hides: record i answers `sent[i]` (the reply carries no names),
+/// and status 2 makes the reference set `[rec+0x29] = 1` (`0x51db84`), dropping it from Lua.
 pub fn hidden_from_reply(statuses: &[u8], sent: &[SecureAddon]) -> Vec<String> {
     statuses
         .iter()
@@ -79,26 +23,22 @@ pub fn hidden_from_reply(statuses: &[u8], sent: &[SecureAddon]) -> Vec<String> {
         .collect()
 }
 
-/// One record in the addon block — a secure addon as the client describes it to the server.
+/// One record of the addon block.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SecureAddon<'a> {
     /// The addon's folder name (`Blizzard_AuctionUI`), sent as a `CString`.
     pub name: &'a str,
-    /// Byte 0 of the addon's `.pub` file — `1` for a stock signature, `0` when the client found no
-    /// usable `.pub`. A server may write a different byte back (`SMSG_ADDON_INFO`), which the real
-    /// client persists into the `.pub` and echoes next logon; cmangos's anticheat uses exactly that
-    /// channel to stamp a per-install fingerprint across four of the twelve.
+    /// Byte 0 of the `.pub`: 1 for a stock signature, 0 for none usable. A server may write another
+    /// back in `SMSG_ADDON_INFO`, which the reference saves to the `.pub` and echoes next logon.
     pub flags: u8,
-    /// CRC-32 of the `.pub`'s 256 modulus bytes — [`STANDARD_MODULUS_CRC`] for a stock signature,
-    /// `0` when `flags` is `0`.
+    /// CRC-32 of the `.pub`'s 256 modulus bytes; 0 when `flags` is 0.
     pub modulus_crc: u32,
     /// CRC-32 of the addon's `.url` string. `0` for every stock addon (none ship one).
     pub url_crc: u32,
 }
 
 impl SecureAddon<'_> {
-    /// A stock, signed Blizzard built-in: enabled signature, standard modulus, no URL. The shape
-    /// all twelve take on an unmodified install.
+    /// A stock signed built-in, the shape all twelve take on an unmodified install.
     const fn stock(name: &str) -> SecureAddon<'_> {
         SecureAddon {
             name,
@@ -109,20 +49,9 @@ impl SecureAddon<'_> {
     }
 }
 
-/// The twelve `Blizzard_*` built-ins a stock 1.12.1 install reports, in the order the client sends
-/// them (ascending ASCII of the folder name).
-///
-/// VERIFIED against a real 1.12.1.5875 client's `CMSG_AUTH_SESSION` captured against a live
-/// Blizzard server in 2006 (wow-5875-re `system/net/scratch/cmsg-auth-session-addon-block.md`):
-/// 342 uncompressed bytes, twelve records, every one `flags = 1`, `modulus_crc =`
-/// [`STANDARD_MODULUS_CRC`], `url_crc = 0`, and nothing left over — the arithmetic proof that the
-/// buffer carries no count and no trailer.
-///
-/// benilla sends this list rather than one derived from the install's own `Interface/AddOns`
-/// folder, and the two agree on every stock install: the client's rule is "`## Secure:` non-zero",
-/// which no third-party 1.12 addon sets, and benilla's own addons (loaded from
-/// `benilla-config/AddOns`) are third-party by construction. Reading each `.pub` off the player's
-/// chain would only differ on an install whose signature files have been altered — see 1497.
+/// The twelve `Blizzard_*` built-ins a stock 1.12.1 install reports, in the client's order
+/// (ascending ASCII). Deviation: a fixed list, not read off the install, because no third-party
+/// addon sets `## Secure:`, so the two differ only where the `.pub` files were altered.
 pub const STOCK_SECURE_ADDONS: [SecureAddon<'static>; 12] = [
     SecureAddon::stock("Blizzard_AuctionUI"),
     SecureAddon::stock("Blizzard_BattlefieldMinimap"),
@@ -138,7 +67,7 @@ pub const STOCK_SECURE_ADDONS: [SecureAddon<'static>; 12] = [
     SecureAddon::stock("Blizzard_TrainerUI"),
 ];
 
-/// The **uncompressed** addon buffer: one record per addon, concatenated, nothing else.
+/// The uncompressed addon buffer: the records concatenated, nothing else.
 pub fn addon_block(addons: &[SecureAddon]) -> Vec<u8> {
     let mut out = Vec::with_capacity(addons.iter().map(|a| a.name.len() + 10).sum());
     for addon in addons {
@@ -151,8 +80,7 @@ pub fn addon_block(addons: &[SecureAddon]) -> Vec<u8> {
     out
 }
 
-/// The block as it rides the wire: `u32` uncompressed size + the zlib stream, or **nothing at all**
-/// when there are no secure addons (what the real client does — it never emits a zero size).
+/// The block on the wire: `u32` size and the zlib stream, or nothing when there are no addons.
 pub fn addon_tail(addons: &[SecureAddon]) -> Vec<u8> {
     if addons.is_empty() {
         return Vec::new();
@@ -170,14 +98,13 @@ pub fn addon_tail(addons: &[SecureAddon]) -> Vec<u8> {
 mod tests {
     use super::*;
 
-    /// The retail ground truth: 342 uncompressed bytes, consumed exactly by twelve records.
+    /// The block has retail's 342-byte length and parses as twelve sorted, stock-signed records.
     #[test]
-    fn stock_block_matches_the_retail_capture() {
+    fn stock_block_has_the_retail_size_and_twelve_sorted_stock_records() {
         let plain = addon_block(&STOCK_SECURE_ADDONS);
         assert_eq!(plain.len(), 342, "retail sent 342 uncompressed bytes");
 
-        // Walk it back the way a server does — name, flags, modulus crc, url crc — and require it
-        // to land exactly on the end. That is what proves there is no count and no trailer.
+        // Parse it as a server does; landing exactly on the end proves no count and no trailer.
         let mut rest = &plain[..];
         let mut seen = Vec::new();
         while !rest.is_empty() {
@@ -206,9 +133,7 @@ mod tests {
         );
     }
 
-    /// The wire tail: size prefix, zlib framing, and the retail compressed length. `flate2` at its
-    /// default level reproduces the 2006 client's 130 bytes byte-for-byte — the real client used
-    /// `Z_DEFAULT_COMPRESSION` through the same zlib deflate.
+    /// `flate2`'s default is the reference's `Z_DEFAULT_COMPRESSION`, hence the retail 130 bytes.
     #[test]
     fn stock_tail_is_size_plus_zlib() {
         let tail = addon_tail(&STOCK_SECURE_ADDONS);
@@ -221,8 +146,6 @@ mod tests {
         assert_eq!(tail.len(), 4 + 130, "retail compressed to 130 bytes");
     }
 
-    /// Zero secure addons appends *nothing* — never a zero size, which no real client can emit and
-    /// which cmangos-classic kicks for.
     #[test]
     fn no_secure_addons_appends_nothing() {
         assert!(addon_tail(&[]).is_empty());
diff --git a/crates/benilla-protocol/src/messages/area_trigger.rs b/crates/benilla-protocol/src/messages/area_trigger.rs
index c7e24693..a8794a0b 100644
--- a/crates/benilla-protocol/src/messages/area_trigger.rs
+++ b/crates/benilla-protocol/src/messages/area_trigger.rs
@@ -1,37 +1,20 @@
-//! The area-trigger pair: the client's "I walked into trigger N" report, and the server's refusal
-//! text that sometimes comes back.
-//!
-//! An `AreaTrigger.dbc` volume means nothing to the client — it owns the geometry and nothing else.
-//! Walking into one sends [`area_trigger`] and the **server** decides what happens: a teleport
-//! (every instance entrance, the Darnassus/Rut'theran portals), a quest's explore objective, the
-//! inn's rested state, a battleground's entrance list. A teleport comes back as the ordinary
-//! `SMSG_TRANSFER_PENDING` + `SMSG_NEW_WORLD` pair (decision 0455) or a same-map
-//! `MSG_MOVE_TELEPORT_ACK`; a refusal comes back as [`read_area_trigger_message`]'s text.
+//! The area-trigger pair: the client's report of entering an `AreaTrigger.dbc` volume, and the
+//! server's refusal text. The server decides what a trigger does; a teleport arrives as
+//! `SMSG_TRANSFER_PENDING` and `SMSG_NEW_WORLD`, or a same-map `MSG_MOVE_TELEPORT_ACK`.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_u32_le};
 
-/// Body of `CMSG_AREATRIGGER` (opcode `0xB4`/180 — VERIFIED vmangos `Opcodes_1_12_1.h:183`, and the
-/// reference builds exactly this: `0x5e2110` writes `0xb4` then the record's first field, its id).
-/// One `u32`: the `AreaTrigger.dbc` id.
-///
-/// The server re-checks the claim before acting — `HandleAreaTriggerOpcode`
-/// (`Handlers/MiscHandler.cpp:622`) drops it unless the id is a real DBC row and the player is
-/// inside the volume with 5 yd of slop — so a stale or invented id costs nothing but is never
-/// obeyed. It is also dropped outright while taxi-flying.
+/// `CMSG_AREATRIGGER` (180, as `0x5e2110` sends it): the `u32` `AreaTrigger.dbc` id. The server
+/// obeys only a real row with the player inside the volume (5 yd slop), never while taxi-flying
+/// (`Handlers/MiscHandler.cpp:622`).
 pub fn area_trigger(trigger_id: u32) -> Vec<u8> {
     trigger_id.to_le_bytes().to_vec()
 }
 
-/// Read `SMSG_AREA_TRIGGER_MESSAGE` (VERIFIED vmangos `WorldSession::SendAreaTriggerMessage`,
-/// `Server/WorldSession.cpp:882-898`: `u32 length` then the cstring): server-composed text
-/// explaining why a trigger did *not* fire — "You must be at least level 58 to enter…", "You
-/// cannot enter %s while in ghost form.", a battleground's level/faction refusal.
-///
-/// The length prefix counts the cstring's bytes **including** its terminator; it is redundant with
-/// the string itself, and is read and discarded (the reference does the same — its `0x2b8` arm
-/// reads a u32, then a string, then displays the string).
+/// `SMSG_AREA_TRIGGER_MESSAGE` (`0x2b8`, `Server/WorldSession.cpp:882-898`): why a trigger did
+/// not fire, as a `u32` length (terminator included), which the reference ignores, then the text.
 pub(super) fn read_area_trigger_message(r: &mut &[u8]) -> io::Result<String> {
     let _length = read_u32_le(r)?;
     read_cstring(r)
@@ -46,7 +29,6 @@ mod tests {
         assert_eq!(area_trigger(542), 542u32.to_le_bytes().to_vec());
     }
 
-    /// The length prefix is skipped and the text read whole — built the way the server builds it.
     #[test]
     fn message_reads_past_its_length_prefix() {
         let text = "You must be at least level 58 to enter.";
diff --git a/crates/benilla-protocol/src/messages/attack.rs b/crates/benilla-protocol/src/messages/attack.rs
index 114e0490..b4bcbf2b 100644
--- a/crates/benilla-protocol/src/messages/attack.rs
+++ b/crates/benilla-protocol/src/messages/attack.rs
@@ -1,103 +1,53 @@
-//! Melee auto-attack messages — the attack start/stop edges, the per-swing damage report, and the
-//! creature-aggro notice. Split out of `messages/spells.rs` (decision 0640); mirrored by
-//! `world::writer::attack`.
-//!
-//! `SMSG_ATTACKERSTATEUPDATE` is the melee twin of [`super::combat_log`]'s spell reports: a *swing*
-//! reports itself here (fired exactly once per weapon-timer cycle, independently per hand — which is
-//! what makes it the animation driver, decision 0073), a *spell* reports itself there.
-//! `SMSG_AI_REACTION` rides along because it is the same moment from the creature's side: vmangos
-//! broadcasts it from `Unit::Attack`, i.e. the instant a creature decides to swing (decision 0277).
+//! Melee auto-attack messages: the attack start and stop edges, the per-swing report, and the
+//! creature-aggro notice, which vmangos sends from `Unit::Attack`.
 
 use std::io::{self, Read};
 
 use crate::wire::{read_f32_le, read_packed_guid, read_u32_le, read_u64_le, read_u8};
 
-/// Read `SMSG_ATTACKSTART` (vmangos `AttackStart::AppendBodyTo`): two full `u64` guids.
+/// `SMSG_ATTACKSTART` (vmangos `AttackStart::AppendBodyTo`): two full `u64` guids.
 pub(super) fn read_attack_start(r: &mut impl Read) -> io::Result<(u64, u64)> {
     Ok((read_u64_le(r)?, read_u64_le(r)?))
 }
 
-/// One decoded `SMSG_ATTACKERSTATEUPDATE` — a completed melee swing (vmangos
-/// `Unit::SendAttackStateUpdate`, `Unit.cpp:4572-4605`; fired **exactly once per weapon-timer
-/// cycle**, independently per hand — the real client plays one attacker swing animation per packet,
-/// wow-re `combat-swing-anim.md`, decision 0073). The per-school sub-damage split collapses to the
-/// packet's own `TotalDamage` plus the summed `absorb` (decision 0137 phase 2's floating combat
-/// text feed); `hit_info` bit `0x4` marks an **offhand** swing (the anim selector keys on it), bit
-/// `0x10000` suppresses the swing anim.
+/// `SMSG_ATTACKERSTATEUPDATE`: one melee swing (`Unit.cpp:4572-4605`), sent once per weapon-timer
+/// cycle per hand; the reference plays one swing animation per packet. `hit_info` bit `0x4` marks
+/// an offhand swing, bit `0x10000` suppresses the swing animation.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AttackerState {
     pub attacker: u64,
     pub victim: u64,
     pub hit_info: u32,
-    /// `TotalDamage` — the swing's damage before the sub-damage split.
+    /// `TotalDamage`: the whole swing, before the sub-damage split.
     pub damage: u32,
-    /// `TargetState` (vmangos `VictimState`): 1 hit · 2 dodge · 3 parry · 4 interrupt · 5 blocks ….
-    /// A defended outcome (dodge/parry/block/deflect) plays a dedicated victim defense clip at
-    /// the swing's `$CPP` keyframe (decision 0279, correcting 0073's "never a body animation");
-    /// landed hits flinch/bleed; the rest is sound + floating text.
+    /// `TargetState` (vmangos `VictimState`): 1 hit, 2 dodge, 3 parry, 4 interrupt, 5 blocks, …
     pub victim_state: u32,
-    /// Sum of the per-sub-damage `absorb` fields (vmangos writes exactly one sub-damage block in
-    /// practice; summed faithfully in case more than one ever rides the wire).
+    /// The sub-damage blocks' `absorb`, summed (vmangos writes one block).
     pub absorb: u32,
-    /// Sum of the per-sub-damage `resist` fields — the partial-resist trailer's amount
-    /// (decision 0580's center-text fold-back).
+    /// The sub-damage blocks' `resist`, summed: the partial-resist amount.
     pub resist: i32,
-    /// `BlockedAmount` — the trailing blocked-damage word.
+    /// `BlockedAmount`, the trailing blocked-damage word.
     pub blocked: u32,
-    /// `meleeSpellId` (`rec+0xac`) — **a boolean in practice, not an id.** Both of the client's
-    /// readers only compare it to zero (`0x625e40`, and `0x6246ca`'s `xor/cmp/sbb/neg` feeding
-    /// the swing-animation selector), so in this packet it means "this swing came from a spell".
-    /// Nonzero for an on-next-swing ability — Heroic Strike is the one the field was first
-    /// noticed on.
+    /// `meleeSpellId` (`rec+0xac`), nonzero for an on-next-swing ability such as Heroic Strike; the
+    /// reference only ever compares it to zero (`0x625e40`, `0x6246ca`).
     pub melee_spell_id: u32,
-    /// The **first** sub-damage block's school (`SpellSchools`: 0 physical … 6 arcane; vmangos
-    /// writes `GetFirstSchoolInMask(subDamage->damageSchoolMask)`), `0` when the swing carried no
-    /// sub-damage at all.
-    ///
-    /// It exists for the combat log's wording: a non-physical swing takes the `…SCHOOL` template
-    /// ("You hit X for 5 fire damage.") and physical takes the plain one. The floating text has
-    /// never needed it, which is why the field was read and dropped until B297.
+    /// The first sub-damage block's school (0 physical to 6 arcane, `GetFirstSchoolInMask`), 0
+    /// with no blocks; a non-physical swing takes the combat log's `…SCHOOL` wording.
     pub school: u8,
 }
 
 impl AttackerState {
-    /// `0x625e40` — **whether this swing is displayed at all**, in either of the two places that
-    /// display one. Twenty-six bytes:
-    ///
-    /// ```text
-    /// 625e40 mov  edx, [ecx+0xac]     ; meleeSpellId
-    /// 625e46 test edx, edx
-    /// 625e48 mov  eax, 1
-    /// 625e4d je   0x625e59            ; id == 0        -> TRUE
-    /// 625e4f cmp  [ecx+0xa4], eax     ; victimState vs 1
-    /// 625e55 je   0x625e59            ; state == 1     -> TRUE
-    /// 625e57 xor  eax, eax            ; otherwise      -> FALSE
-    /// ```
-    ///
-    /// **Two callers, and they are the two display paths**: `0x629b3e` in `0x629b10`, which skips
-    /// the whole chat dispatcher `0x629b60` — no line, no trailer, no `COMBAT_TEXT_UPDATE` — and
-    /// `0x62440d`, the first thing the **floating-combat-text builder** `0x6243e0` does, jumping
-    /// straight to its own epilogue. So a Heroic Strike that is dodged or parried produces neither
-    /// a combat-log line nor a floating number.
-    ///
-    /// **Untouched by it:** the swing animation (`0x6246a0`), the swing timers and autorepeat, the
-    /// auto-target arm, the tutorial trigger, and everything `0x624530` does after its call to
-    /// `0x6243e0` — the wound flinch, the blood spurt and the whole victimState-keyed sound block.
-    /// A suppressed swing still swings, still connects, still sounds.
-    ///
-    /// A landing ability (`victimState == 1`) is unaffected whatever its spell id, which is why
-    /// ordinary Heroic Strike damage reads normally.
+    /// `0x625e40`: whether the swing gets a combat-log line (`0x629b10`) and a floating number
+    /// (`0x6243e0`). A dodged or parried Heroic Strike gets neither, yet still animates and sounds.
     #[must_use]
     pub fn displayed(&self) -> bool {
         self.melee_spell_id == 0 || self.victim_state == 1
     }
 }
 
-/// Read `SMSG_ATTACKERSTATEUPDATE` (byte-verified order, attacker **PackGUID first** — settled by
-/// the wow-re §5 against the handler's downstream use, decision 0073): HitInfo · attacker PackGUID ·
-/// victim PackGUID · TotalDamage · SubDamageCount + per-sub `{school u32, damage f32, damage u32,
-/// absorb u32, resist i32}` · TargetState · two u32s (zero + "spell id, seen with heroic strike") ·
-/// BlockedAmount. TargetState is then normalized the way the handler normalizes it (`0x625e35`).
+/// `SMSG_ATTACKERSTATEUPDATE`: `HitInfo`, attacker then victim packed guid, `TotalDamage`, a `u8`
+/// count of `{school u32, damage f32, damage u32, absorb u32, resist i32}`, `TargetState`,
+/// `attackerState`, `meleeSpellId`, `BlockedAmount`.
 pub(super) fn read_attacker_state(r: &mut impl Read) -> io::Result<AttackerState> {
     let hit_info = read_u32_le(r)?;
     let attacker = read_packed_guid(r)?;
@@ -108,9 +58,7 @@ pub(super) fn read_attacker_state(r: &mut impl Read) -> io::Result<AttackerState
     let mut resist = 0i32;
     let mut school = 0u8;
     for i in 0..subs {
-        // damage f32 + damage u32 are folded into TotalDamage above; absorb/resist are summed. The
-        // school is kept from the FIRST block only — the wording takes one word, and vmangos's
-        // extra blocks are the off-school splits of the same swing.
+        // The school comes from the first block; later blocks split off other schools.
         let block_school = read_u32_le(r)?;
         if i == 0 {
             school = u8::try_from(block_school).unwrap_or(0);
@@ -121,22 +69,13 @@ pub(super) fn read_attacker_state(r: &mut impl Read) -> io::Result<AttackerState
         resist += read_u32_le(r)? as i32;
     }
     let victim_state = read_u32_le(r)?;
-    // vmangos names the tail `victimState · attackerState · meleeSpellId · blockedAmount`
-    // (`Server/Packets/Combat.cpp:81`), and the client's parse `0x625c60` stores them at
-    // `rec+0xa4`/`+0xa8`/`+0xac`/`+0xb0` in that order. `attackerState` is read by **nothing** in
-    // the whole combat TU; `meleeSpellId` is read twice and only ever compared to zero.
+    // The tail from `victimState` (`Server/Packets/Combat.cpp:81`) lands at `rec+0xa4`..`+0xb0`
+    // (`0x625c60`); the reference never reads `attackerState`.
     let _attacker_state = read_u32_le(r)?;
     let melee_spell_id = read_u32_le(r)?;
     let blocked = read_u32_le(r)?;
-    // **The handler does not trust the wire's TargetState for a full block** (`0x625e35`): a swing
-    // that got no damage through while blocking something is forced to `VICTIMSTATE_BLOCKS`,
-    // upstream of every consumer, which is why the display dispatcher's flag table has a `1` at an
-    // index its own earlier arm makes unreachable. Normalized here, in the same position — before
-    // the chat line, the floating word and the sound each read it.
-    //
-    // Against vmangos it is belt-and-braces: `Unit.cpp`'s `MELEE_HIT_BLOCK` arm already sets
-    // `VICTIMSTATE_BLOCKS` when `blocked_amount >= subDamage[0].damage`. It costs three lines and
-    // removes the client's dependence on a server doing so.
+    // The reference handler (`0x625e35`) turns a swing with no damage and a block into
+    // `VICTIMSTATE_BLOCKS` (5) before any consumer reads it; vmangos already sends it that way.
     let victim_state = if damage == 0 && blocked != 0 {
         5
     } else {
@@ -156,30 +95,21 @@ pub(super) fn read_attacker_state(r: &mut impl Read) -> io::Result<AttackerState
     })
 }
 
-/// The server's refusal of a `CMSG_ATTACKSWING` — the melee auto-attack answer that is not
-/// `SMSG_ATTACKSTART`. **Three variants for four opcodes, because that is what the client can
-/// distinguish**: the reference dispatches `0x145`/`0x146`/`0x148`/`0x149` through `0x6255b0`'s
-/// jump table `0x625aec`, and `0x148` DEADTARGET and `0x149` CANT_ATTACK land on **arm 4
-/// (`0x625ab8`) verbatim** — one shared body, no reason byte, nothing to tell them apart with.
-/// Collapsing them here is the fidelity fact in the type: a consumer cannot key on a difference
-/// the real client never had.
-///
-/// Every body is empty; the arms read nothing.
+/// The server's refusal of `CMSG_ATTACKSWING`; every body is empty. Four opcodes, three variants:
+/// the reference (`0x6255b0`) handles `0x148` and `0x149` in one shared arm.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AttackSwingError {
-    /// `SMSG_ATTACKSWING_NOTINRANGE` (`0x145`) — arm 2 `0x625a8a`: latch code **1**.
+    /// `SMSG_ATTACKSWING_NOTINRANGE` (`0x145`): the reference latches code 1 (`0x625a8a`).
     NotInRange,
-    /// `SMSG_ATTACKSWING_BADFACING` (`0x146`) — arm 3 `0x625aa1`: latch code **2**.
+    /// `SMSG_ATTACKSWING_BADFACING` (`0x146`): the reference latches code 2 (`0x625aa1`).
     BadFacing,
-    /// `SMSG_ATTACKSWING_DEADTARGET` (`0x148`) **or** `SMSG_ATTACKSWING_CANT_ATTACK` (`0x149`) —
-    /// both arm 4 `0x625ab8`, which raises **no message at all**: it resolves the active player
-    /// and calls StopAttack (`0x5ecac0`) on it, full stop. The name is deliberately the union of
-    /// the two: naming one of them would claim a distinction the client does not have.
+    /// `SMSG_ATTACKSWING_DEADTARGET` (`0x148`) or `SMSG_ATTACKSWING_CANT_ATTACK` (`0x149`): no
+    /// message, the reference only stops the attack (`0x625ab8`).
     DeadOrUnattackable,
 }
 
-/// Read `SMSG_ATTACKSTOP` (vmangos `AttackStop::AppendBodyTo`): two **packed** guids + a `u32`
-/// "victim is dead" word (dropped — death arrives through the descriptor seam).
+/// `SMSG_ATTACKSTOP` (`AttackStop::AppendBodyTo`): two packed guids and a `u32` victim-is-dead
+/// word, dropped because death arrives through the descriptor.
 pub(super) fn read_attack_stop(r: &mut impl Read) -> io::Result<(u64, u64)> {
     let attacker = read_packed_guid(r)?;
     let victim = read_packed_guid(r)?;
@@ -187,21 +117,17 @@ pub(super) fn read_attack_stop(r: &mut impl Read) -> io::Result<(u64, u64)> {
     Ok((attacker, victim))
 }
 
-/// Read `SMSG_AI_REACTION` → `(unit, reaction)` (vmangos `Creature::SendAIReaction`,
-/// `Objects/Creature.cpp:2490-2498` → `WorldPackets::Misc::AiReaction::AppendBodyTo`,
-/// `Server/Packets/Misc.cpp:445-449`): a raw (unpacked) `u64` guid + a `u32` reaction. Broadcast
-/// with reaction 2 (HOSTILE) on every creature melee-attack start (`Unit::Attack`) and 0 (ALERT)
-/// on stealth pre-aggro detection (`CreatureAI::TriggerAlertDirect`); 1/4 exist server-side but
-/// are never sent (decision 0277).
+/// `SMSG_AI_REACTION` (`Server/Packets/Misc.cpp:445-449`): a raw `u64` guid and a `u32` reaction,
+/// 2 (hostile) when a creature starts a melee attack, 0 (alert) on stealth detection; 1 and 4 are
+/// never sent.
 pub(super) fn read_ai_reaction(r: &mut impl Read) -> io::Result<(u64, u32)> {
     let unit = read_u64_le(r)?;
     let reaction = read_u32_le(r)?;
     Ok((unit, reaction))
 }
 
-/// Body of `CMSG_ATTACKSWING` (vmangos `AttackSwing::ReadFromWorldPacket`): one full `u64` victim
-/// guid. Starts melee auto-attack; the server answers `SMSG_ATTACKSTART` (or an attack-swing error
-/// packet). `CMSG_ATTACKSTOP`'s body is empty — no builder needed.
+/// `CMSG_ATTACKSWING`: the full `u64` victim guid, answered by `SMSG_ATTACKSTART` or an
+/// [`AttackSwingError`]. `CMSG_ATTACKSTOP` has an empty body.
 pub fn attack_swing(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
@@ -224,19 +150,12 @@ mod tests {
         b.extend_from_slice(&0u32.to_le_bytes()); // absorb
         b.extend_from_slice(&0u32.to_le_bytes()); // resist
         b.extend_from_slice(&victim_state.to_le_bytes()); // TargetState
-        b.extend_from_slice(&0u32.to_le_bytes()); // zero
-        b.extend_from_slice(&0u32.to_le_bytes()); // spell id
+        b.extend_from_slice(&0u32.to_le_bytes()); // attackerState
+        b.extend_from_slice(&0u32.to_le_bytes()); // meleeSpellId
         b.extend_from_slice(&blocked.to_le_bytes()); // BlockedAmount
         b
     }
 
-    /// `0x625e40` — a swing that came from a spell and did not land plainly is not displayed at
-    /// all, in either of the two places a swing is displayed.
-    ///
-    /// Heroic Strike is the case: it rides `SMSG_ATTACKERSTATEUPDATE` with a nonzero
-    /// `meleeSpellId`, so when it lands (`victimState == 1`) it reads exactly like a white hit,
-    /// and when it is dodged or parried the reference prints **no combat-log line and floats no
-    /// word**. An ordinary swing carries id 0 and is never touched by this.
     #[test]
     fn a_swing_from_a_spell_that_did_not_land_is_not_displayed() {
         let with_id = |state: u32| {
@@ -245,32 +164,23 @@ mod tests {
             b[at..at + 4].copy_from_slice(&78u32.to_le_bytes()); // Heroic Strike
             read_attacker_state(&mut b.as_slice()).expect("parse")
         };
-        // Dodged, parried, missed outright: suppressed.
+        // Every state but a hit (1) is suppressed.
         for state in [0, 2, 3, 4] {
             assert!(
                 !with_id(state).displayed(),
                 "spell swing, victimState {state}"
             );
         }
-        // Landed: displayed like any other hit.
         assert!(
             with_id(1).displayed(),
             "a landing Heroic Strike still shows"
         );
-        // A plain swing carries id 0 and is displayed whatever the victim did.
         for state in [0, 1, 2, 3, 4] {
             let s = read_attacker_state(&mut packet(0, state, 0).as_slice()).expect("parse");
             assert!(s.displayed(), "plain swing, victimState {state}");
         }
     }
 
-    /// `0x625e35` — a swing that got nothing through while blocking something **is** a block, and
-    /// the handler says so before any consumer reads the field.
-    ///
-    /// It matters because the display dispatcher's `victimState == 5` arm is what words `VSBLOCK`,
-    /// and its else-arm emits no line at all for the `1` the wire might otherwise carry — so
-    /// without this normalization a fully-blocked swing could go silent instead of reading
-    /// "X blocks your attack."
     #[test]
     fn a_fully_blocked_swing_is_normalized_to_victimstate_blocks() {
         let s = read_attacker_state(&mut packet(0, 1, 90).as_slice()).expect("parse");
diff --git a/crates/benilla-protocol/src/messages/auction.rs b/crates/benilla-protocol/src/messages/auction.rs
index 00a29db4..10d85fd1 100644
--- a/crates/benilla-protocol/src/messages/auction.rs
+++ b/crates/benilla-protocol/src/messages/auction.rs
@@ -1,144 +1,89 @@
-//! The auction house arc's wire layer (decision 1511 phase P0): the auctioneer hello, the three
-//! list pages (browse / your bids / your auctions), the sell/bid/cancel verbs, the one command
-//! verdict, and the three notifications (vmangos `Handlers/AuctionHouseHandler.cpp`,
-//! `AuctionHouse/AuctionHouseMgr.{h,cpp}`, `Server/Packets/AuctionHouse.{h,cpp}`,
-//! `Opcodes_1_12_1.h`, VERIFIED — read twice independently at decision time and re-read against
-//! the source while writing this module).
-//!
-//! **There is no `*_LIST_PENDING_SALES` opcode on 5875** — the symbol does not exist anywhere in
-//! vmangos's opcode tables (0x264/0x265 sit between `SMSG_SPELLORDAMAGE_IMMUNE` and
-//! `SMSG_SET_FLAT_SPELL_MODIFIER` with no gap for one), and the matching mail answer
-//! `AUCTION_SALE_PENDING(6)` is dead in the tree. The same shape of recorded fact as `mail`'s
-//! missing `SMSG_SHOW_MAILBOX`: a pane that exists in later clients has no wire here to build.
-//!
-//! Two things hold across every packet below. **Every guid is a plain 8-byte LE `u64`, never a
-//! packed guid** — vmangos's `ObjectGuid` stream operators write and read `GetRawValue()` whole
-//! (`ObjectGuid.cpp`), and `PackedGuid` never appears on the auction path. And **the auctioneer
-//! guid rides at the head of every CMSG** because the server re-validates the 5 yd interact
-//! distance on each one independently (`GetCheckedAuctionHouseForAuctioneer`): the hello is not a
-//! session token.
+//! The auction-house messages (vmangos `Server/Packets/AuctionHouse.cpp`): hello, the three list
+//! pages, sell, bid, cancel, the command result and three notifications; 5875 has no
+//! pending-sales opcode. Every guid is a plain `u64`, and the auctioneer guid heads every CMSG
+//! because the server re-checks the 5 yd interact distance on each one.
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_i32_le, read_u32_le, read_u64_le};
 
-/// `SMSG_AUCTION_COMMAND_RESULT`'s `action` field — which verb the verdict answers (VERIFIED
-/// vmangos `AuctionHouseMgr.h:53-58`, `AuctionAction`).
+/// `SMSG_AUCTION_COMMAND_RESULT`'s `action` (`AuctionAction`, `AuctionHouseMgr.h:53-58`).
 pub mod auction_action {
-    /// Answers [`super::auction_sell_item`] — a new listing was created.
+    /// Answers [`super::auction_sell_item`].
     pub const STARTED: u32 = 0;
-    /// Answers [`super::auction_remove_item`] — a listing was cancelled.
+    /// Answers [`super::auction_remove_item`].
     pub const REMOVED: u32 = 1;
-    /// Answers [`super::auction_place_bid`]. A *buyout* rides this action too: buyout is inferred
-    /// server-side (`price >= buyout && buyout != 0`), never flagged on the wire.
+    /// Answers [`super::auction_place_bid`], buyouts too (inferred, never flagged).
     pub const BID_PLACED: u32 = 2;
 }
 
-/// `SMSG_AUCTION_COMMAND_RESULT`'s `error` field (VERIFIED vmangos `AuctionHouseMgr.h:40-51`,
-/// `AuctionError`). **6, 8, 9, 11 and 12 have no name**: vmangos has no enumerator for them and
-/// never sends them, and the real client's `ERR_AUCTION_*` table falls through to a generic
-/// failure branch for anything it doesn't recognize — so an unknown code here is a generic
-/// refusal to report, not a parse failure.
+/// `SMSG_AUCTION_COMMAND_RESULT`'s `error` (`AuctionError`, `AuctionHouseMgr.h:40-51`). vmangos
+/// never sends 6, 8, 9, 11 or 12; the reference shows any unknown code as a generic failure.
 pub mod auction_error {
-    /// Success — read [`super::auction_action`] to know *what* succeeded.
     pub const OK: u32 = 0;
-    /// The only error carrying an [`super::AuctionCommandTail::Inventory`] tail: an
-    /// `InventoryResult` (`EQUIP_ERR_*`) code, the same table the bag/equip refusals use.
+    /// Carries an `EQUIP_ERR_*` tail ([`super::AuctionCommandTail::Inventory`]).
     pub const INVENTORY: u32 = 1;
-    /// `ERR_AUCTION_DATABASE_ERROR` — also vmangos's catch-all refusal (a bad `etime` lands here).
+    /// `ERR_AUCTION_DATABASE_ERROR`, also vmangos's catch-all (a bad `etime` lands here).
     pub const DATABASE: u32 = 2;
     pub const NOT_ENOUGH_MONEY: u32 = 3;
     pub const ITEM_NOT_FOUND: u32 = 4;
-    /// Someone outbid us mid-flight; carries the [`super::AuctionCommandTail::HigherBid`] tail.
+    /// Outbid in flight; carries the [`super::AuctionCommandTail::HigherBid`] tail.
     pub const HIGHER_BID: u32 = 5;
     /// The bid did not clear the minimum increment (5% of the current bid, floored, min 1 copper).
     pub const BID_INCREMENT: u32 = 7;
-    /// You cannot bid on your own auction.
     pub const BID_OWN: u32 = 10;
     pub const RESTRICTED_ACCOUNT: u32 = 13;
 }
 
-/// The "don't filter" sentinels [`auction_list_items`]'s browse filters use (VERIFIED vmangos
-/// `AuctionHouseObject::BuildListAuctionItems`, which compares each filter against exactly these
-/// before applying it — and takes a whole-table fast path when *all* of them are unset).
+/// The no-filter values of [`auction_list_items`] (`AuctionHouseObject::BuildListAuctionItems`,
+/// which takes a whole-table fast path when all are unset).
 pub mod auction_filter {
-    /// `slot_id` / `main_category` / `sub_category` / `quality`: `0xFFFF_FFFF` = no filter.
+    /// For `slot_id`, `main_category`, `sub_category` and `quality`.
     pub const ANY: u32 = 0xFFFF_FFFF;
-    /// `level_min` / `level_max`: `0` = no filter. The pair gates `RequiredLevel`, **not** item
-    /// level, and `level_max` is only consulted when `level_min` is set.
+    /// For `level_min`/`level_max`, which gate `RequiredLevel`; `level_max` needs `level_min`.
     pub const ANY_LEVEL: u8 = 0;
-    /// `usable`: `0` = no filter. Nonzero drops everything `CanUseItem` refuses (and recipes we
-    /// already know).
+    /// For `usable`; nonzero drops what `CanUseItem` refuses and recipes already known.
     pub const ANY_USABILITY: u8 = 0;
 }
 
-/// The three `etime` values `CMSG_AUCTION_SELL_ITEM` may carry, in **minutes** (VERIFIED vmangos
-/// `HandleAuctionSellItem`, `AuctionHouseHandler.cpp:281-296`: `etime * MINUTE` is switched
-/// against 1/4/12 × `MIN_AUCTION_TIME` — and `MIN_AUCTION_TIME` is `2*HOUR`). Anything else is
-/// refused with [`auction_error::DATABASE`]. The same 1/4/12 multiple also scales the deposit.
+/// The three `etime` values of `CMSG_AUCTION_SELL_ITEM`, in minutes: 1, 4 and 12 times the 2 h
+/// `MIN_AUCTION_TIME` (`AuctionHouseHandler.cpp:281-296`); the multiple also scales the deposit.
 pub mod auction_duration {
     pub const SHORT_MINUTES: u32 = 120;
     pub const MEDIUM_MINUTES: u32 = 480;
     pub const LONG_MINUTES: u32 = 1440;
 }
 
-/// Records per list page. Every server list builder stops at 50 (`count < 50`), so paging is
-/// `list_from = page * AUCTION_PAGE_SIZE` and the pager's "of N" comes from the list result's
-/// trailing `total_count`, which is counted *before* this cap.
+/// Records per list page (every server list builder stops at 50); `list_from` steps by it.
 pub const AUCTION_PAGE_SIZE: u32 = 50;
 
-/// One list-result record's fixed width: **64** bytes — twelve 4-byte fields plus the two 8-byte
-/// guids (`owner_guid`, `bidder_guid`). Decision 1511's prose says 60; that is an arithmetic slip
-/// in the summary, not in its field list, which sums to 64 (VERIFIED by re-reading the single
-/// producer, `AuctionEntry::BuildAuctionInfo`, `AuctionHouseMgr.cpp:811-842`, whose writes are
-/// `7×u32, u64, 4×u32, u64, u32`). Load-bearing rather than decorative — it is the bound
-/// [`read_auction_list_result`] uses to survive a body shorter than its own `count` claims.
+/// A list record's fixed width: `7×u32, u64, 4×u32, u64, u32` (`AuctionEntry::BuildAuctionInfo`,
+/// `AuctionHouseMgr.cpp:811-842`); it bounds the read of a body shorter than its `count`.
 pub const AUCTION_RECORD_BYTES: usize = 64;
 
-/// One row of any of the three auction list results. `SMSG_AUCTION_LIST_RESULT`,
-/// `SMSG_AUCTION_OWNER_LIST_RESULT` and `SMSG_AUCTION_BIDDER_LIST_RESULT` share **one** record
-/// layout and one frame — all three call the same producer (VERIFIED vmangos
-/// `AuctionEntry::BuildAuctionInfo`). Fixed width ([`AUCTION_RECORD_BYTES`]), no cstrings: the
-/// item's *name* is not on the wire at all, and comes from the ordinary item-template cache.
+/// One row of any of the three list results; the item name is not on the wire.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AuctionListEntry {
-    /// The auction's server id — the handle [`auction_place_bid`]/[`auction_remove_item`] name.
     pub auction_id: u32,
     pub item_entry: u32,
-    /// `PERM_ENCHANTMENT_SLOT` only. 1.12 carries no other enchant information on an auction row:
-    /// vmangos's own `[-ZERO] no other infos about enchantment in 1.12 [?]` comment sits on the
-    /// commented-out loop that would have written the durations and charges a later client reads.
+    /// The `PERM_ENCHANTMENT_SLOT` enchant, the only enchant a 1.12 auction row carries.
     pub perm_enchant: u32,
-    /// **Signed** — negative is a random *suffix* id, positive a random *property* id.
-    /// `Item::GetItemRandomPropertyId` returns `int32` and the server casts it through `uint32`,
-    /// so the wire bytes are a two's-complement `i32` and reading them unsigned turns every
-    /// suffixed item ("of the Bear") into a ~4.29-billion property id that resolves to nothing.
+    /// Signed: negative is a random suffix id, positive a random property id.
     pub random_property_id: i32,
     pub suffix_factor: u32,
     /// The stack size.
     pub count: u32,
-    /// **Signed** — a negative charge count means "N charges, then destroy the item".
-    /// `Item::GetSpellCharges` returns `int32` and the server casts it through `uint32` (its own
-    /// comment on the line reads `item->charge FFFFFFF`).
+    /// Signed: negative means that many charges, then the item is destroyed (`GetSpellCharges`).
     pub spell_charges: i32,
     pub owner_guid: u64,
-    /// The seller's **opening** price, captured at listing time and constant for the auction's
-    /// life. NOT the current bid ([`Self::current_bid`]) and not the minimum next bid — vmangos's
-    /// own field comment calls it "maybe useless", but it *is* what the first bid must meet.
+    /// The seller's opening price, fixed for the auction's life: what the first bid must meet.
     pub start_bid: u32,
-    /// How much above [`Self::current_bid`] the next bid must go: 5% of the current bid, floored,
-    /// minimum 1 copper. **`0` while nobody has bid** — the server writes
-    /// `bid ? GetAuctionOutBid() : 0`, so a UI must fall back to [`Self::start_bid`] for the
-    /// opening bid rather than reading a `0` here as "any amount will do".
+    /// The next bid's step over [`Self::current_bid`] (5%, floored, min 1); 0 before any bid.
     pub min_increment: u32,
-    /// `0` = no buyout. Buyout is *inferred*, never flagged: a bid of `>= buyout` on a nonzero
-    /// buyout is a buyout.
+    /// 0 for none; a bid of at least a nonzero buyout is a buyout.
     pub buyout: u32,
-    /// **Milliseconds** remaining, and **unclamped**. The server writes
-    /// `(expireTime - now) * IN_MILLISECONDS` with no floor and only sweeps expiry on its own
-    /// timer, so an expired-but-still-listed auction wraps to a value near 4.29 billion. Read
-    /// faithfully here — a consumer must treat an implausibly large value as **expired**, not as
-    /// "very long".
+    /// Milliseconds left, unclamped: an expired auction not yet swept wraps to near 2^32, which a
+    /// consumer must read as expired.
     pub time_left_ms: u32,
     /// `0` = nobody has bid.
     pub bidder_guid: u64,
@@ -146,22 +91,17 @@ pub struct AuctionListEntry {
     pub current_bid: u32,
 }
 
-/// The conditional tail `SMSG_AUCTION_COMMAND_RESULT` carries after its three dwords — which
-/// shape follows is decided by `error` first and `action` only inside the `OK` arm (VERIFIED
-/// vmangos `WorldSession::SendAuctionCommandResult`, `AuctionHouseHandler.cpp:70-96`, whose
-/// `switch` is on the error code).
+/// The tail after `SMSG_AUCTION_COMMAND_RESULT`'s three dwords, chosen by `error`, then by
+/// `action` only on success (`AuctionHouseHandler.cpp:70-96`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AuctionCommandTail {
-    /// Every other (error, action) pair — the three dwords are the whole packet. This is the
-    /// common case: a plain `OK` + `STARTED`/`REMOVED`, and every named error but two.
+    /// Every other pair: the three dwords are the whole packet.
     Empty,
-    /// [`auction_error::OK`] **and** [`auction_action::BID_PLACED`]: the outbid step the *next*
-    /// bid must clear, recomputed from the bid just accepted.
+    /// A placed bid: the step the next bid must clear, from the bid just accepted.
     BidPlaced { new_min_outbid: u32 },
     /// [`auction_error::INVENTORY`]: an `InventoryResult` (`EQUIP_ERR_*`) code.
     Inventory { result: u32 },
-    /// [`auction_error::HIGHER_BID`]: we were outbid between reading the page and bidding — who
-    /// holds it now, at what bid, and the step the next bid must clear.
+    /// [`auction_error::HIGHER_BID`]: who outbid us, at what bid, and the next step to clear.
     HigherBid {
         new_bidder_guid: u64,
         new_bid: u32,
@@ -169,67 +109,46 @@ pub enum AuctionCommandTail {
     },
 }
 
-/// `SMSG_AUCTION_BIDDER_NOTIFICATION` — "you won" / "you were outbid", pushed to the *bidder*
-/// (VERIFIED vmangos `AuctionBidderNotification::AppendBodyTo`,
-/// `Server/Packets/AuctionHouse.cpp:78-87`). Deliberately **not** the same shape as
-/// [`AuctionOwnerNotification`]: this one leads with the house id and puts the guid third, the
-/// owner one has no house id and puts the guid fourth. Two structs and two readers, on purpose —
-/// sharing either would silently mis-decode one of them.
+/// `SMSG_AUCTION_BIDDER_NOTIFICATION`, won or outbid (`Server/Packets/AuctionHouse.cpp:78-87`);
+/// it leads with the house id and has the guid third, unlike the owner notice.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AuctionBidderNotification {
-    /// `AuctionHouse.dbc` row (1..7) — the same id [`read_auction_hello`] answers with.
+    /// `AuctionHouse.dbc` row (1..7), as in the hello reply.
     pub house_id: u32,
     pub auction_id: u32,
-    /// The bidder the notice is *about* — us.
     pub bidder_guid: u64,
-    /// **`0` means WON**, not "no bid" (vmangos writes `won ? 0 : auction->bid`, and the real
-    /// client branches `ERR_AUCTION_WON_S` vs `ERR_AUCTION_OUTBID_S` on exactly this). Nonzero is
-    /// the bid that beat us.
+    /// 0 means won (`won ? 0 : auction->bid`); otherwise the bid that beat us.
     pub bid_or_zero: u32,
     /// The step the next bid must clear (`GetAuctionOutBid()`).
     pub out_bid: u32,
     pub item_entry: u32,
-    /// **Signed**, as on [`AuctionListEntry::random_property_id`] — the same
-    /// `Item::GetItemRandomPropertyId()` value, cast through vmangos's `uint32` packet field.
-    /// `0` when the item is gone.
+    /// Signed, as on [`AuctionListEntry::random_property_id`]; 0 when the item is gone.
     pub random_property_id: i32,
 }
 
-/// `SMSG_AUCTION_OWNER_NOTIFICATION` — "your auction sold" / a bid landed, pushed to the *seller*
-/// (VERIFIED vmangos `AuctionOwnerNotification::AppendBodyTo`,
-/// `Server/Packets/AuctionHouse.cpp:89-97`). **No `house_id`, and the guid sits fourth** — see
-/// [`AuctionBidderNotification`] for why the two are kept apart.
+/// `SMSG_AUCTION_OWNER_NOTIFICATION`, a sale or a new bid, to the seller
+/// (`Server/Packets/AuctionHouse.cpp:89-97`): no house id, and the guid fourth.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AuctionOwnerNotification {
     pub auction_id: u32,
-    /// The current bid.
     pub bid: u32,
     /// The step the next bid must clear (`GetAuctionOutBid()`).
     pub out_bid: u32,
-    /// Who bid. **All-zero on a sale**: vmangos fills this field only when the auction has *not*
-    /// sold yet (`if (!sold)`), so a zero guid here is the "sold" signal, not a missing bidder.
+    /// Who bid; zero on a sale, since vmangos fills it only `if (!sold)`.
     pub bidder_guid: u64,
     pub item_entry: u32,
-    /// **Signed**, as on [`AuctionListEntry::random_property_id`]. `0` when the item is gone.
+    /// Signed, as on [`AuctionListEntry::random_property_id`]; 0 when the item is gone.
     pub random_property_id: i32,
 }
 
-/// Body of `MSG_AUCTION_HELLO` (VERIFIED vmangos `AuctionHello::ReadFromWorldPacket`,
-/// `Server/Packets/AuctionHouse.cpp:3-6`): one full 8-byte auctioneer guid. **Same opcode both
-/// directions** — the reply ([`read_auction_hello`]) echoes the guid and adds the house id, and it
-/// is the *reply* that opens the window, not our send.
+/// `MSG_AUCTION_HELLO` (`Server/Packets/AuctionHouse.cpp:3-6`): the auctioneer guid. The same
+/// opcode comes back with the house id ([`read_auction_hello`]), and that reply opens the window.
 pub fn auction_hello(auctioneer: u64) -> Vec<u8> {
     auctioneer.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_AUCTION_SELL_ITEM` (VERIFIED vmangos `AuctionSellItem::ReadFromWorldPacket`,
-/// `Server/Packets/AuctionHouse.cpp:42-49`): `u64 auctioneer, u64 itemGuid, u32 bid, u32 buyout,
-/// u32 etime`.
-///
-/// `etime_minutes` may only be one of [`auction_duration`]'s three values; anything else is
-/// refused with [`auction_error::DATABASE`]. A `bid` or `etime_minutes` of `0` is answered with
-/// **nothing at all** (`HandleAuctionSellItem`'s silent `return`), as is a bid the player cannot
-/// pay the deposit for — a UI that blocks waiting for an ack will hang.
+/// `CMSG_AUCTION_SELL_ITEM`: an `etime_minutes` outside [`auction_duration`] gets `DATABASE`; a
+/// zero `bid` or `etime`, or an unaffordable deposit, gets no answer (`HandleAuctionSellItem`).
 pub fn auction_sell_item(
     auctioneer: u64,
     item_guid: u64,
@@ -246,11 +165,8 @@ pub fn auction_sell_item(
     body
 }
 
-/// Body of `CMSG_AUCTION_REMOVE_ITEM` (VERIFIED vmangos `AuctionRemoveItem::ReadFromWorldPacket`,
-/// `Server/Packets/AuctionHouse.cpp:36-40`): `u64 auctioneer, u32 auctionId` — the seller's
-/// cancel. Answered by `SMSG_AUCTION_COMMAND_RESULT` (action [`auction_action::REMOVED`]) *except*
-/// when the auction already carries a bid and the seller cannot pay the 5% cut out of pocket, in
-/// which case the server refuses **silently**.
+/// `CMSG_AUCTION_REMOVE_ITEM` (`Server/Packets/AuctionHouse.cpp:36-40`), the seller's cancel. A
+/// seller who cannot pay the 5% cut on an auction with a bid gets no answer at all.
 pub fn auction_remove_item(auctioneer: u64, auction_id: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(8 + 4);
     body.extend_from_slice(&auctioneer.to_le_bytes());
@@ -258,24 +174,9 @@ pub fn auction_remove_item(auctioneer: u64, auction_id: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_AUCTION_LIST_ITEMS` — the Browse tab's search (VERIFIED vmangos
-/// `AuctionListItems::ReadFromWorldPacket`, `Server/Packets/AuctionHouse.cpp:51-63`): `u64
-/// auctioneer, u32 listfrom, cstr searchedname, u8 levelmin, u8 levelmax, u32 auctionSlotID, u32
-/// auctionMainCategory, u32 auctionSubCategory, u32 quality, u8 usable`.
-///
-/// **Ten fields and nothing else: no sort columns, no sort count, no trailing padding.** That is
-/// the field an implementer invents, because later expansions do carry sort bytes here — on 5875
-/// *filtering* is entirely server-side and *sorting* is entirely client-side. (Corroborated
-/// beyond the reader: vmangos runs `VerifyPacketWasCorrectlyRead` after every `ClientPacket`
-/// parse and error-logs a body it did not consume to the end, which a real 5875 client appending
-/// sort bytes would trip on every search.)
-///
-/// The sentinels are in [`auction_filter`]: `0xFFFF_FFFF` for the four u32 filters, `0` for the
-/// three small ones, and an empty `searched_name` is just the lone NUL. `quality` is a
-/// **minimum**, not an equality (`proto->Quality < query.quality` is what drops a row).
-/// `level_min`/`level_max` gate `RequiredLevel`, not item level. The name match is a
-/// case-insensitive substring against the localized name *with the random-property suffix
-/// appended*. `list_from` pages by [`AUCTION_PAGE_SIZE`].
+/// `CMSG_AUCTION_LIST_ITEMS` (`Server/Packets/AuctionHouse.cpp:51-63`): ten fields, no sort
+/// bytes (5875 sorts on the client). `quality` is a minimum; the name is a case-insensitive
+/// substring match on the localized name plus its random-property suffix.
 pub fn auction_list_items(
     auctioneer: u64,
     list_from: u32,
@@ -303,10 +204,8 @@ pub fn auction_list_items(
     body
 }
 
-/// Body of `CMSG_AUCTION_LIST_OWNER_ITEMS` — the Auctions tab (VERIFIED vmangos
-/// `AuctionListOwnerItems::ReadFromWorldPacket`, `Server/Packets/AuctionHouse.cpp:23-27`): `u64
-/// auctioneer, u32 listfrom`. Answered by `SMSG_AUCTION_OWNER_LIST_RESULT`. The server matches on
-/// the **account**, then filters to this character's guid.
+/// `CMSG_AUCTION_LIST_OWNER_ITEMS`, the Auctions tab (`Server/Packets/AuctionHouse.cpp:23-27`);
+/// the server matches the account, then filters to this character.
 pub fn auction_list_owner_items(auctioneer: u64, list_from: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(8 + 4);
     body.extend_from_slice(&auctioneer.to_le_bytes());
@@ -314,10 +213,8 @@ pub fn auction_list_owner_items(auctioneer: u64, list_from: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_AUCTION_PLACE_BID` (VERIFIED vmangos `AuctionPlaceBid::ReadFromWorldPacket`,
-/// `Server/Packets/AuctionHouse.cpp:29-34`): `u64 auctioneer, u32 auctionId, u32 price`. The
-/// buyout verb too — send `price = buyout` and the server takes it as one; there is no separate
-/// opcode and no flag. A bid the player cannot afford is refused **silently**.
+/// `CMSG_AUCTION_PLACE_BID` (`Server/Packets/AuctionHouse.cpp:29-34`), also the buyout: a `price`
+/// equal to the buyout is one. An unaffordable bid gets no answer at all.
 pub fn auction_place_bid(auctioneer: u64, auction_id: u32, price: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(8 + 4 + 4);
     body.extend_from_slice(&auctioneer.to_le_bytes());
@@ -326,15 +223,9 @@ pub fn auction_place_bid(auctioneer: u64, auction_id: u32, price: u32) -> Vec<u8
     body
 }
 
-/// Body of `CMSG_AUCTION_LIST_BIDDER_ITEMS` — the Bid tab (VERIFIED vmangos
-/// `AuctionListBidderItem::ReadFromWorldPacket`, `Server/Packets/AuctionHouse.cpp:8-21`): `u64
-/// auctioneer, u32 listfrom, u32 count`, then `count` × `u32 auctionId`.
-///
-/// The trailing id list is a **refresh set**, not a filter: the server emits a record for each id
-/// named here *first* and then appends every auction this player is the current bidder on, both
-/// feeding one `count`/`total_count` — so an id that is also still ours appears twice in the page.
-/// Send it empty (`&[]`) for a plain page fetch; the reference client fills it with the auctions
-/// it has been outbid on so their rows re-sync.
+/// `CMSG_AUCTION_LIST_BIDDER_ITEMS`, the Bid tab (`Server/Packets/AuctionHouse.cpp:8-21`). The
+/// ids are a refresh set, not a filter: the server lists them first, then every auction we lead,
+/// in one page, so an id in both appears twice. The reference sends those it was outbid on.
 pub fn auction_list_bidder_items(auctioneer: u64, list_from: u32, auction_ids: &[u32]) -> Vec<u8> {
     let mut body = Vec::with_capacity(8 + 4 + 4 + 4 * auction_ids.len());
     body.extend_from_slice(&auctioneer.to_le_bytes());
@@ -346,21 +237,12 @@ pub fn auction_list_bidder_items(auctioneer: u64, list_from: u32, auction_ids: &
     body
 }
 
-/// Read `MSG_AUCTION_HELLO`'s **reply** (VERIFIED vmangos `AuctionHelloResponse::AppendBodyTo`,
-/// `Server/Packets/AuctionHouse.cpp:72-76`): `u64 auctioneerGuid, u32 houseId`. Nothing follows
-/// the house id on 5875.
-///
-/// `house_id` indexes `AuctionHouse.dbc` (rows 1..7: the six faction houses, then Blackwater at 7)
-/// and is the field the sell pane needs — the deposit and cut rates are read out of that row, so a
-/// window that assumes a house shows the neutral 25% where it should show 5%. It is also the id
-/// the auction invoice mails arrive under (`MailListEntry::sender_id` on a
-/// [`super::mail_message_type::AUCTION`] mail).
+/// The `MSG_AUCTION_HELLO` reply (`Server/Packets/AuctionHouse.cpp:72-76`): the guid and the
+/// `AuctionHouse.dbc` house id (1..7), whose row sets the deposit and cut rates.
 pub(super) fn read_auction_hello(r: &mut &[u8]) -> io::Result<(u64, u32)> {
     Ok((read_u64_le(r)?, read_u32_le(r)?))
 }
 
-/// One [`AuctionListEntry`] — [`AUCTION_RECORD_BYTES`] of fixed-width fields, 14 reads, in
-/// `AuctionEntry::BuildAuctionInfo`'s order.
 fn read_auction_list_entry(r: &mut &[u8]) -> io::Result<AuctionListEntry> {
     Ok(AuctionListEntry {
         auction_id: read_u32_le(r)?,
@@ -380,39 +262,19 @@ fn read_auction_list_entry(r: &mut &[u8]) -> io::Result<AuctionListEntry> {
     })
 }
 
-/// Read the body all three list results share — `SMSG_AUCTION_LIST_RESULT`,
-/// `SMSG_AUCTION_OWNER_LIST_RESULT`, `SMSG_AUCTION_BIDDER_LIST_RESULT` (VERIFIED vmangos's async
-/// `AuctionHouseClientQueryTask`, `AuctionHouseHandler.cpp:651-701`, which builds all three and
-/// differs only in `SetOpcode`): `u32 count`, then `count` × [`AuctionListEntry`], then `u32
-/// totalCount`.
-///
-/// **`total_count` rides at the very END, after the records.** The leading `count` is written as
-/// a placeholder and patched with `put<uint32>` once the records are in; the total is appended
-/// last. It is the match count *before* the [`AUCTION_PAGE_SIZE`] cap — the pager's "of N" — so
-/// it is routinely larger than the number of records, and reading it in the wrong place silently
-/// yields a record field.
-///
-/// Returns `(records, total_count)`.
+/// The body the three list results share (`AuctionHouseHandler.cpp:651-701`): `u32 count`, the
+/// records, then `u32 totalCount`, the match count before the page cap, at the very end.
 pub(super) fn read_auction_list_result(r: &mut &[u8]) -> io::Result<(Vec<AuctionListEntry>, u32)> {
     let count = read_u32_le(r)?;
-    // Bound the allocation by what the buffer could actually hold, not by a `count` we do not
-    // trust (see the loop guard below).
     let mut auctions = Vec::with_capacity(capacity_hint(count, r.len() / AUCTION_RECORD_BYTES));
     for _ in 0..count {
-        // `count` is an UPPER BOUND, not a record count. vmangos's *browse fast
-        // path* (the no-filter branch of `BuildListAuctionItems`, `AuctionHouseMgr.cpp:716-735`)
-        // does `BuildAuctionInfo(data); if ((++count) >= 50) break;` — discarding a `false`
-        // return. A stale auction whose item row is gone therefore writes ZERO bytes and still
-        // counts, so a real server sends `count = N` with N-k records. Stop cleanly on a short
-        // buffer and return what we did get: the layout is fixed-width, so a dropped record
-        // shifts nothing, and every record we read is intact.
+        // `count` is an upper bound: vmangos's no-filter path (`AuctionHouseMgr.cpp:716-735`)
+        // counts an auction whose item is gone but writes no bytes for it.
         if r.len() < AUCTION_RECORD_BYTES {
             break;
         }
         auctions.push(read_auction_list_entry(r)?);
     }
-    // A body truncated past the last record has no trailing total either; fall back to what we
-    // actually read rather than failing the whole page over the pager's hint.
     let total_count = if r.len() >= 4 {
         read_u32_le(r)?
     } else {
@@ -421,24 +283,14 @@ pub(super) fn read_auction_list_result(r: &mut &[u8]) -> io::Result<(Vec<Auction
     Ok((auctions, total_count))
 }
 
-/// Read `SMSG_AUCTION_COMMAND_RESULT` (VERIFIED vmangos `WorldSession::SendAuctionCommandResult`,
-/// `AuctionHouseHandler.cpp:70-96`): `u32 auctionId, u32 action ([`auction_action`]), u32 error
-/// ([`auction_error`])`, then the conditional [`AuctionCommandTail`] the error selects.
-///
-/// `auction_id` is **`0`** whenever the server had no `AuctionEntry` to name — which is most of
-/// the failure paths, so it is not a usable correlation handle on an error. The
-/// remaining-length guard on each tail mirrors `read_send_mail_result`: a body that doesn't carry
-/// the tail its fields predict decodes as [`AuctionCommandTail::Empty`] rather than erroring.
-///
-/// Returns `(auction_id, action, error, tail)`.
+/// `SMSG_AUCTION_COMMAND_RESULT` (`AuctionHouseHandler.cpp:70-96`): `u32` auction id, action,
+/// error, then the [`AuctionCommandTail`]; the auction id is 0 on most failures.
 pub(super) fn read_auction_command_result(
     r: &mut &[u8],
 ) -> io::Result<(u32, u32, u32, AuctionCommandTail)> {
     let auction_id = read_u32_le(r)?;
     let action = read_u32_le(r)?;
     let error = read_u32_le(r)?;
-    // The server switches on `error`; only its OK arm then looks at `action`. Mirror that order —
-    // an OK with any other action carries no tail at all.
     let tail = match error {
         auction_error::OK if action == auction_action::BID_PLACED && !r.is_empty() => {
             AuctionCommandTail::BidPlaced {
@@ -458,11 +310,6 @@ pub(super) fn read_auction_command_result(
     Ok((auction_id, action, error, tail))
 }
 
-/// Read `SMSG_AUCTION_BIDDER_NOTIFICATION` (VERIFIED vmangos
-/// `AuctionBidderNotification::AppendBodyTo`, `Server/Packets/AuctionHouse.cpp:78-87`): `u32
-/// houseId, u32 auctionId, u64 bidderGuid, u32 bidOrZero, u32 outBid, u32 itemEntry, i32
-/// randomPropertyId`. **Not interchangeable with [`read_auction_owner_notification`]** — see
-/// [`AuctionBidderNotification`].
 pub(super) fn read_auction_bidder_notification(
     r: &mut &[u8],
 ) -> io::Result<AuctionBidderNotification> {
@@ -477,10 +324,6 @@ pub(super) fn read_auction_bidder_notification(
     })
 }
 
-/// Read `SMSG_AUCTION_OWNER_NOTIFICATION` (VERIFIED vmangos
-/// `AuctionOwnerNotification::AppendBodyTo`, `Server/Packets/AuctionHouse.cpp:89-97`): `u32
-/// auctionId, u32 bid, u32 outBid, u64 bidderGuid, u32 itemEntry, i32 randomPropertyId` — a
-/// different field order from the bidder notification, and no house id.
 pub(super) fn read_auction_owner_notification(
     r: &mut &[u8],
 ) -> io::Result<AuctionOwnerNotification> {
@@ -494,12 +337,8 @@ pub(super) fn read_auction_owner_notification(
     })
 }
 
-/// Read `SMSG_AUCTION_REMOVED_NOTIFICATION` (VERIFIED vmangos
-/// `AuctionRemovedNotification::AppendBodyTo`, `Server/Packets/AuctionHouse.cpp:65-70`): `u32
-/// auctionId, u32 itemEntry, i32 randomPropertyId` — pushed to a *bidder* whose auction the seller
-/// cancelled (the real client shows `ERR_AUCTION_REMOVED_S`).
-///
-/// Returns `(auction_id, item_entry, random_property_id)`.
+/// `SMSG_AUCTION_REMOVED_NOTIFICATION` (`Server/Packets/AuctionHouse.cpp:65-70`), to a bidder
+/// whose auction was cancelled: `(auction_id, item_entry, random_property_id)`.
 pub(super) fn read_auction_removed_notification(r: &mut &[u8]) -> io::Result<(u32, u32, i32)> {
     Ok((read_u32_le(r)?, read_u32_le(r)?, read_i32_le(r)?))
 }
diff --git a/crates/benilla-protocol/src/messages/bank.rs b/crates/benilla-protocol/src/messages/bank.rs
index df38f476..fbb4150f 100644
--- a/crates/benilla-protocol/src/messages/bank.rs
+++ b/crates/benilla-protocol/src/messages/bank.rs
@@ -1,19 +1,11 @@
-//! Bank messages — the six-opcode wire (`CMSG_BANKER_ACTIVATE`/`SMSG_SHOW_BANK`/
-//! `CMSG_BUY_BANK_SLOT`/`SMSG_BUY_BANK_SLOT_RESULT`/`CMSG_AUTOSTORE_BANK_ITEM`/
-//! `CMSG_AUTOBANK_ITEM`, opcodes 439-442,642-643, vmangos `Opcodes_1_12_1.h`, VERIFIED). Bodies
-//! from vmangos `Server/Packets/Npc.{h,cpp}` + `Server/Packets/Item.{h,cpp}`, all read this
-//! session. Decision 0604 — the vault itself is already streamed through the ordinary player
-//! descriptor (bank slots 39–62, bank bags 63–68); these opcodes only open the window, buy a bag
-//! slot, and move items in/out.
+//! Bank messages: open the window, buy a bag slot, move items in and out. The vault itself
+//! streams in the player descriptor (bank slots 39-62, bank bags 63-68).
 
 use std::io;
 
 use crate::wire::{read_u32_le, read_u64_le};
 
-/// `SMSG_BUY_BANK_SLOT_RESULT`'s `u32` reason (vmangos `Player.h:91-94`,
-/// `BANK_SLOT_*` enum). Sent only on failure — success is signaled purely by the
-/// `PLAYER_BYTES_2` bank-bag-count byte advancing + the coinage delta, both via `UPDATE_OBJECT`
-/// (decision 0604).
+/// `SMSG_BUY_BANK_SLOT_RESULT`'s reason (`BANK_SLOT_*`, vmangos `Player.h:91-94`).
 pub mod bank_slot_result {
     pub const FAILED_TOO_MANY: u32 = 0;
     pub const INSUFFICIENT_FUNDS: u32 = 1;
@@ -21,49 +13,37 @@ pub mod bank_slot_result {
     pub const OK: u32 = 3;
 }
 
-/// Body of `CMSG_BANKER_ACTIVATE` (vmangos `Npc.h:58-66`): one full 8-byte banker guid. Sent on a
-/// right-click of a *pure* banker (bits 0-7 of `UNIT_NPC_FLAGS` clear, bit 8 `0x100` set) — a
-/// gossip-flagged banker instead opens the gossip menu and the bank arrives through the
-/// `GOSSIP_OPTION_BANKER` option's own `SMSG_SHOW_BANK` (decision 0604).
+/// `CMSG_BANKER_ACTIVATE` (vmangos `Npc.h:58-66`), for a pure banker (`UNIT_NPC_FLAGS` bit 8
+/// `0x100` set, bits 0-7 clear); a gossip banker opens its bank through the gossip option.
 pub fn banker_activate(banker_guid: u64) -> Vec<u8> {
     banker_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_BUY_BANK_SLOT` (vmangos `Item.h:157-163`): one full 8-byte banker guid. The
-/// server buys slot `purchased_count + 1` itself (no slot index on the wire) — the client's job
-/// is only knowing the next price, read from `BankBagSlotPrices.dbc` by `benilla-formats`
-/// (decision 0604).
+/// `CMSG_BUY_BANK_SLOT` (vmangos `Item.h:157-163`): no slot index, the server buys the next one;
+/// its price is in `BankBagSlotPrices.dbc`.
 pub fn buy_bank_slot(banker_guid: u64) -> Vec<u8> {
     banker_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_AUTOBANK_ITEM` (vmangos `Item.h:108-116`): `u8 srcbag, u8 srcslot`. Deposit
-/// only — moves a non-bank item into the first free bank slot. Handler
-/// `HandleAutoBankItemOpcode` (`ItemHandler.cpp:874`).
+/// `CMSG_AUTOBANK_ITEM` (`ItemHandler.cpp:874`): deposit only, into the first free bank slot.
 pub fn autobank_item(bag: u8, slot: u8) -> Vec<u8> {
     vec![bag, slot]
 }
 
-/// Body of `CMSG_AUTOSTORE_BANK_ITEM` (vmangos `Item.h:118-126`): `u8 srcbag, u8 srcslot`.
-/// Direction-tolerant: vmangos's `HandleAutoStoreBankItemOpcode` (`ItemHandler.cpp:971`)
-/// withdraws to inventory when `srcbag`/`srcslot` name a bank position, else deposits — the same
-/// opcode drives both halves of the reference client's right-click auto-move while the bank
-/// window is open.
+/// `CMSG_AUTOSTORE_BANK_ITEM` (`ItemHandler.cpp:971`): withdraws from a bank position, deposits
+/// from anywhere else; the reference's right-click auto-move uses it both ways.
 pub fn autostore_bank_item(bag: u8, slot: u8) -> Vec<u8> {
     vec![bag, slot]
 }
 
-/// Read `SMSG_SHOW_BANK` (vmangos `Npc.cpp:94`, `buffer << bankerGuid`): one full 8-byte banker
-/// guid. Opens the bank window; the server also sends this **unprompted** for the gossip bank
-/// option (`GOSSIP_OPTION_BANKER` → `SendShowBank`, vmangos `Player.cpp:12426`) — a handler must
-/// not assume it only ever follows our own [`banker_activate`].
+/// `SMSG_SHOW_BANK` (vmangos `Npc.cpp:94`): the banker guid. Also sent unprompted for the gossip
+/// bank option (`Player.cpp:12426`), not only after [`banker_activate`].
 pub(super) fn read_show_bank(r: &mut &[u8]) -> io::Result<u64> {
     read_u64_le(r)
 }
 
-/// Read `SMSG_BUY_BANK_SLOT_RESULT` (vmangos `Item.cpp:137-140`): one `u32` [`bank_slot_result`]
-/// code. vmangos sends this only on failure; a successful buy is silent, visible only as the
-/// `PLAYER_BYTES_2` bank-bag-count byte advancing plus the coinage drop, both via `UPDATE_OBJECT`.
+/// `SMSG_BUY_BANK_SLOT_RESULT` (vmangos `Item.cpp:137-140`), sent only on failure: a bought slot
+/// shows only as the `PLAYER_BYTES_2` bank-bag count rising and the coinage falling.
 pub(super) fn read_buy_bank_slot_result(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
diff --git a/crates/benilla-protocol/src/messages/battlefield.rs b/crates/benilla-protocol/src/messages/battlefield.rs
index dfceb428..d4270c03 100644
--- a/crates/benilla-protocol/src/messages/battlefield.rs
+++ b/crates/benilla-protocol/src/messages/battlefield.rs
@@ -1,38 +1,31 @@
-//! The battleground queue's wire (decision 1963; wow-re `staticpopup-dialog-bindings.md` §7):
-//! the server's per-slot status and the port answer `AcceptBattlefieldPort` sends. Three queue
-//! slots exist in the client (`0xb6e9d0`, stride `0x20`), addressed 1-based from Lua.
+//! Battleground messages: queue status, the port answer, the scoreboard, the instance list and
+//! teammate positions. The client keeps three queue slots (`0xb6e9d0`, stride `0x20`).
 
 use std::io::{self, Read};
 
 use crate::wire::{capacity_hint, read_u32_le, read_u8};
 
-/// `SMSG_BATTLEFIELD_STATUS`, one slot's update (VERIFIED at the bytes, handler `0x4aa850`).
+/// `SMSG_BATTLEFIELD_STATUS`, one slot's update (handler `0x4aa850`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct BattlefieldStatus {
-    /// Which of the three slots, 0-based on the wire.
+    /// Which of the three slots, 0-based on the wire (1-based in Lua).
     pub slot: u32,
     /// The battleground's Map.dbc row id; zero clears the slot.
     pub map_id: u32,
     pub bracket: u8,
-    /// `+0x10` — the instance id, `GetBattlefieldStatus`'s third value (1963 parked this dword
-    /// as reader-less; `battlefield-verb-family.md` §2.2 found the reader, 1974).
+    /// The instance id (`+0x10`), `GetBattlefieldStatus`'s third value.
     pub instance_id: u32,
     pub status: u32,
-    /// Status 2: the port deadline's delta, in ms (`+0x14 = now + Δ`, `GetBattlefieldPortExpiration`).
+    /// Status 2: the port deadline in ms from now (`+0x14`, `GetBattlefieldPortExpiration`).
     pub time_ms: Option<u32>,
-    /// Status 3 (`battlefield-verb-family.md` §4.2, 1972): `(Δ₁, Δ₂)` — the instance's expiration
-    /// delta (`[0xb6ebb8] = now + Δ₁`, `GetBattlefieldInstanceExpiration`) and its elapsed run time
-    /// (`[0xb6ebbc] = now − Δ₂`, `GetBattlefieldInstanceRunTime`).
+    /// Status 3: the expiry delta (`[0xb6ebb8] = now + Δ₁`, `GetBattlefieldInstanceExpiration`)
+    /// and the run time (`[0xb6ebbc] = now − Δ₂`, `GetBattlefieldInstanceRunTime`).
     pub in_progress: Option<(u32, u32)>,
-    /// Status 1 (§4.2): `(estimated wait ms, raw; Δ waited)` — `[slot+0x18]` and
-    /// `[slot+0x1c] = now − Δ`, the `GetBattlefieldEstimatedWaitTime`/`GetBattlefieldTimeWaited` pair.
-    /// 1963's reader dropped this tail; the reference reads it (1972).
+    /// Status 1: the estimated wait in ms (`[slot+0x18]`, `GetBattlefieldEstimatedWaitTime`)
+    /// and the time waited (`[slot+0x1c] = now − Δ`, `GetBattlefieldTimeWaited`).
     pub queued: Option<(u32, u32)>,
 }
 
-/// Parse `SMSG_BATTLEFIELD_STATUS`: `u32 slot`, `u32 mapId`, and — only for a non-zero map —
-/// `u8 bracket`, `u32 instanceId`, `u32 status`, then the status-conditional tail: two `u32` for
-/// status 1, one for status 2, two for status 3.
 pub(super) fn read_battlefield_status(r: &mut impl Read) -> io::Result<BattlefieldStatus> {
     let slot = read_u32_le(r)?;
     let map_id = read_u32_le(r)?;
@@ -78,35 +71,31 @@ pub(super) fn read_battlefield_status(r: &mut impl Read) -> io::Result<Battlefie
     })
 }
 
-/// One scoreboard row of `MSG_PVP_LOG_DATA` (VERIFIED at the bytes, handler `0x4aab30`; wow-re
-/// `battlefield-verb-family.md` §2.3/§4.3, 1972). The client's 0x40-byte block, wire order.
+/// One `MSG_PVP_LOG_DATA` scoreboard row (handler `0x4aab30`), a 0x40-byte block in the client.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct PvpLogRow {
     pub guid: u64,
-    /// Wire field 2 — read before the kills, stored at `+0x1c`.
+    /// Wire field 2, before the kills; stored at `+0x1c`.
     pub rank: u32,
     pub killing_blows: u32,
     pub honorable_kills: u32,
     pub deaths: u32,
     pub honor_gained: u32,
-    /// The extra-stat dwords, at most eight stored — the client consumes and discards the rest.
+    /// The extra-stat dwords; the client keeps eight and reads past the rest.
     pub stats: Vec<u32>,
 }
 
-/// `MSG_PVP_LOG_DATA` inbound: the whole scoreboard, rows in wire order (nothing here sorts).
+/// `MSG_PVP_LOG_DATA` inbound: the whole scoreboard, rows in wire order.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct PvpLogData {
-    /// `u8 != 0` — the battleground has ended; `LeaveBattlefield` sends nothing until this is set.
+    /// The battleground has ended; `LeaveBattlefield` sends nothing until it has.
     pub ended: bool,
-    /// Read only when `ended`: `0` = Horde, `1` = Alliance (`GetBattlefieldWinner`).
+    /// Present only when ended: 0 Horde, 1 Alliance (`GetBattlefieldWinner`).
     pub winner: Option<u8>,
     pub rows: Vec<PvpLogRow>,
 }
 
-/// Parse `MSG_PVP_LOG_DATA` (§4.3): `u8 ended`, `u8 winner` iff ended, `u32 count`, `count` rows of
-/// `u64 guid, u32 rank, u32 kb, u32 hk, u32 deaths, u32 honor, u32 statCount, statCount × u32`.
-/// The client stores no more than eight stats per row and clamps nothing else — a count past its
-/// 80 blocks is its own anomaly (§10); ours keeps every row the wire carries.
+/// Deviation: every row is kept; the reference has 80 row blocks and does not clamp the count.
 pub(super) fn read_pvp_log_data(r: &mut impl Read) -> io::Result<PvpLogData> {
     let ended = read_u8(r)? != 0;
     let winner = if ended { Some(read_u8(r)?) } else { None };
@@ -144,30 +133,23 @@ pub(super) fn read_pvp_log_data(r: &mut impl Read) -> io::Result<PvpLogData> {
     })
 }
 
-/// Body of `CMSG_LEAVE_BATTLEFIELD` (VERIFIED, `0x4abe60`): `u32 mapId` — the active slot's map,
-/// or the literal 0 when no slot is active.
+/// `CMSG_LEAVE_BATTLEFIELD` (`0x4abe60`): the active slot's map id, or 0 with none active.
 pub fn leave_battlefield(map_id: u32) -> Vec<u8> {
     map_id.to_le_bytes().to_vec()
 }
 
-/// `SMSG_BATTLEFIELD_LIST` (VERIFIED at the bytes, handler `0x4aa6c0`; wow-re
-/// `battlefield-verb-family.md` §4.1, 1974): the instance list a battlemaster (or
-/// `ShowBattlefieldList`) opens.
+/// `SMSG_BATTLEFIELD_LIST` (handler `0x4aa6c0`): the instance list a battlemaster opens.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldList {
-    /// The battlemaster's guid — `0` when the list was opened without an NPC. Cached by the
-    /// client and read by `JoinBattlefield` to choose between the two join opcodes.
+    /// 0 when opened without an NPC; `JoinBattlefield` picks the join opcode by it.
     pub battlemaster: u64,
-    /// The battleground's Map.dbc row id.
     pub map_id: u32,
     /// The level-bracket index; the client derives the bracket's min/max from it and the map row.
     pub bracket: u8,
-    /// The instance ids, wire order — nothing sorts them; index 0 on the wire is instance 1 in Lua.
+    /// The instance ids in wire order; wire index 0 is instance 1 in Lua.
     pub instances: Vec<u32>,
 }
 
-/// Parse `SMSG_BATTLEFIELD_LIST` (§4.1): `u64 battlemaster`, `u32 mapId`, `u8 bracket`,
-/// `u32 count`, `count × u32 instanceId`.
 pub(super) fn read_battlefield_list(r: &mut impl Read) -> io::Result<BattlefieldList> {
     let battlemaster = crate::wire::read_u64_le(r)?;
     let map_id = read_u32_le(r)?;
@@ -185,9 +167,8 @@ pub(super) fn read_battlefield_list(r: &mut impl Read) -> io::Result<Battlefield
     })
 }
 
-/// One teammate's map position off `MSG_BATTLEGROUND_PLAYER_POSITIONS` (1980): raw world
-/// floats — the client prefers the live object's position when it has one, and normalizes
-/// either through the world-map projection under the active battleground's map.
+/// One teammate's position from `MSG_BATTLEGROUND_PLAYER_POSITIONS`, in raw world coordinates;
+/// the client prefers a live object's own position.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct BattlefieldPosition {
     pub guid: u64,
@@ -195,21 +176,18 @@ pub struct BattlefieldPosition {
     pub y: f32,
 }
 
-/// `MSG_BATTLEGROUND_PLAYER_POSITIONS` inbound (VERIFIED at the bytes, handler `0x4aad40`; wow-re
-/// `worldmap-arrow-and-positions.md` §3.1): the teammates not in the requester's group, then the
-/// friendly flag carrier when there is one.
+/// `MSG_BATTLEGROUND_PLAYER_POSITIONS` (handler `0x4aad40`): teammates outside our group, then
+/// the friendly flag carrier if any.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldPositions {
     pub players: Vec<BattlefieldPosition>,
     pub carrier: Option<BattlefieldPosition>,
 }
 
-/// The client's store holds 40 entries and its handler writes past them for a larger count
-/// (§3.2, an overrun the reference has); ours keeps the first 40.
+/// The client's 40-entry store. Deviation: a larger count keeps the first 40, where the
+/// reference's handler writes past the store.
 pub const BATTLEFIELD_POSITIONS_MAX: usize = 40;
 
-/// Parse it (§3.1): `u32 count`, `count × (u64, f32, f32)`, `u8 hasCarrier`, and the carrier
-/// triple only when that byte is non-zero.
 pub(super) fn read_battlefield_positions(r: &mut impl Read) -> io::Result<BattlefieldPositions> {
     let count = read_u32_le(r)?;
     let mut players = Vec::with_capacity(capacity_hint(count, BATTLEFIELD_POSITIONS_MAX));
@@ -233,13 +211,12 @@ pub(super) fn read_battlefield_positions(r: &mut impl Read) -> io::Result<Battle
     Ok(BattlefieldPositions { players, carrier })
 }
 
-/// Body of `CMSG_BATTLEFIELD_LIST` (VERIFIED, `0x4ab8c0`): `u32 mapId` of the queued slot.
+/// `CMSG_BATTLEFIELD_LIST` (`0x4ab8c0`): the queued slot's map id.
 pub fn battlefield_list(map_id: u32) -> Vec<u8> {
     map_id.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_BATTLEMASTER_JOIN` (VERIFIED, `0x4a9f60`'s GUID arm): `u64 battlemaster`,
-/// `u32 mapId`, `u32 instanceId` (`0` = first available), `u8 asGroup`.
+/// `CMSG_BATTLEMASTER_JOIN` (`0x4a9f60`, with a battlemaster); instance 0 means first available.
 pub fn battlemaster_join(
     battlemaster: u64,
     map_id: u32,
@@ -253,8 +230,7 @@ pub fn battlemaster_join(
     body
 }
 
-/// Body of `CMSG_BATTLEFIELD_JOIN` (VERIFIED, `0x4a9f60`'s no-GUID arm): `u32 mapId`,
-/// `u32 instanceId` (`0` = first available), `u8 asGroup`.
+/// `CMSG_BATTLEFIELD_JOIN` (`0x4a9f60`, no battlemaster); instance 0 means first available.
 pub fn battlefield_join(map_id: u32, instance_id: u32, as_group: bool) -> Vec<u8> {
     let mut body = map_id.to_le_bytes().to_vec();
     body.extend_from_slice(&instance_id.to_le_bytes());
@@ -262,8 +238,7 @@ pub fn battlefield_join(map_id: u32, instance_id: u32, as_group: bool) -> Vec<u8
     body
 }
 
-/// Body of `CMSG_BATTLEFIELD_PORT` (VERIFIED, `0x4ab3b0`): `u32 mapId` then a genuinely
-/// one-byte `accept`, normalised to 0/1 before it reaches the wire.
+/// `CMSG_BATTLEFIELD_PORT` (`0x4ab3b0`): the map id, then a one-byte accept, 0 or 1.
 pub fn battlefield_port(map_id: u32, accept: bool) -> Vec<u8> {
     let mut body = map_id.to_le_bytes().to_vec();
     body.push(u8::from(accept));
@@ -274,6 +249,7 @@ pub fn battlefield_port(map_id: u32, accept: bool) -> Vec<u8> {
 mod tests {
     use super::*;
 
+    /// Status 2, 3 and 1 each read their own tail and no further; a zero map ends the packet.
     #[test]
     fn status_reads_the_conditional_tails() {
         let mut body = vec![
@@ -285,6 +261,34 @@ mod tests {
             (1, 30, 5, 7, 2)
         );
         assert_eq!(s.time_ms, Some(100));
+        assert_eq!((s.in_progress, s.queued), (None, None));
+
+        // The same slot, map, bracket and instance under status 3, then status 1.
+        let header = body[..13].to_vec();
+        let mut b = header.clone();
+        for v in [3u32, 120_000, 45_000] {
+            b.extend_from_slice(&v.to_le_bytes());
+        }
+        b.push(0xEE); // a byte past the tail
+        let mut r = b.as_slice();
+        let s = read_battlefield_status(&mut r).unwrap();
+        assert_eq!(s.status, 3);
+        assert_eq!(s.in_progress, Some((120_000, 45_000)));
+        assert_eq!((s.time_ms, s.queued), (None, None));
+        assert_eq!(r, [0xEE], "the status-3 tail is two u32s");
+
+        let mut b = header;
+        for v in [1u32, 30_000, 5_000] {
+            b.extend_from_slice(&v.to_le_bytes());
+        }
+        b.push(0xEE);
+        let mut r = b.as_slice();
+        let s = read_battlefield_status(&mut r).unwrap();
+        assert_eq!(s.status, 1);
+        assert_eq!(s.queued, Some((30_000, 5_000)));
+        assert_eq!((s.time_ms, s.in_progress), (None, None));
+        assert_eq!(r, [0xEE], "the status-1 tail is two u32s");
+
         body = vec![0u8, 0, 0, 0, 0, 0, 0, 0];
         let s = read_battlefield_status(&mut body.as_slice()).unwrap();
         assert_eq!(
@@ -304,8 +308,6 @@ mod tests {
 mod pvp_log_tests {
     use super::*;
 
-    /// The scoreboard reader: the winner byte only when ended, the rank BEFORE the kills, and no
-    /// more than eight stats kept while every one is consumed.
     #[test]
     fn the_scoreboard_reads_its_conditional_winner_and_keeps_eight_stats() {
         let mut body = vec![1u8, 0u8, 1, 0, 0, 0];
@@ -340,7 +342,6 @@ mod pvp_log_tests {
         assert_eq!(leave_battlefield(489), vec![0xE9, 1, 0, 0]);
     }
 
-    /// The instance list: the guid, the map, the bracket byte and the ids in wire order.
     #[test]
     fn the_list_reads_its_guid_bracket_and_instances() {
         let mut body = 0x1234_5678_9abc_def0u64.to_le_bytes().to_vec();
@@ -366,7 +367,6 @@ mod pvp_log_tests {
         assert!(l.instances.is_empty());
     }
 
-    /// The positions reply: the count-led list, the carrier byte, and the 40-entry cap.
     #[test]
     fn the_positions_reply_reads_the_list_and_the_carrier() {
         let mut body = 2u32.to_le_bytes().to_vec();
@@ -414,7 +414,6 @@ mod pvp_log_tests {
         );
     }
 
-    /// The two join bodies differ only by the leading guid; the list request is the map alone.
     #[test]
     fn the_join_bodies_and_the_list_request() {
         assert_eq!(
@@ -428,7 +427,6 @@ mod pvp_log_tests {
         assert_eq!(battlefield_list(529), vec![0x11, 2, 0, 0]);
     }
 
-    /// Status 1 carries the two wait dwords 1963's reader dropped.
     #[test]
     fn a_queued_status_carries_its_wait_pair() {
         let mut body = vec![0u8, 0, 0, 0];
diff --git a/crates/benilla-protocol/src/messages/binder.rs b/crates/benilla-protocol/src/messages/binder.rs
index e0158826..21402888 100644
--- a/crates/benilla-protocol/src/messages/binder.rs
+++ b/crates/benilla-protocol/src/messages/binder.rs
@@ -1,60 +1,33 @@
-//! The innkeeper bind family — the confirm question, its answer, and the "you are bound" echo
-//! (opcodes 747, 437, 344; decision 1331).
-//!
-//! Three packets and one law worth stating plainly, because getting it wrong is silent: **selecting
-//! the innkeeper's gossip line does not bind anything.** vmangos's `GOSSIP_OPTION_INNKEEPER` arm
-//! (`Player.cpp:12341`) closes the gossip menu and calls `Player::SetBindPoint`, which sends
-//! `SMSG_BINDER_CONFIRM` and stops. The bind happens only when the client answers
-//! `CMSG_BINDER_ACTIVATE` (`HandleBinderActivateOpcode`, `NPCHandler.cpp:479`), at which point the
-//! innkeeper casts spell 3286 "Bind" on the player and `SPELL_EFFECT_BIND`
-//! (`SpellEffects.cpp:5837`) writes the homebind and sends `SMSG_BINDPOINTUPDATE` +
-//! `SMSG_PLAYERBOUND`. A client that shows the gossip line and never sends the answer therefore
-//! looks exactly like a server that ignored the click — which is how B249 read.
-//!
-//! | opcode | direction | body |
-//! |---|---|---|
-//! | `SMSG_BINDER_CONFIRM` 0x2eb | in | `u64` binder guid |
-//! | `CMSG_BINDER_ACTIVATE` 0x1b5 | out | `u64` binder guid |
-//! | `SMSG_PLAYERBOUND` 0x158 | in | `u64` binder guid + `u32` area id |
-//!
-//! The server bodies are VERIFIED against vmangos `Server/Packets/Npc.{h,cpp}` and
-//! `Server/Packets/Misc.{h,cpp}` (`BinderConfirm`, `BinderActivate`, `PlayerBound`). What the
-//! *client* puts in `CMSG_BINDER_ACTIVATE` is the guid it stored from the confirm: vmangos reads
-//! that guid and uses it (`GetNPCIfCanInteractWith(packet.npcGuid, UNIT_NPC_FLAG_INNKEEPER)`), so
-//! unlike the duel echo this one is load-bearing — a zero here is an ignored bind.
+//! The innkeeper bind: `SMSG_BINDER_CONFIRM` (0x2eb) asks, `CMSG_BINDER_ACTIVATE` (0x1b5)
+//! answers, `SMSG_PLAYERBOUND` (0x158) confirms. The gossip line only asks (`Player.cpp:12341`);
+//! the bind happens on the answer, when the innkeeper casts spell 3286 (`NPCHandler.cpp:479`).
 
 use std::io;
 
 use crate::wire::{read_u32_le, read_u64_le};
 
-/// `SMSG_PLAYERBOUND` — the server's echo once the bind has actually taken.
+/// `SMSG_PLAYERBOUND`, sent once the bind has taken (`SpellEffects.cpp:5837`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct PlayerBound {
-    /// The NPC that bound us (vmangos sends the *caster* of spell 3286, i.e. the innkeeper).
+    /// The caster of spell 3286, the innkeeper.
     pub binder: u64,
-    /// The `AreaTable` id the player is now bound in — the same id `SMSG_BINDPOINTUPDATE` carries
-    /// in the packet beside it, so the two can never disagree.
+    /// The `AreaTable` id now bound, the same one `SMSG_BINDPOINTUPDATE` carries beside it.
     pub area: u32,
 }
 
-/// Body of `CMSG_BINDER_ACTIVATE`: the binder's full 8-byte guid — the one the client stored from
-/// [`read_binder_confirm`]. **Not decorative:** `HandleBinderActivateOpcode` resolves this guid to
-/// a live `UNIT_NPC_FLAG_INNKEEPER` creature in interact range and drops the request if it can't,
-/// so an empty or stale guid binds nothing and reports nothing.
+/// `CMSG_BINDER_ACTIVATE`: the guid from [`read_binder_confirm`]. The server binds only if it is
+/// an innkeeper in interact range, and says nothing otherwise.
 pub fn binder_activate(binder_guid: u64) -> Vec<u8> {
     binder_guid.to_le_bytes().to_vec()
 }
 
-/// Read `SMSG_BINDER_CONFIRM` (vmangos `Npc.cpp`, `buffer << binderGuid`): one full 8-byte guid.
-///
-/// This is the *question*, and it arrives with `SMSG_GOSSIP_COMPLETE` right before it — the gossip
-/// window is already closing when the dialog goes up, which is why the confirm is not part of the
-/// gossip session's state.
+/// `SMSG_BINDER_CONFIRM` (vmangos `Npc.cpp`): the innkeeper's guid. `SMSG_GOSSIP_COMPLETE` comes
+/// just before it, so the question outlives the gossip window.
 pub(super) fn read_binder_confirm(r: &mut &[u8]) -> io::Result<u64> {
     read_u64_le(r)
 }
 
-/// Read `SMSG_PLAYERBOUND` (vmangos `Misc.cpp`, `buffer << binderGuid << areaId`).
+/// `SMSG_PLAYERBOUND` (vmangos `Misc.cpp`).
 pub(super) fn read_player_bound(r: &mut &[u8]) -> io::Result<PlayerBound> {
     Ok(PlayerBound {
         binder: read_u64_le(r)?,
@@ -66,8 +39,6 @@ pub(super) fn read_player_bound(r: &mut &[u8]) -> io::Result<PlayerBound> {
 mod tests {
     use super::*;
 
-    /// The activate body is the bare guid, little-endian — the shape vmangos's `BinderActivate`
-    /// reads back.
     #[test]
     fn the_activate_body_is_one_little_endian_guid() {
         assert_eq!(
@@ -76,8 +47,6 @@ mod tests {
         );
     }
 
-    /// Confirm in, bound out: both read the guid first, and `SMSG_PLAYERBOUND` carries the area
-    /// id after it.
     #[test]
     fn the_two_inbound_bodies_round_trip() {
         let guid: u64 = 0xF130_0000_0001_2345;
diff --git a/crates/benilla-protocol/src/messages/broadcast.rs b/crates/benilla-protocol/src/messages/broadcast.rs
index bd8eb7e9..05813d6c 100644
--- a/crates/benilla-protocol/src/messages/broadcast.rs
+++ b/crates/benilla-protocol/src/messages/broadcast.rs
@@ -1,104 +1,31 @@
-//! The four **world broadcasts** — the packets the server sends to everybody, or to everybody in a
-//! zone, rather than to one player about their own doing.
-//!
-//! They have no shared wire family (two carry a zone id, one a DBC index, one nothing at all), and
-//! they are grouped here because they share a *destination*: all four end at a chat line or a UI
-//! toast the player did not ask for. The client's own handlers are three adjacent functions plus
-//! one arm of a shared dispatcher, and two of them are the same function twice over.
-//!
-//! | opcode | handler | what it becomes |
-//! |---|---|---|
-//! | `SMSG_ZONE_UNDER_ATTACK` `0x254` | `0x49dcc0` | `CHAT_MSG_CHANNEL` on the defense channels |
-//! | `SMSG_DEFENSE_MESSAGE` `0x33B` | `0x49de30` | `CHAT_MSG_CHANNEL` on the defense channels |
-//! | `SMSG_SERVER_MESSAGE` `0x291` | `0x49df80` | `CHAT_MSG_SYSTEM` |
-//! | `SMSG_CHAT_RESTRICTED` `0x2FD` | `0x5e38c0` arm `0x5e4a09` | `DisplayError(451)` → `CHAT_MSG_SYSTEM` |
-//!
-//! **The two defense broadcasts do not go where a reimplementation guesses.** Neither is a system
-//! line: the client walks its own **joined-channel list** (`[0xb4fe04]`, count `[0xb4fe00]`, stride
-//! `0xa0` — the record wow-re's `chat-msg-event-args.md` §7 owns) and delivers the text on every
-//! joined channel whose `ChatChannels.dbc` row carries the `DEFENSE` flag `0x10000`, as chat type
-//! `0xE` = `CHAT_MSG_CHANNEL` with **no sender** and language `0`. A `ZONE_DEP` (`0x2`) channel —
-//! LocalDefense — additionally requires the broadcast's zone to be the player's current one; a
-//! GLOBAL one — WorldDefense — always passes. So a player who has joined neither channel sees
-//! nothing at all, which is the faithful answer and not a dropped packet.
-//!
-//! The zone test is on the **parent** zone, not the packet's area: both handlers resolve the id
-//! through `AreaTable.dbc` and replace it with the row's parent (`[rec+0x8]`) when that is nonzero.
-//! `SMSG_ZONE_UNDER_ATTACK`'s *text* still names the packet's own area — the name is read off the
-//! row before the remap — so "Sentinel Hill is under attack!" is matched against Westfall.
-//!
-//! The wire shapes below are VERIFIED against vmangos source with a file:line cite per field, and
-//! confirmed against the client's own reads in the handlers above. The goldens
-//! (`tests/broadcast.rs`) are built the way the server builds each body.
+//! The world broadcasts: server messages, zone-under-attack and defense messages. The last two
+//! print, senderless, on every joined channel whose `ChatChannels.dbc` row has `DEFENSE`
+//! (0x10000); a `ZONE_DEP` (0x2) channel also needs the area's parent zone to be the player's.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_u32_le};
 
-/// Read `SMSG_SERVER_MESSAGE` (VERIFIED vmangos `WorldPackets::Misc::ServerMessage::AppendBodyTo`,
-/// `Server/Packets/Misc.cpp:341-345`): `u32 messageType` + one cstring.
-///
-/// `messageType` is a **`ServerMessages.dbc` row id**, not a free enum — the client indexes the
-/// store at `[0xc0d990]` by it directly (`0x49dfbb`) and takes the row's localized text as a
-/// **format string**, which the packet's own text fills. vmangos's producers are the five rows the
-/// shipped table has (`World.h:62`, whose comment says "ServerMessages.dbc"):
-///
-/// | type | `ServerMessages.dbc` text (enUS) | vmangos sends |
-/// |---|---|---|
-/// | 1 | `[SERVER] Shutdown in %s` | `secsToTimeString(remaining)` |
-/// | 2 | `[SERVER] Restart in %s` | `secsToTimeString(remaining)` |
-/// | 3 | `%s` | the operator's own text (`SERVER_MSG_CUSTOM`) |
-/// | 4 | `[SERVER] Shutdown cancelled` | `""` |
-/// | 5 | `[SERVER] Restart cancelled` | `""` |
-///
-/// The text is carried whole rather than being resolved here: the DBC lives on the *client* side
-/// of this crate's boundary (`benilla_formats::ServerMessagesCatalog`), and the row-missing
-/// fallback the client itself uses — `"[%d]: %s"` at `0x844864` — needs the raw type to render.
+/// `SMSG_SERVER_MESSAGE` (`Server/Packets/Misc.cpp:341-345`, handler `0x49df80`): a
+/// `ServerMessages.dbc` row id whose text is a format string for the cstring (vmangos sends 1-5,
+/// `World.h:62`); a missing row prints as `"[%d]: %s"` (`0x844864`).
 pub(super) fn read_server_message(r: &mut &[u8]) -> io::Result<(u32, String)> {
     let message_type = read_u32_le(r)?;
     let text = read_cstring(r)?;
     Ok((message_type, text))
 }
 
-/// Read `SMSG_ZONE_UNDER_ATTACK` (VERIFIED vmangos
-/// `WorldPackets::Misc::ZoneUnderAttack::AppendBodyTo`, `Server/Packets/Misc.cpp:451-454`): one
-/// `u32`, the `AreaTable.dbc` id of the area under attack.
-///
-/// vmangos sends it from `Creature::SendZoneUnderAttackMessage`
-/// (`src/game/Objects/Creature.cpp:2889`), whose sole caller is the creature-death path
-/// (`Objects/Unit.cpp:1200`) when the victim `IsGuard()` or carries
-/// `CREATURE_STATIC_FLAG_PVP_ENABLING` and the killer was a player. It goes **map-wide to the
-/// opposing team**, throttled to one per area per 10 s — and the function's own comment reads
-/// *"Send a message to LocalDefense channel for players opposition team in the zone"*, which is the
-/// server independently naming the destination the client's handler picks.
+/// `SMSG_ZONE_UNDER_ATTACK` (`Server/Packets/Misc.cpp:451-454`, handler `0x49dcc0`): the attacked
+/// area's `AreaTable.dbc` id, whose own name fills the text. vmangos sends it map-wide to the
+/// enemy team when a player kills a guard or PvP-enabling creature, once per area per 10 s.
 pub(super) fn read_zone_under_attack(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
 
-/// Read `SMSG_DEFENSE_MESSAGE` (VERIFIED vmangos `Map::SendDefenseMessage`,
-/// `src/game/Maps/Map.cpp:1868-1884`): `u32 zoneId`, `u32 length`, then `length` bytes of text.
-///
-/// **Built raw, not through a packet class** — the whole body is three `ByteBuffer <<` writes
-/// inside a `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_11_2`, so this packet exists for 1.12 and
-/// no earlier build. The length is written as `strlen(text) + 1` and the `char const*` write
-/// appends the NUL, so it counts the terminator.
-///
-/// **The length is load-bearing here, unlike [`super::area_trigger::read_area_trigger_message`]'s.**
-/// The client does not read a C string at all: `0x49de5c` calls the `CDataStore` **borrow-and-skip**
-/// `0x419ac0`, which copies nothing, hands back a live pointer into the receive buffer and advances
-/// the cursor by exactly `length` — and which **zeroes its out-parameter before any bounds check**,
-/// so a `length` that overruns the packet reaches the chat composer as a NULL text and
-/// `0x49a870`'s NULL guard at `0x49a889` drops the line entirely (wow-re
-/// `system/net/scratch/cdatastore-get-primitives.md` §5, `system/ui/scratch/world-broadcast-opcodes.md`
-/// §3 — a §5 cross-check that corrected two committed notes calling `0x419ac0` a copy).
-///
-/// So an overrunning length is a **refusal**, not a hint to ignore: it errors here, and the session
-/// drops the packet, which is the same nothing-displayed the reference produces. Within the bounds
-/// the text is the borrowed window up to its first NUL — the reference reads past `length` when
-/// there is no NUL in it (an unmitigated OOB read, wow-re's words), which is the one place a
-/// faithful reimplementation stops short on purpose.
-///
-/// The Eastern Plaguelands tower captures are its only vmangos sender.
+/// `SMSG_DEFENSE_MESSAGE` (`Maps/Map.cpp:1868-1884`, handler `0x49de30`): `u32` zone id, `u32`
+/// length counting the NUL, then the text. The reference skips exactly `length` bytes
+/// (`0x419ac0`) and drops the line when that overruns the packet, so an overrun errors here.
+/// Deviation: text without a NUL stops at `length`, where the reference reads out of bounds.
 pub(super) fn read_defense_message(r: &mut &[u8]) -> io::Result<(u32, String)> {
     let zone_id = read_u32_le(r)?;
     let length = read_u32_le(r)? as usize;
@@ -131,8 +58,6 @@ mod tests {
         );
     }
 
-    /// The cancel messages carry an EMPTY text, and the row's own string is the whole line — so an
-    /// empty string here is a value, never a parse failure.
     #[test]
     fn a_cancel_message_carries_an_empty_text() {
         let mut body = 4u32.to_le_bytes().to_vec();
@@ -149,8 +74,6 @@ mod tests {
         assert_eq!(read_zone_under_attack(&mut &body[..]).unwrap(), 40);
     }
 
-    /// The length prefix is skipped and the text read whole — built the way `Map.cpp` builds it,
-    /// terminator counted.
     #[test]
     fn a_defense_message_skips_its_length_and_reads_the_text() {
         let text = b"The Eastern Plaguelands tower has been taken!";
@@ -163,10 +86,6 @@ mod tests {
         assert_eq!(out, String::from_utf8_lossy(text));
     }
 
-    /// A truncated body is an error, not a silently empty line — and it is the *declared length*
-    /// that decides, because that is what the reference bounds-checks. An overrun leaves its
-    /// out-pointer NULL and the chat composer drops the line; erroring here reproduces the same
-    /// nothing-displayed, with a log line instead of silence.
     #[test]
     fn a_length_that_overruns_the_body_is_refused() {
         let mut body = 139u32.to_le_bytes().to_vec();
@@ -180,8 +99,6 @@ mod tests {
         assert!(read_defense_message(&mut &body[..]).is_err());
     }
 
-    /// A window with no NUL in it is the whole window — the reference would read on past `length`
-    /// (an OOB read it mitigates nowhere); stopping at the bound is the deliberate divergence.
     #[test]
     fn a_window_without_a_terminator_is_taken_whole() {
         let mut body = 139u32.to_le_bytes().to_vec();
diff --git a/crates/benilla-protocol/src/messages/channel.rs b/crates/benilla-protocol/src/messages/channel.rs
index 65b9c764..e31c6d4c 100644
--- a/crates/benilla-protocol/src/messages/channel.rs
+++ b/crates/benilla-protocol/src/messages/channel.rs
@@ -1,19 +1,10 @@
-//! The channel subsystem — join/leave/list/moderation (opcodes 151-168, VERIFIED vmangos
-//! `Server/Protocol/Opcodes_1_12_1.h:154-171`) plus the two server notification packets:
-//! `SMSG_CHANNEL_NOTIFY` (a notice byte + channel name + a per-notice tail — [`read_channel_notify`],
-//! VERIFIED vmangos `Chat/Channel.cpp:804-1008` against the enum in `Chat/Channel.h:35-71`) and
-//! `SMSG_CHANNEL_LIST` (the member roster — [`read_channel_list`], VERIFIED
-//! `Chat/Channel.cpp:497-557`). CMSG bodies are VERIFIED against `Server/Packets/Channel.h`/`.cpp`
-//! (every `ReadFromWorldPacket` there): every moderation command reads `cstring channelName [+
-//! cstring playerName]` — the client body builders in [`super::client`] all funnel through
-//! [`super::client::cstrings_body`] for that shared shape.
+//! The channel notices and member roster (vmangos `Chat/Channel.cpp`).
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_cstring, read_u32_le, read_u64_le, read_u8};
 
-/// `SMSG_CHANNEL_NOTIFY`'s notice byte (`ChatNotify`, VERIFIED vmangos `Chat/Channel.h:35-71`) —
-/// selects which tail follows the channel name (see [`ChannelNoticeTail`]/[`read_channel_notify`]).
+/// `SMSG_CHANNEL_NOTIFY`'s notice byte (`ChatNotify`, vmangos `Chat/Channel.h:35-71`).
 pub mod channel_notice {
     pub const JOINED: u8 = 0x00;
     pub const LEFT: u8 = 0x01;
@@ -49,43 +40,26 @@ pub mod channel_notice {
     pub const THROTTLED: u8 = 0x1F;
 }
 
-/// The per-notice tail `SMSG_CHANNEL_NOTIFY` carries after `u8 notice + cstring channel` — which
-/// shape follows depends on `notice` ([`channel_notice`]); VERIFIED against vmangos's one
-/// `Channel::Make*` producer per notice (`Chat/Channel.cpp:804-1008`). `NOT_MEMBER` (0x05) has a
-/// second, **static** producer (`Channel::MakeNotOnPacket`, `Channel.cpp:847-851`, used when there's
-/// no live `Channel` object to query — e.g. `/list` on a channel name that doesn't exist) that writes
-/// the byte-**identical** shape (`u8 notice, cstring channel`, nothing more): both call sites decode
-/// the same way, an empty tail — there is no ambiguity to special-case here.
+/// What follows the notice byte and channel name, by notice (`Chat/Channel.cpp:804-1008`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ChannelNoticeTail {
-    /// 0x00 JOINED / 0x01 LEFT: the guid that joined/left.
+    /// The member who joined or left.
     Guid(u64),
-    /// 0x02 YOU_JOINED: our own new channel flags. The trailing `u32` vmangos writes after it is a
-    /// hardcoded `0` ("the non-zero number will be appended to the channel name" — never actually
-    /// sent nonzero) and carries no information, so it isn't surfaced.
+    /// Our channel flags; the `u32` after them is always 0.
     YouJoined { flags: u32 },
-    /// 0x03 YOU_LEFT / 0x04 WRONG_PASSWORD / 0x05 NOT_MEMBER / 0x06 NOT_MODERATOR / 0x0A NOT_OWNER /
-    /// 0x11 MUTED / 0x13 BANNED / 0x19 INVITE_WRONG_FACTION / 0x1A WRONG_FACTION / 0x1B INVALID_NAME /
-    /// 0x1C NOT_MODERATED / 0x1F THROTTLED: no tail at all — the notice + channel name is the whole
-    /// packet.
+    /// Nothing follows the channel name.
     Empty,
-    /// 0x07 PASSWORD_CHANGED / 0x08 OWNER_CHANGED / 0x0D ANNOUNCEMENTS_ON / 0x0E ANNOUNCEMENTS_OFF /
-    /// 0x0F MODERATION_ON / 0x10 MODERATION_OFF / 0x17 PLAYER_ALREADY_MEMBER / 0x18 INVITE: the guid
-    /// that made the change / is doing the inviting.
+    /// The player who made the change or sent the invite.
     Actor(u64),
-    /// 0x09 PLAYER_NOT_FOUND / 0x0B CHANNEL_OWNER / 0x16 PLAYER_NOT_BANNED / 0x1D PLAYER_INVITED /
-    /// 0x1E PLAYER_INVITE_BANNED: a bare player name (CHANNEL_OWNER sends the literal string
-    /// `"Nobody"` for a non-constant channel with no owner, or `"PLAYER_NOT_FOUND"` if the owner's
-    /// name can't be resolved — both ride this same string field).
+    /// A player name; `CHANNEL_OWNER` may send the literal `"Nobody"` or `"PLAYER_NOT_FOUND"`.
     Name(String),
-    /// 0x0C MODE_CHANGE: the affected guid + its `ChannelMemberFlags` byte before/after the change.
+    /// The member and its `ChannelMemberFlags` before and after.
     ModeChange {
         guid: u64,
         old_flags: u8,
         new_flags: u8,
     },
-    /// 0x12 PLAYER_KICKED / 0x14 PLAYER_BANNED / 0x15 PLAYER_UNBANNED: the affected player, then who
-    /// did it.
+    /// The affected player, then who acted.
     Actors { target: u64, source: u64 },
 }
 
@@ -97,10 +71,7 @@ pub struct ChannelNotify {
     pub tail: ChannelNoticeTail,
 }
 
-/// Read `SMSG_CHANNEL_NOTIFY` (see [`ChannelNoticeTail`] for the per-notice VERIFIED citations).
-/// An unrecognized notice byte (outside vmangos's defined `0x00..=0x1F`) errors rather than guessing
-/// a shape — there is no way to skip an unknown tail without risking misreading the rest of this
-/// packet's bytes as something else.
+/// A notice byte past 0x1F errors, since the length of its tail is unknown.
 pub(super) fn read_channel_notify(r: &mut &[u8]) -> io::Result<ChannelNotify> {
     use channel_notice as n;
 
@@ -110,7 +81,7 @@ pub(super) fn read_channel_notify(r: &mut &[u8]) -> io::Result<ChannelNotify> {
         n::JOINED | n::LEFT => ChannelNoticeTail::Guid(read_u64_le(r)?),
         n::YOU_JOINED => {
             let flags = read_u32_le(r)?;
-            let _reserved = read_u32_le(r)?; // always 0 on the wire (see the variant doc)
+            let _reserved = read_u32_le(r)?; // always 0 on the wire
             ChannelNoticeTail::YouJoined { flags }
         }
         n::YOU_LEFT
@@ -161,18 +132,14 @@ pub(super) fn read_channel_notify(r: &mut &[u8]) -> io::Result<ChannelNotify> {
     })
 }
 
-/// Read `SMSG_CHANNEL_LIST` (`Channel::List`, VERIFIED vmangos `Chat/Channel.cpp:513-556`): cstring
-/// channel name + `u8` channel flags + `u32` member count + that many `(u64 guid, u8 memberFlags)`
-/// rows (`ChannelMemberFlags` — owner/moderator/voiced/muted/custom/mic-muted, `Chat/Channel.h:
-/// 119-130`). Returns `(channel, flags, members)`.
+/// `SMSG_CHANNEL_LIST` (`Chat/Channel.cpp:513-556`): `(channel, flags, members)`, each member a
+/// guid and its `ChannelMemberFlags` (`Chat/Channel.h:119-130`).
 #[allow(clippy::type_complexity)]
 pub(super) fn read_channel_list(r: &mut &[u8]) -> io::Result<(String, u8, Vec<(u64, u8)>)> {
     let channel = read_cstring(r)?;
     let flags = read_u8(r)?;
     let count = read_u32_le(r)?;
-    // The count is wire-controlled — never let it drive allocation (a corrupt 0xFFFFFFFF must fail
-    // at the bounds-checked reads below, not abort in the allocator). Legit rosters exceed 256
-    // rarely; push simply grows past the hint.
+    // The count is wire-controlled, so it only hints the allocation.
     let mut members = Vec::with_capacity(capacity_hint(count, 256));
     for _ in 0..count {
         let guid = read_u64_le(r)?;
diff --git a/crates/benilla-protocol/src/messages/chat.rs b/crates/benilla-protocol/src/messages/chat.rs
index 0bd0a16d..023fb784 100644
--- a/crates/benilla-protocol/src/messages/chat.rs
+++ b/crates/benilla-protocol/src/messages/chat.rs
@@ -1,35 +1,13 @@
-//! Inbound chat — `SMSG_MESSAGECHAT` (VERIFIED vmangos `ChatHandler::BuildChatPacket`,
-//! `Chat/Chat.cpp:2542-2599`, all `SUPPORTED_CLIENT_BUILD` bands included for 5875): `u8 type`, `u32
-//! language`, a **per-type sender prefix**, then `u32 len` (includes the NUL) + the text + `u8
-//! chatTag`. This is how everything textual reaches the client — player say/yell/whisper, NPC
-//! lines, channels, and the **system messages** GM dot-commands answer with (type `0x0A`), which
-//! is what makes command feedback visible to the probe and the chat UI.
-//!
-//! Also owns the handful of small chat-adjacent SMSG bodies that aren't their own subsystem:
-//! `SMSG_CHAT_PLAYER_NOT_FOUND`, `SMSG_CHAT_WRONG_FACTION`, `SMSG_PLAYED_TIME`, and `MSG_RANDOM_ROLL`'s
-//! server→client broadcast shape. The channel subsystem (join/leave/list/moderation +
-//! `SMSG_CHANNEL_NOTIFY`/`_LIST`) is big enough to own its own module: [`super::channel`].
+//! Inbound chat. `SMSG_MESSAGECHAT` (vmangos `Chat/Chat.cpp:2542-2599`) is `u8 type`,
+//! `u32 language`, a per-type sender prefix, `u32 len` (NUL included), the text, `u8 chatTag`.
+//! Also the small chat-adjacent bodies: player not found, notification, played time, random roll.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_u32_le, read_u64_le, read_u8};
 
-// ChatMsg values (VERIFIED vmangos `SharedDefines.h:1191-1301`, the 5875 band — every
-// `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_11_2`-or-earlier guard is compile-time true for build
-// 5875). vmangos's enum runs the full `0x00..=0x5D`; the combat-log/spell/skill/loot/money block
-// (0x09, 0x0F-0x13, 0x17-0x50, 0x52-0x56) is **never** `SMSG_MESSAGECHAT` wire in 1.12 — canned
-// emotes ride `SMSG_TEXT_EMOTE`, channel feedback rides `SMSG_CHANNEL_NOTIFY`/`_LIST`, and
-// skill/loot/money/xp lines are client-composed from their own opcodes (decision 0288) — so those
-// values have no named constant here. What's below is every type benilla either receives (as a
-// distinct wire shape or a renderable line) or sends.
-//
-// **`0x5B` was in that list until decision 2077 and it did not belong there.** It is
-// `CHAT_MSG_FILTERED`, and it is a real server→client line: 1.12's `ChatFrame.lua` puts it in
-// `ChatTypeGroup["SYSTEM"]` (l.128) and renders it at l.1405 as `format(CHAT_FILTERED, arg2)` —
-// "Unable to send chat to %s because your message contained reserved words." The client's own chat
-// chokepoint carves it out of the spam filter **by name** (`0x49aac9 cmp edi,0x5b`) precisely
-// because it is a line that arrives, and one the filter itself produces. vmangos declares the
-// constant and never sends it, which is what the wrong claim was really observing.
+// ChatMsg values (vmangos `SharedDefines.h:1191-1301`), only those benilla receives or sends.
+// Text emotes, channel notices and combat, skill, loot and money lines come from other opcodes.
 pub const CHAT_MSG_SAY: u8 = 0x00;
 pub const CHAT_MSG_PARTY: u8 = 0x01;
 pub const CHAT_MSG_RAID: u8 = 0x02;
@@ -37,12 +15,10 @@ pub const CHAT_MSG_GUILD: u8 = 0x03;
 pub const CHAT_MSG_OFFICER: u8 = 0x04;
 pub const CHAT_MSG_YELL: u8 = 0x05;
 pub const CHAT_MSG_WHISPER: u8 = 0x06;
-/// Server→client only ("You whisper to Name: …" self-echo, vmangos `MasterPlayerChat.cpp:54`) —
-/// never a `CMSG_MESSAGECHAT` type a client sends.
+/// Server-to-client only: the "You whisper to Name" self-echo (vmangos `MasterPlayerChat.cpp:54`).
 pub const CHAT_MSG_WHISPER_INFORM: u8 = 0x07;
 pub const CHAT_MSG_EMOTE: u8 = 0x08;
-/// GM dot-command feedback and other server-authored lines; always the single-sender-guid shape
-/// (the guid is usually 0).
+/// GM dot-command feedback and other server-authored lines; one sender guid, usually 0.
 pub const CHAT_MSG_SYSTEM: u8 = 0x0A;
 pub const CHAT_MSG_MONSTER_SAY: u8 = 0x0B;
 pub const CHAT_MSG_MONSTER_YELL: u8 = 0x0C;
@@ -50,47 +26,22 @@ pub const CHAT_MSG_MONSTER_EMOTE: u8 = 0x0D;
 pub const CHAT_MSG_CHANNEL: u8 = 0x0E;
 pub const CHAT_MSG_AFK: u8 = 0x14;
 pub const CHAT_MSG_DND: u8 = 0x15;
-/// The "so-and-so is ignoring you" self-notice (`WorldSession::HandleChatIgnoredOpcode`,
-/// `Handlers/ChatHandler.cpp:755-763`) — single-sender-guid shape, sender is the ignoring player.
+/// "Name is ignoring you": one sender guid, the ignoring player (`ChatHandler.cpp:755-763`).
 pub const CHAT_MSG_IGNORED: u8 = 0x16;
 pub const CHAT_MSG_MONSTER_WHISPER: u8 = 0x1A;
-/// `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_10_2` — active for 5875.
 pub const CHAT_MSG_RAID_LEADER: u8 = 0x57;
 pub const CHAT_MSG_RAID_WARNING: u8 = 0x58;
-/// `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_11_2` — active for 5875 (pre-1.11.3 this value
-/// aliased `CHAT_MSG_MONSTER_WHISPER` instead; irrelevant here since 5875 always takes this branch).
 pub const CHAT_MSG_RAID_BOSS_WHISPER: u8 = 0x59;
 pub const CHAT_MSG_RAID_BOSS_EMOTE: u8 = 0x5A;
-/// **The server's "your message was filtered" notice** — not a filtered incoming line. The stock
-/// chat frame formats it as `CHAT_FILTERED` over `arg2` (the addressee), so the wire text carries
-/// the name rather than a sentence. It is the one chat type the client's own spam filter is
-/// *disarmed* for (`0x49aacc`), it is absent from the profanity arm's 14-type table, and it is
-/// delivered whatever both CVars say. wow-re `system/ui/scratch/text-filter-law.md`.
+/// The server's "your message was filtered" notice, which the chat frame formats as
+/// `CHAT_FILTERED`; the client's spam and profanity filters exempt it (`0x49aacc`).
 pub const CHAT_MSG_FILTERED: u8 = 0x5B;
 pub const CHAT_MSG_BATTLEGROUND: u8 = 0x5C;
 pub const CHAT_MSG_BATTLEGROUND_LEADER: u8 = 0x5D;
 
-/// The chat types the real client runs its `$`-macro expander over, and the **only** ones — every
-/// other type, player chat included, reaches the frame verbatim.
-///
-/// **There are two gates in the reference, and this is the WIRE one** (decision 0759 corrects 0754,
-/// which shipped the other). VERIFIED in `WoW.exe` (5875):
-///
-/// - the **wire** path — `0x49d5e4-0x49d606` in the `SMSG_MESSAGECHAT` parser `0x49d560` — routes
-///   `0x0B 0x0C 0x0D 0x1A` **and `0x5A`** into the expanding branch at `0x49da3d`, plus
-///   `0x52 0x53 0x54` into the one at `0x49d961`. **Eight types.**
-/// - the **pending-chat** path — `0x49cf36-0x49cf5d`, guarding `0x49cf70` — is the *re*-expansion
-///   after a name query answers, and its chain is seven: it omits `0x5A`.
-///
-/// benilla decodes the wire, so the wire set is the one that applies. 0754 cited the pending gate
-/// and so dropped `RAID_BOSS_EMOTE` (`0x5A`) — a boss emote's `$n` would have stayed literal.
-///
-/// Note what the set is and isn't: the four monster shapes and `RAID_BOSS_EMOTE`, plus the three
-/// **battleground system** lines (`BG_SYSTEM_NEUTRAL`/`_ALLIANCE`/`_HORDE`, vmangos
-/// `SharedDefines.h:1279-1281`) — which is where "$n has taken the flag!" comes from, and why
-/// "the monster/boss family" is the wrong name for it. `RAID_BOSS_WHISPER` (`0x59`) is **not** in
-/// either gate: it takes its own branch at `0x49d610`, never expands, and is remapped to a plain
-/// whisper (`mov byte [ebp+0xf],0x6` @ `0x49d67e`).
+/// The only chat types the 1.12 client runs its `$`-macro expander over; the rest reach the frame
+/// verbatim. This is the wire gate (`0x49d5e4-0x49d606`); the re-expansion after a name query
+/// (`0x49cf36`) omits `0x5A`.
 pub const MACRO_EXPANDED_TYPES: [u8; 8] = [
     CHAT_MSG_MONSTER_SAY,        // 0x0B
     CHAT_MSG_MONSTER_YELL,       // 0x0C
@@ -99,18 +50,15 @@ pub const MACRO_EXPANDED_TYPES: [u8; 8] = [
     CHAT_MSG_BG_SYSTEM_NEUTRAL,  // 0x52
     CHAT_MSG_BG_SYSTEM_ALLIANCE, // 0x53
     CHAT_MSG_BG_SYSTEM_HORDE,    // 0x54
-    CHAT_MSG_RAID_BOSS_EMOTE,    // 0x5A — wire gate only; absent from the pending-chat gate
+    CHAT_MSG_RAID_BOSS_EMOTE,    // 0x5A, wire gate only
 ];
 
-/// `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_6_1` — active for 5875. The battleground system
-/// lines; they take `BuildChatPacket`'s `default:` branch, so their single guid slot IS the macro
-/// subject.
+/// The battleground system lines: one guid, the macro subject (`BuildChatPacket`'s `default:`).
 pub const CHAT_MSG_BG_SYSTEM_NEUTRAL: u8 = 0x52;
 pub const CHAT_MSG_BG_SYSTEM_ALLIANCE: u8 = 0x53;
 pub const CHAT_MSG_BG_SYSTEM_HORDE: u8 = 0x54;
 
-/// `PlayerChatTag` (VERIFIED vmangos `Chat/Chat.h:86-92`) — [`ChatMessage::chat_tag`]'s values.
-/// `Player::GetChatTag` (`Objects/Player.cpp:1757-1767`) picks GM over DND over AFK over none.
+/// vmangos `PlayerChatTag`; the server picks GM over DND over AFK (`Player.cpp:1757-1767`).
 pub mod chat_tag {
     pub const NONE: u8 = 0;
     pub const AFK: u8 = 1;
@@ -127,39 +75,22 @@ pub struct ChatMessage {
     pub language: u32,
     /// The speaker, when the type carries a guid (0 for system messages / name-only shapes).
     pub sender_guid: u64,
-    /// The **addressee** — the trailing guid slot the monster shapes carry (`0` for the shapes that
-    /// have none). Not display state: this is the subject the real client's `$`-macro expander
-    /// resolves monster chat against, which is why it is kept rather than dropped. See
-    /// [`MACRO_EXPANDED_TYPES`].
+    /// The trailing addressee guid, 0 when the shape has none; the `$`-macro subject.
     pub target_guid: u64,
-    /// The speaker's name, for the monster shapes that carry it inline (`None` elsewhere —
-    /// player names resolve via the name query, exactly like the real client).
+    /// The inline speaker name of the monster shapes; player names come from the name query.
     pub sender_name: Option<String>,
     /// The channel name, on `CHAT_MSG_CHANNEL` only.
     pub channel: Option<String>,
     pub text: String,
-    /// The trailing tag byte ([`chat_tag`]) — 0 none, 1 AFK, 2 DND, 3 GM. Drives the
-    /// `<AFK>`/`<DND>`/`<GM>` prefix the real chat frame prepends to the sender's name.
+    /// The [`chat_tag`] byte, shown as the `<AFK>`/`<DND>`/`<GM>` prefix on the sender's name.
     pub chat_tag: u8,
 }
 
 impl ChatMessage {
-    /// Is this line addon traffic rather than speech? (`language == LANG_ADDON`, decision 1029.)
+    /// Whether this is addon traffic, which the chat frame never prints: 1.12 has no addon opcode
+    /// or chat type, so `LANG_ADDON` on any lane is the only mark.
     ///
-    /// The `language` field is the **whole** discriminator: 1.12.1 has no addon opcode and no addon
-    /// `ChatMsg` type, so an addon broadcast is an ordinary `SMSG_MESSAGECHAT` on whichever lane it
-    /// was sent over — `CHAT_MSG_PARTY` for a hunter addon's version ping, `CHAT_MSG_CHANNEL` for a
-    /// hidden-channel protocol — and only the sentinel language tells it apart. The chat frame must
-    /// drop it; rendering it is what printed `[Party] [Soreen]: Quiver VERSION:3.1.4` (B215).
-    ///
-    /// The `text` of such a line is an addon payload, not a sentence: `prefix`, a TAB, then the
-    /// addon's own encoding. It is deliberately **not** split here — nothing consumes it until
-    /// benilla runs third-party addons, and the split rule belongs with the `CHAT_MSG_ADDON` fire
-    /// that would need it. When that lands, the rule is byte-verified and slightly
-    /// counter-intuitive (wow-re `system/ui/scratch/addon-chat-law.md`): the copy **starts** in the
-    /// prefix buffer and the **first** tab switches it to the message buffer, so text with no tab
-    /// at all yields `prefix = <the whole text>`, `message = ""` — not the reverse — and the event
-    /// still fires. Later tabs are literal payload bytes.
+    /// Its text is `prefix`, a TAB, the payload; with no tab, the 1.12 client reads all as prefix.
     pub fn is_addon(&self) -> bool {
         self.language == super::LANGUAGE_ADDON
     }
@@ -186,9 +117,7 @@ pub(super) fn read_message_chat(r: &mut &[u8]) -> io::Result<ChatMessage> {
     let chat_type = read_u8(r)?;
     let language = read_u32_le(r)?;
     let mut sender_guid = 0u64;
-    // The trailing "addressee" slot. Only the monster shapes carry one; it stays 0 elsewhere, and
-    // the macro expander then falls back to `sender_guid` (which is all the `default:` shapes — the
-    // BG system lines included — have).
+    // 0 unless the shape carries an addressee; the macro expander then uses `sender_guid`.
     let mut target_guid = 0u64;
     let mut sender_name = None;
     let mut channel = None;
@@ -215,9 +144,7 @@ pub(super) fn read_message_chat(r: &mut &[u8]) -> io::Result<ChatMessage> {
             let _player_rank = read_u32_le(r)?;
             sender_guid = read_u64_le(r)?;
         }
-        // Everything else (RAID/GUILD/OFFICER/WHISPER/WHISPER_INFORM/EMOTE/SYSTEM/AFK/DND/IGNORED/
-        // RAID_LEADER/RAID_WARNING/BATTLEGROUND(+LEADER)/BG_SYSTEM_*/…): one sender guid
-        // (vmangos `BuildChatPacket`'s own `default:` branch).
+        // Every other type is `BuildChatPacket`'s `default:` shape: one sender guid.
         _ => {
             sender_guid = read_u64_le(r)?;
         }
@@ -236,40 +163,28 @@ pub(super) fn read_message_chat(r: &mut &[u8]) -> io::Result<ChatMessage> {
     })
 }
 
-/// Read `SMSG_CHAT_PLAYER_NOT_FOUND` (VERIFIED vmangos `WorldPackets::Chat::ChatPlayerNotFound::
-/// AppendBodyTo`, `Server/Packets/Chat.cpp:26-29`): one cstring, the (un-normalized) name the
-/// player tried to whisper. Sent by `WorldSession::SendPlayerNotFoundNotice`
-/// (`Handlers/ChatHandler.cpp:766-771`) — a bad whisper target, offline or misspelled.
+/// Read `SMSG_CHAT_PLAYER_NOT_FOUND`: one cstring, the unnormalized name of an offline or
+/// misspelled whisper target (vmangos `Server/Packets/Chat.cpp:26-29`).
 pub(super) fn read_chat_player_not_found(r: &mut &[u8]) -> io::Result<String> {
     read_cstring(r)
 }
 
-/// Read `SMSG_NOTIFICATION` (VERIFIED vmangos `WorldSession::SendNotification`,
-/// `Server/WorldSession.cpp:900-915`: `data << szStr`): one cstring — the notice text, already
-/// formatted server-side ("You do not know that language", trade refusals, and kin). The real
-/// client flashes it in the red UIErrorsFrame.
+/// Read `SMSG_NOTIFICATION`: one cstring of server-formatted notice text, which the 1.12 client
+/// shows in the red UIErrorsFrame (vmangos `Server/WorldSession.cpp:900-915`).
 pub(super) fn read_notification(r: &mut &[u8]) -> io::Result<String> {
     read_cstring(r)
 }
 
-/// Read `SMSG_PLAYED_TIME` (VERIFIED vmangos `WorldPackets::Misc::PlayedTime::AppendBodyTo`,
-/// `Server/Packets/Misc.cpp:278-282`; handler `WorldSession::HandlePlayedTime`,
-/// `Handlers/MiscHandler.cpp:935-941`): `u32 totalPlayedTime` (seconds since character creation) +
-/// `u32 levelPlayedTime` (seconds since the last level-up) — answers `CMSG_PLAYED_TIME` (empty
-/// body, the `/played` command).
+/// Read `SMSG_PLAYED_TIME`, the `/played` answer: total then this-level played time, both `u32`
+/// seconds (vmangos `Server/Packets/Misc.cpp:278-282`).
 pub(super) fn read_played_time(r: &mut &[u8]) -> io::Result<(u32, u32)> {
     let total = read_u32_le(r)?;
     let level = read_u32_le(r)?;
     Ok((total, level))
 }
 
-/// Read `MSG_RANDOM_ROLL`'s server→client **broadcast** shape (VERIFIED vmangos
-/// `WorldSession::HandleRandomRollOpcode`, `Handlers/GroupHandler.cpp:394-422`): `u32 minimum, u32
-/// maximum, u32 roll` (the server's own `urand(minimum, maximum)`), then a **raw** `u64` guid — the
-/// roller (`data << GetPlayer()->GetObjectGuid()`, an `ObjectGuid` stream write, so unpacked).
-/// Same opcode as the client→server request shape (`u32 minimum, u32 maximum`,
-/// [`super::client::random_roll`]) — a client only ever *receives* this broadcast shape, never its
-/// own request echoed back.
+/// Read the `MSG_RANDOM_ROLL` broadcast (`GroupHandler.cpp:394-422`): `u32` minimum, maximum and
+/// roll, then the roller's unpacked `u64` guid; the request on this opcode is only min and max.
 pub(super) fn read_random_roll(r: &mut &[u8]) -> io::Result<(u32, u32, u32, u64)> {
     let min = read_u32_le(r)?;
     let max = read_u32_le(r)?;
diff --git a/crates/benilla-protocol/src/messages/client.rs b/crates/benilla-protocol/src/messages/client.rs
index ba10ccbc..6fcd3d3e 100644
--- a/crates/benilla-protocol/src/messages/client.rs
+++ b/crates/benilla-protocol/src/messages/client.rs
@@ -1,14 +1,10 @@
-//! Client packet **body builders** — the outbound half of the message layer (the inbound parse +
-//! the `ServerPacket` vocabulary stay in [`super`]; spell/attack builders live with their family
-//! in [`super::spells`]). Framing/encryption is `world.rs`'s job; these produce plain body bytes.
+//! Client packet body builders: plain body bytes, framed and encrypted elsewhere.
 
 use super::addons::{addon_tail, SecureAddon};
 use super::{CharCreateReq, MovementInfo};
 
-/// `CMSG_AUTH_SESSION` body: build, server id, account name, client seed, proof, and the
-/// **addon-info block** — `addons`' uncompressed size plus its zlib stream, exactly as the writer
-/// at `0x51d910` appends it (see [`super::addons`], decision 1497). Pass
-/// [`super::STOCK_SECURE_ADDONS`] for what a stock install sends.
+/// `CMSG_AUTH_SESSION` body: build, server id, account, seed, proof, then the addon block's
+/// uncompressed size and zlib stream (`0x51d910`); stock sends [`super::STOCK_SECURE_ADDONS`].
 pub fn auth_session(
     build: u32,
     username: &str,
@@ -28,15 +24,12 @@ pub fn auth_session(
     body
 }
 
-/// `CMSG_CHAR_CREATE` body: name (CString), then race/class/gender + the 5 appearance bytes
-/// (skin/face/hair_style/hair_color/facial_hair) + `outfit_id`. Matches vmangos's read exactly
-/// (`Packets/Character.cpp:4-19`): name + 9 bytes. `outfit_id` is always 0 — the server reads and
-/// ignores it (`CharacterHandler.cpp:310`) and recomputes start gear (decision 0423).
+/// `CMSG_CHAR_CREATE` body: the name cstring then nine bytes (`Packets/Character.cpp:4-19`); the
+/// last, `outfit_id`, is 0 because the server ignores it (`CharacterHandler.cpp:310`).
 pub fn char_create(req: &CharCreateReq) -> Vec<u8> {
     let mut body = Vec::with_capacity(req.name.len() + 10);
     body.extend_from_slice(req.name.as_bytes());
     body.push(0);
-    // race, class, gender, skin, face, hair_style, hair_color, facial_hair, outfit_id(0).
     body.extend_from_slice(&[
         req.race,
         req.class,
@@ -51,13 +44,8 @@ pub fn char_create(req: &CharCreateReq) -> Vec<u8> {
     body
 }
 
-/// `CMSG_MESSAGECHAT` body for every sendable `ChatMsg` type (VERIFIED vmangos
-/// `WorldPackets::Chat::ChatMessage::ReadFromWorldPacket`, `Server/Packets/Chat.cpp:3-12`):
-/// `recv_data >> type >> lang`, then `>> whisperTargetOrChannel` **only** for
-/// `CHAT_MSG_WHISPER`/`CHAT_MSG_CHANNEL` (the target name or channel name rides *before* the
-/// message, not after — vmangos's own union of the two), then `>> message`. `target` is `None` for
-/// every other sendable type. The general form [`messagechat`]/[`messagechat_whisper`]/
-/// [`messagechat_channel`] build on.
+/// `CMSG_MESSAGECHAT` body: `u32` type and language, the target or channel name for whisper and
+/// channel only (`None` otherwise), then the message (vmangos `Server/Packets/Chat.cpp:3-12`).
 pub fn messagechat_kind(
     chat_type: u32,
     language: u32,
@@ -76,31 +64,22 @@ pub fn messagechat_kind(
     body
 }
 
-/// `CMSG_MESSAGECHAT` body (chat type + language as `u32`, then the message) — the shape shared by
-/// every type that carries no target/channel name (SAY, YELL, EMOTE, PARTY, RAID, GUILD, OFFICER,
-/// RAID_LEADER, RAID_WARNING, BATTLEGROUND(+LEADER), AFK, DND). Thin wrapper over
-/// [`messagechat_kind`] with `target: None`.
+/// `CMSG_MESSAGECHAT` body for every type without a target or channel name.
 pub fn messagechat(chat_type: u32, language: u32, message: &str) -> Vec<u8> {
     messagechat_kind(chat_type, language, None, message)
 }
 
-/// `CMSG_MESSAGECHAT` body for `CHAT_MSG_WHISPER` (`0x6`): chat type + language, then the whisper
-/// **target's player name**, then the message. Thin wrapper over [`messagechat_kind`].
+/// `CMSG_MESSAGECHAT` body for a whisper: the target's player name precedes the message.
 pub fn messagechat_whisper(language: u32, target: &str, message: &str) -> Vec<u8> {
     messagechat_kind(super::CHAT_TYPE_WHISPER, language, Some(target), message)
 }
 
-/// `CMSG_MESSAGECHAT` body for `CHAT_MSG_CHANNEL` (`0xE`): chat type + language, then the
-/// **channel name**, then the message — the same wire shape as [`messagechat_whisper`], vmangos's
-/// `whisperTargetOrChannel` field doing double duty. Thin wrapper over [`messagechat_kind`].
+/// `CMSG_MESSAGECHAT` body for a channel line: the channel name precedes the message.
 pub fn messagechat_channel(language: u32, channel: &str, message: &str) -> Vec<u8> {
     messagechat_kind(super::CHAT_TYPE_CHANNEL, language, Some(channel), message)
 }
 
-/// Concatenate `strings` as back-to-back NUL-terminated C-strings — the shape shared by the whole
-/// `CMSG_CHANNEL_*` family (VERIFIED vmangos `Server/Packets/Channel.cpp`, every `ReadFromWorldPacket`
-/// there: a channel name alone, or a channel name + a second field — a password or a target player
-/// name).
+/// Back-to-back cstrings, the shape of every `CMSG_CHANNEL_*` body (`Packets/Channel.cpp`).
 fn cstrings_body(strings: &[&str]) -> Vec<u8> {
     let mut body = Vec::with_capacity(strings.iter().map(|s| s.len() + 1).sum());
     for s in strings {
@@ -110,125 +89,101 @@ fn cstrings_body(strings: &[&str]) -> Vec<u8> {
     body
 }
 
-/// `CMSG_JOIN_CHANNEL` body (VERIFIED vmangos `WorldPackets::Channel::JoinChannel::
-/// ReadFromWorldPacket`, `Server/Packets/Channel.cpp:3-7`): cstring channel name + cstring password
-/// (empty string for none) — **no channel id** on the 1.12 wire (a TBC+ addition).
+/// `CMSG_JOIN_CHANNEL` body: channel name, then password (empty for none); 1.12 sends no channel
+/// id (`Channel.cpp:3-7`).
 pub fn join_channel(name: &str, password: &str) -> Vec<u8> {
     cstrings_body(&[name, password])
 }
 
-/// `CMSG_LEAVE_CHANNEL` body: cstring channel name (VERIFIED vmangos
-/// `WorldPackets::Channel::LeaveChannel::ReadFromWorldPacket`, `Channel.cpp:9-12`).
+/// `CMSG_LEAVE_CHANNEL` body: the channel name (`Channel.cpp:9-12`).
 pub fn leave_channel(name: &str) -> Vec<u8> {
     cstrings_body(&[name])
 }
 
-/// `CMSG_CHANNEL_LIST` body — asks for the member roster (VERIFIED vmangos
-/// `WorldPackets::Channel::ChannelList::ReadFromWorldPacket`, `Channel.cpp:14-17`): cstring channel
-/// name. Answered by `SMSG_CHANNEL_LIST` ([`super::channel::read_channel_list`]).
+/// `CMSG_CHANNEL_LIST` body, the member-roster request: the channel name (`Channel.cpp:14-17`).
 pub fn channel_list(name: &str) -> Vec<u8> {
     cstrings_body(&[name])
 }
 
-/// `CMSG_CHANNEL_PASSWORD` body (VERIFIED vmangos `ChannelPassword::ReadFromWorldPacket`,
-/// `Channel.cpp:19-23`): cstring channel name + cstring new password.
+/// `CMSG_CHANNEL_PASSWORD` body: channel name, then the new password (`Channel.cpp:19-23`).
 pub fn channel_password(name: &str, password: &str) -> Vec<u8> {
     cstrings_body(&[name, password])
 }
 
-/// `CMSG_CHANNEL_SET_OWNER` body (VERIFIED vmangos `ChannelSetOwner::ReadFromWorldPacket`,
-/// `Channel.cpp:25-29`): cstring channel name + cstring new owner's player name.
+/// `CMSG_CHANNEL_SET_OWNER` body: channel name, then the new owner's name (`Channel.cpp:25-29`).
 pub fn channel_set_owner(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_OWNER` body — asks who owns the channel (VERIFIED vmangos
-/// `ChannelOwner::ReadFromWorldPacket`, `Channel.cpp:31-34`): cstring channel name only (the answer
-/// rides `SMSG_CHANNEL_NOTIFY`'s [`super::channel::channel_notice::CHANNEL_OWNER`] notice).
+/// `CMSG_CHANNEL_OWNER` body: the channel name (`Channel.cpp:31-34`); the answer is a
+/// `SMSG_CHANNEL_NOTIFY` owner notice.
 pub fn channel_owner(name: &str) -> Vec<u8> {
     cstrings_body(&[name])
 }
 
-/// `CMSG_CHANNEL_MODERATOR` body (VERIFIED vmangos `ChannelModerator::ReadFromWorldPacket`,
-/// `Channel.cpp:36-40`): cstring channel name + cstring target player name.
+/// `CMSG_CHANNEL_MODERATOR` body: channel name, then the player's name (`Channel.cpp:36-40`).
 pub fn channel_moderator(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_UNMODERATOR` body (VERIFIED vmangos `ChannelUnmoderator::ReadFromWorldPacket`,
-/// `Channel.cpp:42-46`): cstring channel name + cstring target player name.
+/// `CMSG_CHANNEL_UNMODERATOR` body: channel name, then the player's name (`Channel.cpp:42-46`).
 pub fn channel_unmoderator(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_MUTE` body (VERIFIED vmangos `ChannelMute::ReadFromWorldPacket`,
-/// `Channel.cpp:48-52`): cstring channel name + cstring target player name.
+/// `CMSG_CHANNEL_MUTE` body: channel name, then the player's name (`Channel.cpp:48-52`).
 pub fn channel_mute(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_UNMUTE` body (VERIFIED vmangos `ChannelUnmute::ReadFromWorldPacket`,
-/// `Channel.cpp:54-58`): cstring channel name + cstring target player name.
+/// `CMSG_CHANNEL_UNMUTE` body: channel name, then the player's name (`Channel.cpp:54-58`).
 pub fn channel_unmute(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_INVITE` body (VERIFIED vmangos `ChannelInvite::ReadFromWorldPacket`,
-/// `Channel.cpp:60-64`): cstring channel name + cstring invitee player name.
+/// `CMSG_CHANNEL_INVITE` body: channel name, then the invitee's name (`Channel.cpp:60-64`).
 pub fn channel_invite(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_KICK` body (VERIFIED vmangos `ChannelKick::ReadFromWorldPacket`,
-/// `Channel.cpp:66-70`): cstring channel name + cstring target player name.
+/// `CMSG_CHANNEL_KICK` body: channel name, then the player's name (`Channel.cpp:66-70`).
 pub fn channel_kick(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_BAN` body (VERIFIED vmangos `ChannelBan::ReadFromWorldPacket`,
-/// `Channel.cpp:72-76`): cstring channel name + cstring target player name.
+/// `CMSG_CHANNEL_BAN` body: channel name, then the player's name (`Channel.cpp:72-76`).
 pub fn channel_ban(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_UNBAN` body (VERIFIED vmangos `ChannelUnban::ReadFromWorldPacket`,
-/// `Channel.cpp:78-82`): cstring channel name + cstring target player name.
+/// `CMSG_CHANNEL_UNBAN` body: channel name, then the player's name (`Channel.cpp:78-82`).
 pub fn channel_unban(name: &str, player: &str) -> Vec<u8> {
     cstrings_body(&[name, player])
 }
 
-/// `CMSG_CHANNEL_ANNOUNCEMENTS` body — toggles the channel's join/leave announcements (VERIFIED
-/// vmangos `ChannelAnnouncements::ReadFromWorldPacket`, `Channel.cpp:84-87`): cstring channel name
-/// only.
+/// `CMSG_CHANNEL_ANNOUNCEMENTS` body, the join/leave notice toggle (`Channel.cpp:84-87`).
 pub fn channel_announcements(name: &str) -> Vec<u8> {
     cstrings_body(&[name])
 }
 
-/// `CMSG_CHANNEL_MODERATE` body — toggles channel moderation (VERIFIED vmangos
-/// `ChannelModerate::ReadFromWorldPacket`, `Channel.cpp:89-92`): cstring channel name only.
+/// `CMSG_CHANNEL_MODERATE` body, the moderation toggle (`Channel.cpp:89-92`).
 pub fn channel_moderate(name: &str) -> Vec<u8> {
     cstrings_body(&[name])
 }
 
-/// `CMSG_PLAYED_TIME` body — empty (VERIFIED vmangos: the handler takes a `NullClientPacket`,
-/// `Handlers/MiscHandler.cpp:935`). The `/played` request.
+/// `CMSG_PLAYED_TIME` body, the `/played` request: empty (`Handlers/MiscHandler.cpp:935`).
 pub fn played_time() -> Vec<u8> {
     Vec::new()
 }
 
-/// `CMSG_QUERY_TIME` body — empty (VERIFIED vmangos: `HandleQueryTimeOpcode` takes a
-/// `NullClientPacket`, `Handlers/QueryHandler.cpp:107`). Asks for the server's wall clock; the
-/// answer is `SMSG_QUERY_TIME_RESPONSE`, one `u32` of unix-epoch seconds. Decision 1150 — a timed
-/// quest's deadline is an absolute stamp in *that* epoch, so the countdown is only as right as our
-/// sample of the server's clock.
+/// `CMSG_QUERY_TIME` body: empty (`Handlers/QueryHandler.cpp:107`). The answer is the server's
+/// clock in unix seconds, the epoch timed-quest deadlines are stamped in.
 pub fn query_time() -> Vec<u8> {
     Vec::new()
 }
 
-/// `MSG_RANDOM_ROLL` client→server request body (VERIFIED vmangos
-/// `WorldPackets::Group::RandomRoll::ReadFromWorldPacket`, `Server/Packets/Group.cpp:39-43`): `u32
-/// minimum + u32 maximum`. The server validates `minimum <= maximum <= 10000` and broadcasts the
-/// roll (layout in [`super::chat::read_random_roll`]); an out-of-range request is silently dropped.
+/// `MSG_RANDOM_ROLL` request body (`Server/Packets/Group.cpp:39-43`); the server silently drops
+/// one outside `minimum <= maximum <= 10000`.
 pub fn random_roll(min: u32, max: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(8);
     body.extend_from_slice(&min.to_le_bytes());
@@ -236,14 +191,8 @@ pub fn random_roll(min: u32, max: u32) -> Vec<u8> {
     body
 }
 
-/// `CMSG_TEXT_EMOTE` body: `u32 textEmote (EmotesText.dbc id), u32 emoteNum, u64 target guid`
-/// (0 = no target) — VERIFIED vmangos `TextEmote::ReadFromWorldPacket` (`Misc.cpp:60-65`), three
-/// fields. `emoteNum` is only relayed to observers inside `SMSG_TEXT_EMOTE` (the emote-text
-/// variation index; we send 0 = the first variation). The 12-byte two-field body this originally
-/// sent made the server's guid read run off the packet's end — the emote was silently discarded,
-/// on every send, which read as "/wave does nothing" (director-caught against the ref client).
-/// The server echoes `SMSG_TEXT_EMOTE` to everyone in range **including us**, so our own emote
-/// sound/anim plays through the same receive path as everyone else's.
+/// `CMSG_TEXT_EMOTE` body: `u32` EmotesText.dbc id, `u32` text variation (only relayed), `u64`
+/// target or 0 (`Misc.cpp:60-65`). The server echoes `SMSG_TEXT_EMOTE` to us as well.
 pub fn text_emote(text_id: u32, target: u64) -> Vec<u8> {
     let mut b = Vec::with_capacity(16);
     b.extend_from_slice(&text_id.to_le_bytes());
@@ -256,8 +205,7 @@ pub fn full_guid(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// Body of a `CMSG_CREATURE_QUERY`: the template `entry` + the asking guid (VERIFIED vmangos
-/// `QueryCreature::ReadFromWorldPacket` — `entry` then a full 8-byte guid).
+/// `CMSG_CREATURE_QUERY` body: the template entry, then a full guid (vmangos `QueryCreature`).
 pub fn creature_query(entry: u32, guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&entry.to_le_bytes());
@@ -265,10 +213,8 @@ pub fn creature_query(entry: u32, guid: u64) -> Vec<u8> {
     body
 }
 
-/// Body of a `CMSG_PET_NAME_QUERY`: the pet's **number** then its full guid (VERIFIED vmangos
-/// `QueryPetName::ReadFromWorldPacket`, `Server/Packets/Pet.cpp:3-7`). Both values come out of the
-/// pet's own guid ([`crate::guid::pet_number`]); the server answers only when the number agrees with
-/// the live pet's `CharmInfo` (`PetHandler.cpp:190-192`), and stays silent otherwise.
+/// `CMSG_PET_NAME_QUERY` body: the pet number, then its full guid (`Server/Packets/Pet.cpp:3-7`);
+/// the server stays silent unless the number matches the live pet (`PetHandler.cpp:190-192`).
 pub fn pet_name_query(pet_number: u32, guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&pet_number.to_le_bytes());
@@ -276,19 +222,15 @@ pub fn pet_name_query(pet_number: u32, guid: u64) -> Vec<u8> {
     body
 }
 
-/// Body of a movement message (`MSG_MOVE_*`) — a `MovementInfo`.
+/// Body of a `MSG_MOVE_*` message: a `MovementInfo`.
 pub fn movement(info: &MovementInfo) -> Vec<u8> {
     let mut body = Vec::with_capacity(28);
     info.write(&mut body);
     body
 }
 
-/// Body of `CMSG_MOVE_TIME_SKIPPED` (client): the mover's **full 8-byte** guid then the skipped
-/// milliseconds (vmangos `MoveTimeSkipped::ReadFromWorldPacket`, `Server/Packets/Movement.cpp:10-14`
-/// — `recv_data >> guid` is `ObjectGuid`'s plain `read<uint64>`, `ObjectGuid.cpp:180`, not the
-/// packed reader `PackedGuidReader` takes). Note the asymmetry with the server's own relay of the
-/// same fact, `MSG_MOVE_TIME_SKIPPED`, which writes `GetPackGUID()` (`MovementHandler.cpp:1014`):
-/// inbound is full, outbound is packed.
+/// `CMSG_MOVE_TIME_SKIPPED` body: the mover's unpacked guid, then the skipped ms
+/// (`Server/Packets/Movement.cpp:10-14`); the server's relayed `MSG_MOVE_TIME_SKIPPED` packs it.
 pub fn move_time_skipped(guid: u64, lag_ms: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&guid.to_le_bytes());
@@ -296,15 +238,9 @@ pub fn move_time_skipped(guid: u64, lag_ms: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_MOVE_SPLINE_DONE` (client): the `MovementInfo` at the ride's endpoint, the
-/// `spline_id` being acknowledged (matched against the server's newest spline for our mover), and a
-/// trailing float the server reads-and-discards (`MoveSplineDone::ReadFromWorldPacket` does an
-/// unconditional `read_skip<float>()`, so the four bytes MUST be present or the server's parse
-/// under-runs). The real client writes its **completion fraction** `clamp(elapsed/duration, 0, 1)`
-/// there (byte-verified — `0x600b10`, decision 0496 §claim-6); we only ever send at ride
-/// completion, so the faithful value is `1.0`. Emitted once when a server spline that drove our own
-/// player (Charge/knockback/taxi) finishes; the server then relocates us and re-broadcasts a
-/// stop/heartbeat to observers.
+/// `CMSG_MOVE_SPLINE_DONE` body: the `MovementInfo` at the ride's end, the acked spline id, and a
+/// float the server skips but requires. The 1.12 client writes its completion fraction there
+/// (`0x600b10`); we send only at completion, so it is always 1.0.
 pub fn move_spline_done(info: &MovementInfo, spline_id: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(36);
     info.write(&mut body);
@@ -313,8 +249,7 @@ pub fn move_spline_done(info: &MovementInfo, spline_id: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `MSG_MOVE_TELEPORT_ACK` (client): a **full** 8-byte GUID (not packed — vmangos requires
-/// it for this opcode), the movement counter, and the client time.
+/// `MSG_MOVE_TELEPORT_ACK` body: an unpacked guid (vmangos requires it), counter, client time.
 pub fn teleport_ack(guid: u64, counter: u32, time_ms: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&guid.to_le_bytes());
@@ -323,13 +258,9 @@ pub fn teleport_ack(guid: u64, counter: u32, time_ms: u32) -> Vec<u8> {
     body
 }
 
-/// Body of a `CMSG_FORCE_*_SPEED_CHANGE_ACK` (all six kinds share it): a **full** 8-byte guid (the
-/// mover the SMSG named — vmangos `MoveSpeedAck::ReadFromWorldPacket` extracts a plain `ObjectGuid`,
-/// which reads a raw `uint64`, `ObjectGuid.cpp:180` — NOT packed, unlike the SMSG's guid), the
-/// echoed movement counter, our live `MovementInfo`, and the echoed new speed. The server accepts
-/// only an exact counter match and a speed within ±0.01 of what it sent
-/// (`Unit::FindPendingMovementSpeedChange`), then relocates us to the carried pose — so the info
-/// must be the mover's honest live state, same as any `MSG_MOVE_*`.
+/// Body of all six `CMSG_FORCE_*_SPEED_CHANGE_ACK`s: the mover's unpacked guid, the echoed
+/// counter, our live `MovementInfo`, the echoed speed. The server needs an exact counter and a
+/// speed within 0.01 (`Unit::FindPendingMovementSpeedChange`), then moves us to that pose.
 pub fn force_speed_ack(guid: u64, counter: u32, info: &MovementInfo, speed: f32) -> Vec<u8> {
     let mut body = Vec::with_capacity(44);
     body.extend_from_slice(&guid.to_le_bytes());
@@ -339,10 +270,8 @@ pub fn force_speed_ack(guid: u64, counter: u32, info: &MovementInfo, speed: f32)
     body
 }
 
-/// Body of `CMSG_PING` (the ~30 s keepalive): `{u32 sequence, u32 lastRtt}` — VERIFIED twice, wow-re
-/// net W1 (`SendPing 0x537e10`: seq = ++counter, then the last measured round-trip ms) and vmangos
-/// `WorldSocket::_HandlePing` (`recvPacket >> ping >> latency`). The server echoes `sequence` back
-/// as `SMSG_PONG` and stores `lastRtt` as the session's reported latency.
+/// `CMSG_PING` body, the ~30 s keepalive (`0x537e10`): the sequence, then the last round trip in
+/// ms, which the server stores as our latency; it echoes the sequence in `SMSG_PONG`.
 pub fn ping(sequence: u32, last_rtt_ms: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(8);
     body.extend_from_slice(&sequence.to_le_bytes());
@@ -350,18 +279,10 @@ pub fn ping(sequence: u32, last_rtt_ms: u32) -> Vec<u8> {
     body
 }
 
-/// Body of a **movement-mode ack** — the whole ack'd family (root / water-walk / feather-fall /
-/// hover; decisions 0308, 0866): a **full** `u64` guid, the echoed `u32` movement counter, our
-/// current `MovementInfo`, and — for every mode *except root* — a trailing `u32 apply` (VERIFIED
-/// vmangos `Server/Packets/Movement.cpp:38-59`: `MoveFlagChangeAck` reads the apply dword,
-/// `MoveRootAck` does not; [`MoveMode::ack_carries_apply`](super::MoveMode::ack_carries_apply) is
-/// that rule). The counter MUST be the one the server sent — a zero/greater counter trips its cheat
-/// log (`HandleMoveRootAck`).
-///
-/// **`info.flags` must carry the applied mode bit.** vmangos hard-requires it for root
-/// (`HandleMoveRootAck:715` KICKS an apply-ack whose `MovementInfo` lacks `MOVEFLAG_ROOT`) and takes
-/// the word as the mover's new flags for the rest — so an ack that drops the bit un-grants the very
-/// mode it is accepting.
+/// Body of a movement-mode ack: unpacked guid, the echoed counter, our `MovementInfo`, then
+/// `u32 apply` for every mode but root (`Server/Packets/Movement.cpp:38-59`). `info.flags` must
+/// carry the applied mode bit: vmangos kicks a root ack without it (`MovementHandler.cpp:722-729`)
+/// and takes the flags as the mover's new ones for the other modes.
 pub fn move_flag_ack(guid: u64, counter: u32, info: &MovementInfo, apply: Option<bool>) -> Vec<u8> {
     let mut body = Vec::with_capacity(48);
     body.extend_from_slice(&guid.to_le_bytes());
@@ -373,18 +294,10 @@ pub fn move_flag_ack(guid: u64, counter: u32, info: &MovementInfo, apply: Option
     body
 }
 
-/// Body of `CMSG_MOVE_KNOCK_BACK_ACK` (decision 1702) — **the same shape as a movement-mode ack
-/// without its trailing `apply`**: a full `u64` guid, the echoed `u32` counter, and our
-/// `MovementInfo`. Not a coincidence of layout: both land on a `WorldSession::HandleMove*Ack` that
-/// reads exactly `guid >> counter >> movementInfo` (vmangos `Server/Packets/Movement.cpp:38-68`),
-/// so they are one wire shape with two meanings, and delegating says so.
-///
-/// **`info` must carry `MOVEFLAG_JUMPING` and the launch quad in its jump tail.**
-/// `Unit::FindPendingMovementKnockbackChange` walks the pending changes and matches on the counter
-/// *plus* all four floats within `0.01`; miss, and the ack is discarded as `OnWrongAckData` and the
-/// knockback never reaches observers (the server builds their `MSG_MOVE_KNOCK_BACK` from this very
-/// `MovementInfo`). Send nothing at all and it is `OnFailedToAckChange` — a knockback is the one
-/// pending change vmangos refuses to re-send (`Unit.cpp:6887`).
+/// `CMSG_MOVE_KNOCK_BACK_ACK` body, a movement-mode ack without `apply` (`Movement.cpp:38-68`).
+/// `info` must carry `MOVEFLAG_JUMPING` and the launch quad: the server matches the counter and
+/// all four floats within 0.01 (`Unit::FindPendingMovementKnockbackChange`), builds observers'
+/// `MSG_MOVE_KNOCK_BACK` from this info, and never re-sends a knockback (`Unit.cpp:6887`).
 pub fn knock_back_ack(guid: u64, counter: u32, info: &MovementInfo) -> Vec<u8> {
     move_flag_ack(guid, counter, info, None)
 }
@@ -394,11 +307,7 @@ mod tests {
     use super::*;
     use crate::wire::Vector3d;
 
-    /// `CMSG_MOVE_SPLINE_DONE` body, byte-exact: a `MovementInfo` (here with no swim/jump tail),
-    /// then the acked `splineId`, then the trailing float the server `read_skip`s. The order and the
-    /// mandatory-but-ignored trailing four bytes are what vmangos `MoveSplineDone::ReadFromWorldPacket`
-    /// requires (`>> movementInfo; >> splineId; read_skip<float>()`); omitting the float under-runs
-    /// its parse. A new wire body never lands without a golden (method).
+    /// vmangos `MoveSplineDone::ReadFromWorldPacket` reads info, spline id, then a skipped float.
     #[test]
     fn move_spline_done_body_golden() {
         let info = MovementInfo {
@@ -429,7 +338,6 @@ mod tests {
             0x00, 0x00, 0x80, 0x3F, // completion fraction 1.0 (server-skipped)
         ];
         assert_eq!(body, want, "CMSG_MOVE_SPLINE_DONE body");
-        // The leading bytes are exactly a MovementInfo (the shape the server reads first).
         let mi = movement(&info);
         assert_eq!(
             &body[..mi.len()],
diff --git a/crates/benilla-protocol/src/messages/combat_log.rs b/crates/benilla-protocol/src/messages/combat_log.rs
index a3c26f16..a485725d 100644
--- a/crates/benilla-protocol/src/messages/combat_log.rs
+++ b/crates/benilla-protocol/src/messages/combat_log.rs
@@ -1,16 +1,5 @@
-//! The **combat log** wire — the inbound "what just happened to whom" packets: spell damage,
-//! periodic aura ticks, heals, power gains, damage shields, environmental damage, and a cast's
-//! per-target miss list. Split out of `messages/spells.rs` (decision 0640), where these already sat
-//! behind a hand-drawn `--- the combat-log wire ---` banner; the banner was the concern boundary the
-//! file couldn't express.
-//!
-//! Every layout here is VERIFIED against vmangos source (cited per item). This family is **inbound
-//! only** — nothing in it has an outbound counterpart, so unlike its siblings it has no
-//! `world::writer` twin. Its consumer is the floating/center combat text (decisions 0137 phase 2,
-//! 0578, 0580) plus the fall-damage dust puff (`EnvironmentalDamageLog`).
-//!
-//! The melee half of the same story is [`super::attack`]'s `SMSG_ATTACKERSTATEUPDATE`: a *swing*
-//! reports itself there, a *spell* reports itself here.
+//! The combat log wire, inbound only: spell damage, periodic ticks, heals, power gains, damage
+//! shields, environmental damage, misses, kills, dispels, enchants and spell effect logs.
 
 use std::io::{self, Read};
 
@@ -18,9 +7,8 @@ use crate::wire::{
     capacity_hint, read_f32_le, read_i32_le, read_packed_guid, read_u32_le, read_u64_le, read_u8,
 };
 
-/// One decoded `SMSG_SPELLNONMELEEDAMAGELOG` — non-melee (spell) damage dealt (vmangos
-/// `WorldPackets::Spell::SpellNonMeleeDamageLog::AppendBodyTo`, `Server/Packets/Spell.cpp:124-140` +
-/// `Spell.h:178-198`). `hit_info` bit `0x2` is `SPELL_HIT_TYPE_CRIT` (vmangos `SpellDefines.h:179`).
+/// `SMSG_SPELLNONMELEEDAMAGELOG`, spell damage dealt (`Server/Packets/Spell.cpp:124-140`);
+/// `hit_info` bit `0x2` is a crit (`SpellDefines.h:179`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SpellDamageLog {
     pub target: u64,
@@ -35,9 +23,6 @@ pub struct SpellDamageLog {
     pub hit_info: u32,
 }
 
-/// Read `SMSG_SPELLNONMELEEDAMAGELOG`: target PackedGuid · attacker PackedGuid · spellId u32 ·
-/// damage u32 · school u8 · absorbed u32 · resist i32 · periodicLog u8 (bool) · unused u8 · blocked
-/// u32 · hitInfo u32 · extendedData u8 (always 0 — read and dropped).
 pub(super) fn read_spell_damage_log(r: &mut impl Read) -> io::Result<SpellDamageLog> {
     let target = read_packed_guid(r)?;
     let attacker = read_packed_guid(r)?;
@@ -65,11 +50,7 @@ pub(super) fn read_spell_damage_log(r: &mut impl Read) -> io::Result<SpellDamage
     })
 }
 
-/// One tick of `SMSG_PERIODICAURALOG` — the payload shape depends on the tick's `AuraType` (vmangos
-/// `SpellAuraDefines.h`): `PERIODIC_DAMAGE` (3) / `PERIODIC_DAMAGE_PERCENT` (89) carry a damage
-/// breakdown; `PERIODIC_HEAL` (8) / `OBS_MOD_HEALTH` (20) a plain heal amount; `OBS_MOD_MANA` (21) /
-/// `PERIODIC_ENERGIZE` (24) a power+amount pair; `PERIODIC_MANA_LEECH` (64) a power+amount+multiplier
-/// triple.
+/// One `SMSG_PERIODICAURALOG` tick, shaped by its aura type (vmangos `SpellAuraDefines.h`).
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum PeriodicTick {
     Damage {
@@ -92,9 +73,7 @@ pub enum PeriodicTick {
     },
 }
 
-/// One decoded `SMSG_PERIODICAURALOG` — periodic (DoT/HoT/regen) aura ticks (vmangos
-/// `Unit::SendPeriodicAuraLog`, `Unit.cpp:4395-4443`). vmangos always writes `count == 1`; the loop
-/// is decoded faithfully regardless.
+/// `SMSG_PERIODICAURALOG`, periodic aura ticks (vmangos `Unit.cpp:4395-4443`).
 #[derive(Debug, Clone, PartialEq)]
 pub struct PeriodicAuraLog {
     pub target: u64,
@@ -111,9 +90,7 @@ const AURA_PERIODIC_ENERGIZE: u32 = 24;
 const AURA_PERIODIC_MANA_LEECH: u32 = 64;
 const AURA_PERIODIC_DAMAGE_PERCENT: u32 = 89;
 
-/// Read `SMSG_PERIODICAURALOG`: target PackedGuid · caster PackedGuid · spellId u32 · count u32 ·
-/// `count` entries of `{auraType u32, payload}` — see [`PeriodicTick`] for the payload shapes. An
-/// aura type outside that set cannot be skipped without desyncing the stream, so it errors instead.
+/// Read `SMSG_PERIODICAURALOG`; an unknown aura type errors, as its payload width is unknown.
 pub(super) fn read_periodic_aura_log(r: &mut impl Read) -> io::Result<PeriodicAuraLog> {
     let target = read_packed_guid(r)?;
     let caster = read_packed_guid(r)?;
@@ -159,9 +136,7 @@ pub(super) fn read_periodic_aura_log(r: &mut impl Read) -> io::Result<PeriodicAu
     })
 }
 
-/// One decoded `SMSG_SPELLHEALLOG` — a direct heal landing (vmangos
-/// `WorldPackets::Spell::SpellHealLog::AppendBodyTo`, `Server/Packets/Spell.cpp:105-112` +
-/// `Spell.h:151-163`) — the center combat text's HEAL/HEAL_CRIT feed (decision 0578).
+/// `SMSG_SPELLHEALLOG`, a direct heal landing (`Server/Packets/Spell.cpp:105-112`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SpellHealLog {
     pub target: u64,
@@ -171,8 +146,6 @@ pub struct SpellHealLog {
     pub critical: bool,
 }
 
-/// Read `SMSG_SPELLHEALLOG`: target PackedGuid · healer PackedGuid · spellId u32 · amount u32 ·
-/// critical u8 (bool).
 pub(super) fn read_spell_heal_log(r: &mut impl Read) -> io::Result<SpellHealLog> {
     Ok(SpellHealLog {
         target: read_packed_guid(r)?,
@@ -183,10 +156,8 @@ pub(super) fn read_spell_heal_log(r: &mut impl Read) -> io::Result<SpellHealLog>
     })
 }
 
-/// One decoded `SMSG_SPELLENERGIZELOG` — an instant power gain (vmangos
-/// `WorldPackets::Spell::SpellEnergizeLog::AppendBodyTo`, `Server/Packets/Spell.cpp:114-121` +
-/// `Spell.h:165-176`). `power` is the vmangos `Powers` enum (0 mana · 1 rage · 2 focus ·
-/// 3 energy · 4 happiness) — the center combat text's MANA/RAGE/FOCUS/ENERGY feed.
+/// `SMSG_SPELLENERGIZELOG`, an instant power gain (`Server/Packets/Spell.cpp:114-121`); `power` is
+/// 0 mana, 1 rage, 2 focus, 3 energy, 4 happiness.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SpellEnergizeLog {
     pub target: u64,
@@ -196,8 +167,6 @@ pub struct SpellEnergizeLog {
     pub amount: u32,
 }
 
-/// Read `SMSG_SPELLENERGIZELOG`: target PackedGuid · caster PackedGuid · spellId u32 ·
-/// powerType u32 · amount u32.
 pub(super) fn read_spell_energize_log(r: &mut impl Read) -> io::Result<SpellEnergizeLog> {
     Ok(SpellEnergizeLog {
         target: read_packed_guid(r)?,
@@ -208,10 +177,8 @@ pub(super) fn read_spell_energize_log(r: &mut impl Read) -> io::Result<SpellEner
     })
 }
 
-/// One decoded `SMSG_SPELLDAMAGESHIELD` — a damage-shield (Thorns-style) return hit (vmangos
-/// `WorldPackets::Combat::SpellDamageShield::AppendBodyTo`, `Server/Packets/Combat.cpp:73-79` +
-/// `Combat.h:124-134`). `victim` is the shield's bearer; `attacker` is the unit that struck them and
-/// now **receives** this damage back.
+/// `SMSG_SPELLDAMAGESHIELD`, a Thorns-style return hit (`Server/Packets/Combat.cpp:73-79`):
+/// `victim` bears the shield, `attacker` struck it and takes this damage.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct DamageShield {
     pub victim: u64,
@@ -220,8 +187,6 @@ pub struct DamageShield {
     pub school: u32,
 }
 
-/// Read `SMSG_SPELLDAMAGESHIELD`: victim raw `u64` guid · attacker raw `u64` guid · damage u32 ·
-/// school u32.
 pub(super) fn read_damage_shield(r: &mut impl Read) -> io::Result<DamageShield> {
     Ok(DamageShield {
         victim: read_u64_le(r)?,
@@ -231,13 +196,9 @@ pub(super) fn read_damage_shield(r: &mut impl Read) -> io::Result<DamageShield>
     })
 }
 
-/// One decoded `SMSG_ENVIRONMENTALDAMAGELOG` — environmental damage taken: fall, drowning,
-/// fatigue, lava, slime, fire (vmangos `Unit::SendEnvironmentalDamageLog`, `Objects/Unit.cpp:5392`
-/// → `WorldPackets::Combat::EnvironmentalDamageLog::AppendBodyTo`, `Server/Packets/Combat.cpp:58-67`;
-/// the absorb/resist tail is the `> 1.6.1` layout our 5875 wire carries). `damage_type` is
-/// vmangos `EnvironmentalDamageType` (`Objects/Player.h:590`): 0 exhausted · 1 drowning ·
-/// 2 **fall** · 3 lava · 4 slime · 5 fire — the index into the client's `EnvironmentalDamage.dbc`
-/// 6-slot damage-type → SpellVisualKit table (its fall row is the landing dust puff).
+/// `SMSG_ENVIRONMENTALDAMAGELOG`, environmental damage taken (`Server/Packets/Combat.cpp:58-67`).
+/// `damage_type` is 0 exhausted, 1 drowning, 2 fall, 3 lava, 4 slime, 5 fire (`Player.h:590`), the
+/// row of `EnvironmentalDamage.dbc` whose visual kit plays (fall's is the landing dust puff).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct EnvironmentalDamageLog {
     pub victim: u64,
@@ -247,9 +208,7 @@ pub struct EnvironmentalDamageLog {
     pub resist: i32,
 }
 
-/// Read `SMSG_ENVIRONMENTALDAMAGELOG`: victim raw `u64` guid (vmangos `ObjectGuid.cpp:174`
-/// streams the raw value; the client reads it with its plain 8-byte guid reader `0x4190b0`) ·
-/// damageType u8 · damage u32 · absorbed u32 · resist i32.
+/// Read `SMSG_ENVIRONMENTALDAMAGELOG`; the victim guid is raw on both ends (client `0x4190b0`).
 pub(super) fn read_environmental_damage_log(
     r: &mut impl Read,
 ) -> io::Result<EnvironmentalDamageLog> {
@@ -262,12 +221,9 @@ pub(super) fn read_environmental_damage_log(
     })
 }
 
-/// One decoded `SMSG_SPELLLOGMISS` — a spell cast's per-target miss list (vmangos
-/// `WorldPackets::Spell::SpellLogMiss::AppendBodyTo`, `Server/Packets/Spell.cpp:68-86` +
-/// `Spell.h:109-124`). Each entry's `u8` is a `SpellMissInfo` (vmangos `SpellDefines.h:160-174`,
-/// the same vocabulary [`SpellGo`](crate::messages::SpellGo)'s own miss list carries): 1 MISS ·
-/// 2 RESIST · 3 DODGE · 4 PARRY ·
-/// 5 BLOCK · 6 EVADE · 7/8 IMMUNE · 9 DEFLECT · 10 ABSORB · 11 REFLECT.
+/// `SMSG_SPELLLOGMISS`, a cast's per-target miss list (`Server/Packets/Spell.cpp:68-86`). Each
+/// `u8` is a `SpellMissInfo` (`SpellDefines.h:160-174`): 1 miss, 2 resist, 3 dodge, 4 parry,
+/// 5 block, 6 evade, 7 and 8 immune, 9 deflect, 10 absorb, 11 reflect.
 #[derive(Debug, Clone, PartialEq)]
 pub struct SpellLogMiss {
     pub spell_id: u32,
@@ -275,17 +231,12 @@ pub struct SpellLogMiss {
     pub misses: Vec<(u64, u8)>,
 }
 
-/// Read `SMSG_SPELLLOGMISS`: spellId u32 · caster raw `u64` · useExtended u8 (vmangos always 0) ·
-/// count u32 · `count` entries of `{target raw u64, missInfo u8}`. When `useExtended != 0`, each
-/// entry additionally carries a trailing `2×f32` — read and dropped to keep the cursor aligned; no
-/// consumer needs it.
 pub(super) fn read_spell_log_miss(r: &mut impl Read) -> io::Result<SpellLogMiss> {
     let spell_id = read_u32_le(r)?;
     let caster = read_u64_le(r)?;
     let use_extended = read_u8(r)?;
     let count = read_u32_le(r)?;
-    // No server bound: vmangos never sends this opcode at all (its miss list rides
-    // `SMSG_SPELL_GO`), so 64 is a generous sane one.
+    // vmangos never sends this opcode (misses ride `SMSG_SPELL_GO`), so 64 is an arbitrary cap.
     let mut misses = Vec::with_capacity(capacity_hint(count, 64));
     for _ in 0..count {
         let target = read_u64_le(r)?;
@@ -303,18 +254,14 @@ pub(super) fn read_spell_log_miss(r: &mut impl Read) -> io::Result<SpellLogMiss>
     })
 }
 
-/// One decoded `SMSG_PARTYKILLLOG` — the killing blow, sent to the killer's party (vmangos
-/// `WorldPackets::Combat::PartyKillLog::AppendBodyTo`, `Server/Packets/Combat.cpp:52-56`).
-///
-/// It is the **only** source of the "You have slain %s!" / "%s is slain by %s!" pair; the plain
-/// "%s dies." line is not a packet at all — it rides the client's own unit-death reflex.
+/// `SMSG_PARTYKILLLOG`, the killing blow, sent to the killer's party (`Combat.cpp:52-56`): the
+/// only source of "You have slain %s!"; "%s dies." comes from the client's own death handling.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct PartyKillLog {
     pub killer: u64,
     pub victim: u64,
 }
 
-/// Read `SMSG_PARTYKILLLOG`: killer raw `u64` guid · victim raw `u64` guid.
 pub(super) fn read_party_kill_log(r: &mut impl Read) -> io::Result<PartyKillLog> {
     Ok(PartyKillLog {
         killer: read_u64_le(r)?,
@@ -322,15 +269,13 @@ pub(super) fn read_party_kill_log(r: &mut impl Read) -> io::Result<PartyKillLog>
     })
 }
 
-/// One decoded `SMSG_SPELLINSTAKILLLOG` — an instant kill (vmangos `Spell::EffectInstaKill`,
-/// `Spells/SpellEffects.cpp:274-279`; the packet exists only for `> 1.11.2` clients, which 5875 is).
+/// `SMSG_SPELLINSTAKILLLOG`, an instant kill (vmangos `Spells/SpellEffects.cpp:274-279`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SpellInstaKillLog {
     pub victim: u64,
     pub spell_id: u32,
 }
 
-/// Read `SMSG_SPELLINSTAKILLLOG`: victim raw `u64` guid · spellId u32.
 pub(super) fn read_spell_insta_kill_log(r: &mut impl Read) -> io::Result<SpellInstaKillLog> {
     Ok(SpellInstaKillLog {
         victim: read_u64_le(r)?,
@@ -338,12 +283,9 @@ pub(super) fn read_spell_insta_kill_log(r: &mut impl Read) -> io::Result<SpellIn
     })
 }
 
-/// One decoded `SMSG_PROCRESIST` **or** `SMSG_SPELLORDAMAGE_IMMUNE` — the two share a body byte for
-/// byte (vmangos `WorldPackets::Spell::ProcResist` / `SpellOrDamageImmune`,
-/// `Server/Packets/Spell.cpp:88-102`) and differ only in which sentence they word.
-///
-/// `log_format` is vmangos's `logFormat` (`0` default, `1` debug); the reference reads it as the
-/// "is periodic" flag that decides whether `CombatLogPeriodicSpells` gates the line.
+/// `SMSG_PROCRESIST` or `SMSG_SPELLORDAMAGE_IMMUNE`, which share one body
+/// (`Server/Packets/Spell.cpp:88-102`). The 1.12 client reads `log_format` as the "is periodic"
+/// flag that lets `CombatLogPeriodicSpells` gate the line.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SpellOutcomeLog {
     pub caster: u64,
@@ -352,8 +294,6 @@ pub struct SpellOutcomeLog {
     pub log_format: u8,
 }
 
-/// Read `SMSG_PROCRESIST` / `SMSG_SPELLORDAMAGE_IMMUNE`: caster raw `u64` · target raw `u64` ·
-/// spellId u32 · logFormat u8.
 pub(super) fn read_spell_outcome_log(r: &mut impl Read) -> io::Result<SpellOutcomeLog> {
     Ok(SpellOutcomeLog {
         caster: read_u64_le(r)?,
@@ -363,19 +303,16 @@ pub(super) fn read_spell_outcome_log(r: &mut impl Read) -> io::Result<SpellOutco
     })
 }
 
-/// One decoded `SMSG_SPELLDISPELLOG` — auras a dispel actually removed (vmangos
-/// `Spell::EffectDispel`, `Spells/SpellEffects.cpp:2524-2539`; the guid pair is **packed** on the
-/// `>= 1.12.1` branch our build takes).
+/// `SMSG_SPELLDISPELLOG`, the auras a dispel removed (vmangos `SpellEffects.cpp:2524-2539`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SpellDispelLog {
     /// The unit the auras were on.
     pub victim: u64,
-    /// The dispeller. The sentence never names them — `AURADISPEL*` words the bearer and the aura.
+    /// The dispeller; the `AURADISPEL*` line never names them.
     pub caster: u64,
     pub spell_ids: Vec<u32>,
 }
 
-/// Read `SMSG_SPELLDISPELLOG`: victim PackedGuid · caster PackedGuid · count u32 · `count` × u32.
 pub(super) fn read_spell_dispel_log(r: &mut impl Read) -> io::Result<SpellDispelLog> {
     let victim = read_packed_guid(r)?;
     let caster = read_packed_guid(r)?;
@@ -391,11 +328,8 @@ pub(super) fn read_spell_dispel_log(r: &mut impl Read) -> io::Result<SpellDispel
     })
 }
 
-/// One decoded `SMSG_DISPEL_FAILED` — auras a dispel tried and failed to remove (vmangos
-/// `Spell::EffectDispel`, `Spells/SpellEffects.cpp:2549-2555`).
-///
-/// **The list runs to the end of the packet** — vmangos writes no count, so the body's own length
-/// is the terminator. The reference reads it the same way (`0x628c20` loops to end of buffer).
+/// `SMSG_DISPEL_FAILED`, the auras a dispel failed to remove (`SpellEffects.cpp:2549-2555`). No
+/// count: the spell ids run to the end of the body, as the 1.12 client reads them (`0x628c20`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DispelFailed {
     pub caster: u64,
@@ -403,7 +337,6 @@ pub struct DispelFailed {
     pub spell_ids: Vec<u32>,
 }
 
-/// Read `SMSG_DISPEL_FAILED`: caster raw `u64` · victim raw `u64` · u32 spell ids to end of body.
 pub(super) fn read_dispel_failed(r: &mut impl Read) -> io::Result<DispelFailed> {
     let caster = read_u64_le(r)?;
     let victim = read_u64_le(r)?;
@@ -412,7 +345,7 @@ pub(super) fn read_dispel_failed(r: &mut impl Read) -> io::Result<DispelFailed>
         let mut b = [0u8; 4];
         match r.read_exact(&mut b) {
             Ok(()) => spell_ids.push(u32::from_le_bytes(b)),
-            // The body ended — the only terminator this packet has.
+            // The end of the body is the list's only terminator.
             Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => break,
             Err(e) => return Err(e),
         }
@@ -424,25 +357,19 @@ pub(super) fn read_dispel_failed(r: &mut impl Read) -> io::Result<DispelFailed>
     })
 }
 
-/// One decoded `SMSG_ENCHANTMENTLOG` — an enchant landing on, or fading from, an item (vmangos
-/// `WorldPackets::Item::EnchantmentLog::AppendBodyTo`, `Server/Packets/Item.cpp:235-242`;
-/// filled by `Player::SendEnchantmentLog`, `Objects/Player.cpp:12049-12072`).
-///
-/// **An empty `caster` means the enchant FADED**, not that the server forgot who cast it — that is
-/// vmangos's own comment on the field, and it is the two-way the reference switches on.
+/// `SMSG_ENCHANTMENTLOG`, an enchant landing on or fading from an item
+/// (`Server/Packets/Item.cpp:235-242`); a zero `caster` means it faded.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct EnchantmentLog {
     pub caster: u64,
     pub owner: u64,
     pub item_entry: u32,
     pub spell_id: u32,
-    /// vmangos `showAffiliation`: false on the copy sent to the item's owner, true on the broadcast
-    /// to everyone else. The reference lets it pick the msg-id selector on the ADD leg.
+    /// False on the owner's copy, true on everyone else's; the 1.12 client picks the
+    /// enchant-added message by it.
     pub show_affiliation: bool,
 }
 
-/// Read `SMSG_ENCHANTMENTLOG`: caster raw `u64` · owner raw `u64` · itemEntry u32 · spellId u32 ·
-/// showAffiliation u8.
 pub(super) fn read_enchantment_log(r: &mut impl Read) -> io::Result<EnchantmentLog> {
     Ok(EnchantmentLog {
         caster: read_u64_le(r)?,
@@ -453,17 +380,11 @@ pub(super) fn read_enchantment_log(r: &mut impl Read) -> io::Result<EnchantmentL
     })
 }
 
-/// One `SMSG_SPELLLOGEXECUTE` entry — a single (effect, target) row. The payload shape is decided
-/// by the **effect id**, exactly as vmangos's `Spell::SendLogExecute` switch writes it
-/// (`Spells/Spell.cpp:4694-4771`) and as the reference's own per-effect jump table reads it
-/// (`0x5e8074 jmp [edx*4+0x5e8430]`, byte remap `0x5e845c`).
+/// One `SMSG_SPELLLOGEXECUTE` row, shaped by its effect id as vmangos writes it
+/// (`Spells/Spell.cpp:4694-4771`) and the 1.12 client reads it (`0x5e8074`).
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum ExecuteLog {
-    /// Effect 8 `POWER_DRAIN`. **Field order VERIFIED at the client's bytes, not just the server's**:
-    /// the arm at `0x5e807b` reads guid → u32 → u32 → f32 and hands them to `0x62dbf0` →
-    /// `0x627930(…, spellId, powerType, amount, multiplier)` — where `0x62793c cmp edi,4` and
-    /// `0x62795d call 0x6278f0` (GetPowerTypeNoun) identify the SECOND u32 as the power type. So
-    /// the wire is (amount, power), which is what vmangos writes, and the two agree.
+    /// Effect 8 `POWER_DRAIN`: amount, then power (the 1.12 client, `0x5e807b` and `0x62793c`).
     PowerDrain {
         target: u64,
         amount: u32,
@@ -482,35 +403,27 @@ pub enum ExecuteLog {
         amount: u32,
         power: u32,
     },
-    /// Effect 19 `ADD_EXTRA_ATTACKS` — "You gain %d extra attacks through %s."
+    /// Effect 19 `ADD_EXTRA_ATTACKS`: "You gain %d extra attacks through %s."
     ExtraAttacks { target: u64, count: u32 },
-    /// Effect 24 `CREATE_ITEM` — the tradeskill line. **No target guid**: the item entry is the
-    /// whole payload.
+    /// Effect 24 `CREATE_ITEM`, the tradeskill line: no target guid, only the item entry.
     CreateItem { item_entry: u32 },
-    /// Effect 68 `INTERRUPT_CAST` — the interrupted target and the spell that was interrupted.
+    /// Effect 68 `INTERRUPT_CAST`: the interrupted target and spell.
     InterruptCast { target: u64, spell_id: u32 },
-    /// Effect 101 `FEED_PET` — like [`Self::CreateItem`], an item entry alone.
+    /// Effect 101 `FEED_PET`: an item entry alone.
     FeedPet { item_entry: u32 },
-    /// Effect 111 `DURABILITY_DAMAGE`. Both fields are **signed**: `-1`/`-1` is the "all items"
-    /// form, which the reference words with its own `SPELLDURABILITYDAMAGEALL*` family. vmangos
-    /// calls the second field `unk`; the reference calls it the item SLOT and tests it with the
-    /// entry for exactly that `-1` pair.
+    /// Effect 111 `DURABILITY_DAMAGE`, both fields signed; `-1`, `-1` is the all-items form
+    /// (`SPELLDURABILITYDAMAGEALL*`). The 1.12 client reads vmangos's `unk` as the item slot.
     DurabilityDamage {
         target: u64,
         item_entry: i32,
         slot: i32,
     },
-    /// Every other effect vmangos logs — a bare target guid. The effect id is kept because it is
-    /// what the reference's formatter switch keys on (open lock, dismiss pet, summon, dispel …).
+    /// Every other effect vmangos logs: a bare target guid.
     Target { target: u64 },
 }
 
-/// One decoded `SMSG_SPELLLOGEXECUTE` — "this cast's effects did these things" (vmangos
-/// `Spell::SendLogExecute`, `Spells/Spell.cpp:4662-4778`).
-///
-/// The packet is a *list of lists*: one group per spell effect that logged anything, each group a
-/// run of per-target rows. Groups keep their effect id because the whole formatter choice hangs off
-/// it — one packet can carry a tradeskill create, an interrupt and a power drain at once.
+/// `SMSG_SPELLLOGEXECUTE`, what a cast's effects did (`Spells/Spell.cpp:4662-4778`): one group of
+/// rows per logging effect, keyed by the effect id that picks the combat-log line.
 #[derive(Debug, Clone, PartialEq)]
 pub struct SpellLogExecute {
     pub caster: u64,
@@ -530,13 +443,7 @@ const EFFECT_INTERRUPT_CAST: u32 = 68;
 const EFFECT_FEED_PET: u32 = 101;
 const EFFECT_DURABILITY_DAMAGE: u32 = 111;
 
-/// Read `SMSG_SPELLLOGEXECUTE`: caster PackedGuid · spellId u32 · effectCount u32 · per group
-/// `{effect u32, count u32, count × payload}` — the payload per [`ExecuteLog`].
-///
-/// An effect id outside the set vmangos logs cannot be skipped without desyncing the body (the row
-/// width is not on the wire), so it errors rather than guessing. vmangos never sends one: its own
-/// switch `return`s before `SendMessageToSet` for anything it has no case for, so an unlisted
-/// effect means no packet at all rather than a truncated one.
+/// Read `SMSG_SPELLLOGEXECUTE`; an unknown effect errors, as its row width is not on the wire.
 pub(super) fn read_spell_log_execute(r: &mut impl Read) -> io::Result<SpellLogExecute> {
     let caster = read_packed_guid(r)?;
     let spell_id = read_u32_le(r)?;
@@ -583,8 +490,6 @@ pub(super) fn read_spell_log_execute(r: &mut impl Read) -> io::Result<SpellLogEx
                     item_entry: read_i32_le(r)?,
                     slot: read_i32_le(r)?,
                 },
-                // The long tail of vmangos's switch: instakill, dispel, threat, summon, open lock,
-                // dismiss pet … all one guid wide.
                 _ if rows_are_guid_only(effect) => ExecuteLog::Target {
                     target: read_u64_le(r)?,
                 },
@@ -605,9 +510,7 @@ pub(super) fn read_spell_log_execute(r: &mut impl Read) -> io::Result<SpellLogEx
     })
 }
 
-/// The effects vmangos logs as a bare target guid — its `SendLogExecute` switch's long
-/// fall-through case list (`Spells/Spell.cpp:4735-4770`), each name resolved against
-/// `Spells/SpellDefines.h`'s `SpellEffects` enum rather than transcribed from memory.
+/// The effects vmangos logs as a bare target guid (`Spells/Spell.cpp:4735-4770`).
 fn rows_are_guid_only(effect: u32) -> bool {
     matches!(
         effect,
diff --git a/crates/benilla-protocol/src/messages/death.rs b/crates/benilla-protocol/src/messages/death.rs
index 24a0e810..169edfe4 100644
--- a/crates/benilla-protocol/src/messages/death.rs
+++ b/crates/benilla-protocol/src/messages/death.rs
@@ -1,38 +1,23 @@
-//! The death-arc messages (decision 0308): release/repop, the corpse query, the reclaim delay +
-//! reclaim, the spirit healer, and resurrect requests. Every body shape below is VERIFIED against
-//! vmangos source (file:line cites per item); the goldens mirror the server's own packet builds.
-//!
-//! Not modelled here (known siblings): `SMSG_DURABILITY_DAMAGE_DEATH` (0x2BD — an EMPTY body the
-//! server sends with the 10% natural-death durability loss; the real client shows a durability
-//! warning — a later polish slice), and the BG-only death family (area spirit healers, the forced
-//! BG repop aura 2584 — 0308 defers battlegrounds).
+//! Death and resurrection: the corpse query, corpse reclaim, spirit healers, resurrect offers.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_f32_le, read_i32_le, read_u32_le, read_u64_le, read_u8};
 
-/// `MSG_CORPSE_QUERY`'s answer (opcode `0x216`/534 — VERIFIED vmangos `Opcodes_1_12_1.h:535`; our
-/// request is the same opcode with an EMPTY body, `NullClientPacket`). VERIFIED
-/// `QueryHandler.cpp:258-304` (`HandleCorpseQueryOpcode`): not-found = the lone `u8(0)`; found =
-/// `u8(1), i32 mapid, f32 x, f32 y, f32 z, u32 corpsemapid`.
-///
-/// The two maps differ deliberately: `display_map`/`position` are **where to walk toward** — for a
-/// corpse inside a dungeon they are rewritten to the dungeon's `ghostEntranceMap` + entrance
-/// coordinates — while `corpse_map` is always the corpse's real map, untouched. The server also
-/// pushes an UNPROMPTED not-found (`u8(0)`) when a lootable corpse converts to bones
-/// (`Map.cpp:3624-3629`), so a not-found mid-session means "drop the marker", not "query failed".
+/// `MSG_CORPSE_QUERY`'s answer (`QueryHandler.cpp:258-304`), a lone `u8(0)` when not found; the
+/// request is the same opcode, empty. The server also sends an unprompted not-found when the
+/// corpse turns to bones (`Map.cpp:3624-3629`), which means "drop the marker".
 #[derive(Debug, Clone, PartialEq)]
 pub struct CorpseLocation {
     pub found: bool,
-    /// The map to show/route toward (dungeon-entrance-adjusted). `0` when `!found`.
+    /// The map to walk toward, rewritten to the entrance's for a corpse inside a dungeon.
     pub display_map: i32,
-    /// Raw WoW coordinates of the corpse (or the dungeon entrance). Zeroed when `!found`.
+    /// Raw WoW coordinates of the corpse, or of the dungeon entrance.
     pub position: [f32; 3],
-    /// The corpse's REAL map id, never adjusted. `0` when `!found`.
+    /// The corpse's real map id, never adjusted.
     pub corpse_map: u32,
 }
 
-/// Read `MSG_CORPSE_QUERY`'s answer — both shapes (see [`CorpseLocation`]).
 pub(super) fn read_corpse_query_response(r: &mut &[u8]) -> io::Result<CorpseLocation> {
     let found = read_u8(r)? != 0;
     if !found {
@@ -54,26 +39,16 @@ pub(super) fn read_corpse_query_response(r: &mut &[u8]) -> io::Result<CorpseLoca
     })
 }
 
-/// Read `SMSG_CORPSE_RECLAIM_DELAY` (opcode `0x269`/617 — VERIFIED `Opcodes_1_12_1.h:618`): one
-/// `u32`, the delay in **milliseconds** before the corpse can be reclaimed (VERIFIED
-/// `Server/Packets/Misc.cpp:653-656` — `buffer << delayMs`). Sent at release
-/// (`Player::BuildPlayerRepop`, `Player.cpp:4677`) and at login while dead
-/// (`CharacterHandler.cpp:571-572`) — never at the death itself. The value is 30 s base,
-/// 60/120 s for repeated deaths within 5-minute steps (`copseReclaimDelay[]`, `Player.cpp:106`).
+/// Read `SMSG_CORPSE_RECLAIM_DELAY`: the ms until the corpse can be reclaimed
+/// (`Misc.cpp:653-656`), sent at release and at login while dead, never at death itself. It is
+/// 30 s, or 60 or 120 s after repeated deaths (`Player.cpp:106`).
 pub(super) fn read_corpse_reclaim_delay(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
 
-/// A resurrection offer (`SMSG_RESURRECT_REQUEST`, opcode `0x15B`/347 — VERIFIED
-/// `Opcodes_1_12_1.h:348`). VERIFIED `Spell.cpp:5024-5044` (`Spell::SendResurrectRequest`):
-/// `u64 caster, u32 nameLen (strlen+1), cstring name, u8 sickness, u8 hasResTimer`.
-///
-/// `name` is **empty when the caster is a player** (the client resolves the offerer's display name
-/// from the guid through the ordinary name-query cache); it carries the localized creature name for
-/// an NPC caster. `sickness` warns the accept applies resurrection sickness; `has_timer` says the
-/// client should still honor the `SMSG_CORPSE_RECLAIM_DELAY` gate (inverted server-side from
-/// `SPELL_ATTR_EX3_NO_RES_TIMER`). The reference UI picks its popup off exactly these two bits
-/// (RESURRECT / RESURRECT_NO_SICKNESS / RESURRECT_NO_TIMER — UIParent.lua's RESURRECT_REQUEST arm).
+/// `SMSG_RESURRECT_REQUEST`, a resurrection offer (`Spell.cpp:5024-5044`). `sickness` warns the
+/// accept brings resurrection sickness, `has_timer` keeps the reclaim-delay gate, and the stock
+/// popup picks its variant by the two.
 #[derive(Debug, Clone, PartialEq)]
 pub struct ResurrectRequestBody {
     pub caster: u64,
@@ -83,9 +58,7 @@ pub struct ResurrectRequestBody {
     pub has_timer: bool,
 }
 
-/// Read `SMSG_RESURRECT_REQUEST` (see [`ResurrectRequestBody`]). The `u32` length prefix duplicates
-/// the C-string's own length (strlen+1) — read and cross-checked loosely (the cstring terminator is
-/// authoritative; vmangos always writes both consistently).
+/// Read `SMSG_RESURRECT_REQUEST`; the name's `u32` length (strlen + 1) is skipped for its NUL.
 pub(super) fn read_resurrect_request(r: &mut &[u8]) -> io::Result<ResurrectRequestBody> {
     let caster = read_u64_le(r)?;
     let _name_len = read_u32_le(r)?;
@@ -100,40 +73,27 @@ pub(super) fn read_resurrect_request(r: &mut &[u8]) -> io::Result<ResurrectReque
     })
 }
 
-/// Read `SMSG_SPIRIT_HEALER_CONFIRM` (opcode `0x222`/546 — VERIFIED `Opcodes_1_12_1.h:547`): one
-/// full `u64`, the spirit-healer NPC's guid. VERIFIED `SpellEffects.cpp:818-831` — vmangos sends it
-/// from the gossip-menu spirit-healer option (the NPC casts 17251 "Spirit Healer Res" whose dummy
-/// effect builds this packet), NOT from `CMSG_SPIRIT_HEALER_ACTIVATE`. The client answers the
-/// eventual XP_LOSS confirm-accept with [`spirit_healer_activate`] carrying this guid.
+/// Read `SMSG_SPIRIT_HEALER_CONFIRM`: the spirit healer's full guid, sent from its gossip option
+/// through spell 17251 (`SpellEffects.cpp:818-831`); accepting sends [`spirit_healer_activate`].
 pub(super) fn read_spirit_healer_confirm(r: &mut &[u8]) -> io::Result<u64> {
     read_u64_le(r)
 }
 
-/// Body of `CMSG_RECLAIM_CORPSE` (opcode `0x1D2`/466 — VERIFIED `Opcodes_1_12_1.h:467`): one full
-/// `u64` guid (VERIFIED `Server/Packets/Misc.cpp:122-125` — `recv_data >> guid`). The server
-/// resolves the corpse through the player itself and never checks this guid's content, but the
-/// real client sends its corpse's guid — we do the same. Server gates (`MiscHandler.cpp:573-603`):
-/// dead + `PLAYER_FLAGS_GHOST` + corpse exists + the reclaim delay elapsed + within
-/// `CORPSE_RECLAIM_RADIUS` (39 yd, `Corpse.h:40`) — success is `ResurrectPlayer(0.5)` + bones.
+/// `CMSG_RECLAIM_CORPSE` body: the corpse's full guid, as the 1.12 client sends, though the server
+/// ignores it. It requires a ghost, the delay elapsed and 39 yd range (`MiscHandler.cpp:573-603`).
 pub fn reclaim_corpse(corpse_guid: u64) -> Vec<u8> {
     corpse_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_SPIRIT_HEALER_ACTIVATE` (opcode `0x21C`/540 — VERIFIED `Opcodes_1_12_1.h:541`):
-/// one full `u64`, the spirit healer's guid (VERIFIED `Server/Packets/Npc.cpp:40-43`). Server
-/// gates (`NPCHandler.cpp:416-428` → `CanInteractWithNPC` with `UNIT_NPC_FLAG_SPIRITHEALER`
-/// `0x20`): 5-yd interaction distance, ghost-visible NPC. Effect (`SendSpiritResurrect`,
-/// `NPCHandler.cpp:430-477`): res at 50%, 25% durability loss on ALL items, resurrection sickness
-/// 15007 at level ≥ 11 (scaling duration to 10 min at 20+), corpse → bones, teleport to the
-/// corpse-nearest graveyard when it differs from the current one.
+/// `CMSG_SPIRIT_HEALER_ACTIVATE` body: the healer's full guid (`Npc.cpp:40-43`), within 5 yd. The
+/// server resurrects at 50% with 25% durability loss and, from level 11, sickness
+/// (`NPCHandler.cpp:430-477`).
 pub fn spirit_healer_activate(npc: u64) -> Vec<u8> {
     npc.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_RESURRECT_RESPONSE` (opcode `0x15C`/348 — VERIFIED `Opcodes_1_12_1.h:349`): the
-/// offerer's `u64` guid + `u8 accept` (VERIFIED `Server/Packets/Misc.cpp:132-136`). A decline just
-/// clears the server-side offer; an accept teleports us to the caster (cross-instance redirected to
-/// the entrance) and resurrects with the offer's stored health/mana (`Player.cpp:20188-20244`).
+/// `CMSG_RESURRECT_RESPONSE` body: the offerer's guid and `u8 accept` (`Misc.cpp:132-136`); an
+/// accept moves us to the caster and resurrects us (`Player.cpp:20188-20244`).
 pub fn resurrect_response(caster: u64, accept: bool) -> Vec<u8> {
     let mut body = Vec::with_capacity(9);
     body.extend_from_slice(&caster.to_le_bytes());
@@ -145,9 +105,7 @@ pub fn resurrect_response(caster: u64, accept: bool) -> Vec<u8> {
 mod tests {
     use super::*;
 
-    /// The found shape, byte-exact against `HandleCorpseQueryOpcode`'s build (`QueryHandler.cpp:
-    /// 296-303`): `u8(1) << i32(mapid) << f32(x) << f32(y) << f32(z) << u32(corpsemapid)` — here a
-    /// corpse on Eastern Kingdoms (0) at Northshire-ish coords, no entrance adjustment.
+    /// Built as `HandleCorpseQueryOpcode` builds it (`QueryHandler.cpp:296-303`).
     #[test]
     fn corpse_query_found_golden() {
         let mut body = vec![1u8];
@@ -170,8 +128,7 @@ mod tests {
         );
     }
 
-    /// The not-found shape is the lone `u8(0)` (`QueryHandler.cpp:262-267`) — also pushed
-    /// unprompted at bones-conversion (`Map.cpp:3624-3629`).
+    /// The lone `u8(0)` of `QueryHandler.cpp:262-267`.
     #[test]
     fn corpse_query_not_found_golden() {
         let body = [0u8];
@@ -182,8 +139,7 @@ mod tests {
         assert_eq!(loc.corpse_map, 0);
     }
 
-    /// A dungeon corpse: `mapid`/coords rewritten to the ghost entrance, `corpsemapid` kept real
-    /// (`QueryHandler.cpp:276-292`) — the two-map split the marker consumer relies on.
+    /// A dungeon corpse's entrance map and real map (`QueryHandler.cpp:276-292`).
     #[test]
     fn corpse_query_dungeon_entrance_split() {
         let mut body = vec![1u8];
@@ -191,14 +147,14 @@ mod tests {
         body.extend_from_slice(&(-11209.6f32).to_le_bytes()); // Deadmines entrance-ish
         body.extend_from_slice(&1666.54f32.to_le_bytes());
         body.extend_from_slice(&25.0f32.to_le_bytes());
-        body.extend_from_slice(&36u32.to_le_bytes()); // the corpse's REAL map: Deadmines
+        body.extend_from_slice(&36u32.to_le_bytes()); // the corpse's real map: Deadmines
         let mut r = body.as_slice();
         let loc = read_corpse_query_response(&mut r).unwrap();
         assert_eq!(loc.display_map, 0);
         assert_eq!(loc.corpse_map, 36);
     }
 
-    /// `SMSG_CORPSE_RECLAIM_DELAY` is one `u32` of milliseconds (`Misc.cpp:653-656`; 30 s base).
+    /// One `u32` of ms (`Misc.cpp:653-656`); 30 s is the base delay.
     #[test]
     fn corpse_reclaim_delay_golden() {
         let body = 30_000u32.to_le_bytes();
@@ -207,9 +163,7 @@ mod tests {
         assert!(r.is_empty());
     }
 
-    /// A player-caster offer, byte-exact against `Spell::SendResurrectRequest` (`Spell.cpp:
-    /// 5024-5044`): empty name (len prefix 1 = just the terminator), sickness 0 (a player res
-    /// spell), hasResTimer 1 (no `SPELL_ATTR_EX3_NO_RES_TIMER`).
+    /// Built as `Spell::SendResurrectRequest` builds a player's offer (`Spell.cpp:5024-5044`).
     #[test]
     fn resurrect_request_player_caster_golden() {
         let mut body = Vec::new();
@@ -232,8 +186,7 @@ mod tests {
         );
     }
 
-    /// An NPC-caster offer carries the creature's localized name and (for a spirit-healer-style
-    /// caster) the sickness warning bit.
+    /// A spirit healer's offer as `Spell::SendResurrectRequest` builds it: named, with sickness.
     #[test]
     fn resurrect_request_npc_caster_golden() {
         let name = b"Spirit Healer";
@@ -243,12 +196,19 @@ mod tests {
         body.extend_from_slice(name);
         body.push(0);
         body.push(1); // sickness = true
-        body.push(1);
+        body.push(1); // hasResTimer = true
         let mut r = body.as_slice();
         let req = read_resurrect_request(&mut r).unwrap();
         assert!(r.is_empty());
-        assert_eq!(req.name, "Spirit Healer");
-        assert!(req.sickness);
+        assert_eq!(
+            req,
+            ResurrectRequestBody {
+                caster: 0xF130_0FBE_0000_2AB3,
+                name: "Spirit Healer".into(),
+                sickness: true,
+                has_timer: true,
+            }
+        );
     }
 
     /// `SMSG_SPIRIT_HEALER_CONFIRM` is one full guid (`SpellEffects.cpp:825-829`).
@@ -263,8 +223,6 @@ mod tests {
         assert!(r.is_empty());
     }
 
-    /// The three client bodies: full little-endian guids (+ the accept byte), matching the server
-    /// readers quoted on each builder.
     #[test]
     fn client_bodies_are_full_guids() {
         assert_eq!(
@@ -281,19 +239,21 @@ mod tests {
         let mut expect = 0x2Au64.to_le_bytes().to_vec();
         expect.push(0);
         assert_eq!(resurrect_response(0x2A, false), expect);
+        assert_eq!(
+            area_spirit_healer(0xF130_0033_3C00_0010),
+            0xF130_0033_3C00_0010u64.to_le_bytes().to_vec()
+        );
     }
 }
 
-/// `SMSG_AREA_SPIRIT_HEALER_TIME` (VERIFIED, wow-re `staticpopup-dialog-bindings.md` §6, arm
-/// `0x48fa29`): the battleground spirit healer's guid and the milliseconds to its next
-/// resurrection wave. Decision 1963.
+/// `SMSG_AREA_SPIRIT_HEALER_TIME`: a battleground spirit healer's guid and the ms until its next
+/// resurrection wave (client `0x48fa29`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct AreaSpiritHealerTime {
     pub healer: u64,
     pub ms: u32,
 }
 
-/// Parse `SMSG_AREA_SPIRIT_HEALER_TIME`: `u64 guid`, `u32 ms`.
 pub(super) fn read_area_spirit_healer_time(
     r: &mut impl std::io::Read,
 ) -> std::io::Result<AreaSpiritHealerTime> {
@@ -303,8 +263,8 @@ pub(super) fn read_area_spirit_healer_time(
     })
 }
 
-/// Body of `CMSG_AREA_SPIRIT_HEALER_QUERY` / `CMSG_AREA_SPIRIT_HEALER_QUEUE` (VERIFIED, §6): one
-/// `u64`, the healer's guid — the query when the client adopts a healer, the queue on Accept.
+/// `CMSG_AREA_SPIRIT_HEALER_QUERY` or `_QUEUE` body: the healer's guid; the client queries when it
+/// adopts a healer and queues on accept.
 pub fn area_spirit_healer(healer: u64) -> Vec<u8> {
     healer.to_le_bytes().to_vec()
 }
diff --git a/crates/benilla-protocol/src/messages/duel.rs b/crates/benilla-protocol/src/messages/duel.rs
index c37a63bf..ffbec623 100644
--- a/crates/benilla-protocol/src/messages/duel.rs
+++ b/crates/benilla-protocol/src/messages/duel.rs
@@ -1,43 +1,18 @@
-//! The duel family — challenge, countdown, bounds, completion, and the winner broadcast
-//! (opcodes 359-365 + 695; decision 0633).
-//!
-//! Duels are the one family where **both ends are pinned at the bytes**. The server side is
-//! vmangos `Server/Packets/Duel.{h,cpp}` (every `ReadFromWorldPacket` / `AppendBodyTo`),
-//! `Handlers/DuelHandler.cpp`, `Objects/Player.cpp` (`DuelComplete`, `CheckDuelDistance`,
-//! `UpdateDuelFlag`, `SendDuelCountdown`) and `Spells/SpellEffects.cpp` (`EffectDuel`). The
-//! client side is WoW.exe's own duel TU — `E:\build\buildWoW\WoW\Source\Ui\DuelInfo.cpp`
-//! (`__FILE__` @`0x84a020`), handlers registered at `0x4d4710`:
-//!
-//! | opcode | handler | what it reads |
-//! |---|---|---|
-//! | `SMSG_DUEL_REQUESTED` 0x167 | `0x4d49d0` | two full guids: arbiter, then challenger |
-//! | `SMSG_DUEL_OUTOFBOUNDS` 0x168 | `0x4d4aa0` | nothing |
-//! | `SMSG_DUEL_INBOUNDS` 0x169 | `0x4d4ac0` | nothing |
-//! | `SMSG_DUEL_COMPLETE` 0x16a | `0x4d4b20` | one `u8` |
-//! | `SMSG_DUEL_WINNER` 0x16b | `0x4d4ba0` | `u8` + two cstrings |
-//! | `SMSG_DUEL_COUNTDOWN` 0x2b7 | `0x4d4ae0` | one `u32`, **milliseconds** |
-//!
-//! and the two sends, `AcceptDuel` `0x4d4830` / `CancelDuel` `0x4d48b0`, which each build the
-//! opcode and push the **stored arbiter guid** (`[0xb73240]`, saved by the request handler) — the
-//! body vmangos ignores, so only the binary could settle it.
+//! The duel family: challenge, countdown, bounds, completion and the winner line. The 1.12
+//! client's handlers are registered at `0x4d4710`; the two bounds messages have empty bodies.
 
 use std::io::{self, Read};
 
 use crate::wire::{read_cstring, read_u32_le, read_u64_le, read_u8};
 
-/// `SMSG_DUEL_REQUESTED` — a duel challenge, sent to **both** parties (VERIFIED vmangos
-/// `SpellEffects.cpp` `EffectDuel`: `data << pGameObj->GetObjectGuid(); data <<
-/// caster->GetObjectGuid();` then `SendPacket` to caster *and* target).
+/// `SMSG_DUEL_REQUESTED`, a duel challenge sent to both parties (vmangos `EffectDuel`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct DuelRequested {
-    /// The **duel-flag GameObject** the effect spawned midway between the two players (`Duel
-    /// Flag`, entry 21680, type 16 `DUEL_ARBITER`). It is both the out-of-bounds anchor and the
-    /// identity of the duel: it lands in each duellist's `PLAYER_DUEL_ARBITER` descriptor field,
-    /// and it is the guid the client echoes back on accept/cancel.
+    /// The duel flag game object (entry 21680) between the players: the bounds anchor, the
+    /// `PLAYER_DUEL_ARBITER` value, and the guid echoed on accept and cancel.
     pub arbiter: u64,
-    /// Who cast the challenge. The client compares this against its own guid: equal means *we*
-    /// challenged (show "You have requested a duel." and auto-accept), otherwise we are the one
-    /// being challenged (`0x4d49d0`).
+    /// Who challenged; when it is us, the 1.12 client shows "You have requested a duel." and
+    /// auto-accepts (`0x4d49d0`).
     pub challenger: u64,
 }
 
@@ -49,28 +24,21 @@ pub fn read_duel_requested(r: &mut impl Read) -> io::Result<DuelRequested> {
     })
 }
 
-/// Read `SMSG_DUEL_COMPLETE`'s single `u8` and return it as vmangos's `started` flag (VERIFIED
-/// `Player::DuelComplete`: `packet->started = (type != DUEL_INTERRUPTED)`).
-///
-/// `false` — the duel ended **before it began** (declined, cancelled during the countdown, one
-/// side logged out or was interrupted). That is exactly the case the client answers with the
-/// `ERR_DUEL_CANCELLED` line (`0x4d4b20`: `test al,al; jne` past `DisplayError(0x136)`).
+/// Read `SMSG_DUEL_COMPLETE`'s `started` flag; false means the duel ended before it began, which
+/// the 1.12 client reports as `ERR_DUEL_CANCELLED` (`0x4d4b20`).
 pub fn read_duel_complete(r: &mut impl Read) -> io::Result<bool> {
     Ok(read_u8(r)? != 0)
 }
 
-/// `SMSG_DUEL_WINNER` — the outcome line, broadcast to everyone around the loser (VERIFIED
-/// `Player::DuelComplete`'s `SendObjectMessageToSet`, so bystanders read it too).
+/// `SMSG_DUEL_WINNER`, the outcome line, broadcast around the loser (`Player::DuelComplete`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DuelWinner {
-    /// `false` = knocked out (`DUEL_WINNER_KNOCKOUT`, "%1$s has defeated %2$s in a duel"),
-    /// `true` = the loser fled or forfeited (`DUEL_WINNER_RETREAT`, "%2$s has fled from %1$s in
-    /// a duel"). vmangos writes `fled = (type != DUEL_WON)`; the client picks the template on
-    /// `test al,al` at `0x4d4bd9`.
+    /// True when the loser fled or forfeited (`DUEL_WINNER_RETREAT`), false for a knockout
+    /// (`DUEL_WINNER_KNOCKOUT`); the 1.12 client picks the line by it (`0x4d4bd9`).
     pub fled: bool,
-    /// Winner's name (`%1$s`). The client reads it into a 0x30-byte buffer.
+    /// The winner's name, `%1$s`.
     pub winner: String,
-    /// Loser's name (`%2$s`), same buffer size.
+    /// The loser's name, `%2$s`.
     pub loser: String,
 }
 
@@ -83,33 +51,20 @@ pub fn read_duel_winner(r: &mut impl Read) -> io::Result<DuelWinner> {
     })
 }
 
-/// Read `SMSG_DUEL_COUNTDOWN` and return **seconds**.
-///
-/// The wire carries milliseconds (vmangos `HandleDuelAcceptedOpcode` sends a literal `3000`), and
-/// the client divides by 1000 before using it as a tick count — `0x4d4aef: mov eax,0x10624dd3;
-/// mul [countdown]; shr edx,0x6` is the compiler's reciprocal for `/1000`. The truncation is the
-/// client's, so it is ours: a hypothetical 3500 ms counts down from 3, not 4.
+/// Read `SMSG_DUEL_COUNTDOWN` as whole seconds: the wire carries ms (vmangos sends 3000) and the
+/// 1.12 client truncates them to seconds (`0x4d4aef`).
 pub fn read_duel_countdown(r: &mut impl Read) -> io::Result<u32> {
     Ok(read_u32_le(r)? / 1000)
 }
 
-/// Body of `CMSG_DUEL_ACCEPTED` — the duel-arbiter guid (VERIFIED WoW.exe `AcceptDuel 0x4d4830`:
-/// builds opcode `0x16c`, then `PutInt64([0xb73240])`, the guid the request handler stored).
-///
-/// vmangos reads the guid into `DuelAccepted::playerGuid` and never looks at it
-/// (`HandleDuelAcceptedOpcode` keys off `m_duel` alone) — the binary is the only authority for
-/// what actually goes on the wire, which is why we read it there rather than guessing zero.
+/// `CMSG_DUEL_ACCEPTED` body: the arbiter guid from the request, as the 1.12 client sends it
+/// (`0x4d4830`); vmangos ignores it.
 pub fn duel_accepted(arbiter: u64) -> Vec<u8> {
     arbiter.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_DUEL_CANCELLED` — the same arbiter guid (VERIFIED WoW.exe `CancelDuel 0x4d48b0`,
-/// identical to [`duel_accepted`] but for opcode `0x16d`).
-///
-/// One opcode covers three player intents, disambiguated server-side by duel state
-/// (`HandleDuelCancelledOpcode`): declining the popup, cancelling during the countdown
-/// (`DUEL_INTERRUPTED`), and `/forfeit` **after** the duel has started — which makes the sender
-/// beg (spell 7267) and hands the win to the opponent.
+/// `CMSG_DUEL_CANCELLED` body: the arbiter guid (`0x4d48b0`). The server reads it by duel state as
+/// a decline, a countdown cancel, or once started a forfeit that hands the opponent the win.
 pub fn duel_cancelled(arbiter: u64) -> Vec<u8> {
     arbiter.to_le_bytes().to_vec()
 }
@@ -118,7 +73,6 @@ pub fn duel_cancelled(arbiter: u64) -> Vec<u8> {
 mod tests {
     use super::*;
 
-    /// `SMSG_DUEL_REQUESTED`: arbiter then challenger, both full 8-byte little-endian guids.
     #[test]
     fn duel_requested_is_arbiter_then_challenger() {
         let body = [
@@ -134,14 +88,12 @@ mod tests {
         );
     }
 
-    /// `SMSG_DUEL_COMPLETE`'s `started` byte: 0 = interrupted before the duel began.
     #[test]
     fn duel_complete_started_byte() {
         assert!(!read_duel_complete(&mut &[0u8][..]).unwrap());
         assert!(read_duel_complete(&mut &[1u8][..]).unwrap());
     }
 
-    /// `SMSG_DUEL_WINNER`: flag, winner cstring, loser cstring.
     #[test]
     fn duel_winner_flag_then_two_names() {
         let mut body = vec![1u8];
@@ -157,7 +109,6 @@ mod tests {
         );
     }
 
-    /// `SMSG_DUEL_COUNTDOWN` is milliseconds on the wire; the client's `/1000` truncates.
     #[test]
     fn duel_countdown_is_milliseconds_truncated_to_seconds() {
         assert_eq!(
@@ -174,8 +125,7 @@ mod tests {
         );
     }
 
-    /// Both client sends are the bare arbiter guid — byte-for-byte what `0x4d4830`/`0x4d48b0`
-    /// push.
+    /// The bytes `0x4d4830` and `0x4d48b0` push.
     #[test]
     fn accept_and_cancel_carry_the_arbiter_guid() {
         let guid = 0x0000_00F1_DEAD_BEEFu64;
diff --git a/crates/benilla-protocol/src/messages/gameobject.rs b/crates/benilla-protocol/src/messages/gameobject.rs
index c4f90300..3f06eaa4 100644
--- a/crates/benilla-protocol/src/messages/gameobject.rs
+++ b/crates/benilla-protocol/src/messages/gameobject.rs
@@ -1,31 +1,17 @@
-//! GameObject-interaction messages (decision 0236). The player-facing verb for every usable world
-//! GameObject — a chest, a door, a quest object, a lever — is the single `CMSG_GAMEOBJ_USE`; the
-//! server fans it out by GO type and answers on the systems we already have (the loot window for a
-//! chest, the gossip/quest windows for a questgiver GO, a `GAMEOBJECT_STATE` flip for a door). This
-//! module also carries the ask-once `CMSG_GAMEOBJECT_QUERY` template lookup (`entry + guid` →
-//! `SMSG_GAMEOBJECT_QUERY_RESPONSE`'s type/display/name/`data[24]` head) — the GO twin of
-//! `CMSG_CREATURE_QUERY`; it grows further as the arc lands its later phases.
+//! Game object messages: `CMSG_GAMEOBJ_USE`, the one verb for every usable object, which the
+//! server answers through loot, gossip or state; the template query; and one-shot animations.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_i32_le, read_u32_le, read_u64_le};
 
-/// Body of `CMSG_GAMEOBJ_USE` (opcode `0xB1`/177 — VERIFIED vmangos
-/// `Server/Protocol/Opcodes_1_12_1.h`): one full `u64` guid, the GameObject to use. Read server-side
-/// by `WorldSession::HandleGameObjectUseOpcode` (`Handlers/SpellHandler.cpp`), which gates on
-/// spawned · not GENERIC(5) · not `GO_FLAG_NO_INTERACT` · interact distance · `PlayerCanUse`, then
-/// runs `GameObject::Use`. The wire shape is identical to `CMSG_LOOT` — a bare little-endian guid —
-/// but the two are **not** interchangeable: `HandleLootOpcode` rejects a GameObject guid outright
-/// (anticheat), so a chest opens its loot through *this* opcode (→ server `SendLoot` →
-/// `SMSG_LOOT_RESPONSE`), never through `CMSG_LOOT`.
+/// `CMSG_GAMEOBJ_USE` body: the object's full guid (`Handlers/SpellHandler.cpp`). A chest's loot
+/// opens through this, never `CMSG_LOOT`, which rejects a game object guid.
 pub fn gameobj_use(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// Body of a `CMSG_GAMEOBJECT_QUERY` (opcode `0x005E`/94 — VERIFIED vmangos
-/// `Server/Protocol/Opcodes_1_12_1.h`): the template `entry` + the asking guid (VERIFIED vmangos
-/// `QueryGameObject::ReadFromWorldPacket` — `u32 entryID` then a full `u64` guid), identical shape to
-/// [`super::creature_query`].
+/// `CMSG_GAMEOBJECT_QUERY` body: the template entry, then a full guid (vmangos `QueryGameObject`).
 pub fn gameobject_query(entry: u32, guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&entry.to_le_bytes());
@@ -33,12 +19,8 @@ pub fn gameobject_query(entry: u32, guid: u64) -> Vec<u8> {
     body
 }
 
-/// The head of a GameObject-template answer (`SMSG_GAMEOBJECT_QUERY_RESPONSE`, opcode `0x005F`/95,
-/// answering `CMSG_GAMEOBJECT_QUERY`) — decision 0236's ask-once template lookup. `data[24]` is the
-/// template's raw `GameObjectData` union tail (VERIFIED vmangos `QueryHandler.cpp`
-/// `HandleGameObjectQueryOpcode`: `data << info->raw.data[i]` for `i in 0..24`); its slot layout is
-/// **type-specific** (e.g. a chest's lockId lives at a different index than a door's) — this layer
-/// parses the array verbatim and leaves resolving a slot to the consumer that knows `type_id`.
+/// A game object template from `SMSG_GAMEOBJECT_QUERY_RESPONSE`; `data` is the raw
+/// `GameObjectData` union, whose slots mean different things per `type_id`.
 #[derive(Debug, Clone, PartialEq)]
 pub struct GameObjectQueryInfo {
     pub type_id: u32,
@@ -47,13 +29,8 @@ pub struct GameObjectQueryInfo {
     pub data: [i32; 24],
 }
 
-/// Read `SMSG_GAMEOBJECT_QUERY_RESPONSE` → `(entry, Some(info))`, or `(entry, None)` on a miss.
-/// VERIFIED vmangos `QueryHandler.cpp` `HandleGameObjectQueryOpcode`, the
-/// `SUPPORTED_CLIENT_BUILD >= CLIENT_BUILD_1_12_1` branch — wire order: `entry, type, displayId,
-/// name`, then 3 empty name slots + an `icon` C-string (the 5th name slot), all read past and
-/// dropped except `name`, then `data[24]` as 24 little-endian `i32`s. There is **no** trailing float
-/// `size` field in 5875 (the `data << float(info->size)` line is commented out server-side). A miss
-/// is the lone `u32` of `entry | 0x8000_0000` — the same shape as the creature/item miss.
+/// Read `SMSG_GAMEOBJECT_QUERY_RESPONSE` (vmangos `HandleGameObjectQueryOpcode`): no trailing
+/// `size` float in 1.12.1, and a miss is the lone `u32` `entry | 0x8000_0000`.
 pub(super) fn read_gameobject_query_response(
     r: &mut &[u8],
 ) -> io::Result<(u32, Option<GameObjectQueryInfo>)> {
@@ -67,7 +44,7 @@ pub(super) fn read_gameobject_query_response(
     for _ in 0..3 {
         let _ = read_cstring(r)?; // name2..name4, always empty in 5875
     }
-    let _icon = read_cstring(r)?; // name5 — the GO's icon key; unused until a consumer needs it
+    let _icon = read_cstring(r)?; // name5, the icon key
     let mut data = [0i32; 24];
     for slot in &mut data {
         *slot = read_i32_le(r)?;
@@ -83,22 +60,16 @@ pub(super) fn read_gameobject_query_response(
     ))
 }
 
-/// Read `SMSG_GAMEOBJECT_CUSTOM_ANIM` → `(guid, anim_id)`. VERIFIED vmangos
-/// `GameObject::SendGameObjectCustomAnim`: a full `u64` guid then `u32 animId`. The client-side
-/// meaning (wow-re `gameobject-anim-arm.md` §"one-shot channel" step 8): arm the GO's Custom
-/// substate `8 + animId` — AnimationData ids 153..156 — with `animId >= 4` rejected; the
-/// consumer applies that gate, this layer parses verbatim.
+/// Read `SMSG_GAMEOBJECT_CUSTOM_ANIM`: the guid, then `animId`, which the 1.12 client plays as
+/// custom substate `8 + animId` (AnimationData 153 to 156), ignoring `animId >= 4`.
 pub(super) fn read_gameobject_custom_anim(r: &mut &[u8]) -> io::Result<(u64, u32)> {
     let guid = read_u64_le(r)?;
     let anim_id = read_u32_le(r)?;
     Ok((guid, anim_id))
 }
 
-/// Read `SMSG_GAMEOBJECT_DESPAWN_ANIM` → `guid`. VERIFIED vmangos
-/// `WorldObject::SendObjectDeSpawnAnim` (`Objects/Object.cpp:2307`) →
-/// `WorldPackets::Misc::GameObjectDespawnAnim`, whose whole body is the object guid. The
-/// client-side meaning (wow-re `gameobject-anim-arm.md` §2c): arm substate 12, AnimationData id
-/// **157 Despawn** — the arm channel, like the custom one, is disjoint from the §243 lid family.
+/// Read `SMSG_GAMEOBJECT_DESPAWN_ANIM`, only the guid (`Objects/Object.cpp:2307`); the 1.12
+/// client plays substate 12, AnimationData 157 Despawn.
 pub(super) fn read_gameobject_despawn_anim(r: &mut &[u8]) -> io::Result<u64> {
     read_u64_le(r)
 }
@@ -117,7 +88,7 @@ mod tests {
 
     #[test]
     fn cmsg_gameobj_use_body_golden() {
-        // A full little-endian guid, no more (SpellHandler.cpp reads a single ObjectGuid).
+        // SpellHandler.cpp reads a single ObjectGuid.
         assert_eq!(
             gameobj_use(0x1234_5678_9abc_def0),
             hx("f0debc9a78563412"),
@@ -127,8 +98,7 @@ mod tests {
 
     #[test]
     fn cmsg_gameobject_query_body_golden() {
-        // entry u32 + full 8-byte guid — identical shape to CMSG_CREATURE_QUERY (VERIFIED vmangos
-        // `QueryGameObject::ReadFromWorldPacket`).
+        // As vmangos `QueryGameObject::ReadFromWorldPacket` reads it.
         assert_eq!(
             gameobject_query(1731, 0x1234_5678_9abc_def0),
             hx("c3060000f0debc9a78563412"),
@@ -143,9 +113,9 @@ mod tests {
         body.extend_from_slice(&123u32.to_le_bytes()); // displayId
         body.extend_from_slice(b"Chest\0"); // name
         body.extend_from_slice(&[0, 0, 0]); // name2..name4, empty C-strings
-        body.extend_from_slice(b"Icon\0"); // icon (name5) — read past and dropped
+        body.extend_from_slice(b"Icon\0"); // icon (name5), dropped
         let mut data = [0i32; 24];
-        data[0] = 57; // stand-in lockId — the type-specific slot a later consumer resolves
+        data[0] = 57; // a stand-in lockId
         for v in data {
             body.extend_from_slice(&v.to_le_bytes());
         }
@@ -166,10 +136,6 @@ mod tests {
 
     #[test]
     fn gameobject_despawn_anim_decodes() {
-        // The whole body is the object guid (VERIFIED vmangos
-        // `WorldObject::SendObjectDeSpawnAnim` → `WorldPackets::Misc::GameObjectDespawnAnim`,
-        // whose `AppendBodyTo` writes only `gameObjectGuid`). A UBRS Rookery Egg spending its
-        // last trap charge is the load-bearing sender (decision 1404).
         let body = hx("f0debc9a78563412");
         match parse_server(opcode::SMSG_GAMEOBJECT_DESPAWN_ANIM, &body).unwrap() {
             ServerPacket::GameObjectDespawnAnim { guid } => {
@@ -181,8 +147,7 @@ mod tests {
 
     #[test]
     fn gameobject_custom_anim_decodes() {
-        // A full little-endian guid + u32 animId (VERIFIED vmangos
-        // `GameObject::SendGameObjectCustomAnim`). The bobber's bite is animId 0.
+        // A fishing bobber's bite is animId 0.
         let body = hx("f0debc9a7856341200000000");
         match parse_server(opcode::SMSG_GAMEOBJECT_CUSTOM_ANIM, &body).unwrap() {
             ServerPacket::GameObjectCustomAnim { guid, anim_id } => {
@@ -208,9 +173,6 @@ mod tests {
 
     #[test]
     fn gameobject_query_response_miss_decodes() {
-        // A miss is the lone entry echoed with its top bit set (VERIFIED vmangos
-        // HandleGameObjectQueryOpcode's "GO's info was not found" branch — same shape as the
-        // creature/item miss).
         let body = (1731u32 | 0x8000_0000).to_le_bytes();
         match parse_server(opcode::SMSG_GAMEOBJECT_QUERY_RESPONSE, &body).unwrap() {
             ServerPacket::GameObjectQueryResponse { entry, info } => {
diff --git a/crates/benilla-protocol/src/messages/gm_ticket.rs b/crates/benilla-protocol/src/messages/gm_ticket.rs
index 42e9ba39..730dd6c7 100644
--- a/crates/benilla-protocol/src/messages/gm_ticket.rs
+++ b/crates/benilla-protocol/src/messages/gm_ticket.rs
@@ -1,115 +1,53 @@
-//! The GM trouble-ticket family — the five request/answer pairs behind the Help window
-//! (opcodes 0x205-0x21B; decision 1673).
-//!
-//! | opcode | direction | body |
-//! |---|---|---|
-//! | `CMSG_GMTICKET_CREATE` 0x205 | out | `u8` category, `u32` map, `f32` x/y/z, cstring text, cstring reserved |
-//! | `SMSG_GMTICKET_CREATE` 0x206 | in | `u32` response |
-//! | `CMSG_GMTICKET_UPDATETEXT` 0x207 | out | `u8` category, cstring text |
-//! | `SMSG_GMTICKET_UPDATETEXT` 0x208 | in | `u32` response |
-//! | `CMSG_GMTICKET_GETTICKET` 0x211 | out | *empty* |
-//! | `SMSG_GMTICKET_GETTICKET` 0x212 | in | `u32` status, then the ticket iff status == 6 |
-//! | `CMSG_GMTICKET_DELETETICKET` 0x217 | out | *empty* |
-//! | `SMSG_GMTICKET_DELETETICKET` 0x218 | in | `u32` response |
-//! | `CMSG_GMTICKET_SYSTEMSTATUS` 0x21A | out | *empty* |
-//! | `SMSG_GMTICKET_SYSTEMSTATUS` 0x21B | in | `u32` queue status |
-//!
-//! ## The two outbound bodies are byte-verified against the real client, not just the server
-//!
-//! Both are places where reading only the emulator would have got it wrong, so both were taken
-//! from the 5875 binary's own senders:
-//!
-//! - **`CMSG_GMTICKET_CREATE`'s category is a `u8`, not a `u32`** (sender `0x5ef740`, reached from
-//!   the Lua glue `NewGMTicket` `0x48c9d0`): `PutInt8` at `0x5ef851`, then `PutInt32(mapId)`, three
-//!   `PutFloat`s, `PutCString(text)`, and a second cstring — the literal
-//!   [`RESERVED_FOR_FUTURE_USE`] at VA `0x860708`. vmangos reads exactly that head
-//!   (`Server/Packets/GmTicket.cpp:5-17`).
-//! - **`CMSG_GMTICKET_UPDATETEXT` carries the category byte too** (sender `0x5efac0`: `PutInt8` at
-//!   `0x5efb2d`, `PutCString` at `0x5efb3c`). This one is a real fork in the emulator world —
-//!   vmangos reads `u8 type; cstring text` (`GmTicket.cpp:19-23`) and matches the client, while
-//!   cmangos-classic reads a bare cstring (`GMTicketHandler.cpp:160-161`) and therefore swallows
-//!   our category byte as the first character of the ticket. We are faithful to the client; a
-//!   cmangos server would store a stray control byte at the head of the text. Recorded rather than
-//!   worked around: the client is the authority, and bending the wire to one emulator's bug would
-//!   break the other.
-//!
-//! **The `category == 2` chat-log tail is deliberately not sent.** The real client appends a
-//! zlib-compressed transcript of the last (up to 60) chat lines to a Behavior/Harassment ticket
-//! (`0x5ef936` onward). Neither emulator uses it: vmangos does not read it at all (and logs a
-//! parse-length warning for the leftover bytes), cmangos reads two `u32`s under the wrong names
-//! and discards the rest. Sending it would buy nothing and cost a log line per ticket, so
-//! [`gm_ticket_create`] stops after the reserved string — see [`crate::messages::gm_ticket`]'s
-//! test for the byte-exact shape we do send.
-//!
-//! ## The inbound ticket reads TEXT BEFORE CATEGORY
-//!
-//! [`GmTicket`]'s field order is the *wire* order, and it is not the order the Lua `UPDATE_TICKET`
-//! event uses (`HelpFrameOpenTicket_OnEvent` reads arg1 = category, arg2 = description). vmangos
-//! and cmangos agree byte-for-byte on the wire order — `cstring text` then `u8 category`
-//! (vmangos `Server/Packets/GmTicket.cpp:66-79` filled at `GMTicketMgr.cpp:120-151`; cmangos
-//! `GMTickets/GMTicketHandler.cpp:35-51`) — so the reorder happens inside the client's own handler
-//! and belongs to the app's event feed, not here. Decoding it any other way would desynchronise
-//! the whole struct after the first string.
+//! The GM ticket family behind the Help window: create, update text, get, delete and queue
+//! status, each a request and a `u32`-led answer; the get, delete and status requests are empty.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_f32_le, read_u32_le, read_u8};
 
-/// The second cstring of `CMSG_GMTICKET_CREATE`, verbatim from the client's own constant at VA
-/// `0x860708`. It is exactly what it says: a slot nothing has ever read. We send the real string
-/// rather than an empty one because that is what the client puts on the wire, and a server that
-/// ever grows a use for it should see what retail sent.
+/// The second cstring of `CMSG_GMTICKET_CREATE`, the 1.12 client's constant at `0x860708`.
 pub const RESERVED_FOR_FUTURE_USE: &str = "Reserved for future use";
 
 /// `SMSG_GMTICKET_GETTICKET`'s status when a ticket follows (`GMTICKET_STATUS_HASTEXT`).
 pub const GMTICKET_STATUS_HASTEXT: u32 = 0x06;
 
-/// `SMSG_GMTICKET_GETTICKET`'s status when there is no ticket (`GMTICKET_STATUS_DEFAULT`) — a
-/// 4-byte body and nothing after it. **This is the ordinary answer, not an error**: it is what
-/// retail answered the client's own post-login ask with in the 1.12.1 sniff, and it is what the
-/// Help window's "you have no open ticket" state is drawn from.
+/// `SMSG_GMTICKET_GETTICKET`'s status for no ticket (`GMTICKET_STATUS_DEFAULT`): a 4-byte body,
+/// and the ordinary answer to the client's post-login ask.
 pub const GMTICKET_STATUS_DEFAULT: u32 = 0x0A;
 
 /// The queue is accepting tickets (`GMTICKET_QUEUE_STATUS_ENABLED`).
 pub const GMTICKET_QUEUE_ENABLED: i32 = 1;
 
-/// The player's open ticket, as `SMSG_GMTICKET_GETTICKET` describes it.
-///
-/// The three `f32`s are **days**, not seconds, and two of them can legitimately be negative:
-/// cmangos sends `-1.0` for `oldest_ticket_age`/`update_time` when it has never computed them
-/// (`GMTicketMgr.h:318`, `GMTicketMgr.cpp:1340-1343`), and the shipped FrameXML tests exactly that
-/// (`arg4 < 0 or arg5 < 0` → "Wait time currently unavailable"). So this is a plain `f32` with no
-/// clamping: the negative *is* the signal.
+/// The player's open ticket from `SMSG_GMTICKET_GETTICKET`, in wire order: text before category
+/// (`GmTicket.cpp:66-79`), which the Lua `UPDATE_TICKET` event reverses. The `f32`s are days, and
+/// a negative one means unknown (the stock Help frame then shows no wait time).
 #[derive(Debug, Clone, PartialEq)]
 pub struct GmTicket {
-    /// What the player typed. On vmangos a completed ticket has the GM's answer **appended into
-    /// this same string** (`GMTicketMgr.cpp:124-136`) — there is no response channel in 1.12, so
-    /// the reply arrives as part of the description.
+    /// What the player typed; vmangos appends a GM's answer here, as 1.12 has no reply channel
+    /// (`GMTicketMgr.cpp:124-136`).
     pub text: String,
     /// The `GMTicketCategory.dbc` id the ticket was filed under (1..10).
     pub category: u8,
-    /// Days since the ticket was last modified — the FrameXML's `arg3`.
+    /// Days since the ticket was last modified (FrameXML `arg3`).
     pub ticket_age: f32,
-    /// Days since the oldest open ticket on the realm was last modified; `0.0` when there is none,
-    /// negative when unknown. The FrameXML subtracts `ticket_age` from this to estimate the wait.
+    /// Days since the realm's oldest open ticket was modified, 0 when none, negative when unknown;
+    /// the FrameXML's wait estimate is this minus `ticket_age`.
     pub oldest_ticket_age: f32,
-    /// How stale the oldest-ticket figure is, in days; negative or `> 0.042` (≈ 1 hour) means the
-    /// data is no good and the window says so instead of guessing.
+    /// Age of the oldest-ticket figure in days; negative or over 0.042 (about an hour) is stale.
     pub update_time: f32,
-    /// 0 = unassigned, 1 = assigned to a GM, 2 = in the escalation queue. vmangos clamps its
-    /// internal 3 ("escalated and assigned") down to 2 before sending (`GMTicketMgr.cpp:147`), so
-    /// nothing above 2 can arrive.
+    /// 0 unassigned, 1 assigned to a GM, 2 escalated; vmangos clamps its 3 to 2
+    /// (`GMTicketMgr.cpp:147`).
     pub assigned_to_gm: u8,
     /// 1 once a GM has actually opened the ticket, 0 before that.
     pub opened_by_gm: u8,
 }
 
-/// Body of `CMSG_GMTICKET_CREATE` — the Submit that files a new ticket.
+/// `CMSG_GMTICKET_CREATE` body as the 1.12 client sends it (`0x5ef740`): a `u8` category, the
+/// player's map and position, the text, then [`RESERVED_FOR_FUTURE_USE`].
 ///
-/// `map`/`x`/`y`/`z` are where the player is standing when they file it; vmangos stores them so a
-/// GM can `.ticket go` to the spot. The text is sent as typed: the client's own 1999-char cap
-/// (`SStrCopy` bound `0x7d0` at `0x5ef7fd`) sits far above the Help window's `letters="500"`
-/// EditBox, so nothing here can truncate a ticket the UI allowed.
+/// Deviation: the 1.12 client appends a zlib chat transcript to a category 2 ticket (`0x5ef936`);
+/// we omit it because vmangos never reads it and logs the leftover bytes. The client also cuts
+/// the text at 1999 chars (`0x5ef7fd`); we do not, as the Help window stops at 500.
 pub fn gm_ticket_create(category: u8, map: u32, pos: [f32; 3], text: &str) -> Vec<u8> {
     let mut out =
         Vec::with_capacity(1 + 4 + 12 + text.len() + 1 + RESERVED_FOR_FUTURE_USE.len() + 1);
@@ -125,18 +63,8 @@ pub fn gm_ticket_create(category: u8, map: u32, pos: [f32; 3], text: &str) -> Ve
     out
 }
 
-/// Body of `CMSG_GMTICKET_UPDATETEXT` — the "Save Changes" that edits an open ticket.
-///
-/// Carries the category byte as well as the text (module doc: byte-verified at `0x5efb2d`), and
-/// vmangos **stores** it: `HandleGMTicketUpdateTextOpcode` does `SetMessage(packet.ticketText)`
-/// then `SetTicketType(TicketType(packet.type))` before saving (`GMTicketHandler.cpp:59-61`). So an
-/// edit re-files the ticket under whatever category the byte carries, and getting this field wrong
-/// silently moves a GM's ticket to a different queue rather than merely being ignored.
-///
-/// benilla's own Help window has no category picker (decision 1687), so it passes back the
-/// category the server last reported for the ticket — precisely so an edit does not overwrite a
-/// re-filing a GM made. That is the window's discipline, not the server's: the opcode itself will
-/// happily move a ticket to whatever byte arrives.
+/// `CMSG_GMTICKET_UPDATETEXT` body: the category byte (`0x5efb2d`), then the text. vmangos stores
+/// the byte, so an edit re-files the ticket under it (`GMTicketHandler.cpp:59-61`).
 pub fn gm_ticket_updatetext(category: u8, text: &str) -> Vec<u8> {
     let mut out = Vec::with_capacity(1 + text.len() + 1);
     out.push(category);
@@ -145,36 +73,20 @@ pub fn gm_ticket_updatetext(category: u8, text: &str) -> Vec<u8> {
     out
 }
 
-/// Read the shared `u32` answer of `SMSG_GMTICKET_CREATE` / `UPDATETEXT` / `DELETETICKET`.
-///
-/// One reader for three opcodes because all three bodies are the same 4 bytes — the *meaning* of
-/// the number is the opcode's, and that split lives in [`crate::events`]. The value set (vmangos
-/// `GMTicketMgr.h:49-54`): 1 already-exists, 2 create-ok, 3 create-error, 4 update-ok,
-/// 5 update-error, 9 deleted.
+/// Read the `u32` answer shared by create, update text and delete (vmangos `GMTicketMgr.h:49-54`):
+/// 1 already exists, 2 created, 3 create failed, 4 updated, 5 update failed, 9 deleted.
 pub(super) fn read_gm_ticket_response(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
 
-/// Read `SMSG_GMTICKETSYSTEMSTATUS`: 1 = the queue is taking tickets, 0 = it is not.
-///
-/// **Signed, and that is byte-verified rather than a preference.** The reference copies the field
-/// off the wire verbatim (`0x418e95`, no extension), pushes it unmodified (`0x5e467b`) and hands it
-/// to Lua through `0x704fa6 fild dword` — a signed load, with no `cmp`, `test`, clamp or mapping
-/// anywhere in between (wow-re §5). `HelpFrame`'s `arg1 == -1` arm — "the queue is down, say so" —
-/// is therefore reachable exactly when a server sends `0xFFFFFFFF`, and reading this unsigned would
-/// turn that into 4294967295 and silently cost the dialog. vmangos only ever sends 0 or 1, so
-/// nothing here would have caught the difference in a live run.
+/// Read `SMSG_GMTICKET_SYSTEMSTATUS`, 1 when the queue takes tickets and 0 when not. Signed: the
+/// 1.12 client hands it to Lua as a signed dword (`0x704fa6`), and `HelpFrame` branches on -1.
 pub(super) fn read_gm_ticket_system_status(r: &mut &[u8]) -> io::Result<i32> {
     Ok(read_u32_le(r)? as i32)
 }
 
-/// Read `SMSG_GMTICKET_GETTICKET`: a status, and the ticket itself only when that status is
-/// [`GMTICKET_STATUS_HASTEXT`].
-///
-/// Returns `Ok(None)` for every other status — which in practice is the 4-byte
-/// [`GMTICKET_STATUS_DEFAULT`] body meaning "you have no open ticket". Deliberately **not** an
-/// error: that answer is the common case, it is what the client's own post-login ask gets, and
-/// treating it as a parse failure would put a warn line in the log on every login.
+/// Read `SMSG_GMTICKET_GETTICKET`: a status, then the ticket only for
+/// [`GMTICKET_STATUS_HASTEXT`]; any other status is no ticket, not an error.
 pub(super) fn read_gm_ticket(r: &mut &[u8]) -> io::Result<Option<GmTicket>> {
     if read_u32_le(r)? != GMTICKET_STATUS_HASTEXT {
         return Ok(None);
@@ -194,9 +106,7 @@ pub(super) fn read_gm_ticket(r: &mut &[u8]) -> io::Result<Option<GmTicket>> {
 mod tests {
     use super::*;
 
-    /// The create body, byte for byte — the client's own field order and widths (`0x5ef740`), with
-    /// the category as ONE byte. Getting this wrong by widening the category to `u32` would shift
-    /// the map id and the whole position by three bytes and file every ticket at a garbage spot.
+    /// The field order and widths of the 1.12 client's sender (`0x5ef740`).
     #[test]
     fn the_create_body_is_a_category_byte_then_map_position_text_and_the_reserved_string() {
         let body = gm_ticket_create(4, 1, [-8949.95, -132.493, 83.5312], "My sword vanished.");
@@ -208,8 +118,6 @@ mod tests {
         want.extend_from_slice(b"My sword vanished.\0");
         want.extend_from_slice(b"Reserved for future use\0");
         assert_eq!(body, want);
-        // The tail the client sends for a Behavior/Harassment ticket is deliberately absent: the
-        // body ends at the reserved string for every category, including 2.
         assert_eq!(
             gm_ticket_create(2, 0, [0.0; 3], "x").len(),
             1 + 4 + 12 + 2 + 24,
@@ -217,8 +125,7 @@ mod tests {
         );
     }
 
-    /// The updatetext body leads with the category byte — the divergence the module doc records.
-    /// A bare cstring here is what cmangos expects and what the client never sends.
+    /// As the 1.12 client's sender writes it (`0x5efac0`).
     #[test]
     fn the_updatetext_body_leads_with_the_category_byte() {
         assert_eq!(
@@ -227,9 +134,7 @@ mod tests {
         );
     }
 
-    /// The ticket round-trips in WIRE order — text first, category second. Pinning it here is the
-    /// point: the Lua event's order is the reverse, and a "fix" that swapped these two to match
-    /// the event would desynchronise every field after the string.
+    /// The Lua `UPDATE_TICKET` event reverses this order; the wire does not.
     #[test]
     fn a_held_ticket_decodes_in_wire_order_text_before_category() {
         let mut bytes = GMTICKET_STATUS_HASTEXT.to_le_bytes().to_vec();
@@ -255,9 +160,7 @@ mod tests {
         );
     }
 
-    /// The queue status is read SIGNED: `0xFFFFFFFF` must reach Lua as `-1`, which is the value the
-    /// shipped window branches on to raise "GM Help Tickets are currently unavailable." Read it
-    /// unsigned and that arm can never fire.
+    /// The stock Help frame branches on -1 ("GM Help Tickets are currently unavailable.").
     #[test]
     fn the_queue_status_is_signed_so_all_ones_reads_as_minus_one() {
         assert_eq!(
@@ -270,13 +173,12 @@ mod tests {
         );
     }
 
-    /// "You have no ticket" is a 4-byte body and an `Ok(None)`, never an error — it is the answer
-    /// retail gave the client's own post-login ask, so an error here would warn on every login.
+    /// Retail's answer to the client's own post-login ask.
     #[test]
     fn the_no_ticket_answer_is_four_bytes_and_is_not_an_error() {
         let bytes = GMTICKET_STATUS_DEFAULT.to_le_bytes();
         assert_eq!(read_gm_ticket(&mut &bytes[..]).unwrap(), None);
-        // Any other status is likewise "nothing to show" rather than a parse failure.
+        // Any other status is also no ticket.
         let bytes = 0u32.to_le_bytes();
         assert_eq!(read_gm_ticket(&mut &bytes[..]).unwrap(), None);
     }
diff --git a/crates/benilla-protocol/src/messages/gossip.rs b/crates/benilla-protocol/src/messages/gossip.rs
index aac5d1ca..5d5e93ab 100644
--- a/crates/benilla-protocol/src/messages/gossip.rs
+++ b/crates/benilla-protocol/src/messages/gossip.rs
@@ -1,19 +1,11 @@
-//! Gossip + NPC-text messages — the "right-click a friendly NPC → dialog" family (opcodes 379-384,
-//! vmangos `Opcodes_1_12_1.h`, VERIFIED). Bodies from vmangos `Npc.{h,cpp}` + the hand-serialized
-//! `GossipDef.cpp`. Vendor bodies live beside this in [`super::vendor`] — a different wire family
-//! (`CMSG_LIST_INVENTORY`/buy/sell) that a gossip option can lead into but doesn't share a shape with.
-//! Quest-giver flows (`SMSG_QUESTGIVER_*`) are a separate, out-of-scope arc; the quest-option block
-//! riding inside `SMSG_GOSSIP_MESSAGE` is parsed here only to stay byte-aligned.
+//! Gossip and NPC text, the dialog a friendly NPC opens (vmangos `Npc.cpp`, `GossipDef.cpp`).
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_cstring, read_f32_le, read_u32_le, read_u64_le, read_u8};
 
-/// One gossip menu entry (`SMSG_GOSSIP_MESSAGE`'s option list, 1.12 shape — no box-money field,
-/// that's TBC+). `index` is the value the client echoes back as `gossipListId` on select; `icon` is
-/// a `GOSSIP_ICON_*` (0 chat bubble, 1 vendor, 2 taxi, 3 trainer, …); `coded` marks a password-gated
-/// option (petition signing etc. — v1 sends an empty code only for non-coded options, see
-/// [`gossip_select_option`]).
+/// One `SMSG_GOSSIP_MESSAGE` option: `index` is echoed as `gossipListId` on select, `icon` is a
+/// `GOSSIP_ICON_*` (0 chat, 1 vendor, 2 taxi, 3 trainer, …), `coded` asks for a code.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct GossipOption {
     pub index: u32,
@@ -22,9 +14,7 @@ pub struct GossipOption {
     pub message: String,
 }
 
-/// One quest-giver entry riding the same packet (`SMSG_GOSSIP_MESSAGE`'s quest-option list). Parsed
-/// for byte alignment only — quest-giver flows are out of scope for this arc (gossip/vendor arc
-/// brief §8).
+/// One quest in `SMSG_GOSSIP_MESSAGE`'s quest list.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QuestOption {
     pub quest_id: u32,
@@ -33,18 +23,14 @@ pub struct QuestOption {
     pub title: String,
 }
 
-/// Body of `CMSG_GOSSIP_HELLO` (vmangos `Npc.cpp:3`): one full 8-byte NPC guid. Works on *any*
-/// interactable creature, not only gossip-flagged ones — the server's `CanInteractWithNPC` passes
-/// `UNIT_NPC_FLAG_NONE` for this opcode (`Player.cpp:347`).
+/// `CMSG_GOSSIP_HELLO` body: the NPC's full guid (`Npc.cpp:3`); it works on any interactable
+/// creature, gossip flag or not (`Player.cpp:347`).
 pub fn gossip_hello(npc_guid: u64) -> Vec<u8> {
     npc_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_GOSSIP_SELECT_OPTION` (vmangos `Npc.cpp:78-86`): guid, the `gossipListId`
-/// (= the chosen [`GossipOption::index`]), then an **optional** trailing code cstring — appended
-/// only for a `coded` option carrying a real code; the server reads it only when the buffer is
-/// non-empty, so a non-coded select must omit it entirely rather than send an empty string.
-/// Handler dispatch: `NPCHandler.cpp:370`.
+/// `CMSG_GOSSIP_SELECT_OPTION` body: guid, the option's `index`, then the code only for a coded
+/// option; the server reads a code whenever bytes remain, so omit it otherwise (`Npc.cpp:78-86`).
 pub fn gossip_select_option(npc_guid: u64, gossip_list_id: u32, code: Option<&str>) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&npc_guid.to_le_bytes());
@@ -56,9 +42,7 @@ pub fn gossip_select_option(npc_guid: u64, gossip_list_id: u32, code: Option<&st
     body
 }
 
-/// Body of `CMSG_NPC_TEXT_QUERY` (vmangos `Npc.cpp:8-12`): `u32 textID`, `u64 guid`. Sent on
-/// receiving a gossip menu to fetch the greeting text for `textId` (ask-once cacheable, like the
-/// item template query).
+/// `CMSG_NPC_TEXT_QUERY` body: the text id, then the NPC's guid (`Npc.cpp:8-12`).
 pub fn npc_text_query(text_id: u32, guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&text_id.to_le_bytes());
@@ -66,10 +50,7 @@ pub fn npc_text_query(text_id: u32, guid: u64) -> Vec<u8> {
     body
 }
 
-/// Read `SMSG_GOSSIP_MESSAGE` (vmangos `GossipDef.cpp:180-225`, the 1.12 shape — build 5875 predates
-/// the TBC box-money field): `u64 objectGuid, u32 textId, u32 optionCount` + options
-/// (`u32 index, u8 icon, u8 coded, cstr message`), then `u32 questCount` + quest options
-/// (`u32 questId, u32 icon, u32 level, cstr title`). Returns `(npc_guid, text_id, options, quests)`.
+/// Read `SMSG_GOSSIP_MESSAGE` (vmangos `GossipDef.cpp:180-225`); 1.12 options have no box money.
 pub(super) fn read_gossip_message(
     r: &mut &[u8],
 ) -> io::Result<(u64, u32, Vec<GossipOption>, Vec<QuestOption>)> {
@@ -87,8 +68,7 @@ pub(super) fn read_gossip_message(
         });
     }
     let quest_count = read_u32_le(r)?;
-    // The quest menu is an unbounded vector server-side (`GossipDef.h:184`); the same 32-item
-    // client display limit bounds the hint.
+    // Unbounded server-side (`GossipDef.h:184`); the 32-item display limit bounds the hint.
     let mut quests = Vec::with_capacity(capacity_hint(quest_count, 32));
     for _ in 0..quest_count {
         quests.push(QuestOption {
@@ -101,21 +81,18 @@ pub(super) fn read_gossip_message(
     Ok((npc_guid, text_id, options, quests))
 }
 
-/// One of the 8 greeting variants in an `SMSG_NPC_TEXT_UPDATE` record. Both gender columns are kept:
-/// which one is read is decided **per NPC**, not per block — see [`select_greeting`].
+/// One of the eight greeting variants of an `SMSG_NPC_TEXT_UPDATE` record, both gender columns.
 #[derive(Debug, Clone, Default, PartialEq)]
 pub struct NpcTextBlock {
-    /// The block's draw weight. Not a rank — the reference sums these and draws (see
-    /// [`select_greeting`]); vmangos's own fallback record sets all eight to `0.0`.
+    /// The block's draw weight, not a rank; vmangos's fallback record sets all eight to 0.
     pub probability: f32,
-    /// `text0` — shown when the NPC is male, or genderless.
+    /// `text0`, shown when the NPC is male or genderless.
     pub male: String,
-    /// `text1` — shown when the NPC is female.
+    /// `text1`, shown when the NPC is female.
     pub female: String,
 }
 
 impl NpcTextBlock {
-    /// This block's text in the gender column [`select_greeting`] chose for the NPC.
     fn column(&self, female: bool) -> &str {
         if female {
             &self.female
@@ -125,21 +102,14 @@ impl NpcTextBlock {
     }
 }
 
-/// The number of greeting blocks in an `SMSG_NPC_TEXT_UPDATE` record — always exactly 8.
+/// The greeting blocks in every `SMSG_NPC_TEXT_UPDATE` record.
 pub const NPC_TEXT_BLOCKS: usize = 8;
 
-/// Read `SMSG_NPC_TEXT_UPDATE` (vmangos `GossipDef.cpp:298-369`): `u32 textID` then always exactly 8
-/// blocks of `{f32 probability, cstr text0 (male), cstr text1 (female), u32 languageId, 3x(u32
-/// emoteDelay, u32 emoteId)}`. Returns `(text_id, blocks)` — **all** of them, undecided.
+/// Read `SMSG_NPC_TEXT_UPDATE` (vmangos `GossipDef.cpp:298-369`), all eight blocks undecided; the
+/// greeting is picked when the frame opens, by [`select_greeting`].
 ///
-/// This layer used to pick the greeting here (highest probability, with a per-block fall back to the
-/// other gender column). Both halves of that were wrong, and neither could be fixed here: the real
-/// choice needs the NPC and a die roll, which the wire layer has neither of. It belongs at the
-/// moment the frame opens, where the reference does it — [`select_greeting`], called from the app.
-///
-/// The language and emote tails are still parsed for alignment and dropped. Language is the input to
-/// the reference's garble pass (`0x49b560`), which is inert at `lang == 0`; we do not garble at all,
-/// so a non-zero language would read plainly here. No such record is known in 1.12 data.
+/// Deviation: the 1.12 client garbles a block in a non-zero language (`0x49b560`); we drop the
+/// language because no 1.12 record sets one.
 pub(super) fn read_npc_text_update(r: &mut &[u8]) -> io::Result<(u32, Vec<NpcTextBlock>)> {
     let text_id = read_u32_le(r)?;
     let mut blocks = Vec::with_capacity(NPC_TEXT_BLOCKS);
@@ -161,36 +131,26 @@ pub(super) fn read_npc_text_update(r: &mut &[u8]) -> io::Result<(u32, Vec<NpcTex
     Ok((text_id, blocks))
 }
 
-/// A point-of-interest marker (`SMSG_GOSSIP_POI`) — the flag a guard drops on your map when you
-/// ask where the warrior trainer is. Volunteered by the server when a gossip option carries an
-/// `action_poi_id` (vmangos `Player::OnGossipSelect` → `PlayerMenu::SendPointOfInterest`), so it
-/// answers no request of ours and can arrive with or without the menu staying open.
-///
-/// The reference client feeds it into the minimap's **AreaPOI landmark** pipeline as a synthetic
-/// record (`system/minimap/scratch/minimap-re.md`: blip slot 1, `0xcea7d4`, written by
-/// `set_blip 0x6dac10` from the 0x224 handler `0x4e2840`) — which is why the field names below are
-/// the DBC's: `flags` and `icon` are read by exactly the laws that read `AreaPOI.dbc`'s columns.
+/// `SMSG_GOSSIP_POI`, the map flag a guard drops when asked for directions; the server sends it
+/// unasked from a gossip option (`Player::OnGossipSelect`). The 1.12 client treats it as an
+/// `AreaPOI.dbc` record in minimap blip slot 1 (`0x4e2840`), hence the DBC field names.
 #[derive(Debug, Clone, PartialEq)]
 pub struct GossipPoi {
-    /// The `AreaPOI.dbc` `Flags` column's role: bit 0 = a candidate at all, bit 1 = draw the
-    /// in-range icon. 5875-era `points_of_interest` rows all ship `99` (0x63 — both bits set).
+    /// As `AreaPOI.dbc` `Flags`: bit 0 makes it a candidate, bit 1 draws the in-range icon; every
+    /// vmangos row sends 99.
     pub flags: u32,
-    /// World position — **x, y only**; the wire carries no z (the marker is a map pin, and every
-    /// law that consumes it measures a 2-D distance).
+    /// World x and y; the wire carries no z.
     pub pos: [f32; 2],
-    /// The `POIIcons.blp` cell, 8×8 grid, gated `< 64` by the draw. All 250 5875-era rows use
-    /// `6` = `ICON_POI_REDFLAG`, "red flag w/ yellow !" (vmangos `GossipDef.h:113`).
+    /// The `POIIcons.blp` cell (8×8 grid, drawn only below 64); every vmangos row uses 6, the red
+    /// flag (`GossipDef.h:113`).
     pub icon: u32,
-    /// vmangos `points_of_interest.data` — `0` in every 5875-era row (the `.debug send poi`
-    /// command sends `30`). Carried for the wire's sake; see the app-side marker for what the
-    /// reference does with it.
+    /// vmangos `points_of_interest.data`, 0 in every row.
     pub data: u32,
-    /// The destination's name ("Stormwind Warrior Trainer") — the marker's hover tooltip.
+    /// The destination's name, the marker's tooltip.
     pub name: String,
 }
 
-/// Read `SMSG_GOSSIP_POI` (vmangos `GossipDef.cpp:239-295` — both overloads write the same
-/// shape): `u32 flags, f32 x, f32 y, u32 icon, u32 data, cstr name`.
+/// Read `SMSG_GOSSIP_POI` (vmangos `GossipDef.cpp:239-295`).
 pub(super) fn read_gossip_poi(r: &mut &[u8]) -> io::Result<GossipPoi> {
     let flags = read_u32_le(r)?;
     let x = read_f32_le(r)?;
@@ -204,34 +164,10 @@ pub(super) fn read_gossip_poi(r: &mut &[u8]) -> io::Result<GossipPoi> {
     })
 }
 
-/// Pick the greeting line the way the reference does (`0x4e2010`, wow-re
-/// `system/ui/scratch/gossip-npctext-law.md`) — a **weighted random draw**, not the highest weight:
-///
-/// ```text
-/// sum = Σ probability  over blocks whose CHOSEN-COLUMN text is non-empty
-/// thr = (2.0 - roll) * sum          ∈ (0, sum]   for roll ∈ [1.0, 2.0)
-/// walk the same blocks in order, acc += probability, take the first where thr <= acc
-/// ```
-///
-/// Three details are load-bearing, and each is the opposite of what we assumed:
-///
-/// - **The column is chosen once, from the NPC's own gender** (`UNIT_FIELD_BYTES_0` byte 2, tested
-///   `== 1` for female — so genderless `2` reads as male), before any block is examined. It is never
-///   chosen per block, never from the emptiness of a string, and never from the *player*, whom the
-///   reference resolves only as an existence check and never dereferences for data.
-/// - **There is no fallback to the other column.** A block whose chosen-column text is empty is
-///   excluded from the draw outright; if that empties the record, the reference takes its error path
-///   and shows no greeting at all, rather than reading the other gender's line.
-/// - **The predicate is `<=`, not `<`** (the emitted jcc is `jne` on `test ah,0x41`, so the equal
-///   case selects). That is what makes an all-`0.0` record — vmangos's fallback, and much of the
-///   1.12 table — deterministically select block 0 instead of nothing.
-///
-/// `roll` is the reference's uniform float in `[1.0, 2.0)` (it builds one by stuffing PRNG bits into
-/// a mantissa: `(rand & 0x7fffff) | 0x3f800000`); passing it in keeps this pure and lets tests pin
-/// each branch. Accumulation is `f64` deliberately: the reference's accumulators live on the x87
-/// stack at 53-bit precision and round to `f32` exactly once, at the end.
-///
-/// `None` = the record names no greeting for this NPC (the reference's `"Missing gossip text!"`).
+/// Pick the greeting as the 1.12 client does (`0x4e2010`): a weighted draw over the blocks with
+/// text in the NPC's gender column (female only at 1), never falling back to the other column.
+/// `roll` is uniform in `[1.0, 2.0)`, `<=` makes an all-zero record pick block 0, and the sums
+/// are `f64` as on the client's x87 stack. `None` is its "Missing gossip text!".
 pub fn select_greeting(blocks: &[NpcTextBlock], npc_gender: u8, roll: f32) -> Option<&str> {
     let female = npc_gender == 1;
     let drawn = || blocks.iter().filter(|b| !b.column(female).is_empty());
diff --git a/crates/benilla-protocol/src/messages/group.rs b/crates/benilla-protocol/src/messages/group.rs
index 97d53e5b..73c2d269 100644
--- a/crates/benilla-protocol/src/messages/group.rs
+++ b/crates/benilla-protocol/src/messages/group.rs
@@ -1,12 +1,6 @@
-//! Group/party messages — invite/accept/decline/kick/leader/disband, the loot method, the roster
-//! push, party command feedback, live member stats for the party/raid frame, minimap pings, raid
-//! subgroup management, raid-target icons, and ready checks (opcodes 110/111/114-127, 469,
-//! 638-640, 654-655, 754, 801-802 — VERIFIED vmangos `Server/Protocol/Opcodes_1_12_1.h`). CMSG
-//! bodies from vmangos `Server/Packets/Group.{h,cpp}` (every `ReadFromWorldPacket`); SMSG layouts
-//! from the same file's `AppendBodyTo` writers plus the hand-serialized member-stats builder in
-//! `Handlers/GroupHandler.cpp` (line citations inline in each item). `ObjectGuid`'s own
-//! `operator<</>>` (`ObjectGuid.cpp:172-183`) is a plain 8-byte `u64` — every guid below is FULL
-//! unless explicitly marked PACKED (only [`PartyMemberStatsInfo`]'s subject guid is).
+//! Group messages: invites, leadership, loot method, roster, member stats, minimap pings,
+//! subgroups, raid target icons, ready checks and lockouts (vmangos `Server/Packets/Group.cpp`).
+//! Every guid here is a full `u64` except the party member stats subject, which is packed.
 
 use std::io::{self, Read};
 
@@ -16,14 +10,11 @@ use crate::wire::{
     read_u64_le, read_u8,
 };
 
-/// The raid-assistant bit in [`GroupMemberEntry::flags`] / `SMSG_GROUP_LIST`'s own-flags byte —
-/// bits 0-2 carry the subgroup index (0-7, raid-only; a party has just one), this bit marks a
-/// raid assistant (VERIFIED vmangos `Group.cpp:158,166`: `uint8(itr.group | (itr.assistant ? 0x80
-/// : 0))`).
+/// The raid-assistant bit of a member's flags byte; bits 0-2 are the subgroup
+/// (`Group.cpp:158,166`).
 pub const GROUP_MEMBER_ASSISTANT: u8 = 0x80;
 
-/// `GroupMemberStatus` (VERIFIED vmangos `Group/Group.h:102-111`) — the bits of
-/// [`GroupMemberEntry::status`] (bit `0x20` is reserved/unused — `MEMBER_STATUS_UNK3`, never set).
+/// vmangos `GroupMemberStatus` (`Group/Group.h:102-111`); bit `0x20` is never set.
 pub mod member_status {
     pub const OFFLINE: u8 = 0x00;
     pub const ONLINE: u8 = 0x01;
@@ -35,16 +26,13 @@ pub mod member_status {
     pub const DND: u8 = 0x80;
 }
 
-/// `PartyOperation` (VERIFIED vmangos `Server/WorldSession.h:94-98`) — the `u32` on
-/// `SMSG_PARTY_COMMAND_RESULT` naming which command the result answers.
+/// vmangos `PartyOperation` (`WorldSession.h:94-98`): which command a party result answers.
 pub mod party_operation {
     pub const INVITE: u32 = 0;
     pub const LEAVE: u32 = 2;
 }
 
-/// `PartyResult` (VERIFIED vmangos `Server/WorldSession.h:100-111`) — the `u32` verdict on
-/// `SMSG_PARTY_COMMAND_RESULT`. `ERR_INTERNAL_BATTLEGROUND` (10, "does not exist client-side" per
-/// vmangos's own comment) never reaches the wire and is omitted.
+/// vmangos `PartyResult` (`WorldSession.h:100-111`), the verdict of `SMSG_PARTY_COMMAND_RESULT`.
 pub mod party_result {
     pub const OK: u32 = 0;
     pub const BAD_PLAYER_NAME: u32 = 1;
@@ -57,38 +45,31 @@ pub mod party_result {
     pub const IGNORING_YOU: u32 = 8;
 }
 
-/// One other member row on `SMSG_GROUP_LIST` (VERIFIED vmangos `Server/Packets/Group.h:261-267`,
-/// `Group.cpp:161-167`, `Group::SendUpdate`). The recipient's own row never appears in the list —
-/// their subgroup/assistant flag rides `SMSG_GROUP_LIST`'s separate `own_flags` byte instead.
+/// One `SMSG_GROUP_LIST` member row (`Group.cpp:161-167`); the recipient has no row, their flags
+/// ride the list's own-flags byte.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct GroupMemberEntry {
     pub name: String,
     pub guid: u64,
     /// [`member_status`] bits (`GetGroupMemberStatus`, `Group.cpp:45-63`).
     pub status: u8,
-    /// Subgroup index in bits 0-2; [`GROUP_MEMBER_ASSISTANT`] (`0x80`) set = raid assistant.
+    /// Subgroup in bits 0-2, plus [`GROUP_MEMBER_ASSISTANT`].
     pub flags: u8,
 }
 
-/// The loot-method tail `SMSG_GROUP_LIST` appends only when the member list is non-empty
-/// (VERIFIED `Group.cpp:170-179`). `threshold` is an `ItemQualities` value (2..4 in practice —
-/// uncommon and up).
+/// The loot tail `SMSG_GROUP_LIST` carries only when it lists members (`Group.cpp:170-179`);
+/// `threshold` is an item quality, 2 to 4 in practice.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct GroupLootInfo {
-    /// `0` free-for-all, `1` round-robin, `2` master, `3` group, `4` need-before-greed (vmangos
-    /// `LootMethod`, `Group.h`).
+    /// 0 free-for-all, 1 round-robin, 2 master, 3 group, 4 need before greed (`LootMethod`).
     pub method: u8,
-    /// The master looter's guid — `0` unless `method == 2` (master loot).
+    /// The master looter, 0 unless `method` is 2.
     pub master: u64,
     pub threshold: u8,
 }
 
-/// Read `SMSG_GROUP_LIST` (VERIFIED vmangos `Group.cpp:155-180`, `GroupList::AppendBodyTo`):
-/// `u8 groupType` (0 party / 1 raid), `u8 ownGroupAndAssistantFlag`, `u32 memberCount`,
-/// `memberCount` × [`GroupMemberEntry`], `u64 leaderGuid`, then — only if `memberCount > 0` — the
-/// [`GroupLootInfo`] tail plus a trailing `u8 dungeonDifficulty` (always `0` at 5875, `Group.h:281`
-/// — "unused in 1.x"). The "you left the group" shape is the degenerate empty-member-list case:
-/// exactly 14 bytes (`0, 0, u32 0, u64 0`), no tail at all.
+/// Read `SMSG_GROUP_LIST` (`Group.cpp:155-180`): type (0 party, 1 raid), own flags, members,
+/// leader, then the loot tail only with members. "You left the group" is the 14-byte empty list.
 #[allow(clippy::type_complexity)]
 pub(super) fn read_group_list(
     r: &mut &[u8],
@@ -123,35 +104,28 @@ pub(super) fn read_group_list(
     Ok((group_type, own_flags, members, leader, loot))
 }
 
-/// Read `SMSG_GROUP_INVITE` (VERIFIED vmangos `Group.cpp:107-110`,
-/// `GroupInviteNotification::AppendBodyTo`): one cstring, the inviter's name.
+/// Read `SMSG_GROUP_INVITE`: the inviter's name (`Group.cpp:107-110`).
 pub(super) fn read_group_invite(r: &mut impl Read) -> io::Result<String> {
     read_cstring(r)
 }
 
-/// Read `SMSG_GROUP_DECLINE` (VERIFIED vmangos `Group.cpp:112-115`,
-/// `GroupDeclineNotification::AppendBodyTo`): one cstring, the declining player's name.
+/// Read `SMSG_GROUP_DECLINE`: the decliner's name (`Group.cpp:112-115`).
 pub(super) fn read_group_decline(r: &mut impl Read) -> io::Result<String> {
     read_cstring(r)
 }
 
-/// Read `SMSG_GROUP_SET_LEADER` (VERIFIED vmangos `Group.cpp:150-153`,
-/// `GroupSetLeaderNotification::AppendBodyTo`): one cstring, the new leader's name.
+/// Read `SMSG_GROUP_SET_LEADER`: the new leader's name (`Group.cpp:150-153`).
 pub(super) fn read_group_set_leader(r: &mut impl Read) -> io::Result<String> {
     read_cstring(r)
 }
 
-/// Read `SMSG_PARTY_COMMAND_RESULT` (VERIFIED vmangos `Group.cpp:100-105`,
-/// `PartyCommandResult::AppendBodyTo`): `u32 operation` ([`party_operation`]), `cstring
-/// memberName` (may be empty — e.g. the ignoring-you refusal names no one, `Handlers/
-/// GroupHandler.cpp:466`), `u32 result` ([`party_result`]).
+/// Read `SMSG_PARTY_COMMAND_RESULT` (`Group.cpp:100-105`): operation, member name, result; the
+/// name can be empty, as in the ignoring-you refusal (`GroupHandler.cpp:466`).
 pub(super) fn read_party_command_result(r: &mut impl Read) -> io::Result<(u32, String, u32)> {
     Ok((read_u32_le(r)?, read_cstring(r)?, read_u32_le(r)?))
 }
 
-/// `GROUP_UPDATE_FLAG_*` (VERIFIED vmangos `Group/Group.h:124-151`) — the bits of the leading `u32`
-/// mask on `SMSG_PARTY_MEMBER_STATS`/`_FULL`, selecting which fields follow, each in ascending bit
-/// order (see [`read_party_member_stats`]).
+/// vmangos `GROUP_UPDATE_FLAG_*` (`Group.h:124-151`): the member stats that follow, in bit order.
 pub mod party_member_mask {
     pub const STATUS: u32 = 0x0000_0001;
     pub const CUR_HP: u32 = 0x0000_0002;
@@ -176,13 +150,8 @@ pub mod party_member_mask {
     pub const PET_AURAS_NEGATIVE: u32 = 0x0010_0000;
 }
 
-/// One `SMSG_PARTY_MEMBER_STATS`/`_FULL` payload — both opcodes decode through the same field
-/// layout (the caller picks `full` off which opcode arrived, see [`super::ServerPacket::name`]'s
-/// arm): a packed guid, a `u32` field mask ([`party_member_mask`]), then only the fields whose bit
-/// is set — `None` otherwise (VERIFIED vmangos `Handlers/GroupHandler.cpp:590-742`,
-/// `BuildPartyMemberStatsPacket`). The plain (delta) opcode's mask names only what *changed*; the
-/// `_FULL` opcode (our own [`request_party_member_stats`] ask, or the offline-miss reply) sets
-/// every bit the target has data for.
+/// One `SMSG_PARTY_MEMBER_STATS` or `_FULL` payload (`GroupHandler.cpp:590-742`): only the masked
+/// fields are present. The plain opcode carries what changed; `_FULL` everything the server has.
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct PartyMemberStatsInfo {
     pub status: Option<u8>,
@@ -193,13 +162,11 @@ pub struct PartyMemberStatsInfo {
     pub max_power: Option<u16>,
     pub level: Option<u16>,
     pub zone: Option<u16>,
-    /// Raw WoW `(x, y)`, truncated to `i16` on the wire (vmangos casts the live float position,
-    /// `GroupHandler.cpp:623`).
+    /// Raw WoW x and y, truncated to `i16` by the server (`GroupHandler.cpp:623`).
     pub position: Option<(i16, i16)>,
-    /// Active buff spell ids, ascending bit order — the wire's `u32` position-mask prefix is
-    /// decoded away (no consumer needs the raw aura slot, only which buffs are up).
+    /// Active buff spell ids in slot order; the wire's `u32` slot mask is not kept.
     pub auras: Option<Vec<u16>>,
-    /// Active debuff spell ids, same convention as [`Self::auras`] (the wire mask here is `u16`).
+    /// Active debuff spell ids, likewise, from a `u16` slot mask.
     pub auras_negative: Option<Vec<u16>>,
     pub pet_guid: Option<u64>,
     pub pet_name: Option<String>,
@@ -214,12 +181,8 @@ pub struct PartyMemberStatsInfo {
 }
 
 impl PartyMemberStatsInfo {
-    /// **The `1/1` placeholder** — the record a member *new to the roster* starts life with
-    /// (VERIFIED wow-re `ui/scratch/party-oor-stats-and-portrait-law.md` §2.2: the GROUP_LIST slot
-    /// writer `0x4e82d0` zero-fills the record and then stores `1` into `+0x0a`/`+0x0c`/`+0x0e`/
-    /// `+0x10` at `0x4e833d`-`0x4e8357`). It is what an out-of-range member you have never seen
-    /// shows until their first stats packet lands: a *full* bar, not an empty one. `status` carries
-    /// the roster's own online bit, which is the one field the writer takes from its caller.
+    /// The record of a member new to the roster: 1/1 health and power, so an unseen member shows
+    /// full bars until stats arrive (`0x4e833d`), and the roster's online bit.
     pub fn placeholder(online: bool) -> Self {
         Self {
             status: Some(u8::from(online)),
@@ -231,53 +194,31 @@ impl PartyMemberStatsInfo {
         }
     }
 
-    /// **The live-descriptor snapshot** — `0x5f0880`, the record's third writer beside the wire and
-    /// the slot writer (VERIFIED wow-re `object-layer/scratch/party-record-live-snapshot.md` §1).
-    /// The reference runs it at the instant a party/raid member's object leaves the object manager
-    /// (`SMSG_DESTROY_OBJECT` and the `OUT_OF_RANGE` block take the same virtual), immediately
-    /// before asking the server for the member's stats — which is why an out-of-range party frame
-    /// never reads `0/0` at the despawn edge.
+    /// Snapshot a member's live descriptor as the 1.12 client does (`0x5f0880`) when the member's
+    /// object leaves view, just before the stats request, so the frame never reads 0/0. Values are
+    /// raw; [`Self::shown_power`] divides at the read. AFK and DND are cleared, as in the client.
     ///
-    /// Fields, in the binary's own order: `status` (bit0 online — an object you can see belongs to
-    /// an online player, `0x5f088e c6 46 08 01`; bit3 ghost; bit1 PVP; bit4 FFA-PVP; bit2 dead),
-    /// `+0x0a` cur HP, `+0x0c` max HP, `+0x09` power type, `+0x0e`/`+0x10` the power pair,
-    /// `+0x12` level. **Raw** descriptor values, not the `Unit*` getters' display ones: the
-    /// reference copies the field words (`5f08ea 66 8b 51 40`), and the raw→display divide happens
-    /// at the *read*, in [`Self::shown_power`] — the same place the live path does it.
-    ///
-    /// **Three stated deviations** (decision 1640), each a field with no reader in benilla today:
-    /// - `zone` and `position` are **left as they were** rather than overwritten. The reference
-    ///   writes the *viewer's* zone (`[0xb4e314]`) and the object's world position; ours keeps the
-    ///   last wire-reported pair, which the `_FULL` answer to the request corrects within a round
-    ///   trip either way. Nothing draws party dots on the minimap yet — that is the consumer whose
-    ///   arrival makes the position worth plumbing.
-    /// - the 48-slot **aura** block and the **pet** block are not snapshotted: benilla feeds no
-    ///   party-token aura list and resolves no `partypetN` token, so both would be write-only.
-    /// - AFK/DND (`0x40`/`0x80`) are dropped from `status`, exactly as the reference's byte is
-    ///   rewritten whole — those two bits live on the roster entry, which is what the party frame
-    ///   actually overlays.
+    /// Deviation: zone and position are kept, not set to the viewer's zone and the object's
+    /// position, and the aura and pet blocks are not copied, because nothing in benilla reads them.
     pub fn snapshot_descriptor(&mut self, fields: &crate::messages::update_object::ObjectFields) {
         let mut status = member_status::ONLINE;
         if fields.player_is_ghost() {
             status |= member_status::GHOST;
         }
-        // `UNIT_FIELD_FLAGS` PvP bit — the same word/bit the tooltip's PvP line reads.
+        // `UNIT_FIELD_FLAGS` PvP bit.
         if fields.unit_flags() & 0x1000 != 0 {
             status |= member_status::PVP;
         }
-        // `PLAYER_FLAGS` bit 7 (`0x5f08be c1 ea 07`).
+        // `PLAYER_FLAGS` bit 7 (`0x5f08be`).
         if fields.player_flags() & 0x80 != 0 {
             status |= member_status::PVP_FFA;
         }
-        // `[desc+0x40] <= 0` — the raw health, not `unit_reads_dead`: the snapshot has no
-        // dyn-flag leg, so a feigning member's record says alive (`5f08d3 85 c9; 7f 04`).
+        // Raw health, not `unit_reads_dead`: a feigning member reads alive (`0x5f08d3`).
         if fields.unit_health().unwrap_or(0) == 0 {
             status |= member_status::DEAD;
         }
         self.status = Some(status);
-        // The record's fields are `u16` (`+0x0a`..`+0x12`), and so is the wire's — the reference
-        // takes the low word of each dword (`66 8b 51 40`), which is a truncation no 1.12
-        // character can reach.
+        // The record holds `u16`s; the 1.12 client keeps each dword's low word (`0x5f08ea`).
         let power_type = fields.unit_power_type();
         self.cur_hp = Some(fields.unit_health().unwrap_or(0) as u16);
         self.max_hp = Some(fields.unit_max_health().unwrap_or(0) as u16);
@@ -287,31 +228,26 @@ impl PartyMemberStatsInfo {
         self.level = Some(fields.unit_level().unwrap_or(0) as u16);
     }
 
-    /// `UnitPowerType` on the record path — `+0x09`, `0` when the record has never carried one
-    /// (the binding's own miss value).
+    /// `UnitPowerType` from the record, 0 when it has none (the binding's miss value).
     pub fn shown_power_type(&self) -> u8 {
         self.power_type.unwrap_or(0)
     }
 
-    /// `UnitMana` on the record path (`0x517744`-`0x51775e`) — the stored power divided by
-    /// [`power_display_scale`], exactly as the live-object leg divides. Without it an out-of-range
-    /// warrior's rage bar reads ten times an in-range one's. Miss ⇒ `0`, the binding's own.
+    /// `UnitMana` from the record (`0x517744`): the stored power divided by
+    /// [`power_display_scale`], as for a live unit.
     pub fn shown_power(&self) -> u32 {
         u32::from(self.cur_power.unwrap_or(0))
             / power_display_scale(u32::from(self.shown_power_type()))
     }
 
-    /// `UnitManaMax` on the record path (`0x5178af`), the same divide.
+    /// `UnitManaMax` from the record (`0x5178af`), the same divide.
     pub fn shown_max_power(&self) -> u32 {
         u32::from(self.max_power.unwrap_or(0))
             / power_display_scale(u32::from(self.shown_power_type()))
     }
 }
 
-/// Read the aura tail shared by [`party_member_mask::AURAS`]/`PET_AURAS` (a `u32` bit mask) and
-/// `AURAS_NEGATIVE`/`PET_AURAS_NEGATIVE` (a `u16` bit mask, passed widened): one `u16` spell id per
-/// set bit, ascending bit order (VERIFIED `GroupHandler.cpp:624-630` positive, `634-644`
-/// negative/pet-negative shape).
+/// One `u16` spell id per set bit of `mask`, in bit order (`GroupHandler.cpp:624-644`).
 fn read_aura_spells(r: &mut impl Read, mask: u32, bits: u32) -> io::Result<Vec<u16>> {
     let mut spells = Vec::new();
     for bit in 0..bits {
@@ -322,9 +258,7 @@ fn read_aura_spells(r: &mut impl Read, mask: u32, bits: u32) -> io::Result<Vec<u
     Ok(spells)
 }
 
-/// Read one `SMSG_PARTY_MEMBER_STATS`/`_FULL` body → `(guid, info)` (see [`PartyMemberStatsInfo`]).
-/// The guid is PACKED (`GroupHandler.cpp:768`, `packet.guid.WriteAsPacked()` / `773`
-/// `player->GetPackGUID()` — both build-5875 branches, `SUPPORTED_CLIENT_BUILD > 1_8_4`).
+/// Read `SMSG_PARTY_MEMBER_STATS` or `_FULL`; the guid is packed (`GroupHandler.cpp:768`).
 pub(super) fn read_party_member_stats(
     r: &mut impl Read,
 ) -> io::Result<(u64, PartyMemberStatsInfo)> {
@@ -404,25 +338,20 @@ pub(super) fn read_party_member_stats(
     Ok((guid, info))
 }
 
-/// Read `MSG_MINIMAP_PING`, the inbound (rebroadcast) shape (VERIFIED vmangos
-/// `Handlers/GroupHandler.cpp:382-391`, `HandleMinimapPingOpcode`): full 8-byte `u64 guid` (the
-/// server stamps the pinger's own guid on), `f32 x`, `f32 y`.
+/// Read the relayed `MSG_MINIMAP_PING`: the pinger's guid, which the server adds, then x and y
+/// (`GroupHandler.cpp:382-391`).
 pub(super) fn read_minimap_ping(r: &mut impl Read) -> io::Result<(u64, f32, f32)> {
     Ok((read_u64_le(r)?, read_f32_le(r)?, read_f32_le(r)?))
 }
 
-/// One decoded `MSG_RAID_TARGET_UPDATE` server body (VERIFIED vmangos `Server/Packets/
-/// Group.cpp:132-147`, `RaidTargetUpdateDelta`/`RaidTargetUpdateAll::AppendBodyTo`): a leading `u8`
-/// mode byte picks the shape — `0` one changed icon, `1` the whole current icon set (only
-/// currently-set icons ride the list; none marked sends an empty list, not a fixed 8-slot array).
-/// Both shapes carry FULL 8-byte guids, not packed.
+/// A server `MSG_RAID_TARGET_UPDATE` (`Group.cpp:132-147`): mode 0 is one changed icon, mode 1
+/// every set icon, an empty list when none is.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum RaidTargetUpdate {
     Delta { icon: u8, guid: u64 },
     List(Vec<(u8, u64)>),
 }
 
-/// Read one `MSG_RAID_TARGET_UPDATE` server body (see [`RaidTargetUpdate`]).
 pub(super) fn read_raid_target_update(r: &mut &[u8]) -> io::Result<RaidTargetUpdate> {
     let mode = read_u8(r)?;
     if mode == 0 {
@@ -439,17 +368,14 @@ pub(super) fn read_raid_target_update(r: &mut &[u8]) -> io::Result<RaidTargetUpd
     }
 }
 
-/// One decoded `MSG_RAID_READY_CHECK` server body (VERIFIED vmangos `Server/Packets/
-/// Group.cpp:94-96` the empty request, `:126-130` the answer): empty = the leader just started a
-/// check; non-empty = one member's answer, forwarded to the leader only (`ObjectGuid senderGuid`
-/// FULL, not packed, + `u8 state`).
+/// A server `MSG_RAID_READY_CHECK`: empty when the leader starts a check, else one member's answer,
+/// sent to the leader only (`Group.cpp:94-96`, `126-130`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ReadyCheck {
     Started,
     Answer { guid: u64, ready: u8 },
 }
 
-/// Read one `MSG_RAID_READY_CHECK` server body (see [`ReadyCheck`]).
 pub(super) fn read_ready_check(r: &mut &[u8]) -> io::Result<ReadyCheck> {
     if r.is_empty() {
         return Ok(ReadyCheck::Started);
@@ -460,8 +386,7 @@ pub(super) fn read_ready_check(r: &mut &[u8]) -> io::Result<ReadyCheck> {
     })
 }
 
-/// Body of `CMSG_GROUP_INVITE` (VERIFIED vmangos `Group.cpp:4-7`,
-/// `GroupInvite::ReadFromWorldPacket`): one cstring, the invited player's name.
+/// `CMSG_GROUP_INVITE` body: the invitee's name (`Group.cpp:4-7`).
 pub fn group_invite(member_name: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(member_name.len() + 1);
     body.extend_from_slice(member_name.as_bytes());
@@ -469,20 +394,17 @@ pub fn group_invite(member_name: &str) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_GROUP_ACCEPT` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp` —
-/// `NullClientPacket`): empty.
+/// `CMSG_GROUP_ACCEPT` body: empty (vmangos `NullClientPacket`).
 pub fn group_accept() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GROUP_DECLINE` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp` —
-/// `NullClientPacket`): empty. The inviter sees `SMSG_GROUP_DECLINE`.
+/// `CMSG_GROUP_DECLINE` body: empty; the inviter gets `SMSG_GROUP_DECLINE`.
 pub fn group_decline() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GROUP_UNINVITE` (VERIFIED vmangos `Group.cpp:9-12`,
-/// `GroupUninvite::ReadFromWorldPacket`): one cstring, the kicked player's name.
+/// `CMSG_GROUP_UNINVITE` body: the kicked player's name (`Group.cpp:9-12`).
 pub fn group_uninvite(member_name: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(member_name.len() + 1);
     body.extend_from_slice(member_name.as_bytes());
@@ -490,23 +412,18 @@ pub fn group_uninvite(member_name: &str) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_GROUP_UNINVITE_GUID` (VERIFIED vmangos `Group.cpp:14-17`,
-/// `GroupUninviteGuid::ReadFromWorldPacket`): one full 8-byte guid — the raid-frame right-click kick.
+/// `CMSG_GROUP_UNINVITE_GUID` body, the raid frame's kick: a full guid (`Group.cpp:14-17`).
 pub fn group_uninvite_guid(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_GROUP_SET_LEADER` (VERIFIED vmangos `Group.h:102-113` + `Group.cpp:57-64`,
-/// `GroupSetLeader::ReadFromWorldPacket`, the `SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_11_2` branch
-/// active for 5875): one full 8-byte guid — the 1.12 wire dropped the older name-based form.
+/// `CMSG_GROUP_SET_LEADER` body: a full guid (`Group.cpp:57-64`, vmangos's post-1.11.2 branch).
 pub fn group_set_leader(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_LOOT_METHOD` (VERIFIED vmangos `Group.h:51-60` + `Group.cpp:26-31`,
-/// `LootMethod::ReadFromWorldPacket`): `u32 method` (`0` free-for-all, `1` round-robin, `2`
-/// master, `3` group, `4` need-before-greed), full 8-byte `u64 loot_master` guid (ignored unless
-/// `method == 2`), `u32 threshold` (an `ItemQualities` value, 2..4 in practice).
+/// `CMSG_LOOT_METHOD` body (`Group.cpp:26-31`): `u32` method, the master looter's full guid
+/// (ignored unless the method is 2), `u32` quality threshold.
 pub fn loot_method(method: u32, loot_master: u64, threshold: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&method.to_le_bytes());
@@ -515,28 +432,23 @@ pub fn loot_method(method: u32, loot_master: u64, threshold: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_GROUP_DISBAND` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp` —
-/// `NullClientPacket`): empty.
+/// `CMSG_GROUP_DISBAND` body: empty.
 pub fn group_disband() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GROUP_RAID_CONVERT` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp` —
-/// `NullClientPacket`): empty — converts the sender's party into a raid.
+/// `CMSG_GROUP_RAID_CONVERT` body: empty; turns the sender's party into a raid.
 pub fn group_raid_convert() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_REQUEST_PARTY_MEMBER_STATS` (VERIFIED vmangos `Group.h:41-49` + `Group.cpp:20-23`,
-/// `RequestPartyMemberStats::ReadFromWorldPacket`): one full 8-byte guid — the target whose stats
-/// we're asking for. Answered by `SMSG_PARTY_MEMBER_STATS_FULL` (or its offline-miss shape).
+/// `CMSG_REQUEST_PARTY_MEMBER_STATS` body: the member's full guid (`Group.cpp:20-23`); answered
+/// by `SMSG_PARTY_MEMBER_STATS_FULL`.
 pub fn request_party_member_stats(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_GROUP_CHANGE_SUB_GROUP` (VERIFIED vmangos `Group.cpp:45-49`,
-/// `GroupChangeSubGroup::ReadFromWorldPacket`): cstring member name + `u8` destination subgroup
-/// index — raid-only (a party has just one subgroup).
+/// `CMSG_GROUP_CHANGE_SUB_GROUP` body: a member's name, then the subgroup (`Group.cpp:45-49`).
 pub fn group_change_sub_group(name: &str, group_nr: u8) -> Vec<u8> {
     let mut body = Vec::with_capacity(name.len() + 2);
     body.extend_from_slice(name.as_bytes());
@@ -545,9 +457,7 @@ pub fn group_change_sub_group(name: &str, group_nr: u8) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_GROUP_SWAP_SUB_GROUP` (VERIFIED vmangos `Group.cpp:51-55`,
-/// `GroupSwapSubGroup::ReadFromWorldPacket`): two cstrings — the member to move, then the member
-/// whose subgroup slot it swaps into.
+/// `CMSG_GROUP_SWAP_SUB_GROUP` body: the two members' names, mover first (`Group.cpp:51-55`).
 pub fn group_swap_sub_group(name: &str, swap_with: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(name.len() + swap_with.len() + 2);
     body.extend_from_slice(name.as_bytes());
@@ -557,9 +467,8 @@ pub fn group_swap_sub_group(name: &str, swap_with: &str) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_GROUP_ASSISTANT_LEADER` (VERIFIED vmangos `Group.h:115-127` + `Group.cpp:66-74`,
-/// `GroupAssistantLeader::ReadFromWorldPacket`, the 1.12 guid branch): full 8-byte guid + `u8 flag`
-/// (`1` grant raid-assistant, `0` revoke).
+/// `CMSG_GROUP_ASSISTANT_LEADER` body: a full guid, then 1 to grant raid assistant or 0 to revoke
+/// it (`Group.cpp:66-74`).
 pub fn group_assistant_leader(guid: u64, grant: bool) -> Vec<u8> {
     let mut body = Vec::with_capacity(9);
     body.extend_from_slice(&guid.to_le_bytes());
@@ -567,9 +476,7 @@ pub fn group_assistant_leader(guid: u64, grant: bool) -> Vec<u8> {
     body
 }
 
-/// Body of `MSG_MINIMAP_PING`, our own ping (VERIFIED vmangos `Group.cpp:33-37`,
-/// `MinimapPing::ReadFromWorldPacket`): `f32 x, f32 y` — no guid (the server stamps ours on before
-/// relaying, `Handlers/GroupHandler.cpp:382-391`).
+/// Our `MSG_MINIMAP_PING` body: x and y, no guid (`Group.cpp:33-37`).
 pub fn minimap_ping(x: f32, y: f32) -> Vec<u8> {
     let mut body = Vec::with_capacity(8);
     body.extend_from_slice(&x.to_le_bytes());
@@ -577,10 +484,8 @@ pub fn minimap_ping(x: f32, y: f32) -> Vec<u8> {
     body
 }
 
-/// Body of `MSG_RAID_TARGET_UPDATE`, setting/clearing one icon (VERIFIED vmangos
-/// `Group.cpp:77-82`, `RaidTargetUpdate::ReadFromWorldPacket`): `u8 icon` (0..7) + full 8-byte
-/// `u64 guid` — `guid == 0` clears that icon. The client never sends the server's mode byte
-/// (compare [`RaidTargetUpdate`]); [`raid_target_request`] disambiguates purely by icon value.
+/// `MSG_RAID_TARGET_UPDATE` body: icon 0 to 7, then a full guid, 0 to clear; the client sends no
+/// mode byte (`Group.cpp:77-82`).
 pub fn raid_target_set(icon: u8, guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(9);
     body.push(icon);
@@ -588,53 +493,36 @@ pub fn raid_target_set(icon: u8, guid: u64) -> Vec<u8> {
     body
 }
 
-/// Body of `MSG_RAID_TARGET_UPDATE`, asking the current icon set (VERIFIED vmangos
-/// `Group.cpp:80-81`: `iconId != 0xFF` gates the trailing guid read): the single byte `0xFF` — no
-/// guid follows. Answered by the server's mode-1 full list ([`RaidTargetUpdate::List`]).
+/// `MSG_RAID_TARGET_UPDATE` body asking for every icon: `0xFF` alone, no guid (`Group.cpp:80-81`).
 pub fn raid_target_request() -> Vec<u8> {
     vec![0xFF]
 }
 
-/// Body of `MSG_RAID_READY_CHECK`, starting a check (VERIFIED vmangos
-/// `RaidReadyCheckFromClient::ReadFromWorldPacket`, `Group.cpp:84-92`, the `state` unset case):
-/// empty — the leader-only trigger; the server broadcasts the request to the rest of the raid.
+/// `MSG_RAID_READY_CHECK` body starting a check: empty (`Group.cpp:84-92`).
 pub fn ready_check_start() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `MSG_RAID_READY_CHECK`, answering one (VERIFIED vmangos `Group.cpp:84-92`, the `state`
-/// set case): one `u8`, `1` ready / `0` not — no guid; the server already knows the sender from
-/// the session and forwards it to the raid leader alone.
+/// `MSG_RAID_READY_CHECK` body answering one: 1 ready or 0 not, no guid (`Group.cpp:84-92`).
 pub fn ready_check_answer(ready: bool) -> Vec<u8> {
     vec![u8::from(ready)]
 }
 
-/// One row of `SMSG_RAID_INSTANCE_INFO` — a raid lockout the character is bound to (VERIFIED
-/// vmangos `Objects/Player.cpp::Player::SendRaidInfo`: the writer walks `m_boundInstances` and
-/// emits a row for every **permanent** bind, so a heroic-style temporary bind never appears).
-///
-/// `reset` is a REMAINING duration in seconds (`resetTime - time(nullptr)` on the server), not an
-/// absolute timestamp — the Lua binding hands it straight to `SecondsToTime`, and reading it as a
-/// timestamp would print "Resets in 57 years".
+/// One `SMSG_RAID_INSTANCE_INFO` row, a permanent raid lockout (vmangos `Player::SendRaidInfo`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct RaidInstanceEntry {
-    /// `Map.dbc` id — the *name* the UI shows is the client's own DBC lookup, never on the wire.
+    /// `Map.dbc` id; the name shown is the client's own lookup.
     pub map: u32,
     /// Seconds until the lockout resets.
     pub reset: u32,
-    /// The instance id, which is what the UI shows beside the name (`GetSavedInstanceInfo`'s
-    /// second return).
+    /// The instance id, `GetSavedInstanceInfo`'s second return.
     pub instance: u32,
 }
 
-/// Read an `SMSG_RAID_INSTANCE_INFO` body (see [`RaidInstanceEntry`]): `u32 count` then that many
-/// 12-byte rows. The count is authoritative — the server writes it back over its placeholder — so
-/// a short body is a malformed packet rather than a silent truncation.
+/// Read `SMSG_RAID_INSTANCE_INFO`; the count is authoritative, so a short body is an error.
 pub(super) fn read_raid_instance_info(r: &mut &[u8]) -> io::Result<Vec<RaidInstanceEntry>> {
     let count = read_u32_le(r)?;
-    // A cap before the allocation: `count` is attacker-controlled in the general case, and the
-    // real client's own list is `MAX_RAID_INFOS`-bounded at the UI. 1024 is far above anything a
-    // server can legitimately send and far below a memory problem.
+    // 1024 caps the preallocation far above any real lockout list.
     let mut out = Vec::with_capacity(capacity_hint(count, 1024));
     for _ in 0..count {
         out.push(RaidInstanceEntry {
@@ -646,8 +534,7 @@ pub(super) fn read_raid_instance_info(r: &mut &[u8]) -> io::Result<Vec<RaidInsta
     Ok(out)
 }
 
-/// Body of `CMSG_REQUEST_RAID_INFO` (VERIFIED vmangos `Handlers/GroupHandler.cpp`'s
-/// `HandleRequestRaidInfoOpcode` — the handler reads nothing and answers `SendRaidInfo()`): empty.
+/// `CMSG_REQUEST_RAID_INFO` body: empty (vmangos `HandleRequestRaidInfoOpcode`).
 pub fn request_raid_info() -> Vec<u8> {
     Vec::new()
 }
diff --git a/crates/benilla-protocol/src/messages/guild.rs b/crates/benilla-protocol/src/messages/guild.rs
index 3e054f19..0bbc5183 100644
--- a/crates/benilla-protocol/src/messages/guild.rs
+++ b/crates/benilla-protocol/src/messages/guild.rs
@@ -1,100 +1,49 @@
-//! The guild family — the roster, the guild query, invitations, rank administration and the event
-//! broadcast (opcodes `0x54`/`0x55`, `0x81`–`0x93`, `0x231`–`0x235`, `0x2FC`).
+//! The guild wire messages: roster, guild query, invitations, rank administration and the event
+//! broadcast (opcodes `0x54`/`0x55`, `0x81`-`0x93`, `0x231`-`0x235`, `0x2FC`).
 //!
-//! The server side is pinned at the bytes by vmangos `Server/Packets/Guild.{h,cpp}` (every
-//! `ReadFromWorldPacket` / `AppendBodyTo`), `Guild/Guild.{h,cpp}` (`SendGuildRoster`,
-//! `SendQueryResponse`, `BroadcastEvent`, and the enums) and `Handlers/GuildHandler.cpp` (which
-//! `NullClientPacket` handlers take an empty body).
-//!
-//! The client side of `SMSG_GUILD_EVENT` is VERIFIED in wow-re
-//! (`system/object-layer/scratch/rf77-smsg-chat-wire-order.md`, RF-0077 corrected): opcode `0x92`
-//! registers handler `0x5e7180` (`0x5e337a mov ecx,0x92; call 0x5ab650`), which reads `u8
-//! eventType`, `u8 strCount` (≤ 3 — three stack buffers), `strCount` × CString, and then — **only**
-//! in the `0xc`/`0xd` arms of its `switch` (jump table `0x5e74dc`) — a trailing `u64` guid via
-//! `0x4190b0`. That is the read [`read_guild_event`] implements, and it is *narrower* than what
-//! vmangos writes (see that function's doc).
-//!
-//! The client side of `SMSG_GUILD_ROSTER` and `SMSG_GUILD_QUERY_RESPONSE` is likewise VERIFIED in
-//! wow-re (`system/ui/scratch/guild-roster-wire.md`), by a §5 trio deriving each independently.
-//! The two do **not** live in the guild-init block the event handler does: `0x8a` is handler
-//! `0x4d0ad0` (registered `0x4d0a0e`) in a **`GuildInfo.cpp`** TU, and `0x55` is `0x555290`
-//! (registered `0x555073`) in **dbcache**, delegating to decoder `0x62f260` — which wow-re already
-//! held bit-exact as `PRIMITIVE:dbcache_guild`. Per-field addresses are on the two readers below.
-//!
-//! **The parse trap in this family is `SMSG_GUILD_ROSTER`'s `f32 lastOnlineTime`**: it rides on the
-//! member's presence byte, so reading it unconditionally desynchronises every *later* member —
-//! exactly the shape [`super::social::read_friend_status`] already has, and written the same way
-//! (an explicit condition on the field the wire keys off, never a "read if bytes remain").
-//!
-//! **One reference behaviour we deliberately do not reproduce: capped string reads.** The client's
-//! `0x4191b0` takes a per-field capacity (counting the NUL, so the real cap is `cap - 1`) — roster
-//! name `0x30`, notes `0x80`, motd `0x200`, info text `0x7d0`, query guild name `0x60`, rank name
-//! `0x40`. On overflow it does not truncate gracefully: it slams the cursor to `size + 1`
-//! (`0x4192aa`) and NULs `dest[0]` (`0x4192be`), so the field arrives **empty** *and every later
-//! read in that packet silently no-ops*. [`read_cstring`] is unbounded, which is strictly safer and
-//! cannot poison a packet — and it costs no fidelity, because every one of those caps is far above
-//! the content limit the server enforces (a 15-character rank name into a 64-byte buffer, a
-//! 128-character MOTD into 512). The caps are recorded here because they explain a class of
-//! "the guild pane went blank" behaviour in the reference, not because we want them.
+//! Deviation: string reads are unbounded. The reference `0x4191b0` caps each field, counting the
+//! NUL (roster name `0x30`, notes `0x80`, MOTD `0x200`, info `0x7d0`, guild name `0x60`, rank name
+//! `0x40`), and on overflow empties it and no-ops every later read in the packet; every cap is far
+//! above the server's own length limits, so a legitimate packet reads the same.
 
 use std::io::{self, Read};
 
 use crate::wire::{capacity_hint, read_cstring, read_f32_le, read_u32_le, read_u64_le, read_u8};
 
-/// A guild always has at least this many ranks — vmangos `GUILD_RANKS_MIN_COUNT` (`Guild/Guild.h:31`);
-/// the five defaults are GM / Officer / Veteran / Member / Initiate ([`guild_default_rank`]).
+/// Minimum rank count: the five defaults in [`guild_default_rank`] (`Guild/Guild.h:31`).
 pub const GUILD_RANKS_MIN_COUNT: usize = 5;
-/// …and at most this many — vmangos `GUILD_RANKS_MAX_COUNT` (`Guild/Guild.h:32`). Load-bearing for
-/// the parse, not just a policy number: `SMSG_GUILD_QUERY_RESPONSE` always carries **exactly**
-/// this many rank-name cstrings, padding unused ranks with empty strings
-/// (`Guild/Guild.cpp:868-872`, whose own comment is "show always 10 ranks").
+/// Maximum rank count (`Guild/Guild.h:32`), and the exact number of rank names
+/// `SMSG_GUILD_QUERY_RESPONSE` carries, unused ones empty (`Guild/Guild.cpp:868-872`).
 pub const GUILD_RANKS_MAX_COUNT: usize = 10;
 
-/// Rank-name cap, in *characters* — vmangos `GUILD_RANK_MAX_LENGTH` (`Guild/Guild.h:36`).
-///
-/// These five caps are the reference UI's edit-box `maxLetters`, and vmangos re-checks the three
-/// it can (`utf8length`, not byte length). Over-long is **not** a polite refusal on the rank ones:
-/// `HandleGuildRankOpcode` / `HandleGuildAddRankOpcode` (`Handlers/GuildHandler.cpp:580-584`,
-/// `:600-604`) run `ProcessAnticheatAction(… CHEAT_ACTION_KICK)`. The builders below do **not**
-/// truncate — silently shortening a rank name or a note would send the wrong text, which is its
-/// own bug — so the caller enforces the cap at the edit box, as the reference UI does.
+/// Rank-name cap in characters (`Guild/Guild.h:36`). The builders do not truncate, and an
+/// over-long rank name gets the session kicked (`Handlers/GuildHandler.cpp:580-584`, `:600-604`).
 pub const GUILD_RANK_MAX_LENGTH: usize = 15;
-/// Guild-name cap, in characters — vmangos `GUILD_NAME_MAX_LENGTH` (`Guild/Guild.h:37`).
+/// Guild-name cap, in characters (`Guild/Guild.h:37`).
 pub const GUILD_NAME_MAX_LENGTH: usize = 24;
-/// Public/officer note cap, in characters — vmangos `GUILD_NOTE_MAX_LENGTH` (`Guild/Guild.h:38`).
+/// Public/officer note cap, in characters (`Guild/Guild.h:38`).
 pub const GUILD_NOTE_MAX_LENGTH: usize = 31;
-/// Guild info text cap, in characters — vmangos `GUILD_INFO_MAX_LENGTH` (`Guild/Guild.h:39`).
+/// Guild info text cap, in characters (`Guild/Guild.h:39`).
 pub const GUILD_INFO_MAX_LENGTH: usize = 500;
-/// MOTD cap, in characters — vmangos `GUILD_MOTD_MAX_LENGTH` (`Guild/Guild.h:40`).
+/// MOTD cap, in characters (`Guild/Guild.h:40`).
 pub const GUILD_MOTD_MAX_LENGTH: usize = 128;
 
-/// The five ranks every guild is created with and cannot delete — vmangos `GuildDefaultRanks`
-/// (`Guild/Guild.h:44-54`). Rank ids are **0-based with 0 = guild master**, and the ordering is the
-/// authority hierarchy: promote does `rank--`, demote does `rank++` (vmangos's own comments).
+/// The five ranks every guild is created with and cannot delete (`Guild/Guild.h:44-54`). Ids are
+/// 0-based with 0 = guild master; promote does `rank--`, demote `rank++`.
 pub mod guild_default_rank {
-    /// `GR_GUILDMASTER` — rank 0. `HandleGuildRankOpcode` force-overwrites this rank's rights with
-    /// `GR_RIGHT_ALL` whatever the client sends, "to prevent loss of leader rights".
+    /// `GR_GUILDMASTER`; the server forces this rank's rights to `GR_RIGHT_ALL` whatever we send.
     pub const GUILDMASTER: u32 = 0;
-    /// `GR_OFFICER`.
     pub const OFFICER: u32 = 1;
-    /// `GR_VETERAN`.
     pub const VETERAN: u32 = 2;
-    /// `GR_MEMBER`.
     pub const MEMBER: u32 = 3;
-    /// `GR_INITIATE` — the lowest default rank.
+    /// `GR_INITIATE`, the lowest default rank.
     pub const INITIATE: u32 = 4;
 }
 
-/// One rank's rights bitmask — vmangos `GuildRankRights` (`Guild/Guild.h:56-74`), **with
-/// `GR_RIGHT_EMPTY` factored out**.
-///
-/// vmangos writes every named right as `GR_RIGHT_EMPTY | bit` (`GR_RIGHT_GCHATLISTEN = 0x41`,
-/// not `0x01`) because its test is `(rights & right) != GR_RIGHT_EMPTY` — the `0x40` is a sentinel
-/// that makes that comparison work, not a right. The meaningful bit is the other half, and that is
-/// what is named here; [`EMPTY`] is kept so the vmangos constants can be reconstructed and
-/// recognised.
+/// One rank's rights bitmask (`Guild/Guild.h:56-74`) with the `GR_RIGHT_EMPTY` bit factored out:
+/// vmangos spells each right `0x40 | bit` for its test `(rights & right) != GR_RIGHT_EMPTY`.
 pub mod guild_rank_right {
-    /// `GR_RIGHT_EMPTY` (`0x40`) — the sentinel described in the module doc. Carries no permission.
+    /// `GR_RIGHT_EMPTY`, the sentinel vmangos ORs into every right; it grants nothing.
     pub const EMPTY: u32 = 0x0000_0040;
     /// Read guild chat (`GR_RIGHT_GCHATLISTEN`, vmangos `0x41`).
     pub const GCHAT_LISTEN: u32 = 0x0000_0001;
@@ -116,27 +65,21 @@ pub mod guild_rank_right {
     pub const SET_MOTD: u32 = 0x0000_1000;
     /// Edit any member's public note (`GR_RIGHT_EPNOTE`, vmangos `0x2040`).
     pub const EDIT_PUBLIC_NOTE: u32 = 0x0000_2000;
-    /// **See** officer notes at all (`GR_RIGHT_VIEWOFFNOTE`, vmangos `0x4040`). Without it the
-    /// server blanks every `officerNote` in the roster it sends us
-    /// (`Guild/Guild.cpp:821`, `:844`) — the empty string is a *permission* signal, not "no note".
+    /// See officer notes (`GR_RIGHT_VIEWOFFNOTE`, vmangos `0x4040`); without it the server blanks
+    /// every roster `officerNote` (`Guild/Guild.cpp:821`, `:844`).
     pub const VIEW_OFFICER_NOTE: u32 = 0x0000_4000;
     /// Edit officer notes (`GR_RIGHT_EOFFNOTE`, vmangos `0x8040`).
     pub const EDIT_OFFICER_NOTE: u32 = 0x0000_8000;
     /// Edit the guild information text (`GR_RIGHT_MODIFY_GUILD_INFO`, vmangos `0x10040`).
     pub const MODIFY_GUILD_INFO: u32 = 0x0001_0000;
-    /// `GR_RIGHT_ALL` — what the server force-writes onto rank 0 regardless of what we send.
-    /// Unlike the named rights above, this is a **raw wire value, sentinel and all**: it includes
-    /// [`EMPTY`], and it lights bits (`0x0000_0E00`, `0x000E_0000`) that no 1.12 right owns. Test
-    /// a rank against the named bits, never against this.
+    /// `GR_RIGHT_ALL`, forced onto rank 0 by the server. A raw vmangos value: it includes
+    /// [`EMPTY`] and bits no 1.12 right owns, so test ranks against the named bits, never this.
     pub const ALL: u32 = 0x000F_F1FF;
 }
 
-/// The thirteen rank-right checkboxes **in the order the FrameXML API indexes them**.
-///
-/// `GuildControlGetRankFlags()` returns a flat list and `GuildControlSetRankFlag(i, on)` takes an
-/// index into it, so **index order is the API contract** — and it is deliberately *not* bit order:
-/// Promote/Demote (indices 5/6 here) sit above Invite/Remove (7/8) in bit value. Anything that
-/// computes the bit as `1 << (i - 1)` is wrong; this table is the mapping.
+/// The thirteen rank-right checkboxes in the order `GuildControlGetRankFlags()` and
+/// `GuildControlSetRankFlag(i, on)` index them, which is not bit order: Promote/Demote (5/6) come
+/// before Invite/Remove (7/8), whose bits are lower.
 pub const GUILD_RANK_RIGHT_ORDER: [u32; 13] = [
     guild_rank_right::GCHAT_LISTEN,
     guild_rank_right::GCHAT_SPEAK,
@@ -153,104 +96,81 @@ pub const GUILD_RANK_RIGHT_ORDER: [u32; 13] = [
     guild_rank_right::MODIFY_GUILD_INFO,
 ];
 
-/// A roster member's presence byte — vmangos `GuildRosterPresenceFlags` (`Guild/Guild.h:139-144`).
-///
-/// `0` (no bit at all) is the only value the wire treats specially: it is what makes the member's
-/// `f32 lastOnlineTime` present. The AFK/DND bits ride alongside `ONLINE`, exactly as the friend
-/// list's [`super::social::friend_status`] does.
-///
-/// The reference client tests these as its own chat flags, and **DND is tested first**
-/// (`0x4d13e4` before `0x4d13fb`, wow-re `system/ui/scratch/guild-roster-wire.md`) — so a member
-/// flagged both AFK and DND displays as DND. That precedence is a display rule, not a wire rule,
-/// but it belongs with the bits.
+/// A roster member's presence byte (`Guild/Guild.h:139-144`); only `0` changes the wire, adding
+/// the `f32 lastOnlineTime`. The reference tests DND before AFK (`0x4d13e4`, `0x4d13fb`), so a
+/// member flagged both shows as DND.
 pub mod guild_presence {
-    /// Offline — and **only** this value carries the `lastOnlineTime` float.
+    /// Offline; only this value carries the `lastOnlineTime` float.
     pub const OFFLINE: u8 = 0x00;
-    /// `GRF_ONLINE`. Value INFERRED from vmangos: the reference client only ever tests the whole
-    /// byte against zero, so nothing in the binary pins this bit specifically.
+    /// `GRF_ONLINE` (vmangos value; the reference only tests the whole byte against zero).
     pub const ONLINE: u8 = 0x01;
-    /// `GRF_AFK` — set alongside [`ONLINE`]. VERIFIED as the client's own `CHAT_FLAG_AFK`.
+    /// `GRF_AFK`, set alongside [`ONLINE`]; the reference's own `CHAT_FLAG_AFK`.
     pub const AFK: u8 = 0x02;
-    /// `GRF_DND` — set alongside [`ONLINE`]. VERIFIED as the client's own `CHAT_FLAG_DND`, and
-    /// tested ahead of [`AFK`].
+    /// `GRF_DND`, set alongside [`ONLINE`]; the reference's own `CHAT_FLAG_DND`.
     pub const DND: u8 = 0x04;
 }
 
-/// `SMSG_GUILD_EVENT`'s leading byte — vmangos `GuildEvents` (`Guild/Guild.h:121-137`), which is
-/// also the reference client's own `switch` (14 arms, jump table `0x5e74dc`; wow-re RF-0077).
+/// `SMSG_GUILD_EVENT`'s leading byte (`Guild/Guild.h:121-137`), the arms of the reference
+/// handler's `switch` (jump table `0x5e74dc`).
 pub mod guild_event {
-    /// `GE_PROMOTION` — params: promoter, promoted, new rank name.
+    /// `GE_PROMOTION`, params: promoter, promoted, new rank name.
     pub const PROMOTION: u8 = 0x00;
-    /// `GE_DEMOTION` — params: demoter, demoted, new rank name.
+    /// `GE_DEMOTION`, params: demoter, demoted, new rank name.
     pub const DEMOTION: u8 = 0x01;
-    /// `GE_MOTD` — param: the new message of the day. The reference client routes this one
-    /// through the profanity filter (`0x703f50(0x11c,…)`, CVar-gated), not the normal event path.
+    /// `GE_MOTD`, param: the new MOTD. The reference routes it through the CVar-gated profanity
+    /// filter (`0x703f50`), not the normal event path.
     pub const MOTD: u8 = 0x02;
-    /// `GE_JOINED` — param: the joiner's name.
+    /// `GE_JOINED`, param: the joiner's name.
     pub const JOINED: u8 = 0x03;
-    /// `GE_LEFT` — param: the leaver's name.
+    /// `GE_LEFT`, param: the leaver's name.
     pub const LEFT: u8 = 0x04;
-    /// `GE_REMOVED` — params: the removed player, then who removed them.
+    /// `GE_REMOVED`, params: the removed player, then who removed them.
     pub const REMOVED: u8 = 0x05;
-    /// `GE_LEADER_IS` — param: the current leader.
+    /// `GE_LEADER_IS`, param: the current leader.
     pub const LEADER_IS: u8 = 0x06;
-    /// `GE_LEADER_CHANGED` — params: old leader, new leader.
+    /// `GE_LEADER_CHANGED`, params: old leader, new leader.
     pub const LEADER_CHANGED: u8 = 0x07;
-    /// `GE_DISBANDED` — no params.
+    /// `GE_DISBANDED`, no params.
     pub const DISBANDED: u8 = 0x08;
-    /// `GE_TABARDCHANGE`. The reference client falls through to its default arm for this one.
+    /// `GE_TABARDCHANGE`; the reference handles it in its default arm.
     pub const TABARD_CHANGE: u8 = 0x09;
-    /// `GE_UPDATE_RANK_NAME` — params: rank id, new rank name. The reference client writes it
-    /// straight into the roster cache (`0x560e30`) and fires **no** FrameScript event.
+    /// `GE_UPDATE_RANK_NAME`, params: rank id, new rank name. The reference writes it into the
+    /// roster cache (`0x560e30`) and fires no FrameScript event.
     pub const UPDATE_RANK_NAME: u8 = 0x0A;
-    /// `GE_UPDATE_ROSTER` — "re-ask for the roster". Silent in the reference client; vmangos never
-    /// sends it (it re-sends the whole `SMSG_GUILD_ROSTER` instead).
+    /// `GE_UPDATE_ROSTER`: silent in the reference, and vmangos never sends it.
     pub const UPDATE_ROSTER: u8 = 0x0B;
-    /// `GE_SIGNED_ON` — param: the guildmate's name. **Carries the trailing guid.**
+    /// `GE_SIGNED_ON`, param: the guildmate's name; carries the trailing guid.
     pub const SIGNED_ON: u8 = 0x0C;
-    /// `GE_SIGNED_OFF` — param: the guildmate's name. **Carries the trailing guid.**
+    /// `GE_SIGNED_OFF`, param: the guildmate's name; carries the trailing guid.
     pub const SIGNED_OFF: u8 = 0x0D;
 }
 
-/// `SMSG_GUILD_COMMAND_RESULT`'s leading `u32` — which *verb* the result is about (vmangos
-/// `Typecommand`, `Guild/Guild.h:76-85`).
-///
-/// It is a much coarser tag than the opcode that provoked it: vmangos answers "you're not in a
-/// guild" to `CMSG_GUILD_INFO`, `_ROSTER`, `_LEAVE`, `_DISBAND` and half a dozen others all as
-/// [`CREATE`], and every permission refusal as [`INVITE`]. So the pair
-/// `(command, result)` names the *message*, not the request — vmangos's own comment notes that
-/// values 2, 4-13 and 15-18 "have no effect" here.
+/// `SMSG_GUILD_COMMAND_RESULT`'s leading `u32`, the verb the result is about
+/// (`Guild/Guild.h:76-85`). Coarser than the request: vmangos reports "not in a guild" for most
+/// verbs as [`CREATE`] and every permission refusal as [`INVITE`].
 pub mod guild_command {
-    /// `GUILD_CREATE_S` — also vmangos's catch-all for "you are not in a guild".
+    /// `GUILD_CREATE_S`, also vmangos's catch-all for "you are not in a guild".
     pub const CREATE: u32 = 0x00;
-    /// `GUILD_INVITE_S` — also vmangos's catch-all for a permission refusal.
+    /// `GUILD_INVITE_S`, also vmangos's catch-all for a permission refusal.
     pub const INVITE: u32 = 0x01;
-    /// `GUILD_QUIT_S` — leaving/being removed.
+    /// `GUILD_QUIT_S`: leaving or being removed.
     pub const QUIT: u32 = 0x03;
-    /// `GUILD_FOUNDER_S`.
     pub const FOUNDER: u32 = 0x0E;
-    /// `GUILD_UNK19`.
     pub const UNK19: u32 = 0x13;
-    /// `GUILD_UNK20`.
     pub const UNK20: u32 = 0x14;
 }
 
-/// `SMSG_GUILD_COMMAND_RESULT`'s trailing `u32` — vmangos `CommandErrors`
-/// (`Guild/Guild.h:96-119`). The string field between the two carries whatever `%s` the matching
-/// `ERR_GUILD_*` GlobalString needs (a player name, a guild name, or empty).
-///
-/// Note [`LEADER_LEAVE`] and [`PERMISSIONS`] are the **same** value `0x08`: which one it means is
-/// decided by the [`guild_command`] tag beside it (`QUIT` → the leader-can't-leave message,
-/// anything else → the permission refusal). That collision is the reason the command tag has to be
-/// carried through to the consumer rather than dropped.
+/// `SMSG_GUILD_COMMAND_RESULT`'s trailing `u32` (`Guild/Guild.h:96-119`). [`LEADER_LEAVE`] and
+/// [`PERMISSIONS`] share `0x08`: with command `QUIT` it is the leader-cannot-leave message,
+/// otherwise the permission refusal.
 pub mod guild_command_error {
-    /// `ERR_PLAYER_NO_MORE_IN_GUILD` — vmangos's own comment: "no message/error".
+    /// `ERR_PLAYER_NO_MORE_IN_GUILD`: "no message/error" per vmangos.
     pub const PLAYER_NO_MORE_IN_GUILD: u32 = 0x00;
     /// `ERR_GUILD_INTERNAL`.
     pub const INTERNAL: u32 = 0x01;
-    /// `ERR_ALREADY_IN_GUILD` — *you* are.
+    /// `ERR_ALREADY_IN_GUILD`: you are.
     pub const ALREADY_IN_GUILD: u32 = 0x02;
-    /// `ERR_ALREADY_IN_GUILD_S` — *they* are (the string names them).
+    /// `ERR_ALREADY_IN_GUILD_S`: they are (the string names them).
     pub const ALREADY_IN_GUILD_S: u32 = 0x03;
     /// `ERR_INVITED_TO_GUILD`.
     pub const INVITED_TO_GUILD: u32 = 0x04;
@@ -260,18 +180,17 @@ pub mod guild_command_error {
     pub const NAME_INVALID: u32 = 0x06;
     /// `ERR_GUILD_NAME_EXISTS_S`.
     pub const NAME_EXISTS_S: u32 = 0x07;
-    /// `ERR_GUILD_LEADER_LEAVE` — the guild master cannot `/gquit` while anyone else remains.
-    /// Same value as [`PERMISSIONS`]; disambiguated by [`guild_command::QUIT`].
+    /// `ERR_GUILD_LEADER_LEAVE`: the guild master cannot `/gquit` while anyone else remains.
     pub const LEADER_LEAVE: u32 = 0x08;
-    /// `ERR_GUILD_PERMISSIONS` — see [`LEADER_LEAVE`].
+    /// `ERR_GUILD_PERMISSIONS`, sharing `0x08` with [`LEADER_LEAVE`].
     pub const PERMISSIONS: u32 = 0x08;
-    /// `ERR_GUILD_PLAYER_NOT_IN_GUILD` — *you* aren't.
+    /// `ERR_GUILD_PLAYER_NOT_IN_GUILD`: you aren't.
     pub const PLAYER_NOT_IN_GUILD: u32 = 0x09;
-    /// `ERR_GUILD_PLAYER_NOT_IN_GUILD_S` — *they* aren't.
+    /// `ERR_GUILD_PLAYER_NOT_IN_GUILD_S`: they aren't.
     pub const PLAYER_NOT_IN_GUILD_S: u32 = 0x0A;
     /// `ERR_GUILD_PLAYER_NOT_FOUND_S`.
     pub const PLAYER_NOT_FOUND_S: u32 = 0x0B;
-    /// `ERR_GUILD_NOT_ALLIED` — cross-faction, refused by config.
+    /// `ERR_GUILD_NOT_ALLIED`: cross-faction, refused by config.
     pub const NOT_ALLIED: u32 = 0x0C;
     /// `ERR_GUILD_RANK_TOO_HIGH_S`.
     pub const RANK_TOO_HIGH_S: u32 = 0x0D;
@@ -279,46 +198,30 @@ pub mod guild_command_error {
     pub const RANK_TOO_LOW_S: u32 = 0x0E;
     /// `ERR_GUILD_RANKS_LOCKED` (`0x0F`/`0x10` are unused at 5875).
     pub const RANKS_LOCKED: u32 = 0x11;
-    /// `ERR_GUILD_RANK_IN_USE` — can't delete the lowest rank while somebody holds it.
+    /// `ERR_GUILD_RANK_IN_USE`: the lowest rank cannot be deleted while somebody holds it.
     pub const RANK_IN_USE: u32 = 0x12;
     /// `ERR_GUILD_IGNORING_YOU_S`.
     pub const IGNORING_YOU_S: u32 = 0x13;
-    /// `ERR_GUILD_UNK20` — vmangos: "for Typecommand 0x05 only".
+    /// `ERR_GUILD_UNK20`: "for Typecommand 0x05 only" per vmangos.
     pub const UNK20: u32 = 0x14;
 }
 
-/// `SMSG_GUILD_QUERY_RESPONSE` — one guild's public identity: its name, its ten rank names, and
-/// its tabard.
-///
-/// This is an ask-once cache fill, the guild twin of the name query: the roster and every chat
-/// line reference a guild by id, and this is what turns that id into text.
+/// `SMSG_GUILD_QUERY_RESPONSE`: one guild's name, ten rank names and tabard, by guild id.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct GuildQueryResponse {
     /// The guild id we asked about.
     pub guild_id: u32,
-    /// The guild's name — and, **empty, the "no such guild" answer**. The reference client tests
-    /// exactly this (`0x5552ae test al,al` on the decoded record's name, choosing the cache
-    /// *insert* `0x561070` or the cache *remove* `0x561390`); there is no separate not-found flag,
-    /// and the full record is consumed either way. A consumer must therefore treat an empty name
-    /// as "this id names nothing", not as "a guild with a blank name".
+    /// The guild's name; empty means no such guild, and the reference then drops the id from its
+    /// cache instead of inserting it (`0x5552ae`).
     pub name: String,
-    /// **Always exactly [`GUILD_RANKS_MAX_COUNT`] entries**, indexed by rank id (0 = guild
-    /// master); ranks the guild has not created are empty strings, not absent. A guild has between
-    /// [`GUILD_RANKS_MIN_COUNT`] and [`GUILD_RANKS_MAX_COUNT`] real ranks, so the tail of this
-    /// array is normally empty — "how many ranks exist" is the count of leading non-empty entries,
-    /// or better, the roster's `rank_rights` length.
+    /// Indexed by rank id, uncreated ranks empty; the live rank count is the roster's
+    /// `rank_rights` length.
     pub rank_names: [String; GUILD_RANKS_MAX_COUNT],
-    /// Tabard emblem symbol index — the file index the body composite formats into
-    /// `Textures\GuildEmblems\Emblem_<style>_<color>_…` (decision 1704).
-    ///
-    /// **Signed, and `-1` is the common case.** These five are `int32` on the wire (vmangos
-    /// `Server/Packets/Guild.h:208`), a guild is *constructed* with all five at `-1`
-    /// (`Guild/Guild.cpp:86`) and reloaded with `GetInt32()` (`:308`), and only the tabard designer
-    /// ever writes a real index. So "this guild has never bought a tabard" arrives as `-1`, not as
-    /// `0` — decoding these unsigned would turn that into 4294967295 and lose the one value that is
-    /// not a file index. What the renderer does with it is 1704's business, not the decoder's.
+    /// Tabard emblem index, formatted into `Textures\GuildEmblems\Emblem_<style>_<color>_…`. All
+    /// five tabard fields are `int32` (`Server/Packets/Guild.h:208`) and a new guild has each at
+    /// `-1` (`Guild/Guild.cpp:86`), meaning no tabard designed.
     pub emblem_style: i32,
-    /// Tabard emblem colour index. Signed, `-1` = no tabard designed — see [`Self::emblem_style`].
+    /// Tabard emblem colour index. Signed, `-1` = no tabard designed.
     pub emblem_color: i32,
     /// Tabard border style index. Signed, `-1` = no tabard designed.
     pub border_style: i32,
@@ -328,21 +231,8 @@ pub struct GuildQueryResponse {
     pub background_color: i32,
 }
 
-/// Read `SMSG_GUILD_QUERY_RESPONSE` (VERIFIED **both ends**): `u32 guildId`, the guild name, then
-/// **exactly ten** rank-name cstrings, then the five tabard `i32`s (signed — see
-/// [`GuildQueryResponse::emblem_style`] for why the sign is load-bearing).
-///
-/// Server: vmangos `Server/Packets/Guild.cpp:118-131` `GuildQueryResponse::AppendBodyTo`, filled by
-/// `Guild/Guild.cpp:862-880` `SendQueryResponse`. Client: wow-re
-/// `system/ui/scratch/guild-roster-wire.md` — handler `0x555290` (dbcache) delegating to decoder
-/// `0x62f260`, reads at `0x62f26e` (id), `0x62f27b` (name), `0x62f295` × 10, then `0x62f2af`,
-/// `0x62f2bd`, `0x62f2cb`, `0x62f2d9`, `0x62f2e7`.
-///
-/// The ten is a fixed loop over the sender's `rankNames[10]` array, **not** a counted list — the
-/// server pads with empty strings for ranks the guild never created ("show always 10 ranks", its
-/// own comment), and the client's own loop bound is the compile-time constant `0x62f283 mov
-/// [ebp+8],0xa` on a `do`/`while`, so it always runs ten times. Reading a count first, or stopping
-/// at the guild's real rank count, would land the parse in the middle of the emblem block.
+/// Read `SMSG_GUILD_QUERY_RESPONSE` (`Server/Packets/Guild.cpp:118-131`, reference `0x62f260`):
+/// `u32` id, name, exactly ten rank-name cstrings with no count, then five `i32` tabard fields.
 pub(super) fn read_guild_query_response(r: &mut impl Read) -> io::Result<GuildQueryResponse> {
     let guild_id = read_u32_le(r)?;
     let name = read_cstring(r)?;
@@ -362,131 +252,64 @@ pub(super) fn read_guild_query_response(r: &mut impl Read) -> io::Result<GuildQu
     })
 }
 
-/// One row of `SMSG_GUILD_ROSTER`.
-///
-/// Unlike a friend-list slot, every field the guild pane shows *is* on the wire — a roster is a
-/// snapshot the server composed, so no name-cache round trip is needed to draw it.
+/// One row of `SMSG_GUILD_ROSTER`; every field the guild pane shows is on the wire.
 #[derive(Debug, Clone, PartialEq, Default)]
 pub struct GuildRosterMember {
     /// The member's player guid (vmangos always builds it as `ObjectGuid(HIGHGUID_PLAYER, …)`).
     pub guid: u64,
-    /// [`guild_presence`] bits. [`guild_presence::OFFLINE`] (`0`) is the value that makes
-    /// [`Self::last_online_days`] present on the wire — see [`Self::is_online`].
+    /// [`guild_presence`] bits; `0` puts [`Self::last_online_days`] on the wire.
     pub presence: u8,
-    /// Character name.
     pub name: String,
     /// Rank id, 0-based with 0 = guild master; indexes [`GuildQueryResponse::rank_names`] and
     /// [`GuildRoster::rank_rights`].
     pub rank_id: u32,
-    /// Character level. A `u8` on the wire, not a `u32` — the roster is the widest packet in the
-    /// game and it is packed accordingly.
     pub level: u8,
     /// Class id (`ChrClasses.dbc`).
     pub class: u8,
-    /// Zone id (`AreaTable.dbc`). For an offline member this is their *last known* zone, out of
-    /// the character table.
+    /// Zone id (`AreaTable.dbc`); an offline member's last known zone.
     pub zone: u32,
-    /// Days since this member last logged out, as a fraction — vmangos computes
-    /// `(now - logoutTime) / DAY` (`Guild/Guild.cpp:841`). **Only on the wire for offline
-    /// members**; reads back as `0.0` for online ones, where it is meaningless. The reference UI's
-    /// `GetGuildRosterLastOnline` binding is what splits it into years/months/days.
+    /// Fractional days since logout (`Guild/Guild.cpp:841`), sent for offline members only;
+    /// `GetGuildRosterLastOnline` splits it into years, months and days.
     pub last_online_days: f32,
-    /// The member's public note (empty if unset).
     pub public_note: String,
-    /// The member's officer note — **empty when *we* lack [`guild_rank_right::VIEW_OFFICER_NOTE`]**,
-    /// because the server blanks it per-viewer (`Guild/Guild.cpp:821`, `:844`). An empty string
-    /// therefore does not distinguish "no note" from "not allowed to see it"; the viewer's own
-    /// rank rights do.
+    /// The member's officer note, blanked by the server unless the viewer holds
+    /// [`guild_rank_right::VIEW_OFFICER_NOTE`] (`Guild/Guild.cpp:821`, `:844`).
     pub officer_note: String,
 }
 
 impl GuildRosterMember {
-    /// Is this member online at all (any of ONLINE/AFK/DND)? This is the wire's own test — vmangos
-    /// writes [`Self::last_online_days`] under exactly `if (!member.presenceFlags)`, and
-    /// [`read_guild_roster`] reads it under the same condition.
-    ///
-    /// It is a **whole-byte** comparison against [`guild_presence::OFFLINE`], not `presence &
-    /// ONLINE`, and that is the reference client's own predicate rather than a convenience: it
-    /// derives the flag with `0x4d0c12 test dl,dl` / `0x4d0c1d setne cl` before branching on it.
-    /// An unknown future presence bit therefore reads as *online*, which is the safe direction —
-    /// masking `0x1` would mis-classify it and take the wrong branch on the float.
+    /// Any presence bit set. A whole-byte test, not `& ONLINE`, as it is the wire's condition for
+    /// `lastOnlineTime` in vmangos and in the reference (`0x4d0c12`, `0x4d0c1d`).
     pub fn is_online(&self) -> bool {
         self.presence != guild_presence::OFFLINE
     }
 }
 
-/// `SMSG_GUILD_ROSTER` — the whole guild in one packet: the MOTD, the info text, every rank's
-/// rights, and every member.
-///
-/// Always a complete snapshot, never a delta: vmangos re-sends the whole thing for any change
-/// worth showing (a note edit, a rank-rights change, a promotion). It is also the game's widest
-/// packet, and the sender **truncates the member list** to fit `GUILD_ROSTER_MAX_LENGTH`
-/// (`0x8000 - 4` bytes, `Guild/Guild.h:41`) — so [`Self::members`] can be shorter than the guild
-/// for a very large guild with very long notes, which is the server's behaviour, not a parse error.
+/// `SMSG_GUILD_ROSTER`: the whole guild, re-sent complete on any change. The server truncates the
+/// member list to fit `GUILD_ROSTER_MAX_LENGTH` (`0x8000 - 4` bytes, `Guild/Guild.h:41`), so a
+/// large guild can arrive short.
 #[derive(Debug, Clone, PartialEq, Default)]
 pub struct GuildRoster {
-    /// The message of the day.
     pub motd: String,
-    /// The guild information text (the "Guild Information" pane). 1.12-only — vmangos writes it
-    /// under `SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_8_4`.
+    /// The "Guild Information" text, written only for builds above `CLIENT_BUILD_1_8_4`.
     pub info: String,
-    /// One rights bitmask ([`guild_rank_right`]) per rank, indexed by rank id. Its **length is the
-    /// guild's real rank count** — the one place on the wire that says how many of
-    /// [`GuildQueryResponse::rank_names`]'s ten slots are live.
-    ///
-    /// More than [`GUILD_RANKS_MAX_COUNT`] entries is malformed. We still read them all (dropping
-    /// any would desynchronise everything after) and hand them over; a consumer indexing a fixed
-    /// ten-slot model must bound itself. The reference client does **not**: its loop writes
-    /// straight into a 10-entry array at `[0xb726d0, 0xb726f8)`, so a `rankCount >= 12` walks over
-    /// that array's own container fields — a bug to clamp around, never to reproduce (wow-re
-    /// `system/ui/scratch/guild-roster-wire.md`).
+    /// One [`guild_rank_right`] mask per rank, by rank id; the length is the guild's real rank
+    /// count. More than [`GUILD_RANKS_MAX_COUNT`] is malformed but read in full, so a ten-slot
+    /// consumer bounds itself (the reference overruns its array at `0xb726d0`).
     pub rank_rights: Vec<u32>,
-    /// The members, **arrival order** — vmangos iterates its `members` map, i.e. by low guid.
-    ///
-    /// This is not display order and is not stable in any way a UI should lean on: the reference
-    /// client re-`qsort`s its own copy after every packet (`0x4d0d32`). Sorting is the consumer's
-    /// job; this vector is what came off the wire.
+    /// The members in wire order, by low guid; the reference re-sorts its own copy after every
+    /// packet (`0x4d0d32`), so sorting is the consumer's job.
     pub members: Vec<GuildRosterMember>,
 }
 
-/// A defensive cap on the `Vec::with_capacity` hint taken from the wire's member count: a
-/// corrupt/hostile `u32` must not turn into a multi-gigabyte allocation before the first read
-/// fails. The real ceiling is the packet's own `0x8000`-byte budget, which cannot hold more than
-/// ~1.4k members at the minimum member size.
+/// Allocation cap for the wire member count; a `0x8000`-byte roster fits about 1.4k members.
 const ROSTER_CAPACITY_HINT_CAP: usize = 2048;
 
-/// Read `SMSG_GUILD_ROSTER` (VERIFIED **both ends**): `u32 memberCount`, the MOTD, the info text,
-/// `u32 rankCount`, that many `u32` rights, then the members.
-///
-/// Each member is `u64 guid`, `u8 presenceFlags`, name, `u32 rankId`, `u8 level`, `u8 classId`,
-/// `u32 zoneId`, **`f32 lastOnlineTime` if and only if `presenceFlags == 0`**, public note,
-/// officer note.
-///
-/// Server: vmangos `Server/Packets/Guild.cpp:143-173` `GuildRoster::AppendBodyTo`, filled by
-/// `Guild/Guild.cpp:803-858` `SendGuildRoster`. Client: wow-re
-/// `system/ui/scratch/guild-roster-wire.md` — handler `0x4d0ad0`, head reads at `0x4d0af3`,
-/// `0x4d0b65`, `0x4d0b82`, `0x4d0b9a`, `0x4d0bb3`; member reads at `0x4d0bfd`, `0x4d0c08`,
-/// `0x4d0c43`, `0x4d0c56`, `0x4d0c61`, `0x4d0c6c`, `0x4d0ca0`, `0x4d0cc2`, `0x4d0ce7`, `0x4d0d02`.
-///
-/// That condition is the whole difficulty of this packet. An offline member is 4 bytes longer than
-/// an online one, so a parser that reads the float unconditionally does not merely get one field
-/// wrong — it walks off into the following cstrings and mis-parses **every remaining member**.
-/// It is spelled out as an explicit test on the presence byte rather than a "read if bytes remain"
-/// check for the same reason [`super::social::read_friend_status`] is: the wire keys the field off
-/// a value, and only that value can decide it.
-///
-/// Three independent sources agree on it, and on its exact shape. vmangos states it twice — the
-/// writer (`Guild.cpp:164-165`) and the size accounting that decides where to truncate
-/// (`Guild/Guild.cpp:793-794`). The binary states it once, precisely: `0x4d0cad cmp
-/// DWORD PTR [eax+0x48],edi` (with `edi` held at `0` across the loop) / `0x4d0cb0 je 0x4d0cba`,
-/// whose taken leg is the guarded read `0x4d0cc2`; the other leg consumes nothing and stores `0`.
-/// Two details of that carve are load-bearing here: the predicate is the **whole presence byte**
-/// against zero (`0x4d0c12 test dl,dl` → `0x4d0c1d setne cl`), never `flags & ONLINE` — which is
-/// why [`GuildRosterMember::is_online`] compares against [`guild_presence::OFFLINE`] rather than
-/// masking a bit. And the field really is an `f32`: the client's 4-byte getters are byte-identical
-/// template clones that could never settle a type, so it is pinned at two *consumers* instead —
-/// `0x4d0f19 fld` / `0x4d0f1f fcomp` in the roster comparator, and `0x4d1508 fld` in
-/// `GetGuildRosterLastOnline`.
+/// Read `SMSG_GUILD_ROSTER` (`Server/Packets/Guild.cpp:143-173`, reference `0x4d0ad0`): `u32`
+/// member count, MOTD, info text, `u32` rank count and that many `u32` rights, then per member
+/// `u64` guid, `u8` presence, name, `u32` rank, `u8` level, `u8` class, `u32` zone, an `f32`
+/// last-online time only when presence is `0` (`0x4d0cad`), public note and officer note.
+/// Reading the float unconditionally misparses every later member.
 pub(super) fn read_guild_roster(r: &mut impl Read) -> io::Result<GuildRoster> {
     let member_count = read_u32_le(r)?;
     let motd = read_cstring(r)?;
@@ -526,48 +349,26 @@ pub(super) fn read_guild_roster(r: &mut impl Read) -> io::Result<GuildRoster> {
     })
 }
 
-/// `SMSG_GUILD_EVENT` — one thing that happened in the guild, as the event id plus its
-/// already-formatted `%s` arguments.
+/// `SMSG_GUILD_EVENT`: a guild event id and its `%s` arguments.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct GuildEventNotice {
-    /// A [`guild_event`] id. The reference client's `switch` covers `0x00`–`0x0D` and treats
-    /// anything above as its default arm, so an unknown id is a display question, not a parse one.
+    /// A [`guild_event`] id; the reference sends anything above `0x0D` to its default arm.
     pub event: u8,
-    /// The event's string arguments, in order, exactly as many as `strCount` said.
-    ///
-    /// **Not capped at three, and the reference is not either** — this doc used to claim it was.
-    /// `0x5e7180`'s read loop has no bound: a `strCount >= 4` writes past its three `0x100` stack
-    /// buffers into the live locals (wow-re `system/ui/scratch/guild-api-carve.md` §5). What *is*
-    /// bounded is the **display**: the shared emitter tail `0x5e745f` passes 1, 2 or 3 strings to
-    /// `DisplayError` and passes **none** for `strCount == 0` or `>= 4`. Reading into a `Vec` has
-    /// no overflow to reproduce, so that rule lives on the display side
-    /// (`ui_guild::lines::event_line`, decision 2054) and this field carries what arrived.
+    /// Every string `strCount` announced, uncapped like the reference read loop; the reference
+    /// display passes none of them when there are four or more (`0x5e745f`).
     pub params: Vec<String>,
-    /// The guildmate the event is about — present for [`guild_event::SIGNED_ON`] and
-    /// [`guild_event::SIGNED_OFF`] only. See [`read_guild_event`] for why that is narrower than
-    /// what vmangos writes.
+    /// The guildmate's guid, read only for [`guild_event::SIGNED_ON`] and
+    /// [`guild_event::SIGNED_OFF`].
     pub guid: Option<u64>,
 }
 
-/// Read `SMSG_GUILD_EVENT` (VERIFIED both ends: vmangos `Server/Packets/Guild.cpp:133-141`
-/// `GuildEvent::AppendBodyTo`, and the reference client's own handler `0x5e7180` — wow-re RF-0077,
-/// `system/object-layer/scratch/rf77-smsg-chat-wire-order.md`): `u8 event`, `u8 paramCount`, that
-/// many cstrings, then the optional trailing guid.
-///
-/// **The two ends disagree about *when* the guid is there, and we follow the client.** vmangos
-/// writes it whenever its `affectedPlayerGuid` is set, which its callers do for `GE_JOINED`
-/// (`Handlers/GuildHandler.cpp:218`) and `GE_LEFT` (`:405`, `Guild/Guild.cpp:572`) as well as
-/// `GE_SIGNED_ON`/`GE_SIGNED_OFF`. The reference client reads it in **only** the `0xc`/`0xd` arms
-/// of its jump table — for the other two the guid is simply trailing slack it never touches (the
-/// body is length-framed, so ignoring a trailing field costs nothing and desynchronises nothing).
-/// benilla is the client, so this reads on the event id, and `GE_JOINED`/`GE_LEFT` report
-/// `guid: None` even when the bytes are present. Nothing is lost: those two carry the player's
-/// **name** in `params`, which is what the event is displayed by.
+/// Read `SMSG_GUILD_EVENT` (`Server/Packets/Guild.cpp:133-141`, reference `0x5e7180`): `u8`
+/// event, `u8` count, that many cstrings, then a `u64` guid that the reference reads only for
+/// sign-on and sign-off; vmangos also sends it with `GE_JOINED` and `GE_LEFT`, unread there.
 pub(super) fn read_guild_event(r: &mut impl Read) -> io::Result<GuildEventNotice> {
     let event = read_u8(r)?;
     let param_count = read_u8(r)?;
-    // No protocol bound (`Server/Packets/Guild.h:222`, a vector); the events carry one to three
-    // strings, so 16 is generous.
+    // Events carry one to three strings; the count is unbounded (`Server/Packets/Guild.h:222`).
     let mut params = Vec::with_capacity(capacity_hint(param_count, 16));
     for _ in 0..param_count {
         params.push(read_cstring(r)?);
@@ -582,21 +383,18 @@ pub(super) fn read_guild_event(r: &mut impl Read) -> io::Result<GuildEventNotice
     })
 }
 
-/// `SMSG_GUILD_COMMAND_RESULT` — the server's verdict on a guild verb we sent.
+/// `SMSG_GUILD_COMMAND_RESULT`: the server's verdict on a guild verb we sent.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct GuildCommandResult {
-    /// A [`guild_command`] tag. Load-bearing rather than decorative: it is what disambiguates the
-    /// two meanings of result `0x08` (see [`guild_command_error::LEADER_LEAVE`]).
+    /// A [`guild_command`] tag; it decides which of result `0x08`'s two meanings applies.
     pub command: u32,
-    /// The `%s` the matching error string wants — a player name, a guild name, or empty.
+    /// The `%s` of the matching `ERR_GUILD_*` string: a player name, a guild name, or empty.
     pub name: String,
     /// A [`guild_command_error`] code.
     pub result: u32,
 }
 
-/// Read `SMSG_GUILD_COMMAND_RESULT` (VERIFIED vmangos `Server/Packets/Guild.cpp:96-101`
-/// `GuildCommandResult::AppendBodyTo`): `u32 command`, cstring, `u32 result` — the string is in the
-/// **middle**, which is the field order to get right.
+/// Read `SMSG_GUILD_COMMAND_RESULT` (`Server/Packets/Guild.cpp:96-101`): `u32`, cstring, `u32`.
 pub(super) fn read_guild_command_result(r: &mut impl Read) -> io::Result<GuildCommandResult> {
     Ok(GuildCommandResult {
         command: read_u32_le(r)?,
@@ -605,35 +403,21 @@ pub(super) fn read_guild_command_result(r: &mut impl Read) -> io::Result<GuildCo
     })
 }
 
-/// `SMSG_GUILD_INFO` — the small "founded on / N members / N accounts" summary, answering
-/// `CMSG_GUILD_INFO`. Nothing here overlaps [`GuildRoster`]; it is a separate ask.
-///
-/// The layout — a cstring then five `u32`s — is VERIFIED at both ends. The **field names below are
-/// INFERRED**: they are vmangos's, and the binary does not label them. What the binary does supply
-/// is a corroboration of the first three: the `GUILD_INFO_TEMPLATE` pushes at `0x5e704d`–`0x5e7061`
-/// reorder them **wire #2, wire #1, wire #3-5**, which is exactly the swap an enUS `M/D/Y` date
-/// template applies to a `day, month, year` wire (wow-re `system/ui/scratch/guild-roster-wire.md`).
-/// Good evidence, not a labelled proof — treat a surprising founding date as a lead, not an
-/// impossibility.
+/// `SMSG_GUILD_INFO`, answering `CMSG_GUILD_INFO`: founding date, member and account counts. The
+/// field names are vmangos's; the reference formats wire fields 2, 1, 3 into its enUS `M/D/Y`
+/// `GUILD_INFO_TEMPLATE` (`0x5e704d`), which fits day, month, year.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct GuildInfo {
-    /// The guild's name.
     pub name: String,
-    /// Founding day-of-month (INFERRED — see the struct doc).
     pub created_day: u32,
-    /// Founding month (INFERRED).
     pub created_month: u32,
-    /// Founding year (INFERRED).
     pub created_year: u32,
-    /// How many characters are in the guild.
     pub member_count: u32,
-    /// How many distinct *accounts* those characters belong to — the number the guild pane shows
-    /// alongside the member count.
+    /// How many distinct accounts the members belong to.
     pub account_count: u32,
 }
 
-/// Read `SMSG_GUILD_INFO` (VERIFIED vmangos `Server/Packets/Guild.cpp:103-111`
-/// `GuildInfo::AppendBodyTo`): the guild name, then day/month/year and the two counts, all `u32`.
+/// Read `SMSG_GUILD_INFO` (`Server/Packets/Guild.cpp:103-111`): the name, then five `u32`s.
 pub(super) fn read_guild_info(r: &mut impl Read) -> io::Result<GuildInfo> {
     Ok(GuildInfo {
         name: read_cstring(r)?,
@@ -645,134 +429,101 @@ pub(super) fn read_guild_info(r: &mut impl Read) -> io::Result<GuildInfo> {
     })
 }
 
-/// Read `SMSG_GUILD_INVITE` (VERIFIED vmangos `Server/Packets/Guild.cpp:85-89`
-/// `GuildInviteNotification::AppendBodyTo`): two cstrings — who invited us, and into which guild.
-/// Answered by `CMSG_GUILD_ACCEPT` or `CMSG_GUILD_DECLINE`, neither of which echoes anything, so
-/// the pending invite is client-side state.
+/// Read `SMSG_GUILD_INVITE` (`Server/Packets/Guild.cpp:85-89`): inviter, then guild name. The
+/// accept and decline replies name neither, so the pending invite is client state.
 pub(super) fn read_guild_invite(r: &mut impl Read) -> io::Result<(String, String)> {
     let inviter = read_cstring(r)?;
     let guild = read_cstring(r)?;
     Ok((inviter, guild))
 }
 
-/// Read `SMSG_GUILD_DECLINE` (VERIFIED vmangos `Server/Packets/Guild.cpp:91-94`
-/// `GuildDeclineNotification::AppendBodyTo`): one cstring — the name of the player who turned our
-/// invitation down. Delivered only to the inviter (`Handlers/GuildHandler.cpp:230-236`).
+/// Read `SMSG_GUILD_DECLINE` (`Server/Packets/Guild.cpp:91-94`): who declined our invitation.
 pub(super) fn read_guild_decline(r: &mut impl Read) -> io::Result<String> {
     read_cstring(r)
 }
 
-/// Body of `CMSG_GUILD_QUERY` (VERIFIED vmangos `Server/Packets/Guild.cpp:8-11`
-/// `GuildQuery::ReadFromWorldPacket`): one `u32`, the guild id. Answered by
-/// `SMSG_GUILD_QUERY_RESPONSE` — or, if no such guild exists, by an
-/// `SMSG_GUILD_COMMAND_RESULT`(`CREATE`, `PLAYER_NOT_IN_GUILD`), which is vmangos's catch-all and
-/// not literally about us (`Handlers/GuildHandler.cpp:44`).
+/// Body of `CMSG_GUILD_QUERY` (`Server/Packets/Guild.cpp:8-11`): the `u32` guild id. vmangos
+/// answers an unknown id with `SMSG_GUILD_COMMAND_RESULT` `(CREATE, PLAYER_NOT_IN_GUILD)`
+/// (`Handlers/GuildHandler.cpp:44`).
 pub fn guild_query(guild_id: u32) -> Vec<u8> {
     guild_id.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_GUILD_CREATE` (VERIFIED vmangos `Server/Packets/Guild.cpp:3-6`
-/// `GuildCreate::ReadFromWorldPacket`): one cstring, the desired name.
-///
-/// vmangos registers this opcode `STATUS_NEVER` (`Server/Protocol/Opcodes.cpp:210`) — on a 1.12
-/// realm a guild is founded through the charter/petition flow, never by this packet. Built for
-/// completeness of the family; do not expect a reply.
+/// Body of `CMSG_GUILD_CREATE` (`Server/Packets/Guild.cpp:3-6`): the name. vmangos never handles
+/// it (`STATUS_NEVER`, `Server/Protocol/Opcodes.cpp:210`); a 1.12 guild is founded by charter.
 pub fn guild_create(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_GUILD_INVITE` (VERIFIED vmangos `Server/Packets/Guild.cpp:13-16`
-/// `GuildInvite::ReadFromWorldPacket`): one cstring, the name to invite. The server normalises the
-/// case itself (`normalizePlayerName`), so the client need not.
+/// Body of `CMSG_GUILD_INVITE` (`Server/Packets/Guild.cpp:13-16`): the name, which the server
+/// case-normalises itself.
 pub fn guild_invite(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_GUILD_ACCEPT` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp:213` —
-/// `NullClientPacket`): empty. Which invitation it accepts is the server's own pending state
-/// (`GetGuildIdInvited`), not a field.
+/// Body of `CMSG_GUILD_ACCEPT`: empty (`Server/Protocol/Opcodes.cpp:213`); the server holds the
+/// pending invite.
 pub fn guild_accept() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GUILD_DECLINE` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp:214` —
-/// `NullClientPacket`): empty. Sends the inviter an `SMSG_GUILD_DECLINE` naming us.
+/// Body of `CMSG_GUILD_DECLINE`: empty (`Server/Protocol/Opcodes.cpp:214`); the inviter gets an
+/// `SMSG_GUILD_DECLINE` naming us.
 pub fn guild_decline() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GUILD_INFO` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp:216` —
-/// `NullClientPacket`): empty. Answered by `SMSG_GUILD_INFO` for our own guild.
+/// Body of `CMSG_GUILD_INFO`: empty (`Server/Protocol/Opcodes.cpp:216`); asks about our guild.
 pub fn guild_info() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GUILD_ROSTER` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp:218` —
-/// `NullClientPacket`): empty. Answered by the whole `SMSG_GUILD_ROSTER`; the server also pushes
-/// that packet unasked after any change, so this is a refresh.
+/// Body of `CMSG_GUILD_ROSTER`: empty (`Server/Protocol/Opcodes.cpp:218`); the server also pushes
+/// the roster unasked after any change.
 pub fn guild_roster() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GUILD_PROMOTE` (VERIFIED vmangos `Server/Packets/Guild.cpp:23-26`
-/// `GuildPromote::ReadFromWorldPacket`): one cstring, who to promote. Promotion is by name and
-/// moves them **up** one rank — the server does `rank--` (`Guild/Guild.h:52`).
+/// Body of `CMSG_GUILD_PROMOTE` (`Server/Packets/Guild.cpp:23-26`): the name, moved one rank up.
 pub fn guild_promote(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_GUILD_DEMOTE` (VERIFIED vmangos `Server/Packets/Guild.cpp:28-31`
-/// `GuildDemote::ReadFromWorldPacket`): one cstring; the server does `rank++`.
+/// Body of `CMSG_GUILD_DEMOTE` (`Server/Packets/Guild.cpp:28-31`): the name, moved one rank down.
 pub fn guild_demote(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_GUILD_LEAVE` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp:222` —
-/// `NullClientPacket`): empty. Refused with
-/// `(QUIT, LEADER_LEAVE)` if we are the guild master and anyone else is still in the guild.
+/// Body of `CMSG_GUILD_LEAVE`: empty (`Server/Protocol/Opcodes.cpp:222`). A guild master is
+/// refused `(QUIT, LEADER_LEAVE)` while anyone else remains.
 pub fn guild_leave() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GUILD_REMOVE` (VERIFIED vmangos `Server/Packets/Guild.cpp:18-21`
-/// `GuildRemove::ReadFromWorldPacket`): one cstring, who to kick.
+/// Body of `CMSG_GUILD_REMOVE` (`Server/Packets/Guild.cpp:18-21`): the member to kick.
 pub fn guild_remove(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_GUILD_DISBAND` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp:224` —
-/// `NullClientPacket`): empty. Guild master only.
+/// Body of `CMSG_GUILD_DISBAND`: empty (`Server/Protocol/Opcodes.cpp:224`); guild master only.
 pub fn guild_disband() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GUILD_LEADER` (VERIFIED vmangos `Server/Packets/Guild.cpp:33-36`
-/// `GuildLeader::ReadFromWorldPacket`): one cstring — hand the guild over to this member.
+/// Body of `CMSG_GUILD_LEADER` (`Server/Packets/Guild.cpp:33-36`): the new guild master's name.
 pub fn guild_leader(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_GUILD_MOTD` (VERIFIED vmangos `Server/Packets/Guild.cpp:38-42`
-/// `GuildMOTD::ReadFromWorldPacket`): one cstring, the new message of the day.
-///
-/// **Clearing the MOTD sends `""` as a one-byte body (the NUL), not a zero-byte body.** vmangos's
-/// read is guarded — `if (!recv_data.empty()) recv_data >> motd;` — so a *literally empty* body is
-/// also accepted and also means "clear it" (its `motd` stays default-constructed). Both shapes
-/// therefore work, and the guard exists to stop an empty packet throwing a `ByteBufferException`
-/// rather than to define a second wire form. We emit the well-formed cstring in every case: one
-/// builder, one shape, and the empty string is not a special case anywhere in this crate.
+/// Body of `CMSG_GUILD_MOTD` (`Server/Packets/Guild.cpp:38-42`): the new MOTD; `""`, a lone NUL,
+/// clears it.
 pub fn guild_motd(motd: &str) -> Vec<u8> {
     cstring_body(motd)
 }
 
-/// Body of `CMSG_GUILD_RANK` (VERIFIED vmangos `Server/Packets/Guild.cpp:78-83`
-/// `GuildRank::ReadFromWorldPacket`): `u32 rankId`, `u32 rights`, then the rank name.
-///
-/// This one packet both renames a rank and rewrites its rights, so a caller changing only one must
-/// still send the current value of the other. Two server-side facts shape the call: sending it for
-/// [`guild_default_rank::GUILDMASTER`] has its `rights` **ignored and replaced** with
-/// [`guild_rank_right::ALL`], and a `name` longer than [`GUILD_RANK_MAX_LENGTH`] characters gets
-/// the session **kicked** by the anticheat, not refused.
+/// Body of `CMSG_GUILD_RANK` (`Server/Packets/Guild.cpp:78-83`): rank id, rights, name. Both are
+/// set, so changing one resends the other; rank 0's rights become [`guild_rank_right::ALL`], and
+/// a name over [`GUILD_RANK_MAX_LENGTH`] gets the session kicked.
 pub fn guild_rank(rank_id: u32, rights: u32, name: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(9 + name.len());
     body.extend_from_slice(&rank_id.to_le_bytes());
@@ -781,50 +532,41 @@ pub fn guild_rank(rank_id: u32, rights: u32, name: &str) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_GUILD_ADD_RANK` (VERIFIED vmangos `Server/Packets/Guild.cpp:73-76`
-/// `GuildAddRank::ReadFromWorldPacket`): one cstring, the new rank's name. The rank is appended at
+/// Body of `CMSG_GUILD_ADD_RANK` (`Server/Packets/Guild.cpp:73-76`): the name. The rank goes at
 /// the bottom with `GCHAT_LISTEN | GCHAT_SPEAK` (`Handlers/GuildHandler.cpp:623`); the server
-/// silently ignores the packet once the guild already has [`GUILD_RANKS_MAX_COUNT`] ranks.
+/// ignores the packet once the guild has [`GUILD_RANKS_MAX_COUNT`] ranks.
 pub fn guild_add_rank(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_GUILD_DEL_RANK` (VERIFIED vmangos `Server/Protocol/Opcodes.cpp:655` —
-/// `NullClientPacket`): empty. There is no rank id: it always deletes the **lowest** rank, which is
-/// why the reference UI only ever offers to remove the last row.
+/// Body of `CMSG_GUILD_DEL_RANK`: empty (`Server/Protocol/Opcodes.cpp:655`); the server always
+/// deletes the lowest rank.
 pub fn guild_del_rank() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_GUILD_SET_PUBLIC_NOTE` (VERIFIED vmangos `Server/Packets/Guild.cpp:61-65`
-/// `GuildSetPublicNote::ReadFromWorldPacket`): the member's name, then the note.
+/// Body of `CMSG_GUILD_SET_PUBLIC_NOTE` (`Server/Packets/Guild.cpp:61-65`): name, then note.
 pub fn guild_set_public_note(name: &str, note: &str) -> Vec<u8> {
     two_cstring_body(name, note)
 }
 
-/// Body of `CMSG_GUILD_SET_OFFICER_NOTE` (VERIFIED vmangos `Server/Packets/Guild.cpp:67-71`
-/// `GuildSetOfficerNote::ReadFromWorldPacket`): the same two-cstring shape as
-/// [`guild_set_public_note`], gated on [`guild_rank_right::EDIT_OFFICER_NOTE`] instead.
+/// Body of `CMSG_GUILD_SET_OFFICER_NOTE` (`Server/Packets/Guild.cpp:67-71`): name, then note.
 pub fn guild_set_officer_note(name: &str, note: &str) -> Vec<u8> {
     two_cstring_body(name, note)
 }
 
-/// Body of `CMSG_GUILD_INFO_TEXT` (VERIFIED vmangos `Server/Packets/Guild.cpp:44-49`
-/// `GuildChangeInfoText::ReadFromWorldPacket`): one cstring, the guild information text. 1.12-only
-/// — vmangos compiles both the opcode's handler and the roster's matching `guildInfo` field under
-/// `SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_8_4`.
+/// Body of `CMSG_GUILD_INFO_TEXT` (`Server/Packets/Guild.cpp:44-49`): the guild information text;
+/// vmangos handles it only for builds above `CLIENT_BUILD_1_8_4`.
 pub fn guild_info_text(text: &str) -> Vec<u8> {
     cstring_body(text)
 }
 
-/// A body that is exactly one NUL-terminated string.
 fn cstring_body(s: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(s.len() + 1);
     push_cstring(&mut body, s);
     body
 }
 
-/// A body that is exactly two NUL-terminated strings.
 fn two_cstring_body(a: &str, b: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(a.len() + b.len() + 2);
     push_cstring(&mut body, a);
@@ -832,7 +574,6 @@ fn two_cstring_body(a: &str, b: &str) -> Vec<u8> {
     body
 }
 
-/// Append a NUL-terminated string to `body`.
 fn push_cstring(body: &mut Vec<u8>, s: &str) {
     body.extend_from_slice(s.as_bytes());
     body.push(0);
@@ -842,8 +583,6 @@ fn push_cstring(body: &mut Vec<u8>, s: &str) {
 mod tests {
     use super::*;
 
-    /// The rights table is *not* `1 << (i - 1)`: the FrameXML checkbox order puts Promote/Demote
-    /// ahead of Invite/Remove, whose bits are lower. This pins the two orders apart.
     #[test]
     fn rank_right_checkbox_order_is_not_bit_order() {
         assert_eq!(GUILD_RANK_RIGHT_ORDER[4], 0x0000_0080, "idx 5 = Promote");
@@ -854,15 +593,13 @@ mod tests {
             GUILD_RANK_RIGHT_ORDER[4] > GUILD_RANK_RIGHT_ORDER[6],
             "the order is deliberately non-monotonic in bit value"
         );
-        // Every entry is a single bit, and none of them is the GR_RIGHT_EMPTY sentinel.
         for right in GUILD_RANK_RIGHT_ORDER {
             assert_eq!(right.count_ones(), 1, "{right:#x} is one bit");
             assert_ne!(right, guild_rank_right::EMPTY);
         }
     }
 
-    /// Each right, ORed with the `GR_RIGHT_EMPTY` sentinel, reproduces vmangos's own constant —
-    /// the check that the "factor the 0x40 out" reading of `Guild/Guild.h:56-74` is right.
+    /// The expected values are vmangos's `GuildRankRights` (`Guild/Guild.h:56-74`).
     #[test]
     fn rank_rights_reconstruct_the_vmangos_constants() {
         use guild_rank_right::*;
diff --git a/crates/benilla-protocol/src/messages/instance.rs b/crates/benilla-protocol/src/messages/instance.rs
index 6f159034..640d36ff 100644
--- a/crates/benilla-protocol/src/messages/instance.rs
+++ b/crates/benilla-protocol/src/messages/instance.rs
@@ -1,58 +1,28 @@
-//! The instance/raid **lockout message** family — the six server packets the 1.12 client turns
-//! into a `CHAT_MSG_SYSTEM` line or into its own lockout bookkeeping, plus the one thing the
-//! player can ask for (`CMSG_RESET_INSTANCES`). Decision 1748.
-//!
-//! | opcode | direction | body | what the client does with it |
-//! |---|---|---|---|
-//! | `SMSG_INSTANCE_SAVE_CREATED` 0x2cb | in | `u32` flag | chat line `INSTANCE_SAVED` |
-//! | `SMSG_RAID_INSTANCE_MESSAGE` 0x2fa | in | `u32` type, `u32` mapId, `u32` secsToReset | chat line, one of four |
-//! | `CMSG_RESET_INSTANCES` 0x31d | out | empty | — |
-//! | `SMSG_INSTANCE_RESET` 0x31e | in | `u32` mapId | chat line `INSTANCE_RESET_SUCCESS` + clears the last-instance latch |
-//! | `SMSG_INSTANCE_RESET_FAILED` 0x31f | in | `u32` reason, `u32` mapId | chat line, one of three |
-//! | `SMSG_UPDATE_LAST_INSTANCE` 0x320 | in | `u32` mapId | records the last dungeon we were in |
-//! | `SMSG_UPDATE_INSTANCE_OWNERSHIP` 0x32b | in | `u32` flag | the "do I hold any permanent bind" latch |
-//!
-//! **The client side is VERIFIED at the bytes** (WoW.exe build 5875): the six handlers are
-//! registered together at `0x498680`-`0x4986cf` (`0x49e1c0` 0x2fa, `0x49e470` 0x31e, `0x49e540`
-//! 0x31f, `0x49e670` 0x320, `0x49e6c0` 0x32b) with the save-created one registered apart, in the
-//! chat-spam-filter TU, at `0x4e7e48` (`0x4e7e60`). Every one reads its fields with
-//! `CDataStore::GetInt32 0x418e30` in the order below, so the layouts here are the client's own
-//! read order, not an inference from the server. The server side is VERIFIED vmangos
-//! `Server/Packets/Misc.{h,cpp}` (`RaidInstanceMessage`, `InstanceReset`, `InstanceResetFailed`,
-//! `UpdateLastInstance`, `UpdateInstanceOwnership`) + `Maps/Map.cpp:2288,2388` for the
-//! save-created flag, and the two agree field for field.
-//!
-//! **No map NAME is ever on the wire** — every one of these carries a `Map.dbc` id and the client
-//! looks the display name up itself (`[0xc0daa8][id]`, field `+0x10` = `MapName_Lang[locale]`),
-//! falling back to the id printed through `"%d"` when the row is missing. Ours resolves through
-//! `MapCatalog::name` with the same fallback.
+//! The instance lockout messages and `CMSG_RESET_INSTANCES`. The 1.12 client prints a system chat
+//! line for a new save (`INSTANCE_SAVED`), a raid warning, a reset (`INSTANCE_RESET_SUCCESS`,
+//! which also clears the last instance) and a failed reset, and keeps the last instance and the
+//! permanent-bind flag as state. Maps travel as `Map.dbc` ids; the reference looks the name up
+//! itself (`0xc0daa8`) and prints the id when the row is missing.
 
 use std::io;
 
 use crate::wire::read_u32_le;
 
-/// `SMSG_RAID_INSTANCE_MESSAGE`'s `type` — which of the four warning templates the line uses
-/// (VERIFIED: the client's `switch (type - 1)` jump table at `0x49e45c`, four entries; the same
-/// numbering vmangos writes in `Objects/Player.h:568-573`).
-///
-/// **Type 5 (`RAID_INSTANCE_EXPIRED` in later clients) and type 0 print nothing**: the dispatch is
-/// `dec eax; cmp eax,3; ja <return>`, so anything outside 1..=4 leaves the handler silently.
+/// `SMSG_RAID_INSTANCE_MESSAGE`'s `type` (`Objects/Player.h:568-573`). Outside 1-4 the reference
+/// prints nothing (jump table `0x49e45c`), even for 5, later clients' `RAID_INSTANCE_EXPIRED`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum RaidInstanceWarning {
-    /// 1 — `RAID_INSTANCE_WARNING_HOURS`, filled with `resetTime / 3600`.
+    /// 1: `RAID_INSTANCE_WARNING_HOURS`, filled with `resetTime / 3600`.
     Hours,
-    /// 2 — `RAID_INSTANCE_WARNING_MIN`, filled with `resetTime / 60`.
+    /// 2: `RAID_INSTANCE_WARNING_MIN`, filled with `resetTime / 60`.
     Minutes,
-    /// 3 — `RAID_INSTANCE_WARNING_MIN_SOON`, filled with `resetTime / 60`.
+    /// 3: `RAID_INSTANCE_WARNING_MIN_SOON`, filled with `resetTime / 60`.
     MinutesSoon,
-    /// 4 — `RAID_INSTANCE_WELCOME`, filled with the `d`/`h`/`m` breakdown of `resetTime`.
+    /// 4: `RAID_INSTANCE_WELCOME`, filled with the `d`/`h`/`m` breakdown of `resetTime`.
     Welcome,
 }
 
 impl RaidInstanceWarning {
-    /// The wire `type` → the template, or `None` for the values the reference's jump table drops
-    /// (0 and ≥ 5). A dropped type is not an error: the packet is well-formed, the client just
-    /// has no line for it.
     pub fn from_wire(ty: u32) -> Option<Self> {
         match ty {
             1 => Some(Self::Hours),
@@ -63,8 +33,7 @@ impl RaidInstanceWarning {
         }
     }
 
-    /// The GlobalStrings token the reference passes to `GetText` for this template (the four
-    /// `mov ecx, <string>` at `0x49e276`/`0x49e2e5`/`0x49e354`/`0x49e40b`).
+    /// The reference's GlobalStrings token (`0x49e276`, `0x49e2e5`, `0x49e354`, `0x49e40b`).
     pub fn token(self) -> &'static str {
         match self {
             Self::Hours => "RAID_INSTANCE_WARNING_HOURS",
@@ -75,38 +44,31 @@ impl RaidInstanceWarning {
     }
 }
 
-/// `SMSG_RAID_INSTANCE_MESSAGE` — a raid lockout's welcome/countdown line.
+/// `SMSG_RAID_INSTANCE_MESSAGE`: a raid lockout's welcome or countdown line.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct RaidInstanceMessage {
-    /// The raw wire type. Kept raw rather than pre-resolved so a type the reference drops still
-    /// round-trips through the event layer (and so a golden can assert the drop).
+    /// The raw wire type; [`RaidInstanceWarning::from_wire`] resolves it.
     pub message_type: u32,
-    /// `Map.dbc` id of the instance the warning is about.
     pub map: u32,
-    /// **Seconds remaining** until the reset, not a timestamp (vmangos passes
-    /// `resetTime` = a remaining duration into `SendInstanceResetWarning`).
+    /// Seconds until the reset, a duration rather than a timestamp (`SendInstanceResetWarning`).
     pub reset: u32,
 }
 
-/// `SMSG_INSTANCE_RESET_FAILED`'s `reason` — which of the three refusal templates the line uses
-/// (VERIFIED: the client's `sub eax,0; je / dec eax; je / dec eax; jne` ladder at `0x49e5b7`;
-/// vmangos `Maps/MapPersistentStateMgr.h:270-276`, whose fourth value `_SILENTLY` = 3 is
-/// deliberately outside the ladder).
+/// `SMSG_INSTANCE_RESET_FAILED`'s `reason` (ladder at `0x49e5b7`; vmangos
+/// `Maps/MapPersistentStateMgr.h:270-276`, whose `INSTANCERESET_FAIL_SILENTLY` is 3).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum InstanceResetFailure {
-    /// 0 — `INSTANCE_RESET_FAILED`: players still inside.
+    /// 0: `INSTANCE_RESET_FAILED`, players still inside.
     General,
-    /// 1 — `INSTANCE_RESET_FAILED_OFFLINE`: someone in the party is offline.
+    /// 1: `INSTANCE_RESET_FAILED_OFFLINE`, someone in the party is offline.
     Offline,
-    /// 2 — `INSTANCE_RESET_FAILED_ZONING`: someone in the party is zoning in.
+    /// 2: `INSTANCE_RESET_FAILED_ZONING`, someone in the party is zoning in.
     Zoning,
 }
 
 impl InstanceResetFailure {
-    /// The wire `reason` → the template, or `None` for ≥ 3 (`INSTANCERESET_FAIL_SILENTLY` and
-    /// above). The reference *falls through* those to its chat call with an **uninitialized**
-    /// stack buffer — a real 1.12 bug we do not reproduce: silence is what the server means by
-    /// them, and printing a garbage line is not fidelity to an intent, only to an accident.
+    /// Deviation: a reason of 3 or more is silent, where the reference prints an uninitialized
+    /// stack buffer; 3 is the server's `INSTANCERESET_FAIL_SILENTLY`.
     pub fn from_wire(reason: u32) -> Option<Self> {
         match reason {
             0 => Some(Self::General),
@@ -116,7 +78,7 @@ impl InstanceResetFailure {
         }
     }
 
-    /// The GlobalStrings token (the three `mov ecx, <string>` at `0x49e61b`/`0x49e5f6`/`0x49e5d1`).
+    /// The reference's GlobalStrings token (`0x49e61b`, `0x49e5f6`, `0x49e5d1`).
     pub fn token(self) -> &'static str {
         match self {
             Self::General => "INSTANCE_RESET_FAILED",
@@ -126,17 +88,16 @@ impl InstanceResetFailure {
     }
 }
 
-/// `SMSG_INSTANCE_RESET_FAILED` — the group leader's reset was refused.
+/// `SMSG_INSTANCE_RESET_FAILED`: the group leader's reset was refused.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct InstanceResetFailed {
-    /// The raw wire reason (see [`InstanceResetFailure::from_wire`]).
+    /// The raw wire reason; [`InstanceResetFailure::from_wire`] resolves it.
     pub reason: u32,
-    /// `Map.dbc` id of the instance that would not reset.
     pub map: u32,
 }
 
-/// Read `SMSG_RAID_INSTANCE_MESSAGE`: `u32 type`, `u32 mapId`, `u32 secondsUntilReset` — the
-/// client's own read order at `0x49e1cd`/`0x49e1d8`/`0x49e1e3`.
+/// Read `SMSG_RAID_INSTANCE_MESSAGE`: type, map, seconds to reset (reference reads `0x49e1cd`,
+/// `0x49e1d8`, `0x49e1e3`).
 pub(super) fn read_raid_instance_message(r: &mut &[u8]) -> io::Result<RaidInstanceMessage> {
     Ok(RaidInstanceMessage {
         message_type: read_u32_le(r)?,
@@ -153,31 +114,28 @@ pub(super) fn read_instance_reset_failed(r: &mut &[u8]) -> io::Result<InstanceRe
     })
 }
 
-/// Read a body that is one bare `u32` — `SMSG_INSTANCE_RESET`'s map id (`0x49e481`),
-/// `SMSG_UPDATE_LAST_INSTANCE`'s map id (`0x49e676`), `SMSG_UPDATE_INSTANCE_OWNERSHIP`'s flag
-/// (`0x49e6c6`) and `SMSG_INSTANCE_SAVE_CREATED`'s flag (`0x4e7e6c`) are all exactly this.
+/// Read a one-`u32` body: `SMSG_INSTANCE_RESET`'s map (`0x49e481`), `SMSG_UPDATE_LAST_INSTANCE`'s
+/// map (`0x49e676`), `SMSG_UPDATE_INSTANCE_OWNERSHIP`'s permanent-bind flag (`0x49e6c6`) and
+/// `SMSG_INSTANCE_SAVE_CREATED`'s flag (`0x4e7e6c`).
 pub(super) fn read_u32_body(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
 
-/// Body of `CMSG_RESET_INSTANCES` (VERIFIED both ways: the client's `ResetInstances` binding
-/// `0x48a6b0` builds a `CDataStore` and sends opcode `0x31d` without writing a field; vmangos
-/// `HandleResetInstancesOpcode` reads nothing): empty.
+/// Body of `CMSG_RESET_INSTANCES`: empty (reference `ResetInstances`, `0x48a6b0`).
 pub fn reset_instances() -> Vec<u8> {
     Vec::new()
 }
 
-/// `SMSG_RAID_GROUP_ONLY` (VERIFIED, wow-re `staticpopup-dialog-bindings.md` §5.2, arm
-/// `0x5e48f1`): the instance-boot clock and its reason. `delay_ms > 0` arms the boot deadline
-/// (`INSTANCE_BOOT_START`); `0` clears it (`INSTANCE_BOOT_STOP`), and then `reason` 1 / 2 is
-/// `ERR_RAID_GROUP_ONLY` / `ERR_RAID_GROUP_FULL` on screen. Decision 1963.
+/// `SMSG_RAID_GROUP_ONLY` (reference `0x5e48f1`): a nonzero `delay_ms` arms the instance-boot
+/// deadline (`INSTANCE_BOOT_START`); `0` clears it (`INSTANCE_BOOT_STOP`), and then `reason` 1 or
+/// 2 shows `ERR_RAID_GROUP_ONLY` or `ERR_RAID_GROUP_FULL`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct RaidGroupOnly {
     pub delay_ms: u32,
     pub reason: u32,
 }
 
-/// Parse `SMSG_RAID_GROUP_ONLY`: `u32 delayMs`, `u32 reason` — both 32-bit reads.
+/// Parse `SMSG_RAID_GROUP_ONLY`: `u32 delayMs`, `u32 reason`.
 pub(super) fn read_raid_group_only(r: &mut impl std::io::Read) -> std::io::Result<RaidGroupOnly> {
     Ok(RaidGroupOnly {
         delay_ms: crate::wire::read_u32_le(r)?,
diff --git a/crates/benilla-protocol/src/messages/items.rs b/crates/benilla-protocol/src/messages/items.rs
index 2fe9f9bc..d7e3f057 100644
--- a/crates/benilla-protocol/src/messages/items.rs
+++ b/crates/benilla-protocol/src/messages/items.rs
@@ -1,209 +1,137 @@
-//! Item messages — the T2 container groundwork (decision 0068's tier ladder: Bagnon needs item
-//! identity), widened to the **full** 1.12.1 item template (decision 0274 P1: the tooltip builder
-//! needs every line the real client can render). The 1.12 wire carries no item *templates* in
-//! descriptors — like unit names, they answer a query pair: `CMSG_ITEM_QUERY_SINGLE` (entry + guid)
-//! → `SMSG_ITEM_QUERY_SINGLE_RESPONSE` (VERIFIED vmangos `HandleItemQuerySingleOpcode`; opcodes
-//! 86/88 `Opcodes_1_12_1.h`).
-//!
-//! [`ItemInfo`] now carries the response whole: identity (class/subclass/name — 4 name slots, the
-//! server sends 1 + 3 empties — displayInfoID, quality, inventoryType, sheath), the buy/sell
-//! economy, every requirement gate (level/skill/spell/honor rank/city rank/reputation,
-//! allowable class/race), stacking (maxCount/stackable/containerSlots), the full 10-slot stat
-//! block, all 5 damage blocks (block 0 also mirrors into the legacy `dmg_min`/`dmg_max`/`dmg_type`
-//! fields existing consumers already key on), armor plus the 6-wide resistance run, ranged data,
-//! all 5 spell-trigger slots (the first ON_USE slot still surfaces separately as `use_spell` — the
-//! client's own cooldown-scan key), bonding, description, page/lock/material/random-property/set,
-//! durability, and the area/map/bagFamily tail (VERIFIED field order vmangos
-//! `HandleItemQuerySingleOpcode`, `ItemHandler.cpp:269-415`; every `SUPPORTED_CLIENT_BUILD`
-//! conditional in that function evaluates *included* for build 5875). A **miss** (undiscovered/
-//! unknown entry) is the lone `u32` of `entry | 0x8000_0000`, the same shape as the creature miss.
+//! Item messages. Item templates are not in descriptors: `CMSG_ITEM_QUERY_SINGLE` (opcode 86,
+//! entry and guid) asks, and `SMSG_ITEM_QUERY_SINGLE_RESPONSE` (88) answers in the field order of
+//! vmangos `ItemHandler.cpp:269-415`, every build conditional included at 5875. A miss is the lone
+//! `u32` `entry | 0x8000_0000`.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_f32_le, read_i32_le, read_u32_le, read_u64_le, read_u8};
 
-/// A full item-template answer (decision 0274 P1: the tooltip builder's source of truth; every
-/// field the wire carries, none discarded). (`PartialEq` only: several fields are wire floats —
-/// the damage bounds and `ranged_mod_range`.)
+/// One item template, as `SMSG_ITEM_QUERY_SINGLE_RESPONSE` carries it.
 #[derive(Debug, Clone, PartialEq)]
 pub struct ItemInfo {
     pub class: u32,
     pub subclass: u32,
     pub name: String,
-    /// `ItemDisplayInfo.dbc` key — the icon/model resolve.
+    /// `ItemDisplayInfo.dbc` id, for the icon and model.
     pub display_info_id: u32,
-    /// 0 poor … 6 artifact (the RF-55 quality-color table's index).
+    /// 0 poor to 6 artifact; indexes the quality colour table.
     pub quality: u32,
-    /// `ItemPrototypeFlags` bitmask (conjured, lootable, indestructible, wrapper, no-equip-cooldown,
-    /// …) — the tooltip's "Unique"/no-sell/no-disenchant lines key on bits here.
+    /// `ItemPrototypeFlags` bits (conjured, lootable, wrapper, …); tooltip lines key on them.
     pub flags: u32,
-    /// `BuyPrice` — what a vendor charges per [`crate::messages::VendorItem::buy_count`]-sized
-    /// stack, in copper.
+    /// Copper a vendor charges per [`crate::messages::VendorItem::buy_count`] stack.
     pub buy_price: u32,
-    /// `SellPrice` — what a vendor pays per unit, in copper (the bag tooltip's money row while a
-    /// merchant is open; 0 = unsellable → the "No sell price" line).
+    /// Copper a vendor pays per unit; 0 is unsellable, the tooltip's "No sell price" line.
     pub sell_price: u32,
-    /// `InventoryType` — the equip-slot family (1 head, 21/22 main/off-hand weapon, …); drives
-    /// which paperdoll slot an item can go in and which visual-item field it feeds.
+    /// `InventoryType`, the equip-slot family (1 head, 21/22 main/off-hand weapon, …).
     pub inventory_type: u32,
-    /// `AllowableClass` — a class bitmask; the all-bits-set sentinel (`-1`) means no class
-    /// restriction, so this stays signed rather than reading as the unsigned `0xFFFF_FFFF`.
+    /// Class bitmask; `-1`, all bits, means no restriction.
     pub allowable_class: i32,
-    /// `AllowableRace` — the same bitmask shape as [`Self::allowable_class`], races instead.
+    /// Race bitmask; `-1` means no restriction.
     pub allowable_race: i32,
-    /// `ItemLevel` — the repair-cost formula's `DurabilityCosts.dbc` row key (also a tooltip line).
+    /// Item level, the `DurabilityCosts.dbc` row for the repair cost.
     pub item_level: u32,
-    /// `RequiredLevel` — the tooltip's "Requires Level N" line; 0 = no level requirement.
+    /// The "Requires Level N" line; 0 means none.
     pub required_level: u32,
-    /// `RequiredSkill` — id from `SkillLine.dbc`; 0 = no skill requirement.
+    /// `SkillLine.dbc` id; 0 means none.
     pub required_skill: u32,
-    /// `RequiredSkillRank` — the skill value [`Self::required_skill`] must meet or exceed.
+    /// The minimum [`Self::required_skill`] value.
     pub required_skill_rank: u32,
-    /// `RequiredSpell` — id from `Spell.dbc`; the item is unusable without knowing this spell.
+    /// A `Spell.dbc` id the player must know to use the item.
     pub required_spell: u32,
-    /// `RequiredHonorRank`/`RequiredCityRank` — two more requirement gates the wire carries; the
-    /// tooltip's requirement-line law for these two is unverified (folds in with decision 0274's
-    /// §5 line-order dispatch).
     pub required_honor_rank: u32,
     pub required_city_rank: u32,
-    /// `RequiredReputationFaction` — id from `Faction.dbc`; 0 = no reputation requirement.
+    /// `Faction.dbc` id; 0 means none.
     pub required_rep_faction: u32,
-    /// `RequiredReputationRank` — the wire's own gate: the server sends 0 whenever
-    /// [`Self::required_rep_faction`] is 0, even if the row has a nonzero rank (VERIFIED vmangos
-    /// `ItemHandler.cpp:321-322`).
+    /// Sent as 0 whenever [`Self::required_rep_faction`] is 0 (`ItemHandler.cpp:321-322`).
     pub required_rep_rank: u32,
-    /// `MaxCount` — the account-wide cap this item enforces (0 = uncapped); the tooltip's "Unique"
-    /// family of lines derive from this and [`Self::flags`].
+    /// `MaxCount`, 0 uncapped; the tooltip's "Unique" lines derive from it and [`Self::flags`].
     pub max_count: u32,
-    /// `Stackable` — the max stack size a single slot can hold (1 = doesn't stack).
+    /// Maximum stack size; 1 does not stack.
     pub stackable: u32,
-    /// `ContainerSlots` — nonzero only for bag items (the number of slots the bag itself grants).
+    /// Slots a bag grants; 0 for anything else.
     pub container_slots: u32,
-    /// The 10-slot `ItemStat` block, `(type, value)`, **filtered to nonzero entries** (type or
-    /// value nonzero) in wire order — the tooltip's "+N Stat" lines (`ItemModType` at this build:
-    /// 0 mana, 1 health, 3 agility, 4 strength, 5 intellect, 6 spirit, 7 stamina).
+    /// The 10-slot `ItemStat` block as `(type, value)`, all-zero slots dropped, in wire order
+    /// (`ItemModType`: 0 mana, 1 health, 3 agility, 4 strength, 5 intellect, 6 spirit, 7 stamina).
     pub stats: Vec<(u32, i32)>,
-    /// The 5-slot `Damage` block, **filtered to entries with `max > 0`**, in wire order —
-    /// secondary damage lines (e.g. a Fiery weapon's bonus Fire line) beyond the primary
-    /// [`Self::dmg_min`]/[`Self::dmg_max`]/[`Self::dmg_type`], which always mirror block 0 whether
-    /// or not it clears this filter.
+    /// The 5-slot `Damage` block, entries with `max > 0` only, in wire order.
     pub damages: Vec<ItemDamage>,
-    /// Damage block 0's per-hit minimum (the tooltip's "X - Y Damage" line; 0 for non-weapons) —
-    /// kept mirrored from `damages` block 0 for existing consumers.
+    /// Damage block 0's minimum, whether or not block 0 is in [`Self::damages`].
     pub dmg_min: f32,
     /// Damage block 0's per-hit maximum.
     pub dmg_max: f32,
-    /// Damage block 0's school (0 physical, 1 Holy … 6 Arcane — the tooltip's school suffix).
+    /// Damage block 0's school (0 physical, 1 Holy … 6 Arcane).
     pub dmg_type: u32,
-    /// `Armor` — the first slot of the wire's 7-wide resistance run.
+    /// The first slot of the wire's 7-wide resistance run.
     pub armor: u32,
-    /// The remaining 6 slots of the resistance run, in wire order: `[holy, fire, nature, frost,
-    /// shadow, arcane]` (`int32` on the wire in vmangos's own `ItemPrototype` — a template's
-    /// resistance can't go negative in practice, but the sign rides along).
+    /// The other six resistances: holy, fire, nature, frost, shadow, arcane (`int32` in vmangos).
     pub resistances: [i32; 6],
     /// Attack delay in milliseconds (the tooltip's "Speed" = delay / 1000).
     pub delay_ms: u32,
-    /// `AmmoType` — the projectile family a ranged weapon consumes (0 none, 2 arrow, 3 bullet).
+    /// The projectile a ranged weapon consumes (0 none, 2 arrow, 3 bullet).
     pub ammo_type: u32,
-    /// `RangedModRange` — a ranged weapon's range multiplier; the tooltip never shows this raw, it
-    /// feeds the range formula.
+    /// A ranged weapon's range multiplier.
     pub ranged_mod_range: f32,
-    /// The 5-slot `ItemSpell` block, **filtered to entries with `spell_id != 0`**, in wire order —
-    /// every "Use:"/"Equip:"/"Chance on hit:" trigger line the tooltip can render. Each entry
-    /// carries its own [`ItemSpellEntry::index`], since this vector's positions are not the
-    /// template's block ordinals.
+    /// The 5-slot `ItemSpell` block, `spell_id != 0` only, in wire order; positions here are not
+    /// block ordinals, [`ItemSpellEntry::index`] is.
     pub spells: Vec<ItemSpellEntry>,
-    /// Spell **block 0**'s `SpellCharges` word, raw and unfiltered — the reference's
-    /// `template+0x144`, and the sole input to [`Self::has_finite_charges`].
+    /// Block 0's `SpellCharges`, unfiltered: the reference's `template+0x144`.
     pub spell_charges_0: i32,
-    /// The first ON_USE (`SpellTrigger == 0`) spell block — what a right-click/action-bar use
-    /// casts, and the key the item's cooldown tracks (the client's own 5-slot scan: spell id > 0,
-    /// trigger == 0 — wow-re `wave-cooldown.md` `GetItemCooldown 0x6e2ed0`). `None` for items with
-    /// no use effect. A stored view onto [`Self::spells`] (rather than a derived accessor) so
-    /// existing cooldown/tooltip consumers reading `.use_spell` are untouched.
+    /// The first ON_USE (trigger 0) spell block: what a use casts, and the item's cooldown key
+    /// (the reference's `GetItemCooldown` scan, `0x6e2ed0`).
     pub use_spell: Option<ItemUseSpell>,
-    /// `Bonding` — `ItemBondingType` (0 none … 4 quest-bind); the tooltip's "Binds when picked
-    /// up"/"equipped"/"used" line.
+    /// `ItemBondingType` (0 none … 4 quest-bind).
     pub bonding: u32,
-    /// The item's flavor text (the tooltip's italic line under the stat block); empty = none.
+    /// Flavor text, the tooltip's italic line; empty for none.
     pub description: String,
-    /// `PageText` — a readable item's `PageText.wdb` id (0 = not a book/readable).
+    /// A readable item's `PageText.wdb` id; 0 for none.
     pub page_text: u32,
-    /// `LanguageID` — id from `Languages.dbc`; which in-game language a readable's text renders in.
+    /// `Languages.dbc` id a readable's text is written in.
     pub language_id: u32,
-    /// `PageMaterial` — id from `PageTextMaterial.dbc`; the book-frame background/texture.
+    /// `PageTextMaterial.dbc` id, the book frame's background.
     pub page_material: u32,
-    /// `StartQuest` — a quest-starter item's quest id (0 = doesn't start a quest).
+    /// The quest this item starts; 0 for none.
     pub start_quest: u32,
-    /// `LockID` — id from `Lock.dbc`; nonzero means the item (a chest/junkbox) needs picking/keying
-    /// open.
+    /// `Lock.dbc` id; nonzero means the item must be picked or keyed open.
     pub lock_id: u32,
-    /// `Material` — id from `Material.dbc`; drives the item's equip/drop/footstep sound set.
+    /// `Material.dbc` id, for the item's sounds.
     pub material: u32,
-    /// `Sheath` — the holster style a drawn weapon of this type renders with (vmangos
-    /// `ItemPrototype::Sheath`; the same vocabulary as [`super::update_object::ObjectFields`]'s
-    /// virtual-item sheath byte).
+    /// Sheath style, in the values of the descriptor's virtual-item sheath byte.
     pub sheath: u32,
-    /// `RandomProperty` — id from `ItemRandomProperties.dbc`; a "of the Whale"-style suffix roll
-    /// (the concrete roll lives on the item *instance*, not the template — this is just which
-    /// property table applies).
+    /// `ItemRandomProperties.dbc` id for an "of the Whale" suffix, rolled per instance.
     pub random_property: u32,
-    /// `Block` — a shield's block value (two `u32`s past `Sheath`, after `RandomProperty`).
+    /// A shield's block value.
     pub block: u32,
-    /// `ItemSet` — id from `ItemSet.dbc`; 0 = not part of a set.
+    /// `ItemSet.dbc` id; 0 for none.
     pub item_set: u32,
-    /// `MaxDurability` — 0 for items without durability (never repairable).
+    /// 0 for items without durability.
     pub max_durability: u32,
-    /// `Area` — id from `AreaTable.dbc`; a zone-bound item's required zone (0 = anywhere).
+    /// `AreaTable.dbc` zone the item is bound to; 0 for anywhere.
     pub area: u32,
-    /// `Map` — id from `Map.dbc`; a map-bound item's required map (0 = anywhere).
+    /// `Map.dbc` map the item is bound to; 0 for anywhere.
     pub map: u32,
-    /// `BagFamily` — which specialised container an item belongs in (quiver 1, ammo pouch 2, soul
-    /// bag 3, herb 6, enchanting 7, engineering 8, **keys 9**; 0 = an ordinary item / ordinary bag).
-    /// An **enum, not a bitmask**, on this wire: 1.12 tests it for equality (vmangos
-    /// `ItemPrototype.h`'s `enum BagFamily`, and the reference's own `HasKey` `0x48ae90` compares
-    /// `template+0x1d0 == 9`) — it only became a mask in 2.x. `9` is what routes an item into the
-    /// keyring, and what [`crate::ObjectFields::player_keyring_slot`]'s slots hold.
+    /// The specialised container an item belongs in (1 quiver, 2 ammo pouch, 3 soul bag, 6 herb,
+    /// 7 enchanting, 8 engineering, 9 keyring; 0 none). An enum, not a mask, in 1.12: the
+    /// reference's `HasKey` (`0x48ae90`) tests `== 9`.
     pub bag_family: u32,
 }
 
 impl ItemInfo {
-    /// Does this item carry **finite charges**? The reference's
-    /// `template+0x144 != 0 && template+0x144 != -1` (wow-re `action-item-slot.md` §8.2) — the
-    /// gate on the use path's mode-`0x20` inventory search, which skips spent copies so a click
-    /// reaches one that still works. `-1` is the "unlimited" sentinel, `0` "no charges at all".
+    /// The reference's `template+0x144 != 0 && != -1` (`-1` unlimited, `0` none), which gates the
+    /// use path's mode-`0x20` search for a copy with charges left.
     pub fn has_finite_charges(&self) -> bool {
         self.spell_charges_0 != 0 && self.spell_charges_0 != -1
     }
 
-    /// The **block ordinal** (0..4) of the first ON_USE spell — the third byte of `CMSG_USE_ITEM`
-    /// (wow-re `action-item-slot.md` §8.3). `None` for an item with no on-use spell. Almost
-    /// always 0, but an item whose block 0 is an ON_EQUIP proc and whose on-use sits in block 1
-    /// needs the real index or the server casts the wrong block.
+    /// The first ON_USE spell's block ordinal, the third byte of `CMSG_USE_ITEM`; usually 0, but
+    /// an item with an ON_EQUIP block 0 has its on-use in a later block.
     pub fn use_spell_index(&self) -> Option<u8> {
         self.spells.iter().find(|s| s.trigger == 0).map(|s| s.index)
     }
 
-    /// Is this item **consumable** in the sense the action bar's Count fontstring means?
-    /// `IsConsumableAction 0x4e5250`, byte-read (`4e52b9`–`4e52ea`), after it has resolved the
-    /// slot's item template:
-    ///
-    /// ```text
-    /// [rec+0x2c] InventoryType == 0x18 (AMMO) or 0x19 (THROWN)          -> true   (4e52b9-4e52c4)
-    /// OR  ∃ i∈[0,5):  SpellId[i]      [rec+0x11c+4i] != 0                        (4e52d0)
-    ///              ∧  SpellTrigger[i] [rec+0x130+4i] == 0   (ON_USE)             (4e52d7)
-    ///              ∧  SpellCharges[i] [rec+0x144+4i] <  0   (destroy-on-use)     (4e52dc)
-    /// otherwise                                                         -> false
-    /// ```
-    ///
-    /// **Negative** charges — not merely finite ones — are the test: the sign is vmangos's own
-    /// "the ITEM is consumed once the charges run out" convention, so a potion (`-1`) counts and a
-    /// wand-like item with positive charges does not. Nothing here looks at `Class`: a mount
-    /// (`Class` 15 Miscellaneous, `InventoryType` 0, on-use spell with `SpellCharges` 0) is **not**
-    /// consumable, which is why the reference shows no stack number under a mount on the bar.
-    ///
-    /// [`Self::spells`] already drops the `SpellId == 0` blocks, so iterating it is the `4e52d5`
-    /// skip.
+    /// Consumable as the action bar's count means it (reference `IsConsumableAction`,
+    /// `0x4e5250`): ammo or thrown, or an ON_USE spell with negative charges, which use the item
+    /// up. Neither positive charges nor `Class` count: a mount, with charges 0, shows no count.
     pub fn is_consumable(&self) -> bool {
         const INVTYPE_AMMO: u32 = 0x18;
         const INVTYPE_THROWN: u32 = 0x19;
@@ -211,93 +139,53 @@ impl ItemInfo {
             || self.spells.iter().any(|s| s.trigger == 0 && s.charges < 0)
     }
 
-    /// Can this item be placed on an action-bar slot? `PlaceAction`'s only item filter, byte-read
-    /// (wow-re `action-item-slot.md` §5, `4e6571`–`4e6598`): **an on-use spell OR equippable**.
-    /// No quality, bind, class/subclass, container or level test exists anywhere on that path — a
-    /// bag (`InventoryType` 18) IS placeable; a grey trade good with neither is silently refused.
+    /// The reference `PlaceAction`'s only item filter (`0x4e6571`): an on-use spell or anything
+    /// equippable, bags included; anything else is refused silently.
     pub fn placeable_on_action_bar(&self) -> bool {
         self.use_spell.is_some() || self.inventory_type != 0
     }
 
-    /// Does the tooltip put the green `<Right Click to Open>` line on this instance?
-    /// `instance_flags` is the item object's `ITEM_FIELD_FLAGS`; a template-only view (a
-    /// hyperlink, a merchant row) passes 0 and, being object-less, gets no line at all — the
-    /// reference's own gate 1 at `0x52e2e0`.
-    ///
-    /// VERIFIED wow-re `right-click-open.md` §1.4 (`0x52e2f8`–`0x52e321`), re-derived by a §5 pair
-    /// 2026-08-02: the template LOOTABLE bit [`ITEM_FLAG_LOOTABLE`] behind its **lock sub-gate** —
-    /// a [`ItemInfo::lock_id`] item earns the line only once the instance carries
-    /// [`ITEM_DYNFLAG_UNLOCKED`] — **or** a wrapped gift ([`ITEM_FLAG_WRAPPER`] on the template
-    /// plus [`ITEM_DYNFLAG_WRAPPED`] on the instance).
-    ///
-    /// **This is deliberately NOT the send condition** ([`Self::opens_loot`]). The line is a
-    /// promise, and the reference only makes it when opening will actually work; the *click*
-    /// tests the bare template bit and lets the server refuse a still-locked box with its own
-    /// error line. Decision 0896 — an earlier reading of ours collapsed the two, which would have
-    /// silently swallowed the click on every locked junkbox.
+    /// Whether the tooltip shows the green `<Right Click to Open>` line (`0x52e2f8`), given the
+    /// instance's `ITEM_FIELD_FLAGS`: lootable and, if locked, unlocked; or a wrapped gift. An
+    /// object-less view (a hyperlink, a merchant row) gets no line at all (`0x52e2e0`). Stricter
+    /// than [`Self::opens_loot`] on purpose: the click still sends for a locked box.
     pub fn shows_open_line(&self, instance_flags: u32) -> bool {
         let lootable = self.flags & ITEM_FLAG_LOOTABLE != 0
             && (self.lock_id == 0 || instance_flags & ITEM_DYNFLAG_UNLOCKED != 0);
         lootable || self.unwraps_gift(instance_flags)
     }
 
-    /// Does a right-click on this instance send `CMSG_OPEN_ITEM` to **unwrap a gift**? The first
-    /// arm of the reference's use dispatcher (`0x5d8d00` #2, `0x5d8d92`/`0x5d8d9d` → the `0x5edd60`
-    /// emitter): template [`ITEM_FLAG_WRAPPER`] **and** instance [`ITEM_DYNFLAG_WRAPPED`].
-    ///
-    /// It is a separate predicate from [`Self::opens_loot`] because it sits at a different point
-    /// in the dispatcher's order — *before* the quest-starter and readable arms, where the loot
-    /// arm sits after them. A wrapper template whose instance is *not* wrapped takes the
-    /// begin-wrap cursor path instead ([`Self::begins_gift_wrap`]) — local, no packet.
+    /// Whether a right-click sends `CMSG_OPEN_ITEM` to unwrap a gift (`0x5d8d92`). The reference
+    /// tests it before the quest-starter and readable arms; the loot arm comes after them.
     pub fn unwraps_gift(&self, instance_flags: u32) -> bool {
         self.flags & ITEM_FLAG_WRAPPER != 0 && instance_flags & ITEM_DYNFLAG_WRAPPED != 0
     }
 
-    /// Does a right-click on this instance **arm the gift-wrap cursor**? The *other* side of the
-    /// same fork [`Self::unwraps_gift`] tests (`0x5d8d00` arm 2): template [`ITEM_FLAG_WRAPPER`]
-    /// with the instance's [`ITEM_DYNFLAG_WRAPPED`] **clear** — a piece of wrapping paper rather
-    /// than a wrapped present.
-    ///
-    /// **Nothing is sent on this click.** `0x5d8dba` calls `0x5edea0`, whose only three acts are
-    /// `LockItem 0x4953e0` on the paper, `SetCursorBaseMode(2)` and `CursorSetMode(2)` — a purely
-    /// local arm (wow-re `object-layer/scratch/gift-wrap-law.md`, §5-carved). What completes it is
-    /// the next **left**-click on a container slot, which sends [`wrap_item`]. Decision 1934.
+    /// Whether a right-click arms the gift-wrap cursor: wrapping paper, not a wrapped present.
+    /// Nothing is sent (`0x5edea0` locks the paper and sets cursor mode 2); the next left-click on
+    /// a container slot sends [`wrap_item`].
     pub fn begins_gift_wrap(&self, instance_flags: u32) -> bool {
         self.flags & ITEM_FLAG_WRAPPER != 0 && instance_flags & ITEM_DYNFLAG_WRAPPED == 0
     }
 
-    /// Does a right-click on this template send `CMSG_OPEN_ITEM` to **loot it open**? The
-    /// reference's arm #8 (`0x5d8f7c: test al,4` → the `0x5edc80` emitter): a **bare** template
-    /// [`ITEM_FLAG_LOOTABLE`] test.
-    ///
-    /// VERIFIED wow-re `right-click-open.md` §3, positively *and* negatively — no `LockID`
-    /// (`[rec+0x1ac]`) operand exists anywhere on the send path, checked against a positive
-    /// control. So a **still-locked junkbox does send the packet**, and the server answers
-    /// `EQUIP_ERR_ITEM_LOCKED`, which is where the player's "Item is locked" line comes from.
-    /// Refusing locally instead would eat the click in silence.
+    /// Whether a right-click sends `CMSG_OPEN_ITEM` to loot the item (`0x5d8f7c`): the bare
+    /// template bit with no lock test, so a locked box still sends and the server answers
+    /// `EQUIP_ERR_ITEM_LOCKED`.
     pub fn opens_loot(&self) -> bool {
         self.flags & ITEM_FLAG_LOOTABLE != 0
     }
 }
 
-/// `ITEM_FLAG_LOOTABLE` — the **template** bit that makes an item right-clickable into a loot
-/// window (a clam, a lockbox, a Gnomish Mind Control Cap's box). vmangos
-/// `ItemPrototype.h:66`, whose own comment names the client behaviour this drives: "It or lockid
-/// set enable for client show 'Right click to open'".
+/// Template bit: right-click opens a loot window, as on a clam or lockbox (`ItemPrototype.h:66`).
 pub const ITEM_FLAG_LOOTABLE: u32 = 0x0000_0004;
-/// `ITEM_FLAG_WRAPPER` — the template bit for gift wrapping (vmangos `ItemPrototype.h:73`); paired
-/// with [`ITEM_DYNFLAG_WRAPPED`] on the instance it makes the wrapped present openable.
+/// Template bit for gift wrapping (`ItemPrototype.h:73`).
 pub const ITEM_FLAG_WRAPPER: u32 = 0x0000_0200;
-/// `ITEM_DYNFLAG_UNLOCKED` — the **instance** (`ITEM_FIELD_FLAGS`) bit a lockbox gains once it has
-/// been picked/keyed open; until then a `LockID` item refuses to open (vmangos
-/// `HandleOpenItemOpcode`'s `EQUIP_ERR_ITEM_LOCKED`).
+/// Instance (`ITEM_FIELD_FLAGS`) bit a lockbox gains once picked or keyed open.
 pub const ITEM_DYNFLAG_UNLOCKED: u32 = 0x0000_0004;
-/// `ITEM_DYNFLAG_WRAPPED` — the instance bit on a gift-wrapped item; opening it unwraps to the
-/// present (vmangos swaps the entry from `character_gifts` rather than sending loot).
+/// Instance bit on a wrapped gift; opening it swaps the entry back from `character_gifts`.
 pub const ITEM_DYNFLAG_WRAPPED: u32 = 0x0000_0008;
 
-/// One `Damage` block ([`ItemInfo::damages`] — block 0 is also mirrored into
-/// [`ItemInfo::dmg_min`]/[`ItemInfo::dmg_max`]/[`ItemInfo::dmg_type`]).
+/// One `Damage` block of [`ItemInfo::damages`].
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct ItemDamage {
     pub min: f32,
@@ -306,18 +194,11 @@ pub struct ItemDamage {
     pub school: u32,
 }
 
-/// One item-template spell block ([`ItemInfo::spells`]) — the full 6-word wire shape, not just the
-/// resolved ON_USE cooldown pair ([`ItemUseSpell`]). `charges`: positive = consumed only while
-/// charges last, negative = the item itself is consumed once charges run out (vmangos
-/// `ItemPrototype::_ItemSpell::SpellCharges`). The cooldown pair is **server-resolved** the same way
-/// as [`ItemUseSpell`]'s (VERIFIED vmangos `ItemHandler.cpp:354-391`).
+/// One template spell block of [`ItemInfo::spells`]. Negative `charges` use the item up when they
+/// run out, positive ones leave it (`ItemPrototype::_ItemSpell::SpellCharges`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ItemSpellEntry {
-    /// Which of the template's **five** spell blocks this is (0..4). Not the index in
-    /// [`ItemInfo::spells`] — that vector drops empty blocks, and the wire's own
-    /// `CMSG_USE_ITEM` spell byte is this block ordinal (wow-re `action-item-slot.md` §8.3: the
-    /// reference scans `SpellId[5]`/`SpellTrigger[5]` for the block it is casting and sends its
-    /// position).
+    /// The template block ordinal (0..4), which `CMSG_USE_ITEM`'s spell byte carries.
     pub index: u8,
     pub spell_id: u32,
     /// `ItemSpelltriggerType`: 0 ON_USE, 1 ON_EQUIP, 2 CHANCE_ON_HIT.
@@ -331,13 +212,9 @@ pub struct ItemSpellEntry {
     pub category_cooldown_ms: i32,
 }
 
-/// The first ON_USE spell block ([`ItemInfo::use_spell`]) — a resolved-cooldown view of whichever
-/// [`ItemSpellEntry`] has `trigger == 0`. The cooldown pair is **server-resolved** (VERIFIED vmangos
-/// `ItemHandler.cpp:354-380`: the `item_template` override when its value is `>= 0`, else the
-/// spell's own `RecoveryTime`/`Category`/`CategoryRecoveryTime`) — but a lone `-1` can still ride
-/// next to a set override, so the fields stay signed and a negative means "use the spell's own
-/// Spell.dbc value" (the client's `>= 0` pick in `StartCooldown 0x6e2c60`, wow-re
-/// `wave-cooldown.md`).
+/// An item's first ON_USE spell block. The server substitutes the spell's own cooldowns for unset
+/// ones (`ItemHandler.cpp:354-380`), but a `-1` can still arrive; negative means the spell's
+/// `Spell.dbc` value, as the reference's `StartCooldown` (`0x6e2c60`) reads it.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ItemUseSpell {
     pub spell_id: u32,
@@ -349,8 +226,7 @@ pub struct ItemUseSpell {
     pub category_cooldown_ms: i32,
 }
 
-/// Read `SMSG_ITEM_QUERY_SINGLE_RESPONSE` → `(entry, Some(head))`, or `(entry, None)` on a miss
-/// (VERIFIED field order vmangos `HandleItemQuerySingleOpcode`, `ItemHandler.cpp:269-415`).
+/// Read `SMSG_ITEM_QUERY_SINGLE_RESPONSE` in the field order of `ItemHandler.cpp:269-415`.
 pub(super) fn read_item_query_response(r: &mut &[u8]) -> io::Result<(u32, Option<ItemInfo>)> {
     let entry = read_u32_le(r)?;
     if entry & 0x8000_0000 != 0 {
@@ -360,7 +236,7 @@ pub(super) fn read_item_query_response(r: &mut &[u8]) -> io::Result<(u32, Option
     let subclass = read_u32_le(r)?;
     let name = read_cstring(r)?;
     for _ in 0..3 {
-        let _ = read_cstring(r)?; // name2..name4 — the server sends empties
+        let _ = read_cstring(r)?; // name2..name4, always sent empty
     }
     let display_info_id = read_u32_le(r)?;
     let quality = read_u32_le(r)?;
@@ -383,8 +259,7 @@ pub(super) fn read_item_query_response(r: &mut &[u8]) -> io::Result<(u32, Option
     let stackable = read_u32_le(r)?;
     let container_slots = read_u32_le(r)?;
 
-    // 10x ItemStat { type, value } — kept only where either half is nonzero (an all-zero slot is a
-    // genuinely unused one), wire order preserved.
+    // 10 ItemStat { type, value }; an all-zero slot is unused.
     let mut stats = Vec::new();
     for _ in 0..10 {
         let stat_type = read_u32_le(r)?;
@@ -394,10 +269,7 @@ pub(super) fn read_item_query_response(r: &mut &[u8]) -> io::Result<(u32, Option
         }
     }
 
-    // 5x Damage { min f32, max f32, type u32 }, wire order. Block 0 is the tooltip's primary
-    // damage line — always mirrored into the legacy dmg_min/dmg_max/dmg_type fields for existing
-    // consumers, whether or not it clears the `max > 0` filter below (a non-weapon's block 0 is a
-    // real 0/0/0, not a missing value).
+    // 5 Damage { min f32, max f32, type u32 }; block 0 also fills dmg_* unfiltered.
     let dmg_min = read_f32_le(r)?;
     let dmg_max = read_f32_le(r)?;
     let dmg_type = read_u32_le(r)?;
@@ -418,8 +290,6 @@ pub(super) fn read_item_query_response(r: &mut &[u8]) -> io::Result<(u32, Option
         }
     }
 
-    // Armor is its own field; the remaining 6-wide resistance run (Holy/Fire/Nature/Frost/
-    // Shadow/Arcane) lands in `resistances` in wire order.
     let armor = read_u32_le(r)?;
     let holy_res = read_i32_le(r)?;
     let fire_res = read_i32_le(r)?;
@@ -435,17 +305,10 @@ pub(super) fn read_item_query_response(r: &mut &[u8]) -> io::Result<(u32, Option
     let ammo_type = read_u32_le(r)?;
     let ranged_mod_range = read_f32_le(r)?;
 
-    // 5x Spell block { SpellId, SpellTrigger, SpellCharges, Cooldown, Category, CategoryCooldown }
-    // (VERIFIED vmangos `ItemHandler.cpp:354-391`) — the server always writes all six words; a slot
-    // with no resolvable spell sends the sentinel 0,0,0,-1,0,-1. Kept in `spells` wherever
-    // `spell_id != 0`; the first ON_USE (trigger 0) slot also surfaces as `use_spell` — the
-    // client's own 5-slot scan.
+    // 5 spell blocks of six words (`ItemHandler.cpp:354-391`); an empty block is 0,0,0,-1,0,-1.
     let mut spells = Vec::new();
     let mut use_spell = None;
-    // Block 0's charges, kept RAW — whether the item has finite charges is the reference's
-    // `template+0x144 != 0 && != -1` test on exactly this word ([`ItemInfo::has_finite_charges`],
-    // wow-re `action-item-slot.md` §8.2), which reads block 0 even when block 0 carries no spell
-    // and so never reaches `spells` below.
+    // Kept even when block 0 has no spell: the reference's charge test reads it regardless.
     let mut spell_charges_0 = 0;
     for block in 0..5u8 {
         let spell_id = read_u32_le(r)?;
@@ -554,9 +417,7 @@ pub(super) fn read_item_query_response(r: &mut &[u8]) -> io::Result<(u32, Option
     ))
 }
 
-/// Body of `CMSG_ITEM_QUERY_SINGLE` (vmangos `QueryItem::ReadFromWorldPacket`): the template
-/// `entry` + a full 8-byte item guid (0 when asking about a template with no instance in hand) —
-/// the exact shape of the creature query.
+/// Body of `CMSG_ITEM_QUERY_SINGLE`: entry, then a full item guid (0 with no instance in hand).
 pub fn item_query(entry: u32, guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&entry.to_le_bytes());
@@ -564,82 +425,46 @@ pub fn item_query(entry: u32, guid: u64) -> Vec<u8> {
     body
 }
 
-/// The wire's "the player's own inventory" bag index (`INVENTORY_SLOT_BAG_0`): with it, `slot`
-/// addresses the player descriptor's item array directly — equipment 0–18, bag slots 19–22, the
-/// backpack 23–38 (VERIFIED vmangos `Player.h` slot enums; the same 23-slot base the descriptor's
-/// `PACK_SLOT_1` offset encodes).
+/// The player's own bag index (`INVENTORY_SLOT_BAG_0`): `slot` then indexes the player's item
+/// array, equipment 0-18, bags 19-22, backpack 23-38 (vmangos `Player.h`).
 pub const BAG_PLAYER_INVENTORY: u8 = 255;
 /// The backpack's first player-array slot (`INVENTORY_SLOT_ITEM_START`).
 pub const SLOT_PACK_FIRST: u8 = 23;
-/// The first equipped-bag player-array slot (`INVENTORY_SLOT_BAG_START`; bags occupy 19–22).
+/// The first equipped-bag player-array slot (`INVENTORY_SLOT_BAG_START`; bags occupy 19-22).
 pub const SLOT_BAG_FIRST: u8 = 19;
 
-/// `TARGET_FLAG_GAMEOBJECT` — the cast-target bit that carries a GO guid (vmangos
-/// `SpellDefines.h`; its `SpellCastTargets::read` is the only bit here that consumes bytes).
+/// `SpellCastTargets` mask bits, vmangos `SpellDefines.h`.
 const TARGET_FLAG_GAMEOBJECT: u16 = 0x0800;
 
-/// `TARGET_FLAG_UNIT` — a bound unit target: the same bit, and the same packed guid, a
-/// `CMSG_CAST_SPELL` writes. In the real client ONE block builder serves both opcodes, so one bit
-/// table serves both here.
 const TARGET_FLAG_UNIT: u16 = 0x0002;
-/// `TARGET_FLAG_DEST_LOCATION` — a ground point, the same bit and the same three `f32` WoW coords
-/// a ground-targeted `CMSG_CAST_SPELL` writes ([`super::spells::cast_spell_at_dest`]).
 const TARGET_FLAG_DEST_LOCATION: u16 = 0x0040;
-/// `TARGET_FLAG_SOURCE_LOCATION` — the dest bit's twin one place down, and the same three `f32`
-/// ([`super::spells::cast_spell_at_source`]). Both come out of the one binder `BindLocation
-/// 0x6e60f0` (decision 2218).
 const TARGET_FLAG_SOURCE_LOCATION: u16 = 0x0020;
-/// `TARGET_FLAG_ITEM` — a bound *item* target, the same bit and the same packed guid an
-/// item-targeted `CMSG_CAST_SPELL` writes (`super::spells::cast_spell_on_item`). One block
-/// builder, two opcodes (decision 0923).
 const TARGET_FLAG_ITEM: u16 = 0x0010;
 
-/// The `SpellCastTargets` block a `CMSG_USE_ITEM` carries — built by the *same* code as a
-/// `CMSG_CAST_SPELL`'s. `SendCast 0x6e54f0` picks the opcode from its item-vs-caster discriminator
-/// (`0x6e57d8 push 0xab` when the pending-cast block's guid is the item's, `push 0x12e` when it is
-/// the caster's) and then writes the one targets block `ArmCast 0x6e5250` bound — item or not
-/// (wow-re `action-item-slot.md` §8: "body `{u8 bagIndex, u8 slot, u8 spell_index}` + the
-/// cast-targets block"; `cursor-system.md` §8.4a for the split).
+/// The `SpellCastTargets` block of a `CMSG_USE_ITEM`, the same block a `CMSG_CAST_SPELL` carries:
+/// the reference's `SendCast` (`0x6e54f0`) only picks the opcode (`0x6e57d8`).
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub enum UseItemTarget {
-    /// Mask 0 (`TARGET_FLAG_SELF`) — the implicit self-cast an ordinary consumable sends, whose
-    /// target the server resolves itself. What 81% of the 1.12 on-use items bind to.
+    /// Mask 0 (`TARGET_FLAG_SELF`): an ordinary consumable; the server resolves the target.
     #[default]
     SelfImplicit,
-    /// `TARGET_FLAG_UNIT` + the packed guid — an item whose spell binds a unit exactly as a
-    /// spell's does: a bandage, a soulstone, an offensive trinket.
+    /// `TARGET_FLAG_UNIT` and a packed guid: a bandage, a soulstone, an offensive trinket.
     Unit(u64),
-    /// `TARGET_FLAG_GAMEOBJECT` + the packed guid — the **key-in-a-lock** case (decision 0769):
-    /// opening a locked door or chest with a key is not a spell cast, it is *using the key at the
-    /// object*. It matters that this is USE_ITEM and not a bare cast: `Spell::CanOpenLock` honours
-    /// a `Lock.dbc` KEY slot **only** when `m_CastItem` is set (`Spell.cpp:7892`), which only this
-    /// packet supplies. The mask is `0x0800` alone — `TARGET_FLAG_LOCKED` is a *targeting-word*
-    /// bit that `BindTarget 0x6e5b40` consumes and never writes to the wire (decision 0939,
-    /// correcting 0769; see [`super::spells::cast_spell_gameobject`] for the census).
+    /// `TARGET_FLAG_GAMEOBJECT` and a packed guid: a key used on a lock, which the server honours
+    /// only from an item cast (`Spell.cpp:7892`). The mask is `0x0800` alone; the reference's
+    /// `BindTarget` (`0x6e5b40`) never writes `TARGET_FLAG_LOCKED`.
     Object(u64),
-    /// `TARGET_FLAG_DEST_LOCATION` + three `f32` WoW coords — the targeting-cursor commit for a
-    /// **thrown** item: dynamite, grenades, bombs, the Goblin Mortar (46 of the 1.12 on-use item
-    /// spells, decision 0914). Same block a ground-targeted spell writes; only the opcode differs.
+    /// `TARGET_FLAG_DEST_LOCATION` and three `f32` coords: a thrown item, dynamite or a grenade.
     Dest([f32; 3]),
-    /// `TARGET_FLAG_ITEM` + the packed guid — the targeting cursor's **item** commit: a poison, a
-    /// sharpening stone, a weapon oil, an enchanting scroll applied to the item you clicked in a
-    /// bag or on the paper doll (decision 0923). The reference reaches it through the very same
-    /// `BindTarget 0x6e5b40` a unit goes through (`0x495d60` @ `496056`), so the block is the same
-    /// block; only which bit is set differs.
+    /// `TARGET_FLAG_ITEM` and a packed guid: a poison, oil or stone applied to a clicked item.
     Item(u64),
-    /// `TARGET_FLAG_SOURCE_LOCATION` + three `f32` WoW coords — [`Self::Dest`]'s twin, one bit
-    /// over: `BindLocation 0x6e60f0`'s bit-5 arm writes the clicked point to `SPELLCAST+0x30` and
-    /// ORs `0x0020` into the wire mask, where its bit-6 arm writes `+0x3c` and ORs `0x0040`. Three
-    /// shipped items reach it — Martin Fury (17), 192 and 5417, all carrying spell 265 "Area Death
-    /// (TEST)" (decision 2218). vmangos reads this triple **before** the dest one.
+    /// `TARGET_FLAG_SOURCE_LOCATION` and three `f32` coords (`BindLocation`, `0x6e60f0`); only
+    /// items carrying spell 265, such as Martin Fury, use it. vmangos reads it before the dest.
     Source([f32; 3]),
 }
 
-/// Body of `CMSG_USE_ITEM` (VERIFIED vmangos `UseItem::ReadFromWorldPacket` + opcode 171
-/// `Opcodes_1_12_1.h`): `bagIndex` (a bag's player-array slot 19–22, or [`BAG_PLAYER_INVENTORY`]
-/// with an absolute `slot`), `slot` (0-based within the bag), `spellSlot` (which of the template's
-/// 5 spell effects — 0, the "use" effect, for a plain use), then a `SpellCastTargets` block
-/// ([`UseItemTarget`]).
+/// Body of `CMSG_USE_ITEM` (opcode 171): bag index (a bag's player-array slot 19-22, or
+/// [`BAG_PLAYER_INVENTORY`]), slot within it, the spell block ordinal, then the targets block.
 pub fn use_item(bag_index: u8, slot: u8, spell_slot: u8, target: UseItemTarget) -> Vec<u8> {
     let mut body = Vec::with_capacity(5);
     body.push(bag_index);
@@ -681,112 +506,66 @@ pub fn use_item(bag_index: u8, slot: u8, spell_slot: u8, target: UseItemTarget)
     body
 }
 
-/// Body of `CMSG_OPEN_ITEM` (VERIFIED vmangos `OpenItem::ReadFromWorldPacket`,
-/// `Server/Packets/Spell.cpp` + `.h:36-45`; opcode 172 `Opcodes_1_12_1.h:175`): `bagIndex`, `slot`
-/// — the same two bytes and the same bag addressing as [`use_item`], and nothing else (no spell
-/// ordinal, no targets block: opening is not a cast).
-///
-/// The right-click fork for an [`ItemInfo::openable`] item. The server answers on the **item's own
-/// guid**: `SendLoot(item, LOOT_CORPSE)` for a lootable, or — for a wrapped gift — an entry swap
-/// and no window at all.
+/// Body of `CMSG_OPEN_ITEM` (opcode 172, `Server/Packets/Spell.h:36-45`): bag index and slot, as
+/// in [`use_item`]. The server loots the item on its own guid, or unwraps a gift in place.
 pub fn open_item(bag_index: u8, slot: u8) -> Vec<u8> {
     vec![bag_index, slot]
 }
 
-/// Body of `CMSG_WRAP_ITEM` (VERIFIED vmangos `WrapItem::ReadFromWorldPacket`,
-/// `Server/Packets/Item.cpp:121-127` + `.h:191-201`; opcode 467 `Opcodes_1_12_1.h:468`):
-/// `giftBag`, `giftSlot`, `itemBag`, `itemSlot` — all `uint8`, the **paper's** position first and
-/// the target's second, the same bag addressing as [`use_item`].
-///
-/// The server refuses every ineligible target with an `EQUIP_ERR_*` of its own
-/// (`HandleWrapItemOpcode`: equipped, a bag, soulbound, stackable, unique, already wrapped, or
-/// mid-cast) — so a refusal reaches the player as an `SMSG_INVENTORY_CHANGE_FAILURE` line, not as
-/// a silently eaten click. On success the *target* item keeps its guid and takes the paper's
-/// `WrappedGift` entry, gains `ITEM_FIELD_GIFTCREATOR` and `ITEM_DYNFLAG_WRAPPED`, and one paper
-/// is destroyed — all as ordinary field updates, no answering packet of its own.
+/// Body of `CMSG_WRAP_ITEM` (opcode 467, `Server/Packets/Item.cpp:121-127`): the paper's bag and
+/// slot, then the target's. The server refuses with `SMSG_INVENTORY_CHANGE_FAILURE`; success is
+/// only field updates, the target taking the paper's gift entry and `ITEM_DYNFLAG_WRAPPED`.
 pub fn wrap_item(gift_bag: u8, gift_slot: u8, item_bag: u8, item_slot: u8) -> Vec<u8> {
     vec![gift_bag, gift_slot, item_bag, item_slot]
 }
 
-/// Body of `CMSG_AUTOEQUIP_ITEM` (VERIFIED vmangos `AutoEquipItem::ReadFromWorldPacket`,
-/// `Server/Packets/Item.cpp:17-21` + `.h:31-39`; opcode 266 `Opcodes_1_12_1.h:269`): source
-/// `srcbag`/`srcslot` (both `uint8`), the same bag addressing as [`use_item`]. The real client
-/// sends this — not USE_ITEM — when the clicked bag item is *equippable* (the equip-vs-use fork is
-/// client-side); the server picks the destination slot itself. Refusals answer
-/// `SMSG_INVENTORY_CHANGE_FAILURE`.
+/// Body of `CMSG_AUTOEQUIP_ITEM` (opcode 266, `Server/Packets/Item.cpp:17-21`): source bag and
+/// slot. The reference sends it instead of `CMSG_USE_ITEM` for an equippable item; the server
+/// picks the slot.
 pub fn auto_equip_item(bag_index: u8, slot: u8) -> Vec<u8> {
     vec![bag_index, slot]
 }
 
-/// Body of `CMSG_AUTOSTORE_BAG_ITEM` (VERIFIED vmangos `AutoStoreBagItem::ReadFromWorldPacket`,
-/// `Server/Packets/Item.cpp:23-28` + `.h:41-49`; opcode 267 `Opcodes_1_12_1.h:270`): `srcbag`,
-/// `srcslot`, `dstbag` — all `uint8`. "Auto-store this item into that bag, server picks the slot."
-/// Builder only tonight (backpack-internal moves take [`swap_inv_item`]); no UI path yet.
+/// Body of `CMSG_AUTOSTORE_BAG_ITEM` (opcode 267, `Server/Packets/Item.cpp:23-28`): source bag
+/// and slot, then the bag to store into; the server picks the slot.
 pub fn auto_store_bag_item(src_bag: u8, src_slot: u8, dst_bag: u8) -> Vec<u8> {
     vec![src_bag, src_slot, dst_bag]
 }
 
-/// Body of `CMSG_SWAP_ITEM` (VERIFIED vmangos `SwapItem::ReadFromWorldPacket`,
-/// `Server/Packets/Item.cpp:30-36` + `.h:51-61`; opcode 268 `Opcodes_1_12_1.h:271`): `dstbag`,
-/// `dstslot`, `srcbag`, `srcslot` — all `uint8`, **destination FIRST**. The general bag↔bag move
-/// (either endpoint an equipped bag). Builder only tonight; the windowed backpack's internal moves
-/// go out as [`swap_inv_item`].
+/// Body of `CMSG_SWAP_ITEM` (opcode 268, `Server/Packets/Item.cpp:30-36`): destination bag and
+/// slot first, then the source; a move with an equipped bag at either end.
 pub fn swap_item(dst_bag: u8, dst_slot: u8, src_bag: u8, src_slot: u8) -> Vec<u8> {
     vec![dst_bag, dst_slot, src_bag, src_slot]
 }
 
-/// Body of `CMSG_SWAP_INV_ITEM` (VERIFIED vmangos `SwapInvItem::ReadFromWorldPacket`,
-/// `Server/Packets/Item.cpp:38-42` + `.h:63-72`; opcode 269 `Opcodes_1_12_1.h:272`): `srcslot`,
-/// `dstslot` — two `uint8` player-array slots, both implicitly on the player itself
-/// (`INVENTORY_SLOT_BAG_0`). This is the wire for a backpack-internal pick/place/swap: both slots
-/// are `INVENTORY_SLOT_ITEM_START`+i (see [`SLOT_PACK_FIRST`]). An empty destination is still a
-/// swap on this wire — the server treats it as a move.
+/// Body of `CMSG_SWAP_INV_ITEM` (opcode 269, `Server/Packets/Item.cpp:38-42`): source then
+/// destination slot in the player's own array; an empty destination makes it a move.
 pub fn swap_inv_item(src_slot: u8, dst_slot: u8) -> Vec<u8> {
     vec![src_slot, dst_slot]
 }
 
-/// Body of `CMSG_SPLIT_ITEM` (VERIFIED vmangos `SplitItem::ReadFromWorldPacket`,
-/// `Server/Packets/Item.cpp:44-51` + `.h:74-85`; opcode 270 `Opcodes_1_12_1.h:273`): `srcbag`,
-/// `srcslot`, `dstbag`, `dstslot`, `count` — all `uint8`. Builder only: the UI split dialog is out
-/// of scope, but the wire is pinned so a later stack-split slice has a byte-exact starting point.
+/// Body of `CMSG_SPLIT_ITEM` (opcode 270, `Server/Packets/Item.cpp:44-51`): source bag and slot,
+/// destination bag and slot, count.
 pub fn split_item(src_bag: u8, src_slot: u8, dst_bag: u8, dst_slot: u8, count: u8) -> Vec<u8> {
     vec![src_bag, src_slot, dst_bag, dst_slot, count]
 }
 
-/// Body of `CMSG_DESTROYITEM` (VERIFIED vmangos `Packets/Item.cpp:59-68`; opcode 273
-/// `Opcodes_1_12_1.h`): `bag`, `slot`, `count` (0 = the whole stack — matches [`split_item`]'s
-/// count and the app's `container_destroys` triple), then THREE more `uint8`s the server reads
-/// off the wire and discards — the real client sends them, so the body stays 6 bytes rather than
-/// a shorter, non-matching one. Decision 0216 §3: the delete-confirm popup's `OnAccept`
-/// (`DeleteCursorItem`).
+/// Body of `CMSG_DESTROYITEM` (opcode 273, `Packets/Item.cpp:59-68`): bag, slot, count (0 for the
+/// whole stack), then three bytes the reference sends and the server discards.
 pub fn destroy_item(bag: u8, slot: u8, count: u8) -> Vec<u8> {
     vec![bag, slot, count, 0, 0, 0]
 }
 
-/// Body of `CMSG_SET_AMMO` (VERIFIED wow-re `cursor-dragdrop-slots.md`: the client's auto-equip
-/// sender `0x5e1480` forks ammo-class → opcode `0x268`, body `{itemEntry}` (a single `u32`); the
-/// vmangos handler `HandleSetAmmoOpcode` reads the same lone `uint32` entry). Unlike every other
-/// item CMSG this is NOT a `(bag, slot)` address — ammo is loaded by item *entry*, and the stack
-/// stays put in the bag (`PLAYER_AMMO_ID` just references it). The server refuses a mismatch
-/// (`EQUIP_ERR_ONLY_AMMO_CAN_GO_HERE` &c.) via `SMSG_INVENTORY_CHANGE_FAILURE`. Decision 0526.
+/// Body of `CMSG_SET_AMMO` (opcode `0x268`): the ammo's item entry, not a bag and slot; the
+/// reference's auto-equip sender (`0x5e1480`) sends it for ammo, and the stack stays in its bag.
 pub fn set_ammo(entry: u32) -> Vec<u8> {
     entry.to_le_bytes().to_vec()
 }
 
-/// Read `SMSG_INVENTORY_CHANGE_FAILURE` (VERIFIED vmangos `InventoryChangeFailure::AppendBodyTo`):
-/// `u8 reason` (`InventoryResult`; 0 = OK, no tail), then — only when failed — a `u32` required
-/// level *iff* `reason == 1` (`CANT_EQUIP_LEVEL_I`), the two full item guids, and the bag slot.
-///
-/// The trailing `u8` is **the destination bag's absolute player slot**, not a subslot: vmangos
-/// declares it *"slot of target bag that has storing condition (can be InventorySlots or
-/// BankBagSlots)"* and fills it with `bagSlot = bag` at each `CanStoreItem` refusal
-/// (`Player.cpp:8899`ff), where `bag` is `INVENTORY_SLOT_BAG_0` (255, the player's own array) or
-/// an equipped bag's slot. The reference reads it the same way — its reason-16 helper
-/// `0x5ede00` bails on `slot == 0xFF` and otherwise indexes the player's slot array by it (wow-re
-/// `inventory-change-failure-display.md` §6). It is the `%s` source of *"Only Arrows can be
-/// placed in that."*; see `benilla::ui_items::feed`.
-///
-/// Returns `(reason, required_level, item_guid, bag_slot)`.
+/// Read `SMSG_INVENTORY_CHANGE_FAILURE` into `(reason, required_level, item_guid, bag_slot)`: a
+/// `u8` reason and, unless it is 0, a `u32` level for reason 1 only, two item guids and a bag
+/// slot. That slot is the target bag's player-array slot, 255 for the player's own
+/// (`Player.cpp:8899`); the reference names that bag in reason 16's message (`0x5ede00`).
 pub(super) fn read_inventory_change_failure(
     r: &mut &[u8],
 ) -> io::Result<(u8, Option<u32>, u64, u8)> {
@@ -805,30 +584,29 @@ pub(super) fn read_inventory_change_failure(
     Ok((reason, required_level, item_guid, bag_slot))
 }
 
-/// Read `SMSG_ITEM_TIME_UPDATE` (VERIFIED vmangos `Item::SendTimeUpdate`,
-/// `Objects/Item.cpp:1096-1106`): the item guid, then the remaining **seconds**
-/// (`ITEM_FIELD_DURATION`, which vmangos counts down in seconds — `Item::UpdateDuration`,
-/// `Item.cpp:243-257`). No trailing player guid on this one, unlike its enchant sibling: the
-/// packet is `(8 + 4)` bytes and vmangos sizes it exactly so.
-///
-/// Sent on world enter for every carried duration item (`Player::SendItemDurations`,
-/// `Player.cpp:12007`) and again whenever one is created or its duration changes
-/// (`Player.cpp:19782-19785`).
+/// Read `SMSG_ITEM_TIME_UPDATE` (`Objects/Item.cpp:1096-1106`): item guid, then seconds left, and
+/// no player guid after. Sent for every duration item on world enter and on each change.
 pub(super) fn read_item_time(r: &mut &[u8]) -> io::Result<(u64, u32)> {
     let item_guid = read_u64_le(r)?;
     let seconds = read_u32_le(r)?;
     Ok((item_guid, seconds))
 }
 
-/// Read `SMSG_ITEM_ENCHANT_TIME_UPDATE` (VERIFIED vmangos
-/// `WorldPackets::Item::ItemEnchantTimeUpdate::AppendBodyTo`, `Server/Packets/Item.cpp:161-169`):
-/// item guid, enchant **slot**, remaining **seconds**, then the owning player's guid (present from
-/// build 1.10.2 up, so always in 1.12). Returns `(item_guid, slot, seconds)`; the trailing player
-/// guid is dropped — the packet only ever concerns our own items and the item guid already names
-/// which one.
-///
-/// `seconds == 0` means expired, and the reference stores that as **no timer** (`0x5d9cc0` writes
-/// a `0` deadline whenever `seconds <= 0`), not as "0 seconds left".
+/// Read `SMSG_OPEN_CONTAINER`, the bag's guid, sent when an auto-equip lands in a bag slot
+/// (`ItemHandler.cpp:227`); the reference fires only `BAG_OPEN` from it.
+pub(super) fn read_open_container(r: &mut &[u8]) -> io::Result<u64> {
+    read_u64_le(r)
+}
+
+/// Read `SMSG_INSPECT`, the echoed target guid (`MiscHandler.cpp:957`); the reference's handler
+/// (`0x5e7d70`) ignores it.
+pub(super) fn read_inspect(r: &mut &[u8]) -> io::Result<u64> {
+    read_u64_le(r)
+}
+
+/// Read `SMSG_ITEM_ENCHANT_TIME_UPDATE` (`Server/Packets/Item.cpp:161-169`): item guid, slot,
+/// seconds, then our own guid, left unread. The reference stores 0 seconds as no timer
+/// (`0x5d9cc0`), not as a timer at zero.
 pub(super) fn read_item_enchant_time(r: &mut &[u8]) -> io::Result<(u64, u32, u32)> {
     let item_guid = read_u64_le(r)?;
     let slot = read_u32_le(r)?;
@@ -840,11 +618,34 @@ pub(super) fn read_item_enchant_time(r: &mut &[u8]) -> io::Result<(u64, u32, u32
 mod tests {
     use super::*;
 
-    // The `SMSG_ITEM_QUERY_SINGLE_RESPONSE` parse goldens (hit + miss, byte-exact against the
-    // vmangos field order) live in `tests/items.rs` — one home, no drifting twins.
+    // The query-response parse goldens are in `tests/items.rs`; do not duplicate them here.
 
-    // Byte-exact encode goldens — the item-move CMSG bodies (VERIFIED field order + widths against
-    // vmangos `Server/Packets/Item.cpp` `ReadFromWorldPacket`s; every field is a `uint8`).
+    // Item-move body goldens follow vmangos `Server/Packets/Item.cpp`; every field is a `u8`.
+
+    #[test]
+    fn open_container_decodes() {
+        let body = 0x4000_0000_0012_3456u64.to_le_bytes();
+        match crate::messages::parse_server(crate::messages::opcode::SMSG_OPEN_CONTAINER, &body)
+            .unwrap()
+        {
+            crate::messages::ServerPacket::OpenContainer { item } => {
+                assert_eq!(item, 0x4000_0000_0012_3456);
+            }
+            other => panic!("expected OpenContainer, got {}", other.name()),
+        }
+    }
+
+    #[test]
+    fn inspect_decodes_and_is_ignored() {
+        let body = 0x0000_0000_0000_0007u64.to_le_bytes();
+        let packet =
+            crate::messages::parse_server(crate::messages::opcode::SMSG_INSPECT, &body).unwrap();
+        assert!(matches!(
+            packet,
+            crate::messages::ServerPacket::Inspect { guid: 7 }
+        ));
+        assert!(crate::events::decode(packet).is_empty());
+    }
 
     #[test]
     fn auto_equip_item_body() {
@@ -854,8 +655,10 @@ mod tests {
 
     #[test]
     fn wrap_item_body_paper_first() {
-        // 467: giftbag, giftslot, itembag, itemslot (Item.cpp:121-127) — the PAPER's pair leads.
+        // 467: giftbag, giftslot, itembag, itemslot (Item.cpp:121-127).
         assert_eq!(wrap_item(255, 23, 255, 24), vec![255, 23, 255, 24]);
+        // Paper in the first bag's slot 3, the target in backpack slot 24: four distinct bytes.
+        assert_eq!(wrap_item(19, 3, 255, 24), vec![19, 3, 255, 24]);
     }
 
     #[test]
@@ -866,19 +669,19 @@ mod tests {
 
     #[test]
     fn swap_item_body_destination_first() {
-        // 268: dstbag, dstslot, srcbag, srcslot — destination pair FIRST (Item.cpp:30-36).
+        // 268: dstbag, dstslot, srcbag, srcslot (Item.cpp:30-36).
         assert_eq!(swap_item(19, 3, 255, 30), vec![19, 3, 255, 30]);
     }
 
     #[test]
     fn swap_inv_item_body() {
-        // 269: srcslot, dstslot (Item.cpp:38-42). Backpack slot 1↔2 = player-array 23↔24.
+        // 269: srcslot, dstslot (Item.cpp:38-42); backpack slots 1 and 2 are 23 and 24.
         assert_eq!(swap_inv_item(23, 24), vec![23, 24]);
     }
 
     #[test]
     fn set_ammo_body() {
-        // 616 (0x268): a lone little-endian u32 item entry (wow-re cursor-dragdrop-slots.md).
+        // 616 (0x268): a lone little-endian u32 item entry.
         assert_eq!(set_ammo(0x0001_6b74), vec![0x74, 0x6b, 0x01, 0x00]);
     }
 
@@ -894,13 +697,10 @@ mod tests {
         assert_eq!(destroy_item(255, 23, 0), vec![255, 23, 0, 0, 0, 0]);
     }
 
-    // SMSG_INVENTORY_CHANGE_FAILURE parse — both branches of the conditional `requiredLevel u32`
-    // (VERIFIED vmangos `InventoryChangeFailure::AppendBodyTo`, `Item.cpp:198-209`;
-    // EQUIP_ERR_CANT_EQUIP_LEVEL_I = 1, `Objects/ItemDefines.h`).
+    // Reason 1 is `EQUIP_ERR_CANT_EQUIP_LEVEL_I` (`Objects/ItemDefines.h`, `Item.cpp:198-209`).
 
     #[test]
     fn inventory_failure_ok_reason_is_bare() {
-        // reason 0 (EQUIP_ERR_OK) ships no tail.
         let buf = [0u8];
         let mut r = &buf[..];
         assert_eq!(
@@ -911,7 +711,6 @@ mod tests {
 
     #[test]
     fn inventory_failure_level_branch_reads_the_u32() {
-        // reason 1 (CANT_EQUIP_LEVEL_I): requiredLevel u32, item1Guid u64, item2Guid u64, bagSlot u8.
         let mut buf = Vec::new();
         buf.push(1u8); // reason
         buf.extend_from_slice(&40u32.to_le_bytes()); // requiredLevel
@@ -925,9 +724,6 @@ mod tests {
         );
     }
 
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE`'s body, byte-exact against vmangos's writer: guid, slot,
-    /// seconds, then the player guid we drop. Pinned because a wrong width here would silently
-    /// park a garbage deadline (decision 0920).
     #[test]
     fn item_enchant_time_reads_guid_slot_seconds() {
         let mut buf = Vec::new();
@@ -940,13 +736,10 @@ mod tests {
             read_item_enchant_time(&mut r).unwrap(),
             (0x4000_0000_0000_00f7, 1, 600)
         );
-        // The trailing player guid stays unread — the reader consumes exactly its three fields.
+        // The trailing player guid stays unread.
         assert_eq!(r.len(), 8);
     }
 
-    /// `SMSG_ITEM_TIME_UPDATE`'s body: guid then seconds, and **nothing after** — the enchant
-    /// twin's trailing player guid is not on this packet (vmangos sizes it `8 + 4`). Pinned
-    /// because the two share a handler and it would be easy to copy the wrong tail.
     #[test]
     fn item_time_reads_guid_then_seconds() {
         let mut buf = Vec::new();
@@ -962,9 +755,8 @@ mod tests {
 
     #[test]
     fn inventory_failure_nonlevel_branch_has_no_u32() {
-        // Any failed reason != 1 skips requiredLevel: item1Guid u64, item2Guid u64, bagSlot u8.
         let mut buf = Vec::new();
-        buf.push(3u8); // reason (ITEM_DOESNT_GO_TO_SLOT) — no requiredLevel
+        buf.push(3u8); // reason (ITEM_DOESNT_GO_TO_SLOT)
         buf.extend_from_slice(&0xDEAD_BEEF_0000_0001u64.to_le_bytes()); // item1
         buf.extend_from_slice(&0u64.to_le_bytes()); // item2
         buf.push(0); // bagSlot
diff --git a/crates/benilla-protocol/src/messages/loot.rs b/crates/benilla-protocol/src/messages/loot.rs
index 7f5e23ad..9317243b 100644
--- a/crates/benilla-protocol/src/messages/loot.rs
+++ b/crates/benilla-protocol/src/messages/loot.rs
@@ -1,25 +1,12 @@
-//! Loot messages — the solo-loot wire family (opcodes 264, 349-355, 357-358; VERIFIED vmangos
-//! `Server/Protocol/Opcodes_1_12_1.h:267,350-359`). Bodies from vmangos `Server/Packets/Loot.{h,cpp}`
-//! (the light client-read / server-append shapes) + the hand-serialized `LootMgr.cpp`
-//! (`operator<<(LootItem)`/`operator<<(LootView)`) and `Player.cpp` (`SendLoot`/`SendLootError`).
-//! The group-roll family (opcodes 670-674 — `SMSG_LOOT_START_ROLL`/`SMSG_LOOT_ROLL`/
-//! `SMSG_LOOT_ROLL_WON`/`SMSG_LOOT_ALL_PASSED` + our `CMSG_LOOT_ROLL`) rides here too, from
-//! vmangos `Group/Group.cpp`'s four senders (decision 0591). Master loot
-//! (`CMSG_LOOT_MASTER_GIVE` 675 / `SMSG_LOOT_MASTER_LIST` 676) lands here too, from
-//! `Group::MasterLoot` + `WorldSession::HandleLootMasterGiveOpcode` (decision 1675).
+//! Loot wire messages: the loot window, group rolls, master loot and item-push results.
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_u32_le, read_u64_le, read_u8};
 
-/// One item row on the normal shape of `SMSG_LOOT_RESPONSE` (vmangos `LootMgr.cpp:837-845` the
-/// `LootItem` write, wrapped by the slot index + trailing slot-type byte the caller appends around
-/// it — `LootMgr.cpp:900-912`, `ALL_PERMISSION` branch, the solo-loot path). `slot` is the wire's
-/// 0-based loot-window slot — what [`autostore_loot_item`] addresses back; a quest item rides the
-/// same list with `slot = items.len() + i` (`LootMgr.cpp:970`, out of the solo drop-loot path but
-/// parsed the same way if ever present). The wire's `randomSuffix` field is **not** a real per-item
-/// value — the server always writes a literal `0` there (`LootMgr.cpp:841`) — so this parser reads
-/// and discards it.
+/// One item row of `SMSG_LOOT_RESPONSE` (vmangos `LootMgr.cpp:837-845,900-912`). `slot` is the
+/// 0-based wire slot that [`autostore_loot_item`] sends back; quest items follow at
+/// `items.len() + i` (`LootMgr.cpp:970`). The wire's `randomSuffix` is always 0 and is discarded.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LootItem {
     pub slot: u8,
@@ -28,44 +15,27 @@ pub struct LootItem {
     /// `item_template.display_id` → icon via `ItemDisplayInfo.dbc`.
     pub display_info_id: u32,
     pub random_property_id: u32,
-    /// A [`slot_type`] code. Solo paths (`ALL_PERMISSION`/`OWNER_PERMISSION`) always write
-    /// `ALLOW_LOOT` (`LootMgr.cpp:918-926`); `MASTER` rides the master-loot path (decision 1675),
-    /// `ROLL_ONGOING` a group roll in flight, `LOCKED` a requirement the viewer fails.
+    /// A [`slot_type`] code; solo looting always writes `ALLOW_LOOT` (`LootMgr.cpp:918-926`).
     pub slot_type: u8,
 }
 
-/// `LootSlotType` (VERIFIED vmangos `LootMgr.h:75-83`) — the `u8` riding after each [`LootItem`] on
-/// `SMSG_LOOT_RESPONSE`.
+/// `LootSlotType` (vmangos `LootMgr.h:75-83`): the `u8` that ends each [`LootItem`] row.
 pub mod slot_type {
-    /// The player can loot the item.
     pub const ALLOW_LOOT: u8 = 0;
-    /// A group roll is ongoing on this item — shown, not yet lootable.
+    /// A group roll is in progress on this item: shown, not yet lootable.
     pub const ROLL_ONGOING: u8 = 1;
-    /// Only the group's loot master can distribute this item — the row is not takeable by a
-    /// `CMSG_AUTOSTORE_LOOT_ITEM` from anyone, and the master looter assigns it with
-    /// [`loot_master_give`] instead (decision 1675).
-    ///
-    /// **vmangos stamps this on *every* row it shows a group member under master loot**
-    /// (`LootMgr.cpp:917-941`, the `MASTER_PERMISSION` arm, which never consults
-    /// `is_underthreshold`) — even greys, which the server's own take handler would have allowed
-    /// (`LootHandler.cpp:171-182`). `LootItem::GetSlotTypeForSharedLoot` (`LootMgr.cpp:443-459`)
-    /// encodes the threshold-aware answer but is not on this path. So under vmangos the whole
-    /// window reads as master-only; we render the wire (decision 0086's rule).
+    /// Only the loot master can hand this out ([`loot_master_give`]). Under master loot vmangos
+    /// sends it on every row, even greys its take handler allows (`LootMgr.cpp:917-941`).
     pub const MASTER: u8 = 2;
-    /// Shown red — not lootable (a missing-requirement item in a group).
+    /// Shown red and not lootable: a requirement the viewer fails, in a group.
     pub const LOCKED: u8 = 3;
     /// Owner-permission solo looting, binding checks skipped.
     pub const OWNER: u8 = 4;
 }
 
-/// `LootType` (VERIFIED vmangos `LootMgr.h:49-61`) — the `u8` naming what's being looted on the
-/// normal shape of `SMSG_LOOT_RESPONSE`. Only 4 values ever reach the wire: `Player::SendLoot`
-/// (`Player.cpp:8117-8131`) remaps `SKINNING`(6)/`INSIGNIA`(22) to `PICKPOCKETING` and
-/// `FISHING_HOLE`(20)/`FISHING_FAIL`(21) to `FISHING` before sending — the client has no separate
-/// UI state for those. `CMSG_LOOT` (a corpse/creature loot request) always answers with `CORPSE`
-/// (`LootHandler.cpp:340-354`, `HandleLootOpcode` → `SendLoot(guid, LOOT_CORPSE)` unconditionally);
-/// the rest arrive only from other loot sources (pickpocket spell, fishing, disenchant), out of
-/// scope for this slice but pinned for completeness.
+/// `LootType` (vmangos `LootMgr.h:49-61`). Only these four reach the wire: `SendLoot` remaps
+/// skinning and insignia to `PICKPOCKETING`, fishing holes and fails to `FISHING`
+/// (`Player.cpp:8117-8131`); `CMSG_LOOT` always gets `CORPSE` (`LootHandler.cpp:340-354`).
 pub mod loot_type {
     pub const CORPSE: u8 = 1;
     pub const PICKPOCKETING: u8 = 2;
@@ -73,16 +43,10 @@ pub mod loot_type {
     pub const DISENCHANTING: u8 = 4;
 }
 
-/// `LootError` (VERIFIED vmangos `LootMgr.h:85-100`) — the `u8` on the error shape of
-/// `SMSG_LOOT_RESPONSE` (`Player::SendLootError`, `Player.cpp:7744-7750`). A plain `CMSG_LOOT` on a
-/// creature corpse can only surface a subset: `DIDNT_KILL` (guid isn't a lootable
-/// creature/player/corpse, or the creature check fails — `LootHandler.cpp:342-346`,
-/// `Player.cpp:7938-7943`), `PLAYER_NOT_FOUND` (dead/not-in-world — `LootHandler.cpp:349-353`),
-/// `PLAY_TIME_EXCEEDED`, `NOTSTANDING`, `STUNNED` (`LootHandler.cpp:358-373`), and `TOO_FAR`
-/// (range check in `Player.cpp:7938-7947`). The `MASTER_*` trio answers a refused
-/// [`loot_master_give`] and reaches only the master looter (`LootHandler.cpp:618-750`, decision
-/// 1675); `BAD_FACING`/`LOCKED`/`ALREADY_PICKPOCKETED`/`NOT_WHILE_SHAPESHIFTED` ride other loot
-/// sources, pinned for completeness.
+/// `LootError` (vmangos `LootMgr.h:85-100`): the code on the error shape of `SMSG_LOOT_RESPONSE`.
+/// `CMSG_LOOT` can draw `DIDNT_KILL`, `PLAYER_NOT_FOUND`, `PLAY_TIME_EXCEEDED`, `NOTSTANDING`,
+/// `STUNNED` (`LootHandler.cpp:342-373`) and `TOO_FAR` (`Player.cpp:7938-7947`); the `MASTER_*`
+/// codes answer a refused [`loot_master_give`], to the master looter only.
 pub mod loot_error {
     pub const DIDNT_KILL: u8 = 0;
     pub const TOO_FAR: u8 = 4;
@@ -99,70 +63,49 @@ pub mod loot_error {
     pub const NOT_WHILE_SHAPESHIFTED: u8 = 16;
 }
 
-/// The two shapes `SMSG_LOOT_RESPONSE` can take, disambiguated by the `lootType` byte right after
-/// the guid: `0` means "no window — this is an error", anything else is a real loot window.
+/// The two shapes of `SMSG_LOOT_RESPONSE`: a `lootType` of 0 after the guid is the error shape.
 #[derive(Debug, Clone, PartialEq)]
 pub enum LootResponseBody {
-    /// The normal shape (VERIFIED vmangos `Player.cpp:8135-8138` + `operator<<(LootView)`,
-    /// `LootMgr.cpp:848-873`): `u32 gold, u8 itemCount`, then `itemCount` rows of [`LootItem`].
+    /// `u32 gold, u8 itemCount`, then the [`LootItem`] rows (vmangos `LootMgr.cpp:848-873`).
     Items {
         loot_type: u8,
         gold: u32,
         items: Vec<LootItem>,
     },
-    /// The error shape (VERIFIED vmangos `Player::SendLootError`, `Player.cpp:7744-7750`): just
-    /// the trailing `u8` error code, nothing else follows.
+    /// Only a [`loot_error`] code follows (`Player.cpp:7744-7750`).
     Error { error: u8 },
 }
 
-/// Body of `CMSG_LOOT` (VERIFIED vmangos `Server/Packets/Loot.cpp:8-11`,
-/// `LootUnit::ReadFromWorldPacket`): one full 8-byte guid — the corpse/creature/player being
-/// opened. Always answered by `SMSG_LOOT_RESPONSE` (one shape or the other).
+/// `CMSG_LOOT` (`Loot.cpp:8-11`): the guid to open, always answered by `SMSG_LOOT_RESPONSE`.
 pub fn loot(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_AUTOSTORE_LOOT_ITEM` (VERIFIED vmangos `Server/Packets/Loot.cpp:3-6`,
-/// `AutoStoreLootItem::ReadFromWorldPacket`): one `u8` — the 0-based wire loot slot (see
-/// [`LootItem::slot`]). The server auto-places the item into the first free bag slot
-/// (`LootHandler.cpp:183-206`, `CanStoreNewItem`/`StoreNewItem`); no specific-slot variant exists
-/// for loot (unlike vendor buy).
+/// `CMSG_AUTOSTORE_LOOT_ITEM` (`Loot.cpp:3-6`): a [`LootItem::slot`]; the server picks the bag.
 pub fn autostore_loot_item(loot_slot: u8) -> Vec<u8> {
     vec![loot_slot]
 }
 
-/// Body of `CMSG_LOOT_MONEY` (VERIFIED vmangos `Server/Protocol/Opcodes_1_12_1.h:351` — the
-/// handler `WorldSession::HandleLootMoneyOpcode` takes a `NullClientPacket`): empty.
+/// `CMSG_LOOT_MONEY`: an empty body (vmangos `Opcodes_1_12_1.h:351`).
 pub fn loot_money() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_LOOT_RELEASE` (VERIFIED vmangos `Server/Packets/Loot.cpp:13-16`,
-/// `LootRelease::ReadFromWorldPacket`): one full 8-byte guid, though the server ignores it and
-/// releases whatever loot guid it has stored for us instead (`Server/Packets/Loot.h:31-36`: "not
-/// used by server"; handler `HandleLootReleaseOpcode`, `LootHandler.cpp:383-389`).
+/// `CMSG_LOOT_RELEASE` (`Loot.cpp:13-16`): a guid the server ignores for the loot guid it stored.
 pub fn loot_release(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// `RollVote` (VERIFIED vmangos `Group/Group.h:88-99`) — the `u8` vote a client may cast on
-/// `CMSG_LOOT_ROLL`. The server hard-rejects anything `>= 3` (`MAX_ROLL_FROM_CLIENT`,
-/// `GroupHandler.cpp:367-368`), so these three are the whole client-side vocabulary; `Group.h`'s
-/// `ROLL_NOT_EMITED_YET`(3)/`ROLL_NOT_VALID`(4) are server bookkeeping that never reaches us.
-///
-/// These same values also ride *back* as `SMSG_LOOT_ROLL`/`SMSG_LOOT_ROLL_WON`'s `roll_type` —
-/// but there they are **not** self-describing: see [`LootRoll::is_dice`] for the disambiguation.
+/// `RollVote` (vmangos `Group/Group.h:88-99`): the server rejects a vote `>= 3`
+/// (`GroupHandler.cpp:367-368`). Overloaded on `SMSG_LOOT_ROLL`: see [`LootRoll::is_dice`].
 pub mod roll_vote {
     pub const PASS: u8 = 0;
     pub const NEED: u8 = 1;
     pub const GREED: u8 = 2;
 }
 
-/// Body of `CMSG_LOOT_ROLL` (VERIFIED vmangos `Server/Packets/Loot.cpp:18-23`,
-/// `LootRoll::ReadFromWorldPacket`): `u64 lootedTarget, u32 itemSlot, u8 rollType` — the corpse
-/// guid + wire loot slot that identify *which* roll, and our [`roll_vote`]. The pair
-/// `(lootedTarget, itemSlot)` is the roll's server-side identity; the client-side `rollID` the
-/// FrameXML API passes around is ours alone and never reaches the wire.
+/// `CMSG_LOOT_ROLL` (`Loot.cpp:18-23`): `u64 lootedTarget, u32 itemSlot, u8 rollType`. The
+/// corpse and slot identify the roll; the FrameXML `rollID` never reaches the wire.
 pub fn loot_roll(looted_target: u64, item_slot: u32, roll_type: u8) -> Vec<u8> {
     let mut body = looted_target.to_le_bytes().to_vec();
     body.extend_from_slice(&item_slot.to_le_bytes());
@@ -170,15 +113,8 @@ pub fn loot_roll(looted_target: u64, item_slot: u32, roll_type: u8) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_LOOT_MASTER_GIVE` (VERIFIED vmangos `Server/Packets/Loot.{h:50-59,cpp:25-30}`,
-/// `LootMasterGive::ReadFromWorldPacket`): `u64 lootGuid, u8 slotId, u64 playerGuid` — the open
-/// loot source, the **wire** loot slot (see [`LootItem::slot`], not the display row), and the
-/// group member to hand the item to.
-///
-/// Sent only by the master looter; the server re-checks all three (`LootHandler.cpp:618-750`) and
-/// answers a refusal with a [`loot_error`] `MASTER_*` code on `SMSG_LOOT_RESPONSE`. Note the slot
-/// width: this one is a `u8` where the roll family's `item_slot` is a `u32`, so the two are not
-/// interchangeable even though they index the same array.
+/// `CMSG_LOOT_MASTER_GIVE` (`Loot.cpp:25-30`): `u64 lootGuid, u8 slotId, u64 playerGuid`; the
+/// slot is a `u8` here, a `u32` in the roll family. A refusal is a `MASTER_*` [`loot_error`].
 pub fn loot_master_give(loot_guid: u64, slot: u8, player_guid: u64) -> Vec<u8> {
     let mut body = loot_guid.to_le_bytes().to_vec();
     body.push(slot);
@@ -186,69 +122,40 @@ pub fn loot_master_give(loot_guid: u64, slot: u8, player_guid: u64) -> Vec<u8> {
     body
 }
 
-/// `SMSG_LOOT_START_ROLL` (VERIFIED vmangos `Server/Packets/Loot.{h:78-90,cpp:43-51}`) — a group
-/// roll opened on one drop; sent to every eligible roller. `countdown_ms` is the server's
-/// `LOOT_ROLL_TIMEOUT`, a flat `1*MINUTE*IN_MILLISECONDS` = `60_000` at 5875
-/// (`Group/Group.cpp:67`), but it is read from the wire rather than assumed.
-///
-/// The wire's `randomSuffix` field is a literal `0` the server never fills (`Group.cpp:764`), so
-/// this parser reads and discards it — same treatment as [`LootItem`]'s.
+/// `SMSG_LOOT_START_ROLL` (`Loot.cpp:43-51`): a group roll opened on one drop, sent to every
+/// eligible roller. Its `randomSuffix` is always 0 (`Group/Group.cpp:764`) and is discarded.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LootStartRoll {
-    /// The corpse/container being looted — with `item_slot`, the roll's wire identity.
     pub looted_target: u64,
-    /// The 0-based **wire** loot slot (the same vocabulary as [`LootItem::slot`], widened to `u32`
-    /// here because this packet carries it as one).
+    /// The wire [`LootItem::slot`], carried as a `u32` here.
     pub item_slot: u32,
     pub item_id: u32,
     pub random_property_id: u32,
-    /// How long the roll stays open, in milliseconds.
+    /// How long the roll stays open, in ms (vmangos: `60_000`, `Group.cpp:67`).
     pub countdown_ms: u32,
 }
 
-/// `SMSG_LOOT_ROLL` (VERIFIED vmangos `Server/Packets/Loot.{h:92-106,cpp:53-63}`) — one
-/// announcement about one roller, broadcast to every eligible roller.
-///
-/// **The `(roll_number, roll_type)` pair is overloaded** and this is the load-bearing subtlety of
-/// the whole family. vmangos emits exactly four shapes (VERIFIED `Group/Group.cpp:970-990` for the
-/// votes, `:1163`/`:1214` for the dice):
-///
-/// | `roll_number` | `roll_type` | meaning                                    |
-/// |---------------|-------------|--------------------------------------------|
-/// | `0`           | `0`         | that player **voted** Need                  |
-/// | `128`         | `128`       | that player **voted** Pass                  |
-/// | `128`         | `2`         | that player **voted** Greed                 |
-/// | `1..=100`     | `1` or `2`  | that player's **dice result** (Need/Greed)  |
-///
-/// So `roll_type` alone cannot tell a Greed *vote* (`128, 2`) from a Greed *dice roll*
-/// (`57, 2`) — `roll_number` is the discriminator. [`LootRoll::is_dice`] encodes it.
+/// `SMSG_LOOT_ROLL` (`Loot.cpp:53-63`): one player's vote or dice roll, sent to every roller.
+/// `(roll_number, roll_type)` is overloaded: a vote is `(0, 0)` Need, `(128, 128)` Pass or
+/// `(128, 2)` Greed; a dice result is `(1..=100, 1 or 2)` (`Group/Group.cpp:970-990,1163,1214`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LootRoll {
     pub looted_target: u64,
     pub item_slot: u32,
-    /// The player this announcement is about — compare against our own guid for the "You …"
-    /// phrasing.
     pub roller: u64,
     pub item_id: u32,
     pub random_property_id: u32,
-    /// `1..=100` for a dice result; `0`/`128` for a vote announcement (see the type docs).
     pub roll_number: u8,
-    /// A [`roll_vote`] value for a dice result; `0`/`2`/`128` for a vote (see the type docs).
     pub roll_type: u8,
 }
 
 impl LootRoll {
-    /// Whether this is an actual **dice result** (`roll_number` in `1..=100`) rather than one of
-    /// the three vote announcements (`roll_number` `0` or `128`). See the type docs for the table
-    /// this encodes — vmangos only ever emits `urand(1, 100)` for real rolls (`Group.cpp:1162`,
-    /// `:1213`), and only `0`/`128` for votes, so the ranges cannot collide.
+    /// A dice result rather than a vote: vmangos rolls `urand(1, 100)` (`Group.cpp:1162,1213`).
     pub fn is_dice(&self) -> bool {
         (1..=100).contains(&self.roll_number)
     }
 
-    /// The vote this announcement reports when it is *not* a dice result — a [`roll_vote`] value.
-    /// `None` for a dice result (there `roll_type` is already a true [`roll_vote`]) or for a pair
-    /// outside the four shapes vmangos emits.
+    /// The [`roll_vote`] this announcement reports, when it is a vote.
     pub fn vote(&self) -> Option<u8> {
         match (self.roll_number, self.roll_type) {
             (0, 0) => Some(roll_vote::NEED),
@@ -259,9 +166,8 @@ impl LootRoll {
     }
 }
 
-/// `SMSG_LOOT_ROLL_WON` (VERIFIED vmangos `Server/Packets/Loot.{h:108-122,cpp:65-75}`) — the roll
-/// resolved and `winner` took the item. Note the field order differs from [`LootRoll`]: the winner
-/// guid lands *after* the item block, not before it.
+/// `SMSG_LOOT_ROLL_WON` (`Loot.cpp:65-75`): `winner` took the item. Unlike [`LootRoll`], the
+/// winner guid comes after the item fields.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LootRollWon {
     pub looted_target: u64,
@@ -269,21 +175,14 @@ pub struct LootRollWon {
     pub item_id: u32,
     pub random_property_id: u32,
     pub winner: u64,
-    /// The winning dice value (`1..=100`), or a literal `100` on the uncontested
-    /// single-eligible-roller short-circuit (`Group.cpp:1110`, sent with `ROLL_NEED`).
+    /// The winning dice value, or 100 with Need when only one player may roll (`Group.cpp:1110`).
     pub roll_number: u8,
-    /// A [`roll_vote`] value — which kind of roll won.
+    /// The [`roll_vote`] that won.
     pub roll_type: u8,
 }
 
-/// `SMSG_LOOT_ALL_PASSED` (VERIFIED vmangos `Server/Packets/Loot.{h:124-134,cpp:77-84}`) — nobody
-/// wanted it; the roll closes and the item returns to the corpse for ordinary looting.
-///
-/// **Field-order quirk:** unlike every other packet in this family, the append order here is
-/// `itemRandomPropId` **then** `randomSuffixId` (`Loot.cpp:79-83`) — the two `u32`s are swapped
-/// relative to [`LootStartRoll`]/[`LootRoll`]/[`LootRollWon`]. Both are effectively `0` in
-/// practice (the server never fills `randomSuffixId`), so the swap is invisible on the wire today,
-/// but the parser follows the source order rather than the family's.
+/// `SMSG_LOOT_ALL_PASSED` (`Loot.cpp:77-84`): everyone passed; the item stays for normal looting.
+/// Unlike the rest of the family, `itemRandomPropId` comes before `randomSuffixId` here.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LootAllPassed {
     pub looted_target: u64,
@@ -292,7 +191,6 @@ pub struct LootAllPassed {
     pub random_property_id: u32,
 }
 
-/// Read `SMSG_LOOT_START_ROLL` (see [`LootStartRoll`]).
 pub(super) fn read_loot_start_roll(r: &mut &[u8]) -> io::Result<LootStartRoll> {
     let looted_target = read_u64_le(r)?;
     let item_slot = read_u32_le(r)?;
@@ -309,7 +207,6 @@ pub(super) fn read_loot_start_roll(r: &mut &[u8]) -> io::Result<LootStartRoll> {
     })
 }
 
-/// Read `SMSG_LOOT_ROLL` (see [`LootRoll`] — including the overloaded `(roll_number, roll_type)`).
 pub(super) fn read_loot_roll(r: &mut &[u8]) -> io::Result<LootRoll> {
     let looted_target = read_u64_le(r)?;
     let item_slot = read_u32_le(r)?;
@@ -330,7 +227,6 @@ pub(super) fn read_loot_roll(r: &mut &[u8]) -> io::Result<LootRoll> {
     })
 }
 
-/// Read `SMSG_LOOT_ROLL_WON` (see [`LootRollWon`] — the winner guid follows the item block).
 pub(super) fn read_loot_roll_won(r: &mut &[u8]) -> io::Result<LootRollWon> {
     let looted_target = read_u64_le(r)?;
     let item_slot = read_u32_le(r)?;
@@ -351,13 +247,12 @@ pub(super) fn read_loot_roll_won(r: &mut &[u8]) -> io::Result<LootRollWon> {
     })
 }
 
-/// Read `SMSG_LOOT_ALL_PASSED` (see [`LootAllPassed`] — note the swapped `u32` pair).
 pub(super) fn read_loot_all_passed(r: &mut &[u8]) -> io::Result<LootAllPassed> {
     let looted_target = read_u64_le(r)?;
     let item_slot = read_u32_le(r)?;
     let item_id = read_u32_le(r)?;
     let random_property_id = read_u32_le(r)?;
-    let _random_suffix = read_u32_le(r)?; // the swapped tail — a literal 0 (Group.cpp:849)
+    let _random_suffix = read_u32_le(r)?; // the swapped tail, a literal 0 (Group.cpp:849)
     Ok(LootAllPassed {
         looted_target,
         item_slot,
@@ -366,19 +261,12 @@ pub(super) fn read_loot_all_passed(r: &mut &[u8]) -> io::Result<LootAllPassed> {
     })
 }
 
-/// Read `SMSG_LOOT_MASTER_LIST` (VERIFIED vmangos `Server/Packets/Group.{h:288-296,cpp:182-187}`,
-/// `LootMasterList::AppendBodyTo`): `u8 count`, then `count` full guids — the group members
-/// eligible to be handed an item from the loot window that is opening.
-///
-/// It rides the **open**, not a click: `Player::SendLoot` calls `Group::MasterLoot`
-/// (`Player.cpp:8077-8081`) before it writes `SMSG_LOOT_RESPONSE`, so the candidate list is
-/// already in hand by the time the window paints. vmangos sends it to *every* group member who
-/// opens the corpse, not only the master looter (the `MASTER_PERMISSION` arm is unconditional),
-/// and filters the list by loot-XP distance and `IsAllowedLooter` (`Group.cpp:914-940`).
+/// `SMSG_LOOT_MASTER_LIST` (vmangos `Server/Packets/Group.cpp:182-187`): `u8 count`, then the
+/// eligible members' guids. Every member who opens the corpse gets it just before
+/// `SMSG_LOOT_RESPONSE` (`Player.cpp:8077-8081`), filtered by range (`Group/Group.cpp:914-940`).
 pub(super) fn read_loot_master_list(r: &mut &[u8]) -> io::Result<Vec<u64>> {
     let count = read_u8(r)?;
-    // The candidates are group members (`Group.cpp:914-940`): vmangos `MAX_RAID_SIZE` 40
-    // (`Group/Group.h:50`).
+    // At most a raid: vmangos `MAX_RAID_SIZE` is 40 (`Group/Group.h:50`).
     let mut candidates = Vec::with_capacity(capacity_hint(count, 40));
     for _ in 0..count {
         candidates.push(read_u64_le(r)?);
@@ -386,11 +274,8 @@ pub(super) fn read_loot_master_list(r: &mut &[u8]) -> io::Result<Vec<u64>> {
     Ok(candidates)
 }
 
-/// Read `SMSG_LOOT_RESPONSE` — both shapes (see [`LootResponseBody`]). Wire order (VERIFIED
-/// vmangos `Player.cpp:8135-8138`): `u64 guid, u8 lootType`, then either the error tail (`lootType
-/// == 0`) or `u32 gold, u8 itemCount` + `itemCount` × [`LootItem`] rows (each `u8 slot, u32
-/// itemid, u32 count, u32 displayInfoID, u32 0(randomSuffix, discarded), u32 randomPropertyId, u8
-/// slotType` — `LootMgr.cpp:848-873,900-912`, the `ALL_PERMISSION` solo branch).
+/// `SMSG_LOOT_RESPONSE` (vmangos `Player.cpp:8135-8138`): `u64 guid, u8 lootType`, then the
+/// error code when `lootType` is 0, else gold and the [`LootItem`] rows.
 pub(super) fn read_loot_response(r: &mut &[u8]) -> io::Result<(u64, LootResponseBody)> {
     let guid = read_u64_le(r)?;
     let loot_type = read_u8(r)?;
@@ -400,8 +285,7 @@ pub(super) fn read_loot_response(r: &mut &[u8]) -> io::Result<(u64, LootResponse
     }
     let gold = read_u32_le(r)?;
     let count = read_u8(r)?;
-    // The loot view indexes both lists by one `u8`: `MAX_NR_LOOT_ITEMS` 16 + `MAX_NR_QUEST_ITEMS`
-    // 32 (vmangos `LootMgr.h:34,36`).
+    // `MAX_NR_LOOT_ITEMS` 16 + `MAX_NR_QUEST_ITEMS` 32 (vmangos `LootMgr.h:34,36`).
     let mut items = Vec::with_capacity(capacity_hint(count, 16 + 32));
     for _ in 0..count {
         let slot = read_u8(r)?;
@@ -430,44 +314,34 @@ pub(super) fn read_loot_response(r: &mut &[u8]) -> io::Result<(u64, LootResponse
     ))
 }
 
-/// Read `SMSG_LOOT_RELEASE_RESPONSE` (VERIFIED vmangos `Server/Packets/Loot.h:137-145`,
-/// `Player::SendLootRelease`, `Player.cpp:7736-7742`): `u64 guid, u8 result` — `result` is always
-/// `1` (the struct's default; vmangos never sets it otherwise).
+/// `SMSG_LOOT_RELEASE_RESPONSE` (`Loot.h:137-145`): `u64 guid, u8 result`; the result is always 1.
 pub(super) fn read_loot_release_response(r: &mut &[u8]) -> io::Result<(u64, u8)> {
     Ok((read_u64_le(r)?, read_u8(r)?))
 }
 
-/// Read `SMSG_LOOT_REMOVED` (VERIFIED vmangos `Server/Packets/Loot.h:147-154`): one `u8` — the wire
-/// loot slot that was just taken (by anyone; the row disappears from every current looter's
-/// window, `Loot::NotifyItemRemoved`).
+/// `SMSG_LOOT_REMOVED` (`Loot.h:147-154`): the wire slot just taken, sent to every looter.
 pub(super) fn read_loot_removed(r: &mut &[u8]) -> io::Result<u8> {
     read_u8(r)
 }
 
-/// Read `SMSG_LOOT_MONEY_NOTIFY` (VERIFIED vmangos `Server/Packets/Loot.h:69-76`): one `u32` — the
-/// requester's share of the coin pile (an equal split among current looters; solo looting is the
-/// degenerate 1-looter case, the requester's whole share).
+/// `SMSG_LOOT_MONEY_NOTIFY` (`Loot.h:69-76`): our share of the coin, split equally among looters.
 pub(super) fn read_loot_money_notify(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
 
-/// `SMSG_ITEM_PUSH_RESULT` (VERIFIED vmangos `Server/Packets/Item.h:324-345` +
-/// `Item.cpp:211-224`; both `SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_10_2` conditionals evaluate
-/// *included* for build 5875) — drives the "You receive loot: …" / "You receive item: …" chat
-/// line. `item_slot` is `0xFFFF_FFFF` when the item stacked onto an existing slot instead of
-/// landing in a fresh one.
+/// `SMSG_ITEM_PUSH_RESULT` (vmangos `Server/Packets/Item.cpp:211-224`, both post-1.10.2 fields
+/// present at 5875): the "You receive …" chat line. `item_slot` is `0xFFFF_FFFF` when it stacked.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ItemPushResult {
     pub player_guid: u64,
     /// `false` = looted, `true` = received from an NPC (vendor purchase, quest reward).
     pub from_npc: bool,
-    /// `true` = the item was CREATED (crafting's `EffectCreateItem`, a conjure aura — vmangos
-    /// `SendNewItem`'s own comment "0=received, 1=created"; the only `created=true` senders are
-    /// the create-item paths) → the client's "You create: …" line. NOT a stack-merge flag.
+    /// Crafted or conjured, giving the "You create: …" line; not a stack-merge flag (vmangos
+    /// `SendNewItem`: "0=received, 1=created").
     pub created: bool,
     pub show_in_chat: bool,
-    /// Which bag slot the item went to (`NULL_BAG`/`INVENTORY_SLOT_BAG_0`-style index — the same
-    /// vocabulary as [`super::items::BAG_PLAYER_INVENTORY`]/[`super::items::SLOT_BAG_FIRST`]).
+    /// The bag it went to, numbered as [`super::items::BAG_PLAYER_INVENTORY`] and
+    /// [`super::items::SLOT_BAG_FIRST`].
     pub bag_slot: u8,
     pub item_slot: u32,
     pub item_entry: u32,
@@ -476,7 +350,6 @@ pub struct ItemPushResult {
     pub count: u32,
 }
 
-/// Read `SMSG_ITEM_PUSH_RESULT` (see [`ItemPushResult`] for the field-inclusion verification).
 pub(super) fn read_item_push_result(r: &mut &[u8]) -> io::Result<ItemPushResult> {
     let player_guid = read_u64_le(r)?;
     let received = read_u32_le(r)?;
@@ -516,40 +389,32 @@ mod tests {
 
     #[test]
     fn cmsg_bodies_golden() {
-        // CMSG_LOOT (Server/Packets/Loot.cpp:8-11): a full guid.
         assert_eq!(
             loot(0x1234_5678_9abc_def0),
             hx("f0debc9a78563412"),
             "CMSG_LOOT body"
         );
 
-        // CMSG_AUTOSTORE_LOOT_ITEM (Loot.cpp:3-6): one u8 wire slot.
         assert_eq!(
             autostore_loot_item(3),
             hx("03"),
             "CMSG_AUTOSTORE_LOOT_ITEM body"
         );
 
-        // CMSG_LOOT_MONEY: empty.
         assert_eq!(loot_money(), Vec::<u8>::new(), "CMSG_LOOT_MONEY body");
 
-        // CMSG_LOOT_RELEASE (Loot.cpp:13-16): a full guid (server ignores it).
         assert_eq!(
             loot_release(0x1234_5678_9abc_def0),
             hx("f0debc9a78563412"),
             "CMSG_LOOT_RELEASE body"
         );
 
-        // CMSG_LOOT_ROLL (Loot.cpp:18-23): u64 lootedTarget, u32 itemSlot, u8 rollType.
         assert_eq!(
             loot_roll(0x1234_5678_9abc_def0, 2, roll_vote::GREED),
             hx("f0debc9a785634120200000002"),
             "CMSG_LOOT_ROLL body"
         );
 
-        // CMSG_LOOT_MASTER_GIVE (Loot.cpp:25-30): u64 lootGuid, u8 slotId, u64 playerGuid. The
-        // slot is a BYTE here — the roll family's itemSlot is a u32 over the same array, so the
-        // two builders are not interchangeable and the byte count proves which one this is.
         let give = loot_master_give(0x1234_5678_9abc_def0, 2, 0x0fed_cba9_8765_4321);
         assert_eq!(
             give,
@@ -559,8 +424,7 @@ mod tests {
         assert_eq!(give.len(), 17, "8 + 1 + 8, not 8 + 4 + 8");
     }
 
-    /// The five group-roll opcode values (VERIFIED vmangos `Opcodes_1_12_1.h:671-675`) and the
-    /// master-loot pair that follows them (`:676-677`).
+    /// The roll and master-loot opcodes (vmangos `Opcodes_1_12_1.h:671-677`).
     #[test]
     fn roll_opcode_values() {
         assert_eq!(opcode::SMSG_LOOT_ALL_PASSED, 670);
@@ -574,7 +438,6 @@ mod tests {
 
     #[test]
     fn loot_master_list_decodes() {
-        // Group.cpp:182-187: u8 count, then count full guids.
         let mut body = vec![3u8];
         for guid in [0xAAu64, 0xBB, 0xCC] {
             body.extend_from_slice(&guid.to_le_bytes());
@@ -588,9 +451,7 @@ mod tests {
         }
     }
 
-    /// An empty candidate list is a legal body, not a truncation: `Group::MasterLoot`
-    /// (`Group.cpp:925-937`) filters by loot-XP distance and `IsAllowedLooter`, so a group whose
-    /// other members are all out of range sends `count = 0` and nothing else.
+    /// `Group::MasterLoot` filters by range (`Group/Group.cpp:925-937`): `count = 0` is legal.
     #[test]
     fn loot_master_list_accepts_an_empty_list() {
         match parse_server(opcode::SMSG_LOOT_MASTER_LIST, &[0u8]).unwrap() {
@@ -601,12 +462,10 @@ mod tests {
 
     #[test]
     fn loot_start_roll_decodes() {
-        // Group.cpp:759-772 / Loot.cpp:43-51: guid, itemSlot, itemEntry, randomSuffix(0),
-        // randomPropId, countdown.
         let mut body = 0xAAu64.to_le_bytes().to_vec();
         body.extend_from_slice(&1u32.to_le_bytes()); // itemSlot
         body.extend_from_slice(&17182u32.to_le_bytes()); // itemEntryId
-        body.extend_from_slice(&0u32.to_le_bytes()); // randomSuffix — always 0
+        body.extend_from_slice(&0u32.to_le_bytes()); // randomSuffix, always 0
         body.extend_from_slice(&0u32.to_le_bytes()); // itemRandomPropId
         body.extend_from_slice(&60_000u32.to_le_bytes()); // LOOT_ROLL_TIMEOUT (Group.cpp:67)
 
@@ -625,10 +484,7 @@ mod tests {
         }
     }
 
-    /// The four `(roll_number, roll_type)` shapes vmangos actually emits — the overloaded pair
-    /// [`LootRoll::is_dice`]/[`LootRoll::vote`] disentangle. The Greed pair is the load-bearing
-    /// case: a Greed *vote* is `(128, 2)` and a Greed *dice roll* is `(1..=100, 2)`, identical in
-    /// `roll_type`.
+    /// A Greed vote `(128, 2)` and a Greed roll `(1..=100, 2)` share their `roll_type`.
     #[test]
     fn loot_roll_decodes_and_disambiguates() {
         let announce = |roll_number: u8, roll_type: u8| {
@@ -646,7 +502,6 @@ mod tests {
             }
         };
 
-        // Field placement, once, off the Need-vote shape.
         let need_vote = announce(0, 0);
         assert_eq!(
             need_vote,
@@ -661,7 +516,7 @@ mod tests {
             }
         );
 
-        // The three vote announcements (Group.cpp:970-990).
+        // The three vote shapes (Group.cpp:970-990).
         assert!(!need_vote.is_dice());
         assert_eq!(need_vote.vote(), Some(roll_vote::NEED));
 
@@ -673,7 +528,7 @@ mod tests {
         assert!(!greed_vote.is_dice());
         assert_eq!(greed_vote.vote(), Some(roll_vote::GREED));
 
-        // The dice results (Group.cpp:1163 / :1214) — urand(1, 100), so both bounds are legal.
+        // Dice results are urand(1, 100) (Group.cpp:1163, 1214), so both bounds are legal.
         for roll_number in [1u8, 57, 100] {
             for roll_type in [roll_vote::NEED, roll_vote::GREED] {
                 let dice = announce(roll_number, roll_type);
@@ -686,7 +541,6 @@ mod tests {
 
     #[test]
     fn loot_roll_won_decodes() {
-        // Loot.cpp:65-75 — note the winner guid lands AFTER the item block, unlike SMSG_LOOT_ROLL.
         let mut body = 0xAAu64.to_le_bytes().to_vec();
         body.extend_from_slice(&1u32.to_le_bytes()); // itemSlot
         body.extend_from_slice(&17182u32.to_le_bytes()); // itemEntryId
@@ -715,13 +569,12 @@ mod tests {
 
     #[test]
     fn loot_all_passed_decodes() {
-        // Loot.cpp:77-84 — the SWAPPED tail: itemRandomPropId THEN randomSuffixId, the reverse of
-        // every sibling in this family. A non-zero prop id proves the parser follows source order.
+        // A non-zero prop id ahead of the suffix proves the swapped order (Loot.cpp:77-84).
         let mut body = 0xAAu64.to_le_bytes().to_vec();
         body.extend_from_slice(&1u32.to_le_bytes()); // itemSlot
         body.extend_from_slice(&17182u32.to_le_bytes()); // itemEntryId
-        body.extend_from_slice(&7u32.to_le_bytes()); // itemRandomPropId — read
-        body.extend_from_slice(&0u32.to_le_bytes()); // randomSuffixId — discarded
+        body.extend_from_slice(&7u32.to_le_bytes()); // itemRandomPropId, read
+        body.extend_from_slice(&0u32.to_le_bytes()); // randomSuffixId, discarded
 
         match parse_server(opcode::SMSG_LOOT_ALL_PASSED, &body).unwrap() {
             ServerPacket::LootAllPassed(p) => assert_eq!(
@@ -739,12 +592,11 @@ mod tests {
 
     #[test]
     fn loot_response_items_shape_decodes() {
-        // SMSG_LOOT_RESPONSE, normal shape: guid, lootType=CORPSE, gold, itemCount, 2 rows.
         let mut body = 0xAAu64.to_le_bytes().to_vec();
         body.push(loot_type::CORPSE);
         body.extend_from_slice(&1234u32.to_le_bytes()); // gold
         body.push(2); // item count
-                      // item 0: slot 0, entry 117, count 1, display 123, randomSuffix(0), randomPropertyId 0, ALLOW_LOOT
+                      // slot 0: entry 117, count 1, display 123, suffix 0, prop 0, ALLOW_LOOT
         body.push(0);
         body.extend_from_slice(&117u32.to_le_bytes());
         body.extend_from_slice(&1u32.to_le_bytes());
@@ -752,7 +604,7 @@ mod tests {
         body.extend_from_slice(&0u32.to_le_bytes());
         body.extend_from_slice(&0u32.to_le_bytes());
         body.push(slot_type::ALLOW_LOOT);
-        // item 1: slot 1, entry 6948 (Hearthstone), count 1, display 4500, randomSuffix(0), randomPropertyId 0, LOCKED
+        // slot 1: entry 6948 (Hearthstone), count 1, display 4500, suffix 0, prop 0, LOCKED
         body.push(1);
         body.extend_from_slice(&6948u32.to_le_bytes());
         body.extend_from_slice(&1u32.to_le_bytes());
@@ -799,8 +651,6 @@ mod tests {
 
     #[test]
     fn loot_response_error_shape_decodes() {
-        // SMSG_LOOT_RESPONSE, error shape: guid, lootType=0, error code. Nothing else follows —
-        // the parser must not try to read gold/itemCount off a slice this short.
         let mut body = 0xBBu64.to_le_bytes().to_vec();
         body.push(0); // lootType 0 ⇒ error shape
         body.push(loot_error::TOO_FAR);
@@ -855,9 +705,6 @@ mod tests {
 
     #[test]
     fn item_push_result_wire() {
-        // SMSG_ITEM_PUSH_RESULT (Item.cpp:211-224, both build-5875 conditionals included):
-        // playerGuid, received, created, showInChat, bagSlot, itemSlot, itemEntry, suffixFactor,
-        // randomPropertyId, count.
         let mut body = 0x42u64.to_le_bytes().to_vec();
         body.extend_from_slice(&0u32.to_le_bytes()); // received: looted
         body.extend_from_slice(&1u32.to_le_bytes()); // created: new item
diff --git a/crates/benilla-protocol/src/messages/mail.rs b/crates/benilla-protocol/src/messages/mail.rs
index 8335bdd5..94244714 100644
--- a/crates/benilla-protocol/src/messages/mail.rs
+++ b/crates/benilla-protocol/src/messages/mail.rs
@@ -1,31 +1,25 @@
-//! The mail arc's wire layer (decision 0544 phase P0): the mailbox window's send/inbox/take/
-//! item-text/arrival opcodes (vmangos `Handlers/MailHandler.cpp`, `Mail/Mail.{h,cpp}`,
-//! `Server/Packets/Mail.{h,cpp}`, `Misc.{h,cpp}`, `Opcodes_1_12_1.h`, VERIFIED at decision time).
-//! There is no `SMSG_SHOW_MAILBOX` on 5875 — the window open is entirely client-side (0544's
-//! recorded fact); every mail CMSG below carries the mailbox guid at its head and the server
-//! re-validates the 5 yd interact distance (`CheckMailBox`) on each one independently.
+//! Mail wire messages. There is no `SMSG_SHOW_MAILBOX`: the client opens the window itself. Each
+//! mailbox CMSG leads with the mailbox guid, range-checked (5 yd) by vmangos `CheckMailBox`.
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_cstring, read_f32_le, read_u32_le, read_u64_le, read_u8};
 
-/// `MAIL_ITEM (5)` on [`MailListEntry::message_type`] carries no sender bytes at all — the only
-/// branch of the four that reads nothing before the subject cstring (VERIFIED vmangos
-/// `WorldSession::HandleGetMailList`, `Handlers/MailHandler.cpp`).
+/// [`MailListEntry::message_type`]: each value fixes the form of the row's sender field.
 pub mod mail_message_type {
-    /// A player sender — the sender field is a plain 8-byte guid.
+    /// A player: the sender field is an 8-byte guid.
     pub const NORMAL: u8 = 0;
-    /// An auction-house notice — the sender field is a u32 auction id.
+    /// An auction-house notice: the sender field is a u32 auction id.
     pub const AUCTION: u8 = 2;
-    /// A creature/NPC sender — the sender field is a u32 creature entry.
+    /// A creature: the sender field is a u32 creature entry.
     pub const CREATURE: u8 = 3;
-    /// A GameObject sender — the sender field is a u32 GameObject entry.
+    /// A GameObject: the sender field is a u32 GameObject entry.
     pub const GAMEOBJECT: u8 = 4;
-    /// A pre-made "item" mail (e.g. a GM/starter mail) — NO sender field rides the wire at all.
+    /// A pre-made item mail (a GM or starter mail): no sender field at all.
     pub const ITEM: u8 = 5;
 }
 
-/// `SMSG_SEND_MAIL_RESULT`'s `action` field (VERIFIED vmangos `Mail.h` `MailResponseType`).
+/// `SMSG_SEND_MAIL_RESULT`'s `action` (vmangos `Mail.h` `MailResponseType`).
 pub mod mail_action {
     pub const SEND: u32 = 0;
     pub const MONEY_TAKEN: u32 = 1;
@@ -35,10 +29,9 @@ pub mod mail_action {
     pub const MADE_PERMANENT: u32 = 5;
 }
 
-/// `SMSG_SEND_MAIL_RESULT`'s `error` field (VERIFIED vmangos `Mail.h` `MailResponseResult`).
+/// `SMSG_SEND_MAIL_RESULT`'s `error` (vmangos `Mail.h` `MailResponseResult`).
 pub mod mail_error {
     pub const OK: u32 = 0;
-    /// The trailing `equipError` tail rides only this one.
     pub const EQUIP_ERROR: u32 = 1;
     pub const CANNOT_SEND_TO_SELF: u32 = 2;
     pub const NOT_ENOUGH_MONEY: u32 = 3;
@@ -49,10 +42,8 @@ pub mod mail_error {
     pub const TOO_MANY_ATTACHMENTS: u32 = 15;
 }
 
-/// The single attachment slot a mail can carry (`MAX_MAIL_ITEMS == 1` on 5875) — the fixed-width
-/// item block that always rides `SMSG_MAIL_LIST_RESULT`'s per-record tail, zeroed when the mail
-/// carries no item. `entry == 0` on the wire is the "no item" signal; [`read_mail_list_result`]
-/// folds that into `None` rather than a zeroed `Some`.
+/// A mail's one attachment (`MAX_MAIL_ITEMS` is 1 in 1.12): a fixed-width block present on every
+/// `SMSG_MAIL_LIST_RESULT` row, all zero when there is no item.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MailAttachment {
     pub entry: u32,
@@ -65,47 +56,35 @@ pub struct MailAttachment {
     pub durability: u32,
 }
 
-/// One `SMSG_MAIL_LIST_RESULT` row (VERIFIED vmangos `WorldSession::HandleGetMailList`'s
-/// hand-serialization, `Handlers/MailHandler.cpp`). `sender_guid`/`sender_id` are
-/// mutually exclusive branches of one wire field, keyed by `message_type`
-/// ([`mail_message_type`]): a player sender is a guid, an auction/creature/GameObject sender is a
-/// u32 id, and a pre-made item mail (`ITEM`) sends neither.
+/// One `SMSG_MAIL_LIST_RESULT` row (vmangos `HandleGetMailList`, `Handlers/MailHandler.cpp`).
+/// `sender_guid` and `sender_id` are one wire field, whose form `message_type` picks.
 #[derive(Debug, Clone, PartialEq)]
 pub struct MailListEntry {
     pub message_id: u32,
     pub message_type: u8,
-    /// `Some` only for [`mail_message_type::NORMAL`].
     pub sender_guid: Option<u64>,
-    /// `Some` for [`mail_message_type::AUCTION`]/`CREATURE`/`GAMEOBJECT`.
     pub sender_id: Option<u32>,
     pub subject: String,
     /// `0` = no letter body to fetch; nonzero = a [`super::item_text_query`] key.
     pub item_text_id: u32,
     pub stationery: u32,
-    /// `None` iff the wire's item-block `entry` is `0`.
     pub item: Option<MailAttachment>,
     pub money: u32,
     pub cod: u32,
-    /// `checked` bit masks (VERIFIED vmangos `Mail.h`): READ `0x1`, RETURNED `0x2`, COPIED `0x4`,
-    /// COD_PAYMENT `0x8`, HAS_BODY `0x10`.
+    /// vmangos `Mail.h` flags: READ 0x1, RETURNED 0x2, COPIED 0x4, COD_PAYMENT 0x8, HAS_BODY 0x10.
     pub checked: u32,
     pub expire_days: f32,
     pub mail_template_id: u32,
 }
 
-/// Body of `CMSG_GET_MAIL_LIST` (VERIFIED vmangos `Server/Packets/Mail.cpp`,
-/// `GetMailList::ReadFromWorldPacket`): one full 8-byte mailbox guid. Answered by
-/// `SMSG_MAIL_LIST_RESULT` ([`read_mail_list_result`]).
+/// `CMSG_GET_MAIL_LIST` (vmangos `Server/Packets/Mail.cpp`): the mailbox guid.
 pub fn get_mail_list(mailbox: u64) -> Vec<u8> {
     mailbox.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_SEND_MAIL` (VERIFIED vmangos `Server/Packets/Mail.cpp`,
-/// `SendMail::ReadFromWorldPacket`): `u64 mailbox, cstr receiver, cstr subject, cstr body, u32
-/// stationery, u32 package, u64 itemGuid, u32 money, u32 COD`, then **9 zero bytes** (a `u64 0` +
-/// a `u8 0`) — the 1.12.1 tail vmangos read-skips without interpreting. vmangos *discards* the
-/// client's `stationery`/`package` choice: player mail is always stored `MAIL_STATIONERY_DEFAULT`
-/// (41), so both fields exist only to keep the reader aligned.
+/// `CMSG_SEND_MAIL` (vmangos `Server/Packets/Mail.cpp`): mailbox guid, receiver, subject and body
+/// cstrings, `u32` stationery and package, item guid, `u32` money and COD, then 9 zero bytes
+/// vmangos skips. It ignores stationery and package, storing `MAIL_STATIONERY_DEFAULT` (41).
 pub fn send_mail(
     mailbox: u64,
     receiver: &str,
@@ -132,13 +111,11 @@ pub fn send_mail(
     out.extend_from_slice(&item_guid.to_le_bytes());
     out.extend_from_slice(&money.to_le_bytes());
     out.extend_from_slice(&cod.to_le_bytes());
-    // The 9-byte read-skipped tail: a u64 then a u8, both zero, both discarded server-side.
     out.extend_from_slice(&0u64.to_le_bytes());
     out.push(0);
     out
 }
 
-/// The shared `u64 mailbox, u32 mailId` shape of the five take/mark/return/delete CMSGs below.
 fn mailbox_and_mail_id(mailbox: u64, mail_id: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&mailbox.to_le_bytes());
@@ -146,52 +123,41 @@ fn mailbox_and_mail_id(mailbox: u64, mail_id: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_MAIL_TAKE_MONEY`: `u64 mailbox, u32 mailId`. Answered by `SMSG_SEND_MAIL_RESULT`
-/// (action [`mail_action::MONEY_TAKEN`]).
+/// `CMSG_MAIL_TAKE_MONEY`: answered by a [`mail_action::MONEY_TAKEN`] result.
 pub fn mail_take_money(mailbox: u64, mail_id: u32) -> Vec<u8> {
     mailbox_and_mail_id(mailbox, mail_id)
 }
 
-/// Body of `CMSG_MAIL_TAKE_ITEM`: `u64 mailbox, u32 mailId`. Answered by `SMSG_SEND_MAIL_RESULT`
-/// (action [`mail_action::ITEM_TAKEN`], carrying the taken item's entry + count on success).
+/// `CMSG_MAIL_TAKE_ITEM`: answered by an [`mail_action::ITEM_TAKEN`] result naming the item.
 pub fn mail_take_item(mailbox: u64, mail_id: u32) -> Vec<u8> {
     mailbox_and_mail_id(mailbox, mail_id)
 }
 
-/// Body of `CMSG_MAIL_MARK_AS_READ`: `u64 mailbox, u32 mailId`. **No response packet** — the app
-/// flips the local `checked` READ bit and repaints.
+/// `CMSG_MAIL_MARK_AS_READ`: there is no reply; the caller sets the `checked` READ bit itself.
 pub fn mail_mark_as_read(mailbox: u64, mail_id: u32) -> Vec<u8> {
     mailbox_and_mail_id(mailbox, mail_id)
 }
 
-/// Body of `CMSG_MAIL_RETURN_TO_SENDER`: `u64 mailbox, u32 mailId`. Answered by
-/// `SMSG_SEND_MAIL_RESULT` (action [`mail_action::RETURNED`]).
+/// `CMSG_MAIL_RETURN_TO_SENDER`: answered by a [`mail_action::RETURNED`] result.
 pub fn mail_return_to_sender(mailbox: u64, mail_id: u32) -> Vec<u8> {
     mailbox_and_mail_id(mailbox, mail_id)
 }
 
-/// Body of `CMSG_MAIL_DELETE`: `u64 mailbox, u32 mailId`. Answered by `SMSG_SEND_MAIL_RESULT`
-/// (action [`mail_action::DELETED`]).
+/// `CMSG_MAIL_DELETE`: answered by a [`mail_action::DELETED`] result.
 pub fn mail_delete(mailbox: u64, mail_id: u32) -> Vec<u8> {
     mailbox_and_mail_id(mailbox, mail_id)
 }
 
-/// Body of `CMSG_MAIL_CREATE_TEXT_ITEM` (VERIFIED vmangos `Server/Packets/Mail.cpp`,
-/// `MailCreateTextItem::ReadFromWorldPacket`): `u64 mailbox, u32 mailId, u32 mailTemplateId` —
-/// the letter button's "permanent copy" verb; `mailTemplateId` is always `0` for player mail (no
-/// mail templates in 1.12 player mail; vmangos only reads it on builds > 1.9.4). Answered by
-/// `SMSG_SEND_MAIL_RESULT` (action [`mail_action::MADE_PERMANENT`]); on OK the server also stamps
-/// the mail's `checked` COPIED bit — the next list re-sync flips `textCreated`.
+/// `CMSG_MAIL_CREATE_TEXT_ITEM`: mailbox, mail id and a `u32` template id, 0 for player mail.
+/// Answered by a [`mail_action::MADE_PERMANENT`] result; on OK the mail's COPIED bit is set.
 pub fn mail_create_text_item(mailbox: u64, mail_id: u32) -> Vec<u8> {
     let mut body = mailbox_and_mail_id(mailbox, mail_id);
     body.extend_from_slice(&0u32.to_le_bytes()); // mailTemplateId
     body
 }
 
-/// Body of `CMSG_ITEM_TEXT_QUERY` (VERIFIED vmangos `Server/Packets/Mail.cpp`,
-/// `ItemTextQuery::ReadFromWorldPacket`): `u32 textId, u32 mailId, u32 unk` — vmangos resolves the
-/// text from `textId` alone and never reads `mailId`/`unk` back out, but the real client writes
-/// all three. Answered by `SMSG_ITEM_TEXT_QUERY_RESPONSE` ([`read_item_text_query_response`]).
+/// `CMSG_ITEM_TEXT_QUERY` (vmangos `Server/Packets/Mail.cpp`): `u32 textId, u32 mailId, u32 unk`.
+/// The 1.12 client writes all three; vmangos only uses `textId`.
 pub fn item_text_query(text_id: u32, mail_id: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&text_id.to_le_bytes());
@@ -200,13 +166,7 @@ pub fn item_text_query(text_id: u32, mail_id: u32) -> Vec<u8> {
     body
 }
 
-/// Read `SMSG_MAIL_LIST_RESULT` (VERIFIED vmangos `WorldSession::HandleGetMailList`,
-/// hand-serialized in `Handlers/MailHandler.cpp`): `u8 count` (cap 254; ≤100 by business rule), then `count`
-/// × [`MailListEntry`] rows. Each row: `u32 messageId, u8 messageType`, the sender branch keyed by
-/// `messageType` ([`mail_message_type`]), `cstr subject, u32 itemTextId, u32 package(dropped —
-/// always 0, no consumer), u32 stationery`, the fixed-width item block (ALWAYS present; `entry ==
-/// 0` folds to [`MailListEntry::item`] being `None`), `u32 money, u32 COD, u32 checked, f32
-/// expireDays, u32 mailTemplateId`.
+/// `SMSG_MAIL_LIST_RESULT` (vmangos `HandleGetMailList`): `u8 count`, then [`MailListEntry`] rows.
 pub(super) fn read_mail_list_result(r: &mut &[u8]) -> io::Result<Vec<MailListEntry>> {
     let count = read_u8(r)?;
     // vmangos stops the list at 254 (`MailHandler.cpp:761`, `mailsCount >= 254`).
@@ -224,7 +184,7 @@ pub(super) fn read_mail_list_result(r: &mut &[u8]) -> io::Result<Vec<MailListEnt
         };
         let subject = read_cstring(r)?;
         let item_text_id = read_u32_le(r)?;
-        let _package = read_u32_le(r)?; // always 0 on 5875 (vmangos hardcodes it); no consumer
+        let _package = read_u32_le(r)?; // always 0 (vmangos hardcodes it)
         let stationery = read_u32_le(r)?;
         let entry = read_u32_le(r)?;
         let perm_enchant = read_u32_le(r)?;
@@ -268,14 +228,8 @@ pub(super) fn read_mail_list_result(r: &mut &[u8]) -> io::Result<Vec<MailListEnt
     Ok(mails)
 }
 
-/// Read `SMSG_SEND_MAIL_RESULT` (VERIFIED vmangos `Server/Packets/Mail.cpp`,
-/// `SendMailResult::AppendBodyTo`): `u32 mailId, u32 action ([`mail_action`]), u32 error
-/// ([`mail_error`])`, then a conditional tail — `u32 equipError` iff `error ==
-/// `[`mail_error::EQUIP_ERROR`]`, else `u32 itemEntry, u32 itemCount` iff `action ==
-/// `[`mail_action::ITEM_TAKEN`]` and `error == `[`mail_error::OK`]``. Neither tail rides any other
-/// action/error combination; the remaining-length guard mirrors how the codec's other
-/// conditional tails (e.g. `SMSG_TRANSFER_PENDING`'s transport block) stay robust to a body that
-/// doesn't carry the tail its fields would otherwise predict.
+/// `SMSG_SEND_MAIL_RESULT` (vmangos `Server/Packets/Mail.cpp`): `u32 mailId, action, error`, then
+/// `u32 equipError` on `EQUIP_ERROR`, or `u32 itemEntry, itemCount` on an OK `ITEM_TAKEN`.
 #[allow(clippy::type_complexity)]
 pub(super) fn read_send_mail_result(
     r: &mut &[u8],
@@ -293,29 +247,19 @@ pub(super) fn read_send_mail_result(
     Ok((mail_id, action, error, equip_error, item))
 }
 
-/// Read `SMSG_ITEM_TEXT_QUERY_RESPONSE` (VERIFIED vmangos `Server/Packets/Mail.cpp`,
-/// `ItemTextQueryResponse::AppendBodyTo`): `u32 textId, cstr text` — the letter body's ask-once
-/// fetch, answering [`item_text_query`].
+/// `SMSG_ITEM_TEXT_QUERY_RESPONSE` (vmangos `Server/Packets/Mail.cpp`): `u32 textId, cstr text`.
 pub(super) fn read_item_text_query_response(r: &mut &[u8]) -> io::Result<(u32, String)> {
     Ok((read_u32_le(r)?, read_cstring(r)?))
 }
 
-/// Read `SMSG_RECEIVED_MAIL`: one **`f32` delay** — the seconds until the mail is "waiting", the
-/// same countdown units as [`read_query_next_mail_time`]. Sent when a mail *arrives* (instant for
-/// text-only, on the delivery timer's expiry otherwise).
-///
-/// The real client reads these four bytes as a float and feeds them to the pending-mail countdown's
-/// set-value ladder (VERIFIED wow-re, handler `0x4ad620`; decision 0913). vmangos writes them as
-/// `uint32(0)` (`MailHandler.cpp::SendNewMail`) and `0x00000000` *is* `0.0f`, so the two agree
-/// exactly on the only value vmangos ever sends — reading it the way the client does costs nothing
-/// and keeps a server that sends a real delay working.
+/// `SMSG_RECEIVED_MAIL`: an `f32` delay in seconds until the mail shows as waiting; the 1.12
+/// client reads a float (`0x4ad620`). vmangos writes `uint32(0)` (`SendNewMail`), bitwise `0.0`.
 pub(super) fn read_received_mail(r: &mut &[u8]) -> io::Result<f32> {
     read_f32_le(r)
 }
 
-/// Read `MSG_QUERY_NEXT_MAIL_TIME`'s reply (same opcode both directions — our request is an EMPTY
-/// body, [`super::opcode::MSG_QUERY_NEXT_MAIL_TIME`]): one `f32` — `0.0` = unread mail waiting,
-/// `-86400.0` = none.
+/// The `MSG_QUERY_NEXT_MAIL_TIME` reply (the request is an empty body on the same opcode): an
+/// `f32`, `0.0` for unread mail waiting and `-86400.0` for none.
 pub(super) fn read_query_next_mail_time(r: &mut &[u8]) -> io::Result<f32> {
     read_f32_le(r)
 }
diff --git a/crates/benilla-protocol/src/messages/meeting_stone.rs b/crates/benilla-protocol/src/messages/meeting_stone.rs
index 3200d6ab..0a2a7e16 100644
--- a/crates/benilla-protocol/src/messages/meeting_stone.rs
+++ b/crates/benilla-protocol/src/messages/meeting_stone.rs
@@ -1,20 +1,17 @@
-//! The meeting-stone queue's wire (decisions 1963/1974/2283; wow-re `staticpopup-dialog-bindings.md`
-//! §8 and `meeting-stone-status.md` §8/§9/§10): the server's queue state, the JOIN a right-click on
-//! the stone sends, and the leave request `CancelMeetingStoneRequest` sends.
+//! Meeting-stone wire messages: the queue state, the right-click join and the leave request.
 
 use std::io::{self, Read};
 
 use crate::wire::{read_u32_le, read_u8};
 
-/// `SMSG 0x295` (VERIFIED at the bytes, handler `0x4ca230`): the queued area and a status byte
-/// the client turns into one of five local messages, then `MEETINGSTONE_CHANGED`.
+/// `SMSG 0x295` (reference handler `0x4ca230`): the queued area and a status byte, which the
+/// client turns into one of five messages before firing `MEETINGSTONE_CHANGED`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct MeetingStoneSetQueue {
     pub area: u32,
     pub status: u8,
 }
 
-/// Parse it: `u32 areaId`, `u8 status`.
 pub(super) fn read_meeting_stone_set_queue(r: &mut impl Read) -> io::Result<MeetingStoneSetQueue> {
     Ok(MeetingStoneSetQueue {
         area: read_u32_le(r)?,
@@ -22,42 +19,36 @@ pub(super) fn read_meeting_stone_set_queue(r: &mut impl Read) -> io::Result<Meet
     })
 }
 
-/// Body of `CMSG 0x292` (VERIFIED, builder `0x4c9ff0`): one full little-endian `u64` — the guid of
-/// the `GAMEOBJECT_TYPE_MEETINGSTONE` (23) the player right-clicked, written by the 8-byte guid
-/// writer `0x418370` straight after `PutUInt32(0x292)`. Nothing else is in the packet: the area is
-/// the SERVER's to resolve from the stone's `gameobject_template.data[2]`, which is why the join
-/// names an object and the reply names an area.
+/// `CMSG 0x292` (reference builder `0x4c9ff0`): the right-clicked stone's guid (GO type 23) and
+/// nothing else; the server resolves the area from the stone's `gameobject_template.data[2]`.
 pub fn meeting_stone_join(go_guid: u64) -> Vec<u8> {
     go_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG 0x293` (VERIFIED, `0x4ca120`): empty.
+/// `CMSG 0x293` (reference `0x4ca120`, `CancelMeetingStoneRequest`): an empty body.
 pub fn meeting_stone_leave() -> Vec<u8> {
     Vec::new()
 }
 
-/// The four display-only replies one handler serves (`0x4ca3c0`, dispatched on the opcode; wow-re
-/// `meeting-stone-status.md` §9, 1974). None touches the queue state, none fires an event.
+/// Display-only replies (reference handler `0x4ca3c0`): none changes the queue or fires an event.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum MeetingStoneNotice {
     /// `0x297`, empty.
     Success,
     /// `0x298`, empty.
     InProgress,
-    /// `0x299`, `u64 guid` — the line waits for the name cache.
+    /// `0x299`, `u64 guid`; the line waits for the name cache.
     MemberAdded { guid: u64 },
     /// `0x2BB`, `u8 code`.
     JoinFailed { code: u8 },
 }
 
-/// Parse `0x299`'s guid.
 pub(super) fn read_meeting_stone_member_added(r: &mut impl Read) -> io::Result<MeetingStoneNotice> {
     Ok(MeetingStoneNotice::MemberAdded {
         guid: crate::wire::read_u64_le(r)?,
     })
 }
 
-/// Parse `0x2BB`'s code byte.
 pub(super) fn read_meeting_stone_join_failed(r: &mut impl Read) -> io::Result<MeetingStoneNotice> {
     Ok(MeetingStoneNotice::JoinFailed { code: read_u8(r)? })
 }
@@ -66,8 +57,7 @@ pub(super) fn read_meeting_stone_join_failed(r: &mut impl Read) -> io::Result<Me
 mod tests {
     use super::*;
 
-    /// The join body is the bare guid, little-endian, eight bytes and no more — `0x4c9ff0` writes
-    /// `PutUInt32(0x292)` into the header and then exactly one `0x418370` (the 8-byte guid writer).
+    /// The reference builder `0x4c9ff0` writes one 8-byte guid (`0x418370`) after the opcode.
     #[test]
     fn cmsg_meetingstone_join_body_golden() {
         assert_eq!(
@@ -77,7 +67,6 @@ mod tests {
         );
     }
 
-    /// Both of the other two sends in this family are empty bodies.
     #[test]
     fn the_leave_body_is_empty() {
         assert!(meeting_stone_leave().is_empty());
diff --git a/crates/benilla-protocol/src/messages/mirror_timer.rs b/crates/benilla-protocol/src/messages/mirror_timer.rs
index 62093a0a..86763dc9 100644
--- a/crates/benilla-protocol/src/messages/mirror_timer.rs
+++ b/crates/benilla-protocol/src/messages/mirror_timer.rs
@@ -1,59 +1,26 @@
-//! The mirror timers — the breath / fatigue / feign-death bars (opcodes 473-475; decision 0874).
-//!
-//! "Mirror" is the client's own word for a timer whose authority is the **server**: the client
-//! never computes breath or fatigue, it mirrors a countdown the server ships and integrates it
-//! locally between packets. Three opcodes carry the whole system:
-//!
-//! | opcode | what it means |
-//! |---|---|
-//! | `SMSG_START_MIRROR_TIMER` 0x1D9 | start **or fully re-state** one timer |
-//! | `SMSG_PAUSE_MIRROR_TIMER` 0x1DA | freeze/unfreeze one running timer |
-//! | `SMSG_STOP_MIRROR_TIMER` 0x1DB | that timer is over — hide its bar |
-//!
-//! The bodies are VERIFIED against vmangos's own packet builds
-//! (`Server/Packets/Misc.h:718-751` + `Misc.cpp:472-491`), which are the exact bytes benilla
-//! receives, and the type numbering against `Objects/MirrorTimer.h`
-//! (`FATIGUE=0, BREATH=1, FEIGNDEATH=2, NUM_CLIENT_TIMERS=3`) — the server's `SendMirrorTimers`
-//! gate means a **fourth** type (its internal `ENVIRONMENTAL`, lava/slime damage) is never sent
-//! to a client at all; it drives damage server-side with no bar.
-//!
-//! Two things about this family are worth knowing before reading the app side:
-//!
-//! - **There is no separate "update" opcode.** A running timer that changes anything —
-//!   direction, remaining time, frozen state — is re-sent as a whole `START`
-//!   (`Player::SendMirrorTimers`, the `FULL_UPDATE` arm). So the consumer must treat `START` as
-//!   idempotent *re-statement*, not only as a first appearance.
-//! - **`PAUSE` is effectively dead on a vanilla wire.** vmangos deliberately never sends it —
-//!   `SendMirrorTimers` replaces the pause with a full `START` and says why in the source
-//!   ("Gotta do a full update with SMSG_START_MIRROR_TIMER to avoid lua errors"), because the
-//!   shipped 1.12 `MirrorTimer.lua` handler tests the same `arg1` both as a name and as a number.
-//!   We still decode it — a server that sends one should not desync us (see
-//!   `crate::ui_mirror` for what the app does with it).
+//! Mirror timers: the breath, fatigue and feign-death bars. The server owns the countdown and the
+//! client integrates it between packets. Any change is re-sent as a full `START`
+//! (`Player::SendMirrorTimers`), so `START` also re-states a running timer; vmangos never sends
+//! `PAUSE`, whose stock `MirrorTimer.lua` handler errors on it.
 
 use std::io::{self, Read};
 
 use crate::wire::{read_i32_le, read_u32_le, read_u8};
 
-/// Which mirror timer a packet is about — the wire's `timerType` word.
-///
-/// The numbering is the server's `MirrorTimer::Type` (vmangos `Objects/MirrorTimer.h`), and it is
-/// also the index the reference client uses into its own 3-entry name table, so a value outside
-/// this set has no meaning on either end.
+/// The wire's `timerType` (vmangos `Objects/MirrorTimer.h`), also the reference client's index
+/// into its 3-entry timer name table.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum MirrorTimerKind {
-    /// `0` — swimming in "high sea" (deep, uncharted water): the **Fatigue** bar.
+    /// `0`: swimming in deep, uncharted water.
     Fatigue,
-    /// `1` — head under the surface: the **Breath** bar.
+    /// `1`: head under the surface.
     Breath,
-    /// `2` — feigning death. The server starts this one from a duration that is zero unless a
-    /// script set it, so vanilla play essentially never shows it; it is a client timer type all
-    /// the same.
+    /// `2`: feigning death; its duration is zero unless a script sets it, so it rarely shows.
     FeignDeath,
 }
 
 impl MirrorTimerKind {
-    /// Map the wire's `timerType` word, or `None` for a type this client has no bar for
-    /// (the server's own `NUM_CLIENT_TIMERS` gate means vanilla never sends one).
+    /// The server's `NUM_CLIENT_TIMERS` gate keeps its internal `ENVIRONMENTAL` (3) off the wire.
     pub fn from_wire(value: u32) -> Option<Self> {
         match value {
             0 => Some(Self::Fatigue),
@@ -63,7 +30,6 @@ impl MirrorTimerKind {
         }
     }
 
-    /// The `timerType` word this kind is sent as — the inverse of [`Self::from_wire`].
     pub fn to_wire(self) -> u32 {
         match self {
             Self::Fatigue => 0,
@@ -73,34 +39,25 @@ impl MirrorTimerKind {
     }
 }
 
-/// `SMSG_START_MIRROR_TIMER` — start, or wholly re-state, one mirror timer.
+/// `SMSG_START_MIRROR_TIMER`: starts, or wholly re-states, one mirror timer.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MirrorTimerStart {
-    /// The wire's raw `timerType`. Kept raw rather than pre-mapped so an unknown type survives
-    /// the decode as data instead of failing the whole packet; [`MirrorTimerKind::from_wire`]
-    /// is the mapping, applied at the UI seam.
+    /// The raw `timerType`, left unmapped so an unknown one still decodes.
     pub kind: u32,
-    /// Time left, in **milliseconds**. Counts toward `0` while draining and toward `duration_ms`
-    /// while refilling; the bar is `remaining_ms / 1000` in bar units.
+    /// Time left in ms, counting toward 0 while draining and toward `duration_ms` while refilling.
     pub remaining_ms: u32,
-    /// The timer's full span, in **milliseconds** — the bar's maximum (60 s of breath by
-    /// default: vmangos `CONFIG_UINT32_MIRRORTIMER_BREATH_MAX`).
+    /// The bar's maximum in ms (breath: 60 s by default, `CONFIG_UINT32_MIRRORTIMER_BREATH_MAX`).
     pub duration_ms: u32,
-    /// Rate of change, in bar-units per second, and **signed**: `-1` while the timer drains
-    /// (underwater, in high sea), `+10` while it refills (surfaced — a full breath bar refills
-    /// ten times faster than it drained, which is why surfacing snaps it back). The consumer
-    /// integrates `scale * elapsed` between packets; this is the whole of the client-side motion.
+    /// Signed rate in bar seconds per second: `-1` while draining, `+10` while refilling after
+    /// surfacing. The client integrates `scale * elapsed` between packets.
     pub scale: i32,
-    /// Frozen: the bar holds its value and stops integrating. Sent as one byte.
+    /// Frozen: the bar holds its value and stops integrating.
     pub paused: bool,
-    /// The spell driving this timer, if any (a water-breathing aura owns the breath timer for its
-    /// duration). `0` = no spell. The reference client's Lua never sees this field.
+    /// The spell driving the timer (water breathing) or `0`; the reference Lua never sees it.
     pub spell_id: u32,
 }
 
-/// Read `SMSG_START_MIRROR_TIMER`: `u32 type, u32 remaining, u32 duration, i32 scale, u8 paused,
-/// u32 spellId` — VERIFIED against vmangos `StartMirrorTimer::AppendBodyTo` (`Misc.cpp:472`),
-/// field for field in that order. `scale` is the one signed field.
+/// `SMSG_START_MIRROR_TIMER` (vmangos `Server/Packets/Misc.cpp:472`).
 pub fn read_start_mirror_timer(r: &mut impl Read) -> io::Result<MirrorTimerStart> {
     Ok(MirrorTimerStart {
         kind: read_u32_le(r)?,
@@ -112,14 +69,12 @@ pub fn read_start_mirror_timer(r: &mut impl Read) -> io::Result<MirrorTimerStart
     })
 }
 
-/// Read `SMSG_PAUSE_MIRROR_TIMER`: `u32 type, u8 paused` (vmangos `PauseMirrorTimer::AppendBodyTo`,
-/// `Misc.cpp:487`). Returns the raw type and the flag.
+/// `SMSG_PAUSE_MIRROR_TIMER` (vmangos `Misc.cpp:487`): the raw type and the paused flag.
 pub fn read_pause_mirror_timer(r: &mut impl Read) -> io::Result<(u32, bool)> {
     Ok((read_u32_le(r)?, read_u8(r)? != 0))
 }
 
-/// Read `SMSG_STOP_MIRROR_TIMER`: the bare `u32 type` and nothing else
-/// (vmangos `StopMirrorTimer::AppendBodyTo`, `Misc.cpp:482`).
+/// `SMSG_STOP_MIRROR_TIMER` (vmangos `Misc.cpp:482`): the raw type alone.
 pub fn read_stop_mirror_timer(r: &mut impl Read) -> io::Result<u32> {
     read_u32_le(r)
 }
@@ -128,8 +83,6 @@ pub fn read_stop_mirror_timer(r: &mut impl Read) -> io::Result<u32> {
 mod tests {
     use super::*;
 
-    /// A golden `SMSG_START_MIRROR_TIMER` body, byte-for-byte as vmangos writes it: the breath
-    /// timer draining with 45 s left of a 60 s span, unfrozen, no spell.
     #[test]
     fn start_reads_every_field_in_the_servers_order() {
         let mut body = Vec::new();
@@ -153,9 +106,6 @@ mod tests {
         );
     }
 
-    /// The refill direction: surfacing re-sends the same timer with `scale = +10`, frozen flag
-    /// clear, and a water-breathing aura's id when one owns it. `scale` must survive as a
-    /// *signed* field — a `u32` read would still pass on `+10` and silently break on `-1`.
     #[test]
     fn start_carries_a_signed_scale_and_the_owning_spell() {
         let mut body = Vec::new();
@@ -172,10 +122,14 @@ mod tests {
         );
         assert!(start.paused);
         assert_eq!(start.spell_id, 5697);
+
+        // The draining rate, -1 on the wire, reads back negative.
+        body[12..16].copy_from_slice(&(-1i32).to_le_bytes());
+        let start = read_start_mirror_timer(&mut &body[..]).unwrap();
+        assert_eq!(start.scale, -1, "draining");
+        assert_eq!(start.spell_id, 5697);
     }
 
-    /// The three client timer types, and the fact that nothing else maps — the server's
-    /// `NUM_CLIENT_TIMERS` gate keeps its internal `ENVIRONMENTAL` (3) off the wire entirely.
     #[test]
     fn only_the_three_client_timer_types_map() {
         assert_eq!(
@@ -202,7 +156,6 @@ mod tests {
         }
     }
 
-    /// `SMSG_PAUSE_MIRROR_TIMER`: type then one flag byte.
     #[test]
     fn pause_is_a_type_and_a_flag_byte() {
         let mut body = 0u32.to_le_bytes().to_vec();
@@ -213,7 +166,6 @@ mod tests {
         assert_eq!(read_pause_mirror_timer(&mut &body[..]).unwrap(), (1, false));
     }
 
-    /// `SMSG_STOP_MIRROR_TIMER`: the bare type word.
     #[test]
     fn stop_is_the_bare_type_word() {
         assert_eq!(
@@ -222,8 +174,7 @@ mod tests {
         );
     }
 
-    /// A truncated body is an error, never a silently zeroed field — the `paused` byte and the
-    /// trailing `spellId` are the two the server appends last and the two a sloppy reader drops.
+    /// The cuts fall before `scale`, before `paused`, before `spellId` and inside it.
     #[test]
     fn a_truncated_start_body_is_an_error() {
         let mut full = Vec::new();
diff --git a/crates/benilla-protocol/src/messages/mod.rs b/crates/benilla-protocol/src/messages/mod.rs
index 5465d11d..a22a00d1 100644
--- a/crates/benilla-protocol/src/messages/mod.rs
+++ b/crates/benilla-protocol/src/messages/mod.rs
@@ -1,19 +1,5 @@
-//! The world (`mangosd`) message layer — in-repo replacement for `wow_world_messages` (decision
-//! 0021), scoped to the opcodes benilla sends and receives.
-//!
-//! World packets are framed by a header-encrypted size+opcode (see [`crate::world`]); this module owns
-//! only the *bodies*: parsing the server packets benilla decodes into [`ServerPacket`], and building
-//! the client packet bodies benilla sends. The one genuinely complex packet is `SMSG_UPDATE_OBJECT`
-//! (and its zlib twin) — an object list where each entry carries a [`MovementBlock`]-shaped position
-//! and a sparse [`ObjectFields`] of descriptor fields; its decode lives in [`update_object`], and
-//! [`crate::events`] pulls out the handful of fields the renderer uses.
-//! The [`ServerPacket`] enum itself lives in `packet`; the opcode→variant dispatch
-//! ([`parse_server`]) in `parse`.
-//!
-//! Proven byte-for-byte against `wow_world_messages` during the decision-0021 migration (oracle test
-//! in git history); ongoing coverage is the oracle-free golden/fixture tests in `tests/*.rs` (split by
-//! domain — client, movement, items, spells, update_object, simple_packets — sharing fixtures via
-//! `tests/common`).
+//! World (`mangosd`) packet bodies: server packets decode into [`ServerPacket`] via
+//! [`parse_server`], client bodies are built here; the header framing lives in [`crate::world`].
 
 mod action_bar;
 pub mod addons;
@@ -273,18 +259,9 @@ pub use vendor::{
 };
 pub use world_state::InitWorldStates;
 
-/// The **world server's** `SMSG_AUTH_RESPONSE` result codes — a **different enum** from the
-/// realmd logon-proof's `AuthLogonResult` (`crate::AuthReject`, 0x00..=0x12), which is the trap
-/// this block exists to close: both are "the auth result byte", they overlap numerically, and they
-/// mean unrelated things. 0x0C is `AUTH_OK` here and `AUTH_LOGON_FAILED_SUSPENDED` there.
-///
-/// VERIFIED two ways. The client's own dispatch over exactly this enum is decompiled in wow-re
-/// `system/net/scratch/w2b-pack.c` — case 0x0c → `AUTH_OK`, 0x0d → `AUTH_FAILED`, 0x0e →
-/// `AUTH_REJECT`, … 0x15 → `AUTH_UNKNOWN_ACCOUNT`, 0x16 → `AUTH_INCORRECT_PASSWORD`, 0x1b →
-/// `AUTH_WAIT_QUEUE`, 0x22..=0x26 → the `REALM_LIST_*` strings — and the same numbering is
-/// `AuthResponseCodes` in cmangos `src/game/Globals/SharedDefines.h:1721+`. Each constant's name
-/// is the `GlueStrings` key the client shows for it, which is what makes the mapping in
-/// `crate::login`'s `world_refusal_text` a transcription rather than a judgement call.
+/// World `SMSG_AUTH_RESPONSE` result codes, not realmd's `AuthLogonResult` (`crate::AuthReject`):
+/// the ranges overlap, and 0x0C is `AUTH_OK` here but `AUTH_LOGON_FAILED_SUSPENDED` there. Each
+/// name is the `GlueStrings` key the client shows (cmangos `SharedDefines.h:1721`).
 pub const AUTH_OK: u8 = 0x0C;
 pub const AUTH_FAILED: u8 = 0x0D;
 pub const AUTH_REJECT: u8 = 0x0E;
@@ -300,11 +277,10 @@ pub const AUTH_SESSION_EXPIRED: u8 = 0x17;
 pub const AUTH_SERVER_SHUTTING_DOWN: u8 = 0x18;
 pub const AUTH_ALREADY_LOGGING_IN: u8 = 0x19;
 pub const AUTH_LOGIN_SERVER_NOT_FOUND: u8 = 0x1A;
-/// The realm is full and we are **queued**, not refused — the one code here that is not an ending.
+/// The realm is full and we are queued, not refused: the one code here that is not an ending.
 pub const AUTH_WAIT_QUEUE: u8 = 0x1B;
-// The tail past the queue. These five are exactly the codes the client's `OKAY_WITH_URL` table
-// (`0x803740`, 5 records, stride 0x24) keys on — banned/no-time/db-busy/suspended/parental — which
-// is why the URL dialog is reachable ONLY from this enum and never from realmd.
+// The 1.12 client's `OKAY_WITH_URL` table (`0x803740`) keys on banned, no-time, db-busy,
+// suspended and parental, so the URL dialog is reachable only from this enum, never from realmd.
 pub const AUTH_BANNED: u8 = 0x1C;
 pub const AUTH_ALREADY_ONLINE: u8 = 0x1D;
 pub const AUTH_NO_TIME: u8 = 0x1E;
@@ -313,54 +289,30 @@ pub const AUTH_SUSPENDED: u8 = 0x20;
 pub const AUTH_PARENTAL_CONTROL: u8 = 0x21;
 /// `LogoutResult::Success` (`SMSG_LOGOUT_RESPONSE`).
 pub const LOGOUT_SUCCESS: u32 = 0x0;
-/// Chat `Language` wire ids (VERIFIED vmangos `SharedDefines.h:256-261`): the faction tongues.
-/// `Universal` (0) is server-reserved — vmangos rejects it from clients for ordinary chat.
+/// Faction-tongue `Language` ids (vmangos `SharedDefines.h:256-261`); vmangos rejects
+/// `Universal` (0) from clients in ordinary chat.
 pub const LANGUAGE_COMMON: u32 = 0x7;
 pub const LANGUAGE_ORCISH: u32 = 0x1;
 
-/// `LANG_ADDON` (VERIFIED vmangos `SharedDefines.h:270`) — **not a tongue**. 1.12.1 has no addon
-/// opcode: `SendAddonMessage` rides the ordinary chat lanes and this sentinel in the `language`
-/// field is the *only* thing that marks the line as addon-to-addon data rather than speech
-/// (decision 1029). The real client routes it to the `CHAT_MSG_ADDON` event; it never reaches the
-/// chat frame.
-///
-/// The server treats it as its own class throughout: exempt from the `KnowsLanguage` gate, from
-/// flood control, and from message sanitizing (`SanitizeChatMessage` returns early,
-/// `Handlers/ChatHandler.cpp:49`); gated instead by the `AddonChannel` config
-/// (`ChatHandler.cpp:165`); and restricted by `WorldSession::IsLanguageAllowedForChatType`
-/// (`ChatHandler.cpp:84`) to the group/guild/channel lanes — PARTY, RAID, RAID_LEADER,
-/// RAID_WARNING, GUILD, OFFICER, BATTLEGROUND, BATTLEGROUND_LEADER, CHANNEL. Never
-/// SAY/YELL/EMOTE/WHISPER, which is why addon traffic can never reach a chat bubble or a
-/// `/r` target. It is also the one language the server never rewrites: the whole
-/// GM/two-side/`SPELL_AURA_MOD_LANGUAGE` normalisation block lives in that check's `else`
-/// (`ChatHandler.cpp:176-218`), so on the party lane a line's language is either a tongue (often
-/// normalised to `Universal`) or exactly this.
-///
-/// **The client's own send set is narrower than the server's permission list.** VERIFIED in
-/// `WoW.exe` (5875) — wow-re `system/ui/scratch/addon-chat-law.md`: `SendAddonMessage`
-/// (`0x49f920`) hard-whitelists **four** types at `0x49fa3f`-`0x49fa4e` — PARTY, RAID, GUILD,
-/// BATTLEGROUND — and the receive side's `distribution` argument uses the same four (remap table
-/// `0x49aff4`), reporting every other type as the literal `"UNKNOWN"`. So a real client accepts
-/// addon traffic on lanes it will never itself send on.
+/// `LANG_ADDON` (vmangos `SharedDefines.h:270`): marks a chat line as addon data, not speech;
+/// 1.12 has no addon opcode, and the client routes such a line to `CHAT_MSG_ADDON`. The server
+/// skips language, flood and sanitize checks for it, never rewrites it, and allows it only on the
+/// group, guild and channel lanes (`ChatHandler.cpp:49,84,176-218`). The 1.12 `SendAddonMessage`
+/// (`0x49f920`) sends only PARTY, RAID, GUILD and BATTLEGROUND, and the receive side names any
+/// other lane "UNKNOWN" (`0x49aff4`).
 pub const LANGUAGE_ADDON: u32 = 0xFFFF_FFFF;
 
-/// The language a character speaks by default — its faction tongue. Every send must carry a
-/// language the character *knows*: vmangos drops the whole message (including a `.command`
-/// payload, which is intercepted downstream of the check) with a "not learned" notification
-/// otherwise (`HandleChatMessageOpcode`'s `KnowsLanguage` gate, `Handlers/ChatHandler.cpp`).
-/// Race → tongue VERIFIED against the live world DB (`playercreateinfo_spell`): races 1/3/4/7
-/// (Alliance) learn spell 668 Language Common, races 2/5/6/8 (Horde) learn 669 Language Orcish.
+/// A race's faction tongue. vmangos drops a chat line, `.command`s included, in a language the
+/// speaker does not know (`KnowsLanguage`, `Handlers/ChatHandler.cpp`); races 2/5/6/8 learn 669
+/// Language Orcish, the rest 668 Language Common (`playercreateinfo_spell`).
 pub fn faction_language(race: u8) -> u32 {
     match race {
         2 | 5 | 6 | 8 => LANGUAGE_ORCISH, // orc, undead, tauren, troll
         _ => LANGUAGE_COMMON,             // human, dwarf, night elf, gnome
     }
 }
-/// `ChatMsg` wire values benilla sends, widened to `u32` (VERIFIED vmangos `SharedDefines.h:
-/// 1191-1301`) — `CMSG_MESSAGECHAT`'s `type` field is a `u32` on the wire
-/// (`WorldPackets::Chat::ChatMessage::type`, `Server/Packets/Chat.h:12`), unlike the inbound
-/// `SMSG_MESSAGECHAT` decode's `u8` (hence the separate, narrower [`CHAT_MSG_SAY`] etc. set there):
-/// two constant sets for the same enum because the two wire fields are different widths.
+/// `ChatMsg` values (vmangos `SharedDefines.h:1191-1301`) as `CMSG_MESSAGECHAT`'s `u32` `type`
+/// (`Server/Packets/Chat.h:12`). The inbound `u8` field has its own set, [`CHAT_MSG_SAY`] etc.
 pub const CHAT_TYPE_SAY: u32 = 0x0;
 pub const CHAT_TYPE_PARTY: u32 = 0x1;
 pub const CHAT_TYPE_RAID: u32 = 0x2;
@@ -372,9 +324,9 @@ pub const CHAT_TYPE_EMOTE: u32 = 0x8;
 pub const CHAT_TYPE_CHANNEL: u32 = 0xE;
 pub const CHAT_TYPE_AFK: u32 = 0x14;
 pub const CHAT_TYPE_DND: u32 = 0x15;
-/// `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_10_2` — active for 5875.
+/// `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_10_2`: active for 5875.
 pub const CHAT_TYPE_RAID_LEADER: u32 = 0x57;
 pub const CHAT_TYPE_RAID_WARNING: u32 = 0x58;
-/// `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_11_2` — active for 5875.
+/// `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_11_2`: active for 5875.
 pub const CHAT_TYPE_BATTLEGROUND: u32 = 0x5C;
 pub const CHAT_TYPE_BATTLEGROUND_LEADER: u32 = 0x5D;
diff --git a/crates/benilla-protocol/src/messages/monster_move.rs b/crates/benilla-protocol/src/messages/monster_move.rs
index 8cb9b20f..63ec064a 100644
--- a/crates/benilla-protocol/src/messages/monster_move.rs
+++ b/crates/benilla-protocol/src/messages/monster_move.rs
@@ -1,19 +1,7 @@
-//! `SMSG_MONSTER_MOVE` — the server-dictated creature movement path — and its transport twin.
-//!
-//! One packet: a mover, its `start`, a spline id, a `moveType`-switched final facing, then (unless it is
-//! a `Stop`) the spline block — a flag word, a duration, and the waypoints. Decodes into the full
-//! travel-order polyline [`ServerPacket::MonsterMove::path`] the app rides at constant (arc-length) speed
-//! (decision 0097). The wire packs the waypoints two ways, keyed by the `Flying`/`Mask_CatmullRom` flag —
-//! see [`read_monster_move_spline`].
-//!
-//! **`SMSG_MONSTER_MOVE_TRANSPORT` is the same packet with one field inserted**: a second packed guid,
-//! the transport's, immediately after the mover's — and every coordinate in the body is then an
-//! **offset in that transport's frame**, not world space (decision 1936). vmangos writes exactly that
-//! (`Movement::MoveSplineInit::Launch`, `spline/MoveSplineInit.cpp:138-170`: the same builder, the
-//! opcode swapped and the transport packed guid appended, after `CalculatePassengerOffset` has moved
-//! the start into deck space), and it computes such a path against the transport's **model** navmesh
-//! rather than the map's (`PathFinder::calculate`, `Maps/PathFinder.cpp:76-84`), so the waypoints are
-//! deck-local too. One reader serves both, keyed by [`read_monster_move`]'s `on_transport`.
+//! `SMSG_MONSTER_MOVE`: a mover, its start, a spline id, a `moveType` facing, then (unless a stop)
+//! spline flags, a duration and the waypoints. `SMSG_MONSTER_MOVE_TRANSPORT` inserts the
+//! transport's packed guid after the mover's, and every coordinate is then deck-local, waypoints
+//! included (vmangos `MoveSplineInit.cpp:138-170`, `PathFinder.cpp:76-84`).
 
 use std::io;
 
@@ -23,46 +11,26 @@ use crate::wire::{
     read_u64_le, read_u8, Vector3d,
 };
 
-/// `MonsterMoveType::Stop` (`SMSG_MONSTER_MOVE`).
 const MONSTER_MOVE_STOP: u8 = 0x1;
-/// `SplineFlags::Flying` in the `SMSG_MONSTER_MOVE` spline-flags word. When set, the unit follows the
-/// path's **own Z** (a 3-D flight path, points sent explicit); when clear, the path is a *ground* walk
-/// and the real client **discards the spline Z and re-derives it from the terrain** under the unit (the
-/// swept-collision down-probe — byte-verified in wow-5875-re: the grounded fork zeroes the spline's
-/// Z-delta at `0x616cb0` and the WALK resolver `0x634040 → 0x6367b0` reads Z off the world trace
-/// `0x6721b0`). benilla mirrors that split: a non-flying spline is terrain-clamped, a flying one keeps
-/// its Z. The client gates on this same bit (`0x6018f0: test ah,0x2`). It is also `Mask_CatmullRom` —
-/// flying paths interpolate (and wire-encode) as a curve, ground paths as straight segments.
+/// `SplineFlags::Flying`, also `Mask_CatmullRom` (tested at `0x6018f0`). Set, the unit keeps the
+/// path's own Z along a curve; clear, the 1.12 client drops the spline Z (`0x616cb0`) and takes Z
+/// from the terrain (`0x634040`), moving along straight segments.
 const SPLINE_FLAG_FLYING: u32 = 0x200;
-/// `SPLINEFLAG_RUNMODE` — the path is travelled at run speed. Its **absence** is what matters:
-/// the real client feeds this bit straight into `CMovement::SetRunMode 0x7c71c0`
-/// (`0x7c6ac2 and edi,0x100` → `0x7c6acb call 0x7c71c0`, inside the `SMSG_MONSTER_MOVE` commit
-/// `0x7c6a50`), and that setter's argument is *run* — so a spline **without** this bit **sets**
-/// `MOVEFLAG_WALK_MODE` on the unit it moves. The two `0x100`s are inverses of each other
-/// (wow-re `collision/scratch/walk-mode-law.md` §5.2; benilla decision 1758).
+/// `SPLINEFLAG_RUNMODE`: run speed. The 1.12 client passes it to `CMovement::SetRunMode`
+/// (`0x7c71c0`, from `0x7c6ac2`), so a spline without it sets `MOVEFLAG_WALK_MODE` on the unit.
 const SPLINE_FLAG_RUNMODE: u32 = 0x100;
 
-/// Parse an `SMSG_MONSTER_MOVE` body into [`ServerPacket::MonsterMove`]. The head (mover, `start`, spline
-/// id, `moveType` + its final facing) is always present; a **stop** (`moveType 1`) ends there (the client
-/// reads no flags/duration/points and implies `flags=0x100, count=1, duration=0` — wow-re RF-0049;
-/// reading a tail anyway over-ran the body, the `0x00dd: failed to fill whole buffer` skip that dropped
-/// every creature stop). Otherwise the spline block yields the full polyline `[start, …waypoints…,
-/// endpoint]`.
+/// A stop (`moveType` 1) ends after the head: the 1.12 client reads no spline block and implies
+/// `flags = 0x100, count = 1, duration = 0`. Otherwise the path runs `[start, …, endpoint]`.
 pub(super) fn read_monster_move(r: &mut &[u8], on_transport: bool) -> io::Result<ServerPacket> {
     let guid = read_packed_guid(r)?;
-    // `SMSG_MONSTER_MOVE_TRANSPORT` only: the deck the whole body is expressed on, packed like the
-    // mover's guid and read immediately after it. Everything below is unchanged — the two opcodes
-    // share the builder server-side and differ by this one field.
     let transport = on_transport.then(|| read_packed_guid(r)).transpose()?;
     let start = Vector3d::read(r)?;
-    // The server's per-move spline counter. Discarded for a creature (nothing acks its walk), but
-    // the client echoes it back in `CMSG_MOVE_SPLINE_DONE` when a spline drives its OWN player
-    // (Charge/knockback/taxi): the server validates the ack against the newest spline id.
+    // Echoed in `CMSG_MOVE_SPLINE_DONE` when the spline moves our own player (charge, knockback,
+    // taxi); the server checks it against its newest spline id.
     let spline_id = read_u32_le(r)?;
     let move_type = read_u8(r)?;
-    // The `moveType`-switched final facing (jumptable `0x602114`): 2 = spot, 3 = target guid, 4 = angle.
-    // The real client snaps the unit to it (`0x7c6f30`); benilla applies it in the net bridge. A plain
-    // move (0) / stop (1) dictates no facing.
+    // Final facing (jumptable `0x602114`); the 1.12 client snaps the unit to it (`0x7c6f30`).
     let facing = match move_type {
         2 => {
             let spot = Vector3d::read(r)?;
@@ -83,8 +51,7 @@ pub(super) fn read_monster_move(r: &mut &[u8], on_transport: bool) -> io::Result
             stop: true,
             duration_ms: 0,
             flying: false,
-            // The stop form carries no spline-flags dword at all, so there is no run/walk verdict
-            // in it — and it builds no path, so nothing downstream reads this.
+            // A stop carries no flags and builds no path; nothing reads this.
             run_mode: true,
         }
     } else {
@@ -92,18 +59,12 @@ pub(super) fn read_monster_move(r: &mut &[u8], on_transport: bool) -> io::Result
         let duration_ms = read_u32_le(r)?;
         let flying = spline_flags & SPLINE_FLAG_FLYING != 0;
         let run_mode = spline_flags & SPLINE_FLAG_RUNMODE != 0;
-        // The decoded waypoints *after* the start (see [`read_monster_move_spline`]): a ground path's
-        // first packed point re-encodes `start` (quantized), so drop it and anchor the path with the
-        // exact wire `start`; a flying path sends only post-start points, kept whole. The result is the
-        // full travel-order polyline `[start, …waypoints…, endpoint]`.
+        // Both layouts ship only the points after the start, so the head's `start` leads the path.
         let tail = read_monster_move_spline(r, flying)?;
         let path = if tail.is_empty() {
             Vec::new()
         } else {
-            let skip = usize::from(!flying && tail.len() >= 2);
-            std::iter::once(start)
-                .chain(tail.into_iter().skip(skip))
-                .collect()
+            std::iter::once(start).chain(tail).collect()
         };
         ServerPacket::MonsterMove {
             guid,
@@ -120,52 +81,29 @@ pub(super) fn read_monster_move(r: &mut &[u8], on_transport: bool) -> io::Result
     })
 }
 
-/// `SMSG_MONSTER_MOVE` spline points → the reconstructed **absolute** waypoints the block carries, in
-/// travel order (the point *after* the start … the endpoint). Two wire layouts, keyed by `catmull_rom`
-/// (the `Mask_CatmullRom` = `Flying` spline flag), both from vmangos `PacketBuilder`:
-///
-/// - **Ground (linear, `WriteLinearPath`):** a `u32` count, then the endpoint as an absolute `Vector3d`,
-///   then `count − 1` packed `i32` offsets — `endpoint − waypoint` per point (see [`packed_to_vector3d`]),
-///   in travel order. We invert each (`waypoint = endpoint − offset`) and append the endpoint, so the
-///   returned list is `[waypoint₀ ≈ start, waypoint₁, …, endpoint]`. `waypoint₀` re-encodes the packet's
-///   `start` (¼-yd quantized); the caller drops it in favour of the exact `start`.
-///   **`count == 2` carries no offsets at all**: vmangos guards the offset loop with `last_idx > 1`
-///   (`packet_builder.cpp:92`) while still writing `last_idx + 1` as the count, so a plain two-point
-///   `MoveTo` announces 2 points and ships only the destination. Reading the phantom offset anyway
-///   over-runs the body and the whole packet is skipped — i.e. that creature stops dead until its next
-///   move, the same freeze decision 0708 is about. Never observed on this deploy (its pathfinder emits
-///   3+ point paths, verified over four live runs: no `nodes=2` in any `csp`/`mmv` trace), but a map
-///   without mmaps would hit it on every step.
-/// - **Flying (Catmull-Rom, `WriteCatmullRomPath`):** a `u32` count, then `count` **absolute** `Vector3d`s
-///   (the control points from `getPoint(2)` on — the post-start waypoints through the endpoint). Returned
-///   verbatim. (Reading these as packed offsets — the old single-layout path — mis-sized the body and
-///   dropped every flight move.)
-///
-/// The client interpolates a ground path **piecewise-linearly, arc-length-parameterised** through all of
-/// these (wow-re curvemath RF-0048/RF-0052: the creature follow's point-at-t is `linear_pos_diff`, not the
-/// Catmull-Rom blend — only flying units take the curved family).
+/// The absolute waypoints after the start, endpoint last (vmangos `PacketBuilder`). Flying
+/// (`WriteCatmullRomPath`): a `u32` count, then that many absolute points. Ground
+/// (`WriteLinearPath`): a `u32` count, the absolute endpoint, then `count - 1` packed
+/// `endpoint - waypoint` offsets. The start is not among them: vmangos writes from
+/// `firstPoint = 1` (`MoveSplineInit.cpp:169`), and the reference decoder (`0x6018f0`) reads
+/// the same `count - 1`.
 fn read_monster_move_spline(r: &mut &[u8], catmull_rom: bool) -> io::Result<Vec<Vector3d>> {
     let count = read_u32_le(r)?;
-    // Cap the *pre-allocation* (not the read) at a sane bound — a corrupt `count` must not reserve GBs;
-    // the read itself still errors the instant the (bounded) body underruns.
+    // 0xFFFF bounds only the pre-allocation against a corrupt `count`.
     if catmull_rom {
-        // Absolute control points, verbatim.
         let mut points = Vec::with_capacity(capacity_hint(count, 0xFFFF));
         for _ in 0..count {
             points.push(Vector3d::read(r)?);
         }
         return Ok(points);
     }
-    // Endpoint (absolute) + packed offsets from it; invert to absolute, endpoint last.
     if count == 0 {
         return Ok(Vec::new());
     }
     let endpoint = Vector3d::read(r)?;
     let mut points = Vec::with_capacity(capacity_hint(count, 0xFFFF));
-    // `count == 2` ⇒ the producer skipped its offset loop entirely (`last_idx > 1`); the destination is
-    // the whole payload, and the caller pairs it with the packet's exact `start`.
-    let offsets = if count > 2 { count - 1 } else { 0 };
-    for _ in 0..offsets {
+    // `count == 1` is a straight hop: no offsets (vmangos: `if (last_idx > 1)`).
+    for _ in 1..count {
         let off = packed_to_vector3d(read_i32_le(r)?);
         points.push(Vector3d {
             x: endpoint.x - off.x,
@@ -180,10 +118,10 @@ fn read_monster_move_spline(r: &mut &[u8], catmull_rom: bool) -> io::Result<Vec<
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::messages::{opcode, parse_server};
+    use crate::messages::{opcode, parse_server, parse_server_with_tail};
     use crate::wire::write_packed_guid;
 
-    /// The fixed head of a `SMSG_MONSTER_MOVE`: packed guid, start pos, splineId, moveType.
+    /// The fixed head: packed guid, start, splineId, moveType.
     fn head(guid: u64, start: [f32; 3], move_type: u8) -> Vec<u8> {
         let mut b = Vec::new();
         write_packed_guid(guid, &mut b).unwrap();
@@ -195,22 +133,20 @@ mod tests {
         b
     }
 
-    /// The producer's linear encoder, transcribed from vmangos `PacketBuilder::WriteLinearPath`:
-    /// count = number of points, the **endpoint** written absolute, then each earlier point as a packed
-    /// `endpoint − point` offset in travel order. `path` is the full `[start, …mids…, endpoint]`.
-    /// The `last_idx > 1` guard is transcribed too: a **two**-point path writes the count and the
-    /// destination and stops — no offsets at all, not even for the start.
+    /// vmangos `WriteLinearPath` from `firstPoint = 1` over `path = [c₀, …, cₙ₋₁]`: the count
+    /// `n - 1`, the endpoint, then `c₁ … cₙ₋₂` as packed `endpoint - point` offsets.
     fn append_linear_path(body: &mut Vec<u8>, path: &[[f32; 3]]) {
         let (&endpoint, leading) = path.split_last().expect("a path has an endpoint");
-        body.extend_from_slice(&(path.len() as u32).to_le_bytes());
+        let last_idx = path.len() - 1;
+        body.extend_from_slice(&(last_idx as u32).to_le_bytes()); // last_idx − start + 1
         for f in endpoint {
             body.extend_from_slice(&f.to_le_bytes());
         }
-        if path.len() <= 2 {
-            return; // vmangos `packet_builder.cpp:92` — `if (last_idx > 1)`
+        if last_idx <= 1 {
+            return; // vmangos `packet_builder.cpp:92`: `if (last_idx > 1)`
         }
-        // `leading` = [start, …mids…]; each packed as endpoint − point (¼-yd quantized).
-        for &p in leading {
+        // `for (i = start; i < last_idx; ++i)` with `start = 1`, packed in ¼-yd units.
+        for &p in &leading[1..] {
             let pack = |v: f32, shift: u32, mask: i32| ((v * 4.0).round() as i32 & mask) << shift;
             let off = [endpoint[0] - p[0], endpoint[1] - p[1], endpoint[2] - p[2]];
             let packed = pack(off[0], 0, 0x7FF) | pack(off[1], 11, 0x7FF) | pack(off[2], 22, 0x3FF);
@@ -218,12 +154,7 @@ mod tests {
         }
     }
 
-    /// `SMSG_MONSTER_MOVE_TRANSPORT` is `SMSG_MONSTER_MOVE` with the transport's packed guid
-    /// inserted between the mover's guid and the start position — everything after it parses
-    /// identically, and every coordinate is then a deck-local offset. Reading the *plain* opcode's
-    /// layout for it would consume the transport guid as the start's X and Y and land the creature
-    /// somewhere near the map origin; reading the transport layout for a plain packet is the same
-    /// mistake in reverse. Both directions are pinned here (decision 1936).
+    /// Each opcode reads its own layout; the plain one must not find a transport guid.
     #[test]
     fn monster_move_transport_reads_the_deck_guid_first() {
         let mut body = Vec::new();
@@ -255,19 +186,16 @@ mod tests {
             _ => panic!("expected MonsterMove"),
         }
 
-        // The plain opcode over the SAME bytes must NOT come back with a transport — and it
-        // mis-reads the head, which is exactly why the two layouts cannot share one arm.
+        // The plain opcode over the same bytes must not come back with a transport.
         match parse_server(opcode::SMSG_MONSTER_MOVE, &body) {
             Ok(ServerPacket::MonsterMove { transport, .. }) => assert_eq!(transport, None),
             Ok(_) => panic!("expected MonsterMove"),
-            Err(_) => {} // an under-run is equally fine: the point is that it is not the same read
+            Err(_) => {} // an under-run is fine too: it is not the same read
         }
     }
 
     #[test]
     fn monster_move_stop_has_no_tail() {
-        // A STOP (moveType 1) is head-only: no flags/duration/points. Parsing the tail anyway
-        // over-ran the body and skipped the packet (`0x00dd: failed to fill whole buffer`).
         let body = head(0x1234, [1.0, 2.0, 3.0], MONSTER_MOVE_STOP);
         let p = parse_server(opcode::SMSG_MONSTER_MOVE, &body).expect("a stop parses head-only");
         match p {
@@ -281,7 +209,7 @@ mod tests {
 
     #[test]
     fn monster_move_facing_angle_is_captured() {
-        // A facing-angle move (moveType 4): head, angle, then flags/duration/count + one point.
+        // moveType 4 carries a facing angle.
         let mut body = head(0x55, [0.0, 0.0, 0.0], 4);
         body.extend_from_slice(&1.25f32.to_le_bytes()); // facing angle
         body.extend_from_slice(&0u32.to_le_bytes()); // spline flags (ground)
@@ -301,7 +229,6 @@ mod tests {
             } => {
                 assert!(!stop);
                 assert_eq!(duration_ms, 500);
-                // A count-1 (endpoint-only) move is the two-point straight hop `[start, endpoint]`.
                 assert_eq!(path.len(), 2, "start + endpoint");
                 assert!((path[0].x - 0.0).abs() < 1e-6, "anchored at the wire start");
                 assert!((path[1].x - 10.0).abs() < 1e-6, "endpoint verbatim");
@@ -314,17 +241,15 @@ mod tests {
         }
     }
 
-    /// The plain two-point hop — a `MoveTo` with no intermediate waypoints. vmangos announces `count = 2`
-    /// but ships **only** the destination (its offset loop is guarded by `last_idx > 1`), so a decoder
-    /// that trusts the count and reads `count − 1` offsets over-runs the body and the packet is skipped
-    /// entirely — the creature freezes where it stands. Encoded here by the transcribed producer above.
     #[test]
     fn monster_move_two_point_path_carries_no_offsets() {
         let mut body = head(0x77, [4.0, 8.0, 0.0], 0);
         body.extend_from_slice(&0u32.to_le_bytes()); // spline flags: ground
         body.extend_from_slice(&1_000u32.to_le_bytes()); // duration
         append_linear_path(&mut body, &[[4.0, 8.0, 0.0], [12.0, 8.0, 0.0]]);
-        let p = parse_server(opcode::SMSG_MONSTER_MOVE, &body).expect("a two-point hop parses");
+        let (p, tail) = parse_server_with_tail(opcode::SMSG_MONSTER_MOVE, &body)
+            .expect("a two-point hop parses");
+        assert_eq!(tail, 0, "the body is exactly the count and the destination");
         match p {
             ServerPacket::MonsterMove { path, .. } => {
                 assert_eq!(path.len(), 2, "start + destination, got {path:?}");
@@ -334,12 +259,37 @@ mod tests {
         }
     }
 
+    /// Hand-assembled rather than through `append_linear_path`: the route `c₀ → c₁ → c₂` is
+    /// `count = 2`, the endpoint `c₂` and one packed offset `c₂ - c₁`.
+    #[test]
+    fn monster_move_one_corner_path_keeps_its_corner() {
+        let mut body = head(0x77, [0.0, 0.0, 0.0], 0); // c₀ in the head
+        body.extend_from_slice(&0u32.to_le_bytes()); // spline flags: ground
+        body.extend_from_slice(&2_000u32.to_le_bytes()); // duration
+        body.extend_from_slice(&2u32.to_le_bytes()); // count = last_idx − start + 1 = 2
+        for f in [10.0f32, 10.0, 0.0] {
+            body.extend_from_slice(&f.to_le_bytes()); // endpoint c₂
+        }
+        // c₂ − c₁ = (0, 10, 0): x 0, y 10·4 = 40 at bit 11, z 0 (`appendPackXYZ`'s ¼-yd fields).
+        body.extend_from_slice(&(40i32 << 11).to_le_bytes());
+        let (p, tail) =
+            parse_server_with_tail(opcode::SMSG_MONSTER_MOVE, &body).expect("a corner path parses");
+        assert_eq!(tail, 0, "the one offset is read, not left behind");
+        match p {
+            ServerPacket::MonsterMove { path, .. } => {
+                let got: Vec<[f32; 3]> = path.iter().map(|v| [v.x, v.y, v.z]).collect();
+                assert_eq!(
+                    got,
+                    vec![[0.0, 0.0, 0.0], [10.0, 0.0, 0.0], [10.0, 10.0, 0.0]]
+                );
+            }
+            _ => panic!("expected MonsterMove"),
+        }
+    }
+
     #[test]
     fn monster_move_ground_path_decodes_every_waypoint() {
-        // A four-waypoint ground patrol, encoded exactly as vmangos `WriteLinearPath` ships it, must
-        // round-trip to the full travel-order polyline — not collapse to `start → endpoint`. Points are
-        // ¼-yd multiples so the packed quantization is exact. The start is anchored from the wire `start`
-        // (the redundant quantized first packed point is dropped).
+        // ¼-yd multiples, so the packed quantization is exact.
         let want = [
             [0.0f32, 0.0, 0.0], // start
             [10.0, 0.0, 0.0],   // corner east
@@ -376,9 +326,6 @@ mod tests {
 
     #[test]
     fn monster_move_flying_path_reads_absolute_points() {
-        // A flying (`Mask_CatmullRom`) move ships its waypoints ABSOLUTE (vmangos `WriteCatmullRomPath`),
-        // not as packed offsets. The parser must switch layouts on the flag — the old single-layout read
-        // mis-sized the body and dropped every flight. `count` = post-start points; the start prepends.
         let mids = [[3.0f32, 4.0, 50.0], [6.0, 8.0, 55.0]];
         let mut body = head(0x77, [0.0, 0.0, 40.0], 0);
         body.extend_from_slice(&SPLINE_FLAG_FLYING.to_le_bytes()); // flying ⇒ catmull-rom layout
diff --git a/crates/benilla-protocol/src/messages/movement.rs b/crates/benilla-protocol/src/messages/movement.rs
index caddfe01..d27b3a4c 100644
--- a/crates/benilla-protocol/src/messages/movement.rs
+++ b/crates/benilla-protocol/src/messages/movement.rs
@@ -1,50 +1,29 @@
-//! The shared movement vocabulary: the `MovementInfo` body (+ its `JumpInfo` ballistic tail and
-//! `TransportPose` rider tail) every `MSG_MOVE_*` relay carries, its flag bits, and the parse — read by
-//! the update-object living block and [`super`]'s relay arms, written by [`super::client`]'s outbound
-//! movement.
+//! The `MovementInfo` body every `MSG_MOVE_*` carries, its flag bits, and the movement verbs.
 
 use std::io::{self, Read};
 
 use crate::wire::{read_f32_le, read_u32_le, read_u64_le, Vector3d};
 
-// MovementFlags bits, shared by the living [`MovementBlock`](super::MovementBlock) (in
-// `update_object`) and the client [`MovementInfo`] parse ([`read_movement_info`]) below.
-// ON_TRANSPORT is 1.12's bit 25 (vmangos `MovementInfo.h:56` `MOVEFLAG_ONTRANSPORT = 0x02000000`)
-// — NOT the TBC-era 0x200, which in vanilla is `MOVEFLAG_UNUSED10`. The original transcription
-// carried 0x200; caught 2026-07-17 against the vmangos source when riding (0438 phase 2) landed.
+// MovementFlags bits (vmangos `MovementInfo.h`). ON_TRANSPORT is 1.12's 0x0200_0000
+// (`MovementInfo.h:56`), not TBC's 0x200, which 1.12 names `MOVEFLAG_UNUSED10`.
 pub(super) const MOVEMENT_FLAG_ON_TRANSPORT: u32 = 0x0200_0000;
 pub(super) const MOVEMENT_FLAG_JUMPING: u32 = 0x2000;
 pub(super) const MOVEMENT_FLAG_SWIMMING: u32 = 0x20_0000;
 pub(super) const MOVEMENT_FLAG_SPLINE_ENABLED: u32 = 0x40_0000;
 pub(super) const MOVEMENT_FLAG_SPLINE_ELEVATION: u32 = 0x400_0000;
 
-/// Read `MSG_MOVE_TIME_SKIPPED` — one observed mover's **packed** guid and the milliseconds its
-/// own client skipped (VERIFIED: the reference's handler `0x603b40` reads a packed guid through
-/// `0x642ed0`, resolves under `TYPEMASK_UNIT`, then reads a plain `u32`; vmangos relays exactly
-/// that shape, `MovementHandler.cpp:1011-1017`).
-///
-/// Note the **asymmetry with the client's own send**, which is the same fact in the other
-/// direction and writes a *plain* 8-byte guid (see [`super::client::move_time_skipped`]).
-/// Inbound packed, outbound plain — that is the reference's own encoding, not a slip.
+/// `MSG_MOVE_TIME_SKIPPED` inbound: a packed guid and the ms that mover's client skipped
+/// (reference handler `0x603b40`; vmangos `MovementHandler.cpp:1011-1017`). Our own send uses a
+/// plain 8-byte guid ([`super::client::move_time_skipped`]); the asymmetry is the reference's.
 pub(super) fn read_move_time_skipped(r: &mut &[u8]) -> io::Result<(u64, u32)> {
     let guid = crate::wire::read_packed_guid(r)?;
     let lag_ms = read_u32_le(r)?;
     Ok((guid, lag_ms))
 }
 
-/// Read a wire `MovementInfo` — the body shared by every `MSG_MOVE_*` (and the teleport ack). Surfaces
-/// `flags`/`position`/`orientation`/`timestamp`/`fall_time`, the **transport pose** ([`TransportPose`],
-/// present iff `MOVEFLAG_ON_TRANSPORT` — this is how a boarded rider's `MSG_MOVE_*` heartbeat carries
-/// its local frame, decision 0438 "Riding is the mover's platform frame"), the **swim pitch**
-/// (`Self::pitch`, present iff `MOVEFLAG_SWIMMING`), and the **jump tail** ([`JumpInfo`], so an
-/// observer can replay a jump arc); the spline-elevation tail is parsed to stay aligned but discarded.
-///
-/// VERIFIED byte-for-byte against vmangos `MovementInfo::Read` (build 1.12.1): note 1.12 has **no**
-/// transport-time field after the transport pose — that was added in TBC. (The `update_object`
-/// movement-block transport read, proven against `wow_world_messages`, omits it for the same reason.)
-/// The **swim pitch** is a lone `f32` after the (optional) transport pose and before `fallTime`, gated on
-/// `MOVEFLAG_SWIMMING`. `fallTime` is a `u32` and the jump tail (gated on `MOVEFLAG_JUMPING`) is `zspeed,
-/// cosAngle, sinAngle, xyspeed`, after `fallTime` and before the spline-elevation float.
+/// vmangos `MovementInfo::Read` order: flags, time, position, facing, the transport pose if
+/// `ON_TRANSPORT` (1.12 has no transport time), the swim pitch if `SWIMMING`, `u32` fall time, the
+/// jump tail if `JUMPING`, then a spline-elevation `f32` if `SPLINE_ELEVATION`, read and dropped.
 pub(super) fn read_movement_info(r: &mut impl Read) -> io::Result<MovementInfo> {
     let flags = read_u32_le(r)?;
     let timestamp = read_u32_le(r)?;
@@ -52,9 +31,7 @@ pub(super) fn read_movement_info(r: &mut impl Read) -> io::Result<MovementInfo>
     let orientation = read_f32_le(r)?;
     let transport = if flags & MOVEMENT_FLAG_ON_TRANSPORT != 0 {
         Some(TransportPose {
-            // A FULL u64, not packed: vmangos `data >> t_guid` resolves to the plain
-            // `ObjectGuid` operator (`ObjectGuid.cpp:180`, `buf.read<uint64>()`); the packed
-            // reader is a distinct operator this path never uses.
+            // A full u64, not packed (vmangos `ObjectGuid.cpp:180`, `buf.read<uint64>()`).
             guid: read_u64_le(r)?,
             pos: Vector3d::read(r)?,
             orientation: read_f32_le(r)?,
@@ -93,11 +70,10 @@ pub(super) fn read_movement_info(r: &mut impl Read) -> io::Result<MovementInfo>
     })
 }
 
-// --- shared movement vocabulary (read by the arms above, written by `client`) ---------------------
+// --- movement vocabulary ---
 
-/// Which of a mover's six movement speeds a force-speed-change packet addresses — the wire family's
-/// shared axis (each kind is its own SMSG/CMSG opcode pair; see [`super::opcode`]'s force-speed
-/// block). Order matches the `LIVING` block's speed array and vmangos `UnitMoveType`.
+/// A mover speed, each with its own force-change opcode pair; the order is the `LIVING` block's
+/// speed array and vmangos `UnitMoveType`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SpeedKind {
     Walk,
@@ -123,25 +99,11 @@ impl SpeedKind {
     }
 }
 
-/// **A granted mover *mode*** — one of the four the server hands the controlling client, each a
-/// single `MOVEMENTFLAGS` bit that changes how the mover behaves rather than where it is going
-/// (decision 0866). Sibling of [`SpeedKind`]: same shape (a mode per opcode pair, an ack per mode),
-/// same reason for existing — the server treats the set as one family (`IsFlagAckOpcode`,
-/// `MovementChangeType`), so we do too, and a fifth mode is a variant rather than a new lane.
-///
-/// The bit values are 1.12's, VERIFIED vmangos `Objects/MovementInfo.h:25-62`. What each one *does*
-/// is the client's own business — the server only grants it — and all four are byte-verified in the
-/// reference's CMovement setter cluster (`0x7c7280`–`0x7c7370`, wow-re `system/collision`):
-///
-/// | mode | bit | reference effect | granted by |
-/// |---|---|---|---|
-/// | [`Root`](Self::Root) | `0x0000_1000` | translation dies; the fall stops. **Turning stays live**, by the input tick's authored allow-list (`0x618054`). | root/stun/death |
-/// | [`WaterWalk`](Self::WaterWalk) | `0x1000_0000` | the liquid surface becomes walkable ground | `SPELL_AURA_WATER_WALK` (104) |
-/// | [`FeatherFall`](Self::FeatherFall) | `0x2000_0000` | terminal fall velocity drops to 7 yd/s from 60.148 (`0x7c5d20`) | `SPELL_AURA_FEATHER_FALL` (105) |
-/// | [`Hover`](Self::Hover) | `0x4000_0000` | ground contact rises by 1.0 yd (walk resolver `0x6367b0`) | `SPELL_AURA_HOVER` (106) |
-///
-/// **Levitate (1706) grants three of them at once** — feather fall + hover + water walk — which is
-/// what makes them one system rather than four coincidences.
+/// A mode the server grants the controlling client, one `MOVEMENTFLAGS` bit each (vmangos
+/// `MovementInfo.h:25-62`, reference setters `0x7c7280`-`0x7c7370`). Root stops translation and
+/// falling but not turning (`0x618054`); water walk makes liquid walkable (aura 104); feather fall
+/// caps the fall at 7 yd/s instead of 60.148 (aura 105, `0x7c5d20`); hover lifts ground contact by
+/// 1.0 yd (aura 106, `0x6367b0`). Levitate (spell 1706) grants the last three at once.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum MoveMode {
     Root,
@@ -161,8 +123,8 @@ impl MoveMode {
         }
     }
 
-    /// The `CMSG_*_ACK` opcode answering this mode's SMSG. Root is the only mode whose two
-    /// directions ack on *different* opcodes (vmangos routes both to `HandleMoveRootAck`).
+    /// The `CMSG_*_ACK` answering this mode's SMSG. Only root acks apply and remove on different
+    /// opcodes (vmangos routes both to `HandleMoveRootAck`).
     pub fn ack_opcode(self, apply: bool) -> u16 {
         use super::opcode;
         match (self, apply) {
@@ -174,53 +136,32 @@ impl MoveMode {
         }
     }
 
-    /// Whether the ack body carries the trailing `u32 apply` dword. Root's does **not**: it lands on
-    /// vmangos's `HandleMoveRootAck` (which infers apply from the opcode), while the other three land
-    /// on `HandleMovementFlagChangeToggleAck`, which reads it (`Server/Packets/Movement.cpp:38-59`).
+    /// Whether the ack ends in a `u32 apply`: not root's, whose handler infers it from the opcode
+    /// (vmangos `Server/Packets/Movement.cpp:38-59`).
     pub fn ack_carries_apply(self) -> bool {
         !matches!(self, MoveMode::Root)
     }
 }
 
-/// **A movement mode granted on a unit we do not control** — the `SMSG_SPLINE_MOVE_*` twelve
-/// (decision 1780), the observer half of [`MoveMode`]'s family.
-///
-/// Same bits, and for the four they share the same reference setters — but it is a *different
-/// message*, and the three differences are what the type exists to keep straight:
-///
-/// 1. **No counter and no ack.** The controller's family is a handshake (`packed guid + u32
-///    counter`, ack or the server never applies it); this one is a bare `packed guid` broadcast.
-///    The client's handler `0x603c80` replies to nothing.
-/// 2. **Any unit.** `0x603c80` resolves the guid with `TYPEMASK_UNIT` and applies to whatever it
-///    finds — normally a creature, since vmangos only takes this leg for a unit *not* being moved
-///    by a player (`Unit::SetRooted`/`SetWaterWalking`/`SetFeatherFall`/`SetHover`'s `else` arm,
-///    and `SendToggleRunWalkToAll` unconditionally).
-/// 3. **Two extra modes.** [`WalkMode`](Self::WalkMode) and [`Swimming`](Self::Swimming) have no
-///    ack'd counterpart at all.
-///
-/// [`Swimming`](Self::Swimming) is modelled but vmangos never sends it — nothing in the tree
-/// constructs `SMSG_SPLINE_MOVE_START_SWIM`/`_STOP_SWIM`, and `Opcodes.cpp:888` marks both
-/// `SendByServer`-only. The client handles them (`0x61a130`/`0x61a160`), so we decode them; on this
-/// server they are dead wire.
+/// A mode set on a unit we do not control, by the twelve `SMSG_SPLINE_MOVE_*`: a bare packed guid,
+/// no counter, no ack (client handler `0x603c80`, any unit). vmangos sends the four shared modes
+/// only for units no player moves, and walk/run always. Walk mode and swimming have no acked form.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SplineMode {
     Root,
     WaterWalk,
     FeatherFall,
     Hover,
-    /// `MOVEFLAG_WALK_MODE` (`0x100`) — the gait selector. **`apply` here is the flag's direction,
-    /// not the opcode's noun**: `SMSG_SPLINE_MOVE_SET_WALK_MODE` is `apply: true` and
-    /// `..._SET_RUN_MODE` is `apply: false`, because the reference's `0x617e80` passes the opcode's
-    /// bool to `SetRunMode 0x7c71c0`, whose argument is *run*. The inversion is folded at the parse
-    /// so every variant of this enum means the same thing by "apply".
+    /// `MOVEFLAG_WALK_MODE` (`0x100`); `apply` is the flag's direction, so `SET_WALK_MODE` applies
+    /// and `SET_RUN_MODE` removes (the reference `0x617e80` feeds `SetRunMode`, `0x7c71c0`).
     WalkMode,
-    /// `MOVEFLAG_SWIMMING` (`0x20_0000`) — `SMSG_SPLINE_MOVE_START_SWIM`/`_STOP_SWIM`. Never sent by
-    /// vmangos (see the type docs).
+    /// `MOVEFLAG_SWIMMING` (`0x20_0000`), by `START_SWIM`/`STOP_SWIM`. The reference handles them
+    /// (`0x61a130`, `0x61a160`); vmangos never sends them (`Opcodes.cpp:888`).
     Swimming,
 }
 
 impl SplineMode {
-    /// This mode's `MOVEMENTFLAGS` bit — the same word [`MoveMode::flag`] writes into.
+    /// This mode's `MOVEMENTFLAGS` bit, in the same word as [`MoveMode::flag`].
     pub fn flag(self) -> u32 {
         match self {
             SplineMode::Root => 0x0000_1000,
@@ -233,55 +174,29 @@ impl SplineMode {
     }
 }
 
-/// **What the opcode of a relayed move means**, beyond the pose every one of them carries — the
-/// receiver's switch, modelled once (decision 2064).
-///
-/// The `[packed guid][MovementInfo]` relay family is 23 opcodes on ONE client handler (`0x603bb0` →
-/// `OnUnitMoveEvent 0x601580`), and for most of them the opcode is pure narration: the flags word in
-/// the body already says what changed, and `0x601580`'s parse runs *before* it even loads the opcode
-/// (`0x47eba0` at `0x6015ce`). Three cases are not narration, and this enum is exactly those three —
-/// VERIFIED against the binary in wow-re's `collision/scratch/movement-relay-family-map.md`, which
-/// maps all thirty rows.
-///
-/// Deliberately one field rather than a bag of booleans: they are disjoint (one opcode per packet)
-/// and the set is closed, so an enum forces every receiver to say what it does with each — which is
-/// how the mistake below was possible for as long as it was.
+/// What a relayed move's opcode means beyond its pose. The 23 `[packed guid][MovementInfo]` relays
+/// share one reference handler (`0x603bb0`, `0x601580`), and for most the opcode adds nothing the
+/// flags word does not say. The variants beyond `Pose` name the opcodes a receiver tells apart.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum RelayVerb {
-    /// The ordinary pose stream: start/stop/strafe/jump/turn/pitch/swim/fall-land/set-facing,
-    /// walk-vs-run mode, the observer's hover / feather-fall / water-walk, and the knockback relay.
-    /// The opcode adds nothing the flags word does not already carry.
+    /// Every other relay (start, stop, strafe, jump, turn, swim, land, facing, modes, knockback).
     #[default]
     Pose,
-    /// `MSG_MOVE_HEARTBEAT` — the periodic mid-move pulse.
-    ///
-    /// **It is NOT excluded from the pre-fire reconcile, and believing otherwise was a two-year
-    /// error** (decision 2064, correcting 0601/0603). The queued move-event node's tag `0x26`, which
-    /// `0x619030` (facing interp) and `0x619090` (position reconcile) both skip, is the
-    /// **teleport's**, not the heartbeat's — `push 0x26` appears at exactly two addresses in the
-    /// movement region, `0x6186bd` and `0x618736`, both inside functions reached only from the
-    /// teleport arms (`0x602fb0`, whose other branch sends `push 0xc7` = `MSG_MOVE_TELEPORT_ACK`).
-    /// A deferred heartbeat *is* eligible for both blends. The variant survives the correction
-    /// because the distinction is still worth tracing.
+    /// `MSG_MOVE_HEARTBEAT`, the periodic mid-move pulse. Both reference blends apply to it
+    /// (`0x619030`, `0x619090`); the tag they skip, `0x26`, is only pushed for a teleport.
     Heartbeat,
-    /// `MSG_MOVE_TELEPORT` — the observer's near-teleport (a Blink, a `.tele`). **The one opcode of
-    /// the thirty the client never smooths toward**: tag `0x26`, skipped by both blends. Every relay
-    /// snaps the pose (`0x7c6420` writes the wire pose into the live position *and* the integrator
-    /// base); this one additionally re-bases the mover, zeroes the interp cells `[cmov+0x148]`/
-    /// `[cmov+0x14c]` via `0x617e90`, and past 30.0 yd forces a world re-anchor.
+    /// `MSG_MOVE_TELEPORT`, an observed near-teleport (Blink, `.tele`): the one relay the client
+    /// never smooths toward (tag `0x26`). It also re-bases the mover, zeroes its interpolation
+    /// (`0x617e90`) and past 30 yd re-anchors the world.
     Teleport,
-    /// `MSG_MOVE_ROOT` (`true`) / `MSG_MOVE_UNROOT` (`false`) — the one place in this family where
-    /// **the opcode decides and the flags word does not get a vote**. After the masked merge, the
-    /// client runs `SetRoot 0x7c7340` (`or 0x1000`, then the one-shot motion wipe `& 0xffe07f00`) or
-    /// `ClearRoot 0x7c7370` (`and ~0x1000`) unconditionally. vmangos happens to send a word that
-    /// already agrees — it forces `MOVEFLAG_ROOT` back on for a rooted mover
-    /// (`MovementHandler.cpp:1070`) — so honouring the opcode changes nothing today and makes the
-    /// root independent of the server continuing to be careful.
+    /// `MSG_MOVE_ROOT` (`true`) / `MSG_MOVE_UNROOT` (`false`): the opcode, not the flags word,
+    /// decides. The client then runs `SetRoot` (`0x7c7340`, also wiping motion) or `ClearRoot`
+    /// (`0x7c7370`) unconditionally; vmangos's flags already agree (`MovementHandler.cpp:1070`).
     Root(bool),
 }
 
 impl RelayVerb {
-    /// Which verb a relay opcode carries. Anything not named here is [`Self::Pose`].
+    /// The verb a relay opcode carries.
     pub fn of(opcode: u16) -> Self {
         use super::opcode as op;
         match opcode {
@@ -294,77 +209,43 @@ impl RelayVerb {
     }
 }
 
-/// One jump's ballistic launch parameters — the conditional `MovementInfo` tail present iff the
-/// `MOVEFLAG_JUMPING` (0x2000) flag is set. VERIFIED byte-for-byte against vmangos `MovementInfo::Read`
-/// (build 1.12.1): wire order is `zspeed, cosAngle, sinAngle, xyspeed` (note cos *before* sin). The
-/// horizontal launch velocity is `(cos_angle, sin_angle) · xy_speed` in **world XY** (absolute, frozen
-/// at take-off) and `zspeed` is the constant take-off vertical speed (+Z up); the resulting arc is
-/// `pos += horiz·t`, `z += zspeed·t − ½·g·t²` (the same `g = 19.291105` the controller uses). This is
-/// what lets a receiver replay a jump as one ballistic event between packets rather than snapping its
-/// height at the packet rate (decision 0053). Corroborated by vmangos `Unit.cpp` `ExtrapolateMovement`,
-/// which integrates exactly this arc from the same fields.
+/// The `JUMPING` tail: `zspeed, cosAngle, sinAngle, xyspeed`, cos before sin (vmangos
+/// `MovementInfo::Read`). The launch is `(cos, sin) * xy_speed` in world XY, frozen at take-off,
+/// so a receiver can replay the arc under `g = 19.291105` (vmangos `ExtrapolateMovement`).
 #[derive(Debug, Clone, Copy, Default, PartialEq)]
 pub struct JumpInfo {
-    /// Take-off vertical speed (yd/s), constant for the whole arc, **down-positive**: the real 1.12.1
-    /// client sends `-7.955547` for a *rising* jump (VERIFIED, vanilla-sniffs `dwarf_rogue_dun_morogh`).
-    /// The receiver's up-speed is therefore `-zspeed` (decision 0054).
+    /// Take-off vertical speed (yd/s), down-positive: the 1.12 client sends `-7.955547` for a
+    /// rising jump, so the up-speed is `-zspeed`.
     pub zspeed: f32,
-    /// Cosine of the horizontal launch heading (the X component of the unit launch direction, world XY).
     pub cos_angle: f32,
-    /// Sine of the horizontal launch heading (the Y component, world XY).
     pub sin_angle: f32,
     /// Horizontal launch speed (yd/s); the frozen ground speed at take-off.
     pub xy_speed: f32,
 }
 
-/// A rider's pose **relative to the transport it's on** — the `MOVEFLAG_ON_TRANSPORT` (0x0200_0000)
-/// conditional tail carried by both a `LIVING` update-object movement block (`MovementBlock::transport`,
-/// in `update_object`) and a `MSG_MOVE_*` relay's `MovementInfo` ([`Self::transport`]): `[u64
-/// transport guid][local x, y, z][local o]`. VERIFIED byte-for-byte against vmangos `MovementInfo::Read`
-/// (build 1.12.1) — the guid is a FULL u64 (never packed here), and 1.12 carries **no**
-/// transport-time field after this (added TBC).
-/// `pos`/`orientation` are in the transport's own local frame (decision 0438 "Riding is the mover's
-/// platform frame"): a consumer composes `world = transport_matrix × local` off the named transport's
-/// live pose each frame, never treats these as raw world coordinates.
+/// The `ON_TRANSPORT` tail of `MovementInfo` and of a `LIVING` block: a full `u64` transport guid,
+/// then position and facing in the transport's own frame (vmangos `MovementInfo::Read`).
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct TransportPose {
-    /// The transport GameObject's guid (`HIGH_MO_TRANSPORT` or `HIGH_TRANSPORT` — [`crate::guid`]).
+    /// The transport GameObject's guid, `HIGH_MO_TRANSPORT` or `HIGH_TRANSPORT`.
     pub guid: u64,
     pub pos: Vector3d,
     pub orientation: f32,
 }
 
-/// A wire `MovementInfo` — the body shared by every `MSG_MOVE_*` (both directions) and the teleport
-/// ack. benilla sets the base directional/turn/walk flags, `JUMPING` while airborne, `SWIMMING`
-/// while in the water, and `ON_TRANSPORT` (+ the [`TransportPose`] tail) while riding a boat/zepp
-/// (decision 0438 phase 2). The transport, swim-pitch, and jump tails are conditional
-/// outbound, gated on their flags. Inbound, every conditional tail is parsed (see
-/// [`read_movement_info`]) — the transport pose into [`Self::transport`], the swim pitch into
-/// `Self::pitch`, the jump tail into [`Self::jump`], and the spline-elevation float to stay aligned
-/// only (no consumer needs it).
+/// The body of every `MSG_MOVE_*`, in both directions, and of the teleport ack.
 pub struct MovementInfo {
     pub flags: u32,
     pub timestamp: u32,
     pub position: Vector3d,
     pub orientation: f32,
-    /// The sender's pose on a transport — `Some` iff `flags & MOVEMENT_FLAG_ON_TRANSPORT`, carried
-    /// right after `orientation` and before the swim-pitch tail (VERIFIED order vs vmangos
-    /// `MovementInfo::Read`). This is how another rider's `MSG_MOVE_*` heartbeat tells us they're on a
-    /// boat/elevator and where, in that transport's local frame.
+    /// `Some` iff `ON_TRANSPORT` is set: the sender's pose in the transport's frame.
     pub transport: Option<TransportPose>,
-    /// The **swim pitch** (radians, +up) — the conditional `f32` tail present iff `flags &
-    /// MOVEMENT_FLAG_SWIMMING`, carried after the orientation/transport pose and before `fall_time`
-    /// (VERIFIED order vs vmangos `MovementInfo::Read`). It is the vertical angle of the swim heading, so
-    /// observers can pitch a swimming body up/down the way the local client does. `0.0` (level) when not
-    /// swimming — the serializer only emits it while the `SWIMMING` flag is set, so a zero here on a
-    /// non-swimming packet costs nothing.
+    /// Swim pitch in radians, up-positive; on the wire only while `SWIMMING`, else read as `0.0`.
     pub pitch: f32,
-    /// Milliseconds airborne — a **`u32`** on the wire (VERIFIED vmangos `MovementInfo::fallTime`; it
-    /// was read+written as an f32 while discarded, harmless then but wrong once consumed). The
-    /// receiver's ballistic clock: current vertical speed is `zspeed − g·(fall_time/1000)`.
+    /// Milliseconds airborne, a `u32` (vmangos `MovementInfo::fallTime`): the jump arc's clock.
     pub fall_time: u32,
-    /// The jump tail — `Some` iff `flags & MOVEMENT_FLAG_JUMPING`. The launch params an observer
-    /// replays the arc from.
+    /// `Some` iff `JUMPING` is set: the launch an observer replays the arc from.
     pub jump: Option<JumpInfo>,
 }
 
@@ -376,11 +257,7 @@ impl MovementInfo {
         w.extend_from_slice(&self.position.y.to_le_bytes());
         w.extend_from_slice(&self.position.z.to_le_bytes());
         w.extend_from_slice(&self.orientation.to_le_bytes());
-        // The transport tail rides iff ON_TRANSPORT is set — right after `orientation`, before the
-        // swim pitch, matching vmangos `MovementInfo::Read` exactly: `[u64 guid][local x,y,z][local
-        // o]` (the guid is a FULL u64 — see `read_movement_info`). Flag and tail must travel
-        // together or the server's read desyncs; the caller sets both from one rider state
-        // (decision 0438 "Riding is the mover's platform frame").
+        // Each conditional tail must travel with its flag or vmangos `MovementInfo::Read` desyncs.
         if self.flags & MOVEMENT_FLAG_ON_TRANSPORT != 0 {
             let t = self.transport.unwrap_or(TransportPose {
                 guid: 0,
@@ -397,18 +274,10 @@ impl MovementInfo {
             w.extend_from_slice(&t.pos.z.to_le_bytes());
             w.extend_from_slice(&t.orientation.to_le_bytes());
         }
-        // The swim-pitch tail rides iff SWIMMING is set — after the transport pose and before
-        // `fall_time`, matching `read_movement_info`'s gate and order exactly: setting the flag
-        // without serializing the pitch (or vice-versa) desyncs the server's `MovementInfo::Read`,
-        // the reason this bit was masked off the wire until now.
         if self.flags & MOVEMENT_FLAG_SWIMMING != 0 {
             w.extend_from_slice(&self.pitch.to_le_bytes());
         }
-        // fall_time follows the transport + swim-pitch tails.
         w.extend_from_slice(&self.fall_time.to_le_bytes());
-        // The jump tail rides iff JUMPING is set — matching the parser's gate exactly: setting the flag
-        // without serializing the tail (or vice-versa) desyncs the server's `MovementInfo::Read`. Order
-        // matches vmangos: zspeed, cosAngle, sinAngle, xyspeed.
         if self.flags & MOVEMENT_FLAG_JUMPING != 0 {
             let j = self.jump.unwrap_or_default();
             w.extend_from_slice(&j.zspeed.to_le_bytes());
@@ -441,9 +310,6 @@ mod tests {
         }
     }
 
-    /// The swim-pitch tail round-trips byte-exactly through `write` → `read_movement_info` when
-    /// SWIMMING is set: the reason the flag was masked off the wire (an unwritten tail desyncing the
-    /// server's `MovementInfo::Read`) is closed only if write and read agree on gate + order.
     #[test]
     fn swim_pitch_round_trips_when_swimming() {
         let mut bytes = Vec::new();
@@ -458,10 +324,6 @@ mod tests {
         );
     }
 
-    /// The transport tail round-trips byte-exactly through `write` → `read_movement_info` when
-    /// ON_TRANSPORT is set: `[u64 guid][x,y,z][o]` right after `orientation` (vmangos
-    /// `MovementInfo::Read`/`Write` order), 24 bytes exactly — a packed guid or the TBC 0x200
-    /// flag value would both shift `fall_time` and desync the server.
     #[test]
     fn transport_tail_round_trips_when_riding() {
         let mut riding = info(MOVEMENT_FLAG_ON_TRANSPORT);
@@ -491,8 +353,6 @@ mod tests {
         assert_eq!(back.fall_time, 42, "fall_time lands after the tail");
     }
 
-    /// Non-swimming packets carry NO pitch tail — the four pitch bytes are absent, so the wire stays
-    /// byte-identical to before this tail existed (and `fall_time` reads from the right offset).
     #[test]
     fn no_pitch_tail_when_not_swimming() {
         let mut swimming = Vec::new();
diff --git a/crates/benilla-protocol/src/messages/opcode.rs b/crates/benilla-protocol/src/messages/opcode.rs
index a82486b9..66d315a6 100644
--- a/crates/benilla-protocol/src/messages/opcode.rs
+++ b/crates/benilla-protocol/src/messages/opcode.rs
@@ -1,146 +1,107 @@
-//! World opcode numbers (verified against `wow_world_messages` 0.3 / wowdev + vmangos
-//! `Opcodes_1_12_1.h`). All are 16-bit values — the client packet header's opcode field is 4 bytes
-//! wide but every value fits `u16`, so we keep one natural type and the senders widen to the wire field.
+//! The 1.12.1 world opcode numbers (vmangos `Opcodes_1_12_1.h`). A client packet's header holds
+//! the opcode in 4 bytes, but every value fits `u16`; the senders widen it.
 
-// Server → client.
 pub const SMSG_CHAR_CREATE: u16 = 0x003A;
 pub const SMSG_CHAR_ENUM: u16 = 0x003B;
-// The delete pair (VERIFIED vmangos `Opcodes_1_12_1.h`: 56/60): CMSG body a full u64 guid,
-// SMSG body the result byte (`CHAR_DELETE_SUCCESS` = 0x39, `SharedDefines.h` ResponseCodes).
+// Character delete: CMSG a full u64 guid, SMSG one result byte (`CHAR_DELETE_SUCCESS` = 0x39).
 pub const CMSG_CHAR_DELETE: u16 = 0x0038;
 pub const SMSG_CHAR_DELETE: u16 = 0x003C;
-/// `SMSG_CHARACTER_LOGIN_FAILED` (VERIFIED vmangos `Opcodes_1_12_1.h`: 65) — the server's refusal
-/// of a `CMSG_PLAYER_LOGIN`. Body: one result byte.
+/// The server's refusal of a `CMSG_PLAYER_LOGIN`: one result byte.
 pub const SMSG_CHARACTER_LOGIN_FAILED: u16 = 0x0041;
 pub const SMSG_NAME_QUERY_RESPONSE: u16 = 0x0051; // 81
 pub const SMSG_CREATURE_QUERY_RESPONSE: u16 = 0x0061; // 97
-/// VERIFIED vmangos `Opcodes_1_12_1.h:86`: 83. Answers `CMSG_PET_NAME_QUERY` — the only query that
-/// can name a pet, whose guid carries no template entry ([`crate::guid::pet_number`]). Body: `u32
-/// petNumber`, cstring name, `u32 nameTimestamp` (`Server/Packets/Pet.cpp:79-84`). The server simply
-/// does not reply when the guid is not a live pet bearing that number (`PetHandler.cpp:190-192`), so
-/// there is no "unknown" answer shape to model.
+/// Answers `CMSG_PET_NAME_QUERY`: `u32 petNumber`, cstring name, `u32 nameTimestamp`. No reply
+/// comes unless the guid is a live pet with that number (`PetHandler.cpp:190-192`).
 pub const SMSG_PET_NAME_QUERY_RESPONSE: u16 = 0x0053; // 83
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 95 (decision 0236). Answers `CMSG_GAMEOBJECT_QUERY`; body
-/// (`GameObjectQueryInfo`) in [`super::gameobject`].
+/// Answers `CMSG_GAMEOBJECT_QUERY` with the GameObject's template.
 pub const SMSG_GAMEOBJECT_QUERY_RESPONSE: u16 = 0x005F; // 95
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 93. Answers `CMSG_QUEST_QUERY`; body in
-/// [`super::quest::read_quest_query_response`] ([`super::QuestTemplate`]).
+/// Answers `CMSG_QUEST_QUERY` with the quest's template.
 pub const SMSG_QUEST_QUERY_RESPONSE: u16 = 0x005D; // 93
 
-// The **page-text** query pair (VERIFIED vmangos `Opcodes_1_12_1.h`: 90/91) — the ask-once cache
-// behind every readable BOOK, and a different one from the mail letter's `CMSG_ITEM_TEXT_QUERY`
-// further down: a `PageText.wdb` id names one *page*, chained by `nextPageId`, and it is what a
-// readable item TEMPLATE (`PageText`) and a world book/plaque GameObject (`GAMEOBJECT_TYPE_TEXT`'s
-// `data[0]`) both read from. Bodies in [`super::page_text`]; decision 1105.
+// Page text: the ask-once `PageText.wdb` cache behind readable items and book GameObjects; an id
+// names one page, chained by `nextPageId`. Mail letters use `CMSG_ITEM_TEXT_QUERY` instead.
 pub const CMSG_PAGE_TEXT_QUERY: u16 = 0x005A; // 90
 pub const SMSG_PAGE_TEXT_QUERY_RESPONSE: u16 = 0x005B; // 91
 
 pub const SMSG_NEW_WORLD: u16 = 0x003E;
-// The far-teleport preamble pair (VERIFIED vmangos `Opcodes_1_12_1.h`: 63/64). TRANSFER_PENDING's
-// optional transport block decides how NEW_WORLD's coordinates read — boat-local when present,
-// world otherwise (decision 0455; vmangos `Player.cpp:2065-2068` / `SendNewWorld`).
+// The far-teleport preamble: with `SMSG_TRANSFER_PENDING`'s optional transport block, the next
+// `SMSG_NEW_WORLD`'s coordinates are transport-local, else world (`Player.cpp:2065-2068`).
 pub const SMSG_TRANSFER_PENDING: u16 = 0x003F;
 pub const SMSG_TRANSFER_ABORTED: u16 = 0x0040;
 pub const SMSG_LOGIN_SETTIMESPEED: u16 = 0x0042;
 pub const SMSG_BINDPOINTUPDATE: u16 = 0x0155;
-/// 295 — the per-item-class proficiency mask (VERIFIED vmangos `Opcodes_1_12_1.h` + Skill.h).
+/// The proficiency mask for one item class (vmangos `Skill.h`).
 pub const SMSG_SET_PROFICIENCY: u16 = 0x0127;
 pub const SMSG_LOGOUT_RESPONSE: u16 = 0x004C;
 pub const SMSG_LOGOUT_COMPLETE: u16 = 0x004D;
-/// 79 — the ack for [`CMSG_LOGOUT_CANCEL`] (VERIFIED vmangos `Opcodes_1_12_1.h`), empty body.
+/// The ack for [`CMSG_LOGOUT_CANCEL`]; empty body.
 pub const SMSG_LOGOUT_CANCEL_ACK: u16 = 0x004F;
 pub const SMSG_UPDATE_OBJECT: u16 = 0x00A9;
 pub const SMSG_DESTROY_OBJECT: u16 = 0x00AA;
-// The cinematic pair (VERIFIED vmangos `Opcodes_1_12_1.h`: 250/252). The server sends the trigger
-// on a character's first-ever login (the race intro) and for GameObject type-13 cameras; while one
-// runs UNACKED, vmangos re-anchors object visibility to the flying cinematic camera
-// (`Player::UpdateCinematic`), despawning everything around the body — so the client must answer.
+// Cinematics: a first login's race intro, or a type-13 GameObject camera. Until the COMPLETE ack,
+// vmangos sees from the camera and despawns all around the body (`Player::UpdateCinematic`).
 pub const SMSG_TRIGGER_CINEMATIC: u16 = 0x00FA;
-/// Sent when playback advances from one camera of a multi-camera `CinematicSequences` row to the
-/// next — empty body, exactly like the completion ack. VERIFIED in the reference at `0x48efe0`
-/// (`NextCamera`): it bumps the camera index, and the send is `push 0xfb; call 0x418190` with
-/// nothing written between the CDataStore open and `call 0x5ab630`.
+/// The next camera of a multi-camera `CinematicSequences` row began; empty body (`0x48efe0`).
 pub const CMSG_NEXT_CINEMATIC_CAMERA: u16 = 0x00FB;
 pub const CMSG_COMPLETE_CINEMATIC: u16 = 0x00FC;
 pub const SMSG_MONSTER_MOVE: u16 = 0x00DD;
-/// `SMSG_MONSTER_MOVE_TRANSPORT` (VERIFIED vmangos `Opcodes_1_12_1.h`: 686) — the transport twin of
-/// [`SMSG_MONSTER_MOVE`]: the identical body with the **transport's packed guid inserted after the
-/// mover's**, and every coordinate in it a deck-local offset instead of a world position. Sent for a
-/// unit pathing *on* a transport — a pet following its owner aboard a boat, anything a player pulls
-/// onto a deck (`Movement::MoveSplineInit::Launch`, `spline/MoveSplineInit.cpp:146-154`). Body in
-/// [`super::monster_move::read_monster_move`]; decision 1936.
+/// [`SMSG_MONSTER_MOVE`] for a unit on a transport: the transport's packed guid follows the
+/// mover's, and every coordinate is deck-local (`MoveSplineInit.cpp:146-154`).
 pub const SMSG_MONSTER_MOVE_TRANSPORT: u16 = 0x02AE; // 686
 pub const SMSG_INITIALIZE_FACTIONS: u16 = 0x0122;
-/// A faction became visible in the reputation pane (VERIFIED vmangos `Opcodes_1_12_1.h`: 291,
-/// sender `ReputationMgr::SendVisible`) — body one `u32` reputation-list slot. The server sets the
-/// slot's `FACTION_FLAG_VISIBLE` on first contact and pushes *only* this, never a fresh standing:
-/// a client that ignores it keeps a correct standing on a row the pane refuses to list.
+/// A faction became visible in the reputation pane: one `u32` list slot. It is the only notice of
+/// `FACTION_FLAG_VISIBLE`; no fresh standing comes with it (`ReputationMgr::SendVisible`).
 pub const SMSG_SET_FACTION_VISIBLE: u16 = 0x0123;
 pub const SMSG_SET_FACTION_STANDING: u16 = 0x0124;
-/// The reputation pane's three send verbs (VERIFIED vmangos `Opcodes.cpp`'s `DEFINE_HANDLER`
-/// registrations: 293, 791, 792). Bodies in [`super::reputation`]; none is acked.
+/// Set a faction's at-war flag from the reputation pane; none of the pane's three verbs is acked.
 pub const CMSG_SET_FACTION_ATWAR: u16 = 0x0125; // 293
 pub const CMSG_SET_FACTION_INACTIVE: u16 = 0x0317; // 791
 pub const CMSG_SET_WATCHED_FACTION: u16 = 0x0318; // 792
 pub const SMSG_AUTH_CHALLENGE: u16 = 0x01EC;
 pub const SMSG_AUTH_RESPONSE: u16 = 0x01EE;
-/// The Warden anticheat challenge. A server that sends this starts a response-timeout clock
-/// (vmangos `Warden::BeginTimeoutClock`, `Warden.ClientResponseDelay` — default 30 s) and kicks
-/// unconditionally when it expires (`Warden::Update`), so a client that can't answer cannot stay
-/// in the world. benilla does not implement Warden; [`crate::WorldSession::connect`] refuses such
-/// a server at the handshake rather than entering a 30-second kick/reconnect cycle.
+/// The Warden anticheat challenge; vmangos kicks a client that leaves it unanswered for 30 s
+/// (`Warden::Update`). Deviation: no Warden ([`crate::WardenRequired`]), so the connect refuses.
 pub const SMSG_WARDEN_DATA: u16 = 0x02E6;
-/// The server's answer to `CMSG_AUTH_SESSION`'s addon block — one record per `## Secure:` addon we
-/// sent, in the order we sent them, with no count and no names (decision 2175).
+/// One record per `## Secure:` addon in `CMSG_AUTH_SESSION`, in order, with no count or names.
 pub const SMSG_ADDON_INFO: u16 = 0x02EF;
 pub const SMSG_COMPRESSED_UPDATE_OBJECT: u16 = 0x01F6;
-/// A zlib envelope holding a **batch of whole movement packets** (763, VERIFIED vmangos
-/// `Opcodes_1_12_1.h`). Not an edge case: vmangos moves a session onto this carrier the moment it
-/// has pushed 300 movement packets to it inside ten seconds (`Compression.Movement.Count`), which
-/// one nearby player moving at frame cadence reaches in about five. See
-/// [`super::ServerPacket::CompressedMoves`].
+/// A zlib envelope of whole movement packets. Routine: vmangos switches a session to it after 300
+/// movement packets in ten seconds (`Compression.Movement.Count`).
 pub const SMSG_COMPRESSED_MOVES: u16 = 0x02FB;
 pub const SMSG_LOGIN_VERIFY_WORLD: u16 = 0x0236;
-/// The account's tutorial bank (wow-re `tutorial-flags.md` §7, decision 1976): every remaining
-/// byte of the body is the bank, both of the client's banks copied from it — vmangos sends 32
-/// bytes (256 bits) after the login. Until it lands no tutorial can fire.
+/// The account's tutorial bits: the whole body (32 bytes from vmangos after login), copied into
+/// both of the client's banks. No tutorial fires before it arrives.
 pub const SMSG_TUTORIAL_FLAGS: u16 = 0x00FD; // 253
-/// `FlagTutorial(n)` and the six auto-acknowledge sites (§5/§6, 1976): one `u32`, the 0-based id.
+/// `FlagTutorial(n)` and the client's six auto-acknowledge sites: one `u32`, the 0-based id.
 pub const CMSG_TUTORIAL_FLAG: u16 = 0x00FE; // 254
-/// `ClearTutorials()` (§6, 1976): EMPTY — every bit set locally and on the server.
+/// `ClearTutorials()`: empty body; every bit is set locally and on the server.
 pub const CMSG_TUTORIAL_CLEAR: u16 = 0x00FF; // 255
-/// `ResetTutorials()` (§6, 1976): EMPTY — every bit cleared locally and on the server.
+/// `ResetTutorials()`: empty body; every bit is cleared locally and on the server.
 pub const CMSG_TUTORIAL_RESET: u16 = 0x0100; // 256
-                                             // The server-pushed sound trio (1.12.1 values VERIFIED vmangos `Opcodes_1_12_1.h`:
-                                             // 631/632/722).
 pub const SMSG_PLAY_MUSIC: u16 = 0x0277;
 pub const SMSG_PLAY_OBJECT_SOUND: u16 = 0x0278;
 pub const SMSG_PLAY_SOUND: u16 = 0x02D2;
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 756.
+/// The zone's weather, pushed by the server.
 pub const SMSG_WEATHER: u16 = 0x02F4;
-// The emote pair + our send side (VERIFIED vmangos `Opcodes_1_12_1.h`: 259/260/261).
 pub const SMSG_EMOTE: u16 = 0x0103;
 pub const CMSG_TEXT_EMOTE: u16 = 0x0104;
 pub const SMSG_TEXT_EMOTE: u16 = 0x0105;
-// The spell-book/action-bar/cast/attack set (VERIFIED vmangos `Opcodes_1_12_1.h`:
-// 297/298/304/323/324 in, 302/321/322 out). Bodies in [`super::spells`].
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 88. Body in [`items`].
+/// Answers `CMSG_ITEM_QUERY_SINGLE` with the item's template.
 pub const SMSG_ITEM_QUERY_SINGLE_RESPONSE: u16 = 0x0058;
-// The item-move CMSG family (VERIFIED vmangos `Opcodes_1_12_1.h:269-273`; bodies in [`items`]).
 pub const CMSG_AUTOEQUIP_ITEM: u16 = 0x010A; // 266
 pub const CMSG_AUTOSTORE_BAG_ITEM: u16 = 0x010B; // 267
 pub const CMSG_SWAP_ITEM: u16 = 0x010C; // 268
 pub const CMSG_SWAP_INV_ITEM: u16 = 0x010D; // 269
 pub const CMSG_SPLIT_ITEM: u16 = 0x010E; // 270
-pub const CMSG_DESTROYITEM: u16 = 0x0111; // 273 — the popup-confirmed world-drop delete (0216 §3)
+pub const CMSG_DESTROYITEM: u16 = 0x0111; // 273, the popup-confirmed world-drop delete
 pub const SMSG_INVENTORY_CHANGE_FAILURE: u16 = 0x0112; // 274
+/// A bag was auto-equipped: one raw `u64` guid (`ItemHandler.cpp:227`). The reference raises
+/// `BAG_OPEN` for it (`0x4f9410`): our own guid is container 0, a cached bag 1..10, else nothing.
+pub const SMSG_OPEN_CONTAINER: u16 = 0x0113; // 275
 
-// The player-to-player trade family (VERIFIED vmangos `Opcodes_1_12_1.h:278-289`,
-// `Handlers/TradeHandler.cpp`, `Server/Packets/Trade.{h,cpp}`; bodies/parses in [`trade`],
-// decision 0592 P0). CMSG bodies: INITIATE = u64 target; ACCEPT = u32 (read-skipped);
-// SET_ITEM = 3×u8 (tradeSlot, bag, slot); CLEAR_ITEM = u8 tradeSlot; SET_GOLD = u32 copper;
-// BEGIN/BUSY/IGNORE/UNACCEPT/CANCEL are empty. SMSG: TRADE_STATUS = u32 status (+ a per-status
-// tail); TRADE_STATUS_EXTENDED = the 444-byte item/gold snapshot.
+// Trade. CMSG bodies: INITIATE u64 target, ACCEPT u32 (ignored), SET_ITEM 3×u8 (tradeSlot, bag,
+// slot), CLEAR_ITEM u8, SET_GOLD u32 copper, the rest empty. SMSG: TRADE_STATUS u32 plus a
+// per-status tail; TRADE_STATUS_EXTENDED the 444-byte item/gold snapshot.
 pub const CMSG_INITIATE_TRADE: u16 = 0x0116; // 278
 pub const CMSG_BEGIN_TRADE: u16 = 0x0117; // 279
 pub const CMSG_BUSY_TRADE: u16 = 0x0118; // 280
@@ -153,301 +114,141 @@ pub const CMSG_CLEAR_TRADE_ITEM: u16 = 0x011E; // 286
 pub const CMSG_SET_TRADE_GOLD: u16 = 0x011F; // 287
 pub const SMSG_TRADE_STATUS: u16 = 0x0120; // 288
 pub const SMSG_TRADE_STATUS_EXTENDED: u16 = 0x0121; // 289
-/// Load ammo into the ammo "slot" (`PLAYER_AMMO_ID`) — VERIFIED wow-re `cursor-dragdrop-slots.md`
-/// (the client's auto-equip sender `0x5e1480` forks ammo-class here) + vmangos `Opcodes_1_12_1.h`:
-/// 616. Body in [`items::set_ammo`]. Note the hex/decimal trap: `0x0268` (this) ≠ `0x010C`
-/// (`CMSG_SWAP_ITEM`, "opcode 268" in decimal). Decision 0526.
+/// Load ammo (`PLAYER_AMMO_ID`); the auto-equip sender `0x5e1480` sends ammo here. Trap: `0x0268`
+/// is not decimal 268, which is `CMSG_SWAP_ITEM` (`0x010C`).
 pub const CMSG_SET_AMMO: u16 = 0x0268; // 616
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 296 — `MiscHandler.cpp:885`'s `HandleSetActionButtonOpcode`
-/// (decision 0216 §7/0218 §4). Body in [`super::action_bar::set_action_button`].
+/// Set one action-bar button (`HandleSetActionButtonOpcode`, `MiscHandler.cpp:885`).
 pub const CMSG_SET_ACTION_BUTTON: u16 = 0x0128; // 296
-/// The four extra action bars' visibility byte (`PLAYER_FIELD_BYTES` byte 2) — VERIFIED at the
-/// bytes, wow-re `system/ui/scratch/action-bar-toggles.md` §3: `0x4e771d push 0x2bf` is the ONE
-/// site image-wide that emits this opcode, and the frame it builds is `u32 opcode` + a single `u8`
-/// and nothing else (`0x418190` PutUInt32 then `0x418070` PutUInt8; `0x5379b3` computes the
-/// payload as size − read = **5**). Body in [`super::action_bar::set_actionbar_toggles`].
-///
-/// Corroborated by vmangos `Opcodes_1_12_1.h`: 703 → `HandleSetActionBarTogglesOpcode`
-/// (`Packets/Misc.cpp:150-153` reads one `uint8`; `Handlers/MiscHandler.cpp:923-932` stores it with
-/// `SetByteValue(PLAYER_FIELD_BYTES, 2, …)`).
+/// The four extra action bars' visibility: one `u8`, stored as `PLAYER_FIELD_BYTES` byte 2
+/// (sent only from `0x4e771d`; `MiscHandler.cpp:923-932`).
 pub const CMSG_SET_ACTIONBAR_TOGGLES: u16 = 0x02BF; // 703
 pub const SMSG_ACTION_BUTTONS: u16 = 0x0129; // 297
 pub const SMSG_INITIAL_SPELLS: u16 = 0x012A; // 298
 
-// The incremental spell-learn pair (VERIFIED vmangos `Opcodes_1_12_1.h`: 299/300) — a spell added to
-// the book after login (trainer purchase / quest reward / level-up), and the rank-up in-place swap.
-// Bodies in [`super::spells`] (decision 0237).
+// Spell-book changes after login: a spell learned, and a rank swapped in place.
 pub const SMSG_LEARNED_SPELL: u16 = 0x012B; // 299
 pub const SMSG_SUPERCEDED_SPELL: u16 = 0x012C; // 300
 
-/// The **third** member of that family and the only one that shrinks the book (VERIFIED vmangos
-/// `Opcodes_1_12_1.h`: 515; `Player::SendSpellRemoved`, the tail of `Player::RemoveSpell`). Sent
-/// once per spell the server takes away — a talent wipe sends one for every rank of every talent,
-/// which is the whole reason decision 1584 exists. Body in [`super::spellbook`]: one `u16`.
+/// A spell left the book (`Player::RemoveSpell`): one `u16` id; a talent wipe sends one per rank.
 pub const SMSG_REMOVED_SPELL: u16 = 0x0203; // 515
 pub const SMSG_CAST_RESULT: u16 = 0x0130; // 304
 
-// The pet action bar's inbound wire (decision 0982; VERIFIED vmangos `Opcodes_1_12_1.h`:
-// 377/378/710/312). Bodies in [`super::pet`].
-/// The control handoff (VERIFIED vmangos `Opcodes_1_12_1.h`: 345; built at
-/// `Server/Packets/Misc.cpp:677-682`). Body: **packed** mover guid, then a `u8` `allowMove`.
-///
-/// It is the whole of possession's control half, and it is a *statement about one unit*, not a
-/// swap: the server always sends it to our own session, naming some unit and whether we may drive
-/// it. Mind Control's start sends the caster `(victim, 1)` and the victim `(victim, 0)`; the end
-/// sends the caster `(self, 1)` **then** `(victim, 0)`, and the victim `(victim, 1)`.
-///
-/// **Two consequences the server leans on us for.** It expects a
-/// [`CMSG_SET_ACTIVE_MOVER`] reply and drops every `MSG_MOVE_*` for the new mover until it
-/// arrives (`Player::GetConfirmedMover`). And it never immobilises a possessed *player* — no root,
-/// no speed change, and its `StopMoving()` is a documented no-op for one — nor does it validate
-/// their movement, so `allowMove = 0` for our own guid is the **only** thing standing between a
-/// mind-controlled player and walking away. Enforcing that is the client's job.
+/// Whether we may drive one unit: packed guid, `u8 allowMove` (`Misc.cpp:677-682`). Each packet
+/// is about one unit, not a swap: ending Mind Control sends the caster `(self, 1)` then
+/// `(victim, 0)`. The server drops `MSG_MOVE_*` for a new mover until [`CMSG_SET_ACTIVE_MOVER`]
+/// answers, and never stops a possessed player: `allowMove = 0` on our guid is ours to enforce.
 pub const SMSG_CLIENT_CONTROL_UPDATE: u16 = 0x0159; // 345
-/// The whole pet bar in one body — the ten slots, the react/command state, the pet's spell list
-/// and its cooldowns. Its **8-byte guid-only form is the teardown** (`Player::RemovePetActionBar`),
-/// and the only signal that the bar has gone away.
+/// The whole pet bar: ten slots, react/command state, spell list, cooldowns. The 8-byte
+/// guid-only form is the teardown, the only sign the bar is gone (`Player::RemovePetActionBar`).
 pub const SMSG_PET_SPELLS: u16 = 0x0179; // 377
 /// The state-only refresh: the same four state bytes, with no bar behind them.
 pub const SMSG_PET_MODE: u16 = 0x017A; // 378
 /// One reason byte for a refused pet order (the red error line).
 pub const SMSG_PET_ACTION_FEEDBACK: u16 = 0x02C6; // 710
-/// The pet's twin of [`SMSG_CAST_RESULT`] — the same `SpellCastResult` vocabulary, its own opcode
-/// because the caster that failed is the pet, not us.
+/// [`SMSG_CAST_RESULT`] for a failed pet cast, with the same `SpellCastResult` codes.
 pub const SMSG_PET_CAST_FAILED: u16 = 0x0138; // 312
 
-// The three remaining pet-feedback arms, carved together (decision 2039). Each was name-table-only
-// until then, and each has a handler in the reference that does something visible.
-/// **The taming refusal** — one `u8` reason from `PetTameFailureReason`. Not only taming: vmangos
-/// sends it for Call Pet and Revive Pet too (`SpellEffects.cpp:3167/3174`, `Spell.cpp:5463/6113`).
-///
-/// The reference's handler `0x6e97e0` reads the byte and hands it to `0x6e6a20`, which turns
-/// `reason - 1` into one of eleven `PETTAME_*` GlobalStrings keys through the jump table at
-/// `0x6e6ac0`, resolves it (`0x703bf0`) and raises `DisplayError(0xee)` =
-/// `ERR_TAME_FAILED` (`"%s."`) with that string as the fill. Anything outside `1..=11` — `0` and
-/// `12` included — takes the default arm's `PETTAME_UNKNOWNERROR`. The map is in
-/// [`super::pet::pet_tame_failure_key`].
+/// Tame, Call Pet or Revive Pet refused: one `u8` reason. The reference (`0x6e97e0`) shows
+/// `ERR_TAME_FAILED` with the reason's `PETTAME_*` string, `PETTAME_UNKNOWNERROR` outside 1..=11.
 pub const SMSG_PET_TAME_FAILURE: u16 = 0x0173; // 371
-/// **The refused rename** — an EMPTY body, and a visible error all the same.
-///
-/// vmangos's `SendPetNameInvalid` drops both the reason code and the name with the comment "not
-/// read by vanilla client" (`PetHandler.cpp:542-548`), and the reference agrees: its arm reads no
-/// body. What it does read is the *opcode* — 0x178 lands in the shared dispatcher `0x5e38c0`,
-/// whose index byte at `0x5e4c6c[0]` selects target `0x5e4c40[0]` = `0x5e3e33`, five instructions:
-/// `push 0xf7; call 0x496720` = `DisplayError(247)` = **`ERR_INVALID_PETNAME`**, "Error, invalid
-/// name entered.".
-///
-/// **Decision 1066 said the opposite** — that a refused rename "silently does nothing, which is
-/// what the reference does too" — on a carve that had attributed [`SMSG_PET_BROKEN`]'s handler
-/// `0x4bdc00` to this opcode. `re/net/opcode-handlers.tsv` maps 0x178 to `0x5e38c0` and 0x2AF to
-/// `0x4bdc00`; they are different functions raising different messages.
+/// A refused pet rename: empty body (`PetHandler.cpp:542-548`), yet the reference shows
+/// `ERR_INVALID_PETNAME` for it (`0x5e3e33`).
 pub const SMSG_PET_NAME_INVALID: u16 = 0x0178; // 376
-/// **The pet ran away** — an empty body; vmangos sends it when a hunter pet's loyalty hits zero
-/// (`Pet.cpp:822`, immediately before `Unsummon(PET_SAVE_AS_DELETED)`).
-///
-/// Handler `0x4bdc00`: `push 0x1a3; call 0x496720` = `DisplayError(419)` = `ERR_PET_BROKEN`,
-/// "Your pet has run away". It reads no body, writes no state and fires no event — the bar's
-/// teardown rides the `SMSG_PET_SPELLS` zero-guid form as usual (wow-re
-/// `ui/scratch/pet-action-bar-api.md` §11c.5).
+/// The pet ran away at zero loyalty (`Pet.cpp:822`): empty body. The reference (`0x4bdc00`) only
+/// shows `ERR_PET_BROKEN`; the bar's teardown still comes as an `SMSG_PET_SPELLS`.
 pub const SMSG_PET_BROKEN: u16 = 0x02AF; // 687
-/// **The pet's voice** — `u64 petGuid` then a `u32` *talk* selector (not a `SoundEntries` id):
-/// `0` = `PET_TALK_SPECIAL_SPELL`, `1` = `PET_TALK_ATTACK` (vmangos `Pet.h:98`,
-/// `Unit::SendPetTalk`).
-///
-/// Handler `0x6040c0` resolves the guid, then calls the creature bark dispatcher
-/// `0x623a40(unit, state)` with **state 1 for selector 0 and state 2 for selector 1** — i.e.
-/// `CreatureSoundData` columns 28 (`PetOrder`) and 27 (`PetAttack`). Any other selector plays
-/// nothing. The bark rides the unit's ordinary one-shot voice slot and its priority latch, so it
-/// is not a free-standing sound (see `crate::sound::creature`'s bark core on the benilla side).
+/// The pet's voice: `u64 petGuid`, `u32` talk selector (`Pet.h:98`). The reference (`0x6040c0`)
+/// barks `CreatureSoundData` column 28 (`PetOrder`) for 0, 27 (`PetAttack`) for 1, else nothing,
+/// through the unit's one-shot voice slot.
 pub const SMSG_PET_ACTION_SOUND: u16 = 0x0324; // 804
-/// **The dismissed pet's parting sound** — `u32 creatureModelDataId` then a `f32` x/y/z, and the
-/// odd one of the family in every way.
-///
-/// Handler `0x604140` reads those four fields, walks **`CreatureModelData[id]` → its own
-/// `SoundID` (col 13, `[row+0x34]`) → `CreatureSoundData` → column 29**, and plays that kit at the
-/// given point with `z + 1.0` (`0x7ff9d8`) and a free-picked variation. No unit is involved: it is
-/// off the bark dispatcher's table entirely, takes no voice latch and has no attach point —
-/// because by the time it sounds the pet has gone. That fresh, inlined, by-id resolve is also why
-/// a census over the *cached* `[unit+0xb40]` row's consumers concluded column 29 was dead.
-///
-/// **vmangos never sends it** (no `SendPetDismissSound` anywhere in the tree; the opcode is
-/// registered only as server-bound). Built because the reference is the spec and this handler is
-/// what makes column 29 load-bearing — not because anything we talk to can trigger it.
+/// A dismissed pet's parting sound: `u32 creatureModelDataId`, `f32` x, y, z. The reference
+/// (`0x604140`) plays that model's `CreatureSoundData` column 29 there at `z + 1.0`, with no unit.
+/// vmangos never sends it.
 pub const SMSG_PET_DISMISS_SOUND: u16 = 0x0325; // 805
 
-/// The client's ack that a server-authored spline (`SMSG_MONSTER_MOVE` to our own guid — Charge,
-/// knockback, taxi) finished. Body: a `MovementInfo` at the endpoint, the `splineId` being acked,
-/// and a trailing float the server `read_skip`s (VERIFIED vmangos `Opcodes_1_12_1.h`: 713;
-/// `MoveSplineDone::ReadFromWorldPacket`).
+/// Our own server-driven spline (Charge, taxi) finished: `MovementInfo` at the endpoint, the
+/// `splineId`, and a float the server skips (`MoveSplineDone::ReadFromWorldPacket`).
 pub const CMSG_MOVE_SPLINE_DONE: u16 = 0x02C9; // 713
-/// The client's report that its movement clock **skipped** — a stall, a long frame, a window that
-/// went to the background — carrying the mover and how many milliseconds went missing (VERIFIED
-/// vmangos `Opcodes_1_12_1.h`: 718). Body in [`super::client::move_time_skipped`].
-///
-/// vmangos adds the reported `lag` to the mover's `stime`/`ctime` so its own movement clock stays
-/// aligned with ours — **and hangs a 1.12-specific transport fix off it**: a player whose last
-/// movement packet was the *first* one carrying `MOVEFLAG_ONTRANSPORT` is flagged `JustBoarded`,
-/// and the next `CMSG_MOVE_TIME_SKIPPED` makes the server re-send that transport's out-of-range
-/// update followed by a fresh create (`HandleMoveTimeSkippedOpcode`,
-/// `Handlers/MovementHandler.cpp:989-1019`, comment *"fix an 1.12 client problem with
-/// transports"*). A client that never sends this never gets that refresh. Decision 1935.
+/// Our movement clock skipped (a stall, a long frame): the mover and the missing milliseconds.
+/// vmangos shifts its clock, and re-creates a just-boarded transport (`MovementHandler.cpp:989`).
 pub const CMSG_MOVE_TIME_SKIPPED: u16 = 0x02CE; // 718
-/// The **broadcast twin** of [`CMSG_MOVE_TIME_SKIPPED`] (VERIFIED vmangos `Opcodes_1_12_1.h`: 793):
-/// the server relays one mover's skip to everyone watching it, so their copies of that unit's
-/// movement clock move with it (`MovementHandler.cpp:1011-1017`, packed guid + the same `u32`).
-///
-/// **Not ignorable.** The reference registers a handler for it (`0x6035e0` → `0x603b40`) that reads
-/// a packed guid, resolves under `TYPEMASK_UNIT`, and adds the lag to `[CMovement+0xac]` — the
-/// observed unit's last-seen **wire** movement timestamp, the monotonic maximum the relay chain
-/// hangs off (`0x601560` → `0x61ab90`). That cell is benilla-app's relay-chain `last_wire_ms`
-/// (`net::motion::relay::RelayChain`, decision 0615, which models `+0xa8`/`+0xac` by name). Drop the packet and the chain's copy stays `lag` ms short of the sender's
-/// forever: the mover's next real packet then reads as a step `lag` too large and is scheduled
-/// that much late — a hitch on that unit, not a lost packet. Decision 1935.
+/// Another mover's clock skip, relayed: packed guid, `u32` lag (`MovementHandler.cpp:1011-1017`).
+/// The reference (`0x603b40`) adds it to that unit's last wire timestamp (`CMovement+0xac`); if
+/// dropped, the unit's next packet lands `lag` ms late.
 pub const MSG_MOVE_TIME_SKIPPED: u16 = 0x0319; // 793
 pub const SMSG_ATTACKSTART: u16 = 0x0143; // 323
 pub const SMSG_ATTACKSTOP: u16 = 0x0144; // 324
 pub const SMSG_ATTACKERSTATEUPDATE: u16 = 0x014A; // 330
 
-// The four melee swing REFUSALS — the server's answers to a `CMSG_ATTACKSWING` it will not honour.
-// All four bodies are EMPTY (vmangos `Server/Packets/Combat.cpp`, every `AppendBodyTo` a no-op),
-// and the reference's arms read nothing from the datastore either.
-//
-// **There is no `0x147` here, and that is the finding, not an omission.** The reference registers
-// exactly these four opcodes onto its combat handler `0x6255b0` (`0x62555f`/`0x625570`/`0x625581`/
-// `0x625592`); `0x147` SMSG_ATTACKSWING_NOTSTANDING is never registered, so the client ignores it —
-// and vmangos never sends it either (`Player::SendAttackSwingNotStanding` has zero callers). An arm
-// for it would be code no server can reach and no client ever ran.
+// The server's refusals of a `CMSG_ATTACKSWING`, all with empty bodies (`Combat.cpp`). `0x147`
+// NOTSTANDING is absent on purpose: the reference registers no handler for it (`0x6255b0`).
 pub const SMSG_ATTACKSWING_NOTINRANGE: u16 = 0x0145; // 325
 pub const SMSG_ATTACKSWING_BADFACING: u16 = 0x0146; // 326
 pub const SMSG_ATTACKSWING_DEADTARGET: u16 = 0x0148; // 328
 pub const SMSG_ATTACKSWING_CANT_ATTACK: u16 = 0x0149; // 329
 
-/// The FORCED attack cancel — the swing family's fourth arm, and the one that is not an
-/// `SMSG_ATTACKSWING_*` at all. Empty body (vmangos `WorldPackets::Combat::CancelCombat`), sent by
-/// `Player::SendAttackSwingCancelAttack()` from four places: `Unit::CombatStop`,
-/// `Unit::StopAttackFaction`, `Unit::InterruptAttacksOnMe`, and a resisted feign death.
-///
-/// Registered by the SPELL TU, not the combat one (`0x5e3308`, handler `0x5e7dd0`) — which is why
-/// `0x625520`'s eight-opcode census does not list it. Its handler is **byte-identical to arm 4**
-/// (`0x625ab8`), down to the `__LINE__` it pushes: resolve the active player and StopAttack, no
-/// message on any surface.
+/// The forced attack cancel: empty body (`Player::SendAttackSwingCancelAttack`). The reference
+/// (`0x5e7dd0`) stops our attack and shows nothing.
 pub const SMSG_CANCEL_COMBAT: u16 = 0x014E; // 334
 
-/// A Feign Death the target resisted — empty body (vmangos
-/// `WorldPackets::Combat::FeignDeathResisted`), sent by `Player::SendFeignDeathResisted()` from the
-/// one site that also sends [`SMSG_CANCEL_COMBAT`] (`Objects/Unit.cpp:9445-9451`). The reference's
-/// handler `0x6e9800` is two instructions — `push 0x1a5; call 0x496720` — so it is a plain
-/// `DisplayError(421)` = `ERR_FEIGN_DEATH_RESISTED` = "Resisted", with no latch and no cooldown
-/// behind it.
+/// A Feign Death was resisted: empty body (`Unit.cpp:9445-9451`). The reference (`0x6e9800`) only
+/// shows `ERR_FEIGN_DEATH_RESISTED`.
 pub const SMSG_FEIGN_DEATH_RESISTED: u16 = 0x02B4; // 692
-/// Creature aggro/alert flare (VERIFIED vmangos `Opcodes_1_12_1.h`: 316; body in
-/// [`super::attack::read_ai_reaction`]).
+/// A creature's aggro or alert flare.
 pub const SMSG_AI_REACTION: u16 = 0x013C; // 316
 
-// The spell-visual pipeline wire (VERIFIED vmangos `Opcodes_1_12_1.h`: 305/306/499/668/678;
-// decision 0099 phase 1). Bodies in [`super::spells`].
 pub const SMSG_SPELL_START: u16 = 0x0131; // 305
 pub const SMSG_SPELL_GO: u16 = 0x0132; // 306
 pub const SMSG_PLAY_SPELL_VISUAL: u16 = 0x01F3; // 499
-/// The guild tabard designer's two-way pair (decision 1977; bodies in [`super::tabard`]): the
-/// vendor activation that opens the frame, and the save whose reply is a six-row result.
+/// Save the tabard design, both ways; the reply is one of six results.
 pub const MSG_SAVE_GUILD_EMBLEM: u16 = 0x01F1; // 497
 pub const MSG_TABARDVENDOR_ACTIVATE: u16 = 0x01F2; // 498
 pub const SMSG_CANCEL_AUTO_REPEAT: u16 = 0x029C; // 668
 pub const SMSG_SPELL_FAILED_OTHER: u16 = 0x02A6; // 678
 
-/// `SMSG_SPELL_UPDATE_CHAIN_TARGETS` (VERIFIED vmangos `Opcodes_1_12_1.h`: 816) — the **only**
-/// source of the client's chain-target list, and so the only way a beam gets more than one hop.
-/// The client's handler is `0x6e9820`; it fills the growable array at `unit+0xd44`, which the
-/// chain `CharProc` consumes once and zeroes (decision 0955). Body in [`super::spells`].
+/// The only source of a chain beam's extra hops: the reference (`0x6e9820`) fills `unit+0xd44`,
+/// which the chain `CharProc` consumes once and zeroes.
 pub const SMSG_SPELL_UPDATE_CHAIN_TARGETS: u16 = 0x0330; // 816
 
-/// The **talent spell-modifier** pair (VERIFIED vmangos `Opcodes_1_12_1.h`: 614/615) — the only
-/// feed for every talent that cheapens a spell, shortens its cast or cooldown, extends its range
-/// or radius, or lengthens its duration. Body in [`super::spells::read_set_spell_modifier`];
-/// decision-level law in wow-re `system/spell/scratch/spellmod-table-law.md`.
-///
-/// **One handler, two tables.** Both opcodes register to `Spell_C::HandleSetSpellModifier
-/// 0x6e9950` (`0x6e7245`/`0x6e7255`), which reads the same 6-byte body either way and forks on the
-/// opcode alone (`6e9989: cmp edi,0x267`): `0x266` stores into the FLAT table `0xcead60`, `0x267`
-/// into the PCT table `0xcecb30`, each `i32[64][29]`. The store is a plain `mov`, so the server
-/// sends the **absolute** value of one cell, never a delta (vmangos `Player::SendSpellMod` sends
-/// one packet per set mask bit carrying that pair's total).
-///
-/// That is why the two share a variant here rather than taking one each: the wire shape is
-/// identical and the opcode IS the discriminant, exactly as the reference treats it.
+/// A talent's flat spell modifier; the next opcode is the percent one. Both carry the same 6-byte
+/// body, the absolute value of one table cell, never a delta (reference `0x6e9950`).
 pub const SMSG_SET_FLAT_SPELL_MODIFIER: u16 = 0x0266; // 614
 pub const SMSG_SET_PCT_SPELL_MODIFIER: u16 = 0x0267; // 615
 
-// The cooldown wire (VERIFIED vmangos `Opcodes_1_12_1.h`: 308/176/309/478/481; the client
-// handlers are byte-verified in wow-re `wave-handlers.md` — 0x6e9460/0x6e95d0/0x6e9670/0x6e9730;
-// decision 0137 phase 4). Bodies in [`super::spells`].
 pub const SMSG_SPELL_COOLDOWN: u16 = 0x0134; // 308
 pub const SMSG_ITEM_COOLDOWN: u16 = 0x00B0; // 176
 pub const SMSG_COOLDOWN_EVENT: u16 = 0x0135; // 309
 pub const SMSG_CLEAR_COOLDOWN: u16 = 0x01DE; // 478
 pub const SMSG_COOLDOWN_CHEAT: u16 = 0x01E1; // 481
 
-/// `SMSG_ITEM_TIME_UPDATE` (VERIFIED vmangos `Opcodes_1_12_1.h`: 490) — the
-/// remaining lifetime, in **seconds**, of one duration-limited item instance (a conjured stone, a
-/// holiday gift, a timed quest item). Shares its handler with
-/// [`SMSG_ITEM_ENCHANT_TIME_UPDATE`]: both read an 8-byte item guid first and then fork on the
-/// opcode (`0x5e4f69 sub eax,0x1ea ; je …` / `0x5e4f74 dec eax` — wow-re
-/// `ui/scratch/weapon-enchant-info.md` §7).
-///
-/// The item's own `ITEM_FIELD_DURATION` (wire field 15) carries the same number and is sent to the
-/// owner, but vmangos's writer says in as many words that it is not what the client displays —
-/// *"Though the client has the information in the item's data field, we have to send
-/// SMSG_ITEM_TIME_UPDATE to display the remaining time"* (`Item::SendTimeUpdate`,
-/// `Objects/Item.cpp:1094`). Same shape as the enchant countdown (decision 0920): a client-local
-/// deadline whose only feed is the packet. Body in [`super::items::read_item_time`]; decision 1933.
+/// A timed item's remaining life in seconds; the display reads this, not `ITEM_FIELD_DURATION`
+/// (`Item.cpp:1094`). It shares the reference handler (`0x5e4f69`) with the enchant update below.
 pub const SMSG_ITEM_TIME_UPDATE: u16 = 0x01EA; // 490
 
-/// `SMSG_ITEM_ENCHANT_TIME_UPDATE` (VERIFIED vmangos `Opcodes_1_12_1.h`: 491) — the **only** source
-/// of a temporary enchant's remaining time. The item's `ITEM_FIELD_ENCHANTMENT` duration field is
-/// never read for it: the reference's tooltip reads a client-side per-slot deadline array
-/// (`[obj + slot*4 + 0x324]`) whose only writers are this packet's handler `0x5e4f82` and the item
-/// refresh `0x5ebe34` (wow-re `ui/scratch/tooltip-content-law.md` §E3, byte-verified). Body in
-/// [`super::items::read_item_enchant_time`]; decision 0920.
+/// The only source of a temporary enchant's remaining time: the reference tooltip reads a
+/// per-slot deadline (`obj + slot*4 + 0x324`) that this handler (`0x5e4f82`) writes.
 pub const SMSG_ITEM_ENCHANT_TIME_UPDATE: u16 = 0x01EB; // 491
 
-/// Pushback (VERIFIED vmangos `Opcodes_1_12_1.h`: 482): sent to the caster when a cast takes damage
-/// and the server delays it (`Spell::Delayed`, `Spell.cpp:7472` — a raw `u64` caster guid + `u32`
-/// delaytime ms). The cast bar slides its window out by it (`SPELLCAST_DELAYED`); a normal hit never
-/// interrupts a cast, it only pushes it back (decision 0256).
+/// Cast pushback, to the caster: raw `u64` guid, `u32` delay ms (`Spell.cpp:7472`), and the cast
+/// bar slides by it. A hit only pushes a cast back, never interrupts it.
 pub const SMSG_SPELL_DELAYED: u16 = 0x01E2; // 482
 
-// The self-only channel UI pair (VERIFIED vmangos `Opcodes_1_12_1.h`: 313/314; sent only to the
-// casting player — `Spell::SendChannelStart` {spellId u32, duration_ms u32},
-// `Player::SendChannelUpdate` {remaining_ms u32, 0 = the channel is over}; decision 0137 phase 1,
-// the cast bar's channel half). Bodies in [`super::spells`].
+// The channel bar, to the caster only: START is `u32 spellId`, `u32 duration_ms`; UPDATE is
+// `u32 remaining_ms`, 0 when the channel is over.
 pub const MSG_CHANNEL_START: u16 = 0x0139; // 313
 pub const MSG_CHANNEL_UPDATE: u16 = 0x013A; // 314
 
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 311. Body in [`super::spells::read_update_aura_duration`] —
-/// `{u8 slot, u32 remaining_ms}`. **The only aura fact not carried by the descriptor**, and it is
-/// self-only: `SpellAuraHolder::UpdateAuraDuration` (`SpellAuras.cpp:7511-7523`) writes it to the
-/// aura's *target* (gated on `TYPEID_PLAYER`) and skips permanent auras entirely. So we learn how
-/// long our own buffs last, and never how long anyone else's do. It is also sent **before** the
-/// `UNIT_FIELD_AURA` delta that names the slot's spell — the server writes the descriptor dirty
-/// (flushed at end of tick) and then sends this immediately (decision 0255).
+/// Our own aura's remaining time: `u8 slot`, `u32 remaining_ms`; never for others' or permanent
+/// auras (`SpellAuras.cpp:7511-7523`). It arrives before the `UNIT_FIELD_AURA` delta for the slot.
 pub const SMSG_UPDATE_AURA_DURATION: u16 = 0x0137; // 311
 
-/// The ding (VERIFIED vmangos `Opcodes_1_12_1.h`: 468) — our own level-up, self-addressed only
-/// (`Player::GiveLevel` builds it with no guid and sends straight to the leveling session). Body
-/// in [`super::progression::read_level_up_info`] — decision 0304.
+/// Our own level-up, with no guid and sent only to the leveling player (`Player::GiveLevel`).
 pub const SMSG_LEVELUP_INFO: u16 = 0x01D4; // 468
-/// A newly explored area — area id + the XP it granted (0 at max level). Body
-/// in [`super::progression::read_exploration_xp`] — decision 0828.
-pub const SMSG_EXPLORATION_EXPERIENCE: u16 = 0x01F8; // 504 (VERIFIED vmangos `Opcodes_1_12_1.h:505`)
-/// The honor payout (VERIFIED vmangos `Opcodes_1_12_1.h`: 652) — the XP-gain line's PvP twin, and
-/// the only attributed notice of an honor award: the descriptor's contribution fields move too,
-/// but they are running totals. Sent for **dishonorable** kills as well, carrying negative honor.
-/// Body in [`super::pvp::read_pvp_credit`] ([`super::PvpCredit`]) — decision 1512.
+/// A newly explored area: the area id and the XP it granted (0 at max level).
+pub const SMSG_EXPLORATION_EXPERIENCE: u16 = 0x01F8; // 504
+/// An honor award, the only attributed notice of one; dishonorable kills carry negative honor.
 pub const SMSG_PVP_CREDIT: u16 = 0x028C; // 652
 
-// The combat-log wire (VERIFIED vmangos `Opcodes_1_12_1.h`: 464/587/590/591/592) — decision 0137
-// phase 2's floating-combat-text data feed. Bodies in [`super::spells`].
 pub const SMSG_ENVIRONMENTALDAMAGELOG: u16 = 0x01FC; // 508
 pub const SMSG_LOG_XPGAIN: u16 = 0x01D0; // 464
 pub const SMSG_SPELLLOGMISS: u16 = 0x024B; // 587
@@ -455,9 +256,6 @@ pub const SMSG_PERIODICAURALOG: u16 = 0x024E; // 590
 pub const SMSG_SPELLDAMAGESHIELD: u16 = 0x024F; // 591
 pub const SMSG_SPELLNONMELEEDAMAGELOG: u16 = 0x0250; // 592
 
-// The combat log's remaining wire (VERIFIED vmangos `Opcodes_1_12_1.h`; decision 1703 — the
-// families 1571 §5 named as "deliberately out because their wire sources are undecoded"). Bodies
-// in [`super::combat_log`].
 pub const SMSG_ENCHANTMENTLOG: u16 = 0x01D7; // 471
 pub const SMSG_PARTYKILLLOG: u16 = 0x01F5; // 501
 pub const SMSG_SPELLLOGEXECUTE: u16 = 0x024C; // 588
@@ -467,131 +265,69 @@ pub const SMSG_SPELLORDAMAGE_IMMUNE: u16 = 0x0263; // 611
 pub const SMSG_SPELLDISPELLOG: u16 = 0x027B; // 635
 pub const SMSG_SPELLINSTAKILLLOG: u16 = 0x032F; // 815
 
-// The heal/energize pair (VERIFIED vmangos `Opcodes_1_12_1.h`: 336/337) — the center combat
-// text's HEAL / power-gain feed (decision 0578). Bodies in [`super::spells`].
 pub const SMSG_SPELLHEALLOG: u16 = 0x0150; // 336
 pub const SMSG_SPELLENERGIZELOG: u16 = 0x0151; // 337
 
-// Client → server.
 pub const CMSG_CHAR_CREATE: u16 = 0x0036;
 pub const CMSG_CHAR_ENUM: u16 = 0x0037;
 pub const CMSG_PLAYER_LOGIN: u16 = 0x003D;
 pub const CMSG_LOGOUT_REQUEST: u16 = 0x004B;
-/// The forced logout (`ForceLogout 0x48ab50`, decision 1963): the same session dispatcher as
-/// `Logout`/`Quit` with `force = 1`, which turns the opcode from `0x4B` into `0x4A` and bypasses
-/// the pending-logout latch. Empty body (wow-re `staticpopup-dialog-bindings.md` §4).
+/// The forced logout (`ForceLogout`, `0x48ab50`): empty body, sent in place of
+/// `CMSG_LOGOUT_REQUEST` and past the pending-logout latch.
 pub const CMSG_PLAYER_LOGOUT: u16 = 0x004A; // 74
-/// 78 — call off a pending logout (VERIFIED vmangos `Opcodes_1_12_1.h`), empty body; answered by
-/// [`SMSG_LOGOUT_CANCEL_ACK`]. The CAMP/QUIT dialog's Cancel (decision 0674).
+/// The CAMP/QUIT dialog's Cancel: empty body, answered by [`SMSG_LOGOUT_CANCEL_ACK`].
 pub const CMSG_LOGOUT_CANCEL: u16 = 0x004E;
 pub const CMSG_NAME_QUERY: u16 = 0x0050; // 80
 pub const CMSG_CREATURE_QUERY: u16 = 0x0060; // 96
-/// VERIFIED vmangos `Opcodes_1_12_1.h:85`: 82. Body in [`super::client::pet_name_query`]. Answered
-/// by [`SMSG_PET_NAME_QUERY_RESPONSE`].
+/// Ask a pet's name; answered by [`SMSG_PET_NAME_QUERY_RESPONSE`].
 pub const CMSG_PET_NAME_QUERY: u16 = 0x0052; // 82
 
-// The pet action bar's outbound verbs (decision 0982; VERIFIED vmangos `Opcodes_1_12_1.h`:
-// 373/372/755/746). Bodies in [`super::pet`].
-/// One pet bar press: the slot's own packed word, echoed back with a target guid. The server
-/// re-splits it and dispatches on the type byte — command, reaction, or cast.
+/// A pet bar press: the slot's packed word and a target guid, dispatched on its type byte.
 pub const CMSG_PET_ACTION: u16 = 0x0175; // 373
-/// Move/swap a pet bar slot (the drag). One or two `(position, packed)` pairs; the server tells
-/// the two forms apart **by body size alone**.
+/// A pet bar drag: one or two `(position, packed)` pairs, told apart by body size alone.
 pub const CMSG_PET_SET_ACTION: u16 = 0x0174; // 372
-/// Ask for a pet spell's autocast bit to be set to a given value (the right-click).
+/// Set a pet spell's autocast bit to a given value (the right-click).
 pub const CMSG_PET_SPELL_AUTOCAST: u16 = 0x02F3; // 755
-/// Call the pet off — the Attack button's second press.
+/// Call the pet off: the Attack button's second press.
 pub const CMSG_PET_STOP_ATTACK: u16 = 0x02EA; // 746
-/// Take an aura off the **pet** — a pet bar spell click on a spell already running on it. The
-/// player's own `CMSG_CANCEL_AURA` cannot serve: its body is a bare spell id with no room to name
-/// whose aura to drop.
+/// Cancel one of the pet's auras; `CMSG_CANCEL_AURA` carries only a spell id, no unit.
 pub const CMSG_PET_CANCEL_AURA: u16 = 0x026B; // 619
 
-// The pet right-click menu's two outbound verbs (decision 1066; VERIFIED vmangos
-// `Opcodes_1_12_1.h`: 374/375). Bodies in [`super::pet`].
-/// **Give the pet up permanently** — the right-click menu's Abandon row, and `PetAbandon
-/// 0x4be4c0`'s only packet (wow-re `ui/scratch/pet-action-bar-api.md` §11c, `push 0x176`
-/// @`0x4bd765`). `HandlePetAbandon` deletes a hunter pet (`PET_SAVE_AS_DELETED`) and merely
-/// unsummons anything else (`PET_SAVE_NOT_IN_SLOT`, `PetHandler.cpp:347-374`).
-///
-/// The menu's **Dismiss** row is NOT this opcode, which is worth stating because the two would be
-/// indistinguishable in play: `PetDismiss 0x4be4d0` opens no packet at all and hands the packed
-/// word `0x07000003` to the pet bar's own dispatcher, so it leaves as [`CMSG_PET_ACTION`].
+/// The pet menu's Abandon (`PetAbandon`, `0x4be4c0`): deletes a hunter pet, unsummons anything
+/// else (`PetHandler.cpp:347-374`). Dismiss sends [`CMSG_PET_ACTION`] word `0x07000003` instead.
 pub const CMSG_PET_ABANDON: u16 = 0x0176; // 374
-/// Rename the pet — `PetRename 0x4be4e0` → `0x4bd840` (`push 0x177` @`0x4bd8fe`). Gated server-side
-/// on `UNIT_FLAG_PET_RENAME` and **one-shot**: the handler clears that bit on success, so the row
-/// disappears after the first rename (`PetHandler.cpp:302-345`). Nothing client-side clears it —
-/// wow-re's census found no writer of that byte anywhere in `.text`.
-///
-/// A refused name answers with [`SMSG_PET_NAME_INVALID`] (0x178). Its body really is empty — but
-/// the reference is **not** silent about it: the handler raises `ERR_INVALID_PETNAME` on the red
-/// line. Decision 1066's claim that it does nothing was a mis-attributed handler; see that
-/// constant's own note.
+/// Rename the pet (`PetRename`, `0x4be4e0`). One-shot: the server clears `UNIT_FLAG_PET_RENAME`
+/// on success (`PetHandler.cpp:302-345`); a refusal is [`SMSG_PET_NAME_INVALID`].
 pub const CMSG_PET_RENAME: u16 = 0x0177; // 375
 
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 94 (decision 0236). Body in
-/// [`super::gameobject::gameobject_query`] — the ask-once GO template lookup, identical shape to
-/// `CMSG_CREATURE_QUERY`.
+/// The ask-once GameObject template lookup, shaped like `CMSG_CREATURE_QUERY`.
 pub const CMSG_GAMEOBJECT_QUERY: u16 = 0x005E; // 94
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 92. Body in [`super::quest::quest_query`].
+/// Ask for a quest's template; answered by [`SMSG_QUEST_QUERY_RESPONSE`].
 pub const CMSG_QUEST_QUERY: u16 = 0x005C; // 92
 pub const CMSG_ITEM_QUERY_SINGLE: u16 = 0x0056; // 86
 pub const CMSG_USE_ITEM: u16 = 0x00AB; // 171
-/// VERIFIED vmangos `Opcodes_1_12_1.h:175`: 172. Body in [`super::items::open_item`] — the bag
-/// position of an *openable* item (a clam, an unlocked lockbox, a wrapped gift). The right-click
-/// fork `CMSG_USE_ITEM` never takes: the server answers `SMSG_LOOT_RESPONSE` on the **item's own
-/// guid** (`HandleOpenItemOpcode` → `SendLoot(item, LOOT_CORPSE)`), so the loot window opens over
-/// a thing in your bag rather than a corpse in the world.
+/// Open an openable item (a clam, a lockbox, a gift) by bag position; the loot that answers names
+/// the item's own guid (`HandleOpenItemOpcode`).
 pub const CMSG_OPEN_ITEM: u16 = 0x00AC; // 172
-/// Wrap an item in a piece of gift wrapping (VERIFIED vmangos `Opcodes_1_12_1.h`: 467). Body in
-/// [`super::items::wrap_item`]: `giftBag`, `giftSlot`, `itemBag`, `itemSlot` — the **paper first**,
-/// then the thing being wrapped.
-///
-/// The other half of the gift arc: [`CMSG_OPEN_ITEM`] above *unwraps* one, and this is how a gift
-/// gets made. Right-clicking a `ITEM_FLAG_WRAPPER` template whose instance is **not** already
-/// wrapped sends nothing at all — it arms a purely local wrap cursor (`0x5edea0`: the item lock
-/// `0x4953e0` @`0x5edeb5` + `CursorSetMode(2)`, disarmed by `0x5eded0` from inside `ClearCursor`;
-/// wow-re `ui/scratch/right-click-open.md`, use-dispatcher arm 2, VERIFIED) — and *this* opcode
-/// goes out when the armed cursor is then clicked on a target. Decision 1934.
+/// Gift-wrap an item: `giftBag`, `giftSlot`, `itemBag`, `itemSlot`, paper first. Sent when the
+/// wrap cursor, armed locally by right-clicking the paper (`0x5edea0`), clicks the item.
 pub const CMSG_WRAP_ITEM: u16 = 0x01D3; // 467
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 177. Body in [`super::gameobj_use`] — a full guid, the
-/// GameObject to use (decision 0236). Not interchangeable with `CMSG_LOOT`: the server rejects a
-/// GameObject guid on `CMSG_LOOT`, so a chest opens its loot through this opcode.
+/// Use a GameObject by full guid; chests loot through this, since `CMSG_LOOT` refuses their guids.
 pub const CMSG_GAMEOBJ_USE: u16 = 0x00B1; // 177
-/// A GameObject plays a one-shot **custom** animation (VERIFIED vmangos `Opcodes_1_12_1.h`: 179;
-/// body in [`super::read_gameobject_custom_anim`] — `u64 guid + u32 animId`, from
-/// `GameObject::SendGameObjectCustomAnim`). The client arms GO substate `8 + animId`
-/// (Custom0..3, AnimationData ids 153..156), rejecting `animId >= 4` — wow-re
-/// `gameobject-anim-arm.md` §"one-shot channel" step 8. The load-bearing sender: the fishing
-/// bobber's bite (`animId 0` — the splash; decision 1086).
+/// A GameObject's one-shot custom animation: `u64 guid`, `u32 animId`. The client arms substate
+/// `8 + animId` (AnimationData 153..156) and rejects `animId >= 4`; the bobber's bite is 0.
 pub const SMSG_GAMEOBJECT_CUSTOM_ANIM: u16 = 0x00B3; // 179
-/// The **other** one-shot GameObject arm channel (VERIFIED vmangos `Opcodes_1_12_1.h`: 533,
-/// `WorldObject::SendObjectDeSpawnAnim` → `WorldPackets::Misc::GameObjectDespawnAnim`). Body in
-/// [`super::gameobject`]: a bare `u64` guid. The client arms substate **12** — AnimationData id
-/// **157 Despawn** — and the object then survives its own `SMSG_DESTROY_OBJECT` for the length of
-/// that play (wow-re `gameobject-anim-arm.md` §2c's code table `0x80b0e0[6]` → the `0x8607e4` LUT,
-/// and `go-display-sound-events.md` §6d's arm-time pin). The load-bearing sender: a TRAP that has
-/// spent its charges — UBRS's Rookery Eggs hatch on this packet (decision 1404).
-///
-/// It is **not** GameObject-only: `SendObjectDeSpawnAnim` lives on `WorldObject`, so a totem's
-/// death and a DynamicObject's expiry send it too. The consumer treats a guid with nothing armable
-/// as an ordinary destroy.
+/// The despawn animation: a bare `u64` guid, from `WorldObject` so totems and DynamicObjects too.
+/// The client arms substate 12 (AnimationData 157) and the object outlives its
+/// `SMSG_DESTROY_OBJECT` for that play.
 pub const SMSG_GAMEOBJECT_DESPAWN_ANIM: u16 = 0x0215; // 533
-/// VERIFIED vmangos `Opcodes_1_12_1.h:183`: 180 — and the reference writes this literal
-/// (`0x5e2110`, its area-trigger check, builds `0xb4` + the trigger id). Body in
-/// [`super::area_trigger`]: the `AreaTrigger.dbc` id the player just walked into.
+/// We walked into an area trigger: its `AreaTrigger.dbc` id (reference `0x5e2110`).
 pub const CMSG_AREATRIGGER: u16 = 0x00B4; // 180
-/// VERIFIED vmangos `Opcodes_1_12_1.h:697`: 696. Body in
-/// [`super::area_trigger::read_area_trigger_message`] — why a trigger refused (level, ghost form,
-/// battleground faction). The reference displays it through the same system-message sink as
-/// `SMSG_NOTIFICATION` (`0x4945b0`).
+/// An area trigger's refusal (level, ghost, faction), shown like `SMSG_NOTIFICATION` (`0x4945b0`).
 pub const SMSG_AREA_TRIGGER_MESSAGE: u16 = 0x02B8; // 696
 pub const CMSG_MESSAGECHAT: u16 = 0x0095;
 pub const SMSG_MESSAGECHAT: u16 = 0x0096;
-// The channel family (VERIFIED vmangos `Server/Protocol/Opcodes_1_12_1.h:154-171`, decimal
-// 151-168): join/leave/list + the whole moderation set. Every CMSG here is `cstring channelName [+
-// cstring playerName]` (bodies in [`super::channel`]/[`super::client`]); no channel id rides the
-// 1.12 wire (that's a TBC+ addition). `SMSG_CHANNEL_NOTIFY`/`_LIST` layouts in [`super::channel`].
+// Channels: every CMSG is `cstring channelName` [+ `cstring playerName`]; 1.12 has no channel id.
 pub const CMSG_JOIN_CHANNEL: u16 = 0x0097; // 151
 pub const CMSG_LEAVE_CHANNEL: u16 = 0x0098; // 152
 pub const SMSG_CHANNEL_NOTIFY: u16 = 0x0099; // 153
@@ -611,176 +347,90 @@ pub const CMSG_CHANNEL_UNBAN: u16 = 0x00A6; // 166
 pub const CMSG_CHANNEL_ANNOUNCEMENTS: u16 = 0x00A7; // 167
 pub const CMSG_CHANNEL_MODERATE: u16 = 0x00A8; // 168
 
-// The remaining decision-0288 "wire completeness" opcodes — small, single-purpose chat-adjacent
-// packets that don't belong to any of the families above.
-/// The ignore-list self-notice ("Name is now ignoring you" — VERIFIED vmangos `Opcodes_1_12_1.h`:
-/// 549). Body in [`super::client::chat_ignored`] — a raw `u64` guid
-/// (`WorldPackets::Misc::ChatIgnored::ReadFromWorldPacket`, `Server/Packets/Misc.cpp:127-130`).
+/// The ignore notice ("Name is now ignoring you"): a raw `u64` guid (`Misc.cpp:127-130`).
 pub const CMSG_CHAT_IGNORED: u16 = 0x0225; // 549
-/// A whisper target wasn't found online (VERIFIED vmangos `Opcodes_1_12_1.h`: 681). Body:
-/// [`super::chat::read_chat_player_not_found`] (cstring name, `Server/Packets/Chat.cpp:26-29`).
+/// A whisper target is not online: one cstring name (`Chat.cpp:26-29`).
 pub const SMSG_CHAT_PLAYER_NOT_FOUND: u16 = 0x02A9; // 681
-/// A cross-faction whisper was refused (VERIFIED vmangos `Opcodes_1_12_1.h`: 537); empty body
-/// (`WorldPackets::Chat::ChatWrongFaction::AppendBodyTo`, `Server/Packets/Chat.cpp:16-18`).
+/// A cross-faction whisper was refused; empty body (`Chat.cpp:16-18`).
 pub const SMSG_CHAT_WRONG_FACTION: u16 = 0x0219; // 537
-/// The fishing channel ended with nothing on the hook (VERIFIED vmangos `Opcodes_1_12_1.h`: 456;
-/// empty body — `GameObject::Update`'s bobber-expiry arm and `Use(FISHINGNODE)`'s
-/// clicked-too-early arm both send size 0). The red `ERR_FISH_NOT_HOOKED` toast — "No fish are
-/// hooked." (decision 1086).
+/// Nothing hooked (the bobber expired or was clicked early): empty body, `ERR_FISH_NOT_HOOKED`.
 pub const SMSG_FISH_NOT_HOOKED: u16 = 0x01C8; // 456
-/// The hooked fish got away — the fishing-skill roll failed on the click (VERIFIED vmangos
-/// `Opcodes_1_12_1.h`: 457; empty body — `GameObject::Use`'s FISHINGNODE failure arm). The red
-/// `ERR_FISH_ESCAPED` toast — "Your fish got away!" (decision 1086).
+/// The hooked fish got away (the skill roll failed); empty body, `ERR_FISH_ESCAPED`.
 pub const SMSG_FISH_ESCAPED: u16 = 0x01C9; // 457
-/// A server notice the real client flashes in the red UIErrorsFrame (VERIFIED vmangos
-/// `Opcodes_1_12_1.h`: 459): one cstring (`WorldSession::SendNotification`,
-/// `Server/WorldSession.cpp:900-915`) — "You do not know that language", trade refusals, and kin.
+/// A server notice shown in the red UIErrorsFrame: one cstring (`WorldSession.cpp:900-915`).
 pub const SMSG_NOTIFICATION: u16 = 0x01CB; // 459
 
-// The **world broadcasts** — sent to everyone, or to everyone in a zone, rather than to one player
-// about their own doing. Bodies and the client's own handlers: [`super::broadcast`].
-/// An area is under attack by enemy players (VERIFIED vmangos `Opcodes_1_12_1.h`: 596): one `u32`
-/// `AreaTable.dbc` id (`WorldPackets::Misc::ZoneUnderAttack::AppendBodyTo`,
-/// `Server/Packets/Misc.cpp:451-454`). The client (`0x49dcc0`) formats FrameXML's
-/// `ZONE_UNDER_ATTACK` global string with the area's name and delivers it as `CHAT_MSG_CHANNEL` on
-/// the joined defense channels — **not** as a system line.
+// World broadcasts: to everyone, or to everyone in a zone.
+/// An area is under attack: one `u32` `AreaTable.dbc` id. The client (`0x49dcc0`) fills
+/// `ZONE_UNDER_ATTACK` and posts it on the joined defense channels, not as a system line.
 pub const SMSG_ZONE_UNDER_ATTACK: u16 = 0x0254; // 596
-/// A shutdown/restart countdown or an operator's broadcast (VERIFIED vmangos `Opcodes_1_12_1.h`:
-/// 657): `u32 messageType` + one cstring (`WorldPackets::Misc::ServerMessage::AppendBodyTo`,
-/// `Server/Packets/Misc.cpp:341-345`; layout in [`super::broadcast::read_server_message`]). The
-/// type indexes `ServerMessages.dbc`, whose text is the format string the packet's text fills; the
-/// client (`0x49df80`) shows the result as `CHAT_MSG_SYSTEM`.
+/// A shutdown countdown or operator broadcast: a `u32` `ServerMessages.dbc` id, whose text formats
+/// the cstring that follows; shown as `CHAT_MSG_SYSTEM` (`0x49df80`).
 pub const SMSG_SERVER_MESSAGE: u16 = 0x0291; // 657
-/// A trial account hit its whisper cap (VERIFIED vmangos `Opcodes_1_12_1.h`: 765); **empty body**
-/// (`WorldPackets::Chat::ChatRestricted::AppendBodyTo`, `Server/Packets/Chat.cpp:21-23`), and the
-/// client's arm (`0x5e4a09`) reads none — it is three instructions, `DisplayError(0x1c3)`.
+/// A trial account hit its whisper cap: empty body; the client (`0x5e4a09`) shows error `0x1c3`.
 pub const SMSG_CHAT_RESTRICTED: u16 = 0x02FD; // 765
-/// A world-defense broadcast — the Eastern Plaguelands tower captures (VERIFIED vmangos
-/// `Opcodes_1_12_1.h`: 827): `u32 zoneId`, `u32 length`, then the text (`Map::SendDefenseMessage`,
-/// `src/game/Maps/Map.cpp:1868-1884`, built raw rather than through a packet class and
-/// **1.12-only**). Same destination as [`SMSG_ZONE_UNDER_ATTACK`] and the same handler shape
-/// (`0x49de30`), but the text rides the wire instead of a global string.
+/// A defense broadcast (the Eastern Plaguelands towers): `u32 zoneId`, `u32 length`, the text
+/// (`Map.cpp:1868-1884`). Posted like [`SMSG_ZONE_UNDER_ATTACK`] (`0x49de30`).
 pub const SMSG_DEFENSE_MESSAGE: u16 = 0x033B; // 827
 
-/// `/played` (VERIFIED vmangos `Opcodes_1_12_1.h`: 460/461): empty CMSG body
-/// (`NullClientPacket`), SMSG body `u32 total + u32 level` seconds
-/// (`WorldPackets::Misc::PlayedTime::AppendBodyTo`, `Server/Packets/Misc.cpp:278-282`; layout in
-/// [`super::chat::read_played_time`]).
+/// `/played`: an empty request; the reply is `u32 total`, `u32 level` seconds (`Misc.cpp:278-282`).
 pub const CMSG_PLAYED_TIME: u16 = 0x01CC; // 460
 pub const SMSG_PLAYED_TIME: u16 = 0x01CD; // 461
-/// The server's wall clock (VERIFIED vmangos `Opcodes_1_12_1.h`: 462/463): empty CMSG body
-/// (`NullClientPacket`), SMSG body one `u32` = the server's `time(nullptr)`, i.e. **unix-epoch
-/// seconds** (`WorldSession::SendQueryTimeResponse`, `Handlers/QueryHandler.cpp:418-423`).
-///
-/// This is the epoch the quest-log slot's timer field is expressed in — a timed quest's deadline
-/// is written as `time(nullptr) + limitTime` (`Player::AddQuest`), an absolute stamp with no
-/// relative form anywhere on the wire. So a countdown needs the *server's* now, not ours: that is
-/// what this pair is for, and why benilla sends it (decision 1150). The CMSG body is
-/// [`super::query_time`]; the response is decoded inline beside `SMSG_LOGIN_SETTIMESPEED`, the
-/// other clock packet.
+/// Ask the server's clock: an empty request; the reply is one `u32` of unix seconds
+/// (`QueryHandler.cpp:418-423`). Timed-quest deadlines are stamps on this clock.
 pub const CMSG_QUERY_TIME: u16 = 0x01CE; // 462
 pub const SMSG_QUERY_TIME_RESPONSE: u16 = 0x01CF; // 463
-/// `/random` (VERIFIED vmangos `Opcodes_1_12_1.h`: 507) — same opcode both directions, different
-/// bodies: client sends `u32 min + u32 max` ([`super::client::random_roll`],
-/// `WorldPackets::Group::RandomRoll::ReadFromWorldPacket`, `Server/Packets/Group.cpp:39-43`); the
-/// server broadcasts `u32 min + u32 max + u32 roll + u64 guid`
-/// (`WorldSession::HandleRandomRollOpcode`, `Handlers/GroupHandler.cpp:394-422`; layout in
-/// [`super::chat::read_random_roll`]).
+/// `/random`, both ways: we send `u32 min`, `u32 max`; the server broadcasts min, max,
+/// `u32 roll`, `u64 guid` (`GroupHandler.cpp:394-422`).
 pub const MSG_RANDOM_ROLL: u16 = 0x01FB; // 507
 
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 257. Body in [`super::stand_state_change`].
+/// Ask for a new stand state.
 pub const CMSG_STANDSTATECHANGE: u16 = 0x0101; // 257
+/// A server-side change to our stand state (eat/drink sit, stand on damage): one `u8`, no guid
+/// (`Unit.cpp:9541`). The reference (`0x603e50`) applies it to the local player, ungated.
+pub const SMSG_STANDSTATE_UPDATE: u16 = 0x029D; // 669
 pub const CMSG_CAST_SPELL: u16 = 0x012E; // 302
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 310. Body in [`super::spells::cancel_aura`] — a lone `u32`
-/// spell id (`Server/Packets/Spell.h:55-62`): the server cancels **by spell, never by slot**, and
-/// its handler (`SpellHandler.cpp:333-405`) refuses passives, `SPELL_ATTR_NO_AURA_CANCEL` spells,
-/// and debuffs. wow-re independently records the real client's sender (`Spell_C::CancelAura`
-/// `0x6e7040`, `push 0x136`). Decision 0255.
-/// Body: one `u32` spell id (vmangos `HandleCancelCastOpcode`). The wand-only auto-repeat
-/// handoff sends it for the cached wand Shoot before the local cancel (`0x6095b8`, wow-re
-/// `nocked-ammo-cancel.md` §Q-B-5).
+/// Cancel our cast: one `u32` spell id. The wand auto-repeat handoff sends it for the cached Shoot
+/// before the local cancel (`0x6095b8`).
 pub const CMSG_CANCEL_CAST: u16 = 0x012F; // 303
 pub const CMSG_CANCEL_AURA: u16 = 0x0136; // 310
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 315. Body: one `u32` spell id — the server ignores it
-/// (`Server/Packets/Spell.h:69` "not used by server"; `HandleCancelChanneling` interrupts the
-/// current channel unconditionally) but the real client writes it, so ours does too. Sent by the
-/// cast bar's local self-cancel (`benilla::ui_cast`) when movement/Esc ends our own channel.
+/// Cancel our channel: a `u32` spell id the server ignores (`Spell.h:69`) and 1.12 still sends.
 pub const CMSG_CANCEL_CHANNELLING: u16 = 0x013B; // 315
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 276. Body: a raw 8-byte guid ([`super::full_guid`] —
-/// `WorldPackets::Misc::Inspect`). The server sets our selection to it, refuses beyond
-/// `INSPECT_DISTANCE` (10.0y) or on `IsValidAttackTarget`, and otherwise replies `SMSG_INSPECT`
-/// (277) carrying **only the echoed guid** (`MiscHandler.cpp:943-960`). We deliberately do not
-/// parse that reply: it carries no data, the real client's inspect frame paints from the already-
-/// streamed PUBLIC `PLAYER_VISIBLE_ITEM_*` fields without waiting on it, and no FrameXML handler
-/// registers an inspect event. Decision 0631.
+/// Inspect a player: a raw 8-byte guid. The server selects it, then answers `SMSG_INSPECT` unless
+/// it is beyond 10 yd or attackable (`MiscHandler.cpp:943-960`).
 pub const CMSG_INSPECT: u16 = 0x0114; // 276
-/// 726 (VERIFIED vmangos `Opcodes_1_12_1.h`) — the inspect window's **Honor tab**, and an `MSG_`:
-/// the one opcode number carries both directions. Our request is a raw 8-byte guid
-/// ([`super::inspect_honor_stats`]); the server's reply, on the same number, is the 50-byte
-/// [`super::InspectHonorStats`] body. Nothing needs to disambiguate the two shapes — direction
-/// does: [`super::parse_server`] only ever sees inbound bodies, so a 0x2D6 there is always the
-/// reply, and our outbound body never passes through it.
-///
-/// Same three silent refusals as [`CMSG_INSPECT`] (`MiscHandler.cpp:962-972`), but *unlike* it
-/// this handler does not set our selection. Decision 1512.
+/// The inspect reply, the echoed `u64` guid; the reference discards it (`0x5e7d70`), so we drop it.
+pub const SMSG_INSPECT: u16 = 0x0115; // 277
+/// The inspect Honor tab, both ways: we send a raw 8-byte guid, the reply is a 50-byte body.
+/// Refused silently like [`CMSG_INSPECT`], but without selecting (`MiscHandler.cpp:962-972`).
 pub const MSG_INSPECT_HONOR_STATS: u16 = 0x02D6; // 726
-/// The NPC-click ladder's BATTLEMASTER arm (`0x5e01a0`): a `u64` NPC guid, no gate; the server
-/// answers with `SMSG_BATTLEFIELD_LIST` (decision 1977 retires 1861's greeting stand-in).
+/// Right-click a battlemaster (`0x5e01a0`): a `u64` guid; answered by `SMSG_BATTLEFIELD_LIST`.
 pub const CMSG_BATTLEMASTER_HELLO: u16 = 0x02D7; // 727
 pub const CMSG_SET_SELECTION: u16 = 0x013D; // 317
 pub const CMSG_ATTACKSWING: u16 = 0x0141; // 321
 pub const CMSG_ATTACKSTOP: u16 = 0x0142; // 322
-/// VERIFIED vmangos `Opcodes_1_12_1.h`: 480. Body in [`super::pose::set_sheathed`].
+/// Set our weapon sheath state.
 pub const CMSG_SETSHEATHED: u16 = 0x01E0; // 480
 pub const CMSG_AUTH_SESSION: u16 = 0x01ED;
 pub const CMSG_SET_ACTIVE_MOVER: u16 = 0x026A;
-/// The other half of the mover handshake (VERIFIED vmangos `Opcodes_1_12_1.h`: 721,
-/// `MovementHandler.cpp:886-965`). Body: the full u64 guid of the mover we are *giving up*, then a
-/// whole `MovementInfo`. It clears the server's `m_clientMoverGuid` and re-broadcasts a stop under
-/// the old guid, so skipping it strands observers on that mover's last relayed pose.
+/// Give up a mover: its full u64 guid, then a `MovementInfo`. The server re-broadcasts a stop for
+/// it; unsent, observers keep its last relayed pose (`MovementHandler.cpp:886-965`).
 pub const CMSG_MOVE_NOT_ACTIVE_MOVER: u16 = 0x02D1; // 721
-/// The far-sight **toggle vote** (VERIFIED vmangos `Opcodes_1_12_1.h`: 634,
-/// `MiscHandler.cpp:1138-1155`). Body is a single `u8`: `1` = look through the object, `0` = look
-/// through my own body again.
-///
-/// **The client never names the object.** The server resolves it from `PLAYER_FARSIGHT`, which
-/// only the server writes — so this is a vote on a view it already chose, not a request. Both
-/// branches pass `update_far_sight_field = false`, so **neither touches the field**: it keeps
-/// naming the object while the view toggles under it.
-///
-/// **Sending `0` is destructive and must be deliberate.** It moves the server's *visibility*
-/// source back to our body while `PLAYER_FARSIGHT` still names the object — the world around that
-/// object stops streaming while the camera is still anchored to it. Sending nothing is the safe
-/// default: the server tracks no reply, and it has already attached the viewpoint before we could
-/// answer. `1` is a no-op in every normal flow (`Camera::SetView` early-returns on an unchanged
-/// source); it exists for the buff-click toggle, whose only shipped user is Sentry Totem.
+/// The far-sight toggle: one `u8`, 1 views through the `PLAYER_FARSIGHT` object, 0 through our
+/// body (`MiscHandler.cpp:1138-1155`). Sending 0 moves visibility home while the camera stays on
+/// the object, so it must be deliberate; the server expects no reply.
 pub const CMSG_FAR_SIGHT: u16 = 0x027A; // 634
-/// Empty body. The real client sends it from exactly ONE site — inside the local auto-repeat
-/// cancel `0x6ea080` (`0x6ea0c6`) — so it rides along with *every* cancel trigger (wow-re
-/// `nocked-ammo-cancel.md`). vmangos `HandleCancelAutoRepeatSpellOpcode` interrupts the held
-/// auto-repeat spell (idempotent when the server already cancelled it first).
+/// Stop auto-repeat: empty body, sent from the local cancel (`0x6ea080`), so on every cancel.
 pub const CMSG_CANCEL_AUTO_REPEAT_SPELL: u16 = 0x026D; // 621
 
-// The keepalive pair (VERIFIED twice: vmangos `Opcodes_1_12_1.h` 476/477 AND wow-re net W1 —
-// `SendPing 0x537e10` pushes opcode 0x1dc, `HandlePong 0x537d60` matches 0x1dd). The real client
-// pings every 30 000 ms (wow-re `0x537ff0`, the connection drain's cadence check); vmangos kicks a
-// player socket that pings *faster* than 27 s apart more than `MaxOverspeedPings` (default 2) times
-// (`WorldSocket::_HandlePing`). Bodies: CMSG `{u32 sequence, u32 lastRtt}`; SMSG echoes `{u32
-// sequence}`. vmangos handles the ping inline on the socket (pre-session-queue) and stores the
-// latency field for `.server info`.
+// Keepalive: the 1.12 client pings every 30 s (`0x537ff0`) with `u32 sequence`, `u32 lastRtt`,
+// and the pong echoes the sequence. vmangos kicks after more than 2 pings under 27 s apart.
 pub const CMSG_PING: u16 = 0x01DC; // 476
 pub const SMSG_PONG: u16 = 0x01DD; // 477
 
-// The force-speed-change family (VERIFIED vmangos `Opcodes_1_12_1.h`: 226-231 + 730-735): the
-// server tells the CONTROLLER of a unit its speed changed (an aura slow, a mount, GM `.modify
-// speed`) as `[packed mover guid][u32 movementCounter][f32 newSpeed]` (flat yd/s —
-// `MovementPacketSender::SendSpeedChangeToController`, 5875 = the `> 1_9_4` branch), and the client
-// MUST answer the matching ACK: `[u64 FULL guid][u32 movementCounter][MovementInfo][f32 speed]`
-// (`MoveSpeedAck::ReadFromWorldPacket` — plain `ObjectGuid` extraction reads a full 8 bytes,
-// `ObjectGuid.cpp:180`; the echoed speed must match the sent one ±0.01 and the counter must match
-// a pending change, `Unit::FindPendingMovementSpeedChange`). Unacked, the server force-resolves
-// after `Movement.PendingAckResponseTime` (4 s default) and flags the anticheat's
-// `OnFailedToAckChange` — every speed change desyncs for 4 s and looks like cheating.
+// Speed changes to a unit's controller: `[packed guid][u32 counter][f32 yd/s]`. The client must
+// ack with `[full u64 guid][u32 counter][MovementInfo][f32 speed]`, the speed within 0.01 and the
+// counter pending; unacked, vmangos force-resolves after 4 s and flags it as cheating.
 pub const SMSG_FORCE_RUN_SPEED_CHANGE: u16 = 0x00E2; // 226
 pub const CMSG_FORCE_RUN_SPEED_CHANGE_ACK: u16 = 0x00E3; // 227
 pub const SMSG_FORCE_RUN_BACK_SPEED_CHANGE: u16 = 0x00E4; // 228
@@ -794,14 +444,9 @@ pub const CMSG_FORCE_SWIM_BACK_SPEED_CHANGE_ACK: u16 = 0x02DD; // 733
 pub const SMSG_FORCE_TURN_RATE_CHANGE: u16 = 0x02DE; // 734
 pub const CMSG_FORCE_TURN_RATE_CHANGE_ACK: u16 = 0x02DF; // 735
 
-// The OBSERVER speed-change legs (VERIFIED vmangos `MovementPacketSender`, decision 0441): a
-// speed change on a unit we don't control reaches us one of two ways, neither acked. A
-// server-controlled mover (creature), or a player mid-spline, broadcasts
-// `SMSG_SPLINE_SET_*_SPEED` = `[packed guid][f32 speed]` (`SendSpeedChangeToAll` / the
-// non-finalized `SendSpeedChangeToObservers` branch; 766-771). A freely-moving player's change —
-// the common case: another player mounting up — broadcasts `MSG_MOVE_SET_*_SPEED` =
-// `[packed guid][MovementInfo][f32 speed]` (the finalized-spline branch; 205-216, gaps real),
-// which also carries a fresh authoritative pose.
+// Speed changes on units we do not control, never acked. A creature's, or a player's mid-spline,
+// come as `SMSG_SPLINE_SET_*` `[packed guid][f32 speed]`; a freely moving player's come as
+// `MSG_MOVE_SET_*` `[packed guid][MovementInfo][f32 speed]`, which also carries a fresh pose.
 pub const SMSG_SPLINE_SET_RUN_SPEED: u16 = 0x02FE; // 766
 pub const SMSG_SPLINE_SET_RUN_BACK_SPEED: u16 = 0x02FF; // 767
 pub const SMSG_SPLINE_SET_SWIM_SPEED: u16 = 0x0300; // 768
@@ -809,39 +454,10 @@ pub const SMSG_SPLINE_SET_WALK_SPEED: u16 = 0x0301; // 769
 pub const SMSG_SPLINE_SET_SWIM_BACK_SPEED: u16 = 0x0302; // 770
 pub const SMSG_SPLINE_SET_TURN_RATE: u16 = 0x0303; // 771
 
-// **The OBSERVER movement-mode family** (decision 1780) — the spline-move twelve. Where the
-// `SMSG_FORCE_*`/`SMSG_MOVE_*` family above hands the *controlling client* a mode to ack, this one
-// tells everyone else that some unit's mode changed, and it is a different wire in three ways:
-// the body is a **bare packed guid** (no counter, no `MovementInfo`), there is **no ack**, and the
-// target is **any unit**, not our mover.
-//
-// VERIFIED both ends. Server: vmangos `MovementPacketSender::SendMovementFlagChangeToAll` /
-// `SendToggleRunWalkToAll` (`MovementPacketSender.cpp:399-462`) write `data << unit->GetPackGUID()`
-// and stop — the `+ 4` / `9` in the `WorldPacket` ctor is a capacity hint, not content. Client:
-// all twelve register the single handler `0x603c80`, which reads one packed guid (`0x642ed0`),
-// resolves it with `ClntObjMgrObjectPtr(TYPEMASK_UNIT)` and calls the dispatcher `0x601420`
-// (`lea eax,[edi-0x304]; cmp eax,0x16; ja` — so `0x304..=0x31A`, and `SMSG_SPLINE_MOVE_ROOT`'s
-// out-of-band `0x31A` is deliberately the range's top). An unresolvable guid is dropped silently.
-//
-// The dispatcher's twelve arms, in registration order (`0x603775`-`0x603830`), are a 1:1 map onto
-// the twelve opcodes; six of the arms are independently VERIFIED in wow-re's collision ledger:
-//
-// | opcode | arm | effect on `CMovement+0x40` |
-// |---|---|---|
-// | `0x31A` ROOT | `0x619a10` | `SetRoot 0x7c7340` — sets `0x1000`, and **wipes `0xffe07f00`'s complement once at apply** |
-// | `0x304` UNROOT | `0x619a40` | `ClearRoot 0x7c7370(1)` — clears `0x1000` |
-// | `0x305`/`0x306` | `0x61a4e0` | `SetFeatherFall 0x7c72e0` — `0x20000000` |
-// | `0x307`/`0x308` | `0x61a620` | `SetHover 0x7c7310` — `0x40000000` |
-// | `0x309`/`0x30A` | `0x61a3d0` | `SetWaterWalk 0x7c7280` — `0x10000000` |
-// | `0x30B`/`0x30C` | `0x61a130`/`0x61a160` | `SetSwim 0x7c6e50`/`0x7c6e80` — `0x200000` |
-// | `0x30D`/`0x30E` | `0x617e80` | `SetRunMode 0x7c71c0` — `0x100`, **inverted** (see below) |
-//
-// After any arm the dispatcher re-runs the unit's animation selector (`0x6014ec push edi; call
-// 0x60e480` then `push -1; call 0x5fd9e0`), which is why this family is *visual*: the mode change
-// re-picks the gait on the spot rather than waiting for the next pose.
-//
-// (wow-re `collision/scratch/moveflag-family.md` §§2-5, `collision/scratch/walk-mode-law.md` §5,
-// `collision/scratch/remote-swim-decision.md` §1.4, `collision/ledger.tsv` rows for each arm.)
+// Mode changes on any unit, for observers: a bare packed guid, no counter, no ack
+// (`MovementPacketSender.cpp:399-462`). The reference handles all twelve at `0x603c80`, drops an
+// unresolvable guid, and re-picks the unit's animation after each. Trap: SET_RUN_MODE clears
+// `MOVEFLAG_WALK_MODE` and SET_WALK_MODE sets it (`0x617e80`).
 pub const SMSG_SPLINE_MOVE_UNROOT: u16 = 0x0304; // 772
 pub const SMSG_SPLINE_MOVE_FEATHER_FALL: u16 = 0x0305; // 773
 pub const SMSG_SPLINE_MOVE_NORMAL_FALL: u16 = 0x0306; // 774
@@ -851,11 +467,6 @@ pub const SMSG_SPLINE_MOVE_WATER_WALK: u16 = 0x0309; // 777
 pub const SMSG_SPLINE_MOVE_LAND_WALK: u16 = 0x030A; // 778
 pub const SMSG_SPLINE_MOVE_START_SWIM: u16 = 0x030B; // 779
 pub const SMSG_SPLINE_MOVE_STOP_SWIM: u16 = 0x030C; // 780
-                                                    // **The run/walk pair is inverted against the flag bit, and that is the reference's own sign.**
-                                                    // `0x617e80` passes the opcode's bool straight to `CMovement::SetRunMode 0x7c71c0`, whose argument
-                                                    // is *run* — so `SET_RUN_MODE` CLEARS `MOVEFLAG_WALK_MODE` (`0x100`) and `SET_WALK_MODE` sets it.
-                                                    // Modelled as one [`super::movement::SplineMode::WalkMode`] whose `apply` is the flag's direction,
-                                                    // so every arm of the family means the same thing by "apply": set this bit.
 pub const SMSG_SPLINE_MOVE_SET_RUN_MODE: u16 = 0x030D; // 781
 pub const SMSG_SPLINE_MOVE_SET_WALK_MODE: u16 = 0x030E; // 782
 pub const SMSG_SPLINE_MOVE_ROOT: u16 = 0x031A; // 794
@@ -866,28 +477,18 @@ pub const MSG_MOVE_SET_SWIM_SPEED: u16 = 0x00D3; // 211
 pub const MSG_MOVE_SET_SWIM_BACK_SPEED: u16 = 0x00D5; // 213
 pub const MSG_MOVE_SET_TURN_RATE: u16 = 0x00D8; // 216
 
-// Mount feedback (VERIFIED vmangos `Opcodes_1_12_1.h` 366-367, `Player::SendMountResult` /
-// `SendDismountResult` — one u32 result code; decision 0441). The success codes
-// (`MOUNTRESULT_OK` = 10 / `DISMOUNTRESULT_OK` = 3) are silent in the reference; the failure
-// codes map to red error lines (a P2 trimming — decoded and logged for now).
+// Mount results: one `u32` code (`Player::SendMountResult`). Success (`MOUNTRESULT_OK` = 10,
+// `DISMOUNTRESULT_OK` = 3) is silent in the reference; any other code is a red error line.
 pub const SMSG_MOUNTRESULT: u16 = 0x016E; // 366
 pub const SMSG_DISMOUNTRESULT: u16 = 0x016F; // 367
 
-// The mounted space-bar flourish (VERIFIED vmangos `HandleMountSpecialAnimOpcode`,
-// `MovementHandler.cpp:967`): the CMSG is an EMPTY body; the server rebroadcasts
-// `SMSG_MOUNTSPECIAL_ANIM` — one raw u64 guid — to everyone in range, INCLUDING the sender
-// on vmangos's non-broadcaster delivery path (its `self=false` only gates cheat-logging;
-// live-verified by the double-flourish probe 2026-07-17). The app plays its own flourish
-// locally at send time and self-suppresses the echo; receivers play MountSpecial(94) on
-// that unit's mount (decision 0441 P2).
+// The mounted space-bar flourish: an empty CMSG, echoed as `SMSG_MOUNTSPECIAL_ANIM` (raw u64 guid)
+// to all in range, the sender too (`MovementHandler.cpp:967`); receivers play MountSpecial (94).
 pub const CMSG_MOUNTSPECIAL_ANIM: u16 = 0x0171; // 369
 pub const SMSG_MOUNTSPECIAL_ANIM: u16 = 0x0172; // 370
 
-// Movement (`MSG_MOVE_*`, both directions). The player-movement relay set: the server rebroadcasts
-// each opcode bound to its `HandleMovementOpcodes` (VERIFIED vmangos `Opcodes.cpp`) to nearby clients
-// as `[packed mover guid][MovementInfo]`, same opcode. We *send* the locomotion subset to drive our
-// own avatar and *receive* the whole set as other players' movement (see [`is_movement_relay`]). The
-// two acks (TELEPORT/WORLDPORT) ride the same family but carry different bodies, handled separately.
+// Movement, both ways: vmangos relays each `HandleMovementOpcodes` opcode to nearby clients as
+// `[packed mover guid][MovementInfo]` (`Opcodes.cpp`); the TELEPORT and WORLDPORT acks differ.
 pub const MSG_MOVE_START_FORWARD: u16 = 0x00B5; // 181
 pub const MSG_MOVE_START_BACKWARD: u16 = 0x00B6; // 182
 pub const MSG_MOVE_STOP: u16 = 0x00B7; // 183
@@ -912,9 +513,6 @@ pub const MSG_MOVE_SET_FACING: u16 = 0x00DA; // 218
 pub const MSG_MOVE_SET_PITCH: u16 = 0x00DB; // 219
 pub const MSG_MOVE_HEARTBEAT: u16 = 0x00EE; // 238
 
-// The gossip/vendor interaction set — "right-click a friendly NPC → dialog/vendor" (VERIFIED
-// vmangos `Opcodes_1_12_1.h`: 379-384 gossip/NPC-text, 414-421 vendor). Bodies in
-// [`super::gossip`] (gossip + NPC text) and [`super::vendor`] (vendor list/buy/sell).
 pub const CMSG_GOSSIP_HELLO: u16 = 0x017B; // 379
 pub const CMSG_GOSSIP_SELECT_OPTION: u16 = 0x017C; // 380
 pub const SMSG_GOSSIP_MESSAGE: u16 = 0x017D; // 381
@@ -922,14 +520,9 @@ pub const SMSG_GOSSIP_COMPLETE: u16 = 0x017E; // 382
 pub const CMSG_NPC_TEXT_QUERY: u16 = 0x017F; // 383
 pub const SMSG_NPC_TEXT_UPDATE: u16 = 0x0180; // 384
 
-// The guard's directions marker. Volunteered by a gossip option carrying an `action_poi_id`
-// (vmangos `Player::OnGossipSelect` → `PlayerMenu::SendPointOfInterest`, `GossipDef.cpp:253`), so
-// it answers no request of ours — a gossip-family SMSG with no CMSG beside it, which is why it
-// sits out at 548 instead of inside the 379-384 block. Body in [`super::gossip`].
+// A guard's map marker, pushed unasked by a gossip option's `action_poi_id` (`GossipDef.cpp:253`).
 pub const SMSG_GOSSIP_POI: u16 = 0x0224; // 548
 
-// The questgiver panel set — "accept/turn-in a quest at an NPC" (VERIFIED vmangos
-// `Opcodes_1_12_1.h`: 386-402). Bodies + SMSG layouts in [`super::quest`] (decision 0088).
 pub const CMSG_QUESTGIVER_STATUS_QUERY: u16 = 0x0182; // 386
 pub const SMSG_QUESTGIVER_STATUS: u16 = 0x0183; // 387
 pub const CMSG_QUESTGIVER_HELLO: u16 = 0x0184; // 388
@@ -946,9 +539,6 @@ pub const SMSG_QUESTGIVER_QUEST_INVALID: u16 = 0x018F; // 399
 pub const SMSG_QUESTGIVER_QUEST_COMPLETE: u16 = 0x0191; // 401
 pub const SMSG_QUESTGIVER_QUEST_FAILED: u16 = 0x0192; // 402
 
-// The quest-log wire (VERIFIED vmangos `Opcodes_1_12_1.h`: 403-410) — swap/abandon a logged
-// quest, the full-log refusal, and the log's live progress/state pushes. Bodies + the
-// `SMSG_QUEST_QUERY_RESPONSE` full template in [`super::quest`].
 pub const CMSG_QUESTLOG_SWAP_QUEST: u16 = 0x0193; // 403
 pub const CMSG_QUESTLOG_REMOVE_QUEST: u16 = 0x0194; // 404
 pub const SMSG_QUESTLOG_FULL: u16 = 0x0195; // 405
@@ -958,10 +548,8 @@ pub const SMSG_QUESTUPDATE_COMPLETE: u16 = 0x0198; // 408
 pub const SMSG_QUESTUPDATE_ADD_KILL: u16 = 0x0199; // 409
 pub const SMSG_QUESTUPDATE_ADD_ITEM: u16 = 0x019A; // 410
 
-// The party quest-**share** set (VERIFIED vmangos `Opcodes_1_12_1.h`: 411-413 + 630) — decision
-// 1733. `MSG_QUEST_PUSH_RESULT` is the one bidirectional opcode of the quest family: the receiver
-// sends its own verdict up, the server relays every verdict (its own and the receiver's) back down
-// to the SHARER. Bodies in [`super::quest`]'s `share` submodule.
+// Quest sharing. `MSG_QUEST_PUSH_RESULT` runs both ways: the receiver sends its verdict, and the
+// server relays every verdict, its own and the receiver's, to the sharer.
 pub const CMSG_QUEST_CONFIRM_ACCEPT: u16 = 0x019B; // 411
 pub const SMSG_QUEST_CONFIRM_ACCEPT: u16 = 0x019C; // 412
 pub const CMSG_PUSHQUESTTOPARTY: u16 = 0x019D; // 413
@@ -972,25 +560,16 @@ pub const SMSG_LIST_INVENTORY: u16 = 0x019F; // 415
 pub const CMSG_SELL_ITEM: u16 = 0x01A0; // 416
 pub const SMSG_SELL_ITEM: u16 = 0x01A1; // 417
 pub const CMSG_BUY_ITEM: u16 = 0x01A2; // 418
-/// Buy into a **specific** bag slot. This is what a vendor row dropped out of the merchant
-/// cursor sends (`PickupMerchantItem` mode 5 → the container/doll drop), as against
-/// `CMSG_BUY_ITEM`'s auto-place, which is what clicking the row sends. Both ship (decision 1797).
+/// Buy into a given bag slot (a vendor row dropped from the cursor); a click sends `CMSG_BUY_ITEM`.
 pub const CMSG_BUY_ITEM_IN_SLOT: u16 = 0x01A3; // 419
 pub const SMSG_BUY_ITEM: u16 = 0x01A4; // 420
 pub const SMSG_BUY_FAILED: u16 = 0x01A5; // 421
-/// Buy a sold item back (VERIFIED wow-re `BuybackItem 0x4fb950`'s PutUint32 opcode immediate,
-/// ui/scratch/buyback-data-path.md + vmangos `Opcodes_1_12_1.h` 656 — NOT in the 0x19E vendor run).
+/// Buy a sold item back (`BuybackItem`, `0x4fb950`); outside the 0x19E vendor run.
 pub const CMSG_BUYBACK_ITEM: u16 = 0x0290; // 656
-/// Repair one item (guid) or everything (guid 0) at a repair-capable vendor (VERIFIED wow-re
-/// ui/scratch/repair-machinery.md: `68 a8 02 00 00` at all 4 client send sites; vmangos 680).
+/// Repair one item by guid, or everything with guid 0, at a repair vendor.
 pub const CMSG_REPAIR_ITEM: u16 = 0x02A8; // 680
 
-// The taxi/flight-master set (VERIFIED vmangos `Opcodes_1_12_1.h`: 425-431 the status/menu/
-// activate family, 786 the express-route activate — added later in the opcode table but the same
-// wire family, kept here rather than off with the vendor-era outliers). Guid fields on every one
-// of these (both directions) are a PLAIN u64, never a packed guid (vmangos `ObjectGuid::operator
-// >>/<<`, `ObjectGuid.cpp:174-186` — `PackedGuid` is a distinct type these packets never use).
-// Bodies in [`super::taxi`] (decision 0484).
+// Taxi: every guid in these, both ways, is a plain u64, never packed (`ObjectGuid.cpp:174-186`).
 pub const SMSG_SHOWTAXINODES: u16 = 0x01A9; // 425
 pub const CMSG_TAXINODE_STATUS_QUERY: u16 = 0x01AA; // 426
 pub const SMSG_TAXINODE_STATUS: u16 = 0x01AB; // 427
@@ -998,48 +577,25 @@ pub const CMSG_TAXIQUERYAVAILABLENODES: u16 = 0x01AC; // 428
 pub const CMSG_ACTIVATETAXI: u16 = 0x01AD; // 429
 pub const SMSG_ACTIVATETAXIREPLY: u16 = 0x01AE; // 430
 pub const SMSG_NEW_TAXI_PATH: u16 = 0x01AF; // 431
-/// `> CLIENT_BUILD_1_9_4` — active for 5875. Multi-hop route activate (guid, totalcost, node
-/// list); a single hop still goes through plain `CMSG_ACTIVATETAXI` above (vmangos accepts both).
+/// A multi-hop flight: guid, total cost, node list; a single hop uses `CMSG_ACTIVATETAXI`.
 pub const CMSG_ACTIVATETAXIEXPRESS: u16 = 0x0312; // 786
 
-// The class/profession trainer set (VERIFIED vmangos `Opcodes_1_12_1.h`: 432-436) — one window for
-// both, reached through the gossip trainer option (`GOSSIP_OPTION_TRAINER`), not a trainer-specific
-// open verb. `CMSG_TRAINER_LIST` requests/refreshes the list; buy is `CMSG_TRAINER_BUY_SPELL`.
-// Bodies in [`super::trainer`] (decision 0237).
+// Trainers, class and profession alike, open from `GOSSIP_OPTION_TRAINER`; there is no open verb.
 pub const CMSG_TRAINER_LIST: u16 = 0x01B0; // 432
 pub const SMSG_TRAINER_LIST: u16 = 0x01B1; // 433
 pub const CMSG_TRAINER_BUY_SPELL: u16 = 0x01B2; // 434
 pub const SMSG_TRAINER_BUY_SUCCEEDED: u16 = 0x01B3; // 435
 pub const SMSG_TRAINER_BUY_FAILED: u16 = 0x01B4; // 436
 
-// The innkeeper bind set (VERIFIED vmangos `Opcodes_1_12_1.h`: 437, 344, 747; decision 1331).
-// Selecting an innkeeper's `GOSSIP_OPTION_INNKEEPER` line makes the server close the gossip menu
-// and send `SMSG_BINDER_CONFIRM` — a QUESTION, not a bind. Nothing is bound until the client
-// answers `CMSG_BINDER_ACTIVATE`, which is what the confirm dialog's Accept sends; the server then
-// has the innkeeper cast spell 3286 "Bind" on the player, whose `SPELL_EFFECT_BIND` sends
-// `SMSG_BINDPOINTUPDATE` (above) and `SMSG_PLAYERBOUND` (vmangos `SpellEffects.cpp` `EffectBind`).
-// Bodies in [`super::binder`]. `SMSG_PLAYERBINDERROR` (0x01B6) is the refusal and is not parsed:
-// vmangos never sends it on any path (`SendBindPoint` simply returns inside an instance).
+// The innkeeper bind: `SMSG_BINDER_CONFIRM` only asks; Accept sends `CMSG_BINDER_ACTIVATE`, then
+// spell 3286 binds and sends `SMSG_BINDPOINTUPDATE` and `SMSG_PLAYERBOUND` (`EffectBind`).
 pub const CMSG_BINDER_ACTIVATE: u16 = 0x01B5; // 437
 pub const SMSG_PLAYERBOUND: u16 = 0x0158; // 344
 pub const SMSG_BINDER_CONFIRM: u16 = 0x02EB; // 747
 
-// The GM trouble-ticket set (VERIFIED vmangos `Opcodes_1_12_1.h` + `Opcodes.cpp:608-630`; decision
-// 1673). Five request/answer pairs behind the Help window, and the client asks for all of them —
-// there is no ticket state pushed at login, so `CMSG_GMTICKET_GETTICKET` right after world entry is
-// the client's own (seen in the 1.12.1 retail sniff, answered `TicketStatus: 10 (NoText)`).
-//
-// **Two of these answers can also arrive UNSOLICITED on vmangos**, which is why they are decoded
-// rather than correlated to a pending ask: `.ticket viewid`/`viewname`/`escalate`/`complete` push a
-// fresh `SMSG_GMTICKET_GETTICKET` at the ticket's author (`GMTicketMgr.cpp:153-159`,
-// `TicketCommands.cpp:265,443-452`), and `.ticket delete <id>` pushes a
-// `SMSG_GMTICKET_DELETETICKET` = `TICKET_DELETED` (`TicketCommands.cpp:100-103`).
-//
-// **And two requests can be answered with SILENCE**, which is why nothing in the client blocks on a
-// reply: `HandleGMTicketCreateOpcode` simply returns — no packet at all — when the queue is off,
-// when the player is under `GMTickets.MinLevel`, or when the category is >= 11
-// (`GMTicketHandler.cpp:91,106-113`), and delete-with-no-ticket likewise returns silently (`:73-86`).
-// Bodies in [`super::gm_ticket`].
+// GM tickets: nothing is pushed at login, so the client asks `CMSG_GMTICKET_GETTICKET`. GM commands
+// push GETTICKET and DELETETICKET answers unasked (`TicketCommands.cpp`), and a create or delete
+// can go unanswered (`GMTicketHandler.cpp:73-113`), so nothing waits on a reply.
 pub const CMSG_GMTICKET_CREATE: u16 = 0x0205; // 517
 pub const SMSG_GMTICKET_CREATE: u16 = 0x0206; // 518
 pub const CMSG_GMTICKET_UPDATETEXT: u16 = 0x0207; // 519
@@ -1051,24 +607,13 @@ pub const SMSG_GMTICKET_DELETETICKET: u16 = 0x0218; // 536
 pub const CMSG_GMTICKET_SYSTEMSTATUS: u16 = 0x021A; // 538
 pub const SMSG_GMTICKET_SYSTEMSTATUS: u16 = 0x021B; // 539
 
-/// The GM's own ticket-state push (VERIFIED vmangos `Opcodes_1_12_1.h`: 808). Body is a bare `u32`:
-/// 1 = updated, 2 = closed, 3 = a survey is offered.
-///
-/// **vmangos never constructs this packet on any path** — it is registered in its opcode table and
-/// nothing in its source sends it — so on the server benilla talks to this arm is dead. cmangos-
-/// classic makes it the core of its notification model (escalation, first GM read, re-sort, text
-/// update, assignment, queue toggle, close), which is why it is parsed rather than dropped.
-///
-/// It is decoded for one reason beyond completeness: the reference engine answers value 1 by
-/// re-asking for the ticket (`0x5e7932`, wow-re §5), the same leg the create/update success codes
-/// take. Values 2 and 3 are recorded but not acted on — 3 is the GM-survey trigger, and the survey
-/// window is deferred (decision 1673).
+/// A ticket-state push: `u32` 1 updated, 2 closed, 3 survey offered; vmangos never sends it. The
+/// reference re-asks for the ticket on 1 (`0x5e7932`). Deviation: 3 opens no survey window,
+/// since vmangos can never offer one.
 pub const SMSG_GM_TICKET_STATUS_UPDATE: u16 = 0x0328; // 808
 
-// The bank set (VERIFIED vmangos `Opcodes_1_12_1.h`: 439,440-441,642-643).
-// `CMSG_BANKER_ACTIVATE` right-clicks a pure banker;
-// `SMSG_SHOW_BANK` also arrives unprompted from the `GOSSIP_OPTION_BANKER` gossip option. Slot
-// purchase and deposit/withdraw bodies in [`super::bank`].
+// The bank: `CMSG_BANKER_ACTIVATE` opens a pure banker; `SMSG_SHOW_BANK` also arrives unasked
+// from the `GOSSIP_OPTION_BANKER` option.
 pub const CMSG_BANKER_ACTIVATE: u16 = 0x01B7; // 439
 pub const SMSG_SHOW_BANK: u16 = 0x01B8; // 440
 pub const CMSG_BUY_BANK_SLOT: u16 = 0x01B9; // 441
@@ -1076,20 +621,12 @@ pub const SMSG_BUY_BANK_SLOT_RESULT: u16 = 0x01BA; // 442
 pub const CMSG_AUTOSTORE_BANK_ITEM: u16 = 0x0282; // 642
 pub const CMSG_AUTOBANK_ITEM: u16 = 0x0283; // 643
 
-// The pet-stable set (VERIFIED vmangos `Opcodes_1_12_1.h`: 623-629). `MSG_LIST_STABLED_PETS` is one
-// opcode in BOTH directions: the gossip stable option makes the server send the list unprompted
-// (that is how the window opens), and the client sends the same number back — one guid — to
-// refresh. The four mutations are all answered by a single `SMSG_STABLE_RESULT` byte and nothing
-// else, so a successful one is a cue to re-ask the list. Bodies in [`super::stable`]
-// (decision 1676). `CMSG_STABLE_REVIVE_PET` (0x0274, 628) is deliberately absent: vmangos's handler
-// is an empty no-op and whether the 5875 client ever sends it is an open RE question.
-/// Forget a cached player name (VERIFIED vmangos `Opcodes_1_12_1.h`: 796) — body `{u64 guid}`.
-/// The client's name cache has **no TTL**: eviction is explicit, and this is the one packet that
-/// does it for a player (wow-re `system/dbcache/dbcache.md` Contracts, remove-by-key `0x556ff0`).
-/// Decision 1689. vmangos never sends it, so this is the mechanism present and correct rather
-/// than a path our own server exercises.
+/// Forget a cached player name: `u64 guid`, the cache's only eviction for a player (it has no
+/// TTL; `0x556ff0`). vmangos never sends it.
 pub const SMSG_INVALIDATE_PLAYER: u16 = 0x031C; // 796
 
+// The pet stable. `MSG_LIST_STABLED_PETS` runs both ways: the server sends the list to open the
+// window, the client sends one guid to refresh. Mutations get only one `SMSG_STABLE_RESULT` byte.
 pub const MSG_LIST_STABLED_PETS: u16 = 0x026F; // 623
 pub const CMSG_STABLE_PET: u16 = 0x0270; // 624
 pub const CMSG_UNSTABLE_PET: u16 = 0x0271; // 625
@@ -1097,172 +634,102 @@ pub const CMSG_BUY_STABLE_SLOT: u16 = 0x0272; // 626
 pub const SMSG_STABLE_RESULT: u16 = 0x0273; // 627
 pub const CMSG_STABLE_SWAP_PET: u16 = 0x0275; // 629
 
-/// Spend talent points (VERIFIED vmangos `Opcodes_1_12_1.h`: 593) — body in
-/// [`super::progression::learn_talent`]; the server answers with the rank spell's learn effects
-/// (`SMSG_LEARNED_SPELL` etc.) and the refreshed `PLAYER_CHARACTER_POINTS1`. Decision 0304.
+/// Spend a talent point; the rank's `SMSG_LEARNED_SPELL` and `PLAYER_CHARACTER_POINTS1` answer it.
 pub const CMSG_LEARN_TALENT: u16 = 0x0251; // 593
 
-/// The respec question and its answer — **one opcode, both directions** (VERIFIED vmangos
-/// `Opcodes_1_12_1.h`: 682 + `Opcodes.cpp`'s `HandleTalentWipeConfirmOpcode` registration; decision
-/// 1580). Selecting a class trainer's "I wish to unlearn my talents" line
-/// (`GOSSIP_OPTION_UNLEARNTALENTS`, `Player.cpp:12330`) makes the server close the gossip menu and
-/// send this **inbound** carrying the trainer's guid and the current cost — a QUESTION, the talent
-/// twin of [`SMSG_BINDER_CONFIRM`]. Nothing is unlearned until the client sends the same opcode
-/// **outbound** with that guid, which is the `CONFIRM_TALENT_WIPE` dialog's Accept; the server then
-/// runs `Player::ResetTalents` and has the trainer cast 14867 "Untalent Visual Effect".
-///
-/// Byte-verified client-side too (wow-re `system/ui/scratch/talent-api.md` §ConfirmTalentWipe,
-/// `0x48dc40` → `0x5df980`): both directions run through one range-gated function, whose outbound
-/// leg puts the *latched* trainer guid on the wire. Bodies in [`super::progression`].
+/// The respec, both ways: the trainer's gossip line (`Player.cpp:12330`) makes the server ask with
+/// the trainer's guid and the cost; the `CONFIRM_TALENT_WIPE` Accept sends the latched guid back.
 pub const MSG_TALENT_WIPE_CONFIRM: u16 = 0x02AA; // 682
-/// `SMSG_RAID_GROUP_ONLY` (wow-re `staticpopup-dialog-bindings.md` §5.2): `u32 delayMs`,
-/// `u32 reason`. Every arrival fires an instance-boot event — START for a positive delay, STOP
-/// for zero — and a zero delay with reason 1/2 also shows `ERR_RAID_GROUP_ONLY`/`_FULL`
-/// (decision 1963).
+/// The instance boot timer: `u32 delayMs`, `u32 reason`; boot START for a positive delay, STOP for
+/// zero, and with reason 1 or 2 a zero delay also shows `ERR_RAID_GROUP_ONLY` or `_FULL`.
 pub const SMSG_RAID_GROUP_ONLY: u16 = 0x0286; // 646
-/// The battleground queue's slot update (§7): `u32 slot`, `u32 mapId`, `u8 bracket`, `u32`,
-/// `u32 status`, then `u32` when status is 2 and two `u32` when it is 3; fires
-/// `UPDATE_BATTLEFIELD_STATUS` (decision 1963).
+/// A battleground queue slot: `u32 slot`, `u32 mapId`, `u8 bracket`, `u32`, `u32 status`, then
+/// one `u32` for status 2, two for 3; fires `UPDATE_BATTLEFIELD_STATUS`.
 pub const SMSG_BATTLEFIELD_STATUS: u16 = 0x02D4; // 724
-/// `AcceptBattlefieldPort(index, accept)`'s packet (§7): `u32 mapId` (the slot's Map.dbc row),
-/// `u8 accept` (decision 1963).
+/// `AcceptBattlefieldPort(index, accept)`: `u32 mapId` (the slot's Map.dbc row), `u8 accept`.
 pub const CMSG_BATTLEFIELD_PORT: u16 = 0x02D5; // 725
-/// The battleground scoreboard, both ways (wow-re `battlefield-verb-family.md` §4.3/§5.1, 1972):
-/// the client's `RequestBattlefieldScoreData` sends it EMPTY (throttled to 5000 ms client-side);
-/// the server's answer is `u8 ended`, `u8 winner` only when ended, `u32 count`, then per row
-/// `u64 guid, u32 rank, u32 killingBlows, u32 honorableKills, u32 deaths, u32 honorGained,
-/// u32 statCount, statCount × u32` (the client stores at most eight). Fires
-/// `UPDATE_BATTLEFIELD_SCORE` once every row's name resolves.
+/// The battleground scoreboard, both ways: an empty request (throttled to 5000 ms); the reply is
+/// `u8 ended`, `u8 winner` if ended, `u32 count`, then per row `u64 guid`, `u32` rank,
+/// killingBlows, honorableKills, deaths, honorGained, statCount, and statCount `u32` (the client
+/// keeps eight). Fires `UPDATE_BATTLEFIELD_SCORE` once every row's name resolves.
 pub const MSG_PVP_LOG_DATA: u16 = 0x02E0; // 736
-/// `LeaveBattlefield()`'s packet (§5.3, 1972): `u32 mapId` of the battleground the client is in,
-/// sent only once the scoreboard's "ended" byte has arrived.
+/// `LeaveBattlefield()`: `u32 mapId`, sent only once the scoreboard's ended byte has arrived.
 pub const CMSG_LEAVE_BATTLEFIELD: u16 = 0x02E1; // 737
-/// The battleground teammate positions, both ways (wow-re `worldmap-arrow-and-positions.md` §3.1,
-/// 1980): `RequestBattlefieldPositions()` sends it EMPTY (5000 ms throttle, only with an active
-/// slot); the server's answer is `u32 count`, `count × (u64 guid, f32 x, f32 y)`, then
-/// `u8 hasCarrier` and, when set, one `(u64 guid, f32 x, f32 y)` flag carrier. No event fires on
-/// arrival — the UI polls.
+/// Battleground teammate positions, both ways: an empty request (5000 ms throttle, active slot
+/// only); the reply is `u32 count`, count × `(u64 guid, f32 x, f32 y)`, `u8 hasCarrier`, and if
+/// set one more such triple for the flag carrier. No event fires; the UI polls.
 pub const MSG_BATTLEGROUND_PLAYER_POSITIONS: u16 = 0x02E9; // 745
-/// `ShowBattlefieldList(index)`'s packet (wow-re `battlefield-verb-family.md` §5, 1974): `u32 mapId`
-/// of a QUEUED slot — the battlemaster-less way to reopen the instance list.
+/// `ShowBattlefieldList(index)`: a queued slot's `u32 mapId`, reopening the list without an NPC.
 pub const CMSG_BATTLEFIELD_LIST: u16 = 0x023C; // 572
-/// The battleground instance list (§4.1, 1974): `u64 battlemaster` (zero when the list was not
-/// opened at an NPC), `u32 mapId`, `u8 bracket`, `u32 count`, `count × u32 instanceId`. Fires
-/// `BATTLEFIELDS_SHOW`; the cached battlemaster guid decides which join opcode a later
-/// `JoinBattlefield` sends.
+/// The battleground instance list: `u64 battlemaster` (0 away from an NPC), `u32 mapId`,
+/// `u8 bracket`, `u32 count`, count × `u32 instanceId`. Fires `BATTLEFIELDS_SHOW`; the
+/// battlemaster guid decides which join opcode `JoinBattlefield` sends.
 pub const SMSG_BATTLEFIELD_LIST: u16 = 0x023D; // 573
-/// `JoinBattlefield`'s packet when the list arrived WITHOUT a battlemaster (§5.2, 1974): `u32 mapId`,
-/// `u32 instanceId` (0 = first available), `u8 asGroup`.
+/// `JoinBattlefield`, no battlemaster: `u32 mapId`, `u32 instanceId` (0 = any), `u8 asGroup`.
 pub const CMSG_BATTLEFIELD_JOIN: u16 = 0x023E; // 574
-/// `JoinBattlefield`'s packet when the list arrived from a battlemaster (§5.2, 1974): `u64 guid`,
-/// `u32 mapId`, `u32 instanceId` (0 = first available), `u8 asGroup`.
+/// `JoinBattlefield` at a battlemaster: `u64 guid`, then the body of [`CMSG_BATTLEFIELD_JOIN`].
 pub const CMSG_BATTLEMASTER_JOIN: u16 = 0x02EE; // 750
-/// The world-enter status request (§5/§8, 1974): EMPTY; the server answers with one
-/// `SMSG_BATTLEFIELD_STATUS` per live queue slot.
+/// The world-entry status request: empty; answered by one `SMSG_BATTLEFIELD_STATUS` per live slot.
 pub const CMSG_BATTLEFIELD_STATUS: u16 = 0x02D3; // 723
-/// A group join's verdict (§4.4, 1974): `u32 result` — `0xFFFFFFFE` deserters (message 439), a
-/// Map.dbc id joined (440, with the map's name), anything else the generic failure (441).
+/// A group join's verdict: `u32`, `0xFFFFFFFE` for deserters (message 439), a Map.dbc id joined
+/// (440), anything else failure (441).
 pub const SMSG_GROUP_JOINED_BATTLEGROUND: u16 = 0x02E8; // 744
-/// A player joined the battleground (§4.5, 1974): `u64 guid`, printed as message 444 once the name
-/// cache answers.
+/// A player joined the battleground: `u64 guid`, printed as message 444 once the name resolves.
 pub const SMSG_BATTLEGROUND_PLAYER_JOINED: u16 = 0x02EC; // 748
-/// A player left the battleground (§4.5, 1974): `u64 guid`, message 445.
+/// A player left the battleground: `u64 guid`, message 445.
 pub const SMSG_BATTLEGROUND_PLAYER_LEFT: u16 = 0x02ED; // 749
-/// The area spirit healer query the client sends when it adopts a new healer (§6): `u64 guid`;
-/// answered by [`SMSG_AREA_SPIRIT_HEALER_TIME`] (decision 1963).
+/// Sent on adopting a new area spirit healer: `u64 guid`; [`SMSG_AREA_SPIRIT_HEALER_TIME`] answers.
 pub const CMSG_AREA_SPIRIT_HEALER_QUERY: u16 = 0x02E2; // 738
-/// `AcceptAreaSpiritHeal()`'s packet (§6): `u64 guid`, the CACHED current-area healer, never an
-/// argument (decision 1963).
+/// `AcceptAreaSpiritHeal()`: the cached area healer's `u64 guid`, never an argument.
 pub const CMSG_AREA_SPIRIT_HEALER_QUEUE: u16 = 0x02E3; // 739
-/// The healer's next-resurrection clock (§6): `u64 guid`, `u32 ms`; a match against the cached
-/// healer with a positive time arms the deadline and fires `AREA_SPIRIT_HEALER_IN_RANGE`
-/// (decision 1963).
+/// The healer's next resurrection: `u64 guid`, `u32 ms`. For the cached healer and a positive
+/// time it arms the deadline and fires `AREA_SPIRIT_HEALER_IN_RANGE`.
 pub const SMSG_AREA_SPIRIT_HEALER_TIME: u16 = 0x02E4; // 740
-/// The meeting stone's JOIN — the packet a right-click on a `GAMEOBJECT_TYPE_MEETINGSTONE` (23)
-/// sends: `u64 gameObjectGuid`, built and sent by `0x4c9ff0` from the tail (`0x5f6af6`) of that
-/// type's own use-slot validator `0x5f69d0` = `[0x80bf40+0x1c]` (decision 2283, VERIFIED by
-/// wow-re's §5 round on that function). Twelve bytes on the wire, body exactly eight, no padding.
-///
-/// A meeting stone **cannot** send [`CMSG_GAMEOBJ_USE`]: the shared sender `0x5f33e0` has zero
-/// direct callers and is reachable only as some vtable's `+0x1c`, which type 23's is not. And
-/// vmangos would drop it anyway — `GameObject::Use` has an explicit do-nothing type-23 arm
-/// (`GameObject.cpp:1836`, "Should never be called for this type of object").
+/// Right-click a meeting stone (GameObject type 23): `u64` guid, sent by `0x4c9ff0`. A stone never
+/// sends [`CMSG_GAMEOBJ_USE`], which vmangos ignores for type 23 (`GameObject.cpp:1836`).
 pub const CMSG_MEETINGSTONE_JOIN: u16 = 0x0292; // 658
-/// `CancelMeetingStoneRequest()`'s packet (§8): EMPTY. Gated client-side on party leadership
-/// only; clears nothing — the server's `0x295` reply does (decision 1963). The emulators' name
-/// for this number does not line up with the client's block; the number is what is verified.
+/// `CancelMeetingStoneRequest()`: empty, party leader only; the server's `0x295` reply clears the
+/// state. The name is the emulators'; the number is the client's.
 pub const CMSG_MEETINGSTONE_LEAVE: u16 = 0x0293; // 659
-/// The meeting-stone queue state (§8): `u32 areaId`, `u8 status`; stored unconditionally, a
-/// status message per value, then `MEETINGSTONE_CHANGED` (decision 1963).
+/// The meeting-stone queue state: `u32 areaId`, `u8 status`; always stored, a message per
+/// status, then `MEETINGSTONE_CHANGED`.
 pub const SMSG_MEETINGSTONE_SETQUEUE: u16 = 0x0295; // 661
-/// The enter-world "what is my meeting-stone status" query (wow-re `meeting-stone-status.md`
-/// §6, 1974): EMPTY, sent once per world session right after the status text resets to the
-/// localized `UNKNOWN`; the server answers with `0x295`. The emulators' names for this block do
-/// not line up with the client's; the numbers are what is verified.
+/// The world-entry meeting-stone status query: empty, once per session; answered by `0x295`.
+/// vmangos names it `CMSG_MEETINGSTONE_INFO`.
 pub const CMSG_MEETINGSTONE_STATUS_QUERY: u16 = 0x0296; // 662
-/// Display-only (§9): empty; `ERR_MEETING_STONE_SUCCESS` (1974).
+/// Display only: empty; `ERR_MEETING_STONE_SUCCESS`.
 pub const SMSG_MEETINGSTONE_SUCCESS: u16 = 0x0297; // 663
-/// Display-only (§9): empty; `ERR_MEETING_STONE_IN_PROGRESS` (1974).
+/// Display only: empty; `ERR_MEETING_STONE_IN_PROGRESS`.
 pub const SMSG_MEETINGSTONE_IN_PROGRESS: u16 = 0x0298; // 664
-/// Display-only (§9): `u64 guid`; `ERR_MEETING_STONE_MEMBER_ADDED_S` with the name once the name
-/// cache answers, nothing on a miss that never resolves (1974).
+/// Display only: `u64 guid`; `ERR_MEETING_STONE_MEMBER_ADDED_S` once the name resolves.
 pub const SMSG_MEETINGSTONE_MEMBER_ADDED: u16 = 0x0299; // 665
-/// Display-only (§9): `u8 code` — `1` must-be-leader, `2` group full, `3` no raid group, anything
-/// else nothing (1974).
+/// Display only: `u8 code`, 1 must be leader, 2 group full, 3 no raid group, else nothing.
 pub const SMSG_MEETINGSTONE_JOIN_FAILED: u16 = 0x02BB; // 699
-/// `ConfirmPetUnlearn()`'s packet (§9): `u64 trainerGuid`, the latch — never an argument
-/// (decision 1963).
+/// `ConfirmPetUnlearn()`: the latched `u64 trainerGuid`, never an argument.
 pub const CMSG_PET_UNLEARN: u16 = 0x02F0; // 752
-/// The pet trainer's question (§9): `u64 trainerGuid`, `u32 costCopper` — latched, then
-/// `CONFIRM_PET_UNLEARN(cost)`; a zero guid shows `ERR_TALENT_WIPE_ERROR` instead (the reference
-/// re-uses the talent-wipe string there) (decision 1963).
+/// The pet trainer asks: `u64 trainerGuid`, `u32 costCopper`, latched for
+/// `CONFIRM_PET_UNLEARN`; a zero guid shows `ERR_TALENT_WIPE_ERROR` instead.
 pub const SMSG_PET_UNLEARN_CONFIRM: u16 = 0x02F1; // 753
 
-/// The player-summon pair — the question and the accept (VERIFIED vmangos `Opcodes_1_12_1.h`:
-/// 683/684 + `Opcodes.cpp`'s `HandleSummonResponseOpcode` registration; decision 1747). A
-/// warlock's Ritual of Summoning, a meeting stone and a GM `.summon` all arrive as the same
-/// inbound question, and the client answers only to say **yes**: there is no decline opcode and no
-/// accept flag in the body, so a declined summon is silence and the server's own two-minute timer.
-///
-/// Byte-verified client-side as well as against vmangos (wow-re: the `0x5ab650` registration site
-/// maps `0x2ab` to handler `0x5e6140`, and the `ConfirmSummon` binding `0x48b770` writes `0x2ac`).
-/// Bodies in [`super::summon`].
+/// A summon offer (warlock, meeting stone, GM). The client can only accept, with
+/// `CMSG_SUMMON_RESPONSE` (`0x48b770`); a decline is silence until the two-minute timeout.
 pub const SMSG_SUMMON_REQUEST: u16 = 0x02AB; // 683
 pub const CMSG_SUMMON_RESPONSE: u16 = 0x02AC; // 684
 
-/// Unlearn (abandon) a whole skill line — the skills pane's red circle-slash (VERIFIED vmangos
-/// `Opcodes.cpp` handler registration + `Opcodes_1_9_4.h`: 514). Body in
-/// [`super::skills::unlearn_skill`]; no ack — the removal returns as a `PLAYER_SKILL_INFO`
-/// field update.
+/// Abandon a skill line; no ack, the removal arrives as a `PLAYER_SKILL_INFO` update.
 pub const CMSG_UNLEARN_SKILL: u16 = 0x0202; // 514
 
-/// Ask to flip our own PvP flag (decision 0646). A **two-way** opcode: vmangos reads a `bool`
-/// target state iff the body is exactly one byte (`Server/Packets/Misc.cpp`
-/// `TogglePvP::ReadFromWorldPacket`) and otherwise *toggles* `PLAYER_FLAGS_PVP_DESIRED`
-/// (`Handlers/MiscHandler.cpp` `HandleTogglePvP`). benilla sends the **empty** body — the verb is
-/// a toggle. No ack: the answer arrives as the `UNIT_FIELD_FLAGS` PvP bit in a descriptor update,
-/// and turning the preference *off* changes nothing until the server's 300 s drop timer expires.
+/// Toggle our PvP flag: we send the empty body, a toggle; one byte would set a state instead
+/// (`TogglePvP`). No ack; the flag arrives in `UNIT_FIELD_FLAGS`, and turning it off waits out
+/// the server's 300 s timer.
 pub const CMSG_TOGGLE_PVP: u16 = 0x0253; // 595
 
-/// The two **equipment-display** toggles — "show my helm" / "show my cloak" (VERIFIED vmangos
-/// `Opcodes_1_12_1.h`: 697/698, handlers `HandleShowingHelmOpcode`/`HandleShowingCloakOpcode` in
-/// `Handlers/CharacterHandler.cpp:753-761`). Both are **empty-bodied pure toggles**: the handler
-/// is a bare `ToggleFlag(PLAYER_FLAGS, PLAYER_FLAGS_HIDE_HELM | HIDE_CLOAK)` with no target-state
-/// form at all, unlike [`CMSG_TOGGLE_PVP`] above — so a client that wants a *specific* state must
-/// compare against the flag it already holds and send only on a difference.
-///
-/// No ack, exactly like the PvP toggle: the answer is the `PLAYER_FLAGS` bit arriving in the next
-/// descriptor update. That field is `UF_FLAG_PUBLIC` (vmangos `UpdateFields_1_12_1`), which is what
-/// makes the preference *everyone's* — a remote player's hidden helm hides on our screen too, off
-/// their own descriptor. The server round-trips the same preference through the char-enum record's
-/// `CHARACTER_FLAG_HIDE_HELM`/`HIDE_CLOAK` at load and save (`Player.cpp:14839-14842` /
-/// `16504-16505`), so the glue lane's flags and this one are the same stored bit (decision 1472).
+/// Toggle `PLAYER_FLAGS_HIDE_HELM`: an empty body and a pure toggle, so send only when the held
+/// flag differs (`CharacterHandler.cpp:753-761`). No ack; the public flag hides it for everyone.
 pub const CMSG_TOGGLE_HELM: u16 = 0x02B9; // 697
-/// The cloak half of [`CMSG_TOGGLE_HELM`] — same shape, `PLAYER_FLAGS_HIDE_CLOAK`.
+/// [`CMSG_TOGGLE_HELM`] for `PLAYER_FLAGS_HIDE_CLOAK`.
 pub const CMSG_TOGGLE_CLOAK: u16 = 0x02BA; // 698
 
-// The solo-loot wire family (VERIFIED vmangos `Opcodes_1_12_1.h`: 264, 349-355, 357-358).
-// Bodies in [`super::loot`].
 pub const CMSG_AUTOSTORE_LOOT_ITEM: u16 = 0x0108; // 264
 pub const CMSG_LOOT: u16 = 0x015D; // 349
 pub const CMSG_LOOT_MONEY: u16 = 0x015E; // 350
@@ -1274,24 +741,18 @@ pub const SMSG_LOOT_MONEY_NOTIFY: u16 = 0x0163; // 355
 pub const SMSG_LOOT_CLEAR_MONEY: u16 = 0x0165; // 357
 pub const SMSG_ITEM_PUSH_RESULT: u16 = 0x0166; // 358
 
-// The group-loot roll family (VERIFIED vmangos `Opcodes_1_12_1.h:671-675`) — the Need/Greed/Pass
-// flow the `GroupLootFrame`s drive when the group's loot method is group/need-before-greed and a
-// drop is at or above the quality threshold (decision 0591). Bodies in [`super::loot`].
+// Need/Greed/Pass rolls: group or need-before-greed loot on a drop at or above the threshold.
 pub const SMSG_LOOT_ALL_PASSED: u16 = 0x029E; // 670
 pub const SMSG_LOOT_ROLL_WON: u16 = 0x029F; // 671
 pub const CMSG_LOOT_ROLL: u16 = 0x02A0; // 672
 pub const SMSG_LOOT_START_ROLL: u16 = 0x02A1; // 673
 pub const SMSG_LOOT_ROLL: u16 = 0x02A2; // 674
 
-// Master loot (VERIFIED vmangos `Opcodes_1_12_1.h:676-677`) — the other answer to an
-// above-threshold drop: no roll, the master looter is handed the eligible-member list at
-// window-open and assigns each row from a dropdown (decision 1675). Bodies in [`super::loot`].
+// Master loot: no roll; the master looter gets the eligible members when the window opens.
 pub const CMSG_LOOT_MASTER_GIVE: u16 = 0x02A3; // 675
 pub const SMSG_LOOT_MASTER_LIST: u16 = 0x02A4; // 676
 
-// The death arc (decision 0308) — release/repop, corpse query, reclaim, spirit healer, resurrect
-// requests (all VERIFIED vmangos `Opcodes_1_12_1.h`: 346-348, 466, 534, 540, 546, 617). Bodies in
-// [`super::death`]. `CMSG_REPOP_REQUEST` and our `MSG_CORPSE_QUERY` request are EMPTY bodies.
+// Death: `CMSG_REPOP_REQUEST` and our `MSG_CORPSE_QUERY` request have empty bodies.
 pub const CMSG_REPOP_REQUEST: u16 = 0x015A; // 346
 pub const SMSG_RESURRECT_REQUEST: u16 = 0x015B; // 347
 pub const CMSG_RESURRECT_RESPONSE: u16 = 0x015C; // 348
@@ -1300,32 +761,15 @@ pub const MSG_CORPSE_QUERY: u16 = 0x0216; // 534
 pub const CMSG_SPIRIT_HEALER_ACTIVATE: u16 = 0x021C; // 540
 pub const SMSG_SPIRIT_HEALER_CONFIRM: u16 = 0x0222; // 546
 pub const SMSG_CORPSE_RECLAIM_DELAY: u16 = 0x0269; // 617
-/// Self-resurrect — the DEATH popup's soulstone/Reincarnation button (`UseSoulstone()`, decision
-/// 1746). **EMPTY body** (VERIFIED vmangos `Opcodes_1_12_1.h:692` = 691, handler
-/// `WorldSession::HandleSelfResOpcode(NullClientPacket const&)`, `SpellHandler.cpp:461`): the
-/// server casts whatever `PLAYER_SELF_RES_SPELL` holds on us and zeroes the field. There is no
-/// answer packet — the resurrection arrives as ordinary descriptor deltas, exactly like a reclaim.
+/// `UseSoulstone()`: empty body; the server casts our `PLAYER_SELF_RES_SPELL` and zeroes it
+/// (`SpellHandler.cpp:461`). No answer packet, only descriptor deltas.
 pub const CMSG_SELF_RES: u16 = 0x02B3; // 691
-/// Sent with the 10% durability loss a natural (non-PvP) death applies (VERIFIED vmangos
-/// `Opcodes_1_12_1.h` 701 + `Unit.cpp:1170-1182` — an EMPTY body; the client's cue for the red
-/// "Your equipped items suffer a 10%% durability loss." error line).
+/// A non-PvP death's 10% durability loss: empty body, a red error line (`Unit.cpp:1170-1182`).
 pub const SMSG_DURABILITY_DAMAGE_DEATH: u16 = 0x02BD; // 701
 
-// **The ack'd movement-mode family** — four granted mover modes, one wire shape (decision 0866).
-// This is not our grouping: the server names the set itself in `IsFlagAckOpcode`
-// (`Server/Protocol/Opcodes.h`) and routes all four through one sender
-// (`MovementPacketSender::AddMovementFlagChangeToController`, whose `MovementChangeType` is exactly
-// `{ROOT, WATER_WALK, SET_HOVER, FEATHER_FALL}`). Opcode numbers VERIFIED vmangos `Opcodes_1_1x.h`
-// (unchanged into 1.12.1) and cross-checked against the client's own name table
-// ([`super::opcode_names`]).
-//
-// **The wire shape is uniform.** The SMSG to the mover carries `packed guid + u32 counter`; the ack
-// echoes `full u64 guid + u32 counter + MovementInfo`, plus a trailing `u32 apply` for every mode
-// **except root** — the root ack lands on vmangos's `HandleMoveRootAck`, the other three on
-// `HandleMovementFlagChangeToggleAck`, which reads that extra dword
-// (`Server/Packets/Movement.cpp:38-59`). Un-acked changes never reach observers, and wrong/zero
-// counters trip the server's cheat log — the counter must be echoed. Modelled as
-// [`super::MoveMode`], whose docs carry what each flag does to the mover.
+// Mover modes, acked (`IsFlagAckOpcode`): the SMSG is a packed guid and `u32 counter`; the ack
+// echoes the full u64 guid, the counter and a `MovementInfo`, plus a `u32 apply` for all but root
+// (`Movement.cpp:38-59`). An unacked change never reaches observers.
 pub const SMSG_MOVE_WATER_WALK: u16 = 0x00DE; // 222
 pub const SMSG_MOVE_LAND_WALK: u16 = 0x00DF; // 223
 pub const CMSG_MOVE_WATER_WALK_ACK: u16 = 0x02D0; // 720
@@ -1340,38 +784,10 @@ pub const SMSG_MOVE_UNSET_HOVER: u16 = 0x00F5; // 245
 pub const CMSG_MOVE_HOVER_ACK: u16 = 0x00F6; // 246
 pub const CMSG_MOVE_FEATHER_FALL_ACK: u16 = 0x02CF; // 719
 
-// **The OBSERVER leg of that same family** — what everyone *else* is told once the mover acks
-// (decision 2061). The ack'd family above and the `SMSG_SPLINE_MOVE_*` twelve below are only two
-// of the three legs, and this is the one that was missing: `SMSG_SPLINE_MOVE_*` reaches a unit the
-// **server** drives (a creature), and the ack'd leg reaches only the mover's **own** client — so a
-// *player* being rooted, levitated or blinked had no leg at all, and every such change was invisible
-// until that player's next ordinary pose packet.
-//
-// vmangos names the three legs itself, in one table (`Movement/MovementPacketSender.h:30-60`):
-// `{ SMSG_FORCE_MOVE_ROOT → CMSG_FORCE_MOVE_ROOT_ACK → MSG_MOVE_ROOT }` and its three siblings,
-// plus `{ MSG_MOVE_TELEPORT_ACK → MSG_MOVE_TELEPORT_ACK → MSG_MOVE_TELEPORT }`. `SendMovementFlagChange
-// ToObservers` / `SendTeleportToObservers` (`MovementPacketSender.cpp:221-239`, `:368-397`) write
-// `[packed guid][MovementInfo]` and stop — **the ordinary relay shape**, decoded by
-// [`super::parse`]'s relay arm like a heartbeat.
-//
-// **The client agrees they are one family.** All six register the *same* handler as the 22 relay
-// opcodes we already carry — `0x603bb0` (wow-re `re/net/opcode-handlers.tsv`; 30 rows, one handler),
-// which reads a packed guid, resolves it under `TYPEMASK_UNIT` and hands the body to
-// `OnUnitMoveEvent 0x601580`. There is nothing to ack: the ack already happened, on the mover's own
-// client.
-//
-// **Apply/unapply is in the flags word, not the opcode.** Only root splits into two opcodes; hover,
-// feather-fall and water-walk each use ONE for both directions, because the server has already
-// written the bit into the `m_movementInfo` it is about to broadcast (`SetHoverReal` &co. run
-// *before* the send, `Handlers/MovementHandler.cpp:626-638`/`:743-744`). So the receiver folds the
-// whole word and asks nothing of the opcode — which is what our relay arm already does.
-//
-// **`MSG_MOVE_TELEPORT` carries no counter** (unlike `MSG_MOVE_TELEPORT_ACK`, 0x00C7, whose
-// `[packed guid][u32 counter][MovementInfo]` is the *mover's* handshake): an observer has nothing to
-// ack, so the dword isn't there. It is sent **twice** per near-teleport — once before the relocation
-// and once after (`Player::ExecuteTeleportNear`) — so observers around both the old and the new
-// position hear it; both carry the destination, so applying both is idempotent. It is also how a
-// **creature** blink arrives (`Unit::NearTeleportTo`, which `DisableSpline()`s first).
+// The observers' leg of those modes and of teleports (`MovementPacketSender.h:30-60`): the relay
+// shape `[packed guid][MovementInfo]`, handled like the relay opcodes (`0x603bb0`). Only root has
+// two opcodes; apply is in the flags word. `MSG_MOVE_TELEPORT` has no counter and comes twice per
+// near teleport, both with the destination; a creature blink arrives the same way.
 pub const MSG_MOVE_TELEPORT: u16 = 0x00C5; // 197
 pub const MSG_MOVE_ROOT: u16 = 0x00EC; // 236
 pub const MSG_MOVE_UNROOT: u16 = 0x00ED; // 237
@@ -1379,78 +795,32 @@ pub const MSG_MOVE_HOVER: u16 = 0x00F7; // 247
 pub const MSG_MOVE_FEATHER_FALL: u16 = 0x02B0; // 688
 pub const MSG_MOVE_WATER_WALK: u16 = 0x02B1; // 689
 
-// **The knockback handshake** — the server aims a launch at our own mover, the mover flies it, and
-// the ack is what the server relays onward (decision 1702). Numbers VERIFIED vmangos
-// `Opcodes_1_11_2.h:242-244` (unchanged into 1.12.1) and cross-checked against the client's own name
-// table ([`super::opcode_names`]).
-//
-// **The shape.** `SMSG_MOVE_KNOCK_BACK` carries `packed guid + u32 counter + f32 vcos + f32 vsin +
-// f32 speedXY + f32 speedZ` (vmangos `MovementPacketSender::SendKnockBackToController`, the
-// `> CLIENT_BUILD_1_9_4` branch that carries the counter). Those last four floats are a
-// [`super::JumpInfo`] in a different field order — the same launch quad, and that is not a
-// coincidence: the ack must echo them back as the `MovementInfo` **jump tail**, which is why
-// `speedZ` rides the jump tail's **down-positive** convention (vmangos negates the caller's
-// upward `verticalSpeed` on the way out, with the source comment "!! notice the - sign in front of
-// speedZ !!").
-//
-// **The ack is mandatory and checked value-by-value.** `CMSG_MOVE_KNOCK_BACK_ACK` is
-// `full u64 guid + u32 counter + MovementInfo` (`Server/Packets/Movement.cpp:61-68` — the same
-// shape as the movement-mode family's ack minus its trailing `apply` dword), and
-// `Unit::FindPendingMovementKnockbackChange` refuses it unless the counter matches **and** all four
-// jump-tail floats are within `0.01` of what was sent — so `MOVEFLAG_JUMPING` must be set and the
-// tail must be the launch quad. A mismatched ack is `OnWrongAckData`; a missing one is
-// `OnFailedToAckChange` (a knockback is the one pending change the server will not re-send,
-// `Unit.cpp:6887`). The ack is also the observers' packet: the server answers it with
-// `MSG_MOVE_KNOCK_BACK` built from the `MovementInfo` we sent.
+// Knockback. `SMSG_MOVE_KNOCK_BACK` to the mover: packed guid, `u32 counter`, `f32` vcos, vsin,
+// speedXY, speedZ, with speedZ down-positive like the jump tail. The mandatory ack is full u64
+// guid, counter, `MovementInfo`, whose jump tail must echo the four floats within 0.01 with
+// `MOVEFLAG_JUMPING` set; a knockback is never re-sent (`Unit.cpp:6887`). Observers get
+// `MSG_MOVE_KNOCK_BACK`: the relay shape plus the four floats, re-launched by `0x6026f0`.
 pub const SMSG_MOVE_KNOCK_BACK: u16 = 0x00EF; // 239
 pub const CMSG_MOVE_KNOCK_BACK_ACK: u16 = 0x00F0; // 240
-                                                  //
-                                                  // **And the observers hear it — `MSG_MOVE_KNOCK_BACK` is NOT dead** (decision 1702, correcting
-                                                  // decision 0277's "no observer-side knockback signal exists in 1.12 at all"). The reference
-                                                  // registers `0xF1` at its own dispatch entry `0x603bb0`, which reaches `CGUnit_C::OnKnockBack`
-                                                  // `0x6026f0` — it reads the four floats *after* a full `MovementInfo` and re-launches the unit
-                                                  // locally through the very same `0x6179c0` the controller's own knockback uses, acking nothing.
-                                                  // That body (`packed guid + MovementInfo + vcos + vsin + speedXY + speedZ`) is exactly what vmangos
-                                                  // sends (`SendKnockBackToObservers`), and its leading `[packed guid][MovementInfo]` is the ordinary
-                                                  // relay shape — the launch quad also rides that `MovementInfo`'s own jump tail, so a receiver that
-                                                  // replays the relayed arc reproduces the re-launch without reading the trailing four.
 pub const MSG_MOVE_KNOCK_BACK: u16 = 0x00F1; // 241
 
-// The social family — the friend list, the ignore list, and `/who` (VERIFIED vmangos
-// `Opcodes_1_12_1.h` + `Server/Packets/Social.{h,cpp}`, `Handlers/MiscHandler.cpp`,
-// `SocialMgr.{h,cpp}`; client side wow-re's `FriendList.cpp` TU, `system/net/scratch/w2b.md`).
-// Bodies in [`super::social`]; decision 0668.
 pub const CMSG_WHO: u16 = 0x0062; // 98
 pub const SMSG_WHO: u16 = 0x0063; // 99
 pub const CMSG_FRIEND_LIST: u16 = 0x0066; // 102
 pub const SMSG_FRIEND_LIST: u16 = 0x0067; // 103
 pub const SMSG_FRIEND_STATUS: u16 = 0x0068; // 104
 pub const CMSG_ADD_FRIEND: u16 = 0x0069; // 105
-/// The client's LFG slots and comment (wow-re `lfg-set-get-law.md`: written into a `CDataStore`
-/// at exactly one site image-wide, `0x4e8948`; no registered handler answers it). The name is
-/// the emulators' — the value and its site are the bytes'.
+/// Our LFG slots and comment, sent only from `0x4e8948`; nothing answers it. The name is the
+/// emulators'.
 pub const CMSG_SET_LOOKING_FOR_GROUP: u16 = 0x0200; // 512
 pub const CMSG_DEL_FRIEND: u16 = 0x006A; // 106
 pub const SMSG_IGNORE_LIST: u16 = 0x006B; // 107
 pub const CMSG_ADD_IGNORE: u16 = 0x006C; // 108
 pub const CMSG_DEL_IGNORE: u16 = 0x006D; // 109
 
-// The guild family — the query/roster caches, invitations, the member verbs, rank administration
-// and the event broadcast (VERIFIED vmangos `Opcodes_1_12_1.h:87-88`, `:132-151`, `:562-566`,
-// `:765` + `Server/Packets/Guild.{h,cpp}`, `Guild/Guild.{h,cpp}`, `Handlers/GuildHandler.cpp`; the
-// client side of `SMSG_GUILD_EVENT` is wow-re's RF-0077,
-// `system/object-layer/scratch/rf77-smsg-chat-wire-order.md`, which pins handler `0x5e7180` to
-// this 0x92 and reads its guild-init registration/teardown block). Bodies in [`super::guild`].
-//
-// The numbers are two contiguous runs plus two strays: the query pair sits with the other ask-once
-// caches at 0x54/0x55, the core family runs 0x81-0x93 immediately after the group family, rank
-// administration was appended at 0x231-0x235, and the guild info text at 0x2FC. The
-// charter/petition opcodes that *found* a guild are their own family, below; the tabard
-// opcodes that dress one are not built.
 pub const CMSG_GUILD_QUERY: u16 = 0x0054; // 84
 pub const SMSG_GUILD_QUERY_RESPONSE: u16 = 0x0055; // 85
-/// vmangos registers this `STATUS_NEVER` (`Opcodes.cpp:210`): at 1.12 a guild is founded through
-/// the charter/petition flow, not by this packet. Modelled for completeness; no reply comes back.
+/// Never handled (`STATUS_NEVER`, `Opcodes.cpp:210`): 1.12 guilds are founded by petition.
 pub const CMSG_GUILD_CREATE: u16 = 0x0081; // 129
 pub const CMSG_GUILD_INVITE: u16 = 0x0082; // 130
 pub const SMSG_GUILD_INVITE: u16 = 0x0083; // 131
@@ -1460,8 +830,8 @@ pub const SMSG_GUILD_DECLINE: u16 = 0x0086; // 134
 pub const CMSG_GUILD_INFO: u16 = 0x0087; // 135
 pub const SMSG_GUILD_INFO: u16 = 0x0088; // 136
 pub const CMSG_GUILD_ROSTER: u16 = 0x0089; // 137
-/// The widest packet in the game — the sender truncates its member list to `0x8000 - 4` bytes —
-/// and the one conditional-field trap in the family: see [`super::guild::read_guild_roster`].
+/// The roster, cut by the sender at `0x8000 - 4` bytes; one field is conditional (see
+/// `super::guild::read_guild_roster`).
 pub const SMSG_GUILD_ROSTER: u16 = 0x008A; // 138
 pub const CMSG_GUILD_PROMOTE: u16 = 0x008B; // 139
 pub const CMSG_GUILD_DEMOTE: u16 = 0x008C; // 140
@@ -1479,44 +849,25 @@ pub const CMSG_GUILD_SET_PUBLIC_NOTE: u16 = 0x0234; // 564
 pub const CMSG_GUILD_SET_OFFICER_NOTE: u16 = 0x0235; // 565
 pub const CMSG_GUILD_INFO_TEXT: u16 = 0x02FC; // 764
 
-// The petition family — the guild-charter flow that FOUNDS a guild (VERIFIED vmangos
-// `Opcodes_1_12_1.h:444-456`, `:705-706` + `Server/Packets/Petition.{h,cpp}`,
-// `Handlers/PetitionsHandler.cpp`; the handler table is `Opcodes.cpp:528-540` and `:800-801`).
-// Bodies in [`super::petition`]; decision 1672.
-//
-// Two shapes to know. The three `MSG_` opcodes are genuinely bidirectional with *different*
-// bodies each way — decline sends an item guid and receives a player guid — so each has its own
-// reader and its own builder rather than one shared body. And `MSG_DELETE_GUILD_CHARTER` (0x2C0)
-// is deliberately **absent**: vmangos registers it `INVALID_PACKET(…, Unhandled)`
-// (`Opcodes.cpp:800`) and has no handler at all, because destroying a charter runs through the
-// ordinary item-destroy path, which cascades into deleting the petition (`Player.cpp:10811-10817`,
-// `Item.cpp:515-516`). Declaring it would model traffic that nothing on either end sends.
 pub const CMSG_PETITION_SHOWLIST: u16 = 0x01BB; // 443
 pub const SMSG_PETITION_SHOWLIST: u16 = 0x01BC; // 444
 pub const CMSG_PETITION_BUY: u16 = 0x01BD; // 445
 pub const CMSG_PETITION_SHOW_SIGNATURES: u16 = 0x01BE; // 446
-/// The answer to **two** different asks — our own `CMSG_PETITION_SHOW_SIGNATURES`, and someone
-/// else's `CMSG_OFFER_PETITION` aimed at us. Only its `owner` field tells the two apart.
+/// Answers our `CMSG_PETITION_SHOW_SIGNATURES` and another player's `CMSG_OFFER_PETITION` alike;
+/// only `owner` tells them apart.
 pub const SMSG_PETITION_SHOW_SIGNATURES: u16 = 0x01BF; // 447
 pub const CMSG_PETITION_SIGN: u16 = 0x01C0; // 448
 pub const SMSG_PETITION_SIGN_RESULTS: u16 = 0x01C1; // 449
-/// Bidirectional with different bodies: we send the charter **item's** guid, the owner receives
-/// the declining **player's** guid.
+/// Both ways, different bodies: we send the charter item's guid, the owner gets the decliner's.
 pub const MSG_PETITION_DECLINE: u16 = 0x01C2; // 450
 pub const CMSG_OFFER_PETITION: u16 = 0x01C3; // 451
 pub const CMSG_TURN_IN_PETITION: u16 = 0x01C4; // 452
 pub const SMSG_TURN_IN_PETITION_RESULTS: u16 = 0x01C5; // 453
 pub const CMSG_PETITION_QUERY: u16 = 0x01C6; // 454
 pub const SMSG_PETITION_QUERY_RESPONSE: u16 = 0x01C7; // 455
-/// Bidirectional, and here the two bodies agree: `u64 item` + the new name, both ways. The echo
-/// comes back only on success.
+/// Both ways, one body: `u64 item` and the new name; echoed back only on success.
 pub const MSG_PETITION_RENAME: u16 = 0x02C1; // 705
 
-// The group/party family — invite/accept/decline/kick/leader/disband, the loot-method setting, the
-// roster push (`SMSG_GROUP_LIST`), party command feedback, live member stats for the party/raid
-// frame, minimap pings, raid subgroup management, raid-target icons, and ready checks (VERIFIED
-// vmangos `Opcodes_1_12_1.h` + `Server/Packets/Group.{h,cpp}`, `Handlers/GroupHandler.cpp`,
-// `Group/Group.{h,cpp}`). Bodies in [`super::group`].
 pub const CMSG_GROUP_INVITE: u16 = 0x006E; // 110
 pub const SMSG_GROUP_INVITE: u16 = 0x006F; // 111
 pub const CMSG_GROUP_ACCEPT: u16 = 0x0072; // 114
@@ -1533,10 +884,7 @@ pub const SMSG_GROUP_DESTROYED: u16 = 0x007C; // 124
 pub const SMSG_GROUP_LIST: u16 = 0x007D; // 125
 pub const SMSG_PARTY_MEMBER_STATS: u16 = 0x007E; // 126
 pub const SMSG_PARTY_COMMAND_RESULT: u16 = 0x007F; // 127
-/// Same opcode both directions (VERIFIED vmangos `Group.cpp:33-37` client read, `Handlers/
-/// GroupHandler.cpp:382-391` server rebroadcast): the client's own ping carries no guid, the
-/// server stamps ours on before relaying to the rest of the group (see
-/// [`super::group::minimap_ping`] / the parse arm).
+/// Both ways: our ping has no guid; the server adds ours and relays it (`GroupHandler.cpp:382`).
 pub const MSG_MINIMAP_PING: u16 = 0x01D5; // 469
 pub const CMSG_GROUP_CHANGE_SUB_GROUP: u16 = 0x027E; // 638
 pub const CMSG_REQUEST_PARTY_MEMBER_STATS: u16 = 0x027F; // 639
@@ -1544,28 +892,17 @@ pub const CMSG_GROUP_SWAP_SUB_GROUP: u16 = 0x0280; // 640
 pub const CMSG_GROUP_RAID_CONVERT: u16 = 0x028E; // 654
 pub const CMSG_GROUP_ASSISTANT_LEADER: u16 = 0x028F; // 655
 pub const SMSG_PARTY_MEMBER_STATS_FULL: u16 = 0x02F2; // 754
-/// Same opcode both directions, mode-prefixed shapes on the server's side (VERIFIED vmangos
-/// `Server/Packets/Group.cpp:77-82` client read, `:132-147` server write; see
-/// [`super::group::RaidTargetUpdate`]).
+/// Both ways; the server's side is mode-prefixed (`Group.cpp:77-82` read, `:132-147` write).
 pub const MSG_RAID_TARGET_UPDATE: u16 = 0x0321; // 801
-/// Same opcode both directions — an empty body starts/requests, a non-empty one answers (VERIFIED
-/// vmangos `Server/Packets/Group.cpp:84-96`, `:126-130`; see [`super::group::ReadyCheck`]).
+/// Both ways: an empty body starts a check, a non-empty one answers (`Group.cpp:84-96`).
 pub const MSG_RAID_READY_CHECK: u16 = 0x0322; // 802
-/// Ask the server for our saved-instance (raid lockout) list — empty body (VERIFIED vmangos
-/// `Server/Protocol/Opcodes.cpp` registers it against `HandleRequestRaidInfoOpcode`, which is a
-/// bare `SendRaidInfo()`). The RaidFrame's `RequestRaidInfo()` on every OnShow (decision 1549).
+/// Ask for our raid lockouts: empty body, sent by `RequestRaidInfo()` on every RaidFrame show.
 pub const CMSG_REQUEST_RAID_INFO: u16 = 0x02CD; // 717
-/// The answer: `u32 count` then `count` × `{u32 mapId, u32 secondsUntilReset, u32 instanceId}`
-/// (VERIFIED vmangos `Objects/Player.cpp::Player::SendRaidInfo`, permanent binds only; see
-/// [`super::group::read_raid_instance_info`]).
+/// Our permanent binds: `u32 count`, count × `{u32 mapId, u32 secondsUntilReset, u32 instanceId}`.
 pub const SMSG_RAID_INSTANCE_INFO: u16 = 0x02CC; // 716
 
-// The duel family (decision 0633) — the six inbound handlers WoW.exe registers in
-// `Ui/DuelInfo.cpp` at `0x4d4710` plus the two it sends from `AcceptDuel 0x4d4830` /
-// `CancelDuel 0x4d48b0`; server side VERIFIED vmangos `Server/Packets/Duel.{h,cpp}` +
-// `Handlers/DuelHandler.cpp`. There is no CMSG for *starting* a duel: the challenge is a normal
-// `CMSG_CAST_SPELL` of the spellbook spell whose `Effect[0]` is `SPELL_EFFECT_DUEL` (83).
-// Bodies in [`super::duel`].
+// Duels (reference handlers registered at `0x4d4710`). A challenge is a `CMSG_CAST_SPELL` of the
+// `SPELL_EFFECT_DUEL` (83) spell; there is no opcode to start one.
 pub const SMSG_DUEL_REQUESTED: u16 = 0x0167; // 359
 pub const SMSG_DUEL_OUTOFBOUNDS: u16 = 0x0168; // 360
 pub const SMSG_DUEL_INBOUNDS: u16 = 0x0169; // 361
@@ -1573,118 +910,84 @@ pub const SMSG_DUEL_COMPLETE: u16 = 0x016A; // 362
 pub const SMSG_DUEL_WINNER: u16 = 0x016B; // 363
 pub const CMSG_DUEL_ACCEPTED: u16 = 0x016C; // 364
 pub const CMSG_DUEL_CANCELLED: u16 = 0x016D; // 365
-/// Milliseconds, not seconds — the client divides by 1000 (`0x4d4aef`). Live on 5875 despite the
-/// opcode's high number: `0x4d474a` registers a handler for it alongside the 0x167 block.
+/// The duel countdown in milliseconds; the client divides by 1000 (`0x4d4aef`). Registered with
+/// the 0x167 block (`0x4d474a`) despite its number.
 pub const SMSG_DUEL_COUNTDOWN: u16 = 0x02B7; // 695
 
-// The mirror timers — breath / fatigue / feign-death (decision 0874; VERIFIED vmangos
-// `Opcodes_1_12_1.h:474-476` + `Server/Packets/Misc.{h,cpp}`). Server-authoritative countdowns the
-// client only mirrors and integrates; the family has no CMSG and no separate "update" opcode — a
-// running timer that changes anything is re-sent as a whole START. Bodies in
-// [`super::mirror_timer`].
+// Mirror timers (breath, fatigue, feign death): server countdowns; any change re-sends a START.
 pub const SMSG_START_MIRROR_TIMER: u16 = 0x01D9; // 473
-/// Never sent by vmangos, on purpose (`Player::SendMirrorTimers` substitutes a full START and says
-/// why in the source): the shipped 1.12 `MirrorTimer.lua` handler reads the same `arg1` as both a
-/// timer name and a number, so a real pause packet errors out in the reference UI. Decoded anyway.
+/// Never sent by vmangos, which re-sends a START instead: the stock `MirrorTimer.lua` errors on
+/// a real pause (`Player::SendMirrorTimers`).
 pub const SMSG_PAUSE_MIRROR_TIMER: u16 = 0x01DA; // 474
 pub const SMSG_STOP_MIRROR_TIMER: u16 = 0x01DB; // 475
 
-// The mail arc (decision 0544; VERIFIED vmangos `Opcodes_1_12_1.h` + `Handlers/MailHandler.cpp`).
-// There is no `SMSG_SHOW_MAILBOX` on 5875 — the mailbox window opens entirely client-side; every
-// CMSG below carries the mailbox guid at its head, and the server independently re-validates the
-// 5 yd interact distance (`CheckMailBox`) on each one. Bodies in [`super::mail`].
+// Mail opens client-side; every CMSG leads with the mailbox guid, checked at 5 yd (`CheckMailBox`).
 pub const CMSG_SEND_MAIL: u16 = 0x0238; // 568
 pub const SMSG_SEND_MAIL_RESULT: u16 = 0x0239; // 569
 pub const CMSG_GET_MAIL_LIST: u16 = 0x023A; // 570
 pub const SMSG_MAIL_LIST_RESULT: u16 = 0x023B; // 571
-/// Letter bodies never ride the list inline — the client fetches them ask-once by `itemTextId`.
+/// A letter's text, fetched ask-once by `itemTextId`; the mail list never carries it.
 pub const CMSG_ITEM_TEXT_QUERY: u16 = 0x0243; // 579
 pub const SMSG_ITEM_TEXT_QUERY_RESPONSE: u16 = 0x0244; // 580
 pub const CMSG_MAIL_TAKE_MONEY: u16 = 0x0245; // 581
 pub const CMSG_MAIL_TAKE_ITEM: u16 = 0x0246; // 582
-/// No response packet — the app flips the local `checked` READ bit and repaints.
+/// No response; the client sets the letter's read bit itself.
 pub const CMSG_MAIL_MARK_AS_READ: u16 = 0x0247; // 583
 pub const CMSG_MAIL_RETURN_TO_SENDER: u16 = 0x0248; // 584
 pub const CMSG_MAIL_DELETE: u16 = 0x0249; // 585
 pub const CMSG_MAIL_CREATE_TEXT_ITEM: u16 = 0x024A; // 586
-/// Same opcode both directions (VERIFIED vmangos `Opcodes_1_12_1.h`: 644): our request is an EMPTY
-/// body; the reply (same opcode) is one `f32` — `0.0` unread mail waiting, `-86400.0` none.
+/// Both ways: an empty request; the reply is one `f32`, `0.0` for unread mail, `-86400.0` none.
 pub const MSG_QUERY_NEXT_MAIL_TIME: u16 = 0x0284; // 644
-/// One `u32` (always 0) — sent when a mail *arrives* (instant for text-only, on the delivery
-/// timer's expiry otherwise).
+/// A mail arrived (text-only at once, else when its delivery timer ends): one `u32`, always 0.
 pub const SMSG_RECEIVED_MAIL: u16 = 0x0285; // 645
 
-// The auction house arc (decision 1511 P0; VERIFIED vmangos `Opcodes_1_12_1.h`: 597-607, 612-613,
-// 653 — every value re-read against that table). Bodies in [`super::auction`]. Two family facts
-// belong here: **there is no `*_LIST_PENDING_SALES` on 5875** — the symbol exists in no vmangos
-// opcode table at all, so the pending-sales pane is a later client's and has no wire to build —
-// and every CMSG below carries the auctioneer guid at its head because the server re-validates
-// the 5 yd interact distance on each one independently; the hello is not a session token.
-/// Same opcode both directions (597): our request is one auctioneer guid; the reply echoes it and
-/// adds `u32 houseId` (`AuctionHouse.dbc`, rows 1..7, which carries the deposit/cut rates). It is
-/// the **reply** that opens the window, not our send.
+// The auction house: every CMSG leads with the auctioneer guid, and the server checks 5 yd on
+// each, so the hello is no session token.
+/// Both ways: we send the auctioneer guid; the reply echoes it with `u32 houseId`
+/// (`AuctionHouse.dbc` 1..7) and opens the window.
 pub const MSG_AUCTION_HELLO: u16 = 0x0255; // 597
 pub const CMSG_AUCTION_SELL_ITEM: u16 = 0x0256; // 598
 pub const CMSG_AUCTION_REMOVE_ITEM: u16 = 0x0257; // 599
-/// The Browse search — ten fields and **no sort bytes** on 5875: filtering is server-side,
-/// sorting entirely client-side ([`super::auction::auction_list_items`]).
+/// The Browse search: ten fields and no sort bytes; the server filters, the client sorts.
 pub const CMSG_AUCTION_LIST_ITEMS: u16 = 0x0258; // 600
 pub const CMSG_AUCTION_LIST_OWNER_ITEMS: u16 = 0x0259; // 601
-/// Bid *and* buy out: buyout is inferred from the price (`price >= buyout && buyout != 0`), never
-/// flagged, and there is no separate opcode for it.
+/// Bid or buy out: a buyout is `price >= buyout && buyout != 0`, never flagged.
 pub const CMSG_AUCTION_PLACE_BID: u16 = 0x025A; // 602
-/// The one verdict opcode for sell/cancel/bid, with a conditional tail keyed on its error
-/// ([`super::auction::AuctionCommandTail`]). Several refusals send **nothing at all** instead.
+/// The sell, cancel or bid verdict, with a tail keyed on its error; some refusals send nothing.
 pub const SMSG_AUCTION_COMMAND_RESULT: u16 = 0x025B; // 603
-/// This and the two list results below share ONE frame and ONE 64-byte record layout
-/// ([`super::auction::read_auction_list_result`]): `u32 count`, the records, then `u32 totalCount`
-/// at the very end — the match count *before* the 50-row page cap.
+/// Shared with the owner and bidder list results: `u32 count`, 64-byte records, then
+/// `u32 totalCount`, the matches before the 50-row page cap.
 pub const SMSG_AUCTION_LIST_RESULT: u16 = 0x025C; // 604
 pub const SMSG_AUCTION_OWNER_LIST_RESULT: u16 = 0x025D; // 605
-/// Pushed to the bidder: won, or outbid — `bidOrZero == 0` means **won**, not "no bid".
+/// To the bidder, won or outbid: `bidOrZero == 0` means won, not "no bid".
 pub const SMSG_AUCTION_BIDDER_NOTIFICATION: u16 = 0x025E; // 606
-/// Pushed to the seller. A **different field order** from the bidder notification, and no
-/// `houseId`; the two never share a struct or a reader.
+/// To the seller: a different field order from the bidder notification, and no `houseId`.
 pub const SMSG_AUCTION_OWNER_NOTIFICATION: u16 = 0x025F; // 607
 pub const CMSG_AUCTION_LIST_BIDDER_ITEMS: u16 = 0x0264; // 612
 pub const SMSG_AUCTION_BIDDER_LIST_RESULT: u16 = 0x0265; // 613
 /// Pushed to a bidder whose auction the seller cancelled.
 pub const SMSG_AUCTION_REMOVED_NOTIFICATION: u16 = 0x028D; // 653
 
-// The world-state table (VERIFIED both ways: vmangos `Opcodes_1_12_1.h` 706-707, and wow-re's read
-// of the reference's own handler `0x48f690`, whose registration at `0x48f515-0x48f52f` selects these
-// two arms as the ONLY writers of the table setter `0x4c5870`). Bodies in
-// [`super::world_state`]. Backs the NPC-text `$<n>w`/`$<n>e` tokens today; the BG/PvP scoreboard
-// later.
+// The world-state table; these two are its only writers (reference `0x48f690`). NPC text's
+// `$<n>w`/`$<n>e` tokens read it.
 pub const SMSG_INIT_WORLD_STATES: u16 = 0x02C2; // 706
 pub const SMSG_UPDATE_WORLD_STATE: u16 = 0x02C3; // 707
 
-// ── The instance/raid lockout family (decision 1748) ──────────────────────────────────────────
-//
-// The five inbound handlers WoW.exe registers together at `0x498680`-`0x4986cf`, plus the
-// save-created one registered apart at `0x4e7e48`, plus the one thing the player can ask for.
-// Bodies (and the client's own read order) in [`super::instance`]; server side VERIFIED vmangos
-// `Server/Packets/Misc.{h,cpp}` + `Maps/Map.cpp`.
+// ── Instance and raid lockouts ──
 
-/// "You are now saved to this instance" (`u32` flag; handler `0x4e7e60`). vmangos always sends
-/// `0`; the client's `== 1` arm wraps the same string in a `"(Debug-Only Lock Notice) %s"`
-/// literal, and anything ≥ 2 prints an uninitialized buffer (a real 1.12 bug — we print nothing).
+/// "You are now saved to this instance": a `u32` flag, 0 from vmangos (`0x4e7e60`; 1 adds a debug
+/// prefix). Deviation: 2 or more prints nothing; the reference prints an uninitialized buffer.
 pub const SMSG_INSTANCE_SAVE_CREATED: u16 = 0x02CB; // 715
-/// The raid-lockout welcome/countdown line: `u32 type`, `u32 mapId`, `u32 secondsUntilReset`
-/// (handler `0x49e1c0`; the four types in [`super::instance::RaidInstanceWarning`]).
+/// A raid-lockout warning: `u32 type`, `u32 mapId`, `u32 secondsUntilReset` (`0x49e1c0`).
 pub const SMSG_RAID_INSTANCE_MESSAGE: u16 = 0x02FA; // 762
-/// "Reset all instances" — empty body (the `ResetInstances` binding `0x48a6b0`; vmangos
-/// `HandleResetInstancesOpcode`).
+/// "Reset all instances": empty body (`ResetInstances`, `0x48a6b0`).
 pub const CMSG_RESET_INSTANCES: u16 = 0x031D; // 797
-/// "%s has been reset." — `u32 mapId` (handler `0x49e470`, which also clears the last-instance
-/// latch `0x495d00` *before* reading the body).
+/// "%s has been reset.": `u32 mapId`; `0x49e470` clears the last-instance latch before reading it.
 pub const SMSG_INSTANCE_RESET: u16 = 0x031E; // 798
-/// The reset refusal: `u32 reason`, `u32 mapId` (handler `0x49e540`; the three reasons in
-/// [`super::instance::InstanceResetFailure`]).
+/// The reset refusal: `u32 reason`, `u32 mapId` (`0x49e540`).
 pub const SMSG_INSTANCE_RESET_FAILED: u16 = 0x031F; // 799
-/// The dungeon we were last in: `u32 mapId` (handler `0x49e670` → `0x495d10`). Shows no line —
-/// it is half of what `CanShowResetInstances()` reads.
+/// The dungeon we were last in: `u32 mapId` (`0x49e670`), half of what
+/// `CanShowResetInstances()` reads; it shows no line.
 pub const SMSG_UPDATE_LAST_INSTANCE: u16 = 0x0320; // 800
-/// Whether we hold any permanent bind: `u32` flag (handler `0x49e6c0` → `0x495d50`). The other
-/// half of `CanShowResetInstances()`.
+/// Whether we hold any permanent bind: `u32` flag (`0x49e6c0`), half of `CanShowResetInstances()`.
 pub const SMSG_UPDATE_INSTANCE_OWNERSHIP: u16 = 0x032B; // 811
diff --git a/crates/benilla-protocol/src/messages/opcode_names.rs b/crates/benilla-protocol/src/messages/opcode_names.rs
index 39bef30c..63300259 100644
--- a/crates/benilla-protocol/src/messages/opcode_names.rs
+++ b/crates/benilla-protocol/src/messages/opcode_names.rs
@@ -1,5 +1,5 @@
-//! The full 1.12.1 world-opcode name table — **generated** from vmangos
-//! `Server/Protocol/Opcodes_1_12_1.h` (825 entries, deduped by number, sorted):
+//! Every 1.12.1 world opcode's name, generated from vmangos `Server/Protocol/Opcodes_1_12_1.h`
+//! (825 entries, deduped by number, sorted):
 //!
 //! ```sh
 //! sed -nE 's/^[[:space:]]+([A-Z_0-9]+)[[:space:]]*=[[:space:]]*([0-9]+),.*/\2 \1/p' \
@@ -7,13 +7,9 @@
 //!   | awk '!seen[$1]++ {printf "    (0x%04X, \"%s\"),\n", $1, $2}'
 //! ```
 //!
-//! The 1.12.1 wire is frozen, so this table can never go stale. It exists for the
-//! *instruments* — naming an opcode in the dropped-packet tally (the debug panel's
-//! wire-coverage gap detector) and in skip logs — never for dispatch (that's
-//! [`super::opcode`]'s explicitly-verified constants).
+//! For diagnostics only (the dropped-packet tally, skip logs); dispatch uses [`super::opcode`].
 
-/// Look up the canonical 1.12.1 name of a world opcode (either direction), if the number is
-/// assigned at all. O(log n) over the sorted table.
+/// The 1.12.1 name of a world opcode in either direction, by binary search of the sorted table.
 pub fn opcode_name(opcode: u16) -> Option<&'static str> {
     NAMES
         .binary_search_by_key(&opcode, |&(n, _)| n)
diff --git a/crates/benilla-protocol/src/messages/packet.rs b/crates/benilla-protocol/src/messages/packet.rs
index fb23212e..b1285ac3 100644
--- a/crates/benilla-protocol/src/messages/packet.rs
+++ b/crates/benilla-protocol/src/messages/packet.rs
@@ -1,6 +1,4 @@
-//! The decoded [`ServerPacket`] — one variant per server opcode benilla models, with the wire
-//! provenance on each, plus the logging [`ServerPacket::name`]. The opcode→variant dispatch lives
-//! in the sibling `parse` module; the per-domain payload readers in the domain children.
+//! [`ServerPacket`]: one variant per server opcode benilla decodes, plus its logging name.
 
 use crate::wire::Vector3d;
 
@@ -23,76 +21,54 @@ use super::{
     VendorItem, WhoResults, XpGain,
 };
 
-/// The **final facing** a `SMSG_MONSTER_MOVE` dictates (its `moveType`): the unit snaps to face this
-/// when the move is applied — the real client stores it straight into the unit's movement facing, a
-/// hard snap, not a smooth turn (wow-re object-layer: `0x6018f0` → `0x7c6f30 mov [esi+0x1c],eax`).
-/// This is how a creature re-orients without walking (a scripted/emote/aggro face), and benilla used
-/// to **discard** it (the "mob won't turn to face me" gap). `Angle` is a raw WoW orientation; `Spot`
-/// / `Target` resolve to an angle in the app (atan2 from the unit to the point, or to the target
-/// unit's live position — the client snapshots the target's position at receipt, it doesn't track).
+/// The final facing a `SMSG_MONSTER_MOVE` dictates (`moveType`), applied as a hard snap, not a
+/// turn (`0x6018f0`); `Spot` and `Target` resolve once, from positions at receipt.
 #[derive(Debug, Clone, Copy)]
 pub enum MonsterMoveFacing {
-    /// A plain move (`moveType` 0) or a stop — no dictated facing; the unit faces its travel direction.
+    /// `moveType` 0 or a stop: the unit faces its travel direction.
     None,
-    /// `moveType 2` — face a world point (raw WoW coords).
+    /// `moveType` 2: face a world point (raw WoW coords).
     Spot([f32; 3]),
-    /// `moveType 3` — face a unit by guid (resolved to its position when applied).
+    /// `moveType` 3: face a unit by guid, resolved to its position when applied.
     Target(u64),
-    /// `moveType 4` — face a raw orientation (radians, WoW convention).
+    /// `moveType` 4: face a raw orientation (radians, WoW convention).
     Angle(f32),
 }
 
-/// One creature template's UI-visible head (see [`ServerPacket::CreatureQueryResponse`]).
+/// One creature template's UI-visible head, from `SMSG_CREATURE_QUERY_RESPONSE`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreatureQueryInfo {
     pub name: String,
-    /// The NPC subtitle ("Stable Master") — the unit tooltip's second line.
+    /// The NPC subtitle ("Stable Master"), the unit tooltip's second line.
     pub subname: String,
-    /// `CreatureType.dbc` id (Beast/Humanoid/… — the level line's type word + the TAB filter).
+    /// `CreatureType.dbc` id: the tooltip level line's type word and the TAB-target filter.
     pub creature_type: u32,
-    /// `CreatureFamily.dbc` id (Wolf/Cat/Imp/… — `UnitCreatureFamily`'s row, and through that row's
-    /// pet-food mask, `GetPetFoodTypes`'s diet list; decision 1062). `0` for anything that is not a
-    /// tameable beast or a warlock minion — which is most of the table, and the reason both
-    /// consumers treat a missing row as nil rather than as an error.
+    /// `CreatureFamily.dbc` id; `0`, read as nil, for all but tameable beasts and warlock minions.
     pub pet_family: u32,
-    /// Elite rank: 0 normal, 1 elite, 2 rare-elite, 3 world boss, 4 rare — the unit tooltip's
-    /// rank word `{"", Elite, Elite, Boss, ""}` (decision 0276's byte-verified table).
+    /// 0 normal, 1 elite, 2 rare-elite, 3 world boss, 4 rare (tooltip: "", Elite, Elite, Boss, "").
     pub rank: u32,
-    /// The template type flags. Bit `0x10` (HIDE_FACTION_TOOLTIP) suppresses the unit tooltip's
-    /// faction-name line (the client's `0x612610` gate on the cached record's `+0x14`).
+    /// Bit `0x10` (HIDE_FACTION_TOOLTIP) drops the tooltip's faction line (`0x612610`).
     pub type_flags: u32,
-    /// The civilian flag (the tooltip's green CIVILIAN line; dishonorable-kill marking).
+    /// The tooltip's green CIVILIAN line and the dishonorable-kill mark.
     pub civilian: bool,
-    /// The racial-leader flag (the tooltip's white LEADER line; `0x6125c0` on the record's `+0x31`).
+    /// The tooltip's white LEADER line (`0x6125c0`).
     pub racial_leader: bool,
-    /// `CreatureDisplayInfo.dbc` id (`creature_template.display_id[0]`, vmangos
-    /// `QueryHandler.cpp:179`); `0` when the template has none. The one field that lets the client
-    /// draw a creature it has **never seen in the world** — a stabled pet, whose wire record names
-    /// only a `creature_template` entry and has no world object to read a display id from
-    /// (decision 1676). vmangos randomizes among a template's four display ids when it *spawns* a
-    /// creature, so this is the template's first entry, not necessarily what a given live unit
-    /// shows: for anything actually on screen, the unit's own `UNIT_FIELD_DISPLAYID` still wins.
+    /// `creature_template.display_id[0]` (`QueryHandler.cpp:179`), `0` if none, for drawing an
+    /// unseen creature; a spawned unit may use any of its four ids, so its own display id wins.
     pub display_id: u32,
 }
 
-/// A decoded server packet (only the opcodes benilla handles; everything else is [`Self::Other`]).
+/// A decoded server packet; an unmodelled opcode is [`Self::Other`].
 pub enum ServerPacket {
     AuthChallenge {
         server_seed: u32,
     },
     AuthResponse {
         result: u8,
-        /// Our place in the login queue, when `result` is [`super::AUTH_WAIT_QUEUE`] — `None` for
-        /// every other result, and also for a queue packet whose body was too short to carry one.
+        /// Our login-queue place; only for [`super::AUTH_WAIT_QUEUE`] with a long enough body.
         queue_position: Option<u32>,
-        /// The account's accumulated **rested billing minutes**, the third field of the billing
-        /// group — what `GetBillingTimeRested()` reports (decision 1820). `None` when the body was
-        /// too short to carry the group, which is the same length branch `queue_position` takes.
-        ///
-        /// The unit is the server's convention, not the engine's: the client applies no conversion
-        /// at any point (the binding `0x48ec50` does a bare unsigned u32→double, and the parser
-        /// `0x418eb0` a bare `mov`). Minutes is what the reference's own FrameXML assumes —
-        /// `PlayerFrame.lua:246` divides by 60 to get hours against `REQUIRED_REST_HOURS = 5`.
+        /// Rested billing minutes (`PlayerFrame.lua:246` divides by 60), returned unconverted by
+        /// `GetBillingTimeRested()` (`0x48ec50`); `None` on a body too short for the group.
         billing_time_rested: Option<u32>,
     },
     CharEnum {
@@ -104,108 +80,66 @@ pub enum ServerPacket {
     CharDelete {
         result: u8,
     },
-    /// `SMSG_CHARACTER_LOGIN_FAILED` — the server refused the `CMSG_PLAYER_LOGIN` we just sent.
-    ///
-    /// The byte is a **1-based reason index**, not a `ResponseCodes` value: the client feeds it to
-    /// a six-entry jump table (`0x5aae08`, behind `dec eax; cmp eax,5; ja`) that maps it onto the
-    /// `CHAR_LOGIN_*` status codes, so `1` is "world server is down" and everything past `6` is
-    /// the default "login failed" (VERIFIED off `WoW.exe` — wow-5875-re
-    /// `system/net/scratch/char-login-failed-law.md`). Both emulators speak that dialect: vmangos
-    /// sends a bare `1`, and mangos-classic's live enum is `CharLoginFailReasons` 0x01–0x08 (its
-    /// `ResponseCodes` `CHAR_LOGIN_*` block is commented out).
-    ///
-    /// Kept raw here all the same — turning it into a player-facing string is the glue layer's
-    /// job, and it is the only place that holds the reference's table.
+    /// `SMSG_CHARACTER_LOGIN_FAILED`: a 1-based reason index, not a `ResponseCodes` value, that
+    /// the client maps (`0x5aae08`) 1 to "world server is down" and past 6 to "login failed".
     CharacterLoginFailed {
         result: u8,
     },
     UpdateObject {
         objects: Vec<Object>,
     },
-    /// `SMSG_COMPRESSED_MOVES` — a **batch** of whole movement packets in one zlib envelope, each
-    /// already parsed into its own [`ServerPacket`] (decision 0624).
-    ///
-    /// vmangos flips a session onto this container once it has been sent
-    /// `Compression.Movement.Count` (300) movement packets inside a ten-second window
-    /// (`WorldSession::SendMovementPacket`), and flips back when the rate drops — so it is not an
-    /// exotic case but the **normal** carrier for any nearby player moving at frame cadence, which
-    /// since decision 0617 is what our own sender produces. Body: `u32` uncompressed size, then a
-    /// deflate stream of `[u8 size][u16 opcode][body]` records where `size` counts the opcode's two
-    /// bytes (`MovementData::AddPacket`).
+    /// `SMSG_COMPRESSED_MOVES`: a `u32` size, then deflated records `[u8 size][u16 opcode][body]`,
+    /// `size` counting the opcode (`MovementData::AddPacket`). vmangos switches to it past 300
+    /// movement packets in ten seconds (`SendMovementPacket`), so it is the normal carrier.
     CompressedMoves {
         packets: Vec<ServerPacket>,
     },
-    /// `SMSG_DESTROY_OBJECT` — one object ceased to exist server-side (a corpse decaying ahead of
-    /// respawn, a despawn), body a plain `u64` guid (vmangos `DestroyObject::AppendBodyTo`). Distinct
-    /// from the update-object `OutOfRange` block (*we* left its range; the real client keeps those
-    /// staged for cheap re-create): destroy frees the object outright (handler `0xaa → 0x4674a0`).
+    /// `SMSG_DESTROY_OBJECT`: a plain `u64` guid that ceased to exist server-side. The client frees
+    /// it outright (`0x4674a0`), unlike an `OutOfRange` block, whose objects it keeps staged.
     DestroyObject {
         guid: u64,
     },
-    /// `SMSG_TRIGGER_CINEMATIC` — play the cinematic sequence (body: the `CinematicSequences.dbc`
-    /// id, `u32`). Sent on a character's first-ever login (the race intro,
-    /// `HandleCharEnum`'s played-time-0 branch) and by GameObject type-13 cameras. While one runs
-    /// unacked, vmangos anchors visibility to the flying camera (see [`super::opcode`]'s note) — the
-    /// client must answer with `CMSG_COMPLETE_CINEMATIC` (empty body) when done (or to skip).
+    /// `SMSG_TRIGGER_CINEMATIC`: a `CinematicSequences.dbc` id, sent at first login and by type-13
+    /// camera objects. vmangos anchors visibility to the camera until `CMSG_COMPLETE_CINEMATIC`.
     TriggerCinematic {
         cinematic_id: u32,
     },
-    /// `MSG_MOVE_TIME_SKIPPED` — an observed mover's own client skipped `lag_ms` of movement
-    /// simulation, so every watcher's copy of its wire clock must move with it (layout in
-    /// [`super::movement::read_move_time_skipped`]). Decision 1935.
+    /// `MSG_MOVE_TIME_SKIPPED`: an observed mover skipped `lag_ms`; its wire clock moves with it.
     MoveTimeSkipped {
         guid: u64,
         lag_ms: u32,
     },
     MonsterMove {
         guid: u64,
-        /// `SMSG_MONSTER_MOVE_TRANSPORT` only: the transport whose frame `start` and every `path`
-        /// point are expressed in (deck-local offsets, not world coordinates). `None` = the plain
-        /// `SMSG_MONSTER_MOVE`, whose coordinates are absolute. Decision 1936.
+        /// `SMSG_MONSTER_MOVE_TRANSPORT` only: the transport whose frame `start` and `path` are in.
         transport: Option<u64>,
         start: Vector3d,
-        /// The server's per-move spline counter — echoed back in `CMSG_MOVE_SPLINE_DONE` when the
-        /// spline drives our own player (Charge/knockback/taxi); ignored for a creature's walk.
+        /// Echoed in `CMSG_MOVE_SPLINE_DONE` when the spline moves our own player.
         spline_id: u32,
-        /// The **full** ordered path the unit traverses, in travel order `[start, …waypoints…, endpoint]`
-        /// (absolute WoW coords) — every intermediate waypoint decoded, not just the endpoint. The client
-        /// walks all of them at constant (arc-length) speed; a straight hop is the two-point degenerate.
-        /// Empty for a `Stop`/degenerate move. (Ground paths pack the waypoints as `¼`-yd offsets from the
-        /// endpoint; a flying `Mask_CatmullRom` path sends them absolute — decoded in `monster_move`.)
+        /// The whole path, `[start, waypoints…, endpoint]`, walked at constant arc-length speed;
+        /// empty for a stop. Ground waypoints are `¼`-yd endpoint offsets, flying ones absolute.
         path: Vec<Vector3d>,
-        /// The dictated final facing (`moveType` 2/3/4), applied as a snap. [`MonsterMoveFacing::None`]
-        /// for a plain move — the unit then faces its travel direction along the path.
+        /// The dictated final facing (`moveType` 2/3/4), applied as a snap.
         facing: MonsterMoveFacing,
         stop: bool,
         duration_ms: u32,
-        /// The path is a 3-D **flight** (`SPLINE_FLAG_FLYING` = `Mask_CatmullRom`): keep the spline's own Z.
-        /// Clear ⇒ a ground walk whose Z the client re-derives from the terrain (the app terrain-clamps it).
+        /// `SPLINE_FLAG_FLYING` (`Mask_CatmullRom`): keep the spline's Z, else clamp to terrain.
         flying: bool,
-        /// The path's `SPLINEFLAG_RUNMODE` bit — and its **absence** is the load-bearing half: a
-        /// spline without it forces `MOVEFLAG_WALK_MODE` **on** for the unit it moves (see
-        /// [`super::monster_move`]'s `SPLINE_FLAG_RUNMODE`).
+        /// `SPLINEFLAG_RUNMODE`; a spline without it forces `MOVEFLAG_WALK_MODE` on for the unit.
         run_mode: bool,
     },
-    /// A relayed *player* movement packet (`MSG_MOVE_*`, see [`super::parse::is_movement_relay`]): the mover's
-    /// authoritative pose plus its live CMovement `moveFlags`. The app snaps the entity to `position`
-    /// and extrapolates from `flags` between packets. `opcode` is kept for logging/diagnostics.
-    /// `fall_time` + `jump` carry the airborne clock + ballistic launch params when `JUMPING` is set, so
-    /// a jump replays as one arc (decision 0053). `transport` is `Some` while `MOVEFLAG_ON_TRANSPORT` is
-    /// set: the mover's local pose on the named transport (decision 0438 — an observed rider's boarding
-    /// tail, composed through the transport's live matrix rather than read as world coordinates).
+    /// A relayed player `MSG_MOVE_*`: authoritative pose and live `moveFlags`; `transport` is set
+    /// while `MOVEFLAG_ON_TRANSPORT`, a pose local to the transport.
     PlayerMove {
         guid: u64,
         opcode: u16,
         flags: u32,
         position: Vector3d,
         orientation: f32,
-        /// The swim pitch (radians, +up) from the `MovementInfo` tail — the mover's 3D travel
-        /// angle while `MOVEFLAG_SWIMMING` is set (`0.0` otherwise), so observers integrate the
-        /// vertical between packets the way the client's swim velocity basis does (`0x7c5880`).
+        /// Swim pitch (radians, +up) while `MOVEFLAG_SWIMMING`, else `0.0`: observers integrate
+        /// the vertical with it, as the client's swim velocity basis does (`0x7c5880`).
         pitch: f32,
-        /// The `MovementInfo` time word. vmangos stamps it with **its own ms clock at receipt**
-        /// (`MovementInfo::stime`, `Object.cpp` `Write`), so every relayed move shares one server
-        /// clock — the scheduling basis for the reference's deferred replay (decision 0601).
+        /// vmangos's own ms clock at receipt (`MovementInfo::stime`), shared by all relayed moves.
         time: u32,
         fall_time: u32,
         jump: Option<JumpInfo>,
@@ -222,10 +156,8 @@ pub enum ServerPacket {
         position: Vector3d,
         orientation: f32,
     },
-    /// The far-teleport preamble (`SMSG_TRANSFER_PENDING`): the destination map and, when the
-    /// player is riding a transport through the transfer, `(transportEntry, oldMapId)`. The
-    /// block's presence decides how the follow-up [`Self::NewWorld`] coordinates read —
-    /// boat-local vs world (decision 0455).
+    /// `SMSG_TRANSFER_PENDING`: the far-teleport's map, plus `(transportEntry, oldMapId)` when
+    /// riding a transport, which makes the following [`Self::NewWorld`] coordinates boat-local.
     TransferPending {
         map: u32,
         transport: Option<(u32, u32)>,
@@ -242,168 +174,134 @@ pub enum ServerPacket {
     TimeSpeed {
         hours: u8,
         minutes: u8,
-        /// Monotonic day count flattened from the packed date (`year·372 + month·31 + day`) —
-        /// the celestial layer's moon-phase precession input.
+        /// Day count from the packed date, `year·372 + month·31 + day`; drives the moon phase.
         day_serial: u32,
         timescale: f32,
     },
-    /// `SMSG_QUERY_TIME_RESPONSE`: the server's wall clock in **unix-epoch seconds**, answering our
-    /// `CMSG_QUERY_TIME`. Not the in-game clock — that is [`Self::TimeSpeed`]'s packed date, a
-    /// different quantity entirely. This one exists so the client can read the *absolute* stamps
-    /// the server writes into descriptor fields: today the quest-log slot's timed-quest deadline
-    /// (decision 1150).
+    /// `SMSG_QUERY_TIME_RESPONSE`: wall-clock unix seconds, the base of absolute descriptor stamps.
     QueryTimeResponse {
         unix_time: u32,
     },
-    /// The player's hearthstone bind point (`SMSG_BINDPOINTUPDATE`, at login + on re-bind):
-    /// position + map + the AreaTable id the `$z` token names.
+    /// `SMSG_BINDPOINTUPDATE` (login, re-bind): the hearth point and the AreaTable id `$z` names.
     BindPoint {
         position: Vector3d,
         map: u32,
         area: u32,
     },
-    /// `SMSG_GMTICKET_GETTICKET` — the player's open GM ticket, or `None` for the ordinary
-    /// "you have no ticket" answer (decision 1673). **Not always solicited**: vmangos pushes a
-    /// fresh one at the ticket's author when a GM views, escalates or completes it
-    /// (`GMTicketMgr.cpp:153-159`), which is how a reply reaches the player at all in 1.12.
+    /// `SMSG_GMTICKET_GETTICKET`: our open ticket, `None` for "no ticket". Also pushed unasked
+    /// when a GM views, escalates or completes it (`GMTicketMgr.cpp:153-159`).
     GmTicketAnswer {
         ticket: Option<Box<GmTicket>>,
     },
-    /// `SMSG_GMTICKET_CREATE` — the answer to filing a ticket: 2 = created, 3 = refused,
-    /// 1 = you already have one (decision 1673). vmangos never sends 1 (an existing ticket just
-    /// yields 3), and answers several refusals with **silence** rather than a code at all.
+    /// `SMSG_GMTICKET_CREATE`: 2 created, 3 refused, 1 already have one; vmangos never sends 1
+    /// and answers some refusals with silence.
     GmTicketCreated {
         response: u32,
     },
-    /// `SMSG_GMTICKET_UPDATETEXT` — the answer to editing a ticket: 4 = saved, 5 = refused.
+    /// `SMSG_GMTICKET_UPDATETEXT`: the answer to an edit, 4 saved, 5 refused.
     GmTicketUpdated {
         response: u32,
     },
-    /// `SMSG_GMTICKET_DELETETICKET` — the answer to abandoning a ticket: 9 = deleted.
-    /// Also arrives **unsolicited** when a GM runs `.ticket delete` (`TicketCommands.cpp:100-103`).
+    /// `SMSG_GMTICKET_DELETETICKET`: 9 = deleted. Also sent unasked when a GM runs
+    /// `.ticket delete` (`TicketCommands.cpp:100-103`).
     GmTicketDeleted {
         response: u32,
     },
-    /// `SMSG_GMTICKETSYSTEMSTATUS` — 1 = the petition queue is taking tickets, 0 = it is not.
-    /// Answers `CMSG_GMTICKET_SYSTEMSTATUS`; cmangos also broadcasts it to every session when a
-    /// GM toggles the queue, vmangos never does.
+    /// `SMSG_GMTICKETSYSTEMSTATUS`: 1 = tickets accepted, 0 = not; vmangos sends it only on ask.
     GmTicketSystemStatus {
         status: i32,
     },
-    /// `SMSG_GM_TICKET_STATUS_UPDATE` — a GM touched the ticket: 1 = updated, 2 = closed,
-    /// 3 = a survey is offered. Never sent by vmangos; the core of cmangos's notification model.
+    /// `SMSG_GM_TICKET_STATUS_UPDATE`: 1 updated, 2 closed, 3 survey; vmangos never sends it.
     GmTicketStatusUpdate {
         status: u32,
     },
-    /// `SMSG_BINDER_CONFIRM` — an innkeeper is *asking* whether to make this your home
-    /// (decision 1331). The body is the innkeeper's guid, which must come back in
-    /// `CMSG_BINDER_ACTIVATE` for anything to happen: this packet binds nothing on its own.
+    /// `SMSG_BINDER_CONFIRM`: an innkeeper's question; `CMSG_BINDER_ACTIVATE` with the guid binds.
     BinderConfirm {
         binder: u64,
     },
-    /// `MSG_TALENT_WIPE_CONFIRM` (inbound) — a class trainer is *asking* whether to unlearn every
-    /// talent, and what it will cost (decision 1580). The twin of [`Self::BinderConfirm`] in every
-    /// respect: nothing is unlearned until the same opcode goes back out carrying `trainer`.
-    /// `trainer == 0` is vmangos's "you have no talents to reset" refusal, not a question.
+    /// `MSG_TALENT_WIPE_CONFIRM` inbound: a trainer offers a talent wipe for `cost`; nothing is
+    /// unlearned until the opcode goes back with `trainer`. `trainer == 0` means no talents.
     TalentWipeConfirm {
         trainer: u64,
         cost: u32,
     },
-    /// `SMSG_PET_UNLEARN_CONFIRM` — the pet trainer's question (decision 1963): the talent-wipe
-    /// twin for a pet, the same latch-and-confirm shape; nothing is unlearned until
-    /// `CMSG_PET_UNLEARN` goes back with the guid.
+    /// `SMSG_PET_UNLEARN_CONFIRM`: a pet trainer asks; `CMSG_PET_UNLEARN` with the guid confirms.
     PetUnlearnConfirm {
         trainer: u64,
         cost: u32,
     },
-    /// `SMSG_RAID_GROUP_ONLY` — the instance-boot clock (decision 1963): a positive delay arms
-    /// the boot, zero clears it and names the reason on screen.
+    /// `SMSG_RAID_GROUP_ONLY`: a delay arms the instance boot; zero clears it and shows `reason`.
     RaidGroupOnly {
         delay_ms: u32,
         reason: u32,
     },
-    /// `SMSG_AREA_SPIRIT_HEALER_TIME` — a battleground spirit healer's next wave (decision 1963).
+    /// `SMSG_AREA_SPIRIT_HEALER_TIME`: a battleground spirit healer's next wave.
     AreaSpiritHealerTime {
         healer: u64,
         ms: u32,
     },
-    /// `SMSG_BATTLEFIELD_STATUS` — one of the three queue slots (decision 1963).
+    /// `SMSG_BATTLEFIELD_STATUS`: one of the three queue slots.
     BattlefieldStatus(crate::messages::BattlefieldStatus),
-    /// `MSG_PVP_LOG_DATA` inbound — the battleground scoreboard (decision 1972).
+    /// `MSG_PVP_LOG_DATA` inbound: the battleground scoreboard.
     PvpLogData(crate::messages::PvpLogData),
-    /// `SMSG_BATTLEFIELD_LIST` — the battleground instance list (decision 1974).
+    /// `SMSG_BATTLEFIELD_LIST`: the battleground instance list.
     BattlefieldList(crate::messages::BattlefieldList),
-    /// `MSG_BATTLEGROUND_PLAYER_POSITIONS` inbound — the teammates and the flag carrier (1980).
+    /// `MSG_BATTLEGROUND_PLAYER_POSITIONS` inbound: the teammates and the flag carrier.
     BattlefieldPositions(crate::messages::BattlefieldPositions),
-    /// `MSG_TABARDVENDOR_ACTIVATE` inbound — the vendor guid that opens the tabard designer (1977).
+    /// `MSG_TABARDVENDOR_ACTIVATE` inbound: the vendor guid that opens the tabard designer.
     TabardVendorActivate(u64),
-    /// `MSG_SAVE_GUILD_EMBLEM` inbound — the save's result row (1977).
+    /// `MSG_SAVE_GUILD_EMBLEM` inbound: the save's result row.
     SaveGuildEmblemResult(u32),
-    /// `SMSG_GROUP_JOINED_BATTLEGROUND` — a group join's verdict (decision 1974).
+    /// `SMSG_GROUP_JOINED_BATTLEGROUND`: a group join's verdict.
     GroupJoinedBattleground {
         result: u32,
     },
-    /// `SMSG_BATTLEGROUND_PLAYER_JOINED` / `_LEFT` — one guid each (decision 1974).
+    /// `SMSG_BATTLEGROUND_PLAYER_JOINED` / `_LEFT`: one guid each.
     BattlegroundPlayer {
         guid: u64,
         joined: bool,
     },
-    /// `SMSG 0x295` — the meeting-stone queue state (decision 1963).
+    /// `SMSG_MEETINGSTONE_SETQUEUE` (`0x295`): the meeting-stone queue state.
     MeetingStoneSetQueue {
         area: u32,
         status: u8,
     },
-    /// `SMSG 0x297/0x298/0x299/0x2BB` — the meeting stone's display-only replies (decision 1974).
+    /// `0x297`/`0x298`/`0x299`/`0x2BB`: the meeting stone's display-only replies.
     MeetingStoneNotice(crate::messages::MeetingStoneNotice),
-    /// `SMSG_TUTORIAL_FLAGS` — the account's tutorial bank (decision 1976).
+    /// `SMSG_TUTORIAL_FLAGS`: the account's tutorial bank.
     TutorialFlags(crate::messages::TutorialFlags),
-    /// `SMSG_SUMMON_REQUEST` — someone is *asking* to pull us to them (decision 1747): a
-    /// warlock's ritual, a meeting stone, a GM. The twin of [`Self::BinderConfirm`] in shape —
-    /// nothing moves until `CMSG_SUMMON_RESPONSE` goes back — and its opposite in teardown:
-    /// there is no decline opcode, so the question expires rather than being answered no.
+    /// `SMSG_SUMMON_REQUEST`: someone asks to pull us to them; nothing moves until
+    /// `CMSG_SUMMON_RESPONSE`, and with no decline opcode the offer just expires.
     SummonRequest {
         summoner: u64,
         zone: u32,
         delay_ms: u32,
     },
-    /// `SMSG_PLAYERBOUND` — the bind took: who bound us and the AreaTable id we are now bound in.
-    /// Arrives beside [`Self::BindPoint`], which carries the same area id plus the position; this
-    /// one exists for the "X is now your home" acknowledgement.
+    /// `SMSG_PLAYERBOUND`: the bind took (the "now your home" line), beside [`Self::BindPoint`].
     PlayerBound {
         binder: u64,
         area: u32,
     },
-    /// `SMSG_SET_PROFICIENCY` (at login + on train): the subclass bitmask the player can equip
-    /// for one item class (2 weapons / 4 armor) — the client's `0xc4d4a0[class]` store, the item
-    /// tooltip's slot-line proficiency red (vmangos `Skill.h`: u8 itemClass + u32 mask).
+    /// `SMSG_SET_PROFICIENCY`: equippable subclasses of item class 2 or 4 (`0xc4d4a0[class]`).
     SetProficiency {
         item_class: u8,
         subclass_mask: u32,
     },
-    /// `SMSG_INITIALIZE_FACTIONS` — the player's reputation store, sent once at login: `(flags,
-    /// standing)` per reputation-list slot (vanilla sends all 64), indexed by `Faction.dbc`'s
-    /// `reputationIndex`. The wire standing **excludes** the DBC base value — the client adds the
-    /// race/class-matched `BaseRepValue` before ranking (hated → exalted).
+    /// `SMSG_INITIALIZE_FACTIONS` (login): `(flags, standing)` for all 64 slots by `Faction.dbc`
+    /// `reputationIndex`. Standing excludes the race/class `BaseRepValue`, which the client adds.
     InitializeFactions {
         standings: Vec<(u8, i32)>,
     },
-    /// `SMSG_SET_FACTION_STANDING` — mid-session standing deltas: `(reputationListId, standing)`
-    /// per changed slot (vmangos `ReputationMgr::SendState` batches every `needSend` faction).
-    /// Same standing convention as [`Self::InitializeFactions`] (DBC base excluded).
+    /// `SMSG_SET_FACTION_STANDING`: `(reputationListId, standing)` per changed slot, base excluded.
     SetFactionStanding {
         standings: Vec<(u32, i32)>,
     },
-    /// `SMSG_SET_FACTION_VISIBLE` — one reputation-list slot just became visible in the pane
-    /// (vmangos `ReputationMgr::SendVisible`, pushed the first time the player meets the faction).
-    /// It carries **no standing**: the slot's existing standing is already correct, and this only
-    /// lifts `FACTION_FLAG_VISIBLE` on it.
+    /// `SMSG_SET_FACTION_VISIBLE`: sets `FACTION_FLAG_VISIBLE` on one slot; it carries no standing.
     SetFactionVisible {
         list_id: u32,
     },
-    /// `SMSG_NAME_QUERY_RESPONSE` — a player character's identity, answering `CMSG_NAME_QUERY`:
-    /// guid, name, realm (1.12.1 carries it, empty on a single realm), race/gender/class as `u32`s
-    /// (VERIFIED vmangos `NameQueryResponse::AppendBodyTo`). An unknown guid answers with an empty
-    /// name (`SendNameQueryOpcodeFromDBCallBack` with no DB row).
+    /// `SMSG_NAME_QUERY_RESPONSE`: guid, name, realm (empty on one realm), race/gender/class as
+    /// `u32`s (`NameQueryResponse::AppendBodyTo`); an unknown guid gets an empty name.
     NameQueryResponse {
         guid: u64,
         name: String,
@@ -411,542 +309,412 @@ pub enum ServerPacket {
         gender: u32,
         class: u32,
     },
-    /// `SMSG_CREATURE_QUERY_RESPONSE` — a creature template's display data, answering
-    /// `CMSG_CREATURE_QUERY`. We surface what the UI consumes ([`CreatureQueryInfo`]: name,
-    /// subname, `CreatureType.dbc` id, the `CreatureFamily.dbc` id, the elite **rank**, the type
-    /// flags, and the civilian/racial-leader pair); only `unk`, the pet spell-list id and the
-    /// display id are still parsed for alignment and dropped. A **miss** (unknown entry) is a lone `u32` of
-    /// `entry | 0x8000_0000` → `None` (VERIFIED vmangos `HandleCreatureQueryOpcode`, both
-    /// branches).
+    /// `SMSG_CREATURE_QUERY_RESPONSE`: a template's UI head; `unk` and the pet spell-list id are
+    /// read and dropped. A miss is a lone `entry | 0x8000_0000` (`HandleCreatureQueryOpcode`).
     CreatureQueryResponse {
         entry: u32,
-        /// `Some` on a hit; `None` when the server flagged the entry unknown.
         info: Option<CreatureQueryInfo>,
     },
-    /// `SMSG_PET_NAME_QUERY_RESPONSE` — a pet's display name, answering `CMSG_PET_NAME_QUERY`.
-    /// Keyed by **pet number**, not a template entry (a pet guid carries none — see
-    /// [`crate::guid::pet_number`]); that is also how the real client's own pet-name cache is keyed.
-    /// The `nameTimestamp` tail is parsed for alignment and dropped: it exists to age out that
-    /// on-disk cache, which we have no equivalent of.
+    /// `SMSG_PET_NAME_QUERY_RESPONSE`: keyed by pet number, as the client's pet-name cache is; the
+    /// `nameTimestamp` tail, which only ages that on-disk cache, is read and dropped.
     PetNameQueryResponse {
         pet_number: u32,
         name: String,
     },
-    /// `SMSG_GAMEOBJECT_QUERY_RESPONSE` — a GameObject template's type/display/name/`data[24]` head,
-    /// answering `CMSG_GAMEOBJECT_QUERY` (decision 0236's ask-once template lookup, the GO twin of
-    /// [`Self::CreatureQueryResponse`]). `data[24]` is the raw type-specific tail (e.g. a chest's
-    /// lockId) — parsed verbatim, resolved by whichever later consumer knows the GO's type. A miss
-    /// (unknown entry) is a lone `u32` of `entry | 0x8000_0000` → `None`, same shape as the
-    /// creature/item miss.
+    /// `SMSG_GAMEOBJECT_QUERY_RESPONSE`: a template's type, display, name and raw type-specific
+    /// `data[24]`; a miss is a lone `entry | 0x8000_0000`.
     GameObjectQueryResponse {
         entry: u32,
         info: Option<GameObjectQueryInfo>,
     },
-    /// `SMSG_PAGE_TEXT_QUERY_RESPONSE` — one page of a book, answering `CMSG_PAGE_TEXT_QUERY`
-    /// (the ask-once page cache every readable reaches: a readable item template's `PageText` and a
-    /// `GAMEOBJECT_TYPE_TEXT` object's `data[0]`, decision 1105). Pages **chain** —
-    /// `next_page_id == 0` is the last one — and vmangos answers a single query with one of these
-    /// per page of the whole chain.
+    /// `SMSG_PAGE_TEXT_QUERY_RESPONSE`: one book page; `next_page_id == 0` is the last, and
+    /// vmangos answers one query with every page of the chain.
     PageTextQueryResponse {
         page_id: u32,
         text: String,
         next_page_id: u32,
     },
-    /// `SMSG_GAMEOBJECT_CUSTOM_ANIM` — a GameObject plays a one-shot Custom animation. Payload
-    /// VERIFIED vmangos `GameObject::SendGameObjectCustomAnim`: `u64 guid, u32 animId`. The
-    /// client arms GO substate `8 + animId` (AnimationData 153..156, `animId >= 4` rejected) —
-    /// the fishing bobber's bite splash is `animId 0` (decision 1086).
+    /// `SMSG_GAMEOBJECT_CUSTOM_ANIM`: `u64 guid, u32 animId`; the client arms substate
+    /// `8 + animId` (AnimationData 153..156, `animId >= 4` rejected). The bobber's bite is 0.
     GameObjectCustomAnim {
         guid: u64,
         anim_id: u32,
     },
-    /// `SMSG_GAMEOBJECT_DESPAWN_ANIM` — an object plays its one-shot **Despawn** animation and
-    /// then goes away. Payload VERIFIED vmangos `WorldObject::SendObjectDeSpawnAnim`: a bare
-    /// `u64` guid. The client arms substate 12 (AnimationData **157 Despawn**) and PINS the
-    /// object so the `SMSG_DESTROY_OBJECT` that follows in the same server tick waits for the
-    /// play to finish (decision 1404).
+    /// `SMSG_OPEN_CONTAINER`: a bag's raw `u64` guid on equip; the reference only fires `BAG_OPEN`.
+    OpenContainer {
+        item: u64,
+    },
+    /// `SMSG_INSPECT`: the target's raw `u64` guid, ignored, as the reference ignores it.
+    Inspect {
+        guid: u64,
+    },
+    /// `SMSG_STANDSTATE_UPDATE`: the server set our stand state (`u8`), applied ungated.
+    StandStateUpdate {
+        state: u8,
+    },
+    /// `SMSG_GAMEOBJECT_DESPAWN_ANIM`: a bare `u64` guid. The client arms substate 12 (anim 157)
+    /// and pins the object, so the same tick's `SMSG_DESTROY_OBJECT` waits for the play to end.
     GameObjectDespawnAnim {
         guid: u64,
     },
-    /// `SMSG_FISH_NOT_HOOKED` — the fishing channel ended (expiry, or clicked before the splash)
-    /// with nothing hooked. Empty body (VERIFIED vmangos `GameObject::Update`/`Use`); the red
-    /// `ERR_FISH_NOT_HOOKED` toast (decision 1086).
+    /// `SMSG_FISH_NOT_HOOKED`: the channel ended unhooked (empty body; `ERR_FISH_NOT_HOOKED`).
     FishNotHooked,
-    /// `SMSG_FISH_ESCAPED` — the hooked fish got away (the skill roll failed on the click).
-    /// Empty body (VERIFIED vmangos `GameObject::Use`); the red `ERR_FISH_ESCAPED` toast
-    /// (decision 1086).
+    /// `SMSG_FISH_ESCAPED`: the skill roll failed on the click (empty body; `ERR_FISH_ESCAPED`).
     FishEscaped,
-    /// `SMSG_PLAY_SOUND` — a 2D sound-kit id, map/zone-wide (BG events, scripts). Payload
-    /// VERIFIED vmangos `Map::PlayDirectSoundToMap`: one `u32 soundId` (SoundEntries).
+    /// `SMSG_PLAY_SOUND`: one `u32` SoundEntries id, played 2D (`Map::PlayDirectSoundToMap`).
     PlaySound {
         sound_id: u32,
     },
-    /// `SMSG_PLAY_MUSIC` — a music kit for the music channel (scripts, e.g. Karazhan opera).
-    /// Payload VERIFIED vmangos: one `u32 musicId` (SoundEntries).
+    /// `SMSG_PLAY_MUSIC`: one `u32` SoundEntries id for the music channel.
     PlayMusic {
         music_id: u32,
     },
-    /// `SMSG_PLAY_OBJECT_SOUND` — a 3D kit at a source object (fishing-bobber splash 3355,
-    /// distance-dependent scripts). Payload VERIFIED vmangos `WorldObject::PlayDistanceSound`:
-    /// `u32 soundId, u64 sourceGuid`.
+    /// `SMSG_PLAY_OBJECT_SOUND`: `u32 soundId, u64 sourceGuid`, played 3D at the source object.
     PlayObjectSound {
         sound_id: u32,
         guid: u64,
     },
-    /// `SMSG_WEATHER` — the zone's weather state. Payload VERIFIED vmangos
-    /// `Weather::SendWeatherForPlayersInZone` (1.12 shape): `u32 type, f32 grade,
-    /// u32 soundId (a SoundEntries kit — 8533..8558, the rain/snow/sandstorm loops; 0 = clear),
-    /// u8 instant`. `type`/`grade`/`instant` also feed the weather *visuals* when they exist.
+    /// `SMSG_WEATHER`: `u32 type, f32 grade, u32 soundId, u8 instant`; sounds 8533..8558, 0 clear.
     Weather {
         weather_type: u32,
         grade: f32,
         sound_id: u32,
         instant: bool,
     },
-    /// `SMSG_TEXT_EMOTE` — a nearby unit performed a chat emote (`/wave`). Payload VERIFIED
-    /// vmangos `EmoteChatBuilder`: `u64 guid, u32 textEmote (EmotesText.dbc), u32 emoteNum,
-    /// u32 namelen, char name[namelen]` (the target's name; namelen ≥ 1, a lone NUL when there was
-    /// no target).
-    ///
-    /// **`target_name` is load-bearing and used to be dropped here** (decision 1274 / B156): it is
-    /// what selects the emote's sentence FORM — untargeted vs targeted vs "…at you" — in
-    /// `benilla_formats::EmoteTextCatalog`, and it is the raw wire string, never round-tripped
-    /// through a name cache, exactly as the reference passes it. `emoteNum` really is
-    /// dropped: the receive side reads it off the wire and never consumes it (wow-re
-    /// `ui/scratch/text-emote-composition.md` §3).
+    /// `SMSG_TEXT_EMOTE`: `u64 guid, u32 textEmote, u32 emoteNum, u32 namelen, char name[namelen]`
+    /// (`EmoteChatBuilder`; a lone NUL for no target). The raw `target_name` picks the sentence
+    /// form, as in the reference; `emoteNum` is read and ignored, as the reference ignores it.
     TextEmote {
         guid: u64,
         text_emote: u32,
         target_name: String,
     },
-    /// `SMSG_EMOTE` — a unit plays an anim emote. Payload VERIFIED vmangos
-    /// `Unit::HandleEmote`: `u32 emoteId (Emotes.dbc), u64 guid`.
+    /// `SMSG_EMOTE`: `u32 emoteId (Emotes.dbc), u64 guid`, an animation emote.
     Emote {
         guid: u64,
         emote_id: u32,
     },
-    /// `SMSG_ITEM_QUERY_SINGLE_RESPONSE` — an item template's display head, answering
-    /// `CMSG_ITEM_QUERY_SINGLE` (layout in [`super::items`]); `None` info = the miss shape. `ItemInfo` now
-    /// carries the full 1.12.1 item template (decision 0274 P1) — boxed so this one wide-but-rare
-    /// variant doesn't inflate every other (tiny, hot) `ServerPacket` (`clippy::large_enum_variant`).
+    /// `SMSG_ITEM_QUERY_SINGLE_RESPONSE`: the full item template, boxed for size; `None` is a miss.
     ItemQueryResponse {
         entry: u32,
         info: Option<Box<ItemInfo>>,
     },
-    /// `SMSG_MESSAGECHAT` — one inbound chat line (say/yell/system/NPC/channel; layout in
-    /// [`super::chat`]). System lines (type `0x0A`) are how GM dot-commands answer.
+    /// `SMSG_MESSAGECHAT`: one chat line; GM dot-commands answer as system lines (type `0x0A`).
     MessageChat(ChatMessage),
-    /// `SMSG_CHANNEL_NOTIFY` — a channel join/leave/error/moderation notice (layout in
-    /// [`super::channel::read_channel_notify`], decision 0288).
+    /// `SMSG_CHANNEL_NOTIFY`: a channel join, leave, error or moderation notice.
     ChannelNotify(ChannelNotify),
-    /// `SMSG_CHANNEL_LIST` — a channel's member roster, answering our `CMSG_CHANNEL_LIST` (layout in
-    /// [`super::channel::read_channel_list`]): `(guid, memberFlags)` per row.
+    /// `SMSG_CHANNEL_LIST`: a channel's roster, `(guid, memberFlags)` per member.
     ChannelList {
         channel: String,
         flags: u8,
         members: Vec<(u64, u8)>,
     },
-    /// `SMSG_CHAT_PLAYER_NOT_FOUND` — a whisper target wasn't found online (vmangos
-    /// `Server/Packets/Chat.cpp:26-29`).
+    /// `SMSG_CHAT_PLAYER_NOT_FOUND`: the whisper target is not online (`Chat.cpp:26-29`).
     ChatPlayerNotFound {
         name: String,
     },
-    /// `SMSG_CHAT_WRONG_FACTION` — a cross-faction whisper was refused; empty body (vmangos
-    /// `Server/Packets/Chat.cpp:16-18`).
+    /// `SMSG_CHAT_WRONG_FACTION`: a cross-faction whisper was refused; empty body.
     ChatWrongFaction,
-    /// `SMSG_NOTIFICATION` — a server notice ("You do not know that language", …); one cstring
-    /// (vmangos `WorldSession::SendNotification`, `Server/WorldSession.cpp:900-915`).
+    /// `SMSG_NOTIFICATION`: one cstring server notice (`WorldSession.cpp:900-915`).
     Notification {
         text: String,
     },
-    /// `SMSG_AREA_TRIGGER_MESSAGE` — why an area trigger refused us ("You must be at least level 58
-    /// to enter…"); `u32 length` + one cstring (vmangos `WorldSession::SendAreaTriggerMessage`,
-    /// `Server/WorldSession.cpp:882-898`).
+    /// `SMSG_AREA_TRIGGER_MESSAGE`: why a trigger refused us, as `u32 length` then a cstring
+    /// (`WorldSession.cpp:882-898`).
     AreaTriggerMessage {
         text: String,
     },
-    /// `SMSG_SERVER_MESSAGE` — a shutdown/restart countdown or an operator broadcast: the
-    /// `ServerMessages.dbc` row id and the text that fills its `%s` (layout in
-    /// [`super::broadcast::read_server_message`]).
+    /// `SMSG_SERVER_MESSAGE`: a `ServerMessages.dbc` row (shutdown, broadcast) and its `%s`.
     ServerMessage {
         message_type: u32,
         text: String,
     },
-    /// `SMSG_ZONE_UNDER_ATTACK` — an area is under attack by enemy players; one `AreaTable.dbc` id
-    /// (layout in [`super::broadcast::read_zone_under_attack`]).
+    /// `SMSG_ZONE_UNDER_ATTACK`: one `AreaTable.dbc` id under attack by enemy players.
     ZoneUnderAttack {
         area_id: u32,
     },
-    /// `SMSG_DEFENSE_MESSAGE` — a world-defense broadcast (the EPL tower captures): the zone it is
-    /// about and the server-composed text (layout in [`super::broadcast::read_defense_message`]).
+    /// `SMSG_DEFENSE_MESSAGE`: a world-defense broadcast (EPL towers), the zone and composed text.
     DefenseMessage {
         zone_id: u32,
         text: String,
     },
-    /// `SMSG_CHAT_RESTRICTED` — a trial account hit its whisper cap; empty body (vmangos
-    /// `Server/Packets/Chat.cpp:21-23`). The [`Self::ChatWrongFaction`] shape exactly.
+    /// `SMSG_CHAT_RESTRICTED`: a trial account hit its whisper cap; empty body.
     ChatRestricted,
-    /// `SMSG_PLAYED_TIME` — answers our `CMSG_PLAYED_TIME` (`/played`): total played time + time
-    /// since the last level-up, both in seconds (layout in [`super::chat::read_played_time`]).
+    /// `SMSG_PLAYED_TIME` (`/played`): total and this-level played time, in seconds.
     PlayedTime {
         total: u32,
         level: u32,
     },
-    /// `MSG_RANDOM_ROLL` — the server's `/random` broadcast (layout in
-    /// [`super::chat::read_random_roll`]): the rolled range, the result, and the roller's guid.
+    /// `MSG_RANDOM_ROLL`: the server's `/random` broadcast.
     RandomRoll {
         min: u32,
         max: u32,
         roll: u32,
         guid: u64,
     },
-    /// `SMSG_INVENTORY_CHANGE_FAILURE` — the server refused an inventory operation
-    /// (equip/store/split; layout in [`super::items::read_inventory_change_failure`]). `reason` is the
-    /// `InventoryResult` code; `required_level` rides only on the level refusal (reason 1).
+    /// `SMSG_INVENTORY_CHANGE_FAILURE`: an `InventoryResult`; `required_level` rides only reason 1.
     InventoryChangeFailure {
         reason: u8,
         required_level: Option<u32>,
         item_guid: u64,
-        /// The destination bag's ABSOLUTE player slot (255 = the player's own array).
+        /// The destination bag's absolute player slot (255 = the player's own array).
         bag_slot: u8,
     },
-    /// `SMSG_INITIAL_SPELLS` — the player's spell book + active cooldowns, once at login
-    /// (layout in [`super::spellbook::read_initial_spells`]).
+    /// `SMSG_INITIAL_SPELLS`: the spell book and active cooldowns, once at login.
     InitialSpells {
         spell_ids: Vec<u16>,
         cooldowns: Vec<SpellCooldown>,
     },
-    /// `SMSG_ACTION_BUTTONS` — the player's saved action bar, once at login: the occupied slots
-    /// of the 120-slot wire array (layout in [`super::action_bar::read_action_buttons`]).
+    /// `SMSG_ACTION_BUTTONS` (login): the occupied slots of the 120-slot action bar array.
     ActionButtons {
         buttons: Vec<ActionButton>,
     },
-    /// `SMSG_LEARNED_SPELL` — a spell was added to the book after login (trainer/quest/level-up;
-    /// layout in [`super::spellbook::read_learned_spell`]). The first post-login spell-book mutation (0237).
+    /// `SMSG_LEARNED_SPELL`: a spell joined the book after login.
     LearnedSpell {
         spell_id: u16,
     },
-    /// `SMSG_REMOVED_SPELL` — the server took a spell out of the book (layout in
-    /// [`super::spellbook::read_removed_spell`]). One per spell: a talent wipe sends a burst of
-    /// them, one for every rank of every talent (decision 1584).
+    /// `SMSG_REMOVED_SPELL`: one spell left the book; a talent wipe sends one per rank per talent.
     RemovedSpell {
         spell_id: u16,
     },
-    /// `SMSG_SUPERCEDED_SPELL` — a rank-up replaced its predecessor in the book + action bar
-    /// (layout in [`super::spellbook::read_superceded_spell`]).
+    /// `SMSG_SUPERCEDED_SPELL`: a rank-up replaced its predecessor in the book and action bar.
     SupercededSpell {
         old_spell_id: u16,
         new_spell_id: u16,
     },
-    /// `SMSG_CAST_RESULT` — the server's verdict on our `CMSG_CAST_SPELL`.
+    /// `SMSG_CAST_RESULT`: the server's verdict on our `CMSG_CAST_SPELL`.
     CastResult {
         spell_id: u32,
         outcome: CastOutcome,
     },
-    /// `SMSG_PET_SPELLS` — the pet action bar's whole state, or (with a zero `pet_guid`) its
-    /// teardown (layout in [`super::pet::read_pet_spells`], decision 0982).
+    /// `SMSG_PET_SPELLS`: the pet bar's whole state; a zero `pet_guid` tears it down.
     PetSpells(PetSpells),
-    /// `SMSG_PET_MODE` — the pet's react/command state alone, no bar behind it
-    /// (layout in [`super::pet::read_pet_mode`]).
+    /// `SMSG_PET_MODE`: the pet's react and command state alone.
     PetMode(PetMode),
-    /// `SMSG_PET_ACTION_FEEDBACK` — one reason byte for a refused pet order.
+    /// `SMSG_PET_ACTION_FEEDBACK`: one reason byte for a refused pet order.
     PetActionFeedback {
         reason: u8,
     },
-    /// `SMSG_PET_CAST_FAILED` — the pet's cast refusal, in `SMSG_CAST_RESULT`'s vocabulary.
+    /// `SMSG_PET_CAST_FAILED`: the pet's cast refusal, in `SMSG_CAST_RESULT`'s vocabulary.
     PetCastFailed {
         spell_id: u32,
         outcome: CastOutcome,
     },
-    /// `SMSG_PET_TAME_FAILURE` — one `PetTameFailureReason` byte; the red line's text comes from
-    /// [`super::pet::pet_tame_failure_key`].
+    /// `SMSG_PET_TAME_FAILURE`: one `PetTameFailureReason` byte.
     PetTameFailure {
         reason: u8,
     },
-    /// `SMSG_PET_NAME_INVALID` — the refused rename. Empty body: the opcode IS the message.
+    /// `SMSG_PET_NAME_INVALID`: the rename was refused; empty body.
     PetNameInvalid,
-    /// `SMSG_PET_BROKEN` — the pet's loyalty hit zero and it ran away. Empty body.
+    /// `SMSG_PET_BROKEN`: the pet's loyalty hit zero and it ran away; empty body.
     PetBroken,
-    /// `SMSG_PET_ACTION_SOUND` — the pet's voice: which unit, and which of the two talk
-    /// selectors ([`super::pet::PET_TALK_ORDER`] / [`super::pet::PET_TALK_ATTACK`]).
+    /// `SMSG_PET_ACTION_SOUND`: the pet's voice; `talk` is [`super::pet::PET_TALK_ORDER`] or
+    /// [`super::pet::PET_TALK_ATTACK`].
     PetActionSound {
         pet_guid: u64,
         talk: u32,
     },
-    /// `SMSG_PET_DISMISS_SOUND` — a `CreatureModelData` id and the point to play its column-29
-    /// kit at. No guid: the pet is already gone.
+    /// `SMSG_PET_DISMISS_SOUND`: a `CreatureModelData` id whose column-29 kit plays at `position`.
     PetDismissSound {
         model_id: u32,
         position: Vector3d,
     },
-    /// `SMSG_ATTACKSTART` — a unit began melee auto-attack (including our own echo).
+    /// `SMSG_ATTACKSTART`: a unit began melee auto-attack, our own echo included.
     AttackStart {
         attacker: u64,
         victim: u64,
     },
-    /// `SMSG_ATTACKSTOP` — a unit stopped melee auto-attack.
+    /// `SMSG_ATTACKSTOP`: a unit stopped melee auto-attack.
     AttackStop {
         attacker: u64,
         victim: u64,
     },
-    /// `SMSG_ATTACKERSTATEUPDATE` — one completed melee swing (decision 0073: the attacker's swing
-    /// animation trigger).
+    /// `SMSG_ATTACKERSTATEUPDATE`: one completed melee swing, the attacker's swing-animation cue.
     AttackerState(AttackerState),
-    /// The server refused our `CMSG_ATTACKSWING` — `SMSG_ATTACKSWING_NOTINRANGE` (`0x145`),
-    /// `_BADFACING` (`0x146`), `_DEADTARGET` (`0x148`) or `_CANT_ATTACK` (`0x149`), collapsed to
-    /// the three arms the reference actually wires (see [`AttackSwingError`]). Empty bodies.
+    /// The server refused our `CMSG_ATTACKSWING` (`SMSG_ATTACKSWING_*` `0x145`, `0x146`, `0x148`,
+    /// `0x149`, all empty), collapsed to the three arms the reference wires.
     AttackSwingError(AttackSwingError),
-    /// `SMSG_CANCEL_COMBAT` (`0x14e`) — the server forced our attack to stop. Empty body; the
-    /// reference's handler `0x5e7dd0` is arm 4's body verbatim (StopAttack, no message).
+    /// `SMSG_CANCEL_COMBAT` (`0x14e`, empty): stop our attack, no message (reference `0x5e7dd0`).
     CancelCombat,
-    /// `SMSG_FEIGN_DEATH_RESISTED` (`0x2b4`) — the target resisted our Feign Death. Empty body;
-    /// the reference's handler `0x6e9800` is a bare `DisplayError(421)`.
+    /// `SMSG_FEIGN_DEATH_RESISTED` (`0x2b4`, empty): a bare `DisplayError(421)` (`0x6e9800`).
     FeignDeathResisted,
-    /// `SMSG_AI_REACTION` — a creature flared aggro (2 HOSTILE) or a stealth pre-aggro alert
-    /// (0 ALERT) at someone (layout in [`super::attack::read_ai_reaction`]; decision 0277).
+    /// `SMSG_AI_REACTION`: a creature's aggro flare (2 HOSTILE) or stealth alert (0 ALERT).
     AiReaction {
         unit: u64,
         reaction: u32,
     },
-    /// `SMSG_SPELL_START` — a non-triggered cast began, instants included (decision 0099 phase 1:
-    /// the precast trigger; layout in [`super::spells::read_spell_start`]).
+    /// `SMSG_SPELL_START`: a non-triggered cast began, instants included.
     SpellStart(SpellStart),
-    /// `SMSG_SPELL_GO` — the cast launched: hit/miss lists + (for a ranged spell) the ammo block.
-    /// The server schedules impact itself off `Spell.dbc` Speed — nothing about missile travel
-    /// rides this packet (layout in [`super::spells::read_spell_go`]).
+    /// `SMSG_SPELL_GO`: the cast launched, with hit and miss lists and a ranged spell's ammo;
+    /// missile travel is not on the wire, the server times impact off `Spell.dbc` Speed.
     SpellGo(SpellGo),
     SpellChainTargets(SpellChainTargets),
-    /// `SMSG_SPELL_FAILED_OTHER` — an observed cast was interrupted/cancelled (vmangos
-    /// `Spell::SendInterrupted`); our own cast's failure is [`Self::CastResult`] instead.
+    /// `SMSG_SPELL_FAILED_OTHER`: an observed cast was interrupted; ours is [`Self::CastResult`].
     SpellFailedOther {
         caster: u64,
         spell_id: u32,
     },
-    /// `SMSG_SPELL_DELAYED` — pushback: our own cast took damage and the server extended its timer
-    /// by `delay_ms` (vmangos `Spell::Delayed`). The cast bar slides its window out by the same, so
-    /// a hit pushes the bar back instead of letting it finish early (decision 0256).
+    /// `SMSG_SPELL_DELAYED`: pushback; a hit extended our cast by `delay_ms` (`Spell::Delayed`).
     SpellDelayed {
         caster: u64,
         delay_ms: u32,
     },
-    /// `SMSG_CANCEL_AUTO_REPEAT` — stop our own ranged auto-repeat visual; self-only, empty body
-    /// (vmangos `WorldPackets::Misc::CancelAutoRepeat`). Consumed by the local cancel funnel
-    /// (`net/apply/spells.rs::cancel_auto_repeat`, decision 2273). vmangos DOES send it —
-    /// `SpellCaster::InterruptSpell` → `Player::SendAutoRepeatCancel`, on every player autorepeat
-    /// interrupt, target death included (corrected 2026-08-05; the earlier "zero send sites" note
-    /// here was wrong).
+    /// `SMSG_CANCEL_AUTO_REPEAT` (self-only, empty): stop our ranged auto-repeat; vmangos sends it
+    /// on every autorepeat interrupt, target death included (`Player::SendAutoRepeatCancel`).
     CancelAutoRepeat,
-    /// `SMSG_SPELL_COOLDOWN` — server-pushed cooldowns for the player or pet, by caster guid
-    /// (layout + the `cooldown_ms == 0` "use Spell.dbc" fork in [`super::spellbook::read_spell_cooldown`];
-    /// decision 0137 phase 4).
+    /// `SMSG_SPELL_COOLDOWN`: server-pushed cooldowns for the player or pet, by caster guid.
     SpellCooldownList {
         caster: u64,
-        /// `(spell_id, cooldown_ms)` — `0` ms = the spell's own DBC recovery/category times.
+        /// `(spell_id, cooldown_ms)`; `0` ms means the spell's own DBC recovery and category times.
         cooldowns: Vec<(u32, u32)>,
     },
-    /// `SMSG_ITEM_COOLDOWN` — put an item (by instance guid) on the client's fixed 30 s use
-    /// cooldown for its on-use spell (layout in [`super::spellbook::read_item_cooldown`]).
+    /// `SMSG_ITEM_COOLDOWN`: put an item instance on the client's fixed 30 s on-use cooldown.
     ItemCooldown {
         item_guid: u64,
         spell_id: u32,
     },
-    /// `SMSG_ITEM_TIME_UPDATE` — how long one duration-limited item instance has left, in
-    /// **seconds** (layout in [`super::items::read_item_time`]). Decision 1933.
+    /// `SMSG_ITEM_TIME_UPDATE`: a duration-limited item instance's time left, in seconds.
     ItemTime {
         item_guid: u64,
         seconds: u32,
     },
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE` — how long one item's TEMPORARY enchant has left (layout in
-    /// [`super::items::read_item_enchant_time`]). The tooltip's countdown has no other source
-    /// (decision 0920).
+    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE`: a temporary enchant's time left, the tooltip's only source.
     ItemEnchantTime {
         item_guid: u64,
         slot: u32,
         seconds: u32,
     },
-    /// `SMSG_SET_FLAT_SPELL_MODIFIER` / `SMSG_SET_PCT_SPELL_MODIFIER` — one cell of one of the two
-    /// talent spell-modifier tables, absolutely (layout + the index law in
-    /// [`super::spells::read_set_spell_modifier`]).
-    ///
-    /// One variant for both opcodes because the reference has one handler for both
-    /// (`0x6e9950`), reading the identical body and forking on the opcode alone to pick the table
-    /// — so `flat` IS the opcode, and nothing else differs.
+    /// `SMSG_SET_FLAT_SPELL_MODIFIER` / `SMSG_SET_PCT_SPELL_MODIFIER`: one absolute cell of a
+    /// talent modifier table; one handler reads both (`0x6e9950`) and the opcode picks the table.
     SpellModifier {
-        /// `true` = `0x266`, the FLAT table (summed and added); `false` = `0x267`, the PCT table
-        /// (summed, then `+100`, clamped at 0, then used as a raw multiplier).
+        /// `true`: `0x266`, the flat table (summed, added). `false`: `0x267`, the percent table
+        /// (summed, plus 100, clamped at 0, then a raw multiplier).
         flat: bool,
-        /// The spell's `SpellFamilyFlags` **bit index**, 0..=63 — the table's row. The wire does
-        /// not bound it (the reference's own store overruns into the neighbouring global on a
-        /// 64); the consumer refuses it.
+        /// The row: a `SpellFamilyFlags` bit index, 0..=63, unbounded on the wire. Deviation: the
+        /// consumer refuses 64 and up, because there the reference's store overruns its table.
         mask_bit: u8,
-        /// The SpellModOp, 0..=28 — the table's column. Likewise unbounded on the wire.
+        /// The column: a SpellModOp, 0..=28, also unbounded on the wire.
         op: u8,
-        /// The cell's new value, **signed** and **absolute** — never a delta.
+        /// The cell's new value, signed and absolute, never a delta.
         value: i32,
     },
-    /// `SMSG_COOLDOWN_EVENT` — start an on-hold (`SPELL_ATTR_COOLDOWN_ON_EVENT`) cooldown's
-    /// parked timers now (layout in [`super::spellbook::read_cooldown_event`]).
+    /// `SMSG_COOLDOWN_EVENT`: start a parked `SPELL_ATTR_COOLDOWN_ON_EVENT` cooldown now.
     CooldownEvent {
         spell_id: u32,
         caster: u64,
     },
-    /// `SMSG_CLEAR_COOLDOWN` — remove one spell's cooldown record outright (same body shape as
-    /// [`Self::CooldownEvent`]).
+    /// `SMSG_CLEAR_COOLDOWN`: remove one spell's cooldown record outright.
     ClearCooldown {
         spell_id: u32,
         caster: u64,
     },
-    /// `SMSG_COOLDOWN_CHEAT` — wipe every cooldown for the named unit (the GM reset).
+    /// `SMSG_COOLDOWN_CHEAT`: wipe every cooldown for the named unit (the GM reset).
     CooldownCheat {
         caster: u64,
     },
-    /// `MSG_CHANNEL_START` — our own channeled cast opened (self-only; no guid on the wire). The
-    /// cast bar's channel-open edge (decision 0137).
+    /// `MSG_CHANNEL_START`: our own channel opened (self-only, no guid on the wire).
     ChannelStart {
         spell_id: u32,
         duration_ms: u32,
     },
-    /// `MSG_CHANNEL_UPDATE` — our own channel's time left; `0` = over (natural end and interrupt
-    /// alike). Self-only (decision 0137).
+    /// `MSG_CHANNEL_UPDATE` (self-only): our channel's time left; `0` ends it, end or interrupt.
     ChannelUpdate {
         remaining_ms: u32,
     },
-    /// `SMSG_UPDATE_AURA_DURATION` — how long one of **our own** auras has left, keyed by its
-    /// `UNIT_FIELD_AURA` slot. Self-only, never sent for a permanent aura, and it arrives *before*
-    /// the descriptor delta that says which spell occupies the slot — so a consumer buffers it by
-    /// slot and joins on `(slot, spell_id)` (decision 0255).
+    /// `SMSG_UPDATE_AURA_DURATION` (self-only, never for a permanent aura): one aura slot's time
+    /// left. It arrives before the delta naming the slot's spell, so buffer it by slot.
     UpdateAuraDuration {
         slot: u8,
         remaining_ms: u32,
     },
-    /// `SMSG_PLAY_SPELL_VISUAL` — play a spell-visual kit on a unit outside the normal cast
-    /// sequence, at the client's hardcoded stage 0 (the eat/drink kit cadence, mid-channel kit
-    /// swaps — decision 0280).
+    /// `SMSG_PLAY_SPELL_VISUAL`: a spell-visual kit on a unit outside a cast, at the fixed stage 0.
     PlaySpellVisual {
         unit: u64,
         kit_id: u32,
     },
-    /// `SMSG_SPELLNONMELEEDAMAGELOG` — non-melee (spell) damage dealt (decision 0137 phase 2's
-    /// floating-combat-text data feed; layout in [`super::combat_log::read_spell_damage_log`]).
+    /// `SMSG_SPELLNONMELEEDAMAGELOG`: non-melee (spell) damage dealt.
     SpellDamageLog(SpellDamageLog),
-    /// `SMSG_PERIODICAURALOG` — periodic (DoT/HoT/regen) aura ticks (decision 0137 phase 2; layout
-    /// in [`super::combat_log::read_periodic_aura_log`]).
+    /// `SMSG_PERIODICAURALOG`: periodic (DoT, HoT, regen) aura ticks.
     PeriodicAuraLog(PeriodicAuraLog),
-    /// `SMSG_SPELLHEALLOG` — a direct heal landing (decision 0578's center-combat-text feed;
-    /// layout in [`super::combat_log::read_spell_heal_log`]).
+    /// `SMSG_SPELLHEALLOG`: a direct heal landing.
     SpellHealLog(SpellHealLog),
-    /// `SMSG_SPELLENERGIZELOG` — an instant power gain (decision 0578; layout in
-    /// [`super::combat_log::read_spell_energize_log`]).
+    /// `SMSG_SPELLENERGIZELOG`: an instant power gain.
     SpellEnergizeLog(SpellEnergizeLog),
-    /// `SMSG_SPELLDAMAGESHIELD` — a damage-shield (Thorns-style) return hit (decision 0137 phase 2;
-    /// layout in [`super::combat_log::read_damage_shield`]).
+    /// `SMSG_SPELLDAMAGESHIELD`: a damage-shield (Thorns-style) return hit.
     DamageShield(DamageShield),
-    /// `SMSG_ENVIRONMENTALDAMAGELOG` — environmental damage taken (fall/drowning/…; layout in
-    /// [`super::combat_log::read_environmental_damage_log`]).
+    /// `SMSG_ENVIRONMENTALDAMAGELOG`: environmental damage taken (falling, drowning, …).
     EnvironmentalDamageLog(EnvironmentalDamageLog),
-    /// `SMSG_SPELLLOGMISS` — a spell cast's per-target miss list (decision 0137 phase 2; layout in
-    /// [`super::combat_log::read_spell_log_miss`]).
+    /// `SMSG_SPELLLOGMISS`: a cast's per-target miss list.
     SpellLogMiss(SpellLogMiss),
-    /// `SMSG_PARTYKILLLOG` — the killing blow (decision 1703; layout in
-    /// [`super::combat_log::read_party_kill_log`]).
+    /// `SMSG_PARTYKILLLOG`: the killing blow.
     PartyKillLog(PartyKillLog),
-    /// `SMSG_SPELLINSTAKILLLOG` — an instant kill (decision 1703; layout in
-    /// [`super::combat_log::read_spell_insta_kill_log`]).
+    /// `SMSG_SPELLINSTAKILLLOG`: an instant kill.
     SpellInstaKillLog(SpellInstaKillLog),
-    /// `SMSG_PROCRESIST` — a proc the target resisted (decision 1703; layout in
-    /// [`super::combat_log::read_spell_outcome_log`]).
+    /// `SMSG_PROCRESIST`: a proc the target resisted.
     ProcResist(SpellOutcomeLog),
-    /// `SMSG_SPELLORDAMAGE_IMMUNE` — a target immune to the spell (decision 1703; the same body as
-    /// [`Self::ProcResist`], a different sentence).
+    /// `SMSG_SPELLORDAMAGE_IMMUNE`: a target immune to the spell.
     SpellOrDamageImmune(SpellOutcomeLog),
-    /// `SMSG_SPELLDISPELLOG` — the auras a dispel removed (decision 1703; layout in
-    /// [`super::combat_log::read_spell_dispel_log`]).
+    /// `SMSG_SPELLDISPELLOG`: the auras a dispel removed.
     SpellDispelLog(SpellDispelLog),
-    /// `SMSG_DISPEL_FAILED` — the auras a dispel failed to remove (decision 1703; layout in
-    /// [`super::combat_log::read_dispel_failed`]).
+    /// `SMSG_DISPEL_FAILED`: the auras a dispel failed to remove.
     DispelFailed(DispelFailed),
-    /// `SMSG_ENCHANTMENTLOG` — an enchant landing on or fading from an item (decision 1703; layout
-    /// in [`super::combat_log::read_enchantment_log`]).
+    /// `SMSG_ENCHANTMENTLOG`: an enchant landing on or fading from an item.
     EnchantmentLog(EnchantmentLog),
-    /// `SMSG_SPELLLOGEXECUTE` — what a cast's effects did: created items, interrupts, extra
-    /// attacks, power drains, durability damage (decision 1703; layout in
-    /// [`super::combat_log::read_spell_log_execute`]).
+    /// `SMSG_SPELLLOGEXECUTE`: what a cast's effects did: created items, interrupts, drains, ….
     SpellLogExecute(SpellLogExecute),
-    /// `SMSG_LOG_XPGAIN` — an XP award, kill or non-kill (decision 0137 phase 2; layout in
-    /// [`super::progression::read_xp_gain`]).
+    /// `SMSG_LOG_XPGAIN`: an XP award, kill or non-kill.
     XpGain(XpGain),
-    /// `SMSG_EXPLORATION_EXPERIENCE` — a first visit to an area: the discovered area id + its XP
-    /// award (decision 0828; layout in [`super::progression::read_exploration_xp`]).
+    /// `SMSG_EXPLORATION_EXPERIENCE`: a first visit to an area, its id and XP award.
     ExplorationXp(ExplorationXp),
-    /// `SMSG_LEVELUP_INFO` — our own ding, self-addressed only (decision 0304; layout in
-    /// [`super::progression::read_level_up_info`]).
+    /// `SMSG_LEVELUP_INFO`: our own level-up, self-addressed only.
     LevelUp(LevelUpInfo),
-    /// `SMSG_QUESTGIVER_STATUS` — the questgiver dialog status for one NPC (`!`/`?` marker), a
-    /// [`super::quest::dialog_status`] value. A world-marker concern (out of the panel slice, decision
-    /// 0088): parsed + surfaced per guid now, rendered later.
+    /// `SMSG_QUESTGIVER_STATUS`: one NPC's `!`/`?` marker, a [`super::quest::dialog_status`] value.
     QuestGiverStatus {
         npc: u64,
         status: u32,
     },
-    /// `SMSG_QUESTGIVER_QUEST_LIST` — the greeting panel: an NPC's offered/active quest rows
-    /// (layout in [`super::quest::read_questgiver_quest_list`]).
+    /// `SMSG_QUESTGIVER_QUEST_LIST`: the greeting panel, an NPC's offered and active quests.
     QuestGiverQuestList(QuestGiverList),
-    /// `SMSG_QUESTGIVER_QUEST_DETAILS` — the accept panel: full quest text + rewards on offer
-    /// (layout in [`super::quest::read_questgiver_quest_details`]).
+    /// `SMSG_QUESTGIVER_QUEST_DETAILS`: the accept panel, full quest text and rewards.
     QuestGiverDetails(QuestDetails),
-    /// `SMSG_QUESTGIVER_REQUEST_ITEMS` — the progress panel: the "bring me these" text + required
-    /// items and the completability flag (layout in [`super::quest::read_questgiver_request_items`]).
+    /// `SMSG_QUESTGIVER_REQUEST_ITEMS`: the progress panel, required items and completability.
     QuestGiverRequestItems(QuestRequestItems),
-    /// `SMSG_QUESTGIVER_OFFER_REWARD` — the reward panel: turn-in text + rewards to grant (layout in
-    /// [`super::quest::read_questgiver_offer_reward`]).
+    /// `SMSG_QUESTGIVER_OFFER_REWARD`: the reward panel, turn-in text and rewards.
     QuestGiverOfferReward(QuestOfferReward),
-    /// `SMSG_QUESTGIVER_QUEST_COMPLETE` — the turn-in result: XP/money granted + fixed items
-    /// (layout in [`super::quest::read_questgiver_quest_complete`]).
+    /// `SMSG_QUESTGIVER_QUEST_COMPLETE`: the turn-in result, XP, money and fixed items.
     QuestGiverComplete(QuestComplete),
-    /// `SMSG_QUESTGIVER_QUEST_INVALID` (vmangos `Quest.cpp:126`) — the accept/query attempt was
-    /// rejected before a details/failed panel could be built; `msg` is a client message code.
+    /// `SMSG_QUESTGIVER_QUEST_INVALID` (`Quest.cpp:126`): accept or query refused; `msg` says why.
     QuestGiverInvalid {
         msg: u32,
     },
-    /// `SMSG_QUESTGIVER_QUEST_FAILED` (vmangos `Quest.cpp:110`) — a `CMSG_QUESTGIVER_ACCEPT_QUEST`
-    /// (or an in-progress requirement) failed; `reason` is a client `QuestFailedReason` code.
+    /// `SMSG_QUESTGIVER_QUEST_FAILED` (`Quest.cpp:110`): `reason` is a `QuestFailedReason` code.
     QuestGiverFailed {
         quest_id: u32,
         reason: u32,
     },
-    /// `SMSG_QUEST_QUERY_RESPONSE` — the full quest template, answering `CMSG_QUEST_QUERY`; feeds
-    /// the quest-log detail view (layout + wire-trap notes on [`QuestTemplate`]). Boxed: at 400+
-    /// bytes (four fixed-count arrays plus five strings) it would otherwise dwarf every other
-    /// `ServerPacket` variant and bloat the whole enum.
+    /// `SMSG_QUEST_QUERY_RESPONSE`: the full quest template (400+ bytes, hence boxed).
     QuestQueryResponse(Box<QuestTemplate>),
-    /// `SMSG_QUESTLOG_FULL` — the log has no free slot for a new quest; empty body (vmangos
-    /// `Quest.cpp:87`).
+    /// `SMSG_QUESTLOG_FULL`: no free log slot for a new quest; empty body (`Quest.cpp:87`).
     QuestLogFull,
-    /// `MSG_QUEST_PUSH_RESULT` — one party member's verdict on a quest we shared, relayed to the
-    /// SHARER (layout + the direction trap on [`QuestPushResult`], decision 1733). Arrives once per
-    /// member per push, and more than once per member: the server opens with `SHARING_QUEST` and
-    /// then sends the real outcome.
+    /// `MSG_QUEST_PUSH_RESULT`: a member's verdict on a quest we shared, sent to the sharer; per
+    /// member the server sends `SHARING_QUEST` first, then the real outcome.
     QuestPushResult(QuestPushResult),
-    /// `SMSG_QUEST_CONFIRM_ACCEPT` — a party member started a `QUEST_FLAGS_PARTY_ACCEPT` (escort)
-    /// quest and we are being asked whether to start it too (layout in [`QuestConfirmAccept`]).
+    /// `SMSG_QUEST_CONFIRM_ACCEPT`: join a member's `QUEST_FLAGS_PARTY_ACCEPT` (escort) quest?
     QuestConfirmAccept(QuestConfirmAccept),
-    /// `SMSG_QUESTUPDATE_COMPLETE` — every objective on this quest is now complete (vmangos
-    /// `Quest.cpp:91`); the log slot's state byte gets `QUEST_STATE_COMPLETE`.
+    /// `SMSG_QUESTUPDATE_COMPLETE`: all objectives done; the slot becomes `QUEST_STATE_COMPLETE`.
     QuestUpdateComplete {
         quest_id: u32,
     },
-    /// `SMSG_QUESTUPDATE_FAILED` — the quest failed outright (vmangos `Quest.cpp:116`).
+    /// `SMSG_QUESTUPDATE_FAILED`: the quest failed outright (`Quest.cpp:116`).
     QuestUpdateFailed {
         quest_id: u32,
     },
-    /// `SMSG_QUESTUPDATE_FAILEDTIMER` — a timed quest's clock ran out (vmangos `Quest.cpp:121`).
+    /// `SMSG_QUESTUPDATE_FAILEDTIMER`: a timed quest's clock ran out (`Quest.cpp:121`).
     QuestUpdateFailedTimer {
         quest_id: u32,
     },
-    /// `SMSG_QUESTUPDATE_ADD_KILL` — a kill/use toast for a creature-or-gameobject objective
-    /// (vmangos `Quest.cpp:144`); `entry` carries the same raw creature/GO encoding as
-    /// [`super::quest::QuestObjective::creature_or_go`], and mirrors (doesn't replace) the durable
-    /// `PLAYER_QUEST_LOG` counter field.
+    /// `SMSG_QUESTUPDATE_ADD_KILL`: a kill or use toast, `entry` encoded as
+    /// [`super::quest::QuestObjective::creature_or_go`]; the durable count is `PLAYER_QUEST_LOG`.
     QuestUpdateAddKill {
         quest_id: u32,
         entry: u32,
@@ -954,290 +722,221 @@ pub enum ServerPacket {
         required: u32,
         guid: u64,
     },
-    /// `SMSG_QUESTUPDATE_ADD_ITEM` — an item-collection toast (vmangos `Quest.cpp:138`).
+    /// `SMSG_QUESTUPDATE_ADD_ITEM`: an item-collection toast (`Quest.cpp:138`).
     QuestUpdateAddItem {
         item_id: u32,
         count: u32,
     },
-    /// `SMSG_GOSSIP_MESSAGE` — a gossip menu opened on an NPC, answering our `CMSG_GOSSIP_HELLO` (or
-    /// riding a `CMSG_GOSSIP_SELECT_OPTION` reply that re-opens the menu). Payload VERIFIED vmangos
-    /// `GossipDef.cpp:180-225` (the 1.12 shape — no box-money field, that's TBC+); `text_id` drives a
-    /// follow-up `CMSG_NPC_TEXT_QUERY` for the greeting body. `quests` carries the quest-option rows
-    /// riding the same packet (wired to the questgiver panels — decision 0088).
+    /// `SMSG_GOSSIP_MESSAGE`: an NPC's gossip menu and quest rows (`GossipDef.cpp:180-225`, no
+    /// box-money field in 1.12); `text_id` is for a follow-up `CMSG_NPC_TEXT_QUERY`.
     GossipMessage {
         npc: u64,
         text_id: u32,
         options: Vec<GossipOption>,
         quests: Vec<QuestOption>,
     },
-    /// `SMSG_GOSSIP_COMPLETE` — the gossip window closes (vmangos `Npc.cpp:90`); an empty body.
+    /// `SMSG_GOSSIP_COMPLETE`: the gossip window closes; empty body (`Npc.cpp:90`).
     GossipComplete,
-    /// `SMSG_GOSSIP_POI` — the marker a guard drops when you ask for directions (vmangos
-    /// `GossipDef.cpp:253`). Volunteered, never requested.
+    /// `SMSG_GOSSIP_POI`: a guard's directions marker, unrequested (`GossipDef.cpp:253`).
     GossipPoi(GossipPoi),
-    /// `SMSG_NPC_TEXT_UPDATE` — answers `CMSG_NPC_TEXT_QUERY`: always 8 weighted text blocks
-    /// (vmangos `GossipDef.cpp:298-369`), carried here **undecided**. Which line greets you needs
-    /// the NPC's gender and a die roll, so it is drawn when the frame opens, not when the packet
-    /// lands — [`super::gossip::select_greeting`].
+    /// `SMSG_NPC_TEXT_UPDATE`: always 8 weighted text blocks (`GossipDef.cpp:298-369`), kept
+    /// undrawn; [`super::gossip::select_greeting`] picks one by gender and a roll at frame open.
     NpcText {
         text_id: u32,
         blocks: Vec<super::gossip::NpcTextBlock>,
     },
-    /// `SMSG_LIST_INVENTORY` — a vendor's stock, answering `CMSG_LIST_INVENTORY` (vmangos
-    /// `ItemHandler.cpp:741-810`). Empty stock sends `count = 0` plus one error byte (always 0,
-    /// "Vendor has no inventory") that the parser consumes and drops.
+    /// `SMSG_LIST_INVENTORY`: a vendor's stock (`ItemHandler.cpp:741-810`); an empty stock sends
+    /// `count = 0` and one error byte, always 0, which is dropped.
     VendorList {
         vendor: u64,
         items: Vec<VendorItem>,
     },
-    /// `SMSG_BUY_ITEM` — the vendor stock update after a purchase (vmangos `Item.cpp:190-196`); the
-    /// purchased item itself arrives via `UPDATE_OBJECT` + `SMSG_ITEM_PUSH_RESULT`, already handled.
+    /// `SMSG_BUY_ITEM`: the vendor's stock after a purchase (`Item.cpp:190-196`).
     BuyItem {
         vendor: u64,
         slot: u32,
         new_count: u32,
         purchase_count: u32,
     },
-    /// `SMSG_SELL_ITEM` — the **error** path only (vmangos `Item.cpp:183-188`, `SendSellError`
-    /// `Player.cpp:11723`); a successful sell sends nothing, visible only as the item vanishing +
-    /// coinage rising via `UPDATE_OBJECT`. `reason` is a [`super::vendor::sell_result`] code.
+    /// `SMSG_SELL_ITEM`: errors only (`Player.cpp:11723`), a [`super::vendor::sell_result`] code;
+    /// a successful sell sends nothing and shows only in the descriptors.
     SellItemResult {
         vendor: u64,
         item_guid: u64,
         reason: u8,
     },
-    /// `SMSG_BUY_FAILED` — the server refused a purchase (vmangos `Item.h:277`). `reason` is a
-    /// [`super::vendor::buy_result`] code.
+    /// `SMSG_BUY_FAILED`: a refused purchase, `reason` a [`super::vendor::buy_result`] code.
     BuyFailed {
         vendor: u64,
         item_entry: u32,
         reason: u8,
     },
-    /// `SMSG_SHOW_BANK` — the bank window opens, answering our `CMSG_BANKER_ACTIVATE` (vmangos
-    /// `Npc.cpp:94`) — or arriving unprompted for the `GOSSIP_OPTION_BANKER` gossip option
-    /// (`SendShowBank`, `Player.cpp:12426`); the handler must not assume it always follows our own
-    /// activate. The vault itself is already streamed via the ordinary player descriptor
-    /// (decision 0604) — this only opens the window.
+    /// `SMSG_SHOW_BANK`: open the bank window, answering `CMSG_BANKER_ACTIVATE` or unprompted
+    /// from the banker gossip option (`Player.cpp:12426`); the vault streams in the descriptor.
     ShowBank {
         banker: u64,
     },
-    /// `SMSG_BUY_BANK_SLOT_RESULT` — a bank-slot purchase was refused (vmangos `Item.cpp:137-140`).
-    /// `result` is a [`super::bank::bank_slot_result`] code; a *successful* buy sends no packet at
-    /// all, visible only as the `PLAYER_BYTES_2` bank-bag-count byte advancing + the coinage drop
-    /// (decision 0604).
+    /// `SMSG_BUY_BANK_SLOT_RESULT`: a refused slot purchase, a [`super::bank::bank_slot_result`];
+    /// success sends nothing, only `PLAYER_BYTES_2`'s bank-bag count advances.
     BuyBankSlotResult {
         result: u32,
     },
-    /// `SMSG_TRAINER_LIST` — a class/profession trainer's service list, reached through the gossip
-    /// trainer option (layout in [`super::trainer::read_trainer_list`], decision 0237). `trainer_type` is
-    /// the window-framing kind (0 class · 1 mount · 2 tradeskill · 3 pet); `title` is the greeting.
+    /// `SMSG_TRAINER_LIST`: services, greeting; `trainer_type` 0 class, 1 mount, 2 trade, 3 pet.
     TrainerList {
         trainer: u64,
         trainer_type: u32,
         services: Vec<TrainerSpell>,
         title: String,
     },
-    /// `SMSG_TRAINER_BUY_SUCCEEDED` — the trainer taught the service (vmangos `SendTrainingSuccess`);
-    /// confirmation + sound only — the learned spell arrives via `SMSG_LEARNED_SPELL`, and the
-    /// green→gray repaint needs a `CMSG_TRAINER_LIST` re-request.
+    /// `SMSG_TRAINER_BUY_SUCCEEDED`: confirmation and sound only; the spell arrives as
+    /// `SMSG_LEARNED_SPELL`, and repainting the list takes a fresh `CMSG_TRAINER_LIST`.
     TrainerBuySucceeded {
         trainer: u64,
         spell_id: u32,
     },
-    /// `SMSG_TRAINER_BUY_FAILED` — the trainer refused (vmangos `SendTrainingFailure`). `error` is a
-    /// [`super::trainer::train_fail`] code (0 unavailable · 1 not-enough-money · 2 not-enough-skill).
+    /// `SMSG_TRAINER_BUY_FAILED`: `error` is a [`super::trainer::train_fail`] code.
     TrainerBuyFailed {
         trainer: u64,
         spell_id: u32,
         error: u32,
     },
-    /// `MSG_LIST_STABLED_PETS` — the stable master's pet list (layout in
-    /// [`super::stable::read_list_stabled_pets`], decision 1676). Arrives **unprompted** when the
-    /// gossip stable option is chosen — that is how the window opens — and again in answer to our
-    /// own send of the same opcode, which is the only refresh there is (a successful mutation
-    /// answers with nothing but a [`Self::StableResult`] byte).
-    ///
-    /// `num_stable_slots` is how many stable slots the player has *bought* (0..=2), not how many
-    /// are occupied. `pets` carries the current pet **and** the stabled ones, each keyed by its own
-    /// already-rebased [`StabledPet::slot`] (`0` = current) — the current-pet row is absent for a
-    /// petless hunter or a warlock, so the list must be read by slot, never by position.
+    /// `MSG_LIST_STABLED_PETS`: opens the stable unprompted and is its only refresh when we send
+    /// it. `num_stable_slots` is slots bought (0..=2); `pets` must be read by
+    /// [`StabledPet::slot`] (`0` = current), never by position, as the current pet may be absent.
     ListStabledPets {
         npc: u64,
         num_stable_slots: u8,
         pets: Vec<StabledPet>,
     },
-    /// `SMSG_INVALIDATE_PLAYER` — drop this guid from the player-name cache (decision 1689). The
-    /// cache ages nothing out, so this packet is the only thing that unsticks a name short of a
-    /// reconnect; it matters more to benilla than to the reference only because ours now persists.
+    /// `SMSG_INVALIDATE_PLAYER`: drop this guid from the player-name cache, which ages nothing out.
     InvalidatePlayer {
         guid: u64,
     },
-    /// `SMSG_STABLE_RESULT` — the whole answer to a stable/unstable/swap/buy-slot ask (vmangos
-    /// `StableResult::AppendBodyTo`). `result` is a [`super::stable::stable_result`] code; success
-    /// codes carry no updated list, so repainting the window takes a fresh
-    /// `MSG_LIST_STABLED_PETS` send.
+    /// `SMSG_STABLE_RESULT`: the whole answer to a stable ask, a [`super::stable::stable_result`]
+    /// code; success carries no list, so a repaint takes a fresh `MSG_LIST_STABLED_PETS`.
     StableResult {
         result: u8,
     },
-    /// `SMSG_LOOT_RESPONSE`, normal shape — a loot window opened, answering `CMSG_LOOT` (layout in
-    /// [`super::loot::read_loot_response`]). `loot_type` is a [`super::loot::loot_type`] code; `items` includes
-    /// any quest-item rows riding the same list.
+    /// `SMSG_LOOT_RESPONSE`, normal shape: a loot window opened. `loot_type` is a
+    /// [`super::loot::loot_type`] code; `items` includes quest-item rows.
     LootResponse {
         guid: u64,
         loot_type: u8,
         gold: u32,
         items: Vec<LootItem>,
     },
-    /// `SMSG_LOOT_RESPONSE`, error shape — the server refused to open the loot window (didn't
-    /// kill it, too far, not standing, …). `error` is a [`super::loot::loot_error`] code.
+    /// `SMSG_LOOT_RESPONSE`, error shape: `error` is a [`super::loot::loot_error`] code.
     LootError {
         guid: u64,
         error: u8,
     },
-    /// `SMSG_LOOT_RELEASE_RESPONSE` — the loot window closes, answering `CMSG_LOOT_RELEASE`.
-    /// `result` is always `1` (vmangos never sends another value).
+    /// `SMSG_LOOT_RELEASE_RESPONSE`: the loot window closes; vmangos always sends `result` 1.
     LootReleaseResponse {
         guid: u64,
         result: u8,
     },
-    /// `SMSG_LOOT_REMOVED` — one loot-window row was taken, by anyone.
+    /// `SMSG_LOOT_REMOVED`: one loot-window row was taken, by anyone.
     LootRemoved {
         slot: u8,
     },
-    /// `SMSG_LOOT_MONEY_NOTIFY` — our share of the loot's coin pile, answering `CMSG_LOOT_MONEY`.
+    /// `SMSG_LOOT_MONEY_NOTIFY`: our share of the loot's coin pile, answering `CMSG_LOOT_MONEY`.
     LootMoneyNotify {
         amount: u32,
     },
-    /// `SMSG_LOOT_CLEAR_MONEY` — the coin line disappears for every current looter; empty body.
+    /// `SMSG_LOOT_CLEAR_MONEY`: the coin line disappears for every current looter; empty body.
     LootClearMoney,
-    /// `SMSG_LOOT_START_ROLL` — a group roll opened on one drop (layout in [`LootStartRoll`]);
-    /// drives a `GroupLootFrame`.
+    /// `SMSG_LOOT_START_ROLL`: a group roll opened on one drop, a `GroupLootFrame`.
     LootStartRoll(LootStartRoll),
-    /// `SMSG_LOOT_ROLL` — one roller's vote or dice result (layout, and the overloaded
-    /// `(roll_number, roll_type)` pair, in [`LootRoll`]).
+    /// `SMSG_LOOT_ROLL`: one roller's vote or dice result.
     LootRoll(LootRoll),
-    /// `SMSG_LOOT_ROLL_WON` — a group roll resolved (layout in [`LootRollWon`]).
+    /// `SMSG_LOOT_ROLL_WON`: a group roll resolved.
     LootRollWon(LootRollWon),
-    /// `SMSG_LOOT_ALL_PASSED` — everyone passed; the roll closes and the item returns to the
-    /// corpse for ordinary looting (layout in [`LootAllPassed`]).
+    /// `SMSG_LOOT_ALL_PASSED`: everyone passed; the item goes back to ordinary corpse looting.
     LootAllPassed(LootAllPassed),
-    /// `SMSG_LOOT_MASTER_LIST` — the group members eligible to be handed an item from the loot
-    /// window that is opening (layout in [`super::loot::read_loot_master_list`]). It precedes the
-    /// `SMSG_LOOT_RESPONSE` it belongs to.
+    /// `SMSG_LOOT_MASTER_LIST`: master-loot candidates; precedes its `SMSG_LOOT_RESPONSE`.
     LootMasterList {
         candidates: Vec<u64>,
     },
-    /// `SMSG_ITEM_PUSH_RESULT` — an item landed in our bags (looted or received from an NPC);
-    /// drives the "You receive loot: …" chat line (layout in [`ItemPushResult`]).
+    /// `SMSG_ITEM_PUSH_RESULT`: an item landed in our bags, the "You receive loot" line.
     ItemPushResult(ItemPushResult),
-    /// `MSG_CORPSE_QUERY`'s answer — where our corpse is (layout + the two-map split in
-    /// [`CorpseLocation`]); also pushed unprompted as not-found at bones-conversion.
+    /// `MSG_CORPSE_QUERY` answer: where our corpse is; pushed as not-found when it turns to bones.
     CorpseQuery(CorpseLocation),
-    /// `SMSG_CORPSE_RECLAIM_DELAY` — ms until the corpse can be reclaimed (sent at release +
-    /// at login-while-dead).
+    /// `SMSG_CORPSE_RECLAIM_DELAY`: ms until reclaim, sent at release and at a login while dead.
     CorpseReclaimDelay {
         delay_ms: u32,
     },
-    /// `SMSG_DURABILITY_DAMAGE_DEATH` — the 10% natural-death durability loss happened (empty
-    /// body); the red error-line cue.
+    /// `SMSG_DURABILITY_DAMAGE_DEATH` (empty): the 10% death durability loss, a red error line.
     DurabilityDamageDeath,
-    /// `SMSG_RESURRECT_REQUEST` — a resurrection offer (layout in [`ResurrectRequestBody`]).
+    /// `SMSG_RESURRECT_REQUEST`: a resurrection offer.
     ResurrectRequest(ResurrectRequestBody),
-    /// `SMSG_SPIRIT_HEALER_CONFIRM` — the spirit healer asks for the XP_LOSS-style confirm;
-    /// carries the NPC's guid (the eventual `CMSG_SPIRIT_HEALER_ACTIVATE` target).
+    /// `SMSG_SPIRIT_HEALER_CONFIRM`: the healer asks; `CMSG_SPIRIT_HEALER_ACTIVATE` targets `npc`.
     SpiritHealerConfirm {
         npc: u64,
     },
-    /// **A granted mover mode changed** — the ack'd movement-mode family (decision 0866): root,
-    /// water-walk, feather-fall or hover, granted or revoked on our mover. `apply` is the direction.
-    /// Must be acked with the echoed `counter` ([`MoveMode::ack_opcode`]) or the server never applies
-    /// the change and observers never see it.
+    /// Root, water-walk, feather-fall or hover granted (`apply`) or revoked on our mover. Unless
+    /// acked with `counter` ([`MoveMode::ack_opcode`]), the server never applies it.
     MoveMode {
         guid: u64,
         counter: u32,
         mode: MoveMode,
         apply: bool,
     },
-    /// **Some unit's movement mode changed** — the `SMSG_SPLINE_MOVE_*` twelve (decision 1780), the
-    /// observer half of [`Self::MoveMode`]'s family. A bare packed guid: no counter, **no ack**, and
-    /// `guid` is any unit — normally a creature, which is exactly the case the ack'd family cannot
-    /// reach. `apply` is always the direction of [`SplineMode::flag`]'s bit (the run/walk pair's
-    /// inversion is folded at the parse).
+    /// The twelve `SMSG_SPLINE_MOVE_*`: any unit's mode change, a bare packed guid with no ack.
+    /// `apply` is the direction of [`SplineMode::flag`]'s bit, run/walk inversion already folded.
     SplineMoveMode {
         guid: u64,
         mode: SplineMode,
         apply: bool,
     },
-    /// **The server aimed a knockback at our mover** (`SMSG_MOVE_KNOCK_BACK`, decision 1702) —
-    /// a ballistic launch it hands the controlling client to fly. `launch` is the packet's four
-    /// floats read into the launch quad they *are*: `cos_angle`/`sin_angle` the world-XY direction,
-    /// `xy_speed` the horizontal speed, `zspeed` the take-off vertical speed in the jump tail's
-    /// **down-positive** convention (negative = upward). The wire order is `vcos, vsin, speedXY,
-    /// speedZ` — NOT [`JumpInfo`]'s own `zspeed`-first serialization order, which is why this is a
-    /// read into the type rather than the type's own reader.
-    ///
-    /// Owes `CMSG_MOVE_KNOCK_BACK_ACK` with the echoed `counter` and a `MovementInfo` whose jump
-    /// tail is exactly this quad ([`opcode::SMSG_MOVE_KNOCK_BACK`]'s note has the server's checks).
+    /// `SMSG_MOVE_KNOCK_BACK`: a launch for our mover to fly, on the wire as `vcos, vsin, speedXY,
+    /// speedZ`, not [`JumpInfo`]'s `zspeed`-first order; `zspeed` is down-positive. Owes
+    /// `CMSG_MOVE_KNOCK_BACK_ACK` with `counter` and a jump tail of exactly this quad.
     KnockBack {
         guid: u64,
         counter: u32,
         launch: JumpInfo,
     },
-    /// `SMSG_LOGOUT_COMPLETE` — the world session is over; we are back at character select.
+    /// `SMSG_LOGOUT_COMPLETE`: the world session is over; we are back at character select.
     LogoutComplete,
-    /// `SMSG_LOGOUT_RESPONSE` — the server's answer to `CMSG_LOGOUT_REQUEST`, and the ONLY thing
-    /// that decides whether logging out is instant or a countdown. Body `{u32 reason, u8 instant}`
-    /// (vmangos `WorldPackets::Misc::LogoutResponse`; the real client reads the same pair — wow-re
-    /// `system/net/ledger.tsv` 0x5b4630 `Handle(0x4c) — {u32, u8}`).
-    ///
-    /// `reason` non-zero is a REFUSAL and no logout starts (vmangos `HandleLogoutRequestOpcode`:
-    /// 1 in combat, 3 jumping/falling, 2 GM-frozen). `instant` is set when the server logs you out
-    /// on the spot — resting (an inn or a city), on a taxi, or a GM account — in which case
-    /// `LogoutComplete` follows immediately; otherwise a 20-second server-side timer runs, which is
-    /// what the client's CAMP/QUIT dialog counts down.
+    /// `SMSG_LOGOUT_RESPONSE`: `{u32 reason, u8 instant}` (reference `0x5b4630`). A non-zero
+    /// `reason` refuses (1 combat, 2 frozen, 3 falling); `instant` (resting, taxi, GM) means
+    /// `LogoutComplete` follows at once, else a 20 s server timer runs, the CAMP countdown.
     LogoutResponse {
         reason: u32,
         instant: bool,
     },
-    /// `SMSG_LOGOUT_CANCEL_ACK` — the server dropped a pending logout at our `CMSG_LOGOUT_CANCEL`.
-    /// Empty body; it is what takes the countdown dialog back down (`LOGOUT_CANCEL`).
+    /// `SMSG_LOGOUT_CANCEL_ACK` (empty): the logout was cancelled; it takes the countdown down.
     LogoutCancelAck,
-    /// `SMSG_PONG` — the echo of our `CMSG_PING`'s sequence number (the keepalive's return leg;
-    /// the io layer matches it against the ping clock to measure the round-trip).
+    /// `SMSG_PONG`: our `CMSG_PING`'s sequence echoed back, timed for the round trip.
     Pong {
         sequence: u32,
     },
-    /// A `SMSG_FORCE_*_SPEED_CHANGE` — the server changed one of our mover's six speeds (aura,
-    /// mount, GM `.modify speed`) and awaits the matching `CMSG_FORCE_*_SPEED_CHANGE_ACK` carrying
-    /// this `counter` + the exact `speed` back (see the opcode block's protocol note). `guid` is
-    /// the mover (packed on the wire); `speed` is flat yd/s (rad/s for the turn rate).
+    /// `SMSG_FORCE_*_SPEED_CHANGE`: one of our mover's six speeds, in yd/s (rad/s for turning);
+    /// owes the matching `_ACK` with `counter` and the exact `speed`.
     ForceSpeedChange {
         guid: u64,
         kind: SpeedKind,
         counter: u32,
         speed: f32,
     },
-    /// `SMSG_GROUP_INVITE` — someone invited us to their group (layout in
-    /// [`super::group::read_group_invite`]).
+    /// `SMSG_GROUP_INVITE`: someone invited us to their group.
     GroupInvite {
         inviter: String,
     },
-    /// `SMSG_GROUP_DECLINE` — an invite we sent was declined.
+    /// `SMSG_GROUP_DECLINE`: an invite we sent was declined.
     GroupDecline {
         name: String,
     },
-    /// `SMSG_GROUP_UNINVITE` — we were removed from our group (kicked or left); empty body.
+    /// `SMSG_GROUP_UNINVITE`: we were removed from our group (kicked or left); empty body.
     GroupUninvited,
-    /// `SMSG_GROUP_SET_LEADER` — the group's leader changed.
+    /// `SMSG_GROUP_SET_LEADER`: the group's leader changed.
     GroupLeaderChanged {
         name: String,
     },
-    /// `SMSG_GROUP_DESTROYED` — the group disbanded outright; empty body.
+    /// `SMSG_GROUP_DESTROYED`: the group disbanded outright; empty body.
     GroupDestroyed,
-    /// `SMSG_GROUP_LIST` — the full roster, sent on every membership change (layout in
-    /// [`super::group::read_group_list`]). `members` excludes the recipient's own row (`own_flags`
-    /// carries theirs); `loot` is `None` for the empty "you left" shape and whenever the list has
-    /// no other members.
+    /// `SMSG_GROUP_LIST`: the full roster on every change, without our own row (see `own_flags`);
+    /// `loot` is absent when there are no other members.
     GroupList {
         group_type: u8,
         own_flags: u8,
@@ -1245,274 +944,224 @@ pub enum ServerPacket {
         leader: u64,
         loot: Option<GroupLootInfo>,
     },
-    /// `SMSG_PARTY_COMMAND_RESULT` — the server's verdict on a group command we issued
-    /// (invite/leave): `operation` a [`super::group::party_operation`] code, `result` a
-    /// [`super::group::party_result`] code.
+    /// `SMSG_PARTY_COMMAND_RESULT`: `operation` a [`super::group::party_operation`], `result` a
+    /// [`super::group::party_result`].
     PartyCommandResult {
         operation: u32,
         member: String,
         result: u32,
     },
-    /// `SMSG_PARTY_MEMBER_STATS` / `_FULL` — a party/raid member's live stats for the frame
-    /// (layout in [`super::group::read_party_member_stats`]); `full` distinguishes the delta form
-    /// from the ask-once full form (our own [`super::group::request_party_member_stats`], or the
-    /// offline-miss reply). Boxed: [`PartyMemberStatsInfo`]'s ~20 optional fields would otherwise
-    /// dwarf every other variant here.
+    /// `SMSG_PARTY_MEMBER_STATS` (delta) or `_FULL` (answering our request, or an offline miss).
     PartyMemberStats {
         guid: u64,
         full: bool,
         info: Box<PartyMemberStatsInfo>,
     },
-    /// `MSG_MINIMAP_PING` — someone pinged the minimap for the group.
+    /// `MSG_MINIMAP_PING`: someone pinged the minimap for the group.
     MinimapPing {
         guid: u64,
         x: f32,
         y: f32,
     },
-    /// `MSG_RAID_TARGET_UPDATE`, delta shape — one raid-target icon changed; `guid == 0` clears it.
+    /// `MSG_RAID_TARGET_UPDATE`, delta shape: one raid-target icon changed; `guid == 0` clears it.
     RaidTargetSet {
         icon: u8,
         guid: u64,
     },
-    /// `MSG_RAID_TARGET_UPDATE`, full-list shape — the whole current icon set (only currently-set
-    /// icons are present).
+    /// `MSG_RAID_TARGET_UPDATE`, full shape: every icon currently set.
     RaidTargetList {
         entries: Vec<(u8, u64)>,
     },
-    /// `MSG_RAID_READY_CHECK`, empty body — the raid leader started a ready check.
+    /// `MSG_RAID_READY_CHECK`, empty body: the raid leader started a ready check.
     ReadyCheckRequest,
-    /// `MSG_RAID_READY_CHECK`, non-empty body — one member's answer, forwarded to the leader only.
+    /// `MSG_RAID_READY_CHECK`, non-empty body: one member's answer, forwarded to the leader only.
     ReadyCheckAnswer {
         guid: u64,
         ready: u8,
     },
-    /// `SMSG_RAID_INSTANCE_INFO` — our saved raid lockouts, answering `CMSG_REQUEST_RAID_INFO`
-    /// (decision 1549). Empty is the ordinary answer for a character bound to nothing.
+    /// `SMSG_RAID_INSTANCE_INFO`: our saved raid lockouts, answering `CMSG_REQUEST_RAID_INFO`.
     RaidInstanceInfo {
         entries: Vec<super::group::RaidInstanceEntry>,
     },
-    /// `SMSG_RAID_INSTANCE_MESSAGE` — a raid lockout's welcome/countdown line (decision 1748).
+    /// `SMSG_RAID_INSTANCE_MESSAGE`: a raid lockout's welcome or countdown line.
     RaidInstanceMessage {
         message: super::instance::RaidInstanceMessage,
     },
-    /// `SMSG_INSTANCE_SAVE_CREATED` — "you are now saved to this instance". vmangos always sends
-    /// `0`; the flag is kept raw because the client's `== 1` arm is a different line.
+    /// `SMSG_INSTANCE_SAVE_CREATED`: "now saved"; vmangos sends 0 (the client's `1` line differs).
     InstanceSaveCreated {
         flag: u32,
     },
-    /// `SMSG_INSTANCE_RESET` — the reset took; the payload is the `Map.dbc` id that was reset.
+    /// `SMSG_INSTANCE_RESET`: the reset took; the payload is the `Map.dbc` id that was reset.
     InstanceReset {
         map: u32,
     },
-    /// `SMSG_INSTANCE_RESET_FAILED` — the reset was refused (decision 1748).
+    /// `SMSG_INSTANCE_RESET_FAILED`: the reset was refused.
     InstanceResetFailed {
         failure: super::instance::InstanceResetFailed,
     },
-    /// `SMSG_UPDATE_LAST_INSTANCE` — the `Map.dbc` id of the dungeon we were last in.
+    /// `SMSG_UPDATE_LAST_INSTANCE`: the `Map.dbc` id of the dungeon we were last in.
     UpdateLastInstance {
         map: u32,
     },
-    /// `SMSG_UPDATE_INSTANCE_OWNERSHIP` — non-zero while we hold at least one permanent bind.
+    /// `SMSG_UPDATE_INSTANCE_OWNERSHIP`: non-zero while we hold at least one permanent bind.
     UpdateInstanceOwnership {
         owns: u32,
     },
-    /// `SMSG_DUEL_REQUESTED` — a duel challenge. Sent to challenger and challenged alike; which
-    /// one we are is `challenger == our guid` (decision 0633).
+    /// `SMSG_DUEL_REQUESTED`: sent to both sides; we issued it when `challenger` is our guid.
     DuelRequested {
         arbiter: u64,
         challenger: u64,
     },
-    /// `SMSG_DUEL_OUTOFBOUNDS` — we left the 75 yd bubble around the duel flag; 10 s to return.
+    /// `SMSG_DUEL_OUTOFBOUNDS`: we left the 75 yd bubble around the duel flag; 10 s to return.
     DuelOutOfBounds,
-    /// `SMSG_DUEL_INBOUNDS` — we came back inside (70 yd, the hysteresis edge).
+    /// `SMSG_DUEL_INBOUNDS`: we came back inside (70 yd, the hysteresis edge).
     DuelInBounds,
-    /// `SMSG_DUEL_COMPLETE` — the duel is over. `started` is false only when it ended before it
-    /// began (declined/cancelled), which is what earns the "Duel cancelled." line.
+    /// `SMSG_DUEL_COMPLETE`: `started` false means declined or cancelled ("Duel cancelled.").
     DuelComplete {
         started: bool,
     },
-    /// `SMSG_DUEL_WINNER` — the outcome line, broadcast to everyone nearby.
+    /// `SMSG_DUEL_WINNER`: the outcome line, broadcast to everyone nearby.
     DuelWinner {
         fled: bool,
         winner: String,
         loser: String,
     },
-    /// `SMSG_DUEL_COUNTDOWN` — start the "Duel starting: N" tick. Already converted from the
-    /// wire's milliseconds to whole seconds ([`super::duel::read_duel_countdown`]).
+    /// `SMSG_DUEL_COUNTDOWN`: the "Duel starting: N" tick, converted from the wire's milliseconds.
     DuelCountdown {
         seconds: u32,
     },
-    /// The `MSG_INSPECT_HONOR_STATS` **reply** — another player's honor stats (decision 1512).
-    /// The opcode is an `MSG_`, so the same number carries our request; direction disambiguates
-    /// (see [`super::opcode::MSG_INSPECT_HONOR_STATS`]). Unsolicited replies do not happen: this
-    /// only ever arrives because we asked, and a refused ask is answered with silence.
+    /// The `MSG_INSPECT_HONOR_STATS` reply, only ever to our ask; a refused ask gets silence.
     InspectHonorStats(InspectHonorStats),
-    /// `SMSG_PVP_CREDIT` — an honor payout, the only *attributed* notice of one. Also sent for
-    /// dishonorable kills, with negative honor.
+    /// `SMSG_PVP_CREDIT`: an attributed honor payout, negative for a dishonorable kill.
     PvpCredit(PvpCredit),
-    /// `SMSG_START_MIRROR_TIMER` — start or wholly re-state one mirror timer (the breath /
-    /// fatigue bars, decision 0874). The family has no update opcode: every change re-sends this.
+    /// `SMSG_START_MIRROR_TIMER`: start or restate a breath or fatigue bar; resent on each change.
     MirrorTimerStart(MirrorTimerStart),
-    /// `SMSG_PAUSE_MIRROR_TIMER` — freeze/unfreeze a running timer. vmangos never sends it.
+    /// `SMSG_PAUSE_MIRROR_TIMER`: freeze or unfreeze a running timer; vmangos never sends it.
     MirrorTimerPause {
         kind: u32,
         paused: bool,
     },
-    /// `SMSG_STOP_MIRROR_TIMER` — that timer is over; hide its bar.
+    /// `SMSG_STOP_MIRROR_TIMER`: that timer is over; hide its bar.
     MirrorTimerStop {
         kind: u32,
     },
-    /// `SMSG_FRIEND_LIST` — the whole friend list, guids + presence (decision 0668). Pushed
-    /// unasked at login and on every `CMSG_FRIEND_LIST`; always complete, never a delta.
+    /// `SMSG_FRIEND_LIST`: the whole friend list, pushed at login and on `CMSG_FRIEND_LIST`.
     FriendList {
         friends: Vec<FriendEntry>,
     },
-    /// `SMSG_IGNORE_LIST` — the whole ignore list: guids and nothing else.
+    /// `SMSG_IGNORE_LIST`: the whole ignore list, guids only.
     IgnoreList {
         guids: Vec<u64>,
     },
-    /// `SMSG_FRIEND_STATUS` — one result about one player: the ack for an add/remove, or the
-    /// login/logout broadcast every friend-lister receives.
+    /// `SMSG_FRIEND_STATUS`: an add or remove ack, or a friend's login or logout.
     FriendStatus(FriendStatusUpdate),
-    /// `SMSG_WHO` — the `/who` answer: up to 49 rows plus the true match total.
+    /// `SMSG_WHO`: the `/who` answer, up to 49 rows plus the true match total.
     WhoResults(WhoResults),
-    /// `SMSG_GUILD_QUERY_RESPONSE` — one guild's public identity: name, its ten rank names, tabard.
-    /// The guild twin of the name query: an ask-once cache fill keyed by guild id.
+    /// `SMSG_GUILD_QUERY_RESPONSE`: a guild's name, ten rank names and tabard, cached by guild id.
     GuildQueryResponse(GuildQueryResponse),
-    /// `SMSG_GUILD_ROSTER` — the whole guild: MOTD, info text, every rank's rights, every member.
-    /// Always a complete snapshot (the server re-sends it for any change), never a delta.
+    /// `SMSG_GUILD_ROSTER`: a complete snapshot, resent on any change: MOTD, info, ranks, members.
     GuildRoster(GuildRoster),
-    /// `SMSG_GUILD_EVENT` — one thing that happened in the guild, as an event id plus its
-    /// already-formatted string arguments.
+    /// `SMSG_GUILD_EVENT`: an event id and its formatted string arguments.
     GuildEvent(GuildEventNotice),
-    /// `SMSG_GUILD_COMMAND_RESULT` — the verdict on a guild verb we sent. The command tag beside
-    /// the code is load-bearing, not decorative (result `0x08` means two different things).
+    /// `SMSG_GUILD_COMMAND_RESULT`: read the code with its command tag; `0x08` means two things.
     GuildCommandResult(GuildCommandResult),
-    /// `SMSG_GUILD_INVITE` — somebody asked us into their guild. Answered by `CMSG_GUILD_ACCEPT` /
-    /// `CMSG_GUILD_DECLINE`, neither of which echoes anything back, so the pending invite is
-    /// client-side state.
+    /// `SMSG_GUILD_INVITE`: an invite into a guild. `CMSG_GUILD_ACCEPT` and `CMSG_GUILD_DECLINE`
+    /// echo nothing back, so the pending invite is client state.
     GuildInvite {
         inviter: String,
         guild: String,
     },
-    /// `SMSG_GUILD_DECLINE` — the player we invited turned it down. Sent only to the inviter.
+    /// `SMSG_GUILD_DECLINE`: the player we invited turned it down; sent only to the inviter.
     GuildDecline {
         name: String,
     },
-    /// `SMSG_GUILD_INFO` — the "founded on / N members / N accounts" summary; a separate ask from
-    /// the roster, with no overlapping fields.
+    /// `SMSG_GUILD_INFO`: the founded, members and accounts summary, apart from the roster.
     GuildInfo(GuildInfo),
-    /// `SMSG_PETITION_SHOWLIST` — a guild registrar's charter list. In 1.12 always one row, and
-    /// the packet that opens the registrar window.
+    /// `SMSG_PETITION_SHOWLIST`: a registrar's charter list, always one row; opens the window.
     PetitionShowList(PetitionShowList),
-    /// `SMSG_PETITION_SHOW_SIGNATURES` — who has signed a charter. Answers **two** different asks
-    /// (our own show-signatures, and someone else's offer aimed at us); only `owner` tells them
-    /// apart.
+    /// `SMSG_PETITION_SHOW_SIGNATURES`: a charter's signers, answering our ask or someone's offer
+    /// to us; only `owner` tells them apart.
     PetitionShowSignatures(PetitionShowSignatures),
-    /// `SMSG_PETITION_SIGN_RESULTS` — the verdict on one signature. Sent to *both* parties on
-    /// success, and both copies name the signer.
+    /// `SMSG_PETITION_SIGN_RESULTS`: one signature's verdict; on success both sides get it.
     PetitionSignResults(PetitionSignResults),
-    /// `SMSG_PETITION_QUERY_RESPONSE` — a petition's record: the proposed guild name and the
-    /// signature requirement, neither of which is on any other packet.
+    /// `SMSG_PETITION_QUERY_RESPONSE`: the proposed guild name and signature requirement.
     PetitionQueryResponse(PetitionQueryResponse),
-    /// `SMSG_TURN_IN_PETITION_RESULTS` — a bare result code. A name collision produces no packet
-    /// at all, so silence is a real outcome.
+    /// `SMSG_TURN_IN_PETITION_RESULTS`: a bare result code; a name collision gets no packet.
     TurnInPetitionResults {
         result: u32,
     },
-    /// `MSG_PETITION_DECLINE` inbound — the guid of the player who declined our charter. Sent only
-    /// to the charter's owner.
+    /// `MSG_PETITION_DECLINE` inbound: who declined our charter, sent only to its owner.
     PetitionDeclined {
         player: u64,
     },
-    /// `MSG_PETITION_RENAME` inbound — the server's echo of a rename that took. Only on success.
+    /// `MSG_PETITION_RENAME` inbound: the echo of a rename that took, success only.
     PetitionRenamed(PetitionRename),
-    /// A `SMSG_SPLINE_SET_*_SPEED` — a speed change on a unit we don't control (a creature, or a
-    /// player mid-spline): `[packed guid][f32 speed]`, no counter, no ack (decision 0441 — how an
-    /// observed unit's mounted speed reaches us).
+    /// `SMSG_SPLINE_SET_*_SPEED`: a unit we don't control, `[packed guid][f32 speed]`, no ack.
     SplineSpeedChange {
         guid: u64,
         kind: SpeedKind,
         speed: f32,
     },
-    /// A `MSG_MOVE_SET_*_SPEED` — a freely-moving *player's* speed change (the common observer
-    /// case: someone mounts up nearby): `[packed guid][MovementInfo][f32 speed]` — a speed change
-    /// AND a fresh authoritative pose in one packet (decision 0441).
+    /// `MSG_MOVE_SET_*_SPEED`: `[packed guid][MovementInfo][f32 speed]`, a speed and a fresh pose.
     MoveSetSpeed {
         guid: u64,
         kind: SpeedKind,
         flags: u32,
         position: Vector3d,
         orientation: f32,
-        /// The swim pitch from the `MovementInfo` tail (see [`Self::PlayerMove::pitch`]).
+        /// Swim pitch (radians, +up), `0.0` unless swimming.
         pitch: f32,
-        /// The `MovementInfo` time word (see [`Self::PlayerMove::time`]).
+        /// The `MovementInfo` time word, stamped by vmangos's clock at receipt.
         time: u32,
         fall_time: u32,
         jump: Option<JumpInfo>,
-        /// The rider's platform frame when ON_TRANSPORT is set (a speed change aboard a boat
-        /// carries the same MovementInfo as any relay — decision 0438's frame law applies).
+        /// The rider's pose on its transport while `MOVEFLAG_ON_TRANSPORT` is set.
         transport: Option<TransportPose>,
         speed: f32,
     },
-    /// `SMSG_MOUNTRESULT` / `SMSG_DISMOUNTRESULT` — the server's answer to a (dis)mount attempt
-    /// (`mount` distinguishes them): one raw result code (vmangos `UnitMountResult` /
-    /// `UnitDismountResult`; OK = 10 / 3). Decision 0441; error lines are a P2 trimming.
+    /// `SMSG_MOUNTRESULT` / `SMSG_DISMOUNTRESULT` (by `mount`): a raw `UnitMountResult` (OK = 10)
+    /// or `UnitDismountResult` (OK = 3).
     MountResult {
         mount: bool,
         code: u32,
     },
-    /// `SMSG_MOUNTSPECIAL_ANIM` — a nearby mounted player hit the flourish (one raw u64 guid;
-    /// VERIFIED vmangos `HandleMountSpecialAnimOpcode`, `MovementHandler.cpp:969-970`). The
-    /// sender is excluded from the broadcast, so this only ever names someone else's mount.
+    /// `SMSG_MOUNTSPECIAL_ANIM`: one raw `u64` guid, always another player's mount, since the
+    /// sender is left out of the broadcast (`MovementHandler.cpp:969-970`).
     MountSpecialAnim {
         guid: u64,
     },
-    /// `SMSG_CLIENT_CONTROL_UPDATE` — packed mover guid + `u8` allowMove (VERIFIED vmangos
-    /// `Server/Packets/Misc.cpp:677-682`). Always addressed to us; `mover` is the unit it speaks
-    /// about, which is our own guid when the server is taking control *away*.
+    /// `SMSG_CLIENT_CONTROL_UPDATE`: packed guid, `u8` allowMove (`Misc.cpp:677-682`); `mover`
+    /// is our own guid when the server takes control away.
     ClientControlUpdate {
         mover: u64,
         allow_move: bool,
     },
-    /// `SMSG_SHOWTAXINODES` — the taxi map (vmangos `SendTaxiMenu`, `TaxiHandler.cpp:82-96`;
-    /// layout in [`super::taxi::read_show_taxi_nodes`], decision 0484). `window` is the
-    /// window-framing constant vmangos always writes `1`; `flightmaster` names the NPC the menu
-    /// opened on (its taxi mount resolves through the `benilla-formats` `TaxiNodes` catalog);
-    /// `nearest_node` is the node the flight master itself sits at; `known` is the full
-    /// known-node bitmask.
+    /// `SMSG_SHOWTAXINODES` (`TaxiHandler.cpp:82-96`): the taxi map; vmangos always writes
+    /// `window` 1, and `nearest_node` is the flight master's own node.
     ShowTaxiNodes {
         window: u32,
         flightmaster: u64,
         nearest_node: u32,
         known: TaxiMask,
     },
-    /// `SMSG_TAXINODE_STATUS` — answers `CMSG_TAXINODE_STATUS_QUERY`, and also rides a
-    /// first-visit "learn" (vmangos `SendLearnNewTaxiNode`, `TaxiHandler.cpp:117-138`): `guid`
-    /// names the flight master asked about (plain, not packed); `known` is whether the nearest
-    /// node to it is in our taxi mask.
+    /// `SMSG_TAXINODE_STATUS`: answers the status query, and rides a first-visit learn
+    /// (`TaxiHandler.cpp:117-138`). `guid` is plain; `known` means its node is in our mask.
     TaxiNodeStatus {
         guid: u64,
         known: bool,
     },
-    /// `SMSG_ACTIVATETAXIREPLY` — answers `CMSG_ACTIVATETAXI`/`CMSG_ACTIVATETAXIEXPRESS`: `code`
-    /// is a [`super::taxi_reply`] value (`0` OK, everything else a refusal — no flight starts).
+    /// `SMSG_ACTIVATETAXIREPLY`: a [`super::taxi_reply`]; `0` is OK, anything else refuses.
     ActivateTaxiReply {
         code: u32,
     },
-    /// `SMSG_NEW_TAXI_PATH` — empty body. Rides a first-visit "learn" alongside
-    /// [`Self::TaxiNodeStatus`] (vmangos `SendLearnNewTaxiNode`); the client has nothing to read
-    /// from it, but the wire is modelled rather than silently dropped.
+    /// `SMSG_NEW_TAXI_PATH` (empty): rides a first-visit learn beside [`Self::TaxiNodeStatus`].
     NewTaxiPath,
-    /// `SMSG_MAIL_LIST_RESULT` — the inbox page, answering `CMSG_GET_MAIL_LIST` (layout in
-    /// [`super::mail::read_mail_list_result`], decision 0544 P0).
+    /// `SMSG_MAIL_LIST_RESULT`: the inbox, answering `CMSG_GET_MAIL_LIST`.
     MailList {
         mails: Vec<MailListEntry>,
     },
-    /// `SMSG_SEND_MAIL_RESULT` — the verdict on a mail action (send/take-money/take-item/return/
-    /// delete), keyed by `action` ([`super::mail::mail_action`]) and `error`
-    /// ([`super::mail::mail_error`]); `equip_error`/`item` are the two mutually-exclusive
-    /// conditional tails (layout in [`super::mail::read_send_mail_result`]).
+    /// `SMSG_SEND_MAIL_RESULT`: a [`super::mail::mail_action`] and [`super::mail::mail_error`];
+    /// `equip_error` and `item` are mutually exclusive tails.
     SendMailResult {
         mail_id: u32,
         action: u32,
@@ -1520,106 +1169,81 @@ pub enum ServerPacket {
         equip_error: Option<u32>,
         item: Option<(u32, u32)>,
     },
-    /// `SMSG_ITEM_TEXT_QUERY_RESPONSE` — a letter's body text, answering `CMSG_ITEM_TEXT_QUERY`
-    /// (the ask-once fetch a mail's nonzero `item_text_id` triggers).
+    /// `SMSG_ITEM_TEXT_QUERY_RESPONSE`: a letter's body, fetched once for a nonzero `item_text_id`.
     ItemTextQueryResponse {
         text_id: u32,
         text: String,
     },
-    /// `SMSG_RECEIVED_MAIL` — a mail arrived (instant for text-only, on the delivery timer's
-    /// expiry otherwise). `seconds` is the delay until it is "waiting", in the countdown's units:
-    /// vmangos only ever sends `0.0` ("now"), but the real client reads a float here and runs it
-    /// through the countdown's set-value ladder (decision 0913).
+    /// `SMSG_RECEIVED_MAIL`: a mail arrived; `seconds` until it waits, always `0.0` from vmangos,
+    /// though the client runs it through its countdown.
     ReceivedMail {
         seconds: f32,
     },
-    /// `MSG_QUERY_NEXT_MAIL_TIME`'s reply (same opcode as our empty-body request): `0.0` = unread
-    /// mail waiting, `-86400.0` = none.
+    /// `MSG_QUERY_NEXT_MAIL_TIME` reply: `0.0` means unread mail waits, `-86400.0` none.
     NextMailTime {
         seconds: f32,
     },
-    /// `MSG_AUCTION_HELLO`'s **reply** (same opcode as our one-guid request, decision 1511 P0):
-    /// the auctioneer we greeted plus the `AuctionHouse.dbc` row (1..7) that names its deposit and
-    /// cut rates. It is this packet, not our send, that opens the window.
+    /// `MSG_AUCTION_HELLO` reply: the auctioneer and its `AuctionHouse.dbc` row (1..7, the deposit
+    /// and cut rates); this reply, not our send, opens the window.
     AuctionHello {
         auctioneer: u64,
         house_id: u32,
     },
-    /// `SMSG_AUCTION_COMMAND_RESULT` — the verdict on a sell/cancel/bid, keyed by `action`
-    /// ([`super::auction::auction_action`]) and `error` ([`super::auction::auction_error`]);
-    /// `tail` is the conditional payload the error selects (layout in
-    /// [`super::auction::read_auction_command_result`]). `auction_id` is `0` on most failures.
+    /// `SMSG_AUCTION_COMMAND_RESULT`: `action` an [`super::auction::auction_action`], `error` an
+    /// [`super::auction::auction_error`] that selects `tail`; `auction_id` is 0 on most failures.
     AuctionCommandResult {
         auction_id: u32,
         action: u32,
         error: u32,
         tail: AuctionCommandTail,
     },
-    /// `SMSG_AUCTION_LIST_RESULT` — a Browse page, answering `CMSG_AUCTION_LIST_ITEMS`.
-    /// `total_count` is the match count *before* the 50-row cap (the pager's "of N"), and rides
-    /// at the END of the body (layout in [`super::auction::read_auction_list_result`]).
+    /// `SMSG_AUCTION_LIST_RESULT`: a Browse page; `total_count` is the match count before the
+    /// 50-row cap and rides at the end of the body.
     AuctionListResult {
         auctions: Vec<AuctionListEntry>,
         total_count: u32,
     },
-    /// `SMSG_AUCTION_OWNER_LIST_RESULT` — the Auctions tab page (your own listings), answering
-    /// `CMSG_AUCTION_LIST_OWNER_ITEMS`. Same frame and record as [`Self::AuctionListResult`].
+    /// `SMSG_AUCTION_OWNER_LIST_RESULT`: the Auctions tab (our listings), shaped as a Browse page.
     AuctionOwnerListResult {
         auctions: Vec<AuctionListEntry>,
         total_count: u32,
     },
-    /// `SMSG_AUCTION_BIDDER_LIST_RESULT` — the Bid tab page, answering
-    /// `CMSG_AUCTION_LIST_BIDDER_ITEMS`. Same frame and record as [`Self::AuctionListResult`];
-    /// the server emits the explicitly-refreshed ids first and then our own live bids, so a row
-    /// can legitimately appear twice in one page.
+    /// `SMSG_AUCTION_BIDDER_LIST_RESULT`: the Bid tab; the server lists the refreshed ids, then
+    /// our live bids, so a row can appear twice.
     AuctionBidderListResult {
         auctions: Vec<AuctionListEntry>,
         total_count: u32,
     },
-    /// `SMSG_AUCTION_BIDDER_NOTIFICATION` — we won, or we were outbid (`bid_or_zero == 0` means
-    /// **won**). A different shape from [`Self::AuctionOwnerNotification`], deliberately.
+    /// `SMSG_AUCTION_BIDDER_NOTIFICATION`: we won (`bid_or_zero == 0`) or were outbid.
     AuctionBidderNotification(AuctionBidderNotification),
-    /// `SMSG_AUCTION_OWNER_NOTIFICATION` — our own auction sold or took a bid. No house id, and
-    /// the bidder guid sits fourth rather than third; an all-zero guid is the "sold" signal.
+    /// `SMSG_AUCTION_OWNER_NOTIFICATION`: our auction sold (all-zero bidder guid) or took a bid.
     AuctionOwnerNotification(AuctionOwnerNotification),
-    /// `SMSG_AUCTION_REMOVED_NOTIFICATION` — an auction we had bid on was cancelled by its seller.
+    /// `SMSG_AUCTION_REMOVED_NOTIFICATION`: an auction we had bid on was cancelled by its seller.
     AuctionRemovedNotification {
         auction_id: u32,
         item_entry: u32,
         random_property_id: i32,
     },
-    /// `SMSG_TRADE_STATUS` — one pulse of the trade state machine (open/accept/cancel/complete/
-    /// the refusal reasons); the tail-carrying statuses hold their payload in [`TradeStatus`]
-    /// (layout in [`super::trade::read_trade_status`], decision 0592 P0).
+    /// `SMSG_TRADE_STATUS`: one step of the trade state machine, tails included.
     TradeStatus {
         status: TradeStatus,
     },
-    /// `SMSG_TRADE_STATUS_EXTENDED` — the item/gold snapshot for one window side, pushed whenever
-    /// that side's offer changes (layout in [`super::trade::read_trade_status_extended`]). Boxed:
-    /// the seven-slot item array is ~460 bytes, and it would otherwise bloat every `ServerPacket`
-    /// (the same reason `QuestQueryResponse`/`PartyMemberStats` box their payloads).
+    /// `SMSG_TRADE_STATUS_EXTENDED`: one side's items and gold, pushed whenever that side changes.
     TradeStatusExtended {
         state: Box<TradeStatusExtended>,
     },
-    /// `SMSG_INIT_WORLD_STATES` — the whole world-state table for a zone, pushed on login and on
-    /// every zone change (layout in [`super::world_state::read_init_world_states`]).
+    /// `SMSG_INIT_WORLD_STATES`: a zone's whole world-state table, at login and each zone change.
     InitWorldStates(InitWorldStates),
-    /// `SMSG_UPDATE_WORLD_STATE` — one `(id, value)` write into that table.
+    /// `SMSG_UPDATE_WORLD_STATE`: one `(id, value)` write into that table.
     UpdateWorldState {
         id: u32,
         value: u32,
     },
-    /// `SMSG_ADDON_INFO` (`0x2ef`) — the server's per-addon verdict on the block we sent in
-    /// `CMSG_AUTH_SESSION` (decision 2175).
-    ///
-    /// **It carries no count and no names.** The client re-walks its own `## Secure:` list in the
-    /// same order it sent it and reads one record per addon, so record *i* is
-    /// `STOCK_SECURE_ADDONS[i]` (wow-re `system/net/scratch/cmsg-auth-session-addon-block.md` §6).
-    /// Only the `status` byte matters to us: **2** is what makes the client set `[rec+0x29] = 1`
-    /// and drop the addon from the Lua index space, which is why a stock install's AddOns list
-    /// shows the player's addons and none of Blizzard's.
+    /// `SMSG_ADDON_INFO` (`0x2ef`): one record per addon we sent in `CMSG_AUTH_SESSION`, in that
+    /// order with no count or names, so record i is `STOCK_SECURE_ADDONS[i]`. Status 2 drops the
+    /// addon from the client's Lua index, which hides Blizzard's addons from the AddOns list.
     AddonInfo {
-        /// One `status` per record, in the order the records arrived.
+        /// One status per record, in arrival order.
         statuses: Vec<u8>,
     },
     Other {
@@ -1628,7 +1252,7 @@ pub enum ServerPacket {
 }
 
 impl ServerPacket {
-    /// A short human name for logging/tallying (the opcode in hex for unmodelled packets).
+    /// A short name for logs and tallies; the opcode in hex for an unmodelled packet.
     pub fn name(&self) -> String {
         match self {
             ServerPacket::AuthChallenge { .. } => "SMSG_AUTH_CHALLENGE".into(),
@@ -1709,6 +1333,9 @@ impl ServerPacket {
             ServerPacket::PageTextQueryResponse { .. } => "SMSG_PAGE_TEXT_QUERY_RESPONSE".into(),
             ServerPacket::GameObjectCustomAnim { .. } => "SMSG_GAMEOBJECT_CUSTOM_ANIM".into(),
             ServerPacket::GameObjectDespawnAnim { .. } => "SMSG_GAMEOBJECT_DESPAWN_ANIM".into(),
+            ServerPacket::OpenContainer { .. } => "SMSG_OPEN_CONTAINER".into(),
+            ServerPacket::Inspect { .. } => "SMSG_INSPECT".into(),
+            ServerPacket::StandStateUpdate { .. } => "SMSG_STANDSTATE_UPDATE".into(),
             ServerPacket::FishNotHooked => "SMSG_FISH_NOT_HOOKED".into(),
             ServerPacket::FishEscaped => "SMSG_FISH_ESCAPED".into(),
             ServerPacket::PlaySound { .. } => "SMSG_PLAY_SOUND".into(),
@@ -1750,8 +1377,7 @@ impl ServerPacket {
             ServerPacket::AttackStart { .. } => "SMSG_ATTACKSTART".into(),
             ServerPacket::AttackStop { .. } => "SMSG_ATTACKSTOP".into(),
             ServerPacket::AttackerState(_) => "SMSG_ATTACKERSTATEUPDATE".into(),
-            // The wire opcode is not recoverable from the collapsed arm 4 — the client cannot tell
-            // DEADTARGET from CANT_ATTACK either, so the name says which arm ran.
+            // DEADTARGET and CANT_ATTACK share one arm, as in the client; the name says which arm.
             ServerPacket::AttackSwingError(e) => match e {
                 AttackSwingError::NotInRange => "SMSG_ATTACKSWING_NOTINRANGE".into(),
                 AttackSwingError::BadFacing => "SMSG_ATTACKSWING_BADFACING".into(),
@@ -1772,8 +1398,6 @@ impl ServerPacket {
             ServerPacket::ItemCooldown { .. } => "SMSG_ITEM_COOLDOWN".into(),
             ServerPacket::ItemTime { .. } => "SMSG_ITEM_TIME_UPDATE".into(),
             ServerPacket::ItemEnchantTime { .. } => "SMSG_ITEM_ENCHANT_TIME_UPDATE".into(),
-            // The opcode IS the table, so the name recovers it — unlike the collapsed
-            // `AttackSwingError` arm above, nothing here is lost.
             ServerPacket::SpellModifier { flat, .. } => if *flat {
                 "SMSG_SET_FLAT_SPELL_MODIFIER"
             } else {
@@ -1876,7 +1500,7 @@ impl ServerPacket {
                 (SplineMode::Hover, false) => "SMSG_SPLINE_MOVE_UNSET_HOVER".into(),
                 (SplineMode::Swimming, true) => "SMSG_SPLINE_MOVE_START_SWIM".into(),
                 (SplineMode::Swimming, false) => "SMSG_SPLINE_MOVE_STOP_SWIM".into(),
-                // Inverted on purpose — see [`SplineMode::WalkMode`].
+                // Inverted on purpose: see `SplineMode::WalkMode`.
                 (SplineMode::WalkMode, true) => "SMSG_SPLINE_MOVE_SET_WALK_MODE".into(),
                 (SplineMode::WalkMode, false) => "SMSG_SPLINE_MOVE_SET_RUN_MODE".into(),
             },
diff --git a/crates/benilla-protocol/src/messages/page_text.rs b/crates/benilla-protocol/src/messages/page_text.rs
index c5f8a8fb..ba669811 100644
--- a/crates/benilla-protocol/src/messages/page_text.rs
+++ b/crates/benilla-protocol/src/messages/page_text.rs
@@ -1,29 +1,15 @@
-//! The **page-text** query pair (decision 1105) — the ask-once cache behind every readable *book*.
-//!
-//! Distinct from the mail letter's `CMSG_ITEM_TEXT_QUERY` ([`super::mail`]), which fetches one
-//! whole player-written body by an *instance* text id. A `PageText.wdb` id names a single **page**,
-//! and pages **chain**: each answer carries the next page's id (`0` = last). Two things read from
-//! this cache, and both reach it the same way — the client opens its reader on an object guid and
-//! asks the object for its page id:
-//!
-//! - a readable **item template** (`ItemPrototype::PageText`) — a book in your bags;
-//! - a **`GAMEOBJECT_TYPE_TEXT`** world object (its template `data[0]`) — a book, plaque or sign
-//!   lying in the world.
-//!
-//! The client's request carries the asking object's guid after the page id (VERIFIED: the cache's
-//! request writer `0x564730` appends the 8-byte guid at `0x56485d` under the per-cache "requests
-//! carry a guid" flag `[cache+0x38]` — the very address vmangos cites in
-//! `QueryPageText::ReadFromWorldPacket` when it reads the tail as optional). vmangos resolves the
-//! page from the id alone and skips the guid.
+//! The page-text query pair, the ask-once cache behind every readable book: a `PageText.wdb` id
+//! names one page, and each answer carries the next page's id (`0` = last). The first id comes
+//! from an item template's `PageText` or a `GAMEOBJECT_TYPE_TEXT` object's `data[0]`; mail bodies
+//! use `CMSG_ITEM_TEXT_QUERY` instead.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_u32_le};
 
-/// Body of `CMSG_PAGE_TEXT_QUERY` (opcode `0x005A`/90 — VERIFIED vmangos
-/// `Server/Protocol/Opcodes_1_12_1.h`): `u32 pageId` then the asking object's `u64 guid` (VERIFIED
-/// `QueryPageText::ReadFromWorldPacket`, which reads the guid only `if (rpos() < size())` and
-/// discards it; the real client writes it — see the module doc).
+/// Body of `CMSG_PAGE_TEXT_QUERY` (`0x005A`): `u32 pageId`, then the asking object's `u64 guid`,
+/// which the 1.12 client appends (`0x564730`, at `0x56485d`) and vmangos reads only if present,
+/// then discards (`QueryPageText::ReadFromWorldPacket`).
 pub fn page_text_query(page_id: u32, guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&page_id.to_le_bytes());
@@ -31,13 +17,10 @@ pub fn page_text_query(page_id: u32, guid: u64) -> Vec<u8> {
     body
 }
 
-/// Read `SMSG_PAGE_TEXT_QUERY_RESPONSE` (VERIFIED vmangos `Server/Packets/Query.cpp`,
-/// `PageTextQueryResponse::AppendBodyTo`): `u32 pageId, cstr text, u32 nextPageId`.
-///
-/// vmangos answers **one query with the whole chain** — `HandlePageTextQueryOpcode` loops on
-/// `next_page`, sending one of these per page — so asking for page 1 lands every page of the book
-/// unsolicited. A page the server doesn't know answers `"Item page missing."` with `nextPageId = 0`,
-/// which terminates the chain rather than erroring.
+/// Read `SMSG_PAGE_TEXT_QUERY_RESPONSE`: `u32 pageId, cstr text, u32 nextPageId`
+/// (`PageTextQueryResponse::AppendBodyTo`). vmangos answers one query with the whole chain, one
+/// packet per page (`HandlePageTextQueryOpcode`), and an unknown page with `"Item page missing."`
+/// and `nextPageId = 0`.
 pub(super) fn read_page_text_query_response(r: &mut &[u8]) -> io::Result<(u32, String, u32)> {
     Ok((read_u32_le(r)?, read_cstring(r)?, read_u32_le(r)?))
 }
@@ -77,8 +60,9 @@ mod tests {
         }
     }
 
+    /// A last page's zero `nextPageId` reads as 0, the value that ends the chain.
     #[test]
-    fn last_page_terminates_the_chain() {
+    fn the_last_page_reads_a_zero_next_page_id() {
         let mut body = 9u32.to_le_bytes().to_vec();
         body.extend_from_slice(b"The end.\0");
         body.extend_from_slice(&0u32.to_le_bytes());
diff --git a/crates/benilla-protocol/src/messages/parse.rs b/crates/benilla-protocol/src/messages/parse.rs
index 877b27d1..8e589874 100644
--- a/crates/benilla-protocol/src/messages/parse.rs
+++ b/crates/benilla-protocol/src/messages/parse.rs
@@ -1,7 +1,4 @@
-//! The opcode→[`ServerPacket`] dispatch: [`parse_server`] decodes one server packet body (already
-//! decrypted + sized) into its variant, delegating per-domain payloads to the domain children
-//! (`spells`, `quest`, `loot`, …). One match arm per opcode — which opcode carries what stays
-//! readable in one place.
+//! The opcode to [`ServerPacket`] dispatch, one match arm per opcode.
 
 use std::io::{self, Read};
 
@@ -14,14 +11,13 @@ use super::{
     action_bar, area_trigger, attack, auction, bank, battlefield, binder, broadcast, channel, chat,
     combat_log, death, duel, gameobject, gm_ticket, gossip, group, guild, instance, items, loot,
     mail, meeting_stone, mirror_timer, monster_move, movement, opcode, page_text, pet, petition,
-    progression, pvp, quest, social, spellbook, spells, stable, summon, tabard, taxi, trade,
+    pose, progression, pvp, quest, social, spellbook, spells, stable, summon, tabard, taxi, trade,
     trainer, tutorial, update_object, vendor, world_state, AttackSwingError, Character,
     CreatureQueryInfo, JumpInfo, MoveMode, ServerPacket, SpeedKind, SplineMode,
 };
 
-/// Read one `SMSG_FORCE_*_SPEED_CHANGE` body — `[packed mover guid][u32 counter][f32 speed]`,
-/// identical across all six kinds (VERIFIED vmangos `SendSpeedChangeToController`, the 5875
-/// `> 1_9_4` branch). The kind is the opcode's; the caller's arm names it.
+/// Read a `SMSG_FORCE_*_SPEED_CHANGE` body: `[packed guid][u32 counter][f32 speed]` for all six
+/// kinds (vmangos `SendSpeedChangeToController`, the `> 1_9_4` branch).
 fn read_force_speed(kind: SpeedKind, r: &mut impl Read) -> io::Result<ServerPacket> {
     Ok(ServerPacket::ForceSpeedChange {
         guid: read_packed_guid(r)?,
@@ -31,28 +27,21 @@ fn read_force_speed(kind: SpeedKind, r: &mut impl Read) -> io::Result<ServerPack
     })
 }
 
-/// Read an `SMSG_COMPRESSED_MOVES` body: `[u32 uncompressed size][deflate stream]`, the stream a
-/// run of `[u8 size][u16 opcode][body]` records where `size` counts the opcode's own two bytes
-/// (VERIFIED vmangos `MovementData::AddPacket`/`BuildPacket`). Each record is a whole movement
-/// packet, so it goes straight back through [`parse_server`] — the batch is a *transport*, not a
-/// message shape, and nothing downstream needs to know a move arrived batched.
-///
-/// A record that fails to parse fails the **whole** batch (surfacing as one `Poll::Skipped` naming
-/// the inner opcode) rather than being dropped quietly. Losing a batch is worse than losing a
-/// packet, but silence here is what cost days: an unhandled inner opcode has to be loud. Only the
-/// `MSG_MOVE_*` relays vmangos routes through `ObjectViewersMovementDeliverer` can appear, and we
-/// model all of them (`the_batch_carries_every_relayed_move_opcode`).
-fn read_compressed_moves(r: &mut impl Read) -> io::Result<Vec<ServerPacket>> {
+/// Read an `SMSG_COMPRESSED_MOVES` body: `u32` uncompressed size, then deflated
+/// `[u8 size][u16 opcode][body]` records, `size` counting the opcode (`MovementData::AddPacket`).
+/// Each record goes back through [`parse_server`], and one bad record fails the whole batch; only
+/// the `MSG_MOVE_*` relays can appear (vmangos `ObjectViewersMovementDeliverer`).
+fn read_compressed_moves(r: &mut &[u8]) -> io::Result<Vec<ServerPacket>> {
     let uncompressed = read_u32_le(r)? as usize;
     let mut buf = Vec::with_capacity(uncompressed.min(64 * 1024));
-    flate2::read::ZlibDecoder::new(r).read_to_end(&mut buf)?;
+    // `bufread`, not `read`: the cursor must stop at the stream's end for the tail to be seen.
+    flate2::bufread::ZlibDecoder::new(r).read_to_end(&mut buf)?;
     let mut rest = buf.as_slice();
     let mut packets = Vec::new();
     while !rest.is_empty() {
         let size = read_u8(&mut rest)? as usize;
         let opcode = read_u16_le(&mut rest)?;
-        // `size` spans opcode + body; anything under two bytes cannot even hold the opcode we
-        // just read, so the stream is misframed and every later record would be garbage.
+        // `size` spans opcode and body, so under 2 means the stream is misframed.
         let body_len = size.checked_sub(2).ok_or_else(|| {
             io::Error::new(
                 io::ErrorKind::InvalidData,
@@ -90,9 +79,8 @@ fn read_compressed_moves(r: &mut impl Read) -> io::Result<Vec<ServerPacket>> {
     Ok(packets)
 }
 
-/// Read one `SMSG_SPLINE_SET_*_SPEED` body — `[packed guid][f32 speed]` (VERIFIED vmangos
-/// `MovementPacketSender::SendSpeedChangeToAll` + the mid-spline observer branch, the 5875
-/// `> 1_8_4` layout). Observer-only: no counter, no ack (decision 0441).
+/// Read a `SMSG_SPLINE_SET_*_SPEED` body: `[packed guid][f32 speed]`, no counter, no ack
+/// (vmangos `SendSpeedChangeToAll`, the `> 1_8_4` layout).
 fn read_spline_speed(kind: SpeedKind, r: &mut impl Read) -> io::Result<ServerPacket> {
     Ok(ServerPacket::SplineSpeedChange {
         guid: read_packed_guid(r)?,
@@ -101,9 +89,8 @@ fn read_spline_speed(kind: SpeedKind, r: &mut impl Read) -> io::Result<ServerPac
     })
 }
 
-/// Read one `MSG_MOVE_SET_*_SPEED` body — `[packed guid][MovementInfo][f32 speed]` (VERIFIED
-/// vmangos `SendSpeedChangeToObservers`, the finalized-spline branch): a freely-moving player's
-/// speed change, carrying a fresh pose alongside (decision 0441). No ack.
+/// Read a `MSG_MOVE_SET_*_SPEED` body: `[packed guid][MovementInfo][f32 speed]`, no ack
+/// (vmangos `SendSpeedChangeToObservers`).
 fn read_move_set_speed(kind: SpeedKind, r: &mut impl Read) -> io::Result<ServerPacket> {
     let guid = read_packed_guid(r)?;
     let info = movement::read_movement_info(r)?;
@@ -122,21 +109,10 @@ fn read_move_set_speed(kind: SpeedKind, r: &mut impl Read) -> io::Result<ServerP
     })
 }
 
-/// True for a relayed movement opcode — one the server rebroadcasts as `[packed guid][MovementInfo]`.
-/// Two groups, one wire shape and one client handler (`0x603bb0`, wow-re `re/net/opcode-handlers.tsv`
-/// — 30 rows pointing at it, of which these are 23):
-///
-/// - the **echoed input stream**, every opcode bound to vmangos `HandleMovementOpcodes` (VERIFIED
-///   `Opcodes.cpp`): another player's walking, turning, jumping, swimming, facing;
-/// - the **observer leg of the movement-mode family** (decision 2061): root/unroot, hover,
-///   feather-fall, water-walk and the near-teleport, broadcast by
-///   `MovementPacketSender::Send{MovementFlagChange,Teleport}ToObservers` once the mover's own
-///   client has acked. Same body, no ack, and the apply/unapply direction rides the `MovementInfo`
-///   flags word rather than the opcode (see [`super::opcode`]'s block).
-///
-/// Excludes `MSG_MOVE_TELEPORT_ACK` / `MSG_MOVE_WORLDPORT_ACK`, which share the family but carry
-/// different bodies and are decoded by their own arms — note `MSG_MOVE_TELEPORT` (197) is the
-/// observer's teleport and is NOT `MSG_MOVE_TELEPORT_ACK` (199): no counter dword, so it parses here.
+/// True for an opcode the server relays as `[packed guid][MovementInfo]`, one client handler
+/// (`0x603bb0`): the echoed input stream (vmangos `HandleMovementOpcodes`), and the observer leg
+/// of root, hover, feather-fall, water-walk and teleport, with no ack and its direction in the
+/// flags word. `MSG_MOVE_TELEPORT` (197) has no counter, unlike `MSG_MOVE_TELEPORT_ACK` (199).
 const fn is_movement_relay(o: u16) -> bool {
     matches!(
         o,
@@ -161,15 +137,10 @@ const fn is_movement_relay(o: u16) -> bool {
             | opcode::MSG_MOVE_SET_FACING
             | opcode::MSG_MOVE_SET_PITCH
             | opcode::MSG_MOVE_HEARTBEAT
-            // Somebody else was knocked back (decision 1702). It carries four extra floats after the
-            // `MovementInfo` — the launch quad — which this reader simply doesn't reach, and doesn't
-            // need to: the server built that `MovementInfo` from the victim's own ack, so its jump
-            // tail already IS the quad, and the arc replays from it like any other relayed jump.
+            // Another unit's knockback: the four trailing launch floats go unread, since the
+            // `MovementInfo` comes from the victim's ack and its jump tail already is that quad.
             | opcode::MSG_MOVE_KNOCK_BACK
-            // The observer leg of the movement-mode family (decision 2061): somebody else was
-            // rooted, levitated (hover + feather fall + water walk), or blinked. The mode lands in
-            // the `MovementInfo` flags word this body already carries, so no arm of its own is
-            // needed — only the opcode's admission to the family.
+            // Another unit's mode change: the mode rides the `MovementInfo` flags word.
             | opcode::MSG_MOVE_ROOT
             | opcode::MSG_MOVE_UNROOT
             | opcode::MSG_MOVE_HOVER
@@ -179,11 +150,7 @@ const fn is_movement_relay(o: u16) -> bool {
     )
 }
 
-/// Parse a server packet body (already decrypted + sized) by opcode.
-/// `SMSG_ADDON_INFO`'s record stream — **no count, no names, no trailer** (decision 2175).
-///
-/// The grammar is the one `AddOn_ReadAddonInfoReply 0x51da70` reads, per record (wow-re
-/// `system/net/scratch/cmsg-auth-session-addon-block.md` §6):
+/// `SMSG_ADDON_INFO`'s records, with no count, names or trailer, as `0x51da70` reads each:
 ///
 /// ```text
 /// u8  status              ; 2 -> [rec+0x29] = 1 (hidden from the Lua index space)
@@ -198,13 +165,8 @@ const fn is_movement_relay(o: u16) -> bool {
 /// if urlProvided: u8[256] url
 /// ```
 ///
-/// The retail capture is the minimal form — 12 x 8 bytes of `{2, 1, 0, 0u32, 0}`.
-///
-/// **A truncated record ends the walk and keeps the records before it**, rather than failing the
-/// packet. Only a record that parsed whole contributes a status, so `statuses[i]` is always
-/// record *i*'s and the pairing against what we sent cannot slip. The stream is self-delimiting only if every field is read exactly right, so a grammar
-/// error here would otherwise turn a working login into an unparseable packet; the statuses we did
-/// read are still true, and a short read is visible as a count that does not match what we sent.
+/// Retail sends the minimal form, 12 records of `{2, 1, 0, 0u32, 0}`. A truncated record ends the
+/// walk and keeps the whole records before it, so `statuses[i]` is always record i's.
 fn read_addon_info(r: &mut &[u8]) -> Vec<u8> {
     let mut statuses = Vec::new();
     while !r.is_empty() {
@@ -228,31 +190,21 @@ fn read_addon_info(r: &mut &[u8]) -> Vec<u8> {
     statuses
 }
 
-/// Advance `r` by `n` bytes, or `None` when it holds fewer.
 fn skip(r: &mut &[u8], n: usize) -> Option<()> {
     (r.len() >= n).then(|| *r = &r[n..])
 }
 
-/// Decode one server packet body into its [`ServerPacket`]. The body is the whole length-framed
-/// packet, so a decoder that reads fewer bytes than the server wrote succeeds all the same; that
-/// gap is what [`parse_server_with_tail`] reports, and this is its `(packet, _)` projection.
+/// Decode one server packet body into its [`ServerPacket`], ignoring any unread tail that
+/// [`parse_server_with_tail`] would report.
 pub fn parse_server(opcode: u16, body: &[u8]) -> io::Result<ServerPacket> {
     parse_server_with_tail(opcode, body).map(|(packet, _)| packet)
 }
 
-/// [`parse_server`], also reporting the **tail**: how many of `body`'s bytes the decoder left
-/// unconsumed. A body is length-framed, so a decoder shorter than the server's layout does not
-/// fail — it silently reads a prefix, and the next field the server added is invisible from
-/// outside. A non-zero tail is the instrument for that drift (decision 2265 §B1): the reader
-/// surfaces it on [`crate::Poll::Events`], the app announces it once per opcode. It is a count,
-/// never a failure — a working decoder with a trailing field it has no use for stays working.
-/// An unknown opcode ([`ServerPacket::Other`]) consumes nothing by definition and reports `0`,
-/// so the tally does not double-count what the dropped-packet tally already names.
+/// [`parse_server`], plus how many body bytes the decoder left unread: a count, never a failure,
+/// that exposes a decoder shorter than the server's layout. [`ServerPacket::Other`] reports `0`.
 pub fn parse_server_with_tail(opcode: u16, body: &[u8]) -> io::Result<(ServerPacket, usize)> {
     let mut r = body;
-    // `inner_tail` is the one arm that decodes through a second stream (the compressed update
-    // object): the outer cursor ends at the zlib stream's end, and what the INFLATED bytes left
-    // unread is that packet's tail.
+    // The inflated leftover of the compressed update object, the one arm with a second stream.
     let mut inner_tail = 0;
     let packet = parse_server_body(opcode, &mut r, &mut inner_tail)?;
     let tail = match packet {
@@ -262,9 +214,7 @@ pub fn parse_server_with_tail(opcode: u16, body: &[u8]) -> io::Result<(ServerPac
     Ok((packet, tail))
 }
 
-/// The opcode → variant dispatch over a slice cursor. `cursor` is advanced past what the arm read
-/// **only on success** (an error's partial read is nobody's business); the arms themselves keep
-/// the plain `&[u8]` local every helper is typed over.
+/// The opcode dispatch; `cursor` advances past what the arm read only on success.
 fn parse_server_body(
     opcode: u16,
     cursor: &mut &[u8],
@@ -276,40 +226,18 @@ fn parse_server_body(
             server_seed: read_u32_le(&mut r)?,
         },
         opcode::SMSG_AUTH_RESPONSE => {
-            // **The client's own grammar** (VERIFIED, handler `0x5b41b0`; wow-re
-            // `system/glue/scratch/login-failure-dialogs.md`):
-            //
-            //   u8 code
-            //   if (code == AUTH_OK || code == AUTH_WAIT_QUEUE) && remaining >= 5:
-            //       u32 billingTimeRemaining, u8 billingPlanFlags, u32 billingTimeRested
-            //   if code == AUTH_WAIT_QUEUE:
-            //       u32 position
-            //
-            // The client **branches on the remaining length**, which is what makes both shapes the
-            // mangos family sends parse correctly: the short `{u8, u32}` leaves 4 bytes (`4 < 5`,
-            // billing skipped, position at body offset 1) and the long
-            // `{u8, u32, u8, u32, u32}` leaves 13 (billing read, position at offset 10).
-            //
-            // The threshold is **5 guarding a 9-byte group** — not a size check, just "is there
-            // more here than a bare position?". Copied rather than tidied: a body of 6..=9 bytes
-            // hits it and mis-parses, and matching the client's mistakes is the point of a
-            // faithful parser.
-            //
-            // ONE DELIBERATE DIVERGENCE: where a truncated body leaves the client's position
-            // *unwritten* — silently redisplaying the previous queue position from an
-            // uninitialised process-lifetime global — ours reports `None`. Rendering a stale
-            // position as current is a bug we decline to reproduce.
+            // The client's grammar (`0x5b41b0`): `u8 code`; then, for OK or WAIT_QUEUE with 5+
+            // bytes left, `u32 billingTimeRemaining, u8 billingPlanFlags, u32 billingTimeRested`;
+            // then, for WAIT_QUEUE, `u32 position`. The 5 guarding a 9-byte group is the client's
+            // and mis-parses a 6..=9 byte body; matched on purpose. Deviation: a body too short
+            // for the position gives `None`, because the client redisplays a stale position.
             let result = read_u8(&mut r)?;
             let queued = result == super::AUTH_WAIT_QUEUE;
             let mut billing_time_rested = None;
             if (result == super::AUTH_OK || queued) && r.len() >= 5 {
                 let _billing_time_remaining = read_u32_le(&mut r)?;
                 let _billing_plan_flags = read_u8(&mut r)?;
-                // Kept rather than dropped since 1820: this is the only place the value ever
-                // arrives, and `GetBillingTimeRested()` is a plain read of it. The client parks it
-                // in a process-lifetime global (`[ClientServices+0x1af8]`, sole writer `0x5b421a`);
-                // ours rides the session, which has the same lifetime and cannot go stale across a
-                // reconnect the way that global does.
+                // The only source of `GetBillingTimeRested()` (the client's writer is `0x5b421a`).
                 billing_time_rested = Some(read_u32_le(&mut r)?);
             }
             ServerPacket::AuthResponse {
@@ -320,8 +248,7 @@ fn parse_server_body(
         }
         opcode::SMSG_CHAR_ENUM => {
             let count = read_u8(&mut r)?;
-            // Hint bounded by the realm's character cap: vmangos clamps `CharactersPerRealm` to
-            // 10 (`World.cpp:629`, `setConfigMinMax(…, 10, 1, 10)`).
+            // vmangos clamps `CharactersPerRealm` to 10 (`World.cpp:629`).
             let mut characters = Vec::with_capacity(capacity_hint(count, 10));
             for _ in 0..count {
                 characters.push(Character::read(&mut r)?);
@@ -348,12 +275,9 @@ fn parse_server_body(
         },
         opcode::SMSG_COMPRESSED_UPDATE_OBJECT => {
             let _decompressed_size = read_u32_le(&mut r)?;
-            // Through `&mut r`, so the cursor advances over the compressed bytes. Handed `r` by
-            // value the decoder reads a COPY of the slice, and the whole zlib body then reads
-            // as unconsumed — 803 bytes on the decode-length instrument's first live login
-            // (2266 §B1). The tail that means drift here is the inflated stream's, reported
-            // through `inner_tail`.
-            let mut decoder = flate2::read::ZlibDecoder::new(&mut r);
+            // `&mut r` so the cursor advances over the zlib bytes (by value it reads a copy), and
+            // `bufread`, not `read`, whose 32 KiB buffer would swallow bytes after the stream.
+            let mut decoder = flate2::bufread::ZlibDecoder::new(&mut r);
             let mut decompressed = Vec::new();
             decoder.read_to_end(&mut decompressed)?;
             drop(decoder);
@@ -403,10 +327,8 @@ fn parse_server_body(
             }
         }
         opcode::SMSG_TRANSFER_PENDING => {
-            // `u32 newMapId` +, iff the player rides a transport through the transfer,
-            // `{u32 transportEntry, u32 oldMapId}` (VERIFIED vmangos `Misc.cpp:493-501`). The
-            // block's PRESENCE is load-bearing: it decides whether the follow-up NEW_WORLD's
-            // coordinates are boat-local or world (decision 0455).
+            // `u32 newMapId`, then `{u32 transportEntry, u32 oldMapId}` only when riding a
+            // transport (`Misc.cpp:493-501`), which makes the following NEW_WORLD boat-local.
             let map = read_u32_le(&mut r)?;
             let transport = if r.is_empty() {
                 None
@@ -421,10 +343,8 @@ fn parse_server_body(
             reason: read_u8(&mut r)?,
         },
         opcode::SMSG_LOGIN_SETTIMESPEED => {
-            // The vanilla packed DateTime bit layout (LSB up): minute:6, hour:5, weekday:3,
-            // day-of-month:6, month:4, year:5. The day serial flattens it with the packed
-            // convention's fixed 31-day months / 372-day years — monotonic across the dates a
-            // server actually serves, which is all the celestial moon-phase precession needs.
+            // Packed DateTime, LSB up: minute:6, hour:5, weekday:3, day:6, month:4, year:5. The
+            // day serial assumes 31-day months and 372-day years, monotonic but not calendar-true.
             let datetime = read_u32_le(&mut r)?;
             let timescale = read_f32_le(&mut r)?;
             let (day, month, year) = (
@@ -439,12 +359,7 @@ fn parse_server_body(
                 timescale,
             }
         }
-        // The OTHER clock (decision 1150) — kept beside SETTIMESPEED precisely because they are
-        // easy to confuse: this one is wall-clock UNIX seconds (vmangos
-        // `WorldSession::SendQueryTimeResponse`, `Handlers/QueryHandler.cpp:418-423` — a bare
-        // `(uint32)time(nullptr)`), the epoch every absolute stamp the server writes into a
-        // descriptor field is expressed in. SETTIMESPEED above is the in-game day/night clock and
-        // says nothing about it.
+        // Wall-clock unix seconds (`QueryHandler.cpp:418-423`), not the game clock above.
         opcode::SMSG_QUERY_TIME_RESPONSE => ServerPacket::QueryTimeResponse {
             unix_time: read_u32_le(&mut r)?,
         },
@@ -459,8 +374,7 @@ fn parse_server_body(
                 area,
             }
         }
-        // The GM trouble-ticket answers (decision 1673). The three response opcodes share one
-        // 4-byte body and therefore one reader; only the opcode says which verb was answered.
+        // The ticket response opcodes share one 4-byte body; only the opcode names the verb.
         opcode::SMSG_GMTICKET_GETTICKET => ServerPacket::GmTicketAnswer {
             ticket: gm_ticket::read_gm_ticket(&mut r)?.map(Box::new),
         },
@@ -482,8 +396,7 @@ fn parse_server_body(
         opcode::SMSG_BINDER_CONFIRM => ServerPacket::BinderConfirm {
             binder: binder::read_binder_confirm(&mut r)?,
         },
-        // The summon question (decision 1747). Three fields, and the client's whole answer is
-        // the guid back — see `super::summon` for the byte pin on both bodies.
+        // The summon question; the client's whole answer is the guid back.
         opcode::SMSG_SUMMON_REQUEST => {
             let ask = summon::read_summon_request(&mut r)?;
             ServerPacket::SummonRequest {
@@ -492,8 +405,7 @@ fn parse_server_body(
                 delay_ms: ask.delay_ms,
             }
         }
-        // The talent twin of the confirm above, on a two-way `MSG_` opcode: this direction is the
-        // question (guid + cost); the answer we send back carries the guid alone (decision 1580).
+        // Two-way `MSG_`: inbound is the question (guid, cost); our answer is the guid alone.
         opcode::MSG_TALENT_WIPE_CONFIRM => {
             let ask = progression::read_talent_wipe_confirm(&mut r)?;
             ServerPacket::TalentWipeConfirm {
@@ -608,13 +520,10 @@ fn parse_server_body(
         opcode::SMSG_TEXT_EMOTE => {
             let guid = read_u64_le(&mut r)?;
             let text_emote = read_u32_le(&mut r)?;
-            // Read and dropped on purpose — `emoteNum` selects neither the sentence nor the voice
-            // kit on the receive side (wow-re `ui/scratch/text-emote-composition.md` §3).
+            // `emoteNum` picks neither sentence nor voice kit on the reference's receive side.
             let _emote_num = read_u32_le(&mut r)?;
-            // The target's name, length-prefixed **including its NUL** (vmangos writes a lone
-            // `0x00` and `namelen == 1` when there was no target). Trimmed at the first NUL, so an
-            // untargeted emote arrives as the empty string — which is precisely the "untargeted"
-            // bit of the sentence-form selector, not a missing value.
+            // The target's name, length-prefixed including its NUL (a lone `0x00` for no
+            // target); trimmed at the first NUL, so no target reads as "", the untargeted form.
             let namelen = read_u32_le(&mut r)? as usize;
             let mut name = Vec::with_capacity(capacity_hint(namelen, 64));
             for _ in 0..namelen {
@@ -736,8 +645,7 @@ fn parse_server_body(
         opcode::SMSG_PET_TAME_FAILURE => ServerPacket::PetTameFailure {
             reason: pet::read_pet_tame_failure(&mut r)?,
         },
-        // Both bodies really are empty — the opcode is the whole message on either (vmangos's
-        // `AppendBodyTo` writes nothing, and the reference's handlers read nothing).
+        // Empty bodies on both sides: vmangos writes nothing and the reference reads nothing.
         opcode::SMSG_PET_NAME_INVALID => ServerPacket::PetNameInvalid,
         opcode::SMSG_PET_BROKEN => ServerPacket::PetBroken,
         opcode::SMSG_PET_ACTION_SOUND => {
@@ -759,9 +667,8 @@ fn parse_server_body(
         opcode::SMSG_ATTACKERSTATEUPDATE => {
             ServerPacket::AttackerState(attack::read_attacker_state(&mut r)?)
         }
-        // The swing refusals — empty bodies, nothing read. `SMSG_ATTACKSWING_NOTSTANDING` (`0x147`)
-        // is deliberately absent: the reference never registers it and vmangos never sends it, so
-        // it falls to the unknown-opcode arm exactly as it does in the real client's dispatcher.
+        // The empty swing refusals. `SMSG_ATTACKSWING_NOTSTANDING` (`0x147`) is absent on purpose:
+        // the reference never registers it and vmangos never sends it.
         opcode::SMSG_ATTACKSWING_NOTINRANGE => {
             ServerPacket::AttackSwingError(AttackSwingError::NotInRange)
         }
@@ -771,7 +678,7 @@ fn parse_server_body(
         opcode::SMSG_ATTACKSWING_DEADTARGET | opcode::SMSG_ATTACKSWING_CANT_ATTACK => {
             ServerPacket::AttackSwingError(AttackSwingError::DeadOrUnattackable)
         }
-        // The family's fourth arm, from the spell TU's registration — same empty body, same act.
+        // The family's fourth arm, registered with the spell handlers: same empty body, same act.
         opcode::SMSG_CANCEL_COMBAT => ServerPacket::CancelCombat,
         opcode::SMSG_FEIGN_DEATH_RESISTED => ServerPacket::FeignDeathResisted,
         opcode::SMSG_AI_REACTION => {
@@ -815,7 +722,7 @@ fn parse_server_body(
                 seconds,
             }
         }
-        // One body, two tables — the opcode picks, exactly as `0x6e9950`'s `cmp edi,0x267` does.
+        // One body, two tables: the opcode picks, as `0x6e9950`'s `cmp edi,0x267` does.
         opcode::SMSG_SET_FLAT_SPELL_MODIFIER | opcode::SMSG_SET_PCT_SPELL_MODIFIER => {
             let (mask_bit, op, value) = spells::read_set_spell_modifier(&mut r)?;
             ServerPacket::SpellModifier {
@@ -881,7 +788,7 @@ fn parse_server_body(
         opcode::SMSG_SPELLINSTAKILLLOG => {
             ServerPacket::SpellInstaKillLog(combat_log::read_spell_insta_kill_log(&mut r)?)
         }
-        // One body, two sentences — the arm is the only thing that tells them apart.
+        // One body, two sentences: only the opcode tells them apart.
         opcode::SMSG_PROCRESIST => {
             ServerPacket::ProcResist(combat_log::read_spell_outcome_log(&mut r)?)
         }
@@ -1109,11 +1016,8 @@ fn parse_server_body(
         opcode::SMSG_SPIRIT_HEALER_CONFIRM => ServerPacket::SpiritHealerConfirm {
             npc: death::read_spirit_healer_confirm(&mut r)?,
         },
-        // **The ack'd movement-mode family** (decision 0866) — root, water-walk, feather-fall and
-        // hover, granted to the controlling client. ONE wire shape for all eight opcodes:
-        // `packed guid + u32 counter` (VERIFIED vmangos `MovementPacketSender.cpp:342-366`, the
-        // `> CLIENT_BUILD_1_9_4` branch). The app must ack with the echoed counter, or the server
-        // never applies the change and observers never see it.
+        // The acked mode family, all eight `packed guid, u32 counter`
+        // (`MovementPacketSender.cpp:342-366`); unacked, the server never applies the change.
         opcode::SMSG_FORCE_MOVE_ROOT
         | opcode::SMSG_FORCE_MOVE_UNROOT
         | opcode::SMSG_MOVE_WATER_WALK
@@ -1141,11 +1045,8 @@ fn parse_server_body(
                 apply,
             }
         }
-        // **The observer movement-mode family** (decision 1780) — the spline-move twelve. Body is a
-        // BARE packed guid: no counter, no `MovementInfo`, and nothing to ack (VERIFIED vmangos
-        // `MovementPacketSender::SendMovementFlagChangeToAll`/`SendToggleRunWalkToAll`, and the
-        // reference's single handler `0x603c80`, which reads one packed guid and dispatches).
-        // `guid` is any unit, not our mover — the constants block in `opcode` carries the arm map.
+        // The observer mode family: twelve bare packed guids for any unit, nothing to ack
+        // (vmangos `SendMovementFlagChangeToAll`; the reference's one handler `0x603c80`).
         opcode::SMSG_SPLINE_MOVE_ROOT
         | opcode::SMSG_SPLINE_MOVE_UNROOT
         | opcode::SMSG_SPLINE_MOVE_WATER_WALK
@@ -1169,7 +1070,7 @@ fn parse_server_body(
                 opcode::SMSG_SPLINE_MOVE_UNSET_HOVER => (SplineMode::Hover, false),
                 opcode::SMSG_SPLINE_MOVE_START_SWIM => (SplineMode::Swimming, true),
                 opcode::SMSG_SPLINE_MOVE_STOP_SWIM => (SplineMode::Swimming, false),
-                // The one inverted pair: RUN_MODE *clears* `MOVEFLAG_WALK_MODE`, because the
+                // The one inverted pair: RUN_MODE clears `MOVEFLAG_WALK_MODE`, because the
                 // reference's `0x617e80` feeds the opcode's bool to `SetRunMode 0x7c71c0`.
                 opcode::SMSG_SPLINE_MOVE_SET_WALK_MODE => (SplineMode::WalkMode, true),
                 _ => (SplineMode::WalkMode, false),
@@ -1180,12 +1081,9 @@ fn parse_server_body(
                 apply,
             }
         }
-        // **The knockback the server aims at our mover** (decision 1702): `packed guid + u32
-        // counter`, then the launch quad `vcos, vsin, speedXY, speedZ` (VERIFIED vmangos
-        // `MovementPacketSender.cpp:261-277`, the `> CLIENT_BUILD_1_9_4` branch). The quad reads
-        // straight into a [`JumpInfo`] — it *is* the jump tail the ack must echo — but the wire
-        // order here is direction-first, where `JumpInfo`'s own serialization is `zspeed` first, so
-        // the four reads are named rather than delegated.
+        // `packed guid, u32 counter`, then `vcos, vsin, speedXY, speedZ`
+        // (`MovementPacketSender.cpp:261-277`): the jump tail the ack echoes, but direction-first
+        // where `JumpInfo` serializes `zspeed` first, so the reads are spelled out.
         opcode::SMSG_MOVE_KNOCK_BACK => {
             let guid = read_packed_guid(&mut r)?;
             let counter = read_u32_le(&mut r)?;
@@ -1245,7 +1143,7 @@ fn parse_server_body(
         }
         opcode::SMSG_CREATURE_QUERY_RESPONSE => {
             let entry = read_u32_le(&mut r)?;
-            // A miss is the lone entry echoed with its top bit set — nothing follows.
+            // A miss is the lone entry echoed with its top bit set; nothing follows.
             if entry & 0x8000_0000 != 0 {
                 ServerPacket::CreatureQueryResponse {
                     entry: entry & 0x7FFF_FFFF,
@@ -1257,17 +1155,8 @@ fn parse_server_body(
                     let _ = read_cstring(&mut r)?; // name2..name4, always empty in 5875
                 }
                 let subname = read_cstring(&mut r)?;
-                // The tail (VERIFIED vmangos `HandleCreatureQueryOpcode`, 5875 = every build
-                // guard included): type_flags, type, pet_family, RANK, unk, pet_spell_list_id,
-                // display_id (u32 ×7), then civilian + racial_leader (u8 ×2). We keep `type`
-                // (the `CreatureType.dbc` id — the TAB-target filter's input), `pet_family` (the
-                // `CreatureFamily.dbc` id behind `UnitCreatureFamily` and the diet tooltip,
-                // decision 1062), `rank` (the unit tooltip's Elite/Boss word, decision 0276's
-                // level-line law), `type_flags` (bit 0x10 hides its faction line), the
-                // `civilian`/`racial_leader` pair (its green CIVILIAN / white LEADER lines), and
-                // `display_id` — the template's model, which is the ONLY way to draw a creature
-                // that has no world object to read `UNIT_FIELD_DISPLAYID` off: a stabled pet
-                // (decision 1676). The `unk`/`pet_spell_list_id` pair stays alignment-only.
+                // `HandleCreatureQueryOpcode`: seven `u32`s (type_flags, type, pet_family, rank,
+                // unk, pet_spell_list_id, display_id), then civilian and racial_leader as `u8`s.
                 let type_flags = read_u32_le(&mut r)?;
                 let creature_type = read_u32_le(&mut r)?;
                 let pet_family = read_u32_le(&mut r)?;
@@ -1293,9 +1182,8 @@ fn parse_server_body(
                 }
             }
         }
-        // `u32 petNumber`, cstring name, `u32 nameTimestamp` (VERIFIED vmangos
-        // `PetNameQueryResponse::AppendBodyTo`, `Server/Packets/Pet.cpp:79-84`). The timestamp ages
-        // out the reference's on-disk pet-name cache; we keep none, so it is alignment-only.
+        // `u32 petNumber, cstring name, u32 nameTimestamp` (`Pet.cpp:79-84`); the timestamp only
+        // ages the reference's on-disk pet-name cache.
         opcode::SMSG_PET_NAME_QUERY_RESPONSE => {
             let pet_number = read_u32_le(&mut r)?;
             let name = read_cstring(&mut r)?;
@@ -1322,31 +1210,32 @@ fn parse_server_body(
             let guid = gameobject::read_gameobject_despawn_anim(&mut r)?;
             ServerPacket::GameObjectDespawnAnim { guid }
         }
-        // Both fishing verdicts are empty-bodied (the opcode IS the message).
+        opcode::SMSG_OPEN_CONTAINER => ServerPacket::OpenContainer {
+            item: items::read_open_container(&mut r)?,
+        },
+        opcode::SMSG_INSPECT => ServerPacket::Inspect {
+            guid: items::read_inspect(&mut r)?,
+        },
+        opcode::SMSG_STANDSTATE_UPDATE => ServerPacket::StandStateUpdate {
+            state: pose::read_stand_state_update(&mut r)?,
+        },
         opcode::SMSG_FISH_NOT_HOOKED => ServerPacket::FishNotHooked,
         opcode::SMSG_FISH_ESCAPED => ServerPacket::FishEscaped,
         opcode::SMSG_LOGOUT_COMPLETE => ServerPacket::LogoutComplete,
-        // `{u32 reason, u8 instant}` — the `instant` byte is what the CAMP/QUIT countdown hangs
-        // on (see the variant's own doc); it used to be dropped on the floor here.
         opcode::SMSG_LOGOUT_RESPONSE => ServerPacket::LogoutResponse {
             reason: read_u32_le(&mut r)?,
             instant: read_u8(&mut r)? != 0,
         },
         opcode::SMSG_LOGOUT_CANCEL_ACK => ServerPacket::LogoutCancelAck,
-        // The keepalive echo: our CMSG_PING's sequence number back (vmangos `_HandlePing` — the
-        // body is the one u32 it read from us).
         opcode::SMSG_PONG => ServerPacket::Pong {
             sequence: read_u32_le(&mut r)?,
         },
-        // The force-speed-change family — one arm per kind, one shared body reader (the wire shape
-        // and the mandatory ack protocol are documented on the opcode block).
         opcode::SMSG_FORCE_WALK_SPEED_CHANGE => read_force_speed(SpeedKind::Walk, &mut r)?,
         opcode::SMSG_FORCE_RUN_SPEED_CHANGE => read_force_speed(SpeedKind::Run, &mut r)?,
         opcode::SMSG_FORCE_RUN_BACK_SPEED_CHANGE => read_force_speed(SpeedKind::RunBack, &mut r)?,
         opcode::SMSG_FORCE_SWIM_SPEED_CHANGE => read_force_speed(SpeedKind::Swim, &mut r)?,
         opcode::SMSG_FORCE_SWIM_BACK_SPEED_CHANGE => read_force_speed(SpeedKind::SwimBack, &mut r)?,
         opcode::SMSG_FORCE_TURN_RATE_CHANGE => read_force_speed(SpeedKind::TurnRate, &mut r)?,
-        // The group/party family (see the opcode block's note; bodies in `group`).
         opcode::SMSG_GROUP_INVITE => ServerPacket::GroupInvite {
             inviter: group::read_group_invite(&mut r)?,
         },
@@ -1403,8 +1292,7 @@ fn parse_server_body(
                 ServerPacket::ReadyCheckAnswer { guid, ready }
             }
         },
-        // The instance/raid lockout family (decision 1748; bodies in `instance`). Every one of
-        // these is read here in the client's own field order.
+        // The lockout family, read in the client's own field order.
         opcode::SMSG_RAID_INSTANCE_MESSAGE => ServerPacket::RaidInstanceMessage {
             message: instance::read_raid_instance_message(&mut r)?,
         },
@@ -1423,8 +1311,6 @@ fn parse_server_body(
         opcode::SMSG_UPDATE_INSTANCE_OWNERSHIP => ServerPacket::UpdateInstanceOwnership {
             owns: instance::read_u32_body(&mut r)?,
         },
-        // The duel family (decision 0633; bodies in `duel`). Both empty-body arms carry their
-        // whole meaning in the opcode.
         opcode::SMSG_DUEL_REQUESTED => {
             let req = duel::read_duel_requested(&mut r)?;
             ServerPacket::DuelRequested {
@@ -1448,18 +1334,11 @@ fn parse_server_body(
         opcode::SMSG_DUEL_COUNTDOWN => ServerPacket::DuelCountdown {
             seconds: duel::read_duel_countdown(&mut r)?,
         },
-        // The honor pair (decision 1512; bodies in `pvp`). MSG_INSPECT_HONOR_STATS is an `MSG_`:
-        // opcode 0x2D6 carries our 8-byte request AND the server's 50-byte reply. There is no
-        // ambiguity to resolve here — `parse_server` is fed only by the world *reader*, so an
-        // 0x2D6 body arriving at this function is always the reply. The request shape is built by
-        // `pvp::inspect_honor_stats` and goes straight out through `world::writer::pvp`; it never
-        // reaches this match.
+        // `0x2D6` carries our 8-byte request and the 50-byte reply; only the reply reaches here.
         opcode::MSG_INSPECT_HONOR_STATS => {
             ServerPacket::InspectHonorStats(pvp::read_inspect_honor_stats(&mut r)?)
         }
         opcode::SMSG_PVP_CREDIT => ServerPacket::PvpCredit(pvp::read_pvp_credit(&mut r)?),
-        // The mirror timers (decision 0874; bodies in `mirror_timer`). START carries the timer's
-        // whole state and is re-sent on every change — there is no update opcode in the family.
         opcode::SMSG_START_MIRROR_TIMER => {
             ServerPacket::MirrorTimerStart(mirror_timer::read_start_mirror_timer(&mut r)?)
         }
@@ -1470,8 +1349,6 @@ fn parse_server_body(
         opcode::SMSG_STOP_MIRROR_TIMER => ServerPacket::MirrorTimerStop {
             kind: mirror_timer::read_stop_mirror_timer(&mut r)?,
         },
-        // The social family (decision 0668; bodies in `social`). Both list packets are
-        // replace-everything snapshots; the status packet is one result about one player.
         opcode::SMSG_FRIEND_LIST => ServerPacket::FriendList {
             friends: social::read_friend_list(&mut r)?,
         },
@@ -1482,10 +1359,6 @@ fn parse_server_body(
             ServerPacket::FriendStatus(social::read_friend_status(&mut r)?)
         }
         opcode::SMSG_WHO => ServerPacket::WhoResults(social::read_who(&mut r)?),
-        // The guild family (bodies in `guild`). The two big ones are caches — a query response
-        // fills the guild-id→identity cache, the roster replaces the whole membership — and the
-        // three small ones are notifications. `SMSG_GUILD_ROSTER`'s member loop carries the
-        // family's one conditional field; see `guild::read_guild_roster`.
         opcode::SMSG_GUILD_QUERY_RESPONSE => {
             ServerPacket::GuildQueryResponse(guild::read_guild_query_response(&mut r)?)
         }
@@ -1502,10 +1375,7 @@ fn parse_server_body(
             name: guild::read_guild_decline(&mut r)?,
         },
         opcode::SMSG_GUILD_INFO => ServerPacket::GuildInfo(guild::read_guild_info(&mut r)?),
-        // The petition family (bodies in `petition`) — founding a guild, which at 1.12 is an
-        // entirely different wire from the guild family above. Note `SMSG_PETITION_SHOW_SIGNATURES`
-        // answers two different asks, and the two `MSG_` opcodes read a *different* body from the
-        // one they write (see `petition`'s own docs).
+        // Guild founding; the two `MSG_` opcodes read a different body from the one they write.
         opcode::SMSG_PETITION_SHOWLIST => {
             ServerPacket::PetitionShowList(petition::read_petition_show_list(&mut r)?)
         }
@@ -1527,9 +1397,6 @@ fn parse_server_body(
         opcode::MSG_PETITION_RENAME => {
             ServerPacket::PetitionRenamed(petition::read_petition_rename(&mut r)?)
         }
-        // The observer speed legs (decision 0441): a unit we don't control changed speed — a
-        // creature or mid-spline player (SPLINE family), or a freely-moving player (MOVE_SET
-        // family, which carries a fresh pose too). No ack on either.
         opcode::SMSG_SPLINE_SET_WALK_SPEED => read_spline_speed(SpeedKind::Walk, &mut r)?,
         opcode::SMSG_SPLINE_SET_RUN_SPEED => read_spline_speed(SpeedKind::Run, &mut r)?,
         opcode::SMSG_SPLINE_SET_RUN_BACK_SPEED => read_spline_speed(SpeedKind::RunBack, &mut r)?,
@@ -1542,8 +1409,6 @@ fn parse_server_body(
         opcode::MSG_MOVE_SET_SWIM_SPEED => read_move_set_speed(SpeedKind::Swim, &mut r)?,
         opcode::MSG_MOVE_SET_SWIM_BACK_SPEED => read_move_set_speed(SpeedKind::SwimBack, &mut r)?,
         opcode::MSG_MOVE_SET_TURN_RATE => read_move_set_speed(SpeedKind::TurnRate, &mut r)?,
-        // Mount feedback (decision 0441): one u32 result code per attempt; error lines are a P2
-        // trimming — decoded so the wire is modelled, surfaced for the debug log.
         opcode::SMSG_MOUNTRESULT => ServerPacket::MountResult {
             mount: true,
             code: read_u32_le(&mut r)?,
@@ -1552,20 +1417,15 @@ fn parse_server_body(
             mount: false,
             code: read_u32_le(&mut r)?,
         },
-        // A nearby rider's flourish: one raw u64 guid (VERIFIED vmangos
-        // `HandleMountSpecialAnimOpcode` — `data << GetObjectGuid()`, full 8 bytes, not packed).
+        // A full 8-byte guid, not packed (vmangos `HandleMountSpecialAnimOpcode`).
         opcode::SMSG_MOUNTSPECIAL_ANIM => ServerPacket::MountSpecialAnim {
             guid: read_u64_le(&mut r)?,
         },
-        // The control handoff: PACKED guid (unlike the flourish above) + one byte (VERIFIED
-        // vmangos `Server/Packets/Misc.cpp:677-682` — `WriteAsPacked()`, then `uint8 allowMove`).
+        // A packed guid, unlike the flourish, then `u8 allowMove` (`Misc.cpp:677-682`).
         opcode::SMSG_CLIENT_CONTROL_UPDATE => ServerPacket::ClientControlUpdate {
             mover: read_packed_guid(&mut r)?,
             allow_move: read_u8(&mut r)? != 0,
         },
-        // The taxi/flight-master family (decision 0484): the map (SHOWTAXINODES), a status
-        // answer/first-visit learn (TAXINODE_STATUS), the activate verdict, and the multi-hop
-        // path ack (NEW_TAXI_PATH, empty body).
         opcode::SMSG_SHOWTAXINODES => {
             let (window, flightmaster, nearest_node, known) = taxi::read_show_taxi_nodes(&mut r)?;
             ServerPacket::ShowTaxiNodes {
@@ -1586,9 +1446,6 @@ fn parse_server_body(
             code: taxi::read_activate_taxi_reply(&mut r)?,
         },
         opcode::SMSG_NEW_TAXI_PATH => ServerPacket::NewTaxiPath,
-        // The mail arc (decision 0544 P0): the inbox list, the send/take/return/delete verdict,
-        // the letter-body ask-once fetch, and the arrival pair (RECEIVED_MAIL + the
-        // QUERY_NEXT_MAIL_TIME reply — same opcode as our empty-body request).
         opcode::SMSG_MAIL_LIST_RESULT => ServerPacket::MailList {
             mails: mail::read_mail_list_result(&mut r)?,
         },
@@ -1612,11 +1469,8 @@ fn parse_server_body(
         opcode::MSG_QUERY_NEXT_MAIL_TIME => ServerPacket::NextMailTime {
             seconds: mail::read_query_next_mail_time(&mut r)?,
         },
-        // The auction house arc (decision 1511 P0). MSG_AUCTION_HELLO is two-way — this is the
-        // REPLY (our request is the same opcode with just the guid), and it is what opens the
-        // window. The three list results share one frame and one 64-byte record; their reader is
-        // bounded by the buffer as well as by the wire `count`, because vmangos's browse fast path
-        // can count a record it then fails to write.
+        // The three list results share one frame and a 64-byte record; the reader is bounded by
+        // the buffer too, since vmangos's browse fast path can count a record it never writes.
         opcode::MSG_AUCTION_HELLO => {
             let (auctioneer, house_id) = auction::read_auction_hello(&mut r)?;
             ServerPacket::AuctionHello {
@@ -1654,8 +1508,7 @@ fn parse_server_body(
                 total_count,
             }
         }
-        // The two notifications carry different field orders and the owner one has no house id —
-        // two readers, never one.
+        // Different field orders, and no house id on the owner's: two readers, never one.
         opcode::SMSG_AUCTION_BIDDER_NOTIFICATION => ServerPacket::AuctionBidderNotification(
             auction::read_auction_bidder_notification(&mut r)?,
         ),
@@ -1671,16 +1524,13 @@ fn parse_server_body(
                 random_property_id,
             }
         }
-        // The player-trade arc (decision 0592 P0): the state-machine status pulse and the
-        // item/gold snapshot for one window side.
         opcode::SMSG_TRADE_STATUS => ServerPacket::TradeStatus {
             status: trade::read_trade_status(&mut r)?,
         },
         opcode::SMSG_TRADE_STATUS_EXTENDED => ServerPacket::TradeStatusExtended {
             state: Box::new(trade::read_trade_status_extended(&mut r)?),
         },
-        // The world-state table — the `$<n>w`/`$<n>e` NPC-text tokens' source (and a battleground
-        // scoreboard's, later). Both opcodes write the one table; see [`super::world_state`].
+        // The world-state table, source of the `$<n>w`/`$<n>e` NPC-text tokens.
         opcode::SMSG_INIT_WORLD_STATES => {
             ServerPacket::InitWorldStates(world_state::read_init_world_states(&mut r)?)
         }
@@ -1688,9 +1538,7 @@ fn parse_server_body(
             let (id, value) = world_state::read_update_world_state(&mut r)?;
             ServerPacket::UpdateWorldState { id, value }
         }
-        // A relayed player movement packet: `[packed mover guid][MovementInfo]`, same opcode the mover
-        // sent. This is how other players' walking/turning/strafing reaches us (creatures use
-        // SMSG_MONSTER_MOVE instead). Surface the pose + live move-flags; the app extrapolates between.
+        // Another player's move, relayed under the mover's opcode (creatures use monster moves).
         o if is_movement_relay(o) => {
             let guid = read_packed_guid(&mut r)?;
             let info = movement::read_movement_info(&mut r)?;
@@ -1720,8 +1568,6 @@ fn parse_server_body(
 mod tests {
     use super::*;
 
-    /// The tail is the decoder's unconsumed remainder: a known-good body reports 0, the same body
-    /// with one byte appended reports 1, and neither is an error.
     #[test]
     fn a_trailing_byte_is_reported_as_tail_one_and_never_as_a_failure() {
         // `SMSG_SET_FACTION_VISIBLE`: exactly one `u32 repListId`.
@@ -1743,14 +1589,9 @@ mod tests {
             ServerPacket::SetFactionVisible { list_id: 21 }
         ));
         assert_eq!(tail, 1);
-        // …and the projection every existing caller uses is unchanged by it.
         assert!(parse_server(opcode::SMSG_SET_FACTION_VISIBLE, &longer).is_ok());
     }
 
-    /// The compressed update object decodes through a second stream. Its zlib bytes are consumed
-    /// through the cursor (a copy of the slice read the whole body as a tail — 803 bytes on the
-    /// instrument's first live login), and the tail it reports is what the INFLATED stream left
-    /// unread — the one leftover that means the inner layout drifted.
     #[test]
     fn the_compressed_update_object_reports_the_inflated_streams_tail_not_its_zlib_bytes() {
         use std::io::Write;
@@ -1775,10 +1616,18 @@ mod tests {
             parse_server_with_tail(opcode::SMSG_COMPRESSED_UPDATE_OBJECT, &body(&longer))
                 .expect("a trailing inflated byte is not a failure");
         assert_eq!(tail, 1, "the inflated stream's leftover is the tail");
+
+        // Bytes after the zlib stream, still in the packet body, are the outer tail.
+        let mut outer = body(&empty);
+        outer.extend([0xAB, 0xCD]);
+        let (_, tail) = parse_server_with_tail(opcode::SMSG_COMPRESSED_UPDATE_OBJECT, &outer)
+            .expect("bytes after the stream are not a failure");
+        assert_eq!(
+            tail, 2,
+            "the body's bytes after the zlib stream are the tail"
+        );
     }
 
-    /// An unknown opcode consumes nothing by definition; reporting its whole body as a tail would
-    /// double-count what the dropped-packet tally already names.
     #[test]
     fn an_unknown_opcode_reports_no_tail() {
         let (packet, tail) =
@@ -1787,10 +1636,9 @@ mod tests {
         assert_eq!(tail, 0);
     }
 
-    /// **The falsifier for decision 2265 §B1**: a wire count of `0xFFFF_FFFF` followed by one
-    /// valid row must come back as a short-read `Err` — never reserve the count, never abort.
+    /// A count past the body ends in `UnexpectedEof` at the first missing row, in both opcodes.
     #[test]
-    fn a_lying_faction_count_is_a_short_read_not_an_allocation() {
+    fn a_lying_faction_count_is_a_short_read() {
         let mut body = 0xFFFF_FFFFu32.to_le_bytes().to_vec();
         body.push(0x01); // flags
         body.extend_from_slice(&3000i32.to_le_bytes()); // standing
diff --git a/crates/benilla-protocol/src/messages/pet.rs b/crates/benilla-protocol/src/messages/pet.rs
index 9bfcb92d..39ff4257 100644
--- a/crates/benilla-protocol/src/messages/pet.rs
+++ b/crates/benilla-protocol/src/messages/pet.rs
@@ -1,174 +1,96 @@
-//! Pet messages — the pet action bar's state packet and the client verbs that drive it
-//! (decisions 0982, 0988). Mirrored on the outbound side by `world::writer::pet`.
-//!
-//! The **shape of the system** is worth stating once, because it is neither the action bar's nor
-//! the one it looks like. The bar's **contents** are the server's: `SMSG_PET_SPELLS` carries all
-//! ten slots and nothing else does. The bar's **state** — the lit command, the lit reaction, the
-//! autocast bit, "the pet is attacking" — is the **client's**, applied on the press and never
-//! confirmed. Not as an optimisation: the server does not answer these packets at all, and the
-//! real client writes its own state and repaints before the send (wow-re §10.1/§10.2). A client
-//! that waited would show a bar that never lights.
-//!
-//! Compare the player's 120-slot bar, which is client-authoritative and merely *echoed* to the
-//! server ([`super::action_bar`], decisions 0216 §7/0218 §4): different split, same lesson — know
-//! which half of a surface each end owns before writing either.
-//!
-//! `SMSG_PET_SPELLS` carries the whole bar in one body, and the same body serves a hunter/warlock
-//! pet, a possessed minion and a charmed creature (vmangos `Player::PetSpellInitialize` /
-//! `PossessSpellInitialize` / `CharmSpellInitialize`, `Objects/Player.cpp:17519-17672` — three
-//! builders, one byte layout: the possess builder's `int32 duration` + `uint32 0` occupies exactly
-//! the pet builder's `uint32 0` + four state bytes). Its **guid-only** form (an 8-byte body
-//! carrying a zero guid — `Player::RemovePetActionBar`) is the teardown: the bar goes away.
+//! Pet messages: the pet action bar's state packet and the client verbs that drive it. The bar's
+//! contents are the server's; its state (lit command, lit reaction, autocast) is the client's,
+//! applied on the press, because the server never answers these verbs.
 
 use std::io::{self, Read};
 
 use crate::wire::{capacity_hint, read_u16_le, read_u32_le, read_u64_le, read_u8, Vector3d};
 
-/// Pet action-bar slots (vmangos `MAX_UNIT_ACTION_BAR_INDEX` = `ACTION_BAR_INDEX_END(10) -
-/// ACTION_BAR_INDEX_START(0)`, `Objects/UnitDefines.h:781-787`); the client's own
-/// `NUM_PET_ACTION_SLOTS` is the same 10 (`PetActionBarFrame.lua:4`).
+/// Pet bar slots: vmangos `MAX_UNIT_ACTION_BAR_INDEX`, FrameXML's `NUM_PET_ACTION_SLOTS`.
 pub const PET_ACTION_SLOTS: usize = 10;
 
-/// `ActiveStates` — the value the **server** puts in a packed word's top byte (vmangos
-/// `Objects/UnitDefines.h:724-732`). These are what you BUILD a word from; they are **not** what
-/// you decode one into (see [`PetActionEntry::kind`], and the note below).
-///
-/// A passive spell: shown, never clickable, no autocast.
+/// vmangos `ActiveStates` (`UnitDefines.h:724-732`): the server's top byte of a packed word; the
+/// client decodes the masked [`PetActionEntry::kind`] instead. Passive: shown, never clickable.
 pub const PET_ACT_PASSIVE: u8 = 0x01;
-/// A castable spell with autocast OFF — `0x01 | ` [`PET_AUTOCAST_ALLOWED`]`>>24`.
+/// A castable spell with autocast off: `0x01 | ` [`PET_AUTOCAST_ALLOWED`]`>>24`.
 pub const PET_ACT_DISABLED: u8 = 0x81;
-/// A castable spell with autocast ON — `0x81 | ` [`PET_AUTOCAST_ON`]`>>24`.
+/// A castable spell with autocast on: `0x81 | ` [`PET_AUTOCAST_ON`]`>>24`.
 pub const PET_ACT_ENABLED: u8 = 0xC1;
-/// A command token — the action is a [`PET_COMMAND_STAY`]-family value, not a spell id.
+/// A command token: the action is a [`PET_COMMAND_STAY`]-family value, not a spell id.
 pub const PET_ACT_COMMAND: u8 = 0x07;
-/// A reaction token — the action is a [`PET_REACT_PASSIVE`]-family value, not a spell id.
+/// A reaction token: the action is a [`PET_REACT_PASSIVE`]-family value, not a spell id.
 pub const PET_ACT_REACTION: u8 = 0x06;
 
-/// The **client's** slot type, after its own `& 0x3F` mask (wow-re
-/// `system/ui/scratch/pet-action-bar-api.md` §1, `0x4bdccd`). This is the vocabulary a decoded
-/// word speaks, and it is deliberately SHORTER than `ActiveStates`': the mask drops bits 30/31,
-/// which is precisely what collapses [`PET_ACT_PASSIVE`], [`PET_ACT_DISABLED`] and
-/// [`PET_ACT_ENABLED`] — three server states — onto **one** client type, with the autocast pair
-/// carried separately as [`PET_AUTOCAST_ALLOWED`]/[`PET_AUTOCAST_ON`].
-///
-/// `GetPetActionInfo`'s jump table sends types 1–5 down the spell branch, 6 to reaction, 7 to
-/// command (§2). The two token constants are numerically the `ACT_` ones, so a `kind()` compare
-/// against `PET_ACT_COMMAND`/`PET_ACT_REACTION` still reads correctly; the spell family does not,
-/// which is why [`PetActionEntry::is_spell`] is a range and not a set of equalities.
+/// First spell-branch slot type. The client's type is the top byte `& 0x3F` (`0x4bdccd`), which
+/// folds all three spell `ActiveStates` onto 1; types 6 and 7 are reaction and command.
 pub const PET_TYPE_SPELL_FIRST: u8 = 1;
 /// The last type the client's jump table routes to the spell branch.
 pub const PET_TYPE_SPELL_LAST: u8 = 5;
 
-/// Bit 31 of a packed word: this slot **may** autocast (wow-re §2.1, `0x4bdd65`). The client
-/// additionally requires the spell to exist in `Spell.dbc` before reporting it.
+/// Bit 31 of a packed word: the slot may autocast (`0x4bdd65`), given a `Spell.dbc` record.
 pub const PET_AUTOCAST_ALLOWED: u32 = 0x8000_0000;
-/// Bit 30: autocast is currently **running** (wow-re §2.1, `0x4bdda4`). This is the bit
-/// `TogglePetAutocast` flips in place before it sends (§10.2, `0x4bcbff`).
+/// Bit 30: autocast is running (`0x4bdda4`); `TogglePetAutocast` flips it before the send.
 pub const PET_AUTOCAST_ON: u32 = 0x4000_0000;
 
-/// `CommandStates` (vmangos `UnitDefines.h:755-761`) — the action value carried by a
-/// [`PET_ACT_COMMAND`] slot, and what `CharmInfo::GetCommandState` reports.
+/// vmangos `CommandStates` (`UnitDefines.h:755-761`): a [`PET_ACT_COMMAND`] slot's action.
 pub const PET_COMMAND_STAY: u32 = 0;
 pub const PET_COMMAND_FOLLOW: u32 = 1;
 pub const PET_COMMAND_ATTACK: u32 = 2;
 pub const PET_COMMAND_DISMISS: u32 = 3;
 
-/// `ReactStates` (vmangos `UnitDefines.h:734-739`) — the action value carried by a
-/// [`PET_ACT_REACTION`] slot, and what `CharmInfo::GetReactState` reports.
+/// vmangos `ReactStates` (`UnitDefines.h:734-739`): a [`PET_ACT_REACTION`] slot's action.
 pub const PET_REACT_PASSIVE: u32 = 0;
 pub const PET_REACT_DEFENSIVE: u32 = 1;
 pub const PET_REACT_AGGRESSIVE: u32 = 2;
 
-/// The bit that marks the pet's bar **disabled**, in [`PetSpells::state`]'s own dword.
-///
-/// Two independent readings meet on this one bit, which is why it is worth stating: vmangos writes
-/// `pet->IsEnabled() ? 0x0 : 0x8` as the state field's **fourth byte** (`Player.cpp:17536`), and
-/// the client reads **bit 27** of the whole dword (wow-re §1/§4, `0x4bd08d`). `0x8 << 24` is bit
-/// 27 — the same bit, reached from both ends.
-///
-/// It does two things, both verified in the client: it forces the reaction compare's left side to
-/// Passive (§2.2) and it fails the usability predicate (§4). A disabled bar still draws.
+/// Bit 27 of [`PetSpells::state`], vmangos's fourth byte `0x8` (`Player.cpp:17536`): the bar is
+/// disabled, its lit reaction reads Passive and it is unusable, but it still draws (`0x4bd08d`).
 pub const PET_STATE_BAR_DISABLED: u32 = 0x0800_0000;
 
-/// The pet's `UNIT_FIELD_FLAGS` bits that make its bar unusable — vmangos
-/// `UNIT_FLAG_STUNNED 0x00040000` / `UNIT_FLAG_CONFUSED 0x00400000` / `UNIT_FLAG_FLEEING
-/// 0x00800000` (`UnitDefines.h:509-514`), which are exactly bits 18/22/23, the three the client's
-/// usability predicate tests (wow-re §4 step 6, `0x4bd075`-`0x4bd08b`).
-///
-/// i.e. **a stunned, confused or feared pet cannot be ordered** — and note `UNIT_FLAG_POSSESSED`
-/// (bit 24) is deliberately NOT among them: a possessed unit is exactly the case where the bar
-/// must still work.
+/// The pet's `UNIT_FIELD_FLAGS` bits that make its bar unusable: stunned, confused, fleeing
+/// (`0x4bd075`). `UNIT_FLAG_POSSESSED` is not among them: a possessed unit's bar must work.
 pub const PET_UNUSABLE_UNIT_FLAGS: u32 = 0x0004_0000 | 0x0040_0000 | 0x0080_0000;
 
-/// The permanent-cooldown marker OR-ed into a pet cooldown's **category** duration (vmangos
-/// `Unit::WritePetSpellsCooldown`, `Objects/Unit.cpp:11270-11271`) — the twin of the player
-/// initial-spell list's top-bit convention. Strip it before using the number as a duration.
+/// Permanent-cooldown marker OR-ed into a pet cooldown's category duration (vmangos
+/// `Unit.cpp:11270-11271`); strip it before using the number as a duration.
 pub const PET_COOLDOWN_PERMANENT: u32 = 0x0800_0000;
 
-/// One packed pet action word, decoded **the way the client decodes it** (wow-re §1, verified at
-/// `0x4bdcc7`/`0x4bdccd`/`0x4bdce3`):
-///
-/// ```text
-/// kind   = (packed >> 24) & 0x3F     the 0x3F mask is load-bearing — see below
-/// action = packed & 0xFFFF           SIXTEEN bits, not 24
-/// bit 31 = autocast allowed          bits 16..23 are never read by anything
-/// bit 30 = autocast on
-/// ```
-///
-/// The mask is the whole reason the server's five `ActiveStates` become the client's three
-/// branches: `0x01`, `0x81` and `0xC1` all mask to type **1**, and what separated them —
-/// castability and autocast — is read from bits 31/30 instead. Decoding `>> 24` unmasked (which
-/// benilla did until this was pinned) happens to work for the exact bytes vmangos sends and
-/// silently mis-sorts anything else.
-///
-/// What `action` *means* is `kind`'s to say: a spell id on the spell branch, a `CommandStates`
-/// for [`PET_ACT_COMMAND`], a `ReactStates` for [`PET_ACT_REACTION`]. The raw word is kept
-/// because the client echoes it **verbatim** in a [`pet_action`] body — re-packing from the split
-/// pair would be a second chance to get it wrong.
+/// One packed pet action word, as the client decodes it (`0x4bdcc7`/`0x4bdccd`/`0x4bdce3`): the
+/// action in bits 0-15, the type in 24-29, autocast allowed in 31 and on in 30; bits 16-23 are
+/// never read. The raw word is kept because the client echoes it verbatim in [`pet_action`].
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct PetActionEntry {
-    /// The whole word, exactly as it arrived (what [`pet_action`] echoes).
     pub packed: u32,
 }
 
 impl PetActionEntry {
-    /// Bits 0–15: the spell id, command state or react state.
+    /// Bits 0-15: the spell id, command state or react state.
     pub fn action(self) -> u32 {
         self.packed & 0xFFFF
     }
-    /// The client's slot type — bits 24–29 (see the type doc for why the mask matters).
+    /// The client's slot type, bits 24-29.
     pub fn kind(self) -> u8 {
         ((self.packed >> 24) & 0x3F) as u8
     }
-    /// Does this slot take the **spell** branch (client types 1–5), rather than the reaction or
-    /// command branch? A type outside 1–7 is neither: it falls into the client's own default arm,
-    /// which we treat as an empty slot rather than reproducing (wow-re §2.5 quirk 1).
+    /// Client types 1-5 take the spell branch. Deviation: a type outside 1-7 reads as nothing
+    /// rather than the reference's default arm, which under-pushes its returns.
     pub fn is_spell(self) -> bool {
         (PET_TYPE_SPELL_FIRST..=PET_TYPE_SPELL_LAST).contains(&self.kind())
     }
-    /// Is the slot EMPTY? **The whole word is zero** — the client tests the dword, not a field
-    /// (`0x4bdcbd test ecx,ecx`).
-    ///
-    /// vmangos's own unused middle slots are `(0, ACT_DISABLED)` = `0x8100_0000`, which is *not*
-    /// zero and so takes the spell branch — where spell id 0 has no `Spell.dbc` record, so every
-    /// return including the autocast pair comes back nil anyway (§2.1's no-record sub-path). Two
-    /// routes, one empty-looking button; this is the client's route.
+    /// Empty is a zero word (`0x4bdcbd`). vmangos's unused slots, `0x8100_0000`, take the spell
+    /// branch instead and come back nil, since spell 0 has no `Spell.dbc` record.
     pub fn is_empty(self) -> bool {
         self.packed == 0
     }
-    /// Bit 31 — this slot may autocast. (The client also requires the spell to resolve in
-    /// `Spell.dbc`; that half belongs to whoever holds the catalog.)
+    /// Bit 31; the client also requires a `Spell.dbc` record, which the catalog holder checks.
     pub fn autocast_allowed(self) -> bool {
         self.packed & PET_AUTOCAST_ALLOWED != 0
     }
-    /// Bit 30 — autocast is currently running.
+    /// Bit 30: autocast is running.
     pub fn autocast_on(self) -> bool {
         self.packed & PET_AUTOCAST_ON != 0
     }
-    /// The word with bit 30 set or cleared — exactly `TogglePetAutocast`'s own in-place flip
-    /// (wow-re §10.2, `0x4bcbff`: `if (bit30 clear) v |= 0x40000000 else v &= 0xBFFFFFFF`), which
-    /// the client writes back to the slot **before** sending and which is then what goes on the
-    /// wire.
+    /// Bit 30 set or cleared: `TogglePetAutocast`'s in-place flip (`0x4bcbff`), before the send.
     pub fn with_autocast(self, on: bool) -> Self {
         Self {
             packed: if on {
@@ -186,9 +108,7 @@ impl From<u32> for PetActionEntry {
     }
 }
 
-/// One entry of `SMSG_PET_SPELLS`' trailing cooldown block, decoded. The wire widths are
-/// [`read_cooldown_block`]'s problem — the two senders disagree about them — so this is the
-/// decoded shape only.
+/// One decoded entry of `SMSG_PET_SPELLS`' trailing cooldown block.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct PetSpellCooldown {
     pub spell_id: u32,
@@ -198,80 +118,46 @@ pub struct PetSpellCooldown {
     pub category_cd_ms: u32,
 }
 
-/// `SMSG_PET_SPELLS` in full — the pet action bar's entire state, in one body.
+/// `SMSG_PET_SPELLS`: the pet action bar's entire state in one body.
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct PetSpells {
-    /// The controlled unit (pet, possessed minion or charmed creature). **Zero means the bar is
-    /// gone**: `Player::RemovePetActionBar` sends an 8-byte body holding a zero guid and nothing
-    /// else, and [`read_pet_spells`] answers that with an otherwise-default value.
+    /// The pet, possessed minion or charmed creature; zero means the bar is gone.
     pub pet_guid: u64,
-    /// The charm's remaining duration in ms (`0` for a real pet — only the possess/charm builders
-    /// fill it, from the `SPELL_AURA_MOD_POSSESS`/`MOD_CHARM` aura).
+    /// The possess or charm aura's remaining ms; 0 for a real pet.
     pub duration_ms: u32,
-    /// The pet's mode word, **stored verbatim** — react state in byte 0, command state in byte 1,
-    /// [`PET_STATE_BAR_DISABLED`] at bit 27.
-    ///
-    /// One dword rather than four bytes because that is what the client keeps (`[0xb71468]`, wow-re
-    /// §1) and because two of its readings depend on the *whole* word rather than a field: the
-    /// reaction compare zeroes itself on bit 27, and the command compare is an **unmasked**
-    /// `state >> 8`, so a set bit 27 puts it out of range of any action and no command can light
-    /// (§2.3). Splitting it into bytes loses both behaviours silently.
+    /// The mode word, one dword as the client keeps it (`[0xb71468]`): react state in byte 0,
+    /// command state in byte 1, [`PET_STATE_BAR_DISABLED`] at bit 27. Do not split it into bytes.
     pub state: u32,
     /// The ten bar slots, in bar order.
     pub bar: [PetActionEntry; PET_ACTION_SLOTS],
-    /// The pet's whole known-spell list — the pet spellbook, packed the same way (spell id +
-    /// its current autocast type). Empty for a temporary pet or a charm; only a permanent pet
-    /// gets one (`Pet::IsPermanentPetFor` gates the loop, `Player.cpp:17549`).
+    /// The pet spellbook, packed like the bar; only a permanent pet has one (`Player.cpp:17549`).
     pub spells: Vec<PetActionEntry>,
-    /// The pet's running cooldowns.
     pub cooldowns: Vec<PetSpellCooldown>,
 }
 
 impl PetSpells {
-    /// Byte 0 of [`Self::state`] — a [`PET_REACT_PASSIVE`]-family value.
+    /// Byte 0 of [`Self::state`], a [`PET_REACT_PASSIVE`]-family value.
     pub fn react_state(&self) -> u32 {
         self.state & 0xFF
     }
-    /// `state >> 8` — a [`PET_COMMAND_STAY`]-family value, **unmasked on purpose**.
-    ///
-    /// The client's own command compare is `(state >> 8) == action` with no `& 0xFF`
-    /// (`0x4bdf0f`), so when bit 27 is set this is a number no command state can equal and every
-    /// command button goes dark. Masking here would be "tidier" and would quietly delete that.
+    /// `state >> 8`, unmasked like the client's compare (`0x4bdf0f`): with bit 27 set it matches
+    /// no command state, so every command button goes dark. Masking it would lose that.
     pub fn command_state(&self) -> u32 {
         self.state >> 8
     }
-    /// Bit 27 — the server says the bar is disabled.
+    /// Bit 27: the server has disabled the bar.
     pub fn bar_disabled(&self) -> bool {
         self.state & PET_STATE_BAR_DISABLED != 0
     }
 }
 
-/// Read `SMSG_PET_SPELLS` (VERIFIED vmangos `Player::PetSpellInitialize`,
-/// `Objects/Player.cpp:17519-17561`, with `CharmInfo::BuildActionBar` `Unit.cpp:8782-8786` and
-/// `Unit::WritePetSpellsCooldown` `Unit.cpp:11245-11280`):
-///
-/// ```text
-/// u64 petGuid
-/// u32 duration          (0 for a pet; the charm/possess remainder otherwise)
-/// u32 state             react | command<<8 | 0<<16 | enabledFlag<<24  — kept VERBATIM
-/// u32 × 10              the bar, packed
-/// u8  spellCount        then that many u32, packed the same way
-/// <the cooldown block>  see read_cooldown_block — the one field the client and vmangos disagree on
-/// ```
-///
-/// vmangos writes the state as four separate bytes and the client reads one dword
-/// (`0x4bd9d3 GetInt32` → `[0xb71468]`); those are the same four bytes, and holding the dword is
-/// what lets bit 27 and the unmasked `>> 8` behave (see [`PetSpells::state`]).
-///
-/// The **8-byte teardown** form (`Player::RemovePetActionBar`, `Player.cpp:17672-17677`) is a lone
-/// zero guid: this returns [`PetSpells::default`] for it, so a caller's only test is
-/// `pet_guid == 0`. Anything short of a full body after a non-zero guid is a real parse error and
-/// surfaces as one — a truncated bar is not a bar.
+/// Read `SMSG_PET_SPELLS` (vmangos `Player::PetSpellInitialize`, `Player.cpp:17519-17561`):
+/// `u64 petGuid, u32 duration, u32 state, u32 bar[10], u8 count, u32 spells[count]`, then the
+/// cooldown block. A lone guid is the teardown; any longer body cut short is an error.
 pub(super) fn read_pet_spells(r: &mut &[u8]) -> io::Result<PetSpells> {
     let pet_guid = read_u64_le(r)?;
     if r.is_empty() {
-        // The teardown. vmangos always writes a zero guid here; carrying whatever arrived keeps
-        // the reader honest, and the `pet_guid == 0` test is the caller's contract either way.
+        // The teardown; vmangos always writes a zero guid here.
         return Ok(PetSpells {
             pet_guid,
             ..Default::default()
@@ -286,7 +172,7 @@ pub(super) fn read_pet_spells(r: &mut &[u8]) -> io::Result<PetSpells> {
     }
 
     let spell_count = read_u8(r)?;
-    // A `u8` count with no tighter server bound (`Player.cpp:17471`, `uint8 addlist`).
+    // A `u8` count with no tighter server bound (`Player.cpp:17471`).
     let mut spells = Vec::with_capacity(capacity_hint(spell_count, usize::from(u8::MAX)));
     for _ in 0..spell_count {
         spells.push(read_u32_le(r)?.into());
@@ -304,28 +190,14 @@ pub(super) fn read_pet_spells(r: &mut &[u8]) -> io::Result<PetSpells> {
     })
 }
 
-/// The trailing cooldown block — **the one place the real client and vmangos disagree about this
-/// packet**, so it is read by measuring rather than by choosing a side.
-///
-/// - The **client** reads `u8 count` then 12-byte entries `{u16 spellId, u16 category, u32, u32}`
-///   (wow-re §8, getter widths verified at `0x4bda58`/`0x4bda6c`/`0x4bda82`; the arbitration is
-///   §12.6).
-/// - **vmangos** writes `u16 count` then 14-byte entries `{u32 spellId, u16 category, u32, u32}`
-///   (`Unit::WritePetSpellsCooldown`, `Objects/Unit.cpp:11225-11258`) — the later-expansion
-///   layout. A real 1.12 client talking to vmangos mis-parses this block; we are not going to
-///   reproduce that bug just to match it.
-///
-/// The block is the packet's **tail**, so the remaining length settles it outright: `n` client
-/// entries leave `12n` bytes, `n` vmangos entries leave `1 + 14n` (the `+1` being the u16 count's
-/// high byte, which the `u8` read did not consume). `12n == 1 + 14m` has no solution in
-/// non-negative integers with `n == m`, and for `count == 0` both leave nothing to read. So the
-/// discriminator is exact, not a heuristic — and the day vmangos is fixed, this keeps working.
+/// The trailing cooldown block. The client reads `u8 count` then 12-byte entries
+/// `{u16 spell, u16 category, u32, u32}` (`0x4bda58`); vmangos writes `u16 count` then 14-byte
+/// entries with a `u32` spell (`Unit.cpp:11225-11258`). Deviation: both are read, told apart
+/// exactly by the tail length (`12n` vs `1 + 14n`), since the 1.12 client mis-parses vmangos's.
 fn read_cooldown_block(r: &mut &[u8]) -> io::Result<Vec<PetSpellCooldown>> {
     let count = usize::from(read_u8(r)?);
-    // The discriminator holds at `count == 0` too: vmangos's lone leftover is its `u16` count's
-    // high byte, the client's form leaves nothing. The byte is consumed rather than left behind
-    // so an empty block is not a tail for the decode-length check to announce (decision 2265
-    // §B1); either way nothing else is read and no entry is invented.
+    // At `count == 0` vmangos still leaves its `u16` count's high byte; it is consumed so the
+    // decode-length check sees no tail.
     let vmangos = r.len() == 1 + 14 * count;
     if vmangos {
         let _high_byte = read_u8(r)?;
@@ -333,7 +205,7 @@ fn read_cooldown_block(r: &mut &[u8]) -> io::Result<Vec<PetSpellCooldown>> {
     if count == 0 {
         return Ok(Vec::new());
     }
-    // `count` came off a `u8` (above); no tighter bound exists on either producer.
+    // `count` came off a `u8`; no tighter bound exists on either producer.
     let mut cooldowns = Vec::with_capacity(capacity_hint(count, usize::from(u8::MAX)));
     for _ in 0..count {
         let spell_id = if vmangos {
@@ -351,20 +223,15 @@ fn read_cooldown_block(r: &mut &[u8]) -> io::Result<Vec<PetSpellCooldown>> {
     Ok(cooldowns)
 }
 
-/// `SMSG_PET_MODE` — the state-only refresh: the same four bytes `SMSG_PET_SPELLS` carries, with
-/// no bar behind them. The server sends it when a command or reaction changes without the bar's
-/// contents moving.
+/// `SMSG_PET_MODE`: the state word without the bar, for a command or reaction change.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct PetMode {
     pub pet_guid: u64,
-    /// The same verbatim dword [`PetSpells::state`] holds — the client stores it through the very
-    /// same writer (`0x4bc930`) from both packets.
+    /// The same dword as [`PetSpells::state`]; the client stores both through `0x4bc930`.
     pub state: u32,
 }
 
-/// Read `SMSG_PET_MODE` — `u64 petGuid, u32 state` (client handler `0x4bdb10`, wow-re §8;
-/// vmangos's four state bytes at `WorldPackets::Pet::PetMode::AppendBodyTo`,
-/// `Server/Packets/Pet.cpp:101-108`, are that dword).
+/// Read `SMSG_PET_MODE`: `u64 petGuid, u32 state` (`0x4bdb10`; vmangos `Packets/Pet.cpp:101-108`).
 pub(super) fn read_pet_mode(r: &mut impl Read) -> io::Result<PetMode> {
     Ok(PetMode {
         pet_guid: read_u64_le(r)?,
@@ -372,32 +239,18 @@ pub(super) fn read_pet_mode(r: &mut impl Read) -> io::Result<PetMode> {
     })
 }
 
-/// Read `SMSG_PET_ACTION_FEEDBACK` (VERIFIED vmangos `PetActionFeedback::AppendBodyTo`,
-/// `Server/Packets/Pet.cpp:87-90`): one reason byte. The client turns it into the red error line
-/// ("Your pet has no path to that location", …).
+/// Read `SMSG_PET_ACTION_FEEDBACK` (vmangos `Packets/Pet.cpp:87-90`): one reason byte.
 pub(super) fn read_pet_action_feedback(r: &mut impl Read) -> io::Result<u8> {
     read_u8(r)
 }
 
-/// Read `SMSG_PET_TAME_FAILURE` (VERIFIED vmangos `PetTameFailure::AppendBodyTo`,
-/// `Server/Packets/Pet.cpp:122-125`): one reason byte. [`pet_tame_failure_key`] is what the
-/// reference does with it.
+/// Read `SMSG_PET_TAME_FAILURE` (vmangos `Packets/Pet.cpp:122-125`): one reason byte.
 pub(super) fn read_pet_tame_failure(r: &mut impl Read) -> io::Result<u8> {
     read_u8(r)
 }
 
-/// The `SMSG_PET_TAME_FAILURE` reason -> the `GlobalStrings.lua` key whose text fills
-/// `ERR_TAME_FAILED`'s lone `%s` — the reference's jump table at `0x6e6ac0`, read out of the
-/// image dword for dword.
-///
-/// `0x6e6a20` computes `reason - 1` and bounds it at `0xa`, so **`1..=11` index the table and
-/// everything else takes the default arm** `0x6e6a87` -> `PETTAME_UNKNOWNERROR`. That default is
-/// reachable in play: vmangos's own enum has a twelfth value (`PETTAME_UNKNOWNERROR = 12`) which
-/// falls out of range and lands on it, arriving at the same string by the other road.
-///
-/// The eleven pairs are byte-identical to vmangos's `PetTameFailureReason`
-/// (`src/game/SharedDefines.h:1707`) — the two ends agree without either having been fitted to
-/// the other.
+/// The `GlobalStrings.lua` key filling `ERR_TAME_FAILED`'s `%s`: the reference's table
+/// (`0x6e6ac0`) covers `1..=11`, and anything else, vmangos's 12 included, is the default arm.
 pub fn pet_tame_failure_key(reason: u8) -> &'static str {
     match reason {
         1 => "PETTAME_INVALIDCREATURE",
@@ -415,44 +268,26 @@ pub fn pet_tame_failure_key(reason: u8) -> &'static str {
     }
 }
 
-/// `SMSG_PET_ACTION_SOUND`'s selector: the pet acknowledging an **order** (vmangos
-/// `PET_TALK_SPECIAL_SPELL`, sent when a pet bar spell press is accepted —
-/// `PetHandler.cpp:523`, `PetAI.cpp:336`).
+/// Sound selector for an accepted order (vmangos `PET_TALK_SPECIAL_SPELL`, `PetHandler.cpp:523`).
 pub const PET_TALK_ORDER: u32 = 0;
-/// `SMSG_PET_ACTION_SOUND`'s selector: the pet **attacking** (vmangos `PET_TALK_ATTACK`, sent
-/// from `Unit.cpp:8941` when an attack order is taken).
+/// Sound selector for an attack order (vmangos `PET_TALK_ATTACK`, `Unit.cpp:8941`).
 pub const PET_TALK_ATTACK: u32 = 1;
 
-/// Read `SMSG_PET_ACTION_SOUND` (VERIFIED vmangos `PetActionSound::AppendBodyTo`,
-/// `Server/Packets/Pet.cpp:96-100`, and the reference's own reader at `0x6040ca`/`0x6040db`):
-/// `u64 petGuid` then the `u32` talk selector.
-///
-/// The selector is NOT a `SoundEntries` id — it is [`PET_TALK_ORDER`] / [`PET_TALK_ATTACK`], and
-/// the sound comes off the pet's own `CreatureSoundData` row. Worth saying because the opcode's
-/// name invites the other reading, and a two-value selector and a kit id are indistinguishable
-/// on the wire.
+/// Read `SMSG_PET_ACTION_SOUND`: `u64 petGuid, u32 selector` (`0x6040ca`, vmangos
+/// `Packets/Pet.cpp:96-100`). The selector is a `PET_TALK_*` value, not a `SoundEntries` id: the
+/// sound comes off the pet's `CreatureSoundData` row.
 pub(super) fn read_pet_action_sound(r: &mut impl Read) -> io::Result<(u64, u32)> {
     Ok((read_u64_le(r)?, read_u32_le(r)?))
 }
 
-/// Read `SMSG_PET_DISMISS_SOUND` — `u32 creatureModelDataId` then `f32` x/y/z.
-///
-/// VERIFIED off **the reference's own reader**, which is the only authority there is: `0x604140`
-/// takes one `0x418e30` (u32) then three `0x419130` (f32) in that order, and vmangos has no
-/// sender to cross-check against. The `+1.0` the handler adds to `z` afterwards is a *play*
-/// detail, not a wire one, so it is not applied here.
+/// Read `SMSG_PET_DISMISS_SOUND`: `u32 creatureModelDataId, f32 x, y, z` (reader `0x604140`;
+/// vmangos never sends it). The handler's `+1.0` on `z` is a play detail, not applied here.
 pub(super) fn read_pet_dismiss_sound(r: &mut impl Read) -> io::Result<(u32, Vector3d)> {
     Ok((read_u32_le(r)?, Vector3d::read(r)?))
 }
 
-/// Read `SMSG_PET_CAST_FAILED` (VERIFIED vmangos `PetCastFailed::AppendBodyTo`,
-/// `Server/Packets/Pet.cpp:127-132`): `u32 spellId, u8 status, u8 reason`. The pet's twin of
-/// `SMSG_CAST_RESULT` — the same `SpellCastResult` vocabulary, decoded the same way (status `2` =
-/// fail) so the one message table renders both. vmangos only ever sends the fail status here, but
-/// reading it the shared way costs nothing and keeps the two decodes from drifting.
-///
-/// The body stops at the reason: unlike `CastResult`, `PetCastFailed::AppendBodyTo` writes **no
-/// argument words** at all, so a pet failure never carries a `%s` fill.
+/// Read `SMSG_PET_CAST_FAILED` (vmangos `Packets/Pet.cpp:127-132`): `u32` spell, `u8` status,
+/// `u8` reason, in `SMSG_CAST_RESULT`'s vocabulary (2 is a failure) but with no argument words.
 pub(super) fn read_pet_cast_failed(r: &mut impl Read) -> io::Result<(u32, super::CastOutcome)> {
     let spell_id = read_u32_le(r)?;
     let status = read_u8(r)?;
@@ -467,14 +302,8 @@ pub(super) fn read_pet_cast_failed(r: &mut impl Read) -> io::Result<(u32, super:
     Ok((spell_id, outcome))
 }
 
-/// Body of `CMSG_PET_ACTION` (VERIFIED vmangos `WorldPackets::Pet::PetAction::ReadFromWorldPacket`,
-/// `Server/Packets/Pet.cpp:9-14`; opcode 373 `Opcodes_1_12_1.h:374`): `u64 petGuid, u32 packedData,
-/// u64 targetGuid`.
-///
-/// **`packed` is the slot's own word, echoed** — the server re-splits it exactly as the client
-/// packed it (`UNIT_ACTION_BUTTON_ACTION/TYPE` at `PetHandler.cpp:37-38`) and dispatches on the
-/// type: `ACT_COMMAND` runs `HandlePetCommand`, `ACT_REACTION` sets the react state, and the three
-/// spell types cast. `target` is `0` when the action needs none.
+/// Body of `CMSG_PET_ACTION` (opcode 373, vmangos `Packets/Pet.cpp:9-14`): `u64` pet guid, the
+/// slot's `u32` word echoed verbatim, `u64` target guid (0 when the action needs none).
 pub fn pet_action(pet_guid: u64, packed: u32, target_guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(20);
     body.extend_from_slice(&pet_guid.to_le_bytes());
@@ -483,26 +312,15 @@ pub fn pet_action(pet_guid: u64, packed: u32, target_guid: u64) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_PET_STOP_ATTACK` (VERIFIED vmangos `PetStopAttack::ReadFromWorldPacket`,
-/// `Server/Packets/Pet.cpp:33-36`; opcode 746 `Opcodes_1_12_1.h:747`): the lone `u64` pet guid.
-/// The Attack button's *second* press — `PetActionBarFrame.lua:258-262` calls `PetStopAttack()`
-/// instead of `CastPetAction` when the attack is already running.
+/// Body of `CMSG_PET_STOP_ATTACK` (opcode 746, vmangos `Packets/Pet.cpp:33-36`): the pet guid,
+/// sent by the Attack button's second press (`PetActionBarFrame.lua:258-262`).
 pub fn pet_stop_attack(pet_guid: u64) -> Vec<u8> {
     pet_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_PET_CANCEL_AURA` (opcode 619): `u64 petGuid` then `u32 spellId`.
-///
-/// Both ends agree independently. wow-re read the send off the client
-/// (`ui/scratch/pet-action-bar-api.md` §10.1, `0x4bd25f`–`0x4bd2ad`: `push 0x26b`, the guid pair,
-/// the id); vmangos reads the same two fields in the same order
-/// (`PetCancelAura::ReadFromWorldPacket`, `Server/Packets/Pet.cpp:27-31`).
-///
-/// The guid is what distinguishes it from the player's `CMSG_CANCEL_AURA` — which carries a bare
-/// spell id and so could only ever mean "mine". The handler re-checks that the guid is our pet or
-/// our charm and drops the packet otherwise, and answers a **dead** pet with
-/// `SendPetActionFeedback(FEEDBACK_PET_DEAD)` rather than silence (`HandlePetCancelAuraOpcode`,
-/// `Handlers/SpellHandler.cpp:407-432`) — the same feedback channel the bar's other refusals use.
+/// Body of `CMSG_PET_CANCEL_AURA` (opcode 619, sender `0x4bd25f`): `u64` pet guid, `u32` spell.
+/// The server drops it unless the guid is our pet or charm and answers a dead pet with
+/// `FEEDBACK_PET_DEAD` (vmangos `SpellHandler.cpp:407-432`).
 pub fn pet_cancel_aura(pet_guid: u64, spell_id: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&pet_guid.to_le_bytes());
@@ -510,20 +328,8 @@ pub fn pet_cancel_aura(pet_guid: u64, spell_id: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_PET_SPELL_AUTOCAST` (opcode 755): `u64 petGuid`, `u32 spellId`, `u8 state` —
-/// **thirteen** bytes, and the trailing field is a byte (decision 1032).
-///
-/// Both ends agree independently. The client builds it at `0x4bcd5f`–`0x4bcdb2`: `push 0x2f3`, the
-/// guid pair through the u64 writer `0x418370`, the spell id through the u32 writer `0x418190`,
-/// then `(word >> 30) & 0xFFFFFF01` through **`0x418070`**, the *byte* writer — which is also why
-/// that mask ends in `01`. vmangos reads `guid, spellId, state` in that order with `state` a
-/// `uint8` (`PetSpellAutocast::ReadFromWorldPacket`, `Server/Packets/Pet.cpp:44-49`).
-///
-/// **This is the pet SPELLBOOK's autocast verb, not the pet bar's.** The bar's right click sends
-/// [`pet_set_action`], whose body names a slot *position*; the book has no positions, so this one
-/// names the spell. The server's handler is correspondingly different — it re-derives which slots
-/// to update itself (`HandlePetSpellAutocastOpcode`, `PetHandler.cpp:451-478`), gating on
-/// `pet->HasSpell(spellId) && Spells::IsAutocastable(spellId)`. No reply packet.
+/// Body of `CMSG_PET_SPELL_AUTOCAST` (opcode 755, sender `0x4bcd5f`): `u64` guid, `u32` spell,
+/// `u8` state. The pet spellbook's autocast verb, with no reply; the bar's is [`pet_set_action`].
 pub fn pet_spell_autocast(pet_guid: u64, spell_id: u32, enabled: bool) -> Vec<u8> {
     let mut body = Vec::with_capacity(13);
     body.extend_from_slice(&pet_guid.to_le_bytes());
@@ -532,22 +338,11 @@ pub fn pet_spell_autocast(pet_guid: u64, spell_id: u32, enabled: bool) -> Vec<u8
     body
 }
 
-/// Body of `CMSG_PET_SET_ACTION` (opcode 372): `u64 petGuid` then one or two
-/// `(u32 position, u32 packedData)` pairs. The server distinguishes the forms **by body size
-/// alone** — 24 bytes ⇒ two entries, anything else ⇒ one (`PetSetAction::ReadFromWorldPacket`,
-/// `Server/Packets/Pet.cpp:52-62`) — so a one-entry body must not be padded.
-///
-/// This one opcode carries **both** of the bar's write verbs, which is the thing to know about it:
-///
-/// - **the autocast toggle** — one pair, the pressed slot and its word with bit 30 flipped. That
-///   is `TogglePetAutocast`'s whole send (wow-re §10.2, `0x4bcc1e push 0x174`), and the server
-///   reads the flip straight out of the type byte: `ACT_ENABLED` ⇒ `ToggleAutocast(true)`,
-///   `ACT_DISABLED` ⇒ `false` (`HandlePetSetAction`, `PetHandler.cpp`). `CMSG_PET_SPELL_AUTOCAST`
-///   (0x2F3) is **not** this verb — it belongs to `ToggleSpellAutocast`, the pet *spellbook*
-///   frame's binding, and indexes the spellbook rather than the bar (wow-re §10.2/§11).
-/// - **the drag** — one or two pairs, from `0x4bc9a0` (wow-re §10.4): the optional first pair
-///   relocates whatever occupied the target slot, the mandatory second writes the drop. vmangos
-///   requires the two-pair form whenever a command/reaction token moves.
+/// Body of `CMSG_PET_SET_ACTION` (opcode 372): `u64` pet guid, then one or two
+/// `(u32 position, u32 packed)` pairs, counted by body size alone (24 bytes is two, vmangos
+/// `Packets/Pet.cpp:52-62`), so one pair must not be padded. It carries the bar's autocast toggle
+/// (one pair, bit 30 flipped, `0x4bcc1e`) and its drag (`0x4bc9a0`), whose optional first pair
+/// relocates the target slot's occupant; vmangos requires it when a command or reaction moves.
 pub fn pet_set_action(pet_guid: u64, entries: &[(u32, u32)]) -> Vec<u8> {
     let mut body = Vec::with_capacity(8 + 8 * entries.len());
     body.extend_from_slice(&pet_guid.to_le_bytes());
@@ -558,24 +353,15 @@ pub fn pet_set_action(pet_guid: u64, entries: &[(u32, u32)]) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_PET_ABANDON` (VERIFIED vmangos `PetAbandon::ReadFromWorldPacket`,
-/// `Server/Packets/Pet.cpp:16-19`; opcode 374): the lone `u64` pet guid.
-///
-/// **The menu's Abandon and its Dismiss are this same message** — see [`super::opcode`]'s note.
-/// Nothing in the body says which the player picked, and nothing needs to: the server forks on the
-/// pet's own type, deleting a hunter pet and unsummoning anything else. The client's fork is purely
-/// about which *word* the menu shows.
+/// Body of `CMSG_PET_ABANDON` (opcode 374, vmangos `Packets/Pet.cpp:16-19`): the pet guid. The
+/// menu's Abandon and Dismiss both send it; the server deletes a hunter pet and unsummons others.
 pub fn pet_abandon(pet_guid: u64) -> Vec<u8> {
     pet_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_PET_RENAME` (VERIFIED vmangos `PetRename::ReadFromWorldPacket`,
-/// `Server/Packets/Pet.cpp:21-25`; opcode 375): `u64 petGuid` then the name as a **C string**.
-///
-/// The name is not length-prefixed and not padded — vmangos's `>> std::string` reads to the first
-/// NUL. The 12-character cap is the popup's (`RENAME_PET`'s `maxLetters = 12`), not the wire's; the
-/// server re-checks with `ObjectMgr::CheckPetName` and refuses with `SMSG_PET_NAME_INVALID`
-/// rather than truncating.
+/// Body of `CMSG_PET_RENAME` (opcode 375, vmangos `Packets/Pet.cpp:21-25`): the pet guid, then
+/// the name NUL-terminated. The 12-letter cap is the popup's; the server refuses a bad name with
+/// `SMSG_PET_NAME_INVALID` rather than truncating.
 pub fn pet_rename(pet_guid: u64, name: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(9 + name.len());
     body.extend_from_slice(&pet_guid.to_le_bytes());
@@ -588,8 +374,7 @@ pub fn pet_rename(pet_guid: u64, name: &str) -> Vec<u8> {
 mod tests {
     use super::*;
 
-    /// A hunter pet's `SMSG_PET_SPELLS`, byte-for-byte as vmangos builds it: the default
-    /// 3 commands / 4 spell slots / 3 reactions bar, one known spell, one running cooldown.
+    /// A hunter pet's `SMSG_PET_SPELLS` as vmangos builds it, with one spell and one cooldown.
     fn pet_spells_body() -> Vec<u8> {
         let mut b = Vec::new();
         b.extend_from_slice(&0xF140_0000_0000_002Au64.to_le_bytes()); // pet guid
@@ -598,8 +383,7 @@ mod tests {
         b.push(PET_COMMAND_FOLLOW as u8);
         b.push(0);
         b.push(0); // enabled
-                   // The bar, exactly CharmInfo::InitPetActionBar's default: attack/follow/stay,
-                   // four spell slots (one filled with Claw 3010, autocast on), aggressive/def/passive.
+                   // The bar is CharmInfo::InitPetActionBar's default, Claw 3010 autocasting.
         for packed in [
             PET_COMMAND_ATTACK | (u32::from(PET_ACT_COMMAND) << 24),
             PET_COMMAND_FOLLOW | (u32::from(PET_ACT_COMMAND) << 24),
@@ -616,7 +400,7 @@ mod tests {
         }
         b.push(1); // spell count
         b.extend_from_slice(&(3010u32 | (u32::from(PET_ACT_ENABLED) << 24)).to_le_bytes());
-        // The cooldown block in VMANGOS's layout: u16 count, u32 spell id (14-byte entries).
+        // The cooldown block in vmangos's layout: u16 count, u32 spell id (14-byte entries).
         b.extend_from_slice(&1u16.to_le_bytes());
         b.extend_from_slice(&3010u32.to_le_bytes());
         b.extend_from_slice(&0u16.to_le_bytes()); // category
@@ -625,8 +409,7 @@ mod tests {
         b
     }
 
-    /// The same packet with the cooldown block in the **client's** layout: u8 count, u16 spell id
-    /// (12-byte entries). Both must decode identically — see [`read_cooldown_block`].
+    /// The same packet with the cooldown block in the client's layout: u8 count, 12-byte entries.
     fn pet_spells_body_client_cooldowns() -> Vec<u8> {
         let mut b = pet_spells_body();
         b.truncate(b.len() - 16); // drop vmangos's u16 count + its one 14-byte entry
@@ -651,22 +434,19 @@ mod tests {
         assert_eq!(p.command_state(), PET_COMMAND_FOLLOW);
         assert!(!p.bar_disabled());
 
-        // The three branches, read off the same word shape.
         assert_eq!(p.bar[0].kind(), PET_ACT_COMMAND);
         assert_eq!(p.bar[0].action(), PET_COMMAND_ATTACK);
         assert!(!p.bar[0].is_spell());
         assert_eq!(p.bar[9].kind(), PET_ACT_REACTION);
         assert_eq!(p.bar[9].action(), PET_REACT_PASSIVE);
 
-        // The mask at work: the server sent 0xC1, and the client's type is 1 — the autocast pair
-        // having moved out of the type byte into bits 31/30.
+        // The server sent 0xC1; the client's type is 1, with autocast in bits 31/30.
         assert_eq!(p.bar[3].kind(), PET_TYPE_SPELL_FIRST);
         assert_eq!(p.bar[3].action(), 3010);
         assert!(p.bar[3].is_spell() && !p.bar[3].is_empty());
         assert!(p.bar[3].autocast_allowed() && p.bar[3].autocast_on());
 
-        // vmangos's unused middle slot (0, ACT_DISABLED) is NOT the client's empty word — it takes
-        // the spell branch, where spell id 0 resolves to nothing. Same button, different route.
+        // vmangos's unused slot (0, ACT_DISABLED) is not empty; it takes the spell branch.
         assert!(!p.bar[4].is_empty());
         assert!(p.bar[4].is_spell() && p.bar[4].action() == 0);
         assert!(
@@ -687,8 +467,6 @@ mod tests {
         );
     }
 
-    /// The cooldown block's two layouts decode to the same thing — the client's 12-byte form and
-    /// vmangos's 14-byte one, told apart by the tail length alone.
     #[test]
     fn both_cooldown_layouts_decode_identically() {
         let from_vmangos = read_pet_spells(&mut &pet_spells_body()[..]).unwrap();
@@ -700,9 +478,7 @@ mod tests {
         assert_eq!(from_client, from_vmangos);
     }
 
-    /// A pet with no cooldowns at all: the client's form ends the packet, vmangos's leaves its
-    /// count's high byte behind. Neither is an error and neither invents an entry — and the
-    /// high byte is consumed, so neither leaves a tail.
+    /// No cooldowns: the client's form is one byte, vmangos's two, and both are fully consumed.
     #[test]
     fn an_empty_cooldown_block_reads_either_way() {
         let mut client = &[0u8][..];
@@ -716,8 +492,7 @@ mod tests {
         );
     }
 
-    /// The teardown: an 8-byte body of zero guid ⇒ a default value whose `pet_guid` is 0. This is
-    /// the ONLY signal that the bar has gone away, so it must not read as a parse error.
+    /// A zero-guid body is the only signal that the bar is gone, so it must not be an error.
     #[test]
     fn the_guid_only_body_is_the_teardown() {
         let body = 0u64.to_le_bytes();
@@ -727,8 +502,7 @@ mod tests {
         assert_eq!(p.pet_guid, 0);
     }
 
-    /// A truncated bar is a parse error, not a half-read bar — the failure mode that would
-    /// otherwise paint 4 real slots and 6 zeroes.
+    /// Cut after the first bar slot: an error, not a half-read bar.
     #[test]
     fn a_truncated_body_errors() {
         let body = pet_spells_body();
@@ -738,8 +512,7 @@ mod tests {
 
     #[test]
     fn pet_mode_and_the_client_verbs_golden() {
-        // SMSG_PET_MODE: guid + the same state dword, no bar behind it. vmangos's fourth byte 0x8
-        // IS the client's bit 27 — the two ends of the same bit.
+        // SMSG_PET_MODE: vmangos's fourth state byte 0x8 is the client's bit 27.
         let mut body = 0x2Au64.to_le_bytes().to_vec();
         body.extend_from_slice(&[2, 0, 0, 0x8]);
         let mut r = &body[..];
@@ -748,7 +521,6 @@ mod tests {
         assert_eq!(mode.state, 0x0800_0002);
         assert_eq!(mode.state & PET_STATE_BAR_DISABLED, PET_STATE_BAR_DISABLED);
 
-        // CMSG_PET_ACTION: guid, the slot word VERBATIM, target guid.
         let packed = 3010 | (u32::from(PET_ACT_ENABLED) << 24);
         assert_eq!(
             pet_action(0x2A, packed, 0x99),
@@ -760,11 +532,8 @@ mod tests {
             .concat()
         );
 
-        // CMSG_PET_STOP_ATTACK: the lone guid.
         assert_eq!(pet_stop_attack(0x2A), 0x2Au64.to_le_bytes());
 
-        // CMSG_PET_CANCEL_AURA: guid then spell id, 12 bytes — the guid is the whole difference
-        // from the player's own CMSG_CANCEL_AURA, which is a bare u32.
         assert_eq!(
             pet_cancel_aura(0x2A, 2645),
             [
@@ -775,17 +544,13 @@ mod tests {
         );
         assert_eq!(pet_cancel_aura(0x2A, 2645).len(), 12);
 
-        // CMSG_PET_SET_ACTION: the server tells one entry from two BY BODY SIZE, so the one-entry
-        // form is 16 bytes and the two-entry form is exactly 24.
+        // CMSG_PET_SET_ACTION: the server counts entries by body size, so 16 bytes or exactly 24.
         assert_eq!(pet_set_action(0x2A, &[(3, packed)]).len(), 16);
         assert_eq!(pet_set_action(0x2A, &[(3, packed), (4, 0)]).len(), 24);
 
-        // CMSG_PET_ABANDON: the lone guid — the same shape as stop-attack, a different verb.
         assert_eq!(pet_abandon(0x2A), 0x2Au64.to_le_bytes());
 
-        // CMSG_PET_RENAME: guid then a NUL-TERMINATED name. The terminator is the whole framing —
-        // there is no length prefix and no padding, so dropping it would leave the server reading
-        // the name off the end of the body.
+        // CMSG_PET_RENAME: guid then a NUL-terminated name, the terminator being its only framing.
         assert_eq!(
             pet_rename(0x2A, "Bruce"),
             [&0x2Au64.to_le_bytes()[..], b"Bruce\0"].concat()
@@ -797,8 +562,6 @@ mod tests {
         );
     }
 
-    /// The autocast flip touches **bit 30 and nothing else** — the client's own in-place edit, and
-    /// the word it produces is exactly what `CMSG_PET_SET_ACTION` then carries.
     #[test]
     fn the_autocast_flip_moves_only_bit_30() {
         let on = PetActionEntry::from(3010 | (u32::from(PET_ACT_ENABLED) << 24));
@@ -811,14 +574,11 @@ mod tests {
         assert!(off.autocast_allowed() && !off.autocast_on());
         assert_eq!(off.with_autocast(true), on);
 
-        // A passive spell can be asked to autocast and the word still says it may not — bit 31 is
-        // the server's to grant, and flipping 30 does not forge it.
+        // Bit 31 is the server's to grant; flipping bit 30 on a passive spell does not forge it.
         let passive = PetActionEntry::from(3010 | (u32::from(PET_ACT_PASSIVE) << 24));
         assert!(!passive.with_autocast(true).autocast_allowed());
     }
 
-    /// The `& 0x3F` mask, stated on its own: the server's five `ActiveStates` land on three client
-    /// branches, and the two dropped bits reappear as the autocast pair.
     #[test]
     fn the_type_mask_collapses_the_spell_states() {
         for act in [PET_ACT_PASSIVE, PET_ACT_DISABLED, PET_ACT_ENABLED] {
@@ -836,17 +596,15 @@ mod tests {
             PET_ACT_REACTION
         );
 
-        // A type outside 1-7 is the client's default arm; we treat it as nothing at all rather
-        // than reproduce its under-push (wow-re §2.5 quirk 1).
+        // A type outside 1-7 is neither a spell nor a token.
         let odd = PetActionEntry::from(3010 | (0x33u32 << 24));
         assert!(!odd.is_spell());
         assert!(odd.kind() != PET_ACT_COMMAND && odd.kind() != PET_ACT_REACTION);
     }
 }
 
-/// `SMSG_PET_UNLEARN_CONFIRM` (VERIFIED at the bytes, wow-re `staticpopup-dialog-bindings.md`
-/// §9, arm `0x5e4a26`): the pet trainer's guid and what unlearning costs, in copper — the
-/// reference latches both and fires `CONFIRM_PET_UNLEARN(cost)`. Decision 1963.
+/// `SMSG_PET_UNLEARN_CONFIRM` (`0x5e4a26`): the trainer's guid and the unlearn cost in copper,
+/// which the reference latches before firing `CONFIRM_PET_UNLEARN(cost)`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct PetUnlearnConfirm {
     pub trainer: u64,
@@ -863,7 +621,7 @@ pub(super) fn read_pet_unlearn_confirm(
     })
 }
 
-/// Body of `CMSG_PET_UNLEARN` (VERIFIED, §9 `0x5dfba0`'s confirm arm): the latched trainer guid.
+/// Body of `CMSG_PET_UNLEARN` (the confirm arm of `0x5dfba0`): the latched trainer guid.
 pub fn pet_unlearn(trainer: u64) -> Vec<u8> {
     trainer.to_le_bytes().to_vec()
 }
diff --git a/crates/benilla-protocol/src/messages/petition.rs b/crates/benilla-protocol/src/messages/petition.rs
index 595b94d7..c46f24ef 100644
--- a/crates/benilla-protocol/src/messages/petition.rs
+++ b/crates/benilla-protocol/src/messages/petition.rs
@@ -1,44 +1,8 @@
-//! The petition family — the guild-charter flow that *founds* a guild (opcodes `0x1BB`–`0x1C7`
-//! plus `0x2C1`).
-//!
-//! [`super::guild`] is about *being* in a guild; this is about *making* one. At 1.12 those are
-//! entirely different wires: `CMSG_GUILD_CREATE` is registered `STATUS_NEVER` on vmangos, and the
-//! only path to a new guild is buy a charter → collect nine signatures → turn it in.
-//!
-//! The server side is pinned at the bytes by vmangos `Server/Packets/Petition.{h,cpp}` (the
-//! `ReadFromWorldPacket` / `AppendBodyTo` pairs) and `Handlers/PetitionsHandler.cpp` (which
-//! packets each handler answers with, and the order of its refusals). **Two of the five
-//! server→client packets are not built through the packet classes at all** —
-//! `SMSG_PETITION_SHOW_SIGNATURES` is hand-assembled at `PetitionsHandler.cpp:160-168` and
-//! `:390-397` — so their layout is read off the handler, not off `Petition.cpp`.
-//!
-//! Four shapes of this family are worth knowing before touching any of it:
-//!
-//! - **The charter is an ITEM, and the petition id rides in its enchantment slot.** Buying stores
-//!   item [`CHARTER_ITEM_ENTRY`] and writes the petition id into `ITEM_FIELD_ENCHANTMENT` slot 0's
-//!   `id` dword (`PetitionsHandler.cpp:126`). That is not a hack the client is unaware of: the
-//!   reference's item tooltip **forces enchantment slot 0 to zero and skips the enchant lines
-//!   entirely** for any item whose template flags carry [`ITEM_FLAG_CHARTER`]
-//!   (`test ah,0x20 / jne 0x52c9ee`, wow-re `system/ui/scratch/tooltip-content-law.md:485-505`).
-//!   So slot 0 on a charter is a petition id by contract on both ends, and nothing may read it as
-//!   a `SpellItemEnchantment.dbc` row.
-//! - **Almost nothing is acked positively.** A successful buy sends **no confirmation packet** —
-//!   the client learns of it only from the `SMSG_ITEM_PUSH_RESULT` for the new item
-//!   (`PetitionsHandler.cpp:130`). Rename echoes only on success (`:209-215`). The refusals come
-//!   back as `SMSG_GUILD_COMMAND_RESULT`, the *guild* family's error channel, reused here.
-//! - **`SMSG_PETITION_SHOW_SIGNATURES` is the answer to two different questions.** It answers our
-//!   own `CMSG_PETITION_SHOW_SIGNATURES` (`:160-168`), and it is also what a *third party* is sent
-//!   when someone offers us their charter (`:390-397`, the `CMSG_OFFER_PETITION` path). One
-//!   inbound packet, two meanings, distinguished only by whether its `owner` is us.
-//! - **The signature limit is enforced three times with three different numbers.** vmangos's
-//!   `MinPetitionSigns` config (clamped 0..=9, `World.cpp:665`) decides when a petition
-//!   `IsComplete()` — with `==`, not `>=` (`GuildMgr.h:124`); the sign handler *separately*
-//!   hard-caps at nine with the comment "Client hard limit at 9 signatures"
-//!   (`PetitionsHandler.cpp:269-271`); and `SMSG_PETITION_QUERY_RESPONSE` reports min = max = 9
-//!   hardcoded (`:182-183`), regardless of the config. [`MAX_PETITION_SIGNATURES`] is that client
-//!   limit; a consumer wanting "how many does this petition need" reads the wire's
-//!   `max_signatures`, not the constant, because on a server with `MinPetitionSigns` lowered the
-//!   two disagree.
+//! The petition family (opcodes `0x1BB`-`0x1C7`, `0x2C1`): the guild-charter flow. vmangos
+//! registers `CMSG_GUILD_CREATE` as `STATUS_NEVER`, so a guild is founded only by buying a
+//! charter, collecting nine signatures and turning it in. The charter item's enchantment slot 0
+//! holds the petition id (`PetitionsHandler.cpp:126`); the reference tooltip skips enchant lines
+//! on a charter (`0x52c9ee`), so nothing may read that slot as an enchantment.
 
 use std::io::{self, Read};
 
@@ -46,111 +10,76 @@ use crate::wire::{
     capacity_hint, read_cstring, read_i32_le, read_u16_le, read_u32_le, read_u64_le, read_u8,
 };
 
-/// The one item that is a guild charter — vmangos `GUILD_CHARTER` (`PetitionsHandler.cpp:37`),
-/// also `Item::IsCharter`'s literal (`Item.h:158`, `GetEntry() == 5863u`). Confirmed against this
-/// deployment's world DB: entry 5863 "Guild Charter", display 16161, flags `0x2000`.
+/// The guild charter's item entry, vmangos `GUILD_CHARTER` (`PetitionsHandler.cpp:37`).
 pub const CHARTER_ITEM_ENTRY: u32 = 5863;
 
-/// The charter's inventory display id — vmangos `CHARTER_DISPLAY_ID` (`PetitionsHandler.cpp:38`).
-/// It rides in [`PetitionShowListEntry::charter_display_id`] as well as in the item template, and
-/// the two agree; the packet's copy exists so a vendor list can be drawn before the item is owned.
+/// The charter's display id, vmangos `CHARTER_DISPLAY_ID` (`PetitionsHandler.cpp:38`).
 pub const CHARTER_DISPLAY_ID: u32 = 16161;
 
-/// `ITEM_FLAG_CHARTER` — the template-flag bit that makes an item a signable petition
-/// (vmangos `ItemPrototype.h:77`). **The reference client keys on this same bit** to print the
-/// green `ITEM_SIGNABLE` tooltip line and to suppress the enchantment lines
-/// (wow-re `system/ui/scratch/tooltip-content-law.md:485-505`), so it is a shared contract rather
-/// than a server-side convenience.
+/// The template-flag bit of a signable petition (vmangos `ItemPrototype.h:77`); the reference
+/// tooltip keys on it for the green `ITEM_SIGNABLE` line and to suppress enchantment lines.
 pub const ITEM_FLAG_CHARTER: u32 = 0x0000_2000;
 
-/// The most signatures a 1.12 charter can hold — vmangos's own "Client hard limit at 9
-/// signatures" (`PetitionsHandler.cpp:269-271`), and the reference FrameXML's
-/// `MAX_PETITION_SIGNATURES = 9` (`PetitionFrame.lua:1`), which sizes the window's name rows.
-///
-/// This is the **row count**, not the requirement: how many a petition needs to be turned in is
-/// [`PetitionQueryResponse::min_signatures`] off the wire, which a server may configure lower.
+/// The most signatures a charter holds (`PetitionFrame.lua:1`, `PetitionsHandler.cpp:269`); the
+/// requirement is [`PetitionQueryResponse::min_signatures`].
 pub const MAX_PETITION_SIGNATURES: usize = 9;
 
-/// Charter-name cap, in *characters* — vmangos `MAX_CHARTER_NAME` (`ObjectMgr.h:401`), enforced by
-/// `ObjectMgr::IsValidCharterName` (`ObjectMgr.cpp:9322-9334`) as a UTF-8 length. The reference's
-/// own edit boxes agree: `GuildRegistrarFrameEditBox letters="24"` and the `RENAME_GUILD` popup's
-/// `maxLetters = 24`. Same number as [`super::GUILD_NAME_MAX_LENGTH`], and not a coincidence — a
-/// charter name becomes a guild name.
+/// Charter-name cap in characters (vmangos `MAX_CHARTER_NAME`, `ObjectMgr.h:401`); equal to
+/// [`super::GUILD_NAME_MAX_LENGTH`] because the charter name becomes the guild's.
 pub const CHARTER_NAME_MAX_LENGTH: usize = 24;
 
-/// `SMSG_PETITION_SIGN_RESULTS`' and `SMSG_TURN_IN_PETITION_RESULTS`' shared result code —
-/// vmangos `PetitionSigns` (`Guild/Guild.h:147-154`). One enum, two packets, and the two use
-/// **disjoint subsets** of it, which is why the arms are documented by packet.
+/// The result code shared by `SMSG_PETITION_SIGN_RESULTS` and `SMSG_TURN_IN_PETITION_RESULTS`
+/// (vmangos `PetitionSigns`, `Guild.h:147-154`); each packet uses its own subset.
 pub mod petition_result {
-    /// Signed, or turned in. Used by both packets.
+    /// Signed, or turned in; both packets.
     pub const OK: u32 = 0;
-    /// Sign only — this account has already signed this charter. vmangos checks uniqueness **per
-    /// account first**, then per character (`GuildMgr.cpp:388-400`), so a second character on one
-    /// account gets this, not a second signature.
+    /// Sign only: this account already signed. vmangos checks per account before per character
+    /// (`GuildMgr.cpp:388-400`), so an alt on the same account gets this.
     pub const ALREADY_SIGNED: u32 = 1;
-    /// Turn-in only — the would-be founder is already in a guild (`PetitionsHandler.cpp:427`).
-    /// Never sent by the sign path, which answers an already-guilded *signer* with an
-    /// `SMSG_GUILD_COMMAND_RESULT` instead (`:258`).
+    /// Turn-in only: the founder is already in a guild (`PetitionsHandler.cpp:427`); a guilded
+    /// signer gets `SMSG_GUILD_COMMAND_RESULT` instead (`:258`).
     pub const ALREADY_IN_GUILD: u32 = 2;
-    /// Sign only — you cannot sign your own charter (`PetitionsHandler.cpp:237`).
+    /// Sign only: you cannot sign your own charter (`PetitionsHandler.cpp:237`).
     pub const CANT_SIGN_OWN: u32 = 3;
-    /// Turn-in only — not enough signatures yet (`PetitionsHandler.cpp:438`).
+    /// Turn-in only: not enough signatures (`PetitionsHandler.cpp:438`); vmangos requires exactly
+    /// `MinPetitionSigns` (`GuildMgr.h:124`).
     pub const NEED_MORE: u32 = 4;
-    /// Not on the same realm. vmangos never sends it (cross-realm charters cannot arise on a
-    /// single-realm server); modelled because the reference has a string for it
-    /// (`ERR_PETITION_NOT_SAME_SERVER`) and the client's switch must have an arm.
+    /// Not on the same realm (`ERR_PETITION_NOT_SAME_SERVER`); vmangos never sends it.
     pub const NOT_SERVER: u32 = 5;
 }
 
-/// One row of `SMSG_PETITION_SHOWLIST` — a charter a petitioner NPC will sell.
-///
-/// vmangos always sends exactly one of these, and its own header says **"only 1 element is
-/// supported in the client"** (`Petition.h:176`). We parse the counted list faithfully anyway: a
-/// count is a count, and a reader that assumes one would desynchronise rather than degrade if it
-/// were ever wrong.
+/// One row of `SMSG_PETITION_SHOWLIST`: a charter the NPC sells. vmangos always sends exactly one
+/// (`Petition.h:176`: "only 1 element is supported in the client").
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionShowListEntry {
-    /// Row index, 1-based (`PetitionsHandler.cpp:501`, a literal `1`).
+    /// Row index, 1-based (`PetitionsHandler.cpp:501`).
     pub index: u32,
-    /// The item entry sold — [`CHARTER_ITEM_ENTRY`] in practice.
+    /// The item entry sold, [`CHARTER_ITEM_ENTRY`] in practice.
     pub charter_entry: u32,
-    /// Its display id — [`CHARTER_DISPLAY_ID`] in practice.
+    /// Its display id, [`CHARTER_DISPLAY_ID`] in practice.
     pub charter_display_id: u32,
-    /// Price in **copper** (1000 = 10 silver on vmangos, `PetitionsHandler.cpp:39`). Signed on the
-    /// wire (`int32`), which is why it is signed here: a reader that narrows it to `u32` would be
-    /// asserting a range the sender does not.
+    /// Price in copper, an `int32` on the wire (vmangos charges 1000, `PetitionsHandler.cpp:39`).
     pub charter_cost: i32,
-    /// vmangos sends `1` and its header says the row **"must be `&1` to show it in the UI"**
-    /// (`Petition.h:169`). Kept raw rather than folded into a `bool`: that claim is a *comment*
-    /// about the reference client, not something vmangos itself enforces, and a consumer that
-    /// wants the filter can apply it knowingly.
+    /// vmangos sends 1; its header says a row "must be `&1` to show it in the UI"
+    /// (`Petition.h:169`).
     pub entry_flags: i32,
 }
 
-/// `SMSG_PETITION_SHOWLIST` — a petitioner NPC's "here is what I sell" list. In 1.12 that is
-/// always the single guild charter, and this packet is what puts the guild registrar's window on
-/// screen.
+/// `SMSG_PETITION_SHOWLIST`: the registrar NPC's charter list, which opens its window.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionShowList {
-    /// The NPC we are talking to. Every later verb in the flow that names an NPC uses this guid.
+    /// The NPC; every later verb in the flow that names an NPC takes this guid.
     pub npc: u64,
-    /// The rows, in wire order. Normally exactly one; see [`PetitionShowListEntry`].
     pub entries: Vec<PetitionShowListEntry>,
 }
 
-/// Read `SMSG_PETITION_SHOWLIST` (VERIFIED vmangos `Server/Packets/Petition.cpp:115-127`
-/// `PetitionShowList::AppendBodyTo`, filled at `Handlers/PetitionsHandler.cpp:482-507`):
-/// `u64 npcGuid`, `u8 count`, then per row `u32 index`, `u32 charterEntry`, `u32 charterDisplayId`,
-/// `i32 charterCost`, `i32 entryFlags`.
-///
-/// The send is gated on `GetNPCIfCanInteractWith(guid, UNIT_NPC_FLAG_PETITIONER)`
-/// (`:484`; the flag is `0x200`, `Objects/UnitDefines.h:666`), so a list arriving at all is the
-/// server's confirmation that we are in range of a real registrar.
+/// Read `SMSG_PETITION_SHOWLIST` (vmangos `Packets/Petition.cpp:115-127`): `u64 npc, u8 count`,
+/// then per row `u32 index, u32 entry, u32 displayId, i32 cost, i32 flags`. The request handler
+/// sends it only for an NPC in range with `UNIT_NPC_FLAG_PETITIONER` (`PetitionsHandler.cpp:484`).
 pub(super) fn read_petition_show_list(r: &mut impl Read) -> io::Result<PetitionShowList> {
     let npc = read_u64_le(r)?;
     let count = read_u8(r)?;
-    // vmangos sends exactly one charter (`PetitionsHandler.cpp:503`, `entries = { entry }`);
-    // 8 is generous.
+    // vmangos sends exactly one charter (`PetitionsHandler.cpp:503`); 8 is generous.
     let mut entries = Vec::with_capacity(capacity_hint(count, 8));
     for _ in 0..count {
         entries.push(PetitionShowListEntry {
@@ -164,48 +93,30 @@ pub(super) fn read_petition_show_list(r: &mut impl Read) -> io::Result<PetitionS
     Ok(PetitionShowList { npc, entries })
 }
 
-/// One signature on a charter — a signer's guid, and the dword that always follows it.
+/// One signature on a charter: the signer's guid and a trailing dword.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionSignature {
-    /// The signing character's guid. Turning it into a *name* is the client's job: the packet
-    /// carries no names at all.
+    /// The signer's guid; the packet carries no names.
     pub signer: u64,
-    /// The trailing dword, which vmangos writes as a literal `0`
-    /// (`Guild/GuildMgr.cpp:358-366`, `data << 0`). Kept rather than skipped so the field is
-    /// visible in a dump and a non-zero value from another server would be *noticed* rather than
-    /// silently consumed.
+    /// Always 0 from vmangos (`GuildMgr.cpp:358-366`); decoded, not skipped.
     pub unknown: u32,
 }
 
-/// `SMSG_PETITION_SHOW_SIGNATURES` — who has signed a charter. **The answer to two different
-/// questions** (module doc): our own `CMSG_PETITION_SHOW_SIGNATURES`, and someone else's
-/// `CMSG_OFFER_PETITION` aimed at us.
-///
-/// Note what is *not* here: the guild name, the body text, and the signature requirement. Those
-/// live only in `SMSG_PETITION_QUERY_RESPONSE`, keyed by [`Self::petition_id`] — the same
-/// two-caches shape [`super::guild`] has, where the roster carries no guild name.
+/// `SMSG_PETITION_SHOW_SIGNATURES`: a charter's signers, in answer to our request or when
+/// someone offers us theirs. Its name and requirement come from `SMSG_PETITION_QUERY_RESPONSE`.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionShowSignatures {
-    /// The charter **item's** guid — the handle every later verb takes (sign, offer, rename, turn
-    /// in, decline). Not the petition id.
+    /// The charter item's guid, which every later verb takes; not the petition id.
     pub item: u64,
-    /// The charter owner's character guid. Whether this is us is what makes the window the
-    /// leader's view or a signer's view.
+    /// The charter's owner; whether it is us decides the leader's view or a signer's.
     pub owner: u64,
-    /// The petition id — the key `CMSG_PETITION_QUERY` takes, and the same value the charter
-    /// item's enchantment slot 0 carries (module doc).
+    /// The key `CMSG_PETITION_QUERY` takes, also carried in the charter's enchantment slot 0.
     pub petition_id: u32,
-    /// The signatures so far, in wire order.
     pub signatures: Vec<PetitionSignature>,
 }
 
-/// Read `SMSG_PETITION_SHOW_SIGNATURES` (VERIFIED vmangos `Handlers/PetitionsHandler.cpp:160-168`
-/// and `:390-397`, which build it **by hand** rather than through a packet class):
-/// `u64 itemGuid`, `u64 ownerGuid`, `u32 petitionId`, `u8 signatureCount`, then per signature
-/// `u64 signerGuid` + `u32 0`.
-///
-/// The 12-byte stride is corroborated by the sender's own size hint `8+8+4+1 + signs*12` and by
-/// `Guild/GuildMgr.cpp:358-366` (`Petition::BuildSignatureData`).
+/// Read `SMSG_PETITION_SHOW_SIGNATURES` (hand-built at vmangos `PetitionsHandler.cpp:160-168`,
+/// `:390-397`): `u64 item, u64 owner, u32 petitionId, u8 count`, then `u64 signer, u32 0` each.
 pub(super) fn read_petition_show_signatures(
     r: &mut impl Read,
 ) -> io::Result<PetitionShowSignatures> {
@@ -229,24 +140,19 @@ pub(super) fn read_petition_show_signatures(
     })
 }
 
-/// `SMSG_PETITION_SIGN_RESULTS` — the verdict on one signature attempt.
-///
-/// **It is sent to both parties on success**: once to the signer (`PetitionsHandler.cpp:299`) and
-/// again, identical, to the charter's owner if they are online (`:312-316`). Both copies name the
-/// *signer* in [`Self::player`], so a receiver cannot tell the two apart from this packet alone —
-/// only from whether it holds that charter.
+/// `SMSG_PETITION_SIGN_RESULTS`: the verdict on one signature. A success goes, identical, to the
+/// signer and the online owner (`PetitionsHandler.cpp:299`, `:312-316`); both name the signer.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionSignResults {
     /// The charter item's guid.
     pub item: u64,
-    /// The **signer's** guid — in both copies of the packet, per the doc above.
+    /// The signer's guid, in both copies.
     pub player: u64,
     /// A [`petition_result`] code.
     pub result: u32,
 }
 
-/// Read `SMSG_PETITION_SIGN_RESULTS` (VERIFIED vmangos `Server/Packets/Petition.cpp:69-74`
-/// `PetitionSignResults::AppendBodyTo`): `u64 itemGuid`, `u64 playerGuid`, `u32 result`.
+/// Read `SMSG_PETITION_SIGN_RESULTS` (vmangos `Packets/Petition.cpp:69-74`).
 pub(super) fn read_petition_sign_results(r: &mut impl Read) -> io::Result<PetitionSignResults> {
     Ok(PetitionSignResults {
         item: read_u64_le(r)?,
@@ -255,64 +161,48 @@ pub(super) fn read_petition_sign_results(r: &mut impl Read) -> io::Result<Petiti
     })
 }
 
-/// `SMSG_PETITION_QUERY_RESPONSE` — a petition's own record, keyed by petition id.
-///
-/// Sixteen fields, of which vmangos fills three with anything but a constant, and whose own header
-/// says *"all those fields below don't really change anything in the UI"* (`Petition.h:126`). They
-/// are parsed in full regardless: the trailing `choice` list is length-prefixed, so skipping the
-/// middle would make the tail unreadable, and a field that is constant on this server is not
-/// thereby constant on the wire.
+/// `SMSG_PETITION_QUERY_RESPONSE`: a petition's record, keyed by petition id.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionQueryResponse {
     /// The petition id we asked about.
     pub petition_id: u32,
     /// The charter owner's character guid.
     pub owner: u64,
-    /// The proposed guild's name. This is the only place it exists on the wire.
+    /// The proposed guild's name, carried by no other packet.
     pub name: String,
-    /// Free text on the charter — always empty on vmangos (`PetitionsHandler.cpp:178`).
+    /// Free text on the charter; empty on vmangos (`PetitionsHandler.cpp:178`).
     pub body_text: String,
-    /// vmangos sends `1` (`:179`). Meaning unknown; kept because it is a real wire field.
+    /// vmangos sends 1 (`PetitionsHandler.cpp:179`); meaning unknown.
     pub flags: u32,
-    /// How many signatures are **required**. vmangos hardcodes 9 here even when its
-    /// `MinPetitionSigns` config is lower (module doc), so this is the number the reference's
-    /// Request-Signature button disables against, and it need not equal
-    /// [`MAX_PETITION_SIGNATURES`].
+    /// Signatures required, which the reference's Request-Signature button tests; vmangos sends 9
+    /// even when its `MinPetitionSigns` is lower (`PetitionsHandler.cpp:182`).
     pub min_signatures: u32,
-    /// How many signatures fit. vmangos hardcodes 9 (`:183`).
+    /// Signatures that fit; 9 on vmangos (`PetitionsHandler.cpp:183`).
     pub max_signatures: u32,
-    /// Deadline timestamp — `0` on vmangos.
+    /// Deadline timestamp, 0 on vmangos.
     pub deadline: u32,
-    /// Creation timestamp — `0` on vmangos.
+    /// Creation timestamp, 0 on vmangos.
     pub creation: u32,
-    /// Restricting guild id — `0` on vmangos.
+    /// Restricting guild id, 0 on vmangos.
     pub allowed_guild_id: u32,
-    /// Class mask restriction — `0` on vmangos.
+    /// Class mask restriction, 0 on vmangos.
     pub allowed_classes: u32,
-    /// Race mask restriction — `0` on vmangos.
+    /// Race mask restriction, 0 on vmangos.
     pub allowed_races: u32,
-    /// Gender restriction — **`u16` on the wire, not `u32`** (`Petition.cpp:94`). The one odd
-    /// width in the packet, and misreading it as a dword shifts every field after it by two bytes.
+    /// Gender restriction: a `u16`, the packet's one odd width (`Packets/Petition.cpp:94`).
     pub allowed_gender: u16,
-    /// Minimum level — `0` on vmangos.
+    /// Minimum level, 0 on vmangos.
     pub allowed_min_level: u32,
-    /// Maximum level — `0` on vmangos.
+    /// Maximum level, 0 on vmangos.
     pub allowed_max_level: u32,
-    /// The multiple-choice options this petition offers — always empty on vmangos, and the reason
-    /// the tail cannot be skipped: the count is what says where `default_choice` starts.
+    /// The petition's multiple-choice options; empty on vmangos.
     pub choices: Vec<String>,
-    /// Which choice is pre-selected — `0` on vmangos.
+    /// The pre-selected choice, 0 on vmangos.
     pub default_choice: u32,
 }
 
-/// Read `SMSG_PETITION_QUERY_RESPONSE` (VERIFIED vmangos `Server/Packets/Petition.cpp:81-102`
-/// `PetitionQueryResponse::AppendBodyTo`, filled at `Handlers/PetitionsHandler.cpp:177-184`):
-/// `u32 petitionId`, `u64 ownerGuid`, cstring name, cstring bodyText, `u32 flags`,
-/// `u32 minSignatures`, `u32 maxSignatures`, `u32 deadline`, `u32 creation`, `u32 allowedGuildID`,
-/// `u32 allowedClasses`, `u32 allowedRaces`, **`u16 allowedGender`**, `u32 allowedMinLevel`,
-/// `u32 allowedMaxLevel`, `u32 choiceCount`, `choiceCount ×` cstring, `u32 defaultChoice`.
-///
-/// The `u16` in the middle is the trap: see [`PetitionQueryResponse::allowed_gender`].
+/// Read `SMSG_PETITION_QUERY_RESPONSE` (vmangos `Packets/Petition.cpp:81-102`): the fields in
+/// struct order, the choices as a `u32` count of C strings.
 pub(super) fn read_petition_query_response(r: &mut impl Read) -> io::Result<PetitionQueryResponse> {
     let petition_id = read_u32_le(r)?;
     let owner = read_u64_le(r)?;
@@ -355,22 +245,16 @@ pub(super) fn read_petition_query_response(r: &mut impl Read) -> io::Result<Peti
     })
 }
 
-/// `MSG_PETITION_RENAME` — the server's echo of a successful rename.
-///
-/// Sent **only on success** (`PetitionsHandler.cpp:209-215`); a rejected name comes back as an
-/// `SMSG_GUILD_COMMAND_RESULT` instead. Note the handler does **no ownership check** — anyone
-/// holding the item may rename it.
+/// `MSG_PETITION_RENAME`: the server's echo of a successful rename (`PetitionsHandler.cpp:209`);
+/// a rejected name gets `SMSG_GUILD_COMMAND_RESULT`. Any holder of the item may rename it.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionRename {
     /// The charter item's guid.
     pub item: u64,
-    /// Its new name.
     pub name: String,
 }
 
-/// Read `MSG_PETITION_RENAME` (VERIFIED vmangos `Server/Packets/Petition.cpp:104-108`
-/// `PetitionRename::AppendBodyTo`): `u64 itemGuid`, cstring newName. The same two fields the
-/// client sends, in the same order — which is what makes it an `MSG_` rather than a pair.
+/// Read `MSG_PETITION_RENAME` (vmangos `Packets/Petition.cpp:104-108`): `u64` item, cstring name.
 pub(super) fn read_petition_rename(r: &mut impl Read) -> io::Result<PetitionRename> {
     Ok(PetitionRename {
         item: read_u64_le(r)?,
@@ -378,56 +262,29 @@ pub(super) fn read_petition_rename(r: &mut impl Read) -> io::Result<PetitionRena
     })
 }
 
-/// Read `SMSG_TURN_IN_PETITION_RESULTS` (VERIFIED vmangos `Server/Packets/Petition.cpp:76-79`
-/// `TurnInPetitionResults::AppendBodyTo`): one `u32`, a [`petition_result`] code — and **only** the
-/// code. Which charter it refers to is implicit; there can be only one in flight.
-///
-/// The three codes vmangos actually sends here are [`petition_result::OK`] (`:473`),
-/// [`petition_result::ALREADY_IN_GUILD`] (`:427`) and [`petition_result::NEED_MORE`] (`:438`). A
-/// name collision is reported as `SMSG_GUILD_COMMAND_RESULT` instead and produces no results
-/// packet at all (`:445`), so "no answer" is a real outcome of a turn-in.
+/// Read `SMSG_TURN_IN_PETITION_RESULTS` (vmangos `Packets/Petition.cpp:76-79`): a lone
+/// [`petition_result`] code. A name collision sends `SMSG_GUILD_COMMAND_RESULT` and no result
+/// packet at all (`PetitionsHandler.cpp:445`).
 pub(super) fn read_turn_in_petition_results(r: &mut impl Read) -> io::Result<u32> {
     read_u32_le(r)
 }
 
-/// Read `MSG_PETITION_DECLINE`'s **inbound** form (VERIFIED vmangos
-/// `Server/Packets/Petition.cpp:110-113` `PetitionDecline::AppendBodyTo`): one `u64`, the guid of
-/// the player who declined. Delivered only to the charter's owner
-/// (`Handlers/PetitionsHandler.cpp:321-338`).
-///
-/// The outbound form of the same opcode carries the *item* guid instead
-/// ([`petition_decline`]) — one opcode, two different bodies by direction, which is what `MSG_`
-/// means here.
+/// Read `MSG_PETITION_DECLINE` inbound (vmangos `Packets/Petition.cpp:110-113`): the decliner's
+/// guid, sent to the owner only. The outbound form carries the item guid instead.
 pub(super) fn read_petition_decline(r: &mut impl Read) -> io::Result<u64> {
     read_u64_le(r)
 }
 
-/// Body of `CMSG_PETITION_SHOWLIST` (VERIFIED vmangos `Server/Packets/Petition.cpp:3-6`
-/// `PetitionShowListRequest::ReadFromWorldPacket`): one `u64`, the petitioner NPC's guid.
-///
-/// Answered by `SMSG_PETITION_SHOWLIST`, or by nothing at all if the NPC is out of range or lacks
-/// `UNIT_NPC_FLAG_PETITIONER` (`Handlers/PetitionsHandler.cpp:484`). The server also sends that
-/// answer unasked when a `GOSSIP_OPTION_PETITIONER` row is selected (`Player.cpp:12428-12431`), so
-/// this request is the *second* way in, not the only one.
+/// Body of `CMSG_PETITION_SHOWLIST` (vmangos `Packets/Petition.cpp:3-6`): the NPC's guid. The
+/// server also sends the list unasked for a `GOSSIP_OPTION_PETITIONER` row (`Player.cpp:12428`).
 pub fn petition_show_list(npc: u64) -> Vec<u8> {
     npc.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_PETITION_BUY` (VERIFIED vmangos `Server/Packets/Petition.cpp:47-67`
-/// `PetitionBuy::ReadFromWorldPacket`) — **72 bytes, of which the server reads exactly two
-/// fields**: the NPC guid at offset 0 and the name at offset 20. Everything else is skipped.
-///
-/// The shape is a generic multi-choice petition struct that never shipped: `u64 npcGuid`,
-/// `u32 0`, `u64 0`, cstring name, `10 × u32 0`, `u16 0`, `u8 0`, `u32 index`, `u32 0`. We send
-/// zeros for every skipped field — including `index`, which the server's own comment calls
-/// "unused" — because a field nobody reads has no correct non-zero value, and a zero is the one
-/// choice that cannot encode an accident.
-///
-/// The refusal ladder is worth knowing, because none of it is a petition packet: an already-taken
-/// or invalid name answers `SMSG_GUILD_COMMAND_RESULT(GUILD_CREATE_S, name, …)`
-/// (`Handlers/PetitionsHandler.cpp:78`, `:83`, `:93`), too little money answers `SMSG_BUY_FAILED`
-/// (`:108`), a full bag answers `SMSG_INVENTORY_CHANGE_FAILURE` (`:116`) — and **success answers
-/// nothing but the new item** (`:130`).
+/// Body of `CMSG_PETITION_BUY` (vmangos `Packets/Petition.cpp:47-67`): `u64 npc, u32 0, u64 0`,
+/// the name, `u32 0` x10, `u16 0, u8 0, u32 index, u32 0`. The server reads only NPC and name.
+/// A bad name gets `SMSG_GUILD_COMMAND_RESULT`, no money `SMSG_BUY_FAILED`, a full bag
+/// `SMSG_INVENTORY_CHANGE_FAILURE`; success is only the item push (`PetitionsHandler.cpp:78-130`).
 pub fn petition_buy(npc: u64, name: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(72 + name.len());
     body.extend_from_slice(&npc.to_le_bytes());
@@ -437,30 +294,19 @@ pub fn petition_buy(npc: u64, name: &str) -> Vec<u8> {
     body.extend_from_slice(&[0u8; 40]); // 10 × u32
     body.extend_from_slice(&0u16.to_le_bytes());
     body.push(0);
-    body.extend_from_slice(&0u32.to_le_bytes()); // index — the server's own "unused"
+    body.extend_from_slice(&0u32.to_le_bytes()); // index, "unused" per the server
     body.extend_from_slice(&0u32.to_le_bytes());
     body
 }
 
-/// Body of `CMSG_PETITION_SHOW_SIGNATURES` (VERIFIED vmangos `Server/Packets/Petition.cpp:8-11`
-/// `PetitionShowSignaturesRequest::ReadFromWorldPacket`): one `u64`, the charter **item's** guid.
-///
-/// Answered with `SMSG_PETITION_SHOW_SIGNATURES` — or silently dropped if we are already in a
-/// guild (`Handlers/PetitionsHandler.cpp:140`) or do not hold that item (`:143`).
+/// Body of `CMSG_PETITION_SHOW_SIGNATURES` (vmangos `Packets/Petition.cpp:8-11`): the charter
+/// item's guid, unanswered if we are guilded or lack the item (`PetitionsHandler.cpp:140-143`).
 pub fn petition_show_signatures(item: u64) -> Vec<u8> {
     item.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_PETITION_SIGN` (VERIFIED vmangos `Server/Packets/Petition.cpp:35-39`
-/// `PetitionSign::ReadFromWorldPacket`): `u64 itemGuid` then one `i8` the server **skips**, whose
-/// own vmangos comment is *"argument of `/run SignPetition(123)` is never used in the official
-/// interface"*.
-///
-/// **The client's default for that byte is `1`, not `0`** — `SignPetition`'s optional Lua argument
-/// initialises `edi = 1` at `0x4f46d9` and the byte goes out through `Put8` at `0x4f4749` (wow-re
-/// `system/ui/scratch/petition-charter-api.md`). Since the server reads and discards it, **nothing
-/// observable depends on the value**, which is exactly why it shipped here as `0` and why only a
-/// golden can tell the difference.
+/// Body of `CMSG_PETITION_SIGN` (vmangos `Packets/Petition.cpp:35-39`): the item guid, then an
+/// `i8` the server skips. `SignPetition` defaults it to 1 (`0x4f46d9`, sent at `0x4f4749`).
 pub fn petition_sign(item: u64, arg: i8) -> Vec<u8> {
     let mut body = Vec::with_capacity(9);
     body.extend_from_slice(&item.to_le_bytes());
@@ -468,13 +314,9 @@ pub fn petition_sign(item: u64, arg: i8) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_OFFER_PETITION` (VERIFIED vmangos `Server/Packets/Petition.cpp:41-45`
-/// `OfferPetition::ReadFromWorldPacket`): `u64 itemGuid`, `u64 playerGuid` — the charter, and who
-/// to show it to.
-///
-/// On success the server sends `SMSG_PETITION_SHOW_SIGNATURES` **to the target**, not back to us
-/// (`Handlers/PetitionsHandler.cpp:390-397`); we hear only about refusals, as
-/// `SMSG_GUILD_COMMAND_RESULT`.
+/// Body of `CMSG_OFFER_PETITION` (vmangos `Packets/Petition.cpp:41-45`): item guid, target guid.
+/// Success sends the target `SMSG_PETITION_SHOW_SIGNATURES` (`PetitionsHandler.cpp:390-397`); we
+/// hear only refusals, as `SMSG_GUILD_COMMAND_RESULT`.
 pub fn offer_petition(item: u64, player: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&item.to_le_bytes());
@@ -482,24 +324,15 @@ pub fn offer_petition(item: u64, player: u64) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_TURN_IN_PETITION` (VERIFIED vmangos `Server/Packets/Petition.cpp:24-27`
-/// `TurnInPetition::ReadFromWorldPacket`): one `u64`, the charter item's guid.
-///
-/// Only the petition's **owner** may turn it in; anyone else is refused silently
-/// (`Handlers/PetitionsHandler.cpp:432`). On success the guild is created with every signer as a
-/// member at the lowest rank, the petition row is deleted, and *then* the item is destroyed — in
-/// that order, because destroying a charter cascades into deleting its petition
-/// (`Player.cpp:10811-10817`).
+/// Body of `CMSG_TURN_IN_PETITION` (vmangos `Packets/Petition.cpp:24-27`): the charter item's
+/// guid. Only the owner may turn it in; anyone else gets silence (`PetitionsHandler.cpp:432`).
+/// Success founds the guild with every signer at the lowest rank.
 pub fn turn_in_petition(item: u64) -> Vec<u8> {
     item.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_PETITION_QUERY` (VERIFIED vmangos `Server/Packets/Petition.cpp:13-17`
-/// `PetitionQuery::ReadFromWorldPacket`): `u32 petitionId`, `u64 itemGuid`.
-///
-/// The item guid is **read and then ignored** by the handler (`Handlers/PetitionsHandler.cpp:171-185`),
-/// which looks the petition up by id alone. Sent anyway, at its true value: a field the current
-/// server does not use is not a field to fill with garbage.
+/// Body of `CMSG_PETITION_QUERY` (vmangos `Packets/Petition.cpp:13-17`): `u32 petitionId`,
+/// `u64 item`; the server looks up by id alone (`PetitionsHandler.cpp:171-185`).
 pub fn petition_query(petition_id: u32, item: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&petition_id.to_le_bytes());
@@ -507,14 +340,8 @@ pub fn petition_query(petition_id: u32, item: u64) -> Vec<u8> {
     body
 }
 
-/// Body of `MSG_PETITION_RENAME`'s **outbound** form (VERIFIED vmangos
-/// `Server/Packets/Petition.cpp:29-33` `PetitionRename::ReadFromWorldPacket`): `u64 itemGuid`,
-/// cstring newName.
-///
-/// Echoed back as the same two fields on success ([`read_petition_rename`]); rejected names come
-/// back as `SMSG_GUILD_COMMAND_RESULT` and no echo. The name is capped at
-/// [`CHARTER_NAME_MAX_LENGTH`] characters by the server's own validator — not truncated here, for
-/// the reason [`super::guild`]'s caps give: silently shortening sends the wrong text.
+/// Body of `MSG_PETITION_RENAME` outbound (vmangos `Packets/Petition.cpp:29-33`): `u64` item,
+/// cstring name. Not truncated to [`CHARTER_NAME_MAX_LENGTH`]; the server validates it.
 pub fn petition_rename(item: u64, name: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(9 + name.len());
     body.extend_from_slice(&item.to_le_bytes());
@@ -522,15 +349,12 @@ pub fn petition_rename(item: u64, name: &str) -> Vec<u8> {
     body
 }
 
-/// Body of `MSG_PETITION_DECLINE`'s **outbound** form (VERIFIED vmangos
-/// `Server/Packets/Petition.cpp:19-22` `PetitionDecline::ReadFromWorldPacket`): one `u64`, the
-/// charter item's guid. The server forwards our guid to the charter's owner
-/// ([`read_petition_decline`]).
+/// Body of `MSG_PETITION_DECLINE` outbound (vmangos `Packets/Petition.cpp:19-22`): the charter
+/// item's guid; the server forwards our guid to the owner.
 pub fn petition_decline(item: u64) -> Vec<u8> {
     item.to_le_bytes().to_vec()
 }
 
-/// Append a NUL-terminated string to `body`.
 fn push_cstring(body: &mut Vec<u8>, s: &str) {
     body.extend_from_slice(s.as_bytes());
     body.push(0);
@@ -540,9 +364,7 @@ fn push_cstring(body: &mut Vec<u8>, s: &str) {
 mod tests {
     use super::*;
 
-    /// `CMSG_PETITION_BUY`'s body is a fixed 72 bytes plus the name — the shape vmangos's reader
-    /// walks field by field. A body one byte short leaves the reader mid-field and the buy is
-    /// silently dropped, which is exactly the failure this pins.
+    /// A body one byte short leaves vmangos's reader mid-field and the buy is silently dropped.
     #[test]
     fn petition_buy_body_is_seventy_two_bytes_plus_the_name() {
         let body = petition_buy(0x1234_5678_9abc_def0, "Test");
@@ -555,8 +377,6 @@ mod tests {
         );
     }
 
-    /// The charter constants are a shared contract between server and reference client, not
-    /// vmangos policy — the tooltip's signable branch keys on the same `0x2000`.
     #[test]
     fn charter_constants_match_the_world_data() {
         assert_eq!(CHARTER_ITEM_ENTRY, 5863);
diff --git a/crates/benilla-protocol/src/messages/pose.rs b/crates/benilla-protocol/src/messages/pose.rs
index 7fc033db..08ff5858 100644
--- a/crates/benilla-protocol/src/messages/pose.rs
+++ b/crates/benilla-protocol/src/messages/pose.rs
@@ -1,31 +1,42 @@
-//! The two **client-volunteered pose** bodies — sheath state and stand state. Split out of
-//! `messages/spells.rs` (`set_sheathed`) and `messages/client.rs` (`stand_state_change`) by
-//! decision 0640, which is also what mirrors `world::writer::pose`.
-//!
-//! They were apart for no reason anyone recorded, and they are plainly one thing: the client
-//! decides, the server stores whatever we send with no validation of its own, and the echo into our
-//! `UNIT_FIELD_BYTES_2` / `UNIT_FIELD_BYTES_1` is what every observer's body reads (decisions
-//! 0080 / 0080c). The server has no independent way to know a weapon is drawn or that we sat down —
-//! so the only consequence of getting one wrong is that other players see the wrong body.
-//!
-//! `CMSG_MOUNTSPECIAL_ANIM`, the third member of that family, has an empty body and so needs no
-//! builder here (see `world::writer::pose`).
+//! The client-volunteered pose bodies, sheath and stand state: the server stores what we send
+//! unvalidated and echoes it through our unit fields, which every observer's body reads.
 
-/// Body of `CMSG_SETSHEATHED` (vmangos `SetSheathed::ReadFromWorldPacket`: `recv_data >> sheathed`):
-/// one `u32` sheath state (0 unarmed/stowed, 1 melee drawn, 2 ranged drawn). Purely
-/// client-volunteered — `HandleSetSheathedOpcode` (`CombatHandler.cpp:80-87`) just stores whatever
-/// we send via `Unit::SetSheath`, which lands in our own `UNIT_FIELD_BYTES_2` and relays to nearby
-/// observers on the next values update; the server has no independent way to know a weapon is drawn.
+use std::io;
+
+use crate::wire::read_u8;
+
+/// Body of `CMSG_SETSHEATHED`: a `u32` sheath state (0 stowed, 1 melee, 2 ranged), stored
+/// unvalidated into `UNIT_FIELD_BYTES_2` (vmangos `CombatHandler.cpp:80-87`).
 pub fn set_sheathed(state: u32) -> Vec<u8> {
     state.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_STANDSTATECHANGE` (vmangos `StandStateChange::ReadFromWorldPacket`:
-/// `recv_data >> animState`): one `u32` stand state. The server accepts only
-/// {0 STAND, 1 SIT, 3 SLEEP, 8 KNEEL} (`HandleStandStateChangeOpcode`,
-/// `MiscHandler.cpp:437`) and applies it via `Unit::SetStandState` → `UNIT_FIELD_BYTES_1`
-/// byte 0, which relays to every observer — the same client-volunteers → server-echoes →
-/// fields-drive-everyone pattern as sheath (decision 0080c).
+/// Body of `CMSG_STANDSTATECHANGE`: a `u32` stand state, of which the server accepts only
+/// 0 stand, 1 sit, 3 sleep and 8 kneel (`MiscHandler.cpp:437`), into `UNIT_FIELD_BYTES_1` byte 0.
 pub fn stand_state_change(state: u32) -> Vec<u8> {
     state.to_le_bytes().to_vec()
 }
+
+/// Read `SMSG_STANDSTATE_UPDATE`: one `u8` stand state (vmangos `Unit.cpp:9541`), with no guid;
+/// the reference (`0x603e50`) applies it to the local player whatever unit the server meant.
+pub(super) fn read_stand_state_update(r: &mut &[u8]) -> io::Result<u8> {
+    read_u8(r)
+}
+
+#[cfg(test)]
+mod inbound_tests {
+    use crate::messages::{opcode, parse_server, ServerPacket};
+
+    #[test]
+    fn stand_state_update_decodes() {
+        // One byte; a drink's sit is 1.
+        match parse_server(opcode::SMSG_STANDSTATE_UPDATE, &[1]).unwrap() {
+            ServerPacket::StandStateUpdate { state } => assert_eq!(state, 1),
+            other => panic!("expected StandStateUpdate, got {}", other.name()),
+        }
+        assert!(
+            parse_server(opcode::SMSG_STANDSTATE_UPDATE, &[]).is_err(),
+            "a short body is an error"
+        );
+    }
+}
diff --git a/crates/benilla-protocol/src/messages/progression.rs b/crates/benilla-protocol/src/messages/progression.rs
index e494e196..bb26e663 100644
--- a/crates/benilla-protocol/src/messages/progression.rs
+++ b/crates/benilla-protocol/src/messages/progression.rs
@@ -1,31 +1,23 @@
-//! Character-progression messages — XP awarded, the level-up summary, and the talent spend. Split
-//! out of `messages/spells.rs` (decision 0640).
-//!
-//! One decision produced all three (**0304**), and they are one arc on the wire: kill or complete
-//! something → `SMSG_LOG_XPGAIN` → (on a ding) `SMSG_LEVELUP_INFO` → the points it granted go back
-//! out as `CMSG_LEARN_TALENT`. Layouts VERIFIED against vmangos (cited per item).
+//! Character-progression messages: XP, exploration, level-up, talent learning and talent wipe.
 
 use std::io::{self, Read};
 
 use crate::wire::{read_f32_le, read_u32_le, read_u64_le, read_u8};
 
-/// One decoded `SMSG_LOG_XPGAIN` — an XP award, kill or non-kill (vmangos
-/// `WorldPackets::Misc::LogXpGain::AppendBodyTo`, `Server/Packets/Misc.cpp:512-522` +
-/// `Misc.h:779-790`). `victim` is `0` for non-kill xp (quest/exploration/GM command).
+/// `SMSG_LOG_XPGAIN`: an XP award; `victim` is 0 for non-kill XP (vmangos `Misc.cpp:512-522`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct XpGain {
     pub victim: u64,
     pub total: u32,
-    /// The award before the rested bonus — only a kill carries it on the wire (rested applies
-    /// to kill XP only, so a non-kill packet's `base` is `= total` here). `total − base` is the
-    /// chat line's "(+N exp Rested bonus)" amount (decision 0304).
+    /// The award before the rested bonus; only a kill carries it, else it equals `total`.
+    /// `total - base` is the chat line's "(+N exp Rested bonus)".
     pub base: u32,
     pub kill: bool,
 }
 
-/// Read `SMSG_LOG_XPGAIN`: victim raw `u64` (0 for non-kill) · totalXp u32 · xpType u8 (0 = kill,
-/// 1 = non-kill) · iff `xpType == 0`: baseXp u32 · groupBonus f32 (read and dropped — composing
-/// the "+N group bonus" line form waits for parties to exist; decision 0304 scope call).
+/// Read `SMSG_LOG_XPGAIN`: `u64 victim, u32 total, u8 type` (0 kill, 1 other), then for a kill
+/// `u32 base, f32 groupBonus`. Deviation: the group bonus is read and dropped; vmangos always
+/// sends 1.0, meaning none (`Player.cpp:3039`), so 1.12 shows no group-bonus line either.
 pub(super) fn read_xp_gain(r: &mut impl Read) -> io::Result<XpGain> {
     let victim = read_u64_le(r)?;
     let total = read_u32_le(r)?;
@@ -44,32 +36,25 @@ pub(super) fn read_xp_gain(r: &mut impl Read) -> io::Result<XpGain> {
     })
 }
 
-/// One decoded `SMSG_EXPLORATION_EXPERIENCE` — a first visit to an area: the newly explored
-/// `AreaTable.dbc` row **id** (not the explore-flag bit) and the XP the discovery granted
-/// (vmangos `WorldPackets::Misc::ExplorationExperience`, `Server/Packets/Misc.h:838-846` +
-/// `Misc.cpp:552-556`; filled by `Player::CheckAreaExploreAndOutdoor`, Player.cpp:6228-6341,
-/// which sends it **even when xp is 0** — max level, or an area with no level). The XP itself
-/// also rides a separate non-kill [`XpGain`]; this packet is what names the area. Decision 0828.
+/// `SMSG_EXPLORATION_EXPERIENCE`: a first visit to an area, sent even for 0 XP
+/// (`Player.cpp:6228-6341`). The XP also arrives as a non-kill [`XpGain`]; this names the area.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ExplorationXp {
-    /// The `AreaTable.dbc` row id of the area just discovered.
+    /// The `AreaTable.dbc` row id, not the explore-flag bit.
     pub area_id: u32,
-    /// The exploration XP awarded (0 at max level / unleveled areas).
+    /// The XP awarded; 0 at max level or for an area without a level.
     pub xp: u32,
 }
 
-/// Read `SMSG_EXPLORATION_EXPERIENCE`: areaId u32 · xp u32 (8 bytes, `Misc.cpp:552-556`).
+/// Read `SMSG_EXPLORATION_EXPERIENCE`: `u32 areaId, u32 xp` (vmangos `Misc.cpp:552-556`).
 pub(super) fn read_exploration_xp(r: &mut impl Read) -> io::Result<ExplorationXp> {
     let area_id = read_u32_le(r)?;
     let xp = read_u32_le(r)?;
     Ok(ExplorationXp { area_id, xp })
 }
 
-/// Body of `CMSG_LEARN_TALENT` (vmangos `Server/Packets/Skill.h:10-19` +
-/// `Player::LearnTalent`, Player.cpp:20807): `u32 talentId` (a `Talent.dbc` row id) +
-/// `u32 requestedRank`, **0-based** — requesting rank k learns *up to* k (the server spends
-/// `k − current + 1` points), so the click sends the current rank count itself (the next
-/// 0-based rank). Decision 0304.
+/// Body of `CMSG_LEARN_TALENT`: `u32` `Talent.dbc` id, `u32` 0-based rank. Requesting rank k
+/// learns up to k (`Player.cpp:20807`), so a click sends the current rank count.
 pub fn learn_talent(talent_id: u32, requested_rank: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(8);
     body.extend_from_slice(&talent_id.to_le_bytes());
@@ -77,26 +62,18 @@ pub fn learn_talent(talent_id: u32, requested_rank: u32) -> Vec<u8> {
     body
 }
 
-/// One decoded **inbound** `MSG_TALENT_WIPE_CONFIRM` — a class trainer asking whether to unlearn
-/// every talent (vmangos `WorldPackets::Skill::TalentWipeConfirmResponse`,
-/// `Server/Packets/Skill.h:39-52` + `Skill.cpp:19-23`, filled by `Player::SendTalentWipeConfirm`,
-/// `Player.cpp:8338`). Decision 1580.
+/// Inbound `MSG_TALENT_WIPE_CONFIRM`: a class trainer asks whether to unlearn every talent
+/// (vmangos `Player.cpp:8338`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct TalentWipeConfirm {
-    /// The trainer that asked — echoed back in the outbound answer, where it is load-bearing
-    /// (`HandleTalentWipeConfirmOpcode` resolves it to a live `UNIT_NPC_FLAG_TRAINER` in range and
-    /// drops the request otherwise), exactly like the innkeeper guid in [`super::binder`].
-    ///
-    /// **Zero means "you have no talents to reset"** — vmangos's own comment on the field, and the
-    /// value its refusal path sends (`SkillHandler.cpp:52`, after a failed `ResetTalents`). There
-    /// is no trainer to ask about, so there is nothing to put on screen.
+    /// The asking trainer, echoed in the answer and required to be a trainer in range there.
+    /// Zero means "you have no talents to reset" (vmangos `SkillHandler.cpp:52`).
     pub trainer: u64,
-    /// What the reset costs, in copper — `Player::GetResetTalentsCost()`, which climbs with every
-    /// reset (the dialog's money frame, and the line "The cost will increase each time you do it").
+    /// Cost in copper, climbing with every reset (`Player::GetResetTalentsCost`).
     pub cost: u32,
 }
 
-/// Read the inbound `MSG_TALENT_WIPE_CONFIRM`: trainer guid u64 · cost u32 (`Skill.cpp:19-23`).
+/// Read the inbound `MSG_TALENT_WIPE_CONFIRM`: `u64 trainer, u32 cost` (`Skill.cpp:19-23`).
 pub(super) fn read_talent_wipe_confirm(r: &mut impl Read) -> io::Result<TalentWipeConfirm> {
     Ok(TalentWipeConfirm {
         trainer: read_u64_le(r)?,
@@ -104,35 +81,28 @@ pub(super) fn read_talent_wipe_confirm(r: &mut impl Read) -> io::Result<TalentWi
     })
 }
 
-/// Body of the **outbound** `MSG_TALENT_WIPE_CONFIRM` — the `CONFIRM_TALENT_WIPE` dialog's Accept
-/// (vmangos `WorldPackets::Skill::TalentWipeConfirm`, `Skill.cpp:14-17`: one guid, no cost). The
-/// guid is the one the question arrived with; the real client sends its own latched copy
-/// (`0xc4d7a0`, wow-re `talent-api.md`), which is the same number. Decision 1580.
+/// Body of the outbound `MSG_TALENT_WIPE_CONFIRM`, the `CONFIRM_TALENT_WIPE` Accept: the trainer
+/// guid alone (vmangos `Skill.cpp:14-17`), as the reference latches it at `0xc4d7a0`.
 pub fn talent_wipe_confirm(trainer_guid: u64) -> Vec<u8> {
     trainer_guid.to_le_bytes().to_vec()
 }
 
-/// One decoded `SMSG_LEVELUP_INFO` — our own ding, self-addressed only (vmangos
-/// `WorldPackets::Misc::LevelUpInfo`, `Misc.h:793-802` + `Misc.cpp:524-532`; filled by
-/// `Player::GiveLevel`, Player.cpp:3210-3218, and sent straight to the leveling session — no
-/// guid). Decision 0304.
+/// `SMSG_LEVELUP_INFO`: our own level-up, sent only to us with no guid (`Player.cpp:3210-3218`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LevelUpInfo {
     /// The level just reached.
     pub level: u32,
     /// Hit points gained.
     pub health: u32,
-    /// Power gains indexed mana, rage, focus, energy, happiness. The 1.12 server fills mana (or
-    /// zero for non-mana classes) and leaves the rest zero; `powers[0]` is the reference chat
-    /// line's mana arg.
+    /// Power gains: mana, rage, focus, energy, happiness. The server fills only mana, which is
+    /// the reference chat line's mana argument.
     pub powers: [u32; 5],
-    /// Stat gains indexed str, agi, stam, int, spirit — the reference chat's `SPELL_STAT0..4`
-    /// order, one line per positive entry.
+    /// Stat gains in `SPELL_STAT0..4` order (str, agi, stam, int, spirit), one chat line per
+    /// positive entry.
     pub stats: [u32; 5],
 }
 
-/// Read `SMSG_LEVELUP_INFO`: level u32 · healthGain u32 · powerGains u32×5 · statGains u32×5
-/// (48 bytes, `Misc.cpp:524-532`).
+/// Read `SMSG_LEVELUP_INFO`: `u32` level, health, 5 powers, 5 stats (`Misc.cpp:524-532`).
 pub(super) fn read_level_up_info(r: &mut impl Read) -> io::Result<LevelUpInfo> {
     let level = read_u32_le(r)?;
     let health = read_u32_le(r)?;
@@ -156,8 +126,6 @@ pub(super) fn read_level_up_info(r: &mut impl Read) -> io::Result<LevelUpInfo> {
 mod tests {
     use super::*;
 
-    /// The respec pair, both directions: the question carries guid + cost, the answer carries the
-    /// guid alone. Asymmetric bodies on ONE opcode is the whole reason this is an `MSG_`.
     #[test]
     fn the_talent_wipe_pair_round_trips() {
         let trainer: u64 = 0xF130_0000_0000_2A01;
@@ -173,9 +141,6 @@ mod tests {
         assert_eq!(talent_wipe_confirm(trainer), trainer.to_le_bytes().to_vec());
     }
 
-    /// vmangos's "you have no talents to reset" reply — guid 0, and a cost that is still filled in.
-    /// It parses; what to DO with it is the app's call (decision 1580: there is no trainer to ask
-    /// about, so nothing goes on screen).
     #[test]
     fn a_zero_trainer_is_a_parseable_refusal() {
         let mut body = 0u64.to_le_bytes().to_vec();
diff --git a/crates/benilla-protocol/src/messages/pvp.rs b/crates/benilla-protocol/src/messages/pvp.rs
index 07324082..860184a1 100644
--- a/crates/benilla-protocol/src/messages/pvp.rs
+++ b/crates/benilla-protocol/src/messages/pvp.rs
@@ -1,68 +1,35 @@
-//! The two honor-system wire messages (decision 1512): the inspect-honor request/reply pair and
-//! the honor-gain credit. Every shape below is VERIFIED against vmangos source (file:line cites
-//! per item); the goldens are hand-built against the server's own `AppendBodyTo` order.
-//!
-//! The *durable* honor state is not here — it rides the player descriptor, eleven PRIVATE fields
-//! plus the PUBLIC current-rank byte ([`crate::messages::ObjectFields::player_pvp_rank`] and
-//! friends). These two packets cover exactly what the descriptor cannot: **somebody else's**
-//! honor stats (which never stream to us), and the *moment* a kill pays out.
-//!
-//! Not modelled here (known siblings, VERIFIED present in vmangos `Opcodes_1_12_1.h`): the
-//! battleground family — `MSG_PVP_LOG_DATA` (736), `CMSG`/`SMSG_BATTLEFIELD_LIST` (572/573) and
-//! `…_STATUS` (723/724) — which 0208/0631 defer wholesale, and `SMSG_ZONE_UNDER_ATTACK` (596), a
-//! world broadcast rather than an honor message.
+//! The honor wire messages: the inspect-honor request/reply pair and the honor-gain credit.
+//! Durable honor state rides the player descriptor; these carry what it cannot, another player's
+//! stats and the moment a kill pays out.
 
 use std::io;
 
 use crate::wire::{read_i32_le, read_u16_le, read_u32_le, read_u64_le, read_u8};
 
-/// Another player's honor stats — the `MSG_INSPECT_HONOR_STATS` **reply** (opcode `0x2D6`/726,
-/// VERIFIED vmangos `Opcodes_1_12_1.h`; already named in `opcode_names`). A 50-byte body, all
-/// little-endian with no padding, in the exact order
-/// `WorldPackets::Misc::InspectHonorStatsResponse::AppendBodyTo` writes it
-/// (`Server/Packets/Misc.cpp:301-325`). Every `#if SUPPORTED_CLIENT_BUILD >= CLIENT_BUILD_1_6_1`
-/// block in that function is live for build 5875, so all three conditional members are present.
-///
-/// This exists because the honor descriptor fields are PRIVATE: nothing about a *foreign* player's
-/// kills, honor or progress bar is on the wire until we ask. The one exception is their current
-/// rank, which streams publicly in `PLAYER_BYTES_3` and so is **not** in this packet —
-/// [`crate::messages::ObjectFields::player_pvp_rank`] answers it off the target's own descriptor.
-///
-/// The server builds every value straight out of the target's descriptor
-/// (`Handlers/MiscHandler.cpp:962-1010`), so these fields are the inspected player's own
-/// `PLAYER_FIELD_*` honor block, re-serialized — with two shape differences worth knowing:
-/// `sessionKills` arrives as the raw packed dword rather than a split pair, and the three weekly
-/// HK counts arrive as bare `u16`s with a separate (dead) dishonorable slot beside each.
+/// Another player's honor stats, the `MSG_INSPECT_HONOR_STATS` reply (opcode 726): 50 bytes in
+/// vmangos `Misc.cpp:301-325` order, from the target's `PLAYER_FIELD_*` honor block. Their
+/// current rank is not here; it streams publicly in `PLAYER_BYTES_3`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct InspectHonorStats {
-    /// Whose stats these are — echoed from our request (`MiscHandler.cpp:977`). The reply carries
-    /// no error shape at all: the server simply does not answer when the target is missing, out of
-    /// `INSPECT_DISTANCE` (10 yd), or a valid attack target, so a silent non-reply is the refusal.
+    /// Echoed from the request. There is no error reply: a missing, distant (10 yd) or hostile
+    /// target gets no answer at all (`MiscHandler.cpp:977`).
     pub player_guid: u64,
-    /// The target's **highest lifetime** honor rank (`GetHighestRank().rank`,
-    /// `MiscHandler.cpp:985`) — the *internal* rank 0..18, the same domain as
-    /// [`crate::messages::ObjectFields::player_honor_rank`], NOT the visual number the UI draws.
-    /// Their *current* rank is the PUBLIC descriptor byte, not this.
+    /// The highest lifetime rank (`MiscHandler.cpp:985`), internal 0..18 like
+    /// [`crate::messages::ObjectFields::player_honor_rank`], not the visual number.
     pub highest_rank: u8,
-    /// Today's kills as the raw packed `PLAYER_FIELD_SESSION_KILLS` dword — low `u16` honorable,
-    /// high `u16` dishonorable (`MiscHandler.cpp:988` reads the whole field with
-    /// `GetUInt32Value`). Split with [`InspectHonorStats::session_kills`].
+    /// Today's kills, the packed `PLAYER_FIELD_SESSION_KILLS` dword (`MiscHandler.cpp:988`).
     pub session_kills: u32,
-    /// Yesterday's honorable kills (`GetUInt16Value(PLAYER_FIELD_YESTERDAY_KILLS, 0)`).
+    /// Yesterday's honorable kills, the low half of `PLAYER_FIELD_YESTERDAY_KILLS`.
     pub yesterday_hk: u16,
-    /// Written `0` by vmangos (`MiscHandler.cpp:994`, comment *"Unknown (deprecated, yesterday
-    /// dishonourable?)"*). Decoded and carried rather than skipped: whether the real client reads
-    /// these three slots at all is a question currently out with an RE orchestrator in
-    /// `wow-5875-re`, and a field we decode and ignore is honest where a silently-skipped one
-    /// would be a landmine if the verdict comes back "it reads them".
+    /// Always 0 from vmangos (`MiscHandler.cpp:994`); decoded, not skipped.
     pub unknown_old1: u16,
     /// Last week's honorable kills.
     pub last_week_hk: u16,
-    /// Written `0` by vmangos — see [`InspectHonorStats::unknown_old1`].
+    /// Always 0 from vmangos.
     pub unknown_old2: u16,
-    /// This week's honorable kills (a 1.6.0 addition; live for 5875).
+    /// This week's honorable kills.
     pub this_week_hk: u16,
-    /// Written `0` by vmangos — see [`InspectHonorStats::unknown_old1`].
+    /// Always 0 from vmangos.
     pub unknown_old3: u16,
     /// Lifetime honorable kills (`PLAYER_FIELD_LIFETIME_HONORBALE_KILLS`, vmangos's spelling).
     pub lifetime_hk: u32,
@@ -72,35 +39,24 @@ pub struct InspectHonorStats {
     pub yesterday_honor: u32,
     /// Last week's honor points.
     pub last_week_honor: u32,
-    /// This week's honor points (a 1.6.0 addition; live for 5875).
+    /// This week's honor points.
     pub this_week_honor: u32,
-    /// Last week's **standing** — the numeric ladder position, not a rank
-    /// (`PLAYER_FIELD_LAST_WEEK_RANK`; `0` = unranked that week).
+    /// Last week's standing, the ladder position and not a rank; 0 if unranked that week.
     pub last_week_rank: u32,
-    /// The rank progress bar, `0..255` **within the target's current rank** (a 1.6.0 addition;
-    /// live for 5875). See [`crate::messages::ObjectFields::player_honor_rank_bar`] for the
-    /// server's computation and the negative-rank wrap.
+    /// Progress within the target's current rank, 0..255, computed as
+    /// [`crate::messages::ObjectFields::player_honor_rank_bar`] is.
     pub rank_bar: u8,
 }
 
 impl InspectHonorStats {
-    /// [`Self::session_kills`] split into `(honorable, dishonorable)` — the `TWO_SHORT` packing
-    /// the descriptor field uses (low half, then high half). The wire carries the dword whole
-    /// here, so unlike the descriptor accessor this split is ours to do.
+    /// The packed field split into `(honorable, dishonorable)`, low half then high half.
     pub fn session_kills(&self) -> (u16, u16) {
         (self.session_kills as u16, (self.session_kills >> 16) as u16)
     }
 }
 
-/// Read the `MSG_INSPECT_HONOR_STATS` **reply** (see [`InspectHonorStats`]): 50 bytes in
-/// `AppendBodyTo` order. A short body errors (`UnexpectedEof`) rather than yielding a
-/// half-populated struct.
-///
-/// The opcode is an **`MSG_`**: the same number 0x2D6 carries our request *and* the server's
-/// reply, and the two bodies are different shapes (8 bytes vs 50). Nothing has to disambiguate
-/// them, because direction does it: [`super::parse_server`] is fed only by the world *reader*, so
-/// every 0x2D6 body it ever sees is a reply. Our own request never passes through here — it is
-/// built by [`inspect_honor_stats`] and handed straight to the writer.
+/// Read the `MSG_INSPECT_HONOR_STATS` reply. Our 8-byte request shares the opcode, but only
+/// server packets reach this reader.
 pub(super) fn read_inspect_honor_stats(r: &mut &[u8]) -> io::Result<InspectHonorStats> {
     Ok(InspectHonorStats {
         player_guid: read_u64_le(r)?,
@@ -122,66 +78,30 @@ pub(super) fn read_inspect_honor_stats(r: &mut &[u8]) -> io::Result<InspectHonor
     })
 }
 
-/// Body of the `MSG_INSPECT_HONOR_STATS` **request**: the inspected player's full 8-byte GUID and
-/// nothing else (VERIFIED vmangos `WorldPackets::Misc::InspectHonorStats::ReadFromWorldPacket`,
-/// `Server/Packets/Misc.cpp:93-96` — `recv_data >> guid`, a raw `uint64`, not a packed guid).
-///
-/// Server gates (`MiscHandler.cpp:962-972`) are the same three `CMSG_INSPECT` applies: the target
-/// must be an online player, within `INSPECT_DISTANCE` (10.0), and not a valid attack target. Each
-/// refusal is a silent `return` — there is no error reply, so a consumer must not block on an
-/// answer that may never come. Unlike `CMSG_INSPECT`, this handler does **not** set our selection
-/// (`HandleInspectOpcode` opens with `SetSelectionGuid`; this one does not), which is why the send
-/// lives in `world::writer::pvp` rather than `writer::selection`.
+/// Body of the `MSG_INSPECT_HONOR_STATS` request: the raw, unpacked `u64` guid (vmangos
+/// `Misc.cpp:93-96`). A refused request gets no answer, and unlike `CMSG_INSPECT` it does not
+/// set our selection (`MiscHandler.cpp:962-972`).
 pub fn inspect_honor_stats(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// An honor payout (`SMSG_PVP_CREDIT`, opcode `0x28C`/652 — VERIFIED vmangos
-/// `Opcodes_1_12_1.h`; already named in `opcode_names`). A 16-byte body in the order
-/// `WorldPackets::Misc::PvpCredit::AppendBodyTo` writes it (`Server/Packets/Misc.cpp:376-381`),
-/// sent from `HonorMgr::SendPVPCredit` (`HonorMgr.cpp:1061-1093`) on every honor row the server
-/// books — **including a dishonorable one**, which is why [`PvpCredit::honor`] is signed.
-///
-/// This is the *only* notice of a specific payout: the descriptor's contribution fields move too,
-/// but they are running totals with no attribution. The chat line and the floating combat text
-/// both have to come from here.
+/// `SMSG_PVP_CREDIT` (opcode 652): one honor payout, dishonorable ones included (vmangos
+/// `HonorMgr.cpp:1061-1093`). The descriptor holds only totals; this is the only per-payout notice.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct PvpCredit {
-    /// Honor points, truncated to an integer server-side (`static_cast<int32>(honor)`).
-    ///
-    /// **Signed, and genuinely negative for a dishonorable kill**: `HonorMgr::Add` computes
-    /// `honor = (type == DISHONORABLE) ? -cp : cp` (`HonorMgr.cpp:807`) and hands *that* to
-    /// `SendPVPCredit` (`HonorMgr.cpp:833`). A `u32` here would read a DK penalty as ~4 billion
-    /// honor.
+    /// Honor, truncated server-side; negative for a dishonorable kill (`HonorMgr.cpp:807`).
     pub honor: i32,
-    /// Who we killed. **`0` means there is no victim** — vmangos only fills the guid inside
-    /// `if (victim)` (`HonorMgr.cpp:1069-1071`), and it passes the *pre-fallback* `realSource`, so
-    /// an honor row booked with no source at all arrives with a zero guid. The UI needs a
-    /// victim-less phrasing rather than resolving a name for guid 0.
+    /// Who we killed; 0 for an honor row with no source (`HonorMgr.cpp:1069-1071`), which
+    /// needs a victim-less phrasing rather than a name lookup.
     pub victim_guid: u64,
-    /// The victim's **internal** rank — the same `[0..18]` domain as the descriptor's rank bytes
-    /// and [`InspectHonorStats::highest_rank`], and therefore a direct index into the
-    /// `PVP_RANK_<rank>_<team>` GlobalStrings. NOT the visual rank the badge texture uses; do the
-    /// `internal > 4 ? internal - 4 : -internal` conversion (`HonorMgr.cpp:991`) at the display
-    /// edge if a badge is wanted, and do not do it twice.
-    ///
-    /// VERIFIED `HonorMgr::SendPVPCredit` (`HonorMgr.cpp:1078-1089`): a **player** victim sends
-    /// `GetHonorMgr().GetRank().rank`, a **creature** victim sends `19` iff it is a racial leader
-    /// and otherwise leaves the field at its `0` default.
-    ///
-    /// One quirk to observe rather than imitate: for a player victim vmangos **floors the value at
-    /// 5** (`if (!rank) rank = (HONOR_RANK_COUNT - POSITIVE_HONOR_RANK_COUNT) + 1`, i.e. "at least
-    /// Scout"), with the comment *"Never display just 'HK:' without rank name"*. That is the
-    /// server working around a client that would otherwise print an empty rank name — it is
-    /// **server behaviour we receive**, not a rule we should re-implement: we render whatever
-    /// number arrives, and an unranked-victim `0` from some other server must still come out
-    /// sanely at the display edge.
-    ///
-    /// `i32` because that is the wire type; nothing vmangos sends here is negative.
+    /// The victim's internal rank (0..18), indexing the `PVP_RANK_<rank>_<team>` strings; the
+    /// badge's visual rank is `internal > 4 ? internal - 4 : -internal` (`HonorMgr.cpp:991`).
+    /// A creature sends 19 if a racial leader, else 0; vmangos floors a player victim at 5
+    /// (`HonorMgr.cpp:1078-1089`), a server fallback rather than a rule to re-implement.
     pub victim_rank: i32,
 }
 
-/// Read `SMSG_PVP_CREDIT` (see [`PvpCredit`]): `i32 honor`, `u64 victimGuid`, `i32 victimRank`.
+/// Read `SMSG_PVP_CREDIT`: `i32 honor, u64 victimGuid, i32 victimRank`.
 pub(super) fn read_pvp_credit(r: &mut &[u8]) -> io::Result<PvpCredit> {
     Ok(PvpCredit {
         honor: read_i32_le(r)?,
@@ -194,9 +114,6 @@ pub(super) fn read_pvp_credit(r: &mut &[u8]) -> io::Result<PvpCredit> {
 mod tests {
     use super::*;
 
-    /// The 50-byte reply, hand-built in `InspectHonorStatsResponse::AppendBodyTo` order with the
-    /// field boundaries commented — a level-60 target with a rank-11 lifetime best, kills in every
-    /// bucket, and a bar three-quarters of the way through the current rank.
     #[test]
     fn inspect_honor_stats_golden() {
         #[rustfmt::skip]
@@ -205,11 +122,11 @@ mod tests {
             0xB3, 0x2A, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00,
             // [8] u8 highestRank = 11 (internal)
             0x0B,
-            // [9..13) u32 sessionKills = 0x0002_0011 — 17 HK low, 2 DK high
+            // [9..13) u32 sessionKills = 0x0002_0011: 17 HK low, 2 DK high
             0x11, 0x00, 0x02, 0x00,
             // [13..15) u16 yesterdayHK = 41
             0x29, 0x00,
-            // [15..17) u16 unknownOld1 = 0 (server always writes 0)
+            // [15..17) u16 unknownOld1 = 0
             0x00, 0x00,
             // [17..19) u16 lastWeekHK = 420
             0xA4, 0x01,
@@ -229,7 +146,7 @@ mod tests {
             0xEF, 0x20, 0x00, 0x00,
             // [41..45) u32 thisWeekHonor = 1250
             0xE2, 0x04, 0x00, 0x00,
-            // [45..49) u32 lastWeekRank = 57 (the STANDING)
+            // [45..49) u32 lastWeekRank = 57 (the standing)
             0x39, 0x00, 0x00, 0x00,
             // [49] u8 rankBar = 191
             0xBF,
@@ -258,13 +175,10 @@ mod tests {
                 rank_bar: 191,
             }
         );
-        // The packed today-kills dword splits the same way the descriptor's TWO_SHORT does.
         assert_eq!(stats.session_kills(), (17, 2));
     }
 
-    /// A truncated reply must ERROR, not panic and not yield a half-populated struct — the wire is
-    /// hostile input. 49 bytes is the nastiest case: everything but the trailing `rankBar`, which
-    /// is exactly what a pre-1.6.1 server would send.
+    /// 49 bytes is everything but the trailing `rankBar`, which is what a pre-1.6.1 server sends.
     #[test]
     fn inspect_honor_stats_truncated_body_errors() {
         let full = [0u8; 50];
@@ -275,25 +189,21 @@ mod tests {
                 "a {len}-byte inspect-honor body must be rejected"
             );
         }
-        // …and the full length still parses, so the loop above is testing truncation and not a
-        // decoder that rejects everything.
+        // The full length parses, so the loop above really tests truncation.
         let mut r = full.as_slice();
         assert!(read_inspect_honor_stats(&mut r).is_ok());
     }
 
-    /// The request is the bare 8-byte guid — byte-exact against
-    /// `InspectHonorStats::ReadFromWorldPacket`'s single `recv_data >> guid`.
     #[test]
     fn inspect_honor_stats_request_golden() {
         assert_eq!(
             inspect_honor_stats(0x0000_0001_0000_2AB3),
             vec![0xB3, 0x2A, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00],
         );
-        // No sentinel handling: a zero guid is encoded as-is (the server answers by not answering).
+        // A zero guid is encoded as-is.
         assert_eq!(inspect_honor_stats(0), vec![0u8; 8]);
     }
 
-    /// The 16-byte credit body, hand-built in `PvpCredit::AppendBodyTo` order.
     #[test]
     fn pvp_credit_golden() {
         #[rustfmt::skip]
@@ -302,7 +212,7 @@ mod tests {
             0x8F, 0x00, 0x00, 0x00,
             // [4..12) u64 victimGuid = 0x0000_0001_0000_2AB3
             0xB3, 0x2A, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00,
-            // [12..16) i32 victimRank = 11 (INTERNAL rank — the PVP_RANK_11_<team> key)
+            // [12..16) i32 victimRank = 11 (internal rank, the PVP_RANK_11_<team> key)
             0x0B, 0x00, 0x00, 0x00,
         ];
         let mut r = body.as_slice();
@@ -318,9 +228,6 @@ mod tests {
         );
     }
 
-    /// A **dishonorable** kill rides the same packet with a negative `honor`
-    /// (`HonorMgr.cpp:807`, `honor = -cp`) — the reason the field is `i32`. Decoded as `u32` this
-    /// body would read as 4 294 967 291 honor.
     #[test]
     fn pvp_credit_dishonorable_kill_is_negative_honor() {
         let mut body = Vec::with_capacity(16);
@@ -334,10 +241,6 @@ mod tests {
         assert_eq!(credit.victim_rank, 5);
     }
 
-    /// The victim-less shape the UI has to phrase differently: vmangos fills the guid only inside
-    /// `if (victim)` and passes the pre-fallback `realSource`, so an honor row with no source
-    /// arrives as a zero guid with the rank left at its `0` default (which is also what a
-    /// non-racial-leader creature victim sends).
     #[test]
     fn pvp_credit_zero_guid_means_no_victim() {
         let mut body = Vec::with_capacity(16);
@@ -351,7 +254,6 @@ mod tests {
         assert_eq!(credit.victim_rank, 0);
     }
 
-    /// A truncated credit body errors rather than panicking.
     #[test]
     fn pvp_credit_truncated_body_errors() {
         let full = [0u8; 16];
diff --git a/crates/benilla-protocol/src/messages/quest/giver.rs b/crates/benilla-protocol/src/messages/quest/giver.rs
index 08ece1aa..56edfa86 100644
--- a/crates/benilla-protocol/src/messages/quest/giver.rs
+++ b/crates/benilla-protocol/src/messages/quest/giver.rs
@@ -1,34 +1,15 @@
-//! `SMSG_QUESTGIVER_*` / `CMSG_QUESTGIVER_*` — the "accept/turn-in a quest at an NPC" family
-//! (opcodes 386-402, vmangos `Opcodes_1_12_1.h`, VERIFIED). This is the *giver panel* slice
-//! (decision 0088): the four questgiver windows carry their own text, so it needs none of the full
-//! `SMSG_QUEST_QUERY_RESPONSE` template — that lives in the sibling [`super::log`] slice. CMSG
-//! bodies from vmangos `Server/Packets/Quest.cpp:6-78`; SMSG layouts from the same file's
-//! `AppendBodyTo` writers (line citations inline).
-//!
-//! Wire traps this parser is written against the *byte stream* to survive (never the C++ control
-//! flow):
-//! - **QUEST_LIST icon is a `u32`** — `QuestListEntry`'s `icon` field is `uint32` (`Quest.h:270`),
-//!   not the `u8` the gossip-menu option icon uses.
-//! - **OFFER_REWARD emotes are `{delay, emote}`** — reversed from DETAILS' `{emote, delay}`
-//!   (`Quest.cpp:271` vs `:308-309`).
-//! - **DETAILS rewards parse is uniform across the HIDDEN_REWARDS fork** — the hidden branch writes
-//!   three `u32` zeros (`Quest.cpp:235-237`), which a count-prefixed reader consumes as
-//!   `choiceCount=0, rewCount=0, money=0`, identical in shape to an empty rewards block. The parser
-//!   can't see the quest flag, and it doesn't need to.
+//! The questgiver family (opcodes 386-402): the NPC accept, progress and reward panels, which
+//! carry their own text. Layouts from vmangos `Server/Packets/Quest.cpp`.
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_cstring, read_i32_le, read_u32_le, read_u64_le, read_u8};
 
-/// `QUEST_EMOTE_COUNT` (vmangos `QuestDef.h:43`) — DETAILS always writes exactly this many emote
-/// pairs; OFFER_REWARD writes a variable count (0..=4), so only DETAILS relies on the constant.
+/// vmangos `QUEST_EMOTE_COUNT` (`QuestDef.h:43`): the emote pairs DETAILS always writes.
 pub const QUEST_EMOTE_COUNT: u32 = 4;
 
-/// `DIALOG_STATUS_*` (vmangos `QuestDef.h:120-129`) — the questgiver dialog status a
-/// `SMSG_QUESTGIVER_STATUS` carries per NPC guid, and the per-quest `icon` in a `QUEST_LIST` /
-/// gossip quest entry. Drives the `!`/`?` over the NPC head (a world-marker concern, out of the
-/// panel slice — parsed + stored per guid now, rendered later) and the greeting panel's
-/// active-vs-available split.
+/// vmangos `DIALOG_STATUS_*` (`QuestDef.h:120-129`): an NPC's `SMSG_QUESTGIVER_STATUS`, which
+/// drives the `!`/`?` over its head, and a quest row's `icon`.
 pub mod dialog_status {
     pub const NONE: u32 = 0;
     pub const UNAVAILABLE: u32 = 1;
@@ -40,10 +21,8 @@ pub mod dialog_status {
     pub const REWARD2: u32 = 7;
 }
 
-/// One reward/choice item on a questgiver panel (`{itemId u32, count u32, displayId u32}` triple,
-/// as written in DETAILS/OFFER_REWARD — vmangos `Quest.cpp:244-249` etc.). `display_id` →
-/// `ItemDisplayInfo.dbc` icon, exactly like a vendor row; a `0` id means the server had no template
-/// (writes a zero triple, `Quest.cpp:248-249`).
+/// One reward or choice item on a questgiver panel (vmangos `Quest.cpp:244-249`). `display_id`
+/// is an `ItemDisplayInfo.dbc` row; an all-zero triple means the server had no item template.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct QuestRewardItem {
     pub item_id: u32,
@@ -51,13 +30,10 @@ pub struct QuestRewardItem {
     pub display_id: u32,
 }
 
-/// One required item on the progress panel (`SMSG_QUESTGIVER_REQUEST_ITEMS`), same triple shape as
-/// [`QuestRewardItem`] (vmangos `Quest.cpp:376-381`).
+/// A required item on the progress panel, the same triple (vmangos `Quest.cpp:376-381`).
 pub type QuestRequiredItem = QuestRewardItem;
 
-/// One entry in a `SMSG_QUESTGIVER_QUEST_LIST` (the greeting panel's quest rows). `icon` is a
-/// [`dialog_status`] value (**`u32`** — `Quest.h:270`, the list-entry trap), `level` the quest's
-/// display level, `title` the row label.
+/// One greeting-panel quest row; `icon` is a [`dialog_status`] value, a `u32` (`Quest.h:270`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QuestListEntry {
     pub quest_id: u32,
@@ -76,9 +52,8 @@ pub struct QuestGiverList {
     pub quests: Vec<QuestListEntry>,
 }
 
-/// `SMSG_QUESTGIVER_QUEST_DETAILS` (vmangos `Quest.cpp:205-273`): the accept panel — full quest
-/// text + the rewards on offer. `money` is the reward money (`GetRewOrReqMoney`, `i32`; negative on
-/// a money-*sink* quest, which DETAILS shows as a required cost — rare, kept signed).
+/// `SMSG_QUESTGIVER_QUEST_DETAILS` (vmangos `Quest.cpp:205-273`): the accept panel. `money` is
+/// signed, negative for a quest that costs money (`GetRewOrReqMoney`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QuestDetails {
     pub npc: u64,
@@ -93,9 +68,7 @@ pub struct QuestDetails {
     pub reward_spell: u32,
 }
 
-/// `SMSG_QUESTGIVER_OFFER_REWARD` (vmangos `Quest.cpp:275-339`): the reward panel — the turn-in
-/// text + the rewards to grant. Note the emote pairs are `{delay, emote}` (reversed vs DETAILS) and
-/// are consumed for alignment only.
+/// `SMSG_QUESTGIVER_OFFER_REWARD` (vmangos `Quest.cpp:275-339`): the reward panel.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QuestOfferReward {
     pub npc: u64,
@@ -110,10 +83,8 @@ pub struct QuestOfferReward {
     pub reward_spell: u32,
 }
 
-/// `SMSG_QUESTGIVER_REQUEST_ITEMS` (vmangos `Quest.cpp:341-391`): the progress panel — the "bring
-/// me these" text + required items/money, and the four completion flags the client ANDs to enable
-/// the Continue button. `is_complete` is derived from the second flag word (`0x03` complete /
-/// `0x00` not — `Quest.cpp:388`), the only place the completability reaches the client.
+/// `SMSG_QUESTGIVER_REQUEST_ITEMS` (vmangos `Quest.cpp:341-391`): the progress panel. The client
+/// ANDs four flag words to enable Continue; `is_complete` comes from the second (`Quest.cpp:388`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QuestRequestItems {
     pub npc: u64,
@@ -127,9 +98,8 @@ pub struct QuestRequestItems {
     pub is_complete: bool,
 }
 
-/// `SMSG_QUESTGIVER_QUEST_COMPLETE` (vmangos `Quest.cpp:96-108`): the turn-in result — the XP +
-/// money granted and the fixed items handed over. The reward *item* rows here carry only
-/// `{itemId, count}` (no display id — the client already knows them from the offer panel).
+/// `SMSG_QUESTGIVER_QUEST_COMPLETE` (vmangos `Quest.cpp:96-108`): the XP, money and fixed items
+/// granted; the item rows carry no display id.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QuestComplete {
     pub quest_id: u32,
@@ -138,52 +108,46 @@ pub struct QuestComplete {
     pub items: Vec<(u32, u32)>,
 }
 
-// ── CMSG encoders (all trivial, readers at vmangos `Quest.cpp:6-50`) ──────────────────────────────
+// ── CMSG encoders (vmangos `Quest.cpp:6-50`) ─────────────────────────────────────────────────────
 
-/// Body of `CMSG_QUESTGIVER_STATUS_QUERY` (`Quest.cpp:11-14`): one `u64` NPC guid. Answered by
-/// `SMSG_QUESTGIVER_STATUS`.
+/// Body of `CMSG_QUESTGIVER_STATUS_QUERY` (`Quest.cpp:11-14`): the `u64` NPC guid.
 pub fn questgiver_status_query(npc: u64) -> Vec<u8> {
     npc.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_QUESTGIVER_HELLO` (`Quest.cpp:16-19`): one `u64` NPC guid. The same
-/// `SendPreparedGossip` path as `CMSG_GOSSIP_HELLO` (vmangos `QuestHandler.cpp:103`), so benilla's
-/// interact route can keep sending gossip-hello; this opener exists for completeness/parity.
+/// Body of `CMSG_QUESTGIVER_HELLO` (`Quest.cpp:16-19`): the NPC guid. The server answers it like
+/// `CMSG_GOSSIP_HELLO`, through `SendPreparedGossip` (`QuestHandler.cpp:103`).
 pub fn questgiver_hello(npc: u64) -> Vec<u8> {
     npc.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_QUESTGIVER_QUERY_QUEST` (`Quest.cpp:27-31`): `u64 guid, u32 quest`. Answered by
-/// `SMSG_QUESTGIVER_QUEST_DETAILS` (vmangos `QuestHandler.cpp:224`, always — this is "look at an
-/// available quest"). The click a greeting/gossip quest row makes.
+/// Body of `CMSG_QUESTGIVER_QUERY_QUEST` (`Quest.cpp:27-31`): `u64 guid, u32 quest`, sent by a
+/// quest row's click and always answered with the details panel (`QuestHandler.cpp:224`).
 pub fn questgiver_query_quest(npc: u64, quest: u32) -> Vec<u8> {
     guid_quest(npc, quest)
 }
 
-/// Body of `CMSG_QUESTGIVER_ACCEPT_QUEST` (`Quest.cpp:21-25`): `u64 guid, u32 quest`. Adds the quest
-/// to the log, then the server closes the gossip window (`SMSG_GOSSIP_COMPLETE`).
+/// Body of `CMSG_QUESTGIVER_ACCEPT_QUEST` (`Quest.cpp:21-25`): `u64 guid, u32 quest`. The server
+/// logs the quest, then closes the gossip window (`SMSG_GOSSIP_COMPLETE`).
 pub fn questgiver_accept_quest(npc: u64, quest: u32) -> Vec<u8> {
     guid_quest(npc, quest)
 }
 
-/// Body of `CMSG_QUESTGIVER_COMPLETE_QUEST` (`Quest.cpp:46-50`): `u64 guid, u32 quest`. Asks the
-/// server to show the turn-in **progress** panel (`SMSG_QUESTGIVER_REQUEST_ITEMS`, vmangos
-/// `QuestHandler.cpp:383-397`) — the alternate entry from a quest-log completable quest.
+/// Body of `CMSG_QUESTGIVER_COMPLETE_QUEST` (`Quest.cpp:46-50`): `u64 guid, u32 quest`, answered
+/// with the progress panel (`QuestHandler.cpp:383-397`).
 pub fn questgiver_complete_quest(npc: u64, quest: u32) -> Vec<u8> {
     guid_quest(npc, quest)
 }
 
-/// Body of `CMSG_QUESTGIVER_REQUEST_REWARD` (`Quest.cpp:40-44`): `u64 guid, u32 quest`. The progress
-/// panel's Continue button — advances to the **reward** panel (`SMSG_QUESTGIVER_OFFER_REWARD`,
-/// vmangos `QuestHandler.cpp:286-312`, which first `CompleteQuest`s if it can).
+/// Body of `CMSG_QUESTGIVER_REQUEST_REWARD` (`Quest.cpp:40-44`): `u64 guid, u32 quest`, the
+/// progress panel's Continue, answered with the reward panel (`QuestHandler.cpp:286-312`).
 pub fn questgiver_request_reward(npc: u64, quest: u32) -> Vec<u8> {
     guid_quest(npc, quest)
 }
 
-/// Body of `CMSG_QUESTGIVER_CHOOSE_REWARD` (`Quest.cpp:33-38`): `u64 guid, u32 quest, u32 reward`.
-/// `reward` is the **index** into the quest's choice items (0-based; ignored when the quest has no
-/// choice rewards — pass 0). The reward panel's Complete button — grants the reward and answers
-/// `SMSG_QUESTGIVER_QUEST_COMPLETE` (vmangos `QuestHandler.cpp:239-284`).
+/// Body of `CMSG_QUESTGIVER_CHOOSE_REWARD` (`Quest.cpp:33-38`): `u64 guid, u32 quest, u32 reward`,
+/// `reward` a 0-based choice index (0 with no choice). Sent by the reward panel's Complete and
+/// answered with `SMSG_QUESTGIVER_QUEST_COMPLETE` (`QuestHandler.cpp:239-284`).
 pub fn questgiver_choose_reward(npc: u64, quest: u32, reward: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&npc.to_le_bytes());
@@ -192,7 +156,6 @@ pub fn questgiver_choose_reward(npc: u64, quest: u32, reward: u32) -> Vec<u8> {
     body
 }
 
-/// The shared `{u64 guid, u32 quest}` body of the five simple questgiver CMSGs.
 fn guid_quest(npc: u64, quest: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&npc.to_le_bytes());
@@ -200,10 +163,8 @@ fn guid_quest(npc: u64, quest: u32) -> Vec<u8> {
     body
 }
 
-// ── SMSG parsers ──────────────────────────────────────────────────────────────────────────────────
+// ── SMSG parsers ─────────────────────────────────────────────────────────────────────────────────
 
-/// Read a `{itemId u32, count u32, displayId u32}` reward/choice/required triple (the shape shared
-/// by DETAILS/OFFER_REWARD/REQUEST_ITEMS).
 fn read_item_triple(r: &mut &[u8]) -> io::Result<QuestRewardItem> {
     Ok(QuestRewardItem {
         item_id: read_u32_le(r)?,
@@ -212,11 +173,9 @@ fn read_item_triple(r: &mut &[u8]) -> io::Result<QuestRewardItem> {
     })
 }
 
-/// Read a count-prefixed run of item triples (`u32 count` then that many triples).
 fn read_item_block(r: &mut &[u8]) -> io::Result<Vec<QuestRewardItem>> {
     let count = read_u32_le(r)?;
-    // The wider of the two lists this reads: `QUEST_REWARD_CHOICES_COUNT` 6 (vmangos
-    // `QuestDef.h:39`; the fixed rewards are `QUEST_REWARDS_COUNT` 4).
+    // `QUEST_REWARD_CHOICES_COUNT` 6, the wider of the two lists (vmangos `QuestDef.h:39`).
     let mut items = Vec::with_capacity(capacity_hint(count, 6));
     for _ in 0..count {
         items.push(read_item_triple(r)?);
@@ -229,18 +188,16 @@ pub(in crate::messages) fn read_questgiver_status(r: &mut &[u8]) -> io::Result<(
     Ok((read_u64_le(r)?, read_u32_le(r)?))
 }
 
-/// Read `SMSG_QUESTGIVER_QUEST_LIST` (vmangos `Quest.cpp:159-203`): `u64 npcGuid, cstr greeting,
-/// u32 emoteDelay, u32 emote, u8 count`, then per quest `{u32 questId, u32 icon, u32 level, cstr
-/// title}`. Note the entry `icon` is a **`u32`** (the list-entry trap), unlike the gossip option's
-/// `u8` icon.
+/// Read `SMSG_QUESTGIVER_QUEST_LIST` (vmangos `Quest.cpp:159-203`): `u64 npc`, greeting,
+/// `u32 emoteDelay, u32 emote, u8 count`, then per quest `u32 id, u32 icon, u32 level`, title.
+/// The icon is a `u32` here, unlike a gossip option's `u8`.
 pub(in crate::messages) fn read_questgiver_quest_list(r: &mut &[u8]) -> io::Result<QuestGiverList> {
     let npc = read_u64_le(r)?;
     let greeting = read_cstring(r)?;
     let emote_delay = read_u32_le(r)?;
     let emote = read_u32_le(r)?;
     let count = read_u8(r)?;
-    // No server cap (the quest menu is a vector, `GossipDef.h:184`); `GOSSIP_MAX_MENU_ITEMS` 32
-    // (`GossipDef.h:32`) is the client's display limit.
+    // No server cap (`GossipDef.h:184`); `GOSSIP_MAX_MENU_ITEMS` 32 is the display limit.
     let mut quests = Vec::with_capacity(capacity_hint(count, 32));
     for _ in 0..count {
         quests.push(QuestListEntry {
@@ -259,12 +216,10 @@ pub(in crate::messages) fn read_questgiver_quest_list(r: &mut &[u8]) -> io::Resu
     })
 }
 
-/// Read `SMSG_QUESTGIVER_QUEST_DETAILS` (vmangos `Quest.cpp:205-273`): `u64 npcGuid, u32 questId,
-/// cstr title, cstr details, cstr objectives, u32 autoFinish`, then the count-prefixed choice block,
-/// the count-prefixed reward block, `i32 money`, `u32 rewSpell`, `u32 emoteCount (=4)` and that many
-/// `{u32 emote, u32 delay}` pairs (consumed for alignment). The HIDDEN_REWARDS fork writes three
-/// `u32` zeros in place of the two blocks + money, which this count-prefixed reader consumes
-/// identically to an empty rewards block (the uniform-parse trap).
+/// Read `SMSG_QUESTGIVER_QUEST_DETAILS` (vmangos `Quest.cpp:205-273`): npc, id, title, details,
+/// objectives, auto-finish, the choice and reward blocks, money, spell, then a count (always 4)
+/// of `{u32 emote, u32 delay}` pairs. A hidden-rewards quest writes three zeros for the blocks
+/// and money (`Quest.cpp:235-237`), which read as empty blocks.
 pub(in crate::messages) fn read_questgiver_quest_details(
     r: &mut &[u8],
 ) -> io::Result<QuestDetails> {
@@ -297,11 +252,9 @@ pub(in crate::messages) fn read_questgiver_quest_details(
     })
 }
 
-/// Read `SMSG_QUESTGIVER_OFFER_REWARD` (vmangos `Quest.cpp:275-339`): `u64 npcGuid, u32 questId,
-/// cstr title, cstr offerText, u32 autoFinish, u32 emoteCount` then that many `{u32 delay, u32
-/// emote}` pairs (**delay first** — reversed vs DETAILS), the choice block, the reward block, `i32
-/// money, u32 questFlags, u32 rewSpell` (the spell is guarded by build > 1.4.2 server-side, which
-/// 5875 satisfies — always present).
+/// Read `SMSG_QUESTGIVER_OFFER_REWARD` (vmangos `Quest.cpp:275-339`): npc, id, title, text,
+/// auto-finish, a counted run of `{u32 delay, u32 emote}` pairs (delay first, unlike DETAILS,
+/// `Quest.cpp:308-309`), the choice and reward blocks, money, quest flags, spell.
 pub(in crate::messages) fn read_questgiver_offer_reward(
     r: &mut &[u8],
 ) -> io::Result<QuestOfferReward> {
@@ -312,7 +265,7 @@ pub(in crate::messages) fn read_questgiver_offer_reward(
     let auto_finish = read_u32_le(r)?;
     let emote_count = read_u32_le(r)?;
     for _ in 0..emote_count {
-        let _delay = read_u32_le(r)?; // delay FIRST here (reversed vs DETAILS)
+        let _delay = read_u32_le(r)?; // delay first here, unlike DETAILS
         let _emote = read_u32_le(r)?;
     }
     let choices = read_item_block(r)?;
@@ -334,11 +287,9 @@ pub(in crate::messages) fn read_questgiver_offer_reward(
     })
 }
 
-/// Read `SMSG_QUESTGIVER_REQUEST_ITEMS` (vmangos `Quest.cpp:341-391`): `u64 npcGuid, u32 questId,
-/// cstr title, cstr requestText, u32 emoteDelay(0), u32 emote, u32 closeOnCancel, u32 requiredMoney,
-/// u32 reqCount` then that many `{u32 itemId, u32 count, u32 displayId}` triples, then four `u32`
-/// completion flags (`0x02, isComplete?0x03:0x00, 0x04, 0x08`). `is_complete` comes from the second
-/// flag word — the only completability signal on this wire.
+/// Read `SMSG_QUESTGIVER_REQUEST_ITEMS` (vmangos `Quest.cpp:341-391`): npc, id, title, text,
+/// `u32` emote delay, emote, close-on-cancel and money, the required items, then four flag words
+/// `0x02, complete ? 0x03 : 0x00, 0x04, 0x08`.
 pub(in crate::messages) fn read_questgiver_request_items(
     r: &mut &[u8],
 ) -> io::Result<QuestRequestItems> {
@@ -368,9 +319,8 @@ pub(in crate::messages) fn read_questgiver_request_items(
     })
 }
 
-/// Read `SMSG_QUESTGIVER_QUEST_COMPLETE` (vmangos `Quest.cpp:96-108`): `u32 questId, u32 unknown,
-/// u32 xp, u32 money, u32 itemCount` then that many `{u32 itemId, u32 count}` pairs (no display id
-/// on this wire).
+/// Read `SMSG_QUESTGIVER_QUEST_COMPLETE` (vmangos `Quest.cpp:96-108`): `u32` quest, unknown, xp,
+/// money and item count, then `{u32 itemId, u32 count}` pairs.
 pub(in crate::messages) fn read_questgiver_quest_complete(
     r: &mut &[u8],
 ) -> io::Result<QuestComplete> {
@@ -406,7 +356,7 @@ pub(in crate::messages) fn read_questgiver_quest_failed(r: &mut &[u8]) -> io::Re
 mod tests {
     use super::*;
 
-    // ── Small byte-buffer builders for the hand-built parse fixtures ──────────────────────────────
+    // ── Byte-buffer builders ─────────────────────────────────────────────────────────────────────
     fn push_u32(b: &mut Vec<u8>, v: u32) {
         b.extend_from_slice(&v.to_le_bytes());
     }
@@ -430,7 +380,6 @@ mod tests {
 
     #[test]
     fn cmsg_guid_only_bodies() {
-        // STATUS_QUERY and HELLO are both a lone u64 guid, little-endian.
         assert_eq!(
             questgiver_status_query(0x0102_0304_0506_0708),
             vec![0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01]
@@ -440,7 +389,6 @@ mod tests {
 
     #[test]
     fn cmsg_guid_quest_bodies() {
-        // QUERY/ACCEPT/COMPLETE/REQUEST_REWARD share the {u64 guid, u32 quest} body.
         let mut want = Vec::new();
         push_u64(&mut want, 0x42);
         push_u32(&mut want, 3);
@@ -452,7 +400,6 @@ mod tests {
 
     #[test]
     fn cmsg_choose_reward_body() {
-        // {u64 guid, u32 quest, u32 reward-index}.
         let mut want = Vec::new();
         push_u64(&mut want, 0x99);
         push_u32(&mut want, 40);
@@ -474,8 +421,7 @@ mod tests {
 
     #[test]
     fn quest_list_reads_u32_icon() {
-        // The list-entry `icon` is a u32 — exercise it by putting a value that would misalign the
-        // next field if read as a u8 (0x0000_0005). Two quests.
+        // Reading the `u32` icon as a `u8` would misalign every field after it.
         let mut b = Vec::new();
         push_u64(&mut b, 0xABCD);
         push_cstr(&mut b, "Greetings, hero.");
@@ -483,7 +429,7 @@ mod tests {
         push_u32(&mut b, 1); // emote
         b.push(2); // count (u8)
         push_u32(&mut b, 100); // questId
-        push_u32(&mut b, dialog_status::AVAILABLE); // icon (u32!)
+        push_u32(&mut b, dialog_status::AVAILABLE); // icon, a u32
         push_u32(&mut b, 3); // level
         push_cstr(&mut b, "A Threat Within");
         push_u32(&mut b, 200);
@@ -504,8 +450,6 @@ mod tests {
 
     #[test]
     fn details_rewards_block_is_uniform() {
-        // A quest with one choice + one fixed reward + money. The count-prefixed reader is the same
-        // shape the HIDDEN_REWARDS fork's three zeros parse as (choice 0, reward 0, money 0).
         let mut b = Vec::new();
         push_u64(&mut b, 0x42);
         push_u32(&mut b, 100); // questId
@@ -550,7 +494,6 @@ mod tests {
 
     #[test]
     fn details_hidden_rewards_fork_parses_as_empty() {
-        // The HIDDEN_REWARDS branch writes exactly three u32 zeros where the blocks + money go.
         let mut b = Vec::new();
         push_u64(&mut b, 0x42);
         push_u32(&mut b, 100);
@@ -574,10 +517,9 @@ mod tests {
         assert_eq!(d.reward_spell, 42);
     }
 
+    /// The pairs are read and discarded, so the check is that the fields after the run align.
     #[test]
-    fn offer_reward_emotes_are_delay_first() {
-        // OFFER_REWARD's emote pairs are {delay, emote} — the reverse of DETAILS. Encode a distinctive
-        // pair and prove the rest of the packet still aligns (choices/rewards/money/flags/spell land).
+    fn offer_reward_skips_its_counted_emote_pairs() {
         let mut b = Vec::new();
         push_u64(&mut b, 0x42);
         push_u32(&mut b, 100);
@@ -585,7 +527,7 @@ mod tests {
         push_cstr(&mut b, "Here is your reward.");
         push_u32(&mut b, 1); // autoFinish
         push_u32(&mut b, 2); // emoteCount
-        push_u32(&mut b, 500); // delay (FIRST)
+        push_u32(&mut b, 500); // delay, first
         push_u32(&mut b, 1); // emote
         push_u32(&mut b, 0); // delay
         push_u32(&mut b, 2); // emote
@@ -671,12 +613,10 @@ mod tests {
 
     #[test]
     fn quest_invalid_and_failed_parse() {
-        // QUESTGIVER_QUEST_INVALID: one u32 message code.
         let mut b = Vec::new();
         push_u32(&mut b, 7);
         assert_eq!(read_questgiver_quest_invalid(&mut b.as_slice()).unwrap(), 7);
 
-        // QUESTGIVER_QUEST_FAILED: {questId, reason}.
         let mut b2 = Vec::new();
         push_u32(&mut b2, 100);
         push_u32(&mut b2, 4);
diff --git a/crates/benilla-protocol/src/messages/quest/log.rs b/crates/benilla-protocol/src/messages/quest/log.rs
index 3f5753dc..dc50a823 100644
--- a/crates/benilla-protocol/src/messages/quest/log.rs
+++ b/crates/benilla-protocol/src/messages/quest/log.rs
@@ -1,46 +1,19 @@
-//! `CMSG_QUEST_QUERY`/`SMSG_QUEST_QUERY_RESPONSE` (92/93) plus the quest-log book-keeping wire:
-//! `CMSG_QUESTLOG_SWAP_QUEST`/`CMSG_QUESTLOG_REMOVE_QUEST`/`SMSG_QUESTLOG_FULL` (403-405) and the
-//! `SMSG_QUESTUPDATE_*` progress pushes (406-410) — all VERIFIED vmangos `Opcodes_1_12_1.h`. CMSG
-//! bodies from vmangos `Server/Packets/Quest.cpp:6-78`; SMSG layouts from the same file's
-//! `AppendBodyTo` writers (line citations inline).
-//!
-//! Wire traps this parser is written against the *byte stream* to survive (never the C++ control
-//! flow):
-//! - **The cstr order is `title, objectives, details, endText`** (`Quest.cpp:393-528`, the
-//!   `>1_9_4` branch, live on 5875) — objectives lands *before* details, reversed from the giver
-//!   [`super::giver::QuestDetails`] panel's `title, details, objectives`.
-//! - **The reward/choice/objective arrays are fixed-count, not count-prefixed** — always 4/6/4
-//!   slots regardless of how many the quest uses (the tail is zero-filled), and unlike the
-//!   giver-panel triples they carry **no display ids**.
-//! - **The 4 objective texts trail the whole packet** — after all 4 objective quads, not
-//!   interleaved with them.
-//! - **A gameobject objective id is `(−id)|0x80000000`** (`Quest.cpp:512-516`) — the same raw
-//!   encoding `SMSG_QUESTUPDATE_ADD_KILL`'s `entry` field carries for a GO kill/use event
-//!   (`Player.cpp:14634-14637`); both are kept undecoded on the parsed structs.
+//! Quest-log wire (vmangos `Server/Packets/Quest.cpp`): the quest query and response (92/93), log
+//! swap, remove and full (403-405), and the `SMSG_QUESTUPDATE_*` progress pushes (406-410).
 
 use std::io;
 
 use crate::wire::{read_cstring, read_f32_le, read_i32_le, read_u32_le, read_u64_le};
 
-/// `QUEST_OBJECTIVES_COUNT` (= `QUEST_ITEM_OBJECTIVES_COUNT`, vmangos `QuestDef.h:34-43`) — the
-/// fixed objective-quad count `SMSG_QUEST_QUERY_RESPONSE` always writes, regardless of how many
-/// objectives the quest actually has (the unused tail is zero-filled).
+/// Objective quads the response always writes, the unused tail zero-filled (`QuestDef.h:34-43`).
 pub const QUEST_OBJECTIVES_COUNT: u32 = 4;
-/// `QUEST_REWARDS_COUNT` (vmangos `QuestDef.h:34-43`) — the fixed count of `{itemId, count}` reward
-/// slots on `SMSG_QUEST_QUERY_RESPONSE`.
+/// `{itemId, count}` reward slots the response always writes.
 pub const QUEST_REWARDS_COUNT: u32 = 4;
-/// `QUEST_REWARD_CHOICES_COUNT` (vmangos `QuestDef.h:34-43`) — the fixed count of `{itemId, count}`
-/// reward-choice slots on `SMSG_QUEST_QUERY_RESPONSE`.
+/// `{itemId, count}` reward-choice slots the response always writes.
 pub const QUEST_REWARD_CHOICES_COUNT: u32 = 6;
 
-/// One objective slot inside [`QuestTemplate`] (vmangos `Quest.cpp:512-522`): the
-/// `{reqCreatureOrGOId, reqCreatureOrGOCount, reqItemId, reqItemCount}` quad plus its trailing
-/// `objectiveText` cstr (read separately, at the very end of the packet — see
-/// [`read_quest_query_response`]). `creature_or_go` is kept **raw**: a positive value is a creature
-/// entry, a gameobject objective is written as `(−id)|0x80000000` (`Quest.cpp:512-516`) — the same
-/// encoding `SMSG_QUESTUPDATE_ADD_KILL`'s `entry` field carries (`Player.cpp:14634-14637`).
-/// Deciding which case applies (and un-negating the GO id) is a UI concern; the wire doesn't
-/// disambiguate beyond the sign/top bit.
+/// One objective quad plus its text, which the packet sends after all the quads. `creature_or_go`
+/// stays raw: a creature entry, or `(-id)|0x80000000` for a gameobject (`Quest.cpp:512-516`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QuestObjective {
     pub creature_or_go: u32,
@@ -50,46 +23,30 @@ pub struct QuestObjective {
     pub text: String,
 }
 
-/// `QuestFlags` (vmangos `QuestDef.h:145-160`) — the [`QuestTemplate::flags`] word, which is the
-/// only place the client learns a quest's *kind* (the giver panels carry text and rewards, never
-/// flags). Two of these are load-bearing for the party share (decision 1733) and the rest are
-/// pinned beside them so the word is documented once:
-///
-/// - [`PARTY_ACCEPT`] — an escort quest. When a party member accepts one, every other eligible
-///   member gets `SMSG_QUEST_CONFIRM_ACCEPT`.
-/// - [`SHARABLE`] — the quest log's *Share Quest* button. **The client owns this test**: the
-///   server's `HandlePushQuestToParty` does not check the bit at all, it only re-tests it when the
-///   receiver accepts (`Player::CanShareQuest`, `Player.cpp:13959`).
-/// - [`HIDDEN_REWARDS`] documents a wire shape this parser already survives (see the module's
-///   uniform-rewards note): the rewards block is written as three zero `u32`s rather than omitted.
+/// `QuestFlags` (vmangos `QuestDef.h:145-160`): the `QuestTemplate::flags` word, the only place
+/// the client learns a quest's kind; the giver panels never carry it.
 pub mod quest_flags {
     /// Not used by 1.12 data.
     pub const STAY_ALIVE: u32 = 0x0000_0001;
-    /// Escort: accepting it asks the rest of the party whether they want it too.
+    /// Escort: one member accepting sends every other eligible one `SMSG_QUEST_CONFIRM_ACCEPT`.
     pub const PARTY_ACCEPT: u32 = 0x0000_0002;
     /// Not used by 1.12 data.
     pub const EXPLORATION: u32 = 0x0000_0004;
-    /// The quest may be shared with the party.
+    /// Shareable. The client gates Share Quest on it: the server never tests it on the push, only
+    /// on the receiver's accept (`Player::CanShareQuest`, `Player.cpp:13959`).
     pub const SHARABLE: u32 = 0x0000_0008;
     /// Not used by 1.12 data.
     pub const EPIC: u32 = 0x0000_0020;
     /// Not used by 1.12 data.
     pub const RAID: u32 = 0x0000_0040;
-    /// Rewards ship only in `SMSG_QUESTGIVER_OFFER_REWARD` — the DETAILS panel and this template
-    /// write an empty rewards block instead.
+    /// Rewards ship only in `SMSG_QUESTGIVER_OFFER_REWARD`; DETAILS and this template zero them.
     pub const HIDDEN_REWARDS: u32 = 0x0000_0200;
     /// Granted and completed in one step; never appears in the client's quest log.
     pub const AUTO_REWARDED: u32 = 0x0000_0400;
 }
 
-/// `SMSG_QUEST_QUERY_RESPONSE` (vmangos `Quest.cpp:393-528`, the `>1_9_4` branch — live on 5875):
-/// the full quest template, answering `CMSG_QUEST_QUERY` and feeding the quest log's detail view.
-/// Unlike the giver panels this carries **fixed-count** reward/choice/objective arrays (no count
-/// prefix, no display ids) and a **different cstr order** — `title, objectives, details, endText`,
-/// objectives *before* details, reversed from [`super::giver::QuestDetails`]. `money`/
-/// `money_max_level` mirror the giver DETAILS panel's `rewOrReqMoney`/`rewMoneyMaxLevel` split; a
-/// HIDDEN_REWARDS quest zeroes the reward/choice/money fields but keeps the same shape — this
-/// parser is flag-blind, same as [`super::giver::read_questgiver_quest_details`].
+/// `SMSG_QUEST_QUERY_RESPONSE` (vmangos `Quest.cpp:393-528`, the `>1_9_4` branch): the quest
+/// template behind the quest log's detail view. Its arrays are fixed-count with no display ids.
 #[derive(Debug, Clone, PartialEq)]
 pub struct QuestTemplate {
     pub quest_id: u32,
@@ -118,33 +75,27 @@ pub struct QuestTemplate {
     pub objectives: [QuestObjective; QUEST_OBJECTIVES_COUNT as usize],
 }
 
-// ── CMSG encoders (readers at vmangos `Quest.cpp:6-58`) ───────────────────────────────────────────
+// ── CMSG encoders ────────────────────────────────────────────────────────────────────────────────
 
-/// Body of `CMSG_QUEST_QUERY` (vmangos `Quest.cpp:6`, `Quest.h:17`): one `u32` quest entry.
-/// Answered by `SMSG_QUEST_QUERY_RESPONSE` ([`QuestTemplate`]) — the quest-log detail view's
-/// opener, distinct from the giver-panel `CMSG_QUESTGIVER_QUERY_QUEST` (which needs an NPC guid).
+/// Body of `CMSG_QUEST_QUERY` (`Quest.cpp:6`): the quest id. Unlike the giver query, no NPC guid.
 pub fn quest_query(quest_id: u32) -> Vec<u8> {
     quest_id.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_QUESTLOG_REMOVE_QUEST` (vmangos `Quest.cpp:58`, `Quest.h:105`): one `u8` log
-/// slot. Abandons the quest in that slot; the server clears the `PLAYER_QUEST_LOG` fields
-/// directly — there is no ack SMSG, the field update *is* the confirmation.
+/// Body of `CMSG_QUESTLOG_REMOVE_QUEST` (`Quest.cpp:58`): abandons a log slot. There is no reply;
+/// the cleared `PLAYER_QUEST_LOG` fields are the confirmation.
 pub fn questlog_remove_quest(slot: u8) -> Vec<u8> {
     vec![slot]
 }
 
-/// Body of `CMSG_QUESTLOG_SWAP_QUEST` (vmangos `Quest.cpp:52`, `Quest.h:95-96`): two `u8` log
-/// slots to swap.
+/// Body of `CMSG_QUESTLOG_SWAP_QUEST` (`Quest.cpp:52`).
 pub fn questlog_swap_quest(slot1: u8, slot2: u8) -> Vec<u8> {
     vec![slot1, slot2]
 }
 
-// ── SMSG parsers ──────────────────────────────────────────────────────────────────────────────────
+// ── SMSG parsers ─────────────────────────────────────────────────────────────────────────────────
 
-/// Read `SMSG_QUEST_QUERY_RESPONSE` (vmangos `Quest.cpp:393-528`, the `>1_9_4` branch, live on
-/// 5875) — see [`QuestTemplate`] for the field-by-field wire-trap notes (cstr order, fixed-count
-/// arrays, the trailing objective texts, the raw GO objective encoding).
+/// Read `SMSG_QUEST_QUERY_RESPONSE`.
 pub(in crate::messages) fn read_quest_query_response(r: &mut &[u8]) -> io::Result<QuestTemplate> {
     let quest_id = read_u32_le(r)?;
     let method = read_u32_le(r)?;
@@ -153,8 +104,8 @@ pub(in crate::messages) fn read_quest_query_response(r: &mut &[u8]) -> io::Resul
     let quest_type = read_u32_le(r)?;
     let rep_objective_faction = read_u32_le(r)?;
     let rep_objective_value = read_u32_le(r)?;
-    let _opposite_rep_faction = read_u32_le(r)?; // requiredOppositeRepFaction — always 0
-    let _opposite_rep_value = read_u32_le(r)?; // requiredOppositeRepValue — always 0
+    let _opposite_rep_faction = read_u32_le(r)?; // requiredOppositeRepFaction, always 0
+    let _opposite_rep_value = read_u32_le(r)?; // requiredOppositeRepValue, always 0
     let next_quest_in_chain = read_u32_le(r)?;
     let money = read_i32_le(r)?;
     let money_max_level = read_u32_le(r)?;
@@ -162,8 +113,7 @@ pub(in crate::messages) fn read_quest_query_response(r: &mut &[u8]) -> io::Resul
     let src_item_id = read_u32_le(r)?;
     let flags = read_u32_le(r)?;
 
-    // Fixed-count reward/choice arrays — NOT count-prefixed like the giver-panel item blocks, and
-    // no display ids. HIDDEN_REWARDS zeroes the values but keeps the same shape.
+    // Fixed-count, unlike the giver panels' count-prefixed blocks; HIDDEN_REWARDS only zeroes them.
     let mut rewards = [(0u32, 0u32); QUEST_REWARDS_COUNT as usize];
     for slot in rewards.iter_mut() {
         *slot = (read_u32_le(r)?, read_u32_le(r)?);
@@ -179,8 +129,7 @@ pub(in crate::messages) fn read_quest_query_response(r: &mut &[u8]) -> io::Resul
     let point_opt = read_u32_le(r)?;
 
     let title = read_cstring(r)?;
-    // The trap: objectives overview text lands BEFORE details here — reversed vs DETAILS
-    // (`QuestDetails`, whose order is title/details/objectives).
+    // Objectives before details: the reverse of the giver panel's `QuestDetails` order.
     let objectives_text = read_cstring(r)?;
     let details = read_cstring(r)?;
     let end_text = read_cstring(r)?;
@@ -194,7 +143,7 @@ pub(in crate::messages) fn read_quest_query_response(r: &mut &[u8]) -> io::Resul
             read_u32_le(r)?,
         );
     }
-    // The 4 objective texts trail the *whole* packet — after every quad, not interleaved.
+    // The objective texts follow all the quads, not interleaved with them.
     let mut objective_texts = Vec::with_capacity(QUEST_OBJECTIVES_COUNT as usize);
     for _ in 0..QUEST_OBJECTIVES_COUNT {
         objective_texts.push(read_cstring(r)?);
@@ -244,12 +193,9 @@ pub(in crate::messages) fn read_quest_query_response(r: &mut &[u8]) -> io::Resul
     })
 }
 
-/// Read `SMSG_QUESTUPDATE_ADD_KILL` (vmangos `Quest.cpp:144`): `u32 questId, u32 entry, u32
-/// count, u32 required, u64 guid`. `entry` for a gameobject objective is
-/// `(−ReqCreatureOrGOId)|0x80000000` (`Player.cpp:14634-14637`, the same raw encoding as
-/// [`QuestObjective::creature_or_go`]); `count` is asserted `< 64` server-side (a 6-bit
-/// slot-counter store) and mirrors — doesn't replace — the durable `PLAYER_QUEST_LOG` counter
-/// field: this packet is the toast line, the field update is the durable state.
+/// Read `SMSG_QUESTUPDATE_ADD_KILL` (`Quest.cpp:144`): `(questId, entry, count, required, guid)`.
+/// A gameobject `entry` is `(-id)|0x80000000` (`Player.cpp:14634`); `count` stays below 64. This
+/// is the toast line only: the `PLAYER_QUEST_LOG` counter field is the durable state.
 pub(in crate::messages) fn read_quest_update_add_kill(
     r: &mut &[u8],
 ) -> io::Result<(u32, u32, u32, u32, u64)> {
@@ -267,9 +213,7 @@ pub(in crate::messages) fn read_quest_update_add_item(r: &mut &[u8]) -> io::Resu
     Ok((read_u32_le(r)?, read_u32_le(r)?))
 }
 
-/// Read `SMSG_QUESTUPDATE_COMPLETE` (vmangos `Quest.cpp:91`): one `u32` quest id. Fires once
-/// every objective is complete (`Player.cpp` ~14494); the log slot's state byte gets
-/// `QUEST_STATE_COMPLETE`.
+/// Read `SMSG_QUESTUPDATE_COMPLETE` (`Quest.cpp:91`): the quest id, once every objective is done.
 pub(in crate::messages) fn read_quest_update_complete(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
@@ -279,8 +223,7 @@ pub(in crate::messages) fn read_quest_update_failed(r: &mut &[u8]) -> io::Result
     read_u32_le(r)
 }
 
-/// Read `SMSG_QUESTUPDATE_FAILEDTIMER` (vmangos `Quest.cpp:121`): one `u32` quest id — a timed
-/// quest's clock ran out.
+/// Read `SMSG_QUESTUPDATE_FAILEDTIMER` (`Quest.cpp:121`): the id of a timed quest that expired.
 pub(in crate::messages) fn read_quest_update_failedtimer(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
@@ -289,7 +232,7 @@ pub(in crate::messages) fn read_quest_update_failedtimer(r: &mut &[u8]) -> io::R
 mod tests {
     use super::*;
 
-    // ── Small byte-buffer builders for the hand-built parse fixtures ──────────────────────────────
+    // ── Fixture builders ─────────────────────────────────────────────────────────────────────────
     fn push_u32(b: &mut Vec<u8>, v: u32) {
         b.extend_from_slice(&v.to_le_bytes());
     }
@@ -427,7 +370,6 @@ mod tests {
         assert_eq!(q.point_y, -45.25);
         assert_eq!(q.point_opt, 2);
         assert_eq!(q.title, "A Threat Within");
-        // The trap: objectives-overview text lands BEFORE details.
         assert_eq!(q.objectives_text, "Slay 10 kobolds.");
         assert_eq!(q.details, "Kill the kobolds threatening Goldshire.");
         assert_eq!(q.end_text, "You have done well, adventurer.");
@@ -445,8 +387,7 @@ mod tests {
 
     #[test]
     fn quest_query_response_hidden_rewards_shape_is_blind() {
-        // A HIDDEN_REWARDS quest zeroes every reward/choice slot and the money field, but the
-        // fixed-count shape is unchanged — this parser can't see (and doesn't need) the flag.
+        // HIDDEN_REWARDS zeroes the rewards, choices and money but keeps the fixed-count shape.
         let mut b = Vec::new();
         push_u32(&mut b, 200); // questId
         push_u32(&mut b, 0); // method
@@ -462,7 +403,7 @@ mod tests {
         push_u32(&mut b, 0); // rewMoneyMaxLevel
         push_u32(&mut b, 99); // rewSpell
         push_u32(&mut b, 0); // srcItemId
-        push_u32(&mut b, 0x200); // questFlags (a HIDDEN_REWARDS-shaped value; parser is flag-blind)
+        push_u32(&mut b, 0x200); // questFlags: HIDDEN_REWARDS
         for _ in 0..QUEST_REWARDS_COUNT {
             push_u32(&mut b, 0);
             push_u32(&mut b, 0);
@@ -515,7 +456,6 @@ mod tests {
 
     #[test]
     fn quest_update_simple_smsgs_parse() {
-        // COMPLETE/FAILED/FAILEDTIMER are all a lone u32 quest id.
         let mut b = Vec::new();
         push_u32(&mut b, 42);
         assert_eq!(read_quest_update_complete(&mut b.as_slice()).unwrap(), 42);
@@ -525,7 +465,6 @@ mod tests {
             42
         );
 
-        // ADD_ITEM: {itemId, count}.
         let mut b2 = Vec::new();
         push_u32(&mut b2, 3000);
         push_u32(&mut b2, 5);
diff --git a/crates/benilla-protocol/src/messages/quest/mod.rs b/crates/benilla-protocol/src/messages/quest/mod.rs
index f9056d8e..95fc47d6 100644
--- a/crates/benilla-protocol/src/messages/quest/mod.rs
+++ b/crates/benilla-protocol/src/messages/quest/mod.rs
@@ -1,15 +1,5 @@
-//! Questgiver + quest-log messages, split along the two decision-scoped slices: [`giver`] — the
-//! "accept/turn-in a quest at an NPC" family (opcodes 386-402, vmangos `Opcodes_1_12_1.h`,
-//! VERIFIED; decision 0088) — and [`log`] — the quest-log wire: `CMSG_QUEST_QUERY`/
-//! `SMSG_QUEST_QUERY_RESPONSE` (92/93), `CMSG_QUESTLOG_SWAP_QUEST`/`CMSG_QUESTLOG_REMOVE_QUEST`/
-//! `SMSG_QUESTLOG_FULL` (403-405), and the `SMSG_QUESTUPDATE_*` progress pushes (406-410). CMSG
-//! bodies from vmangos `Server/Packets/Quest.cpp:6-78`; SMSG layouts from the same file's
-//! `AppendBodyTo` writers (line citations inline in each submodule). The third slice — `share`,
-//! `CMSG_QUEST_CONFIRM_ACCEPT` / `SMSG_QUEST_CONFIRM_ACCEPT` / `CMSG_PUSHQUESTTOPARTY` /
-//! `MSG_QUEST_PUSH_RESULT` (411-413 + 630) — is the party quest-share flow (decision 1733). It is
-//! its own file and not `giver`'s, even though a shared quest lands on the giver's own DETAILS
-//! panel: what is new here is the *verdict* wire between sharer and receiver, and `giver` never
-//! learns that a share exists — it only ever sees a giver guid that happens to be a player.
+//! Quest messages: [`giver`] for accepting and turning in at an NPC (386-402), [`log`] for the
+//! quest log (92/93, 403-410), and `share` for the party quest share (411-413, 630).
 
 mod giver;
 mod log;
diff --git a/crates/benilla-protocol/src/messages/quest/share.rs b/crates/benilla-protocol/src/messages/quest/share.rs
index f2e07e7b..ee26c5a1 100644
--- a/crates/benilla-protocol/src/messages/quest/share.rs
+++ b/crates/benilla-protocol/src/messages/quest/share.rs
@@ -1,119 +1,73 @@
-//! The **party quest-share** wire (opcodes 411-413 + 630, VERIFIED vmangos `Opcodes_1_12_1.h`) —
-//! decision 1733, the third slice of the quest arc after [`super::giver`] and [`super::log`].
-//!
-//! Two independent flows share this file because they share the same server-side latch (vmangos
-//! `Player::SetQuestShareInfo`/`ClearQuestShareInfo`, one `{sharerGuid, questId}` pair per player):
-//!
-//! 1. **The push** — the quest log's *Share Quest* button. `CMSG_PUSHQUESTTOPARTY{questId}` → the server
-//!    walks the group and, per member, sends the SHARER a `MSG_QUEST_PUSH_RESULT`
-//!    verdict; an eligible member additionally gets an ordinary `SMSG_QUESTGIVER_QUEST_DETAILS`
-//!    whose `npcGuid` is the **sharer's player guid** (vmangos `QuestHandler.cpp:403-459`). That is
-//!    the whole reason the receiver needs no new inbound opcode: a shared quest arrives on the
-//!    detail panel already built, and Accept answers it with the ordinary
-//!    `CMSG_QUESTGIVER_ACCEPT_QUEST` addressed to that player guid (the server's own
-//!    `TYPEID_PLAYER` arm, `QuestHandler.cpp:111-114`, gated on `Player::CanShareQuest`).
-//!    A **decline** is the one verdict the client itself originates: `MSG_QUEST_PUSH_RESULT` back
-//!    up, which the server relays to the sharer with the *receiver's* guid substituted
-//!    (`QuestHandler.cpp:461-478`).
-//! 2. **The escort confirm** — `QUEST_FLAGS_PARTY_ACCEPT` (0x2). When a party member accepts such
-//!    a quest, every other eligible member gets `SMSG_QUEST_CONFIRM_ACCEPT` and answers with
-//!    `CMSG_QUEST_CONFIRM_ACCEPT` if they say yes (vmangos `QuestHandler.cpp:172-193`,
-//!    `Player.cpp:14571-14594`). Saying *no* sends nothing at all — the server's latch is cleared
-//!    by the next thing that touches it.
-//!
-//! **Who the guid names flips direction on `MSG_QUEST_PUSH_RESULT`, and that is the one trap here.**
-//! The opcode is `MSG_*` — the same number both ways — but the `u64` never means the same thing
-//! twice: going *up* it is the sharer the receiver is answering; coming *down* it is the OTHER
-//! party (`Player::SendPushToPartyResponse` writes `pPlayer`'s guid, the member the verdict is
-//! *about*, `Player.cpp:14596-14608`), so the sharer's `%s` fills from it directly.
+//! The party quest-share wire (411-413, 630). The sharer gets one `MSG_QUEST_PUSH_RESULT` per
+//! member; an eligible member gets an ordinary `SMSG_QUESTGIVER_QUEST_DETAILS` with the sharer's
+//! player guid as `npcGuid`, and Accept sends `CMSG_QUESTGIVER_ACCEPT_QUEST` to that guid
+//! (`QuestHandler.cpp:111-114, 403-459`). The push-result guid names a different player each way.
 
 use std::io;
 
 use crate::wire::{read_cstring, read_u32_le, read_u64_le, read_u8};
 
-/// `QuestShareMessages` (vmangos `QuestDef.h:62-70`) — the `u8` verdict `MSG_QUEST_PUSH_RESULT`
-/// carries in both directions. The server originates 0/1/4/5/6/7/8 while walking the group, and 2
-/// when the receiver accepts; the client originates 3 when the receiver declines.
-///
-/// Kept as a plain `u8` newtype rather than an enum with a `TryFrom` because the *display* mapping
-/// (which `ERR_QUEST_PUSH_*` message id each value selects, and on which surface) belongs to the
-/// app layer's message table, not to the wire — and an unknown value must survive the parse the way
-/// every other unmapped code in this crate does, not become a parse error that drops the packet.
+/// `QuestShareMessages` (vmangos `QuestDef.h:62-70`): the `u8` verdict of `MSG_QUEST_PUSH_RESULT`.
+/// A newtype, not an enum, so an unknown value survives the parse.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct QuestShareMsg(pub u8);
 
 impl QuestShareMsg {
-    /// `QUEST_PARTY_MSG_SHARING_QUEST` — the server's opening "the push went out to this member".
+    /// `QUEST_PARTY_MSG_SHARING_QUEST`: the push went out to this member.
     pub const SHARING_QUEST: Self = Self(0);
-    /// `QUEST_PARTY_MSG_CANT_TAKE_QUEST` — the member fails `CanTakeQuest` (level, race, prereqs).
+    /// `QUEST_PARTY_MSG_CANT_TAKE_QUEST`: the member fails `CanTakeQuest` (level, race, prereqs).
     pub const CANT_TAKE_QUEST: Self = Self(1);
-    /// `QUEST_PARTY_MSG_ACCEPT_QUEST` — the member accepted (server-originated, on their
-    /// `CMSG_QUESTGIVER_ACCEPT_QUEST`).
+    /// `QUEST_PARTY_MSG_ACCEPT_QUEST`: sent by the server when the member accepts.
     pub const ACCEPT_QUEST: Self = Self(2);
-    /// `QUEST_PARTY_MSG_DECLINE_QUEST` — **the one value the client sends**.
+    /// `QUEST_PARTY_MSG_DECLINE_QUEST`: the one value the client sends.
     pub const DECLINE_QUEST: Self = Self(3);
-    /// `QUEST_PARTY_MSG_TOO_FAR` — outside `QUEST_SHARE_DISTANCE` (14.0 yd, vmangos `Object.h:72`).
+    /// `QUEST_PARTY_MSG_TOO_FAR`: beyond `QUEST_SHARE_DISTANCE`, 14 yd (vmangos `Object.h:72`).
     pub const TOO_FAR: Self = Self(4);
-    /// `QUEST_PARTY_MSG_BUSY` — the member already has a share latched.
+    /// `QUEST_PARTY_MSG_BUSY`: the member already has a share latched.
     pub const BUSY: Self = Self(5);
-    /// `QUEST_PARTY_MSG_LOG_FULL` — the member's quest log is full.
+    /// `QUEST_PARTY_MSG_LOG_FULL`: the member's quest log is full.
     pub const LOG_FULL: Self = Self(6);
-    /// `QUEST_PARTY_MSG_HAVE_QUEST` — the member is already on the quest.
+    /// `QUEST_PARTY_MSG_HAVE_QUEST`: the member is already on the quest.
     pub const HAVE_QUEST: Self = Self(7);
-    /// `QUEST_PARTY_MSG_FINISH_QUEST` — the member has already completed the quest.
+    /// `QUEST_PARTY_MSG_FINISH_QUEST`: the member has already completed the quest.
     pub const FINISH_QUEST: Self = Self(8);
 }
 
-/// `MSG_QUEST_PUSH_RESULT` as the **server** sends it (vmangos
-/// `Server/Packets/Quest.cpp:81-85`): `u64 guid, u8 msg`.
-///
-/// `guid` is the party member the verdict is *about* — never the sharer, and never us (see the
-/// module header's direction trap). It is what fills the `%s` of every `ERR_QUEST_PUSH_*` string.
+/// `MSG_QUEST_PUSH_RESULT` from the server (`Quest.cpp:81-85`). Its guid is the member the verdict
+/// is about, never the sharer, and fills the `%s` of `ERR_QUEST_PUSH_*` (`Player.cpp:14596-14608`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct QuestPushResult {
-    /// The party member the verdict concerns.
     pub member: u64,
-    /// The verdict.
     pub msg: QuestShareMsg,
 }
 
-/// `SMSG_QUEST_CONFIRM_ACCEPT` (vmangos `Server/Packets/Quest.cpp:131-136`): `u32 questId, cstr
-/// questTitle, u64 senderGuid` — the `QUEST_FLAGS_PARTY_ACCEPT` (escort) confirm box.
-///
-/// The **title travels on the wire** rather than being looked up from the client's template cache,
-/// because the server localizes it per receiver session (`Player::SendQuestConfirmAccept`,
-/// `Player.cpp:14575-14586`) — and because the receiver may never have queried this quest at all.
+/// `SMSG_QUEST_CONFIRM_ACCEPT` (`Quest.cpp:131-136`): the escort confirm, sent to the other
+/// eligible members when one accepts.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QuestConfirmAccept {
-    /// The quest being started — echoed back verbatim in [`quest_confirm_accept`].
+    /// Echoed back in [`quest_confirm_accept`].
     pub quest_id: u32,
-    /// The quest title, already localized by the server.
+    /// Server-localized (`Player.cpp:14575-14586`); the receiver may not have the quest cached.
     pub title: String,
-    /// The party member who accepted it — the first `%s` of `QUEST_ACCEPT`.
+    /// The member who accepted: the first `%s` of `QUEST_ACCEPT`.
     pub sender: u64,
 }
 
-// ── CMSG encoders ─────────────────────────────────────────────────────────────────────────────────
+// ── CMSG encoders ────────────────────────────────────────────────────────────────────────────────
 
-/// Body of `CMSG_PUSHQUESTTOPARTY` (vmangos `Quest.cpp:68-71`): one `u32` quest id. The quest log's
-/// *Share Quest* button; the server addresses the group itself, so no member guid rides along.
+/// Body of `CMSG_PUSHQUESTTOPARTY` (`Quest.cpp:68-71`): Share Quest; the server walks the group.
 pub fn push_quest_to_party(quest_id: u32) -> Vec<u8> {
     quest_id.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_QUEST_CONFIRM_ACCEPT` (vmangos `Quest.cpp:63-66`): one `u32` quest id — the
-/// escort confirm's Yes.
+/// Body of `CMSG_QUEST_CONFIRM_ACCEPT` (`Quest.cpp:63-66`): the escort confirm's yes. A no sends
+/// nothing (`QuestHandler.cpp:172-193`).
 pub fn quest_confirm_accept(quest_id: u32) -> Vec<u8> {
     quest_id.to_le_bytes().to_vec()
 }
 
-/// Body of `MSG_QUEST_PUSH_RESULT` as the **client** sends it (vmangos `Quest.cpp:73-77`): `u64
-/// guid, u8 msg`. `guid` is the *sharer* we are answering — the `npcGuid` the shared
-/// `SMSG_QUESTGIVER_QUEST_DETAILS` arrived under.
-///
-/// vmangos ignores the guid entirely (it re-derives the sharer from its own latch,
-/// `QuestHandler.cpp:461-467`), so a wrong value here would go unnoticed against this server. It is
-/// sent correctly anyway: the field is the protocol's, not the server's.
+/// Body of `MSG_QUEST_PUSH_RESULT` from the client (`Quest.cpp:73-77`): the sharer being answered,
+/// the `npcGuid` the shared DETAILS came under. vmangos ignores it (`QuestHandler.cpp:461-467`).
 pub fn quest_push_result(sharer: u64, msg: QuestShareMsg) -> Vec<u8> {
     let mut b = Vec::with_capacity(9);
     b.extend_from_slice(&sharer.to_le_bytes());
@@ -121,9 +75,9 @@ pub fn quest_push_result(sharer: u64, msg: QuestShareMsg) -> Vec<u8> {
     b
 }
 
-// ── SMSG readers ──────────────────────────────────────────────────────────────────────────────────
+// ── SMSG readers ─────────────────────────────────────────────────────────────────────────────────
 
-/// Read `MSG_QUEST_PUSH_RESULT` (see [`QuestPushResult`]).
+/// Read `MSG_QUEST_PUSH_RESULT` from the server.
 pub(in crate::messages) fn read_quest_push_result(r: &mut &[u8]) -> io::Result<QuestPushResult> {
     Ok(QuestPushResult {
         member: read_u64_le(r)?,
@@ -131,7 +85,7 @@ pub(in crate::messages) fn read_quest_push_result(r: &mut &[u8]) -> io::Result<Q
     })
 }
 
-/// Read `SMSG_QUEST_CONFIRM_ACCEPT` (see [`QuestConfirmAccept`]).
+/// Read `SMSG_QUEST_CONFIRM_ACCEPT`.
 pub(in crate::messages) fn read_quest_confirm_accept(
     r: &mut &[u8],
 ) -> io::Result<QuestConfirmAccept> {
@@ -163,7 +117,6 @@ mod tests {
 
     #[test]
     fn push_result_reads_member_then_msg() {
-        // The server's `AppendBodyTo`: guid first, verdict byte last.
         let mut b = 0x0000_0000_0000_00AAu64.to_le_bytes().to_vec();
         b.push(8);
         let r = read_quest_push_result(&mut b.as_slice()).unwrap();
@@ -176,8 +129,6 @@ mod tests {
         );
     }
 
-    /// An unmapped verdict byte must survive the parse — the display table decides what (if
-    /// anything) to show, exactly as every other unmapped wire code in this crate is handled.
     #[test]
     fn unknown_verdict_byte_parses() {
         let mut b = 1u64.to_le_bytes().to_vec();
diff --git a/crates/benilla-protocol/src/messages/reputation.rs b/crates/benilla-protocol/src/messages/reputation.rs
index 673e0961..cb86b8ef 100644
--- a/crates/benilla-protocol/src/messages/reputation.rs
+++ b/crates/benilla-protocol/src/messages/reputation.rs
@@ -1,61 +1,33 @@
-//! The reputation pane's three send verbs, and the one server push that is not a standing.
-//!
-//! Every faction the client can *change* is addressed by its **reputation-list id** — `Faction.dbc`'s
-//! `reputationIndex`, the same slot the `SMSG_INITIALIZE_FACTIONS` array is positional in — never by
-//! the `Faction.dbc` id and never by the panel's display row. The three bodies are byte-exact against
-//! the vmangos reader side (`Server/Packets/Misc.cpp` + `Misc.h`, the `SetFactionAtWar` /
-//! `SetFactionInactive` / `SetWatchedFaction` `ClientPacket`s), which is what a real server will
-//! actually parse:
-//!
-//! | verb | opcode | body |
-//! |---|---|---|
-//! | at-war toggle | `CMSG_SET_FACTION_ATWAR` 0x125 | `u32 repListId`, `u8 flag` |
-//! | inactive toggle | `CMSG_SET_FACTION_INACTIVE` 0x317 | `u32 repListId`, `u8 inactive` |
-//! | watched faction | `CMSG_SET_WATCHED_FACTION` 0x318 | `i32 repListId` |
-//!
-//! **The watched verb is signed, and that is load-bearing.** Slot `0` is a real faction (the Bloodsail
-//! Buccaneers hold `reputationIndex` 0 in 1.12's `Faction.dbc`), so "watch nothing" cannot be 0 on the
-//! wire — vmangos writes the value straight into `PLAYER_FIELD_WATCHED_FACTION_INDEX` with
-//! `SetInt32Value` (`Handlers/CharacterHandler.cpp` `HandleSetWatchedFactionOpcode`), and the descriptor
-//! field's "none" is `-1`. FrameXML's own `SetWatchedFactionIndex(0)` passes a *display row* of 0
-//! meaning "no row", so the binding — not this layer — is where 0 becomes [`WATCHED_FACTION_NONE`].
-//!
-//! None of the three is acked. The at-war and inactive flags come back as the flag byte of a fresh
-//! `SMSG_INITIALIZE_FACTIONS`-shaped state only at the next login; within a session the client owns
-//! its own optimistic flag copy, exactly as it owns the collapse state. The watched index comes back
-//! as a `PLAYER_FIELD_WATCHED_FACTION_INDEX` descriptor update.
+//! The reputation pane's send verbs (vmangos `Misc.cpp`). A faction is addressed by its
+//! reputation-list id (`Faction.dbc` `reputationIndex`, its `SMSG_INITIALIZE_FACTIONS` slot),
+//! never by the DBC id or the panel row. None is acked: at-war and inactive return only at the
+//! next login, so the client keeps its own copy; the watched index returns as a descriptor update.
 
-/// The length of the reputation-list array `SMSG_INITIALIZE_FACTIONS` is positional in — vmangos
-/// `WorldPackets::Misc::InitializeFactions::MAX_FACTION_COUNT` (`Server/Packets/Misc.h:607`), the
-/// `std::array<FactionInitEntry, 64>` the packet is built over. Every `repListId` on this wire —
-/// the `SMSG_SET_FACTION_STANDING` / `SMSG_SET_FACTION_VISIBLE` slot, and the three send verbs' —
-/// is an index into that array, so one past it is not a faction and a store sized from it is a
-/// store sized from a lie (decision 2265 §B1).
+/// Length of the reputation list `SMSG_INITIALIZE_FACTIONS` is positional in (vmangos `Misc.h:607`,
+/// `MAX_FACTION_COUNT`); every `repListId` on this wire indexes it.
 pub const FACTION_LIST_LEN: usize = 64;
 
-/// The `PLAYER_FIELD_WATCHED_FACTION_INDEX` / `CMSG_SET_WATCHED_FACTION` sentinel for "watch no
-/// faction" — see the module header on why it cannot be `0`.
+/// "Watch no faction" for `CMSG_SET_WATCHED_FACTION` and `PLAYER_FIELD_WATCHED_FACTION_INDEX`. Not
+/// 0: slot 0 is a real faction (Bloodsail Buccaneers) and vmangos stores the value as sent
+/// (`HandleSetWatchedFactionOpcode`). FrameXML's row 0 means none; the binding maps it to this.
 pub const WATCHED_FACTION_NONE: i32 = -1;
 
-/// Body of `CMSG_SET_FACTION_ATWAR`: the reputation-list slot, then the desired at-war state.
-///
-/// vmangos drops the request outright while the player is in combat
-/// (`HandleSetFactionAtWarOpcode`), so a declare/withdraw mid-fight is silently nothing.
+/// Body of `CMSG_SET_FACTION_ATWAR`. vmangos drops it without a reply while the player is in combat
+/// (`HandleSetFactionAtWarOpcode`).
 pub fn set_faction_at_war(rep_list_id: u32, at_war: bool) -> Vec<u8> {
     let mut out = rep_list_id.to_le_bytes().to_vec();
     out.push(u8::from(at_war));
     out
 }
 
-/// Body of `CMSG_SET_FACTION_INACTIVE`: the reputation-list slot, then the desired inactive state.
+/// Body of `CMSG_SET_FACTION_INACTIVE`.
 pub fn set_faction_inactive(rep_list_id: u32, inactive: bool) -> Vec<u8> {
     let mut out = rep_list_id.to_le_bytes().to_vec();
     out.push(u8::from(inactive));
     out
 }
 
-/// Body of `CMSG_SET_WATCHED_FACTION`: one **signed** reputation-list slot, or
-/// [`WATCHED_FACTION_NONE`] to stop watching.
+/// Body of `CMSG_SET_WATCHED_FACTION`: a slot, or [`WATCHED_FACTION_NONE`] to stop watching.
 pub fn set_watched_faction(rep_list_id: i32) -> Vec<u8> {
     rep_list_id.to_le_bytes().to_vec()
 }
diff --git a/crates/benilla-protocol/src/messages/roster.rs b/crates/benilla-protocol/src/messages/roster.rs
index b82154fe..81852c9f 100644
--- a/crates/benilla-protocol/src/messages/roster.rs
+++ b/crates/benilla-protocol/src/messages/roster.rs
@@ -1,6 +1,5 @@
-//! The character-select roster family: the `SMSG_CHAR_ENUM` [`Character`] entry (vmangos
-//! `Player::BuildEnumData` field order, byte-goldened in `tests/char_enum.rs`) + the
-//! create/delete result codes and the race/class/gender ids the create path sends.
+//! Character select: the `SMSG_CHAR_ENUM` [`Character`] entry (vmangos `Player::BuildEnumData`
+//! order), the create/delete result codes and the create request.
 
 use std::io::{self, Read};
 
@@ -9,26 +8,19 @@ use crate::wire::{read_cstring, read_u32_le, read_u64_le, read_u8, Vector3d};
 /// `WorldResult::CharCreateSuccess` / `CharCreateNameInUse` (`SMSG_CHAR_CREATE`).
 pub const CHAR_CREATE_SUCCESS: u8 = 0x2E;
 pub const CHAR_CREATE_NAME_IN_USE: u8 = 0x31;
-/// `WorldResult::CharCreateServerLimit` — the account already holds `CharactersPerRealm` characters
-/// (vmangos `HandleCharCreateOpcode`, checked against the last char-enum's count). Counted from the
-/// `CHAR_CREATE_SUCCESS = 0x2E` anchor through the `SharedDefines.h` ResponseCodes order
-/// (SUCCESS, ERROR, FAILED, NAME_IN_USE, DISABLED, PVP_TEAMS_VIOLATION, SERVER_LIMIT).
+/// `WorldResult::CharCreateServerLimit`: the account already holds `CharactersPerRealm`
+/// characters (vmangos `HandleCharCreateOpcode`; 0x2E + 6 in `SharedDefines.h` ResponseCodes).
 pub const CHAR_CREATE_SERVER_LIMIT: u8 = 0x34;
-/// `WorldResult::CharDeleteSuccess` (`SMSG_CHAR_DELETE`; vmangos `SharedDefines.h` ResponseCodes,
-/// counted from the verified `CHAR_CREATE_SUCCESS = 0x2E` anchor).
+/// `WorldResult::CharDeleteSuccess` (`SMSG_CHAR_DELETE`; vmangos `SharedDefines.h` ResponseCodes).
 pub const CHAR_DELETE_SUCCESS: u8 = 0x39;
 /// Race/Class/Gender values benilla's char-create sends.
 pub const RACE_HUMAN: u8 = 0x1;
 pub const CLASS_WARRIOR: u8 = 0x1;
 pub const GENDER_MALE: u8 = 0x0;
 
-/// A character-creation request: the identity + the five appearance dials the create screen picked.
-/// Consumed by the [`super::char_create`] body builder (`CMSG_CHAR_CREATE`) and carried to the
-/// parked IO thread over the pick channel (decision 0423). `outfit_id` isn't here — it's always 0 on
-/// the wire (the server reads and ignores it, then recomputes start gear; verified vmangos
-/// `CharacterHandler.cpp:310`). The five appearance bytes are `ChrRaces`/`CharSections`-valid indices
-/// the create UI derives from the DBCs, so every request the UI can build passes the server's
-/// `Player::ValidateAppearance`.
+/// A `CMSG_CHAR_CREATE` request for [`super::char_create`]. The outfit id is always 0 on the wire:
+/// the server ignores it and picks the start gear (vmangos `CharacterHandler.cpp:310`). The
+/// appearance bytes must be valid `CharSections` indices or `Player::ValidateAppearance` refuses.
 #[derive(Debug, Clone)]
 pub struct CharCreateReq {
     pub name: String,
@@ -45,28 +37,21 @@ pub struct CharCreateReq {
     pub facial_hair: u8,
 }
 
-/// The enum entry's `flags` bits the select screen renders (vmangos `CHARACTER_FLAG_*`,
-/// `Player::BuildEnumData`): the at-login helm/cloak hide toggles, the dead-as-ghost marker, and
-/// the server-ordered rename.
+/// The vmangos `CHARACTER_FLAG_*` bits of [`Character::flags`] that the select screen renders.
 pub const CHARACTER_FLAG_HIDE_HELM: u32 = 0x0400;
 pub const CHARACTER_FLAG_HIDE_CLOAK: u32 = 0x0800;
 pub const CHARACTER_FLAG_GHOST: u32 = 0x2000;
 pub const CHARACTER_FLAG_RENAME: u32 = 0x4000;
 
-/// One visible-equipment entry of the enum record: the `ItemDisplayInfo.dbc` id (NOT an item id —
-/// the server already resolved the template hop) and the item's `InventoryType`. `display_id == 0`
-/// is an empty slot. 19 slots in the vanilla equipment order (head 0 … tabard 18).
+/// One visible-equipment slot: an `ItemDisplayInfo.dbc` id (not an item id, 0 for empty) and the
+/// item's `InventoryType`.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct CharEnumItem {
     pub display_id: u32,
     pub inventory_type: u8,
 }
 
-/// A character from `SMSG_CHAR_ENUM` — the full roster entry the character-select screen renders
-/// (decision 0465): identity, the five appearance bytes, zone/map/position, the display flags, the
-/// visible equipment display ids, and the **pet triple** (the hunter/warlock companion standing
-/// beside the selected character). Only the guild id, first-login byte and first-bag pair are
-/// parsed for alignment and discarded (nothing at select renders them).
+/// One `SMSG_CHAR_ENUM` roster entry.
 #[derive(Debug, Clone)]
 pub struct Character {
     pub guid: u64,
@@ -77,30 +62,26 @@ pub struct Character {
     pub class: u8,
     /// 0 male, 1 female.
     pub gender: u8,
-    /// The five appearance dials, `CharSections` indices (the create screen's tuple, echoed back).
+    /// First of the five appearance bytes, all `CharSections` indices.
     pub skin: u8,
     pub face: u8,
     pub hair_style: u8,
     pub hair_color: u8,
     pub facial_hair: u8,
     pub level: u8,
-    /// `AreaTable.dbc` id of the character's zone (the roster row's location line).
+    /// `AreaTable.dbc` id of the character's zone.
     pub zone: u32,
     pub map: u32,
     pub position: Vector3d,
-    /// `CHARACTER_FLAG_*` bits (hide-helm/hide-cloak/ghost/rename are the rendered ones).
+    /// `CHARACTER_FLAG_*` bits.
     pub flags: u32,
-    /// The 19 visible equipment slots (vanilla order: head, neck, shoulders, shirt, chest, waist,
-    /// legs, feet, wrists, hands, finger×2, trinket×2, back, main hand, off hand, ranged, tabard).
+    /// Equipment order: head, neck, shoulders, shirt, chest, waist, legs, feet, wrists, hands,
+    /// finger x2, trinket x2, back, main hand, off hand, ranged, tabard.
     pub equipment: [CharEnumItem; 19],
-    /// The pet's `CreatureDisplayInfo.dbc` id — the companion the select screen stands beside the
-    /// character. **0 = no pet**, and that one test is the whole client-side gate: the server
-    /// already suppresses the triple for anything but a living hunter/warlock (vmangos
-    /// `Player::BuildEnumData` — `!GHOST && (CLASS_WARLOCK || CLASS_HUNTER)`), so no class or
-    /// ghost check belongs here.
+    /// The pet's `CreatureDisplayInfo.dbc` id, 0 for none. The server already zeroes it for all but
+    /// a living hunter or warlock (`Player::BuildEnumData`), so the client needs no class check.
     pub pet_display_id: u32,
-    /// The pet's level, and its `CreatureFamily.dbc` id. Carried because they are the record's own
-    /// fields; **nothing renders them today** — the select screen's pet is display-id-driven.
+    /// The pet's level; `pet_family` is its `CreatureFamily.dbc` id.
     pub pet_level: u32,
     pub pet_family: u32,
 }
diff --git a/crates/benilla-protocol/src/messages/skills.rs b/crates/benilla-protocol/src/messages/skills.rs
index a8e7beca..7aab2c76 100644
--- a/crates/benilla-protocol/src/messages/skills.rs
+++ b/crates/benilla-protocol/src/messages/skills.rs
@@ -1,11 +1,6 @@
-//! Skill-line messages — the skills pane's one send verb, `CMSG_UNLEARN_SKILL` (0x202, vmangos
-//! `Opcodes.cpp`'s `DEFINE_HANDLER` → `HandleUnlearnSkillOpcode`). Body from vmangos
-//! `Server/Packets/Skill.h` (`UnlearnSkill { uint32 skillId }`); semantics from
-//! `Handlers/SkillHandler.cpp`: the server gates on the requested line's `SkillRaceClassInfo.flags
-//! & SKILL_FLAG_UNLEARNABLE (0x20)` — a request without it is DROPPED and anticheat-flagged, so
-//! the client must only ever offer the unlearn where that bit is set (the skills pane's
-//! `abandonable` predicate, `benilla-formats::skill_lines`) — and answers `SetSkill(id, 0, 0)`:
-//! the removal comes back as a `PLAYER_SKILL_INFO` field update, never an ack packet.
+//! Skill-line messages: the skills pane's `CMSG_UNLEARN_SKILL` (0x202). `HandleUnlearnSkillOpcode`
+//! drops and anticheat-flags a request for a line without `SKILL_FLAG_UNLEARNABLE` (0x20) in its
+//! `SkillRaceClassInfo.flags`; a removal comes back as a `PLAYER_SKILL_INFO` update, not an ack.
 
 /// Body of `CMSG_UNLEARN_SKILL`: one `u32` skill line id.
 pub fn unlearn_skill(skill_id: u32) -> Vec<u8> {
diff --git a/crates/benilla-protocol/src/messages/social.rs b/crates/benilla-protocol/src/messages/social.rs
index 7058a1a4..390eb591 100644
--- a/crates/benilla-protocol/src/messages/social.rs
+++ b/crates/benilla-protocol/src/messages/social.rs
@@ -1,66 +1,37 @@
-//! The social family — the friend list, the ignore list, and `/who` (opcodes 0x62–0x6d;
-//! decision 0668).
-//!
-//! Like the duel family, **both ends are pinned at the bytes**. The server side is vmangos
-//! `SocialMgr.{h,cpp}` (`PlayerSocial::SendFriendList`/`SendIgnoreList`,
-//! `SocialMgr::SendFriendStatus`), `Server/Packets/Social.{h,cpp}` (every `AppendBodyTo`),
-//! `Server/Packets/Misc.{h,cpp}` (the five client reads) and `Handlers/MiscHandler.cpp`
-//! (`HandleWhoOpcode`'s `WhoListClientQueryTask` + the add/del handlers). The client side is
-//! WoW.exe's own `FriendList.cpp` TU, recorded VERIFIED in wow-re `system/net/scratch/w2b.md`
-//! (the 0x728-byte `FriendList` object `DAT_00c28168`, its six registered SMSG handlers, and the
-//! Lua glue):
-//!
-//! | opcode | client fn | what it reads / writes |
-//! |---|---|---|
-//! | `SMSG_FRIEND_LIST` 0x67 | `FriendList::ParseFriendList 0x5ae350` | `u8` count, per slot `{guid u64, online u8, area/level/class u32}` |
-//! | `SMSG_FRIEND_STATUS` 0x68 | `0x5add30` → `HandleResult 0x5acab0` | `u8` op + `u64` guid (+ the online tail) |
-//! | `SMSG_IGNORE_LIST` 0x6b | the ignore-slot half of the same object | `u8` count, `u64` guids into the 25 slots @+0x650 |
-//! | `SMSG_WHO` 0x63 | `0x5adde0` | count-led entry list → FrameScript |
-//!
-//! Two client-side facts that shape everything above this layer, both from that TU:
-//!
-//! - **The friend/ignore lists are guids, not names.** A slot holds `{status, note*, guid, area,
-//!   level, class}` — no name — and the client resolves the display name through the **ObjectMgr
-//!   name cache** (`0x55f080`, the `CMSG_NAME_QUERY` cache) at format time. benilla's
-//!   [`NameCache`](../../../benilla/src/names.rs) plays that role, which is why a friend row can
-//!   populate a frame late rather than never.
-//! - **The client's own capacity is 50 friends / 25 ignores** (the slot arrays at `+0x008` and
-//!   `+0x650`), exactly vmangos's `SOCIALMGR_FRIEND_LIMIT` / `SOCIALMGR_IGNORE_LIMIT`. The
-//!   FrameXML's `MAX_IGNORE = 50` is dead data — the engine cap is 25.
+//! The social family: friend list, ignore list and `/who` (0x62-0x6d). The 1.12 client holds 50
+//! friends and 25 ignores (the `FriendList` slot arrays at `+0x008` and `+0x650`), the vmangos
+//! limits too; FrameXML's `MAX_IGNORE = 50` is dead data.
 
 use std::io::{self, Read};
 
 use crate::wire::{capacity_hint, read_cstring, read_u32_le, read_u64_le, read_u8};
 
-/// `SMSG_FRIEND_STATUS`'s result byte — vmangos's `FriendsResult` (`SocialMgr.h:81-110`), which is
-/// the client's own enum: `FriendList::HandleResult 0x5acab0` switches on it and displays
-/// `0x496720`'s catalog ids `0x104..0x114` (one per result, `ADDED_ONLINE`/`ADDED_OFFLINE`
-/// sharing `ERR_FRIEND_ADDED_S`). Every one of those rows routes **kind 0 = the chat frame**, not
-/// the red error line — see [`crate::messages`]'s consumer for that mapping.
+/// `SMSG_FRIEND_STATUS`'s result byte, vmangos `FriendsResult` (`SocialMgr.h:81-110`). The client
+/// (`0x5acab0`) prints each result's `ERR_*` string to the chat frame, not the red error line.
 pub mod friend_result {
-    /// `ERR_FRIEND_DB_ERROR` — the server's lookup failed.
+    /// `ERR_FRIEND_DB_ERROR`: the server's lookup failed.
     pub const DB_ERROR: u8 = 0x00;
-    /// `ERR_FRIEND_LIST_FULL` — 50 friends already.
+    /// `ERR_FRIEND_LIST_FULL`: 50 friends already.
     pub const LIST_FULL: u8 = 0x01;
-    /// `ERR_FRIEND_ONLINE_SS` — a friend just logged in (broadcast, not an ack).
+    /// `ERR_FRIEND_ONLINE_SS`: a friend just logged in (broadcast, not an ack).
     pub const ONLINE: u8 = 0x02;
-    /// `ERR_FRIEND_OFFLINE_S` — a friend just logged out (broadcast).
+    /// `ERR_FRIEND_OFFLINE_S`: a friend just logged out (broadcast).
     pub const OFFLINE: u8 = 0x03;
-    /// `ERR_FRIEND_NOT_FOUND` — no character by that name.
+    /// `ERR_FRIEND_NOT_FOUND`: no character by that name.
     pub const NOT_FOUND: u8 = 0x04;
-    /// `ERR_FRIEND_REMOVED_S` — the ack for `CMSG_DEL_FRIEND`.
+    /// `ERR_FRIEND_REMOVED_S`: the ack for `CMSG_DEL_FRIEND`.
     pub const REMOVED: u8 = 0x05;
-    /// `ERR_FRIEND_ADDED_S`, and the added friend is online — carries the online tail.
+    /// `ERR_FRIEND_ADDED_S`, friend online: carries the online tail.
     pub const ADDED_ONLINE: u8 = 0x06;
-    /// `ERR_FRIEND_ADDED_S`, added while offline — no tail.
+    /// `ERR_FRIEND_ADDED_S`, friend offline: no tail.
     pub const ADDED_OFFLINE: u8 = 0x07;
     /// `ERR_FRIEND_ALREADY_S`.
     pub const ALREADY: u8 = 0x08;
     /// `ERR_FRIEND_SELF`.
     pub const SELF: u8 = 0x09;
-    /// `ERR_FRIEND_WRONG_FACTION` — cross-faction friending, refused by config.
+    /// `ERR_FRIEND_WRONG_FACTION`: cross-faction friending, refused by config.
     pub const ENEMY: u8 = 0x0A;
-    /// `ERR_IGNORE_FULL` — 25 ignores already.
+    /// `ERR_IGNORE_FULL`: 25 ignores already.
     pub const IGNORE_FULL: u8 = 0x0B;
     /// `ERR_IGNORE_SELF`.
     pub const IGNORE_SELF: u8 = 0x0C;
@@ -68,21 +39,19 @@ pub mod friend_result {
     pub const IGNORE_NOT_FOUND: u8 = 0x0D;
     /// `ERR_IGNORE_ALREADY_S`.
     pub const IGNORE_ALREADY: u8 = 0x0E;
-    /// `ERR_IGNORE_ADDED_S` — the ack for `CMSG_ADD_IGNORE`.
+    /// `ERR_IGNORE_ADDED_S`: the ack for `CMSG_ADD_IGNORE`.
     pub const IGNORE_ADDED: u8 = 0x0F;
-    /// `ERR_IGNORE_REMOVED_S` — the ack for `CMSG_DEL_IGNORE`.
+    /// `ERR_IGNORE_REMOVED_S`: the ack for `CMSG_DEL_IGNORE`.
     pub const IGNORE_REMOVED: u8 = 0x10;
     /// `ERR_IGNORE_AMBIGUOUS`.
     pub const IGNORE_AMBIGUOUS: u8 = 0x11;
-    /// `ERR_FRIEND_ERROR` — "Unknown friend response from server."; vmangos's `FRIEND_UNKNOWN`.
+    /// `ERR_FRIEND_ERROR` ("Unknown friend response from server."), vmangos `FRIEND_UNKNOWN`.
     pub const UNKNOWN: u8 = 0x1A;
 }
 
-/// A friend slot's presence byte — vmangos's `FriendStatus` (`SocialMgr.h:36-43`). `0` is the
-/// only value the wire treats specially (it suppresses the area/level/class tail); the rest are
-/// the AFK/DND flavours the friends list renders as its `<AFK>` / `<DND>` tag.
+/// A friend's presence byte, vmangos `FriendStatus` (`SocialMgr.h:36-43`).
 pub mod friend_status {
-    /// Offline — the entry carries no area/level/class.
+    /// Offline: the entry carries no area/level/class.
     pub const OFFLINE: u8 = 0;
     /// Online, no away flag.
     pub const ONLINE: u8 = 1;
@@ -92,42 +61,29 @@ pub mod friend_status {
     pub const DND: u8 = 4;
 }
 
-/// One row of the friend list — a guid plus, when the friend is online, where they are.
-///
-/// The name is deliberately absent: it is not on the wire (see the module doc's first client-side
-/// fact) and is resolved from the name cache by the consumer.
+/// One friend-list row. The name is not on the wire: the client resolves it through its name cache
+/// (`0x55f080`, filled by `CMSG_NAME_QUERY`) when it draws the row.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub struct FriendEntry {
-    /// The friend's player guid. vmangos rebuilds it as `ObjectGuid(HIGHGUID_PLAYER, lowguid)`,
-    /// so it is always a player guid.
+    /// Always a player guid: vmangos rebuilds it as `ObjectGuid(HIGHGUID_PLAYER, lowguid)`.
     pub guid: u64,
-    /// [`friend_status`] — `OFFLINE` means the three fields below were **not** sent and read back
-    /// as zero.
+    /// A [`friend_status`]; when `OFFLINE`, the fields below were not sent and read as zero.
     pub status: u8,
-    /// The friend's zone id (`AreaTable.dbc`), `0` when offline.
+    /// The friend's zone id (`AreaTable.dbc`).
     pub area: u32,
-    /// The friend's level, `0` when offline.
     pub level: u32,
-    /// The friend's class id, `0` when offline.
     pub class: u32,
 }
 
 impl FriendEntry {
-    /// Is this friend online at all (any of ONLINE/AFK/DND)? The wire's own test — vmangos writes
-    /// the area/level/class tail under exactly `if (entry.status)`, and the client's parse reads
-    /// it under the same condition.
+    /// Any of ONLINE/AFK/DND: the wire's own test for whether the area/level/class tail is sent.
     pub fn is_online(&self) -> bool {
         self.status != friend_status::OFFLINE
     }
 }
 
-/// Read `SMSG_FRIEND_LIST` (VERIFIED vmangos `Social.cpp`
-/// `WorldPackets::Social::FriendList::AppendBodyTo`, and WoW.exe
-/// `FriendList::ParseFriendList 0x5ae350`): a `u8` count, then per friend a `u64` guid and a `u8`
-/// status — and the `u32` area/level/class triple **only when the status is non-zero**.
-///
-/// The conditional tail is why this cannot be a fixed-stride read: an offline friend is 9 bytes,
-/// an online one 21.
+/// Read `SMSG_FRIEND_LIST` (vmangos `Social.cpp`, client `0x5ae350`): a `u8` count, then per
+/// friend a `u64` guid, a `u8` status and, only if the status is non-zero, `u32` area/level/class.
 pub fn read_friend_list(r: &mut impl Read) -> io::Result<Vec<FriendEntry>> {
     let count = read_u8(r)?;
     // vmangos `SOCIALMGR_FRIEND_LIMIT` 50 (`SocialMgr.h:114`).
@@ -148,53 +104,36 @@ pub fn read_friend_list(r: &mut impl Read) -> io::Result<Vec<FriendEntry>> {
     Ok(friends)
 }
 
-/// Read `SMSG_IGNORE_LIST` (VERIFIED vmangos `Social.cpp`
-/// `WorldPackets::Social::IgnoreList::AppendBodyTo`): a `u8` count then that many full guids, and
-/// nothing else — an ignore slot in the client is 8 bytes wide for the same reason (the `+0x650`
-/// array).
+/// Read `SMSG_IGNORE_LIST` (vmangos `Social.cpp`): a `u8` count, then that many guids.
 pub fn read_ignore_list(r: &mut impl Read) -> io::Result<Vec<u64>> {
     let count = read_u8(r)?;
     (0..count).map(|_| read_u64_le(r)).collect()
 }
 
-/// `SMSG_FRIEND_STATUS` — one result code about one player, and (for the two "is online" results)
-/// where they are.
+/// `SMSG_FRIEND_STATUS`: one result about one player, with their whereabouts when online.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct FriendStatusUpdate {
-    /// A [`friend_result`] code. It is both an ack (we asked to add/remove) and a broadcast (a
-    /// friend logged in or out) — the code, not the opcode, says which.
+    /// A [`friend_result`] code, either an ack or a login/logout broadcast; the code says which.
     pub result: u8,
-    /// The player the result is about. Note vmangos sends the *asked-for* guid even for
-    /// `NOT_FOUND`, where it is `0`.
+    /// The player the result is about; 0 for `NOT_FOUND`.
     pub guid: u64,
-    /// The online tail, present iff the result is [`friend_result::ONLINE`] or
-    /// [`friend_result::ADDED_ONLINE`] (VERIFIED `SocialMgr::SendFriendStatus`'s switch).
+    /// Present only for [`friend_result::ONLINE`] and [`friend_result::ADDED_ONLINE`].
     pub online: Option<FriendOnline>,
 }
 
-/// The presence tail `SMSG_FRIEND_STATUS` carries for an online friend — the same four fields a
-/// [`FriendEntry`] holds, so a status update can refresh a list row in place.
+/// The presence tail of an online `SMSG_FRIEND_STATUS`: the four fields a [`FriendEntry`] holds.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct FriendOnline {
-    /// [`friend_status`] — 1.12 sends this byte (the `SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_8_4`
-    /// arm; the 1.8 wire had no status byte here).
+    /// A [`friend_status`] (the vmangos `SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_8_4` arm).
     pub status: u8,
     /// Zone id.
     pub area: u32,
-    /// Level.
     pub level: u32,
-    /// Class id.
     pub class: u32,
 }
 
-/// Read `SMSG_FRIEND_STATUS` (VERIFIED vmangos `Social.cpp`
-/// `WorldPackets::Social::FriendStatus::AppendBodyTo` + `SocialMgr::SendFriendStatus`; client
-/// handler `0x5add30`, which reads `u8` op + `u64` guid before handing off to
-/// `HandleResult 0x5acab0`).
-///
-/// The tail is read on the *result code*, not on a length check: only `FRIEND_ADDED_ONLINE` and
-/// `FRIEND_ONLINE` carry it. Reading it on any other code would desynchronise the parse, which is
-/// exactly why the condition is spelled out rather than "read if bytes remain".
+/// Read `SMSG_FRIEND_STATUS` (vmangos `SocialMgr::SendFriendStatus`, client `0x5add30`): `u8`
+/// result, `u64` guid, then the online tail when the result code says so, whatever the length.
 pub fn read_friend_status(r: &mut impl Read) -> io::Result<FriendStatusUpdate> {
     let result = read_u8(r)?;
     let guid = read_u64_le(r)?;
@@ -215,43 +154,32 @@ pub fn read_friend_status(r: &mut impl Read) -> io::Result<FriendStatusUpdate> {
     })
 }
 
-/// One `/who` hit. Unlike the friend list, every field is on the wire — a who result is a
-/// snapshot the server composed, not a reference into any client cache.
+/// One `/who` hit; unlike a friend row, every field is on the wire.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct WhoEntry {
-    /// Character name.
     pub name: String,
-    /// Guild name, empty when unguilded (vmangos writes `GetGuildNameById(0)` = `""`).
+    /// An empty cstring when unguilded.
     pub guild: String,
-    /// Level.
     pub level: u32,
-    /// Class id.
     pub class: u32,
-    /// Race id.
     pub race: u32,
-    /// Zone id (`AreaTable.dbc`) — the server sends the id, the client names it.
+    /// `AreaTable.dbc` zone id; the client resolves the name.
     pub zone: u32,
 }
 
-/// `SMSG_WHO` — the results, plus the two counts the "N players total (M displayed)" line needs.
+/// `SMSG_WHO`: the results and the two counts of the "N players total (M displayed)" line.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct WhoResults {
-    /// How many entries follow (`clientCount`, ≤ 49 — vmangos breaks the walk at 49 despite the
-    /// "50 is maximum" comment).
+    /// Entries that follow (`clientCount`); vmangos stops at 49.
     pub displayed: u32,
-    /// How many matched in total: the full match count when it exceeds 49, otherwise the same as
-    /// [`Self::displayed`] (VERIFIED `data.put(4, count > 49 ? count : clientCount)`).
+    /// The full match count when over 49, else equal to [`Self::displayed`].
     pub total: u32,
-    /// The entries themselves, server order.
+    /// In server order.
     pub entries: Vec<WhoEntry>,
 }
 
-/// Read `SMSG_WHO` (VERIFIED vmangos `MiscHandler.cpp`'s `WhoListClientQueryTask::operator()`):
-/// two `u32` counts, then `displayed` entries of `{name, guild, level, class, race, zone}`.
-///
-/// 1.12 does **not** carry the trailing party-status `u32` — vmangos writes it only under
-/// `SUPPORTED_CLIENT_BUILD <= CLIENT_BUILD_1_8_4`, and its own comment calls it "not actually
-/// displayed anywhere".
+/// Read `SMSG_WHO` (vmangos `WhoListClientQueryTask`, client `0x5adde0`): two `u32` counts, then
+/// `{name, guild, level, class, race, zone}` per entry. 1.12 has no trailing party-status `u32`.
 pub fn read_who(r: &mut impl Read) -> io::Result<WhoResults> {
     let displayed = read_u32_le(r)?;
     let total = read_u32_le(r)?;
@@ -273,31 +201,25 @@ pub fn read_who(r: &mut impl Read) -> io::Result<WhoResults> {
     })
 }
 
-/// A `/who` query, already parsed out of the filter string the player typed.
-///
-/// The *parsing* is engine work in the real client too (the FrameXML hands `SendWho` a raw string
-/// like `z-"Elwynn Forest" 1-10`), and it needs `AreaTable.dbc` to turn a zone name into the id
-/// the wire wants — so benilla parses it app-side, where the DBCs live, and this struct is the
-/// result. [`Default`] is the query the client sends for a bare `/who` with no terms.
+/// A `/who` query parsed from the typed filter, e.g. `z-"Elwynn Forest" 1-10`, which the 1.12
+/// engine (not FrameXML) parses for `SendWho`. [`Default`] is a bare `/who`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct WhoRequest {
     /// Inclusive minimum level.
     pub level_min: u32,
-    /// Inclusive maximum level. The real client's un-set value is **100** (vmangos's own comment:
-    /// "client send in case not set max level value 100"), not 255 — so that is the default here.
+    /// Inclusive maximum level; the 1.12 client sends 100 when unset, not 255.
     pub level_max: u32,
-    /// `n-` — a name substring, empty for "any".
+    /// `n-`: a name substring, empty for any.
     pub player_name: String,
-    /// `g-` — a guild-name substring, empty for "any".
+    /// `g-`: a guild-name substring, empty for any.
     pub guild_name: String,
-    /// `r-` — a bitmask over race ids (`1 << race`), all-ones for "any".
+    /// `r-`: a bitmask over race ids (`1 << race`), all-ones for any.
     pub race_mask: u32,
-    /// `c-` — a bitmask over class ids (`1 << class`), all-ones for "any".
+    /// `c-`: a bitmask over class ids (`1 << class`), all-ones for any.
     pub class_mask: u32,
-    /// `z-` — zone ids, resolved from names client-side. The server refuses more than 10.
+    /// `z-`: zone ids, resolved from names client-side.
     pub zones: Vec<u32>,
-    /// Untagged words: the server matches each against name, guild **and** zone name (any hit
-    /// keeps the row). Refused past 4.
+    /// Untagged words; the server matches each against name, guild and zone name.
     pub search_terms: Vec<String>,
 }
 
@@ -316,20 +238,13 @@ impl Default for WhoRequest {
     }
 }
 
-/// The server's own limits on a `/who` (`HandleWhoOpcode`: `> 10` zones or `> 4` terms and the
-/// whole packet is dropped, silently). Trimming to them client-side turns a dropped query into a
-/// narrower one.
+/// Over 10 zones or 4 search terms, `HandleWhoOpcode` silently drops the whole query.
 pub const WHO_MAX_ZONES: usize = 10;
 /// See [`WHO_MAX_ZONES`].
 pub const WHO_MAX_SEARCH_TERMS: usize = 4;
 
-/// Body of `CMSG_WHO` (VERIFIED vmangos `Misc.cpp` `WorldPackets::Misc::Who::ReadFromWorldPacket`):
-/// `levelMin`, `levelMax`, name cstring, guild cstring, `raceMask`, `classMask`, then a counted
-/// `u32` zone array and a counted cstring array — in that order.
-///
-/// Both arrays are trimmed to the server's caps ([`WHO_MAX_ZONES`], [`WHO_MAX_SEARCH_TERMS`]):
-/// over them the handler `return`s before doing anything, so an untrimmed query would look
-/// exactly like a `/who` that matched nobody.
+/// Body of `CMSG_WHO` (vmangos `Misc.cpp`, `Who::ReadFromWorldPacket`). Both arrays are trimmed to
+/// the server's caps, so an over-long query narrows instead of matching nobody.
 pub fn who(request: &WhoRequest) -> Vec<u8> {
     let zones = &request.zones[..request.zones.len().min(WHO_MAX_ZONES)];
     let terms = &request.search_terms[..request.search_terms.len().min(WHO_MAX_SEARCH_TERMS)];
@@ -352,43 +267,34 @@ pub fn who(request: &WhoRequest) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_FRIEND_LIST` (VERIFIED vmangos `Opcodes.cpp` — `NullClientPacket`): empty. The
-/// list also arrives unasked at login (`CharacterHandler.cpp:527`), so this is a refresh, which is
-/// exactly what the FrameXML's `ShowFriends()` is for.
+/// Body of `CMSG_FRIEND_LIST`: empty. The `ShowFriends()` refresh; the list also arrives unasked
+/// at login (`CharacterHandler.cpp:527`).
 pub fn friend_list() -> Vec<u8> {
     Vec::new()
 }
 
-/// Body of `CMSG_ADD_FRIEND` (VERIFIED vmangos `Misc.cpp` `AddFriend::ReadFromWorldPacket`): one
-/// cstring, the name to befriend. The server normalises the case itself
-/// (`normalizePlayerName`), so the client need not.
+/// Body of `CMSG_ADD_FRIEND`: the name; the server normalises its case (`normalizePlayerName`).
 pub fn add_friend(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_DEL_FRIEND` (VERIFIED vmangos `Misc.cpp` `DelFriend::ReadFromWorldPacket`): one
-/// full guid. Removal is by **guid**, not name — which is why the client keeps the list keyed by
-/// guid and resolves names for display only.
+/// Body of `CMSG_DEL_FRIEND`: removal is by guid, not name.
 pub fn del_friend(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_ADD_IGNORE` (VERIFIED vmangos `Misc.cpp` `AddIgnore::ReadFromWorldPacket`): one
-/// cstring, the name to ignore.
+/// Body of `CMSG_ADD_IGNORE`: the name to ignore.
 pub fn add_ignore(name: &str) -> Vec<u8> {
     cstring_body(name)
 }
 
-/// Body of `CMSG_DEL_IGNORE` (VERIFIED vmangos `Misc.cpp` `DelIgnore::ReadFromWorldPacket`): one
-/// full guid, the [`del_friend`] shape.
+/// Body of `CMSG_DEL_IGNORE`: removal is by guid.
 pub fn del_ignore(guid: u64) -> Vec<u8> {
     guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_SET_LOOKING_FOR_GROUP` (VERIFIED at the bytes, wow-re `lfg-set-get-law.md` §5,
-/// `0x4e88c0`): the three slot words as stored (`u32` LE each), then the comment as a
-/// NUL-terminated string, appended unconditionally — a packet, once sent, always carries it. The
-/// reference sends only when the commit changed something, which the caller decides.
+/// Body of `CMSG_SET_LOOKING_FOR_GROUP` (`0x4e88c0`): the three slot words as stored, then the
+/// comment cstring, always. The 1.12 client sends it only when a commit changed something.
 pub fn set_looking_for_group(slots: [u32; 3], comment: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(12 + comment.len() + 1);
     for slot in slots {
@@ -398,14 +304,12 @@ pub fn set_looking_for_group(slots: [u32; 3], comment: &str) -> Vec<u8> {
     body
 }
 
-/// A body that is exactly one NUL-terminated string.
 fn cstring_body(s: &str) -> Vec<u8> {
     let mut body = Vec::with_capacity(s.len() + 1);
     push_cstring(&mut body, s);
     body
 }
 
-/// Append a NUL-terminated string to `body`.
 fn push_cstring(body: &mut Vec<u8>, s: &str) {
     body.extend_from_slice(s.as_bytes());
     body.push(0);
@@ -415,7 +319,6 @@ fn push_cstring(body: &mut Vec<u8>, s: &str) {
 mod tests {
     use super::*;
 
-    /// `CMSG_SET_LOOKING_FOR_GROUP`: three slot words then the comment, NUL-terminated (1961).
     #[test]
     fn set_looking_for_group_is_three_words_and_a_cstring() {
         let body = set_looking_for_group([0, 0, 0], "LF2M UBRS");
@@ -428,9 +331,6 @@ mod tests {
         });
     }
 
-    /// `SMSG_FRIEND_LIST`: the area/level/class tail rides on the status byte, so an offline and
-    /// an online entry have different widths in the same packet — the parse has to follow it or
-    /// every later entry is garbage.
     #[test]
     fn friend_list_tail_is_conditional_on_the_status_byte() {
         let mut body = vec![2u8]; // count
@@ -463,7 +363,6 @@ mod tests {
         assert!(!friends[0].is_online() && friends[1].is_online());
     }
 
-    /// `SMSG_IGNORE_LIST` is a `u8` count and bare guids.
     #[test]
     fn ignore_list_is_a_counted_guid_array() {
         let mut body = vec![2u8];
@@ -475,8 +374,6 @@ mod tests {
         );
     }
 
-    /// `SMSG_FRIEND_STATUS`: only ONLINE and ADDED_ONLINE carry the presence tail. A REMOVED with
-    /// trailing bytes must still read as tail-less — the code decides, not the length.
     #[test]
     fn friend_status_tail_is_keyed_on_the_result_code() {
         let mut online = vec![friend_result::ONLINE];
@@ -507,8 +404,6 @@ mod tests {
         assert_eq!(status.online, None);
     }
 
-    /// `SMSG_WHO`: two counts, then name/guild cstrings and four `u32`s per entry. `total` can
-    /// exceed `displayed` — that difference is what the "(N displayed)" suffix reports.
     #[test]
     fn who_results_carry_both_counts() {
         let mut body = Vec::new();
@@ -538,8 +433,6 @@ mod tests {
         );
     }
 
-    /// An unguilded who row still carries its (empty) guild cstring — dropping it would eat the
-    /// next field.
     #[test]
     fn who_reads_the_empty_guild_string() {
         let mut body = Vec::new();
@@ -556,8 +449,6 @@ mod tests {
         assert_eq!(who.entries[0].level, 5);
     }
 
-    /// `CMSG_WHO`'s field order, byte for byte — the golden for the one body in this family the
-    /// server actually parses field-by-field.
     #[test]
     fn who_request_body_is_byte_exact() {
         let request = WhoRequest {
@@ -584,10 +475,9 @@ mod tests {
         assert_eq!(who(&request), want);
     }
 
-    /// The default query is the bare `/who`: every level up to the client's own 100, every race
-    /// and class, no terms.
+    /// A bare `/who` as bytes: levels 0 to 100, both names empty, every race and class, no lists.
     #[test]
-    fn the_default_who_query_is_the_clients_unset_shape() {
+    fn the_default_who_query_encodes_levels_0_to_100_with_every_filter_open() {
         let body = who(&WhoRequest::default());
         assert_eq!(&body[0..4], &0u32.to_le_bytes(), "levelMin");
         assert_eq!(&body[4..8], &100u32.to_le_bytes(), "levelMax — not 255");
@@ -599,8 +489,6 @@ mod tests {
         assert_eq!(body.len(), 26);
     }
 
-    /// Both arrays are trimmed to the server's caps: past them `HandleWhoOpcode` drops the whole
-    /// packet, so an over-long query would silently return nothing at all.
     #[test]
     fn who_trims_to_the_servers_caps() {
         let request = WhoRequest {
@@ -616,7 +504,6 @@ mod tests {
         assert_eq!(term_count as usize, WHO_MAX_SEARCH_TERMS);
     }
 
-    /// The four small client bodies: two cstrings, two bare guids.
     #[test]
     fn the_add_and_del_bodies() {
         assert_eq!(add_friend("Bob"), b"Bob\0");
diff --git a/crates/benilla-protocol/src/messages/spellbook.rs b/crates/benilla-protocol/src/messages/spellbook.rs
index e28126ad..dd946de7 100644
--- a/crates/benilla-protocol/src/messages/spellbook.rs
+++ b/crates/benilla-protocol/src/messages/spellbook.rs
@@ -1,28 +1,12 @@
-//! Spell-book and cooldown messages — what the character knows, and when they may use it again.
-//! Split out of `messages/spells.rs` (decision 0640).
-//!
-//! Book and cooldowns share a file because they share a **packet**: `SMSG_INITIAL_SPELLS` delivers
-//! the known-spell list and the active-cooldown list in one body, so [`read_initial_spells`] cannot
-//! be separated from [`SpellCooldown`] at the wire. The book then grows through
-//! `SMSG_LEARNED_SPELL` / `SMSG_SUPERCEDED_SPELL` (a trainer purchase, a quest reward, a level-up
-//! rank gain — decision 0237), and the four cooldown packets adjust it from the server side.
-//!
-//! Worth knowing before reaching for these: a **normal cast's cooldown is CLIENT-tracked**. The
-//! server only sends cooldowns for school lockouts, pets, item procs and GM resets — so these
-//! packets are the exceptions, not the mechanism. Layouts VERIFIED against vmangos and, for the four
-//! cooldown packets, against the real client's own handlers (wow-re `wave-handlers.md`).
-//!
-//! This family is inbound only; the outbound half of "what I know" is
-//! `world::writer::{skills, progression}`.
+//! Spell-book and cooldown messages, all inbound. A normal cast's cooldown is tracked by the
+//! client; the server sends cooldowns only for school lockouts, pets, item procs and GM resets.
 
 use std::io::{self, Read};
 
 use crate::wire::{capacity_hint, read_u16_le, read_u32_le, read_u64_le, read_u8};
 
-/// One active cooldown from `SMSG_INITIAL_SPELLS`' second list (vmangos `SendInitialSpells`):
-/// `u16 spell, u16 castItem, u16 category, u32 spellCdMs, u32 categoryCdMs`. A *permanent*
-/// cooldown (a one-per-fight ability the server re-arms) is `spell_cd_ms == 1` with the category
-/// word's top bit set.
+/// One active cooldown from `SMSG_INITIAL_SPELLS` (vmangos `SendInitialSpells`). A permanent one,
+/// re-armed by the server, is `spell_cd_ms == 1` with the category word's top bit set.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SpellCooldown {
     pub spell_id: u16,
@@ -32,14 +16,12 @@ pub struct SpellCooldown {
     pub category_cd_ms: u32,
 }
 
-/// Read `SMSG_INITIAL_SPELLS` (vmangos `Player::SendInitialSpells`): `u8 0; u16 n; n×(u16 spellId,
-/// u16 0); u16 m; m×`[`SpellCooldown`]. The per-spell second word is "not slot id" (vmangos's own
-/// note) and always 0 — skipped.
+/// Read `SMSG_INITIAL_SPELLS` (vmangos `Player::SendInitialSpells`): `u8 0`, a `u16` count of
+/// `{u16 spellId, u16 0}`, then a `u16` count of [`SpellCooldown`]s.
 pub(super) fn read_initial_spells(r: &mut impl Read) -> io::Result<(Vec<u16>, Vec<SpellCooldown>)> {
     let _ = read_u8(r)?;
     let n = read_u16_le(r)?;
-    // No protocol bound on either list (`Player::SendInitialSpells` walks the spell map); a
-    // 1.12 spellbook is a few hundred entries, so 1024 is generous.
+    // No protocol bound on either list; a 1.12 spellbook holds a few hundred spells.
     let mut spells = Vec::with_capacity(capacity_hint(n, 1024));
     for _ in 0..n {
         spells.push(read_u16_le(r)?);
@@ -59,40 +41,28 @@ pub(super) fn read_initial_spells(r: &mut impl Read) -> io::Result<(Vec<u16>, Ve
     Ok((spells, cooldowns))
 }
 
-/// Read `SMSG_LEARNED_SPELL` (vmangos `WorldPackets::Spell::LearnedSpell::AppendBodyTo`,
-/// `Server/Packets/Spell.cpp:175-179`): `u16 spellId, u16 actionBarSlot`. The slot is "not used on
-/// client" (vmangos's own note) and dropped. This is the one wire that grows the spell book *after*
-/// login — a trainer purchase, a quest reward, a level-up rank gain (decision 0237); benilla's book
-/// was otherwise login-only ([`read_initial_spells`]).
+/// Read `SMSG_LEARNED_SPELL` (vmangos `Spell.cpp:175-179`): `u16 spellId`, then an action-bar slot
+/// the client does not use. The one message that adds to the book after login.
 pub(super) fn read_learned_spell(r: &mut impl Read) -> io::Result<u16> {
     let spell_id = read_u16_le(r)?;
     let _action_bar_slot = read_u16_le(r)?;
     Ok(spell_id)
 }
 
-/// Read `SMSG_REMOVED_SPELL` (vmangos `RemovedSpell::AppendBodyTo`, `Server/Packets/Spell.cpp:181`):
-/// a bare `u16 spellId`, and **no action-bar slot** — unlike its `SMSG_LEARNED_SPELL` sibling above,
-/// which pads one on. The spell is gone from the book; what happens to a bar button still pointing
-/// at it is a separate law (decision 1584).
+/// Read `SMSG_REMOVED_SPELL` (vmangos `Spell.cpp:181`): a bare `u16 spellId`, no action-bar slot.
 pub(super) fn read_removed_spell(r: &mut impl Read) -> io::Result<u16> {
     read_u16_le(r)
 }
 
-/// Read `SMSG_SUPERCEDED_SPELL` (vmangos `SupercededSpell::AppendBodyTo`, `Spell.cpp:169-173`): `u16
-/// oldSpellId, u16 newSpellId` — a rank-up replaces the old spell with the new one in both the book
-/// and the action bar (decision 0237).
+/// Read `SMSG_SUPERCEDED_SPELL` (vmangos `Spell.cpp:169-173`): `(oldSpellId, newSpellId)`; a
+/// rank-up replaces the old spell in both the book and the action bar.
 pub(super) fn read_superceded_spell(r: &mut impl Read) -> io::Result<(u16, u16)> {
     Ok((read_u16_le(r)?, read_u16_le(r)?))
 }
 
-/// Read `SMSG_SPELL_COOLDOWN` → `(caster, Vec<(spell_id, cooldown_ms)>)` (VERIFIED both sides:
-/// vmangos `WorldPackets::Spell::SpellCooldown::AppendBodyTo`, `Server/Packets/Spell.cpp:142-151` —
-/// a raw `u64` guid then pairs to end-of-body, NO flags byte in 1.12 (vmangos's own commented-out
-/// `uint8`); the client handler `0x6e9460` reads exactly guid + `(GetInt32, GetUInt32)*` until the
-/// stream runs dry, wow-re `wave-handlers.md`). `cooldown_ms == 0` means "use the spell's own
-/// `Spell.dbc` RecoveryTime/CategoryRecoveryTime" (the handler's `cooldownMs!=0` fork); nonzero is
-/// a server-set duration (the school-lockout path sends these). vmangos sends this for lockouts
-/// (`Player::LockOutSpells`) and pet cooldowns — a normal cast's cooldown is CLIENT-tracked.
+/// Read `SMSG_SPELL_COOLDOWN` (vmangos `Spell.cpp:142-151`, client `0x6e9460`): a `u64` caster,
+/// then `(spell, ms)` pairs to the end, with no flags byte in 1.12. `ms == 0` means the spell's own
+/// `Spell.dbc` recovery times. Sent for school lockouts and pet cooldowns.
 pub(super) fn read_spell_cooldown(r: &mut &[u8]) -> io::Result<(u64, Vec<(u32, u32)>)> {
     let caster = read_u64_le(r)?;
     let mut cooldowns = Vec::new();
@@ -104,29 +74,21 @@ pub(super) fn read_spell_cooldown(r: &mut &[u8]) -> io::Result<(u64, Vec<(u32, u
     Ok((caster, cooldowns))
 }
 
-/// Read `SMSG_ITEM_COOLDOWN` → `(item_guid, spell_id)` (VERIFIED both sides: vmangos
-/// `WorldPackets::Item::ItemCooldown::AppendBodyTo`, `Server/Packets/Item.cpp:229-233` — raw `u64`
-/// item guid + `u32` spell id; the client handler `0x6e95d0` resolves the item object and inserts a
-/// **fixed 30 000 ms** cooldown on it, wow-re `wave-handlers.md` — the 30 s is the client's
-/// hardcode, nothing more rides the wire). Sent when a proc puts an equipped on-use item on its
-/// shared 30 s use-cooldown (vmangos `Player.cpp:19370-19383`).
+/// Read `SMSG_ITEM_COOLDOWN` (vmangos `Item.cpp:229-233`): `(item_guid, spell_id)`. The client
+/// (`0x6e95d0`) gives the item a hardcoded 30 s cooldown; no duration is on the wire.
 pub(super) fn read_item_cooldown(r: &mut impl Read) -> io::Result<(u64, u32)> {
     Ok((read_u64_le(r)?, read_u32_le(r)?))
 }
 
-/// Read `SMSG_COOLDOWN_EVENT` / `SMSG_CLEAR_COOLDOWN` → `(spell_id, caster)` — the two share one
-/// body shape (VERIFIED both sides: vmangos `CooldownEvent`/`ClearCooldown::AppendBodyTo`,
-/// `Server/Packets/Spell.cpp:152-167` — `u32` spell id THEN raw `u64` guid; the client handler
-/// `0x6e9670` reads GetInt32 then GetGuid, wow-re `wave-handlers.md`). EVENT **starts** an on-hold
-/// (`SPELL_ATTR_COOLDOWN_ON_EVENT`) record's parked timers now; CLEAR removes the record outright.
+/// Read `SMSG_COOLDOWN_EVENT` or `SMSG_CLEAR_COOLDOWN` (vmangos `Spell.cpp:152-167`, client
+/// `0x6e9670`): the `u32` spell id first, then the `u64` caster. EVENT starts the timers of an
+/// on-hold (`SPELL_ATTR_COOLDOWN_ON_EVENT`) cooldown; CLEAR removes the cooldown.
 pub(super) fn read_cooldown_event(r: &mut impl Read) -> io::Result<(u32, u64)> {
     Ok((read_u32_le(r)?, read_u64_le(r)?))
 }
 
-/// Read `SMSG_COOLDOWN_CHEAT` → the target guid (VERIFIED both sides: vmangos
-/// `CooldownCheat::AppendBodyTo` — one raw `u64`; the client handler `0x6e9730` wipes the whole
-/// self/pet cooldown list when the guid matches, wow-re `wave-handlers.md`). The GM `.cooldown`
-/// reset.
+/// Read `SMSG_COOLDOWN_CHEAT`, the GM `.cooldown` reset. The client (`0x6e9730`) clears every
+/// cooldown of the self or pet the guid names.
 pub(super) fn read_cooldown_cheat(r: &mut impl Read) -> io::Result<u64> {
     read_u64_le(r)
 }
@@ -135,10 +97,6 @@ pub(super) fn read_cooldown_cheat(r: &mut impl Read) -> io::Result<u64> {
 mod tests {
     use super::*;
 
-    /// The three incremental book packets, side by side, because their bodies differ in exactly the
-    /// way that bites: LEARNED pads an unused action-bar slot after the id, REMOVED does not pad
-    /// anything, and SUPERCEDED carries a pair. Reading REMOVED with LEARNED's reader would work by
-    /// accident on a 4-byte body and starve on the real 2-byte one.
     #[test]
     fn the_three_book_deltas_have_three_different_bodies() {
         // SMSG_LEARNED_SPELL: u16 spell + u16 slot (dropped).
@@ -158,10 +116,7 @@ mod tests {
 
     #[test]
     fn cooldown_bodies_golden() {
-        // SMSG_SPELL_COOLDOWN: raw u64 guid, then (u32 spell, u32 ms) pairs to end-of-body — NO
-        // flags byte in 1.12 (vmangos's own commented-out uint8; the client handler reads the
-        // pairs straight after the guid). Guid 0x10, then {133, 0} ("use Spell.dbc") and
-        // {5384, 30000}.
+        // SMSG_SPELL_COOLDOWN: guid, then (spell, ms) pairs, no flags byte; {133, 0} = Spell.dbc.
         let body: Vec<u8> = [
             0x10u64.to_le_bytes().to_vec(),
             133u32.to_le_bytes().to_vec(),
@@ -177,8 +132,7 @@ mod tests {
         );
         assert!(r.is_empty());
 
-        // SMSG_ITEM_COOLDOWN: raw u64 item guid + u32 spell id — nothing else (the 30 s is the
-        // client's hardcode).
+        // SMSG_ITEM_COOLDOWN: item guid + spell id, nothing else.
         let body: Vec<u8> = [
             0x40u64.to_le_bytes().to_vec(),
             439u32.to_le_bytes().to_vec(),
@@ -187,8 +141,7 @@ mod tests {
         let mut r = &body[..];
         assert_eq!(read_item_cooldown(&mut r).unwrap(), (0x40, 439));
 
-        // SMSG_COOLDOWN_EVENT / SMSG_CLEAR_COOLDOWN: u32 spell id FIRST, then the raw u64 guid
-        // (vmangos `CooldownEvent::AppendBodyTo`; the client reads GetInt32 then GetGuid).
+        // SMSG_COOLDOWN_EVENT / SMSG_CLEAR_COOLDOWN: spell id first, then the guid.
         let body: Vec<u8> = [
             1784u32.to_le_bytes().to_vec(),
             0x22u64.to_le_bytes().to_vec(),
diff --git a/crates/benilla-protocol/src/messages/spells.rs b/crates/benilla-protocol/src/messages/spells.rs
index 3f5339c6..01a0f18b 100644
--- a/crates/benilla-protocol/src/messages/spells.rs
+++ b/crates/benilla-protocol/src/messages/spells.rs
@@ -1,25 +1,6 @@
-//! The **cast pipeline** — a cast's whole life on the wire: the four outbound `CMSG_CAST_SPELL`
-//! shapes, the server's verdict, the start/launch pair every observer sees, the interrupt and
-//! pushback notices, the channel timer, and the aura a cast leaves behind. Every layout here is
-//! VERIFIED against vmangos source (cited per item); the opcodes are in [`super::opcode`] (verified
-//! `Opcodes_1_12_1.h`).
-//!
-//! This file was once the whole spell/combat/bar/progression wire in one 1061-line block; decision
-//! 0640 peeled off [`super::spellbook`], [`super::action_bar`], [`super::attack`],
-//! [`super::combat_log`], [`super::progression`] and [`super::pose`], leaving the cast itself.
-//! Mirrored by `world::writer::spells`.
-//!
-//! Two things about the shape that are easy to get wrong and are load-bearing here:
-//!
-//! - [`SpellCastTargets`]'s decode must follow vmangos' **write**-side branch order bit for bit, not
-//!   the symmetric-looking read side — the writer's if/else-if chain emits exactly one packed guid
-//!   when several target bits are set, and guessing differently desyncs the stream.
-//! - Nothing about missile travel rides `SMSG_SPELL_GO`. It is sent at **launch**; the server
-//!   schedules impact itself off `Spell.dbc` Speed (decision 0099).
-//!
-//! The aura pair lives here rather than in a family of its own because an aura is what a spell
-//! leaves behind, and the wire says so: `CMSG_CANCEL_AURA` is addressed **by spell id, not by aura
-//! slot**. Aura *state* is descriptor data (`UNIT_FIELD_AURA`), not a packet.
+//! The cast pipeline on the wire: the `CMSG_CAST_SPELL` shapes, the server's verdict, the
+//! start/launch pair every observer sees, interrupt and pushback notices, the channel timer and the
+//! aura messages. Aura state itself is descriptor data (`UNIT_FIELD_AURA`), not a packet.
 
 use std::io::{self, Read};
 
@@ -28,45 +9,24 @@ use crate::wire::{
     read_u64_le, read_u8, Vector3d,
 };
 
-/// `SMSG_CAST_RESULT`'s verdict: `u32 spellId, u8 status` — status `0` (`SPELL_RESULT_STATUS_OKAY`)
-/// ends the packet, status `2` (`SPELL_RESULT_STATUS_FAIL`) appends a `u8` failure reason and then
-/// up to two **reason-specific argument words** (vmangos `CastResult::AppendBodyTo`).
+/// `SMSG_CAST_RESULT`'s verdict: status 0 (`OKAY`) ends the packet; status 2 (`FAIL`) adds a `u8`
+/// reason and up to two argument words (vmangos `CastResult::AppendBodyTo`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum CastOutcome {
     Ok,
     Failed {
         reason: u8,
-        /// The failure's first argument word, when the server sent one — the `%s` source of the
-        /// client's argument-formatted messages (the arm table at `0x6e1d8e`): a
-        /// `SpellFocusObject.dbc` id for `REQUIRES_SPELL_FOCUS` (0x5e), an `AreaTable.dbc` id for
-        /// `REQUIRES_AREA` (0x5d), an `EquippedItemClass` for the 0x19–0x1b family, a
-        /// permanent-cooldown flag for `NOT_READY` (0x3c). `None` = the packet ended at the reason.
+        /// The `%s` of the client's message (`0x6e1d8e`): a `SpellFocusObject.dbc` id for
+        /// `REQUIRES_SPELL_FOCUS` (0x5e), an `AreaTable.dbc` id for `REQUIRES_AREA` (0x5d), an
+        /// `EquippedItemClass` for 0x19-0x1b, a permanent-cooldown flag for `NOT_READY` (0x3c).
         arg: Option<u32>,
     },
 }
 
-/// Read `SMSG_CAST_RESULT` → `(spell_id, outcome)`.
-///
-/// The trailing argument words are **positional, gated on the remaining body length** — and that
-/// is the reference's own decode, not merely a convenient one. `CastResultHandler 0x6e7330`
-/// (registered at `0x6e7155`) reads `u32 spellId`, `u8 status`, then on `status == 2` a
-/// `u8 reason`, then each word only `if cursor < size` (`0x6e737a` and `0x6e738c`, comparing
-/// CDataStore `+0x14` against `+0x10`) — never keyed off the reason value (wow-re
-/// `system/spell/scratch/cast-fail-strings.md` §WIRE-ARGS, §5 cross-checked). It has to be: vmangos
-/// writes `if (arg1 || arg2) << u32 arg1; if (arg2) << u32 arg2;`
-/// (`Server/Packets/Spell.cpp`, `CastResult::AppendBodyTo`), so a reason whose argument is
-/// legitimately 0 with no second argument behind it sends no word at all, and a reason-keyed decode
-/// would desync on exactly that case.
-///
-/// **The reference's absent value is `-1`, not zero** (`0x6e736e or eax,0xffffffff` initializes both
-/// slots before the gated reads). `None` here is that sentinel: every consumer treats it and an
-/// out-of-range id the same way — decline the fill — so the two encodings are behaviourally
-/// identical, and `Option` says which case it is at the type level.
-///
-/// The second word is read to keep the shape documented, then dropped: only the
-/// `EQUIPPED_ITEM_CLASS*` family (0x19–0x1b) sends one, and that arm's `%s` fill reads the failing
-/// spell's own `EquippedItemClass`/`EquippedItemSubClassMask` columns — the same two values the
-/// server copied out of `SpellEntry` to build the packet (`Spell::SendCastResult`).
+/// Read `SMSG_CAST_RESULT` (client `0x6e7330`). Each argument word is read only while bytes
+/// remain, never keyed on the reason, because vmangos omits a zero argument. `None` stands for
+/// the client's absent value, -1 (`0x6e736e`). The second word, sent only for 0x19-0x1b, is
+/// dropped: the client fills that message from the spell's own `EquippedItem*` columns.
 pub(super) fn read_cast_result(r: &mut &[u8]) -> io::Result<(u32, CastOutcome)> {
     let spell_id = read_u32_le(r)?;
     let status = read_u8(r)?;
@@ -81,10 +41,9 @@ pub(super) fn read_cast_result(r: &mut &[u8]) -> io::Result<(u32, CastOutcome)>
     Ok((spell_id, outcome))
 }
 
-// --- the spell-visual pipeline wire (decision 0099 phase 1) -----------------------------------------
+// --- Start and go --------------------------------------------------------------------------------
 //
-// `SpellCastTargets` bit flags (vmangos `SpellDefines.h:96-113`, `SpellCastTargetFlags`) needed to
-// decode the `write()` shape (`SpellCastTargetsInfo.cpp:180-234`) SMSG_SPELL_START/GO carry.
+// vmangos `SpellCastTargetFlags` (`SpellDefines.h:96-113`).
 const TARGET_FLAG_UNIT: u16 = 0x0002;
 const TARGET_FLAG_ITEM: u16 = 0x0010;
 const TARGET_FLAG_SOURCE_LOCATION: u16 = 0x0020;
@@ -95,20 +54,14 @@ const TARGET_FLAG_TRADE_ITEM: u16 = 0x1000;
 const TARGET_FLAG_STRING: u16 = 0x2000;
 const TARGET_FLAG_CORPSE_ALLY: u16 = 0x8000;
 
-/// A decoded `SpellCastTargets` (vmangos `SpellCastTargetsInfo.cpp:180-234`, the **write** side —
-/// asymmetric from the client→server `read()`: when more than one of UNIT/GAMEOBJECT/CORPSE_* is set,
-/// the writer's if/else-if chain emits exactly **one** packed guid, by priority UNIT > GAMEOBJECT >
-/// CORPSE_ALLY|CORPSE_ENEMY — never happens for a real spell, but the decode must follow the same
-/// branch order bit for bit or it desyncs the stream). Surfaces what a consumer needs now
-/// (`unit_target`, `go_target`, `dest`); item/corpse/source/string targets are read to keep the cursor
-/// aligned and dropped — no consumer for them yet.
+/// A decoded `SpellCastTargets` in the server's write order (`SpellCastTargetsInfo.cpp:180-234`),
+/// not its read order: any mix of UNIT, GAMEOBJECT and CORPSE_* bits yields one packed guid.
+/// Item, corpse, source and string targets are read and dropped.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct SpellCastTargets {
     pub mask: u16,
     pub unit_target: Option<u64>,
-    /// The GameObject this cast targets (`TARGET_FLAG_GAMEOBJECT`) — an open-lock cast on a chest / locked
-    /// door rides here. Surfaced for the GO lid/door open animation (decision 2271); a unit spell leaves
-    /// it `None`. Mutually exclusive with `unit_target` in practice (the writer emits one guid).
+    /// The `TARGET_FLAG_GAMEOBJECT` target, such as the chest an open-lock cast opens.
     pub go_target: Option<u64>,
     pub dest: Option<Vector3d>,
 }
@@ -124,8 +77,7 @@ fn read_spell_cast_targets(r: &mut impl Read) -> io::Result<SpellCastTargets> {
             | TARGET_FLAG_CORPSE_ALLY)
         != 0
     {
-        // Exactly one packed guid rides here (see the struct doc); the writer's priority is UNIT >
-        // GAMEOBJECT, so mirror that branch order (UNIT wins if both bits are set, never in practice).
+        // One packed guid; the server's priority is UNIT, then GAMEOBJECT, then CORPSE_*.
         let guid = read_packed_guid(r)?;
         if mask & TARGET_FLAG_UNIT != 0 {
             unit_target = Some(guid);
@@ -155,27 +107,20 @@ fn read_spell_cast_targets(r: &mut impl Read) -> io::Result<SpellCastTargets> {
     })
 }
 
-/// `CAST_FLAG_AMMO` (vmangos `Spell.h:53`) — the projectile-visual bit, set for every ranged spell on
-/// both `SMSG_SPELL_START` and `SMSG_SPELL_GO`; its presence gates the trailing ammo block.
+/// vmangos `Spell.h:53`: set on START and GO for every ranged spell; gates the ammo block.
 const CAST_FLAG_AMMO: u16 = 0x0020;
 
-/// Read the ammo block (`Spell::WriteAmmoToPacket`, `Spell.cpp:4540-4606`): `u32 displayId, u32
-/// inventoryType`. Only `displayId` has a consumer today (the projectile model, phase 4/5) —
-/// `inventoryType` is read to stay aligned and dropped.
+/// Read the ammo block (`Spell.cpp:4540-4606`): `u32 displayId`, `u32 inventoryType` (dropped).
 fn read_ammo(r: &mut impl Read) -> io::Result<u32> {
     let display_id = read_u32_le(r)?;
     let _inventory_type = read_u32_le(r)?;
     Ok(display_id)
 }
 
-/// One decoded `SMSG_SPELL_START` — a non-triggered cast began, instants included (`cast_time_ms ==
-/// 0` — the precast trigger, decision 0099 phase 1). VERIFIED vmangos `Spell::SendSpellStart`
-/// (`Spell.cpp:4468-4503`): `item_or_caster` pguid (the cast item's guid when one is in play, else
-/// the caster's own — `WriteGuidHelper`, `Spell.cpp:4453-4466`) · `caster` pguid (`m_casterUnit` —
-/// **empty, i.e. guid 0, whenever the caster is a GameObject**, which never sets that member;
-/// [`crate::events`]' `spell_caster` is what resolves the pair) · `u32 spellId` · `u16 castFlags` (always `CAST_FLAG_UNKNOWN2` 0x2, +
-/// `CAST_FLAG_AMMO` 0x20 for a ranged spell) · `u32` remaining cast-time ms (`m_timer`) ·
-/// [`SpellCastTargets`] · the ammo block iff `castFlags & 0x20`.
+/// `SMSG_SPELL_START` (vmangos `Spell.cpp:4468-4503`): a non-triggered cast began, instants
+/// included (`cast_time_ms == 0`). `item_or_caster` is the cast item's guid if any, else the
+/// caster's; `caster` is 0 for a GameObject caster. `cast_flags` is always 0x2, plus
+/// `CAST_FLAG_AMMO` for a ranged spell.
 #[derive(Debug, Clone, PartialEq)]
 pub struct SpellStart {
     pub item_or_caster: u64,
@@ -210,19 +155,14 @@ pub(super) fn read_spell_start(r: &mut impl Read) -> io::Result<SpellStart> {
     })
 }
 
-/// `SPELL_MISS_REFLECT` (vmangos `SpellDefines.h:173`) — the one `SpellMissInfo` that carries a
-/// trailing byte (the reflected spell's own outcome against its new target).
+/// vmangos `SpellDefines.h:173`: the one `SpellMissInfo` followed by a byte, the reflected
+/// spell's outcome against its new target.
 const SPELL_MISS_REFLECT: u8 = 11;
 
-/// One decoded `SMSG_SPELL_GO` — the cast launched. VERIFIED vmangos `Spell::SendSpellGo`
-/// (`Spell.cpp:4505-4538`) + its target-list writer `WriteSpellGoTargets` (`Spell.cpp:4608-4659`):
-/// the same guid pair + spellId as [`SpellStart`] (caster slot 2 empty for a GameObject caster —
-/// see there) · `u16 castFlags` (always `CAST_FLAG_UNKNOWN9`
-/// 0x100, + `CAST_FLAG_AMMO` 0x20 for a ranged spell) · `u8` hit count + that many **raw** (unpacked)
-/// `u64` hit guids · `u8` miss count + that many `{u64 guid, u8 SpellMissInfo, u8 reflectResult iff
-/// the reason is `SPELL_MISS_REFLECT`}` · [`SpellCastTargets`] · the ammo block iff `castFlags &
-/// 0x20`. Sent at **launch** — the server schedules impact itself off `Spell.dbc` Speed, so nothing
-/// about missile travel rides this packet (decision 0099).
+/// `SMSG_SPELL_GO` (vmangos `Spell.cpp:4505-4538, 4608-4659`): the cast launched. Guids and spell
+/// as in [`SpellStart`]; `cast_flags` is always 0x100, plus `CAST_FLAG_AMMO` for a ranged spell.
+/// Sent at launch: the server times the impact from `Spell.dbc` Speed, so no missile travel data
+/// rides it.
 #[derive(Debug, Clone, PartialEq)]
 pub struct SpellGo {
     pub item_or_caster: u64,
@@ -230,8 +170,7 @@ pub struct SpellGo {
     pub spell_id: u32,
     pub cast_flags: u16,
     pub hits: Vec<u64>,
-    /// `(guid, SpellMissInfo reason)` — the reflect-outcome byte (present only when `reason ==
-    /// SPELL_MISS_REFLECT`) is read to stay aligned and dropped; no consumer yet.
+    /// `(guid, SpellMissInfo)`; a reflect's trailing outcome byte is dropped.
     pub misses: Vec<(u64, u8)>,
     pub targets: SpellCastTargets,
     pub ammo_display_id: Option<u32>,
@@ -243,12 +182,11 @@ pub(super) fn read_spell_go(r: &mut impl Read) -> io::Result<SpellGo> {
     let spell_id = read_u32_le(r)?;
     let cast_flags = read_u16_le(r)?;
 
-    // Both counts are `u8` placeholders the server writes back over (`Spell.cpp:4607-4609`);
-    // no tighter bound exists.
+    // Both counts are `u8`s the server backfills (`Spell.cpp:4607-4609`); no tighter bound.
     let hit_count = read_u8(r)?;
     let mut hits = Vec::with_capacity(capacity_hint(hit_count, usize::from(u8::MAX)));
     for _ in 0..hit_count {
-        hits.push(read_u64_le(r)?); // raw guid (Spell.cpp:4627,4635) — the hit list is never packed
+        hits.push(read_u64_le(r)?); // raw guid, never packed (Spell.cpp:4627,4635)
     }
     let miss_count = read_u8(r)?;
     let mut misses = Vec::with_capacity(capacity_hint(miss_count, usize::from(u8::MAX)));
@@ -279,68 +217,41 @@ pub(super) fn read_spell_go(r: &mut impl Read) -> io::Result<SpellGo> {
     })
 }
 
-/// Read `SMSG_SPELL_FAILED_OTHER` → `(caster, spell_id)` (vmangos `Spell::SendInterrupted`,
-/// `Spell.cpp:4780-4789`): the broadcast cast-cancel notice for **observers** — a raw (unpacked)
-/// `u64` guid + `u32` spellId. Our own cast's failure rides `SMSG_CAST_RESULT` instead;
-/// `SMSG_SPELL_FAILURE` is never constructed server-side (decision 0099).
+/// Read `SMSG_SPELL_FAILED_OTHER` (vmangos `Spell.cpp:4780-4789`): an observer's cast-cancel
+/// notice, raw `u64` caster then spell id. Our own failure rides `SMSG_CAST_RESULT`; vmangos never
+/// sends `SMSG_SPELL_FAILURE`.
 pub(super) fn read_spell_failed_other(r: &mut impl Read) -> io::Result<(u64, u32)> {
     let caster = read_u64_le(r)?;
     let spell_id = read_u32_le(r)?;
     Ok((caster, spell_id))
 }
 
-/// Read `SMSG_SPELL_DELAYED` → `(caster, delay_ms)` (vmangos `Spell::Delayed`, `Spell.cpp:7472`):
-/// a raw (unpacked) `u64` caster guid + `u32` pushback time in ms, sent **to the caster** when a
-/// pushback-eligible cast takes damage (Fireball carries `DAMAGE_PUSHBACK`; the server extends its
-/// own cast timer by `delay_ms`). The cast bar shifts its window out by the same (decision 0256).
+/// Read `SMSG_SPELL_DELAYED` (vmangos `Spell.cpp:7472`): raw `u64` caster, `u32` pushback ms. Sent
+/// to the caster when damage pushes back a cast; the server extends its own cast timer by as much.
 pub(super) fn read_spell_delayed(r: &mut impl Read) -> io::Result<(u64, u32)> {
     let caster = read_u64_le(r)?;
     let delay_ms = read_u32_le(r)?;
     Ok((caster, delay_ms))
 }
 
-/// Read `MSG_CHANNEL_START` → `(spell_id, duration_ms)` (vmangos `Spell::SendChannelStart`,
-/// `Spell.cpp:4951-4954`): `u32 spellId` + `u32 duration` — **self-only** (SendDirectMessage to
-/// the casting player; no guid on the wire). The cast bar's channel-open edge (decision 0137).
+/// Read `MSG_CHANNEL_START` (vmangos `Spell.cpp:4951-4954`): `(spell_id, duration_ms)`, sent only
+/// to the caster, so no guid.
 pub(super) fn read_channel_start(r: &mut impl Read) -> io::Result<(u32, u32)> {
     let spell_id = read_u32_le(r)?;
     let duration_ms = read_u32_le(r)?;
     Ok((spell_id, duration_ms))
 }
 
-/// Read `MSG_CHANNEL_UPDATE` → `remaining_ms` (vmangos `Player::SendChannelUpdate`,
-/// `Player.cpp:21106-21110`): a single `u32` time-left — **self-only**, `0` = the channel is over
-/// (sent on natural end and on interrupt alike). The cast bar's channel tick/close (decision 0137).
+/// Read `MSG_CHANNEL_UPDATE` (vmangos `Player.cpp:21106-21110`): ms left, caster only; 0 ends the
+/// channel, whether it finished or was interrupted.
 pub(super) fn read_channel_update(r: &mut impl Read) -> io::Result<u32> {
     read_u32_le(r)
 }
 
-/// Read `SMSG_SET_FLAT_SPELL_MODIFIER` / `SMSG_SET_PCT_SPELL_MODIFIER` → `(mask_bit, op, value)`.
-///
-/// **Exactly 6 bytes, and the first byte is the one that is easy to get backwards.** The single
-/// handler `Spell_C::HandleSetSpellModifier 0x6e9950` reads `u8` (`6e9963`), `u8` (`6e996e`), `i32`
-/// (`6e9979`) — the widths are the stream accessors' own (`0x418cb0` advances the cursor by 1,
-/// `0x418e30` by 4) — and then stores at `imul eax,eax,0x1d; add eax,ecx`, i.e.
-/// **`index = field1 * 29 + field2`**. The reader `GetSpellModifiers 0x6e6b30` strength-reduces
-/// the same index to `4*op + 0x74*i` over a loop counter `i` bounded by `cmp eax,0x40`, which
-/// forces `field1 = i` (the `SpellFamilyFlags` **bit index**, 0..63) and `field2 = op` (the
-/// SpellModOp, 0..28) uniquely — and only that assignment fills the 64×29 table exactly
-/// (`29*63 + 28 == 1855`). The transposed reading addresses 47% of the array and would make the
-/// writer and the reader touch systematically disjoint cells, dropping every modifier silently.
-/// wow-re `system/spell/scratch/spellmod-table-law.md` §1/§3 — which was written to correct
-/// exactly that inversion in a note that had carried it, `verified`, for months.
-///
-/// **vmangos's writer says the same thing from the other end**, which is worth having because the
-/// client-side roles were published inverted once already: `Player::SendSpellMod`
-/// (`Objects/Player.cpp:17815`) loops `for (int eff = 0; eff < 64; ++eff)` over the modifier's
-/// 64-bit `mask` and, for each set bit, writes `uint8(eff)`, `uint8(mod->op)`, `int32(val)` — one
-/// packet per set bit, `val` the SUM of every matching modifier, i.e. absolute. `MAX_SPELLMOD`
-/// there is **29** (`Spells/SpellDefines.h`), the stride.
-///
-/// Both bytes are `movzx`-ed (unsigned); the value's signedness is fixed three independent ways by
-/// the reader (`sets dl` on the pct sum, `fild dword`, and a signed magic-divide). Neither byte is
-/// bounds-checked by the reference — that is the consumer's job, and
-/// `benilla::spell_mods::SpellModifiers` does it; this decode owns the shape only.
+/// Read `SMSG_SET_FLAT_SPELL_MODIFIER` / `SMSG_SET_PCT_SPELL_MODIFIER`: a `u8` `SpellFamilyFlags`
+/// bit index (0..63), a `u8` SpellModOp (0..28), then the `i32` sum of every matching modifier.
+/// The bit comes first: the client (`0x6e9950`) stores at `bit * 29 + op`, and vmangos
+/// (`Player.cpp:17815`) sends one packet per set bit. The client range-checks neither byte.
 pub(super) fn read_set_spell_modifier(r: &mut impl Read) -> io::Result<(u8, u8, i32)> {
     let mask_bit = read_u8(r)?;
     let op = read_u8(r)?;
@@ -348,32 +259,26 @@ pub(super) fn read_set_spell_modifier(r: &mut impl Read) -> io::Result<(u8, u8,
     Ok((mask_bit, op, value))
 }
 
-/// Read `SMSG_UPDATE_AURA_DURATION` → `(slot, remaining_ms)` (vmangos
-/// `SpellAuraHolder::UpdateAuraDuration`, `SpellAuras.cpp:7511-7523`): a `u8` `UNIT_FIELD_AURA` slot
-/// index and a `u32` of milliseconds left. **Self-only** — it goes to the aura's target, never to
-/// the caster or an onlooker — and never sent for a permanent aura, so an occupied slot that has no
-/// duration is the reference's "until cancelled" (decision 0255).
+/// Read `SMSG_UPDATE_AURA_DURATION` (vmangos `SpellAuras.cpp:7511-7523`): an aura slot and its ms
+/// left. Sent only to the aura's target and never for a permanent aura, so an occupied slot with
+/// no duration lasts until cancelled.
 pub(super) fn read_update_aura_duration(r: &mut impl Read) -> io::Result<(u8, u32)> {
     let slot = read_u8(r)?;
     let remaining_ms = read_u32_le(r)?;
     Ok((slot, remaining_ms))
 }
 
-/// Read `SMSG_PLAY_SPELL_VISUAL` → `(unit, kit_id)` (vmangos
-/// `WorldPackets::Spell::PlaySpellVisual::AppendBodyTo`, `Server/Packets/Spell.cpp:54-58`): a raw
-/// (unpacked) `u64` guid + `u32` kit id, bounds-checked against `SpellVisualKit.dbc` and played
-/// at the client's hardcoded stage 0 (`0x6e98d0` — the eat/drink cadence; decision 0280).
+/// Read `SMSG_PLAY_SPELL_VISUAL` (vmangos `Spell.cpp:54-58`): raw `u64` unit, `u32` kit id. The
+/// client (`0x6e98d0`) checks the kit against `SpellVisualKit.dbc` and plays it at stage 0.
 pub(super) fn read_play_spell_visual(r: &mut impl Read) -> io::Result<(u64, u32)> {
     let unit = read_u64_le(r)?;
     let kit_id = read_u32_le(r)?;
     Ok((unit, kit_id))
 }
 
-/// Body of `CMSG_CAST_SPELL` (vmangos `CastSpell::ReadFromWorldPacket` → `SpellCastTargets::read`):
-/// `u32 spellId` + the target block. `None` = a self/implicit cast — mask `TARGET_FLAG_SELF (0)`,
-/// nothing follows (the server fills the target from the spell's implicit targeting).
-/// `Some(guid)` = an explicit unit target — mask `TARGET_FLAG_UNIT (0x0002)` + the guid **packed**
-/// (`ReadAsPackedClientBuildAware` is the packed reader for builds > 1.8.4).
+/// Body of `CMSG_CAST_SPELL` for a self or unit target. `None` sends mask 0 (`TARGET_FLAG_SELF`)
+/// and the server applies the spell's implicit targeting; `Some` sends `TARGET_FLAG_UNIT` and the
+/// packed guid.
 pub fn cast_spell(spell_id: u32, target: Option<u64>) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&spell_id.to_le_bytes());
@@ -387,20 +292,10 @@ pub fn cast_spell(spell_id: u32, target: Option<u64>) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_CAST_SPELL` aimed at a **GameObject** (decision 0239): the OPEN_LOCK cast a
-/// right-click on a locked chest / mining vein / herb node sends instead of `CMSG_GAMEOBJ_USE`, and
-/// the targeting cursor's world commit (decision 0939). `spell_id`, then the target mask
-/// `GAMEOBJECT (0x0800)` **alone**, then the GameObject's **packed** guid — the one field that mask
-/// reads. Distinct from [`cast_spell`]'s unit/self target shape (flag `0x2` + packed guid).
-///
-/// **`TARGET_FLAG_LOCKED (0x4000)` is not in this mask** (decision 0939, correcting 0239/0769). The
-/// bit lives in the *targeting* word `0xcecac0`: the implicit-target switch ORs it there
-/// (`6e44e1: orl $0x4000, %ebx` — `%ebx` is the word that switch is accumulating, not the outgoing
-/// mask), and `BindTarget 0x6e5b40`'s GameObject arm then **consumes** it — `6e5f60 testb $0x48, %ch`
-/// on the word, `6e5f69 orb $0x8, 0xceac5d` (⇒ `0x0800`) into the wire mask, `6e5f70` clearing the
-/// word's own `0x4800`. A whole-image census of every write to the 16-bit mask at `0xceac5c` (one
-/// `movw` restore plus eleven `orb` sites) contains no `0x4000` anywhere: the real client never puts
-/// `LOCKED` on the wire, in this packet or any other.
+/// Body of `CMSG_CAST_SPELL` at a GameObject: the open-lock cast on a locked chest, vein or herb
+/// (instead of `CMSG_GAMEOBJ_USE`), or a targeting-cursor commit. The mask is `GAMEOBJECT` alone:
+/// the 1.12 client never puts `TARGET_FLAG_LOCKED` (0x4000) on the wire; `BindTarget` (`0x6e5b40`)
+/// consumes it from the targeting word, and no write to the wire mask (`0xceac5c`) sets it.
 pub fn cast_spell_gameobject(spell_id: u32, go_guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&spell_id.to_le_bytes());
@@ -409,11 +304,8 @@ pub fn cast_spell_gameobject(spell_id: u32, go_guid: u64) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_CAST_SPELL` aimed at an **ITEM** (decision 0437 phase 3): the enchant/poison
-/// cast the CraftFrame's item pick completes. `spell_id`, mask `TARGET_FLAG_ITEM (0x0010)`, then
-/// the item's **packed** guid — the one field the mask reads (vmangos `SpellCastTargets::read`,
-/// `SpellCastTargetsInfo.cpp:159-160`: `ITEM | TRADE_ITEM → one packed guid`; the trade-window
-/// sentinel form (`TRADE_ITEM 0x1000`) is the player-trade arc's, not built here).
+/// Body of `CMSG_CAST_SPELL` at an item, such as an enchant or poison: `TARGET_FLAG_ITEM` and the
+/// item's packed guid (`SpellCastTargetsInfo.cpp:159-160`).
 pub fn cast_spell_item(spell_id: u32, item_guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&spell_id.to_le_bytes());
@@ -422,12 +314,9 @@ pub fn cast_spell_item(spell_id: u32, item_guid: u64) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_CAST_SPELL` aimed at a **ground point** (decision 0792): the targeting-cursor
-/// commit for a `Targets & 0x40` spell (Blizzard, Flamestrike, Rain of Fire…). `spell_id`, mask
-/// `DEST_LOCATION (0x0040)`, then the destination as three `f32` **WoW world coords** — the one
-/// field the mask reads (vmangos `SpellCastTargets::read`, `SpellCastTargetsInfo.cpp:169-174`:
-/// `DEST_LOCATION → x,y,z`, `IsValidMapCoord`-gated). The real client ships the same shape from
-/// `SPELLCAST+0x3c..0x44` (`BindLocation 0x6e60f0` → `SendCast 0x6e54f0`, wow-re `wave-cast.md`).
+/// Body of `CMSG_CAST_SPELL` at a ground point, for a `Targets & 0x40` spell such as Blizzard:
+/// `DEST_LOCATION` and three `f32` WoW world coords (`SpellCastTargetsInfo.cpp:169-174`; client
+/// `BindLocation` `0x6e60f0`).
 pub fn cast_spell_at_dest(spell_id: u32, dest: [f32; 3]) -> Vec<u8> {
     let mut body = Vec::with_capacity(18);
     body.extend_from_slice(&spell_id.to_le_bytes());
@@ -438,16 +327,9 @@ pub fn cast_spell_at_dest(spell_id: u32, dest: [f32; 3]) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_CAST_SPELL` aimed at a **source point** (decision 2218): the targeting-cursor
-/// commit for a `Targets & 0x20` spell — the *other* half of `BindLocation 0x6e60f0`, whose bit-5
-/// arm writes `SPELLCAST+0x30..0x38` and ORs `SOURCE_LOCATION (0x0020)` into the wire mask
-/// (`6e6105`–`6e6126`), exactly as its bit-6 arm does for the dest at `+0x3c..0x44`. Same block,
-/// same three `f32` WoW world coords, one bit over (vmangos `SpellCastTargets::read`,
-/// `SpellCastTargetsInfo.cpp:161-167`: `SOURCE_LOCATION → x,y,z`, `IsValidMapCoord`-gated, read
-/// **before** the dest triple).
-///
-/// The server centres the AoE on it: `TARGET_ENUM_UNITS_ENEMY_AOE_AT_SRC_LOC (15)` fills its
-/// target map with `FillAreaTargets(…, PUSH_SRC_CENTER, …)` (`Spell.cpp:2265`).
+/// Body of `CMSG_CAST_SPELL` at a source point, for a `Targets & 0x20` spell: `SOURCE_LOCATION`
+/// and three `f32` WoW world coords (client `0x6e60f0`, `SpellCastTargetsInfo.cpp:161-167`). The
+/// server centres the AoE there (`TARGET_ENUM_UNITS_ENEMY_AOE_AT_SRC_LOC`, `Spell.cpp:2265`).
 pub fn cast_spell_at_source(spell_id: u32, src: [f32; 3]) -> Vec<u8> {
     let mut body = Vec::with_capacity(18);
     body.extend_from_slice(&spell_id.to_le_bytes());
@@ -458,11 +340,9 @@ pub fn cast_spell_at_source(spell_id: u32, src: [f32; 3]) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_CANCEL_AURA` (vmangos `WorldPackets::Spell::CancelAura`, `Server/Packets/Spell.h:55-62`):
-/// one `u32` spell id. The server cancels **by spell, not by slot** — `HandleCancelAuraOpcode`
-/// (`SpellHandler.cpp:333-405`) looks the spell up, refuses passives, `SPELL_ATTR_NO_AURA_CANCEL`
-/// spells and debuffs, then calls `RemoveAurasDueToSpellByCancel`. The wire's own
-/// `AURA_FLAG_CANCELABLE` nibble bit is the matching client-side gate (decision 0255).
+/// Body of `CMSG_CANCEL_AURA`: by spell id, not slot. `HandleCancelAuraOpcode`
+/// (`SpellHandler.cpp:333-405`) refuses passives, debuffs and `SPELL_ATTR_NO_AURA_CANCEL` spells;
+/// the client gates on the aura's `AURA_FLAG_CANCELABLE` bit.
 pub fn cancel_aura(spell_id: u32) -> Vec<u8> {
     spell_id.to_le_bytes().to_vec()
 }
@@ -473,24 +353,19 @@ mod tests {
 
     #[test]
     fn cast_spell_gameobject_body_golden() {
-        // spell_id (LE) + target mask GAMEOBJECT = 0x0800 (LE `00 08`) + packed guid 0x1234
-        // (mask 0x03, bytes 34 12). The `0x4000` LOCKED bit is deliberately absent: it is a
-        // *targeting-word* bit that `BindTarget 0x6e5b40` consumes, never a wire bit (decision
-        // 0939 — the whole-image census of writes to `0xceac5c` has no `0x4000`).
+        // spell 1, mask 0x0800 (no LOCKED 0x4000), packed guid 0x1234 (mask 0x03, bytes 34 12).
         assert_eq!(
             cast_spell_gameobject(1, 0x1234),
             [0x01, 0x00, 0x00, 0x00, 0x00, 0x08, 0x03, 0x34, 0x12],
             "CMSG_CAST_SPELL (GameObject/OPEN_LOCK) body"
         );
-        // The unit-target twin still carries flag 0x2, not 0x800 — the two shapes stay distinct.
+        // The self-cast shape stays distinct: mask 0, no guid.
         assert_eq!(cast_spell(1, None), [0x01, 0x00, 0x00, 0x00, 0x00, 0x00]);
     }
 
     #[test]
     fn cast_spell_at_dest_body_golden() {
-        // spell_id 10 (Blizzard, LE) + mask DEST_LOCATION 0x0040 (LE `40 00`) + the dest Vec3 as
-        // three f32 LE: 1.0 = 00 00 80 3F, -2.5 = 00 00 20 C0, 3.0 = 00 00 40 40. VERIFIED against
-        // vmangos `SpellCastTargets::read` (mask → DEST branch reads exactly x, y, z).
+        // Spell 10 is Blizzard.
         assert_eq!(
             cast_spell_at_dest(10, [1.0, -2.5, 3.0]),
             [
@@ -506,10 +381,7 @@ mod tests {
 
     #[test]
     fn cast_spell_at_source_body_golden() {
-        // spell_id 265 (Area Death (TEST) — Martin Fury's on-use, LE) + mask SOURCE_LOCATION
-        // 0x0020 (LE `20 00`) + the source Vec3 as three f32 LE. VERIFIED against vmangos
-        // `SpellCastTargets::read` (`SpellCastTargetsInfo.cpp:161-167`), which reads the SOURCE
-        // triple BEFORE the dest one and `IsValidMapCoord`-gates it. Decision 2218.
+        // Spell 265 is Area Death (TEST), Martin Fury's on-use.
         assert_eq!(
             cast_spell_at_source(265, [1.0, -2.5, 3.0]),
             [
@@ -521,8 +393,6 @@ mod tests {
             ],
             "CMSG_CAST_SPELL (ground source) body"
         );
-        // One bit apart from its twin, and nothing else: the two bodies differ in exactly the
-        // mask byte.
         let (src, dest) = (
             cast_spell_at_source(265, [1.0, -2.5, 3.0]),
             cast_spell_at_dest(265, [1.0, -2.5, 3.0]),
@@ -537,8 +407,7 @@ mod tests {
 
     #[test]
     fn aura_bodies_golden() {
-        // CMSG_CANCEL_AURA: a lone u32 spell id, LE. 1126 (Mark of the Wild) = 0x0000_0466. The
-        // server cancels by spell — there is no slot byte to get wrong.
+        // CMSG_CANCEL_AURA: 1126 (Mark of the Wild) = 0x0000_0466.
         assert_eq!(cancel_aura(1126), [0x66, 0x04, 0x00, 0x00]);
 
         // SMSG_UPDATE_AURA_DURATION: u8 slot, then u32 ms LE. Slot 3, 12_000 ms = 0x0000_2EE0.
@@ -551,10 +420,9 @@ mod tests {
         );
     }
 
-    /// The spell-modifier body, byte for byte — and the field ORDER, which is the whole trap.
     #[test]
     fn set_spell_modifier_body_golden() {
-        // mask_bit 35 (0x23) · op 14 (0x0e, SPELLMOD_COST) · value -30 (0xFFFF_FFE2 LE).
+        // mask_bit 35 (0x23), op 14 (0x0e, SPELLMOD_COST), value -30 (0xFFFF_FFE2 LE).
         let body = [0x23, 0x0E, 0xE2, 0xFF, 0xFF, 0xFF];
         let mut r = &body[..];
         assert_eq!(read_set_spell_modifier(&mut r).unwrap(), (35, 14, -30));
@@ -563,10 +431,7 @@ mod tests {
             "the body is exactly 6 bytes — two bytes and a dword, never three dwords"
         );
 
-        // The two bytes are NOT interchangeable, and this body is chosen so that a swap is
-        // detectable rather than plausible: 35 is a legal mask bit (0..=63) and an ILLEGAL op
-        // (0..=28), so a decode that read them the other way round would hand the consumer an op
-        // of 35 — off the end of the table's 29-wide axis.
+        // 35 is a legal mask bit (0..=63) but not a legal op (0..=28), so a swap would show.
         let (mask_bit, op, _) = read_set_spell_modifier(&mut &body[..]).unwrap();
         assert!(
             mask_bit >= 29,
@@ -574,8 +439,7 @@ mod tests {
         );
         assert!(op < 29, "field 2 is a legal op as read");
 
-        // Both bytes are unsigned (`movzx`) and the value is signed: 0xFF in field 1 is bit 255,
-        // not -1, and it is the consumer that must refuse it.
+        // Both bytes are unsigned, the value signed; the consumer must refuse bit 255.
         assert_eq!(
             read_set_spell_modifier(&mut &[0xFF, 0xFF, 0x01, 0x00, 0x00, 0x00][..]).unwrap(),
             (255, 255, 1)
@@ -583,42 +447,24 @@ mod tests {
     }
 }
 
-/// One decoded `SMSG_SPELL_UPDATE_CHAIN_TARGETS` — the **beam's hop list** (decision 0955).
-///
-/// VERIFIED on both sides. Server: vmangos `Spell::SendChannelStart` (`Spell.cpp:4970-4997`) —
-/// `ObjectGuid caster` (raw `u64`) · `u32 spellId` · `u32 count` · that many raw `u64` target
-/// guids. Client: the handler `0x6e9820` decodes exactly that shape (`GetGuid` · `GetInt32` ·
-/// `GetInt32` · `count × GetGuid`) and hands it to the array filler `0x605780`, which writes the
-/// growable array at `unit+0xd44`. The chain `CharProc` (`0x60da79`) then consumes it once and
-/// zeroes the count (`0x60db72`).
-///
-/// **This packet is NOT the only producer** (wow-re `chain-beam-law.md`, which refuted that
-/// reading at the bytes): `0x605780` has exactly two callers — this handler's `0x605767`, and
-/// **`0x6e800d`, inside `HandleSpellGo` `0x6e7a70`**. The client fills the same hop array from
-/// `SMSG_SPELL_GO`'s own hit list, which is what makes a chain spell draw on its very first cast.
-/// That matters here because vmangos only ever *sends* this packet from `SendChannelStart`, gated
-/// on `SPELL_ATTR_EX_IS_CHANNELED` — so on this server the channel beams (Drain Life, Mind Flay,
-/// Health Funnel, Corruption…) arrive by packet and the cast-stage chains (Chain Lightning, Chain
-/// Heal, Chain Burn) arrive by the GO path. Both are the reference's own mechanism; benilla's
-/// GO-derived hops are **not** a divergence (decision 0955).
+/// `SMSG_SPELL_UPDATE_CHAIN_TARGETS`: a beam's hop list (vmangos `Spell.cpp:4970-4997`, client
+/// `0x6e9820`). vmangos sends it only for channeled spells; the 1.12 client also fills the same
+/// hop array from `SMSG_SPELL_GO`'s hits (`0x6e800d`), which is how Chain Lightning draws.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SpellChainTargets {
     pub caster: u64,
     pub spell_id: u32,
-    /// The hop list in wire order. The client's filler (`0x605780`) walks it dropping any entry
-    /// equal to the caster's own guid, so that filter belongs to the consumer, not to this decode.
+    /// In wire order. The client (`0x605780`) skips any entry equal to the caster; that filter is
+    /// the consumer's.
     pub targets: Vec<u64>,
 }
 
-/// Read `SMSG_SPELL_UPDATE_CHAIN_TARGETS`. Guids are **raw** `u64` on both ends of the list — the
-/// server writes `ObjectGuid` and the client reads `GetGuid` (0x4190b0), never the packed form.
+/// Read `SMSG_SPELL_UPDATE_CHAIN_TARGETS`; every guid in it is a raw `u64`, never packed.
 pub(super) fn read_spell_chain_targets(r: &mut impl Read) -> io::Result<SpellChainTargets> {
     let caster = read_u64_le(r)?;
     let spell_id = read_u32_le(r)?;
     let count = read_u32_le(r)?;
-    // The count is server-written and unbounded on the wire; read defensively rather than
-    // pre-allocating from it (the `with_capacity` idiom the rest of this module uses is safe only
-    // where a `u8` bounds the count).
+    // The `u32` count is unbounded, so nothing is pre-allocated from it.
     let mut targets = Vec::new();
     for _ in 0..count {
         targets.push(read_u64_le(r)?);
diff --git a/crates/benilla-protocol/src/messages/stable.rs b/crates/benilla-protocol/src/messages/stable.rs
index df2491b7..16153263 100644
--- a/crates/benilla-protocol/src/messages/stable.rs
+++ b/crates/benilla-protocol/src/messages/stable.rs
@@ -1,121 +1,58 @@
-//! Stable-master messages — the hunter pet stable's wire (opcodes 623-629, vmangos
-//! `Opcodes_1_12_1.h`, VERIFIED). Bodies from vmangos `NPCHandler.cpp` (`SendStablePet` +
-//! the five `HandleStable*` handlers) and the hand-serialized `Server/Packets/Npc.{h,cpp}`
-//! (`ListStabledPets`/`StablePet`/`UnstablePet`/`BuyStableSlot`/`StableSwapPet`/`StableResult`).
-//!
-//! **The shape of the system.** A stable master keeps a hunter's pets in **three places**: the one
-//! *current* pet walking beside the player, plus up to two *stable* slots that must each be bought
-//! with gold (`Player::m_stableSlots`, `StableSlotPrices.dbc`). The window (`PetStableFrame`) is
-//! opened by the gossip stable option, which makes the server send `MSG_LIST_STABLED_PETS`
-//! unprompted — the same opcode the client sends back as the *refresh* verb (it is an `MSG_`, one
-//! number in both directions). Every mutation is a single-verb ask answered by one
-//! `SMSG_STABLE_RESULT` byte and **nothing else**: the list is not resent, so a client that acted
-//! successfully re-asks with [`list_stabled_pets`] to repaint.
-//!
-//! **Slots are 1-based on the wire and 0-based in the client**, and this module absorbs the
-//! difference exactly once — see [`StabledPet::slot`]. The rest of benilla only ever sees the
-//! client's own indices (`0` = the current pet, `1..=NUM_PET_STABLE_SLOTS`).
-//!
-//! Only *hunter* pets reach the stable: vmangos gates every verb on `HUNTER_PET`, so a warlock at a
-//! stable master gets an empty list. Decision 1676.
+//! Stable-master messages (623-629; vmangos `NPCHandler.cpp`, `Server/Packets/Npc.cpp`): a
+//! hunter's current pet plus up to two bought stable slots. The gossip stable option makes the
+//! server send `MSG_LIST_STABLED_PETS`; every other verb gets only a `SMSG_STABLE_RESULT` byte,
+//! never a fresh list. Only hunter pets are listed, so a warlock sees an empty stable.
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_cstring, read_u32_le, read_u64_le, read_u8};
 
-/// One row of `MSG_LIST_STABLED_PETS` (vmangos `WorldSession::SendStablePet`,
-/// `NPCHandler.cpp:522-575`) — a pet the stable master can show, whether it is the one currently at
-/// the player's side or one asleep in a stable slot.
-///
-/// The wire record is `u32 petNumber, u32 creatureEntry, u32 level, cstring name, u32 loyalty,
-/// u8 slot`. Note what is *not* on it: no display id and no family — a stabled pet has no world
-/// object to read either from, so drawing its portrait takes a `CMSG_CREATURE_QUERY` on
-/// [`creature_entry`](Self::creature_entry) (which is why that response's display id is kept,
-/// decision 1676).
+/// One `MSG_LIST_STABLED_PETS` row (vmangos `NPCHandler.cpp:522-575`), the current pet or a
+/// stabled one. It has no display id or family; those come from a creature query on the entry.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct StabledPet {
-    /// The pet's own id — vmangos's `character_pet.id`, the same number
-    /// [`crate::guid::pet_number`] reads out of a live pet's guid. This, **not** the slot, is what
-    /// [`unstable_pet`] and [`stable_swap_pet`] name.
+    /// vmangos `character_pet.id`; [`unstable_pet`] and [`stable_swap_pet`] take this, not a slot.
     pub pet_number: u32,
-    /// `creature_template` entry (`Pet::GetEntry()` / `character_pet.entry`) — **not** a display
-    /// id. Feed it to `CMSG_CREATURE_QUERY` to get the name, family and display id the window's
-    /// icon and diet tooltip need.
+    /// A `creature_template` entry, not a display id.
     pub creature_entry: u32,
-    /// The pet's level.
     pub level: u32,
-    /// The pet's name — the one the hunter gave it, not the creature template's.
+    /// The name the hunter gave it, not the template's.
     pub name: String,
-    /// Loyalty **level** 1..6 (`LoyaltyLevel`, vmangos `Pet.h:57-65`: Rebellious … Best Friend) — a
-    /// `PetLoyalty.dbc` row id the client renders as a string, never a string on the wire.
+    /// Loyalty level 1..6 (`Pet.h:57-65`), a `PetLoyalty.dbc` row id, not a string.
     pub loyalty: u32,
-    /// **Client** slot index, already rebased: `0` = the current pet, `1..=2` = the two stable
-    /// slots.
-    ///
-    /// The wire byte is 1-based over vmangos's own 0-based `character_pet.slot`: `SendStablePet`
-    /// writes a literal `0x01` for the current pet (`PET_SAVE_AS_CURRENT` = 0) and `it->slot + 1`
-    /// for a stabled one, where `PET_SAVE_FIRST_STABLE_SLOT` = 1 and `PET_SAVE_LAST_STABLE_SLOT` =
-    /// `MAX_PET_STABLES` = 2 (`Pet.h:37-48`). The reference UI indexes `0` (current) through
-    /// `NUM_PET_STABLE_SLOTS`, so **client index = wire slot − 1** — done once, here, so no
-    /// consumer has to rediscover a ±1.
+    /// The client's index: 0 is the current pet, 1..=2 the stable slots. The wire byte is one
+    /// higher (`SendStablePet` writes `character_pet.slot + 1`) and is rebased here, once.
     pub slot: u8,
 }
 
-/// `SMSG_STABLE_RESULT`'s one `u8` — the whole answer to every stable verb (vmangos's
-/// `StableResultCode`, `NPCHandler.cpp:40-47`, VERIFIED). Nothing else comes back: the list is
-/// **not** resent, so a success is a cue to re-ask with [`list_stabled_pets`].
+/// `SMSG_STABLE_RESULT` codes, vmangos `StableResultCode` (`NPCHandler.cpp:40-47`).
 pub mod stable_result {
-    /// `STABLE_ERR_MONEY` — not enough gold for the next stable slot. Only [`super::buy_stable_slot`]
-    /// produces it (`HandleBuyStableSlot`, `NPCHandler.cpp:704-729`).
+    /// `STABLE_ERR_MONEY`: not enough gold for the next slot; only a slot purchase gets it.
     pub const ERR_MONEY: u8 = 0x01;
-    /// `STABLE_ERR_STABLE` — the catch-all failure, and the answer to *every* refusal except the
-    /// money one: dead player, not a real stable master (or out of interact range), no live hunter
-    /// pet to stable, all bought slots full, an unknown/untameable pet number, a pet already out
-    /// when unstabling, a failed load from the DB, or buying a fourth slot. It carries no reason —
-    /// the client cannot tell those cases apart, and neither can we.
+    /// `STABLE_ERR_STABLE`: every refusal but the money one, with no reason attached.
     pub const ERR_STABLE: u8 = 0x06;
-    /// `STABLE_SUCCESS_STABLE` — the current pet went into the first free stable slot
-    /// ([`super::stable_pet`]).
+    /// `STABLE_SUCCESS_STABLE`: the current pet went into the first free stable slot.
     pub const SUCCESS_STABLE: u8 = 0x08;
-    /// `STABLE_SUCCESS_UNSTABLE` — a stabled pet is now the current pet. Sent for **both**
-    /// [`super::unstable_pet`] and a successful [`super::stable_swap_pet`] (vmangos
-    /// `HandleStableSwapPet` ends on this same code), so it does not identify which verb was used.
+    /// `STABLE_SUCCESS_UNSTABLE`: a stabled pet is now current, after an unstable or a swap.
     pub const SUCCESS_UNSTABLE: u8 = 0x09;
-    /// `STABLE_SUCCESS_BUY_SLOT` — a stable slot was purchased; the gold is already gone and
-    /// `m_stableSlots` has advanced, visible on the next list's `num_stable_slots`.
+    /// `STABLE_SUCCESS_BUY_SLOT`: a slot was bought; the next list's slot count shows it.
     pub const SUCCESS_BUY_SLOT: u8 = 0x0A;
 }
 
-/// Body of `MSG_LIST_STABLED_PETS` sent **client → server** (vmangos `Npc.cpp:51-54`,
-/// `ListStabledPets::ReadFromWorldPacket`): one full 8-byte stable-master guid.
-///
-/// The *refresh* verb, not the open verb: the window first appears off the gossip stable option,
-/// which has the server send this same opcode inbound unprompted. Re-ask after any successful
-/// mutation — `SMSG_STABLE_RESULT` is the entire answer to those, and the server never resends the
-/// list on its own.
+/// Body of `MSG_LIST_STABLED_PETS` from the client (`Npc.cpp:51-54`): the refresh, needed after
+/// every successful verb because the server never resends the list.
 pub fn list_stabled_pets(npc_guid: u64) -> Vec<u8> {
     npc_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_STABLE_PET` (vmangos `Npc.cpp:56-59`, `StablePet::ReadFromWorldPacket`): one full
-/// 8-byte stable-master guid.
-///
-/// **It carries no slot** — the surprising part. The server picks the destination itself:
-/// `HandleStablePet` (`NPCHandler.cpp:609-655`) walks `PET_SAVE_FIRST_STABLE_SLOT..=
-/// PET_SAVE_LAST_STABLE_SLOT`, takes the first slot no `character_pet` row occupies, and refuses
-/// with [`stable_result::ERR_STABLE`] if that index exceeds the number of slots the player has
-/// bought. So there is no "stable into slot 2" intent to express, and a UI that lets the player
-/// drop a pet onto a particular empty slot is describing a placement the wire cannot carry.
+/// Body of `CMSG_STABLE_PET` (`Npc.cpp:56-59`). It carries no slot: the server takes the first
+/// free bought slot or refuses (`HandleStablePet`, `NPCHandler.cpp:609-655`).
 pub fn stable_pet(npc_guid: u64) -> Vec<u8> {
     npc_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_UNSTABLE_PET` (vmangos `Npc.cpp:61-65`, `UnstablePet::ReadFromWorldPacket`): `u64
-/// npcGuid, u32 petNumber` — the [`StabledPet::pet_number`] of the chosen row, never its slot.
-///
-/// Summons that pet as the current pet. Refused with [`stable_result::ERR_STABLE`] when the player
-/// already *has* a pet — even an unsummoned one that is merely out of range
-/// (`HandleUnstablePet`, `NPCHandler.cpp:657-702`); trading places is [`stable_swap_pet`]'s job.
+/// Body of `CMSG_UNSTABLE_PET` (`Npc.cpp:61-65`): makes the pet current. Refused while the player
+/// has any pet, even one out of range (`NPCHandler.cpp:657-702`); swapping is [`stable_swap_pet`].
 pub fn unstable_pet(npc_guid: u64, pet_number: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&npc_guid.to_le_bytes());
@@ -123,25 +60,14 @@ pub fn unstable_pet(npc_guid: u64, pet_number: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_BUY_STABLE_SLOT` (vmangos `Npc.cpp:67-70`, `BuyStableSlot::ReadFromWorldPacket`):
-/// one full 8-byte stable-master guid.
-///
-/// Like the bank's slot purchase, the *which* is implicit: the server buys slot
-/// `m_stableSlots + 1`, prices it from `StableSlotPrices.dbc` at that row, and answers
-/// [`stable_result::SUCCESS_BUY_SLOT`], [`stable_result::ERR_MONEY`], or — past `MAX_PET_STABLES`
-/// (2) — [`stable_result::ERR_STABLE`] (`HandleBuyStableSlot`, `NPCHandler.cpp:704-729`). Knowing
-/// the next price is the client's own job, read from that DBC.
+/// Body of `CMSG_BUY_STABLE_SLOT` (`Npc.cpp:67-70`): buys the next slot at its
+/// `StableSlotPrices.dbc` price, which the client reads itself (`NPCHandler.cpp:704-729`).
 pub fn buy_stable_slot(npc_guid: u64) -> Vec<u8> {
     npc_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_STABLE_SWAP_PET` (vmangos `Npc.cpp:72-76`, `StableSwapPet::ReadFromWorldPacket`):
-/// `u64 npcGuid, u32 petNumber` — same shape as [`unstable_pet`], and the verb to use when the
-/// player *already* has a current pet.
-///
-/// The current pet takes the named pet's stable slot and the named pet is summoned, in one step
-/// (`HandleStableSwapPet`, `NPCHandler.cpp:735-789`). Success answers
-/// [`stable_result::SUCCESS_UNSTABLE`] — the same code a plain unstable returns.
+/// Body of `CMSG_STABLE_SWAP_PET` (`Npc.cpp:72-76`): the current pet and the named one trade
+/// places in one step (`NPCHandler.cpp:735-789`).
 pub fn stable_swap_pet(npc_guid: u64, pet_number: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&npc_guid.to_le_bytes());
@@ -149,26 +75,11 @@ pub fn stable_swap_pet(npc_guid: u64, pet_number: u32) -> Vec<u8> {
     body
 }
 
-// No `CMSG_STABLE_REVIVE_PET` (0x0274) send verb, deliberately: vmangos's
-// `HandleStableRevivePet` (`NPCHandler.cpp:731-733`) is an empty no-op, and whether the 5875 client
-// ever puts that opcode on the wire is an open RE question — nothing here can be verified against a
-// handler that does nothing. If a capture ever shows the reference client sending it, the verb gets
-// added then, from that evidence (decision 1676).
+// No `CMSG_STABLE_REVIVE_PET` (0x0274) verb: vmangos's handler is empty (`NPCHandler.cpp:731`).
 
-/// Read `MSG_LIST_STABLED_PETS` arriving **server → client** (vmangos
-/// `WorldSession::SendStablePet`, `NPCHandler.cpp:522-575`): `u64 npcGuid, u8 numPets, u8
-/// numStableSlots, numPets ×` [`StabledPet`] (a variable-length record — the name is a cstring).
-/// Returns `(npc, num_stable_slots, pets)`.
-///
-/// `num_stable_slots` is `Player::m_stableSlots` — how many slots are **purchased** (0..=2), which
-/// is what greys the unbought ones and drives the "buy the next slot" price line; it is *not* a
-/// count of occupied slots.
-///
-/// **The current pet's row may be absent.** vmangos emits a slot-0 row only when the player has a
-/// live `HUNTER_PET` or a cached `character_pet` for one that has despawned; a warlock, or a hunter
-/// with no pet at all, simply gets a list whose rows are all stabled ones (or none). So `pets[0]`
-/// is not the current pet — the rows are keyed by their own [`StabledPet::slot`], and a consumer
-/// must look the slot up rather than index positionally.
+/// Read `MSG_LIST_STABLED_PETS` from the server (`NPCHandler.cpp:522-575`). The slot count is how
+/// many are bought (0..=2), not occupied. The current pet's row may be missing, so find rows by
+/// [`StabledPet::slot`], not position.
 pub(super) fn read_list_stabled_pets(r: &mut &[u8]) -> io::Result<(u64, u8, Vec<StabledPet>)> {
     let npc = read_u64_le(r)?;
     let num_pets = read_u8(r)?;
@@ -183,17 +94,14 @@ pub(super) fn read_list_stabled_pets(r: &mut &[u8]) -> io::Result<(u64, u8, Vec<
             level: read_u32_le(r)?,
             name: read_cstring(r)?,
             loyalty: read_u32_le(r)?,
-            // Wire slot is 1-based (see `StabledPet::slot`); rebase to the client's own index here,
-            // once. `saturating_sub` rather than `- 1` only so a malformed 0 can't wrap to 255 —
-            // vmangos never writes one.
+            // 1-based on the wire; saturating so a malformed 0 cannot wrap to 255.
             slot: read_u8(r)?.saturating_sub(1),
         });
     }
     Ok((npc, num_stable_slots, pets))
 }
 
-/// Read `SMSG_STABLE_RESULT` (vmangos `StableResult::AppendBodyTo`, `Npc.cpp:99-102`): one
-/// [`stable_result`] byte, and the complete answer to every stable verb.
+/// Read `SMSG_STABLE_RESULT` (`Npc.cpp:99-102`): one [`stable_result`] byte.
 pub(super) fn read_stable_result(r: &mut &[u8]) -> io::Result<u8> {
     read_u8(r)
 }
diff --git a/crates/benilla-protocol/src/messages/summon.rs b/crates/benilla-protocol/src/messages/summon.rs
index 8a0718c7..e1502d44 100644
--- a/crates/benilla-protocol/src/messages/summon.rs
+++ b/crates/benilla-protocol/src/messages/summon.rs
@@ -1,52 +1,24 @@
-//! The player-summon family — the server's question and the client's one-word answer
-//! (opcodes 683 and 684; decision 1747).
-//!
-//! Two packets, and the asymmetry between them is the whole story. A warlock's Ritual of
-//! Summoning, a meeting stone, or a GM's `.summon` all end in the *server* asking the summoned
-//! player `SMSG_SUMMON_REQUEST`; the client parks the three fields and puts the `CONFIRM_SUMMON`
-//! dialog up. Accepting sends `CMSG_SUMMON_RESPONSE` carrying **the summoner's guid and nothing
-//! else** — there is no accept/decline byte in 1.12, because **declining sends no packet at all**
-//! and the server auto-declines on its own timer.
-//!
-//! | opcode | direction | body |
-//! |---|---|---|
-//! | `SMSG_SUMMON_REQUEST` 0x2ab | in | `u64` summoner guid + `u32` zone id + `u32` delay ms |
-//! | `CMSG_SUMMON_RESPONSE` 0x2ac | out | `u64` summoner guid |
-//!
-//! **Byte-pinned client-side**, not inferred from the server: the 1.12.1 handler `0x5e6140` (the
-//! `0x5ab650` registration site maps `0x2ab` to it) reads exactly three fields in this order —
-//! `CDataStore::GetGuid 0x4190b0`, `CDataStore::GetInt32 0x418e30`, `CDataStore::GetUInt32_2
-//! 0x418fb0` — and the accept binding `ConfirmSummon 0x48b770` writes opcode `0x2ac` followed by
-//! one `CDataStore::PutGuid 0x418370` and sends (`ClientServices::Send 0x5ab630`). Nothing else
-//! goes into either body.
-//!
-//! vmangos agrees on both, independently: `Server/Packets/Misc.cpp`'s
-//! `SummonRequest::AppendBodyTo` writes `summonerGuid; zoneId; autoDeclineDelay`, and
-//! `SummonResponse::ReadFromWorldPacket` reads **only** `summonerGuid` — then ignores it, calling
-//! `Player::SummonIfPossible(true)` off its own `m_summon_expire` window
-//! (`Handlers/MovementHandler.cpp`). So the guid is an echo the server does not check; what makes
-//! a stale accept harmless is the server's timer, not the guid.
+//! The player summon: `SMSG_SUMMON_REQUEST` (0x2ab, client `0x5e6140`) and the accept,
+//! `CMSG_SUMMON_RESPONSE` (0x2ac, `ConfirmSummon` `0x48b770`). There is no decline packet: the
+//! server declines on its own timer.
 
 use std::io;
 
 use crate::wire::{read_u32_le, read_u64_le};
 
-/// `SMSG_SUMMON_REQUEST` — someone is asking to pull us to them.
+/// `SMSG_SUMMON_REQUEST`: someone is asking to pull us to them.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SummonRequest {
-    /// Who is summoning. Echoed back in [`summon_response`], and it is the guid
-    /// `GetSummonConfirmSummoner()` resolves through the name cache.
+    /// Echoed in [`summon_response`]; `GetSummonConfirmSummoner()` names it from the name cache.
     pub summoner: u64,
-    /// The **summoner's** zone — an `AreaTable.dbc` id, which is the whole of what
-    /// `GetSummonConfirmAreaName()` looks up. Not our own zone, and not a map id.
+    /// The summoner's `AreaTable.dbc` zone id, not ours and not a map id.
     pub zone: u32,
-    /// Milliseconds until the server auto-declines (vmangos `MAX_PLAYER_SUMMON_DELAY * 1000`, two
-    /// minutes). The client turns it into a deadline the moment the packet lands and counts down
-    /// against it; the dialog takes itself off screen when it runs out.
+    /// Ms until the server auto-declines (vmangos `MAX_PLAYER_SUMMON_DELAY`, two minutes); the
+    /// client counts down from arrival and closes the dialog at zero.
     pub delay_ms: u32,
 }
 
-/// Read `SMSG_SUMMON_REQUEST`: guid, zone, delay — see the module header for the byte pin.
+/// Read `SMSG_SUMMON_REQUEST`: guid, zone, delay.
 pub(super) fn read_summon_request(r: &mut &[u8]) -> io::Result<SummonRequest> {
     Ok(SummonRequest {
         summoner: read_u64_le(r)?,
@@ -55,12 +27,8 @@ pub(super) fn read_summon_request(r: &mut &[u8]) -> io::Result<SummonRequest> {
     })
 }
 
-/// Body of `CMSG_SUMMON_RESPONSE`: the summoner's full 8-byte guid, and nothing after it.
-///
-/// **Decorative on vmangos, and still the right thing to send**: its handler reads the guid and
-/// never looks at it again. The client's own `ConfirmSummon 0x48b770` puts the latched guid here,
-/// so a server that *does* check it (or a future one that must distinguish two pending summons)
-/// gets what the reference would have sent.
+/// Body of `CMSG_SUMMON_RESPONSE`: the summoner's guid, nothing else. vmangos ignores it and
+/// relies on its own expiry timer.
 pub fn summon_response(summoner_guid: u64) -> Vec<u8> {
     summoner_guid.to_le_bytes().to_vec()
 }
@@ -69,9 +37,6 @@ pub fn summon_response(summoner_guid: u64) -> Vec<u8> {
 mod tests {
     use super::*;
 
-    /// The request body is the three fields in wire order, and the reader must not reorder the
-    /// two `u32`s — a swapped pair would name the zone by a millisecond count and count down two
-    /// minutes' worth of area ids, both of which read as "the dialog is just wrong".
     #[test]
     fn the_request_body_is_guid_then_zone_then_delay() {
         let mut bytes = 0xF130_0000_0001_2345u64.to_le_bytes().to_vec();
@@ -87,16 +52,12 @@ mod tests {
         );
     }
 
-    /// A truncated body is an error, not a zero-filled request: a half-read packet that latched
-    /// would put a dialog up naming nobody, for no time.
     #[test]
     fn a_short_request_body_is_an_error() {
         let bytes = [0u8; 15];
         assert!(read_summon_request(&mut &bytes[..]).is_err());
     }
 
-    /// The answer is one little-endian guid — the shape vmangos's `SummonResponse` reads back,
-    /// and byte-for-byte what `ConfirmSummon 0x48b770` puts on the wire.
     #[test]
     fn the_response_body_is_one_little_endian_guid_and_nothing_else() {
         assert_eq!(
diff --git a/crates/benilla-protocol/src/messages/tabard.rs b/crates/benilla-protocol/src/messages/tabard.rs
index c6c85ab8..cdf81db4 100644
--- a/crates/benilla-protocol/src/messages/tabard.rs
+++ b/crates/benilla-protocol/src/messages/tabard.rs
@@ -1,21 +1,12 @@
-//! The guild tabard designer's wire (decision 1977; wow-re `system/ui/scratch/tabard-designer.md`
-//! §4, VERIFIED at the bytes): two `MSG_*` opcodes used in both directions, and the battlemaster
-//! greeting the same TU ships beside them.
-//!
-//! - `MSG_TABARDVENDOR_ACTIVATE 0x1F2` — out: `u64 npcGuid` (the NPC-click ladder's
-//!   TABARDDESIGNER arm, `0x5e00e0`); in: `u64 vendorGuid`, the only thing that opens the frame
-//!   (`0x5e70c0` → `0x4f5840`).
-//! - `MSG_SAVE_GUILD_EMBLEM 0x1F1` — out: `u64 vendorGuid` then the five `u32` design values in
-//!   the order *emblemStyle, emblemColor, borderStyle, borderColor, backgroundColor* (`0x5e03f0`);
-//!   in: one `u32` result (`0x5e70f0`), indexed into a six-row message table.
-//! - `CMSG_BATTLEMASTER_HELLO 0x2D7` — out: `u64 npcGuid`, no gate (`0x5e01a0`).
+//! The guild tabard designer's wire, two `MSG_*` opcodes used both ways, plus the battlemaster
+//! greeting.
 
 use std::io::{self, Read};
 
 use crate::wire::{read_u32_le, read_u64_le};
 
-/// Body of `MSG_SAVE_GUILD_EMBLEM` outbound: the vendor guid raw little-endian (not packed), then
-/// the five design values as `u32`s in the designer's slot order.
+/// Body of `MSG_SAVE_GUILD_EMBLEM` (0x1F1, client `0x5e03f0`): the raw vendor guid, then emblem
+/// style, emblem color, border style, border color and background color as `u32`s.
 pub fn save_guild_emblem(vendor: u64, design: [u32; 5]) -> Vec<u8> {
     let mut body = vendor.to_le_bytes().to_vec();
     for v in design {
@@ -24,29 +15,28 @@ pub fn save_guild_emblem(vendor: u64, design: [u32; 5]) -> Vec<u8> {
     body
 }
 
-/// Body of `MSG_TABARDVENDOR_ACTIVATE` outbound: the NPC guid and nothing else.
+/// Body of `MSG_TABARDVENDOR_ACTIVATE` (0x1F2, client `0x5e00e0`): the NPC guid.
 pub fn tabard_vendor_activate(npc: u64) -> Vec<u8> {
     npc.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_BATTLEMASTER_HELLO`: the NPC guid and nothing else.
+/// Body of `CMSG_BATTLEMASTER_HELLO` (0x2D7, client `0x5e01a0`, no gate): the NPC guid.
 pub fn battlemaster_hello(npc: u64) -> Vec<u8> {
     npc.to_le_bytes().to_vec()
 }
 
-/// `MSG_SAVE_GUILD_EMBLEM` inbound: one `u32` result.
+/// `MSG_SAVE_GUILD_EMBLEM` inbound (client `0x5e70f0`): the result row.
 pub(super) fn read_save_guild_emblem_result(r: &mut impl Read) -> io::Result<u32> {
     read_u32_le(r)
 }
 
-/// `MSG_TABARDVENDOR_ACTIVATE` inbound: the vendor guid.
+/// `MSG_TABARDVENDOR_ACTIVATE` inbound (`0x5e70c0`): the vendor guid. Only this opens the frame.
 pub(super) fn read_tabard_vendor_activate(r: &mut impl Read) -> io::Result<u64> {
     read_u64_le(r)
 }
 
-/// The reply handler's result table (`0x85fe88`, six rows — the consumer's own `0 ≤ result < 6`
-/// bound): the message-catalog key each result shows, `None` for row 5, the `0x1d1` sentinel that
-/// shows nothing. A result past the table is ignored outright.
+/// The reply's message keys (`0x85fe88`); row 5 is the `0x1d1` sentinel that shows nothing, and a
+/// result past the table is ignored.
 pub const GUILD_EMBLEM_RESULT_MESSAGES: [Option<&str>; 6] = [
     Some("ERR_GUILDEMBLEM_SUCCESS"),
     Some("ERR_GUILDEMBLEM_INVALID_TABARD_COLORS"),
diff --git a/crates/benilla-protocol/src/messages/taxi.rs b/crates/benilla-protocol/src/messages/taxi.rs
index dee70ac1..0424d318 100644
--- a/crates/benilla-protocol/src/messages/taxi.rs
+++ b/crates/benilla-protocol/src/messages/taxi.rs
@@ -1,29 +1,17 @@
-//! Taxi/flight-master messages — the "right-click a flight master → pick a destination → fly"
-//! wire (opcodes 425-431 + 786, vmangos `Opcodes_1_12_1.h`, VERIFIED; decision 0484). Bodies from
-//! vmangos `Handlers/TaxiHandler.cpp` (the SMSG writers) and the hand-serialized
-//! `Server/Packets/Taxi.{h,cpp}` (the CMSG readers + the two hand-serialized SMSGs,
-//! `TaxiNodeStatus`/`ActivateTaxiReply`/`NewTaxiPath`). Every guid on this wire, both directions,
-//! is a **plain** u64 — `ObjectGuid`'s own `ByteBuffer` stream operators (`ObjectGuid.cpp:174-186`)
-//! read/write the raw value; `PackedGuid` is a distinct type these packets never reach for. The
-//! flight itself (`SMSG_MONSTER_MOVE`, the mount rails) rides existing wire families
-//! (`messages::monster_move`, decision 0441) — this module is only the menu + activate send.
+//! Flight-master messages (425-431, 786; vmangos `TaxiHandler.cpp`, `Server/Packets/Taxi.cpp`).
+//! Every guid here, both ways, is a plain `u64`, never packed (`ObjectGuid.cpp:174-186`).
 
 use std::io;
 
 use crate::wire::{read_u32_le, read_u64_le, read_u8};
 
-/// The known-node bitmask (`SHOWTAXINODES`'s tail; vmangos `PlayerTaxi::m_taximask`, a `TaxiMask`
-/// = `uint32[8]`, `DBCStructure.h:842-844` `TaxiMaskSize`/`TaxiMask`, written by
-/// `PlayerTaxi::AppendTaximaskTo`, `PlayerTaxi.cpp:53-65`). Bit law (`PlayerTaxi.h:37-49`,
-/// `IsTaximaskNodeKnown`/`SetTaximaskNode`): a node id is 1-based, `field = (id-1)/32`, `bit =
-/// (id-1)%32` within that word.
+/// The known-node bitmask (vmangos `PlayerTaxi::AppendTaximaskTo`, `PlayerTaxi.cpp:53-65`). Node
+/// ids are 1-based: node `id` is bit `(id-1) % 32` of word `(id-1) / 32` (`PlayerTaxi.h:37-49`).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub struct TaxiMask(pub [u32; 8]);
 
 impl TaxiMask {
-    /// Whether `node_id` is known. Node id `0` is never valid (ids are 1-based) and reads
-    /// unknown; an id past the mask's 256-node range reads unknown too (the shipped 1.12 catalog
-    /// tops out at 85 nodes, so real data never reaches that branch).
+    /// Whether `node_id` is known; 0 and ids past 256 read unknown (1.12 ships 85 nodes).
     pub fn is_known(&self, node_id: u32) -> bool {
         node_id != 0
             && self
@@ -33,12 +21,9 @@ impl TaxiMask {
     }
 }
 
-/// `TaxiError` (vmangos `Objects/Player.h:404-416`) — `SMSG_ACTIVATETAXIREPLY`'s `replyCode`.
-/// Codes actually assigned by `Player::ActivateTaxiPathTo` (`Player.cpp:18008-18252`, this
-/// session's grep): OK, UNSPECIFIED_SERVER_ERROR, NO_SUCH_PATH, NOT_ENOUGH_MONEY, TOO_FAR, BUSY,
-/// ALREADY_MOUNTED, SHAPESHIFTED. `NO_VENDOR_NEARBY`/`NOT_VISITED`/`PLAYER_MOVING`/`SAME_NODE`/
-/// `NOT_STANDING` are defined in the enum but no send site ever assigns them — kept for
-/// completeness (a private-server fork could still emit one) but never observed on the wire.
+/// `SMSG_ACTIVATETAXIREPLY` codes, vmangos `TaxiError` (`Player.h:404-416`). vmangos never sends
+/// `NO_VENDOR_NEARBY`, `NOT_VISITED`, `PLAYER_MOVING`, `SAME_NODE` or `NOT_STANDING`
+/// (`Player::ActivateTaxiPathTo`, `Player.cpp:18008-18252`).
 pub mod taxi_reply {
     pub const OK: u32 = 0;
     pub const UNSPECIFIED_SERVER_ERROR: u32 = 1;
@@ -55,29 +40,20 @@ pub mod taxi_reply {
     pub const NOT_STANDING: u32 = 12;
 }
 
-/// Body of `CMSG_TAXINODE_STATUS_QUERY` (vmangos `Packets/Taxi.cpp`,
-/// `TaxiNodeStatusQuery::ReadFromWorldPacket`): one full 8-byte guid — "the GUID of the
-/// flightmaster" per vmangos's own comment (a normal client sends the NPC it's standing near, not
-/// itself). Answered by `SMSG_TAXINODE_STATUS`.
+/// Body of `CMSG_TAXINODE_STATUS_QUERY`, answered by `SMSG_TAXINODE_STATUS`.
 pub fn taxi_node_status_query(flightmaster_guid: u64) -> Vec<u8> {
     flightmaster_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_TAXIQUERYAVAILABLENODES` (vmangos `Packets/Taxi.cpp`,
-/// `TaxiQueryAvailableNodes::ReadFromWorldPacket`): one full 8-byte flight-master guid — the
-/// direct taxi-map opener (decision 0496 I4: CONFIRMED as built — the client's interact ladder is
-/// first-match-wins low→high over `UNIT_NPC_FLAGS`, so a gossip+taxi NPC pre-empts to gossip and
-/// only a pure flightmaster sends this; the gossip taxi option reaches the same menu server-side
-/// through `SendTaxiMenu`). Answered by `SMSG_SHOWTAXINODES` on a known node; a
-/// never-visited node instead answers `SMSG_NEW_TAXI_PATH` + `SMSG_TAXINODE_STATUS(known=1)` —
-/// the server "learns, never opens" on first contact (vmangos `SendLearnNewTaxiNode`).
+/// Body of `CMSG_TAXIQUERYAVAILABLENODES`, sent only for a pure flight master: the 1.12 client's
+/// interact order sends a gossip+taxi NPC to gossip. A known node answers `SMSG_SHOWTAXINODES`; an
+/// unvisited one is learned, not opened (`SMSG_NEW_TAXI_PATH`, `SendLearnNewTaxiNode`).
 pub fn taxi_query_available_nodes(flightmaster_guid: u64) -> Vec<u8> {
     flightmaster_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_ACTIVATETAXI` (vmangos `Packets/Taxi.cpp`, `ActivateTaxi::ReadFromWorldPacket`):
-/// `u64 flightmasterGuid, u32 node1 (source), u32 node2 (dest)` — a single-hop flight. Answered
-/// by `SMSG_ACTIVATETAXIREPLY`; success continues into the mount + `SMSG_MONSTER_MOVE` flight.
+/// Body of `CMSG_ACTIVATETAXI`: a flight along one direct `TaxiPath` edge, `node1` to `node2`,
+/// answered by `SMSG_ACTIVATETAXIREPLY`.
 pub fn activate_taxi(flightmaster_guid: u64, node1: u32, node2: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&flightmaster_guid.to_le_bytes());
@@ -86,13 +62,8 @@ pub fn activate_taxi(flightmaster_guid: u64, node1: u32, node2: u32) -> Vec<u8>
     body
 }
 
-/// Body of `CMSG_ACTIVATETAXIEXPRESS` (vmangos `Packets/Taxi.cpp`,
-/// `ActivateTaxiExpress::ReadFromWorldPacket`, `> CLIENT_BUILD_1_9_4` — active for 5875): `u64
-/// flightmasterGuid, u32 totalcost, u32 nodeCount, nodeCount x u32 node` — the full multi-hop
-/// chain in one send when **no direct `TaxiPath` edge exists current→target** (decision 0496
-/// §TU-3, byte-verified discriminator at `0x4dbad0`: it is edge presence, not hop count — a
-/// direct edge sends the single-hop `ActivateTaxi` below even when the drawn route detours
-/// through intermediate stops).
+/// Body of `CMSG_ACTIVATETAXIEXPRESS`: the whole multi-hop chain, sent when no direct `TaxiPath`
+/// edge joins the two nodes (client `0x4dbad0`), however many stops the drawn route has.
 pub fn activate_taxi_express(flightmaster_guid: u64, total_cost: u32, nodes: &[u32]) -> Vec<u8> {
     let mut body = Vec::with_capacity(16 + nodes.len() * 4);
     body.extend_from_slice(&flightmaster_guid.to_le_bytes());
@@ -104,14 +75,9 @@ pub fn activate_taxi_express(flightmaster_guid: u64, total_cost: u32, nodes: &[u
     body
 }
 
-/// Read `SMSG_SHOWTAXINODES` (vmangos `WorldSession::SendTaxiMenu`, `TaxiHandler.cpp:82-96`):
-/// `u32 gate`, then **iff `gate != 0`** `u64 flightmasterGuid` (plain, not packed), `u32
-/// nearestNode` (the node closest to the flight master — the map's "you are here"), `u32[8]
-/// knownMask` ([`TaxiMask`], `AppendTaximaskTo`). The leading word is a real conditional gate in
-/// the client's own parser (`0x5ece60` reads the rest only when it is nonzero — byte-verified,
-/// decision 0496 §claim-1), not a constant to skip; vmangos always sends `1` (48 bytes), so the
-/// gated-off 4-byte body never occurs live — parsed faithfully anyway. Returns `(gate,
-/// flightmaster, nearest_node, mask)`, all-zero past a zero gate (decode drops it — no event).
+/// Read `SMSG_SHOWTAXINODES` (vmangos `TaxiHandler.cpp:82-96`): a `u32` gate, then, only when it
+/// is nonzero (client `0x5ece60`), the flight master, the nearest node and the [`TaxiMask`].
+/// vmangos always sends 1.
 pub(super) fn read_show_taxi_nodes(r: &mut &[u8]) -> io::Result<(u32, u64, u32, TaxiMask)> {
     let window = read_u32_le(r)?;
     if window == 0 {
@@ -126,15 +92,12 @@ pub(super) fn read_show_taxi_nodes(r: &mut &[u8]) -> io::Result<(u32, u64, u32,
     Ok((window, flightmaster, nearest_node, TaxiMask(mask)))
 }
 
-/// Read `SMSG_TAXINODE_STATUS` (vmangos `TaxiNodeStatus::AppendBodyTo`, `Packets/Taxi.cpp:36-40`):
-/// `u64 guid` (plain), `u8 known` (a C++ `bool` — `ByteBuffer::operator<<(bool const&)` appends
-/// exactly one byte, `ByteBuffer.h:194-197`). Returns `(guid, known)`.
+/// Read `SMSG_TAXINODE_STATUS` (`Taxi.cpp:36-40`): `(guid, known)`, `known` a one-byte bool.
 pub(super) fn read_taxi_node_status(r: &mut &[u8]) -> io::Result<(u64, u8)> {
     Ok((read_u64_le(r)?, read_u8(r)?))
 }
 
-/// Read `SMSG_ACTIVATETAXIREPLY` (vmangos `ActivateTaxiReply::AppendBodyTo`,
-/// `Packets/Taxi.cpp:46-49`): one [`taxi_reply`] `u32` code.
+/// Read `SMSG_ACTIVATETAXIREPLY` (`Taxi.cpp:46-49`): one [`taxi_reply`] code.
 pub(super) fn read_activate_taxi_reply(r: &mut &[u8]) -> io::Result<u32> {
     read_u32_le(r)
 }
diff --git a/crates/benilla-protocol/src/messages/trade.rs b/crates/benilla-protocol/src/messages/trade.rs
index fa4fe017..b1810f3f 100644
--- a/crates/benilla-protocol/src/messages/trade.rs
+++ b/crates/benilla-protocol/src/messages/trade.rs
@@ -1,93 +1,75 @@
-//! The player-to-player trade arc's wire layer (decision 0592 phase P0): the request verbs the
-//! trade window sends and the two status packets the server pushes back. Layout VERIFIED against
-//! vmangos `Handlers/TradeHandler.cpp`, `Server/Packets/Trade.{h,cpp}`, `Objects/TradeData.{h,cpp}`
-//! and `SharedDefines.h` (read directly at decision time). Trade renders nothing derived from
-//! WoW.exe, so vmangos is the whole wire authority: its `ReadFromWorldPacket` pins every CMSG body
-//! below, its `AppendBodyTo`/`SendUpdateTrade` pin both SMSG parses — no wow-re dispatch is
-//! load-bearing (decision 0592, "No wow-re dispatch").
+//! Player-to-player trade wire: the trade window's request verbs and the two status packets the
+//! server pushes back (vmangos `TradeHandler.cpp`, `Server/Packets/Trade.cpp`).
 
 use std::io;
 
 use crate::wire::{read_i32_le, read_u32_le, read_u64_le, read_u8};
 
-/// `TRADE_SLOT_COUNT` (`TradeData.h`): seven slots per side — six tradeable (0..6) plus the
-/// seventh **non-traded / enchant** slot ([`TRADE_SLOT_NONTRADED`]), whose item is not exchanged
-/// but is the target an enchant/lockpick spell is applied to through the window.
+/// Slots per side (`TradeData.h`): six traded plus the non-traded enchant slot.
 pub const TRADE_SLOT_COUNT: usize = 7;
-/// `TRADE_SLOT_TRADED_COUNT` — the six slots (0..6) whose items actually change hands.
+/// Slots 0..6, whose items change hands.
 pub const TRADE_SLOT_TRADED_COUNT: usize = 6;
-/// `TRADE_SLOT_NONTRADED` — the 7th slot (index 6, UI id 7): an item parked here stays with its
-/// owner; it is the enchant/spell target, not part of the exchange.
+/// UI slot 7: its item stays with its owner as the target of an enchant or lockpick spell.
 pub const TRADE_SLOT_NONTRADED: usize = 6;
 
-/// The trade state machine's status codes (`SharedDefines.h` `enum TradeStatus`, 0..=22). The
-/// tail-carrying members hold their `SMSG_TRADE_STATUS` payload inline (VERIFIED vmangos
-/// `WorldPackets::Trade::TradeStatus::AppendBodyTo`): only `BEGIN_TRADE`, `CLOSE_WINDOW` and
-/// `ONLY_CONJURED` ride a tail; every other status is the bare `u32`. [`TradeStatus::Unknown`]
-/// keeps an out-of-range code (never emitted by vmangos on 5875) parseable rather than fatal.
+/// `SMSG_TRADE_STATUS` codes (`SharedDefines.h` `enum TradeStatus`), each with its tail inline.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TradeStatus {
-    /// `0` — the target is already trading / busy (also the initiator's own "already trading").
+    /// The target is busy, or the initiator is already trading.
     Busy,
-    /// `1` — sent to the *target* of a fresh `CMSG_INITIATE_TRADE`; `partner` is the initiator's
-    /// guid. The client answers `CMSG_BEGIN_TRADE`, which makes the server emit `OpenWindow` to
-    /// both sides.
+    /// To the target of `CMSG_INITIATE_TRADE`; its `CMSG_BEGIN_TRADE` opens both windows.
     BeginTrade { partner: u64 },
-    /// `2` — open the trade window (fires the client's `TRADE_SHOW`). Sent to both sides once the
-    /// target's `CMSG_BEGIN_TRADE` arrives.
+    /// Opens the window on both sides (the client's `TRADE_SHOW`).
     OpenWindow,
-    /// `3` — the trade was cancelled; close both windows.
+    /// The trade was cancelled; both windows close.
     Canceled,
-    /// `4` — the *partner* pressed Trade (drives the accept-glow on their column).
+    /// The partner pressed Trade (the accept highlight on their column).
     Accept,
-    /// `5` — a second "busy" code, handled as busy.
+    /// A second busy code, handled as `Busy`.
     Busy2,
-    /// `6` — no such target for `CMSG_INITIATE_TRADE`.
+    /// No such target for `CMSG_INITIATE_TRADE`.
     NoTarget,
-    /// `7` — a change happened after an accept (or the 200 ms scam-delay bounced an accept):
-    /// drop the accept and go back to editing.
+    /// An offer changed after an accept, or the 200 ms scam delay bounced one: the accept drops.
     BackToTrade,
-    /// `8` — both sides accepted and the swap completed; close both windows.
+    /// Both sides accepted and the swap completed; both windows close.
     Complete,
-    /// `9` — the trade was rejected.
+    /// The trade was rejected.
     Rejected,
-    /// `10` — the partner is out of `TRADE_DISTANCE` (also the flying/no-map initiate refusal).
+    /// Out of `TRADE_DISTANCE`; also the refusal to initiate while flying or off-map.
     TargetTooFar,
-    /// `11` — cross-faction trade refused (unless the server allows two-side interaction).
+    /// Cross-faction, unless the server allows two-side interaction.
     WrongFaction,
-    /// `12` — close the window; `result`/`item_limit_category` are the vanilla tail (usually 0;
-    /// the middle `u8` vmangos writes is consumed but carries nothing for player trade).
+    /// The tail is usually zero; the `u8` vmangos writes between the two fields is dropped.
     CloseWindow {
         result: u32,
         item_limit_category: u32,
     },
-    /// `13` — vmangos comments it is "handled with TRADE_STATUS_TRADE_CANCELED"; kept distinct so
-    /// the wire round-trips.
+    /// Per a vmangos note, handled as `Canceled`; kept distinct so the code round-trips.
     Unknown13,
-    /// `14` — the target has you on ignore.
+    /// The target has you on ignore.
     IgnoreYou,
-    /// `15` — you are stunned.
+    /// You are stunned.
     YouStunned,
-    /// `16` — the target is stunned.
+    /// The target is stunned.
     TargetStunned,
-    /// `17` — you are dead.
+    /// You are dead.
     YouDead,
-    /// `18` — the target is dead.
+    /// The target is dead.
     TargetDead,
-    /// `19` — you are logging out.
+    /// You are logging out.
     YouLogout,
-    /// `20` — the target is logging out.
+    /// The target is logging out.
     TargetLogout,
-    /// `21` — a trial account restriction.
+    /// A trial account restriction.
     TrialAccount,
-    /// `22` — "you can only trade conjured items…"; `slot` names the offending trade slot.
+    /// "You can only trade conjured items"; `slot` is the offending trade slot.
     OnlyConjured { slot: u8 },
-    /// A code outside 0..=22 (vmangos never sends one on 5875) — kept parseable, no tail read.
+    /// A code outside 0..=22, which vmangos never sends; read with no tail.
     Unknown(u32),
 }
 
 impl TradeStatus {
-    /// The raw `u32` code this status serializes as (the enum discriminant on the wire).
+    /// The `u32` status code on the wire.
     pub fn code(self) -> u32 {
         match self {
             TradeStatus::Busy => 0,
@@ -118,13 +100,10 @@ impl TradeStatus {
     }
 }
 
-/// One item shown in a trade slot, as it rides `SMSG_TRADE_STATUS_EXTENDED`'s fixed 60-byte
-/// (15×u32) per-slot block (VERIFIED vmangos `WorldSession::SendUpdateTrade`). An empty slot is
-/// all-zero on the wire and folds to `None` rather than a zeroed `Some` (the `entry == 0` signal,
-/// same convention as [`super::MailAttachment`]).
+/// One trade slot's 60-byte item block; an all-zero block is an empty slot.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct TradeItem {
-    /// `Item.dbc` entry (`OBJECT_FIELD_ENTRY`) — the key to name/icon via `ITEM_QUERY_SINGLE`.
+    /// `Item.dbc` entry (`OBJECT_FIELD_ENTRY`), the key for name and icon via `ITEM_QUERY_SINGLE`.
     pub entry: u32,
     pub display_id: u32,
     pub count: u32,
@@ -133,7 +112,7 @@ pub struct TradeItem {
     pub gift_creator: u64,
     pub perm_enchant: u32,
     pub creator: u64,
-    /// Spell charges — signed (a negative count means "N uses left" on some items).
+    /// Signed: a negative count means N uses left on some items.
     pub charges: i32,
     pub suffix_factor: u32,
     pub random_prop_id: u32,
@@ -142,62 +121,51 @@ pub struct TradeItem {
     pub durability: u32,
 }
 
-/// A decoded `SMSG_TRADE_STATUS_EXTENDED` — the full item/gold snapshot for **one** window side.
-/// The server pushes one of these per side whenever that side's offer changes.
+/// `SMSG_TRADE_STATUS_EXTENDED`: one side's snapshot, sent whenever that side's offer changes.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct TradeStatusExtended {
-    /// `true` = the *partner's* (recipient / right) column, `false` = our own (left) column
-    /// (vmangos's `trader_state`: `1` for the trader's data, `0` for ours).
+    /// The partner's (right) column when the wire byte is 1, ours (left) when 0.
     pub their_window: bool,
-    /// Gold offered on this side, in copper.
+    /// In copper.
     pub gold: u32,
-    /// The spell applied to this side's non-traded slot item (`0` = none) — the enchant slot.
+    /// The spell cast on this side's non-traded slot item, 0 for none.
     pub enchant_spell_id: u32,
-    /// The seven slots (0..[`TRADE_SLOT_COUNT`]); `None` = empty.
     pub slots: [Option<TradeItem>; TRADE_SLOT_COUNT],
 }
 
-// ── Client → server bodies (what vmangos `ReadFromWorldPacket` consumes) ─────────────────────
+// ── Client → server bodies ──
 
-/// Body of `CMSG_INITIATE_TRADE` (vmangos `InitiateTrade::ReadFromWorldPacket`): one full 8-byte
-/// target-player guid. The server answers the initiator on any refusal (`SMSG_TRADE_STATUS`) and,
-/// on success, sends the *target* `BeginTrade`.
+/// `CMSG_INITIATE_TRADE`: a refusal is a status back to us; success sends the target `BeginTrade`.
 pub fn initiate_trade(target: u64) -> Vec<u8> {
     target.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_ACCEPT_TRADE` (vmangos `AcceptTrade::ReadFromWorldPacket`): one `u32` the server
-/// **read-skips**. The real client sends `1` once it has seen `OPEN_WINDOW`; we send `1` too (the
-/// value is discarded either way).
+/// `CMSG_ACCEPT_TRADE`: a `u32` the server skips; the 1.12 client sends 1.
 pub fn accept_trade() -> Vec<u8> {
     1u32.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_SET_TRADE_ITEM` (vmangos `SetTradeItem::ReadFromWorldPacket`): `u8 tradeSlot,
-/// u8 bag, u8 slot` — put the item at inventory (`bag`, `slot`) into trade slot `tradeSlot`.
+/// `CMSG_SET_TRADE_ITEM`: puts the item at (`bag`, `slot`) into `trade_slot`.
 pub fn set_trade_item(trade_slot: u8, bag: u8, slot: u8) -> Vec<u8> {
     vec![trade_slot, bag, slot]
 }
 
-/// Body of `CMSG_CLEAR_TRADE_ITEM` (vmangos `ClearTradeItem::ReadFromWorldPacket`): `u8 tradeSlot`.
+/// `CMSG_CLEAR_TRADE_ITEM` body.
 pub fn clear_trade_item(trade_slot: u8) -> Vec<u8> {
     vec![trade_slot]
 }
 
-/// Body of `CMSG_SET_TRADE_GOLD` (vmangos `SetTradeGold::ReadFromWorldPacket`): `u32 copper`.
+/// `CMSG_SET_TRADE_GOLD` body, in copper.
 pub fn set_trade_gold(copper: u32) -> Vec<u8> {
     copper.to_le_bytes().to_vec()
 }
 
 // `CMSG_BEGIN_TRADE`, `CMSG_BUSY_TRADE`, `CMSG_IGNORE_TRADE`, `CMSG_UNACCEPT_TRADE` and
-// `CMSG_CANCEL_TRADE` carry **empty** bodies (vmangos reads them as `NullClientPacket`); the
-// writer sends `&[]` directly, so they need no builder here.
+// `CMSG_CANCEL_TRADE` have empty bodies (vmangos `NullClientPacket`), so they need no builder.
 
-// ── Server → client parses (what vmangos `AppendBodyTo` / `SendUpdateTrade` emit) ─────────────
+// ── Server → client parses ──
 
-/// Read `SMSG_TRADE_STATUS` (VERIFIED vmangos `TradeStatus::AppendBodyTo`): `u32 status`, then a
-/// per-status tail — `BEGIN_TRADE → u64 partnerGuid`; `CLOSE_WINDOW → u32 result, u8 unk, u32
-/// itemLimitCategory`; `ONLY_CONJURED → u8 slot`; every other status has none.
+/// `SMSG_TRADE_STATUS` (vmangos `TradeStatus::AppendBodyTo`): a `u32` code, then its tail.
 pub(super) fn read_trade_status(r: &mut &[u8]) -> io::Result<TradeStatus> {
     let code = read_u32_le(r)?;
     Ok(match code {
@@ -238,12 +206,8 @@ pub(super) fn read_trade_status(r: &mut &[u8]) -> io::Result<TradeStatus> {
     })
 }
 
-/// Read `SMSG_TRADE_STATUS_EXTENDED` (VERIFIED vmangos `WorldSession::SendUpdateTrade`):
-/// `u8 which`, `u32 slotCount`, `u32 slotCount` (again — the two counts match), `u32 gold`,
-/// `u32 enchantSpellId`, then [`TRADE_SLOT_COUNT`] records of `u8 slotIndex` + a fixed 60-byte
-/// (15×u32) item block (all-zero → the slot is empty). The `slotIndex` byte places the block, so
-/// a block is stored at `slots[slotIndex]` (defensive against reordering; vmangos writes 0..7 in
-/// order).
+/// `SMSG_TRADE_STATUS_EXTENDED` (vmangos `WorldSession::SendUpdateTrade`): `u8 which`, the slot
+/// count twice, gold, enchant spell, then seven records of `u8 index` and a 60-byte item block.
 pub(super) fn read_trade_status_extended(r: &mut &[u8]) -> io::Result<TradeStatusExtended> {
     let which = read_u8(r)?;
     let _slot_count_a = read_u32_le(r)?;
@@ -297,7 +261,7 @@ pub(super) fn read_trade_status_extended(r: &mut &[u8]) -> io::Result<TradeStatu
 mod tests {
     use super::*;
 
-    // ── CMSG body goldens (byte-exact against vmangos's ReadFromWorldPacket layout) ──
+    // ── CMSG body goldens ──
 
     #[test]
     fn initiate_trade_is_the_target_guid_le() {
@@ -314,7 +278,6 @@ mod tests {
 
     #[test]
     fn set_trade_item_is_three_u8s() {
-        // Put bag 0 / slot 23 into trade slot 2.
         assert_eq!(set_trade_item(2, 0, 23), vec![2, 0, 23]);
     }
 
@@ -330,12 +293,42 @@ mod tests {
 
     // ── SMSG_TRADE_STATUS parse goldens ──
 
+    /// Every code without a tail reads as its variant and leaves the byte after the code unread.
     #[test]
     fn trade_status_bare_code_has_no_tail() {
-        let buf = 2u32.to_le_bytes(); // OPEN_WINDOW
-        let mut r = &buf[..];
-        assert_eq!(read_trade_status(&mut r).unwrap(), TradeStatus::OpenWindow);
-        assert!(r.is_empty(), "no tail should be consumed for a bare status");
+        for (code, want) in [
+            (0, TradeStatus::Busy),
+            (2, TradeStatus::OpenWindow),
+            (3, TradeStatus::Canceled),
+            (4, TradeStatus::Accept),
+            (5, TradeStatus::Busy2),
+            (6, TradeStatus::NoTarget),
+            (7, TradeStatus::BackToTrade),
+            (8, TradeStatus::Complete),
+            (9, TradeStatus::Rejected),
+            (10, TradeStatus::TargetTooFar),
+            (11, TradeStatus::WrongFaction),
+            (13, TradeStatus::Unknown13),
+            (14, TradeStatus::IgnoreYou),
+            (15, TradeStatus::YouStunned),
+            (16, TradeStatus::TargetStunned),
+            (17, TradeStatus::YouDead),
+            (18, TradeStatus::TargetDead),
+            (19, TradeStatus::YouLogout),
+            (20, TradeStatus::TargetLogout),
+            (21, TradeStatus::TrialAccount),
+        ] {
+            let mut buf = u32::to_le_bytes(code).to_vec();
+            buf.push(0xEE); // the next byte, which a bare status leaves unread
+            let mut r = &buf[..];
+            assert_eq!(read_trade_status(&mut r).unwrap(), want, "code {code}");
+            assert_eq!(
+                r,
+                [0xEE],
+                "no tail should be consumed for bare status {code}"
+            );
+            assert_eq!(want.code(), code);
+        }
     }
 
     #[test]
@@ -394,8 +387,7 @@ mod tests {
 
     // ── SMSG_TRADE_STATUS_EXTENDED parse golden ──
 
-    /// Build a full 444-byte snapshot the way vmangos does: a 17-byte header, then 7 slot records
-    /// (each a `u8 index` + 60-byte block). `items[i] = Some(entry)` fills slot `i`; `None` zeroes it.
+    /// A 444-byte snapshot as vmangos builds it; `Some(entry)` fills a slot, `None` zeroes it.
     fn extended_wire(
         which: u8,
         gold: u32,
@@ -432,12 +424,30 @@ mod tests {
         b
     }
 
+    /// The parser reads exactly 444 bytes, whether the slots are empty, full or mixed.
     #[test]
     fn extended_snapshot_is_always_444_bytes() {
-        // 17-byte header (u8 which + 4×u32) + 7 slot records of (u8 index + 60-byte block).
-        let wire = extended_wire(0, 0, 0, [None; TRADE_SLOT_COUNT]);
-        assert_eq!(wire.len(), 17 + TRADE_SLOT_COUNT * 61);
-        assert_eq!(wire.len(), 444);
+        // A 17-byte header (u8 and four u32), then 7 records of u8 index and a 60-byte block.
+        let mut mixed = [None; TRADE_SLOT_COUNT];
+        mixed[0] = Some(0xABCD);
+        mixed[TRADE_SLOT_NONTRADED] = Some(0x1111);
+        for entries in [
+            [None; TRADE_SLOT_COUNT],
+            [Some(0xABCD); TRADE_SLOT_COUNT],
+            mixed,
+        ] {
+            let mut wire = extended_wire(0, 0, 0, entries);
+            assert_eq!(wire.len(), 17 + TRADE_SLOT_COUNT * 61);
+            assert_eq!(wire.len(), 444);
+            assert!(
+                read_trade_status_extended(&mut &wire[..443]).is_err(),
+                "443 bytes is a short read"
+            );
+            wire.push(0xEE); // a byte past the snapshot
+            let mut r = &wire[..];
+            read_trade_status_extended(&mut r).unwrap();
+            assert_eq!(r, [0xEE], "the parser stops at byte 444");
+        }
     }
 
     #[test]
diff --git a/crates/benilla-protocol/src/messages/trainer.rs b/crates/benilla-protocol/src/messages/trainer.rs
index 844a815d..7da79806 100644
--- a/crates/benilla-protocol/src/messages/trainer.rs
+++ b/crates/benilla-protocol/src/messages/trainer.rs
@@ -1,84 +1,58 @@
-//! Trainer messages — the class/profession trainer window's wire (opcodes 432-436, vmangos
-//! `Opcodes_1_12_1.h:433-437`, VERIFIED). Bodies from vmangos `NPCHandler.cpp` (`SendTrainerList` +
-//! its per-service helper `SendTrainerSpellHelper`) and the hand-serialized `Server/Packets/Npc.cpp`
-//! (the `TrainerList`/`TrainerBuySpell`/`TrainerBuySucceeded`/`TrainerBuyFailed` structs). One frame
-//! (`ClassTrainerFrame`) serves both class and tradeskill trainers; the window is reached through the
-//! gossip trainer option (`GOSSIP_OPTION_TRAINER`, [`super::gossip`]), not a trainer-specific open
-//! verb — so this arc is the receive side plus the two send verbs (decision 0237).
+//! Trainer window wire (opcodes 432-436). The window opens off the gossip trainer option
+//! (`GOSSIP_OPTION_TRAINER`), so there is no open verb, only a list refresh and a buy.
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_cstring, read_u32_le, read_u64_le, read_u8};
 
-/// One trainer service (`SMSG_TRAINER_LIST`, vmangos `SendTrainerSpellHelper`,
-/// `NPCHandler.cpp:97-139`) — a spell or tradeskill step the trainer can teach. The 38-byte wire
-/// record; the list is **pre-filtered server-side** to services fitting the player's class/race, so
-/// what arrives is already the player's own menu.
+/// One 38-byte `SMSG_TRAINER_LIST` service (`NPCHandler.cpp:97-139`); the server already filters
+/// the list to the player's class and race.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct TrainerSpell {
-    /// The service spell id — what `CMSG_TRAINER_BUY_SPELL` names to purchase it (see
-    /// [`trainer_buy_spell`]).
+    /// The service spell id, which `CMSG_TRAINER_BUY_SPELL` names to buy it.
     pub spell: u32,
-    /// A [`trainer_spell_state`] byte: the green/red/gray colouring the client renders (it does not
-    /// recompute it). `GREEN_DISABLED` (server-internal, 10) never rides the wire — it is sent as
-    /// `GREEN`.
+    /// A [`trainer_spell_state`]: the client renders the colour as sent, never recomputing it.
     pub state: u8,
-    /// Cost in copper, already reputation-discounted server-side.
+    /// In copper, already reputation-discounted by the server.
     pub cost: u32,
-    /// Wire field 4 (`primary_prof_first_rank && can_learn_primary_prof`): the client enables the
-    /// "Learn" button only when this equals [`is_primary_prof_first_rank`] — so a primary-profession
-    /// first rank you *can't* take (already holding two professions) arrives as `false` here with
-    /// `is_primary_prof_first_rank == true`, greying the button.
+    /// Sent as `first_rank && can_learn`; the client enables Learn only when it equals
+    /// `is_primary_prof_first_rank`, which greys a third primary profession.
     pub can_learn_primary_prof: bool,
-    /// Wire field 5 (`primary_prof_first_rank`): this service is a first-rank primary profession, so
-    /// taking it spends a profession slot (drives the client's confirmation dialog).
+    /// Taking it spends a profession slot, so the client asks for confirmation.
     pub is_primary_prof_first_rank: bool,
-    /// Character level required to learn (`spellLevel`).
     pub req_level: u8,
-    /// Required `SkillLine.dbc` id (0 = none) — e.g. the tradeskill this step belongs to.
+    /// A `SkillLine.dbc` id, 0 for none.
     pub req_skill: u32,
-    /// Required skill points in [`req_skill`] (0 = none).
     pub req_skill_value: u32,
-    /// Up to three prerequisite spell ids (`SpellChainNode` req/prev + a trailing slot). The trailing
-    /// slot is structurally always 0 on 5875; kept as an array to match the client's own
-    /// `GetTrainerServiceAbilityReq(i)` model.
+    /// The `SpellChainNode` req and prev spells, then a slot vmangos always sends as 0.
     pub req_spells: [u32; 3],
 }
 
-/// `TrainerSpellState` (vmangos `Player.h:119-122`) — the service `state` byte. `GREEN_DISABLED` (10)
-/// is server-internal and is sent on the wire as `GREEN`, so only these three ever arrive.
+/// `TrainerSpellState` (`Player.h:119-122`); `GREEN_DISABLED` (10) is sent as `GREEN`.
 pub mod trainer_spell_state {
     /// Learnable now.
     pub const GREEN: u8 = 0;
-    /// Requirements unmet (level / skill / prerequisite).
+    /// Level, skill or prerequisite unmet.
     pub const RED: u8 = 1;
     /// Already known.
     pub const GRAY: u8 = 2;
 }
 
-/// The `errorCode` on `SMSG_TRAINER_BUY_FAILED` (vmangos `SharedDefines.h:1120-1122`,
-/// `TrainerServiceType`-adjacent `TRAIN_FAIL_*`). A `u32` on the wire.
+/// `SMSG_TRAINER_BUY_FAILED` error codes (vmangos `SharedDefines.h:1120-1122` `TRAIN_FAIL_*`).
 pub mod train_fail {
-    /// Trainer service unavailable (not a trainer of yours, out of LOS, service not in the list).
+    /// Not your trainer, out of line of sight, or not a listed service.
     pub const UNAVAILABLE: u32 = 0;
-    /// Not enough money.
     pub const NOT_ENOUGH_MONEY: u32 = 1;
-    /// Not enough skill points.
     pub const NOT_ENOUGH_SKILL: u32 = 2;
 }
 
-/// Body of `CMSG_TRAINER_LIST` (vmangos `Npc.cpp`, `TrainerList::ReadFromWorldPacket`): one full
-/// 8-byte trainer guid. Requests (and, after a purchase, re-requests to repaint green→gray) the
-/// service list — the *refresh* verb, not the open verb: the window first opens off the gossip
-/// trainer option's `SMSG_TRAINER_LIST` (decision 0237).
+/// `CMSG_TRAINER_LIST`: re-requests the list, as after a purchase to turn the service gray.
 pub fn trainer_list(trainer_guid: u64) -> Vec<u8> {
     trainer_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_TRAINER_BUY_SPELL` (vmangos `Npc.cpp`, `TrainerBuySpell::ReadFromWorldPacket`):
-/// `u64 trainerGuid, u32 spellId` (the [`TrainerSpell::spell`] of the chosen service). The server
-/// answers `SMSG_TRAINER_BUY_SUCCEEDED` (+ the learned spell via `SMSG_LEARNED_SPELL`) or
-/// `SMSG_TRAINER_BUY_FAILED`.
+/// `CMSG_TRAINER_BUY_SPELL`: the server answers `SMSG_TRAINER_BUY_SUCCEEDED` plus
+/// `SMSG_LEARNED_SPELL`, or `SMSG_TRAINER_BUY_FAILED`.
 pub fn trainer_buy_spell(trainer_guid: u64, spell_id: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&trainer_guid.to_le_bytes());
@@ -86,21 +60,18 @@ pub fn trainer_buy_spell(trainer_guid: u64, spell_id: u32) -> Vec<u8> {
     body
 }
 
-/// Read `SMSG_TRAINER_LIST` (vmangos `WorldSession::SendTrainerList`, `NPCHandler.cpp:141-241`):
-/// `u64 trainerGuid, u32 trainerType, u32 count, count ×` [`TrainerSpell`] (38 bytes each)`, cstr
-/// title`. `trainerType` is the window-framing kind (0 class · 1 mount · 2 tradeskill · 3 pet); the
-/// title is the greeting line. Returns `(trainer, trainer_type, services, title)`.
+/// `SMSG_TRAINER_LIST` (`NPCHandler.cpp:141-241`): the type is 0 class, 1 mount, 2 tradeskill or
+/// 3 pet, and the title is the greeting line.
 pub(super) fn read_trainer_list(
     r: &mut &[u8],
 ) -> io::Result<(u64, u32, Vec<TrainerSpell>, String)> {
     let trainer = read_u64_le(r)?;
     let trainer_type = read_u32_le(r)?;
     let count = read_u32_le(r)?;
-    // No protocol bound: the list is every spell the trainer's template carries (vmangos
-    // `NPCHandler.cpp:170` sums its two lists). 1024 is far past any real trainer.
+    // No protocol bound (`NPCHandler.cpp:170` sums two lists); 1024 is past any real trainer.
     let mut services = Vec::with_capacity(capacity_hint(count, 1024));
     for _ in 0..count {
-        // Struct-literal fields evaluate top-to-bottom, so this reads in wire order.
+        // Struct-literal fields evaluate top to bottom, so this reads in wire order.
         services.push(TrainerSpell {
             spell: read_u32_le(r)?,
             state: read_u8(r)?,
@@ -117,15 +88,13 @@ pub(super) fn read_trainer_list(
     Ok((trainer, trainer_type, services, title))
 }
 
-/// Read `SMSG_TRAINER_BUY_SUCCEEDED` (vmangos `TrainerBuySucceeded::AppendBodyTo`): `u64
-/// trainerGuid, u32 spellId`. Confirmation + sound only — the learned spell itself lands via
-/// `SMSG_LEARNED_SPELL`, and the green→gray repaint needs a `CMSG_TRAINER_LIST` re-request.
+/// `SMSG_TRAINER_BUY_SUCCEEDED` (trainer, spell) is confirmation only: the spell arrives by
+/// `SMSG_LEARNED_SPELL` and the gray repaint needs a `CMSG_TRAINER_LIST`.
 pub(super) fn read_trainer_buy_succeeded(r: &mut &[u8]) -> io::Result<(u64, u32)> {
     Ok((read_u64_le(r)?, read_u32_le(r)?))
 }
 
-/// Read `SMSG_TRAINER_BUY_FAILED` (vmangos `TrainerBuyFailed::AppendBodyTo`): `u64 trainerGuid, u32
-/// serviceId (the spell), u32 errorCode` (a [`train_fail`] code).
+/// `SMSG_TRAINER_BUY_FAILED`: trainer, spell and a [`train_fail`] code.
 pub(super) fn read_trainer_buy_failed(r: &mut &[u8]) -> io::Result<(u64, u32, u32)> {
     Ok((read_u64_le(r)?, read_u32_le(r)?, read_u32_le(r)?))
 }
diff --git a/crates/benilla-protocol/src/messages/tutorial.rs b/crates/benilla-protocol/src/messages/tutorial.rs
index 4750b716..1d064750 100644
--- a/crates/benilla-protocol/src/messages/tutorial.rs
+++ b/crates/benilla-protocol/src/messages/tutorial.rs
@@ -1,29 +1,21 @@
-//! The tutorial system's wire (decision 1976; wow-re `system/ui/scratch/tutorial-flags.md` §7):
-//! one inbound bank of bits and the three sends the client's tutorial code makes.
-//!
-//! The client keeps two bit banks filled from the same `SMSG_TUTORIAL_FLAGS` — the fire-once bank
-//! its C++ trigger reads and sets, and the acknowledged bank Lua's `FlagTutorial` and six C++
-//! auto-flag sites write, which is the only path that sends. The handler takes **whatever bytes
-//! are left in the packet** and sizes both banks as `bytes × 8` bits; vmangos sends 32 bytes.
+//! Tutorial wire: one inbound bank of bits and the client's three tutorial sends. The 1.12
+//! client sizes its banks from every remaining byte of the packet; vmangos sends 32 bytes.
 
 use std::io::{self, Read};
 
-/// `SMSG_TUTORIAL_FLAGS` (VERIFIED at the bytes, handler `0x4b5700`): the raw bank, every
-/// remaining byte of the packet — bit `id` is `bytes[id >> 3] & (1 << (id & 7))`, the same
-/// `word = id >> 5, bit = 1 << (id & 31)` addressing on little-endian dwords.
+/// `SMSG_TUTORIAL_FLAGS` (handler `0x4b5700`): bit `id` is `bytes[id >> 3] & (1 << (id & 7))`.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct TutorialFlags {
     pub bytes: Vec<u8>,
 }
 
-/// Parse it: the rest of the body, whatever its length.
 pub(super) fn read_tutorial_flags(r: &mut impl Read) -> io::Result<TutorialFlags> {
     let mut bytes = Vec::new();
     r.read_to_end(&mut bytes)?;
     Ok(TutorialFlags { bytes })
 }
 
-/// Body of `CMSG_TUTORIAL_FLAG` (VERIFIED, `0x4b54c0`): one `u32`, the **0-based** id.
+/// `CMSG_TUTORIAL_FLAG` (`0x4b54c0`): the 0-based id as a `u32`.
 pub fn tutorial_flag(id: u32) -> Vec<u8> {
     id.to_le_bytes().to_vec()
 }
diff --git a/crates/benilla-protocol/src/messages/update_object/fields/mod.rs b/crates/benilla-protocol/src/messages/update_object/fields/mod.rs
index 34ee4af4..bd65fad4 100644
--- a/crates/benilla-protocol/src/messages/update_object/fields/mod.rs
+++ b/crates/benilla-protocol/src/messages/update_object/fields/mod.rs
@@ -4,74 +4,49 @@ use crate::wire::{capacity_hint, read_u32_le, read_u8, Vector3d};
 
 use super::movement::ObjectType;
 
-// ObjectFields descriptor-field indices (build 5875), shared across object types.
+// Descriptor field indices for build 5875.
 const FIELD_OBJECT_TYPE: u16 = 2;
 const FIELD_OBJECT_SCALE_X: u16 = 4;
-// `OBJECT_FIELD_CREATED_BY` = OBJECT_END(6) + 0x0..0x1 (vmangos `UpdateFields_1_12_1.h`): the
-// GameObject block's creator guid pair — the summoning player of a spell-spawned object
-// (fishing bobber, ritual portal); zero/absent for a world spawn.
+// The creator of a spell-spawned object (bobber, ritual portal); 0 for a world spawn.
 const FIELD_GAMEOBJECT_CREATED_BY: u16 = 6;
 const FIELD_GAMEOBJECT_DISPLAYID: u16 = 8;
 const FIELD_GAMEOBJECT_FLAGS: u16 = 9;
-// `GAMEOBJECT_ROTATION` = OBJECT_END(6) + 0x4 .. +0x7 (vmangos `UpdateFields_1_12_1.h`): the
-// spawn's local-rotation quaternion (x, y, z, w), 4 floats. The type-11 transport evaluator
-// rotates its keyframe offsets by this (decision 0438 phase 3's second consumer).
+// The spawn's rotation quaternion (x, y, z, w), four floats.
 const FIELD_GAMEOBJECT_ROTATION: u16 = 10;
 pub const FIELD_GAMEOBJECT_STATE: u16 = 14;
 const FIELD_GAMEOBJECT_POS_X: u16 = 15;
 const FIELD_GAMEOBJECT_POS_Y: u16 = 16;
 const FIELD_GAMEOBJECT_POS_Z: u16 = 17;
 const FIELD_GAMEOBJECT_FACING: u16 = 18;
-// `OBJECT_END + 0x34` bytes ⇒ `OBJECT_END(6) + field 13` = 19 (wow-re cursor-system §4a byte offset;
-// vmangos' `UpdateFields_1_5_1.h` inserts a stray `GAMEOBJECT_TIMESTAMP` that would shift this to 20,
-// but that header is not the 5875 layout — STATE@14 / TYPE_ID@21 both work against this same server).
+// The client reads it at GameObject block byte 0x34. vmangos `UpdateFields_1_5_1.h` adds a
+// `GAMEOBJECT_TIMESTAMP` that would make it 20, but that is not the 5875 layout.
 const FIELD_GAMEOBJECT_DYN_FLAGS: u16 = 19;
-// GAMEOBJECT_FACTION = OBJECT_END(6) + field 14 — the slot between DYN_FLAGS(13) and TYPE_ID(15),
-// i.e. the binary's `[go+0x110]+0x38` (wow-re cursor-system §4a's faction term, decision 0764).
+// The client reads it at `[go+0x110]+0x38`, between DYN_FLAGS and TYPE_ID.
 const FIELD_GAMEOBJECT_FACTION: u16 = 20;
 const FIELD_GAMEOBJECT_TYPE_ID: u16 = 21;
-// GAMEOBJECT_LEVEL = OBJECT_END(6) + 0x10 (vmangos UpdateFields_1_12_1.h:317).
+// OBJECT_END + 0x10 (vmangos `UpdateFields_1_12_1.h:317`).
 const FIELD_GAMEOBJECT_LEVEL: u16 = 22;
-/// `CORPSE_FIELD_DYNAMIC_FLAGS` = `OBJECT_END(6) + 0x1E` (vmangos `UpdateFields_1_12_1.h`) — bit 0
-/// is the lootable-insignia flag [`ObjectFields::corpse_lootable`] reads and the loot-art arm
-/// watches. Named because a watch keys on the raw index, and `36` is `UNIT_FIELD_BYTES_0` on a
-/// unit: the same number means two things, which is why a field edge carries its object class.
+/// `CORPSE_FIELD_DYNAMIC_FLAGS`; bit 0 is lootable insignia. On a unit, index 36 is
+/// `UNIT_FIELD_BYTES_0`, so a field edge carries its object class.
 pub const FIELD_CORPSE_DYNAMIC_FLAGS: u16 = 36;
-// UNIT descriptor fields (verified against wow-5875-re object-layer node, build 5875; FLAGS /
-// COMBATREACH / DYNAMIC_FLAGS / NPC_FLAGS additionally cross-checked against the cursor RE's client
-// offsets `+0xa0`/`+0x1f0`/`+0x224`/`+0x234` and vmangos `UpdateFields_1_12_1.h`).
-/// `UNIT_FIELD_TARGET` (idx 16, a 2-field guid) — who the unit is attacking/interacting with. The
-/// real client turns an idle unit's body to *face* this target (there is no wire facing for a
-/// stationary re-face — vmangos `SetInFront` is server-only); benilla mirrors that (`face_target`).
+// UNIT fields. The client reads FLAGS, COMBATREACH, DYNAMIC_FLAGS and NPC_FLAGS at unit block
+// bytes 0xa0, 0x1f0, 0x224 and 0x234.
+/// The unit's target; the client turns an idle unit to face it, and no packet carries that facing.
 const FIELD_UNIT_TARGET: u16 = 16;
-/// `UNIT_FIELD_SUMMON` (idx 8, `OBJECT_END(6) + 0x2`, a 2-field guid, PUBLIC — VERIFIED vmangos
-/// `UpdateFields_1_12_1.h:42`) — the **inverse** of [`FIELD_UNIT_SUMMONEDBY`] below: the unit this
-/// one has summoned. On our own descriptor it is the pet, and so the anchor of the `"pet"` unit
-/// token; the pet action bar reads its own guid off `SMSG_PET_SPELLS` instead, which is why the
-/// two can legitimately disagree for a beat around a summon (decision 0982).
+/// The unit this one summoned (`UpdateFields_1_12_1.h:42`); on us, the `"pet"` unit. The pet bar
+/// reads its guid off `SMSG_PET_SPELLS`, so the two can disagree briefly around a summon.
 const FIELD_UNIT_SUMMON: u16 = 8;
-/// `UNIT_FIELD_CHARMEDBY` (idx 10, `OBJECT_END(6) + 0x4`, a 2-field guid — vmangos
-/// `UpdateFields_1_12_1.h`) — whoever is currently charming this unit, `0` when nobody is.
-/// Byte-verified client-side as `[unit+0x110]+0x10`: the shared attack-start validator
-/// `0x612df0` reads it at `0x612e33` and refuses the swing when it is nonzero and is **not** the
-/// active player's own guid (`ERR_ATTACK_CHARMED`), and the owner-guid pair in both `0x5ee5a0`
-/// and the `PET_ATTACK_*` callback `0x5ff580` prefers it over their respective fallbacks
-/// (wow-re `object-layer/scratch/pet-command-validators.md` §1/§2/§4).
+/// The charmer, 0 for none. The attack-start check `0x612df0` refuses a swing when it is set and
+/// is not us (`ERR_ATTACK_CHARMED`); `0x5ee5a0` and `0x5ff580` prefer it as the owner.
 const FIELD_UNIT_CHARMEDBY: u16 = 10;
-/// `UNIT_FIELD_SUMMONEDBY` (idx 12, `OBJECT_END(6) + 0x6`, a 2-field guid — vmangos
-/// `UpdateFields_1_12_1.h`) — the summoner of a pet/guardian/totem. With CREATEDBY below, the
-/// combat-text source-ownership classifier's "owned by me" test (wow-re `0x5efea0`).
+/// The summoner of a pet, guardian or totem; with CREATEDBY, the "owned by me" test of `0x5efea0`.
 const FIELD_UNIT_SUMMONEDBY: u16 = 12;
-/// `UNIT_FIELD_CREATEDBY` (idx 14, a 2-field guid) — the creator (totems, summoned objects).
 const FIELD_UNIT_CREATEDBY: u16 = 14;
-/// `UNIT_FIELD_CHANNEL_OBJECT` (idx 20, `OBJECT_END(6) + 0xE`, a 2-field guid, PUBLIC — VERIFIED
-/// vmangos `UpdateFields_1_12_1.h:48`) — the object a channeled spell is aimed at (may be the
-/// caster itself). Public, so an **observer** renders another unit's channel loop from this field
-/// pair, not from the self-only `MSG_CHANNEL_START`/`UPDATE` UI packets (decision 0099 phase 1).
+/// The channel's target, possibly the caster (`UpdateFields_1_12_1.h:48`). Public, so another
+/// unit's channel renders from it; `MSG_CHANNEL_START`/`UPDATE` reach only the caster.
 const FIELD_UNIT_CHANNEL_OBJECT: u16 = 20;
 pub const FIELD_UNIT_HEALTH: u16 = 22;
-/// `UNIT_FIELD_POWER1` — first of 5 consecutive power slots (mana, rage, focus, energy, happiness);
-/// `MAXPOWER1..5` sit symmetrically after `MAXHEALTH` (vmangos `UpdateFields_1_12_1.h`).
+/// Five power slots: mana, rage, focus, energy, happiness; `MAXPOWER1..5` follow `MAXHEALTH`.
 const FIELD_UNIT_POWER1: u16 = 23;
 pub const FIELD_UNIT_MAXHEALTH: u16 = 28;
 const FIELD_UNIT_MAXPOWER1: u16 = 29;
@@ -80,188 +55,110 @@ pub const FIELD_UNIT_FACTIONTEMPLATE: u16 = 35;
 const FIELD_UNIT_BYTES_0: u16 = 36;
 pub const FIELD_UNIT_BYTES_1: u16 = 138;
 pub const FIELD_UNIT_FLAGS: u16 = 46;
-// The aura block — four parallel arrays, all PUBLIC, so every unit we can see streams its full set
-// (vmangos `UpdateFields_1_12_1.h:67-70`, `OBJECT_END(6) + 0x29/0x59/0x5F/0x6B`). wow-re places the
-// same arrays in the client at `descriptor + 0xa4` / `+0x164` (= `0x29`/`0x59` × 4 — the same field
-// indices, derived independently from the binary: `object-layer/scratch/w2d1.md`, VERIFIED).
-// Duration and caster are NOT here and are not in any other field: duration reaches only the aura's
-// own target, over `SMSG_UPDATE_AURA_DURATION`; a caster guid never reaches anyone (decision 0255).
+// The aura block: four public parallel arrays (`UpdateFields_1_12_1.h:67-70`), which the client
+// reads at unit block bytes 0xa4 and 0x164 onward. Duration reaches only the aura's own target,
+// over `SMSG_UPDATE_AURA_DURATION`, and no packet carries the caster.
 pub const FIELD_UNIT_AURA: u16 = 47;
 /// Nibble-packed, 8 slots per `u32` (`SpellAuraHolder::SetAuraFlag`, `SpellAuras.cpp:7456-7462`).
 pub const FIELD_UNIT_AURAFLAGS: u16 = 95;
-/// Byte-packed, 4 slots per `u32` — the *caster's level* (`SetAuraLevel`, `SpellAuras.cpp:7484`).
+/// Byte-packed, 4 slots per `u32`: the caster's level (`SetAuraLevel`, `SpellAuras.cpp:7484`).
 const FIELD_UNIT_AURALEVELS: u16 = 101;
-/// Byte-packed, 4 slots per `u32`, holding `stack - 1` ("field expect count-1 for proper amount
-/// show" — `UpdateAuraApplication`, `SpellAuras.cpp:7500-7507`).
+/// Byte-packed, 4 slots per `u32`, holding `stack - 1` (`SpellAuras.cpp:7500-7507`).
 pub const FIELD_UNIT_AURAAPPLICATIONS: u16 = 113;
-/// `UNIT_FIELD_AURASTATE` (`OBJECT_END(6) + 0x77` = 125 — vmangos `UpdateFields_1_12_1.h`) — the
-/// aura-state bit set the usable walk's CasterAuraState/TargetAuraState legs test with
-/// `1 << (state-1)` (wow-re §2a; the client reads its parsed-descriptor copy at
-/// `[unit+0x110]+0x1dc`, the update-field identity corroborated by the bit-test semantics +
-/// vmangos `Unit::ModifyAuraState`).
+/// Aura-state bits, tested as `1 << (state - 1)` by the usable check (client `[unit+0x110]+0x1dc`).
 const FIELD_UNIT_AURASTATE: u16 = 125;
-/// `UNIT_FIELD_BOUNDINGRADIUS` (`OBJECT_END(6) + 0x7B` = 129, right before COMBATREACH — vmangos
-/// `UpdateFields_1_12_1.h`) — the unit's horizontal bounding radius (yd).
+/// Horizontal bounding radius, in yards.
 const FIELD_UNIT_BOUNDINGRADIUS: u16 = 129;
 const FIELD_UNIT_COMBATREACH: u16 = 130;
 const FIELD_UNIT_BASE_MANA: u16 = 162;
 const FIELD_UNIT_DISPLAYID: u16 = 131;
-/// `UNIT_FIELD_NATIVEDISPLAYID` (`OBJECT_END(6) + 0x7E` = 132, PUBLIC — vmangos
-/// `UpdateFields_1_12_1.h:77`; it is the index between DISPLAYID (131) and MOUNTDISPLAYID (133),
-/// both of which are independently pinned above). The unit's **unshifted** appearance: the server
-/// writes it once at spawn/login and leaves it alone through every transform — a druid form
-/// (`Aura::HandleAuraModShapeshift` sets DISPLAYID and restores it *from* this field), a GM
-/// `.modify morph`, a polymorph. `UNIT_FIELD_DISPLAYID` is what you see; this is what the unit is.
-///
-/// The client reads it for exactly one thing benilla cares about: the **mover collision prism**
-/// (`0x60b270` fetches its DBC row at `[unit+0x110]+0x1f8`, while its sibling `0x60ae10` uses
-/// `+0x1f4` = DISPLAYID against the same array) — so a shapeshift does *not* resize the collision
-/// box (wow-re `mover-collision-scalars.md`, `remote-swim-decision.md` §4; decision 1574).
+/// The unshifted appearance, untouched by forms, morphs and polymorph (`UpdateFields_1_12_1.h:77`).
+/// The client sizes the mover collision box from it (`0x60b270`), so a shapeshift keeps the box.
 const FIELD_UNIT_NATIVEDISPLAYID: u16 = 132;
-/// `UNIT_FIELD_MOUNTDISPLAYID` (`OBJECT_END(6) + 0x7F` = 133, PUBLIC — vmangos
-/// `UpdateFields_1_12_1.h:78`; byte-verified client-side at `[unit+0x110]+0x1fc` = index 0x85,
-/// wow-re `rf39-field-index-map.md`/`d1.md`, HARD). A raw `CreatureDisplayInfo` id: the mount the
-/// unit is riding, `0`/absent = not mounted. The server writes it on aura-78 apply and zeroes it
-/// on every dismount path (`Unit::Mount`/`Unmount`) — this field, not the aura, IS the mounted
-/// state (`Unit::IsMounted` reads it back; no flag or bytes field accompanies it). Decision 0441.
+/// The ridden mount's `CreatureDisplayInfo` id, 0 when unmounted; this field, not the aura, is the
+/// mounted state (`Unit::IsMounted`; client `[unit+0x110]+0x1fc`).
 pub const FIELD_UNIT_MOUNTDISPLAYID: u16 = 133;
-/// `UNIT_FIELD_PETNUMBER` (`OBJECT_END(6) + 0x85` = 139, PUBLIC — vmangos
-/// `UpdateFields_1_12_1.h:84`; byte-verified client-side as `[unit+0x110]+0x214` = relative index
-/// `0x85`, the second gate inside the rank getter `0x605620` — decision 0782). Non-zero ⇒ this
-/// unit is somebody's pet or charm, which is exactly how the
-/// client decides a creature has **no** classification (rank forced to 0), so no elite dragon, no
-/// ELITE/BOSS tooltip word and no world-boss skull on an enslaved mob.
+/// Nonzero on a pet or charm; the rank getter `0x605620` then forces rank 0, so an enslaved mob
+/// shows no elite dragon, tooltip rank word or boss skull.
 const FIELD_UNIT_PETNUMBER: u16 = 139;
-/// `UNIT_FIELD_PET_NAME_TIMESTAMP` (`OBJECT_END(6) + 0x86` = 140, PUBLIC — vmangos
-/// `UpdateFields_1_12_1.cpp:80`) — the unix second at which this pet's name was last set.
-///
-/// It matters because a pet's name does **not** ride its descriptor: it is answered once by
-/// `CMSG_PET_NAME_QUERY` and cached by pet NUMBER, so a rename would otherwise stay invisible until
-/// relog. The server bumps this on every `SetName` (`Pet.cpp:285`, and `HandlePetRename`'s last
-/// line `PetHandler.cpp:344`), which makes a **change** here the cache's one invalidation signal.
+/// Unix time of the pet's last rename (`Pet.cpp:285`). The name itself comes from
+/// `CMSG_PET_NAME_QUERY`, cached by pet number, so a change here invalidates that cache.
 const FIELD_UNIT_PET_NAME_TIMESTAMP: u16 = 140;
-/// `UNIT_FIELD_PETEXPERIENCE` (idx 141) / `UNIT_FIELD_PETNEXTLEVELEXP` (142) — a hunter pet's XP
-/// bar, the `(currXP, nextXP)` pair `GetPetExperience 0x4be840` returns in that order.
-/// Byte-verified client-side at `[unit+0x110]+0x21c` / `+0x220` (wow-re
-/// `ui/scratch/pet-action-bar-api.md` §11b); the client converts each with `fild qword` off a
-/// **zero-extended** dword, so neither can read negative however large it gets.
+/// With the next field, the `(currXP, nextXP)` pair `GetPetExperience` (`0x4be840`) returns; the
+/// client reads both unsigned.
 const FIELD_UNIT_PETEXPERIENCE: u16 = 141;
 const FIELD_UNIT_PETNEXTLEVELEXP: u16 = 142;
-/// `UNIT_TRAINING_POINTS` (idx 149) — **two `u16`s packed into one dword**, byte-verified at
-/// `[unit+0x110]+0x23c` / `+0x23e`: `GetPetTrainingPoints 0x4be790` pushes the **high** word first
-/// and the low word second, which `PetPaperDollFrame.lua` names `totalPoints, spent`.
+/// Two `u16`s: `GetPetTrainingPoints` (`0x4be790`) returns the high word first, which
+/// `PetPaperDollFrame.lua` names `totalPoints`, then the low word as `spent`.
 const FIELD_UNIT_TRAINING_POINTS: u16 = 149;
 pub const FIELD_UNIT_DYNAMIC_FLAGS: u16 = 143;
-/// `UNIT_CHANNEL_SPELL` (idx 144, `OBJECT_END(6) + 0x8A`, PUBLIC — VERIFIED vmangos
-/// `UpdateFields_1_12_1.h:89`) — the spell id a unit is channeling (`0` = not channeling).
+/// The spell being channeled, 0 for none (`UpdateFields_1_12_1.h:89`).
 pub const FIELD_UNIT_CHANNEL_SPELL: u16 = 144;
-/// `UNIT_CREATED_BY_SPELL` (idx 146, `OBJECT_END(6) + 0x8C`, PUBLIC — vmangos
-/// `UpdateFields_1_12_1.h`) — the spell that summoned this unit (`0` = not summoned by one). The
-/// **first** of the three gates on the reference's feed-pet path `0x6ea1e0`: a unit with no
-/// creating spell is not a pet you can feed, whatever else it is.
-///
-/// The index is fixed by construction rather than asserted from a header we don't ship: this table
-/// already pins both ends of a contiguous run — `PETEXPERIENCE` 141, `PETNEXTLEVELEXP` 142,
-/// `DYNAMIC_FLAGS` 143, `CHANNEL_SPELL` 144, `MOD_CAST_SPEED` 145, then this, then `NPC_FLAGS` 147.
+/// The summoning spell, 0 for none; the first gate of the client's feed-pet path `0x6ea1e0`.
 const FIELD_UNIT_CREATED_BY_SPELL: u16 = 146;
 pub const FIELD_UNIT_NPC_FLAGS: u16 = 147;
-/// `UNIT_NPC_EMOTESTATE` (`OBJECT_END + 0x8E`; PUBLIC — VERIFIED vmangos `UpdateFields_1_12_1.h:93`)
-/// — the unit's looping **state emote** as an `Emotes.dbc` id (dance, NPC cooking/working flavor).
-/// For a player it's the server echo of a state-class text emote (`HandleEmote`,
-/// `ChatHandler.cpp:738`); `0` = none.
+/// The looping state emote, an `Emotes.dbc` id or 0; on a player, the server's echo of a
+/// state-class emote (`ChatHandler.cpp:738`).
 const FIELD_UNIT_NPC_EMOTESTATE: u16 = 148;
-/// `UNIT_VIRTUAL_ITEM_SLOT_DISPLAY` (`OBJECT_END(6) + 0x1F`) — 3 consecutive dwords, one per
-/// `WeaponAttackType` slot (0 mainhand / 1 offhand / 2 ranged): a creature's virtual-weapon
-/// **display id**, written straight from `creature_equip_template`'s item's `DisplayInfoID`
-/// (VERIFIED vmangos `Creature.cpp` `Creature::SetVirtualItem`, `Creature.cpp:4158-4181`) — there's
-/// no item guid behind it, purely a render hint the client never resolves through the item system.
+/// A creature's weapon display ids (main hand, off hand, ranged), with no item behind them
+/// (`Creature.cpp:4158-4181`).
 const FIELD_UNIT_VIRTUAL_ITEM_SLOT_DISPLAY: u16 = 37;
-/// `UNIT_VIRTUAL_ITEM_INFO` (`OBJECT_END + 0x22`) — 6 dwords, 2 per slot. Dword 0 of a slot's pair
-/// packs `(class, subclass, material, inventoryType)` bytes (VERIFIED vmangos
-/// `CreatureDefines.h:621-627` `VirtualItemInfoByteOffset`); dword 1's byte 0 is the slot's Sheath
-/// (`CreatureDefines.h:628` `VIRTUAL_ITEM_INFO_1_OFFSET_SHEATH`), the rest of that dword unused.
+/// Two dwords per weapon slot: class, subclass, material and inventory type bytes, then the
+/// sheath byte (`CreatureDefines.h:621-628`).
 const FIELD_UNIT_VIRTUAL_ITEM_INFO: u16 = 40;
-/// `UNIT_FIELD_BYTES_2` (`OBJECT_END + 0x9E`; PUBLIC) — byte 0 is the sheath state (VERIFIED vmangos
-/// `UnitDefines.h:93` `UNIT_BYTES_2_OFFSET_SHEATH_STATE = 0`, written by `Unit::SetSheath`; for a
-/// player it's purely client-volunteered via `CMSG_SETSHEATHED` — the server has no other way to
-/// know a weapon is drawn). **Not** [`FIELD_PLAYER_BYTES_2`] (194, facialHair) — an unrelated,
-/// differently-indexed field; this UNIT-block index was cross-checked clean of the a783a5b
-/// PLAYER-block hex-comment drift (vmangos's own enum arithmetic and its stale hex comment agree
-/// here: `UNIT_END + 0x9E` both ways).
+/// Byte 0 is the sheath state (`UnitDefines.h:93`); a player's comes only from `CMSG_SETSHEATHED`.
+/// Not `FIELD_PLAYER_BYTES_2`.
 const FIELD_UNIT_BYTES_2: u16 = 164;
-// UNIT combat/stat block (decision 0208 phase 1a — the paper-doll stats pane). VERIFIED against
-// vmangos `UpdateFields_1_12_1.h` **enum arithmetic** this session (`OBJECT_END` = 6; unlike the
-// CONTAINER-onward block below, this block's own `//0x..` hex comments agree with the arithmetic —
-// no staleness here). Every index below chain-locks to the file's already-tested
-// `FIELD_PLAYER_INV_SLOT_HEAD` (486) anchor through `UNIT_END` (188) — see the tests.
+// UNIT combat and stat block: offset from OBJECT_END, then the wire type.
 const FIELD_UNIT_BASEATTACKTIME: u16 = 126; // OBJECT_END+0x78; 2 slots [main, offhand], ms, INT
 const FIELD_UNIT_RANGEDATTACKTIME: u16 = 128; // +0x7A, INT
 const FIELD_UNIT_MINDAMAGE: u16 = 134; // +0x80, FLOAT
 const FIELD_UNIT_MAXDAMAGE: u16 = 135; // +0x81, FLOAT
 const FIELD_UNIT_MINOFFHANDDAMAGE: u16 = 136; // +0x82, FLOAT
 const FIELD_UNIT_MAXOFFHANDDAMAGE: u16 = 137; // +0x83, FLOAT
-const FIELD_UNIT_STAT0: u16 = 150; // +0x90 ×5, INT (`Unit::SetStat`→`SetStatInt32Value`)
-const FIELD_UNIT_RESISTANCES: u16 = 155; // +0x95 ×7, INT; [0] = armor (`Unit::SetArmor` writes +0)
+const FIELD_UNIT_STAT0: u16 = 150; // +0x90 ×5, INT
+const FIELD_UNIT_RESISTANCES: u16 = 155; // +0x95 ×7, INT; [0] = armor
 const FIELD_UNIT_ATTACK_POWER: u16 = 165; // +0x9F, INT
-/// `UNIT_FIELD_ATTACK_POWER_MODS` (166, +0xA0, `TWO_SHORT`) — `(positiveMods, negativeMods)` as
-/// **signed 16-bit halves**, lo = positive, hi = negative (VERIFIED vmangos
-/// `StatSystem.cpp:335-336`, `Player::UpdateAttackPowerAndDamage`: `SetInt16Value(index_mod, 0,
-/// (int16)attackPowerModPositive)` / `SetInt16Value(index_mod, 1, (int16)attackPowerModNegative)`;
-/// `Object::SetUInt16Value`'s `offset*16` shift confirms offset 0 = the low half). The negative
-/// half is stored **already negative-or-zero** — `Unit::HandleAttackPowerModifier`'s
-/// `AP_MOD_NEGATIVE_FLAT` branch accumulates `apply ? amount : -amount`, and its caller
-/// (`SpellAuras.cpp:5116`) only routes there when `!IsPositive()`, i.e. `amount` is already ≤ 0.
+/// +0xA0, `TWO_SHORT`: signed halves, the low positive, the high already negative or zero
+/// (`StatSystem.cpp:335-336`).
 const FIELD_UNIT_ATTACK_POWER_MODS: u16 = 166;
-const FIELD_UNIT_ATTACK_POWER_MULTIPLIER: u16 = 167; // +0xA1, FLOAT: (multiplier − 1.0), StatSystem.cpp:339-340
+const FIELD_UNIT_ATTACK_POWER_MULTIPLIER: u16 = 167; // +0xA1, FLOAT: multiplier − 1.0
 const FIELD_UNIT_RANGED_ATTACK_POWER: u16 = 168; // +0xA2, INT
-const FIELD_UNIT_RANGED_ATTACK_POWER_MODS: u16 = 169; // +0xA3, same TWO_SHORT packing as melee above
+const FIELD_UNIT_RANGED_ATTACK_POWER_MODS: u16 = 169; // +0xA3, TWO_SHORT as above
 const FIELD_UNIT_RANGED_ATTACK_POWER_MULTIPLIER: u16 = 170; // +0xA4, FLOAT
 const FIELD_UNIT_MINRANGEDDAMAGE: u16 = 171; // +0xA5, FLOAT
 const FIELD_UNIT_MAXRANGEDDAMAGE: u16 = 172; // +0xA6, FLOAT
 
 /// Aura slots per unit (vmangos `MAX_AURAS`, `SpellAuraDefines.h:25`).
 pub const UNIT_AURA_SLOTS: u8 = 48;
-/// Slots `0..UNIT_AURA_POSITIVE_SLOTS` hold **buffs**; the rest hold **debuffs** (vmangos
-/// `MAX_POSITIVE_AURAS`, `SpellAuraDefines.h:26`). The server picks the lowest free slot in the
-/// matching half (`SpellAuraHolder::_AddSpellAuraHolder`, `SpellAuras.cpp:6715-6736`), and assigns
-/// no slot at all to an aura that fails `IsNeedVisibleSlot` — so **passives never reach the wire**
-/// and a client renders the array as-is, with no filtering of its own.
+/// Slots below this hold buffs, the rest debuffs (`SpellAuraDefines.h:26`). Passives get no slot,
+/// so the client renders the array unfiltered (`SpellAuras.cpp:6715-6736`).
 pub const UNIT_AURA_POSITIVE_SLOTS: u8 = 32;
 
-/// `AFLAG_CANCELABLE` (vmangos `SpellAuraDefines.h:31`) — the right-click gate. The server sets it
-/// iff the aura is positive and its spell lacks `SPELL_ATTR_NO_AURA_CANCEL` (`SpellAuras.cpp:7467`),
-/// which is exactly the condition `CMSG_CANCEL_AURA`'s handler re-checks, so honouring this bit is
-/// enough — no `Spell.dbc` lookup needed to know whether a buff can be clicked off.
+/// `AFLAG_CANCELABLE`: set on a positive aura without `SPELL_ATTR_NO_AURA_CANCEL`, the same test
+/// the `CMSG_CANCEL_AURA` handler makes (`SpellAuras.cpp:7467`).
 pub const AURA_FLAG_CANCELABLE: u8 = 0x01;
-/// `AFLAG_EFF_INDEX_0|1|2` — which of the spell's three effects this holder actually applied. An
-/// occupied slot always has at least one set, which is why the real client uses `flags & 0x0E` as
-/// its liveness test (wow-re `object-layer/scratch/w2d1.md`), and why [`ObjectFields::unit_aura`]
-/// gates on it too: a slot the server clears can keep a **stale spell id** after its flags nibble
-/// goes to zero, so `flags & 0x0E` — not "has a spell id" — is what tells a live aura from a husk.
-/// Gating on the id alone surfaces the husk as a phantom buff the real client never shows.
+/// `AFLAG_EFF_INDEX_0|1|2`, the client's aura liveness test: a cleared slot can keep a stale spell
+/// id, so a live aura is one with any of these bits set.
 pub const AURA_FLAG_EFF_INDEX_MASK: u8 = 0x0E;
 
-/// One **occupied** aura slot, decoded from the four parallel `UNIT_FIELD_AURA*` arrays. Everything
-/// the 1.12 wire says about a resident aura is here; note what is missing and cannot be added — the
-/// **remaining duration** (self-only, and it arrives out-of-band on `SMSG_UPDATE_AURA_DURATION`) and
-/// the **caster** (which no packet ever associates with a slot). Decision 0255.
+/// One occupied aura slot, from the four `UNIT_FIELD_AURA*` arrays; duration and caster are not
+/// on the descriptor.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct UnitAuraSlot {
-    /// The slot index it occupies, `0..UNIT_AURA_SLOTS`. Also its buff/debuff class, and the key
-    /// `SMSG_UPDATE_AURA_DURATION` uses.
+    /// Also the buff or debuff class, and the key `SMSG_UPDATE_AURA_DURATION` uses.
     pub slot: u8,
-    /// The `Spell.dbc` id.
     pub spell_id: u32,
-    /// The raw `UNIT_FIELD_AURAFLAGS` nibble for this slot.
+    /// The raw `UNIT_FIELD_AURAFLAGS` nibble.
     pub flags: u8,
-    /// The **caster's** level at apply time — the only thing the wire says about who cast this.
+    /// The caster's level at apply time, the only trace of the caster.
     pub level: u8,
-    /// Stack count, ≥ 1 (the wire byte holds `stack - 1`).
+    /// At least 1; the wire byte holds `stack - 1`.
     pub stacks: u8,
 }
 
 impl UnitAuraSlot {
-    /// A buff (slot in the positive half) rather than a debuff.
+    /// A buff: the slot is in the positive half.
     pub fn is_helpful(&self) -> bool {
         self.slot < UNIT_AURA_POSITIVE_SLOTS
     }
@@ -271,35 +168,20 @@ impl UnitAuraSlot {
     }
 }
 
-// PLAYER descriptor fields — player customization (RF-0056, byte-verified against the client's own
-// appearance decode `0x5fb200` + corpse cross-check). The PLAYER block starts at field 188.
+// PLAYER fields start at UNIT_END (188); the client decodes appearance bytes at `0x5fb200`.
 const FIELD_PLAYER_BYTES: u16 = 193;
 const FIELD_PLAYER_BYTES_2: u16 = 194;
-// PLAYER_BYTES_3 = UNIT_END(188) + 0x7: the low u16 packs `gender | (drunk & 0xFFFE)` (vmangos
-// `Player::SetDrunkValue`), so byte 1 is the drunk value's high byte — exactly the byte the
-// reference client reads at `[[unit+0xe68]+0x1d]` (wow-re `drunk_fraction_5e2a90`).
-// Byte 2 = the city-protector title (a race id), byte 3 = the **current** honor rank
-// (`PLAYER_BYTES_3_OFFSET_HONOR_RANK`, vmangos `Player.h:351-356`).
-//
-// **PUBLIC** (VERIFIED vmangos `UpdateFields_1_12_1.h:125`) — and that flag is the whole reason a
-// foreign player's rank is knowable: this is the ONE honor value that streams for every visible
-// player. The rest of the honor block (1250..1260 below, plus `PLAYER_FIELD_BYTES`' highest-rank
-// byte) is PRIVATE, which is why anyone else's honor stats have to be *asked* for over the wire
-// (`MSG_INSPECT_HONOR_STATS`, [`crate::messages::InspectHonorStats`]).
+// The low u16 is `gender | (drunk & 0xFFFE)`, so byte 1 is the drunk level the client reads at
+// `[[unit+0xe68]+0x1d]`; byte 2 is the city-protector race, byte 3 the current honor rank
+// (`Player.h:351-356`). Public: the one honor value that streams for every visible player.
 const FIELD_PLAYER_BYTES_3: u16 = 195;
-// PLAYER_QUEST_LOG_1_1 = UNIT_END(188) + 0xA = 198 (vmangos `UpdateFields_1_12_1.h:128`; this block
-// precedes the CONTAINER-onward hex-comment drift — enum arithmetic and hex comment agree here, and
-// decision 0088 §4 live-verified an accepted quest id landing on 198 + 3·slot). 20 slots
-// (MAX_QUEST_LOG_SIZE, vmangos `QuestDef.h:34`) × 3 fields (MAX_QUEST_OFFSET, `Player.h:439-444`):
-// +0 quest id, +1 packed objective counters + state byte, +2 timer. The `_1` id field is GROUP_ONLY
-// and the `_2` pair PRIVATE — both always stream for our own player, the exact consumer (the log).
+// 20 slots of 3 fields (`Player.h:439-444`): the quest id (group-only), then the counters and
+// state byte, and the timer (both private).
 pub const FIELD_PLAYER_QUEST_LOG_1_1: u16 = 198;
 
-/// The descriptor indices a field watch names (decision 2297) — the very constants the accessors
-/// above read through, re-exported under one roof so a watch and the accessor it mirrors cannot
-/// disagree on a number. Anything watched lives here; anything only read stays private.
+/// The indices a field watch names: the same constants the accessors read, so the two agree.
 pub mod field {
-    /// The one bit a watcher tests on a raw `UNIT_DYNAMIC_FLAGS` edge (the feign-death set edge).
+    /// The bit a watcher tests on a raw `UNIT_DYNAMIC_FLAGS` edge (feign death).
     pub use super::unit::UNIT_DYNFLAG_DEAD;
     pub use super::{
         FIELD_CORPSE_DYNAMIC_FLAGS, FIELD_GAMEOBJECT_STATE, FIELD_PLAYER_FIELD_COINAGE,
@@ -311,108 +193,56 @@ pub mod field {
     };
 }
 
-/// The number of `PLAYER_QUEST_LOG` slots (vmangos `MAX_QUEST_LOG_SIZE`, `QuestDef.h:34`).
+/// `MAX_QUEST_LOG_SIZE` (`QuestDef.h:34`).
 pub const PLAYER_QUEST_LOG_SLOTS: u8 = 20;
 
-/// One decoded `PLAYER_QUEST_LOG` slot — the descriptor's durable quest-log state (the
-/// `SMSG_QUESTUPDATE_*` packets are the transient "toast" lines; this is what survives).
+/// One `PLAYER_QUEST_LOG` slot, the durable quest state; `SMSG_QUESTUPDATE_*` are only toasts.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct QuestLogSlot {
-    /// The quest id occupying the slot (`0` = the server cleared it — an empty slot).
+    /// 0 for an empty slot.
     pub quest_id: u32,
-    /// The four 6-bit kill/cast/interact objective counters (counter `i` at bits `6i..6i+6` of the
-    /// count-state field — vmangos `Player.h:1100-1106` `SetQuestSlotCounter`). Item-objective
-    /// progress is *not* here; the client counts bag items itself.
+    /// Four 6-bit kill, cast and interact counters at bits `6i..6i+6` (`Player.h:1100-1106`); the
+    /// client counts item objectives from the bags itself.
     pub counters: [u8; 4],
-    /// The state byte (byte 3 of the count-state field — `Player.h:1107` `SetQuestSlotState`):
-    /// [`quest_slot_state::COMPLETE`] / [`quest_slot_state::FAIL`], `0` = in progress.
+    /// Byte 3 of the counter field (`Player.h:1107`): a [`quest_slot_state`] bit, 0 in progress.
     pub state: u8,
-    /// The timer field — the absolute end time for a timed quest, else `0`.
+    /// The absolute end time of a timed quest, else 0.
     pub timer: u32,
 }
 
-/// `QUEST_STATE_*` (vmangos `Player.h:447-451`) — [`QuestLogSlot::state`] bit values.
+/// `QUEST_STATE_*` bits of [`QuestLogSlot::state`] (`Player.h:447-451`).
 pub mod quest_slot_state {
     pub const COMPLETE: u8 = 0x01;
     pub const FAIL: u8 = 0x02;
 }
-// ITEM/CONTAINER/PLAYER inventory fields (VERIFIED vmangos `UpdateFields_1_12_1.h` **enum
-// arithmetic** — never its hex comments; see below) — the T2 container groundwork. The PLAYER
-// slot arrays are PRIVATE-flagged: the server sends them only for our own player, which is
-// exactly the consumer (our bags). Each slot is a 2-field guid.
-const FIELD_ITEM_STACK_COUNT: u16 = 14; // OBJECT_END(6) + 0x8 (the ITEM-block comments are still true)
-const FIELD_ITEM_ENCHANTMENT: u16 = 22; // OBJECT_END + 0x10, Size 21 = 7 slots × 3 (id/duration/charges)
-const FIELD_CONTAINER_NUM_SLOTS: u16 = 48; // ITEM_END = 6 + 0x2A (comment says 42 — stale, 6 low)
+// Inventory fields. The PLAYER slot arrays are private, and each slot is a 2-field guid.
+const FIELD_ITEM_STACK_COUNT: u16 = 14; // OBJECT_END + 0x8
+const FIELD_ITEM_ENCHANTMENT: u16 = 22; // OBJECT_END + 0x10; 7 slots × 3 (id, duration, charges)
+const FIELD_CONTAINER_NUM_SLOTS: u16 = 48; // ITEM_END = 6 + 0x2A
 const FIELD_CONTAINER_SLOT_1: u16 = 50; // ITEM_END + 0x2; 36 slots × 2
 
-// CORRECTED 2026-07-03: vmangos's UpdateFields_1_12_1.h hex COMMENTS go stale from the CONTAINER
-// block on (6 low vs its own enum arithmetic, which is what the server compiles): INV_SLOT_HEAD =
-// UNIT_END(0xBC) + 0x12A = 0x1E6 = 486, not the commented 0x1E0. VERIFIED against a live
-// descriptor dump: with these bases One's shirt/legs/feet/mainhand/offhand/bags land on exactly
-// the slots the character visibly wears (visible-item cross-check below).
+// From the CONTAINER block on, the hex comments in vmangos `UpdateFields_1_12_1.h` run 6 low. The
+// indices here follow its enum arithmetic, which the server compiles: INV_SLOT_HEAD = 188 + 0x12A.
 const FIELD_PLAYER_VISIBLE_ITEM_1_CREATOR: u16 = 258; // UNIT_END + 0x46; 12 fields per slot
-pub const FIELD_PLAYER_INV_SLOT_HEAD: u16 = 486; // 23 slots × 2 (equipment 0–18, bag bags 19–22)
+pub const FIELD_PLAYER_INV_SLOT_HEAD: u16 = 486; // 23 slots × 2 (equipment 0–18, bags 19–22)
 const FIELD_PLAYER_PACK_SLOT_1: u16 = 532; // 16 slots × 2 (the backpack)
 const FIELD_PLAYER_BANK_SLOT_1: u16 = 564; // 24 slots × 2
 const FIELD_PLAYER_BANK_BAG_SLOT_1: u16 = 612; // 564 + 24×2; 6 bag slots × 2 (item guids)
-                                               // The buyback trio (VERIFIED two ways: the slot array is chain-locked between the tested BANK
-                                               // anchor and the tested XP anchor — 564 +48 bank = 612 bankbags, +12 = 624 buyback, +24 keyring
-                                               // 648, +64 farsight 712, +2 combo 714, +2 = XP 716 ✓ — and price/timestamp are wow-re byte
-                                               // anchors (ui/scratch/buyback-data-path.md: playerBlock +0x1038/+0x1068) rebased through the
-                                               // tested COINAGE anchor: block base = 1176 − 0xf70/4 = 188 → 188+1038 = 1226, 188+1050 = 1238).
 const FIELD_PLAYER_VENDORBUYBACK_SLOT_1: u16 = 624; // 12 slots × 2 (item guids)
-                                                    // PLAYER_FIELD_KEYRING_SLOT_1 — the next link of the same chain the buyback comment walks
-                                                    // (624 + 12×2 = 648; +32×2 = 712 = FARSIGHT ✓, which the chain's far end already pins).
 const FIELD_PLAYER_KEYRING_SLOT_1: u16 = 648; // 32 slots × 2 (item guids), wire slots 81–112
-                                              // PLAYER_FARSIGHT — the object our view is anchored to (Mind Vision, Sentry Totem, the Ornate
-                                              // Spyglass), or 0 for "my own body". A 2-field guid, PRIVATE, so it only ever arrives on our own
-                                              // descriptor — exactly the consumer. Its index needs no fresh derivation: it is the next link of
-                                              // the same chain the two comments above walk, and both ends of that chain are tested anchors
-                                              // (648 + 32×2 = 712; +2 combo 714, +2 = XP 716 ✓). vmangos's hex comment reads 0x2C2 = 706 — the
-                                              // same 6-low drift as COINAGE/XP, and not what the server compiles: its enum arithmetic says
-                                              // UNIT_END(0xBC = 188) + 0x20C(524) = 712.
-const FIELD_PLAYER_FARSIGHT: u16 = 712;
+const FIELD_PLAYER_FARSIGHT: u16 = 712; // our view's anchor (Mind Vision, Sentry Totem), or 0
 const FIELD_PLAYER_BUYBACK_PRICE_1: u16 = 1226; // 12 × u32 copper, indexed slot−69
-const FIELD_PLAYER_BUYBACK_TIMESTAMP_1: u16 = 1238; // 12 × u32 — the client's sort key only
-                                                    // PLAYER_FIELD_COINAGE, our purse in copper (INT, PRIVATE — sent only for our own player, the exact
-                                                    // consumer). Same comment drift as the slot arrays above: from the CONTAINER block on, vmangos's
-                                                    // UpdateFields_1_12_1.h hex comments run 6 low vs its own enum arithmetic (which is what the server
-                                                    // compiles). Derived by that arithmetic: COINAGE = UNIT_END(0xBC = 188) + 0x3DC(988) = 1176; the
-                                                    // stale hex comment reads 0x492 = 1170 (decision 0081 quoted "field 1170" from it — 6 low).
-                                                    // Cross-checked against the corrected neighbours: 486 (INV_SLOT_HEAD) + (0x3DC − 0x12A = 690) = 1176;
-                                                    // 564 (BANK_SLOT_1) + (0x3DC − 0x178 = 612) = 1176. Both agree.
-pub const FIELD_PLAYER_FIELD_COINAGE: u16 = 1176;
-// PLAYER_XP / PLAYER_NEXT_LEVEL_XP (INT, PRIVATE — sent only for our own player, the exact consumer:
-// the MainMenuBar XP bar). Derived by the same server enum arithmetic as COINAGE above:
-// PLAYER_XP = UNIT_END(0xBC = 188) + 0x210(528) = 716; PLAYER_NEXT_LEVEL_XP = 717. Cross-checked
-// against COINAGE: 1176 − 716 = 460 = (0x3DC − 0x210). (vmangos UpdateFields_1_12_1.h lists them at
-// UNIT_END + 0x210 / 0x211; its stale hex comments read 0x2C6/0x2C7, the same 6-low drift as COINAGE.)
+const FIELD_PLAYER_BUYBACK_TIMESTAMP_1: u16 = 1238; // 12 × u32, the client's sort key only
+pub const FIELD_PLAYER_FIELD_COINAGE: u16 = 1176; // copper
 const FIELD_PLAYER_XP: u16 = 716;
 const FIELD_PLAYER_NEXT_LEVEL_XP: u16 = 717;
-// PLAYER_FIELD_WATCHED_FACTION_INDEX (INT, PRIVATE — self only): the reputation-list slot whose bar
-// rides the main menu bar, or -1 for none. SIGNED, and that matters — slot 0 is a real faction (the
-// Bloodsail Buccaneers), so -1 is the only "watch nothing" (vmangos writes it with `SetInt32Value`
-// in `HandleSetWatchedFactionOpcode`). Derived by the same server enum arithmetic as COINAGE above:
-// UNIT_END(0xBC = 188) + 0x431(1073) = 1261. Cross-checked against the tested COINAGE anchor:
-// 1176 + (0x431 − 0x3DC = 85) = 1261 ✓. (vmangos UpdateFields_1_12_1.h's stale hex comment reads
-// 0x4E7 = 1255, the usual 6-low drift.)
+// The watched reputation slot, signed: slot 0 is a real faction, so only -1 means none.
 const FIELD_PLAYER_WATCHED_FACTION_INDEX: u16 = 1261;
-// PLAYER_REST_STATE_EXPERIENCE (INT, PRIVATE — self only): the rested-XP pool, in BASE kill-XP
-// units — the server drains it 1:1 against a kill's base XP while granting +100%
-// (vmangos `Player::GetXPRestBonus`), and caps it at NEXT_LEVEL_XP × 1.5 / 2 (`SetRestBonus`), so
-// the on-screen doubled-XP span is 2× this field (the exhaustion tick's math; decision 1082).
-// Derived by the same server enum arithmetic as COINAGE above: UNIT_END(0xBC = 188) +
-// 0x3DB(987) = 1175 — exactly one below the tested COINAGE anchor (1175 + 1 = 1176 ✓).
+// The rested pool in base kill-XP units: a kill drains it 1:1 while granting +100%
+// (`Player::GetXPRestBonus`), so the doubled span on the XP bar is twice this value.
 const FIELD_PLAYER_REST_STATE_EXPERIENCE: u16 = 1175;
-// PLAYER_EXPLORED_ZONES_1 (BYTES ×64, PRIVATE — self only): the discovery bitset, 2048 bits
-// indexed by AreaTable's exploreFlag column; the world map's exploration overlays key off it
-// (decision 0203 phase 3). Derived by the same server enum arithmetic as COINAGE/XP above:
-// UNIT_END(0xBC = 188) + 0x39B(923) = 1111. Cross-checked against COINAGE: 0x3DC − 0x39B = 65 =
-// the 64 bitset slots + PLAYER_REST_STATE_EXPERIENCE between them (1111 + 64 = 1175, then
-// 1176 ✓); the stale hex comment reads 0x451 — the usual 6-low drift.
-// The four avoidance/crit percentages the spell tooltip's chance-to-X line reads (law §3-CHANCE),
-// consecutive and immediately below EXPLORED_ZONES_1: UNIT_END(188) + 0x396..0x399. FLOAT, and the
-// header agrees for once. Anchored on EXPLORED_ZONES_1 = UNIT_END + 0x39B = 1111 just below.
+// EXPLORED_ZONES_1 is the discovery bitset, 2048 bits indexed by `AreaTable.dbc` exploreFlag. Just
+// below it sit block, dodge, parry and crit chance (FLOAT, UNIT_END + 0x396..0x399).
 const FIELD_PLAYER_BLOCK_PERCENTAGE: u16 = 1106;
 const FIELD_PLAYER_DODGE_PERCENTAGE: u16 = 1107;
 const FIELD_PLAYER_PARRY_PERCENTAGE: u16 = 1108;
@@ -420,143 +250,47 @@ const FIELD_PLAYER_CRIT_PERCENTAGE: u16 = 1109;
 const FIELD_PLAYER_EXPLORED_ZONES_1: u16 = 1111;
 /// The bitset's slot count (`Size: 64` in the server enum).
 pub const PLAYER_EXPLORED_ZONES_SLOTS: u16 = 64;
-// PLAYER stat/skill block (decision 0208 phase 1a). Derived the same way as the buyback trio above:
-// `UNIT_END`(188) + vmangos's own symbolic offset, in **decimal** (never the hex `//` comments, stale
-// from the CONTAINER block on) — chain-verified against the already-tested COINAGE(1176) and
-// BUYBACK_PRICE_1(1226) anchors (see the tests).
-// **These four families are INT on the wire, and the server's own storage type is not the wire
-// type** (decision 1397). The header's "Type: INT" tag is right and the earlier "FLOAT" reading
-// here was wrong: it was taken from vmangos's *internal* accessors (`Player.h:1505,1511-1514`
-// really do route through `ApplyModSignedFloatValue`/`GetFloatValue`), which is one layer below
-// the question. `Object::BuildValuesUpdate` (`Objects/Object.cpp`) carries an explicit special
-// case — comment *"there are some float values which may be negative or can't get negative due to
-// other checks"* — that sends exactly `NEGSTAT0..4`, `POSSTAT0..4`,
-// `RESISTANCEBUFFMODSPOSITIVE+0..6` and `…NEGATIVE+0..6` as `*data << uint32(m_floatValues[index])`,
-// the same float→int narrowing it already applies to `UNIT_FIELD_BASEATTACKTIME`. Live-confirmed on
-// a level-60 warrior in preraid-BiS gear: fields 1177..1181 arrive as `105, 76, 68, 4, 4` (the
-// gear's own +105 str / +76 agi / …), and 1215 `MOD_DAMAGE_DONE_PCT` in the same packet arrives as
-// `0x3F800000` — genuine f32 — so the two encodings sit side by side in one block.
-//
-// Read **signed**: the server's cast of a negative float to `uint32` is UB, and the two
-// architectures disagree. On x86 it wraps to the two's-complement word; on aarch64 `fcvtzu`
-// saturates and a stat *debuff* arrives as a flat `0` (measured on this deploy's arm64 container:
-// a −5 agility debuff moved `UNIT_FIELD_STAT1` but sent `NEGSTAT1 = 0`). `i32` is right for both.
+// PLAYER stat block. POSSTAT, NEGSTAT and the resistance buff mods are floats in vmangos but go out
+// as INT (`Object::BuildValuesUpdate` narrows them). Read them signed: the server's cast of a
+// negative float wraps on x86 and saturates to 0 on aarch64.
 const FIELD_PLAYER_POSSTAT0: u16 = 1177; // UNIT_END+0x3DD ×5, INT
 const FIELD_PLAYER_NEGSTAT0: u16 = 1182; // ×5, INT; negative-or-zero where the wire can carry it
 const FIELD_PLAYER_RESISTANCEBUFFMODSPOSITIVE: u16 = 1187; // ×7, INT
 const FIELD_PLAYER_RESISTANCEBUFFMODSNEGATIVE: u16 = 1194; // ×7, INT; negative-or-zero
-const FIELD_PLAYER_MOD_DAMAGE_DONE_POS: u16 = 1201; // ×7 schools ([0]=physical), INT (VERIFIED
-                                                    // `StatSystem.cpp:87` `SetStatInt32Value` for the magic
-                                                    // schools, `SpellAuras.cpp:5208-5210`
-                                                    // `ApplyModUInt32Value` for school 0/physical).
-const FIELD_PLAYER_MOD_DAMAGE_DONE_NEG: u16 = 1208; // ×7, INT; negative-or-zero (VERIFIED
-                                                    // `SpellAuras.cpp:5211-5213,5244-5247`
-                                                    // `ApplyModInt32Value(..., m_modifier.m_amount, apply)`
-                                                    // with an already-negative `m_amount` on the debuff branch).
-const FIELD_PLAYER_MOD_DAMAGE_DONE_PCT: u16 = 1215; // ×7, **FLOAT despite the header's "Type: INT"
-                                                    // tag** (VERIFIED vmangos `Player.cpp:3336`
-                                                    // `SetFloatValue(PLAYER_FIELD_MOD_DAMAGE_DONE_PCT + i,
-                                                    // 1.00f)` init and `Player.cpp:7274`
-                                                    // `SetFloatValue(PLAYER_FIELD_MOD_DAMAGE_DONE_PCT +
-                                                    // school, multiplier)` — decision 0208's flagged
-                                                    // question, now closed: a true float, default 1.0.
-                                                    // UNIT_END+0x212, ×384 (128 skills × 3 dwords) — see [`PlayerSkillSlot`] for the verified
-                                                    // packing. `pub` for fixtures that seed a skill block through [`ObjectFields::from_pairs`]
-                                                    // (the lock resolver's skill-term tests); live reads go through [`ObjectFields::player_skill`].
-pub const FIELD_PLAYER_SKILL_INFO_1_1: u16 = 718;
+const FIELD_PLAYER_MOD_DAMAGE_DONE_POS: u16 = 1201; // ×7 schools ([0] physical), INT
+const FIELD_PLAYER_MOD_DAMAGE_DONE_NEG: u16 = 1208; // ×7, INT; negative-or-zero
+const FIELD_PLAYER_MOD_DAMAGE_DONE_PCT: u16 = 1215; // ×7, FLOAT (header says INT), default 1.0
+                                                    // (`Player.cpp:3336`, `Player.cpp:7274`)
+pub const FIELD_PLAYER_SKILL_INFO_1_1: u16 = 718; // ×384: 128 skills × 3 dwords
 
-// PLAYER_CHARACTER_POINTS1/2 (INT, PRIVATE — self only): unspent talent points / free primary
-// professions — the reference's `UnitCharacterPoints("player")` pair (decision 0304). Derived by
-// the same server enum arithmetic as the anchors above: UNIT_END(188) + 0x392(914) = 1102 and
-// +0x393 = 1103 — exactly one past the skill array (718 + 384 = 1102 ✓, the tests' chain).
+// Unspent talent points and free primary professions, `UnitCharacterPoints("player")`.
 const FIELD_PLAYER_CHARACTER_POINTS1: u16 = 1102;
 const FIELD_PLAYER_CHARACTER_POINTS2: u16 = 1103;
-// PLAYER_TRACK_CREATURES / PLAYER_TRACK_RESOURCES (INT, PRIVATE — self only): the active tracking
-// bitmasks the minimap dot classifier tests — bit `1 << (n − 1)` where `n` is a creature type
-// (TRACK_CREATURES) or a `LockType.dbc` id (TRACK_RESOURCES); the server sets one bit per active
-// tracking aura from the aura's MiscValue (vmangos `SpellAuras.cpp` `HandleAuraTrackCreatures`/
-// `HandleAuraTrackResources`, `1 << (m_miscvalue − 1)`). Derived by the same server enum
-// arithmetic as the anchors above: UNIT_END(188) + 0x394(916) = 1104 and +0x395 = 1105 —
-// contiguous past the CHARACTER_POINTS pair (1103 + 1 = 1104 ✓).
+// Tracking masks the minimap tests: bit `1 << (n - 1)` for creature type or `LockType.dbc` id `n`,
+// one bit per active tracking aura.
 const FIELD_PLAYER_TRACK_CREATURES: u16 = 1104;
 const FIELD_PLAYER_TRACK_RESOURCES: u16 = 1105;
-const FIELD_PLAYER_AMMO_ID: u16 = 1223; // UNIT_END+0x40B, INT — the equipped ammo item id
-                                        // (`Player.cpp:7656` etc., `Player::SetUInt32Value`).
-                                        // PLAYER_SELF_RES_SPELL = UNIT_END(188) + 0x40C (INT, **PRIVATE** — self only), the spell id the
-                                        // server will cast if we ask to self-resurrect: the whole soulstone/Reincarnation mechanism, on
-                                        // the wire as one dword (decision 1746). Contiguous past the ammo id (1223 + 1 = 1224 ✓), and
-                                        // cross-checked two ways in vmangos because its two tables disagree: the enum
-                                        // `UpdateFields_1_12_1.h:284` gives `UNIT_END + 0x40C` (= 1224) while its trailing *comment* says
-                                        // `// 0x4C2` — the comment is stale; the parallel descriptor table `UpdateFields_1_12_1.cpp:277`
-                                        // carries the absolute index `0x4C8` = **1224**, agreeing with the arithmetic.
+const FIELD_PLAYER_AMMO_ID: u16 = 1223; // UNIT_END+0x40B, INT: the equipped ammo item id
 const FIELD_PLAYER_SELF_RES_SPELL: u16 = 1224;
-// PLAYER_FLAGS = UNIT_END(188) + 0x2 (VERIFIED vmangos `UpdateFields_1_12_1.h:120`; the duel
-// arbiter guid takes +0x0/+0x1). Bit 0x10 = PLAYER_FLAGS_GHOST (`Player.h:319`), set/cleared by
-// the ghost aura 8326's HandleAuraGhost at release/resurrect (decision 0308 §1).
+// Bit 0x10 is PLAYER_FLAGS_GHOST (`Player.h:319`), held by the ghost aura 8326 until resurrection.
 pub const FIELD_PLAYER_FLAGS: u16 = 190;
-// PLAYER_DUEL_ARBITER = UNIT_END(188) + 0x0 (GUID, PUBLIC), PLAYER_DUEL_TEAM = UNIT_END + 0x8
-// (INT, PUBLIC) — VERIFIED vmangos `UpdateFields_1_12_1.h:119,126`. The arbiter opens the player
-// block, which is why the real client caches a pointer to that base (`[player+0xe68]`) and indexes
-// both off it: `+0x00/+0x04` the arbiter halves, `+0x08` PLAYER_FLAGS, `+0x20` the duel team — the
-// three reads `UnitReaction 0x6061e0`'s duel leg makes (decision 0633).
+// The client's player block base `[player+0xe68]` is field 188: the arbiter at +0x0, PLAYER_FLAGS
+// at +0x8 and the duel team at +0x20, the three reads of `UnitReaction`'s duel leg (`0x6061e0`).
 const FIELD_PLAYER_DUEL_ARBITER: u16 = 188;
 const FIELD_PLAYER_DUEL_TEAM: u16 = 196;
-// PLAYER_GUILDID = UNIT_END(188) + 0x3, PLAYER_GUILDRANK = UNIT_END + 0x4 — both INT and both
-// **PUBLIC** (VERIFIED vmangos `UpdateFields_1_12_1.h:120-121`), the same arithmetic that pins
-// PLAYER_FLAGS = 190 at +0x2 above. Independently VERIFIED in the binary off the very player-block
-// base the duel pair is read through: `GetGuildInfo 0x4c9330` takes the guild id at `[+0xe68]+0xc`
-// (`0x4c93a9`, whose `test ecx,ecx` IS the guildless→nil path) and the rank at `+0x10` (`0x4c93e4`,
-// `shl edx,0x6` — the 0x40-byte rank-name slot in the cached guild record). 0xc/4 + 188 = 191 and
-// 0x10/4 + 188 = 192, with `+0x8` = PLAYER_FLAGS(190) as the third point on the same line.
-//
-// PUBLIC is the load-bearing half: these stream for *every visible player*, not just for us, which
-// is what makes `GetGuildInfo(unit)` answerable for an arbitrary unit — and why the guild query
-// response carries a fixed ten rank names to decode another player's rank against (decision 1257).
+// Public, so `GetGuildInfo(unit)` (`0x4c9330`, reading block +0xc and +0x10) answers for any
+// visible player; a guild id of 0 is guildless.
 const FIELD_PLAYER_GUILDID: u16 = 191;
 const FIELD_PLAYER_GUILDRANK: u16 = 192;
-// PLAYER_FIELD_COMBO_TARGET = UNIT_END(188) + 0x20E (GUID, PRIVATE) — VERIFIED vmangos
-// `UpdateFields_1_12_1.h:251`, and independently by the binary: `GetComboPoints 0x51a190` reads the
-// pair at `[player+0xe68]+0x838/+0x83c`, and 0x838/4 + 188 = 714 (decision 0875). The same player-
-// block base that puts the combo-point byte at `+0x1029` (0x1029/4 + 188 = 1222) — two offsets off
-// one pointer landing on two independently-known field indices is what pins the base itself.
+// `GetComboPoints` (`0x51a190`) reads the target at block +0x838 and the count byte at +0x1029.
 const FIELD_PLAYER_FIELD_COMBO_TARGET: u16 = 714;
-const FIELD_PLAYER_FIELD_BYTES: u16 = 1222; // UNIT_END+0x40A, BYTES — vmangos `PLAYER_FIELD_BYTES`
-                                            // (distinct from the appearance `PLAYER_BYTES`(193)):
-                                            // flags / comboPoints / actionBars / HIGHEST_HONOR_RANK
-                                            // (`Player.h` PLAYER_FIELD_BYTES_OFFSET_*).
+const FIELD_PLAYER_FIELD_BYTES: u16 = 1222; // UNIT_END+0x40A: flags, combo points, action bars,
+                                            // highest honor rank; not the appearance PLAYER_BYTES
 
-// The **honor block** — the eleven fields the two PvP/honor panes read, a contiguous run
-// UNIT_END(188) + 0x426..0x430 (VERIFIED vmangos `UpdateFields_1_12_1.h:288-298` **enum
-// arithmetic**; its inline `// 0x4DC`-style comments carry the usual 6-low drift and are not
-// copied). The run needs no fresh anchor of its own: it closes against already-tested neighbours
-// at BOTH ends — the 12-slot `BUYBACK_TIMESTAMP_1` array ends exactly where it begins
-// (1238 + 12 = 1250) and `WATCHED_FACTION_INDEX`, itself chain-locked to the tested COINAGE, sits
-// exactly one past its end (1260 + 1 = 1261). Eleven fields is precisely the size of that gap.
-//
-// **Every one of them is PRIVATE** — the server sends them only on our OWN descriptor — and that
-// is the mechanical reason the character window's Honor tab works for the local player and for
-// nobody else. A foreign player's honor stats are not on the wire at all until we ask for them
-// with `MSG_INSPECT_HONOR_STATS` ([`crate::messages::InspectHonorStats`]); the sole honor value
-// that *does* stream for every visible player is the current rank in the PUBLIC
-// `PLAYER_BYTES_3`(195) byte 3 above.
-//
-// Types, in run order — `+0x426..0x429` TWO_SHORT, `+0x42A..0x42F` INT, `+0x430` BYTES:
-//
-// The four kill counters are TWO_SHORT, `(honorable, dishonorable)` in the low/high halves. Only
-// SESSION_KILLS is genuinely written as two halves (vmangos `HonorMgr.cpp:913-914`,
-// `SetUInt16Value(…, 0, todayHK)` / `(…, 1, todayDK)`); the other three go out as a whole dword
-// (`SetUInt32Value(PLAYER_FIELD_YESTERDAY_KILLS, yesterdayKills)`, `HonorMgr.cpp:917/924/929`), so
-// their high half is always 0 from this server. The descriptor type is TWO_SHORT regardless and
-// the real client reads halves, so we decode halves — see the accessors in `player.rs`.
-//
-// The six INT fields are the three honor-point "contribution" totals, the two lifetime kill
-// counts, and LAST_WEEK_RANK — which is the weekly **standing** (our ladder position), not a rank.
-// All six are `SetUInt32Value` writes from `HonorMgr::Update` (`HonorMgr.cpp:917-935`). Our two
-// lifetime names fix vmangos's own typo: the header spells them
-// `PLAYER_FIELD_LIFETIME_HONORBALE_KILLS` / `…DISHONORBALE…`.
-//
-// BYTES2's byte 0 is `HONOR_RANK_BAR` (`PLAYER_FIELD_BYTES_2_OFFSET_HONOR_RANK_BAR`, vmangos
-// `Player.h:366-372`); its bytes 1..3 are a flags byte and two unknowns this server never writes.
+// The honor block (`UpdateFields_1_12_1.h:288-298`) is private: another player's honor needs
+// `MSG_INSPECT_HONOR_STATS`. The four kill counters are TWO_SHORT (honorable, dishonorable), but
+// vmangos writes all except SESSION_KILLS as a whole dword. LAST_WEEK_RANK is the weekly standing,
+// not a rank. BYTES2 byte 0 is the rank bar (`Player.h:366-372`).
 const FIELD_PLAYER_FIELD_SESSION_KILLS: u16 = 1250;
 const FIELD_PLAYER_FIELD_YESTERDAY_KILLS: u16 = 1251;
 const FIELD_PLAYER_FIELD_LAST_WEEK_KILLS: u16 = 1252;
@@ -569,67 +303,27 @@ const FIELD_PLAYER_FIELD_LAST_WEEK_CONTRIBUTION: u16 = 1258;
 const FIELD_PLAYER_FIELD_LAST_WEEK_RANK: u16 = 1259;
 const FIELD_PLAYER_FIELD_BYTES2: u16 = 1260;
 
-/// The number of `PLAYER_SKILL_INFO` slots the descriptor reserves (384 fields ÷ 3 per slot;
-/// vmangos `UpdateFields_1_12_1.h`). vmangos itself only ever *populates* `PLAYER_MAX_SKILLS` (127,
-/// `Player.h:69`) of these — the last reserved slot is never written; `player_skill` honors the
-/// full wire capacity so an out-of-range read is a real bug, not a silently-narrowed one.
+/// `PLAYER_SKILL_INFO` slots on the wire, 3 fields each; vmangos fills only 127 (`Player.h:69`).
 pub const PLAYER_SKILL_SLOTS: u8 = 128;
 
-/// One decoded `PLAYER_SKILL_INFO` slot (VERIFIED packing vmangos `Player.cpp:90-99`
-/// `PLAYER_SKILL_INDEX`/`_VALUE_INDEX`/`_BONUS_INDEX` + the `MAKE_PAIR32`/`PAIR32_LOPART`/`_HIPART`
-/// macros, `shared/Common.h:119-121`, and `Player::SetSkill`, `Player.cpp:5664-5677`): three
-/// consecutive dwords per slot — `(id | step<<16)`, `(value | max<<16)`,
-/// `(tempBonus | permBonus<<16)`, with the bonus halves **signed** (`SKILL_TEMP_BONUS`/
-/// `SKILL_PERM_BONUS` cast to `int16` — a malus reads negative).
+/// One `PLAYER_SKILL_INFO` slot, three dwords (`Player.cpp:90-99`): `id | step << 16`,
+/// `value | max << 16`, `temp_bonus | perm_bonus << 16` with signed bonuses.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct PlayerSkillSlot {
-    /// The `SkillLine.dbc` id (`0` = an unused slot).
+    /// A `SkillLine.dbc` id, 0 for an unused slot.
     pub skill_id: u16,
-    /// The skill-tier step (`Player::SetSkill`'s `step` — 0 unless a tier-raising effect is live).
+    /// The tier step, 0 unless a tier-raising effect is live.
     pub step: u16,
-    /// Current skill value.
     pub value: u16,
-    /// Max skill value (the level/tier cap).
     pub max: u16,
-    /// Temporary bonus (auras/consumables/enchants); signed — a malus reads negative.
+    /// From auras, consumables and enchants; a malus is negative.
     pub temp_bonus: i16,
-    /// Permanent bonus (talents); signed.
+    /// From talents.
     pub perm_bonus: i16,
 }
 
-/// A sparse update-field set: a bitmask of `u32` blocks followed by one `u32` per set bit. We keep
-/// the wire's own mask plus a dense value array — not a map — because the ECS-side pollers
-/// (animation, equipment, plates) probe thousands of fields **per frame**, so a read must be two
-/// array indexings, never a tree walk (decision 1457); the wire's `u8` block count bounds the
-/// arrays at 8160 dwords, and a Unit's real footprint is ~800 B. We expose **named** accessors for
-/// the descriptor fields consumers read — the raw `get_*(index)` reads stay module-private, so
-/// field-index knowledge (a wire fact) never leaves this crate (decision 0061). The ECS mirrors
-/// one of these per object and [`Self::merge`]s each `Values` delta into it; the codec itself
-/// stays stateless (decision 0006).
-///
-/// **Absent-field semantics** hinge on `Self::descriptor_end`: a CREATE block is a *complete*
-/// snapshot — the server masks in only non-zero fields (vmangos `Object::_SetCreateBits`: bit set
-/// iff `value != 0`), and the real client reads it into a zero-initialized descriptor buffer — so
-/// on a create-seeded store an absent field reads `Some(0)`, the truth. A bare `Values` delta
-/// carries only *changed* fields; there an absent field means "not touched", so it reads `None`
-/// (and a merge must not clobber it). Director-caught: an item at durability 0 streams its create
-/// with `MAXDURABILITY` but no `DURABILITY` word, and the sparse `None` sent the tooltip to the
-/// template's max/max — 100% on fully broken gear.
-///
-/// **…but only within the object's OWN descriptor** (decision 1081). "Absent = 0" is a statement
-/// about the *zero-initialized buffer*, and that buffer is exactly [`descriptor_len`] dwords long
-/// for this object's type. A creature has no PLAYER block at all, so a PLAYER-block index read off
-/// one is not an absent field — it is a question the object cannot answer, and the honest reply is
-/// `None`. Conflating the two made every `player_*` accessor answer a confident `0` for any
-/// created creature, which is how the pet sheet's damage multiplier came out `0` instead of the
-/// unstreamed default `1.0` and the tooltip read `inf - inf` / `nan` (director, 2026-08-07).
-/// A corpse's body appearance — the seven `CORPSE_FIELD_BYTES_1`/`_2` bytes the reference's dress
-/// `0x5d6260` loads into the corpse's own `CCharacterComponent` (`+0x69..+0x6f`), which are the same
-/// seven selectors a living player's body is composited from. Read via
-/// [`ObjectFields::corpse_look`].
-///
-/// This is the corpse's OWN snapshot, taken at death: it is not the owner's live `PLAYER_BYTES`,
-/// and it survives the owner logging out or being nowhere near.
+/// A corpse's own appearance, snapshotted at death: the seven `CORPSE_FIELD_BYTES_1`/`_2` bytes
+/// the client's dress `0x5d6260` loads, not the owner's live `PLAYER_BYTES`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct CorpseLook {
     pub race: u8,
@@ -641,29 +335,22 @@ pub struct CorpseLook {
     pub facial_hair: u8,
 }
 
+/// A sparse update-field set: the wire's block mask and a dense value array. A CREATE carries only
+/// nonzero fields (`Object::_SetCreateBits`) into the client's zeroed buffer, so an absent field
+/// within the created type's descriptor reads `Some(0)`; in a `Values` delta, or past the
+/// descriptor's end, it reads `None`.
 #[derive(Debug, Clone, Default)]
 pub struct ObjectFields {
-    /// Presence bitmask, one bit per field index (`index = word * 32 + bit`) — the wire's block
-    /// mask, kept verbatim.
+    /// The wire's block mask, verbatim (`index = word * 32 + bit`).
     present: Vec<u32>,
-    /// Dense value array, invariant `values.len() == present.len() * 32`; a slot is meaningful
-    /// iff its `present` bit is set (unset slots hold `0` but must be read through the mask —
-    /// absent-vs-zero is exactly the distinction the struct doc is about).
+    /// Always `present.len() * 32` long; an unset slot holds 0 but must be read through the mask.
     values: Vec<u32>,
-    /// How long this object's descriptor is, in dwords — [`descriptor_len`] of the CREATE block's
-    /// own `ObjectType` (set by the parser via [`Self::into_created`]). Every index **below** it is
-    /// known: absent = `0`. `0` marks a bare `Values` delta (or a hand-built fixture), where no
-    /// index is known and absent = `None`.
+    /// The created type's [`descriptor_len`], below which absent reads 0; 0 for a delta or fixture.
     descriptor_end: u16,
 }
 
-/// The length of an object's descriptor buffer, in dwords — the `*_END` of the innermost block its
-/// `ObjectType` names (vmangos `UpdateFields_1_12_1.h`, build 5875, **by enum arithmetic**: the
-/// trailing comments in that header's CONTAINER and PLAYER blocks are stale by a constant and are
-/// not the numbers here).
-///
-/// The type hierarchy is inclusive — a Player's buffer spans OBJECT+UNIT+PLAYER, a Container's
-/// OBJECT+ITEM+CONTAINER — so each entry is the outermost end, not a block size.
+/// An object's descriptor length in dwords: the `*_END` of its innermost block, so a Player spans
+/// OBJECT, UNIT and PLAYER.
 fn descriptor_len(object_type: ObjectType) -> u16 {
     match object_type {
         ObjectType::Object => 6,         // OBJECT_END = 0x6
@@ -677,8 +364,7 @@ fn descriptor_len(object_type: ObjectType) -> u16 {
     }
 }
 
-/// The widest descriptor's mask-word count: `PLAYER_END` 1282 fields (the [`descriptor_len`]
-/// table) is 41 words of 32 bits. A block count past it describes no 1.12 object.
+/// Mask words of the widest descriptor, `PLAYER_END`; no 1.12 object needs more.
 const MAX_MASK_WORDS: usize = 1282usize.div_ceil(32);
 
 impl ObjectFields {
@@ -703,19 +389,13 @@ impl ObjectFields {
         })
     }
 
-    /// Mark this set as a CREATE snapshot of `object_type` (see the struct doc's absent-field
-    /// semantics) — the parser calls it on a create block's mask with the type off the same block's
-    /// header; a `Values` delta never gets it. The type is what bounds "absent = 0" to the
-    /// object's own descriptor.
+    /// Marks a CREATE snapshot of `object_type`, so absent fields in its descriptor read 0.
     pub fn into_created(mut self, object_type: ObjectType) -> Self {
         self.descriptor_end = descriptor_len(object_type);
         self
     }
 
-    /// Build a field set directly from `(index, value)` pairs — the fixture constructor (unit
-    /// tests, the capture harness's synthetic self-player, probes). The wire path is
-    /// [`Self::read`]; live code never builds fields by hand. Chain [`Self::into_created`] when
-    /// the fixture stands in for a create snapshot.
+    /// A fixture from `(index, value)` pairs; [`Self::into_created`] makes it a create.
     pub fn from_pairs(pairs: &[(u16, u32)]) -> Self {
         let mut this = Self::default();
         for &(index, value) in pairs {
@@ -724,72 +404,40 @@ impl ObjectFields {
         this
     }
 
-    /// A 2-field guid: `lo | hi << 32`, present iff the low half is (the wire always sends guid
-    /// halves together; an absent slot reads `None`, a sent-empty slot reads `Some(0)`).
-    /// `CORPSE_FIELD_OWNER` (field 6, `OBJECT_END + 0x0`, a 2-field guid — VERIFIED vmangos
-    /// `UpdateFields_1_12_1.h:339`): the dead player this corpse belongs to. Only meaningful on a
-    /// TYPEID_CORPSE (7) object; the net bridge uses it to recognize OUR corpse for the reclaim
-    /// send (decision 0308 §5). `None`/0 when absent.
+    /// `CORPSE_FIELD_OWNER` (`UpdateFields_1_12_1.h:339`): the dead player, only on a corpse.
     pub fn corpse_owner(&self) -> Option<u64> {
         self.get_guid(6).filter(|&g| g != 0)
     }
 
-    /// `CORPSE_FIELD_DISPLAY_ID` (field 12, `OBJECT_END + 0x6`): the dead player's body model, as a
-    /// **`CreatureDisplayInfo` id** — vmangos writes the owner's `GetNativeDisplayId()` straight in
-    /// (`Player::CreateCorpse`, `Player.cpp:4809`), so it resolves down the very same
-    /// displayId → CreatureDisplayInfo → CreatureModelData chain a player's living body does
-    /// (decision 0041). The reference reads exactly this field for the model: `0x5d6700`'s
-    /// not-bones leg is `[[corpse+0x110]+0x18]` → `[0xc0de90]` (CreatureDisplayInfo) → `[row+4]`
-    /// → `[0xc0de68]` (CreatureModelData) → `[row+8]` = the path.
-    ///
-    /// **Only meaningful while [`Self::corpse_is_bones`] is false.** A bone pile carries the field
-    /// (the server's corpse→bones conversion copies fields 3.. verbatim, vmangos `Map.cpp:3638`)
-    /// and the client ignores it: `0x5d6700` branches on the BONES bit *first* and builds the
-    /// skeleton path from race/sex instead.
+    /// The body's `CreatureDisplayInfo` id, the owner's native display (`Player.cpp:4809`). A bone
+    /// pile keeps it, but `0x5d6700` ignores it there and builds the skeleton from race and sex.
     pub fn corpse_display_id(&self) -> Option<u32> {
         self.get_u32(12).filter(|&d| d != 0)
     }
 
-    /// One `CORPSE_FIELD_ITEM` slot (fields 13..31, `OBJECT_END + 0x7 + slot`, `slot` = the
-    /// **equipment slot** 0..18): the worn piece as `(ItemDisplayInfo id, InventoryType)` — the
-    /// server packs `DisplayInfoID | (InventoryType << 24)` (`Player::CreateCorpse`,
-    /// `Player.cpp:4821`), and the client unpacks the same way (`0x5d6423 and eax,0xffffff`
-    /// before the `[0xc0dc10]` ItemDisplayInfo index). `None` for an empty slot.
-    ///
-    /// Note this is a **display id, already resolved** — unlike `PLAYER_VISIBLE_ITEM`, which
-    /// carries item *entries* and needs a template round trip. A corpse dresses off the wire alone.
+    /// The piece in equipment slot `slot` (0..18) as `(ItemDisplayInfo id, InventoryType)`, packed
+    /// `display | type << 24` (`Player.cpp:4821`); unlike `PLAYER_VISIBLE_ITEM`, not an item entry.
     pub fn corpse_item(&self, slot: u8) -> Option<(u32, u8)> {
         let raw = self.get_u32(13 + u16::from(slot))?;
         let display = raw & 0x00ff_ffff;
         (display != 0).then_some((display, (raw >> 24) as u8))
     }
 
-    /// `CORPSE_FIELD_GUILD` (field 34, `OBJECT_END + 0x1C`) — the dead player's guild id,
-    /// snapshotted at death (vmangos `Player::CreateCorpse` writes `GetGuildId()`). The reference
-    /// reads exactly this word at `0x5d6edf` (`[[corpse+0x110]+0x70]`) and hands it, with
-    /// `CORPSE_FIELD_OWNER`, to the guild-name-cache lookup `0x6d6d20` that feeds the corpse's
-    /// **tabard emblem** install `0x5d6ec0` (wow-re `corpse-decal-and-loot-sparkle.md` §6b). A
-    /// corpse therefore wears its owner's crest exactly as the living body did. `0` = guildless.
+    /// The owner's guild id at death, 0 for none; the client builds the corpse's tabard crest from
+    /// it (`0x5d6ec0`).
     pub fn corpse_guild(&self) -> u32 {
         self.get_u32(34).unwrap_or(0)
     }
 
-    /// `CORPSE_FIELD_BYTES_1` (field 32, `OBJECT_END + 0x1A`) — byte 1 **race**, byte 2 **gender**,
-    /// byte 3 **skinColor** (byte 0 is unused; vmangos writes `(0) | (race<<8) | (gender<<16) |
-    /// (skin<<24)`, `Corpse.cpp:228`). The reference reads them one byte at a time off the same
-    /// word — `[[corpse+0x110]+0x69/+0x6a/+0x6b]` in the dress `0x5d6260`.
+    /// Race, gender and skin in bytes 1..3; byte 0 is unused (`Corpse.cpp:228`).
     fn corpse_bytes_1(&self) -> Option<u32> {
         self.get_u32(32)
     }
-    /// `CORPSE_FIELD_BYTES_2` (field 33, `OBJECT_END + 0x1B`) — byte 0 **face**, byte 1
-    /// **hairStyle**, byte 2 **hairColor**, byte 3 **facialHair** (`Corpse.cpp:229`; the reference's
-    /// `+0x6c..+0x6f`).
+    /// Face, hair style, hair colour and facial hair (`Corpse.cpp:229`).
     fn corpse_bytes_2(&self) -> Option<u32> {
         self.get_u32(33)
     }
-    /// The corpse's body appearance — `(race, sex, skin, face, hairStyle, hairColor, facialHair)`,
-    /// the seven bytes `0x5d6260` loads into the corpse's own `CCharacterComponent`. `None` when
-    /// neither BYTES word is known (a bare `Values` delta).
+    /// The corpse's appearance, `None` in a delta that lacks either BYTES word.
     pub fn corpse_look(&self) -> Option<CorpseLook> {
         let (b1, b2) = (self.corpse_bytes_1()?, self.corpse_bytes_2()?);
         Some(CorpseLook {
@@ -803,99 +451,59 @@ impl ObjectFields {
         })
     }
 
-    /// `CORPSE_FIELD_FLAGS` (field 35, `OBJECT_END + 0x1D`) — the corpse's own flag word, read by
-    /// the reference as `[[corpse+0x110]+0x74]`. `0` when absent.
+    /// `CORPSE_FIELD_FLAGS`, 0 when absent (client `[[corpse+0x110]+0x74]`).
     pub fn corpse_flags(&self) -> u32 {
         self.get_u32(35).unwrap_or(0)
     }
-    /// [`Self::corpse_flags`] **preserving absence** — `None` when this snapshot does not carry
-    /// field 35 at all.
-    ///
-    /// The two are not interchangeable, and the difference is the create-vs-delta seam: a values
-    /// delta carries only what changed, so an untouched `FLAGS` reads absent, and `unwrap_or(0)`
-    /// would report every bit *clear* — turning "nothing was said about the flags" into a positive
-    /// claim that the corpse is not bones. Readers acting on a **change** must use this one.
+    /// [`Self::corpse_flags`] keeping absence: untouched flags in a delta are `None`, not all
+    /// clear. A reader acting on a change must use this one.
     pub fn corpse_flags_present(&self) -> Option<u32> {
         self.get_u32(35)
     }
-    /// `CORPSE_FLAG_BONES` (`0x01`) — this object is a **bone pile**, not a fresh body. It is the
-    /// first thing `0x5d6260` tests (`0x5d6287 test byte [eax+0x74],0x1; jne`): a bone pile builds
-    /// **no** character component at all, wears nothing, and takes its model from race/sex rather
-    /// than from [`Self::corpse_display_id`] (`0x5d6700`). Named in vmangos `Corpse.h:45`; set on
-    /// the converted object at `Map.cpp:3644`.
+    /// `CORPSE_FLAG_BONES`: a bone pile, which `0x5d6260` tests first; it wears nothing and takes
+    /// its model from race and sex.
     pub fn corpse_is_bones(&self) -> bool {
         self.corpse_flags() & 0x01 != 0
     }
-    /// `CORPSE_FLAG_HIDE_HELM` (`0x08`) — the owner's helm preference, snapshotted at death
-    /// (vmangos copies `PLAYER_FLAGS_HIDE_HELM` in, `Player.cpp:4801`). The corpse honours it by
-    /// **never installing equipment slot 0** (`0x5d6465 test byte [edx+0x74],0x8` → the skip),
-    /// which is its own bit on its own field — *not* `PLAYER_FLAGS`, and the opposite instruction
-    /// polarity to the player lane (wow-re `helm-cloak-hide.md` §2b).
+    /// `CORPSE_FLAG_HIDE_HELM`, the owner's setting at death; the client skips slot 0 (`0x5d6465`).
     pub fn corpse_hides_helm(&self) -> bool {
         self.corpse_flags() & 0x08 != 0
     }
-    /// `CORPSE_FLAG_HIDE_CLOAK` (`0x10`) — the same, for equipment slot 14 (`0x5d6470`).
+    /// `CORPSE_FLAG_HIDE_CLOAK`: the same for slot 14 (`0x5d6470`).
     pub fn corpse_hides_cloak(&self) -> bool {
         self.corpse_flags() & 0x10 != 0
     }
 
-    /// `CORPSE_FIELD_DYNAMIC_FLAGS` (field 36, `OBJECT_END + 0x1E`) bit 0 — this bone pile carries
-    /// **lootable insignia** (`CORPSE_DYNFLAG_LOOTABLE`, vmangos `Map.cpp:3660`). The reference's
-    /// `0x5d6e20` is literally `return *(+0x110)+0x78 & 1`, and it gates both the corpse highlight
-    /// emitter (`0x5d6e30`/`0x5d6e80`, armed at build and re-armed by the field's own mirror
-    /// handler) and the `CMSG_LOOT` route off the corpse's interact slot (wow-re
-    /// `loot-anim-leg.md`).
+    /// `CORPSE_DYNFLAG_LOOTABLE` (`Map.cpp:3660`): the bone pile has insignia; `0x5d6e20` gates the
+    /// loot highlight and the `CMSG_LOOT` click on it.
     pub fn corpse_lootable(&self) -> bool {
         self.get_u32(FIELD_CORPSE_DYNAMIC_FLAGS).unwrap_or(0) & 0x01 != 0
     }
 
-    /// `CORPSE_FLAG_LOOTABLE` (`0x20`, [`Self::corpse_flags`] bit 5) — the flag that makes a body's
-    /// **battleground insignia** takeable. It gates the second leg of the corpse cursor classifier
-    /// `0x482740` (`[[corpse+0x110]+0x74] >> 5 & 1`), and the corpse right-click `0x5d6bf0` reads
-    /// it again at `0x5d6c9c` for the matching send.
-    ///
-    /// **Neither of `w2a.md`'s two labels for this bit was right**, and it took a §5 round to say
-    /// so (wow-re `corpse-click-and-reclaim.md`; decision 1729). "Reclaimable" (its line 264) is
-    /// wrong outright — nothing in the reclaim path consults it, and `RetrieveCorpse` reads no
-    /// corpse flag at all. "PvP flag" (its line 618) names the wrong bit: the corpse's actual PvP
-    /// flag is **bit 2**, read by `UnitIsPVP 0x516460` at `0x5164e6` (`shr eax,2; and al,1`), and
-    /// it is the only corpse flag this client exposes to Lua.
-    ///
-    /// What bit 5 actually unlocks is spell **22027 "Remove Insignia"** — the sole row in the
-    /// shipped `Spell.dbc` with `Effect[0] == 116`, targeting `TARGET_FLAG_PVP_CORPSE`, absent
-    /// from the base `dbc.MPQ` and added with Battlegrounds. The "skin a player" reading came from
-    /// the cursor **art** names (`SkinAlliance`/`SkinHorde`) and from nowhere else; there is no
-    /// skinning of players in 1.12.1.
+    /// `CORPSE_FLAG_LOOTABLE`: the battleground insignia is takeable, by spell 22027 "Remove
+    /// Insignia". The cursor `0x482740` and right-click `0x5d6bf0` test it; the corpse's PvP flag
+    /// is bit 2 (`UnitIsPVP`, `0x516460`).
     pub fn corpse_pvp_insignia(&self) -> bool {
         self.corpse_flags() & 0x20 != 0
     }
 
-    /// `DYNAMICOBJECT_CASTER` (fields 6–7, `OBJECT_END + 0x0`, a 2-field guid — vmangos
-    /// `UpdateFields_1_12_1.h:325`): the unit whose ground cast anchored this object.
-    /// Index-twin of [`Self::corpse_owner`] — each TYPEID reuses `OBJECT_END`; the TypeId (or
-    /// [`Self::dynamicobject_spell_id`]'s presence) decides which name applies.
+    /// The ground caster (`UpdateFields_1_12_1.h:325`), at the same index as a corpse's owner.
     pub fn dynamicobject_caster(&self) -> Option<u64> {
         self.get_guid(6).filter(|&g| g != 0)
     }
-    /// `DYNAMICOBJECT_BYTES` (field 8): the dynobj type byte — vmangos sends `1` (area spell)
-    /// for every persistent-area cast (`DynamicObject::Create`; captured live 2026-07-30 for
-    /// Blizzard 10 and Flamestrike 2120).
+    /// The type byte; vmangos sends 1 (area spell) for every persistent-area cast.
     pub fn dynamicobject_bytes(&self) -> Option<u32> {
         self.get_u32(8)
     }
-    /// `DYNAMICOBJECT_SPELLID` (field 9): the anchoring spell — the root of the dest-anchored
-    /// visual chain (B132 follow-up). `None`/0 when absent.
+    /// The anchoring spell, the root of the ground-targeted visual chain.
     pub fn dynamicobject_spell_id(&self) -> Option<u32> {
         self.get_u32(9).filter(|&s| s != 0)
     }
-    /// `DYNAMICOBJECT_RADIUS` (field 10): the area's radius in yards (live: Blizzard 8.0,
-    /// Flamestrike 5.0 — the server's `SpellRadius.dbc` resolve).
+    /// The area's radius in yards, which the server resolves from `SpellRadius.dbc`.
     pub fn dynamicobject_radius(&self) -> Option<f32> {
         self.get_f32(10)
     }
-    /// `DYNAMICOBJECT_POS_X/Y/Z` + `FACING` (fields 11–14): the anchored point in raw WoW
-    /// coords. Duplicates the create's movement-block position on the vmangos wire (both
-    /// captured identical live); the accessor exists for `Values`-delta reads and tests.
+    /// The anchored point and facing in raw WoW coordinates, equal to the create's position.
     pub fn dynamicobject_position(&self) -> Option<([f32; 3], f32)> {
         Some((
             [self.get_f32(11)?, self.get_f32(12)?, self.get_f32(13)?],
@@ -903,24 +511,20 @@ impl ObjectFields {
         ))
     }
 
-    /// Whether the wire genuinely carried this field (mask bit set) — the raw presence probe
-    /// under every accessor, bypassing the created-store absent-is-zero fold.
+    /// Whether the mask carries the field, ignoring the created store's absent-is-zero.
     fn contains(&self, index: u16) -> bool {
         self.present
             .get(usize::from(index / 32))
             .is_some_and(|w| w & (1u32 << (index % 32)) != 0)
     }
 
-    /// The carried value, `None` when the mask bit is unset — [`Self::contains`]'s value twin.
     fn get_raw(&self, index: u16) -> Option<u32> {
         self.contains(index)
             .then(|| self.values[usize::from(index)])
     }
 
     fn insert(&mut self, index: u16, value: u32) {
-        // `index` is a `u16`, so `word` is at most 2047 and the store at most 64 Ki values —
-        // bounded by the type, not by anything the wire says (the wire's block count above is
-        // a `u8`, 255 words at the very most).
+        // A `u16` index bounds the store at 64 Ki values, whatever the wire says.
         let word = usize::from(index / 32);
         if word >= self.present.len() {
             self.present.resize(word + 1, 0);
@@ -931,9 +535,7 @@ impl ObjectFields {
     }
 
     fn get_guid(&self, index: u16) -> Option<u64> {
-        // Raw read on purpose: a guid slot stays "present iff the low half is" even on a
-        // created store — every consumer already treats a sent-empty `Some(0)` as no-guid, so the
-        // absent-is-zero fallback would only blur the two identical cases.
+        // Raw on purpose: a guid is present iff its low half is, even on a created store.
         let lo = self.get_raw(index)?;
         let hi = self.get_u32(index + 1).unwrap_or(0);
         Some(u64::from(lo) | (u64::from(hi) << 32))
@@ -949,14 +551,12 @@ impl ObjectFields {
     fn get_i32(&self, index: u16) -> Option<i32> {
         self.get_u32(index).map(|v| v as i32)
     }
-    /// Split a `u32` field into its low/high 16-bit halves — a `TWO_SHORT`/`PAIR32` field
-    /// (`MAKE_PAIR32`/`PAIR32_LOPART`/`_HIPART`, vmangos `shared/Common.h:119-121`).
+    /// A `TWO_SHORT` field as its (low, high) halves (vmangos `shared/Common.h:119-121`).
     fn get_u16_pair(&self, index: u16) -> Option<(u16, u16)> {
         self.get_u32(index).map(|v| (v as u16, (v >> 16) as u16))
     }
 
-    /// One slot's nibble out of a 8-slots-per-`u32` array (`UNIT_FIELD_AURAFLAGS`). An absent word
-    /// reads `0`, matching the client's zero-initialized descriptor array.
+    /// One slot's `UNIT_FIELD_AURAFLAGS` nibble; an absent word reads 0, as in the client.
     fn get_aura_nibble(&self, slot: u8) -> u8 {
         let word = self
             .get_u32(FIELD_UNIT_AURAFLAGS + u16::from(slot >> 3))
@@ -964,37 +564,22 @@ impl ObjectFields {
         ((word >> ((slot & 7) * 4)) & 0x0F) as u8
     }
 
-    /// One slot's byte out of a 4-slots-per-`u32` array (`UNIT_FIELD_AURALEVELS`,
-    /// `UNIT_FIELD_AURAAPPLICATIONS`). An absent word reads `0`, as above.
+    /// One slot's byte of `UNIT_FIELD_AURALEVELS` or `UNIT_FIELD_AURAAPPLICATIONS`; an absent word
+    /// reads 0.
     fn get_aura_byte(&self, base: u16, slot: u8) -> u8 {
         let word = self.get_u32(base + u16::from(slot >> 2)).unwrap_or(0);
         (word >> ((slot & 3) * 8)) as u8
     }
 
-    /// Fold an update into this store. A `Values` delta overlays: every field it carries replaces
-    /// ours (WoW only resends *changed* fields, and a field going to `0` is an explicit `0`, never
-    /// a removal), so the ECS accumulates the object's full descriptor set across packets
-    /// (decision 0061). A re-CREATE snapshot *replaces* instead: it is the complete descriptor
-    /// (absent = 0), and overlaying it would keep stale non-zero values for every field that
-    /// dropped to zero since the last stream (an aura that expired out of view, durability that
-    /// broke) — exactly the absent-vs-zero bug the `created` flag exists to kill.
+    /// Folds in an update: a `Values` delta overlays, since a field going to 0 is sent as 0; a
+    /// re-CREATE replaces, as overlaying it would keep fields that have since dropped to 0.
     pub fn merge(&mut self, delta: ObjectFields) {
         self.merge_diff(delta, |_, _, _| {});
     }
 
-    /// [`Self::merge`] that also reports every dword the fold MOVED — the reference's
-    /// `CMirrorHandler` notify pass (`0x465330`: memcmp live-vs-shadow over each registered span,
-    /// fire only on a difference, the callback handed the OLD value — wow-re `object-layer.md`),
-    /// done in the one write that already holds both sides (decision 2297).
-    ///
-    /// `changed(index, old, new)` runs once per moved index, ascending, and only for a real
-    /// difference: a field re-sent with the value it already had reports nothing, exactly as the
-    /// reference's memcmp fires nothing. `old` reads an absent field as `0`, the reference's
-    /// zero-initialised array. A re-CREATE snapshot reports every index the replace moved, on
-    /// either side's mask — the reference's in-place refresh of an already-live guid goes down
-    /// its values-only path and notifies too — while a FIRST create is never merged at all (the
-    /// caller seeds the store with it), which is where the reference's create-time
-    /// notify-suppress flag lives here.
+    /// [`Self::merge`], calling `changed(index, old, new)` once per changed dword in ascending
+    /// order, as the client's `CMirrorHandler` pass does (`0x465330`): a resend of the same value
+    /// reports nothing, and an absent old value reads 0. A first create is seeded, never merged.
     pub fn merge_diff(&mut self, delta: ObjectFields, mut changed: impl FnMut(u16, u32, u32)) {
         if delta.descriptor_end != 0 {
             let words = self.present.len().max(delta.present.len());
@@ -1030,12 +615,8 @@ impl ObjectFields {
         }
     }
 
-    /// The object class this descriptor was CREATED as, read back off its own length ([`descriptor_len`]
-    /// is injective over the eight classes) — `None` for a bare `Values` delta or a hand-built
-    /// fixture that never went through [`Self::into_created`]. Distinct from
-    /// [`Self::object_type`], the typemask read, which cannot tell a corpse from an item: a field
-    /// edge carries THIS because a raw index means different things per class (`36`: a unit's
-    /// `BYTES_0`, a corpse's `DYNAMIC_FLAGS`).
+    /// The type this was created as, from its descriptor length (the eight lengths are distinct).
+    /// Unlike [`Self::object_type`] it tells a corpse from an item, as index 36 needs.
     pub fn created_as(&self) -> Option<ObjectType> {
         const ALL: [ObjectType; 8] = [
             ObjectType::Object,
@@ -1055,12 +636,11 @@ impl ObjectFields {
             .flatten()
     }
 
-    /// Whether this carried no fields — the codec skips emitting an empty `Values` delta.
+    /// No fields carried; the codec skips an empty `Values` delta.
     pub fn is_empty(&self) -> bool {
         self.present.iter().all(|&w| w == 0)
     }
-    /// Every present `(index, value)` pair in ascending index order — the debug/probe affordance
-    /// for descriptor archaeology (named accessors stay the consumer surface; decision 0061).
+    /// Every carried `(index, value)` pair in ascending order, for debugging and probes.
     pub fn raw_fields(&self) -> impl Iterator<Item = (u16, u32)> + '_ {
         self.present.iter().enumerate().flat_map(move |(word, &w)| {
             (0..32u16)
diff --git a/crates/benilla-protocol/src/messages/update_object/fields/player.rs b/crates/benilla-protocol/src/messages/update_object/fields/player.rs
index 73e10a8c..c2c47173 100644
--- a/crates/benilla-protocol/src/messages/update_object/fields/player.rs
+++ b/crates/benilla-protocol/src/messages/update_object/fields/player.rs
@@ -1,125 +1,77 @@
-//! The item/container/PLAYER named accessors over [`ObjectFields`] — inventory and equipment
-//! slots, purse/XP, the quest log, skills, buyback, reputation-adjacent player bytes. Split from
-//! the one descriptor map (`mod.rs` holds the indices + codec).
+//! Named accessors over [`ObjectFields`] for the item, container, player and GameObject blocks.
 
 use super::*;
 
 impl ObjectFields {
-    /// `OBJECT_FIELD_ENTRY` (3) — the object's template entry (an item object's item id, a
-    /// GameObject's template, a creature's `creature_template` row). The one field that names WHAT
-    /// a streamed object is.
-    ///
-    /// **For a PET this is the only route to its template**, and that is load-bearing: a
-    /// `HIGHGUID_PET` guid carries a *pet number* in the slot a creature's entry occupies
-    /// ([`crate::guid::pet_number`]), so [`crate::guid::entry`] refuses it — but vmangos still
-    /// writes the real `cinfo->entry` here (`Creature::InitEntry`, `Creature.cpp:376`,
-    /// `SetEntry(entry) // normal entry always`). Decision 1062's creature-family lookup goes
-    /// through this field for exactly that reason.
+    /// `OBJECT_FIELD_ENTRY` (3): the template entry. The only route to a pet's template: its guid
+    /// holds a pet number instead, but vmangos writes the entry here (`Creature.cpp:376`).
     pub fn object_entry(&self) -> Option<u32> {
         self.get_u32(3)
     }
-    /// `ITEM_FIELD_STACK_COUNT` — an item object's stack size.
+    /// `ITEM_FIELD_STACK_COUNT`: an item object's stack size.
     pub fn item_stack_count(&self) -> Option<u32> {
         self.get_u32(FIELD_ITEM_STACK_COUNT)
     }
-    /// `ITEM_FIELD_SPELL_CHARGES + i` — this *instance*'s remaining charges for its `i`th spell
-    /// block (`i < 5`), signed: negative = a consumable-on-empty counter, `0` = spent. Distinct
-    /// from the TEMPLATE's `ItemSpellEntry::charges`, which says how many a fresh copy carries.
-    /// Field 16 = `FIELD_ITEM_STACK_COUNT`(14) + DURATION(15) + 1 — the chain between the tested
-    /// STACK_COUNT and FLAGS(21) anchors, and the client's own `[item+0x114]+0x28` (wow-re
-    /// `action-item-slot.md` §8.2, the mode-`0x20` search filter that reads exactly this).
+    /// `ITEM_FIELD_SPELL_CHARGES + i` (field `16 + i`, the client's `[item+0x114]+0x28`):
+    /// charges left on spell `i`, signed; negative is consumed when empty, 0 is spent.
     pub fn item_spell_charges(&self, i: u8) -> Option<i32> {
         (i < 5)
             .then(|| self.get_u32(FIELD_ITEM_STACK_COUNT + 2 + u16::from(i)))?
             .map(|v| v as i32)
     }
-    /// `ITEM_FIELD_FLAGS` (field 21 — wire index; the client's item-relative index 15 + the 6
-    /// object fields, VERIFIED wow-re inventory-alert-law): bit `0x08` = wrapped (a gift — never
-    /// alerts, never reads broken), bit `0x10` = force-red (status 4 regardless of durability;
-    /// the bit's game meaning is unnamed in the binary, the behavior byte-verified).
+    /// `ITEM_FIELD_FLAGS` (field 21): `0x08` wrapped, never alerts; `0x10` forces red status 4.
     pub fn item_flags(&self) -> Option<u32> {
         self.get_u32(21)
     }
-    /// `ITEM_FIELD_CREATOR` (field 10, guid — vmangos `UpdateFields_1_12_1.h` OBJECT_END+0x4) —
-    /// the item's author/crafter. On a mail-made permanent letter this is the letter's SENDER
-    /// (vmangos `HandleMailCreateTextItem` stamps it) — the reader window's "From," line.
+    /// `ITEM_FIELD_CREATOR` (field 10): crafter, or letter sender (`HandleMailCreateTextItem`).
     pub fn item_creator(&self) -> Option<u64> {
         self.get_guid(10).filter(|&g| g != 0)
     }
-    /// `ITEM_FIELD_ITEM_TEXT_ID` (field 45, OWNER_ONLY — vmangos `UpdateFields_1_12_1.h`
-    /// OBJECT_END+0x27) — the item *instance*'s letter text (a mail-made permanent copy). Nonzero
-    /// = right-click reads it (`CMSG_ITEM_TEXT_QUERY`) instead of using it.
+    /// `ITEM_FIELD_ITEM_TEXT_ID` (field 45, owner only): a mailed letter copy's text; nonzero
+    /// makes a right-click read it (`CMSG_ITEM_TEXT_QUERY`) instead of using the item.
     pub fn item_text_id(&self) -> Option<u32> {
         self.get_u32(45)
     }
-    /// `ITEM_FIELD_ENCHANTMENT + 3*slot` — the enchant id in one of an item OBJECT's **7**
-    /// enchantment slots (`slot < 7`; PERM = 0, TEMP = 1, then the five random-property slots).
-    /// `None` = empty / not sent.
-    ///
-    /// This is the item's own array, and it is the FULL one: vmangos
-    /// `UpdateFields_1_12_1.h` gives `ITEM_FIELD_ENCHANTMENT = OBJECT_END + 0x10, Size: 21,
-    /// PUBLIC` = 7 slots × 3 fields (id, duration, charges — `Item.h:117-119`), so field
-    /// `22 + 3*slot`. Distinct from [`Self::player_visible_item_enchant`], the 2-slot
-    /// (PERM, TEMP) copy broadcast on a *unit's* descriptor for everyone else to render from:
-    /// an item object streams only to its owner, so seven slots are readable for our own gear
-    /// and two for anybody else's.
-    ///
-    /// **Signed**, because the sign is load-bearing at exactly one consumer and nowhere else: the
-    /// tooltip resolves the `SpellItemEnchantment` row from `abs(id)` and uses the sign only to
-    /// paint the line pure-red instead of green (wow-re `tooltip-content-law.md` §E3).
+    /// `ITEM_FIELD_ENCHANTMENT + 3*slot` (field `22 + 3*slot`): the enchant id in one of 7 slots
+    /// (0 permanent, 1 temporary, 2-6 random properties), each an id, duration and charges
+    /// (`Item.h:117-119`). Signed: the tooltip looks up `abs(id)` and paints a negative one red.
     pub fn item_enchant(&self, slot: u8) -> Option<i32> {
         (slot < 7)
             .then(|| self.get_u32(FIELD_ITEM_ENCHANTMENT + 3 * u16::from(slot)))?
             .map(|id| id as i32)
             .filter(|&id| id != 0)
     }
-    /// `ITEM_FIELD_ENCHANTMENT + 3*slot + 2` — that slot's remaining enchant **charges**; `0` =
-    /// none. The tooltip appends `" (N Charges)"` to the slot's line when it is nonzero.
-    ///
-    /// The triple's MIDDLE field (the duration) is deliberately not exposed: the reference's
-    /// tooltip never reads it. A temporary enchant's countdown comes from
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE` instead (`items::Items::enchant_remaining_ms`).
+    /// `ITEM_FIELD_ENCHANTMENT + 3*slot + 2`: charges left, shown as `" (N Charges)"` if nonzero.
+    /// The tooltip skips the duration; a countdown comes from `SMSG_ITEM_ENCHANT_TIME_UPDATE`.
     pub fn item_enchant_charges(&self, slot: u8) -> u32 {
         (slot < 7)
             .then(|| self.get_u32(FIELD_ITEM_ENCHANTMENT + 3 * u16::from(slot) + 2))
             .flatten()
             .unwrap_or(0)
     }
-    /// `ITEM_FIELD_RANDOM_PROPERTIES_ID` (field 44 — vmangos `UpdateFields_1_12_1.h`
-    /// `OBJECT_END + 0x26`, chain-locked here by the tested `ITEM_TEXT_ID` 45 / `DURABILITY` 46
-    /// anchors on either side): the **random-suffix roll** this item instance carries, an
-    /// `ItemRandomProperties.dbc` id. `0` = unrolled.
-    ///
-    /// Its one consumer is the NAME: the client joins the row's suffix through
-    /// `ITEM_SUFFIX_TEMPLATE` in its single name formatter `0x5d8b00`, so the item reads "Chipped
-    /// Claw of the Bear" everywhere it is named. The roll's **enchants** never come from here on
-    /// an owned item — the server writes them into `ITEM_FIELD_ENCHANTMENT` slots 2..6, which
-    /// [`Self::item_enchant`] already reads.
+    /// `ITEM_FIELD_RANDOM_PROPERTIES_ID` (field 44): the `ItemRandomProperties.dbc` suffix, 0 if
+    /// none; only the name uses it (`0x5d8b00`), the roll's enchants fill enchant slots 2-6.
     pub fn item_random_properties_id(&self) -> u32 {
         self.get_u32(44).unwrap_or(0)
     }
-    /// `ITEM_FIELD_DURABILITY` — an item's current durability (field 46: chain-locked between the
-    /// tested STACK_COUNT 14 and CONTAINER_NUM_SLOTS 48 = ITEM_END anchors).
+    /// `ITEM_FIELD_DURABILITY` (field 46): current durability.
     pub fn item_durability(&self) -> Option<u32> {
         self.get_u32(46)
     }
-    /// `ITEM_FIELD_MAXDURABILITY` — the item's durability ceiling (0 = has no durability).
+    /// `ITEM_FIELD_MAXDURABILITY`: the durability ceiling, 0 for an item without durability.
     pub fn item_max_durability(&self) -> Option<u32> {
         self.get_u32(47)
     }
-    /// `CONTAINER_FIELD_NUM_SLOTS` — a bag object's capacity.
+    /// `CONTAINER_FIELD_NUM_SLOTS`: a bag object's capacity.
     pub fn container_num_slots(&self) -> Option<u32> {
         self.get_u32(FIELD_CONTAINER_NUM_SLOTS)
     }
-    /// `CONTAINER_FIELD_SLOT_1 + 2i` — the item guid in a bag's slot `i` (< 36). `Some(0)` = the
-    /// server said "empty"; `None` = the field wasn't sent.
+    /// `CONTAINER_FIELD_SLOT_1 + 2i`: the item guid in bag slot `i`, `Some(0)` when empty.
     pub fn container_slot(&self, i: u8) -> Option<u64> {
         (i < 36).then(|| self.get_guid(FIELD_CONTAINER_SLOT_1 + 2 * u16::from(i)))?
     }
-    /// `PLAYER_VISIBLE_ITEM_<slot>_0` — the **public** item entry visibly worn in equipment
-    /// slot `i` (what other clients render from; 12 fields per slot after the 2-field creator).
-    /// The cross-check for the private INV_SLOT guids — and the entry source for our own
-    /// equipment until item objects have a decode path.
+    /// `PLAYER_VISIBLE_ITEM_<slot>_0`: the public entry worn in equipment slot `i`, which other
+    /// clients render from; each slot is 12 dwords, the entry after a 2-dword creator.
     pub fn player_visible_item_entry(&self, i: u8) -> Option<u32> {
         (i < 19)
             .then(|| {
@@ -128,13 +80,9 @@ impl ObjectFields {
             })
             .flatten()
     }
-    /// `PLAYER_VISIBLE_ITEM_<slot>_0 + 1 + j` — the **broadcast enchant ids** on the item worn in
-    /// equipment slot `i`: that 8-field block is the item entry followed by 7 enchant slots, of
-    /// which 1.12 fills exactly two (vmangos `Player::SetVisibleItemSlot` loops
-    /// `MAX_INSPECTED_ENCHANTMENT_SLOT = 2` — PERM then TEMP). This is the only enchant feed a
-    /// client has for **any** unit, itself included: the reference reads a full CGItem's 7-slot
-    /// array (`item+0xc`, wow-re `item-visual-enchant.md` §3b), which on the wire is these.
-    /// Consumed by the weapon-glow lane (decision 0805); `None` = empty slot / field not sent.
+    /// `PLAYER_VISIBLE_ITEM_<slot>_0 + 1 + j`: broadcast enchant `j` of the item in slot `i`;
+    /// vmangos fills only 0 and 1 (`MAX_INSPECTED_ENCHANTMENT_SLOT`). The reference's enchant
+    /// visuals for every unit, itself included, come from these (`item+0xc`).
     pub fn player_visible_item_enchant(&self, i: u8, j: u8) -> Option<u32> {
         (i < 19 && j < 7)
             .then(|| {
@@ -145,15 +93,8 @@ impl ObjectFields {
             })
             .flatten()
     }
-    /// `PLAYER_VISIBLE_ITEM_<slot>_PROPERTIES` — the **broadcast random-suffix roll** of the item
-    /// worn in equipment slot `i`. The 12-dword per-slot record is `creator(2) · entry ·
-    /// enchant[7] · PROPERTIES · PAD`, and PROPERTIES is a `TWO_SHORT` whose **low half** is the
-    /// `ItemRandomProperties` id — the reference reads it with a `movzx WORD` (`0x53339f`, the
-    /// inspect leg's `+0x424` source; wow-re `tooltip-content-law.md` §E7).
-    ///
-    /// This is the only roll feed a client has for anybody else's gear, and its one consumer is
-    /// the NAME: vmangos fills only the PERM/TEMP enchant slots, so an inspected item's suffix
-    /// *lines* stay empty on both sides of the wire — the same thing the reference shows.
+    /// `PLAYER_VISIBLE_ITEM_<slot>_PROPERTIES`: slot `i`'s broadcast suffix roll, the low half
+    /// (`0x53339f`, `movzx WORD`) of the dword after the 7 enchants. Only the name uses it.
     pub fn player_visible_item_properties(&self, i: u8) -> u32 {
         (i < 19)
             .then(|| self.get_u32(FIELD_PLAYER_VISIBLE_ITEM_1_CREATOR + 10 + 12 * u16::from(i)))
@@ -161,124 +102,87 @@ impl ObjectFields {
             .unwrap_or(0)
             & 0xffff
     }
-    /// `PLAYER_FIELD_INV_SLOT_HEAD + 2i` — our equipment (0–18) and equipped-bag (19–22) guids.
+    /// `PLAYER_FIELD_INV_SLOT_HEAD + 2i`: our equipment (0-18) and equipped-bag (19-22) guids.
     pub fn player_inv_slot(&self, i: u8) -> Option<u64> {
         (i < 23).then(|| self.get_guid(FIELD_PLAYER_INV_SLOT_HEAD + 2 * u16::from(i)))?
     }
-    /// `PLAYER_FIELD_PACK_SLOT_1 + 2i` — our backpack's 16 item guids.
+    /// `PLAYER_FIELD_PACK_SLOT_1 + 2i`: our backpack's 16 item guids.
     pub fn player_pack_slot(&self, i: u8) -> Option<u64> {
         (i < 16).then(|| self.get_guid(FIELD_PLAYER_PACK_SLOT_1 + 2 * u16::from(i)))?
     }
-    /// `PLAYER_FIELD_BANK_SLOT_1 + 2i` — our bank's 24 item guids.
+    /// `PLAYER_FIELD_BANK_SLOT_1 + 2i`: our bank's 24 item guids.
     pub fn player_bank_slot(&self, i: u8) -> Option<u64> {
         (i < 24).then(|| self.get_guid(FIELD_PLAYER_BANK_SLOT_1 + 2 * u16::from(i)))?
     }
-    /// `PLAYER_FIELD_BANK_BAG_SLOT_1 + 2i` — the item guid of bank bag `i` (0–5, the 6 purchasable
-    /// bank bag slots); the bag's *contents* stream as an ordinary `CONTAINER_FIELD_SLOT_*` block
-    /// on the bag item itself, addressed by bag byte 63–68 (decision 0604).
+    /// `PLAYER_FIELD_BANK_BAG_SLOT_1 + 2i`: bank bag `i`'s guid; its contents stream on the bag
+    /// item's own `CONTAINER_FIELD_SLOT_*`, addressed as bag 63-68.
     pub fn player_bank_bag_slot(&self, i: u8) -> Option<u64> {
         (i < 6).then(|| self.get_guid(FIELD_PLAYER_BANK_BAG_SLOT_1 + 2 * u16::from(i)))?
     }
-    /// `PLAYER_FIELD_KEYRING_SLOT_1 + 2i` — the keyring's item guids. The **field array is 32
-    /// guids** (`UpdateFields_1_12_1.h`: size 64 dwords; vmangos `MAX_KEYRING_SLOTS 32`) and the
-    /// client's inventory walker treats all 32 as its keyring band (absolute slots 81–112, mode
-    /// bit `0x40` — wow-re `action-item-slot.md` §8.2), but only the **first 16 are addressable
-    /// positions** on this wire (vmangos `KEYRING_SLOT_START 81`, `KEYRING_SLOT_END 97`, whose own
-    /// comment reads "32 slots (only 16 are visible/accessible in UI)"), and only as many of those
-    /// as the player's level unlocks are usable (4/8/12/16 — `ui_items::keyring_size`). Feeds the
-    /// keyring container (decision 0765) and the
-    /// GameObject lock chain's key-slot resolver, which scans the keyring alongside the bags
-    /// (wow-re `cursor-system.md` §8.4; decision 0752). `Some(0)` = empty.
+    /// `PLAYER_FIELD_KEYRING_SLOT_1 + 2i`: 32 guids the client walks as slots 81-112, but only
+    /// 16 are addressable (vmangos `KEYRING_SLOT_END 97`) and level unlocks 4, 8, 12 or 16.
     pub fn player_keyring_slot(&self, i: u8) -> Option<u64> {
         (i < 32).then(|| self.get_guid(FIELD_PLAYER_KEYRING_SLOT_1 + 2 * u16::from(i)))?
     }
-    /// `PLAYER_FIELD_VENDORBUYBACK_SLOT_1 + 2i` — the item guid parked in buyback slot `i` (0–11;
-    /// the wire's absolute inventory slot is `69 + i`). `Some(0)` = empty.
+    /// `PLAYER_FIELD_VENDORBUYBACK_SLOT_1 + 2i`: buyback slot `i`, inventory slot `69 + i`.
     pub fn player_buyback_slot(&self, i: u8) -> Option<u64> {
         (i < 12).then(|| self.get_guid(FIELD_PLAYER_VENDORBUYBACK_SLOT_1 + 2 * u16::from(i)))?
     }
-    /// `PLAYER_FIELD_BUYBACK_PRICE_1 + i` — what buying slot `i` back costs, in copper.
+    /// `PLAYER_FIELD_BUYBACK_PRICE_1 + i`: what buying slot `i` back costs, in copper.
     pub fn player_buyback_price(&self, i: u8) -> Option<u32> {
         (i < 12).then(|| self.get_u32(FIELD_PLAYER_BUYBACK_PRICE_1 + u16::from(i)))?
     }
-    /// `PLAYER_FIELD_BUYBACK_TIMESTAMP_1 + i` — slot `i`'s expiry stamp; the client uses it only
-    /// to order the buyback list oldest→newest (wow-re `0x4fafd0`).
+    /// `PLAYER_FIELD_BUYBACK_TIMESTAMP_1 + i`: expiry, used only to sort oldest first (`0x4fafd0`).
     pub fn player_buyback_timestamp(&self, i: u8) -> Option<u32> {
         (i < 12).then(|| self.get_u32(FIELD_PLAYER_BUYBACK_TIMESTAMP_1 + u16::from(i)))?
     }
-    /// `PLAYER_FIELD_COINAGE` — our purse in copper. `None` for a non-player unit (no PLAYER block)
-    /// or before the field has streamed in; the descriptor's zero-initialized default is 0 copper.
+    /// `PLAYER_FIELD_COINAGE`: our money, in copper.
     pub fn player_money(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_FIELD_COINAGE)
     }
-    /// `PLAYER_FARSIGHT` — the object our view is anchored to while a far-sight effect runs (Mind
-    /// Vision, Sentry Totem, the Ornate Spyglass), or `None` when the view is our own body.
-    ///
-    /// PRIVATE, so like [`Self::player_xp`] it only ever streams for our own avatar — which is the
-    /// whole consumer: this answers "what does the camera orbit", never anything about another
-    /// player. `0` is the cleared state and reads as `None`, following the house convention for
-    /// guid fields ([`Self::unit_charmed_by`] and friends): a zero guid is absence, not an object.
+    /// `PLAYER_FARSIGHT` (private): the view's anchor during Mind Vision and the like, or 0.
     pub fn player_farsight(&self) -> Option<u64> {
         self.get_guid(FIELD_PLAYER_FARSIGHT).filter(|&g| g != 0)
     }
-    /// `PLAYER_XP` — our current experience within the level (`UnitXP("player")`). `None` for a
-    /// non-player unit (no PLAYER block) or before the field has streamed; a PRIVATE field, so it
-    /// only ever arrives for our own avatar's descriptor.
+    /// `PLAYER_XP` (private): experience within the current level, `UnitXP("player")`.
     pub fn player_xp(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_XP)
     }
-    /// `PLAYER_NEXT_LEVEL_XP` — experience required to reach the next level (`UnitXPMax("player")`).
-    /// Same PRIVATE/own-player caveat as [`Self::player_xp`].
+    /// `PLAYER_NEXT_LEVEL_XP` (private): experience to the next level, `UnitXPMax("player")`.
     pub fn player_next_level_xp(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_NEXT_LEVEL_XP)
     }
-    /// `PLAYER_FIELD_WATCHED_FACTION_INDEX` — the reputation-list slot whose bar rides the main
-    /// menu bar (`GetWatchedFactionInfo`), or `-1` for none. Same PRIVATE/own-player caveat as
-    /// [`Self::player_xp`].
-    ///
-    /// **Signed, and `0` is not "none".** Slot 0 is the Bloodsail Buccaneers, so the only
-    /// no-faction value is `-1` — reading this field as unsigned would silently watch them.
+    /// `PLAYER_FIELD_WATCHED_FACTION_INDEX` (private): the reputation slot on the main menu bar,
+    /// signed: none is `-1`, since slot 0 is the Bloodsail Buccaneers.
     pub fn player_watched_faction(&self) -> Option<i32> {
         self.get_u32(FIELD_PLAYER_WATCHED_FACTION_INDEX)
             .map(|v| v as i32)
     }
-    /// `PLAYER_CHARACTER_POINTS1` — unspent talent points (`UnitCharacterPoints("player")`'s
-    /// first return; the talent frame's "N talent points" line, decision 0304). Same
-    /// PRIVATE/own-player caveat as [`Self::player_xp`].
+    /// `PLAYER_CHARACTER_POINTS1` (private): unspent talent points, first of `UnitCharacterPoints`.
     pub fn player_talent_points(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_CHARACTER_POINTS1)
     }
-    /// `PLAYER_CHARACTER_POINTS2` — free primary professions (`UnitCharacterPoints`'s second
-    /// return; the "You now have %d free professions." chat line). Same caveat as above.
+    /// `PLAYER_CHARACTER_POINTS2` (private): free professions, second of `UnitCharacterPoints`.
     pub fn player_free_professions(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_CHARACTER_POINTS2)
     }
-    /// `PLAYER_TRACK_CREATURES` — the active creature-tracking bitmask (bit `1 << (creatureType −
-    /// 1)` per active TRACK_CREATURES aura): the minimap red-dot predicate's mask. PRIVATE — self
-    /// only; absent (no PLAYER block, or nothing ever tracked) reads as no tracking.
+    /// `PLAYER_TRACK_CREATURES` (private): bit `1 << (creatureType - 1)` per creature tracking
+    /// aura, the mask the minimap's red dots test.
     pub fn player_track_creatures(&self) -> u32 {
         self.get_u32(FIELD_PLAYER_TRACK_CREATURES).unwrap_or(0)
     }
-    /// `PLAYER_TRACK_RESOURCES` — the active resource-tracking bitmask (bit `1 << (lockType − 1)`
-    /// per active TRACK_RESOURCES aura, e.g. Find Minerals → the Mining `LockType.dbc` bit): the
-    /// minimap gold-dot predicate's mask. Same PRIVATE/self-only caveat as above.
+    /// `PLAYER_TRACK_RESOURCES` (private): bit `1 << (lockType - 1)` per resource tracking aura
+    /// (`LockType.dbc`), the mask the minimap's gold dots test.
     pub fn player_track_resources(&self) -> u32 {
         self.get_u32(FIELD_PLAYER_TRACK_RESOURCES).unwrap_or(0)
     }
-    /// `PLAYER_FIELD_BYTES` byte 0 bit `0x2` — track-stealthed active (vmangos
-    /// `PLAYER_FIELD_BYTE_TRACK_STEALTHED`, set by the TRACK_STEALTHED(151) aura handler): the
-    /// tracking classifier's stealth always-show clause — with it set, any CREEP-flagged unit
-    /// red-dots (`0x5ed210` @ the `+0x1028` read, wow-re `track-predicates.md`). Same
-    /// PRIVATE/self-only caveat as the tracking masks.
+    /// `PLAYER_FIELD_BYTES` byte 0 bit `0x2` (private): set by aura type 151, track stealthed;
+    /// every creep-flagged unit then gets a minimap dot (`0x5ed210`, the `+0x1028` read).
     pub fn player_track_stealthed(&self) -> bool {
         self.get_u32(FIELD_PLAYER_FIELD_BYTES).unwrap_or(0) & 0x2 != 0
     }
-    /// `PLAYER_QUEST_LOG_<slot+1>_*` — one decoded quest-log slot (0-based, `slot <
-    /// PLAYER_QUEST_LOG_SLOTS`). `None` when the slot's id field never streamed (or the index is out
-    /// of range); `Some` with `quest_id == 0` is a slot the server has explicitly cleared (an
-    /// abandon/turn-in leaves this). The count-state and timer fields default to `0` when absent —
-    /// the server writes them with the id on every occupy (vmangos `Player.h:1094-1099`
-    /// `SetQuestSlot`), so an absent pair only ever accompanies an untouched slot.
+    /// `PLAYER_QUEST_LOG_<slot+1>_*`: one quest-log slot, `quest_id == 0` when the server cleared
+    /// it; the count-state and timer are written with the id (`Player.h:1094-1099`).
     pub fn player_quest_log(&self, slot: u8) -> Option<QuestLogSlot> {
         if slot >= PLAYER_QUEST_LOG_SLOTS {
             return None;
@@ -298,81 +202,64 @@ impl ObjectFields {
             timer,
         })
     }
-    /// `PLAYER_EXPLORED_ZONES_1 + i` — the discovery bitset's `i`-th u32 (absent slots read 0:
-    /// a fresh descriptor means nothing explored yet). The full set is
-    /// [`PLAYER_EXPLORED_ZONES_SLOTS`] slots; bit `n` of the whole = AreaTable exploreFlag `n`.
+    /// `PLAYER_EXPLORED_ZONES_1 + i`: bitset dword `i`; bit `n` is `AreaTable` explore flag `n`.
     pub fn player_explored_zone_slot(&self, i: u16) -> u32 {
         if i >= PLAYER_EXPLORED_ZONES_SLOTS {
             return 0;
         }
         self.get_u32(FIELD_PLAYER_EXPLORED_ZONES_1 + i).unwrap_or(0)
     }
-    /// `PLAYER_BLOCK_PERCENTAGE` — our chance to block, already a percent (2.62 = "2.62%"). The
-    /// spell tooltip's chance-to-X line (law §3-CHANCE) reads exactly this and its three
-    /// neighbours; the character sheet reads them too. `None` for a non-player unit.
+    /// `PLAYER_BLOCK_PERCENTAGE`: block chance, already a percent (2.62 means 2.62%).
     pub fn player_block_percentage(&self) -> Option<f32> {
         self.get_f32(FIELD_PLAYER_BLOCK_PERCENTAGE)
     }
-    /// `PLAYER_DODGE_PERCENTAGE` — see [`Self::player_block_percentage`].
+    /// `PLAYER_DODGE_PERCENTAGE`: dodge chance, already a percent.
     pub fn player_dodge_percentage(&self) -> Option<f32> {
         self.get_f32(FIELD_PLAYER_DODGE_PERCENTAGE)
     }
-    /// `PLAYER_PARRY_PERCENTAGE` — see [`Self::player_block_percentage`].
+    /// `PLAYER_PARRY_PERCENTAGE`: parry chance, already a percent.
     pub fn player_parry_percentage(&self) -> Option<f32> {
         self.get_f32(FIELD_PLAYER_PARRY_PERCENTAGE)
     }
-    /// `PLAYER_CRIT_PERCENTAGE` — melee crit; see [`Self::player_block_percentage`]. (The ranged
-    /// twin sits one slot above and has no consumer yet.)
+    /// `PLAYER_CRIT_PERCENTAGE`: melee crit chance, already a percent; ranged is the next field.
     pub fn player_crit_percentage(&self) -> Option<f32> {
         self.get_f32(FIELD_PLAYER_CRIT_PERCENTAGE)
     }
-    /// `PLAYER_FIELD_POSSTAT0 + i` — stat `i`'s **positive** buff delta: the sum of every gear,
-    /// enchant and aura contribution the server split out of `UNIT_FIELD_STAT0 + i`. **INT on the
-    /// wire**, whatever the server keeps internally — see the field's doc comment. `i >= 5` reads
-    /// `None`.
+    /// `PLAYER_FIELD_POSSTAT0 + i`: stat `i`'s positive buff total from gear, enchants and
+    /// auras; an int on the wire, narrowed from the server's float (`BuildValuesUpdate`).
     pub fn player_posstat(&self, i: u8) -> Option<i32> {
         (i < 5).then(|| self.get_i32(FIELD_PLAYER_POSSTAT0 + u16::from(i)))?
     }
-    /// `PLAYER_FIELD_NEGSTAT0 + i` — stat `i`'s **negative** buff delta; negative-or-zero, read
-    /// signed because only one of the two server host architectures can carry the sign at all (the
-    /// field's doc comment). `i >= 5` reads `None`.
+    /// `PLAYER_FIELD_NEGSTAT0 + i`: stat `i`'s negative buff total, an int at or below 0. An x86
+    /// server sends it in two's complement, an arm64 one saturates it to 0.
     pub fn player_negstat(&self, i: u8) -> Option<i32> {
         (i < 5).then(|| self.get_i32(FIELD_PLAYER_NEGSTAT0 + u16::from(i)))?
     }
-    /// `PLAYER_FIELD_RESISTANCEBUFFMODSPOSITIVE + school` — the positive resistance buff for
-    /// `school` (0..6), INT on the wire. `school >= 7` reads `None`.
+    /// `PLAYER_FIELD_RESISTANCEBUFFMODSPOSITIVE + school`: the positive resistance buff, an int.
     pub fn player_resistance_buff_pos(&self, school: u8) -> Option<i32> {
         (school < 7)
             .then(|| self.get_i32(FIELD_PLAYER_RESISTANCEBUFFMODSPOSITIVE + u16::from(school)))?
     }
-    /// `PLAYER_FIELD_RESISTANCEBUFFMODSNEGATIVE + school` — negative-or-zero (see the field's doc
-    /// comment). `school >= 7` reads `None`.
+    /// `PLAYER_FIELD_RESISTANCEBUFFMODSNEGATIVE + school`: the negative resistance buff, at most 0.
     pub fn player_resistance_buff_neg(&self, school: u8) -> Option<i32> {
         (school < 7)
             .then(|| self.get_i32(FIELD_PLAYER_RESISTANCEBUFFMODSNEGATIVE + u16::from(school)))?
     }
-    /// `PLAYER_FIELD_MOD_DAMAGE_DONE_POS + school` — positive damage-done bonus (`[0]` = physical).
-    /// `school >= 7` reads `None`.
+    /// `PLAYER_FIELD_MOD_DAMAGE_DONE_POS + school`: the positive damage bonus, school 0 physical.
     pub fn player_mod_damage_done_pos(&self, school: u8) -> Option<i32> {
         (school < 7).then(|| self.get_i32(FIELD_PLAYER_MOD_DAMAGE_DONE_POS + u16::from(school)))?
     }
-    /// `PLAYER_FIELD_MOD_DAMAGE_DONE_NEG + school` — negative-or-zero (see the field's doc
-    /// comment). `school >= 7` reads `None`.
+    /// `PLAYER_FIELD_MOD_DAMAGE_DONE_NEG + school`: the negative damage bonus, at most 0.
     pub fn player_mod_damage_done_neg(&self, school: u8) -> Option<i32> {
         (school < 7).then(|| self.get_i32(FIELD_PLAYER_MOD_DAMAGE_DONE_NEG + u16::from(school)))?
     }
-    /// `PLAYER_FIELD_MOD_DAMAGE_DONE_PCT + school` — the damage-done percent multiplier (a true
-    /// float; see the field's doc comment — decision 0208's flagged question, now closed).
-    /// `school >= 7` reads `None`; an in-range-but-absent read (no aura has touched this school
-    /// yet) is the caller's job to default to `1.0` — the wire only sends fields that changed.
+    /// `PLAYER_FIELD_MOD_DAMAGE_DONE_PCT + school`: the damage multiplier, a true float that the
+    /// server starts at 1.0 (`Player.cpp:3336`); a caller reads `None` as 1.0.
     pub fn player_mod_damage_done_pct(&self, school: u8) -> Option<f32> {
         (school < 7).then(|| self.get_f32(FIELD_PLAYER_MOD_DAMAGE_DONE_PCT + u16::from(school)))?
     }
-    /// `PLAYER_SKILL_INFO_<slot+1>_*` — one decoded skill slot (`slot < `[`PLAYER_SKILL_SLOTS`]).
-    /// `None` when the id dword never streamed (or `slot` is out of range); the value/max and
-    /// bonus dwords default to `0` when absent (mirroring [`Self::player_quest_log`]'s tolerance —
-    /// vmangos writes id and value together on `SetSkill`, so an absent pair only ever accompanies
-    /// a slot whose snapshot hasn't landed yet).
+    /// `PLAYER_SKILL_INFO_<slot+1>_*`: one skill slot; vmangos writes the id and value together
+    /// (`SetSkill`), so an absent value or bonus reads 0.
     pub fn player_skill(&self, slot: u8) -> Option<PlayerSkillSlot> {
         if slot >= PLAYER_SKILL_SLOTS {
             return None;
@@ -390,432 +277,226 @@ impl ObjectFields {
             perm_bonus: perm_bonus as i16,
         })
     }
-    /// `PLAYER_AMMO_ID` — the equipped ammo pouch/quiver's item id (arrows/bullets), or `None`
-    /// before the field streams. `0` = no ammo selected.
+    /// `PLAYER_AMMO_ID`: the item id of the selected arrows or bullets, 0 for none.
     pub fn player_ammo_id(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_AMMO_ID)
     }
-    /// `PLAYER_SELF_RES_SPELL` — the spell the server will cast on `CMSG_SELF_RES`, i.e. **the
-    /// self-resurrect this corpse is owed**: a warlock's Soulstone ("Use Soulstone" 3026 /
-    /// 20758-20761), a shaman's Reincarnation (21169), or Twisting Nether (23700). `None` when
-    /// there is none — the field absent *or* zero are the same fact, so both collapse here
-    /// (decision 1746).
-    ///
-    /// The server writes it at the death itself (`Player::SetDeathState(JUST_DIED)` keeps a
-    /// standing soulstone id across the aura wipe, else falls back to
-    /// `Player::SelectResurrectionSpellId()` for the passive cases) and **zeroes it on any
-    /// resurrection by another means** — so this field alone is the whole client-side condition;
-    /// there is no second gate and no cooldown/reagent test on our side. It is flushed
-    /// *immediately*, in its own `SMSG_UPDATE_OBJECT`, one line **before** the health→0 flush
-    /// (`Unit::DealDamage`, `Unit.cpp:1136-1143`) — which is why the field is already in the
-    /// descriptor by the time the death edge fires, and why the DEATH popup can read it in
-    /// `OnShow`.
-    ///
-    /// `PLAYER_FLAGS_CAN_SELF_RESURRECT (0x1000)` is the pre-1.6 carrier of the same fact and is
-    /// dead on this build — vmangos sets it only under `SUPPORTED_CLIENT_BUILD < CLIENT_BUILD_1_6_1`
-    /// (`Player.cpp:1537-1569`).
+    /// `PLAYER_SELF_RES_SPELL`: the spell `CMSG_SELF_RES` casts (Soulstone 3026, 20758-20761,
+    /// Reincarnation 21169, Twisting Nether 23700) and the whole condition for offering it; set
+    /// one flush before health 0 at death (`Unit.cpp:1136-1143`), zeroed by any other resurrection.
     pub fn player_self_res_spell(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_SELF_RES_SPELL)
             .filter(|&s| s != 0)
     }
-    /// `PLAYER_BYTES` — packed skinColor (byte 0) / faceType (byte 1) / hairStyle (byte 2) / hairColor
-    /// (byte 3). The character compositor's customization input (RF-0056).
+    /// `PLAYER_BYTES`: skinColor, faceType, hairStyle and hairColor, bytes 0 to 3.
     pub fn player_bytes(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_BYTES)
     }
-    /// `PLAYER_BYTES_2` — byte 0 = facialHair, byte 1 = unk, byte 2 = bankBagSlots (see
-    /// [`Self::player_bank_bag_slots_purchased`]), byte 3 = restState (see
-    /// [`Self::player_rest_state`]).
+    /// `PLAYER_BYTES_2`: facialHair, unknown, bank bag slots and rest state, bytes 0 to 3.
     pub fn player_bytes_2(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_BYTES_2)
     }
-    /// `PLAYER_BYTES_2` **byte 3** — the rest state the client's `GetRestState()` maps to its
-    /// (id, name, multiplier) triple: `1` = rested, `2` = normal (vmangos `REST_STATE_*`,
-    /// `Player.h:673`). The server writes it with hysteresis off the rest pool — rested when the
-    /// pool exceeds 10, normal when it falls to ≤1 (`SetRestBonus`) — so the byte, not the pool,
-    /// is the state authority.
-    ///
-    /// **Absent reads `0`, not "normal"** — the struct's own absent-field law, and it is the
-    /// truth: vmangos always writes this word (`Player::Create` and `LoadFromDB` seed byte 3 with
-    /// `REST_STATE_NORMAL` and byte 1 with `0xEE`, so the field is never zero and never masked out
-    /// of a create block), so on a created store this IS the wire's byte. `0` is what the client's
-    /// own zero-initialized descriptor holds *before* the create lands, and it is a state
-    /// `Exhaustion.dbc` cannot map — `GetRestState()` answers the binary's `(nil, nil, nil)` fail
-    /// path for it, which the reference's own unguarded `exhaustionStateID >= 3` cannot survive.
-    /// The reference never meets that because FrameXML is up and the descriptor has landed before
-    /// any handler runs; we hold the same guarantee at the feed's own gate
-    /// (`ui_script::ingame_ui_pending`, 1348). Do not fabricate a `2` here — that hides an
-    /// ordering bug behind a value.
+    /// `PLAYER_BYTES_2` byte 3: rest state, 1 rested, 2 normal (`Player.h:673`), set with
+    /// hysteresis on the pool (`SetRestBonus`). Absent reads 0, which `GetRestState()` answers
+    /// with nils; do not default it to 2, which would hide a read before the create landed.
     pub fn player_rest_state(&self) -> Option<u8> {
         self.player_bytes_2().map(|b| (b >> 24) as u8)
     }
-    /// `PLAYER_REST_STATE_EXPERIENCE` (field 1175) — the rested-XP pool, in **base kill-XP
-    /// units**: the server drains it 1:1 against a kill's base XP while granting +100%
-    /// (vmangos `GetXPRestBonus`), so the doubled-XP span the exhaustion tick marks is 2× this
-    /// value. `None` before the field streams (PRIVATE — self only).
+    /// `PLAYER_REST_STATE_EXPERIENCE` (field 1175, private): the rested pool in base kill XP,
+    /// drained 1:1 while kills pay double (`GetXPRestBonus`), so the bar's rested span is twice it.
     pub fn player_rest_state_experience(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_REST_STATE_EXPERIENCE)
     }
-    /// `PLAYER_BYTES_3` **byte 1** — the inebriation byte (0..255) drunkenness renders from. The
-    /// server packs `gender | (drunk & 0xFFFE)` into the field's low u16 and decays it 256 per
-    /// 10 s (vmangos `Player::SetDrunkValue` / `HandleDrunkReduce`), so this byte is
-    /// `drunk_u16 >> 8` — the value the reference clamps to 100 and scales ×0.01 into its drunk
-    /// fraction (`[[unit+0xe68]+0x1d]`, wow-re `drunk_fraction_5e2a90`). `None` when never sent
-    /// on a bare delta; a create snapshot reads absent as `Some(0)` (sober).
+    /// `PLAYER_BYTES_3` byte 1: drunkenness, the high byte of `drunk & 0xFFFE` in the low half
+    /// (`SetDrunkValue`); the reference clamps it to 100 and scales by 0.01 (`0x5e2a90`).
     pub fn player_drunk_byte(&self) -> Option<u8> {
         self.get_u32(FIELD_PLAYER_BYTES_3).map(|v| (v >> 8) as u8)
     }
-    /// `PLAYER_FLAGS` (field 190) — the player state flags. `0` when absent (the descriptor's
-    /// zero default — a create block skips zero fields).
+    /// `PLAYER_FLAGS` (field 190): the player state flags.
     pub fn player_flags(&self) -> u32 {
         self.get_u32(FIELD_PLAYER_FLAGS).unwrap_or(0)
     }
-    /// **`PLAYER_FLAGS` bit `0x1` — this player leads their group.** The sole consumer image-wide
-    /// is `UnitIsPartyLeader 0x516210`'s first leg (`0x51624a`), out of 55 sites reading this
-    /// field, and it is the only test of the bit anywhere (wow-re
-    /// `ui/scratch/party-leader-and-nameplate-verbs.md`).
-    ///
-    /// The bit's POSITION is verified; the name `PLAYER_FLAGS_GROUP_LEADER` is inferred, earned
-    /// from two disjoint in-binary controls that pin its neighbours — `0x5eca0c` → `"CHAT_FLAG_AFK"`
-    /// and `0x5eca49` → `"CHAT_FLAG_DND"` fix bits 1 and 2, so this is the one before them.
-    ///
-    /// **Server-sourced, and that is the point.** It answers for any held player, including a
-    /// stranger who leads their *own* party — something a comparison against our group's leader
-    /// GUID cannot express. It is one of the predicate's two legs, never the whole of it.
+    /// `PLAYER_FLAGS` bit `0x1`: leads their group, for a stranger's party too; the first leg of
+    /// `UnitIsPartyLeader` (`0x51624a`) and the bit's only test.
     pub fn player_is_group_leader(&self) -> bool {
         self.player_flags() & 0x1 != 0
     }
-    /// Whether the player is a released **ghost** — `PLAYER_FLAGS_GHOST (0x10)`, set/cleared by
-    /// the ghost aura 8326 at release/resurrect (decision 0308 §1). NB a ghost's health is **1**
-    /// on the wire, so `unit_is_dead` is FALSE for a ghost: the three predicates are
-    /// dead = health 0 · ghost = this bit · dead-or-ghost = either (the real client's
-    /// UnitIsDead/UnitIsGhost/UnitIsDeadOrGhost trio).
+    /// `PLAYER_FLAGS_GHOST` (`0x10`), from aura 8326; a ghost has health 1, so not `unit_is_dead`.
     pub fn player_is_ghost(&self) -> bool {
         self.player_flags() & 0x10 != 0
     }
-    /// Whether this player has asked for their **helm** not to be drawn —
-    /// `PLAYER_FLAGS_HIDE_HELM (0x400)` (vmangos `Player.h:325`), flipped by `CMSG_TOGGLE_HELM`
-    /// and persisted per character through the char-enum record's `CHARACTER_FLAG_HIDE_HELM`.
-    ///
-    /// `PLAYER_FLAGS` is `UF_FLAG_PUBLIC`, which is the whole point of reading it *here* rather
-    /// than off a local setting: the preference streams for every player in range, so a remote
-    /// player's hidden helm hides on our screen too, and ours hides on theirs (decision 1472).
-    /// Creatures have no `PLAYER_FLAGS` and read `false`.
+    /// `PLAYER_FLAGS_HIDE_HELM` (`0x400`, `Player.h:325`), set by `CMSG_TOGGLE_HELM`; public.
     pub fn player_hides_helm(&self) -> bool {
         self.player_flags() & 0x400 != 0
     }
-    /// Whether this player has asked for their **cloak** not to be drawn —
-    /// `PLAYER_FLAGS_HIDE_CLOAK (0x800)`, [`Self::player_hides_helm`]'s twin in every respect.
+    /// `PLAYER_FLAGS_HIDE_CLOAK` (`0x800`), public like the helm bit.
     pub fn player_hides_cloak(&self) -> bool {
         self.player_flags() & 0x800 != 0
     }
-    /// Whether the player is inside a rest area (inn/city) — `PLAYER_FLAGS_RESTING (0x20)`
-    /// (vmangos `Player.h:320`), set/cleared by the area-trigger/zone rest checks
-    /// (`SetRestType`). The real client's `IsResting()` and the player frame's flashing zzz
-    /// state icon read exactly this bit.
+    /// `PLAYER_FLAGS_RESTING` (`0x20`, `Player.h:320`): in an inn or city; `IsResting()` reads it.
     pub fn player_is_resting(&self) -> bool {
         self.player_flags() & 0x20 != 0
     }
-    /// `PLAYER_DUEL_ARBITER` (field 188, GUID) — the duel-flag GameObject of the duel this player
-    /// is in, `0` when they are in none. Set on both duellists by `Spell::EffectDuel`, cleared by
-    /// `Player::DuelComplete`; **PUBLIC**, so it streams for every player we can see and not just
-    /// ourselves — which is what lets the client resolve a duel relationship it is not part of.
-    /// Paired with [`Self::player_duel_team`] it is the whole client-side duel law (0633).
+    /// `PLAYER_DUEL_ARBITER` (field 188, guid, public): the duel flag GameObject, 0 for none;
+    /// set on both duellists at the challenge (`Spell::EffectDuel`).
     pub fn player_duel_arbiter(&self) -> u64 {
         self.get_guid(FIELD_PLAYER_DUEL_ARBITER).unwrap_or(0)
     }
-    /// `PLAYER_DUEL_TEAM` (field 196) — `0` until the countdown finishes, then `1` for the
-    /// challenger and `2` for the challenged (`Player::UpdateDuelFlag`). Non-zero on **both**
-    /// sides is what says the duel is actually under way: the arbiter is set from the moment of
-    /// the challenge, so hostility keys off the pair, never the arbiter alone (0633).
+    /// `PLAYER_DUEL_TEAM` (field 196): 0 until the countdown ends, then 1 challenger, 2
+    /// challenged (`Player::UpdateDuelFlag`); a duel is live only when both sides are nonzero.
     pub fn player_duel_team(&self) -> u32 {
         self.get_u32(FIELD_PLAYER_DUEL_TEAM).unwrap_or(0)
     }
-    /// `PLAYER_GUILDID` (field 191) — the id of the guild this player belongs to, `0` for a
-    /// guildless one (and for the absent field, which is the same thing: the descriptor skips
-    /// zeroes). **PUBLIC**, so it arrives for every visible player, not only for us.
-    ///
-    /// It names a guild but does not describe one: the name and the rank names come only from
-    /// `SMSG_GUILD_QUERY_RESPONSE`, keyed by this id (decision 1257). The real client's own
-    /// `GetGuildInfo 0x4c9330` reads exactly this field and answers nil on both the `0` and the
-    /// cache-miss legs (`0x4c93a9`, `0x4c93d7`).
+    /// `PLAYER_GUILDID` (field 191, public): the guild, 0 for none; names come from
+    /// `SMSG_GUILD_QUERY_RESPONSE`, and `GetGuildInfo` (`0x4c9330`) answers nil on 0 or a miss.
     pub fn player_guild_id(&self) -> u32 {
         self.get_u32(FIELD_PLAYER_GUILDID).unwrap_or(0)
     }
-    /// `PLAYER_GUILDRANK` (field 192) — this player's rank within [`Self::player_guild_id`]'s
-    /// guild, **0-based with `0` = guild master** (vmangos promotes with `rank--`). Meaningless
-    /// while the guild id is `0`. Indexes both [`crate::messages::GuildQueryResponse::rank_names`]
-    /// and [`crate::messages::GuildRoster::rank_rights`].
-    ///
-    /// The reference indexes its cached rank-name array with this **unbounded**
-    /// (`0x4c93e4 mov edx,[ecx+0x10]` / `shl edx,0x6`); a consumer of ours must bound it against
-    /// the ten slots that array really has.
+    /// `PLAYER_GUILDRANK` (field 192): the guild rank, 0 the guild master; the reference indexes
+    /// its rank names with it unbounded (`0x4c93e4`), so bound it to the ten ranks.
     pub fn player_guild_rank(&self) -> u32 {
         self.get_u32(FIELD_PLAYER_GUILDRANK).unwrap_or(0)
     }
-    /// `PLAYER_FIELD_BYTES` byte 0 bit `0x08` — `PLAYER_FIELD_BYTE_RELEASE_TIMER`, "Display time
-    /// till auto release spirit" (the header's own comment): set at death iff the map is
-    /// non-instanceable, i.e. exactly when the server will force-release after 6:00. The client
-    /// mirrors that constant for the DEATH popup's countdown (byte-VERIFIED — wow-re death-ui.md
-    /// §1: the client arms `now + 360000 ms` at its own alive→dead edge; bit clear ⇒
-    /// `GetReleaseTimeRemaining() == -1`).
+    /// `PLAYER_FIELD_BYTES` byte 0 bit `0x08`, `PLAYER_FIELD_BYTE_RELEASE_TIMER`: set at death
+    /// outside instances, where the server releases the spirit after 6 minutes; the client arms
+    /// its own `now + 360000` ms, and with the bit clear `GetReleaseTimeRemaining()` is -1.
     pub fn player_release_timer_running(&self) -> bool {
         self.get_u32(FIELD_PLAYER_FIELD_BYTES).unwrap_or(0) & 0x08 != 0
     }
-    /// `PLAYER_FIELD_BYTES` byte 1 — the player's **combo points** (0..5; vmangos
-    /// `PLAYER_FIELD_BYTES_OFFSET_COMBO_POINTS`, written by `Player::SetComboPoints`). PRIVATE, so
-    /// it streams only for our own player — the only consumer. The client reads this byte at
-    /// `[player+0xe68]+0x1029` in the usable walk's leg 5 (the combo-point gate, decision 0869):
-    /// the same dword whose byte 3 is [`Self::player_honor_rank`]'s byte-verified `+0x102b`, off
-    /// the player-block base the duel-arbiter comment pins at `[player+0xe68]`.
-    ///
-    /// **The byte is not rogue/druid-only — the *display* is** (decision 0875). vmangos writes one
-    /// here when a *warrior's* victim **dodges** (`Unit.cpp` `PROC_EX_DODGE` →
-    /// `AddComboPoints(target, 1)` plus a 4 s `REACTIVE_OVERPOWER` timer whose expiry
-    /// `ClearComboPoints`es it) — the server's chosen marker for "Overpower is up", and the only
-    /// way that window reaches the client. Leg 5 reads this byte with no class test, which is what
-    /// greys Overpower; the Lua `GetComboPoints 0x51a190` reads the *same* byte behind a
-    /// rogue-or-druid class gate, which is why a warrior never sees a combo dot light up for it.
-    /// `None` before the field streams.
+    /// `PLAYER_FIELD_BYTES` byte 1 (private): combo points, 0-5, read at `[player+0xe68]+0x1029`.
+    /// vmangos also sets one when a warrior's target dodges (the 4 s Overpower window): the usable
+    /// check reads it for any class, `GetComboPoints` (`0x51a190`) only for rogues and druids.
     pub fn player_combo_points(&self) -> Option<u8> {
         self.get_u32(FIELD_PLAYER_FIELD_BYTES)
             .map(|b| ((b >> 8) & 0xff) as u8)
     }
-    /// `PLAYER_FIELD_COMBO_TARGET` (field 714, GUID) — the unit the banked
-    /// [`Self::player_combo_points`] sit on, written by `Player::SetComboPoints` in the same breath
-    /// as the byte and zeroed with it. PRIVATE, so it only ever streams for our own player.
-    ///
-    /// Combo points are **per target**, and the client enforces that in the *display*, not on the
-    /// wire: `GetComboPoints 0x51a190` reads this pair at `[player+0xe68]+0x838/+0x83c`, compares
-    /// it against the current-target GUID global (`0xb4e2d8/dc`) and pushes `0` on a mismatch
-    /// (decision 0875) — so re-targeting empties the dots without the count moving, and selecting
-    /// the original unit again refills them. `0` when nothing is banked.
+    /// `PLAYER_FIELD_COMBO_TARGET` (field 714, guid, private): the unit the combo points sit on;
+    /// `GetComboPoints` shows 0 unless it is the current target (`0xb4e2d8`).
     pub fn player_combo_target(&self) -> u64 {
         self.get_guid(FIELD_PLAYER_FIELD_COMBO_TARGET).unwrap_or(0)
     }
-    /// `PLAYER_FIELD_BYTES` byte 2 — the **action-bar toggle** byte: which of the four extra bars
-    /// the player has switched on (vmangos `Player.h:360-363`
-    /// `PLAYER_FIELD_BYTES_OFFSET_ACTION_BARS = 2`, written by `HandleSetActionBarTogglesOpcode`'s
-    /// `SetByteValue(PLAYER_FIELD_BYTES, 2, packet.actionBar)`). PRIVATE — the field is only
-    /// *allocated* on our own player (self 1282 dwords vs 486 for any other player), which is why
-    /// the reference binding resolves the local GUID itself instead of taking a unit token.
-    ///
-    /// Byte-VERIFIED (wow-re `system/ui/scratch/action-bar-toggles.md` §4): `GetActionBarToggles
-    /// 0x4e7660` reads it at `[[player+0xe68]+0x102a]`, and `0x2f0 + 0x1028 = 0x1318 = 1222·4`
-    /// closes the arithmetic against index 1222 — the same player-block base that puts
-    /// [`Self::player_combo_points`] at `+0x1029` and [`Self::player_honor_rank`] at `+0x102b`.
-    /// (vmangos's inline comment on the field reads `// 0x4C0`, six low; its own arithmetic
-    /// `UNIT_END + 0x40A` and the binary both say `0x4C6`. The comment is stale — do not copy it.)
-    ///
-    /// **This is the ONLY source of the value: the client never writes the byte.** Displacement
-    /// `0x102a` occurs exactly once image-wide and it is that read; `SetActionBarToggles` stores
-    /// nothing outside its own stack frame and only posts `CMSG_SET_ACTIONBAR_TOGGLES`
-    /// ([`crate::messages::set_actionbar_toggles`]), so the cell moves solely through the generic
-    /// `SMSG_UPDATE_OBJECT` value-apply — and nothing is notified when it does (§4.2). A purely
-    /// field-driven UI therefore lags a round trip; the reference keeps its optimistic copy in Lua
-    /// and re-reads this exactly once, at `PLAYER_ENTERING_WORLD`.
-    ///
-    /// Only bits `0x01`..`0x08` are meaningful to the client — the binding tests four and can set
-    /// four (§2/§5); the high nibble is never read and is destroyed by the next `Set`. Bit→bar is a
-    /// FrameXML convention, not the descriptor's, so it is not named here. `None` before the field
-    /// streams.
+    /// `PLAYER_FIELD_BYTES` byte 2 (private, field 1222): the four extra action bars' toggles,
+    /// bits `0x01..0x08` (`Player.h:360-363`), read by `GetActionBarToggles` (`0x4e7660`) at
+    /// `[[player+0xe68]+0x102a]`. The client never writes it and no event fires when it moves.
+    /// vmangos's `// 0x4C0` beside the field is stale; `UNIT_END + 0x40A` is right.
     pub fn player_action_bar_toggles(&self) -> Option<u8> {
         self.get_u32(FIELD_PLAYER_FIELD_BYTES)
             .map(|b| ((b >> 16) & 0xff) as u8)
     }
-    /// `PLAYER_FIELD_BYTES` byte 3 — the player's **highest lifetime honor rank** (vmangos
-    /// `PLAYER_FIELD_BYTES_OFFSET_HIGHEST_HONOR_RANK`, written by `HonorMgr`): what the client's
-    /// item-usable gate compares an item's `RequiredHonorRank` against (`0x5ea930` reads the
-    /// values byte at `+0x102b`). `None` before the field streams; rank 0 = never ranked.
-    ///
-    /// **Not [`Self::player_pvp_rank`]** — that is the *current* rank, a different byte of a
-    /// different (and PUBLIC) field, and the two diverge the moment a rank is lost: vmangos only
-    /// ever raises this one (`HonorMgr.cpp:894-895`, `SetHighestRank` iff the new visual rank is
-    /// strictly greater), so a demoted player keeps their old title here while the current rank
-    /// falls. The Honor pane shows the current rank; an item requirement reads this one.
+    /// `PLAYER_FIELD_BYTES` byte 3 (private): the highest honor rank held, 0 never ranked, which
+    /// `RequiredHonorRank` checks (`0x5ea930`); only ever raised (`HonorMgr.cpp:894-895`), so it
+    /// outlives a demotion, unlike [`Self::player_pvp_rank`].
     pub fn player_honor_rank(&self) -> Option<u8> {
         self.get_u32(FIELD_PLAYER_FIELD_BYTES)
             .map(|b| ((b >> 24) & 0xff) as u8)
     }
-    /// `PLAYER_BYTES_3` byte 3 — the player's **current** honor rank (vmangos
-    /// `PLAYER_BYTES_3_OFFSET_HONOR_RANK`, written by `HonorMgr::Update`, `HonorMgr.cpp:900`).
-    /// The *internal* rank — `HonorRankInfo::rank`, whose own comment reads "internal range
-    /// [0..18]": 0 = unranked, 1..4 the negative ranks (Pariah…Dishonored), 5 up the positive ones
-    /// (Scout/Private…). It indexes the `PVP_RANK_<rank>_<team>` GlobalStrings directly; the
-    /// number the UI *draws* is the **visual** rank (`rank > 4 ? rank - 4 : -rank`,
-    /// `HonorMgr.cpp:991`), which is a derivation, not a field — do it at the display edge, not
-    /// here, and only once.
-    ///
-    /// **This field is PUBLIC** (vmangos `UpdateFields_1_12_1.h:125`), the only honor value that
-    /// is: it streams for *every visible player*, not just for us. That is what makes a foreign
-    /// unit's rank answerable at all — the reference inspect pane's `UnitPVPRank("target")` reads
-    /// this byte off the target's own descriptor, with no packet involved. Everything else on the
-    /// Honor tab is PRIVATE and has to be requested
-    /// ([`crate::messages::read_inspect_honor_stats`]).
-    ///
-    /// Contrast [`Self::player_honor_rank`], the *highest lifetime* rank in a PRIVATE field's
-    /// byte 3; [`Self::player_drunk_byte`] reads byte 1 of this same dword. `None` before the
-    /// field streams.
+    /// `PLAYER_BYTES_3` byte 3 (public, `UpdateFields_1_12_1.h:125`): the current internal rank
+    /// (`HonorMgr.cpp:900`), 0 unranked, 1-4 negative, 5 up positive, indexing `PVP_RANK_*`;
+    /// the drawn rank is `rank > 4 ? rank - 4 : -rank` (`HonorMgr.cpp:991`).
     pub fn player_pvp_rank(&self) -> Option<u8> {
         self.get_u32(FIELD_PLAYER_BYTES_3)
             .map(|b| ((b >> 24) & 0xff) as u8)
     }
-    /// `PLAYER_BYTES_3` **byte 2** — the **city-protector title**
-    /// (`PLAYER_BYTES_3_OFFSET_CITY_PROTECTOR_TITLE`, vmangos `Player.h:354`, whose own comment
-    /// says the value is a **race id**). PUBLIC, like [`Self::player_pvp_rank`] beside it in the
-    /// same dword.
-    ///
-    /// Its one consumer is `UnitPVPName`, which appends `"\n"` plus the `PVP_MEDAL<n>`
-    /// GlobalString when the byte is non-zero (wow-re `system/ui/scratch/honor-panel-law.md`,
-    /// `0x609370` leg C) — the "Protector of Stormwind" line under a city defender's name.
-    ///
-    /// **vmangos never writes it**, so it is 0 for every character on this server and the medal
-    /// line never renders. Decoded anyway: the field is real, the binding that reads it is real,
-    /// and a decoder that answered `None` here would make a live divergence look like an unbuilt
-    /// feature the day a server does write it. `None` before the field streams.
+    /// `PLAYER_BYTES_3` byte 2 (public): the city-protector title, a race id (`Player.h:354`);
+    /// `UnitPVPName` (`0x609370`) appends `PVP_MEDAL<n>` when nonzero. vmangos never writes it.
     pub fn player_pvp_medal(&self) -> Option<u8> {
         self.get_u32(FIELD_PLAYER_BYTES_3)
             .map(|b| ((b >> 16) & 0xff) as u8)
     }
-    /// `PLAYER_FIELD_SESSION_KILLS` — **today's** `(honorable, dishonorable)` kills, low half then
-    /// high half. The one honor kill counter vmangos genuinely writes as two shorts
-    /// (`HonorMgr.cpp:913-914`, `SetUInt16Value(…, 0, todayHK)` / `(…, 1, todayDK)`), so both
-    /// halves are live here. PRIVATE — self only; `None` before the field streams.
-    ///
-    /// Despite the name the server recomputes it from *today's* honor-CP rows, not from
-    /// session start (`HonorMgr::Update`'s `itr.date == today` arm) — the reference's
-    /// `GetPVPSessionStats()` pair.
+    /// `PLAYER_FIELD_SESSION_KILLS` (private): today's honorable and dishonorable kills, both
+    /// halves written (`HonorMgr.cpp:913-914`); "session" means today, `GetPVPSessionStats()`.
     pub fn player_session_kills(&self) -> Option<(u16, u16)> {
         self.get_u16_pair(FIELD_PLAYER_FIELD_SESSION_KILLS)
     }
-    /// `PLAYER_FIELD_YESTERDAY_KILLS` — `(honorable, dishonorable)` kills for yesterday.
-    ///
-    /// **The dishonorable half is always `0` from this server, and that is not a decode bug.**
-    /// The descriptor type really is TWO_SHORT and the real client really does read halves, but
-    /// vmangos writes the field as a whole dword (`HonorMgr.cpp:917`,
-    /// `SetUInt32Value(PLAYER_FIELD_YESTERDAY_KILLS, yesterdayKills)`) — so the high half never
-    /// receives the DK count. We decode the wire faithfully rather than collapsing the field to a
-    /// `u32`: the shape belongs to the descriptor, and a different server (or a fixed vmangos)
-    /// would fill it. Same for [`Self::player_last_week_kills`] and
-    /// [`Self::player_this_week_kills`]. PRIVATE — self only; `None` before the field streams.
+    /// `PLAYER_FIELD_YESTERDAY_KILLS` (private): yesterday's kills, two shorts; vmangos writes a
+    /// whole dword (`HonorMgr.cpp:917`), so the dishonorable half is 0, not a decode bug.
     pub fn player_yesterday_kills(&self) -> Option<(u16, u16)> {
         self.get_u16_pair(FIELD_PLAYER_FIELD_YESTERDAY_KILLS)
     }
-    /// `PLAYER_FIELD_LAST_WEEK_KILLS` — `(honorable, dishonorable)` kills for last week. The
-    /// high half is always `0` from vmangos (`HonorMgr.cpp:929` writes the whole dword); see
-    /// [`Self::player_yesterday_kills`]. PRIVATE — self only.
+    /// `PLAYER_FIELD_LAST_WEEK_KILLS` (private): last week's kills; the dishonorable half is 0
+    /// from vmangos (`HonorMgr.cpp:929` writes a whole dword).
     pub fn player_last_week_kills(&self) -> Option<(u16, u16)> {
         self.get_u16_pair(FIELD_PLAYER_FIELD_LAST_WEEK_KILLS)
     }
-    /// `PLAYER_FIELD_THIS_WEEK_KILLS` — `(honorable, dishonorable)` kills for the current week.
-    /// The high half is always `0` from vmangos (`HonorMgr.cpp:924` writes the whole dword); see
-    /// [`Self::player_yesterday_kills`]. PRIVATE — self only.
+    /// `PLAYER_FIELD_THIS_WEEK_KILLS` (private): this week's kills; the dishonorable half is 0
+    /// from vmangos (`HonorMgr.cpp:924` writes a whole dword).
     pub fn player_this_week_kills(&self) -> Option<(u16, u16)> {
         self.get_u16_pair(FIELD_PLAYER_FIELD_THIS_WEEK_KILLS)
     }
-    /// `PLAYER_FIELD_THIS_WEEK_CONTRIBUTION` — honor points earned this week (vmangos's
-    /// "contribution": the summed CP of the week's honor rows, floored at 0 —
-    /// `HonorMgr.cpp:925`). PRIVATE — self only; `None` before the field streams.
+    /// `PLAYER_FIELD_THIS_WEEK_CONTRIBUTION` (private): honor earned this week, floored at 0
+    /// (`HonorMgr.cpp:925`).
     pub fn player_this_week_contribution(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_FIELD_THIS_WEEK_CONTRIBUTION)
     }
-    /// `PLAYER_FIELD_YESTERDAY_CONTRIBUTION` — honor points earned yesterday
-    /// (`HonorMgr.cpp:918`). PRIVATE — self only.
+    /// `PLAYER_FIELD_YESTERDAY_CONTRIBUTION` (private): yesterday's honor (`HonorMgr.cpp:918`).
     pub fn player_yesterday_contribution(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_FIELD_YESTERDAY_CONTRIBUTION)
     }
-    /// `PLAYER_FIELD_LAST_WEEK_CONTRIBUTION` — honor points earned last week
-    /// (`HonorMgr.cpp:930`). This is the figure the weekly rank calculation actually consumed.
-    /// PRIVATE — self only.
+    /// `PLAYER_FIELD_LAST_WEEK_CONTRIBUTION` (private): last week's honor, what the weekly rank
+    /// calculation used (`HonorMgr.cpp:930`).
     pub fn player_last_week_contribution(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_FIELD_LAST_WEEK_CONTRIBUTION)
     }
-    /// `PLAYER_FIELD_LAST_WEEK_RANK` — last week's **standing**, i.e. our numeric position on the
-    /// server-wide honor ladder for that week (vmangos `m_standing`, `HonorMgr.cpp:931`), NOT an
-    /// honor rank. `0` means "unranked that week". PRIVATE — self only.
+    /// `PLAYER_FIELD_LAST_WEEK_RANK` (private): last week's standing on the honor ladder, not an
+    /// honor rank; 0 is unranked (`HonorMgr.cpp:931`).
     pub fn player_last_week_rank(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_FIELD_LAST_WEEK_RANK)
     }
-    /// `PLAYER_FIELD_LIFETIME_HONORBALE_KILLS` (vmangos's spelling) — the lifetime honorable-kill
-    /// total (`HonorMgr.cpp:934`). PRIVATE — self only; `None` before the field streams.
+    /// `PLAYER_FIELD_LIFETIME_HONORBALE_KILLS` (private, vmangos's spelling): lifetime honorable
+    /// kills (`HonorMgr.cpp:934`).
     pub fn player_lifetime_honorable_kills(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_FIELD_LIFETIME_HONORABLE_KILLS)
     }
-    /// `PLAYER_FIELD_LIFETIME_DISHONORBALE_KILLS` (vmangos's spelling) — the lifetime
-    /// dishonorable-kill total (`HonorMgr.cpp:935`). PRIVATE — self only.
+    /// `PLAYER_FIELD_LIFETIME_DISHONORBALE_KILLS` (private, vmangos's spelling): lifetime
+    /// dishonorable kills (`HonorMgr.cpp:935`).
     pub fn player_lifetime_dishonorable_kills(&self) -> Option<u32> {
         self.get_u32(FIELD_PLAYER_FIELD_LIFETIME_DISHONORABLE_KILLS)
     }
-    /// `PLAYER_FIELD_BYTES2` byte 0 — the **honor rank progress bar**
-    /// (`PLAYER_FIELD_BYTES_2_OFFSET_HONOR_RANK_BAR`, vmangos `HonorMgr.cpp:905-909`):
-    ///
-    /// ```text
-    /// honorBar = uint32(|rankPoints|);
-    /// honorBar = uint8(((honorBar - rank.minRP) / (rank.maxRP - rank.minRP))
-    ///                  * (rank.positive ? 255 : -255));
-    /// ```
-    ///
-    /// so the byte is **how far through the CURRENT rank we are, scaled 0..255** — not an absolute
-    /// honor total, and it resets each time the rank changes (`minRP`/`maxRP` are that rank's own
-    /// bounds, `HonorMgr::CalculateRankInfo`). A *negative* rank multiplies by `-255`, and the
-    /// C++ cast of a negative float to `uint8` wraps rather than clamping, so the byte a demoted
-    /// player carries is the wrapped product. We carry the byte the wire sent; interpreting the
-    /// negative-rank case is the display edge's problem, not the decoder's.
-    ///
-    /// The field only exists from client 1.6.1 on (vmangos guards the write with
-    /// `SUPPORTED_CLIENT_BUILD >= CLIENT_BUILD_1_6_1`), which is live for build 5875. PRIVATE —
-    /// self only; `None` before the field streams.
+    /// `PLAYER_FIELD_BYTES2` byte 0 (private): progress through the current rank, 0-255
+    /// (`HonorMgr.cpp:905-909`); a negative rank's `-255` scale wraps in the `uint8` cast.
     pub fn player_honor_rank_bar(&self) -> Option<u8> {
         self.get_u32(FIELD_PLAYER_FIELD_BYTES2)
             .map(|b| (b & 0xff) as u8)
     }
-    /// `UNIT_FIELD_BYTES_0` byte 0 — the unit's race. `None` when the field wasn't sent.
+    /// `UNIT_FIELD_BYTES_0` byte 0: race.
     pub fn unit_race(&self) -> Option<u8> {
         self.unit_bytes_0().map(|b| (b & 0xff) as u8)
     }
-    /// `UNIT_FIELD_BYTES_0` byte 1 — the unit's class.
+    /// `UNIT_FIELD_BYTES_0` byte 1: class.
     pub fn unit_class(&self) -> Option<u8> {
         self.unit_bytes_0().map(|b| ((b >> 8) & 0xff) as u8)
     }
-    /// `UNIT_FIELD_BYTES_0` byte 2 — the unit's gender/sex.
+    /// `UNIT_FIELD_BYTES_0` byte 2: gender.
     pub fn unit_gender(&self) -> Option<u8> {
         self.unit_bytes_0().map(|b| ((b >> 16) & 0xff) as u8)
     }
-    /// `PLAYER_BYTES` byte 0 — skinColor. `None` for a non-player unit (no PLAYER block).
+    /// `PLAYER_BYTES` byte 0: skinColor.
     pub fn player_skin(&self) -> Option<u8> {
         self.player_bytes().map(|b| (b & 0xff) as u8)
     }
-    /// `PLAYER_BYTES` byte 1 — faceType.
+    /// `PLAYER_BYTES` byte 1: faceType.
     pub fn player_face(&self) -> Option<u8> {
         self.player_bytes().map(|b| ((b >> 8) & 0xff) as u8)
     }
-    /// `PLAYER_BYTES` byte 2 — hairStyle.
+    /// `PLAYER_BYTES` byte 2: hairStyle.
     pub fn player_hair_style(&self) -> Option<u8> {
         self.player_bytes().map(|b| ((b >> 16) & 0xff) as u8)
     }
-    /// `PLAYER_BYTES` byte 3 — hairColor.
+    /// `PLAYER_BYTES` byte 3: hairColor.
     pub fn player_hair_color(&self) -> Option<u8> {
         self.player_bytes().map(|b| ((b >> 24) & 0xff) as u8)
     }
-    /// `PLAYER_BYTES_2` byte 0 — facialHair.
+    /// `PLAYER_BYTES_2` byte 0: facialHair.
     pub fn player_facial_hair(&self) -> Option<u8> {
         self.player_bytes_2().map(|b| (b & 0xff) as u8)
     }
-    /// `PLAYER_BYTES_2` byte 2 — `PLAYER_BYTES_2_OFFSET_BANK_BAG_SLOTS` (vmangos `Player.h:347`):
-    /// how many of the 6 purchasable bank bag slots are bought. Byte **2**, not byte 1 — the
-    /// server writes byte 0 facialHair, byte 1 unused, byte 2 bankBagSlots, byte 3 restState. The
-    /// only success signal for `CMSG_BUY_BANK_SLOT` (decision 0604): the server sends no packet on
-    /// success, only this descriptor delta (`PLAYERBANKBAGSLOTS_CHANGED` on the reference client).
+    /// `PLAYER_BYTES_2` byte 2 (`Player.h:347`): bank bag slots bought, of 6; this delta is the
+    /// only reply to a successful `CMSG_BUY_BANK_SLOT` (`PLAYERBANKBAGSLOTS_CHANGED`).
     pub fn player_bank_bag_slots_purchased(&self) -> Option<u8> {
         self.player_bytes_2().map(|b| ((b >> 16) & 0xff) as u8)
     }
-    /// `OBJECT_FIELD_CREATED_BY` (the GameObject block's creator guid, fields 6-7 in 1.12): the
-    /// summoning player of a spell-spawned object — the fishing bobber's owner. `None` when absent
-    /// or zero (a world-spawned GO has no creator). The reference's ONE reader on the interaction
-    /// path is the faction resolver `0x5f7fd0`, which prefers the creator's reaction over
-    /// `GAMEOBJECT_FACTION` — the bobber's ownership *gate* is NOT this field but the player's own
-    /// `UNIT_FIELD_CHANNEL_OBJECT` (wow-re `fishing-bobber-interaction.md` §2, the byte-proven
-    /// negative: `0x5f6710` never reads CREATED_BY).
+    /// `OBJECT_FIELD_CREATED_BY` (fields 6-7): who summoned a spell-spawned object; the faction
+    /// resolver `0x5f7fd0` prefers its reaction, but a bobber's use gate is our channel object.
     pub fn gameobject_created_by(&self) -> Option<u64> {
         self.get_guid(FIELD_GAMEOBJECT_CREATED_BY)
             .filter(|&g| g != 0)
@@ -824,19 +505,12 @@ impl ObjectFields {
     pub fn gameobject_displayid(&self) -> Option<i32> {
         self.get_i32(FIELD_GAMEOBJECT_DISPLAYID)
     }
-    /// `GAMEOBJECT_STATE` — 0 active (door open/triggered), 1 ready (closed/armed), 2 active-alt
-    /// (vmangos `GOState`, `OBJECT_END + 0x8` in 1.12). Drives the open/close sound slots.
+    /// `GAMEOBJECT_STATE` (`OBJECT_END + 0x8`): 0 active (open), 1 ready (closed), 2 active-alt.
     pub fn gameobject_state(&self) -> Option<u32> {
         self.get_u32(FIELD_GAMEOBJECT_STATE)
     }
-    /// `GAMEOBJECT_ROTATION` — the spawn's local-rotation quaternion `(x, y, z, w)`. `None` when
-    /// the wire carried no component at all (vmangos omits zero fields from the create mask, and
-    /// an identity-ish quat still sends its nonzero `w`/`z`); absent components within a
-    /// partially-sent quat read as the create-block zero default, so a pure-yaw spawn
-    /// (`x = y = 0`, the live-data norm) round-trips exactly. This is the field a GameObject is
-    /// *placed* by — the reference builds its render matrix from this quaternion and never from
-    /// `GAMEOBJECT_FACING` (decision 1459) — and the basis a type-11 lift rotates its keyframe
-    /// offsets through.
+    /// `GAMEOBJECT_ROTATION`: the spawn quaternion `(x, y, z, w)`, unsent components 0; the
+    /// reference places a GameObject by it, never by `GAMEOBJECT_FACING`.
     pub fn gameobject_rotation(&self) -> Option<[f32; 4]> {
         let any_sent = (0..4u16).any(|i| self.contains(FIELD_GAMEOBJECT_ROTATION + i));
         any_sent.then(|| {
@@ -848,12 +522,8 @@ impl ObjectFields {
             ]
         })
     }
-    /// GameObject position + facing (`GAMEOBJECT_POS_*` / `GAMEOBJECT_FACING`). On a create block this
-    /// is `Some` **even when none of the three were sent** — the created-store zero-fill
-    /// (`get_f32`/`get_u32`'s `created.then_some(0)`) can't tell "genuinely at the origin" from "never
-    /// carried a position at all" (a transport GameObject, whose stationary spot rides the movement
-    /// block's `HAS_POSITION` slot instead — decision 0438 "the wire"). [`Self::gameobject_pos_sent`]
-    /// answers that distinction; the create-placement fallback (`events/decode.rs`) gates on it.
+    /// `GAMEOBJECT_POS_*` and `GAMEOBJECT_FACING`; a create reads `Some` even with no position
+    /// sent, as for a transport, so check [`Self::gameobject_pos_sent`].
     pub fn gameobject_position(&self) -> Option<(Vector3d, f32)> {
         Some((
             Vector3d {
@@ -864,66 +534,43 @@ impl ObjectFields {
             self.get_f32(FIELD_GAMEOBJECT_FACING).unwrap_or(0.0),
         ))
     }
-    /// Whether the wire genuinely carried **any** `GAMEOBJECT_POS_*` field — a raw presence probe on purpose
-    /// (like `get_guid`'s, bypassing the create block's absent-is-zero fold) so a consumer can tell
-    /// "this GO's create never carried a position" from "it did, and it's `0.0` on some axis". A normal
-    /// GameObject sends at least one non-zero axis virtually always; a boat/zeppelin/elevator sends
-    /// **none** (vmangos never sets `GAMEOBJECT_POS_*` on a transport).
+    /// Whether any `GAMEOBJECT_POS_*` was really sent; vmangos sends none for a transport.
     pub fn gameobject_pos_sent(&self) -> bool {
         self.contains(FIELD_GAMEOBJECT_POS_X)
             || self.contains(FIELD_GAMEOBJECT_POS_Y)
             || self.contains(FIELD_GAMEOBJECT_POS_Z)
     }
-    /// `GAMEOBJECT_TYPE_ID` — the GameObject sub-type (DOOR/CHEST/SPELL_FOCUS/…). **Absent ⇒ `0` =
-    /// DOOR**, not "unknown": vmangos omits a zero-valued field from the create mask (the same reason an
-    /// all-zero `PLAYER_BYTES` is never sent), and `GAMEOBJECT_TYPE_DOOR` *is* 0 — so a door sends no type
-    /// field at all, and the absent value is its default. Reading it as `None` silently mis-handled every
-    /// door (no interact cursor, no open/close animation), so this defaults to the wire default.
+    /// `GAMEOBJECT_TYPE_ID`: absent is 0, `GAMEOBJECT_TYPE_DOOR`: a create omits zero fields.
     pub fn gameobject_type_id(&self) -> i32 {
         self.get_i32(FIELD_GAMEOBJECT_TYPE_ID).unwrap_or(0)
     }
-    /// `GAMEOBJECT_FLAGS` (`GameObjectFlags`) — static interactability bits: `0x1` IN_USE (busy),
-    /// `0x4` INTERACT_COND (usable only when the per-player `GAMEOBJECT_DYN_FLAGS` activate bit is set —
-    /// the quest gate), `0x10` NO_INTERACT. Read by the cursor/interact usability gate (decision 0243).
+    /// `GAMEOBJECT_FLAGS`: `0x1` in use, `0x4` needs the quest activate bit, `0x10` no interact.
     pub fn gameobject_flags(&self) -> u32 {
         self.get_u32(FIELD_GAMEOBJECT_FLAGS).unwrap_or(0)
     }
-    /// `GAMEOBJECT_FACTION` — the object's `FactionTemplate.dbc` id, or `0` for "no faction"
-    /// (which the reference resolves as NEUTRAL). The highlightable predicate's faction term reads
-    /// exactly this (`[go+0x110]+0x38`, decision 0764): a GameObject whose template is **hostile to
-    /// the player** is not highlightable, so it shows no cursor, no tooltip and no hover brighten.
+    /// `GAMEOBJECT_FACTION`: the `FactionTemplate.dbc` id, 0 neutral; hostile to the player
+    /// means not highlightable (`[go+0x110]+0x38`): no cursor, tooltip or hover.
     pub fn gameobject_faction(&self) -> u32 {
         self.get_u32(FIELD_GAMEOBJECT_FACTION).unwrap_or(0)
     }
-    /// `GAMEOBJECT_DYN_FLAGS` — the **per-player** dynamic flags; bit `0x1` = `GO_DYNFLAG_LO_ACTIVATE`
-    /// (the sparkle / "usable for me now"), which the server sets from `GameObject::ActivateToQuest`.
-    /// Consulted only when `GAMEOBJECT_FLAGS & INTERACT_COND` is set (decision 0243).
+    /// `GAMEOBJECT_DYN_FLAGS` (per player): `0x1` `GO_DYNFLAG_LO_ACTIVATE`, the sparkle, set by
+    /// `GameObject::ActivateToQuest` and read only under flag `0x4`.
     pub fn gameobject_dynamic_flags(&self) -> u32 {
         self.get_u32(FIELD_GAMEOBJECT_DYN_FLAGS).unwrap_or(0)
     }
-    /// `GAMEOBJECT_LEVEL` — the object's level (vmangos `UpdateFields_1_12_1.h`: `OBJECT_END + 0x10`
-    /// = 22). The lock-refusal toast's required-rank fallback reads it: a skill lock whose
-    /// `Skill[0]` is 0 displays `level × 5` instead (wow-re cursor-system.md §8.8, `0x5f3490`).
-    /// `0` when absent (the create-block zero default).
+    /// `GAMEOBJECT_LEVEL` (field 22): a lock with `Skill[0]` 0 asks for `level * 5` (`0x5f3490`).
     pub fn gameobject_level(&self) -> u32 {
         self.get_u32(FIELD_GAMEOBJECT_LEVEL).unwrap_or(0)
     }
 
-    /// `OBJECT_FIELD_TYPE & TYPEMASK_CONTAINER` — whether this object is a **bag**, not merely an
-    /// item. The reference's own test, byte for byte: `mov ecx,[eax+8]` / `shr ecx,2` /
-    /// `test cl,1` (`0x4c879d`–`0x4c87a6` in `GetInventoryItemCount`, repeated verbatim at
-    /// `0x4c7dbb`–`0x4c7dc4` in `PutItemInBag`). A container's mask carries the ITEM bit too, so
-    /// this is a widening test and not an alternative to it.
-    ///
-    /// `false` when the field is absent — an item whose create block has not landed is not yet
-    /// known to be a bag, and every caller's fallback is the ordinary-item answer.
+    /// `OBJECT_FIELD_TYPE & TYPEMASK_CONTAINER`: a bag, whose mask carries the item bit too; the
+    /// reference's test at `0x4c879d` (`GetInventoryItemCount`) and `0x4c7dbb` (`PutItemInBag`).
     pub fn is_container(&self) -> bool {
         self.get_u32(FIELD_OBJECT_TYPE).unwrap_or(0) & 0x4 != 0
     }
 
-    /// The object's class from the type field (`OBJECT_FIELD_TYPE`), used for `Values`/`Movement`
-    /// updates that carry no separate `TypeId`. Also the reference's own "is this a Player" test
-    /// (`[obj->descriptorBlock[2] + 8] >> 4 & 1`), which is how `CanAttack`/`CanInteract` ask.
+    /// The object's class from `OBJECT_FIELD_TYPE`, for updates with no `TypeId`; the player bit
+    /// `0x10` is the reference's own is-player test (`CanAttack`, `CanInteract`).
     pub fn object_type(&self) -> Option<ObjectType> {
         self.get_u32(FIELD_OBJECT_TYPE).map(|bits| {
             if bits & 0x10 != 0 {
diff --git a/crates/benilla-protocol/src/messages/update_object/fields/tests.rs b/crates/benilla-protocol/src/messages/update_object/fields/tests.rs
index 8b5f8037..882a1dae 100644
--- a/crates/benilla-protocol/src/messages/update_object/fields/tests.rs
+++ b/crates/benilla-protocol/src/messages/update_object/fields/tests.rs
@@ -1,16 +1,13 @@
 use super::*;
 
-/// The 0208 combat/stat indices re-derived from vmangos's own enum arithmetic (`OBJECT_END` =
-/// 6, `UNIT_END` = 188) and chain-locked to the file's two live-tested anchors:
-/// `FIELD_PLAYER_INV_SLOT_HEAD` (486, descriptor-dump verified) and
-/// `FIELD_PLAYER_BUYBACK_PRICE_1` (1226, wow-re byte anchor, decision 0138). If any constant
-/// drifts, this is the tripwire.
+/// The indices re-derived from vmangos's enum arithmetic and chained to two anchors known
+/// independently: `FIELD_PLAYER_INV_SLOT_HEAD` (486, a live descriptor dump) and
+/// `FIELD_PLAYER_BUYBACK_PRICE_1` (1226, the client binary).
 #[test]
 fn combat_stat_indices_chain_to_the_tested_anchors() {
     const OBJECT_END: u16 = 6;
     const UNIT_END: u16 = OBJECT_END + 0xB6; // UpdateFields_1_12_1.h
     assert_eq!(UNIT_END, 188);
-    // The two tested anchors re-derive from the same arithmetic — the chain is sound.
     assert_eq!(FIELD_PLAYER_INV_SLOT_HEAD, UNIT_END + 0x12A);
     assert_eq!(FIELD_PLAYER_BUYBACK_PRICE_1, UNIT_END + 0x40E);
     // UNIT combat block.
@@ -30,8 +27,6 @@ fn combat_stat_indices_chain_to_the_tested_anchors() {
     assert_eq!(FIELD_UNIT_RANGED_ATTACK_POWER_MULTIPLIER, OBJECT_END + 0xA4);
     assert_eq!(FIELD_UNIT_MINRANGEDDAMAGE, OBJECT_END + 0xA5);
     assert_eq!(FIELD_UNIT_MAXRANGEDDAMAGE, OBJECT_END + 0xA6);
-    // The rested-XP pool sits exactly one below the tested COINAGE anchor, and exactly one past
-    // the explored-zones bitset's 64 slots (decision 1082).
     assert_eq!(FIELD_PLAYER_REST_STATE_EXPERIENCE, UNIT_END + 0x3DB);
     assert_eq!(
         FIELD_PLAYER_REST_STATE_EXPERIENCE + 1,
@@ -41,9 +36,7 @@ fn combat_stat_indices_chain_to_the_tested_anchors() {
         FIELD_PLAYER_EXPLORED_ZONES_1 + PLAYER_EXPLORED_ZONES_SLOTS,
         FIELD_PLAYER_REST_STATE_EXPERIENCE
     );
-    // PLAYER stat block: POSSTAT0 sits one past the tested COINAGE, and the run through
-    // AMMO_ID lands three shy of the tested BUYBACK_PRICE_1 (BYTES 1222, SELF_RES 1224,
-    // PVP_MEDALS 1225 between).
+    // The stat block runs past COINAGE to AMMO_ID 1223; SELF_RES and PVP_MEDALS fill 1224-1225.
     assert_eq!(FIELD_PLAYER_POSSTAT0, FIELD_PLAYER_FIELD_COINAGE + 1);
     assert_eq!(FIELD_PLAYER_POSSTAT0, UNIT_END + 0x3DD);
     assert_eq!(FIELD_PLAYER_NEGSTAT0, UNIT_END + 0x3E2);
@@ -56,18 +49,14 @@ fn combat_stat_indices_chain_to_the_tested_anchors() {
     assert_eq!(FIELD_PLAYER_AMMO_ID + 3, FIELD_PLAYER_BUYBACK_PRICE_1);
     assert_eq!(FIELD_PLAYER_FIELD_BYTES, UNIT_END + 0x40A);
     assert_eq!(FIELD_PLAYER_FIELD_BYTES + 1, FIELD_PLAYER_AMMO_ID);
-    // The watched reputation slot, anchored off the tested COINAGE the same way everything in the
-    // PLAYER block is: 0x431 − 0x3DC = 85 dwords above it.
+    // The watched-faction slot is 0x431 - 0x3DC = 85 dwords above COINAGE.
     assert_eq!(FIELD_PLAYER_WATCHED_FACTION_INDEX, UNIT_END + 0x431);
     assert_eq!(
         FIELD_PLAYER_WATCHED_FACTION_INDEX,
         FIELD_PLAYER_FIELD_COINAGE + 85
     );
-    // Far sight is the guid pair immediately before the combo-target pair, which is itself the two
-    // dwords before the live-tested XP pair — so it is chain-locked from BOTH ends against tested
-    // anchors and needs none of its own: keyring 648 +64 = 712, +2 combo 714, +2 XP 716. Worth
-    // asserting because vmangos's hex comment for this field reads 0x2C2 = 706, six low (the same
-    // drift as COINAGE/XP); its enum arithmetic, which is what the server compiles, agrees with us.
+    // Keyring 648 + 64 = far sight 712, + 2 combo target 714, + 2 XP 716. vmangos's hex comment
+    // for far sight says 0x2C2 = 706, six low; its enum arithmetic is what compiles.
     assert_eq!(FIELD_PLAYER_FARSIGHT, UNIT_END + 0x20C);
     assert_eq!(
         FIELD_PLAYER_FARSIGHT,
@@ -75,31 +64,24 @@ fn combat_stat_indices_chain_to_the_tested_anchors() {
         "far sight closes the 32-slot keyring array"
     );
     assert_eq!(FIELD_PLAYER_FARSIGHT + 2, FIELD_PLAYER_FIELD_COMBO_TARGET);
-    // The combo-target GUID is the two dwords immediately BEFORE the live-tested XP pair, so it
-    // needs no anchor of its own. The binary agrees from the other side: `GetComboPoints 0x51a190`
-    // reads it at `[player+0xe68]+0x838`, and 0x838/4 = 0x20E (decision 0875).
+    // `GetComboPoints` (`0x51a190`) reads the combo target at `[player+0xe68]+0x838`, and
+    // 0x838 / 4 = 0x20E.
     assert_eq!(FIELD_PLAYER_FIELD_COMBO_TARGET, UNIT_END + 0x20E);
     assert_eq!(FIELD_PLAYER_FIELD_COMBO_TARGET + 2, FIELD_PLAYER_XP);
-    // The skill array: one past the tested XP pair, 384 dwords ending at CHARACTER_POINTS1.
+    // The skill array is 128 slots of 3 dwords.
     assert_eq!(FIELD_PLAYER_SKILL_INFO_1_1, FIELD_PLAYER_NEXT_LEVEL_XP + 1);
     assert_eq!(FIELD_PLAYER_SKILL_INFO_1_1, UNIT_END + 0x212);
     assert_eq!(FIELD_PLAYER_SKILL_INFO_1_1 + 384, UNIT_END + 0x392);
-    // The character-points pair sits exactly there (UNIT_END + 0x392/0x393; decision 0304).
     assert_eq!(
         FIELD_PLAYER_CHARACTER_POINTS1,
         FIELD_PLAYER_SKILL_INFO_1_1 + 384
     );
     assert_eq!(FIELD_PLAYER_CHARACTER_POINTS2, UNIT_END + 0x393);
-    // The tracking-mask pair sits contiguously past it (UNIT_END + 0x394/0x395).
     assert_eq!(
         FIELD_PLAYER_TRACK_CREATURES,
         FIELD_PLAYER_CHARACTER_POINTS2 + 1
     );
     assert_eq!(FIELD_PLAYER_TRACK_RESOURCES, UNIT_END + 0x395);
-    // The honor block (decision 1512) is eleven contiguous fields filling EXACTLY the gap between
-    // two already-anchored neighbours — the 12-slot buyback-timestamp array below it and the
-    // watched-faction slot above it — so it needs no anchor of its own. If any of the three ever
-    // drifts, one of these two closures breaks.
     assert_eq!(
         FIELD_PLAYER_BUYBACK_TIMESTAMP_1 + 12,
         FIELD_PLAYER_FIELD_SESSION_KILLS,
@@ -127,8 +109,7 @@ fn combat_stat_indices_chain_to_the_tested_anchors() {
     assert_eq!(FIELD_PLAYER_FIELD_LAST_WEEK_CONTRIBUTION, UNIT_END + 0x42E);
     assert_eq!(FIELD_PLAYER_FIELD_LAST_WEEK_RANK, UNIT_END + 0x42F);
     assert_eq!(FIELD_PLAYER_FIELD_BYTES2, UNIT_END + 0x430);
-    // The CURRENT rank rides the appearance dword instead, nowhere near that block — which is the
-    // whole point: PLAYER_BYTES_3 is PUBLIC, so it is the one honor value a foreign player streams.
+    // The current rank rides the public PLAYER_BYTES_3, outside the honor block.
     assert_eq!(FIELD_PLAYER_BYTES_3, UNIT_END + 0x7);
 }
 
@@ -153,8 +134,8 @@ fn unit_stats_and_resistances_read_indexed_and_gate_range() {
 
 #[test]
 fn attack_power_mods_split_signed_halves() {
-    // vmangos SetInt16Value(index_mod, 0, pos) / (index_mod, 1, neg): lo = positive,
-    // hi = negative (already negative-or-zero). pos 30, neg −10.
+    // vmangos `SetInt16Value(index_mod, 0, pos)` and `(index_mod, 1, neg)`: low positive, high
+    // negative. pos 30, neg -10.
     let packed = u32::from(30u16) | (u32::from((-10i16) as u16) << 16);
     let f = ObjectFields::from_pairs(&[
         (165, 78),                              // ATTACK_POWER
@@ -170,7 +151,6 @@ fn attack_power_mods_split_signed_halves() {
     assert_eq!(f.unit_ranged_attack_power(), Some(52));
     assert_eq!(f.unit_ranged_attack_power_mods(), (0, -3));
     assert_eq!(f.unit_ranged_attack_power_multiplier(), Some(0.0));
-    // Absent mods read (0, 0) — the descriptor's zero-initialized default.
     assert_eq!(ObjectFields::default().unit_attack_power_mods(), (0, 0));
 }
 
@@ -199,10 +179,8 @@ fn damage_and_attack_time_fields_read_their_slots() {
     assert_eq!(f.unit_max_ranged_damage(), Some(47.0));
 }
 
-/// The four stat/resistance buff-split arrays are **INT** on the wire (decision 1397), not the
-/// f32 the server keeps internally — `BuildValuesUpdate` narrows them on the way out. The words
-/// below are the ones a real 5875 server sends; the `-4` case is the x86 host's two's-complement
-/// word (an arm64 host saturates the same debuff to a flat `0` — both decode correctly as `i32`).
+/// The buff-split arrays are ints on the wire, narrowed from the server's floats by
+/// `BuildValuesUpdate`; `-4` is an x86 server's word, where arm64 would send 0.
 #[test]
 fn player_stat_buff_arrays_read_signed_ints() {
     let f = ObjectFields::from_pairs(&[
@@ -219,8 +197,7 @@ fn player_stat_buff_arrays_read_signed_ints() {
     assert_eq!(f.player_resistance_buff_neg(2), Some(-20));
     assert_eq!(f.player_resistance_buff_pos(7), None, "out of range");
     assert_eq!(f.player_resistance_buff_neg(7), None, "out of range");
-    // The regression this decode is: a `105` POSSTAT read as f32 rounds to 0, which is what made
-    // every gear-boosted stat on the character sheet render plain white (B165/B251).
+    // A live value: 105 read as an f32 bit pattern would be near 0.
     let live = ObjectFields::from_pairs(&[(1177, 105)]);
     assert_eq!(live.player_posstat(0), Some(105));
 }
@@ -231,7 +208,7 @@ fn player_mod_damage_done_reads_int_pos_neg_and_float_pct() {
         (1201, 25),                   // MOD_DAMAGE_DONE_POS[0] physical
         (1203, 40),                   // MOD_DAMAGE_DONE_POS[2] fire
         (1208, 15u32.wrapping_neg()), // MOD_DAMAGE_DONE_NEG[0] = −15
-        (1215, 1.1f32.to_bits()),     // MOD_DAMAGE_DONE_PCT[0] — a true float
+        (1215, 1.1f32.to_bits()),     // MOD_DAMAGE_DONE_PCT[0], a true float
     ]);
     assert_eq!(f.player_mod_damage_done_pos(0), Some(25));
     assert_eq!(f.player_mod_damage_done_pos(2), Some(40));
@@ -245,8 +222,8 @@ fn player_mod_damage_done_reads_int_pos_neg_and_float_pct() {
 
 #[test]
 fn player_skill_unpacks_the_three_dword_triplet() {
-    // Slot 1 (base 718 + 3 = 721): Swords (43) step 0, 25/300, temp −3 / perm +5 —
-    // MAKE_PAIR32 lo|hi packing throughout, bonuses signed (Player.cpp:94-100).
+    // Slot 1 (718 + 3 = 721): Swords (43) step 0, 25/300, temp -3, perm +5; lo|hi pairs,
+    // bonuses signed (`Player.cpp:94-100`).
     let f = ObjectFields::from_pairs(&[
         (721, 43),
         (722, 25 | (300 << 16)),
@@ -263,8 +240,6 @@ fn player_skill_unpacks_the_three_dword_triplet() {
             perm_bonus: 5,
         })
     );
-    // A never-streamed slot → None; a zeroed (server-cleared) slot → Some with id 0;
-    // out of range → None.
     assert_eq!(f.player_skill(0), None);
     assert_eq!(
         ObjectFields::from_pairs(&[(718, 0)])
@@ -284,9 +259,8 @@ fn player_ammo_id_reads_the_field() {
 
 #[test]
 fn player_self_res_spell_collapses_absent_and_zero() {
-    // 1224 sits one past PLAYER_AMMO_ID(1223), which is one past PLAYER_FIELD_BYTES(1222) — the
-    // run this test pins by neighbour so a mis-derived index shows up as a wrong reading, not a
-    // silent None. A rank-1 soulstone's effect spell is 3026 (decision 1746).
+    // 1224 follows AMMO_ID 1223 and FIELD_BYTES 1222, all set so a wrong index reads a
+    // neighbour. 3026 is the rank-1 soulstone's effect spell.
     let f = ObjectFields::from_pairs(&[(1222, 0), (1223, 0), (1224, 3026)]);
     assert_eq!(f.player_self_res_spell(), Some(3026));
     assert_eq!(
@@ -294,8 +268,6 @@ fn player_self_res_spell_collapses_absent_and_zero() {
         Some(0),
         "the neighbour is not disturbed"
     );
-    // "No self-res" reaches us two ways — the field never streamed, or the server zeroed it on a
-    // resurrection by another means — and they are the same fact, so both read None.
     assert_eq!(ObjectFields::default().player_self_res_spell(), None);
     assert_eq!(
         ObjectFields::from_pairs(&[(1224, 0)]).player_self_res_spell(),
@@ -305,10 +277,8 @@ fn player_self_res_spell_collapses_absent_and_zero() {
 
 #[test]
 fn player_field_bytes_splits_into_combo_points_toggles_and_honor_rank() {
-    // flags=0x01 / combo=0x02 / actionBars=0x03 / highestHonorRank=5 packed little-endian: the
-    // dword's three live readers take bytes 1, 2 and 3 without bleeding into each other. The
-    // offsets are the binary's own — the reads sit at `[[player+0xe68]+0x1029/0x102a/0x102b]`
-    // (wow-re `action-bar-toggles.md` §4), i.e. bytes 1/2/3 of field 1222.
+    // Bytes 0-3: flags 0x01, combo 2, action bars 3, highest rank 5; the client reads bytes 1-3
+    // of field 1222 at `[[player+0xe68]+0x1029..0x102b]`.
     let f = ObjectFields::from_pairs(&[(1222, 0x05_03_02_01)]);
     assert_eq!(f.player_honor_rank(), Some(5));
     assert_eq!(f.player_action_bar_toggles(), Some(3));
@@ -318,8 +288,7 @@ fn player_field_bytes_splits_into_combo_points_toggles_and_honor_rank() {
     assert_eq!(capped.player_combo_points(), Some(5));
     assert_eq!(capped.player_action_bar_toggles(), Some(0));
     assert_eq!(capped.player_honor_rank(), Some(0));
-    // The server may legally hold a high nibble here (it stores the whole byte); the accessor is
-    // the raw byte and does not mask — the four-bit law is the Lua binding's, not the field's.
+    // The accessor returns the raw byte, high nibble included; only the binding masks to 4 bits.
     let high = ObjectFields::from_pairs(&[(1222, 0x00_f5_00_00)]);
     assert_eq!(high.player_action_bar_toggles(), Some(0xf5));
     assert_eq!(ObjectFields::default().player_honor_rank(), None);
@@ -327,13 +296,8 @@ fn player_field_bytes_splits_into_combo_points_toggles_and_honor_rank() {
     assert_eq!(ObjectFields::default().player_combo_points(), None);
 }
 
-/// `PLAYER_BYTES_3` byte 3 is the **current** honor rank, and it shares its dword with the
-/// gender+inebriation low u16 — so the fixture carries a non-zero drunk byte on purpose: a wrong
-/// shift would read `0xA0` (160) as the rank and pass a byte-3-is-zero test.
-///
-/// The pairing with `PLAYER_FIELD_BYTES`' byte 3 is the confusable one and the reason both are
-/// asserted here: current rank (PUBLIC, field 195) vs highest lifetime rank (PRIVATE, field 1222).
-/// A fixture carrying only 195 must answer `None` for the highest rank, not `0`.
+/// The nonzero drunk byte catches a wrong shift; the current rank (field 195) and the highest
+/// rank (field 1222) are separate fields.
 #[test]
 fn player_bytes_3_byte_3_is_the_current_pvp_rank_not_the_highest() {
     // byte 0 = 0x01 gender, byte 1 = 0xA0 drunk, byte 2 = 0x04 city-protector title,
@@ -346,22 +310,19 @@ fn player_bytes_3_byte_3_is_the_current_pvp_rank_not_the_highest() {
         None,
         "the HIGHEST rank is a different field (1222) — absent means absent"
     );
-    // The two really do diverge: a demoted player keeps the higher lifetime rank.
+    // A demoted player keeps the higher lifetime rank.
     let demoted = ObjectFields::from_pairs(&[(195, 0x03_00_00_00), (1222, 0x0B_00_00_00)]);
     assert_eq!(demoted.player_pvp_rank(), Some(3));
     assert_eq!(demoted.player_honor_rank(), Some(11));
     assert_eq!(ObjectFields::default().player_pvp_rank(), None);
 }
 
-/// The four TWO_SHORT kill counters split low = honorable / high = dishonorable
-/// (`MAKE_PAIR32`; vmangos writes SESSION_KILLS as two `SetUInt16Value` halves). The other three
-/// come off vmangos as a whole dword, so their high half is 0 — asserted, because "DK reads 0" is
-/// a property of *this server*, not of the field, and a future capture that shows otherwise is a
-/// finding rather than a regression.
+/// vmangos writes only SESSION_KILLS as two halves; it writes the other three as a whole dword,
+/// so their dishonorable half is 0.
 #[test]
 fn honor_kill_counters_split_into_honorable_and_dishonorable_halves() {
     let f = ObjectFields::from_pairs(&[
-        (1250, 0x0003_0011), // SESSION: 17 HK, 3 DK — both halves live
+        (1250, 0x0003_0011), // SESSION: 17 HK, 3 DK, both halves live
         (1251, 0x0000_0029), // YESTERDAY: 41 HK, whole-dword write ⇒ DK half 0
         (1252, 0x0000_01A4), // LAST_WEEK: 420 HK
         (1253, 0x0000_007B), // THIS_WEEK: 123 HK
@@ -370,11 +331,9 @@ fn honor_kill_counters_split_into_honorable_and_dishonorable_halves() {
     assert_eq!(f.player_yesterday_kills(), Some((41, 0)));
     assert_eq!(f.player_last_week_kills(), Some((420, 0)));
     assert_eq!(f.player_this_week_kills(), Some((123, 0)));
-    // A value that fills the high half of one of the dword-written fields still decodes as a
-    // pair — we carry the descriptor's shape, not vmangos's habit.
+    // A filled high half still decodes: the shape is the descriptor's, not vmangos's habit.
     let both = ObjectFields::from_pairs(&[(1251, 0x0007_0029)]);
     assert_eq!(both.player_yesterday_kills(), Some((41, 7)));
-    // Absent stays absent for every one of the four.
     let empty = ObjectFields::default();
     assert_eq!(empty.player_session_kills(), None);
     assert_eq!(empty.player_yesterday_kills(), None);
@@ -382,8 +341,6 @@ fn honor_kill_counters_split_into_honorable_and_dishonorable_halves() {
     assert_eq!(empty.player_this_week_kills(), None);
 }
 
-/// The INT half of the honor block — three contribution totals, the weekly standing, and the two
-/// lifetime counters — each reading its own index (a swapped constant shows up here).
 #[test]
 fn honor_contributions_standing_and_lifetime_read_their_own_fields() {
     let f = ObjectFields::from_pairs(&[
@@ -392,7 +349,7 @@ fn honor_contributions_standing_and_lifetime_read_their_own_fields() {
         (1256, 12),    // LIFETIME_DISHONORABLE_KILLS
         (1257, 640),   // YESTERDAY_CONTRIBUTION
         (1258, 8_431), // LAST_WEEK_CONTRIBUTION
-        (1259, 57),    // LAST_WEEK_RANK — the STANDING, not an honor rank
+        (1259, 57),    // LAST_WEEK_RANK: the standing, not an honor rank
     ]);
     assert_eq!(f.player_this_week_contribution(), Some(1_250));
     assert_eq!(f.player_lifetime_honorable_kills(), Some(3_907));
@@ -409,14 +366,12 @@ fn honor_contributions_standing_and_lifetime_read_their_own_fields() {
     assert_eq!(empty.player_lifetime_dishonorable_kills(), None);
 }
 
-/// `PLAYER_FIELD_BYTES2` byte 0 is the rank progress bar; bytes 1..3 are a flags byte and two
-/// unknowns, so the fixture sets them to catch a wrong shift.
+/// Bytes 1-3 are a flags byte and two unknowns; the fixture fills them to catch a wrong shift.
 #[test]
 fn player_honor_rank_bar_is_byte_zero_of_player_field_bytes2() {
     let f = ObjectFields::from_pairs(&[(1260, 0xDE_AD_BE_7F)]);
     assert_eq!(f.player_honor_rank_bar(), Some(0x7F));
-    // A negative rank's `uint8(fraction * -255)` wraps rather than clamping — we carry the byte
-    // the wire sent and leave the interpretation to the display edge.
+    // A negative rank's wrapped `uint8(fraction * -255)` is carried as sent.
     assert_eq!(
         ObjectFields::from_pairs(&[(1260, 0x0000_009C)]).player_honor_rank_bar(),
         Some(0x9C)
@@ -424,21 +379,16 @@ fn player_honor_rank_bar_is_byte_zero_of_player_field_bytes2() {
     assert_eq!(ObjectFields::default().player_honor_rank_bar(), None);
 }
 
-/// `PLAYER_FIELD_COMBO_TARGET` reads as one GUID out of its two dwords — the unit the points are
-/// banked on, which the display gate compares against the current target (decision 0875).
 #[test]
 fn player_combo_target_reads_the_guid_pair() {
     let f = ObjectFields::from_pairs(&[(714, 0x1234_5678), (715, 0xF000_0001)]);
     assert_eq!(f.player_combo_target(), 0xF000_0001_1234_5678);
-    // Nothing banked reads as 0 — the same value the current-target global holds with no target,
-    // which is exactly why the binary's plain equality compare needs no null special case.
+    // Nothing banked reads 0, as the current-target global does with no target.
     assert_eq!(ObjectFields::default().player_combo_target(), 0);
 }
 
-/// The four aura arrays tile exactly, and the block lands on `BASEATTACKTIME` — an index this
-/// file already chain-locks to two live-verified anchors. So this pins all four aura indices
-/// without a new anchor of its own: 48 spell-id dwords, then 48 nibbles (6 dwords), then 48
-/// bytes (12 dwords) twice, then `AURASTATE` (+0x77), then `BASEATTACKTIME` (+0x78).
+/// 48 spell-id dwords, 48 nibbles (6 dwords), 48 bytes (12 dwords) twice, `AURASTATE` (+0x77),
+/// then `BASEATTACKTIME` (+0x78), which the first test chains to the anchors.
 #[test]
 fn aura_arrays_tile_from_object_end_onto_the_tested_anchor() {
     const OBJECT_END: u16 = 6;
@@ -469,9 +419,8 @@ fn aura_arrays_tile_from_object_end_onto_the_tested_anchor() {
     );
 }
 
-/// The packing goldens: nibble-per-slot flags (8/dword), byte-per-slot levels and applications
-/// (4/dword, holding `stack - 1`). Slot 32 deliberately omits its applications word — an absent
-/// field must read as the descriptor's zero, i.e. a stack of 1, not a stack of 0.
+/// Flags are a nibble per slot, levels and applications a byte (`stack - 1`); slot 32 has no
+/// applications word, so it reads a stack of 1.
 #[test]
 fn aura_slots_unpack_nibbles_bytes_and_the_stack_bias() {
     let f = ObjectFields::from_pairs(&[
@@ -544,21 +493,16 @@ fn aura_slots_unpack_nibbles_bytes_and_the_stack_bias() {
     assert_eq!(ObjectFields::default().unit_auras().count(), 0);
 }
 
-/// A slot whose flags nibble the server cleared (`& 0x0E == 0`) is **empty**, even if a stale
-/// spell id lingers in `UNIT_FIELD_AURA` — the client's own `flags & 0x0E` liveness test. Gating
-/// on the spell id alone (as an earlier cut did) surfaced the husk as a phantom buff the real
-/// client hides. The cancelable bit `0x1` on its own does not resurrect it (it is not an effect
-/// bit), so this covers both a fully-zeroed nibble and a `0x1`-only one.
+/// The cancelable bit `0x1` alone is no effect bit: a `0x1`-only nibble is as empty as a zero one.
 #[test]
 fn a_stale_spell_id_with_a_cleared_flags_nibble_is_not_a_live_aura() {
     let f = ObjectFields::from_pairs(&[
-        // slot 0: a live buff — spell id + effect bit 0x8.
+        // slot 0: a live buff, spell id and effect bit 0x8.
         (47, 1126),
         (95, 0x0000_0018), // slot 0 nibble 0x8 (eff0), slot 1 nibble 0x1 (cancelable only)
-        // slot 1: a HUSK — the server left the spell id but cleared every effect bit, keeping
-        // only the cancelable bit. `flags & 0x0E == 0`, so it is not live.
+        // slot 1: a stale id with only the cancelable bit.
         (48, 5000),
-        // slot 2: a HUSK — spell id present, flags nibble fully zero.
+        // slot 2: a stale id with a zero nibble.
         (49, 6000),
     ]);
 
@@ -580,10 +524,8 @@ fn a_stale_spell_id_with_a_cleared_flags_nibble_is_not_a_live_aura() {
     );
 }
 
-/// The create-block absent-field semantics (director-caught: fully broken gear read as 100%). A
-/// CREATE omits zero-valued fields (vmangos `_SetCreateBits`: mask bit iff `value != 0`), so a
-/// create-seeded store must answer `Some(0)` for an absent field — the real client's
-/// zero-initialized descriptor — while a bare `Values` delta keeps absent = `None` ("untouched").
+/// A create omits zero fields (vmangos `_SetCreateBits`), so a created store reads absent as 0,
+/// like the client's zeroed descriptor; a bare delta reads it as untouched.
 #[test]
 fn created_store_reads_absent_fields_as_zero_a_delta_as_none() {
     // A broken item's create: MAXDURABILITY present (40), DURABILITY omitted (it is 0).
@@ -595,15 +537,10 @@ fn created_store_reads_absent_fields_as_zero_a_delta_as_none() {
     let delta = ObjectFields::from_pairs(&[(47, 40)]);
     assert_eq!(delta.item_durability(), None, "delta absent = untouched");
 
-    // A guid slot keeps present-iff-low-half semantics even on a created store (consumers
-    // already treat a sent-empty `Some(0)` as no-guid; the fallback would only blur the two).
+    // A guid slot is present only if its low half was sent, even on a created store.
     assert_eq!(create.corpse_owner(), None);
 }
 
-/// The `TYPEID_CORPSE` descriptor's field indices and its two packed words (decision 1706). Every
-/// number here is a *position*, and a position is exactly what a doc comment cannot check: an
-/// off-by-one on `CORPSE_FIELD_ITEM`'s base would read the display id as a shoulder and dress a
-/// body in a helm's row, silently.
 #[test]
 fn corpse_descriptor_indices_and_packing() {
     // `OBJECT_END + 0x6 = 12` display · `+0x7 = 13` item[0] · `+0x1A/0x1B = 32/33` bytes ·
@@ -648,8 +585,7 @@ fn corpse_descriptor_indices_and_packing() {
         "the seven bytes the reference loads at [descr+0x69..+0x6f], in that order"
     );
 
-    // The flags are three independent bits on one field — and BONES is the model fork, so a
-    // mis-read here swaps a dressed body for a skeleton.
+    // Three independent bits; BONES picks the skeleton model.
     assert!(!corpse.corpse_is_bones(), "0x01 clear");
     assert!(corpse.corpse_hides_helm(), "0x08 set");
     assert!(!corpse.corpse_hides_cloak(), "0x10 clear");
@@ -658,7 +594,7 @@ fn corpse_descriptor_indices_and_packing() {
         "DYNAMIC_FLAGS bit 0 — a different field"
     );
 
-    // …and CORPSE_END = 38, so a created corpse answers 0 (not None) for every field below it.
+    // CORPSE_END is 38, so a created corpse reads 0, not None, for every field below it.
     let bare = ObjectFields::from_pairs(&[(12, 49)]).into_created(ObjectType::Corpse);
     assert_eq!(bare.corpse_flags(), 0);
     assert!(
@@ -668,19 +604,13 @@ fn corpse_descriptor_indices_and_packing() {
     assert!(!bare.corpse_lootable());
 }
 
-/// …and "absent = 0" stops at the end of the object's OWN descriptor (decision 1081). A creature
-/// has no PLAYER block to be absent from, so a PLAYER-block read off one is `None` — a question it
-/// cannot answer — not a confident `0`.
-///
-/// The live bug: `unit_combat_stats` reads `PLAYER_FIELD_MOD_DAMAGE_DONE_PCT` for any unit and
-/// defaults an absent answer to the divide-safe `1.0`. With a created pet answering `Some(0.0)`,
-/// the default never fired and the ref's `damage / percent` produced the pet sheet's
-/// `inf - inf` / `nan` tooltip and its red damage line (director, 2026-08-07).
+/// Absent reads 0 only inside the object's own descriptor: a creature has no player block, so a
+/// player-block read off one is `None`.
 #[test]
 fn a_creature_has_no_player_block_to_be_absent_from() {
-    // PLAYER_FIELD_MOD_DAMAGE_DONE_PCT[0] = UNIT_END(188) + 0x403 — past a UNIT's descriptor end.
+    // PLAYER_FIELD_MOD_DAMAGE_DONE_PCT[0] = UNIT_END(188) + 0x403, past a unit's descriptor.
     const MOD_DAMAGE_DONE_PCT: u16 = 1215;
-    // UNIT_FIELD_BASEATTACKTIME — well inside it.
+    // UNIT_FIELD_BASEATTACKTIME, well inside it.
     const BASEATTACKTIME: u16 = 126;
 
     let pet = ObjectFields::from_pairs(&[(2, 0x09), (150, 33)]).into_created(ObjectType::Unit);
@@ -696,28 +626,25 @@ fn a_creature_has_no_player_block_to_be_absent_from() {
     );
     assert_eq!(pet.unit_stat(0), Some(33), "and a present field is itself");
 
-    // The same index on a real player: inside the descriptor, so absent is the honest 0 the
-    // client's own zero-initialized buffer holds.
+    // On a player the same index is inside the descriptor, so absent reads 0.
     let player = ObjectFields::from_pairs(&[(2, 0x19), (BASEATTACKTIME, 1800)])
         .into_created(ObjectType::Player);
     assert_eq!(player.player_mod_damage_done_pct(0), Some(0.0));
     assert_eq!(player.unit_base_attack_time(0), Some(1800));
 
-    // A bare delta answers nothing either way — it never claimed to be complete.
+    // A bare delta reads absent as None either way.
     let delta = ObjectFields::from_pairs(&[(MOD_DAMAGE_DONE_PCT, 1.0f32.to_bits())]);
     assert_eq!(delta.player_mod_damage_done_pct(0), Some(1.0));
     assert_eq!(delta.unit_base_attack_time(0), None);
 }
 
-/// Merging keeps the semantics straight: a delta overlays a created store without unsetting the
-/// created mark, and a re-CREATE *replaces* the store — stale non-zero values for fields the
-/// fresh snapshot omits (they dropped to zero out of view) must die with it.
+/// A re-create replaces the store, so a field that dropped to 0 out of view does not survive.
 #[test]
 fn merge_overlays_deltas_and_replaces_on_recreate() {
     let mut store =
         ObjectFields::from_pairs(&[(3, 2264), (46, 40), (47, 40)]).into_created(ObjectType::Item);
 
-    // A durability-damage delta overlays; the store stays a complete (created) descriptor.
+    // A durability delta overlays; the store stays created.
     store.merge(ObjectFields::from_pairs(&[(46, 30)]));
     assert_eq!(store.item_durability(), Some(30));
     assert_eq!(
@@ -735,10 +662,8 @@ fn merge_overlays_deltas_and_replaces_on_recreate() {
     );
 }
 
-/// The field edges a merge reports (decision 2297) — the reference's per-field notifier, whose
-/// callback fires on a memcmp DIFFERENCE and receives the old value: only the dwords that moved,
-/// ascending, absent reading as `0` on either side, and a value re-sent unchanged reporting
-/// nothing at all.
+/// Like the reference's per-field notifier, which fires on a memcmp difference with the old
+/// value: moved dwords only, ascending, absent as 0, an unchanged resend silent.
 #[test]
 fn merge_diff_reports_each_moved_dword_once_with_its_old_value() {
     let mut store =
@@ -758,9 +683,8 @@ fn merge_diff_reports_each_moved_dword_once_with_its_old_value() {
     assert_eq!(store.unit_flags(), 8);
 }
 
-/// A re-CREATE is the reference's in-place refresh of a live guid — it notifies too, and here it
-/// notifies over BOTH masks: a field the fresh snapshot omits dropped to zero, and that is an edge
-/// the store's replace makes visible (`merge_overlays_deltas_and_replaces_on_recreate` above).
+/// A re-create refreshes a live guid in place and notifies over both masks: an omitted field is
+/// an edge to 0.
 #[test]
 fn merge_diff_on_a_recreate_reports_the_replace_on_both_masks() {
     let mut store =
@@ -778,9 +702,6 @@ fn merge_diff_on_a_recreate_reports_the_replace_on_both_masks() {
     assert_eq!(store.item_durability(), Some(0));
 }
 
-/// The class a store was created as reads back off its length — every class round-trips, and a
-/// bare delta (no create seen) answers nothing, which is what keeps a field edge honest about
-/// which block its index belongs to.
 #[test]
 fn created_as_reads_back_off_the_created_length() {
     for t in [
@@ -801,14 +722,13 @@ fn created_as_reads_back_off_the_created_length() {
     assert_eq!(ObjectFields::from_pairs(&[(22, 1)]).created_as(), None);
 }
 
-/// The `DYNAMICOBJECT_*` accessors against the exact live capture (vmangos, 2026-07-30, the
-/// B132 follow-up's `--groundfx 10` run): Blizzard's dynobj create — caster guid 26, BYTES 1
-/// (area spell), SPELLID 10, RADIUS 8.0, the cast point in POS, FACING never sent.
+/// A live vmangos capture of a Blizzard (spell 10) dynamic-object create: caster guid 26, area
+/// spell, radius 8.0, the cast point in POS, FACING never sent.
 #[test]
 fn dynamicobject_fields_read_the_live_blizzard_capture() {
     let f = ObjectFields::from_pairs(&[
         (0, 6),                        // OBJECT_FIELD_GUID lo
-        (1, 0xf100_0000),              // guid hi — HIGHGUID dynobj
+        (1, 0xf100_0000),              // guid hi, HIGHGUID dynobj
         (2, 0x41),                     // TYPE: OBJECT | DYNAMICOBJECT
         (3, 10),                       // ENTRY = the spell id
         (4, 1.0f32.to_bits()),         // SCALE_X
@@ -835,12 +755,8 @@ fn dynamicobject_fields_read_the_live_blizzard_capture() {
     );
 }
 
-/// **Feign death is one bit, and the client reads it everywhere it reads health** (decision 1022).
-/// `UNIT_DYNFLAG_DEAD` leaves `UNIT_FIELD_HEALTH` alone — vmangos `Unit::SetFeignDeath` only sets
-/// the flag — so every predicate that keys on the raw field must stay FALSE while every one that
-/// keys on how the unit *reads* must flip. The byte law being transcribed: `UnitHealth 0x5174d0`
-/// and `UnitMana 0x517670` answer 0 under the flag, their `*Max` siblings (`0x5175b0`/`0x5177e0`)
-/// have no such gate, and `0x605f90` is the shared reads-dead triple.
+/// `Unit::SetFeignDeath` sets only `UNIT_DYNFLAG_DEAD`: the raw predicates stay false, the
+/// reads-dead ones (`0x605f90`, `UnitHealth`, `UnitMana`) flip, and the maxima stay.
 #[test]
 fn feign_death_reads_dead_without_touching_the_raw_health_field() {
     const MANA: u8 = 0;
@@ -860,14 +776,13 @@ fn feign_death_reads_dead_without_touching_the_raw_health_field() {
     ]);
     let corpse = unit(&[(FIELD_UNIT_HEALTH, 0), (FIELD_UNIT_MAXHEALTH, 1500)]);
 
-    // The raw field predicate is untouched by the flag — the death arc, loot and the corpse never
-    // fire for a feign.
+    // The raw predicate ignores the flag.
     assert!(!alive.unit_is_dead());
     assert!(!feigning.unit_is_dead(), "feign leaves HEALTH alone");
     assert!(corpse.unit_is_dead());
     assert_eq!(feigning.unit_health(), Some(1200), "the raw field survives");
 
-    // …and the reads-dead predicate flips for both, plus the stand-state leg.
+    // The reads-dead predicate flips for both, plus the stand-state leg.
     assert!(!alive.unit_reads_dead());
     assert!(feigning.unit_reads_dead(), "0x605f9d — the dynflag leg");
     assert!(corpse.unit_reads_dead());
@@ -881,26 +796,22 @@ fn feign_death_reads_dead_without_touching_the_raw_health_field() {
         "0x605faa — stand state 7 (inert against vmangos, kept as the reference has it)"
     );
 
-    // The UI getters: current goes to zero, the maxima do not — that is what makes the bar render
-    // 0/max (empty) instead of vanishing.
+    // Current values go to 0 and the maxima stay, so the bar shows empty.
     assert_eq!(alive.unit_shown_health(), Some(1200));
     assert_eq!(feigning.unit_shown_health(), Some(0));
     assert_eq!(feigning.unit_max_health(), Some(1500));
     assert_eq!(alive.unit_shown_power(MANA), Some(300));
     assert_eq!(feigning.unit_shown_power(MANA), Some(0));
     assert_eq!(feigning.unit_max_power(MANA), Some(900));
-    // Out-of-range power slots stay nil under the flag, exactly as the ungated reader has them.
+    // Out-of-range power slots stay None under the flag, as the ungated reader has them.
     assert_eq!(feigning.unit_shown_power(5), None);
-    // An empty store is not a feigning one: no flag, no zeroing, and no invented health.
+    // An empty store has no flag and no health.
     assert!(!ObjectFields::default().unit_reads_dead());
     assert_eq!(ObjectFields::default().unit_shown_health(), None);
 }
 
-/// **The raw→display power divide** (decision 1034, wow-re `feign-death-dyndead.md` §3): the
-/// reference's `UnitMana`/`UnitManaMax` divide by `0x6e7130`'s table at `0x86f978` —
-/// `{1, 10, 1, 1, 1000}`. vmangos ships rage max **1000** and pet happiness max **1050000**
-/// (`GetCreatePowers`), which through that divide are the 100 and 1050 a real client shows. The
-/// RAW accessors must stay raw: the pet happiness bucket thresholds compare on the wire scale.
+/// vmangos sends rage max 1000 and happiness max 1050000 (`GetCreatePowers`); the table at
+/// `0x86f978` divides them to the 100 and 1050 the reference shows.
 #[test]
 fn rage_and_happiness_divide_for_display_but_not_for_the_raw_readers() {
     const RAGE: u8 = 1;
@@ -930,7 +841,7 @@ fn rage_and_happiness_divide_for_display_but_not_for_the_raw_readers() {
     assert_eq!(pet.unit_shown_power(HAPPINESS), Some(1020));
     assert_eq!(pet.unit_shown_max_power(HAPPINESS), Some(1050));
 
-    // Mana/focus/energy divide by 1 — the shown and raw readers agree.
+    // Mana, focus and energy divide by 1.
     let caster = ObjectFields::from_pairs(&[
         (FIELD_UNIT_POWER1 + u16::from(MANA), 4200),
         (FIELD_UNIT_MAXPOWER1 + u16::from(MANA), 8000),
@@ -940,7 +851,6 @@ fn rage_and_happiness_divide_for_display_but_not_for_the_raw_readers() {
         caster.unit_shown_max_power(MANA),
         caster.unit_max_power(MANA)
     );
-    // Absent stays nil rather than becoming a divided zero.
     assert_eq!(caster.unit_shown_power(RAGE), None);
     assert_eq!(caster.unit_shown_max_power(RAGE), None);
     // The dead gate still wins over the divide, and only for the current value.
diff --git a/crates/benilla-protocol/src/messages/update_object/fields/unit.rs b/crates/benilla-protocol/src/messages/update_object/fields/unit.rs
index b41f2084..73a37796 100644
--- a/crates/benilla-protocol/src/messages/update_object/fields/unit.rs
+++ b/crates/benilla-protocol/src/messages/update_object/fields/unit.rs
@@ -1,54 +1,20 @@
-//! The unit/object/GameObject named accessors over [`ObjectFields`] — the UNIT_* family every
-//! world entity carries (health/power/level/auras/combat stats), plus the object scale and the
-//! GameObject block. Split from the one descriptor map (`mod.rs` holds the indices + codec).
+//! Named accessors over [`ObjectFields`] for the object scale and the unit block.
 
 use super::*;
 
-/// `UNIT_DYNAMIC_FLAGS` bit 5 — `UNIT_DYNFLAG_DEAD` (vmangos `SharedDefines.h:1158`). The client
-/// reads it as "this body is a corpse" wherever it reads health for display; the server sets it for
-/// **feign death** and for `CREATURE_FLAG_EXTRA_APPEAR_DEAD` spawns, in both cases with health left
-/// intact. Every consumer goes through [`ObjectFields::unit_reads_dead`] (decision 1022).
+/// `UNIT_DYNAMIC_FLAGS` bit 5 (`SharedDefines.h:1158`): reads as a corpse wherever health is
+/// shown; set for feign death and appear-dead spawns, with health left intact.
 pub const UNIT_DYNFLAG_DEAD: u32 = 0x20;
 
-/// `UNIT_STAND_STATE_DEAD` (vmangos `UnitDefines.h:109`) — the third leg of the client's
-/// reads-dead predicate `0x605f90`. vmangos never writes it, so it is inert against our server.
-///
-/// The client reads it through the virtual `[vtbl+0xa4]`, and the **two classes install different
-/// functions there** — `CGUnit_C` `0x60be50`, `CGPlayer_C` `0x5ed570` (memoised at `[this+0x1d68]`
-/// for the local player) — but both return the same byte, `[descr+0x210]` = `UNIT_FIELD_BYTES_1`
-/// byte 0, which is exactly what [`ObjectFields::unit_stand_state`] reads (wow-re
-/// `feign-death-dyndead.md` §1).
+/// `UNIT_STAND_STATE_DEAD` (`UnitDefines.h:109`), the third leg of `0x605f90`; vmangos never
+/// writes it. Both `[vtbl+0xa4]` overrides (`0x60be50`, `0x5ed570`) read `UNIT_FIELD_BYTES_1`
+/// byte 0.
 const STAND_STATE_DEAD: u8 = 7;
 
-/// The raw→display divisor per power type — the reference's `0x6e7130`, a lookup into the table at
-/// `0x86f978`: **`{1, 10, 1, 1, 1000}`** for MANA / RAGE / FOCUS / ENERGY / HAPPINESS, with `1` for
-/// any out-of-range type (`test ecx,ecx; jl → 1`). Rage is stored ×10 on the wire and pet happiness
-/// ×1000 (vmangos `GetCreatePowers`: `POWER_RAGE → 1000`, `POWER_HAPPINESS → 1050000`), so the real
-/// client's 100 rage and 1050 happiness are this divide, not a different field.
-///
-/// **This is a whole-client law, not one getter's private step** (decision 2117). `0x6e7130` is
-/// called from *every* place a power figure becomes something a player reads, and the wire number
-/// is raw at all of them:
-///
-/// | caller | what it scales |
-/// |---|---|
-/// | `UnitMana 0x517670` (`0x51770f`), `UnitManaMax 0x5177e0` (`0x517864`) | the live descriptor's power slot |
-/// | the same pair's party-record legs (`0x517748`, `0x5178a8`, `0x5178ee`) | [`crate::messages::PartyMemberStatsInfo::shown_power`] (decision 1640) |
-/// | `SMSG_SPELLENERGIZELOG`'s handler `0x5e8a90` (`0x5e8af3`) | the amount, **once**, before both the chat line (`0x62ca00`) and the `COMBAT_TEXT_UPDATE` push (`0x494770`) |
-/// | `SMSG_PERIODICAURALOG`'s handler `0x626dd0` (`0x627087`) | an energize tick's amount, the same way |
-/// | the power leech/drain formatter `0x627930` | `drained = amount / div` and `gained = trunc(amount·multiplier) / div` |
-/// | the spell tooltip's cost cell `0x52e610` (`0x52e8d2`, `0x52e8e7`) | the flat and per-level costs alike |
-///
-/// (wow-re `system/object-layer/scratch/combat-log-chat-law.md` §4.6 — *"Amounts are divided by
-/// `0x6e7130(powerType)`"* — plus the disassembly at each address above.)
-///
-/// The **raw** accessors stay raw: the pet happiness bucket thresholds are on the raw scale, which
-/// is why both forms have to exist (decision 1034).
-///
-/// The argument is a full 32-bit power tag because the wire's is (`SMSG_SPELLENERGIZELOG` ships a
-/// `u32`) and because the reference's own compare is signed — `POWER_HEALTH (-2)` reaches
-/// `0x6e7130` as a negative and takes the `1`. Arriving here as a large `u32` it takes the same
-/// `1` off the same `_` arm.
+/// The reference's raw-to-shown power divisor (`0x6e7130`, table `0x86f978`): 10 for rage, 1000
+/// for pet happiness, 1 for any other type, `POWER_HEALTH` (-2) included. Every power figure a
+/// player reads divides by it: `UnitMana`, `UnitManaMax`, party power, the energize and periodic
+/// logs, the drain formatter and the spell cost; happiness thresholds stay on the raw scale.
 pub fn power_display_scale(ty: u32) -> u32 {
     match ty {
         1 => 10,   // rage
@@ -57,19 +23,18 @@ pub fn power_display_scale(ty: u32) -> u32 {
     }
 }
 
-/// Which field [`ObjectFields::unit_owner`] falls back to when `CHARMEDBY` is clear — the one
-/// thing the client's two owner-guid readers do differently. Named rather than defaulted because
-/// picking the wrong one is invisible until a totem or a guardian behaves like a pet.
+/// The field [`ObjectFields::unit_owner`] falls back to when `CHARMEDBY` is clear, the one thing
+/// the client's two owner readers do differently.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum OwnerFallback {
-    /// `UNIT_FIELD_CREATEDBY` — what `0x5ee5a0` ("resolve my own pet") uses.
+    /// `UNIT_FIELD_CREATEDBY`, as the own-pet resolver `0x5ee5a0` reads.
     CreatedBy,
-    /// `UNIT_FIELD_SUMMONEDBY` — what the `PET_ATTACK_*` callback `0x5ff580` uses.
+    /// `UNIT_FIELD_SUMMONEDBY`, as the `PET_ATTACK_*` callback `0x5ff580` reads.
     SummonedBy,
 }
 
 impl ObjectFields {
-    /// `OBJECT_FIELD_SCALE_X` — the per-object size multiplier.
+    /// `OBJECT_FIELD_SCALE_X`: the per-object size multiplier.
     pub fn object_scale_x(&self) -> Option<f32> {
         self.get_f32(FIELD_OBJECT_SCALE_X)
     }
@@ -77,191 +42,119 @@ impl ObjectFields {
     pub fn unit_displayid(&self) -> Option<i32> {
         self.get_i32(FIELD_UNIT_DISPLAYID)
     }
-    /// `UNIT_FIELD_NATIVEDISPLAYID` (units + players) — the unit's **unshifted** appearance, which
-    /// no transform touches. The collision prism is derived from *this*, not from
-    /// [`Self::unit_displayid`]: a druid in bear form keeps the druid's swim/splash/foam lines
-    /// (decision 1574). `None` when absent — the caller falls back to the render display.
+    /// `UNIT_FIELD_NATIVEDISPLAYID`: the appearance no shapeshift touches; the collision prism
+    /// comes from it, so a druid in bear form keeps the druid's water lines.
     pub fn unit_native_displayid(&self) -> Option<i32> {
         self.get_i32(FIELD_UNIT_NATIVEDISPLAYID)
     }
-    /// `UNIT_FIELD_MOUNTDISPLAYID` — the `CreatureDisplayInfo` id of the mount this unit rides;
-    /// `0` (or absent) = not mounted. The one and only mounted signal on the wire (decision 0441).
+    /// `UNIT_FIELD_MOUNTDISPLAYID`: the mount's `CreatureDisplayInfo` id, the only mounted signal.
     pub fn unit_mount_display_id(&self) -> u32 {
         self.get_u32(FIELD_UNIT_MOUNTDISPLAYID).unwrap_or(0)
     }
-    /// `UNIT_FIELD_TARGET` — the guid this unit is attacking/interacting with (its "look at" target),
-    /// or `None` when it has none (an absent field or an explicit `0`). Drives the idle face-target turn.
+    /// `UNIT_FIELD_TARGET`: the guid this unit is attacking or interacting with.
     pub fn unit_target(&self) -> Option<u64> {
         self.get_guid(FIELD_UNIT_TARGET).filter(|&g| g != 0)
     }
-    /// `UNIT_FIELD_CHANNEL_OBJECT` — the object a channel is aimed at (may be the caster itself),
-    /// or `None` when not channeling (an absent field or an explicit `0`).
+    /// `UNIT_FIELD_CHANNEL_OBJECT`: what a channel is aimed at, possibly the caster itself.
     pub fn unit_channel_object(&self) -> Option<u64> {
         self.get_guid(FIELD_UNIT_CHANNEL_OBJECT).filter(|&g| g != 0)
     }
-    /// `UNIT_CHANNEL_SPELL` — the spell id a unit is channeling; `0` when not channeling or absent.
+    /// `UNIT_CHANNEL_SPELL`: the spell being channelled, 0 for none.
     pub fn unit_channel_spell(&self) -> u32 {
         self.get_u32(FIELD_UNIT_CHANNEL_SPELL).unwrap_or(0)
     }
-    /// `UNIT_FIELD_SUMMON` — the guid of the unit this one has summoned, or `None`. On our own
-    /// descriptor that is **our pet**, and so the anchor of the `"pet"` unit token (decision 0982).
-    /// The inverse of [`Self::unit_summoned_by`].
+    /// `UNIT_FIELD_SUMMON`: the unit this one summoned; on our own descriptor, the `"pet"` unit.
     pub fn unit_summon(&self) -> Option<u64> {
         self.get_guid(FIELD_UNIT_SUMMON).filter(|&g| g != 0)
     }
-    /// `UNIT_FIELD_SUMMONEDBY` — the summoner's guid (pet/guardian/totem), or `None` (absent or
-    /// explicit 0 — an unowned unit).
+    /// `UNIT_FIELD_SUMMONEDBY`: the summoner of a pet, guardian or totem.
     pub fn unit_summoned_by(&self) -> Option<u64> {
         self.get_guid(FIELD_UNIT_SUMMONEDBY).filter(|&g| g != 0)
     }
-    /// `UNIT_FIELD_CHARMEDBY` — whoever is charming this unit, or `None` when nobody is.
+    /// `UNIT_FIELD_CHARMEDBY`: whoever is charming this unit.
     pub fn unit_charmed_by(&self) -> Option<u64> {
         self.get_guid(FIELD_UNIT_CHARMEDBY).filter(|&g| g != 0)
     }
-    /// The unit's **owner** as the client's own two owner-guid readers compute it:
-    /// `charmedBy` when set, else the caller's fallback field.
-    ///
-    /// Both readers are `(charmedBy != 0) ? charmedBy : <fallback>` and **they disagree on the
-    /// fallback**, which is why this takes it rather than picking one. `0x5ee5a0` — "resolve my own
-    /// pet" — falls back to `CREATEDBY` (`0x5ee62f`: `fields+0x10` else `fields+0x20`); the
-    /// `PET_ATTACK_*` field-change callback `0x5ff580` falls back to `SUMMONEDBY` (`0x5ff769`:
-    /// `+0x10` else `+0x18`). Reading one where the reference reads the other silently changes
-    /// which units count as yours (wow-re `object-layer/scratch/pet-command-validators.md` §1, §4).
+    /// The owner as the client's owner readers compute it: `CHARMEDBY` if set, else the fallback,
+    /// which differs by caller (`0x5ee62f` reads `CREATEDBY`, `0x5ff769` `SUMMONEDBY`).
     pub fn unit_owner(&self, fallback: OwnerFallback) -> Option<u64> {
         self.unit_charmed_by().or_else(|| match fallback {
             OwnerFallback::CreatedBy => self.unit_created_by(),
             OwnerFallback::SummonedBy => self.unit_summoned_by(),
         })
     }
-    /// `UNIT_FIELD_CREATEDBY` — the creator's guid (totems and created objects), or `None`.
+    /// `UNIT_FIELD_CREATEDBY`: the creator of a totem or created object.
     pub fn unit_created_by(&self) -> Option<u64> {
         self.get_guid(FIELD_UNIT_CREATEDBY).filter(|&g| g != 0)
     }
-    /// `UNIT_CREATED_BY_SPELL` — the spell that summoned this unit, `None` when zero (nothing
-    /// summoned it). The reference's feed-pet validator `0x6ea1e0` requires it non-zero before it
-    /// will accept a unit as a feedable pet — the first of that function's three gates.
+    /// `UNIT_CREATED_BY_SPELL`: the summoning spell; `0x6ea1e0` requires it to feed a pet.
     pub fn unit_created_by_spell(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_CREATED_BY_SPELL)
             .filter(|&s| s != 0)
     }
-    /// `UNIT_FIELD_PETNUMBER` — non-zero iff this unit is somebody's **pet or charm**.
-    ///
-    /// Not a count and not an index anyone displays: the client reads it as a pure boolean, as the
-    /// **second gate of the rank getter** `0x605620` (decision 0782). A creature with a cached
-    /// template but a non-zero pet number reports classification rank `0` — so an enslaved elite
-    /// loses its dragon border, its ELITE tooltip word and (at rank 3) its world-boss skull, all
-    /// three from this one read.
-    ///
-    /// What lands here is the server's call, and vmangos is narrower than the name suggests:
-    /// `CharmInfo::SetPetNumber(n, statWindow)` writes `n` only when `statWindow`, else **0**. So a
-    /// permanent pet (`Pet::IsPermanentPetFor`), a charm/mind-control apply and a player's summon
-    /// carry a non-zero number, while **guardians and totems carry 0** and therefore keep whatever
-    /// rank their template gives them.
+    /// `UNIT_FIELD_PETNUMBER` is nonzero: a pet or charm, which the rank getter `0x605620`
+    /// reports as rank 0. vmangos writes 0 for guardians and totems (`CharmInfo::SetPetNumber`
+    /// without the stat window), so they keep their template's rank.
     pub fn unit_is_pet_or_charm(&self) -> bool {
-        self.get_u32(FIELD_UNIT_PETNUMBER).unwrap_or(0) != 0
+        self.unit_pet_number() != 0
     }
-    /// `UNIT_FIELD_PET_NAME_TIMESTAMP` — when this pet's name was last set. `None` when the field
-    /// has never been sent (a create omits zeros), which reads the same as "never renamed".
-    ///
-    /// The **only** thing to do with the value is compare it with the last one seen: a pet's name
-    /// lives in a query cache keyed by pet number, and this changing is what says that cache has
-    /// gone stale (see the constant).
+    /// `UNIT_FIELD_PETNUMBER`: `GetUnitName` (`0x609210`) keys the pet-name cache on it when
+    /// nonzero; a `HIGHGUID_PET` guid's number is not a substitute, no name query answers it.
+    pub fn unit_pet_number(&self) -> u32 {
+        self.get_u32(FIELD_UNIT_PETNUMBER).unwrap_or(0)
+    }
+    /// `UNIT_FIELD_PET_NAME_TIMESTAMP`: changes when the pet is renamed, staling the name cache.
     pub fn unit_pet_name_timestamp(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_PET_NAME_TIMESTAMP)
     }
-    /// `UNIT_FIELD_HEALTH` — current hit points (0 ⇒ dead).
+    /// `UNIT_FIELD_HEALTH`: current hit points, 0 when dead.
     pub fn unit_health(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_HEALTH)
     }
-    /// `UNIT_FIELD_MAXHEALTH` — full hit points.
+    /// `UNIT_FIELD_MAXHEALTH`: full hit points.
     pub fn unit_max_health(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_MAXHEALTH)
     }
-    /// Whether the unit is **really dead** — health 0 on a real unit, the RAW field predicate.
-    /// Absent health reads as **zero** — a create block only carries *non-zero* fields (vmangos
-    /// `_SetCreateBits`), so an already-dead corpse streams in with `MAXHEALTH` but **no** `HEALTH`
-    /// at all; the real client's descriptor array is zero-initialized, so absent *is* 0 to it. The
-    /// `MAXHEALTH > 0` guard keeps a unit whose snapshot hasn't arrived (empty store) from reading
-    /// as dead.
-    ///
-    /// This is the predicate for everything that keys on the body actually being a corpse — the
-    /// death arc and its release/ghost UI, loot and skinning, the selection's death-clear edge. For
-    /// **how the unit reads to the eye** — which a feigning hunter shares with a corpse — use
-    /// [`Self::unit_reads_dead`] (decision 1022).
+    /// Really dead: health 0 with a known maximum, since a dead unit's create sends no health.
+    /// For how the unit looks, which a feigning hunter shares, use [`Self::unit_reads_dead`].
     pub fn unit_is_dead(&self) -> bool {
         self.unit_max_health().unwrap_or(0) > 0 && self.unit_health().unwrap_or(0) == 0
     }
-    /// Whether the unit **reads as dead** to the client — the reference's own one predicate
-    /// `0x605f90`, byte-exact: really dead (`[descr+0x40] <= 0`), **or** carrying
-    /// `UNIT_DYNFLAG_DEAD` (`0x605f9d`: `[descr+0x224] >> 5 & 1` — **feign death**), **or** stand
-    /// state 7 `UNIT_STAND_STATE_DEAD` (`0x605faa`: `vtbl+0xa4` == 7).
-    ///
-    /// Feign death is exactly this bit and nothing else: vmangos `Unit::SetFeignDeath`
-    /// (`Unit.cpp:9491`/`9500`) sets and clears it while leaving `UNIT_FIELD_HEALTH` alone, and
-    /// `Object::BuildValuesUpdate` only rewrites `TRACK_UNIT`/`TAPPED` per viewer — so the flag
-    /// reaches **every** viewer, the feigner included. The client then reads dead everywhere it
-    /// matters: `UnitHealth`/`UnitMana` answer 0 ([`Self::unit_shown_health`],
-    /// [`Self::unit_shown_power`]), `UnitIsDead 0x517ac0` answers true, the animation chain's top
-    /// resolver `0x5fcff0` claims and holds the corpse pose, and the plate/loop-sound gates drop.
-    ///
-    /// The stand-state leg is the reference's; vmangos never writes stand state 7, so against our
-    /// server the triple and the narrower `UnitIsDead 0x517ac0` pair (health ≤ 0 ∨ dynflag)
-    /// coincide.
+    /// Reads as dead, the reference's `0x605f90`: health 0, `UNIT_DYNFLAG_DEAD` (feign death,
+    /// `0x605f9d`) or stand state 7 (`0x605faa`). Feign death sets only the flag
+    /// (`Unit.cpp:9491`) and every viewer, the feigner included, receives it.
     pub fn unit_reads_dead(&self) -> bool {
         self.unit_is_dead()
             || self.unit_dynamic_flags() & UNIT_DYNFLAG_DEAD != 0
             || self.unit_stand_state() == STAND_STATE_DEAD
     }
-    /// Health **as the UI reads it** — the `UnitHealth 0x5174d0` law, byte-exact: a unit carrying
-    /// `UNIT_DYNFLAG_DEAD` answers **0** (`0x51753c`–`0x517551`), everything else answers the raw
-    /// field clamped at zero (`0x517553`–`0x517560`: `setle`/`dec`/`and`). So a feigning hunter's
-    /// health bar empties for himself and for everyone watching.
-    ///
-    /// Deliberately NOT mirrored on the max: `UnitHealthMax 0x5175b0` reads `[descr+0x58]` with no
-    /// gate at all, which is what makes the bar render `0/max` (empty) rather than vanish.
+    /// Health as `UnitHealth` (`0x5174d0`) reads it: 0 under `UNIT_DYNFLAG_DEAD`, else raw.
+    /// `UnitHealthMax` (`0x5175b0`) has no such gate, so a feigning unit's bar shows empty.
     pub fn unit_shown_health(&self) -> Option<u32> {
         if self.unit_dynamic_flags() & UNIT_DYNFLAG_DEAD != 0 {
             return Some(0);
         }
         self.unit_health()
     }
-    /// Power **as the UI reads it** — the `UnitMana 0x517670` law, both halves (decision 1034):
-    /// the `UNIT_DYNFLAG_DEAD` gate (`0x5176d6`–`0x5176e6`) ahead of the power-slot read, and then
-    /// the **raw→display divide** by [`power_display_scale`] (`0x517704 call 0x6e7130; 0x51770f
-    /// div ecx`). Rage rides the wire ×10 and pet happiness ×1000; without the divide a warrior's
-    /// bar reads `0/1000` and a pet's `…/1050000`.
-    ///
-    /// `UnitManaMax 0x5177e0` divides too (`0x517864`) but has **no** dead gate, so the bar empties
-    /// against a real maximum — see [`Self::unit_shown_max_power`].
-    ///
-    /// Not transcribed: the `powerType == POWER_HEALTH (-2)` substitution at `0x5176f7`. The
-    /// reference means to read HEALTH there, but `0x5176e8 movzx` zero-extends the byte while
-    /// `0x5176ec cmp edx,0xfffffffe` sign-extends its imm8, so the equality can never hold and the
-    /// leg is **dead code as compiled in 5875** (wow-re `feign-death-dyndead.md` §3, both §5
-    /// workers independently). Rendering it would be reproducing a bug, not the behaviour.
+    /// Power as `UnitMana` (`0x517670`) reads it: 0 under `UNIT_DYNFLAG_DEAD`, else divided by
+    /// [`power_display_scale`]. Its `POWER_HEALTH` leg (`0x5176f7`) compares a zero-extended
+    /// byte with -2, so it never matches and is left out.
     pub fn unit_shown_power(&self, ty: u8) -> Option<u32> {
         if self.unit_dynamic_flags() & UNIT_DYNFLAG_DEAD != 0 {
             return (ty < 5).then_some(0);
         }
         Some(self.unit_power(ty)? / power_display_scale(u32::from(ty)))
     }
-    /// Maximum power **as the UI reads it** — `UnitManaMax 0x5177e0`: the same
-    /// [`power_display_scale`] divide (`0x517864`), and deliberately **no** dead gate.
+    /// Maximum power as `UnitManaMax` (`0x5177e0`) reads it: divided, with no dead gate.
     pub fn unit_shown_max_power(&self, ty: u8) -> Option<u32> {
         Some(self.unit_max_power(ty)? / power_display_scale(u32::from(ty)))
     }
-    /// `UNIT_FIELD_LEVEL` — the unit's level.
+    /// `UNIT_FIELD_LEVEL`: the unit's level.
     pub fn unit_level(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_LEVEL)
     }
-    /// One aura slot (0-based), or `None` when the slot is empty or `slot >= UNIT_AURA_SLOTS`.
-    ///
-    /// Occupancy is the **client's own liveness test**: at least one effect-index bit set in the
-    /// `AURAFLAGS` nibble (`flags & 0x0E`, decision 0257) — *not* "has a spell id". A slot the server
-    /// clears can keep a stale spell id after its flags nibble goes to zero; gating on the id alone
-    /// would surface that husk as a phantom aura the real client hides (`flags & 0x0E` is precisely
-    /// why it doesn't). The `spell_id != 0` guard stays as a belt-and-braces check — for a live aura
-    /// (an applied effect implies a spell) the two always coincide.
+    /// One aura slot, live only when its `AURAFLAGS` nibble has an effect bit (`& 0x0E`) as the
+    /// client tests it, since a cleared slot can keep a stale spell id.
     pub fn unit_aura(&self, slot: u8) -> Option<UnitAuraSlot> {
         if slot >= UNIT_AURA_SLOTS {
             return None;
@@ -284,222 +177,147 @@ impl ObjectFields {
                 .saturating_add(1),
         })
     }
-    /// Every occupied aura slot, **ascending by slot index** — buffs (0–31) before debuffs (32–47).
-    ///
-    /// This is the reference client's ordering law for `UnitBuff`/`UnitDebuff` on **another unit**:
-    /// they read that unit's `UNIT_FIELD_AURA` straight, ascending raw slot within the half (wow-re
-    /// `0x519500`/`0x5198f0`, VERIFIED — decision 0257).
-    ///
-    /// It is **not** the order the player's own buff bar draws. For the local player the client
-    /// keeps a separate, densely packed cache (`0xbc6040`) in **insertion order**, which repacks on
-    /// removal — so a dropped buff slides the later ones along, and a new buff always lands at the
-    /// end rather than in whatever slot the server recycled. That order cannot be recovered from a
-    /// descriptor snapshot; it has to be *maintained* across updates (decision 0257).
+    /// Live auras by ascending slot, buffs 0-31 then debuffs 32-47: the order `UnitBuff` and
+    /// `UnitDebuff` read another unit in (`0x519500`, `0x5198f0`). The local player's buff bar
+    /// keeps insertion order in a packed cache (`0xbc6040`) instead, which this cannot recover.
     pub fn unit_auras(&self) -> impl Iterator<Item = UnitAuraSlot> + '_ {
         (0..UNIT_AURA_SLOTS).filter_map(|slot| self.unit_aura(slot))
     }
-    /// Every `UNIT_FIELD_AURA` slot's **raw** spell id, unfiltered — no `AURAFLAGS` nibble test,
-    /// no zero-skip, in ascending slot order.
-    ///
-    /// This is deliberately NOT [`Self::unit_auras`], and the difference is the reference's, not
-    /// ours: the cast validator's crowd-control exemption scan (`0x6e9ca0`) reads these slots
-    /// straight and **does not consult `UNIT_FIELD_AURAFLAGS`** — it skips no "inactive" slot and
-    /// reads no duration, stack or caster state. Any non-zero, in-range id counts, husk or not.
-    /// The buff bar wants the filtered view; that scan wants this one (decision 1946).
+    /// Every `UNIT_FIELD_AURA` slot's raw spell id, zeros and stale ids included, as the cast
+    /// validator's crowd-control scan (`0x6e9ca0`) reads them, without `AURAFLAGS`.
     pub fn unit_aura_ids(&self) -> impl Iterator<Item = u32> + '_ {
         (0..UNIT_AURA_SLOTS)
             .map(|slot| self.get_u32(FIELD_UNIT_AURA + u16::from(slot)).unwrap_or(0))
     }
 
-    /// The unit's active power type (`UNIT_FIELD_BYTES_0` byte 3): `0` mana, `1` rage, `2` focus,
-    /// `3` energy, `4` happiness. Absent (no bytes_0 on the wire yet) reads as mana, the descriptor's
-    /// zero-initialized default.
+    /// `UNIT_FIELD_BYTES_0` byte 3: power type, 0 mana, 1 rage, 2 focus, 3 energy, 4 happiness.
     pub fn unit_power_type(&self) -> u8 {
         (self.unit_bytes_0().unwrap_or(0) >> 24) as u8
     }
-    /// `UNIT_FIELD_BYTES_1` byte 0 — the unit's stand state (VERIFIED vmangos
-    /// `UNIT_BYTES_1_OFFSET_STAND_STATE = 0`, written by `Unit::SetStandState`): 0 stand · 1 sit
-    /// (ground) · 2 sit-chair · 3 sleep · 4/5/6 chair low/med/high · 8 kneel. For a player it's
-    /// the echo of their own `CMSG_STANDSTATECHANGE`. `0` (standing) when the field is absent —
-    /// the descriptor's zero-initialized default.
+    /// `UNIT_FIELD_BYTES_1` byte 0: stand state, 0 stand, 1 sit, 2 chair, 3 sleep, 4-6 low,
+    /// medium and high chair, 8 kneel; for a player, the echo of `CMSG_STANDSTATECHANGE`.
     pub fn unit_stand_state(&self) -> u8 {
         (self.get_u32(FIELD_UNIT_BYTES_1).unwrap_or(0) & 0xff) as u8
     }
-    /// `UNIT_FIELD_BYTES_1` byte 1 — a hunter pet's **loyalty level**, `1..=8`, and `0` for a unit
-    /// that has none (VERIFIED vmangos `UNIT_BYTES_1_OFFSET_PET_LOYALTY = 1`; byte-verified
-    /// client-side as `[unit+0x110]+0x211`, the byte `GetPetLoyalty 0x4be700` indexes
-    /// `PetLoyalty.dbc` with). `0` is the binding's **nil**, not level 1.
+    /// `UNIT_FIELD_BYTES_1` byte 1: a hunter pet's loyalty level, 1-8, which `GetPetLoyalty`
+    /// (`0x4be700`) indexes `PetLoyalty.dbc` with; 0 is none and answers nil.
     pub fn unit_loyalty_level(&self) -> u8 {
         ((self.get_u32(FIELD_UNIT_BYTES_1).unwrap_or(0) >> 8) & 0xff) as u8
     }
-    /// `UNIT_FIELD_PETEXPERIENCE` / `UNIT_FIELD_PETNEXTLEVELEXP` — `GetPetExperience`'s
-    /// `(currXP, nextXP)`, in that order. Absent fields read `0`, which is the binding's own
-    /// gate-failure value: this pair is numbers on every path, never nil.
+    /// `UNIT_FIELD_PETEXPERIENCE` and `UNIT_FIELD_PETNEXTLEVELEXP`: `GetPetExperience`'s
+    /// `(currXP, nextXP)`; absent reads 0, the binding's own failure value, never nil.
     pub fn unit_pet_experience(&self) -> (u32, u32) {
         (
             self.get_u32(FIELD_UNIT_PETEXPERIENCE).unwrap_or(0),
             self.get_u32(FIELD_UNIT_PETNEXTLEVELEXP).unwrap_or(0),
         )
     }
-    /// `UNIT_TRAINING_POINTS` split as the client splits it — `(total, spent)`, **high word
-    /// first**. The order is the load-bearing half: both are small numbers of the same magnitude,
-    /// so swapping them yields a pet that looks like it has spent everything or nothing, with no
-    /// error anywhere.
+    /// `UNIT_TRAINING_POINTS`: `(total, spent)`, total in the high half as the client splits it.
     pub fn unit_training_points(&self) -> (u16, u16) {
         let packed = self.get_u32(FIELD_UNIT_TRAINING_POINTS).unwrap_or(0);
         ((packed >> 16) as u16, (packed & 0xffff) as u16)
     }
-    /// `UNIT_FIELD_BYTES_1` byte 3's `UNIT_VIS_FLAGS_CREEP (0x2)` — the sneaking visual, set by
-    /// `SPELL_AURA_MOD_STEALTH` (vmangos `SpellAuras.cpp:3610`,
-    /// `UNIT_BYTES_1_OFFSET_VIS_FLAG = 3`). The usable walk's only-stealthed leg tests exactly
-    /// this bit (wow-re §2a leg 7: `[+0x110]+0x213 & 2`); the tracking classifier's
-    /// stealth always-show clause tests it against our own track-stealthed bit
-    /// (`0x5ed210`, wow-re `track-predicates.md`).
+    /// `UNIT_FIELD_BYTES_1` byte 3 bit `0x2`, `UNIT_VIS_FLAGS_CREEP` (`SpellAuras.cpp:3610`):
+    /// stealthed; read by the usable check (`[+0x110]+0x213 & 2`) and the tracker (`0x5ed210`).
     pub fn unit_is_stealthed(&self) -> bool {
         (self.get_u32(FIELD_UNIT_BYTES_1).unwrap_or(0) >> 24) & 0x2 != 0
     }
-    /// `UNIT_FIELD_BYTES_1` byte 3's `UNIT_VIS_FLAGS_GHOST (0x1)` — set on ANY unit by the ghost
-    /// aura (vmangos `HandleAuraGhost`). Byte-VERIFIED (wow-re ghost-death-visuals.md): this flag
-    /// drives NO body render — its complete client effect is nameplate/marker suppression
-    /// (tested as `byte3 & 0x03`, ghost|creep, at `0x607101`/`0x60f62e`). The translucent
-    /// whitened BODY is the ghost aura's own state visual kit (spell 8326 → SpellVisual 886 →
-    /// kit 989: charproc-14 alpha 0.5 + charproc-1 tint 0xFF8CB9FD + `Spells\Ghost_state.mdx`) —
-    /// aura-driven, exactly like Stealth's 0.3 translucency. Consumers: the overhead-name and
-    /// V-plate gates.
+    /// `UNIT_FIELD_BYTES_1` byte 3 bit `0x1`, `UNIT_VIS_FLAGS_GHOST`, set by the ghost aura: it
+    /// only hides names and plates (`byte3 & 0x03`, `0x607101`, `0x60f62e`); the ghostly body is
+    /// the aura's own visual kit (spell 8326, kit 989).
     pub fn unit_is_ghost_visual(&self) -> bool {
         (self.get_u32(FIELD_UNIT_BYTES_1).unwrap_or(0) >> 24) & 0x1 != 0
     }
 
-    /// `UNIT_FIELD_BYTES_1` byte 3's **`0x4`** — the third neighbour of the ghost (`0x1`) and creep
-    /// (`0x2`) bits above. Byte-VERIFIED as the minimap object-dot classifier's own third
-    /// precondition (wow-re `questgiver-marker.md` §W15: `byte [eax+0x213] & 4`, where `eax` is the
-    /// descriptor block base — `0x210/4 = 132` = `UNIT_FIELD_BYTES_1`; the only `& 4` site on this
-    /// byte image-wide, by two independent censuses). Set ⇒ the unit draws **no minimap dot at
-    /// all**, quest or tracking.
-    ///
-    /// The *name* is INFERRED from vmangos's `UNIT_VIS_FLAGS_UNTRACKABLE`, like its two siblings —
-    /// no flag-name string exists in the image. The bit and its effect are verified.
+    /// `UNIT_FIELD_BYTES_1` byte 3 bit `0x4` (vmangos `UNIT_VIS_FLAGS_UNTRACKABLE`): no minimap
+    /// dot at all, quest or tracking (`byte [eax+0x213] & 4`, the byte's only such test).
     pub fn unit_is_untrackable(&self) -> bool {
         (self.get_u32(FIELD_UNIT_BYTES_1).unwrap_or(0) >> 24) & 0x4 != 0
     }
 
-    /// `UNIT_FIELD_AURASTATE` ([`FIELD_UNIT_AURASTATE`]) — the aura-state bit set (defense 1,
-    /// healthless-20% 2, …); the usable walk tests `1 << (state-1)` against it.
+    /// `UNIT_FIELD_AURASTATE`: the aura-state bits (1 defense, 2 health under 20%, ...), which
+    /// the usable check tests as `1 << (state - 1)`.
     pub fn unit_aura_state(&self) -> u32 {
         self.get_u32(FIELD_UNIT_AURASTATE).unwrap_or(0)
     }
 
-    /// `UNIT_FIELD_BYTES_1` byte 2 — the shapeshift form (VERIFIED vmangos `UpdateFields_1_12_1.h`
-    /// 0x8A + `UNIT_BYTES_1_OFFSET_SHAPESHIFT_FORM = 2`): 0 none, 17/18/19 = warrior
-    /// battle/defensive/berserker stance, druid forms in the low ids. Drives the action bar's
-    /// bonus-page pick, and the tracking dots' creature-type override (the `0x605570`
-    /// resolver's first branch — decision 0564).
+    /// `UNIT_FIELD_BYTES_1` byte 2: the shapeshift form, 0 none, 17-19 the warrior stances, the
+    /// druid forms low; the creature-type resolver `0x605570` checks it first.
     pub fn unit_shapeshift_form(&self) -> u8 {
         (self.get_u32(FIELD_UNIT_BYTES_1).unwrap_or(0) >> 16) as u8
     }
-    /// `UNIT_FIELD_POWER1..5` — current power for slot `ty` (the [`Self::unit_power_type`] index).
-    /// Out-of-range slots and absent fields read `None`.
+    /// `UNIT_FIELD_POWER1..5`: current power of type `ty`, on the wire's raw scale.
     pub fn unit_power(&self, ty: u8) -> Option<u32> {
         (ty < 5).then(|| self.get_u32(FIELD_UNIT_POWER1 + u16::from(ty)))?
     }
-    /// `UNIT_FIELD_MAXPOWER1..5` — maximum power for slot `ty`.
+    /// `UNIT_FIELD_MAXPOWER1..5`: maximum power of type `ty`, raw.
     pub fn unit_max_power(&self, ty: u8) -> Option<u32> {
         (ty < 5).then(|| self.get_u32(FIELD_UNIT_MAXPOWER1 + u16::from(ty)))?
     }
-    /// `UNIT_FIELD_BASE_MANA` (VERIFIED vmangos `UpdateFields_1_12_1.h` `OBJECT_END + 0x9C` = 162;
-    /// PRIVATE + OWNER_ONLY, so it rides only our own descriptor) — the base the percent-cost
-    /// spells (`ManaCostPercentage`) scale from. `None` when absent (a non-self unit).
+    /// `UNIT_FIELD_BASE_MANA` (field 162, owner only): what `ManaCostPercentage` costs scale from.
     pub fn unit_base_mana(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_BASE_MANA)
     }
-    /// `UNIT_FIELD_FACTIONTEMPLATE` — the unit's `FactionTemplate.dbc` row id, the key the client's
-    /// whole reaction/hostility decode starts from (wow-re: descriptor `+0x74`, read by every
-    /// `UnitReaction`/`Can*` predicate). Flagged PUBLIC server-side, so it's always on the wire.
+    /// `UNIT_FIELD_FACTIONTEMPLATE` (public, `+0x74`): the `FactionTemplate.dbc` row reactions use.
     pub fn unit_faction_template(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_FACTIONTEMPLATE)
     }
-    /// `UNIT_FIELD_FLAGS` — unit state flags; bit `0x0400_0000` = **skinnable** (the cursor's Skin
-    /// branch reads it — wow-re cursor RE, client `+0xa0`). Absent counts as 0 (create omits zeros).
+    /// `UNIT_FIELD_FLAGS` (`+0xa0`): unit state flags; bit `0x0400_0000` is skinnable.
     pub fn unit_flags(&self) -> u32 {
         self.get_u32(FIELD_UNIT_FLAGS).unwrap_or(0)
     }
-    /// `UNIT_FIELD_COMBATREACH` — the melee-reach float the client's edge-to-edge attack range gate
-    /// reads (`rA + rB + 1.333`, cap 5.0 — wow-re cursor RE `0x6e3480`, client `+0x1f0`). Vanilla
-    /// default 1.5 when absent.
+    /// `UNIT_FIELD_COMBATREACH` (`+0x1f0`): melee reach, summed as `rA + rB + 1.333`, cap 5.0,
+    /// by the attack range gate (`0x6e3480`); 1.5, the vanilla default, before it streams.
     pub fn unit_combat_reach(&self) -> f32 {
         self.get_f32(FIELD_UNIT_COMBATREACH).unwrap_or(1.5)
     }
-    /// `UNIT_FIELD_BOUNDINGRADIUS` — the unit's horizontal bounding radius (yd). The water-foam
-    /// depth gate reads it (`max(2 × radius, 1.0)` — wow-re CWater0Ripple driver `0x5fa760`).
-    /// Absent counts as 0 — the gate's own 1.0-yd floor covers it, like the reference.
+    /// `UNIT_FIELD_BOUNDINGRADIUS`: horizontal radius in yards; the water-foam depth gate takes
+    /// `max(2 * radius, 1.0)` (`0x5fa760`), so absent reads 0.
     pub fn unit_bounding_radius(&self) -> f32 {
         self.get_f32(FIELD_UNIT_BOUNDINGRADIUS).unwrap_or(0.0)
     }
-    /// `UNIT_DYNAMIC_FLAGS` — per-viewer dynamic state; bit `0x1` = **lootable** (the cursor's Loot
-    /// branch — wow-re cursor RE, client `+0x224`), bit `0x2` = tracked (Hunter's Mark), bit `0x20`
-    /// = **dead-looking** ([`Self::unit_reads_dead`] — feign death). Absent counts as 0.
+    /// `UNIT_DYNAMIC_FLAGS` (`+0x224`), per viewer: `0x1` lootable, `0x2` tracked, `0x20` dead.
     pub fn unit_dynamic_flags(&self) -> u32 {
         self.get_u32(FIELD_UNIT_DYNAMIC_FLAGS).unwrap_or(0)
     }
-    /// `UNIT_DYNAMIC_FLAGS` bit `0x20` alone — the **dead-looking** flag, without
-    /// [`Self::unit_reads_dead`]'s two other legs.
-    ///
-    /// It has its own accessor because one caller wants exactly this bit and not that predicate:
-    /// `SetSelection`'s last-enemy stamp gates on `HEALTH > 0 || dynflag 0x20`
-    /// (`0x49372f`-`0x493778`), with no health-zero leg and no stand-state leg, so a feigning unit
-    /// is remembered and a genuinely dead one is not. Reaching for `unit_reads_dead` there would
-    /// quietly add a third condition the reference does not have.
+    /// `UNIT_DYNAMIC_FLAGS` bit `0x20` alone: `SetSelection`'s last-enemy stamp gates on
+    /// `HEALTH > 0 || dynflag 0x20` (`0x49372f`), not on [`Self::unit_reads_dead`].
     pub fn unit_dynflag_dead(&self) -> bool {
         self.unit_dynamic_flags() & UNIT_DYNFLAG_DEAD != 0
     }
-    /// `UNIT_DYNAMIC_FLAGS` bit `0x4` — **tapped**: this unit is someone's kill credit.
-    /// `UnitIsTapped 0x519c90` is exactly `0x519cd0 test BYTE PTR [eax+0x224],0x4` behind an
-    /// object-presence check, nothing else — no ownership, GUID compare, party/raid or health
-    /// conjunct anywhere in its body (wow-re `ui/scratch/tapped-bits-and-unit-faction.md`).
+    /// `UNIT_DYNAMIC_FLAGS` bit `0x4`: tapped, the only test in `UnitIsTapped` (`0x519c90`).
     pub fn unit_tapped(&self) -> bool {
         self.unit_dynamic_flags() & 0x4 != 0
     }
-    /// `UNIT_DYNAMIC_FLAGS` bit `0x8` — **tapped by me** (`UnitIsTappedByPlayer 0x519d00`, the same
-    /// 108-byte body with the mask changed). Per-viewer: the server decides whose credit it is
-    /// before it ships the field, so the client reads it verbatim and does nothing else with it.
-    ///
-    /// The pair is read together — `tapped && !tapped_by_player` is "someone ELSE's kill", the
-    /// grey-bar condition every unit-frame addon draws.
+    /// `UNIT_DYNAMIC_FLAGS` bit `0x8`: tapped by me (`UnitIsTappedByPlayer`, `0x519d00`), which
+    /// the server sets per viewer; tapped but not by me is the grey unit frame.
     pub fn unit_tapped_by_player(&self) -> bool {
         self.unit_dynamic_flags() & 0x8 != 0
     }
-    /// `UNIT_DYNAMIC_FLAGS` bit `0x1` — **lootable by me** (the server strips the bit per viewer
-    /// before it ships — vmangos's "hide lootable animation for unallowed players"). Gates the
-    /// loot cursor, the right-click loot route, and the corpse sparkle (wow-re
-    /// `loot-corpse-effect.md`).
+    /// `UNIT_DYNAMIC_FLAGS` bit `0x1`: lootable by me, stripped per viewer by the server; gates
+    /// the loot cursor, right-click looting and the corpse sparkle.
     pub fn unit_lootable(&self) -> bool {
         self.unit_dynamic_flags() & 0x1 != 0
     }
-    /// `UNIT_NPC_FLAGS` — the NPC service bits (vanilla values: gossip `0x1`, questgiver `0x2`,
-    /// vendor `0x4`, flightmaster `0x8`, trainer `0x10`, … repair `0x4000` — vmangos
-    /// `UnitDefines.h`). The cursor's service ladder switches on these, first bit wins (wow-re
-    /// cursor RE, client `+0x234`). Absent counts as 0.
+    /// `UNIT_NPC_FLAGS` (`+0x234`, `UnitDefines.h`): gossip `0x1`, questgiver `0x2`, vendor
+    /// `0x4`, flight master `0x8`, trainer `0x10`, ..., repair `0x4000`; cursor: first bit wins.
     pub fn unit_npc_flags(&self) -> u32 {
         self.get_u32(FIELD_UNIT_NPC_FLAGS).unwrap_or(0)
     }
-    /// `UNIT_NPC_EMOTESTATE` — the unit's looping state emote (`Emotes.dbc` id: dance, NPC
-    /// cooking/working flavor; `0`/absent = none). The anim layer loops its `AnimID` while the
-    /// unit stands; movement suppresses it (the field stays set server-side until cleared).
+    /// `UNIT_NPC_EMOTESTATE`: the looping `Emotes.dbc` state, which the server keeps while moving.
     pub fn unit_emote_state(&self) -> u32 {
         self.get_u32(FIELD_UNIT_NPC_EMOTESTATE).unwrap_or(0)
     }
-    /// `UNIT_FIELD_BYTES_0` — packed race (byte 0) / class (byte 1) / gender (byte 2) / power type (3).
+    /// `UNIT_FIELD_BYTES_0`: race, class, gender and power type, bytes 0 to 3.
     pub fn unit_bytes_0(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_BYTES_0)
     }
-    /// `UNIT_VIRTUAL_ITEM_SLOT_DISPLAY + slot` — a creature's virtual-weapon **display id** for
-    /// `slot` (0 mainhand / 1 offhand / 2 ranged): the item's `DisplayInfoID` directly, no item guid
-    /// behind it (see the field's doc comment). `slot >= 3` reads `None`.
+    /// `UNIT_VIRTUAL_ITEM_SLOT_DISPLAY + slot`: a creature's weapon `DisplayInfoID` for slot 0
+    /// main hand, 1 off hand or 2 ranged, with no item behind it.
     pub fn unit_virtual_item_display(&self, slot: u8) -> Option<u32> {
         (slot < 3).then(|| self.get_u32(FIELD_UNIT_VIRTUAL_ITEM_SLOT_DISPLAY + u16::from(slot)))?
     }
-    /// `UNIT_VIRTUAL_ITEM_INFO + 2*slot` — `slot`'s flavor bytes: `(class, subclass, material,
-    /// inventory_type)`. `slot >= 3` reads `None`.
+    /// `UNIT_VIRTUAL_ITEM_INFO + 2*slot`: bytes `(class, subclass, material, inventory_type)`.
     pub fn unit_virtual_item_info(&self, slot: u8) -> Option<(u8, u8, u8, u8)> {
         let v =
             (slot < 3).then(|| self.get_u32(FIELD_UNIT_VIRTUAL_ITEM_INFO + 2 * u16::from(slot)))?;
@@ -512,95 +330,84 @@ impl ObjectFields {
             )
         })
     }
-    /// `UNIT_VIRTUAL_ITEM_INFO + 2*slot + 1` byte 0 — `slot`'s virtual item Sheath. `slot >= 3`
-    /// reads `None`.
+    /// `UNIT_VIRTUAL_ITEM_INFO + 2*slot + 1` byte 0: the virtual item's sheath type.
     pub fn unit_virtual_item_sheath(&self, slot: u8) -> Option<u8> {
         let v = (slot < 3)
             .then(|| self.get_u32(FIELD_UNIT_VIRTUAL_ITEM_INFO + 2 * u16::from(slot) + 1))?;
         v.map(|v| (v & 0xff) as u8)
     }
-    /// `UNIT_FIELD_BYTES_2` byte 0 — the unit's sheath state: `0` unarmed/stowed, `1` melee drawn,
-    /// `2` ranged drawn. For a player this is purely what they last told the server via
-    /// `CMSG_SETSHEATHED`, not a server-computed fact.
+    /// `UNIT_FIELD_BYTES_2` byte 0: sheath state, 0 stowed, 1 melee drawn, 2 ranged drawn; for a
+    /// player, whatever they last sent in `CMSG_SETSHEATHED`.
     pub fn unit_sheath_state(&self) -> Option<u8> {
         self.get_u32(FIELD_UNIT_BYTES_2).map(|v| (v & 0xff) as u8)
     }
-    /// `UNIT_FIELD_STAT0..4 + i` — the unit's raw (post-buff) primary stat `i` (0 Str, 1 Agi,
-    /// 2 Stam, 3 Int, 4 Spirit — the `Stats` enum order). `i >= 5` reads `None`.
+    /// `UNIT_FIELD_STAT0 + i`: primary stat `i` after buffs, 0 Str, 1 Agi, 2 Sta, 3 Int, 4 Spi.
     pub fn unit_stat(&self, i: u8) -> Option<u32> {
         (i < 5).then(|| self.get_u32(FIELD_UNIT_STAT0 + u16::from(i)))?
     }
-    /// `UNIT_FIELD_RESISTANCES + i` — resistance `i` (0 = armor, 1..6 the magic schools). `i >= 7`
-    /// reads `None`.
+    /// `UNIT_FIELD_RESISTANCES + i`: resistance `i`, signed, 0 armor, 1-6 the magic schools.
     pub fn unit_resistance(&self, i: u8) -> Option<i32> {
         (i < 7).then(|| self.get_i32(FIELD_UNIT_RESISTANCES + u16::from(i)))?
     }
-    /// `UNIT_FIELD_ATTACK_POWER` — melee attack power before the split pos/neg mods.
+    /// `UNIT_FIELD_ATTACK_POWER`: melee attack power before the split pos/neg mods.
     pub fn unit_attack_power(&self) -> Option<i32> {
         self.get_i32(FIELD_UNIT_ATTACK_POWER)
     }
-    /// `UNIT_FIELD_ATTACK_POWER_MODS` — `(positive, negative)` flat AP mods (the negative half
-    /// already negative-or-zero; see the field's doc comment for the verified packing/sign).
-    /// Absent reads `(0, 0)` — no mods applied yet.
+    /// `UNIT_FIELD_ATTACK_POWER_MODS`: flat `(positive, negative)` mods, the low and high i16.
     pub fn unit_attack_power_mods(&self) -> (i16, i16) {
         let (lo, hi) = self
             .get_u16_pair(FIELD_UNIT_ATTACK_POWER_MODS)
             .unwrap_or((0, 0));
         (lo as i16, hi as i16)
     }
-    /// `UNIT_FIELD_ATTACK_POWER_MULTIPLIER` — the percent AP bonus **minus 1.0** (`0.0` = no
-    /// bonus; vmangos writes `multiplier − 1.0`, see the field's doc comment).
+    /// `UNIT_FIELD_ATTACK_POWER_MULTIPLIER`: the percent bonus minus 1.0, so 0.0 is no bonus.
     pub fn unit_attack_power_multiplier(&self) -> Option<f32> {
         self.get_f32(FIELD_UNIT_ATTACK_POWER_MULTIPLIER)
     }
-    /// `UNIT_FIELD_RANGED_ATTACK_POWER` — ranged attack power before the split pos/neg mods.
+    /// `UNIT_FIELD_RANGED_ATTACK_POWER`: ranged attack power before the split pos/neg mods.
     pub fn unit_ranged_attack_power(&self) -> Option<i32> {
         self.get_i32(FIELD_UNIT_RANGED_ATTACK_POWER)
     }
-    /// `UNIT_FIELD_RANGED_ATTACK_POWER_MODS` — the ranged twin of
-    /// [`Self::unit_attack_power_mods`].
+    /// `UNIT_FIELD_RANGED_ATTACK_POWER_MODS`: the ranged `(positive, negative)` flat mods.
     pub fn unit_ranged_attack_power_mods(&self) -> (i16, i16) {
         let (lo, hi) = self
             .get_u16_pair(FIELD_UNIT_RANGED_ATTACK_POWER_MODS)
             .unwrap_or((0, 0));
         (lo as i16, hi as i16)
     }
-    /// `UNIT_FIELD_RANGED_ATTACK_POWER_MULTIPLIER` — the ranged twin of
-    /// [`Self::unit_attack_power_multiplier`].
+    /// `UNIT_FIELD_RANGED_ATTACK_POWER_MULTIPLIER`: the ranged percent bonus minus 1.0.
     pub fn unit_ranged_attack_power_multiplier(&self) -> Option<f32> {
         self.get_f32(FIELD_UNIT_RANGED_ATTACK_POWER_MULTIPLIER)
     }
-    /// `UNIT_FIELD_MINDAMAGE` — the mainhand weapon's minimum damage.
+    /// `UNIT_FIELD_MINDAMAGE`: the mainhand weapon's minimum damage.
     pub fn unit_min_damage(&self) -> Option<f32> {
         self.get_f32(FIELD_UNIT_MINDAMAGE)
     }
-    /// `UNIT_FIELD_MAXDAMAGE` — the mainhand weapon's maximum damage.
+    /// `UNIT_FIELD_MAXDAMAGE`: the mainhand weapon's maximum damage.
     pub fn unit_max_damage(&self) -> Option<f32> {
         self.get_f32(FIELD_UNIT_MAXDAMAGE)
     }
-    /// `UNIT_FIELD_MINOFFHANDDAMAGE` — the offhand weapon's minimum damage (present whether or not
-    /// one's equipped; the paper-doll only shows it when an offhand item is worn).
+    /// `UNIT_FIELD_MINOFFHANDDAMAGE`: the offhand minimum damage, sent even with no offhand worn.
     pub fn unit_min_offhand_damage(&self) -> Option<f32> {
         self.get_f32(FIELD_UNIT_MINOFFHANDDAMAGE)
     }
-    /// `UNIT_FIELD_MAXOFFHANDDAMAGE` — the offhand weapon's maximum damage.
+    /// `UNIT_FIELD_MAXOFFHANDDAMAGE`: the offhand weapon's maximum damage.
     pub fn unit_max_offhand_damage(&self) -> Option<f32> {
         self.get_f32(FIELD_UNIT_MAXOFFHANDDAMAGE)
     }
-    /// `UNIT_FIELD_MINRANGEDDAMAGE` — the ranged weapon's minimum damage.
+    /// `UNIT_FIELD_MINRANGEDDAMAGE`: the ranged weapon's minimum damage.
     pub fn unit_min_ranged_damage(&self) -> Option<f32> {
         self.get_f32(FIELD_UNIT_MINRANGEDDAMAGE)
     }
-    /// `UNIT_FIELD_MAXRANGEDDAMAGE` — the ranged weapon's maximum damage.
+    /// `UNIT_FIELD_MAXRANGEDDAMAGE`: the ranged weapon's maximum damage.
     pub fn unit_max_ranged_damage(&self) -> Option<f32> {
         self.get_f32(FIELD_UNIT_MAXRANGEDDAMAGE)
     }
-    /// `UNIT_FIELD_BASEATTACKTIME + i` — attack speed in ms (`i` 0 mainhand, 1 offhand). `i >= 2`
-    /// reads `None`.
+    /// `UNIT_FIELD_BASEATTACKTIME + i`: attack speed in ms, 0 mainhand, 1 offhand.
     pub fn unit_base_attack_time(&self, i: u8) -> Option<u32> {
         (i < 2).then(|| self.get_u32(FIELD_UNIT_BASEATTACKTIME + u16::from(i)))?
     }
-    /// `UNIT_FIELD_RANGEDATTACKTIME` — ranged weapon attack speed in ms.
+    /// `UNIT_FIELD_RANGEDATTACKTIME`: ranged weapon attack speed in ms.
     pub fn unit_ranged_attack_time(&self) -> Option<u32> {
         self.get_u32(FIELD_UNIT_RANGEDATTACKTIME)
     }
diff --git a/crates/benilla-protocol/src/messages/update_object/mod.rs b/crates/benilla-protocol/src/messages/update_object/mod.rs
index 3e09adc1..0621e242 100644
--- a/crates/benilla-protocol/src/messages/update_object/mod.rs
+++ b/crates/benilla-protocol/src/messages/update_object/mod.rs
@@ -1,9 +1,5 @@
-//! `SMSG_UPDATE_OBJECT` body decode: the object list, each entry's [`MovementBlock`] pose and sparse
-//! [`ObjectFields`] of descriptor fields. The complex, *growing* core of the message layer (decision
-//! 0021) — split out because the descriptor-field decode expands as the object layer does. The parent
-//! module ([`super`]) owns packet framing/dispatch and the client builders, and the shared
-//! `MOVEMENT_FLAG_*` constants (also used by its movement-info parse), which this module reaches via
-//! `super::`.
+//! `SMSG_UPDATE_OBJECT` body decode: the object list, each entry's [`MovementBlock`] and its
+//! sparse [`ObjectFields`].
 
 use std::io::{self, Read};
 
@@ -31,7 +27,7 @@ pub enum Object {
         guid: u64,
         movement: MovementBlock,
     },
-    /// `CREATE_OBJECT` / `CREATE_OBJECT2` (identical wire shape; the distinction is irrelevant here).
+    /// `CREATE_OBJECT` or `CREATE_OBJECT2`, which share one wire shape.
     Create {
         guid: u64,
         object_type: ObjectType,
@@ -62,11 +58,8 @@ impl Object {
                 let guid = read_packed_guid(r)?;
                 let object_type = ObjectType::from_u8(read_u8(r)?);
                 let movement = MovementBlock::read(r)?;
-                // A create's mask is the COMPLETE descriptor — the server omits zero-valued
-                // fields (vmangos `_SetCreateBits`), so absent must read 0, not unknown
-                // (`ObjectFields`'s created semantics). The TYPE rides along because "absent = 0"
-                // holds only inside this object's OWN descriptor: a creature has no PLAYER block
-                // to be absent from (decision 1081).
+                // A create omits zero fields (vmangos `_SetCreateBits`), so absent reads 0, but
+                // only inside this type's own descriptor.
                 let mask = ObjectFields::read(r)?.into_created(object_type);
                 Object::Create {
                     guid,
@@ -100,7 +93,7 @@ fn read_guid_list(r: &mut impl Read) -> io::Result<Vec<u64>> {
     Ok(guids)
 }
 
-/// Parse an `SMSG_UPDATE_OBJECT` body's object list (the count + has-transport byte + each `Object`).
+/// Parse an `SMSG_UPDATE_OBJECT` body: the count, the has-transport byte, then each `Object`.
 pub(super) fn read_update_object(r: &mut impl Read) -> io::Result<Vec<Object>> {
     let amount_of_objects = read_u32_le(r)?;
     let _has_transport = read_u8(r)?;
@@ -117,8 +110,8 @@ mod tests {
 
     #[test]
     fn quest_log_slot_unpacks_counters_and_state() {
-        // Slot 2 (base 198 + 6 = 204): counters 5/10/63/0 packed at 6-bit strides, state byte
-        // COMPLETE, a timer value. Counter packing per vmangos Player.h:1100-1106.
+        // Slot 2 (198 + 6 = 204): counters 5/10/63/0 at 6-bit strides, state COMPLETE, a timer
+        // (`Player.h:1100-1106`).
         let count_state =
             5u32 | (10 << 6) | (63 << 12) | ((quest_slot_state::COMPLETE as u32) << 24);
         let f = ObjectFields::from_pairs(&[(204, 783), (205, count_state), (206, 4242)]);
@@ -131,7 +124,6 @@ mod tests {
                 timer: 4242,
             })
         );
-        // The neighbouring slots never streamed → None; out of range → None.
         assert_eq!(f.player_quest_log(1), None);
         assert_eq!(f.player_quest_log(3), None);
         assert_eq!(f.player_quest_log(PLAYER_QUEST_LOG_SLOTS), None);
@@ -139,7 +131,7 @@ mod tests {
 
     #[test]
     fn quest_log_cleared_slot_reads_zero_id() {
-        // An abandoned slot: the server zeroes the id (and pair) — still `Some`, id 0.
+        // An abandoned slot: the server zeroes the id and the pair.
         let f = ObjectFields::from_pairs(&[(198, 0), (199, 0), (200, 0)]);
         assert_eq!(f.player_quest_log(0).map(|s| s.quest_id), Some(0));
     }
diff --git a/crates/benilla-protocol/src/messages/update_object/movement.rs b/crates/benilla-protocol/src/messages/update_object/movement.rs
index 6e770110..876d3411 100644
--- a/crates/benilla-protocol/src/messages/update_object/movement.rs
+++ b/crates/benilla-protocol/src/messages/update_object/movement.rs
@@ -36,127 +36,66 @@ impl ObjectType {
     }
 }
 
-// MovementBlock update_flag bits (UpdateObject-only; the shared MOVEMENT_FLAG_* live in `super`).
 const UPDATE_FLAG_TRANSPORT: u8 = 0x02;
 const UPDATE_FLAG_MELEE_ATTACKING: u8 = 0x04;
 const UPDATE_FLAG_HIGH_GUID: u8 = 0x08;
 const UPDATE_FLAG_ALL: u8 = 0x10;
 const UPDATE_FLAG_LIVING: u8 = 0x20;
 const UPDATE_FLAG_HAS_POSITION: u8 = 0x40;
-// SplineFlag final-destination bits (checked angle → target → point).
 const SPLINE_FLAG_FINAL_POINT: u32 = 0x1_0000;
 const SPLINE_FLAG_FINAL_TARGET: u32 = 0x2_0000;
 const SPLINE_FLAG_FINAL_ANGLE: u32 = 0x4_0000;
-/// `MoveSplineFlag::Flying` — and in vmangos 1.12 that bit alone *is* `Mask_CatmullRom`
-/// (`MoveSplineFlag.h:48,77`), the same split [`crate::ServerPacket::MonsterMove`] reads: set ⇒ a 3-D
-/// flight path that keeps its own Z, clear ⇒ a ground walk whose Z the client re-derives from terrain.
+/// `MoveSplineFlag::Flying`; in vmangos it alone is `Mask_CatmullRom` (`MoveSplineFlag.h:48,77`).
 const SPLINE_FLAG_FLYING: u32 = 0x200;
-/// `SPLINEFLAG_RUNMODE` — see [`super::super::monster_move`]'s copy for why its *absence* is what
-/// matters: a spline without it forces walk mode on for the unit it moves.
 const SPLINE_FLAG_RUNMODE: u32 = 0x100;
-/// `MoveSplineFlag::Cyclic` (`MoveSplineFlag.h:59`) — the path loops back on itself forever.
+/// `MoveSplineFlag::Cyclic` (`MoveSplineFlag.h:59`).
 const SPLINE_FLAG_CYCLIC: u32 = 0x10_0000;
 
-/// The **live spline a unit is already riding** when it streams into view — the `LIVING` block's
-/// `MOVEFLAG_SPLINE_ENABLED` tail (vmangos `Object.cpp:535` → `PacketBuilder::WriteCreate`,
-/// `packet_builder.cpp:152`). Without it, a creature that was walking when we first saw it stands
-/// frozen at its create pose until the server's *next* `SMSG_MONSTER_MOVE` — which then teleports it
-/// to wherever it actually got to (decision 0708).
-///
-/// [`Self::path`] is the **travel-order polyline**, the same shape `MonsterMove` decodes to. The wire
-/// carries the server's raw internal control array (`MoveSpline::getPath()` = `Spline::getPoints()`),
-/// which is *not* that: vmangos builds every spline — linear ones included — through
-/// `SplineBase::InitCatmullRom` ("we should use catmullrom initializer even for linear mode!",
-/// `spline.cpp:52`), so the array is `[phantom, p₀, …, pₙ, tail]` whose walkable range is
-/// `index_lo = 1 ..= index_hi = len − 2` (`spline.cpp:238-270`): the phantom head is `p₀` extrapolated
-/// one segment *backwards*, and the tail duplicates the destination (or, cyclic, closes the loop).
-/// We hand over exactly that range.
+/// The spline a `LIVING` unit is already riding when it streams in (`packet_builder.cpp:152`).
+/// vmangos builds every spline as Catmull-Rom (`spline.cpp:52`), so the wire array is
+/// `[phantom, p₀, …, pₙ, tail]` and [`Self::path`] is its walkable range `1 ..= len − 2`.
 #[derive(Debug, Clone)]
 pub struct CreateSpline {
-    /// The full travel-order polyline in raw WoW coords: `[start, …waypoints…, endpoint]`.
+    /// The travel-order polyline in raw WoW coords, start to endpoint.
     pub path: Vec<[f32; 3]>,
     /// The server's spline id (`MoveSpline::GetId`), as on `MonsterMove`.
     pub id: u32,
-    /// Milliseconds of this spline the server has **already ridden** (`MoveSpline::timePassed`): the
-    /// unit is `time_passed_ms / duration_ms` of the way along `path`, so a client that starts the
-    /// ride at `now − time_passed_ms` lands exactly where the server has it.
+    /// Ms of the path already ridden (`MoveSpline::timePassed`); start the ride at now minus this.
     pub time_passed_ms: u32,
-    /// The whole path's duration in ms (`MoveSpline::Duration` = the spline's length, which vmangos
-    /// initialises in *time* units at one constant velocity — `CommonInitializer`,
-    /// `MoveSpline.cpp:125-135`). Time is therefore uniform in arc length along the whole polyline,
-    /// which is what makes the `time_passed` fraction above exact.
+    /// Duration in ms at one constant speed, time uniform in arc length (`MoveSpline.cpp:125-135`).
     pub duration_ms: u32,
     /// `MoveSplineFlag::Flying`: a 3-D flight path (keep the spline's Z); clear for a ground walk.
     pub flying: bool,
-    /// `MoveSplineFlag::Cyclic` — the server loops this path forever. The app rides it once; a looping
-    /// follow is unbuilt (the same gap `MonsterMove`'s cyclic paths have).
+    /// `MoveSplineFlag::Cyclic`: the server loops this path forever.
     pub cyclic: bool,
-    /// `MoveSplineFlag::Runmode` — and its absence forces walk mode on (decision 1758).
+    /// `MoveSplineFlag::Runmode`; its absence forces walk mode on.
     pub run_mode: bool,
 }
 
 /// A `LIVING` block's live mover state: the `MOVEMENTFLAGS` word and the swim pitch that rides it.
-/// See [`MovementBlock::mover`] for why both are surfaced rather than parsed and dropped.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct MoverState {
-    /// The raw `MOVEMENTFLAGS` word (`CMovement+0x40`) — direction bits, swim, falling, the granted
-    /// modes.
+    /// The raw `MOVEMENTFLAGS` word (`CMovement+0x40`).
     pub flags: u32,
-    /// The **swim pitch** (radians, +up), present on the wire iff `MOVEFLAG_SWIMMING`; `0.0` (level)
-    /// otherwise.
+    /// Swim pitch in radians, +up; on the wire only with `MOVEFLAG_SWIMMING`, else `0.0`.
     pub pitch: f32,
 }
 
-/// The decoded fields a movement block carries: the pose (from its `LIVING`/`HAS_POSITION` flag),
-/// for a `LIVING` block the unit's 6 movement speeds, its live [`CreateSpline`] and (if
-/// `ON_TRANSPORT`) its rider pose, and (if `UPDATE_FLAG_TRANSPORT`) a transport GameObject's path
-/// progress. The rest of the block is parsed and discarded to stay aligned.
+/// The decoded fields of a movement block; the rest is read and discarded to stay aligned.
 pub struct MovementBlock {
     pub position: Option<(Vector3d, f32)>,
-    /// A `LIVING` block's **live `MOVEMENTFLAGS` word** and its **swim pitch** — the mover state this
-    /// unit is *already in* at the moment it streams into view. `None` for a `HAS_POSITION`-only
-    /// block (a GameObject has no mover).
-    ///
-    /// **The reference applies both, byte-VERIFIED** (wow-5875-re §5,
-    /// `system/collision/scratch/create-block-swim-pitch.md`). The create-block apply `0x619320`
-    /// reaches `0x618c30`, which merges the block's flags into `CMovement+0x40` under the same
-    /// `0x75a07dff` mask a relayed `MSG_MOVE_*` uses (`0x618df3`; `SWIMMING`, `FORWARD` and
-    /// `BACKWARD` are all inside it) and then calls the pose commit `0x7c6420`, whose
-    /// `fld [edx+0x34]` / `fst [ecx+0x20]` copies **this pitch** into the mover pitch field
-    /// unconditionally, alongside the position and facing. So a unit that streams in mid-swim is
-    /// pitched on its **first drawn frame** — the apply runs before `0x613e10` has even built the
-    /// model or registered its per-frame render callback.
-    ///
-    /// Dropping the pair is why a player who came into view mid-swim rendered *level* until their
-    /// next relay packet: the body-pitch render law reads exactly these two values and had neither.
-    ///
-    /// The pitch is `0.0` (level) whenever `MOVEFLAG_SWIMMING` is clear, and that is the
-    /// reference's own value, not our convenience: the block field is explicitly zeroed at
-    /// `0x47ec4a` on the non-swimming leg, so the unconditional commit stores a real 0.0 rather
-    /// than stale memory.
+    /// A `LIVING` block's mover state. The reference merges these flags under the relay's
+    /// `0x75a07dff` mask (`0x618c30`) and commits the pitch at once (`0x7c6420`), so a unit
+    /// streaming in mid-swim is pitched on its first frame.
     pub mover: Option<MoverState>,
-    /// A `LIVING` block's 6 movement speeds (yd/s) in wire order `[walk, run, run_back, swim, swim_back,
-    /// turn_rate]`; `None` for a `HAS_POSITION`-only block (GameObjects, which don't move under their
-    /// own power). The animation selector keys walk-vs-run on `walk` (boundary 2× it — RF-0057); the
-    /// net bridge extrapolates a remote mover between packets at `run`/`run_back`/`swim` + `turn_rate`.
+    /// A `LIVING` block's speeds in wire order `[walk, run, run_back, swim, swim_back, turn_rate]`.
     pub speeds: Option<[f32; 6]>,
-    /// A transport GameObject's (`UPDATE_FLAG_TRANSPORT`, 0x02) path progress: the server's ms clock in
-    /// the path domain (vmangos `Object.cpp:590-605` — `GenericTransport::GetPathProgress()`, the same
-    /// `m_pathProgress` `ShipTransport::Update`/`CalculateSegmentPos` key off, `Transports/Transport.cpp:
-    /// 285-301`). `None` for every non-transport object: vmangos raises `UPDATEFLAG_TRANSPORT` only in
-    /// the transport GO paths — `ShipTransport`'s ctor (`Transport.cpp:39`) and the type-11 elevator
-    /// branch of `GameObject::Create` (`GameObject.cpp:246`); units/players never set it
-    /// (`Unit.cpp:88`). This is decision 0438's
-    /// **cycle anchor**: `anchor = this value`, `t₀ = Instant::now()` on create, `progress = anchor +
-    /// elapsed_ms` thereafter.
+    /// A ship's or elevator's path progress in ms at create, the anchor its cycle runs from
+    /// (`Object.cpp:590-605`); no other object sets `UPDATE_FLAG_TRANSPORT`.
     pub transport_progress: Option<u32>,
-    /// A `LIVING` block's rider pose on a transport (`MOVEFLAG_ON_TRANSPORT`, 0x0200_0000) — `Some` when this
-    /// unit/player is standing on a boat/zeppelin/elevator, its position local to that transport's frame
-    /// (decision 0438 "Riding is the mover's platform frame" — an observed rider carried this way
-    /// re-anchors through the transport's live matrix each frame, never treating `pos` as world-space).
+    /// A `LIVING` block's rider pose (`MOVEFLAG_ON_TRANSPORT`), local to the transport's frame.
     pub transport: Option<TransportPose>,
-    /// The path this unit is **already walking** at create time (`MOVEFLAG_SPLINE_ENABLED`) — see
-    /// [`CreateSpline`]. `None` for a unit standing still, and for every non-`LIVING` block.
+    /// The path this unit is already walking at create (`MOVEFLAG_SPLINE_ENABLED`).
     pub spline: Option<CreateSpline>,
 }
 
@@ -178,17 +117,13 @@ impl MovementBlock {
             position = Some((living_position, living_orientation));
 
             if flags & MOVEMENT_FLAG_ON_TRANSPORT != 0 {
-                // A FULL u64, not packed: the LIVING block serializes through the same vmangos
-                // `MovementInfo::Write` as the MSG_MOVE relays (`Object.cpp:524` `*data << m`),
-                // whose `data << t_guid` is the plain-u64 `ObjectGuid` operator.
+                // A full u64, not packed, as in `MovementInfo::Write` (`Object.cpp:524`).
                 transport = Some(TransportPose {
                     guid: read_u64_le(r)?,
                     pos: Vector3d::read(r)?,
                     orientation: read_f32_le(r)?,
                 });
             }
-            // The swim-pitch tail — a lone `f32` present iff `MOVEFLAG_SWIMMING`, the same gate
-            // (and the same position in the layout) the `MSG_MOVE_*` body uses.
             let pitch = if flags & MOVEMENT_FLAG_SWIMMING != 0 {
                 read_f32_le(r)?
             } else {
@@ -204,9 +139,6 @@ impl MovementBlock {
             if flags & MOVEMENT_FLAG_SPLINE_ELEVATION != 0 {
                 let _ = read_f32_le(r)?;
             }
-            // The 6 movement speeds (RF-0058 order): [0]=walk, [1]=run, [2]=run-back, [3]=swim,
-            // [4]=swim-back, [5]=turn-rate. The animation selector keys walk-vs-run on the walk speed
-            // (boundary = 2× it — RF-0057); the net bridge extrapolates a remote mover with the rest.
             let mut s = [0.0f32; 6];
             for slot in &mut s {
                 *slot = read_f32_le(r)?;
@@ -214,10 +146,7 @@ impl MovementBlock {
             speeds = Some(s);
             if flags & MOVEMENT_FLAG_SPLINE_ENABLED != 0 {
                 let spline_flags = read_u32_le(r)?;
-                // The dictated final facing, in vmangos's own angle → target → point order
-                // (`packet_builder.cpp:162-167`). Parsed for alignment only: a unit still riding a
-                // path faces its travel tangent every frame, exactly as `MonsterMove`'s facing snap is
-                // overwritten while a path runs (`net::apply::objects::monster_move`).
+                // The final facing (`packet_builder.cpp:162-167`); a unit on a path faces along it.
                 if spline_flags & SPLINE_FLAG_FINAL_ANGLE != 0 {
                     let _ = read_f32_le(r)?;
                 } else if spline_flags & SPLINE_FLAG_FINAL_TARGET != 0 {
@@ -234,11 +163,9 @@ impl MovementBlock {
                     let v = Vector3d::read(r)?;
                     nodes.push([v.x, v.y, v.z]);
                 }
-                // The final destination trails the array; it is `path`'s last real point again
-                // (`MoveSpline::FinalDestination` = `getPoint(last())`), or zero on a cyclic path.
+                // The final destination repeats the path's last point, or is zero on a cyclic path.
                 let _final_node = Vector3d::read(r)?;
-                // Drop the server's two virtual control points — see [`CreateSpline`]. Fewer than
-                // four nodes cannot hold a two-point path, so there is nothing to ride.
+                // Drop the two virtual control points; under four nodes there is no path to ride.
                 spline = (nodes.len() >= 4).then(|| CreateSpline {
                     path: nodes[1..nodes.len() - 1].to_vec(),
                     id,
diff --git a/crates/benilla-protocol/src/messages/vendor.rs b/crates/benilla-protocol/src/messages/vendor.rs
index 80012a8c..fa12b707 100644
--- a/crates/benilla-protocol/src/messages/vendor.rs
+++ b/crates/benilla-protocol/src/messages/vendor.rs
@@ -1,17 +1,11 @@
-//! Vendor messages — `CMSG_LIST_INVENTORY`/buy/sell (opcodes 414-421, vmangos `Opcodes_1_12_1.h`,
-//! VERIFIED). Bodies from vmangos `Item.{h,cpp}` + the hand-serialized `ItemHandler.cpp`. Lives
-//! beside, not inside, [`super::items`] (the item-*template* query pair): vendor rows carry their
-//! own wire shape and the buy/sell result vocabulary, unrelated to
-//! `SMSG_ITEM_QUERY_SINGLE_RESPONSE`.
+//! Vendor messages: the inventory list, buy and sell (opcodes 414-421), buyback and repair.
 
 use std::io;
 
 use crate::wire::{capacity_hint, read_u32_le, read_u64_le, read_u8};
 
-/// One vendor row (`SMSG_LIST_INVENTORY`, vmangos `ItemHandler.cpp:741-810`). `slot` (the wire's
-/// `muid`) is the row's 1-based position in the vendor's list — **not** what buying uses; buying
-/// addresses the item by [`VendorItem::entry`] (see [`buy_item`]). `current_count` of
-/// `0xFFFF_FFFF` means unlimited stock; `price` is already reputation-discounted server-side.
+/// One vendor row (`ItemHandler.cpp:741-810`): `slot` is the 1-based list position, not what a buy
+/// sends; `current_count` `0xFFFF_FFFF` is unlimited; `price` is already reputation-discounted.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct VendorItem {
     pub slot: u32,
@@ -26,7 +20,7 @@ pub struct VendorItem {
     pub buy_count: u32,
 }
 
-/// `BuyResult` (vmangos `ItemDefines.h:120-141`) — the `u8` reason on `SMSG_BUY_FAILED`.
+/// `BuyResult` (vmangos `ItemDefines.h:120-141`): the `u8` reason on `SMSG_BUY_FAILED`.
 pub mod buy_result {
     pub const CANT_FIND_ITEM: u8 = 0;
     pub const ITEM_ALREADY_SOLD: u8 = 1;
@@ -39,9 +33,7 @@ pub mod buy_result {
     pub const REPUTATION_REQUIRE: u8 = 12;
 }
 
-/// `SellResult` (vmangos `ItemDefines.h:120-141`) — the `u8` reason on `SMSG_SELL_ITEM`. A
-/// *successful* sell sends no packet at all (the item vanishes + coinage rises via
-/// `UPDATE_OBJECT`); only the error path (`SendSellError`, `Player.cpp:11723`) uses this shape.
+/// `SellResult` (vmangos `ItemDefines.h:120-141`): the `u8` reason on `SMSG_SELL_ITEM`.
 pub mod sell_result {
     pub const CANT_FIND_ITEM: u8 = 1;
     pub const CANT_SELL_ITEM: u8 = 2;
@@ -51,16 +43,13 @@ pub mod sell_result {
     pub const ONLY_EMPTY_BAG: u8 = 6;
 }
 
-/// Body of `CMSG_LIST_INVENTORY` (vmangos `Item.cpp:94`): one full 8-byte vendor guid. The server
-/// gates on `UNIT_NPC_FLAG_VENDOR` + the player being alive (`ItemHandler.cpp:693`).
+/// Body of `CMSG_LIST_INVENTORY`: the vendor guid; the dead get no list (`ItemHandler.cpp:693`).
 pub fn list_inventory(vendor_guid: u64) -> Vec<u8> {
     vendor_guid.to_le_bytes().to_vec()
 }
 
-/// Body of `CMSG_BUY_ITEM` (vmangos `Item.cpp:104-110`): `u64 vendorGuid, u32 item` (the template
-/// **entry**, not the vendor row's `muid`), `u8 count` (stacks to buy), `u8 unk1` (always 0).
-/// Auto-places into the first free bag slot — the specific-bag-slot variant is
-/// [`buy_item_in_slot`]. Handler → `BuyItemFromVendor` (`ItemHandler.cpp:688`).
+/// Body of `CMSG_BUY_ITEM` (vmangos `Item.cpp:104-110`): `u64 vendorGuid`, `u32` template entry
+/// (not the row's `muid`), `u8 count` (stacks), `u8 unk1` (0); it fills the first free slot.
 pub fn buy_item(vendor_guid: u64, entry: u32, count: u8) -> Vec<u8> {
     let mut body = Vec::with_capacity(14);
     body.extend_from_slice(&vendor_guid.to_le_bytes());
@@ -70,18 +59,9 @@ pub fn buy_item(vendor_guid: u64, entry: u32, count: u8) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_BUY_ITEM_IN_SLOT` (vmangos `Item.cpp:113-120`): `u64 vendorGuid, u32 item`
-/// (the template **entry**, like [`buy_item`]), `u64 bagGuid`, `u8 bagSlot`, `u8 count`.
-///
-/// The buy-into-a-named-slot variant, and the packet the **merchant cursor** sends: the reference
-/// puts a vendor row on the cursor as payload mode 5 (`PickupMerchantItem 0x4fb760`) and the
-/// three container drop handlers each call the sender `0x5e1f30` with `count = 1`
-/// (wow-re `system/ui/scratch/merchant-cursor-law.md` §5). Clicking a row is the auto-place
-/// [`buy_item`]; dragging it into a slot is this.
-///
-/// `bag_guid` is the **container object's** guid, or the player's own for the backpack and the
-/// equipment slots; `bag_slot` is the destination within it. Handler → `BuyItemFromVendor`, the
-/// same one `CMSG_BUY_ITEM` reaches, with the slot pair filled instead of `NULL_BAG`/`NULL_SLOT`.
+/// Body of `CMSG_BUY_ITEM_IN_SLOT` (vmangos `Item.cpp:113-120`): `u64 vendorGuid`, `u32` template
+/// entry, `u64 bagGuid` (ours for the backpack), `u8 bagSlot`, `u8 count`; the reference sends it
+/// with `count = 1` for a vendor row dropped into a slot (`0x5e1f30`).
 pub fn buy_item_in_slot(
     vendor_guid: u64,
     entry: u32,
@@ -98,8 +78,8 @@ pub fn buy_item_in_slot(
     body
 }
 
-/// Body of `CMSG_SELL_ITEM` (vmangos `Item.cpp:87-92`): `u64 vendorGuid, u64 itemGuid, u8 count`
-/// (0 = sell the whole stack). Handler `ItemHandler.cpp:442`.
+/// Body of `CMSG_SELL_ITEM` (vmangos `Item.cpp:87-92`): `u64 vendorGuid, u64 itemGuid, u8 count`,
+/// where 0 sells the whole stack.
 pub fn sell_item(vendor_guid: u64, item_guid: u64, count: u8) -> Vec<u8> {
     let mut body = Vec::with_capacity(17);
     body.extend_from_slice(&vendor_guid.to_le_bytes());
@@ -108,10 +88,8 @@ pub fn sell_item(vendor_guid: u64, item_guid: u64, count: u8) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_BUYBACK_ITEM` (VERIFIED wow-re ui/scratch/buyback-data-path.md, `0x4fb950`:
-/// `u64 vendorGuid, u32 slot` — the slot is the **absolute** player-array buyback slot 69–80
-/// (`BUYBACK_SLOT_START` + index), sent raw with no re-base; vmangos `HandleBuybackItem` reads it
-/// the same way).
+/// Body of `CMSG_BUYBACK_ITEM` (`0x4fb950`): `u64 vendorGuid, u32 slot`, the absolute buyback
+/// slot 69-80 (`BUYBACK_SLOT_START` + index), not re-based.
 pub fn buyback_item(vendor_guid: u64, slot: u32) -> Vec<u8> {
     let mut body = Vec::with_capacity(12);
     body.extend_from_slice(&vendor_guid.to_le_bytes());
@@ -119,9 +97,7 @@ pub fn buyback_item(vendor_guid: u64, slot: u32) -> Vec<u8> {
     body
 }
 
-/// Body of `CMSG_REPAIR_ITEM` (VERIFIED wow-re ui/scratch/repair-machinery.md, all 4 client send
-/// sites: `u64 vendorGuid, u64 itemGuid`; `itemGuid == 0` = repair everything. vmangos
-/// `HandleRepairItemOpcode` corroborates).
+/// Body of `CMSG_REPAIR_ITEM`: `u64 vendorGuid, u64 itemGuid`; item guid 0 repairs everything.
 pub fn repair_item(vendor_guid: u64, item_guid: u64) -> Vec<u8> {
     let mut body = Vec::with_capacity(16);
     body.extend_from_slice(&vendor_guid.to_le_bytes());
@@ -130,12 +106,8 @@ pub fn repair_item(vendor_guid: u64, item_guid: u64) -> Vec<u8> {
 }
 
 /// Read `SMSG_LIST_INVENTORY` (vmangos `ItemHandler.cpp:741-810`): `u64 vendorGuid, u8 count`
-/// (≤ `MAX_VENDOR_ITEMS` 128) then `count` rows of [`VendorItem`]. The empty-vendor case is
-/// `count = 0` followed by one trailing `u8` — both producers write a literal `uint8(0)`
-/// ("Vendor has no inventory": `ItemHandler.cpp:728-733` for a creature with no item lists,
-/// `:806-809` for one whose every item is hidden from this player). It carries no other value
-/// on this wire, so it is consumed and dropped — consumed *explicitly*, so an empty list leaves
-/// no tail for the decode-length check to report (decision 2265 §B1).
+/// (at most 128), then `count` rows. An empty list is followed by one `u8` 0
+/// (`ItemHandler.cpp:728-733`, `:806-809`), read here so no tail is left over.
 pub(super) fn read_list_inventory(r: &mut &[u8]) -> io::Result<(u64, Vec<VendorItem>)> {
     let vendor_guid = read_u64_le(r)?;
     let count = read_u8(r)?;
@@ -159,11 +131,8 @@ pub(super) fn read_list_inventory(r: &mut &[u8]) -> io::Result<(u64, Vec<VendorI
     Ok((vendor_guid, items))
 }
 
-/// Read `SMSG_BUY_ITEM` (vmangos `Item.cpp:190-196`, sent from `Player.cpp:18637`): `u64
-/// vendorGuid, u32 vendorSlot` (1-based), `u32 newCount` (new stock; `0xFFFF_FFFF` unlimited),
-/// `u32 purchaseCount`. Only updates the vendor stock display — the purchased item itself arrives
-/// through the normal `SMSG_ITEM_PUSH_RESULT` + `UPDATE_OBJECT` path (`SendNewItem`,
-/// `Player.cpp:18644`), which benilla's inventory already handles.
+/// Read `SMSG_BUY_ITEM` (vmangos `Item.cpp:190-196`): `u64 vendorGuid, u32 vendorSlot` (1-based),
+/// `u32 newCount` (`0xFFFF_FFFF` unlimited), `u32 purchaseCount`; the item arrives separately.
 pub(super) fn read_buy_item(r: &mut &[u8]) -> io::Result<(u64, u32, u32, u32)> {
     Ok((
         read_u64_le(r)?,
@@ -174,8 +143,7 @@ pub(super) fn read_buy_item(r: &mut &[u8]) -> io::Result<(u64, u32, u32, u32)> {
 }
 
 /// Read `SMSG_SELL_ITEM` (vmangos `Item.cpp:183-188`): `u64 vendorGuid, u64 itemGuid, u8 reason`
-/// (a [`sell_result`] code). Only the error path sends this packet at all — a successful sell is
-/// silent, visible only as the item's removal + coinage rising via `UPDATE_OBJECT`.
+/// (a [`sell_result`] code). Only a failed sell sends it; a sale shows only in `UPDATE_OBJECT`.
 pub(super) fn read_sell_item(r: &mut &[u8]) -> io::Result<(u64, u64, u8)> {
     Ok((read_u64_le(r)?, read_u64_le(r)?, read_u8(r)?))
 }
diff --git a/crates/benilla-protocol/src/messages/world_state.rs b/crates/benilla-protocol/src/messages/world_state.rs
index b03bf81f..a4e861e7 100644
--- a/crates/benilla-protocol/src/messages/world_state.rs
+++ b/crates/benilla-protocol/src/messages/world_state.rs
@@ -1,56 +1,28 @@
-//! World states — the server's key/value scoreboard table (`SMSG_INIT_WORLD_STATES` `0x2C2`,
-//! `SMSG_UPDATE_WORLD_STATE` `0x2C3`). It is what the NPC-text `$<n>w`/`$<n>e` tokens read, and it
-//! is what a battleground scoreboard is built from; benilla uses the first today.
+//! World states, the server's key/value table (`SMSG_INIT_WORLD_STATES` `0x2C2`,
+//! `SMSG_UPDATE_WORLD_STATE` `0x2C3`) that NPC-text `$<n>w`/`$<n>e` tokens and scoreboards read.
 //!
-//! Both wires are settled from two independent sources that agree:
-//!
-//! - **The reference binary** (wow-re `system/ui/scratch/questtext-macro-expander.md` §3): the one
-//!   handler `0x48f690` holds the only two callers of the table setter `0x4c5870`, registered
-//!   against exactly these two opcodes at `0x48f515-0x48f52f`. `0x2C2` is *two leading dwords*
-//!   (handed to `0x4c5650`), a `u16` count, then `count × (id:u32, value:u32)`; `0x2C3` is a
-//!   single such pair. **`0x4c5650` is carved** (2026-08-25, wow-re
-//!   `system/ui/scratch/worldstate-ui-law.md`): it CLEARS the table, stores the two dwords as the
-//!   world-state UI's display filter, and rebuilds that list — all before the pair loop runs. See
-//!   [`InitWorldStates::zone`].
-//! - **vmangos's writers** (`Player::SendInitWorldStates`, `Player.cpp:8219-8293`, and
-//!   `WorldPackets::Misc::UpdateWorldState::AppendBodyTo`, `Misc.cpp:685-694`): `u32 mapId`,
-//!   `u32 zoneId` (the zone dword is `#if SUPPORTED_CLIENT_BUILD > CLIENT_BUILD_1_11_2`, so 1.12.1
-//!   gets it), the `u16` count back-patched at the end, then the pairs; and `u32 field, u32 value`
-//!   respectively (also build-gated — a pre-1.8.4 client would read `u16`s).
-//!
-//! **The count includes a `(0, 0)` terminator.** vmangos starts `count = 1` and appends
-//! `uint32(0) << uint32(0)` last, *"to prevent repeating audio bug"* — so the pair run is read
-//! verbatim, terminator and all, exactly as the reference's count loop does. There is no
-//! terminator special case on either side and we add none: id 0 simply lands in the table as 0.
-//!
-//! Ids and values are **raw dwords** on the wire and stay raw here. That matters: the reference's
-//! `$<n>e` token reads the table at the *negated* key, so a text asking for `$2077e` looks up
-//! `0xFFFFF7E3` — a key only reachable if nothing has re-interpreted the field on the way in.
+//! On `0x2C2` the reference clears the table and takes map and zone as its UI filter (`0x4c5650`)
+//! before the pairs run. vmangos counts a trailing `(0, 0)` pair (`Player.cpp:8219-8293`), which
+//! is read as data. Ids and values stay raw dwords: `$<n>e` reads the table at the negated key, so
+//! `$2077e` looks up `0xFFFFF7E3`.
 
 use std::io;
 
 use crate::wire::{read_u16_le, read_u32_le};
 
-/// `SMSG_INIT_WORLD_STATES` — the whole table for a zone, sent on login and on every zone change
-/// (vmangos `Player::UpdateZone` → `SendInitWorldStates`).
+/// `SMSG_INIT_WORLD_STATES`: the whole table for a zone, sent on login and every zone change.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct InitWorldStates {
-    /// The map the states are scoped to — the client's `[0xb71e84]`, and the first half of the
-    /// filter its world-state UI list is built against (see the module doc).
+    /// The map the states are scoped to; the reference keeps it at `[0xb71e84]`.
     pub map: u32,
-    /// The second leading dword. Named `zone` for the field vmangos fills it from; the client
-    /// stores it as `[0xb71ea8]` and matches it against **`WorldStateUI.dbc`'s `AreaID`** when it
-    /// decides which always-up rows a scope admits, so "whatever the server put here" is exactly
-    /// the comparand either way.
+    /// The zone vmangos fills in; the reference keeps it at `[0xb71ea8]` and matches it against
+    /// `WorldStateUI.dbc`'s `AreaID`.
     pub zone: u32,
     /// `(id, value)` verbatim, including the trailing `(0, 0)` terminator.
     pub states: Vec<(u32, u32)>,
 }
 
 /// Read `SMSG_INIT_WORLD_STATES`: `u32 map, u32 zone, u16 count`, then `count` `(id, value)` pairs.
-///
-/// The count is trusted only as far as the body allows — a truncated run stops at the short read
-/// like every other reader here, rather than pre-allocating on a hostile length.
 pub(in crate::messages) fn read_init_world_states(r: &mut &[u8]) -> io::Result<InitWorldStates> {
     let map = read_u32_le(r)?;
     let zone = read_u32_le(r)?;
@@ -71,8 +43,6 @@ pub(in crate::messages) fn read_update_world_state(r: &mut &[u8]) -> io::Result<
 mod tests {
     use super::*;
 
-    /// A vmangos-shaped `SMSG_INIT_WORLD_STATES`: map, zone, a count that *includes* the trailing
-    /// `(0, 0)` terminator, then the pairs. The terminator is data, not a sentinel we strip.
     #[test]
     fn init_reads_every_pair_including_the_terminator() {
         let mut body = Vec::new();
@@ -89,7 +59,6 @@ mod tests {
         assert_eq!(got.states, vec![(2264, 7), (2263, 0), (0, 0)]);
     }
 
-    /// A count longer than the body is a short read, not a panic or a giant allocation.
     #[test]
     fn init_truncated_run_errors() {
         let mut body = Vec::new();
@@ -100,8 +69,7 @@ mod tests {
         assert!(read_init_world_states(&mut body.as_slice()).is_err());
     }
 
-    /// The update wire is the bare pair, and both halves stay raw dwords — a value with the top bit
-    /// set survives as-is, so the `%d` render downstream is the only place a sign appears.
+    /// A top-bit value stays unsigned; only the `%d` render downstream gives it a sign.
     #[test]
     fn update_reads_a_raw_dword_pair() {
         let mut body = Vec::new();
diff --git a/crates/benilla-protocol/src/wire.rs b/crates/benilla-protocol/src/wire.rs
index 9023af02..f4aef1a1 100644
--- a/crates/benilla-protocol/src/wire.rs
+++ b/crates/benilla-protocol/src/wire.rs
@@ -1,11 +1,8 @@
-//! Low-level wire read/write helpers shared by the auth ([`crate::auth`]) and world
-//! ([`crate::world`]) protocols. Everything is little endian unless noted; these mirror the exact
-//! field encodings the 1.12 client uses.
+//! Wire read/write helpers shared by the auth and world protocols; little endian unless noted.
 
 use std::io::{self, Read, Write};
 
-/// WoW packs an 8-byte GUID as a one-byte mask (which of the 8 bytes are non-zero) followed by only
-/// those non-zero bytes, low to high — used throughout the world protocol for object references.
+/// Read a packed GUID: a mask byte naming the non-zero bytes, then only those bytes, low to high.
 pub fn read_packed_guid(r: &mut impl Read) -> io::Result<u64> {
     let mask = read_u8(r)?;
     let mut guid = 0u64;
@@ -92,19 +89,8 @@ pub fn read_cstring(r: &mut impl Read) -> io::Result<String> {
     Ok(String::from_utf8_lossy(&bytes).into_owned())
 }
 
-/// Bound a wire-derived element count before it becomes a `Vec::with_capacity` hint.
-///
-/// A count read off the wire is server- (and so bug- and attacker-) controlled, and
-/// `Vec::with_capacity(count as usize)` on a raw `u32` is the one failure the decoders' `io::Result`
-/// totality does not cover: an allocation that cannot be satisfied is `handle_alloc_error` →
-/// `abort()` — no unwind, no [`crate::Poll::Skipped`], no tally (decision 2265 §B1). The returned
-/// hint bounds only the **up-front** allocation: the `Vec` still grows past it when the body really
-/// carries more rows, and a lying count still fails on the short read of the body, which is
-/// `u16`-bounded and read whole before parse. `cap` is the protocol's own bound where one exists
-/// (cited at the call site), or a generous sane one where none does.
-///
-/// Every `with_capacity` under `messages/` whose argument is a wire count goes through this; the
-/// source-scan test beside it (`wire_count_capacity_hints_are_capped`) keeps that true.
+/// Bound a wire-derived count before it becomes a `Vec::with_capacity` hint: a failed allocation
+/// aborts rather than erroring. `cap` is the protocol's own bound where one exists.
 pub fn capacity_hint(count: impl TryInto<u64>, cap: usize) -> usize {
     count
         .try_into()
@@ -137,11 +123,8 @@ impl Vector3d {
     }
 }
 
-/// Decode a movement-spline packed point (`SMSG_MONSTER_MOVE` packs every point after the first this
-/// way): **signed** two's-complement fields — 11 bits x, 11 bits y, 10 bits z — in quarter-yard
-/// units (the server packs `round(v * 4)` per axis; vmangos `ByteBuffer::appendPackXYZ`). The
-/// decoded vector is the offset from the spline's **destination** back to this waypoint
-/// (`destination - waypoint`; vmangos `PacketBuilder::WriteLinearPath`), not an absolute position.
+/// Decode a `SMSG_MONSTER_MOVE` packed point: signed 11-bit x, 11-bit y, 10-bit z in quarter yards
+/// (`ByteBuffer::appendPackXYZ`), the offset `destination - waypoint`, not a position.
 pub fn packed_to_vector3d(p: i32) -> Vector3d {
     // Sign-extend each field: shift it to the top of the i32, then arithmetic-shift back down.
     Vector3d {
@@ -155,8 +138,7 @@ pub fn packed_to_vector3d(p: i32) -> Vector3d {
 mod tests {
     use super::*;
 
-    /// The producer's encoder, transcribed from vmangos `ByteBuffer::appendPackXYZ`:
-    /// `packed |= ((int)lroundf(v * 4.0f) & mask) << shift` with masks 0x7FF/0x7FF/0x3FF.
+    /// vmangos's encoder, `ByteBuffer::appendPackXYZ`.
     fn pack_xyz(x: f32, y: f32, z: f32) -> i32 {
         let mut packed = 0u32;
         packed |= ((x * 4.0).round() as i32 & 0x7FF) as u32;
@@ -167,9 +149,7 @@ mod tests {
 
     #[test]
     fn packed_point_roundtrips_signed_quarter_yards() {
-        // Field ranges: x/y are 11-bit signed (−256 .. 255.75 yd), z 10-bit signed (−128 .. 127.75 yd).
-        // Quarter-yard multiples are exact in f32, so the round-trip must be exact — including the
-        // negative offsets the old unsigned decode destroyed.
+        // x and y span −256..255.75 yd, z −128..127.75 yd; quarter yards are exact in f32.
         for &(x, y, z) in &[
             (0.0f32, 0.0f32, 0.0f32),
             (1.25, -2.5, 3.75),
@@ -190,16 +170,10 @@ mod tests {
         assert_eq!(capacity_hint(u64::MAX, 1024), 1024);
     }
 
-    /// **The rule, enforced instead of remembered** (decision 2265 §B1).
-    ///
-    /// A `Vec::with_capacity` whose argument is a raw wire count aborts the process — not the
-    /// packet — the day a server (or a decoder bug) puts a huge number there: an allocation
-    /// failure never unwinds, so it never becomes `Poll::Skipped`. There is no runtime signal to
-    /// test for, which is exactly why the check is structural: every `with_capacity(` under
-    /// `messages/` whose argument is a bare variable (cast or not) must go through
-    /// [`capacity_hint`] or carry a `.min(`, or be named in [`EXEMPT`] with the reason.
+    /// Every `with_capacity` under `messages/` whose argument is a bare variable goes through
+    /// [`capacity_hint`], carries a `.min(`, or is listed in [`EXEMPT`].
     #[test]
-    fn wire_count_capacity_hints_are_capped() {
+    fn bare_variable_capacity_hints_under_messages_are_capped() {
         let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/messages");
         let mut offenders = Vec::new();
         for file in rust_files(&root) {
@@ -221,20 +195,16 @@ mod tests {
              process instead of skipping the packet. Bound each with \
              `crate::wire::capacity_hint(count, CAP)` (CAP = the protocol's own bound, cited at \
              the site, or a generous sane one), or add it to `EXEMPT` in `wire.rs` with the reason \
-             it is not a wire count (decision 2265 §B1):\n  {}",
+             it is not a wire count:\n  {}",
             offenders.join("\n  ")
         );
     }
 
-    /// `with_capacity` arguments under `messages/` that look like bare variables but are **not**
-    /// wire counts, each with the reason. Keyed `(path under src/messages/, argument text)`.
+    /// Bare-variable arguments that are not wire counts, as `(path under src/messages/, argument)`.
     const EXEMPT: &[(&str, &str)] = &[];
 
-    /// The classifier, pinned on synthetic arguments so a regression in it cannot pass silently
-    /// as "nothing to flag".
     #[test]
     fn the_scan_flags_a_bare_wire_count_and_passes_a_bounded_one() {
-        // Flagged: a bare variable, with or without the cast, however it is wrapped.
         for arg in [
             "count as usize",
             "count",
@@ -245,7 +215,6 @@ mod tests {
         ] {
             assert!(uncapped_wire_count(arg), "should flag `{arg}`");
         }
-        // Passes: literals, length arithmetic, a constant, and the two bounded forms.
         for arg in [
             "12",
             "name.len() + 1",
@@ -259,7 +228,6 @@ mod tests {
         ] {
             assert!(!uncapped_wire_count(arg), "should pass `{arg}`");
         }
-        // The extractor: the balanced argument of every call on the line, with its line number.
         let src = "let a = Vec::with_capacity(count as usize);\nlet b = Vec::with_capacity((n as usize).min(4));\n";
         assert_eq!(
             capacity_arguments(src),
@@ -270,9 +238,7 @@ mod tests {
         );
     }
 
-    /// Is this `with_capacity` argument a raw wire count? A bare identifier (optionally cast
-    /// `as usize`, optionally parenthesised, optionally `usize::from(...)`-wrapped) that is not a
-    /// `const` (all caps) and carries neither `.min(` nor `capacity_hint(`.
+    /// A lowercase identifier, however cast or wrapped, with no `.min(` or `capacity_hint(`.
     fn uncapped_wire_count(arg: &str) -> bool {
         if arg.contains(".min(") || arg.contains("capacity_hint(") {
             return false;
@@ -330,7 +296,6 @@ mod tests {
         out
     }
 
-    /// Every `.rs` file under `root`, recursively.
     fn rust_files(root: &std::path::Path) -> Vec<std::path::PathBuf> {
         let mut out = Vec::new();
         let mut stack = vec![root.to_path_buf()];
diff --git a/crates/benilla-protocol/src/world/mod.rs b/crates/benilla-protocol/src/world/mod.rs
index 56db9e81..9ee98433 100644
--- a/crates/benilla-protocol/src/world/mod.rs
+++ b/crates/benilla-protocol/src/world/mod.rs
@@ -1,18 +1,8 @@
-//! Phase 4: world server (`mangosd`) connection.
+//! The world server (`mangosd`) connection, opened with the realm logon's SRP6 session key.
 //!
-//! After the realmd logon ([`crate::logon`]) hands us the SRP6 session key, we connect to the world
-//! server, prove we know that key, then stream object updates. The handshake:
-//!
-//! 1. Read `SMSG_AUTH_CHALLENGE` (unencrypted) → server seed.
-//! 2. Send `CMSG_AUTH_SESSION` (unencrypted): build, uppercased account name, a client seed, and a
-//!    SHA1 digest binding the session key to both seeds (computed by `benilla-srp`).
-//! 3. **1.12 header obfuscation turns on right after** `CMSG_AUTH_SESSION` — every subsequent packet
-//!    header (4-byte server / 6-byte client) is encrypted; bodies stay plaintext. The first encrypted
-//!    packet we read is `SMSG_AUTH_RESPONSE`.
-//! 4. `CMSG_CHAR_ENUM` → `SMSG_CHAR_ENUM`, then `CMSG_PLAYER_LOGIN(guid)`, then the world streams
-//!    `SMSG_UPDATE_OBJECT`.
-//!
-//! Headers are (de)crypted by [`benilla_srp::vanilla_header`]; bodies by [`crate::messages`].
+//! `SMSG_AUTH_CHALLENGE` (server seed) and `CMSG_AUTH_SESSION` (build, uppercased account, client
+//! seed, SHA1 over key and seeds) travel plain; every header after them is encrypted (4-byte
+//! server, 6-byte client), bodies never, starting with `SMSG_AUTH_RESPONSE`.
 
 use std::io::{Read, Write};
 use std::net::TcpStream;
@@ -31,14 +21,10 @@ pub use reader::WorldReader;
 pub use session::{WardenRequired, WorldAuthReject, WorldSession};
 pub use writer::WorldWriter;
 
-/// Default `mangosd` world-server port — the stock one, which our vmangos deploy maps straight
-/// through. Normally the realm list reply carries the port (the deploy's
-/// `VMANGOS_REALMLIST_PORT=8085` matches); this constant is the fallback for probes/examples that
-/// dial the world server directly.
+/// The stock `mangosd` port, for probes that dial the world server without a realm list.
 pub const WORLD_PORT: u16 = 8085;
 
-/// Read one server packet from `stream`: decrypt the 4-byte header, read the body, parse by opcode.
-/// `decrypter` is `None` for the (single) unencrypted `SMSG_AUTH_CHALLENGE`.
+/// Read, decrypt and parse one packet; `decrypter` is `None` only for `SMSG_AUTH_CHALLENGE`.
 pub(super) fn recv_packet(
     stream: &mut TcpStream,
     decrypter: Option<&mut DecrypterHalf>,
@@ -61,8 +47,7 @@ pub(super) fn recv_packet(
     messages::parse_server(opcode, &body).map_err(|e| anyhow!("parsing opcode {opcode:#x}: {e}"))
 }
 
-/// Write one client packet: an (optionally encrypted) 6-byte header + plaintext body. The header size
-/// field counts the 4-byte opcode plus the body, but not the size field itself.
+/// Write one client packet: a 6-byte header, its size counting opcode and body, then the body.
 pub(super) fn send_packet(
     stream: &mut TcpStream,
     encrypter: Option<&mut EncrypterHalf>,
@@ -79,12 +64,7 @@ pub(super) fn send_packet(
     if let Some(e) = encrypter {
         e.encrypt(&mut header);
     }
-    // **One write, not two** (decision 0617). Header-then-body was a self-inflicted Nagle stall: the
-    // 6-byte header goes out as its own segment, and the body — small, and now behind unacknowledged
-    // data — is held by the kernel until the server ACKs it. With Nagle now off (see
-    // [`WorldSession::connect`]) that stall is gone either way, but two segments per packet is still
-    // two syscalls and two headers for a ≤40-byte message, and the server cannot parse the packet
-    // until both land. Joined here so one movement report is one segment.
+    // One write, not two: header and body leave as one segment.
     let mut packet = Vec::with_capacity(header.len() + body.len());
     packet.extend_from_slice(&header);
     packet.extend_from_slice(body);
diff --git a/crates/benilla-protocol/src/world/movement.rs b/crates/benilla-protocol/src/world/movement.rs
index b708209f..967434a9 100644
--- a/crates/benilla-protocol/src/world/movement.rs
+++ b/crates/benilla-protocol/src/world/movement.rs
@@ -1,18 +1,10 @@
 use crate::messages::MovementInfo;
 use crate::wire::Vector3d;
 
-/// `MovementFlags::FORWARD` — the only movement flag benilla sets.
 pub(super) const MOVEMENT_FLAG_FORWARD: u32 = 0x1;
 
-/// A monotonic **client-uptime** millisecond stamp for the `MovementInfo` time field — the kind the real
-/// 1.12 client sends (`GetTickCount()`, ms since the client started), **not** wall-clock. vmangos reads it
-/// into `MovementInfo::ctime` and uses it only two ways (VERIFIED, decision 0057): a non-zero guard
-/// (`ctime == 0` reads as "not a client packet" and *pauses* its movement extrapolation) and *deltas*
-/// (`getMSTimeDiff`, so the epoch cancels). It never compares the value to its own clock, and it
-/// overwrites the field with its server clock before relaying to nearby players — so this value never
-/// reaches observers. Hence: match the real client's clock kind, wrap cleanly as a full `u32` (~49.7 days,
-/// which `getMSTimeDiff` handles), and keep it non-zero. (The old value was wall-clock masked to 31 bits,
-/// which folded backwards every ~24.85 days — a delta glitch the clean `u32` wrap avoids.)
+/// Ms since start for the `MovementInfo` time, as the 1.12 client's `GetTickCount()`, never 0:
+/// vmangos pauses extrapolation on 0 and otherwise uses only deltas, so a full `u32` wrap is safe.
 pub(super) fn client_uptime_ms() -> u32 {
     use std::sync::OnceLock;
     use std::time::Instant;
@@ -20,7 +12,7 @@ pub(super) fn client_uptime_ms() -> u32 {
     (START.get_or_init(Instant::now).elapsed().as_millis() as u32).max(1)
 }
 
-/// Build a `MovementInfo` stamped with the client-uptime time ([`client_uptime_ms`]).
+/// Build a `MovementInfo` stamped with [`client_uptime_ms`].
 pub(super) fn movement_info(pos: [f32; 3], orientation: f32, flags: u32) -> MovementInfo {
     MovementInfo {
         flags,
@@ -31,11 +23,9 @@ pub(super) fn movement_info(pos: [f32; 3], orientation: f32, flags: u32) -> Move
             z: pos[2],
         },
         orientation,
-        // benilla never sets ON_TRANSPORT outbound yet (boarding/riding is decision 0438 phase 2) — the
-        // writer only emits the transport tail while the flag is set, so this is always dropped.
+        // Written only under ON_TRANSPORT, which benilla does not send.
         transport: None,
-        // Level swim (0) by default; the writer only emits the pitch tail while SWIMMING is set, and the
-        // controller supplies the live swim pitch through `send_movement` when it does.
+        // Written only under SWIMMING; `send_movement` supplies the live pitch then.
         pitch: 0.0,
         fall_time: 0,
         jump: None,
@@ -46,15 +36,13 @@ pub(super) fn movement_info(pos: [f32; 3], orientation: f32, flags: u32) -> Move
 mod tests {
     use super::*;
 
+    /// Never 0, and a stamp taken right after is not smaller; it wraps at `u32::MAX` ms.
     #[test]
-    fn client_uptime_ms_is_nonzero_and_monotonic() {
-        // The load-bearing property: vmangos treats `ctime == 0` as "not a client packet" and pauses its
-        // extrapolation, so our stamp must never be zero (the bug the old wall-clock value worked around).
-        // It must also be non-decreasing so `getMSTimeDiff` deltas stay sane.
+    fn client_uptime_ms_is_nonzero_and_back_to_back_calls_do_not_decrease() {
         let a = client_uptime_ms();
         let b = client_uptime_ms();
         assert!(a >= 1, "stamp is non-zero: {a}");
-        assert!(b >= a, "stamp is monotonic non-decreasing: {a} -> {b}");
+        assert!(b >= a, "the next stamp is not smaller: {a} -> {b}");
     }
 
     #[test]
diff --git a/crates/benilla-protocol/src/world/reader.rs b/crates/benilla-protocol/src/world/reader.rs
index 480f574f..35e0b716 100644
--- a/crates/benilla-protocol/src/world/reader.rs
+++ b/crates/benilla-protocol/src/world/reader.rs
@@ -8,8 +8,7 @@ use crate::messages::{self, ServerPacket};
 
 use super::recv_packet;
 
-/// Read half of a split [`WorldSession`](super::WorldSession) — owns a cloned socket + the decrypter. Lives on the network
-/// thread, streaming decoded [`crate::SessionEvent`]s (via [`Self::poll`]).
+/// The read half of a split [`WorldSession`](super::WorldSession): cloned socket and decrypter.
 pub struct WorldReader {
     pub(super) stream: TcpStream,
     pub(super) decrypter: DecrypterHalf,
@@ -21,13 +20,8 @@ impl WorldReader {
         recv_packet(&mut self.stream, Some(&mut self.decrypter))
     }
 
-    /// Read one packet and decode it into a [`crate::Poll`]: the typed [`crate::SessionEvent`]s it
-    /// produced, or [`crate::Poll::Skipped`] for an unparseable one. Errors only on a real socket
-    /// failure (disconnect). The running world model lives in the ECS — the reader is stateless,
-    /// turning bytes into events and nothing more.
-    ///
-    /// `recv_packet` reads the whole body into a buffer before parsing, so a parse error leaves the
-    /// stream aligned — we skip that packet rather than tear down the session.
+    /// Read one packet and decode it into a [`crate::Poll`]; errors only when the socket fails. The
+    /// whole body is read before parsing, so an unparseable packet is skipped, the stream aligned.
     pub fn poll(&mut self) -> Result<crate::Poll> {
         let mut header = [0u8; 4];
         if let Err(e) = self.stream.read_exact(&mut header) {
@@ -47,9 +41,6 @@ impl WorldReader {
                 events: crate::decode(packet),
                 tail,
             }),
-            // Include the raw body (capped) so an unparseable packet can be decoded by hand — a parse
-            // bug is otherwise invisible past "failed to fill whole buffer". The opcode rides
-            // separately so the net thread can feed the app's dropped-packet tally.
             Err(e) => Ok(crate::Poll::Skipped {
                 opcode,
                 reason: format!(
@@ -62,8 +53,7 @@ impl WorldReader {
     }
 }
 
-/// Space-separated hex of the first `max` bytes of `body` (with a `…` when truncated) — the diagnostic
-/// tail on a [`crate::Poll::Skipped`] reason so an unparseable packet's layout can be decoded by hand.
+/// Hex of the first `max` bytes of `body`, `…` when truncated, for decoding a packet by hand.
 fn hex_preview(body: &[u8], max: usize) -> String {
     use std::fmt::Write;
     let mut s = String::new();
diff --git a/crates/benilla-protocol/src/world/session.rs b/crates/benilla-protocol/src/world/session.rs
index b05b6717..9a8e529d 100644
--- a/crates/benilla-protocol/src/world/session.rs
+++ b/crates/benilla-protocol/src/world/session.rs
@@ -11,45 +11,21 @@ use super::reader::WorldReader;
 use super::writer::WorldWriter;
 use super::{recv_packet, send_packet};
 
-/// Socket read timeout for the handshake phase only (connect → `player_login`), where each step
-/// waits for one specific server reply and silence means the session is dead (decision 0065).
-/// Generous — a local vmangos answers in milliseconds; this only bounds the pathological stall.
+/// Read timeout through `player_login`, where each step awaits one reply.
 const HANDSHAKE_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
 
-/// The read bound while **queued** — a different question from the handshake's.
-///
-/// [`HANDSHAKE_READ_TIMEOUT`] is 10 s because every handshake step should answer promptly. Sitting
-/// in a login queue is the one step that should not: the server speaks when our place moves, which
-/// on a full realm can be minutes apart. Keeping the handshake bound would abort every queue that
-/// mattered. The real client bounds this not at all (it is event-driven and simply waits), but an
-/// unbounded blocking read here would make a server that dies mid-queue indistinguishable from a
-/// long wait, so the wait is generous rather than infinite.
+/// Read timeout in the login queue, where updates can be minutes apart. Deviation: the reference
+/// waits forever; a bound tells a server that died mid-queue from a long wait.
 const QUEUE_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(300);
 
-/// The server requires Warden, which benilla does not implement — raised by
-/// [`WorldSession::connect`] and recoverable through the `anyhow` chain with
-/// `err.downcast_ref::<WardenRequired>()`, so the login screen can say so plainly.
-///
-/// VERIFIED (vmangos `src/game/Anticheat/WardenAnticheat/Warden.cpp`): every Warden request arms a
-/// response clock (`BeginTimeoutClock`, `Warden.ClientResponseDelay` — default 30 s in
-/// `World.cpp`), and `Warden::Update` kicks unconditionally when it expires — not subject to the
-/// penalty config, and regardless of module/maiev mode. So a client that cannot answer cannot stay
-/// in the world: refusing at the handshake is the honest outcome, not a policy choice.
+/// The server requires Warden. Deviation: benilla does not implement it; vmangos ships with it
+/// off (`Warden.WinEnabled`, `Warden.OSXEnabled`). vmangos kicks a client that leaves a Warden
+/// request unanswered for 30 s (`Warden.cpp`), so the connect refuses.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct WardenRequired;
 
-/// The **world server** refused the session (`SMSG_AUTH_RESPONSE` with anything but
-/// [`messages::AUTH_OK`]).
-///
-/// Typed, and carrying its raw code, for the same reason [`crate::AuthReject`] is: the screen owes
-/// the player the client's own authored words for what happened, and it cannot look them up from a
-/// formatted string. Before this the code was interpolated into a `bail!` and thrown away, so every
-/// world-side refusal — expired session, server shutting down, already logging in — arrived at the
-/// login screen as the same generic "Unable to connect".
-///
-/// **Its codes are `messages`' `AUTH_*` block, NOT [`crate::AuthReject`]'s.** See that block for
-/// why the distinction is load-bearing: the two enums overlap numerically and mean unrelated
-/// things.
+/// The world server refused the session. Its code is from `messages`' `AUTH_*` block, not
+/// [`crate::AuthReject`]'s, whose numbers overlap with unrelated meanings.
 #[derive(Debug, Clone, Copy)]
 pub struct WorldAuthReject {
     pub code: u8,
@@ -82,31 +58,23 @@ impl std::error::Error for WardenRequired {}
 pub struct WorldSession {
     stream: TcpStream,
     crypto: HeaderCrypto,
-    /// The roster's guid → race, remembered from [`Self::char_enum`] so [`Self::player_login`]
-    /// can derive the character's faction tongue without the caller's help.
+    /// Roster guid to race, so [`Self::player_login`] can pick the chat language.
     roster_races: std::collections::HashMap<u64, u8>,
-    /// The language chat sends speak — the logged-in character's faction tongue
-    /// ([`messages::faction_language`]), set automatically by [`Self::player_login`]. Load-bearing:
-    /// vmangos drops any chat whose language the character doesn't know (dot-commands included) —
-    /// hardcoded Common silently ate every Horde character's chat and commands once.
+    /// The language chat sends speak, the character's faction tongue: vmangos drops chat, even
+    /// dot-commands, in a language the character does not know.
     chat_language: u32,
-    /// The rested billing minutes the admitting `SMSG_AUTH_RESPONSE` carried, or `0` when its body
-    /// was too short for the billing group. Read by [`Self::billing_time_rested`]; see decision
-    /// 1820 for why `0` rather than the client's own uninitialised-global behaviour.
+    /// The rested billing minutes the admitting `SMSG_AUTH_RESPONSE` carried. Deviation: `0` when
+    /// the body is too short, where the reference leaves its global as it was; this field lives
+    /// per connection, with nothing earlier to keep.
     billing_time_rested: u32,
-    /// `SMSG_TUTORIAL_FLAGS` if it landed during the login handshake rather than in the world
-    /// stream (decision 1976) — handed to the world entry the way the billing minutes are.
+    /// `SMSG_TUTORIAL_FLAGS` when it lands during the handshake rather than in the world stream.
     tutorial_flags: Option<Vec<u8>>,
-    /// `SMSG_ADDON_INFO`'s per-record `status` bytes, in arrival order — `None` until the server
-    /// answers our addon block, which is the state that keeps the Lua index space empty
-    /// (decision 2175). Read by [`Self::take_addon_info`].
+    /// `SMSG_ADDON_INFO`'s per-record status bytes in order; `None` until the server answers.
     addon_info: Option<Vec<u8>>,
 }
 
 impl WorldSession {
-    /// Connect to the world server and complete the auth handshake, leaving header obfuscation
-    /// enabled. `username` must be the same account used at logon; `session_key` is what
-    /// [`crate::logon`] returned.
+    /// Connect and complete the auth handshake with the logon's account and session key.
     pub fn connect(
         addr: impl ToSocketAddrs,
         username: &str,
@@ -115,19 +83,9 @@ impl WorldSession {
         Self::connect_queued(addr, username, session_key, &mut |_| true)
     }
 
-    /// [`Self::connect`], reporting our place in the **login queue** as it moves.
-    ///
-    /// `on_queue` fires once per `AUTH_WAIT_QUEUE` the server sends — `None` when the packet
-    /// carried no readable position — and the call returns only once we are admitted (`AUTH_OK`),
-    /// refused, or the socket fails. The queue is a wait, not an outcome, so it is a callback
-    /// rather than a return value: the screen has to be able to show the position *while* the
-    /// handshake is still parked here.
-    ///
-    /// **Returning `false` abandons the queue** and fails the connect. That is the only way out of
-    /// a wait that can last minutes: every other stage of the handshake is bounded tightly enough
-    /// that a cancel is honoured at its next boundary, and a queue is not. Abandoning is checked
-    /// once per packet rather than per frame — the reference tears the socket down on the next
-    /// tick, which is finer-grained, but it costs a player at most one server update.
+    /// [`Self::connect`], calling `on_queue` with each queue position; `false` abandons the queue.
+    /// Deviation: checked per queue packet where the reference checks each tick, so a cancel can
+    /// lag one server update.
     pub fn connect_queued(
         addr: impl ToSocketAddrs,
         username: &str,
@@ -136,33 +94,20 @@ impl WorldSession {
     ) -> Result<Self> {
         let mut queued = false;
         let mut stream = TcpStream::connect(addr).context("connecting to world server")?;
-        // **Nagle off** (decision 0617). VERIFIED in the reference client: `0x5bca60` calls
-        // `setsockopt(s, 6 /* IPPROTO_TCP */, 1 /* TCP_NODELAY */, &1, 4)` unconditionally on its game
-        // socket (WSOCK32 ordinal 21, IAT slot `0x7ff6f8`; a sibling helper at `0x43dda0` toggles the
-        // same option from a bool). Rust leaves Nagle *on*, which is exactly wrong for this protocol:
-        // every packet we send is a sub-MSS write on a latency-critical stream, so the kernel holds
-        // each one until the server ACKs the last — coalescing our movement stream into delayed-ACK-
-        // sized clumps. The de-jitter chain on the observing client then sizes its buffer to that
-        // self-inflicted lateness (decision 0615). Fatal on failure: the option cannot fail on a
-        // healthy connected socket, so an error here means the next handshake write is doomed anyway —
-        // better one named failure than a session that silently plays at delayed-ACK cadence.
+        // Nagle off: the reference sets `TCP_NODELAY` on its game socket (`0x5bca60`).
         stream
             .set_nodelay(true)
             .context("disabling Nagle (TCP_NODELAY) on the world socket")?;
-        // Handshake reads wait for one specific reply each — silence is failure, so bound them
-        // (decision 0065). A server that stays connected but never answers must not wedge the net
-        // thread forever. Cleared in `into_split` for the streaming phase (a quiet world is legal).
+        // `into_split` clears this for the streaming phase, where a quiet world is legal.
         stream
             .set_read_timeout(Some(HANDSHAKE_READ_TIMEOUT))
             .context("setting handshake read timeout")?;
 
-        // 1. SMSG_AUTH_CHALLENGE (unencrypted) carries the server seed.
         let server_seed = match recv_packet(&mut stream, None)? {
             ServerPacket::AuthChallenge { server_seed } => server_seed,
             other => bail!("expected SMSG_AUTH_CHALLENGE, got {}", other.name()),
         };
 
-        // 2. Bind the session key to (server_seed, our client_seed) → proof + header crypto.
         let username_n =
             NormalizedString::new(username).map_err(|e| anyhow!("invalid username: {e}"))?;
         let seed = ProofSeed::new();
@@ -170,10 +115,8 @@ impl WorldSession {
         let (client_proof, crypto) =
             seed.into_client_header_crypto(&username_n, session_key, server_seed);
 
-        // 3. CMSG_AUTH_SESSION goes out unencrypted; obfuscation begins immediately after.
-        // The addon block is the tail of this packet and is NOT optional: cmangos-classic kicks a
-        // session whose addon size is zero, which is what benilla used to send (B277, decision
-        // 1497). `STOCK_SECURE_ADDONS` is what a stock 1.12.1 install reports.
+        // Sent plain; header encryption starts right after. The addon block is required (cmangos
+        // kicks a zero-size one); `STOCK_SECURE_ADDONS` is what a stock 1.12.1 install reports.
         let body = messages::auth_session(
             u32::from(crate::CLIENT_BUILD),
             &username.to_uppercase(),
@@ -194,15 +137,7 @@ impl WorldSession {
             addon_info: None,
         };
 
-        // 4. Wait for SMSG_AUTH_RESPONSE. Usually the first encrypted packet, but not always first
-        // on the wire, so skip interleaved packets (as `char_enum` does) rather than demanding
-        // AUTH_RESPONSE lead. Each read is still bounded by the handshake timeout, so a server that
-        // never answers still fails per decision 0065.
-        //
-        // SMSG_WARDEN_DATA among them ends the connection here: it means the server runs Warden,
-        // whose response clock kicks us ~30 s later no matter what else we do ([`WardenRequired`]).
-        // Refusing at the handshake trades an unplayable 30-second kick/reconnect cycle for one
-        // honest message at the login screen.
+        // AUTH_RESPONSE is not always first, so others are skipped; Warden data ends the connect.
         loop {
             match session.recv()? {
                 ServerPacket::AuthResponse {
@@ -210,16 +145,11 @@ impl WorldSession {
                     billing_time_rested,
                     ..
                 } if result == messages::AUTH_OK => {
-                    // The admitting packet is the only one that counts: a queue packet carries the
-                    // group too, but the client re-reads it on every AUTH_RESPONSE and the last one
-                    // wins, which is this one.
+                    // The reference keeps the last AUTH_RESPONSE's billing group.
                     session.billing_time_rested = billing_time_rested.unwrap_or(0);
                     break;
                 }
-                // **Queued, not refused** — the realm is full and we keep our place in line. Report
-                // the position and go back to reading; the server re-sends as we move up and ends
-                // the wait with an `AUTH_OK`. Treating this as an ending (which it was until now)
-                // meant benilla could not log into a busy server at all.
+                // Queued, not refused: the server re-sends as we move up and ends with `AUTH_OK`.
                 ServerPacket::AuthResponse {
                     result,
                     queue_position,
@@ -244,8 +174,7 @@ impl WorldSession {
                 _ => continue,
             }
         }
-        // Admitted. The rest of the handshake is prompt again, so it gets the prompt bound back —
-        // leaving the queue's 300 s in place would make a stalled roster step look like a long wait.
+        // Admitted: the rest of the handshake is prompt again.
         if queued {
             session
                 .set_read_timeout(Some(HANDSHAKE_READ_TIMEOUT))
@@ -255,24 +184,17 @@ impl WorldSession {
         Ok(session)
     }
 
-    /// The account's accumulated **rested billing minutes**, from the `SMSG_AUTH_RESPONSE` that
-    /// admitted this session — what `GetBillingTimeRested()` reports (decision 1820).
-    ///
-    /// Against vmangos this is always `0`: the server hardcodes `uint32(0)` for the field
-    /// (`World.cpp:331`, and `:380` for the queue packet), guarded on a build newer than 1.7.1,
-    /// which 1.12 is. It is read from the wire rather than assumed so that a server which does
-    /// populate it is reported honestly.
+    /// Rested billing minutes (`GetBillingTimeRested`); always 0 from vmangos (`World.cpp:331`).
     pub fn billing_time_rested(&self) -> u32 {
         self.billing_time_rested
     }
 
-    /// The tutorial bank captured during the login handshake, if any (decision 1976).
+    /// The tutorial bank captured during the login handshake, if any.
     pub fn take_tutorial_flags(&mut self) -> Option<Vec<u8>> {
         self.tutorial_flags.take()
     }
 
-    /// Set a read timeout on the underlying socket (e.g. so a debug read-loop can stop when the
-    /// world goes quiet). `None` clears it (blocking reads).
+    /// Set the socket's read timeout; `None` makes reads block.
     pub fn set_read_timeout(&self, timeout: Option<std::time::Duration>) -> Result<()> {
         self.stream
             .set_read_timeout(timeout)
@@ -282,20 +204,15 @@ impl WorldSession {
     /// Read + decrypt + parse one server packet.
     pub fn recv(&mut self) -> Result<ServerPacket> {
         let packet = recv_packet(&mut self.stream, Some(self.crypto.decrypter()))?;
-        // **Captured here rather than in a loop arm**, because it is not one loop's business:
-        // `SMSG_ADDON_INFO` lands somewhere between `CMSG_AUTH_SESSION` and the roster, and which
-        // of the handshake's three read loops sees it is the server's timing, not our contract.
-        // `recv` is the one place all of them go through (decision 2175).
+        // `SMSG_ADDON_INFO` can reach any of the handshake's read loops, so it is caught here.
         if let ServerPacket::AddonInfo { statuses } = &packet {
             self.addon_info = Some(statuses.clone());
         }
         Ok(packet)
     }
 
-    /// The `SMSG_ADDON_INFO` verdict, taken once — `None` when the server never answered our addon
-    /// block, which is a real state and not a failure: vmangos only replies when
-    /// `BuildAddonPacket` accepts the block, and a rejection leaves the session alive and silent
-    /// (`WorldSocket.cpp:447`). The reference behaves the same way — no reply, no Lua index space.
+    /// The `SMSG_ADDON_INFO` statuses, taken once; `None` is real, as vmangos stays silent when it
+    /// rejects the addon block (`WorldSocket.cpp:447`).
     pub fn take_addon_info(&mut self) -> Option<Vec<u8>> {
         self.addon_info.take()
     }
@@ -310,8 +227,7 @@ impl WorldSession {
         )
     }
 
-    /// Request the character list and return it (remembering each character's race, so
-    /// [`Self::player_login`] can pick the right chat tongue).
+    /// Request and return the character list, remembering each race for the chat language.
     pub fn char_enum(&mut self) -> Result<Vec<Character>> {
         self.send(opcode::CMSG_CHAR_ENUM, &[])?;
         loop {
@@ -320,13 +236,11 @@ impl WorldSession {
                     self.roster_races = characters.iter().map(|c| (c.guid, c.race)).collect();
                     return Ok(characters);
                 }
-                // Warden can land either side of SMSG_AUTH_RESPONSE depending on when the server
-                // arms it, so the roster step refuses it too — same reason as `connect`.
+                // Warden can arm on either side of SMSG_AUTH_RESPONSE, so this step refuses it too.
                 ServerPacket::Other {
                     opcode: opcode::SMSG_WARDEN_DATA,
                 } => return Err(WardenRequired.into()),
-                // The tutorial bank, if the server sends it this early (1976): kept for the world
-                // entry — skipped here it would be lost to the roster loop.
+                // Kept for the world entry when the server sends it this early.
                 ServerPacket::TutorialFlags(flags) => {
                     self.tutorial_flags = Some(flags.bytes);
                     continue;
@@ -337,9 +251,7 @@ impl WorldSession {
         }
     }
 
-    /// Create a character (the create screen's request, or the create-if-empty starter that unblocks
-    /// `PLAYER_LOGIN` on a fresh account). Returns the `SMSG_CHAR_CREATE` result byte (`WorldResult`)
-    /// for the caller to inspect ([`messages::CHAR_CREATE_SUCCESS`], a `CHAR_NAME_*` code, …).
+    /// Create a character; returns the `SMSG_CHAR_CREATE` result byte.
     pub fn create_character(&mut self, req: &messages::CharCreateReq) -> Result<u8> {
         self.send(opcode::CMSG_CHAR_CREATE, &messages::char_create(req))?;
         loop {
@@ -350,9 +262,7 @@ impl WorldSession {
         }
     }
 
-    /// Delete a character (`CMSG_CHAR_DELETE`, full u64 guid — only valid at character select,
-    /// never while in-world). Returns the `SMSG_CHAR_DELETE` result byte
-    /// ([`messages::CHAR_DELETE_SUCCESS`] on success) for the caller to inspect.
+    /// Delete a character at character select; returns the `SMSG_CHAR_DELETE` result byte.
     pub fn delete_character(&mut self, guid: u64) -> Result<u8> {
         self.send(opcode::CMSG_CHAR_DELETE, &messages::full_guid(guid))?;
         loop {
@@ -363,11 +273,7 @@ impl WorldSession {
         }
     }
 
-    /// Send `CMSG_PLAYER_LOGIN` to enter the world as the given character. Also adopts the
-    /// character's faction tongue for every subsequent chat send (session and split writer alike):
-    /// vmangos drops chat — dot-commands included — spoken in a language the character doesn't
-    /// know, so the tongue must follow the pick. Falls back to Common when the guid wasn't in the
-    /// enumerated roster (no [`Self::char_enum`] this connection).
+    /// Enter the world as `guid`, adopting its faction tongue for chat (Common if not enumerated).
     pub fn player_login(&mut self, guid: u64) -> Result<()> {
         self.chat_language = self
             .roster_races
@@ -378,19 +284,17 @@ impl WorldSession {
         self.send(opcode::CMSG_PLAYER_LOGIN, &messages::full_guid(guid))
     }
 
-    /// Declare `guid` as the unit this client controls. vmangos drops all `MSG_MOVE_*` until the
-    /// client is a *confirmed mover*, which this establishes (the real client sends it at login).
+    /// Declare the unit we move, as the 1.12 client does at login; vmangos drops moves until then.
     pub fn set_active_mover(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_SET_ACTIVE_MOVER, &messages::full_guid(guid))
     }
 
-    /// Acknowledge a triggered cinematic as finished (`CMSG_COMPLETE_CINEMATIC`, empty body) — the
-    /// unsplit twin of [`WorldWriter::complete_cinematic`], for the CLI/probe path.
+    /// Acknowledge a triggered cinematic as finished (`CMSG_COMPLETE_CINEMATIC`, empty body).
     pub fn complete_cinematic(&mut self) -> Result<()> {
         self.send(opcode::CMSG_COMPLETE_CINEMATIC, &[])
     }
 
-    /// Walk our player forward `info`-style: begin moving (`MSG_MOVE_START_FORWARD`).
+    /// Start walking forward (`MSG_MOVE_START_FORWARD`).
     pub fn start_forward(&mut self, pos: [f32; 3], orientation: f32) -> Result<()> {
         self.send(
             opcode::MSG_MOVE_START_FORWARD,
@@ -414,11 +318,7 @@ impl WorldSession {
         )
     }
 
-    /// Answer a `SMSG_FORCE_*_SPEED_CHANGE` at rest — the unsplit twin of
-    /// [`WorldWriter::force_speed_change_ack`], for the `--speed` probe: echo the mover guid +
-    /// counter + exact speed with a stationary `MovementInfo`. A wrong shape (packed guid, missing
-    /// counter, off-by-0.01 speed) is rejected by the server's pending-change matcher — the probe's
-    /// pass is the server logging no mismatch and the next change arriving with counter+1.
+    /// Ack a `SMSG_FORCE_*_SPEED_CHANGE` at rest with the full guid, counter and exact speed.
     pub fn force_speed_ack(
         &mut self,
         kind: messages::SpeedKind,
@@ -434,11 +334,7 @@ impl WorldSession {
         )
     }
 
-    /// Acknowledge a finished server spline (`CMSG_MOVE_SPLINE_DONE`) — the unsplit twin of
-    /// [`WorldWriter::move_spline_done`], for the `--charge` probe: after the server drives us with a
-    /// self `SMSG_MONSTER_MOVE`, echo its `spline_id` at the endpoint (at rest) so the server clears
-    /// its spline-pending state and relocates us. A malformed body throws in the server's parser and
-    /// drops the session — so a surviving stream is the live proof the wire is right.
+    /// Ack a finished self `SMSG_MONSTER_MOVE` at its endpoint (`CMSG_MOVE_SPLINE_DONE`).
     pub fn move_spline_done(
         &mut self,
         pos: [f32; 3],
@@ -451,14 +347,12 @@ impl WorldSession {
         )
     }
 
-    /// Ask a player's name (`CMSG_NAME_QUERY`) — the unsplit twin of [`WorldWriter::name_query`],
-    /// for the CLI/probe path. The answer arrives in the stream as `SMSG_NAME_QUERY_RESPONSE`.
+    /// Ask a player's name (`CMSG_NAME_QUERY`), answered by `SMSG_NAME_QUERY_RESPONSE`.
     pub fn name_query(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_NAME_QUERY, &messages::full_guid(guid))
     }
 
-    /// Ask a creature template's name (`CMSG_CREATURE_QUERY`) — the unsplit twin of
-    /// [`WorldWriter::creature_query`].
+    /// Ask a creature template's name (`CMSG_CREATURE_QUERY`).
     pub fn creature_query(&mut self, entry: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_CREATURE_QUERY,
@@ -466,8 +360,7 @@ impl WorldSession {
         )
     }
 
-    /// Cast a spell (`CMSG_CAST_SPELL`) — the unsplit twin of [`WorldWriter::cast_spell`], for the
-    /// CLI/probe path. `target: None` = self/implicit; the verdict arrives as `SMSG_CAST_RESULT`.
+    /// Cast a spell (`CMSG_CAST_SPELL`), `None` targeting self; answered by `SMSG_CAST_RESULT`.
     pub fn cast_spell(&mut self, spell_id: u32, target: Option<u64>) -> Result<()> {
         self.send(
             opcode::CMSG_CAST_SPELL,
@@ -475,9 +368,7 @@ impl WorldSession {
         )
     }
 
-    /// Cast a spell at a **ground point** (`CMSG_CAST_SPELL` with `TARGET_FLAG_DEST_LOCATION` +
-    /// WoW world coords) — the unsplit twin of [`WorldWriter::cast_spell_at_dest`], for the
-    /// `--spells` probe's dest-cast round trip (decision 0792).
+    /// Cast a spell at a ground point in world coords (`TARGET_FLAG_DEST_LOCATION`).
     pub fn cast_spell_at_dest(&mut self, spell_id: u32, dest: [f32; 3]) -> Result<()> {
         self.send(
             opcode::CMSG_CAST_SPELL,
@@ -485,10 +376,7 @@ impl WorldSession {
         )
     }
 
-    /// Cast an OPEN_LOCK spell at a **GameObject** (`CMSG_CAST_SPELL`) — the unsplit twin of
-    /// [`WorldWriter::cast_spell_gameobject`], for a probe's live chest-loot verification (decision
-    /// 0239): cast e.g. 3365 "Opening" / 2575 "Mining" at a lockable GO and expect
-    /// `SMSG_LOOT_RESPONSE`.
+    /// Cast an OPEN_LOCK spell (e.g. 3365 Opening, 2575 Mining) at a GameObject.
     pub fn cast_spell_gameobject(&mut self, spell_id: u32, go_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_CAST_SPELL,
@@ -496,8 +384,7 @@ impl WorldSession {
         )
     }
 
-    /// Ask an item template (`CMSG_ITEM_QUERY_SINGLE`) — the unsplit twin of
-    /// [`WorldWriter::item_query`]. Answered by `SMSG_ITEM_QUERY_SINGLE_RESPONSE`.
+    /// Ask an item template (`CMSG_ITEM_QUERY_SINGLE`).
     pub fn item_query(&mut self, entry: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_ITEM_QUERY_SINGLE,
@@ -505,8 +392,7 @@ impl WorldSession {
         )
     }
 
-    /// Use an item by bag position (`CMSG_USE_ITEM`) — the unsplit twin of
-    /// [`WorldWriter::use_item`], for the probe's live use-item verification.
+    /// Use an item by bag position (`CMSG_USE_ITEM`).
     pub fn use_item(&mut self, bag_index: u8, slot: u8, spell_slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_USE_ITEM,
@@ -519,8 +405,7 @@ impl WorldSession {
         )
     }
 
-    /// Open an item by bag position (`CMSG_OPEN_ITEM`) — the unsplit twin of
-    /// [`WorldWriter::open_item`], for the probe's live open-item verification.
+    /// Open an item by bag position (`CMSG_OPEN_ITEM`).
     pub fn open_item(&mut self, bag_index: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_OPEN_ITEM,
@@ -528,8 +413,7 @@ impl WorldSession {
         )
     }
 
-    /// Equip a bag item (`CMSG_AUTOEQUIP_ITEM`) — the unsplit twin of
-    /// [`WorldWriter::auto_equip_item`], for the probe's live equip verification.
+    /// Equip a bag item (`CMSG_AUTOEQUIP_ITEM`).
     pub fn auto_equip_item(&mut self, bag_index: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOEQUIP_ITEM,
@@ -537,8 +421,7 @@ impl WorldSession {
         )
     }
 
-    /// Swap two player-array slots (`CMSG_SWAP_INV_ITEM`) — the unsplit twin of
-    /// [`WorldWriter::swap_inv_item`], for the probe's live backpack-move verification.
+    /// Swap two player-array slots (`CMSG_SWAP_INV_ITEM`).
     pub fn swap_inv_item(&mut self, src_slot: u8, dst_slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_SWAP_INV_ITEM,
@@ -546,9 +429,7 @@ impl WorldSession {
         )
     }
 
-    /// Ask a vendor's stock (`CMSG_LIST_INVENTORY`) — the unsplit twin of
-    /// [`WorldWriter::list_inventory`], for the probe's live vendor verification. Answered by
-    /// `SMSG_LIST_INVENTORY` (a `VendorInventory` event).
+    /// Ask a vendor's stock (`CMSG_LIST_INVENTORY`), answered by `SMSG_LIST_INVENTORY`.
     pub fn list_inventory(&mut self, vendor_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_LIST_INVENTORY,
@@ -556,8 +437,7 @@ impl WorldSession {
         )
     }
 
-    /// Buy from a vendor (`CMSG_BUY_ITEM`) — the unsplit twin of [`WorldWriter::buy_item`]; `entry`
-    /// is the item template id, not the vendor row's `muid`.
+    /// Buy from a vendor (`CMSG_BUY_ITEM`); `entry` is the item template, not the row's `muid`.
     pub fn buy_item(&mut self, vendor_guid: u64, entry: u32, count: u8) -> Result<()> {
         self.send(
             opcode::CMSG_BUY_ITEM,
@@ -565,7 +445,7 @@ impl WorldSession {
         )
     }
 
-    /// `CMSG_BUY_ITEM_IN_SLOT` — buy into a named container slot, the merchant cursor's drop.
+    /// Buy into a named container slot (`CMSG_BUY_ITEM_IN_SLOT`), the merchant cursor's drop.
     pub fn buy_item_in_slot(
         &mut self,
         vendor_guid: u64,
@@ -580,8 +460,7 @@ impl WorldSession {
         )
     }
 
-    /// Sell an item to a vendor (`CMSG_SELL_ITEM`) — the unsplit twin of [`WorldWriter::sell_item`];
-    /// `count` 0 = the whole stack.
+    /// Sell an item to a vendor (`CMSG_SELL_ITEM`); `count` 0 sells the whole stack.
     pub fn sell_item(&mut self, vendor_guid: u64, item_guid: u64, count: u8) -> Result<()> {
         self.send(
             opcode::CMSG_SELL_ITEM,
@@ -589,8 +468,7 @@ impl WorldSession {
         )
     }
 
-    /// Buy a sold item back (`CMSG_BUYBACK_ITEM`) — the unsplit twin of
-    /// [`WorldWriter::buyback_item`]; `slot` is the absolute buyback slot 69–80.
+    /// Buy a sold item back (`CMSG_BUYBACK_ITEM`); `slot` is the absolute buyback slot 69-80.
     pub fn buyback_item(&mut self, vendor_guid: u64, slot: u32) -> Result<()> {
         self.send(
             opcode::CMSG_BUYBACK_ITEM,
@@ -598,8 +476,7 @@ impl WorldSession {
         )
     }
 
-    /// Repair at a vendor (`CMSG_REPAIR_ITEM`) — the unsplit twin of [`WorldWriter::repair_item`];
-    /// `item_guid` 0 = repair everything.
+    /// Repair at a vendor (`CMSG_REPAIR_ITEM`); `item_guid` 0 repairs everything.
     pub fn repair_item(&mut self, vendor_guid: u64, item_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_REPAIR_ITEM,
@@ -607,8 +484,7 @@ impl WorldSession {
         )
     }
 
-    /// Right-click a pure banker (`CMSG_BANKER_ACTIVATE`) — opens the bank window, answered by
-    /// `SMSG_SHOW_BANK` (a `ShowBank` event). Decision 0604.
+    /// Open the bank at a banker (`CMSG_BANKER_ACTIVATE`), answered by `SMSG_SHOW_BANK`.
     pub fn banker_activate(&mut self, banker_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_BANKER_ACTIVATE,
@@ -616,10 +492,7 @@ impl WorldSession {
         )
     }
 
-    /// Buy the next bank bag slot (`CMSG_BUY_BANK_SLOT`) — the server buys slot
-    /// `purchased_count + 1` and debits the price itself; success is silent (the
-    /// `PLAYER_BYTES_2` bank-bag-count byte advances via `UPDATE_OBJECT`), failure answers
-    /// `SMSG_BUY_BANK_SLOT_RESULT` (a `BuyBankSlotResult` event). Decision 0604.
+    /// Buy the next bank bag slot; success is silent, failure answers `SMSG_BUY_BANK_SLOT_RESULT`.
     pub fn buy_bank_slot(&mut self, banker_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_BUY_BANK_SLOT,
@@ -627,8 +500,7 @@ impl WorldSession {
         )
     }
 
-    /// Deposit a bag item into the bank (`CMSG_AUTOBANK_ITEM`) — moves the item at player-array
-    /// position `(bag, slot)` into the first free bank slot. Decision 0604.
+    /// Deposit the item at `(bag, slot)` into the first free bank slot (`CMSG_AUTOBANK_ITEM`).
     pub fn autobank_item(&mut self, bag: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOBANK_ITEM,
@@ -636,9 +508,7 @@ impl WorldSession {
         )
     }
 
-    /// Auto-move at the bank (`CMSG_AUTOSTORE_BANK_ITEM`) — withdraws `(bag, slot)` to inventory
-    /// when it names a bank position, else deposits it (vmangos `HandleAutoStoreBankItemOpcode`,
-    /// `ItemHandler.cpp:971`). Decision 0604.
+    /// Withdraw a bank position, or deposit any other (`CMSG_AUTOSTORE_BANK_ITEM`).
     pub fn autostore_bank_item(&mut self, bag: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOSTORE_BANK_ITEM,
@@ -646,8 +516,7 @@ impl WorldSession {
         )
     }
 
-    /// Ask an NPC's questgiver dialog status (`CMSG_QUESTGIVER_STATUS_QUERY`) — answered by
-    /// `SMSG_QUESTGIVER_STATUS`, the overhead `!`/`?` marker's value.
+    /// Ask an NPC's overhead `!`/`?` status (`CMSG_QUESTGIVER_STATUS_QUERY`).
     pub fn questgiver_status_query(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_STATUS_QUERY,
@@ -655,8 +524,7 @@ impl WorldSession {
         )
     }
 
-    /// Open a questgiver dialog (`CMSG_QUESTGIVER_HELLO`) — the unsplit twin for the probe's live
-    /// quest verification. The same `SendPreparedGossip` server path as gossip-hello.
+    /// Open a questgiver dialog (`CMSG_QUESTGIVER_HELLO`), the server's gossip-hello path.
     pub fn questgiver_hello(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_HELLO,
@@ -664,8 +532,7 @@ impl WorldSession {
         )
     }
 
-    /// Ask a quest's detail panel (`CMSG_QUESTGIVER_QUERY_QUEST`) — answered by
-    /// `SMSG_QUESTGIVER_QUEST_DETAILS`.
+    /// Ask a quest's detail panel (`CMSG_QUESTGIVER_QUERY_QUEST`).
     pub fn questgiver_query_quest(&mut self, npc: u64, quest: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_QUERY_QUEST,
@@ -673,8 +540,7 @@ impl WorldSession {
         )
     }
 
-    /// Accept a quest (`CMSG_QUESTGIVER_ACCEPT_QUEST`) — adds it to the log; the server closes the
-    /// gossip window.
+    /// Accept a quest (`CMSG_QUESTGIVER_ACCEPT_QUEST`); the server closes the gossip window.
     pub fn questgiver_accept_quest(&mut self, npc: u64, quest: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_ACCEPT_QUEST,
@@ -682,8 +548,7 @@ impl WorldSession {
         )
     }
 
-    /// Ask for a quest's turn-in progress panel (`CMSG_QUESTGIVER_COMPLETE_QUEST`) — answered by
-    /// `SMSG_QUESTGIVER_REQUEST_ITEMS` (or OFFER_REWARD when there are no required items).
+    /// Ask a quest's turn-in panel: `REQUEST_ITEMS`, or `OFFER_REWARD` when nothing is required.
     pub fn questgiver_complete_quest(&mut self, npc: u64, quest: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_COMPLETE_QUEST,
@@ -691,8 +556,7 @@ impl WorldSession {
         )
     }
 
-    /// Advance from progress to the reward panel (`CMSG_QUESTGIVER_REQUEST_REWARD`) — answered by
-    /// `SMSG_QUESTGIVER_OFFER_REWARD`.
+    /// Advance to the reward panel (`CMSG_QUESTGIVER_REQUEST_REWARD`).
     pub fn questgiver_request_reward(&mut self, npc: u64, quest: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_REQUEST_REWARD,
@@ -700,8 +564,7 @@ impl WorldSession {
         )
     }
 
-    /// Choose a reward and finish the quest (`CMSG_QUESTGIVER_CHOOSE_REWARD`, `reward` = choice
-    /// index) — answered by `SMSG_QUESTGIVER_QUEST_COMPLETE` + the XP/money/item grants.
+    /// Choose reward index `reward` and finish the quest (`CMSG_QUESTGIVER_CHOOSE_REWARD`).
     pub fn questgiver_choose_reward(&mut self, npc: u64, quest: u32, reward: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_CHOOSE_REWARD,
@@ -709,25 +572,17 @@ impl WorldSession {
         )
     }
 
-    /// Ask a quest's full template (`CMSG_QUEST_QUERY`) — the unsplit twin of
-    /// [`WorldWriter::quest_query`]; the quest-log detail pane's ask-once source, distinct from
-    /// [`Self::questgiver_query_quest`] (which needs an NPC guid, not just the quest id). Answered
-    /// by `SMSG_QUEST_QUERY_RESPONSE` (a `QuestTemplate` event).
+    /// Ask a quest's full template by id alone (`CMSG_QUEST_QUERY`).
     pub fn quest_query(&mut self, quest_id: u32) -> Result<()> {
         self.send(opcode::CMSG_QUEST_QUERY, &messages::quest_query(quest_id))
     }
 
-    /// Ask the server for its wall clock (`CMSG_QUERY_TIME`) — the unsplit twin of
-    /// [`WorldWriter::query_time`]; answered by `SMSG_QUERY_TIME_RESPONSE`, one `u32` of
-    /// unix-epoch seconds. That is the epoch a timed quest's deadline is written in, so no
-    /// countdown can be read off the descriptor without it (decision 1150).
+    /// Ask the server's unix-seconds clock, the epoch of timed-quest deadlines (`CMSG_QUERY_TIME`).
     pub fn query_time(&mut self) -> Result<()> {
         self.send(opcode::CMSG_QUERY_TIME, &messages::query_time())
     }
 
-    /// Abandon a quest-log slot (`CMSG_QUESTLOG_REMOVE_QUEST`) — the unsplit twin of
-    /// [`WorldWriter::questlog_remove_quest`]; no ack SMSG, the server clears the
-    /// `PLAYER_QUEST_LOG` slot fields directly.
+    /// Abandon a quest-log slot; no reply, the server clears the `PLAYER_QUEST_LOG` fields.
     pub fn questlog_remove_quest(&mut self, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTLOG_REMOVE_QUEST,
@@ -735,10 +590,7 @@ impl WorldSession {
         )
     }
 
-    /// Send a `/say` line — the unsplit twin of [`WorldWriter::send_chat`]; the probe CLI drives GM
-    /// dot-commands (`.go xyz …`) through it. Same body rules as the writer: spoken in the
-    /// character's own tongue (set by [`Self::player_login`]) — the server rejects `Universal`
-    /// from clients, and rejects a tongue the character doesn't know.
+    /// Send a `/say` line, GM dot-commands included, in the character's own tongue.
     pub fn send_chat(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -746,10 +598,7 @@ impl WorldSession {
         )
     }
 
-    /// Send a chat line on an arbitrary lane — the generalised twin of [`Self::send_chat`]
-    /// (which is this with `CHAT_TYPE_SAY`). `target` is the whisper target on
-    /// `CHAT_TYPE_WHISPER` and the channel name on `CHAT_TYPE_CHANNEL`, `None` elsewhere. Spoken
-    /// in the character's own tongue, with the same server-side rules.
+    /// Send a chat line on any lane; `target` is the whisper target or channel name.
     pub fn send_chat_kind(
         &mut self,
         chat_type: u32,
@@ -762,8 +611,7 @@ impl WorldSession {
         )
     }
 
-    /// Join a channel — the unsplit twin of [`WorldWriter::join_channel`]; `password` is empty for
-    /// a channel that has none.
+    /// Join a channel; `password` is empty for a channel that has none.
     pub fn join_channel(&mut self, name: &str, password: &str) -> Result<()> {
         self.send(
             opcode::CMSG_JOIN_CHANNEL,
@@ -771,13 +619,12 @@ impl WorldSession {
         )
     }
 
-    /// Leave a channel — the unsplit twin of [`WorldWriter::leave_channel`].
+    /// Leave a channel.
     pub fn leave_channel(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_LEAVE_CHANNEL, &messages::leave_channel(name))
     }
 
-    /// Invite a player to our group by name (`CMSG_GROUP_INVITE`); they answer with
-    /// `SMSG_GROUP_INVITE` and, if they want in, [`Self::group_accept`].
+    /// Invite a player to our group by name (`CMSG_GROUP_INVITE`).
     pub fn group_invite(&mut self, member_name: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_INVITE,
@@ -790,23 +637,14 @@ impl WorldSession {
         self.send(opcode::CMSG_GROUP_ACCEPT, &messages::group_accept())
     }
 
-    /// Leave/disband our group (`CMSG_GROUP_DISBAND`, empty body) — probes tear the group down so
-    /// the next run starts ungrouped.
+    /// Leave or disband our group (`CMSG_GROUP_DISBAND`, empty body).
     pub fn group_disband(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GROUP_DISBAND, &messages::group_disband())
     }
 
-    /// Send an **addon message** — a `CMSG_MESSAGECHAT` on `chat_type`'s lane with
-    /// [`messages::LANGUAGE_ADDON`] in the language field, which is what makes it addon traffic
-    /// rather than speech (decision 1029). `target` is the channel name on
-    /// [`messages::CHAT_TYPE_CHANNEL`] and `None` on the group/guild lanes; `text` is the raw
-    /// payload (`prefix`, TAB, the addon's own encoding) — this verb does not compose it.
-    ///
-    /// Probe-only, and deliberately: benilla runs FrameXML, not third-party addons, so it has
-    /// nothing to *say* over this lane. It exists so the receive gate can be proved against the
-    /// live server (`addon_chat_probe`) rather than argued from folk memory of the lane. The
-    /// server drops the whole message unless `AddonChannel` is on and `chat_type` is one of the
-    /// lanes `IsLanguageAllowedForChatType` permits (see [`messages::LANGUAGE_ADDON`]).
+    /// Send an addon message: [`messages::LANGUAGE_ADDON`] as the language, `target` the channel
+    /// name on [`messages::CHAT_TYPE_CHANNEL`]. vmangos drops it unless `AddonChannel` is on and
+    /// the lane allows it. Probe-only: benilla runs no third-party addons.
     pub fn send_addon_message(
         &mut self,
         chat_type: u32,
@@ -819,8 +657,7 @@ impl WorldSession {
         )
     }
 
-    /// Echo a same-map teleport ack — the unsplit twin of [`WorldWriter::teleport_ack`] (without it
-    /// the server freezes our movement after a `.go`).
+    /// Echo a same-map teleport ack; without it the server freezes our movement.
     pub fn teleport_ack(&mut self, guid: u64, counter: u32) -> Result<()> {
         self.send(
             opcode::MSG_MOVE_TELEPORT_ACK,
@@ -828,19 +665,12 @@ impl WorldSession {
         )
     }
 
-    /// Echo a cross-map worldport ack — the unsplit twin of [`WorldWriter::worldport_ack`]
-    /// (`MSG_MOVE_WORLDPORT_ACK`, empty body). Without it the server never runs
-    /// `HandleMoveWorldportAckOpcode`, so nothing on the destination map is ever streamed: no self
-    /// create block, and none of the arrival's own side effects (the `--mount-tele` probe's whole
-    /// subject — the mount strip a map that forbids mounting performs right there).
+    /// Ack a cross-map worldport (empty body); without it nothing on the new map is streamed.
     pub fn worldport_ack(&mut self) -> Result<()> {
         self.send(opcode::MSG_MOVE_WORLDPORT_ACK, &[])
     }
 
-    /// **Acknowledge a granted mover mode** — root, water-walk, feather-fall or hover (the ack'd
-    /// family; decision 0866) — the unsplit twin of [`WorldWriter::move_mode_ack`], for the
-    /// `--death` probe: the server roots us at death, unroots and grants walk-on-water at release,
-    /// and applies nothing until we echo the counter (+ our current `pose`) back.
+    /// Ack a granted mover mode with the counter and current `pose`; nothing applies until then.
     pub fn move_mode_ack(
         &mut self,
         guid: u64,
@@ -858,30 +688,22 @@ impl WorldSession {
         )
     }
 
-    /// Release the spirit (`CMSG_REPOP_REQUEST`, empty body) — the unsplit twin of
-    /// [`WorldWriter::repop_request`], for the `--death` probe's live release verification.
+    /// Release the spirit (`CMSG_REPOP_REQUEST`, empty body).
     pub fn repop_request(&mut self) -> Result<()> {
         self.send(opcode::CMSG_REPOP_REQUEST, &[])
     }
 
-    /// Ask where our corpse is (`MSG_CORPSE_QUERY`, empty request) — the unsplit twin of
-    /// [`WorldWriter::corpse_query`], for the `--death` probe. Answered by the same opcode (a
-    /// [`SessionEvent::CorpseQuery`](crate::SessionEvent::CorpseQuery)).
+    /// Ask where our corpse is (`MSG_CORPSE_QUERY`, empty body), answered on the same opcode.
     pub fn corpse_query(&mut self) -> Result<()> {
         self.send(opcode::MSG_CORPSE_QUERY, &[])
     }
 
-    /// Self-resurrect (`CMSG_SELF_RES`, empty body) — the unsplit twin of
-    /// [`WorldWriter::self_res`], for the `--self-res` probe. The server casts whatever
-    /// `PLAYER_SELF_RES_SPELL` holds and zeroes the field.
+    /// Self-resurrect; the server casts `PLAYER_SELF_RES_SPELL` and zeroes it.
     pub fn self_res(&mut self) -> Result<()> {
         self.send(opcode::CMSG_SELF_RES, &[])
     }
 
-    /// Ask the graveyard's Spirit Healer for the immediate res (`CMSG_SPIRIT_HEALER_ACTIVATE`,
-    /// full guid) — the unsplit twin of [`WorldWriter::spirit_healer_activate`], for the
-    /// `--spirit` probe's live durability-loss verification. The server resurrects at 50% health
-    /// and pushes the 25% durability loss as item values-deltas.
+    /// Take the Spirit Healer's resurrection: 50% health and a 25% durability loss.
     pub fn spirit_healer_activate(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::CMSG_SPIRIT_HEALER_ACTIVATE,
@@ -889,36 +711,27 @@ impl WorldSession {
         )
     }
 
-    /// Start melee auto-attack (`CMSG_ATTACKSWING`, full guid) — the unsplit twin of
-    /// [`WorldWriter::attack_swing`]. Echoed as `SMSG_ATTACKSTART`; each completed swing arrives as
-    /// `SMSG_ATTACKERSTATEUPDATE`.
+    /// Start melee auto-attack (`CMSG_ATTACKSWING`), echoed as `SMSG_ATTACKSTART`.
     pub fn attack_swing(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_ATTACKSWING, &messages::attack_swing(guid))
     }
 
-    /// Set our target (`CMSG_SET_SELECTION`, full guid) — the unsplit twin of
-    /// [`WorldWriter::set_selection`], for probe fidelity (the client selects before it casts).
+    /// Set our target (`CMSG_SET_SELECTION`, full guid); the client selects before it casts.
     pub fn set_selection(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_SET_SELECTION, &messages::full_guid(guid))
     }
 
-    /// Open a loot window (`CMSG_LOOT`) — the unsplit twin of [`WorldWriter::loot`], for the
-    /// probe's live loot verification. Answered by `SMSG_LOOT_RESPONSE` (either shape).
+    /// Open a loot window (`CMSG_LOOT`), answered by `SMSG_LOOT_RESPONSE`.
     pub fn loot(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_LOOT, &messages::loot(guid))
     }
 
-    /// Use a world GameObject (`CMSG_GAMEOBJ_USE`) — the unsplit twin of [`WorldWriter::gameobj_use`],
-    /// for a probe's live GO-interaction verification (decision 0236 phase 3's chest-loot capture).
-    /// The server answers on the type's own system (`SMSG_LOOT_RESPONSE` for a chest, gossip/quest for
-    /// a questgiver GO) or not at all.
+    /// Use a world GameObject; the server answers by type, or not at all.
     pub fn gameobj_use(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_GAMEOBJ_USE, &messages::gameobj_use(guid))
     }
 
-    /// Ask for a GameObject template's head (`CMSG_GAMEOBJECT_QUERY`) — the unsplit twin of
-    /// [`WorldWriter::gameobject_query`], for the CLI/probe path. Answered by
-    /// `SMSG_GAMEOBJECT_QUERY_RESPONSE`.
+    /// Ask a GameObject template (`CMSG_GAMEOBJECT_QUERY`).
     pub fn gameobject_query(&mut self, entry: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_GAMEOBJECT_QUERY,
@@ -926,9 +739,7 @@ impl WorldSession {
         )
     }
 
-    /// Take one loot-window row (`CMSG_AUTOSTORE_LOOT_ITEM`) — the unsplit twin of
-    /// [`WorldWriter::autostore_loot_item`]; `loot_slot` is the wire's 0-based row index from the
-    /// `SMSG_LOOT_RESPONSE` this answers.
+    /// Take one loot row; `loot_slot` is the 0-based row of the `SMSG_LOOT_RESPONSE`.
     pub fn autostore_loot_item(&mut self, loot_slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOSTORE_LOOT_ITEM,
@@ -936,24 +747,19 @@ impl WorldSession {
         )
     }
 
-    /// Take the loot's coin pile (`CMSG_LOOT_MONEY`, empty body) — the unsplit twin of
-    /// [`WorldWriter::loot_money`]. Answered by `SMSG_LOOT_MONEY_NOTIFY` + `SMSG_LOOT_CLEAR_MONEY`.
+    /// Take the loot's coin (`CMSG_LOOT_MONEY`, empty body).
     pub fn loot_money(&mut self) -> Result<()> {
         self.send(opcode::CMSG_LOOT_MONEY, &messages::loot_money())
     }
 
-    /// Close the loot window (`CMSG_LOOT_RELEASE`) — the unsplit twin of
-    /// [`WorldWriter::loot_release`]; the server ignores `guid` and releases its own stored loot
-    /// target. Answered by `SMSG_LOOT_RELEASE_RESPONSE`.
+    /// Close the loot window; the server ignores `guid` and releases its own loot target.
     pub fn loot_release(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_LOOT_RELEASE, &messages::loot_release(guid))
     }
 
-    /// Split into independent read/write halves (separate cloned sockets + crypto halves) so a reader
-    /// thread can stream updates while another path sends our movement. Call after [`Self::player_login`].
+    /// Split into a reader and a writer on cloned sockets, after [`Self::player_login`].
     pub fn into_split(self) -> Result<(WorldReader, WorldWriter)> {
-        // The handshake is over — clear its read timeout (decision 0065): the streaming phase reads
-        // block indefinitely (a quiet world is legal; connection liveness is the caller's loop).
+        // A quiet world is legal, so streaming reads block without a timeout.
         self.stream
             .set_read_timeout(None)
             .context("clearing handshake read timeout")?;
@@ -976,10 +782,7 @@ impl WorldSession {
         ))
     }
 
-    /// Cleanly leave the world back to character-select: send `CMSG_LOGOUT_REQUEST` and wait for
-    /// `SMSG_LOGOUT_COMPLETE` (instant for GM / rested). The server persists the character on logout,
-    /// so a follow-up [`Self::char_enum`] reflects the saved position. Requires a read timeout (so the
-    /// poll loop can give up); returns once logged out or `timeout` elapses.
+    /// Log out to character select, waiting up to `timeout`; needs a socket read timeout.
     pub fn logout(&mut self, timeout: std::time::Duration) -> Result<()> {
         self.send(opcode::CMSG_LOGOUT_REQUEST, &[])?;
         let deadline = std::time::Instant::now() + timeout;
@@ -992,7 +795,7 @@ impl WorldSession {
                     denied = reason != messages::LOGOUT_SUCCESS;
                 }
                 Ok(_) => {}
-                Err(_) => {} // read-timeout tick — keep polling until the deadline
+                Err(_) => {} // a read-timeout tick; poll until the deadline
             }
         }
         if denied {
diff --git a/crates/benilla-protocol/src/world/writer/action_bar.rs b/crates/benilla-protocol/src/world/writer/action_bar.rs
index d9dfb6f2..0ce26acc 100644
--- a/crates/benilla-protocol/src/world/writer/action_bar.rs
+++ b/crates/benilla-protocol/src/world/writer/action_bar.rs
@@ -1,13 +1,5 @@
-//! The action bar's `WorldWriter` send — one verb, mirroring [`crate::messages::action_bar`]. Split
-//! out of [`super::spells`] by decision 0640.
-//!
-//! One verb is the whole family because the bar is **client-authoritative** (decisions 0216 §7 /
-//! 0218 §4): the server stores the slots and hands them back at login and never edits them in
-//! normal play. So every pickup, place and hop the player makes is exactly one of these — a
-//! drag-swap is two sends, never atomic.
-//!
-//! The second verb is the mirror image of the first: [`WorldWriter::set_actionbar_toggles`] posts a
-//! byte the client is **not** allowed to write locally.
+//! The action bar sends. Its contents are client-authoritative: the server stores the slots,
+//! hands them back at login and never edits them in play.
 
 use anyhow::Result;
 
@@ -16,12 +8,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Set (or clear, `packed == 0`) one action-bar slot (`CMSG_SET_ACTION_BUTTON`, layout in
-    /// [`messages::set_action_button`]) — decision 0216 §7/0218 §4: the bar is
-    /// client-authoritative, so this is the ONLY wire traffic a local pickup/place/hop generates,
-    /// one send per slot mutation (a drag-swap is two sends, never atomic). No dedicated answer
-    /// packet — `SMSG_ACTION_BUTTONS` only ever re-arrives on a server-side edit (a GM command, a
-    /// macro-menu save), never as our own edit's echo.
+    /// Set one action-bar slot, or clear it with `packed == 0` (`CMSG_SET_ACTION_BUTTON`). A
+    /// drag-swap is two sends, never atomic; the server never echoes our own edit.
     pub fn set_action_button(&mut self, button: u8, packed: u32) -> Result<()> {
         self.send(
             opcode::CMSG_SET_ACTION_BUTTON,
@@ -29,21 +17,9 @@ impl WorldWriter {
         )
     }
 
-    /// Post the four extra bars' visibility byte (`CMSG_SET_ACTIONBAR_TOGGLES`, layout in
-    /// [`messages::set_actionbar_toggles`]) — `PLAYER_FIELD_BYTES` byte 2, VERIFIED wow-re
-    /// `system/ui/scratch/action-bar-toggles.md`.
-    ///
-    /// **The opposite arrangement to [`Self::set_action_button`]**, and the difference is the whole
-    /// point. The bar's *contents* are client-authoritative; the bar's *visibility* is
-    /// server-owned: the real client never stores this byte itself (§4.1 — the one `+0x102a`
-    /// instruction image-wide is a read), so the value only becomes true when the server's
-    /// `SMSG_UPDATE_OBJECT` echoes it back into the descriptor. There is no answer packet and no
-    /// field-change notification (§4.2), which is why the reference UI keeps its own optimistic
-    /// copy in Lua and re-reads the field exactly once, at `PLAYER_ENTERING_WORLD`.
-    ///
-    /// Sending while disconnected is a **silent no-op**, not an error, matching the reference: the
-    /// binding gates nothing and drops the packet at `0x5ab637` (no connection) or `0x5379ab`
-    /// (connection state ≠ 6), returning zero Lua values either way, so nothing upstream can tell.
+    /// Post the extra bars' visibility byte, `PLAYER_FIELD_BYTES` byte 2. The server owns it: the
+    /// reference never writes it locally, it holds once `SMSG_UPDATE_OBJECT` echoes it, and a
+    /// disconnected send is dropped silently (`0x5ab637`).
     pub fn set_actionbar_toggles(&mut self, toggles: u8) -> Result<()> {
         self.send(
             opcode::CMSG_SET_ACTIONBAR_TOGGLES,
diff --git a/crates/benilla-protocol/src/world/writer/area_trigger.rs b/crates/benilla-protocol/src/world/writer/area_trigger.rs
index a0bd3212..1edb0128 100644
--- a/crates/benilla-protocol/src/world/writer/area_trigger.rs
+++ b/crates/benilla-protocol/src/world/writer/area_trigger.rs
@@ -1,4 +1,4 @@
-//! The one area-trigger send. Body in [`crate::messages::area_trigger`], whose scope this mirrors.
+//! The area-trigger send.
 
 use anyhow::Result;
 
@@ -7,14 +7,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Report that we just walked into an `AreaTrigger.dbc` volume (`CMSG_AREATRIGGER`, layout in
-    /// [`messages::area_trigger`]) — the client's whole part in the trigger system: it owns the
-    /// geometry and names the id, and the **server** decides what that trigger means (a teleport,
-    /// a quest's explore objective, the inn's rested state, a battleground's entrance list).
-    ///
-    /// There is no dedicated success reply: a teleport arrives as the ordinary
-    /// `SMSG_TRANSFER_PENDING` + `SMSG_NEW_WORLD` pair or a same-map `MSG_MOVE_TELEPORT_ACK`, a
-    /// refusal as `SMSG_AREA_TRIGGER_MESSAGE`, and most triggers answer with nothing at all.
+    /// Report walking into an `AreaTrigger.dbc` volume (`CMSG_AREATRIGGER`). There is no success
+    /// reply; a refusal is `SMSG_AREA_TRIGGER_MESSAGE`, and most triggers answer nothing.
     pub fn area_trigger(&mut self, trigger_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_AREATRIGGER,
diff --git a/crates/benilla-protocol/src/world/writer/attack.rs b/crates/benilla-protocol/src/world/writer/attack.rs
index bb75aa67..64d1cc03 100644
--- a/crates/benilla-protocol/src/world/writer/attack.rs
+++ b/crates/benilla-protocol/src/world/writer/attack.rs
@@ -1,11 +1,5 @@
-//! The auto-attack family's `WorldWriter` sends — start and stop the melee swing, and stop the
-//! ranged auto-repeat. Bodies in [`crate::messages::attack`], whose scope this mirrors (the two
-//! stops are bodyless). Split out of [`super::spells`] by decision 0640, when the messages side
-//! grew an `attack` family of its own.
-//!
-//! Melee and ranged sit together because they are two halves of one toggle: the client runs at most
-//! one auto-attack, and switching weapons hands off between `CMSG_ATTACKSTOP` and
-//! `CMSG_CANCEL_AUTO_REPEAT_SPELL`.
+//! The auto-attack sends. The client runs at most one auto-attack, so switching between melee and
+//! ranged hands off between `CMSG_ATTACKSTOP` and `CMSG_CANCEL_AUTO_REPEAT_SPELL`.
 
 use anyhow::Result;
 
@@ -14,8 +8,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Start melee auto-attack on `guid` (`CMSG_ATTACKSWING`, a full 8-byte guid — vmangos
-    /// `AttackSwing::ReadFromWorldPacket`). Echoed back as `SMSG_ATTACKSTART`.
+    /// Start melee auto-attack (`CMSG_ATTACKSWING`, full guid), echoed as `SMSG_ATTACKSTART`.
     pub fn attack_swing(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_ATTACKSWING, &messages::attack_swing(guid))
     }
@@ -25,8 +18,7 @@ impl WorldWriter {
         self.send(opcode::CMSG_ATTACKSTOP, &[])
     }
 
-    /// Stop our ranged auto-repeat (`CMSG_CANCEL_AUTO_REPEAT_SPELL`, empty body) — the ack every
-    /// local cancel sends (the client's one send site `0x6ea0c6`, inside the cancel `0x6ea080`).
+    /// Stop our ranged auto-repeat; the reference sends it on every local cancel (`0x6ea080`).
     pub fn cancel_auto_repeat(&mut self) -> Result<()> {
         self.send(opcode::CMSG_CANCEL_AUTO_REPEAT_SPELL, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/auction.rs b/crates/benilla-protocol/src/world/writer/auction.rs
index ddbaf276..64e6c6ed 100644
--- a/crates/benilla-protocol/src/world/writer/auction.rs
+++ b/crates/benilla-protocol/src/world/writer/auction.rs
@@ -1,17 +1,7 @@
-//! The auction house's `WorldWriter` sends (decision 1511 P0): the auctioneer greeting, the three
-//! list pages (browse / your bids / your auctions), and the three market verbs — list an item,
-//! bid or buy out, cancel. Bodies in [`crate::messages`]'s `auction` builders (layout VERIFIED
-//! against vmangos `Handlers/AuctionHouseHandler.cpp` + `Server/Packets/AuctionHouse.cpp`). Split
-//! out per `writer/mod.rs`'s rule — the module a body builder lives in names the module its send
-//! lives in.
-//!
-//! Two things every caller here has to know. **The auctioneer guid rides on every send**, not
-//! just the hello: the server re-validates the 5 yd interact distance on each one independently
-//! (`GetCheckedAuctionHouseForAuctioneer`), so there is no session to hold and a walk-away
-//! invalidates the next verb rather than the window. And **several refusals are silent** — a sell
-//! with a zero bid or duration, a bid the player cannot afford, a cancel whose 5% cut they cannot
-//! pay, and any list request while one is already in flight all get *no packet at all*. A UI that
-//! blocks waiting for an ack hangs.
+//! The auction house sends. Each carries the auctioneer guid, and the server re-checks the 5 yd
+//! range on each (`GetCheckedAuctionHouseForAuctioneer`). Sell, bid and cancel answer
+//! `SMSG_AUCTION_COMMAND_RESULT`, but some refusals are silent: a zero bid or duration, an
+//! unaffordable bid or cancel cut, and a list request while one is in flight.
 
 use anyhow::Result;
 
@@ -20,10 +10,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Greet an auctioneer (`MSG_AUCTION_HELLO`, layout in [`messages::auction_hello`]) — one
-    /// auctioneer guid. **Two-way opcode**: the reply carries the guid back plus the
-    /// `AuctionHouse.dbc` house id (an `AuctionHello` event), and it is that reply which opens the
-    /// window.
+    /// Greet an auctioneer; the reply, carrying the `AuctionHouse.dbc` id, opens the window.
     pub fn auction_hello(&mut self, auctioneer: u64) -> Result<()> {
         self.send(
             opcode::MSG_AUCTION_HELLO,
@@ -31,11 +18,8 @@ impl WorldWriter {
         )
     }
 
-    /// Ask a Browse page (`CMSG_AUCTION_LIST_ITEMS`, layout in
-    /// [`messages::auction_list_items`]) — the search's filters as the server reads them, with
-    /// [`messages::auction_filter`]'s sentinels for the ones left unset. **No sort rides the
-    /// wire**: sorting the returned page is entirely ours. `list_from` pages by
-    /// [`messages::AUCTION_PAGE_SIZE`]. Answered by `SMSG_AUCTION_LIST_RESULT`.
+    /// Ask a Browse page; unset filters are [`messages::auction_filter`]'s sentinels, no sort rides
+    /// the wire, and `list_from` pages by [`messages::AUCTION_PAGE_SIZE`].
     pub fn auction_list_items(
         &mut self,
         auctioneer: u64,
@@ -66,9 +50,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ask the Auctions tab page (`CMSG_AUCTION_LIST_OWNER_ITEMS`, layout in
-    /// [`messages::auction_list_owner_items`]) — our own listings. Answered by
-    /// `SMSG_AUCTION_OWNER_LIST_RESULT`.
+    /// Ask a page of our own auctions (`CMSG_AUCTION_LIST_OWNER_ITEMS`).
     pub fn auction_list_owner_items(&mut self, auctioneer: u64, list_from: u32) -> Result<()> {
         self.send(
             opcode::CMSG_AUCTION_LIST_OWNER_ITEMS,
@@ -76,11 +58,8 @@ impl WorldWriter {
         )
     }
 
-    /// Ask the Bid tab page (`CMSG_AUCTION_LIST_BIDDER_ITEMS`, layout in
-    /// [`messages::auction_list_bidder_items`]). `auction_ids` is a **refresh set**, not a filter:
-    /// the server prepends a record for each id named and then appends every auction we are the
-    /// current bidder on. Pass `&[]` for a plain page. Answered by
-    /// `SMSG_AUCTION_BIDDER_LIST_RESULT`.
+    /// Ask a Bid tab page (`CMSG_AUCTION_LIST_BIDDER_ITEMS`). `auction_ids` is a refresh set, not
+    /// a filter: the server lists those first, then every auction we are the current bidder on.
     pub fn auction_list_bidder_items(
         &mut self,
         auctioneer: u64,
@@ -93,12 +72,7 @@ impl WorldWriter {
         )
     }
 
-    /// List an item for auction (`CMSG_AUCTION_SELL_ITEM`, layout in
-    /// [`messages::auction_sell_item`]) — the Create Auction pane's Create button.
-    /// `etime_minutes` must be one of [`messages::auction_duration`]'s three values (120/480/1440);
-    /// the deposit is charged immediately out of the player's purse. Answered by
-    /// `SMSG_AUCTION_COMMAND_RESULT` (action [`messages::auction_action::STARTED`]) — or by
-    /// silence, if the bid or duration is zero or the deposit is unaffordable.
+    /// List an item; `etime_minutes` is 120, 480 or 1440, and the deposit is charged at once.
     pub fn auction_sell_item(
         &mut self,
         auctioneer: u64,
@@ -113,11 +87,7 @@ impl WorldWriter {
         )
     }
 
-    /// Bid on — or buy out — an auction (`CMSG_AUCTION_PLACE_BID`, layout in
-    /// [`messages::auction_place_bid`]). One verb for both: the server reads a `price` at or above
-    /// a nonzero buyout *as* a buyout; there is no separate opcode and no flag. Answered by
-    /// `SMSG_AUCTION_COMMAND_RESULT` (action [`messages::auction_action::BID_PLACED`]), or by
-    /// silence if the player cannot afford the price.
+    /// Bid on an auction; a `price` at or above a nonzero buyout is the buyout.
     pub fn auction_place_bid(
         &mut self,
         auctioneer: u64,
@@ -130,11 +100,7 @@ impl WorldWriter {
         )
     }
 
-    /// Cancel one of our own auctions (`CMSG_AUCTION_REMOVE_ITEM`, layout in
-    /// [`messages::auction_remove_item`]) — the Auctions tab's Cancel button. The deposit is
-    /// **forfeit**, and if the auction already carries a bid the 5% cut comes out of the seller's
-    /// pocket (and the cancel is refused *silently* when they cannot pay it). Answered by
-    /// `SMSG_AUCTION_COMMAND_RESULT` (action [`messages::auction_action::REMOVED`]).
+    /// Cancel one of our auctions; the deposit is forfeit, and with a bid the seller pays 5%.
     pub fn auction_remove_item(&mut self, auctioneer: u64, auction_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_AUCTION_REMOVE_ITEM,
diff --git a/crates/benilla-protocol/src/world/writer/bank.rs b/crates/benilla-protocol/src/world/writer/bank.rs
index 914e046a..7187f95e 100644
--- a/crates/benilla-protocol/src/world/writer/bank.rs
+++ b/crates/benilla-protocol/src/world/writer/bank.rs
@@ -1,11 +1,5 @@
-//! The bank window's `WorldWriter` sends — open the bank, buy the next bag slot, deposit,
-//! withdraw. Bodies in [`crate::messages::bank`], whose scope this mirrors. Split out of
-//! `writer/mod.rs` (decision 0636).
-//!
-//! There is no dedicated withdraw opcode in the sense the names suggest: vmangos routes
-//! `CMSG_AUTOBANK_ITEM` / `CMSG_AUTOSTORE_BANK_ITEM` by whether the source `(bag, slot)` *is* a
-//! bank position, so it tolerates either direction and the pair is really "move it across the bank
-//! boundary, server picks the destination" (decision 0604).
+//! The bank sends. vmangos routes `CMSG_AUTOBANK_ITEM` and `CMSG_AUTOSTORE_BANK_ITEM` by whether
+//! the source is a bank position, so either moves an item across the bank boundary.
 
 use anyhow::Result;
 
@@ -14,8 +8,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Open the bank (`CMSG_BANKER_ACTIVATE`, layout in [`messages::banker_activate`]) — one
-    /// 8-byte banker guid. Answered by `SMSG_SHOW_BANK` (decision 0604).
+    /// Open the bank (`CMSG_BANKER_ACTIVATE`, full banker guid), answered by `SMSG_SHOW_BANK`.
     pub fn banker_activate(&mut self, banker_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_BANKER_ACTIVATE,
@@ -23,9 +16,7 @@ impl WorldWriter {
         )
     }
 
-    /// Buy the next bank-bag slot (`CMSG_BUY_BANK_SLOT`, layout in [`messages::buy_bank_slot`]).
-    /// No packet on success (the PLAYER_BYTES_2 count + coinage deltas are the confirmation);
-    /// refusal answers `SMSG_BUY_BANK_SLOT_RESULT`.
+    /// Buy the next bank-bag slot; success is silent, failure answers `SMSG_BUY_BANK_SLOT_RESULT`.
     pub fn buy_bank_slot(&mut self, banker_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_BUY_BANK_SLOT,
@@ -33,8 +24,7 @@ impl WorldWriter {
         )
     }
 
-    /// Deposit an item into the bank (`CMSG_AUTOBANK_ITEM`, layout in
-    /// [`messages::autobank_item`]): the wire `(bag, slot)` of the source item.
+    /// Deposit the item at wire `(bag, slot)` into the bank (`CMSG_AUTOBANK_ITEM`).
     pub fn autobank_item(&mut self, bag: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOBANK_ITEM,
@@ -42,9 +32,7 @@ impl WorldWriter {
         )
     }
 
-    /// Withdraw a bank item into the bags (`CMSG_AUTOSTORE_BANK_ITEM`, layout in
-    /// [`messages::autostore_bank_item`]): the wire `(bag, slot)` of the bank item (vmangos
-    /// routes by whether the source is a bank position, so it tolerates either direction).
+    /// Withdraw the bank item at wire `(bag, slot)` into the bags (`CMSG_AUTOSTORE_BANK_ITEM`).
     pub fn autostore_bank_item(&mut self, bag: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOSTORE_BANK_ITEM,
diff --git a/crates/benilla-protocol/src/world/writer/battlefield.rs b/crates/benilla-protocol/src/world/writer/battlefield.rs
index c79767ec..6568cdc9 100644
--- a/crates/benilla-protocol/src/world/writer/battlefield.rs
+++ b/crates/benilla-protocol/src/world/writer/battlefield.rs
@@ -1,4 +1,4 @@
-//! The battleground queue's sends (decision 1963).
+//! The battleground queue's sends.
 
 use anyhow::Result;
 
@@ -7,8 +7,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Answer a ready battleground (`CMSG_BATTLEFIELD_PORT`): the slot's map id and whether to
-    /// enter — `AcceptBattlefieldPort(index, accept)`'s packet.
+    /// Enter or decline a ready battleground by map id, as `AcceptBattlefieldPort` sends.
     pub fn battlefield_port(&mut self, map_id: u32, accept: bool) -> Result<()> {
         self.send(
             opcode::CMSG_BATTLEFIELD_PORT,
@@ -16,14 +15,12 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for the scoreboard (`MSG_PVP_LOG_DATA`, empty) — `RequestBattlefieldScoreData()`'s
-    /// packet; the 5000 ms throttle is the caller's (decision 1972).
+    /// Ask the scoreboard (`RequestBattlefieldScoreData`); the caller throttles it to 5000 ms.
     pub fn request_battlefield_score_data(&mut self) -> Result<()> {
         self.send(opcode::MSG_PVP_LOG_DATA, &[])
     }
 
-    /// Leave the battleground (`CMSG_LEAVE_BATTLEFIELD`): `LeaveBattlefield()`'s packet, sent
-    /// only once the scoreboard's "ended" byte has arrived (decision 1972).
+    /// Leave the battleground, sent only once the scoreboard's "ended" byte has arrived.
     pub fn leave_battlefield(&mut self, map_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_LEAVE_BATTLEFIELD,
@@ -31,8 +28,7 @@ impl WorldWriter {
         )
     }
 
-    /// Reopen a queued battleground's instance list (`CMSG_BATTLEFIELD_LIST`):
-    /// `ShowBattlefieldList(index)`'s packet, the queued slot's map (decision 1974).
+    /// Reopen a queued slot's instance list by map, as `ShowBattlefieldList` sends.
     pub fn battlefield_list(&mut self, map_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_BATTLEFIELD_LIST,
@@ -40,8 +36,7 @@ impl WorldWriter {
         )
     }
 
-    /// Join through the battlemaster the list came from (`CMSG_BATTLEMASTER_JOIN`) —
-    /// `JoinBattlefield`'s packet when the cached guid is non-zero (decision 1974).
+    /// Join through the list's battlemaster, as `JoinBattlefield` sends for a non-zero guid.
     pub fn battlemaster_join(
         &mut self,
         battlemaster: u64,
@@ -55,8 +50,7 @@ impl WorldWriter {
         )
     }
 
-    /// Join without a battlemaster (`CMSG_BATTLEFIELD_JOIN`) — `JoinBattlefield`'s packet when
-    /// the list arrived with a zero guid (decision 1974).
+    /// Join without a battlemaster, as `JoinBattlefield` sends when the list had a zero guid.
     pub fn battlefield_join(
         &mut self,
         map_id: u32,
@@ -69,14 +63,12 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for every queue slot's state (`CMSG_BATTLEFIELD_STATUS`, empty) — the reference's
-    /// world-enter reset sends it once per entry (decision 1974).
+    /// Ask every queue slot's state; the reference sends it once per world entry.
     pub fn battlefield_status(&mut self) -> Result<()> {
         self.send(opcode::CMSG_BATTLEFIELD_STATUS, &[])
     }
 
-    /// Ask for the teammates' positions (`MSG_BATTLEGROUND_PLAYER_POSITIONS`, empty) —
-    /// `RequestBattlefieldPositions()`'s packet; the 5000 ms throttle is the caller's (1980).
+    /// Ask teammates' positions (`RequestBattlefieldPositions`); the caller throttles to 5000 ms.
     pub fn request_battlefield_positions(&mut self) -> Result<()> {
         self.send(opcode::MSG_BATTLEGROUND_PLAYER_POSITIONS, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/binder.rs b/crates/benilla-protocol/src/world/writer/binder.rs
index c9929256..5f97bb75 100644
--- a/crates/benilla-protocol/src/world/writer/binder.rs
+++ b/crates/benilla-protocol/src/world/writer/binder.rs
@@ -1,9 +1,5 @@
-//! The innkeeper bind answer — the client's one send in the bind family (decision 1331).
-//!
-//! There is no "bind me here" verb: the flow starts with the *server's* `SMSG_BINDER_CONFIRM`
-//! (raised by selecting the innkeeper's gossip line), and this is the Yes. The guid is the one
-//! that arrived in the confirm; vmangos resolves it back to a live innkeeper in interact range
-//! (`HandleBinderActivateOpcode`), so it is load-bearing rather than an echo.
+//! The innkeeper bind answer: the Yes to the server's `SMSG_BINDER_CONFIRM`, carrying its guid,
+//! which vmangos resolves to an innkeeper in range (`HandleBinderActivateOpcode`).
 
 use anyhow::Result;
 
@@ -12,9 +8,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Accept an innkeeper's bind offer (`CMSG_BINDER_ACTIVATE`) — the `CONFIRM_BINDER` dialog's
-    /// Accept. The server answers by casting spell 3286 on us, which lands as
-    /// `SMSG_BINDPOINTUPDATE` + `SMSG_PLAYERBOUND`; declining sends nothing at all.
+    /// Accept an innkeeper's bind offer (`CMSG_BINDER_ACTIVATE`). The server casts spell 3286 on
+    /// us, landing as `SMSG_BINDPOINTUPDATE` and `SMSG_PLAYERBOUND`; declining sends nothing.
     pub fn binder_activate(&mut self, binder_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_BINDER_ACTIVATE,
diff --git a/crates/benilla-protocol/src/world/writer/channel.rs b/crates/benilla-protocol/src/world/writer/channel.rs
index dba039d1..357e2329 100644
--- a/crates/benilla-protocol/src/world/writer/channel.rs
+++ b/crates/benilla-protocol/src/world/writer/channel.rs
@@ -1,8 +1,4 @@
-//! The channel family's `WorldWriter` sends — join/leave/list/moderation (bodies in
-//! [`crate::messages`]'s `join_channel`/`leave_channel`/`channel_*` builders, all cstring-only
-//! shapes; layout VERIFIED against vmangos `Server/Packets/Channel.h`/`.cpp`). Split out of
-//! `writer/mod.rs` (decision 0288 phase 1) — the channel administration commands are one clearly
-//! separable concern among the writer's many domains.
+//! The channel sends: join, leave, list and moderation, all with cstring-only bodies.
 
 use anyhow::Result;
 
@@ -11,12 +7,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Join a channel (`CMSG_JOIN_CHANNEL`, layout in [`messages::join_channel`]): `password` is an
-    /// empty string for a channel that has none. Zone channels (General/Trade/LocalDefense) are
-    /// joined by the CLIENT too — in 1.12 the client walks ChatChannels.dbc on login/zone-in and
-    /// sends this same packet with the composed name ("General - Elwynn Forest"); the server only
-    /// tracks membership by name (decision 0288 phase 6 drives that walk). Answered by
-    /// `SMSG_CHANNEL_NOTIFY`'s `YOU_JOINED`/`WRONG_PASSWORD`/`BANNED`/… notice.
+    /// Join a channel; the 1.12 client joins zone channels this way ("General - Elwynn Forest").
     pub fn join_channel(&mut self, name: &str, password: &str) -> Result<()> {
         self.send(
             opcode::CMSG_JOIN_CHANNEL,
@@ -24,19 +15,17 @@ impl WorldWriter {
         )
     }
 
-    /// Leave a channel (`CMSG_LEAVE_CHANNEL`, layout in [`messages::leave_channel`]).
+    /// Leave a channel (`CMSG_LEAVE_CHANNEL`).
     pub fn leave_channel(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_LEAVE_CHANNEL, &messages::leave_channel(name))
     }
 
-    /// Ask a channel's member roster (`CMSG_CHANNEL_LIST`, layout in [`messages::channel_list`]),
-    /// the `/chatlist` / `/list` command. Answered by `SMSG_CHANNEL_LIST`.
+    /// Ask a channel's members (`CMSG_CHANNEL_LIST`, `/chatlist`), answered by `SMSG_CHANNEL_LIST`.
     pub fn channel_list(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_CHANNEL_LIST, &messages::channel_list(name))
     }
 
-    /// Set a channel's password (`CMSG_CHANNEL_PASSWORD`, layout in
-    /// [`messages::channel_password`]) — owner-only server-side.
+    /// Set a channel's password (`CMSG_CHANNEL_PASSWORD`); owner only.
     pub fn channel_password(&mut self, name: &str, password: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_PASSWORD,
@@ -44,8 +33,7 @@ impl WorldWriter {
         )
     }
 
-    /// Transfer channel ownership (`CMSG_CHANNEL_SET_OWNER`, layout in
-    /// [`messages::channel_set_owner`]) — owner-only server-side.
+    /// Transfer channel ownership (`CMSG_CHANNEL_SET_OWNER`); owner only.
     pub fn channel_set_owner(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_SET_OWNER,
@@ -53,14 +41,12 @@ impl WorldWriter {
         )
     }
 
-    /// Ask who owns a channel (`CMSG_CHANNEL_OWNER`, layout in [`messages::channel_owner`]) — the
-    /// `/console` "who owns" query. Answered by `SMSG_CHANNEL_NOTIFY`'s `CHANNEL_OWNER` notice.
+    /// Ask who owns a channel (`CMSG_CHANNEL_OWNER`), answered by a `CHANNEL_OWNER` notify.
     pub fn channel_owner(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_CHANNEL_OWNER, &messages::channel_owner(name))
     }
 
-    /// Grant moderator (`CMSG_CHANNEL_MODERATOR`, layout in [`messages::channel_moderator`]) —
-    /// owner-only server-side.
+    /// Grant moderator (`CMSG_CHANNEL_MODERATOR`); owner only.
     pub fn channel_moderator(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_MODERATOR,
@@ -68,7 +54,7 @@ impl WorldWriter {
         )
     }
 
-    /// Revoke moderator (`CMSG_CHANNEL_UNMODERATOR`, layout in [`messages::channel_unmoderator`]).
+    /// Revoke moderator (`CMSG_CHANNEL_UNMODERATOR`).
     pub fn channel_unmoderator(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_UNMODERATOR,
@@ -76,8 +62,7 @@ impl WorldWriter {
         )
     }
 
-    /// Mute a player on the channel (`CMSG_CHANNEL_MUTE`, layout in [`messages::channel_mute`]) —
-    /// moderator-only server-side.
+    /// Mute a player on the channel (`CMSG_CHANNEL_MUTE`); moderator only.
     pub fn channel_mute(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_MUTE,
@@ -85,7 +70,7 @@ impl WorldWriter {
         )
     }
 
-    /// Unmute a player (`CMSG_CHANNEL_UNMUTE`, layout in [`messages::channel_unmute`]).
+    /// Unmute a player (`CMSG_CHANNEL_UNMUTE`).
     pub fn channel_unmute(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_UNMUTE,
@@ -93,9 +78,7 @@ impl WorldWriter {
         )
     }
 
-    /// Invite a player to a moderated/private channel (`CMSG_CHANNEL_INVITE`, layout in
-    /// [`messages::channel_invite`]); level-gated server-side
-    /// (`CONFIG_UINT32_CHANNEL_INVITE_MIN_LEVEL`).
+    /// Invite a player to a channel, gated on `CONFIG_UINT32_CHANNEL_INVITE_MIN_LEVEL`.
     pub fn channel_invite(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_INVITE,
@@ -103,8 +86,7 @@ impl WorldWriter {
         )
     }
 
-    /// Kick a player off the channel (`CMSG_CHANNEL_KICK`, layout in [`messages::channel_kick`]) —
-    /// moderator-only server-side.
+    /// Kick a player off the channel (`CMSG_CHANNEL_KICK`); moderator only.
     pub fn channel_kick(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_KICK,
@@ -112,8 +94,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ban a player from the channel (`CMSG_CHANNEL_BAN`, layout in [`messages::channel_ban`]) —
-    /// moderator-only server-side.
+    /// Ban a player from the channel (`CMSG_CHANNEL_BAN`); moderator only.
     pub fn channel_ban(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_BAN,
@@ -121,7 +102,7 @@ impl WorldWriter {
         )
     }
 
-    /// Unban a player (`CMSG_CHANNEL_UNBAN`, layout in [`messages::channel_unban`]).
+    /// Unban a player (`CMSG_CHANNEL_UNBAN`).
     pub fn channel_unban(&mut self, name: &str, player: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_UNBAN,
@@ -129,8 +110,7 @@ impl WorldWriter {
         )
     }
 
-    /// Toggle join/leave announcements (`CMSG_CHANNEL_ANNOUNCEMENTS`, layout in
-    /// [`messages::channel_announcements`]) — owner/moderator-only server-side.
+    /// Toggle join/leave announcements (`CMSG_CHANNEL_ANNOUNCEMENTS`); owner or moderator only.
     pub fn channel_announcements(&mut self, name: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_ANNOUNCEMENTS,
@@ -138,8 +118,7 @@ impl WorldWriter {
         )
     }
 
-    /// Toggle moderation (speak-restricted-to-moderators) mode (`CMSG_CHANNEL_MODERATE`, layout in
-    /// [`messages::channel_moderate`]) — owner-only server-side.
+    /// Toggle moderated mode, where only moderators speak (`CMSG_CHANNEL_MODERATE`); owner only.
     pub fn channel_moderate(&mut self, name: &str) -> Result<()> {
         self.send(
             opcode::CMSG_CHANNEL_MODERATE,
diff --git a/crates/benilla-protocol/src/world/writer/chat.rs b/crates/benilla-protocol/src/world/writer/chat.rs
index 95e0a128..f0cfcde6 100644
--- a/crates/benilla-protocol/src/world/writer/chat.rs
+++ b/crates/benilla-protocol/src/world/writer/chat.rs
@@ -1,16 +1,5 @@
-//! The chat frame's `WorldWriter` sends — every `CMSG_MESSAGECHAT` flavour the slash commands
-//! reach (say/yell/emote/whisper/party/raid/guild/officer/the two raid-leader forms/the two
-//! battleground forms/AFK/DND/channel), the ignore-list notify, and the three non-`MESSAGECHAT`
-//! slash commands whose *answer* is a chat line (`/played`, `/random`, the DBC-indexed `/wave`).
-//! Bodies in [`crate::messages`]'s `messagechat*`/`played_time`/`random_roll`/`text_emote`
-//! builders; the inbound half is [`crate::messages::chat`]. Split out of `writer/mod.rs`
-//! (decision 0636), mirroring [`super::channel`], which owns the channel *administration* verbs
-//! (join/leave/moderation) — only the channel *send* lives here.
-//!
-//! One fact governs the whole family: **every send must speak [`WorldWriter::chat_language`]**, the
-//! logged-in character's own tongue. vmangos rejects `Universal` from clients and rejects a tongue
-//! the character doesn't know, dropping the whole message — which silently ate every Horde
-//! character's dot-commands while this was hardcoded Common.
+//! The chat sends. Chat speaks [`WorldWriter::chat_language`]: vmangos drops `Universal` from
+//! clients and any tongue the character does not know.
 
 use anyhow::Result;
 
@@ -19,11 +8,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Send a chat line as `/say`. Used to issue server **dot commands** (`.tele Westfall`, …) —
-    /// vmangos parses anything beginning with `.` as a GM command on the way in, but only *after*
-    /// the language gate: the send must speak [`Self::chat_language`], the character's own tongue
-    /// (**vmangos rejects `Universal` from clients**, and rejects a tongue the character doesn't
-    /// know — which silently ate every Horde character's commands while this was hardcoded Common).
+    /// Send a `/say` line; dot-commands go out this way, parsed after the language gate.
     pub fn send_chat(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -31,8 +16,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/yell` line (`CHAT_MSG_YELL`) — same body shape as [`Self::send_chat`], a different
-    /// wire chat type (VERIFIED vmangos `SharedDefines.h:1199`).
+    /// Send a `/yell` line (`CHAT_MSG_YELL`, `SharedDefines.h:1199`).
     pub fn send_yell(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -40,9 +24,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a custom `/emote <text>` line (`CHAT_MSG_EMOTE`, VERIFIED vmangos
-    /// `SharedDefines.h:1202`) — distinct from [`Self::text_emote`]'s DBC-indexed `/wave`: the
-    /// server renders it verbatim as `"PlayerName <text>"`.
+    /// Send a custom `/emote` line (`CHAT_MSG_EMOTE`), shown verbatim as `"PlayerName <text>"`.
     pub fn send_emote_chat(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -50,10 +32,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/whisper <target> <text>` line (`CHAT_MSG_WHISPER`): body in
-    /// [`messages::messagechat_whisper`], the one `CMSG_MESSAGECHAT` shape that carries a name
-    /// ahead of the message (VERIFIED vmangos `Server/Packets/Chat.cpp:3-12`). A bad `target`
-    /// answers `SMSG_CHAT_PLAYER_NOT_FOUND`, unmodelled here — silent from the client's own POV.
+    /// Send a `/whisper` line; the body carries the name before the message (`Chat.cpp:3-12`).
     pub fn send_whisper(&mut self, target: &str, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -61,10 +40,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/p` party line (`CHAT_MSG_PARTY`) — same body shape as [`Self::send_chat`] (VERIFIED
-    /// vmangos `Handlers/ChatHandler.cpp:472-493`: the server rebroadcasts to the group, no group
-    /// membership needed on the wire — the server enforces it and silently drops the send if we're
-    /// not grouped).
+    /// Send a `/p` party line, dropped silently when ungrouped (`ChatHandler.cpp:472-493`).
     pub fn send_party(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -72,8 +48,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/ra` raid line (`CHAT_MSG_RAID`) — requires a raid group server-side
-    /// (`Handlers/ChatHandler.cpp:514-536`).
+    /// Send a `/ra` raid line (`CHAT_MSG_RAID`); needs a raid (`ChatHandler.cpp:514-536`).
     pub fn send_raid(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -81,8 +56,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/g` guild line (`CHAT_MSG_GUILD`) — requires guild membership server-side
-    /// (`Handlers/ChatHandler.cpp:494-503`).
+    /// Send a `/g` guild line (`CHAT_MSG_GUILD`); needs a guild (`ChatHandler.cpp:494-503`).
     pub fn send_guild(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -90,8 +64,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/o` guild-officer line (`CHAT_MSG_OFFICER`) — requires guild membership server-side
-    /// (`Handlers/ChatHandler.cpp:504-513`).
+    /// Send a `/o` officer line (`CHAT_MSG_OFFICER`); needs a guild (`ChatHandler.cpp:504-513`).
     pub fn send_officer(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -99,8 +72,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/rl` raid-leader line (`CHAT_MSG_RAID_LEADER`) — leader-only server-side
-    /// (`Handlers/ChatHandler.cpp:538-559`; VERIFIED active for 5875, `> CLIENT_BUILD_1_10_2`).
+    /// Send a `/rl` raid-leader line, leader only (`ChatHandler.cpp:538-559`).
     pub fn send_raid_leader(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -108,8 +80,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/rw` raid-warning line (`CHAT_MSG_RAID_WARNING`) — leader/assistant-only server-side
-    /// (`Handlers/ChatHandler.cpp:561-576`).
+    /// Send a `/rw` raid warning, leader or assistant only (`ChatHandler.cpp:561-576`).
     pub fn send_raid_warning(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -121,8 +92,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a battleground raid line (`CHAT_MSG_BATTLEGROUND`) — requires a BG group server-side
-    /// (`Handlers/ChatHandler.cpp:579-593`; VERIFIED active for 5875, `> CLIENT_BUILD_1_11_2`).
+    /// Send a battleground line; needs a battleground group (`ChatHandler.cpp:579-593`).
     pub fn send_battleground(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -134,8 +104,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a battleground-leader line (`CHAT_MSG_BATTLEGROUND_LEADER`) — BG-group-leader-only
-    /// server-side (`Handlers/ChatHandler.cpp:595-609`).
+    /// Send a battleground-leader line, leader only (`ChatHandler.cpp:595-609`).
     pub fn send_battleground_leader(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -147,9 +116,7 @@ impl WorldWriter {
         )
     }
 
-    /// Toggle AFK (`CHAT_MSG_AFK`, `/afk [message]`) — `message` may be empty (a bare toggle); when
-    /// non-empty it becomes the AFK auto-reply text (vmangos `Handlers/ChatHandler.cpp:611-630`:
-    /// `masterPlr->afkMsg`). Setting AFK clears DND server-side (mutually exclusive).
+    /// Toggle AFK, `message` the auto-reply if any; it clears DND (`ChatHandler.cpp:611-630`).
     pub fn send_afk(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -157,8 +124,7 @@ impl WorldWriter {
         )
     }
 
-    /// Toggle DND (`CHAT_MSG_DND`, `/dnd [message]`) — same shape as [`Self::send_afk`]
-    /// (`Handlers/ChatHandler.cpp:632-648`); mutually exclusive with AFK server-side.
+    /// Toggle DND (`CHAT_MSG_DND`), which clears AFK (`ChatHandler.cpp:632-648`).
     pub fn send_dnd(&mut self, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -166,26 +132,9 @@ impl WorldWriter {
         )
     }
 
-    /// **Send an addon broadcast** (`SendAddonMessage`, decision 1235) — the one `CMSG_MESSAGECHAT`
-    /// in this module that does **not** speak [`Self::chat_language`].
-    ///
-    /// `chat_type` is one of the client's four addon lanes (`CHAT_TYPE_PARTY`/`RAID`/`GUILD`/
-    /// `BATTLEGROUND`); `text` is the already-composed `prefix` TAB `message` payload — this verb
-    /// does not compose it, because the Lua binding does and the tab's position is the only thing
-    /// the far client's splitter has to go on.
-    ///
-    /// The language field carries [`messages::LANGUAGE_ADDON`] (`0xFFFFFFFF`), and that sentinel
-    /// is the entire difference between addon data and speech: 1.12.1 has no addon opcode.
-    /// VERIFIED in `WoW.exe` (5875), wow-re `system/ui/scratch/addon-chat-law.md` §5 — the binding
-    /// `0x49f920` writes opcode `0x95` (`0x49facf`), the chat type (`0x49fad8`), then
-    /// `or ebx,-0x1` / `push ebx` (`0x49fab9`/`0x49fadd`) into the u32 language write at
-    /// `0x49fae1`, then the message CString at `0x49faf0`. Corroborated end-to-end against a live
-    /// vmangos by `examples/addon_chat_probe` (decision 1029): the sentinel and the tab both
-    /// survive the relay untouched.
-    ///
-    /// Server-side the line is exempt from the `KnowsLanguage` gate, from flood control and from
-    /// `SanitizeChatMessage`, and gated instead by the `AddonChannel` config — see
-    /// [`messages::LANGUAGE_ADDON`] for the whole treatment.
+    /// Send an addon message (`SendAddonMessage`). Its language, [`messages::LANGUAGE_ADDON`], is
+    /// the only mark of addon data (`0x49f920`); vmangos gates it on `AddonChannel` and skips the
+    /// language gate, flood control and sanitizing.
     pub fn send_addon_message(&mut self, chat_type: u32, text: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -193,9 +142,7 @@ impl WorldWriter {
         )
     }
 
-    /// Send a `/1`-style channel line (`CHAT_MSG_CHANNEL`) — `channel` is the channel **name**
-    /// (`Handlers/ChatHandler.cpp:255-327`; body in [`messages::messagechat_channel`]). Requires
-    /// membership; the server silently drops it if we're not on the channel.
+    /// Send a channel line by name, dropped unless we are on it (`ChatHandler.cpp:255-327`).
     pub fn send_channel(&mut self, channel: &str, message: &str) -> Result<()> {
         self.send(
             opcode::CMSG_MESSAGECHAT,
@@ -203,31 +150,22 @@ impl WorldWriter {
         )
     }
 
-    /// Tell the server we've added `guid` to our ignore list (`CMSG_CHAT_IGNORED`, a raw 8-byte
-    /// guid — VERIFIED vmangos `WorldPackets::Misc::ChatIgnored::ReadFromWorldPacket`,
-    /// `Server/Packets/Misc.cpp:127-130`). The server whispers that player a `CHAT_MSG_IGNORED`
-    /// self-notice ("So-and-so is now ignoring you") — `Handlers/ChatHandler.cpp:755-763`.
+    /// Tell the server we ignore `guid`; that player gets a `CHAT_MSG_IGNORED` notice.
     pub fn chat_ignored(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_CHAT_IGNORED, &messages::full_guid(guid))
     }
 
-    /// Ask our played time (`CMSG_PLAYED_TIME`, empty body, layout in [`messages::played_time`]) —
-    /// the `/played` command. Answered by `SMSG_PLAYED_TIME` (total + since-last-level-up seconds).
+    /// Ask our played time (`CMSG_PLAYED_TIME`), answered by `SMSG_PLAYED_TIME`.
     pub fn played_time(&mut self) -> Result<()> {
         self.send(opcode::CMSG_PLAYED_TIME, &messages::played_time())
     }
 
-    /// Roll `/random [min] [max]` (`MSG_RANDOM_ROLL`, layout in [`messages::random_roll`]): the
-    /// server validates `min <= max <= 10000` and broadcasts the result (to our group if we're in
-    /// one, else just to us) as the same opcode's server→client shape — `min, max, roll, guid`
-    /// (decoded by the codec into a `RandomRoll` event).
+    /// Roll `/random`; the server checks `min <= max <= 10000` and answers on the same opcode.
     pub fn random_roll(&mut self, min: u32, max: u32) -> Result<()> {
         self.send(opcode::MSG_RANDOM_ROLL, &messages::random_roll(min, max))
     }
 
-    /// Perform a chat emote (`CMSG_TEXT_EMOTE`: EmotesText id + target guid, 0 = untargeted).
-    /// The server echoes `SMSG_TEXT_EMOTE` to everyone in range **including us**, so our own
-    /// emote's sound/anim arrive through the same receive path as everyone else's.
+    /// Perform a text emote (EmotesText id, target or 0), echoed to everyone in range, us included.
     pub fn text_emote(&mut self, text_id: u32, target: u64) -> Result<()> {
         self.send(
             opcode::CMSG_TEXT_EMOTE,
diff --git a/crates/benilla-protocol/src/world/writer/death.rs b/crates/benilla-protocol/src/world/writer/death.rs
index 993b6e6d..ae6c6b0b 100644
--- a/crates/benilla-protocol/src/world/writer/death.rs
+++ b/crates/benilla-protocol/src/world/writer/death.rs
@@ -1,13 +1,5 @@
-//! The death/corpse-run family's `WorldWriter` sends — release the spirit, find the corpse,
-//! reclaim it, self-resurrect off a soulstone, or take the spirit healer's res; plus the answer
-//! to someone else's res offer.
-//! Bodies in [`crate::messages`]'s `reclaim_corpse`/`spirit_healer_activate`/`resurrect_response`
-//! builders (`repop_request`, `corpse_query` and `self_res` are bodyless). Split out of
-//! `writer/mod.rs` (decision 0636), mirroring [`crate::messages::death`].
-//!
-//! Every one of these is server-gated on a death state the client only *believes* it is in
-//! (ghost/unreleased/delay-elapsed/in-range), so a refusal is normal and is not always a packet —
-//! the confirmations arrive as ordinary descriptor deltas.
+//! The death and corpse-run sends. Each is server-gated on a death state the client only believes
+//! it is in, so refusals are normal and not always a packet; success arrives as descriptor deltas.
 
 use anyhow::Result;
 
@@ -16,32 +8,23 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Release the spirit (`CMSG_REPOP_REQUEST`, empty body — decision 0308 slice 1): valid only
-    /// while dead and unreleased (the server refuses it alive or already-ghost). The server
-    /// answers with the ghost form (aura 8326 → the ghost flags), the corpse object, unroot,
-    /// water-walk, `SMSG_CORPSE_RECLAIM_DELAY`, and the graveyard teleport.
+    /// Release the spirit while dead and unreleased; the server answers with ghost aura 8326, the
+    /// corpse, `SMSG_CORPSE_RECLAIM_DELAY` and the graveyard teleport.
     pub fn repop_request(&mut self) -> Result<()> {
         self.send(opcode::CMSG_REPOP_REQUEST, &[])
     }
 
-    /// Ask where our corpse is (`MSG_CORPSE_QUERY`, empty request): answered by the same opcode
-    /// (the [`SessionEvent::CorpseQuery`](crate::SessionEvent::CorpseQuery) feed for the map
-    /// markers + the corpse-run range gate).
+    /// Ask where our corpse is (`MSG_CORPSE_QUERY`, empty body), answered on the same opcode.
     pub fn corpse_query(&mut self) -> Result<()> {
         self.send(opcode::MSG_CORPSE_QUERY, &[])
     }
 
-    /// Self-resurrect (`CMSG_SELF_RES`, empty body — decision 1746): the DEATH popup's second
-    /// button, offered only while `PLAYER_SELF_RES_SPELL` is non-zero. The server casts that
-    /// spell on us and zeroes the field; like the reclaim, the success is ordinary descriptor
-    /// deltas (alive, health/mana per the spell) with no answer packet of its own.
+    /// Self-resurrect while `PLAYER_SELF_RES_SPELL` is set; the server casts it, with no reply.
     pub fn self_res(&mut self) -> Result<()> {
         self.send(opcode::CMSG_SELF_RES, &[])
     }
 
-    /// Reclaim our corpse (`CMSG_RECLAIM_CORPSE` — the RECOVER_CORPSE popup's Accept): the corpse's
-    /// guid. Server gates: ghost, the reclaim delay elapsed, within 39 yd. Success comes back as
-    /// ordinary descriptor deltas (alive, ghost flags clear) + the corpse-to-bones swap.
+    /// Reclaim our corpse as a ghost, past the reclaim delay, within 39 yd.
     pub fn reclaim_corpse(&mut self, corpse_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_RECLAIM_CORPSE,
@@ -49,9 +32,7 @@ impl WorldWriter {
         )
     }
 
-    /// Take the spirit healer's resurrection (`CMSG_SPIRIT_HEALER_ACTIVATE` — the XP_LOSS
-    /// confirm's final Accept): res at 50%, 25% durability loss, resurrection sickness at
-    /// level ≥ 11. `npc` is the spirit healer's guid (from `SMSG_SPIRIT_HEALER_CONFIRM`).
+    /// Take the spirit healer's res: 50% health, 25% durability loss, sickness from level 11.
     pub fn spirit_healer_activate(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::CMSG_SPIRIT_HEALER_ACTIVATE,
@@ -59,8 +40,7 @@ impl WorldWriter {
         )
     }
 
-    /// Answer a resurrection offer (`CMSG_RESURRECT_RESPONSE` — the RESURRECT popup's
-    /// Accept/Decline): the offerer's guid + the accept byte.
+    /// Accept or decline a resurrection offer (`CMSG_RESURRECT_RESPONSE`).
     pub fn resurrect_response(&mut self, caster: u64, accept: bool) -> Result<()> {
         self.send(
             opcode::CMSG_RESURRECT_RESPONSE,
@@ -68,9 +48,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ask a battleground spirit healer for its clock (`CMSG_AREA_SPIRIT_HEALER_QUERY`) — sent
-    /// when the client adopts a new healer; answered by `SMSG_AREA_SPIRIT_HEALER_TIME`
-    /// (decision 1963).
+    /// Ask a new battleground spirit healer's clock, answered by `SMSG_AREA_SPIRIT_HEALER_TIME`.
     pub fn area_spirit_healer_query(&mut self, healer: u64) -> Result<()> {
         self.send(
             opcode::CMSG_AREA_SPIRIT_HEALER_QUERY,
@@ -78,8 +56,7 @@ impl WorldWriter {
         )
     }
 
-    /// Queue for the healer's next wave (`CMSG_AREA_SPIRIT_HEALER_QUEUE`) —
-    /// `AcceptAreaSpiritHeal()`'s packet, carrying the cached healer (decision 1963).
+    /// Queue for the healer's next wave, as `AcceptAreaSpiritHeal` sends.
     pub fn area_spirit_healer_queue(&mut self, healer: u64) -> Result<()> {
         self.send(
             opcode::CMSG_AREA_SPIRIT_HEALER_QUEUE,
diff --git a/crates/benilla-protocol/src/world/writer/duel.rs b/crates/benilla-protocol/src/world/writer/duel.rs
index f2d652de..2b8bae4f 100644
--- a/crates/benilla-protocol/src/world/writer/duel.rs
+++ b/crates/benilla-protocol/src/world/writer/duel.rs
@@ -1,10 +1,6 @@
-//! The duel family's `WorldWriter` sends — the only two the client ever makes (decision 0633).
-//!
-//! There is no "start a duel" opcode: the challenge goes out as an ordinary `CMSG_CAST_SPELL` of
-//! the spellbook spell whose `Effect[0]` is `SPELL_EFFECT_DUEL`, which is why nothing here builds
-//! one. Both bodies carry the duel-arbiter guid, byte-verified against WoW.exe's own
-//! `AcceptDuel 0x4d4830` / `CancelDuel 0x4d48b0` (bodies in [`crate::messages`]'s `duel_*`
-//! builders).
+//! The duel sends. There is no start-duel opcode: a challenge is a `CMSG_CAST_SPELL` of the spell
+//! whose `Effect[0]` is `SPELL_EFFECT_DUEL`. Both bodies carry the arbiter guid (`AcceptDuel`
+//! `0x4d4830`, `CancelDuel` `0x4d48b0`).
 
 use anyhow::Result;
 
@@ -13,8 +9,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Accept a duel challenge (`CMSG_DUEL_ACCEPTED`) — the popup's Accept, and the challenger's
-    /// own immediate auto-accept of the request it just triggered.
+    /// Accept a duel (`CMSG_DUEL_ACCEPTED`); the challenger also auto-accepts its own request.
     pub fn duel_accepted(&mut self, arbiter: u64) -> Result<()> {
         self.send(
             opcode::CMSG_DUEL_ACCEPTED,
@@ -22,9 +17,7 @@ impl WorldWriter {
         )
     }
 
-    /// Decline or abandon a duel (`CMSG_DUEL_CANCELLED`) — the popup's Decline, a cancel during
-    /// the countdown, and `/forfeit` once the duel is under way. The server reads the intent from
-    /// the duel's own state, not from the packet.
+    /// Decline, cancel or forfeit a duel; the server reads which from the duel's state.
     pub fn duel_cancelled(&mut self, arbiter: u64) -> Result<()> {
         self.send(
             opcode::CMSG_DUEL_CANCELLED,
diff --git a/crates/benilla-protocol/src/world/writer/gameobject.rs b/crates/benilla-protocol/src/world/writer/gameobject.rs
index 87f33f90..2a483abe 100644
--- a/crates/benilla-protocol/src/world/writer/gameobject.rs
+++ b/crates/benilla-protocol/src/world/writer/gameobject.rs
@@ -1,11 +1,4 @@
-//! The GameObject family's `WorldWriter` sends — the single player-facing USE verb and the
-//! ask-once template head. Bodies in [`crate::messages::gameobject`], whose scope this mirrors.
-//! Split out of `writer/mod.rs` (decision 0636).
-//!
-//! Two verbs is the whole family by design (decision 0236): the client does not know or care what
-//! kind of GameObject it just clicked — one `CMSG_GAMEOBJ_USE` goes out and the *server* fans it
-//! out by GO type. Everything the client needs to draw the thing and pick its cursor comes from the
-//! template query.
+//! The GameObject sends; one `CMSG_GAMEOBJ_USE` serves every kind, dispatched by type.
 
 use anyhow::Result;
 
@@ -14,20 +7,12 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Use a world GameObject (`CMSG_GAMEOBJ_USE`, layout in [`messages::gameobj_use`]) — the single
-    /// player-facing verb for any usable GO (decision 0236): a full guid naming the chest/door/quest
-    /// object/lever. The server fans it out by GO type — a chest answers with `SMSG_LOOT_RESPONSE`
-    /// (the loot window), a questgiver GO with the gossip/quest packets, a door with a
-    /// `GAMEOBJECT_STATE` flip via `UPDATE_OBJECT` — or refuses silently (out of range, locked, no
-    /// quest). There is no dedicated success reply.
+    /// Use a world GameObject; the server answers by type or refuses silently, with no ack.
     pub fn gameobj_use(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_GAMEOBJ_USE, &messages::gameobj_use(guid))
     }
 
-    /// Ask for a GameObject template's type/display/name/`data[24]` head (`CMSG_GAMEOBJECT_QUERY`:
-    /// entry + guid — the ask-once template lookup, decision 0236). The `entry` is the one embedded
-    /// in the GameObject's guid bits 24–47 ([`crate::guid::entry`]), the same convention as
-    /// [`WorldWriter::creature_query`]. Answered by `SMSG_GAMEOBJECT_QUERY_RESPONSE`.
+    /// Ask a GameObject template; `entry` is the guid's bits 24-47 ([`crate::guid::entry`]).
     pub fn gameobject_query(&mut self, entry: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_GAMEOBJECT_QUERY,
@@ -35,12 +20,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for one page of a book (`CMSG_PAGE_TEXT_QUERY`, layout in
-    /// [`messages::page_text_query`]) — the ask-once page cache a readable reaches when the reader
-    /// opens on it (decision 1105). `guid` names the asking object (the book item or the
-    /// `GAMEOBJECT_TYPE_TEXT` world object); the server resolves the page from the id alone.
-    /// Answered by `SMSG_PAGE_TEXT_QUERY_RESPONSE` — once per page of the whole chain, not just
-    /// the one asked for.
+    /// Ask a book page; the server resolves it by id alone and answers each page of the chain.
     pub fn page_text_query(&mut self, page_id: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_PAGE_TEXT_QUERY,
diff --git a/crates/benilla-protocol/src/world/writer/gm_ticket.rs b/crates/benilla-protocol/src/world/writer/gm_ticket.rs
index a012b609..89e93124 100644
--- a/crates/benilla-protocol/src/world/writer/gm_ticket.rs
+++ b/crates/benilla-protocol/src/world/writer/gm_ticket.rs
@@ -1,19 +1,9 @@
-//! The Help window's five sends — the whole client half of the GM trouble-ticket flow
-//! (decision 1673).
+//! The GM ticket sends. The client holds no ticket state; the server's answers are the only truth.
 //!
-//! Three of the five have empty bodies, which is the shape of the feature: the client holds no
-//! ticket state of its own, so "show me my ticket", "abandon it" and "is the queue up?" are each a
-//! bare opcode and the server's answer is the only truth. The two that carry a body — file and
-//! edit — are byte-verified against the real client's own senders (`0x5ef740` / `0x5efac0`); see
-//! [`crate::messages::gm_ticket`] for why the category is a single byte in both.
-//!
-//! **Nothing here may be retried on a timeout.** vmangos answers several refusals with silence
-//! rather than a response code (queue off, under `GMTickets.MinLevel`, category >= 11 —
-//! `GMTicketHandler.cpp:91,106-113`), and it treats more than two `CMSG_GMTICKET_UPDATETEXT` in a
-//! single world tick as flooding, whose default sanction is a **kick**
-//! (`WorldSession.cpp:1316-1342`, `Antiflood.Sanction = 8`). So a client that re-sent an edit
-//! because no answer came would disconnect itself. The Help window asks once per click, exactly as
-//! the reference does.
+//! Never retry one on a timeout: vmangos refuses several silently (queue off, under
+//! `GMTickets.MinLevel`, category >= 11, `GMTicketHandler.cpp:91,106-113`), and more than two
+//! `CMSG_GMTICKET_UPDATETEXT` in one world tick is flooding, kicked by default
+//! (`WorldSession.cpp:1316-1342`).
 
 use anyhow::Result;
 
@@ -22,12 +12,9 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// File a new ticket (`CMSG_GMTICKET_CREATE`) — the Help window's Submit.
-    ///
-    /// `category` is a `GMTicketCategory.dbc` id (1..10, the clicked row); `map`/`pos` are where
-    /// the player is standing, which is what lets a GM `.tele` to the reported spot. Answered by
-    /// `SMSG_GMTICKET_CREATE` — **or by nothing at all**, on the several vmangos paths that refuse
-    /// silently (module doc).
+    /// File a ticket (`CMSG_GMTICKET_CREATE`, sender `0x5ef740`): `category` is a
+    /// `GMTicketCategory.dbc` id 1-10, `map` and `pos` where the player stands. Answered by
+    /// `SMSG_GMTICKET_CREATE`, or by silence.
     pub fn gm_ticket_create(
         &mut self,
         category: u8,
@@ -41,11 +28,7 @@ impl WorldWriter {
         )
     }
 
-    /// Edit the open ticket's text (`CMSG_GMTICKET_UPDATETEXT`) — the Help window's "Save Changes".
-    ///
-    /// Carries the category byte the client carries even though vmangos reads and discards it; the
-    /// category of an existing ticket cannot actually be changed this way. Answered by
-    /// `SMSG_GMTICKET_UPDATETEXT`. **Rate-limited server-side** — see the module doc.
+    /// Edit the open ticket's text (sender `0x5efac0`); vmangos discards the category byte.
     pub fn gm_ticket_updatetext(&mut self, category: u8, text: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GMTICKET_UPDATETEXT,
@@ -53,26 +36,18 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for the open ticket (`CMSG_GMTICKET_GETTICKET`, empty body) — `GetGMTicket()`.
-    ///
-    /// The client's own poll: once on world entry and every 10 minutes while the ticket status
-    /// toast is up. Answered by `SMSG_GMTICKET_GETTICKET`, and on vmangos **also** by an
-    /// unsolicited `SMSG_QUERY_TIME_RESPONSE` — its handler calls `SendQueryTimeResponse()` as its
-    /// first statement (`GMTicketHandler.cpp:34`), so two packets come back for this one request.
+    /// Ask for the open ticket, on world entry and every 10 minutes with the toast up; vmangos also
+    /// sends an unsolicited `SMSG_QUERY_TIME_RESPONSE` (`GMTicketHandler.cpp:34`).
     pub fn gm_ticket_get(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GMTICKET_GETTICKET, &[])
     }
 
-    /// Abandon the open ticket (`CMSG_GMTICKET_DELETETICKET`, empty body) — the
-    /// `HELP_TICKET_ABANDON_CONFIRM` dialog's Yes. Answered by `SMSG_GMTICKET_DELETETICKET`
-    /// carrying 9, or — with no ticket to delete — by nothing at all on vmangos.
+    /// Abandon the open ticket; the reply carries 9, and vmangos sends none if there is no ticket.
     pub fn gm_ticket_delete(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GMTICKET_DELETETICKET, &[])
     }
 
-    /// Ask whether the petition queue is taking tickets (`CMSG_GMTICKET_SYSTEMSTATUS`, empty body)
-    /// — `GetGMStatus()`, which the Help window calls from its own OnShow. Answered by
-    /// `SMSG_GMTICKETSYSTEMSTATUS`.
+    /// Ask whether the ticket queue is open, as `GetGMStatus` does when the Help window shows.
     pub fn gm_ticket_system_status(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GMTICKET_SYSTEMSTATUS, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/gossip.rs b/crates/benilla-protocol/src/world/writer/gossip.rs
index cb286606..4a9ca716 100644
--- a/crates/benilla-protocol/src/world/writer/gossip.rs
+++ b/crates/benilla-protocol/src/world/writer/gossip.rs
@@ -1,11 +1,5 @@
-//! The gossip family's `WorldWriter` sends — open a menu, choose an option, and fetch a menu's
-//! greeting text. Bodies in [`crate::messages::gossip`], whose scope this mirrors. Split out of
-//! `writer/mod.rs` (decision 0636).
-//!
-//! `CMSG_GOSSIP_HELLO` is the front door to every other NPC service window — vendor, trainer,
-//! bank, taxi, quest — because the server passes `UNIT_NPC_FLAG_NONE` for this opcode (vmangos
-//! `CanInteractWithNPC`, `Player.cpp:347`), so it works on any interactable creature, not only
-//! gossip-flagged ones.
+//! The gossip sends. `CMSG_GOSSIP_HELLO` opens every NPC service window: vmangos accepts it for any
+//! interactable creature (`CanInteractWithNPC` with `UNIT_NPC_FLAG_NONE`, `Player.cpp:347`).
 
 use anyhow::Result;
 
@@ -14,18 +8,12 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Open a gossip menu on an NPC (`CMSG_GOSSIP_HELLO`, layout in [`messages::gossip_hello`]) —
-    /// works on any interactable creature, not only gossip-flagged ones (vmangos
-    /// `CanInteractWithNPC`, `Player.cpp:347`, passes `UNIT_NPC_FLAG_NONE` for this opcode).
-    /// Answered by `SMSG_GOSSIP_MESSAGE` (a `GossipMenu` event).
+    /// Open a gossip menu on an NPC (`CMSG_GOSSIP_HELLO`), answered by `SMSG_GOSSIP_MESSAGE`.
     pub fn gossip_hello(&mut self, npc_guid: u64) -> Result<()> {
         self.send(opcode::CMSG_GOSSIP_HELLO, &messages::gossip_hello(npc_guid))
     }
 
-    /// Choose a gossip option (`CMSG_GOSSIP_SELECT_OPTION`, layout in
-    /// [`messages::gossip_select_option`]): `gossip_list_id` is the option's echoed `index`; `code`
-    /// carries a password only for a `coded` option, omitted entirely otherwise. The server answers
-    /// either a fresh `SMSG_GOSSIP_MESSAGE` (a sub-menu) or `SMSG_GOSSIP_COMPLETE`.
+    /// Choose a gossip option by its echoed `index`; `code` is sent only for a coded option.
     pub fn gossip_select_option(
         &mut self,
         npc_guid: u64,
@@ -38,9 +26,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for a gossip menu's greeting text (`CMSG_NPC_TEXT_QUERY`, layout in
-    /// [`messages::npc_text_query`]) — sent on receiving a gossip menu's `text_id`. Answered by
-    /// `SMSG_NPC_TEXT_UPDATE` (an `NpcGreeting` event); ask-once cacheable like an item template.
+    /// Ask a gossip menu's greeting text (`CMSG_NPC_TEXT_QUERY`); ask once and cache.
     pub fn npc_text_query(&mut self, text_id: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_NPC_TEXT_QUERY,
diff --git a/crates/benilla-protocol/src/world/writer/group.rs b/crates/benilla-protocol/src/world/writer/group.rs
index f7ee6f9c..29dcb4d6 100644
--- a/crates/benilla-protocol/src/world/writer/group.rs
+++ b/crates/benilla-protocol/src/world/writer/group.rs
@@ -1,9 +1,4 @@
-//! The group/party family's `WorldWriter` sends — invite/accept/decline/kick/leader/disband, loot
-//! method, party-stats asks, raid subgroup management, minimap pings, raid-target icons, and ready
-//! checks (bodies in [`crate::messages`]'s `group_*`/`loot_method`/`minimap_ping`/`raid_target_*`/
-//! `ready_check_*` builders; layout VERIFIED against vmangos `Server/Packets/Group.{h,cpp}`,
-//! `Handlers/GroupHandler.cpp`). Split out of `writer/mod.rs`, mirroring [`super::channel`] — the
-//! group commands are one clearly separable concern among the writer's many domains.
+//! The group and raid sends.
 
 use anyhow::Result;
 
@@ -12,8 +7,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Invite a player to group (`CMSG_GROUP_INVITE`, layout in [`messages::group_invite`]).
-    /// Answered by `SMSG_PARTY_COMMAND_RESULT`; the invited player sees `SMSG_GROUP_INVITE`.
+    /// Invite a player to group, answered by `SMSG_PARTY_COMMAND_RESULT`.
     pub fn group_invite(&mut self, member_name: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_INVITE,
@@ -26,13 +20,12 @@ impl WorldWriter {
         self.send(opcode::CMSG_GROUP_ACCEPT, &messages::group_accept())
     }
 
-    /// Decline a pending group invite (`CMSG_GROUP_DECLINE`, empty body); the inviter sees
-    /// `SMSG_GROUP_DECLINE`.
+    /// Decline a pending group invite; the inviter gets `SMSG_GROUP_DECLINE`.
     pub fn group_decline(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GROUP_DECLINE, &messages::group_decline())
     }
 
-    /// Kick a group member by name (`CMSG_GROUP_UNINVITE`, layout in [`messages::group_uninvite`]).
+    /// Kick a group member by name (`CMSG_GROUP_UNINVITE`).
     pub fn group_uninvite(&mut self, member_name: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_UNINVITE,
@@ -40,7 +33,7 @@ impl WorldWriter {
         )
     }
 
-    /// Kick a group member by guid (`CMSG_GROUP_UNINVITE_GUID`) — the raid-frame right-click kick.
+    /// Kick a group member by guid (`CMSG_GROUP_UNINVITE_GUID`), the raid frame's kick.
     pub fn group_uninvite_guid(&mut self, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_UNINVITE_GUID,
@@ -48,7 +41,7 @@ impl WorldWriter {
         )
     }
 
-    /// Hand off group leadership (`CMSG_GROUP_SET_LEADER`, a full guid — the 1.12 wire form).
+    /// Hand off group leadership (`CMSG_GROUP_SET_LEADER`, a full guid in 1.12).
     pub fn group_set_leader(&mut self, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_SET_LEADER,
@@ -56,10 +49,9 @@ impl WorldWriter {
         )
     }
 
-    /// Set the group's loot method (`CMSG_LOOT_METHOD`, layout in [`messages::loot_method`]):
-    /// `method` is `0` free-for-all / `1` round-robin / `2` master / `3` group / `4`
-    /// need-before-greed; `loot_master` is the master looter's guid (ignored unless `method ==
-    /// 2`); `threshold` is an `ItemQualities` value.
+    /// Set the group's loot method (`CMSG_LOOT_METHOD`): `method` 0 free-for-all, 1 round-robin,
+    /// 2 master (the only one that reads `loot_master`), 3 group, 4 need-before-greed;
+    /// `threshold` is an `ItemQualities` value.
     pub fn loot_method(&mut self, method: u32, loot_master: u64, threshold: u32) -> Result<()> {
         self.send(
             opcode::CMSG_LOOT_METHOD,
@@ -72,8 +64,7 @@ impl WorldWriter {
         self.send(opcode::CMSG_GROUP_DISBAND, &messages::group_disband())
     }
 
-    /// Ask a party/raid member's full live stats (`CMSG_REQUEST_PARTY_MEMBER_STATS`, a full guid).
-    /// Answered by `SMSG_PARTY_MEMBER_STATS_FULL` (or its offline-miss shape).
+    /// Ask a member's live stats, answered by `SMSG_PARTY_MEMBER_STATS_FULL`.
     pub fn request_party_member_stats(&mut self, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_REQUEST_PARTY_MEMBER_STATS,
@@ -81,8 +72,7 @@ impl WorldWriter {
         )
     }
 
-    /// Move a raid member to a different subgroup (`CMSG_GROUP_CHANGE_SUB_GROUP`, layout in
-    /// [`messages::group_change_sub_group`]) — raid-only drag-drop between subgroup columns.
+    /// Move a raid member to another subgroup (`CMSG_GROUP_CHANGE_SUB_GROUP`).
     pub fn group_change_sub_group(&mut self, name: &str, group_nr: u8) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_CHANGE_SUB_GROUP,
@@ -90,8 +80,7 @@ impl WorldWriter {
         )
     }
 
-    /// Swap two raid members' subgroups (`CMSG_GROUP_SWAP_SUB_GROUP`, layout in
-    /// [`messages::group_swap_sub_group`]).
+    /// Swap two raid members' subgroups (`CMSG_GROUP_SWAP_SUB_GROUP`).
     pub fn group_swap_sub_group(&mut self, name: &str, swap_with: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_SWAP_SUB_GROUP,
@@ -99,8 +88,7 @@ impl WorldWriter {
         )
     }
 
-    /// Convert the party into a raid (`CMSG_GROUP_RAID_CONVERT`, empty body) — leader-only,
-    /// one-way.
+    /// Convert the party into a raid (`CMSG_GROUP_RAID_CONVERT`, empty body); leader only, one-way.
     pub fn group_raid_convert(&mut self) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_RAID_CONVERT,
@@ -108,8 +96,7 @@ impl WorldWriter {
         )
     }
 
-    /// Grant or revoke raid-assistant on a member (`CMSG_GROUP_ASSISTANT_LEADER`, layout in
-    /// [`messages::group_assistant_leader`]).
+    /// Grant or revoke raid assistant (`CMSG_GROUP_ASSISTANT_LEADER`).
     pub fn group_assistant_leader(&mut self, guid: u64, grant: bool) -> Result<()> {
         self.send(
             opcode::CMSG_GROUP_ASSISTANT_LEADER,
@@ -117,14 +104,12 @@ impl WorldWriter {
         )
     }
 
-    /// Ping the minimap for the group (`MSG_MINIMAP_PING`, layout in [`messages::minimap_ping`]) —
-    /// the server stamps our guid and relays it to the rest of the group.
+    /// Ping the minimap (`MSG_MINIMAP_PING`); the server adds our guid and relays it to the group.
     pub fn minimap_ping(&mut self, x: f32, y: f32) -> Result<()> {
         self.send(opcode::MSG_MINIMAP_PING, &messages::minimap_ping(x, y))
     }
 
-    /// Set (or clear, `guid == 0`) one raid-target icon (`MSG_RAID_TARGET_UPDATE`, layout in
-    /// [`messages::raid_target_set`]).
+    /// Set one raid-target icon, or clear it with `guid == 0` (`MSG_RAID_TARGET_UPDATE`).
     pub fn raid_target_set(&mut self, icon: u8, guid: u64) -> Result<()> {
         self.send(
             opcode::MSG_RAID_TARGET_UPDATE,
@@ -132,8 +117,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ask the current raid-target icon set (`MSG_RAID_TARGET_UPDATE`, layout in
-    /// [`messages::raid_target_request`]). Answered by the server's full-list shape.
+    /// Ask the raid-target icons (`MSG_RAID_TARGET_UPDATE`), answered with the full list.
     pub fn raid_target_request(&mut self) -> Result<()> {
         self.send(
             opcode::MSG_RAID_TARGET_UPDATE,
@@ -141,13 +125,12 @@ impl WorldWriter {
         )
     }
 
-    /// Start a raid ready check (`MSG_RAID_READY_CHECK`, empty body) — leader-only.
+    /// Start a raid ready check (`MSG_RAID_READY_CHECK`, empty body); leader only.
     pub fn ready_check_start(&mut self) -> Result<()> {
         self.send(opcode::MSG_RAID_READY_CHECK, &messages::ready_check_start())
     }
 
-    /// Answer a raid ready check (`MSG_RAID_READY_CHECK`, layout in
-    /// [`messages::ready_check_answer`]).
+    /// Answer a raid ready check (`MSG_RAID_READY_CHECK`).
     pub fn ready_check_answer(&mut self, ready: bool) -> Result<()> {
         self.send(
             opcode::MSG_RAID_READY_CHECK,
@@ -155,8 +138,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for our saved-instance list (`CMSG_REQUEST_RAID_INFO`, empty body — decision 1549's
-    /// Raid Info panel). Answered by `SMSG_RAID_INSTANCE_INFO`.
+    /// Ask our saved-instance list, answered by `SMSG_RAID_INSTANCE_INFO`.
     pub fn request_raid_info(&mut self) -> Result<()> {
         self.send(
             opcode::CMSG_REQUEST_RAID_INFO,
diff --git a/crates/benilla-protocol/src/world/writer/guild.rs b/crates/benilla-protocol/src/world/writer/guild.rs
index d8d98ef1..9330b7ce 100644
--- a/crates/benilla-protocol/src/world/writer/guild.rs
+++ b/crates/benilla-protocol/src/world/writer/guild.rs
@@ -1,17 +1,6 @@
-//! The guild family's `WorldWriter` sends — the two cache asks, the invitation dance, the member
-//! verbs, and rank administration.
-//!
-//! Three shapes of the family are worth knowing before calling any of these:
-//!
-//! - **Almost nothing is acked individually.** Promote, demote, remove, the leader handover, the
-//!   MOTD, both notes and every rank verb answer with a fresh `SMSG_GUILD_ROSTER` (and, for the
-//!   rank verbs, an `SMSG_GUILD_QUERY_RESPONSE` too) — the server re-sends the whole snapshot
-//!   rather than a delta. A refusal instead comes back as `SMSG_GUILD_COMMAND_RESULT`. So the
-//!   caller's model updates when the roster lands, never optimistically at the send.
-//! - **Members are addressed by NAME here**, unlike the friend list's remove-by-guid: every verb
-//!   below that targets a player takes the character name, and the server normalises its case.
-//! - **Rank ids are 0-based with 0 = guild master**, and authority *decreases* as the id rises —
-//!   [`WorldWriter::guild_promote`] moves a member to `rank - 1`.
+//! The guild sends. Members are addressed by name, and rank 0 is the guild master. The server acks
+//! a member or rank change with a whole fresh `SMSG_GUILD_ROSTER` and refuses one with
+//! `SMSG_GUILD_COMMAND_RESULT`, so state updates when the roster lands, not at the send.
 
 use anyhow::Result;
 
@@ -20,67 +9,52 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask for a guild's public identity by id (`CMSG_GUILD_QUERY`) — name, rank names, tabard.
-    /// The ask-once cache fill behind every "which guild is that?": a roster row, a `/who` hit and
-    /// a guild chat line all reference a guild by id alone.
+    /// `CMSG_GUILD_QUERY`: a guild's name, rank names and tabard by id, for the ask-once cache.
     pub fn guild_query(&mut self, guild_id: u32) -> Result<()> {
         self.send(opcode::CMSG_GUILD_QUERY, &messages::guild_query(guild_id))
     }
 
-    /// Found a guild by name (`CMSG_GUILD_CREATE`). vmangos registers this opcode `STATUS_NEVER`:
-    /// on a 1.12 realm founding runs through the charter/petition flow instead, so this send is
-    /// here for completeness of the family and draws no reply.
+    /// `CMSG_GUILD_CREATE`: `STATUS_NEVER` in vmangos, so no reply; guilds are founded by charter.
     pub fn guild_create(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_GUILD_CREATE, &messages::guild_create(name))
     }
 
-    /// Invite a character into our guild by name (`CMSG_GUILD_INVITE`). They get an
-    /// `SMSG_GUILD_INVITE` popup; we get an `SMSG_GUILD_COMMAND_RESULT` only if it was refused
-    /// (already guilded, ignoring us, wrong faction, no permission).
+    /// `CMSG_GUILD_INVITE`: the invitee gets `SMSG_GUILD_INVITE`; we hear back only on a refusal.
     pub fn guild_invite(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_GUILD_INVITE, &messages::guild_invite(name))
     }
 
-    /// Accept the guild invitation we are holding (`CMSG_GUILD_ACCEPT`, empty body). Which
-    /// invitation is the server's pending state, not a field — so there is nothing to pass, and
-    /// nothing to get wrong except sending it when no invite is outstanding (a silent no-op).
+    /// `CMSG_GUILD_ACCEPT`, empty: takes the server's pending invite; a silent no-op without one.
     pub fn guild_accept(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GUILD_ACCEPT, &messages::guild_accept())
     }
 
-    /// Turn down the guild invitation we are holding (`CMSG_GUILD_DECLINE`, empty body). The
-    /// inviter is told by `SMSG_GUILD_DECLINE`; we hear nothing back.
+    /// `CMSG_GUILD_DECLINE`, empty: the inviter gets `SMSG_GUILD_DECLINE`; we hear nothing.
     pub fn guild_decline(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GUILD_DECLINE, &messages::guild_decline())
     }
 
-    /// Ask for our guild's founding date and member/account counts (`CMSG_GUILD_INFO`, empty
-    /// body), answered by `SMSG_GUILD_INFO`. A different ask from the roster, sharing no fields.
+    /// `CMSG_GUILD_INFO`, empty: answered by `SMSG_GUILD_INFO`, the founding date and counts.
     pub fn guild_info(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GUILD_INFO, &messages::guild_info())
     }
 
-    /// Ask for the whole guild roster (`CMSG_GUILD_ROSTER`, empty body). The server also pushes
-    /// `SMSG_GUILD_ROSTER` unasked after every change it makes, so this is a refresh — the guild
-    /// pane's opener — and never the only way the roster arrives.
+    /// `CMSG_GUILD_ROSTER`, empty: a refresh; the server also pushes the roster after every change.
     pub fn guild_roster(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GUILD_ROSTER, &messages::guild_roster())
     }
 
-    /// Promote a member one rank (`CMSG_GUILD_PROMOTE`): the server does `rank - 1`, *towards*
-    /// guild master. Answered by a fresh roster, or refused with `RANK_TOO_HIGH_S`/`PERMISSIONS`.
+    /// `CMSG_GUILD_PROMOTE`: the server moves the member to `rank - 1`, toward guild master.
     pub fn guild_promote(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_GUILD_PROMOTE, &messages::guild_promote(name))
     }
 
-    /// Demote a member one rank (`CMSG_GUILD_DEMOTE`): `rank + 1`, away from guild master.
+    /// `CMSG_GUILD_DEMOTE`: `rank + 1`, away from guild master.
     pub fn guild_demote(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_GUILD_DEMOTE, &messages::guild_demote(name))
     }
 
-    /// Leave our guild (`CMSG_GUILD_LEAVE`, empty body). Refused with
-    /// `(QUIT, LEADER_LEAVE)` while we are the guild master and anyone else remains — hand over
-    /// with [`Self::guild_leader`] first, or [`Self::guild_disband`].
+    /// `CMSG_GUILD_LEAVE`, empty: refused (`LEADER_LEAVE`) for a guild master while others remain.
     pub fn guild_leave(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GUILD_LEAVE, &messages::guild_leave())
     }
@@ -90,32 +64,24 @@ impl WorldWriter {
         self.send(opcode::CMSG_GUILD_REMOVE, &messages::guild_remove(name))
     }
 
-    /// Disband the guild (`CMSG_GUILD_DISBAND`, empty body). Guild master only, and irreversible —
-    /// every member gets a `GE_DISBANDED` event.
+    /// `CMSG_GUILD_DISBAND`, empty: guild master only; every member gets `GE_DISBANDED`.
     pub fn guild_disband(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GUILD_DISBAND, &messages::guild_disband())
     }
 
-    /// Hand the guild to another member (`CMSG_GUILD_LEADER`). Guild master only; both names ride
-    /// back to everyone as a `GE_LEADER_CHANGED` event.
+    /// `CMSG_GUILD_LEADER`: guild master only; everyone gets both names in `GE_LEADER_CHANGED`.
     pub fn guild_leader(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_GUILD_LEADER, &messages::guild_leader(name))
     }
 
-    /// Set the message of the day (`CMSG_GUILD_MOTD`). Passing `""` clears it — see
-    /// [`messages::guild_motd`] for why we send the one-byte empty cstring rather than an empty
-    /// body, which the server also accepts.
+    /// `CMSG_GUILD_MOTD`: `""` clears the message of the day.
     pub fn guild_motd(&mut self, motd: &str) -> Result<()> {
         self.send(opcode::CMSG_GUILD_MOTD, &messages::guild_motd(motd))
     }
 
-    /// Rewrite one rank's name **and** rights in a single packet (`CMSG_GUILD_RANK`).
-    ///
-    /// There is no partial form: a caller changing only the name must still send the rank's
-    /// current rights, and vice versa. Guild master only; `rights` is ignored and replaced with
-    /// [`messages::guild_rank_right::ALL`] for rank 0; and a `name` over
-    /// [`messages::GUILD_RANK_MAX_LENGTH`] characters gets the session **kicked** by vmangos's
-    /// anticheat rather than refused, so the caller caps it.
+    /// `CMSG_GUILD_RANK`: a rank's name and rights together, with no partial form. Guild master
+    /// only; rank 0 always gets all rights, and a name over [`messages::GUILD_RANK_MAX_LENGTH`]
+    /// gets the session kicked by vmangos, so the caller caps it.
     pub fn guild_rank(&mut self, rank_id: u32, rights: u32, name: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GUILD_RANK,
@@ -123,22 +89,18 @@ impl WorldWriter {
         )
     }
 
-    /// Append a rank at the bottom of the ladder (`CMSG_GUILD_ADD_RANK`). It starts with guild
-    /// chat listen + speak and nothing else. Silently ignored once the guild already has
-    /// [`messages::GUILD_RANKS_MAX_COUNT`] ranks — the reference UI hides the button there.
+    /// `CMSG_GUILD_ADD_RANK`: a new bottom rank with only guild chat rights; ignored at
+    /// [`messages::GUILD_RANKS_MAX_COUNT`] ranks.
     pub fn guild_add_rank(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_GUILD_ADD_RANK, &messages::guild_add_rank(name))
     }
 
-    /// Delete the **lowest** rank (`CMSG_GUILD_DEL_RANK`, empty body). There is no rank id on the
-    /// wire: it is always the last one, which is why the reference UI only ever offers to remove
-    /// the bottom row. Refused with `RANK_IN_USE` while a member still holds it.
+    /// `CMSG_GUILD_DEL_RANK`, empty: always the lowest rank; refused with `RANK_IN_USE` while held.
     pub fn guild_del_rank(&mut self) -> Result<()> {
         self.send(opcode::CMSG_GUILD_DEL_RANK, &messages::guild_del_rank())
     }
 
-    /// Set a member's public note (`CMSG_GUILD_SET_PUBLIC_NOTE`); needs
-    /// [`messages::guild_rank_right::EDIT_PUBLIC_NOTE`].
+    /// `CMSG_GUILD_SET_PUBLIC_NOTE`: needs [`messages::guild_rank_right::EDIT_PUBLIC_NOTE`].
     pub fn guild_set_public_note(&mut self, name: &str, note: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GUILD_SET_PUBLIC_NOTE,
@@ -146,9 +108,7 @@ impl WorldWriter {
         )
     }
 
-    /// Set a member's officer note (`CMSG_GUILD_SET_OFFICER_NOTE`); needs
-    /// [`messages::guild_rank_right::EDIT_OFFICER_NOTE`]. Note that *seeing* officer notes is a
-    /// separate right — a roster whose officer notes are all empty may mean we cannot view them.
+    /// `CMSG_GUILD_SET_OFFICER_NOTE`: needs [`messages::guild_rank_right::EDIT_OFFICER_NOTE`].
     pub fn guild_set_officer_note(&mut self, name: &str, note: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GUILD_SET_OFFICER_NOTE,
@@ -156,8 +116,7 @@ impl WorldWriter {
         )
     }
 
-    /// Set the guild information text (`CMSG_GUILD_INFO_TEXT`) — the long free-text pane, not the
-    /// MOTD and not `SMSG_GUILD_INFO`'s counts. It rides back on the roster as its `info` field.
+    /// `CMSG_GUILD_INFO_TEXT`: the free-text info pane; it comes back as the roster's `info`.
     pub fn guild_info_text(&mut self, text: &str) -> Result<()> {
         self.send(
             opcode::CMSG_GUILD_INFO_TEXT,
diff --git a/crates/benilla-protocol/src/world/writer/instance.rs b/crates/benilla-protocol/src/world/writer/instance.rs
index 3dc42b02..9afa140c 100644
--- a/crates/benilla-protocol/src/world/writer/instance.rs
+++ b/crates/benilla-protocol/src/world/writer/instance.rs
@@ -1,7 +1,4 @@
-//! The instance/raid lockout family's one outbound verb (decision 1748).
-//!
-//! Everything else in the family is the server telling us something; the only thing the player can
-//! *do* is press "Reset all instances" on their own portrait, which is this.
+//! The instance lockout family's one send: "Reset all instances" from the player's portrait.
 
 use anyhow::Result;
 
@@ -10,20 +7,9 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Reset every dungeon we are the owner of (`CMSG_RESET_INSTANCES`, empty body) — the
-    /// `CONFIRM_RESET_INSTANCES` dialog's Yes.
-    ///
-    /// The answer is per instance, not one verdict: the server walks every bind and sends an
-    /// `SMSG_INSTANCE_RESET` for each map that reset, so a mixed outcome is normal — and **no
-    /// answer at all is the ordinary case**, because a character with nothing resettable gets
-    /// nothing back. Refusals only exist on the group path: vmangos `Group::ResetInstances` sends
-    /// `INSTANCERESET_FAIL_OFFLINE` (2187) and `INSTANCERESET_FAIL_GENERAL` (2205), while the solo
-    /// path `Player::ResetInstances` sends successes only. `INSTANCERESET_FAIL_ZONING` is a code
-    /// the client can render and this server never sends.
-    ///
-    /// Both sides also refuse a RAID here — `entry->mapType == MAP_RAID` is skipped outright —
-    /// which is the server's face of the same party-dungeon rule `CanShowResetInstances()` gates
-    /// the menu row on.
+    /// `CMSG_RESET_INSTANCES`, empty: the `CONFIRM_RESET_INSTANCES` dialog's Yes. The server sends
+    /// one `SMSG_INSTANCE_RESET` per map it reset and nothing when none could; raids are skipped,
+    /// and only the group path refuses (vmangos `Group::ResetInstances`).
     pub fn reset_instances(&mut self) -> Result<()> {
         self.send(opcode::CMSG_RESET_INSTANCES, &messages::reset_instances())
     }
diff --git a/crates/benilla-protocol/src/world/writer/items.rs b/crates/benilla-protocol/src/world/writer/items.rs
index e9fccceb..eebf5c5d 100644
--- a/crates/benilla-protocol/src/world/writer/items.rs
+++ b/crates/benilla-protocol/src/world/writer/items.rs
@@ -1,13 +1,5 @@
-//! The bag/equipment family's `WorldWriter` sends — the item-template ask, use, auto-equip, the
-//! ammo fork, the three move/swap/split shapes, and destroy. Bodies in
-//! [`crate::messages::items`], whose scope this mirrors. Split out of `writer/mod.rs`
-//! (decision 0636).
-//!
-//! Three distinct swap opcodes exist because the addressable space differs, not the intent:
-//! `CMSG_SWAP_INV_ITEM` only ever names two slots in the player's own grid, while `CMSG_SWAP_ITEM`
-//! and `CMSG_SPLIT_ITEM` take a `(bag, slot)` pair on each side so either endpoint may be an
-//! equipped bag (decision 0216 §6). Every one of them refuses the same way —
-//! `SMSG_INVENTORY_CHANGE_FAILURE` — and succeeds silently, as values deltas on both slots.
+//! The bag and equipment sends. A move succeeds silently, as values deltas on both slots, and is
+//! refused with `SMSG_INVENTORY_CHANGE_FAILURE`.
 
 use anyhow::Result;
 
@@ -16,9 +8,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask an item template's display head (`CMSG_ITEM_QUERY_SINGLE`: entry + item guid, 0 for
-    /// template-only asks). Answered by `SMSG_ITEM_QUERY_SINGLE_RESPONSE` (an `ItemTemplate`
-    /// event) — the T2 container groundwork.
+    /// `CMSG_ITEM_QUERY_SINGLE`: an item template by entry; `guid` is 0 for a template-only ask.
     pub fn item_query(&mut self, entry: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_ITEM_QUERY_SINGLE,
@@ -26,10 +16,8 @@ impl WorldWriter {
         )
     }
 
-    /// Use an item by bag position (`CMSG_USE_ITEM`, layout in [`messages::use_item`]) — eat the
-    /// food, drink the potion, hearthstone home. `go_target` aims the use at a GameObject, which is
-    /// how a KEY opens a locked door (decision 0769). The server answers with the effect (values
-    /// deltas, a stack decrement/destroy) or `SMSG_CAST_RESULT` on refusal.
+    /// `CMSG_USE_ITEM`: use the item at a bag position; a GameObject `target` is how a key opens a
+    /// locked door. Refused with `SMSG_CAST_RESULT`.
     pub fn use_item(
         &mut self,
         bag_index: u8,
@@ -43,11 +31,8 @@ impl WorldWriter {
         )
     }
 
-    /// Open an item by bag position (`CMSG_OPEN_ITEM`, layout in [`messages::open_item`]) — crack
-    /// the clam, empty the picked lockbox, unwrap the gift. The right-click fork for an
-    /// `crate::ItemInfo::openable` item; the server answers with `SMSG_LOOT_RESPONSE` on the
-    /// item's **own** guid (so the loot window opens over a thing in the bag), or an equip error
-    /// on a refusal (still locked, dead, flying).
+    /// `CMSG_OPEN_ITEM`: open a clam, lockbox or gift; the loot window comes back on the item's
+    /// own guid.
     pub fn open_item(&mut self, bag_index: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_OPEN_ITEM,
@@ -55,10 +40,8 @@ impl WorldWriter {
         )
     }
 
-    /// Wrap an item in gift paper (`CMSG_WRAP_ITEM`, layout in [`messages::wrap_item`]) — the
-    /// completion of the local wrap cursor a `ITEM_FLAG_WRAPPER` item's right-click arms. The
-    /// paper's `(bag, slot)` leads, the target's follows. Success is silent (field updates on the
-    /// target, one paper destroyed); every refusal comes back as `SMSG_INVENTORY_CHANGE_FAILURE`.
+    /// `CMSG_WRAP_ITEM`: wrap an item in the `ITEM_FLAG_WRAPPER` paper; success is silent and
+    /// consumes one paper.
     pub fn wrap_item(
         &mut self,
         gift_bag: u8,
@@ -72,9 +55,7 @@ impl WorldWriter {
         )
     }
 
-    /// Equip a bag item (`CMSG_AUTOEQUIP_ITEM`, layout in [`messages::auto_equip_item`]) — the
-    /// server picks the destination slot. Success arrives as inventory-slot values deltas (and the
-    /// visible-item change everyone renders); refusal as `SMSG_INVENTORY_CHANGE_FAILURE`.
+    /// `CMSG_AUTOEQUIP_ITEM`: equip a bag item; the server picks the slot.
     pub fn auto_equip_item(&mut self, bag_index: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOEQUIP_ITEM,
@@ -82,19 +63,13 @@ impl WorldWriter {
         )
     }
 
-    /// Load ammo into the ammo slot (`CMSG_SET_AMMO`, layout in [`messages::set_ammo`]) — the
-    /// client's own auto-equip fork for ammo-class items (wow-re `cursor-dragdrop-slots.md`).
-    /// Addressed by item *entry*, not a bag slot; the stack stays in the bag and `PLAYER_AMMO_ID`
-    /// starts referencing it. A wrong/absent ranged weapon refuses via
-    /// `SMSG_INVENTORY_CHANGE_FAILURE`. Decision 0526.
+    /// `CMSG_SET_AMMO`: what the 1.12 client sends to auto-equip ammo. It names an item entry, not
+    /// a slot; the stack stays in the bag and `PLAYER_AMMO_ID` points at it.
     pub fn set_ammo(&mut self, entry: u32) -> Result<()> {
         self.send(opcode::CMSG_SET_AMMO, &messages::set_ammo(entry))
     }
 
-    /// Swap two of the player's own inventory slots (`CMSG_SWAP_INV_ITEM`, layout in
-    /// [`messages::swap_inv_item`]) — the wire for a backpack-internal pick/place/swap (both slots
-    /// are `INVENTORY_SLOT_ITEM_START`+i). An empty destination is a move; the server settles both
-    /// slots with values deltas, or refuses via `SMSG_INVENTORY_CHANGE_FAILURE`.
+    /// `CMSG_SWAP_INV_ITEM`: two slots of the player's own grid; an empty destination is a move.
     pub fn swap_inv_item(&mut self, src_slot: u8, dst_slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_SWAP_INV_ITEM,
@@ -102,11 +77,7 @@ impl WorldWriter {
         )
     }
 
-    /// The general bag↔bag move (`CMSG_SWAP_ITEM`, layout in [`messages::swap_item`]): either
-    /// endpoint may be an equipped bag (unlike [`Self::swap_inv_item`], which only ever addresses
-    /// the player's own grid) — the wire for a whole-space bag-window pick/place/swap (decision
-    /// 0216 §6, slice 2). An empty destination is a move, same as `swap_inv_item`; refusal answers
-    /// `SMSG_INVENTORY_CHANGE_FAILURE`.
+    /// `CMSG_SWAP_ITEM`: a `(bag, slot)` on each side, so either end may be in an equipped bag.
     pub fn swap_item(
         &mut self,
         dst_bag: u8,
@@ -120,11 +91,8 @@ impl WorldWriter {
         )
     }
 
-    /// Auto-store an item into a bag (`CMSG_AUTOSTORE_BAG_ITEM`, layout in
-    /// [`messages::auto_store_bag_item`]): take `(src_bag, src_slot)` and put it anywhere inside
-    /// `dst_bag` — **the client names no destination slot; the server picks it**. The wire for
-    /// `PutItemInBag`'s auto-store leg and the whole of `PutItemInBackpack` (wow-re
-    /// `bag-verbs-law.md`). Refusal answers `SMSG_INVENTORY_CHANGE_FAILURE`.
+    /// `CMSG_AUTOSTORE_BAG_ITEM`: into `dst_bag` at a slot the server picks; the wire of
+    /// `PutItemInBackpack` and of `PutItemInBag`'s auto-store.
     pub fn auto_store_bag_item(&mut self, src_bag: u8, src_slot: u8, dst_bag: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOSTORE_BAG_ITEM,
@@ -132,10 +100,7 @@ impl WorldWriter {
         )
     }
 
-    /// Split a stack (`CMSG_SPLIT_ITEM`, layout in [`messages::split_item`]): carry `count` off
-    /// `(src_bag, src_slot)` onto `(dst_bag, dst_slot)` — either endpoint may be an equipped bag
-    /// (unlike [`Self::swap_inv_item`]). Success settles both slots via values deltas; refusal
-    /// answers `SMSG_INVENTORY_CHANGE_FAILURE`.
+    /// `CMSG_SPLIT_ITEM`: move `count` off a stack; either end may be in an equipped bag.
     pub fn split_item(
         &mut self,
         src_bag: u8,
@@ -150,9 +115,7 @@ impl WorldWriter {
         )
     }
 
-    /// Destroy a bag item (`CMSG_DESTROYITEM`, layout in [`messages::destroy_item`]): `count` 0 =
-    /// the whole stack. The delete-confirm popup's `OnAccept` (decision 0216 §3) — no dedicated
-    /// answer packet; the item's disappearance is the ordinary field-update stream.
+    /// `CMSG_DESTROYITEM`: `count` 0 destroys the whole stack; there is no reply packet.
     pub fn destroy_item(&mut self, bag: u8, slot: u8, count: u8) -> Result<()> {
         self.send(
             opcode::CMSG_DESTROYITEM,
diff --git a/crates/benilla-protocol/src/world/writer/lifecycle.rs b/crates/benilla-protocol/src/world/writer/lifecycle.rs
index 8db74493..94d38a2f 100644
--- a/crates/benilla-protocol/src/world/writer/lifecycle.rs
+++ b/crates/benilla-protocol/src/world/writer/lifecycle.rs
@@ -1,11 +1,5 @@
-//! The session-lifecycle `WorldWriter` sends — the three the client makes about *being logged in*
-//! rather than about anything in the world: the keepalive, the leave-the-world request, and the
-//! cinematic ack that gates the world stream on entering it. Split out of `writer/mod.rs`
-//! (decision 0636).
-//!
-//! All three are effectively bodyless (`ping` carries only its two counters), and all three are
-//! **cadence/obligation** sends rather than player intents: skip the ping and the socket dies,
-//! skip the cinematic ack and the world around the body despawns.
+//! The sends about being logged in rather than about the world: the keepalive, logout, the server
+//! clock and the cinematic acks.
 
 use anyhow::Result;
 
@@ -14,70 +8,45 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Send the ~30 s keepalive (`CMSG_PING`): `sequence` is the ++counter the server echoes back
-    /// as `SMSG_PONG`, `last_rtt_ms` the previous round-trip measurement (the real client's
-    /// lastRtt; the server stores it as our reported latency). Cadence discipline is the caller's:
-    /// vmangos kicks a socket whose pings repeat faster than 27 s apart (`_HandlePing`'s
-    /// overspeed count), so this is a timer send, never a retry.
+    /// `CMSG_PING`, every ~30 s: the server echoes `sequence` in `SMSG_PONG` and stores
+    /// `last_rtt_ms` as our latency. vmangos kicks pings under 27 s apart, so never retry one.
     pub fn ping(&mut self, sequence: u32, last_rtt_ms: u32) -> Result<()> {
         self.send(opcode::CMSG_PING, &messages::ping(sequence, last_rtt_ms))
     }
 
-    /// Ask to leave the world back to character select (`CMSG_LOGOUT_REQUEST`, empty body). The
-    /// server answers `SMSG_LOGOUT_RESPONSE` (a refusal while in combat) and, once the logout
-    /// completes (instant for a resting/GM character), `SMSG_LOGOUT_COMPLETE` — which the stream
-    /// surfaces as [`SessionEvent::LoggedOut`](crate::SessionEvent::LoggedOut).
+    /// `CMSG_LOGOUT_REQUEST`, empty: answered by `SMSG_LOGOUT_RESPONSE`, then
+    /// `SMSG_LOGOUT_COMPLETE` when the logout ends (at once for a resting or GM character).
     pub fn logout_request(&mut self) -> Result<()> {
         self.send(opcode::CMSG_LOGOUT_REQUEST, &[])
     }
 
-    /// The FORCED logout (`CMSG_PLAYER_LOGOUT`, empty) — `ForceLogout()`'s packet, the same
-    /// dispatcher as [`Self::logout_request`] with the pending-logout latch bypassed
-    /// (decision 1963).
+    /// `CMSG_PLAYER_LOGOUT`, empty: the forced logout the 1.12 client's `ForceLogout()` sends.
     pub fn player_logout(&mut self) -> Result<()> {
         self.send(opcode::CMSG_PLAYER_LOGOUT, &[])
     }
 
-    /// Call off a pending logout (`CMSG_LOGOUT_CANCEL`, empty body) — the CAMP/QUIT dialog's Cancel
-    /// (decision 0674). Only meaningful while the server's 20-second timer is running (a non-instant
-    /// [`logout_request`](Self::logout_request)); the server drops the timer, unroots the character
+    /// `CMSG_LOGOUT_CANCEL`, empty: the server stops its 20 s logout timer, unroots the character
     /// and answers `SMSG_LOGOUT_CANCEL_ACK`.
     pub fn logout_cancel(&mut self) -> Result<()> {
         self.send(opcode::CMSG_LOGOUT_CANCEL, &[])
     }
 
-    /// Ask the server for its wall clock (`CMSG_QUERY_TIME`, empty body); answered with
-    /// `SMSG_QUERY_TIME_RESPONSE`, one `u32` of unix-epoch seconds.
-    ///
-    /// A cadence/obligation send like [`ping`](Self::ping), not a player intent: the server writes
-    /// *absolute* stamps in its own epoch into descriptor fields — a timed quest's deadline is
-    /// `time(nullptr) + limitTime` — and nothing on the wire ever restates them as a duration. So
-    /// every countdown the client draws is only as right as its last sample of this clock; benilla
-    /// takes one on entering the world (decision 1150).
+    /// `CMSG_QUERY_TIME`, empty: answered with the server's unix time as one `u32`. Descriptor
+    /// deadlines, such as a timed quest's, are absolute server time, so countdowns need this clock.
     pub fn query_time(&mut self) -> Result<()> {
         self.send(opcode::CMSG_QUERY_TIME, &messages::query_time())
     }
 
-    /// Acknowledge a triggered cinematic as finished (`CMSG_COMPLETE_CINEMATIC`, empty body) — the
-    /// packet the real client sends when the cinematic ends or the player ESCs out. Must answer
-    /// every `SMSG_TRIGGER_CINEMATIC` ([`SessionEvent::CinematicTriggered`]
-    /// (crate::SessionEvent::CinematicTriggered)): while one runs unacked, vmangos anchors object
-    /// visibility to the flying cinematic camera and the world around the body despawns.
+    /// `CMSG_COMPLETE_CINEMATIC`, empty: sent when a cinematic ends or is escaped, and owed for
+    /// every `SMSG_TRIGGER_CINEMATIC`; until then vmangos anchors visibility to the cinematic
+    /// camera and the world around the body despawns.
     pub fn complete_cinematic(&mut self) -> Result<()> {
         self.send(opcode::CMSG_COMPLETE_CINEMATIC, &[])
     }
 
-    /// Announce the cinematic shot being armed (`CMSG_NEXT_CINEMATIC_CAMERA`, empty body) — see
-    /// the opcode's own note. Sent once per shot, **including the first**, so a stock single-camera
-    /// race intro sends exactly one; the run still ends with exactly one
-    /// [`complete_cinematic`](Self::complete_cinematic).
-    ///
-    /// The reference's send is inside the shot arm `0x48edf0` (`0x48ef11 push 0xfb` → the
-    /// `0x418190` builder → `0x5ab630` flush), immediately before that shot's narration starts —
-    /// *not* inside the shot advance `0x48efe0`, where benilla first placed it. That misreading
-    /// mattered on the shipped path rather than only on a private server's: every 1.12
-    /// `CinematicSequences` row carries exactly one camera, so "between cameras" meant benilla
-    /// sent this packet **never**.
+    /// `CMSG_NEXT_CINEMATIC_CAMERA`, empty: sent as each shot is armed, the first included, just
+    /// before its narration (reference: shot arm `0x48edf0`, not the advance `0x48efe0`). Every
+    /// 1.12 `CinematicSequences` row has one camera, so a race intro sends exactly one.
     pub fn next_cinematic_camera(&mut self) -> Result<()> {
         self.send(opcode::CMSG_NEXT_CINEMATIC_CAMERA, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/loot.rs b/crates/benilla-protocol/src/world/writer/loot.rs
index 771c09f6..eacb9ac8 100644
--- a/crates/benilla-protocol/src/world/writer/loot.rs
+++ b/crates/benilla-protocol/src/world/writer/loot.rs
@@ -1,11 +1,4 @@
-//! The loot window's `WorldWriter` sends — open, take a row, take the coin pile, close, and vote
-//! in a group roll. Bodies in [`crate::messages::loot`], whose scope this mirrors. Split out of
-//! `writer/mod.rs` (decision 0636).
-//!
-//! Two addressing quirks worth keeping together: [`WorldWriter::loot_release`] passes a guid the
-//! server *ignores* (it releases whatever loot guid it has stored for us), and
-//! [`WorldWriter::loot_roll`] is addressed by the `(looted_target, item_slot)` pair the roll was
-//! opened with — never by the client-internal `rollID` the reference UI keys its frames on.
+//! The loot window sends: open, take, coin, close, roll, and the master looter's give.
 
 use anyhow::Result;
 
@@ -14,18 +7,12 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Open a loot window (`CMSG_LOOT`, layout in [`messages::loot`]) — a full guid naming the
-    /// corpse/creature/player to loot. Answered by `SMSG_LOOT_RESPONSE` (a `LootResponse` event
-    /// on success, `LootError` on refusal).
+    /// `CMSG_LOOT`: open the loot of a corpse, creature or player (`SMSG_LOOT_RESPONSE`).
     pub fn loot(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_LOOT, &messages::loot(guid))
     }
 
-    /// Take one loot-window row (`CMSG_AUTOSTORE_LOOT_ITEM`, layout in
-    /// [`messages::autostore_loot_item`]): `loot_slot` is the wire's 0-based row index. The server
-    /// auto-places the item into the first free bag slot; success arrives via the normal
-    /// item-create/values path plus `SMSG_LOOT_REMOVED` clearing the row and
-    /// `SMSG_ITEM_PUSH_RESULT` naming what landed.
+    /// `CMSG_AUTOSTORE_LOOT_ITEM`: take the 0-based row `loot_slot` into the first free bag slot.
     pub fn autostore_loot_item(&mut self, loot_slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_AUTOSTORE_LOOT_ITEM,
@@ -33,25 +20,19 @@ impl WorldWriter {
         )
     }
 
-    /// Take the loot's coin pile (`CMSG_LOOT_MONEY`, empty body). Answered by
-    /// `SMSG_LOOT_MONEY_NOTIFY` (our share) then `SMSG_LOOT_CLEAR_MONEY` (the coin line clears for
-    /// every looter) plus the coinage rising via `UPDATE_OBJECT`.
+    /// `CMSG_LOOT_MONEY`, empty: answered by `SMSG_LOOT_MONEY_NOTIFY` with our share, then
+    /// `SMSG_LOOT_CLEAR_MONEY` to every looter.
     pub fn loot_money(&mut self) -> Result<()> {
         self.send(opcode::CMSG_LOOT_MONEY, &messages::loot_money())
     }
 
-    /// Close the loot window (`CMSG_LOOT_RELEASE`, layout in [`messages::loot_release`]); the
-    /// server ignores `guid` and releases whatever loot guid it has stored for us instead.
-    /// Answered by `SMSG_LOOT_RELEASE_RESPONSE` (a `LootReleaseResponse` event).
+    /// `CMSG_LOOT_RELEASE`: the server ignores `guid` and releases the loot it has stored for us.
     pub fn loot_release(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_LOOT_RELEASE, &messages::loot_release(guid))
     }
 
-    /// Cast a group-loot vote (`CMSG_LOOT_ROLL`, layout in [`messages::loot_roll`]) — the roll is
-    /// addressed by the `(looted_target, item_slot)` pair `SMSG_LOOT_START_ROLL` opened it with,
-    /// never by the client-internal `rollID`. `roll_type` is a [`messages::roll_vote`] value; the
-    /// server drops anything `>= 3` without a reply. Answered by an `SMSG_LOOT_ROLL` broadcast of
-    /// our vote, then the resolution (`SMSG_LOOT_ROLL_WON` / `SMSG_LOOT_ALL_PASSED`).
+    /// `CMSG_LOOT_ROLL`: addressed by the `(looted_target, item_slot)` of `SMSG_LOOT_START_ROLL`,
+    /// not the UI's `rollID`; a [`messages::roll_vote`] of 3 or more is dropped unanswered.
     pub fn loot_roll(&mut self, looted_target: u64, item_slot: u32, roll_type: u8) -> Result<()> {
         self.send(
             opcode::CMSG_LOOT_ROLL,
@@ -59,15 +40,8 @@ impl WorldWriter {
         )
     }
 
-    /// Hand one loot-window row to a group member (`CMSG_LOOT_MASTER_GIVE`, layout in
-    /// [`messages::loot_master_give`]) — the master looter's replacement for taking the row
-    /// themselves. `loot_guid` is the open loot source and `slot` the wire's 0-based row index,
-    /// the same one [`WorldWriter::autostore_loot_item`] would carry.
-    ///
-    /// Success looks like anyone else's loot from here: `SMSG_LOOT_REMOVED` clears the row for
-    /// every looter, and the *recipient* (not us) gets the item-create traffic. A refusal comes
-    /// back on `SMSG_LOOT_RESPONSE`'s error shape carrying a `MASTER_*`
-    /// [`messages::loot_error`] code.
+    /// `CMSG_LOOT_MASTER_GIVE`: the master looter hands 0-based row `slot` of `loot_guid` to a
+    /// member; a refusal is an `SMSG_LOOT_RESPONSE` error with a `MASTER_*` loot error code.
     pub fn loot_master_give(&mut self, loot_guid: u64, slot: u8, player_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_LOOT_MASTER_GIVE,
diff --git a/crates/benilla-protocol/src/world/writer/mail.rs b/crates/benilla-protocol/src/world/writer/mail.rs
index 3d10954e..1d2ef857 100644
--- a/crates/benilla-protocol/src/world/writer/mail.rs
+++ b/crates/benilla-protocol/src/world/writer/mail.rs
@@ -1,8 +1,4 @@
-//! The mail arc's `WorldWriter` sends (decision 0544 P0): the inbox open/refresh, send, take-money/
-//! take-item/mark-read/return/delete/copy-letter verbs, the letter-body ask-once fetch, and the login
-//! unread-mail query. Bodies in [`crate::messages`]'s `mail` builders (layout VERIFIED against
-//! vmangos `Handlers/MailHandler.cpp` + `Server/Packets/Mail.cpp`). Split out of `writer/mod.rs`
-//! the same way `channel`/`group` are — one clearly separable concern among the writer's domains.
+//! The mailbox sends. A verb on one mail is acked by `SMSG_SEND_MAIL_RESULT` carrying its action.
 
 use anyhow::Result;
 
@@ -11,9 +7,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask the mailbox's inbox page (`CMSG_GET_MAIL_LIST`, layout in [`messages::get_mail_list`]) —
-    /// the window's open verb and its refresh: one mailbox guid. Answered by
-    /// `SMSG_MAIL_LIST_RESULT` (a `MailList` event).
+    /// `CMSG_GET_MAIL_LIST`: opens and refreshes the inbox; answered by `SMSG_MAIL_LIST_RESULT`.
     pub fn get_mail_list(&mut self, mailbox: u64) -> Result<()> {
         self.send(
             opcode::CMSG_GET_MAIL_LIST,
@@ -21,11 +15,8 @@ impl WorldWriter {
         )
     }
 
-    /// Send a mail (`CMSG_SEND_MAIL`, layout in [`messages::send_mail`]) — the Send tab:
-    /// recipient/subject/body, an optional item attachment (`item_guid == 0` = none), money, and
-    /// COD. `stationery`/`package` ride the wire but are discarded server-side (player mail is
-    /// always stored `MAIL_STATIONERY_DEFAULT`). Answered by `SMSG_SEND_MAIL_RESULT` (a
-    /// `SendMailResult` event).
+    /// `CMSG_SEND_MAIL`: `item_guid` 0 attaches nothing. The server discards `stationery` and
+    /// `package`, storing player mail as `MAIL_STATIONERY_DEFAULT`.
     pub fn send_mail(
         &mut self,
         mailbox: u64,
@@ -46,9 +37,7 @@ impl WorldWriter {
         )
     }
 
-    /// Take a mail's attached money (`CMSG_MAIL_TAKE_MONEY`, layout in
-    /// [`messages::mail_take_money`]). Answered by `SMSG_SEND_MAIL_RESULT`
-    /// (action [`messages::mail_action::MONEY_TAKEN`]).
+    /// `CMSG_MAIL_TAKE_MONEY`: acked with [`messages::mail_action::MONEY_TAKEN`].
     pub fn mail_take_money(&mut self, mailbox: u64, mail_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_MAIL_TAKE_MONEY,
@@ -56,9 +45,7 @@ impl WorldWriter {
         )
     }
 
-    /// Take a mail's attached item (`CMSG_MAIL_TAKE_ITEM`, layout in
-    /// [`messages::mail_take_item`]). Answered by `SMSG_SEND_MAIL_RESULT`
-    /// (action [`messages::mail_action::ITEM_TAKEN`]).
+    /// `CMSG_MAIL_TAKE_ITEM`: acked with [`messages::mail_action::ITEM_TAKEN`].
     pub fn mail_take_item(&mut self, mailbox: u64, mail_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_MAIL_TAKE_ITEM,
@@ -66,9 +53,8 @@ impl WorldWriter {
         )
     }
 
-    /// Mark a mail read (`CMSG_MAIL_MARK_AS_READ`, layout in [`messages::mail_mark_as_read`]) —
-    /// sent when a letter opens. **No response packet**: the app flips the local `checked` READ
-    /// bit and repaints.
+    /// `CMSG_MAIL_MARK_AS_READ`: sent when a letter opens. There is no reply, so the caller sets
+    /// the read bit itself.
     pub fn mail_mark_as_read(&mut self, mailbox: u64, mail_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_MAIL_MARK_AS_READ,
@@ -76,9 +62,7 @@ impl WorldWriter {
         )
     }
 
-    /// Return a mail to its sender (`CMSG_MAIL_RETURN_TO_SENDER`, layout in
-    /// [`messages::mail_return_to_sender`]). Answered by `SMSG_SEND_MAIL_RESULT`
-    /// (action [`messages::mail_action::RETURNED`]).
+    /// `CMSG_MAIL_RETURN_TO_SENDER`: acked with [`messages::mail_action::RETURNED`].
     pub fn mail_return_to_sender(&mut self, mailbox: u64, mail_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_MAIL_RETURN_TO_SENDER,
@@ -86,9 +70,7 @@ impl WorldWriter {
         )
     }
 
-    /// Delete a mail (`CMSG_MAIL_DELETE`, layout in [`messages::mail_delete`]) — the taken-letter
-    /// close and the explicit Delete button alike. Answered by `SMSG_SEND_MAIL_RESULT`
-    /// (action [`messages::mail_action::DELETED`]).
+    /// `CMSG_MAIL_DELETE`: acked with [`messages::mail_action::DELETED`].
     pub fn mail_delete(&mut self, mailbox: u64, mail_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_MAIL_DELETE,
@@ -96,9 +78,8 @@ impl WorldWriter {
         )
     }
 
-    /// Make a permanent copy of a letter's body (`CMSG_MAIL_CREATE_TEXT_ITEM`, layout in
-    /// [`messages::mail_create_text_item`]) — the open letter's "Take Attachments" letter button.
-    /// Answered by `SMSG_SEND_MAIL_RESULT` (action [`messages::mail_action::MADE_PERMANENT`]).
+    /// `CMSG_MAIL_CREATE_TEXT_ITEM`: a permanent copy of the letter; acked with
+    /// [`messages::mail_action::MADE_PERMANENT`].
     pub fn mail_create_text_item(&mut self, mailbox: u64, mail_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_MAIL_CREATE_TEXT_ITEM,
@@ -106,9 +87,7 @@ impl WorldWriter {
         )
     }
 
-    /// Fetch a letter's body text (`CMSG_ITEM_TEXT_QUERY`, layout in [`messages::item_text_query`])
-    /// — sent once per mail whose `item_text_id != 0` (ask-once cacheable). Answered by
-    /// `SMSG_ITEM_TEXT_QUERY_RESPONSE` (a `MailItemText` event).
+    /// `CMSG_ITEM_TEXT_QUERY`: a letter's body, asked once per mail with a nonzero `item_text_id`.
     pub fn item_text_query(&mut self, text_id: u32, mail_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_ITEM_TEXT_QUERY,
@@ -116,9 +95,8 @@ impl WorldWriter {
         )
     }
 
-    /// Ask whether unread mail is waiting (`MSG_QUERY_NEXT_MAIL_TIME`, EMPTY body — same opcode
-    /// answers with one `f32`: `0.0` unread waiting, `-86400.0` none). Sent once at login to seed
-    /// `HasNewMail()`/the minimap letter icon.
+    /// `MSG_QUERY_NEXT_MAIL_TIME`, empty: the reply is one `f32`, `0.0` when unread mail waits and
+    /// `-86400.0` when none. Sent at login to seed `HasNewMail()`.
     pub fn query_next_mail_time(&mut self) -> Result<()> {
         self.send(opcode::MSG_QUERY_NEXT_MAIL_TIME, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/meeting_stone.rs b/crates/benilla-protocol/src/world/writer/meeting_stone.rs
index 3728686e..62afd247 100644
--- a/crates/benilla-protocol/src/world/writer/meeting_stone.rs
+++ b/crates/benilla-protocol/src/world/writer/meeting_stone.rs
@@ -1,4 +1,4 @@
-//! The meeting-stone queue's sends (decisions 1963/2283).
+//! The meeting-stone queue's sends.
 
 use anyhow::Result;
 
@@ -7,10 +7,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Join the meeting-stone queue (`CMSG 0x292`, `u64 goGuid`) — what a right-click on a
-    /// `GAMEOBJECT_TYPE_MEETINGSTONE` sends once that type's own use-slot validator has passed
-    /// its four client-side refusals (decision 2283). Never `CMSG_GAMEOBJ_USE`: the server has no
-    /// type-23 case for the shared opener.
+    /// `CMSG_MEETINGSTONE_JOIN`: a meeting stone's right-click, after the client's own checks.
+    /// Never `CMSG_GAMEOBJ_USE`: the server has no case for type 23 there.
     pub fn meeting_stone_join(&mut self, go_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_MEETINGSTONE_JOIN,
@@ -18,8 +16,8 @@ impl WorldWriter {
         )
     }
 
-    /// Leave the meeting-stone queue (`CMSG 0x293`, empty) — `CancelMeetingStoneRequest()`'s
-    /// packet, sent by the party leader (or a player in no party).
+    /// `CMSG_MEETINGSTONE_LEAVE`, empty: `CancelMeetingStoneRequest()`, from the party leader or a
+    /// player in no party.
     pub fn meeting_stone_leave(&mut self) -> Result<()> {
         self.send(
             opcode::CMSG_MEETINGSTONE_LEAVE,
@@ -27,8 +25,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for the meeting-stone status (`CMSG 0x296`, empty) — the enter-world query the
-    /// reference sends once per world session (decision 1974).
+    /// `CMSG_MEETINGSTONE_STATUS_QUERY`, empty: the reference sends it once per world session.
     pub fn meeting_stone_status_query(&mut self) -> Result<()> {
         self.send(opcode::CMSG_MEETINGSTONE_STATUS_QUERY, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/mod.rs b/crates/benilla-protocol/src/world/writer/mod.rs
index 3563fd46..de0fa1d1 100644
--- a/crates/benilla-protocol/src/world/writer/mod.rs
+++ b/crates/benilla-protocol/src/world/writer/mod.rs
@@ -1,53 +1,5 @@
-//! The world session's **write half** — [`WorldWriter`] and every outbound verb the client has: one
-//! method per thing the player can *do*, which is not quite one per opcode (the fifteen chat
-//! flavours all ride `CMSG_MESSAGECHAT`, and four cast shapes ride `CMSG_CAST_SPELL`).
-//!
-//! This file holds only the type, its state, and the one private [`WorldWriter::send`] every verb
-//! funnels through; the verbs themselves live in per-family sibling modules. The families **mirror
-//! [`crate::messages`]'s own decomposition**, so the module a body builder lives in names the module
-//! its send lives in (`messages::vendor::buy_item` ↔ `writer::vendor`'s `buy_item`) — the split rule
-//! is mechanical rather than a matter of judgment, which is what keeps it from silting back up
-//! (decision 0636; [`channel`]/[`group`]/[`mail`]/[`trade`]/[`duel`] were peeled off ahead of it,
-//! starting with decision 0288 phase 1).
-//!
-//! | module | the family |
-//! |---|---|
-//! | [`self_movement`] | our own mover: the `MSG_MOVE_*` stream + every mover ack |
-//! | [`lifecycle`] | being logged in: ping, logout, the cinematic ack |
-//! | [`selection`] | the two sends that set our target: select, inspect |
-//! | [`pvp`] | the honor system's one ask: another player's honor stats |
-//! | [`names`] | the ask-once name lookups: player, creature, pet |
-//! | [`chat`] | the chat frame's wire: every `MESSAGECHAT` flavour + `/played`, `/random`, `/wave` |
-//! | [`channel`] | channel administration: join/leave/list/moderation |
-//! | [`spells`] | casting, the four cancels, and the aura cancel |
-//! | [`attack`] | the auto-attack toggle: melee start/stop, ranged auto-repeat stop |
-//! | [`action_bar`] | the one client-authoritative slot write |
-//! | [`pet`] | the pet bar's four intents: press, autocast, call off, drag |
-//! | [`progression`] | the talent spend |
-//! | [`skills`] | the skills pane's abandon |
-//! | [`pose`] | the client-volunteered body state: sheath, stand, the mounted flourish |
-//! | [`items`] | bags and equipment: use, equip, swap/split/destroy, the template ask |
-//! | [`loot`] | the loot window: open, take, coin, close, roll |
-//! | [`death`] | the corpse run: release, corpse query, reclaim, spirit healer, res answer |
-//! | [`gm_ticket`] | the Help window: file, edit, ask, abandon, queue status |
-//! | [`gossip`] | the front door to every NPC service window |
-//! | [`vendor`] | buy, sell, buy back, repair |
-//! | [`bank`] | open, buy a slot, deposit, withdraw |
-//! | [`trainer`] | the service list refresh + the purchase |
-//! | [`stable`] | the hunter stable: the list refresh, stable/unstable/swap, buy a slot |
-//! | [`taxi`] | the flight master: status, map, the two flight verbs |
-//! | [`quest`] | the questgiver dialog walk + the two quest-log verbs |
-//! | [`gameobject`] | the one USE verb + the template ask |
-//! | [`group`] | party/raid: invite, kick, leader, loot method, icons, ready checks |
-//! | [`guild`] | the guild: the two cache asks, invitations, member verbs, rank administration |
-//! | [`instance`] | the one lockout verb: reset all instances |
-//! | [`trade`] | the player-trade dance |
-//! | [`duel`] | accept and cancel |
-//! | [`mail`] | the mailbox |
-//! | [`auction`] | the auction house: the hello, the three list pages, sell/bid/cancel |
-//! | [`player_flags`] | the empty-bodied `PLAYER_FLAGS` toggles: PvP, show-helm, show-cloak |
-//! | [`social`] | friends, ignores, and `/who` |
-//! | [`area_trigger`] | the one "I walked into trigger N" report |
+//! The world session's write half: [`WorldWriter`] and one method per thing the player can do.
+//! Each family module mirrors its namesake in `crate::messages`, which builds the bodies.
 
 use std::net::TcpStream;
 
@@ -101,39 +53,23 @@ mod trainer;
 mod tutorial;
 mod vendor;
 
-/// Write half of a split [`WorldSession`](super::WorldSession) — owns a cloned socket + the encrypter. Used to send our own
-/// movement (`MSG_MOVE_*`). The active player must already be the confirmed mover (see
-/// [`WorldSession::set_active_mover`](super::WorldSession::set_active_mover)). Coordinates are raw WoW yards; `orientation` is radians.
+/// Write half of a split [`WorldSession`](super::WorldSession): a cloned socket and the encrypter.
+/// Movement sends need the active player confirmed as mover first
+/// ([`WorldSession::set_active_mover`](super::WorldSession::set_active_mover)). Positions are raw
+/// WoW yards; `orientation` is radians.
 pub struct WorldWriter {
     pub(super) stream: TcpStream,
     pub(super) encrypter: EncrypterHalf,
-    /// Every packet that has actually reached the socket since the last drain, as
-    /// `(opcode, body length)` — armed by [`Self::watch_sends`], `None` (and free) otherwise.
-    ///
-    /// The **outbound twin of the app's inbound `in` trace**. Inbound, every packet is accounted
-    /// for by name the moment it arrives; outbound there was nothing of the kind — the mover's
-    /// `snd` lines record a *decision* taken before the command is even queued, and the `wire` tag
-    /// records only failures, so "did we actually send X?" could be answered only by inference
-    /// from a silence. That is a poor instrument for a client whose fidelity is partly *what it
-    /// puts on the wire*: decision 1872 landed a whole feature — the GameObject questgiver query —
-    /// whose entire observable effect is a send, and the only way to see it from inside was to add
-    /// state to a game resource.
-    ///
-    /// Recorded **after** a successful write, never before, so a line here means a transmission
-    /// and not an intention.
+    /// Every packet that reached the socket since the last drain, as `(opcode, body length)`;
+    /// `None` until [`Self::watch_sends`]. Pushed only after a successful write.
     pub(super) sent: Option<Vec<(u16, usize)>>,
-    /// The language every chat send carries — the logged-in character's faction tongue,
-    /// inherited from the session at split (set by `WorldSession::player_login` off the roster's
-    /// race). Load-bearing: vmangos drops the whole message (dot-commands included) when the
-    /// character doesn't know the language — a Horde character sending Common gets only an
-    /// `SMSG_NOTIFICATION` back, never the say / the command.
+    /// The character's faction language, set at login from its race; every chat send carries it.
+    /// vmangos drops the whole message, dot-commands included, when the character does not know it.
     pub(super) chat_language: u32,
 }
 
 impl WorldWriter {
-    /// Frame, encrypt, and write one packet. Private, and the sole write path — every verb in the
-    /// family modules goes through here, so there is exactly one place framing/encryption happens.
-    /// Visible to them because a private item is in scope throughout its module's descendants.
+    /// Frame, encrypt and write one packet: the sole write path every verb goes through.
     fn send(&mut self, opcode: u16, body: &[u8]) -> Result<()> {
         let sent = send_packet(&mut self.stream, Some(&mut self.encrypter), opcode, body);
         if sent.is_ok() {
@@ -144,14 +80,12 @@ impl WorldWriter {
         sent
     }
 
-    /// Start recording what reaches the socket — see [`Self::sent`]. Idempotent; a writer that is
-    /// already watching keeps whatever it has not yet handed over.
+    /// Start recording what reaches the socket; a second call keeps what is not yet drained.
     pub fn watch_sends(&mut self) {
         self.sent.get_or_insert_with(Vec::new);
     }
 
-    /// Hand over (and clear) everything recorded since the last call — `(opcode, body length)` per
-    /// packet, in send order. A no-op on a writer that is not watching.
+    /// Hand over and clear the recorded `(opcode, body length)` pairs, in send order.
     pub fn drain_sent(&mut self, mut each: impl FnMut(u16, usize)) {
         if let Some(log) = &mut self.sent {
             for (opcode, len) in log.drain(..) {
diff --git a/crates/benilla-protocol/src/world/writer/names.rs b/crates/benilla-protocol/src/world/writer/names.rs
index f0455cd2..430b47e0 100644
--- a/crates/benilla-protocol/src/world/writer/names.rs
+++ b/crates/benilla-protocol/src/world/writer/names.rs
@@ -1,13 +1,4 @@
-//! The name-lookup `WorldWriter` sends — the three ask-once queries that turn a guid into
-//! something displayable: a player's name/race/gender/class, a creature template's name/subname,
-//! and a pet's given name. Bodies in [`crate::messages`]'s `full_guid`/`creature_query`/
-//! `pet_name_query` builders. Split out of `writer/mod.rs` (decision 0636).
-//!
-//! Three verbs rather than one because the guid's own bits decide which can answer: a creature's
-//! guid embeds its template entry ([`crate::guid::entry`]) while a pet's embeds a pet number
-//! ([`crate::guid::pet_number`]), so [`WorldWriter::creature_query`] cannot name a pet and
-//! [`WorldWriter::pet_name_query`] is the only thing that can. Every answer is cacheable forever
-//! (a name never changes under a guid), which is what makes these the ask-once family.
+//! The ask-once lookups that turn a guid into a player, creature or pet name.
 
 use anyhow::Result;
 
@@ -16,15 +7,12 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask for a player character's name/race/gender/class (`CMSG_NAME_QUERY`, a full 8-byte guid —
-    /// vmangos `QueryPlayerName::ReadFromWorldPacket`). Answered by `SMSG_NAME_QUERY_RESPONSE`.
+    /// `CMSG_NAME_QUERY`: a player's name, race, gender and class, by full 8-byte guid.
     pub fn name_query(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_NAME_QUERY, &messages::full_guid(guid))
     }
 
-    /// Ask for a creature template's name/subname (`CMSG_CREATURE_QUERY`: entry + guid). The `entry`
-    /// is the one embedded in the creature's guid bits 24–47 ([`crate::guid::entry`]). Answered by
-    /// `SMSG_CREATURE_QUERY_RESPONSE`.
+    /// `CMSG_CREATURE_QUERY`: a template's name and subname; `entry` is guid bits 24 to 47.
     pub fn creature_query(&mut self, entry: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_CREATURE_QUERY,
@@ -32,10 +20,8 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for a pet's name (`CMSG_PET_NAME_QUERY`: pet number + guid). A pet's guid holds a pet
-    /// number where a creature's holds its template entry ([`crate::guid::pet_number`]), so
-    /// [`Self::creature_query`] cannot name one — this is the only query that can. Answered by
-    /// `SMSG_PET_NAME_QUERY_RESPONSE`, or by silence if the pet is gone.
+    /// `CMSG_PET_NAME_QUERY`: the only way to name a pet, whose guid holds a pet number, not an
+    /// entry. A pet that is gone gets no answer.
     pub fn pet_name_query(&mut self, pet_number: u32, guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_PET_NAME_QUERY,
diff --git a/crates/benilla-protocol/src/world/writer/pet.rs b/crates/benilla-protocol/src/world/writer/pet.rs
index 8d5224ce..7eec2614 100644
--- a/crates/benilla-protocol/src/world/writer/pet.rs
+++ b/crates/benilla-protocol/src/world/writer/pet.rs
@@ -1,25 +1,6 @@
-//! The pet's `WorldWriter` sends — mirroring [`crate::messages::pet`] (decisions 0982, 0988, 1066).
-//!
-//! Six verbs, and the thing to know about the bar's four is that **no reply packet answers any of
-//! them**. The first three are intents the client has already applied to its own state before sending
-//! (wow-re §10.1/§10.2: the reaction, command and autocast paths all write `[0xb71468]` or the
-//! slot word and fire `PET_BAR_UPDATE` *before* the packet leaves). The bar's contents change only
-//! when a fresh `SMSG_PET_SPELLS` arrives — a summon, a swap, a learned spell — never as a reply
-//! to one of these.
-//!
-//! [`WorldWriter::pet_cancel_aura`] is the exception worth naming: it too gets no reply, but it is
-//! the one verb the client does *not* pre-apply, because what it changes is the pet's own
-//! descriptor. The aura leaves in a `UNIT_FIELD_AURA` delta, and the slot's icon follows from
-//! that — so the round trip is visible, just not as an answer.
-//!
-//! The menu's two ([`WorldWriter::pet_abandon`], [`WorldWriter::pet_rename`]) invert that: neither
-//! is pre-applied, because what each asks for is not a UI state the server ignores but a change to
-//! the world that it may refuse — and the answer arrives as the pet leaving, or as a bumped name
-//! timestamp in its descriptor.
-//!
-//! Every one carries the pet's guid: the server re-checks ownership on each
-//! (`PetHandler.cpp`'s `GetCharmerOrOwnerGuid` gate) and silently drops anything naming a unit we
-//! don't control.
+//! The pet sends. No reply answers a bar send: the 1.12 client applies the press to its own state
+//! (`0xb71468`, `PET_BAR_UPDATE`) before sending, and the bar changes only on a fresh
+//! `SMSG_PET_SPELLS`. The server drops a send naming a pet we do not control (`PetHandler.cpp`).
 
 use anyhow::Result;
 
@@ -28,10 +9,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Press one pet bar slot (`CMSG_PET_ACTION`, layout in [`messages::pet_action`]) — the one
-    /// verb behind all three slot classes, because the server dispatches on the **type byte inside
-    /// the word we echo**: a command token runs `HandlePetCommand`, a reaction token sets the react
-    /// state, a spell casts. `target` is the unit the action should aim at, or `0`.
+    /// `CMSG_PET_ACTION`: press a bar slot. The server dispatches on the type byte of the echoed
+    /// word (command, reaction or spell); `target_guid` is 0 for none.
     pub fn pet_action(&mut self, pet_guid: u64, packed: u32, target_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_PET_ACTION,
@@ -39,8 +18,7 @@ impl WorldWriter {
         )
     }
 
-    /// Call the pet off its target (`CMSG_PET_STOP_ATTACK`, layout in
-    /// [`messages::pet_stop_attack`]) — the Attack button's second press.
+    /// `CMSG_PET_STOP_ATTACK`: the Attack button's second press.
     pub fn pet_stop_attack(&mut self, pet_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_PET_STOP_ATTACK,
@@ -48,13 +26,9 @@ impl WorldWriter {
         )
     }
 
-    /// Cancel one of the **pet's** auras (`CMSG_PET_CANCEL_AURA`, layout in
-    /// [`messages::pet_cancel_aura`]) — a pet bar spell click that lands on a spell already running
-    /// on the pet (wow-re §10.1, `0x4bd25f`; the predicate is `0x4bcea0`).
-    ///
-    /// The click that sends this sends **nothing else**: the reference returns straight after,
-    /// so the ordinary `CMSG_PET_ACTION` never leaves. That "and return" is the whole behaviour —
-    /// clicking a lit pet buff takes it off rather than re-casting it.
+    /// `CMSG_PET_CANCEL_AURA`: a bar click on a spell already on the pet sends only this, not
+    /// `CMSG_PET_ACTION` (reference: `0x4bd25f`, predicate `0x4bcea0`). Not pre-applied: the aura
+    /// leaves by a `UNIT_FIELD_AURA` delta.
     pub fn pet_cancel_aura(&mut self, pet_guid: u64, spell_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_PET_CANCEL_AURA,
@@ -62,13 +36,8 @@ impl WorldWriter {
         )
     }
 
-    /// Write one or two pet bar slots (`CMSG_PET_SET_ACTION`, layout — and the reason this one
-    /// opcode carries two different verbs — in [`messages::pet_set_action`]).
-    ///
-    /// **The autocast toggle is this send**, with one entry: the pressed slot and its word with
-    /// bit 30 flipped. The drag is the same send with one or two. Unlike the player bar's
-    /// [`WorldWriter::set_action_button`], a swap here IS atomic — the server tells the forms
-    /// apart by body size and applies both entries together.
+    /// `CMSG_PET_SET_ACTION`: one entry toggles autocast (the slot's word with bit 30 flipped); a
+    /// drag sends one or two, and the server applies a two-entry swap atomically.
     pub fn pet_set_action(&mut self, pet_guid: u64, entries: &[(u32, u32)]) -> Result<()> {
         self.send(
             opcode::CMSG_PET_SET_ACTION,
@@ -76,14 +45,8 @@ impl WorldWriter {
         )
     }
 
-    /// Flip one pet **spellbook** entry's autocast (`CMSG_PET_SPELL_AUTOCAST`, layout in
-    /// [`messages::pet_spell_autocast`]) — `ToggleSpellAutocast`'s send (decision 1032).
-    ///
-    /// The fifth verb, and the one easy to mistake for the fourth: the pet BAR's autocast right
-    /// click is [`WorldWriter::pet_set_action`] with one entry (a slot and its word), while this
-    /// names a **spell id**, because the book it comes from has no slots. Same bit, same
-    /// server-side effect; different opcode, different body, different handler. Like the rest of
-    /// this file: no reply.
+    /// `CMSG_PET_SPELL_AUTOCAST`: `ToggleSpellAutocast` from the pet spellbook, by spell id. The
+    /// bar's autocast click is `pet_set_action` instead.
     pub fn pet_spell_autocast(
         &mut self,
         pet_guid: u64,
@@ -96,24 +59,14 @@ impl WorldWriter {
         )
     }
 
-    /// Give the pet up (`CMSG_PET_ABANDON`, layout in [`messages::pet_abandon`]) — the right-click
-    /// menu's Abandon **and** its Dismiss, which are one message (decision 1066).
-    ///
-    /// Unlike everything above it this one is not pre-applied and does not need to be: what answers
-    /// it is the pet leaving — `SMSG_PET_SPELLS` with a zero guid tears the bar down, and the
-    /// object's own removal takes the frame with it. Optimism would only race that.
+    /// `CMSG_PET_ABANDON`: both Abandon and Dismiss. Not pre-applied: the pet leaving answers it,
+    /// with `SMSG_PET_SPELLS` carrying a zero guid.
     pub fn pet_abandon(&mut self, pet_guid: u64) -> Result<()> {
         self.send(opcode::CMSG_PET_ABANDON, &messages::pet_abandon(pet_guid))
     }
 
-    /// Rename the pet (`CMSG_PET_RENAME`, layout in [`messages::pet_rename`]) — the `RENAME_PET` →
-    /// `PETRENAMECONFIRM` popup chain's payload.
-    ///
-    /// Also not pre-applied, and here that is load-bearing: the server validates the name
-    /// (`ObjectMgr::CheckPetName`, the reserved-name list) and may refuse it outright, so a client
-    /// that wrote the new name locally would show a name the world does not agree with. What
-    /// arrives on success is a bumped `UNIT_FIELD_PET_NAME_TIMESTAMP` in the pet's descriptor,
-    /// which is what makes the name cache re-ask.
+    /// `CMSG_PET_RENAME`: not pre-applied, as the server may refuse the name
+    /// (`ObjectMgr::CheckPetName`). Success bumps `UNIT_FIELD_PET_NAME_TIMESTAMP`.
     pub fn pet_rename(&mut self, pet_guid: u64, name: &str) -> Result<()> {
         self.send(
             opcode::CMSG_PET_RENAME,
@@ -121,8 +74,7 @@ impl WorldWriter {
         )
     }
 
-    /// Unlearn the pet's skills at its trainer (`CMSG_PET_UNLEARN`) — `ConfirmPetUnlearn()`'s
-    /// packet, carrying the latched trainer guid (decision 1963).
+    /// `CMSG_PET_UNLEARN`: `ConfirmPetUnlearn()`, carrying the latched trainer guid.
     pub fn pet_unlearn(&mut self, trainer: u64) -> Result<()> {
         self.send(opcode::CMSG_PET_UNLEARN, &messages::pet_unlearn(trainer))
     }
diff --git a/crates/benilla-protocol/src/world/writer/petition.rs b/crates/benilla-protocol/src/world/writer/petition.rs
index 6c023bea..2bb588c1 100644
--- a/crates/benilla-protocol/src/world/writer/petition.rs
+++ b/crates/benilla-protocol/src/world/writer/petition.rs
@@ -1,21 +1,6 @@
-//! The petition family's `WorldWriter` sends — buying a guild charter, showing it, signing it,
-//! offering it, renaming it and turning it in (decision 1672).
-//!
-//! [`super::guild`] is *being* in a guild; this is *founding* one, and at 1.12 the two share only
-//! their error channel. Three shapes bind every caller here:
-//!
-//! - **A charter is addressed by its ITEM guid**, not by a petition id — sign, offer, rename,
-//!   decline and turn-in all take the item. The petition *id* appears in exactly one place,
-//!   [`WorldWriter::petition_query`], and it is not derivable from the item without either a
-//!   preceding `SMSG_PETITION_SHOW_SIGNATURES` or a read of the item's enchantment slot 0
-//!   (see [`crate::messages::petition`]'s module doc).
-//! - **Success is mostly silent.** Buying answers with nothing but the new item; offering answers
-//!   the *target*, not us; renaming echoes only if it took. What comes back on a refusal is an
-//!   `SMSG_GUILD_COMMAND_RESULT`, borrowed from the guild family — so a caller that only listens
-//!   for petition opcodes will see a failed verb as a hang.
-//! - **Every one of these can be refused silently** by a range or ownership check the client
-//!   cannot see (`GetNPCIfCanInteractWith`, "do we hold that item", "are we the owner"). None of
-//!   them is safe to treat as applied at the send.
+//! The guild charter sends. A charter is addressed by its item guid; only `petition_query` takes
+//! the petition id. Success is mostly silent, a refusal comes back as the guild family's
+//! `SMSG_GUILD_COMMAND_RESULT`, and a failed range or ownership check drops a send unanswered.
 
 use anyhow::Result;
 
@@ -24,13 +9,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask a petitioner NPC what charters it sells (`CMSG_PETITION_SHOWLIST`), answered by
-    /// `SMSG_PETITION_SHOWLIST`.
-    ///
-    /// This is the **second** way that answer arrives: selecting the NPC's
-    /// `GOSSIP_OPTION_PETITIONER` row makes the server close the gossip menu and push the same
-    /// packet unasked (`Player.cpp:12428-12431`). So a client that only ever talks through gossip
-    /// never needs this send — it is here for the direct re-open, and because the opcode exists.
+    /// `CMSG_PETITION_SHOWLIST`: answered by `SMSG_PETITION_SHOWLIST`, which the petitioner's
+    /// gossip option also pushes unasked (`Player.cpp:12428`).
     pub fn petition_show_list(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::CMSG_PETITION_SHOWLIST,
@@ -38,18 +18,9 @@ impl WorldWriter {
         )
     }
 
-    /// Buy a guild charter from a petitioner NPC (`CMSG_PETITION_BUY`) under the given name.
-    ///
-    /// **Nothing acknowledges a successful buy.** The server takes the money, stores item
-    /// [`messages::CHARTER_ITEM_ENTRY`] and sends only the ordinary `SMSG_ITEM_PUSH_RESULT`
-    /// (`Handlers/PetitionsHandler.cpp:130`). A refusal, by contrast, is loud and arrives on three
-    /// *different* opcodes depending on which check failed: `SMSG_GUILD_COMMAND_RESULT` for a
-    /// taken or invalid name, `SMSG_BUY_FAILED` for too little money, `SMSG_INVENTORY_CHANGE_FAILURE`
-    /// for a full bag.
-    ///
-    /// The name is capped at [`messages::CHARTER_NAME_MAX_LENGTH`] characters by the server's own
-    /// validator; the caller enforces that at the edit box, as the reference does, rather than
-    /// truncating here.
+    /// `CMSG_PETITION_BUY`, name capped by the caller: success sends only `SMSG_ITEM_PUSH_RESULT`
+    /// (`PetitionsHandler.cpp:130`); a refusal is `SMSG_GUILD_COMMAND_RESULT` (name),
+    /// `SMSG_BUY_FAILED` (money) or `SMSG_INVENTORY_CHANGE_FAILURE` (full bag).
     pub fn petition_buy(&mut self, npc: u64, name: &str) -> Result<()> {
         self.send(
             opcode::CMSG_PETITION_BUY,
@@ -57,12 +28,8 @@ impl WorldWriter {
         )
     }
 
-    /// Open a charter and see who has signed it (`CMSG_PETITION_SHOW_SIGNATURES`), answered by
-    /// `SMSG_PETITION_SHOW_SIGNATURES`.
-    ///
-    /// Dropped **silently** if we are already in a guild or do not hold that item
-    /// (`Handlers/PetitionsHandler.cpp:140`, `:143`), so a caller must not wait on the answer as
-    /// though it were guaranteed.
+    /// `CMSG_PETITION_SHOW_SIGNATURES`: dropped unanswered if we are in a guild or do not hold the
+    /// item (`PetitionsHandler.cpp:140`).
     pub fn petition_show_signatures(&mut self, item: u64) -> Result<()> {
         self.send(
             opcode::CMSG_PETITION_SHOW_SIGNATURES,
@@ -70,14 +37,9 @@ impl WorldWriter {
         )
     }
 
-    /// Sign somebody's charter (`CMSG_PETITION_SIGN`), answered by `SMSG_PETITION_SIGN_RESULTS` —
-    /// which the server sends to the **owner too**, identical, with the signer's guid in both
-    /// copies.
-    ///
-    /// Not every refusal comes back on that opcode: an already-guilded or cross-faction signer is
-    /// answered with an `SMSG_GUILD_COMMAND_RESULT` instead
-    /// (`Handlers/PetitionsHandler.cpp:252`, `:258`).
-    /// `arg` is the byte the optional Lua argument rides on; the client's own default is `1`.
+    /// `CMSG_PETITION_SIGN`: `SMSG_PETITION_SIGN_RESULTS` goes to us and the owner alike; a
+    /// guilded or cross-faction signer gets `SMSG_GUILD_COMMAND_RESULT` instead
+    /// (`PetitionsHandler.cpp:252`). `arg` carries the optional Lua argument, 1 by default.
     pub fn petition_sign(&mut self, item: u64, arg: i8) -> Result<()> {
         self.send(
             opcode::CMSG_PETITION_SIGN,
@@ -85,12 +47,8 @@ impl WorldWriter {
         )
     }
 
-    /// Show our charter to another player so they can sign it (`CMSG_OFFER_PETITION`).
-    ///
-    /// The success path answers **them**, not us: the server sends *the target* an
-    /// `SMSG_PETITION_SHOW_SIGNATURES` (`Handlers/PetitionsHandler.cpp:390-397`). We hear only
-    /// about refusals, as `SMSG_GUILD_COMMAND_RESULT`. So there is nothing local to update on the
-    /// send, and no answer to wait for.
+    /// `CMSG_OFFER_PETITION`: the target gets `SMSG_PETITION_SHOW_SIGNATURES`; we hear back only on
+    /// a refusal (`PetitionsHandler.cpp:390`).
     pub fn offer_petition(&mut self, item: u64, player: u64) -> Result<()> {
         self.send(
             opcode::CMSG_OFFER_PETITION,
@@ -98,17 +56,9 @@ impl WorldWriter {
         )
     }
 
-    /// Turn a completed charter in to a guild registrar (`CMSG_TURN_IN_PETITION`), answered by
-    /// `SMSG_TURN_IN_PETITION_RESULTS`.
-    ///
-    /// Only the charter's **owner** may do this; anyone else is refused silently
-    /// (`Handlers/PetitionsHandler.cpp:432`). And a guild-name collision answers with an
-    /// `SMSG_GUILD_COMMAND_RESULT` and **no results packet at all** (`:445`) — so the absence of a
-    /// result is itself an outcome, not a dropped packet.
-    ///
-    /// On success the guild is created with every signer as a member, and the charter item is
-    /// destroyed — which arrives as an ordinary inventory update, plus the guild family's own
-    /// roster push.
+    /// `CMSG_TURN_IN_PETITION`: answered by `SMSG_TURN_IN_PETITION_RESULTS`, except that a
+    /// non-owner gets nothing (`PetitionsHandler.cpp:432`) and a taken guild name gets only
+    /// `SMSG_GUILD_COMMAND_RESULT` (`:445`).
     pub fn turn_in_petition(&mut self, item: u64) -> Result<()> {
         self.send(
             opcode::CMSG_TURN_IN_PETITION,
@@ -116,12 +66,8 @@ impl WorldWriter {
         )
     }
 
-    /// Ask for a petition's record by id (`CMSG_PETITION_QUERY`), answered by
-    /// `SMSG_PETITION_QUERY_RESPONSE` — the **only** packet that carries the proposed guild's name
-    /// and the signature requirement.
-    ///
-    /// The `item` field is read and then ignored by vmangos, which looks the petition up by id
-    /// alone (`Handlers/PetitionsHandler.cpp:171-185`); it is sent at its true value anyway.
+    /// `CMSG_PETITION_QUERY`: the only source of the proposed guild name and signature count.
+    /// vmangos ignores `item` and looks the petition up by id (`PetitionsHandler.cpp:171`).
     pub fn petition_query(&mut self, petition_id: u32, item: u64) -> Result<()> {
         self.send(
             opcode::CMSG_PETITION_QUERY,
@@ -129,11 +75,8 @@ impl WorldWriter {
         )
     }
 
-    /// Rename a charter (`MSG_PETITION_RENAME`), echoed back **only if it took**; a rejected name
-    /// comes back as an `SMSG_GUILD_COMMAND_RESULT` and no echo.
-    ///
-    /// vmangos does **no ownership check** here — anyone holding the item may rename it
-    /// (`Handlers/PetitionsHandler.cpp:187-216`).
+    /// `MSG_PETITION_RENAME`: echoed only on success, else `SMSG_GUILD_COMMAND_RESULT`. vmangos
+    /// lets anyone holding the item rename it (`PetitionsHandler.cpp:187`).
     pub fn petition_rename(&mut self, item: u64, name: &str) -> Result<()> {
         self.send(
             opcode::MSG_PETITION_RENAME,
@@ -141,9 +84,7 @@ impl WorldWriter {
         )
     }
 
-    /// Decline a charter someone offered us (`MSG_PETITION_DECLINE`). We send the charter's item
-    /// guid; the server forwards **our** guid to its owner, which is why one opcode has two
-    /// bodies.
+    /// `MSG_PETITION_DECLINE`: we send the item guid; the owner gets ours on the same opcode.
     pub fn petition_decline(&mut self, item: u64) -> Result<()> {
         self.send(
             opcode::MSG_PETITION_DECLINE,
diff --git a/crates/benilla-protocol/src/world/writer/player_flags.rs b/crates/benilla-protocol/src/world/writer/player_flags.rs
index 84fea4d8..9e102847 100644
--- a/crates/benilla-protocol/src/world/writer/player_flags.rs
+++ b/crates/benilla-protocol/src/world/writer/player_flags.rs
@@ -1,13 +1,5 @@
-//! The **`PLAYER_FLAGS` toggles** — the three empty-bodied sends by which the player asks the
-//! server to flip one bit of their own `PLAYER_FLAGS`: the PvP flag (decision 0646), and the two
-//! equipment-display preferences, show-helm and show-cloak (decision 1472).
-//!
-//! What makes these one family, and unlike [`super::pose`]'s client-volunteered body state: **the
-//! server owns the bit, and the only answer is the descriptor.** Nothing here has an ack, nothing
-//! here has a body — the packet *is* the verb — and each one's effect comes back as a field in the
-//! next `SMSG_UPDATE_OBJECT`. So there is no body builder in [`crate::messages`] to mirror, and a
-//! caller that wants a *specific* state rather than a flip must compare against the flag it is
-//! already holding and send only on a difference.
+//! The empty-bodied toggles that ask the server to flip a bit of our own `PLAYER_FLAGS`. There is
+//! no ack, only the next descriptor update, so to reach a given state send only when it differs.
 
 use anyhow::Result;
 
@@ -16,24 +8,19 @@ use crate::messages::opcode;
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask the server to flip our own PvP flag (`CMSG_TOGGLE_PVP`, empty body) — `/pvp` and the
-    /// unit popup's PvP row. There is no ack and no immediate local effect: flagging *on* comes
-    /// back as the `UNIT_FIELD_FLAGS` PvP bit within the next descriptor update, while flagging
-    /// *off* only clears the preference — the flag itself survives until vmangos' 300 s drop
-    /// timer expires (`Player::UpdatePvP`). The client predicts neither.
+    /// `CMSG_TOGGLE_PVP`: flagging on shows as the `UNIT_FIELD_FLAGS` PvP bit; flagging off clears
+    /// only the wish, and the flag drops after vmangos's 300 s timer (`Player::UpdatePvP`).
     pub fn toggle_pvp(&mut self) -> Result<()> {
         self.send(opcode::CMSG_TOGGLE_PVP, &[])
     }
 
-    /// Ask the server to flip our show-helm preference (`CMSG_TOGGLE_HELM`, empty body) — the
-    /// Options window's *Show Helm* row, through the VM's intent queue. The answer is
-    /// `PLAYER_FLAGS`' `HIDE_HELM` bit in the next descriptor update, which is what every client
-    /// in range dresses our body from (decision 1472).
+    /// `CMSG_TOGGLE_HELM`: answered by the `PLAYER_FLAGS` `HIDE_HELM` bit, which every client in
+    /// range dresses our body from.
     pub fn toggle_helm(&mut self) -> Result<()> {
         self.send(opcode::CMSG_TOGGLE_HELM, &[])
     }
 
-    /// The cloak half of [`Self::toggle_helm`] (`CMSG_TOGGLE_CLOAK`, empty body).
+    /// `CMSG_TOGGLE_CLOAK`: the cloak half of [`Self::toggle_helm`].
     pub fn toggle_cloak(&mut self) -> Result<()> {
         self.send(opcode::CMSG_TOGGLE_CLOAK, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/pose.rs b/crates/benilla-protocol/src/world/writer/pose.rs
index 48946ad6..bdf1a520 100644
--- a/crates/benilla-protocol/src/world/writer/pose.rs
+++ b/crates/benilla-protocol/src/world/writer/pose.rs
@@ -1,13 +1,5 @@
-//! The three **client-volunteered** pose `WorldWriter` sends — sheath, stand state, and the
-//! mounted flourish. Bodies in [`crate::messages`]'s `set_sheathed`/`stand_state_change` builders
-//! (the flourish is bodyless). Split out of `writer/mod.rs` (decision 0636).
-//!
-//! What makes these one family, and unlike every other send here: **the client decides, the server
-//! only relays.** Nothing validates them and nothing answers them — the sheath byte and the stand
-//! byte land in our own `UNIT_FIELD_BYTES_2`/`BYTES_1` and every observer reads the pose from
-//! there (decisions 0080/0080c), and the flourish is a pure broadcast the sender plays locally at
-//! send time. So the *only* consequence of getting one wrong is that other players see the wrong
-//! body.
+//! The client-volunteered pose sends: sheath, stand state and the mount flourish. None gets a
+//! reply; other clients read the pose from our descriptor.
 
 use anyhow::Result;
 
@@ -16,19 +8,15 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Tell the server our sheath state (`CMSG_SETSHEATHED`): `state` 0 unarmed/stowed, 1 melee
-    /// drawn, 2 ranged drawn. Purely client-volunteered (body in [`messages::set_sheathed`]) — it
-    /// becomes our own `UNIT_FIELD_BYTES_2` sheath byte, which other clients read. Sent by the
-    /// manual toggle, the attack-start auto-draw, and every reconcile force (byte-verified: the
-    /// setter `0x611cf0` sends it whenever `bFireEvent` — wow-re `sheath-policy.md`,
-    /// decision 0080).
+    /// `CMSG_SETSHEATHED`: `state` 0 stowed, 1 melee drawn, 2 ranged drawn, stored as our
+    /// `UNIT_FIELD_BYTES_2` sheath byte. The reference setter `0x611cf0` sends it whenever
+    /// `bFireEvent` is set.
     pub fn set_sheathed(&mut self, state: u32) -> Result<()> {
         self.send(opcode::CMSG_SETSHEATHED, &messages::set_sheathed(state))
     }
 
-    /// Tell the server our stand state (`CMSG_STANDSTATECHANGE`): 0 stand · 1 sit · 3 sleep ·
-    /// 8 kneel (the only values vmangos accepts). Client-volunteered like sheath — the echo into
-    /// `UNIT_FIELD_BYTES_1` byte 0 drives every observer's sit/stand pose (decision 0080c).
+    /// `CMSG_STANDSTATECHANGE`: vmangos accepts only 0 stand, 1 sit, 3 sleep and 8 kneel, stored
+    /// as `UNIT_FIELD_BYTES_1` byte 0.
     pub fn stand_state_change(&mut self, state: u32) -> Result<()> {
         self.send(
             opcode::CMSG_STANDSTATECHANGE,
@@ -36,10 +24,8 @@ impl WorldWriter {
         )
     }
 
-    /// The mounted space-bar flourish (`CMSG_MOUNTSPECIAL_ANIM`, EMPTY body — VERIFIED vmangos
-    /// `HandleMountSpecialAnimOpcode`). The sender plays its own MountSpecial(94) locally at
-    /// send time and self-suppresses the broadcast echo (decision 0441 P2 — whether the echo
-    /// arrives is a server-config detail).
+    /// `CMSG_MOUNTSPECIAL_ANIM`, empty: the mounted space-bar flourish. The sender plays
+    /// `MountSpecial` (94) itself at send time and ignores the broadcast echo.
     pub fn mount_special(&mut self) -> Result<()> {
         self.send(opcode::CMSG_MOUNTSPECIAL_ANIM, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/progression.rs b/crates/benilla-protocol/src/world/writer/progression.rs
index fc722336..aa7e9fb8 100644
--- a/crates/benilla-protocol/src/world/writer/progression.rs
+++ b/crates/benilla-protocol/src/world/writer/progression.rs
@@ -1,10 +1,4 @@
-//! The character-progression `WorldWriter` send — the talent spend, mirroring
-//! [`crate::messages::progression`]. Split out of [`super::spells`] by decision 0640.
-//!
-//! The rest of that family is inbound only: XP awards and the level-up summary arrive as packets,
-//! and the points they grant go back out through this one verb — plus the one that gives them all
-//! back, the respec answer (decision 1580). The skills half of "what I have learned" has its own
-//! opcode and its own file, [`super::skills`].
+//! The talent sends: spending points and confirming a respec.
 
 use anyhow::Result;
 
@@ -13,10 +7,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Spend talent points (`CMSG_LEARN_TALENT`, layout in [`messages::learn_talent`]): the
-    /// `Talent.dbc` row id + the requested rank (0-based, learn-up-to). No dedicated reply — the
-    /// server validates silently; success arrives as the rank spell's learn effects plus the
-    /// refreshed `PLAYER_CHARACTER_POINTS1` (decision 0304).
+    /// `CMSG_LEARN_TALENT`: a `Talent.dbc` row and the 0-based rank to learn up to. No reply:
+    /// success is the rank spell's learn plus a fresh `PLAYER_CHARACTER_POINTS1`.
     pub fn learn_talent(&mut self, talent_id: u32, requested_rank: u32) -> Result<()> {
         self.send(
             opcode::CMSG_LEARN_TALENT,
@@ -24,12 +16,8 @@ impl WorldWriter {
         )
     }
 
-    /// Answer a class trainer's respec question (`MSG_TALENT_WIPE_CONFIRM` outbound, layout in
-    /// [`messages::talent_wipe_confirm`]) — the `CONFIRM_TALENT_WIPE` dialog's Accept, and the only
-    /// packet in the flow that unlearns anything: the question that raised the dialog arrived on
-    /// this same opcode and changed nothing. The server answers by resetting the talents and having
-    /// the trainer cast 14867, which lands as the un-learn of every rank spell plus the refreshed
-    /// `PLAYER_CHARACTER_POINTS1`; declining sends nothing at all (decision 1580).
+    /// `MSG_TALENT_WIPE_CONFIRM`: the `CONFIRM_TALENT_WIPE` dialog's Accept; declining sends
+    /// nothing. The server resets the talents and has the trainer cast spell 14867.
     pub fn talent_wipe_confirm(&mut self, trainer_guid: u64) -> Result<()> {
         self.send(
             opcode::MSG_TALENT_WIPE_CONFIRM,
diff --git a/crates/benilla-protocol/src/world/writer/pvp.rs b/crates/benilla-protocol/src/world/writer/pvp.rs
index 9cfeb34f..88aebb9e 100644
--- a/crates/benilla-protocol/src/world/writer/pvp.rs
+++ b/crates/benilla-protocol/src/world/writer/pvp.rs
@@ -1,13 +1,5 @@
-//! The one honor-system send: asking for another player's honor stats (decision 1512). The
-//! family's other message, `SMSG_PVP_CREDIT`, is inbound only.
-//!
-//! **Why its own module rather than [`super::selection`]** — that module is "the two sends that
-//! set our selection", and this send does not: `HandleInspectOpcode` opens with
-//! `SetSelectionGuid` (vmangos `MiscHandler.cpp:944`) while `HandleInspectHonorStatsOpcode` does
-//! not (`MiscHandler.cpp:962-972`), so filing it there would make that module's own doc false. It
-//! also follows `writer/mod.rs`'s stated, mechanical split rule: a send lives in the module named
-//! after the [`crate::messages`] module its body builder lives in, and this body builder is
-//! `messages::pvp::inspect_honor_stats`.
+//! The honor send: another player's honor stats. Unlike inspect, it does not set our selection
+//! (`MiscHandler.cpp:962`).
 
 use anyhow::Result;
 
@@ -16,14 +8,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask for a player's honor stats (`MSG_INSPECT_HONOR_STATS`, a raw 8-byte guid — body and
-    /// server gates documented on [`messages::inspect_honor_stats`]). The reply rides the **same**
-    /// opcode and surfaces as [`crate::events::SessionEvent::InspectHonorStats`].
-    ///
-    /// There is no failure reply: each of the server's three refusals (target offline, beyond
-    /// `INSPECT_DISTANCE`, a valid attack target) is a silent `return`. A caller must therefore
-    /// treat the ask as fire-and-forget and keep whatever it already had on screen, exactly as the
-    /// reference pane does — it re-asks on show and simply shows nothing until an answer lands.
+    /// `MSG_INSPECT_HONOR_STATS`: the reply rides the same opcode. An offline, distant or hostile
+    /// target gets no reply at all, so keep what is on screen until one lands.
     pub fn inspect_honor_stats(&mut self, guid: u64) -> Result<()> {
         self.send(
             opcode::MSG_INSPECT_HONOR_STATS,
diff --git a/crates/benilla-protocol/src/world/writer/quest.rs b/crates/benilla-protocol/src/world/writer/quest.rs
index 03befbaa..2886f17c 100644
--- a/crates/benilla-protocol/src/world/writer/quest.rs
+++ b/crates/benilla-protocol/src/world/writer/quest.rs
@@ -1,13 +1,5 @@
-//! The quest family's `WorldWriter` sends — the questgiver dialog walk (status probe → detail →
-//! accept → progress → reward panel → complete) and the two quest-log verbs. Bodies in
-//! [`crate::messages::quest`], whose `giver`/`log` split this mirrors as one file. Split out of
-//! `writer/mod.rs` (decision 0636).
-//!
-//! The dialog is a **client-driven state machine**: each panel the player advances to is another
-//! send, and the server only ever answers the panel that was asked for. Note the two ways a quest's
-//! text is fetched — [`WorldWriter::questgiver_query_quest`] needs an NPC guid (it's the click on a
-//! greeting row), while [`WorldWriter::quest_query`] takes only the id and is the quest log's own
-//! ask-once source.
+//! The quest sends: the questgiver dialog, the quest log and sharing. The dialog is client-driven:
+//! each panel is its own send, and the server answers only the panel asked for.
 
 use anyhow::Result;
 
@@ -16,10 +8,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Greet a questgiver (`CMSG_QUESTGIVER_HELLO`, layout in [`messages::questgiver_hello`]) —
-    /// answered with `SMSG_QUESTGIVER_QUEST_LIST` (or the gossip menu, server's choice). Sent by
-    /// the *end* of a quest session on a non-gossip NPC, which is how the reference puts the
-    /// player back in the giver's list after a decline (decision 1738).
+    /// `CMSG_QUESTGIVER_HELLO`: answered by the quest list or the gossip menu. The reference also
+    /// sends it when a quest session on a non-gossip NPC ends, to return to the giver's list.
     pub fn questgiver_hello(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_HELLO,
@@ -27,9 +17,7 @@ impl WorldWriter {
         )
     }
 
-    /// Ask a quest's detail panel (`CMSG_QUESTGIVER_QUERY_QUEST`, layout in
-    /// [`messages::questgiver_query_quest`]) — the click a greeting/gossip quest row makes.
-    /// Answered by `SMSG_QUESTGIVER_QUEST_DETAILS` (a `QuestDetail` event).
+    /// `CMSG_QUESTGIVER_QUERY_QUEST`: a quest row's click, asking for the details panel.
     pub fn questgiver_query_quest(&mut self, npc: u64, quest: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_QUERY_QUEST,
@@ -37,9 +25,7 @@ impl WorldWriter {
         )
     }
 
-    /// Accept a quest (`CMSG_QUESTGIVER_ACCEPT_QUEST`, layout in
-    /// [`messages::questgiver_accept_quest`]) — the detail panel's Accept button. Adds it to the log;
-    /// the server closes the gossip window (`SMSG_GOSSIP_COMPLETE`).
+    /// `CMSG_QUESTGIVER_ACCEPT_QUEST`: answered by `SMSG_GOSSIP_COMPLETE` closing the window.
     pub fn questgiver_accept_quest(&mut self, npc: u64, quest: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_ACCEPT_QUEST,
@@ -47,9 +33,8 @@ impl WorldWriter {
         )
     }
 
-    /// Ask a quest's turn-in progress panel (`CMSG_QUESTGIVER_COMPLETE_QUEST`, layout in
-    /// [`messages::questgiver_complete_quest`]) — answered by `SMSG_QUESTGIVER_REQUEST_ITEMS`
-    /// (a `QuestProgress` event), or OFFER_REWARD when there are no required items.
+    /// `CMSG_QUESTGIVER_COMPLETE_QUEST`: answered by the progress panel, or by the reward panel
+    /// when no items are required.
     pub fn questgiver_complete_quest(&mut self, npc: u64, quest: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_COMPLETE_QUEST,
@@ -57,9 +42,8 @@ impl WorldWriter {
         )
     }
 
-    /// Advance from the progress panel to the reward panel (`CMSG_QUESTGIVER_REQUEST_REWARD`, layout
-    /// in [`messages::questgiver_request_reward`]) — the progress panel's Continue button. Answered
-    /// by `SMSG_QUESTGIVER_OFFER_REWARD` (a `QuestOffer` event).
+    /// `CMSG_QUESTGIVER_REQUEST_REWARD`: the progress panel's Continue, answered by the reward
+    /// panel.
     pub fn questgiver_request_reward(&mut self, npc: u64, quest: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_REQUEST_REWARD,
@@ -67,10 +51,8 @@ impl WorldWriter {
         )
     }
 
-    /// Choose a reward and finish the quest (`CMSG_QUESTGIVER_CHOOSE_REWARD`, layout in
-    /// [`messages::questgiver_choose_reward`]; `reward` = choice index) — the reward panel's Complete
-    /// button. Answered by `SMSG_QUESTGIVER_QUEST_COMPLETE` (a `QuestComplete` event) + the
-    /// XP/money/item grants via `UPDATE_OBJECT`.
+    /// `CMSG_QUESTGIVER_CHOOSE_REWARD`: `reward` is the choice index; answered by
+    /// `SMSG_QUESTGIVER_QUEST_COMPLETE`.
     pub fn questgiver_choose_reward(&mut self, npc: u64, quest: u32, reward: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_CHOOSE_REWARD,
@@ -78,17 +60,12 @@ impl WorldWriter {
         )
     }
 
-    /// Ask a quest's full template (`CMSG_QUEST_QUERY`, layout in [`messages::quest_query`]) — the
-    /// quest-log detail pane's ask-once source, distinct from [`Self::questgiver_query_quest`]
-    /// (which needs an NPC guid, not just the quest id). Answered by `SMSG_QUEST_QUERY_RESPONSE`
-    /// (a `QuestTemplate` event).
+    /// `CMSG_QUEST_QUERY`: a quest template by id alone, the quest log's ask-once source.
     pub fn quest_query(&mut self, quest_id: u32) -> Result<()> {
         self.send(opcode::CMSG_QUEST_QUERY, &messages::quest_query(quest_id))
     }
 
-    /// Ask an NPC's questgiver dialog status (`CMSG_QUESTGIVER_STATUS_QUERY`, layout in
-    /// [`messages::questgiver_status_query`]) — the overhead `!`/`?` marker's value, answered by
-    /// `SMSG_QUESTGIVER_STATUS`.
+    /// `CMSG_QUESTGIVER_STATUS_QUERY`: the NPC's overhead `!` or `?` marker.
     pub fn questgiver_status_query(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTGIVER_STATUS_QUERY,
@@ -96,9 +73,7 @@ impl WorldWriter {
         )
     }
 
-    /// Abandon a quest-log slot (`CMSG_QUESTLOG_REMOVE_QUEST`, layout in
-    /// [`messages::questlog_remove_quest`]) — no ack SMSG; the server clears the `PLAYER_QUEST_LOG`
-    /// slot fields directly.
+    /// `CMSG_QUESTLOG_REMOVE_QUEST`: no ack; the server clears the `PLAYER_QUEST_LOG` slot fields.
     pub fn questlog_remove_quest(&mut self, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_QUESTLOG_REMOVE_QUEST,
@@ -106,11 +81,8 @@ impl WorldWriter {
         )
     }
 
-    /// Share the quest with the party (`CMSG_PUSHQUESTTOPARTY`, layout in
-    /// [`messages::push_quest_to_party`]) — the quest log's *Share Quest* button (decision 1733).
-    /// No member guid: the server walks the group itself and answers with one
-    /// `MSG_QUEST_PUSH_RESULT` per member (often two — the `SHARING_QUEST` opener, then the
-    /// outcome).
+    /// `CMSG_PUSHQUESTTOPARTY`: the server walks the group and answers with `MSG_QUEST_PUSH_RESULT`
+    /// per member, often two (`SHARING_QUEST`, then the outcome).
     pub fn push_quest_to_party(&mut self, quest_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_PUSHQUESTTOPARTY,
@@ -118,9 +90,8 @@ impl WorldWriter {
         )
     }
 
-    /// Answer the escort confirm with Yes (`CMSG_QUEST_CONFIRM_ACCEPT`, layout in
-    /// [`messages::quest_confirm_accept`]) — a `QUEST_FLAGS_PARTY_ACCEPT` quest a party member
-    /// started. Saying **No** sends nothing at all, so there is no counterpart method.
+    /// `CMSG_QUEST_CONFIRM_ACCEPT`: Yes to a party member's `QUEST_FLAGS_PARTY_ACCEPT` quest; No
+    /// sends nothing.
     pub fn quest_confirm_accept(&mut self, quest_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_QUEST_CONFIRM_ACCEPT,
@@ -128,11 +99,8 @@ impl WorldWriter {
         )
     }
 
-    /// Report our verdict on a quest a party member shared with us (`MSG_QUEST_PUSH_RESULT`,
-    /// layout in [`messages::quest_push_result`]) — the receiver's leg of the share, relayed by the
-    /// server to the sharer. `sharer` is the giver guid the shared
-    /// `SMSG_QUESTGIVER_QUEST_DETAILS` arrived under (a *player* guid, which is what makes that
-    /// panel a share).
+    /// `MSG_QUEST_PUSH_RESULT`: our answer to a shared quest, relayed to `sharer`, the player guid
+    /// the shared details panel arrived under.
     pub fn quest_push_result(&mut self, sharer: u64, msg: messages::QuestShareMsg) -> Result<()> {
         self.send(
             opcode::MSG_QUEST_PUSH_RESULT,
diff --git a/crates/benilla-protocol/src/world/writer/reputation.rs b/crates/benilla-protocol/src/world/writer/reputation.rs
index a4c51262..6940385c 100644
--- a/crates/benilla-protocol/src/world/writer/reputation.rs
+++ b/crates/benilla-protocol/src/world/writer/reputation.rs
@@ -1,8 +1,4 @@
-//! The reputation pane's `WorldWriter` sends, mirroring [`crate::messages::reputation`]: the at-war
-//! toggle, the inactive toggle, and the watched faction. Split out of `writer/mod.rs` (decision 0636).
-//!
-//! All three address a faction by its **reputation-list slot**, and none is acked — see the messages
-//! module for the shapes and for why the watched slot is signed.
+//! The reputation pane's sends. Each names a faction by its reputation-list slot; none is acked.
 
 use anyhow::Result;
 
@@ -11,9 +7,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Declare or withdraw war on a faction (`CMSG_SET_FACTION_ATWAR`, layout in
-    /// [`messages::set_faction_at_war`]) — the pane's crossed-swords checkbox. vmangos DROPS this
-    /// while the player is in combat, so a flip mid-fight is silently nothing.
+    /// `CMSG_SET_FACTION_ATWAR`: vmangos drops it while the player is in combat.
     pub fn set_faction_at_war(&mut self, rep_list_id: u32, at_war: bool) -> Result<()> {
         self.send(
             opcode::CMSG_SET_FACTION_ATWAR,
@@ -21,8 +15,7 @@ impl WorldWriter {
         )
     }
 
-    /// Move a faction to (or out of) the pane's inactive bucket (`CMSG_SET_FACTION_INACTIVE`,
-    /// layout in [`messages::set_faction_inactive`]).
+    /// `CMSG_SET_FACTION_INACTIVE`: move a faction into or out of the pane's inactive group.
     pub fn set_faction_inactive(&mut self, rep_list_id: u32, inactive: bool) -> Result<()> {
         self.send(
             opcode::CMSG_SET_FACTION_INACTIVE,
@@ -30,9 +23,8 @@ impl WorldWriter {
         )
     }
 
-    /// Watch a faction on the main bar, or [`messages::WATCHED_FACTION_NONE`] to stop
-    /// (`CMSG_SET_WATCHED_FACTION`, layout in [`messages::set_watched_faction`]). The answer comes
-    /// back as a `PLAYER_FIELD_WATCHED_FACTION_INDEX` descriptor update, not an ack.
+    /// `CMSG_SET_WATCHED_FACTION`: [`messages::WATCHED_FACTION_NONE`] stops watching; the answer is
+    /// a `PLAYER_FIELD_WATCHED_FACTION_INDEX` update.
     pub fn set_watched_faction(&mut self, rep_list_id: i32) -> Result<()> {
         self.send(
             opcode::CMSG_SET_WATCHED_FACTION,
diff --git a/crates/benilla-protocol/src/world/writer/selection.rs b/crates/benilla-protocol/src/world/writer/selection.rs
index e23d09d8..e9bd50bc 100644
--- a/crates/benilla-protocol/src/world/writer/selection.rs
+++ b/crates/benilla-protocol/src/world/writer/selection.rs
@@ -1,9 +1,5 @@
-//! The two `WorldWriter` sends that set our **selection** — picking a unit, and inspecting a
-//! player. Both carry a raw 8-byte guid ([`crate::messages::full_guid`]), and both land in the
-//! server's `UNIT_FIELD_TARGET` for us: `CMSG_INSPECT` sets the selection as a side effect
-//! (vmangos `MiscHandler.cpp:945`), which is why the real client sends it even though the inspect
-//! window paints from already-streamed PUBLIC fields. Split out of `writer/mod.rs`
-//! (decision 0636).
+//! The two sends that set our selection, picking a unit and inspecting a player, both carrying a
+//! raw 8-byte guid.
 
 use anyhow::Result;
 
@@ -12,20 +8,14 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Set (or clear) our current target: `CMSG_SET_SELECTION` carrying a **full 8-byte GUID** (verified
-    /// vmangos `SetSelection::ReadFromWorldPacket` — `recv_data >> guid` reads a raw `uint64`, not a
-    /// packed guid). `guid == 0` clears the selection. The real client sends this the moment the local
-    /// player picks a unit; the server records it in the player's `UNIT_FIELD_TARGET` and relays it to
-    /// nearby observers.
+    /// `CMSG_SET_SELECTION`: a raw `u64`, not a packed guid (`SetSelection::ReadFromWorldPacket`);
+    /// 0 clears it. The server stores it in our `UNIT_FIELD_TARGET` for observers.
     pub fn set_selection(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_SET_SELECTION, &messages::full_guid(guid))
     }
 
-    /// Ask to inspect a player (`CMSG_INSPECT`, a full 8-byte guid — vmangos
-    /// `WorldPackets::Misc::Inspect`). Server-side this *also* sets our selection to the target
-    /// (`MiscHandler.cpp:945`), which is why the real client sends it even though the inspect
-    /// window paints from already-streamed PUBLIC fields. The `SMSG_INSPECT` reply echoes the guid
-    /// and nothing else — we neither wait for it nor parse it (decision 0631).
+    /// `CMSG_INSPECT`: it also sets our selection (`MiscHandler.cpp:945`), so the reference sends
+    /// it though the window paints from streamed fields; the `SMSG_INSPECT` reply is just the guid.
     pub fn inspect(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_INSPECT, &messages::full_guid(guid))
     }
diff --git a/crates/benilla-protocol/src/world/writer/self_movement.rs b/crates/benilla-protocol/src/world/writer/self_movement.rs
index 887dfe6c..df66c9a1 100644
--- a/crates/benilla-protocol/src/world/writer/self_movement.rs
+++ b/crates/benilla-protocol/src/world/writer/self_movement.rs
@@ -1,14 +1,6 @@
-//! Our own mover's `WorldWriter` sends — the self-movement stream (`MSG_MOVE_*`) and the acks the
-//! server demands of a player mover (speed change, near-teleport, worldport, the granted
-//! movement-mode family, spline-done). Bodies in [`crate::messages`]'s `movement`/`move_*`/`teleport_ack`/
-//! `force_speed_ack` builders; the `MovementInfo` stamping is
-//! [`crate::world::movement`]'s. Split out of `writer/mod.rs` (decision 0636), the family the
-//! writer type itself was originally built for.
-//!
-//! What unites these beyond the opcode range: every one of them carries a full `MovementInfo`
-//! snapshot (or is the empty echo of one), and every ack is **mandatory** — un-acked, the server
-//! either force-resolves the change on a timeout and flags its anticheat, or completes the
-//! teleport ~20 s late.
+//! Our own mover's sends: the `MSG_MOVE_*` stream and the acks the server demands of a player
+//! mover. Every ack is mandatory: unacked, the server force-resolves the change on a timeout and
+//! flags its anticheat, or completes a teleport about 20 s late.
 
 use anyhow::Result;
 
@@ -18,13 +10,9 @@ use crate::world::movement::{client_uptime_ms, movement_info};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Send one self-movement packet: a `MSG_MOVE_*` `opcode` carrying a `MovementInfo` with the given
-    /// `flags` + pose. The caller (the controller) chooses the opcode per movement-axis transition
-    /// (start/stop forward/back/strafe/turn), the periodic heartbeat, and the facing update — exactly as
-    /// the real client does — and the `flags` it passes are the live CMovement bits the server relays to
-    /// nearby players. `flags` must only set bits whose `MovementInfo` tail we serialize — the base
-    /// directional/turn/walk bits, `JUMPING` (with its `jump` tail), `SWIMMING` (with its `pitch`
-    /// tail), and `ON_TRANSPORT` (with its `transport` local-frame tail — decision 0438 phase 2).
+    /// One `MSG_MOVE_*` packet, its opcode picked per movement transition as the reference does.
+    /// `flags` may set only bits with a serialized tail: directional, turn and walk bits, and
+    /// `JUMPING`, `SWIMMING` and `ON_TRANSPORT` with `jump`, `pitch` and `transport`.
     pub fn send_movement(
         &mut self,
         opcode: u16,
@@ -37,9 +25,7 @@ impl WorldWriter {
         transport: Option<TransportPose>,
     ) -> Result<()> {
         let mut info = movement_info(pos, orientation, flags);
-        // Each conditional tail is gated on its flag by the serializer, so the flag and the value must
-        // agree (they share `flags`): `SWIMMING` ⇒ the swim pitch, `JUMPING` ⇒ the ballistic launch
-        // tail, `ON_TRANSPORT` ⇒ the rider's local pose.
+        // The serializer writes each tail only when its flag is set, so flag and value must agree.
         info.pitch = pitch;
         info.fall_time = fall_time;
         info.jump = jump;
@@ -47,35 +33,21 @@ impl WorldWriter {
         self.send(opcode, &messages::movement(&info))
     }
 
-    /// Claim `guid` as the unit whose movement we are sending (`CMSG_SET_ACTIVE_MOVER`, a full u64).
-    ///
-    /// **The mover handshake is client-driven — no server packet sets it.** The server states who
-    /// we *may* drive (`SMSG_CLIENT_CONTROL_UPDATE`) and then waits; until this reply lands,
-    /// `Player::GetConfirmedMover` resolves nothing for the new mover and **every** `MSG_MOVE_*` we
-    /// send for it is discarded (vmangos `MovementHandler.cpp:844-884`, which also rejects a claim
-    /// on a unit it never handed us). Login makes this claim for our own body; possession simply
-    /// re-makes it for somebody else's.
+    /// `CMSG_SET_ACTIVE_MOVER`, full guid: the client's claim after `SMSG_CLIENT_CONTROL_UPDATE`.
+    /// Until it lands, every `MSG_MOVE_*` for that unit is discarded (`MovementHandler.cpp:844`);
+    /// sent at login for our own body and again on possession.
     pub fn set_active_mover(&mut self, guid: u64) -> Result<()> {
         self.send(opcode::CMSG_SET_ACTIVE_MOVER, &messages::full_guid(guid))
     }
 
-    /// Vote on the far-sight view the server has already chosen (`CMSG_FAR_SIGHT`, one `u8`).
-    ///
-    /// The real client sends this from exactly two sites, both inside its far-sight engage/release
-    /// function `0x5ee290`: `1` when the view attaches (`5ee3cb`/`5ee3dd`), `0` when it releases
-    /// (`5ee4f3`/`5ee504`). It names no object — the server resolves that from `PLAYER_FARSIGHT`,
-    /// which only the server writes.
+    /// `CMSG_FAR_SIGHT`, one `u8`: 1 when the view attaches, 0 when it releases (reference:
+    /// `0x5ee290`). It names no object; the server reads its own `PLAYER_FARSIGHT`.
     pub fn far_sight(&mut self, engage: bool) -> Result<()> {
         self.send(opcode::CMSG_FAR_SIGHT, &[u8::from(engage)])
     }
 
-    /// Give up `guid` as our mover (`CMSG_MOVE_NOT_ACTIVE_MOVER`): the full u64 guid being
-    /// released, then a `MovementInfo` at its parting pose.
-    ///
-    /// The pose is the point. vmangos clears its confirmed-mover state and **re-broadcasts a stop
-    /// under the old guid** built from what we send here (`MovementHandler.cpp:886-965`), so
-    /// skipping it strands every observer on that unit's last relayed pose — a possessed creature
-    /// left sliding where the possession ended.
+    /// `CMSG_MOVE_NOT_ACTIVE_MOVER`: the released full guid, then its parting pose, which vmangos
+    /// re-broadcasts to observers as a stop (`MovementHandler.cpp:886`).
     pub fn move_not_active_mover(
         &mut self,
         guid: u64,
@@ -91,11 +63,8 @@ impl WorldWriter {
         self.send(opcode::CMSG_MOVE_NOT_ACTIVE_MOVER, &body)
     }
 
-    /// Report that our movement clock skipped `lag_ms` (`CMSG_MOVE_TIME_SKIPPED`, layout in
-    /// [`messages::move_time_skipped`]) for the named mover. The server folds the number into its
-    /// own copy of our movement clock — and, when we have just boarded a transport, answers by
-    /// re-sending that transport's create update (the 1.12 boarding fix; see
-    /// [`opcode::CMSG_MOVE_TIME_SKIPPED`]).
+    /// `CMSG_MOVE_TIME_SKIPPED`: the server adds `lag_ms` to its copy of our movement clock and,
+    /// just after we board a transport, re-sends that transport's create update.
     pub fn move_time_skipped(&mut self, guid: u64, lag_ms: u32) -> Result<()> {
         self.send(
             opcode::CMSG_MOVE_TIME_SKIPPED,
@@ -103,11 +72,8 @@ impl WorldWriter {
         )
     }
 
-    /// Acknowledge that a server-authored spline (Charge/knockback/taxi — an `SMSG_MONSTER_MOVE`
-    /// addressed to our own guid) finished: `CMSG_MOVE_SPLINE_DONE` with a `MovementInfo` at the
-    /// ride's endpoint and the `spline_id` we were driven by. The server sets `SplineDonePending` for
-    /// a player mover and validates this against its newest spline id, then relocates us and
-    /// re-broadcasts a stop/heartbeat to observers — so it must be sent, at rest, once the ride ends.
+    /// `CMSG_MOVE_SPLINE_DONE`: owed, at rest, when an `SMSG_MONSTER_MOVE` on our own guid ends.
+    /// The server checks `spline_id` against its newest, then relocates us and tells observers.
     pub fn move_spline_done(
         &mut self,
         flags: u32,
@@ -122,16 +88,13 @@ impl WorldWriter {
         )
     }
 
-    /// Echo a cross-map worldport ack: confirms `SMSG_NEW_WORLD` so the server resumes its object
-    /// stream on the new continent (`MSG_MOVE_WORLDPORT_ACK` has an empty body).
+    /// `MSG_MOVE_WORLDPORT_ACK`, empty: confirms `SMSG_NEW_WORLD` so the object stream resumes.
     pub fn worldport_ack(&mut self) -> Result<()> {
         self.send(opcode::MSG_MOVE_WORLDPORT_ACK, &[])
     }
 
-    /// Answer a `SMSG_FORCE_*_SPEED_CHANGE` (`CMSG_FORCE_*_SPEED_CHANGE_ACK`, picked by `kind`):
-    /// echo the mover `guid` + `counter` + the exact `speed` the server sent, carrying our live
-    /// `MovementInfo` (same field set as [`Self::send_movement`] — the server relocates us to it).
-    /// Mandatory: unacked, the server force-resolves the change after ~4 s and flags its anticheat.
+    /// `CMSG_FORCE_*_SPEED_CHANGE_ACK`: echoes `counter` and the exact `speed` with our live pose,
+    /// which the server relocates us to. Unacked, it force-resolves after ~4 s and flags anticheat.
     pub fn force_speed_change_ack(
         &mut self,
         kind: messages::SpeedKind,
@@ -157,14 +120,8 @@ impl WorldWriter {
         )
     }
 
-    /// Echo a same-map teleport ack so the server completes the near-teleport **immediately**
-    /// (relocates us + streams the surrounding objects). Without a valid ack the teleport only
-    /// finishes on a ~20s server-side fallback, so the destination's objects appear ~20s late.
-    ///
-    /// vanilla 1.12 / vmangos expect a **full 8-byte guid** for this opcode (the lone movement opcode
-    /// that does — the `MovementInfo` ones are correctly packed). With a packed guid the server's
-    /// `ByteBuffer` overruns and drops the packet (confirmed by a vmangos capture: opcode `0xC7` →
-    /// `ByteBufferException`, then the teleport completing 20s later).
+    /// `MSG_MOVE_TELEPORT_ACK`: completes a near-teleport at once; without it the server finishes
+    /// on a ~20 s fallback. The guid is a full 8 bytes: a packed one overruns vmangos's reader.
     pub fn teleport_ack(&mut self, guid: u64, counter: u32) -> Result<()> {
         self.send(
             opcode::MSG_MOVE_TELEPORT_ACK,
@@ -172,19 +129,10 @@ impl WorldWriter {
         )
     }
 
-    /// **Acknowledge a granted mover mode** — root, water-walk, feather-fall or hover (the ack'd
-    /// family; decision 0866): full guid + the echoed counter + our current `MovementInfo`, plus the
-    /// trailing `u32 apply` for every mode but root ([`MoveMode::ack_carries_apply`]). Un-acked, the
-    /// server never applies the change and observers never see it; a wrong/zero counter trips its
-    /// cheat log (`HandleMoveRootAck`).
-    ///
-    /// `flags` is the caller's live wire word and must already carry the applied mode's bit. Two
-    /// server rules constrain it: an apply-ack without the bit is a KICK for root
-    /// (`HandleMoveRootAck:715`), and **moving bits must never accompany `MOVEFLAG_ROOT`** — they
-    /// freeze the real client (vmangos `MovementInfo.h`) and trip `CHEAT_TYPE_ROOT_MOVE`. Turn bits
-    /// are not moving bits (`MOVEFLAG_MASK_MOVING` excludes them) and are fine alongside root.
-    ///
-    /// `pose` is the mover's live `(position, orientation)` — the pair `World::self_pose` returns.
+    /// Ack a granted root, water-walk, feather-fall or hover: full guid, echoed counter and our
+    /// pose, plus a trailing `u32 apply` for all but root. Unacked, the server never applies it.
+    /// `flags` must carry the mode's bit (a root apply-ack without it is a kick, vmangos
+    /// `MovementHandler.cpp:722-729`) and no moving bit beside `MOVEFLAG_ROOT`; turn bits are fine.
     pub fn move_mode_ack(
         &mut self,
         guid: u64,
@@ -202,16 +150,9 @@ impl WorldWriter {
         )
     }
 
-    /// **Acknowledge the knockback we are now flying** (`CMSG_MOVE_KNOCK_BACK_ACK`, decision 1702):
-    /// full guid + the echoed counter + our `MovementInfo` at the moment of launch, whose jump tail
-    /// is the server's own `launch` quad echoed back.
-    ///
-    /// The echo is not politeness — it is the server's whole validation. `flags` must carry
-    /// `MOVEFLAG_JUMPING`, and `launch` must be bit-for-bit what arrived (vmangos matches all four
-    /// floats within `0.01`); miss either and `FindPendingMovementKnockbackChange` fails, the ack is
-    /// logged as `OnWrongAckData`, and no observer ever sees the knockback — the server builds their
-    /// `MSG_MOVE_KNOCK_BACK` from the `MovementInfo` sent here. `fall_time` is the launch's fresh
-    /// clock (0).
+    /// `CMSG_MOVE_KNOCK_BACK_ACK`: our pose at launch, with the server's `launch` echoed as the
+    /// jump tail. `flags` must carry `MOVEFLAG_JUMPING` and `launch` must match within 0.01, or
+    /// vmangos rejects the ack and observers never see the knockback.
     pub fn knock_back_ack(
         &mut self,
         guid: u64,
diff --git a/crates/benilla-protocol/src/world/writer/skills.rs b/crates/benilla-protocol/src/world/writer/skills.rs
index 5a944ab6..b48ca204 100644
--- a/crates/benilla-protocol/src/world/writer/skills.rs
+++ b/crates/benilla-protocol/src/world/writer/skills.rs
@@ -1,9 +1,4 @@
-//! The skills pane's `WorldWriter` send — one verb, mirroring [`crate::messages::skills`]: the
-//! abandon. Split out of `writer/mod.rs` (decision 0636).
-//!
-//! There is no "learn a skill" counterpart and no skill-up send: skills are granted server-side
-//! (by a trainer purchase, a quest, or a use-based tick) and arrive as `PLAYER_SKILL_INFO` field
-//! updates, so abandoning is the only skill verb the client ever initiates.
+//! The skills pane's one send, the abandon; skills are granted server-side as field updates.
 
 use anyhow::Result;
 
@@ -12,9 +7,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Unlearn a whole skill line (`CMSG_UNLEARN_SKILL`, layout in [`messages::unlearn_skill`]) —
-    /// the skills pane's abandon. No ack: the server's `SetSkill(id, 0, 0)` comes back as a
-    /// `PLAYER_SKILL_INFO` field update.
+    /// `CMSG_UNLEARN_SKILL`: no ack; the removal comes back as a `PLAYER_SKILL_INFO` update.
     pub fn unlearn_skill(&mut self, skill_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_UNLEARN_SKILL,
diff --git a/crates/benilla-protocol/src/world/writer/social.rs b/crates/benilla-protocol/src/world/writer/social.rs
index e5a76321..c342723a 100644
--- a/crates/benilla-protocol/src/world/writer/social.rs
+++ b/crates/benilla-protocol/src/world/writer/social.rs
@@ -1,10 +1,5 @@
-//! The social family's `WorldWriter` sends — friends, ignores, and `/who` (decision 0668).
-//!
-//! Note the asymmetry the wire imposes and the UI has to live with: you **add** by name and
-//! **remove** by guid (`CMSG_ADD_FRIEND` takes a cstring, `CMSG_DEL_FRIEND` a guid). That is not
-//! an inconsistency to paper over — it is why the client keeps both lists keyed by guid and
-//! resolves display names through the name cache (see [`crate::messages::social`]'s module doc).
-//! A "remove Bob" verb therefore has to find Bob's guid in the list *before* it can send anything.
+//! The social sends: friends, ignores and `/who`. The wire adds by name and removes by guid, so a
+//! removal must find the guid in the list first.
 
 use anyhow::Result;
 
@@ -13,21 +8,18 @@ use crate::messages::{self, opcode, WhoRequest};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask for the friend list again (`CMSG_FRIEND_LIST`, empty body) — the FrameXML's
-    /// `ShowFriends()`. The server also pushes it unasked at login, so this is a refresh, never
-    /// the only way the list arrives.
+    /// `CMSG_FRIEND_LIST`, empty: `ShowFriends()`'s refresh; the server also pushes it at login.
     pub fn friend_list(&mut self) -> Result<()> {
         self.send(opcode::CMSG_FRIEND_LIST, &messages::friend_list())
     }
 
-    /// Befriend a character by name (`CMSG_ADD_FRIEND`). The answer is an `SMSG_FRIEND_STATUS`
-    /// carrying one of the `FRIEND_ADDED_*` / refusal codes — never a silent success.
+    /// `CMSG_ADD_FRIEND`: always answered by `SMSG_FRIEND_STATUS`, `FRIEND_ADDED_*` or a refusal.
     pub fn add_friend(&mut self, name: &str) -> Result<()> {
         self.send(opcode::CMSG_ADD_FRIEND, &messages::add_friend(name))
     }
 
-    /// The client's LFG slots and comment (`CMSG_SET_LOOKING_FOR_GROUP`). Nothing answers it —
-    /// the reference has no handler for the opcode, and the readback is purely local (1961).
+    /// `CMSG_SET_LOOKING_FOR_GROUP`: the LFG slots and comment. vmangos leaves the opcode unhandled
+    /// (`Opcodes.cpp:603`), so the readback is local.
     pub fn set_looking_for_group(&mut self, slots: [u32; 3], comment: &str) -> Result<()> {
         self.send(
             opcode::CMSG_SET_LOOKING_FOR_GROUP,
@@ -50,9 +42,8 @@ impl WorldWriter {
         self.send(opcode::CMSG_DEL_IGNORE, &messages::del_ignore(guid))
     }
 
-    /// Run a `/who` (`CMSG_WHO`). The server answers at most one query per session at a time
-    /// (`ReceivedWhoRequest` gates it) and runs it as an async task, so the `SMSG_WHO` lands a
-    /// tick or two later — a second query fired while one is in flight is dropped, not queued.
+    /// `CMSG_WHO`: the server runs one query per session at a time, as an async task, so the reply
+    /// lags a tick or two and a second query sent meanwhile is dropped (`ReceivedWhoRequest`).
     pub fn who(&mut self, request: &WhoRequest) -> Result<()> {
         self.send(opcode::CMSG_WHO, &messages::who(request))
     }
diff --git a/crates/benilla-protocol/src/world/writer/spells.rs b/crates/benilla-protocol/src/world/writer/spells.rs
index 14452bf4..84e36c11 100644
--- a/crates/benilla-protocol/src/world/writer/spells.rs
+++ b/crates/benilla-protocol/src/world/writer/spells.rs
@@ -1,16 +1,5 @@
-//! The cast family's `WorldWriter` sends — the three `CMSG_CAST_SPELL` shapes (a unit or self, a
-//! GameObject, an item), plus the three cancels a cast can need: the in-flight cast, the channel,
-//! and the aura it left behind. Bodies in [`crate::messages::spells`], whose scope this mirrors;
-//! the two spell-id cancels are a bare `u32` written inline. Split out of `writer/mod.rs`
-//! (decision 0636), narrowed to the cast itself by decision 0640.
-//!
-//! 0636 kept auto-attack, the action bar and the talent spend here on the grounds that all of them
-//! are "the ability system's wire". That was the weakest grouping in it, and once 0640 split
-//! `messages/spells.rs` the mirror both allowed and recommended the finer cut: they are now
-//! [`super::attack`], [`super::action_bar`] and [`super::progression`].
-//!
-//! The aura cancel stays because the wire says it belongs to the spell, not to the aura:
-//! `CMSG_CANCEL_AURA` is addressed **by spell id, not by aura slot**.
+//! The cast sends: each `CMSG_CAST_SPELL` target shape, and the three cancels (cast, channel,
+//! aura), all addressed by spell id.
 
 use anyhow::Result;
 
@@ -19,9 +8,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Cast a spell (`CMSG_CAST_SPELL`): `target: None` = a self/implicit cast, `Some(guid)` = an
-    /// explicit unit target (body in [`messages::cast_spell`]). The server answers
-    /// `SMSG_CAST_RESULT` (and `SMSG_SPELL_START`/`GO` on success, unmodelled yet).
+    /// `CMSG_CAST_SPELL`: `None` is a self or implicit cast, `Some` a unit target; answered by
+    /// `SMSG_CAST_RESULT`.
     pub fn cast_spell(&mut self, spell_id: u32, target: Option<u64>) -> Result<()> {
         self.send(
             opcode::CMSG_CAST_SPELL,
@@ -29,19 +17,14 @@ impl WorldWriter {
         )
     }
 
-    /// Cancel one of our own auras (`CMSG_CANCEL_AURA`, body in [`messages::cancel_aura`]) — the
-    /// right-click-a-buff wire. Carries the **spell id**, not a slot; the server refuses passives,
-    /// no-cancel spells and debuffs (decision 0257). No answer packet — the removal arrives as a
-    /// `UNIT_FIELD_AURA` delta zeroing the slot.
+    /// `CMSG_CANCEL_AURA`: by spell id, not slot; the server refuses passives, no-cancel spells and
+    /// debuffs. No reply: the slot clears by a `UNIT_FIELD_AURA` delta.
     pub fn cancel_aura(&mut self, spell_id: u32) -> Result<()> {
         self.send(opcode::CMSG_CANCEL_AURA, &messages::cancel_aura(spell_id))
     }
 
-    /// Cast an OPEN_LOCK spell at a **GameObject** (`CMSG_CAST_SPELL`, body in
-    /// [`messages::cast_spell_gameobject`]) — the right-click on a locked chest / mining vein / herb
-    /// node (decision 0239). The server runs `EffectOpenLock` → for a chest, opens the loot
-    /// (`SMSG_LOOT_RESPONSE`); the profession/skill gate is the server's. Answered by
-    /// `SMSG_CAST_RESULT` on refusal.
+    /// `CMSG_CAST_SPELL` at a GameObject: the open-lock cast on a chest, vein or herb. The server
+    /// checks the skill, and a chest answers with its loot.
     pub fn cast_spell_gameobject(&mut self, spell_id: u32, go_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_CAST_SPELL,
@@ -49,10 +32,8 @@ impl WorldWriter {
         )
     }
 
-    /// Cast an item-targeted spell (`CMSG_CAST_SPELL` with `TARGET_FLAG_ITEM` + the item's packed
-    /// guid — [`messages::cast_spell_item`]): the enchant cast the CraftFrame's item pick
-    /// completes (decision 0437 phase 3). The server resolves the item, checks reagents, applies
-    /// the enchant; refusal answers `SMSG_CAST_RESULT`.
+    /// `CMSG_CAST_SPELL` with `TARGET_FLAG_ITEM` and the item's packed guid: an enchant on the item
+    /// picked in the craft frame.
     pub fn cast_spell_item(&mut self, spell_id: u32, item_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_CAST_SPELL,
@@ -60,10 +41,8 @@ impl WorldWriter {
         )
     }
 
-    /// Cast a spell at a **ground point** (`CMSG_CAST_SPELL` with `TARGET_FLAG_DEST_LOCATION` +
-    /// the destination Vec3 in WoW world coords — [`messages::cast_spell_at_dest`]): the
-    /// targeting-cursor commit for a ground-targeted AOE (decision 0792). The server range/LOS
-    /// checks the point in `Spell::CheckCast`; refusal answers `SMSG_CAST_RESULT`.
+    /// `CMSG_CAST_SPELL` with `TARGET_FLAG_DEST_LOCATION`: a ground-targeted spell at a world
+    /// point; the server checks range and line of sight (`Spell::CheckCast`).
     pub fn cast_spell_at_dest(&mut self, spell_id: u32, dest: [f32; 3]) -> Result<()> {
         self.send(
             opcode::CMSG_CAST_SPELL,
@@ -71,10 +50,8 @@ impl WorldWriter {
         )
     }
 
-    /// Cast a spell at a **source point** (`CMSG_CAST_SPELL` with `TARGET_FLAG_SOURCE_LOCATION` +
-    /// the Vec3 in WoW world coords — [`messages::cast_spell_at_source`]): the targeting-cursor
-    /// commit for a `Targets & 0x20` spell (decision 2218). The dest verb's twin, one bit over;
-    /// the server centres the AoE on the point it carries.
+    /// `CMSG_CAST_SPELL` with `TARGET_FLAG_SOURCE_LOCATION`, for a `Targets & 0x20` spell; the
+    /// server centres the area effect on `src`, a world point.
     pub fn cast_spell_at_source(&mut self, spell_id: u32, src: [f32; 3]) -> Result<()> {
         self.send(
             opcode::CMSG_CAST_SPELL,
@@ -82,16 +59,14 @@ impl WorldWriter {
         )
     }
 
-    /// Cancel a named in-flight cast (`CMSG_CANCEL_CAST`: one `u32` spell id — vmangos
-    /// `HandleCancelCastOpcode`). Sent by the wand-only auto-repeat handoff (`0x6095b8`) and by
-    /// the cast bar's local self-cancel (movement/Esc mid-cast, `benilla::ui_cast`).
+    /// `CMSG_CANCEL_CAST`, one `u32` spell id: sent by the wand auto-repeat handoff (reference:
+    /// `0x6095b8`) and when movement or Esc cancels a cast.
     pub fn cancel_cast(&mut self, spell_id: u32) -> Result<()> {
         self.send(opcode::CMSG_CANCEL_CAST, &spell_id.to_le_bytes())
     }
 
-    /// End our own running channel (`CMSG_CANCEL_CHANNELLING`: one `u32` spell id, which vmangos
-    /// reads and ignores — the interrupt is unconditional; the real client still writes it). The
-    /// channel half of the local self-cancel (`benilla::ui_cast`).
+    /// `CMSG_CANCEL_CHANNELLING`: the 1.12 client writes the spell id, which vmangos ignores,
+    /// interrupting unconditionally.
     pub fn cancel_channelling(&mut self, spell_id: u32) -> Result<()> {
         self.send(opcode::CMSG_CANCEL_CHANNELLING, &spell_id.to_le_bytes())
     }
diff --git a/crates/benilla-protocol/src/world/writer/stable.rs b/crates/benilla-protocol/src/world/writer/stable.rs
index 91496025..49c8bc41 100644
--- a/crates/benilla-protocol/src/world/writer/stable.rs
+++ b/crates/benilla-protocol/src/world/writer/stable.rs
@@ -1,17 +1,6 @@
-//! The stable window's `WorldWriter` sends — the list refresh and the four mutations. Bodies in
-//! [`crate::messages::stable`], whose scope this mirrors.
-//!
-//! **Every verb names the stable master's guid**, because the server re-checks the interaction on
-//! each one (`WorldSession::CheckStableMaster`, VERIFIED vmangos `NPCHandler.cpp:584-607`): the guid
-//! must be an NPC with `UNIT_NPC_FLAG_STABLEMASTER` that the player can still interact with. A
-//! window left open while the player walks away therefore fails every button with
-//! [`messages::stable_result::ERR_STABLE`] rather than acting at a distance — which is why the app
-//! side range-guards the session rather than trusting the open window.
-//!
-//! **None of the four mutations is answered with a fresh list** — only a one-byte
-//! `SMSG_STABLE_RESULT` (VERIFIED: every `HandleStable*` path ends in `SendStableResult` and
-//! nothing else). So a success is a cue to re-ask with [`WorldWriter::list_stabled_pets`], the same
-//! shape as the trainer's post-purchase re-request.
+//! The stable window's sends. Each names the stable master, whose reach the server re-checks
+//! (`NPCHandler.cpp:584`), so an out-of-range window fails with `ERR_STABLE`. A mutation is
+//! answered only by a one-byte `SMSG_STABLE_RESULT`; on success, re-ask for the list.
 
 use anyhow::Result;
 
@@ -20,13 +9,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask (or re-ask) a stable master's pet list (`MSG_LIST_STABLED_PETS`, layout in
-    /// [`messages::list_stabled_pets`]) — one 8-byte NPC guid.
-    ///
-    /// This is the *refresh* verb. The window first *opens* off the server's own unprompted send of
-    /// the same opcode, which the gossip stable option produces (`GOSSIP_OPTION_STABLEPET` →
-    /// `SendStablePet`, VERIFIED vmangos `Player.cpp:12400-12402`) — exactly the trainer's and the
-    /// vendor's arrangement. Answered by `MSG_LIST_STABLED_PETS` inbound.
+    /// `MSG_LIST_STABLED_PETS`: the refresh; the window first opens on the server's unasked send
+    /// from the gossip stable option (`Player.cpp:12400`).
     pub fn list_stabled_pets(&mut self, npc_guid: u64) -> Result<()> {
         self.send(
             opcode::MSG_LIST_STABLED_PETS,
@@ -34,25 +18,14 @@ impl WorldWriter {
         )
     }
 
-    /// Put the current pet into a stable slot (`CMSG_STABLE_PET`, layout in
-    /// [`messages::stable_pet`]): the NPC guid alone.
-    ///
-    /// **There is no slot to name** — the server takes the first free one and refuses if that index
-    /// exceeds the slots the player has bought (`HandleStablePet`, VERIFIED `NPCHandler.cpp:609-655`).
-    /// Answers [`messages::stable_result::SUCCESS_STABLE`], or `ERR_STABLE` when the player is dead,
-    /// has no live hunter pet, or has no free bought slot.
+    /// `CMSG_STABLE_PET`: the server picks the first free bought slot (`NPCHandler.cpp:609`);
+    /// a dead player, no live hunter pet or no free slot gets `ERR_STABLE`.
     pub fn stable_pet(&mut self, npc_guid: u64) -> Result<()> {
         self.send(opcode::CMSG_STABLE_PET, &messages::stable_pet(npc_guid))
     }
 
-    /// Summon a stabled pet as the current pet (`CMSG_UNSTABLE_PET`, layout in
-    /// [`messages::unstable_pet`]): the NPC guid + the pet's own
-    /// [`messages::StabledPet::pet_number`], never its slot.
-    ///
-    /// Only valid with **no** current pet — vmangos refuses even when the existing pet is merely
-    /// unsummoned and out of range (`HandleUnstablePet`, VERIFIED `NPCHandler.cpp:657-702`). With a
-    /// pet already out, the verb is [`Self::stable_swap_pet`]. Answers
-    /// [`messages::stable_result::SUCCESS_UNSTABLE`] or `ERR_STABLE`.
+    /// `CMSG_UNSTABLE_PET`: by `pet_number`, never slot. vmangos refuses it while any current pet
+    /// exists, even an unsummoned one (`NPCHandler.cpp:657`); with a pet out, swap instead.
     pub fn unstable_pet(&mut self, npc_guid: u64, pet_number: u32) -> Result<()> {
         self.send(
             opcode::CMSG_UNSTABLE_PET,
@@ -60,14 +33,8 @@ impl WorldWriter {
         )
     }
 
-    /// Trade the current pet for a stabled one in a single step (`CMSG_STABLE_SWAP_PET`, layout in
-    /// [`messages::stable_swap_pet`]): the NPC guid + the stabled pet's
-    /// [`messages::StabledPet::pet_number`].
-    ///
-    /// The current pet goes into the slot the named pet vacates (`HandleStableSwapPet`, VERIFIED
-    /// `NPCHandler.cpp:735-789`). Requires a live hunter pet to be out. Answers
-    /// [`messages::stable_result::SUCCESS_UNSTABLE`] — the *same* code a plain unstable returns, so
-    /// the reply cannot tell the two verbs apart.
+    /// `CMSG_STABLE_SWAP_PET`: the live pet takes the named pet's slot (`NPCHandler.cpp:735`).
+    /// Success is `SUCCESS_UNSTABLE`, the same code as a plain unstable.
     pub fn stable_swap_pet(&mut self, npc_guid: u64, pet_number: u32) -> Result<()> {
         self.send(
             opcode::CMSG_STABLE_SWAP_PET,
@@ -75,15 +42,9 @@ impl WorldWriter {
         )
     }
 
-    /// Buy the next stable slot (`CMSG_BUY_STABLE_SLOT`, layout in
-    /// [`messages::buy_stable_slot`]): the NPC guid alone.
-    ///
-    /// The *which* is implicit, exactly as it is for the bank's bag slots (decision 0604): the
-    /// server buys `m_stableSlots + 1` and prices it from `StableSlotPrices.dbc` at that row
-    /// (`HandleBuyStableSlot`, VERIFIED `NPCHandler.cpp:704-729`). Answers
-    /// [`messages::stable_result::SUCCESS_BUY_SLOT`], `ERR_MONEY`, or — past the two slots 5875
-    /// ships — `ERR_STABLE`. No packet reports the new count: the next list's `num_stable_slots`
-    /// does.
+    /// `CMSG_BUY_STABLE_SLOT`: the server buys the next slot at its `StableSlotPrices.dbc` price
+    /// (`NPCHandler.cpp:704`); past the two 1.12 slots it answers `ERR_STABLE`. Only the next
+    /// list carries the new count.
     pub fn buy_stable_slot(&mut self, npc_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_BUY_STABLE_SLOT,
diff --git a/crates/benilla-protocol/src/world/writer/summon.rs b/crates/benilla-protocol/src/world/writer/summon.rs
index d755cbbd..15ca1e57 100644
--- a/crates/benilla-protocol/src/world/writer/summon.rs
+++ b/crates/benilla-protocol/src/world/writer/summon.rs
@@ -1,9 +1,5 @@
-//! The summon answer — the client's one send in the summon family (decision 1747).
-//!
-//! There is no "summon me" verb and no decline verb: the flow starts with the *server's*
-//! `SMSG_SUMMON_REQUEST` (a warlock's ritual, a meeting stone, a GM) and this is the Yes.
-//! Declining is silence — the server auto-declines when its own two-minute window runs out — which
-//! is why this file has exactly one function and its twin does not exist.
+//! The summon accept, the client's one summon send. Declining sends nothing: the server's
+//! two-minute window lapses.
 
 use anyhow::Result;
 
@@ -12,12 +8,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Accept a summon (`CMSG_SUMMON_RESPONSE`) — the `CONFIRM_SUMMON` dialog's Accept, carrying
-    /// the guid the question arrived with.
-    ///
-    /// The server answers by teleporting us to the summon point it recorded when it asked. It does
-    /// **not** check the guid (vmangos reads it and calls `Player::SummonIfPossible(true)` off its
-    /// own `m_summon_expire`), so what makes a late accept harmless is that timer, not this field.
+    /// `CMSG_SUMMON_RESPONSE`: the `CONFIRM_SUMMON` Accept. vmangos ignores the guid and teleports
+    /// us unless its own `m_summon_expire` has passed (`Player::SummonIfPossible`).
     pub fn summon_response(&mut self, summoner_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_SUMMON_RESPONSE,
diff --git a/crates/benilla-protocol/src/world/writer/tabard.rs b/crates/benilla-protocol/src/world/writer/tabard.rs
index 5502dda4..36ef37a5 100644
--- a/crates/benilla-protocol/src/world/writer/tabard.rs
+++ b/crates/benilla-protocol/src/world/writer/tabard.rs
@@ -1,4 +1,4 @@
-//! The tabard designer's senders (decision 1977; bodies in [`crate::messages::tabard`]).
+//! The tabard designer's sends, and the battlemaster greeting.
 
 use anyhow::Result;
 
@@ -7,7 +7,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// `MSG_TABARDVENDOR_ACTIVATE` out — the NPC-click ladder's TABARDDESIGNER arm.
+    /// `MSG_TABARDVENDOR_ACTIVATE`: the NPC-click ladder's `TABARDDESIGNER` arm.
     pub fn tabard_vendor_activate(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::MSG_TABARDVENDOR_ACTIVATE,
@@ -15,7 +15,7 @@ impl WorldWriter {
         )
     }
 
-    /// `MSG_SAVE_GUILD_EMBLEM` out — `TabardModel:Save()` past its fourteen pre-flight checks.
+    /// `MSG_SAVE_GUILD_EMBLEM`: `TabardModel:Save()`, once its fourteen client-side checks pass.
     pub fn save_guild_emblem(&mut self, vendor: u64, design: [u32; 5]) -> Result<()> {
         self.send(
             opcode::MSG_SAVE_GUILD_EMBLEM,
@@ -23,7 +23,7 @@ impl WorldWriter {
         )
     }
 
-    /// `CMSG_BATTLEMASTER_HELLO` — the ladder's BATTLEMASTER arm.
+    /// `CMSG_BATTLEMASTER_HELLO`: the NPC-click ladder's `BATTLEMASTER` arm.
     pub fn battlemaster_hello(&mut self, npc: u64) -> Result<()> {
         self.send(
             opcode::CMSG_BATTLEMASTER_HELLO,
diff --git a/crates/benilla-protocol/src/world/writer/taxi.rs b/crates/benilla-protocol/src/world/writer/taxi.rs
index 1975f66d..3f88dfd9 100644
--- a/crates/benilla-protocol/src/world/writer/taxi.rs
+++ b/crates/benilla-protocol/src/world/writer/taxi.rs
@@ -1,10 +1,5 @@
-//! The flight-master family's `WorldWriter` sends — the known-status probe, the map open, and the
-//! two flight verbs. Bodies in [`crate::messages::taxi`], whose scope this mirrors. Split out of
-//! `writer/mod.rs` (decision 0636).
-//!
-//! Two flight opcodes, one discriminator (decision 0496 §TU-3): send `CMSG_ACTIVATETAXI` when a
-//! direct `TaxiPath` edge exists current→target, and `CMSG_ACTIVATETAXIEXPRESS` with the whole node
-//! chain when it doesn't — the real rule the verdict corrected from a hop-count guess. Both answer
+//! The flight master's sends. A flight is `CMSG_ACTIVATETAXI` when a direct `TaxiPath` edge joins
+//! the two nodes, else `CMSG_ACTIVATETAXIEXPRESS` with the whole chain; both are answered by
 //! `SMSG_ACTIVATETAXIREPLY`.
 
 use anyhow::Result;
@@ -14,9 +9,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask a nearby flight master's known status (`CMSG_TAXINODE_STATUS_QUERY`, layout in
-    /// [`messages::taxi_node_status_query`]): the flight master's guid, not ours. Answered by
-    /// `SMSG_TAXINODE_STATUS` (a `TaxiNodeStatus` event, decision 0484).
+    /// `CMSG_TAXINODE_STATUS_QUERY`: whether we know a nearby flight master's node; answered by
+    /// `SMSG_TAXINODE_STATUS`.
     pub fn taxi_node_status_query(&mut self, flightmaster_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_TAXINODE_STATUS_QUERY,
@@ -24,12 +18,8 @@ impl WorldWriter {
         )
     }
 
-    /// Open a flight master's taxi map (`CMSG_TAXIQUERYAVAILABLENODES`, layout in
-    /// [`messages::taxi_query_available_nodes`], decision 0496 I4 — CONFIRMED as built: the
-    /// interact ladder is first-match-wins low→high over `UNIT_NPC_FLAGS`, so only a pure
-    /// flightmaster reaches here). A known node answers `SMSG_SHOWTAXINODES` (a `TaxiNodesShown`
-    /// event); a never-visited node instead answers the first-visit learn pair (`NewTaxiPath` +
-    /// `TaxiNodeStatus`) and opens no menu on this click.
+    /// `CMSG_TAXIQUERYAVAILABLENODES`: a known node answers `SMSG_SHOWTAXINODES`; a new node
+    /// answers with the first-visit learn pair instead, and no map opens on that click.
     pub fn taxi_query_available_nodes(&mut self, flightmaster_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_TAXIQUERYAVAILABLENODES,
@@ -37,9 +27,7 @@ impl WorldWriter {
         )
     }
 
-    /// Fly a single hop (`CMSG_ACTIVATETAXI`, layout in [`messages::activate_taxi`]): the
-    /// flight-master guid, the source node, the destination node. Answered by
-    /// `SMSG_ACTIVATETAXIREPLY`; success continues into the mount + `SMSG_MONSTER_MOVE` flight.
+    /// `CMSG_ACTIVATETAXI`: one hop; success mounts us and flies an `SMSG_MONSTER_MOVE` path.
     pub fn activate_taxi(
         &mut self,
         flightmaster_guid: u64,
@@ -52,11 +40,7 @@ impl WorldWriter {
         )
     }
 
-    /// Fly a multi-hop chain in one send (`CMSG_ACTIVATETAXIEXPRESS`, layout in
-    /// [`messages::activate_taxi_express`], decision 0496 §TU-3 — sent when no direct `TaxiPath`
-    /// edge exists current→target, the real discriminator the verdict corrected from a hop-count
-    /// guess): the flight-master guid, the route's combined fare, and the full node chain in
-    /// order. Answered by `SMSG_ACTIVATETAXIREPLY`, same as [`Self::activate_taxi`].
+    /// `CMSG_ACTIVATETAXIEXPRESS`: the route's combined fare and its whole node chain, in order.
     pub fn activate_taxi_express(
         &mut self,
         flightmaster_guid: u64,
diff --git a/crates/benilla-protocol/src/world/writer/trade.rs b/crates/benilla-protocol/src/world/writer/trade.rs
index 1062c61b..3a052d33 100644
--- a/crates/benilla-protocol/src/world/writer/trade.rs
+++ b/crates/benilla-protocol/src/world/writer/trade.rs
@@ -1,8 +1,4 @@
-//! The player-trade arc's `WorldWriter` sends (decision 0592 P0): initiate, the auto-`BEGIN_TRADE`
-//! reply, the decline pair (busy/ignore), set/clear an item, set gold, and accept/unaccept/cancel.
-//! Bodies in [`crate::messages`]'s `trade` builders (layout VERIFIED against vmangos
-//! `Handlers/TradeHandler.cpp` + `Server/Packets/Trade.cpp`). Split out of `writer/mod.rs` the same
-//! way `channel`/`group`/`mail` are — one clearly separable concern among the writer's domains.
+//! The player trade sends.
 
 use anyhow::Result;
 
@@ -11,9 +7,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Open a trade with another player (`CMSG_INITIATE_TRADE`, layout in
-    /// [`messages::initiate_trade`]): the target's guid. The server answers us on any refusal
-    /// (`SMSG_TRADE_STATUS`) and, on success, sends the *target* a `BEGIN_TRADE`.
+    /// `CMSG_INITIATE_TRADE`: the target gets `BEGIN_TRADE`; we hear back only on a refusal.
     pub fn initiate_trade(&mut self, target: u64) -> Result<()> {
         self.send(
             opcode::CMSG_INITIATE_TRADE,
@@ -21,27 +15,23 @@ impl WorldWriter {
         )
     }
 
-    /// Acknowledge a received `BEGIN_TRADE` (`CMSG_BEGIN_TRADE`, EMPTY body) — the client's
-    /// automatic reply that makes the server emit `OPEN_WINDOW` to both sides.
+    /// `CMSG_BEGIN_TRADE`, empty: the automatic reply to `BEGIN_TRADE`, after which the server
+    /// sends both sides `OPEN_WINDOW`.
     pub fn begin_trade(&mut self) -> Result<()> {
         self.send(opcode::CMSG_BEGIN_TRADE, &[])
     }
 
-    /// Decline a trade request as busy (`CMSG_BUSY_TRADE`, EMPTY body) — the server cancels it with
-    /// `TRADE_STATUS_BUSY` to the initiator.
+    /// `CMSG_BUSY_TRADE`, empty: the initiator gets `TRADE_STATUS_BUSY`.
     pub fn busy_trade(&mut self) -> Result<()> {
         self.send(opcode::CMSG_BUSY_TRADE, &[])
     }
 
-    /// Decline a trade request as ignored (`CMSG_IGNORE_TRADE`, EMPTY body) — the server cancels it
-    /// with `TRADE_STATUS_IGNORE_YOU` to the initiator.
+    /// `CMSG_IGNORE_TRADE`, empty: the initiator gets `TRADE_STATUS_IGNORE_YOU`.
     pub fn ignore_trade(&mut self) -> Result<()> {
         self.send(opcode::CMSG_IGNORE_TRADE, &[])
     }
 
-    /// Put a bag item into a trade slot (`CMSG_SET_TRADE_ITEM`, layout in
-    /// [`messages::set_trade_item`]): the trade slot, and the item's inventory `bag`/`slot`.
-    /// Clears the partner's accept and re-arms the 200 ms scam-prevention delay server-side.
+    /// `CMSG_SET_TRADE_ITEM`: clears the partner's accept and re-arms the server's 200 ms delay.
     pub fn set_trade_item(&mut self, trade_slot: u8, bag: u8, slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_SET_TRADE_ITEM,
@@ -49,8 +39,7 @@ impl WorldWriter {
         )
     }
 
-    /// Remove an item from a trade slot (`CMSG_CLEAR_TRADE_ITEM`, layout in
-    /// [`messages::clear_trade_item`]): the trade slot.
+    /// `CMSG_CLEAR_TRADE_ITEM`: empty one trade slot.
     pub fn clear_trade_item(&mut self, trade_slot: u8) -> Result<()> {
         self.send(
             opcode::CMSG_CLEAR_TRADE_ITEM,
@@ -58,8 +47,7 @@ impl WorldWriter {
         )
     }
 
-    /// Set the gold we are offering (`CMSG_SET_TRADE_GOLD`, layout in [`messages::set_trade_gold`]):
-    /// copper. Clears the partner's accept and re-arms the scam-prevention delay server-side.
+    /// `CMSG_SET_TRADE_GOLD`, in copper: clears the partner's accept and re-arms the 200 ms delay.
     pub fn set_trade_gold(&mut self, copper: u32) -> Result<()> {
         self.send(
             opcode::CMSG_SET_TRADE_GOLD,
@@ -67,20 +55,18 @@ impl WorldWriter {
         )
     }
 
-    /// Press Trade (`CMSG_ACCEPT_TRADE`, layout in [`messages::accept_trade`]) — accepting within
-    /// 200 ms of the last change is bounced by the server as `TRADE_STATUS_BACK_TO_TRADE`; when
-    /// both sides have accepted and the checks pass, the server swaps and sends both `COMPLETE`.
+    /// `CMSG_ACCEPT_TRADE`: bounced (`TRADE_STATUS_BACK_TO_TRADE`) within 200 ms of a change; once
+    /// both sides accept, the server swaps and sends both `COMPLETE`.
     pub fn accept_trade(&mut self) -> Result<()> {
         self.send(opcode::CMSG_ACCEPT_TRADE, &messages::accept_trade())
     }
 
-    /// Un-press Trade (`CMSG_UNACCEPT_TRADE`, EMPTY body) — drops our accept back to editing.
+    /// `CMSG_UNACCEPT_TRADE`, empty: withdraws our accept.
     pub fn unaccept_trade(&mut self) -> Result<()> {
         self.send(opcode::CMSG_UNACCEPT_TRADE, &[])
     }
 
-    /// Cancel the trade (`CMSG_CANCEL_TRADE`, EMPTY body) — the Close/Cancel path; the server
-    /// unwinds both sides with `TRADE_STATUS_TRADE_CANCELED`.
+    /// `CMSG_CANCEL_TRADE`, empty: both sides get `TRADE_STATUS_TRADE_CANCELED`.
     pub fn cancel_trade(&mut self) -> Result<()> {
         self.send(opcode::CMSG_CANCEL_TRADE, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/trainer.rs b/crates/benilla-protocol/src/world/writer/trainer.rs
index 1e306c75..5a6b544b 100644
--- a/crates/benilla-protocol/src/world/writer/trainer.rs
+++ b/crates/benilla-protocol/src/world/writer/trainer.rs
@@ -1,11 +1,4 @@
-//! The trainer window's `WorldWriter` sends — the service-list refresh and the purchase. Bodies in
-//! [`crate::messages::trainer`], whose scope this mirrors. Split out of `writer/mod.rs`
-//! (decision 0636).
-//!
-//! [`WorldWriter::trainer_list`] is the *refresh* verb, not the open: the window first appears off
-//! the gossip trainer option's own `SMSG_TRAINER_LIST`. It exists because the server does **not**
-//! auto-resend the list after a purchase (VERIFIED vmangos `NPCHandler.cpp:92-95`), so repainting
-//! the bought row green→gray takes a standalone re-request.
+//! The trainer window's sends: the list refresh and the purchase.
 
 use anyhow::Result;
 
@@ -14,13 +7,8 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask (or re-ask) a trainer's service list (`CMSG_TRAINER_LIST`, layout in
-    /// [`messages::trainer_list`]) — one 8-byte trainer guid. The window first *opens* off the
-    /// gossip trainer option's `SMSG_TRAINER_LIST`; this is the *refresh* verb, re-requested after a
-    /// purchase to repaint the bought row green→gray (vmangos `HandleTrainerListOpcode` honors a
-    /// standalone re-request while the player can still interact — VERIFIED `NPCHandler.cpp:92-95`,
-    /// the server does not auto-resend on a buy). Answered by `SMSG_TRAINER_LIST` (a `TrainerList`
-    /// event).
+    /// `CMSG_TRAINER_LIST`: the refresh after a purchase, which the server does not resend
+    /// (`NPCHandler.cpp:92`); the window first opens from the gossip option.
     pub fn trainer_list(&mut self, trainer_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_TRAINER_LIST,
@@ -28,11 +16,8 @@ impl WorldWriter {
         )
     }
 
-    /// Buy (learn) a trainer service (`CMSG_TRAINER_BUY_SPELL`, layout in
-    /// [`messages::trainer_buy_spell`]): the trainer guid + the service's spell id. Success answers
-    /// `SMSG_TRAINER_BUY_SUCCEEDED` and delivers the spell via the learn effect's `SMSG_LEARNED_SPELL`
-    /// (the green→gray repaint then needs a `CMSG_TRAINER_LIST` re-request); refusal answers
-    /// `SMSG_TRAINER_BUY_FAILED` with a [`messages::train_fail`] code.
+    /// `CMSG_TRAINER_BUY_SPELL`: answered by `SMSG_TRAINER_BUY_SUCCEEDED` and `SMSG_LEARNED_SPELL`,
+    /// or by `SMSG_TRAINER_BUY_FAILED` with a [`messages::train_fail`] code.
     pub fn trainer_buy_spell(&mut self, trainer_guid: u64, spell_id: u32) -> Result<()> {
         self.send(
             opcode::CMSG_TRAINER_BUY_SPELL,
diff --git a/crates/benilla-protocol/src/world/writer/tutorial.rs b/crates/benilla-protocol/src/world/writer/tutorial.rs
index 44be9e43..d223a3c4 100644
--- a/crates/benilla-protocol/src/world/writer/tutorial.rs
+++ b/crates/benilla-protocol/src/world/writer/tutorial.rs
@@ -1,4 +1,4 @@
-//! The tutorial system's sends (decision 1976).
+//! The tutorial system's sends.
 
 use anyhow::Result;
 
@@ -7,18 +7,18 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Acknowledge one tutorial (`CMSG_TUTORIAL_FLAG`): the 0-based id — `FlagTutorial`'s and the
-    /// six auto-acknowledge sites' packet, sent only when the acknowledged bank's bit was clear.
+    /// `CMSG_TUTORIAL_FLAG`, a 0-based id: sent by `FlagTutorial` and six auto-acknowledge sites,
+    /// only when that tutorial's bit was clear.
     pub fn tutorial_flag(&mut self, id: u32) -> Result<()> {
         self.send(opcode::CMSG_TUTORIAL_FLAG, &messages::tutorial_flag(id))
     }
 
-    /// Mark every tutorial acknowledged (`CMSG_TUTORIAL_CLEAR`, empty) — `ClearTutorials()`.
+    /// `CMSG_TUTORIAL_CLEAR`, empty: `ClearTutorials()`, marking every tutorial acknowledged.
     pub fn tutorial_clear(&mut self) -> Result<()> {
         self.send(opcode::CMSG_TUTORIAL_CLEAR, &[])
     }
 
-    /// Forget every tutorial (`CMSG_TUTORIAL_RESET`, empty) — `ResetTutorials()`.
+    /// `CMSG_TUTORIAL_RESET`, empty: `ResetTutorials()`, forgetting every tutorial.
     pub fn tutorial_reset(&mut self) -> Result<()> {
         self.send(opcode::CMSG_TUTORIAL_RESET, &[])
     }
diff --git a/crates/benilla-protocol/src/world/writer/vendor.rs b/crates/benilla-protocol/src/world/writer/vendor.rs
index aaf61b80..6d5fac8c 100644
--- a/crates/benilla-protocol/src/world/writer/vendor.rs
+++ b/crates/benilla-protocol/src/world/writer/vendor.rs
@@ -1,12 +1,5 @@
-//! The vendor window's `WorldWriter` sends — list the stock, buy, sell, buy back, repair. Bodies in
-//! [`crate::messages::vendor`], whose scope this mirrors. Split out of `writer/mod.rs`
-//! (decision 0636).
-//!
-//! Note the two different item identities the family uses: buying names the item **template
-//! entry** (not the vendor row's `muid`), while selling and repairing name the **item guid** of the
-//! thing in our bags, and buyback names an absolute player-array slot 69–80. Only the two failures
-//! answer with a packet (`SMSG_BUY_FAILED` / `SMSG_SELL_ITEM`'s error shape); every success is
-//! ordinary `UPDATE_OBJECT` traffic.
+//! The vendor sends. Buying names an item template entry, not the vendor row's `muid`; selling and
+//! repairing name the item guid in our bags.
 
 use anyhow::Result;
 
@@ -15,9 +8,7 @@ use crate::messages::{self, opcode};
 use super::WorldWriter;
 
 impl WorldWriter {
-    /// Ask a vendor's stock (`CMSG_LIST_INVENTORY`, layout in [`messages::list_inventory`]) — the
-    /// server requires `UNIT_NPC_FLAG_VENDOR` + the player alive (`ItemHandler.cpp:693`). Answered
-    /// by `SMSG_LIST_INVENTORY` (a `VendorInventory` event).
+    /// `CMSG_LIST_INVENTORY`: needs `UNIT_NPC_FLAG_VENDOR` and us alive (`ItemHandler.cpp:693`).
     pub fn list_inventory(&mut self, vendor_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_LIST_INVENTORY,
@@ -25,10 +16,8 @@ impl WorldWriter {
         )
     }
 
-    /// Buy from a vendor (`CMSG_BUY_ITEM`, layout in [`messages::buy_item`]): `entry` is the item
-    /// **template** id (not the vendor row's `muid`), `count` the number of stacks. Auto-places
-    /// into the first free bag slot. Success updates the vendor stock (`SMSG_BUY_ITEM`) and
-    /// delivers the item via the normal item-create path; refusal answers `SMSG_BUY_FAILED`.
+    /// `CMSG_BUY_ITEM`: `count` stacks into the first free bag slot; answered by `SMSG_BUY_ITEM`
+    /// with the new stock, or by `SMSG_BUY_FAILED`.
     pub fn buy_item(&mut self, vendor_guid: u64, entry: u32, count: u8) -> Result<()> {
         self.send(
             opcode::CMSG_BUY_ITEM,
@@ -36,10 +25,8 @@ impl WorldWriter {
         )
     }
 
-    /// Buy into a **named** container slot (`CMSG_BUY_ITEM_IN_SLOT`, layout in
-    /// [`messages::buy_item_in_slot`]) — the merchant cursor's drop, as against [`Self::buy_item`]'s
-    /// auto-place from a row click. `bag_guid` is the container object's guid, or the player's own
-    /// for the backpack and the equipment slots.
+    /// `CMSG_BUY_ITEM_IN_SLOT`: the merchant cursor's drop. `bag_guid` is the container's guid, or
+    /// the player's own for the backpack and the equipment slots.
     pub fn buy_item_in_slot(
         &mut self,
         vendor_guid: u64,
@@ -54,10 +41,8 @@ impl WorldWriter {
         )
     }
 
-    /// Sell an item to a vendor (`CMSG_SELL_ITEM`, layout in [`messages::sell_item`]): `count` 0 =
-    /// sell the whole stack. Success is silent (the item vanishes + coinage rises via
-    /// `UPDATE_OBJECT`); refusal answers `SMSG_SELL_ITEM`'s error shape (a `VendorSellFailed`
-    /// event).
+    /// `CMSG_SELL_ITEM`: `count` 0 sells the whole stack. Success is silent; a refusal comes back
+    /// as `SMSG_SELL_ITEM`'s error shape.
     pub fn sell_item(&mut self, vendor_guid: u64, item_guid: u64, count: u8) -> Result<()> {
         self.send(
             opcode::CMSG_SELL_ITEM,
@@ -65,9 +50,8 @@ impl WorldWriter {
         )
     }
 
-    /// Buy a sold item back (`CMSG_BUYBACK_ITEM`, layout in [`messages::buyback_item`]): `slot` is
-    /// the absolute player-array buyback slot 69–80. Success is the item re-creating + coinage
-    /// falling via `UPDATE_OBJECT`; refusal answers `SMSG_BUY_FAILED`.
+    /// `CMSG_BUYBACK_ITEM`: `slot` is the absolute player-array buyback slot, 69 to 80; a refusal
+    /// is `SMSG_BUY_FAILED`.
     pub fn buyback_item(&mut self, vendor_guid: u64, slot: u32) -> Result<()> {
         self.send(
             opcode::CMSG_BUYBACK_ITEM,
@@ -75,9 +59,7 @@ impl WorldWriter {
         )
     }
 
-    /// Repair at a repair-capable vendor (`CMSG_REPAIR_ITEM`, layout in
-    /// [`messages::repair_item`]): `item_guid` 0 = repair everything. No dedicated answer packet —
-    /// durability rises + coinage falls via `UPDATE_OBJECT`.
+    /// `CMSG_REPAIR_ITEM`: `item_guid` 0 repairs everything; there is no reply packet.
     pub fn repair_item(&mut self, vendor_guid: u64, item_guid: u64) -> Result<()> {
         self.send(
             opcode::CMSG_REPAIR_ITEM,
diff --git a/crates/benilla-protocol/tests/auction.rs b/crates/benilla-protocol/tests/auction.rs
index 67ee7a2c..a7b5d407 100644
--- a/crates/benilla-protocol/tests/auction.rs
+++ b/crates/benilla-protocol/tests/auction.rs
@@ -1,11 +1,5 @@
-//! Oracle-free golden tests for the auction house arc's protocol layer (decision 1511 phase P0):
-//! byte-exact goldens for all seven CMSG bodies, the `MSG_AUCTION_HELLO` reply, the four
-//! `SMSG_AUCTION_COMMAND_RESULT` tail shapes, the one 64-byte record and one frame the three list
-//! results share (including that `total_count` rides *after* the records, and that a body shorter
-//! than its own `count` claims still yields the records it does carry), the two deliberately
-//! different notifications, and the removal notice. Same idioms as `tests/mail.rs` — `hx(...)`
-//! golden CMSG bodies, hand-built SMSG bodies round-tripped through `parse_server`, and a
-//! `decode()` bridge assertion.
+//! Golden tests for the auction house wire: every client body byte-exact, and hand-built server
+//! bodies through `parse_server` and `decode`.
 
 use benilla_protocol::events::{decode, SessionEvent};
 use benilla_protocol::messages::{
@@ -26,14 +20,13 @@ const AUCTIONEER: u64 = 0x00F1_3000_0000_0055;
 
 #[test]
 fn auction_send_bodies_golden() {
-    // MSG_AUCTION_HELLO: one full auctioneer guid, nothing else.
+    // MSG_AUCTION_HELLO: the auctioneer's full guid and nothing else.
     assert_eq!(
         messages::auction_hello(AUCTIONEER),
         hx("550000000030f100"),
         "MSG_AUCTION_HELLO body"
     );
 
-    // CMSG_AUCTION_SELL_ITEM: u64 auctioneer, u64 itemGuid, u32 bid, u32 buyout, u32 etime.
     assert_eq!(
         messages::auction_sell_item(
             AUCTIONEER,
@@ -76,9 +69,7 @@ fn auction_send_bodies_golden() {
 
 #[test]
 fn auction_list_items_body_golden() {
-    // CMSG_AUCTION_LIST_ITEMS with every filter set: u64 auctioneer, u32 listfrom, cstr name,
-    // u8 levelmin, u8 levelmax, u32 slotId, u32 mainCategory, u32 subCategory, u32 quality,
-    // u8 usable. TEN fields — no sort column, no sort count, no trailing padding on 5875.
+    // Ten fields and nothing after them: 1.12 has no sort column, sort count or padding.
     assert_eq!(
         messages::auction_list_items(AUCTIONEER, 50, "Copper", 10, 20, 1, 2, 3, 4, 1),
         hx(concat!(
@@ -90,15 +81,13 @@ fn auction_list_items_body_golden() {
             "01000000",         // slotId
             "02000000",         // mainCategory
             "03000000",         // subCategory
-            "04000000",         // quality (a MINIMUM, not an equality)
+            "04000000",         // quality, a minimum, not an equality
             "01",               // usable
         )),
         "CMSG_AUCTION_LIST_ITEMS body (filters set)"
     );
 
-    // The default browse: every filter at its sentinel and an EMPTY search name — which is just
-    // the lone NUL byte between `listfrom` and `levelmin`, nothing more. This exact body is the
-    // one that puts vmangos on its no-filter fast path.
+    // Every filter at its sentinel: the body that takes vmangos's no-filter fast path.
     let body = messages::auction_list_items(
         AUCTIONEER,
         0,
@@ -116,7 +105,7 @@ fn auction_list_items_body_golden() {
         hx(concat!(
             "550000000030f100", // auctioneer
             "00000000",         // listfrom 0
-            "00",               // "" — the lone NUL, and the whole of the name field
+            "00",               // "": the lone NUL is the whole name field
             "00",               // levelmin 0
             "00",               // levelmax 0
             "ffffffff",         // slotId    ANY
@@ -127,22 +116,19 @@ fn auction_list_items_body_golden() {
         )),
         "CMSG_AUCTION_LIST_ITEMS body (empty name, all sentinels)"
     );
-    // 8 + 4 + 1 + 1 + 1 + 4*4 + 1 — the tightest possible browse body. Stated as a number so an
-    // invented trailing field cannot slip in behind a hex string nobody re-counts.
+    // 8 + 4 + 1 + 1 + 1 + 4 * 4 + 1: the smallest browse body.
     assert_eq!(body.len(), 32, "no trailing sort bytes ride this opcode");
 }
 
 #[test]
 fn auction_list_bidder_items_body_golden() {
-    // CMSG_AUCTION_LIST_BIDDER_ITEMS with NO refresh ids: u64 auctioneer, u32 listfrom, u32 0.
-    // The count field is always present even when the list is empty.
+    // u64 auctioneer, u32 listfrom, u32 id count: the count is present even with no ids.
     assert_eq!(
         messages::auction_list_bidder_items(AUCTIONEER, 0, &[]),
         hx("550000000030f1000000000000000000"),
         "CMSG_AUCTION_LIST_BIDDER_ITEMS body (no ids)"
     );
 
-    // ...and with several: the count, then that many u32 auction ids.
     assert_eq!(
         messages::auction_list_bidder_items(AUCTIONEER, 50, &[7, 4242, 0xDEAD_BEEF]),
         hx(concat!(
@@ -159,7 +145,7 @@ fn auction_list_bidder_items_body_golden() {
 
 #[test]
 fn auction_hello_reply_wire() {
-    // MSG_AUCTION_HELLO's reply (same opcode as our request): u64 auctioneerGuid, u32 houseId.
+    // The reply rides the request's opcode: u64 auctioneer, u32 houseId.
     let mut body = AUCTIONEER.to_le_bytes().to_vec();
     body.extend_from_slice(&6u32.to_le_bytes()); // houseId 6 (Orgrimmar), AuctionHouse.dbc 1..7
     match messages::parse_server(messages::opcode::MSG_AUCTION_HELLO, &body).unwrap() {
@@ -169,7 +155,6 @@ fn auction_hello_reply_wire() {
         } => assert_eq!((auctioneer, house_id), (AUCTIONEER, 6)),
         other => panic!("auction hello, got {}", other.name()),
     }
-    // The decode() bridge carries both fields through unchanged.
     let packet = messages::parse_server(messages::opcode::MSG_AUCTION_HELLO, &body).unwrap();
     match decode(packet).pop().unwrap() {
         SessionEvent::AuctionHello {
@@ -202,8 +187,7 @@ fn parse_command(body: &[u8]) -> (u32, u32, u32, AuctionCommandTail) {
 
 #[test]
 fn auction_command_result_bare_wire() {
-    // The bare 3-u32 form: OK + STARTED carries NO tail (the server's OK arm writes one only for
-    // BID_PLACED). This is the shape a successful listing and a successful cancel both take.
+    // OK carries a tail only with BID_PLACED, so a successful listing or cancel is bare.
     let body = command_head(4242, auction_action::STARTED, auction_error::OK);
     assert_eq!(body.len(), 12);
     assert_eq!(
@@ -216,7 +200,6 @@ fn auction_command_result_bare_wire() {
         )
     );
 
-    // OK + REMOVED, likewise bare.
     assert_eq!(
         parse_command(&command_head(
             4242,
@@ -227,8 +210,7 @@ fn auction_command_result_bare_wire() {
         AuctionCommandTail::Empty
     );
 
-    // A named error with no tail of its own (NOT_ENOUGH_MONEY) — bare too, and `auction_id` is
-    // `0` because the server had no AuctionEntry to name.
+    // `auction_id` is 0 when the server had no auction to name.
     assert_eq!(
         parse_command(&command_head(
             0,
@@ -243,14 +225,12 @@ fn auction_command_result_bare_wire() {
         )
     );
 
-    // An UNNAMED error code (6, 8, 9, 11, 12 have no vmangos enumerator) also decodes bare rather
-    // than erroring — the real client falls through to a generic failure branch for these.
+    // Codes 6, 8, 9, 11 and 12 have no vmangos name; the 1.12 client shows a generic failure.
     assert_eq!(
         parse_command(&command_head(0, auction_action::BID_PLACED, 9)).3,
         AuctionCommandTail::Empty
     );
 
-    // The decode() bridge, asserted on this shape.
     let packet = messages::parse_server(
         messages::opcode::SMSG_AUCTION_COMMAND_RESULT,
         &command_head(4242, auction_action::STARTED, auction_error::OK),
@@ -277,8 +257,6 @@ fn auction_command_result_bare_wire() {
 
 #[test]
 fn auction_command_result_bid_placed_tail_wire() {
-    // OK **and** BID_PLACED: one trailing u32 newMinOutBid. Both fields have to match — an OK on
-    // any other action carries nothing (asserted in the bare test above).
     let mut body = command_head(4242, auction_action::BID_PLACED, auction_error::OK);
     body.extend_from_slice(&617u32.to_le_bytes());
     assert_eq!(
@@ -296,8 +274,7 @@ fn auction_command_result_bid_placed_tail_wire() {
 
 #[test]
 fn auction_command_result_inventory_tail_wire() {
-    // INVENTORY: one trailing u32 InventoryResult (EQUIP_ERR_*). Keyed on the ERROR alone — the
-    // action here is STARTED, which carries no tail under OK.
+    // The INVENTORY tail is keyed on the error alone, whatever the action.
     let mut body = command_head(0, auction_action::STARTED, auction_error::INVENTORY);
     body.extend_from_slice(&2u32.to_le_bytes()); // EQUIP_ERR_* code
     assert_eq!(
@@ -313,8 +290,6 @@ fn auction_command_result_inventory_tail_wire() {
 
 #[test]
 fn auction_command_result_higher_bid_tail_wire() {
-    // HIGHER_BID: u64 newBidder, u32 newBid, u32 newMinOutBid — 16 trailing bytes, the longest of
-    // the three tails and the one a reader most easily under-reads.
     let mut body = command_head(4242, auction_action::BID_PLACED, auction_error::HIGHER_BID);
     body.extend_from_slice(&0x0000_0000_0000_07D1u64.to_le_bytes()); // new bidder
     body.extend_from_slice(&25_000u32.to_le_bytes()); // new bid
@@ -352,8 +327,7 @@ fn push_record(body: &mut Vec<u8>, e: &AuctionListEntry) {
     body.extend_from_slice(&e.time_left_ms.to_le_bytes());
     body.extend_from_slice(&e.bidder_guid.to_le_bytes());
     body.extend_from_slice(&e.current_bid.to_le_bytes());
-    // The record's width is load-bearing (it is the reader's short-buffer bound) and decision
-    // 1511's prose miscounts it as 60; pin it here so the two can never drift apart silently.
+    // The record width is the reader's short-buffer bound.
     assert_eq!(body.len() - before, AUCTION_RECORD_BYTES);
     assert_eq!(AUCTION_RECORD_BYTES, 64);
 }
@@ -398,14 +372,11 @@ fn parse_list(opcode: u16, body: &[u8]) -> (Vec<AuctionListEntry>, u32) {
 
 #[test]
 fn auction_list_result_empty_wire() {
-    // count 0, no records, then the trailing totalCount — which can still be nonzero (page 2 of a
-    // one-page result set asked past the end).
+    // Count 0, then a totalCount that is still nonzero when a page past the end is asked.
     let mut body = 0u32.to_le_bytes().to_vec();
     body.extend_from_slice(&37u32.to_le_bytes());
     assert_eq!(body.len(), 8);
 
-    // All three list opcodes share this frame and this record; assert on each so a future arm
-    // cannot be wired to the wrong reader.
     for opcode in [
         messages::opcode::SMSG_AUCTION_LIST_RESULT,
         messages::opcode::SMSG_AUCTION_OWNER_LIST_RESULT,
@@ -419,7 +390,6 @@ fn auction_list_result_empty_wire() {
 
 #[test]
 fn auction_list_result_records_wire() {
-    // Three rows through the real parse_server entry point, then the trailing totalCount.
     let rows = [
         unbid_row(1),
         AuctionListEntry {
@@ -451,14 +421,12 @@ fn auction_list_result_records_wire() {
     assert_eq!(auctions, rows);
     assert_eq!(total_count, 129);
 
-    // Field semantics worth pinning rather than assuming: `min_increment` is 0 while nobody has
-    // bid, `buyout` 0 means no buyout, and `start_bid` is NOT the current bid.
+    // `min_increment` is 0 until a bid, `buyout` 0 means none, `start_bid` is not the current bid.
     assert_eq!(auctions[0].min_increment, 0);
     assert_eq!(auctions[0].current_bid, 0);
     assert_eq!(auctions[1].buyout, 0);
     assert_ne!(auctions[1].start_bid, auctions[1].current_bid);
 
-    // The decode() bridge carries the rows and the total through unchanged.
     let packet = messages::parse_server(messages::opcode::SMSG_AUCTION_LIST_RESULT, &body).unwrap();
     match decode(packet).pop().unwrap() {
         SessionEvent::AuctionListResult {
@@ -471,7 +439,6 @@ fn auction_list_result_records_wire() {
         other => panic!("auction list result event, got {other:?}"),
     }
 
-    // The owner/bidder opcodes land on their own variants off the same bytes.
     let packet =
         messages::parse_server(messages::opcode::SMSG_AUCTION_OWNER_LIST_RESULT, &body).unwrap();
     assert!(matches!(
@@ -488,10 +455,7 @@ fn auction_list_result_records_wire() {
 
 #[test]
 fn auction_list_result_total_count_rides_after_the_records() {
-    // `totalCount` is at the very END of the body, not beside the leading `count`. Build ONE
-    // record whose every field differs from the total, so a reader that took the total from the
-    // front (or from any record field) is caught: the leading count is 1, the total is 9999, and
-    // no record field holds 9999.
+    // Neither the leading count nor any record field is 9999, so only the trailing total can be.
     let row = AuctionListEntry {
         auction_id: 11,
         item_entry: 12,
@@ -522,9 +486,7 @@ fn auction_list_result_total_count_rides_after_the_records() {
 
 #[test]
 fn auction_list_record_round_trips_negative_signed_fields() {
-    // `random_property_id` and `spell_charges` are SIGNED (the server casts int32 through uint32).
-    // A negative random property id is a random *suffix* ("of the Bear"); a negative charge count
-    // means "N charges then destroy". Read unsigned, both become ~4.29-billion nonsense.
+    // Both are int32: a negative property id is a suffix; negative charges destroy when spent.
     let row = AuctionListEntry {
         auction_id: 77,
         item_entry: 7_078,
@@ -550,8 +512,7 @@ fn auction_list_record_round_trips_negative_signed_fields() {
     assert_eq!(auctions[0].spell_charges, -5);
     assert_eq!(auctions[0].suffix_factor, 143);
 
-    // And the unclamped time_left: an expired-but-unswept auction wraps rather than clamping to
-    // 0. The reader must pass it through faithfully; judging it is the consumer's job.
+    // An expired but unswept auction's time left wraps instead of clamping; it passes through.
     let mut expired = unbid_row(78);
     expired.time_left_ms = u32::MAX - 500; // (expire - now) * 1000 on a negative difference
     let mut body = 1u32.to_le_bytes().to_vec();
@@ -563,9 +524,7 @@ fn auction_list_record_round_trips_negative_signed_fields() {
 
 #[test]
 fn auction_list_result_survives_a_count_larger_than_the_records() {
-    // vmangos's browse fast path increments `count` for a record it then fails to write (a stale
-    // auction whose item row is gone writes ZERO bytes and still counts). A body claiming 3 and
-    // carrying 2 must yield those 2 rather than failing the whole page.
+    // vmangos's browse fast path counts a stale auction whose item is gone but writes no bytes.
     let rows = [unbid_row(1), unbid_row(2)];
     let mut body = 3u32.to_le_bytes().to_vec(); // the server's inflated count
     for row in &rows {
@@ -577,8 +536,7 @@ fn auction_list_result_survives_a_count_larger_than_the_records() {
     assert_eq!(auctions, rows, "the records that DID arrive come back");
     assert_eq!(total_count, 2);
 
-    // The harsher variant: truncated past the last record, so even the trailing total is missing.
-    // Still not an error — the total falls back to what we read.
+    // With the trailing total missing too, the total falls back to the records read.
     let mut body = 3u32.to_le_bytes().to_vec();
     for row in &rows {
         push_record(&mut body, row);
@@ -587,8 +545,7 @@ fn auction_list_result_survives_a_count_larger_than_the_records() {
     assert_eq!(auctions, rows);
     assert_eq!(total_count, 2, "falls back to the records actually read");
 
-    // And a count that is pure nonsense (a hostile/desynced body) must not allocate on its word
-    // alone or error — it yields the one record the buffer holds.
+    // A nonsense count yields the one record the buffer holds.
     let mut body = u32::MAX.to_le_bytes().to_vec();
     push_record(&mut body, &rows[0]);
     let (auctions, _) = parse_list(messages::opcode::SMSG_AUCTION_LIST_RESULT, &body);
@@ -597,13 +554,11 @@ fn auction_list_result_survives_a_count_larger_than_the_records() {
 
 #[test]
 fn auction_bidder_notification_wire() {
-    // SMSG_AUCTION_BIDDER_NOTIFICATION: u32 houseId, u32 auctionId, u64 bidderGuid,
-    // u32 bidOrZero, u32 outBid, u32 itemEntry, i32 randomPropertyId — houseId FIRST and the
-    // guid THIRD, unlike the owner notification.
+    // House id first and the guid third, unlike the owner notification.
     let mut body = 6u32.to_le_bytes().to_vec(); // houseId
     body.extend_from_slice(&4242u32.to_le_bytes()); // auctionId
     body.extend_from_slice(&0x0000_0000_0000_0505u64.to_le_bytes()); // bidderGuid
-    body.extend_from_slice(&15_000u32.to_le_bytes()); // bidOrZero — nonzero: OUTBID
+    body.extend_from_slice(&15_000u32.to_le_bytes()); // bidOrZero, nonzero: outbid
     body.extend_from_slice(&750u32.to_le_bytes()); // outBid
     body.extend_from_slice(&12_640u32.to_le_bytes()); // itemEntry
     body.extend_from_slice(&(-19i32).to_le_bytes()); // randomPropertyId, signed
@@ -623,8 +578,7 @@ fn auction_bidder_notification_wire() {
         other => panic!("auction bidder notification, got {}", other.name()),
     }
 
-    // bidOrZero == 0 means WON, not "no bid" — the one field whose zero is a *state*, and the
-    // reason this notification cannot share a struct with the owner one.
+    // bidOrZero 0 means won, not no bid.
     let mut won = body.clone();
     won[16..20].copy_from_slice(&0u32.to_le_bytes());
     match messages::parse_server(messages::opcode::SMSG_AUCTION_BIDDER_NOTIFICATION, &won).unwrap()
@@ -637,9 +591,7 @@ fn auction_bidder_notification_wire() {
         other => panic!("auction bidder notification (won), got {}", other.name()),
     }
 
-    // The two notifications must never share a reader. Feed these same bytes to the OWNER opcode
-    // (28 bytes needed, 32 available, so it parses rather than EOF-ing) and every field lands
-    // somewhere else: the house id is eaten as the auction id and the guid slides four bytes.
+    // The owner reader takes 28 of these 32 bytes and misplaces every field.
     match messages::parse_server(messages::opcode::SMSG_AUCTION_OWNER_NOTIFICATION, &body).unwrap()
     {
         ServerPacket::AuctionOwnerNotification(n) => {
@@ -663,9 +615,7 @@ fn auction_bidder_notification_wire() {
 
 #[test]
 fn auction_owner_notification_wire() {
-    // SMSG_AUCTION_OWNER_NOTIFICATION: u32 auctionId, u32 bid, u32 outBid, u64 bidderGuid,
-    // u32 itemEntry, i32 randomPropertyId — NO houseId, and the guid sits FOURTH. Deliberately a
-    // different shape from the bidder notification above.
+    // No house id and the guid fourth, unlike the bidder notification.
     let mut body = 4242u32.to_le_bytes().to_vec(); // auctionId
     body.extend_from_slice(&15_000u32.to_le_bytes()); // bid
     body.extend_from_slice(&750u32.to_le_bytes()); // outBid
@@ -688,7 +638,7 @@ fn auction_owner_notification_wire() {
         other => panic!("auction owner notification, got {}", other.name()),
     }
 
-    // An all-zero bidder guid is the "sold" signal, not a missing bidder.
+    // An all-zero bidder guid means sold, not a missing bidder.
     let mut sold = body.clone();
     sold[12..20].copy_from_slice(&0u64.to_le_bytes());
     match messages::parse_server(messages::opcode::SMSG_AUCTION_OWNER_NOTIFICATION, &sold).unwrap()
diff --git a/crates/benilla-protocol/tests/auth.rs b/crates/benilla-protocol/tests/auth.rs
index 49f1df1a..10622fc0 100644
--- a/crates/benilla-protocol/tests/auth.rs
+++ b/crates/benilla-protocol/tests/auth.rs
@@ -1,22 +1,16 @@
-//! Oracle-free regression tests for the realmd login protocol — specifically **stream alignment**.
-//! Login packets are not length-framed, so each reader must consume its packet *exactly*; a reader
-//! that stops early leaves trailing bytes that desync the next read. These build a back-to-back
-//! challenge → proof → realm-list byte stream (the real logon sequence) and read all three from one
-//! cursor, which fails loudly if any reader under- or over-consumes.
+//! Login packets are not length-framed, so each realmd reader must consume its packet exactly:
+//! these read a back-to-back challenge, proof and realm-list stream from one cursor.
 
 use benilla_protocol::auth;
 
 const N: [u8; 32] = benilla_srp::LARGE_SAFE_PRIME_LITTLE_ENDIAN;
 
-/// The `crc_salt` a real mangos-family realmd sends (its fixed `VersionChallenge`). The fixture uses
-/// the live bytes rather than zeros, so the reader meets what it actually meets — and so the `got
-/// 0xba` in the proof-read comment below names a real byte of this array.
+/// The `crc_salt` a mangos-family realmd sends: its fixed `VersionChallenge` bytes.
 const CRC_SALT: [u8; 16] = [
     0xba, 0xa3, 0x1e, 0x99, 0xa0, 0x0b, 0x21, 0x57, 0xfc, 0x37, 0x3f, 0xb3, 0x69, 0xcd, 0xd2, 0xf1,
 ];
 
-/// A successful `CMD_AUTH_LOGON_CHALLENGE_Server` body, including the `crc_salt` + `security_flag`
-/// tail that must be consumed.
+/// A successful `CMD_AUTH_LOGON_CHALLENGE_Server` body, with its `crc_salt` + `security_flag` tail.
 fn challenge_packet(server_public_key: &[u8; 32], salt: &[u8; 32]) -> Vec<u8> {
     let mut p = vec![0x00, 0x00, 0x00]; // opcode, protocol_version, result=success
     p.extend_from_slice(server_public_key);
@@ -66,14 +60,13 @@ fn logon_read_sequence_stays_aligned() {
     let server_proof: [u8; 20] =
         std::array::from_fn(|i| (i as u8).wrapping_mul(13).wrapping_add(4));
 
-    // Concatenate the three replies as the server would stream them back-to-back.
     let mut buf = challenge_packet(&server_public_key, &salt);
     buf.extend_from_slice(&proof_packet(&server_proof));
     buf.extend_from_slice(&realm_list_packet());
 
     let mut stream: &[u8] = &buf;
 
-    // 1. Challenge — must consume crc_salt + security_flag so the proof read lands on opcode 0x01.
+    // The challenge read must consume the `crc_salt` + `security_flag` tail to land on opcode 0x01.
     let reply = auth::read_challenge_reply(&mut stream).expect("challenge reply");
     assert_eq!(reply.server_public_key, server_public_key);
     assert_eq!(reply.generator, 7);
@@ -81,12 +74,10 @@ fn logon_read_sequence_stays_aligned() {
     assert_eq!(reply.salt, salt);
     assert_eq!(reply.crc_salt, CRC_SALT); // the proof's `crc_hash` is computed from this
 
-    // 2. Proof — this is exactly where a challenge-reply under-read used to surface (`got 0xba`).
     let proof =
         auth::read_proof_reply(&mut stream).expect("proof reply (stream desynced if this fails)");
     assert_eq!(proof, server_proof);
 
-    // 3. Realm list — confirms the proof reader also consumed its packet exactly.
     let realms =
         auth::read_realm_list(&mut stream).expect("realm list (stream desynced if this fails)");
     assert_eq!(realms.len(), 1);
@@ -94,7 +85,6 @@ fn logon_read_sequence_stays_aligned() {
     assert_eq!(realms[0].address, "127.0.0.1:8085");
     assert_eq!(realms[0].characters, 3);
 
-    // The whole stream should be consumed (no leftover bytes).
     assert!(
         stream.is_empty(),
         "{} trailing bytes — a reader over/under-consumed",
diff --git a/crates/benilla-protocol/tests/bank.rs b/crates/benilla-protocol/tests/bank.rs
index 46f1ce4f..92ca27e8 100644
--- a/crates/benilla-protocol/tests/bank.rs
+++ b/crates/benilla-protocol/tests/bank.rs
@@ -1,9 +1,5 @@
-//! Oracle-free golden tests for the bank arc's protocol layer (Phase 1 of decision 0604): the
-//! six-opcode wire (`CMSG_BANKER_ACTIVATE`/`SMSG_SHOW_BANK`/`CMSG_BUY_BANK_SLOT`/
-//! `SMSG_BUY_BANK_SLOT_RESULT`/`CMSG_AUTOSTORE_BANK_ITEM`/`CMSG_AUTOBANK_ITEM`) plus the two field
-//! accessors the vault window needs (`player_bank_bag_slot`, `player_bank_bag_slots_purchased`).
-//! Same idioms as `tests/gossip_vendor.rs` — `hx(...)` golden CMSG bodies, hand-built SMSG bodies
-//! round-tripped through `parse_server`.
+//! The bank wire: the banker, slot-purchase and autostore opcodes, plus the two player fields the
+//! vault window reads (the bank bag guids and the purchased-slot count).
 
 use benilla_protocol::events::{decode, SessionEvent};
 use benilla_protocol::messages::{self, ObjectFields};
@@ -25,8 +21,7 @@ fn bank_bodies_golden() {
         "CMSG_BANKER_ACTIVATE body"
     );
 
-    // CMSG_BUY_BANK_SLOT (vmangos Item.h:157-163): a full guid — no slot index, the server buys
-    // `purchased_count + 1` itself.
+    // CMSG_BUY_BANK_SLOT (vmangos Item.h:157-163): only a guid; the server buys the next slot.
     assert_eq!(
         messages::buy_bank_slot(0x1234_5678_9abc_def0),
         hx("f0debc9a78563412"),
@@ -40,8 +35,8 @@ fn bank_bodies_golden() {
         "CMSG_AUTOBANK_ITEM body"
     );
 
-    // CMSG_AUTOSTORE_BANK_ITEM (vmangos Item.h:118-126): srcbag, srcslot — same shape, direction
-    // is decided server-side by whether the position names a bank slot.
+    // CMSG_AUTOSTORE_BANK_ITEM (vmangos Item.h:118-126): the same shape; the server picks the
+    // direction by whether the position is a bank slot.
     assert_eq!(
         messages::autostore_bank_item(255, 39),
         vec![255u8, 39],
@@ -73,7 +68,7 @@ fn show_bank_wire() {
 fn buy_bank_slot_result_wire() {
     use messages::bank_slot_result;
 
-    // Result enum values (vmangos Player.h:91-94) — pinned so a future edit can't drift them.
+    // The result codes (vmangos Player.h:91-94).
     assert_eq!(
         (
             bank_slot_result::FAILED_TOO_MANY,
@@ -84,7 +79,7 @@ fn buy_bank_slot_result_wire() {
         (0, 1, 2, 3)
     );
 
-    // SMSG_BUY_BANK_SLOT_RESULT (vmangos Item.cpp:137-140): one u32 result. Round-trip every code.
+    // SMSG_BUY_BANK_SLOT_RESULT (vmangos Item.cpp:137-140): one u32 result.
     for &code in &[
         bank_slot_result::FAILED_TOO_MANY,
         bank_slot_result::INSUFFICIENT_FUNDS,
@@ -129,18 +124,16 @@ fn player_bank_bag_slot_field() {
 
 #[test]
 fn player_bank_bag_slots_purchased_field() {
-    // PLAYER_BYTES_2 (field 194): byte 0 facialHair, byte 1 unk, byte 2 bankBagSlots, byte 3
-    // restState (vmangos Player.h:347, PLAYER_BYTES_2_OFFSET_BANK_BAG_SLOTS = 2). Packed value
-    // 0x04_03_02_01 = restState 4, bankBagSlots 3, unk 2, facialHair 1.
+    // PLAYER_BYTES_2 (field 194), from byte 0: facialHair, unk, bankBagSlots, restState
+    // (vmangos Player.h:347).
     let f = ObjectFields::from_pairs(&[(194, 0x0403_0201)]);
     assert_eq!(f.player_bank_bag_slots_purchased(), Some(3));
     assert_eq!(f.player_facial_hair(), Some(1), "byte 0 unaffected");
 
-    // Unsent field: None, not 0 — the caller must not treat "unstreamed" as "zero slots bought".
+    // An unsent field reads None, not 0: unstreamed is not "zero slots bought".
     let empty = ObjectFields::from_pairs(&[]);
     assert_eq!(empty.player_bank_bag_slots_purchased(), None);
 
-    // All 6 slots purchased.
     let full = ObjectFields::from_pairs(&[(194, 6 << 16)]);
     assert_eq!(full.player_bank_bag_slots_purchased(), Some(6));
 }
diff --git a/crates/benilla-protocol/tests/broadcast.rs b/crates/benilla-protocol/tests/broadcast.rs
index 3d1641b0..dfc963e0 100644
--- a/crates/benilla-protocol/tests/broadcast.rs
+++ b/crates/benilla-protocol/tests/broadcast.rs
@@ -1,13 +1,5 @@
-//! World-broadcast wire decode goldens (mirrors `src/messages/broadcast.rs`):
-//! `SMSG_SERVER_MESSAGE`, `SMSG_ZONE_UNDER_ATTACK`, `SMSG_DEFENSE_MESSAGE` and the bodyless
-//! `SMSG_CHAT_RESTRICTED`. Bytes hand-computed from the vmangos layout (citations inline),
-//! independent of the Rust decoder — see `tests/common` for the shared `hx` fixture helper.
-//!
-//! These four are the packets nobody asks for: they arrive because the world did something, not
-//! because this client did. Three of them had no decode at all until now, which meant a shutdown
-//! countdown, a civilian-kill alarm and an Eastern Plaguelands tower capture all reached benilla as
-//! an unhandled opcode — the server drops you with no warning, and the tower changes hands in
-//! silence.
+//! The unsolicited world broadcasts, bytes built from the vmangos layout: `SMSG_SERVER_MESSAGE`,
+//! `SMSG_ZONE_UNDER_ATTACK`, `SMSG_DEFENSE_MESSAGE` and the bodyless `SMSG_CHAT_RESTRICTED`.
 
 mod common;
 
@@ -16,14 +8,9 @@ use benilla_protocol::messages;
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// `SMSG_SERVER_MESSAGE` (VERIFIED vmangos `WorldPackets::Misc::ServerMessage::AppendBodyTo`,
-/// `Server/Packets/Misc.cpp:341-345`: `buffer << messageType; buffer << text`): `u32` + cstring.
-///
-/// Both shapes the five `ServerMessageType` producers actually send (`World.cpp:2742`/`2761`): a
-/// countdown carrying `secsToTimeString(...)` for its row's `%s`, and a cancellation carrying an
-/// **empty** string, because rows 4 and 5 have no `%s` to fill. The empty text is a value, not a
-/// short packet — the client's own handler tests `[ebp-0x400] == 0` at `0x49dfc8` and takes a
-/// straight copy of the row instead of a format.
+/// `SMSG_SERVER_MESSAGE` (vmangos `Server/Packets/Misc.cpp:341-345`): a `u32` type and a cstring.
+/// A countdown fills its row's `%s`; a cancellation sends empty text (`World.cpp:2742`/`2761`),
+/// which the reference prints as the bare row (`0x49dfc8`).
 #[test]
 fn server_message_decodes_a_countdown_and_a_cancellation() {
     let body = hx("020000003135204d696e7574657300"); // type 2 (RESTART_TIME), "15 Minutes"
@@ -59,9 +46,8 @@ fn server_message_decodes_a_countdown_and_a_cancellation() {
     }
 }
 
-/// `SMSG_ZONE_UNDER_ATTACK` (VERIFIED vmangos
-/// `WorldPackets::Misc::ZoneUnderAttack::AppendBodyTo`, `Server/Packets/Misc.cpp:451-454`): one
-/// `u32` `AreaTable.dbc` id and nothing else. 40 is Westfall.
+/// `SMSG_ZONE_UNDER_ATTACK` (vmangos `Server/Packets/Misc.cpp:451-454`): one `u32`
+/// `AreaTable.dbc` id; 40 is Westfall.
 #[test]
 fn zone_under_attack_decodes() {
     let body = hx("28000000");
@@ -73,12 +59,8 @@ fn zone_under_attack_decodes() {
     ));
 }
 
-/// `SMSG_DEFENSE_MESSAGE` (VERIFIED vmangos `Map::SendDefenseMessage`, `Maps/Map.cpp:1868-1884`):
-/// `u32 zoneId`, `u32 strlen(text) + 1`, then the NUL-terminated text. 139 is the Eastern
-/// Plaguelands, whose tower captures are this packet's only vmangos sender.
-///
-/// The length counts the terminator (`0x30` = 48 for a 47-byte string) and is redundant with the
-/// string; the reference reads and discards it too.
+/// `SMSG_DEFENSE_MESSAGE` (vmangos `Maps/Map.cpp:1868-1884`): `u32 zoneId`, `u32 strlen + 1`
+/// and the cstring; the reference reads and discards the length. 139 is the Eastern Plaguelands.
 #[test]
 fn defense_message_decodes() {
     let body = hx(
@@ -102,9 +84,8 @@ fn defense_message_decodes() {
     }
 }
 
-/// `SMSG_CHAT_RESTRICTED` (VERIFIED vmangos `WorldPackets::Chat::ChatRestricted::AppendBodyTo`,
-/// `Server/Packets/Chat.cpp:21-23`): an **empty** body, exactly like `SMSG_CHAT_WRONG_FACTION`.
-/// The client's arm reads nothing off the wire either (`0x5e4a09` is `push 0x1c3; call 0x496720`).
+/// `SMSG_CHAT_RESTRICTED` (vmangos `Server/Packets/Chat.cpp:21-23`) has an empty body; the
+/// reference's handler reads nothing either (`0x5e4a09`).
 #[test]
 fn chat_restricted_is_bodyless() {
     let p = messages::parse_server(messages::opcode::SMSG_CHAT_RESTRICTED, &[]).unwrap();
diff --git a/crates/benilla-protocol/tests/char_enum.rs b/crates/benilla-protocol/tests/char_enum.rs
index 101754d8..78c56f3f 100644
--- a/crates/benilla-protocol/tests/char_enum.rs
+++ b/crates/benilla-protocol/tests/char_enum.rs
@@ -1,17 +1,11 @@
-//! `SMSG_CHAR_ENUM` (the character-select roster) + the logout round-trip. The enum body is
-//! hand-built byte-exact to the vmangos serializer (`Player::BuildEnumData`, `Player.cpp:1629`:
-//! guid u64 · name cstring · race/class/gender/skin/face/hairStyle/hairColor/facialHair u8 ·
-//! level u8 · zone u32 · map u32 · x/y/z f32 · guild u32 · flags u32 · firstLogin u8 ·
-//! petDisplay/petLevel/petFamily u32 · 19×(display u32 + invType u8) equipment · first-bag
-//! display u32 + invType u8); two characters in one body exercise the alignment of everything
-//! the parser skips.
+//! `SMSG_CHAR_ENUM` in vmangos `Player::BuildEnumData` order (`Player.cpp:1629`), two entries per
+//! body so any misalignment shows, plus the logout and refused-login replies.
 
 use benilla_protocol::events::{decode, SessionEvent};
 use benilla_protocol::messages;
 use benilla_protocol::ServerPacket;
 
-/// One serialized enum entry, vmangos field order. Non-roster fields get distinct junk values so a
-/// misaligned parse can't accidentally pass.
+/// One enum entry; the fixed fields hold distinct values so a misaligned parse cannot pass.
 fn enum_entry(
     guid: u64,
     name: &str,
@@ -36,7 +30,7 @@ fn enum_entry(
         b.extend_from_slice(&c.to_le_bytes());
     }
     b.extend_from_slice(&0u32.to_le_bytes()); // guild id
-    b.extend_from_slice(&0x0200_0000u32.to_le_bytes()); // character flags (DECLINED — junk)
+    b.extend_from_slice(&0x0200_0000u32.to_le_bytes()); // character flags (DECLINED, a junk value)
     b.push(1); // first login
     b.extend_from_slice(&pet_display.to_le_bytes()); // pet display id
     b.extend_from_slice(&7u32.to_le_bytes()); // pet level
@@ -62,7 +56,7 @@ fn char_enum_roster_parses_and_decodes() {
         1,
         0,
         [-8949.95, -132.493, 83.5312],
-        99, // a pet — the select screen stands one beside this character
+        99, // a pet, which the select screen stands beside this character
     ));
     body.extend(enum_entry(
         0x0000_0000_0000_0009,
@@ -86,17 +80,12 @@ fn char_enum_roster_parses_and_decodes() {
         (c.guid, c.name.as_str(), c.race, c.class, c.gender),
         (7, "Two", 1, 1, 0)
     );
-    // The appearance bytes + zone + flags land verbatim (decision 0465 — the select screen
-    // renders them; they used to be alignment-skips).
     assert_eq!(
         (c.skin, c.face, c.hair_style, c.hair_color, c.facial_hair),
         (3, 4, 5, 6, 7)
     );
     assert_eq!((c.zone, c.flags), (12, 0x0200_0000));
-    // The pet triple, which used to be three alignment-skips: it sits between the first-login byte
-    // and the equipment array, and reading it *as* the roster's fields is what stands a pet on the
-    // select screen. The equipment assertions below are the alignment half of this — a triple read
-    // one field wide would slide every display id.
+    // The pet triple sits before the equipment array: a misread slides every display id below.
     assert_eq!(
         (c.pet_display_id, c.pet_level, c.pet_family),
         (99, 7, 1),
@@ -104,7 +93,6 @@ fn char_enum_roster_parses_and_decodes() {
     );
     assert_eq!((c.level, c.map), (1, 0));
     assert_eq!((c.position.x, c.position.y), (-8949.95, -132.493));
-    // All 19 equipment pairs, in slot order: display 1000+slot, invType = slot.
     for (slot, item) in c.equipment.iter().enumerate() {
         assert_eq!(
             (item.display_id, item.inventory_type),
@@ -118,12 +106,11 @@ fn char_enum_roster_parses_and_decodes() {
     );
     assert_eq!((c.level, c.map, c.position.z), (60, 1, 3.5));
     assert_eq!(c.equipment[18].display_id, 1018);
-    // No pet: `petDisplayId == 0` is the whole gate — the server zeroes the triple for every
-    // character but a living hunter's or warlock's, so the client needs no class test of its own.
+    // The server zeroes the triple for all but a hunter's or warlock's pet, so display id 0 is the
+    // whole no-pet gate.
     assert_eq!(c.pet_display_id, 0);
 
-    // Decodes to one CharacterList event carrying the roster through (no realm context on the raw
-    // decode path — the IO thread's own emit is what carries the auth realm entry).
+    // The raw decode has no realm; the IO thread's own emit carries the auth realm entry.
     match &decode(p)[..] {
         [SessionEvent::CharacterList { characters, realm }] => {
             assert_eq!(characters.len(), 2);
@@ -135,20 +122,12 @@ fn char_enum_roster_parses_and_decodes() {
 
 #[test]
 fn logout_complete_decodes_to_logged_out() {
-    // SMSG_LOGOUT_COMPLETE: empty body.
     let p = messages::parse_server(messages::opcode::SMSG_LOGOUT_COMPLETE, &[]).unwrap();
     assert!(matches!(decode(p)[..], [SessionEvent::LoggedOut]));
 }
 
-/// The **refused** pick (`SMSG_CHARACTER_LOGIN_FAILED`, opcode 65): one result byte, straight
-/// through to the event the glue layer answers.
-///
-/// It used to parse into nothing at all — the opcode had a name and no arm — so a server that
-/// refused a character login said it to a client that could not hear it, and the entry the IO
-/// thread had already announced simply never finished. The byte travels **raw**: it is a 1-based
-/// reason index whose meaning is a table in the reference's glue layer, and the wire has no
-/// business holding that table. `0x01` is vmangos's only value; `0x08` is the top of
-/// mangos-classic's `CharLoginFailReasons`, past the client's six-entry switch.
+/// `SMSG_CHARACTER_LOGIN_FAILED` (opcode 65): one raw 1-based reason byte the glue layer maps;
+/// vmangos sends only `0x01`, and `0x08` is past the reference's six-entry switch.
 #[test]
 fn a_refused_character_login_parses_and_decodes() {
     for result in [0x01u8, 0x08] {
diff --git a/crates/benilla-protocol/tests/chat.rs b/crates/benilla-protocol/tests/chat.rs
index 236fcdba..9c5c669b 100644
--- a/crates/benilla-protocol/tests/chat.rs
+++ b/crates/benilla-protocol/tests/chat.rs
@@ -1,11 +1,5 @@
-//! Chat + channel wire decode tests (mirrors `src/messages/chat.rs` + `src/messages/channel.rs`,
-//! decision 0288 phase 1): one golden per `SMSG_MESSAGECHAT` per-type wire shape (the reader was
-//! byte-correct before this decision but had zero golden coverage), `SMSG_TEXT_EMOTE`/`SMSG_EMOTE`,
-//! every `SMSG_CHANNEL_NOTIFY` tail shape, `SMSG_CHANNEL_LIST`, `SMSG_CHAT_PLAYER_NOT_FOUND`,
-//! `SMSG_CHAT_WRONG_FACTION`, `SMSG_NOTIFICATION`, `SMSG_PLAYED_TIME`, and `MSG_RANDOM_ROLL`'s
-//! broadcast shape. Bytes
-//! hand-computed from the vmangos layout (citations inline), independent of the Rust decoder — see
-//! `tests/common` for the shared `hx` fixture helper.
+//! The chat and channel wire: every `SMSG_MESSAGECHAT` shape, the emotes, the channel notices and
+//! list, and the small chat replies, bytes built from the vmangos layout.
 
 mod common;
 
@@ -14,17 +8,13 @@ use benilla_protocol::messages::{self, ChannelNoticeTail};
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// `SMSG_MESSAGECHAT`'s five distinct wire shapes (VERIFIED vmangos `ChatHandler::BuildChatPacket`,
-/// `Chat/Chat.cpp:2542-2599`): SAY/PARTY/YELL (sender guid **twice**), MONSTER_SAY/MONSTER_YELL
-/// (guid + length-prefixed name + target guid), CHANNEL (cstring channel + `u32` rank + guid),
-/// MONSTER_WHISPER/RAID_BOSS_WHISPER/RAID_BOSS_EMOTE/MONSTER_EMOTE (length-prefixed name + target
-/// guid, no leading sender guid), and the `default:` shape (one sender guid) — SYSTEM, WHISPER,
-/// EMOTE, RAID, GUILD, OFFICER, AFK, DND, IGNORED, RAID_LEADER/WARNING, BATTLEGROUND(+LEADER) all
-/// fall here. Every shape ends `u32 len (incl NUL) + text + NUL`, then the trailing `u8 chatTag`
-/// (`Chat/Chat.h:86-92`) this decision surfaces on [`messages::ChatMessage::chat_tag`].
+/// The five `SMSG_MESSAGECHAT` shapes (vmangos `Chat/Chat.cpp:2542-2599`): SAY/PARTY/YELL send
+/// the sender guid twice; MONSTER_SAY/YELL a guid, a length-prefixed name and a target guid;
+/// CHANNEL a cstring channel, a `u32` rank and a guid; MONSTER_WHISPER, the raid-boss types and
+/// MONSTER_EMOTE the name and target guid only; every other type one sender guid. Each ends with a
+/// `u32` length (NUL included), the text and a `u8` chat tag (`Chat/Chat.h:86-92`).
 #[test]
 fn message_chat_decodes_every_wire_shape() {
-    // SAY: guid twice, chat_tag = AFK (1) — proves the tag rides through on the "two guid" shape.
     let body = hx("0007000000887766554433221188776655443322110900000068692074686572650001");
     match messages::parse_server(messages::opcode::SMSG_MESSAGECHAT, &body).unwrap() {
         ServerPacket::MessageChat(m) => {
@@ -39,17 +29,12 @@ fn message_chat_decodes_every_wire_shape() {
         _ => panic!("expected MessageChat"),
     }
 
-    // MONSTER_SAY: guid + length-prefixed name + target guid, chat_tag = none. Body: type(0b) +
-    // language(00000000) + sender guid(ddccbbaa…) + namelen(0f000000) + "Timmy the Wolf\0" +
-    // target guid(66778899…) + msglen(05000000) + "Grr!\0" + chatTag(00).
     let body = hx("0b00000000ddccbbaa000000000f00000054696d6d792074686520576f6c6600667788990000000005000000477272210000");
     match messages::parse_server(messages::opcode::SMSG_MESSAGECHAT, &body).unwrap() {
         ServerPacket::MessageChat(m) => {
             assert_eq!(m.chat_type, messages::CHAT_MSG_MONSTER_SAY);
             assert_eq!(m.sender_guid, 0xAABB_CCDD);
-            // The addressee — the guid slot between the name and the message. It is the subject
-            // the real client's `$`-macro expander resolves this line against (decision 0754), so
-            // it has to survive the parse instead of being read and dropped.
+            // The target guid is what the reference's `$`-macro expander resolves the line against.
             assert_eq!(m.target_guid, 0x9988_7766);
             assert_eq!(m.sender_name.as_deref(), Some("Timmy the Wolf"));
             assert_eq!(m.channel, None);
@@ -59,9 +44,6 @@ fn message_chat_decodes_every_wire_shape() {
         _ => panic!("expected MessageChat"),
     }
 
-    // CHANNEL: cstring channel + u32 rank + guid. Body: type(0e) + language(00000000) +
-    // "General\0" + playerRank(00000000) + sender guid(3412…) + msglen(10000000) +
-    // "wtb boar livers\0" + chatTag(00).
     let body = hx("0e0000000047656e6572616c000000000034120000000000001000000077746220626f6172206c69766572730000");
     match messages::parse_server(messages::opcode::SMSG_MESSAGECHAT, &body).unwrap() {
         ServerPacket::MessageChat(m) => {
@@ -74,9 +56,6 @@ fn message_chat_decodes_every_wire_shape() {
         _ => panic!("expected MessageChat"),
     }
 
-    // MONSTER_WHISPER: length-prefixed name + target guid (no leading sender guid at all). Body:
-    // type(1a) + language(00000000) + namelen(0e000000) + "Innkeeper Bob\0" + target guid(55…) +
-    // msglen(19000000) + "Welcome, weary traveler!\0".
     let body = hx("1a000000000e000000496e6e6b656570657220426f620055000000000000001900000057656c636f6d652c2077656172792074726176656c6572210000");
     match messages::parse_server(messages::opcode::SMSG_MESSAGECHAT, &body).unwrap() {
         ServerPacket::MessageChat(m) => {
@@ -89,9 +68,6 @@ fn message_chat_decodes_every_wire_shape() {
         _ => panic!("expected MessageChat"),
     }
 
-    // default shape (SYSTEM): one sender guid (0), chat_tag = GM (3). Body: type(0a) +
-    // language(00000000) + sender guid(0000000000000000) + msglen(1a000000) +
-    // "This is a system message.\0" + chatTag(03).
     let body = hx(
         "0a0000000000000000000000001a0000005468697320697320612073797374656d206d6573736167652e0003",
     );
@@ -106,17 +82,14 @@ fn message_chat_decodes_every_wire_shape() {
     }
 }
 
-/// `SMSG_TEXT_EMOTE` (VERIFIED vmangos `MaNGOS::EmoteChatBuilder::operator()`,
-/// `Handlers/ChatHandler.cpp:681-702`): `u64` performer guid (an `ObjectGuid` write, unpacked) + `u32`
-/// textEmote + `u32` emoteNum + `u32 namelen` + `namelen` bytes (the target's name + NUL, or a lone
-/// NUL when untargeted) — and `SMSG_EMOTE` (VERIFIED vmangos `EmoteNotify::AppendBodyTo`,
-/// `Server/Packets/Misc.cpp:670-674`): `u32` emoteId + `u64` guid.
+/// `SMSG_TEXT_EMOTE` (vmangos `Handlers/ChatHandler.cpp:681-702`): unpacked `u64` guid, `u32`
+/// textEmote, `u32` emoteNum, `u32` namelen and the target name with its NUL; `SMSG_EMOTE`
+/// (`Server/Packets/Misc.cpp:670-674`): `u32` emoteId and `u64` guid.
 #[test]
 fn text_emote_and_emote_decode() {
     let body = hx("7700000000000000650000000000000004000000426f6200");
     let p = messages::parse_server(messages::opcode::SMSG_TEXT_EMOTE, &body).unwrap();
-    // The target name is KEPT, not skipped past: it is the sentence-form selector (decision 1274).
-    // The NUL inside `namelen` is trimmed, so the string is exactly the display name.
+    // The target name picks the sentence form; the NUL counted in `namelen` is trimmed.
     assert!(matches!(
         &p,
         ServerPacket::TextEmote {
@@ -134,8 +107,7 @@ fn text_emote_and_emote_decode() {
         }] if target_name == "Bob"
     ));
 
-    // Untargeted: vmangos writes `namelen == 1` and a lone NUL, which must read as the EMPTY
-    // string — the "untargeted" bit — and not as a one-byte name.
+    // Untargeted, vmangos sends `namelen == 1` and a lone NUL: an empty name, not a one-byte one.
     let body = hx("770000000000000065000000000000000100000000");
     assert!(matches!(
         messages::parse_server(messages::opcode::SMSG_TEXT_EMOTE, &body).unwrap(),
@@ -160,12 +132,9 @@ fn text_emote_and_emote_decode() {
     ));
 }
 
-/// Every `SMSG_CHANNEL_NOTIFY` tail shape (VERIFIED vmangos `Channel::Make*`,
-/// `Chat/Channel.cpp:804-1008`), one representative per [`ChannelNoticeTail`] variant, plus the
-/// unrecognized-notice error path.
+/// One `SMSG_CHANNEL_NOTIFY` per tail shape (vmangos `Chat/Channel.cpp:804-1008`).
 #[test]
 fn channel_notify_decodes_each_tail_shape() {
-    // 0x00 JOINED: guid.
     let body = hx("0047656e6572616c00aa00000000000000");
     match messages::parse_server(messages::opcode::SMSG_CHANNEL_NOTIFY, &body).unwrap() {
         ServerPacket::ChannelNotify(n) => {
@@ -186,8 +155,7 @@ fn channel_notify_decodes_each_tail_shape() {
         _ => panic!("expected ChannelNotify"),
     }
 
-    // 0x05 NOT_MEMBER: empty tail — both the instance (`MakeNotMember`) and static
-    // (`MakeNotOnPacket`) vmangos producers write this exact shape; no special-casing needed.
+    // 0x05 NOT_MEMBER: empty tail; `MakeNotMember` and `MakeNotOnPacket` both send it.
     let body = hx("0553656372657400");
     match messages::parse_server(messages::opcode::SMSG_CHANNEL_NOTIFY, &body).unwrap() {
         ServerPacket::ChannelNotify(n) => {
@@ -198,7 +166,6 @@ fn channel_notify_decodes_each_tail_shape() {
         _ => panic!("expected ChannelNotify"),
     }
 
-    // 0x18 INVITE: a lone actor guid.
     let body = hx("1847656e6572616c00bb00000000000000");
     match messages::parse_server(messages::opcode::SMSG_CHANNEL_NOTIFY, &body).unwrap() {
         ServerPacket::ChannelNotify(n) => {
@@ -208,7 +175,6 @@ fn channel_notify_decodes_each_tail_shape() {
         _ => panic!("expected ChannelNotify"),
     }
 
-    // 0x09 PLAYER_NOT_FOUND: a bare name.
     let body = hx("0947656e6572616c0047686f737400");
     match messages::parse_server(messages::opcode::SMSG_CHANNEL_NOTIFY, &body).unwrap() {
         ServerPacket::ChannelNotify(n) => {
@@ -228,7 +194,6 @@ fn channel_notify_decodes_each_tail_shape() {
         _ => panic!("expected ChannelNotify"),
     }
 
-    // 0x0C MODE_CHANGE: guid + old flags + new flags.
     let body = hx("0c47656e6572616c00cc000000000000000002");
     match messages::parse_server(messages::opcode::SMSG_CHANNEL_NOTIFY, &body).unwrap() {
         ServerPacket::ChannelNotify(n) => {
@@ -245,7 +210,6 @@ fn channel_notify_decodes_each_tail_shape() {
         _ => panic!("expected ChannelNotify"),
     }
 
-    // 0x12 PLAYER_KICKED: target guid + source (actor) guid.
     let body = hx("1247656e6572616c00dd00000000000000ee00000000000000");
     match messages::parse_server(messages::opcode::SMSG_CHANNEL_NOTIFY, &body).unwrap() {
         ServerPacket::ChannelNotify(n) => {
@@ -261,8 +225,6 @@ fn channel_notify_decodes_each_tail_shape() {
         _ => panic!("expected ChannelNotify"),
     }
 
-    // Round-trip the decoded ChannelNotify through the event layer once (the mapping is a flat
-    // passthrough, but it must actually be wired).
     let body = hx("0047656e6572616c00aa00000000000000");
     let p = messages::parse_server(messages::opcode::SMSG_CHANNEL_NOTIFY, &body).unwrap();
     match &decode(p)[..] {
@@ -278,14 +240,13 @@ fn channel_notify_decodes_each_tail_shape() {
         other => panic!("channel notify decode: {} events", other.len()),
     }
 
-    // An unrecognized notice byte (outside vmangos's defined 0x00..=0x1F) errors rather than
-    // guessing a tail shape.
+    // A notice byte past vmangos's 0x00..=0x1F errors rather than guessing a tail.
     let body = hx("2047656e6572616c00");
     assert!(messages::parse_server(messages::opcode::SMSG_CHANNEL_NOTIFY, &body).is_err());
 }
 
-/// `SMSG_CHANNEL_LIST` (VERIFIED vmangos `Channel::List`, `Chat/Channel.cpp:513-556`): cstring
-/// channel + `u8` flags + `u32` count + that many `(u64 guid, u8 memberFlags)` rows.
+/// `SMSG_CHANNEL_LIST` (vmangos `Chat/Channel.cpp:513-556`): cstring channel, `u8` flags, `u32`
+/// count, then `(u64 guid, u8 memberFlags)` rows.
 #[test]
 fn channel_list_decodes_roster() {
     let body = hx("47656e6572616c001802000000011000000000000001021000000000000000");
@@ -303,7 +264,7 @@ fn channel_list_decodes_roster() {
     }
 }
 
-/// `SMSG_CHAT_PLAYER_NOT_FOUND` (cstring name, VERIFIED vmangos `Server/Packets/Chat.cpp:26-29`) and
+/// `SMSG_CHAT_PLAYER_NOT_FOUND` (cstring name, vmangos `Server/Packets/Chat.cpp:26-29`) and
 /// `SMSG_CHAT_WRONG_FACTION` (empty body, `Server/Packets/Chat.cpp:16-18`).
 #[test]
 fn chat_player_not_found_and_wrong_faction_decode() {
@@ -324,10 +285,8 @@ fn chat_player_not_found_and_wrong_faction_decode() {
     assert!(matches!(decode(p)[..], [SessionEvent::ChatWrongFaction]));
 }
 
-/// `SMSG_NOTIFICATION` (VERIFIED vmangos `WorldSession::SendNotification`,
-/// `Server/WorldSession.cpp:900-915`: `data << szStr`): one cstring, pre-formatted server-side —
-/// the "You do not know that language" reply is how a wrong-tongue send fails (silently, until
-/// this packet was rendered).
+/// `SMSG_NOTIFICATION` (vmangos `Server/WorldSession.cpp:900-915`): one cstring, formatted by the
+/// server; a send in a language the sender does not know fails with this reply.
 #[test]
 fn notification_decodes() {
     let body = hx("596f7520646f206e6f74206b6e6f772074686174206c616e677561676500");
@@ -343,8 +302,7 @@ fn notification_decodes() {
     }
 }
 
-/// `SMSG_PLAYED_TIME` (VERIFIED vmangos `WorldPackets::Misc::PlayedTime::AppendBodyTo`,
-/// `Server/Packets/Misc.cpp:278-282`): `u32` total + `u32` level, both seconds.
+/// `SMSG_PLAYED_TIME` (vmangos `Server/Packets/Misc.cpp:278-282`): total and level, `u32` seconds.
 #[test]
 fn played_time_decodes() {
     let body = hx("40e20100100e0000"); // total = 123456, level = 3600
@@ -365,9 +323,8 @@ fn played_time_decodes() {
     ));
 }
 
-/// `MSG_RANDOM_ROLL`'s server→client broadcast shape (VERIFIED vmangos
-/// `WorldSession::HandleRandomRollOpcode`, `Handlers/GroupHandler.cpp:394-422`): `u32` min + `u32`
-/// max + `u32` roll + a **raw** `u64` guid.
+/// `MSG_RANDOM_ROLL`'s broadcast (vmangos `Handlers/GroupHandler.cpp:394-422`): `u32` min, max
+/// and roll, then an unpacked `u64` guid.
 #[test]
 fn random_roll_broadcast_decodes() {
     let body = hx("01000000640000002a0000009999000000000000");
@@ -392,25 +349,16 @@ fn random_roll_broadcast_decodes() {
     ));
 }
 
-/// The `$`-macro gate is a byte-level fact, not a design choice — pin it.
-///
-/// **The reference has TWO gates, and we want the WIRE one** (decision 0759 corrects 0754). The
-/// `SMSG_MESSAGECHAT` parser `0x49d560` routes `0x0B 0x0C 0x0D 0x1A 0x5A` into the expanding branch
-/// at `0x49da3d` (`0x49d5e4-0x49d606`) and `0x52 0x53 0x54` into the one at `0x49d961` — **eight**.
-/// The seven-value chain at `0x49cf36-0x49cf5d` is the *pending-chat re-expansion* gate and omits
-/// `0x5A`; 0754 cited that one by mistake, leaving boss emotes unexpanded.
-///
-/// Three plausible-and-wrong edits this guards against: dropping `RAID_BOSS_EMOTE` (0x5A) because
-/// the other gate omits it, adding `RAID_BOSS_WHISPER` (0x59) because it looks like its sibling, and
-/// dropping the BG_SYSTEM trio (0x52-0x54) because they look like plain system lines. Player chat is
-/// never expanded.
+/// The `$`-macro types are the reference's wire gate: parser `0x49d560` sends 0x0B, 0x0C, 0x0D,
+/// 0x1A and 0x5A to the expander at `0x49da3d`, and 0x52 to 0x54 to the one at `0x49d961`. The
+/// chain at `0x49cf36-0x49cf5d` is the pending-chat gate, which omits 0x5A; it is not this one.
 #[test]
 fn the_macro_expanded_chat_types_are_the_reference_wire_gate() {
     let mut got = messages::MACRO_EXPANDED_TYPES;
     got.sort_unstable();
     assert_eq!(got, [0x0B, 0x0C, 0x0D, 0x1A, 0x52, 0x53, 0x54, 0x5A]);
-    // 0x59 RAID_BOSS_WHISPER takes its own branch (`0x49d610`), never expands, and is remapped to a
-    // plain whisper — it must never creep in alongside 0x5A.
+    // 0x59 RAID_BOSS_WHISPER takes its own branch (`0x49d610`): never expanded, remapped to a
+    // plain whisper.
     for t in [
         messages::CHAT_MSG_SAY,
         messages::CHAT_MSG_YELL,
@@ -427,20 +375,11 @@ fn the_macro_expanded_chat_types_are_the_reference_wire_gate() {
     }
 }
 
-/// **Addon chat is ordinary chat with a sentinel language** (decision 1029, B215). 1.12.1 has no
-/// addon opcode and no addon `ChatMsg` type: a hunter addon's version ping reaches the client as a
-/// `CHAT_MSG_PARTY` like any other, and only `language == LANG_ADDON` (`0xFFFFFFFF`) separates it
-/// from someone talking. Miss that field and it renders — which is exactly what printed
-/// `[Party] [Soreen]: Quiver VERSION:3.1.4` in a mixed-client party.
-///
-/// The bytes below are the shape `addon_chat_probe` observed coming back off the **live** vmangos
-/// on both lanes it tested (`cargo run -p benilla-protocol --example addon_chat_probe`): the
-/// reported PARTY lane and the CHANNEL lane. Note what the payload is — `prefix`, a TAB, then the
-/// addon's own encoding — and that the server passes it through untouched (addon chat skips
-/// `SanitizeChatMessage` entirely, vmangos `Handlers/ChatHandler.cpp:49`).
+/// 1.12.1 has no addon opcode or chat type: addon chat is ordinary chat in language `LANG_ADDON`
+/// (`0xFFFFFFFF`), its payload `prefix`, a TAB and the message, which vmangos passes through
+/// unsanitized (`Handlers/ChatHandler.cpp:49`). The bytes are what `addon_chat_probe` reads back.
 #[test]
 fn addon_chat_is_an_ordinary_type_with_the_sentinel_language() {
-    // PARTY (the reported case): the two-guid shape, language 0xFFFFFFFF, "Quiver\tVERSION:3.1.4".
     let body = hx("01ffffffff21000000000000002100000000000000150000005175697665720956455253494f4e3a332e312e340000");
     match messages::parse_server(messages::opcode::SMSG_MESSAGECHAT, &body).unwrap() {
         ServerPacket::MessageChat(m) => {
@@ -455,10 +394,8 @@ fn addon_chat_is_an_ordinary_type_with_the_sentinel_language() {
         }
         _ => panic!("expected MessageChat"),
     }
-    // The control, same lane, same shape: speech must not be caught by a language-keyed gate. The
-    // live server hands party speech back as LANG_UNIVERSAL (0) — `HandleChatMessageOpcode`
-    // rewrites the tongue for GMs and for two-side-enabled lanes, and the one language it never
-    // rewrites is LANG_ADDON (the whole normalisation block sits in that `if`'s `else`).
+    // Party speech as vmangos sends it back: `HandleChatMessageOpcode` rewrites the language to
+    // LANG_UNIVERSAL (0) for GMs and two-side-enabled lanes, and never rewrites LANG_ADDON.
     let body = hx("01000000002100000000000000210000000000000013000000706172747920636f6e74726f6c206c696e650000");
     match messages::parse_server(messages::opcode::SMSG_MESSAGECHAT, &body).unwrap() {
         ServerPacket::MessageChat(m) => {
@@ -468,8 +405,7 @@ fn addon_chat_is_an_ordinary_type_with_the_sentinel_language() {
         }
         _ => panic!("expected MessageChat"),
     }
-    // Every tongue a character can actually speak is speech, sentinel or not — the gate is an
-    // equality test against 0xFFFFFFFF, never a range or a "not a known language" test.
+    // Every speakable language is speech: the gate is equality with 0xFFFFFFFF, not a range.
     for lang in [0, 1, 2, 3, 6, 7, 8, 9, 10, 11, 12, 13, 14, 33] {
         let m = messages::ChatMessage {
             chat_type: messages::CHAT_MSG_PARTY,
diff --git a/crates/benilla-protocol/tests/client.rs b/crates/benilla-protocol/tests/client.rs
index aea89f75..e49efe7f 100644
--- a/crates/benilla-protocol/tests/client.rs
+++ b/crates/benilla-protocol/tests/client.rs
@@ -1,7 +1,5 @@
-//! Client-body + query wire tests (mirrors `src/messages/client.rs`): the golden client-encoded
-//! bodies (auth/char-create/chat/emote/stand-state/movement/teleport-ack) and the creature/name
-//! query request+response roundtrip. Split out of the former `tests/messages.rs` (decision-adjacent
-//! mechanical split — see `tests/common` for the shared fixtures and methodology note).
+//! The client-built bodies (auth, char create, chat, emotes, channels, movement, ping) and the
+//! name and creature query replies.
 
 mod common;
 
@@ -11,10 +9,8 @@ use benilla_protocol::wire::Vector3d;
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// The faction tongue every chat send must speak ([`messages::faction_language`]): race → tongue
-/// VERIFIED against the live world DB (`playercreateinfo_spell` — Alliance races 1/3/4/7 learn
-/// spell 668 Language Common, Horde races 2/5/6/8 learn 669 Language Orcish); wire ids VERIFIED
-/// vmangos `SharedDefines.h:256-261` (`LANG_ORCISH = 1`, `LANG_COMMON = 7`).
+/// Alliance races learn Common (spell 668), Horde races Orcish (669) in `playercreateinfo_spell`;
+/// `LANG_COMMON = 7`, `LANG_ORCISH = 1` (vmangos `SharedDefines.h:256-261`).
 #[test]
 fn faction_language_per_race() {
     for race in [1u8, 3, 4, 7] {
@@ -36,9 +32,8 @@ fn faction_language_per_race() {
 #[test]
 fn client_bodies_golden() {
     let proof: [u8; 20] = std::array::from_fn(|i| (i as u8).wrapping_mul(3).wrapping_add(7));
-    // The tail is the addon-info block: `342` uncompressed + the zlib stream of the stock twelve
-    // (decision 1497). Byte-identical to a real 1.12.1.5875 client's — the same 130 compressed
-    // bytes as the 2006 retail capture wow-5875-re verified this against.
+    // The tail is the addon block: `u32` 342 uncompressed, then the zlib stream of the stock
+    // twelve, the same 130 bytes a retail 1.12.1 client sends.
     assert_eq!(
         messages::auth_session(
             5875,
@@ -57,13 +52,14 @@ fn client_bodies_golden() {
         )),
         "CMSG_AUTH_SESSION body"
     );
-    // No secure addons: the tail is *absent*, never a zero size (which no real client emits).
+    // No secure addons: the tail is absent, never a zero size, which no real client sends.
     assert_eq!(
         messages::auth_session(5875, "TESTUSER", 0x1122_3344, &proof, &[]),
         hx("f31600000000000054455354555345520044332211070a0d101316191c1f2225282b2e3134373a3d40"),
         "CMSG_AUTH_SESSION body with no secure addons"
     );
-    // Zero-appearance body (the create-if-empty starter): name + [race,class,gender] + 5 zeros + 0.
+    // CMSG_CHAR_CREATE in vmangos's read order (`Packets/Character.cpp:4-19`): name, race, class,
+    // gender, skin, face, hairStyle, hairColor, facialHair, outfit.
     assert_eq!(
         messages::char_create(&messages::CharCreateReq {
             name: "Benilla".into(),
@@ -79,9 +75,6 @@ fn client_bodies_golden() {
         hx("42656e696c6c6100010100000000000000"),
         "CMSG_CHAR_CREATE body (zero appearance)"
     );
-    // Distinct appearance dials (3/4/5/6/7) — a misplaced byte can't pass. Body is name + nul +
-    // race(01) class(01) gender(00) skin(03) face(04) hairStyle(05) hairColor(06) facialHair(07)
-    // outfit(00), matching vmangos's read order (`Packets/Character.cpp:4-19`).
     assert_eq!(
         messages::char_create(&messages::CharCreateReq {
             name: "Benilla".into(),
@@ -102,9 +95,8 @@ fn client_bodies_golden() {
         hx("00000000070000002e74656c65205765737466616c6c00"),
         "CMSG_MESSAGECHAT body"
     );
-    // The three-field vmangos shape (`Misc.cpp:60-65`): textEmote, emoteNum(0), full target
-    // guid. The original two-field body was silently discarded server-side (the guid read ran
-    // off the packet) — /wave did nothing on any client until the director caught it on the ref.
+    // CMSG_TEXT_EMOTE (vmangos `Misc.cpp:60-65`): textEmote, emoteNum (0) and the full target
+    // guid; the server silently drops a body without the guid.
     assert_eq!(
         messages::text_emote(101, 0x2A),
         hx("65000000000000002a00000000000000"),
@@ -115,8 +107,7 @@ fn client_bodies_golden() {
         hx("01000000"),
         "CMSG_STANDSTATECHANGE body: one u32 animState (Misc.cpp:35-38)"
     );
-    // The chat-type consts feeding CMSG_MESSAGECHAT's type field (VERIFIED vmangos
-    // `SharedDefines.h:1194..1202`, the 5875 band).
+    // The CMSG_MESSAGECHAT type values (vmangos `SharedDefines.h:1194..1202`).
     assert_eq!(messages::CHAT_TYPE_SAY, 0x0, "ChatMsg::CHAT_MSG_SAY");
     assert_eq!(messages::CHAT_TYPE_YELL, 0x5, "ChatMsg::CHAT_MSG_YELL");
     assert_eq!(
@@ -125,7 +116,6 @@ fn client_bodies_golden() {
         "ChatMsg::CHAT_MSG_WHISPER"
     );
     assert_eq!(messages::CHAT_TYPE_EMOTE, 0x8, "ChatMsg::CHAT_MSG_EMOTE");
-    // /yell and /emote share `messagechat`'s body shape, only the type field differs.
     assert_eq!(
         messages::messagechat(messages::CHAT_TYPE_YELL, 7, "for the horde"),
         hx("0500000007000000666f722074686520686f72646500"),
@@ -136,9 +126,8 @@ fn client_bodies_golden() {
         hx("080000000700000064616e63657300"),
         "CMSG_MESSAGECHAT (emote) body"
     );
-    // A Horde say speaks Orcish (0x1) in the language field — hardcoded Common here once made
-    // vmangos drop every Horde character's sends at the `KnowsLanguage` gate, dot-commands
-    // included (only an SMSG_NOTIFICATION came back).
+    // A Horde say speaks Orcish (1): vmangos drops a send in an unknown language at its
+    // `KnowsLanguage` gate, dot-commands included, and answers only with SMSG_NOTIFICATION.
     assert_eq!(
         messages::messagechat(
             messages::CHAT_TYPE_SAY,
@@ -148,29 +137,27 @@ fn client_bodies_golden() {
         hx("0000000001000000666f722074686520686f72646500"),
         "CMSG_MESSAGECHAT (say, Orcish) body"
     );
-    // CMSG_MESSAGECHAT (whisper): type + language, then the target name, then the message — both
-    // NUL-terminated C-strings, target *before* message (VERIFIED vmangos
-    // `Server/Packets/Chat.cpp:3-12`, `ChatMessage::ReadFromWorldPacket`).
+    // Whisper: type, language, then the target and the message cstrings, target first (vmangos
+    // `Server/Packets/Chat.cpp:3-12`).
     assert_eq!(
         messages::messagechat_whisper(7, "Bob", "hi there"),
         hx("0600000007000000426f6200686920746865726500"),
         "CMSG_MESSAGECHAT (whisper) body"
     );
-    // The full 8-byte LE guid body, shared by CMSG_PLAYER_LOGIN / CMSG_SET_ACTIVE_MOVER /
-    // CMSG_SET_SELECTION (all read `recv_data >> guid` server-side — a raw uint64, not a packed guid).
+    // CMSG_PLAYER_LOGIN, CMSG_SET_ACTIVE_MOVER and CMSG_SET_SELECTION all read a raw `u64` guid,
+    // not a packed one.
     assert_eq!(
         messages::full_guid(0x1234_5678_9abc_def0),
         hx("f0debc9a78563412"),
         "full guid body"
     );
-    // CMSG_SET_SELECTION opcode value (317 / 0x013D) — verified vmangos `Opcodes_1_12_1.h`.
+    // CMSG_SET_SELECTION is opcode 317 (vmangos `Opcodes_1_12_1.h`).
     assert_eq!(
         messages::opcode::CMSG_SET_SELECTION,
         0x013D,
         "CMSG_SET_SELECTION opcode"
     );
-    // CMSG_INSPECT (276 / 0x0114) — verified vmangos `Opcodes_1_12_1.h`; body is the same raw
-    // 8-byte guid (`WorldPackets::Misc::Inspect`), NOT a packed guid. Decision 0631.
+    // CMSG_INSPECT is opcode 276 (vmangos `Opcodes_1_12_1.h`), its body a raw guid, not packed.
     assert_eq!(
         messages::opcode::CMSG_INSPECT,
         0x0114,
@@ -207,12 +194,9 @@ fn client_bodies_golden() {
     );
 }
 
-/// The full sendable `CMSG_MESSAGECHAT` type set beyond the original four (decision 0288 phase 1) —
-/// every one VERIFIED against vmangos `Handlers/ChatHandler.cpp`'s `HandleChatMessageOpcode` switch
-/// (253-655): PARTY/RAID/GUILD/OFFICER/RAID_LEADER/RAID_WARNING/BATTLEGROUND(+LEADER)/AFK/DND all
-/// share [`messages::messagechat`]'s plain shape (no target field); CHANNEL carries the channel name
-/// the same way WHISPER carries its target (`messages::messagechat_channel`). Bytes hand-computed
-/// from the vmangos layout (`Server/Packets/Chat.cpp:3-12`), independent of the Rust builder.
+/// The other sendable `CMSG_MESSAGECHAT` types (vmangos `Handlers/ChatHandler.cpp:253-655`) use
+/// the plain shape, except CHANNEL, which carries its channel name where WHISPER carries its
+/// target (`Server/Packets/Chat.cpp:3-12`).
 #[test]
 fn messagechat_sendable_types_golden() {
     assert_eq!(messages::CHAT_TYPE_PARTY, 0x1, "ChatMsg::CHAT_MSG_PARTY");
@@ -307,15 +291,11 @@ fn messagechat_sendable_types_golden() {
         hx("1500000007000000646f206e6f74206469737475726200"),
         "CMSG_MESSAGECHAT (dnd) body"
     );
-    // CHANNEL: type + language, then the channel name, then the message — the same
-    // target-before-message shape as whisper (vmangos's `whisperTargetOrChannel` union).
     assert_eq!(
         messages::messagechat_channel(0, "General", "wtb boar livers"),
         hx("0e0000000000000047656e6572616c0077746220626f6172206c697665727300"),
         "CMSG_MESSAGECHAT (channel) body"
     );
-    // The generic builder both named wrappers are thin shells over: `target: None` matches
-    // `messagechat`, `target: Some(_)` matches `messagechat_whisper`/`messagechat_channel`.
     assert_eq!(
         messages::messagechat_kind(messages::CHAT_TYPE_SAY, 7, None, "hi"),
         messages::messagechat(messages::CHAT_TYPE_SAY, 7, "hi"),
@@ -328,38 +308,18 @@ fn messagechat_sendable_types_golden() {
     );
 }
 
-/// **The addon broadcast body** (`SendAddonMessage`, decision 1235) — `CMSG_MESSAGECHAT` on one of
-/// four ordinary lanes with the `LANG_ADDON` sentinel in the language field. Bytes hand-computed
-/// from the layout, independent of the Rust builder.
-///
-/// VERIFIED in `WoW.exe` (5875) — wow-re `system/ui/scratch/addon-chat-law.md` §5, the binding
-/// `0x49f920`: opcode `0x95` (`0x49facf`), u32 chat type (`0x49fad8`), u32 language from
-/// `or ebx,-0x1` (`0x49fab9`) written at `0x49fae1`, then the message CString (`0x49faf0`). There
-/// is **no prefix field and no target field on the wire** — the prefix is glued to the message
-/// with a literal TAB (`_snprintf(dst, 0x800, "%s\t%s", …)` at `0x49f9b3`, format `0x844b5c`, raw
-/// `25 73 09 25 73 00`) and the pair rides as one C-string. The far client splits on the FIRST tab
-/// (`0x49a8d0`).
-///
-/// Corroborated end-to-end against a live vmangos by `examples/addon_chat_probe` (decision 1029):
-/// the sentinel comes back intact and the `0x09` survives (addon chat skips `SanitizeChatMessage`,
-/// `Handlers/ChatHandler.cpp:49`).
+/// `SendAddonMessage` (reference `0x49f920`) sends `CMSG_MESSAGECHAT` on one of four lanes: `u32`
+/// type, `u32` language `LANG_ADDON`, then one cstring of prefix, TAB and message (`0x49f9b3`);
+/// there is no prefix or target field. The receiver splits on the first TAB (`0x49a8d0`).
 #[test]
 fn addon_message_bodies_golden() {
-    // `LANG_ADDON` — the whole discriminator. Not a tongue, and never rewritten by the server.
     assert_eq!(
         messages::LANGUAGE_ADDON,
         0xFFFF_FFFF,
         "LANG_ADDON (vmangos SharedDefines.h:270)"
     );
 
-    // oRA2 `Core.lua:563`, verbatim: SendAddonMessage("CTRA", msg, "RAID") — the corpus's one
-    // live caller of this verb.
-    //   02 00 00 00                          CHAT_MSG_RAID
-    //   ff ff ff ff                          LANG_ADDON
-    //   43 54 52 41                          "CTRA"
-    //   09                                   TAB — the prefix/message separator
-    //   73 74 61 74 75 73                    "status"
-    //   00                                   the message C-string's NUL
+    // oRA2's `SendAddonMessage("CTRA", msg, "RAID")` (`Core.lua:563`).
     assert_eq!(
         messages::messagechat(
             messages::CHAT_TYPE_RAID,
@@ -370,8 +330,7 @@ fn addon_message_bodies_golden() {
         "CMSG_MESSAGECHAT (addon, RAID) body"
     );
 
-    // The other three lanes of the client's four-value whitelist (`0x49fa3f`-`0x49fa4e`). Only the
-    // type byte moves; the sentinel and the tab-composed payload are identical.
+    // The other lanes of the reference's four-lane whitelist (`0x49fa3f`-`0x49fa4e`).
     assert_eq!(
         messages::messagechat(
             messages::CHAT_TYPE_PARTY,
@@ -400,12 +359,8 @@ fn addon_message_bodies_golden() {
         "CMSG_MESSAGECHAT (addon, BATTLEGROUND) body"
     );
 
-    // AceEvent-2.0.lua's own line — `SendAddonMessage("LOOT_OPENED", "", "RAID")`, the call
-    // replicated in 24 of the 218 corpus addons. **The empty message still carries its tab**: the
-    // composition is unconditional, so the payload is `"LOOT_OPENED\t"` and the body ends TAB, NUL.
-    // A builder that "helpfully" dropped a trailing separator would make the far client read
-    // prefix `"LOOT_OPENED"` with no message at all — which is the same thing, but only by
-    // accident of the receiver's no-tab rule; the bytes must still match the reference's.
+    // An empty message still carries its TAB: the reference composes `"%s\t%s"` unconditionally,
+    // so AceEvent-2.0's `SendAddonMessage("LOOT_OPENED", "", "RAID")` ends TAB, NUL.
     assert_eq!(
         messages::messagechat(
             messages::CHAT_TYPE_RAID,
@@ -416,9 +371,6 @@ fn addon_message_bodies_golden() {
         "CMSG_MESSAGECHAT (addon, empty message keeps its TAB) body"
     );
 
-    // An addon line is byte-identical to ordinary speech on the same lane EXCEPT the language
-    // field — the property the receive-side gate rests on, pinned so a future refactor cannot
-    // quietly reintroduce a tongue here.
     let addon = messages::messagechat(messages::CHAT_TYPE_PARTY, messages::LANGUAGE_ADDON, "x\ty");
     let speech =
         messages::messagechat(messages::CHAT_TYPE_PARTY, messages::LANGUAGE_COMMON, "x\ty");
@@ -429,10 +381,8 @@ fn addon_message_bodies_golden() {
     assert_eq!(&speech[4..8], &[0x07, 0x00, 0x00, 0x00], "LANG_COMMON");
 }
 
-/// The channel wire family's CMSG bodies (decision 0288 phase 1) — join/leave/list + the full
-/// moderation set, ALL verified vmangos `Server/Packets/Channel.cpp` (every `ReadFromWorldPacket`
-/// there is a channel-name cstring, optionally followed by a second cstring: a password or a target
-/// player name). Bytes hand-computed from that layout, independent of the Rust builder.
+/// The channel CMSG bodies: a channel-name cstring, then optionally a password or target-name
+/// cstring (vmangos `Server/Packets/Channel.cpp`).
 #[test]
 fn channel_client_bodies_golden() {
     assert_eq!(
@@ -521,8 +471,7 @@ fn channel_client_bodies_golden() {
         "CMSG_CHANNEL_MODERATE body"
     );
 
-    // Every opcode in the family (VERIFIED vmangos `Server/Protocol/Opcodes_1_12_1.h:154-171`,
-    // decimal 151-168).
+    // The family's opcodes, 151 to 168 (vmangos `Server/Protocol/Opcodes_1_12_1.h:154-171`).
     assert_eq!(messages::opcode::CMSG_JOIN_CHANNEL, 0x0097);
     assert_eq!(messages::opcode::CMSG_LEAVE_CHANNEL, 0x0098);
     assert_eq!(messages::opcode::SMSG_CHANNEL_NOTIFY, 0x0099);
@@ -543,11 +492,9 @@ fn channel_client_bodies_golden() {
     assert_eq!(messages::opcode::CMSG_CHANNEL_MODERATE, 0x00A8);
 }
 
-/// The remaining decision-0288 phase-1 small bodies: `CMSG_CHAT_IGNORED` (reuses
-/// [`messages::full_guid`] — VERIFIED vmangos `WorldPackets::Misc::ChatIgnored::
-/// ReadFromWorldPacket`, `Server/Packets/Misc.cpp:127-130`, a raw un-packed guid), `CMSG_PLAYED_TIME`
-/// (empty), and `MSG_RANDOM_ROLL`'s client→server request shape (VERIFIED vmangos
-/// `WorldPackets::Group::RandomRoll::ReadFromWorldPacket`, `Server/Packets/Group.cpp:39-43`).
+/// `CMSG_CHAT_IGNORED` is a raw guid (vmangos `Server/Packets/Misc.cpp:127-130`),
+/// `CMSG_PLAYED_TIME` is empty, and the `MSG_RANDOM_ROLL` request is `u32` min and max
+/// (`Server/Packets/Group.cpp:39-43`).
 #[test]
 fn chat_ignored_played_time_random_roll_golden() {
     assert_eq!(
@@ -575,15 +522,22 @@ fn chat_ignored_played_time_random_roll_golden() {
 
 #[test]
 fn name_and_creature_query_roundtrip() {
-    // CMSG_CREATURE_QUERY body: entry u32 + full 8-byte guid (vmangos QueryCreature::ReadFromWorldPacket).
+    // CMSG_CREATURE_QUERY: `u32` entry and the full guid (vmangos `QueryCreature`).
     assert_eq!(
         messages::creature_query(69, 0x1234_5678_9abc_def0),
         hx("45000000f0debc9a78563412"),
         "CMSG_CREATURE_QUERY body"
     );
 
-    // SMSG_NAME_QUERY_RESPONSE: guid, name, realm (empty), race/gender/class u32s (vmangos
-    // NameQueryResponse::AppendBodyTo, 1.12.1 includes the realm string).
+    // CMSG_NAME_QUERY: the full guid (vmangos `QueryPlayerName`), built by `full_guid`.
+    assert_eq!(
+        messages::full_guid(7),
+        hx("0700000000000000"),
+        "CMSG_NAME_QUERY body"
+    );
+
+    // SMSG_NAME_QUERY_RESPONSE (vmangos `NameQueryResponse::AppendBodyTo`): guid, name, an empty
+    // realm cstring, then race, gender and class as `u32`.
     let body = hx("070000000000000042656e696c6c610000010000000000000001000000");
     match messages::parse_server(messages::opcode::SMSG_NAME_QUERY_RESPONSE, &body).unwrap() {
         ServerPacket::NameQueryResponse {
@@ -600,14 +554,8 @@ fn name_and_creature_query_roundtrip() {
         _ => panic!("name query response"),
     }
 
-    // SMSG_CREATURE_QUERY_RESPONSE hit: entry, name, 3 empty names, subname, the 7-u32 tail
-    // (type_flags, TYPE — the TAB critter filter's input — FAMILY, RANK, unk, pet_spell_id,
-    // display_id), 2 u8 tail. Family and rank are given DIFFERENT non-zero values on purpose:
-    // they are adjacent dwords, so a one-column slip between them reads as plausible data and
-    // shows up only as a pet whose level line names the wrong beast (decision 1062). `display_id`
-    // is non-zero for the same reason (decision 1676): it sits behind two alignment-only dwords
-    // that were zeros here, so a slip into either read 0 — indistinguishable from "no model" —
-    // and the stable window would have drawn an empty booth for every pet.
+    // A hit. Family, rank and display id get distinct non-zero values so a one-dword slip between
+    // adjacent fields cannot read as plausible data.
     let body = hx(concat!(
         "45000000",
         "596f756e6720576f6c6600", // "Young Wolf"
@@ -618,7 +566,7 @@ fn name_and_creature_query_roundtrip() {
         "01000000",               // pet_family = 1 (Wolf)
         "02000000",               // rank = 2 (rare elite)
         "0000000000000000",       // unk, pet_spell_list_id
-        "15020000",               // display_id = 533 — the model a stabled pet is drawn from
+        "15020000",               // display_id = 533, the model a stabled pet is drawn from
         "0101"                    // civilian, racial_leader
     ));
     match messages::parse_server(messages::opcode::SMSG_CREATURE_QUERY_RESPONSE, &body).unwrap() {
@@ -653,10 +601,8 @@ fn name_and_creature_query_roundtrip() {
     }
 }
 
-/// The event layer's subname law: an EMPTY wire subname is NO subname (vmangos sends "" for
-/// creatures without one; the real client renders no line for it — the nameplate builder's
-/// verified shape, `0x608f50`). `Some("")` reaching a consumer painted an empty tooltip line
-/// whose zero-extent chain slot spilled every later line below the plate.
+/// An empty wire subname is no subname: vmangos sends "" for a creature without one, and the
+/// reference renders no line for it (`0x608f50`).
 #[test]
 fn creature_query_empty_subname_decodes_to_none() {
     let body = |subname_hex: &str| {
@@ -684,7 +630,6 @@ fn creature_query_empty_subname_decodes_to_none() {
         }
         other => panic!("expected one CreatureName event, got {other:?}"),
     }
-    // Control: a real subname survives verbatim.
     match decode(parse(&body("5465737400"))).as_slice() {
         [SessionEvent::CreatureName { subname, .. }] => {
             assert_eq!(subname.as_deref(), Some("Test"));
@@ -693,10 +638,8 @@ fn creature_query_empty_subname_decodes_to_none() {
     }
 }
 
-/// The keepalive pair, byte-exact both ways: the `CMSG_PING` body is `{u32 sequence, u32 lastRtt}`
-/// LE (VERIFIED wow-re net W1 `SendPing 0x537e10` + vmangos `_HandlePing`'s read order), and the
-/// `SMSG_PONG` echo (`{u32 sequence}`) parses and decodes to the event the io layer times against
-/// its ping clock. A new wire body never lands without a golden (method).
+/// `CMSG_PING` is `u32` sequence then `u32` last RTT (reference `0x537e10`, vmangos
+/// `_HandlePing`); `SMSG_PONG` echoes the sequence.
 #[test]
 fn ping_body_golden_and_pong_roundtrip() {
     assert_eq!(
@@ -724,13 +667,9 @@ fn ping_body_golden_and_pong_roundtrip() {
     }
 }
 
-/// **`SMSG_ADDON_INFO`, against the retail capture's own bytes** (decision 2175).
-///
-/// The reply carries no count and no names: the client re-walks the `## Secure:` list it sent and
-/// reads one record per addon. The 2006 capture is the minimal form — 96 bytes, 12 x
-/// `{status = 2, infoProvided = 1, keyProvided = 0, revision = 0u32, urlProvided = 0}` — and
-/// `status = 2` is what sets `[rec+0x29] = 1` (`0x51db84`) and drops the addon from the Lua index
-/// space (wow-re `system/net/scratch/cmsg-auth-session-addon-block.md` §6).
+/// `SMSG_ADDON_INFO` has no count or names: the client reads one record per addon it sent. A
+/// retail capture is 12 records of `{status 2, info 1, key 0, u32 revision 0, url 0}`; status 2
+/// hides the addon from the Lua index (reference `0x51db84`).
 #[test]
 fn the_addon_info_reply_pairs_its_statuses_back_against_what_we_sent() {
     let capture: Vec<u8> = std::iter::repeat_n(hx("0201000000000000"), 12)
@@ -743,8 +682,7 @@ fn the_addon_info_reply_pairs_its_statuses_back_against_what_we_sent() {
     };
     assert_eq!(statuses, vec![2u8; 12]);
 
-    // Paired back against the block we send, every stock addon is hidden from the index space —
-    // which is why the reference's AddOns list shows the player's addons and none of Blizzard's.
+    // Every stock addon comes back hidden, so the reference's AddOns list shows none of Blizzard's.
     let hidden = messages::hidden_from_reply(&statuses, &messages::STOCK_SECURE_ADDONS);
     assert_eq!(hidden.len(), 12);
     assert!(
@@ -752,8 +690,8 @@ fn the_addon_info_reply_pairs_its_statuses_back_against_what_we_sent() {
         "{hidden:?}"
     );
 
-    // A record that says it carries a key and a url is 8 + 256 + 256 bytes, and `status = 1`
-    // leaves the addon VISIBLE — the exclusion is `2` alone, not "the server said something".
+    // A record with a key and a url is 8 + 256 + 256 bytes; status 1 leaves the addon visible,
+    // only status 2 hides it.
     let mut fat = vec![1u8, 1, 1];
     fat.extend(std::iter::repeat_n(0xABu8, 256)); // modulus
     fat.extend([0u8; 4]); // revision
@@ -766,8 +704,6 @@ fn the_addon_info_reply_pairs_its_statuses_back_against_what_we_sent() {
     assert_eq!(statuses, vec![1u8], "the fat record parsed whole");
     assert!(messages::hidden_from_reply(&statuses, &messages::STOCK_SECURE_ADDONS).is_empty());
 
-    // A truncated record contributes nothing, and the whole ones before it survive — the pairing
-    // against what we sent cannot slip.
     let mut short = hx("0201000000000000").to_vec();
     short.extend([2u8, 1]); // a second record that stops mid-way
     let packet = messages::parse_server(messages::opcode::SMSG_ADDON_INFO, &short).unwrap();
diff --git a/crates/benilla-protocol/tests/common/mod.rs b/crates/benilla-protocol/tests/common/mod.rs
index 43575f36..8570acca 100644
--- a/crates/benilla-protocol/tests/common/mod.rs
+++ b/crates/benilla-protocol/tests/common/mod.rs
@@ -1,9 +1,4 @@
-//! Shared fixtures for the world message layer's oracle-free regression tests (split by domain
-//! across `tests/*.rs`). Client packet bodies are pinned to golden hex captured from the validated
-//! implementation (byte-validated against `wow_world_messages` during the decision-0021 migration);
-//! `SMSG_UPDATE_OBJECT` fixtures are real serialized packet bodies from that same corpus, parsed +
-//! decoded here. Simple server bodies are hand-built (their layout is trivial: a few little-endian
-//! scalars).
+//! Shared fixtures for the protocol tests: `hx` decodes the hex of a golden packet body.
 
 pub fn hx(s: &str) -> Vec<u8> {
     (0..s.len())
diff --git a/crates/benilla-protocol/tests/gossip_vendor.rs b/crates/benilla-protocol/tests/gossip_vendor.rs
index 246dfd28..397eb890 100644
--- a/crates/benilla-protocol/tests/gossip_vendor.rs
+++ b/crates/benilla-protocol/tests/gossip_vendor.rs
@@ -1,8 +1,5 @@
-//! Oracle-free golden tests for the gossip/vendor interaction arc's protocol layer (Phase 1 of the
-//! gossip/vendor arc): `CMSG_GOSSIP_HELLO`/`SELECT_OPTION`, `CMSG_NPC_TEXT_QUERY`, and the vendor
-//! `LIST_INVENTORY`/`BUY_ITEM`/`SELL_ITEM` family. Split out from `messages.rs` (same idioms —
-//! `hx(...)` golden CMSG bodies, hand-built SMSG bodies round-tripped through `parse_server`) since
-//! it's a self-contained wire family or size.
+//! The gossip and vendor wire: hello, option select, NPC text and the greeting draw, and the vendor
+//! inventory, buy and sell messages.
 
 use benilla_protocol::events::{decode, SessionEvent};
 use benilla_protocol::messages;
@@ -17,8 +14,7 @@ fn hx(s: &str) -> Vec<u8> {
 
 #[test]
 fn gossip_bodies_golden() {
-    // CMSG_GOSSIP_HELLO (vmangos Npc.cpp:3) / CMSG_LIST_INVENTORY (Item.cpp:94) share the same
-    // full-guid body shape.
+    // CMSG_GOSSIP_HELLO (vmangos Npc.cpp:3): a full guid.
     assert_eq!(
         messages::gossip_hello(0x1234_5678_9abc_def0),
         hx("f0debc9a78563412"),
@@ -32,9 +28,8 @@ fn gossip_bodies_golden() {
         "CMSG_NPC_TEXT_QUERY body"
     );
 
-    // CMSG_GOSSIP_SELECT_OPTION (vmangos Npc.cpp:78-86): guid, gossipListId, then an optional
-    // trailing code cstring — appended only for a coded option with a real code, omitted entirely
-    // otherwise (the server reads it only when the buffer is non-empty).
+    // CMSG_GOSSIP_SELECT_OPTION (vmangos Npc.cpp:78-86): guid, gossipListId, then a code cstring
+    // only for a coded option; the server reads it only when bytes remain.
     assert_eq!(
         messages::gossip_select_option(0x1234_5678_9abc_def0, 3, None),
         hx(concat!("f0debc9a78563412", "03000000")),
@@ -58,8 +53,7 @@ fn vendor_bodies_golden() {
         "CMSG_LIST_INVENTORY body"
     );
 
-    // CMSG_BUY_ITEM (vmangos Item.cpp:104-110): vendorGuid, item ENTRY (not muid), count, unk1(0).
-    // entry 2488 is the live-verified creature-54 vendor's Gladius row (decision 0081).
+    // CMSG_BUY_ITEM (vmangos Item.cpp:104-110): vendorGuid, item entry (not muid), count, unk1 (0).
     assert_eq!(
         messages::buy_item(0x1234_5678_9abc_def0, 2488, 1),
         hx(concat!("f0debc9a78563412", "b8090000", "01", "00")),
@@ -78,9 +72,7 @@ fn vendor_bodies_golden() {
 fn gossip_message_wire() {
     use benilla_protocol::messages::{GossipOption, QuestOption};
 
-    // SMSG_GOSSIP_MESSAGE (vmangos GossipDef.cpp:180-225, the 1.12 shape): objectGuid, textId,
-    // optionCount + options (index, icon, coded, message), questOptionCount + quest options. Zero
-    // quest options — the common case for a pure vendor/gossip NPC.
+    // SMSG_GOSSIP_MESSAGE (vmangos GossipDef.cpp:180-225), with no quest options.
     let mut body = 0xAAu64.to_le_bytes().to_vec(); // objectGuid
     body.extend_from_slice(&100u32.to_le_bytes()); // textId
     body.extend_from_slice(&2u32.to_le_bytes()); // optionCount
@@ -124,7 +116,6 @@ fn gossip_message_wire() {
         other => panic!("gossip message, got {}", other.name()),
     }
 
-    // decode() surfaces a GossipMenu event carrying the (empty here) quest block.
     let packet = messages::parse_server(messages::opcode::SMSG_GOSSIP_MESSAGE, &body).unwrap();
     match decode(packet).pop().unwrap() {
         SessionEvent::GossipMenu {
@@ -139,8 +130,6 @@ fn gossip_message_wire() {
         other => panic!("gossip menu event, got {other:?}"),
     }
 
-    // Nonzero quest options: parsed for byte alignment, kept on the wire struct (arc ignores them
-    // downstream — quest-giver flows are out of scope, decision 0081).
     let mut body_q = 0xBBu64.to_le_bytes().to_vec();
     body_q.extend_from_slice(&200u32.to_le_bytes()); // textId
     body_q.extend_from_slice(&0u32.to_le_bytes()); // optionCount: 0
@@ -172,7 +161,6 @@ fn gossip_message_wire() {
         other => panic!("gossip message with quests, got {}", other.name()),
     }
 
-    // SMSG_GOSSIP_COMPLETE — empty body.
     match messages::parse_server(messages::opcode::SMSG_GOSSIP_COMPLETE, &[]).unwrap() {
         ServerPacket::GossipComplete => {}
         other => panic!("gossip complete, got {}", other.name()),
@@ -184,10 +172,8 @@ fn gossip_message_wire() {
     }
 }
 
-/// `SMSG_GOSSIP_POI` — the guard's directions marker (vmangos `GossipDef.cpp:239-295`):
-/// `u32 flags, f32 x, f32 y, u32 icon, u32 data, cstr name`. The golden body is a REAL row of the
-/// 5875-era `points_of_interest` table (entry 658, "Lion's Pride Inn": flags 99, icon 6 =
-/// `ICON_POI_REDFLAG`, data 0) — the shape every guard direction actually takes.
+/// `SMSG_GOSSIP_POI`, a guard's directions marker (vmangos `GossipDef.cpp:239-295`); the body is
+/// `points_of_interest` row 658, "Lion's Pride Inn".
 #[test]
 fn gossip_poi_wire_and_event() {
     let body = hx(concat!(
@@ -235,7 +221,7 @@ fn npc_text_update_greeting_extraction() {
         }
     }
 
-    // The wire carries all 8 blocks through UNDECIDED — the parse layer no longer picks.
+    // The parse carries all 8 blocks; `select_greeting` picks one.
     let mut body = 321u32.to_le_bytes().to_vec(); // textID
     block(&mut body, 0.1, "Low probability greeting", "");
     block(&mut body, 0.0, "", "");
@@ -263,14 +249,23 @@ fn npc_text_update_greeting_extraction() {
         SessionEvent::NpcGreeting { text_id, blocks } => {
             assert_eq!(text_id, 321);
             assert_eq!(blocks.len(), messages::NPC_TEXT_BLOCKS);
+
+            // A near-zero threshold draws the first block with text in the gender's column, the
+            // full sum the last; the male column skips block 6, the female column block 0.
+            const NEAR: f32 = 1.999_999_9;
+            const FAR: f32 = 1.0;
+            let pick = |gender, roll| messages::select_greeting(&blocks, gender, roll);
+            assert_eq!(pick(0, NEAR), Some("Low probability greeting"));
+            assert_eq!(pick(0, FAR), Some("Welcome, $N!"));
+            assert_eq!(pick(1, NEAR), Some("Welcome, traveler!"));
+            assert_eq!(pick(1, FAR), Some("Female-only greeting"));
         }
         other => panic!("npc greeting event, got {other:?}"),
     }
 }
 
-/// The greeting DRAW (wow-re `gossip-npctext-law.md`, reference `0x4e2010`) — a weighted random
-/// pick over the blocks whose chosen gender column is non-empty. Every branch pinned with an
-/// explicit roll, because all three rules here are the opposite of what this client used to do.
+/// The greeting draw (reference `0x4e2010`): a weighted random pick over the blocks whose chosen
+/// gender column is non-empty.
 #[test]
 fn greeting_draw_follows_the_weighted_law() {
     use benilla_protocol::messages::{select_greeting, NpcTextBlock};
@@ -280,27 +275,24 @@ fn greeting_draw_follows_the_weighted_law() {
         male: male.into(),
         female: female.into(),
     };
-    // roll ∈ [1, 2) ⇒ thr = (2 - roll) * sum ∈ (0, sum]. roll = 1.0 is the far end (thr = sum),
-    // roll → 2.0 the near end (thr → 0).
+    // The threshold is (2 - roll) * sum for roll in [1, 2): FAR gives the sum, NEAR nearly 0.
     const NEAR: f32 = 1.999_999_9;
     const FAR: f32 = 1.0;
 
-    // 1 · The all-zero record — vmangos's fallback, and much of the 1.12 table. sum = 0 ⇒ thr = 0,
-    //     and the predicate is `<=`, so block 0 wins on EVERY roll rather than nothing winning.
+    // An all-zero record, vmangos's fallback: the threshold is 0 and the test is `<=`, so block 0
+    // wins on every roll.
     let zeros: Vec<_> = (0..8).map(|i| b(0.0, &format!("line {i}"), "")).collect();
     for roll in [FAR, 1.5, NEAR] {
         assert_eq!(select_greeting(&zeros, 0, roll), Some("line 0"));
     }
 
-    // 2 · Real weights: the draw walks in order, so a near-zero threshold takes the first non-empty
-    //     block and a threshold of the full sum takes the last. The old rule — highest probability
-    //     wins — would have answered "big" for both.
+    // The draw walks in order: a near-zero threshold takes the first non-empty block, the full
+    // sum the last.
     let weighted = vec![b(0.1, "small", ""), b(0.8, "big", ""), b(0.1, "last", "")];
     assert_eq!(select_greeting(&weighted, 0, NEAR), Some("small"));
     assert_eq!(select_greeting(&weighted, 0, FAR), Some("last"));
 
-    // 3 · The column is the NPC's gender, chosen once. Genderless (2) reads as male, because the
-    //     reference tests `== 1`, not `!= 0`.
+    // Genderless (2) reads as male: the reference tests the gender `== 1`, not `!= 0`.
     let gendered = vec![b(1.0, "sir", "madam")];
     assert_eq!(select_greeting(&gendered, 0, FAR), Some("sir"));
     assert_eq!(select_greeting(&gendered, 1, FAR), Some("madam"));
@@ -310,9 +302,8 @@ fn greeting_draw_follows_the_weighted_law() {
         "genderless"
     );
 
-    // 4 · No fallback to the other column. A female NPC skips male-only blocks outright — she does
-    //     NOT borrow their text (this client used to) — and if that empties the record she gets no
-    //     greeting at all, which is the reference's "Missing gossip text!" path.
+    // No fallback to the other column: a female NPC skips male-only blocks, and if none remain she
+    // gets no greeting, the reference's "Missing gossip text!" path.
     let male_only = vec![b(1.0, "men only", ""), b(1.0, "", "ladies")];
     assert_eq!(select_greeting(&male_only, 1, FAR), Some("ladies"));
     assert_eq!(select_greeting(&male_only, 1, NEAR), Some("ladies"));
@@ -324,11 +315,8 @@ fn greeting_draw_follows_the_weighted_law() {
 fn vendor_list_inventory_wire() {
     use benilla_protocol::messages::VendorItem;
 
-    // SMSG_LIST_INVENTORY (vmangos ItemHandler.cpp:741-810): vendorGuid, u8 count, count x {muid,
-    // entry, displayId, currentCount, price, maxDurability, buyCount}. Two rows keyed off the
-    // live-verified creature-54 weapon vendor data (decision 0081): Gladius (entry
-    // 2488, price 536, display 22078, maxcount 0 -> unlimited) and a limited-stock second row.
-    // Trailing junk proves the parser stops reading rows at `count`.
+    // SMSG_LIST_INVENTORY (vmangos ItemHandler.cpp:741-810): vendorGuid, `u8` count, then per row
+    // `u32` muid, entry, displayId, currentCount, price, maxDurability and buyCount.
     let mut body = 0xCCu64.to_le_bytes().to_vec();
     body.push(2); // count
     for v in [1u32, 2488, 22078, 0xFFFF_FFFF, 536, 35, 1] {
@@ -377,8 +365,7 @@ fn vendor_list_inventory_wire() {
         other => panic!("vendor inventory event, got {other:?}"),
     }
 
-    // Empty stock: count = 0 followed by the trailing error byte (ItemHandler.cpp:728-733,
-    // 806-809) — consumed explicitly, so the decode leaves no tail to report.
+    // Empty stock: count 0, then an error byte (vmangos ItemHandler.cpp:728-733, 806-809).
     let mut empty_body = 0xDDu64.to_le_bytes().to_vec();
     empty_body.push(0); // count
     empty_body.push(0); // trailing errorByte(0)
@@ -393,14 +380,13 @@ fn vendor_list_inventory_wire() {
         }
         other => panic!("empty vendor list, got {}", other.name()),
     }
-    // …and the byte is REQUIRED: a count of 0 with nothing after it is the short read it is.
+    // The error byte is required: count 0 with nothing after it is a short read.
     let truncated = &empty_body[..empty_body.len() - 1];
     assert!(messages::parse_server(messages::opcode::SMSG_LIST_INVENTORY, truncated).is_err());
 }
 
-/// **The falsifier for decision 2265 §B1** on a `u32`-counted list: an option count of
-/// `0xFFFF_FFFF` followed by one valid option must come back as a short-read `Err` — the decoder
-/// must neither reserve the count nor abort.
+/// A `u32` option count of `0xFFFF_FFFF` over one valid option is a short-read `Err`: the decoder
+/// neither reserves the count nor aborts.
 #[test]
 fn a_lying_gossip_option_count_is_a_short_read_not_an_allocation() {
     let mut body = 0x77u64.to_le_bytes().to_vec(); // npc guid
@@ -420,8 +406,8 @@ fn a_lying_gossip_option_count_is_a_short_read_not_an_allocation() {
 fn vendor_buy_sell_result_wire() {
     use benilla_protocol::messages::{buy_result, sell_result};
 
-    // SMSG_BUY_ITEM (vmangos Item.cpp:190-196): vendorGuid, vendorSlot (1-based), newCount
-    // (0xFFFF_FFFF unlimited), purchaseCount. Only the vendor stock display changes here.
+    // SMSG_BUY_ITEM (vmangos Item.cpp:190-196): vendorGuid, 1-based vendorSlot, newCount
+    // (0xFFFF_FFFF unlimited), purchaseCount.
     let mut body = 0xCCu64.to_le_bytes().to_vec();
     for v in [1u32, 0xFFFF_FFFF, 1] {
         body.extend_from_slice(&v.to_le_bytes());
@@ -448,7 +434,7 @@ fn vendor_buy_sell_result_wire() {
         other => panic!("vendor buy result event, got {other:?}"),
     }
 
-    // SMSG_SELL_ITEM (vmangos Item.cpp:183-188) — the error path only: vendorGuid, itemGuid, reason.
+    // SMSG_SELL_ITEM (vmangos Item.cpp:183-188), the error path only: vendorGuid, itemGuid, reason.
     let mut body = 0xCCu64.to_le_bytes().to_vec();
     body.extend_from_slice(&0x42u64.to_le_bytes());
     body.push(sell_result::CANT_FIND_ITEM);
@@ -498,7 +484,7 @@ fn vendor_buy_sell_result_wire() {
         other => panic!("vendor buy failed event, got {other:?}"),
     }
 
-    // Result enum values (vmangos ItemDefines.h:120-141) — pinned so a future edit can't drift them.
+    // The result codes (vmangos ItemDefines.h:120-141).
     assert_eq!(
         (
             buy_result::CANT_FIND_ITEM,
diff --git a/crates/benilla-protocol/tests/group.rs b/crates/benilla-protocol/tests/group.rs
index a4e0a94a..8dbdf442 100644
--- a/crates/benilla-protocol/tests/group.rs
+++ b/crates/benilla-protocol/tests/group.rs
@@ -1,9 +1,5 @@
-//! Golden tests for the group/party opcode family — invite/accept/decline/kick/leader/disband, the
-//! loot method, the roster push (`SMSG_GROUP_LIST`), party command feedback, live member stats for
-//! the party/raid frame, minimap pings, raid subgroup management, raid-target icons, and ready
-//! checks. CMSG bodies are asserted byte-exact against the builder output; SMSG bodies are hand-built
-//! per the vmangos layouts (cited inline) and round-tripped through `parse_server` + `decode`. See
-//! `tests/common` for the shared `hx()` fixture helper and methodology note.
+//! The group wire: invites, leadership, loot method, the roster, member stats, minimap pings, raid
+//! subgroups, target icons, ready checks and raid info, laid out per vmangos.
 
 mod common;
 
@@ -15,8 +11,6 @@ use benilla_protocol::messages::{
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// Every CMSG builder in the family, byte-exact — including the empty-body ones (asserting an
-/// empty `Vec`) and the `raid_target_set` vs `raid_target_request` distinction.
 #[test]
 fn cmsg_bodies_golden() {
     let guid = 0x1234_5678_9abc_def0u64;
@@ -34,8 +28,7 @@ fn cmsg_bodies_golden() {
         "CMSG_GROUP_UNINVITE body"
     );
 
-    // CMSG_GROUP_ACCEPT / DECLINE / DISBAND / RAID_CONVERT (vmangos Opcodes.cpp: NullClientPacket):
-    // all empty.
+    // ACCEPT, DECLINE, DISBAND and RAID_CONVERT are empty (vmangos Opcodes.cpp: NullClientPacket).
     assert_eq!(
         messages::group_accept(),
         Vec::<u8>::new(),
@@ -57,7 +50,7 @@ fn cmsg_bodies_golden() {
         "CMSG_GROUP_RAID_CONVERT body"
     );
 
-    // CMSG_GROUP_UNINVITE_GUID / CMSG_GROUP_SET_LEADER / CMSG_REQUEST_PARTY_MEMBER_STATS: a full guid.
+    // UNINVITE_GUID, SET_LEADER and REQUEST_PARTY_MEMBER_STATS: a full guid.
     assert_eq!(
         messages::group_uninvite_guid(guid),
         hx(guid_hex),
@@ -107,15 +100,15 @@ fn cmsg_bodies_golden() {
         "CMSG_GROUP_ASSISTANT_LEADER body, revoke"
     );
 
-    // MSG_MINIMAP_PING, outbound (Group.cpp:33-37): f32 x, f32 y — no guid.
+    // MSG_MINIMAP_PING, outbound (Group.cpp:33-37): f32 x, f32 y, no guid.
     assert_eq!(
         messages::minimap_ping(1.0, 2.0),
         hx("0000803f00000040"),
         "MSG_MINIMAP_PING outbound body"
     );
 
-    // MSG_RAID_TARGET_UPDATE, client bodies (Group.cpp:77-82): icon+guid to set/clear one icon, a
-    // lone 0xFF to ask for the current set — the two builders are never interchangeable byte-shapes.
+    // MSG_RAID_TARGET_UPDATE (Group.cpp:77-82): icon and guid set or clear one icon; a lone 0xFF
+    // requests the current set.
     assert_eq!(
         messages::raid_target_set(3, guid),
         hx(concat!("03", "f0debc9a78563412")),
@@ -150,8 +143,6 @@ fn cmsg_bodies_golden() {
     );
 }
 
-/// The name/notice trio (`SMSG_GROUP_INVITE`/`_DECLINE`/`_SET_LEADER`, one cstring each) plus the
-/// two empty-body notices (`SMSG_GROUP_UNINVITE`/`_DESTROYED`).
 #[test]
 fn group_notification_smsg_wire() {
     // SMSG_GROUP_INVITE (Group.cpp:107-110): one cstring, the inviter's name.
@@ -187,7 +178,7 @@ fn group_notification_smsg_wire() {
         other => panic!("group leader changed decode: {other:?}"),
     }
 
-    // SMSG_GROUP_UNINVITE (Group.cpp:117-119): empty body — we were kicked/left.
+    // SMSG_GROUP_UNINVITE (Group.cpp:117-119): empty; we were removed or left.
     let p = messages::parse_server(opcode::SMSG_GROUP_UNINVITE, &[]).unwrap();
     assert!(matches!(p, ServerPacket::GroupUninvited));
     assert!(matches!(
@@ -195,7 +186,7 @@ fn group_notification_smsg_wire() {
         [SessionEvent::GroupUninvited]
     ));
 
-    // SMSG_GROUP_DESTROYED (Group.cpp:121-123): empty body — the group disbanded outright.
+    // SMSG_GROUP_DESTROYED (Group.cpp:121-123): empty; the group disbanded.
     let p = messages::parse_server(opcode::SMSG_GROUP_DESTROYED, &[]).unwrap();
     assert!(matches!(p, ServerPacket::GroupDestroyed));
     assert!(matches!(
@@ -204,12 +195,11 @@ fn group_notification_smsg_wire() {
     ));
 }
 
-/// `SMSG_GROUP_LIST`, party shape: 2 other members + the full loot tail (master loot, so
-/// `looterGuid` carries the master's guid).
+/// `SMSG_GROUP_LIST`, party shape, master loot: `looterGuid` carries the master looter.
 #[test]
 fn group_list_party_two_members_master_loot() {
-    // Group.cpp:155-180 (GroupList::AppendBodyTo): groupType, ownGroupAndAssistantFlag,
-    // memberCount, memberCount x member rows, leaderGuid, then (memberCount > 0) the loot tail.
+    // Group.cpp:155-180: groupType, own flags, memberCount, the member rows, leaderGuid, then the
+    // loot tail only when memberCount > 0.
     let mut body = vec![0u8]; // groupType: party
     body.push(0x00); // ownGroupAndAssistantFlag: subgroup 0, not assistant
     body.extend_from_slice(&2u32.to_le_bytes()); // memberCount
@@ -287,8 +277,8 @@ fn group_list_party_two_members_master_loot() {
     }
 }
 
-/// `SMSG_GROUP_LIST`, raid shape: `groupType == 1`, one member carrying the raid-assistant bit
-/// (`0x80`), round-robin loot (so `looterGuid` is `0` — vmangos only fills it for master loot).
+/// `SMSG_GROUP_LIST`, raid shape (`groupType == 1`), with the assistant bit (`0x80`) and
+/// round-robin loot, whose `looterGuid` is 0: vmangos fills it only for master loot.
 #[test]
 fn group_list_raid_with_assistant_flag() {
     let mut body = vec![1u8]; // groupType: raid
@@ -342,12 +332,17 @@ fn group_list_raid_with_assistant_flag() {
     }
 }
 
-/// The degenerate "you left the group" shape (`Group.cpp:155-180` with an empty member list):
-/// exactly 14 bytes (`groupType, ownFlags, u32 memberCount=0, u64 leaderGuid=0`), no loot tail.
+/// The "you left the group" shape (`Group.cpp:155-180`, no members): 14 bytes, no loot tail.
 #[test]
 fn group_list_empty_you_left_shape_is_14_bytes() {
     let body = vec![0u8; 14];
     assert_eq!(body.len(), 14);
+    let (_, tail) = messages::parse_server_with_tail(opcode::SMSG_GROUP_LIST, &body).unwrap();
+    assert_eq!(tail, 0, "the parser reads all 14 bytes");
+    assert!(
+        messages::parse_server(opcode::SMSG_GROUP_LIST, &body[..13]).is_err(),
+        "13 bytes is a short read"
+    );
 
     let p = messages::parse_server(opcode::SMSG_GROUP_LIST, &body).unwrap();
     match &p {
@@ -377,8 +372,8 @@ fn group_list_empty_you_left_shape_is_14_bytes() {
     }
 }
 
-/// `SMSG_PARTY_COMMAND_RESULT` (Group.cpp:100-105): a named refusal, and the ignoring-you refusal
-/// which names no one (`Handlers/GroupHandler.cpp:466`: `SendPartyResult(PARTY_OP_INVITE, "", ...)`).
+/// `SMSG_PARTY_COMMAND_RESULT` (Group.cpp:100-105): a named refusal, and the ignoring-you refusal,
+/// which names no one (`Handlers/GroupHandler.cpp:466`).
 #[test]
 fn party_command_result_wire() {
     let mut body = party_operation::INVITE.to_le_bytes().to_vec();
@@ -420,8 +415,7 @@ fn party_command_result_wire() {
     }
 }
 
-/// `SMSG_PARTY_MEMBER_STATS` (delta form): mask `0x000000FF` — every bit from `STATUS` through
-/// `ZONE` — hand-computed body, the plain (non-`_FULL`) opcode.
+/// `SMSG_PARTY_MEMBER_STATS` (delta) with mask `0xFF`: every field from `STATUS` to `ZONE`.
 #[test]
 fn party_member_stats_delta_status_through_zone() {
     let body = hx(concat!(
@@ -468,9 +462,8 @@ fn party_member_stats_delta_status_through_zone() {
     }
 }
 
-/// `SMSG_PARTY_MEMBER_STATS_FULL`: `POSITION` + `AURAS` (2 bits set) + `AURAS_NEGATIVE` (1 bit) +
-/// the whole pet block (`PET_GUID`..`PET_AURAS_NEGATIVE`, including `PET_AURAS`) — every remaining
-/// field family the delta test above didn't touch.
+/// `SMSG_PARTY_MEMBER_STATS_FULL` with position, auras and the whole pet block: every field the
+/// delta test does not cover.
 #[test]
 fn party_member_stats_full_position_auras_and_pet_block() {
     let mask = party_member_mask::POSITION
@@ -501,9 +494,7 @@ fn party_member_stats_full_position_auras_and_pet_block() {
     // AURAS_NEGATIVE: u16 negMask, bit 2 set -> spell id 8050.
     body.extend_from_slice(&0x0004u16.to_le_bytes());
     body.extend_from_slice(&8050u16.to_le_bytes());
-    // PET_GUID.
     body.extend_from_slice(&0x1122_3344_5566_7788u64.to_le_bytes());
-    // PET_NAME.
     body.extend_from_slice(b"Fido\0");
     // PET_MODEL_ID, PET_CUR_HP, PET_MAX_HP.
     body.extend_from_slice(&618u16.to_le_bytes());
@@ -539,7 +530,6 @@ fn party_member_stats_full_position_auras_and_pet_block() {
             assert_eq!(info.pet_max_power, Some(100));
             assert_eq!(info.pet_auras, Some(vec![1126]));
             assert_eq!(info.pet_auras_negative, Some(vec![770]));
-            // Bits not in the mask stay None.
             assert_eq!(info.status, None);
             assert_eq!(info.level, None);
         }
@@ -556,8 +546,8 @@ fn party_member_stats_full_position_auras_and_pet_block() {
     }
 }
 
-/// The offline-miss reply (`Handlers/GroupHandler.cpp:763-774`, the not-in-raid-with-us branch):
-/// `SMSG_PARTY_MEMBER_STATS_FULL`, mask `STATUS` only, status `MEMBER_STATUS_OFFLINE` (`0`).
+/// The reply for a member not in our group (`Handlers/GroupHandler.cpp:763-774`):
+/// `SMSG_PARTY_MEMBER_STATS_FULL` with only `STATUS`, set to offline (0).
 #[test]
 fn party_member_stats_offline_miss_is_status_only() {
     let body = hx(concat!(
@@ -577,8 +567,8 @@ fn party_member_stats_offline_miss_is_status_only() {
     }
 }
 
-/// `MSG_MINIMAP_PING` inbound (`Handlers/GroupHandler.cpp:382-391`): full guid + f32 x + f32 y —
-/// the server-stamped rebroadcast shape (outbound, guid-less, is covered in [`cmsg_bodies_golden`]).
+/// `MSG_MINIMAP_PING` inbound (`Handlers/GroupHandler.cpp:382-391`): the server prefixes the
+/// sender's full guid to the `f32` x and y.
 #[test]
 fn minimap_ping_inbound_wire() {
     let mut body = 0x77u64.to_le_bytes().to_vec();
@@ -599,8 +589,8 @@ fn minimap_ping_inbound_wire() {
     }
 }
 
-/// `MSG_RAID_TARGET_UPDATE`, all three server shapes (Group.cpp:132-147): mode 0 (delta), mode 1
-/// with 2 entries, and mode 1 empty (no icons currently set — a raid with a clean target board).
+/// `MSG_RAID_TARGET_UPDATE` from the server (Group.cpp:132-147): mode 0 carries one icon, mode 1
+/// the full list, possibly empty.
 #[test]
 fn raid_target_update_smsg_shapes() {
     let mut body = vec![0u8, 3]; // mode 0 (delta), icon 3
@@ -638,7 +628,6 @@ fn raid_target_update_smsg_shapes() {
         other => panic!("raid target list decode: {other:?}"),
     }
 
-    // mode 1, empty: no icons currently marked.
     let p = messages::parse_server(opcode::MSG_RAID_TARGET_UPDATE, &[1u8]).unwrap();
     match &p {
         ServerPacket::RaidTargetList { entries } => assert!(entries.is_empty()),
@@ -646,8 +635,8 @@ fn raid_target_update_smsg_shapes() {
     }
 }
 
-/// `MSG_RAID_READY_CHECK`, both server shapes (Group.cpp:94-96 empty / 126-130 answer): the empty
-/// "a check just started" body, and a member's forwarded answer (full guid + state).
+/// `MSG_RAID_READY_CHECK` from the server: empty when a check starts (Group.cpp:94-96), a full
+/// guid and state for a member's answer (126-130).
 #[test]
 fn ready_check_smsg_shapes() {
     let p = messages::parse_server(opcode::MSG_RAID_READY_CHECK, &[]).unwrap();
@@ -676,11 +665,9 @@ fn ready_check_smsg_shapes() {
     }
 }
 
-/// `CMSG_REQUEST_RAID_INFO` / `SMSG_RAID_INSTANCE_INFO` (decision 1549's Raid Info panel;
-/// vmangos `Player::SendRaidInfo`): an empty request, and a `u32 count` + `count` × 12-byte rows
-/// answer. The zero-count body is the ordinary answer for a character bound to nothing, and it
-/// must decode to an EMPTY list rather than to nothing at all — the UI reads the arrival as "the
-/// server has spoken", which is what disables the Raid Info button.
+/// `CMSG_REQUEST_RAID_INFO` is empty; `SMSG_RAID_INSTANCE_INFO` (vmangos `Player::SendRaidInfo`)
+/// is a `u32` count of 12-byte rows. A zero count still decodes to an event: its arrival is what
+/// disables the Raid Info button.
 #[test]
 fn raid_instance_info_wire() {
     assert_eq!(
@@ -699,8 +686,6 @@ fn raid_instance_info_wire() {
         other => panic!("empty raid info decode: {other:?}"),
     }
 
-    // Two rows: Molten Core (map 409) resetting in 0x00015180 = 86400 s, instance 1234; and
-    // Onyxia's Lair (map 249) in 3600 s, instance 77.
     let body = hx(concat!(
         "02000000", // count
         "99010000", "80510100", "d2040000", // map 409, 86400 s, instance 1234
diff --git a/crates/benilla-protocol/tests/guild.rs b/crates/benilla-protocol/tests/guild.rs
index ac312881..1cb3bd71 100644
--- a/crates/benilla-protocol/tests/guild.rs
+++ b/crates/benilla-protocol/tests/guild.rs
@@ -1,17 +1,5 @@
-//! Golden tests for the guild opcode family — the query and roster caches, invitations, the member
-//! verbs, rank administration, the event broadcast and the command-result feedback. CMSG bodies are
-//! asserted byte-exact against the builder output; SMSG bodies are hand-built per the vmangos
-//! layouts (cited inline) and round-tripped through `parse_server` + `decode`. See `tests/common`
-//! for the shared `hx()` fixture helper and methodology note.
-//!
-//! Three of the tests below exist for a specific failure mode rather than for coverage, and each
-//! was mutation-checked — the parser was broken that exact way and the test observed to fail:
-//! `guild_roster_conditional_float_keeps_later_members_in_sync` (the `f32` that rides on the
-//! presence byte, whose third member is the one that proves the parse re-synchronises after a
-//! wider record), `guild_query_response_always_carries_ten_rank_names` (the fixed ten, which a
-//! counted read walks straight past into the emblem block), and
-//! `guild_event_trailing_guid_rides_on_the_event_id` (which pins us to the *client's* narrower
-//! read, not vmangos's write rule).
+//! The guild wire: the query and roster caches, invitations, member verbs, rank administration,
+//! the event broadcast and command results, laid out per vmangos.
 
 mod common;
 
@@ -23,9 +11,6 @@ use benilla_protocol::messages::{
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// Every CMSG builder in the family, byte-exact — the six empty-body verbs asserting an empty
-/// `Vec`, the eight one-cstring verbs, the two two-cstring note verbs, the `u32` query, and the
-/// three-field rank write.
 #[test]
 fn cmsg_bodies_golden() {
     // CMSG_GUILD_QUERY (vmangos Server/Packets/Guild.cpp:8-11): one u32, the guild id.
@@ -84,8 +69,7 @@ fn cmsg_bodies_golden() {
         "CMSG_GUILD_MOTD body"
     );
 
-    // The empty-body verbs (vmangos Opcodes.cpp: NullClientPacket at :213, :214, :216, :218, :222,
-    // :224, :655). Every one of these carries its meaning entirely in the opcode.
+    // The empty verbs (vmangos Opcodes.cpp:213, 214, 216, 218, 222, 224, 655: NullClientPacket).
     assert_eq!(
         messages::guild_accept(),
         Vec::<u8>::new(),
@@ -122,8 +106,7 @@ fn cmsg_bodies_golden() {
         "CMSG_GUILD_DEL_RANK body"
     );
 
-    // CMSG_GUILD_RANK (Guild.cpp:78-83): u32 rankId, u32 rights, cstring rankName — the rights
-    // here are the officer set (chat listen/speak both channels, invite, promote, demote).
+    // CMSG_GUILD_RANK (Guild.cpp:78-83): u32 rankId, u32 rights, cstring rankName.
     let rights = guild_rank_right::GCHAT_LISTEN
         | guild_rank_right::GCHAT_SPEAK
         | guild_rank_right::OFFCHAT_LISTEN
@@ -138,8 +121,7 @@ fn cmsg_bodies_golden() {
         "CMSG_GUILD_RANK body"
     );
 
-    // CMSG_GUILD_SET_PUBLIC_NOTE / _OFFICER_NOTE (Guild.cpp:61-65 / 67-71): name then note, two
-    // cstrings — the same byte shape, distinguished only by opcode and by which right gates it.
+    // CMSG_GUILD_SET_PUBLIC_NOTE / _OFFICER_NOTE (Guild.cpp:61-65 / 67-71): name, then note.
     assert_eq!(
         messages::guild_set_public_note("Bob", "hi"),
         hx(concat!("426f6200", "686900")),
@@ -152,14 +134,8 @@ fn cmsg_bodies_golden() {
     );
 }
 
-/// Clearing the MOTD.
-///
-/// vmangos's read is guarded — `GuildMOTD::ReadFromWorldPacket` (Server/Packets/Guild.cpp:38-42)
-/// is `if (!recv_data.empty()) recv_data >> motd;` — so a **zero-byte** body is a legal shape that
-/// also means "clear it" (the packet's `motd` stays default-constructed). We emit the well-formed
-/// one-byte empty cstring instead: one builder, one shape, and the empty string is not a special
-/// case anywhere in the crate. Both land on the server as `motd == ""`, so this is a choice about
-/// our own code, not about what the server does.
+/// An empty MOTD is a one-byte empty cstring; vmangos (`Server/Packets/Guild.cpp:38-42`) reads a
+/// zero-byte body as a clear too.
 #[test]
 fn guild_motd_clears_with_an_empty_cstring_not_an_empty_body() {
     assert_eq!(
@@ -170,14 +146,8 @@ fn guild_motd_clears_with_an_empty_cstring_not_an_empty_body() {
     assert_eq!(messages::guild_motd("").len(), 1, "one NUL, not zero bytes");
 }
 
-/// `SMSG_GUILD_QUERY_RESPONSE`: **exactly ten** rank-name cstrings, always — a fixed loop over the
-/// sender's `rankNames[10]`, not a counted list (vmangos Server/Packets/Guild.cpp:118-131, filled
-/// by Guild/Guild.cpp:862-880, whose own comment reads "show always 10 ranks").
-///
-/// The fixture gives the guild five real ranks, so five of the ten are empty strings. A parser
-/// that read a count, or that stopped at the guild's real rank count, would land in the middle of
-/// the five-`u32` emblem block — which is why the emblem values here are all distinct: getting
-/// them back in order is the proof the ten were consumed.
+/// `SMSG_GUILD_QUERY_RESPONSE` always carries ten rank-name cstrings, not a counted list (vmangos
+/// `Server/Packets/Guild.cpp:118-131`); the distinct emblem values after them catch a short read.
 #[test]
 fn guild_query_response_always_carries_ten_rank_names() {
     let mut body = Vec::new();
@@ -193,7 +163,7 @@ fn guild_query_response_always_carries_ten_rank_names() {
         body.extend_from_slice(name);
         body.push(0);
     }
-    // The five ranks this guild never created: an empty string each — a bare NUL, not absent.
+    // The five uncreated ranks: an empty string each, a bare NUL, not absent.
     body.extend_from_slice(&[0u8; GUILD_RANKS_MAX_COUNT - 5]);
     body.extend_from_slice(&1u32.to_le_bytes()); // emblemStyle
     body.extend_from_slice(&2u32.to_le_bytes()); // emblemColor
@@ -215,7 +185,6 @@ fn guild_query_response_always_carries_ten_rank_names() {
         &["", "", "", "", ""],
         "the five uncreated ranks are empty strings on the wire"
     );
-    // The emblem block landing intact is what proves all ten strings were consumed.
     assert_eq!(response.emblem_style, 1, "emblemStyle — the desync canary");
     assert_eq!(response.emblem_color, 2);
     assert_eq!(response.border_style, 3);
@@ -228,13 +197,8 @@ fn guild_query_response_always_carries_ten_rank_names() {
     }
 }
 
-/// "No such guild" has no flag of its own: the answer is a normal, complete
-/// `SMSG_GUILD_QUERY_RESPONSE` whose **guild name is empty**. The reference client branches on
-/// exactly that (`0x5552ae test al,al` → cache insert `0x561070` vs cache remove `0x561390`,
-/// wow-re `system/ui/scratch/guild-roster-wire.md`) and consumes the whole record either way.
-///
-/// So the not-found shape must still parse end to end — all ten rank strings and the emblem block
-/// included — or a consumer keying off the empty name would be reading a half-parsed record.
+/// "No such guild" is a complete `SMSG_GUILD_QUERY_RESPONSE` with an empty name: the reference
+/// branches on it (`0x5552ae`) and still consumes the whole record.
 #[test]
 fn guild_query_response_reports_no_such_guild_as_an_empty_name() {
     let mut body = Vec::new();
@@ -256,11 +220,8 @@ fn guild_query_response_reports_no_such_guild_as_an_empty_name() {
     }
 }
 
-/// Append one `SMSG_GUILD_ROSTER` member per vmangos Server/Packets/Guild.cpp:155-172.
-///
-/// `last_online` is passed explicitly rather than derived from `presence`, so the *fixture* states
-/// the wire rule independently of the parser under test: an offline member carries the float, an
-/// online one does not.
+/// Append one `SMSG_GUILD_ROSTER` member (vmangos `Server/Packets/Guild.cpp:155-172`); the caller
+/// passes `last_online` itself, `Some` only for an offline member.
 fn push_member(
     body: &mut Vec<u8>,
     guid: u64,
@@ -291,8 +252,8 @@ fn push_member(
     body.push(0);
 }
 
-/// Append an `SMSG_GUILD_ROSTER` head (Server/Packets/Guild.cpp:143-153): member count, MOTD, info
-/// text, then the counted rank-rights array.
+/// An `SMSG_GUILD_ROSTER` head (Server/Packets/Guild.cpp:143-153): member count, MOTD, info text,
+/// then the counted rank-rights array.
 fn roster_head(member_count: u32, motd: &str, info: &str, rank_rights: &[u32]) -> Vec<u8> {
     let mut body = Vec::new();
     body.extend_from_slice(&member_count.to_le_bytes());
@@ -307,15 +268,9 @@ fn roster_head(member_count: u32, motd: &str, info: &str, rank_rights: &[u32]) -
     body
 }
 
-/// **The one that matters.** `SMSG_GUILD_ROSTER`'s `f32 lastOnlineTime` is on the wire only when
-/// the member's presence byte is `0` (vmangos Server/Packets/Guild.cpp:164-165, and independently
-/// Guild/Guild.cpp:793-794's size accounting, which decides where the sender truncates).
-///
-/// The fixture is deliberately **online, offline, online**, and the assertions that count are on
-/// the *third* member: it is the only one that can show the parse **re-synchronising** after a
-/// record of a different width. Getting one member's own fields right proves the field list; only
-/// a member that follows a wider one proves the stride. Mutation-checked — reading the float
-/// unconditionally fails this test (and the officer-note one) on exactly those assertions.
+/// `SMSG_GUILD_ROSTER`'s `f32 lastOnlineTime` is sent only when the presence byte is 0 (vmangos
+/// `Server/Packets/Guild.cpp:164-165`); the third member, after a wider offline one, checks the
+/// parse stays in step.
 #[test]
 fn guild_roster_conditional_float_keeps_later_members_in_sync() {
     let mut body = roster_head(
@@ -324,7 +279,6 @@ fn guild_roster_conditional_float_keeps_later_members_in_sync() {
         "We are a guild.",
         &[guild_rank_right::ALL, 0x0000_019F, 0x0000_0003],
     );
-    // 1. online — NO float.
     push_member(
         &mut body,
         0x1111,
@@ -338,7 +292,6 @@ fn guild_roster_conditional_float_keeps_later_members_in_sync() {
         "the GM",
         "trusted",
     );
-    // 2. offline — the float IS there. This is the member whose width differs.
     push_member(
         &mut body,
         0x2222,
@@ -352,7 +305,6 @@ fn guild_roster_conditional_float_keeps_later_members_in_sync() {
         "on holiday",
         "back next week",
     );
-    // 3. online again — the one that catches a desynchronised parse.
     push_member(
         &mut body,
         0x3333,
@@ -396,7 +348,6 @@ fn guild_roster_conditional_float_keeps_later_members_in_sync() {
     assert_eq!(bob.public_note, "on holiday");
     assert_eq!(bob.officer_note, "back next week");
 
-    // The whole point of the fixture: everything about the member *after* the wider one.
     let carol = &roster.members[2];
     assert_eq!(carol.guid, 0x3333, "third member guid — the desync canary");
     assert_eq!(carol.name, "Carol");
@@ -416,9 +367,6 @@ fn guild_roster_conditional_float_keeps_later_members_in_sync() {
     }
 }
 
-/// A roster with no members at all — the head alone, and nothing after the rank-rights array. The
-/// degenerate shape a brand-new or just-disbanded guild produces; the member loop must simply not
-/// run rather than reach for a first guid.
 #[test]
 fn guild_roster_with_no_members_is_just_the_head() {
     let body = roster_head(0, "", "", &[guild_rank_right::ALL]);
@@ -434,11 +382,8 @@ fn guild_roster_with_no_members_is_just_the_head() {
     }
 }
 
-/// Officer notes blanked because *we* lack `GR_RIGHT_VIEWOFFNOTE`: vmangos decides that once, per
-/// viewer (`canViewOfficerNote`, Guild/Guild.cpp:821), and writes `""` for every member
-/// (`:844`) — the cstring is still on the wire, just empty. Dropping the field for an
-/// unprivileged viewer would desynchronise exactly as the float does, so this pins that the
-/// terminator is read.
+/// A viewer without `GR_RIGHT_VIEWOFFNOTE` gets `""` for every officer note (vmangos
+/// `Guild/Guild.cpp:821`, `:844`): the cstring's NUL is still on the wire.
 #[test]
 fn guild_roster_reads_the_empty_officer_notes_of_an_unprivileged_viewer() {
     let mut body = roster_head(2, "motd", "info", &[guild_rank_right::ALL, 0x0000_0003]);
@@ -485,20 +430,13 @@ fn guild_roster_reads_the_empty_officer_notes_of_an_unprivileged_viewer() {
     }
 }
 
-/// The float's condition is the **whole presence byte** against zero, never `presence & ONLINE`.
-///
-/// That is the reference client's own predicate — it derives the flag with `0x4d0c12 test dl,dl` /
-/// `0x4d0c1d setne cl` and branches on the result (wow-re `system/ui/scratch/guild-roster-wire.md`),
-/// and the binary never tests bit `0x1` at all. The difference shows up on any presence byte with
-/// a bit set that we don't have a name for: a whole-byte test reads it as online and skips the
-/// float, a `& 0x1` mask reads it as offline and eats four bytes of the next field. This fixture
-/// uses `0x08` — a bit no 1.12 flag owns — as the member *before* a normal one, so a masking
-/// implementation desynchronises and fails on the second member.
+/// The float's condition is the whole presence byte against zero, as the reference tests it
+/// (`0x4d0c12`), never `presence & ONLINE`; `0x08`, a bit no 1.12 flag owns, still means online.
 #[test]
 fn roster_presence_is_tested_whole_byte_not_masked_against_online() {
     let mut body = roster_head(2, "", "", &[guild_rank_right::ALL]);
     push_member(
-        &mut body, 0x1111, 0x08, // an unnamed presence bit: online, so NO float
+        &mut body, 0x1111, 0x08, // an unnamed presence bit: online, so no float
         "Alice", 0, 60, 2, 1519, None, "first", "",
     );
     push_member(
@@ -532,17 +470,12 @@ fn roster_presence_is_tested_whole_byte_not_masked_against_online() {
     }
 }
 
-/// `SMSG_GUILD_EVENT`'s trailing guid rides on the **event id**, not on whether bytes remain.
-///
-/// The reference client's handler `0x5e7180` reads it in only the `0xc`/`0xd` arms of its jump
-/// table (wow-re RF-0077, `system/object-layer/scratch/rf77-smsg-chat-wire-order.md`), while
-/// vmangos *writes* one whenever `affectedPlayerGuid` is set — which its callers also do for
-/// `GE_JOINED` (Handlers/GuildHandler.cpp:218) and `GE_LEFT` (`:405`). benilla is the client, so
-/// the third case below is the interesting one: a `GE_JOINED` **with** vmangos's trailing guid
-/// still reports `guid: None`, and its params parse correctly, exactly as the reference does.
+/// `SMSG_GUILD_EVENT`'s trailing guid rides on the event id: the reference (`0x5e7180`) reads it
+/// only for 0x0c and 0x0d, though vmangos also writes one for `GE_JOINED` and `GE_LEFT`
+/// (`Handlers/GuildHandler.cpp:218`, `:405`).
 #[test]
 fn guild_event_trailing_guid_rides_on_the_event_id() {
-    // GE_SIGNED_ON (0x0c) — one param and the guid (Server/Packets/Guild.cpp:133-141).
+    // GE_SIGNED_ON (0x0c): one param and the guid (Server/Packets/Guild.cpp:133-141).
     let mut body = vec![guild_event::SIGNED_ON, 1];
     body.extend_from_slice(b"Alice\0");
     body.extend_from_slice(&0xDEAD_BEEFu64.to_le_bytes());
@@ -560,7 +493,7 @@ fn guild_event_trailing_guid_rides_on_the_event_id() {
         other => panic!("guild event decode: {other:?}"),
     }
 
-    // GE_MOTD (0x02) — one param, no guid at all on the wire.
+    // GE_MOTD (0x02): one param, no guid.
     let mut body = vec![guild_event::MOTD, 1];
     body.extend_from_slice(b"Raid at 8\0");
     let packet = messages::parse_server(opcode::SMSG_GUILD_EVENT, &body).unwrap();
@@ -573,8 +506,7 @@ fn guild_event_trailing_guid_rides_on_the_event_id() {
         other => panic!("expected GuildEvent, got {}", other.name()),
     }
 
-    // GE_JOINED (0x03) — vmangos DOES append a guid here; the reference client never reads it.
-    // The params must still be right, and the guid must be reported absent.
+    // GE_JOINED (0x03): vmangos appends a guid here, which the reference never reads.
     let mut body = vec![guild_event::JOINED, 1];
     body.extend_from_slice(b"Carol\0");
     body.extend_from_slice(&0x1234u64.to_le_bytes());
@@ -590,7 +522,7 @@ fn guild_event_trailing_guid_rides_on_the_event_id() {
         other => panic!("expected GuildEvent, got {}", other.name()),
     }
 
-    // GE_PROMOTION (0x00) — the three-param maximum (promoter, promoted, new rank name).
+    // GE_PROMOTION (0x00): the three-param maximum (promoter, promoted, new rank name).
     let mut body = vec![guild_event::PROMOTION, 3];
     body.extend_from_slice(b"Alice\0Bob\0Officer\0");
     match &messages::parse_server(opcode::SMSG_GUILD_EVENT, &body).unwrap() {
@@ -601,7 +533,7 @@ fn guild_event_trailing_guid_rides_on_the_event_id() {
         other => panic!("expected GuildEvent, got {}", other.name()),
     }
 
-    // GE_DISBANDED (0x08) — no params, no guid: the two-byte minimum body.
+    // GE_DISBANDED (0x08): no params, no guid, the two-byte minimum body.
     let packet = messages::parse_server(
         opcode::SMSG_GUILD_EVENT,
         &hx(concat!("08", "00")), // event, paramCount
@@ -617,12 +549,8 @@ fn guild_event_trailing_guid_rides_on_the_event_id() {
     }
 }
 
-/// `SMSG_GUILD_COMMAND_RESULT` (Server/Packets/Guild.cpp:96-101): `u32 command`, cstring, `u32
-/// result` — the string sits in the **middle**, which is the field order to get wrong.
-///
-/// The two cases here are the pair that share result `0x08`: with `QUIT` it is "the guild master
-/// cannot leave", with anything else it is "you don't have permission". Carrying the command tag
-/// through is what keeps them apart.
+/// `SMSG_GUILD_COMMAND_RESULT` (Server/Packets/Guild.cpp:96-101): `u32` command, a cstring in the
+/// middle, `u32` result.
 #[test]
 fn guild_command_result_wire() {
     let mut body = Vec::new();
@@ -643,8 +571,8 @@ fn guild_command_result_wire() {
         other => panic!("guild command result decode: {other:?}"),
     }
 
-    // The collision: 0x08 under QUIT is ERR_GUILD_LEADER_LEAVE, under anything else it is
-    // ERR_GUILD_PERMISSIONS (vmangos Guild/Guild.h:106-107) — and both carry an empty string.
+    // Result 0x08 is ERR_GUILD_LEADER_LEAVE under QUIT and ERR_GUILD_PERMISSIONS otherwise
+    // (vmangos Guild/Guild.h:106-107); the command tag tells them apart.
     assert_eq!(
         guild_command_error::LEADER_LEAVE,
         guild_command_error::PERMISSIONS
@@ -699,8 +627,8 @@ fn guild_info_wire() {
     }
 }
 
-/// The two notification packets: `SMSG_GUILD_INVITE` (Server/Packets/Guild.cpp:85-89) is inviter
-/// then guild, two cstrings; `SMSG_GUILD_DECLINE` (`:91-94`) is one cstring, the decliner.
+/// `SMSG_GUILD_INVITE` (Server/Packets/Guild.cpp:85-89) is inviter then guild, two cstrings;
+/// `SMSG_GUILD_DECLINE` (`:91-94`) is one cstring, the decliner.
 #[test]
 fn guild_invite_and_decline_wire() {
     let packet = messages::parse_server(
diff --git a/crates/benilla-protocol/tests/handshake.rs b/crates/benilla-protocol/tests/handshake.rs
index dfa07487..1812d197 100644
--- a/crates/benilla-protocol/tests/handshake.rs
+++ b/crates/benilla-protocol/tests/handshake.rs
@@ -1,10 +1,6 @@
-//! The world handshake against a fake server, exercising [`WorldSession::connect`] over a real
-//! socket with real header obfuscation.
-//!
-//! What these pin down is the packet *ordering* tolerance the handshake needs. A server does not
-//! promise `SMSG_AUTH_RESPONSE` is the first encrypted packet — it interleaves its own traffic —
-//! and one of those interleaved packets, `SMSG_WARDEN_DATA`, means the server runs an anticheat we
-//! cannot answer and must be refused at login rather than entered and kicked ~30 s later.
+//! The world handshake over a real socket against a fake server: packets may precede
+//! `SMSG_AUTH_RESPONSE`. Deviation: `SMSG_WARDEN_DATA` refuses the login, because benilla cannot
+//! answer Warden and the server kicks a client that stays silent about 30 s later.
 
 use std::io::{Read, Write};
 use std::net::{TcpListener, TcpStream};
@@ -18,8 +14,8 @@ use benilla_srp::SESSION_KEY_LENGTH;
 const SESSION_KEY: [u8; SESSION_KEY_LENGTH] = [7u8; SESSION_KEY_LENGTH];
 const SERVER_SEED: u32 = 0xDEAD_BEEF;
 
-/// Write one server packet: 2-byte BE size (counts the opcode, not itself) + 2-byte LE opcode,
-/// encrypted once `crypto` is in play, then the plaintext body.
+/// Write one server packet: `u16` BE size (opcode plus body) and `u16` LE opcode, encrypted once
+/// `crypto` is set, then the plaintext body.
 fn send(stream: &mut TcpStream, crypto: Option<&mut HeaderCrypto>, opcode: u16, body: &[u8]) {
     let size = (body.len() + 2) as u16;
     let s = size.to_be_bytes();
@@ -41,8 +37,8 @@ fn read_auth_session(stream: &mut TcpStream) {
     stream.read_exact(&mut body).unwrap();
 }
 
-/// Stand up a fake world server that sends `pre` (opcode, body) pairs — encrypted, in order —
-/// before a successful `SMSG_AUTH_RESPONSE`. Returns the address to point `connect` at.
+/// A fake world server that sends the `pre` packets, encrypted and in order, before a successful
+/// `SMSG_AUTH_RESPONSE`; returns its address.
 fn fake_server(pre: Vec<(u16, Vec<u8>)>) -> String {
     let listener = TcpListener::bind("127.0.0.1:0").unwrap();
     let addr = listener.local_addr().unwrap().to_string();
@@ -71,15 +67,13 @@ fn fake_server(pre: Vec<(u16, Vec<u8>)>) -> String {
     addr
 }
 
-/// The plain case: `SMSG_AUTH_RESPONSE` leads, the handshake completes.
 #[test]
 fn auth_response_alone_completes_the_handshake() {
     let addr = fake_server(vec![]);
     assert!(WorldSession::connect(&addr, "one", SESSION_KEY).is_ok());
 }
 
-/// A server interleaving its own traffic ahead of the auth response must not fail the handshake —
-/// the real one does this, and demanding AUTH_RESPONSE lead once broke login outright.
+/// The server interleaves its own packets ahead of the auth response.
 #[test]
 fn packets_ahead_of_the_auth_response_are_skipped() {
     let addr = fake_server(vec![
@@ -89,8 +83,6 @@ fn packets_ahead_of_the_auth_response_are_skipped() {
     assert!(WorldSession::connect(&addr, "one", SESSION_KEY).is_ok());
 }
 
-/// Warden among them is refused, with the error the login screen shows — never a session that
-/// would be kicked once the server's response clock expires.
 #[test]
 fn a_warden_server_is_refused_at_the_handshake() {
     let addr = fake_server(vec![(opcode::SMSG_WARDEN_DATA, vec![0u8; 16])]);
diff --git a/crates/benilla-protocol/tests/instance.rs b/crates/benilla-protocol/tests/instance.rs
index 06878fec..1c70ed7d 100644
--- a/crates/benilla-protocol/tests/instance.rs
+++ b/crates/benilla-protocol/tests/instance.rs
@@ -1,11 +1,5 @@
-//! Oracle-free golden tests for the instance/raid **lockout message** family (decision 1748): the
-//! six inbound bodies, the one outbound body, and the two enums the client's own dispatch tables
-//! define.
-//!
-//! Every layout here is the *client's* read order, taken from the five handlers registered at
-//! `0x498680`-`0x4986cf` plus `0x4e7e60`, and cross-checked against vmangos
-//! `Server/Packets/Misc.{h,cpp}`. `hx(...)` bodies round-tripped through `parse_server`, the
-//! idiom of `tests/bank.rs`.
+//! The instance lockout messages in the reference's read order (handlers registered at
+//! `0x498680`-`0x4986cf` and `0x4e7e60`; vmangos `Server/Packets/Misc.cpp`).
 
 use benilla_protocol::events::{decode, SessionEvent};
 use benilla_protocol::messages::{
@@ -20,17 +14,14 @@ fn hx(s: &str) -> Vec<u8> {
         .collect()
 }
 
-/// `CMSG_RESET_INSTANCES` — empty, both in the binding (`0x48a6b0` writes no field before its
-/// send) and in vmangos's handler (which reads none).
+/// `CMSG_RESET_INSTANCES` is empty in the reference (`0x48a6b0`) and in vmangos's handler.
 #[test]
 fn reset_instances_body_is_empty() {
     assert_eq!(messages::reset_instances(), Vec::<u8>::new());
 }
 
-/// `SMSG_RAID_INSTANCE_MESSAGE`: `u32 type`, `u32 mapId`, `u32 secondsUntilReset`, in that order
-/// — the client reads the three at `0x49e1cd`/`0x49e1d8`/`0x49e1e3` and uses the SECOND for the
-/// `Map.dbc` lookup, which is what fixes the order (a type/map swap would name the wrong instance
-/// and pick the wrong template, silently).
+/// `SMSG_RAID_INSTANCE_MESSAGE`: `u32` type, map id and seconds until reset, in that order; the
+/// reference reads them at `0x49e1cd`/`0x49e1d8`/`0x49e1e3` and looks up `Map.dbc` by the second.
 #[test]
 fn raid_instance_message_wire() {
     // type 4 (WELCOME), map 409 (Molten Core), 3 d 2 h 0 m = 266400 s.
@@ -64,9 +55,8 @@ fn raid_instance_message_wire() {
     );
 }
 
-/// The four warning types and the two the reference's jump table drops. `dec eax; cmp eax,3; ja`
-/// at `0x49e246` means 0 and ≥ 5 leave the handler in silence — including the value later clients
-/// call `RAID_INSTANCE_EXPIRED` (5).
+/// The four warning types; the reference's jump table (`0x49e246`) prints nothing for 0 or 5 and
+/// up, including 5, which later clients call `RAID_INSTANCE_EXPIRED`.
 #[test]
 fn raid_instance_warning_types() {
     use RaidInstanceWarning as W;
@@ -103,9 +93,7 @@ fn instance_reset_wire() {
     assert!(messages::parse_server(opcode::SMSG_INSTANCE_RESET, &hx("2400")).is_err());
 }
 
-/// `SMSG_INSTANCE_RESET_FAILED`: `u32 reason` FIRST, then `u32 mapId` (`0x49e54d`/`0x49e558`) —
-/// the opposite order to the reset success packet's single field, and the pair vmangos writes in
-/// `InstanceResetFailed::AppendBodyTo`.
+/// `SMSG_INSTANCE_RESET_FAILED`: `u32` reason first, then `u32` map id (`0x49e54d`/`0x49e558`).
 #[test]
 fn instance_reset_failed_wire() {
     let body = hx(concat!("01000000", "24000000")); // OFFLINE, Deadmines
@@ -128,9 +116,8 @@ fn instance_reset_failed_wire() {
     }
 }
 
-/// The three refusal reasons, and the silent tail. vmangos's own enum names 3
-/// `INSTANCERESET_FAIL_SILENTLY` "as well as any above this"; the reference falls through those
-/// to its chat call with an uninitialized buffer, which we deliberately do not reproduce.
+/// The three refusal reasons; vmangos names 3 and up `INSTANCERESET_FAIL_SILENTLY`. Deviation:
+/// for those we print nothing, because the reference prints an uninitialized buffer.
 #[test]
 fn instance_reset_failure_reasons() {
     use InstanceResetFailure as F;
@@ -145,9 +132,8 @@ fn instance_reset_failure_reasons() {
     assert_eq!(F::Zoning.token(), "INSTANCE_RESET_FAILED_ZONING");
 }
 
-/// The three bare-`u32` bodies that are not a map name: the save-created flag (`0x4e7e6c`), the
-/// last-instance map (`0x49e676`) and the ownership flag (`0x49e6c6`). The ownership flag is
-/// narrowed to a bool at the event layer because the reference's reader is a `test eax,eax`.
+/// Three bare `u32` bodies: the save-created flag (`0x4e7e6c`), the last-instance map
+/// (`0x49e676`) and the ownership flag (`0x49e6c6`), a bool: the reference tests it against zero.
 #[test]
 fn save_created_last_instance_and_ownership_wire() {
     let p = messages::parse_server(opcode::SMSG_INSTANCE_SAVE_CREATED, &hx("00000000")).unwrap();
diff --git a/crates/benilla-protocol/tests/items.rs b/crates/benilla-protocol/tests/items.rs
index 1c9168b2..1927e352 100644
--- a/crates/benilla-protocol/tests/items.rs
+++ b/crates/benilla-protocol/tests/items.rs
@@ -1,7 +1,5 @@
-//! Item wire tests (mirrors `src/messages/items.rs`): the query request/response roundtrip,
-//! inventory-change-failure (level refusal vs. plain), the GM-command system chat shape, and the
-//! full `SMSG_ITEM_QUERY_SINGLE_RESPONSE` field walk (hit + undiscovered miss). Split out of the
-//! former `tests/messages.rs` — see `tests/common` for the shared fixtures and methodology note.
+//! The item wire: the query request and its full template reply, `CMSG_USE_ITEM`'s target forms,
+//! equip and open, and the inventory-change refusals.
 
 mod common;
 
@@ -12,29 +10,20 @@ use common::hx;
 
 #[test]
 fn item_query_wire() {
-    // CMSG_ITEM_QUERY_SINGLE: entry u32 + full item guid (vmangos QueryItem::ReadFromWorldPacket).
+    // CMSG_ITEM_QUERY_SINGLE: `u32` entry and the full item guid (vmangos `QueryItem`).
     assert_eq!(messages::item_query(117, 0), hx("750000000000000000000000"));
 
     // CMSG_USE_ITEM (vmangos UseItem::ReadFromWorldPacket): bagIndex, slot, spellSlot, then a
-    // self-shaped target block (u16 mask 0). Backpack slot 1 = bag 255 + player-array slot 23.
+    // target block, here self (`u16` mask 0). Backpack slot 1 is bag 255, player slot 23.
     assert_eq!(
         messages::use_item(255, 23, 0, messages::UseItemTarget::SelfImplicit),
         hx("ff17000000")
     );
 
-    // The KEY-IN-A-LOCK form (decision 0769): the same three bytes, then a SpellCastTargets with
-    // mask TARGET_FLAG_GAMEOBJECT (0x0800) and the object's PACKED guid. This is the packet the
-    // real client sends for a key (wow-re cursor-system.md §8.4: sender 0x6e54f0's item arm ->
-    // 0x6e57d8 push 0xab) and the only one vmangos will open a KEY-slot lock for
-    // (Spell::CanOpenLock requires m_CastItem, Spell.cpp:7892).
-    //
-    // `TARGET_FLAG_LOCKED` (0x4000) is deliberately NOT here (decision 0939, correcting 0769): it
-    // is a bit of the *targeting word* `0xcecac0` that `BindTarget 0x6e5b40`'s GameObject arm reads
-    // and clears (`6e5f60`/`6e5f70`) while writing only `0x800` to the outgoing mask (`6e5f69`).
-    // A whole-image census of writes to `0xceac5c` finds no `0x4000` anywhere.
-    //
-    // Keyring slot 1 = bag 255 + player-array slot 81 (0x51). The guid 0xF110000C1F00A3B2 has two
-    // zero bytes (indices 2 and 5), so it packs to mask 0xDB + the other six, low byte first.
+    // A key in a lock: TARGET_FLAG_GAMEOBJECT (0x0800) and the object's packed guid, as the
+    // reference sends it (`0x6e57d8`); vmangos opens a key lock only for a cast item
+    // (Spell.cpp:7892). TARGET_FLAG_LOCKED (0x4000) never reaches the wire mask (`0x6e5f69`).
+    // Keyring slot 1 is bag 255, player slot 81; the guid's two zero bytes pack to mask 0xDB.
     assert_eq!(
         messages::use_item(
             255,
@@ -45,45 +34,36 @@ fn item_query_wire() {
         hx("ff51000008dbb2a31f0c10f1"),
     );
 
-    // The packed form really does drop zero bytes: guid 1 is mask 0x01 + a single byte, and the
-    // spellSlot ordinal rides in the third byte.
+    // Packed guid 1 is mask 0x01 and one byte; the spellSlot ordinal is the third byte.
     assert_eq!(
         messages::use_item(255, 81, 2, messages::UseItemTarget::Object(1)),
         hx("ff510200080101")
     );
 
-    // The UNIT form (decision 0914): an item whose spell binds a unit the way a spell's does — a
-    // bandage, a soulstone — writes TARGET_FLAG_UNIT (0x0002) + the packed guid, the SAME block a
-    // CMSG_CAST_SPELL writes. In the real client one builder serves both opcodes: SendCast
-    // 0x6e54f0 picks 0xab-vs-0x12e from its item discriminator and then writes ArmCast's block.
+    // A unit target (a bandage, a soulstone): TARGET_FLAG_UNIT (0x0002) and the packed guid, the
+    // block CMSG_CAST_SPELL writes; the reference builds both in one sender (`0x6e54f0`).
     assert_eq!(
         messages::use_item(255, 24, 0, messages::UseItemTarget::Unit(1)),
         hx("ff180002000101")
     );
 
-    // The DEST form (decision 0914): the targeting-cursor commit for a THROWN item — dynamite, a
-    // grenade, the Goblin Mortar. TARGET_FLAG_DEST_LOCATION (0x0040) + three f32 WoW coords, the
-    // same tail cast_spell_at_dest writes. 1.0f32 = 0x3f800000, 2.0 = 0x40000000, 3.0 = 0x40400000.
+    // A thrown item (dynamite, a grenade): TARGET_FLAG_DEST_LOCATION (0x0040) and three `f32`
+    // coords, the tail `cast_spell_at_dest` writes.
     assert_eq!(
         messages::use_item(19, 3, 1, messages::UseItemTarget::Dest([1.0, 2.0, 3.0])),
         hx("13030140000000803f0000004000004040")
     );
 
-    // The SOURCE form (decision 2218): the same terrain click one bit over — the three shipped
-    // items carrying spell 265 "Area Death (TEST)" (Martin Fury 17, plus 192 and 5417), whose
-    // `Targets` is a bare 0x20. `BindLocation 0x6e60f0` writes SPELLCAST+0x30 and ORs 0x0020
-    // where its dest arm writes +0x3c and ORs 0x0040; vmangos reads this triple first. Martin
-    // Fury is worn, so the wire position is the player array (255) + EQUIPMENT_SLOT_BODY (3).
+    // The source form (0x0020), as for spell 265 on Martin Fury: the reference (`0x6e60f0`) sets
+    // 0x0020 where a dest sets 0x0040. Martin Fury is worn, so bag 255, slot 3 (body).
     assert_eq!(
         messages::use_item(255, 3, 0, messages::UseItemTarget::Source([1.0, 2.0, 3.0])),
         hx("ff030020000000803f0000004000004040")
     );
 
-    // The ITEM form (decision 0923): the targeting cursor's item commit — a poison / sharpening
-    // stone / weapon oil applied to the weapon you clicked. TARGET_FLAG_ITEM (0x0010) + the packed
-    // guid, the same block cast_spell_on_item writes; the reference reaches both through the one
-    // BindTarget 0x6e5b40 (0x495d60 @ 496056). Packed guid 0xF1500000_0000ABCD = mask 0xc3 (bytes
-    // 0, 1, 6, 7 nonzero) then those four bytes.
+    // An item target (a poison or oil on a weapon): TARGET_FLAG_ITEM (0x0010) and the packed
+    // guid, as `cast_spell_on_item` writes (reference `0x6e5b40`); 0xF150_0000_0000_ABCD packs to
+    // mask 0xC3 and four bytes.
     assert_eq!(
         messages::use_item(255, 24, 0, messages::UseItemTarget::Item(1)),
         hx("ff180010000101")
@@ -101,12 +81,9 @@ fn item_query_wire() {
     // CMSG_AUTOEQUIP_ITEM (vmangos AutoEquipItem::ReadFromWorldPacket): bagIndex, slot.
     assert_eq!(messages::auto_equip_item(255, 25), hx("ff19"));
 
-    // CMSG_OPEN_ITEM (vmangos OpenItem::ReadFromWorldPacket, Server/Packets/Spell.cpp:19-23):
-    // bagIndex, slot — and NOTHING else (no spell ordinal, no targets block; opening is not a
-    // cast). The same two bytes as auto-equip under a different opcode: this is the fork a
-    // clam/lockbox/gift takes instead of USE_ITEM, and the only one the server answers with
-    // SendLoot on the item's own guid. Backpack slot 3 = bag 255 + player-array slot 25; an item
-    // inside an equipped bag addresses that bag's own player-array slot (19..22) + inner slot.
+    // CMSG_OPEN_ITEM (vmangos Server/Packets/Spell.cpp:19-23): bagIndex and slot only, no cast
+    // block. A clam, lockbox or gift uses it; the server answers with loot on the item's guid.
+    // An item in an equipped bag addresses that bag's player slot (19..22) and its inner slot.
     assert_eq!(messages::open_item(255, 25), hx("ff19"));
     assert_eq!(messages::open_item(19, 0), hx("1300"));
 
@@ -126,7 +103,7 @@ fn item_query_wire() {
         } => {
             assert_eq!((reason, required_level), (1, Some(10)));
             assert_eq!(item_guid, 0x4000_0000_0000_0042);
-            // The trailing byte is the destination BAG's absolute player slot, not a subslot.
+            // The trailing byte is the destination bag's absolute player slot, not a subslot.
             assert_eq!(bag_slot, 0);
         }
         other => panic!("level refusal, got {}", other.name()),
@@ -145,8 +122,8 @@ fn item_query_wire() {
         other => panic!("plain refusal, got {}", other.name()),
     }
 
-    // SMSG_MESSAGECHAT, the system shape (type 0x0A: guid, len-prefixed text incl. NUL, tag) —
-    // the GM-command feedback channel (live-verified: '.additem' answers exactly this shape).
+    // SMSG_MESSAGECHAT's system shape (type 0x0A: guid, length-prefixed text, tag), the shape
+    // GM commands such as `.additem` answer with.
     let sys = messages::parse_server(
         messages::opcode::SMSG_MESSAGECHAT,
         &hx("0a0000000000000000000000000600000068656c6c6f0000"),
@@ -161,13 +138,8 @@ fn item_query_wire() {
     }
 }
 
-/// `SMSG_ITEM_QUERY_SINGLE_RESPONSE`, hit: the full 1.12.1 item template, byte-exact (VERIFIED
-/// field order vmangos `HandleItemQuerySingleOpcode`, `ItemHandler.cpp:269-415`; every
-/// `SUPPORTED_CLIENT_BUILD` conditional there is included for build 5875) — decision 0274 P1's
-/// tooltip builder needs every line. A main-hand sword exercising every filtered/mirrored shape at
-/// once: 2 of 5 damage blocks, 3 of 10 stats, 2 of 6 resistances, 2 of 5 spells (one ON_USE trigger
-/// 0, one ON_EQUIP trigger 1), a nonempty description, and real requirement/durability values.
-/// Every field carries a distinct value so a transposed or misaligned read fails the assert below.
+/// `SMSG_ITEM_QUERY_SINGLE_RESPONSE` in vmangos order (`ItemHandler.cpp:269-415`, build 5875
+/// branches), for a sword whose fields all differ so a misaligned read fails.
 #[test]
 fn item_query_response_full_weapon_golden() {
     use benilla_protocol::messages::{ItemDamage, ItemInfo, ItemSpellEntry, ItemUseSpell};
@@ -198,8 +170,7 @@ fn item_query_response_full_weapon_golden() {
     body.extend_from_slice(&1u32.to_le_bytes()); // Stackable
     body.extend_from_slice(&0u32.to_le_bytes()); // ContainerSlots
 
-    // 10x ItemStat { type, value } — 3 nonzero (one negative value proves signed reads), 7 empty
-    // (dropped by the nonzero filter).
+    // 10 ItemStat { type, value }: empty ones are dropped; the negative one checks signed reads.
     let stat_slots: [(u32, i32); 10] = [
         (4, 15), // STRENGTH +15
         (7, 20), // STAMINA +20
@@ -217,8 +188,8 @@ fn item_query_response_full_weapon_golden() {
         body.extend_from_slice(&stat_value.to_le_bytes());
     }
 
-    // 5x Damage { min f32, max f32, type u32 } — 2 real blocks (physical + a secondary Fire line),
-    // 3 empty (dropped by the `max > 0` filter). Block 0 also mirrors into dmg_min/dmg_max/dmg_type.
+    // 5 Damage { f32 min, f32 max, u32 type }: blocks with `max > 0` are kept, and block 0 also
+    // fills dmg_min/dmg_max/dmg_type.
     let dmg_slots: [(f32, f32, u32); 5] = [
         (12.0, 22.0, 0), // physical
         (3.0, 7.0, 2),   // Fire
@@ -233,7 +204,7 @@ fn item_query_response_full_weapon_golden() {
     }
 
     body.extend_from_slice(&15u32.to_le_bytes()); // Armor
-                                                  // Resistances: Holy/Fire/Nature/Frost/Shadow/Arcane — 2 of 6 nonzero.
+                                                  // Holy, Fire, Nature, Frost, Shadow, Arcane.
     for r in [0i32, 8, 0, 0, 12, 0] {
         body.extend_from_slice(&r.to_le_bytes());
     }
@@ -241,10 +212,9 @@ fn item_query_response_full_weapon_golden() {
     body.extend_from_slice(&2u32.to_le_bytes()); // AmmoType
     body.extend_from_slice(&1.5f32.to_le_bytes()); // RangedModRange
 
-    // 5x Spell block { SpellId, SpellTrigger, SpellCharges, Cooldown, Category, CategoryCooldown }
-    // — slot 0 ON_USE (a lone -1 use-cooldown next to a resolved category pair, the mixed shape
-    // vmangos can send), slot 1 ON_EQUIP (a plain passive, no cooldown), slots 2-4 the server's own
-    // unresolved-slot sentinel (0,0,0,-1,0,-1).
+    // 5 spell blocks { id, trigger, charges, cooldown, category, categoryCooldown }: ON_USE with
+    // a -1 cooldown beside a real category (a mix vmangos sends), ON_EQUIP, then the server's
+    // empty-slot sentinel (0, 0, 0, -1, 0, -1).
     let spell_slots: [(u32, u32, i32, i32, u32, i32); 5] = [
         (17_251, 0, 0, -1, 4, 60_000),
         (671, 1, 0, 0, 0, 0),
@@ -379,14 +349,9 @@ fn item_query_response_full_weapon_golden() {
     }
 }
 
-/// `SMSG_ITEM_QUERY_SINGLE_RESPONSE`, hit: a minimal consumable (a potion). The server zeroes
-/// `subclass` for every `ITEM_CLASS_CONSUMABLE` row regardless of the DB value (VERIFIED vmangos
-/// `ItemHandler.cpp:300`) — that's a server-side rule, so this fixture just carries the
-/// already-zeroed wire byte; the parser itself has no class-conditional logic. What this exercises
-/// instead is the "everything empty" path the weapon golden above only partly covers: `stats`,
-/// `damages`, and 4 of 5 `spells` slots all read as real zeroed wire data that must land as **empty
-/// `Vec`s**, not get pushed as garbage entries — while the one real ON_USE slot still resolves both
-/// into `spells` and into the legacy `use_spell` accessor.
+/// A potion: zeroed stats, damages and spell slots land as empty `Vec`s while the ON_USE slot
+/// fills both `spells` and `use_spell`. The server zeroes a consumable's subclass (vmangos
+/// `ItemHandler.cpp:300`).
 #[test]
 fn item_query_response_consumable_all_zero_slots_are_empty_not_garbage() {
     use benilla_protocol::messages::{ItemInfo, ItemSpellEntry, ItemUseSpell};
@@ -428,7 +393,7 @@ fn item_query_response_consumable_all_zero_slots_are_empty_not_garbage() {
     body.extend_from_slice(&0u32.to_le_bytes()); // Delay
     body.extend_from_slice(&0u32.to_le_bytes()); // AmmoType
     body.extend_from_slice(&0f32.to_le_bytes()); // RangedModRange
-                                                 // Spell slot 0: the ON_USE heal; slots 1-4 the server's unresolved-slot sentinel.
+                                                 // Slot 0: the ON_USE heal; 1-4: empty sentinels.
     body.extend_from_slice(&2024u32.to_le_bytes()); // SpellId
     body.extend_from_slice(&0u32.to_le_bytes()); // SpellTrigger: ON_USE
     body.extend_from_slice(&0u32.to_le_bytes()); // SpellCharges
@@ -536,8 +501,7 @@ fn item_query_response_consumable_all_zero_slots_are_empty_not_garbage() {
     }
 }
 
-/// `SMSG_ITEM_QUERY_SINGLE_RESPONSE`, miss: the lone entry with the top bit set (vmangos
-/// undiscovered/unknown-entry branch) — the same shape as the creature miss.
+/// A miss is the lone entry with the top bit set (vmangos's unknown-entry branch).
 #[test]
 fn item_query_response_miss() {
     let fail = messages::parse_server(
diff --git a/crates/benilla-protocol/tests/mail.rs b/crates/benilla-protocol/tests/mail.rs
index b8af7981..4a2054c6 100644
--- a/crates/benilla-protocol/tests/mail.rs
+++ b/crates/benilla-protocol/tests/mail.rs
@@ -1,10 +1,5 @@
-//! Oracle-free golden tests for the mail arc's protocol layer (decision 0544 phase P0): the
-//! `CMSG_GET_MAIL_LIST`/`CMSG_SEND_MAIL`/take-money/take-item/mark-read/return/delete/
-//! `CMSG_ITEM_TEXT_QUERY` send verbs, the `SMSG_MAIL_LIST_RESULT` inbox page (all three sender
-//! shapes + the always-present item block), `SMSG_SEND_MAIL_RESULT`'s three tail shapes, the
-//! letter-body fetch reply, and the arrival pair (`SMSG_RECEIVED_MAIL` / `MSG_QUERY_NEXT_MAIL_TIME`).
-//! Same idioms as `tests/trainer.rs` — `hx(...)` golden CMSG bodies, hand-built SMSG bodies
-//! round-tripped through `parse_server`, and a `decode()` bridge assertion.
+//! The mail wire: the send verbs, the inbox page with its three sender shapes, the send result's
+//! tails, the letter-body fetch, and the arrival notices.
 
 use benilla_protocol::events::{decode, SessionEvent};
 use benilla_protocol::messages::{
@@ -30,8 +25,6 @@ fn mail_send_bodies_golden() {
         "CMSG_GET_MAIL_LIST body"
     );
 
-    // CMSG_SEND_MAIL: u64 mailbox, cstr receiver, cstr subject, cstr body, u32 stationery, u32
-    // package, u64 itemGuid, u32 money, u32 COD, then the 9-byte zero tail (u64 0 + u8 0).
     assert_eq!(
         messages::send_mail(
             MAILBOX,
@@ -68,7 +61,7 @@ fn mail_send_bodies_golden() {
     assert_eq!(messages::mail_return_to_sender(MAILBOX, 77), golden);
     assert_eq!(messages::mail_delete(MAILBOX, 77), golden);
 
-    // CMSG_MAIL_CREATE_TEXT_ITEM: the shared shape + u32 mailTemplateId(0) (vmangos
+    // CMSG_MAIL_CREATE_TEXT_ITEM: the shared shape, then `u32` mailTemplateId 0 (vmangos
     // `MailCreateTextItem::ReadFromWorldPacket`).
     assert_eq!(
         messages::mail_create_text_item(MAILBOX, 77),
@@ -84,9 +77,8 @@ fn mail_send_bodies_golden() {
     );
 }
 
-/// Append one 8-byte-fixed item block (the tail every `SMSG_MAIL_LIST_RESULT` row always carries,
-/// zeroed when the mail has no attachment): entry, permEnchant, randomPropId, suffixFactor u32 ×4,
-/// stackCount u8, spellCharges/durabilityMax/durabilityCur u32 ×3.
+/// Append the item block every `SMSG_MAIL_LIST_RESULT` row carries, zeroed without an attachment:
+/// four `u32`, a `u8` stack count, then three `u32`.
 fn push_item_block(
     body: &mut Vec<u8>,
     entry: u32,
@@ -110,14 +102,11 @@ fn push_item_block(
 
 #[test]
 fn mail_list_result_wire() {
-    // SMSG_MAIL_LIST_RESULT: u8 count, then per row: u32 messageId, u8 messageType, the sender
-    // branch keyed by messageType, cstr subject, u32 itemTextId, u32 package(dropped), u32
-    // stationery, the item block (ALWAYS present), u32 money, u32 COD, u32 checked, f32
-    // expireDays, u32 mailTemplateId. Three rows exercise all three sender shapes.
+    // SMSG_MAIL_LIST_RESULT: `u8` count, then rows whose sender field depends on the message type
+    // and whose item block is always present.
     let mut body = vec![3u8]; // count
 
-    // Row 1 — MAIL_NORMAL: a player sender (guid), an attached item, money + COD + checked flags,
-    // a fractional expire_days.
+    // MAIL_NORMAL: the sender is a player guid.
     body.extend_from_slice(&1u32.to_le_bytes()); // messageId
     body.push(mail_message_type::NORMAL);
     body.extend_from_slice(&0x0000_0001_0000_00AAu64.to_le_bytes()); // sender guid
@@ -132,7 +121,7 @@ fn mail_list_result_wire() {
     body.extend_from_slice(&2.5f32.to_le_bytes()); // expire_days
     body.extend_from_slice(&0u32.to_le_bytes()); // mailTemplateId
 
-    // Row 2 — MAIL_AUCTION: a u32 sender id, no item (all-zero item block).
+    // MAIL_AUCTION: the sender is a `u32` id; no item, so an all-zero item block.
     body.extend_from_slice(&2u32.to_le_bytes());
     body.push(mail_message_type::AUCTION);
     body.extend_from_slice(&42u32.to_le_bytes()); // sender id (auction id)
@@ -147,7 +136,7 @@ fn mail_list_result_wire() {
     body.extend_from_slice(&1.0f32.to_le_bytes()); // expire_days
     body.extend_from_slice(&0u32.to_le_bytes());
 
-    // Row 3 — MAIL_ITEM: NO sender bytes at all.
+    // MAIL_ITEM: no sender bytes at all.
     body.extend_from_slice(&3u32.to_le_bytes());
     body.push(mail_message_type::ITEM);
     body.extend_from_slice(b"Welcome\0");
@@ -216,7 +205,6 @@ fn mail_list_result_wire() {
         other => panic!("mail list, got {}", other.name()),
     }
 
-    // The decode() bridge carries the wire rows through unchanged.
     match decode(packet).pop().unwrap() {
         SessionEvent::MailList { mails } => assert_eq!(mails.len(), 3),
         other => panic!("mail list event, got {other:?}"),
@@ -225,7 +213,7 @@ fn mail_list_result_wire() {
 
 #[test]
 fn send_mail_result_wire() {
-    // Plain shape: action SEND, error OK — neither conditional tail rides.
+    // Action SEND, error OK: no tail.
     let mut plain = 1u32.to_le_bytes().to_vec();
     plain.extend_from_slice(&mail_action::SEND.to_le_bytes());
     plain.extend_from_slice(&mail_error::OK.to_le_bytes());
@@ -246,7 +234,6 @@ fn send_mail_result_wire() {
         }
         other => panic!("send mail result (plain), got {}", other.name()),
     }
-    // The decode() bridge, asserted on this shape.
     let packet = messages::parse_server(messages::opcode::SMSG_SEND_MAIL_RESULT, &plain).unwrap();
     match decode(packet).pop().unwrap() {
         SessionEvent::SendMailResult {
@@ -335,15 +322,13 @@ fn item_text_query_response_wire() {
 
 #[test]
 fn received_mail_wire() {
-    // SMSG_RECEIVED_MAIL: one f32 delay, the same countdown units as MSG_QUERY_NEXT_MAIL_TIME's
-    // reply (decision 0913 — the real client reads these four bytes as a float). vmangos writes
-    // them as `uint32(0)`, and 0x00000000 *is* 0.0f, so its only value decodes as "waiting now".
+    // SMSG_RECEIVED_MAIL: one `f32` delay, which the reference reads as a float; vmangos writes
+    // `uint32(0)`, the same bits as 0.0.
     let vmangos_body = 0u32.to_le_bytes();
     match messages::parse_server(messages::opcode::SMSG_RECEIVED_MAIL, &vmangos_body).unwrap() {
         ServerPacket::ReceivedMail { seconds } => assert_eq!(seconds, 0.0),
         other => panic!("received mail, got {}", other.name()),
     }
-    // A server that sends a real delay round-trips it.
     for seconds in [0.0f32, 120.0f32] {
         let body = seconds.to_le_bytes();
         let packet = messages::parse_server(messages::opcode::SMSG_RECEIVED_MAIL, &body).unwrap();
@@ -356,7 +341,7 @@ fn received_mail_wire() {
 
 #[test]
 fn query_next_mail_time_wire() {
-    // MSG_QUERY_NEXT_MAIL_TIME's reply: one f32 — 0.0 unread waiting, -86400.0 none.
+    // MSG_QUERY_NEXT_MAIL_TIME's reply: one `f32`, 0.0 for unread mail waiting, -86400.0 for none.
     for seconds in [0.0f32, -86400.0f32] {
         let body = seconds.to_le_bytes();
         match messages::parse_server(messages::opcode::MSG_QUERY_NEXT_MAIL_TIME, &body).unwrap() {
diff --git a/crates/benilla-protocol/tests/movement.rs b/crates/benilla-protocol/tests/movement.rs
index ac802da7..2ddfbcda 100644
--- a/crates/benilla-protocol/tests/movement.rs
+++ b/crates/benilla-protocol/tests/movement.rs
@@ -1,7 +1,5 @@
-//! Player-movement relay + teleport-ack wire tests: the `[packed guid][MovementInfo]` relay shape
-//! that rebroadcasts other players' `MSG_MOVE_*` locomotion (including the jump ballistic tail), and
-//! `MSG_MOVE_TELEPORT_ACK`'s server-form pose. Split out of the former `tests/messages.rs` — see
-//! `tests/common` for the shared fixtures and methodology note.
+//! The movement wire: the `[packed guid][MovementInfo]` relay of other units' moves, teleport
+//! acks, speed changes, knockbacks, compressed batches and the movement-mode opcodes.
 
 mod common;
 
@@ -13,10 +11,8 @@ use common::hx;
 
 #[test]
 fn movement_relay_decodes_to_unit_move() {
-    // A relayed player move: [packed mover guid][MovementInfo]. Packed guid 0xAA = mask 0x01 + byte
-    // 0xAA; the MovementInfo body is the same 28-byte FORWARD info pinned in `client_bodies_golden`
-    // (flags 0x1, time, pos, orientation 1.25, fall_time). The server rebroadcasts with the mover's
-    // opcode — here MSG_MOVE_START_FORWARD — which is how another player's walking reaches us.
+    // Packed guid 0xAA, then the 28-byte FORWARD MovementInfo of `client_bodies_golden`; the
+    // server relays another player's move under the mover's own opcode.
     let body = hx("01aa0100000004030201cdd70bc6357e04c3f90fa7420000a03f00000000");
     match messages::parse_server(messages::opcode::MSG_MOVE_START_FORWARD, &body).unwrap() {
         ServerPacket::PlayerMove {
@@ -40,8 +36,7 @@ fn movement_relay_decodes_to_unit_move() {
         }
         p => panic!("expected PlayerMove, got {}", p.name()),
     }
-    // The whole relay family routes through the same body shape — spot-check a couple more opcodes and
-    // the fan-out into a SessionEvent the ECS consumes.
+    // Every relay opcode shares the body shape.
     for op in [
         messages::opcode::MSG_MOVE_HEARTBEAT,
         messages::opcode::MSG_MOVE_SET_FACING,
@@ -65,9 +60,8 @@ fn movement_relay_decodes_to_unit_move() {
 
 #[test]
 fn jump_relay_round_trips_the_ballistic_tail() {
-    // A jumping MovementInfo (JUMPING 0x2000 | FORWARD) carries the ballistic launch tail. Round-trip it
-    // through write → parse to pin the wire layout: `fall_time` is a u32 (ms), and the jump tail order is
-    // `zspeed, cosAngle, sinAngle, xyspeed` — cos *before* sin (VERIFIED vmangos `MovementInfo::Read`).
+    // JUMPING (0x2000) adds the launch tail after the `u32` fall_time (ms): zspeed, cosAngle,
+    // sinAngle, xyspeed, cos before sin (vmangos `MovementInfo::Read`).
     let mi = MovementInfo {
         flags: 0x2000 | 0x1,
         timestamp: 0x0102_0304,
@@ -77,8 +71,8 @@ fn jump_relay_round_trips_the_ballistic_tail() {
             z: 3.0,
         },
         orientation: 0.5,
-        transport: None, // not on a transport — no transport tail is written
-        pitch: 0.0,      // not swimming — no pitch tail is written
+        transport: None, // not on a transport: no transport tail
+        pitch: 0.0,      // not swimming: no pitch tail
         fall_time: 250,
         jump: Some(messages::JumpInfo {
             zspeed: 7.955_547,
@@ -87,7 +81,7 @@ fn jump_relay_round_trips_the_ballistic_tail() {
             xy_speed: 7.0,
         }),
     };
-    let mut body = hx("01aa"); // [packed guid 0xAA][MovementInfo] — the relay shape.
+    let mut body = hx("01aa"); // [packed guid 0xAA][MovementInfo], the relay shape.
     body.extend_from_slice(&messages::movement(&mi));
     match messages::parse_server(messages::opcode::MSG_MOVE_JUMP, &body).unwrap() {
         ServerPacket::PlayerMove {
@@ -111,35 +105,29 @@ fn jump_relay_round_trips_the_ballistic_tail() {
     }
 }
 
-/// A relayed rider on a transport: `MOVEFLAG_ON_TRANSPORT | MOVEFLAG_SWIMMING | MOVEFLAG_JUMPING` all
-/// set, so the transport pose, swim pitch, `fall_time`, and jump tail all ride the same packet — the
-/// exact regression the old discard comment warned about (`messages/movement.rs`'s prior "the
-/// transport ... tail is parsed to stay aligned but discarded"): a wrong transport-tail length would
-/// misalign every tail after it. `write()` never serializes a transport tail (benilla doesn't set the
-/// flag outbound — riding is decision 0438 phase 2), so this fixture is hand-built to the exact byte
-/// order `read_movement_info` implements.
+/// A rider with ON_TRANSPORT, SWIMMING and JUMPING set: the transport pose, pitch, fall_time and
+/// jump tail share one packet, so a wrong transport-tail length misaligns everything after it.
 #[test]
 fn movement_relay_surfaces_transport_pose_and_keeps_the_rest_aligned() {
-    // An elevator (HIGH_TRANSPORT, 0xF120): template entry 900, DB spawn low guid 4242 — the standard
-    // entry layout (guid.rs `entry()`).
+    // An elevator guid (HIGH_TRANSPORT 0xF120): entry 900, low guid 4242.
     let transport_guid: u64 = 4242 | (900u64 << 24) | (0xF120u64 << 48);
 
     let mut body = Vec::new();
     write_packed_guid(0xAA, &mut body).unwrap(); // mover guid
-    let flags: u32 = 0x0200_0000 | 0x20_0000 | 0x2000 | 0x1; // ON_TRANSPORT | SWIMMING | JUMPING | FORWARD
+    let flags: u32 = 0x0200_0000 | 0x20_0000 | 0x2000 | 0x1; // transport, swim, jump, forward
     body.extend_from_slice(&flags.to_le_bytes());
     body.extend_from_slice(&0x1122_3344u32.to_le_bytes()); // timestamp
     body.extend_from_slice(&10.0f32.to_le_bytes()); // position.x
     body.extend_from_slice(&20.0f32.to_le_bytes()); // position.y
     body.extend_from_slice(&30.0f32.to_le_bytes()); // position.z
     body.extend_from_slice(&0.75f32.to_le_bytes()); // orientation
-    body.extend_from_slice(&transport_guid.to_le_bytes()); // ON_TRANSPORT tail: FULL u64 guid
+    body.extend_from_slice(&transport_guid.to_le_bytes()); // ON_TRANSPORT tail: full u64 guid
     body.extend_from_slice(&1.0f32.to_le_bytes()); // local x
     body.extend_from_slice(&2.0f32.to_le_bytes()); // local y
     body.extend_from_slice(&3.0f32.to_le_bytes()); // local z
     body.extend_from_slice(&0.5f32.to_le_bytes()); // local o
     body.extend_from_slice(&(-0.3f32).to_le_bytes()); // SWIMMING tail: pitch
-    body.extend_from_slice(&999u32.to_le_bytes()); // fall_time (u32 — must land right after pitch)
+    body.extend_from_slice(&999u32.to_le_bytes()); // fall_time (u32, right after pitch)
     body.extend_from_slice(&7.9f32.to_le_bytes()); // JUMPING tail: zspeed
     body.extend_from_slice(&0.6f32.to_le_bytes()); // cos_angle
     body.extend_from_slice(&0.8f32.to_le_bytes()); // sin_angle
@@ -186,8 +174,6 @@ fn movement_relay_surfaces_transport_pose_and_keeps_the_rest_aligned() {
         p => panic!("expected PlayerMove, got {}", p.name()),
     }
 
-    // The same fixture through the SessionEvent fan-out: UnitMove carries the same transport pose and
-    // the same post-tail fields.
     let events =
         decode(messages::parse_server(messages::opcode::MSG_MOVE_HEARTBEAT, &body).unwrap());
     match events.as_slice() {
@@ -207,8 +193,7 @@ fn movement_relay_surfaces_transport_pose_and_keeps_the_rest_aligned() {
 
 #[test]
 fn teleport_ack_parses_pose() {
-    // MSG_MOVE_TELEPORT_ACK (server→client form): [packed guid][counter u32][MovementInfo]. Exercises
-    // the refactored read_movement_info (non-transport path) end to end.
+    // MSG_MOVE_TELEPORT_ACK from the server: [packed guid][u32 counter][MovementInfo].
     let body = hx("01aa070000000100000004030201cdd70bc6357e04c3f90fa7420000a03f00000000");
     match messages::parse_server(messages::opcode::MSG_MOVE_TELEPORT_ACK, &body).unwrap() {
         ServerPacket::Teleport {
@@ -229,11 +214,9 @@ fn teleport_ack_parses_pose() {
     }
 }
 
-/// The force-speed-change family, byte-exact both directions (a new wire body never lands without
-/// a golden — method): the SMSG body is `[packed guid][u32 counter][f32 speed]` (vmangos
-/// `SendSpeedChangeToController`, 5875 branch), and the ACK body is `[u64 FULL guid][u32 counter]
-/// [MovementInfo][f32 speed]` (`MoveSpeedAck::ReadFromWorldPacket` — a plain `ObjectGuid`
-/// extraction is a raw u64, `ObjectGuid.cpp:180`, NOT packed like the SMSG's).
+/// `SMSG_FORCE_*_SPEED_CHANGE` is `[packed guid][u32 counter][f32 speed]` (vmangos
+/// `SendSpeedChangeToController`); the ack is `[u64 guid][u32 counter][MovementInfo][f32 speed]`
+/// with the guid unpacked (`MoveSpeedAck::ReadFromWorldPacket`).
 #[test]
 fn force_speed_change_parses_and_ack_body_golden() {
     use benilla_protocol::messages::SpeedKind;
@@ -260,8 +243,7 @@ fn force_speed_change_parses_and_ack_body_golden() {
         }] => assert_eq!(*speed, 14.0),
         other => panic!("expected one ForceSpeedChange event, got {other:?}"),
     }
-    // Every kind maps to its own SMSG opcode (the walk/swim-back/turn-rate trio lives in the
-    // 730-735 block, not the 226-231 run).
+    // Each kind has its own opcode; walk, swim-back and turn rate sit at 730-735, not 226-231.
     for (op, kind) in [
         (
             messages::opcode::SMSG_FORCE_WALK_SPEED_CHANGE,
@@ -282,8 +264,6 @@ fn force_speed_change_parses_and_ack_body_golden() {
         }
     }
 
-    // The ACK body golden: full 8-byte guid, counter, a stationary MovementInfo (flags 0 => no
-    // conditional tails), then the echoed speed.
     let info = MovementInfo {
         flags: 0,
         timestamp: 12345,
@@ -303,28 +283,18 @@ fn force_speed_change_parses_and_ack_body_golden() {
         hx("08000000000000000700000000000000393000000000803f00000040000040400000003f2a00000000006041"),
         "CMSG_FORCE_*_SPEED_CHANGE_ACK body"
     );
-    // The ack opcode per kind — the run ack is 227, the walk ack lives in the high block (731).
     assert_eq!(SpeedKind::Run.ack_opcode(), 0x00E3);
     assert_eq!(SpeedKind::Walk.ack_opcode(), 0x02DB);
     assert_eq!(SpeedKind::TurnRate.ack_opcode(), 0x02DF);
 }
 
-/// **The knockback handshake, byte-exact both ways** (decision 1702).
-///
-/// The two halves are one test because the second is only correct *relative to* the first: the ack's
-/// jump tail has to be the arriving quad, and the two packets order those same four floats
-/// differently. `SMSG_MOVE_KNOCK_BACK` is direction-first (`vcos, vsin, speedXY, speedZ`); the
-/// `MovementInfo` jump tail is `zspeed, cos, sin, xyspeed`. Read one in the other's order and every
-/// field is still a plausible float, the arc flies off at a wrong angle, and
-/// `FindPendingMovementKnockbackChange` rejects the ack — so this is exactly the transposition a
-/// type alone cannot catch.
-///
-/// `speedZ` is negative here because it is **down-positive**: this is a knockback that throws the
-/// body *upward* at 12 yd/s (wow-re: `0x7c61f0` stores the wire value verbatim into the same
-/// `CMovement+0xa0` a land jump seeds with `0xc0fe93d8` = −7.955547).
+/// The knockback and its ack: `SMSG_MOVE_KNOCK_BACK` orders the launch vcos, vsin, speedXY,
+/// speedZ; the ack's jump tail orders it zspeed, cos, sin, xyspeed, and vmangos rejects a
+/// mismatched ack. speedZ is down-positive: the reference stores it as-is (`0x7c61f0`) where a
+/// jump stores -7.955547, so -12 throws the body up.
 #[test]
 fn knock_back_parses_and_ack_body_golden() {
-    // packed guid 8 (mask 0x01, one byte), counter 7, then vcos 0.6, vsin 0.8, speedXY 25, speedZ −12.
+    // Packed guid 8, counter 7, then vcos 0.6, vsin 0.8, speedXY 25, speedZ -12.
     let body = hx("0108070000009a99193fcdcc4c3f0000c841000040c1");
     let packet = messages::parse_server(messages::opcode::SMSG_MOVE_KNOCK_BACK, &body).unwrap();
     let launch = match &packet {
@@ -354,9 +324,8 @@ fn knock_back_parses_and_ack_body_golden() {
         other => panic!("expected one KnockBack event, got {other:?}"),
     }
 
-    // The ACK body golden: a **full** 8-byte guid (packed on the way in, never on the way out), the
-    // echoed counter, and a `MovementInfo` carrying `MOVEFLAG_JUMPING` (0x2000) — without which the
-    // jump tail is not serialized at all and the server has nothing to match against.
+    // The ack: the full guid (packed only inbound), the counter, and a MovementInfo with
+    // MOVEFLAG_JUMPING (0x2000), without which no jump tail is written for the server to match.
     let info = MovementInfo {
         flags: 0x2000,
         timestamp: 12345,
@@ -380,17 +349,12 @@ fn knock_back_parses_and_ack_body_golden() {
     assert_eq!(messages::opcode::CMSG_MOVE_KNOCK_BACK_ACK, 0x00F0);
 }
 
-/// **Somebody else's knockback reaches us, and replays as an arc** (decision 1702, correcting
-/// decision 0277's "no observer-side knockback signal exists in 1.12 at all").
-///
-/// `MSG_MOVE_KNOCK_BACK` is an ordinary `[packed guid][MovementInfo]` relay with the launch quad
-/// appended — and the appendix is redundant by construction, because the server builds that
-/// `MovementInfo` from the victim's own ack, whose jump tail already carries the quad. So the
-/// trailing four floats go unread and the arc still replays: this test's assertion is that the tail
-/// the reader *does* reach is the launch, not that the packet was consumed to the last byte.
+/// `MSG_MOVE_KNOCK_BACK` relays another unit's knockback: `[packed guid][MovementInfo]` and the
+/// launch again. The MovementInfo is built from the victim's ack, whose jump tail already holds
+/// the launch, so the appended quad goes unread.
 #[test]
 fn an_observed_knockback_relays_the_arc() {
-    // packed guid 0xAA, a JUMPING MovementInfo whose tail is (zspeed −12, cos 0.6, sin 0.8, xy 25),
+    // packed guid 0xAA, a JUMPING MovementInfo whose tail is (zspeed -12, cos 0.6, sin 0.8, xy 25),
     // then the same quad again in the SMSG's own direction-first order.
     let body = hx("01aa00200000393000000000803f00000040000040400000003f00000000000040c19a99193fcdcc4c3f0000c8419a99193fcdcc4c3f0000c841000040c1");
     let packet = messages::parse_server(messages::opcode::MSG_MOVE_KNOCK_BACK, &body).unwrap();
@@ -413,12 +377,9 @@ fn an_observed_knockback_relays_the_arc() {
     assert_eq!(messages::opcode::MSG_MOVE_KNOCK_BACK, 0x00F1);
 }
 
-/// The OBSERVER speed legs, byte-exact (decision 0441 — how an observed unit's mounted speed
-/// reaches us; no counter, no ack on either): `SMSG_SPLINE_SET_*_SPEED` is `[packed guid]
-/// [f32 speed]` (vmangos `SendSpeedChangeToAll` + the mid-spline observer branch), and
-/// `MSG_MOVE_SET_*_SPEED` is `[packed guid][MovementInfo][f32 speed]`
-/// (`SendSpeedChangeToObservers`, finalized branch) — a speed change AND a fresh pose, decoding
-/// to a `UnitMove` + `SpeedChanged` pair.
+/// An observed unit's speed changes, with no counter or ack: `SMSG_SPLINE_SET_*_SPEED` is
+/// `[packed guid][f32 speed]` (vmangos `SendSpeedChangeToAll`), `MSG_MOVE_SET_*_SPEED` is
+/// `[packed guid][MovementInfo][f32 speed]` (`SendSpeedChangeToObservers`), a pose and a speed.
 #[test]
 fn observer_speed_legs_parse_golden() {
     use benilla_protocol::messages::SpeedKind;
@@ -446,8 +407,7 @@ fn observer_speed_legs_parse_golden() {
         }] => assert_eq!(*speed, 14.0),
         other => panic!("expected one SpeedChanged event, got {other:?}"),
     }
-    // Each kind maps to its own opcode — spot-check the walk (769) and swim-back (770) slots,
-    // whose order differs from the FORCE family's.
+    // Walk (769) and swim-back (770) sit in a different order from the FORCE family's.
     for (op, kind) in [
         (
             messages::opcode::SMSG_SPLINE_SET_WALK_SPEED,
@@ -464,8 +424,7 @@ fn observer_speed_legs_parse_golden() {
         }
     }
 
-    // MSG_MOVE_SET_RUN_SPEED: [packed guid 0xAA][the shared 28-byte FORWARD MovementInfo golden]
-    // [speed 14.0] — decodes to the pose + the speed, in one drain.
+    // MSG_MOVE_SET_RUN_SPEED: packed guid 0xAA, the shared FORWARD MovementInfo, speed 14.0.
     let body = hx("01aa0100000004030201cdd70bc6357e04c3f90fa7420000a03f0000000000006041");
     let packet = messages::parse_server(messages::opcode::MSG_MOVE_SET_RUN_SPEED, &body).unwrap();
     match &packet {
@@ -523,8 +482,7 @@ fn observer_speed_legs_parse_golden() {
         other => panic!("expected MountResult(dismount, 3), got {other:?}"),
     }
 
-    // SMSG_MOUNTSPECIAL_ANIM: one raw u64 guid, NOT packed (vmangos
-    // `HandleMountSpecialAnimOpcode` writes `data << GetObjectGuid()` — full 8 bytes).
+    // SMSG_MOUNTSPECIAL_ANIM: one unpacked `u64` guid (vmangos `HandleMountSpecialAnimOpcode`).
     match decode(
         messages::parse_server(
             messages::opcode::SMSG_MOUNTSPECIAL_ANIM,
@@ -541,20 +499,16 @@ fn observer_speed_legs_parse_golden() {
     }
 }
 
-/// `SMSG_COMPRESSED_MOVES` — the batch carrier vmangos switches a session onto once it has been
-/// sent 300 movement packets in ten seconds (decision 0624). The fixture is built exactly as
-/// `MovementData::AddPacket` + `BuildPacket` do: `[u32 uncompressed size][zlib(records)]`, each
-/// record `[u8 size][u16 opcode][body]` with `size` counting the opcode's two bytes. The two
-/// records carry the same relay bodies pinned by `movement_relay_decodes_to_unit_move` above, so
-/// what this adds is the *framing* — that a batched move decodes identically to a loose one.
+/// `SMSG_COMPRESSED_MOVES`, which vmangos switches a session to after 300 movement packets in ten
+/// seconds: `[u32 size][zlib(records)]`, each record `[u8 size][u16 opcode][body]` with the size
+/// counting the opcode (vmangos `MovementData::BuildPacket`).
 #[test]
 fn compressed_moves_unwraps_to_the_same_events_as_loose_relays() {
     let body = hx("42000000780153d8cac0b88a91818181859989f1ec75ee63a6752c877ff22f77626058600f146650b805540062602a38005600002f2610d9");
     let events =
         decode(messages::parse_server(messages::opcode::SMSG_COMPRESSED_MOVES, &body).unwrap());
 
-    // Both records, in wire order, as ordinary moves — order is load-bearing: the remote-replay
-    // queue reconstructs a mover's arc from it (decision 0618).
+    // Both records, in wire order: the remote-replay queue rebuilds a mover's arc from that order.
     match events.as_slice() {
         [SessionEvent::UnitMove {
             guid: 0xAA,
@@ -570,50 +524,42 @@ fn compressed_moves_unwraps_to_the_same_events_as_loose_relays() {
         ),
     }
 
-    // A batched move must be byte-identical to the same move arriving loose.
-    let loose = decode(
-        messages::parse_server(
+    // The batch's two records, relayed loose under their own opcodes.
+    let loose: Vec<SessionEvent> = [
+        (
             messages::opcode::MSG_MOVE_START_FORWARD,
-            &hx("01aa0100000004030201cdd70bc6357e04c3f90fa7420000a03f00000000"),
-        )
-        .unwrap(),
-    );
-    assert_eq!(format!("{:?}", events[0]), format!("{:?}", loose[0]));
+            "01aa0100000004030201cdd70bc6357e04c3f90fa7420000a03f00000000",
+        ),
+        (
+            messages::opcode::MSG_MOVE_SET_FACING,
+            "01aa0000000004030201cdd70bc6357e04c3f90fa7420000c03f00000000",
+        ),
+    ]
+    .into_iter()
+    .flat_map(|(opcode, body)| decode(messages::parse_server(opcode, &hx(body)).unwrap()))
+    .collect();
+    assert_eq!(format!("{events:?}"), format!("{loose:?}"));
 }
 
-/// A misframed batch must fail **loudly** (one `Poll::Skipped` naming the inner opcode), never
-/// silently drop the moves it carries — the exact silence that made the runaway unattributable for
-/// three rounds of fixes (decision 0624).
+/// A misframed batch is a parse error, never a silent drop of the moves it carries.
 #[test]
 fn a_misframed_batch_errors_rather_than_dropping_moves() {
     // A HEARTBEAT record claiming a 40-byte body with only 4 bytes left in the stream.
     let truncated = hx("070000007801d37ac700020006c10119");
     assert!(messages::parse_server(messages::opcode::SMSG_COMPRESSED_MOVES, &truncated).is_err());
 
-    // A record whose size (1) cannot even hold the opcode that follows it — misframing, not an
-    // empty-body packet, and it must not underflow into a huge body length.
+    // A record whose size (1) cannot hold its opcode: misframed, and it must not underflow.
     let undersized = hx("030000007801637cc7000001e200f0");
     assert!(messages::parse_server(messages::opcode::SMSG_COMPRESSED_MOVES, &undersized).is_err());
 }
 
-/// **The observer movement-mode family, byte-exact** (decision 1780) — the `SMSG_SPLINE_MOVE_*`
-/// twelve. Three things are asserted because all three are how this family differs from the ack'd
-/// `SMSG_FORCE_*` one it is otherwise a twin of:
-///
-/// 1. **The body is a bare packed guid** — parsing a *four-byte-shorter* body than the FORCE family's
-///    must succeed, so a trailing counter is not being read. Reading one would desync every
-///    subsequent packet in the same TCP read.
-/// 2. **All twelve opcodes are handled**, including `SMSG_SPLINE_MOVE_ROOT`'s out-of-band `0x31A`
-///    (the reference's dispatcher range is `0x304..=0x31A`, root deliberately at the top).
-/// 3. **The run/walk pair is inverted** — `SET_RUN_MODE` *clears* `MOVEFLAG_WALK_MODE`, because the
-///    reference's `0x617e80` hands the opcode's bool to `SetRunMode 0x7c71c0`, whose argument is
-///    *run*. Getting this backwards would walk every running creature in view.
+/// The twelve `SMSG_SPLINE_MOVE_*` opcodes (reference dispatch `0x304..=0x31A`, root at `0x31A`):
+/// the body is a bare packed guid with no counter, and `SET_RUN_MODE` clears
+/// `MOVEFLAG_WALK_MODE`, because the reference (`0x617e80`) passes its bool to `SetRunMode`.
 #[test]
 fn spline_move_mode_family_parses_golden() {
     use benilla_protocol::messages::SplineMode;
 
-    // Packed guid 0xAA (mask 0x01, one byte) and NOTHING else — four bytes shorter than the
-    // FORCE family's `[packed guid][u32 counter]`.
     let body = hx("01aa");
     assert_eq!(body.len(), 2, "the whole body is one packed guid");
 
@@ -707,7 +653,6 @@ fn spline_move_mode_family_parses_golden() {
         }
     }
 
-    // The flag bits are the same word the ack'd family writes — the two families are one state.
     assert_eq!(SplineMode::Root.flag(), messages::MoveMode::Root.flag());
     assert_eq!(
         SplineMode::WaterWalk.flag(),
@@ -720,32 +665,14 @@ fn spline_move_mode_family_parses_golden() {
     assert_eq!(SplineMode::Hover.flag(), messages::MoveMode::Hover.flag());
 }
 
-/// **The observer leg of the movement-mode family, byte-exact** (decision 2061) — the six opcodes
-/// that tell everyone *else* a player was rooted, levitated or blinked. Until this landed they hit
-/// [`ServerPacket::Other`] and were dropped, so a watched player kept sliding through a root and
-/// stood in the wrong place after a Blink until their next ordinary pose packet.
-///
-/// Four things are asserted, because each is how this leg differs from a sibling it is otherwise a
-/// twin of:
-///
-/// 1. **The body is the ordinary relay shape** — `[packed guid][MovementInfo]`, no counter. That is
-///    the whole difference from the ack'd `SMSG_FORCE_MOVE_ROOT` leg (`[packed guid][u32 counter]`)
-///    and from `MSG_MOVE_TELEPORT_ACK` (`[packed guid][u32 counter][MovementInfo]`); reading a
-///    counter that isn't there would shift the pose by four bytes and desync the rest of the read.
-/// 2. **Apply/unapply rides the flags word, not the opcode.** Only root splits in two; hover,
-///    feather-fall and water-walk use ONE opcode for both directions, because vmangos runs
-///    `SetHoverReal` &co. *before* the broadcast (`MovementHandler.cpp:626-638`, `:743-744`) so the
-///    `m_movementInfo` it sends already carries the bit's new state.
-/// 3. **The whole word reaches the app**, which is what makes (2) work: `UnitMove.flags` is the
-///    wire word verbatim, and Levitate — feather fall + hover + water walk at once (decision 1706)
-///    — arrives as three packets whose flags words accumulate server-side.
-/// 4. **`MSG_MOVE_TELEPORT` is tagged as a teleport and nothing else is.** The pose is a
-///    discontinuity; the app's pre-fire reconcile has to know not to glide the mover into it.
+/// The movement-mode opcodes relayed to observers (root, hover, feather fall, water walk,
+/// teleport) use the plain relay shape, no counter. Only root has a separate off opcode: vmangos
+/// updates the others' flag before broadcasting (`MovementHandler.cpp:626-638`, `:743-744`), so
+/// the flags word carries the state. Only `MSG_MOVE_TELEPORT` is tagged as a teleport.
 #[test]
 fn observer_move_mode_family_parses_golden() {
-    // Packed guid 0xAA (mask 0x01, one byte) + a 28-byte MovementInfo with no conditional tails:
-    // flags, time 12345, pos (1, 2, 3), orientation 0.5, fall_time 0. 30 bytes total — FOUR SHORT
-    // of `MSG_MOVE_TELEPORT_ACK`'s same-content body, which is the point of the length assertion.
+    // Packed guid 0xAA and a 28-byte MovementInfo with no tails: time 12345, pos (1, 2, 3),
+    // orientation 0.5, fall_time 0; 30 bytes, four fewer than `MSG_MOVE_TELEPORT_ACK`'s.
     let info = |flags: u32| {
         let mut b = hx("01aa");
         b.extend_from_slice(&flags.to_le_bytes());
@@ -758,7 +685,7 @@ fn observer_move_mode_family_parses_golden() {
     const FEATHER_FALL: u32 = 0x2000_0000;
     const HOVER: u32 = 0x4000_0000;
 
-    // (opcode, the flags word the server would have written into it, the opcode's own verb)
+    // (opcode, the flags word the server writes into it, the opcode's verb)
     let expected = [
         (messages::opcode::MSG_MOVE_ROOT, ROOT, RelayVerb::Root(true)),
         (messages::opcode::MSG_MOVE_UNROOT, 0, RelayVerb::Root(false)),
@@ -767,8 +694,7 @@ fn observer_move_mode_family_parses_golden() {
             WATER_WALK,
             RelayVerb::Pose,
         ),
-        // The same opcode, the other direction — the bit is simply absent, and the verb is still
-        // `Pose`: for these three the word is the whole message.
+        // The same opcode, the other direction: the bit is absent and the verb is still `Pose`.
         (messages::opcode::MSG_MOVE_WATER_WALK, 0, RelayVerb::Pose),
         (
             messages::opcode::MSG_MOVE_FEATHER_FALL,
@@ -776,7 +702,7 @@ fn observer_move_mode_family_parses_golden() {
             RelayVerb::Pose,
         ),
         (messages::opcode::MSG_MOVE_HOVER, HOVER, RelayVerb::Pose),
-        // Levitate grants all three at once (decision 1706) — one word, three bits.
+        // Levitate grants all three at once: one word, three bits.
         (
             messages::opcode::MSG_MOVE_HOVER,
             HOVER | FEATHER_FALL | WATER_WALK,
@@ -800,7 +726,6 @@ fn observer_move_mode_family_parses_golden() {
             } => {
                 assert_eq!(*opcode, op);
                 assert_eq!(*f, flags, "the whole flags word survives for {op:#06x}");
-                // Four bytes off and this would read (2.0, 3.0, 0.5) — the counter-eating bug.
                 assert_eq!(
                     (position.x, position.y, position.z),
                     (1.0, 2.0, 3.0),
@@ -829,9 +754,7 @@ fn observer_move_mode_family_parses_golden() {
         }
     }
 
-    // The numbers themselves (vmangos `Opcodes_1_12_1.h`; cross-checked against the client's own
-    // name table). `MSG_MOVE_TELEPORT` (197) is NOT `MSG_MOVE_TELEPORT_ACK` (199) — the pair this
-    // family is easiest to get wrong on, and the reason (1)'s length assertion exists.
+    // Opcode numbers (vmangos `Opcodes_1_12_1.h`).
     assert_eq!(messages::opcode::MSG_MOVE_TELEPORT, 197);
     assert_eq!(messages::opcode::MSG_MOVE_TELEPORT_ACK, 199);
     assert_eq!(messages::opcode::MSG_MOVE_ROOT, 236);
diff --git a/crates/benilla-protocol/tests/petition.rs b/crates/benilla-protocol/tests/petition.rs
index ebeed018..eb6c64bc 100644
--- a/crates/benilla-protocol/tests/petition.rs
+++ b/crates/benilla-protocol/tests/petition.rs
@@ -1,22 +1,4 @@
-//! Golden tests for the petition opcode family — the guild-charter flow that founds a guild
-//! (decision 1672). CMSG bodies are asserted byte-exact against the builder output; SMSG bodies are
-//! hand-built per the vmangos layouts (cited inline) and round-tripped through `parse_server` +
-//! `decode`. See `tests/common` for the shared `hx()` helper and methodology note.
-//!
-//! Four of the tests exist for a specific failure mode rather than for coverage, and each was
-//! mutation-checked — the code was broken that exact way and the test observed to fail:
-//!
-//! - `petition_buy_body_is_the_full_seventy_two_byte_frame` — vmangos's reader walks 72 fixed bytes
-//!   field by field and never checks the remainder, so a body one field short leaves it reading
-//!   garbage and the buy is dropped **silently**. There is no error packet for a malformed buy.
-//! - `petition_query_response_gender_is_sixteen_bit` — the one odd width in the family. Read as a
-//!   `u32`, every field after it shifts by two bytes and the choice count becomes a huge number.
-//! - `petition_show_signatures_stride_is_twelve_bytes` — the trailing zero dword per signature is
-//!   easy to omit; a nine-signature charter then reads eight signers and a truncation error, and a
-//!   two-signature fixture would still pass.
-//! - `msg_petition_opcodes_read_a_different_body_than_they_write` — the two `MSG_` opcodes are
-//!   genuinely asymmetric (decline sends an item guid and receives a player guid), which is exactly
-//!   the shape a shared body type would paper over.
+//! The petition wire: the guild-charter flow that founds a guild, laid out per vmangos.
 
 mod common;
 
@@ -27,7 +9,6 @@ use benilla_protocol::messages::{
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// Every CMSG builder in the family, byte-exact.
 #[test]
 fn cmsg_bodies_golden() {
     // CMSG_PETITION_SHOWLIST (vmangos Server/Packets/Petition.cpp:3-6): one u64, the NPC.
@@ -37,7 +18,7 @@ fn cmsg_bodies_golden() {
         "CMSG_PETITION_SHOWLIST body"
     );
 
-    // CMSG_PETITION_SHOW_SIGNATURES (Petition.cpp:8-11): one u64, the charter ITEM.
+    // CMSG_PETITION_SHOW_SIGNATURES (Petition.cpp:8-11): one u64, the charter item.
     assert_eq!(
         messages::petition_show_signatures(0x0000_0000_0001_0203),
         hx("0302010000000000"),
@@ -51,16 +32,15 @@ fn cmsg_bodies_golden() {
         "CMSG_TURN_IN_PETITION body"
     );
 
-    // MSG_PETITION_DECLINE outbound (Petition.cpp:19-22): one u64 — the ITEM, not the player.
+    // MSG_PETITION_DECLINE outbound (Petition.cpp:19-22): one u64, the item, not the player.
     assert_eq!(
         messages::petition_decline(0x0000_0000_0001_0203),
         hx("0302010000000000"),
         "MSG_PETITION_DECLINE body"
     );
 
-    // CMSG_PETITION_SIGN (Petition.cpp:35-39): u64 item, then an i8 the server reads and skips.
-    // The client's own default for that byte is 1, not 0 (`0x4f46d9`) — and because the server
-    // discards it, this golden is the ONLY thing that can tell the two apart.
+    // CMSG_PETITION_SIGN (Petition.cpp:35-39): u64 item, then an i8 the server skips; the
+    // reference defaults it to 1 (`0x4f46d9`).
     assert_eq!(
         messages::petition_sign(0x0000_0000_0001_0203, 1),
         hx("030201000000000001"),
@@ -94,14 +74,9 @@ fn cmsg_bodies_golden() {
     );
 }
 
-/// `CMSG_PETITION_BUY` is 72 fixed bytes plus the name's, laid out exactly as vmangos's reader
-/// walks them (`Server/Packets/Petition.cpp:47-67`): `u64 npc`, `u32 0`, `u64 0`, cstring name,
-/// `10 × u32 0`, `u16 0`, `u8 0`, `u32 index`, `u32 0`.
-///
-/// **Mutation-checked.** Dropping any one of the skipped fields still compiles, still sends, and is
-/// answered by nothing at all — the server reads past the end, `IsValidCharterName` sees garbage or
-/// the handler returns, and no error packet exists for a malformed buy. This test is the only thing
-/// between that and a "the Purchase button does nothing" report.
+/// `CMSG_PETITION_BUY` is 72 fixed bytes plus the name, in vmangos's read order
+/// (`Server/Packets/Petition.cpp:47-67`); a short body gets no reply at all, since the server has
+/// no error packet for a malformed buy.
 #[test]
 fn petition_buy_body_is_the_full_seventy_two_byte_frame() {
     let body = messages::petition_buy(0x0000_0000_0000_2a1f, "Legacy");
@@ -116,15 +91,14 @@ fn petition_buy_body_is_the_full_seventy_two_byte_frame() {
             "00000000000000000000000000000000000000000000000000000000000000000000000000000000",
             "0000",     // u16 skipped
             "00",       // u8 skipped
-            "00000000", // u32 index — the server's own "unused"
+            "00000000", // u32 index, unused by the server
             "00000000", // u32 skipped
         )),
         "CMSG_PETITION_BUY body"
     );
     assert_eq!(body.len(), 72 + "Legacy".len(), "72 fixed bytes + the name");
 
-    // The name is the only variable-length part, and it sits at offset 20 — where the server's
-    // reader arrives after skipping 8 + 4 + 8 bytes.
+    // The name, the only variable part, starts at offset 20 (8 + 4 + 8).
     assert_eq!(
         &body[20..27],
         b"Legacy\0",
@@ -132,17 +106,13 @@ fn petition_buy_body_is_the_full_seventy_two_byte_frame() {
     );
 }
 
-/// `SMSG_PETITION_SHOWLIST` — the packet that opens the guild registrar. Layout from
-/// `Server/Packets/Petition.cpp:115-127`, values from `Handlers/PetitionsHandler.cpp:482-507`.
-///
-/// The list is **counted**, and parsed as one even though vmangos's own header says the reference
-/// client supports only one row: a reader that assumed one would desynchronise rather than degrade
-/// if a server ever sent two. The fixture sends two for exactly that reason.
+/// `SMSG_PETITION_SHOWLIST` opens the guild registrar (`Server/Packets/Petition.cpp:115-127`).
+/// The list is counted: vmangos sends one row, the fixture two, so a one-row reader fails.
 #[test]
 fn petition_show_list_parses_a_counted_list() {
     let body = hx(concat!(
         "1f2a000000000000", // u64 npcGuid
-        "02",               // u8 count — deliberately not vmangos's 1
+        "02",               // u8 count, not vmangos's 1
         // row 1: index 1, entry 5863, display 16161, cost 1000, flags 1
         "01000000",
         "e7160000",
@@ -184,13 +154,9 @@ fn petition_show_list_parses_a_counted_list() {
     );
 }
 
-/// `SMSG_PETITION_SHOW_SIGNATURES` — `u64 item`, `u64 owner`, `u32 petitionId`, `u8 count`, then
-/// **12 bytes per signature**: the signer's guid and a dword vmangos writes as a literal zero
-/// (`Handlers/PetitionsHandler.cpp:160-168`, `Guild/GuildMgr.cpp:358-366`).
-///
-/// **Mutation-checked** against omitting that dword. The fixture carries a full nine signatures
-/// because that is the only size at which the drift is unmistakable — with two, an 8-byte stride
-/// reads one signer and then a truncation error, which is easy to misread as a short packet.
+/// `SMSG_PETITION_SHOW_SIGNATURES`: `u64` item, `u64` owner, `u32` petitionId, `u8` count, then
+/// 12 bytes per signature, the signer's guid and a zero dword (vmangos
+/// `Handlers/PetitionsHandler.cpp:160-168`); nine signatures make a wrong stride fail plainly.
 #[test]
 fn petition_show_signatures_stride_is_twelve_bytes() {
     let mut body = hx(concat!(
@@ -212,8 +178,6 @@ fn petition_show_signatures_stride_is_twelve_bytes() {
     assert_eq!(sigs.owner, 0xaa);
     assert_eq!(sigs.petition_id, 7);
     assert_eq!(sigs.signatures.len(), MAX_PETITION_SIGNATURES);
-    // The LAST signer is the one that proves the stride: an 8-byte stride would have walked into
-    // the padding long before here.
     assert_eq!(
         sigs.signatures[MAX_PETITION_SIGNATURES - 1].signer,
         MAX_PETITION_SIGNATURES as u64,
@@ -228,12 +192,8 @@ fn petition_show_signatures_stride_is_twelve_bytes() {
     );
 }
 
-/// `SMSG_PETITION_QUERY_RESPONSE` — sixteen fields, one of which is sixteen bits.
-///
-/// **Mutation-checked** against reading `allowedGender` as a `u32`. That shifts everything after it
-/// by two bytes: `allowedMinLevel` picks up half of `allowedMaxLevel`, and the choice count reads a
-/// large number, so the parse fails on a truncated cstring — far from the cause. The fixture gives
-/// every trailing field a distinct value so the shift cannot land on a lucky zero.
+/// `SMSG_PETITION_QUERY_RESPONSE`: sixteen fields, of which `allowedGender` alone is a `u16`; the
+/// fields after it get distinct values so a 32-bit read cannot land on a lucky zero.
 #[test]
 fn petition_query_response_gender_is_sixteen_bit() {
     let body = hx(concat!(
@@ -267,7 +227,6 @@ fn petition_query_response_gender_is_sixteen_bit() {
     assert_eq!(r.min_signatures, 9);
     assert_eq!(r.max_signatures, 9);
     assert_eq!(r.allowed_gender, 0x6666, "sixteen bits, not thirty-two");
-    // These two are what a 32-bit gender read would corrupt first.
     assert_eq!(r.allowed_min_level, 0x7777_7777);
     assert_eq!(r.allowed_max_level, 0x8888_8888);
     assert_eq!(r.choices, vec!["Yes".to_string()], "the counted tail");
@@ -280,14 +239,13 @@ fn petition_query_response_gender_is_sixteen_bit() {
     );
 }
 
-/// `SMSG_PETITION_SIGN_RESULTS` (`Petition.cpp:69-74`) and `SMSG_TURN_IN_PETITION_RESULTS`
-/// (`:76-79`) share the `PetitionSigns` enum but not a layout: the first carries two guids and a
-/// code, the second carries **only** the code.
+/// `SMSG_PETITION_SIGN_RESULTS` (`Petition.cpp:69-74`) carries two guids and a code,
+/// `SMSG_TURN_IN_PETITION_RESULTS` (`:76-79`) only the code, from the same `PetitionSigns` enum.
 #[test]
 fn the_two_results_packets_share_an_enum_but_not_a_layout() {
     let body = hx(concat!(
         "0302010000000000", // u64 itemGuid
-        "bb00000000000000", // u64 playerGuid — the SIGNER, in both copies of this packet
+        "bb00000000000000", // u64 playerGuid: the signer, in both copies of this packet
         "03000000",         // u32 result = CANT_SIGN_OWN
     ));
     let packet = messages::parse_server(opcode::SMSG_PETITION_SIGN_RESULTS, &body).unwrap();
@@ -298,7 +256,6 @@ fn the_two_results_packets_share_an_enum_but_not_a_layout() {
     assert_eq!(r.player, 0xbb);
     assert_eq!(r.result, petition_result::CANT_SIGN_OWN);
 
-    // The turn-in answer is a bare u32 with no charter named at all.
     let packet = messages::parse_server(
         opcode::SMSG_TURN_IN_PETITION_RESULTS,
         &hx("04000000"), // NEED_MORE
@@ -322,16 +279,10 @@ fn the_two_results_packets_share_an_enum_but_not_a_layout() {
     );
 }
 
-/// The two `MSG_` opcodes are genuinely bidirectional, and **decline reads a different body than it
-/// writes**: we send the charter's item guid, the owner receives the declining player's guid. Both
-/// are eight bytes, so nothing but this test distinguishes a correct implementation from one that
-/// reuses a single body type and is wrong half the time.
-///
-/// Rename, by contrast, is symmetric — the same `u64 item` + cstring both ways — which is why the
-/// two are asserted together: the family is not uniformly one or the other.
+/// `MSG_PETITION_DECLINE` sends the charter's item guid but receives the decliner's player guid,
+/// both eight bytes; `MSG_PETITION_RENAME` is `u64` item and cstring name both ways.
 #[test]
-fn msg_petition_opcodes_read_a_different_body_than_they_write() {
-    // Decline: outbound is the ITEM, inbound is the PLAYER. Same width, opposite meaning.
+fn msg_petition_decline_differs_by_direction_and_rename_does_not() {
     assert_eq!(
         messages::petition_decline(0x0001_0203),
         hx("0302010000000000"),
@@ -345,7 +296,7 @@ fn msg_petition_opcodes_read_a_different_body_than_they_write() {
         packet.name()
     );
 
-    // Rename: symmetric, and the echo arrives only on success.
+    // The rename echo arrives only on success.
     let body = hx("03020100000000004c656761637900");
     assert_eq!(
         messages::petition_rename(0x0001_0203, "Legacy"),
@@ -366,9 +317,6 @@ fn msg_petition_opcodes_read_a_different_body_than_they_write() {
     );
 }
 
-/// An empty charter — no signatures yet, which is what the owner sees the moment they buy one.
-/// The count byte is zero and the packet simply ends; nothing may read a signature record that is
-/// not there.
 #[test]
 fn a_freshly_bought_charter_has_no_signatures() {
     let body = hx(concat!(
diff --git a/crates/benilla-protocol/tests/pvp.rs b/crates/benilla-protocol/tests/pvp.rs
index 00f69873..9f99c970 100644
--- a/crates/benilla-protocol/tests/pvp.rs
+++ b/crates/benilla-protocol/tests/pvp.rs
@@ -1,9 +1,5 @@
-//! The honor-system wire route end to end (decision 1512), mirroring `src/messages/pvp.rs`: raw
-//! body → [`messages::parse_server`] → `ServerPacket` → [`decode`] → `SessionEvent`. The
-//! byte-exact field goldens live inline in `pvp.rs`; what this file adds is the part those cannot
-//! reach — that the opcode actually dispatches to the right reader, that the packet names itself
-//! correctly in the log, and that the event fan-out carries the payload through unchanged. See
-//! `tests/common` for the shared fixtures and methodology note.
+//! The honor wire end to end: an opcode dispatches to its reader, names itself, and reaches its
+//! event unchanged.
 
 mod common;
 
@@ -12,11 +8,8 @@ use benilla_protocol::messages;
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// The 50-byte `MSG_INSPECT_HONOR_STATS` reply, in `InspectHonorStatsResponse::AppendBodyTo`
-/// order: guid `0x0000000100002AB3`, highestRank 11, sessionKills 17|2<<16, yesterdayHK 41,
-/// unknownOld1 0, lastWeekHK 420, unknownOld2 0, thisWeekHK 123, unknownOld3 0, lifetimeHK 3907,
-/// lifetimeDHK 12, yesterdayHonor 640, lastWeekHonor 8431, thisWeekHonor 1250, lastWeekRank 57,
-/// rankBar 191.
+/// The 50-byte `MSG_INSPECT_HONOR_STATS` reply, in vmangos
+/// `InspectHonorStatsResponse::AppendBodyTo` order.
 fn inspect_honor_body() -> Vec<u8> {
     hx(concat!(
         "b32a000001000000", // u64 playerGuid
@@ -38,9 +31,8 @@ fn inspect_honor_body() -> Vec<u8> {
     ))
 }
 
-/// The reply dispatches off opcode 0x2D6 and reaches the UI as one event with every field intact.
-/// The opcode is an `MSG_` — the same number carries our request — but `parse_server` only ever
-/// sees inbound bodies, so there is nothing to disambiguate here.
+/// `MSG_INSPECT_HONOR_STATS` (0x2D6) also carries our request, a bare guid; `parse_server` only
+/// sees the reply.
 #[test]
 fn inspect_honor_stats_wire() {
     let body = inspect_honor_body();
@@ -79,17 +71,14 @@ fn inspect_honor_stats_wire() {
         other => panic!("one inspect-honor event, got {other:?}"),
     }
 
-    // Our own request on the same opcode is the bare guid — a different shape entirely, which is
-    // exactly why direction and not content has to tell the two apart.
     assert_eq!(
         messages::inspect_honor_stats(0x0000_0001_0000_2AB3),
         hx("b32a000001000000")
     );
 }
 
-/// `SMSG_PVP_CREDIT` dispatches off 0x28C and carries honor / victim / rank through to the event.
-/// The victim rank is the **internal** rank (`SendPVPCredit` sends `GetRank().rank`, floored at 5
-/// for a player victim) — a direct `PVP_RANK_<rank>_<team>` key, not the visual badge number.
+/// `SMSG_PVP_CREDIT` (0x28C): honor, victim guid, and the victim's internal rank (vmangos
+/// `SendPVPCredit`, floored at 5 for a player), a `PVP_RANK_<rank>_<team>` key, not the badge.
 #[test]
 fn pvp_credit_wire() {
     // i32 honor = 143, u64 victimGuid = 0x0000000100002AB3, i32 victimRank = 11.
@@ -119,8 +108,6 @@ fn pvp_credit_wire() {
     assert_eq!(credit.honor, -5);
 }
 
-/// A truncated body must surface as a parse error, not a panic — both opcodes, at the wire edge
-/// rather than only at the reader.
 #[test]
 fn truncated_honor_bodies_error_at_the_dispatch() {
     let full = inspect_honor_body();
diff --git a/crates/benilla-protocol/tests/quest_share.rs b/crates/benilla-protocol/tests/quest_share.rs
index 032904cd..3007384e 100644
--- a/crates/benilla-protocol/tests/quest_share.rs
+++ b/crates/benilla-protocol/tests/quest_share.rs
@@ -1,13 +1,5 @@
-//! Golden tests for the **party quest-share** opcode family (decision 1733) — the quest log's
-//! *Share Quest* push, the escort confirm, and the two-way verdict relay. CMSG bodies are asserted
-//! byte-exact against the builder output; SMSG bodies are hand-built per the vmangos layouts (cited
-//! inline) and round-tripped through `parse_server` + `decode`. See `tests/common` for the shared
-//! `hx()` fixture helper and methodology note.
-//!
-//! The property worth a test file of its own is the **direction flip** on `MSG_QUEST_PUSH_RESULT`:
-//! one opcode number, two meanings for its `u64`. Going up it is the sharer we are answering;
-//! coming down it is the party member the verdict is *about*. Nothing in the type system can catch
-//! a swap, so it is pinned here from both ends.
+//! The party quest-share wire: the Share Quest push, the escort confirm, and the verdict relay.
+//! `MSG_QUEST_PUSH_RESULT`'s guid is the sharer going up and the member concerned coming down.
 
 mod common;
 
@@ -16,11 +8,11 @@ use benilla_protocol::messages::{self, opcode, quest_flags, QuestShareMsg};
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// The three CMSG builders, byte-exact (vmangos `Server/Packets/Quest.cpp:63-77`).
+/// The three CMSG bodies (vmangos `Server/Packets/Quest.cpp:63-77`).
 #[test]
 fn cmsg_bodies_golden() {
-    // CMSG_PUSHQUESTTOPARTY / CMSG_QUEST_CONFIRM_ACCEPT: one u32 quest id, nothing else — the
-    // server addresses the group itself, so no member guid rides along.
+    // CMSG_PUSHQUESTTOPARTY / CMSG_QUEST_CONFIRM_ACCEPT: one u32 quest id and no member guid; the
+    // server addresses the group itself.
     assert_eq!(
         messages::push_quest_to_party(0x1234),
         hx("34120000"),
@@ -32,8 +24,8 @@ fn cmsg_bodies_golden() {
         "CMSG_QUEST_CONFIRM_ACCEPT body"
     );
 
-    // MSG_QUEST_PUSH_RESULT going UP: u64 guid, then the u8 verdict. The guid is the SHARER we are
-    // answering (`Quest.cpp:73-77`).
+    // MSG_QUEST_PUSH_RESULT going up: the u64 guid of the sharer we answer, then the u8 verdict
+    // (`Quest.cpp:73-77`).
     assert_eq!(
         messages::quest_push_result(0x1234_5678_9abc_def0, QuestShareMsg::DECLINE_QUEST),
         hx("f0debc9a7856341203"),
@@ -41,9 +33,8 @@ fn cmsg_bodies_golden() {
     );
 }
 
-/// `MSG_QUEST_PUSH_RESULT` coming DOWN (`Quest.cpp:81-85`, written by
-/// `Player::SendPushToPartyResponse`): the same two fields, but the guid is now the party MEMBER
-/// the verdict concerns — never the sharer, and never us.
+/// `MSG_QUEST_PUSH_RESULT` coming down (`Quest.cpp:81-85`): the same two fields, the guid now the
+/// party member the verdict concerns.
 #[test]
 fn push_result_decodes_member_and_verdict() {
     let body = hx("f0debc9a7856341200");
@@ -64,27 +55,36 @@ fn push_result_decodes_member_and_verdict() {
     }
 }
 
-/// The whole verdict enum survives the round trip, including a value the client has no message
-/// for: an unmapped byte must reach the app as data, not kill the packet (the display table is
-/// where "show nothing" is decided).
+/// Every verdict byte survives encode, parse and decode; an unmapped one is data, not an error.
 #[test]
 fn every_verdict_byte_round_trips() {
-    for raw in [0u8, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0xFF] {
+    for raw in 0..=u8::MAX {
         let mut body = 1u64.to_le_bytes().to_vec();
         body.push(raw);
-        match messages::parse_server(opcode::MSG_QUEST_PUSH_RESULT, &body).unwrap() {
+        assert_eq!(
+            messages::quest_push_result(1, QuestShareMsg(raw)),
+            body,
+            "verdict {raw} encodes"
+        );
+        let p = messages::parse_server(opcode::MSG_QUEST_PUSH_RESULT, &body).unwrap();
+        match &p {
             ServerPacket::QuestPushResult(r) => {
                 assert_eq!(r.msg, QuestShareMsg(raw), "verdict {raw}");
                 assert_eq!(r.member, 1);
             }
             other => panic!("verdict {raw} parsed as {}", other.name()),
         }
+        match decode(p).as_slice() {
+            [SessionEvent::QuestPushResult { member: 1, msg }] => {
+                assert_eq!(*msg, QuestShareMsg(raw), "verdict {raw} decodes");
+            }
+            other => panic!("verdict {raw} decoded to {other:?}"),
+        }
     }
 }
 
-/// `SMSG_QUEST_CONFIRM_ACCEPT` (`Quest.cpp:131-136`): `u32 questId, cstr questTitle, u64
-/// senderGuid` — note the title sits BETWEEN the two numbers, so a reader that grouped the
-/// scalars would decode the guid out of the title's tail.
+/// `SMSG_QUEST_CONFIRM_ACCEPT` (`Quest.cpp:131-136`): `u32` questId, cstring title, `u64`
+/// senderGuid; the title sits between the two numbers.
 #[test]
 fn confirm_accept_decodes_id_title_sender() {
     let mut body = 1234u32.to_le_bytes().to_vec();
@@ -102,9 +102,8 @@ fn confirm_accept_decodes_id_title_sender() {
     }
 }
 
-/// The two flag bits the share flow reads, pinned against vmangos `QuestDef.h:145-160`. They are
-/// the only route by which the client learns a quest is shareable or an escort — the giver panels
-/// carry no flags at all.
+/// The two quest flags the share flow reads (vmangos `QuestDef.h:145-160`), the client's only
+/// sign that a quest is shareable or an escort.
 #[test]
 fn share_quest_flags_are_the_documented_bits() {
     assert_eq!(quest_flags::PARTY_ACCEPT, 0x2);
diff --git a/crates/benilla-protocol/tests/reputation.rs b/crates/benilla-protocol/tests/reputation.rs
index a283cfb8..777ff630 100644
--- a/crates/benilla-protocol/tests/reputation.rs
+++ b/crates/benilla-protocol/tests/reputation.rs
@@ -1,8 +1,5 @@
-//! The reputation pane's wire: the pane's three client verbs, byte-exact against the vmangos
-//! reader side, and the one server push (`SMSG_SET_FACTION_VISIBLE`) that carries no standing.
-//!
-//! The standing-bearing pair (`SMSG_INITIALIZE_FACTIONS` / `SMSG_SET_FACTION_STANDING`) already
-//! has its goldens in `tests/simple_packets.rs`, where it landed with the unit-reaction decode.
+//! The reputation pane's wire: its three client verbs, in vmangos's read order, and the one push
+//! without a standing, `SMSG_SET_FACTION_VISIBLE`.
 
 mod common;
 
@@ -11,26 +8,21 @@ use benilla_protocol::messages::{self, opcode};
 use benilla_protocol::ServerPacket;
 use common::hx;
 
-/// `CMSG_SET_FACTION_ATWAR` (293): `u32 repListId`, `u8 flag` — the pane's crossed-swords box.
-///
-/// Byte-exact against vmangos's reader (`WorldPackets::Misc::SetFactionAtWar::ReadFromWorldPacket`,
-/// `Server/Packets/Misc.cpp`, over the `uint32 repListId` / `uint8 flag` fields in `Misc.h`), which
-/// is the side that has to parse what we send.
+/// `CMSG_SET_FACTION_ATWAR` (293), the pane's crossed-swords box: `u32` repListId, `u8` flag
+/// (vmangos `SetFactionAtWar::ReadFromWorldPacket`).
 #[test]
 fn set_faction_at_war_body_is_slot_then_flag() {
     assert_eq!(opcode::CMSG_SET_FACTION_ATWAR, 293);
-    // Slot 21 (Booty Bay is reputationIndex 1; 21 is Darnassus's), war ON.
+    // Slot 21 (Darnassus), at war.
     assert_eq!(messages::set_faction_at_war(21, true), hx("1500000001"));
-    // …and OFF. The flag is a whole byte, not a bit — `0`, never a cleared bit in a mask.
+    // The flag is a whole byte: off is 0, not a cleared bit.
     assert_eq!(messages::set_faction_at_war(21, false), hx("1500000000"));
-    // Slot 0 is a REAL faction (the Bloodsail Buccaneers hold reputationIndex 0), so a zero slot
-    // is an ordinary request here — the "nothing" sentinel problem is the watched verb's alone.
+    // Slot 0 is a real faction (the Bloodsail Buccaneers), an ordinary request here.
     assert_eq!(messages::set_faction_at_war(0, true), hx("0000000001"));
 }
 
-/// `CMSG_SET_FACTION_INACTIVE` (791): `u32 repListId`, `u8 inactive` — the "move to inactive" box.
-///
-/// Byte-exact against `WorldPackets::Misc::SetFactionInactive::ReadFromWorldPacket`.
+/// `CMSG_SET_FACTION_INACTIVE` (791), the "move to inactive" box: `u32` repListId, `u8` inactive
+/// (vmangos `SetFactionInactive::ReadFromWorldPacket`).
 #[test]
 fn set_faction_inactive_body_is_slot_then_flag() {
     assert_eq!(opcode::CMSG_SET_FACTION_INACTIVE, 791);
@@ -38,14 +30,9 @@ fn set_faction_inactive_body_is_slot_then_flag() {
     assert_eq!(messages::set_faction_inactive(54, false), hx("3600000000"));
 }
 
-/// `CMSG_SET_WATCHED_FACTION` (792): one **signed** `i32` slot, `-1` for "watch nothing".
-///
-/// The signedness is the whole point and is why this has its own assert: vmangos writes the value
-/// straight into `PLAYER_FIELD_WATCHED_FACTION_INDEX` with `SetInt32Value`
-/// (`HandleSetWatchedFactionOpcode`), and slot `0` is a real faction — so a `0` here would watch the
-/// Bloodsail Buccaneers rather than clear the bar. FrameXML's `SetWatchedFactionIndex(0)` means "no
-/// display row"; translating that to [`messages::WATCHED_FACTION_NONE`] is the binding's job, above
-/// this layer, and this test pins the two values apart so the translation cannot be skipped silently.
+/// `CMSG_SET_WATCHED_FACTION` (792): one signed `i32` slot, -1 for none. vmangos writes it into
+/// `PLAYER_FIELD_WATCHED_FACTION_INDEX` (`HandleSetWatchedFactionOpcode`) and slot 0 is a real
+/// faction, so the binding maps FrameXML's `SetWatchedFactionIndex(0)` to `WATCHED_FACTION_NONE`.
 #[test]
 fn set_watched_faction_body_is_a_signed_slot_and_none_is_minus_one() {
     assert_eq!(opcode::CMSG_SET_WATCHED_FACTION, 792);
@@ -55,19 +42,14 @@ fn set_watched_faction_body_is_a_signed_slot_and_none_is_minus_one() {
         messages::set_watched_faction(messages::WATCHED_FACTION_NONE),
         hx("ffffffff")
     );
-    // The trap, asserted: watching slot 0 and watching nothing are different bytes.
     assert_ne!(
         messages::set_watched_faction(0),
         messages::set_watched_faction(messages::WATCHED_FACTION_NONE)
     );
 }
 
-/// `SMSG_SET_FACTION_VISIBLE` (291): one `u32` reputation-list slot, no standing
-/// (vmangos `ReputationMgr::SendVisible` / `SetFactionVisible::AppendBodyTo`).
-///
-/// The server pushes it the first time the player meets a faction. A client that drops it keeps a
-/// correct standing for a row the pane will not list — which is exactly the failure this parse arm
-/// exists to prevent, so the decode leg is asserted too.
+/// `SMSG_SET_FACTION_VISIBLE` (291): one `u32` reputation-list slot (vmangos
+/// `ReputationMgr::SendVisible`), pushed the first time the player meets a faction.
 #[test]
 fn set_faction_visible_parses_and_decodes() {
     assert_eq!(opcode::SMSG_SET_FACTION_VISIBLE, 291);
diff --git a/crates/benilla-protocol/tests/simple_packets.rs b/crates/benilla-protocol/tests/simple_packets.rs
index b19b4e22..5ac6e1af 100644
--- a/crates/benilla-protocol/tests/simple_packets.rs
+++ b/crates/benilla-protocol/tests/simple_packets.rs
@@ -1,7 +1,4 @@
-//! Simple bare-scalar server packets — bodies too trivial to need golden hex from a validated
-//! implementation: auth challenge/new-world/login-timespeed, the server-pushed sound trio, and
-//! weather. Split out of the former `tests/messages.rs` — see `tests/common` for the shared
-//! fixtures and methodology note.
+//! Server packets with small fixed bodies, parsed and decoded against hand-built bytes.
 
 mod common;
 
@@ -12,12 +9,11 @@ use common::hx;
 
 #[test]
 fn simple_server_bodies_parse() {
-    // SMSG_AUTH_CHALLENGE: just a u32 seed.
     match messages::parse_server(messages::opcode::SMSG_AUTH_CHALLENGE, &hx("efbeadde")).unwrap() {
         ServerPacket::AuthChallenge { server_seed } => assert_eq!(server_seed, 0xDEAD_BEEF),
         _ => panic!("auth challenge"),
     }
-    // SMSG_NEW_WORLD: map u32=1, position (1,2,3), orientation 0.5.
+    // SMSG_NEW_WORLD: u32 map, f32 x/y/z, f32 orientation.
     let nw = hx("010000000000803f0000004000004040000000bf");
     match messages::parse_server(messages::opcode::SMSG_NEW_WORLD, &nw).unwrap() {
         ServerPacket::NewWorld {
@@ -31,9 +27,8 @@ fn simple_server_bodies_parse() {
         }
         _ => panic!("new world"),
     }
-    // SMSG_LOGIN_SETTIMESPEED: packed DateTime (LSB up: minute:6, hour:5, weekday:3, day:6,
-    // month:4, year:5) with 14:30 on year 26 / month 6 / day 17; timescale. The day serial
-    // flattens the date with the packed convention's 31-day months: 26·372 + 6·31 + 17 = 9875.
+    // SMSG_LOGIN_SETTIMESPEED: packed date (LSB up: minute:6, hour:5, weekday:3, day:6, month:4,
+    // year:5) then f32 timescale. The day serial counts 31-day months: year·372 + month·31 + day.
     let datetime: u32 = (26 << 24) | (6 << 20) | (17 << 14) | (14 << 6) | 30;
     let mut ts = datetime.to_le_bytes().to_vec();
     ts.extend_from_slice(&0.0166_6667f32.to_le_bytes());
@@ -52,22 +47,15 @@ fn simple_server_bodies_parse() {
     }
 }
 
-/// The server wall clock (`CMSG_QUERY_TIME` 462 / `SMSG_QUERY_TIME_RESPONSE` 463, decision 1150):
-/// an empty request body, and a response of one LE `u32` of unix-epoch seconds — the epoch a timed
-/// quest's descriptor deadline is written in.
-///
-/// Byte-exact against the vmangos sender (`WorldSession::SendQueryTimeResponse`,
-/// `Handlers/QueryHandler.cpp:418-423` — `packet->time = (uint32)time(nullptr)`, that field and
-/// nothing else). The sample is a real present-day stamp with all four bytes distinct, so a byte
-/// order or width slip reads as a wildly wrong date rather than a plausible one.
+/// The response is one u32 of unix-epoch seconds (vmangos `Handlers/QueryHandler.cpp:418-423`).
 #[test]
-fn query_time_round_trips_the_server_wall_clock() {
+fn query_time_asks_empty_and_decodes_the_server_wall_clock() {
     assert!(
         messages::query_time().is_empty(),
         "CMSG_QUERY_TIME is a NullClientPacket"
     );
 
-    // 2026-08-13T12:00:00Z = 1_786_622_400 = 0x6a7db1c0.
+    // 2026-08-13T12:00:00Z = 1_786_622_400 = 0x6a7db1c0: four distinct bytes.
     assert_eq!(u32::from_le_bytes([0xc0, 0xb1, 0x7d, 0x6a]), 1_786_622_400);
     let p = messages::parse_server(messages::opcode::SMSG_QUERY_TIME_RESPONSE, &hx("c0b17d6a"))
         .unwrap();
@@ -84,19 +72,16 @@ fn query_time_round_trips_the_server_wall_clock() {
         }]
     ));
 
-    // A short body is an error, not a silent zero: every countdown drawn from this clock would
-    // otherwise be wrong rather than absent.
     assert!(
         messages::parse_server(messages::opcode::SMSG_QUERY_TIME_RESPONSE, &hx("c0b17d")).is_err()
     );
 }
 
-/// The cinematic trigger (opcode 250, body a bare `CinematicSequences.dbc` id u32 per the vmangos
-/// `SendCinematicStart` sender) parses and decodes to the event the Net drain must ack — and the
-/// char-delete result (opcode 60, one result byte) parses.
+/// `SMSG_TRIGGER_CINEMATIC` is one u32 `CinematicSequences.dbc` id; `SMSG_CHAR_DELETE` one byte,
+/// which the handshake consumes, so it decodes to no event.
 #[test]
 fn cinematic_and_char_delete_parse_and_decode() {
-    // SMSG_TRIGGER_CINEMATIC: u32 cinematic id (41 = the dwarf intro, live-captured 2026-07-07).
+    // 41 = the dwarf intro.
     let body = 41u32.to_le_bytes();
     let p = messages::parse_server(messages::opcode::SMSG_TRIGGER_CINEMATIC, &body).unwrap();
     assert!(matches!(
@@ -108,16 +93,14 @@ fn cinematic_and_char_delete_parse_and_decode() {
         [SessionEvent::CinematicTriggered { cinematic_id: 41 }]
     ));
 
-    // SMSG_CHAR_DELETE: one result byte (0x39 = success, live-verified).
+    // 0x39 = CHAR_DELETE_SUCCESS.
     let p = messages::parse_server(messages::opcode::SMSG_CHAR_DELETE, &[0x39]).unwrap();
     assert!(matches!(p, ServerPacket::CharDelete { result: 0x39 }));
+    assert!(decode(p).is_empty());
 }
 
-/// The server-pushed sound trio (opcodes vmangos `Opcodes_1_12_1.h` 631/632/722; bodies are bare
-/// LE scalars per the vmangos senders): each parses to its packet and decodes to one event.
 #[test]
 fn server_sound_trio_parse_and_decode() {
-    // SMSG_PLAY_SOUND: u32 soundId.
     let body = 8595u32.to_le_bytes();
     let p = messages::parse_server(messages::opcode::SMSG_PLAY_SOUND, &body).unwrap();
     assert!(matches!(p, ServerPacket::PlaySound { sound_id: 8595 }));
@@ -126,7 +109,6 @@ fn server_sound_trio_parse_and_decode() {
         [SessionEvent::PlaySound { sound_id: 8595 }]
     ));
 
-    // SMSG_PLAY_MUSIC: u32 musicId.
     let body = 2523u32.to_le_bytes();
     let p = messages::parse_server(messages::opcode::SMSG_PLAY_MUSIC, &body).unwrap();
     assert!(matches!(
@@ -134,8 +116,7 @@ fn server_sound_trio_parse_and_decode() {
         [SessionEvent::PlayMusic { music_id: 2523 }]
     ));
 
-    // SMSG_PLAY_OBJECT_SOUND: u32 soundId + u64 guid (the fishing-bobber splash, vmangos
-    // GameObject.cpp:373 sends exactly soundId 3355).
+    // 3355: the fishing-bobber splash (vmangos `GameObject.cpp:373`).
     let mut body = 3355u32.to_le_bytes().to_vec();
     body.extend_from_slice(&0xF110_0000_0000_002Au64.to_le_bytes());
     let p = messages::parse_server(messages::opcode::SMSG_PLAY_OBJECT_SOUND, &body).unwrap();
@@ -148,9 +129,7 @@ fn server_sound_trio_parse_and_decode() {
     ));
 }
 
-/// SMSG_WEATHER (opcode vmangos 756; body `u32 type, f32 grade, u32 soundId, u8 instant` per
-/// `Weather::SendWeatherForPlayersInZone`, 1.12 branch): parses and decodes to one event, with
-/// the soundId being a real SoundEntries loop kit (8534 = RainMedium).
+/// Body per vmangos `Weather::SendWeatherForPlayersInZone`; 8534 is the RainMedium sound loop.
 #[test]
 fn weather_parses_and_decodes() {
     let mut body = 1u32.to_le_bytes().to_vec(); // WEATHER_TYPE_RAIN
@@ -172,13 +151,11 @@ fn weather_parses_and_decodes() {
     }
 }
 
-/// `SMSG_SET_PROFICIENCY` (295): u8 itemClass + u32 subclass bitmask (vmangos `Skill.h` /
-/// `Skill.cpp AppendBodyTo`) — parses and decodes to the proficiency event the item tooltip's
-/// slot-line red reads.
+/// u8 itemClass + u32 subclass bitmask, per vmangos `Skill.cpp` `AppendBodyTo`.
 #[test]
 fn set_proficiency_parses_and_decodes() {
     assert_eq!(messages::opcode::SMSG_SET_PROFICIENCY, 295);
-    // Weapons (class 2), mask 0x2408F: the fresh-warrior shape.
+    // Weapons (class 2), mask 0x2408F: what a fresh warrior gets.
     let body = hx("028f400200");
     let p = messages::parse_server(messages::opcode::SMSG_SET_PROFICIENCY, &body).unwrap();
     match p {
@@ -201,13 +178,11 @@ fn set_proficiency_parses_and_decodes() {
     ));
 }
 
-/// `SMSG_SET_FACTION_STANDING` (292): u32 count + count x (u32 reputationListId, i32 standing)
-/// (vmangos `ReputationMgr::SendState` / `SetFactionStanding::AppendBodyTo`) — the mid-session
-/// standing delta the reputation red re-ranks from.
+/// u32 count + count x (u32 reputationListId, i32 standing), per vmangos `SetFactionStanding`.
 #[test]
 fn set_faction_standing_parses_and_decodes() {
     assert_eq!(messages::opcode::SMSG_SET_FACTION_STANDING, 292);
-    // Two slots: list 46 -> 3000, list 89 -> -6000 (a standing can go down).
+    // Two slots: list 46 -> 3000, list 89 -> -6000 (standing is signed).
     let body = hx("020000002e000000b80b00005900000090e8ffff");
     let p = messages::parse_server(messages::opcode::SMSG_SET_FACTION_STANDING, &body).unwrap();
     match p {
@@ -223,17 +198,10 @@ fn set_faction_standing_parses_and_decodes() {
     ));
 }
 
-/// The dropped-packet tally feed (the wire-coverage instrument): an opcode with no parse arm falls
-/// through to `ServerPacket::Other` and MUST decode to a `PacketDropped` event (not silence) so the
-/// app can tally the gap — and the generated 1.12.1 name table resolves both known and unassigned
-/// opcode numbers.
+/// An opcode with no parse arm decodes to `PacketDropped`, not silence, so the app can tally it.
 #[test]
 fn unknown_opcode_decodes_to_packet_dropped() {
-    // 0x021E = SMSG_SET_REST_START — assigned in 1.12.1 but deliberately unparsed by benilla.
-    // (The sentinel used to be 0x0319 `MSG_MOVE_TIME_SKIPPED`, which decision 1935 gave a parse
-    // arm; then 0x0324 `SMSG_PET_ACTION_SOUND`, which decision 2039 gave one — the pet's voice
-    // turned out to drive two real `CreatureSoundData` columns. A sentinel earning a parse arm is
-    // this test working, not this test breaking.)
+    // Sentinel: SMSG_SET_REST_START (0x021E) has no parse arm; swap in another if it gains one.
     let packet = messages::parse_server(0x021E, &hx("0102030405")).unwrap();
     assert!(matches!(packet, ServerPacket::Other { opcode: 0x021E }));
     match decode(packet).as_slice() {
@@ -243,7 +211,6 @@ fn unknown_opcode_decodes_to_packet_dropped() {
         }] => {}
         other => panic!("expected one PacketDropped event, got {other:?}"),
     }
-    // The generated name table: a known opcode resolves, an unassigned number doesn't.
     assert_eq!(messages::opcode_name(0x021E), Some("SMSG_SET_REST_START"));
     assert_eq!(
         messages::opcode_name(messages::opcode::SMSG_UPDATE_OBJECT),
@@ -252,16 +219,11 @@ fn unknown_opcode_decodes_to_packet_dropped() {
     assert_eq!(messages::opcode_name(0xFFFF), None);
 }
 
-/// The death arc's wire family (decision 0308): the corpse query answer (both shapes + the
-/// dungeon-entrance map split), the reclaim delay, a resurrect request, the spirit-healer
-/// confirm, and the ack'd movement-flag family with its PACKED mover guid — all through
-/// `parse_server` and the event decode.
 #[test]
 fn death_arc_family_parses_and_decodes() {
     use benilla_protocol::messages::opcode;
 
-    // MSG_CORPSE_QUERY, found: u8(1), i32 map 0, xyz, u32 corpsemap 36 (a dungeon corpse whose
-    // display coords were entrance-rewritten — the two maps deliberately differ).
+    // Found: a dungeon corpse reports its entrance's map and coords, so the two maps differ.
     let mut body = vec![1u8];
     body.extend_from_slice(&0i32.to_le_bytes());
     body.extend_from_slice(&(-11209.6f32).to_le_bytes());
@@ -283,14 +245,13 @@ fn death_arc_family_parses_and_decodes() {
         }
         other => panic!("corpse query decode: {other:?}"),
     }
-    // The unprompted not-found shape (bones conversion): the lone u8(0).
+    // Not found, also sent unprompted when the corpse turns to bones: a lone u8 0.
     let pkt = messages::parse_server(opcode::MSG_CORPSE_QUERY, &[0u8]).unwrap();
     match decode(pkt).as_slice() {
         [SessionEvent::CorpseQuery { found: false, .. }] => {}
         other => panic!("corpse query not-found decode: {other:?}"),
     }
 
-    // SMSG_CORPSE_RECLAIM_DELAY: u32 ms.
     let pkt = messages::parse_server(opcode::SMSG_CORPSE_RECLAIM_DELAY, &30_000u32.to_le_bytes())
         .unwrap();
     match decode(pkt).as_slice() {
@@ -313,7 +274,6 @@ fn death_arc_family_parses_and_decodes() {
         other => panic!("resurrect request decode: {other:?}"),
     }
 
-    // SMSG_SPIRIT_HEALER_CONFIRM: one full guid.
     let pkt = messages::parse_server(
         opcode::SMSG_SPIRIT_HEALER_CONFIRM,
         &0xF130_0000_0000_2AB3u64.to_le_bytes(),
@@ -326,10 +286,6 @@ fn death_arc_family_parses_and_decodes() {
         other => panic!("spirit healer confirm decode: {other:?}"),
     }
 
-    // **The whole ack'd movement-mode family, all eight opcodes** (decision 0866): one wire shape,
-    // PACKED guid + u32 counter. Guid 0x2A packs as mask 0x01 + one byte. Every pair is exercised,
-    // because the family's whole point is that adding a mode must not need a new lane — and because
-    // the four that were missing (feather-fall, hover) were missing *silently*.
     let body = hx("012a07000000"); // packed(0x2A) + counter 7
     for (op, mode, apply) in [
         (opcode::SMSG_FORCE_MOVE_ROOT, MoveMode::Root, true),
@@ -353,16 +309,13 @@ fn death_arc_family_parses_and_decodes() {
         }
     }
 
-    // The mode→bit map, VERIFIED vmangos `Objects/MovementInfo.h:25-62`. These are the bits the
-    // mover reads and the ack echoes, so a transcription slip here is silent everywhere else.
+    // The movement-flag bits (vmangos `Objects/MovementInfo.h:25-62`).
     assert_eq!(MoveMode::Root.flag(), 0x0000_1000);
     assert_eq!(MoveMode::WaterWalk.flag(), 0x1000_0000);
     assert_eq!(MoveMode::FeatherFall.flag(), 0x2000_0000);
     assert_eq!(MoveMode::Hover.flag(), 0x4000_0000);
 
-    // Root is the ONLY mode whose ack opcode differs by direction, and the only one whose ack body
-    // carries no trailing apply dword — vmangos routes it to `HandleMoveRootAck`, the other three to
-    // `HandleMovementFlagChangeToggleAck` (`Server/Protocol/Opcodes.cpp:314-816`).
+    // Root alone acks per direction, with no apply dword (vmangos `HandleMoveRootAck`).
     assert_eq!(
         MoveMode::Root.ack_opcode(true),
         opcode::CMSG_FORCE_MOVE_ROOT_ACK
@@ -382,10 +335,7 @@ fn death_arc_family_parses_and_decodes() {
     }
 }
 
-/// The movement-mode ack bodies (client side): full guid + echoed counter + MovementInfo, with the
-/// trailing `u32 apply` on every mode EXCEPT root (vmangos `Movement.cpp:38-59` — `MoveRootAck` has
-/// no apply dword). The root ack must be exactly 4 bytes shorter than the others for the same
-/// inputs.
+/// Root's ack lacks the trailing u32 apply the other modes carry (vmangos `Movement.cpp:38-59`).
 #[test]
 fn move_flag_ack_bodies_differ_by_the_apply_tail() {
     use benilla_protocol::messages::{move_flag_ack, MovementInfo};
@@ -410,13 +360,12 @@ fn move_flag_ack_bodies_differ_by_the_apply_tail() {
     assert_eq!(root.len() + 4, walk.len());
     assert_eq!(&walk[..root.len()], root.as_slice());
     assert_eq!(&walk[root.len()..], 1u32.to_le_bytes());
-    // The full (unpacked) guid + counter head.
+    // The ack's guid is full, not packed.
     assert_eq!(&root[..8], &0x2Au64.to_le_bytes());
     assert_eq!(&root[8..12], &7u32.to_le_bytes());
 }
 
-/// `SMSG_DURABILITY_DAMAGE_DEATH` (0x2BD): an EMPTY body (vmangos `DurabilityDamageDeath::
-/// AppendBodyTo` writes nothing) parsing to its cue event — the red 10%-loss error line.
+/// `SMSG_DURABILITY_DAMAGE_DEATH` (0x2BD): empty body; the cue for the 10% durability-loss line.
 #[test]
 fn durability_damage_death_is_an_empty_body_cue() {
     let pkt = messages::parse_server(messages::opcode::SMSG_DURABILITY_DAMAGE_DEATH, &[]).unwrap();
@@ -427,14 +376,10 @@ fn durability_damage_death_is_an_empty_body_cue() {
     ));
 }
 
-/// `SMSG_TRANSFER_PENDING` (0x3F): `u32 mapId` alone for an ordinary far teleport; `+ u32
-/// transportEntry + u32 oldMapId` when the player rides a transport through the transfer
-/// (VERIFIED vmangos `Misc.cpp:493-501`). The block's presence routes how NEW_WORLD's
-/// coordinates are read (decision 0455), so both shapes are pinned — and the abort
-/// (`SMSG_TRANSFER_ABORTED`, one reason byte) clears the latch.
+/// u32 mapId, then u32 transportEntry + u32 oldMapId when the player rides a transport through
+/// (vmangos `Misc.cpp:493-501`).
 #[test]
 fn transfer_pending_both_shapes_and_abort_parse_and_decode() {
-    // Plain: mapId 1 (Kalimdor), no transport block.
     let plain =
         messages::parse_server(messages::opcode::SMSG_TRANSFER_PENDING, &hx("01000000")).unwrap();
     assert!(matches!(
@@ -451,7 +396,7 @@ fn transfer_pending_both_shapes_and_abort_parse_and_decode() {
             transport_entry: None
         }]
     ));
-    // Riding: mapId 0 (EK), transportEntry 176310 (0x2B0B6 — the Menethil boat), oldMapId 1.
+    // Riding: 176310 is the Menethil boat, arriving in EK (0) from Kalimdor (1).
     let mut riding = 0u32.to_le_bytes().to_vec();
     riding.extend_from_slice(&176310u32.to_le_bytes());
     riding.extend_from_slice(&1u32.to_le_bytes());
@@ -470,7 +415,6 @@ fn transfer_pending_both_shapes_and_abort_parse_and_decode() {
             transport_entry: Some(176310)
         }]
     ));
-    // Abort: one reason byte.
     let abort = messages::parse_server(messages::opcode::SMSG_TRANSFER_ABORTED, &[2]).unwrap();
     assert!(matches!(abort, ServerPacket::TransferAborted { reason: 2 }));
     assert!(matches!(
@@ -479,19 +423,11 @@ fn transfer_pending_both_shapes_and_abort_parse_and_decode() {
     ));
 }
 
-/// `SMSG_CLIENT_CONTROL_UPDATE` — the possession handoff. Golden hex is hand-derived from
-/// vmangos's builder (`Server/Packets/Misc.cpp:677-682`): `moverGuid.WriteAsPacked()` then
-/// `uint8 allowMove`. The packed form is a mask byte whose bit *i* marks a non-zero byte *i* of
-/// the little-endian u64, followed by exactly those bytes — so the same guid costs a different
-/// number of bytes depending on its value, and getting the mask wrong desynchronises everything
-/// after it in the stream.
-///
-/// **The two cases below are the two the app must tell apart**, and they differ only in a guid:
-/// the server grants control by naming somebody *else* and revokes it by naming *us*.
+/// Packed mover guid then u8 allowMove (vmangos `Server/Packets/Misc.cpp:677-682`).
 #[test]
 fn client_control_update_reads_a_packed_mover_and_the_allow_byte() {
-    // Grant: a creature guid 0xF130000C1A00A2B4 with allowMove = 1. Non-zero LE bytes are
-    // b4 a2 00 1a 0c 00 30 f1 → indices 0,1,3,4,6,7 → mask 0b1101_1011 = 0xdb.
+    // Grant: creature 0xF130000C1A00A2B4, allowMove 1. Mask 0xdb marks its non-zero LE bytes
+    // (b4 a2 00 1a 0c 00 30 f1 → indices 0,1,3,4,6,7), which follow in order.
     let grant = hx("dbb4a21a0c30f101");
     match messages::parse_server(messages::opcode::SMSG_CLIENT_CONTROL_UPDATE, &grant).unwrap() {
         ServerPacket::ClientControlUpdate { mover, allow_move } => {
@@ -500,9 +436,7 @@ fn client_control_update_reads_a_packed_mover_and_the_allow_byte() {
         }
         other => panic!("client control update, got {}", other.name()),
     }
-    // Revoke: our own player guid 0x45 (one non-zero byte, index 0 → mask 0x01) with
-    // allowMove = 0. This is the shape a mind-controlled player receives about themselves, and
-    // the whole of what stops them walking away — vmangos never roots them.
+    // Revoke: our own guid 0x45, allowMove 0; vmangos never roots a mind-controlled player.
     let revoke = hx("014500");
     let revoke = messages::parse_server(messages::opcode::SMSG_CLIENT_CONTROL_UPDATE, &revoke)
         .expect("revoke parses");
@@ -520,8 +454,7 @@ fn client_control_update_reads_a_packed_mover_and_the_allow_byte() {
             allow_move: false
         }]
     ));
-    // A zero guid packs to a lone zero mask byte and no guid bytes at all — the degenerate case
-    // that would read the allow byte AS the guid if the mask were mishandled.
+    // A zero guid packs to a lone zero mask byte, so the very next byte is allowMove.
     let empty = messages::parse_server(messages::opcode::SMSG_CLIENT_CONTROL_UPDATE, &hx("0001"))
         .expect("empty guid parses");
     assert!(matches!(
@@ -533,40 +466,30 @@ fn client_control_update_reads_a_packed_mover_and_the_allow_byte() {
     ));
 }
 
-/// The hunter pet-feedback family (decision 2039) — the three arms that were name-table-only, on
-/// their real bodies.
-///
-/// The two **empty** bodies are the point of half this test: `SMSG_PET_NAME_INVALID` and
-/// `SMSG_PET_BROKEN` carry nothing at all (vmangos's `AppendBodyTo` writes nothing; the
-/// reference's handlers read nothing), so "parses" here means "the opcode alone produced the
-/// event" — and a body that arrives with junk on it must not change that.
 #[test]
 fn pet_feedback_family_parses_and_decodes() {
     use benilla_protocol::messages::opcode;
 
-    // SMSG_PET_TAME_FAILURE: one reason byte. 9 = PETTAME_TOOHIGHLEVEL.
+    // 9 = PETTAME_TOOHIGHLEVEL.
     let p = messages::parse_server(opcode::SMSG_PET_TAME_FAILURE, &hx("09")).unwrap();
     assert!(matches!(p, ServerPacket::PetTameFailure { reason: 9 }));
     assert!(matches!(
         decode(p)[..],
         [SessionEvent::PetTameFailure { reason: 9 }]
     ));
-    // The reason -> GlobalStrings key table, at both ends of the reference's bounds check
-    // (`0x6e6a20`: `reason - 1` bounded at `0xa`) and in the middle.
+    // Reason to GlobalStrings key: the reference bounds `reason - 1` at 0xa (`0x6e6a20`).
     assert_eq!(messages::pet_tame_failure_key(1), "PETTAME_INVALIDCREATURE");
     assert_eq!(
         messages::pet_tame_failure_key(5),
         "PETTAME_ANOTHERSUMMONACTIVE"
     );
     assert_eq!(messages::pet_tame_failure_key(11), "PETTAME_NOTDEAD");
-    // Out of range on BOTH sides falls to the default arm — including vmangos's own 12th value,
-    // which is `PETTAME_UNKNOWNERROR` in the enum and reaches the same string by the other road.
+    // Out of range on either side, vmangos's 12th value included, falls to the default arm.
     assert_eq!(messages::pet_tame_failure_key(0), "PETTAME_UNKNOWNERROR");
     assert_eq!(messages::pet_tame_failure_key(12), "PETTAME_UNKNOWNERROR");
     assert_eq!(messages::pet_tame_failure_key(200), "PETTAME_UNKNOWNERROR");
 
-    // SMSG_PET_NAME_INVALID / SMSG_PET_BROKEN: empty bodies, and unread ones — a body with bytes
-    // on it still decodes to the bare event, because neither handler reads one.
+    // The reference reads no body here (vmangos writes none), so stray bytes change nothing.
     for body in ["", "deadbeef"] {
         let p = messages::parse_server(opcode::SMSG_PET_NAME_INVALID, &hx(body)).unwrap();
         assert!(matches!(p, ServerPacket::PetNameInvalid), "body {body:?}");
@@ -595,10 +518,8 @@ fn pet_feedback_family_parses_and_decodes() {
         }]
     ));
 
-    // SMSG_PET_DISMISS_SOUND: a CreatureModelData id then a raw WoW x/y/z. Model 726, at
-    // (-8949.95, -132.493, 83.5312) — the human starting point, chosen because its bytes are
-    // recognisable if the field order ever slips. The handler's `+1.0` on z is a PLAY detail and
-    // must NOT appear here.
+    // SMSG_PET_DISMISS_SOUND: u32 CreatureModelData id then raw WoW x/y/z (the human start).
+    // The reference handler's +1.0 on z belongs to playback, not to the decode.
     let mut body = hx("d6020000"); // model 726
     for f in [-8949.95_f32, -132.493, 83.5312] {
         body.extend_from_slice(&f.to_le_bytes());
diff --git a/crates/benilla-protocol/tests/spells.rs b/crates/benilla-protocol/tests/spells.rs
index d1782449..ec00c833 100644
--- a/crates/benilla-protocol/tests/spells.rs
+++ b/crates/benilla-protocol/tests/spells.rs
@@ -1,8 +1,4 @@
-//! Spell/action/attack + spell-visual wire tests (mirrors `src/messages/spells.rs`): initial spells,
-//! action buttons, cast/attack swing, cast result, attacker state, plus the spell-visual pipeline
-//! (`SMSG_SPELL_START`/`GO`, `SMSG_SPELL_FAILED_OTHER`, `SMSG_CANCEL_AUTO_REPEAT`,
-//! `SMSG_PLAY_SPELL_VISUAL`, decision 0099 phase 1). Split out of the former `tests/messages.rs` —
-//! see `tests/common` for the shared fixtures and methodology note.
+//! Wire tests for spells, action buttons, melee and the combat log (`src/messages/spells.rs`).
 
 mod common;
 
@@ -15,7 +11,7 @@ use common::hx;
 fn spell_and_action_wire() {
     use benilla_protocol::messages::{ActionButton, CastOutcome, ACTION_KIND_ITEM};
 
-    // SMSG_INITIAL_SPELLS (vmangos Player::SendInitialSpells): u8 0; u16 n; n x (u16 id, u16 0);
+    // SMSG_INITIAL_SPELLS (vmangos `Player::SendInitialSpells`): u8 0; u16 n; n x (u16 id, u16 0);
     // u16 m; m x (u16 spell, u16 item, u16 category, u32 spellCdMs, u32 catCdMs).
     let body = hx(concat!(
         "00", "0300", "4e000000", // 78 Heroic Strike
@@ -40,7 +36,7 @@ fn spell_and_action_wire() {
         _ => panic!("initial spells"),
     }
 
-    // SMSG_ACTION_BUTTONS: 120 packed u32s — action bits 0-23, kind bits 24-31, 0 = empty.
+    // SMSG_ACTION_BUTTONS: 120 packed u32s, action bits 0-23, kind bits 24-31, 0 = empty.
     let mut body = vec![0u8; 120 * 4];
     body[0..4].copy_from_slice(&0x0000_1A11u32.to_le_bytes()); // slot 0: spell 6673
     body[4..8].copy_from_slice(&0x8000_0075u32.to_le_bytes()); // slot 1: item 117
@@ -70,14 +66,12 @@ fn spell_and_action_wire() {
             },
         ]
     );
-    // ...and the decode passes them through as the ActionButtons event.
     match decode(packet).pop().unwrap() {
         SessionEvent::ActionButtons { buttons: b } => assert_eq!(b, buttons),
         _ => panic!("action buttons event"),
     }
 
-    // CMSG_CAST_SPELL golden bytes (vmangos SpellCastTargets::read): self cast = mask 0, nothing
-    // follows; unit cast = mask 2 + PACKED guid (build > 1.8.4 reads targets packed).
+    // CMSG_CAST_SPELL targets per vmangos `SpellCastTargets::read`: packed guids after 1.8.4.
     assert_eq!(
         messages::cast_spell(6673, None),
         hx("111a00000000"),
@@ -90,8 +84,7 @@ fn spell_and_action_wire() {
         "unit cast: u32 id + u16 mask 2 + packed guid (mask 0xC9)"
     );
 
-    // CMSG_CAST_SPELL at an ITEM (0437 phase 3 — the enchant pick): mask 0x0010 + packed guid.
-    // Item guid 0x4700_0000_0000_0951: present bytes 0 (0x51), 1 (0x09), 7 (0x47) → mask 0x83.
+    // Guid 0x4700_0000_0000_0951 has non-zero bytes 0 (0x51), 1 (0x09), 7 (0x47) → mask 0x83.
     let enchant_target = 0x4700_0000_0000_0951u64;
     assert_eq!(
         messages::cast_spell_item(7418, enchant_target),
@@ -99,11 +92,10 @@ fn spell_and_action_wire() {
         "item cast: u32 id + u16 mask 0x10 + packed item guid"
     );
 
-    // CMSG_ATTACKSWING: one full 8-byte guid.
+    // CMSG_ATTACKSWING: one full 8-byte guid, not packed.
     assert_eq!(messages::attack_swing(victim), hx("2a000045000030f1"));
 
-    // CMSG_SET_ACTION_BUTTON opcode (296 / 0x0128 — vmangos Opcodes_1_12_1.h) + body: button u8 +
-    // packed u32 (WorldPackets::Misc::SetActionButton::ReadFromWorldPacket, Misc.cpp:87-90).
+    // CMSG_SET_ACTION_BUTTON: u8 button + packed u32 action (vmangos `Misc.cpp:87-90`).
     assert_eq!(
         messages::opcode::CMSG_SET_ACTION_BUTTON,
         0x0128,
@@ -120,10 +112,7 @@ fn spell_and_action_wire() {
         "packed 0 clears the slot"
     );
 
-    // CMSG_SET_ACTIONBAR_TOGGLES opcode (703 / 0x02BF) + body: ONE u8 and nothing else — VERIFIED
-    // at the bytes, wow-re `system/ui/scratch/action-bar-toggles.md` §3 (`0x4e771d push 0x2bf`,
-    // the one emitter image-wide; PutUInt32 opcode + PutUInt8 byte; NetClient::Send computes the
-    // payload as 5 = 4 + 1). vmangos corroborates: `Misc.cpp:150-153` reads a single uint8.
+    // CMSG_SET_ACTIONBAR_TOGGLES: one u8 (reference `0x4e771d`, vmangos `Misc.cpp:150-153`).
     assert_eq!(
         messages::opcode::CMSG_SET_ACTIONBAR_TOGGLES,
         0x02BF,
@@ -142,10 +131,9 @@ fn spell_and_action_wire() {
     assert_eq!(
         messages::set_actionbar_toggles(0x0f),
         hx("0f"),
-        "all four — the largest value the reference binding can ever accumulate (§2)"
+        "all four — the largest value the reference binding can ever accumulate"
     );
 
-    // CMSG_SETSHEATHED opcode (480 / 0x01E0 — vmangos Opcodes_1_12_1.h) + body: one u32 state.
     assert_eq!(
         messages::opcode::CMSG_SETSHEATHED,
         0x01E0,
@@ -175,11 +163,8 @@ fn spell_and_action_wire() {
         ),
         _ => panic!("cast fail event"),
     }
-    // The reason-specific argument words (`CastResult::AppendBodyTo`) are POSITIONAL — read by
-    // what is left in the body, never keyed off the reason. One word for 0x5e
-    // REQUIRES_SPELL_FOCUS (the `SpellFocusObject.dbc` id: 12 = "Starbreeze Village Moonwell",
-    // the `%s` of "Requires %s"); two for the 0x19 EQUIPPED_ITEM_CLASS family (class + subclass
-    // mask), whose second is read and dropped.
+    // Argument words are read by body length, not by reason (vmangos `CastResult::AppendBodyTo`).
+    // 12 = Starbreeze Village Moonwell (`SpellFocusObject.dbc`); 0x19's subclass mask is dropped.
     let focus = messages::parse_server(
         messages::opcode::SMSG_CAST_RESULT,
         &hx("111a0000025e0c000000"),
@@ -229,10 +214,7 @@ fn spell_and_action_wire() {
         _ => panic!("attack stop"),
     }
 
-    // SMSG_ATTACKERSTATEUPDATE (vmangos Unit::SendAttackStateUpdate, Unit.cpp:4572-4605 — decision
-    // 0073): HitInfo, attacker PackGUID **first**, victim PackGUID, TotalDamage, *two* sub-damage
-    // blocks (absorb summed across both — decision 0137 phase 2's floating combat text feed),
-    // VictimState, two u32s (zero + spell id), blocked. The offhand bit (0x4) rides HitInfo.
+    // SMSG_ATTACKERSTATEUPDATE, per vmangos `Unit.cpp:4572-4605`; the attacker guid comes first.
     let mut body = 0x6u32.to_le_bytes().to_vec(); // HitInfo: 0x2 | 0x4 (offhand)
     body.extend_from_slice(&hx("0101")); // attacker packed guid = 1
     body.extend_from_slice(&hx("c92a4530f1")); // victim packed guid
@@ -272,8 +254,7 @@ fn spell_and_action_wire() {
         _ => panic!("attacker state"),
     }
 
-    // SMSG_AI_REACTION (vmangos Creature::SendAIReaction → Misc.cpp:445-449): raw (unpacked)
-    // guid + reaction u32 — 2 HOSTILE (aggro), 0 ALERT (stealth pre-aggro).
+    // SMSG_AI_REACTION: raw guid + u32 reaction, 2 = HOSTILE (vmangos `Misc.cpp:445-449`).
     let body = hx(concat!("3412000000000000", "02000000"));
     let packet = messages::parse_server(messages::opcode::SMSG_AI_REACTION, &body).unwrap();
     match &packet {
@@ -288,19 +269,8 @@ fn spell_and_action_wire() {
     }
 }
 
-/// The melee swing family's SIX opcodes and FOUR arms — plus the one that must stay unparsed.
-///
-/// Every body is empty (vmangos `Server/Packets/Combat.cpp`: `AttackSwingNotInRange`,
-/// `AttackSwingBadFacing`, `AttackSwingDeadTarget`, `AttackSwingCantAttack` all have a no-op
-/// `AppendBodyTo`), so there are no bytes to pin — what needs pinning is the **arm map**, which is
-/// the reference's and not the wire's:
-///
-/// - `0x148` DEADTARGET and `0x149` CANT_ATTACK both reach arm 4 (`0x625ab8`) verbatim, so the
-///   client cannot tell them apart and neither can we;
-/// - `0x147` NOTSTANDING is **never registered** (`0x6255b0`'s table `0x625aec` has it on the
-///   default arm `0x625ade`) and vmangos never sends it
-///   (`Player::SendAttackSwingNotStanding` has zero callers), so it must stay an unknown opcode
-///   here. A future session adding it "for completeness" fails this test, which is the point.
+/// Every swing refusal has an empty body (vmangos `Server/Packets/Combat.cpp`). DEADTARGET (0x148)
+/// and CANT_ATTACK (0x149) share the reference's arm `0x625ab8`, so they decode alike.
 #[test]
 fn attack_swing_refusal_wire() {
     use benilla_protocol::messages::AttackSwingError;
@@ -334,7 +304,7 @@ fn attack_swing_refusal_wire() {
         }
     }
 
-    // The family's fourth arm — a different opcode family, the same empty body and the same act.
+    // SMSG_CANCEL_COMBAT is the fourth arm: another opcode family, same empty body and effect.
     assert!(
         matches!(
             messages::parse_server(messages::opcode::SMSG_CANCEL_COMBAT, &[]).unwrap(),
@@ -347,8 +317,7 @@ fn attack_swing_refusal_wire() {
         SessionEvent::CancelCombat
     ));
 
-    // The family's other empty-bodied sibling, sent from the same vmangos site as CANCEL_COMBAT —
-    // but a bare `DisplayError(421)` in the reference (`0x6e9800`), with no latch behind it.
+    // SMSG_FEIGN_DEATH_RESISTED: in the reference only a `DisplayError(421)` (`0x6e9800`).
     assert!(matches!(
         messages::parse_server(messages::opcode::SMSG_FEIGN_DEATH_RESISTED, &[]).unwrap(),
         ServerPacket::FeignDeathResisted
@@ -358,9 +327,8 @@ fn attack_swing_refusal_wire() {
         SessionEvent::FeignDeathResisted
     ));
 
-    // 0x147 SMSG_ATTACKSWING_NOTSTANDING — unregistered in the reference, unsent by vmangos, and
-    // therefore an UNKNOWN opcode here: it falls to the `Other` arm, which is exactly what
-    // `0x6255b0`'s default arm `0x625ade` does with it.
+    // 0x147 SMSG_ATTACKSWING_NOTSTANDING stays unknown: the reference never registers it (default
+    // arm `0x625ade`) and vmangos never sends it.
     assert!(
         matches!(
             messages::parse_server(0x0147, &[]).unwrap(),
@@ -370,20 +338,16 @@ fn attack_swing_refusal_wire() {
     );
 }
 
-/// The spell-visual pipeline wire (decision 0099 phase 1): `SMSG_SPELL_START`/`GO`,
-/// `SMSG_SPELL_FAILED_OTHER`, `SMSG_CANCEL_AUTO_REPEAT`, `SMSG_PLAY_SPELL_VISUAL`. Golden bytes are
-/// hand-built from the vmangos writers (`Spell.cpp:4468-4659`, `SpellCastTargetsInfo.cpp:180-234`,
-/// `Spell.cpp:4780-4789`, `Server/Packets/Misc.cpp:548-550`, `Server/Packets/Spell.cpp:54-58`) —
-/// there is no existing oracle for these opcodes.
+/// Spell-visual bodies per vmangos `Spell.cpp:4468-4659` and `4780-4789`,
+/// `SpellCastTargetsInfo.cpp:180-234`, `Server/Packets/Misc.cpp:548-550` and
+/// `Server/Packets/Spell.cpp:54-58`.
 #[test]
 fn spell_visual_wire_golden() {
     use benilla_protocol::messages::{SpellCastTargets, SpellGo, SpellStart};
 
-    let creature = 0xF130_0000_4500_002Au64; // packs mask 0xC9 (same fixture guid as elsewhere)
+    let creature = 0xF130_0000_4500_002Au64; // packs with mask 0xC9
 
-    // SMSG_SPELL_START, a Fireball-style cast: item_or_caster pguid (no cast item, guid 1) + caster
-    // pguid (the creature) + spellId + castFlags (CAST_FLAG_UNKNOWN2 only) + remaining cast-time ms
-    // + a unit-target SpellCastTargets block. No ammo (castFlags doesn't carry CAST_FLAG_AMMO).
+    // SMSG_SPELL_START, a Fireball-style cast at a unit. The ammo block rides only CAST_FLAG_AMMO.
     let body = hx(concat!(
         "0101",       // item_or_caster pguid: mask 1, guid 1
         "c92a4530f1", // caster pguid: the creature guid, mask 0xC9
@@ -438,16 +402,13 @@ fn spell_visual_wire_golden() {
         other => panic!("spell start event, got {other:?}"),
     }
 
-    // SMSG_SPELL_START, an instant self-cast: cast time 0 (never gets a `Casting` component — the
-    // net bridge's insert gate is `cast_time_ms > 0`), target mask 0 (TARGET_FLAG_SELF) — nothing
-    // follows the mask.
     let body = hx(concat!(
-        "0109",     // item_or_caster pguid: mask 1, guid 9 (no cast item — this is the caster itself)
+        "0109",     // item_or_caster pguid: mask 1, guid 9 (no cast item: the caster itself)
         "0109",     // caster pguid: same object, guid 9
         "11000000", // spellId 17
         "0200",     // castFlags 0x2
         "00000000", // remaining cast time: 0 (instant)
-        "0000",     // SpellCastTargets mask: 0 (SELF) — nothing follows
+        "0000",     // SpellCastTargets mask: 0 (SELF), nothing follows
     ));
     let packet = messages::parse_server(messages::opcode::SMSG_SPELL_START, &body).unwrap();
     match decode(packet).pop().unwrap() {
@@ -461,10 +422,7 @@ fn spell_visual_wire_golden() {
         other => panic!("instant spell start event, got {other:?}"),
     }
 
-    // SMSG_SPELL_GO, a ranged Auto Shot: the same guid pair + spellId + castFlags (UNKNOWN9 |
-    // AMMO) + a 2-hit/2-miss target list (one plain miss, one SPELL_MISS_REFLECT with its trailing
-    // reflectResult byte) + a unit-target SpellCastTargets block + the ammo block (displayId
-    // 5996, inventoryType dropped).
+    // SMSG_SPELL_GO: only a SPELL_MISS_REFLECT miss carries the extra reflectResult byte.
     let body = hx(concat!(
         "0101",             // item_or_caster pguid: guid 1
         "c92a4530f1",       // caster pguid: the creature
@@ -530,18 +488,13 @@ fn spell_visual_wire_golden() {
             assert_eq!(go_target, None); // a unit-targeted cast leaves the GO target empty
             assert_eq!(dest, None); // …and the ground point empty (mask 0x2, no 0x40)
             assert_eq!(ammo_display_id, Some(5996));
-            // The packet's first guid (1) differs from the caster — an item cast, surfaced for
-            // the item-use cooldown key.
+            // A first guid that differs from the caster marks an item cast.
             assert_eq!(item_caster, Some(1));
         }
         other => panic!("spell go event, got {other:?}"),
     }
 
-    // SMSG_SPELL_GO for a GROUND cast (the B132 follow-up): empty hit/miss lists, mask 0x0040 +
-    // the dest Vector3d — the exact shape the live vmangos Blizzard capture produced
-    // (2026-07-30; the f32 bit patterns below are the captured DYNAMICOBJECT_POS values). The
-    // event layer must surface the point — it is the only launch-side record of where the
-    // spell went.
+    // A ground cast (Blizzard): mask 0x0040 + dest, a real cast's DYNAMICOBJECT_POS.
     let body = hx(concat!(
         "011a",     // item_or_caster pguid: guid 0x1a (== caster: a plain spell, no item)
         "011a",     // caster pguid
@@ -582,18 +535,12 @@ fn spell_visual_wire_golden() {
         other => panic!("ground spell go event, got {other:?}"),
     }
 
-    // SMSG_SPELL_GO for a **GameObject caster** — the Priest's Lightwell (GO entry 181102) casting
-    // spell 7001 "Lightwell Renew" on the player who clicked it. `GameObject::Use` keeps
-    // `spellCaster = this` for `GAMEOBJECT_TYPE_SPELLCASTER` (22) and builds the GameObject
-    // overload, whose ctor leaves `Unit* const m_casterUnit = nullptr` standing (`Spell.cpp:102`,
-    // `Spell.h:368`) — so `SendSpellGo`'s slot-2 write `WriteGuidHelper(data, m_casterUnit)`
-    // (`Spell.cpp:4513`) emits `ObjectGuid().WriteAsPacked()`: a lone zero mask byte, guid 0.
-    // Slot 1 still carries the object (no cast item → `m_caster`). The event layer must resolve the
-    // pair, or the cast has no caster the world index can ever hold and loses its whole visual body.
-    const LIGHTWELL: u64 = 0xF110_02C3_6E00_0123; // HIGHGUID_GAMEOBJECT | entry 181102 << 24 | 0x123
+    // A GameObject caster (Lightwell 181102, spell 7001): vmangos writes the null `m_casterUnit`
+    // as a lone zero mask byte (`Spell.cpp:4513`), so the object rides only slot 1.
+    const LIGHTWELL: u64 = 0xF110_02C3_6E00_0123; // GO high guid, entry 181102 << 24, counter 0x123
     let body = hx(concat!(
-        "fb23016ec30210f1", // item_or_caster pguid: the GameObject (mask 0xfb — byte 2 is zero)
-        "00",               // caster pguid: EMPTY — vmangos wrote a null `m_casterUnit`
+        "fb23016ec30210f1", // item_or_caster pguid: the GameObject (mask 0xfb: byte 2 is zero)
+        "00",               // caster pguid: empty, vmangos writes a null `m_casterUnit`
         "591b0000",         // spellId 7001 (Lightwell Renew)
         "0001",             // castFlags 0x100 (CAST_FLAG_UNKNOWN9)
         "01",               // hit count 1
@@ -605,7 +552,6 @@ fn spell_visual_wire_golden() {
     let packet = messages::parse_server(messages::opcode::SMSG_SPELL_GO, &body).unwrap();
     match &packet {
         ServerPacket::SpellGo(g) => {
-            // The message layer stays a faithful decode: slot 2 really is empty on the wire.
             assert_eq!((g.item_or_caster, g.caster), (LIGHTWELL, 0));
         }
         other => panic!("lightwell spell go, got {}", other.name()),
@@ -648,8 +594,7 @@ fn spell_visual_wire_golden() {
         other => panic!("spell failed other event, got {other:?}"),
     }
 
-    // SMSG_SPELL_DELAYED: raw (unpacked) guid + pushback ms (vmangos `Spell::Delayed` — `data <<
-    // ObjectGuid` is a raw u64, then `u32` delaytime). 500ms = 0x1F4.
+    // SMSG_SPELL_DELAYED: raw guid + u32 pushback ms (vmangos `Spell::Delayed`).
     let body = hx(concat!("4200000000000000", "f4010000"));
     let packet = messages::parse_server(messages::opcode::SMSG_SPELL_DELAYED, &body).unwrap();
     match &packet {
@@ -665,7 +610,7 @@ fn spell_visual_wire_golden() {
         other => panic!("spell delayed event, got {other:?}"),
     }
 
-    // SMSG_CANCEL_AUTO_REPEAT: empty body (vmangos `CancelAutoRepeat::AppendBodyTo` writes nothing).
+    // SMSG_CANCEL_AUTO_REPEAT: empty body (vmangos `CancelAutoRepeat::AppendBodyTo`).
     let packet = messages::parse_server(messages::opcode::SMSG_CANCEL_AUTO_REPEAT, &[]).unwrap();
     assert!(matches!(packet, ServerPacket::CancelAutoRepeat));
     assert!(matches!(
@@ -687,8 +632,8 @@ fn spell_visual_wire_golden() {
         other => panic!("play spell visual event, got {other:?}"),
     }
 
-    // MSG_CHANNEL_START: spellId + duration, both u32 — self-only, no guid on the wire (vmangos
-    // `Spell::SendChannelStart`, `Spell.cpp:4951-4954`; decision 0137). 10797 Starshards, 6s.
+    // MSG_CHANNEL_START: u32 spellId + u32 duration, no guid since only the caster gets it
+    // (vmangos `Spell.cpp:4951-4954`). 10797 is Starshards.
     let body = hx(concat!("2d2a0000", "70170000"));
     let packet = messages::parse_server(messages::opcode::MSG_CHANNEL_START, &body).unwrap();
     match &packet {
@@ -706,8 +651,7 @@ fn spell_visual_wire_golden() {
         other => panic!("channel start event, got {other:?}"),
     }
 
-    // MSG_CHANNEL_UPDATE: one u32 time-left (vmangos `Player::SendChannelUpdate`,
-    // `Player.cpp:21106-21110`); 0 = the channel is over.
+    // MSG_CHANNEL_UPDATE: u32 ms left, 0 = over (vmangos `Player.cpp:21106-21110`).
     let body = hx("b80b0000");
     let packet = messages::parse_server(messages::opcode::MSG_CHANNEL_UPDATE, &body).unwrap();
     match &packet {
@@ -719,8 +663,6 @@ fn spell_visual_wire_golden() {
         other => panic!("channel update event, got {other:?}"),
     }
 
-    // Truncated buffers fail cleanly rather than silently short-reading (the codec's usual
-    // contract — every reader is `Read::read_exact`-backed, which errors on a short buffer).
     let body = hx(concat!(
         "0101",
         "c92a4530f1",
@@ -739,10 +681,7 @@ fn spell_visual_wire_golden() {
     assert!(messages::parse_server(messages::opcode::SMSG_SPELL_GO, &body).is_err());
 }
 
-/// An open-lock cast on a chest / locked door: `SMSG_SPELL_GO` whose `SpellCastTargets` names a
-/// GameObject (`TARGET_FLAG_GAMEOBJECT`, no unit target). The decoder must surface the GO guid so the
-/// lid/door animation can open it (decision 2271) — the guid the older decode read for alignment and
-/// dropped.
+/// An open-lock cast names its chest or door as a `TARGET_FLAG_GAMEOBJECT` target, not a unit.
 #[test]
 fn spell_go_surfaces_the_gameobject_target() {
     let body = hx(concat!(
@@ -778,12 +717,8 @@ fn spell_go_surfaces_the_gameobject_target() {
     }
 }
 
-/// The combat-log wire (decision 0137 phase 2's floating-combat-text data feed):
-/// `SMSG_SPELLNONMELEEDAMAGELOG`, `SMSG_PERIODICAURALOG`, `SMSG_SPELLDAMAGESHIELD`,
-/// `SMSG_SPELLLOGMISS`, `SMSG_LOG_XPGAIN`, `SMSG_LEVELUP_INFO`. Golden bytes are hand-built from
-/// the vmangos writers (`Server/Packets/Spell.cpp:68-86,124-140`, `Unit.cpp:4395-4443`,
-/// `Server/Packets/Combat.cpp:73-79`, `Server/Packets/Misc.cpp:512-532`) — there is no existing
-/// oracle for these opcodes.
+/// Combat-log bodies per vmangos `Server/Packets/Spell.cpp:68-86,124-140`, `Unit.cpp:4395-4443`,
+/// `Server/Packets/Combat.cpp:73-79` and `Server/Packets/Misc.cpp:512-532`.
 #[test]
 fn combat_log_wire_golden() {
     use benilla_protocol::messages::{
@@ -791,11 +726,8 @@ fn combat_log_wire_golden() {
         PeriodicTick, SpellDamageLog, SpellLogMiss, XpGain,
     };
 
-    let creature = 0xF130_0000_4500_002Au64; // packs mask 0xC9 (same fixture guid as elsewhere)
+    let creature = 0xF130_0000_4500_002Au64; // packs with mask 0xC9
 
-    // SMSG_SPELLNONMELEEDAMAGELOG: target PackedGuid, attacker PackedGuid, spellId, damage, school
-    // u8, absorbed, resist i32, periodicLog u8 (bool), unused u8, blocked, hitInfo, extendedData u8
-    // (always 0, dropped). hitInfo 0x2 = SPELL_HIT_TYPE_CRIT.
     let body = hx(concat!(
         "c92a4530f1", // target pguid: the creature
         "0101",       // attacker pguid: guid 1
@@ -807,7 +739,7 @@ fn combat_log_wire_golden() {
         "00",         // periodicLog: false (direct, not a DoT tick)
         "00",         // unused
         "0a000000",   // blocked 10
-        "02000000",   // hitInfo 0x2 (crit)
+        "02000000",   // hitInfo 0x2 (SPELL_HIT_TYPE_CRIT)
         "00",         // extendedData (always 0, dropped)
     ));
     let packet =
@@ -837,8 +769,7 @@ fn combat_log_wire_golden() {
         other => panic!("spell damage log event, got {other:?}"),
     }
 
-    // SMSG_PERIODICAURALOG: target PackedGuid, caster PackedGuid, spellId, count, then `count` x
-    // {auraType u32, payload}. First vector: one PERIODIC_DAMAGE (3) tick.
+    // SMSG_PERIODICAURALOG: target, caster, spellId, then count x {u32 auraType, payload}.
     let body = hx(concat!(
         "c92a4530f1", // target pguid: the creature
         "0101",       // caster pguid: guid 1
@@ -875,7 +806,6 @@ fn combat_log_wire_golden() {
         other => panic!("periodic aura log event, got {other:?}"),
     }
 
-    // Second vector: one PERIODIC_HEAL (8) tick — a self-heal (target == caster).
     let body = hx(concat!(
         "0101",     // target pguid: guid 1
         "0101",     // caster pguid: guid 1 (self)
@@ -900,8 +830,7 @@ fn combat_log_wire_golden() {
         other => panic!("periodic aura log (heal), got {}", other.name()),
     }
 
-    // Third vector: an unrecognized auraType (4) cannot be skipped without desyncing the stream —
-    // decode must fail rather than guess a payload width.
+    // An unhandled auraType has no known payload width, so the decode fails rather than desync.
     let body = hx(concat!(
         "0101",     // target
         "0101",     // caster
@@ -911,8 +840,7 @@ fn combat_log_wire_golden() {
     ));
     assert!(messages::parse_server(messages::opcode::SMSG_PERIODICAURALOG, &body).is_err());
 
-    // SMSG_SPELLDAMAGESHIELD: victim raw guid, attacker raw guid, damage, school — all four fields
-    // distinct. `victim` is the shield's bearer; `attacker` receives the damage back.
+    // SMSG_SPELLDAMAGESHIELD: `victim` bears the shield; `attacker` takes the damage back.
     let body = hx(concat!(
         "1111000000000000", // victim raw guid 0x1111
         "2222000000000000", // attacker raw guid 0x2222
@@ -939,9 +867,8 @@ fn combat_log_wire_golden() {
         other => panic!("damage shield event, got {other:?}"),
     }
 
-    // SMSG_ENVIRONMENTALDAMAGELOG: victim raw guid (vmangos `ObjectGuid.cpp:174` streams the raw
-    // u64, NOT a PackedGuid), damageType u8, damage, absorbed, resist i32 (the > 1.6.1 tail,
-    // `Server/Packets/Combat.cpp:58-67`). Type 2 = fall.
+    // SMSG_ENVIRONMENTALDAMAGELOG: a raw victim guid (vmangos `ObjectGuid.cpp:174`); absorbed and
+    // resist are the post-1.6.1 tail (`Server/Packets/Combat.cpp:58-67`).
     let body = hx(concat!(
         "0300000000000000", // victim raw guid 3
         "02",               // damageType 2 (DAMAGE_FALL)
@@ -973,9 +900,8 @@ fn combat_log_wire_golden() {
         other => panic!("environmental damage log event, got {other:?}"),
     }
 
-    // SMSG_SPELLLOGMISS: spellId, caster raw guid, useExtended u8 (0 here — no trailing 2xf32 per
-    // entry), count, then `count` x {target raw guid, missInfo u8}. Two entries: DODGE (3) and
-    // REFLECT (11) — the reflect trailing byte only rides SMSG_SPELL_GO's miss list, not this one.
+    // SMSG_SPELLLOGMISS: count x {raw target guid, u8 missInfo}; useExtended 1 adds 2 x f32 per
+    // entry. REFLECT's extra byte rides only SMSG_SPELL_GO's miss list, not this one.
     let body = hx(concat!(
         "85000000",         // spellId 133
         "4200000000000000", // caster raw guid 0x42
@@ -1005,9 +931,6 @@ fn combat_log_wire_golden() {
         other => panic!("spell log miss event, got {other:?}"),
     }
 
-    // SMSG_LOG_XPGAIN: victim raw guid (0 for non-kill) + total + xpType (0 kill, carries trailing
-    // base+bonus; 1 non-kill, nothing trailing). Both vectors consume exactly their own body — a
-    // kill's trailing base/bonus is present, a non-kill's is absent.
     let mut body = 0xCCu64.to_le_bytes().to_vec(); // victim
     body.extend_from_slice(&250u32.to_le_bytes()); // total
     body.push(0); // xpType: kill
@@ -1035,7 +958,7 @@ fn combat_log_wire_golden() {
 
     let mut body = 0u64.to_le_bytes().to_vec(); // victim: 0 (non-kill xp has no victim)
     body.extend_from_slice(&50u32.to_le_bytes()); // total
-    body.push(1); // xpType: non-kill — nothing trails
+    body.push(1); // xpType: non-kill, nothing trails
     let packet = messages::parse_server(messages::opcode::SMSG_LOG_XPGAIN, &body).unwrap();
     match &packet {
         ServerPacket::XpGain(x) => {
@@ -1056,9 +979,8 @@ fn combat_log_wire_golden() {
         other => panic!("xp gain event, got {other:?}"),
     }
 
-    // SMSG_EXPLORATION_EXPERIENCE: areaId u32 (an AreaTable.dbc row id) + xp u32 — exactly
-    // 8 bytes (VERIFIED vmangos Misc.cpp:552-556; sent even when xp is 0). The vector is
-    // Westfall (area 40) worth 85 xp.
+    // SMSG_EXPLORATION_EXPERIENCE: u32 AreaTable.dbc id (40 = Westfall) + u32 xp, sent even when
+    // xp is 0 (vmangos `Misc.cpp:552-556`).
     let mut body = 40u32.to_le_bytes().to_vec();
     body.extend_from_slice(&85u32.to_le_bytes());
     assert_eq!(body.len(), 8);
@@ -1081,9 +1003,8 @@ fn combat_log_wire_golden() {
         other => panic!("exploration xp event, got {other:?}"),
     }
 
-    // SMSG_LEVELUP_INFO: twelve u32 — level, healthGain, powerGains[5] (mana..happiness),
-    // statGains[5] (str..spirit). VERIFIED vmangos Misc.cpp:524-532; exactly 48 bytes, no guid
-    // (self-addressed). The vector is a caster-flavored ding: mana + int/spirit heavy.
+    // SMSG_LEVELUP_INFO: twelve u32, level, healthGain, powerGains[5] (mana..happiness) and
+    // statGains[5] (str..spirit), no guid (vmangos `Misc.cpp:524-532`).
     let mut body = Vec::new();
     for v in [7u32, 22, 15, 0, 0, 0, 0, 1, 0, 1, 2, 1] {
         body.extend_from_slice(&v.to_le_bytes());
@@ -1110,25 +1031,18 @@ fn combat_log_wire_golden() {
     }
 }
 
-/// `SMSG_SPELL_UPDATE_CHAIN_TARGETS` — the beam's hop list (decision 0955). Byte-exact against
-/// vmangos `Spell::SendChannelStart` (`Spell.cpp:4970-4997`), which writes an `ObjectGuid` (raw
-/// `u64`, never packed), then `u32 spellId`, then a `u32` count, then that many raw guids. The
-/// client's handler `0x6e9820` decodes exactly that shape.
-///
-/// This is the packet the whole beam system hangs off: it is the **only** producer of the client's
-/// chain-target array (`unit+0xd44`), so a decode slip here reads as "the beams came back wrong"
-/// rather than as a parse error.
+/// Raw caster guid, u32 spellId, u32 count, raw guids (vmangos `Spell.cpp:4970-4997`); in the
+/// reference (`0x6e9820`) the only writer of the beams' chain-target array (`unit+0xd44`).
 #[test]
 fn spell_chain_targets_wire() {
     use benilla_protocol::messages::SpellChainTargets;
 
     const CASTER: u64 = 0x0000_01f1_3045_2ac9;
 
-    // Drain Life (689) channelled from a creature onto one target — the common case, count 1.
     let body = hx(concat!(
-        "c92a4530f1010000", // caster guid, RAW u64 (not packed)
+        "c92a4530f1010000", // caster guid, raw u64 (not packed)
         "b1020000",         // spellId 689 (Drain Life)
-        "01000000",         // count 1 — a u32, not the u8 the GO lists use
+        "01000000",         // count 1: a u32, not the u8 the GO lists use
         "aa00000000000000", // target guid 0xAA, raw
     ));
     let packet =
@@ -1153,7 +1067,6 @@ fn spell_chain_targets_wire() {
         other => panic!("chain targets event, got {other:?}"),
     }
 
-    // A three-hop chain, hop order preserved: the beam runs caster -> t1 -> t2 -> t3.
     let body = hx(concat!(
         "0100000000000000",
         "a5010000", // spellId 421 (Chain Lightning)
@@ -1170,8 +1083,7 @@ fn spell_chain_targets_wire() {
         other => panic!("chain targets, got {}", other.name()),
     }
 
-    // An empty list is legal on the wire (the server only *sends* when it has hits, but the shape
-    // is a count) and must decode rather than error.
+    // An empty list is legal on the wire, though the server only sends the packet with hits.
     let body = hx(concat!("0100000000000000", "a5010000", "00000000"));
     match messages::parse_server(messages::opcode::SMSG_SPELL_UPDATE_CHAIN_TARGETS, &body).unwrap()
     {
@@ -1179,7 +1091,7 @@ fn spell_chain_targets_wire() {
         other => panic!("chain targets, got {}", other.name()),
     }
 
-    // A truncated body is an error, not a silent short list — the count says 2, one guid follows.
+    // Count 2 with one guid following is an error, not a short list.
     let body = hx(concat!(
         "0100000000000000",
         "a5010000",
@@ -1191,19 +1103,15 @@ fn spell_chain_targets_wire() {
     );
 }
 
-/// **The combat-log completeness wire** (decision 1703) — the eight bodies 1571 §5 named as
-/// "deliberately out because their wire sources are undecoded". Byte-exact against vmangos's own
-/// writers, cited per packet, because a wrong field order here is a wrong *sentence* in the chat
-/// log and no gate downstream can see it.
+/// Eight combat-log opcodes, each parsed against the vmangos writer cited at it.
 #[test]
-fn combat_log_completeness_wire() {
+fn kill_outcome_dispel_enchantment_and_execute_logs_parse() {
     use benilla_protocol::messages::{
         DispelFailed, EnchantmentLog, ExecuteLog, PartyKillLog, SpellDispelLog, SpellInstaKillLog,
         SpellLogExecute, SpellOutcomeLog,
     };
 
-    // SMSG_PARTYKILLLOG: killer raw guid, victim raw guid
-    // (`WorldPackets::Combat::PartyKillLog::AppendBodyTo`, Combat.cpp:52-56).
+    // SMSG_PARTYKILLLOG: raw killer + raw victim guid (vmangos `Server/Packets/Combat.cpp:52-56`).
     let body = hx(concat!(
         "0700000000000000", // killer 7
         "2a00000000000000", // victim 42
@@ -1219,8 +1127,7 @@ fn combat_log_completeness_wire() {
         other => panic!("party kill log, got {}", other.name()),
     }
 
-    // SMSG_SPELLINSTAKILLLOG: victim raw guid, spellId (`Spell::EffectInstaKill`,
-    // SpellEffects.cpp:274-279).
+    // SMSG_SPELLINSTAKILLLOG: raw victim guid, u32 spellId (vmangos `SpellEffects.cpp:274-279`).
     let body = hx(concat!("0900000000000000", "0d270000"));
     match messages::parse_server(messages::opcode::SMSG_SPELLINSTAKILLLOG, &body).unwrap() {
         ServerPacket::SpellInstaKillLog(p) => assert_eq!(
@@ -1233,8 +1140,7 @@ fn combat_log_completeness_wire() {
         other => panic!("instakill log, got {}", other.name()),
     }
 
-    // SMSG_PROCRESIST / SMSG_SPELLORDAMAGE_IMMUNE: one body, two opcodes
-    // (`WorldPackets::Spell::ProcResist`/`SpellOrDamageImmune`, Spell.cpp:88-102).
+    // One body, two opcodes (vmangos `Server/Packets/Spell.cpp:88-102`).
     let body = hx(concat!(
         "0100000000000000", // caster 1
         "0200000000000000", // target 2
@@ -1256,8 +1162,7 @@ fn combat_log_completeness_wire() {
         other => panic!("spell-or-damage immune, got {}", other.name()),
     }
 
-    // SMSG_SPELLDISPELLOG: victim PACKED guid, caster PACKED guid, count, count x spellId
-    // (`Spell::EffectDispel`, SpellEffects.cpp:2524-2539 — the >= 1.12.1 branch, which is ours).
+    // SMSG_SPELLDISPELLOG, per vmangos `SpellEffects.cpp:2524-2539` (its 1.12.1 branch).
     let body = hx(concat!(
         "0105",     // packed victim: mask 0x01, byte 0x05 -> 5
         "0206",     // packed caster: mask 0x02, byte 0x06 -> 0x600
@@ -1277,8 +1182,8 @@ fn combat_log_completeness_wire() {
         other => panic!("spell dispel log, got {}", other.name()),
     }
 
-    // SMSG_DISPEL_FAILED: caster raw guid, victim raw guid, then spell ids TO THE END OF THE BODY —
-    // vmangos writes no count (`Spell::EffectDispel`, SpellEffects.cpp:2549-2555).
+    // SMSG_DISPEL_FAILED: raw caster, raw victim, then spell ids to the end of the body, with no
+    // count (vmangos `SpellEffects.cpp:2549-2555`).
     let body = hx(concat!(
         "0300000000000000",
         "0400000000000000",
@@ -1296,18 +1201,15 @@ fn combat_log_completeness_wire() {
         ),
         other => panic!("dispel failed, got {}", other.name()),
     }
-    // The same packet with no failures at all is a legal two-guid body, not a parse error.
     let body = hx(concat!("0300000000000000", "0400000000000000"));
     match messages::parse_server(messages::opcode::SMSG_DISPEL_FAILED, &body).unwrap() {
         ServerPacket::DispelFailed(p) => assert!(p.spell_ids.is_empty()),
         other => panic!("dispel failed, got {}", other.name()),
     }
 
-    // SMSG_ENCHANTMENTLOG: caster raw guid, owner raw guid, itemEntry, spellId, showAffiliation
-    // (`WorldPackets::Item::EnchantmentLog::AppendBodyTo`, Item.cpp:235-242). An EMPTY caster is
-    // how the server says the enchant FADED (`Player::SendEnchantmentLog`'s own comment).
+    // SMSG_ENCHANTMENTLOG, per vmangos `Server/Packets/Item.cpp:235-242`.
     let body = hx(concat!(
-        "0000000000000000", // caster 0 -> a fade
+        "0000000000000000", // caster 0: the enchant faded
         "0b00000000000000", // owner 11
         "d2040000",         // itemEntry 1234
         "39050000",         // spellId 1337
@@ -1327,11 +1229,7 @@ fn combat_log_completeness_wire() {
         other => panic!("enchantment log, got {}", other.name()),
     }
 
-    // SMSG_SPELLLOGEXECUTE: caster PACKED guid, spellId, groupCount, then per group
-    // {effect, rowCount, rows} (`Spell::SendLogExecute`, Spell.cpp:4662-4778). Three groups here
-    // cover the three payload shapes that are not a bare guid, including POWER_DRAIN's
-    // (amount, power, multiplier) — the order verified at the client's own bytes, not only at
-    // vmangos's (see `ExecuteLog::PowerDrain`).
+    // SMSG_SPELLLOGEXECUTE (vmangos `Spell.cpp:4662-4778`): row shape varies by effect.
     let body = hx(concat!(
         "0107",     // packed caster 7
         "e8030000", // spellId 1000
@@ -1343,11 +1241,11 @@ fn combat_log_completeness_wire() {
         "2c010000",         // amount 300
         "00000000",         // power 0 (mana)
         "0000803f",         // multiplier 1.0
-        // group 2: effect 24 CREATE_ITEM, one row — an item entry and nothing else
+        // group 2: effect 24 CREATE_ITEM, one row of just an item entry
         "18000000",
         "01000000",
         "b80b0000", // itemEntry 3000
-        // group 3: effect 102 DISMISS_PET, one row — the guid-only tail of the switch
+        // group 3: effect 102 DISMISS_PET, one row of just a guid
         "66000000",
         "01000000",
         "1e00000000000000", // target 30
@@ -1376,30 +1274,25 @@ fn combat_log_completeness_wire() {
         other => panic!("spell log execute, got {}", other.name()),
     }
 
-    // An effect id vmangos has no case for cannot be skipped — its row width is not on the wire —
-    // so the body errors rather than desyncing. vmangos never sends one: its own switch returns
-    // before `SendMessageToSet`, so an unlisted effect means no packet, never a truncated one.
+    // An effect vmangos has no case for has no known row width, so the body errors; vmangos never
+    // sends one, since its switch returns before `SendMessageToSet`.
     let body = hx(concat!(
         "0107", "e8030000", "01000000", "77000000", "01000000"
     ));
     assert!(messages::parse_server(messages::opcode::SMSG_SPELLLOGEXECUTE, &body).is_err());
 }
 
-/// The talent spell-modifier pair, end to end: both opcodes through `parse_server` and on into a
-/// [`SessionEvent`]. One handler, one body, and the opcode as the only discriminant — so the two
-/// bodies here are byte-identical and only the `flat` flag differs.
+/// The flat and pct spell-modifier opcodes share one body; only the opcode sets `flat`.
 #[test]
 fn spell_modifier_wire() {
-    // mask_bit 35 · op 14 (SPELLMOD_COST) · value -30. Bit 35 is deliberately past the low dword:
-    // it is a real shipped value (Cure Poison 526's only bit) and it is the half a 32-bit mask
-    // would quietly drop.
+    // u8 mask_bit 35, u8 op 14 (SPELLMOD_COST), i32 value -30. Bit 35, Cure Poison 526's only
+    // bit, sits past the low dword that a 32-bit mask would keep.
     let body = hx("230ee2ffffff");
     for (wire_op, is_flat) in [
         (messages::opcode::SMSG_SET_FLAT_SPELL_MODIFIER, true),
         (messages::opcode::SMSG_SET_PCT_SPELL_MODIFIER, false),
     ] {
         let packet = messages::parse_server(wire_op, &body).unwrap();
-        // The name recovers the opcode, which the collapsed-arm families cannot.
         assert_eq!(
             packet.name(),
             if is_flat {
@@ -1428,8 +1321,6 @@ fn spell_modifier_wire() {
         }
     }
 
-    // Five bytes is not a body: the value is a dword, not the three bytes a "u8 u8 u8 i16" misread
-    // would take.
     assert!(messages::parse_server(
         messages::opcode::SMSG_SET_FLAT_SPELL_MODIFIER,
         &hx("230ee2ffff")
diff --git a/crates/benilla-protocol/tests/stable.rs b/crates/benilla-protocol/tests/stable.rs
index 1c7a9db0..1d8e19eb 100644
--- a/crates/benilla-protocol/tests/stable.rs
+++ b/crates/benilla-protocol/tests/stable.rs
@@ -1,13 +1,5 @@
-//! Oracle-free golden tests for the stable-master arc's protocol layer (decision 1676): the five
-//! send verbs, the `MSG_LIST_STABLED_PETS` list, and the `SMSG_STABLE_RESULT` byte. Same idioms as
-//! `trainer.rs` — `hx(...)` golden CMSG bodies, hand-built SMSG bodies round-tripped through
-//! `parse_server`.
-//!
-//! Every layout here is VERIFIED against vmangos: the send bodies from
-//! `Server/Packets/Npc.cpp:51-76` (`ReadFromWorldPacket` for each `ClientPacket`), the list from
-//! `WorldSession::SendStablePet` (`Handlers/NPCHandler.cpp:522-575`), and the result byte from
-//! `StableResult::AppendBodyTo` (`Npc.cpp:99-102`) with the codes from that file's
-//! `StableResultCode` enum (`NPCHandler.cpp:40-47`).
+//! Stable-master wire: send bodies per vmangos `Server/Packets/Npc.cpp:51-76`, the pet list per
+//! `Handlers/NPCHandler.cpp:522-575` and the result byte per `Npc.cpp:99-102`.
 
 use benilla_protocol::messages::{self, stable_result, StabledPet};
 use benilla_protocol::ServerPacket;
@@ -24,10 +16,7 @@ const NPC_HEX: &str = "f0debc9a78563412";
 
 #[test]
 fn stable_send_bodies_golden() {
-    // The three guid-only verbs. They are byte-identical bodies on three different opcodes — the
-    // opcode IS the verb — so each is asserted separately rather than through a shared helper: a
-    // writer that sent `stable_pet`'s body under `CMSG_BUY_STABLE_SLOT` would still match a shared
-    // assertion.
+    // Three guid-only verbs with identical bodies: only the opcode tells them apart.
     assert_eq!(
         messages::list_stabled_pets(NPC),
         hx(NPC_HEX),
@@ -44,9 +33,7 @@ fn stable_send_bodies_golden() {
         "CMSG_BUY_STABLE_SLOT body"
     );
 
-    // The two pet-number verbs: u64 npcGuid, u32 petNumber. The number is the pet's OWN id
-    // (`character_pet.id`), never its slot — a body carrying a slot index would name the wrong pet
-    // for every hunter whose stable is not in id order.
+    // u64 npcGuid + u32 petNumber, the pet's own id (`character_pet.id`), never its slot.
     assert_eq!(
         messages::unstable_pet(NPC, 42),
         hx(&format!("{NPC_HEX}2a000000")),
@@ -59,9 +46,7 @@ fn stable_send_bodies_golden() {
     );
 }
 
-/// Append one variable-length pet record to a `MSG_LIST_STABLED_PETS` body, in wire order:
-/// `u32 petNumber, u32 creatureEntry, u32 level, cstring name, u32 loyalty, u8 slot` — where
-/// `slot` is the **wire** value (1-based), not the client index the decode produces.
+/// Appends one pet record in wire order; `wire_slot` is 1-based, unlike the decoded index.
 fn push_pet(
     body: &mut Vec<u8>,
     pet_number: u32,
@@ -101,11 +86,8 @@ fn parse_list(body: &[u8]) -> (u64, u8, Vec<StabledPet>) {
     }
 }
 
-/// A full hunter: a pet at their side and both stable slots occupied. **The slot rebasing is the
-/// assertion that matters** — the wire is 1-based (`SendStablePet` writes a literal `0x01` for the
-/// current pet and `it->slot + 1` for a stabled one) and the client is 0-based, so a decode that
-/// forwarded the wire byte would put the current pet in stable slot 1 and drop the last pet off the
-/// end of a 3-slot window.
+/// Wire slots are 1-based (`SendStablePet` writes 1 for the current pet and `slot + 1` for a
+/// stabled one); decoded slots are 0-based.
 #[test]
 fn a_full_stable_decodes_with_client_slot_indices() {
     let body = list_body(
@@ -135,16 +117,13 @@ fn a_full_stable_decodes_with_client_slot_indices() {
     );
     assert_eq!(pets[1].slot, 1);
     assert_eq!(pets[2].slot, 2);
-    // The name is a cstring mid-record, so every field after it depends on having consumed it
-    // exactly: a mis-read name shifts loyalty and slot together.
+    // The name is a cstring mid-record; every later field depends on consuming it exactly.
     assert_eq!(pets[2].name, "Nibbles");
     assert_eq!((pets[2].loyalty, pets[2].creature_entry), (1, 883));
 }
 
-/// A hunter with **no current pet** — the row for slot 0 is simply absent (vmangos emits it only
-/// for a live `HUNTER_PET` or a cached one). The rows must therefore be read BY SLOT: a consumer
-/// that treated `pets[0]` as the current pet would show a stabled wolf standing at the player's
-/// side.
+/// vmangos sends the slot-0 row only for a live or cached `HUNTER_PET`, so rows are read by slot,
+/// never by position.
 #[test]
 fn an_absent_current_pet_leaves_no_slot_zero_row() {
     let body = list_body(1, &[(8, 1126, 38, "Bruiser", 4, 2)]);
@@ -158,26 +137,21 @@ fn an_absent_current_pet_leaves_no_slot_zero_row() {
     assert!(!pets.iter().any(|p| p.slot == 0));
 }
 
-/// A hunter who has bought a slot and stabled nothing: an empty list with a non-zero slot count.
-/// This must decode to an empty vec — the count and the rows are independent numbers, and treating
-/// `num_stable_slots` as a row count would over-read the body.
+/// The purchased slot count and the row count are independent numbers.
 #[test]
 fn an_empty_list_still_carries_the_purchased_slot_count() {
     let (_, slots, pets) = parse_list(&list_body(1, &[]));
     assert_eq!(slots, 1);
     assert!(pets.is_empty());
 
-    // And the true zero state: nothing bought, nothing stabled.
     let (_, slots, pets) = parse_list(&list_body(0, &[]));
     assert_eq!(slots, 0);
     assert!(pets.is_empty());
 }
 
-/// Every `StableResultCode` vmangos can send, round-tripped. The success codes are distinct
-/// numbers but `SUCCESS_UNSTABLE` answers BOTH a plain unstable and a swap, so the reply alone
-/// never identifies which verb ran.
+/// Each result byte parses as itself, and the codes are vmangos's `StableResultCode` values.
 #[test]
-fn stable_result_codes_round_trip() {
+fn stable_result_codes_parse_as_their_vmangos_bytes() {
     for code in [
         stable_result::ERR_MONEY,
         stable_result::ERR_STABLE,
@@ -191,8 +165,7 @@ fn stable_result_codes_round_trip() {
         }
     }
 
-    // The values themselves, against vmangos's enum — a renumbering here would silently turn a
-    // refusal into a success in the app's match.
+    // vmangos's `StableResultCode` values (`NPCHandler.cpp:40-47`).
     assert_eq!(
         [
             stable_result::ERR_MONEY,
diff --git a/crates/benilla-protocol/tests/taxi.rs b/crates/benilla-protocol/tests/taxi.rs
index 5ab454cc..80d3fe09 100644
--- a/crates/benilla-protocol/tests/taxi.rs
+++ b/crates/benilla-protocol/tests/taxi.rs
@@ -1,9 +1,4 @@
-//! Oracle-free golden tests for the taxi/flight-master arc's protocol layer (decision 0484 phase
-//! 1): the four `CMSG_TAXI*` send verbs, the `SMSG_SHOWTAXINODES` map + `TaxiMask` bit law, the
-//! `SMSG_TAXINODE_STATUS` status/learn packet, `SMSG_ACTIVATETAXIREPLY`'s verdict codes, and the
-//! empty `SMSG_NEW_TAXI_PATH` ack. Same idioms as `trainer.rs`/`gossip_vendor.rs` — `hx(...)`
-//! golden CMSG bodies, hand-built SMSG bodies round-tripped through `parse_server`, each SMSG's
-//! `decode()` bridge exercised too.
+//! Flight-master wire: the taxi send verbs, the node map and its mask, status, reply and path ack.
 
 use benilla_protocol::events::{decode, SessionEvent};
 use benilla_protocol::messages::{self, taxi_reply, TaxiMask};
@@ -18,8 +13,7 @@ fn hx(s: &str) -> Vec<u8> {
 
 #[test]
 fn taxi_send_bodies_golden() {
-    // CMSG_TAXINODE_STATUS_QUERY / CMSG_TAXIQUERYAVAILABLENODES (vmangos Packets/Taxi.cpp): both
-    // a single full 8-byte guid — same shape as CMSG_GOSSIP_HELLO / CMSG_TRAINER_LIST.
+    // Both queries are one full 8-byte guid (vmangos `Packets/Taxi.cpp`).
     assert_eq!(
         messages::taxi_node_status_query(0x1234_5678_9abc_def0),
         hx("f0debc9a78563412"),
@@ -31,16 +25,14 @@ fn taxi_send_bodies_golden() {
         "CMSG_TAXIQUERYAVAILABLENODES body"
     );
 
-    // CMSG_ACTIVATETAXI (vmangos ActivateTaxi::ReadFromWorldPacket): guid, node1, node2 — a
-    // single-hop flight, Stormwind (2) -> Sentinel Hill (4).
+    // CMSG_ACTIVATETAXI: guid, from node, to node; Stormwind (2) -> Sentinel Hill (4).
     assert_eq!(
         messages::activate_taxi(0x1234_5678_9abc_def0, 2, 4),
         hx(concat!("f0debc9a78563412", "02000000", "04000000")),
         "CMSG_ACTIVATETAXI body"
     );
 
-    // CMSG_ACTIVATETAXIEXPRESS (vmangos ActivateTaxiExpress::ReadFromWorldPacket): guid,
-    // totalcost, nodeCount, nodeCount x node — a 3-node chain at a combined 110-copper fare.
+    // CMSG_ACTIVATETAXIEXPRESS: guid, u32 total cost, u32 count, count x u32 node.
     assert_eq!(
         messages::activate_taxi_express(0x1234_5678_9abc_def0, 110, &[2, 3, 4]),
         hx(concat!(
@@ -53,7 +45,6 @@ fn taxi_send_bodies_golden() {
         )),
         "CMSG_ACTIVATETAXIEXPRESS body"
     );
-    // An empty node list still writes a zero count, not a truncated body.
     assert_eq!(
         messages::activate_taxi_express(0x1234_5678_9abc_def0, 0, &[]),
         hx(concat!("f0debc9a78563412", "00000000", "00000000")),
@@ -63,9 +54,7 @@ fn taxi_send_bodies_golden() {
 
 #[test]
 fn taxi_mask_bit_law() {
-    // Bit law (vmangos PlayerTaxi.h IsTaximaskNodeKnown/SetTaximaskNode): 1-based node id,
-    // field = (id-1)/32, bit = (id-1)%32. Node 2 -> field 0 bit 1 (0x2); node 4 -> field 0 bit 3
-    // (0x8); node 33 -> field 1 bit 0 (0x1) — the first id that crosses into the second word.
+    // Node ids are 1-based: field (id-1)/32, bit (id-1)%32 (vmangos `PlayerTaxi.h`).
     let mask = TaxiMask([0x0000_000A, 0x0000_0001, 0, 0, 0, 0, 0, 0]);
     assert!(mask.is_known(2));
     assert!(mask.is_known(4));
@@ -77,9 +66,7 @@ fn taxi_mask_bit_law() {
 
 #[test]
 fn show_taxi_nodes_wire() {
-    // SMSG_SHOWTAXINODES (vmangos SendTaxiMenu, TaxiHandler.cpp:82-96): u32 windowConstant
-    // (always 1), u64 flightmasterGuid (PLAIN, not packed), u32 nearestNode, u32[8] knownMask.
-    // 48 bytes fixed. Mask carries node 2 (Stormwind) and node 33 (crosses into the second word).
+    // SMSG_SHOWTAXINODES (vmangos `TaxiHandler.cpp:82-96`): window always 1, guid not packed.
     let mut body = 1u32.to_le_bytes().to_vec(); // window constant
     body.extend_from_slice(&0xCCu64.to_le_bytes()); // flightmaster guid
     body.extend_from_slice(&2u32.to_le_bytes()); // nearest node
@@ -105,7 +92,6 @@ fn show_taxi_nodes_wire() {
         other => panic!("show taxi nodes, got {}", other.name()),
     }
 
-    // The decode() bridge drops the gate word and carries the rest straight through.
     let packet = messages::parse_server(messages::opcode::SMSG_SHOWTAXINODES, &body).unwrap();
     match decode(packet).pop().unwrap() {
         SessionEvent::TaxiNodesShown {
@@ -119,9 +105,7 @@ fn show_taxi_nodes_wire() {
         other => panic!("taxi nodes shown event, got {other:?}"),
     }
 
-    // The leading word is the client parser's own conditional gate (0496 §claim-1): a zero gate
-    // ends the body right there — 4 bytes total, and no event out of decode. vmangos never sends
-    // it; the parse is faithful anyway.
+    // The leading word gates the reference's parse: 0 ends the body (vmangos never sends 0).
     let gated = 0u32.to_le_bytes().to_vec();
     let packet = messages::parse_server(messages::opcode::SMSG_SHOWTAXINODES, &gated).unwrap();
     assert!(
@@ -132,8 +116,7 @@ fn show_taxi_nodes_wire() {
 
 #[test]
 fn taxi_node_status_wire() {
-    // SMSG_TAXINODE_STATUS (vmangos TaxiNodeStatus::AppendBodyTo): u64 guid (PLAIN), u8 known
-    // (a C++ bool — one byte). Exercise both known and unknown.
+    // SMSG_TAXINODE_STATUS (vmangos `TaxiNodeStatus::AppendBodyTo`): raw u64 guid + u8 known.
     let mut known_body = 0xCCu64.to_le_bytes().to_vec();
     known_body.push(1);
     match messages::parse_server(messages::opcode::SMSG_TAXINODE_STATUS, &known_body).unwrap() {
@@ -157,7 +140,7 @@ fn taxi_node_status_wire() {
 
 #[test]
 fn activate_taxi_reply_and_new_taxi_path_wire() {
-    // SMSG_ACTIVATETAXIREPLY (vmangos ActivateTaxiReply::AppendBodyTo): one u32 TaxiError code.
+    // SMSG_ACTIVATETAXIREPLY (vmangos `ActivateTaxiReply::AppendBodyTo`): one u32 TaxiError code.
     let body = taxi_reply::NOT_ENOUGH_MONEY.to_le_bytes().to_vec();
     match messages::parse_server(messages::opcode::SMSG_ACTIVATETAXIREPLY, &body).unwrap() {
         ServerPacket::ActivateTaxiReply { code } => {
@@ -173,11 +156,8 @@ fn activate_taxi_reply_and_new_taxi_path_wire() {
         other => panic!("activate taxi reply event, got {other:?}"),
     }
 
-    // TaxiError values (vmangos Objects/Player.h:404-416) — pinned so a future edit can't drift
-    // them. Codes actually emitted by Player::ActivateTaxiPathTo (this session's grep of
-    // Player.cpp:18008-18252): OK, UNSPECIFIED_SERVER_ERROR, NO_SUCH_PATH, NOT_ENOUGH_MONEY,
-    // TOO_FAR, BUSY, ALREADY_MOUNTED, SHAPESHIFTED. The rest are defined but never sent.
-    // (13-wide, so an array rather than a tuple — Rust's tuple trait impls stop at 12.)
+    // vmangos `TaxiError` (`Objects/Player.h:404-416`); `ActivateTaxiPathTo` only ever sends 0-4
+    // and 7-9 (`Player.cpp:18008-18252`).
     assert_eq!(
         [
             taxi_reply::OK,
@@ -197,7 +177,6 @@ fn activate_taxi_reply_and_new_taxi_path_wire() {
         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
     );
 
-    // SMSG_NEW_TAXI_PATH — empty body (vmangos NewTaxiPath::AppendBodyTo writes nothing).
     match messages::parse_server(messages::opcode::SMSG_NEW_TAXI_PATH, &[]).unwrap() {
         ServerPacket::NewTaxiPath => {}
         other => panic!("new taxi path, got {}", other.name()),
diff --git a/crates/benilla-protocol/tests/trainer.rs b/crates/benilla-protocol/tests/trainer.rs
index 904e1bae..b8319686 100644
--- a/crates/benilla-protocol/tests/trainer.rs
+++ b/crates/benilla-protocol/tests/trainer.rs
@@ -1,10 +1,4 @@
-//! Oracle-free golden tests for the training arc's protocol layer (decision 0237): the
-//! `CMSG_TRAINER_LIST`/`CMSG_TRAINER_BUY_SPELL` send verbs, the `SMSG_TRAINER_LIST` service list and
-//! the buy succeeded/failed results, and the incremental spell-learn pair
-//! (`SMSG_LEARNED_SPELL`/`SMSG_SUPERCEDED_SPELL`). Same idioms as `gossip_vendor.rs` — `hx(...)`
-//! golden CMSG bodies, hand-built SMSG bodies round-tripped through `parse_server`. The learn pair
-//! also asserts its `decode()` bridge (phase 2 wired those events); the trainer list/buy variants
-//! stay consumer-free until phases 3–4 wire the `TrainerState` events + `ClassTrainerFrame`.
+//! Trainer wire: the list and buy send verbs, the service list, buy results and spell learning.
 
 use benilla_protocol::events::{decode, SessionEvent};
 use benilla_protocol::messages::{self, train_fail, trainer_spell_state, TrainerSpell};
@@ -19,15 +13,14 @@ fn hx(s: &str) -> Vec<u8> {
 
 #[test]
 fn trainer_send_bodies_golden() {
-    // CMSG_TRAINER_LIST (vmangos Npc.cpp, TrainerList::Read): one full trainer guid — same shape as
-    // CMSG_GOSSIP_HELLO / CMSG_LIST_INVENTORY.
+    // CMSG_TRAINER_LIST: one full trainer guid (vmangos `Npc.cpp` `TrainerList::Read`).
     assert_eq!(
         messages::trainer_list(0x1234_5678_9abc_def0),
         hx("f0debc9a78563412"),
         "CMSG_TRAINER_LIST body"
     );
 
-    // CMSG_TRAINER_BUY_SPELL (vmangos Npc.cpp, TrainerBuySpell::Read): u64 trainerGuid, u32 spellId.
+    // CMSG_TRAINER_BUY_SPELL: u64 trainerGuid + u32 spellId (vmangos `TrainerBuySpell::Read`).
     assert_eq!(
         messages::trainer_buy_spell(0x1234_5678_9abc_def0, 78),
         hx(concat!("f0debc9a78563412", "4e000000")),
@@ -35,9 +28,7 @@ fn trainer_send_bodies_golden() {
     );
 }
 
-/// Append one 38-byte service record (vmangos SendTrainerSpellHelper, NPCHandler.cpp:97-139) to a
-/// SMSG_TRAINER_LIST body: spell u32, state u8, cost u32, canLearnPrimaryProf u32, isPrimaryProfFirstRank
-/// u32, reqLevel u8, reqSkill u32, reqSkillValue u32, then three prerequisite-spell u32s.
+/// Appends one 38-byte service record in wire order (vmangos `NPCHandler.cpp:97-139`).
 fn push_service(
     body: &mut Vec<u8>,
     spell: u32,
@@ -65,10 +56,7 @@ fn push_service(
 
 #[test]
 fn trainer_list_wire() {
-    // SMSG_TRAINER_LIST (vmangos SendTrainerList, NPCHandler.cpp:141-241): u64 trainerGuid, u32
-    // trainerType, u32 count, count x 38-byte service, cstr title. Two services: a green (learnable)
-    // class spell with a level gate, and a gray (already-known) primary-profession first rank with a
-    // skill gate + one prerequisite spell — exercising both prof flag fields and the req_spells array.
+    // SMSG_TRAINER_LIST, per vmangos `SendTrainerList` (`NPCHandler.cpp:141-241`).
     let mut body = 0xCCu64.to_le_bytes().to_vec();
     body.extend_from_slice(&0u32.to_le_bytes()); // trainerType 0 = class
     body.extend_from_slice(&2u32.to_le_bytes()); // count
@@ -116,7 +104,6 @@ fn trainer_list_wire() {
         other => panic!("trainer list, got {}", other.name()),
     }
 
-    // Empty trainer (count 0): the title still follows immediately — no service records to read.
     let mut empty = 0xDDu64.to_le_bytes().to_vec();
     empty.extend_from_slice(&2u32.to_le_bytes()); // trainerType 2 = tradeskill
     empty.extend_from_slice(&0u32.to_le_bytes()); // count
@@ -135,7 +122,6 @@ fn trainer_list_wire() {
         other => panic!("empty trainer list, got {}", other.name()),
     }
 
-    // The decode() bridge maps title → greeting and carries the wire services through (phase 3).
     let packet = messages::parse_server(messages::opcode::SMSG_TRAINER_LIST, &body).unwrap();
     match decode(packet).pop().unwrap() {
         SessionEvent::TrainerList {
@@ -153,7 +139,7 @@ fn trainer_list_wire() {
 
 #[test]
 fn trainer_buy_result_wire() {
-    // SMSG_TRAINER_BUY_SUCCEEDED (vmangos TrainerBuySucceeded::AppendBodyTo): u64 trainerGuid, u32 spellId.
+    // SMSG_TRAINER_BUY_SUCCEEDED (vmangos `TrainerBuySucceeded`): u64 trainerGuid, u32 spellId.
     let mut ok = 0xCCu64.to_le_bytes().to_vec();
     ok.extend_from_slice(&78u32.to_le_bytes());
     match messages::parse_server(messages::opcode::SMSG_TRAINER_BUY_SUCCEEDED, &ok).unwrap() {
@@ -163,8 +149,7 @@ fn trainer_buy_result_wire() {
         other => panic!("trainer buy succeeded, got {}", other.name()),
     }
 
-    // SMSG_TRAINER_BUY_FAILED (vmangos TrainerBuyFailed::AppendBodyTo): u64 trainerGuid, u32 serviceId,
-    // u32 errorCode.
+    // SMSG_TRAINER_BUY_FAILED (vmangos `TrainerBuyFailed`): u64 guid, u32 serviceId, u32 error.
     let mut failed = 0xCCu64.to_le_bytes().to_vec();
     failed.extend_from_slice(&78u32.to_le_bytes());
     failed.extend_from_slice(&train_fail::NOT_ENOUGH_MONEY.to_le_bytes());
@@ -182,8 +167,7 @@ fn trainer_buy_result_wire() {
         other => panic!("trainer buy failed, got {}", other.name()),
     }
 
-    // Wire enum values pinned so a future edit can't drift them (vmangos Player.h:119-122,
-    // SharedDefines.h:1120-1122).
+    // vmangos values (`Player.h:119-122`, `SharedDefines.h:1120-1122`).
     assert_eq!(
         (
             trainer_spell_state::GREEN,
@@ -204,14 +188,12 @@ fn trainer_buy_result_wire() {
 
 #[test]
 fn learned_and_superceded_spell_wire() {
-    // SMSG_LEARNED_SPELL (vmangos LearnedSpell::AppendBodyTo, Spell.cpp:175-179): u16 spellId, u16
-    // actionBarSlot. The slot is unused on the client and dropped — a nonzero slot here must not leak
-    // into spell_id (proving it's read as two u16s, not one u32).
+    // SMSG_LEARNED_SPELL: u16 spellId + u16 actionBarSlot, the slot unused by the client and
+    // dropped (vmangos `Spell.cpp:175-179`).
     match messages::parse_server(messages::opcode::SMSG_LEARNED_SPELL, &hx("cb19aaaa")).unwrap() {
         ServerPacket::LearnedSpell { spell_id } => assert_eq!(spell_id, 6603),
         other => panic!("learned spell, got {}", other.name()),
     }
-    // The bridge widens the wire u16 to the store's u32 (phase 2).
     let packet =
         messages::parse_server(messages::opcode::SMSG_LEARNED_SPELL, &hx("cb19aaaa")).unwrap();
     match decode(packet).pop().unwrap() {
@@ -219,8 +201,7 @@ fn learned_and_superceded_spell_wire() {
         other => panic!("spell learned event, got {other:?}"),
     }
 
-    // SMSG_SUPERCEDED_SPELL (vmangos SupercededSpell::AppendBodyTo, Spell.cpp:169-173): u16 oldSpellId,
-    // u16 newSpellId.
+    // SMSG_SUPERCEDED_SPELL: u16 oldSpellId + u16 newSpellId (vmangos `Spell.cpp:169-173`).
     match messages::parse_server(messages::opcode::SMSG_SUPERCEDED_SPELL, &hx("cb19cc19")).unwrap()
     {
         ServerPacket::SupercededSpell {
diff --git a/crates/benilla-protocol/tests/update_object.rs b/crates/benilla-protocol/tests/update_object.rs
index 5361a3f5..1d770b17 100644
--- a/crates/benilla-protocol/tests/update_object.rs
+++ b/crates/benilla-protocol/tests/update_object.rs
@@ -1,8 +1,4 @@
-//! `SMSG_UPDATE_OBJECT` / `SMSG_DESTROY_OBJECT` wire tests (mirrors `src/messages/update_object.rs`):
-//! object creates (unit/gameobject/item/container), out-of-range removal, destroy, and the sparse
-//! `ObjectFields` Values-update decode (unit state/power/customization, virtual items + sheath,
-//! inventory slots). Split out of the former `tests/messages.rs` — see `tests/common` for the shared
-//! fixtures and methodology note.
+//! `SMSG_UPDATE_OBJECT` and `SMSG_DESTROY_OBJECT` wire tests (`src/messages/update_object.rs`).
 
 mod common;
 
@@ -13,9 +9,7 @@ use common::hx;
 
 #[test]
 fn update_object_fixture_decodes() {
-    // A real serialized SMSG_UPDATE_OBJECT body: Unit create (guid 0xAA, displayid 50, scale 1.5, a
-    // living position) + GameObject create (guid 0xBB, displayid 99, scale 2.0, pos 100/200/300) +
-    // out-of-range [0x10, 0x20].
+    // A unit create (0xAA), a gameobject create (0xBB) and an out-of-range block [0x10, 0x20].
     let body = hx("03000000000301aa03200000000000000000cdd70bc6357e04c3f90fa74200000040000000000000803f0000e040000090400000000000000000db0f4940051700000000000000000000000000000008000000aa00000000000000090000000000c03f320000000301bb05000117810700bb000000000000002100000000000040630000000000c84200004843000096430000803f040200000001100120");
     let packet = messages::parse_server(messages::opcode::SMSG_UPDATE_OBJECT, &body).unwrap();
     let events = decode(packet);
@@ -74,9 +68,7 @@ fn update_object_fixture_decodes() {
 
 #[test]
 fn destroy_object_decodes_to_object_destroyed() {
-    // SMSG_DESTROY_OBJECT: a plain u64 guid (vmangos `DestroyObject::AppendBodyTo` streams the raw
-    // ObjectGuid) — the corpse-decay / despawn teardown. Its own event, distinct from the OutOfRange
-    // update block: destroyed objects pop instantly, out-of-range ones fade.
+    // SMSG_DESTROY_OBJECT: a raw u64 guid (vmangos `DestroyObject::AppendBodyTo`).
     let body = hx("efbeadde01000000");
     let packet = messages::parse_server(messages::opcode::SMSG_DESTROY_OBJECT, &body).unwrap();
     assert_eq!(packet.name(), "SMSG_DESTROY_OBJECT");
@@ -92,10 +84,8 @@ fn destroy_object_decodes_to_object_destroyed() {
 
 #[test]
 fn values_update_decodes_unit_state() {
-    // A hand-built Values-only update (update_type 0) for guid 0xAA carrying the unit descriptor
-    // fields HEALTH=22 (=100), MAXHEALTH=28 (=120), LEVEL=34 (=5), BYTES_0=36 (race 1/class 1/gender 0)
-    // — bits in 2 mask blocks, values in ascending field order. Verifies the `Object::Values` path
-    // (previously dropped) emits an ObjectValues delta whose fields decode via the named accessors.
+    // Values update for 0xAA: fields 22 HEALTH 100, 28 MAXHEALTH 120, 34 LEVEL 5 and 36 BYTES_0
+    // (race 1, class 1, gender 0), in 2 mask blocks with values in ascending field order.
     let body = hx("01000000000001aa02000040101400000064000000780000000500000001010001");
     let packet = messages::parse_server(messages::opcode::SMSG_UPDATE_OBJECT, &body).unwrap();
     let fields = decode(packet)
@@ -116,17 +106,14 @@ fn values_update_decodes_unit_state() {
         ),
         (Some(100), Some(120), Some(5), Some(1), Some(1), Some(0))
     );
-    // A non-player unit carries no PLAYER block, so the customization accessors stay `None`.
     assert_eq!(fields.player_skin(), None);
     assert_eq!(fields.player_facial_hair(), None);
 }
 
 #[test]
 fn values_update_decodes_player_customization() {
-    // A Values-only update for player guid 0xBB carrying PLAYER_BYTES=193 (skin 0x10 / face 0x11 /
-    // hairStyle 0x12 / hairColor 0x13, packed b0..b3) and PLAYER_BYTES_2=194 (facialHair 0x14, b0).
-    // Field 193 lives in mask block 6 (bit 1), 194 in block 6 (bit 2) → 7 blocks, the first six empty.
-    // Pins the RF-0056 field indices + byte order against the decode.
+    // Player 0xBB: PLAYER_BYTES (193) = skin, face, hairStyle, hairColor in b0..b3; PLAYER_BYTES_2
+    // (194) b0 = facialHair. Both sit in mask block 6 (bits 1, 2), after six empty blocks.
     let body = hx(
         "01000000000001bb07000000000000000000000000000000000000000000000000060000001011121314000000",
     );
@@ -152,9 +139,8 @@ fn values_update_decodes_player_customization() {
 
 #[test]
 fn values_update_decodes_unit_power() {
-    // A Values-only update for guid 0xAA carrying POWER1=23 (40), MAXPOWER1=29 (60), BYTES_0=36
-    // (race 1 / class 1 / gender 0 / power type 0 = mana). Pins the 1.12.1 power field indices
-    // (vmangos UpdateFields_1_12_1.h) + the bytes_0 power-type byte against the decode.
+    // Fields 23 POWER1 = 40, 29 MAXPOWER1 = 60, 36 BYTES_0 with power type 0 (mana) in b3 (vmangos
+    // `UpdateFields_1_12_1.h`).
     let body = hx("01000000000001aa020000802010000000280000003c00000001010000");
     let packet = messages::parse_server(messages::opcode::SMSG_UPDATE_OBJECT, &body).unwrap();
     let fields = decode(packet)
@@ -167,19 +153,15 @@ fn values_update_decodes_unit_power() {
     assert_eq!(fields.unit_power_type(), 0);
     assert_eq!(fields.unit_power(0), Some(40));
     assert_eq!(fields.unit_max_power(0), Some(60));
-    // Other slots are absent; out-of-range slots are None by contract.
     assert_eq!(fields.unit_power(1), None);
     assert_eq!(fields.unit_max_power(5), None);
 }
 
 #[test]
 fn values_update_decodes_unit_virtual_items_and_sheath() {
-    // A Values-only update for creature guid 0xCC carrying UNIT_VIRTUAL_ITEM_SLOT_DISPLAY slot 0
-    // (field 37) = 1234, UNIT_VIRTUAL_ITEM_INFO slot 0's pair (fields 40/41): dword0 packs
-    // class=2/subclass=7/material=1/invType=21, dword1 byte0 = sheath 3; and UNIT_FIELD_BYTES_2
-    // (field 164) byte0 = sheath state 1 (melee drawn). Field -> (block, bit): 37 -> (1,5),
-    // 40 -> (1,8), 41 -> (1,9), 164 -> (5,4) -- 6 mask blocks.
-    let mut body = hx("01000000000001cc06"); // count 1, no transport, VALUES, packed guid 0xCC, 6 blocks
+    // Fields 37 (virtual item display 0), 40/41 (its info pair, sheath 3 in 41's b0) and 164
+    // (UNIT_FIELD_BYTES_2, b0 = sheath state 1, melee drawn).
+    let mut body = hx("01000000000001cc06"); // count 1, no transport, VALUES, guid 0xCC, 6 blocks
     let mut masks = [0u32; 6];
     masks[1] = (1 << 5) | (1 << 8) | (1 << 9);
     masks[5] = 1 << 4;
@@ -219,12 +201,9 @@ fn values_update_decodes_unit_virtual_items_and_sheath() {
 
 #[test]
 fn values_update_decodes_inventory_slots() {
-    // A Values-only update for guid 1 carrying PLAYER_FIELD_INV_SLOT 16 (the offhand, fields
-    // 518/519 — live-verified: One's shield guid landed exactly there) = guid 0xAB and
-    // PLAYER_FIELD_PACK_SLOT 0 (fields 532/533, live-verified) = guid 0xCD. Pins the CORRECTED
-    // 1.12.1 bases (vmangos enum arithmetic, NOT its stale hex comments: INV_SLOT_HEAD 486,
-    // PACK 532). 17 mask blocks; block 16 = bits 6,7 (518,519) + 20,21 (532,533).
-    let mut body = hx("010000000000010111"); // count 1, no transport, VALUES, packed guid 1, 17 blocks
+    // INV_SLOT 16, the offhand (fields 518/519) = 0xAB; PACK_SLOT 0 (532/533) = 0xCD. The bases
+    // (INV_SLOT_HEAD 486, PACK 532) follow vmangos's enum arithmetic, not its stale hex comments.
+    let mut body = hx("010000000000010111"); // count 1, no transport, VALUES, guid 1, 17 blocks
     for block in 0..17u32 {
         let mask: u32 = if block == 16 { 0x0030_00C0 } else { 0 };
         body.extend_from_slice(&mask.to_le_bytes());
@@ -249,19 +228,15 @@ fn values_update_decodes_inventory_slots() {
 
 #[test]
 fn item_and_container_creates_decode() {
-    // Two position-less creates in one packet — an item and a bag — exactly as vmangos streams our
-    // inventory at login: CREATE_OBJECT, packed guid, TypeId 1/2, movement block = UPDATEFLAG_ALL
-    // (0x10) + its constant u32 1 (wire-verified `Object::BuildMovementUpdate`), then the mask.
-    // These used to be dropped whole by the create placement gate; now they're ItemCreate events.
-    // Container fields pin the CORRECTED bases (enum arithmetic, not the stale hex comments —
-    // the same 6-low drift as the PLAYER block): NUM_SLOTS = ITEM_END = 48, SLOT_1 = 50.
+    // Item and bag creates as vmangos streams them at login (movement block 0x10 + u32 1). Bases
+    // follow vmangos's enum arithmetic, not its stale hex comments: NUM_SLOTS 48, SLOT_1 50.
     let mut body = hx("0200000000");
     // Item guid 0x42, entry 4660 (field 3), stack count 5 (field 14): 1 mask block, bits 3+14.
     body.extend_from_slice(&hx("0201420110010000000108400000"));
     body.extend_from_slice(&4660u32.to_le_bytes());
     body.extend_from_slice(&5u32.to_le_bytes());
     // Container guid 0x43, entry 828 (field 3), num-slots 6 (field 48), slot-0 guid 0x42
-    // (fields 50/51): 2 mask blocks — block0 bit 3, block1 bits 16/18/19.
+    // (fields 50/51): 2 mask blocks, block0 bit 3, block1 bits 16/18/19.
     body.extend_from_slice(&hx("020143021001000000020800000000000d00"));
     for v in [828u32, 6, 0x42, 0] {
         body.extend_from_slice(&v.to_le_bytes());
@@ -295,17 +270,12 @@ fn item_and_container_creates_decode() {
     }
 }
 
-/// A transport GameObject's create (decision 0438 "the wire"): `UPDATE_FLAG_HAS_POSITION` (0x40) +
-/// `UPDATE_FLAG_TRANSPORT` (0x02), the latter's tail being the server's pathProgress ms anchor
-/// (vmangos `Object.cpp:590-605`). The mask carries `GAMEOBJECT_DISPLAYID` only — **no**
-/// `GAMEOBJECT_POS_*` fields, exactly what vmangos sends for a boat/zeppelin (it puts the stationary
-/// spawn point in the movement block's `HAS_POSITION` slot instead) — pinning both the new
-/// `transport_progress` surfacing AND the create-placement fallback to the movement block's position
-/// (`create_placement`, `events/decode.rs`) in one fixture.
+/// A boat's create: `HAS_POSITION` (0x40) + `TRANSPORT` (0x02), whose u32 tail is pathProgress ms
+/// (vmangos `Object.cpp:590-605`); vmangos sends no `GAMEOBJECT_POS_*`, only the movement pose.
 #[test]
 fn gameobject_create_surfaces_transport_progress_and_position_fallback() {
-    // HIGH_MO_TRANSPORT (0x1FC0) with the Menethil-Theramore ferry's real template entry (176495)
-    // riding the full low 32 bits (guid.rs `entry()` — MO_TRANSPORT has no 24-bit entry slot).
+    // HIGH_MO_TRANSPORT (0x1FC0) guids hold the entry in the full low 32 bits; 176495 is the
+    // Grom'Gol-Undercity zeppelin.
     let guid: u64 = 176_495 | (0x1FC0u64 << 48);
 
     let mut body = 1u32.to_le_bytes().to_vec(); // amount_of_objects
@@ -314,13 +284,12 @@ fn gameobject_create_surfaces_transport_progress_and_position_fallback() {
     write_packed_guid(guid, &mut body).unwrap();
     body.push(5); // TypeId::GameObject
 
-    // Movement block: HAS_POSITION | TRANSPORT.
     body.push(0x40 | 0x02);
     body.extend_from_slice(&5000.0f32.to_le_bytes()); // stationary pos.x
     body.extend_from_slice(&6000.0f32.to_le_bytes()); // stationary pos.y
     body.extend_from_slice(&15.0f32.to_le_bytes()); // stationary pos.z
     body.extend_from_slice(&2.0f32.to_le_bytes()); // orientation
-    body.extend_from_slice(&123_456u32.to_le_bytes()); // UPDATE_FLAG_TRANSPORT tail: pathProgress ms
+    body.extend_from_slice(&123_456u32.to_le_bytes()); // TRANSPORT tail: pathProgress ms
 
     // Mask: 1 block, GAMEOBJECT_DISPLAYID (field 8) only.
     body.push(1);
@@ -368,15 +337,11 @@ fn gameobject_create_surfaces_transport_progress_and_position_fallback() {
     }
 }
 
-/// A unit's `LIVING` block with `MOVEFLAG_ON_TRANSPORT` (0x0200_0000): the rider pose tail
-/// `[u64 transport guid][local x,y,z][local o]` (`update_object/movement.rs`'s `MovementBlock::read`,
-/// mirroring `read_movement_info`'s relay parse). VERIFIES the tail lands in `ObjectCreate::transport`
-/// and the 6 movement speeds that follow still parse from the right offset (the alignment the old
-/// discard-to-stay-aligned code depended on, now proven by consuming the values instead of dropping
-/// them).
+/// `MOVEFLAG_ON_TRANSPORT` (0x0200_0000) adds a rider tail to the `LIVING` block: u64 transport
+/// guid, then local x, y, z and orientation.
 #[test]
 fn unit_living_block_surfaces_on_transport_rider_pose() {
-    // The Org-UC zeppelin's template entry (176244), same MO_TRANSPORT composition as the ferry above.
+    // 176244 is the Moonspray, the Auberdine-Rut'theran boat.
     let transport_guid: u64 = 176_244 | (0x1FC0u64 << 48);
 
     let mut body = 1u32.to_le_bytes().to_vec();
@@ -389,18 +354,18 @@ fn unit_living_block_surfaces_on_transport_rider_pose() {
     let flags: u32 = 0x0200_0000; // MOVEFLAG_ON_TRANSPORT (1.12 bit 25, vmangos MovementInfo.h)
     body.extend_from_slice(&flags.to_le_bytes());
     body.extend_from_slice(&0u32.to_le_bytes()); // timestamp
-    body.extend_from_slice(&100.0f32.to_le_bytes()); // living pos.x (world, NOT local)
+    body.extend_from_slice(&100.0f32.to_le_bytes()); // living pos.x (world, not local)
     body.extend_from_slice(&200.0f32.to_le_bytes()); // living pos.y
     body.extend_from_slice(&5.0f32.to_le_bytes()); // living pos.z
     body.extend_from_slice(&1.0f32.to_le_bytes()); // living orientation
-    body.extend_from_slice(&transport_guid.to_le_bytes()); // ON_TRANSPORT tail: FULL u64 guid
+    body.extend_from_slice(&transport_guid.to_le_bytes()); // ON_TRANSPORT tail: full u64 guid
     body.extend_from_slice(&2.0f32.to_le_bytes()); // local x
     body.extend_from_slice(&3.0f32.to_le_bytes()); // local y
     body.extend_from_slice(&0.5f32.to_le_bytes()); // local z
     body.extend_from_slice(&0.25f32.to_le_bytes()); // local o
-    body.extend_from_slice(&0.0f32.to_le_bytes()); // fall_time (not swimming/jumping, no other tails)
+    body.extend_from_slice(&0.0f32.to_le_bytes()); // fall_time (no swim or jump tails)
     for v in [2.5f32, 7.0, 4.5, 4.722_222_3, 2.5, std::f32::consts::PI] {
-        body.extend_from_slice(&v.to_le_bytes()); // the 6 speeds — must still land right after the tail
+        body.extend_from_slice(&v.to_le_bytes()); // the 6 speeds, right after the tail
     }
 
     body.push(0); // mask: 0 blocks (nothing to interpret beyond the pose)
@@ -447,17 +412,8 @@ fn unit_living_block_surfaces_on_transport_rider_pose() {
     }
 }
 
-/// A player who streams in **already swimming**: the `LIVING` block's `MOVEFLAG_SWIMMING` word and
-/// the swim-pitch float that rides it both reach [`SessionEvent::ObjectCreate::mover`], and the six
-/// speeds after the tail still parse from the right offset.
-///
-/// This is the byte the client threw away for as long as observed swimming has existed
-/// (`let _pitch = read_f32_le(r)?;`). Its cost was the whole body-pitch render law being
-/// unreachable at create: the app's only source of a mover's flags + pitch was a relayed
-/// `MSG_MOVE_*`, so a player who swam into view rendered LEVEL until their next packet — and an
-/// idle floater, who sends none while unmoving, stayed level for as long as they floated. The
-/// reference re-authors `CMovement`'s live flags word from this same block (wow-5875-re
-/// `system/collision/collision.md`, the create-block apply's `0x75a07dff` merge).
+/// A swimming create's flags word and swim pitch both reach [`SessionEvent::ObjectCreate::mover`];
+/// the reference re-authors the mover's live flags from this block (the `0x75a07dff` merge).
 #[test]
 fn unit_living_block_surfaces_the_swim_it_is_already_in() {
     let mut body = 1u32.to_le_bytes().to_vec();
@@ -474,11 +430,10 @@ fn unit_living_block_surfaces_the_swim_it_is_already_in() {
     body.extend_from_slice(&(-566.0f32).to_le_bytes()); // living pos.y
     body.extend_from_slice(&(-3.25f32).to_le_bytes()); // living pos.z (under the surface)
     body.extend_from_slice(&2.0f32.to_le_bytes()); // living orientation
-                                                   // The SWIMMING tail: one f32, no ON_TRANSPORT pose before it, `fall_time` right after.
-    body.extend_from_slice(&(-0.4f32).to_le_bytes()); // swim pitch — nose DOWN
+    body.extend_from_slice(&(-0.4f32).to_le_bytes()); // the SWIMMING tail: pitch, nose down
     body.extend_from_slice(&0.0f32.to_le_bytes()); // fall_time
     for v in [2.5f32, 7.0, 4.5, 4.722_222_3, 2.5, std::f32::consts::PI] {
-        body.extend_from_slice(&v.to_le_bytes()); // the 6 speeds — must land right after the tail
+        body.extend_from_slice(&v.to_le_bytes()); // the 6 speeds, right after the tail
     }
 
     body.push(0); // mask: 0 blocks
@@ -509,10 +464,7 @@ fn unit_living_block_surfaces_the_swim_it_is_already_in() {
     }
 }
 
-/// A **dry** create carries no pitch tail at all — the four bytes are absent, so a parse that read
-/// one unconditionally would swallow `fall_time` and misalign every speed after it. The mover state
-/// still surfaces (the flags word is not conditional); its pitch is a level `0.0`, which is what the
-/// render law's own SWIMMING gate then reads.
+/// Without SWIMMING there is no pitch tail; the mover still surfaces, with a level 0.0 pitch.
 #[test]
 fn a_dry_living_block_has_no_pitch_tail_and_reads_level() {
     let mut body = 1u32.to_le_bytes().to_vec();
@@ -528,7 +480,7 @@ fn a_dry_living_block_has_no_pitch_tail_and_reads_level() {
     for v in [10.0f32, 20.0, 30.0, 0.5] {
         body.extend_from_slice(&v.to_le_bytes()); // pos + orientation
     }
-    body.extend_from_slice(&0.0f32.to_le_bytes()); // fall_time — NO pitch tail before it
+    body.extend_from_slice(&0.0f32.to_le_bytes()); // fall_time, no pitch tail before it
     for v in [2.5f32, 7.0, 4.5, 4.722_222_3, 2.5, std::f32::consts::PI] {
         body.extend_from_slice(&v.to_le_bytes());
     }
@@ -552,22 +504,11 @@ fn a_dry_living_block_has_no_pitch_tail_and_reads_level() {
     }
 }
 
-/// A unit that is **already walking** when it streams in: the `LIVING` block's
-/// `MOVEFLAG_SPLINE_ENABLED` (0x0040_0000) tail, byte-shaped exactly as vmangos writes it
-/// (`PacketBuilder::WriteCreate`, `packet_builder.cpp:152`). Two things are verified, and both are
-/// what decision 0708 turns on:
-///
-/// 1. The node array is the server's **internal** control array — `[phantom, p₀…pₙ, tail]`, since
-///    vmangos builds even a linear spline through `InitCatmullRom` (`spline.cpp:52`) — so the decoded
-///    `path` must be that array with its two virtual points trimmed, not the raw nodes.
-/// 2. The descriptor mask *after* the spline still parses: a mis-sized spline read (a missed node, a
-///    forgotten final destination) silently shifts every field that follows, which is precisely how a
-///    parse-and-discard block hides its own bugs.
+/// `MOVEFLAG_SPLINE_ENABLED` (0x0040_0000) adds a spline tail (vmangos `packet_builder.cpp:152`).
+/// Its nodes are the internal control array `[phantom, p₀…pₙ, tail]`, since vmangos builds even a
+/// linear spline through `InitCatmullRom` (`spline.cpp:52`); the decoded path drops the two ends.
 #[test]
 fn unit_living_block_surfaces_the_walk_it_is_already_on() {
-    // The real path: an L, 10 yd east then 20 yd north. What the server actually serializes is that
-    // path wrapped in its two virtual points: a phantom head at `p₀.lerp(p₁, -1)` = 2p₀ − p₁ (one
-    // segment *behind* the start) and a tail duplicating the destination.
     let path = [
         [10.0f32, 20.0, 30.0],
         [20.0, 20.0, 30.0],
@@ -591,10 +532,8 @@ fn unit_living_block_surfaces_the_walk_it_is_already_on() {
     let flags: u32 = 0x0040_0000; // MOVEFLAG_SPLINE_ENABLED (vmangos MovementInfo.h:53)
     body.extend_from_slice(&flags.to_le_bytes());
     body.extend_from_slice(&0u32.to_le_bytes()); // timestamp
-                                                 // The unit's stored pose — vmangos re-syncs it to the spline only every 400 ms, so it trails the
-                                                 // true position; the spline below is what actually places the unit.
     for v in [14.0f32, 20.0, 30.0, 0.0] {
-        body.extend_from_slice(&v.to_le_bytes()); // living pos + orientation
+        body.extend_from_slice(&v.to_le_bytes()); // stored pose, synced to the spline every 400 ms
     }
     body.extend_from_slice(&0.0f32.to_le_bytes()); // fall_time
     for v in [2.5f32, 7.0, 4.5, 4.722_222_3, 2.5, std::f32::consts::PI] {
@@ -658,8 +597,6 @@ fn unit_living_block_surfaces_the_walk_it_is_already_on() {
     }
 }
 
-/// A unit standing still carries no spline tail at all — the flag gates it, so `spline` is `None` and
-/// nothing downstream tries to walk it.
 #[test]
 fn unit_living_block_without_the_spline_flag_carries_no_walk() {
     let mut body = 1u32.to_le_bytes().to_vec();
@@ -686,15 +623,8 @@ fn unit_living_block_without_the_spline_flag_carries_no_walk() {
     }
 }
 
-/// `PLAYER_VISIBLE_ITEM_<n>_0` across the slot range — the PUBLIC entry the inspect window's whole
-/// paper doll is built from (decision 0631) and the same field equipment rendering resolves other
-/// players' gear through. Untested until now, and an off-by-one in its `258 + 2 + 12i` stride would
-/// put an inspected player's rings on their feet: the stride is exercised at both ends and in the
-/// middle, not just at slot 0 (which any wrong-but-anchored formula would also get right).
-///
-/// Field index = `PLAYER_VISIBLE_ITEM_1_CREATOR` (258, a 2-field guid) + 2 + 12·slot, so
-/// slot 0 → 260 (block 8 bit 4), slot 1 → 272 (block 8 bit 16), slot 14 → 428 (block 13 bit 12),
-/// slot 18 → 476 (block 14 bit 28). 15 mask blocks cover it.
+/// `PLAYER_VISIBLE_ITEM_<n>_0`, the public entry other players' gear renders from, sits at field
+/// 258 (`PLAYER_VISIBLE_ITEM_1_CREATOR`, a 2-field guid) + 2 + 12·slot: 260, 272, 428, 476 here.
 #[test]
 fn values_update_decodes_player_visible_item_entries() {
     let mut body: Vec<u8> = Vec::new();
@@ -710,7 +640,6 @@ fn values_update_decodes_player_visible_item_entries() {
     for m in masks {
         body.extend_from_slice(&m.to_le_bytes());
     }
-    // Ascending field order: 260, 272, 428, 476.
     for v in [7365u32, 2196u32, 15406u32, 2504u32] {
         body.extend_from_slice(&v.to_le_bytes());
     }
@@ -727,8 +656,7 @@ fn values_update_decodes_player_visible_item_entries() {
     assert_eq!(fields.player_visible_item_entry(1), Some(2196), "NECK");
     assert_eq!(fields.player_visible_item_entry(14), Some(15406), "BACK");
     assert_eq!(fields.player_visible_item_entry(18), Some(2504), "TABARD");
-    // An unsent slot and the sentinel are both None — an empty equipment slot must not read as
-    // "item 0" (the feed keys "is there gear here" on exactly this).
+    // An unsent slot and an out-of-range one both read None, never item 0.
     assert_eq!(fields.player_visible_item_entry(2), None, "slot 2 unsent");
     assert_eq!(
         fields.player_visible_item_entry(19),
diff --git a/crates/benilla-srp/Cargo.toml b/crates/benilla-srp/Cargo.toml
index c9e9c663..5ce8f2b1 100644
--- a/crates/benilla-srp/Cargo.toml
+++ b/crates/benilla-srp/Cargo.toml
@@ -3,7 +3,7 @@ name = "benilla-srp"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "WoW 1.12.1 (build 5875) SRP6 client + vanilla world-header crypto — in-repo, decision 0021"
+description = "WoW 1.12.1 (build 5875) SRP6 client and world-header crypto"
 
 [lints]
 workspace = true
diff --git a/crates/benilla-srp/examples/provision_probe.rs b/crates/benilla-srp/examples/provision_probe.rs
index d22587a4..9f7e7424 100644
--- a/crates/benilla-srp/examples/provision_probe.rs
+++ b/crates/benilla-srp/examples/provision_probe.rs
@@ -1,18 +1,13 @@
-//! Provision a slot-keyed probe account for the local vmangos `realmd` DB (decision 0450: a
-//! session in `pool-N` probes as `probeN`/`pprobeN`/`Probe<N-spelled>`). Growing the worktree
-//! pool means provisioning the matching account first; this is that recipe as one command
-//! (decision 0530 — the pool once grew without it, leaving a slot with no working identity).
+//! Provision a probe account (`probeN`, password `pprobeN`, character `Probe<N spelled>`) in the
+//! local vmangos `realmd` DB, one per checkout that runs probes. It touches no DB: it prints the
+//! SQL and the character-create line to run.
 //!
-//! No DB access here — it prints the SQL and the char-create probe line; run those yourself.
-//!
-//! Validate the stored-hex convention against an existing row first (0450's discipline):
+//! Check the hex convention against an existing row first, then emit the new slot's row:
 //!   cargo run -p benilla-srp --example provision_probe -- check <USER> <PASS> <s-hex> <v-hex>
-//! then emit the new slot's row:
 //!   cargo run -p benilla-srp --example provision_probe -- emit <N>
 //!
-//! Hex convention (validated against PROBE0's stored row, matching vmangos `BigNumber`): the DB
-//! stores `v`/`s` as big-endian hex of the number; the salt bytes fed to SHA1 are that number's
-//! little-endian bytes.
+//! The DB stores `v` and `s` as the big-endian hex of the number, as vmangos `BigNumber` writes it;
+//! SRP hashes the salt as that number's little-endian bytes.
 
 use benilla_srp::{generate_account, password_verifier, NormalizedString};
 
diff --git a/crates/benilla-srp/src/lib.rs b/crates/benilla-srp/src/lib.rs
index 49127923..094d83fa 100644
--- a/crates/benilla-srp/src/lib.rs
+++ b/crates/benilla-srp/src/lib.rs
@@ -1,40 +1,19 @@
-//! SRP6 client + vanilla world-header crypto for **WoW 1.12.1 (build 5875)** — in-repo, replacing
-//! `wow_srp` (decision 0021).
-//!
-//! WoW uses a lightly customised SRP6 for logon: a fixed 32-byte safe prime `N`, generator `g = 7`,
-//! multiplier `k = 3`, and a bespoke "interleave" that folds the shared secret `S` into the 40-byte
-//! session key. We implement only the **client** side (the realmd handshake) plus the world server's
-//! header obfuscation — the only pieces benilla needs.
-//!
-//! All byte arrays are **little endian** on the wire (as the client sends them).
-//!
-//! Proven by a full SRP6 round-trip against `wow_srp`'s server + a byte-exact header-cipher diff
-//! during the decision-0021 migration (oracle test in git history); ongoing regression coverage is
-//! the oracle-free known-answer + golden tests in this crate.
+//! SRP6 client and world-header crypto for 1.12.1 (build 5875): the client side of the realmd
+//! handshake and the world server's header obfuscation. Every byte array is little endian, as on
+//! the wire.
 //!
 //! # Encoding-unambiguous handshakes
 //!
-//! The values the handshake feeds to SHA-1 (`A`, `B`, `K`, the salt, `M1`) are *numbers*, and the two
-//! implementations in the wild serialize a number differently:
+//! The 1.12.1 client hashes `A`, `B`, `K`, the salt and `M1` at their declared widths, zero-padded
+//! (`0x5d3650`); vmangos (`SHA1::Generator::UpdateData(BigNumber const&)`) and cmangos
+//! (`Sha1Hash::UpdateBigNumbers`) drop high-order zero bytes, so a value with one hashes
+//! differently and realmd answers `WOW_FAIL_UNKNOWN_ACCOUNT` (0x04) to a correct password. The low
+//! end of `S` has the same split ([`calculate_interleaved`]).
 //!
-//! - The **1.12.1 client** writes each at its declared width, zero-padded in the high bytes — `A`/`B`
-//!   32, `K` 40, `M1` 20 (`wow-5875-re` `srp6_client_session`, byte-exact from `WoW.exe` `0x5d3650`).
-//! - The **mangos family** (vmangos `SHA1::Generator::UpdateData(BigNumber const&)`, cmangos
-//!   `Sha1Hash::UpdateBigNumbers`) writes `BigNumber::AsByteArray()` with no minimum — **high-order
-//!   zero bytes dropped**.
-//!
-//! They agree only while no value happens to have a high-order zero byte, and disagree silently when
-//! one does: realmd answers `WOW_FAIL_UNKNOWN_ACCOUNT` (0x04) to a perfectly correct password. There
-//! is a matching disagreement at the other end of `S` (see [`calculate_interleaved`]). Measured
-//! against a live vmangos, a client that picks a side loses ~1 handshake in 45 — see
-//! `benilla-protocol`'s `srp_encoding_probe` example, which forces each case and prints the verdict.
-//!
-//! benilla picks **neither side**. `a` is ours to draw, and every ambiguous value is downstream of
-//! it, so [`SrpClientChallenge::new`] simply redraws until the handshake it is about to send is one
-//! both conventions serialize identically — see [`is_width_stable`]. What we send is then bit-for-bit
-//! the real client's arithmetic *and* accepted by a mangos-family server, with no branch on which
-//! kind of server we are talking to. The one value we cannot draw is the server's `B`; `benilla-
-//! protocol`'s `logon` redials for a fresh challenge when that one lands ambiguous.
+//! Deviation: [`SrpClientChallenge::new`] redraws `a` until every value it sends serializes the
+//! same both ways ([`is_width_stable`]), and `benilla-protocol`'s `logon` redials when the server's
+//! `B` lands ambiguous, because a client that picks either serialization fails about 1 handshake
+//! in 45 against vmangos. The arithmetic stays the client's; only an ambiguous draw is declined.
 
 use num_bigint::BigInt;
 use rand::{thread_rng, RngCore};
@@ -44,25 +23,24 @@ pub mod vanilla_header;
 
 pub use vanilla_header::{DecrypterHalf, EncrypterHalf, HeaderCrypto, ProofSeed};
 
-/// Session-key length in bytes — always 40 (two concatenated SHA-1 hashes).
+/// Session-key length in bytes: two interleaved SHA-1 digests.
 pub const SESSION_KEY_LENGTH: usize = 40;
-/// Proof (`M1`/`M2`) length in bytes — a SHA-1 hash.
+/// Proof (`M1`, `M2`) length in bytes: one SHA-1 digest.
 pub const PROOF_LENGTH: usize = 20;
 /// Public-key (`A`/`B`) length in bytes.
 pub const PUBLIC_KEY_LENGTH: usize = 32;
-/// Salt length in bytes.
 pub const SALT_LENGTH: usize = 32;
-/// Generator `g` — statically 7 for WoW.
+/// The generator `g`.
 pub const GENERATOR: u8 = 7;
-/// The WoW safe prime `N`, little endian (as sent in `CMD_AUTH_LOGON_CHALLENGE_Server`).
+/// The safe prime `N`, little endian, as `CMD_AUTH_LOGON_CHALLENGE_Server` sends it.
 pub const LARGE_SAFE_PRIME_LITTLE_ENDIAN: [u8; 32] = [
     0xb7, 0x9b, 0x3e, 0x2a, 0x87, 0x82, 0x3c, 0xab, 0x8f, 0x5e, 0xbf, 0xbf, 0x8e, 0xb1, 0x1, 0x8,
     0x53, 0x50, 0x6, 0x29, 0x8b, 0x5b, 0xad, 0xbd, 0x5b, 0x53, 0xe1, 0x89, 0x5e, 0x64, 0x4b, 0x89,
 ];
-/// The SRP multiplier `k` — statically 3 in this (pre-SRP6a) flavour.
+/// The SRP multiplier `k`, fixed at 3 (SRP6, not 6a).
 const K_VALUE: u8 = 3;
 
-// --- bigint helpers (little-endian, unsigned magnitude) -------------------------------------------
+// --- bigint helpers (little-endian, unsigned magnitude) ------------------------------------------
 
 fn from_le(bytes: &[u8]) -> BigInt {
     BigInt::from_bytes_le(num_bigint::Sign::Plus, bytes)
@@ -84,19 +62,16 @@ fn sha1(parts: &[&[u8]]) -> [u8; 20] {
     h.finalize().into()
 }
 
-/// Does this little-endian value hash the same whichever serialization the peer uses — its declared
-/// width (the 1.12.1 client) or its minimal length (the mangos family)? True exactly when the
-/// high-order byte is non-zero, since minimal encoding differs from padded only by dropping those.
-/// See the crate docs, "Encoding-unambiguous handshakes".
+/// Whether a little-endian value hashes the same at its declared width and at minimal length:
+/// exactly when its high-order byte is non-zero.
 fn is_width_stable(little_endian: &[u8]) -> bool {
     matches!(little_endian.last(), Some(&b) if b != 0)
 }
 
-// --- normalized string ----------------------------------------------------------------------------
+// --- normalized string ---------------------------------------------------------------------------
 
-/// A username/password normalised the way the 1.12 client does it: ASCII only (no control chars),
-/// uppercased, 1..=16 bytes. The SRP6 hashes are computed over this form, and the uppercased account
-/// name is what's sent on the wire.
+/// A username or password as the 1.12 client normalises it: ASCII without control characters,
+/// uppercased, 1..=16 bytes. SRP6 hashes this form, and the account name goes on the wire in it.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct NormalizedString {
     s: String,
@@ -122,7 +97,6 @@ impl std::fmt::Display for NormalizedStringError {
 impl std::error::Error for NormalizedStringError {}
 
 impl NormalizedString {
-    /// Validate + uppercase `s`. See [`NormalizedString`].
     pub fn new(s: impl AsRef<str>) -> Result<Self, NormalizedStringError> {
         let s = s.as_ref();
         if s.is_empty() || s.len() > 16 {
@@ -145,7 +119,7 @@ impl AsRef<str> for NormalizedString {
     }
 }
 
-// --- public key -----------------------------------------------------------------------------------
+// --- public key ----------------------------------------------------------------------------------
 
 /// A validated SRP public key (`A` or `B`), stored little endian. Rejected if it is exactly zero or
 /// exactly the safe prime `N` (the only 32-byte values that are `0 mod N`).
@@ -157,7 +131,6 @@ pub struct PublicKey {
 /// Error from [`PublicKey::from_le_bytes`].
 #[derive(Debug)]
 pub enum InvalidPublicKeyError {
-    /// The key is all zeros.
     IsZero,
     /// The key is `0 mod N` (equal to the safe prime).
     ModLargeSafePrimeIsZero,
@@ -174,10 +147,8 @@ impl std::fmt::Display for InvalidPublicKeyError {
 impl std::error::Error for InvalidPublicKeyError {}
 
 impl PublicKey {
-    /// Build from little-endian bytes, validating the key (see [`PublicKey`]).
     pub fn from_le_bytes(key: [u8; 32]) -> Result<Self, InvalidPublicKeyError> {
-        // Valid unless every byte is either 0 or matches N[i] — i.e. the key is exactly 0 or exactly
-        // N. (A multiple of N ≥ 2N needs 33 bytes, so those are the only two zero residues.)
+        // A byte-wise test for 0 and `N`, the only 32-byte multiples of `N` (`2N` needs 33 bytes).
         let only_zero_or_prime = key
             .iter()
             .zip(LARGE_SAFE_PRIME_LITTLE_ENDIAN.iter())
@@ -192,14 +163,12 @@ impl PublicKey {
         Ok(Self { key })
     }
 
-    /// The key as little-endian bytes.
     pub const fn as_le_bytes(&self) -> &[u8; 32] {
         &self.key
     }
 
-    /// Whether this key hashes identically under both serialization conventions (crate docs,
-    /// "Encoding-unambiguous handshakes"). [`SrpClientChallenge::new`] guarantees it for the `A` it
-    /// draws; for the server's `B` it is luck, and the caller's cue to redial for a fresh challenge.
+    /// Whether this key hashes the same under both conventions; for the server's `B`, false is the
+    /// cue to redial for a fresh challenge.
     pub const fn is_width_stable(&self) -> bool {
         self.key[31] != 0
     }
@@ -209,10 +178,9 @@ impl PublicKey {
     }
 }
 
-// --- SRP6 client ----------------------------------------------------------------------------------
+// --- SRP6 client ---------------------------------------------------------------------------------
 
-/// `H( SHA1(N) XOR SHA1(g) )` — folded into the client proof `M1`. Computed from the server-supplied
-/// `g`/`N` (they're fixed for WoW, but we don't assume it).
+/// `SHA1(N) XOR SHA1(g)`, the head of `M1`, from the `g` and `N` the server sent.
 fn xor_hash(generator: u8, large_safe_prime: &[u8; 32]) -> [u8; 20] {
     let n_hash = sha1(&[large_safe_prime]);
     let g_hash = sha1(&[&[generator]]);
@@ -245,20 +213,12 @@ fn calculate_u(client_public_key: &PublicKey, server_public_key: &PublicKey) ->
     ])
 }
 
-/// Fold the shared secret `S` (32 LE bytes) into the 40-byte session key: split the even / odd bytes,
-/// SHA-1 each half, then interleave the two digests. This is WoW's specific `SHA1_Interleave`.
+/// Fold `S` (32 LE bytes) into the 40-byte session key: SHA-1 the even and the odd bytes apart and
+/// interleave the two digests (WoW's `SHA1_Interleave`).
 ///
-/// This is the crate-doc encoding split again, at the *low* end of `S`. The SRP-6 RFC strips leading
-/// zero bytes before the split and the real client does too (`wow-5875-re` `srp6_interleave`, from
-/// `WoW.exe` `0x5d3360`, 406 cases bit-exact) — leading in its little-endian `S` meaning the **low**
-/// bytes. vmangos does not: it hashes all 32 unconditionally (`SRP6::HashSessionKey`,
-/// `S.AsByteArray(32)`). A trim would derive a different `K`, hence a different `M1`, for the
-/// ~1-in-256 `S` ending in a zero low byte — an intermittent `WOW_FAIL_UNKNOWN_ACCOUNT` (0x04) on a
-/// correct password.
-///
-/// We hash all 32 bytes, and [`SrpClientChallenge::new`] only keeps an `S` whose low byte is
-/// non-zero — which makes the strip a no-op, so this `K` is simultaneously the real client's and
-/// vmangos'. Neither convention is chosen; the ambiguous inputs are simply never presented.
+/// The client strips leading zero bytes first, the low bytes of a little-endian `S` (`0x5d3360`);
+/// vmangos hashes all 32 (`SRP6::HashSessionKey`, `S.AsByteArray(32)`). This hashes all 32, and
+/// [`SrpClientChallenge::new`] never keeps an `S` with a zero low byte, so this `K` is both.
 fn calculate_interleaved(s: &[u8; 32]) -> [u8; 40] {
     let mut e = [0u8; 16];
     for (i, b) in s.iter().step_by(2).enumerate() {
@@ -280,7 +240,7 @@ fn calculate_interleaved(s: &[u8; 32]) -> [u8; 40] {
     out
 }
 
-/// `M2 = SHA1( A | M1 | K )` — what the server proves back and we verify.
+/// `M2 = SHA1( A | M1 | K )`, the server's proof back.
 fn calculate_server_proof(
     client_public_key: &PublicKey,
     client_proof: &[u8; 20],
@@ -289,9 +249,8 @@ fn calculate_server_proof(
     sha1(&[client_public_key.as_le_bytes(), client_proof, session_key])
 }
 
-/// First step of the client logon: given the server's challenge values, computes our public key `A`,
-/// the proof `M1`, and the session key. Send `A` + `M1` in `CMD_AUTH_LOGON_PROOF_Client`, then call
-/// [`SrpClientChallenge::verify_server_proof`] with the server's `M2`.
+/// The client's side of the logon proof: `A` and `M1` go in `CMD_AUTH_LOGON_PROOF_Client`, and the
+/// server's `M2` is checked with [`SrpClientChallenge::verify_server_proof`].
 #[derive(Debug, Clone)]
 pub struct SrpClientChallenge {
     username: NormalizedString,
@@ -300,22 +259,17 @@ pub struct SrpClientChallenge {
     session_key: [u8; 40],
 }
 
-/// How many ephemerals [`SrpClientChallenge::new`] will draw looking for an encoding-unambiguous
-/// handshake. Each draw succeeds ~97.4% of the time, so the loop all but always ends on the first;
-/// the bound only exists so a degenerate `N`/`g` from a hostile server cannot spin forever. On
-/// exhaustion we send the last draw anyway — the same handshake we would have sent before this
-/// guarantee existed, i.e. it can fail the logon but cannot corrupt one.
+/// The cap on ephemerals [`SrpClientChallenge::new`] draws, so a hostile `N`/`g` cannot spin it
+/// forever. Each passes about 97.4% of the time; the last is sent regardless, which can fail the
+/// logon but never corrupt it.
 const MAX_EPHEMERAL_DRAWS: u32 = 512;
 
 impl SrpClientChallenge {
-    /// Compute `A`, `M1`, and the session key from the server challenge. Mirrors the real client:
-    /// random 32-byte private key `a`, `A = g^a mod N`, `S = (B - k·g^x)^(a + u·x) mod N`, session
-    /// key = interleave(S), `M1 = SHA1( H(N)^H(g) | SHA1(user) | salt | A | B | K )`.
-    ///
-    /// `a` is redrawn until every value the handshake serializes is one both conventions in the wild
-    /// encode identically (crate docs, "Encoding-unambiguous handshakes"): `A`, `K` and `M1` with no
-    /// high-order zero byte, and `S` with no low-order one. The arithmetic is untouched — this only
-    /// declines to *use* an ephemeral whose handshake would be read two ways.
+    /// Compute `A`, `M1` and the session key as the client does: a random 32-byte `a`,
+    /// `A = g^a mod N`, `S = (B - k·g^x)^(a + u·x) mod N`, `K = interleave(S)` and
+    /// `M1 = SHA1( H(N)^H(g) | SHA1(user) | salt | A | B | K )`. Deviation: `a` is redrawn until
+    /// `A`, `K` and `M1` have no high-order zero byte and `S` no low-order one, because the client
+    /// and vmangos hash those values differently.
     pub fn new(
         username: NormalizedString,
         password: NormalizedString,
@@ -323,12 +277,32 @@ impl SrpClientChallenge {
         large_safe_prime: [u8; 32],
         server_public_key: PublicKey,
         salt: [u8; 32],
+    ) -> SrpClientChallenge {
+        Self::new_with_rng(
+            &mut thread_rng(),
+            username,
+            password,
+            generator,
+            large_safe_prime,
+            server_public_key,
+            salt,
+        )
+    }
+
+    /// [`Self::new`] with the draw source injected, so a test can script a draw that trips a guard.
+    fn new_with_rng<R: RngCore>(
+        rng: &mut R,
+        username: NormalizedString,
+        password: NormalizedString,
+        generator: u8,
+        large_safe_prime: [u8; 32],
+        server_public_key: PublicKey,
+        salt: [u8; 32],
     ) -> SrpClientChallenge {
         let n = from_le(&large_safe_prime);
         let g = BigInt::from(generator);
         let k = BigInt::from(K_VALUE);
 
-        // Everything the draw does not move, hoisted out of the loop.
         let x = from_le(&calculate_x(&username, &password, &salt));
         let s_base = server_public_key.as_bigint() - &k * g.modpow(&x, &n);
         let xor = xor_hash(generator, &large_safe_prime);
@@ -338,10 +312,9 @@ impl SrpClientChallenge {
             let last = draw == MAX_EPHEMERAL_DRAWS;
 
             let mut private_key = [0u8; 32];
-            thread_rng().fill_bytes(&mut private_key);
+            rng.fill_bytes(&mut private_key);
             let a = from_le(&private_key);
 
-            // A = g^a mod N
             let client_public_key = to_padded_32_le(&g.modpow(&a, &n));
             if !is_width_stable(&client_public_key) && !last {
                 continue;
@@ -353,8 +326,7 @@ impl SrpClientChallenge {
 
             // S = (B - k·(g^x mod N))^(a + u·x) mod N
             let s = to_padded_32_le(&s_base.modpow(&(&a + &u * &x), &n));
-            // A zero low byte is the one the real client's interleave would strip (see
-            // `calculate_interleaved`) — decline it so our K is both implementations' K.
+            // The client's interleave strips a zero low byte: decline it, so `K` is both sides'.
             if s[0] == 0 && !last {
                 continue;
             }
@@ -364,7 +336,6 @@ impl SrpClientChallenge {
                 continue;
             }
 
-            // M1 = SHA1( xor_hash | SHA1(username) | salt | A | B | K )
             let client_proof = sha1(&[
                 &xor,
                 &username_hash,
@@ -373,8 +344,7 @@ impl SrpClientChallenge {
                 server_public_key.as_le_bytes(),
                 &session_key,
             ]);
-            // M1 is itself hashed back into the server's M2, so it needs the guarantee too — this is
-            // the case realmd *accepts* while the M2 it replies with fails our check.
+            // M1 feeds the server's M2: an ambiguous one passes realmd but fails our M2 check.
             if !is_width_stable(&client_proof) && !last {
                 continue;
             }
@@ -389,18 +359,17 @@ impl SrpClientChallenge {
         unreachable!("the final draw is accepted unconditionally")
     }
 
-    /// Our proof `M1` (little endian) — send in `CMD_AUTH_LOGON_PROOF_Client`.
+    /// Our proof `M1`, little endian.
     pub const fn client_proof(&self) -> &[u8; 20] {
         &self.client_proof
     }
 
-    /// Our public key `A` (little endian) — send in `CMD_AUTH_LOGON_PROOF_Client`.
+    /// Our public key `A`, little endian.
     pub const fn client_public_key(&self) -> &[u8; 32] {
         &self.client_public_key
     }
 
-    /// Verify the server's proof `M2`. On success the SRP handshake is complete and the session key
-    /// is held in the returned [`SrpClient`].
+    /// Verify the server's proof `M2`; the returned [`SrpClient`] holds the session key.
     pub fn verify_server_proof(
         self,
         server_proof: [u8; 20],
@@ -427,9 +396,7 @@ impl SrpClientChallenge {
 /// The server's proof `M2` did not match what we computed (usually a wrong password).
 #[derive(Debug)]
 pub struct MatchProofsError {
-    /// The proof the server sent.
     pub server_proof: [u8; 20],
-    /// The proof we expected.
     pub expected: [u8; 20],
 }
 impl std::fmt::Display for MatchProofsError {
@@ -454,11 +421,9 @@ impl SrpClient {
     }
 }
 
-// --- account creation (server-side verifier) ------------------------------------------------------
+// --- account creation (server-side verifier) -----------------------------------------------------
 
-/// The SRP6 **password verifier** `v = g^x mod N` (little endian) for a given salt — the value a
-/// server stores alongside the salt so it never holds the raw password. Deterministic in
-/// `(username, password, salt)`. See [`generate_account`] for the new-account path.
+/// The SRP6 password verifier `v = g^x mod N`, little endian: what a server stores beside the salt.
 pub fn password_verifier(
     username: &NormalizedString,
     password: &NormalizedString,
@@ -470,14 +435,9 @@ pub fn password_verifier(
     to_padded_32_le(&g.modpow(&x, &n))
 }
 
-/// Generate a fresh random salt and the matching [`password_verifier`] for a new account. Returns
-/// `(salt, verifier)`, both little endian.
-///
-/// The salt's top bit is forced, exactly as vmangos' own account creation does it
-/// (`BigNumber::SetRand(256)` → `BN_rand(_bn, 256, 0, 1)`, whose `top = 0` sets the MSB). The salt is
-/// the one hashed value fixed for the life of the account rather than redrawn per handshake, so a
-/// high-order zero byte there is not a 1-in-256 *login* failure but a permanently unloggable account
-/// (crate docs, "Encoding-unambiguous handshakes").
+/// A fresh random salt and its [`password_verifier`] for a new account, both little endian. The
+/// salt's top bit is set, as vmangos's `BigNumber::SetRand(256)` does (`BN_rand(_bn, 256, 0, 1)`):
+/// a salt lives as long as its account, so an ambiguous one would never log in.
 pub fn generate_account(
     username: &NormalizedString,
     password: &NormalizedString,
@@ -491,10 +451,8 @@ pub fn generate_account(
 
 #[cfg(test)]
 mod tests {
-    //! Oracle-free regression tests. The SRP6 *interleave* and `x` derivation are pinned to published
-    //! WoW SRP6 test vectors (the gtker/wow_srp corpus, MIT — the same values used to byte-validate
-    //! this crate against `wow_srp` during the decision-0021 migration). The header cipher + password
-    //! verifier are pinned to golden outputs captured from that validated implementation.
+    //! The interleave and `x` are pinned to the published WoW SRP6 vectors (the `wow_srp` crate's
+    //! MIT corpus); the header cipher and password verifier to goldens from that implementation.
     use super::*;
 
     fn hx(s: &str) -> Vec<u8> {
@@ -527,11 +485,6 @@ mod tests {
         }
     }
 
-    /// A low-order zero byte in `S` must *not* shorten the split: we hash all 32 bytes, so `S` and
-    /// `S` with its low byte zeroed differ only in that byte, never in length. (Trimming is the
-    /// SRP-6 RFC's — and the real client's — behaviour, and against vmangos it is what made ~1 login
-    /// in 256 come back as "wrong password"; `SrpClientChallenge::new` keeps the two identical by
-    /// never drawing an `S` with a zero low byte at all.)
     #[test]
     fn interleave_does_not_trim_low_order_zero_bytes() {
         let mut s = [0u8; 32];
@@ -542,8 +495,7 @@ mod tests {
         zeroed[0] = 0;
         zeroed[1] = 0;
 
-        // Even halves: byte 0 is the only difference; odd halves: byte 1. Both must change, and the
-        // trimming implementation would instead have re-split the remaining 30 bytes wholesale.
+        // The untrimmed split, built by hand; a trim would re-split the remaining 30 bytes.
         let mut expect_even = [0u8; 16];
         let mut expect_odd = [0u8; 16];
         for i in 0..16 {
@@ -564,8 +516,7 @@ mod tests {
 
     #[test]
     fn calculate_x_known_answer() {
-        // Fixed salt (big-endian in the corpus); user/pass → x (big-endian in the corpus). We store
-        // both little-endian, so reverse the corpus hex.
+        // The corpus writes the salt and `x` big-endian; we store both little-endian.
         let salt: [u8; 32] = rev(hx(
             "CAC94AF32D817BA64B13F18FDEDEF92AD4ED7EF7AB0E19E9F2AE13C828AEAF57",
         ))
@@ -600,21 +551,19 @@ mod tests {
         assert!(!is_width_stable(&[]));
     }
 
-    /// The crate's guarantee: every handshake we hand out is one both serialization conventions read
-    /// identically, so no value carries a high-order zero byte. `A` lands ambiguous ~1 draw in 137
-    /// and `K`/`M1` ~1 in 256 each, so over this many draws a regression that dropped any one guard
-    /// is caught with ~97% probability. (The live gate is `benilla-protocol`'s `srp_encoding_probe`,
-    /// which forces each case against a real realmd.)
     #[test]
     fn every_drawn_handshake_is_encoding_unambiguous() {
+        use rand::{rngs::StdRng, SeedableRng};
         let user = NormalizedString::new("alice").unwrap();
         let pass = NormalizedString::new("password1").unwrap();
+        let mut rng = StdRng::seed_from_u64(0x5875);
         for i in 0..128u32 {
             let mut b = [0u8; 32];
-            thread_rng().fill_bytes(&mut b);
+            rng.fill_bytes(&mut b);
             b[31] |= 0x80; // the shape of server key `logon` keeps
             let salt = std::array::from_fn(|j| (j as u8).wrapping_mul(11).wrapping_add(i as u8));
-            let c = SrpClientChallenge::new(
+            let c = SrpClientChallenge::new_with_rng(
+                &mut rng,
                 user.clone(),
                 pass.clone(),
                 GENERATOR,
@@ -635,8 +584,129 @@ mod tests {
         }
     }
 
-    /// A salt is fixed for the life of an account rather than redrawn per handshake, so an ambiguous
-    /// one is not a flaky login but an account that can never log in.
+    /// A draw source that hands out exactly the private keys it was given, in order.
+    struct Scripted(std::collections::VecDeque<[u8; 32]>);
+
+    impl RngCore for Scripted {
+        fn next_u32(&mut self) -> u32 {
+            unreachable!("the ephemeral is drawn with fill_bytes")
+        }
+        fn next_u64(&mut self) -> u64 {
+            unreachable!("the ephemeral is drawn with fill_bytes")
+        }
+        fn fill_bytes(&mut self, dest: &mut [u8]) {
+            let key = self
+                .0
+                .pop_front()
+                .expect("a scripted draw was left for this");
+            dest.copy_from_slice(&key);
+        }
+        fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), rand::Error> {
+            self.fill_bytes(dest);
+            Ok(())
+        }
+    }
+
+    /// The `B` (high bit set, as `logon` keeps) and salt the guard vectors were found against;
+    /// change either and the vectors mean nothing.
+    const FIXTURE_B: [u8; 32] = [
+        5, 42, 79, 116, 153, 190, 227, 8, 45, 82, 119, 156, 193, 230, 11, 48, 85, 122, 159, 196,
+        233, 14, 51, 88, 125, 162, 199, 236, 17, 54, 91, 128,
+    ];
+    const FIXTURE_SALT: [u8; 32] = [
+        3, 14, 25, 36, 47, 58, 69, 80, 91, 102, 113, 124, 135, 146, 157, 168, 179, 190, 201, 212,
+        223, 234, 245, 0, 11, 22, 33, 44, 55, 66, 77, 88,
+    ];
+    /// Private keys that each trip one guard against the fixture: `TRIPS_A` gives `A` a high-order
+    /// zero byte, `TRIPS_S` gives `S` a low-order one, `TRIPS_K` and `TRIPS_M1` give the key and
+    /// the proof a high-order one; `CLEAN` trips none.
+    const TRIPS_A: [u8; 32] = [
+        237, 250, 2, 239, 106, 197, 124, 117, 132, 5, 226, 189, 212, 217, 169, 146, 39, 212, 214,
+        11, 198, 57, 225, 84, 17, 219, 168, 107, 118, 105, 11, 95,
+    ];
+    const TRIPS_S: [u8; 32] = [
+        205, 28, 249, 67, 94, 223, 246, 194, 118, 47, 78, 155, 220, 133, 163, 151, 42, 72, 65, 90,
+        37, 9, 156, 83, 38, 132, 96, 6, 129, 245, 202, 203,
+    ];
+    const TRIPS_K: [u8; 32] = [
+        2, 176, 65, 251, 162, 142, 23, 37, 53, 25, 44, 220, 201, 39, 234, 48, 141, 207, 127, 19, 0,
+        93, 140, 154, 16, 181, 118, 225, 147, 237, 174, 28,
+    ];
+    const TRIPS_M1: [u8; 32] = [
+        143, 237, 243, 79, 25, 151, 163, 98, 11, 221, 191, 202, 69, 148, 140, 221, 123, 95, 152,
+        146, 230, 232, 181, 86, 18, 72, 78, 135, 95, 129, 234, 248,
+    ];
+    const CLEAN: [u8; 32] = [
+        52, 226, 21, 16, 93, 106, 129, 125, 56, 197, 129, 14, 149, 1, 254, 105, 63, 23, 9, 190, 46,
+        113, 240, 125, 128, 130, 150, 46, 174, 240, 93, 249,
+    ];
+
+    /// `A = g^a mod N` for a private key, as the constructor computes it.
+    fn public_key_of(private_key: &[u8; 32]) -> [u8; 32] {
+        let n = from_le(&LARGE_SAFE_PRIME_LITTLE_ENDIAN);
+        to_padded_32_le(&BigInt::from(GENERATOR).modpow(&from_le(private_key), &n))
+    }
+
+    /// Each guard gets a key known to trip it, then a clean one, and must return the clean draw.
+    #[test]
+    fn each_encoding_guard_rejects_the_draw_it_exists_for() {
+        let user = NormalizedString::new("alice").unwrap();
+        let pass = NormalizedString::new("password1").unwrap();
+        let server = PublicKey::from_le_bytes(FIXTURE_B).unwrap();
+        let clean_a = public_key_of(&CLEAN);
+
+        // The fixture still means what the vectors say: each trips its guard, CLEAN trips none.
+        assert!(
+            !is_width_stable(&public_key_of(&TRIPS_A)),
+            "TRIPS_A no longer trips A"
+        );
+        assert!(is_width_stable(&clean_a), "CLEAN no longer passes A");
+
+        for (guard, bad) in [
+            ("A", TRIPS_A),
+            ("S", TRIPS_S),
+            ("K", TRIPS_K),
+            ("M1", TRIPS_M1),
+        ] {
+            let mut rng = Scripted([bad, CLEAN].into_iter().collect());
+            let c = SrpClientChallenge::new_with_rng(
+                &mut rng,
+                user.clone(),
+                pass.clone(),
+                GENERATOR,
+                LARGE_SAFE_PRIME_LITTLE_ENDIAN,
+                server,
+                FIXTURE_SALT,
+            );
+            assert_eq!(
+                c.client_public_key(),
+                &clean_a,
+                "guard {guard}: the tripping draw was accepted instead of the clean one"
+            );
+            assert!(
+                rng.0.is_empty(),
+                "guard {guard}: the clean draw was never reached"
+            );
+            assert!(is_width_stable(c.client_public_key()));
+            assert!(is_width_stable(&c.session_key));
+            assert!(is_width_stable(c.client_proof()));
+        }
+
+        // And a draw that trips nothing is taken first time.
+        let mut rng = Scripted([CLEAN, TRIPS_A].into_iter().collect());
+        let c = SrpClientChallenge::new_with_rng(
+            &mut rng,
+            user,
+            pass,
+            GENERATOR,
+            LARGE_SAFE_PRIME_LITTLE_ENDIAN,
+            server,
+            FIXTURE_SALT,
+        );
+        assert_eq!(c.client_public_key(), &clean_a);
+        assert_eq!(rng.0.len(), 1, "a clean first draw is the handshake");
+    }
+
     #[test]
     fn generated_salts_are_encoding_unambiguous() {
         let user = NormalizedString::new("alice").unwrap();
diff --git a/crates/benilla-srp/src/vanilla_header.rs b/crates/benilla-srp/src/vanilla_header.rs
index fab74ffa..0613c206 100644
--- a/crates/benilla-srp/src/vanilla_header.rs
+++ b/crates/benilla-srp/src/vanilla_header.rs
@@ -1,24 +1,16 @@
-//! Vanilla (1.12) world-packet **header obfuscation**.
-//!
-//! After `CMSG_AUTH_SESSION`, every world-packet *header* (not the body) is run through a stateful
-//! byte cipher keyed by the SRP session key. It is not a real cipher — each byte is XORed with a
-//! rotating session-key byte and chained against the previous ciphertext byte:
+//! The 1.12 world-packet header obfuscation. After `CMSG_AUTH_SESSION` every header, not the body,
+//! runs through a byte cipher keyed by the 40-byte session key, `i` cycling over the key and
+//! `last_c` the previous ciphertext byte, both starting at 0:
 //!
 //! ```text
 //! encrypt: c = (p ^ key[i]) + last_c ;  decrypt: p = (c - last_c) ^ key[i]
 //! ```
 //!
-//! with `i` cycling over the 40-byte key and `last_c` the previous ciphertext byte (both start 0).
-//! Client headers are 6 bytes (a `u16` BE size and `u32` LE opcode); server headers are **always 4**
-//! (a `u16` BE size and `u16` LE opcode). There is no wider-size variant in 1.12: vmangos writes
-//! every outgoing header as `ServerPktHeader { uint16 size; uint16 cmd; }` (WorldSocket.cpp — a
-//! larger body is *truncated* into the u16, never given a wider field) and routes big object
-//! updates through `SMSG_COMPRESSED_UPDATE_OBJECT` instead. The 3-byte large-packet size is a
-//! later-expansion convention; nothing in this stack handles it, by design.
-//!
-//! The handshake: the server's `SMSG_AUTH_CHALLENGE` carries a random seed; the client picks its own
-//! seed (a [`ProofSeed`]), proves it knows the session key via
-//! [`ProofSeed::into_client_header_crypto`], and from then on encrypts/decrypts headers.
+//! Client headers are 6 bytes (`u16` BE size, `u32` LE opcode); server headers are always 4
+//! (`u16` BE size, `u16` LE opcode). vmangos writes every header as
+//! `ServerPktHeader { uint16 size; uint16 cmd; }`, truncating a larger size (`WorldSocket.cpp`),
+//! and sends big object updates as `SMSG_COMPRESSED_UPDATE_OBJECT`; the 3-byte large-packet size
+//! is a later expansion's.
 
 use std::io::{Read, Write};
 
@@ -48,7 +40,7 @@ fn world_server_proof(
     h.finalize().into()
 }
 
-/// Encryption half of the header cipher — kept with the write half of a split connection.
+/// The header cipher's encrypting half, for the write side of a split connection.
 #[derive(Debug, Clone)]
 pub struct EncrypterHalf {
     session_key: [u8; SESSION_KEY_LENGTH],
@@ -77,7 +69,6 @@ impl EncrypterHalf {
         header
     }
 
-    /// Write an encrypted client header to `w`.
     pub fn write_encrypted_client_header<W: Write>(
         &mut self,
         mut w: W,
@@ -89,7 +80,7 @@ impl EncrypterHalf {
     }
 }
 
-/// Decryption half of the header cipher — kept with the read half of a split connection.
+/// The header cipher's decrypting half, for the read side of a split connection.
 #[derive(Debug, Clone)]
 pub struct DecrypterHalf {
     session_key: [u8; SESSION_KEY_LENGTH],
@@ -110,8 +101,7 @@ impl DecrypterHalf {
         }
     }
 
-    /// Decrypt a 4-byte server header into `(size, opcode)`. (1.12 server headers are always 4
-    /// bytes — see the module doc; there is no wider-size variant to handle.)
+    /// Decrypt a 4-byte server header; 1.12 has no wider-size variant.
     pub fn decrypt_server_header(&mut self, mut data: [u8; SERVER_HEADER_LENGTH]) -> ServerHeader {
         self.decrypt(&mut data);
         ServerHeader {
@@ -120,7 +110,6 @@ impl DecrypterHalf {
         }
     }
 
-    /// Read + decrypt a 4-byte server header from `r`.
     pub fn read_and_decrypt_server_header<R: Read>(
         &mut self,
         mut r: R,
@@ -134,13 +123,12 @@ impl DecrypterHalf {
 /// A decrypted server-packet header.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ServerHeader {
-    /// Body size in bytes, *including* the opcode field but not the size field.
+    /// Body size in bytes, counting the opcode field but not the size field.
     pub size: u16,
-    /// Server opcode.
     pub opcode: u16,
 }
 
-/// Both halves of the header cipher. Split with [`Self::split`] for separate read/write paths.
+/// Both halves of the header cipher.
 #[derive(Debug, Clone)]
 pub struct HeaderCrypto {
     encrypt: EncrypterHalf,
@@ -148,26 +136,21 @@ pub struct HeaderCrypto {
 }
 
 impl HeaderCrypto {
-    /// Mutable access to the decryption half.
     pub fn decrypter(&mut self) -> &mut DecrypterHalf {
         &mut self.decrypt
     }
 
-    /// Mutable access to the encryption half.
     pub fn encrypter(&mut self) -> &mut EncrypterHalf {
         &mut self.encrypt
     }
 
-    /// Split into independent encrypt / decrypt halves (one per direction of a split socket).
+    /// Split into halves, one per direction of a split socket.
     pub fn split(self) -> (EncrypterHalf, DecrypterHalf) {
         (self.encrypt, self.decrypt)
     }
 
-    /// The cipher built straight from a session key, skipping the proof step — the *peer* side of
-    /// [`ProofSeed::into_client_header_crypto`]. Both ends run the same state machine with inverse
-    /// operations from (index 0, previous 0), so a server's [`EncrypterHalf`] is exactly what a
-    /// client's [`DecrypterHalf`] inverts. Lets a test harness stand up a fake world server that
-    /// speaks real encrypted headers.
+    /// The cipher from a session key alone, skipping the proof: a server's [`EncrypterHalf`] is
+    /// what a client's [`DecrypterHalf`] inverts, so a fake world server speaks real headers.
     pub fn from_session_key(session_key: [u8; SESSION_KEY_LENGTH]) -> Self {
         Self::new(session_key)
     }
@@ -188,15 +171,13 @@ impl HeaderCrypto {
     }
 }
 
-/// The client's random seed for the world handshake. Created before `CMSG_AUTH_SESSION`; turned into
-/// the proof + [`HeaderCrypto`] once we know the server's seed.
+/// The client's random seed for the world handshake.
 #[derive(Debug, Clone, Copy)]
 pub struct ProofSeed {
     seed: u32,
 }
 
 impl ProofSeed {
-    /// A new random client seed.
     #[allow(clippy::new_without_default)]
     pub fn new() -> Self {
         Self {
@@ -209,8 +190,7 @@ impl ProofSeed {
         self.seed
     }
 
-    /// Compute the client proof (binds the session key to both seeds) and the [`HeaderCrypto`] used
-    /// for all subsequent headers. Valid once the server replies with a successful `SMSG_AUTH_RESPONSE`.
+    /// The client proof, binding the session key to both seeds, and the header cipher.
     pub fn into_client_header_crypto(
         self,
         username: &NormalizedString,
diff --git a/crates/benilla-ui/Cargo.toml b/crates/benilla-ui/Cargo.toml
index 96f2f778..d771455d 100644
--- a/crates/benilla-ui/Cargo.toml
+++ b/crates/benilla-ui/Cargo.toml
@@ -3,14 +3,12 @@ name = "benilla-ui"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "Engine-free WoW UI engine core: TOC/FrameXML parsing, templates, anchors, z-order — decision 0068"
+description = "Engine-free WoW UI engine core: TOC and FrameXML parsing, templates, anchors, z-order"
 
 [lints]
 workspace = true
 
 [dependencies]
 roxmltree = "0.20"
-# The embedded Lua runtime for the script host (decision 0068). `lua51` = Classic Era's Lua
-# version; `vendored` builds PUC-Rio Lua from source (no system dependency). 0.11 matches the
-# runtime that decision 0068's probe A verified (mlua + the LUAI_MAXCSTACK=8000 finding).
+# The script host's Lua 5.1; `vendored` builds it from the workspace's patched `lua-src`.
 mlua = { version = "0.11", features = ["lua51", "vendored"] }
diff --git a/crates/benilla-ui/examples/dump_globals.rs b/crates/benilla-ui/examples/dump_globals.rs
index b85f510f..1ff2df50 100644
--- a/crates/benilla-ui/examples/dump_globals.rs
+++ b/crates/benilla-ui/examples/dump_globals.rs
@@ -1,40 +1,17 @@
-//! `dump_globals` — print benilla's Lua global namespace, asked of a real VM.
+//! `dump_globals`: print benilla's Lua global namespace, asked of a real VM.
 //!
 //! ```text
 //! cargo run -q -p benilla-ui --example dump_globals            # name<TAB>type, one per line
-//! cargo run -q -p benilla-ui --example dump_globals --members  # ...the stdlib TABLES' members too
+//! cargo run -q -p benilla-ui --example dump_globals --members  # plus the stdlib tables' members
 //! ```
 //!
-//! **The point is that it is a run, not a grep** (decisions 1188, 1189). Every wrong number in the
-//! addon arc came from measuring our API surface by pattern-matching Rust source: a regex over
-//! `.set("Name", …)` misses the Lua prelude, miscounts a `format!`-registered family, and cannot
-//! see what the sandbox removed. When the question is what a running system exposes, ask the
-//! running system — this is the four-minute answer 1188 §4 describes, made permanent.
-//!
-//! This is [`UiScript::new`]'s namespace: the Rust bindings plus the Lua stdlib prelude, i.e. what
-//! an addon sees *before* any FrameXML loads. That is deliberately the engine half — it is
-//! deterministic, needs no install, and is exactly what `scripts/api-coverage.sh` compares against
-//! `reference/1.12-globals.tsv`'s `engine` and `lua` rows.
-//!
-//! ## `--members`, and the blind spot it closes (decision 1194)
-//!
-//! `_G` is not the whole surface an addon can tell apart. `table.setn` is not a global — it is a
-//! member of the `table` table — and it stopped **61 of 218** real addons dead, because mlua's Lua
-//! 5.1 raises `'setn' is obsolete` where the 1.12 client's Lua 5.0 does the thing. A `_G`-only
-//! instrument cannot see that, and did not: the arc measured coverage for two sessions with this
-//! gap wide open. `--members` prints `table.setn`-style rows for the stdlib tables, so the dialect
-//! is measurable the same way the API surface is.
-//!
-//! It also prints the **per-type metatables** (decision 2171), which is the same blind spot one
-//! layer further down and stayed open longer because a metatable is not a *name*: 5.1 gives the
-//! string type one and 5.0 cannot have one, so `("x"):upper()` worked here and raised on the
-//! reference for as long as nothing thought to look.
+//! The namespace is [`UiScript::new`]'s, the engine half before any FrameXML loads, which
+//! `scripts/api-coverage.sh` compares with `reference/1.12-globals.tsv`. `--members` adds what `_G`
+//! cannot show: the stdlib tables' members (`table.setn` is one) and the per-type metatables.
 use benilla_ui::script::UiScript;
 
-/// The tables whose membership an addon can observe and depend on.
-///
-/// Deliberately a fixed list, not "every table-valued global": `_G` would recurse, and a *frame*
-/// table's members are the widget API, which is a different question with a different reference.
+/// The stdlib tables whose members an addon can observe: a fixed list, since `_G` would recurse
+/// and a frame's members are the widget API.
 const STDLIB: &[&str] = &["string", "table", "math", "coroutine", "os", "io", "debug"];
 
 fn main() -> mlua::Result<()> {
@@ -66,18 +43,9 @@ fn main() -> mlua::Result<()> {
             rows.extend(members);
         }
 
-        // **The per-type metatables — the surface `_G` and the member lists both miss** (decision
-        // 2171). `table.setn` taught 1194 that a `_G`-only instrument cannot see a *member*; the
-        // string metatable is the same lesson one layer further down, and it stayed invisible for
-        // longer because it is not a name at all. 1.12 installs none — `lua_setmetatable 0x6f4020`
-        // accepts only LUA_TTABLE and LUA_TUSERDATA and returns 0 for every other tag, so a
-        // primitive type there *cannot* carry one — while stock 5.1 gives `string` a metatable
-        // whose `__index` is the `string` table itself, which is what makes `("x"):upper()` work
-        // on 5.1 and raise on 5.0. Every row here should read `nil`.
-        //
-        // Written as a fixed list rather than a table because a `nil` value has no entry to
-        // iterate — the one type whose metatable slot is easiest to forget is the one a
-        // constructor silently drops.
+        // The per-type metatables. Every row should read `nil`: 1.12's `lua_setmetatable`
+        // (`0x6f4020`) takes only tables and userdata, where 5.1 gives strings one whose `__index`
+        // makes `("x"):upper()` work. Probed one by one, since a `nil` has no table entry.
         let metatables: Vec<String> = script.eval(
             "local out = {} \
              local function probe(name, v) \
diff --git a/crates/benilla-ui/examples/dump_widget_methods.rs b/crates/benilla-ui/examples/dump_widget_methods.rs
index ad0d3dc7..27550a20 100644
--- a/crates/benilla-ui/examples/dump_widget_methods.rs
+++ b/crates/benilla-ui/examples/dump_widget_methods.rs
@@ -1,13 +1,10 @@
-//! `dump_widget_methods` — print benilla's widget METHOD surface, asked of a real VM.
+//! `dump_widget_methods`: print benilla's widget method surface, asked of a real VM.
 //!
 //! ```text
 //! cargo run -q -p benilla-ui --example dump_widget_methods    # class<TAB>method, one per line
 //! ```
 //!
-//! The sibling of [`dump_globals`](../dump_globals.rs). The measurement itself lives in
-//! `benilla_ui::script::widget_method_census` — its module doc is the *why*, and the widget-surface
-//! gate (decision 2142) reads the same function, so the instrument you look at by hand and the gate
-//! that fails the build can never disagree about what our surface is.
+//! The census is `widget_method_census`, the same function the widget-surface gate reads.
 use benilla_ui::script::{widget_method_census, UiScript};
 
 fn main() -> mlua::Result<()> {
diff --git a/crates/benilla-ui/src/bindings_xml.rs b/crates/benilla-ui/src/bindings_xml.rs
index a34b7ab6..895c9d3e 100644
--- a/crates/benilla-ui/src/bindings_xml.rs
+++ b/crates/benilla-ui/src/bindings_xml.rs
@@ -1,105 +1,37 @@
-//! **`Bindings.xml`** — an addon's key-binding declaration (decision 1188 phase 4).
+//! An addon's `Bindings.xml`, its key-binding declarations. The reference loads one per addon in
+//! `AddOn_Load 0x51f240`, after the addon's `.toc` files (`0x51f3fa`) and before its saved
+//! variables (`0x51f400` to `0x51f4b5`). The stock file has 228 live bindings (94 `runOnUp`, 13
+//! `header`, 12 `hidden`, 9 `debug`, 5 `platform`); the six `MOVEVIEW*` ones sit in an XML comment.
 //!
-//! The reference loads one per addon, at a verified position inside `AddOn_Load 0x51f240`
-//! (wow-5875-re `system/ui/ui.md`): **after** that addon's `.toc`-listed files (`0x51f3fa`) and
-//! **before** its saved-variables files (`0x51f400` → `0x51f4b5`). Both of benilla's load paths
-//! attach there — the startup walk (`benilla_app::ui_script::addons`) and the demand load
-//! ([`crate::script::addon`]) — and what they parse here feeds the same table the Key Bindings
-//! window edits ([`crate::script::keybind`]).
-//!
-//! ## The format, read off the client's own file, not remembered
-//!
-//! `Interface\FrameXML\Bindings.xml` (extracted 1.12.1) is **228 live `<Binding>` elements**,
-//! every one named, and the whole schema it uses is six attributes: `name` (228), `runOnUp` (94),
-//! `header` (13), `hidden` (12), `debug` (9), `platform` (5).
-//!
-//! *Live*, because a text search says 234: six more sit inside an XML comment — Blizzard commented
-//! out the whole `MOVEVIEW*` family in place. A parser that finds bindings by scanning text (and
-//! any count taken by `grep`) registers those six as real, which is why the counts here are the
-//! ones this module's own parse returns and why `a_commented_out_binding_is_not_a_binding` exists.
-//!
-//! ```xml
-//! <Bindings>
-//!     <Binding name="MOVEFORWARD" runOnUp="true" header="MOVEMENT">
-//!         if ( keystate == "down" ) then MoveForwardStart(); else MoveForwardStop(); end
-//!     </Binding>
-//! </Bindings>
-//! ```
-//!
-//! - **The body is ONE Lua chunk, run once or twice.** A `runOnUp="true"` binding runs on the
-//!   press *and again* on the release, with the global `keystate` set to `"down"` / `"up"` — which
-//!   is why every shipped `runOnUp` body is an `if ( keystate == "down" )` fork. A binding without
-//!   it runs once, on the press. (Our own registry says the same thing a second way:
-//!   `benilla_app::bindings::commands::Kind::EdgeUpDown` holds the two halves as two strings,
-//!   because a host command's halves are ours to write. An addon's is one string and a global.)
-//! - **`header` is a GLOBAL-STRING KEY, and it opens a SECTION.** `header="MOVEMENT"` means the
-//!   category `BINDING_HEADER_MOVEMENT`, and every following binding *without* a `header` belongs
-//!   to it: 13 headers over 228 bindings is 13 sections, and the client's own list is flat with
-//!   `HEADER_*` pseudo-entries in it (`Blizzard_BindingUI.lua:87` tests
-//!   `strsub(commandName, 1, 6) == "HEADER"`). The carry-forward is applied at *registration*, not
-//!   here, so this type stays a faithful record of what the file says — see
-//!   [`crate::script::UiScript::register_addon_bindings`].
-//! - **`hidden="true"` keeps a binding out of the Key Bindings window** while leaving it bindable
-//!   and dispatchable — 1.12 uses it for the debug toggles and for the three mouselook bindings
-//!   (`TURNORACTION`, `CAMERAORSELECTORMOVE`, …) that the mouse owns rather than the player.
-//! - **`platform="mac"` is the file's own OS gate**, and its five uses are the whole of it: the
-//!   `ITUNES_REMOTE` block, which remotes the *system* music player and therefore exists only in
-//!   the Mac build. It is carried on [`AddonBinding::platform`] and acted on at registration
-//!   ([`crate::script::UiScript::register_addon_bindings`]) — a row for another platform is not
-//!   registered at all, so it never reaches the Key Bindings window, a save file, or a chord.
-//!   Registering it instead would list a command whose body calls functions this build does not
-//!   have, which is a row that can only ever error on its first press.
-//! - `debug="true"` is **read and not acted on**: it appears only on the client's own nine
-//!   hidden dev toggles, always together with `hidden="true"` (which IS acted on and is what
-//!   keeps them out of the window), and no addon in the wild uses it. Recording that it exists is
-//!   the point; inventing a second meaning for it would be a guess.
-//!
-//! ## Why this lives beside `toc` and `framexml` rather than under `script/`
-//!
-//! It is the third of the client's **file formats**, and the crate's top level is where a format
-//! becomes owned data with no VM in sight: [`crate::toc`] turns manifest text into a load list,
-//! [`crate::framexml`] turns document text into a tree, and this turns binding text into
-//! [`AddonBinding`]s. `script/` is the other side of that line — the live Lua-facing runtime,
-//! which *consumes* what these three produce. A parser under `script/keybind` would also be
-//! unreachable from the host's own load path without going through the VM, which is exactly the
-//! shape 1186 spent a decision untangling.
-//!
-//! XML *parsing* is delegated plumbing here for the same reason it is in [`crate::framexml`] (the
-//! RE spec's own split: "XML parsing is DELEGATED; the schema→op map is owned") — `roxmltree`
-//! reads the bytes, and only the schema→meaning map below is ours.
+//! A body is one Lua chunk; with `runOnUp="true"` it runs on press and again on release, the
+//! global `keystate` set to `"down"` or `"up"`. `header="X"` opens the section
+//! `BINDING_HEADER_X` that following header-less bindings join, in a flat list with `HEADER`
+//! pseudo-entries (`Blizzard_BindingUI.lua:87`). `hidden="true"` keeps a binding bindable but out
+//! of the Key Bindings window. `platform="mac"` marks the `ITUNES_REMOTE` rows; the reference
+//! skips another platform's row at load (`0x4b70c3`–`0x4b70e5`), benilla at registration.
 
 use std::fmt;
 
-/// One `<Binding>` element, exactly as the file states it.
-///
-/// Deliberately a *record of the file*, not of the registered binding: `header` is the raw
-/// attribute (`None` when the element carries none, which is 221 of the reference's 234), and the
-/// section carry-forward and the `BINDING_HEADER_` prefixing happen where the addon's identity is
-/// known — [`crate::script::UiScript::register_addon_bindings`]. (`None` for 215 of the
-/// reference's 228 rows, which is what makes the carry-forward the whole story rather than a
-/// detail.)
+/// One `<Binding>` element as the file states it; the section carry-forward and the
+/// `BINDING_HEADER_` prefix are applied by [`crate::script::UiScript::register_addon_bindings`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AddonBinding {
-    /// The `name` attribute — the command name `SetBinding`/`GetBindingKey` speak in.
+    /// The command name `SetBinding` and `GetBindingKey` speak in.
     pub name: String,
-    /// The `header` attribute's global-string *suffix* (`MOVEMENT` → `BINDING_HEADER_MOVEMENT`),
-    /// when this element opens a section.
+    /// The raw `header` suffix (`MOVEMENT` of `BINDING_HEADER_MOVEMENT`), opening a section.
     pub header: Option<String>,
-    /// `runOnUp="true"` — the body runs on the press **and** on the release (see the module doc).
+    /// `runOnUp="true"`: the body runs on press and on release.
     pub run_on_up: bool,
-    /// `hidden="true"` — bindable and dispatchable, but not listed in the Key Bindings window.
+    /// `hidden="true"`: bindable, but not listed in the Key Bindings window.
     pub hidden: bool,
-    /// `platform="mac"` — the row belongs to one build only, lower-cased. `None` on every row
-    /// that carries no such attribute, which is every row but five.
+    /// `platform=`, lower-cased: the one build the row belongs to.
     pub platform: Option<String>,
-    /// The element's own text: one Lua chunk, verbatim (entities already decoded, so a body that
-    /// wrote `&lt;` arrives as `<`).
+    /// The element's own text, one Lua chunk, entities decoded (`&lt;` arrives as `<`).
     pub body: String,
 }
 
-/// A malformed document. Everything softer — an element with no `name`, an unknown attribute, an
-/// unexpected root — is tolerated the way the real loader tolerates it; only bytes that are not
-/// XML stop the file.
+/// Bytes that are not XML. A nameless element, an unknown attribute or an unexpected root is
+/// tolerated, as the reference's loader tolerates them.
 #[derive(Debug)]
 pub enum Error {
     Xml(roxmltree::Error),
@@ -121,23 +53,13 @@ impl std::error::Error for Error {
     }
 }
 
-/// Parse `Bindings.xml` text into its bindings, in document order.
-///
-/// **Every `<Binding>` under the root**, at any depth and matched case-insensitively like every
-/// other element compare in this crate (`0x64a4c0`, see [`crate::framexml`]'s header). The shipped
-/// root is `<Bindings>` and the elements are its direct children, but a descendant walk costs
-/// nothing and cannot over-collect — a `<Binding>` never nests — while it does keep an addon that
-/// wraps its bindings in a `<Ui>` root (or ships them inside a `<Bindings>` inside one) working.
-///
-/// **A `<Binding>` with no `name` is skipped**: there is nothing for `SetBinding` to name and
-/// nothing for the reference's record to key on. Defensive rather than observed — all 228 of the
-/// client's own are named.
+/// Parse `Bindings.xml` text into its bindings, in document order: every `<Binding>` at any
+/// depth, the tag matched case-insensitively (`0x64a4c0`), skipping one with no `name`. The
+/// reference reads only the root's children (`0x4b701f`) and also skips a row with an empty body
+/// (`0x4b7093`–`0x4b709e`) or `debug="true"` (`0x4b70a4`–`0x4b70bd`), which this keeps.
 pub fn parse(text: &str) -> Result<Vec<AddonBinding>, Error> {
-    // Namespace-oblivious, like the FrameXML document layer beside it and for the same reason
-    // (decision 2155; `framexml::parse`'s comment is the mechanism): a `Bindings.xml` is read by
-    // the same `XMLTree.cpp` tree the client builds with expat's `XML_ParserCreate`, which has no
-    // namespace processing at all — so an undeclared prefix cannot be an error there, and must not
-    // cost the whole file here.
+    // The reference's expat has no namespace processing, so an undeclared prefix is bound and the
+    // text re-read rather than costing the file, as in `framexml::parse`.
     let repaired;
     let doc = match roxmltree::Document::parse(text) {
         Ok(doc) => doc,
@@ -169,25 +91,21 @@ pub fn parse(text: &str) -> Result<Vec<AddonBinding>, Error> {
     Ok(out)
 }
 
-/// Case-insensitive attribute lookup — Blizzard's own XML is inconsistent about attribute casing
-/// and the real loader's `GetAttribute 0x6f2cf0` folds case ([`crate::framexml`]).
+/// Case-insensitive attribute lookup, as the reference's `GetAttribute 0x6f2cf0` folds case.
 fn attr_ci(node: roxmltree::Node, name: &str) -> Option<String> {
     node.attributes()
         .find(|a| a.name().eq_ignore_ascii_case(name))
         .map(|a| a.value().to_string())
 }
 
-/// A boolean attribute: true **iff** present and equal to the literal `"true"`, case-insensitively
-/// — the client's own rule (`0x6f1b30`'s true-cmp; there is no `"false"` branch, so `runOnUp="1"`
-/// is false exactly as it is in the real loader).
+/// True only for a case-insensitive `"true"` (`0x6f1b30` has no `"false"` branch), so
+/// `runOnUp="1"` is false.
 fn attr_bool(node: roxmltree::Node, name: &str) -> bool {
     attr_ci(node, name).is_some_and(|v| v.eq_ignore_ascii_case("true"))
 }
 
-/// The node's own direct text/CDATA children, concatenated — the binding's Lua chunk. Does not
-/// descend into child elements, and so drops the `<!-- … -->` comments the shipped file is full
-/// of. Concatenation (rather than the first text node) is what keeps a body containing an entity
-/// whole: `a &lt; b` arrives from `roxmltree` as three text nodes.
+/// The node's direct text and CDATA, concatenated: `roxmltree` splits `a &lt; b` into three text
+/// nodes.
 fn direct_text(node: roxmltree::Node) -> String {
     node.children()
         .filter(|n| n.is_text())
@@ -199,15 +117,6 @@ fn direct_text(node: roxmltree::Node) -> String {
 mod tests {
     use super::*;
 
-    /// **The reference's own shape**, element for element: the `runOnUp` + `header` opener with a
-    /// multi-line `keystate` fork, a plain one-shot binding, a `hidden` debug toggle, and — the
-    /// one case a hand-written addon file actually hits — an entity inside a body.
-    ///
-    /// What this catches: a parser that reads only the first text node (the `&lt;` body comes back
-    /// truncated at the entity), one that treats `runOnUp="1"`/absent as true, one that swallows
-    /// the newlines a Lua chunk needs to stay a Lua chunk, and one that hands back the `header`
-    /// already prefixed (the prefixing is registration's job — a doubled
-    /// `BINDING_HEADER_BINDING_HEADER_MOVEMENT` is the failure that would follow).
     #[test]
     fn the_reference_shape_parses_attribute_for_attribute() {
         let binds = parse(
@@ -268,8 +177,7 @@ mod tests {
             "the body is a Lua chunk — its newlines are load-bearing"
         );
 
-        // A binding with no header of its own carries none: the section it belongs to is a
-        // property of the LIST, resolved at registration.
+        // Section membership is resolved at registration, not here.
         assert_eq!(binds[1].name, "JUMP");
         assert_eq!(binds[1].header, None);
         assert!(!binds[1].run_on_up);
@@ -277,23 +185,18 @@ mod tests {
         assert!(binds[2].hidden, "hidden=\"true\" is recorded, not dropped");
         assert!(!binds[2].run_on_up);
 
-        // Attribute name AND value fold case (the loader's own compares do); the entity is
-        // decoded and the body around it survives whole.
+        // Attribute names and values fold case; the entity decodes and the body stays whole.
         assert!(binds[3].run_on_up, "RUNONUP=\"TRUE\" is runOnUp");
         assert_eq!(binds[3].body.trim(), "if ( a < b ) then Probe(); end");
 
-        // ...but only the literal `true` is true — there is no `"false"` branch in the client's
-        // parse, so `"1"` is simply not it.
         assert!(
             !binds[4].run_on_up,
             "runOnUp=\"1\" is false: the client's bool compares against \"true\" alone"
         );
     }
 
-    /// A nameless `<Binding>` is skipped rather than registered under `""` — where it would eat
-    /// `GetBindingAction`'s "no command is bound to this key" answer, which IS the empty string.
-    /// A `<Binding>` nested under a wrapper element still counts, so an addon that wraps its
-    /// bindings does not silently lose them.
+    /// Registered under `""`, a nameless binding would shadow `GetBindingAction`'s empty answer
+    /// for an unbound key.
     #[test]
     fn nameless_bindings_are_skipped_and_nesting_is_tolerated() {
         let binds = parse(
@@ -310,11 +213,6 @@ mod tests {
         assert_eq!(binds[0].name, "PROBEWRAPPED");
     }
 
-    /// **A commented-out `<Binding>` is not a binding** — and this is not a hypothetical: the
-    /// client's own file carries the entire `MOVEVIEW*` family (six bindings) inside one XML
-    /// comment, which is the whole gap between the 234 elements a text search finds and the 228
-    /// the loader sees. Registering them would put six commands in the Key Bindings window that
-    /// the client does not have, each one a key a player could bind to nothing at all.
     #[test]
     fn a_commented_out_binding_is_not_a_binding() {
         let binds = parse(
@@ -337,45 +235,9 @@ mod tests {
         );
     }
 
-    /// Bytes that are not XML stop the file — the one hard error. The addon's other files have
-    /// already run by then (`Bindings.xml` loads after them, `0x51f400`), so the load path reports
-    /// this and carries on; what it must not do is silently register nothing.
     #[test]
     fn malformed_xml_is_an_error() {
         let e = parse("<Bindings><Binding name=\"X\"></Bindings>").expect_err("malformed");
         assert!(e.to_string().starts_with("malformed Bindings.xml:"));
     }
-
-    /// Parses the REAL shipped file when `BENILLA_BINDINGS_XML` points at one (never committed —
-    /// extract `Interface\FrameXML\Bindings.xml` with benilla-extract). Skips silently otherwise,
-    /// matching `toc.rs`'s and `framexml.rs`'s pattern so the gates never depend on client data.
-    ///
-    /// The numbers are the ones this module's header quotes, so a wrong count here is either a
-    /// wrong file or a header that has drifted from the client.
-    #[test]
-    fn real_bindings_xml_when_available() {
-        let Ok(path) = std::env::var("BENILLA_BINDINGS_XML") else {
-            return;
-        };
-        let text = std::fs::read_to_string(&path).expect("reading BENILLA_BINDINGS_XML");
-        let binds = parse(&text).unwrap_or_else(|e| panic!("{path}: {e}"));
-        assert_eq!(
-            binds.len(),
-            228,
-            "1.12.1 ships 228 live bindings — the other six are inside a comment"
-        );
-        assert!(binds.iter().all(|b| !b.name.is_empty()));
-        assert!(
-            !binds.iter().any(|b| b.name.starts_with("MOVEVIEW")),
-            "the commented-out family must not register"
-        );
-        assert_eq!(binds.iter().filter(|b| b.run_on_up).count(), 94);
-        assert_eq!(binds.iter().filter(|b| b.header.is_some()).count(), 13);
-        assert_eq!(binds.iter().filter(|b| b.hidden).count(), 12);
-        assert_eq!(
-            binds[0].header.as_deref(),
-            Some("MOVEMENT"),
-            "the file opens on the MOVEMENT section"
-        );
-    }
 }
diff --git a/crates/benilla-ui/src/civil.rs b/crates/benilla-ui/src/civil.rs
index c050a795..a919a1a7 100644
--- a/crates/benilla-ui/src/civil.rs
+++ b/crates/benilla-ui/src/civil.rs
@@ -1,14 +1,6 @@
-//! **The tree's one civil-time conversion** — broken-down UTC from an epoch second.
-//!
-//! It lives here because this crate already had to have one: 1.12's `date()` global is Lua 5.0's
-//! `os.date` hoisted, and the sandbox strips `os` ([`crate::script`]'s stdlib), so the calendar
-//! had to be written by hand. The screenshot writer is its second caller (decision 1487), and one
-//! correct closed form with two callers beats two hand-rolled loops.
-//!
-//! **UTC, deliberately, and it is a stated divergence wherever a caller wanted local time.** The
-//! workspace has no date dependency at all — every format crate in it is in-repo — and resolving a
-//! local offset needs a timezone source, not a different algorithm. `date()` records the same
-//! divergence for the same reason.
+//! Broken-down UTC time from an epoch second, the calendar behind `date()` and screenshot names.
+//! Deviation: UTC where the reference's callers use local time, because the workspace has no
+//! timezone source.
 
 /// Broken-down UTC time.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
@@ -27,12 +19,8 @@ pub struct Civil {
     pub yearday: u32,
 }
 
-/// Break an epoch second down into UTC fields.
-///
-/// The civil-from-days conversion is Howard Hinnant's, shifted to a March-based year so the leap
-/// day lands at the end and no month-length table is needed. Chosen over a hand-rolled loop
-/// because it is a known-correct closed form with no accumulation error, which matters for the
-/// "persisted last session, compared this session" use every corpus `date()` caller has.
+/// Break an epoch second down into UTC fields, by Howard Hinnant's civil-from-days: years count
+/// from month 3, so the leap day falls last and no month-length table is needed.
 pub fn from_unix(secs: i64) -> Civil {
     let days = secs.div_euclid(86_400);
     let rem = secs.rem_euclid(86_400);
@@ -55,7 +43,6 @@ pub fn from_unix(secs: i64) -> Civil {
     let month = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
     let year = if month <= 2 { y + 1 } else { y };
 
-    // Day of the year, from the same conversion applied to Jan 1.
     let yearday = (days - days_from_civil(year, 1, 1) + 1) as u32;
     Civil {
         year,
@@ -69,7 +56,6 @@ pub fn from_unix(secs: i64) -> Civil {
     }
 }
 
-/// Days since the epoch for a civil date — the inverse of the above, used only for `yearday`.
 fn days_from_civil(y: i64, m: u32, d: u32) -> i64 {
     let y = if m <= 2 { y - 1 } else { y };
     let era = y.div_euclid(400);
@@ -80,8 +66,7 @@ fn days_from_civil(y: i64, m: u32, d: u32) -> i64 {
     era * 146_097 + doe - 719_468
 }
 
-/// Wall-clock seconds since the Unix epoch. Before the epoch is not a state a game client is in; a
-/// clock that somehow reports it clamps to 0 rather than raising inside an addon's file scope.
+/// Wall-clock seconds since the Unix epoch; a clock set before 1970 reads 0 rather than raising.
 pub fn unix_seconds() -> i64 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
@@ -93,8 +78,7 @@ pub fn unix_seconds() -> i64 {
 mod tests {
     use super::*;
 
-    /// Four instants that between them cover the epoch itself, a leap day, a century boundary and
-    /// an ordinary afternoon — the cases a closed-form conversion gets wrong when it is wrong.
+    /// The epoch, an ordinary afternoon, a leap day and the eve of 2000.
     #[test]
     fn known_instants_break_down() {
         let cases = [
@@ -121,8 +105,7 @@ mod tests {
         }
     }
 
-    /// Before 1970 is not a state a client is in, but the arithmetic must not wrap into nonsense
-    /// if a clock reports it — `div_euclid`/`rem_euclid` are load-bearing here, not stylistic.
+    /// `div_euclid`/`rem_euclid` keep a second before 1970 from wrapping into nonsense.
     #[test]
     fn negative_seconds_stay_civil() {
         assert_eq!(
diff --git a/crates/benilla-ui/src/framexml.rs b/crates/benilla-ui/src/framexml.rs
index a5b0725d..957e8e3a 100644
--- a/crates/benilla-ui/src/framexml.rs
+++ b/crates/benilla-ui/src/framexml.rs
@@ -1,46 +1,25 @@
-//! The FrameXML **document** layer (decision 0068): turns a `.xml` file's text into an owned,
-//! order-preserving tree, resolves `virtual`/`inherits` template expansion, and rewrites `$parent`
-//! name tokens. This is XML-tree semantics only — no widget instantiation (frame factories, anchor
-//! resolution, script compilation) and no Lua; those live in the layer above, which walks the tree
-//! this module produces.
-//!
-//! Ground truth is wow-5875-re's verified transcription of the real client's loader
-//! (`0x6edc00–0x6f3000`, closed VERIFIED ORCHESTRATION region):
-//! - `system/ui/ui.md` §"The FrameXML XML loader — schema → frame-op interpretation (RF-0024)"
-//! - `system/ui/scratch/rf24-framexml-loader.md` — the full top-level + per-element op map
-//! - `system/ui/scratch/rf26-nested-frames.md` — `<Frames>` / load-order (widget-layer concern; cited
-//!   here only for the "spliced before the instance's own nodes" ordering that also governs template
-//!   `<Frames>` children, which this module's generic child-concat already gets right)
-//! - `system/ui/scratch/rf27-parent-name-token.md` — the `$parent` substitution rule (RF-0027)
-//!
-//! XML *parsing* is DELEGATED plumbing per the RE spec ("XML parsing is DELEGATED; the schema→op map
-//! is owned") — we use `roxmltree` rather than reproduce a tokenizer; only the schema→op
-//! interpretation below is transcribed from the spec.
+//! The FrameXML document layer: a `.xml` file's text as an owned, order-preserving tree, with
+//! `inherits` template expansion and `$parent` name substitution; no widgets and no Lua. It
+//! follows the reference's loader (`0x6edc00`–`0x6f3000`, the file loader `0x6ede10`), whose XML
+//! tokenizer is an embedded expat and ours `roxmltree`.
 
 use std::collections::{HashMap, HashSet};
 use std::fmt;
 
-/// An owned XML element: tag, attributes (order preserved — Blizzard XML attribute order is
-/// sometimes meaningful for authoring tools, and always useful for round-tripping/debugging), and
-/// element children. Case-insensitive attribute lookup: "attrs via `GetAttribute 0x6f2cf0`" and
-/// element-name compares are case-insensitive in the real loader (`0x64a4c0`,
-/// rf24-framexml-loader.md, header), and Blizzard's own shipped XML is inconsistent about attribute
-/// casing (e.g. both `relativeTo` and stray all-lowercase variants appear in the wild), so lookups
-/// here fold case rather than assume a canonical spelling.
+/// An owned XML element, attributes in document order. Lookups fold case, as the reference's
+/// `GetAttribute 0x6f2cf0` and element-name compares (`0x64a4c0`) do.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Element {
     pub tag: String,
     attrs: Vec<(String, String)>,
     pub children: Vec<Element>,
-    /// The node's own direct text content (the XML node struct's `body-text @ +0xc`, per
-    /// rf24-framexml-loader.md's node-struct note). Populated for text-bearing elements such as
-    /// `<Scripts>` handler bodies (`<OnLoad>lua…</OnLoad>`) and inline `<Script>` bodies. Empty for
-    /// purely structural elements.
+    /// The node's own direct text (the reference node's body text at `+0xc`): a handler or
+    /// `<Script>` body.
     pub body: String,
 }
 
 impl Element {
-    /// Case-insensitive attribute lookup (see struct docs).
+    /// Case-insensitive attribute lookup.
     pub fn attr(&self, name: &str) -> Option<&str> {
         self.attrs
             .iter()
@@ -48,92 +27,68 @@ impl Element {
             .map(|(_, v)| v.as_str())
     }
 
-    /// A boolean attribute (`hidden="true"`, `virtual="true"`, …): true iff present and equal to
-    /// the literal `"true"`, case-insensitively (`0x6f1b30`'s true-cmp, rf24-framexml-loader.md).
-    /// Absent or any other value is false — matching the client (there is no explicit `"false"`
-    /// branch in the spec; only a `true` match flips the flag).
+    /// True only for a case-insensitive `"true"` (`0x6f1b30`); there is no `"false"` branch.
     pub fn attr_bool(&self, name: &str) -> bool {
         self.attr(name)
             .is_some_and(|v| v.eq_ignore_ascii_case("true"))
     }
 
-    /// The same, but **presence-aware** — `None` when the attribute is absent.
-    ///
-    /// [`attr_bool`](Self::attr_bool) folds "absent" and `="false"` together, which is fine for a
-    /// flag whose default is off and *silently wrong* for one whose default is on: it turns an
-    /// explicit opt-out into a no-op. `<EditBox autoFocus="false">` is exactly that flag, and the
-    /// shipped UI writes it ten times.
+    /// [`attr_bool`](Self::attr_bool), but `None` when absent, for a flag whose default is on
+    /// (`<EditBox autoFocus="false">`).
     pub fn attr_bool_opt(&self, name: &str) -> Option<bool> {
         self.attr(name).map(|v| v.eq_ignore_ascii_case("true"))
     }
 
-    /// The `name` attribute, if any.
     pub fn name(&self) -> Option<&str> {
         self.attr("name")
     }
 
-    /// All attributes, in document order, as written.
     pub fn attrs(&self) -> &[(String, String)] {
         &self.attrs
     }
 }
 
-/// A `<Script>` reference: an external file (`<Script file="…"/>`) or an inline body
-/// (`<Script>lua…</Script>`). Both run in document order relative to everything else at the top
-/// level ("`<Script file=>`/inline `<Script>` → run Lua … **in document order** — this is how
-/// XML-referenced FrameXML Lua loads", rf24-framexml-loader.md, top level).
+/// A `<Script file=…>` or an inline `<Script>` body; both run in document order with the rest of
+/// the top level (`0x704bc0`/`0x704cd0`, from `0x6ede10`'s walk).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ScriptRef {
     File(String),
     Inline {
         body: String,
-        /// The 1-based line **of this XML file** that `body`'s first character sits on.
-        ///
-        /// Carried so the loader can pad the chunk out to that offset, making Lua's own error
-        /// lines the file's lines. Without it every inline block starts at line 1 and a raise
-        /// reports a number belonging to no file — worse than no number, because it looks like one
-        /// you could go and read (decision 1214).
+        /// The 1-based line of the file that `body` starts on, so the loader can pad the chunk and
+        /// Lua's error lines are the file's.
         line: u32,
     },
 }
 
-/// One top-level item of a FrameXML document, in document order. Modeled as an order-preserving
-/// `Vec<TopLevel>` rather than a split `{ scripts, fonts, templates, instances }` struct because the
-/// real loader executes `<Include>`/`<Script>` interleaved with frame element definitions **in
-/// document order** (rf24-framexml-loader.md, top level) — a split-by-kind struct would lose that
-/// order and misrepresent Lua load sequencing.
+/// One top-level item, kept in document order: the reference runs `<Include>` and `<Script>`
+/// interleaved with frame definitions (`0x6ede10`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum TopLevel {
-    /// `<Include file="…"/>` — recurse-load another file at this point in the sequence
-    /// (rf24-framexml-loader.md, top level: `0x8710c0`). File resolution/recursion is the loader
-    /// layer's job; this only preserves *where* the include happens relative to everything else.
+    /// `<Include file=…>`: load another file at this point (`0x8710c0`).
     Include(String),
     Script(ScriptRef),
-    /// `<Font …>` — a named font definition (rf24-framexml-loader.md, top level: `0x87106c`).
+    /// `<Font …>`, a named font definition (`0x87106c`).
     Font(Element),
-    /// A frame/region element with `virtual="true"`: registered as a template keyed by `name`, not
-    /// instantiated (rf24-framexml-loader.md, top level: `0x6ee500`).
+    /// An element with `virtual="true"`: a template keyed by `name`, not instantiated
+    /// (`0x6ee500`).
     Template(Element),
-    /// A frame/region element without `virtual="true"`: instantiated in place.
+    /// An element without `virtual="true"`: instantiated in place.
     Instance(Element),
 }
 
-/// The result of parsing one FrameXML document: its top-level items in order, plus any tolerable
-/// issues found along the way.
+/// One parsed document: its top-level items in order, and the issues it loaded past.
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct ParsedDocument {
     pub items: Vec<TopLevel>,
-    /// Tolerable issues: unregistered (unnamed) virtual templates, missing `Include`/`Font`
-    /// attributes, a non-`<Ui>` root, and similar — the real client logs and continues rather than
-    /// aborting the whole file for these, so parsing does too (see [`parse`]'s docs).
+    /// An unnamed virtual, an `<Include>` or `<Font>` missing its attribute, a root that is not
+    /// `<Ui>`: logged, and the file goes on.
     pub warnings: Vec<String>,
 }
 
 impl ParsedDocument {
-    /// All registered templates, keyed by name, for use with [`expand`]. A [`TopLevel::Template`]
-    /// with no `name` (already flagged in [`ParsedDocument::warnings`] at parse time — an
-    /// "Unnamed virtual node" load error in the real client, rf24-framexml-loader.md) is simply
-    /// absent here, matching the fact that nothing can `inherits=` it.
+    /// The named templates, for [`expand`]; an unnamed one (the reference's "Unnamed virtual
+    /// node" error, `0x6ee500`) is absent.
     pub fn templates(&self) -> HashMap<&str, &Element> {
         self.items
             .iter()
@@ -145,8 +100,7 @@ impl ParsedDocument {
     }
 }
 
-/// A document parse error: malformed XML. Tolerable issues (unknown tags, missing optional
-/// attributes, an unregistrable template) are not errors — see [`ParsedDocument::warnings`].
+/// Malformed XML; anything softer is a [`ParsedDocument::warnings`] entry.
 #[derive(Debug)]
 pub enum Error {
     Xml(roxmltree::Error),
@@ -168,45 +122,16 @@ impl std::error::Error for Error {
     }
 }
 
-/// Parse FrameXML document text into an owned, order-preserving tree.
-///
-/// Top-level semantics (rf24-framexml-loader.md, "top level"): the root's children are walked in
-/// order; `<Include file=>` and `<Script file=>`/inline `<Script>` are preserved as-is (their
-/// execution is the loader layer's job — this only fixes their position); `<Font>` becomes a font
-/// definition; any other element with `virtual="true"` registers as a template (by `name`); anything
-/// else is an instance. Unknown top-level tags (not one of the 13 known frame-element types) are
-/// kept as generic [`Element`]s and classified the same way (template if `virtual="true"`, else
-/// instance) — the real client's loader tolerates them the same way (widget-type validation happens
-/// later, at instantiation, which is out of this module's scope).
-///
-/// A root element that isn't (case-insensitively) `<Ui>` is tolerated with a warning, not a hard
-/// error: the RE spec never states the loader checks the root's own tag name, only that it walks
-/// its children (`0x6ede10`).
+/// Parse FrameXML text. As in `0x6ede10`, the root's children are walked in order: `<Include>`
+/// and `<Script>` keep their place, `<Font>` is a font, and any other element, known tag or not,
+/// is a template when `virtual="true"` and an instance otherwise; widget types are checked at
+/// instantiation. A root that is not `<Ui>` only warns: the reference's walk is not known to check
+/// the root's tag.
 pub fn parse(text: &str) -> Result<ParsedDocument, Error> {
-    // **The reference has no XML Namespaces, and our stand-in parser does** (decision 2155).
-    //
-    // The client's document tree is `XMLTree.cpp`'s, built by embedded **expat 1.95.5** created
-    // through `XML_ParserCreate 0x7e6690` — *not* `XML_ParserCreateNS` — so namespace processing
-    // is off: a prefix is opaque bytes inside the attribute's name, an `xmlns:` declaration is an
-    // ordinary attribute, and an *undeclared* prefix cannot be an error because nothing is
-    // resolving one. The node struct the FrameXML loader walks is that same tree (name `@+0x8`,
-    // the `{char*, char*}` attribute array `@+0x14`, looked up by `GetAttribute 0x6f2cf0`'s linear
-    // case-insensitive scan — `scratch/rf24-framexml-loader.md`'s header and
-    // `scratch/simplehtml-markup-engine.md` §1.2).
-    //
-    // `roxmltree` is namespace-aware and has no switch for it, so it refuses
-    // `<Ui xsi:schemaLocation="…">` with `UnknownNamespace` when the file never declares
-    // `xmlns:xsi` — and takes the **whole document** with it. That is not a rare authoring slip:
-    // Auctioneer writes exactly that line at the top of all five of its UI documents and
-    // BeanCounter includes two of them, so the Auction House replacement lost its entire interface
-    // to a concept the client it targets does not implement.
-    //
-    // So a namespace error is answered by giving the parser the binding it wants and re-reading —
-    // driven by the prefix the error itself names, never by scanning the text for colons (which
-    // would fire inside comments, CDATA and attribute values). The document's own bytes are
-    // otherwise untouched, and [`element_from_node`] drops every prefixed attribute, so nothing
-    // downstream can see the difference between a repaired document and one that never had a
-    // prefix.
+    // The reference's expat is created by `XML_ParserCreate 0x7e6690`, not the NS variant, so a
+    // prefix is opaque and an undeclared one (`xsi:` with no `xmlns:xsi`) is no error, where
+    // `roxmltree` rejects the whole document. Bind the prefix the error names and re-read; the
+    // bytes are otherwise untouched, and `element_from_node` drops prefixed attributes.
     let repaired;
     let doc = match roxmltree::Document::parse(text) {
         Ok(doc) => doc,
@@ -221,7 +146,7 @@ pub fn parse(text: &str) -> Result<ParsedDocument, Error> {
     let mut warnings = Vec::new();
     if !root.tag_name().name().eq_ignore_ascii_case("Ui") {
         warnings.push(format!(
-            "root element is <{}>, not <Ui>; tolerated (rf24-framexml-loader.md's file loader walks \
+            "root element is <{}>, not <Ui>; tolerated (the reference's file loader walks \
              the root's children regardless of the root's own tag)",
             root.tag_name().name()
         ));
@@ -255,7 +180,7 @@ pub fn parse(text: &str) -> Result<ParsedDocument, Error> {
                 if el.name().is_none() {
                     warnings.push(format!(
                         "virtual <{}> without a name — a load error in the real client \
-                         (\"Unnamed virtual node\", rf24-framexml-loader.md); kept but unregistered, \
+                         (\"Unnamed virtual node\"); kept but unregistered, \
                          so nothing can inherit it",
                         el.tag
                     ));
@@ -270,22 +195,10 @@ pub fn parse(text: &str) -> Result<ParsedDocument, Error> {
     Ok(ParsedDocument { items, warnings })
 }
 
-/// Declare every prefix the document uses but never binds, so a namespace-aware parser stops
-/// having an opinion the reference's parser cannot have (decision 2155; the *why* is in
-/// [`parse`]).
-///
-/// **Driven by the parser's own error, not by a scan.** `roxmltree` names the offending prefix in
-/// `UnknownNamespace`, so each round adds exactly that one binding to the ROOT element's start tag
-/// — where a declaration is in scope for the whole document, including the root's own name — and
-/// re-parses. A text scan for `name:` would fire inside comments, CDATA and attribute values
-/// (`Interface\AddOns\…` and `$Id:` lines are everywhere in this corpus), and would have to
-/// re-implement the tokenizer to avoid it.
-///
-/// Bounded, and honest when it gives up: a document that keeps naming new prefixes stops after
-/// [`MAX_BOUND_PREFIXES`] rounds and the text is returned as it stands, so [`parse`] reports the
-/// parser's real error rather than looping. A document whose error is something else on the retry
-/// (a genuinely malformed file that also has a stray prefix) reports that error, which is the one
-/// worth reading.
+/// Declare each prefix the document uses but never binds, one per round on the root's start tag
+/// (in scope everywhere, the root's own name included), taking the prefix each
+/// `UnknownNamespace` error names, never a text scan, which would match inside comments and
+/// values. Any other error, or [`MAX_BOUND_PREFIXES`] rounds, returns the text as it stands.
 pub(crate) fn bind_undeclared_prefixes(text: &str) -> String {
     let mut out = text.to_string();
     for _ in 0..MAX_BOUND_PREFIXES {
@@ -296,9 +209,7 @@ pub(crate) fn bind_undeclared_prefixes(text: &str) -> String {
         let Some(at) = root_attr_insertion_point(&out) else {
             return out;
         };
-        // The URI is inert and never read: nothing downstream resolves a namespace, and
-        // `element_from_node` drops prefixed attributes outright. It only has to be *a* URI, and
-        // distinct per prefix so two stray prefixes are not silently the same namespace.
+        // An inert URI, distinct per prefix so two stray prefixes stay two namespaces.
         out.insert_str(
             at,
             &format!(" xmlns:{prefix}=\"urn:benilla:undeclared:{prefix}\""),
@@ -307,20 +218,12 @@ pub(crate) fn bind_undeclared_prefixes(text: &str) -> String {
     out
 }
 
-/// How many distinct undeclared prefixes [`bind_undeclared_prefixes`] will bind before it stops.
-///
-/// Generous against the real cause (one file, one stray `xsi:`) and small enough that a
-/// pathological document cannot turn a failed parse into a long loop.
+/// The most undeclared prefixes [`bind_undeclared_prefixes`] binds before giving up.
 const MAX_BOUND_PREFIXES: usize = 8;
 
-/// The byte offset inside the ROOT element's start tag at which a new attribute may be inserted —
-/// just before the `>` or `/>` that closes it.
-///
-/// Walks the prolog by hand rather than parsing, because the document by definition does not parse
-/// at this point: `<?…?>`, `<!--…-->` and `<!…>` are skipped, and the first remaining `<` opens the
-/// root. Inside that tag, `'` and `"` runs are stepped over whole, so a `>` living in an attribute
-/// value (`hyperlinkFormat="|H%s|h[%s]|h"` is the shape that exists in this corpus) cannot be
-/// mistaken for the tag's end.
+/// The byte offset just before the `>` or `/>` closing the root's start tag, found by hand since
+/// the document does not parse yet: the prolog is skipped and quoted values are stepped over, so
+/// a `>` inside one (`hyperlinkFormat="|H%s|h[%s]|h"`) is not the tag's end.
 fn root_attr_insertion_point(text: &str) -> Option<usize> {
     let b = text.as_bytes();
     let mut i = 0usize;
@@ -337,7 +240,7 @@ fn root_attr_insertion_point(text: &str) -> Option<usize> {
         } else if rest.starts_with("<!") {
             i += rest.find('>').map(|n| n + 1)?;
         } else {
-            // The root's start tag. Step over quoted runs so a `>` inside a value is not its end.
+            // The root's start tag.
             let mut j = i + 1;
             while j < b.len() {
                 match b[j] {
@@ -368,14 +271,8 @@ fn attr_ci(node: roxmltree::Node, name: &str) -> Option<String> {
         .map(|a| a.value().to_string())
 }
 
-/// Concatenates a node's own direct text/CDATA children (not descending into child elements) —
-/// the XML node struct's `body-text @ +0xc` (rf24-framexml-loader.md, header).
-/// The 1-based line of the first text byte inside a `<Script>` element.
-///
-/// Taken from the first text child's own range rather than the element's, because a CDATA section
-/// puts `<![CDATA[` between the two and every FrameXML script block in this project uses one — the
-/// element's start line would be off by however much of the opening tag precedes the body.
-/// Falls back to the element's line for a `<Script></Script>` with no text at all.
+/// The 1-based line of the first text byte inside a `<Script>`: the first text child's, since
+/// `<![CDATA[` can sit between the tag and the body, else the element's own.
 fn inline_start_line(doc: &roxmltree::Document, node: roxmltree::Node) -> u32 {
     let at = node
         .children()
@@ -398,13 +295,9 @@ fn element_from_node(node: roxmltree::Node) -> Element {
         tag: node.tag_name().name().to_string(),
         attrs: node
             .attributes()
-            // **A prefixed attribute is unreachable in the reference, so it is not an attribute
-            // here** (decision 2155). `GetAttribute 0x6f2cf0` compares a lookup key against the
-            // stored name whole, and no FrameXML attribute name contains a colon — so
-            // `xsi:schemaLocation` can never match any key the loader asks for. Dropping it is
-            // what keeps a *declared* prefix (stock FrameXML's own `<Ui xmlns:xsi=… xsi:schema
-            // Location=…>`) and an *undeclared* one (Auctioneer's) behave identically, and stops
-            // `roxmltree`'s local-name view from making `xsi:name` answer a lookup for `name`.
+            // `GetAttribute 0x6f2cf0` matches the whole stored name and no FrameXML key has a
+            // colon, so a prefixed attribute is unreachable; dropping it also stops `roxmltree`'s
+            // local names from letting `xsi:name` answer for `name`.
             .filter(|a| a.namespace().is_none())
             .map(|a| (a.name().to_string(), a.value().to_string()))
             .collect(),
@@ -417,40 +310,12 @@ fn element_from_node(node: roxmltree::Node) -> Element {
     }
 }
 
-/// Resolve `inherits="A, B"` template references into a fully materialized [`Element`]: a
-/// structural merge with inherited content first, the element's own content last.
-///
-/// **Splice order** (rf24-framexml-loader.md, "virtual / template inheritance": "the matched
-/// entry is a template, its stored attribute/child nodes are spliced in first" [then the instance's
-/// own nodes are read on top]; rf26-nested-frames.md confirms the same "inherited-first" ordering
-/// for a template's own `<Frames>` children) — so:
-/// - **children**: the (fully expanded) template's children first, in order, then the element's own
-///   children appended after.
-/// - **attributes**: the template's attributes, with the element's own attributes overriding any
-///   attribute of the same name (case-insensitively) and adding any the template didn't have. This
-///   is the literal reading of "spliced in first, then the instance's own" applied to attributes —
-///   note this means an element that omits `name` entirely while inheriting a *named* template would
-///   inherit that template's registration name, and `virtual="true"`/`inherits="…"` themselves are
-///   ordinary attributes that splice through too (harmlessly inert post-expansion: nothing reads
-///   them again after the one-time top-level virtual/instance routing decision, which already
-///   happened on the *outer* node before expansion ever runs). Real FrameXML avoids ever hitting the
-///   `name` case (instances either supply their own name or stay anonymous), and the RE notes don't
-///   call out a `name`/`virtual` exception, so this implementation does not special-case them —
-///   flagged as an unverified edge case, not a silent guess.
-///
-/// **Multiple `inherits`** (`"A, B"`, comma-separated, left-to-right): each named template is
-/// resolved and merged in order, so `B`'s content lands on top of `A`'s where they overlap, and the
-/// element's own content lands on top of both. The RE spec documents the single-template splice
-/// precisely but not multi-template precedence beyond "the named template's[s'] … nodes"
-/// (rf24-framexml-loader.md); left-to-right precedence (later name wins ties) is the natural reading
-/// and is what this function implements — flagged, not guessed silently, since it isn't
-/// byte-verified for the multi-name case specifically.
-///
-/// **Chains** (a template inheriting another template) recurse: each named template is itself fully
-/// expanded (its own `inherits` resolved) before being merged in.
-///
-/// **Cycles** are guarded: if expanding a chain would re-enter a template already being expanded,
-/// that reference is skipped and a warning is appended instead of infinite-recursing.
+/// Resolve `inherits` into a materialized [`Element`]: the named template, itself expanded first,
+/// then the element on top, as the reference splices a template's nodes before the instance's
+/// own (`LoadChildFrames 0x76a060` keeps that order for `<Frames>`). Children are the template's
+/// then the element's; the element's attributes override or extend the template's
+/// (case-insensitively). `name` and `virtual` splice like any attribute; whether the reference
+/// exempts them is untraced. A cycle is skipped with a warning.
 pub fn expand(
     element: &Element,
     templates: &HashMap<&str, &Element>,
@@ -459,14 +324,8 @@ pub fn expand(
     expand_known(element, templates, &HashSet::new(), warnings)
 }
 
-/// [`expand`], plus the names that are known to be **font objects** rather than element templates.
-///
-/// A `<FontString inherits="GameFontNormalSmall">` names a font, not a template, and the font is
-/// applied later by its own path (`apply_fontstring_font`) — so the name must be skipped here
-/// silently rather than warned as unknown. `Loader::expand_region` already made that distinction
-/// for an INSTANCE; it could not make it one level down, and stock `BuffFrame.xml` is exactly that
-/// case: `BuffButtonDurationTemplate` is a virtual `<FontString>` that inherits a font object, so
-/// every instance of it warned twenty-six times over (decision 1874).
+/// [`expand`], skipping without a warning an `inherits` that names a font object: a
+/// `<FontString inherits="GameFontNormalSmall">` takes a font, applied later, not a template.
 pub fn expand_known(
     element: &Element,
     templates: &HashMap<&str, &Element>,
@@ -488,25 +347,10 @@ fn expand_inner(
         return element.clone();
     };
 
-    // ── ONE name, matched case-INSENSITIVELY (wow-re, template-name lookup) ────────────────────
-    //
-    // **No comma splitting.** 1.12's registry lookup `0x6ee6f0` has no splitter at all:
-    // `inherits="A, B"` is ONE literal name, misses, and applies neither template. Supporting the
-    // list is what LATER clients do, so splitting here made us a superset of 1.12 (1189). Nothing
-    // uses it — 0 comma lists in our own assets, 0 across the 218-addon corpus, and 0 in stock
-    // Blizzard XML's 249 distinct `inherits=` values.
-    //
-    // **Case-insensitive.** The compare is `SStrCmpI` → `_strnicmp` at `0x6ee747`, and the trap
-    // that decides it is the BUCKET HASH: `SStrHash 0x64b3f0` uppercases before mixing, so a
-    // mis-cased name lands in the same bucket and the stored-hash pre-check passes rather than
-    // short-circuiting. `Recap`'s `inherits="UIDropdownMenuTemplate"` (lowercase d) resolves on the
-    // real client. ASCII-only, like every other fold in this engine — bytes >= 0x80 are untouched.
-    //
-    // The fold is done as a scan on miss rather than by re-keying the view, because this same
-    // function resolves the FONT registry too and both are name→element maps of the same shape.
-    // Verbatim — not trimmed. `GetAttribute 0x6f2cf0` returns the parsed value as expat stored it
-    // (`SStrDup`, no trim, no fold), and the empty test is a single `cmp [esi],0` on the first
-    // byte: `inherits=""` is a silent skip, `inherits=" "` is a lookup that misses.
+    // `inherits` is one name, not a list: `0x6ee6f0` has no splitter, so `"A, B"` misses (later
+    // clients split it). It is used verbatim (`GetAttribute 0x6f2cf0` does not trim; `""` is
+    // skipped, `" "` misses) and matched case-insensitively, ASCII only: `_strnicmp` at
+    // `0x6ee747`, reached despite a mis-cased name because `SStrHash 0x64b3f0` uppercases.
     let mut base: Option<Element> = None;
     for name in [inherits].into_iter().filter(|s| !s.is_empty()) {
         if !active.insert(name.to_string()) {
@@ -522,8 +366,7 @@ fn expand_inner(
                 .map(|(_, v)| *v)
         });
         let Some(template) = hit else {
-            // A FONT OBJECT is not an unknown template: it is a different namespace, applied by
-            // `apply_fontstring_font` after this. Skip it without a word (1874).
+            // A font object is not an unknown template; it is applied after this.
             if !fonts.contains(name) {
                 warnings.push(format!(
                     "unknown template '{name}' referenced by inherits; skipping"
@@ -546,10 +389,7 @@ fn expand_inner(
     }
 }
 
-/// The structural merge documented on [`expand`]: `base`'s children first, `over`'s appended after;
-/// `over`'s attributes override `base`'s of the same name (case-insensitive), and are added if
-/// `base` didn't have them. `over`'s tag and body win (an instance's own tag/handler body, if any,
-/// is what actually runs).
+/// [`expand`]'s merge; `over`'s tag wins, and its body when it has one.
 fn merge(base: &Element, over: &Element) -> Element {
     let mut attrs = base.attrs.clone();
     for (k, v) in &over.attrs {
@@ -575,19 +415,9 @@ fn merge(base: &Element, over: &Element) -> Element {
     }
 }
 
-/// The synthetic element a **runtime** `CreateFrame(kind, name, parent, "A, B")` expands: a bare
-/// node of the caller's own `tag` carrying nothing but the `inherits=` list.
-///
-/// Handing this to [`expand`] is what makes the Lua path and the XML path *the same* path — one
-/// comma-split, one chain resolution, one cycle guard, one unknown-template warning, one splice
-/// order. Nothing about `inherits=` is written twice.
-///
-/// And because [`merge`] takes the **overriding** node's tag, the expanded result carries `tag` —
-/// the kind `CreateFrame` was actually given — whatever the templates were declared as. That is
-/// the honest answer to `CreateFrame("Frame", n, p, "SomeButtonTemplate")`: the frame already
-/// exists as a Frame, so the template's `<Button>` tag cannot retype it, and the loader's per-kind
-/// passes (which every one of them gate on the element tag) skip the parts that could not apply
-/// anyway.
+/// The bare node a runtime `CreateFrame(kind, name, parent, inherits)` expands through
+/// [`expand`], so Lua and XML resolve `inherits` alike. The result keeps `tag`, the kind
+/// `CreateFrame` was given: a template's `<Button>` cannot retype a `"Frame"`.
 pub fn inherits_node(tag: &str, inherits: &str) -> Element {
     Element {
         tag: tag.to_string(),
@@ -597,31 +427,15 @@ pub fn inherits_node(tag: &str, inherits: &str) -> Element {
     }
 }
 
-/// The literal fallback base name (rf27-parent-name-token.md, rule 5): when a `$parent`-prefixed
-/// name has no named ancestor to substitute (e.g. a top-level element), the real client seeds the
-/// result with the literal string `"Top"` (VA `0x8788ac`) rather than leaving the token literal,
-/// erroring, or producing an empty name.
+/// What `$parent` expands to with no named ancestor: the literal `"Top"` (`0x8788ac`).
 pub const DEFAULT_PARENT_NAME: &str = "Top";
 
-/// `$parent` name-token substitution (RF-0027, rf27-parent-name-token.md).
-///
-/// A `name` attribute beginning, **case-insensitively**, with the literal `"$parent"` (rule 5: the
-/// compare folds `A`–`Z`; `$Parent`/`$PARENT` all match — the *only* such token, there is no
-/// `$parentKey`/`$parentN` variant, rf27 point 1) has that 7-character prefix replaced with
-/// `parent_name`, and the remainder of `raw` appended verbatim (`SStrCat`). A `name` not starting
-/// with the token is copied through unchanged.
-///
-/// `parent_name` must be the caller's **already-resolved** name for the nearest ancestor that has
-/// one — i.e. the caller walks the ancestor chain (`this+0x9c`, rf27 rule 3) for the first ancestor
-/// whose own (already-substituted) name is non-empty, and passes [`DEFAULT_PARENT_NAME`] (`"Top"`)
-/// if there is none. Passing the already-resolved name (not the raw ancestor `name=` attribute
-/// text) is what makes nested `$parent` chains compose (rf27 rule 4): a child of a
-/// `$parent`-named parent inherits the parent's fully-resolved name, e.g. parent `PlayerFrame` +
-/// `"$parentHealthBar"` → `"PlayerFrameHealthBar"`, and a grandchild's `"$parentBar"` resolves
-/// against `"PlayerFrameHealthBar"`, not against the literal text `"$parentHealthBar"`.
-///
-/// Applies only to the `name` attribute (rf27 point 2) — `parent=` (which *resolves* the enclosing
-/// frame) is never `$parent`-substituted, and no other attribute is either.
+/// `$parent` substitution (`0x76c5b0`): a leading `$parent`, case-insensitive and the only such
+/// token, becomes `parent_name`, the rest appended verbatim. `parent_name` is the already-resolved
+/// name of the nearest named ancestor (the `+0x9c` walk), else [`DEFAULT_PARENT_NAME`], so nested
+/// `$parent` names compose. The reference calls it from two sites only, in `SetName` (`0x76c691`)
+/// and in the layout resolver `0x76c700` (`0x76c71c`): a name and an anchor's `relativeTo` (XML,
+/// `SetPoint` or `SetAllPoints`) expand, and `parent=` never does.
 pub fn resolve_name(raw: &str, parent_name: &str) -> String {
     const TOKEN: &str = "$parent";
     match raw.get(..TOKEN.len()) {
@@ -636,15 +450,6 @@ pub fn resolve_name(raw: &str, parent_name: &str) -> String {
 mod tests {
     use super::*;
 
-    /// **An undeclared namespace prefix is not an error, because the reference has no namespaces**
-    /// (decision 2155). The client's tree is `XMLTree.cpp`'s, built by expat 1.95.5 through
-    /// `XML_ParserCreate 0x7e6690` — never `XML_ParserCreateNS` — so nothing is resolving a prefix
-    /// and nothing can find one unbound.
-    ///
-    /// The literal line is Auctioneer's, at the top of all five of its UI documents (and two of
-    /// them are `<Include>`d by BeanCounter): a `roxmltree` `UnknownNamespace` there cost the
-    /// Auction House replacement its entire interface, an element at a time, to a concept the
-    /// client it targets does not implement.
     #[test]
     fn an_undeclared_namespace_prefix_does_not_cost_the_document() {
         let doc = parse(
@@ -660,9 +465,7 @@ mod tests {
         assert_eq!(el.name(), Some("Survived"));
     }
 
-    /// Two stray prefixes, and one of them on an ELEMENT rather than an attribute — the binding
-    /// goes on the root, where it is in scope for the whole document including the root's own
-    /// name, and the retry loop is driven by the parser naming each prefix in turn.
+    /// One stray prefix is on an element, not an attribute.
     #[test]
     fn several_undeclared_prefixes_are_all_bound() {
         let doc = parse(
@@ -675,10 +478,7 @@ mod tests {
         assert_eq!(doc.items.len(), 2);
     }
 
-    /// **A prefixed attribute is not an attribute** — `GetAttribute 0x6f2cf0` compares a lookup key
-    /// against the stored name whole, and no FrameXML key contains a colon, so `xsi:name` can never
-    /// answer a lookup for `name`. Asserted on a *declared* prefix as well, because stock FrameXML
-    /// writes one on every `<Ui>` and the two spellings must behave identically.
+    /// Both spellings, since stock FrameXML declares `xmlns:xsi` on every `<Ui>`.
     #[test]
     fn a_prefixed_attribute_never_answers_an_unprefixed_lookup() {
         for text in [
@@ -696,16 +496,11 @@ mod tests {
         }
     }
 
-    /// A genuinely malformed document still fails — the repair answers `UnknownNamespace` and
-    /// nothing else, so a mismatched tag is still the error a reader gets.
     #[test]
     fn a_malformed_document_still_fails_with_its_own_error() {
         assert!(parse(r#"<Ui xsi:a="b"><Frame></Ui>"#).is_err());
     }
 
-    /// The insertion point is found in the ROOT's start tag, past a prolog and past a `>` that
-    /// lives inside an attribute value — the shape `hyperlinkFormat="|H%s|h[%s]|h"` has in this
-    /// corpus, and the reason this walks quotes rather than searching for the first `>`.
     #[test]
     fn the_root_tag_is_found_past_a_prolog_and_a_quoted_angle_bracket() {
         let doc = parse(
@@ -714,7 +509,7 @@ mod tests {
         )
         .unwrap();
         assert_eq!(doc.items.len(), 1);
-        // …and a self-closing root: the attribute goes before the slash, not between it and `>`.
+        // A self-closing root: the binding goes before the slash.
         assert!(parse(r#"<Ui xsi:a="b"/>"#).is_ok());
     }
 
@@ -837,17 +632,8 @@ print(x)</Script>
         assert!(doc.warnings.is_empty());
     }
 
-    /// `inherits="A, B"` is **one name**, not a list — and it misses.
-    ///
-    /// This test used to assert the opposite (that both templates merged, children concatenated in
-    /// order). That was a superset of 1.12 borrowed from later clients: the carve found no splitter
-    /// anywhere in the loader — all 8 call sites hand `0x6ee6f0` the pointer `GetAttribute`
-    /// returned, one or two instructions later, and no comma is examined in `0x6ed000–0x6f6000` at
-    /// all. So the lookup runs **once**, for the literal name `"A, B"`, misses, warns at
-    /// severity 1, and the element loads with **neither** template applied.
-    ///
-    /// Whitespace is never trimmed either, which is why the second half asserts `" A "` misses a
-    /// template that genuinely exists.
+    /// All eight callers of `0x6ee6f0` pass `GetAttribute`'s pointer as is, and nothing in
+    /// `0x6ed000`–`0x6f6000` examines a comma; the value is not trimmed either.
     #[test]
     fn a_comma_list_is_one_literal_name_that_misses_and_applies_neither_template() {
         let doc = parse(
@@ -872,14 +658,13 @@ print(x)</Script>
         let mut warnings = Vec::new();
         let expanded = expand(inst, &templates, &mut warnings);
 
-        // Warned, naming the whole unsplit string — not split, not silently ignored.
         assert_eq!(warnings.len(), 1, "{warnings:?}");
         assert!(
             warnings[0].contains("A, B"),
             "the warning must name the literal it looked up: {warnings:?}"
         );
 
-        // The element still loads, with all of its OWN content and none of the templates'.
+        // The element loads with its own content only.
         assert_eq!(expanded.attr("alpha"), Some("1.0"));
         assert_eq!(expanded.children.len(), 1);
         fn texture_name(el: &Element) -> &str {
@@ -887,7 +672,7 @@ print(x)</Script>
         }
         assert_eq!(texture_name(&expanded.children[0]), "FromInst");
 
-        // And a padded name misses a template that exists — the value is used verbatim.
+        // A padded name misses: the value is used verbatim.
         let TopLevel::Instance(padded) = &doc.items[3] else {
             panic!("expected instance")
         };
@@ -921,8 +706,7 @@ print(x)</Script>
         let mut warnings = Vec::new();
         let expanded = expand(leaf, &templates, &mut warnings);
         assert!(warnings.is_empty());
-        // Mid's own frameStrata (it overrode Root's) wins, since chain-expanding Mid resolves Root
-        // first and Mid's own attrs on top, before Leaf (which sets nothing) merges on top of that.
+        // Mid's frameStrata overrides Root's, and Leaf sets none.
         assert_eq!(expanded.attr("frameStrata"), Some("MEDIUM"));
         assert_eq!(
             expanded.children.len(),
@@ -946,7 +730,6 @@ print(x)</Script>
             panic!("expected instance")
         };
         let mut warnings = Vec::new();
-        // Must terminate (not infinitely recurse) and report the cycle.
         let _expanded = expand(inst, &templates, &mut warnings);
         assert!(
             warnings.iter().any(|w| w.contains("cycle")),
@@ -969,38 +752,17 @@ print(x)</Script>
             resolve_name("NotAParentName", "PlayerFrame"),
             "NotAParentName"
         );
-        // No named ancestor: caller passes the literal "Top" fallback.
+        // No named ancestor: the caller passes the literal "Top".
         assert_eq!(resolve_name("$parentFoo", DEFAULT_PARENT_NAME), "TopFoo");
     }
 
     #[test]
     fn parent_name_substitution_composes_through_nested_children() {
-        // A named parent, a child using $parent, and a grandchild using $parent against the
-        // child's *resolved* name — not the child's raw literal "$parent..." text (rf27 rule 4).
+        // The grandchild resolves against the child's resolved name, not its raw "$parent…" text.
         let parent_name = "PlayerFrame";
         let child_name = resolve_name("$parentHealthBar", parent_name);
         assert_eq!(child_name, "PlayerFrameHealthBar");
         let grandchild_name = resolve_name("$parentText", &child_name);
         assert_eq!(grandchild_name, "PlayerFrameHealthBarText");
     }
-
-    /// Parses a REAL shipped FrameXML file when `BENILLA_FRAMEXML` points at one (never committed —
-    /// extract e.g. `Interface\FrameXML\PlayerFrame.xml` with benilla-extract). Skips silently
-    /// otherwise, matching toc.rs's `real_manifest_when_available` pattern so CI/gates don't depend
-    /// on client data.
-    #[test]
-    fn real_framexml_when_available() {
-        let Ok(path) = std::env::var("BENILLA_FRAMEXML") else {
-            return;
-        };
-        let text = std::fs::read_to_string(&path).expect("reading BENILLA_FRAMEXML");
-        let doc = parse(&text).unwrap_or_else(|e| panic!("{path}: {e}"));
-        assert!(
-            !doc.items.is_empty(),
-            "{path}: a real FrameXML file has at least one top-level item"
-        );
-        for w in &doc.warnings {
-            eprintln!("{path}: warning: {w}");
-        }
-    }
 }
diff --git a/crates/benilla-ui/src/justify.rs b/crates/benilla-ui/src/justify.rs
index ab0995e2..a2a2255c 100644
--- a/crates/benilla-ui/src/justify.rs
+++ b/crates/benilla-ui/src/justify.rs
@@ -1,57 +1,11 @@
-//! The justify enum — **one** transcription of `.rdata 0x811ad0`, shared by every table that
-//! speaks it.
-//!
-//! ## Why this is a module and not three sets of `match` arms
-//!
-//! Justification is set on **three** widget tables — a `FontString` (`0x87c1d8`), a `<Font>`
-//! object (`0x87c7c8`) and an `EditBox` — and each had been transcribed *independently* from the
-//! same byte law. Each drifted its own way, and each looked right alone:
-//!
-//! | | FontString ([`crate::script::region`]) | Font ([`crate::script::font`]) | EditBox ([`crate::widget::kinds::editbox`]) | the bytes |
-//! |---|---|---|---|---|
-//! | `GetJustifyH`/`V` | **absent** | present | present | present (`0x79e5f0`/`0x79e7f0`) |
-//! | space-padded token | rejected | `.trim()`ed, **accepted** | rejected | rejected (whole-string) |
-//! | unmatched string | silently `CENTER` | silently `CENTER` | **raises** | **raises** |
-//! | cross-axis token | silently `CENTER` | silently `CENTER` | **clears the axis** | clears the axis |
-//! | axis storage | resolved enum → **the dword** (1239) | resolved enum | **the raw dword** | one dword |
-//!
-//! That is the seam class the addon-lane round trip named: halves transcribed separately from one
-//! law drift where they meet, while every test on every side still passes. **The EditBox column is
-//! the one that was right** — written last, straight from the bytes, and never consulted by the two
-//! older tables. So this module is not new law: it is that column, lifted to where all three reach
-//! it. It sits at the crate root rather than under `script` because `widget::kinds` needs it too.
-//!
-//! ## The law
-//!
-//! Storage is a single dword — `CSimpleFont+0x54`, `CSimpleFontString+0x120` — with **bits 0–2
-//! horizontal and bits 3–5 vertical**. `SetJustifyH 0x79fc20` computes `(cur ^ parsed) & 0x07 ^
-//! cur`, i.e. `(cur & !0x07) | (parsed & 0x07)`, replacing only its own axis (VERIFIED at
-//! `0x79fc5d`–`0x79fc64`); `SetJustifyV 0x79fce0` uses mask `0x38`. The ctor default is `0x212` =
-//! `CENTER | MIDDLE | 0x200`, bit 9 being outside both masks and read by neither accessor.
-//!
-//! Two consequences fall out of that arithmetic, and both are transcribed below:
-//!
-//! - **A cross-axis token is accepted and clears.** `SetJustifyH("TOP")` parses fine (`0x08`) but
-//!   `0x08 & 0x07 == 0`, so it erases the horizontal justification with **no error raised**, and a
-//!   following `GetJustifyH()` answers `"UNKNOWN"` — while the glyphs keep drawing **centred**.
-//!   The two readers genuinely disagree, which is why [`Justify`] stores the dword rather than a
-//!   resolved enum: [`Justify::name_h`] is the getter's answer and [`Justify::paint_h`] is the
-//!   draw path's, and they differ only in this state.
-//! - **A non-token raises.** `0x6f1990` scans all six entries with `SStrCmpI` — whole-string,
-//!   case-insensitive, **no trimming** — and returns 0 on a miss, which is the caller's cue to
-//!   raise `Usage: %s:SetJustifyH("justify")` (`.rdata 0x87c77c`) / `…SetJustifyV…`
-//!   (`0x87c7a0`). Per `script::binding_abi`, that arm does not return: it abandons the caller's
-//!   statement.
-//!
-//! Recorded in wow-re `system/ui/scratch/font-object-lua-surface.md` §9.4 and, for the
-//! fall-through and the unconditional inherit clear, `system/ui/scratch/justify-fallthrough-law.md`
-//! (§5 quad, arbitrated).
+//! The justify dword and its token table (`.rdata 0x811ad0`), shared by the `FontString`
+//! (`0x87c1d8`), `Font` (`0x87c7c8`) and `EditBox` method tables. Each setter replaces only its
+//! own axis, and also clears the inherit bit whether or not the value changed (`0x79fc7c`).
 
 use crate::script::{JustifyH, JustifyV};
 
-/// `.rdata 0x811ad0` — six `{u32 bits, const char* name}` entries, in image order. The order is
-/// load-bearing twice over: `0x6f1990` scans it linearly, and `0x6f1a00` answers with the **first**
-/// entry whose bit is set.
+/// `.rdata 0x811ad0`, six `{u32 bits, const char* name}` entries in image order. The order
+/// matters: `0x6f1990` scans linearly and `0x6f1a00` answers the first entry with its bit set.
 const TOKENS: [(u32, &str); 6] = [
     (0x01, "LEFT"),
     (0x02, "CENTER"),
@@ -64,43 +18,30 @@ const TOKENS: [(u32, &str); 6] = [
 /// The literal `0x6f1a00` answers when no bit in the requested axis is set (`.data 0x838044`).
 pub const UNKNOWN: &str = "UNKNOWN";
 
-/// The horizontal axis — bits 0–2, `SetJustifyH`'s mask.
+/// The horizontal axis, bits 0–2: the mask of `SetJustifyH 0x79fc20`.
 pub const H_MASK: u32 = 0x07;
-/// The vertical axis — bits 3–5, `SetJustifyV`'s mask.
+/// The vertical axis, bits 3–5: the mask of `SetJustifyV 0x79fce0`.
 pub const V_MASK: u32 = 0x38;
 
-/// What a justify argument turned out to be — the three outcomes of `0x6f1990` followed by the
-/// setter's mask.
+/// A justify argument after `0x6f1990` and the setter's mask.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum Set<J> {
-    /// A token carrying a bit on *this* axis: the new justification.
+    /// A token with a bit on this axis.
     To(J),
-    /// A token that matched the table but carries no bit on this axis — `SetJustifyH("TOP")`.
-    /// The reference **clears** the axis and raises nothing; `GetJustifyH()` then answers
-    /// `"UNKNOWN"` while the glyphs keep drawing centred ([`Justify::paint_h`]).
-    ///
-    /// Not hypothetical: 13 corpus sites call `SetJustifyV("CENTER")` meaning "middle"
-    /// (`FonzAppraiser` ×12, `Roid-Macros`), which parses and then erases the vertical axis.
+    /// A token with no bit on this axis (`SetJustifyH("TOP")`): the reference clears the axis and
+    /// raises nothing; corpus addons call `SetJustifyV("CENTER")` and hit this.
     Clears,
-    /// No entry matched. The caller raises its own `Usage:` string; it does not coerce.
+    /// No entry matched: the caller raises its `Usage:` string, never coerces.
     NoMatch,
 }
 
-/// The ctor default — `CENTER | MIDDLE | 0x200`. Bit 9 is outside both axis masks and is read by
-/// neither accessor nor the gx translator. `CSimpleFontString`'s **own** ctor writes it at
-/// `0x770dd3`, so a FontString that has never been told otherwise reads `CENTER`/`MIDDLE`.
+/// `CENTER | MIDDLE | 0x200`, as `CSimpleFontString`'s ctor writes it (`0x770dd3`); bit 9 is in
+/// neither axis and no reader looks at it.
 const CTOR_DEFAULT: u32 = 0x212;
 
-/// The justify **dword** — `CSimpleFont+0x54`, `CSimpleFontString+0x120`, `CSimpleEditBox`'s own —
-/// with bits 0–2 horizontal and bits 3–5 vertical.
-///
-/// Stored as the dword rather than a pair of resolved enums because **an axis with no bit set is a
-/// real, reachable state** and a resolved enum cannot hold it: `SetJustifyH("TOP")` parses `0x08`,
-/// contributes nothing to mask `0x07`, and erases the axis with no error raised.
-///
-/// The two readers then disagree, faithfully, and that is the whole reason this type exists:
-/// [`Justify::name_h`] (the Lua getter) answers `"UNKNOWN"`, while [`Justify::paint_h`] (the draw
-/// path) answers `CENTER`. Anything that collapses the two loses one of them.
+/// The justify dword (`CSimpleFont+0x54`, `CSimpleFontString+0x120`, `CSimpleEditBox`'s own),
+/// bits 0–2 horizontal and 3–5 vertical. Kept raw because an axis with no bit set is reachable,
+/// and there the getter answers `"UNKNOWN"` while the draw path centres.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct Justify(pub u32);
 
@@ -111,11 +52,9 @@ impl Default for Justify {
 }
 
 impl Justify {
-    /// Replace the horizontal bits — `(cur & !0x07) | (parsed & 0x07)`.
     pub fn set_h(&mut self, j: JustifyH) {
         self.0 = set_axis(self.0, H_MASK, bits_h(j));
     }
-    /// Replace the vertical bits — `(cur & !0x38) | (parsed & 0x38)`.
     pub fn set_v(&mut self, j: JustifyV) {
         self.0 = set_axis(self.0, V_MASK, bits_v(j));
     }
@@ -123,46 +62,36 @@ impl Justify {
     pub fn clear_h(&mut self) {
         self.0 = set_axis(self.0, H_MASK, 0);
     }
-    /// Erase the vertical axis.
     pub fn clear_v(&mut self) {
         self.0 = set_axis(self.0, V_MASK, 0);
     }
 
-    /// `GetJustifyH`'s answer — `0x6f1a00`, so `"UNKNOWN"` for a cleared axis.
+    /// `GetJustifyH`'s answer (`0x79e5f0`) through `0x6f1a00`: `"UNKNOWN"` for a cleared axis.
     pub fn name_h(self) -> &'static str {
         name_of(self.0, H_MASK)
     }
-    /// `GetJustifyV`'s answer.
+    /// `GetJustifyV`'s answer (`0x79e7f0`).
     pub fn name_v(self) -> &'static str {
         name_of(self.0, V_MASK)
     }
 
-    /// What the glyphs actually draw at horizontally — the ui→gx translator `0x44d420`, whose one
-    /// call site image-wide is `0x772693`.
-    ///
-    /// **It is a priority ladder, not a switch, and the fall-through is `CENTER` — not `LEFT`.**
-    /// Each axis's result register is pre-set to `1` *between* the `test` and the `jcc`
-    /// (`0x44d4fb mov ebx,0x1`, then `0x44d516 je`), so an all-clear axis exits with `1` still in
-    /// it, and `1` is bit-identical to CENTER. A cleared axis is therefore visually
-    /// indistinguishable from the ctor default.
-    ///
-    /// **The trap, quoted from the finding:** the gx layer's `else` arms genuinely *are* LEFT and
-    /// BOTTOM, but both are unreachable from a FontString — `0x44d420` emits only `{0,1,2}` and
-    /// `0x5c1c30` rejects `>= 3`. *Mapping the ui bitmask onto the gx enum with a `0` default
-    /// inverts both axes.*
+    /// Where the glyphs draw horizontally: the translator `0x44d420` (called only from
+    /// `0x772693`) is a ladder whose result is pre-set to `1`, CENTER (`0x44d4fb`, before the
+    /// `je` at `0x44d516`), so a cleared axis draws centred. The gx enum's `else` arms, LEFT and
+    /// BOTTOM, are unreachable (`0x44d420` emits only 0 to 2, `0x5c1c30` rejects 3 and up):
+    /// mapping the bitmask onto that enum with a `0` default inverts both axes.
     pub fn paint_h(self) -> JustifyH {
         if self.0 & 0x04 != 0 {
             JustifyH::Right
         } else if self.0 & 0x01 != 0 {
             JustifyH::Left
         } else {
-            JustifyH::Center // 0x02 set, or NOTHING set — the pre-set `1`
+            JustifyH::Center // 0x02 set, or no bit set: the pre-set `1`
         }
     }
 
-    /// What the glyphs draw at vertically — the same ladder, `TOP > BOTTOM > MIDDLE`, falling
-    /// through to `MIDDLE`. `0x44d536`'s redundant `mov esi,0x1` on the MIDDLE arm is MSVC's own
-    /// tell that `default:` and `MIDDLE` share a constant.
+    /// The same ladder vertically, `TOP > BOTTOM > MIDDLE`, falling through to MIDDLE
+    /// (`0x44d536`).
     pub fn paint_v(self) -> JustifyV {
         if self.0 & 0x08 != 0 {
             JustifyV::Top
@@ -190,8 +119,7 @@ fn bits_v(j: JustifyV) -> u32 {
     }
 }
 
-/// `0x6f1990` — a linear scan of all six entries with `SStrCmpI`: **whole-string,
-/// case-insensitive, and without trimming**, so `"left "` is a miss.
+/// `0x6f1990`: `SStrCmpI` over the six entries, whole-string and untrimmed, so `"left "` misses.
 pub fn parse_bits(s: &str) -> Option<u32> {
     TOKENS
         .iter()
@@ -199,7 +127,7 @@ pub fn parse_bits(s: &str) -> Option<u32> {
         .map(|(bits, _)| *bits)
 }
 
-/// `0x6f1a00` — the **first** entry whose bit is set within `mask`, else the literal `UNKNOWN`.
+/// `0x6f1a00`: the first entry whose bit is set within `mask`, else the literal `UNKNOWN`.
 pub fn name_of(bits: u32, mask: u32) -> &'static str {
     TOKENS
         .iter()
@@ -207,14 +135,13 @@ pub fn name_of(bits: u32, mask: u32) -> &'static str {
         .map_or(UNKNOWN, |(_, name)| *name)
 }
 
-/// Replace one axis's bits with `parsed`'s, masked to that axis — `0x79fc5d`'s
-/// `(cur ^ parsed) & mask ^ cur`, i.e. `(cur & !mask) | (parsed & mask)`. This is the operation
-/// that makes a cross-axis token *clear* rather than raise.
+/// The setters' `(cur ^ parsed) & mask ^ cur` (`SetJustifyH` at `0x79fc5d`–`0x79fc64`), which is
+/// why a cross-axis token clears rather than raises.
 pub fn set_axis(cur: u32, mask: u32, parsed: u32) -> u32 {
     (cur & !mask) | (parsed & mask)
 }
 
-/// `SetJustifyH`'s argument, resolved against mask `0x07`.
+/// `SetJustifyH`'s argument, against mask `0x07`.
 pub fn parse_h(s: &str) -> Set<JustifyH> {
     match parse_bits(s) {
         None => Set::NoMatch,
@@ -225,7 +152,7 @@ pub fn parse_h(s: &str) -> Set<JustifyH> {
     }
 }
 
-/// `SetJustifyV`'s argument, resolved against mask `0x38`.
+/// `SetJustifyV`'s argument, against mask `0x38`.
 pub fn parse_v(s: &str) -> Set<JustifyV> {
     match parse_bits(s) {
         None => Set::NoMatch,
@@ -236,18 +163,17 @@ pub fn parse_v(s: &str) -> Set<JustifyV> {
     }
 }
 
-/// `GetJustifyH`'s answer for a resolved horizontal justification, through the same table.
+/// `GetJustifyH`'s answer for a resolved justification.
 pub fn name_h(j: JustifyH) -> &'static str {
     name_of(bits_h(j), H_MASK)
 }
 
-/// `GetJustifyV`'s answer for a resolved vertical justification, through the same table.
 pub fn name_v(j: JustifyV) -> &'static str {
     name_of(bits_v(j), V_MASK)
 }
 
-/// The `Usage:` string `SetJustifyH` raises on a miss (`.rdata 0x87c77c`). The `%s` is spelled as
-/// the widget type, matching the shipped convention in `script::font_block`.
+/// The `Usage:` string `SetJustifyH` raises on a miss (`.rdata 0x87c77c`), the `%s` spelled as
+/// the widget type.
 pub fn usage_h(widget: &str) -> mlua::Error {
     mlua::Error::runtime(format!("Usage: <{widget}>:SetJustifyH(\"justify\")"))
 }
@@ -266,8 +192,7 @@ mod tests {
         assert_eq!(parse_h("LEFT"), Set::To(JustifyH::Left));
         assert_eq!(parse_h("left"), Set::To(JustifyH::Left));
         assert_eq!(parse_h("LeFt"), Set::To(JustifyH::Left));
-        // `SStrCmpI` compares the whole string; the client does not trim, and neither do we —
-        // the Font-object path used to, which is the divergence this module exists to end.
+        // `SStrCmpI` compares the whole string, untrimmed.
         assert_eq!(parse_h("left "), Set::NoMatch);
         assert_eq!(parse_h(" left"), Set::NoMatch);
         assert_eq!(parse_h("leftmost"), Set::NoMatch);
@@ -276,8 +201,6 @@ mod tests {
 
     #[test]
     fn an_unmatched_string_does_not_coerce_to_center() {
-        // The whole point of the raise: the reference tells the addon it passed nonsense, where we
-        // used to silently answer CENTER on both tables.
         assert_eq!(parse_h("MIDDLE_LEFT"), Set::NoMatch);
         assert_eq!(parse_v("CENTERED"), Set::NoMatch);
     }
@@ -304,15 +227,12 @@ mod tests {
 
     #[test]
     fn the_formatter_is_first_bit_set_within_the_axis_else_unknown() {
-        // `0x6f1a00`'s two documented edges, neither reachable through our resolved enums but both
-        // part of the law being transcribed: no bit in the axis answers the literal UNKNOWN, and a
-        // dword with two bits set answers the *first* table entry rather than the largest.
+        // `0x6f1a00`: no bit in the axis answers UNKNOWN, two bits answer the first table entry.
         assert_eq!(name_of(0x00, H_MASK), "UNKNOWN");
         assert_eq!(name_of(0x38, H_MASK), "UNKNOWN"); // vertical bits only
         assert_eq!(name_of(0x05, H_MASK), "LEFT"); // LEFT | RIGHT
         assert_eq!(name_of(0x30, V_MASK), "MIDDLE"); // MIDDLE | BOTTOM
-                                                     // The ctor default `0x212` reads CENTER/MIDDLE, and bit 9 is invisible to both axes.
-        assert_eq!(name_of(0x212, H_MASK), "CENTER");
+        assert_eq!(name_of(0x212, H_MASK), "CENTER"); // the ctor default; bit 9 is in no axis
         assert_eq!(name_of(0x212, V_MASK), "MIDDLE");
     }
 }
diff --git a/crates/benilla-ui/src/layout.rs b/crates/benilla-ui/src/layout.rs
index de84dcae..8c68f058 100644
--- a/crates/benilla-ui/src/layout.rs
+++ b/crates/benilla-ui/src/layout.rs
@@ -1,69 +1,37 @@
-//! The frame anchor/layout resolver — anchor graph → resolved rects (decision 0068).
+//! The frame anchor resolver: the 1.12 client's `CLayoutFrame` rect resolution, transcribed
+//! function by function, with the reference's operations in the reference's order.
 //!
-//! This is a faithful transcription of the WoW 1.12.1 client's `CLayoutFrame` geometry resolver,
-//! whose math is reverse-engineered bit-exact against `WoW.exe` in the sibling repo `wow-5875-re`
-//! (`system/ui/scratch/layout.md`, `.../rf32-composed-resolver.md`, `.../frame-model.md`,
-//! `.../propagation.md`). The leaf float kernels and the recursion-guarded per-edge composition are
-//! transcribed from that repo's own verified `w5875-ui::layout` crate
-//! (`wow-5875-re/crates/ui/src/layout.rs`), which is gated bit-exact under a Unicorn/`WoW.exe`
-//! difftest harness (per-function diffs + the composed `assemble` over 6006 synthesized cases).
-//! Matching that crate's operations and their order — not "improving" the arithmetic — is the goal.
+//! The client computes on the x87 at 53-bit precision, which `f64` matches, and narrows to `f32`
+//! only at its stores (each sub-edge before a `combine_*`, each final edge, the `width * scale`
+//! span), so the arithmetic here runs in `f64` with an explicit `as f32` at exactly those sites.
 //!
-//! ## Precision — why `f64` intermediates, not naive `f32`
-//!
-//! The client is an x87 binary: every intermediate lives in an FPU register at PC_53 (53-bit
-//! mantissa = IEEE `f64` precision) and is narrowed to `f32` *only* at the documented `fstp m32`
-//! store sites (each sub-edge result before a `combine_*`; each final edge into the out-rect; the
-//! `width·scale` span). A leaf like `(right + left) * 0.5 + xOff·scale` therefore rounds **once**
-//! (at the final store), whereas doing every operation in `f32` would round at each step and
-//! diverge. So "the client is f32" is true only at the storage boundaries: to be bit-faithful the
-//! chain of `+`/`-`/`*0.5` runs in `f64` (host-exact — every operand is `f32`-derived, so each op is
-//! exact in `f64`) with an explicit `as f32` at exactly the sites the RE pins. This mirrors
-//! `w5875-ui::layout` verbatim.
-//!
-//! ## Coordinate space
-//!
-//! Rects are stored in the client's own convention: `[bottom, left, top, right]` (frame-absolute
-//! `+0x64/+0x68/+0x6c/+0x70`; VERIFIED via `GetRect 0x768320` + the Lua `GetBottom/Left/Top/Right`
-//! readers, `layout.md`). WoW UI space is **y-up**: `top > bottom`, the screen root's rect is the
-//! physical screen (the anchor chain bottoms out at the `CSimpleTop` root), and `width = right −
-//! left`, `height = top − bottom`. Coordinates are screen pixels throughout; `scale` (layoutScale =
-//! effective scale, `propagation.md`) scales only the per-anchor offsets and the `width/height` span.
+//! Rects are `[bottom, left, top, right]` (frame `+0x64..+0x70`, `GetRect` `0x768320`) in screen
+//! pixels, y-up.
 
 use std::collections::VecDeque;
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Constants (objdump-VERIFIED in layout.md "Constants")
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Constants ────────────────────────────────────────────────────────────────────────────────
 
-/// UNSET coordinate sentinel: `+Infinity` (the `.data` slot `0xcf550c`, runtime-initialized from
-/// `[0x81d56c] = 0x7f800000`, `layout.md`). "coordinate is set" ⇔ `x != +Inf`. Intermediates carry
-/// this in `f64`; the `f32` narrowing preserves it (`+Inf as f32 == +Inf`).
+/// The unset-coordinate sentinel, `+Inf` (`0xcf550c`, set at runtime from `0x81d56c`).
 const UNSET: f64 = f64::INFINITY;
 
-/// `OnSizeChanged` trigger ε — `_DAT_008029d4` = `0x34800000` ≈ 2.384e-7 (`layout.md` Constants;
-/// applied in `ApplyRect 0x76b580`). `OnSizeChanged(width,height)` fires iff `|Δwidth| ≥ ε` OR
-/// `|Δheight| ≥ ε` between the old and new resolved rect. See [`size_changed`].
+/// The least width or height change that fires `OnSizeChanged`: 2^-22, bits `0x34800000` at
+/// `0x8029d4`, tested in `ApplyRect` (`0x76b580`).
 pub const SIZE_EPS: f64 = 2.384_185_791_015_625e-7;
 
-/// Recompute change threshold ε — `_DAT_0080c5c8` = `0x3727c5ac` ≈ 9.96e-6 (`layout.md`; applied in
-/// `recompute 0x768d20`): an edge must move at least this far vs the cached rect for a re-store +
-/// `ApplyRect`. Benilla owns its own caching (the caller's dirty gate); this const records the client's
-/// documented threshold for fidelity work that needs it.
+/// The least edge move against the cached rect for the client to re-store it and `ApplyRect`, 1e-5
+/// (`0x80c5c8`, in `0x768d20`). Recorded, not applied: the caller's own dirty gate decides.
 pub const RESOLVE_EPS: f64 = f32::from_bits(0x3727_c5ac) as f64;
 
-/// point-id → X column (VERIFIED table `0x81c3b8`.., `layout.md` "Point-id → coordinate"):
-/// `{0,3,6}` (LEFT column) → 0, `{1,4,7}` (center) → 1, `{2,5,8}` (RIGHT column) → 2.
+/// Point id to X column: left 0, center 1, right 2.
 const X_COL: [u8; 9] = [0, 1, 2, 0, 1, 2, 0, 1, 2];
-/// point-id → Y row: `{0,1,2}` (TOP row) → 0, `{3,4,5}` (center) → 1, `{6,7,8}` (BOTTOM row) → 2.
+/// Point id to Y row: top 0, center 1, bottom 2.
 const Y_ROW: [u8; 9] = [0, 0, 0, 1, 1, 1, 2, 2, 2];
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Public types
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Public types ─────────────────────────────────────────────────────────────────────────────
 
-/// The nine anchor points, with the client's exact discriminants (VERIFIED static tables
-/// `0x81c3b8–0x81c3fc`, `layout.md`): the id is the slot index in the client's `anchorPoints[9]`.
+/// The nine anchor points; the discriminant is the client's point id, the slot in its
+/// `anchorPoints[9]` (tables at `0x81c3b8..0x81c3fc`).
 #[repr(u8)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum Point {
@@ -79,13 +47,11 @@ pub enum Point {
 }
 
 impl Point {
-    /// The point-id (0..=8), which is also the `anchorPoints[9]` slot index.
     #[inline]
     pub const fn id(self) -> u8 {
         self as u8
     }
 
-    /// Build a [`Point`] from its client id, `None` if out of range.
     pub const fn from_id(id: u8) -> Option<Point> {
         Some(match id {
             0 => Point::TopLeft,
@@ -102,11 +68,10 @@ impl Point {
     }
 }
 
-/// An opaque handle to an anchor target. This crate does not own the frame arena; the caller maps
-/// handles to frames / external rects. (In the client this is the `CAnchor+0xc relativeTo` pointer.)
+/// An anchor target, which the caller maps to a frame or an external rect (`CAnchor+0xc`).
 pub type Handle = u32;
 
-/// A resolved rect in the client's `[bottom, left, top, right]` convention (screen pixels, y-up).
+/// A resolved rect, `[bottom, left, top, right]` in screen pixels, y-up.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Rect {
     pub bottom: f32,
@@ -116,7 +81,6 @@ pub struct Rect {
 }
 
 impl Rect {
-    /// Construct from the four edges in client order.
     pub const fn new(bottom: f32, left: f32, top: f32, right: f32) -> Rect {
         Rect {
             bottom,
@@ -126,50 +90,39 @@ impl Rect {
         }
     }
 
-    /// `[bottom, left, top, right]` — the client's cached-rect layout (`+0x64..0x70`).
     #[inline]
     pub const fn to_array(self) -> [f32; 4] {
         [self.bottom, self.left, self.top, self.right]
     }
 
-    /// From `[bottom, left, top, right]`.
     #[inline]
     pub const fn from_array(a: [f32; 4]) -> Rect {
         Rect::new(a[0], a[1], a[2], a[3])
     }
 
-    /// `right − left` (`GetWidth` semantics, `layout.md`).
     #[inline]
     pub fn width(self) -> f32 {
         self.right - self.left
     }
 
-    /// `top − bottom` (`GetHeight` semantics; y-up).
     #[inline]
     pub fn height(self) -> f32 {
         self.top - self.bottom
     }
 }
 
-/// One anchor of a frame — a `CAnchor` record (`{xOff@4, yOff@8, relativeTo@0xc, relativePoint@0x10}`,
-/// `frame-model.md`). `point` is the point *on this frame* being pinned (its `anchorPoints[9]` slot);
-/// `relative_point` is the point *on the target* it pins to.
+/// One anchor, a client `CAnchor` (`xOff +4`, `yOff +8`, `relativeTo +0xc`, `relativePoint +0x10`):
+/// `point` on this frame pins to `relative_point` on the target.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Anchor {
-    /// The point on *this* frame that is being anchored (its `anchorPoints[9]` slot index).
     pub point: Point,
-    /// The target frame/region this anchor is relative to (`CAnchor+0xc`).
     pub relative_to: Handle,
-    /// The point on the *target* this anchor pins to (`CAnchor+0x10 relativePoint`).
     pub relative_point: Point,
-    /// X offset (`CAnchor+4`), scaled by the requesting frame's `scale`.
     pub x_off: f32,
-    /// Y offset (`CAnchor+8`), scaled by `scale`.
     pub y_off: f32,
 }
 
 impl Anchor {
-    /// Convenience constructor.
     pub fn new(
         point: Point,
         relative_to: Handle,
@@ -187,28 +140,24 @@ impl Anchor {
     }
 }
 
-/// A frame's full layout input: its anchors, its optional explicit size, its scale, and the
-/// clamp-to-screen flag + extents. Mirrors the client's geometry subobject fields consulted by the
-/// resolver (`frame-model.md`, `rf32-composed-resolver.md`): `anchorPoints[9]` (`G+0x28`), `width`
-/// (`G+0x50`), `height` (`G+0x54`), `layoutScale` (`G+0x58`), flags bit4 = clamp (`G+0x3c`).
+/// A frame's layout input, the geometry fields the client's resolver reads: `anchorPoints[9]`
+/// (`G+0x4`), `width` (`G+0x50`), `height` (`G+0x54`), `layoutScale` (`G+0x58`) and the clamp flag
+/// (bit 4 of `G+0x3c`).
 #[derive(Clone, Debug, PartialEq)]
 pub struct LayoutInput {
-    /// The frame's anchors. Placed into the nine `anchorPoints` slots by their `point`; if two share
-    /// a `point`, the *last* wins (the client's `SetPoint 0x767c70` overwrites the slot).
+    /// Slotted by `point`, the later of two on one point winning (`SetPoint`, `0x767c70`).
     pub anchors: Vec<Anchor>,
-    /// Explicit width (`G+0x50`); **`0.0` ⇒ derive from opposing anchors** (the no-explicit-size
-    /// sentinel `DAT_007ffd74`, `layout.md`).
+    /// `0.0` is the no-size sentinel (`0x7ffd74`): the axis derives from the anchors.
     pub width: f32,
-    /// Explicit height (`G+0x54`); `0.0` ⇒ derive from opposing anchors.
     pub height: f32,
-    /// `layoutScale` = effective scale (`parentScale · ownScale`, ε-gated, `propagation.md`); the
-    /// px↔coord multiplier applied to offsets and the size span. Default `1.0`.
+    /// The effective scale, parent times own (`0x76ac90`), applied only to the anchor offsets and
+    /// the size span.
     pub scale: f32,
-    /// Clamp the assembled rect into `[0, extent]` per axis (`G` flags bit4, `layout.md` Assemble).
+    /// Clamp the rect into `[0, extent]` on each axis.
     pub clamp: bool,
-    /// Screen X extent, only consulted when `clamp` (client `0x41ae60` return, default `0.8`).
+    /// The clamp's X extent; the client's default is `0.8` (`0x41ae60`).
     pub extent_x: f32,
-    /// Screen Y extent, only consulted when `clamp` (client `0x41ae70` return, default `0.6`).
+    /// The clamp's Y extent; the client's default is `0.6` (`0x41ae70`).
     pub extent_y: f32,
 }
 
@@ -238,32 +187,18 @@ impl LayoutInput {
     }
 }
 
-/// The outcome of resolving one frame's rect.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ResolveOutcome {
-    /// Every edge resolved → the cached rect `[bottom, left, top, right]` (`assemble` returned 1).
     Resolved(Rect),
-    /// At least one edge stayed `+Inf` — under-constrained (`assemble 0x767a20` returns 0, caller
-    /// sets flags bit3 "resolution-failed").
+    /// An edge stayed `+Inf`: the client's `assemble` returns 0 and its caller sets flags bit 3.
     Unresolvable,
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Leaf float kernels — the owned-fidelity math (layout.md). Transcribed from w5875-ui::layout,
-// binary-diffed. Each returns its coordinate in `f64` (the un-narrowed x87 `st0` observable);
-// callers narrow to `f32` at the documented store sites.
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Leaf kernels: each returns the un-narrowed `f64` ─────────────────────────────────────────
 
-/// `combineEdge 0x767440(center, opp, span)` (`layout.md`): resolve one edge from the opposite
-/// edge, the axis center, and the signed `size·scale` span, in that fallback order.
-///
-/// - opposite known and non-zero span → `opp + span` (edge = opposite ± size·scale);
-/// - else center known: non-zero span → `span·0.5 + center` (edge = center ± half-size);
-///   else opposite known → `(center − opp) + center` (= 2·center − opposite, the mirror);
-/// - else → `+Inf` (unresolvable).
-///
-/// The `+Inf`/`0.0` sentinels are compared with IEEE equality, matching the binary's `fcomp`
-/// against the `.data` slots (a NaN operand is unordered ⇒ "not equal to the sentinel").
+/// `combineEdge` (`0x767440`): an edge from the opposite edge and the signed `size * scale` span,
+/// else from the axis center. The sentinels compare by IEEE equality, as the client's `fcomp`
+/// does, so a NaN never matches one.
 #[allow(clippy::float_cmp)]
 pub fn combine_edge(center: f32, opp: f32, span: f32) -> f64 {
     let (c, o, s) = (f64::from(center), f64::from(opp), f64::from(span));
@@ -281,12 +216,7 @@ pub fn combine_edge(center: f32, opp: f32, span: f32) -> f64 {
     UNSET
 }
 
-/// `combineCenter 0x7672d0(lo, hi, span)` (`layout.md`): resolve an axis center from the low edge,
-/// the high edge, and the signed `size·scale` span.
-///
-/// - low known: high known → `(lo+hi)·0.5`; else non-zero span → `span·0.5 + lo`;
-/// - else high known and non-zero span → `hi − span·0.5`;
-/// - else → `+Inf`.
+/// `combineCenter` (`0x7672d0`): an axis center from the low and high edges and the signed span.
 #[allow(clippy::float_cmp)]
 pub fn combine_center(lo: f32, hi: f32, span: f32) -> f64 {
     let (l, h, s) = (f64::from(lo), f64::from(hi), f64::from(span));
@@ -304,16 +234,9 @@ pub fn combine_center(lo: f32, hi: f32, span: f32) -> f64 {
     UNSET
 }
 
-/// `CAnchor::ResolveX 0x7a2f90(scale)` (`layout.md`): resolve this anchor's X coordinate against its
-/// `relativeTo`'s cached rect.
-///
-/// `rect` = the target's cached rect `[bottom, left, top, right]` when `GetRect` succeeded (cache
-/// valid), `None` when it failed ⇒ `+Inf`. `mirror` = the target's geometry-vtable `+0x24`
-/// normalize predicate (RTL/local-origin): when set, X edges are translated so `left → 0`,
-/// `right → right − left` (each stored back as `f32`, the binary's `fstp m32`). For an ordinary
-/// frame the predicate returns 0, so `mirror` is `false` (VERIFIED `0x46ff60 = xor eax,eax; ret`,
-/// `rf32-composed-resolver.md`). `coord = xOff·scale + edge` for the relativePoint's column
-/// (center = mid-X + xOff·scale). `rel_point > 8` ⇒ `+Inf`.
+/// `CAnchor::ResolveX` (`0x7a2f90`): the anchor's X against its target's cached `rect`, which is
+/// `None` when `GetRect` fails. `mirror` is the target's normalize predicate (vtable `+0x24`, 0 for
+/// an ordinary frame at `0x46ff60`), which shifts the edges to start at 0, each stored as `f32`.
 pub fn anchor_resolve_x(
     scale: f32,
     x_off: f32,
@@ -340,9 +263,7 @@ pub fn anchor_resolve_x(
     }
 }
 
-/// `CAnchor::ResolveY 0x7a3070(scale)` — the Y twin of [`anchor_resolve_x`] (`layout.md`). `mirror`
-/// normalizes the Y edges (`bottom → 0`, `top → top − bottom`); `coord = yOff·scale + edge` for the
-/// relativePoint's row (center = mid-Y + yOff·scale). `rect` = `[bottom, left, top, right]`.
+/// `CAnchor::ResolveY` (`0x7a3070`), the Y counterpart of [`anchor_resolve_x`].
 pub fn anchor_resolve_y(
     scale: f32,
     y_off: f32,
@@ -369,21 +290,16 @@ pub fn anchor_resolve_y(
     }
 }
 
-/// The assembled (and possibly clamped) rect + whether every edge resolved.
+/// [`assemble_rect`]'s result: `ok` when every edge resolved.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct AssembleRect {
     pub ok: bool,
-    /// `[bottom, left, top, right]` (meaningful only when `ok`).
+    /// `[bottom, left, top, right]`, meaningful only when `ok`.
     pub rect: [f32; 4],
 }
 
-/// `assemble 0x767a20` (`layout.md`): given the four resolved edge coordinates `[bottom, left, top,
-/// right]` (each `+Inf` ⇒ unresolvable), fail if any is `+Inf`; else optionally clamp into
-/// `[0, extent]` per axis.
-///
-/// Clamp (geom flags bit4): a low edge `< 0` shifts to 0 carrying the span to the high edge; a high
-/// edge past the screen extent shifts back carrying to the low edge, high edge = extent. Each store
-/// is narrowed to `f32`.
+/// `assemble` (`0x767a20`): fails if any edge is `+Inf`, else with `clamp` (flags bit 4) shifts
+/// the rect into `[0, extent]` on each axis, low edge first, keeping its size.
 #[allow(clippy::float_cmp)]
 pub fn assemble_rect(edges: [f32; 4], clamp: bool, extent_x: f32, extent_y: f32) -> AssembleRect {
     let [mut bottom, mut left, mut top, mut right] = edges;
@@ -420,9 +336,8 @@ pub fn assemble_rect(edges: [f32; 4], clamp: bool, extent_x: f32, extent_y: f32)
     }
 }
 
-/// `OnSizeChanged` fire test (`ApplyRect 0x76b580`, `layout.md`): fires iff `|Δwidth| ≥ [`SIZE_EPS`]`
-/// OR `|Δheight| ≥ SIZE_EPS`, with `width = right − left`, `height = top − bottom`. Deltas are `f64`
-/// of the `f32` edges (the binary's `fsub` of the `fld`'d rect components).
+/// `ApplyRect`'s `OnSizeChanged` test (`0x76b580`): width or height moved by at least
+/// [`SIZE_EPS`], the deltas taken in `f64` from the `f32` edges.
 pub fn size_changed(old: Rect, new: Rect) -> bool {
     let dw =
         (f64::from(new.right) - f64::from(new.left)) - (f64::from(old.right) - f64::from(old.left));
@@ -431,15 +346,9 @@ pub fn size_changed(old: Rect, new: Rect) -> bool {
     dw.abs() >= SIZE_EPS || dh.abs() >= SIZE_EPS
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The composed resolver — recursion-guarded per-edge sequencing over the leaves above.
-// Transcribed from w5875-ui::layout (RF-0032, rf32-composed-resolver.md): bit-exact over the
-// binary's `assemble 0x767a20` → six per-edge resolvers → anchor scans → leaf kernels. Adds NO new
-// arithmetic — only integer control flow + the documented `fstp m32` `f32` narrowing at each site.
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The composed resolver: `assemble` over six recursion-guarded edge resolvers ──────────────
 
-/// A resolved anchor for the internal edge tree: like [`Anchor`] but with the target's rect already
-/// looked up (`None` ⇒ target had no valid rect ⇒ `GetRect`-fail leg).
+/// An [`Anchor`] with its target's rect looked up, `None` where `GetRect` would fail.
 #[derive(Clone, Copy)]
 struct AnchorRel {
     x_off: f32,
@@ -449,8 +358,6 @@ struct AnchorRel {
     mirror: bool,
 }
 
-/// Internal per-edge resolver input: the nine `anchorPoints` slots (by point-id) with rects
-/// resolved, plus the size/scale/clamp fields.
 struct EdgeInput {
     anchors: [Option<AnchorRel>; 9],
     width: f32,
@@ -461,7 +368,7 @@ struct EdgeInput {
     extent_y: f32,
 }
 
-// recursion-guard bits (the binary's `G+0x28` bitfield, layout.md).
+// The recursion-guard bits of the client's `G+0x28`.
 const G_LEFT: u32 = 0x01;
 const G_TOP: u32 = 0x02;
 const G_RIGHT: u32 = 0x04;
@@ -469,7 +376,7 @@ const G_BOTTOM: u32 = 0x08;
 const G_XC: u32 = 0x10;
 const G_YC: u32 = 0x20;
 
-// per-edge point-id scan tables (`.rdata` 0x81c3b8..0x81c3f4, rf32-composed-resolver.md).
+// The point ids each edge scans (`.rdata` 0x81c3b8..0x81c3f4).
 const IDS_LEFT: [usize; 3] = [0, 3, 6];
 const IDS_RIGHT: [usize; 3] = [2, 5, 8];
 const IDS_TOP: [usize; 3] = [0, 1, 2];
@@ -477,8 +384,7 @@ const IDS_BOTTOM: [usize; 3] = [6, 7, 8];
 const IDS_XC: [usize; 3] = [1, 4, 7];
 const IDS_YC: [usize; 3] = [3, 4, 5];
 
-/// `anchorScanX 0x7671a0`: over the edge's three point-ids, the first present anchor whose
-/// `ResolveX` is non-`+Inf` wins; else `+Inf`.
+/// `anchorScanX` (`0x7671a0`): the first of the edge's anchors whose X resolves, else `+Inf`.
 #[allow(clippy::float_cmp)]
 fn anchor_scan_x(ids: &[usize; 3], f: &EdgeInput) -> f64 {
     for &id in ids {
@@ -492,7 +398,7 @@ fn anchor_scan_x(ids: &[usize; 3], f: &EdgeInput) -> f64 {
     UNSET
 }
 
-/// `anchorScanY 0x7671f0` — the Y twin.
+/// `anchorScanY` (`0x7671f0`).
 #[allow(clippy::float_cmp)]
 fn anchor_scan_y(ids: &[usize; 3], f: &EdgeInput) -> f64 {
     for &id in ids {
@@ -506,18 +412,10 @@ fn anchor_scan_y(ids: &[usize; 3], f: &EdgeInput) -> f64 {
     UNSET
 }
 
-/// `width·scale` / `height·scale` — the `layout_767_span` PRIMITIVE (`rf32-composed-resolver.md`):
-/// operands are `f32` fields, the product narrowed to `f32` at the `fstp [esp]` site, negated for
-/// LEFT/BOTTOM.
-///
-/// **`size` is not always the authored field, and this is the trap** (decision 1349, wow-re
-/// `region-size-fallback.md`): each caller's `call [eax+0x1c]` is **virtual**. A plain frame lands on
-/// `0x768420 fld [G+0x50]` — the flat read this signature assumes — but a `CSimpleTexture` lands on
-/// `0x770720` and a `CSimpleFontString` on `0x772930`, both of which substitute a **content-derived**
-/// extent when the authored value is exactly `0.0` (the texture's own texel size, one texel per
-/// FrameXML unit; the string's measured text, floored at one unit). benilla feeds this the authored
-/// number only, so a zero-authored *texture* axis yields a zero span here where the client yields a
-/// real one. 1349 §4 carries the change and its scope; do not read this kernel as the whole law.
+/// The edge resolvers' span, `size * scale` narrowed to `f32`, negated for LEFT and BOTTOM. The
+/// client reads `size` through a virtual getter: a frame's is the authored field (`0x768420`), but
+/// a texture (`0x770720`) and a font string (`0x772930`) replace an authored `0.0` with their
+/// content's extent, so a region's [`LayoutInput`] must already carry that extent.
 fn size_span(size: f32, scale: f32, negate: bool) -> f32 {
     let span = (f64::from(size) * f64::from(scale)) as f32;
     if negate {
@@ -527,7 +425,7 @@ fn size_span(size: f32, scale: f32, negate: bool) -> f32 {
     }
 }
 
-/// `LEFT 0x7673d0` — direct anchor scan, else `combineEdge(Xcenter, RIGHT, −width·scale)`.
+/// LEFT (`0x7673d0`): its anchor scan, else `combineEdge(Xcenter, RIGHT, -width * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_left(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_LEFT != 0 {
@@ -547,7 +445,7 @@ fn resolve_left(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `RIGHT 0x767540` — direct anchor scan, else `combineEdge(Xcenter, LEFT, +width·scale)`.
+/// RIGHT (`0x767540`): its anchor scan, else `combineEdge(Xcenter, LEFT, width * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_right(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_RIGHT != 0 {
@@ -567,7 +465,7 @@ fn resolve_right(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `TOP 0x7674d0` — direct anchor scan, else `combineEdge(Ycenter, BOTTOM, +height·scale)`.
+/// TOP (`0x7674d0`): its anchor scan, else `combineEdge(Ycenter, BOTTOM, height * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_top(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_TOP != 0 {
@@ -587,7 +485,7 @@ fn resolve_top(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `BOTTOM 0x7675b0` — direct anchor scan, else `combineEdge(Ycenter, TOP, −height·scale)`.
+/// BOTTOM (`0x7675b0`): its anchor scan, else `combineEdge(Ycenter, TOP, -height * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_bottom(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_BOTTOM != 0 {
@@ -607,7 +505,7 @@ fn resolve_bottom(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `Xcenter 0x767260` — direct anchor scan, else `combineCenter(LEFT, RIGHT, +width·scale)`.
+/// Xcenter (`0x767260`): its anchor scan, else `combineCenter(LEFT, RIGHT, width * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_xcenter(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_XC != 0 {
@@ -627,7 +525,7 @@ fn resolve_xcenter(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `Ycenter 0x767360` — direct anchor scan, else `combineCenter(BOTTOM, TOP, +height·scale)`.
+/// Ycenter (`0x767360`): its anchor scan, else `combineCenter(BOTTOM, TOP, height * scale)`.
 #[allow(clippy::float_cmp)]
 fn resolve_ycenter(f: &EdgeInput, guard: &mut u32) -> f64 {
     if *guard & G_YC != 0 {
@@ -647,12 +545,8 @@ fn resolve_ycenter(f: &EdgeInput, guard: &mut u32) -> f64 {
     r
 }
 
-/// `assemble 0x767a20` composed: resolve all four edges (each `fst`'d to the `f32` out-rect),
-/// returning [`ResolveOutcome::Unresolvable`] if any stayed `+Inf`, else the assembled (and, when
-/// `clamp`, screen-clamped) rect. The four top-level resolves share a fresh guard; the binary
-/// clears each edge's bit on return, so order is immaterial — we keep the binary's LEFT→BOTTOM→
-/// RIGHT→TOP order. The `+Inf` test is on the un-narrowed `f64` edge (the binary's `fcomp` before
-/// the `fst`).
+/// `assemble` (`0x767a20`) composed, resolving LEFT, BOTTOM, RIGHT, TOP in the client's order; the
+/// `+Inf` test reads the un-narrowed `f64` edge, as the client's `fcomp` precedes its `fst`.
 #[allow(clippy::float_cmp)]
 fn resolve_edges(f: &EdgeInput) -> ResolveOutcome {
     let mut guard = 0u32;
@@ -668,13 +562,8 @@ fn resolve_edges(f: &EdgeInput) -> ResolveOutcome {
     ResolveOutcome::Resolved(Rect::from_array(a.rect))
 }
 
-/// Resolve one frame's rect. `target_rect` supplies each anchor target's already-resolved rect
-/// (`None` ⇒ the target has no valid rect ⇒ that anchor contributes `+Inf`, the `GetRect`-fail
-/// leg). Anchors are placed into the nine `anchorPoints` slots by their `point`; on a duplicate the
-/// later anchor wins (the client's `SetPoint` overwrite).
-///
-/// This is the fidelity surface: it builds the client's `anchorPoints[9]` view and runs the
-/// verified composed `assemble` (`rf32-composed-resolver.md`).
+/// Resolve one frame's rect; `target_rect` gives each anchor target's resolved rect, and `None`
+/// makes that anchor `+Inf`, as a failed `GetRect` does.
 pub fn resolve_rect(
     frame: &LayoutInput,
     target_rect: impl FnMut(Handle) -> Option<Rect>,
@@ -682,9 +571,6 @@ pub fn resolve_rect(
     resolve_edges(&build_edge_input(frame, target_rect))
 }
 
-/// Build the client's `anchorPoints[9]` view + size/scale/clamp fields for `frame`, resolving each
-/// anchor target's rect through `target_rect`. Shared by [`resolve_rect`] (all-or-nothing) and
-/// [`resolve_rect_edges`] (per-edge).
 fn build_edge_input(
     frame: &LayoutInput,
     mut target_rect: impl FnMut(Handle) -> Option<Rect>,
@@ -696,8 +582,7 @@ fn build_edge_input(
             y_off: a.y_off,
             rel_point: a.relative_point.id() as u32,
             rel_rect: target_rect(a.relative_to).map(Rect::to_array),
-            // Ordinary frames' normalize predicate returns 0 (rf32-composed-resolver.md); RTL/mirror
-            // frames are not modeled here (the leaf `anchor_resolve_*` covers that leg).
+            // An ordinary frame's normalize predicate returns 0 (`0x46ff60`).
             mirror: false,
         });
     }
@@ -712,12 +597,8 @@ fn build_edge_input(
     }
 }
 
-/// Resolve one frame's four edges, returning each as `Some(edge)` when the anchor graph + explicit
-/// size determined it, or `None` when it stayed `+Inf` (unset). The per-edge view **regions** need:
-/// a region inherits any edge its anchors + size don't pin from its owner frame (decision 0068's v1
-/// region model — see [`crate::script`]'s region resolution), so it must see *which* edges resolved,
-/// not the all-or-nothing verdict [`resolve_rect`] gives. Order matches [`Rect`]: `[bottom, left,
-/// top, right]`. No `assemble`/clamp is applied (regions never clamp to screen in v1).
+/// Resolve one frame's edges, `[bottom, left, top, right]`, each `None` where it stayed unset;
+/// `assemble` and its clamp are not applied. The region pass reads it axis by axis.
 #[allow(clippy::float_cmp)]
 pub fn resolve_rect_edges(
     frame: &LayoutInput,
@@ -733,55 +614,27 @@ pub fn resolve_rect_edges(
     [cvt(bottom), cvt(left), cvt(top), cvt(right)]
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Graph driver — resolve a set of frames in dependency order (anchor targets before dependents),
-// detecting cycles. This is benilla's orchestration, not client fidelity math: the client resolves
-// lazily-on-read + per-frame-batched via a dependency-ordered deferred queue (layout.md "Resolve /
-// dirty / cache flow"); we express the same dependency ordering as an explicit topological pass.
-//
-// ## Why a dense, reusable solver rather than a fresh map-backed graph
-//
-// The caller re-solves the whole widget set every round of its fixpoint, and the fixpoint runs
-// every frame. A map-backed graph rebuilt per round paid, per round: one `LayoutInput` clone
-// (heap `Vec<Anchor>`) per frame, a `BTreeMap` insert per node, and a `BTreeMap` probe per anchor
-// target during the solve. Measured on the shipped default UI (1881 frames + 5478 regions,
-// release): 1.36 ms per resolve, of which ~0.25 ms was graph construction and ~0.64 ms the solve
-// itself — paid on a completely quiet frame.
-//
-// [`Handle`]s are the caller's own dense id space (benilla's `Model::next_id`, monotonic from 1
-// with frames and regions sharing the counter), so every per-node map collapses to an array index
-// and every buffer can live across calls. `begin` clears only the slots the previous round
-// touched, so a round costs O(nodes), never O(id space). Iteration order is kept **ascending by
-// handle** — identical to the `BTreeMap` it replaces — because cycle members are resolved
-// best-effort in that order and the result depends on it.
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Graph driver ─────────────────────────────────────────────────────────────────────────────
 
-/// A reusable dependency solver over a set of anchored frames plus *external* pre-resolved rects
-/// (the screen root — the client's `CSimpleTop`, whose rect is the physical screen — and any fixed
-/// targets, such as already-resolved regions).
-///
-/// One solver is kept alive across frames so its buffers are reused. A round is:
-/// [`begin`](Self::begin) → [`set_external`](Self::set_external) /
-/// [`set_frame`](Self::set_frame) → [`solve`](Self::solve) → [`rect`](Self::rect).
+/// Resolves anchored frames in dependency order, a driver of benilla's own: the client resolves
+/// lazily through a dependency-ordered deferred queue (`0x7680e0`, ordered by `0x7681b0`). Handles
+/// index its arrays directly, so they must be dense. A round: [`begin`](Self::begin),
+/// [`set_external`](Self::set_external) and [`set_frame`](Self::set_frame), [`solve`](Self::solve).
 #[derive(Clone, Debug, Default)]
 pub struct LayoutSolver {
-    /// Per-handle layout input. Persistent storage: [`set_frame`](Self::set_frame) overwrites in
-    /// place so the anchors `Vec` keeps its allocation across rounds.
+    /// Overwritten in place, so each anchors `Vec` keeps its allocation.
     input: Vec<LayoutInput>,
-    /// Is `input[h]` a frame to solve this round?
     is_frame: Vec<bool>,
-    /// Per-handle rect: externals as seeded, frames as they resolve. `None` = not (yet) known.
+    /// Externals as seeded, frames as they resolve.
     rect: Vec<Option<Rect>>,
-    /// Kahn in-degree, and the reverse edges (each inner `Vec` is cleared, never freed).
+    /// Kahn in-degree and reverse edges; each inner `Vec` is cleared, never freed.
     indeg: Vec<u32>,
     dependents: Vec<Vec<Handle>>,
-    /// Handles whose slots were written this round — `begin` resets exactly these.
+    /// The handles written this round, the ones `begin` resets.
     touched: Vec<Handle>,
-    /// Is `h` already in `touched`?
     marked: Vec<bool>,
-    /// The frames to solve, ascending (the `BTreeMap` iteration order this replaces).
+    /// Ascending: cycle members resolve in this order, and the result depends on it.
     live: Vec<Handle>,
-    /// Kahn scratch + output.
     queue: VecDeque<Handle>,
     emitted: Vec<bool>,
     order: Vec<Handle>,
@@ -790,12 +643,10 @@ pub struct LayoutSolver {
 }
 
 impl LayoutSolver {
-    /// A new, empty solver.
     pub fn new() -> LayoutSolver {
         LayoutSolver::default()
     }
 
-    /// Grow the per-handle arrays to cover `h`.
     fn ensure(&mut self, h: Handle) {
         let need = h as usize + 1;
         if self.input.len() < need {
@@ -809,7 +660,7 @@ impl LayoutSolver {
         }
     }
 
-    /// Mark `h` as written this round (so [`begin`](Self::begin) will reset its slot).
+    /// Record `h` for [`begin`](Self::begin) to reset.
     fn touch(&mut self, h: Handle) {
         let i = h as usize;
         if !self.marked[i] {
@@ -818,7 +669,7 @@ impl LayoutSolver {
         }
     }
 
-    /// Start a round: reset every slot the previous round touched (O(nodes), not O(id space)).
+    /// Start a round, resetting only the slots the last round touched.
     pub fn begin(&mut self) {
         for &h in &self.touched {
             let i = h as usize;
@@ -837,17 +688,15 @@ impl LayoutSolver {
         self.unresolvable.clear();
     }
 
-    /// Seed a pre-resolved rect at `h` — an anchor target this solve does not compute (the screen
-    /// root, an already-resolved region). Also used to publish a rect mid-sweep so later nodes in
-    /// the same pass see it.
+    /// Seed a rect this solve does not compute, such as the screen root (`CSimpleTop`); also
+    /// publishes one mid-sweep for later nodes of the same pass.
     pub fn set_external(&mut self, h: Handle, rect: Rect) {
         self.ensure(h);
         self.touch(h);
         self.rect[h as usize] = Some(rect);
     }
 
-    /// Register a frame to solve, copying `src` into the solver's persistent slot (the anchors
-    /// `Vec` is refilled in place, so a steady round allocates nothing).
+    /// Register a frame to solve, copying `src` into its slot; a steady round allocates nothing.
     pub fn set_frame(&mut self, h: Handle, src: &LayoutInput) {
         self.ensure(h);
         self.touch(h);
@@ -859,9 +708,7 @@ impl LayoutSolver {
         self.live.push(h);
     }
 
-    /// [`set_frame`](Self::set_frame) with `src`'s anchors replaced by exactly `anchor` — the
-    /// ScrollFrame child override (decision 0112), which otherwise cost a full input clone plus a
-    /// one-element `Vec` per scroll child per round.
+    /// [`set_frame`](Self::set_frame) with `anchor` as the only anchor: a ScrollFrame child's.
     pub fn set_frame_anchored(&mut self, h: Handle, src: &LayoutInput, anchor: Anchor) {
         self.ensure(h);
         self.touch(h);
@@ -873,7 +720,6 @@ impl LayoutSolver {
         self.live.push(h);
     }
 
-    /// The non-anchor fields, copied verbatim.
     fn copy_fields(dst: &mut LayoutInput, src: &LayoutInput) {
         dst.width = src.width;
         dst.height = src.height;
@@ -883,18 +729,13 @@ impl LayoutSolver {
         dst.extent_y = src.extent_y;
     }
 
-    /// Resolve every registered frame in dependency order (each anchor target before its
-    /// dependents), detecting cycles. Cycle members are still resolved best-effort, ascending by
-    /// handle, against whatever rects were available — matching the map-backed driver this
-    /// replaces.
+    /// Resolve every registered frame, anchor targets first; cycle members then resolve
+    /// best-effort, ascending by handle, against the rects known by then.
     pub fn solve(&mut self) {
         self.live.sort_unstable();
 
-        // Frame→frame anchor edges. A dependency on an external or an unknown handle does not
-        // constrain ordering (its rect is fixed / missing, not produced by this pass); only
-        // frame→frame edges do. A self-anchor counts as an edge, so a self-referential frame is
-        // never emitted ⇒ reported as a cycle. Duplicate targets count once (an anchor slot set is
-        // at most 9, so the dedupe is a linear scan, not a set).
+        // Only frame-to-frame anchors order the pass. A self-anchor counts, so a self-anchored
+        // frame lands in `cycle`; a target named twice counts once.
         for idx in 0..self.live.len() {
             let h = self.live[idx];
             let mut seen: [Handle; 9] = [0; 9];
@@ -939,7 +780,7 @@ impl LayoutSolver {
             self.resolve_one(h);
         }
 
-        // Frames never emitted are on (or behind) a cycle; resolve them best-effort, ascending.
+        // A frame never emitted is on or behind a cycle.
         for idx in 0..self.live.len() {
             let h = self.live[idx];
             if !self.emitted[h as usize] {
@@ -949,7 +790,6 @@ impl LayoutSolver {
         }
     }
 
-    /// Resolve one frame against the rects known so far, recording failure.
     fn resolve_one(&mut self, h: Handle) {
         let outcome = {
             let input = &self.input[h as usize];
@@ -962,20 +802,18 @@ impl LayoutSolver {
         }
     }
 
-    /// The rect known at `h`: an external as seeded, or a frame's resolved rect. `None` if the
-    /// handle is unknown or its frame was under-constrained.
+    /// The rect at `h`: an external as seeded, a frame as resolved.
     #[inline]
     pub fn rect(&self, h: Handle) -> Option<Rect> {
         self.rect.get(h as usize).copied().flatten()
     }
 
-    /// Frames on (or behind) an anchor dependency cycle — no valid topological position. Ascending.
+    /// Frames on or behind an anchor cycle, ascending.
     pub fn cycle(&self) -> &[Handle] {
         &self.cycle
     }
 
-    /// Frames whose `assemble` returned unresolvable (under-constrained, or depending on an
-    /// unresolvable/missing target). May overlap [`cycle`](Self::cycle).
+    /// Frames that did not resolve; may overlap [`cycle`](Self::cycle).
     pub fn unresolvable(&self) -> &[Handle] {
         &self.unresolvable
     }
@@ -985,10 +823,8 @@ impl LayoutSolver {
 mod tests {
     use super::*;
 
-    // Screen-root handle used across tests; its rect is the physical screen (y-up).
     const SCREEN: Handle = 0;
     fn screen_rect() -> Rect {
-        // [bottom, left, top, right]
         Rect::new(0.0, 0.0, 600.0, 800.0)
     }
 
@@ -1010,13 +846,10 @@ mod tests {
     }
 
     // ── Leaf kernels ─────────────────────────────────────────────────────────────────────────
-    // Input probes transcribed from wow-5875-re/crates/ui/tests/difftest/layout.rs (the explicit
-    // per-leg probes; binary-diffed there). Expected outputs are hand-computed from the layout.md
-    // formulas — this crate has no WoW.exe emulator, so these are spec-derived, not binary-diffed.
+    // Expected values are hand-computed from the formulas, not taken from the client.
 
     #[test]
     fn combine_edge_legs() {
-        // (center, opp, span)
         assert_eq!(combine_edge(10.0, 50.0, 7.0), 57.0); // opp+span
         assert_eq!(combine_edge(10.0, f32::INFINITY, 7.0), 7.0 * 0.5 + 10.0); // span/2+center
         assert_eq!(combine_edge(10.0, 50.0, 0.0), (10.0 - 50.0) + 10.0); // 2c-opp = -30
@@ -1047,14 +880,13 @@ mod tests {
     #[test]
     fn anchor_resolve_x_columns() {
         let r = [3.0f32, 100.0, 480.0, 260.0]; // [bottom, left, top, right]
-                                               // relLeft, center, relRight (point-ids 0,1,2), scale 1, xOff 5
+                                               // point ids 0, 1, 2 (left, center, right), xOff 5
         assert_eq!(anchor_resolve_x(1.0, 5.0, 0, Some(r), false), 5.0 + 100.0);
         assert_eq!(
             anchor_resolve_x(1.0, 5.0, 1, Some(r), false),
             (260.0 + 100.0) * 0.5 + 5.0
         );
         assert_eq!(anchor_resolve_x(1.0, 5.0, 2, Some(r), false), 5.0 + 260.0);
-        // scale multiplies the offset
         assert_eq!(
             anchor_resolve_x(2.0, 5.0, 0, Some(r), false),
             2.0 * 5.0 + 100.0
@@ -1116,8 +948,7 @@ mod tests {
 
     // ── Composed resolver ─────────────────────────────────────────────────────────────────────
 
-    /// VERIFIED numeric vector from wow-5875-re/system/ui/scratch/rf32-composed-resolver.md
-    /// "Worked oracle (probe 1)" — binary-diffed there against WoW.exe's `assemble 0x767a20`.
+    /// The rect the running reference client's `assemble` (`0x767a20`) produced.
     #[test]
     fn oracle_single_topleft_explicit_size() {
         let f = LayoutInput::sized(
@@ -1131,16 +962,14 @@ mod tests {
             200.0,
             50.0,
         );
-        // screen root [0,0,600,800] (probe uses root top=600, right=800)
+        // The reference run's screen root: top 600, right 800.
         let got = resolve_rect(&f, |_| Some(Rect::new(0.0, 0.0, 600.0, 800.0)));
         assert_rect(got, Rect::new(545.0, 10.0, 595.0, 210.0));
     }
 
     #[test]
     fn single_anchor_all_nine_points_explicit_size() {
-        // For each own-point p, anchor p -> the same point on screen, xOff/yOff 0, w100 h40.
-        // The anchored corner/edge pins directly; the rest derive from size. We assert the pinned
-        // coordinate and the resulting width/height, computed by hand from layout.md.
+        // Each point pinned to the same point on the screen: every leg must keep the 100x40 size.
         let screen = screen_rect();
         for &p in &[
             Point::TopLeft,
@@ -1159,7 +988,6 @@ mod tests {
                 ResolveOutcome::Resolved(r) => r,
                 ResolveOutcome::Unresolvable => panic!("{p:?} unresolvable"),
             };
-            // width/height always preserved
             assert_eq!(r.width().to_bits(), 100.0f32.to_bits(), "{p:?} width");
             assert_eq!(r.height().to_bits(), 40.0f32.to_bits(), "{p:?} height");
         }
@@ -1195,7 +1023,6 @@ mod tests {
 
     #[test]
     fn scale_interaction() {
-        // scale 2 -> offsets and size span doubled.
         let f = LayoutInput {
             anchors: vec![Anchor::new(
                 Point::TopLeft,
@@ -1271,8 +1098,7 @@ mod tests {
 
     #[test]
     fn unset_sentinel_propagates() {
-        // Anchor to a target with no valid rect (GetRect fail) -> that edge is +Inf -> frame
-        // unresolvable (single anchor, so opposite edges can't derive).
+        // The one anchor's target has no rect, so its edges are +Inf and nothing else pins them.
         let f = LayoutInput::sized(
             vec![Anchor::new(
                 Point::TopLeft,
@@ -1335,7 +1161,6 @@ mod tests {
         s.solve();
         assert!(s.cycle().contains(&A));
         assert!(s.cycle().contains(&B));
-        // neither can resolve (each depends on the other's rect, unavailable)
         assert!(s.unresolvable().contains(&A));
         assert!(s.unresolvable().contains(&B));
     }
@@ -1360,18 +1185,15 @@ mod tests {
     #[test]
     fn size_changed_epsilon() {
         let r = Rect::new(0.0, 0.0, 40.0, 100.0);
-        // sub-epsilon width change -> not fired
+        // 1e-7 is under SIZE_EPS.
         let tiny = Rect::new(0.0, 0.0, 40.0, 100.0 + 1e-7);
         assert!(!size_changed(r, tiny));
-        // supra-epsilon -> fired
         let big = Rect::new(0.0, 0.0, 40.0, 100.001);
         assert!(size_changed(r, big));
     }
 
-    /// The solver's buffers live across rounds, so `begin` must leave NO trace of the previous
-    /// one — a stale rect, in-degree, dependent edge, or `is_frame` flag would silently corrupt
-    /// the next solve. Round 2 registers a *disjoint* frame set that anchors to a handle round 1
-    /// used, and must see it as unknown (not round 1's rect).
+    /// The buffers live across rounds, so `begin` must leave nothing behind: round 2 anchors to a
+    /// handle only round 1 registered and must find it unknown.
     #[test]
     fn begin_leaves_no_state_from_the_previous_round() {
         const A: Handle = 1;
@@ -1407,8 +1229,7 @@ mod tests {
         let a_first = s.rect(A).expect("A resolved in round 1");
         assert!(s.rect(B).is_some());
 
-        // Round 2: ONLY B, still anchored to A — but A is no longer registered and no external
-        // seeds it, so B must be unresolvable rather than reusing round 1's stale A rect.
+        // Round 2: only B, whose target A is no longer registered.
         s.begin();
         s.set_external(SCREEN, screen_rect());
         s.set_frame(
@@ -1431,8 +1252,7 @@ mod tests {
         assert!(s.unresolvable().contains(&B));
         assert!(s.cycle().is_empty(), "cycle list must be cleared too");
 
-        // Round 3: the original pair again — identical results to round 1 (no accumulated
-        // in-degree or dependent edges from the rounds between).
+        // Round 3: the original pair again, which must match round 1.
         s.begin();
         s.set_external(SCREEN, screen_rect());
         s.set_frame(
@@ -1465,9 +1285,8 @@ mod tests {
         assert!(s.unresolvable().is_empty());
     }
 
-    /// A frame registered with the ScrollFrame override keeps its size/scale but drops its own
-    /// anchors for exactly the override (decision 0112) — and the slot's anchor `Vec` is reused,
-    /// so the previous round's anchors must not leak through.
+    /// The override keeps the size and scale but replaces the anchors, and the reused anchors `Vec`
+    /// must not leak the last round's.
     #[test]
     fn set_frame_anchored_replaces_only_the_anchors() {
         const A: Handle = 1;
@@ -1491,8 +1310,7 @@ mod tests {
             bits(Rect::new(0.0, 0.0, 600.0, 800.0))
         );
 
-        // Overridden: the two authored anchors are gone, replaced by one TOPLEFT pin at (10, -5),
-        // so the explicit 100x40 size now decides the other two edges.
+        // Overridden: one TOPLEFT pin at (10, -5), so the 100x40 size decides the other edges.
         s.begin();
         s.set_external(SCREEN, screen_rect());
         s.set_frame_anchored(
diff --git a/crates/benilla-ui/src/lib.rs b/crates/benilla-ui/src/lib.rs
index 4bcb1add..4af31f01 100644
--- a/crates/benilla-ui/src/lib.rs
+++ b/crates/benilla-ui/src/lib.rs
@@ -1,25 +1,5 @@
-//! The engine-free core of benilla's UI engine (decision 0068): the WoW interface is data + a
-//! runtime — TOC manifests, FrameXML documents, and Lua — and this crate owns everything about
-//! that runtime which needs neither Bevy nor a GPU: parsing, template expansion, the anchor/layout
-//! resolver, and the draw-order key. The Bevy side (rendering, input, the game-state API bindings)
-//! lives in the app; the Lua VM is embedded by the app and calls back into this crate's model.
-//!
-//! Built currently: [`toc`] — the addon/FrameXML manifest parser; [`framexml`] — the FrameXML
-//! document parser (order-preserving tree, template expansion, `$parent` substitution);
-//! [`bindings_xml`] — the per-addon `Bindings.xml` parser (the third file format, feeding
-//! [`script::keybind`]'s table); [`layout`]
-//! — the anchor/layout resolver (anchor graph → resolved rects), transcribed bit-faithfully from
-//! wow-5875-re's binary-verified spec; [`widget`] — the frame arena and its show/hide/strata/level/
-//! scale/alpha propagation mutations; [`order`] — the strata/draw-layer vocabulary, the packed
-//! total-order key, and the visible-tree traversal that realizes the client's painter order;
-//! [`script`] — the engine-free Lua host (mlua 5.1) binding the arena/layout/order model to the
-//! FrameScript object model + WoW stdlib so FrameXML/addon Lua runs against it (decision 0068);
-//! [`loader`] — the FrameXML loader that joins the two, walking a parsed document to materialize live
-//! frames in a running [`script::UiScript`] by driving the object model exactly as an addon does;
-//! [`markup`] — the single owner of WoW's inline-markup grammar (`|cAARRGGBB`, `|H…|h…|h`, `|n`,
-//! `||`): the client's token decoder and the per-byte class map its cursor law is built on;
-//! [`source`] — what a UI source file *is* before any parser sees it: bytes, BOM-stripped, decoded
-//! to text only where a Rust parser forces it (decision 1193).
+//! The engine-free core of benilla's UI: the `.toc`, FrameXML and `Bindings.xml` parsers, the
+//! layout resolver, the frame arena, draw order and the Lua host FrameXML runs in; no Bevy, no GPU.
 
 pub mod bindings_xml;
 pub mod civil;
diff --git a/crates/benilla-ui/src/loader/backdrop.rs b/crates/benilla-ui/src/loader/backdrop.rs
index ea6c70d8..9b22381a 100644
--- a/crates/benilla-ui/src/loader/backdrop.rs
+++ b/crates/benilla-ui/src/loader/backdrop.rs
@@ -5,11 +5,9 @@ use crate::framexml::Element;
 use super::{abs_value, children_named, color_of, Loader};
 
 impl Loader<'_> {
-    /// `<Backdrop bgFile edgeFile tile>` + children `<EdgeSize>`/`<TileSize>`/`<BackgroundInsets>`/
-    /// `<Color>`/`<BorderColor>` (rf24 LoadXML `0x77e6c0`; backdrop-mechanism.md §1). Builds the same
-    /// table Lua `SetBackdrop` reads and installs it, then applies the two colors — the XML `<Color>`
-    /// parser defaults a *present* element's missing channels to **black** (r=g=b=0, a=1 via
-    /// [`color_of`]), distinct from the ctor white a table `SetBackdrop` leaves.
+    /// `<Backdrop>` (LoadXML `0x77e6c0`): the table Lua `SetBackdrop` takes, then the two colours.
+    /// A present `<Color>` defaults a missing channel to black, alpha 1 (`0x6f23d0`), not the
+    /// white a table `SetBackdrop` leaves.
     pub(super) fn apply_backdrop(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         let Some(bd) = children_named(el, "Backdrop").next() else {
             return;
@@ -32,10 +30,8 @@ impl Loader<'_> {
         }
     }
 
-    /// Build the `SetBackdrop` table from a `<Backdrop>` element: `bgFile`/`edgeFile`/`tile` attrs,
-    /// `<EdgeSize>`/`<TileSize>` scalars ([`abs_value`]), and `<BackgroundInsets>` (an `<AbsInset>`
-    /// child or inline `left`/`right`/`top`/`bottom` attrs). Missing keys are simply absent — the
-    /// object-model `SetBackdrop` leaves the ctor default (tileSize 0, edgeSize 32, insets 0).
+    /// The `SetBackdrop` table for a `<Backdrop>`. A key the element omits stays absent, so
+    /// `SetBackdrop` keeps the ctor's default (tileSize 0, edgeSize 32, insets 0).
     pub(super) fn build_backdrop_table(&self, bd: &Element) -> mlua::Result<Table> {
         let t = self.lua().create_table()?;
         if let Some(f) = bd.attr("bgFile") {
diff --git a/crates/benilla-ui/src/loader/geometry.rs b/crates/benilla-ui/src/loader/geometry.rs
index df2d2a7f..84d3a756 100644
--- a/crates/benilla-ui/src/loader/geometry.rs
+++ b/crates/benilla-ui/src/loader/geometry.rs
@@ -6,35 +6,15 @@ use super::regions::FontAttrs;
 use super::{abs_dim, children_named, Loader};
 
 impl Loader<'_> {
-    /// LoadXML attribute handling (rf24 `0x769820`): the subset the v1 object model exposes, plus a
-    /// warn-once for the attributes whose methods don't exist yet (a next-phase gap, not a workaround).
+    /// A frame element's LoadXML attributes and simple children (`0x769820`), and a model pane's
+    /// own (`0x76cac0`).
     pub(super) fn apply_attrs(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if el.attr_bool("hidden") {
             self.call(wrapper, "Hide", (), dbg);
         }
-        // **An unrecognised `frameStrata=` WARNS and skips; it does not raise** (decision 2160).
-        //
-        // The two doors are genuinely different in the reference and this is the one that is
-        // quiet. `CSimpleFrame::LoadXML 0x769820` resolves the name through `0x6f17d0`, whose miss
-        // arm returns `eax = 0` without writing the caller's out-parameter (`0x6f17ff`); the miss
-        // leg then pushes `0x878658 "Frame %s: Unknown frame strata: %s"` at severity 1 into the
-        // document's `CStatus` sink (`0x7699a4 call [edx+0xc]`, which returns — all five `Add`
-        // implementations image-wide are raise-free) and **reconverges with the hit path at
-        // `0x7699ad`**, carrying straight on into `frameLevel` and the rest of the subtree.
-        // `SetFrameStrata 0x76a470` is called only on the hit arm (`0x769971`), so the frame keeps
-        // whatever stratum it already had — its template's, its parent's, or the ctor's MEDIUM
-        // (`[+0xc0] = 3` at `0x7690c2`).
-        //
-        // The **Lua** binding is the loud one and stays as it is: `0x774360`'s miss reaches
-        // `0x774456 call 0x6f4940` (`luaL_error`), whose callee chain `luaG_errormsg 0x6fc780` /
-        // `luaD_throw 0x6f5d80` contains no `ret` at all — the epilogue after it is dead code.
-        //
-        // (wow-re `ui/scratch/frame-strata-miss-law.md`, §5 trio + orchestrator arbitration.)
-        //
-        // Resolving here rather than letting `SetFrameStrata` raise is what reproduces that split:
-        // routed through `self.call`, a bad value became a `report.errors` row, which is a script
-        // error the player sees — and it cost `EQL3` its whole `EQL3_Log.xml`, on a `<Frame
-        // frameStrata="ARTWORK">` (a draw-LAYER name) the real client shrugs at.
+        // An unknown `frameStrata=` is logged (`0x7699a4`) and skipped, not raised as the Lua
+        // binding would (`0x774360`): `SetFrameStrata` runs only on a hit (`0x769971`), so the
+        // frame keeps the strata it had.
         if let Some(strata) = el.attr("frameStrata") {
             if crate::script::object::strata_from_str(strata).is_some() {
                 self.call(wrapper, "SetFrameStrata", strata.to_string(), dbg);
@@ -54,20 +34,8 @@ impl Loader<'_> {
                 self.call(wrapper, "SetAlpha", a, dbg);
             }
         }
-        // `scale=` on a MODEL pane is the model's own scale, not the frame's: `CSimpleModel::
-        // LoadXML` (`0x76cac0`) writes it into `+0x3a0` at `76cb61` — the field `SetModelScale`
-        // writes — and raises `Frame %s: Invalid model scale: %s` at `76cb92` for `≤ 0` (a raise,
-        // not a clamp; wow-re `modelframe-render-law.md` §2). Every `scale=` in the shipped
-        // FrameXML sits on a model pane (the cooldown indicator's 0.75, the autocast shine's
-        // 1.2/1.22, the pings' 0.4, the dressing room's 2.0), and until decision 2007 the loader
-        // read none of them. Whether the generic frame loader (`0x769820`) reads a `scale`
-        // attribute of its own is not carved; a plain frame's `scale=` is left as it was.
 
-        // `file=` on a model pane is `SetModel` (`CSimpleModel::LoadXML` `0x76cac0` installs the
-        // file into the widget, resident or streaming — decision 2013). Until 2013 no XML-declared
-        // pane ever held a file: the loader read `file=` only to turn the cooldown indicator's
-        // pane into a native widget of ours (retired by 2019), and the pings, the shine and the
-        // item card were bare panes to the engine.
+        // A model pane's `file=` is `SetModel` (`0x76cac0`).
         let model_kind = super::model_kind_tag(&el.tag);
         if model_kind {
             if let Some(file) = el.attr("file") {
@@ -75,6 +43,9 @@ impl Loader<'_> {
                 self.call(wrapper, "SetModel", text, dbg);
             }
         }
+        // A model pane's `scale=` is the model's scale, the field `SetModelScale` writes
+        // (`0x76cb61`); a value of 0 or less is refused, never clamped (`0x76cb92`). A plain
+        // frame's `scale=` is ignored; whether `0x769820` reads one is untraced.
         if let Some(scale) = el.attr("scale") {
             if model_kind {
                 match scale.trim().parse::<f32>() {
@@ -86,12 +57,8 @@ impl Loader<'_> {
                 }
             }
         }
-        // The model pane's own fog attributes and `<FogColor>` child (`CSimpleModel::LoadXML`
-        // `0x76cac0`, render law §5.4). `fogNear`/`fogFar` are **clamped at `≥ 0`** here and only
-        // here (`76cbbb`-`76cbd2` / `76cbf3`-`76cc0a`: `0.0 fcomp value ; jne store ; else store
-        // 0.0`) — the Lua setters store raw. The `<FogColor>` child writes the packed colour AND
-        // arms the fog bit, so it is `SetFogColor` in every respect; nothing in XML touches the
-        // light. Decision 2027.
+        // A model pane's fog: `fogNear`/`fogFar` clamp at 0 here only (`0x76cbbb`, `0x76cbf3`),
+        // where the Lua setters store raw; `<FogColor>` is `SetFogColor`, fog bit included.
         if model_kind {
             for (attr, verb) in [("fogNear", "SetFogNear"), ("fogFar", "SetFogFar")] {
                 if let Some(v) = el.attr(attr).and_then(|v| v.trim().parse::<f32>().ok()) {
@@ -117,22 +84,14 @@ impl Loader<'_> {
                 self.call(wrapper, "SetID", n, dbg);
             }
         }
-        // `clampedToScreen="true"` → SetClampedToScreen (rf24 `0x768cc0` — geometry flags bit4,
-        // the layout resolve's screen clamp; GameTooltip frames carry it by construction).
+        // `clampedToScreen`: the layout's screen clamp, geometry flag bit 4 (`0x768cc0`).
         if el.attr_bool("clampedToScreen") {
             self.call(wrapper, "SetClampedToScreen", true, dbg);
         }
-        // `enableMouse` lands as the real EnableMouse call (the hit test gates on it —
-        // pointer.rs): a ref frame authored mouse-blocking (StaticPopup, BlackoutWorld, the
-        // minimap cluster) must actually capture. The loader ignored it for a while after the
-        // native landed — the stale "v1 gap" note here — which left those frames click-through
-        // and the minimap deaf to its ping click (0434 phase 6c's root cause).
         if el.attr_bool("enableMouse") {
             self.call(wrapper, "EnableMouse", true, dbg);
         }
-        // `<HitRectInsets><AbsInset left= right= top= bottom=/></HitRectInsets>` (also accepted
-        // inline on the element) → SetHitRectInsets: the frame's MOUSE rect, inset from its
-        // resolved rect. Absent sides read 0, so a partial element insets only what it names.
+        // `<HitRectInsets>`: the mouse rect, inset from the frame's; a side it omits is 0.
         if let Some(ins) = children_named(el, "HitRectInsets").next() {
             let src = children_named(ins, "AbsInset").next().unwrap_or(ins);
             let side = |k: &str| {
@@ -147,70 +106,33 @@ impl Loader<'_> {
                 dbg,
             );
         }
-        // `<ResizeBounds><minResize><AbsDimension x= y=/></minResize><maxResize>…` → the resize
-        // quad (rf24 `0x769820`'s child-loop arm at `0x769baa`; wow-re
-        // `system/ui/scratch/resize-bounds-and-button-fontstring.md` §4). Three clauses from that
-        // carve rather than from the shape of the element:
-        //
-        //  · **Both pairs are written unconditionally once `<ResizeBounds>` matches**, each side
-        //    defaulting to `0` before its lookup — so a block carrying only `<minResize>` RESETS
-        //    the max pair to unbounded. That is why this writes both calls, never just the one it
-        //    found.
-        //  · `x` is the WIDTH and `y` the HEIGHT, through the same logical→internal transform
-        //    `<Size>` uses — the same `abs_dim` reader, and the same inline-or-`AbsDimension` pair
-        //    of forms.
-        //  · `<Size>` and `<Anchors>` are consumed by the base-class `CLayoutFrame::LoadXML`
-        //    *before* the child loop is entered at all, so they always precede this structurally
-        //    whatever the document order — and neither path clamps, so an authored `<Size>`
-        //    outside the authored bounds survives load unchanged.
-        //
-        // The shipped 1.12.1 FrameXML uses it exactly once (`FloatingChatFrame.xml:223`,
-        // min 296×75 / max 608×400) and never calls the Lua setters at all.
+        // `<ResizeBounds>` (`0x769baa`): both pairs are always written, an absent one as 0, so a
+        // lone `<minResize>` resets the max to unbounded. A `<Size>` outside them is not clamped.
         if let Some(rb) = children_named(el, "ResizeBounds").next() {
             for (tag, verb) in [("minResize", "SetMinResize"), ("maxResize", "SetMaxResize")] {
                 let (x, y) = children_named(rb, tag).next().map_or((None, None), abs_dim);
                 self.call(wrapper, verb, (x.unwrap_or(0.0), y.unwrap_or(0.0)), dbg);
             }
         }
-        // `movable`/`resizable` → SetMovable/SetResizable — the same flag word the methods write
-        // (`0x76a3c0` with mask 0x100 / 0x200; wow-re `rf24-framexml-loader.md` records the loader
-        // calling that very setter). Both were in the gap list below until the movable family
-        // landed; leaving them there would have left every `movable="true"` reference window
-        // undraggable while `SetMovable` worked from Lua.
+        // `movable`/`resizable`: flag bits 0x100/0x200, via the setter Lua uses (`0x76a3c0`).
         if el.attr_bool("movable") {
             self.call(wrapper, "SetMovable", true, dbg);
         }
         if el.attr_bool("resizable") {
             self.call(wrapper, "SetResizable", true, dbg);
         }
-        // `toplevel` → SetToplevel — the third bit of that same flag word (`0x76a3c0` mask `0x1`,
-        // XML site `0x7698ec`; wow-re `ui/scratch/toplevel-raise.md`), and the third attribute to
-        // graduate out of the gap list below for the same reason: the raise law is built
-        // (`script::object::toplevel`), so accepting the attribute now means the behaviour, not
-        // silence. 82 corpus addons and thirteen of our own frames declare it.
+        // `toplevel`: bit 0x1 of the same flag word (`0x7698ec`).
         if el.attr_bool("toplevel") {
             self.call(wrapper, "SetToplevel", true, dbg);
         }
-        // `enableKeyboard="true"` — the XML half of the flag, which enables BOTH key kinds
-        // (`scripts-auto-enable.md` §1-2). The flag is real, and `script::keyboard`'s delivery
-        // walk is what reads it (1319).
+        // `enableKeyboard` enables both key kinds (`0x769ae8`, `0x769af3`).
         if el.attr_bool("enableKeyboard") {
             self.call(wrapper, "EnableKeyboard", true, dbg);
         }
     }
 
-    /// `<Size>` → SetWidth/SetHeight (rf24 `0x767800`). Accepts either `<Size><AbsDimension x= y=/>`
-    /// or the inline `<Size x= y=/>` form; a dimension that's absent is left untouched (the client's
-    /// "0 = derive"). ALL `<Size>` children apply, in document order — template expansion appends the
-    /// instance's children after the template's ([`crate::framexml::expand`]), and the client simply
-    /// processes each child in turn, so an instance's own `<Size>` overwrites its template's. (Taking
-    /// only `.next()` here silently pinned every templated frame to the TEMPLATE's size; caught on
-    /// the quest log's Abandon button — 125×21 in the instance XML, 80×22 on screen.)
-    /// `<TitleRegion setAllPoints="true"/>` (or one with its own `<Size>`/`<Anchors>`): the
-    /// frame's drag handle, built through the same `CreateTitleRegion` the Lua API exposes — so
-    /// the element and a later `frame:CreateTitleRegion()` name ONE object (the verb is
-    /// idempotent; wow-re `widget-api-batch-benilla.md` Q6) — then laid out like any region.
-    /// The stock `TutorialFrame.xml` declares one over its whole plate (1976).
+    /// `<TitleRegion>`: the drag handle, built through the idempotent `CreateTitleRegion` so the
+    /// element and a later Lua call name one object (`0x769b2a` takes `0x773910`'s path).
     pub(super) fn apply_title_region(
         &mut self,
         el: &Element,
@@ -233,6 +155,8 @@ impl Loader<'_> {
         self.apply_region_layout(tr, &region, self_name, dbg, FontAttrs::Own);
     }
 
+    /// `<Size>` (`0x767800`). Every one applies in document order, and expansion puts an
+    /// instance's children after its template's, so the instance's own `<Size>` wins.
     pub(super) fn apply_size(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         for size in children_named(el, "Size") {
             let (x, y) = abs_dim(size);
@@ -245,12 +169,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<Anchors>` → SetPoint per `<Anchor point= relativeTo= relativePoint=><Offset .../></Anchor>`
-    /// (rf24 `0x767800`). `relativePoint` defaults to `point`; `relativeTo` is `$parent`-substituted
-    /// (rf27) and passed by name (the object model resolves it, falling back to the parent when
-    /// absent/unresolved); a missing `point` is skipped with a warning ("Invalid anchor point").
-    /// The `setAllPoints="true"` shorthand applies first, like the region path — a frame carrying
-    /// only the attribute (WorldMapFrame's chrome layers) pins TOPLEFT+BOTTOMRIGHT to its parent.
+    /// `<Anchors>` (`0x767800`), after the `setAllPoints` shorthand: `relativePoint` defaults to
+    /// `point`, and `relativeTo` expands `$parent` to the nearest named ancestor's name, else
+    /// `Top` (`0x76c5b0`).
     pub(super) fn apply_anchors(
         &mut self,
         el: &Element,
@@ -290,8 +211,7 @@ impl Loader<'_> {
                     args,
                     dbg: dbg.to_string(),
                 };
-                // The XML path's own law, which resolves the name itself and defers a target
-                // the enclosing frame's subtree has not built yet (`Loader::apply_anchor`).
+                // Deferred while the enclosing subtree has not built its target yet.
                 self.apply_anchor(d, true);
             }
         }
diff --git a/crates/benilla-ui/src/loader/mod.rs b/crates/benilla-ui/src/loader/mod.rs
index 2b462226..435bbff9 100644
--- a/crates/benilla-ui/src/loader/mod.rs
+++ b/crates/benilla-ui/src/loader/mod.rs
@@ -1,58 +1,12 @@
-//! The FrameXML **loader** (decision 0068): the join between the document layer ([`crate::framexml`])
-//! and the runtime ([`crate::script`]). It walks a parsed FrameXML document and *materializes* it —
-//! turning `<Include>`/`<Script>` sequencing, template instances, `<Layers>` regions, nested
-//! `<Frames>`, and `<Scripts>` handlers into live frames in a running [`UiScript`] — by driving the
-//! FrameScript object model exactly as an addon does (the `CreateFrame` global + the widget/region
-//! method surface installed in [`crate::script`]), never by reaching into the arena directly.
+//! The FrameXML loader: builds live frames from a parsed document ([`crate::framexml`]) by driving
+//! the Lua object model ([`crate::script`]) as an addon does, never the arena directly.
 //!
-//! ## Ground truth (wow-5875-re, closed VERIFIED ORCHESTRATION region `0x6edc00–0x6f3000`)
+//! The caller's `files` provider supplies bytes, so the loader does no IO; a `<Script file=>`
+//! chunk reaches Lua as the bytes on disk, as `luaL_loadbuffer` receives them. The loader joins a
+//! relative path to its file's directory ([`join_ref`]); the provider decides what it may reach.
 //!
-//! - `system/ui/scratch/rf24-framexml-loader.md` — the element→op map this module transcribes: the
-//!   top-level `<Include>`/`<Script>`/`<Font>`/frame routing (`0x6ede10`), `LoadXML` attribute
-//!   handling (`hidden`/`toplevel`/`movable`/`frameStrata`/`frameLevel`/`alpha`/`enableMouse`,
-//!   `0x769820`), `<Size>` + `<Anchors>` → `SetWidth`/`SetHeight`/`SetPoint` (`0x767800`), and
-//!   `<Layers>`/`<Layer>`/`<Texture>`/`<FontString>` (`0x769d70`), `<Scripts>` → `SetScript`
-//!   (`0x769ef0`).
-//! - `system/ui/scratch/rf26-nested-frames.md` — `LoadChildFrames 0x76a060`: nested `<Frames>` is a
-//!   post-load pass that gives **bottom-up `OnLoad` ordering** (a frame's children are fully built,
-//!   and their `OnLoad`s fired, *before* the parent's `OnLoad` runs).
-//! - `system/ui/scratch/rf27-parent-name-token.md` — `SetName 0x76c650` / the `$parent` token, applied
-//!   here (via [`crate::framexml::resolve_name`]) to frame/region names and to anchor `relativeTo`.
-//!
-//! ## The engine-free seam
-//!
-//! `<Include>`/`<Script file=>` need file bytes, which this crate must not read itself (no Bevy, no
-//! IO — decision 0068 §1). The app supplies a `files` closure that resolves a FrameXML path to its
-//! **bytes** (from the MPQ/addon dir); the loader stays IO-free.
-//!
-//! **Bytes, not text** (decision 1193). A `<Script file=>` chunk is handed to Lua as the bytes on
-//! disk, exactly as the reference's `luaL_loadbuffer` receives them; only an `<Include>`d document
-//! is decoded ([`crate::source::decode`]), because roxmltree needs `&str` and Lua does not. Before
-//! 1193 the provider returned `String`, so a cp1252 locale file did not lose a glyph — it read as
-//! *absent*, and the include or every handler in the script vanished with it.
-//!
-//! **The loader owns relative-path resolution; the provider owns the root** (decision 1186). A
-//! reference is relative to the directory of the *file that contains it*, and may walk up with `..`
-//! — `Bagnon/src/main.xml` reaches its sibling as `templates.xml` and a shared library addon as
-//! `..\..\BagBrother\core\core.xml`. Only the loader knows the include tree, so it does the joining
-//! ([`join_ref`]) and hands the provider one already-resolved path; the provider decides what that
-//! path is allowed to reach. [`load`] starts at the root, [`load_in`] starts at a named directory.
-//!
-//! A path with **no provider hit gets its own list**, [`LoadReport::missing_files`] — neither a
-//! warning nor an error (decision 2155). It was a warning until 1186, and the cost was that an
-//! addon which resolved *nothing* reported success — Bagnon missed all eleven of its references
-//! and came back with zero errors. 1186 answered that by calling it an error, which fixed the
-//! visibility and got the *severity* wrong the other way: the reference logs `"Couldn't open %s"`
-//! and carries on, with nothing raised, so an addon shipping an incomplete package was scoring as
-//! a client script error and reaching the player's red error dialog. Both facts are true and they
-//! need two different lists. The load continues either way (0068: the client logs and carries on).
-//!
-//! ## MAXCSTACK discipline (decision 0068, probe A)
-//!
-//! Like the host it drives, the loader holds **no** breadth-wise accumulation of Lua handles: a
-//! frame's wrapper `Table` and its (optional) `OnLoad` `Function` live only on the Rust stack across
-//! *that frame's own* subtree build (depth-bounded), and region wrappers are dropped as soon as their
-//! visuals are applied. Everything durable lives Lua-side in the host's registry.
+//! Lua handles are never accumulated breadth-wise (MAXCSTACK): a frame's wrapper and `OnLoad`
+//! live only across its own subtree build, and everything durable lives Lua-side.
 
 use std::collections::{HashMap, HashSet};
 
@@ -67,64 +21,28 @@ mod regions;
 mod scripts;
 mod widgets;
 
-/// The outcome of a [`load`]: what went wrong tolerably (`warnings`), what went wrong that dropped
-/// something (`errors`), and how much got built (`frames`). Never a panic and never an abort — a bad
-/// handler body, an unknown frame type, a missing include, or an unsupported attribute is an entry
-/// here and the load continues (decision 0068: the client logs-and-continues; so do we).
+/// The outcome of a [`load`]; nothing aborts a load, as the reference logs and continues.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct LoadReport {
-    /// Tolerable issues: a missing include/script provider, an unsupported-in-v1 attribute or script
-    /// handler, an unregistered `inherits=` font object, and the parse/expand warnings folded in from
-    /// the document layer. None of these dropped a frame — except one, on purpose: an **unknown
-    /// frame type** drops its own node here rather than in `errors`, because that is the channel
-    /// the reference uses for it at the XML door (`0x6ee356`, logged and non-fatal; decision 2191).
+    /// Issues that dropped nothing, and the document layer's parse warnings. An unknown frame type
+    /// drops its node yet lands here: the reference logs it and goes on (`0x6ee356`).
     pub warnings: Vec<String>,
-    /// Things that dropped a frame or a handler and that the reference RAISES on: a handler that
-    /// failed to compile, a method call that errored, a malformed included document.
+    /// Failures the reference raises on: a handler that fails to compile, a method call that
+    /// errors, a malformed included document.
     pub errors: Vec<String>,
-    /// **A named file the provider does not have** — an `<Include file=>` or `<Script file=>` whose
-    /// resolved path hit nothing (decision 2155).
-    ///
-    /// Its own list because it is its own severity, and 1186 put it in the wrong one. The reference
-    /// does not raise here: `0x6edaa0` logs `"Couldn't open %s"` (`0x846ff4`) and returns null, the
-    /// `<Include>` arm never tests the recursion's result (`0x6ee00d` → `0x6ee012`), and the
-    /// `<Script>` leg reports `"Error loading %s"` (`0x872e50`) and returns 0 — every failure leg
-    /// reports through the sink and returns normally, with no throw and no `longjmp`
-    /// (wow-re `ui/scratch/xml-toc-path-resolution.md` §4 and `include-lua-dispatch.md` §7, both
-    /// VERIFIED). This is the same rule 2107 unified for the `.toc` walk and the demand load, at
-    /// the two doors 2107 did not reach.
-    ///
-    /// **1186's finding is preserved and it is why this is not simply folded into
-    /// [`Self::warnings`]:** a document that resolved *nothing* must not report success — Bagnon
-    /// missed all eleven of its references and came back with zero errors. It still reports them,
-    /// under a name that says which kind of failure it is, and the caller decides severity by
-    /// whose manifest lied (`ui_script::addons`: ours is an `error!`, a player's addon a `warn!`,
-    /// both retained where the player can read them and neither raising a script error).
+    /// `<Include file=>` and `<Script file=>` paths the provider lacks. The reference logs
+    /// `"Couldn't open %s"` (`0x6edaa0`, `0x846ff4`) or `"Error loading %s"` (`0x872e50`) and goes
+    /// on (`0x6ee00d`); kept apart from `warnings` so a load that resolved nothing is not clean.
     pub missing_files: Vec<String>,
-    /// How many frame instances were successfully created (`CreateFrame` returned a wrapper) — the
-    /// coverage number the real-file smoke test reports.
+    /// Frame instances `CreateFrame` built.
     pub frames: usize,
-    /// **The loader's trace lines, emitted only while `FrameXML_Debug` is on** (decision 2160).
-    ///
-    /// Empty in every normal load, which is the reference's own default: `[0xceea30]` boots at 0
-    /// and each of the loader's five trace sites is gated `flag > 0` (`0x6ee298 jle`). Its own
-    /// list rather than a `warnings` row because a trace is not a defect — the reference files it
-    /// into the same per-document record at severity **0**, one below the `frameStrata` warning's
-    /// severity 1.
+    /// Trace lines, only while `FrameXML_Debug` is on: the reference's flag (`[0xceea30]`) boots 0
+    /// and its loader traces gate on `flag > 0` (`0x6ee298`). A trace is severity 0, not a warning.
     pub traces: Vec<String>,
 }
 
-/// Materialize a parsed FrameXML document into live frames in `script`.
-///
-/// Walks `doc.items` in document order (rf24-framexml-loader.md, top level): `<Include>` resolves via
-/// `files` and recurses; `<Script file=>`/inline `<Script>` run through the host **in order** (this is
-/// how XML-referenced FrameXML Lua loads); `<Font>` resolves + registers a named font object
-/// ([`Loader::do_font`]); a `virtual` template is registered for later `inherits=`; a non-virtual
-/// instance is expanded ([`crate::framexml::expand`]) and materialized.
-///
-/// `files` is the engine-free seam (see module docs): it resolves a FrameXML/Lua path to its
-/// **bytes**. Returning `None` yields a [`LoadReport::missing_files`] row — reported, but not an
-/// error, because nothing raised (decision 2155).
+/// Materialize a parsed FrameXML document into live frames in `script`, in document order
+/// (`0x6ede10`). `files` returns a path's bytes; a `None` is a [`LoadReport::missing_files`] row.
 pub fn load(
     script: &UiScript,
     doc: &ParsedDocument,
@@ -133,20 +51,8 @@ pub fn load(
     load_in(script, doc, "", files)
 }
 
-/// [`load`] for a document that does **not** sit at the provider's root.
-///
-/// `path` is the document's **own path** in the provider's path space (`/`-separated; `""` for a
-/// document with no path, which only tests have). Its directory is what every `<Include>`/`<Script
-/// file=>` inside resolves against, and each nested include resolves against *its* own directory in
-/// turn — so an addon whose manifest lists `src\main.xml` passes `"<Addon>/src/main.xml"` here and
-/// its `<Include file="templates.xml">` reaches `<Addon>/src/templates.xml` (decision 1186).
-///
-/// **The path, not the directory, because the loader has to be able to say where a raise came
-/// from.** Every `<Script>` chunk is named after the file carrying it; an unnamed chunk takes
-/// mlua's `#[track_caller]` default, which is *this file's* Rust source line, and 26 of the corpus
-/// survey's 70 readable failures pointed at `crates/benilla-ui/src/loader/mod.rs` instead of the
-/// addon (decision 1217). Three callers used to derive this directory themselves with the same
-/// three lines; they pass the path now and [`dir_of`] does it once.
+/// [`load`] for a document at `path` in the provider's path space (`/`-separated, `""` for none),
+/// which its relative references resolve against and its inline `<Script>` chunks are named after.
 pub fn load_in(
     script: &UiScript,
     doc: &ParsedDocument,
@@ -156,9 +62,7 @@ pub fn load_in(
     load_into(script.lua(), doc, path, files)
 }
 
-/// [`load_in`] against the VM directly, for a caller that holds `&Lua` rather than `&UiScript` —
-/// which is every Lua binding, and therefore `LoadAddOn` (1188 phase 2). Identical behaviour;
-/// `load_in` is the same call with the script's own VM.
+/// [`load_in`] on the VM directly, for a Lua binding (`LoadAddOn`), which holds only `&Lua`.
 pub fn load_into(
     lua: &mlua::Lua,
     doc: &ParsedDocument,
@@ -173,51 +77,22 @@ pub fn load_into(
         warned: HashSet::new(),
         deferred_anchors: Vec::new(),
     };
-    // Fold the document layer's own parse warnings in (decision 0068: reuse framexml's warnings).
     loader.report.warnings.extend(doc.warnings.iter().cloned());
     loader.load_doc(doc);
     loader.report
 }
 
-/// Apply a **template** to a frame that already exists — the runtime half of `inherits=`.
-///
-/// This is the fourth argument of `CreateFrame(kind, name, parent, "UIPanelButtonTemplate")`, and
-/// it is the single most common way an addon builds anything. `wrapper` is the frame the binding
-/// has just created, `kind` is the kind string it was given, and `template` is the raw — possibly
-/// comma-separated — `inherits=` list. Returns the messages worth surfacing (warnings first, then
-/// the errors that dropped something); the caller decides where they go. Nothing here can fail
-/// the call.
-///
-/// **The caller's own name wins, and that is the load-bearing part.** `CreateFrame("Button",
-/// "MyButton", p, "SomeTemplate")` is a frame named `MyButton`, so the template's `$parentText`
-/// resolves to `MyButtonText` — which is the global the addon's very next line calls `getglobal`
-/// on. A template whose children came out named after the *template* would be useless.
-///
-/// **The frame is never dropped, whatever the template turns out to be.** Four cases, each a
-/// message and a usable frame:
-/// - an **unknown** name — the reference creates the frame anyway, so we do;
-/// - a name whose element was **not `virtual="true"`** — only virtual elements are ever registered
-///   ([`Loader::load_doc`]), so from the registry's side it is indistinguishable from unknown, and
-///   it reads as unknown;
-/// - a **region** template (a virtual `<Texture>`/`<FontString>`) where a frame was asked for —
-///   its frame-shaped content (`<Size>`, `<Anchors>`) still applies, its region-only content
-///   cannot, and it says so;
-/// - a **kind that disagrees with the template's tag** — the frame already exists as the kind
-///   `CreateFrame` was given and no template can retype it, so [`framexml::inherits_node`] keeps
-///   the caller's kind and the per-kind passes skip what would not apply. Named, not pretended.
-///
-/// **Why this cannot simply call [`Loader::materialize`]:** materialize's step 1 *is*
-/// `CreateFrame`, and this runs from inside that binding — it would recurse forever. The steps
-/// after it are [`Loader::decorate`], which is what both entry points share.
-///
-/// Reachable from a Lua binding at all only because decision 1191 §4 made the loader `&Lua`-native.
+/// Apply a template to an existing frame, `CreateFrame`'s fourth argument. Returns the warnings,
+/// then the errors. The frame always survives: an unknown name leaves it bare, as in the
+/// reference, and only virtual elements are registered. The frame's own name is the `$parent`
+/// base (`MyButton` makes `$parentText` `MyButtonText`). Runs inside the `CreateFrame` binding, so
+/// it enters at [`Loader::decorate`]: [`Loader::materialize`] would recurse.
 pub fn apply_template(lua: &mlua::Lua, wrapper: &Table, kind: &str, template: &str) -> Vec<String> {
     let template = template.trim();
     if template.is_empty() {
         return Vec::new();
     }
-    // A template is a node in the registry, never a file: `<Include>`/`<Script file=>` are
-    // top-level-only, so nothing reachable under `decorate` can ask for bytes.
+    // A template never reads a file: `<Include>` and `<Script file=>` are top-level only.
     let no_files = |_: &str| -> Option<Vec<u8>> { None };
     let mut loader = Loader {
         lua,
@@ -235,18 +110,14 @@ pub fn apply_template(lua: &mlua::Lua, wrapper: &Table, kind: &str, template: &s
         own_name.as_deref().unwrap_or("<unnamed>")
     );
 
-    // The one thing `expand` cannot tell us: what kind each named template was *declared* as. Read
-    // it straight off the registry — a diagnostic pass only; the resolution below is still the
-    // document layer's single implementation.
+    // Diagnostic only: `expand` does not say what kind a template was declared as.
     let mut notes = Vec::new();
     let mut any_resolved = false;
     {
         let model = loader.model();
         let templates = model.framexml_templates.borrow();
-        // One name, verbatim, folded — the same law `framexml::expand` resolves under, kept in
-        // step so this diagnostic cannot disagree with the resolution it describes.
+        // Looked up as `framexml::expand` looks it up (exact, then case-folded); keep them in step.
         for name in [template].into_iter().filter(|s| !s.is_empty()) {
-            // A name that is missing entirely is `expand`'s warning to give, just below.
             let Some(el) = templates.get(name).or_else(|| {
                 templates
                     .iter()
@@ -279,10 +150,7 @@ pub fn apply_template(lua: &mlua::Lua, wrapper: &Table, kind: &str, template: &s
     }
     loader.report.warnings.extend(notes);
 
-    // One expansion, through the document layer's own splice/chain/cycle path — the same call the
-    // XML `inherits=` path makes. Its warnings are terse by design (they were written for a
-    // document walk), so prefix the ones this call produced: a log line has to name the
-    // `CreateFrame` it came from or nobody can act on it.
+    // The XML `inherits=` expansion; its warnings get the `CreateFrame` call as a prefix.
     let first = loader.report.warnings.len();
     let expanded = loader.expand(&framexml::inherits_node(kind, template));
     for w in &mut loader.report.warnings[first..] {
@@ -296,16 +164,8 @@ pub fn apply_template(lua: &mlua::Lua, wrapper: &Table, kind: &str, template: &s
     out
 }
 
-/// Join a FrameXML reference against the directory of the file that contains it, **lexically**.
-///
-/// FrameXML paths are `\`- or `/`-separated and may walk up with `..` — that is how a shared
-/// library addon is reached (`..\..\BagBrother\core\core.xml`). Resolution here touches no
-/// filesystem and follows no symlink: it is pure string arithmetic, so the provider is the only
-/// thing that decides what a resolved path may reach.
-///
-/// A `..` that walks above the root is **kept** as a leading `..` rather than clamped, so the
-/// provider can see the escape and refuse it instead of silently being handed a path that looks
-/// contained.
+/// Join a FrameXML reference to its file's directory, lexically: `\` and `/` both separate, `..`
+/// walks up. A `..` above the root is kept, not clamped, so the provider can refuse the escape.
 pub fn join_ref(base: &str, path: &str) -> String {
     let path = path.replace('\\', "/");
     let combined = if path.starts_with('/') || base.is_empty() {
@@ -329,27 +189,21 @@ pub fn join_ref(base: &str, path: &str) -> String {
     out.join("/")
 }
 
-/// Is `tag` one of the four model-pane kinds — the `CSimpleModel` family, whose own `LoadXML`
-/// (`0x76cac0`) reads the `scale=` attribute into the MODEL scale (`geometry.rs`'s
-/// `apply_attrs`, decision 2007).
+/// A `CSimpleModel` kind, whose `LoadXML` (`0x76cac0`) reads `scale=` as the model's scale.
 pub(super) fn model_kind_tag(tag: &str) -> bool {
     ["Model", "PlayerModel", "DressUpModel", "TabardModel"]
         .iter()
         .any(|k| k.eq_ignore_ascii_case(tag))
 }
 
-/// The `.lua` test `0x6ede10` opens with: `strrchr(path, '.')` on the **whole resolved path**,
-/// then a **case-insensitive** compare against `".lua"` (`0x8710c8`, through `0x64a4c0`).
-///
-/// Deliberately the last dot anywhere in the path rather than the basename's, because that is what
-/// `strrchr` does — a directory carrying a dot and a file carrying none would take the same branch
-/// in the client as it does here.
+/// The `.lua` test `0x6ede10` opens with: the last `.` anywhere in the resolved path, not the
+/// basename's (`strrchr`), compared case-insensitively to `".lua"` (`0x8710c8`, via `0x64a4c0`).
 fn has_lua_suffix(path: &str) -> bool {
     path.rsplit_once('.')
         .is_some_and(|(_, ext)| ext.eq_ignore_ascii_case("lua"))
 }
 
-/// The directory part of a provider path — `""` for a bare name.
+/// The directory part of a provider path, `""` for a bare name.
 fn dir_of(path: &str) -> &str {
     match path.rfind('/') {
         Some(i) => &path[..i],
@@ -358,41 +212,27 @@ fn dir_of(path: &str) -> &str {
 }
 
 struct Loader<'a> {
-    /// **The VM itself, not a `UiScript`** — every piece of state this loader touches
-    /// (the two FrameXML registries, the font objects, the chunk runner) is reachable from a bare
-    /// `&Lua` through [`Model`]. That is what lets `LoadAddOn` load an addon from inside a Lua
-    /// binding, synchronously, the way the reference does (1188 phase 2): a binding is handed
-    /// `&Lua` and can never obtain the `&UiScript` that owns it.
+    /// The VM, not a `UiScript`: a Lua binding such as `LoadAddOn` holds only `&Lua`, and loads
+    /// an addon synchronously from inside the binding, as the reference does.
     pub(super) lua: &'a mlua::Lua,
     pub(super) files: &'a dyn Fn(&str) -> Option<Vec<u8>>,
-    /// The current document's own path in the provider's path space. Its **directory**
-    /// ([`Loader::base`]) is what a relative `<Include>`/`<Script file=>` inside it resolves
-    /// against; its **whole path** is what names an inline `<Script>`'s chunk. Saved and restored
-    /// around each nested include, so depth-1 and depth-5 both resolve — and report — against
-    /// their own file.
+    /// The current document's path: its directory resolves relative references, the whole path
+    /// names inline `<Script>` chunks. Swapped for each nested include and restored after.
     pub(super) path: String,
-    // The template + font-element registries live on the `Model` (`framexml_templates` /
-    // `framexml_fonts`), persisted ACROSS `load` calls — the client's template table is global
-    // (`0x6ee500`), so a file may `inherits=` a template an earlier file registered (the real
-    // MerchantFrame.xml ← CharacterFrameTemplates.xml). "Register before use" in load order,
-    // including through `<Include>`s. Fonts are a separate namespace (a font inherits a font,
-    // never a frame template); each stored font element is already inherits-resolved so a later
-    // font inheriting it reads fully-flattened values (rf24).
+    // The template and font registries live on the `Model` and persist across loads: the
+    // reference's template table is global (`0x6ee500`), so `MerchantFrame.xml` inherits a template
+    // `CharacterFrameTemplates.xml` registered. Fonts are their own namespace, stored flattened.
     pub(super) report: LoadReport,
-    /// Warn-once keys (so a document with 200 `OnClick` handlers doesn't emit 200 identical warnings).
+    /// Warn-once keys.
     pub(super) warned: HashSet<String>,
-    /// Anchors whose named `relativeTo` did not resolve when its element was read, applied once
-    /// the enclosing frame's subtree exists ([`Loader::drain_deferred_anchors`]). The real
-    /// client is order-free here because it resolves anchors at layout, after every child of
-    /// the frame is built; this loader resolves a name at `SetPoint` time, so a `<ButtonText>`
-    /// hung off a `<HighlightTexture>` declared after it (the stock trainer row) — or a state
-    /// texture hung off the label declared after IT (the sort-header arrow) — needs the same
-    /// grace. Each entry belongs to the `decorate` that pushed it and drains there, so a nested
-    /// frame's anchors never wait for its parent (1957).
+    /// Anchors whose named `relativeTo` did not exist yet, applied once the enclosing frame's
+    /// subtree is built: the reference resolves anchors at layout, this loader at `SetPoint`, so a
+    /// target built later waits here (`ClassTrainerFrameTemplates.xml:67` hangs the label off the
+    /// highlight). Each `decorate` drains its own.
     pub(super) deferred_anchors: Vec<DeferredAnchor>,
 }
 
-/// One `SetPoint` the loader holds until its target can exist — see `Loader::deferred_anchors`.
+/// One `SetPoint` held until its target exists.
 pub(super) struct DeferredAnchor {
     pub(super) wrapper: Table,
     /// A region wrapper (`call_region`) rather than a frame's (`call`).
@@ -406,33 +246,20 @@ impl Loader<'_> {
         self.lua
     }
 
-    /// The current document's own directory — what a relative `<Include>`/`<Script file=>` inside
-    /// it resolves against.
+    /// The current document's directory, which its relative references resolve against.
     fn base(&self) -> &str {
         dir_of(&self.path)
     }
 
-    /// Run a chunk in the one global state — `UiScript::run`'s body, reachable from `&Lua`.
-    ///
-    /// Takes **bytes**, because a `<Script file=>` chunk is whatever is on disk (decision 1193) and
-    /// Lua 5.0 strings are byte strings. An inline `<Script>` body arrives as `&str` from the XML
-    /// and is passed through as its own bytes, which is the same thing.
-    ///
-    /// `path` names the chunk, and **naming it is not cosmetic**: mlua's `load` is `#[track_caller]`
-    /// and an unnamed chunk is named after the Rust line that loaded it, so every raise from every
-    /// FrameXML and addon `<Script>` block in this project reported `loader/mod.rs` as its source
-    /// (decision 1217). Lua's leading `@` is what makes it a *file* name rather than a quoted
-    /// source snippet, and the separator is `\` because that is the shape an addon parsing its own
-    /// `debugstack()` matches against (`crate::script::addon_chunk_name`).
+    /// Run a file chunk (bytes, as on disk) in the one global state, named after its path. The
+    /// name matters: unnamed, mlua's `#[track_caller]` `load` names it after this Rust line.
     fn run(&self, chunk: &[u8], path: &str) -> mlua::Result<()> {
-        // A FILE chunk is `"@%s"` (`0x8716e0`) over the resolved path — `0x704bc0` builds it that
-        // way for every `.lua` the loader touches, and `luaO_chunkid`'s `@` branch prints it
-        // plainly (wow-re `scratch/include-lua-dispatch.md` §7).
+        // The reference's file chunk name, `"@%s"` (`0x8716e0`, `0x704bc0`; a file name to
+        // `luaO_chunkid 0x6f5c40`), with `\` separators as in `crate::script::addon_chunk_name`.
         self.run_named(chunk, &format!("@{}", path.replace('/', "\\")))
     }
 
-    /// Run a chunk under a chunk name given **whole** — for the producers whose name is not a
-    /// path. See the inline `<Script>` arm in [`Self::load_doc`].
+    /// Run a chunk under a complete chunk name, for a producer whose name is not a path.
     fn run_named(&self, chunk: &[u8], name: &str) -> mlua::Result<()> {
         self.lua
             .load(chunk)
@@ -441,15 +268,13 @@ impl Loader<'_> {
             .exec()
     }
 
-    /// The model, for the two FrameXML registries below.
     fn model(&self) -> mlua::AppDataRefMut<'_, crate::script::Model> {
         self.lua
             .app_data_mut::<crate::script::Model>()
             .expect("model app_data")
     }
 
-    /// Run a widget handler with the client's calling convention — `UiScript::invoke_handler`'s
-    /// body, reachable from `&Lua`.
+    /// Run a widget handler with the client's calling convention, from `&Lua`.
     pub(super) fn invoke_handler(
         &self,
         wrapper: &mlua::Table,
@@ -464,33 +289,10 @@ impl Loader<'_> {
         }
     }
 
-    /// A `text=` attribute is a **GLOBAL-STRING LOOKUP, not a literal** — the single most load-bearing
-    /// thing about the attribute, and the one this loader used to get wrong.
-    ///
-    /// wow-re `system/ui/scratch/rf28-typed-widget-loadxml.md`: `<Button text=>` (l.36) and
-    /// `<FontString text=>` (l.115) BOTH resolve through `FrameScript_GetText 0x703bf0`, which
-    /// `scratch/framescript.md` carves VERIFIED — it resolves the value as a Lua global and,
-    /// **when that global is not a string, returns a pre-seeded EMPTY string** (`0x882748`), never
-    /// the key name. That is why the reference's `text="LOGOUT"` renders "Logout", and why
-    /// `GlobalStrings.lua` runs before any XML (`ui_script::load_global_strings`).
-    ///
-    /// **The MISS falls back to the raw attribute, and that is the reference's own behaviour — not
-    /// a benilla divergence, which is what this comment used to claim.** `0x703bf0`'s empty return
-    /// never reaches a label: all three `text=` readers image-wide test it and substitute the raw
-    /// attribute string. `Button::LoadXML` at `0x778c07` — recorded in wow-re
-    /// `scratch/template-onload-replacement-law.md` §5, "a fallback to the raw attribute when the
-    /// lookup comes back empty (`0x778c31 mov eax,esi`)" — and byte-identically
-    /// `CSimpleFontString::LoadXML` at `0x771006` (`771012 mov esi,eax` … `771029 test eax,eax` /
-    /// `77102b je 0x771032` / `77102d cmp BYTE [eax],0` / `771030 jne` / `771032 mov eax,esi`), and
-    /// the third reader at `0x7292a6`, which expresses the same law through a copy
-    /// (`7292db mov al,[ebp-0x424]` / `7292e1 test al,al`, empty arm pushes `edi` = the raw).
-    ///
-    /// So the reference's `PetPaperDollFrame.xml:70` `text="Level level race class"` really does
-    /// draw that placeholder until Lua overwrites it, and benilla's plain-English `text="Send
-    /// Mail"` renders for the same reason the reference's would. What IS ours is the extra signal:
-    /// a **key-shaped** value that misses warns here as well as keeping its key on screen — the
-    /// signal that was missing when the macro window shipped with "CREATE_MACROS" across its title
-    /// bar (0983 → 0991).
+    /// Resolve `text=` as a global-string key (`FrameScript_GetText 0x703bf0`), so
+    /// `GlobalStrings.lua` must run before any XML. A miss comes back empty (`0x882748`) and all
+    /// three `text=` readers then show the raw value (`0x778c07`, `0x771006`, `0x7292a6`). The
+    /// warning on a key-shaped miss is benilla's own.
     pub(super) fn resolve_text(&mut self, raw: &str, dbg: &str) -> String {
         if let Ok(s) = self.lua().globals().get::<String>(raw) {
             return s;
@@ -507,34 +309,16 @@ impl Loader<'_> {
         raw.to_string()
     }
 
-    /// Walk one document's top-level items in order (rf24-framexml-loader.md, `0x6ede10`).
+    /// Walk one document's top-level items in order (`0x6ede10`).
     pub(super) fn load_doc(&mut self, doc: &ParsedDocument) {
         for item in &doc.items {
             match item {
                 TopLevel::Include(path) => self.do_include(path),
-                // **A DELIBERATE DIVERGENCE, and a strict superset of the reference.**
-                //
-                // `<Script file=X>` does NOT share `<Include>`'s path law. `0x6ee070`-`0x6ee079`
-                // tests X itself for a separator and, when it has one, uses X **verbatim** — no
-                // `dirname(referrer)` prefix, and no `..` collapse either, since that arm never
-                // enters `0x6ede10`. Only a *bare* name gets `dirname(referrer) + name`.
-                //
-                // A verbatim value cannot open on 1.12. Resolution runs through `0x647e60` against
-                // a hash index whose key is each file's path **relative to the scan root**, and the
-                // root is the process CWD (Storm's base-path global `0xc52418` has no writer
-                // image-wide, so `0x646ebc` substitutes `"."`). The basename retry at `0x647ed3` is
-                // real code but off — it needs a flag bit that `0x648be0(0)` clears at startup. So
-                // `Libs\Ace\Ace.lua` misses every leg: full-string, base-prefixed and the MPQ
-                // chain. There is no per-addon or per-document current directory anywhere in the
-                // client. (wow-re `scratch/include-lua-dispatch.md` §4.1.)
-                //
-                // We resolve it against the including document's directory anyway. That converts a
-                // guaranteed failure into a success and **cannot break anything that worked on the
-                // reference**, because under 1.12 there is no install-root `Libs\` for the verbatim
-                // value to have found. The corpus addons carrying the form are TBC-era anyway —
-                // all three report `iface=20400` and ship LibStub/CallbackHandler-1.0, none of
-                // which existed in 1.12 — so reproducing the failure would buy nothing and cost
-                // `FuBar_AtlasFu`, which works today.
+                // Deviation: a `<Script file=>` value with a separator joins the including
+                // document's directory, like a bare name. The reference uses it verbatim
+                // (`0x6ee070`-`0x6ee079`) against the process CWD (`0x647e60`, `0x646ebc`; the
+                // basename retry at `0x647ed3` is off), where it never opens, so joining breaks
+                // nothing that loads on 1.12.
                 TopLevel::Script(ScriptRef::File(path)) => {
                     let joined = join_ref(self.base(), path);
                     match (self.files)(&joined) {
@@ -552,23 +336,13 @@ impl Loader<'_> {
                     }
                 }
                 TopLevel::Script(ScriptRef::Inline { body, line }) => {
-                    // Padded to the block's own offset in the XML, so Lua counts from where the
-                    // file does. A chunk always starts at line 1; naming it after the file without
-                    // this would make every reported line a confident, checkable lie.
+                    // Deviation: padded to the block's line, so a raise reports a line a reader can
+                    // find in the file; the reference counts from the body's first line.
                     let mut chunk = "\n".repeat(line.saturating_sub(1) as usize).into_bytes();
                     chunk.extend_from_slice(body.as_bytes());
-                    // **Not a file name.** The reference names an inline `<Script>` body
-                    // `"%s:<Scripts>"` (`0x871074`) over the XML document's own path, with NO `@`
-                    // — `0x6ee0ed push ebx` / `0x6ee0ee push 0x871074` → `0x6ee0ff` sprintf →
-                    // `0x6ee10f call 0x704cd0`. So `luaO_chunkid` takes its third branch and the
-                    // frame reads `[string "Interface\FrameXML\Foo.xml:<Scripts>"]`, not a path.
-                    // Writing `@path` here made an inline block indistinguishable from the `.lua`
-                    // file beside it — including to the addons that split a `debugstack` frame on
-                    // `\AddOns\`.
-                    //
-                    // The padding above stays (1214): the reference's line numbers here are
-                    // body-relative, ours are the XML file's, and the file's are the ones a reader
-                    // can go and check — the name now carries the path that makes them checkable.
+                    // The reference names an inline body `"%s:<Scripts>"` (`0x871074`, formatted at
+                    // `0x6ee0ff`) over the document's path with no `@`, so a raise reads
+                    // `[string "Interface\FrameXML\Foo.xml:<Scripts>"]`, not a file path.
                     let name = format!("{}:<Scripts>", self.path.replace('/', "\\"));
                     if let Err(e) = self.run_named(&chunk, &name) {
                         self.report.errors.push(format!("inline <Script>: {e}"));
@@ -576,9 +350,8 @@ impl Loader<'_> {
                 }
                 TopLevel::Font(el) => self.do_font(el),
                 TopLevel::Template(el) => {
-                    // Register the raw (un-expanded) node; `expand` chain-resolves any `inherits` it
-                    // carries at instantiation time. An unnamed virtual node was already warned at
-                    // parse time and cannot be inherited, so it is simply not registered.
+                    // Registered raw; `expand` resolves its own `inherits` at instantiation. An
+                    // unnamed one was warned at parse time.
                     if let Some(name) = el.name() {
                         self.model()
                             .framexml_templates
@@ -603,25 +376,10 @@ impl Loader<'_> {
             ));
             return;
         };
-        // **`<Include>` dispatches on the EXTENSION, and a `.lua` target is RUN, not parsed.**
-        //
-        // `0x6ede10` is not "the XML loader" — it is *load one file by path*, and its first act
-        // after the `..` collapse is a case-insensitive `.lua` suffix test on the **resolved** path
-        // (`0x6edee6`-`0x6edf0f`: `strrchr(path,'.')`, then a case-insensitive compare against
-        // `".lua"` @`0x8710c8`). Extension, never a content sniff — no byte of the file has been
-        // read at that point. A match runs the chunk (`0x6edf0f call 0x704bc0`, chunk name
-        // `"@<resolved path>"` via `0x8716e0`); anything else is opened and parsed as XML.
-        //
-        // `<Include file=X>` is a **recursion into that same routine** (`0x6ee00d`), so it inherits
-        // the dispatch for free: there is no `<Include>`-specific Lua code in the client at all,
-        // and it is the same mechanism that makes a `.lua` line in a `.toc` work. Which is also the
-        // internal evidence that this was ours and not the corpus's — our own `.toc` loader has
-        // always split on extension (`ui_script::addons`, 1185), and only this arm never did.
-        //
-        // Three addons ship the form — FonzAppraiser (67 sites), AckisRecipeList (24), FonzSummon
-        // (22): an authoring habit rather than a convention, but each lost its ENTIRE library set
-        // here, because `embeds.xml` is nothing but these lines. (wow-re
-        // `scratch/include-lua-dispatch.md`, §5-verified.)
+        // `<Include>` recurses (`0x6ee00d`) into the reference's load-one-file routine `0x6ede10`,
+        // which dispatches on the resolved path's extension, never its content: a `.lua` suffix
+        // (`0x6edee6`-`0x6edf0f`) runs the file as a chunk (`0x704bc0`), anything else parses as
+        // XML. A `.toc` line goes through the same routine.
         if has_lua_suffix(&joined) {
             if let Err(e) = self.run(crate::source::chunk(&bytes), &joined) {
                 self.report
@@ -630,13 +388,11 @@ impl Loader<'_> {
             }
             return;
         }
-        // An included document is the one place text is forced: roxmltree parses `&str` (1193).
+        // Only an included document is decoded to text: roxmltree parses `&str`.
         match framexml::parse(&crate::source::decode(&bytes)) {
             Ok(sub) => {
                 self.report.warnings.extend(sub.warnings.iter().cloned());
-                // The included document's OWN path is what ITS relative references resolve against
-                // and what ITS inline scripts are named after — restored after, so a sibling
-                // include at this level is unaffected.
+                // The included document resolves and names against its own path until it is done.
                 let outer = std::mem::replace(&mut self.path, joined.clone());
                 self.load_doc(&sub);
                 self.path = outer;
@@ -648,15 +404,13 @@ impl Loader<'_> {
         }
     }
 
-    /// Resolve `inherits=` against the script's persistent registry (`framexml::expand`),
-    /// folding its warnings into the report.
+    /// Resolve `inherits=` against the persistent template registry (`framexml::expand`).
     pub(super) fn expand(&mut self, el: &Element) -> Element {
         let model = self.model();
         let templates = model.framexml_templates.borrow();
         let view: HashMap<&str, &Element> =
             templates.iter().map(|(k, v)| (k.as_str(), v)).collect();
-        // The font namespace, so a font object inside an inherit chain is skipped rather than
-        // warned as an unknown template (1874).
+        // A font object in an inherit chain is skipped, not warned as an unknown template.
         let fonts = model.framexml_fonts.borrow();
         let font_names: std::collections::HashSet<&str> =
             fonts.keys().map(|k| k.as_str()).collect();
@@ -671,11 +425,8 @@ impl Loader<'_> {
         out
     }
 
-    /// [`Loader::expand`] for a `<Texture>`/`<FontString>` REGION — gated on the `inherits=`
-    /// naming at least one registered element template, because a FontString's `inherits=`
-    /// usually names a font OBJECT (`framexml_fonts`, a separate namespace resolved by
-    /// `apply_fontstring_font`), which must pass through untouched rather than warn as an
-    /// unknown template. The talent branch/arrow art pool is the first region-template user.
+    /// [`Loader::expand`] for a region, only when `inherits=` names a registered element template:
+    /// a FontString's `inherits=` usually names a font object, which passes through unwarned.
     pub(super) fn expand_region(&mut self, el: &Element) -> Element {
         let hit = el.attr("inherits").is_some_and(|names| {
             let model = self.model();
@@ -692,16 +443,12 @@ impl Loader<'_> {
         }
     }
 
-    /// A top-level `<Font name=…>`: resolve its `inherits=` chain against the accumulated font
-    /// registry (a *separate* namespace from frame templates — a font inherits another font, never a
-    /// frame), read the flattened `{font, height, color, outline, justifyH}`, register the resolved
-    /// [`FontObject`] in the engine, and store the merged element so later fonts inheriting this one
-    /// see fully-flattened values. An unnamed `<Font>` was already warned at parse time; skip it.
+    /// A top-level `<Font name=…>`: flatten its `inherits=` chain (fonts inherit only fonts),
+    /// register the [`FontObject`] and store the flattened element for later fonts to inherit.
     pub(super) fn do_font(&mut self, el: &Element) {
         let Some(name) = el.name().map(str::to_string) else {
             return;
         };
-        // Resolve `inherits` against the font registry (reuse the generic template merge).
         let merged = {
             let model = self.model();
             let fonts = model.framexml_fonts.borrow();
@@ -717,27 +464,17 @@ impl Loader<'_> {
         };
 
         let font = font_object_from_element(&merged);
-        // One model borrow, then the insert — `font_objects` and `framexml_fonts` are both on it.
         {
             let mut model = self.model();
             model
                 .font_objects_by_lower
                 .insert(name.to_ascii_lowercase(), font);
-            // Store the merged (flattened) node so a chain rooted here reads resolved values.
             model
                 .framexml_fonts
                 .borrow_mut()
                 .insert(name.clone(), merged);
         }
-        // …and publish `_G[name]` as a real font OBJECT. In 1.12 a `<Font name="GameFontNormal">`
-        // is not only a style record: it is addressable Lua, and that is how the whole addon
-        // ecosystem paints text — `fs:SetFontObject(GameFontNormal)` is 3,180 of the corpus's 3,186
-        // call sites, against 6 that pass a string. Registering the record without ever publishing
-        // the name is why `Gratuity-2.0.lua:57` was handed nil and took five addons down at load.
-        // The object and its method surface are `crate::script::font`.
-        //
-        // Flattening is untouched: the merge above still resolves the `inherits=` chain once, at
-        // load, and publishing only gives the result a name.
+        // In 1.12 a named `<Font>` is also a Lua global, the object `SetFontObject` takes.
         if let Err(e) = crate::script::font::publish(self.lua(), &name) {
             self.report
                 .warnings
@@ -745,41 +482,21 @@ impl Loader<'_> {
         }
     }
 
-    /// Materialize one (already template-expanded) frame element into a live frame, then recurse its
-    /// nested `<Frames>` and fire its `OnLoad` **after** them (bottom-up, rf26).
-    ///
-    /// `parent` is the **lexically** enclosing frame's wrapper (`None` at top level) and
-    /// `parent_name` its already-resolved name (or `"Top"`). A `parent=` attribute overrides both,
-    /// and it is the *effective* parent that `$parent` substitutes against — in this frame's name
-    /// and in its anchors' `relativeTo` (rf27).
-    /// Returns the created frame's wrapper — `None` when `CreateFrame` refused (an unknown frame
-    /// type, rf24 `0x6ee280`'s factory-table miss), which also skips the whole subtree. The
-    /// `<ScrollChild>` pass is the one caller that needs the handle back.
+    /// Build one template-expanded frame element, its nested `<Frames>`, then its `OnLoad`
+    /// (bottom-up, `0x76a060`). `parent` is the lexically enclosing frame, which `parent=`
+    /// overrides; `None` when the frame type is unknown, which skips the subtree.
     pub(super) fn materialize(
         &mut self,
         el: &Element,
         parent: Option<&Table>,
         parent_name: &str,
     ) -> Option<Table> {
-        // ─ Step 1 and ONLY step 1 lives here: resolve the parent, resolve the name against it,
-        //   and call CreateFrame. Everything after it is `decorate`, because the runtime template
-        //   path enters at exactly that seam (`apply_template`) — its frame already exists, and
-        //   re-entering here would recurse.
+        // Only creation lives here: everything after `CreateFrame` is `decorate`, which
+        // `apply_template` enters for a frame that already exists.
 
-        // 0 · **The type lookup, and its XML miss LOGS and skips the node** (decision 2191).
-        //
-        //     `Instantiate 0x6ee280` looks the element's own tag up first (`0x6ee2e5 mov
-        //     edi,[esi+8]`, before `parent=` is read), and on a miss prints `"Unknown frame type:
-        //     %s"` (`0x871124`) at `0x6ee356` into the document's log and makes no object for that
-        //     node — non-fatal, and the walk goes on to the next sibling (wow-re
-        //     `taxiroute-widget-type.md`, `lootbutton-widget-type.md` §1). Only the Lua door
-        //     raises. We used to reach the registry through the Lua `CreateFrame`, so an XML miss
-        //     became a `report.errors` row — a script error the player sees — for a document the
-        //     client shrugs at. The live case: an addon whose `.toc` lists its own `Bindings.xml`
-        //     (MonkeyDev). The toc line runner hands it to the same file loader as any `.xml`, its
-        //     `<Binding>` children are not `Include`/`Script`/`Font`, so each is a frame element
-        //     whose type does not exist — three log lines in the reference, three red dialogs here
-        //     — while the file's real reading as bindings happens at `0x51f400` regardless.
+        // 0 · The type lookup. `Instantiate 0x6ee280` checks the tag before reading `parent=`; a
+        //     miss logs `"Unknown frame type: %s"` (`0x871124`, at `0x6ee356`), builds nothing for
+        //     the node and goes on to the next sibling. Only the Lua door raises.
         if crate::script::object::registered_frame_kind(self.lua(), &el.tag).is_none() {
             self.report
                 .warnings
@@ -787,57 +504,24 @@ impl Loader<'_> {
             return None;
         }
 
-        // 1a · `parent="SomeFrame"` — the OTHER way an element names its parent, and the one the
-        //      reference's own FrameXML uses most, because its files are flat: `<Frame name="X"
-        //      parent="UIParent">` at top level rather than nested inside `<Frames>`. We only ever
-        //      read the lexical parent, so **708 corpus sites across 79 addons** produced a frame
-        //      with `GetParent() == nil` — no visibility inheritance, no scale or alpha
-        //      inheritance, and `this:GetParent():Hide()` raising on a nil. Nothing warned, because
-        //      an ignored attribute is not an error: 1205's silent-drop class again.
-        //
-        //      The attribute WINS over the lexical parent when both are present, which is the
-        //      reference's rule and is what lets an addon nest an element for authoring
-        //      convenience and still attach it elsewhere.
-        //
-        //      **The attribute is NOT `$parent`-expanded.** `0x6ee280` hands the raw string to the
-        //      by-name resolver `0x76c760` **directly** at `0x6ee3e8`, bypassing the expander that
-        //      `name=` and `relativeTo=` reach through `SetName`/`0x76c700` (rf27 §2 and
-        //      `name-string-widget-resolution.md` §9, both VERIFIED). Nothing in ~1100 corpus XML
-        //      files writes `parent="$parent…"`, so expanding it was a dead deviation — but a dead
-        //      deviation on this line is exactly what made 2208's live one hard to see.
-        //
-        //      **Three outcomes, not two** (decision 2213, wow-re `xml-parent-attach-order.md`):
-        //      the slot `[ebp-0x8]` is seeded at `0x6ee28b` with the incoming default parent, and
-        //      `0x6ee3ef mov [ebp-0x8],eax` writes the lookup's result back **unconditionally** —
-        //      so a *miss* stores 0 over that seed and the frame is constructed **parentless**
-        //      (`0x6ee408 mov ecx,[ebp-0x8]`), after logging `0x8710f0`. It does NOT fall back to
-        //      the enclosing frame, which is what we used to do; the divergence is invisible at
-        //      top level (there is no enclosing frame to fall back to) and only shows on a nested
-        //      element naming a parent that is not loaded yet. And an **empty** `parent=""`
-        //      short-circuits earlier still, at `0x6ee3c7`: the default parent is kept, silently,
-        //      and the `inherits` chain is not consulted for one — only an *absent* attribute
-        //      walks it (which for us happens in template expansion, upstream of here).
-        //
-        //      `None` = no attribute, or an empty one: keep the enclosing parent.
-        //      `Some(None)` = named a parent that does not resolve: parentless, and logged.
+        // 1a · `parent=` wins over the lexical parent, unexpanded: `0x6ee280` hands the raw value
+        //      to the by-name lookup `0x76c760` (at `0x6ee3e8`). A miss is logged and stores 0 over
+        //      the default parent (`0x6ee3ef`), so the frame is built parentless (`0x6ee408`); an
+        //      empty `parent=""` keeps the default parent silently (`0x6ee3c7`).
+        //      `None`: no attribute, or an empty one. `Some(None)`: a miss, parentless and logged.
         let attr_parent: Option<Option<Table>> =
             el.attr("parent")
                 .filter(|name| !name.is_empty())
                 .map(|name| {
-                    // A FRAME, not merely a global of that name. `_G` is one namespace: an addon's own
-                    // `MyAddon = {}` sits in it beside every frame, and the corpus really does write
-                    // `parent="TheoryCraft"` where the addon owns that name. Handing a plain table to
-                    // `CreateFrame` would raise and take the element's whole subtree with it — a name
-                    // collision costing a window. The identity test is RF-0023's own: a frame wrapper
-                    // carries its handle at `T[0]` as lightuserdata, and nothing else does. The
-                    // reference's own `0x76c760` reads the frame registry, so a non-frame global of
-                    // the right name is the same miss, with the same message.
+                    // Only a frame counts: `0x76c760` reads the frame registry, so a non-frame
+                    // global of that name is a miss. A frame wrapper is the one table carrying
+                    // lightuserdata at `[0]` (`0x6f3ea0`).
                     let hit =
                         self.lua().globals().get::<Table>(name).ok().filter(|t| {
                             matches!(t.raw_get::<Value>(0), Ok(Value::LightUserData(_)))
                         });
                     if hit.is_none() {
-                        // The reference's own wording (`0x8710f0`), like the frame-type miss above.
+                        // The reference's wording (`0x8710f0`).
                         self.report
                             .warnings
                             .push(format!("Couldn't find frame parent: {name}"));
@@ -849,32 +533,11 @@ impl Loader<'_> {
             None => parent,
         };
 
-        // 1b · **The name, resolved AFTER the parent — and against it** (B387). `$parent` is not a
-        //      lexical token: `SetName 0x76c650` expands it in `0x76c5b0` by walking the frame's
-        //      **actual** parent chain (`this+0x9c`) to the nearest non-empty name, seeded `"Top"`
-        //      (rf27, VERIFIED). And in `Instantiate 0x6ee280` the parent is attached *first* —
-        //      resolved at `0x6ee3e8` into `[ebp-0x8]` and passed as `ecx` to the factory's
-        //      constructor at `0x6ee408 call [ebx+0x18]` — while the node-apply step that reads
-        //      `name=` and calls `SetName` runs only afterwards, at `0x6ee4d6 call [edx+0x20]`
-        //      (read off `system/ui/scratch/disasm-full.txt`, the whole body linear between the
-        //      two). So a **top-level** element whose name leans on `$parent` and whose parent
-        //      comes from the attribute resolves against that attribute's frame.
-        //
-        //      We did it the other way round: the name was substituted against the *lexical*
-        //      ancestor — `"Top"` for a top-level element — and never recomputed once the
-        //      attribute rebound the parent. ClassIcons' `<Frame name="$parentClassIcon"
-        //      inherits="UnitFrameClassIconTemplate" parent="PlayerFrame"/>` was therefore
-        //      published as `TopClassIcon`, and the addon's `PlayerFrameClassIcon:SetPoint` at
-        //      `ClassIcons.lua:228` indexed a nil.
-        //
-        //      The base name comes from the parent FRAME, not from the attribute text — the
-        //      reference reads `p->GetName()`, so a `parent="playerframe"` that resolves
-        //      case-insensitively still yields `PlayerFrame…`; and a parent that is itself
-        //      nameless walks on up, which is what [`Self::frame_names`] already does for the
-        //      runtime template path.
-        //      A parent the attribute nulled leaves the chain walk with nothing to find, so the
-        //      seed survives and `$parent` is `"Top"` — the same answer, by the same route, as a
-        //      top-level element with no parent at all.
+        // 1b · The name resolves after the parent, against it. `Instantiate 0x6ee280` passes the
+        //      parent to the constructor (`0x6ee408`) before it applies `name=` (`0x6ee4d6`), and
+        //      `SetName 0x76c650` expands `$parent` by walking the real parent chain to the nearest
+        //      name, seeded `"Top"` (`0x76c5b0`). The base is the parent frame's own name, not the
+        //      attribute text; a nulled parent leaves the `"Top"` seed.
         let attr_parent_name: Option<String> =
             attr_parent.as_ref().map(|resolved| match resolved {
                 Some(p) => {
@@ -884,15 +547,11 @@ impl Loader<'_> {
                 None => framexml::DEFAULT_PARENT_NAME.to_string(),
             });
         let parent_name = attr_parent_name.as_deref().unwrap_or(parent_name);
-        // The resolved name is what CreateFrame publishes and what this frame's own children
-        // substitute `$parent` against.
         let resolved_name: Option<String> = el
             .name()
             .map(|raw| framexml::resolve_name(raw, parent_name));
 
-        // 1 · CreateFrame(kind = element tag, name, parent). The type is already known to resolve
-        //     (step 0), so an error here is something else the call raised — record it and skip
-        //     the whole subtree.
+        // 1 · `CreateFrame(tag, name, parent)`; the type is known, so an error is a real raise.
         let create: Function = match self.lua().globals().get("CreateFrame") {
             Ok(f) => f,
             Err(e) => {
@@ -923,37 +582,25 @@ impl Loader<'_> {
             .clone()
             .unwrap_or_else(|| format!("<{}>", el.tag));
 
-        // The one trace site walked to the bytes — `Instantiate 0x6ee280`'s
-        // `0x871154 "-- Creating %s named %s"`, gated `flag > 0` at `0x6ee298` (decision 2160).
-        // The kind is the element tag, which is what the reference's first `%s` carries.
+        // One of the reference's five loader traces: `Instantiate 0x6ee280`'s `"-- Creating %s
+        // named %s"` (`0x871154`), gated `flag > 0` at `0x6ee298`; the first `%s` is the tag.
         if self.model().framexml_debug.get() > 0 {
             self.report
                 .traces
                 .push(format!("-- Creating {} named {dbg_name}", el.tag));
         }
 
-        // This frame's own name is what its *contents* (regions, nested frames) substitute `$parent`
-        // against (rf27: a region/child's parent is this frame); a nameless frame passes the nearest
-        // named ancestor through unchanged. This frame's *own* anchors, by contrast, substitute
-        // `$parent` against `parent_name` (their `$parent` is this frame's enclosing parent).
+        // `$parent` for its contents; a nameless frame passes its nearest named ancestor on.
         let self_name = resolved_name.as_deref().unwrap_or(parent_name).to_string();
 
         self.decorate(el, &wrapper, &self_name, parent_name, &dbg_name);
         Some(wrapper)
     }
 
-    /// Everything a frame element does to a frame that **already exists**: LoadXML attributes,
-    /// `<Size>`, `<Anchors>`, `<Layers>` regions, the per-kind extras, `<Scripts>`, the nested
-    /// `<Frames>` pass, and finally this frame's own `OnLoad` (bottom-up, rf26).
-    ///
-    /// Split out of [`Self::materialize`] because materialize's *first* step is `CreateFrame`, and
-    /// the runtime template path — [`apply_template`], i.e. `CreateFrame`'s own fourth argument —
-    /// is called from **inside** that binding. It cannot re-enter materialize without recursing
-    /// forever; it enters here instead, and the two paths share every step that follows.
-    ///
-    /// The two names are not the same thing and the difference is the load-bearing one (rf27):
-    /// `self_name` is what `$parent` means to this frame's **contents** (its regions, its nested
-    /// frames), `parent_name` is what `$parent` means to this frame's **own** anchors.
+    /// Everything a frame element does to an existing frame, from `LoadXML` attributes to its
+    /// `OnLoad` (last, bottom-up, `0x76a060`); shared by [`Self::materialize`] and
+    /// [`apply_template`]. `$parent` is `self_name` in this frame's contents and `parent_name` in
+    /// its own anchors (`0x76c5b0`).
     pub(super) fn decorate(
         &mut self,
         el: &Element,
@@ -962,30 +609,23 @@ impl Loader<'_> {
         parent_name: &str,
         dbg_name: &str,
     ) {
-        // Everything this frame defers drains before its OnLoad (step 8 below); a nested frame's
-        // own deferrals drain inside ITS decorate, so the mark is this frame's alone.
+        // This frame's deferred anchors drain before its OnLoad; a nested frame drains its own.
         let deferred_mark = self.deferred_anchors.len();
-        // 2 · LoadXML attributes (rf24 `0x769820`).
+        // 2 · LoadXML attributes (`0x769820`).
         self.apply_attrs(el, wrapper, dbg_name);
-        // 3 · <Size> and 4 · <Anchors> (the CLayoutFrame geometry base, rf24 `0x767800`).
+        // 3 · <Size> and 4 · <Anchors> (the CLayoutFrame geometry base, `0x767800`).
         self.apply_size(el, wrapper, dbg_name);
         self.apply_anchors(el, wrapper, parent_name, dbg_name);
-        // 5 · <Layers> regions (rf24 `0x769d70`) — `$parent` in a region name is *this* frame.
+        // 5 · <Layers> regions (`0x769d70`); `$parent` in a region name is this frame.
         self.apply_layers(el, wrapper, self_name, dbg_name);
-        // 5·b — a frame's **direct-child** `<FontString>` (outside `<Layers>`): the engine's special
-        // font string (a ScrollingMessageFrame's line font, an EditBox's text font). Created on
-        // OVERLAY so its resolved font object (ChatFontNormal — face/height/shadow) is what the
-        // frame's line/text rendering reads. See [`Self::apply_special_fontstrings`].
+        // 5·b · a direct-child `<FontString>`: the widget's own text font (EditBox, message frame).
         self.apply_special_fontstrings(el, wrapper, self_name, dbg_name);
-        // 5a · <Backdrop> plate (rf24 LoadXML `0x77e6c0`): the tiled bg + 8-piece border.
+        // 5a · <Backdrop> plate (LoadXML `0x77e6c0`): the tiled bg + 8-piece border.
         self.apply_backdrop(el, wrapper, dbg_name);
         // 5a' · <TitleRegion>: the drag handle, through the API's own CreateTitleRegion.
         self.apply_title_region(el, wrapper, self_name, dbg_name);
-        // 5b · per-kind LoadXML extras (RF-28's typed tables) — StatusBar + Button/CheckButton;
-        //      the EditBox flags/caps (RF-0082). Every one of these gates on the element's own tag,
-        //      which is why `apply_template` builds its synthetic node with the kind CreateFrame was
-        //      given: a Frame asked to wear a <Button> template simply skips the Button-only steps
-        //      instead of calling SetNormalTexture on something that has no such method.
+        // 5b · per-kind LoadXML extras (EditBox `0x779fb0`), each gated on the element's own tag,
+        //      so a Frame wearing a <Button> template skips the Button steps.
         self.apply_statusbar(el, wrapper, dbg_name);
         self.apply_slider(el, wrapper, self_name, dbg_name);
         self.apply_colorselect(el, wrapper, self_name, dbg_name);
@@ -994,11 +634,10 @@ impl Loader<'_> {
         self.apply_messageframe(el, wrapper, dbg_name);
         self.apply_simplehtml(el, wrapper, dbg_name);
         self.apply_minimap(el, wrapper, dbg_name);
-        // 6 · <Scripts> handlers (rf24 `0x769ef0`); OnLoad is captured to fire bottom-up below.
+        // 6 · <Scripts> handlers (`0x769ef0`); OnLoad is captured to fire bottom-up below.
         let onload = self.apply_scripts(el, wrapper, dbg_name);
 
-        // 7 · nested <Frames> — build children (firing THEIR OnLoads) before ours (rf26). A child's
-        //     `$parent` (name and anchors) resolves against this frame's name.
+        // 7 · nested <Frames>, whose OnLoads fire before ours (`0x76a060`).
         for frames_el in children_named(el, "Frames") {
             for child in &frames_el.children {
                 let expanded = self.expand(child);
@@ -1006,18 +645,9 @@ impl Loader<'_> {
             }
         }
 
-        // 7b · `<ScrollChild>` — the ScrollFrame's panning content (wow-5875-re
-        //      `rf28-typed-widget-loadxml.md`: "its single child frame is instantiated via
-        //      `0x6ee280`(childNode, this, status)" — the same RF-0026 path `<Frames>` uses — then
-        //      "stored +0x318, flag +0x314=1", which is `SetScrollChild`).
-        //
-        //      **This is what gives a ScrollFrame its scroll range**, and without it
-        //      `FauxScrollFrameTemplate` — the template five corpus addons instantiate and 34 more
-        //      reach through `FauxScrollFrame_Update` — produces a frame whose range is 0, whose
-        //      `SetVerticalScroll` clamps to 0, and whose `OnVerticalScroll` therefore fires with
-        //      `arg1 = 0` forever. The list never scrolls and nothing errors.
-        //
-        //      An **empty** `<ScrollChild>` is an error in the reference, so it is one here.
+        // 7b · <ScrollChild>: its one child is built through `Instantiate 0x6ee280` like
+        //      `<Frames>`, then stored at `+0x318` with `+0x314 = 1`, which is `SetScrollChild`
+        //      and gives the ScrollFrame its scroll range. An empty one errors in the reference.
         for sc in children_named(el, "ScrollChild") {
             let Some(child) = sc.children.first() else {
                 self.report.errors.push(format!(
@@ -1037,9 +667,7 @@ impl Loader<'_> {
             }
         }
 
-        // 7c · the anchors this frame's own elements could not resolve while their targets were
-        //      still unbuilt — every child exists now, which is when the client's own layout
-        //      pass would have read them.
+        // 7c · deferred anchors: every child exists now, as at the reference's layout pass.
         self.drain_deferred_anchors(deferred_mark);
         // 8 · this frame's OnLoad, now that its subtree is complete (bottom-up).
         if let Some(func) = onload {
@@ -1047,23 +675,14 @@ impl Loader<'_> {
         }
     }
 
-    /// The two names a decoration needs, read back from the frame itself through the **public
-    /// object model** (`GetName`/`GetParent`) rather than the arena — the discipline this module
-    /// holds to everywhere else (see the module docs). Used by [`apply_template`], whose caller
-    /// hands it a wrapper and nothing else.
-    ///
-    /// Returns the frame's own name (`None` if it is anonymous) and the name of its nearest
-    /// **named** ancestor — rf27 rule 3's walk, with [`framexml::DEFAULT_PARENT_NAME`] when there
-    /// is none.
+    /// Apply one anchor, deferring it (when `may_defer`) while its named `relativeTo` is unbuilt.
     pub(super) fn apply_anchor(&mut self, d: DeferredAnchor, may_defer: bool) {
         let rel: Value = match d.args.1.as_deref() {
             Some(name) => {
                 match crate::script::object::anchor_args::resolve_xml_relative_to(self.lua(), name)
                 {
                     Some(t) => Value::Table(t),
-                    // Nothing by that name YET — a target declared later in the enclosing frame's
-                    // subtree. Hold it until the subtree is complete (`deferred_anchors`) and try
-                    // once more; a miss THEN is a real miss and takes the reference's leg.
+                    // Not built yet: retry once the subtree is complete; a miss then is real.
                     None if may_defer => {
                         self.deferred_anchors.push(d);
                         return;
@@ -1076,9 +695,8 @@ impl Loader<'_> {
                     }
                 }
             }
-            // No `relativeTo=`: `ebx` still holds `[ebp-0x14]`, the layout parent default that
-            // `0x76785b call [edx+0xc]` (= `0x76c6e0`) seeded before the `<Anchor>` loop. A frame
-            // with no parent gets the screen root there, which is what a Lua `nil` means here.
+            // No `relativeTo=`: the layout parent (`0x76c6e0`, called at `0x76785b`), or the
+            // screen for a parentless frame, which `nil` means here.
             None => match d
                 .wrapper
                 .call_method::<Option<Table>>("GetParent", ())
@@ -1103,8 +721,7 @@ impl Loader<'_> {
         }
     }
 
-    /// Apply the anchors deferred since `mark` (the enclosing `decorate`'s entry), in order. A
-    /// target still missing now is a real miss and warns through the resolver like any other.
+    /// Apply the anchors deferred since `mark`, in order; a target still missing now warns.
     pub(super) fn drain_deferred_anchors(&mut self, mark: usize) {
         let pending: Vec<DeferredAnchor> = self.deferred_anchors.drain(mark..).collect();
         for d in pending {
@@ -1118,8 +735,8 @@ impl Loader<'_> {
             .ok()
             .flatten();
         let mut cur = wrapper.clone();
-        // Bounded: the arena's parent chain is a tree, and a walk that somehow is not must still
-        // return rather than hang a load.
+        // The frame's own name and its nearest named ancestor's, else `"Top"` (`0x76c5b0`'s
+        // walk), read through `GetName`/`GetParent`. Bounded, so a malformed chain cannot hang.
         for _ in 0..64 {
             let Ok(Some(parent)) = cur.call_method::<Option<Table>>("GetParent", ()) else {
                 break;
@@ -1143,16 +760,9 @@ pub(super) fn children_named<'a>(
         .filter(move |c| c.tag.eq_ignore_ascii_case(tag))
 }
 
-/// Iterate an element's direct children whose tag matches ANY of `tags` (case-insensitively), in
-/// document order.
-///
-/// **Two spellings, one pass.** A 1.12 `<Button>` answers to two names for its label
-/// (`<ButtonText>` and `<NormalText>`) and two for each of its three state fonts
-/// (`<NormalFont>`/`<NormalText>`, `<HighlightFont>`/`<HighlightText>`,
-/// `<DisabledFont>`/`<DisabledText>` — `CSimpleButton::LoadXML 0x7788c0`'s tag-compare chain,
-/// wow-re `scratch/fontstring-loadxml-font-attrs.md` §7). Walking one spelling and then the other
-/// would apply them in tag order instead of document order, and every one of these slots is
-/// last-wins — so the alternatives have to be a single filtered walk, not two.
+/// Iterate an element's direct children whose tag matches any of `tags` (case-insensitively), in
+/// document order. One walk, not one per tag: a Button's label and state fonts each answer to two
+/// tags (`CSimpleButton::LoadXML 0x7788c0`) and each slot is last-wins.
 pub(super) fn children_named_any<'a>(
     el: &'a Element,
     tags: &'a [&'a str],
@@ -1162,13 +772,8 @@ pub(super) fn children_named_any<'a>(
         .filter(move |c| tags.iter().any(|t| c.tag.eq_ignore_ascii_case(t)))
 }
 
-/// Does this `text=` value LOOK like a GlobalStrings key? `SCREAMING_SNAKE`, two characters or more —
-/// at least one letter, and nothing but `A-Z`, `0-9`, `_`. The reference's whole string table is
-/// written this way (`CREATE_MACROS`, `DELETE`, `EXIT_GAME`), and benilla's own literals never are
-/// ("Send Mail", "No results found."), so the shape cleanly separates "you meant a key" from "you
-/// meant these words" — all [`Loader::resolve_text`] needs it for. The length floor is the one real
-/// false positive it buys off: a single-character label (`text="X"` on a close button) is a glyph,
-/// never a key.
+/// Whether a `text=` value is shaped like a GlobalStrings key: `SCREAMING_SNAKE` with a letter, two
+/// characters or more (a one-character `text="X"` is a glyph).
 fn is_global_string_key(s: &str) -> bool {
     s.len() >= 2
         && s.chars().any(|c| c.is_ascii_uppercase())
@@ -1176,8 +781,7 @@ fn is_global_string_key(s: &str) -> bool {
             .all(|c| c.is_ascii_uppercase() || c.is_ascii_digit() || c == '_')
 }
 
-/// Read an `x`/`y` dimension from a `<Size>`/`<Offset>` element: prefer a `<AbsDimension>` child,
-/// else the element's own `x`/`y` attributes. Either component may be absent.
+/// An `x`/`y` pair from a `<Size>`/`<Offset>`: its `<AbsDimension>` child, else its own attributes.
 pub(super) fn abs_dim(el: &Element) -> (Option<f32>, Option<f32>) {
     let src = children_named(el, "AbsDimension").next().unwrap_or(el);
     let x = src.attr("x").and_then(|v| v.trim().parse::<f32>().ok());
@@ -1195,25 +799,21 @@ pub(super) fn color_of(el: &Element) -> [f32; 4] {
     [c("r", 0.0), c("g", 0.0), c("b", 0.0), c("a", 1.0)]
 }
 
-/// Read a `<TexCoords left right top bottom>` child's UV rect `(l, r, t, b)`, if present and
-/// fully-specified. A `<TexCoords>` missing any of the four edges is skipped (the loader leaves the
-/// texture at full-texture UVs rather than guess a half-set crop).
+/// A `<TexCoords>` child's UV rect `(l, r, t, b)`; one missing an edge is ignored (full UVs).
 pub(super) fn tex_coords_of(el: &Element) -> Option<(f32, f32, f32, f32)> {
     let tc = children_named(el, "TexCoords").next()?;
     let edge = |k: &str| tc.attr(k).and_then(|v| v.trim().parse::<f32>().ok());
     Some((edge("left")?, edge("right")?, edge("top")?, edge("bottom")?))
 }
 
-/// Read a `<FontHeight>`/`<AbsValue>`-style scalar: prefer an `<AbsValue val=/>` child, else the
-/// element's own `val` attribute (the `Value` type's inline form). `None` if neither parses.
+/// A `<FontHeight>`-style scalar: its `<AbsValue val=>` child, else its own `val=`.
 pub(super) fn abs_value(el: &Element) -> Option<f32> {
     let src = children_named(el, "AbsValue").next().unwrap_or(el);
     src.attr("val").and_then(|v| v.trim().parse::<f32>().ok())
 }
 
-/// Build a resolved [`FontObject`] from an already-inherits-flattened `<Font>` element: the `font=`
-/// path, the *last* `<FontHeight>` and `<Color>` (merge appends inherited-first, so the last wins —
-/// an override), the `outline=` OUTLINETYPE, and optional `justifyH=`/`justifyV=`.
+/// A [`FontObject`] from a flattened `<Font>`. The merge appends inherited nodes first, so the last
+/// `<FontHeight>`, `<Color>` and `<Shadow>` win.
 pub(super) fn font_object_from_element(el: &Element) -> FontObject {
     let justify_h = el
         .attr("justifyH")
@@ -1229,9 +829,8 @@ pub(super) fn font_object_from_element(el: &Element) -> FontObject {
             "BOTTOM" => JustifyV::Bottom,
             _ => JustifyV::Middle,
         });
-    // <Shadow><Offset><AbsDimension x= y=/></Offset><Color r= g= b=/></Shadow> — inherited via the
-    // template merge like every other child (the MasterFont root's (1,-1) black reaches the whole
-    // GameFont* family; ref-Fonts.xml l.55-62).
+    // `<Shadow>` inherits like any child: `MasterFont`'s (1,-1) black reaches every `GameFont*`
+    // (`Fonts.xml:55`).
     let shadow = children_named(el, "Shadow").last().map(|sh| {
         let offset = children_named(sh, "Offset")
             .next()
diff --git a/crates/benilla-ui/src/loader/regions.rs b/crates/benilla-ui/src/loader/regions.rs
index 5c047819..0d91e841 100644
--- a/crates/benilla-ui/src/loader/regions.rs
+++ b/crates/benilla-ui/src/loader/regions.rs
@@ -4,45 +4,20 @@ use crate::framexml::{self, Element};
 
 use super::{abs_dim, abs_value, children_named, color_of, tex_coords_of, Loader};
 
-/// Whether a region parses **its own** font attributes — the reference's `FONTSTRING+0x12c`,
-/// which wow-re named `ownsFontAttrs` (`scratch/fontstring-loadxml-font-attrs.md` §3 and
-/// `scratch/button-label-build-and-anchor-order.md`, both VERIFIED).
-///
-/// It exists for exactly one element in the whole schema. The ctor sets it to 1
-/// (`0x770de7 mov byte [esi+0x12c],1`) and **one site image-wide clears it** — `0x778b7b`, inside
-/// `CSimpleButton::LoadXML 0x7788c0`'s inline build `[0x778b4c, 0x778bb6)`, which is the
-/// **`<NormalText>`** leg (tag `0x879978`, compared at `0x778b43`) and nothing else. A
-/// `<ButtonText>` (tag `0x8799f0`, `0x7789c1`) is built by the ordinary `<FontString>` region
-/// builder `0x6f2780` — the `<Layers>` walker's own — which never touches the flag, so an ordinary
-/// label keeps every attribute it is written with.
-///
-/// Cleared, gate B (`0x7710d3` → `je 0x771468`) makes that string's own
-/// `CSimpleFontString::LoadXML 0x770f40` skip `0x7710e1`–`0x771467` wholesale: `font=`,
-/// `<FontHeight>`, `outline=`, `monochrome=`, the file load, `spacing=`, `justifyV=`, `justifyH=`,
-/// `<Color>` and `<Shadow>`. (Gate A, `0x770f72`, additionally drops the `inherits=` registry-hit
-/// live link.) The SAME node is fed instead to the button's persistent Normal-state `CSimpleFont`
-/// at `+0x33c` (`0x778ba9`/`0x778baf call 0x783c30`) — one owner per attribute, no double
-/// application. The word still reaches the label's paint and its `GetJustifyH` answer: that
-/// loader's tail notify writes the resolved justify into the label's own `+0x120` (`0x784111` →
-/// `0x784180` → `0x773530` → `0x770800` at `0x770876`), **after** the anchor is placed.
-///
-/// Only `justifyH`/`justifyV` are gated here because they are the only two of that surface this
-/// pass ever applied: the rest live in `apply_fontstring_font`/`apply_region_visual`, which the
-/// button's label pass does not call. Geometry — `<Size>`, `<Anchors>`, `setAllPoints`, `name=` —
-/// is `CLayoutFrame::LoadXML`'s and is outside the gate on both legs.
+/// Whether a region reads its own font attributes, the reference's `FONTSTRING+0x12c`: set by the
+/// ctor (`0x770de7`) and cleared only on a Button's `<NormalText>` (`0x778b7b`), whose string then
+/// skips them (`0x7710e1`-`0x771467`) for the button's Normal font to take (`0x783c30`). Here it
+/// gates only justify, the one font attribute the button's label pass applies.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(super) enum FontAttrs {
-    /// The ctor's default: an ordinary region — a `<Layers>` `<FontString>`, an EditBox's special
-    /// string, a title region, **and a Button's `<ButtonText>`** — owns its font attributes.
+    /// Every other region, a Button's `<ButtonText>` included.
     Own,
-    /// A Button's `<NormalText>`, the one element the client disowns: its font attributes belong
-    /// to the button's Normal-state font, never to the label.
+    /// A Button's `<NormalText>`: its font attributes are the button's Normal font's.
     Disowned,
 }
 
 impl Loader<'_> {
-    /// `<Layers>`/`<Layer level=>`/`<Texture>`/`<FontString>` (rf24 `0x769d70`): create each region
-    /// via CreateTexture/CreateFontString on the draw layer, then apply its file/color/text.
+    /// `<Layers>` (`0x769d70`): each `<Texture>` and `<FontString>`, created on its layer.
     pub(super) fn apply_layers(
         &mut self,
         el: &Element,
@@ -54,11 +29,8 @@ impl Loader<'_> {
             for layer in children_named(layers, "Layer") {
                 let level = layer.attr("level").unwrap_or("ARTWORK").to_string();
                 for region in &layer.children {
-                    // A region's `inherits=` may name a virtual REGION template (the talent
-                    // window's branch/arrow art pool) — splice it exactly like a frame's
-                    // (rf24's one template registry serves both). A FontString's `inherits=`
-                    // usually names a font OBJECT instead — a separate namespace this gate
-                    // skips past to `apply_fontstring_font` below.
+                    // `inherits=` may name a region template, in the frames' one registry
+                    // (`0x6ee500`); a font object's name passes on to `apply_fontstring_font`.
                     let region = &self.expand_region(region);
                     let is_texture = region.tag.eq_ignore_ascii_case("Texture");
                     let is_fontstring = region.tag.eq_ignore_ascii_case("FontString");
@@ -85,13 +57,11 @@ impl Loader<'_> {
                                 continue;
                             }
                         };
-                    // hidden= on a Texture/FontString — the region-level VisibleRegion bit.
                     if region.attr_bool("hidden") {
                         if let Err(e) = region_wrapper.call_method::<()>("Hide", ()) {
                             self.report.errors.push(format!("{dbg}: region Hide: {e}"));
                         }
                     }
-                    // alpha= on a Texture/FontString — the region's own alpha, the frame attr's twin.
                     if let Some(a) = region
                         .attr("alpha")
                         .and_then(|v| v.trim().parse::<f32>().ok())
@@ -106,16 +76,12 @@ impl Loader<'_> {
                         FontAttrs::Own,
                     );
                     if is_fontstring {
-                        // Font object (`inherits=`) first, then the FontString's own `font=`/
-                        // `<FontHeight>`/`outline=` overrides — before the generic visual pass applies
-                        // `text`/`<Color>` on top (an explicit `<Color>` overriding the object's).
+                        // Before the visual pass, so an explicit `<Color>` beats the font object's.
                         self.apply_fontstring_font(region, &region_wrapper, dbg);
                     }
                     self.apply_region_visual(region, &region_wrapper, is_texture, dbg);
-                    // The creation-path implicit anchor (decision 1310): AFTER the authored
-                    // `<Size>`/`<Anchors>`/justify are on the region, exactly where the real
-                    // engine runs it (`0x7701c0`/`0x771480`, immediately after the region's
-                    // LoadXML returns). A region the XML anchored is untouched.
+                    // The implicit creation anchor, run after the region's LoadXML as the
+                    // reference does (`0x7701c0`, `0x771480`); an anchored region is left alone.
                     if let Err(e) =
                         crate::script::implicit_creation_anchor_lua(self.lua, &region_wrapper)
                     {
@@ -128,11 +94,8 @@ impl Loader<'_> {
         }
     }
 
-    /// A frame's **direct-child** `<FontString>` (outside `<Layers>`): the client's "special" font
-    /// string — the ScrollingMessageFrame's line font, an EditBox's text font — which real FrameXML
-    /// attaches at the OVERLAY layer. Only ChatFrame uses this in our shipped XML; without it the
-    /// chat lines fall back to the default face with no shadow. Created via the same
-    /// CreateFontString + layout/font/visual path as a `<Layers>` FontString.
+    /// A frame's direct-child `<FontString>`, its "special" string (a message frame's line font, an
+    /// EditBox's text), on the OVERLAY layer.
     pub(super) fn apply_special_fontstrings(
         &mut self,
         el: &Element,
@@ -140,30 +103,21 @@ impl Loader<'_> {
         parent_name: &str,
         dbg: &str,
     ) {
-        // **A `<SimpleHTML>`'s direct-child `<FontString>` is not a region at all** — it is the
-        // declaration of that widget's `P` element font (`0x78a1fe` → `CSimpleFont::LoadXML`), and
-        // `Loader::apply_simplehtml` owns it. Creating a real FontString here instead would leave
-        // an unanchored, textless string on the frame AND leave `elementFont[0]` empty, which is
-        // the one thing that makes every block fall back to the renderer's default face.
+        // A `<SimpleHTML>`'s direct `<FontString>` declares its `P` font, not a region
+        // (`0x78a1fe`); `apply_simplehtml` owns it.
         if el.tag.eq_ignore_ascii_case("SimpleHTML") {
             return;
         }
         for region in &el.children {
             if !region.tag.eq_ignore_ascii_case("FontString") {
-                continue; // <Layers>/<Frames>/<Scripts>/... are handled by their own passes
+                continue;
             }
             let region = &self.expand_region(region);
             let rname: Option<String> = region
                 .name()
                 .map(|raw| framexml::resolve_name(raw, parent_name));
-            // **An EditBox's direct-child `<FontString>` creates NOTHING.** RF-0028
-            // (`scratch/rf28-typed-widget-loadxml.md`, "EditBox — LoadXML `0x779fb0`") lists it as
-            // the *embedded* font string, and its one attribute (`bytes`) writes the box's own
-            // `maxBytes` at `E+0x33c` — it is the declaration of the object the ctor already built
-            // at `0x779bee`, exactly as a `<SimpleHTML>`'s `<FontString>` declares that widget's
-            // element font (the guard at the top of this function). Creating a second region here
-            // would put an orphan on the frame AND push the authored `<Layers>` regions one place
-            // down the list `GetRegions` hands Lua.
+            // An EditBox's `<FontString>` declares the text string its ctor built (`0x779fb0`,
+            // `0x779bee`), so it creates nothing: a second region would also shift `GetRegions`.
             let existing_text = el
                 .tag
                 .eq_ignore_ascii_case("EditBox")
@@ -171,9 +125,6 @@ impl Loader<'_> {
                 .flatten();
             let region_wrapper: Table = match existing_text {
                 Some(w) => {
-                    // The embedded string is nameless in the client's own chain; an authored
-                    // `name=` still publishes both ways, exactly like a setter-created sub-texture
-                    // (`apply_slider`'s thumb).
                     if let Some(n) = rname {
                         crate::script::region::publish_region_name(self.lua(), &n, &w);
                         if let Err(e) = self.lua().globals().set(n.clone(), w.clone()) {
@@ -199,19 +150,14 @@ impl Loader<'_> {
             self.apply_region_layout(region, &region_wrapper, parent_name, dbg, FontAttrs::Own);
             self.apply_fontstring_font(region, &region_wrapper, dbg);
             self.apply_region_visual(region, &region_wrapper, false, dbg);
-            // The creation-path implicit anchor (decision 1310), as in `apply_layers`. For the
-            // EditBox adopt below it is moot — `write_inset_anchors` replaces the anchor set
-            // wholesale — but a plain special FontString (a chat window's) gets the same
-            // justify-point the real engine gives it.
+            // The implicit creation anchor, as in `apply_layers`; an EditBox's adopt replaces it.
             if let Err(e) = crate::script::implicit_creation_anchor_lua(self.lua, &region_wrapper) {
                 self.report
                     .errors
                     .push(format!("{dbg}: implicit anchor: {e}"));
             }
-            // The engine's LoadXML slot assignment: an EditBox's direct-child `<FontString>` IS
-            // its text region — typed text renders in its font, the box's insets anchor it.
-            // Assigned, never searched (a find-first adoption once grabbed the chat header out of
-            // `<Layers>`: typing overwrote "Say:" and the insets re-anchor centered it).
+            // It is the EditBox's text region by slot, never found by a search, which could take a
+            // `<Layers>` string; the box's insets anchor it.
             if el.tag.eq_ignore_ascii_case("EditBox") {
                 if let Err(e) =
                     crate::script::adopt_text_region(self.lua(), wrapper, &region_wrapper)
@@ -224,12 +170,9 @@ impl Loader<'_> {
         }
     }
 
-    /// A region's own geometry (decision 0068 v1): `<Size>` → SetWidth/SetHeight, `<Anchors>` →
-    /// SetPoint (owner-relative; `relativeTo` is `$parent`-substituted like a frame's), the
-    /// `setAllPoints="true"` shorthand, and — only for a region that [`FontAttrs::Own`]s them —
-    /// the FontString `justifyH`/`justifyV` attrs → SetJustifyH/V. This is the join that makes
-    /// region `<Size>`/`<Anchors>` actually place the region (before, both were silently dropped
-    /// — the smeared-merchant root cause).
+    /// A region's geometry: `<Size>`, a FontString's justify when [`FontAttrs::Own`],
+    /// `setAllPoints` and `<Anchors>`, whose `$parent` is the owner's name, or a nameless owner's
+    /// nearest named ancestor's.
     pub(super) fn apply_region_layout(
         &mut self,
         region: &Element,
@@ -238,8 +181,7 @@ impl Loader<'_> {
         dbg: &str,
         font_attrs: FontAttrs,
     ) {
-        // ALL `<Size>` children in document order (same last-wins rule as `apply_size`: a templated
-        // region's own `<Size>` must overwrite its template's).
+        // Every `<Size>` in document order, as in `apply_size`.
         for size in children_named(region, "Size") {
             let (x, y) = abs_dim(size);
             if let Some(w) = x {
@@ -289,8 +231,7 @@ impl Loader<'_> {
                     args,
                     dbg: dbg.to_string(),
                 };
-                // The XML path's own law, which resolves the name itself and defers a target
-                // the enclosing frame's subtree has not built yet (`Loader::apply_anchor`).
+                // Deferred while the enclosing subtree has not built its target yet.
                 self.apply_anchor(d, true);
             }
         }
@@ -306,43 +247,20 @@ impl Loader<'_> {
         let color = children_named(region, "Color").next().map(color_of);
         if is_texture {
             if let Some(file) = region.attr("file") {
-                // A `<Texture file=…>` with a `<Color>` child DISCARDS the colour — it is not a
-                // tint (wow-re `system/ui/scratch/texture-color-composition.md`, VERIFIED).
-                // `CSimpleTexture::LoadXML 0x76fe20` runs its child loop (`0x76fec1`-`0x7700fc`,
-                // where `<Color>` lands in `SetTexture(const CImVector*)` `0x770360`) to completion
-                // BEFORE it reads `file=` at `0x770102`, and a successful load overwrites the very
-                // same `+0xcc` slot (`0x7702cb`/`0x7702dc`) — the generated solid is released
-                // unused. Even the load-FAILURE fallback ignores it, hard-coding `0xff00ff00`
-                // (`0x77016a`). So: load the art, drop the colour.
+                // A `<Color>` beside `file=` is discarded, not a tint: `0x76fe20` applies it in its
+                // child loop, then the file, read after (`0x770102`), overwrites the same slot.
                 self.call_region(region_wrapper, "SetTexture", file.to_string(), dbg);
             } else if let Some(c) = color {
-                // No file: a solid colour fill (SetTexture(r,g,b,a)) — the client really generates
-                // an 8×8 texture out of it, which is why its alpha later MULTIPLIES with any
-                // SetVertexColor rather than being replaced by it (`RegionData::fill`).
+                // No file: a solid fill, an 8×8 texture in the reference, so its alpha multiplies
+                // with `SetVertexColor` rather than being replaced by it.
                 self.call_region(region_wrapper, "SetTexture", (c[0], c[1], c[2], c[3]), dbg);
             }
-            // `<Gradient orientation><MinColor/><MaxColor/></Gradient>` — the texture's FOUR-vertex
-            // colour, and the one XML surface that tints a `file=` texture. It survives alongside
-            // the art because it lands in a different field: the child loop writes the vertex
-            // colours (`+0xb8`, stride 4 — `0x77304d`-`0x77305f`, "4 iff count > 1") while `file=`
-            // is read only afterwards into `+0xcc`
-            // (`texture-color-composition.md` §1-2). That is why `<Color>` beside a `file=` is
-            // discarded above and a `<Gradient>` beside one is not.
-            //
-            // Dropping this silently is what painted Bagnon's character-list popup as a WHITE SLAB:
-            // its background art is `ChatFrameBackground`, which is white by design and is meant to
-            // be tinted black→dark-grey by exactly this element (`Bagnon_Core/core/Frame.xml:32`).
-            //
-            // MinColor → the first stop, MaxColor → the second, which is the natural reading and
-            // the Lua binding's own argument order — but the XML arm's stop-to-vertex mapping is
-            // **not byte-read** (wow-re records the `<Gradient>` tag compare at `0x7700b0` and the
-            // stride, not the arm's body). It cannot matter yet: `RegionData::gradient` is folded to
-            // its midpoint by the paint (`script::extract`), which is symmetric in the two stops.
-            // Swapping them becomes visible the day a quad carries a real two-stop tint.
+            // `<Gradient>` writes the vertex colours (`+0xb8`, `0x77304d`), which `file=` leaves
+            // alone, so unlike `<Color>` it tints the art. MinColor is the first stop and MaxColor
+            // the second; the reference's stop-to-vertex order is untraced (`0x7700b0`).
             if let Some(g) = children_named(region, "Gradient").next() {
                 let stop = |tag: &str| children_named(g, tag).next().map(color_of);
-                // A half-declared gradient is skipped whole rather than half-applied against an
-                // invented default — an absent stop is not a black one.
+                // A gradient missing a stop is skipped: an absent stop is not a black one.
                 if let (Some(min), Some(max)) = (stop("MinColor"), stop("MaxColor")) {
                     self.call_region(
                         region_wrapper,
@@ -362,22 +280,15 @@ impl Loader<'_> {
                     );
                 }
             }
-            // `<TexCoords left right top bottom>`: the UV sub-rect this texture samples (decision
-            // 0084 — quadrant/atlas slicing). ref-MerchantFrame.xml l.259/268/395.
             if let Some(tc) = tex_coords_of(region) {
                 self.call_region(region_wrapper, "SetTexCoord", tc, dbg);
             }
-            // `alphaMode="ADD"` on a `<Layers>` texture — the same blend attribute the state-texture
-            // path already applies; dropping it here rendered every layer glow (the quest log's
-            // selection highlight, ref UI-QuestLogTitleHighlight) as an opaque gray bar instead of
-            // an additive glow (the 0109 look fix).
             if let Some(mode) = region.attr("alphaMode") {
                 self.call_region(region_wrapper, "SetBlendMode", mode.to_string(), dbg);
             }
         } else {
             if let Some(text) = region.attr("text") {
-                // `<FontString text=>` is a global-string lookup, not a literal — rf28 l.115
-                // (`0x703bf0`). See `Loader::resolve_text`.
+                // A global-string key, not a literal (`0x703bf0`).
                 let text = self.resolve_text(text, dbg);
                 self.call_region(region_wrapper, "SetText", Some(text), dbg);
             }
@@ -392,34 +303,14 @@ impl Loader<'_> {
         }
     }
 
-    /// Follow a FontString's `inherits=` to the **font object** at the end of it, through any
-    /// virtual FontString templates in between.
-    ///
-    /// Returns the name unchanged when it already names a font object (the one-hop case), the
-    /// template chain's font object when it does not, and `None` when the chain ends without one —
-    /// which is the case the caller still warns about, because an `inherits=` naming nothing at all
-    /// is a real gap and not something to swallow.
-    ///
-    /// `inherits=` is comma-separated in general; the first entry that resolves wins, which matches
-    /// the single-font reality (a region cannot wear two faces) without pretending the list cannot
-    /// exist. Depth is bounded: a template registry can contain a cycle, and a loader that hangs on
-    /// a malformed addon is worse than one that gives up on it.
+    /// The font object a FontString's `inherits=` names, directly or through virtual FontString
+    /// templates; `None` when the chain ends without one. Bounded, as a registry can hold a cycle.
     pub(super) fn font_object_through_templates(&self, inherits: &str) -> Option<String> {
-        // **The probes here stay case-EXACT, and the outcome is still folded.** Font names match
-        // case-insensitively in 1.12 (`0x783870`, `SStrCmpI`), and that fold lives in
-        // `Model::font_object` — so a miss here falls through to the caller's
-        // `unwrap_or_else(|| name.to_string())` and `SetFontObject` resolves it anyway.
-        //
-        // Not folded HERE because the `framexml_fonts` element registry's other reader hands its
-        // keys to `framexml::expand`, which is the SAME expansion templates go through — and
-        // whether the client matches TEMPLATE names case-insensitively is not carved. Folding this
-        // registry would quietly extend a verified font fact to unverified template behaviour.
         const MAX_HOPS: usize = 8;
         let model = self.model();
         let fonts = model.framexml_fonts.borrow();
         let templates = model.framexml_templates.borrow();
-        // One name, not a comma list — 1.12's lookup has no splitter, and supporting one is a
-        // superset of it. Folded on the probe, like the resolution itself.
+        // One name, not a comma list: 1.12's lookup has no splitter.
         for entry in [inherits] {
             let mut name = entry.to_string();
             for _ in 0..MAX_HOPS {
@@ -440,61 +331,21 @@ impl Loader<'_> {
         None
     }
 
-    /// Is `name` a registered `<Font>` OBJECT? The plain registry probe — **no template walk**,
-    /// unlike [`Self::font_object_through_templates`]. This is the reference's `0x783870(value,
-    /// create = 0)` lookup, which is a flat registry hit or nothing; the template chain is
-    /// `inherits=`'s affordance alone.
-    ///
-    /// Case-folded, because 1.12 matches font names with `SStrCmpI` (`0x783870`).
+    /// Whether `name` is a registered font object: the reference's flat, case-insensitive lookup
+    /// (`0x783870`, `SStrCmpI`), with no template walk.
     pub(super) fn is_font_object(&self, name: &str) -> bool {
         let model = self.model();
         let fonts = model.framexml_fonts.borrow();
         fonts.contains_key(name) || fonts.keys().any(|k| k.eq_ignore_ascii_case(name))
     }
 
-    /// A `<FontString>`'s font resolution: `inherits="GameFontNormal"` → `SetFontObject` (the named
-    /// virtual Font object's face/height/color/outline become this string's defaults), then the
-    /// FontString's own `font=`/`<FontHeight>`/`outline=` → `SetFont` overrides. Called before the
-    /// generic visual pass (so an explicit `<Color>` still overrides the object's color). An
-    /// unregistered `inherits=` target is a warn-once gap, not a dropped region.
-    ///
-    /// **`font=` is a font-object NAME first and a file path only on a miss** — the half of this
-    /// that was missing, and a silent one. The reference tries the registry before the filesystem:
-    /// `0x783d15 call 0x783870(value, create = 0)`, and on a hit takes the same live-link
-    /// `0x770c60` that `SetFontObject` uses, skipping the file-path branch entirely
-    /// (wow-re `system/ui/scratch/font-object-lua-surface.md` §7 + its `LoadXML` surface table
-    /// row 2; `CSimpleFontString::LoadXML 0x770f40` at `0x7710e1`-`0x771114`).
-    ///
-    /// Reading it as a path only is what made Bagnon's item-stack counts unreadable: its
-    /// `<FontString name="$parentCount" font="NumberFontNormal">` (`Bagnon_Core/core/Item.xml:14`)
-    /// stored the literal string `"NumberFontNormal"` as a font PATH, which resolves to no face —
-    /// so height, colour and, above all, `outline="NORMAL"` were all lost, and the atlas fell back
-    /// silently to Friz 12. The black ring around a stack count is that outline (`NumberFontNormal`
-    /// carries no `<Shadow>` in 1.12 — the readability is the halo, not a drop shadow).
-    ///
-    /// Real FrameXML never exercises this: it writes `font=` on `<Font>` elements only, always as a
-    /// path. The addon corpus writes it on FontStrings 117 times.
+    /// A `<FontString>`'s font: `inherits=` through [`Self::font_object_through_templates`], then
+    /// `font=`, a font object's name first and a file only on a miss (`0x770f40`, `0x771104`).
     pub(super) fn apply_fontstring_font(&mut self, region: &Element, wrapper: &Table, dbg: &str) {
         if let Some(name) = region.attr("inherits") {
-            // **Resolved through the TEMPLATE chain, not taken literally.** A FontString's
-            // `inherits=` may name a font object *or* a virtual FontString template, and a template
-            // may itself inherit the font object — which is how every "declare the line once, stamp
-            // it N times" addon is written. `expand_region` splices the template's attributes in,
-            // but the merged element keeps the INSTANCE's own `inherits=` (the template's name), so
-            // the font object at the far end of the chain was simply lost: one hop worked and two
-            // did not.
-            //
-            // `EQL3_Tracker.xml` is the corpus instance — `EQL3_QuestWatch_FontTemplate` inherits
-            // `GameFontHighlight` and each `EQL3_QuestWatchLine<i>` inherits the template — and it
-            // is not a cosmetic loss. `EQL3_Options.lua:1086` reads the line's font back with
-            // `GetFont()` and feeds it straight to `SetFont(t1, height, t2)`, so the dropped face
-            // came back as OUR OWN faithful `Usage: <FontString>:SetFont(...)` raise, firing on our
-            // own nil, and took the addon's session with it.
-            // An UNRESOLVED chain passes the name through UNCHANGED rather than something
-            // emptier. Handing `SetFontObject("")` an empty string is not the same request as
-            // handing it a bad name — it reads as "clear the font object", which is a silent state
-            // change where the old code produced a loud warn, and it cost EQL3 a NEW load-time
-            // failure the first time this landed.
+            // The expanded element keeps the instance's `inherits=`, a template's name, so the
+            // chain is walked to its font object. An unresolved name passes through unchanged:
+            // `SetFontObject("")` would clear the font object where a bad name warns.
             let resolved = self
                 .font_object_through_templates(name)
                 .unwrap_or_else(|| name.to_string());
@@ -505,31 +356,10 @@ impl Loader<'_> {
                 );
             }
         }
-        // **`font=` gates this whole block, and that is the shape of the bytes** — not a set of
-        // independent overrides (`0x7710e1`-`0x771254`, wow-re
-        // `system/ui/scratch/fontstring-loadxml-font-attrs.md`). Three outcomes, and only three:
-        //
-        //  1. `font=` names a **registered font object** → `SetFontObject` (`0x771104` lookup,
-        //     `0x771114 call 0x770c60` — the same live link `inherits=` takes) and then
-        //     `0x771119 jmp 0x771254`, which **skips `<FontHeight>`, `outline=`, `monochrome=` and
-        //     the file load entirely**. The skipped values are not lost: the link forces all five
-        //     changed bits (`0x770d0c`) and the applier `0x770800` pushes the source's
-        //     height/face/outline down through the inherit mask.
-        //  2. `font=` names anything else → a font **FILE**, and `<FontHeight>`/`outline=`/
-        //     `monochrome=` are read as ITS companions (the miss leg, `0x77110b je 0x77111e`).
-        //  3. **No `font=` at all** → `0x7710f1`/`0x7710fa je 0x771254` jump straight past, so
-        //     `<FontHeight>` and `outline=` are **never parsed**. That block's only predecessor is
-        //     the miss leg in (2); the attributes have no independent existence.
-        //
-        // (3) is the one that changes something we already draw. Real FrameXML has exactly one such
-        // site — `ZoneText.xml`'s `AutoFollowStatusText`, `inherits="GameFontNormal"` with a
-        // `<FontHeight val="20">` and no `font=` — so the real client draws that line at
-        // GameFontNormal's **12**, and Blizzard's 20 is dead XML. Our copy carries the same dead 20
-        // and honoured it until now. The corpus has 22 more of these plus 5 stray `outline=`.
-        //
-        // Only `spacing=`/`justifyH`/`justifyV`/`<Color>`/`<Shadow>` sit past the join and are
-        // genuine post-link overrides — they are applied elsewhere (`apply_region_layout` /
-        // `apply_region_visual`), which is already the right side of this line.
+        // `font=` gates `<FontHeight>` and `outline=` (`0x7710e1`-`0x771254`): a font object's
+        // name links it and skips them (`0x771114`, `0x771119`), any other value is a file they
+        // qualify (`0x77110b`), and with no `font=` they are never read (`0x7710fa`), so
+        // `ZoneText.xml`'s `AutoFollowStatusText` draws at GameFontNormal's 12, not its own 20.
         match region.attr("font") {
             Some(name) if self.is_font_object(name) => {
                 if let Err(e) = wrapper.call_method::<()>("SetFontObject", name.to_string()) {
@@ -540,11 +370,8 @@ impl Loader<'_> {
                 }
             }
             Some(path) => {
-                // A font FILE, with its two companions. NOT the `SetFont` binding: XML supplies any
-                // subset, while the reference's `SetFont` requires a path AND a height (raising
-                // `0x87c69c` otherwise), because the real client applies XML font attributes in C++
-                // and never through the Lua method. Routing the loader through the binding is
-                // exactly what forced that binding to stay lenient — one name doing two jobs.
+                // Applied directly, not through the Lua `SetFont`, which requires a height
+                // (`0x87c69c`) where XML may omit it.
                 let height = children_named(region, "FontHeight")
                     .next()
                     .and_then(abs_value);
diff --git a/crates/benilla-ui/src/loader/scripts.rs b/crates/benilla-ui/src/loader/scripts.rs
index 8697e906..8ddabecc 100644
--- a/crates/benilla-ui/src/loader/scripts.rs
+++ b/crates/benilla-ui/src/loader/scripts.rs
@@ -5,11 +5,8 @@ use crate::framexml::Element;
 use super::{children_named, Loader};
 
 impl Loader<'_> {
-    /// `<Scripts>` → SetScript each handler (rf24 `0x769ef0`). Handler source comes from the element
-    /// body (`<OnClick>lua…</OnClick>`) or a `function="Global"` attribute. Returns the compiled
-    /// `OnLoad` handle (if any) so the caller can fire it bottom-up. A body that fails to *compile* is
-    /// an error; an unsupported handler *name* (e.g. the keyboard-focus handlers `OnKeyDown`/`OnChar`,
-    /// not yet modeled) is a warn-once gap.
+    /// `<Scripts>` (`0x769ef0`): `SetScript` for each handler. Returns the `OnLoad`, which the
+    /// caller fires bottom-up.
     pub(super) fn apply_scripts(
         &mut self,
         el: &Element,
@@ -17,16 +14,8 @@ impl Loader<'_> {
         dbg: &str,
     ) -> Option<Function> {
         let mut onload = None;
-        // **The chunk name of an XML handler body is `"<GetName()>:<Handler>"`, read off the
-        // WRAPPER — not off the loader's diagnostic string.** `0x7025fd` calls the script object's
-        // `GetName` through its own vtable (`[[esi]+4]`), falls back to `<unnamed>` (`0x84c7f0`)
-        // at `0x702611` when that is NULL, formats `"%s:%s"` (`0x872a28`) at `0x70261b`, and hands
-        // the result to `0x704c70` at `0x70263c` as the chunk name.
-        //
-        // Reading it here rather than plumbing `dbg` down is the fidelity: `dbg` is a *sentence*
-        // on the `CreateFrame` path (`CreateFrame("Button", "Foo", inherits="Bar")`), which made
-        // every template-inherited handler's errors and `debugstack` frames read as one, and an
-        // unnamed element wrote `<Button>` where the image writes `<unnamed>`.
+        // A handler's chunk name is `"<GetName()>:<Handler>"` off the wrapper, `<unnamed>` for a
+        // nameless frame (`0x7025fd`-`0x70263c`), never the loader's `dbg`.
         for scripts in children_named(el, "Scripts") {
             let owner = wrapper
                 .call_method::<Option<String>>("GetName", ())
@@ -35,32 +24,10 @@ impl Loader<'_> {
                 .unwrap_or_else(|| "<unnamed>".to_string());
             for handler in &scripts.children {
                 let name = handler.tag.clone();
-                // **AN EMPTY BODY IS A CLEAR, AND WHITESPACE IS NOT EMPTY** — the two byte
-                // tests at `SetScript 0x7025c0`, reproduced rather than approximated (wow-5875-re
-                // `system/ui/scratch/xml-script-empty-element.md`, a 3-worker cross-check):
-                //
-                //     7025ec  call 0x702670      ; unref the PREVIOUS handler, unconditionally
-                //     7025f4  test ebx,ebx
-                //     7025f6  je 0x702655        ; text == NULL -> store 0 (reads back as nil)
-                //     7025f8  cmp byte ptr [ebx],0
-                //     7025fb  je 0x702655        ; text == ""   -> same
-                //
-                // The XMLTree chardata handler (`0x6f29d0`) appends every run with `len > 0` and
-                // nothing trims, so `0x7025f8` tests the FIRST BYTE of the raw body.
-                //
-                // That distinction is the whole finding, and it is not academic. 1.12's own
-                // FrameXML has **zero** `<OnX/>` and **zero** `<OnX></OnX>`; its seven blanking
-                // sites (BuffFrame ×3, BankFrame, PaperDollFrame ×2, UIPanelTemplates) are all
-                // `<OnLoad>`↵`</OnLoad>` — a body of `"\n\t\t\t"`, whose first byte is `0x0A`.
-                // Both tests fail and it **compiles to a valid empty function**. So
-                // `TempEnchant1:GetScript("OnLoad")` answers a FUNCTION in the real client, not
-                // nil, and the inherited `BuffButton_OnLoad` is displaced rather than removed.
-                // A `.trim()` here would produce the right window and the wrong answer to an addon.
-                //
-                // The clear path is still real (an empty body, or a `function=` element with no
-                // body — 5875 never reads that attribute at all, so it takes the NULL leg), and it
-                // matters that it is a stored nil: a `0` registry ref is skipped by the dispatch
-                // guard entirely, where the compiled no-op is entered and returns.
+                // An empty body clears the handler to nil, but a whitespace one is an empty
+                // function: `SetScript` (`0x7025c0`) tests only NULL and the first byte
+                // (`0x7025f8`), and nothing trims the body (`0x6f29d0`). The stock blanks
+                // (`BuffFrame.xml:101`) are whitespace, so their `GetScript` answers a function.
                 let cleared = handler.body.is_empty() && handler.attr("function").is_none();
                 let func = if cleared {
                     None
@@ -70,7 +37,6 @@ impl Loader<'_> {
                         None => continue,
                     }
                 };
-                // SetScript stores it; an unsupported name errors — surface as a gap, don't drop hard.
                 if let Err(e) = wrapper.call_method::<()>("SetScript", (name.clone(), func.clone()))
                 {
                     self.warn_once(
@@ -79,22 +45,10 @@ impl Loader<'_> {
                     );
                     continue;
                 }
-                // The real `<Scripts>` walker auto-enables the matching input kind after each
-                // successful SetScript (`0x769ef0` → `0x76af00(kind,-1)` per handler name; wow-re
-                // `ui/scratch/scripts-auto-enable.md`, §5 cross-checked): the five MOUSE-kind
-                // handlers arm the same enable as the XML `enableMouse` attribute — `OnDragStart`
-                // is in the set, `OnDragStop`/`OnReceiveDrag` are NOT. This is XML-load-time
-                // ONLY: the Lua SetScript binding (`0x7748d0`) never auto-enables, so the law
-                // lives here and not in SetScript itself (a runtime-created frame still needs an
-                // explicit `EnableMouse(true)`, like the real client). The KEYBOARD kinds are
-                // modelled and armed just below, and the WHEEL kind (`OnMouseWheel` = kind 3) is
-                // armed the same way right after — it used to say "a separate index this engine
-                // doesn't model yet", and the hit-test carve
-                // (`ui/scratch/hittest-no-fallthrough-law.md`) is what made modelling it necessary:
-                // the wheel plane is the ONE place the engine really does gate on a handler and
-                // continue past a frame that has none. Until it was its own flag, our wheel sweep
-                // had to accept any mouse-enabled frame as a stand-in, and the first such frame
-                // swallowed the wheel.
+                // After each `SetScript` the XML walker enables the handler's input kind
+                // (`0x769ef0` → `0x76af00`): these five arm the mouse (`OnDragStop` and
+                // `OnReceiveDrag` do not), `OnMouseWheel` the wheel (kind 3). The Lua `SetScript`
+                // never does (`0x7748d0`).
                 const MOUSE_KIND: [&str; 5] = [
                     "OnEnter",
                     "OnLeave",
@@ -108,20 +62,14 @@ impl Loader<'_> {
                 if name.eq_ignore_ascii_case("OnMouseWheel") {
                     self.call(wrapper, "EnableMouseWheel", true, dbg);
                 }
-                // The KEYBOARD kinds, the same walker rule one index over (`OnChar` = kind 0,
-                // `OnKeyDown`/`OnKeyUp` = kind 1). Bucket membership is what the delivery walk
-                // iterates ([`crate::script::keyboard`]) and it is the FLAG, never the presence of
-                // a script — so an XML frame carrying a key handler but no `enableKeyboard`
-                // attribute would never be reached by the dispatcher at all, and its handler could
-                // not fire. XML-load-time only, like the mouse half.
+                // The key handlers, the same rule (`OnChar` kind 0, `OnKeyDown`/`OnKeyUp` kind 1);
+                // here any of them sets the one flag both key walks read.
                 const KEY_KIND: [&str; 3] = ["OnChar", "OnKeyDown", "OnKeyUp"];
                 if KEY_KIND.iter().any(|k| name.eq_ignore_ascii_case(k)) {
                     self.call(wrapper, "EnableKeyboard", true, dbg);
                 }
                 if name.eq_ignore_ascii_case("OnLoad") {
-                    // A blanked `<OnLoad/>` leaves nothing to fire — and it must also UNSET a
-                    // handle a template's own OnLoad put here, or the caller fires the very body
-                    // this element exists to remove.
+                    // A cleared `OnLoad` also unsets a template's, or the caller would fire it.
                     onload = func;
                 }
             }
@@ -129,50 +77,11 @@ impl Loader<'_> {
         onload
     }
 
-    /// Compile a handler element into `function(self, ...) <body> end`, or resolve its
-    /// `function="Global"` reference. A syntax error in the body is recorded as an error (and the
-    /// handler dropped), never a panic.
-    ///
-    /// ## `self` falls back to `this`, and that one clause is a whole class of addon bug
-    ///
-    /// The 1.12 contract for an XML script body is that it takes **no arguments**: the frame
-    /// arrives as the `this` global, which [`crate::script::event::invoke_with_globals`] sets
-    /// around every dispatch. This engine also passes the modern `(self, event, …)` positionals —
-    /// convenient, and what Era-era addons expect — and our own FrameXML is written against
-    /// *that* spelling (`<OnEnter>BenillaBagToggle_OnEnter(self)</OnEnter>`).
-    ///
-    /// The two spellings agree right up until **an addon captures a script and calls it back**,
-    /// which is the standard 1.12 hook idiom and the reason `GetScript` exists:
-    ///
-    /// ```lua
-    /// bMainBag_OnEnter = MainMenuBarBackpackButton:GetScript("OnEnter")  -- Bagnon.lua:61
-    /// MainMenuBarBackpackButton:SetScript("OnEnter", BagnonBlizMainBag_OnEnter)
-    /// function BagnonBlizMainBag_OnEnter()
-    ///     …
-    ///     bMainBag_OnEnter()      -- l.87: no arguments. The reference's contract.
-    /// end
-    /// ```
-    ///
-    /// The re-entry is perfectly legal, `this` is correctly set (Bagnon's own body reads
-    /// `this:GetID()` one line above), and our compiled body still took `self` from argument 1 —
-    /// which was nil. The director saw it as `bad argument #2: error converting Lua nil to table`
-    /// out of `GameTooltip:SetOwner`, from a handler that works perfectly when the engine calls it.
-    ///
-    /// So the fallback lives **here**, once, rather than as `(self or this)` sprinkled through
-    /// ~20 handler bodies: any XML body in any file — ours or an addon's — now works under both
-    /// callers.
-    ///
-    /// ## The prologue shares the body's first line, and that is a line-number fix
-    ///
-    /// The reference compiles the handler body **as the chunk**: `0x704c70` takes the raw text and
-    /// `luaL_loadbuffer`s it, so body line *n* is chunk line *n*. Our wrapper used to end with a
-    /// newline, which pushed every body line down by one — a `<OnClick>` whose code sat on the
-    /// element's second line reported `:3:` where the reference reports `:2:`. Keeping the
-    /// prologue on the body's own first line restores the reference's numbering exactly; the
-    /// closing `end` is the only line we add, and it lands *after* the body.
-    ///
-    /// `owner` is the frame's `GetName()` (or `<unnamed>`) — see [`Self::apply_scripts`] for the
-    /// bytes; `dbg` names the load for the report and is deliberately not the same string.
+    /// Compile a handler body, or resolve its `function=` global: not 1.12, whose loader never
+    /// reads the attribute. A 1.12 body takes no arguments and reads its frame from `this`; the
+    /// `self` parameter is not 1.12 either (our `assets/ui` bodies use it) and falls back to `this`
+    /// for a hook that calls a captured handler bare. The prologue shares the body's first line,
+    /// so line numbers match the reference, which loads the raw body as the chunk (`0x704c70`).
     pub(super) fn compile_handler(
         &mut self,
         handler: &Element,
@@ -180,10 +89,7 @@ impl Loader<'_> {
         owner: &str,
         dbg: &str,
     ) -> Option<Function> {
-        // **The raw body, NOT a trimmed one** — 1.12 hands `node->text` straight to
-        // `luaL_loadbuffer` and tests only its first byte, so a whitespace-only body is a real
-        // (empty) chunk there and must be one here. See `apply_scripts` for the bytes and for the
-        // seven stock files that depend on it.
+        // The raw body, never trimmed: a whitespace body is a real empty chunk (`apply_scripts`).
         let body = handler.body.as_str();
         if !body.is_empty() {
             let src = format!(
@@ -222,13 +128,9 @@ impl Loader<'_> {
         None
     }
 
-    /// Fire a captured `OnLoad` with the frame wrapper as both the legacy `this` global (RF-0025,
-    /// set-then-restored) and the modern `self` argument — the same dual convention the host's event
-    /// path uses; we replicate only the `this` set/restore here because there is no public host API to
-    /// fire `OnLoad` directly (it is not an event). Handler errors are recorded, never propagated.
+    /// Fire a captured `OnLoad` under the event path's convention, `this` set and restored
+    /// (`0x704d50`); an error is recorded, never propagated.
     pub(super) fn fire_onload(&mut self, wrapper: &Table, func: &Function, dbg: &str) {
-        // The RF-0025 `this`/`self` convention lives in one home (`UiScript::invoke_handler`); the
-        // loader doesn't re-implement the set/restore, it just supplies the wrapper + captured func.
         if let Err(e) = self.invoke_handler(wrapper, func) {
             self.report.errors.push(format!("{dbg}: OnLoad: {e}"));
         }
diff --git a/crates/benilla-ui/src/loader/tests.rs b/crates/benilla-ui/src/loader/tests.rs
index c7a411fc..a2ba089b 100644
--- a/crates/benilla-ui/src/loader/tests.rs
+++ b/crates/benilla-ui/src/loader/tests.rs
@@ -1,4 +1,4 @@
-//! Loader tests — split from `mod.rs` (file-size budget); same `super::*` view.
+//! Loader tests.
 
 mod loader_tests {
     use crate::framexml;
@@ -6,7 +6,6 @@ mod loader_tests {
     use crate::order::ZTarget;
     use crate::script::{QuadContent, UiScript};
 
-    /// No-provider `files` closure (for docs with no `<Include>`/`<Script file=>`).
     fn no_files(_: &str) -> Option<Vec<u8>> {
         None
     }
@@ -15,16 +14,9 @@ mod loader_tests {
         framexml::parse(text).expect("valid FrameXML")
     }
 
-    /// **`<Minimap>`'s two model attributes name the nine engine children** — the model half of
-    /// `CMinimap::LoadXML 0x4ee2b0`. `minimapArrowModel` goes to children 1–8 through `0x4ee170`'s
-    /// two loops (the five at `[+0x320]`, the three POI arrows at `[+0x314]`);
-    /// `minimapPlayerModel` goes to `[Minimap+0x338]` — child **9** — alone, through `0x4ee260`.
-    /// Without the split all nine read back `GetModel() == ""` and nothing in the tuple says which
-    /// one is the player arrow.
-    ///
-    /// Both halves in one document: the shipped spelling (`Minimap.xml:97` sets both explicitly)
-    /// and an attribute-less `<Minimap>`, which takes the engine defaults `0x84c768` / `0x8453c0`
-    /// rather than staying file-less.
+    /// `CMinimap::LoadXML 0x4ee2b0`: `minimapArrowModel` goes to engine children 1-8 (`0x4ee170`),
+    /// `minimapPlayerModel` to child 9 alone (`[Minimap+0x338]`, `0x4ee260`); without the
+    /// attributes the defaults are `0x84c768` and `0x8453c0`. `Minimap.xml:97` sets both.
     #[test]
     fn the_minimap_model_attributes_name_the_nine_engine_children() {
         let mut s = UiScript::new().unwrap();
@@ -49,7 +41,6 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
 
-        // 1–8 wear the arrow, 9 wears the player model — the authored spelling, unchanged.
         for i in 1..=8 {
             assert_eq!(
                 s.eval::<String>(&format!(
@@ -67,16 +58,14 @@ mod loader_tests {
             "child 9 — [Minimap+0x338] — takes minimapPlayerModel alone"
         );
 
-        // The `<Frames>` child lands PAST the nine, because the factory runs before the descent
-        // (`0x6ee408` before `0x6ee4ea`) and both linkers append at the tail. This is the whole
-        // reason `[9]` is a stable address for an addon.
+        // The `<Frames>` child comes after the nine: the factory runs before the descent
+        // (`0x6ee408` before `0x6ee4ea`) and both append at the tail.
         assert_eq!(
             s.eval::<String>("return ({Minimap:GetChildren()})[10]:GetName()")
                 .unwrap(),
             "MiniMapPingHost"
         );
 
-        // No attributes: the engine defaults, not nothing.
         assert_eq!(
             s.eval::<String>("return ({BareMinimap:GetChildren()})[1]:GetModel()")
                 .unwrap(),
@@ -89,13 +78,7 @@ mod loader_tests {
         );
     }
 
-    /// **`parent="Name"` attaches a top-level element** — the reference's own way of doing it,
-    /// because its FrameXML is flat (decision 1211). 79 corpus addons, 708 sites.
-    ///
-    /// Three claims in one document: the attribute supplies the parent when there is no lexical
-    /// one; an anchor with no `relativeTo` then measures from THAT parent rather than the screen
-    /// (the silent half — a frame in the wrong place with nothing to report); and a name that
-    /// resolves to nothing warns and falls back instead of raising.
+    /// The stock FrameXML attaches with `parent=`; a `relativeTo`-less anchor measures from it.
     #[test]
     fn a_top_level_parent_attribute_attaches_and_anchors() {
         let mut s = UiScript::new().unwrap();
@@ -142,7 +125,6 @@ mod loader_tests {
             "a relativeTo-less anchor measures from the PARENT, not the screen"
         );
 
-        // The miss: a warning, a usable frame, and no parent — never an error.
         assert!(s.eval::<bool>("return Orphan ~= nil").unwrap());
         assert!(s.eval::<bool>("return Orphan:GetParent() == nil").unwrap());
         assert!(
@@ -151,10 +133,7 @@ mod loader_tests {
             report.warnings
         );
 
-        // And a name that exists but is NOT a frame is the same miss, not a raise. `_G` is one
-        // namespace and an addon's own `MyAddon = {}` lives in it — the corpus writes
-        // `parent="TheoryCraft"` where the addon owns that name. Handing a plain table to
-        // CreateFrame would kill the element and its whole subtree.
+        // A global that is not a frame is the same miss, not a raise.
         s.run("NotAFrame = { some = 'table' }").unwrap();
         let doc2 = parse(
             r#"<Ui>
@@ -177,16 +156,8 @@ mod loader_tests {
         );
     }
 
-    /// **A `parent=` that resolves to nothing leaves the frame PARENTLESS** — it does not fall back
-    /// to the enclosing frame (decision 2213). `0x6ee280` seeds `[ebp-0x8]` with the incoming
-    /// default parent and then writes the lookup's result back **unconditionally** at
-    /// `0x6ee3ef`, so a miss stores 0 over the seed and `0x6ee408` constructs with `ecx = 0`
-    /// (wow-re `xml-parent-attach-order.md`, VERIFIED). And an **empty** `parent=""` short-circuits
-    /// at `0x6ee3c7` before any of that: the default parent is kept, silently.
-    ///
-    /// Only the nested case can tell these apart — at top level there is no enclosing frame to
-    /// fall back to, which is why
-    /// [`Self::a_top_level_parent_attribute_attaches_and_anchors`] passed either way.
+    /// A miss stores 0 over the default parent (`0x6ee3ef`), so the frame is built parentless; an
+    /// empty `parent=""` keeps the default silently (`0x6ee3c7`).
     #[test]
     fn a_parent_attribute_that_misses_leaves_the_frame_parentless() {
         let mut s = UiScript::new().unwrap();
@@ -213,15 +184,13 @@ mod loader_tests {
         assert!(report.errors.is_empty(), "{:?}", report.errors);
         s.resolve();
 
-        // The miss: parentless, NOT re-attached to Enclosing.
         assert!(s.eval::<bool>("return TopMissed ~= nil").unwrap());
         assert!(
             s.eval::<bool>("return TopMissed:GetParent() == nil")
                 .unwrap(),
             "a parent= that names nothing nulls the parent; it does not fall back"
         );
-        // …and with no parent, the `$parent` chain walk finds nothing, so the "Top" seed survives
-        // (rf27 §5) — hence `TopMissed`, not `EnclosingMissed`.
+        // With no parent, `$parent` falls to the `"Top"` seed (`0x76c5b0`): `TopMissed`.
         assert!(s.eval::<bool>("return EnclosingMissed == nil").unwrap());
         assert!(
             report
@@ -232,7 +201,6 @@ mod loader_tests {
             report.warnings
         );
 
-        // The empty attribute: the enclosing frame is kept, and nothing is logged.
         assert_eq!(
             s.eval::<String>("return EnclosingEmpty:GetParent():GetName()")
                 .unwrap(),
@@ -246,18 +214,8 @@ mod loader_tests {
         );
     }
 
-    /// **A top-level `name="$parent…"` resolves against the `parent=` attribute** (B387) — the
-    /// reference attaches the parent *first* (`0x6ee280` resolves it at `0x6ee3e8` and passes it to
-    /// the constructor at `0x6ee408`) and only then runs the node-apply step that reads `name=` and
-    /// calls `SetName` (`0x6ee4d6`), whose expander walks the frame's **actual** parent chain
-    /// (rf27 `0x76c5b0`). We resolved the name first, against the lexical ancestor, so ClassIcons'
-    /// `<Frame name="$parentClassIcon" parent="PlayerFrame"/>` was published as `TopClassIcon` and
-    /// every `PlayerFrameClassIcon` lookup in the addon indexed a nil.
-    ///
-    /// Four claims: the name takes the attribute parent's name; that frame's own children compose
-    /// off the corrected name; a top-level `$parent` with no attribute still falls to the `"Top"`
-    /// seed; and the `parent=` attribute itself is NOT expanded (`0x6ee3e8` calls the by-name
-    /// resolver direct, bypassing `0x76c5b0` — rf27 §2).
+    /// The reference attaches the parent (`0x6ee408`) before it applies `name=` (`0x6ee4d6`), and
+    /// `$parent` walks the real parent chain (`0x76c5b0`); `parent=` itself is never expanded.
     #[test]
     fn a_dollar_parent_name_resolves_against_the_parent_attribute() {
         let mut s = UiScript::new().unwrap();
@@ -310,11 +268,10 @@ mod loader_tests {
             "a nested child composes off the CORRECTED name"
         );
 
-        // No attribute, no lexical parent: the expander's `"Top"` seed survives (rf27 §5).
+        // No attribute, no lexical parent: the `"Top"` seed.
         assert!(s.eval::<bool>("return TopLoose ~= nil").unwrap());
 
-        // `parent="$parentPlayerFrame"` is taken LITERALLY — `0x6ee3e8` hands the raw string to
-        // `0x76c760`, so no frame of that name exists and the element falls back (and warns).
+        // `parent=` is taken literally (`0x6ee3e8` hands it to `0x76c760`), so this one misses.
         assert!(s.eval::<bool>("return Literal:GetParent() == nil").unwrap());
         assert!(
             report
@@ -326,15 +283,11 @@ mod loader_tests {
         );
     }
 
-    /// End-to-end: a virtual template, an instance inheriting it (with `<Size>`, screen `<Anchors>`,
-    /// a `<Layers>` coloured `<Texture>`, a nested child `<Frame>` in `<Frames>`, and `<OnLoad>`
-    /// handlers on both) — proving name publication, bottom-up OnLoad, `$parent`, and that
-    /// resolve()+extract() places the texture at the anchored rect.
+    /// Names, `$parent`, bottom-up `OnLoad` and the anchored texture rect, end to end.
     #[test]
     fn synthetic_full_document_materializes() {
         let mut s = UiScript::new().unwrap();
         s.set_screen_size(800.0, 600.0);
-        // Seed the ordering witness before the load runs any OnLoad.
         s.run("loadorder = {}").unwrap();
 
         let doc = parse(
@@ -373,26 +326,22 @@ mod loader_tests {
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
         assert_eq!(report.frames, 2, "parent + child materialized");
 
-        // Frame exists by name; the child's $parent resolved to MyFrameChild; the texture published
-        // its $parent-resolved name.
         assert!(s.eval::<bool>("return MyFrame ~= nil").unwrap());
         assert!(s.eval::<bool>("return MyFrameChild ~= nil").unwrap());
         assert!(s.eval::<bool>("return MyFrameTex ~= nil").unwrap());
 
-        // OnLoad fired for both (modern `self` in child, legacy `this` in parent — both work).
+        // The child's handler uses `self`, the parent's `this`; both work.
         assert_eq!(
             s.eval::<String>("return ChildLoaded").unwrap(),
             "MyFrameChild"
         );
         assert_eq!(s.eval::<String>("return ParentLoaded").unwrap(), "MyFrame");
 
-        // Bottom-up: the child's OnLoad ran before the parent's (rf26).
+        // Bottom-up: the child's OnLoad ran before the parent's (`0x76a060`).
         let order: Vec<String> = s.eval("return loadorder").unwrap();
         assert_eq!(order, vec!["child".to_string(), "parent".to_string()]);
 
-        // resolve()+extract(): the texture quad sits at MyFrame's anchored rect.
-        // Screen [0,0,600,800], TOPLEFT+(10,-20), size 200x100 → Rect(bottom 480, left 10, top 580,
-        // right 210). Region rect = its owner frame's resolved rect (v1).
+        // TOPLEFT+(10,-20), 200x100 on 800x600: bottom 480, left 10, top 580, right 210.
         s.resolve();
         let quads = s.extract();
         let tex = quads
@@ -408,11 +357,8 @@ mod loader_tests {
         );
     }
 
-    /// An instance's own `<Size>` beats its template's: expansion appends the instance's children
-    /// after the template's, and `apply_size` walks EVERY `<Size>` in document order so the last
-    /// write wins — exactly the client's process-each-child behavior. (Regression: `.next()` here
-    /// once pinned every templated button to the TEMPLATE's size; the quest log's Abandon button
-    /// declared 125×21 and rendered 80×22, wrapping its label onto two lines.)
+    /// Expansion appends the instance's children after the template's and every `<Size>` applies
+    /// in order, as the client processes each child, so the last wins.
     #[test]
     fn instance_size_overrides_template_size() {
         let s = UiScript::new().unwrap();
@@ -438,10 +384,6 @@ mod loader_tests {
         );
     }
 
-    /// A `<Frame setAllPoints="true">` (no `<Size>`/`<Anchors>` of its own) resolves to its
-    /// parent's rect — the frame path honors the shorthand like the region path does.
-    /// (Regression: only regions applied it; the world map's chrome frames carried the attribute,
-    /// never resolved, and their whole subtrees — backdrop, title, buttons — silently vanished.)
     #[test]
     fn frame_set_all_points_pins_to_parent() {
         let mut s = UiScript::new().unwrap();
@@ -470,16 +412,8 @@ mod loader_tests {
         assert_eq!(s.eval::<f32>("return PinChild:GetHeight()").unwrap(), 200.0);
     }
 
-    /// **`<Include file="X.lua">` RUNS the file** — the client's `<Include>` is a recursion into
-    /// its load-one-file routine `0x6ede10`, whose first act is a case-insensitive `.lua` suffix
-    /// test on the resolved path. It never sniffs content; it never parses a `.lua` as XML.
-    ///
-    /// We parsed every target as FrameXML, so a `.lua` target died `unknown token at 1:1` and took
-    /// the whole library set with it. Three corpus addons load nothing but these lines —
-    /// FonzAppraiser, AckisRecipeList, FonzSummon — and `embeds.xml` is the whole of their Ace
-    /// dependency chain.
-    ///
-    /// The mixed document is the point: one `<Include>` of each kind, in one file, both landing.
+    /// `<Include>` recurses into `0x6ede10`, which runs a path with a case-insensitive `.lua`
+    /// suffix and parses anything else as XML; it never sniffs content.
     #[test]
     fn include_runs_a_lua_target_and_still_parses_an_xml_one() {
         let s = UiScript::new().unwrap();
@@ -511,16 +445,13 @@ mod loader_tests {
             s.eval::<bool>("return ShoutyLua").unwrap(),
             "case-insensitive suffix"
         );
-        // ...and the XML arm is untouched: both frames still exist.
         assert_eq!(report.frames, 2);
         assert!(s
             .eval::<bool>("return FromXmlInclude ~= nil and FromMain ~= nil")
             .unwrap());
     }
 
-    /// A raise inside an `.lua` Include is reported and the enclosing document CONTINUES — the
-    /// reference logs at severity 2 and falls through (`0x6ee00d` -> `0x6ee012` is unconditional,
-    /// `eax` never read), so one bad library must not cost the frames declared after it.
+    /// The reference logs the raise and falls through unconditionally (`0x6ee00d`-`0x6ee012`).
     #[test]
     fn a_raising_lua_include_does_not_take_the_rest_of_the_document() {
         let s = UiScript::new().unwrap();
@@ -550,7 +481,6 @@ mod loader_tests {
         );
     }
 
-    /// `<Include>` resolved through an in-memory provider closure.
     #[test]
     fn include_resolves_through_provider() {
         let s = UiScript::new().unwrap();
@@ -574,15 +504,8 @@ mod loader_tests {
             .unwrap());
     }
 
-    /// **An unrecognised `frameStrata=` warns and skips; the frame keeps the stratum it had, and
-    /// the rest of the document loads** (decision 2160).
-    ///
-    /// The two doors differ in the reference and this is the quiet one. `CSimpleFrame::LoadXML
-    /// 0x769820` resolves through `0x6f17d0`, whose miss returns 0 without writing the out-param;
-    /// the miss leg pushes `"Frame %s: Unknown frame strata: %s"` at severity 1 into the document
-    /// sink (`0x7699a4`, a call that returns) and reconverges with the hit path at `0x7699ad`,
-    /// never reaching `SetFrameStrata 0x76a470`. `EQL3`'s `EQL3_Log.xml` carries the literal case:
-    /// `<Frame frameStrata="ARTWORK">`, a draw-LAYER name where a strata belongs.
+    /// `CSimpleFrame::LoadXML 0x769820`: a strata `0x6f17d0` does not know logs at severity 1
+    /// (`0x7699a4`) and skips `SetFrameStrata 0x76a470`.
     #[test]
     fn an_unknown_xml_frame_strata_warns_and_leaves_the_stratum_alone() {
         let mut s = UiScript::new().unwrap();
@@ -617,10 +540,7 @@ mod loader_tests {
         );
     }
 
-    /// **The Lua door is the LOUD one and stays that way.** `SetFrameStrata 0x774360`'s miss
-    /// reaches `0x774456 call 0x6f4940` (`luaL_error`), whose chain `luaG_errormsg 0x6fc780` /
-    /// `luaD_throw 0x6f5d80` contains no `ret` at all — the epilogue after it is dead code. Pinned
-    /// beside its XML twin so the asymmetry is a test rather than a comment.
+    /// The Lua `SetFrameStrata 0x774360` raises on the same value (`luaL_error` at `0x774456`).
     #[test]
     fn the_lua_setframestrata_still_raises_on_the_same_value() {
         let s = UiScript::new().unwrap();
@@ -632,10 +552,8 @@ mod loader_tests {
         assert!(err.contains("ARTWORK"), "{err}");
     }
 
-    /// **`FrameXML_Debug` is a get-or-set whose SET arm turns on the loader's trace lines**
-    /// (decision 2160) — and `0` takes the SET arm, because the number zero is Lua-truthy and only
-    /// `nil`/`false` are not (`0x48845d`, after `lua_toboolean 0x6f34d0`). That is the half a
-    /// re-implementation gets backwards, so it is the half asserted first.
+    /// The reference sets the flag from a number, `0` included, and only reads it for any other
+    /// argument (`0x48845d`, after `lua_isnumber 0x6f34d0`).
     #[test]
     fn framexml_debug_is_a_get_or_set_and_gates_the_loader_traces() {
         let s = UiScript::new().unwrap();
@@ -660,7 +578,6 @@ mod loader_tests {
             "{on:?}"
         );
 
-        // The two arms that are easy to get wrong.
         assert_eq!(
             s.eval::<i32>("return FrameXML_Debug(nil)").unwrap(),
             1,
@@ -672,19 +589,11 @@ mod loader_tests {
             "…but 0 is TRUTHY in Lua, so it really does disable it"
         );
         assert!(load(&s, &doc(), &no_files).traces.is_empty());
-        // …and the stored value is truncated toward zero, `0x40a2b0`'s conversion.
+        // The stored value truncates toward zero (`0x40a2b0`).
         assert_eq!(s.eval::<i32>("return FrameXML_Debug(1.9)").unwrap(), 1);
     }
 
-    /// A missing include is **reported, not raised**, and the rest of the load still proceeds.
-    ///
-    /// It was a warning until 1186 and an error from 1186 to 2155; it is now its own list. Both of
-    /// the findings behind those moves are asserted here, because each undid the other:
-    /// **1186's** — a document that resolved *nothing* must not report success (Bagnon missed all
-    /// eleven of its references and came back with zero errors) — so the row is in the report; and
-    /// **2155's** — the reference logs `Couldn't open %s` and carries on with nothing raised
-    /// (wow-re `ui/scratch/xml-toc-path-resolution.md` §4, VERIFIED) — so the row is *not* in
-    /// `errors`, which is the list whose entries reach the player's red error dialog.
+    /// The reference logs `Couldn't open %s` (`0x6edaa0`, `0x846ff4`) and carries on.
     #[test]
     fn missing_include_is_a_missing_file_not_an_error_and_continues() {
         let s = UiScript::new().unwrap();
@@ -705,9 +614,7 @@ mod loader_tests {
         );
     }
 
-    /// So is a missing `<Script file=>` — it drops every handler the file would have defined, and
-    /// the reference's own leg for it (`"Error loading %s"`, `include-lua-dispatch.md` §7) returns
-    /// normally rather than throwing.
+    /// The reference logs `"Error loading %s"` (`0x872e50`) for it and returns normally.
     #[test]
     fn missing_script_file_is_a_missing_file_not_an_error_and_continues() {
         let s = UiScript::new().unwrap();
@@ -721,9 +628,6 @@ mod loader_tests {
         assert!(s.eval::<bool>("return Still ~= nil").unwrap());
     }
 
-    /// **A `<Script file=>` whose chunk RAISES is still an error** — the half `missing_files` must
-    /// not swallow. The two arms sit one line apart in `load_in`, and folding a miss into the
-    /// quiet list is only correct because the raise keeps its own.
     #[test]
     fn a_script_file_that_raises_is_still_an_error() {
         let s = UiScript::new().unwrap();
@@ -740,7 +644,6 @@ mod loader_tests {
         assert!(s.eval::<bool>("return Still ~= nil").unwrap());
     }
 
-    /// `$parent` resolves in a child's *name* and in an anchor's `relativeTo`.
     #[test]
     fn parent_token_in_child_name_and_anchor_relative_to() {
         let mut s = UiScript::new().unwrap();
@@ -765,10 +668,8 @@ mod loader_tests {
         );
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
-        // Child $parent-name resolved to PFInner and published.
         assert!(s.eval::<bool>("return PFInner ~= nil").unwrap());
 
-        // relativeTo="$parent" resolved to PF, so the child sits exactly on the parent's TOPLEFT.
         s.resolve();
         let quads = s.extract();
         let rects: Vec<_> = quads
@@ -778,8 +679,7 @@ mod loader_tests {
                 _ => None,
             })
             .collect();
-        // Parent: screen [0,0,600,800] TOPLEFT+(50,-50), 100x100 → Rect(450,50,550,150). The child,
-        // anchored TOPLEFT→parent TOPLEFT with no offset, resolves to the same rect.
+        // The parent is Rect(450,50,550,150); the child, pinned TOPLEFT to TOPLEFT, matches it.
         let expected = crate::layout::Rect::new(450.0, 50.0, 550.0, 150.0);
         assert!(
             rects.iter().filter(|r| **r == expected).count() >= 2,
@@ -787,9 +687,8 @@ mod loader_tests {
         );
     }
 
-    /// A named state texture and a named `<ButtonText>` are anchor targets by NAME, not only
-    /// globals: the stock trainer row hangs its label off `$parentHighlight`'s RIGHT, and a name
-    /// published only into `_G` sent the label to the button's own edge (1957).
+    /// The stock trainer row's shape: its label hangs off `$parentHighlight`'s RIGHT
+    /// (`ClassTrainerFrameTemplates.xml:67`).
     #[test]
     fn a_named_state_texture_is_an_anchor_target_for_its_sibling_label() {
         let mut s = UiScript::new().unwrap();
@@ -841,8 +740,6 @@ mod loader_tests {
         );
     }
 
-    /// A handler with a syntax error yields an `errors[]` entry, the load continues, and the other
-    /// frame is still built with a working handler.
     #[test]
     fn bad_handler_is_an_error_and_load_continues() {
         let s = UiScript::new().unwrap();
@@ -863,19 +760,11 @@ mod loader_tests {
             "expected a compile error, got {:?}",
             report.errors
         );
-        // The broken frame exists but its OnLoad never ran; the good frame's did.
         assert!(s.eval::<bool>("return Broken ~= nil").unwrap());
         assert!(s.eval::<bool>("return FineRan == true").unwrap());
     }
 
-    /// Unsupported handler names are warn-once gaps, not hard errors, and don't stop the frame
-    /// from building. The example is `OnAttributeChanged` — 2.0's secure-frame system, which no
-    /// 1.12 resolver has a slot for, so it is the one name on that list that is out permanently.
-    ///
-    /// It has been three names now, and each move is the rule working: `OnKeyDown` left when 1319
-    /// built the delivery walk, `OnCursorChanged` when 2141 built the caret flush's fire. A name
-    /// is accepted only once something fires it, so this test's subject is whatever is still
-    /// waiting.
+    /// `OnAttributeChanged` is 2.0's; no 1.12 handler resolver has a slot for it.
     #[test]
     fn unsupported_script_name_is_a_warning() {
         let s = UiScript::new().unwrap();
@@ -891,13 +780,8 @@ mod loader_tests {
             .any(|w| w.contains("OnAttributeChanged")));
     }
 
-    /// **An unknown frame type at the XML door is LOGGED, and its node is skipped — nothing
-    /// raises** (decision 2191).
-    ///
-    /// `Instantiate 0x6ee280` prints `"Unknown frame type: %s"` (`0x871124`) at `0x6ee356` and makes
-    /// no object for that node; only the Lua `CreateFrame` binding raises (`0x872fa8` via
-    /// `luaL_error`). The node's own `<Frames>` go with it — there is no object to parent them —
-    /// and the walk carries on to the next sibling.
+    /// `Instantiate 0x6ee280` logs `"Unknown frame type: %s"` (`0x871124`) and builds nothing for
+    /// the node or its `<Frames>`; only the Lua `CreateFrame` raises (`0x872fa8`).
     #[test]
     fn an_unknown_xml_frame_type_is_logged_and_its_node_skipped() {
         let s = UiScript::new().unwrap();
@@ -924,16 +808,13 @@ mod loader_tests {
         assert_eq!(report.frames, 1, "only the real frame built");
         assert!(s.eval::<bool>("return X == nil and Inside == nil").unwrap());
         assert!(s.eval::<bool>("return Real ~= nil").unwrap());
-        // …and the Lua door still raises, on the same lookup.
+        // The Lua door raises on the same lookup.
         let err = s.run(r#"CreateFrame("Bogus")"#).unwrap_err().to_string();
         assert!(err.contains("unknown frame type 'Bogus'"), "{err}");
     }
 
-    /// **A `.toc`-listed `Bindings.xml` loads as XML and costs nothing but log lines** (decision
-    /// 2191) — MonkeyDev's shape, the director's live report. The `.toc` line runner hands every
-    /// non-`.lua` entry to the same file loader (`0x6edd51` → `0x6ede10`), whose walk ignores the
-    /// root's own tag (`<Bindings>`, tolerated) and sees three `<Binding>` elements: three unknown
-    /// frame types, logged. The file's real reading as bindings is `0x51f400`'s, which runs anyway.
+    /// A `.toc` line hands a listed `Bindings.xml` to `0x6ede10` (from `0x6edd51`), so each
+    /// `<Binding>` logs as an unknown frame type; `0x51f400` reads the bindings regardless.
     #[test]
     fn a_bindings_document_loaded_as_framexml_raises_nothing() {
         let s = UiScript::new().unwrap();
@@ -961,8 +842,7 @@ mod loader_tests {
         );
     }
 
-    /// The WorldFrame's one-shot record, at the XML door: a second `<WorldFrame>` is an unknown
-    /// type, so it logs and builds nothing (decisions 1984, 2191) where `CreateFrame` raises.
+    /// The WorldFrame type is one-shot, so a second `<WorldFrame>` is an unknown type.
     #[test]
     fn a_second_xml_world_frame_is_logged_not_raised() {
         let s = UiScript::new().unwrap();
@@ -980,51 +860,7 @@ mod loader_tests {
         assert!(s.eval::<bool>("return Another == nil").unwrap());
     }
 
-    /// Env-gated smoke test over a real extracted FrameXML file (never committed; extract with
-    /// benilla-extract and point `BENILLA_FRAMEXML_LOAD` at it). Parses + loads with a provider over
-    /// the file's own directory, asserts no hard *parse/loader-internal* error, and reports how many
-    /// frames materialized plus the API/handler gaps the file surfaced. Skips silently otherwise,
-    /// matching framexml.rs's `real_framexml_when_available` pattern so gates never depend on client
-    /// data.
-    #[test]
-    fn real_framexml_load_when_available() {
-        let Ok(path) = std::env::var("BENILLA_FRAMEXML_LOAD") else {
-            return;
-        };
-        let text = std::fs::read_to_string(&path).expect("reading BENILLA_FRAMEXML_LOAD");
-        let dir = std::path::Path::new(&path)
-            .parent()
-            .map(|p| p.to_path_buf())
-            .unwrap_or_default();
-        // Provider: resolve an XML/Lua reference against the file's directory, trying the path as
-        // given and by basename (Blizzard paths use backslashes and are dir-relative).
-        let provider = move |req: &str| -> Option<Vec<u8>> {
-            let norm = req.replace('\\', "/");
-            let base = norm.rsplit('/').next().unwrap_or(&norm);
-            std::fs::read(dir.join(&norm))
-                .or_else(|_| std::fs::read(dir.join(base)))
-                .ok()
-        };
-
-        let s = UiScript::new().unwrap();
-        let doc = framexml::parse(&text).unwrap_or_else(|e| panic!("{path}: {e}"));
-        let report = load(&s, &doc, &provider);
-
-        eprintln!("== {path}: {} frames materialized ==", report.frames);
-        for e in &report.errors {
-            eprintln!("  error: {e}");
-        }
-        for w in &report.warnings {
-            eprintln!("  warn:  {w}");
-        }
-        // Script errors surfaced by any OnLoad that ran against missing API:
-        for e in s.errors() {
-            eprintln!("  script-error: {e}");
-        }
-    }
-
-    /// `<StatusBar>` LoadXML extras (RF-28): value attributes, `<BarTexture>` + `<BarColor>`
-    /// children, orientation — landing in the widget state and scaling the extracted bar quad.
+    /// `<StatusBar>` LoadXML extras (`0x782ef0`).
     #[test]
     fn statusbar_xml_extras_apply() {
         let mut s = UiScript::new().unwrap();
@@ -1077,11 +913,8 @@ mod loader_tests {
         );
     }
 
-    /// The creation-path implicit anchor, XML half (decision 1310; wow-re
-    /// `region-implicit-anchor.md`, §5 VERIFIED): a `<Texture>` with zero anchors gets
-    /// SetAllPoints(parent) right after its LoadXML — two corner anchors that pin all four
-    /// edges, so an authored `<Size>` is structurally unread. This is B180's engine shape: the
-    /// reference stack-split plate authors a vestigial 256×32 and renders 172×96, the frame.
+    /// An anchorless `<Texture>` gets `SetAllPoints` after its LoadXML (`0x7701c0`), so its
+    /// `<Size>` goes unread: `StackSplitFrame.xml:10` authors 256×32 and draws 172×96.
     #[test]
     fn sized_anchorless_layer_texture_fills_its_frame() {
         let mut s = UiScript::new().unwrap();
@@ -1120,9 +953,8 @@ mod loader_tests {
         );
     }
 
-    /// The FontString half of the same law: zero anchors ⇒ ONE middle-row SetPoint chosen by the
-    /// live justify word (`&7`: 1→LEFT, 4→RIGHT, else CENTER) — and the authored `<Size>` stays
-    /// LIVE (single anchor + W/H sizes the opposite edges), unlike the texture's.
+    /// A FontString with no anchors gets one middle-row point from its justify word (`&7`: 1 LEFT,
+    /// 4 RIGHT, else CENTER), so unlike a texture's its `<Size>` stays live.
     #[test]
     fn anchorless_fontstring_seats_at_its_justify_point() {
         let mut s = UiScript::new().unwrap();
@@ -1145,8 +977,7 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
         s.resolve();
-        // LEFT→LEFT at (0,0): left edge at the page's left, vertically on the page's centerline
-        // (middle-row point), 80×20 from the size. Page [0,0]..[200,100] → [0,40]..[80,60].
+        // LEFT to LEFT on the page's centreline, 80×20 from the size: [0,40]..[80,60].
         let (l, r, t, b) = s
             .eval::<(f64, f64, f64, f64)>(
                 "return SeatLeft:GetLeft(), SeatLeft:GetRight(), SeatLeft:GetTop(), SeatLeft:GetBottom()",
@@ -1159,10 +990,8 @@ mod loader_tests {
         );
     }
 
-    /// The XML state-texture ordering (decision 1310's loader half): an authored `<Anchors>` on a
-    /// `<NormalTexture>` wins outright — the materializing setter's implicit SetAllPoints is
-    /// cleared before the authored layout applies, so no implicit corner survives to weld the
-    /// region to the button (the merchant row's icon-scoped highlight is the live consumer).
+    /// The setter's implicit `SetAllPoints` is cleared before the authored anchors apply, so no
+    /// implicit corner survives to weld the state texture to the button.
     #[test]
     fn anchored_state_texture_keeps_its_authored_anchors() {
         let mut s = UiScript::new().unwrap();
@@ -1203,17 +1032,8 @@ mod loader_tests {
         );
     }
 
-    /// **An XML handler body's chunk name is `"<GetName()>:<Handler>"`, and its lines are the
-    /// body's own.** `0x7025fd` calls the script object's `GetName` through its vtable, falls back
-    /// to `<unnamed>` (`0x84c7f0`) at `0x702611`, formats `"%s:%s"` (`0x872a28`) at `0x70261b`,
-    /// and hands that to `0x704c70` at `0x70263c` — which `luaL_loadbuffer`s the raw body, so body
-    /// line *n* is chunk line *n*.
-    ///
-    /// Three producers, because they used to disagree. A named element was already right; an
-    /// unnamed one wrote `<Button>` where the image writes `<unnamed>`; and a `CreateFrame` off a
-    /// template wrote the *whole call* —
-    /// `CreateFrame("Button", "Made", inherits="ProbeTmpl"):OnClick` — into every error message
-    /// and every `debugstack` frame that handler produced.
+    /// `0x7025fd` names a handler chunk `"%s:%s"` (`0x872a28`) from the object's `GetName`, or
+    /// `<unnamed>` (`0x84c7f0`), and `0x704c70` loads the raw body, so body line n is chunk line n.
     #[test]
     fn an_xml_handler_chunk_is_named_by_its_frame_and_handler() {
         let s = UiScript::new().unwrap();
@@ -1247,22 +1067,18 @@ mod loader_tests {
                 .unwrap()
         };
 
-        // A named element. The body sits on the element's SECOND line, and the reference numbers a
-        // handler chunk from the body's own first line — so `:2:`, never `:3:`. Our wrapper used
-        // to end with a newline, which pushed every body line down by one.
+        // The `error` is on the body's second line: `:2:`.
         let named = raised(r#"NamedBtn:GetScript("OnClick")"#);
         assert!(
             named.starts_with(r#"[string "NamedBtn:OnClick"]:2: boom"#),
             "{named}"
         );
-        // A `CreateFrame` instance is named by the INSTANCE — what `GetName()` answers — not by
-        // the call that made it and not by the template it wore.
+        // A `CreateFrame` instance is named by its own `GetName()`, not by its template.
         let made = raised(r#"Made:GetScript("OnClick")"#);
         assert!(
             made.starts_with(r#"[string "Made:OnClick"]:1: tmpl"#),
             "{made}"
         );
-        // The nameless element takes the image's own fallback literal.
         let anon = raised(r#"BenillaAnon:GetScript("OnClick")"#);
         assert!(
             anon.starts_with(r#"[string "<unnamed>:OnClick"]:1: anon"#),
@@ -1270,14 +1086,8 @@ mod loader_tests {
         );
     }
 
-    /// **An inline `<Script>` body is `"<xml path>:<Scripts>"`, with no `@`** — `0x6ee0ed push ebx`
-    /// (the document's own path) / `0x6ee0ee push 0x871074` (`"%s:<Scripts>"`) → `0x6ee0ff` sprintf
-    /// → `0x6ee10f call 0x704cd0`. `luaO_chunkid` therefore takes its *third* branch and the frame
-    /// reads `[string "…"]`, not a bare path — which is how a reader (and every addon that splits a
-    /// `debugstack` frame on `\AddOns\`) tells an inline block from the `.lua` file beside it.
-    ///
-    /// `<Script file="…">` keeps the file form, `"@%s"` (`0x8716e0`), and both are asserted here so
-    /// the two arms cannot drift into each other.
+    /// An inline `<Script>` is `"%s:<Scripts>"` (`0x871074`, at `0x6ee0ff`) over the document's
+    /// path with no `@`, so it reads `[string "…"]`; a `<Script file=>` is `"@%s"` (`0x8716e0`).
     #[test]
     fn an_inline_script_chunk_is_named_for_the_document_not_as_a_file() {
         let s = UiScript::new().unwrap();
@@ -1349,7 +1159,6 @@ mod loader_tests {
             .unwrap();
         assert!(ok, "button XML attrs + textures landed");
 
-        // The checked CheckButton draws its check mark; the idle Button draws only its normal.
         s.resolve();
         let texs: Vec<String> = s
             .extract()
@@ -1364,16 +1173,12 @@ mod loader_tests {
         assert!(!texs.contains(&"Interface\\B-Hi".into()));
         assert!(texs.contains(&"Interface\\CB-Check".into()));
 
-        // A physical click fires the XML OnClick.
         s.mouse_button(30.0, 10.0, "LeftButton", true);
         s.mouse_button(30.0, 10.0, "LeftButton", false);
         assert!(s.eval::<bool>("return xml_clicked == true").unwrap());
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// A state texture's own `<Size>` + `<Anchors>` scope it to less than its button (the merchant
-    /// row's icon-scoped highlight): hovering the 100px-wide button, the highlight quad renders at
-    /// the anchored 20px square, not stretched over the button.
     #[test]
     fn button_state_texture_takes_size_and_anchors() {
         let mut s = UiScript::new().unwrap();
@@ -1397,8 +1202,7 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-        // Hover the button's far-right end — the highlight still sits at the anchored TOPLEFT.
-        // (Resolve first: hit-testing reads the resolved-rect cache.)
+        // Resolve first: hit-testing reads the resolved-rect cache.
         s.resolve();
         s.mouse_move(90.0, 15.0);
         s.resolve();
@@ -1419,8 +1223,7 @@ mod loader_tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// `<EditBox>` LoadXML extras (RF-0082): `letters` → SetMaxLetters and the config flags land in
-    /// the widget state; a click focuses it and the `<OnTextChanged>` handler fires on a typed char.
+    /// `<EditBox>` LoadXML extras (`0x779fb0`).
     #[test]
     fn editbox_xml_extras_apply() {
         let mut s = UiScript::new().unwrap();
@@ -1443,7 +1246,6 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-        // letters=5 landed; numeric abort rejects a non-digit insert wholesale.
         assert_eq!(s.eval::<i64>("return XmlEdit:GetNumLetters()").unwrap(), 0);
         s.run(r#"XmlEdit:Insert("12x")"#).unwrap(); // numeric: aborts
         s.run(r#"XmlEdit:Insert("123456")"#).unwrap(); // digits, capped at 5
@@ -1452,8 +1254,7 @@ mod loader_tests {
             "12345"
         );
 
-        // A click focuses the box (mouse-enabled by construction); a typed char marks it changed,
-        // and the drain on the next tick is what actually fires OnTextChanged (decision 1831).
+        // A typed char marks the box changed; `OnTextChanged` fires on the next tick's drain.
         s.resolve();
         s.mouse_button(50.0, 10.0, "LeftButton", true);
         s.mouse_button(50.0, 10.0, "LeftButton", false);
@@ -1465,15 +1266,8 @@ mod loader_tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// **`autoFocus="false"` is an opt-OUT, and the only reason the attribute is ever written.**
-    ///
-    /// The ctor leaves `flags = 1` — autoFocus ON — so every one of the ten places the shipped
-    /// 1.12.1 chain names the attribute names it to turn the flag *off* (MailFrame ×3,
-    /// MoneyInputFrame ×3, FriendsFrame ×3, AddonList ×1). The flag loop used to call the setter
-    /// only when an attribute parsed as `true`, which made all ten a no-op: harmless while our own
-    /// default was off, and exactly backwards once it matches the client's (decision 1686).
-    ///
-    /// Both directions asserted, because a presence-blind reader passes the `true` half.
+    /// The EditBox ctor leaves autoFocus on (`flags = 1`), so the stock UI writes the attribute
+    /// only as `autoFocus="false"`: ten times across FrameXML and GlueXML.
     #[test]
     fn an_editbox_flag_written_false_in_xml_turns_the_flag_off() {
         let s = UiScript::new().unwrap();
@@ -1487,8 +1281,7 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-        // The box is hidden first so the Show() is a real transition; an autoFocus box takes the
-        // keyboard on show, which is the observable the flag actually drives.
+        // Hidden first so `Show()` is a real transition: an autoFocus box takes focus on show.
         for (name, want) in [("OptOut", false), ("OptIn", true), ("Silent", true)] {
             s.run(&format!(
                 "{name}:Hide(); {name}:ClearFocus(); {name}:Show()"
@@ -1504,10 +1297,9 @@ mod loader_tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    // ── TexCoords + Font objects (decision 0084 engine slice) ───────────────────────────────────
+    // ── TexCoords and font objects ──────────────────────────────────────────────────────────────
 
-    /// `<TexCoords left right top bottom>` on a `<Texture>` parses into the region's UV rect and
-    /// surfaces on the extracted quad as `[left, right, top, bottom]`.
+    /// The extracted quad carries the UV rect as `[left, right, top, bottom]`.
     #[test]
     fn texcoords_parse_to_uv_on_extracted_quad() {
         let mut s = UiScript::new().unwrap();
@@ -1544,8 +1336,6 @@ mod loader_tests {
         );
     }
 
-    /// A `<Font>` `inherits=` chain resolves height + color through two levels: the leaf inherits its
-    /// face + one value from the root and overrides another mid-chain (last-wins merge).
     #[test]
     fn font_inherits_chain_resolves_height_and_color_two_levels() {
         let s = UiScript::new().unwrap();
@@ -1571,15 +1361,13 @@ mod loader_tests {
         assert_eq!(base.height, Some(12.0));
         assert_eq!(base.color, Some([1.0, 0.82, 0.0, 1.0]));
 
-        // Leaf: face inherited from Base (through Mid), color from Mid (white), height overridden (10).
+        // Leaf: Base's face through Mid, Mid's white, its own height of 10.
         let leaf = s.font_object("Leaf").expect("Leaf registered");
         assert_eq!(leaf.font.as_deref(), Some("Fonts\\FRIZQT__.TTF"));
         assert_eq!(leaf.height, Some(10.0));
         assert_eq!(leaf.color, Some([1.0, 1.0, 1.0, 1.0]));
     }
 
-    /// A `<FontString inherits="GameFontNormalSmall">` reports the *smaller* resolved height (and the
-    /// inherited face + color) on the extracted quad — the per-FontString size the renderer bakes at.
     #[test]
     fn fontstring_inherits_reports_smaller_resolved_height() {
         let mut s = UiScript::new().unwrap();
@@ -1625,7 +1413,6 @@ mod loader_tests {
             "the *Small font object resolves to the smaller height"
         );
 
-        // The inherited face + color also flow through.
         let small = s
             .extract()
             .into_iter()
@@ -1638,8 +1425,6 @@ mod loader_tests {
         ));
     }
 
-    /// An explicit `<Color>` on a FontString overrides its font object's color; an `inherits=` naming
-    /// no registered font object is a warn-once gap, not a dropped region.
     #[test]
     fn fontstring_color_overrides_object_and_unknown_inherits_warns() {
         let mut s = UiScript::new().unwrap();
@@ -1670,7 +1455,7 @@ mod loader_tests {
             report.warnings
         );
         s.resolve();
-        // A's explicit <Color> wins over GameFontNormal's gold; its height still comes from the object.
+        // A's own <Color> wins over the object's gold; its height still comes from the object.
         let a = s
             .extract()
             .into_iter()
@@ -1681,19 +1466,14 @@ mod loader_tests {
             QuadContent::Text { color: Some(c), font_height: Some(h), .. }
                 if *c == [0.1, 0.2, 0.3, 1.0] && *h == 12.0
         ));
-        // B still materialized (the unknown inherits didn't drop it).
         assert!(s
             .extract()
             .into_iter()
             .any(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "B")));
     }
 
-    /// The chat edit box's shape: an EditBox with BOTH a `<Layers>` FontString (the "Say:" header)
-    /// and the special direct-child `<FontString>` (the engine's text-font slot). The box must
-    /// adopt the SPECIAL one as its text region — the engine ASSIGNS that slot at LoadXML, it
-    /// never searches. (The old find-first adoption grabbed the header: typing then overwrote
-    /// "Say:", and the `<TextInsets>` re-anchor clobbered the header's LEFT anchor into a
-    /// full-width rect — the centered-header + invisible-typing chat bug.)
+    /// The chat edit box's shape. The engine assigns the text slot from the direct-child
+    /// `<FontString>` at LoadXML; it never searches the regions, so the header stays its own.
     #[test]
     fn editbox_adopts_special_fontstring_not_a_layers_header() {
         let mut s = UiScript::new().unwrap();
@@ -1724,13 +1504,11 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-        // Type into the focused box.
         s.run("EB:SetFocus()").unwrap();
         assert!(s.char_input("h"));
         assert!(s.char_input("i"));
 
-        // Resolve; answer every fontstring measure with a stand-in extent (30×12), resolve again
-        // (the round-trip's second solve).
+        // Answer every text measure with a stand-in 30×12, then solve again.
         s.resolve();
         let answers: Vec<(u32, f32, f32, u64)> = s
             .fontstrings_needing_measure()
@@ -1741,8 +1519,6 @@ mod loader_tests {
         s.resolve();
 
         let quads = s.extract();
-        // The header still reads "Say:" — typing lands in the box's own text region, never the
-        // header. Both strings render.
         let header = quads
             .iter()
             .find(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "Say:"))
@@ -1752,8 +1528,7 @@ mod loader_tests {
             .find(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "hi"))
             .expect("the typed text renders in the box's text region");
 
-        // Header rect: its own LEFT+13 anchor + the measured 30×12 extent (left-flush against the
-        // box's left edge at x=100, v-centered on the 100..132 box) — NOT the insets rect.
+        // The header: its own LEFT+13 anchor and the 30×12 extent, centred on the 100..132 box.
         assert_eq!(
             header.rect,
             Some(crate::layout::Rect::new(110.0, 113.0, 122.0, 143.0)),
@@ -1767,11 +1542,7 @@ mod loader_tests {
         );
     }
 
-    /// `<TitleRegion setAllPoints="true"/>` builds the frame's drag handle over its whole rect —
-    /// the stock `TutorialFrame.xml`'s (1976): a press inside it moves the frame with the cursor,
-    /// exactly as `frame:CreateTitleRegion():SetAllPoints()` from Lua does
-    /// (`script::tests::movable::a_title_region_drag_swallows_the_press_and_ends_on_release`);
-    /// the same frame without the element does not move.
+    /// Stock `TutorialFrame.xml:15`; drags like `CreateTitleRegion():SetAllPoints()` from Lua.
     #[test]
     fn title_region_element_builds_the_drag_handle_over_the_frame() {
         let mut s = UiScript::new().unwrap();
@@ -1837,9 +1608,7 @@ mod loader_tests {
         );
     }
 
-    /// `<HitRectInsets>` reaches SetHitRectInsets, and the inset band stops capturing the mouse
-    /// while the frame's own geometry is untouched — the ref micro-button shape (a 29x58 frame whose
-    /// art fills only the lower ~40, `top="18"`).
+    /// The stock micro-button: 29x58, `top="18"` insets (`MainMenuBarMicroButtons.xml:9`).
     #[test]
     fn hit_rect_insets_element_shrinks_the_mouse_rect() {
         let mut s = UiScript::new().unwrap();
@@ -1861,7 +1630,6 @@ mod loader_tests {
             .eval::<(f64, f64, f64, f64)>("return Micro:GetHitRectInsets()")
             .unwrap();
         assert_eq!((l, r, t, b), (0.0, 0.0, 18.0, 0.0));
-        // Geometry untouched: still a 58-tall button.
         assert_eq!(s.eval::<f64>("return Micro:GetHeight()").unwrap(), 58.0);
         // A button is mouse-enabled by construction, so the hit test is live.
         assert!(
@@ -1871,13 +1639,9 @@ mod loader_tests {
         assert!(s.hit_test(14.0, 20.0).is_some(), "the art band still hits");
     }
 
-    /// **The `<Scripts>` walker auto-enables the mouse kind when it attaches a mouse handler**
-    /// (`0x769ef0` → `0x76af00(2,-1)` per handler name; wow-re `ui/scratch/scripts-auto-enable.md`,
-    /// §5 cross-checked) — the reference's GameTimeFrame declares `<OnEnter>`/`<OnLeave>` and no
-    /// `enableMouse`, yet its tooltip hovers in the real client. The kind-2 name set is exactly
-    /// {OnEnter, OnLeave, OnMouseDown, OnMouseUp, OnDragStart}: `OnDragStop`/`OnReceiveDrag` are
-    /// NOT in it, and the law is XML-load-time only — the Lua SetScript binding (`0x7748d0`)
-    /// never auto-enables (verified negative there).
+    /// The `<Scripts>` walker enables the mouse for `OnEnter`, `OnLeave`, `OnMouseDown`,
+    /// `OnMouseUp` and `OnDragStart` (`0x769ef0` calls `0x76af00(2,-1)`), which is how the stock
+    /// `GameTimeFrame` hovers; the Lua `SetScript` (`0x7748d0`) never does.
     #[test]
     fn scripts_block_mouse_handlers_auto_enable_mouse() {
         let s = UiScript::new().unwrap();
@@ -1902,7 +1666,6 @@ mod loader_tests {
                 .unwrap(),
             "OnDragStop is outside the kind-2 name set"
         );
-        // Runtime SetScript never auto-enables — the law is the XML walker's, not SetScript's.
         s.run("rt = CreateFrame('Frame', 'Rt'); rt:SetScript('OnEnter', function() end)")
             .unwrap();
         assert!(
@@ -1911,28 +1674,9 @@ mod loader_tests {
         );
     }
 
-    /// **`<NormalText>` is the Button's label under its second name** — the spelling the reference
-    /// FrameXML never writes and a third-party template reaches for constantly.
-    ///
-    /// `CSimpleButton::LoadXML 0x7788c0` gives this tag strictly more than `<ButtonText>` does: it
-    /// constructs the label `CSimpleFontString` (`0x778b6c call 0x770d30`), clears its
-    /// `ownsFontAttrs` (`0x778b7b`, the one site image-wide that clears it) so its own `LoadXML`
-    /// skips the whole font-attribute surface, and feeds the SAME node to the button's persistent
-    /// Normal-state `CSimpleFont` at `+0x33c` (`0x778ba9`/`0x778baf call 0x783c30`). One owner per
-    /// attribute: the label pass reads the element's name and geometry, the state-font pass reads
-    /// its `inherits=`, and neither reads the other's. (wow-re
-    /// `scratch/fontstring-loadxml-font-attrs.md` §3/§7 and
-    /// `scratch/resize-bounds-and-button-fontstring.md` §5.3 — VERIFIED off the bytes.)
-    ///
-    /// **Why this could sit broken indefinitely.** The reference writes `<ButtonText>` 31 times and
-    /// `<NormalText>` never, so our own FrameXML could not notice the tag was unhandled — and an
-    /// unhandled child element is silent: the button loads, paints, and simply has no label and no
-    /// global. KLHThreatMeter's column-header template is exactly this shape, and the addon died at
-    /// `PLAYER_LOGIN` indexing the `nil` global, six frames deep, naming nothing about XML.
-    ///
-    /// The document is that template, reduced: a virtual `Button` carrying a named `<NormalText>`,
-    /// reached through `inherits=` (never directly), so this covers the template path the addon
-    /// actually takes.
+    /// `CSimpleButton::LoadXML 0x7788c0` builds the label from `<NormalText>` (`0x778b6c`), clears
+    /// its `ownsFontAttrs` (`0x778b7b`) and feeds the node to the Normal-state font (`0x783c30`,
+    /// at `0x778baf`): the label takes the name and geometry, the state font the `inherits=`.
     #[test]
     fn a_button_normal_text_is_the_label_names_it_and_fonts_it() {
         let mut s = UiScript::new().unwrap();
@@ -1964,16 +1708,13 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
 
-        // 1 · THE GLOBAL. `$parent` resolved against the instantiated button and published in `_G`
-        // — this single read is the one KLHThreatMeter died on.
+        // 1 · The global, `$parent` resolved against the instance.
         assert!(
             s.eval::<bool>("return KtmSelfHeaderNameText ~= nil")
                 .unwrap(),
             "a named <NormalText> must publish its global"
         );
-        // 2 · ...and it is the BUTTON'S label, not a loose FontString that merely shares the name.
-        // Naming a region and publishing a global are two different things (the `<ButtonText>` path
-        // learned that the expensive way), so both directions are asserted.
+        // 2 · It is the button's label, not a loose FontString with the same name.
         assert_eq!(
             s.eval::<String>("return KtmSelfHeaderNameText:GetName()")
                 .unwrap(),
@@ -1985,16 +1726,14 @@ mod loader_tests {
             "KtmSelfHeaderNameText",
             "the <NormalText> region must BE the button's label"
         );
-        // 3 · The element's own geometry landed on the label — the label pass's half.
+        // 3 · The element's geometry landed on the label.
         assert_eq!(
             s.eval::<f64>("return KtmSelfHeaderNameText:GetWidth()")
                 .unwrap(),
             70.0
         );
-        // 4 · ...and its `inherits=` landed on the button's NORMAL-STATE font, which is the half a
-        // plain `<ButtonText>` alias would have missed. Read off the painted quad rather than a
-        // getter: the state font is applied at extract, so what is on screen is the only reading
-        // that proves the link is live.
+        // 4 · Its `inherits=` reached the Normal-state font, read off the painted quad because the
+        // state font applies at extract.
         s.resolve();
         let label = s
             .extract()
@@ -2015,41 +1754,11 @@ mod loader_tests {
         );
     }
 
-    /// **The two spellings of a Button's label are two different legs, and only `<NormalText>` is
-    /// disowned of its own font attributes — so its `justifyH` never reaches the label and the
-    /// implicit anchor stays CENTER, while a `<ButtonText>`'s does and still seats LEFT.**
-    ///
-    /// `CSimpleButton::LoadXML 0x7788c0`'s child chain routes them apart (wow-re
-    /// `scratch/button-label-build-and-anchor-order.md`, §5 + arbitration, VERIFIED):
-    /// `<ButtonText>` (tag `0x8799f0`, compared `0x7789c1`) goes to `0x7789d0 call 0x6f2780`, the
-    /// ordinary `<FontString>` region builder the `<Layers>` walker uses, which never writes
-    /// `+0x12c`; `<NormalText>` (tag `0x879978`, `0x778b43`) goes to the inline build
-    /// `[0x778b4c, 0x778bb6)` carrying `0x778b7b mov byte [edi+0x12c],0` — the one site image-wide
-    /// that clears the gate. Cleared, gate B (`0x7710d3 → je 0x771468`) makes the label's own
-    /// `CSimpleFontString::LoadXML 0x770f40` skip `0x7710e1`–`0x771467` wholesale: `font=`,
-    /// `<FontHeight>`, `outline=`, `monochrome=`, the file load, `spacing=`, **`justifyV=`,
-    /// `justifyH=`**, `<Color>` and `<Shadow>`. That node is fed instead to the button's
-    /// Normal-state `CSimpleFont` at `+0x33c` (`0x778ba9`/`0x778baf call 0x783c30`).
-    ///
-    /// So the creation post-step `0x771480` reads the `<NormalText>` label's **untouched ctor
-    /// default** `0x212` = CENTER|MIDDLE (`0x770dd3`) and seats a single CENTER→CENTER anchor
-    /// (point 4, `0x7714dc`/`0x7714e4`). The authored `justifyH="LEFT"` still reaches the *paint*
-    /// and `GetJustifyH()` — `0x783c30`'s tail notify writes the resolved word into the label's own
-    /// `+0x120` (`0x784111` → `0x784180` → `0x773530` → `0x770800` at `0x770876`) — but that runs
-    /// downstream of the anchor, and a FontString pinned at one point is exactly as wide as its
-    /// text, so a left justify inside it has nothing to move.
-    ///
-    /// The live case is Gatherer 1.0.0's minimap quick-menu, transcribed here: every row is a
-    /// `GathererUI_PopupButtonTemplate`, all rows are `SetWidth` to one common width and stacked
-    /// TOP-to-BOTTOM so they share a centreline, and the template's only alignment statement is
-    /// `<NormalText inherits=… justifyH="LEFT"/>`. Applying that word to the label seated all
-    /// seven rows LEFT→LEFT and the menu read as a left-aligned list against the reference's
-    /// centred one.
-    ///
-    /// Two controls, and the second is why this test carries both spellings: an ordinary
-    /// `<Layers>` `<FontString justifyH="LEFT">` still seats LEFT
-    /// (`anchorless_fontstring_seats_at_its_justify_point` above), and so does a
-    /// `<ButtonText justifyH="LEFT"/>` — the gate is the `<NormalText>` leg's alone.
+    /// Only the `<NormalText>` leg clears the label's `+0x12c` gate (`0x778b7b`), so the label's
+    /// `LoadXML 0x770f40` skips its font attributes, `justifyH` among them (`0x7710d3`), and
+    /// `0x771480` seats the ctor's CENTER (`0x212`, `0x770dd3`). `<ButtonText>` goes through the
+    /// ordinary FontString builder (`0x6f2780`) and seats LEFT. The justify still reaches the
+    /// paint and `GetJustifyH()` through the state font (`0x783c30`), after the anchor is set.
     #[test]
     fn a_button_label_element_does_not_own_its_justify() {
         let mut s = UiScript::new().unwrap();
@@ -2088,7 +1797,7 @@ mod loader_tests {
         let report = load(&s, &doc, &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
 
-        // 1 · The anchor — the whole mechanism, read straight off the label.
+        // 1 · The label's anchor.
         let (point, rel_point, x, y) = s
             .eval::<(String, String, f64, f64)>(
                 "local p, rel, rp, x, y = GathererUI_PopupButton1:GetFontString():GetPoint(1) \
@@ -2101,8 +1810,7 @@ mod loader_tests {
             "<NormalText>'s justifyH is disowned, so 0x771480 seats the ctor's CENTER"
         );
 
-        // 2 · ...and the authored word still reaches the label's PAINT and its getter, through the
-        // Normal-state font's link. Only the anchor was ever the reference's answer here.
+        // 2 · The justify still reaches the label's getter through the state font.
         assert_eq!(
             s.eval::<String>("return GathererUI_PopupButton1:GetFontString():GetJustifyH()")
                 .unwrap(),
@@ -2110,9 +1818,7 @@ mod loader_tests {
             "the state font's justify still reaches the label"
         );
 
-        // 3 · The CONTROL, and the half the byte round corrected: `<ButtonText>` is built by the
-        // ordinary FontString builder (`0x6f2780`), which never clears `+0x12c`, so its own
-        // justifyH lands on the label and the same post-step seats it LEFT.
+        // 3 · The control: `<ButtonText>` keeps its justify, so it seats LEFT.
         let (point, rel_point) = s
             .eval::<(String, String)>(
                 "local p, rel, rp = OwnLabelButton:GetFontString():GetPoint(1) return p, rp",
@@ -2124,9 +1830,8 @@ mod loader_tests {
             "<ButtonText> owns its font attributes — the gate is the <NormalText> leg's alone"
         );
 
-        // 4 · The visible consequence, in resolved coordinates. The popup is [0,0]..[120,60] and
-        // the rows are 64 wide, centred on x=60 → [28,92]. A 40-wide label centred in that is
-        // [40,80]; seated LEFT it is [28,68] — the left edge every Gatherer row shared before this.
+        // 4 · Rows 64 wide centred on x=60 span [28,92]: a 40-wide label centred is [40,80],
+        // seated LEFT [28,68].
         s.run(
             "GathererUI_PopupButton1:GetFontString():SetWidth(40) \
              OwnLabelButton:GetFontString():SetWidth(40)",
@@ -2152,17 +1857,13 @@ mod loader_tests {
         );
     }
 
-    /// **`text=` is a GLOBAL-STRING LOOKUP, not a literal** (wow-re rf28 l.36/l.115 →
-    /// `FrameScript_GetText 0x703bf0`). Every arm of [`Loader::resolve_text`] in one document:
-    /// a `<Button text=>`, a `<ButtonText text=>` and a `<FontString text=>` all resolve through
-    /// the VM's globals; a value with no matching global falls back to the LITERAL (benilla's own
-    /// divergence, so its plain-English FrameXML keeps working); and a **key-shaped** miss warns,
-    /// which is the tripwire that "CREATE_MACROS" across a title bar never had.
+    /// `text=` resolves as a global (`FrameScript_GetText 0x703bf0`) on all three element shapes;
+    /// a miss shows the raw value, as the reference's readers do, and a key-shaped miss warns.
     #[test]
     fn a_text_attribute_resolves_through_the_global_strings() {
         let mut s = UiScript::new().unwrap();
         s.set_screen_size(800.0, 600.0);
-        // The reference boots GlobalStrings.lua before any XML; so does the app.
+        // GlobalStrings.lua runs before any XML.
         s.run(r#"DELETE = "Delete" EXIT_GAME = "Exit Game" TITLE = "The Title""#)
             .unwrap();
 
@@ -2198,17 +1899,14 @@ mod loader_tests {
         assert_eq!(
             texts,
             vec![
-                // The key's VALUE, on all three element shapes…
                 "The Title",
-                // …a non-key literal untouched (the divergence that keeps our own XML working)…
                 "No results found.",
                 "Delete",
                 "Exit Game",
-                // …and a key-shaped MISS keeps its key on screen rather than blanking.
                 "NO_SUCH_KEY",
             ]
         );
-        // Exactly one warning, and it names the miss — the plain-English literal must not warn.
+        // Only the key-shaped miss warns.
         assert_eq!(
             report
                 .warnings
@@ -2222,8 +1920,6 @@ mod loader_tests {
         assert!(report.warnings.iter().any(|w| w.contains("NO_SUCH_KEY")));
     }
 
-    /// The key SHAPE test itself: `SCREAMING_SNAKE`, two characters or more. The floor is what
-    /// keeps a close button's `text="X"` from being reported as a missing string.
     #[test]
     fn key_shape_is_screaming_snake_of_two_or_more() {
         for yes in ["DELETE", "EXIT_GAME", "CHARACTER_POINTS1_COLON", "AB", "A1"] {
@@ -2234,15 +1930,11 @@ mod loader_tests {
         }
     }
 
-    // ── <SimpleHTML> (the markup widget's XML element) ───────────────────────────────────────
+    // ── <SimpleHTML> ─────────────────────────────────────────────────────────────────────────
 
-    /// **`<SimpleHTML>`'s `<FontString>` child is a font DECLARATION, not a region** — the shape
-    /// stock `ItemTextFrame.xml` uses, and the whole reason its `<H1>` renders at the `<P>` size.
-    ///
-    /// Four claims in one document: the element materializes as a real `SimpleHTML` frame with its
-    /// `<Size>`/`<Anchors>`/`<Scripts>` applied like any frame; the direct-child `<FontString
-    /// inherits=>` lands on `elementFont[0]` rather than creating a FontString region; a
-    /// `<FontStringHeader1>` lands on `elementFont[1]`; and `hyperlinkFormat=` reaches `+0x360`.
+    /// A direct-child `<FontString>` declares `elementFont[0]` and `<FontStringHeader1>`
+    /// `elementFont[1]`, neither a region, and `hyperlinkFormat=` lands at `+0x360`; stock
+    /// `ItemTextFrame.xml:214` uses the first.
     #[test]
     fn simplehtml_xml_declares_element_fonts_not_regions() {
         let mut s = UiScript::new().unwrap();
@@ -2278,7 +1970,6 @@ mod loader_tests {
                 .unwrap(),
             "|H%s|h[%s]|h"
         );
-        // The two declarations landed on their own elements…
         assert_eq!(
             s.eval::<(String, f32)>("local p, h = PageText:GetFont(); return p, h")
                 .unwrap(),
@@ -2289,8 +1980,7 @@ mod loader_tests {
                 .unwrap(),
             ("Fonts\\SKURRI.TTF".to_string(), 24.0)
         );
-        // …and NEITHER became a region. A `<FontString>` handled by the generic special-fontstring
-        // pass would leave an unanchored, textless string on the frame here.
+        // Neither declaration became a region.
         let regions = {
             let lua = s.lua();
             let model = lua
@@ -2301,7 +1991,7 @@ mod loader_tests {
         };
         assert_eq!(regions, 0, "the font declarations created no regions");
 
-        // Now drive it: three blocks, the H1 in its OWN declared face, at the frame's width.
+        // Two blocks, the H1 in its declared face, at the frame's width.
         s.run(
             r#"PageText:SetText("<HTML><BODY><H1>Title</H1><P align=\"center\">Body</P></BODY></HTML>")"#,
         )
@@ -2338,17 +2028,8 @@ mod loader_tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// A state-texture element with **no `file=`, no `<Color>` and no `name=`** still builds its
-    /// region: `<NormalTexture/>` is the reference's own form on `SpellBookSkillLineTabTemplate`
-    /// (ref SpellBookFrame.xml l.36), and the real client creates from the ELEMENT, not from any
-    /// attribute on it — `Button::LoadXML 0x7788c0` routes all four `<...Texture>` children through
-    /// the same texture adder the `<Layers>` walker uses (`0x6f26f0`), each followed only by the slot
-    /// store, which does no geometry (wow-re `system/ui/scratch/region-implicit-anchor.md` §3).
-    ///
-    /// The report is pfUI's spellbook skin, which takes `SpellBookSkillLineTab<i>:GetNormalTexture()`
-    /// and immediately `:SetTexCoord()`s it; the corpus carries 38 bare `<DisabledTexture />` besides.
-    /// Before this, the loader materialized only on `file=`/`<Color>`/`name=`, so the getter answered
-    /// nil where the real client answers a live blank texture.
+    /// `CSimpleButton::LoadXML 0x7788c0` builds any `<...Texture>` child through the `<Layers>`
+    /// texture adder (`0x6f26f0`); `SpellBookFrame.xml:36` writes a bare `<NormalTexture/>`.
     #[test]
     fn a_bare_state_texture_element_still_builds_its_region() {
         let mut s = UiScript::new().unwrap();
@@ -2376,8 +2057,7 @@ mod loader_tests {
                 .unwrap(),
             "a bare <DisabledTexture /> builds its region"
         );
-        // Created, not painted: the region is live enough to take SetTexCoord (pfUI's next call) and
-        // still carries no art of its own.
+        // Live enough for `SetTexCoord`, with no art of its own.
         s.run("BareBtn:GetNormalTexture():SetTexCoord(0.07, 0.93, 0.07, 0.93)")
             .unwrap();
         assert!(
@@ -2397,9 +2077,6 @@ mod layer_blend_tests {
         None
     }
 
-    /// `alphaMode="ADD"` on a `<Layers>` texture reaches the extracted quad's blend flag — the
-    /// state-texture path always applied it, the layer path silently dropped it (the quest log's
-    /// selection glow rendered as an opaque gray bar — the 0109 look fix).
     #[test]
     fn layers_texture_alpha_mode_add_reaches_the_quad() {
         let s = UiScript::new().unwrap();
@@ -2447,10 +2124,7 @@ mod region_template_tests {
         None
     }
 
-    /// A `<Texture inherits="…">` layer region splices its virtual template — file, `<Size>`,
-    /// `<Anchors>` — with the instance's own nodes winning (the talent branch/arrow art pool's
-    /// shape; before this, the template was silently ignored and every pooled texture sat at
-    /// 0×0 with no file: shown, positioned by the runtime SetPoint, and invisible).
+    /// The instance's own nodes win over the template's.
     #[test]
     fn layers_texture_inherits_a_virtual_texture_template() {
         let s = UiScript::new().unwrap();
@@ -2482,7 +2156,6 @@ mod region_template_tests {
         );
         let mut s = s;
         s.set_screen_size(800.0, 600.0);
-        // The template's size/file landed; the instance's own <Size> wins over the template's.
         assert_eq!(
             s.eval::<(f64, f64)>("return Branch1:GetWidth(), Branch1:GetHeight()")
                 .unwrap(),
@@ -2510,8 +2183,6 @@ mod region_template_tests {
         );
     }
 
-    /// A `<FontString inherits="GameFontNormal">` names a FONT OBJECT, not an element template —
-    /// the region-template gate must pass it through untouched (no "unknown template" warning).
     #[test]
     fn fontstring_font_object_inherits_stays_out_of_the_template_path() {
         let s = UiScript::new().unwrap();
@@ -2538,11 +2209,6 @@ mod region_template_tests {
             report.warnings
         );
         assert_eq!(s.eval::<String>("return Label:GetText()").unwrap(), "hello");
-        // …and the font it inherited is READABLE BACK, which is the half this test did not ask.
-        // `EQL3_Options.lua:1086` is the corpus line that needs it: it reads the tracker line's
-        // font with `t1, _, t2 = EQL3_QuestWatchLine1:GetFont()` and feeds `t1` straight into
-        // `temp:SetFont(t1, height, t2)` — so a nil path there is not a cosmetic gap, it is our own
-        // faithful `Usage: <FontString>:SetFont(...)` raise firing on our own nil.
         assert_eq!(
             s.eval::<(String, f32)>("local f, h = Label:GetFont() return f, h")
                 .unwrap(),
@@ -2551,13 +2217,7 @@ mod region_template_tests {
         );
     }
 
-    /// **A font-object name resolves case-INSENSITIVELY**, because the client's font registry
-    /// compares its keys with `SStrCmpI` (`0x783870`/`0x7838c7`, wow-re
-    /// `font-object-lua-surface.md`: *"Font names are matched case-insensitively"*).
-    ///
-    /// `Recap/RecapOptions.xml:32` inherits `GameFontHighLightSmall`; the shipped font is
-    /// `GameFontHighlightSmall`, one letter's case apart. On the real client that resolves, and it
-    /// used to be a warn-once gap here — a NARROWING fix, like the unit-token fold (1247).
+    /// The reference's font registry compares names with `SStrCmpI` (`0x783870`/`0x7838c7`).
     #[test]
     fn a_font_object_inherits_resolves_whatever_its_case() {
         let s = UiScript::new().unwrap();
@@ -2591,11 +2251,7 @@ mod region_template_tests {
         );
     }
 
-    /// **EQL3's actual shape: FontString -> virtual FontString TEMPLATE -> Font object.** One hop
-    /// works (above); this is the two-hop chain every "define a line template once, stamp it N
-    /// times" addon writes, and `EQL3_Tracker.xml:6/32` is the corpus instance —
-    /// `EQL3_QuestWatch_FontTemplate` inherits `GameFontHighlight`, and each
-    /// `EQL3_QuestWatchLine<i>` inherits the template.
+    /// Two hops: a FontString inherits a virtual FontString template, which inherits a font object.
     #[test]
     fn a_fontstring_template_carries_the_font_object_it_inherits() {
         let s = UiScript::new().unwrap();
@@ -2628,7 +2284,7 @@ mod region_template_tests {
     }
 }
 
-/// Chunk naming — which FILE and which LINE a `<Script>` raise reports (decision 1217).
+/// Chunk naming: the file and line a `<Script>` raise reports.
 mod chunk_name_tests {
     use crate::framexml;
     use crate::loader::*;
@@ -2642,21 +2298,11 @@ mod chunk_name_tests {
         framexml::parse(text).expect("valid FrameXML")
     }
 
-    /// **A raise inside a `<Script>` block names the file it came from, and the file's own line.**
-    ///
-    /// Both halves are load-bearing and both were wrong. `Loader::run` loaded every chunk with no
-    /// name, and mlua's `load` is `#[track_caller]` — so the chunk was named after the *Rust* line
-    /// that ran it, and a corpus read-back of 70 failures had 26 rows saying
-    /// `crates/benilla-ui/src/loader/mod.rs:327` where the addon's file belonged (decision 1217).
-    ///
-    /// Naming it is only half. A Lua chunk starts at line 1, so an inline block 40 lines down a
-    /// file would report `File.xml:3` for its third line — a lie you can go and check, which is
-    /// strictly worse than the Rust path that was at least obviously not yours. The chunk is padded
-    /// to the block's own offset, so the number is the number you scroll to.
+    /// An inline block is padded to its line in the file, so a raise reports the file's line.
     #[test]
     fn a_script_raise_names_its_own_file_and_line() {
         let s = UiScript::new().unwrap();
-        // `error()` with no level prefixes "chunkname:line:" — exactly what a real raise carries.
+        // `error()` with no level prefixes `chunkname:line:`, as a real raise does.
         let doc = parse(
             "<Ui>\n\
              <Frame name=\"Pad\"/>\n\
@@ -2668,24 +2314,18 @@ mod chunk_name_tests {
         );
         let report = load_in(&s, &doc, "Bagnon/src/main.xml", &no_files);
         let err = report.errors.join("\n");
-        // The file, in the shape an addon's own `debugstack()` matches (backslashes, no `@`).
-        // The `:<Scripts>` suffix and the `[string "…"]` wrapper are the reference's own
-        // (`"%s:<Scripts>"` `0x871074`, `luaO_chunkid`'s third branch), not decoration of ours.
+        // Backslashes, and the reference's `"%s:<Scripts>"` form (`0x871074`).
         assert!(
             err.contains("Bagnon\\src\\main.xml:"),
             "the raise must name the document, got: {err}"
         );
-        // Line 5 of the literal above is `error("boom")` — the body starts on line 4 and the
-        // padding carries it there. Without the pad this reads `:2:`.
+        // `error("boom")` is line 5 of the literal; unpadded it would read `:2:`.
         assert!(
             err.contains("main.xml:<Scripts>\"]:5:"),
             "the line must be the FILE's line, not the block's, got: {err}"
         );
     }
 
-    /// The same, one level down: an `<Include>`d document's inline script names **its own** file,
-    /// not the includer's. The path is saved and restored around the recursion exactly as the
-    /// directory used to be, so depth-1 and depth-5 each report themselves.
     #[test]
     fn an_included_documents_script_names_the_included_file() {
         let s = UiScript::new().unwrap();
@@ -2706,11 +2346,8 @@ mod chunk_name_tests {
         );
     }
 
-    /// **The CDATA shape, which is the only shape our own FrameXML uses.** `<![CDATA[` sits
-    /// between the element's start and the body's first byte, so taking the line from the
-    /// *element* would be short by however much of the opening tag precedes it — and a
-    /// single-line-offset lie is the hardest kind to notice. The line comes from the text child's
-    /// own range instead, which is what this pins.
+    /// The line comes from the text child's own range, not the element's, which the `<![CDATA[`
+    /// opener would offset.
     #[test]
     fn a_cdata_script_block_reports_the_files_line() {
         let s = UiScript::new().unwrap();
@@ -2732,7 +2369,6 @@ mod chunk_name_tests {
         );
     }
 
-    /// A `<Script file=>` chunk is named after the file it loaded, not the document that named it.
     #[test]
     fn a_script_file_chunk_is_named_after_that_file() {
         let s = UiScript::new().unwrap();
@@ -2748,17 +2384,8 @@ mod chunk_name_tests {
         );
     }
 
-    /// **A captured script, called back the reference's way, still knows its frame.**
-    ///
-    /// This is *the* 1.12 hook idiom and the whole reason `GetScript` exists: an addon takes the
-    /// client's handler, installs its own, and calls the original with **no arguments**, because
-    /// the reference's contract passes the frame as the `this` global and nothing else. Our
-    /// wrapper is `function(self, ...)` and our own FrameXML is written against `self`, so before
-    /// the fallback in [`super::Loader::compile_handler`] that re-entry handed every body a nil
-    /// frame. The director met it as `bad argument #2: error converting Lua nil to table` out of
-    /// `GameTooltip:SetOwner`, from a handler that works perfectly when the engine calls it.
-    ///
-    /// Both spellings are asserted, because the fallback must not cost the engine's own call.
+    /// The 1.12 hook idiom: an addon captures a handler with `GetScript` and calls it with no
+    /// arguments, the frame passed only as `this`; `Loader::compile_handler` falls back to `this`.
     #[test]
     fn a_script_captured_and_called_with_no_arguments_still_sees_its_frame() {
         let s = UiScript::new().unwrap();
@@ -2774,12 +2401,11 @@ mod chunk_name_tests {
         let report = load_in(&s, &doc, "Test.xml", &no_files);
         assert!(report.errors.is_empty(), "{:?}", report.errors);
 
-        // The engine's own call: `self` is passed and `this` is set — the modern spelling.
+        // The engine's call passes `self` and sets `this`.
         s.run("SEEN = nil Hooked:Show()").unwrap();
         assert_eq!(s.eval::<String>("return SEEN").unwrap(), "Hooked");
 
-        // The addon's: capture the script, then call it back bare with only `this` standing in for
-        // the frame — exactly `Bagnon.lua:87`'s `bMainBag_OnEnter()`.
+        // The addon's: the captured script called bare, with only `this` set.
         s.run(
             "SEEN = nil \
              local original = Hooked:GetScript(\"OnShow\") \
@@ -2796,30 +2422,20 @@ mod chunk_name_tests {
     }
 }
 
-/// [`super::join_ref`] — the FrameXML path rule (decision 1186).
-///
-/// A reference is relative to the directory of the file containing it, `\` and `/` are the same
-/// separator, and `..` walks up. The escape case is the load-bearing one: a `..` above the root is
-/// KEPT as a leading `..` rather than clamped away, because the provider has to be able to SEE the
-/// escape to refuse it. Clamping would silently hand it a path that looks contained.
 #[test]
 fn join_ref_resolves_relative_framexml_paths() {
     use super::join_ref;
-    // Relative to the including file's own directory.
     assert_eq!(
         join_ref("Bagnon/src", "templates.xml"),
         "Bagnon/src/templates.xml"
     );
-    // Backslashes are separators, and `..` walks up — this is how a library addon is reached.
     assert_eq!(
         join_ref("Bagnon/src", "..\\..\\BagBrother\\core\\core.xml"),
         "BagBrother/core/core.xml"
     );
-    // At the root, a bare name stays bare (the builtin's flat tree).
     assert_eq!(join_ref("", "Fonts.xml"), "Fonts.xml");
-    // `.` is a no-op; redundant separators collapse.
     assert_eq!(join_ref("a/b", "./c//d.xml"), "a/b/c/d.xml");
-    // An escape above the root SURVIVES, so the provider can refuse it.
+    // An escape above the root survives, so the provider can refuse it.
     assert_eq!(join_ref("a", "../../secret"), "../secret");
     assert_eq!(join_ref("", "../secret"), "../secret");
     // A leading `/` re-roots rather than meaning the filesystem root.
diff --git a/crates/benilla-ui/src/loader/widgets.rs b/crates/benilla-ui/src/loader/widgets.rs
index 250520a8..34c39519 100644
--- a/crates/benilla-ui/src/loader/widgets.rs
+++ b/crates/benilla-ui/src/loader/widgets.rs
@@ -9,11 +9,8 @@ use super::{
 };
 
 impl Loader<'_> {
-    /// `<StatusBar>` LoadXML extras (RF-28, byte-verified table `0x782ef0`): `minValue`/`maxValue`
-    /// (a reversed pair is swapped — SetMinMaxValues normalizes identically), `defaultValue` →
-    /// SetValue, `orientation`, and the `<BarTexture>`/`<BarColor>` children; the element's
-    /// `drawLayer` names the bar texture's layer (widget default ARTWORK). The Slider's parallel
-    /// `<ThumbTexture>` path lives in [`Self::apply_slider`].
+    /// `<StatusBar>` (`0x782ef0`): a reversed `minValue`/`maxValue` pair is swapped, as
+    /// `SetMinMaxValues` also does; `drawLayer` is the bar texture's layer, ARTWORK by default.
     pub(super) fn apply_statusbar(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if !el.tag.eq_ignore_ascii_case("StatusBar") {
             return;
@@ -41,12 +38,9 @@ impl Loader<'_> {
                     (file.to_string(), layer.clone()),
                     dbg,
                 );
-                // File + `<Color>` DISCARDS the colour, it does not tint — the same
-                // `CSimpleTexture::LoadXML` ordering `regions.rs`'s `<Texture>` arm cites
-                // (`0x76fe20`: the child loop runs first, then `file=` overwrites the same `+0xcc`).
-                // `<BarColor>` below is this widget's real tint.
+                // A `<Color>` beside `file=` is discarded, as on any texture (`0x76fe20`);
+                // `<BarColor>` is the bar's tint.
             } else if let Some(c) = color {
-                // No file: a solid-color bar (the SetStatusBarTexture(r,g,b,a) form).
                 self.call(
                     wrapper,
                     "SetStatusBarTexture",
@@ -64,15 +58,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<Button>`/`<CheckButton>` extras (RF-28 `0x7788c0`/`0x785170` — the checkbox loader runs
-    /// the button one first, which this shared body mirrors): the four state textures, CheckButton's
-    /// two checked textures + `checked` attr, `<ButtonText text=>`, and the `text` attribute. Each
-    /// texture child takes a `file` or a `<Color>` (the same two forms as the Set*Texture methods)
-    /// plus the generic region layout — `<Size>`/`<Anchors>`/`setAllPoints` — so a state texture can
-    /// cover less than its button (the merchant row's icon-scoped highlight); `$parent` in a state
-    /// texture's anchors resolves against this button's own name, like a `<Layers>` region's.
-    /// The per-state fonts (`<NormalFont>` and kin) are modeled below — object and local justify
-    /// (decision 1996); not modeled (stated): `<PushedTextOffset>`.
+    /// `<Button>`, `<CheckButton>` and `<LootButton>` (`0x7788c0`, which `0x785170` runs first):
+    /// the label, the state textures with their own layout, `checked`, `text=` and the per-state
+    /// fonts. `$parent` in a child's anchors is this button.
     pub(super) fn apply_button(
         &mut self,
         el: &Element,
@@ -81,19 +69,8 @@ impl Loader<'_> {
         dbg: &str,
     ) {
         let is_check = el.tag.eq_ignore_ascii_case("CheckButton");
-        // **`<LootButton>` takes this leg too, and taking only two tags is what hid the loot
-        // window's hover highlight.** `CLootButton` is a `CSimpleButton` subclass that overrides
-        // six vtable slots on the primary table (dtor, the Lua lookup, the two type predicates,
-        // `GetObjectType`, and the click virtual) and exactly ONE on the geometry table — slot 1,
-        // the destructor's adjustor thunk. `LoadXML` is geometry slot 2 (`0x81c7c8[2]` for Button,
-        // `0x804594[2]` for LootButton), and those two entries are the same pointer: a
-        // `<LootButton>` element is parsed by `CSimpleButton::LoadXML 0x7788c0` *verbatim* (wow-re
-        // `ui/scratch/lootbutton-widget-type.md` §4 + `button-disabled-state-texture-law.md`).
-        // Stock `LootButtonTemplate` inherits `ItemButtonTemplate`, whose whole art is three state
-        // textures — so with the tag rejected here the rows lost their Quickslot border, their
-        // depress art and the `ButtonHilight-Square` that lights a row under the cursor. It is the
-        // BUTTON leg and not the check one: `CheckButton::LoadXML 0x785170` is a different slot 2
-        // that calls this one first, and nothing routes a LootButton through it.
+        // A `<LootButton>` loads exactly as a Button: its `LoadXML` slot holds `CSimpleButton`'s
+        // pointer (`0x804594[2]` = `0x81c7c8[2]`).
         if !is_check
             && !el.tag.eq_ignore_ascii_case("Button")
             && !el.tag.eq_ignore_ascii_case("LootButton")
@@ -102,12 +79,8 @@ impl Loader<'_> {
         }
         let tex = |tag: &str, method: &str, this: &mut Self| {
             for raw in children_named(el, tag) {
-                // A state texture may `inherits=` a virtual `<Texture>` — `<NormalTexture
-                // inherits="UIPanelButtonUpTexture"/>` is how the reference's whole shared button
-                // kit carries its art, and it is the ONLY form those templates use. Expanding here
-                // is the same call a `<Layers>` region gets (`expand_region`, which passes a
-                // non-template `inherits=` through untouched), and without it the reads below found
-                // no `file=`, no `<TexCoords>` and no `<Size>`: a button with no art and NO ERROR.
+                // A state texture may inherit a virtual `<Texture>`, the stock button kit's only
+                // form (`UIPanelButtonUpTexture`); it expands like a `<Layers>` region.
                 let expanded = this.expand_region(raw);
                 let t = &expanded;
                 if let Some(file) = t.attr("file") {
@@ -115,44 +88,19 @@ impl Loader<'_> {
                 } else if let Some(c) = children_named(t, "Color").next().map(color_of) {
                     this.call(wrapper, method, (c[0], c[1], c[2], c[3]), dbg);
                 } else {
-                    // A state texture with no art of its own — a NAMED one (`<NormalTexture
-                    // name="$parentIcon">` on the ref's own MacroFrameButtonTemplate, whose art
-                    // arrives later through `SetTexture`) or a BARE one (`<NormalTexture/>`, the
-                    // ref's own SpellBookSkillLineTabTemplate l.36). **The ELEMENT is what creates
-                    // the region; `file=` is not a gate.** wow-re `system/ui/ui.md` + `scratch/
-                    // region-implicit-anchor.md` §3: `Button::LoadXML 0x7788c0` routes all four
-                    // `<...Texture>` children through the SAME texture adder the `<Layers>` walker
-                    // uses (`0x6f26f0` — `0x778903` <NormalTexture> tag `0x879a30`, `0x778935`
-                    // <PushedTexture>, `0x778967` <DisabledTexture>, `0x778999` <HighlightTexture>),
-                    // "each followed only by the slot store (`0x778fd0` state-texture family /
-                    // `0x779110` highlight install), which does no geometry". The adder constructs;
-                    // nothing in that path reads an attribute first.
-                    //
-                    // This arm used to require `t.name().is_some()`, so a bare element built
-                    // nothing and `GetNormalTexture()` answered nil where the real client answers a
-                    // live blank texture. pfUI's spellbook skin is the report — it takes
-                    // `SpellBookSkillLineTab<i>:GetNormalTexture()` and immediately
-                    // `:SetTexCoord()`s it — and the corpus carries 38 more bare
-                    // `<DisabledTexture />` besides.
-                    //
-                    // `""` is the live API's own blank form (`set_slot_texture`'s empty-string arm,
-                    // which runs `ensure_slot` and then clears), so this creates without painting.
+                    // No art: the element alone creates the region, as the reference sends all four
+                    // state textures through the `<Layers>` texture adder (`0x6f26f0`, from
+                    // `0x778903`); `""` creates the slot without painting it.
                     this.call(wrapper, method, String::new(), dbg);
                 }
-                // alphaMode / <Size> / <Anchors> / <TexCoords> apply to the region the setter just
-                // created — fetch it back through the matching getter and use the region methods.
                 let getter = method.replacen("Set", "Get", 1);
                 if let Ok(region) = wrapper.call_method::<Table>(getter.as_str(), ()) {
                     if let Some(mode) = t.attr("alphaMode") {
                         this.call_region(&region, "SetBlendMode", mode.to_string(), dbg);
                     }
-                    // The setter above MATERIALIZED the region with the runtime path's implicit
-                    // SetAllPoints (decision 1310) — but this is the XML path, where the real
-                    // engine routes state textures through the region adder (`0x778903`…: authored
-                    // `<Anchors>` first, the implicit step after). Reproduce that order: clear,
-                    // apply the authored layout, then re-run the conditional step — a same-point
-                    // SetPoint over a live implicit corner would otherwise leave the OTHER corner
-                    // standing (the slot law) and weld an anchored state texture to the button.
+                    // The setter gave the region the runtime path's implicit anchors, but the XML
+                    // path places the authored ones first and the implicit step after (`0x778903`):
+                    // clear, lay out, then re-run it, or a leftover implicit corner would pin it.
                     this.call_region(&region, "ClearAllPoints", (), dbg);
                     this.apply_region_layout(t, &region, self_name, dbg, FontAttrs::Own);
                     if let Err(e) = crate::script::implicit_creation_anchor_lua(this.lua, &region) {
@@ -163,16 +111,10 @@ impl Loader<'_> {
                     if let Some(tc) = tex_coords_of(t) {
                         this.call_region(&region, "SetTexCoord", tc, dbg);
                     }
-                    // Publish a NAMED state texture (`<HighlightTexture
-                    // name="$parentHighlightTexture">`) — the ref kit addresses these by global
-                    // (the tab template's own OnShow does `getglobal(name.."HighlightTexture")`),
-                    // exactly like a named `<Layers>` region or the ButtonText.
+                    // A named state texture is published both ways: the region registry for its
+                    // `GetName()`, `_G` for `getglobal` and a sibling's `relativeTo`.
                     if let Some(rname) = t.name().map(|raw| framexml::resolve_name(raw, self_name))
                     {
-                        // …and into the region-name registry, which is what a sibling's
-                        // `relativeTo` resolves through — the stock trainer row hangs its label
-                        // off `$parentHighlight`'s RIGHT, and a name that lives only in `_G`
-                        // sent that label to the button's edge instead (1957).
                         crate::script::region::publish_region_name(this.lua(), &rname, &region);
                         if let Err(e) = this.lua().globals().set(rname.clone(), region) {
                             this.report
@@ -183,71 +125,24 @@ impl Loader<'_> {
                 }
             }
         };
-        // The LABEL is published before the state textures, and the order is load-bearing: a
-        // state texture may anchor to `$parentText` (the reference's own sort-header template
-        // hangs its arrow off the label's RIGHT), and this loader resolves `relativeTo` eagerly by
-        // name at SetPoint time. Applied the other way round, every such anchor missed and fell
-        // back to the owner — 14 of them in one window, each a sort arrow sitting in the wrong
-        // place. The real client is order-free here because it resolves anchors later; we are not,
-        // so we order it ourselves rather than making each author work around it.
-        // **Both spellings of the label** (`ButtonText` | `NormalText`), in document order.
-        //
-        // `<NormalText>` is not a synonym bolted on here — it is the binary's own second name for
-        // this slot, and **it is a genuinely different leg** (wow-re
-        // `scratch/button-label-build-and-anchor-order.md`, §5 + arbitration, VERIFIED; it
-        // corrected the earlier reading this comment used to carry). `CSimpleButton::LoadXML
-        // 0x7788c0`'s 15-comparison child chain routes the two label spellings apart:
-        //
-        // - `<ButtonText>` (tag `0x8799f0`, compared `0x7789c1`) → `0x7789d0 call 0x6f2780`, the
-        //   **ordinary `<FontString>` region builder** — whose only other caller is the `<Layers>`
-        //   walker (`0x769e61`). It never writes `+0x12c`, so the ctor's `1` stands, both gates in
-        //   `0x770f40` stay open, and the element's `justifyH`/`justifyV` (and `inherits=`,
-        //   `font=`, `<Color>`, `<Shadow>`) apply to the LABEL, exactly like any other FontString.
-        // - `<NormalText>` (tag `0x879978`, compared `0x778b43`) → the inline build
-        //   `[0x778b4c, 0x778bb6)`, a hand-rolled copy of that builder carrying
-        //   `0x778b7b mov byte [edi+0x12c],0` — the ONE site image-wide that clears the gate. Its
-        //   font attributes are skipped on the label and fed to the button's persistent
-        //   Normal-state `CSimpleFont` at `+0x33c` (`0x778ba9`/`0x778baf call 0x783c30`) instead.
-        // - `<HighlightText>`/`<DisabledText>` build no region at all: pure aliases for the
-        //   Highlight/Disabled fonts (`0x778bf4`), which is why they are not in this loop.
-        //
-        // So both spellings make the label and take its geometry and name, and only `<NormalText>`
-        // hands its font attributes away — [`FontAttrs`] below is that one difference.
-        //
-        // The reference FrameXML writes only `<ButtonText>` (31 sites, 16 of them
-        // `name="$parentText"`) and never `<NormalText>`, so nothing we ship could notice the
-        // second spelling was missing. A third-party template is where it shows: KLHThreatMeter's
-        // `<Button name="KLHTM_SelfHeaderStringTemplate" virtual="true"><NormalText
-        // name="$parentText" …>` left `KLHTM_SelfFrameHeaderNameText` nil, and the addon died in
-        // its `PLAYER_LOGIN` handler on exactly that global.
+        // Both label spellings build the label, in document order: `<ButtonText>` through the
+        // ordinary FontString builder (`0x7789d0` → `0x6f2780`), `<NormalText>` through an inline
+        // copy that disowns its font attributes (`0x778b7b`). `<HighlightText>` and
+        // `<DisabledText>` build no region, only fonts (`0x778bf4`).
         for bt in children_named_any(el, &["ButtonText", "NormalText"]) {
-            // Which leg built this label decides who owns its font attributes — see the chain
-            // above. `<ButtonText>` goes through the ordinary FontString builder and keeps them;
-            // `<NormalText>` is the one the button disowns (`0x778b7b`).
             let font_attrs = if bt.tag.eq_ignore_ascii_case("NormalText") {
                 FontAttrs::Disowned
             } else {
                 FontAttrs::Own
             };
-            // Create the label slot even with no text yet (the geometry below must land on a real
-            // region; SetText is the slot's lazy constructor), then apply the element's own
-            // `<Size>`/`<Anchors>` to it — the ref anchors ButtonText all over (the quest
-            // greeting rows hang theirs at TOPLEFT+20 beside the bullet; without this every
-            // labelled Button centered its text over the whole face).
-            // `<ButtonText text=>` is a FontString's own attribute — the same global-string lookup
-            // rf28 l.115 gives every `<FontString text=>`. See `Loader::resolve_text`.
+            // `SetText` creates the label even with no text, so its layout lands on a real region;
+            // `text=` is a global-string key (`0x703bf0`).
             let label = match bt.attr("text") {
                 Some(raw) => self.resolve_text(raw, dbg),
                 None => String::new(),
             };
-            // A NAMED `<ButtonText name="$parentText">` is created as a named region and bound,
-            // rather than left to `SetText`'s lazy constructor and aliased afterwards.
-            //
-            // Publishing a Lua global is not the same thing as naming the region, and the gap was
-            // invisible until something anchored to it: `relativeTo="$parentText"` resolves through
-            // the engine's own named-region lookup, which a global alias never reaches, so every
-            // such anchor missed and fell back to the owner. `GetFontString():GetName()` also
-            // answered nil, which is wrong for any addon that asks.
+            // A named label is created as a named region, not aliased after `SetText`, so its
+            // `GetName()` answers.
             let bt_name = bt.name().map(|raw| framexml::resolve_name(raw, self_name));
             if let Some(rname) = bt_name.clone() {
                 match wrapper
@@ -262,30 +157,10 @@ impl Loader<'_> {
             }
             self.call(wrapper, "SetText", label, dbg);
             if let Ok(region) = wrapper.call_method::<Table>("GetFontString", ()) {
-                // Same clear→layout→implicit order as the state textures above (decision 1310):
-                // SetText materialized the label with the runtime path's implicit anchor; the XML
-                // path re-derives it AFTER the element's own `<Anchors>` apply, which is where
-                // both real legs run it (`0x6f27f5` for `<ButtonText>`, `0x778b96` for
-                // `<NormalText>` — two of that post-step's three call sites).
-                //
-                // **`font_attrs` is the load-bearing argument here** (decision 2100). On the
-                // `<NormalText>` leg the element's `justifyH`/`justifyV` belong to the button's
-                // per-state font, never to the label, so the post-step reads the string's
-                // untouched ctor word (`0x212` = CENTER|MIDDLE) and seats CENTER. Applying the
-                // word to the label instead seated Gatherer's whole quick-menu LEFT→LEFT against
-                // the reference's centred rows: its `GathererUI_PopupButtonTemplate` states its
-                // alignment once, as `<NormalText inherits="GameFontNormal" justifyH="LEFT"/>`,
-                // and every row is `SetWidth` to one common width, so a left-seated label puts all
-                // seven texts on one left edge. The word still reaches the *paint* and
-                // `GetJustifyH()` — `0x783c30`'s tail notify writes the resolved justify into the
-                // label's own `+0x120` (`0x784111` → `0x784180` → `0x773530` → `0x770800` at
-                // `0x770876`), downstream of the anchor — which is why the visible difference is
-                // the anchor alone.
-                //
-                // The adopter's own conditional anchor (`0x778d20`, `[button+0x390]` — decision
-                // 1996) is **structurally dead on both XML label paths**: the builder anchors
-                // first, and the 9-slot scan at `0x778d5f` then finds a slot filled. It is live
-                // only where the label is born from `text=` or Lua `SetText`.
+                // Clear, lay out, then the implicit step, as both reference legs do (`0x6f27f5`,
+                // `0x778b96`); the button's own adopter anchor never fires on them (`0x778d5f`).
+                // On `<NormalText>` the justify is the Normal font's, so the implicit anchor reads
+                // the ctor's CENTER (`0x212`); the justify still reaches the paint (`0x784111`).
                 self.call_region(&region, "ClearAllPoints", (), dbg);
                 self.apply_region_layout(bt, &region, self_name, dbg, font_attrs);
                 if let Err(e) = crate::script::implicit_creation_anchor_lua(self.lua, &region) {
@@ -293,11 +168,8 @@ impl Loader<'_> {
                         .errors
                         .push(format!("{dbg}: implicit anchor: {e}"));
                 }
-                // Publish the label under its resolved name (`<ButtonText name="$parentText">`) —
-                // the ref kit addresses tab/button labels by exactly this global
-                // (PanelTemplates_TabResize's `getglobal(tabName.."Text")`).
+                // Published both ways, like a named state texture.
                 if let Some(rname) = bt_name {
-                    // The registry too, for the same reason as the state textures below (1957).
                     crate::script::region::publish_region_name(self.lua(), &rname, &region);
                     if let Err(e) = self.lua().globals().set(rname.clone(), region) {
                         self.report
@@ -320,14 +192,11 @@ impl Loader<'_> {
             }
         }
         if let Some(text) = el.attr("text") {
-            // `<Button text=>` → the ButtonText fontstring, global-string resolved (rf28 l.36,
-            // `0x703bf0`). This is what makes the reference's `text="DELETE"` read "Delete".
+            // A global-string key (`0x703bf0`): `text="DELETE"` reads "Delete".
             let text = self.resolve_text(text, dbg);
             self.call(wrapper, "SetText", text, dbg);
         }
-        // The per-state label fonts (`<NormalFont inherits=>` etc. — UIPanelButtonTemplate's
-        // gold/white/gray label trio) → the 1.12 setter trio; every occurrence applies in
-        // document order (same last-wins rule as `apply_size`).
+        // The per-state fonts, two spellings each; every occurrence applies, in document order.
         for (children, method, which) in [
             (
                 ["NormalFont", "NormalText"],
@@ -346,36 +215,15 @@ impl Loader<'_> {
             ),
         ] {
             for f in children_named_any(el, &children) {
-                // These three are `<Font>`-TYPED elements — `CSimpleButton::LoadXML 0x7788c0`
-                // routes them at `0x778bf4` into the SAME `0x783c30` a top-level `<Font>` uses — so
-                // they take `inherits=` and `font=` alike, and `font=` wins: both land in one slot
-                // and `0x770c60` unlinks the previous parent (wow-re
-                // `fontstring-loadxml-font-attrs.md` C5; `font=`'s registry-first path is
-                // `0x783d15` → `0x783d22 call 0x770c60` → `0x783d27 jmp 0x783ee0`).
-                //
-                // Reading only `inherits=` here left every corpus button that writes `font=` on its
-                // own default font — Bagnon writes it at seven sites, which is why its character
-                // list's names and its "Show Bags" label were not the Large/normal faces they ask
-                // for. Real FrameXML always writes `inherits=`, so nothing we ship noticed.
-                //
-                // `style=` is deliberately NOT read: it does not exist in 1.12.1. An isolated-token
-                // scan for it returns zero against nine controls that each return one — it is a
-                // later-client idiom, and the reference writes `<NormalFont inherits="GameFontNormal"/>`
-                // (`UIPanelTemplates.xml:20-22`).
+                // `<Font>`-typed elements (`0x778bf4` → `0x783c30`): `inherits=` and `font=` land
+                // in one slot and `font=` wins (`0x783d22`). `style=` is not 1.12 and is not read.
                 for attr in ["inherits", "font"] {
                     if let Some(name) = f.attr(attr) {
                         self.call(wrapper, method, name.to_string(), dbg);
                     }
                 }
-                // An element-level justify (`<NormalFont inherits="QuestFont" justifyH="LEFT"/>`)
-                // is a LOCAL write on that state's embedded font — the same `0x783c30` the
-                // `inherits=` above goes through, on `+0x33c`/`+0x3b8`/`+0x434` — never on the
-                // label. It is what the adopter reads to ANCHOR a label the button later makes
-                // for itself (`UIMenuButtonTemplate`'s rows: Lua `SetText` → `0x778d20` →
-                // `[button+0x390]`), and it reaches an existing label only through the live
-                // link. The v1 form wrote it onto the label directly, which forced a label into
-                // being here with a CENTER anchor already decided — the chat menu's rows drew
-                // centred and "Macro" ran into "/macro" (decision 1996).
+                // A `justifyH` here is a local write on that state's font, never the label
+                // (`0x783c30`); the button reads it to anchor a label it makes later (`0x778d20`).
                 if let Some(j) = f.attr("justifyH") {
                     match crate::justify::parse_h(j) {
                         crate::justify::Set::To(jh) => {
@@ -387,9 +235,8 @@ impl Loader<'_> {
                                     .push(format!("{dbg}: <{}> justifyH: {e}", f.tag));
                             }
                         }
-                        // The reference's parser clears the axis on a cross-axis token and
-                        // raises on a non-token; no 1.12 FrameXML writes either on these
-                        // elements, so both are reported rather than modelled.
+                        // Reported, not modelled: the reference clears the axis on a cross-axis
+                        // token and raises on a non-token.
                         _ => self.report.warnings.push(format!(
                             "{dbg}: <{}> justifyH=\"{j}\" is not a horizontal token — ignored",
                             f.tag
@@ -400,26 +247,10 @@ impl Loader<'_> {
         }
     }
 
-    /// `<EditBox>` extras (RF-0082 §"THE STRUCTURAL KEY"/§3): the `letters` cap → SetMaxLetters,
-    /// `historyLines` → SetHistoryLines (the submitted-line recall ring), and the config flags
-    /// `autoFocus`/`numeric`/`password`/`multiLine`/`ignoreArrows` → their setters.
-    /// A flag absent from the XML stays at its ctor default, and the ctor's own value is
-    /// `flags = 1` — **`autoFocus` defaults ON**, every other flag off (`0x779a29 mov eax,1` /
-    /// `0x779a2e mov [esi+0x318],eax`; LoadXML's `autoFocus` leg writes nothing for an absent or
-    /// empty attribute, `0x77a0b3`/`0x77a0b8`). So the UI.xsd's `true` default is the client's too,
-    /// and the divergence documented here — benilla applying `flags = 0` uniformly — is retired
-    /// (decision 1686). Its stated justification, "autoFocus never focuses on show", was wow-re's
-    /// own `call`-only-census error, corrected 2026-08-29.
-    ///
-    /// **The flags are read presence-aware.** This loop used to call the setter only when an
-    /// attribute parsed as `true`, so `autoFocus="false"` was a no-op — harmless while the default
-    /// was off, and precisely backwards once it is on: the ten boxes in the shipped chain that opt
-    /// OUT (MailFrame ×3, MoneyInputFrame ×3, FriendsFrame ×3, AddonList ×1) are the only places
-    /// the attribute appears at all.
-    /// `<TextInsets>` maps to `SetTextInsets`; `blinkSpeed` → SetBlinkSpeed (the caret
-    /// half-period, `E+0x370`). A declared `<FontString>` is ASSIGNED as the box's text region by
-    /// the special-fontstring pass (`adopt_text_region` — the engine's LoadXML slot, never a
-    /// search).
+    /// `<EditBox>` (`0x779fb0`). An absent flag keeps the ctor's, where `autoFocus` is on and the
+    /// rest off (`0x779a29`, `0x77a0b3`), so flags are read presence-aware: `autoFocus="false"`
+    /// clears. The reference also skips an empty `autoFocus` (`0x77a0b8`), which clears here.
+    /// `blinkSpeed` is the caret half-period (`E+0x370`).
     pub(super) fn apply_editbox(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if !el.tag.eq_ignore_ascii_case("EditBox") {
             return;
@@ -442,9 +273,6 @@ impl Loader<'_> {
         {
             self.call(wrapper, "SetBlinkSpeed", s, dbg);
         }
-        // <TextInsets><AbsInset left= right= top= bottom=/></TextInsets> → SetTextInsets(l,r,t,b)
-        // (the ref chat box drives these from ChatEdit_UpdateHeader at runtime; the XML form seeds
-        // the static case).
         if let Some(ins) = children_named(el, "TextInsets").next() {
             let src = children_named(ins, "AbsInset").next().unwrap_or(ins);
             let get = |k: &str| {
@@ -460,8 +288,7 @@ impl Loader<'_> {
             ("numeric", "SetNumeric"),
             ("password", "SetPassword"),
             ("multiLine", "SetMultiLine"),
-            // The XML spelling of the alt-arrow flag; the Lua spelling is `SetAltArrowKeyMode`,
-            // and there is one flag behind both (wow-re `ignorearrows-alt-arrow-gate.md`).
+            // One flag behind both spellings (`0x77a6b0`, `0x7996e0`, bit 0x10).
             ("ignoreArrows", "SetAltArrowKeyMode"),
         ] {
             if let Some(on) = el.attr_bool_opt(attr) {
@@ -470,29 +297,8 @@ impl Loader<'_> {
         }
     }
 
-    /// The two message-frame classes' LoadXML extras — **`0x787b20` and `0x785910`, two separate
-    /// tables** (msgframe-runtime.md's XML-attribute section), which is why the shared attrs are
-    /// applied for either tag and the two divergent ones are gated on the tag that has them:
-    ///
-    /// - both: `displayDuration`/`fadeDuration` (float, applied **iff `> 0`** — the client's own
-    ///   gate) → SetTimeVisible/SetFadeDuration, and the `fade` bool → SetFading.
-    /// - `<ScrollingMessageFrame>` only: `maxLines` (int, `> 0`, destructive `SetMaxLines`).
-    /// - `<MessageFrame>` only: `insertMode` → SetInsertMode. The scrolling class has no such
-    ///   attribute and no such binding.
-    ///
-    /// A missing attr keeps the ctor default (fading on, 10s/3s; 8 lines / insertMode BOTTOM). The
-    /// `<FontString>` child renders through the generic `<Layers>` path; its resolved font **and its
-    /// `justifyH`** are what the frame's lines bake, stack and align at (read at extract,
-    /// `crate::script::UiScript::extract`) — that child is how `UIErrorsFrame.xml` centres its
-    /// toasts and how a chat frame keeps its lines flush left.
-    /// `<Minimap>`'s LoadXML extras (`CMinimap::LoadXML 0x4ee2b0`): the two model-file attributes,
-    /// which name the nine `Model` children the arena's ctor already built
-    /// (`crate::widget::MINIMAP_ENGINE_CHILDREN`). Both have engine defaults, so an attribute-less
-    /// `<Minimap>` still gets the stock arrows — the reference reads the default string when the
-    /// attribute is absent rather than leaving the children file-less.
-    ///
-    /// Gated on the element's own tag like every other step here, so a plain `<Frame>` wearing a
-    /// Minimap template simply skips it.
+    /// `<Minimap>` (`0x4ee2b0`): the two model files for the ctor's nine `Model` children, each
+    /// the stock model when the attribute is absent, as the reference reads a default string.
     pub(super) fn apply_minimap(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if !el.tag.eq_ignore_ascii_case("Minimap") {
             return;
@@ -513,6 +319,10 @@ impl Loader<'_> {
         }
     }
 
+    /// `<ScrollingMessageFrame>` and `<MessageFrame>`, two loaders (`0x787b20`, `0x785910`): both
+    /// take `displayDuration` and `fadeDuration` (only when > 0) and `fade`; only the scrolling one
+    /// has `maxLines` (> 0), only the plain one `insertMode`. The line font and its `justifyH` come
+    /// from the direct-child `<FontString>`.
     pub(super) fn apply_messageframe(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         let scrolling = el.tag.eq_ignore_ascii_case("ScrollingMessageFrame");
         let plain = el.tag.eq_ignore_ascii_case("MessageFrame");
@@ -556,15 +366,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<Slider>` LoadXML extras (RF-28, byte-verified table `0x789580`): `orientation` →
-    /// SetOrientation (the ctor default is VERTICAL — decision 0250 — so an omitted attr leaves a
-    /// vertical scrollbar); `minValue`/`maxValue` → SetMinMaxValues, with `valueStep` → SetValueStep
-    /// and `defaultValue` → SetValue — the latter three **gated on BOTH minValue AND maxValue
-    /// present** (RF-28). Unlike StatusBar, a reversed `min > max` pair is NOT swapped. The
-    /// `<ThumbTexture>` child → SetThumbTexture (file or `<Color>`) plus the generic region layout
-    /// (`<Size>`/`<Anchors>`/`<TexCoords>`/alphaMode); the element's `drawLayer` names the thumb's
-    /// layer (widget default OVERLAY). The scrollbar template declares only the thumb + orientation;
-    /// its range/value are set at runtime by `FauxScrollFrame_Update`.
+    /// `<Slider>` (`0x789580`), VERTICAL from the ctor: the range, `valueStep` and `defaultValue`
+    /// apply only when both bounds are present, and a reversed pair is not swapped; `drawLayer` is
+    /// the thumb's layer, OVERLAY by default.
     pub(super) fn apply_slider(
         &mut self,
         el: &Element,
@@ -590,11 +394,8 @@ impl Loader<'_> {
         }
         let layer = el.attr("drawLayer").map(str::to_string);
         for raw in children_named(el, "ThumbTexture") {
-            // Same two rules as a Button's state textures, for the same reasons: `inherits=` on a
-            // virtual `<Texture>` is expanded here (see `apply_button`), and a NAMED thumb is
-            // published as a global — `UIPanelScrollBarTemplate`'s own
-            // `ScrollFrame_OnScrollRangeChanged` reaches it with
-            // `getglobal(bar:GetName().."ThumbTexture")`.
+            // As for a Button's state textures: `inherits=` expands, and a named thumb is
+            // published (`ScrollFrame_OnScrollRangeChanged` reads it by name).
             let expanded = self.expand_region(raw);
             let tt = &expanded;
             if let Some(file) = tt.attr("file") {
@@ -607,9 +408,6 @@ impl Loader<'_> {
             } else if let Some(c) = children_named(tt, "Color").next().map(color_of) {
                 self.call(wrapper, "SetThumbTexture", (c[0], c[1], c[2], c[3]), dbg);
             }
-            // alphaMode / <Size> / <Anchors> / <TexCoords> apply to the thumb region the setter just
-            // created — fetch it back through the getter and use the region methods (same shape as a
-            // Button's state textures).
             if let Ok(region) = wrapper.call_method::<Table>("GetThumbTexture", ()) {
                 if let Some(mode) = tt.attr("alphaMode") {
                     self.call_region(&region, "SetBlendMode", mode.to_string(), dbg);
@@ -630,16 +428,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<ColorSelect>`'s four texture sub-elements (RF-28 loader hooks `0x78b580`, `0x78b850`,
-    /// `0x78b8a0`, `0x78ba90`) — the hue wheel, the brightness strip, and a marker for each.
-    /// Structurally `apply_slider`'s `<ThumbTexture>` loop, four times over.
-    ///
-    /// The one thing that is NOT like a thumb: **two of the four carry no `file=`, and that is not
-    /// an omission.** The client generates the wheel and the strip; there is no BLP in the chain
-    /// that is a colour wheel. So the setter is still called — with nothing — because the *region*
-    /// must exist regardless: it is what layout resolves, what the press handler hit-tests, and
-    /// what the app renderer paints into. An element that skipped the setter would leave the picker
-    /// with no wheel to click.
+    /// `<ColorSelect>`'s four textures (`0x78b580`, `0x78b850`, `0x78b8a0`, `0x78ba90`): the hue
+    /// wheel, the value strip and a thumb for each. The client generates the wheel and the strip,
+    /// so a file-less element still creates its region, for layout, hit tests and paint.
     pub(super) fn apply_colorselect(
         &mut self,
         el: &Element,
@@ -681,7 +472,6 @@ impl Loader<'_> {
                 } else if let Some(c) = children_named(tt, "Color").next().map(color_of) {
                     self.call(wrapper, setter, (c[0], c[1], c[2], c[3]), dbg);
                 } else {
-                    // The file-less form — create the region and leave it for the renderer.
                     self.call(wrapper, setter, (), dbg);
                 }
                 if let Ok(region) = wrapper.call_method::<Table>(getter, ()) {
@@ -694,9 +484,8 @@ impl Loader<'_> {
                     }
                     if let Some(rname) = tt.name().map(|raw| framexml::resolve_name(raw, self_name))
                     {
-                        // Into the region-name registry as well as `_G`: `<ColorValueTexture>`
-                        // anchors to `ColorPickerWheel` BY NAME, and a name that only reaches the
-                        // globals resolves to nothing there.
+                        // Published both ways: the stock `<ColorValueTexture>` anchors to
+                        // `ColorPickerWheel` by name.
                         crate::script::region::publish_region_name(self.lua(), &rname, &region);
                         if let Err(e) = self.lua().globals().set(rname.clone(), region) {
                             self.report
@@ -709,25 +498,9 @@ impl Loader<'_> {
         }
     }
 
-    /// `<SimpleHTML>` LoadXML extras — `CSimpleHTML::LoadXML 0x78a130`, whose whole job past the
-    /// base `CSimpleFrame::LoadXML 0x769820` is to fill the four **element fonts** and the
-    /// hyperlink format (wow-re `simplehtml-markup-engine.md` §5.5):
-    ///
-    /// - attribute **`font="NAME"`** (`0x78a152`) — looked up as a font object and `SetFontObject`ed
-    ///   onto **all four** elements at once (the `edi = 4` loop at `0x78a17a`), with
-    ///   `"Couldn't find font object named %s"` on a miss.
-    /// - child **`<FontString>`** → `elementFont[0]` (`P`), **`<FontStringHeader1|2|3>`** →
-    ///   `[1]`/`[2]`/`[3]` (`0x78a1fe`…`0x78a26e`), each through `CSimpleFont::LoadXML 0x783c30`.
-    /// - attribute **`hyperlinkFormat`** (`0x87a87c` → `0x78a540`) and attribute **`file`**
-    ///   (`0x8710b8`), the latter a localized-string lookup fed straight to `SetText`.
-    ///
-    /// **These `<FontString>` children are font DECLARATIONS, not regions**, which is why
-    /// [`Self::apply_special_fontstrings`] skips a `<SimpleHTML>`: creating a real FontString for
-    /// one would put an extra, unanchored string on the frame and leave the element font empty.
-    ///
-    /// Stock `ItemTextFrame.xml` declares exactly one `<FontString inherits="ItemTextFontNormal"/>`,
-    /// which is the whole reason an `<H1>` in a `page_text` body renders at the `<P>` size: nothing
-    /// declares a header font, so `0x78ae30`'s empty-path test sends every element back to `P`'s.
+    /// `<SimpleHTML>` (`0x78a130`): `font=` for all four element fonts (`0x78a17a`), the
+    /// `<FontString>` and `<FontStringHeader1..3>` children one each (`0x78a1fe`, through
+    /// `0x783c30`), `hyperlinkFormat` (`0x78a540`), and `file=`, a global-string key for `SetText`.
     pub(super) fn apply_simplehtml(&mut self, el: &Element, wrapper: &Table, dbg: &str) {
         if !el.tag.eq_ignore_ascii_case("SimpleHTML") {
             return;
@@ -735,8 +508,7 @@ impl Loader<'_> {
         if let Some(fmt) = el.attr("hyperlinkFormat") {
             self.call(wrapper, "SetHyperlinkFormat", fmt.to_string(), dbg);
         }
-        // `font=` on the widget itself paints all four elements; a per-element child below can
-        // still override any of them, exactly as the reference's ordering allows.
+        // Read before the children (`0x78a152`), which may override it.
         if let Some(name) = el.attr("font").filter(|n| !n.is_empty()) {
             if self.is_font_object(name) {
                 for elem in ["P", "H1", "H2", "H3"] {
@@ -751,7 +523,7 @@ impl Loader<'_> {
         }
         for child in &el.children {
             let Some(elem) = crate::script::simplehtml_element_of_xml_tag(&child.tag) else {
-                continue; // <Size>/<Anchors>/<Scripts>/<Layers>/... have their own passes
+                continue;
             };
             let child = &self.expand_region(child);
             self.apply_element_font(child, wrapper, elem, dbg);
@@ -762,14 +534,8 @@ impl Loader<'_> {
         }
     }
 
-    /// One `<FontString>`/`<FontStringHeaderN>` child of a `<SimpleHTML>` → one element font.
-    ///
-    /// The `inherits=` → `font=` gate is the same three-outcome law a `<Layers>` `<FontString>`
-    /// takes ([`Self::apply_fontstring_font`], `0x7710e1`-`0x771254`): a `font=` naming a registered
-    /// object is a `SetFontObject` and **skips** `<FontHeight>`/`outline=` entirely; a `font=`
-    /// naming anything else is a file with those two as its companions; no `font=` at all means
-    /// neither is ever parsed. Only `<Color>`/`<Shadow>`/`justifyH`/`justifyV`/`spacing` sit past
-    /// that join and are genuine post-link overrides.
+    /// One `<SimpleHTML>` font child's element font, with the same `font=` gate as
+    /// [`Self::apply_fontstring_font`].
     fn apply_element_font(&mut self, el: &Element, wrapper: &Table, elem: usize, dbg: &str) {
         let name = ["P", "H1", "H2", "H3"][elem];
         if let Some(inherits) = el.attr("inherits").filter(|n| !n.is_empty()) {
diff --git a/crates/benilla-ui/src/markup.rs b/crates/benilla-ui/src/markup.rs
index 9d99f488..e5817f9e 100644
--- a/crates/benilla-ui/src/markup.rs
+++ b/crates/benilla-ui/src/markup.rs
@@ -1,134 +1,57 @@
-//! WoW's inline text markup — the grammar every 1.12.1 string carries (`|cAARRGGBB`, `|r`,
-//! `|H…|h…|h`, `|n`, `||`), and the cursor law an edit box builds on top of it.
+//! The 1.12 inline text markup (`|cAARRGGBB`, `|r`, `|H…|h…|h`, `|n`, `||`) and the edit box's
+//! cursor law over it, one grammar for the renderer and the edit box. It transcribes the token
+//! decoder `0x5c2810` ([`token_at`]: a byte remap at `0x5c2b10` into the jump table at `0x5c2af4`)
+//! and the edit box's per-byte class array `E+0x330`, rebuilt by `0x77ba90` after every edit, with
+//! the primitives that read it ([`ClassMap`]).
 //!
-//! Pure: `&str` in, indices out. No Lua, no Bevy, no engine types, no I/O — so the renderer and the
-//! edit box can share **one** owner of the grammar instead of drifting apart on where an escape
-//! starts and ends.
+//! 1.12 has no `|T…|t` texture escape: the remap claims only `c`, `h`, `n`, `r` in either case and
+//! `|`, so `|TInterface\Icons\Foo:16:16|t` draws literally.
 //!
-//! ## Ground truth
+//! The decoder's flags word can disable classes, but no code in the 1.12 client sets the bits for
+//! `|c`, `|r`, `|H`, `|h` or `||` (`0x44d670` builds it from a font string's flags). Only `|n` can
+//! be switched off, on a single-line edit box (`SetMultiLine`, `0x77a5e2`), and the class map
+//! parses it regardless (`0x77ba90` passes 0), so that gate belongs to the renderer's line breaker.
 //!
-//! wow-5875-re `system/ui/scratch/rf87-editbox-markup.md` (RF-0087, a §5 trio arbitrated against the
-//! bytes). Two client mechanisms are transcribed here, and every claim below carries its address:
-//!
-//! - **`0x5c2810`** (`font`'s diffed `decode_quoted_code`) — the token decoder. Given a pointer it
-//!   returns a class 0..6 and the token's byte length, dispatching off a byte remap at `0x5c2b10`
-//!   into the 7-arm jump table at `0x5c2af4`. That is [`token_at`] / [`tokens`].
-//! - **`0x77ba90`** — the edit box's per-byte class array `E+0x330`, rebuilt in full after every
-//!   mutation, plus the five primitives that read it (`0x77bd10`, `0x77bd30`, `0x77bc80`,
-//!   `0x77bb30`, `0x77c510`, `0x77bee0`). That is [`ClassMap`].
-//!
-//! ## The seven classes (§1.1) — the client's own numbering
-//!
-//! - **0** `|cAARRGGBB` — 10 bytes. The `AA` is parsed and then *discarded*: `0x5c2ab2–0x5c2ace`
-//!   builds `0xFF << 24 | RR << 16 | GG << 8 | BB`. See [`Rgba`].
-//! - **1** `|r` / `|R` — 2 bytes.
-//! - **2** `\n` · `\r` · `\r\n` · `|n` / `|N` — 1 or 2 bytes.
-//! - **3** `||` — 2 bytes, draws one literal `|`.
-//! - **4** hyperlink OPEN — the **entire** `|H<payload>|h` prefix, however long.
-//! - **5** `|h` close — 2 bytes.
-//! - **6** an ordinary character — its UTF-8 length. Everything the remap doesn't claim lands here,
-//!   *including* a `|` followed by anything outside `{c C h H n N r R |}`.
-//!
-//! **1.12.1 has no `|T…|t` inline-texture escape at all.** The remap table at `0x5c2b10` (index =
-//! `ch - 'C'`) sends every byte but `C`/`H`/`N`/`R` and their lowercase siblings to the
-//! ordinary-character arm, so `|TInterface\Icons\Foo:16:16|t` draws literally, pipe and all. Inline
-//! textures are a later-expansion feature; this module must not invent one.
-//!
-//! ## What the parse gates do *not* do (§1.3)
-//!
-//! `0x5c2810` takes a flags word `K` that can disable classes, and `0x44d670` translates the
-//! FontString's `F` into it. An origination census over the whole image found **no writer anywhere**
-//! for the bits behind `K & 0x100` / `0x400` / `0x800`, so `|c`, `|r`, `|H`, `|h` and `||` are parsed
-//! unconditionally by every `CSimpleFontString` in build 5875. Only `|n` is switchable (`F & 0x4000`,
-//! set on a single-line edit box by `SetMultiLine` `0x77a5e2`) — and `0x77ba90` builds the class map
-//! with `K = 0` regardless, so the *cursor* model always sees `|n` as one token. This module
-//! therefore takes no flags word: the one live gate belongs to the renderer's line breaker, not to
-//! the grammar (the resulting caret drift in a single-line box carrying `|n` is the note's §7
-//! anomaly 1, and is the renderer's to reproduce or to fix).
-//!
-//! ## The law this module exists to hold
-//!
-//! **The reachable cursor set is "a token boundary with every adjacent zero-width escape absorbed" —
-//! after any trailing `|r`/`|h`, before any leading `|c`/`|H`** (§6.1). No index inside an escape is
-//! representable as an output of [`ClassMap::advance`], at either atomicity, in either direction;
-//! atomicity adds exactly one thing, that the visible text between `|H…|h` and its closing `|h`
-//! becomes uncrossable in a single step. Every index taken or returned by anything here is a byte
-//! offset into the original string, and every one lands on a UTF-8 character boundary.
-//!
-//! ## Inferred, not verified
-//!
-//! Flagged here as well as at each site, because the note is explicit about what it proved:
-//!
-//! - **`|H` opens and `|h` closes, discriminated by case.** The remap sends both to one arm and the
-//!   note does not disassemble the case test; §1.1's table (class 4 is the whole `|H<payload>|h`,
-//!   class 5 is `|h`) plus the empty-visible-text guard comparing against lowercase `0x68`
-//!   (`80 7e 01 68` @`0x5c2992`) is the whole basis.
-//! - **The delimiter search is a plain forward byte scan for `|h`** that does not skip `||`. The
-//!   emitter's own scan (`0x5ccdc8`, against the literal at `0x84453c`) is described the same way;
-//!   the decoder arm's scan was not disassembled.
-//! - **`0x77bc80`'s second argument is a byte budget**, not a token count — from the `(start, count)`
-//!   signature and the byte-budget shape of its sibling kernel `0x5c6940`.
-//! - **The end-of-buffer guard on [`ClassMap::advance`] is ours.** The note's excerpt of `0x77bb30`
-//!   shows no bound, and its class-0/class-4 "keep skipping" arms would spin on the zero terminator.
-//! - **The worked example (§6.5) is itself INFERRED in the note**, from the verified mechanism.
+//! A cursor stands only on a token boundary with the adjacent zero-width escapes absorbed: after
+//! any trailing `|r`/`|h`, before any leading `|c`/`|H` (`0x77bb30`). Every index here is a byte
+//! offset on a UTF-8 character boundary.
 
 use std::ops::Range;
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The colour a `|c` token carries
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The colour a `|c` token carries ──────────────────────────────────────────────────────────
 
-/// The colour decoded from `|cAARRGGBB`, packed exactly as the client packs it —
-/// `0xFF << 24 | RR << 16 | GG << 8 | BB` (`0x5c2ab2–0x5c2ace`).
-///
-/// **The `AA` nibbles are parsed and then thrown away** (§7 anomaly 4): there is no way to spell a
-/// translucent colour in 1.12.1 markup. A type that cannot carry alpha is how this module refuses to
-/// invent one — `|c00ff0000` and `|cffff0000` are the same opaque red.
+/// A `|cAARRGGBB` colour as the decoder packs it, `0xFFRRGGBB` (`0x5c2ab2..0x5c2ace`): the `AA` is
+/// parsed and discarded, so `|c00ff0000` and `|cffff0000` are the same red.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub struct Rgba(u32);
 
 impl Rgba {
-    /// The opaque colour with these components — the only way to build one.
     pub const fn from_rgb(r: u8, g: u8, b: u8) -> Rgba {
         Rgba(0xff00_0000 | ((r as u32) << 16) | ((g as u32) << 8) | b as u32)
     }
 
-    /// The client's packed dword, `0xFFRRGGBB`.
     pub const fn packed(self) -> u32 {
         self.0
     }
 
-    /// Red.
     pub const fn r(self) -> u8 {
         (self.0 >> 16) as u8
     }
 
-    /// Green.
     pub const fn g(self) -> u8 {
         (self.0 >> 8) as u8
     }
 
-    /// Blue.
     pub const fn b(self) -> u8 {
         self.0 as u8
     }
 
-    /// Alpha — always `0xff`. Kept as an accessor so the discard is visible at the call site.
     pub const fn a(self) -> u8 {
         0xff
     }
 
-    /// `[r, g, b, alpha]` in 0..1 — the escape's colour drawn at the **FontString's own alpha**.
-    ///
-    /// The decoder forcing `0xff` is only half the law: the emitter then patches the FontString's
-    /// alpha byte over it (`mov cl,[edi+0x2f]; mov [ebp-0x39],cl` @`0x5cceb0`/`0x5cceb6`, written
-    /// into the outColor slot *before* `mov edx,[ebp-0x3c]` reads it — RF-0087 §7, corrected under
-    /// an emulation oracle). So a `|c` span fades with the string it sits in; drawing it opaque
-    /// would leave a chat link burning at full alpha while its own line faded out.
-    ///
-    /// Taking `alpha` as an argument rather than storing one keeps both halves true: the *escape*
-    /// still cannot carry alpha (`|c00ff0000` and `|cffff0000` are the same colour), and the alpha
-    /// that reaches the vertex is always the string's.
+    /// `[r, g, b, alpha]` in 0..1: the emitter patches the font string's own alpha over the decoded
+    /// `0xff` (`0x5cceb0`, `0x5cceb6`), so a `|c` span fades with its string.
     pub fn to_f32_at(self, alpha: f32) -> [f32; 4] {
         [
             self.r() as f32 / 255.0,
@@ -139,57 +62,46 @@ impl Rgba {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Layer 1 — the token decoder (`0x5c2810`)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Layer 1: the token decoder (`0x5c2810`) ──────────────────────────────────────────────────
 
-/// The token class, with the client's own numbering (§1.1) as the discriminant, so a `class` in the
-/// RE note greps straight to a variant here. Returned by `0x5c2810` in `eax`, and stored in bits
-/// 16..23 of every class-map entry.
+/// The token class as `0x5c2810` numbers it, and as a class-map entry stores it (bits 16..23).
 #[repr(u8)]
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum TokenClass {
-    /// 0 — `|cAARRGGBB`, 10 bytes.
+    /// `|cAARRGGBB`, 10 bytes.
     Color = 0,
-    /// 1 — `|r` / `|R`, 2 bytes.
+    /// `|r` or `|R`, 2 bytes.
     ColorReset = 1,
-    /// 2 — `\n`, `\r`, `\r\n`, `|n` / `|N`.
+    /// `\n`, `\r`, `\r\n`, `|n` or `|N`.
     LineBreak = 2,
-    /// 3 — `||`, 2 bytes, drawing one literal `|`.
+    /// `||`, 2 bytes, drawing one `|`.
     EscapedPipe = 3,
-    /// 4 — hyperlink OPEN: the entire `|H<payload>|h` prefix.
+    /// A hyperlink's whole `|H<payload>|h` prefix.
     LinkOpen = 4,
-    /// 5 — `|h`, the close, 2 bytes.
+    /// `|h`, 2 bytes, closing a hyperlink.
     LinkClose = 5,
-    /// 6 — an ordinary character, its UTF-8 length.
+    /// An ordinary character, its UTF-8 length.
     Char = 6,
 }
 
-/// What a token *is*, with whatever it carries.
+/// A token and what it carries.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum TokenKind<'a> {
-    /// Class 0 — switch the draw colour. Opaque by construction; see [`Rgba`].
     Color(Rgba),
-    /// Class 1 — back to the string's base colour (`0x5cce99` restores `FontString+0x2c`).
+    /// Back to the string's base colour (`0x5cce99` restores `FontString+0x2c`).
     ColorReset,
-    /// Class 2 — a line break, whichever of the four spellings produced it.
     LineBreak,
-    /// Class 3 — `||`, which draws one `|` (`0x5ccec3` looks up the glyph).
+    /// Draws one `|` (`0x5ccec3` looks up the glyph).
     EscapedPipe,
-    /// Class 4 — open a hyperlink over the visible text that follows. `payload` is the text between
-    /// `|H` and the delimiting `|h` (`item:12345:0:0:0`, `player:Bob`).
     LinkOpen {
-        /// The link payload, delimiters excluded.
+        /// The text between `|H` and `|h`, such as `item:12345:0:0:0`.
         payload: &'a str,
     },
-    /// Class 5 — the closing `|h`.
     LinkClose,
-    /// Class 6 — an ordinary character. A `|` that opened nothing well-formed arrives here too.
     Char(char),
 }
 
 impl TokenKind<'_> {
-    /// The client's class number for this token.
     pub const fn class(&self) -> TokenClass {
         match self {
             TokenKind::Color(_) => TokenClass::Color,
@@ -203,39 +115,28 @@ impl TokenKind<'_> {
     }
 }
 
-/// One decoded token: what it is, and how many bytes of the source it spans.
-///
-/// The length is not derivable from the kind — `\r\n` and `\n` are both [`TokenKind::LineBreak`],
-/// and a [`TokenKind::LinkOpen`] spans its whole `|H<payload>|h` prefix — so `0x5c2810` returns it
-/// separately (`*ioLen`), and so do we.
+/// One decoded token and its byte length, which `0x5c2810` returns beside the class (`*ioLen`).
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Token<'a> {
-    /// What this token is.
     pub kind: TokenKind<'a>,
-    /// Its byte length. Always ≥ 1.
+    /// At least 1.
     pub byte_len: usize,
 }
 
 impl Token<'_> {
-    /// The client's class number for this token.
     pub const fn class(&self) -> TokenClass {
         self.kind.class()
     }
 }
 
-/// Decode the token starting at byte offset `at` — the whole of `0x5c2810`.
-///
-/// `None` at (or past) the end of the string. `at` must be a UTF-8 character boundary of `text`;
-/// every offset this module produces is one.
-///
-/// The degradations are law, not tolerance: a `|` that opens nothing well-formed is an *ordinary
-/// character* of length 1, exactly as the remap table's fall-through arm makes it.
+/// Decode the token at byte offset `at`, a character boundary: `0x5c2810`. A `|` that opens
+/// nothing well-formed is an ordinary character of length 1, as the remap's fall-through makes it.
 pub fn token_at(text: &str, at: usize) -> Option<Token<'_>> {
     let rest = &text[at..];
     let b = rest.as_bytes();
     let first = *b.first()?;
 
-    // The two bare line breaks. `\r\n` is ONE class-2 token; a lone `\r` is one as well.
+    // `\r\n` is one class-2 token; a lone `\r` is one too.
     if first == b'\r' {
         let byte_len = if b.get(1) == Some(&b'\n') { 2 } else { 1 };
         return Some(Token {
@@ -251,8 +152,7 @@ pub fn token_at(text: &str, at: usize) -> Option<Token<'_>> {
     }
 
     if first == b'|' {
-        // The ordinary-character fall-through: a lone `|`, or one leading anything the remap table
-        // at `0x5c2b10` does not claim.
+        // A lone `|`, or one leading anything the remap (`0x5c2b10`) does not claim.
         let literal_pipe = Token {
             kind: TokenKind::Char('|'),
             byte_len: 1,
@@ -278,8 +178,8 @@ pub fn token_at(text: &str, at: usize) -> Option<Token<'_>> {
                 kind: TokenKind::EscapedPipe,
                 byte_len: 2,
             },
-            // INFERRED (see the module doc): uppercase opens, lowercase closes. The remap sends both
-            // to one arm and the note does not disassemble the case test.
+            // Uppercase opens and lowercase closes, inferred: the remap sends both to one arm,
+            // whose case test is untraced.
             Some(b'H') => match parse_link_open(rest) {
                 Some((payload, byte_len)) => Token {
                     kind: TokenKind::LinkOpen { payload },
@@ -302,9 +202,7 @@ pub fn token_at(text: &str, at: usize) -> Option<Token<'_>> {
     })
 }
 
-/// `b` starts with `|c` or `|C`. Parse the 8 following hex digits as `AARRGGBB` and **discard the
-/// alpha** (`0x5c2ab2–0x5c2ace`). `None` when fewer than 8 hex digits follow — a malformed colour is
-/// an ordinary character, not a swallowed escape.
+/// The 8 hex digits `AARRGGBB` after `|c`, alpha discarded; fewer leave the `|` literal.
 fn parse_color(b: &[u8]) -> Option<Rgba> {
     let digits = b.get(2..10)?;
     let mut v: u32 = 0;
@@ -314,18 +212,10 @@ fn parse_color(b: &[u8]) -> Option<Rgba> {
     Some(Rgba::from_rgb((v >> 16) as u8, (v >> 8) as u8, v as u8))
 }
 
-/// `rest` starts with `|H`. Returns the payload and the byte length of the **whole**
-/// `|H<payload>|h` prefix, or `None` for each of the three degradations that make the `|H` a literal
-/// `|` instead:
-///
-/// - no closing `|h` anywhere after it — the forward scan finds no delimiter;
-/// - the span is exactly 4 bytes, i.e. an empty payload (`83 f8 04; 75 1b` @`0x5c2972`);
-/// - the visible text is empty, i.e. the span is immediately followed by another `|h`
-///   (`80 f9 7c; 75 21; 80 7e 01 68; 75 1b` @`0x5c2992`).
-///
-/// The scan is a plain forward byte search that does not skip `||` (INFERRED — the emitter's own
-/// scan at `0x5ccdc8` is described the same way). Searching bytes is safe in UTF-8: `|` and `h` are
-/// ASCII and can never appear inside a multi-byte character.
+/// The payload after `|H` and the length of the whole `|H<payload>|h` prefix; `None`, a literal
+/// `|`, when no `|h` follows, when the payload is empty (`0x5c2972`) or when the visible text is
+/// empty (`0x5c2992`). The delimiter scan is a plain byte search that does not skip `||`, inferred
+/// from the emitter's own scan (`0x5ccdc8`, for the literal at `0x84453c`).
 fn parse_link_open(rest: &str) -> Option<(&str, usize)> {
     let b = rest.as_bytes();
     let delim = (2..b.len().saturating_sub(1)).find(|&i| b[i] == b'|' && b[i + 1] == b'h')?;
@@ -339,7 +229,7 @@ fn parse_link_open(rest: &str) -> Option<(&str, usize)> {
     Some((&rest[2..delim], span))
 }
 
-/// Every token of `text`, each with the byte offset it starts at — `char_indices`, one grammar up.
+/// Every token of `text` with the byte offset it starts at.
 pub fn tokens(text: &str) -> Tokens<'_> {
     Tokens { text, at: 0 }
 }
@@ -362,25 +252,14 @@ impl<'a> Iterator for Tokens<'a> {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Layer 2 — the per-byte class map (`E+0x330`, built by `0x77ba90`)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Layer 2: the per-byte class map (`E+0x330`, built by `0x77ba90`) ─────────────────────────
 
-/// One entry of the class map — the client's packed dword (§2.1), unpacked:
+/// One class-map entry, the client's dword unpacked: byte length in bits 0..15, class in 16..23,
+/// "inside a hyperlink" in bit 31. Only a token's first byte is stored (`0x77bb0f`); continuation
+/// bytes and the terminator are zero, so they read as no class and not in a link.
 ///
-/// - bits 0..15, the token's **byte length**, non-zero only at the token's *first* byte;
-/// - bits 16..23, the token class;
-/// - bit 31, **"inside a hyperlink"**.
-///
-/// Every continuation byte, and the terminator past the end, is the all-zero dword: `0x77ba90`
-/// `rep stos`-zeroes the array and then stores only at each token's first byte
-/// (`mov [classArr + 4*ebx], ecx` @`0x77bb0f`). So [`Entry::class`] is `None` exactly where
-/// [`Entry::byte_len`] is 0, and [`Entry::in_link`] reads false on a continuation byte even inside
-/// a link — which is the client's own reading (`0x77c510` tests the whole dword's sign bit), and
-/// harmless, since no cursor can be at one.
-///
-/// The client's length field is 16 bits (`and len,0xffff` @`0x77baf3`); ours is wider, so a
-/// pathological `|H` span ≥ 64 KiB simply does not wrap.
+/// Deviation: the length keeps every bit, where the client masks it to 16 (`0x77baf3`), because a
+/// wrapped length would put the cursor inside an `|H` span of 64 KiB or more.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Entry {
     byte_len: u32,
@@ -396,54 +275,39 @@ impl Entry {
         in_link: false,
     };
 
-    /// The token's byte length — 0 at a continuation byte and at the terminator.
     pub const fn byte_len(&self) -> usize {
         self.byte_len as usize
     }
 
-    /// The token class, or `None` at a continuation byte / the terminator.
     pub const fn class(&self) -> Option<TokenClass> {
         self.class
     }
 
-    /// Bit 31 — is this token part of a hyperlink? Raised on the class-4 open **inclusive**, lowered
-    /// only *after* the class-5 close, so the close is tagged too.
+    /// Bit 31: set from a link's `|H` through its closing `|h`, both included.
     pub const fn in_link(&self) -> bool {
         self.in_link
     }
 
-    /// Does a token start here? (Equivalently: is this not a continuation byte?)
     pub const fn is_token_start(&self) -> bool {
         self.byte_len != 0
     }
 }
 
-/// The per-byte token-class array the edit box keeps at `E+0x330`, and the cursor primitives that
-/// read it.
-///
-/// One entry per byte of the source string plus a terminating entry
-/// (`classArr[len] = 0` @`0x77c670`), so an index equal to the string length is always valid — the
-/// cursor's home at the end of the buffer.
-///
-/// It holds no text: every primitive here reads only the entries, which is what lets an edit box own
-/// its `String` and rebuild the map beside it after each mutation, exactly as `0x77ba90` is called
-/// at the tail of every insert (`0x77c022`).
+/// The edit box's per-byte class array (`E+0x330`) and the cursor primitives over it: one entry
+/// per byte plus a zero terminator (`0x77c670`). It holds no text; the edit box rebuilds it after
+/// every edit, as the client calls `0x77ba90` at the end of each insert (`0x77c022`).
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct ClassMap {
     entries: Vec<Entry>,
 }
 
 impl ClassMap {
-    /// Build the map for `text` — `0x77ba90`.
-    ///
-    /// The client passes `K = 0` here (`push 0` @`0x77bad9`), so the cursor model always parses
-    /// *every* class, `|n` included, whatever the FontString's flags say (§2.1, and §7 anomaly 1 for
-    /// the consequence).
+    /// `0x77ba90`, which parses every class, `|n` included, whatever the font string's flags
+    /// (`K = 0` at `0x77bad9`).
     pub fn new(text: &str) -> ClassMap {
         let mut entries = vec![Entry::CONTINUATION; text.len() + 1];
-        // The sticky link bit: raised BEFORE the store on a class-4 open (`or [ebp-4],0x80000000`
-        // @`0x77baec`), lowered AFTER the store on a class-5 close (`and [ebp-4],0x7fffffff`
-        // @`0x77bb1e`) — which is why the closing `|h` is tagged and the byte after it is not.
+        // The link bit rises before the store on an open (`0x77baec`) and falls after it on a
+        // close (`0x77bb1e`), so the closing `|h` is tagged and the byte after it is not.
         let mut in_link = false;
         for (at, token) in tokens(text) {
             let class = token.class();
@@ -462,27 +326,22 @@ impl ClassMap {
         ClassMap { entries }
     }
 
-    /// The byte length of the string this map was built from.
     pub fn text_len(&self) -> usize {
         self.entries.len() - 1
     }
 
-    /// The entry for byte `at`. `at == text_len()` is the terminator; anything past it panics.
+    /// `at == text_len()` is the terminator; past it panics.
     pub fn entry(&self, at: usize) -> Entry {
         self.entries[at]
     }
 
-    /// The next token's start — `0x77bd10`, which is `i + (classArr[i] & 0xffff)` and nothing else.
-    ///
-    /// A fixed point at the terminator and at any continuation byte, where the length is 0; the
-    /// client's add is unguarded in the same way, so a forward walk tests `at < text_len()` rather
-    /// than relying on this to move.
+    /// The next token's start, `0x77bd10`: a fixed point where the length is 0, as the client's
+    /// unguarded add is, so a forward walk must test `at < text_len()`.
     pub fn next_token(&self, at: usize) -> usize {
         at + self.entry(at).byte_len()
     }
 
-    /// The previous token's start — `0x77bd30`: walk back from `at - 1` while the entry is a
-    /// continuation. `None` when there is none (the client's `-1`), i.e. at offset 0.
+    /// The previous token's start, `0x77bd30`; `None`, the client's `-1`, at offset 0.
     pub fn prev_token(&self, at: usize) -> Option<usize> {
         let mut i = at.checked_sub(1)?;
         while !self.entry(i).is_token_start() {
@@ -491,16 +350,9 @@ impl ClassMap {
         Some(i)
     }
 
-    /// How many **letters** the `byte_count` bytes from `start` hold — `0x77bc80`, which counts
-    /// classes 2, 3 and 6 only (`83 fa 02/03/06` @`0x77bcb0`).
-    ///
-    /// This is what `GetNumLetters` reports and what `SetMaxLetters` caps, so **classes 0/1/4/5 are
-    /// not letters**: a 48-byte item link costs 14, its visible `[Chipped Claw]` and nothing more.
-    ///
-    /// INFERRED: that the second argument is a byte budget (the note gives only the `(start, count)`
-    /// signature; the sibling kernel `0x5c6940` consumes bytes the same way). A token straddling the
-    /// end of the budget is counted whole and ends the walk — deliberately *not* the sibling
-    /// kernel's run-to-the-NUL behaviour (§7 anomaly 3), which is a latent trap with no upside here.
+    /// The letters in `byte_count` bytes from `start`, `0x77bc80`, a per-byte scan that counts
+    /// only classes 2, 3 and 6 (`0x77bcb0`): `GetNumLetters` and `SetMaxLetters` see a 48-byte
+    /// item link as its 14 visible letters. A token starting inside the budget counts whole.
     pub fn letters(&self, start: usize, byte_count: usize) -> usize {
         let end = start.saturating_add(byte_count).min(self.text_len());
         let mut at = start;
@@ -519,29 +371,19 @@ impl ClassMap {
         letters
     }
 
-    /// The whole string's letter count — `GetNumLetters`.
+    /// The whole string's letter count, `GetNumLetters`.
     pub fn num_letters(&self) -> usize {
         self.letters(0, self.text_len())
     }
 
-    /// Move the cursor `steps` token-steps from `from` — `0x77bb30`, the heart of the cursor model
-    /// (§6.1). Negative `steps` walk backward. Returns the resulting byte offset (the client returns
-    /// the *magnitude* of the delta and its caller `0x77c6b0` signs it; same thing, one fewer trap).
+    /// The byte offset `steps` token steps from `from`, backward when negative: `0x77bb30`, whose
+    /// caller `0x77c6b0` signs its result. `atomic_links` is the keyboard's walk (arrows, word
+    /// jumps, HOME/END, BACKSPACE, DELETE), crossing a whole `|H…|h[text]|h` in one step; click,
+    /// drag, UP/DOWN, the scroll-window sizing and the IME span stop on each visible character.
     ///
-    /// `atomic_links` is the whole of the difference between the keyboard and the mouse (§6.2): every
-    /// arrow, word-jump, HOME/END, BACKSPACE and DELETE path passes 1 and crosses a whole
-    /// `|H…|h[text]|h` in one step, while click, drag, UP/DOWN, the scroll-window sizing and the IME
-    /// span all pass 0 and stop on each visible character. Neither ever stops *inside* an escape.
-    ///
-    /// **The end-of-buffer guard is a deliberate divergence: the real client HANGS here.** Its inner
-    /// skip loop re-enters at `0x77bb60`, past the zero guard at `0x77bb56`, and the terminator slot
-    /// decodes as class 0 with length 0 — a class the loop skips unconditionally — so a walk still
-    /// skipping at the end of the buffer spins forever consuming no bytes. Confirmed by executing
-    /// `0x77bb30` under an emulation oracle (RF-0087 §10). It is reachable: a trailing `|c` hangs in
-    /// both modes and an unclosed link hangs at `atomic_links = true`, so `SetText("|cffffffff")`
-    /// plus one RIGHT freezes 1.12.1. A user cannot type it (`|` becomes `||`) but any script can
-    /// set it. We bound the loop by the buffer and land the step on the far end instead —
-    /// reproducing a freeze is not fidelity.
+    /// Deviation: a step that runs out of buffer while skipping lands on the far end, because the
+    /// client spins forever there (its skip loop re-enters at `0x77bb60`, past the zero check at
+    /// `0x77bb56`), so `SetText("|cffffffff")` and one RIGHT hang 1.12.
     pub fn advance(&self, from: usize, steps: isize, atomic_links: bool) -> usize {
         let mut at = from;
         for _ in 0..steps.unsigned_abs() {
@@ -554,7 +396,7 @@ impl ClassMap {
         at
     }
 
-    /// One step forward — the inner loop at `0x77bb60`, then the post-step absorb at `0x77bb98`.
+    /// One step forward: the skip loop at `0x77bb60`, then the absorb at `0x77bb98`.
     fn step_forward(&self, from: usize, atomic_links: bool) -> usize {
         let end = self.text_len();
         let mut at = from;
@@ -562,21 +404,20 @@ impl ClassMap {
             let entry = self.entry(at);
             let Some(class) = entry.class() else { break };
             at += entry.byte_len();
-            // `|c` and `|H…|h` are skipped whatever the atomicity: a cursor never sits after a
-            // leading escape (`74 da` @`0x77bb84`, `74 d5` @`0x77bb86`).
+            // `|c` and `|H…|h` are skipped at either atomicity (`0x77bb84`, `0x77bb86`).
             if matches!(class, TokenClass::Color | TokenClass::LinkOpen) {
                 continue;
             }
             if !atomic_links {
-                break; // `84 db; 74 09` — one visible token consumed
+                break; // one visible token consumed
             }
             if !entry.in_link() {
-                break; // `85 d2; 79 05` — bit 31 clear
+                break; // bit 31 clear
             }
             if class == TokenClass::LinkClose {
-                break; // the close is what ends the atomic skip
+                break; // the close ends the atomic skip
             }
-            // Inside a link and not the close: keep skipping (`83 ff 05; 75 c8`) — the atomicity.
+            // Inside a link and not its close: keep skipping.
         }
         // Then absorb any immediately following `|r` / `|h`, so the cursor lands past them.
         while at < end
@@ -590,18 +431,17 @@ impl ClassMap {
         at
     }
 
-    /// One step backward — the mirror at `0x77bc13` / `0x77bc1d` / `0x77bc59`.
+    /// One step backward, the mirror (`0x77bc13`, `0x77bc1d`, `0x77bc59`).
     fn step_back(&self, from: usize, atomic_links: bool) -> usize {
         let mut at = from;
-        // Trailing `|r` / `|h` first (`83 fa 01; 74 ca` / `83 fa 05; 74 c5`).
+        // Trailing `|r` and `|h` first.
         while let Some(prev) = self.prev_token(at) {
             match self.entry(prev).class() {
                 Some(TokenClass::ColorReset | TokenClass::LinkClose) => at = prev,
                 _ => break,
             }
         }
-        // One token back — extended, when atomic, over the whole link to its class-4 open
-        // (`8a 5d 10; 84 db; 74 09; 85 f6; 79 05; 83 fa 04; 75 b5`).
+        // One token back, extended when atomic over the whole link to its open.
         while let Some(prev) = self.prev_token(at) {
             let entry = self.entry(prev);
             at = prev;
@@ -609,7 +449,7 @@ impl ClassMap {
                 break;
             }
         }
-        // Then back over any preceding `|c` / `|H` (`85 f6; 74 05; 83 fe 04; 75 08`).
+        // Then back over any preceding `|c` or `|H`.
         while let Some(prev) = self.prev_token(at) {
             match self.entry(prev).class() {
                 Some(TokenClass::Color | TokenClass::LinkOpen) => at = prev,
@@ -619,23 +459,11 @@ impl ClassMap {
         at
     }
 
-    /// Widen a half-open deletion range so it cannot cut a hyperlink in half — `0x77c510` (§6.3),
-    /// called by BACKSPACE/DELETE (`0x77c280`), by delete-selection (`0x77cd70`) and by Clear
-    /// (`0x77c500`).
-    ///
-    /// If `start` is inside a link, walk back to the class-4 open and then over the whole preceding
-    /// `|c`/`|H` run; if `end` is inside a link, walk forward past the closing `|h` and any following
-    /// `|r`. So **any deletion touching any byte of a link removes the whole
-    /// `|c…|H…|h[text]|h|r` unit** — a second, independent guarantee on top of the atomic walk, and
-    /// what makes even a mouse-drag partial selection delete cleanly.
-    ///
-    /// Two faithfully-kept edges. The endpoint tests read `classArr[start]` / `classArr[end]`
-    /// directly (`83 3c 96 00; 79 50` @`0x77c543`, `83 3c 86 00; 79 55` @`0x77c59d`), so an *end*
-    /// that merely abuts a link's first byte — the byte it does not include — still widens; and the
-    /// backward walk stops on class 0 as well as class 4 (both `jz`s @`0x77c550` land on the same
-    /// target), so a `|c` sitting *inside* a link's visible text ends it early. 1.12 content puts the
-    /// colour outside the link (`0x52adb0`'s `"%s|Hitem:%d:%d:%d:%d|h[%s]|h%s"`), so the second edge
-    /// is unreachable in practice; it is recorded rather than smoothed away.
+    /// Widen a deletion range so it never cuts a hyperlink: `0x77c510`, for BACKSPACE and DELETE
+    /// (`0x77c280`), delete-selection (`0x77cd70`) and Clear (`0x77c500`). Touching any byte of a
+    /// link removes the whole `|c…|H…|h[text]|h|r` unit. The endpoint tests read the entries at
+    /// `start` and `end` (`0x77c543`, `0x77c59d`), so an end that only abuts a link's `|H` still
+    /// widens, and the backward walk also stops on a `|c` inside the link text (`0x77c550`).
     pub fn snap_delete_range(&self, range: Range<usize>) -> Range<usize> {
         let Range {
             start: mut lo,
@@ -677,21 +505,16 @@ impl ClassMap {
         lo..hi
     }
 
-    /// May text be inserted at `at`? — the opening guard of `0x77bee0` (§6.4).
-    ///
-    /// Refused exactly when the entry at the cursor carries bit 31 **and** the previous token's entry
-    /// carries it too (`79 16` @`0x77befb`, `0f 88 …` @`0x77bf0d`). That second test is what still
-    /// permits an insert *at* a link's leading edge, where the `|H` entry has the bit but its
-    /// predecessor — the `|c`, or whatever precedes it — does not.
-    ///
-    /// A strictly-interior cursor is reachable only by mouse (§5, `atomic_links = 0`), and the client
-    /// then silently swallows the typing; INFERRED in the note, from the verified guard.
+    /// The opening guard of `0x77bee0`: refused when the entry at the cursor and the previous
+    /// token's both carry bit 31 (`0x77befb`, `0x77bf0d`), so a link's leading edge still accepts.
+    /// Only the mouse (`0x77d0d0`) reaches a cursor inside a link, and the client then drops the
+    /// typing (inferred from the guard).
     pub fn insert_allowed(&self, at: usize) -> bool {
         if !self.entry(at).in_link() {
             return true;
         }
         match self.prev_token(at) {
-            // `85 c0; 7e 12` — cursor <= 0 proceeds.
+            // Cursor 0 proceeds.
             None => true,
             Some(prev) => !self.entry(prev).in_link(),
         }
@@ -702,7 +525,7 @@ impl ClassMap {
 mod tests {
     use super::*;
 
-    /// The note's §6.5 buffer: an epic item link exactly as `0x52adb0` formats one.
+    /// An epic item link as `0x52adb0` formats one.
     ///
     /// ```text
     ///  0        10                  30            44  46
@@ -711,7 +534,7 @@ mod tests {
     /// ```
     const LINK: &str = "|cffa335ee|Hitem:12345:0:0:0|h[Chipped Claw]|h|r";
 
-    /// The same link with ordinary text on both sides — every offset above shifted by 2.
+    /// The same link between ordinary text, every offset shifted by 2.
     const AROUND: &str = "ab|cffa335ee|Hitem:12345:0:0:0|h[Chipped Claw]|h|rcd";
 
     fn kinds(text: &str) -> Vec<(usize, TokenKind<'_>, usize)> {
@@ -738,7 +561,7 @@ mod tests {
             assert_eq!(one(reset).byte_len, 2);
         }
 
-        // All four spellings of class 2, and `\r\n` as ONE token rather than two.
+        // Every spelling of class 2, `\r\n` as one token.
         for (text, len) in [("\n", 1), ("\r", 1), ("\r\n", 2), ("|n", 2), ("|N", 2)] {
             assert_eq!(one(text).kind, TokenKind::LineBreak, "{text:?}");
             assert_eq!(one(text).byte_len, len, "{text:?}");
@@ -784,8 +607,7 @@ mod tests {
 
     #[test]
     fn there_is_no_inline_texture_escape_in_1_12_1() {
-        // `|T…|t` is a later-expansion feature. Here every byte of it is an ordinary character —
-        // the pipes draw, and a client that stripped the run would be inventing a 2.x escape.
+        // `|T…|t` is a later client's escape; in 1.12 every byte of it is an ordinary character.
         let text = "|TInterface\\Icons\\Foo:16:16|t";
         let first = token_at(text, 0).expect("a token");
         assert_eq!(first.kind, TokenKind::Char('|'));
@@ -794,7 +616,6 @@ mod tests {
             token_at(text, 1).expect("a token").kind,
             TokenKind::Char('T')
         );
-        // Nothing in the whole run is anything but an ordinary character.
         assert!(tokens(text).all(|(_, t)| t.class() == TokenClass::Char));
     }
 
@@ -821,8 +642,7 @@ mod tests {
         };
         assert_eq!(rgba.a(), 0xff);
         assert_eq!(rgba.packed(), 0xffff_0000);
-        // The alpha that reaches the vertex is the STRING's, never the escape's: `|c00ff0000`
-        // inside a half-faded FontString draws at 0.5, not 0.0 and not 1.0 (`0x5cceb0`).
+        // The string's alpha reaches the vertex, never the escape's (`0x5cceb0`).
         assert_eq!(rgba.to_f32_at(1.0), [1.0, 0.0, 0.0, 1.0]);
         assert_eq!(rgba.to_f32_at(0.5), [1.0, 0.0, 0.0, 0.5]);
     }
@@ -837,13 +657,13 @@ mod tests {
         // 1. No closing `|h` anywhere after it.
         degraded("|Hitem:12345:0:0:0[Chipped Claw]");
         degraded("|H");
-        // 2. The span is exactly 4 bytes — an empty payload (0x5c2972).
+        // 2. An empty payload (0x5c2972).
         degraded("|H|h[Chipped Claw]|h");
-        // 3. The visible text is empty — another `|h` immediately follows the span (0x5c2992).
+        // 3. Empty visible text: another `|h` follows at once (0x5c2992).
         degraded("|Hitem:12345:0:0:0|h|h");
 
-        // And the near-misses that must still parse: one visible character is enough, and an
-        // unterminated *link* (delimiter present, no close) still opens — the decoder is stateless.
+        // Near misses still open: one visible character is enough, and the stateless decoder
+        // opens a link that never closes.
         assert_eq!(
             token_at("|Hitem:1|h[|h", 0).expect("a token").kind,
             TokenKind::LinkOpen { payload: "item:1" }
@@ -867,7 +687,7 @@ mod tests {
         }
         assert_eq!(next, AROUND.len());
 
-        // The link buffer's shape, spelled out — every index the rest of these tests cite.
+        // The link's shape: every index the other tests cite.
         let ks = kinds(LINK);
         assert_eq!(ks[0].0, 0);
         assert_eq!(ks[0].2, 10);
@@ -895,8 +715,7 @@ mod tests {
         let map = ClassMap::new(LINK);
         for at in 0..=map.text_len() {
             let entry = map.entry(at);
-            // Raised on the class-4 open (10) inclusive, lowered only after the class-5 close, whose
-            // own entry (44) is therefore still tagged. The `|r` at 46 is not.
+            // Set from the open at 10 through the close at 44; the `|r` at 46 is outside.
             let expected = entry.is_token_start() && (10..=44).contains(&at);
             assert_eq!(entry.in_link(), expected, "bit 31 at {at}");
         }
@@ -928,7 +747,6 @@ mod tests {
         assert_eq!(map.next_token(10), 30);
         assert_eq!(map.next_token(44), 46);
         assert_eq!(map.next_token(46), 48);
-        // A fixed point at the terminator, exactly like the client's unguarded add.
         assert_eq!(map.next_token(48), 48);
 
         assert_eq!(map.prev_token(48), Some(46));
@@ -950,7 +768,7 @@ mod tests {
         assert_eq!(map.letters(30, 14), 14, "the visible text alone");
         assert_eq!(map.letters(44, 4), 0, "the |h|r tail");
 
-        // A line break and an escaped pipe are each ONE letter; `\r\n` is one, not two.
+        // A line break and an escaped pipe are one letter each; `\r\n` is one.
         let map = ClassMap::new("a||b\r\nc|nd");
         assert_eq!(map.num_letters(), 7);
         assert_eq!(ClassMap::new(AROUND).num_letters(), 18, "14 + `ab` + `cd`");
@@ -959,18 +777,9 @@ mod tests {
 
     // ── The cursor law ───────────────────────────────────────────────────────────────────────
 
-    /// The note's §6.5, spelled out: cursor 0, one RIGHT, and the whole link is behind you.
-    /// **The oracle cross-check.** wow-re answered RF-0087 §10 by *executing* the real `0x77bb30`
-    /// under Unicorn on this exact buffer and reporting the reachable index sets. These are its
-    /// numbers, verbatim — the strongest evidence this module can carry, because they came from the
-    /// binary running rather than from anyone reading it.
-    ///
-    /// Three things they pin that a reading could plausibly have got backwards: index **0 is**
-    /// reachable (the leading `|c`+`|H…|h` absorb into the first *step*, not off the origin); index
-    /// **30 is reachable in neither mode** — classes 0 and 4 are skipped unconditionally, so a step
-    /// arriving from the left consumes the `[` in the same step, and the cursor can never sit
-    /// between `|h` and `[`; and after the name the stop is **43 in both modes**, never 39 or 41,
-    /// because the trailing `|h|r` absorb **forward** rather than backward onto the `]`.
+    /// The reachable sets the reference's `0x77bb30` produced, executed on this buffer: 30, between
+    /// `|h` and `[`, is reachable in neither mode, and after the name the stop is 43 in both, the
+    /// trailing `|h|r` absorbing forward.
     #[test]
     fn the_reachable_sets_match_the_emulation_oracle() {
         // `[` at 30, `]` at 38, the `d` of the typed text at 43; 51 bytes.
@@ -996,7 +805,6 @@ mod tests {
             }
             assert_eq!(forward, expected, "forward, atomic={atomic}");
 
-            // Backward visits the identical set and returns exactly to 0.
             let mut back = vec![BUF.len()];
             let mut at = BUF.len();
             while at > 0 {
@@ -1009,23 +817,18 @@ mod tests {
             assert_eq!(back, expected, "backward, atomic={atomic}");
         }
 
-        // The refusal predicate, over every offset: exactly 30..=39 — the display text through the
-        // FIRST byte of the closing `|h`. The link's own boundaries accept (10, the `|H` slot, and
-        // 41, the `|r`), and so does 40, a token-interior byte whose slot is zero.
+        // Insertion is refused at exactly 30..=39, the text through the first byte of the closing
+        // `|h`; 40 is that token's zero interior slot.
         let refused: Vec<usize> = (0..=BUF.len())
             .filter(|&i| !map.insert_allowed(i))
             .collect();
         assert_eq!(refused, (30..=39).collect::<Vec<_>>());
     }
 
-    /// The client freezes where we stop (RF-0087 §10): its inner skip loop re-enters past the zero
-    /// guard, and the terminator decodes as a skip class, so a buffer whose last token is `|c` — or
-    /// an unclosed link, when atomic — spins forever. `SetText("|cffffffff")` plus one RIGHT hangs
-    /// 1.12.1. We land on the far end instead; reproducing a freeze is not fidelity.
+    /// A buffer ending in `|c`, or in an unclosed link when atomic, where the client spins forever.
     #[test]
     fn a_trailing_escape_lands_on_the_end_where_the_client_would_hang() {
-        // Each entry is (buffer, the offset where only skip-class tokens remain, whether the
-        // non-atomic walk hangs there too — an unclosed link only traps the atomic one).
+        // (buffer, offset where only skip-class tokens remain, whether the client hangs non-atomic)
         for (buf, from, both_modes) in [
             ("|cffffffff", 0, true),
             ("ab|cffffffff", 2, true),
@@ -1048,8 +851,7 @@ mod tests {
             "past the whole link, not into it"
         );
         assert_eq!(map.advance(48, -1, true), 0, "and back again");
-        // Not ~50 presses: the visible text is 14 characters and the buffer is 48 bytes, yet the
-        // atomic walk has exactly two stops.
+        // The atomic walk has exactly two stops in the 48 bytes.
         assert_eq!(map.advance(0, 5, true), 48, "clamped at the end");
         assert_eq!(map.advance(48, -5, true), 0);
 
@@ -1063,8 +865,8 @@ mod tests {
         assert_eq!(map.advance(50, -1, true), 2, "back over the whole unit");
     }
 
-    /// The mouse path (`atomic_links = 0`, `0x77d2f6`): every visible character is its own stop, and
-    /// no index inside `|cffa335ee`, `|Hitem:…|h`, `|h` or `|r` ever is.
+    /// The mouse path (`0x77d2f6`): every visible character is a stop, and no index inside
+    /// `|cffa335ee`, `|Hitem:…|h`, `|h` or `|r` ever is.
     #[test]
     fn a_non_atomic_walk_stops_on_each_visible_character_and_never_inside_an_escape() {
         let map = ClassMap::new(LINK);
@@ -1081,7 +883,6 @@ mod tests {
         let expected: Vec<usize> = std::iter::once(0).chain(31..=43).chain([48]).collect();
         assert_eq!(stops, expected);
 
-        // And the same set walking back.
         let mut at = map.text_len();
         let mut back = vec![at];
         while at > 0 {
@@ -1091,7 +892,6 @@ mod tests {
         back.reverse();
         assert_eq!(back, expected);
 
-        // Spelled out: no stop lands inside any escape's byte span.
         for &stop in &stops {
             assert!(
                 !(1..10).contains(&stop)
@@ -1107,8 +907,7 @@ mod tests {
         }
     }
 
-    /// The canonical reachable set of §6.1: **a token boundary with every adjacent zero-width escape
-    /// absorbed — after any trailing `|r`/`|h`, before any leading `|c`/`|H`.**
+    /// The reachable set (`0x77bb30`): boundaries not before a `|r`/`|h` nor after a `|c`/`|H`.
     fn reachable_set(text: &str) -> Vec<usize> {
         let map = ClassMap::new(text);
         (0..=map.text_len())
@@ -1133,9 +932,8 @@ mod tests {
             .collect()
     }
 
-    /// The property sweep: whatever sequence of steps you take, in either direction, at either
-    /// atomicity, you can only ever land in the set above — so no index inside an escape is
-    /// representable as a cursor position. And non-atomically the whole set is reachable.
+    /// Any walk, either way, at either atomicity, lands only in the reachable set, and the walks
+    /// reach all of it.
     #[test]
     fn every_index_any_walk_can_reach_is_a_boundary_with_its_escapes_absorbed() {
         for text in [LINK, AROUND] {
@@ -1172,8 +970,8 @@ mod tests {
         }
     }
 
-    /// The two degenerate ends the guard owns: a step that runs out of buffer while skipping escapes
-    /// lands on the far end rather than spinning (ours, not the note's — see [`ClassMap::advance`]).
+    /// A step that runs out of buffer while skipping lands on the far end, the deviation on
+    /// [`ClassMap::advance`].
     #[test]
     fn a_step_that_runs_out_of_buffer_lands_on_the_far_end() {
         let map = ClassMap::new("ab|cffff0000");
@@ -1186,7 +984,6 @@ mod tests {
         let map = ClassMap::new("|rab");
         assert_eq!(map.advance(2, -1, true), 0, "nothing precedes the |r");
         assert_eq!(map.advance(0, 1, true), 2);
-        // And at the extremes nothing moves.
         let map = ClassMap::new(LINK);
         assert_eq!(map.advance(0, -1, true), 0);
         assert_eq!(map.advance(48, 1, true), 48);
@@ -1198,8 +995,7 @@ mod tests {
     #[test]
     fn deleting_any_byte_of_a_link_widens_to_the_whole_unit() {
         let map = ClassMap::new(AROUND);
-        // Anything touching the visible text takes the |c, the |H…|h, the |h and the |r with it,
-        // leaving exactly `abcd`.
+        // Touching the visible text takes the whole `|c…|r` unit, leaving `abcd`.
         for range in [33..38, 32..46, 33..34, 2..40, 12..46] {
             let snapped = map.snap_delete_range(range.clone());
             assert_eq!(snapped, 2..50, "{range:?}");
@@ -1216,31 +1012,28 @@ mod tests {
         assert_eq!(map.snap_delete_range(35..52), 2..52);
     }
 
-    /// The endpoint tests read the class array directly, so an exclusive end that merely abuts the
-    /// link's first tagged byte still widens. Faithful to `83 3c 86 00` @`0x77c59d`.
+    /// An exclusive end on the link's first tagged byte still widens (`0x77c59d`).
     #[test]
     fn a_deletion_ending_on_the_links_open_still_takes_the_link() {
         let map = ClassMap::new(AROUND);
         assert_eq!(map.snap_delete_range(0..12), 0..50);
-        // Whereas ending on the `|c` — which is not tagged — does not.
+        // Ending on the untagged `|c` does not.
         assert_eq!(map.snap_delete_range(0..2), 0..2);
     }
 
     #[test]
     fn insertion_is_refused_strictly_inside_a_links_visible_text() {
         let map = ClassMap::new(LINK);
-        // Everywhere outside the link.
         assert!(map.insert_allowed(0), "before the leading |c");
         assert!(map.insert_allowed(46), "between the |h and the |r");
         assert!(map.insert_allowed(48), "at the end of the buffer");
         // The leading edge: the |H entry carries bit 31, its predecessor the |c does not.
         assert!(map.insert_allowed(10), "at the link's leading edge");
-        // Strictly inside: refused at every byte from the first visible character through the
-        // closing |h, whose entry is still tagged.
+        // Refused from the first visible character through the tagged closing |h.
         for at in 30..=44 {
             assert!(!map.insert_allowed(at), "inside the link at {at}");
         }
-        // And in particular at every cursor position a mouse click can actually produce.
+        // Including every position a mouse click can produce.
         for at in reachable_set(LINK) {
             assert_eq!(
                 map.insert_allowed(at),
@@ -1259,12 +1052,10 @@ mod tests {
 
     #[test]
     fn no_primitive_can_return_an_index_inside_a_character() {
-        // Multi-byte text before, inside and after the link — 2- and 3-byte characters throughout.
         let text = "héllo |cffa335ee|Hitem:1:0:0:0|h[Épée ✚]|h|r né";
         let map = ClassMap::new(text);
         assert_eq!(map.text_len(), text.len());
 
-        // Every token start, and every index any primitive yields, is a character boundary.
         for (at, token) in tokens(text) {
             assert!(text.is_char_boundary(at), "token start {at}");
             assert!(text.is_char_boundary(at + token.byte_len), "token end {at}");
@@ -1289,17 +1080,14 @@ mod tests {
             let snapped = map.snap_delete_range(at..map.text_len());
             assert!(text.is_char_boundary(snapped.start));
             assert!(text.is_char_boundary(snapped.end));
-            // `String::replace_range` panics unless both ends are character boundaries, so a
-            // snapped range that cut a character in half fails here rather than corrupting.
+            // `replace_range` panics on a range that cuts a character.
             let mut left = text.to_owned();
             left.replace_range(snapped, "");
         }
 
-        // The multi-byte characters are letters like any other: `héllo ` = 6, `[Épée ✚]` = 8,
-        // ` né` = 3.
+        // One letter per character: `héllo ` 6, `[Épée ✚]` 8, ` né` 3.
         assert_eq!(map.num_letters(), 17);
-        // And an atomic step still crosses the whole link in one, from `héllo `'s end to ` né`'s
-        // start, whatever the byte widths in between.
+        // One atomic step still crosses the whole link.
         let open = text.find("|cffa335ee").expect("the colour push");
         let after = text.find("|r").expect("the reset") + 2;
         assert_eq!(map.advance(open, 1, true), after);
diff --git a/crates/benilla-ui/src/messages.rs b/crates/benilla-ui/src/messages.rs
index 209a986e..4dfc3d4a 100644
--- a/crates/benilla-ui/src/messages.rs
+++ b/crates/benilla-ui/src/messages.rs
@@ -1,108 +1,60 @@
-//! The client's **message catalog** — the one table that decides where a UI message is shown.
-//!
-//! Every user-visible refusal, notice and confirmation the engine raises goes through a single
-//! function, `CGGameUI::DisplayError` (`0x496720`), which takes a **message id** and nothing else.
-//! The id indexes the registry at `0xb4b498`, 465 records of 20 bytes:
-//!
-//! | offset | field | what it is |
-//! |---|---|---|
-//! | `+0x00` | [`MessageRecord::key`] | the `GlobalStrings.lua` key, resolved by `FrameScript_GetText` |
-//! | `+0x04` | [`MessageRecord::kind`] | **where it goes** — the four-way jump at `0x496888` ([`MsgKind`]) |
-//! | `+0x08` | [`MessageRecord::sound`] | a sound cue name, or nothing |
-//! | `+0x0c` | [`MessageRecord::type_tag`] | `0x44` = play the cue; anything else is an error-speech id |
-//! | `+0x10` | [`MessageRecord::chat_type`] | the chat type handed to `0x49a870` — read on [`MsgKind::Chat`] only |
-//!
-//! **Why this table is in the tree at all.** benilla names ~160 of these keys across a dozen
-//! modules, and until now every one of them arrived by hand-tracing a `push <id>; call 0x496720`
-//! in the binary and reading the record by eye — the key *and* the surface, carried separately to
-//! the call site, with nothing checking they agreed. That is how [`super::script`]'s petition lines
-//! got their split wrong on the first try (`ui_petition::lines`' own module doc records it), and
-//! it is a tax on every future message. The registry is a **fact about the client**, of exactly the
-//! kind this project already carries as code — opcode numbers, struct offsets, DBC schemas — so it
-//! belongs here as a table, once, instead of being re-derived per call site. Nothing localized
-//! ships with it: the *keys* are `GlobalStrings.lua` identifiers (interface code, decision 1602)
-//! and the text itself is still read at runtime out of the player's own install.
-//!
-//! It is **generated**, never hand-edited — `scripts/gen-message-catalog.py` from wow-5875-re's
-//! `re/ui/message-catalog.tsv`, whose extractor decodes the CRT static initializer
-//! `[0x484ca0, 0x488408)` that fills the table.
-//!
-//! **What the sweep settles that guessing could not:** the split does not follow the key names.
-//! `ERR_PETITION_SIGNED_S` is a chat line and `ERR_PETITION_ALREADY_SIGNED` is a red toast;
-//! `ERR_FISH_ESCAPED` is yellow and `ERR_INV_FULL` is red. 170 rows are [`MsgKind::Chat`], 28 are
-//! [`MsgKind::Info`], 267 are [`MsgKind::Error`] — and **none is the console arm**, which the
-//! dispatcher has and this build's table never reaches (`0x63cb50`'s console lines are called
-//! directly, not through a record), so [`MsgKind`] models three.
+//! The client's message catalog: `CGGameUI::DisplayError` (`0x496720`) takes only a message id,
+//! and the id's 20-byte record in the 465-row table at `0xb4b498` names the `GlobalStrings.lua`
+//! key, where it is shown and its sound. The rows are generated by
+//! `scripts/gen-message-catalog.py` from `reference/1.12-message-catalog.tsv`, decoded from the
+//! table's static initializer `[0x484ca0, 0x488408)`; the text itself is read from the install.
 
 mod catalog;
 
 pub use catalog::CATALOG;
 
-/// Where a message is shown — the record's `+0x04`, as the four-way jump at `0x496888` reads it.
-///
-/// The reference's fourth arm (`3` → the debug console `0x63cd00`) has **no tenant in 5875's
-/// table**: no row carries it, so modelling it would be modelling something that cannot happen.
-/// The generator refuses a kind it does not know, so a build whose table did use it would fail
-/// loudly here rather than silently pick a surface.
+/// Where a message is shown: the record's `+0x04`, as the jump at `0x496888` reads it. Its fourth
+/// arm, `3` (the console `0x63cd00`), has no row in this build's table (console lines call
+/// `0x63cb50` directly), and the generator refuses a kind it does not know.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum MsgKind {
-    /// `0` → the chat window, through the shared composer `0x49a870` with the record's own
-    /// [`MessageRecord::chat_type`].
+    /// `0`: a chat-window line through the composer `0x49a870`, on the record's `chat_type`.
     Chat,
-    /// `1` → `AddErrorMessage(text, 0)`, which fires `UI_INFO_MESSAGE` (`0xe1`) — the **yellow**
-    /// `UIErrorsFrame` line.
+    /// `1`: `AddErrorMessage(text, 0)`, `UI_INFO_MESSAGE` (`0xe1`), yellow in `UIErrorsFrame`.
     Info,
-    /// `2` → `AddErrorMessage(text, 1)`, which fires `UI_ERROR_MESSAGE` (`0xe0`) — the **red**
-    /// `UIErrorsFrame` line. The commonest by a wide margin, which is exactly why guessing it
-    /// usually works and is not good enough.
+    /// `2`: `AddErrorMessage(text, 1)`, `UI_ERROR_MESSAGE` (`0xe0`), red in `UIErrorsFrame`.
     Error,
 }
 
 /// One row of `0xb4b498`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MessageRecord {
-    /// The message id — the argument `DisplayError` is called with, and this row's index.
+    /// The id `DisplayError` takes, and this row's index.
     pub id: u16,
-    /// The `GlobalStrings.lua` key whose text is displayed. An absent or empty string shows
-    /// nothing at all: the reference's own data-suppression face (`0x4967bd`/`0x4967c5`).
+    /// `+0x00`, the `GlobalStrings.lua` key; an absent or empty string shows nothing
+    /// (`0x4967bd`/`0x4967c5`).
     pub key: &'static str,
-    /// Where it is shown.
+    /// `+0x04`, where it is shown.
     pub kind: MsgKind,
-    /// The sound cue played with it, or `None` for the 435 silent rows. Read at the display, by
-    /// `benilla_app::sound::message` (decision 1815).
+    /// `+0x08`, the sound cue; `None` on the 435 silent rows.
     pub sound: Option<&'static str>,
-    /// `+0x0c`. `0x44` means "play [`Self::sound`]"; the other 56 rows carry an error-speech line
-    /// id instead, spoken in the player's own race and gender voice (decision 1815).
+    /// `+0x0c`: `0x44` plays [`Self::sound`]; the other 56 rows carry an error-speech id, spoken
+    /// in the player's race and gender voice.
     pub type_tag: u8,
-    /// The chat type handed to the composer, meaningful for [`MsgKind::Chat`] rows only. `10`
-    /// (`CHAT_MSG_SYSTEM`) for all but three — the skill-up trio `ERR_PROFICIENCY_GAINED_S`,
-    /// `ERR_SKILL_GAINED_S` and `ERR_SKILL_UP_SI` speak on `23` (`CHAT_MSG_SKILL`).
+    /// `+0x10`, read on [`MsgKind::Chat`] rows only: `10` (`CHAT_MSG_SYSTEM`), except `23`
+    /// (`CHAT_MSG_SKILL`) on the skill-up rows `ERR_PROFICIENCY_GAINED_S`, `ERR_SKILL_GAINED_S`
+    /// and `ERR_SKILL_UP_SI`.
     pub chat_type: u8,
 }
 
-/// The record for a message id, or `None` past the table's end — the reference's own bound, the
-/// `cmp id,0x1d1; jge` at `0x49672c`.
+/// The record for a message id; the table ends at the reference's bound, `cmp id,0x1d1` at
+/// `0x49672c`.
 pub fn by_id(id: u16) -> Option<&'static MessageRecord> {
     CATALOG.get(usize::from(id))
 }
 
-/// The record for a `GlobalStrings` key. Keys are unique across the table (the generator refuses a
-/// duplicate), so this is well defined.
-///
-/// A linear scan, deliberately: this is reached once per *displayed message* — a toast, a system
-/// line — which is a handful per second at the very worst, and a sorted side-table would be one
-/// more generated thing to keep true for no measurable gain.
+/// The record for a `GlobalStrings` key; keys are unique (the generator refuses a duplicate).
 pub fn by_key(key: &str) -> Option<&'static MessageRecord> {
     CATALOG.iter().find(|r| r.key == key)
 }
 
-/// Where a message goes, by key — the one question nearly every caller has.
-///
-/// A key with no row falls back to [`MsgKind::Error`]. That case cannot arise in the reference (a
-/// message is an *index*, so an unknown key is not expressible), so it only ever means benilla
-/// named a key the client does not have; the red line is both the commonest kind and the most
-/// visible place for such a mistake to show itself. `benilla-app`'s
-/// `every_error_key_in_the_source_is_a_catalog_row` test is what keeps it unreachable.
+/// Where a message goes, by key. A key with no row is a benilla typo, never a reference state
+/// (the reference addresses messages by index), and falls back to the red line.
 pub fn kind_of(key: &str) -> MsgKind {
     by_key(key).map_or(MsgKind::Error, |r| r.kind)
 }
@@ -111,7 +63,6 @@ pub fn kind_of(key: &str) -> MsgKind {
 mod tests {
     use super::*;
 
-    /// The table is complete and dense, so `CATALOG[id]` is the reference's own addressing.
     #[test]
     fn ids_are_dense_and_the_table_is_whole() {
         assert_eq!(CATALOG.len(), 465);
@@ -121,7 +72,6 @@ mod tests {
         assert!(by_id(465).is_none(), "the reference bounds at 0x1d1");
     }
 
-    /// Keys are unique — [`by_key`] would otherwise be answering an ambiguous question.
     #[test]
     fn keys_are_unique() {
         let mut keys: Vec<&str> = CATALOG.iter().map(|r| r.key).collect();
@@ -131,9 +81,6 @@ mod tests {
         assert_eq!(keys.len(), n);
     }
 
-    /// **The split does not follow the key names.** Four rows that a re-implementation reading
-    /// English would sort differently than the binary does — the petition pair that was actually
-    /// got wrong once, and the fishing verdict that sits one id away from two red neighbours.
     #[test]
     fn the_surface_is_not_guessable_from_the_key() {
         assert_eq!(kind_of("ERR_PETITION_SIGNED_S"), MsgKind::Chat);
@@ -142,7 +89,6 @@ mod tests {
         assert_eq!(kind_of("ERR_INV_FULL"), MsgKind::Error);
     }
 
-    /// The three rows that speak on a chat type other than `CHAT_MSG_SYSTEM`.
     #[test]
     fn the_skill_up_rows_speak_on_chat_msg_skill() {
         for key in [
@@ -157,8 +103,6 @@ mod tests {
         assert_eq!(by_key("ERR_QUEST_ALREADY_ON").unwrap().chat_type, 10);
     }
 
-    /// A key the client does not have is not expressible as a message id; the fallback exists so
-    /// that a benilla typo is loud rather than silent.
     #[test]
     fn an_unknown_key_falls_back_to_the_red_line() {
         assert!(by_key("ERR_NOT_A_REAL_MESSAGE").is_none());
diff --git a/crates/benilla-ui/src/messages/catalog.rs b/crates/benilla-ui/src/messages/catalog.rs
index a9053e54..2f61414e 100644
--- a/crates/benilla-ui/src/messages/catalog.rs
+++ b/crates/benilla-ui/src/messages/catalog.rs
@@ -1,17 +1,14 @@
-//! The 5875 message catalog, row for row.
+//! The 1.12 client's message catalog, row for row.
 //!
-//! @generated by `scripts/gen-message-catalog.py` from wow-5875-re `re/ui/message-catalog.tsv`
-//! (itself generated by that repo's `re/ui/extract-message-catalog.py` out of `WoW.exe`).
-//! Do not edit by hand — regenerate.
+//! @generated by `scripts/gen-message-catalog.py` from `reference/1.12-message-catalog.tsv`.
+//! Do not edit by hand; regenerate.
 
 use super::{MessageRecord, MsgKind};
 
-/// Every row of `0xb4b498`, indexed by message id (the ids are dense `0..465`, so
-/// `CATALOG[id]` *is* the reference's `0xb4b498 + 20*id`).
+/// Every row of `0xb4b498`, indexed by message id: the ids are dense `0..465`, so `CATALOG[id]`
+/// is the reference's `0xb4b498 + 20*id`.
 ///
-/// `rustfmt` is held off so that a regeneration is a no-op diff: one row per line is the shape
-/// this script emits, and a formatter that rewrapped it would make the file drift from its own
-/// generator.
+/// `rustfmt` is off: the generator emits one row per line, and a rewrap would drift from it.
 #[rustfmt::skip]
 pub static CATALOG: [MessageRecord; 465] = [
     MessageRecord { id: 0, key: "ERR_INV_FULL", kind: MsgKind::Error, sound: None, type_tag: 0x00, chat_type: 10 },
diff --git a/crates/benilla-ui/src/order.rs b/crates/benilla-ui/src/order.rs
index dfc60077..db089796 100644
--- a/crates/benilla-ui/src/order.rs
+++ b/crates/benilla-ui/src/order.rs
@@ -1,94 +1,48 @@
-//! The draw-order primitive — the strata/layer vocabulary and the packed total-order key
-//! (`ZKey`), plus the visible-tree [`traversal`] that realizes the client's painter order
-//! (decision 0068).
+//! Draw order: the strata and draw-layer vocabulary, the packed total-order key [`ZKey`], and the
+//! visible-tree [`traversal`] in the client's painter order.
 //!
-//! ## Ground truth (wow-5875-re, binary-verified)
+//! The 1.12 client draws in one flat painter's order, not a tree walk: every visible frame, child
+//! or not, is an entry in a per-`(strata, level)` bucket (`root+0xcd4`), so a child with a lower
+//! strata or level draws before its parent. Inside a bucket the draw layer outranks the frame: the
+//! five layer batches belong to the level node (`levelNode+0x1c`), and the emitter `0x765920` loops
+//! layers outside and frames inside, so every frame's BACKGROUND draws before any frame's BORDER.
+//! Within a layer, `0x76fb00` drains every quad, then every string, then the render callbacks.
 //!
-//! The 1.12.1 client draws in a **flat painter's order**, *not* a hierarchical walk: every visible
-//! frame — children included — is an independent entry in a per-`(strata, level)` bucket
-//! (`propagation.md`, `propagation-anchors.md`). A child frame with a *lower* strata/level than its
-//! parent therefore draws *before* the parent — the order is global, keyed on the tuple below, not
-//! on the tree shape.
+//! The frame term is the client's live intrusive-list position: a frame relinks at its bucket's
+//! tail when shown and when a shown frame's strata or level changes, and the later link draws on
+//! top. [`crate::widget::WidgetArena`] keeps a counter bumped at those moments, which orders the
+//! same within a bucket. The is-region bit is benilla's: the client has no frame drawable, and the
+//! frame's own slot (backdrop, scissor) must precede its regions.
 //!
-//! **Inside one `(strata, level)` bucket, the DRAW LAYER outranks the frame.** The five render
-//! batches belong to the level node (`levelNode+0x1c`), not to any frame, and the emitter
-//! `0x765920` loops `layer = 0..4` outside and frames inside. So a bucket emits every frame's
-//! BACKGROUND, then every frame's BORDER, and so on — regions are *not* grouped behind their owning
-//! frame. Within one layer the same is true of kind: the batch holds a quad sub-array and a text
-//! sub-array, and `0x76fb00` drains all quads before any text, so **all** textures of a
-//! `(strata, level, layer)` precede **all** its font strings. (Decision 0884, wow-re
-//! `ui/scratch/draw-order-law.md`. This supersedes the earlier recorded key, which had no layer
-//! term at all and read the last term backwards.)
-//!
-//! ## The total order (most- to least-significant)
-//!
-//! `(stratum, frame level, draw layer, batch rank quad<text<callback, frame link-stamp, is-region,
-//! sub-level, declaration order)` — packed big-endian-by-priority into one sortable [`ZKey`] (`u64`), so the
-//! whole render list is produced by one sort on the key. The `is-region` bit is benilla's own: the
-//! binary has no frame-level drawable (only regions draw), so it sits *below* the layer key purely
-//! to keep a frame's backdrop/scissor slot ahead of that frame's own regions.
-//!
-//! The **link-stamp** is the client's live intrusive-list position, not a creation index: a frame is
-//! (re)linked at its bucket on becoming visible, on a strata change, and on a *changing* level set
-//! — later link = drawn on top. A monotonic global counter bumped at those same moments is
-//! order-equivalent within any one bucket, which is what [`crate::widget::WidgetArena`] keeps.
-//!
-//! **Below the layer, the frame term is exact for font strings and a deterministic stand-in for
-//! textures.** The client re-sorts each layer's quad array by *texture handle* (`0x7731a0`) and
-//! never sorts the text sub-array. A texture handle is an internal allocation our texture manager
-//! assigns differently, so we reproduce the client's pre-sort array instead — identical wherever a
-//! layer's quads share a texture or don't overlap. **No content may depend on the relative order of
-//! two overlapping textures within one layer.**
-//!
-//! ## Era deltas (designed-for, not invented)
-//!
-//! - **`BLIZZARD` stratum** — the modern engine adds exactly one stratum *above* `TOOLTIP`
-//!   (decision 0068 §"strict superset"; the 1.12 `UI.xsd`↔Era diff). It is the last [`Strata`]
-//!   variant; 1.12 content never selects it.
-//! - **`textureSubLevel`** — an i8 ordering knob *within* a draw layer, first-class in Era. 0884's
-//!   §5 found **no sub-level in 5875 at all** (`0x76a860` takes only `(region, layer)` and
-//!   head-inserts with no comparator; the per-layer header is a plain 0xc-byte triple with nowhere
-//!   to keep a sort key), correcting the earlier note that placed one in the 1.12 region lists. The
-//!   `sub_level` field stays as the Era delta and is inert for 1.12 content.
+//! Deviation: textures in one layer keep link order where the client sorts them by texture handle
+//! (`0x7731a0`, comparator `0x7731c0`), because benilla allocates its handles differently; no
+//! content may depend on the order of two overlapping textures in one layer.
 
 use crate::widget::{FrameHandle, RegionHandle, RegionKind, WidgetArena};
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Strata — the top-level draw buckets
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Strata: the top-level draw buckets ───────────────────────────────────────────────────────
 
-/// The frame strata, in draw order (low → high). Variants 0..=8 are the client's nine
-/// buckets, byte-verified in the `CSimpleTop` ctor's 9-loop (`propagation.md`): WORLD, BACKGROUND,
-/// LOW, MEDIUM (the default, id 3), HIGH, DIALOG, FULLSCREEN, FULLSCREEN_DIALOG, TOOLTIP. `BLIZZARD`
-/// (id 9) is the one stratum the modern engine adds *above* TOOLTIP (decision 0068) — an
-/// extension point, never selected by 1.12 content.
+/// The frame strata in draw order; `World` through `Tooltip` are the client's nine buckets (the
+/// `CSimpleTop` constructor's loop at `0x764180`).
 #[repr(u8)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Strata {
-    /// id 0 — behind everything (the 3D world layer).
+    /// The 3D world, behind everything.
     World = 0,
-    /// id 1.
     Background = 1,
-    /// id 2.
     Low = 2,
-    /// id 3 — the client default (`frameStrata` ctor value `3`, `frame-model.md`).
     Medium = 3,
-    /// id 4.
     High = 4,
-    /// id 5.
     Dialog = 5,
-    /// id 6.
     Fullscreen = 6,
-    /// id 7.
     FullscreenDialog = 7,
-    /// id 8 — topmost in 1.12.
     Tooltip = 8,
-    /// id 9 — **Era addition**, drawn above `Tooltip` (decision 0068). No 1.12 content uses it.
+    /// A later client's stratum above `Tooltip`, not a 1.12 one.
     Blizzard = 9,
 }
 
 impl Strata {
-    /// Every stratum in draw order (low → high).
+    /// Every stratum in draw order.
     pub const ALL: [Strata; 10] = [
         Strata::World,
         Strata::Background,
@@ -102,7 +56,7 @@ impl Strata {
         Strata::Blizzard,
     ];
 
-    /// The client bucket id (0..=9).
+    /// The client bucket id.
     #[inline]
     pub const fn index(self) -> u8 {
         self as u8
@@ -110,33 +64,26 @@ impl Strata {
 }
 
 impl Default for Strata {
-    /// `MEDIUM` — the client's default `frameStrata` (ctor writes `3`, `frame-model.md`).
+    /// The frame constructor writes 3 (`0x7690c2`).
     fn default() -> Strata {
         Strata::Medium
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Draw layers — the within-frame region order
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Draw layers ──────────────────────────────────────────────────────────────────────────────
 
-/// The five draw layers a region sits in, in draw order (`frame-model.md`, the frame's five
-/// region lists ~`0x1c0`): BACKGROUND, BORDER, ARTWORK, OVERLAY, HIGHLIGHT.
+/// The five draw layers, in draw order (the reference's five region lists near `0x1c0`).
 #[repr(u8)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum DrawLayer {
-    /// Drawn first (behind the frame's other regions).
     Background = 0,
     Border = 1,
-    /// The default layer for a texture/fontstring with no explicit `<Layer>`.
     Artwork = 2,
     Overlay = 3,
-    /// Drawn last (mouse-over highlights).
     Highlight = 4,
 }
 
 impl DrawLayer {
-    /// The layer index (0..=4).
     #[inline]
     pub const fn index(self) -> u8 {
         self as u8
@@ -144,117 +91,64 @@ impl DrawLayer {
 }
 
 impl Default for DrawLayer {
-    /// `ARTWORK` — the layer a texture/fontstring with no explicit `<Layer>` lands in.
+    /// The layer of a texture or font string with no `<Layer>`.
     fn default() -> DrawLayer {
         DrawLayer::Artwork
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// ZKey — the packed total-order key
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── ZKey: the packed total-order key ─────────────────────────────────────────────────────────
 //
-// Bit layout (u64), most-significant field = highest draw priority. The whole render list is a
-// single ascending sort on this key.
+// Most significant first; one ascending sort gives the render list.
 //
-//   bits 60..=63 (4)   stratum          Strata::index() 0..=9   (< 16)
-//   bits 44..=59 (16)  frame level      u16                     (< 65536)
-//   bits 41..=43 (3)   draw layer       DrawLayer::index() 0..=4 (< 8)
-//   bit  40      (1)   fontstring       0 = texture, 1 = fontstring — BUCKET-WIDE, above the frame
-//   bits 21..=39 (19)  frame link-stamp monotonic (re)link seq   (< 524288)
-//   bit  20      (1)   is-region        0 = the frame itself, 1 = one of its regions
-//   bits 12..=19 (8)   sub-level        i8 biased by +128        (0..=255) — INERT on 1.12
-//   bits  0..=11 (12)  declaration seq  region index within its owner frame (< 4096)
+//   bits 60..=63 (4)   stratum           Strata::index()
+//   bits 44..=59 (16)  frame level       u16
+//   bits 41..=43 (3)   draw layer        DrawLayer::index()
+//   bits 39..=40 (2)   batch rank        BatchRank: quad, text, callback
+//   bits 21..=38 (18)  frame link-stamp  the (re)link sequence
+//   bit  20      (1)   is-region         0 for the frame's own slot, 1 for a region
+//   bits 12..=19 (8)   sub-level         i8 biased by +128
+//   bits  0..=11 (12)  declaration seq   the region's index within its owner frame
 //
-// ## Why the draw layer outranks the frame (decision 0884 — §5-VERIFIED)
+// Stock content relies on the layer outranking the frame: a child is born at its parent's level
+// plus 1 (`SetParent` `0x76ab10`, at `0x76ab65`), `MirrorTimer.xml:62` lowers the bar by 1 to tie
+// its parent, and the tie lets the bar's ARTWORK fill draw under the parent's OVERLAY border.
 //
-// **The five render batches belong to the LEVEL NODE, not to the frame** (`levelNode+0x1c`, five
-// 0x30-byte batches), and the emitter `0x765920` loops `layer = 0..4` on the OUTSIDE and frames on
-// the inside. So the draw layer is a **bucket-wide** key: every frame sharing a `(strata, level)`
-// emits its BACKGROUND regions, then every frame its BORDER, then ARTWORK, then OVERLAY, then
-// HIGHLIGHT. It is not a within-frame ordering — which is what benilla modeled until 0884, with
-// the frame term ranked above the layer so a frame's regions stayed glued behind it.
-//
-// That inversion is what put the mirror timer's blue fill over its own border art and caption
-// (director report, 2026-08-02). The reference builds those bars as a Frame whose OVERLAY layer
-// carries the border + caption, with a child StatusBar whose `<BarTexture>` takes the default
-// **ARTWORK** layer and whose only OnLoad is `SetFrameLevel(GetFrameLevel() - 1)`. That line does
-// **not** put the child below the parent: a child is born at `parent.level + 1` (`SetParent
-// 0x76ab10` @`0x76ab65`), so the `-1` lands it at *exactly* the parent's level. Its whole job is to
-// **create the tie**, so the layer key can decide — ARTWORK(2) before OVERLAY(3), fill under
-// chrome. Ranked below the frame, there was no tie to resolve and the child always trailed.
-//
-// **`texture < fontstring` is bucket-wide too, and outranks the frame.** A layer's batch holds two
-// independent sub-arrays — the quad array `[batch+0x10]` (every `CSimpleTexture` appends via
-// `0x7706e0` → `0x772fd0`) and the text sub-batch `[batch+0x18]` (`0x772e50` → `0x773080`) — and
-// `0x76fb00` drains the WHOLE quad array before it touches the text one. So for two frames A, B at
-// one `(strata, level, layer)`, each with a texture and a font string, the client emits
-// `A.tex, B.tex, A.text, B.text` — never `A.tex, A.text, B.tex, B.text`.
-//
-// **The frame link-stamp below that is exact for font strings and a deterministic stand-in for
-// textures.** The client re-sorts a layer's quad array by *texture handle* (`0x7731a0`'s qsort,
-// comparator `0x7731c0`) and never sorts the text sub-batch. The handle is an internal allocation
-// our texture manager assigns differently, so reproducing that sort is neither achievable nor
-// desirable; we reproduce the client's PRE-sort array, which agrees wherever a layer's quads share
-// a texture or don't overlap (the common case). **No content may depend on the relative order of
-// two overlapping textures within one layer** — that is not a fidelity invariant.
-//
-// wow-re's own previously-recorded key — `(strata, level, insertion order)` — is superseded by the
-// same §5: it carried no layer term at all.
-//
-// A frame's own entry zeroes the layer and everything below `is-region`, so it precedes its own
-// BACKGROUND regions. That slot is benilla's backdrop/scissor hook, not the client's — in the
-// binary a frame has no drawable of its own — so it sits *below* the layer key, never above it.
-//
-// **`sub-level` is inert on 1.12**: §5 found no sub-level in 5875 at all (`0x76a860` takes only
-// `(region, layer)`, head-inserts with no comparator, and the per-layer header is a plain 0xc-byte
-// triple with nowhere to keep a sort key). The field stays as the modeled Era delta; no 1.12
-// content sets it, so it is always the `0` bias.
+// The sub-level is a later client's ordering within a layer, not 1.12's, which has none
+// (`0x76a860` takes only region and layer and inserts at the head); stock content never sets it.
 
 const STRATUM_SHIFT: u32 = 60;
 const LEVEL_SHIFT: u32 = 44;
 const LAYER_SHIFT: u32 = 41;
-/// The batch RANK within a `(strata, level, layer)`: the three sub-arrays a layer batch carries and
-/// the order `0x76fb00` drains them — its quads (`+0x10`), its string batch (`+0x18`), then its
-/// render-callback list (`+0x1c`; wow-re `ui/scratch/model-frame-draw-order.md`, decision 1995).
-/// Two bits at 39..40, where the one font-string bit used to be; the link stamp below lost a bit
-/// for it (18, from 19 — the arena renumbers at the cap either way).
 const RANK_SHIFT: u32 = 39;
 const INSERTION_SHIFT: u32 = 21;
 const IS_REGION_SHIFT: u32 = 20;
 const SUBLEVEL_SHIFT: u32 = 12;
 const DECL_SHIFT: u32 = 0;
 
+/// The link-stamp width; the arena renumbers its stamps at the cap.
 pub(crate) const INSERTION_BITS: u32 = 18;
 const DECL_BITS: u32 = 12;
 
-/// Which of a layer batch's three sub-arrays an entry drains from — in the order `0x76fb00` drains
-/// them. The client keeps them as three arrays on one batch object (ctor `0x772e80`: quads at
-/// `+0x10`, the `CGxStringBatch` at `+0x18`, a `RENDERCALLBACKNODE` list at `+0x1c`) and empties
-/// them in this order, so within one `(strata, level, layer)` every texture precedes every font
-/// string, and every font string precedes every model scene (wow-re
-/// `ui/scratch/model-frame-draw-order.md`; decision 1995).
+/// Which of a layer batch's arrays an entry drains from, in `0x76fb00`'s order: quads at `+0x10`
+/// (a texture appends at `0x7706e0`), a `CGxStringBatch` at `+0x18` (a font string at `0x772e50`)
+/// and a render-callback list at `+0x1c` (ctor `0x772e80`). So in one `(strata, level, layer)`
+/// every texture precedes every font string, and every font string every model scene.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(u8)]
 pub enum BatchRank {
-    /// A texture quad — drained first.
     Quad = 0,
-    /// A font string — the string batch, drained second.
     Text = 1,
-    /// A `Model` frame's scene — the callback list, drained last. Registered for ARTWORK only
-    /// (`0x76d17f cmp ebx,2`), which is why [`ZKey::callback`] takes the layer it is asked for
-    /// but a model's is always `ARTWORK`.
+    /// A `Model` frame's scene, registered for ARTWORK only (`0x76d17f`).
     Callback = 2,
 }
 
-/// The packed draw-order key: a single `u64` whose natural `Ord` *is* the client's total draw
-/// order. Build one with [`ZKey::frame`] or [`ZKey::region`]; sort ascending to get painter order.
+/// The packed draw-order key; its `Ord` is the client's draw order.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct ZKey(u64);
 
 impl ZKey {
-    /// The key for a **frame's own** entry — every region-level field is zero, so this sorts before
-    /// all of the frame's regions.
+    /// A frame's own entry; its region fields are zero, so it sorts before its regions.
     pub fn frame(strata: Strata, level: u16, insertion: u32) -> ZKey {
         debug_assert!(
             insertion < (1 << INSERTION_BITS),
@@ -266,9 +160,8 @@ impl ZKey {
         ZKey(bits)
     }
 
-    /// The key for one **region** of a frame. `strata`/`level`/`insertion` are the *owner frame's*
-    /// (so the region stays grouped behind its frame); `is_fontstring` places textures before
-    /// fontstrings at equal (layer, sub-level).
+    /// A region's key; `strata`, `level` and `insertion` are its owner frame's, and
+    /// `is_fontstring` picks the text rank.
     pub fn region(
         strata: Strata,
         level: u16,
@@ -286,7 +179,7 @@ impl ZKey {
             u32::from(decl) < (1 << DECL_BITS),
             "region decl seq {decl} exceeds {DECL_BITS} bits"
         );
-        // sub_level (i8, -128..=127) biased into 0..=255 so higher sub-level sorts later.
+        // Biased into 0..=255 so a higher sub-level sorts later.
         let sub_biased = (i16::from(sub_level) + 128) as u64;
         let bits = (u64::from(strata.index()) << STRATUM_SHIFT)
             | (u64::from(level) << LEVEL_SHIFT)
@@ -304,17 +197,10 @@ impl ZKey {
         ZKey(bits)
     }
 
-    /// The key a frame's own **content** draws at: its bare [`ZKey::frame`] slot promoted into its
-    /// region band at `layer` — behind that layer's textures, ahead of its declared font strings.
-    ///
-    /// Content is what a widget kind draws *itself*, with no region to hang it on — today only a
-    /// ScrollingMessageFrame's ring lines, which the client materializes as the frame's own font
-    /// strings (its `<FontString>` child is their font instance, and a font string with no
-    /// `<Layer>` is `ARTWORK`). At the bare frame slot they sorted before **all** of the frame's
-    /// regions, so the chat window's own `$parentBackground` — a `BACKGROUND` texture, faded in
-    /// on hover — painted over the messages and dimmed them (director, 2026-07-26; the white
-    /// text measured 192, exactly `255 × (1 − 0.25)`, the box's own alpha). The frame slot stays
-    /// what it was — the backdrop/scissor setup that must precede everything the frame owns.
+    /// The key for a frame's own content, text with no region: its frame slot moved into its
+    /// region band at `layer` with the text rank. The content is a ScrollingMessageFrame's lines,
+    /// which the client draws as the frame's own font strings (ARTWORK with no `<Layer>`), so the
+    /// frame's BACKGROUND art stays behind them.
     #[inline]
     #[must_use]
     pub const fn content(self, layer: DrawLayer) -> ZKey {
@@ -322,20 +208,15 @@ impl ZKey {
             self.0
                 | (1u64 << IS_REGION_SHIFT)
                 | ((layer.index() as u64) << LAYER_SHIFT)
-                // Sub-level 0 in the same +128 bias `region` uses, and the text rank: content is
-                // text, so it takes the same textures-draw-first slot a font string would.
+                // Sub-level 0, biased as in `region`.
                 | (128u64 << SUBLEVEL_SHIFT)
                 | ((BatchRank::Text as u64) << RANK_SHIFT),
         )
     }
 
-    /// The key a `Model` frame's **scene** draws at: its bare [`ZKey::frame`] slot promoted into
-    /// its region band at `layer` with the CALLBACK rank — after every texture and every font
-    /// string of that `(strata, level, layer)`, whatever their link stamps. That is the client's
-    /// own place for it: `0x76d160` registers the model's render callback into the layer batch,
-    /// and `0x76fb00` drains the callback list after the quads and the text. Two scenes in one
-    /// bucket keep the link-stamp order below the rank (registration order = FIFO), which the
-    /// bare slot's own insertion carries here (decision 1995).
+    /// The key for a `Model` frame's scene: its frame slot moved into its region band at `layer`
+    /// with the callback rank, after every texture and font string of the layer, as `0x76d160`
+    /// registers the scene into the layer batch whose callbacks `0x76fb00` drains last.
     #[inline]
     #[must_use]
     pub const fn callback(self, layer: DrawLayer) -> ZKey {
@@ -348,49 +229,38 @@ impl ZKey {
         )
     }
 
-    /// The raw packed value (the sort key).
     #[inline]
     pub const fn raw(self) -> u64 {
         self.0
     }
 
-    /// Unpack this key back into its fields.
     #[inline]
     pub const fn parts(self) -> ZParts {
         unpack(self.0)
     }
 }
 
-/// The fields of a packed [`ZKey`], in significance order — the readable face of an opaque `u64`.
-///
-/// A draw-order key is a single number by design (one sort produces the whole render list), which
-/// makes every question *about* an order — "why is this over that?", "which pairs would a re-rank
-/// invert?" — unanswerable at a glance. [`unpack`] is that answer, and it is why
-/// [`crate::script::ExtractedQuad::z`] can stay a bare `u64`.
+/// A [`ZKey`]'s fields, most significant first.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ZParts {
-    /// The frame strata bucket id (0..=9, [`Strata::index`]).
+    /// [`Strata::index`].
     pub strata: u8,
-    /// The frame level within the strata bucket.
     pub level: u16,
-    /// The draw layer (0..=4, [`DrawLayer::index`]) — bucket-wide, above the frame (decision 0884).
+    /// [`DrawLayer::index`].
     pub layer: u8,
-    /// The batch rank: all textures of a `(strata, level, layer)` precede all its text, and all its
-    /// text precedes its model scenes ([`BatchRank`]).
     pub rank: BatchRank,
-    /// `rank == Text` — kept for the readers that only ask the old question.
+    /// `rank == BatchRank::Text`.
     pub is_fontstring: bool,
-    /// The owning frame's link-stamp — its position in the client's intrusive bucket list.
+    /// The owning frame's link-stamp.
     pub insertion: u32,
-    /// `false` for a frame's own slot, `true` for one of its regions.
     pub is_region: bool,
-    /// The Era `textureSubLevel` knob; inert for 1.12 content (always 0 there).
+    /// 0 for stock 1.12 content.
     pub sub_level: i8,
-    /// Declaration order within the owning frame's layer.
+    /// Declaration order within the owning frame.
     pub decl: u16,
 }
 
-/// Unpack a raw [`ZKey`] (e.g. [`crate::script::ExtractedQuad::z`]) into its fields.
+/// A raw [`ZKey`]'s fields, as [`crate::script::ExtractedQuad::z`] stores the key.
 #[inline]
 pub const fn unpack(raw: u64) -> ZParts {
     ZParts {
@@ -410,31 +280,26 @@ pub const fn unpack(raw: u64) -> ZParts {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Traversal — the visible render list in the client's painter order
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Traversal: the visible render list in painter order ──────────────────────────────────────
 
-/// What a [`ZKey`] entry points at: a frame's own draw slot, or one of its regions.
+/// What a [`ZKey`] entry points at.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum ZTarget {
-    /// The frame itself (backdrop/scissor slot) — sorts before its regions.
+    /// The frame's own slot (backdrop, scissor).
     Frame(FrameHandle),
-    /// A texture or fontstring belonging to a frame.
     Region(RegionHandle),
 }
 
-/// The sorted draw list itself — shared, so a frame that changed nothing hands out the same one.
+/// The sorted draw list, shared so an unchanged frame hands out the same one.
 pub type DrawList = std::sync::Arc<[(ZTarget, ZKey)]>;
 
-/// [`traversal`]'s memo: the last walk (arena order) and the sorted list built from it.
+/// [`traversal`]'s memo: the last walk, in arena order, and the sorted list built from it.
 #[derive(Default, Debug)]
 pub struct OrderCache(std::cell::RefCell<Option<OrderMemo>>);
 
-/// The last walk, in arena order, and the sorted list built from it.
 type OrderMemo = (Vec<(ZTarget, ZKey)>, DrawList);
 
-/// Every `(target, key)` of the draw list, in ARENA order — the one walk both the fingerprint
-/// and the rebuild are made of, so they cannot disagree.
+/// Every `(target, key)` of the draw list, in arena order.
 fn walk(arena: &WidgetArena, mut f: impl FnMut(ZTarget, ZKey)) {
     for (fh, frame) in arena.iter_frames() {
         if !frame.effective_visible {
@@ -446,8 +311,7 @@ fn walk(arena: &WidgetArena, mut f: impl FnMut(ZTarget, ZKey)) {
             let Some(region) = arena.region(rh) else {
                 continue;
             };
-            // `Region:SetParent(nil)` orphaned this leaf: unlinked from every draw layer, still
-            // alive (see [`crate::widget::Region::detached`]). It draws nothing until re-parented.
+            // A region orphaned by `SetParent(nil)` is in no draw layer until re-parented.
             if region.detached {
                 continue;
             }
@@ -465,36 +329,14 @@ fn walk(arena: &WidgetArena, mut f: impl FnMut(ZTarget, ZKey)) {
     }
 }
 
-/// Produce the render list in the client's exact `render_traverse_order 0x765650` order.
-///
-/// Only **effective-visible** frames contribute: because `effective_visible` is maintained across
-/// the whole subtree by the arena's propagation (`set_shown`/`set_parent`), filtering on the flag is
-/// equivalent to the client's "recurse to child frames, a hidden mid-tree frame blocks its subtree"
-/// (`propagation.md`) — a child of a hidden frame already carries `effective_visible == false` and is
-/// skipped here. Each visible frame emits its own [`ZTarget::Frame`] entry followed by one
-/// [`ZTarget::Region`] per owned region; the returned vec is sorted ascending by [`ZKey`], which *is*
-/// the total draw order (strata → frame level → **draw layer** → texture<fontstring → frame
-/// link-stamp → is-region → sub-level → decl; the layer outranks the frame — see the `ZKey`
-/// bit-layout note and decision 0884). Ties are impossible: distinct frames differ in link-stamp, a frame and its
-/// regions differ in the is-region bit, and a frame's regions differ in the remaining fields.
-///
-/// Ordering only: this emits an entry for *every* region of a visible frame. Region-level
-/// `Show`/`Hide` (the VisibleRegion bit, `region+0xc4`) is applied one layer up, where paint lives —
-/// [`UiScript::extract`](crate::script::UiScript::extract) drops hidden regions before they become
-/// quads. (The 1.12 region-draw cluster that would pin the *draw-time* skip is still flagged unread
-/// in wow-re's findings; the flag itself and its setter `0x77fcb0` are recorded.)
-///
-/// Cached against its own inputs (decision 1979): the list
-/// is a pure function of every visible frame's `(strata, level, insertion)` and every attached
-/// region's layer/sub-level/kind/decl — a walk over ~2 k frames and ~6 k regions, then a sort,
-/// and it was rebuilt on every frame for the extract, the pointer and the edit box alike. The
-/// walk stays (it is the fingerprint); the sort and the allocation happen only when the walk
-/// hashes differently from the last one, which on a still frame it never does.
+/// The render list in the client's `0x765650` order, sorted by [`ZKey`], with no two keys tied.
+/// Only effective-visible frames contribute, as the client skips a hidden frame's whole subtree
+/// (`0x76ae10`, `0x76ad50`). Every region of such a frame is listed; hidden ones (`region+0xc4`,
+/// set by `0x77fcb0`) are dropped by [`UiScript::extract`](crate::script::UiScript::extract), and
+/// where the client skips them at draw time is untraced. An unchanged walk returns the last list.
 pub fn traversal(arena: &WidgetArena) -> DrawList {
     let mut cache = arena.order_cache.0.borrow_mut();
-    // One walk into a scratch (the previous walk's buffer, reused), then an EXACT compare
-    // against the last walk: equal inputs hand out the same list; a hash would have made a
-    // wrong draw order a possibility, however remote, and cost a second walk on every miss.
+    // An exact compare with the last walk, not a hash: a collision would draw in a wrong order.
     let (mut walked, last) = match cache.take() {
         Some((prev, list)) => {
             let mut scratch = Vec::with_capacity(prev.len());
@@ -520,54 +362,26 @@ pub fn traversal(arena: &WidgetArena) -> DrawList {
     list
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Hit-testing — the mouse-focus capture walk
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Hit-testing: the mouse-focus capture walk ────────────────────────────────────────────────
 
-/// Find the frame the cursor captures — the reference's flat hit-test index, **byte-carved**
-/// (wow-re `system/ui/scratch/hittest-no-fallthrough-law.md`).
+/// The frame the cursor captures, by the client's sweep `0x7660d0`: strata high to low, and in one
+/// `(strata, level)` plane the earlier-linked frame first. The first frame that takes the mouse
+/// ends the sweep whatever its handler does (`0x7663f7` overwrites the result of the call at
+/// `0x7663f4`), so a disabled button still eats the click.
 ///
-/// The sweep `0x7660d0` walks the mouse plane strata high→low and, within a stratum, the index from
-/// 0 upward, ending the ENTIRE sweep on the first probe that returns non-zero. There is **no
-/// fall-through**: `0x7663f4 call [edx+0x68]` is followed by `0x7663f7 mov eax,1`, so the handler's
-/// return is destroyed before it is tested. A frame that takes the mouse and does nothing with the
-/// click eats it — a `RegisterForClicks` miss, a disabled button and an unbound script all end the
-/// event identically. (The one real fall-through in the engine is the WHEEL plane, which does gate
-/// on a handler and continue; the engine has the idiom and deliberately does not use it here.)
+/// Equal levels go to the earlier link (`0x764aa0` appends after equals). A parent is linked before
+/// its children (show at `0x76ae85`, then `0x76aeb6`; `SetFrameLevel` likewise), so it wins a tie
+/// with its child, which `TargetFrame.lua:33` relies on; and the first-declared sibling wins, so a
+/// full-area `<Button>` declared first, mouse-enabled by its constructor, swallows its window.
+/// Drawing still puts the later link on top.
 ///
-/// **The index is FLAT** — sorted `(strata, frame level, insertion order)`, with no parent/child
-/// nesting term at all, which is exactly [`traversal`]'s key. The tie is the part that matters and
-/// the part we had backwards: `0x764aa0`'s comparison is a strict `ja`, so a frame arriving at a
-/// level that already exists is **appended after** its equals, and the sweep from index 0 therefore
-/// reaches the **earlier-linked** frame first. `SetFrameLevel` relinks the parent before recursing
-/// into children, and effective-Show registers self (`0x76ae85`) before its children (`0x76aeb6`) —
-/// so at equal levels **the parent wins over its own child**.
-///
-/// That is the whole reason `TargetFrame_OnLoad`'s `SetFrameLevel(textureFrame-1)` on the two bars
-/// works: the bars land at exactly `TargetFrame`'s own level, and the tie goes to the frame that
-/// registered first. Walking the draw order in reverse — which is what this did until the carve —
-/// inverts it and hands the click to the child, so right-clicking a unit frame opened nothing.
-///
-/// **The SIBLING case is the one that bites hardest, and it is why this is not a local fix**
-/// (decision 1816). All children of one parent share `parent.level + 1`, so every sibling set is one
-/// big tie, resolved purely by declaration order — and under the true law the FIRST-declared sibling
-/// wins, not the last. A full-area mouse-enabled overlay declared at the top of a `<Frames>` list
-/// therefore swallows its whole window. Five of our own windows shipped exactly that (the
-/// `*WheelCatcher` `<Button>`s), correct only under the inverted order and removed with this carve;
-/// `SkillFrame.xml` had already recorded one shipped bug from the same shape. Note that
-/// `<Button>` is mouse-enabled by its *constructor* (decision 1795), so such an overlay needs no
-/// `enableMouse` to compete — the wheel is a separate index and needs no mouse hit target at all.
-///
-/// Drawing is unaffected and stays later-on-top: this reordering is the HIT sweep's alone.
-///
-/// Pure over its inputs: `sorted` is draw-order-**ascending** (as [`traversal`] returns), and
-/// `hits(frame)` reports whether that frame is a capture candidate at the cursor. Visibility is
-/// handled upstream. Regions never capture.
+/// `sorted` is [`traversal`]'s ascending list and `hits` says whether a frame is a candidate at the
+/// cursor; regions never capture.
 pub fn hit_test<F: Fn(FrameHandle) -> bool>(
     sorted: &[(ZTarget, ZKey)],
     hits: F,
 ) -> Option<FrameHandle> {
-    // Everything above the insertion field: one (strata, level) plane of the reference's index.
+    // The key's strata and level: one plane of the client's index.
     let plane = |k: ZKey| k.0 >> LEVEL_SHIFT;
     let mut end = sorted.len();
     while end > 0 {
@@ -576,7 +390,7 @@ pub fn hit_test<F: Fn(FrameHandle) -> bool>(
         while start > 0 && plane(sorted[start - 1].1) == p {
             start -= 1;
         }
-        // Planes descend; WITHIN a plane the earlier-linked frame is probed first.
+        // Planes descend; within one, the earlier-linked frame is probed first.
         for (target, _) in &sorted[start..end] {
             if let ZTarget::Frame(fh) = *target {
                 if hits(fh) {
@@ -601,7 +415,7 @@ mod tests {
         let lo = ZKey::frame(Strata::World, u16::MAX, 0);
         let hi = ZKey::frame(Strata::Tooltip, 0, 0);
         assert!(hi > lo);
-        // BLIZZARD (Era) is above TOOLTIP.
+        // BLIZZARD is above TOOLTIP.
         assert!(ZKey::frame(Strata::Blizzard, 0, 0) > ZKey::frame(Strata::Tooltip, u16::MAX, 0));
     }
 
@@ -634,26 +448,23 @@ mod tests {
     #[test]
     fn layer_then_kind_then_frame_then_decl() {
         let mk = |layer, sub, fs, decl| ZKey::region(Strata::Medium, 3, 42, layer, sub, fs, decl);
-        // The layer is the top term below (strata, level) — it dominates everything under it.
+        // The layer is the top term below strata and level.
         assert!(
             mk(DrawLayer::Border, i8::MIN, false, 0) > mk(DrawLayer::Background, 127, true, 4095)
         );
-        // Within a layer, KIND is next: all textures precede all fontstrings — and it now outranks
-        // sub-level (0884: the layer batch's two sub-arrays, quads drained before text).
+        // Within a layer the kind is next: every texture precedes every font string, whatever the
+        // sub-level.
         assert!(
             mk(DrawLayer::Artwork, i8::MIN, true, 0) > mk(DrawLayer::Artwork, 127, false, 4095)
         );
         // Below kind, declaration order decides within one frame's layer.
         assert!(mk(DrawLayer::Artwork, 0, false, 2) > mk(DrawLayer::Artwork, 0, false, 1));
-        // Sub-level still orders below kind — inert on 1.12 (nothing sets it), kept for Era.
+        // Sub-level orders below kind.
         assert!(mk(DrawLayer::Artwork, -1, false, 0) < mk(DrawLayer::Artwork, 0, false, 0));
     }
 
-    /// The law 0884 **replaced**, kept as a test so it cannot come back: a frame's regions are not
-    /// glued behind it. The draw layer is bucket-wide, so at one `(strata, level)` every frame's
-    /// BACKGROUND draws before any frame's OVERLAY — frame A's OVERLAY sorts *after* frame B's
-    /// BACKGROUND even though A linked first. That interleave is what puts the mirror timer's
-    /// ARTWORK fill under its own parent frame's OVERLAY border and caption.
+    /// The layer is bucket-wide: at one `(strata, level)` every frame's BACKGROUND draws before any
+    /// frame's OVERLAY, so a frame's regions are not grouped behind it.
     #[test]
     fn the_layer_interleaves_frames_it_does_not_group_them() {
         let a_overlay = ZKey::region(Strata::Medium, 0, 10, DrawLayer::Overlay, 0, false, 0);
@@ -671,23 +482,20 @@ mod tests {
             "at equal layer+kind, later link draws on top"
         );
 
-        // Kind spans frames: ALL textures of a (strata, level, layer) precede ALL its fontstrings.
+        // Kind spans frames: every texture of a (strata, level, layer) precedes every font string.
         let a_text = ZKey::region(Strata::Medium, 0, 10, DrawLayer::Artwork, 0, true, 0);
         assert!(
             b_art < a_text,
             "a later frame's texture still precedes an earlier frame's fontstring"
         );
-        // …and ALL its font strings precede a model's scene, whatever the link stamps: the scene
-        // drains from the layer batch's callback list, after its quads and its text (1995). The
-        // world map's arrow (a Model linked FIRST under WorldMapFrame) over the zone overlays and
-        // the area label (a later-linked ARTWORK texture and font string) is exactly this pair.
+        // Every font string precedes a model's scene, whatever the link stamps.
         let earlier_model = ZKey::frame(Strata::Medium, 0, 9).callback(DrawLayer::Artwork);
         let later_text = ZKey::region(Strata::Medium, 0, 11, DrawLayer::Artwork, 0, true, 0);
         assert!(
             later_text < earlier_model,
             "an earlier-linked model's scene still draws after a later frame's ARTWORK text"
         );
-        // The rank sits BELOW the layer: an OVERLAY quad still covers an ARTWORK scene.
+        // The rank sits below the layer: an OVERLAY quad still covers an ARTWORK scene.
         let b_overlay = ZKey::region(Strata::Medium, 0, 11, DrawLayer::Overlay, 0, false, 0);
         assert!(
             earlier_model < b_overlay,
@@ -698,8 +506,7 @@ mod tests {
         assert!(earlier_model < later_model);
         assert_eq!(unpack(earlier_model.raw()).rank, BatchRank::Callback);
 
-        // A frame's own slot is benilla's backdrop/scissor hook: it sits BELOW the layer key, so
-        // it precedes only its own regions, starting with its BACKGROUND.
+        // A frame's own slot sorts just before its own BACKGROUND regions.
         let a_frame = ZKey::frame(Strata::Medium, 0, 10);
         let a_bg = ZKey::region(Strata::Medium, 0, 10, DrawLayer::Background, 0, false, 0);
         assert!(a_frame < a_bg);
@@ -713,9 +520,8 @@ mod tests {
     fn traversal_snapshot_over_a_small_tree() {
         let mut a = WidgetArena::new();
 
-        // A DIALOG-strata parent with a texture; a MEDIUM child (lower strata ⇒ draws *before* its
-        // parent, proving the order is flat, not hierarchical); and a hidden frame that must not
-        // appear at all.
+        // A DIALOG frame with two regions, a top-level MEDIUM frame (a MEDIUM child would be forced
+        // to DIALOG) and a hidden frame.
         let dialog = a.create(FrameKind::Frame, Some("Dialog".into()), None);
         a.set_frame_strata(dialog, Strata::Dialog);
         let dlg_bg = a
@@ -725,8 +531,6 @@ mod tests {
             .create_region(dialog, RegionKind::FontString, DrawLayer::Artwork, 0)
             .unwrap();
 
-        // set_frame_strata forced the child to DIALOG too (subtree force), so make the child a
-        // top-level MEDIUM frame instead to exercise cross-strata draw order.
         let medium = a.create(FrameKind::Frame, None, None); // MEDIUM, level 0
         let med_art = a
             .create_region(medium, RegionKind::Texture, DrawLayer::Artwork, 0)
@@ -740,9 +544,7 @@ mod tests {
 
         let list: Vec<ZTarget> = traversal(&a).iter().map(|&(t, _)| t).collect();
 
-        // Expected painter order: MEDIUM frame + its region first (lower strata), then the DIALOG
-        // frame followed by its two regions (Background texture before Artwork fontstring). The
-        // hidden frame and its region are absent.
+        // MEDIUM first; the hidden frame is absent.
         assert_eq!(
             list,
             vec![
@@ -755,13 +557,9 @@ mod tests {
         );
     }
 
-    /// The client's bucket re-add on show (`effective_visible_show 0x76ae10`, propagation.md):
-    /// within one (strata, level) bucket, a frame shown LATER draws over one declared later but
-    /// never hidden — the exact minimap case (MiniMapTrackingFrame is declared before
-    /// MinimapBackdrop, hidden at load, and its runtime Show must lift it over the backdrop's
-    /// ring art, as the director's reference A/B shows; decision 0557). A strata/level change on
-    /// a visible frame re-buckets to the tail the same way; on a hidden frame it does not bump
-    /// (the client's remove/add is visible-gated — it appends on the next show regardless).
+    /// Showing a frame relinks it at its bucket's tail (`0x76ae10`): `MiniMapTrackingFrame`,
+    /// declared hidden before `MinimapBackdrop` (`Minimap.xml:109`, `:415`), draws over the
+    /// backdrop once shown. A strata or level change relinks a shown frame, not a hidden one.
     #[test]
     fn showing_a_frame_moves_it_to_its_buckets_tail() {
         let mut a = WidgetArena::new();
@@ -776,8 +574,7 @@ mod tests {
             vec![ZTarget::Frame(tracking), ZTarget::Frame(backdrop)]
         );
 
-        // Hide-then-show (the XML's hidden="true" + the runtime Show()): tracking re-enters its
-        // bucket at the tail — above the backdrop.
+        // Hide then show: tracking relinks at the tail, above the backdrop.
         a.set_shown(tracking, false);
         a.set_shown(tracking, true);
         assert_eq!(
@@ -785,16 +582,14 @@ mod tests {
             vec![ZTarget::Frame(backdrop), ZTarget::Frame(tracking)]
         );
 
-        // A no-op Show (already visible) is NOT a transition — no re-add, order stays.
+        // Showing a shown frame relinks nothing.
         a.set_shown(backdrop, true);
         assert_eq!(
             order(&a),
             vec![ZTarget::Frame(backdrop), ZTarget::Frame(tracking)]
         );
 
-        // A visible frame's level round-trip re-buckets it to the tail both times — the
-        // remove/add of set_frame_level. (backdrop: level 0 → 1 → 0, ends level 0 again but now
-        // draws over tracking.)
+        // A shown frame's level round trip relinks it at the tail.
         a.set_frame_level(backdrop, 1, false);
         a.set_frame_level(backdrop, 0, false);
         assert_eq!(
@@ -802,8 +597,7 @@ mod tests {
             vec![ZTarget::Frame(tracking), ZTarget::Frame(backdrop)]
         );
 
-        // The same round-trip while HIDDEN doesn't bump: after the show it sits at the tail
-        // because of the show itself, and a hidden frame is in no bucket to move.
+        // The same round trip while hidden moves nothing; the show relinks it.
         a.set_shown(tracking, false);
         a.set_frame_level(tracking, 1, false);
         a.set_frame_level(tracking, 0, false);
@@ -819,8 +613,7 @@ mod tests {
     #[test]
     fn hit_test_returns_topmost_matching_frame_and_skips_regions() {
         let mut a = WidgetArena::new();
-        // Two overlapping frames; `top` (DIALOG) draws above `bottom` (MEDIUM). A region belongs to
-        // `top` and would sort *after* the frame in draw order — it must never be returned.
+        // `top` (DIALOG) draws above `bottom` (MEDIUM); `top`'s region must never be returned.
         let bottom = a.create(FrameKind::Frame, None, None);
         let top = a.create(FrameKind::Frame, None, None);
         a.set_frame_strata(top, Strata::Dialog);
@@ -829,12 +622,9 @@ mod tests {
             .unwrap();
 
         let sorted = traversal(&a);
-        // Both frames are candidates ⇒ the topmost-drawn (`top`) wins.
         assert_eq!(hit_test(&sorted, |_| true), Some(top));
-        // Only `bottom` is a candidate ⇒ it wins even though `top` draws above it (top is transparent
-        // to hits, e.g. mouse-disabled).
+        // A `top` that does not take the mouse lets `bottom` win.
         assert_eq!(hit_test(&sorted, |fh| fh == bottom), Some(bottom));
-        // No candidate ⇒ no capture.
         assert_eq!(hit_test(&sorted, |_| false), None);
     }
 }
diff --git a/crates/benilla-ui/src/script/action.rs b/crates/benilla-ui/src/script/action.rs
index 1c918c0d..28ece326 100644
--- a/crates/benilla-ui/src/script/action.rs
+++ b/crates/benilla-ui/src/script/action.rs
@@ -1,113 +1,76 @@
-//! The action-bar bindings (decision 0068 slice 1, extended by decision 0216 §7/slice 4) — both
-//! directions of the engine seam in one place: the app pushes an **action snapshot** (what each
-//! of the 120 action slots displays, [`UiScript::set_action`], same inward shape as
-//! [`super::unit`]'s snapshots), and `UseAction` queues an outbound **intent** the app drains
-//! into the wire ([`UiScript::take_action_uses`], same outward shape as [`super::sound`]'s
-//! queue). The engine holds no spell/item/macro KNOWLEDGE — a slot is "a texture, a count, and
-//! the packed `(kind, action)` halves" — but slice 4 hands it the packed halves themselves so the
-//! cursor seam ([`super::cursor::bar`]) can pick a slot up and place it without round-tripping the
-//! app: the ENGINE owns the payload + the local slot mutation against its own optimistic mirror
-//! of `model.actions`, the APP owns the authoritative 120-table and drains the queued
-//! `action_sets` onto the wire (`CMSG_SET_ACTION_BUTTON`).
-//!
-//! Actions are keyed by the **Lua action id** (1..120, the live API's space; the 1.12 wire's
-//! 120-slot array is this minus one). `GetBonusBarOffset` reports the app-pushed stance/form
-//! page offset — the vanilla main bar shows actions `(6 + offset − 1)·12 + i` when an offset is
-//! active (warrior stances, druid forms), which the FrameXML side computes exactly like
-//! Blizzard's own bar code.
+//! The action-bar bindings. The app pushes what each of the 120 slots shows and its per-frame
+//! state, and drains the queued `UseAction` presses and the slot writes the cursor made
+//! (`CMSG_SET_ACTION_BUTTON`); the engine keeps each slot's packed `(kind, action)` so the cursor
+//! can move a slot without the app. Actions are keyed by Lua action id, 1..120, one more than the
+//! wire's slot index. FrameXML's bonus bar shows actions `(6 + offset - 1) * 12 + i` for the
+//! app-pushed `GetBonusBarOffset`.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::flag;
 use super::Model;
 
-/// Action-kind bytes — bits 24–31 of the wire's packed slot word (VERIFIED vmangos `Player.h`
-/// `ActionButtonType`; decision 0216 §1, `CMSG_SET_ACTION_BUTTON`'s own packing). The natural
-/// home for the constant every `ActionSlot` producer/consumer needs (`super::cursor::bar`'s
-/// pack/unpack included) — this crate is deliberately engine-free (no protocol dependency, see
-/// the crate doc), so it can't just import `benilla_protocol::messages::ACTION_KIND_*`.
+/// The kind byte, bits 24-31 of the packed slot word (vmangos `Player.h:133`). Must match
+/// `benilla_protocol`'s `ACTION_KIND_*`; this crate has no protocol dependency.
 pub(crate) const ACTION_KIND_SPELL: u8 = 0x00;
 pub(crate) const ACTION_KIND_MACRO: u8 = 0x40;
 pub(crate) const ACTION_KIND_ITEM: u8 = 0x80;
 
-/// What one action slot displays. The app resolves icons (Spell.dbc × SpellIcon.dbc for a spell,
-/// the item template chain for an item) before pushing.
+/// What one action slot shows; the app resolves the icon before pushing.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ActionSlot {
     /// The icon texture path (`Interface\Icons\…`); `None` shows the slot's fallback.
     pub texture: Option<String>,
-    /// The wire's kind byte (bits 24–31 of the packed slot word — SPELL 0x00/MACRO 0x40/ITEM
-    /// 0x80, decision 0216 §1). Opaque to the engine beyond the cursor seam's own pack/unpack
-    /// (`super::cursor::bar`); ids, targets, and the cast are still the app's.
+    /// The kind byte, one of the `ACTION_KIND_*` above.
     pub kind: u8,
-    /// The spell/macro/item id (bits 0–23 of the packed slot word).
+    /// The spell, macro or item id (bits 0-23 of the packed slot word).
     pub action: u32,
-    /// Bag count for an ITEM-kind slot (`GetActionCount`), `0` for every other kind or an empty
-    /// bag — the app-resolved value the Count fontstring reads (decision 0216 §7).
+    /// `GetActionCount`'s bag count for an item slot, 0 otherwise.
     pub count: u32,
-    /// `IsConsumableAction`: the gate the ref's `UpdateCount` puts in front of [`Self::count`]
-    /// (decision 0926 §3). **Identity, not state** — `0x4e5250` reads nothing but the slot's own
-    /// item template, so it changes exactly when the icon does and rides the same push (decision
-    /// 1301; it lived in [`ActionState`] until the login race that split the pair).
+    /// `IsConsumableAction`: `0x4e5250` reads only the slot's item template, so this rides the
+    /// icon's push, not [`ActionState`]'s.
     pub consumable: bool,
 }
 
-/// One action's **dynamic** state — the per-frame half the app's feed pushes beside the slot's
-/// identity ([`ActionSlot`]): what the reference's `ActionButton_Update*` family reads through
-/// `IsUsableAction`/`IsActionInRange`/`IsCurrentAction`/`GetActionCooldown` and kin (decision
-/// 0137 phase 4). Split from the identity map so a state churn (range, cooldown) never disturbs
-/// the identity diff that fires `ACTIONBAR_SLOT_CHANGED`.
+/// One action's per-frame state, read by `IsUsableAction`, `IsActionInRange`, `GetActionCooldown`
+/// and kin; kept apart from [`ActionSlot`] so its churn never fires `ACTIONBAR_SLOT_CHANGED`.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct ActionState {
-    /// `IsUsableAction`'s first return: castable right now (power etc.).
+    /// `IsUsableAction`'s first return: castable now.
     pub usable: bool,
-    /// `IsUsableAction`'s second return: unusable **specifically** for insufficient power (the
-    /// 0.5/0.5/1.0 blue tint); other unusability reads `(false, false)` (the 0.4 grey).
+    /// `IsUsableAction`'s second return: unusable only for lack of power (FrameXML's blue tint).
     pub not_enough_mana: bool,
-    /// `IsActionInRange`: `None` = rangeless action or no valid target (Lua `nil`);
-    /// `Some(true/false)` = the 1/0 verdict.
+    /// `IsActionInRange`: `None` (nil) for a rangeless action or no target, else 1 or 0.
     pub in_range: Option<bool>,
-    /// `ActionHasRange`: the action's spell has a range row to test at all.
+    /// `ActionHasRange`: the action's spell has a range to test.
     pub has_range: bool,
-    /// `IsCurrentAction`: the Attack action while auto-attack is engaged, or the action's spell
-    /// while it is our in-flight cast (the checked ring).
+    /// `IsCurrentAction`: the Attack action while auto-attack is on, or the spell being cast.
     pub current: bool,
-    /// `IsAutoRepeatAction`: the action's spell is the live autorepeat key (`0xceac30`).
+    /// `IsAutoRepeatAction`: the action's spell is the live autorepeat spell (`0xceac30`).
     pub auto_repeat: bool,
     /// `IsAttackAction`: the action is the melee auto-attack.
     pub is_attack: bool,
-    /// `IsEquippedAction`: an ITEM action currently worn (the green border).
+    /// `IsEquippedAction`: an item action currently worn.
     pub equipped: bool,
-    /// The action's cooldown as pushed: `(start_ms, duration_ms, enabled)` with `start_ms` the
-    /// cooldown's **absolute start on the `GetTime` clock** (the app converts from its own clock
-    /// at feed time — the app-side `CooldownInfo::ui_triple`'s job). Absolute so the value is
-    /// identity-preserving: one running cooldown reads the same triple every frame (no diff
-    /// churn), while a re-arm always reads a new one (the sweep restarts — the reference's own
-    /// convention, whose `GetCooldownInfo 0x6e13e0` returns the record's start and therefore
-    /// cannot alias two arms the way a `(remaining, duration)` pair did).
+    /// `(start_ms, duration_ms, enabled)`, the start absolute on the `GetTime` clock, so a running
+    /// cooldown re-pushes the same triple and a re-arm a new one (`0x6e13e0` returns the start).
     pub cooldown: Option<(i64, u32, bool)>,
 }
 
-/// [`ActionState`] as stored: the cooldown converted to the `GetTime` clock at push time.
+/// [`ActionState`] with its cooldown in `GetTime` seconds.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub(crate) struct StoredActionState {
     pub(crate) state: ActionState,
-    /// `(start_s, duration_s, enabled)` in `GetTime` seconds; `None` = no cooldown.
     pub(crate) cooldown: Option<(f64, f64, bool)>,
 }
 
-/// One queued `UseAction` press — the action id, and whether it carried the **self-cast
-/// modifier**.
-///
-/// A struct rather than a `(u32, bool)` because a bare bool in a tuple is exactly the argument
-/// that gets swapped silently; the neighbouring `take_action_sets` pairs two `u32`s, where the
-/// positions are self-describing.
+/// One queued `UseAction` press.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ActionUse {
     /// The 1-based Lua action id, as `UseAction` was given it.
     pub action: u32,
-    /// `UseAction`'s third argument — 1.12's `SELFACTIONBUTTON1`-`12` (`ALT-1`…`ALT-=`) reach the
-    /// bar through `ActionButtonUp(id, 1)`, and every other caller passes nothing.
+    /// `UseAction`'s third argument, which only the self-cast bindings (`SELFACTIONBUTTON1`-`12`)
+    /// pass, through `ActionButtonUp(id, 1)`.
     pub on_self: bool,
 }
 
@@ -125,11 +88,8 @@ impl super::UiScript {
         }
     }
 
-    /// Push (or clear) one action's dynamic state. The cooldown arrives with its **absolute
-    /// start already on the `GetTime` clock** (ms), so storing is a pure unit conversion — no
-    /// anchor derivation, no prev-comparison. A re-push of a running cooldown carries the same
-    /// start (the sweep is undisturbed — the reset-on-kill invariant holds by construction); a
-    /// re-armed one carries a new start (the sweep restarts, as the reference's does).
+    /// Push (or clear) one action's state; the cooldown start is already on the `GetTime` clock,
+    /// so storing only converts milliseconds to seconds.
     pub fn set_action_state(&mut self, action: u32, state: Option<ActionState>) {
         let mut model = self.model_mut();
         match state {
@@ -161,28 +121,20 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().action_uses)
     }
 
-    /// Drain the `(lua action id, packed)` pairs `PickupAction`/`PlaceAction` queued since the
-    /// last call (decision 0216 §7) — the app sends one `CMSG_SET_ACTION_BUTTON` per entry
-    /// (`packed == 0` clears the slot) and updates its own authoritative `PlayerActions` store.
+    /// Drain the `(lua action id, packed)` pairs `PickupAction`/`PlaceAction` queued; the app
+    /// sends each as `CMSG_SET_ACTION_BUTTON` (`packed == 0` clears) and updates its own store.
     pub fn take_action_sets(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().action_sets)
     }
 
-    /// Drain the GlobalStrings keys queued by engine-side client-local refusals since the last
-    /// call — the app resolves each against the VM's own GlobalStrings and fires
-    /// `UI_ERROR_MESSAGE`, standing in for the reference's inline `CGGameUI::DisplayError` (whose
-    /// engine can call it directly; ours is on the far side of the crate boundary). See
-    /// [`crate::script::model::Model::ui_errors`].
+    /// Drain the GlobalStrings keys of engine-side refusals; the app fires `UI_ERROR_MESSAGE` for
+    /// each, where the reference calls `CGGameUI::DisplayError` inline.
     pub fn take_ui_errors(&mut self) -> Vec<&'static str> {
         std::mem::take(&mut self.model_mut().ui_errors)
     }
 }
 
-/// `checkCursor`'s truthiness (`UseAction`'s second argument): the reference's own numeric
-/// convention — `nil`/`false`/`0` all read falsy, anything else (including Lua's own `true`)
-/// reads truthy. Deliberately NOT Lua's plain truthiness (where `0` is truthy) — the reference
-/// passes literal `0` from a keybind meaning "never place", which only a numeric-zero check
-/// reproduces.
+/// `UseAction`'s flag test: `nil`, `false` and `0` are false, unlike Lua, where `0` is true.
 pub(super) fn truthy_nonzero(v: &Value) -> bool {
     match v {
         Value::Nil => false,
@@ -197,7 +149,6 @@ pub(super) fn truthy_nonzero(v: &Value) -> bool {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // HasAction(action) → 1/nil, the reference's predicate shape (`super::binding_abi::flag`).
     g.set(
         "HasAction",
         lua.create_function(|lua, action: u32| {
@@ -220,40 +171,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetActionText(slot) → the MACRO's own name, or nil. 1-based (`0x4e7072 dec eax`).
-    //
-    // **The classification is binary, not four-way** (`0x4e7050`, wow-re
-    // `bag-language-combat-action-bindings.md` §4, §5-cross-checked). The binding tests exactly
-    // one thing — top nibble `raw & 0xf0000000 == 0x40000000` — and **spell, item and empty all
-    // collapse to the identical nil arm**. It settles nothing about how spells or items are
-    // tagged, because it never asks.
-    //
-    // | slot contents | returns |
-    // |---|---|
-    // | macro, id resolves | the macro's own name (record `+0x24`, an inline buffer) |
-    // | macro, id does not resolve | `nil` |
-    // | spell · item · empty | `nil` |
-    // | slot missing / not a number | **raises** `Usage: GetActionText(slot)` (`0x84bff4`) |
-    //
-    // A macro whose name is empty answers `""`, not nil: `+0x24` is an inline buffer and can never
-    // be the null pointer `0x6f3890`'s guard tests for, so that guard is dead at this site. Our
-    // `MacroView::name` is a `String` and reproduces that for free.
-    //
-    // **The reference's trap does not exist here, and the reason is worth stating.** There the
-    // slot's macro payload (`raw & 0x3fffffff`) is an **opaque hash key** into `[0xbdcc54]`, NOT
-    // the 1..36 index — `GetMacroInfo` translates an index through `0xbdcc60` first and
-    // `GetActionText` never does, so a client that treats the payload as an index reads the wrong
-    // macro for every macro whose id ≠ its slot. benilla's macro table has no id space at all
-    // (decision 0983: two dense lists addressed by the 1..36 Lua index), so the payload our wire
-    // carries IS that index — and this is the same lookup `ui_action::feed`'s MACRO icon arm
-    // makes, through the same `MacroState::get`, so a slot's text and its icon cannot disagree
-    // about which macro it holds.
-    //
-    // One deliberate deviation: the reference has **no bounds check** (read contiguously from the
-    // `dec` to `mov eax,[4*eax + 0xbc6980]` — no `cmp`, no clamp), so slot 0 reads the dword below
-    // a 120-dword array and slot 121 reads into the next global. Our slot store is a map, so an
-    // out-of-range slot is simply absent and answers nil. Safer than the binary, and recorded as a
-    // deviation rather than passed off as a match.
+    // GetActionText(slot): the macro's name, else nil. `0x4e7050` tests only
+    // `raw & 0xf0000000 == 0x40000000`, so spell, item and empty slots all answer nil; a missing or
+    // non-number slot raises `Usage: GetActionText(slot)` (`0x84bff4`); the slot is 1-based
+    // (`0x4e7072` `dec eax`). An empty name answers "": it is an inline buffer at `+0x24`, so
+    // `0x6f3890`'s null guard never fires.
+    // The reference's macro payload (`raw & 0x3fffffff`) is a hash key into `[0xbdcc54]`; ours is
+    // the 1..36 index, the lookup the app's macro icon makes too, so text and icon agree.
+    // Deviation: an out-of-range slot answers nil, because the reference indexes `0xbc6980` with
+    // no bounds check and reads the memory beside its 120 slots.
     g.set(
         "GetActionText",
         lua.create_function(|lua, slot: Value| {
@@ -274,28 +200,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UseAction(action [, checkCursor [, onSelf]]). **`onSelf` is the self-cast modifier** — the
-    // third argument stock `ActionButtonUp(id, onSelf)` forwards on its main-bar branch and this
-    // host used to drop on the floor, which is why 1.12's twelve `SELFACTIONBUTTON` bindings
-    // (`ALT-1`…`ALT-=`) had no home. It rides out on [`ActionUse::on_self`] and the app's cast
-    // resolver reads it. `checkCursor` TRUTHY (numeric nonzero — the
-    // reference's own convention, not Lua's: `0` reads falsy here even though Lua truthiness
-    // would call it true) AND a payload is held routes to [`cursor::place_action`] instead of
-    // queuing the use (decision 0216 §7's INTERIM: the reference passes 1 from a mouse click and
-    // 0 from a keybind — the 0216 §5 dispatch never pinned checkCursor's byte semantics
-    // explicitly, and place-on-click is the only reading consistent with that click/keybind
-    // split). Any of the three payload arms counts as "held" — Item/Spell/Action are all
-    // placeable onto a bar slot.
+    // UseAction(action [, checkCursor [, onSelf]]): a nonzero `checkCursor` while the cursor holds
+    // a payload places it, as `PlaceAction` does; otherwise the press is queued with `onSelf`, the
+    // self-cast flag. FrameXML passes 1 from a click and 0 from a keybind; the binding's own test
+    // of it is untraced, and place-on-click is the reading that split implies.
     g.set(
         "UseAction",
         lua.create_function(|lua, (action, rest): (u32, MultiValue)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let mut rest = rest.iter();
             let check_cursor = rest.next().is_some_and(truthy_nonzero);
-            // `onSelf` reads with the SAME truthiness as `checkCursor` — numeric-nonzero, the
-            // reference's convention rather than Lua's — because it arrives from the same
-            // callers by the same route. `ActionButtonUp(id, 1)` is the only shipped caller
-            // that passes it.
             let on_self = rest.next().is_some_and(truthy_nonzero);
             if check_cursor && model.cursor.is_some() {
                 super::cursor::place_action(&mut model, action);
@@ -306,9 +220,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Bag count for an ITEM-kind action, 0 for every other kind (the ref's IsConsumableAction
-    // gate simplified — 0216 §7's App-section note) — the check lives HERE, not in every XML
-    // caller, so a slot fed a stray count on the wrong kind (a bug elsewhere) can't leak through.
     g.set(
         "GetActionCount",
         lua.create_function(|lua, action: u32| {
@@ -329,13 +240,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `ChangeActionBarPage()` — four instructions in the reference (`0x4e7650`: `mov ecx,0xd4;
-    // call FrameScript_SignalEvent; xor eax,eax; ret` — wow-re `action-bar-toggles.md` §6, `ui.md`):
-    // it fires `ACTIONBAR_PAGE_CHANGED` and does NOTHING else. The page is FrameXML state
-    // (`CURRENT_ACTIONBAR_PAGE`, which `ActionBar_PageUp/Down` and the SHIFT-n bindings write before
-    // calling this), the buttons repaint from `ActionButton_OnEvent`, and the up-arrow's OnEvent
-    // restamps the numeral. Synchronous, like the reference's `SignalEvent` (1938; the pattern is
-    // `UpdateSpells` → `SPELLS_CHANGED`, 1924). Zero return values on every path.
+    // ChangeActionBarPage(): fires `ACTIONBAR_PAGE_CHANGED` synchronously and returns nothing
+    // (`0x4e7650`); the page itself is FrameXML's `CURRENT_ACTIONBAR_PAGE`.
     g.set(
         "ChangeActionBarPage",
         lua.create_function(|lua, ()| {
@@ -344,12 +250,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The dynamic-state read API (decision 0137 phase 4): the reference ActionButton.lua's
-    // whole input surface, answered from the app-pushed per-action state. Return conventions are
-    // the 1.12 API's own (1/nil booleans; IsActionInRange's nil/0/1 tri-state) — the transcribed
-    // Lua tests them with plain `if`, so nil-vs-0 matters exactly where the ref makes it matter.
+    // ── Per-action state ──
+    // 1/nil booleans and `IsActionInRange`'s nil/0/1, which FrameXML tests with a plain `if`.
 
-    // A 1/nil boolean read over the state map. An absent action answers nil.
     fn state_flag(lua: &Lua, action: u32, pick: impl Fn(&ActionState) -> bool) -> Value {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         match model.action_states.get(&action) {
@@ -358,7 +261,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         }
     }
 
-    // IsUsableAction(action) → isUsable (1/nil), notEnoughMana (1/nil).
     g.set(
         "IsUsableAction",
         lua.create_function(|lua, action: u32| {
@@ -369,7 +271,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsActionInRange(action) → nil (no range / no target) | 0 | 1.
     g.set(
         "IsActionInRange",
         lua.create_function(|lua, action: u32| {
@@ -404,10 +305,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "IsAttackAction",
         lua.create_function(|lua, action: u32| Ok(state_flag(lua, action, |s| s.is_attack)))?,
     )?;
-    // The Count gate reads the SLOT, not the state map: `IsConsumableAction 0x4e5250` is a pure
-    // query over the item template the icon already came from, so it has to arrive on the same
-    // push the icon does. Split across the two feeds it answered `nil` for the whole session on a
-    // freshly logged-in character (decision 1301).
+    // From the slot, not the state map: `0x4e5250` depends only on the item template.
     g.set(
         "IsConsumableAction",
         lua.create_function(|lua, action: u32| {
@@ -423,10 +321,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, action: u32| Ok(state_flag(lua, action, |s| s.equipped)))?,
     )?;
 
-    // GetActionCooldown(action) → start, duration, enable — the reference's `(GetTime-clock
-    // seconds, seconds, 0/1)` triple. An elapsed (or absent) cooldown answers `(0, 0, 1)`: the
-    // read must go cold once `start + duration` passes, or a later event-driven
-    // `CooldownFrame_SetTimer` re-feed would re-show the sweep and replay the finish flash.
+    // GetActionCooldown(action) → start, duration, enable, in `GetTime` seconds. An absent or
+    // elapsed enabled cooldown answers `(0, 0, 1)`, or a later `CooldownFrame_SetTimer` would
+    // replay the sweep and its finish flash.
     g.set(
         "GetActionCooldown",
         lua.create_function(|lua, action: u32| {
@@ -451,7 +348,6 @@ mod tests {
     use super::ActionSlot;
     use crate::script::UiScript;
 
-    /// `(action, on_self)` pairs, which is what these assertions are actually about.
     fn uses(s: &mut UiScript) -> Vec<(u32, bool)> {
         s.take_action_uses()
             .into_iter()
@@ -459,14 +355,7 @@ mod tests {
             .collect()
     }
 
-    /// **`UseAction`'s third argument is the self-cast modifier** (1745) — 1.12's twelve
-    /// `SELFACTIONBUTTON` bindings (`ALT-1`…`ALT-=`) reach the bar as `ActionButtonUp(id, 1)`,
-    /// and this host dropped it on the floor until the day those bindings needed a home.
-    ///
-    /// It reads with `checkCursor`'s truthiness, not Lua's — **numeric-nonzero** — because it
-    /// arrives from the same callers by the same route. That is the assertion worth having: Lua
-    /// would call `0` true, and a bar where `ActionButtonUp(id, 0)` self-cast would be worse than
-    /// one where nothing did.
+    /// The numeric test: `0` is not the modifier, though Lua would call it true.
     #[test]
     fn use_actions_third_argument_is_the_self_cast_modifier() {
         let mut s = UiScript::new().unwrap();
@@ -528,7 +417,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetBonusBarOffset()").unwrap(), 1);
 
         s.run("UseAction(73)").unwrap();
-        s.run("UseAction(74, 0, 1)").unwrap(); // the self-cast modifier rides out
+        s.run("UseAction(74, 0, 1)").unwrap();
         assert_eq!(uses(&mut s), vec![(73, false), (74, true)]);
         assert!(s.take_action_uses().is_empty());
 
@@ -553,9 +442,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetActionCount(5)").unwrap(), 4);
     }
 
-    /// `UseAction`'s `checkCursor` routes to a place ONLY when truthy (numeric-nonzero, not Lua
-    /// truthiness) AND a payload is held; a keybind's bare `UseAction(id)` and an explicit `0`
-    /// both queue the ordinary use even while holding.
+    /// A place needs a nonzero `checkCursor` and a held payload; a keybind's `0` queues the use.
     #[test]
     fn use_action_check_cursor_routes_to_place_or_use() {
         use crate::script::cursor::{CursorAction, CursorPayload};
@@ -568,26 +455,21 @@ mod tests {
             texture: Some("Interface\\Icons\\Spell_A".into()),
         }));
 
-        // checkCursor 0 (a keybind's own convention): queues the use, cursor untouched.
         s.run("UseAction(9, 0)").unwrap();
         assert_eq!(uses(&mut s), vec![(9, false)]);
         assert!(s.cursor_payload().is_some(), "checkCursor 0 never places");
 
-        // checkCursor 1 (a mouse click) with a payload held: places instead of queuing.
         s.run("UseAction(9, 1)").unwrap();
         assert!(s.take_action_uses().is_empty(), "routed to place, not use");
         assert!(s.cursor_payload().is_none(), "empty destination clears");
         assert_eq!(s.take_action_sets(), vec![(9, 111)]);
 
-        // checkCursor 1 with an EMPTY cursor: the ordinary use (nothing to place).
         s.run("UseAction(10, 1)").unwrap();
         assert_eq!(uses(&mut s), vec![(10, false)]);
     }
 
-    // ── `GetActionText` (wow-re `bag-language-combat-action-bindings.md` §4) ────────────────────
+    // ── `GetActionText` (`0x4e7050`) ──
 
-    /// The classification is **binary**: macro or not. A SPELL slot and an ITEM slot answer the
-    /// identical `nil` an empty slot does — the binding tests one nibble and asks nothing else.
     #[test]
     fn get_action_text_is_the_macro_name_and_nil_for_everything_else() {
         use crate::script::{MacroState, MacroView};
@@ -615,11 +497,11 @@ mod tests {
                 consumable: false,
             })
         };
-        s.set_action(1, slot(0x40, 1)); // macro 1 — "Pull"
-        s.set_action(2, slot(0x40, 2)); // macro 2 — an empty NAME, not an empty slot
-        s.set_action(3, slot(0x40, 30)); // macro id that does not resolve
-        s.set_action(4, slot(0x00, 133)); // a SPELL (Fireball)
-        s.set_action(5, slot(0x80, 117)); // an ITEM
+        s.set_action(1, slot(0x40, 1)); // macro "Pull"
+        s.set_action(2, slot(0x40, 2)); // a macro with an empty name
+        s.set_action(3, slot(0x40, 30)); // no such macro
+        s.set_action(4, slot(0x00, 133)); // a spell
+        s.set_action(5, slot(0x80, 117)); // an item
 
         assert_eq!(s.eval::<String>("return GetActionText(1)").unwrap(), "Pull");
         assert_eq!(
@@ -641,11 +523,11 @@ mod tests {
                 "{why} must be nil"
             );
         }
-        // One value on every non-raising path — never zero values.
+        // One value on every non-raising path.
         assert_eq!(s.arity("GetActionText(4)").unwrap(), 1);
     }
 
-    /// A missing or non-number slot **raises** (`0x4e70be` → `0x6f4940`, which never returns).
+    /// The raise is `0x4e70be` into `0x6f4940`, which never returns.
     #[test]
     fn get_action_text_raises_on_a_bad_slot() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/action_bar_toggles.rs b/crates/benilla-ui/src/script/action_bar_toggles.rs
index d363c3f3..bdb9bb9b 100644
--- a/crates/benilla-ui/src/script/action_bar_toggles.rs
+++ b/crates/benilla-ui/src/script/action_bar_toggles.rs
@@ -1,78 +1,36 @@
-//! `GetActionBarToggles` / `SetActionBarToggles` — the four extra action bars' visibility, as one
-//! server-owned nibble. Byte-VERIFIED against the 1.12.1 binary: wow-re
-//! `system/ui/scratch/action-bar-toggles.md` (a §5 trio cross-check, `417c2d31`), whose section
-//! numbers the comments below cite.
+//! `GetActionBarToggles` and `SetActionBarToggles`: the four extra action bars' visibility, the
+//! low nibble of the server's `PLAYER_FIELD_BYTES` byte 2.
 //!
-//! ## The shape, and why it is not the shape it looks like
+//! The setter (`0x4e76e0`) only posts `CMSG_SET_ACTIONBAR_TOGGLES`; the getter (`0x4e7660`) reads
+//! the live descriptor byte, written only by the `SMSG_UPDATE_OBJECT` apply (`0x466590`), with no
+//! field-change hook (`0x468070`). A `Get` right after a `Set` returns the old value for a round
+//! trip; the stock UI reads it once, at `PLAYER_ENTERING_WORLD` (`UIParent.lua:364`).
 //!
-//! Four booleans in, four booleans out — but **the getter and the setter do not talk to each
-//! other**. `SetActionBarToggles 0x4e76e0` packs its four arguments into a stack byte, posts
-//! `CMSG_SET_ACTIONBAR_TOGGLES` and returns zero values; every store in its body is into its own
-//! `ebp` frame (§4.1). `GetActionBarToggles 0x4e7660` reads the live descriptor at
-//! `[[player+0xe68]+0x102a]` — `PLAYER_FIELD_BYTES` byte 2 — on every call, with no cache (§5). The
-//! only writer of that cell in the whole image is the generic `SMSG_UPDATE_OBJECT` value-apply
-//! (`apply_update_fields 0x466590`), and **nothing is notified when it lands**: all 49 field-change
-//! registrations at `0x468070` were enumerated and none sits at an offset ≥ `0x1000` (§4.2).
-//!
-//! So `SetActionBarToggles(1)` followed immediately by `GetActionBarToggles()` returns the **old**
-//! value, for a whole round trip. That is not a bug to paper over — it is the mechanism, and it is
-//! why [`super::UiScript::set_action_bar_toggles`] (the app's descriptor push) is the *only* thing
-//! that moves our copy. Contrast [`super::worn_display`], whose setter updates its belief
-//! optimistically because its wire verb is a blind flip that would otherwise mis-compute.
-//!
-//! The reference UI does not feel the lag because it never asks: it keeps `SHOW_MULTI_ACTIONBAR_1..4`
-//! as Lua globals, updates them on the checkbox click, and reads the binding exactly once — in
-//! `UIParent.lua`'s `PLAYER_ENTERING_WORLD` handler (§7). Our Lua layer copies that split.
-//!
-//! ## Four bits, and only four
-//!
-//! The setter's loop runs `i = 0..3` (`0x4e770e cmp esi,4`) and ORs `1 << i` for argument `i + 1`;
-//! the accumulator is written by exactly two instructions image-wide — the `mov BYTE [ebp-0x4],0`
-//! that zeroes it and the loop's `or` (§2). Two consequences we reproduce exactly:
-//!
-//! - A **fifth argument is silently dropped**. The shipped `UIOptionsFrame_Save` passes
-//!   `ALWAYS_SHOW_MULTIBARS` as a fifth; the binding never fetches it, so it never reaches the byte
-//!   or the wire (and, consistently, it is the one option of the five that FrameXML saves locally).
-//! - A `Set` **destroys the high nibble**. It starts from zero, so whatever `0x10..0x80` the server
-//!   happened to hold is overwritten with 0 by the next post. The getter never tests those bits
-//!   either (§5), so the client's view of this field is genuinely 4-bit.
-//!
-//! The bit→bar meaning is a FrameXML convention, not the binary's (§7) — the engine stores four
-//! unnamed bits and the names live in the UI layer.
+//! The setter builds the byte from zero out of four arguments (`0x4e76eb`, `0x4e7709`): a fifth,
+//! which `UIOptionsFrame.lua:363` passes, is dropped, and a high nibble the server held is cleared.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::bool_or_default;
 use super::Model;
 
-/// How many toggle bits the bindings read and write — `0x4e770e cmp esi,4` in the setter,
-/// `0x4e76cd mov eax,4` in the getter. Not a UI choice: four is what the binary does, in both
-/// directions, and bits above it are unreachable from Lua.
+/// Toggle bits the bindings read and write, four both ways (setter `0x4e770e`, getter `0x4e76cd`).
 const ACTION_BAR_TOGGLE_BITS: u32 = 4;
 
 impl super::UiScript {
-    /// Push the server's `PLAYER_FIELD_BYTES` byte 2 — the app calls this on the descriptor edge,
-    /// and it is the **only** way this value moves (see the module doc). Mirrors
-    /// [`Self::set_combo_points`], the other PRIVATE byte out of the same dword.
+    /// Push the server's `PLAYER_FIELD_BYTES` byte 2, the only way this value moves.
     pub fn set_action_bar_toggles(&mut self, toggles: u8) {
         self.model_mut().action_bar_toggles = Some(toggles);
     }
 
-    /// What the VM last had pushed into it, or `None` if nothing ever has — the app's own read,
-    /// and the tests'. `None` and `Some(0)` are indistinguishable to Lua by design: with no local
-    /// player the reference's chain fails soft and the getter returns four `nil`s, which is exactly
-    /// what a zero byte returns (§5).
+    /// The last pushed byte. Lua reads `None` as a zero byte, four `nil`s, as the reference does
+    /// with no local player (`0x4e7660`).
     pub fn action_bar_toggles(&self) -> Option<u8> {
         self.model_ref().action_bar_toggles
     }
 
-    /// Drain the `CMSG_SET_ACTIONBAR_TOGGLES` payloads queued since the last call — one per
-    /// `SetActionBarToggles` call, in order.
-    ///
-    /// A list rather than a "latest wins" slot because the binding gates **nothing**: it has no
-    /// did-it-change test (unlike `ShowHelm`/`ShowCloak`) and no connection check of its own, so
-    /// two calls in a frame are two packets. Dropping one here would be an optimisation the real
-    /// client does not make.
+    /// Drain the queued `CMSG_SET_ACTIONBAR_TOGGLES` payloads, one per `SetActionBarToggles` call:
+    /// the binding has no did-it-change test and no connection check, so two calls are two packets.
     pub fn take_action_bar_toggle_sends(&mut self) -> Vec<u8> {
         std::mem::take(&mut self.model_mut().action_bar_toggle_sends)
     }
@@ -82,10 +40,8 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetActionBarToggles() -> four values, each the NUMBER 1 or nil (`0x6f3810` pushes tag 3 with
-    // the double 1.0; `0x6f37f0` pushes tag 0). Never booleans — callers write `if toggle then`,
-    // and the WoW `1`-or-`nil` idiom is what the reference's own `SHOW_MULTI_ACTIONBAR_n` globals
-    // then hold. Return N tests bit `1 << (N-1)`, the exact inverse of the setter's map.
+    // GetActionBarToggles() -> four values, each the number 1 (`0x6f3810`) or nil (`0x6f37f0`),
+    // never a boolean; return N tests bit N-1.
     g.set(
         "GetActionBarToggles",
         lua.create_function(|lua, ()| {
@@ -104,16 +60,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetActionBarToggles(a, b, c, d) -> nothing. Four argument slots, no more: a fifth is never
-    // fetched (§2), which matters because the shipped Options panel passes one.
-    //
-    // The arguments are read through `0x6f1c10`, NOT Lua truthiness ([`bool_or_default`]) — the
-    // panel that calls this hands option bindings the strings "0"/"1", and `"0"` is truthy in Lua.
-    // The default at this call site is FALSE (`0x4e76f4 push 0x0`), so an omitted argument is off.
-    //
-    // Nothing local is written: the byte we hold is the server's, and only the server's push moves
-    // it (module doc). A `Set` that never reaches the server therefore leaves the UI showing the
-    // truth rather than a lie.
+    // SetActionBarToggles(a, b, c, d) -> nothing. Arguments coerce through `0x6f1c10`, not Lua
+    // truthiness, so the Options panel's "0" is off; the default is false (`0x4e76f4`). Nothing
+    // local is written: only the server moves the byte.
     g.set(
         "SetActionBarToggles",
         lua.create_function(|lua, args: MultiValue| {
@@ -137,7 +86,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// The argument→bit map, read straight off `0x4e7703 shl al,cl` with `cl = argIndex − 1`.
+    /// Argument N sets bit N-1 (`0x4e7703`).
     #[test]
     fn the_four_arguments_pack_into_bits_0_through_3() {
         let mut s = UiScript::new().unwrap();
@@ -158,8 +107,7 @@ mod tests {
         }
     }
 
-    /// The coercion is `0x6f1c10`, not `if arg then` — and the case that proves it is the one the
-    /// reference's own Options panel produces. `"0"` is truthy in Lua 5.0/5.1; here it is OFF.
+    /// The coercion is `0x6f1c10`: the Options panel's `"0"`, truthy in Lua, is off.
     #[test]
     fn the_arguments_are_coerced_the_binarys_way_not_luas() {
         let mut s = UiScript::new().unwrap();
@@ -171,7 +119,7 @@ mod tests {
             r#"the strings the panel passes: "0" is FALSE, where Lua truthiness says true"#
         );
 
-        // The number arm TRUNCATES toward zero (`0x40a2b0`, RC = chop) — it does not round.
+        // A number truncates toward zero (`0x40a2b0`).
         s.run("SetActionBarToggles(0.5, -0.9, 1.5, 0)").unwrap();
         assert_eq!(
             s.take_action_bar_toggle_sends(),
@@ -179,7 +127,6 @@ mod tests {
             "fractions inside (-1, 1) truncate to 0 and read false; 1.5 truncates to 1"
         );
 
-        // The keyword and letter arms.
         s.run(r#"SetActionBarToggles("on", "off", "enabled", "disabled")"#)
             .unwrap();
         assert_eq!(s.take_action_bar_toggle_sends(), vec![0x05]);
@@ -187,12 +134,10 @@ mod tests {
             .unwrap();
         assert_eq!(s.take_action_bar_toggle_sends(), vec![0x05]);
 
-        // Booleans, the spelling our own Lua uses.
         s.run("SetActionBarToggles(true, false, true, false)")
             .unwrap();
         assert_eq!(s.take_action_bar_toggle_sends(), vec![0x05]);
 
-        // The default arm (`push 0x0` at this call site) — a table, and an unrecognised string.
         s.run(r#"SetActionBarToggles({}, "maybe", 1, 1)"#).unwrap();
         assert_eq!(
             s.take_action_bar_toggle_sends(),
@@ -201,10 +146,6 @@ mod tests {
         );
     }
 
-    /// The shipped `UIOptionsFrame_Save` calls this with **five** arguments
-    /// (`…, ALWAYS_SHOW_MULTIBARS`). The binding's loop stops at four and never fetches the fifth,
-    /// so it reaches neither the byte nor the wire — the reason that option is the only one of the
-    /// five FrameXML saves locally.
     #[test]
     fn a_fifth_argument_is_accepted_and_dropped() {
         let mut s = UiScript::new().unwrap();
@@ -218,9 +159,6 @@ mod tests {
         );
     }
 
-    /// A `Set` starts from **zero** and ORs at most four bits, so any high nibble the server held
-    /// is destroyed by the next post. Faithful, not tidy: it is what two accumulator writes
-    /// image-wide amount to.
     #[test]
     fn a_set_destroys_whatever_the_server_held_above_the_low_nibble() {
         let mut s = UiScript::new().unwrap();
@@ -233,14 +171,11 @@ mod tests {
         );
     }
 
-    /// The getter reads the **app-pushed descriptor byte**, tests only bits 0..3, and returns the
-    /// NUMBER 1 or nil — never a boolean, never `0`.
     #[test]
     fn the_getter_returns_four_ones_or_nils_from_the_pushed_byte() {
         let mut s = UiScript::new().unwrap();
 
-        // Nothing pushed: four nils, and no error. Indistinguishable from a zero byte, exactly as
-        // "no local player" is in the reference (§5).
+        // Nothing pushed reads as a zero byte, as no local player does (`0x4e7660`).
         assert!(s
             .eval::<bool>(
                 "local a,b,c,d = GetActionBarToggles() \
@@ -262,7 +197,7 @@ mod tests {
             "the NUMBER 1 (0x6f3810 pushes tag 3 / double 1.0), never the boolean true"
         );
 
-        // Bits 0x10..0x80 are loaded but never tested — a byte of 0xf0 reads as all four off.
+        // The high nibble is never tested.
         s.set_action_bar_toggles(0xf0);
         assert!(s
             .eval::<bool>(
@@ -272,9 +207,6 @@ mod tests {
             .unwrap());
     }
 
-    /// Round trip: what the setter packs is what the getter reads back — but only once the value
-    /// has travelled through the app's push, because the setter deliberately does not touch the
-    /// local copy. The stale read in the middle is the mechanism, not an oversight (§4.1).
     #[test]
     fn the_setter_does_not_touch_the_local_copy_so_the_read_lags_a_round_trip() {
         let mut s = UiScript::new().unwrap();
@@ -291,7 +223,7 @@ mod tests {
 
         let sent = s.take_action_bar_toggle_sends();
         assert_eq!(sent, vec![0x03]);
-        // The server echoes it back through UPDATE_OBJECT; now the getter agrees.
+        // The server's `SMSG_UPDATE_OBJECT` echo.
         s.set_action_bar_toggles(sent[0]);
         assert!(s
             .eval::<bool>(
@@ -301,8 +233,6 @@ mod tests {
             .unwrap());
     }
 
-    /// No did-it-change gate and no connection test: two calls in a frame are two packets, in
-    /// order. The binding returns zero Lua values either way, so nothing upstream can tell.
     #[test]
     fn every_call_queues_a_packet_and_returns_nothing() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/addon.rs b/crates/benilla-ui/src/script/addon.rs
index 3de8c80a..31185a6a 100644
--- a/crates/benilla-ui/src/script/addon.rs
+++ b/crates/benilla-ui/src/script/addon.rs
@@ -1,40 +1,8 @@
-//! **The AddOn API** (1188 phase 2) — the eleven globals an addon manager and a demand-loader use,
-//! over a registry the host fills at discovery.
-//!
-//! Every name here is in the 1.12.1 client's own `_G` with origin `engine`
-//! (`reference/1.12-globals.tsv`), so all eleven are ours to implement in Rust and the set is
-//! measured rather than remembered. `SaveAddOns`/`ResetAddOns`/`GetAddOnEnableState` are
-//! deliberately **not** here: they exist only in the *glue* namespace (`Interface\GlueXML\
-//! AddonList.lua`), which is a different `_G` from the in-world one this VM is.
-//!
-//! ## The shapes are the reference's, read off its own call sites
-//!
-//! Not from memory — from `Interface\GlueXML\AddonList.lua` and `FrameXML\UIParent.lua` in the
-//! 1.12 MPQs:
-//!
-//! ```lua
-//! name, title, notes, url, loadable, reason, security, newVersion = GetAddOnInfo(index)
-//! local loaded, reason = LoadAddOn(name)          -- UIParent.lua's UIParentLoadAddOn
-//! ```
-//!
-//! `reason` is a **token**, spliced by the reference into `getglobal("ADDON_"..reason)` — so its
-//! spelling is load-bearing and its full set is enumerable from `GlobalStrings.lua`: `MISSING`,
-//! `DISABLED`, `CORRUPT`, `BANNED`, `INSECURE`, `INTERFACE_VERSION`, `NOT_DEMAND_LOADED`, the
-//! `DEP_*` mirrors of each, and `UNKNOWN_ERROR`. `security` is likewise a token, matched against
-//! `"SECURE"`/`"INSECURE"`/`"BANNED"` by the glue's icon picker.
-//!
-//! **Index or name, everywhere.** Every verb takes either, 1-based, because the reference's do.
-//!
-//! ## The load law lives next door
-//!
-//! Every "can this load, and why not" answer comes from [`super::addon_gate`] — the reference's
-//! `AddOn_CanLoad 0x51e780` as one pure function (decision 1292). The RE answer 1191 §6 was
-//! missing has landed (wow-re `addon-version-gate.md`, §5-verified): the version gate is an
-//! exact `== 11200` whose refusal the `checkAddonVersion` CVar suppresses by **actively
-//! resetting** the reason — so `INTERFACE_VERSION` is now enforced here exactly as the client
-//! enforces it, with the *Load out of date AddOns* toggle as the player's escape, instead of
-//! 1191's report-but-never-act interim. The CVar is read live per query (§2.2), which is why a
-//! checkbox click needs nothing but a list repaint.
+//! The in-game AddOn API, the twelve `engine` addon globals of the 1.12 `_G`
+//! (`reference/1.12-globals.tsv`), over a registry the host fills at discovery. A verb that names
+//! an addon takes a 1-based index or a name. `reason` is a token the stock UI splices into
+//! `getglobal("ADDON_"..reason)` (`UIParent.lua:642`), so its spelling is the contract. Verdicts
+//! come from [`super::addon_gate`], the reference's `AddOn_CanLoad` (`0x51e780`).
 
 use std::path::PathBuf;
 
@@ -44,75 +12,51 @@ use super::addon_gate::{can_load, GateRow, Verdict};
 use super::binding_abi::flag;
 use super::Model;
 
-/// A reader for a chain-sourced addon's files, by chain-internal path — what the host seats
-/// through [`super::UiScript::set_addon_chain_reader`] (1957).
+/// Reads a chain-sourced addon's file by its path inside the patch chain.
 pub type AddonChainReader = Box<dyn Fn(&str) -> Option<Vec<u8>>>;
 
-/// [`AddonChainReader`] as the model holds it: shared, so a load can borrow it without holding
-/// the model.
+/// [`AddonChainReader`], shared so a load can call it without holding the model.
 pub(crate) type SharedChainReader = std::rc::Rc<dyn Fn(&str) -> Option<Vec<u8>>>;
 
-/// One addon, as the AddOn API sees it — the host fills this at discovery
-/// ([`super::UiScript::register_addons`]).
+/// One addon as the AddOn API sees it, filled by the host at discovery.
 #[derive(Clone, Debug, Default)]
 pub struct AddOnInfo {
-    /// The folder name. `GetAddOnInfo`'s first return, `ADDON_LOADED`'s `arg1`, and the key every
-    /// other verb resolves a name against (case-insensitively, as the reference does).
+    /// The folder name: `GetAddOnInfo`'s first return and `ADDON_LOADED`'s `arg1`.
     pub name: String,
-    /// `## Title`. `None` when the manifest declares none — and the reference really does return
-    /// nil there, which is why the glue writes `if title then … else SetText(name) end`.
+    /// `## Title`; `None` when absent, which the reference returns as nil.
     pub title: Option<String>,
-    /// `## Notes`.
     pub notes: Option<String>,
-    /// `## URL`.
     pub url: Option<String>,
-    /// `## Secure: 1` — Blizzard's own addons carry it. Drives the `security` token.
+    /// `## Secure: 1`, which Blizzard's own addons carry; drives the `security` token.
     pub secure: bool,
-    /// `## LoadOnDemand: 1`.
     pub load_on_demand: bool,
     /// `## Dependencies` / `## RequiredDeps`.
     pub dependencies: Vec<String>,
     /// Every `## Key: Value` in manifest order, for `GetAddOnMetadata`.
     pub directives: Vec<(String, String)>,
-    /// The `.toc`'s ordered file list — what `LoadAddOn` runs.
+    /// The `.toc`'s file list in order: what `LoadAddOn` runs.
     pub files: Vec<String>,
-    /// `## SavedVariables` — globals restored from, and written to, the account-scoped file.
+    /// `## SavedVariables`: globals restored from and written to the account-wide file.
     pub saved_variables: Vec<String>,
-    /// `## SavedVariablesPerCharacter` — the same, per character. Loaded **second**, so a
-    /// per-character value wins over the account one (`0x51f4b5` then `0x51f53b`).
+    /// `## SavedVariablesPerCharacter`, loaded after the account file so its values win.
     pub saved_variables_per_character: Vec<String>,
-    /// Enable state, from `AddOns.txt`. An addon nobody has ever disabled is enabled.
+    /// Enable state from `AddOns.txt`; an addon never disabled is enabled.
     pub enabled: bool,
-    /// `enabled` as registration found it — the last-SAVED state, which `ResetDisabledAddOns`
-    /// reverts to. Stamped by [`super::UiScript::register_addons`]; callers need not set it.
+    /// The last-saved `enabled`, which `ResetDisabledAddOns` reverts to; set by `register_addons`.
     pub saved_enabled: bool,
-    /// Has it loaded this session?
     pub loaded: bool,
-    /// `## Interface` as the client parses it (`Toc::interface_version` — the leading integer,
-    /// `0` when the line is absent). What the version gate compares (decision 1292).
+    /// `## Interface`'s leading integer, 0 when absent: what the version gate compares.
     pub interface: u32,
-    /// **The server excluded this record from the Lua index space** — `[rec+0x29]`, which
-    /// `AddOn_ReadAddonInfoReply 0x51da70` sets to 1 for every `SMSG_ADDON_INFO` record whose
-    /// `status` byte is **2** (`0x51db84`), and which the array rebuild then drops (`0x51dc4f
-    /// mov al,[ebx+0x29]` / `0x51dc54 jne`). It is written nowhere else but the ctor's zero
-    /// (`0x52059f`), so an addon the reply never covers stays visible.
-    ///
-    /// The reply covers exactly the `## Secure:` addons, in the order the client sent them, and
-    /// the 2006 retail capture answers `status = 2` for all twelve — which is why the stock
-    /// AddOns list shows the player's addons and none of Blizzard's (wow-re
-    /// `system/net/scratch/cmsg-auth-session-addon-block.md` §6).
+    /// Left out of the Lua index: `[rec+0x29]`, set by `0x51da70` for a `SMSG_ADDON_INFO` status of
+    /// 2 (`0x51db84`) and otherwise only zeroed (`0x52059f`), so an addon the reply skips stays
+    /// visible. A retail server answers 2 for all twelve `Blizzard_*` addons.
     pub hidden: bool,
-    /// The addon's files sit in the player's patch chain, not the AddOns folder — Blizzard's own
-    /// LoadOnDemand addons (`Blizzard_TrainerUI` and its eleven siblings), which the reference
-    /// loads through the same `LoadAddOn` path as a player's (1957). Read through the host's
-    /// chain reader ([`super::UiScript::set_addon_chain_reader`]) at
-    /// `Interface/AddOns/<Name>/<file>`; no folder root is needed for them.
+    /// The files live in the patch chain, not the AddOns folder: Blizzard's twelve LoadOnDemand
+    /// addons, read at `Interface/AddOns/<Name>/<file>` and loaded as a player's addon is.
     pub chain: bool,
 }
 
-/// The verbs' own `Usage:` literals, read out of `.data` rather than reconstructed — the message
-/// an addon's error handler prints, so the spelling is the contract. `%s`-free: each is a whole
-/// string in the image.
+/// Each verb's `Usage:` string as the reference's `.data` holds it; an error handler prints it.
 const USAGE_INFO: &str = "Usage: GetAddOnInfo(index or \"name\")"; // 0x842d68
 const USAGE_METADATA: &str = "Usage: GetAddOnMetadata(index or \"name\", \"variable\")"; // 0x842d90
 const USAGE_DEPENDENCIES: &str = "Usage: GetAddOnDependencies(index or \"name\")"; // 0x842dc8
@@ -122,62 +66,26 @@ const USAGE_LOAD_ON_DEMAND: &str = "Usage: IsAddOnLoadOnDemand(index or \"name\"
 const USAGE_LOADED: &str = "Usage: IsAddOnLoaded(index or \"name\")"; // 0x842e70
 const USAGE_LOAD: &str = "Usage: LoadAddOn(index or \"name\")"; // 0x842e98
 
-/// **The `index or "name"` argument every in-game addon verb opens with — and its two raises.**
-///
-/// All eight bindings (`GetAddOnInfo 0x48e390`, `GetAddOnMetadata 0x48e530`,
-/// `GetAddOnDependencies 0x48e5e0`, `EnableAddOn 0x48e690`, `DisableAddOn 0x48e760`,
-/// `IsAddOnLoadOnDemand 0x48e840`, `IsAddOnLoaded 0x48e8e0`, `LoadAddOn 0x48e980`) open with the
-/// *same eleven instructions*, and the shape has three arms, not one:
-///
-/// ```text
-/// edx=1; call 0x6f34d0            ; lua_isnumber — tag 3 OR a numeric string
-///   je  <string>
-///   call 0x6f3620 / 0x40a2b0      ; lua_tonumber, then double->int32 TRUNCATING toward zero
-///   dec eax                       ; the index is 1-BASED
-///   call 0x51df00                 ; name-at(index0); NULL is the bounds failure
-///   jne <shared>
-///   call 0x51def0                 ; the addon COUNT
-///   luaL_error("AddOn index must be in the range of 1 to %d" /*0x837d70*/, count)
-/// <string>:
-///   call 0x6f3510                 ; lua_isstring
-///   je  <usage>
-///   call 0x6f3690                 ; lua_tostring — used AS GIVEN, never validated here
-/// <usage>:
-///   luaL_error("Usage: <Verb>(index or \"name\")")
-/// ```
-///
-/// **`luaL_error 0x6f4940` does not return** ([`super::binding_abi`]): it longjmps, so both arms
-/// abandon the caller's statement. We answered a placeholder, a `nil` or a silent no-op for every
-/// one of them — the failure mode that module's header names: *"a client that answers `nil` there
-/// keeps executing a statement the real client never finishes."*
-///
-/// Three consequences that are easy to get wrong and are all byte-read:
-///
-/// - **The bound is UNSIGNED** (`0x51df00 cmp ecx,[0xbe1b90]; jb`), so `f(0)` decrements to
-///   `0xFFFFFFFF` and raises by the same route as `f(count+1)`.
-/// - **A numeric STRING is an INDEX**, because `0x6f34d0` coerces one — `GetAddOnInfo("2")` is the
-///   second addon, not an addon named `2`.
-/// - **A name is never checked against the registry by this prologue.** Each verb's own body
-///   decides what a miss means, and they do not agree: `GetAddOnInfo` echoes the name back with
-///   placeholders, `IsAddOnLoaded` answers nil, `GetAddOnDependencies` answers nothing.
+/// The `index or "name"` argument, read by the prologue all eight in-game verbs share
+/// (`GetAddOnInfo 0x48e390`, `GetAddOnMetadata 0x48e530`, `GetAddOnDependencies 0x48e5e0`,
+/// `EnableAddOn 0x48e690`, `DisableAddOn 0x48e760`, `IsAddOnLoadOnDemand 0x48e840`,
+/// `IsAddOnLoaded 0x48e8e0`, `LoadAddOn 0x48e980`). A numeric string is an index. An index out of
+/// range, or a non-string, raises through `luaL_error` (`0x6f4940`), which does not return; a
+/// name passes unchecked, and each verb answers a miss its own way.
 enum AddonKey {
     /// A bounds-checked 0-based position in the registry.
     Index(usize),
-    /// A name exactly as the caller spelled it — unvalidated, per the prologue above.
     Name(String),
 }
 
-/// The prologue itself. `usage` is the verb's own `.data` literal, verbatim.
+/// The prologue; `usage` is the verb's own `.data` string.
 fn addon_key(lua: &Lua, model: &Model, key: &Value, usage: &'static str) -> mlua::Result<AddonKey> {
-    // `lua_isnumber 0x6f34d0` — and `coerce_number` is its exact analogue, numeric strings and all.
+    // `coerce_number` is `lua_isnumber` (`0x6f34d0`), numeric strings included.
     if let Some(n) = lua.coerce_number(key.clone())? {
-        // `_ftol 0x40a2b0` truncates toward zero (not `floor`), then `dec eax`, then an unsigned
-        // compare — so the whole out-of-range family collapses onto one `u32` bound test.
+        // `_ftol` (`0x40a2b0`) truncates; minus one, compared unsigned, so 0 raises like count + 1.
         let index0 = (n as i64 as i32).wrapping_sub(1) as u32 as usize;
-        // **The index space is NOT the registry** (decision 2175). `0x51df00` reads
-        // `[[0xbe1b94] + 4*idx]` — the flat, Title-sorted, hidden-filtered name array — and its
-        // bound is that array's own count `[0xbe1b90]`, which `GetNumAddOns 0x51def0` returns.
-        // The registry list is a different order over a different set.
+        // An index into the sorted, filtered name array, not the registry (`0x51df00` reads
+        // `[[0xbe1b94] + 4*idx]`, bound `[0xbe1b90]`); the message is `0x837d70`'s.
         return match model.addon_index.get(index0) {
             Some(&row) => Ok(AddonKey::Index(row)),
             None => Err(mlua::Error::RuntimeError(format!(
@@ -186,36 +94,21 @@ fn addon_key(lua: &Lua, model: &Model, key: &Value, usage: &'static str) -> mlua
             ))),
         };
     }
-    // `lua_isstring 0x6f3510` → `lua_tostring 0x6f3690`. Lossy for the reason 1193/2138 give: a
-    // 5.0 string is bytes, and a stray one costs a glyph, not the call.
+    // `lua_isstring`, `lua_tostring` (`0x6f3510`, `0x6f3690`); lossy, as a Lua string is bytes.
     match key {
         Value::String(s) => Ok(AddonKey::Name(s.to_string_lossy())),
         _ => Err(mlua::Error::RuntimeError(usage.into())),
     }
 }
 
-/// **Rebuild the Lua index space** — the tail block `[0x51dc30, 0x51dcdf)` of
-/// `AddOn_ReadAddonInfoReply 0x51da70`, and the only place that array is ever built
-/// (decision 2175, wow-re `system/ui/scratch/addon-registry-scan-and-order.md` §7).
-///
-/// Three properties, all byte-read, all easy to get wrong:
-///
-/// - **The set is filtered.** `0x51dc4f mov al,[ebx+0x29]` / `0x51dc54 jne` drops every record the
-///   server marked `status = 2`. On a stock install that is all twelve `Blizzard_*` addons, which
-///   is why the AddOns list shows only the player's own.
-/// - **The order is by `## Title:`, not by folder name.** Comparator `0x51deb0` resolves both
-///   sides through `AddOn_GetTitle 0x51df20` and falls back to the folder name only when the
-///   record declares no `Title` (`0x51ded0`/`0x51ded6`), then compares with `SStrCmpI` — case
-///   INSENSITIVE. A materially different permutation from the registry's.
-/// - **No reply, no array.** `[0xbe1b90]` starts at 0 and is written nowhere else, so
-///   `GetNumAddOns()` answers 0 until the server replies.
-///
-/// The reference's `qsort 0x73f727` is **not stable**, so two records with equal keys have no
-/// defined relative order there; ours is stable, which is a strict refinement of "undefined" and
-/// cannot disagree with a defined case.
+/// Rebuild the Lua index array as `AddOn_ReadAddonInfoReply` (`0x51da70`) does in its tail,
+/// `[0x51dc30, 0x51dcdf)`, the array's only builder: hidden records dropped (`0x51dc4f`), the
+/// rest sorted case-insensitively by `## Title`, else folder name (`0x51deb0` through
+/// `AddOn_GetTitle 0x51df20`, `SStrCmpI`). Empty until the server replies. The reference's
+/// `qsort` (`0x73f727`) is unstable, which a stable sort refines.
 fn rebuild_index(model: &mut Model) {
     let Some(hidden) = model.addon_info_hidden.as_ref() else {
-        model.addon_index = Vec::new(); // no reply yet — the reference's own empty array
+        model.addon_index = Vec::new(); // no reply yet, as in the reference
         return;
     };
     let hidden: std::collections::HashSet<&str> = hidden.iter().map(String::as_str).collect();
@@ -232,8 +125,7 @@ fn rebuild_index(model: &mut Model) {
     model.addon_index = index;
 }
 
-/// A name → a position, folded. Names compare case-insensitively for the same reason dependency
-/// lookup does: a `.toc` may spell a name any way.
+/// A name's registry row, case-insensitive: a `.toc` may spell a name any way.
 fn by_name(model: &Model, name: &str) -> Option<usize> {
     model
         .addons
@@ -241,7 +133,7 @@ fn by_name(model: &Model, name: &str) -> Option<usize> {
         .position(|a| a.name.eq_ignore_ascii_case(name))
 }
 
-/// A validated key → a row, for the verbs whose miss answer is "not found" rather than a raise.
+/// A key's registry row, for the verbs that answer an unknown name rather than raise.
 fn row_of(model: &Model, key: &AddonKey) -> Option<usize> {
     match key {
         AddonKey::Index(i) => Some(*i),
@@ -249,8 +141,7 @@ fn row_of(model: &Model, key: &AddonKey) -> Option<usize> {
     }
 }
 
-/// Lower the registry into the gate's rows — ONE adapter, so every verb consults the same law
-/// ([`super::addon_gate`], decision 1292) over the same facts.
+/// The registry as [`super::addon_gate`] rows, the one input every verb's verdict reads.
 fn gate_rows(model: &Model) -> Vec<GateRow<'_>> {
     model
         .addons
@@ -266,10 +157,8 @@ fn gate_rows(model: &Model) -> Vec<GateRow<'_>> {
         .collect()
 }
 
-/// The live `checkAddonVersion` read — the gate's CVar half, re-read per query like the
-/// reference's (`IsAddonVersionCheckEnabled 0x51f180` inside `AddOn_CanLoad`, §2.2). An absent
-/// table (a bare test VM, or a query before the host's seed) answers the registrar default:
-/// check ON, `"1"`.
+/// `checkAddonVersion`, read per query as `IsAddonVersionCheckEnabled` (`0x51f180`) does; unset,
+/// it is the registered default `"1"`, check on.
 fn version_check(model: &Model) -> bool {
     model
         .cvars
@@ -277,10 +166,8 @@ fn version_check(model: &Model) -> bool {
         .is_none_or(|s| s.value != "0")
 }
 
-/// [`can_load`] over the registry, in the in-game flavour (`dl=1` — the surface these verbs
-/// are): the addon's own verdict, with the loaded short-circuit the in-game `GetAddOnInfo`
-/// applies (`0x48e390`: an already-loaded addon reports loadable/nil before the gate runs, so
-/// flipping its toggle mid-session cannot retroactively mark it unloadable).
+/// [`can_load`] in the in-game flavour (`dl=1`). A loaded addon is loadable before the gate
+/// runs, as in `0x48e390`, so disabling it mid-session does not mark it unloadable.
 fn verdict(model: &Model, i: usize) -> Verdict {
     if model.addons[i].loaded {
         return Verdict::Loadable;
@@ -305,8 +192,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     g.set(
         "GetNumAddOns",
         lua.create_function(|lua, ()| {
-            // `0x51def0` is six bytes: `return [0xbe1b90]` — the count of the SORTED array, not the
-            // registry size (decision 2175).
+            // `0x51def0` returns `[0xbe1b90]`, the sorted array's count, not the registry's.
             Ok(lua
                 .app_data_ref::<Model>()
                 .expect("model")
@@ -315,48 +201,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `name, title, notes, enabled, loadable, reason, security` — SEVEN values, and slot 4 is
-    // **`enabled`**, not `url`.
-    //
-    // **The client registers `GetAddOnInfo` TWICE, as two different functions**, and this is the
-    // in-game one. wow-re `system/ui/scratch/addon-version-gate.md`: glue `0x46d460` returns EIGHT
-    // with `url` at slot 4 and `newVersion` at 8; in-game `0x48e390` returns SEVEN with `enabled`
-    // at slot 4 and no `url` at all. They differ in behaviour too — the in-game one passes `dl=1`,
-    // so `NOT_DEMAND_LOADED` is reachable here and never from glue, and it short-circuits an
-    // already-loaded addon to `1, nil` before the gate.
-    //
-    // We shipped the GLUE shape in the IN-GAME VM. Slots 5/6/7 aligned by luck; slot 4 did not, and
-    // it is the one the ecosystem reads:
-    //
-    //     local name, _, _, enabled, loadable = GetAddOnInfo(major)   -- AceLibrary-1.0:400
-    //
-    // `## URL` is rare, so `enabled` came back nil for nearly every addon and Ace's
-    // `if enabled and loadable` refused to load its own dependency. 70 corpus folders reach it
-    // (AceLibrary/AceAddon replicated — one library, which is what makes it wide rather than
-    // narrow). Nothing errored: a nil where a flag belongs is a legal Lua value.
-    //
-    // `enabled` is the number 1 or nil, never boolean `true` — every push in these functions is
-    // `lua_pushnumber(1.0)` via `0x6f3810`, with no `lua_pushboolean` anywhere. Same for
-    // `loadable`. `flag` already answers in that shape.
-    //
-    // `url` is not lost, it moves to where the client keeps it in-game: `GetAddOnMetadata(name,
-    // "URL")`.
+    // In-game `0x48e390` returns seven: `name, title, notes, enabled, loadable, reason,
+    // security`, the flags the number 1 or nil (`lua_pushnumber` via `0x6f3810`). The glue's
+    // `0x46d460` returns eight, `url` fourth; in-game the URL is `GetAddOnMetadata(name, "URL")`.
     g.set(
         "GetAddOnInfo",
         lua.create_function(|lua, key: Value| {
             let model = lua.app_data_ref::<Model>().expect("model");
-            // **The two argument forms miss differently** (decision 1845). The numeric one cannot
-            // reach here at all — [`addon_key`] has already raised the range error for it.
             let i = match addon_key(lua, &model, &key, USAGE_INFO)? {
                 AddonKey::Index(i) => i,
                 AddonKey::Name(name) => match by_name(&model, &name) {
                     Some(i) => i,
-                    // The STRING form is not existence-checked: it answers seven placeholders, two
-                    // of which are not nil — and **slot 1 is the caller's own string echoed back**
-                    // (`0x48e401`, non-NULL by `lua_isstring`). We used to answer the literal
-                    // `"NoSuchAddon"`, which is the wow-re note's *example call*, not a constant
-                    // the image contains. Slot 4 is `enabled` in-game (the glue table's fourth is
-                    // `url`, and its eighth is an appended `newVersion` — nothing shifts).
+                    // An unknown name answers placeholders, the caller's own string first
+                    // (`0x48e401`).
                     None => {
                         return Ok(MultiValue::from_vec(vec![
                             lua_str(lua, &name)?,
@@ -370,9 +227,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     }
                 },
             };
-            // The one arbiter (decision 1292): loaded short-circuit, then `AddOn_CanLoad` in the
-            // in-game flavour — so NOT_DEMAND_LOADED and INTERFACE_VERSION are reachable here,
-            // exactly as `0x48e390` reports them.
             let reason = verdict(&model, i).token();
             let a = &model.addons[i];
             Ok(MultiValue::from_vec(vec![
@@ -395,8 +249,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, key: Value| {
             let model = lua.app_data_ref::<Model>().expect("model");
             let key = addon_key(lua, &model, &key, USAGE_LOADED)?;
-            // `0x51e6f0` takes the resolved NAME and answers `[rec+0x18]`; a miss pushes nil
-            // (`0x48e95b`), so an unknown name is one value, not a raise.
+            // `0x51e6f0` answers the record's loaded byte `[rec+0x18]`; an unknown name pushes nil
+            // (`0x48e95b`).
             Ok(flag(
                 row_of(&model, &key).is_some_and(|i| model.addons[i].loaded),
             ))
@@ -414,15 +268,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Varargs of dependency names — the glue folds them into a tooltip line with `AddonTooltip_
-    // BuildDeps(GetAddOnDependencies(id))`, so "none" is zero returns, not an empty string.
+    // One return per dependency, none for none (the glue's `AddonList.lua:137` takes varargs).
     g.set(
         "GetAddOnDependencies",
         lua.create_function(|lua, key: Value| {
             let model = lua.app_data_ref::<Model>().expect("model");
             let key = addon_key(lua, &model, &key, USAGE_DEPENDENCIES)?;
-            // A name the registry does not hold reaches `0x51e350` and comes back NULL, which
-            // takes `0x48e68a` — zero values, no raise.
+            // An unknown name comes back NULL from `0x51e350` and answers nothing (`0x48e68a`).
             let Some(i) = row_of(&model, &key) else {
                 return Ok(MultiValue::new());
             };
@@ -434,15 +286,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The raw `## Key: Value`, by key — how an addon reads its own `## Version`.
+    // The raw `## Key: Value` by key, as an addon reads its own `## Version`.
     g.set(
         "GetAddOnMetadata",
         lua.create_function(|lua, (key, field): (Value, Value)| {
             let model = lua.app_data_ref::<Model>().expect("model");
             let key = addon_key(lua, &model, &key, USAGE_METADATA)?;
-            // Argument 2 is gated by its own `lua_isstring` (`0x48e59c`, edx=2) onto the SAME
-            // usage raise (`0x48e5cb`) — so `GetAddOnMetadata("Foo")` raises rather than
-            // answering nil.
+            // A missing or non-string argument 2 raises the same `Usage:` (`0x48e59c`, `0x48e5cb`).
             let field = super::binding_abi::string_arg(lua, field, USAGE_METADATA)?;
             let Some(i) = row_of(&model, &key) else {
                 return Ok(Value::Nil);
@@ -458,14 +308,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // **One argument, index or name — the `(character, index)` form is GLUE-ONLY** (byte-carved,
-    // wow-re `addon-enable-store.md`: in-game `0x48e690`/`0x48e760` read arg1 alone and key the
-    // store on `0x5abdc0()`, the logged-in character; the two-argument shape belongs to the glue
-    // registrars `0x46d7b0`/`0x46d8a0`, and our glue screen is native — no caller exists).
-    // A numeric index out of range is a **Lua error** in the reference (`luaL_error` via
-    // `0x51df00`); an unknown NAME is where we diverge, disclosed: the reference creates a
-    // phantom enable-hash entry for the typo, we no-op — the safer direction, and `resolve`'s
-    // established semantics (1191).
+    // One argument, keyed on the logged-in character (`0x48e690`, `0x48e760`, via `0x5abdc0`);
+    // the `(character, index)` form is the glue's (`0x46d7b0`, `0x46d8a0`). Deviation: an unknown
+    // name is a no-op, where the reference adds an enable-hash entry for it, so that a typo leaves
+    // no row behind.
     for (name, on, usage) in [
         ("EnableAddOn", true, USAGE_ENABLE),
         ("DisableAddOn", false, USAGE_DISABLE),
@@ -483,8 +329,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // No arguments read at all (`0x48e720`/`0x48e7f0` — the loop re-evaluates the bound and the
-    // current character each iteration; ours is one pass over the same store).
+    // No arguments read (`0x48e720`, `0x48e7f0`).
     for (name, on) in [("EnableAllAddOns", true), ("DisableAllAddOns", false)] {
         g.set(
             name,
@@ -498,13 +343,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // `ResetDisabledAddOns 0x48e830` — **revert-to-last-saved**, byte-carved (wow-re
-    // `addon-enable-store.md`): the reference destroys the current character's enable hash and
-    // reloads it from the on-disk `AddOns.txt` — so unsaved toggles of BOTH polarities revert,
-    // and a disable already on disk stays disabled. Within one session the current character's
-    // file is immutable until the shutdown tail writes it (the glue can only edit it with no
-    // session up), so the registration-time `enabled` — read from that very file — IS the
-    // last-saved state, and reverting to it is the same operation without re-reading disk.
+    // `0x48e830` reloads the enable state from `AddOns.txt`, which is unchanged until the shutdown
+    // write, so reverting to the state as registered is the same thing.
     g.set(
         "ResetDisabledAddOns",
         lua.create_function(|lua, ()| {
@@ -516,7 +356,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // loaded, reason — see `load_addon`.
     g.set(
         "LoadAddOn",
         lua.create_function(|lua, key: Value| {
@@ -544,15 +383,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Load one addon on demand, dependencies first — `AddOn_Load 0x51f240` reached from `LoadAddOn`
-/// rather than from the startup sweep.
-///
-/// **This runs inside a Lua binding, synchronously**, which is the whole reason the loader takes
-/// `&Lua` (see `crate::loader::load_into`): the reference's `UIParentLoadAddOn` does
-/// `local loaded = LoadAddOn(name)` and touches the addon's frames on the next line, so a deferred
-/// load would be a different function wearing the same name.
-///
-/// `Err` carries the reference's own reason token.
+/// `AddOn_Load` (`0x51f240`), dependencies first; `Err` is the reason token. Synchronous inside
+/// the Lua call, as stock callers use the addon on the next line (`UIParent.lua:577`).
 fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
     let (name, root, files, deps, already, chain, chain_reader) = {
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -568,21 +400,17 @@ fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
         )
     };
     if already {
-        return Ok(()); // the reference answers a redundant load with success, not an error
+        return Ok(()); // a redundant load succeeds, as in the reference
     }
-    // The one arbiter (decision 1292): the reference's own shape — `LoadAddOn 0x48e980` refuses
-    // through `AddOn_CanLoad` (via `AddOn_Load`'s step 3) and re-derives the reason from the
-    // same gate on failure. The version gate is in here now: an out-of-date addon demand-loads
-    // only under force-load, exactly as `0x48ea8c`'s carve records.
+    // `LoadAddOn` (`0x48e980`) refuses through `AddOn_CanLoad` and takes the reason from the same
+    // gate; an out-of-date addon loads only with the version check off (`0x48ea8c`).
     {
         let model = lua.app_data_ref::<Model>().expect("model");
         if let refused @ Verdict::Refused { .. } = verdict(&model, i) {
             return Err(refused.token().expect("a refusal always carries a token"));
         }
     }
-    // Where this addon's bytes come from: the AddOns folder for a player's addon, the patch chain
-    // for Blizzard's own LoadOnDemand addons (`AddOnInfo::chain`). Either absent is `MISSING` —
-    // a hermetic capture has no folder, a bare VM has no chain.
+    // An absent source (a capture has no folder, a bare VM no chain) is `MISSING`.
     let read: Reader = if chain {
         let Some(reader) = chain_reader else {
             return Err("MISSING".into());
@@ -595,37 +423,17 @@ fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
         Box::new(move |req: &str| read_under(&root, req))
     };
 
-    // ── The *loaded* stamp goes HERE, before the dependency walk — and it is the whole reason a
-    // dependency cycle terminates (decision 2139).
-    //
-    // `AddOn_Load 0x51f240` carries **no re-entrancy guard of its own**: an image-wide census of
-    // the visiting byte `[UIADDON+0x2d]` puts every live site inside `AddOn_CanLoad 0x51e780`
-    // (writers `0x5205a8`/`0x51e8ae`/`0x51e8f1`, reader `0x51e812`) and none in the loader. What
-    // bounds the recursion is this byte: `0x51f313 mov byte [rec+0x18],1` sits between
-    // `0x51f311 test eax,eax` and `0x51f317 jbe` — a flag-neutral, therefore **unconditional**
-    // store — in the dependency loop's PREAMBLE, ahead of both the OptionalDeps body
-    // (`0x51f320`) and the required-dep body (`0x51f343`). So a re-entered frame hits the
-    // already-loaded early-out at `0x51f2d6`/`0x51f2db` and returns 1.
-    //
-    // We stamped it *after* the recursion instead, which is why `LoadAddOn` on two mutually
-    // dependent LoadOnDemand addons overflowed the stack and took the process down with SIGABRT —
-    // not a Lua error, so nothing `pcall` or the error handler could reach.
-    //
-    // **The gate strictly dominates this store** (`0x51f2fa`/`0x51f301` precede `0x51f313`), so a
-    // refusal leaves the byte clear and the load stays retryable. That ordering is why the stamp
-    // is here and not at the top of the function.
-    //
-    // **The consequence is real and is the reference's own**: inside a cycle an addon is flagged
-    // loaded before its own files run, so `IsAddOnLoaded("A")` answers 1 for the whole of B's
-    // execution, and `ADDON_LOADED` fires B before A. That is not a wart we are copying blindly —
-    // it is what makes the recursion finite, and wow-re executed it against the real bytes.
+    // Loaded is stamped after the gate (`0x51f2fa`), so a refusal stays retryable, and before the
+    // dependencies, which is what ends a cycle: `AddOn_Load` has no re-entrancy guard, but its
+    // store `0x51f313` precedes both dependency loops (`0x51f320`, `0x51f343`), so a re-entry
+    // takes the loaded early-out (`0x51f2d6`). Inside a cycle, then, `IsAddOnLoaded("A")` is 1
+    // while B runs and `ADDON_LOADED` fires B before A, as in the reference.
     {
         let mut model = lua.app_data_mut::<Model>().expect("model");
         model.addons[i].loaded = true;
     }
 
-    // The gate said yes, so a dependency failing HERE is a load-time failure (its files errored,
-    // it was uninstalled mid-session) — still mapped to the DEP_ mirror, applied once.
+    // Past the gate, a dependency that fails to load maps to its `DEP_` reason.
     for dep in &deps {
         let d = {
             let model = lua.app_data_ref::<Model>().expect("model");
@@ -644,7 +452,8 @@ fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
                 if !loaded {
                     load_addon(lua, d).map_err(|r| {
                         if r.starts_with("DEP_") {
-                            r // §2.3: the prefix applies exactly once at any nesting depth
+                            // `DEP_` applies once at any depth (`0x51e8ce`, `0x51e8cf`).
+                            r
                         } else {
                             format!("DEP_{r}")
                         }
@@ -655,25 +464,17 @@ fn load_addon(lua: &Lua, i: usize) -> Result<(), String> {
     }
 
     run_files(lua, &name, &read, &files);
-    // `Bindings.xml` (1188 phase 4) attaches here, between the files and the saved variables.
+    // `Bindings.xml` loads between the files and the saved variables.
     load_bindings(lua, &name, &read);
     load_saved_variables(lua, i);
-    // The verified position: after the files, at the end of this addon's load (`0x51f5ad`).
+    // `ADDON_LOADED` closes the addon's load (`0x51f5ad`).
     super::event::fire_global(lua, "ADDON_LOADED", &[super::ScriptValue::Str(name)]);
     Ok(())
 }
 
-/// Register this addon's `Bindings.xml` into the key-binding table (decision 1188 phase 4) — the
-/// demand-load twin of what the host's startup walk does at the same position.
-///
-/// **Position is the mechanism here too**: the reference loads it at `0x51f400`, after the
-/// addon's own `.toc` files and before its saved variables. After the files, because a binding's
-/// body calls the functions those files define; before the saved variables, because they are the
-/// next step of the same verified sequence and `ADDON_LOADED` closes it.
-///
-/// A missing file is the normal case and silent — most addons declare no bindings. `Bindings.xml`
-/// is the reference's own spelling and the only one probed; the sandbox is [`read_under`]'s, so
-/// this reads exactly what the addon's other files may read and nothing else.
+/// Register the addon's `Bindings.xml` where the reference loads it (`0x51f400`): after the
+/// addon's files, whose functions its bindings call, and before its saved variables. A missing
+/// file is the normal case and silent; it reads through the same sandbox as the other files.
 fn load_bindings(lua: &Lua, name: &str, read: &Reader) {
     let path = crate::loader::join_ref(name, "Bindings.xml");
     let Some(bytes) = read(&path) else {
@@ -681,24 +482,14 @@ fn load_bindings(lua: &Lua, name: &str, read: &Reader) {
     };
     match crate::bindings_xml::parse(&crate::source::decode(&bytes)) {
         Ok(bindings) => super::keybind::register_addon_bindings(lua, name, &bindings),
-        // Reported rather than swallowed, like a failed saved-variables chunk: a binding file that
-        // stopped parsing means keys silently stop working, which is exactly what a player cannot
-        // diagnose on their own.
+        // Reported, not swallowed: otherwise a broken binding file leaves keys dead silently.
         Err(e) => log_error(lua, &format!("{name}/Bindings.xml: {e}")),
     }
 }
 
-/// Execute this addon's saved-variables files — **account first, per-character second**, which is
-/// the reference's order (`0x51f4b5` then `0x51f53b`) and therefore why a per-character value wins.
-///
-/// Each file is *executed as a Lua chunk in the shared global state*, not parsed: the reference
-/// does exactly that (`0x704bc0` names the chunk, `0x704ae0` runs `luaL_loadbuffer` +
-/// `lua_pcall`), with no `setfenv` and no restricted environment. A missing file is a silent
-/// no-op (`0x51f4a9`, `0x51f530`) — it is the normal first-run case.
-///
-/// **Position is the mechanism**: this runs after the addon's own files (which assign the
-/// file-scope defaults) and before `ADDON_LOADED` (whose handlers are specified to see the
-/// restored value). Reverse either and the saved value can never win.
+/// Run the addon's saved-variables files, account then per-character (`0x51f4b5`, `0x51f53b`),
+/// as chunks in the shared globals with no `setfenv` (`0x704bc0`, `0x704ae0`), between its files
+/// and `ADDON_LOADED` so saved values win; a missing file is skipped (`0x51f4a9`, `0x51f530`).
 fn load_saved_variables(lua: &Lua, i: usize) {
     let (name, account, character, has_account, has_character) = {
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -713,46 +504,52 @@ fn load_saved_variables(lua: &Lua, i: usize) {
     };
     for (dir, declared) in [(account, has_account), (character, has_character)] {
         if !declared {
-            continue; // an addon that declares nothing has no file, even if one is lying there
+            continue; // declares none: no file is read, even if one exists
         }
         let Some(dir) = dir else { continue };
         let path = dir.join(format!("{name}.lua"));
-        let Ok(bytes) = std::fs::read(&path) else {
-            continue; // absent is the first-run case
+        let bytes = match std::fs::read(&path) {
+            Ok(bytes) => bytes,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue, // the first-run case
+            Err(e) => {
+                // Present but unreadable is held, like a file that will not run.
+                log_error(lua, &format!("{}: {e}", path.display()));
+                let mut model = lua.app_data_mut::<Model>().expect("model");
+                if !model.held_saved_files.contains(&path) {
+                    model.held_saved_files.push(path);
+                }
+                continue;
+            }
         };
         if let Err(e) = run_chunk(
             lua,
             &bytes,
             &crate::script::addon_chunk_name(&name.to_string(), &format!("{name}.lua")),
         ) {
-            // The reference fails this silently. We do not: a settings file that stopped parsing
-            // is exactly the thing a player needs told, and the file is left on disk untouched.
+            // Deviation: the reference fails silently; we report it, as a player needs to know,
+            // and hold the file so the shutdown write keeps it.
             log_error(lua, &format!("{}: {e}", path.display()));
+            let mut model = lua.app_data_mut::<Model>().expect("model");
+            if !model.held_saved_files.contains(&path) {
+                model.held_saved_files.push(path);
+            }
         }
     }
 }
 
-/// Run one addon's `.toc`-listed files, in listed order — the demand-load twin of the host's
-/// `Addon::load_files`, and deliberately the same rules: `.lua` is a chunk, anything else is
-/// FrameXML, and every reference resolves against the *including file's* directory (1186) inside
-/// the AddOns root as the sandbox.
-/// One addon's byte source, by a path relative to the AddOns root (`<Name>/<file>`) — the folder
-/// reader for a player's addon, the chain reader for a Blizzard LoadOnDemand one.
+/// One addon's byte source by path under the AddOns root (`<Name>/<file>`): the folder for a
+/// player's addon, the patch chain for a Blizzard LoadOnDemand one.
 type Reader = Box<dyn Fn(&str) -> Option<Vec<u8>>>;
 
+/// Run the addon's `.toc` files in order, by the startup walk's rules: `.lua` is a chunk,
+/// anything else FrameXML, each path resolved against the including file's directory.
 fn run_files(lua: &Lua, name: &str, read: &Reader, files: &[String]) {
     let provider = |req: &str| -> Option<Vec<u8>> { read(req) };
     for file in files {
         let path = crate::loader::join_ref(name, file);
         let Some(bytes) = read(&path) else {
-            // **A manifest entry the package does not ship is the PACKAGE's defect** — 1450's
-            // rule, and until 2107 this path had its own copy of it that said the opposite.
-            // The reference logs `Couldn't open %s` and carries on
-            // (`diagnostics::record_load_failure`'s doc has the bytes), so the addon still loads
-            // and `IsAddOnLoaded` still answers 1; the miss is retained and warned, never a
-            // script error. It cost 61 corpus addons their session-start row: FuBar's
-            // `LoadLoadOnDemandPlugins` demand-loads 55 plugins whose `.toc`s list a koKR
-            // localization file none of them ships.
+            // The reference logs `Couldn't open %s` and carries on, so the addon still loads and
+            // `IsAddOnLoaded` answers 1; the miss is warned, never a script error.
             load_miss(lua, name, file);
             continue;
         };
@@ -768,18 +565,14 @@ fn run_files(lua: &Lua, name: &str, read: &Reader, files: &[String]) {
         let doc = match crate::framexml::parse(&crate::source::decode(&bytes)) {
             Ok(d) => d,
             Err(e) => {
-                // The walk's severity for the same thing: a document that will not parse is a
-                // load failure, not a raise — the reference answers it with a `FrameXML.log` line
-                // and silence (`Couldn't parse XML in %s` `0x846fd8`, sink severity 2).
+                // A document that will not parse is a load failure, not a raise: the reference
+                // logs `Couldn't parse XML in %s` (`0x846fd8`) to `FrameXML.log` and goes on.
                 load_failure(lua, &format!("{name}/{file}: {e}"));
                 continue;
             }
         };
         let report = crate::loader::load_into(lua, &doc, &path, &provider);
-        // The warnings were dropped on the floor here until 2135 — an unresolved `inherits=`, a
-        // template of the wrong kind, an attribute nobody reads: the addon loads "clean", paints
-        // nothing, and the one thing that knew why was a `LoadReport` that went out of scope.
-        // They carry the `<Addon>/<file>` prefix because a bare loader warning names no document.
+        // Warnings take the `<Addon>/<file>` prefix; a bare loader warning names no document.
         for w in report.warnings {
             crate::script::diagnostics::record_warning(lua, &format!("{name}/{file}: {w}"));
         }
@@ -789,35 +582,25 @@ fn run_files(lua: &Lua, name: &str, read: &Reader, files: &[String]) {
     }
 }
 
-/// A `.toc` line naming a file the package does not contain, classified the one way
-/// ([`crate::script::diagnostics::record_load_failure`]) and logged the one severity (1450: a
-/// player's addon is never an ERROR of ours).
-///
-/// Both halves are the startup walk's, verbatim in effect: the walk pairs its `warn!` with
-/// `report_load_failure`, and this pairs the host warning channel — which the app drains at
-/// `warn!` — with the same retention call. What it deliberately does **not** touch is
-/// [`Model::errors`], the instruments' script-error channel: nothing raised.
+/// A `.toc` file the package does not ship: a load failure at warning severity, as the startup
+/// walk records it, and never in [`Model::errors`], since nothing raised.
 fn load_miss(lua: &Lua, name: &str, file: &str) {
     load_failure(lua, &format!("{name}/{file}: not found"));
 }
 
-/// Record + say out loud, the pair [`log_error`]'s louder sibling makes for a failure that
-/// **raised**. `benilla-ui` has no logger of its own, so the second half goes on the host's
-/// non-fatal warning channel, which the app drains at `warn!` — the walk's own severity for the
-/// same failure.
+/// Record a load failure that did not raise, and warn on the host channel the app drains at
+/// `warn!` (`benilla-ui` has no logger).
 fn load_failure(lua: &Lua, msg: &str) {
     let msg = format!("LoadAddOn: {msg}");
     crate::script::diagnostics::record_load_failure(lua, &msg);
-    // `warn_host_only`, not `record_warning`: `record_load_failure` above has already retained
-    // this exact sentence as a `Load` row, which is the truer kind (the addon is not running).
+    // `warn_host_only`, not `record_warning`: the line above already kept it as a `Load` row.
     lua.app_data_mut::<Model>()
         .expect("model")
         .warn_host_only(msg);
 }
 
-/// `root/rel`, refusing to escape `root` — the AddOns-root sandbox (1186), lexical and applied
-/// before any filesystem call. `join_ref` has already resolved the path, so an escape survives as
-/// a leading `..` and is what the `Normal`-component test rejects.
+/// Read `root/rel`, refusing a path that leaves `root`, lexically before any filesystem call;
+/// `join_ref` has already resolved the path, so an escape shows as a leading `..`.
 fn read_under(root: &std::path::Path, rel: &str) -> Option<Vec<u8>> {
     let rel = std::path::Path::new(rel);
     if rel
@@ -829,9 +612,8 @@ fn read_under(root: &std::path::Path, rel: &str) -> Option<Vec<u8>> {
     std::fs::read(root.join(rel)).ok()
 }
 
-/// Run a chunk that came off disk, from `&Lua` — [`crate::script::UiScript::run_chunk`]'s body for
-/// the demand-load path, which never holds a `UiScript` (1191 §4). Bytes and a BOM strip, for the
-/// reasons in [`crate::source`].
+/// Run a chunk read off disk, BOM stripped: [`crate::script::UiScript::run_chunk`] for the
+/// demand-load path, which has no `UiScript`.
 fn run_chunk(lua: &Lua, bytes: &[u8], name: &str) -> mlua::Result<()> {
     lua.load(crate::source::chunk(bytes))
         .set_name(name)
@@ -839,25 +621,23 @@ fn run_chunk(lua: &Lua, bytes: &[u8], name: &str) -> mlua::Result<()> {
         .exec()
 }
 
-/// Record a load error where the host drains it — the same channel a handler error uses, so a
-/// demand-load failure surfaces the way every other script error does rather than vanishing.
+/// Record a demand-load error as the startup walk does ([`super::UiScript::report_script_error`]):
+/// a `Load` row, dispatched to the player's error handler and put on the host drain.
 fn log_error(lua: &Lua, msg: &str) {
-    lua.app_data_mut::<Model>()
-        .expect("model")
-        .errors
-        .push(format!("LoadAddOn: {msg}"));
+    let msg = format!("LoadAddOn: {msg}");
+    super::diagnostics::record_load_failure(lua, &msg);
+    let mut model = lua.app_data_mut::<Model>().expect("model");
+    model.pending_error_dispatch.push(msg.clone());
+    model.errors.push(msg);
 }
 
-/// The host's push: the discovered registry and the root its files live under.
+/// The host's side: the registry, where its files live, and what to write back.
 impl super::UiScript {
-    /// Seat the host's chain reader — what a chain-sourced addon (`AddOnInfo::chain`) is read
-    /// through, by chain-internal path (1957).
+    /// Seat the reader chain-sourced addons (`AddOnInfo::chain`) are read through.
     pub fn set_addon_chain_reader(&self, reader: AddonChainReader) {
         self.model_mut().addons_chain_reader = Some(std::rc::Rc::from(reader));
     }
-    /// Replace the AddOn registry — called once at world entry, after discovery
-    /// ([`crate::script`]'s `register_bindings` is the same shape: the host owns the facts, the
-    /// engine owns the verbs).
+    /// Replace the AddOn registry; called once at world entry, after discovery.
     pub fn register_addons(
         &mut self,
         mut addons: Vec<AddOnInfo>,
@@ -865,9 +645,7 @@ impl super::UiScript {
         saved_account: Option<PathBuf>,
         saved_character: Option<PathBuf>,
     ) {
-        // The registration-time enable state IS the last-saved state (the host read it off the
-        // enable file moments ago) — snapshot it here so `ResetDisabledAddOns` has its revert
-        // point and no caller has to remember to provide one.
+        // The enable state as registered is the last-saved one, `ResetDisabledAddOns`'s target.
         for a in &mut addons {
             a.saved_enabled = a.enabled;
         }
@@ -876,31 +654,21 @@ impl super::UiScript {
         model.addons_root = root;
         model.addons_saved_account = saved_account;
         model.addons_saved_character = saved_character;
-        // The reference builds the registry at glue login and the Lua array only when the server
-        // answers; our registry is built at world entry, by which time the reply has long landed.
-        // So the rebuild runs here, off whatever the reply said — and does nothing at all if no
-        // reply ever came, which is the reference's own pre-reply state.
+        // The reference builds the array when the server's reply lands, before world entry, so
+        // the rebuild runs here; with no reply the array stays empty, as there.
         rebuild_index(&mut model);
     }
 
-    /// **The `SMSG_ADDON_INFO` (`0x2ef`) verdict** — the names the server answered `status = 2`
-    /// for, which the client stores as `[rec+0x29] = 1` and which the Lua index array then drops
-    /// (decision 2175).
-    ///
-    /// The reply carries no count and no names: it is one record per `## Secure:` addon, in the
-    /// order the client itself sent them in `CMSG_AUTH_SESSION`, so the caller does the pairing
-    /// and hands us the names (wow-re `system/net/scratch/cmsg-auth-session-addon-block.md` §6).
-    /// Calling this with an empty slice is meaningful and different from never calling it: it
-    /// records that a reply arrived and hid nothing.
+    /// Record the `SMSG_ADDON_INFO` (`0x2ef`) verdict, the addons answered status 2; the caller
+    /// pairs the nameless records with `CMSG_AUTH_SESSION`'s order (`0x51da70`). An empty slice
+    /// is a reply that hid nothing, unlike no call at all.
     pub fn note_addon_info_reply(&mut self, hidden: &[String]) {
         let mut model = self.model_mut();
         model.addon_info_hidden = Some(hidden.iter().map(|n| n.to_ascii_lowercase()).collect());
         rebuild_index(&mut model);
     }
 
-    /// Execute one addon's saved-variables files, at the startup walk's verified position — the
-    /// twin of what [`load_saved_variables`] does inside `LoadAddOn`, so both halves restore state
-    /// the same way.
+    /// Run one addon's saved-variables files at the startup walk's position, as `LoadAddOn` does.
     pub fn load_addon_saved_variables(&mut self, name: &str) {
         let i = self
             .model_ref()
@@ -912,12 +680,8 @@ impl super::UiScript {
         }
     }
 
-    /// Every **loaded** addon that declares saved variables, as
-    /// `(name, account-scoped names, per-character names)` — what the host writes at shutdown.
-    ///
-    /// The gate is *loaded*, not a dirty bit: the reference gates its write on the record's loaded
-    /// byte (`0x51f711`) and has no dirty tracking at all. An addon that never loaded this session
-    /// has no globals to write, and writing it would blank the file it never read.
+    /// `(name, account names, per-character names)` to write at shutdown, for each loaded addon
+    /// that declares any: the reference gates the write on the loaded byte (`0x51f711`).
     pub fn addon_saved_variable_sets(&self) -> Vec<(String, Vec<String>, Vec<String>)> {
         self.model_ref()
             .addons
@@ -936,8 +700,7 @@ impl super::UiScript {
             .collect()
     }
 
-    /// Mark an addon loaded — the host's startup walk reporting what it ran, so `IsAddOnLoaded`
-    /// answers for the startup half exactly as it does for the `LoadAddOn` half.
+    /// Mark an addon the startup walk ran as loaded, for `IsAddOnLoaded`.
     pub fn mark_addon_loaded(&mut self, name: &str) {
         if let Some(a) = self
             .model_mut()
@@ -949,8 +712,7 @@ impl super::UiScript {
         }
     }
 
-    /// `(name, enabled)` for every registered addon, in registry order — what the host writes back
-    /// to `AddOns.txt`, so a `DisableAddOn` from Lua survives the session.
+    /// `(name, enabled)` per registered addon, in order: what the host writes to `AddOns.txt`.
     pub fn addon_enable_states(&self) -> Vec<(String, bool)> {
         self.model_ref()
             .addons
diff --git a/crates/benilla-ui/src/script/addon_gate.rs b/crates/benilla-ui/src/script/addon_gate.rs
index f607e65b..d70a7acb 100644
--- a/crates/benilla-ui/src/script/addon_gate.rs
+++ b/crates/benilla-ui/src/script/addon_gate.rs
@@ -1,43 +1,19 @@
-//! **The one load law — `AddOn_CanLoad 0x51e780`, as a pure function** (decision 1292).
+//! `AddOn_CanLoad` (`0x51e780`) as a pure function: the one load law every surface consults.
+//! The first check that fires decides, in the reference's order: missing, the visiting guard (a
+//! cycle is loadable), enabled, banned, corrupt, version, dependencies, demand.
 //!
-//! Every question of the form "can this addon load, and if not, why" has exactly one answer in
-//! the reference: a single arbiter whose checks run in a fixed order, whose version gate and
-//! CVar read re-run on every query, and whose two out-params (`reasonOut`, `depReasonOut`)
-//! render through one formatter. benilla had three partial copies of it — the API verbs'
-//! `not_loadable`, `LoadAddOn`'s inline checks, and the startup walk's disabled set — and the
-//! screens were about to become a fourth. This module is the one copy they all consult.
+//! The version gate is an exact `==` against a hard-coded 11200 (`0x51d7d0`), so 11201 is out of
+//! date and a missing `## Interface` compares as 0. With `checkAddonVersion` off the reason is
+//! reset to none, so force-load falls through to the dependency and demand checks.
 //!
-//! The check order, byte-verified (wow-re `system/ui/scratch/addon-version-gate.md` §2, a §5
-//! pair + arbitration): **missing → visiting-guard (returns loadable — a cycle resolves
-//! optimistically) → enabled → banned → corrupt → the version gate → required-deps recursion →
-//! demand gate**. The first check that fires decides.
-//!
-//! ## The version gate (§2.1, byte for byte)
-//!
-//! `cmp [rec+0x1c], 11200` — an **exact `==` against a hard-coded immediate** (`0x51d7d0` is
-//! `mov eax,0x2bc0; ret`, one caller image-wide). `## Interface: 11201` is as out of date as
-//! `10000`, and a manifest with **no** `## Interface` line compares as `0` — out of date, not
-//! "unknown". On mismatch the reason `7` is written and then, when the check is OFF
-//! (`checkAddonVersion`, the *Load out of date AddOns* checkbox inverted), **actively reset to
-//! `0`** — an out-of-date addon under force-load is byte-indistinguishable from an up-to-date
-//! one; there is no "loadable but flagged" state. Force-load is a fall-through, not a success:
-//! the dependency and demand checks still run.
-//!
-//! ## The reason rendering (§2.3)
-//!
-//! `reason != 0` → its token; `reason == 0 && depReason != 0` → `DEP_<token>`, applied
-//! **exactly once at any nesting depth** (the recursion passes the caller's `depReasonOut` as
-//! the callee's *both* out-params, so the deepest failure's raw token lands in the parent's dep
-//! slot); both zero → nil (all three callers guard it — `LOADABLE` is unreachable as a reason).
-//! `BANNED`/`CORRUPT`/`INSECURE` gate on the server's `SMSG_ADDON_INFO` signature state, which
-//! benilla does not model (nothing a player installs is Blizzard-signed) — the arms exist in
-//! the table for honesty and are never produced.
+//! The reason renders once (`0x51e930`): the addon's own token, else `DEP_` and the deepest failing
+//! dependency's token, else nil. `BANNED`, `CORRUPT` and `INSECURE` read the server's
+//! `SMSG_ADDON_INFO` signature state, which is not modelled; they are never produced.
 
-/// The `## Interface` this client implements — the reference's own hard-coded `0x2bc0`.
+/// The `## Interface` this client implements, the reference's hard-coded `0x2bc0`.
 pub const CLIENT_INTERFACE: u32 = 11200;
 
-/// One addon as the gate reads it — the adapter shape every registry (the VM's `AddOnInfo`
-/// rows, the app's discovered manifests, the glue screen's folder view) lowers into.
+/// One addon as the gate reads it; every addon registry lowers into this.
 pub struct GateRow<'a> {
     pub name: &'a str,
     /// This character's enable state (`AddOns.txt`; an addon nobody disabled is enabled).
@@ -46,13 +22,9 @@ pub struct GateRow<'a> {
     /// the leading integer, `0` when absent.
     pub interface: u32,
     pub load_on_demand: bool,
-    /// Loaded this session. A loaded dependency satisfies the recursion outright — VERIFIED at
-    /// the bytes (wow-re `addon-enable-store.md`, the follow-up carve): the short-circuit lives
-    /// inside `AddOn_CanLoad` itself (`0x51e8ba call AddOn_IsLoaded; jne` skips the recursion),
-    /// and the recursion propagates the caller's own `demandOnly` (`0x51e790` spill →
-    /// `0x51e8c9` reload). The concrete verdicts match this implementation exactly: a
-    /// LoadOnDemand addon over a loaded ordinary dep is loadable/nil; over an
-    /// enabled-but-UNLOADED ordinary dep it reports `DEP_NOT_DEMAND_LOADED`.
+    /// Loaded this session. A loaded dependency satisfies the recursion outright (`0x51e8ba`),
+    /// which otherwise passes on the caller's `demandOnly` (`0x51e790`, `0x51e8c9`): in game, an
+    /// ordinary dependency enabled but not loaded reports `DEP_NOT_DEMAND_LOADED`.
     pub loaded: bool,
     /// `## Dependencies` / `## RequiredDeps` / any `## Dep*` (one list in the reference).
     pub dependencies: Vec<&'a str>,
@@ -63,10 +35,9 @@ pub struct GateRow<'a> {
 pub enum Verdict {
     Loadable,
     Refused {
-        /// The addon's own reason token (`DISABLED`, `INTERFACE_VERSION`, …), when the failure
-        /// is its own.
+        /// The addon's own reason token (`DISABLED`, `INTERFACE_VERSION`, …).
         reason: Option<&'static str>,
-        /// The dependency's raw token when the failure is a dep's — rendered as `DEP_<token>`.
+        /// A failing dependency's raw token, rendered as `DEP_<token>`.
         dep: Option<&'static str>,
     },
 }
@@ -76,8 +47,7 @@ impl Verdict {
         self == Verdict::Loadable
     }
 
-    /// The formatter (`0x51e930`) plus its callers' nil-guard: the reason token, else
-    /// `DEP_<dep>`, else `None` (loadable — `LOADABLE` is unreachable as a reason).
+    /// The formatter (`0x51e930`) with its callers' nil guard, so `LOADABLE` never renders.
     pub fn token(self) -> Option<String> {
         match self {
             Verdict::Loadable => None,
@@ -90,16 +60,14 @@ impl Verdict {
 
 /// `AddOn_CanLoad` over a registry: can `rows[index]` load right now?
 ///
-/// `demand_only` is the in-game flavour (`dl=1`): an enabled, up-to-date, **non**-LoadOnDemand
-/// addon that has not loaded reports `NOT_DEMAND_LOADED` — a state the glue (`dl=0`) never
-/// produces. `version_check` is the live `checkAddonVersion` read; both re-run per query, which
-/// is why toggling the checkbox needs no rescan (§2.2).
+/// `demand_only` is the in-game query (`dl=1`), where an unloaded addon that is not LoadOnDemand
+/// reports `NOT_DEMAND_LOADED`; `version_check` is the live `checkAddonVersion`, read per query.
 pub fn can_load(rows: &[GateRow], index: usize, demand_only: bool, version_check: bool) -> Verdict {
     let mut visiting = vec![false; rows.len()];
     walk(rows, index, demand_only, version_check, &mut visiting)
 }
 
-/// One level of the arbiter — the checks in the reference's evaluation order.
+/// One level of the arbiter, its checks in the reference's order.
 fn walk(
     rows: &[GateRow],
     i: usize,
@@ -107,39 +75,38 @@ fn walk(
     version_check: bool,
     visiting: &mut [bool],
 ) -> Verdict {
-    // Check 2: the in-progress guard — a cycle resolves optimistically (`[rec+0x2d]` → TRUE).
+    // Check 2: the visiting guard; a cycle resolves as loadable.
     if visiting[i] {
         return Verdict::Loadable;
     }
     let row = &rows[i];
-    // Check 3: this character's enable state.
+    // Check 3: enabled.
     if !row.enabled {
         return Verdict::Refused {
             reason: Some("DISABLED"),
             dep: None,
         };
     }
-    // Checks 4/5 (banned / corrupt): no server signature state to read — never produced.
-    // Check 6: the version gate — exact ==, then refuse or actively fall through (§2.1).
+    // Checks 4 and 5, banned and corrupt: no signature state, never produced.
+    // Check 6: the version gate, exact `==`; with the check off it falls through (`0x51e876`).
     if row.interface != CLIENT_INTERFACE && version_check {
         return Verdict::Refused {
             reason: Some("INTERFACE_VERSION"),
             dep: None,
         };
     }
-    // Check 7: required dependencies, recursively; the first failure decides, and the deepest
-    // failure's raw token is the one `DEP_` wraps (§2.3's shared out-param).
+    // Check 7: the dependencies, recursively; a shared out-param makes the deepest failure's raw
+    // token the one `DEP_` wraps (`0x51e8ce`).
     visiting[i] = true;
     for dep in &row.dependencies {
         let found = rows.iter().position(|r| r.name.eq_ignore_ascii_case(dep));
         let verdict = match found {
-            // The recursion's check 1: a name not in the registry is MISSING.
+            // Check 1, in the recursion: a name not in the registry is `MISSING`.
             None => Verdict::Refused {
                 reason: Some("MISSING"),
                 dep: None,
             },
-            // A loaded dependency satisfies the walk outright — `0x51e8ba`, before the
-            // recursion (the row doc has the carve).
+            // A loaded dependency satisfies the walk before any recursion (`0x51e8ba`).
             Some(d) if rows[d].loaded => Verdict::Loadable,
             Some(d) => walk(rows, d, demand_only, version_check, visiting),
         };
@@ -152,7 +119,7 @@ fn walk(
         }
     }
     visiting[i] = false;
-    // Check 8: the demand gate — reachable only from the in-game surface (`dl=1`).
+    // Check 8: the demand gate, in game only (`dl=1`).
     if demand_only && !row.load_on_demand && !row.loaded {
         return Verdict::Refused {
             reason: Some("NOT_DEMAND_LOADED"),
@@ -177,13 +144,12 @@ mod tests {
         }
     }
 
-    /// The check ORDER is the law: a disabled addon reports only DISABLED, whatever else is
-    /// wrong with it — the glue colours that row grey, never red (1197's precedence).
+    /// Enabled comes before every later check, so the glue shows a disabled row grey, never red.
     #[test]
     fn a_disabled_addon_reports_only_disabled() {
         let mut a = row("A", vec!["Ghost"]);
         a.enabled = false;
-        a.interface = 0; // out of date too — and still invisible behind DISABLED
+        a.interface = 0; // out of date too
         let rows = vec![a];
         assert_eq!(
             can_load(&rows, 0, false, true).token().as_deref(),
@@ -191,8 +157,6 @@ mod tests {
         );
     }
 
-    /// §2.1 byte for byte: exact `==` (11201 is out of date), missing `## Interface` is 0 and
-    /// out of date, and force-load RESETS the reason — indistinguishable from up to date.
     #[test]
     fn the_version_gate_is_exact_and_force_load_erases_it() {
         let mut a = row("A", vec![]);
@@ -213,8 +177,6 @@ mod tests {
         );
     }
 
-    /// §2.3: `DEP_` is applied exactly once at any depth — the deepest failure's raw token is
-    /// what the top level wraps.
     #[test]
     fn dep_prefix_applies_once_at_any_depth() {
         let a = row("A", vec!["B"]);
@@ -227,7 +189,7 @@ mod tests {
             Some("DEP_DISABLED"),
             "not DEP_DEP_DISABLED — the shared out-param collapses the nesting"
         );
-        // And a dep that is not installed at all is the recursion's own check 1.
+        // A dependency not installed fails the recursion's check 1.
         let rows = vec![row("A", vec!["Ghost"])];
         assert_eq!(
             can_load(&rows, 0, false, true).token().as_deref(),
@@ -235,8 +197,6 @@ mod tests {
         );
     }
 
-    /// Check 2: a dependency cycle resolves optimistically (the visiting guard returns TRUE),
-    /// so neither side reports a failure from the query side.
     #[test]
     fn a_cycle_is_loadable_to_the_query() {
         let a = row("Ping", vec!["Pong"]);
@@ -245,8 +205,6 @@ mod tests {
         assert_eq!(can_load(&rows, 0, false, true), Verdict::Loadable);
     }
 
-    /// Check 8 is in-game only (`dl=1`), runs AFTER the dep loop, and force-load does not skip
-    /// it — an out-of-date addon under force-load can still be NOT_DEMAND_LOADED.
     #[test]
     fn the_demand_gate_is_in_game_only_and_survives_force_load() {
         let mut a = row("A", vec![]);
@@ -256,13 +214,10 @@ mod tests {
         assert_eq!(
             can_load(&rows, 0, true, false).token().as_deref(),
             Some("NOT_DEMAND_LOADED"),
-            "force-load falls THROUGH, it does not succeed (§2.1 fact 2)"
+            "force-load falls THROUGH, it does not succeed (`0x51e89d`)"
         );
     }
 
-    /// A LoadOnDemand addon whose required dep already loaded at startup is loadable from the
-    /// in-game surface — the loaded short-circuit, VERIFIED at `0x51e8ba` (inside `AddOn_CanLoad`,
-    /// before the recursion; the carve's own concrete A/B verdict is this assertion).
     #[test]
     fn a_loaded_dependency_satisfies_the_demand_query() {
         let mut a = row("A", vec!["B"]);
diff --git a/crates/benilla-ui/src/script/addon_message.rs b/crates/benilla-ui/src/script/addon_message.rs
index 7efd324b..f4a4c583 100644
--- a/crates/benilla-ui/src/script/addon_message.rs
+++ b/crates/benilla-ui/src/script/addon_message.rs
@@ -1,162 +1,40 @@
-//! **`SendAddonMessage`** — the addon-to-addon channel (decision 1235).
+//! `SendAddonMessage(prefix, message [, distribution])`, the addon-to-addon channel. 1.12 has no
+//! addon opcode: the binding (`0x49f920`) sends `prefix`, a TAB and `message` as one
+//! `CMSG_MESSAGECHAT` string with language `LANG_ADDON` (`0xFFFFFFFF`), the only mark of addon
+//! data on either side, and the receiver splits on the first TAB (`0x49a8d0`). The binding reads
+//! Lua arguments 1 to 3 only: 1.12 has no whispered addon message.
 //!
-//! ```lua
-//! SendAddonMessage(prefix, message [, distribution])
-//! ```
-//!
-//! The corpus's single most-wanted missing global (24 of 218 addons name it). It is how an addon
-//! talks to *its own copy running on someone else's client*: oRA2 broadcasting a CTRA raid status,
-//! KLHThreatMeter shipping a threat table, BigWigs syncing a boss timer.
-//!
-//! ## 1.12.1 has no addon opcode — the whole thing is one sentinel in the language field
-//!
-//! There is no `CMSG_ADDON_MESSAGE`. `SendAddonMessage` composes its two strings into ONE chat
-//! line, sends it as an ordinary `CMSG_MESSAGECHAT` on an ordinary chat lane, and sets the
-//! `language` field to `LANG_ADDON` (`0xFFFFFFFF`). That sentinel is the *only* thing separating
-//! addon data from speech, on both sides of the wire.
-//!
-//! VERIFIED in `WoW.exe` (5875) — wow-re `system/ui/scratch/addon-chat-law.md` §5, a §5 trio
-//! (three independent derivations, orchestrator-arbitrated). The binding is `0x49f920`, body
-//! `[0x49f920, 0x49fb2a)`:
-//!
-//! ```text
-//! 49f951/49f958: lua_tostring(L,1)  -> prefix    (NULL -> "" at 0x49f96b-0x49f97a)
-//! 49f95d/49f966: lua_tostring(L,2)  -> message   (NULL -> "" likewise)
-//! 49f97f-49f987: BOTH empty -> luaL_error("Usage: SendAddonMessage(...)")
-//! 49f9a2: push 0x844b5c            ; "%s\t%s"  (raw 25 73 09 25 73 00)
-//! 49f9ad: push 0x800               ; 2048
-//! 49f9b2: push eax                 ; dst = [ebp-0x81c]
-//! 49f9b3: call 0x64a7f0            ; _snprintf(dst, 0x800, "%s\t%s", prefix, message)
-//! 49fa0b/49fa15: lua_isstring(L,3) ; absent/non-string -> esi = 1 = PARTY (0x49fa06/0x49fa12)
-//! 49fa3f: cmp esi,0x01 ; je        ; PARTY
-//! 49fa44: cmp esi,0x02 ; je        ; RAID
-//! 49fa49: cmp esi,0x03 ; je        ; GUILD
-//! 49fa4e: cmp esi,0x5c ; je        ; BATTLEGROUND
-//! 49fa53: push 0x844b44 ; call 0x6f4940   ; luaL_error("Unknown addon chat type")
-//! 49facf: call 0x418190             ; u32 opcode 0x95 = CMSG_MESSAGECHAT
-//! 49fad8: call 0x418190             ; u32 chat type
-//! 49fab9: or  ebx,-0x1
-//! 49fadd: push ebx
-//! 49fae1: call 0x4181f0             ; u32 language = 0xFFFFFFFF
-//! 49faf0: call 0x418430             ; CString message
-//! ```
-//!
-//! Three consequences the shape forces, and each is a thing an implementation gets wrong:
-//!
-//! - **The prefix is not a wire field.** It is glued to the message with a literal TAB and the
-//!   pair rides as one C-string. The receiver splits on the FIRST tab (`0x49a8d0`, the same note
-//!   §3). Nothing on the wire knows a prefix exists.
-//! - **There is no `target` argument.** The body fetches Lua indices `1`, `2` and `3` and no
-//!   other — there is no arg-4 fetch anywhere in its 522 bytes. 1.12 has no whispered addon
-//!   message; the modern 4-argument `SendAddonMessage(prefix, msg, "WHISPER", target)` does not
-//!   exist here, and `"WHISPER"` is not even a legal distribution (below).
-//! - **`_snprintf` with size `0x800` truncates silently at 2047 bytes + NUL** (`0x64a861`-
-//!   `0x64a868`). No error, no tell.
-//!
-//! ## The distribution set is FOUR, and it is narrower than the server's
-//!
-//! [`AddonDistribution`] is the whole legal set — `PARTY`/`RAID`/`GUILD`/`BATTLEGROUND`. Two
-//! independent mechanisms in the binary name the identical four, which is the cross-check that
-//! settles it: the send-side whitelist above, and the *receive* side's remap table (`0x49aff4`,
-//! 92 bytes = `00 01 02` then `04` x88 then `03`) feeding the 5-entry jump table `0x49afe0`, whose
-//! four real arms push `"PARTY"`/`"RAID"`/`"GUILD"`/`"BATTLEGROUND"` and whose default pushes the
-//! literal `"UNKNOWN"`.
-//!
-//! **vmangos is WIDER than the client** and that gap is deliberate, not a bug to close:
-//! `WorldSession::IsLanguageAllowedForChatType` also permits `LANG_ADDON` on OFFICER,
-//! RAID_LEADER, RAID_WARNING, BATTLEGROUND_LEADER and CHANNEL. A real client *accepts* addon
-//! traffic inbound on all of those (the receive-side discriminator is language-only and reads no
-//! type byte) while refusing to *send* on them. We match the client, not the server: the four.
-//!
-//! An unknown token and a known-but-not-whitelisted one (`"SAY"`, `"WHISPER"`, `"CHANNEL"`,
-//! `"OFFICER"`, `"RAID_WARNING"` — all of which DO resolve in the shared 13-record type table at
-//! `0x49f7a0`) converge on the **same** `luaL_error` at `0x49fa53`. That is why this module does
-//! not model the 13-record table at all: its output is unobservable through this binding, because
-//! both paths raise the identical error text. The note says so outright — *"a caller cannot tell a
-//! typo from a rejection."*
-//!
-//! ## The seam
-//!
-//! [`super::chat_send`]'s shape: the verb validates, composes, and queues an [`AddonSend`]; the app
-//! drains it ([`super::UiScript::take_addon_sends`]) into `ClientCommand::AddonMessage` and the
-//! writer puts it on the wire. Plain data across the boundary — this crate holds no wire types —
-//! but the distribution crosses as an **enum, not a token string**, so the app's map is total and
-//! the "unknown type silently guessed into SAY" failure is impossible by construction rather than
-//! by a second validation nobody remembers to write.
-//!
-//! ## The `|`-escape scan — carved, and it is a forward SKIP, not a flat scan (decision 1236)
-//!
-//! `0x49f9bb`-`0x49fa04`, running on the **composed** buffer (cursor `0x49f9bd
-//! lea ecx,[ebp-0x81c]`, byte-identical to the `_snprintf` destination `lea` at `0x49f9a7`) and
-//! strictly **before** the type whitelist — `0x49fa06` is the sole predecessor of `0x49fa0b`, so a
-//! payload with a bad escape *and* a bad distribution reports the escape and never fetches
-//! argument 3. See [`validate_escapes`] for the loop; the two facts that make it non-obvious:
-//!
-//! - **`|c` skips PAST its closer.** `strstr` (`0x64b4f0`, case-**sensitive** — the binary has a
-//!   folding twin at `0x64b540` and deliberately does not use it here) finds the first literal
-//!   `"|r"` and the cursor becomes `lea esi,[eax+0x2]` (`0x49f9f4`), i.e. beyond it. That single
-//!   `lea` is why a well-formed `|r` never reaches the loop head — under a flat scan its own `|`
-//!   would be a `|` followed by `r` and every colour escape in the game would raise.
-//! - **An unmatched `|c` is not an error.** It NUL-terminates in place at the opening `|`
-//!   (`0x49fa6a`) and then `0x49fa6d jmp 0x49fa06` lands on the accept path — **the truncated text
-//!   is transmitted**, with no error and no signal to the addon.
-//!
-//! Because the scan runs on the composed buffer, prefix and message are validated as **one
-//! string**: a `|c` opened in the prefix can be closed by a `|r` in the message, and an unmatched
-//! one in the prefix truncates the payload to a bare prefix with no tab at all.
-//!
-//! ## What is deliberately NOT here, named rather than left to be found
-//!
-//! - **The no-group silent return** (`0x49fa9f`-`0x49faab` -> `0x49fb21`): the reference drops an
-//!   effective-PARTY send when `[0xbc6f48]`/`[0xbc6f4c]` are both zero, with no error and no
-//!   packet. Those two are **`partyMemberGuid[0].lo/.hi` — element 0 of a FOUR-entry array**
-//!   (stride 8, limit `0x20`; `Ui\PartyFrame.cpp`), not "the party GUID" as 1235 called them:
-//!   slot 0 being non-zero is a sound "in a party" test only because `SMSG_GROUP_LIST` refills the
-//!   roster lowest-slot-first (decision 1236 §3).
-//!   We do not implement it, and the reason is a window we have and the reference does
-//!   not: its gate reads the live group GUID, ours would read [`super::party::PartyState`], which
-//!   is `default()` between world entry and the first `SMSG_GROUP_LIST`. Implementing it would
-//!   silently swallow a real broadcast in that window — the exact failure this verb exists to
-//!   avoid. Not implementing it costs one `CMSG_MESSAGECHAT` that vmangos discards
-//!   (`HandleChatMessageOpcode`'s `if (!group) return`), which is the same observable nothing.
+//! Deviation: the reference drops a send that resolves to PARTY while party slot 0's guid
+//! (`0xbc6f48`) is zero (`0x49fa9f`-`0x49faab`); benilla sends it, because `PartyState` is empty
+//! until the first `SMSG_GROUP_LIST` and the gate would swallow a real broadcast. vmangos drops a
+//! group-less party line anyway (`ChatHandler.cpp:476`).
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// The **four** distributions `SendAddonMessage` will send on — the client's own hard whitelist at
-/// `0x49fa3f`-`0x49fa4e`, corroborated by the receive side's remap table (module doc).
-///
-/// An enum rather than a token string on purpose: the binding is the only place a distribution can
-/// be rejected, so everything downstream must be total. The wire type bytes it names are
-/// `ChatMsg::CHAT_MSG_*` and live in `benilla_protocol::messages`; this crate carries no wire
-/// types, so the app maps the variant.
+/// The four distributions the binding sends on (whitelist `0x49fa3f`-`0x49fa4e`); the receiving
+/// side's jump table (`0x49afe0`) names the same four. vmangos also accepts `LANG_ADDON` on the
+/// officer, raid-leader, raid-warning, battleground-leader and channel lanes
+/// (`ChatHandler.cpp:78`), where the 1.12 client never sends it.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum AddonDistribution {
-    /// `PARTY` — wire chat type `0x01`. The **default** when the third argument is absent or not a
-    /// string (`esi` pre-seeded `1` at `0x49fa06`/`0x49fa12`, only overwritten by a successful
-    /// `lua_isstring`+lookup).
+    /// Chat type `0x01`; the default when the third argument is absent or not a string
+    /// (`0x49fa06`).
     Party,
-    /// `RAID` — wire chat type `0x02`. Downgraded to [`Self::Party`] outside a raid; see
-    /// [`AddonDistribution::effective`].
+    /// Chat type `0x02`; sent as PARTY outside a raid.
     Raid,
-    /// `GUILD` — wire chat type `0x03`.
+    /// Chat type `0x03`.
     Guild,
-    /// `BATTLEGROUND` — wire chat type `0x5C`.
+    /// Chat type `0x5C`.
     Battleground,
 }
 
 impl AddonDistribution {
-    /// Resolve a Lua distribution token. `None` = raise `"Unknown addon chat type"`, which is the
-    /// binding's single answer for both an unrecognised token and a recognised-but-not-whitelisted
-    /// one (module doc).
-    ///
-    /// Case-insensitive because the reference's own lookup is: the shared table at `0x49f7a0` is
-    /// scanned with the case-insensitive compare `0x64a4c0` (`0x49f861`-`0x49f875`), so
-    /// `SendAddonMessage("p", "m", "raid")` is a RAID send on a real client.
+    /// A Lua distribution token, case-insensitive like the reference's lookup (`0x64a4c0` over the
+    /// table at `0x49f7a0`). `None` raises `Unknown addon chat type`, the one error the reference
+    /// gives an unknown token and a chat type outside the four alike (`0x49fa53`).
     pub fn from_token(token: &str) -> Option<Self> {
-        // `eq_ignore_ascii_case` rather than an uppercased allocation: the four tokens are ASCII
-        // and this runs on every addon broadcast.
         for (name, dist) in [
             ("PARTY", Self::Party),
             ("RAID", Self::Raid),
@@ -170,8 +48,7 @@ impl AddonDistribution {
         None
     }
 
-    /// The token the receive side reports as `CHAT_MSG_ADDON`'s 3rd argument — the strings the four
-    /// jump-table arms push (`0x8441b0`, `0x844600`, `0x8441a8`, `0x8445f0`).
+    /// The token the receiving side reports as `CHAT_MSG_ADDON`'s third argument (`0x49afe0`).
     pub fn token(self) -> &'static str {
         match self {
             Self::Party => "PARTY",
@@ -181,28 +58,10 @@ impl AddonDistribution {
         }
     }
 
-    /// **RAID sent from outside a raid goes to PARTY**, silently — `0x49fa8b`-`0x49fa93` tests
-    /// `[0xb713e0]` and falls into the PARTY arm when it is zero. Every other distribution passes
-    /// through untouched.
-    ///
-    /// This is the same downgrade a player sees when `/raid` in a 5-man party lands in party chat,
-    /// and vmangos is the reason it has to exist client-side: `HandleChatMessageOpcode`'s
-    /// `CHAT_MSG_RAID` arm requires `group->IsRaidGroup()` and drops the message otherwise. Without
-    /// it, oRA2 — which sends `SendAddonMessage("CTRA", msg, "RAID")` unconditionally
-    /// (`Core.lua:563`) — would reach nobody in an ordinary 5-man group, which is most of the time
-    /// it runs.
-    ///
-    /// `in_raid` is [`super::party::PartyState::raid`] being non-empty, that list being
-    /// `GetNumRaidMembers()`'s own backing (empty outside a raid, and including the player inside
-    /// one).
-    ///
-    /// **That is not an analogy — it is the same cell** (decision 1236). `[0xb713e0]` is not a
-    /// flag: it is the raid member **count**, used as an unsigned loop bound over the 40-slot
-    /// roster at `0xb712a8`, and the binding `GetNumRaidMembers` (`0x4bb530`, `Ui\RaidInfo.cpp`)
-    /// returns that cell verbatim. So the reference's test `[0xb713e0] == 0` *is*
-    /// `GetNumRaidMembers() == 0`, and reading our own `GetNumRaidMembers` backing is the
-    /// mechanism rather than a stand-in for it. (1235 recorded this identity as corroborated-not-
-    /// carved and hedged accordingly; the RE it dispatched carved it, and the hedge is retired.)
+    /// RAID outside a raid silently goes out as PARTY (`0x49fa8b`-`0x49fa93`); vmangos drops a raid
+    /// line from a non-raid group (`ChatHandler.cpp:522`). The reference tests the raid member
+    /// count at `0xb713e0`, the cell `GetNumRaidMembers` (`0x4bb530`) returns, so `in_raid` is
+    /// `PartyState::raid` being non-empty.
     pub fn effective(self, in_raid: bool) -> Self {
         match self {
             Self::Raid if !in_raid => Self::Party,
@@ -211,94 +70,57 @@ impl AddonDistribution {
     }
 }
 
-/// One queued addon broadcast, drained by the app into the wire.
-///
-/// Plain data — [`super::chat_send::ChatSend`]'s twin. The prefix/message split is **already
-/// gone** by the time one of these exists: the reference composes at the binding
-/// (`_snprintf(dst, 0x800, "%s\t%s", …)` at `0x49f9b3`) and so do we, because the tab is the only
-/// separator the wire has and nothing downstream may re-decide where it goes.
+/// One queued addon broadcast, composed at the binding as the reference's is (`_snprintf` at
+/// `0x49f9b3`) and drained by the app onto the wire.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct AddonSend {
-    /// The composed payload — `prefix`, TAB, `message` — truncated to the reference's 2047 bytes.
-    /// Sent verbatim as the `CMSG_MESSAGECHAT` message C-string; vmangos does not sanitise a
-    /// `LANG_ADDON` line (`SanitizeChatMessage` returns early, `Handlers/ChatHandler.cpp:49`), so
-    /// the tab survives to the far client's splitter.
+    /// `prefix`, TAB, `message`, cut at 2047 bytes. vmangos passes a `LANG_ADDON` line through
+    /// unsanitised (`ChatHandler.cpp:49`), so the TAB reaches the receiver.
     pub text: String,
-    /// The lane, **after** the outside-a-raid downgrade ([`AddonDistribution::effective`]) — what
-    /// the app should actually send on, not what the addon asked for.
+    /// The lane to send on, after the outside-a-raid downgrade.
     pub distribution: AddonDistribution,
 }
 
 /// `_snprintf(dst, 0x800, …)` writes at most 2047 bytes plus its NUL (`0x64a861`-`0x64a868`).
 const ADDON_MESSAGE_CAP: usize = 0x800 - 1;
 
-/// **The `|`-escape scan** (`0x49f9bb`-`0x49fa04`, decision 1236) — the reference's only text
-/// validation, run on the already-composed payload and **before** the distribution is even
-/// fetched.
-///
-/// Returns `Err` for an invalid escape (the caller raises the reference's own message); otherwise
-/// `Ok`, having possibly **truncated `text` in place** at an unmatched `|c`, which is the
-/// reference's silent leg — the shortened payload still goes out.
-///
-/// The loop, arm for arm (`esi` = the cursor, always pointing at a `|` found by `strchr`):
-///
-/// | at `|` the next byte is | reference | cursor |
-/// |---|---|---|
-/// | `\|` | accept the escaped pipe | `+2` (`0x49f9d7 add esi,0x2`) |
-/// | `c` and a later `"\|r"` exists | accept the whole colour run | past the closer (`0x49f9f4 lea esi,[eax+0x2]`) |
-/// | `c` and no `"\|r"` | **truncate here, then accept** | — (`0x49fa6a`, `0x49fa6d jmp 0x49fa06`) |
-/// | anything else, incl. the NUL | `luaL_error` | — (`0x49fa6f`) |
-///
-/// Consequences that fall straight out of that table and are pinned by the tests, because every
-/// one of them is a thing a reimplementation gets wrong:
-///
-/// - **`||` and `|c` are the ONLY accepted escape starts.** A bare `|r` raises, and so do `|H`,
-///   `|h`, `|T`, `|t`, `|n` — and `|C`, because the `c` test is case-sensitive. Item links survive
-///   only because they are *wrapped*: `|cffffffff|Hitem:…|h[x]|h|r` opens with `|c`, so the whole
-///   run including every `|H`/`|h` is skipped to the closing `|r` without being examined.
-/// - **Nothing between a `|c` and its first `|r` is validated.** No hex-digit check; a nested
-///   `|c` is legal precisely because it is never looked at. This is a skip, not a nesting counter.
-/// - **`|R` does not close `|c`** (case-sensitive `strstr`) — it truncates instead.
-/// - **A lone trailing `|` raises**, because `strchr` will not match the NUL terminator
-///   (`0x64a402` tests before `0x64a406` compares), so the byte after it is the NUL and the NUL is
-///   not `|` or `c`. Pipe runs must therefore be even: `||||` is sent verbatim, `|||` raises.
+/// The reference's `|`-escape scan (`0x49f9bb`-`0x49fa04`), its only text check, run on the
+/// composed payload before the distribution is read. After each `|`: `||` skips both bytes; `|c`
+/// skips past the first later `|r` (case-sensitive `strstr`, `0x49f9f4`), leaving the run between
+/// unchecked; `|c` with no `|r` cuts `text` at the `|` and accepts (`0x49fa6a`); anything else,
+/// the NUL after a trailing `|` included, is `Err` (`0x49fa6f`).
 fn validate_escapes(text: &mut String) -> Result<(), ()> {
     let bytes = text.as_bytes();
     let mut i = 0usize;
     while let Some(off) = bytes[i..].iter().position(|&b| b == b'|') {
         let pipe = i + off;
         match bytes.get(pipe + 1) {
-            // `||` — an escaped pipe. Past both bytes.
             Some(b'|') => i = pipe + 2,
             Some(b'c') => {
-                // `strstr` from the `|c`'s own `|` for the literal two bytes `"|r"` (operand
-                // `0x844538` = image bytes `7c 72 00`). `|c` cannot match `|r`, so the hit is
-                // always a later closer.
+                // The reference's `strstr` starts at the `|c`, which cannot itself match `|r`.
                 match bytes[pipe..]
                     .windows(2)
                     .position(|w| w == b"|r")
                     .map(|p| pipe + p)
                 {
-                    // Skip PAST the closer, so its own `|` is never fed back to the loop head.
+                    // Past the closer: its `|` must not reach the loop head, where `|r` raises.
                     Some(closer) => i = closer + 2,
-                    // No closer: NUL-terminate at the opening `|` and accept what is left.
+                    // No closer: the reference cuts at the `|` and accepts.
                     None => {
                         text.truncate(pipe);
                         return Ok(());
                     }
                 }
             }
-            // Anything else — including `None`, the NUL that ends a lone trailing `|`.
+            // Anything else, including `None`: the NUL after a trailing `|`.
             _ => return Err(()),
         }
     }
     Ok(())
 }
 
-/// `lua_tostring` semantics + the reference's NULL replacement: strings and numbers coerce,
-/// everything else (nil, boolean, table, function) becomes the shared empty string `0x882748`
-/// (`0x49f96b`-`0x49f97a`). `Lua::coerce_string` **is** `lua_tostring`, so this is the mechanism
-/// rather than an imitation of it.
+/// `lua_tostring` with the reference's NULL-to-empty replacement (`0x49f96b`-`0x49f97a`): strings
+/// and numbers coerce, anything else is `""`.
 fn lua_tostring(lua: &Lua, v: &Value) -> mlua::Result<String> {
     Ok(lua
         .coerce_string(v.clone())?
@@ -313,21 +135,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             |lua, (prefix, message, distribution): (Value, Value, Value)| {
                 let prefix = lua_tostring(lua, &prefix)?;
                 let message = lua_tostring(lua, &message)?;
-                // BOTH empty is the usage error, and only both — there is no empty-prefix-only and
-                // no empty-message-only check (`0x49f97f`-`0x49f987`). AceEvent-2.0 relies on it:
-                // `SendAddonMessage("LOOT_OPENED", "", "RAID")` is 24 of the corpus's 35 call
-                // sites (the same line, in 23 addons' embedded copies) and its message is
-                // deliberately empty. An empty-message guard would break the largest row here.
+                // Only both empty is the usage error (`0x49f97f`-`0x49f987`): AceEvent-2.0 sends
+                // `SendAddonMessage("LOOT_OPENED", "", "RAID")`.
                 if prefix.is_empty() && message.is_empty() {
                     return Err(mlua::Error::RuntimeError(
                         r#"Usage: SendAddonMessage("prefix", "message" [,"type"])"#.into(),
                     ));
                 }
                 let mut text = format!("{prefix}\t{message}");
-                // Truncate exactly where `_snprintf` does — by BYTES, since the reference is
-                // writing a C buffer. `floor_char_boundary` is not stable, so walk back to the
-                // nearest boundary: identical to the reference for ASCII (every corpus payload),
-                // and the alternative is a `String` that is not UTF-8, which cannot exist.
+                // Cut at 2047 bytes as `_snprintf` does. Deviation: backed off to a char boundary,
+                // because a `String` must stay UTF-8; the cut is the same for ASCII.
                 if text.len() > ADDON_MESSAGE_CAP {
                     let mut cut = ADDON_MESSAGE_CAP;
                     while cut > 0 && !text.is_char_boundary(cut) {
@@ -335,21 +152,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     }
                     text.truncate(cut);
                 }
-                // **The escape scan runs HERE — after the compose, before argument 3 is fetched**
-                // (`0x49fa06` is the sole predecessor of `0x49fa0b`; decision 1236). So a call
-                // that is wrong in both ways reports the ESCAPE, and a bad distribution beside a
-                // bad escape is never even looked at. It may truncate `text` in place, which is
-                // the reference's silent leg.
+                // After the compose, before argument 3 is read (`0x49fa06` precedes `0x49fa0b`),
+                // so a bad escape is reported over a bad distribution.
                 if validate_escapes(&mut text).is_err() {
                     return Err(mlua::Error::RuntimeError(
                         "Invalid escape code in chat message".into(),
                     ));
                 }
-                // The third argument goes through `lua_isstring`, which is TRUE for a number too
-                // (`0x49fa0b`/`0x49fa15`) — so `SendAddonMessage("p", "m", 1)` resolves the token
-                // `"1"`, finds nothing, and raises, rather than being read as chat type 1. Absent
-                // or non-string (nil, table, boolean) takes `0x49fa1c je 0x49fa9f`, which skips
-                // the whitelist entirely with the pre-seeded `esi = 1` — the PARTY default.
+                // `lua_isstring` (`0x49fa15`) is true for a number, so `1` is the token "1" and
+                // raises; anything else that is not a string is PARTY (`0x49fa1c`).
                 let asked = match lua.coerce_string(distribution)? {
                     Some(token) => AddonDistribution::from_token(&token.to_string_lossy())
                         .ok_or_else(|| {
@@ -388,9 +199,6 @@ mod tests {
     use crate::script::party::{PartyState, RaidMemberInfo};
     use crate::script::UiScript;
 
-    /// The composition law: prefix, a literal TAB, message — one string, and the prefix is not a
-    /// field. Plus the default distribution, which is PARTY and not SAY (this verb's default is
-    /// not `SendChatMessage`'s).
     #[test]
     fn a_broadcast_is_prefix_tab_message_and_defaults_to_party() {
         let mut s = UiScript::new().unwrap();
@@ -402,19 +210,13 @@ mod tests {
                 distribution: AddonDistribution::Party,
             }]
         );
-        // Drained, not re-read.
         assert!(s.take_addon_sends().is_empty());
     }
 
-    /// **The four, and only the four.** Every token the shared 13-record table at `0x49f7a0`
-    /// resolves but the whitelist at `0x49fa3f`-`0x49fa4e` rejects must raise — SAY and WHISPER
-    /// especially, since a client that accepted them would be inventing a 1.12 whispered addon
-    /// message that does not exist. The error text is the reference's, and it is the SAME one an
-    /// unknown token gets.
     #[test]
     fn the_distribution_set_is_exactly_party_raid_guild_battleground() {
         let mut s = UiScript::new().unwrap();
-        // In a raid, so RAID is not downgraded and its own byte is what is under test.
+        // In a raid, so RAID is not downgraded.
         s.set_party(PartyState {
             raid: vec![RaidMemberInfo::default()],
             ..Default::default()
@@ -424,7 +226,6 @@ mod tests {
             ("RAID", AddonDistribution::Raid),
             ("GUILD", AddonDistribution::Guild),
             ("BATTLEGROUND", AddonDistribution::Battleground),
-            // Case-insensitive: the reference's lookup uses the case-insensitive compare 0x64a4c0.
             ("raid", AddonDistribution::Raid),
             ("Guild", AddonDistribution::Guild),
         ] {
@@ -434,7 +235,8 @@ mod tests {
             assert_eq!(sent.len(), 1, "{token}");
             assert_eq!(sent[0].distribution, want, "{token}");
         }
-        // Resolved by the shared table, refused by the whitelist — one error text for both classes.
+        // Chat types the reference's table resolves (`0x49f7a0`) but the whitelist refuses, and
+        // unknown tokens: one error for both.
         for token in [
             "SAY",
             "YELL",
@@ -464,14 +266,9 @@ mod tests {
         }
     }
 
-    /// A refused distribution sends **nothing** — the whole point of the enum seam. An addon that
-    /// asked for a lane we cannot send on gets an error it can see, never a silent reroute onto
-    /// SAY (which would put its serialized payload in front of every player in range).
     #[test]
     fn a_number_distribution_raises_rather_than_being_read_as_a_type_byte() {
         let mut s = UiScript::new().unwrap();
-        // `lua_isstring` is true for a number, so the reference resolves the TOKEN "1" — which is
-        // not in the type table — and raises. It does not read 1 as CHAT_MSG_PARTY.
         let err = s
             .run(r#"SendAddonMessage("p", "m", 1)"#)
             .expect_err("a numeric distribution must raise");
@@ -479,8 +276,6 @@ mod tests {
         assert!(s.take_addon_sends().is_empty());
     }
 
-    /// Non-string, non-number third argument is **absent**, not an error: `lua_isstring` fails and
-    /// the pre-seeded PARTY default stands.
     #[test]
     fn a_non_string_distribution_takes_the_party_default() {
         let mut s = UiScript::new().unwrap();
@@ -493,9 +288,6 @@ mod tests {
             .all(|a| a.distribution == AddonDistribution::Party));
     }
 
-    /// **RAID outside a raid is PARTY.** The corpus's one live caller (oRA2 `Core.lua:563`) sends
-    /// `"RAID"` unconditionally, so without this its broadcasts reach nobody in an ordinary 5-man
-    /// group — vmangos drops a `CHAT_MSG_RAID` from a non-raid group.
     #[test]
     fn raid_outside_a_raid_is_downgraded_to_party() {
         let mut s = UiScript::new().unwrap();
@@ -506,7 +298,6 @@ mod tests {
             s.take_addon_sends()[0].distribution,
             AddonDistribution::Party
         );
-        // In a raid it stays RAID…
         s.set_party(PartyState {
             raid: vec![RaidMemberInfo::default()],
             ..Default::default()
@@ -517,7 +308,7 @@ mod tests {
             s.take_addon_sends()[0].distribution,
             AddonDistribution::Raid
         );
-        // …and the downgrade is RAID's alone — GUILD and BATTLEGROUND never move.
+        // Only RAID is downgraded.
         s.set_party(PartyState::default());
         for (token, want) in [
             ("GUILD", AddonDistribution::Guild),
@@ -529,9 +320,6 @@ mod tests {
         }
     }
 
-    /// Both arguments empty is the usage error; **either one alone is not**. AceEvent-2.0 —
-    /// literally every one of this verb's replicated corpus callers — sends an empty message with
-    /// a real prefix, and erroring on it would break the row this verb was written for.
     #[test]
     fn only_both_empty_is_a_usage_error() {
         let mut s = UiScript::new().unwrap();
@@ -540,19 +328,15 @@ mod tests {
             .expect_err("both empty must raise");
         assert!(err.to_string().contains("Usage: SendAddonMessage"), "{err}");
         assert!(s.take_addon_sends().is_empty());
-        // AceEvent-2.0.lua's own line, verbatim — the empty message must go out.
+        // AceEvent-2.0's own call.
         s.run(r#"SendAddonMessage("LOOT_OPENED", "", "RAID")"#)
             .unwrap();
-        // A prefix-less payload is legal too; the receiver reads prefix "" and message "m".
         s.run(r#"SendAddonMessage("", "m")"#).unwrap();
         let sent = s.take_addon_sends();
         assert_eq!(sent[0].text, "LOOT_OPENED\t");
         assert_eq!(sent[1].text, "\tm");
     }
 
-    /// `lua_tostring` coercion, and the NULL -> "" replacement at `0x49f96b`-`0x49f97a`: a number
-    /// coerces, a table does not and becomes empty. `SendAddonMessage({}, {})` is therefore the
-    /// usage error, reached the same way `("", "")` reaches it.
     #[test]
     fn arguments_coerce_like_lua_tostring_and_nil_becomes_empty() {
         let mut s = UiScript::new().unwrap();
@@ -560,16 +344,13 @@ mod tests {
         assert_eq!(s.take_addon_sends()[0].text, "v\t314");
         s.run(r#"SendAddonMessage(42, "m")"#).unwrap();
         assert_eq!(s.take_addon_sends()[0].text, "42\tm");
-        // Non-coercible -> "" on both sides -> the usage error, not a Rust type error.
         let err = s
             .run(r#"SendAddonMessage({}, {})"#)
             .expect_err("two tables coerce to two empty strings");
         assert!(err.to_string().contains("Usage: SendAddonMessage"), "{err}");
     }
 
-    /// **The first tab is the split, so a tab inside the prefix is a payload bug the reference also
-    /// has** — no sanitisation of `0x09` exists anywhere in the binding. Pinned so nobody "fixes"
-    /// it: the receiver would split at the prefix's own tab and read a truncated prefix.
+    /// The reference does not strip a TAB from the prefix either; the receiver splits at it.
     #[test]
     fn a_tab_inside_the_prefix_is_passed_through_unsanitised() {
         let mut s = UiScript::new().unwrap();
@@ -577,8 +358,6 @@ mod tests {
         assert_eq!(s.take_addon_sends()[0].text, "pre\tfix\tbody");
     }
 
-    /// Silent truncation at 2047 bytes + the implicit NUL — `_snprintf`'s `0x800`, not the message
-    /// length and not the prefix length. No error: the addon is never told.
     #[test]
     fn the_payload_truncates_silently_at_2047_bytes() {
         let mut s = UiScript::new().unwrap();
@@ -586,30 +365,24 @@ mod tests {
             .unwrap();
         let sent = s.take_addon_sends();
         assert_eq!(sent[0].text.len(), 2047);
-        // The tab survives the cut — it is at byte 1, far inside the cap.
         assert!(sent[0].text.starts_with("p\tx"));
-        // A payload that exactly fills the buffer is NOT truncated.
+        // 1 + 1 + 2045 bytes fills the buffer exactly and is not cut.
         s.run(r#"SendAddonMessage("p", string.rep("y", 2045))"#)
             .unwrap();
         assert_eq!(s.take_addon_sends()[0].text.len(), 2047);
     }
 
-    /// **The escape scan is a forward SKIP, and a well-formed colour run must survive it.** This
-    /// is the test that would have caught the naive flat scan: under one, the `|` of every `|r`
-    /// terminator is a `|` followed by `r` and *every* colour escape in the game raises.
     #[test]
     fn a_well_formed_colour_run_passes_and_its_closer_is_skipped_not_scanned() {
         let mut s = UiScript::new().unwrap();
         for payload in [
             "|cffff0000red|r",
             "before |cffff0000red|r after",
-            // Nested opens are legal precisely because nothing between `|c` and the first `|r` is
-            // examined — a skip, not a nesting counter.
+            // Nothing between `|c` and the first `|r` is examined, so a nested open passes.
             "|cffAA0000 a |cff00BB00 b |r",
-            // An item link survives only because it is WRAPPED: the `|H`/`|h` inside the colour
-            // run are never looked at.
+            // A link passes only inside a colour run.
             "|cffa335ee|Hitem:12345:0:0:0|h[Thunderfury]|h|r",
-            // Escaped pipes, in even runs.
+            // Escaped pipes come in even runs.
             "a || b",
             "||||",
         ] {
@@ -628,20 +401,17 @@ mod tests {
         }
     }
 
-    /// `||` and `|c` are the ONLY accepted starts — everything else raises with the reference's own
-    /// text, including a **bare `|r`**, the link tokens outside a colour run, the case-flipped
-    /// `|C`, and a lone trailing `|` (whose next byte is the NUL, which `strchr` never matches).
     #[test]
     fn every_other_escape_start_raises_including_a_bare_closer_and_a_trailing_pipe() {
         let mut s = UiScript::new().unwrap();
         for payload in [
             "|r",                    // a closer with nothing open
-            "|Hitem:1:0:0:0|h[x]|h", // link tokens NOT wrapped in a colour run
+            "|Hitem:1:0:0:0|h[x]|h", // link tokens outside a colour run
             "|h",
             "|T",
             "|t",
             "|n",
-            "|C",         // |C is not |c — the test is case-sensitive
+            "|C",         // |C is not |c: the test is case-sensitive
             "trailing |", // next byte is the NUL
             "|||",        // odd pipe run: the third one's next byte is the NUL
         ] {
@@ -663,28 +433,22 @@ mod tests {
         }
     }
 
-    /// **An unmatched `|c` is NOT an error — it truncates in place and the short payload is still
-    /// sent** (`0x49fa6a` then `0x49fa6d jmp 0x49fa06`, the accept path). Silent, exactly as the
-    /// reference is: the addon is never told its message was cut.
     #[test]
     fn an_unmatched_colour_open_truncates_in_place_and_still_sends() {
         let mut s = UiScript::new().unwrap();
         s.run(r#"SendAddonMessage("P", "keep|cff00ff00dropped", "GUILD")"#)
             .unwrap();
         assert_eq!(s.take_addon_sends()[0].text, "P\tkeep");
-        // `|R` does not close `|c` — the strstr is case-SENSITIVE, so this truncates too.
+        // `|R` does not close `|c`: the reference's `strstr` is case-sensitive.
         s.run(r#"SendAddonMessage("P", "keep|cff00ff00x|Ry", "GUILD")"#)
             .unwrap();
         assert_eq!(s.take_addon_sends()[0].text, "P\tkeep");
-        // The scan runs on the COMPOSED buffer, so an unmatched open in the PREFIX truncates the
-        // payload to a bare prefix — no tab, no message at all.
+        // The scan runs on the composed text: an open in the prefix cuts the TAB and message off.
         s.run(r#"SendAddonMessage("pre|cffAABBCCfix", "body", "GUILD")"#)
             .unwrap();
         assert_eq!(s.take_addon_sends()[0].text, "pre");
     }
 
-    /// **Prefix and message are validated as ONE string**, because the scan runs after the
-    /// compose — so a colour opened in the prefix is legally closed by the message.
     #[test]
     fn a_colour_run_may_span_the_tab_because_the_scan_is_on_the_composed_buffer() {
         let mut s = UiScript::new().unwrap();
@@ -693,9 +457,6 @@ mod tests {
         assert_eq!(s.take_addon_sends()[0].text, "|cffff0000pre\tpost|r");
     }
 
-    /// **Ordering: the escape check precedes the distribution fetch.** A call that is wrong in
-    /// both ways reports the ESCAPE — `0x49fa06` is the sole predecessor of `0x49fa0b`, so
-    /// argument 3 is never even read. (1235 shipped these the other way round; 1236 corrects it.)
     #[test]
     fn a_bad_escape_beats_a_bad_distribution() {
         let s = UiScript::new().unwrap();
@@ -707,16 +468,13 @@ mod tests {
                 .contains("Invalid escape code in chat message"),
             "the escape must win, not the type: {err}"
         );
-        // But an UNMATCHED `|c` is not an error, so there the bad type does surface — the exact
-        // asymmetry the two legs of the scan produce.
+        // An unmatched `|c` is not an error, so the bad distribution is reported.
         let err = s
             .run(r#"SendAddonMessage("P", "|cff000000x", "TOTALLY_BOGUS")"#)
             .expect_err("must raise");
         assert!(err.to_string().contains("Unknown addon chat type"), "{err}");
     }
 
-    /// The distribution tokens round-trip to the strings the RECEIVE side reports as
-    /// `CHAT_MSG_ADDON`'s third argument (the four jump-table arms at `0x49a918`/`91f`/`926`/`92d`).
     #[test]
     fn the_tokens_are_the_receive_sides_own_strings() {
         for (dist, token) in [
diff --git a/crates/benilla-ui/src/script/auction.rs b/crates/benilla-ui/src/script/auction.rs
index db6cae00..5c466cdb 100644
--- a/crates/benilla-ui/src/script/auction.rs
+++ b/crates/benilla-ui/src/script/auction.rs
@@ -1,44 +1,9 @@
-//! The auction-house bindings (decision 1511) — the Era-shaped auctioneer surface, the same two-way
-//! seam as [`super::merchant`]/[`super::mail`]: the app pushes an **auction snapshot** (three lists
-//! of rows, already resolved from the wire to name/icon/quality/owner and already in display order)
-//! and the Lua `QueryAuctionItems`/`PlaceAuctionBid`/`StartAuction`/… calls queue outbound
-//! **intents** the app drains. The engine holds no auction knowledge: a row is a header, the sort
-//! is a pushed ordering, and the category tree is a pushed table.
+//! The auction-house bindings: the app pushes a snapshot of three lists, rows already resolved and
+//! in display order, and the Lua calls queue intents the app drains. Getters are keyed by `"list"`
+//! (Browse), `"bidder"` (Bids) or `"owner"` (Auctions), with `index` 1-based in the 50-row batch.
 //!
-//! ## Three lists, one API
-//!
-//! Every getter is keyed by a list type string — `"list"` (Browse), `"bidder"` (Bids) and
-//! `"owner"` (Auctions) — and `index` is **1-based within the current 50-row batch**, not within
-//! the whole result set. `GetNumAuctionItems` returns the pair `numBatchAuctions, totalAuctions`;
-//! when `total > batch` the window is paging, and the page turners re-query rather than scroll.
-//!
-//! ## The two null shapes that are load-bearing
-//!
-//! `GetAuctionSellItemInfo()` **always returns six values, never zero** — an empty sell slot pushes
-//! `nil, nil, 1, -1, nil, 0`, with a hard `count = 1` and `quality = -1` rather than nils. The
-//! reference Lua reads that count unguarded (`if count > 1`), so a nil there throws the moment the
-//! player pulls the item back out of the slot. `GetAuctionItemInfo` answers a lone `nil` for an
-//! out-of-range index, which is the shape its callers test.
-//!
-//! ## Sorting is ours, and it is not a three-state cycle
-//!
-//! The wire carries no sort field, so the ordering is entirely client-side over the ≤50 rows the
-//! server returned. Each list owns an **8-deep most-recently-clicked key stack** of
-//! `(key, reversed)` pairs: clicking the column that is already primary toggles its direction;
-//! clicking any other promotes it to primary **keeping the direction it remembers**. That is why
-//! `IsAuctionSortReversed` can answer "reversed" for a column that is not currently sorting
-//! anything. [`super::UiScript::take_auction_sorts`] hands the click to the app, which owns the
-//! stacks and pushes both the reordered rows and the stack back. The selection rides through all
-//! of it untouched, because it is stored as an auction **id** and only resolved to a row position
-//! when something asks (wow-re §5 TU-5).
-//!
-//! ## The deposit is computed here, and it is the *client's* arithmetic
-//!
-//! `CalculateAuctionDeposit(minutes)` reproduces the real client's formula —
-//! `floor(rate × stackValue / 100) × floor(minutes / 120)` — including the intermediate truncation
-//! that makes it disagree with what the server actually charges on cheap items. Decision 1511 §7
-//! records why the label follows the client rather than the server: it is a client artifact, and
-//! benilla renders what the director's client renders.
+//! The wire carries no sort: each list keeps an 8-deep stack of `(key, reversed)`, where clicking
+//! the primary column toggles it and another column is promoted with the direction it remembers.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -46,25 +11,21 @@ use super::binding_abi::flag;
 use super::cursor::{self, CursorPayload};
 use super::Model;
 
-/// The three list types, in the order the app pushes them. The wire calls them nothing at all —
-/// this is purely the Lua API's own keying.
+/// The three list types, in the order the app pushes them.
 pub const LIST: usize = 0;
 pub const BIDDER: usize = 1;
 pub const OWNER: usize = 2;
 
-/// The eight sort keys the reference's headers pass. Order here is the API's, not the comparator's
-/// (decision 1511's INTERIM: the comparator's own mode order is pinned to the in-flight wow-re §5).
+/// The eight sort keys the reference's column headers pass, in the API's order.
 pub const SORT_KEYS: [&str; 8] = [
     "level", "quality", "bid", "duration", "buyout", "status", "name", "seller",
 ];
 
-/// `"list"` / `"bidder"` / `"owner"` → the index the snapshot stores them at, for the other
-/// modules that key off the same three names (the tooltip's `SetAuctionItem`).
+/// A list type's snapshot index, for the other modules (the tooltip's `SetAuctionItem`).
 pub(super) fn list_index_of(kind: &str) -> Option<usize> {
     list_index(kind)
 }
 
-/// `"list"` / `"bidder"` / `"owner"` → the index the snapshot stores them at.
 fn list_index(kind: &str) -> Option<usize> {
     match kind {
         "list" => Some(LIST),
@@ -74,58 +35,46 @@ fn list_index(kind: &str) -> Option<usize> {
     }
 }
 
-/// One auction row, resolved by the app from a wire record (decision 1511). Plain data — its
-/// 1-based order in the window is its position in [`AuctionListState::rows`], which is already the
-/// sorted display order.
+/// One auction row, resolved by the app from a wire record.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionItemRow {
-    /// The wire auction id — what a bid or a cancel addresses. Never shown; the app maps a clicked
-    /// row index back through this.
+    /// The wire auction id a bid or a cancel addresses; never shown.
     pub auction_id: u32,
-    /// The item's template entry — the tooltip store's key and the link's identity.
     pub item_id: u32,
-    /// The listed item's **random-suffix roll** (the wire's `randomPropertyId`) — what the row
-    /// hover resolves its enchant lines from, and the id whose suffix [`Self::name`] already
-    /// carries. `0` = unrolled. The reference's `SetAuctionItem` writes exactly this into the
-    /// tooltip's `+0x424` (decision 1547).
+    /// The wire's `randomPropertyId`, 0 when unrolled; [`Self::name`] already carries its suffix,
+    /// and the reference's `SetAuctionItem` writes it into the tooltip's `+0x424`.
     pub random_property_id: u32,
-    /// `None` while the item template answer is in flight (the row shows a placeholder and fills
-    /// in when it lands, the merchant/mail pattern).
+    /// `None` while the item template query is in flight.
     pub name: Option<String>,
     pub texture: Option<String>,
     pub count: u32,
     pub quality: Option<u32>,
-    /// `RequiredLevel` — printed red when it exceeds the player's own level.
+    /// `RequiredLevel`, printed red above the player's level.
     pub level: u32,
-    /// The seller's opening price. This is what the row shows as the current bid while
-    /// [`Self::bid_amount`] is 0.
+    /// The seller's opening price, shown as the current bid while [`Self::bid_amount`] is 0.
     pub min_bid: u32,
-    /// The minimum step above the current bid — `0` while nobody has bid.
+    /// The minimum step above the current bid; 0 before any bid.
     pub min_increment: u32,
     /// `0` = no buyout.
     pub buyout_price: u32,
-    /// The current high bid; `0` = no bids yet.
+    /// The current high bid; 0 before any bid.
     pub bid_amount: u32,
-    /// Whether *the player* holds the high bid — a flag, not a name. The Browse row's "Your bid:"
-    /// caption and both action-button gates read it.
+    /// Whether the player holds the high bid: a flag, not a name.
     pub high_bidder: bool,
     /// The seller's name; `None` while the name query is in flight.
     pub owner: Option<String>,
-    /// The time-left bucket, `1..=4` (Short/Medium/Long/Very Long); `0` = not known yet.
+    /// The time-left bucket, `1..=4` (Short, Medium, Long, Very Long); 0 when not known yet.
     pub time_left: u32,
-    /// The full item link, built app-side from the row's entry + enchant + random-property +
-    /// suffix (auction rows carry all four on the wire, so the link is the complete one).
+    /// The full item link: auction rows carry entry, enchant, random property and suffix.
     pub link: Option<String>,
 }
 
-/// One of the three lists: the batch the server sent, the pre-cap match count, and the sort stack
-/// that ordered it.
+/// One of the three lists: the batch the server sent, the pre-cap match count and its sort stack.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionListState {
-    /// The current batch, already in display order (≤50 — the server's own page cap).
+    /// The current batch in display order, at most 50 (the server's page cap).
     pub rows: Vec<AuctionItemRow>,
-    /// `totalAuctions` — how many matched *before* the 50-row cap, so the pager can say
-    /// "( %d total )". Equal to `rows.len()` when everything fits on one page.
+    /// `totalAuctions`: the match count before the 50-row cap.
     pub total: u32,
     /// The most-recently-clicked sort stack, primary first: `(key, reversed)`.
     pub sort: Vec<(String, bool)>,
@@ -141,15 +90,18 @@ impl AuctionListState {
     }
 }
 
-/// One row of the Browse tab's category tree, pushed by the app from the player's own
-/// `ItemClass.dbc` / `ItemSubClass.dbc` (decision 1511 §5 — the set and order of classes is a
-/// structural fact; every string here comes off the player's install).
+/// One class of the Browse tab's category tree, from the player's `ItemClass.dbc`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionCategory {
-    /// The wire's `mainCategory` — an item class id, **not** the menu position.
+    /// The wire's `mainCategory`: an item class id, not the menu position.
     pub class_id: u32,
     pub name: String,
-    /// `(subclass id, name, offers inventory-slot filters)`.
+    /// The `0x807060` table's second column. False (Consumable, Trade Goods, Reagent,
+    /// Miscellaneous) empties `GetAuctionItemSubClasses` and `GetAuctionInvTypes`, but
+    /// `QueryAuctionItems` never reads it.
+    pub has_subclass_filter: bool,
+    /// The class's `ItemSubClass.dbc` rows with `DisplayFlags & 2` clear, in file order: what both
+    /// the menu and the query's index scan walk.
     pub subclasses: Vec<AuctionSubCategory>,
 }
 
@@ -158,57 +110,53 @@ pub struct AuctionSubCategory {
     /// The wire's `subCategory`.
     pub sub_id: u32,
     pub name: String,
-    /// Whether selecting this subclass offers the 14 inventory-slot rows beneath it
-    /// (`GetAuctionInvTypes`). INTERIM (decision 1511): the exact predicate is pinned to the
-    /// in-flight §5's TU-4, and lives here as *data* precisely so correcting it is a one-line
-    /// change app-side rather than an engine change.
+    /// `ItemSubClass.Flags & 0x200` (`0x4cfb63`): whether the subclass offers the 14
+    /// inventory-slot rows.
     pub has_inv_types: bool,
 }
 
-/// The open auction house's snapshot. Pushed whole by the app; `None` means no auctioneer session
-/// is open (the window is closed).
+/// The open auction house's snapshot, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionState {
     /// Browse / Bids / Auctions, indexed by [`LIST`], [`BIDDER`], [`OWNER`].
     pub lists: [AuctionListState; 3],
-    /// `GetAuctionHouseDepositRate()` — the percentage this house charges, read from
-    /// `AuctionHouse.dbc` at the `houseId` the hello reply carried.
+    /// `GetAuctionHouseDepositRate()`: the house's `AuctionHouse.dbc` deposit percentage.
     pub deposit_percent: u32,
 }
 
-/// A drained `QueryAuctionItems` — the Browse search, exactly as the reference builds it. The app
-/// maps this to `CMSG_AUCTION_LIST_ITEMS` (decision 1511 P1).
+/// A drained `QueryAuctionItems`, the `CMSG_AUCTION_LIST_ITEMS` filters: each is already a wire id,
+/// mapped from the Lua's menu position as `0x4ce980` does.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuctionQuery {
     pub name: String,
     /// `0` = no filter, for both.
     pub min_level: u32,
     pub max_level: u32,
-    /// `None` = no filter (the wire's `0xFFFFFFFF` sentinel).
+    /// `None` = no filter (the wire's `0xFFFFFFFF`), for all three.
     pub inv_type: Option<u32>,
     pub class: Option<u32>,
     pub sub_class: Option<u32>,
-    /// A **minimum** quality, not an equality. `None` = no filter (the dropdown's `All`, −1).
+    /// A minimum quality, not an equality; `None` = no filter (the dropdown's All, -1).
     pub quality: Option<u32>,
-    /// The page, 0-based. The app multiplies by 50 for the wire's item offset.
+    /// 0-based; the app multiplies by 50 for the wire's item offset.
     pub page: u32,
     pub usable_only: bool,
 }
 
-/// A drained `StartAuction` (decision 1511 P2).
+/// A drained `StartAuction`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct AuctionStartRequest {
     pub min_bid: u32,
     /// `0` = no buyout.
     pub buyout: u32,
-    /// Minutes — only 120, 480 or 1440 are legal, and the reference refuses to send anything else.
+    /// Minutes: 120, 480 or 1440, the only values the reference sends.
     pub duration: u32,
 }
 
 /// A drained `PlaceAuctionBid`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct AuctionBid {
-    /// The list the index addresses ([`LIST`] or [`BIDDER`] — the Auctions tab has no bid button).
+    /// [`LIST`] or [`BIDDER`]: the Auctions tab has no bid button.
     pub list: usize,
     /// 1-based row within the current batch; the app maps it to the wire auction id.
     pub index: u32,
@@ -216,32 +164,23 @@ pub struct AuctionBid {
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open auction house's snapshot. Replacing a list's rows
-    /// **clears that list's selection**, which is why this is one call and not two: the reference's
-    /// selection is C-side state that cannot survive the batch it indexes into, and a stale index
-    /// would silently address a different auction.
-    /// Push the Browse tab's class tree — `GetAuctionItemClasses` and its two siblings read it.
-    /// Login-scoped, not the session's: the stock `AuctionFrameBrowse_OnLoad` reads the classes at
-    /// the addon's LOAD, before any auctioneer, and in the client they are `ItemClass.dbc` names
-    /// with no session behind them (1971).
+    /// Push the Browse tab's class tree. Login-scoped: the stock `AuctionFrameBrowse_OnLoad` reads
+    /// the classes when the addon loads, before any auctioneer session.
     pub fn set_auction_item_classes(&mut self, classes: Vec<AuctionCategory>) {
         self.model_mut().auction_item_classes = classes;
     }
 
     pub fn set_auction(&mut self, state: Option<AuctionState>) {
         let mut model = self.model_mut();
-        // Only opening or closing the session drops the selection. A new PAGE does not, and
-        // neither does a re-sort: the selection is an auction **id**, so it survives the row
-        // moving and simply stops resolving if the auction leaves the page (wow-re §5 TU-5).
+        // Only opening or closing the session drops the selection: it is an auction id, so it
+        // survives a new page or a re-sort and stops resolving when the auction leaves the page.
         if model.auction.is_none() || state.is_none() {
             model.auction_selected = [0; 3];
         }
         model.auction = state;
     }
 
-    /// Push `CanSendAuctionQuery()`'s answer — the app's throttle, read by the Search button's
-    /// every-frame `OnUpdate`. Separate from the snapshot precisely because it changes every frame
-    /// while throttled and would otherwise churn the snapshot's diff.
+    /// Push `CanSendAuctionQuery()`'s answer, the app's query throttle.
     pub fn set_auction_can_query(&mut self, can: bool) {
         self.model_mut().auction_can_query = can;
     }
@@ -286,8 +225,7 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().auction_close)
     }
 
-    /// The item currently in the sell slot — the app resolves its `(bag, slot)` to the wire item
-    /// guid when `StartAuction` fires (the lazy resolve mail's send uses).
+    /// The sell slot's `(bag, slot)`, resolved by the app to the item guid on `StartAuction`.
     pub fn auction_sell_item(&mut self) -> Option<(i64, u32)> {
         self.model_mut()
             .auction_sell_item
@@ -295,14 +233,12 @@ impl super::UiScript {
             .map(|it| (it.bag, it.slot))
     }
 
-    /// Empty the sell slot — the app calls this once the auction is away, and on session close.
+    /// Empty the sell slot, once the auction is sent and on session close.
     pub fn clear_auction_sell_item(&mut self) {
         self.model_mut().auction_sell_item = None;
     }
 }
 
-/// Fetch a cloned row for a list type + 1-based index, or `None` (unknown type / out of range /
-/// no session open).
 fn row_at(model: &Model, kind: &str, index: usize) -> Option<AuctionItemRow> {
     let i = list_index(kind)?;
     model
@@ -312,12 +248,11 @@ fn row_at(model: &Model, kind: &str, index: usize) -> Option<AuctionItemRow> {
         .cloned()
 }
 
-/// The sell slot's `(name, texture, count, quality, canUse, stackValue)`, or `None` when empty.
-/// `stackValue` is the item's vendor sell price **times the stack**, which is what the reference's
-/// suggested opening price and the deposit are both computed from.
+/// The sell slot's `(name, texture, count, quality, canUse, stackValue)`, `stackValue` being the
+/// vendor price times the stack: the base of the suggested opening price and the deposit.
 fn sell_item_info(model: &Model) -> Option<(String, Option<String>, u32, i64, bool, u32)> {
     let it = model.auction_sell_item.as_ref()?;
-    // The TRUE stack size, not the split-carry field — the deposit is per stack.
+    // The real stack size, not the split-carry field: the deposit is per stack.
     let count = cursor::held_count(model, it);
     let template = model.item_templates.get(&it.item_id);
     let name = cursor::item_link_name(it.link.as_deref());
@@ -334,10 +269,8 @@ fn sell_item_info(model: &Model) -> Option<(String, Option<String>, u32, i64, bo
     ))
 }
 
-/// The real client's deposit arithmetic, reproduced including its intermediate truncation
-/// (decision 1511 §7): `floor(rate × stackValue / 100) × floor(minutes / 120)`. Both floors matter
-/// — the inner one is what makes a cheap stack deposit zero here while the server still charges a
-/// few copper, and the outer is why 120/480/1440 minutes scale as 1/4/12 rather than continuously.
+/// The reference client's deposit, `floor(rate × stackValue / 100) × floor(minutes / 120)`: the
+/// inner floor zeroes a cheap stack the server still charges a few copper for.
 fn deposit_for(rate: u32, stack_value: u32, minutes: u32) -> u32 {
     let per_unit = u64::from(rate).saturating_mul(u64::from(stack_value)) / 100;
     let units = u64::from(minutes) / 120;
@@ -347,8 +280,7 @@ fn deposit_for(rate: u32, stack_value: u32, minutes: u32) -> u32 {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumAuctionItems(type) → numBatchAuctions, totalAuctions. The pair is the whole paging
-    // model: batch is what this packet carried (≤50), total is what matched before the cap.
+    // GetNumAuctionItems(type) → numBatchAuctions (at most 50), totalAuctions (before the cap).
     g.set(
         "GetNumAuctionItems",
         lua.create_function(|lua, kind: String| {
@@ -371,8 +303,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemInfo(type, index) → the 12-tuple. `highBidder` is a FLAG, not a name — the
-    // seller's name is the last return, and it is what the Browse "Seller" column shows.
+    // GetAuctionItemInfo(type, index) → twelve values; `highBidder` is a flag, not the seller.
     g.set(
         "GetAuctionItemInfo",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -381,10 +312,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 row_at(&model, &kind, index)
             };
             let Some(r) = row else {
-                // The null tail is TWELVE values, not a lone nil — an unknown type string, an
-                // out-of-range index and an item-cache miss all share it, with a hard `count = 1`
-                // and `quality = -1` (wow-re §5 TU-3, one shared exit at `0x4cf1ec`). Callers
-                // destructure all twelve unguarded, so a short return throws.
+                // A miss (unknown type, out of range, not cached) still answers twelve values, with
+                // `count = 1` and `quality = -1` (one shared exit, `0x4cf1ec`), read unguarded.
                 return Ok(MultiValue::from_vec(vec![
                     Value::Nil,         // name
                     Value::Nil,         // texture
@@ -400,9 +329,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     Value::Nil,         // owner
                 ]));
             };
-            // `canUse` is computed HERE rather than pushed with the row: it depends on the
-            // player's own level, class and spellbook, which move independently of the auction
-            // snapshot. A pushed flag would go stale the moment the player dinged mid-browse.
+            // `canUse` is per call, not pushed: it follows the player's level, class and spellbook.
             let can_use = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 super::item_stats::item_usable_by_id(&model, r.item_id)
@@ -433,9 +360,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemTimeLeft(type, index) → 1..4, the bucket the row's text and tooltip key off.
-    // 0 for a row we have no answer for yet; the reference has no live countdown (its ticking
-    // version is commented out), so this only moves when a fresh list lands.
+    // GetAuctionItemTimeLeft(type, index) → the 1..4 bucket, 0 when unknown. The reference has no
+    // live countdown: it moves only when a new list lands.
     g.set(
         "GetAuctionItemTimeLeft",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -444,9 +370,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemLink(type, index) → the full item link. Auction rows carry enchant, random
-    // property and suffix on the wire, so the app builds the complete link rather than the
-    // zeroed-tail one the bag path settles for.
     g.set(
         "GetAuctionItemLink",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -454,8 +377,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 row_at(&model, &kind, index).and_then(|r| r.link)
             };
-            // A miss returns NO values at all — not nil (wow-re §5 TU-3). `DressUpItemLink(nil)`
-            // and `nil` reaching a chat insert behave differently from an empty argument list.
+            // A miss returns no values at all, not nil (`0x4cf45b`).
             Ok(match link {
                 Some(l) => MultiValue::from_vec(vec![Value::String(lua.create_string(&l)?)]),
                 None => MultiValue::new(),
@@ -463,12 +385,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedAuctionItem(type) → the 1-based selected row, or 0 for none.
-    //
-    // Stored as the **auction id**, resolved to a row position on the way out (wow-re §5 TU-5).
-    // That indirection is the whole reason a re-sort cannot silently move the selection onto a
-    // different auction: the id follows the row wherever the comparator puts it, and an auction
-    // that has left the page simply stops resolving instead of pointing at its neighbour.
+    // GetSelectedAuctionItem(type) → the selected row, 0 for none. Stored as the auction id and
+    // resolved on the way out (`0x4cfda0`/`0x4cfec0`), so it follows its auction through a re-sort.
     g.set(
         "GetSelectedAuctionItem",
         lua.create_function(|lua, kind: String| {
@@ -490,8 +408,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSelectedAuctionItem(type, index) — takes a row position and remembers the auction it
-    // names. An out-of-range index clears the selection rather than remembering a phantom.
+    // SetSelectedAuctionItem(type, index): remembers the auction at that row; out of range clears.
     g.set(
         "SetSelectedAuctionItem",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -509,9 +426,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SortAuctionItems(type, key) — queue the header click; the app owns the stacks and pushes the
-    // reordered rows back. The reference raises on a bad type, and that Usage string is recorded,
-    // so it is reproduced here rather than swallowed.
+    // SortAuctionItems(type, key): queue the header click for the app, which pushes the reordered
+    // rows back. The reference raises this `Usage:` only for an argument neither string nor number
+    // (`0x6f3510`) and matches both strings case-insensitively (`0x64a4c0`), an unknown one sorting
+    // nothing (`0x4cfd90`); here an unknown or differently cased type or column raises.
     g.set(
         "SortAuctionItems",
         lua.create_function(|lua, (kind, key): (String, String)| {
@@ -531,8 +449,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsAuctionSortReversed(type, key) → 1/nil. Answers for ANY key the stack remembers, not just
-    // the primary one — which is the whole reason a non-primary column's arrow can point down.
+    // IsAuctionSortReversed(type, key) → 1/nil, for any key the stack remembers.
     g.set(
         "IsAuctionSortReversed",
         lua.create_function(|lua, (kind, key): (String, String)| {
@@ -544,8 +461,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CanSendAuctionQuery() → 1/nil. Polled every frame by the Search button's OnUpdate, because
-    // a throttled query is dropped silently and there is no failure event to react to.
+    // CanSendAuctionQuery() → 1/nil; a throttled query is dropped silently.
     g.set(
         "CanSendAuctionQuery",
         lua.create_function(|lua, ()| {
@@ -554,10 +470,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemClasses() → the class names, in the reference's own menu order. The ORDER and
-    // the set are structural (ten auctionable classes); every string is the player's own
-    // ItemClass.dbc row, so none of Blizzard's text ships with us (decisions 1234/1260). Static —
-    // pushed at login, read by the stock addon at its load (1971), no session required.
+    // GetAuctionItemClasses() → the ten auctionable class names in the reference's menu order, off
+    // the player's ItemClass.dbc; pushed at login, no session needed.
     g.set(
         "GetAuctionItemClasses",
         lua.create_function(|lua, ()| {
@@ -577,8 +491,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionItemSubClasses(classIndex) → the subclass names under a 1-based menu class. An
-    // out-of-range index returns nothing, which is the reference's own bound-with-no-error.
+    // GetAuctionItemSubClasses(classIndex) → the subclass names; an out-of-range index or a class
+    // whose `0x807060` flag is 0 returns nothing, without an error (`0x4cfa00`, `0x4cfa0e`).
     g.set(
         "GetAuctionItemSubClasses",
         lua.create_function(|lua, class_index: usize| {
@@ -587,6 +501,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 class_index
                     .checked_sub(1)
                     .and_then(|i| model.auction_item_classes.get(i))
+                    .filter(|c| c.has_subclass_filter)
                     .map_or_else(Vec::new, |c| {
                         c.subclasses.iter().map(|s| s.name.clone()).collect()
                     })
@@ -599,10 +514,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionInvTypes(classIndex, subclassIndex) → the 14 inventory-slot GlobalString KEYS, or
-    // nothing. The pair only decides WHETHER the list is offered — the list itself is fixed. Which
-    // pairs offer it is pushed as data (`has_inv_types`), so decision 1511's INTERIM on that
-    // predicate is corrected app-side, not here.
+    // GetAuctionInvTypes(classIndex, subclassIndex) → the fixed 14 inventory-slot GlobalString
+    // keys, or nothing (`0x4cfab0`): nothing without a class (or with its `0x807060` flag 0); a
+    // found subclass needs `Flags & 0x200`, but an index the scan runs past skips that gate (the
+    // exhaust edge at `0x4cfb61` lands past the test at `0x4cfb63`).
     g.set(
         "GetAuctionInvTypes",
         lua.create_function(|lua, (class_index, sub_index): (usize, usize)| {
@@ -611,14 +526,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 class_index
                     .checked_sub(1)
                     .and_then(|i| model.auction_item_classes.get(i))
-                    .and_then(|c| sub_index.checked_sub(1).and_then(|i| c.subclasses.get(i)))
-                    .is_some_and(|s| s.has_inv_types)
+                    .filter(|c| c.has_subclass_filter)
+                    .is_some_and(|c| {
+                        sub_index
+                            .checked_sub(1)
+                            .and_then(|i| c.subclasses.get(i))
+                            .is_none_or(|s| s.has_inv_types)
+                    })
             };
             if !offers {
                 return Ok(MultiValue::new());
             }
             let mut out = Vec::with_capacity(AUCTION_INV_TYPES.len());
-            for key in AUCTION_INV_TYPES {
+            for (_, key) in AUCTION_INV_TYPES {
                 out.push(Value::String(lua.create_string(key)?));
             }
             Ok(MultiValue::from_vec(out))
@@ -626,9 +546,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // QueryAuctionItems(name, minLevel, maxLevel, invTypeIndex, classIndex, subclassIndex, page,
-    // isUsable, qualityIndex) — nine arguments (TBC's tenth, exactMatch, does not exist on 5875).
-    // The level boxes hand us strings, and every filter index is 1-based into the pushed tables;
-    // the app turns those into the wire's class/subclass ids and its 0xFFFFFFFF sentinels.
+    // isUsable, qualityIndex): nine arguments, no `exactMatch` in 1.12. Each filter is a 1-based
+    // menu position mapped to the wire id as `0x4ce980` does: invType through the `0x8070b0` rows,
+    // class through `0x807060`, subclass as the class's Nth non-excluded row (a scan that never
+    // reads the class's filter flag). Anything unresolved is the wire's "any".
     g.set(
         "QueryAuctionItems",
         lua.create_function(|lua, args: MultiValue| {
@@ -658,14 +579,25 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some(Value::Number(n)) if *n >= 0.0 => Some(*n as u32),
                 _ => None,
             };
+            let position = |i: usize| num(i).and_then(|n| (n as usize).checked_sub(1));
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
+            let inv_type = position(3)
+                .and_then(|i| AUCTION_INV_TYPES.get(i))
+                .map(|&(id, _)| id);
+            let category = position(4).and_then(|i| model.auction_item_classes.get(i));
+            let class = category.map(|c| c.class_id);
+            let sub_class = category.and_then(|c| {
+                position(5)
+                    .and_then(|i| c.subclasses.get(i))
+                    .map(|s| s.sub_id)
+            });
             model.auction_query = Some(AuctionQuery {
                 name,
                 min_level: num(1).unwrap_or(0),
                 max_level: num(2).unwrap_or(0),
-                inv_type: num(3).filter(|n| *n > 0),
-                class: num(4).filter(|n| *n > 0),
-                sub_class: num(5).filter(|n| *n > 0),
+                inv_type,
+                class,
+                sub_class,
                 quality,
                 page: num(6).unwrap_or(0),
                 usable_only: truthy(7),
@@ -674,8 +606,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetOwnerAuctionItems([page]) / GetBidderAuctionItems([page]) — the other two tabs' fetches.
-    // Neither is throttled the way Browse is; both default to page 0.
+    // GetOwnerAuctionItems([page]) / GetBidderAuctionItems([page]): unthrottled, page 0 by default.
     g.set(
         "GetOwnerAuctionItems",
         lua.create_function(|lua, page: Option<u32>| {
@@ -693,8 +624,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PlaceAuctionBid(type, index, bidAmount). A buyout is not a distinct verb — it is a bid of
-    // exactly the buyout price, which is why the confirmation popup calls straight into this.
+    // PlaceAuctionBid(type, index, bidAmount); a buyout is a bid of exactly the buyout price.
     g.set(
         "PlaceAuctionBid",
         lua.create_function(|lua, (kind, index, amount): (String, u32, u32)| {
@@ -711,7 +641,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // StartAuction(minBid, buyoutPrice, runTime) — runTime in minutes.
+    // StartAuction(minBid, buyoutPrice, runTime), runTime in minutes.
     g.set(
         "StartAuction",
         lua.create_function(|lua, (min_bid, buyout, duration): (u32, u32, u32)| {
@@ -725,7 +655,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelAuction(index) — always an "owner" row.
+    // CancelAuction(index), always an "owner" row.
     g.set(
         "CancelAuction",
         lua.create_function(|lua, index: u32| {
@@ -735,8 +665,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionHouseDepositRate() → the percentage, off AuctionHouse.dbc at this session's house.
-    // The shipped reference addon never calls it; third-party addons may, so we ship it.
     g.set(
         "GetAuctionHouseDepositRate",
         lua.create_function(|lua, ()| {
@@ -748,8 +676,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CalculateAuctionDeposit(runTime) → copper. See `deposit_for` — this is the client's own
-    // arithmetic, truncation included, not the server's charge.
+    // CalculateAuctionDeposit(runTime) → copper, by the client's arithmetic (`deposit_for`).
     g.set(
         "CalculateAuctionDeposit",
         lua.create_function(|lua, minutes: u32| {
@@ -760,9 +687,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAuctionSellItemInfo() → name, texture, count, quality, canUse, price. SIX values ALWAYS —
-    // the empty slot pushes a hard count of 1 and a quality of -1, never nils, because the
-    // reference Lua reads that count unguarded the moment the slot empties.
+    // GetAuctionSellItemInfo() → name, texture, count, quality, canUse, price: six values always.
+    // An empty slot answers count 1 and quality -1: the stock Lua reads `count > 1` unguarded.
     g.set(
         "GetAuctionSellItemInfo",
         lua.create_function(|lua, ()| {
@@ -798,9 +724,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClickAuctionSellItemButton() — attach the cursor's item, or take back the attached one. The
-    // mail send slot's exact shape (decision 0216's rails): every cursor write is followed by both
-    // queues, which is the law that keeps CURSOR_UPDATE and ITEM_LOCK_CHANGED honest.
+    // ClickAuctionSellItemButton(): attach the cursor's item, or pick the attached one back up;
+    // every cursor write queues both CURSOR_UPDATE and ITEM_LOCK_CHANGED.
     g.set(
         "ClickAuctionSellItemButton",
         lua.create_function(|lua, ()| {
@@ -810,7 +735,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseAuctionHouse() — the client-side close. Vanilla sends nothing; the session simply ends.
+    // CloseAuctionHouse(): the client-side close; nothing goes on the wire.
     g.set(
         "CloseAuctionHouse",
         lua.create_function(|lua, ()| {
@@ -823,29 +748,27 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The fourteen inventory-slot rows the reference offers, as GlobalString **keys** — the Lua
-/// resolves each through the player's own strings, so no English ships here. Inventory ids 1..12
-/// plus CLOAK(16) and HOLDABLE(23); the order is the reference's own.
-const AUCTION_INV_TYPES: [&str; 14] = [
-    "INVTYPE_HEAD",
-    "INVTYPE_NECK",
-    "INVTYPE_SHOULDER",
-    "INVTYPE_BODY",
-    "INVTYPE_CHEST",
-    "INVTYPE_WAIST",
-    "INVTYPE_LEGS",
-    "INVTYPE_FEET",
-    "INVTYPE_WRIST",
-    "INVTYPE_HAND",
-    "INVTYPE_FINGER",
-    "INVTYPE_TRINKET",
-    "INVTYPE_CLOAK",
-    "INVTYPE_HOLDABLE",
+/// The `0x8070b0` table's fourteen `{u32 invTypeId; char name[0x20]}` rows, in its order: the id
+/// goes on the wire, the name is a GlobalString key.
+const AUCTION_INV_TYPES: [(u32, &str); 14] = [
+    (1, "INVTYPE_HEAD"),
+    (2, "INVTYPE_NECK"),
+    (3, "INVTYPE_SHOULDER"),
+    (4, "INVTYPE_BODY"),
+    (5, "INVTYPE_CHEST"),
+    (6, "INVTYPE_WAIST"),
+    (7, "INVTYPE_LEGS"),
+    (8, "INVTYPE_FEET"),
+    (9, "INVTYPE_WRIST"),
+    (10, "INVTYPE_HAND"),
+    (11, "INVTYPE_FINGER"),
+    (12, "INVTYPE_TRINKET"),
+    (16, "INVTYPE_CLOAK"),
+    (23, "INVTYPE_HOLDABLE"),
 ];
 
-/// Attach the cursor's held item to the sell slot, or — with an empty cursor — pick the attached
-/// one back up. A spell or action payload is refused and put back untouched, exactly as the mail
-/// send slot refuses it.
+/// Attach the cursor's item to the sell slot, or with an empty cursor pick the attached one back
+/// up; any other payload stays on the cursor.
 fn click_auction_sell_item(model: &mut Model) {
     match model.cursor.take() {
         Some(CursorPayload::Item(item)) => {
@@ -893,12 +816,6 @@ mod tests {
         state
     }
 
-    /// The selection is an auction id, not a row position — so a re-sort moves the row under it
-    /// and the selection follows, rather than coming to mean whatever took that slot.
-    ///
-    /// This is the case an index would get silently wrong: pick row 2, re-sort, and an
-    /// index-based selection is now pointing at a *different auction* that the Bid button would
-    /// happily bid on.
     #[test]
     fn the_selection_follows_its_auction_through_a_resort() {
         let mut s = UiScript::new().unwrap();
@@ -921,7 +838,7 @@ mod tests {
             "auction 22 moved to row 1 and the selection went with it"
         );
 
-        // It leaves the page entirely (outbid, bought, or filtered out by a new search).
+        // It leaves the page.
         s.set_auction(Some(page(&[33, 44])));
         assert_eq!(
             s.eval::<i64>(r#"return GetSelectedAuctionItem("list")"#)
@@ -942,17 +859,12 @@ mod tests {
         );
     }
 
-    /// A WHOLE-STACK pickup carries no count of its own, so the sell slot has to read the real
-    /// stack size back off the source slot. Reading the cursor field directly answers 1 for a
-    /// stack of twenty — and since the deposit is charged per stack, the pane would quote a
-    /// twentieth of what the server then takes.
     #[test]
     fn the_sell_slot_reads_a_whole_stacks_real_size() {
         use crate::script::container::{ContainerSlot, ContainerState};
         use crate::script::cursor::CursorItem;
 
         let mut s = UiScript::new().unwrap();
-        // Twenty of item 2589 sitting in backpack slot 1.
         let mut slots = std::collections::HashMap::new();
         slots.insert(
             1u32,
@@ -970,7 +882,7 @@ mod tests {
                 slots,
             }),
         );
-        // Picked up whole — `count: None` is the "whole stack" signal, not "one".
+        // Picked up whole: `count: None` means the whole stack, not one.
         {
             let mut model = s.model_mut();
             model.auction_sell_item = Some(CursorItem {
@@ -991,9 +903,6 @@ mod tests {
         assert_eq!(count, 20, "the whole stack, not one of it");
     }
 
-    /// The null tail is twelve values with a hard `count = 1` and `quality = -1`. The reference
-    /// Lua destructures all twelve unguarded, so a short return throws rather than showing an
-    /// empty row.
     #[test]
     fn a_missing_row_still_answers_twelve_values() {
         let s = UiScript::new().unwrap();
@@ -1004,18 +913,14 @@ mod tests {
             .unwrap();
         assert_eq!((count, quality), (1, -1));
 
-        // The link, by contrast, answers with NO values on a miss — not a nil.
+        // The link answers no values on a miss, not a nil.
         let n = s.arity(r#"GetAuctionItemLink("list", 99)"#).unwrap();
         assert_eq!(n, 0, "zero values, not one nil");
     }
 
-    /// The client's own deposit arithmetic, including the intermediate truncation that makes it
-    /// disagree with the server (decision 1511 §7). The cheap-stack case is the one that matters:
-    /// a 9-copper vendor value at 5% over 24h floors to 0 here while vmangos still charges 5, and
-    /// that divergence is deliberate — the label is a client artifact.
+    /// A 9-copper stack at 5% over 24 h deposits 0 here, where vmangos charges 5.
     #[test]
     fn the_deposit_is_the_clients_arithmetic_truncation_and_all() {
-        // 5% of 9c = 0 after the inner floor, so no duration can lift it off zero.
         assert_eq!(deposit_for(5, 9, 1440), 0);
         // Once the inner floor clears, the duration scales it 1 / 4 / 12.
         assert_eq!(deposit_for(5, 10_000, 120), 500);
@@ -1023,13 +928,100 @@ mod tests {
         assert_eq!(deposit_for(5, 10_000, 1440), 6_000);
         // Blackwater's 25% on the same stack.
         assert_eq!(deposit_for(25, 10_000, 120), 2_500);
-        // A duration under the two-hour unit floors the whole thing away — the reference refuses
-        // to send such a duration at all, so this is a shape check, not a reachable state.
+        // Under the two-hour unit it floors to 0; the reference never sends such a duration.
         assert_eq!(deposit_for(5, 10_000, 60), 0);
     }
 
-    /// The sort stack answers for any key it remembers, not just the primary — the reason a
-    /// non-primary column's arrow can still point down.
+    /// Weapon and Armor, then Consumable (flag 0: no subclass rows, but the query scans them).
+    fn tree() -> Vec<AuctionCategory> {
+        let sub = |sub_id: u32, name: &str, has_inv_types: bool| AuctionSubCategory {
+            sub_id,
+            name: name.into(),
+            has_inv_types,
+        };
+        vec![
+            AuctionCategory {
+                class_id: 2,
+                name: "Weapon".into(),
+                has_subclass_filter: true,
+                subclasses: vec![sub(0, "Axe", false), sub(1, "Axe", false)],
+            },
+            AuctionCategory {
+                class_id: 4,
+                name: "Armor".into(),
+                has_subclass_filter: true,
+                subclasses: vec![sub(1, "Cloth", true), sub(6, "Shield", false)],
+            },
+            AuctionCategory {
+                class_id: 0,
+                name: "Consumable".into(),
+                has_subclass_filter: false,
+                subclasses: vec![sub(0, "Consumable", false)],
+            },
+        ]
+    }
+
+    #[test]
+    fn query_sends_ids_not_menu_positions() {
+        let mut s = UiScript::new().unwrap();
+        s.set_auction_item_classes(tree());
+
+        // Weapon / its first subclass / Back (the 13th inventory row).
+        s.run(r#"QueryAuctionItems("", "", "", 13, 1, 1, 0, nil, -1)"#)
+            .unwrap();
+        let q = s.take_auction_query().expect("queued");
+        assert_eq!(q.inv_type, Some(16), "INVTYPE_CLOAK is inventory type 16");
+        assert_eq!(q.class, Some(2), "Weapon is item class 2, not position 1");
+        assert_eq!(q.sub_class, Some(0), "the first weapon subclass is id 0");
+
+        // Armor / its second subclass skips the id gap: Shield is 6, not 2.
+        s.run(r#"QueryAuctionItems("", "", "", 14, 2, 2, 0, nil, -1)"#)
+            .unwrap();
+        let q = s.take_auction_query().expect("queued");
+        assert_eq!(
+            (q.inv_type, q.class, q.sub_class),
+            (Some(23), Some(4), Some(6))
+        );
+
+        // The scan ignores the filter flag: Consumable offers no subclass rows, yet resolves one.
+        s.run(r#"QueryAuctionItems("", "", "", 0, 3, 1, 0, nil, -1)"#)
+            .unwrap();
+        let q = s.take_auction_query().expect("queued");
+        assert_eq!((q.inv_type, q.class, q.sub_class), (None, Some(0), Some(0)));
+
+        // Out of range, or no class to scan under: the wire's "any".
+        s.run(r#"QueryAuctionItems("", "", "", 15, 11, 1, 0, nil, -1)"#)
+            .unwrap();
+        let q = s.take_auction_query().expect("queued");
+        assert_eq!((q.inv_type, q.class, q.sub_class), (None, None, None));
+        s.run(r#"QueryAuctionItems("", "", "", nil, 1, 3, 0, nil, -1)"#)
+            .unwrap();
+        let q = s.take_auction_query().expect("queued");
+        assert_eq!((q.inv_type, q.class, q.sub_class), (None, Some(2), None));
+    }
+
+    /// The gates of `0x4cf9c0` (subclasses) and `0x4cfab0` (inventory types).
+    #[test]
+    fn subclass_and_inv_type_menus_follow_the_reference_gates() {
+        let mut s = UiScript::new().unwrap();
+        s.set_auction_item_classes(tree());
+        assert_eq!(s.arity("GetAuctionItemSubClasses(1)").unwrap(), 2);
+        assert_eq!(
+            s.arity("GetAuctionItemSubClasses(3)").unwrap(),
+            0,
+            "Consumable's flag is 0: no subclass rows"
+        );
+        assert_eq!(s.arity("GetAuctionInvTypes(2, 1)").unwrap(), 14, "Cloth");
+        assert_eq!(s.arity("GetAuctionInvTypes(2, 2)").unwrap(), 0, "Shield");
+        assert_eq!(s.arity("GetAuctionInvTypes(3, 1)").unwrap(), 0, "flag 0");
+        assert_eq!(s.arity("GetAuctionInvTypes(11, 1)").unwrap(), 0, "no class");
+        assert_eq!(
+            s.arity("GetAuctionInvTypes(1, 9)").unwrap(),
+            14,
+            "an exhausted scan skips the gate"
+        );
+    }
+
     #[test]
     fn reversed_answers_for_any_remembered_key() {
         let list = AuctionListState {
diff --git a/crates/benilla-ui/src/script/aura/mod.rs b/crates/benilla-ui/src/script/aura/mod.rs
index 341c79f0..db930c69 100644
--- a/crates/benilla-ui/src/script/aura/mod.rs
+++ b/crates/benilla-ui/src/script/aura/mod.rs
@@ -1,86 +1,15 @@
-//! The game-state aura bindings — **two dialects over one list** (decisions 0255, 0257).
+//! The aura bindings, over the per-token lists the app pushes through [`UiScript::set_auras`] in
+//! display order: the player's in the reference's insertion-ordered cache (`0xbc6040`), kept by
+//! `benilla::ui_aura`, any other unit's by ascending aura slot. The player's list keeps cache order
+//! under every token, where the reference's `UnitBuff("player", i)` reads by slot.
 //!
-//! Same engine-free seam as [`super::unit`]: the app pushes a per-token, **already ordered** list of
-//! [`AuraState`] via [`UiScript::set_auras`], and these globals index it. This module deliberately
-//! knows nothing about slots, caches, or descriptors — the *order* of the list is the app's to decide,
-//! because the two orderings the reference uses are not derivable from a snapshot:
+//! `UnitAura`, `UnitBuff`, `UnitDebuff` and `CancelUnitBuff` take a token and a 1-based index into
+//! the sign-filtered list; the getters answer nil past the end. The 1.12 `GetPlayerBuff`
+//! ([`player_buff`]) takes a 0-based index and returns a cache position, the same number under
+//! every filter, which its siblings and `GameTooltip:SetPlayerBuff` take in place of the counter.
 //!
-//! - the player's own bar walks a densely packed cache in **insertion order** (`GetPlayerBuff`), and
-//! - any other unit is read straight off its aura array, ascending slot (`UnitBuff`/`UnitDebuff`).
-//!
-//! Decision 0257 resolves that split toward the player-bar law for the local player under every token,
-//! since the Era API has one aura function where 1.12 had two.
-//!
-//! # The two dialects
-//!
-//! **Era** — `UnitAura`/`UnitBuff`/`UnitDebuff`/`CancelUnitBuff`: a token plus a **1-based** index
-//! *within the sign-filtered list*, terminated by a bare `nil`. This is the shape our own transcribed
-//! frames use.
-//!
-//! **1.12** — the `GetPlayerBuff*` family plus `CancelPlayerBuff`: the player only, no token, a
-//! **0-based** index, and — the part no documentation gets right — `GetPlayerBuff` does not return the
-//! aura. It returns a **handle**: the aura's *physical position* in the cache, `-1` past the end. Every
-//! sibling (`GetPlayerBuffTexture`, `…TimeLeft`, `…DispelType`, `…Applications`, `CancelPlayerBuff`,
-//! and `GameTooltip:SetPlayerBuff`) takes that position, **not** the loop counter. So the family is a
-//! two-step: enumerate to get a position, then read the position.
-//!
-//! That two-step is what makes the index space *absolute*: the position a filtered enumeration hands
-//! back is the same number an unfiltered one would, which is exactly what the corpus relies on
-//! (`CT_BuffMod/CT_BuffFrame.lua:73-79` obtains an index under `"HARMFUL"` and compares it for
-//! equality against one obtained under `"HELPFUL|HARMFUL"`; `Zorlen/Zorlen.lua:2798` intersects the
-//! filtered and unfiltered walks at the same counter).
-//!
-//! Because [`AuraState`] lists are pushed in the app's display order and the player's list **is** the
-//! reference's `0xbc6040` insertion-ordered cache (`benilla::ui_aura`), a cache position is simply a
-//! 0-based index into `model.auras["player"]`. No second structure exists, and none is needed.
-//!
-//! # Byte-verified signatures (`~/dev/wow-5875-re/WoW/WoW.exe`, `system/ui/ledger.tsv`)
-//!
-//! Read off the disassembly, not off a wiki — a later client changed every one of these shapes, and a
-//! wrong shape fails *silently*.
-//!
-//! | verb | addr | returns | miss |
-//! |---|---|---|---|
-//! | `GetPlayerBuff(index [, "filter"])` | `0x4e45d0` | **always 2** numbers: `pos`, `untilCancelled` | `(-1, 0)` |
-//! | `GetPlayerBuffTexture(pos)` | `0x4e4740` | 1: icon path or nil | nil |
-//! | `GetPlayerBuffDispelType(pos)` | `0x4e4800` | 1: dispel-class name or nil | nil |
-//! | `GetPlayerBuffApplications(pos)` | `0x4e48b0` | 1: number | **`1`** |
-//! | `GetPlayerBuffTimeLeft(pos)` | `0x4e4930` | 1: **seconds** | `0` |
-//! | `CancelPlayerBuff(pos)` | `0x4e49a0` | **0** values | — |
-//!
-//! The traps, each with the site that pins it:
-//!
-//! - **`-1`, never nil.** `GetPlayerBuff` seeds its out-parameter to `-1` (`mov DWORD PTR [ebp-4],
-//!   0xffffffff`, `0x4e46ea`) and pushes it unconditionally, then pushes `record+0xc` or `0`
-//!   (`0x4e46f6`/`0x4e4728`), returning `mov eax,0x2` on **both** paths. The corpus terminates on the
-//!   number — `while GetPlayerBuff(counter) >= 0 do` (`_LazyPig/LazyPig.lua:1174`) — so a nil past the
-//!   end is `attempt to compare nil with number`, and *zero* returns is the same crash.
-//! - **0-based.** `lua_tonumber` → `__ftol` → used raw, with **no `dec`** (`0x4e460a`-`0x4e4616`);
-//!   contrast `UnitBuff 0x519500`, which does `dec eax` at `0x519579`. Every enumerating call site in
-//!   the corpus starts at `0`; the reference's own buttons are `BuffButton0`..`BuffButton23` with
-//!   `id="0"` upward (`ref-BuffFrame.xml:159`).
-//! - **The default filter is `HELPFUL|HARMFUL`, not `HELPFUL`.** `mov esi,0x3` at `0x4e4618`, kept
-//!   when the `lua_isstring` check on arg 2 fails. This is the one that would have failed silently:
-//!   `Zorlen/Zorlen.lua:2797-2801` walks *unfiltered* and feeds each index to
-//!   `GetPlayerBuffDispelType` looking for `"Poison"`/`"Disease"` (`Zorlen_Other.lua:94,98`) — a
-//!   debuff-only concept. Under a `HELPFUL` default that check never matches, and nothing errors.
-//! - **`untilCancelled` is the number `0`/`1`.** Five corpus sites compare it to the *number* `1`
-//!   (`CT_BuffMod/CT_BuffFrame.lua:175,232`; `_LazyPig/LazyPig.lua:2071`; `Zorlen/Zorlen.lua:2800`;
-//!   `ElkBuffBar/ElkBuffBar.lua:502`), as does `ref-BuffFrame.lua:124`. A boolean breaks all six:
-//!   `true ~= 1`.
-//! - **`PASSIVE` is not a token here.** The parser knows exactly four (`stricmp` against `0x84bc34`
-//!   `HELPFUL`=`0x1`, `0x84bc2c` `HARMFUL`=`0x2`, `0x84bc20` `CANCELABLE`=`0x10`, `0x84bc10`
-//!   `NOT_CANCELABLE`=`0x20`; `0x4e4661`-`0x4e46cf`). A `"PASSIVE"` string does exist in the binary at
-//!   `0x806a30`, but `0x4e45d0` never references it — and no corpus addon passes it.
-//! - **The mask starts at ZERO once a filter string is given** (`xor esi,esi`, `0x4e4639`). So
-//!   `GetPlayerBuff(0, "CANCELABLE")` matches *nothing* — neither sign bit is set — where
-//!   [`super::unit`]-style parsing would have defaulted the sign to helpful. Delimiters are
-//!   `" |"` (`0x84bc3c`), i.e. space **or** pipe.
-//!
-//! **Stated gaps, not hidden.** `source` (the caster) is always nil and `duration`/`expirationTime`
-//! are `0` for every unit but the player: the 1.12 wire carries no aura caster at all, and no duration
-//! for anyone but yourself (byte-verified, decision 0257 B6/B10). The reference's own target and party
-//! frames show no timers for the same reason.
+//! `source` is always nil, and only the player's auras carry a duration: the 1.12 wire has no aura
+//! caster and sends durations for the player alone, so the stock target frame shows no timers.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -88,69 +17,51 @@ use super::Model;
 
 mod player_buff;
 
-/// One aura on one unit, as the Era `UnitAura` family reports it. Plain data (no mlua handles, no ECS
-/// types), pushed by the app's [`crate::script::UiScript::set_auras`] feed each frame.
+/// One aura on one unit, as the app's [`crate::script::UiScript::set_auras`] feed pushes it.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct AuraState {
-    /// `Spell.dbc` id (`UnitAura`'s `spellId`).
+    /// `Spell.dbc` id, `UnitAura`'s `spellId`.
     pub spell_id: u32,
-    /// The spell's name, or `None` when the catalog doesn't know the id (`UnitAura` returns nil).
+    /// The spell's name; `None` when the catalog lacks the id.
     pub name: Option<String>,
     /// The icon's extensionless MPQ path (`Interface\Icons\…`).
     pub icon: Option<String>,
-    /// Stack count, ≥ 1 (`UnitAura`'s `count`). The reference shows the number only above 1.
+    /// Stack count, at least 1; the reference shows it only above 1.
     pub count: u8,
-    /// `"Magic"`/`"Curse"`/`"Disease"`/`"Poison"`, or `None` for an undispellable class — the
-    /// `debuffType` return, which the debuff border tints by.
+    /// `"Magic"`, `"Curse"`, `"Disease"`, `"Poison"` or `None`; the debuff border tints by it.
     pub debuff_type: Option<String>,
-    /// The full duration in seconds as the last apply/refresh reported it; `0.0` = no duration
-    /// (a permanent aura, or any aura on a unit that isn't the player).
+    /// Seconds, from the last apply or refresh; 0 when permanent or on a unit not the player.
     pub duration: f64,
-    /// The `GetTime()`-based instant this aura runs out; `0.0` when [`Self::duration`] is `0.0`.
-    /// Lua counts down against it, exactly as `CastingBar.xml` does for a cast.
+    /// The `GetTime()` instant it runs out; 0 when [`Self::duration`] is 0.
     pub expiration_time: f64,
-    /// A buff (helpful) rather than a debuff — the `HELPFUL`/`HARMFUL` filter's discriminator.
+    /// A buff rather than a debuff: the `HELPFUL`/`HARMFUL` filter's test.
     pub helpful: bool,
-    /// Whether right-clicking it will be honoured (the wire's `AFLAG_CANCELABLE`) — the
-    /// `CANCELABLE`/`NOT_CANCELABLE` filter's discriminator.
+    /// The wire's `AFLAG_CANCELABLE`: the `CANCELABLE`/`NOT_CANCELABLE` filter's test.
     pub cancelable: bool,
-    /// **`GetPlayerBuff`'s second return** — the reference's cache record `+0xc`: "this aura has no
-    /// finite duration to display."
-    ///
-    /// DBC-derived at cache-build time, and deliberately **not** the same question as
-    /// `expiration_time == 0.0`: it is computed from the spell, so it is right on the frame an aura
-    /// appears, before any `SMSG_UPDATE_AURA_DURATION` has arrived. That is the whole point of it —
-    /// `ref-BuffFrame.lua:124` returns *before* calling `GetPlayerBuffTimeLeft` when it is `1`, so a
-    /// permanent aura never flickers a `0 s` timer. The app fills it (`benilla::ui_aura`) from the
-    /// byte-verified derivation at `0x4e452e`-`0x4e45c5`; see there for the two clauses.
+    /// `GetPlayerBuff`'s second return, cache record `+0xc`: no finite duration to show. Derived
+    /// from the spell (`0x4e452e`-`0x4e45c5`), not from `expiration_time`, so it holds before any
+    /// `SMSG_UPDATE_AURA_DURATION` and a permanent aura never shows a `0 s` timer.
     pub until_cancelled: bool,
-    /// `Spell.dbc` `AttributesEx & 0x4` (`SPELL_ATTR_EX_IS_CHANNELED`) — the **second** arm of the
-    /// cancel gate, and the only one that can authorise cancelling a *negative* aura. See
-    /// [`cancel_authorized`].
+    /// `AttributesEx & 0x4` (`SPELL_ATTR_EX_IS_CHANNELED`), [`cancel_authorized`]'s second arm.
     pub channeled: bool,
 }
 
-/// The player's active tracking aura — the engine mirror of the reference's tracking global
-/// (`DAT_00bc6378`): during the aura-cache rebuild the client *excludes* a tracking-effect spell
-/// (Find Minerals, Track Beasts, …) from the display cache and records it here instead;
-/// `GetTrackingTexture` is the one reader (wow-re `aura-display-pipeline.md` §3 — the
-/// `{0x2c,0x2d,0x97}` effect test). Pushed by the app's aura feed via [`UiScript::set_tracking`];
-/// `None` = no tracking active (the minimap frame hides).
+/// The player's active tracking aura, the reference's tracking global (`0xbc6378`): the cache
+/// rebuild records a spell with a tracking effect (`0x2c`, `0x2d`, `0x97`) there instead of in
+/// the display cache, and `GetTrackingTexture` (`0x4e4a20`) reads it.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TrackingState {
-    /// `Spell.dbc` id — `CancelTrackingBuff`'s `CMSG_CANCEL_AURA` payload.
+    /// `Spell.dbc` id, the `CMSG_CANCEL_AURA` payload of `CancelTrackingBuff`.
     pub spell_id: u32,
-    /// The spell's name, or `None` when the catalog doesn't know the id (tooltip fallback line).
+    /// The spell's name; `None` when the catalog lacks the id.
     pub name: Option<String>,
-    /// The icon's extensionless MPQ path — `GetTrackingTexture`'s return (`nil` when unknown).
+    /// The icon's extensionless MPQ path, `GetTrackingTexture`'s return.
     pub icon: Option<String>,
-    /// The wire's `AFLAG_CANCELABLE` on the tracking aura's slot — `CancelTrackingBuff`'s gate,
-    /// same client-side check as `CancelUnitBuff`'s.
+    /// The wire's `AFLAG_CANCELABLE` on the aura's slot, `CancelTrackingBuff`'s gate.
     pub cancelable: bool,
 }
 
-/// The parsed `filter` argument: a `|`-separated token set. Absent or sign-less defaults to
-/// `HELPFUL`, matching the live API (`UnitAura(unit, i)` enumerates buffs).
+/// `UnitAura`'s `filter`: `|`-separated tokens, the sign defaulting to `HELPFUL` as in the Era API.
 struct Filter {
     helpful: bool,
     cancelable: Option<bool>,
@@ -161,12 +72,11 @@ impl Filter {
         let spec = spec.unwrap_or("");
         let has = |t: &str| spec.split('|').any(|s| s.trim().eq_ignore_ascii_case(t));
         Self {
-            // HARMFUL wins only if named; everything else (including "CANCELABLE" alone) is HELPFUL.
             helpful: !has("HARMFUL"),
             cancelable: match (has("CANCELABLE"), has("NOT_CANCELABLE")) {
                 (true, false) => Some(true),
                 (false, true) => Some(false),
-                // Both or neither: no cancelable constraint (the reference never passes both).
+                // Both or neither: no constraint; the reference never passes both.
                 _ => None,
             },
         }
@@ -177,35 +87,16 @@ impl Filter {
     }
 }
 
-/// May this aura be cancelled? **One law, two entry points** — `CancelUnitBuff` (the Era name) and
-/// `CancelPlayerBuff` (the 1.12 name) are the same verb over the same cache, so they share the gate
-/// and the queue rather than growing a second mechanism.
-///
-/// Byte-verified, `CancelPlayerBuff 0x4e49a0` (`0x4e49fb`-`0x4e4a14`) — an **OR** of two arms:
-///
-/// 1. the **wire** arm: the aura sits in the positive half (`record.slot < 0x20`, i.e. helpful) AND
-///    carries `AFLAG_CANCELABLE` (`record+0xa & 0x1`), which vmangos sets iff the aura is positive
-///    and the spell lacks `SPELL_ATTR_NO_AURA_CANCEL`; OR
-/// 2. the **DBC** arm: the spell has `AttributesEx & 0x4` (`SPELL_ATTR_EX_IS_CHANNELED`) — the only
-///    way a *negative* aura becomes cancellable, which is how you break a channel being held on you.
-///
-/// Neither arm alone is the gate; reading only the first (the shape `CancelUnitBuff` shipped with)
-/// silently refuses the channeled case.
+/// The cancel gate of `CancelUnitBuff` and `CancelPlayerBuff` (`0x4e49a0`, `0x4e49fb`-`0x4e4a14`):
+/// a helpful aura with `AFLAG_CANCELABLE` (vmangos: unless `SPELL_ATTR_NO_AURA_CANCEL`), or any
+/// aura of a channeled spell, the only negative aura that cancels (breaking a channel on you).
 pub(super) fn cancel_authorized(a: &AuraState) -> bool {
     (a.helpful && a.cancelable) || a.channeled
 }
 
-/// `UnitAura`'s return tuple for a hit. Order and arity follow the Classic Era signature:
-/// `name, icon, count, debuffType, duration, expirationTime, source, isStealable,
-/// nameplateShowPersonal, spellId`. The three we cannot know on this wire (`source`, `isStealable`,
-/// `nameplateShowPersonal`) return nil — an addon that reads them sees "unknown", which is honest,
-/// rather than a fabricated value.
-/// The **1.12** return tuple, which is a different shape and not a prefix of the Era one: the first
-/// value is the TEXTURE, not the name. `UnitBuff` returns `(texture, applications)` (`0x519500`) and
-/// `UnitDebuff` returns `(texture, applications, dispelType)` (`0x5198f0`) — both `verified` in
-/// wow-re's ledger, and both are what the reference's own FrameXML reads
-/// (`TargetFrame.lua:287-290` binds `debuff, debuffStack, debuffType` and then
-/// `SetTexture(debuff)`). Decision 1818, which also records why the Era shape was serving nobody.
+/// The 1.12 tuple, not a prefix of the Era one: `UnitBuff` returns `(texture, applications)`
+/// (`0x519500`) and `UnitDebuff` adds `dispelType` (`0x5198f0`), as stock `TargetFrame.lua:287-290`
+/// reads them.
 fn returns_1121(lua: &Lua, a: &AuraState, with_dispel_type: bool) -> mlua::Result<MultiValue> {
     let icon = match &a.icon {
         Some(t) => Value::String(lua.create_string(t)?),
@@ -221,10 +112,10 @@ fn returns_1121(lua: &Lua, a: &AuraState, with_dispel_type: bool) -> mlua::Resul
     Ok(MultiValue::from_vec(out))
 }
 
-/// Which return shape a getter wants — the two are not compatible, see [`returns_1121`].
+/// Which return tuple a getter pushes.
 #[derive(Clone, Copy)]
 enum Shape {
-    /// `UnitAura`'s ten values. Era-only: the name does not exist in 1.12 FrameXML at all.
+    /// `UnitAura`'s ten values, the Era signature.
     Era,
     /// `UnitBuff`'s two.
     Buff,
@@ -246,16 +137,15 @@ fn returns(lua: &Lua, a: &AuraState) -> mlua::Result<MultiValue> {
         s(&a.debuff_type)?,
         Value::Number(a.duration),
         Value::Number(a.expiration_time),
-        Value::Nil, // source — no aura caster exists on the 1.12 wire, for any unit (0257 B10)
-        Value::Nil, // isStealable — Spellsteal is TBC
+        Value::Nil, // source: the 1.12 wire carries no aura caster
+        Value::Nil, // isStealable: Spellsteal is TBC
         Value::Nil, // nameplateShowPersonal
         Value::Integer(i64::from(a.spell_id)),
     ]))
 }
 
-/// The shared body of `UnitAura`/`UnitBuff`/`UnitDebuff`: take the `index`-th (1-based) aura of
-/// `unit` that passes `filter`, in the order the app pushed them. Out of range → a bare nil, the
-/// live API's "no more auras" terminator that every `for i = 1, N` loop breaks on.
+/// The `index`-th (1-based) aura of `token` passing `filter`, in pushed order; out of range is a
+/// bare nil, the loop terminator.
 fn nth_aura(
     lua: &Lua,
     token: &Option<String>,
@@ -289,9 +179,8 @@ fn nth_aura(
 }
 
 impl super::UiScript {
-    /// Push (or clear) a unit token's aura list, **in display order** — the app decides that order
-    /// (decision 0257): the maintained insertion-order cache for the local player, ascending aura
-    /// slot for anyone else. `None` (or an empty list) makes every `UnitAura(token, i)` return nil.
+    /// Push or clear a token's aura list, in display order: cache order for the player, ascending
+    /// aura slot for anyone else.
     pub fn set_auras(&mut self, token: &str, auras: Option<Vec<AuraState>>) {
         let mut model = self.model_mut();
         match auras {
@@ -304,28 +193,24 @@ impl super::UiScript {
         }
     }
 
-    /// Push (or clear) the player's active tracking aura ([`TrackingState`] doc) — the app's aura
-    /// feed derives it from the same walk that excludes tracking spells from the display lists.
+    /// Push or clear the player's active [`TrackingState`].
     pub fn set_tracking(&mut self, tracking: Option<TrackingState>) {
         self.model_mut().tracking = tracking;
     }
 
-    /// Drain the spell ids `CancelUnitBuff` queued since the last call — the app sends one
-    /// `CMSG_CANCEL_AURA` per id (the server cancels by spell, never by slot; decision 0257 B8).
+    /// Drain the queued cancels, one `CMSG_CANCEL_AURA` per spell id: the server cancels by spell,
+    /// never by slot.
     pub fn take_cancel_aura_requests(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().cancel_aura_requests)
     }
 }
 
-/// Register `UnitAura`, `UnitBuff`, `UnitDebuff` and `CancelUnitBuff`, plus the 1.12 `GetPlayerBuff*`
-/// family ([`player_buff`]).
+/// Register the aura and tracking globals, the `GetPlayerBuff` family from [`player_buff`].
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // UnitAura(unit, index [, filter]) — filter defaults to HELPFUL, like the live API. This one
-    // keeps the Era tuple: it is not a 1.12 verb at all (zero occurrences in the reference's
-    // FrameXML) and has zero call sites in the 110-addon corpus, so it costs nothing and stays the
-    // Era-compat surface 0068 asked for.
+    // UnitAura(unit, index [, filter]), filter defaulting to HELPFUL, with the Era tuple: not a
+    // 1.12 verb.
     g.set(
         "UnitAura",
         lua.create_function(
@@ -341,18 +226,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // UnitBuff(unit, index [, raidFilter]) / UnitDebuff(unit, index [, raidFilter]) — the 1.12
-    // signature and the 1.12 RETURN SHAPE (decision 1818). The sign is fixed by the verb, not by a
-    // filter word: `0x519500` reads aura slots 0..31 and `0x5198f0` reads 32..47.
-    //
-    // **The third argument is a `raidFilter` flag, not Era's filter string.** Non-zero enables ONE
-    // extra per-slot predicate — castable-by-me for buffs (`0x4b3870`), dispellable-by-me for
-    // debuffs (`0x4b3920`). We accept it and DO NOT apply it, because [`AuraState`] holds neither
-    // fact and neither is derivable from the aura feed: castable-by-me needs the player's spellbook,
-    // dispellable-by-me needs a class→dispel-type table joined to `debuff_type`. Inventing an answer
-    // is the guess 1203 exists to prevent, so the flag is parked here in the open. Visible
-    // consequence, so nobody has to rediscover it: the pet frame's buff row and the
-    // dispellable-debuff rows show everything rather than only what the player can cast or dispel.
+    // UnitBuff(unit, index [, raidFilter]) and UnitDebuff: the verb fixes the sign, `0x519500`
+    // reading aura slots 0..31 and `0x5198f0` slots 32..47. A non-zero `raidFilter` keeps only
+    // buffs the player can cast (`0x4b3870`) or debuffs they can dispel (`0x4b3920`); it is
+    // accepted, not applied, as `AuraState` holds neither fact, so the pet frame's buff row and the
+    // dispellable-debuff rows show every aura.
     g.set(
         "UnitBuff",
         lua.create_function(
@@ -382,11 +260,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // CancelUnitBuff(unit, index [, filter]) — the Era name for the reference's
-    // `CancelPlayerBuff(buffIndex)`. Resolves the aura the same way the getters do, then queues its
-    // SPELL ID for the app: the server's `CMSG_CANCEL_AURA` carries a spell, not a slot, and refuses
-    // anything not cancelable. A non-cancelable aura (or a missing one) is a silent no-op, as in the
-    // reference, where the client's own `AFLAG_CANCELABLE` gate never sends the packet.
+    // CancelUnitBuff(unit, index [, filter]): not a 1.12 verb, the Era name for the reference's
+    // `CancelPlayerBuff`. It queues the aura's spell id, what `CMSG_CANCEL_AURA` carries; an aura
+    // the gate refuses is a silent no-op, as in the reference.
     g.set(
         "CancelUnitBuff",
         lua.create_function(
@@ -420,9 +296,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     player_buff::install(lua)?;
 
-    // GetTrackingTexture() — the reference's `0x4e4a20`: the icon path of the active tracking
-    // spell (the tracking global's occupant), or nil when none — `MiniMapTrackingFrame`'s
-    // show/hide + SetTexture driver on PLAYER_AURAS_CHANGED (ref-Minimap.xml l.150-159).
+    // GetTrackingTexture() (`0x4e4a20`): the tracking spell's icon or nil, which shows or hides
+    // the stock `MiniMapTrackingFrame` (`Minimap.xml:150-159`).
     g.set(
         "GetTrackingTexture",
         lua.create_function(|lua, ()| {
@@ -431,10 +306,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelTrackingBuff() — the reference's `0x4e4a80` (the tracking frame's right-click): cancel
-    // the active tracking aura by SPELL id through the same `CMSG_CANCEL_AURA` queue as
-    // `CancelUnitBuff`, behind the same client-side `AFLAG_CANCELABLE` gate. No tracking active
-    // is a silent no-op.
+    // CancelTrackingBuff() (`0x4e4a80`), the tracking frame's right-click: queues the tracking
+    // spell's id behind its `AFLAG_CANCELABLE`; with no tracking it is a no-op.
     g.set(
         "CancelTrackingBuff",
         lua.create_function(|lua, ()| {
@@ -470,8 +343,6 @@ mod tests {
         }
     }
 
-    /// The list the app pushes IS the enumeration order — the binding never re-sorts it. This is the
-    /// contract decision 0257 rests on: the player's insertion-ordered cache survives the seam.
     #[test]
     fn unit_aura_enumerates_the_pushed_order_not_the_spell_id_order() {
         let mut s = UiScript::new().unwrap();
@@ -483,14 +354,12 @@ mod tests {
                 aura(589, "Shadow Word: Pain", false, false),
             ]),
         );
-        // Buffs, in the pushed order (not ascending spell id).
         assert_eq!(
             s.eval::<String>(r#"return (UnitAura("player", 1))"#)
                 .unwrap(),
             "Battle Stance"
         );
-        // `UnitBuff`/`UnitDebuff` enumerate the same list, but their first return is the ICON, not
-        // the name (1.12's shape — decision 1818), so they are addressed by it here.
+        // `UnitBuff` and `UnitDebuff` return the icon first, the 1.12 shape.
         assert_eq!(
             s.eval::<String>(r#"return (UnitBuff("player", 2))"#)
                 .unwrap(),
@@ -502,14 +371,12 @@ mod tests {
                 .unwrap(),
             "Interface\\Icons\\Spell_589"
         );
-        // Past the end → nil, the loop terminator.
         assert!(s
             .eval::<bool>(r#"return UnitBuff("player", 3) == nil"#)
             .unwrap());
         assert!(s
             .eval::<bool>(r#"return UnitDebuff("player", 2) == nil"#)
             .unwrap());
-        // An unknown token, and a zero/negative index, are the same "no aura" shape.
         assert!(s
             .eval::<bool>(r#"return UnitAura("target", 1) == nil"#)
             .unwrap());
@@ -525,11 +392,11 @@ mod tests {
             "player",
             Some(vec![
                 aura(2457, "Battle Stance", true, true),
-                aura(9999, "Sealed", true, false), // helpful but not cancelable
+                aura(9999, "Sealed", true, false), // helpful, not cancelable
                 aura(589, "Pain", false, false),
             ]),
         );
-        // No filter ⇒ HELPFUL: two hits, the debuff invisible.
+        // No filter means HELPFUL.
         assert_eq!(
             s.eval::<i64>(
                 r#"local n = 0 for i=1,10 do if UnitAura("player", i) then n = n + 1 end end return n"#
@@ -537,13 +404,11 @@ mod tests {
             .unwrap(),
             2
         );
-        // HARMFUL names the sign explicitly.
         assert_eq!(
             s.eval::<String>(r#"return (UnitAura("player", 1, "HARMFUL"))"#)
                 .unwrap(),
             "Pain"
         );
-        // CANCELABLE / NOT_CANCELABLE partition the helpful set.
         assert_eq!(
             s.eval::<String>(r#"return (UnitAura("player", 1, "HELPFUL|CANCELABLE"))"#)
                 .unwrap(),
@@ -554,7 +419,7 @@ mod tests {
                 .unwrap(),
             "Sealed"
         );
-        // A bare CANCELABLE still means helpful (the sign defaults, it isn't cleared).
+        // A bare CANCELABLE keeps the helpful default.
         assert_eq!(
             s.eval::<String>(r#"return (UnitAura("player", 1, "CANCELABLE"))"#)
                 .unwrap(),
@@ -586,11 +451,6 @@ mod tests {
         assert_eq!(spell, 589);
     }
 
-    /// The **1.12** shape, which is not a prefix of the Era one: `UnitBuff` → `(texture,
-    /// applications)`, `UnitDebuff` → `(texture, applications, dispelType)`, and the FIRST value is
-    /// the texture. Decision 1818; `0x519500`/`0x5198f0`, both `verified` in wow-re's ledger. The
-    /// reference's own FrameXML reads exactly this (`TargetFrame.lua:287-290`), and so does every
-    /// one of the 184 call sites in the addon corpus.
     #[test]
     fn unit_buff_and_unit_debuff_return_the_1121_tuple_not_the_era_one() {
         let mut s = UiScript::new().unwrap();
@@ -601,7 +461,6 @@ mod tests {
         debuff.debuff_type = Some("Magic".into());
         s.set_auras("target", Some(vec![buff, debuff]));
 
-        // UnitBuff returns exactly TWO values, texture first.
         let (icon, count, third) = s
             .eval::<(String, i64, Option<String>)>(
                 r#"local a, b, c = UnitBuff("target", 1) return a, b, c"#,
@@ -611,7 +470,6 @@ mod tests {
         assert_eq!(count, 1);
         assert_eq!(third, None, "UnitBuff returns two values, never a third");
 
-        // UnitDebuff returns THREE, the dispel type last.
         let (icon, count, dispel, fourth) = s
             .eval::<(String, i64, String, Option<String>)>(
                 r#"local a, b, c, d = UnitDebuff("target", 1) return a, b, c, d"#,
@@ -624,8 +482,7 @@ mod tests {
             "UnitDebuff returns three values, never a fourth"
         );
 
-        // The reference's own read, verbatim from TargetFrame.lua:287-297 — the comparison that
-        // raised `attempt to compare number with string` while we returned the Era tuple.
+        // Stock `TargetFrame.lua:287-297`'s read, verbatim.
         assert!(s
             .eval::<bool>(
                 r#"local d, stack, dtype = UnitDebuff("target", 1)
@@ -633,8 +490,7 @@ mod tests {
             )
             .unwrap());
 
-        // The raidFilter argument is ACCEPTED and its predicate is not applied (1818): passing it
-        // must not error, and must not change the answer.
+        // The raidFilter flag is accepted and not applied.
         assert_eq!(
             s.eval::<String>(r#"return (UnitDebuff("target", 1, 1))"#)
                 .unwrap(),
@@ -655,24 +511,17 @@ mod tests {
         );
         assert!(s.take_cancel_aura_requests().is_empty());
 
-        // A cancelable buff queues its SPELL id (not its index).
+        // Only the cancelable buff queues, by spell id; the others are silent no-ops.
         s.eval::<()>(r#"CancelUnitBuff("player", 1)"#).unwrap();
-        // A non-cancelable one is a silent no-op, as in the reference.
         s.eval::<()>(r#"CancelUnitBuff("player", 2)"#).unwrap();
-        // So is an out-of-range index, and a debuff reached through the helpful filter.
         s.eval::<()>(r#"CancelUnitBuff("player", 9)"#).unwrap();
         assert_eq!(s.take_cancel_aura_requests(), vec![2457]);
         assert!(s.take_cancel_aura_requests().is_empty());
     }
 
-    /// The tracking seam (the reference's `GetTrackingTexture`/`CancelTrackingBuff` pair over the
-    /// tracking global): the pushed state is what the bindings read, the cancel queues the SPELL
-    /// id behind the same `AFLAG_CANCELABLE` gate as `CancelUnitBuff`, and no tracking is nil +
-    /// no-op.
     #[test]
     fn tracking_bindings_read_the_pushed_state_and_cancel_by_spell_id() {
         let mut s = UiScript::new().unwrap();
-        // No tracking pushed yet: nil texture, cancel is a silent no-op.
         assert!(s
             .eval::<bool>("return GetTrackingTexture() == nil")
             .unwrap());
@@ -692,7 +541,6 @@ mod tests {
         s.eval::<()>("CancelTrackingBuff()").unwrap();
         assert_eq!(s.take_cancel_aura_requests(), vec![2580]);
 
-        // A non-cancelable tracking aura refuses, exactly like CancelUnitBuff's gate.
         s.set_tracking(Some(TrackingState {
             spell_id: 2580,
             cancelable: false,
@@ -701,7 +549,6 @@ mod tests {
         s.eval::<()>("CancelTrackingBuff()").unwrap();
         assert!(s.take_cancel_aura_requests().is_empty());
 
-        // Cleared: back to nil (the minimap frame's hide branch).
         s.set_tracking(None);
         assert!(s
             .eval::<bool>("return GetTrackingTexture() == nil")
diff --git a/crates/benilla-ui/src/script/aura/player_buff.rs b/crates/benilla-ui/src/script/aura/player_buff.rs
index 062a8f9e..d41eaa73 100644
--- a/crates/benilla-ui/src/script/aura/player_buff.rs
+++ b/crates/benilla-ui/src/script/aura/player_buff.rs
@@ -1,33 +1,20 @@
-//! **The 1.12 dialect** of the aura API — `GetPlayerBuff` and the five verbs that consume the cache
-//! position it hands back, plus `CancelPlayerBuff`.
-//!
-//! The index law, the byte-verified signature table, and the traps each shape hides are in the
-//! parent module's header ([`super`]); this file is the implementation. Everything here reads the
-//! *same* `model.auras["player"]` list the Era verbs read — the player's list **is** the reference's
-//! `0xbc6040` insertion-ordered cache — so a "cache position" needs no structure of its own.
-//!
-//! The one thing that is genuinely not shared with [`super`] is the **filter**: see
-//! [`PlayerBuffFilter`] for why reusing the Era parser would be a silent bug rather than a tidy-up.
+//! The 1.12 aura verbs: `GetPlayerBuff`, which returns a cache position, and the five that take
+//! one. A position is a 0-based index into the pushed `"player"` list, which is the reference's
+//! insertion-ordered cache (`0xbc6040`).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::{cancel_authorized, AuraState, Model};
 
-/// `GetPlayerBuff`'s filter, as a **bitmask** — deliberately *not* [`Filter`].
-///
-/// The two parsers are not the same function and sharing one would be the silent-shape bug this
-/// module's header is about. `UnitAura`'s filter defaults its *sign* to helpful and treats a bare
-/// `"CANCELABLE"` as `HELPFUL|CANCELABLE`; `GetPlayerBuff`'s mask starts at **zero** the moment a
-/// filter string is supplied (`xor esi,esi`, `0x4e4639`), so a bare `"CANCELABLE"` sets no sign bit
-/// and matches nothing at all. And with **no** filter argument the mask is `HELPFUL|HARMFUL`
-/// (`mov esi,0x3`, `0x4e4618`), where `UnitAura`'s default is helpful only.
+/// `GetPlayerBuff`'s filter mask, not `UnitAura`'s parser: no filter argument means
+/// `HELPFUL|HARMFUL` (`0x4e4618`), and a filter string starts the mask at zero (`0x4e4639`), so a
+/// bare `"CANCELABLE"` matches nothing.
 #[derive(Clone, Copy)]
 struct PlayerBuffFilter(u32);
 
 impl PlayerBuffFilter {
-    /// `stricmp` against the four `.rdata` tokens (`0x4e4661`-`0x4e46cf`). Anything else — including
-    /// `"PASSIVE"` — contributes no bit, exactly as the reference's `strtok`/`stricmp` chain falls
-    /// through. Delimiters are `" |"` (`0x84bc3c`): space or pipe, runs collapsed like `strtok`'s.
+    /// Case-insensitive match against the four tokens (`0x4e4661`-`0x4e46cf`); anything else,
+    /// `"PASSIVE"` included, sets no bit. Space and pipe both delimit, runs collapsed (`0x84bc3c`).
     fn parse(spec: Option<&str>) -> Self {
         const HELPFUL: u32 = 0x1;
         const HARMFUL: u32 = 0x2;
@@ -35,7 +22,6 @@ impl PlayerBuffFilter {
         const NOT_CANCELABLE: u32 = 0x20;
 
         let Some(spec) = spec else {
-            // No filter argument at all: the preloaded `HELPFUL|HARMFUL`, both halves.
             return Self(HELPFUL | HARMFUL);
         };
         let mut mask = 0;
@@ -54,8 +40,8 @@ impl PlayerBuffFilter {
         Self(mask)
     }
 
-    /// The enumerator's per-record test (`0x4e43c9`-`0x4e43f7`): the sign bit for this record's half
-    /// must be set, then `CANCELABLE`/`NOT_CANCELABLE` (if named) must agree with `record+0xa & 1`.
+    /// The enumerator's per-record test (`0x4e43c9`-`0x4e43f7`): the record's sign bit, then any
+    /// named `CANCELABLE`/`NOT_CANCELABLE` against `record+0xa & 1`.
     fn matches(self, a: &AuraState) -> bool {
         const HELPFUL: u32 = 0x1;
         const HARMFUL: u32 = 0x2;
@@ -69,47 +55,29 @@ impl PlayerBuffFilter {
     }
 }
 
-/// `lua_isnumber`-then-`lua_tonumber`-then-`__ftol`, with the reference's own usage message.
-///
-/// Every verb in the family opens with exactly this (`0x4e45d6`, `0x4e4748`, `0x4e4808`, `0x4e48bc`,
-/// `0x4e493e`, `0x4e49a8`): a non-number argument raises through `luaL_error` (`0x6f4940` =
-/// `luaL_where` + `lua_pushvfstring` + `lua_concat` + `lua_error`) rather than returning nil, so an
-/// addon sees the same "Usage:" line the reference prints. Lua 5.1's `lua_isnumber` accepts a numeric
-/// *string*, and [`Lua::coerce_number`] is that same coercion.
+/// The family's index argument, as every verb opens (`0x4e45d6`, `0x4e4748`, `0x4e4808`,
+/// `0x4e48bc`, `0x4e493e`, `0x4e49a8`): a number or numeric string, truncated; anything else raises
+/// the reference's usage line through `luaL_error` (`0x6f4940`).
 fn buff_index_arg(lua: &Lua, v: Value, usage: &'static str) -> mlua::Result<i64> {
     match lua.coerce_number(v)? {
-        // `__ftol` truncates toward zero; `as i64` on f64 does the same (and saturates).
+        // `__ftol` truncates toward zero, as `as i64` does.
         Some(n) => Ok(n as i64),
         None => Err(mlua::Error::RuntimeError(usage.into())),
     }
 }
 
-/// The player's display cache — the reference's `0xbc6040`, which for us **is** the pushed
-/// `"player"` list (decision 0257; `benilla::ui_aura` maintains the insertion order across frames).
-/// `pos` is a physical cache position, 0-based.
-///
-/// Out of range is `None`, covering both of the reference's miss shapes: `0x4e4430` hands back NULL
-/// for `pos < 0` and `pos >= 0x30`, and a position inside the array but past the packed prefix
-/// resolves to a **cleared** record (`slot = -1`, `spellId = 0`), which every sibling then treats as
-/// absent anyway — `GetPlayerBuffTexture` fails its `Spell.dbc` lookup on id 0 and pushes nil,
-/// `…TimeLeft` returns 0 on `slot < 0`, `CancelPlayerBuff` finds no spell and no-ops. (One reference
-/// quirk is deliberately *not* reproduced: `GetPlayerBuffApplications` on a cleared record reads
-/// `+0x9`, which `BuildBuffRecord` never rewrites when it clears — so the real client hands back the
-/// previous occupant's stack count. It is unreachable from any guarded call site, and stale memory is
-/// not a mechanism worth mirroring; we answer with the absent-record default, `1`.)
+/// The record at cache position `pos`, or `None` past the packed prefix, where the reference has
+/// NULL outside `0..0x30` (`0x4e4430`) and cleared records its siblings treat as absent. Deviation:
+/// `GetPlayerBuffApplications` answers 1 for a cleared record where the reference reads its stale
+/// `+0x9`, the previous occupant's count, because no guarded caller reaches it.
 fn player_buff_record(lua: &Lua, pos: i64) -> Option<AuraState> {
     let pos = usize::try_from(pos).ok()?;
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     model.auras.get("player")?.get(pos).cloned()
 }
 
-/// The enumerator, `0x4e43b0`: walk the cache by ascending physical position, counting only records
-/// that pass `filter`, and stop when that count reaches `index`. Returns the **position** and the
-/// record — the position is what every sibling verb consumes.
-///
-/// A negative `index` can never match: the reference's counter starts at 0 and only increments, and
-/// the hit test is an equality (`cmp ebx,[ebp-4]; je`), so it walks the whole cache and falls out
-/// with `*outPos` still at its pre-seeded `-1`.
+/// The enumerator (`0x4e43b0`): the `index`-th record passing `filter`, by ascending position,
+/// with that position. A negative `index` never matches the counter, which counts up from 0.
 fn enumerate_player_buff(
     lua: &Lua,
     index: i64,
@@ -129,19 +97,16 @@ fn enumerate_player_buff(
         .map(|(pos, a)| (pos, a.clone()))
 }
 
-/// Register the six 1.12 globals. Signatures are byte-verified — see [`super`]'s header table for
-/// the addresses and the corpus/FrameXML site that pins each shape.
+/// Register the six 1.12 globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetPlayerBuff(index [, "filter"]) — 0x4e45d0. ALWAYS two numbers: the physical cache position
-    // (-1 past the end) and untilCancelled (0/1). Never nil, never a different arity: both the hit
-    // path (0x4e471e) and the miss path (0x4e4733) end `mov eax,0x2`.
-    //
-    // With the default HELPFUL|HARMFUL mask every live record passes the sign test, so the match
-    // counter advances in lockstep with the position and `GetPlayerBuff(i)` returns exactly `i` over
-    // the packed prefix — which `_LazyPig/LazyPig.lua:1174-1181` relies on, enumerating with
-    // `counter` and then cancelling `counter` rather than the returned index.
+    // GetPlayerBuff(index [, "filter"]) (`0x4e45d0`) returns two numbers on both paths
+    // (`0x4e471e`, `0x4e4733`): the position, -1 past the end and never nil, as addons loop while
+    // it is `>= 0`; and untilCancelled as the number 0 or 1, which stock `BuffFrame.lua:124`
+    // compares with `1`. The index is 0-based, used without `UnitBuff`'s `dec` (`0x4e460a`,
+    // `0x519579`). Unfiltered, every record passes, so `GetPlayerBuff(i)` is `i`, which addons use
+    // to cancel by the counter.
     g.set(
         "GetPlayerBuff",
         lua.create_function(|lua, (index, filter): (Value, Option<String>)| {
@@ -158,14 +123,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerBuffTexture(buffIndex) — 0x4e4740. One value: the icon path, or nil when the position
-    // is absent or the spell/icon row is missing (three separate `lua_pushnil; mov eax,0x1` exits).
-    // Nil is load-bearing: `SnaFu/SnaFu.lua:317` uses this call *as its loop condition*
-    // (`while GetPlayerBuffTexture(i) do`), so an empty string past the end would spin forever.
-    //
-    // The extra argument `CT_BuffMod/CT_BuffFrame.lua:148` passes
-    // (`GetPlayerBuffTexture(buffIndex, "HELPFUL|HARMFUL")`) is simply ignored — the reference reads
-    // argument 1 and nothing else, and mlua drops the surplus for the same reason.
+    // GetPlayerBuffTexture(buffIndex) (`0x4e4740`): the icon path, or nil for an absent position or
+    // a missing spell or icon row; addons loop until the nil. A surplus argument is ignored, as the
+    // reference reads only the first.
     g.set(
         "GetPlayerBuffTexture",
         lua.create_function(|lua, index: Value| {
@@ -174,17 +134,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerBuffDispelType(buffIndex) — 0x4e4800. One value: SpellDispelType.dbc's name for the
-    // spell's `Dispel` column, or nil (dispel id 0, or any missing row — gated at 0x4e485e before
-    // the DBC is touched). The vocabulary is the DBC's, shared with `UnitDebuff`'s third return.
-    //
-    // Nil, never `""` and never `"none"`: the corpus indexes `DebuffTypeColor[debuffType]` behind an
-    // `if ( debuffType )` and falls back to the `"none"` key itself
-    // (`ElkBuffBar/ElkBuffBar.lua:324-329`, `CT_BuffMod/CT_BuffFrame.lua:137-142`). An empty string
-    // is truthy in Lua, so it would take the wrong branch and then index a nil colour.
-    //
-    // It must also tolerate `-1` directly: `ref-BuffFrame.lua:83` calls
-    // `GetPlayerBuffDispelType(GetPlayerBuff(this:GetID(), "HARMFUL"))` with no guard between them.
+    // GetPlayerBuffDispelType(buffIndex) (`0x4e4800`): the `SpellDispelType.dbc` name of the
+    // spell's `Dispel`, or nil for dispel 0 or a missing row (`0x4e485e`); never `""`, which Lua
+    // takes as true. Stock `BuffFrame.lua:83` passes it `GetPlayerBuff`'s result unguarded, -1 too.
     g.set(
         "GetPlayerBuffDispelType",
         lua.create_function(|lua, index: Value| {
@@ -193,15 +145,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerBuffApplications(buffIndex) — 0x4e48b0. One value, always a number: the record's
-    // stack count, and **1** for an absent position (`push 0x3ff00000; push 0x0` = the double 1.0,
-    // 0x4e4917). Never nil — `CT_BuffMod/CT_BuffFrame.lua:216` and `ElkBuffBar/ElkBuffBar.lua:278`
-    // both do `if ( count > 1 )` with no guard, which nil turns into a hard error.
-    //
-    // (The reference's usage string here is `0x84bcc0`, "Usage: GetPlayerBuffTimeLeft(buffIndex)" —
-    // the same constant 0x4e4930 pushes. A copy-paste in the shipped binary; we name the verb the
-    // caller actually called, since nothing can depend on the wrong name and a debugging addon
-    // author would be misled by it.)
+    // GetPlayerBuffApplications(buffIndex) (`0x4e48b0`): the stack count, and 1 for an absent
+    // position (`0x4e4917`), never nil, as addons test `count > 1` unguarded. Deviation: the
+    // reference's usage line names `GetPlayerBuffTimeLeft` (`0x84bcc0`, shared with `0x4e4930`);
+    // ours names this verb, because nothing can depend on the wrong name.
     g.set(
         "GetPlayerBuffApplications",
         lua.create_function(|lua, index: Value| {
@@ -210,36 +157,23 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerBuffTimeLeft(buffIndex) — 0x4e4930 over the reader 0x4e4450. One value, always a
-    // number in **seconds** (the reader returns ms and 0x4e4986 multiplies by the 0.001 at
-    // 0x801608): `max(0, expiry - now)`, and **0** for an absent position, a cleared record, or an
-    // aura with no expiry at all.
-    //
-    // Never nil: `oRA2/Participant/Buff.lua:286` computes `floor(GetPlayerBuffTimeLeft(index) + .5)`
-    // with no guard whatsoever, and `PowerAuras/PowerAuras.lua:593` feeds the result of a *possibly
-    // -1* `GetPlayerBuff` straight in and then compares `> 0`.
-    //
-    // The clock is the VM's own `GetTime()` session clock, the same one `expiration_time` is
-    // expressed on (decision 0257) — so this is a live subtraction per call, exactly as
-    // `ref-BuffFrame.lua:130` re-reads it every frame from `OnUpdate` rather than caching it on the
-    // event.
+    // GetPlayerBuffTimeLeft(buffIndex) (`0x4e4930`, reader `0x4e4450`): seconds, the reader's ms
+    // times the 0.001 at `0x801608` (`0x4e4986`), as `max(0, expiry - now)`, and 0 for an absent,
+    // cleared or permanent aura, never nil, as addons do arithmetic on it unguarded. It is computed
+    // per call against `GetTime()`, as stock `BuffFrame.lua:130` re-reads it every frame.
     g.set(
         "GetPlayerBuffTimeLeft",
         lua.create_function(|lua, index: Value| {
             let pos = buff_index_arg(lua, index, "Usage: GetPlayerBuffTimeLeft(buffIndex)")?;
             let now: f64 = lua.globals().get("__benilla_now").unwrap_or(0.0);
-            // The `max(0, …)` covers both of the reference's zero cases at once: an expired aura,
-            // and a permanent one, whose expiry array slot holds 0 so that `now - 0` is positive.
+            // `max(0, …)` covers both zero cases: an expired aura, and a permanent one, expiry 0.
             Ok(player_buff_record(lua, pos).map_or(0.0, |a| (a.expiration_time - now).max(0.0)))
         })?,
     )?;
 
-    // CancelPlayerBuff(buffIndex) — 0x4e49a0. **Zero** return values on every path, including the
-    // successful one (`xor eax,eax; ret`). Resolves the position to a record, applies
-    // [`cancel_authorized`], and queues the SPELL id onto the same drain `CancelUnitBuff` uses —
-    // there is one queue because there is one packet: `Spell_C::CancelAura 0x6e7040` sends
-    // `CMSG_CANCEL_AURA` (0x136) with a single u32 spell id (decision 0257 B8). A refused or absent
-    // aura is a silent no-op, as in the reference.
+    // CancelPlayerBuff(buffIndex) (`0x4e49a0`): no return values on any path. It queues the spell
+    // id, the one `u32` of `CMSG_CANCEL_AURA` (0x136, `Spell_C::CancelAura` `0x6e7040`), on the
+    // queue `CancelUnitBuff` uses; a refused or absent aura is a silent no-op.
     g.set(
         "CancelPlayerBuff",
         lua.create_function(|lua, index: Value| {
@@ -259,8 +193,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::{AuraState, UiScript};
 
-    /// A plain aura as the app's feed would push it. Local to this module's fixtures: the 1.12
-    /// verbs read fields (`until_cancelled`, `channeled`) the Era tests have no use for.
     fn aura(spell_id: u32, name: &str, helpful: bool, cancelable: bool) -> AuraState {
         AuraState {
             spell_id,
@@ -277,14 +209,13 @@ mod tests {
         }
     }
 
-    /// The player's cache as the app pushes it: buffs and debuffs in ONE insertion-ordered list,
-    /// which is what makes a cache position an absolute handle across filters.
+    /// The player's cache as the app pushes it: buffs and debuffs in one insertion-ordered list.
     fn player_cache() -> Vec<AuraState> {
         let mut mark = aura(1126, "Mark of the Wild", true, true);
         mark.count = 1;
         mark.expiration_time = 100.0;
         let mut stance = aura(2457, "Battle Stance", true, false);
-        stance.until_cancelled = true; // permanent: no SpellDuration row to count down
+        stance.until_cancelled = true; // permanent
         let mut pain = aura(589, "Shadow Word: Pain", false, false);
         pain.count = 3;
         pain.debuff_type = Some("Magic".into());
@@ -299,14 +230,7 @@ mod tests {
         s
     }
 
-    /// **The sentinel, and the arity that carries it.** `GetPlayerBuff` returns two numbers on every
-    /// path — `(-1, 0)` past the end, never nil and never a different count.
-    ///
-    /// The arity assertions are the half that matters, exactly as in
-    /// [`super::super::item_stats`]'s `get_item_info_tests`: an implementation that returned `nil`
-    /// for a miss still "works" for every individual read, and only the arity notices. Here it is
-    /// worse than cosmetic — the corpus's termination test is `>= 0` on the *first* value, so nil is
-    /// `attempt to compare nil with number` and zero returns is the same crash.
+    /// The arity is the point: a nil miss passes each single read but breaks every `>= 0` loop.
     #[test]
     fn get_player_buff_returns_two_numbers_and_minus_one_past_the_end() {
         let mut s = with_player_cache();
@@ -323,12 +247,11 @@ mod tests {
             "and a MISS pushes two as well (0x4e4733), not zero and not nil"
         );
 
-        // 0-based: position 0 is the first aura, not the second.
+        // 0-based: position 0 is the first aura.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetPlayerBuff(0)").unwrap(),
             (0, 0)
         );
-        // Past the end: the -1 sentinel, and untilCancelled 0 beside it.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetPlayerBuff(3)").unwrap(),
             (-1, 0)
@@ -337,20 +260,17 @@ mod tests {
             s.eval::<(i64, i64)>("return GetPlayerBuff(99)").unwrap(),
             (-1, 0)
         );
-        // A negative index can never match the counter, so it is a miss, not an error.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetPlayerBuff(-1)").unwrap(),
             (-1, 0)
         );
-        // untilCancelled is the NUMBER 1 — five corpus sites compare it to `1`, so a boolean
-        // (`true ~= 1`) would silently invert every one of them.
+        // untilCancelled is the number 1, not `true`: callers compare it with `1`.
         assert!(s
             .eval::<bool>("local _, uc = GetPlayerBuff(1) return uc == 1")
             .unwrap());
         assert!(s
             .eval::<bool>("local _, uc = GetPlayerBuff(0) return uc == 0")
             .unwrap());
-        // An empty cache is the same miss shape as an over-long index (not an error, not nil).
         s.set_auras("player", None);
         assert_eq!(
             s.eval::<(i64, i64)>("return GetPlayerBuff(0)").unwrap(),
@@ -358,15 +278,8 @@ mod tests {
         );
     }
 
-    /// **The corpus's own loop.** `while GetPlayerBuff(counter) >= 0 do … end` over a real cache
-    /// must visit every aura once and then *stop* — `_LazyPig/LazyPig.lua:1174`,
-    /// `Zorlen/Zorlen.lua:2797`. Not terminating is the failure mode that matters: it is an infinite
-    /// loop inside a `PLAYER_AURAS_CHANGED` handler, i.e. a frozen client, and no gate but this one
-    /// would see it.
-    ///
-    /// The loop also pins LazyPig's assumption that `counter` and the returned index are
-    /// interchangeable under the default filter, and that the walk covers **debuffs too** (the
-    /// `HELPFUL|HARMFUL` default).
+    /// The corpus's loop (`_LazyPig/LazyPig.lua:1174`) visits every aura, debuffs included, and
+    /// ends: a hang there freezes the client inside a `PLAYER_AURAS_CHANGED` handler.
     #[test]
     fn the_corpus_while_ge_zero_loop_terminates_and_visits_every_aura() {
         let mut s = with_player_cache();
@@ -397,7 +310,6 @@ mod tests {
             "Interface\\Icons\\Spell_1126;Interface\\Icons\\Spell_2457;Interface\\Icons\\Spell_589;"
         );
 
-        // The same loop over an EMPTY cache terminates immediately rather than spinning.
         s.set_auras("player", Some(vec![]));
         assert_eq!(
             s.eval::<i64>(
@@ -410,32 +322,23 @@ mod tests {
         );
     }
 
-    /// **The default filter is `HELPFUL|HARMFUL`.** The trap that fails silently: under a `HELPFUL`
-    /// default (which is what `UnitAura` uses, one function away in this file)
-    /// `Zorlen/Zorlen.lua:2797-2801` — an unfiltered walk feeding `GetPlayerBuffDispelType` and
-    /// matching `"Poison"`/`"Disease"` — simply never finds anything, and nothing errors.
-    ///
-    /// Also pins the absolute index space: a `"HARMFUL"` enumeration hands back the same position an
-    /// unfiltered one does, which `CT_BuffMod/CT_BuffFrame.lua:73-79` compares for equality across
-    /// the two filters.
+    /// Under a `HELPFUL` default an unfiltered walk for `"Poison"` would find nothing, silently;
+    /// and a position is the same number under every filter, which callers compare.
     #[test]
     fn get_player_buff_defaults_to_both_halves_and_indexes_absolutely() {
         let s = with_player_cache();
 
-        // No filter: three matches — the debuff included.
         assert_eq!(
             s.eval::<i64>("local n = 0 while GetPlayerBuff(n) >= 0 do n = n + 1 end return n")
                 .unwrap(),
             3
         );
-        // The debuff is reachable unfiltered, and its dispel class comes back.
         assert_eq!(
             s.eval::<String>("return GetPlayerBuffDispelType(GetPlayerBuff(2))")
                 .unwrap(),
             "Magic"
         );
-        // "HARMFUL" alone finds it at ordinal 0 — and hands back position 2, the SAME number the
-        // unfiltered walk used.
+        // "HARMFUL" finds the debuff at ordinal 0 and returns position 2, the unfiltered number.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(0, "HARMFUL"))"#)
                 .unwrap(),
@@ -446,7 +349,6 @@ mod tests {
                 .unwrap(),
             -1
         );
-        // "HELPFUL" alone: two, at positions 0 and 1.
         assert_eq!(
             s.eval::<(i64, i64)>(
                 r#"return (GetPlayerBuff(0, "HELPFUL")), (GetPlayerBuff(1, "HELPFUL"))"#
@@ -454,7 +356,7 @@ mod tests {
             .unwrap(),
             (0, 1)
         );
-        // CT_BuffMod's own literal, and the space-delimited spelling the reference's strtok accepts.
+        // Pipe- and space-delimited.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(2, "HELPFUL|HARMFUL"))"#)
                 .unwrap(),
@@ -465,20 +367,18 @@ mod tests {
                 .unwrap(),
             2
         );
-        // The zero-mask rule: a filter STRING with no sign token matches nothing at all, because the
-        // mask starts at 0 (`xor esi,esi`) rather than defaulting the sign the way UnitAura's does.
+        // A filter string with no sign token matches nothing: the mask starts at 0.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(0, "CANCELABLE"))"#)
                 .unwrap(),
             -1
         );
-        // "PASSIVE" is not a token in this parser: it contributes no bit, so it is a zero mask too.
+        // "PASSIVE" is not a token.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(0, "PASSIVE"))"#)
                 .unwrap(),
             -1
         );
-        // CANCELABLE / NOT_CANCELABLE partition a named sign.
         assert_eq!(
             s.eval::<i64>(r#"return (GetPlayerBuff(0, "HELPFUL|CANCELABLE"))"#)
                 .unwrap(),
@@ -491,14 +391,12 @@ mod tests {
         );
     }
 
-    /// **The accessors' empty-slot answers**, each of which is a different shape, and each of which
-    /// a corpus site would crash on if it were nil.
     #[test]
     fn the_player_buff_accessors_answer_an_absent_position_without_nil_arithmetic() {
         let mut s = with_player_cache();
-        s.tick(0.0); // GetTime() = 0, the clock GetPlayerBuffTimeLeft counts against
+        s.tick(0.0); // GetTime() = 0
 
-        // Every accessor returns exactly ONE value, hit or miss — the reference's `mov eax,0x1`.
+        // One value, hit or miss.
         for verb in [
             "GetPlayerBuffTexture",
             "GetPlayerBuffDispelType",
@@ -513,13 +411,12 @@ mod tests {
                 );
             }
         }
-        // CancelPlayerBuff pushes NONE (`xor eax,eax; ret`), on every path.
         for arg in ["0", "-1", "99"] {
             assert_eq!(s.arity(&format!("CancelPlayerBuff({arg})")).unwrap(), 0);
         }
         s.take_cancel_aura_requests();
 
-        // Texture: nil past the end — SnaFu's `while GetPlayerBuffTexture(i) do` loop condition.
+        // Texture: nil past the end, a loop condition in the corpus.
         assert!(s
             .eval::<bool>("return GetPlayerBuffTexture(3) == nil")
             .unwrap());
@@ -536,21 +433,18 @@ mod tests {
             3
         );
 
-        // DispelType: nil, never "" and never "none" — the corpus branches on truthiness and then
-        // indexes DebuffTypeColor with the value, so "" would take the wrong branch.
+        // DispelType: nil, never "".
         assert!(s
             .eval::<bool>("return GetPlayerBuffDispelType(0) == nil")
             .unwrap());
         assert!(s
             .eval::<bool>("return GetPlayerBuffDispelType(99) == nil")
             .unwrap());
-        // ref-BuffFrame.lua:83 nests the calls with no guard, so -1 must pass straight through.
+        // Stock BuffFrame.lua:83 nests the calls unguarded.
         assert!(s
             .eval::<bool>(r#"return GetPlayerBuffDispelType(GetPlayerBuff(9, "HARMFUL")) == nil"#)
             .unwrap());
 
-        // Applications: a NUMBER always, and 1 (not 0, not nil) for an absent position — the
-        // reference's `push 0x3ff00000`. `count > 1` is unguarded in CT_BuffMod and ElkBuffBar.
         assert_eq!(
             s.eval::<i64>("return GetPlayerBuffApplications(2)")
                 .unwrap(),
@@ -570,8 +464,6 @@ mod tests {
             .eval::<bool>("return GetPlayerBuffApplications(-1) > 1 == false")
             .unwrap());
 
-        // TimeLeft: a NUMBER always, in seconds, 0 for absent/permanent — oRA2 does
-        // `floor(GetPlayerBuffTimeLeft(index) + .5)` with no guard at all.
         assert_eq!(
             s.eval::<f64>("return GetPlayerBuffTimeLeft(2)").unwrap(),
             18.0
@@ -589,7 +481,7 @@ mod tests {
             s.eval::<f64>("return GetPlayerBuffTimeLeft(-1)").unwrap(),
             0.0
         );
-        // The unguarded corpus arithmetic, run for real.
+        // The corpus's unguarded arithmetic.
         assert_eq!(
             s.eval::<f64>("return math.floor(GetPlayerBuffTimeLeft(-1) + .5)")
                 .unwrap(),
@@ -601,28 +493,26 @@ mod tests {
             0.0
         );
 
-        // It counts down against the VM's GetTime clock, live, per call.
+        // It counts down against GetTime, per call, and floors at 0.
         s.tick(5.0);
         assert_eq!(
             s.eval::<f64>("return GetPlayerBuffTimeLeft(2)").unwrap(),
             13.0
         );
-        // And floors at 0 rather than going negative once the aura is past its expiry.
         s.tick(20.0);
         assert_eq!(
             s.eval::<f64>("return GetPlayerBuffTimeLeft(2)").unwrap(),
             0.0
         );
 
-        // A surplus argument is ignored, not an error — CT_BuffMod/CT_BuffFrame.lua:148 passes a
-        // filter string to GetPlayerBuffTexture, which takes none.
+        // A surplus argument is ignored.
         assert_eq!(
             s.eval::<String>(r#"return GetPlayerBuffTexture(0, "HELPFUL|HARMFUL")"#)
                 .unwrap(),
             "Interface\\Icons\\Spell_1126"
         );
 
-        // A non-number argument raises with the reference's own usage line, rather than answering.
+        // A non-number argument raises the reference's usage line.
         let err = s
             .eval::<()>("GetPlayerBuff({})")
             .expect_err("a table index must raise");
@@ -632,34 +522,27 @@ mod tests {
         );
     }
 
-    /// `CancelPlayerBuff` is `CancelUnitBuff` under its 1.12 name: the same gate, the same queue,
-    /// the same `CMSG_CANCEL_AURA` spell id — never a second mechanism. It differs only in how the
-    /// aura is addressed (a cache position, not a token plus a filtered ordinal).
     #[test]
     fn cancel_player_buff_shares_the_gate_and_the_queue_with_cancel_unit_buff() {
         let mut s = with_player_cache();
         assert!(s.take_cancel_aura_requests().is_empty());
 
-        // Position 0 is a cancelable buff: its SPELL id is queued, not its index.
+        // Position 0 is cancelable: its spell id queues.
         s.eval::<()>("CancelPlayerBuff(0)").unwrap();
         assert_eq!(s.take_cancel_aura_requests(), vec![1126]);
 
-        // Position 1 is a buff without AFLAG_CANCELABLE, position 2 a plain debuff, and 99/-1 are
-        // absent — all silent no-ops, exactly as the reference's gate falls through.
+        // Not cancelable, a plain debuff, absent: all silent no-ops.
         for arg in ["1", "2", "99", "-1"] {
             s.eval::<()>(&format!("CancelPlayerBuff({arg})")).unwrap();
         }
         assert!(s.take_cancel_aura_requests().is_empty());
 
-        // Both names reach the same queue for the same aura: CancelUnitBuff addresses it as the
-        // 1st helpful aura of "player", CancelPlayerBuff as cache position 0.
+        // Both names reach one queue: the first helpful aura is cache position 0.
         s.eval::<()>(r#"CancelUnitBuff("player", 1)"#).unwrap();
         s.eval::<()>("CancelPlayerBuff(0)").unwrap();
         assert_eq!(s.take_cancel_aura_requests(), vec![1126, 1126]);
 
-        // The channeled arm — the only way a NEGATIVE aura is cancelable (DBC AttributesEx & 0x4,
-        // 0x4e4a10). Without it the debuff below is refused, which is the shape CancelUnitBuff
-        // shipped with.
+        // The channeled arm (`AttributesEx & 0x4`, `0x4e4a10`) cancels a negative aura.
         let mut channeled = aura(689, "Drain Life", false, false);
         channeled.channeled = true;
         s.set_auras("player", Some(vec![channeled]));
diff --git a/crates/benilla-ui/src/script/backdrop.rs b/crates/benilla-ui/src/script/backdrop.rs
index 8bd8b69b..41c94743 100644
--- a/crates/benilla-ui/src/script/backdrop.rs
+++ b/crates/benilla-ui/src/script/backdrop.rs
@@ -1,21 +1,13 @@
-//! The frame `Backdrop` mechanism — byte-faithful to `wow-5875-re`'s
-//! `system/ui/scratch/backdrop-mechanism.md` (the RE derivation; every constant below cites its
-//! section). A backdrop is the tiled bg + 8-piece border a `<Backdrop>` element or Lua `SetBackdrop`
-//! installs on a frame (the tooltip/dialog/panel plate). This module owns the **data** ([`Backdrop`])
-//! and the **geometry** ([`pieces`]); the Lua verbs live in [`super::object`] and the XML parse in
-//! [`crate::loader`]. The renderer is the app's job — [`pieces`] hands it screen-space quads with
-//! explicit per-corner UVs.
+//! The frame backdrop as the 1.12 client builds it: the tiled background and 8-piece border that a
+//! `<Backdrop>` element or `SetBackdrop` installs. This module owns the data ([`Backdrop`]) and the
+//! geometry ([`pieces`], screen-space quads with per-corner UVs); the app renders them.
 
 use crate::layout::Rect;
 
-/// The default `edgeSize`, **logical** px: the ctor writes device `DAT_0081c9b0 = 0.025`, which is
-/// logical 32 through the ×1/1024·0.8 logical→device transform (spec §Backdrop-object, `+0x48`, and
-/// the usage string `edgeSize = 32`). Our layout is already in logical px, so we carry 32 directly.
+/// The default `edgeSize`, logical 32: the constructor writes device 0.025 (`DAT_0081c9b0`).
 pub const DEFAULT_EDGE_SIZE: f32 = 32.0;
 
-/// The `BackgroundInsets` — the bg texture is the frame rect inset by these (the border is *not*
-/// inset; it sits flush inside the frame rect). Default all 0 (spec §1). Field order matches the
-/// struct offsets `+0x50 top / +0x54 bottom / +0x58 left / +0x5c right`.
+/// `BackgroundInsets`: the background's inset from the frame rect; the border is never inset.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct Insets {
     pub left: f32,
@@ -24,35 +16,32 @@ pub struct Insets {
     pub bottom: f32,
 }
 
-/// A frame's installed backdrop (spec §Backdrop-object: the 0x68-byte struct at `frame+0x1ac`). The
-/// field set is *exactly* what the compiled reader accepts — `bgFile, edgeFile, tile, tileSize,
-/// edgeSize, insets` — plus the two colors (spec §1 "Field-set summary"). Colors default to opaque
-/// **white** (the ctor `+0x60/+0x64 = 0xffffffff`); the XML `<Color>`/`<BorderColor>` *parser*
-/// separately defaults a *present-but-partial* element to black, which the loader applies.
+/// A frame's installed backdrop (the 0x68-byte struct at `frame+0x1ac`): exactly the keys the
+/// reader accepts (`0x7776e0`) plus the two colours. The colours default to opaque white; the XML
+/// parser defaults a present but partial `<Color>` or `<BorderColor>` to black.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Backdrop {
-    /// The tiled background texture (`+0x24`); `None`/empty ⇒ no bg piece.
+    /// The background texture (`+0x24`); none or empty draws no background.
     pub bg_file: Option<String>,
-    /// The 8-slice border texture (`+0x30`); `None`/empty ⇒ no border pieces.
+    /// The 8-slice border texture (`+0x30`); none or empty draws no border.
     pub edge_file: Option<String>,
-    /// `tile` (`+0x40`): tile the bg (else stretch it). Default false.
+    /// Tile the background, else stretch it (`+0x40`).
     pub tile: bool,
-    /// `tileSize` (`+0x4c`), logical px; `0.0` ⇒ use `edge_size` as the tile period (spec §3). Default 0.
+    /// `tileSize` in logical px (`+0x4c`); 0 tiles at `edge_size` (`0x77f0c0`).
     pub tile_size: f32,
-    /// `edgeSize` (`+0x48`), logical px — the border piece size and the edge tiling period. Default 32.
+    /// `edgeSize` in logical px (`+0x48`): the border piece size and the edge tiling period.
     pub edge_size: f32,
-    /// `BackgroundInsets` (`+0x50..0x5c`). Default 0.
+    /// `BackgroundInsets` (`+0x50..0x5c`).
     pub insets: Insets,
-    /// bg vertex color (`+0x60`, `SetBackdropColor`). Default opaque white.
+    /// The background's vertex colour (`+0x60`, `SetBackdropColor`).
     pub bg_color: [f32; 4],
-    /// border vertex color (`+0x64`, `SetBackdropBorderColor`; all 8 pieces, never the bg). Default white.
+    /// All 8 border pieces' vertex colour (`+0x64`, `SetBackdropBorderColor`).
     pub border_color: [f32; 4],
 }
 
 impl Default for Backdrop {
     fn default() -> Self {
-        // The ctor (spec §Backdrop-object, 0x77e5f0): files empty, tile 0, tileSize 0,
-        // edgeSize logical 32, insets 0, both colors 0xffffffff.
+        // The constructor (`0x77e5f0`).
         Self {
             bg_file: None,
             edge_file: None,
@@ -75,59 +64,39 @@ impl Backdrop {
     }
 }
 
-/// One drawable backdrop piece (the bg, or one of the 8 border pieces). Carries four explicit corner
-/// **positions** (not a rect) so the shipped BR-inset bug's slant is representable, plus four explicit
-/// per-corner **UVs** (the TOP/BOTTOM edges are rotated 90°, spec §3). Both arrays are in
-/// `[top-left, top-right, bottom-right, bottom-left]` screen order (y-up, the layout convention).
+/// One drawable piece, the background or one of the 8 border pieces: explicit corners, not a rect,
+/// so the bottom-right inset quirk can slant it, and per-corner UVs, since the top and bottom edges
+/// are rotated 90° (`0x77f0c0`). Both arrays run `[TL, TR, BR, BL]`, y-up.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct BackdropPiece {
-    /// Corner positions in screen px, y-up: `[TL, TR, BR, BL]`.
+    /// Corner positions in screen px.
     pub corners: [[f32; 2]; 4],
-    /// Corner UVs (texture space), same `[TL, TR, BR, BL]` order.
+    /// Corner UVs in texture space.
     pub uvs: [[f32; 2]; 4],
-    /// The texture needs REPEAT (wrap) addressing — the edge strips run UVs `[0..N]` and a tiled bg
-    /// `[0..w/period]`. The corners' UVs stay in `[0,1]` but share the edge texture, so they carry
-    /// `true` too (one texture identity ⇒ the 9 pieces batch, spec §2's shared edge texture).
+    /// The texture needs repeat addressing. The corners stay in `[0,1]` but share the edge texture,
+    /// so they carry `true` too and the border batches as one texture (`0x77e8d0`).
     pub tile: bool,
-    /// The bg piece (`true`) draws with [`Backdrop::bg_file`]/`bg_color`; a border piece (`false`)
-    /// with `edge_file`/`border_color`. The app resolves the path + tint from the [`Backdrop`].
+    /// Drawn with `bg_file` and `bg_color`, else with `edge_file` and `border_color`.
     pub is_bg: bool,
 }
 
 const SLICE: f32 = 0.125;
 
-/// Pull a piece's UV rect half a texel inward on every axis whose range is **bounded** — i.e. does
-/// not tile — so bilinear magnification cannot reach across an atlas slice boundary.
-///
-/// The 8 border pieces live side by side in ONE texture, each occupying a [`SLICE`] of `u`, and the
-/// sampler is Linear+Repeat. A quad whose `u` ends exactly on a slice boundary samples, at its own
-/// edge, precisely the seam between two texels — so bilinear returns a 50/50 blend of this slice's
-/// last column and the **neighbouring piece's first**. Half a texel of inset moves that edge sample
-/// onto the texel's centre instead, which is the whole fix.
-///
-/// It is invisible at the reference's own 1024×768, where the 32-texel slice draws into a 16 px
-/// border and the bleed is subpixel. We draw the same slice into ~40 device px at 1440p — a 1.25×
-/// **magnification**, which gives the boundary texel a visible band of its own. In this atlas
-/// (`ChatBubble-Backdrop`, 256×32) the column next to the TOP slice is `(255,251,255)` at alpha 0,
-/// so what leaked in was **white**: the pale horizontal line the director reported through the
-/// speech bubble (1402), with a fainter twin under it from the BOTTOM slice's own boundary.
-///
-/// The bounded-axis test is what keeps this from breaking the tiling it sits next to: `u` always
-/// spans one slice and is always inset, while an edge strip's `v` runs `[0, run]` and only gets the
-/// inset when `run ≤ 1`. A strip that genuinely repeats keeps its exact period — insetting a tiling
-/// axis would make every period land a fraction short and walk the art along the run.
+/// Pull a piece's UVs half a texel inward on every axis that does not tile, so bilinear
+/// magnification cannot sample the neighbouring slice of the shared border atlas (in
+/// `ChatBubble-Backdrop`, a white alpha-0 column: a pale line through the speech bubble). A tiling
+/// axis, a strip's `v` past 1, is left exact, or each period would land short and walk the art.
 #[must_use]
 pub fn inset_atlas_bleed(uvs: [[f32; 2]; 4], tex_w: f32, tex_h: f32) -> [[f32; 2]; 4] {
     let mut out = uvs;
     for (axis, tex) in [(0usize, tex_w), (1usize, tex_h)] {
         if tex < 2.0 {
-            continue; // a 1-texel axis has no interior to inset toward
+            continue; // a 1-texel axis has no interior
         }
         let (lo, hi) = uvs.iter().fold((f32::MAX, f32::MIN), |(lo, hi), c| {
             (lo.min(c[axis]), hi.max(c[axis]))
         });
-        // A tiling axis is left exactly alone (see above); `1.0` is one whole period, which is
-        // bounded and does get the inset — that is the corner pieces, whose `v` is `[0,1]`.
+        // A range of exactly 1, the corners' `v`, is bounded and gets the inset.
         if hi - lo > 1.0 + f32::EPSILON {
             continue;
         }
@@ -142,8 +111,7 @@ pub fn inset_atlas_bleed(uvs: [[f32; 2]; 4], tex_w: f32, tex_h: f32) -> [[f32; 2
     out
 }
 
-/// Axis-aligned corners `[TL, TR, BR, BL]` (y-up) for a piece spanning `x∈[x0,x1]`, `y∈[y0,y1]`
-/// (`y1` = top). The bg overrides its own corners to reproduce the BR-inset bug.
+/// Axis-aligned corners `[TL, TR, BR, BL]`, y-up.
 fn aa_corners(x0: f32, x1: f32, y_bottom: f32, y_top: f32) -> [[f32; 2]; 4] {
     [
         [x0, y_top],    // TL
@@ -153,15 +121,14 @@ fn aa_corners(x0: f32, x1: f32, y_bottom: f32, y_top: f32) -> [[f32; 2]; 4] {
     ]
 }
 
-/// Compute the backdrop's drawable pieces for a frame whose resolved rect is `frame` (y-up), in the
-/// client's paint order: the bg (layer BACKGROUND) first, then the 8 border pieces (layer BORDER) —
-/// spec §2. Empty when neither file is set. All geometry is spec §2; all UVs spec §3.
+/// The drawable pieces for a frame's resolved rect (y-up), in paint order: the background (layer
+/// `BACKGROUND`), then the 8 border pieces (layer `BORDER`). Geometry `0x77e8d0`, UVs `0x77f0c0`.
 pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
     let mut out = Vec::with_capacity(9);
     let e = bd.edge_size;
     let (l, r, b, t) = (frame.left, frame.right, frame.bottom, frame.top);
 
-    // ── The background piece (spec §2 bg row) ──────────────────────────────────────────────────
+    // ── The background piece ──
     if bd.has_bg() {
         let (il, ir, it, ib) = (
             bd.insets.left,
@@ -169,18 +136,15 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
             bd.insets.top,
             bd.insets.bottom,
         );
-        // The four SetPoint anchors, y-up (spec §2 bg row). **⚠ BR uses the TOP inset**, not bottom
-        // — the shipped 1.12.1 bug (spec §2 "The BR-inset quirk", bytes `8b 46 50` @ 0x77e9ae:
-        // `SetPoint(8, frame+0x24, 8, −right, +top, 0)` loads `+0x50` = top, not `+0x54` = bottom).
-        // Invisible whenever top==bottom (every shipping backdrop); reproduced for fidelity.
+        // The four anchors, y-up. Bottom-right takes the top inset, as the reference does
+        // (`0x77e9ae` loads `+0x50`, top, not `+0x54`); invisible when the two are equal.
         let corners = [
-            [l + il, t - it], // TL ← frame TL (+left, −top)
-            [r - ir, t - it], // TR ← frame TR (−right, −top)
-            [r - ir, b + it], // BR ← frame BR (−right, +top)  ⚠ bug: top inset
-            [l + il, b + ib], // BL ← frame BL (+left, +bottom)
+            [l + il, t - it],
+            [r - ir, t - it],
+            [r - ir, b + it], // BR: the top inset
+            [l + il, b + ib],
         ];
-        // Tiled bg UVs (spec §3 bg row): period = tileSize, or edgeSize when tileSize==0. When not
-        // tiled, no SetTexCoord runs and the bg keeps [0,1] (stretch).
+        // Untiled, no `SetTexCoord` runs and the background stretches over `[0,1]` (`0x77f0c0`).
         let uvs = if bd.tile {
             let period = if bd.tile_size != 0.0 { bd.tile_size } else { e };
             let bg_w = (r - ir) - (l + il);
@@ -198,14 +162,12 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
         });
     }
 
-    // ── The 8 border pieces (spec §2 edge rows + §3 UV rows) ───────────────────────────────────
+    // ── The 8 border pieces ──
     if bd.has_border() {
-        // Run lengths (spec §3): the edge strips tile `run` periods between the two corner squares
-        // (no upper clamp — they TILE, never stretch); clamped to 0 below 2·edgeSize.
+        // Edge strips tile `run` periods between the corners, 0 below two edges (`0x77f0c0`).
         let w_run = ((r - l) / e - 2.0).max(0.0);
         let h_run = ((t - b) / e - 2.0).max(0.0);
 
-        // Helper: push an axis-aligned edge/corner piece.
         let mut edge = |x0: f32, x1: f32, y0: f32, y1: f32, uvs: [[f32; 2]; 4]| {
             out.push(BackdropPiece {
                 corners: aa_corners(x0, x1, y0, y1),
@@ -215,7 +177,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
             });
         };
 
-        // LEFT (slice 0): upright, v ∈ [0, h_run].
+        // LEFT, slice 0, upright.
         edge(
             l,
             l + e,
@@ -223,7 +185,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
             t - e,
             [[0.0, 0.0], [SLICE, 0.0], [SLICE, h_run], [0.0, h_run]],
         );
-        // RIGHT (slice 1): upright.
+        // RIGHT, slice 1, upright.
         edge(
             r - e,
             r,
@@ -236,8 +198,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
                 [SLICE, h_run],
             ],
         );
-        // TOP (slice 2): ROTATED — atlas-u→screen-Y (0.25 top, 0.375 bottom), atlas-v→screen-X
-        // reversed (w_run at the LEFT end, 0 at the RIGHT).
+        // TOP, slice 2, rotated: atlas `u` runs down the screen, atlas `v` right to left.
         edge(
             l + e,
             r - e,
@@ -250,7 +211,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
                 [3.0 * SLICE, w_run],
             ],
         );
-        // BOTTOM (slice 3): same rotation as TOP.
+        // BOTTOM, slice 3, rotated as TOP.
         edge(
             l + e,
             r - e,
@@ -263,7 +224,7 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
                 [4.0 * SLICE, w_run],
             ],
         );
-        // Corners (slices 4..7): upright, v ∈ [0,1].
+        // The corners, slices 4 to 7, upright.
         let corner_uv = |i: f32| {
             let u0 = i * SLICE;
             let u1 = (i + 1.0) * SLICE;
@@ -282,21 +243,16 @@ pub fn pieces(frame: Rect, bd: &Backdrop) -> Vec<BackdropPiece> {
 mod tests {
     use super::*;
 
-    /// The bleed inset moves each BOUNDED axis's edge sample onto a texel CENTRE, and leaves a
-    /// tiling axis bit-exact. Pinned against the real `ChatBubble-Backdrop` geometry (256×32, eight
-    /// 32-texel slices) because that is the atlas whose white alpha-0 column put a line through the
-    /// speech bubble (1402).
+    /// On the `ChatBubble-Backdrop` geometry: 256×32, eight 32-texel slices.
     #[test]
     fn the_bleed_inset_lands_on_texel_centres_and_spares_tiling() {
         const W: f32 = 256.0;
         const H: f32 = 32.0;
         let half_u = 0.5 / W;
 
-        // A CORNER: u = one slice, v = [0,1]. Both axes are bounded, so both inset.
         let corner = [[0.5, 0.0], [0.625, 0.0], [0.625, 1.0], [0.5, 1.0]];
         let got = inset_atlas_bleed(corner, W, H);
-        // In texel coordinates the edges now sit on 128.5 / 159.5 — the centres of the first and
-        // last texels of the slice, which is exactly what stops bilinear reaching texel 127.
+        // 128.5 and 159.5 are the centres of the slice's first and last texels.
         let us: Vec<f32> = got.iter().map(|c| c[0] * W).collect();
         assert!((us[0] - 128.5).abs() < 1e-3, "left u at {} texels", us[0]);
         assert!((us[1] - 159.5).abs() < 1e-3, "right u at {} texels", us[1]);
@@ -304,8 +260,6 @@ mod tests {
         assert!((vs[0] - 0.5).abs() < 1e-3, "top v at {} texels", vs[0]);
         assert!((vs[2] - 31.5).abs() < 1e-3, "bottom v at {} texels", vs[2]);
 
-        // A TILING edge strip: u = one slice (bounded → inset), v = [0, 8] (tiling → untouched).
-        // Touching v would make every period land a fraction short and walk the art along the run.
         let strip = [[0.25, 8.0], [0.25, 0.0], [0.375, 0.0], [0.375, 8.0]];
         let got = inset_atlas_bleed(strip, W, H);
         for (g, s) in got.iter().zip(strip.iter()) {
@@ -314,7 +268,6 @@ mod tests {
         assert!((got[0][0] - (0.25 + half_u)).abs() < 1e-6);
         assert!((got[2][0] - (0.375 - half_u)).abs() < 1e-6);
 
-        // The inset NEVER crosses a slice boundary — the property the whole thing exists for.
         for i in 0u8..8 {
             let (u0, u1) = (f32::from(i) * SLICE, f32::from(i + 1) * SLICE);
             let piece = [[u0, 0.0], [u1, 0.0], [u1, 1.0], [u0, 1.0]];
@@ -327,7 +280,6 @@ mod tests {
             }
         }
 
-        // Degenerate inputs are identities, not panics or inversions.
         assert_eq!(inset_atlas_bleed(corner, 0.0, 0.0), corner);
         let sliver = [[0.0, 0.0], [0.001, 0.0], [0.001, 1.0], [0.0, 1.0]];
         assert_eq!(
@@ -354,62 +306,53 @@ mod tests {
         }
     }
 
-    // The primary piece-geometry check: a 200×100 frame, edgeSize 16, insets 5/5/5/5 (the tooltip's
-    // shape). Frame y-up rect = [bottom 0, left 0, top 100, right 200].
+    // The tooltip's shape on a 200×100 frame (`Rect::new` takes bottom, left, top, right).
     #[test]
     fn piece_geometry_200x100_edge16_inset5() {
         let frame = Rect::new(0.0, 0.0, 100.0, 200.0);
         let bd = tooltip_backdrop(16.0, 5.0);
         let ps = pieces(frame, &bd);
-        // bg + 8 border pieces.
         assert_eq!(ps.len(), 9);
 
-        // bg: inset by 5 on every side; with symmetric insets the BR bug is invisible (rect exact).
+        // Symmetric insets hide the bottom-right quirk.
         let bg = ps[0];
         assert!(bg.is_bg);
-        assert_eq!(bg.corners[0], [5.0, 95.0]); // TL (left+5, top-5)
+        assert_eq!(bg.corners[0], [5.0, 95.0]); // TL
         assert_eq!(bg.corners[1], [195.0, 95.0]); // TR
-        assert_eq!(bg.corners[2], [195.0, 5.0]); // BR (bottom+top_inset = 0+5)
-        assert_eq!(bg.corners[3], [5.0, 5.0]); // BL (bottom+bottom_inset = 0+5)
-                                               // Tiled bg UVs: period = tileSize 16; bg is 190×90 ⇒ 11.875 × 5.625 tiles.
+        assert_eq!(bg.corners[2], [195.0, 5.0]); // BR
+        assert_eq!(bg.corners[3], [5.0, 5.0]); // BL
         assert_eq!(bg.uvs[0], [0.0, 0.0]);
         assert!((bg.uvs[1][0] - 190.0 / 16.0).abs() < 1e-4);
         assert!((bg.uvs[2][1] - 90.0 / 16.0).abs() < 1e-4);
 
-        // The border pieces are LEFT, RIGHT, TOP, BOTTOM, TL, TR, BL, BR (indices 1..9). The whole
-        // border sits INSIDE the frame rect, flush, insets untouched.
+        // Border pieces 1 to 8: LEFT, RIGHT, TOP, BOTTOM, TL, TR, BL, BR, flush inside the frame.
         let left = ps[1];
         assert!(!left.is_bg && left.tile);
-        // LEFT edge spans x∈[0,16], y∈[16,84] (b+e .. t-e); corners [TL,TR,BR,BL] y-up.
         assert_eq!(
             left.corners,
             [[0.0, 84.0], [16.0, 84.0], [16.0, 16.0], [0.0, 16.0]]
         );
-        // h_run = 100/16 - 2 = 4.25; LEFT UVs upright, v ∈ [0, 4.25].
+        // h_run = 100/16 - 2 = 4.25.
         assert_eq!(left.uvs[0], [0.0, 0.0]);
         assert_eq!(left.uvs[1], [0.125, 0.0]);
         assert!((left.uvs[3][1] - 4.25).abs() < 1e-4);
 
-        // TOP (index 3): ROTATED. x∈[16,184], y∈[84,100]. w_run = 200/16 - 2 = 10.5.
+        // TOP, rotated; w_run = 200/16 - 2 = 10.5.
         let top = ps[3];
         assert_eq!(top.corners[0], [16.0, 100.0]); // TL
         assert_eq!(top.corners[2], [184.0, 84.0]); // BR
-                                                   // atlas-u→screen-Y: top row u=0.25, bottom row u=0.375.
         assert_eq!(top.uvs[0][0], 0.25); // TL u
         assert_eq!(top.uvs[3][0], 0.375); // BL u
-                                          // atlas-v→screen-X reversed: LEFT end v=w_run, RIGHT end v=0.
         assert!((top.uvs[0][1] - 10.5).abs() < 1e-4); // TL v = w_run
         assert_eq!(top.uvs[1][1], 0.0); // TR v = 0
 
-        // BOTTOMRIGHT corner (index 8): slice 7, upright, v∈[0,1], x∈[184,200], y∈[0,16].
+        // BOTTOMRIGHT, slice 7, upright.
         let br = ps[8];
         assert_eq!(br.corners[0], [184.0, 16.0]); // TL
         assert_eq!(br.uvs[0], [0.875, 0.0]);
         assert_eq!(br.uvs[2], [1.0, 1.0]);
     }
 
-    // The BR-inset quirk (spec §2 ⚠, bytes 8b 46 50 @ 0x77e9ae): with top != bottom the bg's
-    // BOTTOMRIGHT corner rides the TOP inset, not the bottom. Asymmetric insets make it assertable.
     #[test]
     fn bg_bottomright_rides_top_inset_bug() {
         let frame = Rect::new(0.0, 0.0, 100.0, 200.0);
@@ -423,20 +366,16 @@ mod tests {
             ..tooltip_backdrop(16.0, 0.0)
         };
         let bg = pieces(frame, &bd)[0];
-        // BL uses the (correct) bottom inset: y = bottom + 9.
         assert_eq!(bg.corners[3], [3.0, 9.0]);
-        // BR uses the TOP inset (the bug): y = bottom + 7, NOT bottom + 9.
+        // BR takes the top inset, 7, not the bottom's 9.
         assert_eq!(bg.corners[2], [196.0, 7.0]);
-        // The other three edges are regular: TL/TR ride the top inset (−7), left/right insets applied.
-        assert_eq!(bg.corners[0], [3.0, 93.0]); // TL (left+3, top-7)
-        assert_eq!(bg.corners[1], [196.0, 93.0]); // TR (right-4, top-7)
+        assert_eq!(bg.corners[0], [3.0, 93.0]); // TL
+        assert_eq!(bg.corners[1], [196.0, 93.0]); // TR
     }
 
-    // Run clamp at tiny sizes: a frame narrower/shorter than 2·edgeSize clamps both runs to 0 (no
-    // negative tiling), so the edge strips carry a zero-length run (spec §3, "clamped to 0 if < 0").
     #[test]
     fn run_clamps_to_zero_below_two_edges() {
-        // 20×20 frame, edgeSize 16 ⇒ width/16 - 2 = -0.75 → 0.
+        // 20/16 - 2 = -0.75.
         let frame = Rect::new(0.0, 0.0, 20.0, 20.0);
         let bd = tooltip_backdrop(16.0, 5.0);
         let ps = pieces(frame, &bd);
@@ -446,7 +385,6 @@ mod tests {
         assert_eq!(top.uvs[0][1], 0.0, "w_run clamped to 0"); // TL v
     }
 
-    // No files ⇒ no pieces; bg-only ⇒ 1; border-only ⇒ 8.
     #[test]
     fn presence_gates_pieces() {
         let frame = Rect::new(0.0, 0.0, 100.0, 100.0);
diff --git a/crates/benilla-ui/src/script/bank.rs b/crates/benilla-ui/src/script/bank.rs
index fc62c9ef..0e757aeb 100644
--- a/crates/benilla-ui/src/script/bank.rs
+++ b/crates/benilla-ui/src/script/bank.rs
@@ -1,54 +1,22 @@
-//! The bank bindings (decision 0604 phase 4) — the Era-shaped bank surface, the same two-way seam
-//! as [`super::merchant`]: the app pushes a **bank snapshot** ([`UiScript::set_bank`] — the
-//! purchased-slot count off the descriptor's `PLAYER_BYTES_2` byte 2 plus the next slot's
-//! `BankBagSlotPrices.dbc` cost), and the Lua `PurchaseSlot`/`CloseBankFrame` calls queue outbound
-//! **intents** the app drains ([`UiScript::take_bank_purchase`] / [`UiScript::take_bank_close`]).
+//! The bank bindings: the app pushes the open bank's snapshot ([`UiScript::set_bank`]), and
+//! `PurchaseSlot` and `CloseBankFrame` queue intents it drains.
 //!
-//! The bank's *contents* never pass through here: bank slots are player-array slots the container
-//! seam already carries — the app feeds them as container `-1` (`BANK_CONTAINER`, the 24 generic
-//! slots) and containers `5..=10` (the six bank bags), the reference client's own id space
-//! (`BankFrame.lua:1-4`), so the container verbs, the cursor drag-drop, and the stack split all
-//! work on bank slots with no bank-specific surface.
-//!
-//! Nor do the six bank BAGS — the bag items themselves, as opposed to what is inside them. Those
-//! are inventory slots at live ids 64..=69, fed beside the paper doll's
-//! ([`super::char_stats::BankBagSlots`]) and read through the ordinary `GetInventoryItem*` /
-//! `PickupBagFromSlot` surface, which is exactly how the reference's own bank reads them
-//! (`BankFrame.lua:28`, `ButtonInventorySlot`). They stream in the player descriptor whether or
-//! not a banker is open, so they are not part of the window's snapshot.
-//!
-//! ## The 5875 API shape (the reference `BankFrame.lua`, read as behavior spec this session)
-//!
-//! - `GetNumBankSlots()` → `numSlots, full` — purchased count 0..6, `full` as `1`/`nil`
-//!   (`UpdateBagSlotStatus` destructures exactly this pair; `full` hides the purchase frame).
-//! - `GetBankSlotCost(numSlots)` → the NEXT slot's cost in copper. The real binding reads
-//!   `BankBagSlotPrices.dbc` — whose rows 7+ hold a 999999999 sentinel, so the call answers even
-//!   when the bank is full (the purchase frame is already hidden then). The argument is ignored
-//!   here as it is there: the cost of "the next slot" is a fact of the pushed state.
-//! - `PurchaseSlot()` — the confirm popup's accept (`StaticPopup.lua` `CONFIRM_BUY_BANK_SLOT`):
-//!   queue the buy intent; the app sends `CMSG_BUY_BANK_SLOT`. No packet on success — the
-//!   descriptor's byte-2 delta is the confirmation (`PLAYERBANKBAGSLOTS_CHANGED`).
-//! - `CloseBankFrame()` — client-side close, **no packet exists** for it (decision 0604): flag the
-//!   app to clear its session, the merchant/gossip pattern.
-//! - `BankButtonIDToInvSlotID(id, isBag)` — the pure button→live-inventory-slot map: item button
-//!   `i` (1..24) → live `39 + i` (wire 39..62 + 1), bag button — whose id is the **container id**
-//!   5..10, not a bag number — → live `59 + id` (wire 63..68 + 1); the same "live id − 1 = wire
-//!   slot" law as the doll (`crate::script::container`'s `EQUIPMENT_BAG` space). See the binding
-//!   for the four places the reference's own file pins the bag arm's numbering.
+//! The vault is container `-1` (24 slots) and containers 5..=10 (the six bags), the reference's
+//! own ids (`BankFrame.lua:1-4`), so the container verbs work on it unchanged. The bag items
+//! themselves are inventory slots 64..=69, read through `GetInventoryItem*` as the reference's bank
+//! reads them (`BankFrame.lua:28`); they stream whether or not a banker is open.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The open bank window's snapshot: what the purchase row and the six bag buttons need. Pushed
-/// whole by the app while the bank session is open; `None` = no bank open (the window is closed).
-/// The bank's item contents ride the container seam (module doc), not this.
+/// The open bank's purchase row, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct BankState {
-    /// Purchased bank-bag slots (0..=6) — the descriptor's `PLAYER_BYTES_2` byte 2.
+    /// Purchased bag slots, 0..=6: `PLAYER_BYTES_2` byte 2.
     pub num_purchased: u32,
-    /// The NEXT slot's price in copper (`BankBagSlotPrices.dbc` row `num_purchased + 1`; the DBC's
-    /// own 999999999 sentinel past slot 6). 0 only if the DBC row is genuinely absent.
+    /// The next slot's price in copper, `BankBagSlotPrices.dbc` row `num_purchased + 1`; the rows
+    /// past 6 hold 999999999, and 0 means the row is absent.
     pub next_cost: u32,
 }
 
@@ -58,14 +26,14 @@ impl super::UiScript {
         self.model_mut().bank = state;
     }
 
-    /// Whether `PurchaseSlot()` was called since the last drain (and clear the flag). The app
-    /// sends `CMSG_BUY_BANK_SLOT` to the open session's banker.
+    /// Whether `PurchaseSlot()` was called since the last drain; the app sends
+    /// `CMSG_BUY_BANK_SLOT`. Success has no reply packet, only the `PLAYER_BYTES_2` byte-2 change
+    /// (`ItemHandler.cpp:934`).
     pub fn take_bank_purchase(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().bank_purchase)
     }
 
-    /// Whether `CloseBankFrame()` was called since the last drain (and clear the flag). No packet
-    /// — the app just clears its local bank session (the merchant pattern).
+    /// Whether `CloseBankFrame()` was called since the last drain; no packet exists for it.
     pub fn take_bank_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().bank_close)
     }
@@ -75,8 +43,8 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumBankSlots() → numSlots, full (1/nil — the client's boolean shape; the reference
-    // destructures `local numSlots, full = GetNumBankSlots()`). 0, nil with no bank open.
+    // GetNumBankSlots() → numSlots, full: `full` is 1 from six slots up, else nil (`0x4f85b0`:
+    // `cmp esi,6; jl`).
     g.set(
         "GetNumBankSlots",
         lua.create_function(|lua, ()| {
@@ -96,8 +64,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetBankSlotCost(numSlots) → the next slot's cost in copper (module doc: the argument is
-    // decorative — the pushed state already names the next slot). 0 with no bank open.
+    // GetBankSlotCost(numSlots): the argument is unread; the pushed state names the next slot.
     g.set(
         "GetBankSlotCost",
         lua.create_function(|lua, _n: Option<u32>| {
@@ -106,10 +73,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BenillaGetBankBagTexture(i) → the bank bag slot's held-bag icon path | nil (empty slot, or
-    // no bank open) — benilla-named (module doc: the snapshot carries what the reference read
-    // through the inventory-item API).
-    // PurchaseSlot() — queue the bank-slot buy intent (the CONFIRM_BUY_BANK_SLOT popup's accept).
+    // PurchaseSlot(): the `CONFIRM_BUY_BANK_SLOT` popup's accept (`StaticPopup.lua:52`).
     g.set(
         "PurchaseSlot",
         lua.create_function(|lua, ()| {
@@ -119,7 +83,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseBankFrame() — client-side close (no packet exists, decision 0604): flag the app.
     g.set(
         "CloseBankFrame",
         lua.create_function(|lua, ()| {
@@ -129,40 +92,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BankButtonIDToInvSlotID(id, isBag) — the pure button→live-slot map (module doc).
-    //
-    // CARVED (`0x4f8530`, 118 bytes; wow-re `system/ui/scratch/bank-button-invslot-law.md`, §5
-    // trio + orchestrator byte arbitration 2026-08-31). Three findings, and two of them corrected
-    // this binding:
-    //
-    // 1 · **The arithmetic is `+59` / `+39`, and the bag arm takes the CONTAINER id 5..10** — not
-    //   a bag number 1..6, which is what this used to compute. `0x4f8575 dec esi` runs BEFORE the
-    //   branch and `0x4f8587 inc esi` AFTER it, so the pair cancels and the constants stand as
-    //   written (`0x4f857f add esi,0x3b` / `0x4f8584 add esi,0x27`). The bag arm is numerically
-    //   identical to `ContainerIDToInventoryID 0x4f94e0`'s own `id >= 5` arm — two functions, two
-    //   instruction sequences, one constant. The reference's file pins the same numbering four
-    //   times over: `BankFrame.xml` gives `BankFrameBag1` `id="5"`, `ButtonInventorySlot` hands
-    //   `this:GetID()` straight in, and `UpdateBagButtonHighlight`/`BankFrameItemButton_UpdateLock`
-    //   both subtract 4 from it to get back to 1..6.
-    //
-    // 2 · **`isBag` is a TYPE test, not a truthiness test.** `0x4f8576 call 0x6f34d0` is
-    //   `lua_isnumber(L, 2)`, which accepts tag 3 or a tag-4 string `luaO_str2d` fully consumes,
-    //   and refuses every other tag at `0x6f7c35` without ever loading the value. So **`true`
-    //   takes the same arm as `nil`, `false` and a missing argument**, while `0` and `"1"` take
-    //   the BAG arm. `BankFrame.lua:24` writes `this.isBag = 1` — a NUMBER — so the stock UI is
-    //   correct either way; a client that models the flag as a boolean diverges the moment an
-    //   addon passes `true`, and would then resolve the six bank bags to 44..49, colliding with
-    //   `BankFrameItem5..10`.
-    //
-    // 3 · **Total, with no range check of any kind.** The only `test`/`cmp` in all 118 bytes are
-    //   on `lua_isnumber`'s return value: no clamp, no mask, no `nil`. This used to answer 0
-    //   outside 1..24 / 5..10 as a "wired wrong" tell; that was our invention, and the reference
-    //   simply returns the arithmetic. Its immediate neighbour `GetNumBankSlots 0x4f85b0` carries
-    //   a real `cmp esi,6; jl`, so a bound would have been visible here if one existed.
-    //
-    // Argument 1 is shape A ([`binding_abi::number_arg`]): `lua_isnumber` gated, truncated toward
-    // zero by the `0x40a2b0` ftol, low dword only, and raising the `.data` usage string verbatim
-    // — which names only `buttonID`, the reference's own omission of the second parameter.
+    // BankButtonIDToInvSlotID(id, isBag) (`0x4f8530`): `id + 39` for an item button, `id + 59`
+    // for a bag button, whose id is the container id 5..=10 (`BankFrame.xml:372`), the same
+    // arithmetic as `ContainerIDToInventoryID`'s bank-bag arm (`0x4f94e0`). There is no range
+    // check. `isBag` is `lua_isnumber(L, 2)` (`0x4f8576`), not truthiness: `true` takes the item
+    // arm, `0` and `"1"` the bag arm; stock sets `this.isBag = 1` (`BankFrame.lua:24`). Argument 1
+    // truncates toward zero (`0x40a2b0`), and its usage string names only `buttonID`.
     g.set(
         "BankButtonIDToInvSlotID",
         lua.create_function(|lua, (id, is_bag): (Value, Option<Value>)| {
@@ -171,7 +106,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 id,
                 "Usage: BankButtonIDToInvSlotID(buttonID)",
             )?;
-            // Finding 2: `lua_isnumber(L, 2)`, asked of the VALUE's type — never its truthiness.
             let is_bag = is_bag
                 .and_then(|v| lua.coerce_number(v).ok().flatten())
                 .is_some();
@@ -188,8 +122,6 @@ mod tests {
     use super::BankState;
     use crate::script::UiScript;
 
-    /// The purchase-row reads: closed → (0, nil)/0; open → the pushed count + next cost; six
-    /// purchased → `full` = 1 (the reference hides the purchase frame on it).
     #[test]
     fn bank_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
@@ -207,7 +139,7 @@ mod tests {
             .unwrap());
         assert_eq!(s.eval::<i64>("return GetBankSlotCost(2)").unwrap(), 100_000);
 
-        // Six purchased: full = 1; the cost read still answers (the DBC's own sentinel row).
+        // Six purchased: full = 1, and 999999999 is the DBC's sentinel row.
         s.set_bank(Some(BankState {
             num_purchased: 6,
             next_cost: 999_999_999,
@@ -216,17 +148,14 @@ mod tests {
             .eval::<bool>("local n, full = GetNumBankSlots()\nreturn n == 6 and full == 1")
             .unwrap());
 
-        // Clearing empties it.
         s.set_bank(None);
         assert!(s
             .eval::<bool>("local n, full = GetNumBankSlots()\nreturn n == 0 and full == nil")
             .unwrap());
     }
 
-    /// The six bank BAGS are inventory slots at live ids 64..=69, read through the ordinary
-    /// inventory API — the band the reference's own bank uses (`ButtonInventorySlot` →
-    /// `BankButtonIDToInvSlotID(id, this.isBag)`, BankFrame.lua:28). Empty slots answer nil, and
-    /// the band does not bleed into the equipment array below it.
+    /// The bank bags are inventory slots 64..=69, as the reference's bank reads them
+    /// (`BankFrame.lua:28`).
     #[test]
     fn bank_bag_slots_read_through_the_inventory_api() {
         let mut s = UiScript::new().unwrap();
@@ -261,7 +190,7 @@ mod tests {
                 .unwrap(),
             4500
         );
-        // Bag slot 2 is empty, and slot 70 is past the band — neither falls through to the doll.
+        // Slot 65 is empty and 70 is past the band; neither falls through to the doll.
         assert!(s
             .eval::<bool>("return GetInventoryItemTexture(\"player\", 65) == nil")
             .unwrap());
@@ -284,14 +213,8 @@ mod tests {
         assert!(!s.take_bank_close(), "drained");
     }
 
-    /// **The bank's inventory BAND answers from the container feed** — the map decision 1751's
-    /// bank swap turns on. The reference's bank paints every slot through the inventory API
-    /// (`BankFrameItemButton_OnUpdate` → `GetInventoryItemTexture("player", BankButtonIDToInv
-    /// SlotID(id))`, BankFrame.lua:35) while benilla feeds the same items as container `-1`. If
-    /// those two ever disagree the bank draws empty, which is exactly the failure this pins.
-    ///
-    /// Asserted through the live API rather than the model, because the API is what the
-    /// reference's file calls, and the tooltip must agree with the icon under it.
+    /// The reference paints the vault through the inventory API (`BankFrame.lua:35`) while the app
+    /// feeds it as container `-1`; if the two disagree the bank draws empty.
     #[test]
     fn the_bank_band_reads_the_vault_through_the_inventory_api() {
         let mut s = UiScript::new().unwrap();
@@ -316,7 +239,7 @@ mod tests {
             }),
         );
 
-        // Vault slot 3 is live-API inventory id 42 (BankButtonIDToInvSlotID(3)).
+        // Vault slot 3 is inventory id 42.
         assert_eq!(
             s.eval::<i64>("return BankButtonIDToInvSlotID(3)").unwrap(),
             42
@@ -336,8 +259,7 @@ mod tests {
                 .unwrap(),
             4496
         );
-        // …and an empty vault slot answers nil, not the equipment slot that shares no numbering
-        // with it — the band must not fall through to `inventory_slots`.
+        // An empty vault slot answers nil rather than falling through to `inventory_slots`.
         assert!(s
             .eval::<bool>("return GetInventoryItemTexture(\"player\", 43) == nil")
             .unwrap());
@@ -347,13 +269,8 @@ mod tests {
             .unwrap());
     }
 
-    /// The button→live-slot map: item buttons 1..24 → 40..63; bag buttons — **whose ids are the
-    /// container ids 5..10, not bag numbers** — → 64..69 (live id − 1 = the wire slot: bank items
-    /// 39..62, bank bags 63..68).
-    ///
-    /// The bag arm's numbering is checked here because getting it wrong reads six slots off the
-    /// end of the band and draws an empty bag row — which is what this binding did until the
-    /// `0x4f8530` carve.
+    /// Item buttons 1..=24 map to 40..=63 and bag buttons, whose ids are the container ids 5..=10,
+    /// to 64..=69; the wire slot is one less.
     #[test]
     fn bank_button_to_inv_slot() {
         let s = UiScript::new().unwrap();
@@ -377,9 +294,8 @@ mod tests {
             69,
             "BankFrameBag6 carries id 10"
         );
-        // It is the SAME map `ContainerIDToInventoryID` computes for a bank bag — one arithmetic
-        // under two names, and a drift between them would put the bag row and the bag windows on
-        // different slots.
+        // The same map as `ContainerIDToInventoryID` for a bank bag; a drift would put the bag row
+        // and the bag windows on different slots.
         for id in 5..=10 {
             assert_eq!(
                 s.eval::<i64>(&format!("return BankButtonIDToInvSlotID({id}, 1)"))
@@ -390,17 +306,12 @@ mod tests {
         }
     }
 
-    /// The three things the `0x4f8530` carve corrected, each of which this binding had wrong or
-    /// invented (wow-re `scratch/bank-button-invslot-law.md`).
     #[test]
     fn bank_button_to_inv_slot_follows_the_carved_abi() {
         let s = UiScript::new().unwrap();
 
-        // **`isBag` is a TYPE test** (`lua_isnumber(L,2)`), not a truthiness test. `true` is not a
-        // number, so it takes the ITEM arm exactly as nil and false do; `0` and `"1"` are numbers
-        // and take the BAG arm. The stock UI is safe either way — `BankFrame.lua:24` writes
-        // `this.isBag = 1` — but an addon passing `true` would otherwise land the six bank bags on
-        // 44..49, on top of `BankFrameItem5..10`.
+        // `isBag` is `lua_isnumber(L, 2)`: `true` takes the item arm as nil and false do, while
+        // `0` and `"1"` take the bag arm.
         for (call, want) in [
             ("BankButtonIDToInvSlotID(5, true)", 44),
             ("BankButtonIDToInvSlotID(5, false)", 44),
@@ -417,8 +328,7 @@ mod tests {
             );
         }
 
-        // **Total — no range check of any kind.** Answering 0 outside the button ranges was ours,
-        // not the reference's; the only compares in the body are on `lua_isnumber`'s result.
+        // No range check: the only compares in `0x4f8530` test `lua_isnumber`'s result.
         assert_eq!(
             s.eval::<i64>("return BankButtonIDToInvSlotID(25)").unwrap(),
             64
@@ -429,9 +339,8 @@ mod tests {
             -61
         );
 
-        // Argument 1 is shape A: `lua_isnumber` gated, truncated toward ZERO by the `0x40a2b0`
-        // ftol (not floored), and raising the `.data` usage string — which names only `buttonID`,
-        // the reference's own omission of the second parameter.
+        // Argument 1 truncates toward zero (`0x40a2b0`), and the usage string names only
+        // `buttonID`.
         assert_eq!(
             s.eval::<i64>("return BankButtonIDToInvSlotID(-2.9)")
                 .unwrap(),
diff --git a/crates/benilla-ui/src/script/battlefield_positions.rs b/crates/benilla-ui/src/script/battlefield_positions.rs
index ac9ba07c..02a96108 100644
--- a/crates/benilla-ui/src/script/battlefield_positions.rs
+++ b/crates/benilla-ui/src/script/battlefield_positions.rs
@@ -1,31 +1,22 @@
-//! The battleground **position** family (decision 1980; wow-re
-//! `system/ui/scratch/worldmap-arrow-and-positions.md` §3): the six verbs the stock
-//! `WorldMapFrame.lua` and `Blizzard_BattlefieldMinimap.lua` poll to place teammates and the
-//! flag carrier on the map.
-//!
-//! The wire carries raw world floats for the teammates outside the requester's group; the
-//! reference filters out itself, its four party slots and its raid roster, prefers the live
-//! object's position over the packet's, and normalizes through the world-map projection under the
-//! active queue slot's map — all app-side facts here, so the app pushes the finished list every
-//! frame ([`BattlefieldPositionView`], already filtered and projected) and the VM owns the getters'
-//! shapes: three values on every non-raising leg, `(0, 0, nil)` off the list.
+//! The battleground position verbs `WorldMapFrame.lua` and `Blizzard_BattlefieldMinimap.lua` poll
+//! to place teammates and the flag carrier (opcode `0x2E9`, handler `0x4aad40`). The reference
+//! drops itself, its party and its raid, prefers a live object's position and projects onto the
+//! active slot's map; the app does all that and pushes the finished list here.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::number_arg;
 use super::Model;
 
-/// One teammate as the app resolved it: the map-normalized pair (`(0, 0)` = off the displayed
-/// map) and the name, `None` while the name cache has not answered.
+/// One teammate: map-normalized position, `(0, 0)` off the displayed map, and name if known.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldPositionView {
     pub uv: (f32, f32),
     pub name: Option<String>,
 }
 
-/// The flag carrier as the app resolved it: the pair, and the token the local player's faction
-/// selects (`"HordeFlag"` for an Alliance viewer, `"AllianceFlag"` for a Horde one, `None` for
-/// neither).
+/// The flag carrier: the position and the token the viewer's faction picks, `"HordeFlag"` for an
+/// Alliance viewer and `"AllianceFlag"` for a Horde one.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldFlagView {
     pub uv: (f32, f32),
@@ -33,7 +24,7 @@ pub struct BattlefieldFlagView {
 }
 
 impl super::UiScript {
-    /// Push the resolved positions, the carrier (or none) and the active map's icon scale.
+    /// Push the positions, the carrier and the active map's icon scale.
     pub fn set_battlefield_positions(
         &mut self,
         players: Vec<BattlefieldPositionView>,
@@ -46,8 +37,8 @@ impl super::UiScript {
         model.battlefield_icon_scale = icon_scale;
     }
 
-    /// `RequestBattlefieldPositions()` calls since the last drain — the app throttles to 5000 ms
-    /// and sends only with an active slot.
+    /// `RequestBattlefieldPositions()` calls since the last drain; the app sends at most every
+    /// 5000 ms, and only with an active slot.
     pub fn take_battlefield_position_requests(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().battlefield_position_requests)
     }
@@ -67,7 +58,6 @@ fn three(lua: &Lua, uv: (f32, f32), third: Option<&str>) -> mlua::Result<MultiVa
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `GetNumBattlefieldPositions()` — the survivors of the filter, one number.
     g.set(
         "GetNumBattlefieldPositions",
         lua.create_function(|lua, ()| {
@@ -76,8 +66,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldPosition(index)` — the usage raise; 1-based over the survivors; three values
-    // on every leg, `(0, 0, nil)` off the list and for 0 or a negative.
+    // Three values on every leg that does not raise: `(0, 0, nil)` off the list, 0 and below too.
     g.set(
         "GetBattlefieldPosition",
         lua.create_function(|lua, index: Value| {
@@ -94,7 +83,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetNumBattlefieldFlagPositions()` — one carrier slot: 1 or 0.
     g.set(
         "GetNumBattlefieldFlagPositions",
         lua.create_function(|lua, ()| {
@@ -103,8 +91,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldFlagPosition(index)` — the usage raise; selected only for index 1 with a
-    // carrier; three values always.
     g.set(
         "GetBattlefieldFlagPosition",
         lua.create_function(|lua, index: Value| {
@@ -117,8 +103,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldMapIconScale()` — the active map's `MinimapIconScale` (map 0's with no slot,
-    // 1.0 on a missing row), pushed by the app.
+    // The active map's `MinimapIconScale`: map 0's with no slot, 1.0 for a missing row.
     g.set(
         "GetBattlefieldMapIconScale",
         lua.create_function(|lua, ()| {
@@ -127,7 +112,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `RequestBattlefieldPositions()` — counted; the app's 5000 ms throttle and slot gate decide.
     g.set(
         "RequestBattlefieldPositions",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/battlefield_queue.rs b/crates/benilla-ui/src/script/battlefield_queue.rs
index c9a1d30c..2fbf1fac 100644
--- a/crates/benilla-ui/src/script/battlefield_queue.rs
+++ b/crates/benilla-ui/src/script/battlefield_queue.rs
@@ -1,58 +1,25 @@
-//! The battleground **list and queue** family (decision 1974; wow-re
-//! `system/ui/scratch/battlefield-verb-family.md` §2.1, §2.2, §3.1–3.6, §5.2): the fourteen
-//! verbs the stock `BattlefieldFrame.lua` and `Minimap.xml` call, over the instance list and the
-//! three queue slots the app pushes. The scoreboard half of the same TU is
-//! [`super::battlefield_score`]; `AcceptBattlefieldPort` is [`super::dialog_verbs`]'s.
-//!
-//! ## What is the app's and what is the VM's
-//!
-//! The reference keeps three caches in `BattlefieldInfo.cpp`: the instance-id vector the
-//! `SMSG_BATTLEFIELD_LIST` handler fills (§2.1), the fixed three-slot queue array
-//! `SMSG_BATTLEFIELD_STATUS` writes (§2.2), and four scalars beside them — the battlemaster
-//! guid, the listed map, the bracket-adjusted level pair, and the **selected instance id**. Every
-//! verb below reads those and nothing else. The app owns the wire, the clock and the Map.dbc
-//! resolves, so it pushes the list ([`BattlefieldListView`]) when a list lands and the slots
-//! ([`BattlefieldQueueSlot`], with every clock-shaped value already in milliseconds) every frame;
-//! the VM owns the selection (`[0xb6eba0]`), the index arithmetic and the getters' shapes.
-//!
-//! ## The selection is a value, not an index (§3.5)
-//!
-//! `SetSelectedBattlefield(n)` stores the **instance id** at list position `n`, and
-//! `GetSelectedBattlefield()` scans the current list for that id — so a fresh list between the
-//! two calls can move or drop the selection, which the stock window's `zoneIndex − 1 ==
-//! GetSelectedBattlefield()` highlight then follows. A client that remembered an index would
-//! diverge the moment a list reorders.
-//!
-//! ## Shapes (§3, §3.1)
-//!
-//! Every required index is shape A (`lua_isnumber`, so a numeric string passes; truncated toward
-//! zero; a non-number raises the binding's own `Usage:`), 1-based with the reference's unsigned
-//! `dec; cmp; jae` gate that rejects 0 and negatives in one branch. `GetBattlefieldStatus`
-//! answers **five values on every leg** — `(nil, nil, 0, 0, 0)` off the three slots.
-//! `GetBattlefieldInfo` answers nine or none. `GetBattlefieldInstanceInfo` raises with
-//! `GetBattlefieldInfo`'s usage string — the shipped client's own mislabel, reproduced.
-//! `CloseBattlefield` does nothing (`xor eax,eax; ret`).
+//! The battleground list and queue verbs of `BattlefieldFrame.lua` and `Minimap.xml`. They read
+//! the reference's instance list (`0xb6e860`, filled by `0x4aa6c0`), its three queue slots
+//! (`0xb6e9d0`, written by `0x4aa850`) and the selected instance id (`[0xb6eba0]`); the app pushes
+//! the list and the slots, clock values in ms, and the VM owns the selection.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::{bool_or_default, flag, number_arg};
 use super::Model;
 
-/// One queue slot as the app pushes it — the reference's `0x20`-byte slot (§2.2) plus the map
-/// name its `GetBattlefieldStatus` resolves off Map.dbc, and the three clock-shaped fields
-/// already reduced against the app's clock.
+/// One queue slot: the reference's `0x20`-byte slot (`0xb6e9d0`) plus its Map.dbc name.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldQueueSlot {
-    /// `+0x00` — the Map.dbc row id; `0` for a cleared slot. The name is resolved for that id too
-    /// (the reference looks map 0 up like any other row).
+    /// `+0x00`, the Map.dbc row id; 0 is a cleared slot, its name looked up like any other.
     pub map_id: u32,
     /// The localized map name, or `None` when the id has no row (a real `nil`).
     pub map_name: Option<String>,
-    /// `+0x04` — `0` none, `1` queued, `2` confirm, `3` active; anything else answers `"error"`.
+    /// `+0x04`: `0` none, `1` queued, `2` confirm, `3` active; anything else answers `"error"`.
     pub status: u32,
-    /// `+0x10` — the instance id.
+    /// `+0x10`.
     pub instance_id: u32,
-    /// `+0x08`/`+0x0c` — the bracket-adjusted level pair.
+    /// `+0x08`/`+0x0c`: the bracket-adjusted level pair.
     pub min_level: u32,
     pub max_level: u32,
     /// `GetBattlefieldPortExpiration`: `deadline − now` in ms, 0 when unset or past.
@@ -63,18 +30,15 @@ pub struct BattlefieldQueueSlot {
     pub time_waited_ms: u32,
 }
 
-/// The Map.dbc half of `GetBattlefieldInfo` (§3.4), resolved by the app for the listed map.
+/// The Map.dbc half of `GetBattlefieldInfo` (`0x4ab0b0`), resolved by the app for the listed map.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldMapInfo {
-    /// The localized map name (value 1).
     pub name: String,
-    /// The faction-side description (value 2) — `None` on the reference's `-1` faction leg, where
-    /// it pushes nothing at all and Lua reads a stack slot below the tuple; here that leg answers
-    /// `nil`, the one shape this binding does not reproduce (the leg is data-unreachable: every
-    /// playable race carries a faction bit).
+    /// The description for the player's faction. Deviation: `None` answers `nil` where the
+    /// reference's `-1` faction leg pushes nothing (Lua reads below the tuple), because no
+    /// playable race reaches that leg.
     pub description: Option<String>,
-    /// The row's raw `MinLevel`/`MaxLevel` columns (values 3 and 4 — the stock Lua names them
-    /// `minLevel, maxLevel`; the bracket-adjusted pair is values 8 and 9).
+    /// The row's raw `MinLevel`/`MaxLevel` (values 3 and 4), not the bracket-adjusted pair.
     pub min_level: u32,
     pub max_level: u32,
     /// Values 5–7: `[row+0x40]` signed, `[row+0x44]` and `[row+0x48]` f32.
@@ -83,7 +47,7 @@ pub struct BattlefieldMapInfo {
     pub field_18: f32,
 }
 
-/// The instance list and its scalars as the app pushes them ([`super::UiScript::set_battlefield_list`]).
+/// The instance list and the scalars beside it, as the app pushes them.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct BattlefieldListView {
     /// The instance ids in wire order (`[0xb6e868]`).
@@ -91,14 +55,13 @@ pub struct BattlefieldListView {
     /// The bracket-adjusted level pair the list handler derived (`[0xb6eba8]`/`[0xb6ebac]`).
     pub bracket_min: u32,
     pub bracket_max: u32,
-    /// The listed map's row, `None` when the id resolves to no row (the second zero-values gate).
+    /// The listed map's row; `None` when the id has no row, which answers no values.
     pub info: Option<BattlefieldMapInfo>,
-    /// The listed map row's group-queue flag (`[row+0xa0]`, §3.6) — `CanJoinBattlefieldAsGroup`.
+    /// The map row's group-queue flag, `[row+0xa0]`.
     pub group_queue: bool,
 }
 
-/// The reference's 1-based index gate: `dec eax; cmp eax,n; jae bail` — an unsigned compare, so
-/// `0` and every negative fall out in the same branch as `> n`.
+/// The reference's 1-based gate (`dec; cmp; jae`), unsigned: 0 and negatives fail as too large.
 fn slot_index(index: i32, n: usize) -> Option<usize> {
     usize::try_from(index)
         .ok()?
@@ -106,15 +69,13 @@ fn slot_index(index: i32, n: usize) -> Option<usize> {
         .filter(|&i| i < n)
 }
 
-/// The local-player gate `GetBattlefieldInfo` and `GetBattlefieldInstanceInfo` answer zero values
-/// behind (`0x468550` + `0x468460(ecx = 0x10)`: the player object, read at call time) — here the
-/// unit model's `"player"` token, the same answer `UnitExists("player")` gives.
+/// The local-player gate of `GetBattlefieldInfo` and `GetBattlefieldInstanceInfo`, read at call
+/// time (`0x468550`, `0x468460` with `ecx = 0x10`): the answer `UnitExists("player")` gives.
 fn player_exists(model: &Model) -> bool {
     model.unit("player").is_some_and(|u| u.exists)
 }
 
-/// `[slot+0x04]` → the status string, through the reference's four-entry jump table with its
-/// `"error"` default (§3.2).
+/// The reference's four-entry status jump table with its `"error"` default (`0x4ab604`).
 fn status_text(status: u32) -> &'static str {
     match status {
         0 => "none",
@@ -126,20 +87,19 @@ fn status_text(status: u32) -> &'static str {
 }
 
 impl super::UiScript {
-    /// Push the instance list. The selection (`[0xb6eba0]`) is left alone — a new list does not
-    /// clear it, it only decides whether `GetSelectedBattlefield` still finds it (§3.5).
+    /// Push the instance list. A new list leaves the selection (`[0xb6eba0]`) alone; it only
+    /// decides whether `GetSelectedBattlefield` still finds it (`0x4ab360`).
     pub fn set_battlefield_list(&mut self, list: BattlefieldListView) {
         self.model_mut().battlefield_list = list;
     }
 
-    /// The world-enter reset's half of this family (§8): the selection cleared with the list.
+    /// The world-enter reset (`0x4a9db0`) clears the selection with the list.
     pub fn reset_battlefield_selection(&mut self) {
         self.model_mut().battlefield_selected = 0;
     }
 
-    /// Push the three queue slots (clock-shaped values already reduced) and the instance
-    /// expiration (`[0xb6ebb8]`, `deadline − now`, 0 when unset or past) — every frame, since
-    /// three of the getters move with the clock.
+    /// Push the queue slots and the instance expiration (`[0xb6ebb8]`) every frame, since the
+    /// clock getters move.
     pub fn set_battlefield_queue(
         &mut self,
         slots: Vec<BattlefieldQueueSlot>,
@@ -150,15 +110,13 @@ impl super::UiScript {
         model.battlefield_instance_expiration_ms = instance_expiration_ms;
     }
 
-    /// `JoinBattlefield` calls since the last drain: `(instance id, 0 = first available; as a
-    /// group)`. The app adds the map, the cached battlemaster guid (which picks the opcode) and
-    /// the group-size refusal (§5.2).
+    /// `JoinBattlefield` calls since the last drain, `(instance, as group)`; instance 0 is first
+    /// available. The app adds the map, the opcode and the group-size refusal (`0x4a9f60`).
     pub fn take_battlefield_join_requests(&mut self) -> Vec<(u32, bool)> {
         std::mem::take(&mut self.model_mut().battlefield_join_requests)
     }
 
-    /// `ShowBattlefieldList` calls that passed their gates since the last drain: the queued
-    /// slot's map id, `CMSG_BATTLEFIELD_LIST`'s payload.
+    /// `ShowBattlefieldList` calls since the last drain: the map ids for `CMSG_BATTLEFIELD_LIST`.
     pub fn take_battlefield_list_requests(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().battlefield_list_requests)
     }
@@ -167,7 +125,6 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `GetNumBattlefields()` — 0 args, never raises: the instance count.
     g.set(
         "GetNumBattlefields",
         lua.create_function(|lua, ()| {
@@ -176,8 +133,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldInfo()` — 0 args, never raises; ZERO values behind either gate (no player, no
-    // map row), else nine (§3.4).
+    // No values without a player or a map row, else nine (`0x4ab0b0`).
     g.set(
         "GetBattlefieldInfo",
         lua.create_function(|lua, ()| {
@@ -204,9 +160,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldInstanceInfo(index)` — raises with GetBattlefieldInfo's usage string (the
-    // shipped mislabel, §3.1); no player or out of range → zero values; else the instance id,
-    // pushed SIGNED (`fild dword`).
+    // Raises with `GetBattlefieldInfo`'s usage string, the reference's own mislabel (`0x845c48`).
+    // No values without a player or out of range, else the instance id pushed signed (`fild`).
     g.set(
         "GetBattlefieldInstanceInfo",
         lua.create_function(|lua, index: Value| {
@@ -225,10 +180,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `JoinBattlefield(index [, asGroup])` — arg 1 shape A, arg 2 the never-raising optional
-    // boolean reader; the instance is `index−1 < count ? list[index−1] : 0` (0 = first
-    // available, and what an out-of-range index — 0 included — degrades to), §5.2. The refusal
-    // leg and the opcode choice are the app's and invisible to Lua.
+    // An out-of-range index, 0 included, joins instance 0, the first available (`0x4a9f60`).
     g.set(
         "JoinBattlefield",
         lua.create_function(|lua, (index, as_group): (Value, Value)| {
@@ -242,11 +194,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CloseBattlefield()` — `xor eax,eax; ret`: nothing, and the stock window calls it on hide.
+    // A no-op in the reference (`xor eax,eax; ret`); the stock window calls it on hide.
     g.set("CloseBattlefield", lua.create_function(|_, ()| Ok(()))?)?;
 
-    // `SetSelectedBattlefield(index)` — stores the instance id at that position, or 0 when out
-    // of range (§3.5).
+    // Stores the instance id at that position, 0 when out of range (`0x4ab300`).
     g.set(
         "SetSelectedBattlefield",
         lua.create_function(|lua, index: Value| {
@@ -258,8 +209,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetSelectedBattlefield()` — the 1-based position of the stored id in the CURRENT list, or
-    // 0 on a miss (which is also what a stored 0 answers: the "first available" row).
+    // The stored id's 1-based position in the current list; 0 on a miss, as for a stored 0.
     g.set(
         "GetSelectedBattlefield",
         lua.create_function(|lua, ()| {
@@ -274,8 +224,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldStatus(index)` — five values on EVERY leg (§3.2): off 1..3 it is
-    // `(nil, nil, 0, 0, 0)`, never a raise and never zero values.
+    // Five values on every leg (`0x4ab5c7`): `(nil, nil, 0, 0, 0)` off slots 1..3.
     g.set(
         "GetBattlefieldStatus",
         lua.create_function(|lua, index: Value| {
@@ -305,8 +254,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The three per-slot clock-shaped getters (§3.3): shape A index, 0 off 1..3, one number
-    // always. The app reduces each against its clock; the values arrive in ms.
+    // The per-slot clock getters (`0x4ab620`, `0x4ab790`, `0x4ab820`), in ms; 0 off slots 1..3.
     for (name, usage, read) in [
         (
             "GetBattlefieldPortExpiration",
@@ -338,7 +286,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // `GetBattlefieldInstanceExpiration()` — 0 args: `[0xb6ebb8] − now`, 0 when unset or past.
+    // `[0xb6ebb8] − now`, 0 when unset or past.
     g.set(
         "GetBattlefieldInstanceExpiration",
         lua.create_function(|lua, ()| {
@@ -347,8 +295,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `ShowBattlefieldList(index)` — shape A; silent off 1..3, on an empty slot, and on any
-    // status but "queued"; else the slot's map goes out as `CMSG_BATTLEFIELD_LIST`. No event.
+    // Silent unless the slot is queued; fires no event.
     g.set(
         "ShowBattlefieldList",
         lua.create_function(|lua, index: Value| {
@@ -365,8 +312,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CanJoinBattlefieldAsGroup()` — `1` or nil off the listed map's `+0xa0` flag (§3.6). The
-    // join-time size check reads a different column and lives with the sender.
+    // `1` or nil (`0x4ac380`); the join-time group-size check reads another column, in the app.
     g.set(
         "CanJoinBattlefieldAsGroup",
         lua.create_function(|lua, ()| {
@@ -383,7 +329,7 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// A VM with a local player — the state every in-world call is made in.
+    /// A VM with a local player, as every in-world call has.
     fn vm() -> UiScript {
         let mut s = UiScript::new().unwrap();
         s.set_unit(
@@ -429,7 +375,6 @@ mod tests {
         }
     }
 
-    /// The reference's 1-based gate: 0 and negatives fall out with the too-large ones.
     #[test]
     fn the_index_gate_is_unsigned_and_one_based() {
         assert_eq!(slot_index(1, 3), Some(0));
@@ -440,8 +385,6 @@ mod tests {
         assert_eq!(slot_index(1, 0), None);
     }
 
-    /// Nine values past both gates, none behind either; the two raw row levels sit at 3 and 4
-    /// and the bracket pair at 8 and 9.
     #[test]
     fn get_battlefield_info_answers_nine_or_none() {
         let mut s = vm();
@@ -474,7 +417,6 @@ mod tests {
         assert_eq!(got, "Arathi Basin|20|60|-1|20|29");
     }
 
-    /// The instance verb: the wrong usage string, the silent out-of-range leg, the signed push.
     #[test]
     fn get_battlefield_instance_info_raises_with_the_mislabel_and_bails_silently() {
         let mut s = vm();
@@ -503,7 +445,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumBattlefields()").unwrap(), 2);
     }
 
-    /// The selection round-trips by VALUE: a reordered list moves it, a shortened one drops it.
     #[test]
     fn the_selection_is_an_instance_id_not_a_position() {
         let mut s = vm();
@@ -538,8 +479,6 @@ mod tests {
         );
     }
 
-    /// `JoinBattlefield`: the instance at the position, 0 for "first available" and for any
-    /// out-of-range index, the optional group flag through the never-raising reader.
     #[test]
     fn join_battlefield_resolves_the_instance_and_the_group_flag() {
         let mut s = vm();
@@ -556,7 +495,6 @@ mod tests {
         s.run("CloseBattlefield()").unwrap();
     }
 
-    /// Five values on every leg of the status verb; the four status strings and the default.
     #[test]
     fn get_battlefield_status_answers_five_values_on_every_leg() {
         let mut s = UiScript::new().unwrap();
@@ -602,8 +540,6 @@ mod tests {
         );
     }
 
-    /// The clock-shaped getters read the pushed ms and answer 0 off the slots; the instance
-    /// expiration is the singleton.
     #[test]
     fn the_time_getters_read_the_pushed_milliseconds() {
         let mut s = UiScript::new().unwrap();
@@ -655,8 +591,6 @@ mod tests {
         }
     }
 
-    /// `ShowBattlefieldList` sends only for a queued, non-empty slot; the group predicate is
-    /// `1` or nil.
     #[test]
     fn show_battlefield_list_gates_on_a_queued_slot() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/battlefield_score.rs b/crates/benilla-ui/src/script/battlefield_score.rs
index d7c74053..c23a0c65 100644
--- a/crates/benilla-ui/src/script/battlefield_score.rs
+++ b/crates/benilla-ui/src/script/battlefield_score.rs
@@ -1,33 +1,13 @@
-//! The battleground **scoreboard** family (decision 1972; wow-re
-//! `system/ui/scratch/battlefield-verb-family.md` §2.3, §3.7–3.9, §5.1, §5.3, §6): the eleven
-//! verbs the stock `WorldStateFrame.lua` score frame calls, over a board the app pushes.
-//!
-//! ## What is the app's and what is the VM's
-//!
-//! The wire (`MSG_PVP_LOG_DATA`) carries rows in wire order with GUIDs; the reference resolves
-//! every name through its name cache first (§6.1 — the board is not rebuilt, and the event not
-//! fired, until the last name arrives) and derives each row's **team** from the resolved race
-//! (§6.2: `0` Horde, `1` Alliance, `-1` neither). That resolution is the app's — it owns the name
-//! cache and the race tables — so the app pushes [`BattlefieldScores`] with names, teams, race and
-//! class strings already in place. The VM owns what the reference's `0x4aa200` rebuild owns: the
-//! faction filter, the sort, the filtered count, and the getters' shapes.
-//!
-//! ## The sort, and the filter that is a sort (§6.2.1, §6.3)
-//!
-//! Rows are ordered by: the filter's team first (only when a filter is set), then killing blows
-//! descending, deaths ascending, honor gained descending, name ascending. `GetNumBattlefieldScores`
-//! is the **filtered** count; `GetBattlefieldScore(index)` and `GetBattlefieldStatData` are bounded
-//! by the **wire** count — an index past the filtered count still answers a real row of the other
-//! team, exactly as the reference does, because the filter sorts rather than compacts.
-//!
-//! Every raise is the reference's own `Usage:` (§3.1); `SetBattlefieldScoreFaction` never raises.
+//! The battleground scoreboard verbs of `WorldStateFrame.lua`, over a board the app pushes with
+//! every name resolved, as the reference waits for the last name (`0x4aa580`). The filter sorts
+//! its team first rather than compacting, so an index past the filtered count answers a real row.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::number_arg;
 use super::Model;
 
-/// One scoreboard row as the app resolved it (wire order, see the module doc).
+/// One scoreboard row as the app resolved it, in wire order.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldScoreRow {
     /// The bare name, or `Name-Realm` for a cross-realm player (the reference's `%s-%s`).
@@ -36,19 +16,17 @@ pub struct BattlefieldScoreRow {
     pub honorable_kills: u32,
     pub deaths: u32,
     pub honor_gained: u32,
-    /// `0` Horde, `1` Alliance, `-1` neither — client-derived from the race, never wire data.
+    /// `0` Horde, `1` Alliance, `-1` neither, derived from the race, never sent on the wire.
     pub faction: i32,
     pub rank: i32,
     /// The race's localized name, `None` for an id the tables do not carry (a nil return).
     pub race: Option<String>,
-    /// The class's localized name, likewise.
     pub class: Option<String>,
     /// The extra-stat dwords, eight slots (the client's block), unfilled ones zero.
     pub stats: [u32; 8],
 }
 
-/// One scoreboard column header — a `WorldStateUI.dbc` `Type == 2` row for the map
-/// (`GetBattlefieldStatInfo`): text raw (no macro expansion), icon, tooltip.
+/// A column header: a `WorldStateUI.dbc` `Type == 2` row for the map, its text not expanded.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldStatColumn {
     pub text: String,
@@ -56,32 +34,30 @@ pub struct BattlefieldStatColumn {
     pub tooltip: String,
 }
 
-/// The whole board the app pushes ([`super::UiScript::set_battlefield_scores`]).
+/// The whole board the app pushes.
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct BattlefieldScores {
     pub rows: Vec<BattlefieldScoreRow>,
-    /// The `MSG_PVP_LOG_DATA` "ended" byte — gates `GetBattlefieldWinner` and `LeaveBattlefield`.
+    /// The `MSG_PVP_LOG_DATA` "ended" byte; gates the winner and `LeaveBattlefield`.
     pub ended: bool,
     /// `0` Horde, `1` Alliance; read only when `ended`.
     pub winner: u8,
     pub columns: Vec<BattlefieldStatColumn>,
 }
 
-/// The VM's half of the board: the pushed rows, the filter, and the order the filter and sort
-/// produce (indices into `rows`).
+/// The VM's half of the board: the pushed rows, the filter and the sorted order into `rows`.
 #[derive(Clone, Debug)]
 pub(crate) struct ScoreBoard {
     pub(crate) scores: BattlefieldScores,
     /// `SetBattlefieldScoreFaction`'s store: `-1` every team (the reset value), `0`, `1`.
     pub(crate) filter: i32,
     pub(crate) order: Vec<usize>,
-    /// The filtered count (§6.3) — the rows whose team equals the filter, or all with `-1`.
+    /// The filtered count (`0xb6ebc4`).
     pub(crate) filtered: usize,
 }
 
 impl Default for ScoreBoard {
-    /// The filter starts at `-1`, every team — the value the status-3 arm resets it to
-    /// (`or ecx,-1; call 0x4aa5a0`, §4.2).
+    /// The filter starts at `-1`, the value the status-3 arm resets it to (`0x4aa5a0`).
     fn default() -> Self {
         Self {
             scores: BattlefieldScores::default(),
@@ -93,7 +69,7 @@ impl Default for ScoreBoard {
 }
 
 impl ScoreBoard {
-    /// `0x4aa200`'s recount and sort (§6.2/§6.2.1), over the pushed rows.
+    /// The reference's recount and sort (`0x4aa200`).
     fn rebuild(&mut self) {
         let rows = &self.scores.rows;
         let filter = self.filter;
@@ -106,7 +82,6 @@ impl ScoreBoard {
         order.sort_by(|&a, &b| {
             let (ra, rb) = (&rows[a], &rows[b]);
             if filter != -1 && ra.faction != rb.faction {
-                // The selected team's row appears first, with no score comparison at all.
                 return (rb.faction == filter).cmp(&(ra.faction == filter));
             }
             rb.killing_blows
@@ -120,41 +95,39 @@ impl ScoreBoard {
 
     fn row(&self, index_1based: i32) -> Option<&BattlefieldScoreRow> {
         let i = usize::try_from(index_1based).ok()?.checked_sub(1)?;
-        // Bounded by the WIRE count, over the sorted order (§6.3).
+        // Bounded by the wire count (`0xb6ebc0`), not the filtered one.
         self.order.get(i).map(|&r| &self.scores.rows[r])
     }
 }
 
 impl super::UiScript {
-    /// Push the resolved board. The filter is the VM's and survives a push; the order is rebuilt.
-    /// The app fires `UPDATE_BATTLEFIELD_SCORE` itself after this, so the reference's ordering
-    /// against `UPDATE_BATTLEFIELD_STATUS` on the status-3 message holds (§4.2).
+    /// Push the resolved board; the filter survives. The app fires `UPDATE_BATTLEFIELD_SCORE`
+    /// itself, keeping the reference's order against `UPDATE_BATTLEFIELD_STATUS` on the status-3
+    /// message (`0x4aaa5a`/`0x4aab05`).
     pub fn set_battlefield_scores(&mut self, scores: BattlefieldScores) {
         let mut model = self.model_mut();
         model.battlefield_board.scores = scores;
         model.battlefield_board.rebuild();
     }
 
-    /// `GetBattlefieldInstanceRunTime()`'s answer, in ms — the app's clock against the stamp the
-    /// status-3 message set (`now − Δ₂`), pushed each frame.
+    /// `GetBattlefieldInstanceRunTime()`'s answer in ms, pushed each frame.
     pub fn set_battlefield_run_time_ms(&mut self, ms: u32) {
         self.model_mut().battlefield_run_time_ms = ms;
     }
 
-    /// `RequestBattlefieldScoreData()` calls since the last drain — the app throttles to 5000 ms
-    /// and sends `MSG_PVP_LOG_DATA` empty.
+    /// `RequestBattlefieldScoreData()` calls since the last drain.
     pub fn take_battlefield_score_requests(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().battlefield_score_requests)
     }
 
-    /// `LeaveBattlefield()` calls that passed the "ended" gate — the app sends
+    /// `LeaveBattlefield()` calls that passed the "ended" gate; the app sends
     /// `CMSG_LEAVE_BATTLEFIELD` with the active slot's map.
     pub fn take_battlefield_leave_requests(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().battlefield_leave_requests)
     }
 }
 
-/// A Lua number-ish → i32 by the client's `__ftol` (truncate), `None` for a non-number.
+/// A Lua number or numeric string to `i32`, truncated as the client's `__ftol` does.
 fn number_of(v: &Value) -> Option<i32> {
     match v {
         Value::Integer(i) => Some(*i as i32),
@@ -171,7 +144,6 @@ fn number_of(v: &Value) -> Option<i32> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `GetNumBattlefieldScores()` — the FILTERED count `[0xb6ebc4]`.
     g.set(
         "GetNumBattlefieldScores",
         lua.create_function(|lua, ()| {
@@ -180,9 +152,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldScore(index)` — nine values on every leg (§3.7): name, killingBlows,
-    // honorableKills, deaths, honorGained, faction, rank, race, class; the fail leg is
-    // `nil, 0,0,0,0,0,0, nil, nil`. Bounded by the wire count over the sorted order.
+    // Nine values on every leg, the fail leg included (`0x4ab9d0`).
     g.set(
         "GetBattlefieldScore",
         lua.create_function(|lua, index: Value| {
@@ -221,7 +191,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldWinner()` — nil until the "ended" byte, then the winner (0 Horde, 1 Alliance).
     g.set(
         "GetBattlefieldWinner",
         lua.create_function(|lua, ()| {
@@ -235,9 +204,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `SetBattlefieldScoreFaction([faction])` — never raises: a non-number means -1; only
-    // {-1, 0, 1} store, and a stored value recounts, re-sorts and fires UPDATE_BATTLEFIELD_SCORE
-    // (§3.8) — here on the deferred lane, the next dispatch.
+    // Never raises; a stored filter fires `UPDATE_BATTLEFIELD_SCORE` (`0x4abc90`), here on the
+    // next dispatch.
     g.set(
         "SetBattlefieldScoreFaction",
         lua.create_function(|lua, faction: Option<Value>| {
@@ -255,7 +223,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetNumBattlefieldStats()` — the column count, no gate.
     g.set(
         "GetNumBattlefieldStats",
         lua.create_function(|lua, ()| {
@@ -264,9 +231,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldStatInfo(index)` — three values: text (raw), icon, tooltip; three nils
-    // for a column the map has not (the reference falls into its lookup with row id 0 and
-    // finds no row).
+    // A column the map lacks answers three nils: the reference looks up row id 0 and finds none.
     g.set(
         "GetBattlefieldStatInfo",
         lua.create_function(|lua, index: Value| {
@@ -291,9 +256,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldStatData(playerIndex, statIndex)` — both required numbers; one number on
-    // every leg: the row's stat, or 0 for a bad row or a stat index outside 1..=8 (the reference
-    // admits 9 and reads one dword past its block, §3.9's anomaly — ours answers 0 there).
+    // A bad row or a stat outside 1..=8 answers 0. Deviation: the reference (`0x4abdc0`) admits 9
+    // and reads one dword past its block; we answer 0 because that read is out of bounds.
     g.set(
         "GetBattlefieldStatData",
         lua.create_function(|lua, (player, stat): (Value, Value)| {
@@ -311,8 +275,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `RequestBattlefieldScoreData()` — 0 args, 0 returns; the app sends `MSG_PVP_LOG_DATA` empty
-    // under the client's 5000 ms throttle (§5.1).
+    // The app sends an empty `MSG_PVP_LOG_DATA` under the client's 5000 ms throttle (`0x4aa170`).
     g.set(
         "RequestBattlefieldScoreData",
         lua.create_function(|lua, ()| {
@@ -322,9 +285,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `LeaveBattlefield()` — a gate, then a payload (§5.3): nothing at all until the scoreboard's
-    // "ended" byte has arrived; then `CMSG_LEAVE_BATTLEFIELD` with the active slot's map (the
-    // app's, which holds the queue).
+    // Nothing at all until the scoreboard's "ended" byte has arrived (`0x4abe66`).
     g.set(
         "LeaveBattlefield",
         lua.create_function(|lua, ()| {
@@ -336,8 +297,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBattlefieldInstanceRunTime()` — 0 args, one number: ms since the instance's stamp
-    // (`now − [0xb6ebbc]`, no sign guard; 0 with no stamp). The app keeps the clock.
+    // Ms since the status-3 stamp (`now - [0xb6ebbc]`, no sign guard, 0 with no stamp).
     g.set(
         "GetBattlefieldInstanceRunTime",
         lua.create_function(|lua, ()| {
@@ -389,8 +349,7 @@ mod tests {
         s
     }
 
-    /// The sort law (§6.2.1): killing blows descending, deaths ascending, honor descending, name;
-    /// a filter puts its team first and shrinks the count without compacting the array (§6.3).
+    /// The order of `0x4aa350`; a filter shrinks the count, not the array.
     #[test]
     fn the_board_sorts_like_the_client_and_the_filter_is_a_sort() {
         let s = board();
@@ -431,8 +390,6 @@ mod tests {
         );
     }
 
-    /// The getters' shapes: nine values with the fail leg's nils and zeros, the raises, the
-    /// column triple, the stat datum, the winner gate and the leave gate.
     #[test]
     fn the_getters_answer_the_clients_shapes() {
         let mut s = board();
diff --git a/crates/benilla-ui/src/script/bind_confirm.rs b/crates/benilla-ui/src/script/bind_confirm.rs
index 79bbd114..ee5eafe2 100644
--- a/crates/benilla-ui/src/script/bind_confirm.rs
+++ b/crates/benilla-ui/src/script/bind_confirm.rs
@@ -1,82 +1,47 @@
-//! The **item soulbind confirmations** other than the loot one — the Era API surface behind
-//! `EQUIP_BIND` / `AUTOEQUIP_BIND` / `USE_BIND` (decision 1750). Three globals, no snapshot: the
-//! question arrives as an event and the answer goes straight back out, exactly like
-//! [`super::binder`] and [`super::duel`].
-//!
-//! ## What the three verbs mean, at the 1.12 bytes
-//!
-//! `EquipPendingItem(index)` `0x4898f0` and `CancelPendingEquip(index)` `0x489960` both delegate to
-//! `0x5e1be0(index, accept)`. **`index` is not a slot** — it is a 0-based index into the client's
-//! own growable pending-equip array (capacity `0xc4c290`, count `0xc4c294`, base `0xc4c298`, stride
-//! `0x20`), which is also what `EQUIP_BIND_CONFIRM`'s and `AUTOEQUIP_BIND_CONFIRM`'s `arg1` carries.
-//! `UIParent.lua:324-339` hangs it on `dialog.data` and the entries hand it straight back, so the
-//! number is opaque on both sides — which is why benilla keeps the reference's index space here
-//! instead of translating it the way the loot arm's row number is translated (1744).
-//!
-//! **Accept is a re-issue of the original action with a suppress flag, not a confirm packet** —
-//! there is no `CMSG_CONFIRM_*` in 1.12. Cancel sends nothing at all; it only releases the item
-//! locks the deferred action took (`UnlockItem 0x495420`).
-//!
-//! `ConfirmBindOnUse()` `0x48d770` is the use arm's answer and takes **no** argument, because that
-//! arm's pending state is not the array: it is two globals the fire site stamps (the item guid at
-//! `0xc4c240`, the target guid at `0xc4c1d0`), and the accept is `CGItem::Use(&target, suppress=1)`.
-//! `USE_BIND_CONFIRM` carries no arguments either, and the reference ships **no** cancel binding for
-//! it — declining simply drops the question.
-//!
-//! All three decisions are **client-local**: the client reads the cached item template's `bonding`
-//! and defers its own send. No packet raises any of them (VERIFIED, wow-re
-//! `system/object-layer/scratch/bind-confirm-law.md`).
-//!
-//! The app owns the pending records, so this module holds only the intents.
+//! The soulbind confirmations other than loot's: `EQUIP_BIND`, `AUTOEQUIP_BIND` and `USE_BIND`.
+//! They are client-local: the client reads the cached template's bonding and defers its own send,
+//! and an accept re-issues that action with a suppress flag, as 1.12 has no confirm packet. The
+//! app owns the pending records; this module holds only the intents.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// One answer to a pending-equip question: the 0-based array index the event handed out, and
-/// whether the player accepted.
+/// One answer to a pending-equip question.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct PendingEquipAnswer {
-    /// The index `EQUIP_BIND_CONFIRM`/`AUTOEQUIP_BIND_CONFIRM` carried out on `arg1`.
+    /// The event's `arg1`, not a slot: a 0-based index into the reference's pending-equip array
+    /// (`0xc4c298`, stride `0x20`), kept untranslated because Lua only hands it back.
     pub index: u32,
-    /// `true` from `EquipPendingItem` (re-issue the action), `false` from `CancelPendingEquip`
-    /// (release the locks, send nothing).
+    /// Accept re-issues the action; cancel sends nothing and only releases the item locks
+    /// (`0x495420`).
     pub accept: bool,
 }
 
 impl super::UiScript {
-    /// Drain the `EquipPendingItem`/`CancelPendingEquip` answers queued since the last drain, in
-    /// call order. An index the app is not holding a record for is the app's to ignore — the
-    /// reference's `0x5e1be0` bounds-checks against the live element count and returns.
+    /// The equip answers in call order. The app ignores an index it holds no record for, as the
+    /// reference's `0x5e1be0` bounds-checks it and returns.
     pub fn take_pending_equip_answers(&mut self) -> Vec<PendingEquipAnswer> {
         std::mem::take(&mut self.model_mut().pending_equip_answers)
     }
 
-    /// Drain the `ConfirmBindOnUse()` calls queued since the last drain — a count, because the verb
-    /// has no payload ([`super::UiScript::take_binder_confirms`]'s shape and its reason).
+    /// `ConfirmBindOnUse()` calls since the last drain.
     pub fn take_bind_on_use_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().bind_on_use_confirms)
     }
 
-    /// The client's item-usable predicate `0x5ea930` for an item known by entry — one of the two
-    /// non-trivial conjuncts on the equip arms' deferral (an item the player *cannot* equip is
-    /// never asked about, because the action it would confirm is one the server would refuse).
-    ///
-    /// Public because the deferral is decided app-side, where the send is: the engine holds the
-    /// templates and the player's requirement state, so the question has to be asked here.
-    /// Same conventions as every other caller ([`super::item_stats::item_usable_by_id`]): entry `0`
-    /// and an unanswered template are both usable.
+    /// The client's item-usable predicate (`0x5ea930`), which the app's equip deferral asks: an
+    /// item the player cannot equip is never asked about. Entry `0` and an unanswered template
+    /// read usable.
     pub fn item_usable(&self, item_id: u32) -> bool {
         super::item_stats::item_usable_by_id(&self.model_ref(), item_id)
     }
 }
 
-/// Register the three globals (the style [`super::binder`] registers its two).
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // EquipPendingItem(index) — `StaticPopupDialogs["EQUIP_BIND"].OnAccept` and its AUTOEQUIP twin
-    // (`StaticPopup.lua:612-647`). Re-issues the deferred action; the app owns what that action was.
+    // `0x4898f0`, the `OnAccept` of `EQUIP_BIND` and `AUTOEQUIP_BIND` (`StaticPopup.lua:612-647`).
     g.set(
         "EquipPendingItem",
         lua.create_function(|lua, index: u32| {
@@ -89,10 +54,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelPendingEquip(index) — the same two entries' `OnCancel` AND their `OnHide`, which is not
-    // redundancy: `exclusive = 1` means a second bind question hides the standing dialog, and the
-    // reference relies on that `OnHide` to cancel the record it supersedes. A superseded pending
-    // equip is CANCELLED, never silently overwritten — without it the old item's locks leak.
+    // `0x489960`, their `OnCancel` and also their `OnHide`: a second bind question hides the
+    // standing dialog (`exclusive = 1`), and that cancel releases the superseded item's locks.
     g.set(
         "CancelPendingEquip",
         lua.create_function(|lua, index: u32| {
@@ -105,9 +68,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmBindOnUse() — `StaticPopupDialogs["USE_BIND"].OnAccept` (`StaticPopup.lua:648-658`).
-    // No argument and no cancel twin: the use arm's pending state is a single client global, and
-    // declining just drops it.
+    // `0x48d770`, `USE_BIND`'s `OnAccept`, with no argument and no cancel: the use arm's pending
+    // state is two globals (item `0xc4c240`, target `0xc4c1d0`), and declining drops it.
     g.set(
         "ConfirmBindOnUse",
         lua.create_function(|lua, ()| {
@@ -124,9 +86,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// The two equip verbs share one queue and are distinguished only by their answer — the app
-    /// needs the call ORDER as well as the verdicts, because a supersede is a cancel of one record
-    /// arriving between two others.
+    /// Order matters: a supersede is a cancel of one record arriving between two others.
     #[test]
     fn the_equip_answers_queue_in_call_order_with_their_verdicts() {
         let mut s = UiScript::new().unwrap();
@@ -143,8 +103,6 @@ mod tests {
         assert!(s.take_pending_equip_answers().is_empty(), "drained");
     }
 
-    /// `ConfirmBindOnUse` is a count, like `ConfirmBinder`: the verb carries no payload because the
-    /// pending item is the app's.
     #[test]
     fn confirm_bind_on_use_counts() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/binder.rs b/crates/benilla-ui/src/script/binder.rs
index f5b56083..2487e217 100644
--- a/crates/benilla-ui/src/script/binder.rs
+++ b/crates/benilla-ui/src/script/binder.rs
@@ -1,31 +1,19 @@
-//! The innkeeper-bind **Era API surface** (decision 1331) — two globals, no snapshot.
-//!
-//! These are the whole Lua side of setting a hearthstone, and they exist because the reference's
-//! `CONFIRM_BINDER` dialog is written against exactly them (`StaticPopup.lua:1308-1322`):
-//! `OnAccept` calls [`ConfirmBinder`], and `OnUpdate` hides the dialog the moment
-//! [`CheckBinderDist`] goes false. Both are engine bindings in 1.12 (`reference/1.12-globals.tsv`
-//! lists `ConfirmBinder` and `CheckBinderDist` as `function`/`engine`), and there are no others in
-//! the family — the question itself arrives as the `CONFIRM_BINDER` event's argument, so there is
-//! nothing to read back, exactly like [`super::duel`].
-//!
-//! The app owns the innkeeper's guid ([`crate::script::UiScript::set_binder_pending`]'s writer),
-//! which is why `ConfirmBinder()` takes no arguments and queues only a count.
+//! `ConfirmBinder` and `CheckBinderDist`, the engine globals the `CONFIRM_BINDER` dialog calls
+//! (`StaticPopup.lua:1321-1335`): Accept binds, and the dialog hides once the distance check
+//! fails. The question arrives as the event's argument, so there is nothing to read back.
 
 use mlua::Lua;
 
 use super::Model;
 
 impl super::UiScript {
-    /// Drain the `ConfirmBinder()` calls queued since the last drain — each one is a
-    /// `CMSG_BINDER_ACTIVATE`. [`super::UiScript::take_played_time_asks`]'s shape, and a count for
-    /// the same reason: the intent has no payload of its own.
+    /// `ConfirmBinder()` calls since the last drain, each a `CMSG_BINDER_ACTIVATE`; a count, since
+    /// the app holds the innkeeper's guid.
     pub fn take_binder_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().binder_confirms)
     }
 
-    /// Push whether an innkeeper's bind question is live and still in range — the host's half of
-    /// `CheckBinderDist()`. Idempotent; `false` covers both "no question pending" and "you walked
-    /// away", which is all the dialog's OnUpdate needs to decide to hide.
+    /// Push whether a bind question is pending with the innkeeper still in range.
     pub fn set_binder_pending(&mut self, pending: bool) {
         let mut model = self.model_mut();
         if model.binder_pending != pending {
@@ -34,12 +22,11 @@ impl super::UiScript {
     }
 }
 
-/// Register the two binder globals (the style [`super::duel`] registers its four).
+/// Register the two binder globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ConfirmBinder() — the CONFIRM_BINDER dialog's Accept. The one call in the client that binds
-    // a hearthstone: everything before it is a question.
+    // `ConfirmBinder()`: the dialog's Accept, the one call that binds a hearthstone.
     g.set(
         "ConfirmBinder",
         lua.create_function(|lua, ()| {
@@ -49,7 +36,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CheckBinderDist() — polled from the dialog's OnUpdate; false hides it.
+    // `CheckBinderDist()`, polled by the dialog's OnUpdate. This answers a boolean; the
+    // reference (`0x48d210`) answers 1 or nil.
     g.set(
         "CheckBinderDist",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/binding_abi.rs b/crates/benilla-ui/src/script/binding_abi.rs
index 68b9c801..9b76b6b6 100644
--- a/crates/benilla-ui/src/script/binding_abi.rs
+++ b/crates/benilla-ui/src/script/binding_abi.rs
@@ -1,62 +1,28 @@
-//! The **registered-binding argument/error ABI** — the marshalling contract every one of build
-//! 5875's ~700 registered Lua C-bindings opens with, in one place because getting it wrong is
-//! wrong 700 times (wow-re `ui/scratch/binding-arg-error-contract.md`, §5-cross-checked with
-//! orchestrator byte-arbitration).
+//! The argument and error ABI every registered Lua C-binding of the 1.12 client opens with.
 //!
-//! ## The three helpers the reference uses, and what they accept
+//! The reference's helpers: `is-number` (`0x6f34d0`) accepts tag 3 or a string coerced through
+//! `0x6f7c20`; `is-number-or-string` (`0x6f3510`) accepts tag 3 or 4; `tonumber` (`0x6f3620`)
+//! feeds `0x40a2b0`, a double-to-int32 cast that truncates toward zero (the x87 rounding control
+//! set to chop), so -2.9 is -2.
 //!
-//! | addr | contract |
-//! |---|---|
-//! | `0x6f34d0` | `is-number(L, idx)` — tag 3, **or** a string coerced through `0x6f7c20` |
-//! | `0x6f3510` | `is-number-**or**-string(L, idx)` — strictly wider: tag 3 or tag 4 |
-//! | `0x6f3620` → `0x40a2b0` | `tonumber` then `double → int32`, **truncating toward zero** |
+//! A bad argument raises: `0x6f4940` is `luaL_error`, which never returns (it ends in `longjmp` or
+//! `exit(1)` through `0x6f4440`, `0x6fc780`, `0x6f5d80`), so the `xor eax,eax; ret` after it is
+//! unreachable and the caller's statement is abandoned. An empty answer is settled per binding:
 //!
-//! `0x40a2b0` sets the x87 rounding control to chop (`or ah,0xc`) before `fistp`, so it is a C
-//! cast and **not** `floor`: `−2.9 → −2`. [`number_arg`] reproduces that (Rust's `as` on a float
-//! truncates toward zero as well), and hands back the low dword the bindings actually consume.
-//!
-//! ## The headline: the `Usage:` arm RAISES
-//!
-//! `0x6f4940` is `luaL_error`, and it **does not return**: `luaL_where` + `lua_pushvfstring` +
-//! `lua_concat` + `lua_error`, whose own chain (`0x6f4440` → `0x6fc780` → `0x6f5d80`) ends in a
-//! CRT `longjmp` or `exit(1)` on both legs. The `xor eax,eax; ret` that MSVC emits after every
-//! such call inside a binding is **unreachable boilerplate**, not a "returns zero values" arm — a
-//! reading five committed wow-re notes had inverted, corrected at the bytes on 2026-08-11.
-//!
-//! So a binding's bad-argument path **abandons the caller's statement** and unwinds to the
-//! enclosing protected call. It returns neither `nil` nor zero values, and a client that answers
-//! `nil` there keeps executing a statement the real client never finishes.
-//!
-//! Stated as the negative, because it is as load-bearing as the positive: the **zero Lua values**
-//! outcome is real only where a binding reaches `xor eax,eax; ret` *without* passing through
-//! `0x6f4940` — `GetDefaultLanguage`'s four object/bounds failure edges are this repo's one
-//! example ([`super::session`]). Those arms genuinely return nothing.
-//!
-//! ## The three shapes an "empty answer" can take
-//!
-//! Settled per binding, never generalised:
-//!
-//! 1. **push nil**, one Lua value (`UnitAffectingCombat` on a false/unresolved unit,
-//!    `GetActionText` on a non-macro slot, `UnitInRaid` on a miss).
-//! 2. **zero Lua values** — distinct from `nil` for anything that counts the return list (5.0's
-//!    `arg.n`, or [`crate::script::UiScript::arity`] on the host side) and for a multiple
-//!    assignment, identical to it for a single-value caller (`GetDefaultLanguage`'s failure edges).
-//! 3. **raise** — the statement is abandoned.
+//! 1. push nil, one value (`UnitAffectingCombat` on a unit out of combat, or a token naming none);
+//! 2. zero values, distinct from nil to anything counting the returns (`arg.n`), reached only by a
+//!    `xor eax,eax; ret` that skips `0x6f4940` (`GetDefaultLanguage`'s failure edges);
+//! 3. raise.
 
 use mlua::{Lua, Value};
 
-/// `is-number` (`0x6f34d0`) → `tonumber` (`0x6f3620`) → `double → int32` truncating toward zero
-/// (`0x40a2b0`), with the binding's own `Usage:` string on the failure edge.
+/// Shape A: `is-number` (`0x6f34d0`), `tonumber` (`0x6f3620`), then the truncating `0x40a2b0`,
+/// raising the binding's `Usage:` on failure. A missing argument fails like a wrong-typed one
+/// (`0x6f3410` returns NULL past `L->top`); a numeric string passes. `0x40a2b0` stores a qword but
+/// the bindings consume only the low dword, hence `i32`.
 ///
-/// A **missing** argument fails the same test a wrong-typed one does — `0x6f3410` returns NULL
-/// past `L->top`, which `0x6f34d0` reports as "not a number" — so `f()` and `f({})` take the same
-/// raise. A numeric *string* passes: Lua 5.1's `lua_isnumber` coerces, and so does
-/// [`Lua::coerce_number`].
-///
-/// The `i32` is deliberate: `0x40a2b0` stores a qword but every binding here consumes only `eax`,
-/// the low dword. Rust's `i64 as i32` truncates the same way. (Past ±2^63 the two diverge — the
-/// x87 stores the "integer indefinite" pattern where Rust saturates — which no caller can reach
-/// and no consumer could tell apart, since both answers are garbage.)
+/// Deviation: past ±2^63 Rust saturates where the x87 stores its integer-indefinite pattern,
+/// because no real argument reaches that range.
 pub(crate) fn number_arg(lua: &Lua, v: Value, usage: &'static str) -> mlua::Result<i32> {
     match lua.coerce_number(v)? {
         Some(n) => Ok(n as i64 as i32),
@@ -64,87 +30,41 @@ pub(crate) fn number_arg(lua: &Lua, v: Value, usage: &'static str) -> mlua::Resu
     }
 }
 
-/// **Shape D** — a `lua_isnumber`-gated *flag* whose failure edge does NOT raise: the local keeps
-/// the zero it was seeded with and the binding carries on. `SetInventoryItem`'s optional third
-/// argument, the one the image's own usage string (`0x8552dc`) calls `nameOnly`, is this repo's
-/// example, and it is stricter than the other shapes on one point: after the
-/// `is-number(L, idx)` guard (`0x6f34d0`, so a numeric STRING passes it) the value is compared
-/// `> 0.0` **strictly** — `0x53303f fcomp qword [0x802970]` against a literal `0.0`, then
-/// `0x533047 test ah,0x41; 0x53304a jne` onto the block that keeps the zero. Masked AH is `0x00`
-/// only for greater-than; less (`0x01`), equal (`0x40`) and unordered (`0x41`) all jump. So `0`,
-/// a negative and NaN are false, and `1`, `0.5` and `"1"` are true.
-///
-/// The distinction from [`number_arg`] is the whole point: shape A *raises* `Usage:` on a
-/// non-number, shape D shrugs. Which shape an argument takes is per binding — wow-re
-/// `ui/scratch/tooltip-nameonly-p4-census.md` §3 for this one.
+/// Shape D: an `is-number`-gated flag whose failure keeps its zero instead of raising. The value
+/// must be strictly `> 0.0` (`0x53303f`), so 0, a negative and NaN are false and `0.5` or `"1"`
+/// true; `SetInventoryItem`'s `nameOnly` is one.
 pub(crate) fn positive_number_flag(lua: &Lua, v: Value) -> mlua::Result<bool> {
     Ok(lua.coerce_number(v)?.is_some_and(|n| n > 0.0))
 }
 
-/// **Shape C** — a numeric argument the binding reads with a bare `lua_tonumber 0x6f3620` and NO
-/// `lua_isnumber` guard, so it cannot fail: absent, `nil`, `true`, a table, a function, or an
-/// unparseable string all land on **`0.0`** and the binding completes.
-///
-/// This is the counterpart to [`number_arg`] (shape A, which raises `Usage:`), and which shape a
-/// given argument takes is **per binding, not a global law** — wow-re
-/// `scratch/numeric-arg-coercion-law.md`, which censused all 408 widget-registrar entries and
-/// found 110 gated positions against 64 ungated ones. The clustering is the useful part: C is the
-/// colour/coordinate tuples (`Set*Color`'s r/g/b, `SetTexCoord`, `SetPosition`), A is the single
-/// scalar setters (`SetAlpha`, `SetWidth`, `SetValue`, `SetID`). Do not reach for this one because
-/// an argument "looks optional" — check the census.
-///
-/// One instruction settles why nil and a table are not distinguished: `0x6f7c32 cmp ecx,4;
-/// jne 0x6f7c6a` refuses every non-string tag without inspecting the value.
+/// Shape C: a bare `lua_tonumber` (`0x6f3620`) with no `is-number` guard, so it cannot fail:
+/// anything but a number or numeric string reads as 0.0. The reference uses it for colour and
+/// coordinate tuples (`Set*Color`, `SetTexCoord`, `SetPosition`) and shape A for scalar setters
+/// (`SetAlpha`, `SetWidth`, `SetValue`, `SetID`); which applies is per binding.
 pub(crate) fn coerced_number(lua: &Lua, v: Option<Value>) -> f64 {
     v.and_then(|v| lua.coerce_number(v).ok().flatten())
         .unwrap_or(0.0)
 }
 
-/// `is-number-or-string` (`0x6f3510`) → `arg-as-C-string` (`0x6f3690`), with the binding's own
-/// `Usage:` string on the failure edge.
-///
-/// Strictly wider than [`number_arg`]'s guard: a *number* is accepted and stringified, which is
-/// why `UnitAffectingCombat(5)` does not raise in the reference — it resolves the token `"5"`,
-/// finds nothing, and answers `nil`. Everything else (nil, boolean, table, function) raises.
+/// `is-number-or-string` (`0x6f3510`) then `0x6f3690`, raising the binding's `Usage:` on failure:
+/// a number is stringified (`UnitAffectingCombat(5)` passes here, then the unit resolver raises
+/// `Unknown unit name` for `"5"`, `0x515c14`), and nil, a boolean, a table or a function raises.
 pub(crate) fn string_arg(lua: &Lua, v: Value, usage: &'static str) -> mlua::Result<String> {
     match lua.coerce_string(v)? {
-        // Lossy, per decision 1193: a Lua 5.0 string is BYTES and the reference reads it as
-        // bytes, so an argument that is not valid UTF-8 costs a glyph here — it does not cost
-        // the call. `to_str()` used to raise, which turned one stray byte in one cp1252 addon's
-        // literal into a dead handler (2138).
+        // Lossy: a Lua string is bytes, so invalid UTF-8 costs a glyph, never the call.
         Some(s) => Ok(s.to_string_lossy()),
         None => Err(mlua::Error::RuntimeError(usage.into())),
     }
 }
 
-/// **[`string_arg`]'s shape-C partner**: coerce like the reference, and treat everything else as
-/// **absent** rather than raising.
-///
-/// The pair is 1717's rule applied to string positions — *which* shape a position takes is settled
-/// per binding, never generalised — and the model-pane and region constructors are the two ends of
-/// it, verified together (wow-re `ui/scratch/xml-template-name-lookup.md` §5.2):
-///
-/// | position | fetch | a table there |
-/// |---|---|---|
-/// | `Model:SetModel` arg 1 | `0x6f3510` → `0x6f3690`, result **tested** | **raises** ([`string_arg`]) |
-/// | `CreateFontString`/`CreateTexture` `name`, `layer` | `0x6f3510` → `0x6f3690`, result **not** tested | absent — this fn |
-/// | `CreateFrame` `name`, `inherits` | `0x6f3690` **unguarded** | absent — this fn |
-///
-/// **The discriminator is not the argument's type; it is whether the binding TESTS its parser's
-/// return.** That is the sentence `numeric-arg-coercion-law.md` §6 had wrong ("an unrecognised
-/// string argument raises"), refuted by this round.
-///
-/// A **number** is accepted and stringified, exactly as `lua_tostring` coerces it — so
-/// `CreateFrame("Frame", 5)` names the frame `"5"`. Callers that must *not* coerce a number (the
-/// `lua_type(L,idx) == LUA_TSTRING` gate `CreateTexture`/`CreateFontString` put on their **fourth**
-/// argument, and only there) test the tag themselves before calling this.
+/// [`string_arg`]'s shape-C partner, for a binding that does not test the parse: a string or a
+/// number is coerced (`CreateFrame("Frame", 5)` names the frame `"5"`), anything else is absent.
+/// `CreateFrame`'s `name` and `inherits` and `CreateFontString`/`CreateTexture`'s `name` and
+/// `layer` take this; `Model:SetModel`, which tests it, takes [`string_arg`]. A caller that must
+/// refuse a number (the fourth argument of `CreateTexture`/`CreateFontString`) checks the tag.
 pub(crate) fn optional_string(lua: &Lua, v: &Value) -> Option<String> {
     match v {
-        // Lossy, per decision 1193 and for the same reason as [`string_arg`] — with a sharper
-        // symptom, because this one's failure was SILENT: `to_str().ok()` folded a string that
-        // was not valid UTF-8 into `None`, which every caller here reads as *the argument was
-        // not there*. `AddMessage` printed nothing, `CreateFrame` produced an unnamed frame, and
-        // nothing anywhere said why (2138).
+        // Lossy: invalid UTF-8 must not read as an absent argument.
         Value::String(_) | Value::Number(_) | Value::Integer(_) => lua
             .coerce_string(v.clone())
             .ok()
@@ -154,21 +74,9 @@ pub(crate) fn optional_string(lua: &Lua, v: &Value) -> Option<String> {
     }
 }
 
-/// **A free-text argument — the player-visible kind — as the reference takes it** (decision 2138).
-///
-/// The text sinks (`FontString`/`Button`/`EditBox`/`SimpleHTML` `SetText`, `SetFormattedText`,
-/// `EditBox:Insert`) took their argument as mlua's `Option<String>`, whose `FromLua` demands valid
-/// UTF-8 and **raises** otherwise. Decision 1193 settled that a UI source file is bytes and that
-/// "the right place to turn bytes into text is the boundary that actually requires text… A stray
-/// byte should cost one glyph, not the file" — and then these boundaries cost the whole call.
-/// `strsub` is byte-indexed (1193 keeps it that way deliberately), so *any* addon slicing
-/// non-ASCII text hands a sink a broken sequence, and a cp1252 literal is a broken sequence to
-/// begin with.
-///
-/// This is `Option<String>`'s conversion with exactly one arm changed: a **string** becomes its
-/// lossy text. Every other type behaves as before — absent and `nil` are `None`, a number
-/// coerces, a table or a function raises mlua's own conversion error — so the raise/absent split
-/// each binding already had (§ [`optional_string`]'s table) is untouched.
+/// A free-text argument for the text sinks (`SetText`, `SetFormattedText`, `EditBox:Insert`):
+/// `Option<String>`'s conversion, except that a string that is not valid UTF-8 becomes lossy text
+/// instead of raising, as the reference takes bytes.
 pub(crate) fn text_arg(lua: &Lua, v: Option<Value>) -> mlua::Result<Option<String>> {
     match v {
         None | Some(Value::Nil) => Ok(None),
@@ -177,65 +85,14 @@ pub(crate) fn text_arg(lua: &Lua, v: Option<Value>) -> mlua::Result<Option<Strin
     }
 }
 
-/// `GetBoolOrDefault` (`0x6f1c10`) — the reference's **boolean argument** coercion, which is *not*
-/// Lua truthiness and gets three arms backwards from the obvious reading. Byte-VERIFIED: wow-re
-/// `system/ui/scratch/action-bar-toggles.md` §2.1 re-derives the whole jump table at `0x6f1ce8`
-/// (`ui.md`, `tooltip-content-law.md` and `object-layer/scratch/helm-cloak-hide.md` cite the same
-/// helper).
+/// Lua's number-to-string as the 1.12 client compiles it: MSVC's `sprintf("%.14g")`
+/// (`luaV_tostring` `0x6f7c80`, format `0x871960`). `EditBox:SetNumber` (`0x798690`) formats
+/// through it too, being byte-identical to `SetText` (`0x7984c0`). The exponent has at least three
+/// digits: `1e20` prints `1e+020`.
 ///
-/// `v` is `None` for an **absent** argument (`LUA_TNONE` = −1, unsigned-compares above the table's
-/// bound and takes the default arm). mlua collapses "missing" into `Value::Nil` for a plain
-/// `Value` parameter, and the two are *different* here, so a binding whose default is `true` must
-/// take its argument as a `MultiValue` to tell them apart.
-///
-/// | Lua type | result |
-/// |---|---|
-/// | absent (`None`) | `default` |
-/// | `nil` | **false** |
-/// | boolean | itself |
-/// | lightuserdata | `default` |
-/// | number | truncate toward zero (`0x40a2b0`), then `!= 0` |
-/// | string | the table below |
-/// | table / function / userdata / thread | `default` |
-///
-/// The **string** arm is the one that bites. It does not parse the number; it dispatches on the
-/// **first byte** through the 0x4a-entry remap table at `0x6f1d08` (indexed `byte − 0x30`,
-/// *signed*, so anything outside `'0'..='y'` — an empty string's terminator included — falls to the
-/// keyword arm):
-///
-/// - first byte `'0' 'F' 'N' 'f' 'n'` → **false**
-/// - first byte `'1'..='9' 'T' 'Y' 't' 'y'` → **true**
-/// - anything else → whole-string, case-insensitive (`SStrCmpI 0x64a4c0`): `"off"`/`"disabled"` →
-///   false, `"on"`/`"enabled"` → true, and **anything unrecognised takes the `default`**
-///
-/// So `"0"` is FALSE where Lua truthiness says true (in Lua every string is truthy), which is
-/// load-bearing rather than pedantic: 1.12's own Interface panel hands its option bindings the
-/// *strings* `"0"`/`"1"`, and a re-implementation wired to `lua_toboolean` inverts every
-/// string-valued option in the game. Equally, `"0.5"` and `"-1"` are decided by their first byte
-/// alone — false and `default` — never by their numeric value.
-/// Lua 5.0's own number→string rule as the 1.12 client compiles it: `sprintf("%.14g")`
-/// (`luaV_tostring 0x6f7c80`, format string `0x871960`). Decision 1831.
-///
-/// This is the whole of `EditBox:SetNumber`'s formatting, because **`SetNumber 0x798690` and
-/// `SetText 0x7984c0` are byte-identical functions** — 245 bytes each, zero differences after
-/// masking rel32 and absolute-VA operands, differing only in which usage string they carry. The
-/// numeric verb does no numeric work of its own; the shared `lua_tostring` marshalling does it all.
-///
-/// The rule, and the three places it is not Rust's `{}`:
-///
-/// - **14 significant digits**, then trailing zeros and a bare trailing `.` are dropped.
-/// - **Exponential iff `exp < -4 || exp >= 14`** — the C `%g` switch.
-/// - **A three-digit exponent, always.** `1e20` prints `1e+020`, not `1e+20`: the exponent is
-///   copied from the literal template `"e+000"` and digits are written onto it. This is MSVC's
-///   `%g`, not C99's, and it is the single most surprising thing here.
-///
-/// **What this deliberately does NOT reproduce**, stated so it is not mistaken for an oversight:
-/// the reference's printf is not correctly rounded. It generates 17 digits half-up and then
-/// re-rounds *that string* to 14, also half-up and with no sticky bit, so it disagrees with a
-/// correctly-rounded formatter on roughly 0.05% of doubles (`-0.11594045739607` where a correct
-/// one gives `…606`). Reproducing that needs the two-stage decimal path, not a format string, and
-/// no consumer we have is sensitive to the fourteenth digit. If one ever is, this is the note that
-/// says where to look.
+/// Deviation: the result is correctly rounded, where the reference rounds to 17 digits half-up and
+/// then again to 14, differing in the last digit on about 0.05% of doubles, because no consumer
+/// reads that digit.
 pub(crate) fn lua_number_text(v: f64) -> String {
     if v.is_nan() {
         // MSVC's own spellings, which are not "NaN".
@@ -273,8 +130,7 @@ pub(crate) fn lua_number_text(v: f64) -> String {
         let (m, _) = mantissa.split_once('e').unwrap_or((mantissa.as_str(), "0"));
         let m = trim_g(m);
         let sign = if exp < 0 { '-' } else { '+' };
-        // Three digits minimum, and MORE if the exponent needs them — the template is padded,
-        // never truncated.
+        // At least three exponent digits, more when needed.
         format!("{m}e{sign}{:03}", exp.abs())
     } else {
         let decimals = (SIG - 1 - exp).max(0) as usize;
@@ -290,6 +146,19 @@ fn trim_g(s: &str) -> &str {
     s.trim_end_matches('0').trim_end_matches('.')
 }
 
+/// `GetBoolOrDefault` (`0x6f1c10`, jump table `0x6f1ce8`), the reference's boolean argument
+/// coercion, which is not Lua truthiness:
+///
+/// - absent (`None`, `LUA_TNONE`) takes `default`, but nil is false; a binding whose default is
+///   true takes a `MultiValue`, since mlua turns a missing argument into nil
+/// - a boolean is itself; a number truncates toward zero (`0x40a2b0`), then `!= 0`
+/// - a string goes by its first byte, through the remap table at `0x6f1d08`: `'0' 'F' 'N' 'f' 'n'`
+///   false, `'1'..='9' 'T' 'Y' 't' 'y'` true; any other is compared whole, case-insensitively
+///   (`0x64a4c0`): `"off"`/`"disabled"` false, `"on"`/`"enabled"` true, anything else `default`
+/// - lightuserdata, a table, function, userdata or thread takes `default`
+///
+/// So `"0"` is false and `"0.5"` goes by its first byte: the Interface panel passes its options
+/// the strings `"0"` and `"1"`.
 pub(crate) fn bool_or_default(v: Option<&Value>, default: bool) -> bool {
     let Some(v) = v else {
         return default; // LUA_TNONE
@@ -298,9 +167,7 @@ pub(crate) fn bool_or_default(v: Option<&Value>, default: bool) -> bool {
         Value::Nil => false,
         Value::Boolean(b) => *b,
         Value::LightUserData(_) => default,
-        // `lua_tonumber` then `0x40a2b0`, whose RC = chop makes it a C cast; the caller tests the
-        // low dword only, which is why the double round-trips through `i64 as i32` (see
-        // [`number_arg`]).
+        // Truncated like `0x40a2b0`, testing only the low dword.
         Value::Integer(i) => (*i as i32) != 0,
         Value::Number(n) => (*n as i64 as i32) != 0,
         Value::String(s) => {
@@ -308,8 +175,8 @@ pub(crate) fn bool_or_default(v: Option<&Value>, default: bool) -> bool {
             match bytes.first() {
                 Some(b'0' | b'F' | b'N' | b'f' | b'n') => false,
                 Some(b'1'..=b'9' | b'T' | b'Y' | b't' | b'y') => true,
-                // The keyword arm — and the fall-through for every byte the remap table cannot
-                // index, which is why an empty string lands here too.
+                // The keyword arm, also reached by every byte the remap table cannot index (and
+                // by an empty string).
                 _ => {
                     if bytes.eq_ignore_ascii_case(b"off") || bytes.eq_ignore_ascii_case(b"disabled")
                     {
@@ -328,69 +195,13 @@ pub(crate) fn bool_or_default(v: Option<&Value>, default: bool) -> bool {
     }
 }
 
-/// **The 1.12 predicate return** — `1` for true, `nil` for false, and never a Lua boolean.
-///
-/// The reference client has essentially no boolean-returning query. Across the 1503 rows
-/// `reference/1.12-shapes.tsv` marks `kinds_conf = agree`, exactly two slots in the whole binding
-/// surface are `boolean`: `IsPetAttackActive` (which really does call `lua_pushboolean 0x6f39f0`,
-/// noted in [`super::pet`]) and Lua's own `rawequal`. Every other `Is*`, `Can*`, `Has*` and every
-/// predicate slot of a multi-value answer is `(nil) | (number)`.
-///
-/// **The difference is invisible to `if x then` and decisive to everything else** — `x == 1`,
-/// `x == nil`, `tostring(x)`, arithmetic, a table key, a value round-tripped through a saved
-/// variable. That is why it survived so long: the transcribed FrameXML reads every one of these
-/// with a plain `if`, so `true` and `1` were interchangeable for as long as *we* wrote the callers.
-/// Real 1.12 addons are not our callers — `ColorPickerPlus.lua:121` writes
-/// `if IsShiftKeyDown() == 1 then`, and reads a `true` as "not held" (decision 2118).
-///
-/// Enforced, not remembered: `ui_script::shape_gate::no_query_binding_answers_a_lua_boolean`
-/// probes the whole registered query surface and fails on any Lua boolean.
-///
-/// ## What `predicate` said, folded in (2142)
-///
-/// This helper had a byte-identical TWIN sixty lines up the same file — `predicate`, 49 call
-/// sites to this one's 77 — carrying its own half of the evidence. 2118 consolidated five *local*
-/// copies into this one and left that one standing, which is the same drift one level up: a house
-/// rule with two homes gets re-derived at each new file, and the file that picks the wrong one is
-/// invisible against the others. The twin is gone; everything it recorded is below.
-///
-///
-/// The return-side counterpart to [`bool_or_default`], and the same class of fact: 1.12's widget
-/// predicates (1830) and its 29 `Unit*` predicates (2043) do not push booleans. `lua_pushboolean
-/// 0x6f39f0` has seven call sites in the whole image; **not one is inside a widget registrar body,
-/// and no binding in the 83-entry unit table at `0x850438` calls it at all** — those predicates go
-/// through `lua_pushnumber 0x6f3810` (the constant double `1.0`) / `lua_pushnil 0x6f37f0`, exactly
-/// one value at every live `ret`.
-///
-/// **Not a whole-image absolute, and 2048 corrects 2043 for saying so.** `lua_pushboolean` is real
-/// and one of its seven callers *is* a registered FrameScript binding: `IsPetAttackActive
-/// 0x4be0e0` answers a genuine Lua `true`/`false` and **never nil** (ours matches — see
-/// [`super::pet`]). The other six are `rawequal`/`pcall`/`xpcall` in the base table `0x811e28` and
-/// two unregistered helpers. So "1.12 has no `lua_pushboolean`" is false; "these two predicate
-/// families never reach it" is what the bytes support, and is what this helper encodes.
-///
-/// **The false leg is settled per body, never inherited from a neighbour.** `IsEnabled 0x7800b0`
-/// is number-`1`/number-`0`-and-never-nil (`setne` + `fild`), which is what makes
-/// `FriendsFrame.lua:404`'s `== 0` live code — so it does NOT come through here. Inside the unit
-/// table itself the *numeric getters* answer the number `0.0` where the predicates answer `nil`
-/// (`UnitLevel 0x518144`, `UnitMana 0x5177c8`, `UnitXP 0x5173f5`, ~15 more; `UnitSex 0x517f9f`
-/// pushes `2.0`).
-///
-/// **Truthiness hides the difference and direct comparison inverts it**, which is why this survived
-/// so long. `if frame:IsVisible()` reads the same either way; `if frame:IsVisible() == nil` does
-/// not — under a boolean a hidden frame answers `false`, and `false == nil` is FALSE, so the caller
-/// concludes the frame is visible exactly when it is not. The 1.12 addon corpus has 21 such direct
-/// comparisons (`IsVisible() == nil` ×9, `GetChecked() == 1` ×6, `IsVisible() ~= nil` ×4, and one
-/// each of `~= 1` / `== 1`) across Questie, AtlasQuest, CT_BagMod, MikScrollingBattleText's options
-/// and `_dl`.
-///
-/// The reference proves its own shape without needing the bytes: stock `UIOptionsFrame.xml:310`
-/// saves a checkbox as `SHOW_BUFF_DURATIONS = tostring(this:GetChecked())` and stock
-/// `BuffFrame.lua:71` reads it back as `== "1"`. That round-trip only closes if `GetChecked`
-/// returns the number 1 — `tostring(true)` is `"true"`, and buff timers would never appear.
-///
-/// Adopting it is strictly safer than what it replaces: every `if x` and `not x` site reads
-/// identically, and only the direct comparisons change — from wrong to right.
+/// The 1.12 predicate return: `1` for true, nil for false, never a Lua boolean. The widget and
+/// `Unit*` predicates push the number 1 (`0x6f3810`) or nil (`0x6f37f0`); outside the base library
+/// (`rawequal`, `pcall`, `xpcall`), the one binding that calls `lua_pushboolean` (`0x6f39f0`) is
+/// `IsPetAttackActive` (`0x4be0e0`). Direct comparisons see it: stock `UIOptionsFrame.xml:310`
+/// saves `tostring(this:GetChecked())` and `BuffFrame.lua:71` compares it with `"1"`. The false
+/// leg is per binding: `IsEnabled` (`0x7800b0`) and numeric getters such as `UnitLevel`
+/// (`0x518144`) answer 0 and do not use this.
 pub(crate) fn flag(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -407,22 +218,20 @@ mod tests {
         Lua::new()
     }
 
-    /// Every arm of `0x6f1c10`, including the three a plausible implementation gets backwards.
     #[test]
     fn bool_or_default_is_not_lua_truthiness() {
         let lua = lua();
         let st = |t: &str| Value::String(lua.create_string(t).unwrap());
 
-        // Absent takes the DEFAULT; an explicit nil is FALSE. The two are different arms.
+        // Absent takes the default; an explicit nil is false.
         assert!(bool_or_default(None, true));
         assert!(!bool_or_default(None, false));
         assert!(!bool_or_default(Some(&Value::Nil), true));
 
-        // Booleans pass through.
         assert!(bool_or_default(Some(&Value::Boolean(true)), false));
         assert!(!bool_or_default(Some(&Value::Boolean(false)), true));
 
-        // Numbers TRUNCATE toward zero — they do not round. `0.5` is off, not on.
+        // Numbers truncate toward zero: `0.5` is off.
         assert!(!bool_or_default(Some(&Value::Number(0.5)), true));
         assert!(!bool_or_default(Some(&Value::Number(-0.5)), true));
         assert!(!bool_or_default(Some(&Value::Number(-0.999)), true));
@@ -431,14 +240,13 @@ mod tests {
         assert!(!bool_or_default(Some(&Value::Integer(0)), true));
         assert!(bool_or_default(Some(&Value::Integer(7)), false));
 
-        // THE headline: `"0"` is FALSE, where Lua truthiness would say true.
+        // `"0"` is false, where Lua truthiness says true.
         assert!(!bool_or_default(Some(&st("0")), true));
         assert!(bool_or_default(Some(&st("1")), false));
-        // First byte only — `"0.5"` is false because it starts `'0'`, not because it truncates.
+        // First byte only: `"0.5"` is false because it starts with `'0'`.
         assert!(!bool_or_default(Some(&st("0.5")), true));
         assert!(bool_or_default(Some(&st("9lives")), false));
 
-        // The letter arms.
         for t in ["false", "F", "no", "NIL", "nope"] {
             assert!(
                 !bool_or_default(Some(&st(t)), true),
@@ -452,14 +260,14 @@ mod tests {
             );
         }
 
-        // The keyword arm, case-insensitive whole-string.
+        // The keyword arm, whole-string and case-insensitive.
         assert!(!bool_or_default(Some(&st("off")), true));
         assert!(!bool_or_default(Some(&st("OFF")), true));
         assert!(!bool_or_default(Some(&st("Disabled")), true));
         assert!(bool_or_default(Some(&st("on")), false));
         assert!(bool_or_default(Some(&st("ENABLED")), false));
 
-        // Unrecognised strings — and every byte the remap table cannot index — take the DEFAULT.
+        // Unrecognised strings, and every byte the remap table cannot index, take the default.
         for t in ["", "-1", "?", "maybe", "@"] {
             assert!(bool_or_default(Some(&st(t)), true), "{t:?} → default true");
             assert!(
@@ -468,7 +276,7 @@ mod tests {
             );
         }
 
-        // Table/function take the default arm, like an absent argument.
+        // A table takes the default, like an absent argument.
         let tbl = Value::Table(lua.create_table().unwrap());
         assert!(bool_or_default(Some(&tbl), true));
         assert!(!bool_or_default(Some(&tbl), false));
@@ -477,7 +285,6 @@ mod tests {
     #[test]
     fn number_arg_truncates_toward_zero_not_floor() {
         let lua = lua();
-        // `0x40a2b0` sets RC = chop before `fistp` — a C cast, not `floor`.
         assert_eq!(number_arg(&lua, Value::Number(2.9), "u").unwrap(), 2);
         assert_eq!(number_arg(&lua, Value::Number(-2.9), "u").unwrap(), -2);
         assert_eq!(number_arg(&lua, Value::Number(-0.5), "u").unwrap(), 0);
@@ -488,8 +295,7 @@ mod tests {
         let lua = lua();
         let s = lua.create_string("7").unwrap();
         assert_eq!(number_arg(&lua, Value::String(s), "u").unwrap(), 7);
-        // Missing and wrong-typed take the SAME arm: `0x6f3410` hands `0x6f34d0` a NULL for an
-        // absent argument, which reports "not a number" exactly as a table does.
+        // Missing and wrong-typed arguments take the same raise.
         for v in [Value::Nil, Value::Boolean(true)] {
             let err = number_arg(&lua, v, "Usage: Thing(n)").unwrap_err();
             assert!(format!("{err}").contains("Usage: Thing(n)"));
diff --git a/crates/benilla-ui/src/script/button.rs b/crates/benilla-ui/src/script/button.rs
index 64fca32d..59188c70 100644
--- a/crates/benilla-ui/src/script/button.rs
+++ b/crates/benilla-ui/src/script/button.rs
@@ -1,21 +1,8 @@
-//! The `Button`/`CheckButton` method surface — per-kind behavior over the frame arena
-//! (`CSimpleButton` `0x6eeab0` / `CSimpleCheckbox` `0x6eeb30`).
-//!
-//! Grounded in wow-re's byte-verified LoadXML tables (RF-28): the four state textures
-//! (`Normal/Pushed/Disabled/Highlight`), the `ButtonText` fontstring + `text` attribute, the
-//! `OnClick` script slot (`+0x4cc`); CheckButton runs Button's loader first and adds
-//! `CheckedTexture`/`DisabledCheckedTexture` + the `checked` bool (`+0x4dc`). Which texture *shows*
-//! is **latched on the transition**, not resolved at paint: [`ButtonState::set_state`] is the
-//! client's `SetState 0x779790` and [`settle`] is where the derived inputs reach it. Two stated v1
-//! gaps: the highlight draws with normal blending (the client ADD-blends it; the quad pass has no
-//! blend modes yet), and `PushedTextOffset` is not modeled. Per-state label fonts *are*: the
-//! `*FontObject` trio picks which object each state inherits and `extract` re-resolves it every
-//! frame, while `SetFont` writes the button's own face/size/flags over all of them
-//! ([`crate::widget::ButtonFont`]).
-//!
-//! Method resolution: CheckButton's table is consulted first, then Button's, then the shared frame
-//! table — mirroring the client's class chain, and keeping duck-typing honest (`frame.SetChecked`
-//! is nil on a plain Button; `frame.GetText` is nil on a plain Frame).
+//! The `Button` and `CheckButton` methods (`CSimpleButton` `0x6eeab0`, `CSimpleCheckbox`
+//! `0x6eeb30`). The shown state texture latches at each state edge (`SetState` `0x779790`), not at
+//! paint. `<PushedTextOffset>` is not built: a pushed label does not shift.
+//! Lookup runs CheckButton's table, then Button's, then the frame table, the client's class chain,
+//! so `SetChecked` is nil on a plain Button and `GetText` on a plain Frame.
 
 use mlua::{Lua, MultiValue, ObjectLike, Table, Value};
 
@@ -32,7 +19,7 @@ use crate::widget::{
 pub(super) const REG_BUTTON_METHODS: &str = "__benilla_button_methods";
 pub(super) const REG_CHECKBUTTON_METHODS: &str = "__benilla_checkbutton_methods";
 
-/// The Button state-texture/text slots (each an arena region created on first set).
+/// A Button's texture and label slots, each an arena region created on first set.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Slot {
     Normal,
@@ -57,10 +44,8 @@ impl Slot {
         }
     }
 
-    /// The three STATE slots go through [`ButtonState::set_state_slot`] — the client's
-    /// `0x778fd0` family, which stores the slot *and* pushes it to the shown pointer when it is
-    /// the current state's. Every other slot is a plain field: the highlight, the checked pair
-    /// and the label are not in the state array and have show rules of their own.
+    /// The three state slots go through [`ButtonState::set_state_slot`] (`0x778fd0`), which also
+    /// shows the texture when it is the current state's; the others are plain fields.
     fn set(self, bs: &mut ButtonState, rh: Option<crate::widget::RegionHandle>) {
         match self {
             Slot::Normal => bs.set_state_slot(ButtonVisualState::Normal, rh),
@@ -73,8 +58,8 @@ impl Slot {
         }
     }
 
-    /// The slot's region kind + default draw layer: state textures under the text, the highlight
-    /// in its own top layer (drawLayer table `0x811a84`), the checked marks above the state.
+    /// The region kind and default layer: state textures under the label, the highlight in its own
+    /// layer (the draw-layer table `0x811a84`), the checked marks above the state.
     fn shape(self) -> (RegionKind, DrawLayer) {
         match self {
             Slot::Normal | Slot::Pushed | Slot::Disabled => {
@@ -87,11 +72,8 @@ impl Slot {
     }
 }
 
-/// The NORMAL embedded font's justify word — `[button+0x390]` (`+0x33c`, the normal `CSimpleFont`,
-/// plus its `+0x54` justify cell): the element-level `<NormalFont justifyH=>` when the template
-/// wrote one (a local write on that instance, severed from what it inherits), else what the
-/// instance inherits from its font object, else the ctor default (CENTER). The word the label
-/// adopter anchors by — decision 1996.
+/// The normal font's justify (`[button+0x390]`): its own `<NormalFont justifyH=>`, else its font
+/// object's, else CENTER. The label adopter anchors by it.
 fn normal_font_justify(model: &Model, bs: &ButtonState) -> Justify {
     let mut word = Justify::default();
     let inherited = || {
@@ -106,20 +88,9 @@ fn normal_font_justify(model: &Model, bs: &ButtonState) -> Justify {
     word
 }
 
-/// `CSimpleButton::SetFontString 0x778d20`'s tail — the ONE path a button label enters by,
-/// whether `SetText` made it (`0x778dc0` allocates, then calls this) or Lua handed one over
-/// (`SetFontString`): anchor it to the button **only if it has no anchor of its own** and **by the
-/// NORMAL font's justify word** (`[button+0x390]`: LEFT→LEFT, RIGHT→RIGHT, else CENTER — never
-/// the string's own `+0x120`, which on a fresh string is the ctor's CENTER), then apply the
-/// button's per-state font to it on the spot (`0x779810`). wow-re
-/// `system/ui/scratch/resize-bounds-and-button-fontstring.md` §5.2, every clause VERIFIED.
-///
-/// The word's source is the whole bug this fixes (decision 1996): a `UIMenuButtonTemplate` row
-/// has no `<ButtonText>` — its label is born from the reference's `UIMenu_AddButton` →
-/// `button:SetText(text)` — and its `<NormalFont inherits="GameFontNormal" justifyH="LEFT"/>` is
-/// the only thing that puts the label at the row's left edge. Reading the fresh string's own
-/// word instead seated every row CENTER, and with the shortcut string anchored RIGHT in a fixed
-/// 104-wide row, "Macro" ran into "/macro".
+/// `SetFontString`'s tail (`0x778d20`), which `SetText` also creates its label through
+/// (`0x778dc0`): an unanchored label anchors LEFT, RIGHT or CENTER by the normal font's justify,
+/// never its own (`+0x120`, CENTER on a fresh string), then takes the per-state font (`0x779810`).
 fn adopt_label(model: &mut Model, owner: FrameHandle, rh: RegionHandle) {
     let point = {
         let Some(frame) = model.arena.frame(owner) else {
@@ -134,34 +105,12 @@ fn adopt_label(model: &mut Model, owner: FrameHandle, rh: RegionHandle) {
     apply_normal_font(model, owner);
 }
 
-/// Point the ButtonText at the button's NORMAL font — object and local justify — so the label's
-/// *query* surface answers what its paint already shows. The live link the reference's per-state
-/// applier `0x779810` → `0x770c60` installs: the instance's field block flows onto the label
-/// behind the label's own severance mask.
-///
-/// Before this, the two disagreed. `extract` resolves the per-state font object every frame and
-/// overlays it onto a CLONE of the region's data (`extract.rs` l.114-122), so the label painted
-/// correctly while `region_data.font_object` stayed `None` — and a dropdown row's
-/// `GetFontObject()` answered **nil**, `GetFont()` answered **nil, nil**. Nothing errored: a
-/// FontString with no font of its own is a legal state, so this was invisible in exactly the way
-/// 1205's silent-drop class predicts.
-///
-/// The measured consequence is smaller than it first looks, and that is stated rather than implied.
-/// The corpus's 65 `GetFontObject` sites are on FontStrings the addon created and linked itself
-/// (Dewdrop-2.0 calls `text:SetFontObject(GameFontHighlightSmall)` one line before it reads the
-/// object back), so none of them were reaching this. What WAS reaching it is the reference's own
-/// `DropDownList1` OnLoad, which derives `UIDROPDOWNMENU_DEFAULT_TEXT_HEIGHT` from
-/// `DropDownList1Button1NormalText:GetFont()` and got nil.
-///
-/// **Normal only, deliberately.** The highlight and disabled objects are transient states that
-/// extract overlays at paint time; linking either here would make a resting button report its hover
-/// font. The remaining divergence, stated: while a button is disabled or hovered, the reference's
-/// label reports that state's font and ours still reports the normal one. The paint is unaffected
-/// either way, and no corpus site reads a label's font mid-state.
-///
-/// `font::repaint` honours the severance mask, so a `<FontHeight>` or `SetTextColor` the label set
-/// for itself survives the link (the rule wow-re pinned in `font-object-lua-surface.md`), and the
-/// local justify goes behind the same mask.
+/// Link the label to the normal font object and local justify, the reference's `0x779810` →
+/// `0x770c60`, so its `GetFont` answers what it paints; the stock `DropDownList1` reads it
+/// (`UIDropDownMenu.xml:11`). Deviation: a hovered or disabled label still reports the normal
+/// font, since the state fonts are overlaid at paint and a link made here would outlive the state.
+/// `font::repaint` keeps what the label set itself (its severance mask, `CSimpleFontString+0xd4`),
+/// and the local justify obeys the same mask.
 fn apply_normal_font(model: &mut Model, owner: FrameHandle) {
     let (rh, name, local_justify) = {
         let Some(frame) = model.arena.frame(owner) else {
@@ -175,8 +124,7 @@ fn apply_normal_font(model: &mut Model, owner: FrameHandle) {
         };
         (rh, bs.normal_font.clone(), bs.normal_justify_h)
     };
-    // An unregistered name is not an error here: `SetTextFontObject` already accepted it, and the
-    // loader's own log-and-continue rule (0068) owns the reporting.
+    // An unregistered name is no error here: the setter accepted it and the loader reports it.
     let fo = name.as_deref().and_then(|n| model.font_object(n).cloned());
     let d = model.region_data.entry(rh).or_default();
     match (&name, fo) {
@@ -203,14 +151,9 @@ pub(crate) enum LabelFont {
     Disabled,
 }
 
-/// `<NormalFont justifyH=>` / `<HighlightFont justifyH=>` / `<DisabledFont justifyH=>` — the
-/// loader-facing write of a per-state embedded font's own justify (`CSimpleButton::LoadXML
-/// 0x7788c0` → the `<Font>` loader `0x783c30` on `+0x33c`/`+0x3b8`/`+0x434`: a `<Font>`-typed
-/// element, so the attribute lands on the instance itself, severed from whatever it inherits).
-/// No 1.12 Lua verb writes this — the API trio sets the OBJECT each instance inherits, never its
-/// local fields — which is why it is crate-internal rather than a method. A label already
-/// adopted keeps its anchor (the reference decided that at adoption) while its own justify word
-/// follows the normal instance, as the live link propagates the write.
+/// The loader's `<NormalFont justifyH=>` and kin: `LoadXML` (`0x7788c0`) runs the `<Font>` loader
+/// (`0x783c30`) on the embedded font, so the justify is its own, not inherited; no Lua verb
+/// writes it. An adopted label keeps its anchor and takes the new normal justify.
 pub(crate) fn set_label_font_justify_h_lua(
     lua: &Lua,
     wrapper: &Table,
@@ -230,14 +173,8 @@ pub(crate) fn set_label_font_justify_h_lua(
     Ok(())
 }
 
-/// Run `f` over a frame's Button state under one short write borrow.
-///
-/// **It no longer settles a state machine afterwards, because there is no longer one to settle**
-/// (decision 2134). The button's state is a latch the engine's own edges write; a Lua write moves
-/// it only when the write IS an edge (`Enable`/`Disable`, `SetButtonState`), and those call the
-/// edge themselves. `RegisterForClicks` and the texture setters no longer disturb the state at
-/// all — which is the reference's behaviour: re-registering a held button's clicks does not
-/// un-press it.
+/// Run `f` over a frame's Button state under one short write borrow. It moves no state, only an
+/// edge does: re-registering a held button's clicks does not un-press it, as in the reference.
 fn with_button<T>(
     lua: &Lua,
     this: &Table,
@@ -255,54 +192,11 @@ fn with_button<T>(
     }
 }
 
-/// `Enable()` / `Disable()` — and the second thing they do, which is not the state texture.
-///
-/// `Disable 0x77ffd0` ends `0x78009a call [vtbl+0x90](0)`, reaching the shared helper
-/// `0x779160`; the constructor reaches the same helper with `1` (`0x778766`), which is what puts
-/// a fresh button in NORMAL. That helper does **two** things:
-///
-/// - `[vtbl+0x9c](state, 0)` = `SetButtonState 0x779790` — [`ButtonState::set_enabled`]'s half,
-///   whose two early-outs (nothing happens if the button is already in the state being asked for)
-///   are the helper's own; and
-/// - `0x7791bb push 4; call 0x76a730` — the per-layer enable for layer **4 = HIGHLIGHT**, written
-///   into the very `[frame+0x198]` array that `Enable/DisableDrawLayer` writes and that
-///   `0x76b3a0` reads back at draw time.
-///
-/// So a disabled button's highlight is switched off **at the layer**, which takes every region
-/// the frame owns there with it — not only the HighlightTexture. That is why the highlight is no
-/// longer gated on `enabled` inside [`ButtonState::region_visible`]: one mechanism, in the place
-/// the client keeps it, instead of a second rule that agreed with it on the common case and
-/// disagreed on `<Layer level="HIGHLIGHT">` art the button did not put there itself.
-///
-/// **The restore is NOT symmetric, and this comment used to claim it was** — *"one array and one
-/// writer, so an addon's `DisableDrawLayer("HIGHLIGHT")` is undone by the next `Enable()`"*. Both
-/// halves are false (wow-re `scratch/button-disabled-state-texture-law.md` §7, sharpened
-/// 2026-09-09 off `0x779160` read contiguously for exactly this question). The indexed form
-/// `[reg + 4*reg + 0x198]` has **three** sites image-wide — `0x76a717` (=1), `0x76a737` (=0) and
-/// `DrawLayer 0x76b3a6`'s read — so there are **two** writers; and the enable arm calls
-/// *neither* helper. It reaches the ON one only one hop away and only when the button is the
-/// frame under the cursor:
-///
-/// ```text
-/// 779183  mov ecx,[esi+0xa0]   ; the CSimpleTop singleton
-/// 779189  cmp esi,[ecx+0x7c]   ; am I the hover target?
-/// 77918c  jne 0x7791ce         ;   no -> return, layer untouched
-/// 779192  call [edx+0x4c]      ; = 0x779490 -> 0x76b6a0 -> 0x76b6c9 push 4; call 0x76a710
-/// ```
-///
-/// — i.e. `Enable()` on a hovered button restores the layer **by re-running the frame's Lua
-/// `<OnEnter>`**, and on a non-hovered one restores nothing (the next hover-enter does it). Both
-/// restore paths are gated on the LockHighlight flag `[frame+0xf8]`, and the disable arm's
-/// `0x7791bb call 0x76a730(4)` is the one site in the image that is *not* — so
-/// `LockHighlight()` → `Disable()` → `Enable()` leaves the layer off in the reference, and only
-/// `UnlockHighlight()`+`LockHighlight()` or an explicit `EnableDrawLayer` brings it back.
-///
-/// **Ours is the symmetric bit-flip**, which draws the same in the ordinary case — a highlight is
-/// only visible while hovered, and every hover-enter sets it — and diverges in two script-visible
-/// ways: we do not fire the `<OnEnter>` the reference synthesises when you `Enable()` a hovered
-/// button, and we restore a locked-then-disabled highlight the reference leaves dark. Named here
-/// rather than fixed, because the faithful shape needs the layer restore moved onto the hover
-/// path where the reference keeps it.
+/// `Enable()`/`Disable()`. `Disable` (`0x77ffd0`) reaches `SetEnabled` (`0x779160`), which also
+/// turns draw layer 4, HIGHLIGHT, off (`0x7791bb`) in the array `DisableDrawLayer` writes, so every
+/// region in that layer goes dark, not only the HighlightTexture. `Enable()` here turns it back
+/// on; the reference restores it only on a hovered button, by re-running its `<OnEnter>`
+/// (`0x779183`), and never while `LockHighlight` holds (`[frame+0xf8]`).
 fn set_enabled(lua: &Lua, this: &Table, on: bool) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -310,9 +204,6 @@ fn set_enabled(lua: &Lua, this: &Table, on: bool) -> mlua::Result<()> {
         .arena
         .frame_mut(h)
         .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
-    // The state half is [`ButtonState::set_enabled`], whose two early-outs are the client's:
-    // `Enable()` on a button that is not DISABLED does nothing at all, and neither does
-    // `Disable()` on one that already is.
     match &mut frame.kind_state {
         KindState::Button(bs) => bs.set_enabled(on),
         _ => return Err(mlua::Error::runtime("not a Button")),
@@ -326,15 +217,9 @@ fn set_enabled(lua: &Lua, this: &Table, on: bool) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Run one of the engine's own state edges over frame `h`, if it is a live Button.
-///
-/// The reference's edge set is exactly seven `SetButtonState` call sites and **six of them are
-/// engine-side** (wow-re `scratch/button-state-edge-set.md`, VERIFIED): Enable, Disable, the hide
-/// notify, mouse-down, mouse-up and the drag-threshold crossing. There is **no enter or leave
-/// edge** — which is why the pointer path no longer calls anything here when the cursor crosses a
-/// button's boundary (decision 2134).
-///
-/// Harmless on a non-Button handle, and on a stale one.
+/// Run an engine state edge over frame `h` if it is a live Button. The reference has six, all of
+/// `0x779790`'s call sites but Lua's: enable, disable, hide, press, release and drag start; the
+/// cursor entering or leaving a button is not one.
 pub(super) fn edge(model: &mut Model, h: FrameHandle, f: impl FnOnce(&mut ButtonState)) {
     if let Some(frame) = model.arena.frame_mut(h) {
         if let KindState::Button(bs) = &mut frame.kind_state {
@@ -343,37 +228,12 @@ pub(super) fn edge(model: &mut Model, h: FrameHandle, f: impl FnOnce(&mut Button
     }
 }
 
-/// Does a hover edge on frame `h` reach the **base** enter/leave notify — the HIGHLIGHT layer and
-/// the Lua `<OnEnter>`/`<OnLeave>` script slots — or is it swallowed on the way there?
-///
-/// `CSimpleButton::OnEnter 0x779490` and `OnLeave 0x7794e0` both open on the state word, and the
-/// branch skips the *whole* body except the sound:
-///
-/// ```text
-/// 779493  mov eax,[esi+0x328]
-/// 779499  test eax,eax
-/// 77949b  je 0x7794b0          ; DISABLED -> skip the base notify AND the label restyle
-/// 77949d  call 0x76b6a0        ; CSimpleFrame::OnEnter — highlight layer on, <OnEnter> at +0x140
-/// ```
-///
-/// — so **a DISABLED Button runs neither script**, and `0x7794b0`'s hover sound is the only thing
-/// past the branch (wow-re `scratch/button-state-edge-set.md` §3.1, VERIFIED; the base pair's
-/// script slots `+0x140`/`+0x148` are `ledger.tsv:7944/7945`). Every path that delivers a hover
-/// edge dispatches through the object's own vtable, so there is no way around the guard: the hover
-/// walk (`0x766218`–`0x76623c`, `[vt+0x50]` then `[vt+0x4c]`), `SetMouseFocus 0x764dc0`
-/// (`0x764ddd push 0`), and the hide/removal tail (`0x764cce mov edx,[edi]; push 1;
-/// call [edx+0x50]`). `CheckButton` inherits both slots; the Hyperlink and NamePlate buttons
-/// override them and tail straight back into this pair (`0x7cb8a5`), so the guard covers the
-/// family.
-///
-/// The hover **target** still moves — the walk reassigns `[root+0x7c]` *before* it fires either
-/// notify — so `GetMouseFocus()` answers a disabled button; it is the scripts alone that stay
-/// quiet. This is what makes AtlasLoot's unset QuickLook buttons safe on the reference: their
-/// `<OnEnter>` guards with `if this:IsEnabled() then`, which is a NUMBER `1`/`0` and therefore
-/// always truthy (`scratch/button-enabled-state.md`), so the body would index a nil
-/// `QuickLooks[n]` — the reference never runs it at all.
-///
-/// `None` (the cursor over no frame) and every non-Button kind notify normally.
+/// Whether a hover edge on `h` reaches the base notify, the HIGHLIGHT layer and the Lua
+/// `<OnEnter>`/`<OnLeave>`: `OnEnter`/`OnLeave` (`0x779490`/`0x7794e0`) skip it on a DISABLED
+/// Button, leaving only the hover sound (`0x7794b0`). Every hover path goes through that pair
+/// (the hover walk `0x766218`, `SetMouseFocus` `0x764dc0`, the hide tail `0x764cce`), and the
+/// Hyperlink and NamePlate overrides chain back (`0x7cb8a5`). The hover target still moves, so
+/// `GetMouseFocus()` answers a disabled button.
 pub(super) fn hover_notify_runs(model: &Model, h: Option<FrameHandle>) -> bool {
     let Some(h) = h else { return true };
     match model.arena.frame(h).map(|f| &f.kind_state) {
@@ -382,8 +242,7 @@ pub(super) fn hover_notify_runs(model: &Model, h: Option<FrameHandle>) -> bool {
     }
 }
 
-/// Write [`ButtonState::loot_slot`] — `LootButton:SetSlot`'s whole body, kept here beside the
-/// other `ButtonState` writers rather than reaching into the arena from `script::loot`.
+/// `LootButton:SetSlot`: writes [`ButtonState::loot_slot`].
 pub(super) fn set_loot_slot(lua: &Lua, this: &Table, slot: Option<u32>) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -396,9 +255,7 @@ pub(super) fn set_loot_slot(lua: &Lua, this: &Table, slot: Option<u32>) -> mlua:
             bs.loot_slot = slot;
             Ok(())
         }
-        // The reference's own guard: `SetSlot` type-checks `this` against the LootButton tag via
-        // vtable slot 4 (`0x4c18ee`), so calling it on a plain Button raises rather than writing a
-        // field nothing would ever read.
+        // `SetSlot` type-checks `this` as a LootButton (`0x4c18ee`) and raises on anything else.
         _ => Err(mlua::Error::runtime(
             "SetSlot: 'this' is not a LootButton widget",
         )),
@@ -426,9 +283,10 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot) -> mlua::Result<u32> {
                 .arena
                 .create_region(h, kind, layer, 0)
                 .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
-            // The highlight draws ADD by contract (the live API's SetHighlightTexture default
-            // blend; highlight art is authored for it — under straight alpha it reads as a
-            // dark box over the icon).
+            // A new highlight blends ADD, `SetHighlightTexture`'s default (`0x781d92`). The
+            // reference applies that mode, or a third argument's, on every call and to a handed-in
+            // Texture too (`0x7703f0` from `0x779050` and `0x779110`); here only a new region
+            // takes it.
             model.region_data.insert(
                 rh,
                 RegionData {
@@ -440,20 +298,14 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot) -> mlua::Result<u32> {
                     ..Default::default()
                 },
             );
-            model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+            model.touch_layout(); // a region entered the layout gate's read set
             if let Some(frame) = model.arena.frame_mut(h) {
                 if let KindState::Button(bs) = &mut frame.kind_state {
                     slot.set(bs, Some(rh));
                 }
             }
-            // A freshly built slot region gets its creation-path implicit anchor (decision 1310)
-            // — an EXISTING slot region is never touched here; the get half of get-or-create
-            // changes no geometry. Which anchor depends on the slot: the reference's C++ string
-            // setters SetAllPoints a fresh state texture outright (`0x778f9d`/`0x7790db` — fresh
-            // means zero anchors, so the conditional form is equivalent), while a fresh LABEL is
-            // handed to the adopter (`SetText 0x778dc0` → `0x778d20`), which anchors it by the
-            // button's normal font and links it (decision 1996). The XML loader re-derives after
-            // applying authored `<Anchors>` (see `loader/widgets.rs`).
+            // Only a new region gets an implicit anchor: a state texture fills the button
+            // (`0x778f9d`/`0x7790db`), a label goes to the adopter (`0x778dc0` → `0x778d20`).
             match slot {
                 Slot::Text => adopt_label(&mut model, h, rh),
                 _ => super::region::implicit_creation_anchor(&mut model, rh),
@@ -464,9 +316,8 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot) -> mlua::Result<u32> {
     Ok(model.region_id(rh))
 }
 
-/// Point `slot` at `rh` (or at nothing) and hand back whatever it held before, when that is a
-/// different region. The reference's slot store `0x778fd0` ends in the outgoing object's
-/// vtable-slot-0 dtor, so the caller frees it.
+/// Point `slot` at `rh` or at nothing, returning the different region it held for the caller to
+/// free, as the slot store `0x778fd0` destroys the outgoing object.
 fn swap_slot(
     model: &mut Model,
     h: FrameHandle,
@@ -486,7 +337,7 @@ fn swap_slot(
     Ok(outgoing)
 }
 
-/// Free the region a slot just gave up — never the one that just moved in.
+/// Free the region a slot gave up, never the one that moved in.
 fn free_outgoing(lua: &Lua, outgoing: Option<RegionHandle>, incoming: RegionHandle) {
     if let Some(old) = outgoing.filter(|old| *old != incoming) {
         super::region::free_region(
@@ -496,26 +347,18 @@ fn free_outgoing(lua: &Lua, outgoing: Option<RegionHandle>, incoming: RegionHand
     }
 }
 
-/// The shared body of `Set<State>Texture(texture | "path" | nil)` / `(r, g, b [, a])`.
-///
-/// The reference forks on `lua_type(L, 2)` into four legs (`0x781970`, carved instruction by
-/// instruction in wow-re `button-state-texture-path-setter.md` §1). **Two of them never touch the
-/// slot's own region at all**, so they are resolved *before* [`ensure_slot`] — which would
-/// otherwise lazily build a region for a call whose entire purpose is to replace or drop one.
+/// `Set<State>Texture(texture | "path" | nil)`, forked on the argument's type (`0x781970`). The
+/// object and nil legs never touch the slot's own region, so they run before [`ensure_slot`]
+/// would create one. The `(r, g, b [, a])` form is not 1.12's, which reads a number as a path
+/// (`0x781b23`).
 fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> mlua::Result<()> {
     match args.front() {
-        // **A widget object installs THAT region into the slot** (`0x781b0b`: `push the Texture
-        // object; push idx; call 0x778fd0`) — it does not load a path into the slot's own region.
-        // Three corpus addons build a highlight exactly this way and every one of them was a
-        // silent no-op here: Bongos' bar-drag button (`bar.lua:64-71`), _Nameplates' mouseover
-        // glow (`_Nameplates.lua:217-222`) and Quiver's option rows (`Quiver.bundle.lua:8949-53`)
-        // each `CreateTexture` on the button, colour it, `SetAllPoints`, and hand it over.
+        // A Texture object is itself installed into the slot (`0x781b0b` → `0x778fd0`).
         Some(Value::Table(t)) => {
             let rh = super::region::region_handle_of(lua, t)?;
             let h = frame_handle_of(lua, this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // The reference type-checks the handed object and raises rather than installing a
-            // FontString into a texture slot (`0x781ab1`, `0x87a1e0`).
+            // Any other widget raises (`0x781ab1`, message `0x87a1e0`).
             if model.arena.region(rh).map(|r| r.kind) != Some(RegionKind::Texture) {
                 return Err(mlua::Error::runtime("Wrong object type, expected texture"));
             }
@@ -524,15 +367,9 @@ fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> m
             free_outgoing(lua, outgoing, rh);
             return Ok(());
         }
-        // **nil CLEARS the slot** (`0x781b5a`: `push 0; push idx; call 0x778fd0`, whose tail runs
-        // the outgoing object's dtor). Clearing the pointer alone would be worse than doing
-        // nothing: `ButtonState::region_visible` shows any region that is not one of the button's
-        // own slots unconditionally, so an unhooked state texture would start drawing in *every*
-        // state instead of none. `TheoryCraft/TheoryCraftUI.lua:215-217` strips a talent-rank
-        // button's normal/pushed/highlight art with three of these.
-        //
-        // A call with NO argument is left alone: `LUA_TNONE` is not `LUA_TNIL`, and the
-        // reference's own nil test is `0x781b4f call 0x6f3400 == 0`.
+        // nil clears the slot and destroys the old region (`0x781b5a` → `0x778fd0`): unhooked but
+        // alive, it would draw in every state. No argument is not nil (`0x781b4f`) and clears
+        // nothing.
         Some(Value::Nil) => {
             let h = frame_handle_of(lua, this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -554,9 +391,7 @@ fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> m
     let rh = *model.id_to_region.get(&id).expect("slot region id");
     let data = model.region_data.entry(rh).or_default();
     match args.front() {
-        // `Set<State>Texture("")` CLEARS — the live API's blank form (ref QuestLogFrame.lua:165
-        // clears the quest rows' +/- slot with exactly this), same as SetTexture(nil)/("") on a
-        // plain region.
+        // `""` clears the texture, which `QuestLogFrame.lua:165` relies on.
         Some(Value::String(s)) if s.to_str()?.is_empty() => {
             data.texture = None;
             data.fill = None;
@@ -565,8 +400,7 @@ fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> m
             data.texture = Some(s.to_str()?.to_string());
             data.fill = None;
         }
-        // The colour form generates a solid texture into the same slot the path form loads into
-        // ([`RegionData::fill`]) — never a tint, so each clears the other.
+        // The colour form is a solid texture, not a tint: it and the path clear each other.
         Some(v @ (Value::Number(_) | Value::Integer(_))) => {
             let arg = |i: usize| args.get(i).map(as_f32);
             data.fill = Some([
@@ -582,7 +416,7 @@ fn set_slot_texture(lua: &Lua, this: &Table, slot: Slot, args: &MultiValue) -> m
     Ok(())
 }
 
-/// The shared body of `Get<State>Texture` — the region wrapper, or nil while unset.
+/// `Get<State>Texture`: the region wrapper, or nil while unset.
 fn get_slot_texture(lua: &Lua, this: &Table, slot: Slot) -> mlua::Result<Value> {
     let rh = with_button(lua, this, |bs| slot.get(bs))?;
     let id = {
@@ -618,17 +452,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     texture_pair(lua, &m, "Disabled", Slot::Disabled)?;
     texture_pair(lua, &m, "Highlight", Slot::Highlight)?;
 
-    // SetText/GetText target the ButtonText fontstring (RF-28: the `text` attr routes there).
+    // SetText/GetText go to the ButtonText fontstring, as the `text` attribute does (`0x778dc0`).
     m.set(
         "SetText",
         lua.create_function(|lua, (this, text): (Table, Option<Value>)| {
             let text = super::binding_abi::text_arg(lua, text)?;
-            // `CSimpleButton::SetText 0x778dc0` opens `if (!text) return;` (`0x778dcc`, wow-re
-            // `button-label-build-and-anchor-order.md`) — a nil never reaches the label at all, so
-            // it neither clears the text nor lazily creates the FontString. That guard is the
-            // BUTTON's own: a `FontString:SetText(nil)` is not a no-op, it truncates the cell
-            // (`0x771d80`, decision 2110). Below the guard the button is a pass-through to
-            // `[button+0x338]->0x771d80`.
+            // A nil returns at once (`0x778dcc`): no clear, no label created. The guard is the
+            // button's own; `FontString:SetText(nil)` clears (`0x771d80`).
             let Some(text) = text else { return Ok(()) };
             let id = ensure_slot(lua, &this, Slot::Text)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -638,10 +468,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetText — like the FontString's own (`region::text`, decision 2110), an **empty label reads
-    // back nil**: `Button:GetText 0x780e10` carries the same first-byte substitution at `0x780ec5`,
-    // over three nil conditions rather than two (no label region, a NULL cell, an empty cell).
-    // Its EditBox neighbour deliberately does not — the law is per binding.
+    // GetText (`0x780e10`): nil for no label, and for an empty one (`0x780ec5`).
     m.set(
         "GetText",
         lua.create_function(|lua, this: Table| {
@@ -663,51 +490,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| get_slot_texture(lua, &this, Slot::Text))?,
     )?;
 
-    // SetFontString(fontString) — ADOPT a caller-made FontString as this Button's label.
-    //
-    // Byte-carved end to end by wow-re (decision 1505,
-    // `system/ui/scratch/resize-bounds-and-button-fontstring.md`
-    // §5): the binding `0x780a60` is gates + a delegate to `CSimpleButton::SetFontString
-    // 0x778d20`, which is the SAME function `SetText`'s lazy creation path funnels through — so
-    // adopting and creating share their whole tail, and only the allocation differs.
-    //
-    // The idiom it exists for: build the label yourself so you can style and place it, then hand
-    // it to the button so `SetText` and the per-state font machinery drive it. Quiver's
-    // `Component/Select.wow.lua` builds every dropdown option row that way, and with the method
-    // nil the row died on its first line — the second of B267's three walls.
-    //
-    // **It raises, in three distinct ways, and never silently no-ops on a bad argument** — the
-    // first shape I built here was a lenient no-op and the bytes say otherwise:
-    //
-    //  · a **missing** argument, `nil`, a number, a string or a boolean → `lua_type(L,2) != TABLE`
-    //    → `Usage: %s:SetFontString(fontstring)` (`0x87a100`). Missing and nil take the identical
-    //    leg (`index2adr` answers NULL → type −1), so `SetFontString(nil)` **cannot clear the
-    //    label from Lua**; the C++ clear exists but no binding reaches it.
-    //  · a **table that is not a widget** → `%s:SetFontString(): Couldn't find 'this' in
-    //    fontstring` (`0x87a160`).
-    //  · a **Frame or a Texture** — anything that is not a FontString → `%s:SetFontString():
-    //    Wrong object type, expected fontstring` (`0x87a124`), gated by an `IsA` against the
-    //    FontString token, which a Texture fails.
-    //
-    // `%s` is the BUTTON's name (or `<unnamed>`), never the argument's. Zero return values.
-    //
-    // What `0x778d20` then does, all four clauses VERIFIED and all four here:
-    //
-    //  · **`new == old` is a total no-op** — the first compare, before anything is touched.
-    //  · **the previous label is DESTROYED**, not orphaned (`old->vtable[0](1)`, the scalar
-    //    deleting destructor, returning the storage to the FontString pool). So a button whose
-    //    `SetText` already lazily made one does not leak a stray string behind the new label.
-    //  · **the string is RE-PARENTED to the button and its draw layer forced to ARTWORK**
-    //    (`0x77fd10(parent, 2, 1)` — layer id 2 in the client's own `.rdata 0x811a80` name table).
-    //    Always, whatever it was parented to or drawn in before.
-    //  · **it is anchored only if it has NO anchors of its own** (a scan of all nine
-    //    `anchorPoints` slots): LEFT/RIGHT/CENTER by the justify bits of the **button's normal
-    //    font** (`[button+0x390]`), to the matching point on the button — [`adopt_label`], the
-    //    same `& 7` → LEFT(1)/RIGHT(4)/else-CENTER chain the FontString post-step runs, over the
-    //    other word. (It used to reuse the post-step and read the string's own word; the two
-    //    only agree when the normal font has no justify — decision 1996.)
-    //  · **the button's per-state font is applied immediately** (`0x779810`) — the same
-    //    [`adopt_label`] links the label to the normal font, so its query surface answers.
+    // SetFontString(fontString) (`0x780a60` → `0x778d20`) raises, naming the button, on a
+    // non-table (`0x87a100`), nil included, so Lua cannot clear the label; on a non-widget
+    // (`0x87a160`); on a non-FontString (`0x87a124`). The same label is a no-op; otherwise the old
+    // one is destroyed and the new one moves to the button at ARTWORK (`0x77fd10`) and is adopted.
     m.set(
         "SetFontString",
         lua.create_function(|lua, args: MultiValue| {
@@ -730,11 +516,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     "Usage: {who}:SetFontString(fontstring)"
                 )));
             };
-            // The two remaining legs are DIFFERENT questions and the reference asks them in this
-            // order: first "is this a framescript object at all" (`0x780b27`), then "is it a
-            // FontString" (`0x780b90`'s `IsA` against the FontString token). A Frame or a Texture
-            // passes the first and fails the second — so resolving straight to a region handle
-            // would collapse both onto the first message and mislabel every widget argument.
+            // Two checks in the reference's order, a widget at all (`0x780b27`), then a FontString
+            // (`0x780b90`), so a Frame or a Texture gets the second message.
             let rh = {
                 let not_an_object = || {
                     mlua::Error::runtime(format!(
@@ -770,8 +553,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             with_button(lua, &this, |bs| bs.text = Some(rh))?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             if let Some(dead) = old {
-                // DESTROYED, not orphaned — the shared region-lifetime law, whose doc carries the
-                // reason (`0x778d3c`'s scalar deleting destructor).
+                // Destroyed, not orphaned (`0x778d3c`).
                 super::region::free_region(&mut model, dead);
             }
             model.arena.set_region_owner(rh, Some(owner));
@@ -779,42 +561,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 r.draw_layer = DrawLayer::Artwork;
             }
             adopt_label(&mut model, owner, rh);
-            // A new label, a new owner and a possible new anchor — the layout's read set moved,
-            // and the string's extents are what the button's own `GetTextWidth` reports.
+            // The layout's read set moved, and `GetTextWidth` reads the new label's extents.
             model.touch_layout();
             model.touch_measure(rh);
             Ok(())
         })?,
     )?;
 
-    // GetTextWidth / GetTextHeight — the Button's OWN text-extent readers (`0x782290` / `0x782390`,
-    // wow-re `system/ui/scratch/item9-firing34-merge.md` l.36 and the Button method carve in
-    // `widget-api-batch-benilla.md` Q8, which lists both present on Button and `GetStringWidth`
-    // absent). Both are thin forwards onto the label FontString's own extent vtable slots
-    // (`0x1c` / `0x20`), which is exactly what this delegation is.
-    //
-    // **Who asks.** `Bagnon_Forever/database/ui.lua:61` sizes its character-switch dropdown from
-    // `button:GetTextWidth() + 40` over every saved character — with the method nil the whole
-    // dropdown died on the first row, so the director could not switch characters in Bagnon at all.
-    // The idiom generalises: it is how a 1.12 kit fits a button to its label, and the reference's
-    // own `MoneyFrame.lua` l.202 (`SetWidth(GetTextWidth() + iconWidth)`) is the same shape.
-    //
-    // **Which measurement**, since a FontString carries two. The label's `GetStringWidth` — the
-    // NATURAL, unwrapped extent — never the laid-out `GetWidth`. A button label does not wrap, so
-    // the two agree in the ordinary case; where they differ, serving the laid-out width would hand
-    // every "size the button to its text" caller its own previous output as its next input, which
-    // is decision 0997's measured feedback loop (the macro window's tab that changed width every
-    // frame). The unwrapped extent is the one that settles.
-    //
-    // `0` before the host has measured the string (a frame's latency, as everywhere else), and `0`
-    // for a Button with no label at all — the reference dereferences its FontString pointer `+0x338`
-    // here where `SetFont`/`GetFont` deliberately do not, and what a null one does is NOT byte-read,
-    // so this answers the harmless number rather than raising on a guess.
+    // GetTextWidth/GetTextHeight (`0x782290`/`0x782390`) forward to the label's extents (vtable
+    // `0x1c`/`0x20`). The width is the natural, unwrapped one: the laid-out width would feed a
+    // size-to-text caller (`MoneyFrame.lua:202`) its own output. 0 before measurement and with no
+    // label, where the reference dereferences `+0x338` and what it does on null is untraced.
     for (name, region_getter) in [
         ("GetTextWidth", "GetStringWidth"),
-        // `GetHeight`, not a `GetStringHeight` — 1.12 has no such method (byte-verified absent
-        // in every encoding), and the reference's own `Button:GetTextHeight 0x782390` is this
-        // same call on the embedded FontString rather than a separate API.
+        // 1.12 has no `GetStringHeight`; `0x782390` reads the label's height.
         ("GetTextHeight", "GetHeight"),
     ] {
         m.set(
@@ -829,17 +589,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // The per-state label fonts (the 1.12 API trio; XML `<NormalFont>/<HighlightFont>/
-    // <DisabledFont>` route here through the loader). Stored as font-object NAMES — extract
-    // re-points the ButtonText to the current state's object each frame, so Enable/Disable and
-    // hover swap the label's paint with no Lua involvement (the client's own behavior:
-    // UIPanelButtonTemplate's gold/white/gray label states).
-    //
-    // Each takes the font OBJECT, its name, or nil, like `FontString:SetFontObject` — across the
-    // trio the corpus splits 5 object-form to 4 string-form, so accepting one shape only would
-    // break about half the callers, and nil clears the state back to the default. Because the
-    // state is stored as a NAME and re-resolved at every `extract`, a later mutation of that font
-    // object reaches these labels for free.
+    // The per-state label fonts, and `<NormalFont>` and kin through the loader. Each takes a font
+    // object, its name or nil, stored by name: extract re-resolves the current state's font every
+    // frame, so a state change or a later edit to the object reaches the label.
     m.set(
         "SetTextFontObject",
         lua.create_function(|lua, (this, font): (Table, Value)| {
@@ -866,31 +618,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetFont(file, height [, flags]) / GetFont() — the Button's own font, `0x780880`/`0x79f3b0`
-    // (wow-re `system/ui/scratch/widget-api-batch-benilla.md` Q8, §5-verified).
-    // `_LazyPig/LazyPigMenu.lua:214` calls it straight on a `CreateFrame("Button", …)`, and it is
-    // that addon's only blocker.
-    //
-    // Three contract details, each a plausible implementation's silent divergence:
-    //
-    //  · **It returns ZERO values.** The shared impl `0x79f210` pushes `1`/nil (a real font-load
-    //    probe on a Font object — `!OmniCC` uses it), but `Button:SetFont` DISCARDS it
-    //    (`xor eax,eax`), so a failed font load is undetectable from a Button. Returning `true`
-    //    here would look harmless and would hand an addon a probe the client does not have.
-    //  · **It never touches the label.** `SetFont`/`GetFont` do not dereference the FontString
-    //    pointer `+0x338` at all, so styling a bare `CreateFrame("Button")` with no `<ButtonText>`
-    //    is no error, no crash and **no lazy creation** — which is why the style is stored on the
-    //    button ([`ButtonState::font`]) and `extract` applies it to whatever label exists. A later
-    //    `SetText` (which *does* lazily create one, `0x778dc0`) then picks it up, so either call
-    //    order works, exactly as the reference's does.
-    //  · **It retunes all three embedded fonts** (normal `+0x33c`, disabled `+0x434`, highlight
-    //    `+0x3b8`) and `GetFont` reads back only the normal one — see [`ButtonFont`] for why one
-    //    record is the faithful shape for three identical writes.
-    //
-    // The argument gate is the shared impl's: arg2 `lua_isstring` and arg3 `lua_isnumber`, else
-    // `luaL_error("Usage: %s:SetFont(\"font\", fontHeight [, flags])")` (`0x87c69c`). Both
-    // predicates are the *coercing* ones in 5.0 — `lua_isstring` takes a number, `lua_isnumber`
-    // takes a numeric string — so the leniency is transcribed rather than tightened.
+    // SetFont(file, height [, flags]) (`0x780880`) sets all three embedded fonts and returns
+    // nothing, discarding the shared `0x79f210`'s load result. It never touches the label
+    // (`+0x338`), so creates none: extract applies the stored font to whatever label exists. Its
+    // checks are 5.0's coercing `lua_isstring`/`lua_isnumber`, else a usage error (`0x87c69c`).
     m.set(
         "SetFont",
         lua.create_function(
@@ -920,15 +651,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         flags,
                     })
                 })
-                // …and nothing is returned: `with_button` yields `()`.
             },
         )?,
     )?;
-    // GetFont() → file, height, flags — **3 values**, read off the NORMAL embedded font. Unset
-    // locally, that font still resolves through what the normal state inherits
-    // (`<NormalFont>`/`SetTextFontObject`), which is how a `GameMenuButtonTemplate` button answers
-    // GameFontNormal's face before anything calls `SetFont`. Nil path / nil height when neither
-    // exists, still 3 values.
+    // GetFont() (`0x7809a0` → `0x79f3b0`) → file, height, flags off the normal font, else the
+    // object it inherits (`<NormalFont>`, `SetTextFontObject`); always three values.
     m.set(
         "GetFont",
         lua.create_function(|lua, this: Table| {
@@ -957,10 +684,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The per-state label COLORS (Button:SetTextColor + the Highlight/Disabled pair): the state's
-    // color, when set, repaints the ButtonText over the state font object's paint at extract —
-    // the dropdown kit's rows use all three (info.textR/G/B rows, isTitle's NORMAL-yellow and
-    // notClickable's HIGHLIGHT-white recolors of a disabled row).
+    // The per-state label colours: a set one paints over the state font's colour at extract.
     m.set(
         "SetTextColor",
         lua.create_function(
@@ -977,25 +701,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // GetTextColor() → r, g, b, a — **FOUR values** (`0x781100`, table `0x879d00`, argc 1, arity 4,
-    // kinds `(number,number,number,number)`), the same shape as the FontString/Font-object twins
-    // (`0x79d840` table `0x87c1d8`, `0x79f680`) this codebase already answers. Three is the
-    // plausible wrong answer, and the shapes table calls the name `name-not-unique` precisely
-    // because it is registered on seven tables; this is the Button one.
-    //
-    // **Read like `GetFont` right above, not like `SetTextColor` right above that.** The reference
-    // reads the colour back off the button's NORMAL embedded `CSimpleFont`, and an unset local
-    // colour there still resolves through what the normal state INHERITS
-    // (`<NormalFont>`/`SetTextFontObject`) — which is how a `GameMenuButtonTemplate` button answers
-    // `GameFontNormal`'s colour before anything calls `SetTextColor`. Falling back to white would
-    // be wrong in exactly the case the corpus cares about: reading a stock button's colour to
-    // restore it after a temporary recolour. White is the last resort, matching every other colour
-    // getter here (`GetVertexColor`, `FontString:GetTextColor`) — the untinted default a region
-    // with no colour anywhere draws at.
-    //
-    // Completeness rather than a live break: the census found no corpus site with a Button
-    // receiver (every measured `GetTextColor` call is on a FontString or a font object). It is here
-    // because the reference registers it and the widget shape gate can then cover it.
+    // GetTextColor() (`0x781100`) → r, g, b, a, four values, off the normal font: its own colour,
+    // else the inherited object's (`<NormalFont>`, `SetTextFontObject`), else white.
     m.set(
         "GetTextColor",
         lua.create_function(|lua, this: Table| {
@@ -1044,8 +751,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // LockHighlight/UnlockHighlight — pin the HighlightTexture on regardless of hover (ref
-    // CButton::LockHighlight; the dropdown kit's checked rows stay lit).
+    // LockHighlight (`0x782840`) and UnlockHighlight: the highlight shows regardless of hover.
     m.set(
         "LockHighlight",
         lua.create_function(|lua, this: Table| {
@@ -1067,28 +773,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "Disable",
         lua.create_function(|lua, this: Table| set_enabled(lua, &this, false))?,
     )?;
-    // IsEnabled() → the NUMBER 1 or the NUMBER 0 — never a boolean, and never nil.
-    //
-    // wow-re `ui/scratch/button-enabled-state.md`, VERIFIED off the Button method table at
-    // `0x879d10`: `IsEnabled 0x7800b0` reads the three-valued STATE at `[obj+0x328]`
-    // (0 DISABLED / 1 NORMAL / 2 PUSHED), does `setne cl` for "not disabled", and pushes that as a
-    // NUMBER. So the reference's own `IsEnabled() == 0` and `== 1` tests (FriendsFrame.lua l.404,
-    // StaticPopup.lua l.713) are live code.
-    //
-    // **This answered a Lua boolean until now, and the difference is not cosmetic, because 0 is
-    // TRUTHY in Lua.** A caller writing the reference's `== 0` got false forever; a caller writing
-    // `IsEnabled() > 0` got "attempt to compare number with boolean" — which is where pfUI's
-    // `api/ui-widgets.lua:812` icon-fade died, taking the widget module with it. The divergence was
-    // known and worked around by hand in three of our own files (FriendsFrame.xml's
-    // `guildButtonDisabled` read BOTH spellings and said so); those workarounds go with this
-    // change, which is 1719's bar — a prior call revisited because a new measurement arrived.
-    //
-    // Slider used to carry its own `IsEnabled` (slider.rs), left alone here because "whether the
-    // slider widget shares the contract is unverified". It does not share it — it does not HAVE
-    // one: 1.12 registers `Enable`/`Disable`/`IsEnabled` on this table alone, and the Slider's
-    // LoadXML `0x789580` has no `enabled` attribute either, so ours was a superset. The trio came
-    // off the Slider rather than being brought into line with this contract; see the note at its
-    // old site in `slider.rs`.
+    // IsEnabled() (`0x7800b0`) → the number 1 or 0 from the state at `+0x328`, never a boolean:
+    // 0 is truthy in Lua, and the stock UI tests `== 0` (`FriendsFrame.lua:404`) and `== 1`
+    // (`StaticPopup.lua:713`).
     m.set(
         "IsEnabled",
         lua.create_function(|lua, this: Table| {
@@ -1096,10 +783,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RegisterForClicks(...): replaces the button's registered-click set outright (the live API's
-    // contract — not additive) with its varargs, verbatim strings (`"LeftButtonUp"`,
-    // `"RightButtonDown"`, …). [`UiScript::mouse_button`] consults the set via [`wants_click`] to
-    // decide whether a press or a release reaches `OnClick`.
+    // RegisterForClicks(...) (`0x782490`) replaces the registered set rather than adding to it
+    // (`0x779730` stores the mask), matching the names in any case (`0x64a4c0`); [`wants_click`]
+    // reads it.
     m.set(
         "RegisterForClicks",
         lua.create_function(|lua, (this, args): (Table, MultiValue)| {
@@ -1113,21 +799,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // **`SetButtonState(state[, lock]) 0x780270` — TWO arguments**, and the second is not
-    // cosmetic (wow-re `scratch/binding-shape-arity-law.md` §3, VERIFIED). It reads three stack
-    // indices and returns none; the state maps case-insensitively over exactly
-    // `{"DISABLED", "NORMAL", "PUSHED"}` (`0x780390`, `SStrCmpI`) and an unrecognised string
-    // raises `Usage: %s:SetButtonState("state", lock)`; the flag is `GetBoolOrDefault` with
-    // **default 0** (`0x78032c push 0`), whose number arm truncates through `_ftol`, so the
-    // literal `1` that `MainMenuBarMicroButtons.lua` passes arms it.
-    //
-    // **The lock is the whole of decision 2134.** While it is set the button ignores the mouse
-    // press/release transitions; while it is clear, the next release un-pushes a scripted push —
-    // which is what Tablet-2.0's rows depend on, since the library pushes them and never calls
-    // `SetButtonState("NORMAL")` anywhere.
-    //
-    // DISABLED really is accepted here — the mapper takes it — even though the 1.12 FrameXML
-    // never passes it.
+    // SetButtonState(state [, lock]) (`0x780270`): DISABLED, NORMAL or PUSHED in any case
+    // (`0x780390`), else a usage error; `lock` is `GetBoolOrDefault` with default 0 (`0x78032c`),
+    // so the `1` of `MainMenuBarMicroButtons.lua:22` sets it. While locked, presses and releases
+    // leave the state alone; unlocked, the next release un-pushes a scripted push.
     m.set(
         "SetButtonState",
         lua.create_function(|lua, (this, state, lock): (Table, String, MultiValue)| {
@@ -1150,12 +825,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "GetButtonState",
         lua.create_function(|lua, this: Table| {
-            // ONE variable, read back (`0x780180` reads `[obj+0x328]`). This used to OR in the
-            // live mouse-held press, because the state was derived and the press lived outside
-            // the widget; now the press *wrote* the state at its edge, so a mouse-held button
-            // answers "PUSHED" for the same reason the reference does — and cannot disagree with
-            // the art the way a re-derived answer could (decision 2134). The chat scroll buttons'
-            // hold-repeat (ref `MessageFrameScrollButton_OnUpdate`) still reads what it needs.
+            // The latched state (`0x780180` reads `+0x328`): a held button answers PUSHED because
+            // its press wrote it, which the chat scroll repeat reads (`ChatFrame.lua:1588`).
             with_button(lua, &this, |bs| match bs.button_state() {
                 ButtonVisualState::Disabled => "DISABLED",
                 ButtonVisualState::Pushed => "PUSHED",
@@ -1164,7 +835,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Click([button]) — the programmatic click: same path as a physical one (toggle-then-OnClick).
+    // Click([button]) (`0x7826c0`): the physical click's path, toggle and `OnClick` alike.
     m.set(
         "Click",
         lua.create_function(|lua, (this, button): (Table, Option<String>)| {
@@ -1174,8 +845,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 model.frame_id(h)
             };
             let btn = button.unwrap_or_else(|| "LeftButton".to_string());
-            // A programmatic Click() always emulates a completed (released) click.
-            // A programmatic Click() — `scripted = true`, which only a LootButton reads.
+            // A released click, flagged as scripted, which only a LootButton reads.
             click_button(lua, id, &btn, false, true);
             Ok(())
         })?,
@@ -1183,22 +853,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     lua.set_named_registry_value(REG_BUTTON_METHODS, m)?;
 
-    // CheckButton's own table (consulted before Button's — the class chain).
+    // CheckButton's own table, consulted before Button's.
     let c = lua.create_table()?;
     texture_pair(lua, &c, "Checked", Slot::Checked)?;
     texture_pair(lua, &c, "DisabledChecked", Slot::DisabledChecked)?;
     c.set(
         "SetChecked",
         lua.create_function(|lua, (this, v): (Table, Value)| {
-            // Numeric coercion, NOT Lua truthiness — byte-verified (decision 0227; wow-re
-            // `system/ui/scratch/button-check-and-state-texture.md`, `SetChecked 0x799bf0` →
-            // `0x6f1c10`): a number goes through `lua_tonumber` then a truncate-to-int (`fistp`,
-            // round-toward-zero, `0x40a2b0`) and the C++ setter tests `!= 0`. So `SetChecked(0)`
-            // UNchecks (0 is Lua-truthy — only a numeric read gets this right) and `SetChecked(1)`
-            // checks; the type-dispatched helper also honors the keyword strings the reference
-            // passes ("true"/"false" — SpellBookFrame.lua l.296-303), while a non-keyword string
-            // falls to tonumber (→ 0 → unchecked). nil/other → false; booleans honored as-is for
-            // this codebase's own Era-style callers.
+            // `SetChecked` (`0x799bf0`) reads its argument through `0x6f1c10` with default 1
+            // (`0x799c77`), not Lua truthiness: a number truncates toward zero (`0x40a2b0`), so
+            // `SetChecked(0)` unchecks, and the stock UI passes `"true"`/`"false"`
+            // (`SpellBookFrame.lua:296-303`). Here a missing argument unchecks and a string checks
+            // only as `"true"` or a nonzero number, where the reference checks for a missing one
+            // and reads a string by its first byte, so `"yes"` checks there.
             let checked = match v {
                 Value::Boolean(b) => b,
                 Value::Integer(i) => i != 0,
@@ -1214,13 +881,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     c.set(
-        // GetChecked() -> the NUMBER 1 or nil, never a boolean (1830). Its neighbour
-        // `IsEnabled` two entries up was corrected for the same reason under 1719, whose comment
-        // records that a boolean here killed pfUI's widget module outright; this is that call
-        // finished. The reference proves the shape in its own source rather than only at the
-        // bytes: stock `UIOptionsFrame.xml:310` saves a checkbox as
-        // `tostring(this:GetChecked())` and stock `BuffFrame.lua:71` reads it back as `== "1"`,
-        // a round-trip that only closes on the number.
+        // GetChecked() → the number 1 or nil, never a boolean: `UIOptionsFrame.xml:310` saves
+        // `tostring(this:GetChecked())` and `BuffFrame.lua:71` compares it with `"1"`.
         "GetChecked",
         lua.create_function(|lua, this: Table| {
             let checked = with_button(lua, &this, |bs| bs.checked)?;
@@ -1232,12 +894,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Whether frame `h` should fire `OnClick` for the input transition `name`
-/// (`"<Button>ButtonUp"`/`"<Button>ButtonDown"`, e.g. `"RightButtonDown"`) — the
-/// [`UiScript::mouse_button`](super::UiScript::mouse_button) gate. A Button/CheckButton consults
-/// its `RegisterForClicks` set (case-insensitively — the live API is forgiving of case); any
-/// other kind with an `OnClick` fires exactly as it always has, before `RegisterForClicks`
-/// existed: on release only (`name` ending `"Up"`), for any button, never on press.
+/// Whether `h` fires `OnClick` for the transition `name` (e.g. `"RightButtonDown"`): a Button
+/// checks its `RegisterForClicks` set, ignoring case; any other kind fires on release only.
 pub(super) fn wants_click(model: &Model, h: FrameHandle, name: &str) -> bool {
     match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::Button(bs)) => bs
@@ -1248,28 +906,10 @@ pub(super) fn wants_click(model: &Model, h: FrameHandle, name: &str) -> bool {
     }
 }
 
-/// Whether frame `h` is registered for `button` (`"LeftButton"`, `"RightButton"`, …) in **either**
-/// variant — the press-visual gate, which is a strictly weaker test than [`wants_click`]'s.
-///
-/// `CButton::OnMouseDown 0x779210` runs the two as separate tests in one pass, and the difference
-/// between them is the whole of this:
-///
-/// ```text
-/// 0x779238  eax = event.buttonMask
-/// 0x779243  ecx = eax << 8 | eax
-/// 0x77924b  test [this+0x330], ecx   ; registered EITHER WAY -> keep going, else nothing at all
-/// 0x779256  hit-test the point       ; else nothing
-/// 0x77926b  test event.buttonMask, [this+0x330]  ; the DOWN bits alone -> fire OnClick
-/// 0x7792ad  push 2 ; SetState(PUSHED)            ; unconditional past the gates above
-/// ```
-///
-/// So `[this+0x330]` is one dword holding the `"…ButtonDown"` registrations in byte 0 and the
-/// `"…ButtonUp"` registrations in byte 1, and the mask `m | m << 8` asks "this button, either
-/// variant". **The pushed art is not conditional on the click firing, or on the handler doing
-/// anything** — it is conditional only on the button being registered for that mouse button at
-/// all, which is why a right-click on an action, spellbook or pet slot lights up even when the
-/// right-click does nothing (they all register `RightButtonUp`), and why a right-click on a plain
-/// `LeftButtonUp` button does not.
+/// Whether `h` is registered for `button` (`"LeftButton"`, …) as Up or Down, the press-art gate.
+/// `OnMouseDown` (`0x779210`) tests `m | m << 8` against `[this+0x330]` (Down in byte 0, Up in
+/// byte 1, `0x77924b`) before the Down-only `OnClick` test (`0x77926b`), so any registration for
+/// that button pushes the art, click or not.
 pub(super) fn wants_press_visual(model: &Model, h: FrameHandle, button: &str) -> bool {
     match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::Button(bs)) => bs.registered_clicks.iter().any(|s| {
@@ -1281,18 +921,12 @@ pub(super) fn wants_press_visual(model: &Model, h: FrameHandle, button: &str) ->
     }
 }
 
-/// The click behavior shared by the input path and `Click()`: gated on `enabled`; a CheckButton
-/// **toggles before OnClick fires** (the documented widget contract — a handler reading
-/// `self:GetChecked()` sees the new state); then `OnClick(self, button, down)` — `down` is `true`
-/// only for a press that fired via a `"<Button>ButtonDown"` registration, `false` for every
-/// release-fired or programmatic click (the Era signature: `down` mirrors which transition fired).
-///
-/// `scripted` says the click came from Lua `:Click()` rather than from hardware — the reference's
-/// second `OnClick` argument (`0` from `0x779280`/`0x7793a4`, `1` from the `Button:Click` binding
-/// `0x7826c0`). Only [`crate::widget::FrameKind::LootButton`] reads it, and it reads it as a hard
-/// gate: `0x4c182b` returns before the base call, so **a scripted click on a loot row does
-/// nothing at all — not even run the row's own Lua `OnClick`**. Every other kind ignores it, which
-/// is the reference's shape too (the base `0x779540` never looks at the flag).
+/// The click shared by the input path and `Click()`: a disabled Button fires nothing, a CheckButton
+/// toggles before `OnClick` runs (`0x785550`), then `OnClick` gets the button name and `down`, true
+/// only for a click a `…ButtonDown` registration fired. The second argument is not 1.12's, whose
+/// `OnClick` gets the name alone (`0x779540`). `scripted` marks a Lua `Click()` (`0x7826c0` passes
+/// 1, the mouse `0x779280`/`0x7793a4` pass 0): a LootButton then does nothing at all, not even its
+/// `OnClick` (`0x4c182b`); every other kind ignores it.
 pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripted: bool) {
     let mut take_loot = None;
     let fire = {
@@ -1308,12 +942,10 @@ pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripte
             if scripted {
                 return;
             }
-            // Read the take BEFORE the handler runs, but queue it after: the reference reads
-            // `[esi+0x4dc]` after the base call, and a handler that re-slots its own row mid-click
-            // is not a case the shipped UI produces — reading first keeps the borrow simple and
-            // the two cannot disagree. The modifier gate is `0x4c183a`/`0x4c1848`/`0x4c1856`:
-            // shift, ctrl OR alt suppresses, and it is the whole reason the shipped
-            // `LootFrameItem_OnClick` never calls a take itself.
+            // Deviation: the slot is read before the handler, where the reference reads it after
+            // (`[esi+0x4dc]`), because reading first keeps the borrow simple and no stock handler
+            // re-slots its row. Shift, ctrl or alt suppresses the take (`0x4c183a`/`0x4c1848`/
+            // `0x4c1856`).
             let (shift, ctrl, alt) = model.modifiers;
             if !shift && !ctrl && !alt {
                 take_loot = model.arena.frame(h).and_then(|f| match &f.kind_state {
@@ -1327,7 +959,7 @@ pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripte
         };
         let is_check = frame.kind == FrameKind::CheckButton;
         match &mut frame.kind_state {
-            // A Button/CheckButton click is gated on its enabled flag…
+            // A Button fires only while enabled;
             KindState::Button(bs) => {
                 if bs.enabled() {
                     if is_check {
@@ -1338,7 +970,7 @@ pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripte
                     false
                 }
             }
-            // …every other kind with an OnClick just fires (plain frames can carry one too).
+            // any other kind with an `OnClick` just fires.
             _ => true,
         }
     };
@@ -1353,24 +985,18 @@ pub(super) fn click_button(lua: &Lua, id: u32, button: &str, down: bool, scripte
     {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
-    // **A nameplate's click is the engine's too** (decision 2148): the reference's plate overrides
-    // the button click slot (`0x7cb910`) *and* chains the base, so its unit is selected whether the
-    // click came from the pointer or from Lua's own `Click()` — this funnel is both. Recorded after
-    // the handler, like the loot take below and for the same reason: an addon hook that errors
-    // cannot silently eat the selection. A press (`down`) records nothing — the plate registers for
-    // `LeftButtonUp | RightButtonUp` only (`RegisterForClicks(0x500)` at `0x7cb637`).
+    // A nameplate click selects its unit, from the pointer or `Click()` alike (the plate's
+    // override `0x7cb910` chains the base), after the handler so an erroring hook cannot eat it. A
+    // press selects nothing: the plate registers Up clicks only (`0x7cb637`).
     if !down {
         super::nameplate::note_click(lua, id, button);
     }
-    // …and then the take, unconditionally on the handler's outcome. `0x4c1867` is not guarded by
-    // anything the Lua side did: the base call at `0x4c1833` returns void and its result is never
-    // tested. A row whose `OnClick` errored still loots, which is the reference's behaviour and
-    // the reason a broken addon hook cannot silently eat your loot.
+    // The take runs whatever the handler did (`0x4c1867`): a row whose `OnClick` errored still
+    // loots.
     if let Some(slot) = take_loot {
-        // The 0-based store, back to the 1-based display row the take queue speaks.
+        // The slot is 0-based; the take queue speaks the 1-based row.
         lua.app_data_mut::<Model>()
             .expect("model app_data")
             .loot_picks
diff --git a/crates/benilla-ui/src/script/camera_view.rs b/crates/benilla-ui/src/script/camera_view.rs
index 93b56703..9d7026bf 100644
--- a/crates/benilla-ui/src/script/camera_view.rs
+++ b/crates/benilla-ui/src/script/camera_view.rs
@@ -1,103 +1,50 @@
-//! The **five camera views** — `SetView` / `SaveView` / `ResetView` / `NextView` / `PrevView`,
-//! plus `FlipCameraYaw`: the outbound half of the reference's `UIUtil\Camera.cpp` Lua surface.
+//! The camera-view verbs from the reference's Lua table at `0x84f7a0`: `SetView`, `SaveView`,
+//! `ResetView`, `NextView`, `PrevView` and `FlipCameraYaw`. Each acts on engine state the VM does
+//! not hold, so each call queues a [`CameraViewRequest`] for the app's camera rig.
 //!
-//! Six globals, no state — [`super::follow`]'s shape exactly. Nothing here reads the camera: every
-//! one of these is an **engine action** over state this VM does not hold (the orbit arm, the pitch,
-//! the character's facing, the zoom ceiling), so each call queues a [`CameraViewRequest`] the app
-//! drains ([`super::UiScript::take_camera_view_requests`]) and applies to the rig
-//! (`benilla_app::player::camera_view`). The alternative — reaching into the ECS from inside the
-//! VM — is the thing decision 0068 §3 exists to forbid.
-//!
-//! **Where they come from.** The reference registers them in one table, `0x84f7a0` (`{const char*
-//! name; handler}` pairs, dumped from `WoW.exe` 5875): rows 15…20 are `SetView 0x50b5b0`,
-//! `SaveView 0x50b600`, `ResetView 0x50b640`, `NextView 0x50b680`, `PrevView 0x50b690`,
-//! `FlipCameraYaw 0x50b6a0`. Sixteen 1.12 binding commands have one of these as their whole body
-//! (`SETVIEW1`…`5`, `SAVEVIEW2`…`5`, `RESETVIEW2`…`5`, `NEXTVIEW`, `PREVVIEW`, `FLIPCAMERAYAW`).
-//!
-//! ## The argument ABI is a third shape, and it is neither of [`super::binding_abi`]'s two
-//!
-//! The four indexed entry points share one prologue, byte-identical across `0x50b5b0` /
-//! `0x50b600` / `0x50b640`:
-//!
-//! ```text
-//! 50b5b8  call 0x6f34d0          ; is-number(L, 1)  — a number, or a coercible string
-//! 50b5bf  je   <exit>            ; NOT a number -> xor eax,eax ; ret   (silent, zero Lua values)
-//! 50b5c8  call 0x6f3620          ; tonumber(L, 1)
-//! 50b5cd  call 0x40a2b0          ; double -> int32, truncating toward zero
-//! 50b5d4  jle  <exit>            ; n <= 0  -> silent
-//! 50b5d9  jg   <exit>            ; n >  5  -> silent
-//! 50b5e5  dec  eax               ; Lua 1..5  ->  internal view 0..4
-//! ```
-//!
-//! So the failure edge **returns without raising** — it never reaches `luaL_error 0x6f4940`, which
-//! is the discriminator [`super::binding_abi`]'s header sets out. A macro doing `SetView(0)`,
-//! `SetView(9)`, `SetView("left")` or `SetView()` is a silent no-op in the real client, and is one
-//! here. That rules out `binding_abi::number_arg` (shape A — raises) and makes
-//! `binding_abi::coerced_number` (shape C — no guard, defaults to `0.0`) merely *accidentally*
-//! right, so the guard is written out rather than borrowed.
-//!
-//! `FlipCameraYaw` takes the same is-number guard and then the raw float — `0x6f3620` straight to
-//! `fstp [ebp-4]`, with no `0x40a2b0` — so its argument is **not** truncated to an integer.
-//!
-//! ## Two verified facts that a reader will expect to be otherwise
-//!
-//! - **The range is 1…5 for all three of Set/Save/Reset.** `SaveView(1)` and `ResetView(1)` are
-//!   accepted by the engine and act on `FIRST_PERSON`; `0x50fa30` (SaveView's body) has no view-0
-//!   gate at all. 1.12 ships no `SAVEVIEW1`/`RESETVIEW1` *binding*, which is a `Bindings.xml`
-//!   decision, not an engine one — a macro reaches what the keybinding cannot.
-//! - **`NextView`/`PrevView` do not wrap.** `0x50faa0` is `eax = view + 1; cmp eax,5; jge <ret>`
-//!   and `0x50fac0` is `test eax,eax; jle <ret>; dec eax` — each is a hard stop at its end of the
-//!   range, so holding `END` walks 1→2→3→4→5 and stays there. The app enforces it (this side only
-//!   queues the verb).
+//! The indexed verbs share one prologue and return silently, never reaching `luaL_error`
+//! (`0x6f4940`), on anything but a number that truncates to 1 to 5; `FlipCameraYaw` keeps its
+//! argument's fraction. `SaveView(1)` and `ResetView(1)` act on first person (`0x50fa30` has no
+//! view-0 gate; only `Bindings.xml` lacks the bindings). `NextView` and `PrevView` stop at the
+//! ends and never wrap (`0x50faa0`, `0x50fac0`).
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// The number of camera views — the reference's default-string table `0x84f488` is five rows, and
-/// every entry point above is bounded by it.
+/// The number of camera views, the rows of the reference's default-string table `0x84f488`.
 pub const CAMERA_VIEW_COUNT: u8 = 5;
 
-/// One camera-view intent queued by the Lua surface, drained by the app
-/// ([`super::UiScript::take_camera_view_requests`]). Plain data — [`super::follow::FollowRequest`]'s
-/// twin.
-///
-/// The indices are the **internal** ones, `0..CAMERA_VIEW_COUNT`, already range-checked here
-/// exactly where the reference range-checks them (its Lua handler, `dec eax`). The app applies
-/// them; it never re-validates a number that cannot be out of range.
+/// A camera-view intent for the app. Indices are internal, `0..CAMERA_VIEW_COUNT`, range-checked
+/// here where the reference checks them, in the Lua handler.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum CameraViewRequest {
-    /// `SetView(n)` — make view `n-1` the live one (distance, pitch and the saved yaw offset).
+    /// `SetView(n)`: make view `n-1` live (distance, pitch and the saved yaw offset).
     Set(u8),
-    /// `SaveView(n)` — store the live pose into view `n-1`.
+    /// `SaveView(n)`: store the live pose into view `n-1`.
     Save(u8),
-    /// `ResetView(n)` — put view `n-1` back to its shipped default.
+    /// `ResetView(n)`: put view `n-1` back to its shipped default.
     Reset(u8),
-    /// `NextView()` — the view above the current one, if there is one (no wrap).
+    /// `NextView()`: the view above the current one, if any.
     Next,
-    /// `PrevView()` — the view below the current one, if there is one (no wrap).
+    /// `PrevView()`: the view below the current one, if any.
     Prev,
-    /// `FlipCameraYaw(degrees)` — add this many **degrees** to the camera's yaw. The binding body
-    /// 1.12 ships is `FlipCameraYaw(180)`.
+    /// `FlipCameraYaw(degrees)`: add degrees to the camera's yaw; `Bindings.xml:795` passes 180.
     FlipYaw(f32),
 }
 
 impl super::UiScript {
-    /// Drain the camera-view intents queued since the last call — the app applies each to the
-    /// camera rig.
+    /// Drain the camera-view intents queued since the last call.
     pub fn take_camera_view_requests(&mut self) -> Vec<CameraViewRequest> {
         std::mem::take(&mut self.model_mut().camera_view_requests)
     }
 }
 
-/// The shared prologue of `SetView`/`SaveView`/`ResetView`: `is-number` → `tonumber` → truncate to
-/// `i32` → the `1 ..= 5` window → the internal index. `None` is every silent-return edge in one.
+/// The indexed verbs' shared prologue: the internal index, or `None` for a silent return.
 fn view_arg(lua: &Lua, v: Value) -> Option<u8> {
-    // `0x6f34d0` is-number, then `0x6f3620` tonumber, then `0x40a2b0`'s chop-toward-zero cast —
-    // `lua.coerce_number` is the first two (Lua coerces a numeric string), `as i64 as i32` the
-    // third (see `binding_abi::number_arg`, whose only difference from this is that it raises).
+    // Is-number (`0x6f34d0`) and `tonumber` (`0x6f3620`) take a numeric string; the cast
+    // truncates toward zero, as `0x40a2b0` does.
     let n = lua.coerce_number(v).ok().flatten()? as i64 as i32;
-    // `test eax,eax; jle` then `cmp eax,5; jg` — both silent.
     (1..=i32::from(CAMERA_VIEW_COUNT))
         .contains(&n)
         .then(|| (n - 1) as u8)
@@ -107,9 +54,8 @@ fn view_arg(lua: &Lua, v: Value) -> Option<u8> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // SetView(n) — `0x50b5b0`. Load view n (1..5). The reference then calls `0x512e90(view,
-    // cameraViewBlendStyle)`, which also writes the `cameraView` CVar so the active view survives
-    // a restart; the app does both halves.
+    // SetView(n), `0x50b5b0`. The reference's `0x512e90` also writes the `cameraView` CVar, so
+    // the view survives a restart; the app does both.
     g.set(
         "SetView",
         lua.create_function(|lua, n: Value| {
@@ -123,9 +69,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SaveView(n) — `0x50b600` → `0x50fa30`, which reads the camera's three TARGET fields
-    // (`+0x198` distance, `+0x1e0` pitch, `+0x210` yaw) into the slot array and writes each to its
-    // archived CVar. Accepts n = 1 (see the module header).
+    // SaveView(n), `0x50b600` → `0x50fa30`: the camera's target distance, pitch and yaw go into
+    // the slot and each to its archived CVar.
     g.set(
         "SaveView",
         lua.create_function(|lua, n: Value| {
@@ -139,8 +84,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ResetView(n) — `0x50b640` → `0x50fae0`, which re-parses the shipped default strings at
-    // `0x84f488 + 12·view` into the slot and re-applies the view if it is the live one.
+    // ResetView(n), `0x50b640` → `0x50fae0`: re-parses the view's default string (`0x84f488`)
+    // into the slot and re-applies the view if it is live.
     g.set(
         "ResetView",
         lua.create_function(|lua, n: Value| {
@@ -154,8 +99,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // NextView() / PrevView() — `0x50b680` → `0x50faa0` and `0x50b690` → `0x50fac0`. No arguments
-    // at all: neither handler touches the Lua stack. Neither wraps.
+    // NextView() and PrevView(), `0x50b680` and `0x50b690`: neither reads the Lua stack.
     g.set(
         "NextView",
         lua.create_function(|lua, ()| {
@@ -173,9 +117,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // FlipCameraYaw(degrees) — `0x50b6a0`, the whole body being
-    // `cam[+0x100] += arg × 0.01745329238474369`. Its argument keeps its fraction (no `0x40a2b0`),
-    // and the is-number guard's failure edge is the same silent return the four above take.
+    // FlipCameraYaw(degrees), `0x50b6a0`: adds `degrees × π/180` to the camera's yaw, fraction
+    // kept; a non-number returns silently.
     g.set(
         "FlipCameraYaw",
         lua.create_function(|lua, degrees: Value| {
diff --git a/crates/benilla-ui/src/script/channel.rs b/crates/benilla-ui/src/script/channel.rs
index 8e3a879c..7f44a22b 100644
--- a/crates/benilla-ui/src/script/channel.rs
+++ b/crates/benilla-ui/src/script/channel.rs
@@ -1,42 +1,15 @@
-//! `GetChannelName` — the joined-channel lookup, in both directions.
-//!
-//! **The state this reads already existed and was built for this verb.** `ui_chat::edit`'s
-//! `ChannelState` has held `joined: Vec<String>` in join order since the chat arc, and its own doc
-//! comment names `GetChannelName(n)` as the law it implements. Only the registration was missing —
-//! the same silent-gap shape the loader arc kept finding, one layer up: the capability was built,
-//! nothing exposed it, and nothing complained.
-//!
-//! Corpus demand, counted by reading every line rather than the grep total (1207): **17 sites
-//! across 6 addons**, every one an unguarded call, no library replicated —
-//! `ChatLog` 7, `Recap` 4, `SmartRes` 2, `Enchantrix` 2, `FuBar_AssistFu` 1, `_LazyPig` 1. Both
-//! lookup directions are live in the corpus: by index (`GetChannelName(i)`) and by name
-//! (`GetChannelName("world")`, `GetChannelName("Trade - City")`).
-//!
-//! Signature verified against wow-5875-re `system/ui/scratch/zone-chat-channel-autojoin.md`
-//! l.374-380 — `GetChannelName = 0x4a05e0`, **three** returns:
-//!
-//! | # | the client's | ours |
-//! |---|---|---|
-//! | 1 | `slot[+0x00]`, the client-local **1-based joined-slot index** (= `CHAT_MSG_*` arg8) | the position in `joined` |
-//! | 2 | `slot[+0x04]`, the channel name | the `joined` entry |
-//! | 3 | `slot[+0x98]`, FrameXML's `instanceID` (= arg10) | **0** — see below |
-//!
-//! **Return 3 is 0, not nil, and that is a recorded position rather than a shrug.** It is the split
-//! index from `YOU_JOINED`'s second u32, which `ui_chat::event`'s doc already records as "0 on every
-//! vanilla emulator" and deliberately does not store. A client that one day meets a server which
-//! splits channels would need the field; nothing in the corpus reads it.
+//! The chat-channel globals: the joined-channel lookups, the join, leave and management verbs the
+//! app sends, and the guild-recruitment auto-join latch. `GetChannelName` (`0x4a05e0`) looks up by
+//! 1-based slot or by name and returns three values: the slot (`CHAT_MSG_*` arg8), the name and
+//! `instanceID` (arg10).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The 1-based slot of `name`, case-insensitively — `GetChannelName`'s first return.
-/// One `ChatChannels.dbc` row as the VM needs it for `JoinChannelByName` (decision 1908),
-/// `Add/RemoveChatWindowChannel` and `EnumerateServerChannels` (wow-re chat-cache-grammar.md
-/// §5-6): the id, the **Shortcut** (`General`, `Trade`, … — what every one of those verbs compares
-/// a typed name against, whole and case-folded), the name composed for the zone the player is in
-/// (`General - Elwynn Forest`; `None` while the zone text is empty, which is the verbs' nil leg),
-/// and whether the row is listed here at all (a `flags & 0x10` city row is, only in a city).
+/// One `ChatChannels.dbc` row for the channel verbs: the id, the Shortcut a typed name is matched
+/// against case-folded, the name composed for the player's zone (`None` while the zone text is
+/// empty, the verbs' nil leg), and whether it is listed (a `flags & 0x10` city row only in a city).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ZoneChannelRow {
     pub id: u32,
@@ -45,12 +18,11 @@ pub struct ZoneChannelRow {
     pub listed: bool,
 }
 
-/// A channel verb's ask, drained by the app into its `CMSG_*` (all of which
-/// `benilla-protocol::messages::client` already builds). The verbs are the stock
-/// `ChatFrame.lua` slash handlers' calls, one variant each.
+/// A channel verb's ask, drained by the app into its `CMSG_*`: the stock `ChatFrame.lua` slash
+/// handlers' calls, one variant each.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum ChannelCommand {
-    /// `JoinChannelByName(name, password)` — sent on both of 1908's non-nil legs.
+    /// `JoinChannelByName(name, password)`, sent on both non-nil legs.
     Join {
         name: String,
         password: String,
@@ -59,13 +31,13 @@ pub enum ChannelCommand {
     Leave {
         name: String,
     },
-    /// `ListChannelByName(name)` — `CMSG_CHANNEL_LIST`.
+    /// `ListChannelByName(name)`: `CMSG_CHANNEL_LIST`.
     List {
         name: String,
     },
-    /// `ListChannels()` — the roster of every joined channel.
+    /// `ListChannels()`: the roster of every joined channel.
     ListAll,
-    /// `DisplayChannelOwner(name)` — `CMSG_CHANNEL_OWNER`.
+    /// `DisplayChannelOwner(name)`: `CMSG_CHANNEL_OWNER`.
     DisplayOwner {
         name: String,
     },
@@ -111,7 +83,7 @@ pub enum ChannelCommand {
         name: String,
         player: String,
     },
-    /// `ChannelModerate(name)` — toggles moderation.
+    /// `ChannelModerate(name)`: toggles moderation.
     Moderate {
         name: String,
     },
@@ -122,8 +94,7 @@ pub enum ChannelCommand {
 }
 
 impl super::UiScript {
-    /// The zone-channel catalog for the player's current zone — fed whenever the zone (and so
-    /// every resolved name) changes.
+    /// Feed the zone-channel catalog, whenever the zone, and so every resolved name, changes.
     pub fn set_zone_channel_catalog(&mut self, rows: Vec<ZoneChannelRow>) {
         self.model_mut().zone_channel_catalog = rows;
     }
@@ -133,35 +104,33 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().channel_commands)
     }
 
-    /// The guild-recruitment auto-join latch — `0` STANDARD, `1` AUTO (decision 2115).
+    /// The guild-recruitment auto-join latch: `0` STANDARD, `1` AUTO.
     pub fn guild_recruitment_mode(&self) -> u8 {
         self.model_ref().guild_recruitment_mode
     }
 
-    /// Seat the latch from the host (the per-character chat cache at login). A host write is not
-    /// a player gesture, so it does **not** arm [`Self::take_guild_recruitment_change`] — the same
-    /// split `set_cvar_from_host` keeps one store over, and what stops a login from composing the
-    /// player's file out of a value the login itself just read.
+    /// Seat the latch from the chat cache at login. A host write is not a player gesture, so it
+    /// does not arm [`Self::take_guild_recruitment_change`]: a login must not save what it read.
     pub fn set_guild_recruitment_mode(&mut self, mode: u8) {
         let mut model = self.model_mut();
         model.guild_recruitment_mode = mode;
         model.guild_recruitment_changed = false;
     }
 
-    /// Has Lua moved the latch since the last drain? The chat cache's dirty signal.
+    /// Whether Lua moved the latch since the last drain: the chat cache's dirty signal.
     pub fn take_guild_recruitment_change(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().guild_recruitment_changed)
     }
 
-    /// Has Lua called `SetGuildRecruitmentMode(1)` since the last drain? The cascade's cue
-    /// (`0x49ea70` → `0x49ea90`; decision 2144).
+    /// Whether Lua called `SetGuildRecruitmentMode(1)` since the last drain: the cue for the
+    /// cascade (`0x49ea70` → `0x49ea90`).
     pub fn take_guild_recruitment_cascade(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().guild_recruitment_cascade)
     }
 
-    /// **A manual join or leave of `GuildRecruitment` forces the latch to 0** — the reference's
-    /// `0x49ed3d`/`0x49ef8f`, `call 0x49ea70(0)`: a player gesture, so unlike the host seat it
-    /// **does** arm the save. No cascade (mode 0 is the latch alone). Answers whether it moved.
+    /// A manual join or leave of `GuildRecruitment` forces the latch to 0 (`0x49ed3d`, `0x49ef8f`)
+    /// and, as a player gesture, arms the save; mode 0 has no cascade, and the cascade's own join
+    /// passes a flag that skips this reset. Returns whether the latch moved.
     pub fn reset_guild_recruitment_mode(&mut self) -> bool {
         let mut model = self.model_mut();
         if model.guild_recruitment_mode == 0 {
@@ -190,12 +159,9 @@ fn slot_of(model: &Model, name: &str) -> Option<usize> {
         .map(|i| i + 1)
 }
 
-/// The name occupying slot `n` (1-based), or `None` for out of range **or a freed slot**.
-///
-/// The hole case is the reference's, not a convenience: its by-index lookup `0x49bf30` bounds-checks
-/// against the record count and then demands the entry's own number field equal the index asked for
-/// (`cmp esi,ecx / jnz`), which a leave zeroed (`0x49bbd0`). So a channel left is a number that
-/// answers "not joined" while every channel above it keeps its own (1286).
+/// The name in slot `n` (1-based), `None` out of range or for a freed slot: the reference's lookup
+/// `0x49bf30` requires the entry's own number to equal `n`, which a leave zeroes (`0x49bbd0`), so a
+/// left channel's number answers "not joined" while every channel above it keeps its own.
 fn name_at(model: &Model, n: usize) -> Option<&str> {
     model.joined_channels.get(n.checked_sub(1)?)?.as_deref()
 }
@@ -203,82 +169,33 @@ fn name_at(model: &Model, n: usize) -> Option<&str> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ── The guild-recruitment auto-join pair (decision 2115) ──────────────────────────────────
-    //
-    // `GetGuildRecruitmentMode 0x4a0040` / `SetGuildRecruitmentMode 0x4a0060` — the store behind
-    // the reference's *Auto-join the Guild Recruitment Channel* option
-    // (`UIOptionsFrameCheckButtons["AUTO_JOIN_GUILD_CHANNEL"]`, index 51). The table entry is a
-    // bare `{ index = 51 }` with no cvar and no uvar, which reads as "unbound" and is not: the
-    // store is the three special-case arms `UIOptionsFrame_Load` (l.243-248), `_Save` (l.326-331)
-    // and `_SetDefaults` (l.649) keep for that key. Exactly the `SHOW_TUTORIALS` shape decision
-    // 2077 corrected, and this tree's own `OptionsFrame.xml` carried the wrong reading until 2115.
-    //
-    // Every byte fact below is wow-re `system/ui/scratch/guild-recruitment-mode.md`, a §5 round
-    // dispatched for this work.
-    //
-    // **The state is one int** — the reference's `[0x843608]`, written only by `0x49ea70`
-    // (`mov ds:0x843608,ecx`; five call sites, no address-takes) and read by the Lua getter and by
-    // the chat-cache writer. Ours is `Model::guild_recruitment_mode`, seated at login and rendered
-    // back out by `ui_chat::settings`; the whole round trip is that file's one
-    // `OPTION_GUILD_RECRUITMENT_CHANNEL STANDARD|AUTO` line, written at teardown (`0x499a80` at
-    // `0x499b0e`: `latch == 1` → `AUTO`, else `STANDARD`), never at set time.
-    //
-    // **It boots at 1 (AUTO)**, and that is a `.data` initialiser rather than a BSS zero — `raw
-    // 0x443608` is `01 00 00 00` — corroborated twice over: `_SetDefaults` calls
-    // `SetGuildRecruitmentMode(1)`, and all 33 `chat-cache.txt` files the reference client itself
-    // wrote in this repo's install say `AUTO`. See `Model::guild_recruitment_mode`.
+    // ── The guild-recruitment auto-join pair ──────────────────────────────────
+    // `GetGuildRecruitmentMode` (`0x4a0040`) and `SetGuildRecruitmentMode` (`0x4a0060`) store the
+    // Auto-join Guild Recruitment Channel option, which has no cvar: `UIOptionsFrame.lua` binds it
+    // by special arms (`:243`, `:328`, `:647`). The state is one int, `[0x843608]`, a `.data`
+    // initialiser of 1 written only by `0x49ea70`, and the chat cache saves it at teardown
+    // (`0x499a80`), never at set time.
     g.set(
         "GetGuildRecruitmentMode",
-        // `[0x4a0040, 0x4a0057)` is 23 bytes and one path: `fild dword [0x843608]` (signed i32),
-        // `fstp qword [esp]`, `lua_pushnumber`, `mov eax,1`, `ret`. No arguments, no gates — a
-        // NUMBER, always, never nil. `UIOptionsFrame_Load` compares it `== 1`, so a nil here would
-        // read as a silent "not auto".
+        // Always a number, never nil: `UIOptionsFrame_Load` tests it `== 1`.
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             Ok(f64::from(model.guild_recruitment_mode))
         })?,
     )?;
-    // ── The `ecx == 1` cascade (decision 2144) ──────────────────────────────────────────
-    // `0x49ea70` writes the latch and then tail-jumps into `0x49ea90` **only when the new
-    // mode is 1**, and `0x49ea90` is not bookkeeping — it acts, on the wire: a guilded
-    // player leaves `GuildRecruitment - City`, an unguilded one in a capital joins it, and
-    // otherwise the one-shot `[0xb6e5e4]` is armed for the next autojoin pass. The whole of
-    // it lives on the app side (`ui_chat::recruitment`), where the player's guild id, the
-    // zone row and the wire are; this binding only raises the ask
-    // (`take_guild_recruitment_cascade`). `Set(0)` is the latch alone — `0x49ea70`'s `jne`
-    // stops at `0x49ea80`, no packet.
-    //
-    // The verb itself fires `UPDATE_CHAT_WINDOWS` once (`0x4a00a9`), unconditionally; the
-    // cascade's two acting arms fire it again, so an acting `Set(1)` fires it twice.
-    //
-    // The mirror: `JoinChannelByName("GuildRecruitment")` (`0x49ed3d`) and
-    // `LeaveChannelByName` (`0x49ef8f`) each force the latch back to 0 — the join's reset is
-    // conditional on the caller's `flag` argument, which the Lua binding passes as 1 and
-    // `0x49ea90`'s own internal join passes as 0 (so the cascade does not undo the mode it
-    // is acting on). That is `reset_guild_recruitment_mode`, called from the app's drain of
-    // both verbs.
+    // ── The `ecx == 1` cascade ──────────────────────────────────────────
+    // For mode 1 only, `0x49ea70` tail-jumps into `0x49ea90`, which acts on the wire (a guilded
+    // player leaves `GuildRecruitment - City`, an unguilded one in a capital joins it); that runs
+    // app-side in `ui_chat::recruitment`, and an acting cascade fires `UPDATE_CHAT_WINDOWS` again.
     g.set(
         "SetGuildRecruitmentMode",
-        // `[0x4a0060, 0x4a00c4)`. One argument at stack index 1, and **two ways to raise** — this
-        // is a shape-A binding (wow-re `numeric-arg-coercion-law.md`), not one of the many that
-        // swallow a nil:
-        //
-        //   * `lua_isnumber 0x6f34d0` — so a NUMERIC STRING passes (`"1"` works) — else
-        //     `luaL_error("Usage: SetGuildRecruitmentMode(mode)")`, which longjmps.
-        //   * then `__ftol 0x40a2b0`, **truncating toward zero**, so `1.7` is silently accepted as
-        //     1 and `-0.5` as 0.
-        //   * then the range gate `0x4a0094 jl` / `0x4a009b jge 2` →
-        //     `luaL_error("SetGuildRecruitmentMode: invalid mode")` for `-1`, `2`, `-1.7`.
-        //
-        // Success returns **0 values** (`xor eax,eax; ret`), not nil. Stock FrameXML can reach
-        // neither raise: `UIOptionsFrame_Save` passes `button:GetChecked()` and coerces its nil to
-        // 0 itself. An ADDON can, and getting the raise right is the difference between an addon
-        // seeing its own bug and seeing ours.
+        // As `0x4a0060`: `lua_isnumber` (`0x6f34d0`, so `"1"` passes), truncation toward zero
+        // (`0x40a2b0`), then the 0..2 range gate (`0x4a0094`); success returns zero values.
         lua.create_function(|lua, mode: Option<Value>| {
             let n = match mode.as_ref() {
                 Some(Value::Integer(i)) => *i as f64,
                 Some(Value::Number(n)) => *n,
-                // `lua_isnumber` is true for a string luaO_str2d fully consumes.
+                // `lua_isnumber` is true for a string `luaO_str2d` fully consumes.
                 Some(Value::String(s)) => s
                     .to_str()
                     .ok()
@@ -315,10 +232,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, key: Value| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let slot = match &key {
-                // The numeric form. The reference bounds-checks `1 <= n <= count` (`0x49bf30`) and
-                // answers only for a CONFIRMED-joined slot; `joined` holds exactly the confirmed
-                // ones (`ui_chat::feed` appends on the server's YOU_JOINED, not on the request), so
-                // the bound is the whole check here.
+                // The reference bounds-checks `1 <= n <= count` (`0x49bf30`) and answers only a
+                // confirmed slot; `joined` holds only those, so the bound is the whole check.
                 Value::Integer(_) | Value::Number(_) => {
                     let n = match &key {
                         Value::Integer(i) => *i,
@@ -329,9 +244,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         .ok()
                         .filter(|n| name_at(&model, *n).is_some())
                 }
-                // The name form. A numeric STRING arrives here and must still resolve as a number:
-                // `ChatFrame.lua:2113` passes the result of a `gsub` — `GetChannelName("1")` — and
-                // Lua's own coercion is what makes that work on the real client.
+                // A numeric string still resolves as a number, as Lua's coercion does in the
+                // reference: `ChatFrame.lua:2113` passes a `gsub` result, `GetChannelName("1")`.
                 Value::String(s) => {
                     let name = s.to_str()?;
                     match name.trim().parse::<usize>() {
@@ -344,16 +258,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             };
 
             let Some(slot) = slot else {
-                // **`0, nil, 0` — three values, not one.** This used to push the number alone,
-                // reasoning that `channelName` is unread by every caller on this branch. True of
-                // the callers; not true of the client. `0x4a05e0` pushes three on every path, and
-                // slot 2 is neither the empty string nor the argument echoed back:
-                // `0x4a0659 xor edx,edx` then `lua_pushstring(NULL)`, which tail-jumps to
-                // `lua_pushnil`. Decision 1845.
-                //
-                // "Not joined" is also wider than a bad index: the lookup answers NULL while the
-                // join-pending word is non-zero, so a channel already in the list but not yet
-                // CONFIRMED reads `0, nil, 0` identically — which is what `joined` models here.
+                // Three values on every path, the name `lua_pushstring(NULL)`, which is nil
+                // (`0x4a0659`); an unconfirmed channel answers the same, as `joined` models.
                 return Ok(MultiValue::from_vec(vec![
                     Value::Integer(0),
                     Value::Nil,
@@ -364,44 +270,21 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(MultiValue::from_vec(vec![
                 Value::Integer(slot as i64),
                 Value::String(lua.create_string(&name)?),
-                // instanceID — see the module doc: 0 on every vanilla emulator, and a number
-                // rather than nil so a caller can compare it like the client's.
+                // `instanceID`: `YOU_JOINED`'s split index, 0 on vanilla servers; never nil.
                 Value::Integer(0),
             ]))
         })?,
     )?;
 
-    // GetChannelList() → slot1, name1, slot2, name2, … over every joined channel, in join order.
-    //
-    // **The shape is settled by two independent consumers, not by a recorded signature** — wow-re
-    // has the address (`0x4a02d0`, `scratch/bindings.md` l.152) and no contract:
-    //
-    //  · the reference's own `FCFDropDown_LoadChannels(...)` walks `for i=1, arg.n, 2` and reads
-    //    `arg[i+1]` as the NAME (FloatingChatFrame.lua l.445-455) — so the pair is (slot, name),
-    //    in that order, and the caller steps by two;
-    //  · `ChatLog.lua:424` packs it with `{ GetChannelList() }` and tests
-    //    `type(value) == "number"` to spot an id — so it is a FLAT vararg, never a table.
-    //
-    // A third witness pins the flatness harder: `AceComm-2.0.lua:334` unpacks TEN pairs in one
-    // statement, `local _,a,_,b,…,j = GetChannelList()`.
-    //
-    // The slot numbering is [`slot_of`]'s — position in `joined_channels` + 1 — so this verb and
-    // `GetChannelName` can never disagree about which channel is 3.
-    //
-    // Zero joined channels is zero returns, not nil: `{ GetChannelList() }` is then an empty
-    // table, which is what every caller above already handles.
-    //
-    // Demand: 4 addons, and only ONE of them names it in its own source (ChatLog). The other
-    // three — FuBar_BGQueueNumber, FuBar_MageFu, FuBar_TankPointsFu — reach it through their
-    // embedded AceComm-2.0. That gap between "greps for the name" and "wants the name" is why the
-    // survey's own read-back exists (`--why`, d2fcef94) and why a hand grep is not the oracle here.
+    // GetChannelList() (`0x4a02d0`): a flat vararg of slot, name pairs in join order, as
+    // `FCFDropDown_LoadChannels` steps it (`FloatingChatFrame.lua:445`); none joined is zero
+    // returns. The slots must match `slot_of`'s, so it agrees with `GetChannelName`.
     g.set(
         "GetChannelList",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let mut out = Vec::with_capacity(model.joined_channels.len() * 2);
-            // Occupied slots only — a freed one is a number nothing is on, so it has no pair to
-            // contribute (the reference walks its record array and skips the cleared entries).
+            // Occupied slots only: the reference skips the cleared entries of its record array.
             for (i, name) in model.joined_channels.iter().enumerate() {
                 let Some(name) = name.as_deref() else {
                     continue;
@@ -413,24 +296,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // JoinChannelByName(name [, password [, frameId]]) — `0x49ff00` → `0x49eb70`, the contract
-    // decision 1908 carved:
-    //
-    //   matched DBC row                        → (ChannelID, resolvedName)
-    //   custom channel (no row)                → (0, nil)      — and 0 is truthy in Lua
-    //   a space in the name, or a matched row  → nil           — no send
-    //     whose zone substitution is empty
-    //
-    // `CMSG_JOIN_CHANNEL` goes out on both non-nil legs. **The third argument registers the
-    // channel in that window's own list** (contract §5, `0x49ec24`–`0x49ede7`, VERIFIED):
-    // `frameId` is `lua_tonumber`d, truncated and decremented, and anything outside `0..10`
-    // after that — a missing or non-numeric argument yields `-1` — silently skips the
-    // registration; otherwise `(Shortcut, ChannelID)` for a matched row and `(name, 0)` for a
-    // custom one is appended to window `frameId - 1`'s parallel arrays, deduplicated by name
-    // (`SStrCmpI`), on both sending legs. It is what puts a `/join`ed channel back into the
-    // window after a `/leave` stripped it — the window's `ZONECHANNELS` word is the character's
-    // registration for that channel's lines, and without this a leave-then-join-then-relog left
-    // General joined and its every line dropped (decision 2144, live run F).
+    // JoinChannelByName(name [, password [, frameId]]) (`0x49ff00` → `0x49eb70`): a DBC row
+    // answers `(ChannelID, resolvedName)` and a custom channel `(0, nil)`, both sending; a name
+    // with a space, or a row whose zone text is empty, answers nil and sends nothing. A `frameId`
+    // that truncates to 1..=10 registers the channel in that window's list, deduplicated by name
+    // (`0x49ec24`), which is what brings a `/leave`-stripped channel's lines back to the window.
     g.set(
         "JoinChannelByName",
         lua.create_function(
@@ -493,10 +363,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // EnumerateServerChannels() — `0x4a1790` (chat-cache-grammar.md §6): the `ChatChannels.dbc`
-    // **shortcuts** in row order, a `flags & 0x10` row only when the zone is a city
-    // (`AreaTable.Flags & 0x8`); 0 values while the zone is unresolvable (an empty catalog here).
-    // Never the composed `<name> - <zone>`: `FCFDropDown_LoadServerChannels` shows these bare.
+    // EnumerateServerChannels() (`0x4a1790`): the `ChatChannels.dbc` Shortcuts in row order, never
+    // the composed names, a `flags & 0x10` row only in a city (`AreaTable.Flags & 0x8`); zero
+    // values while the zone is unresolved.
     g.set(
         "EnumerateServerChannels",
         lua.create_function(|lua, _ignored: MultiValue| {
@@ -509,27 +378,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LeaveChannelByName(name) — `0x4a0000` → `0x49ee70`, the contract wow-re
-    // `leavechannelbyname-contract.md` §11 carved (decision 2144). The only stock caller is
-    // `SlashCmdList["LEAVE"]`, which passes the first whitespace token of the slash text.
-    //
-    //   1. a string or number, else it RAISES `Usage: LeaveChannelByName("name")`; 0 returns.
-    //   2. `SStrToInt(name) != 0` → the key names joined slot n — resolved on the app side, which
-    //      holds the slot states (a suspended or absent slot is a complete no-op there); no
-    //      window strip, because a slot name never equals a window entry.
-    //   3. else a case-insensitive Shortcut match → the composed name for this zone, or a
-    //      complete no-op with no zone text; the window strip is keyed on the DBC's Shortcut.
-    //   4. else a custom channel: the argument verbatim, stripped verbatim.
-    //
-    // **One deliberate divergence, recorded in 2144.** The reference composes the shortcut leg
-    // with `GetRealZoneText` ALONE (`0x49efe8`), never the `"City"` row — so in a capital
-    // `/leave Trade` sends `"Trade - Stormwind City"`, a channel the player is not in, and
-    // leaves nothing. Ours composes with the join's own city-aware substitution (the catalog's
-    // `resolved`), so `/leave Trade` leaves `Trade - City`. The mechanism, done right, not the
-    // reference's broken form of it.
-    //
-    // Nothing local is freed here and no event fires (§6, §10): the slot goes when the server's
-    // `YOU_LEFT` matches its stored name, and the mask bit with it — both the app's.
+    // LeaveChannelByName(name) (`0x4a0000` → `0x49ee70`) returns nothing and raises `Usage:` on a
+    // non-string, non-number. A key whose `SStrToInt` is non-zero is a joined slot, resolved
+    // app-side and never a window entry; a Shortcut leaves the name composed for this zone (a
+    // no-op with no zone text) and strips by Shortcut; anything else is a custom channel.
+    // Deviation: the reference composes the Shortcut with `GetRealZoneText` alone (`0x49efe8`), so
+    // in a capital `/leave Trade` sends `Trade - Stormwind City` and leaves nothing; ours uses the
+    // join's city-aware name, because the reference's form cannot leave the channel it joined.
+    // The slot is freed app-side when the server's `YOU_LEFT` arrives.
     g.set(
         "LeaveChannelByName",
         lua.create_function(|lua, name: Option<Value>| {
@@ -602,7 +458,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The two-name verbs: (channel, player) — or (channel, password) for the password.
+    // The two-name verbs: (channel, player), or (channel, password) for the password.
     for (verb, make) in [
         (
             "SetChannelOwner",
@@ -648,8 +504,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             lua.create_function(
                 move |lua, (name, second): (Option<String>, Option<String>)| {
                     if let Some(name) = non_empty(name) {
-                        // A password may legitimately be empty (`/password General` clears it); a
-                        // player name may not.
+                        // A password may be empty (`/password General` clears it); a player name
+                        // may not.
                         let second = second.unwrap_or_default();
                         if verb == "SetChannelPassword" || !second.trim().is_empty() {
                             push(lua, make(name, second.trim().to_string()));
@@ -665,12 +521,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 }
 
 impl super::UiScript {
-    /// Mirror the app's confirmed-joined channel list, in join order, for [`install`]'s verb.
-    ///
-    /// The `model.party` shape (`party.rs:172`), deliberately, and NOT the `open_chat_requests`
-    /// shape the chat-window work used: that one is a QUEUE the app drains (Lua → app), and this is
-    /// app state READ BY Lua, which is the opposite direction. `ui_chat::feed` owns both edges that
-    /// change it — the server's YOU_JOINED and YOU_LEFT notices — so it pushes here from one place.
+    /// Mirror the app's confirmed-joined channels in join order, `None` for a freed slot;
+    /// `ui_chat::feed` pushes it on each `YOU_JOINED` and `YOU_LEFT`.
     pub fn set_joined_channels(&mut self, joined: Vec<Option<String>>) {
         self.model_mut().joined_channels = joined;
     }
@@ -698,7 +550,7 @@ mod command_tests {
         ]
     }
 
-    /// Decision 1908's three legs, and that 0 is truthy.
+    /// The row, custom-channel and nil legs, and that 0 is truthy.
     #[test]
     fn join_channel_by_name_answers_the_three_legs_of_1908() {
         let mut s = UiScript::new().unwrap();
@@ -794,11 +646,8 @@ mod command_tests {
         );
     }
 
-    /// **`JoinChannelByName`'s third argument registers the channel in that window** (contract §5,
-    /// decision 2144): `frameId - 1` indexes the ten window records, `(Shortcut, ChannelID)` for a
-    /// DBC row and `(name, 0)` for a custom channel, deduplicated by name; a missing, non-numeric or
-    /// out-of-range frame skips the registration and nothing else. It is what puts a `/join`ed
-    /// channel back into a window a `/leave` had stripped it from.
+    /// `frameId - 1` indexes the ten window records (`0x49ec24`); a missing, non-numeric or
+    /// out-of-range frame skips the registration and nothing else.
     #[test]
     fn join_channel_by_name_registers_the_channel_in_the_named_window() {
         let mut s = UiScript::new().unwrap();
@@ -832,16 +681,13 @@ mod command_tests {
             vec![0, 1],
             "…and both windows are owed a save"
         );
-        // The joins themselves went out regardless of the frame argument — five, because this
-        // catalog's Trade is unresolvable (the nil leg, asserted above), and that leg registers
-        // nothing either.
+        // The joins went out whatever the frame argument: five, as this catalog's Trade is the
+        // nil leg, which registers nothing either.
         assert_eq!(s.take_channel_commands().len(), 5);
     }
 
-    /// `LeaveChannelByName`'s legs (contract §11; decision 2144): a number passes through for the
-    /// app's slot lookup and strips nothing; a shortcut composes for the zone and strips the
-    /// window entry it was registered under, in every window; an unresolvable shortcut is a
-    /// complete no-op; a custom name goes verbatim and strips verbatim. Nil raises. Zero returns.
+    /// `LeaveChannelByName`'s four legs and its raise (`0x4a0000` → `0x49ee70`); a Shortcut strips
+    /// its entry from every window.
     #[test]
     fn leave_channel_by_name_composes_strips_and_raises_the_way_the_reference_does() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/char_stats.rs b/crates/benilla-ui/src/script/char_stats.rs
index 0ea72a71..634f4683 100644
--- a/crates/benilla-ui/src/script/char_stats.rs
+++ b/crates/benilla-ui/src/script/char_stats.rs
@@ -1,63 +1,26 @@
-//! The character-window stats + equipment seam (decision 0208 §3) — the paper doll's data feed.
+//! The paper doll's data feed: the stat and equipment-slot globals, read from the combat-stats
+//! snapshots the app pushes for `"player"` and `"pet"` and from its inventory-slot snapshot.
 //!
-//! Same engine-free shape as [`super::unit`]: the app pushes a **combat-stats snapshot** per unit
-//! that has one ([`super::UiScript::set_player_combat_stats`] /
-//! [`super::UiScript::set_pet_combat_stats`]) and an **inventory-slot snapshot**
-//! ([`super::UiScript::set_inventory_slots`]) each frame they change, and the stat/slot globals
-//! here read that plain data.
+//! As in the reference, the pet sheet calls the same `PaperDollFrame_Set*` helpers with `"pet"`
+//! (`PetPaperDollFrame.lua:75-81`). Any other token, or a snapshot not yet pushed, serves the
+//! absent shape: zeros, `percent` 1.0. A pet has no PLAYER block, so its buff splits read 0.
 //!
-//! **The stat family is unit-parameterised, as the reference's is** (decision 1057): every
-//! `PaperDollFrame_Set*(unit, prefix)` helper the character sheet calls with `"player"`, the pet
-//! sheet calls with `"pet"` (ref `PetPaperDollFrame.lua:73-81`), through these very bindings. So
-//! `UnitStat`/`UnitResistance`/`UnitArmor`/… route on the token — `"player"` and `"pet"` each read
-//! their own pushed snapshot, and **every other token (and a snapshot the app has not pushed yet)
-//! serves the absent shape**: zeros, `percent` 1.0. A pet's descriptor carries the UNIT half and no
-//! PLAYER block at all, which is why its buff decompositions read `0` and the ref's own pet sheet
-//! shows plain white numbers.
+//! For a third unit, zeros are right for `UnitStat` (`0x518600`): `UNIT_FIELD_STAT*` is PRIVATE +
+//! OWNER_ONLY, so the reference holds zeros too. Not built: vmangos also sends a beast's
+//! `UNIT_FIELD_RESISTANCES` to the caster of its Beast Lore (`Object.cpp:1065-1067`,
+//! `Player.cpp:2603-2610`), and the reference's `UnitResistance` and `UnitArmor` then answer them.
 //!
-//! (Until 1057 the router was a hard `token == "player"` test documented as "the faithful
-//! player-only gate". It was neither: it was "no consumer yet". The reference passes `"pet"` into
-//! the same bindings, and the gate was simply never exercised.)
-//!
-//! **The absent shape for a third unit is the right ANSWER for `UnitStat` and a known GAP for the
-//! resistance pair — and the reason it used to be filed as blanket-faithful was wrong.** The
-//! binary does not gate slots 1/2 on SELF at all: `UnitStat`'s are NULL + typemask bit 3 only, and
-//! it returns whatever the client's copy of `UNIT_FIELD_STAT0+i` holds (VERIFIED wow-re
-//! `ui/scratch/pet-paperdoll-stat-api.md` §4). What makes our zeros agree there is the *server's*
-//! visibility, not a client gate: `UNIT_FIELD_STAT*` is PRIVATE + OWNER_ONLY, and the only
-//! owner-visible units a 1.12 unit token can name are the two we already serve — so a stranger's
-//! copy is zero on the reference too. `UNIT_FIELD_RESISTANCES` carries a third flag,
-//! **`SPECIAL_INFO`**, which vmangos grants to the caster of `SPELL_AURA_EMPATHY` — its own comment
-//! reads `// Beast Lore` (`Player.cpp:2603-2610`, `Object.cpp:1065-1067`). So with Beast Lore up on
-//! a beast, the reference's `UnitResistance("target", i)` / `UnitArmor("target")` return that
-//! creature's real numbers through their non-SELF leg, and ours return zeros. That is a real,
-//! reachable divergence, unfed rather than decided: the app pushes snapshots for two tokens only.
-//! `unit_combat_stats` already works over any store, so the missing piece is a third push.
-//!
-//! **Return shapes differ BY FAMILY, and the reference Lua's own asymmetry is the tell**
-//! (decision 1397 — reading one and assuming the other is how 0208 got the stat row wrong).
-//! `UnitStat` serves the **raw** `UNIT_FIELD_STAT` twice — once as-is, once clamped at zero — and
-//! leaves the subtraction to `PaperDollFrame_SetStats`, which writes `(stat - posBuff - negBuff)`
-//! itself. `UnitResistance`/`UnitArmor` serve a **decomposed** first return, because the engine
-//! helper `0x5efcd0` does that subtraction for them; their callers use it directly.
-//!
-//! The negative deltas are **negative-or-zero** where the wire can carry them at all, matching the
-//! ref's `negBuff < 0` tests — but see 1397 for how little of that survives a given server: these
-//! four arrays are stored float and narrowed to int by `Object::BuildValuesUpdate`, and that cast
-//! saturates a negative to `0` on an arm64 host while wrapping it correctly on x86.
+//! vmangos narrows the four buff-split arrays with `uint32(float)` (`Object.cpp:759-763`), so a
+//! negative delta arrives as 0 from an arm64 server and intact from x86.
 
 use mlua::{Lua, Value};
 
 use super::binding_abi::flag;
 use super::{binding_abi, Model};
 
-/// The 1.12 weapon-subclass → `SkillLine.dbc` id table, transcribed from vmangos
-/// `ItemPrototype::GetProficiencySkill`'s `item_weapon_skills` (`Objects/Item.cpp:700-707`;
-/// subclass ids `Objects/ItemPrototype.h:190-213`, skill ids `SharedDefines.h:951-1038`) — item
-/// class 2 (weapon) subclasses `0..=20`. `None` = no proficiency skill backs the subclass (the
-/// obsolete/exotic/misc rows) or out of range. The app resolves the paper doll's weapon-skill
-/// line ("Both Hands"/"Ranged") through this, falling back to [`SKILL_UNARMED`] with no weapon
-/// (vmangos `Player::GetBaseWeaponSkillValue`, `Objects/Player.cpp:20175-20186`).
+/// The `SkillLine.dbc` id behind weapon subclass `0..=20` (vmangos `Item.cpp:700-707`), `None`
+/// for the obsolete, exotic and misc rows; with no weapon the skill is [`SKILL_UNARMED`]
+/// (`Player.cpp:20144-20155`).
 pub fn weapon_subclass_skill(subclass: u32) -> Option<u32> {
     const TABLE: [u32; 21] = [
         44,  // 0 axe → SKILL_AXES
@@ -73,7 +36,7 @@ pub fn weapon_subclass_skill(subclass: u32) -> Option<u32> {
         136, // 10 staff → SKILL_STAVES
         0,   // 11 exotic
         0,   // 12 exotic2
-        162, // 13 fist weapon → SKILL_UNARMED (vmangos's own row — fists ride the unarmed skill)
+        162, // 13 fist weapon → SKILL_UNARMED (vmangos's own row: fists use the unarmed skill)
         0,   // 14 misc
         173, // 15 dagger → SKILL_DAGGERS
         176, // 16 thrown → SKILL_THROWN
@@ -85,27 +48,15 @@ pub fn weapon_subclass_skill(subclass: u32) -> Option<u32> {
     TABLE.get(subclass as usize).copied().filter(|&s| s != 0)
 }
 
-/// `SKILL_UNARMED` (162, vmangos `SharedDefines.h:987`) — the melee weapon-skill line's fallback
-/// when no weapon is equipped (`Player::GetBaseWeaponSkillValue`, `Objects/Player.cpp:20184`).
+/// The melee skill with no weapon equipped (vmangos `SharedDefines.h:987`, `Player.cpp:20153`).
 pub const SKILL_UNARMED: u32 = 162;
 
-/// `SKILL_DEFENSE` — the Defense skill line `UnitDefense` reports. **Read out of the shipped
-/// 1.12.1 `SkillLine.dbc` this session**, not remembered: the file's 123 records carry exactly one
-/// row whose enUS `displayName` (column 3, the `SkillLinefmt` layout in
-/// `benilla_formats::skill_lines`) is `"Defense"`, and it is id **95**, category 6 (Weapon Skills).
-/// Corroborated by vmangos `SharedDefines.h:961` (`SKILL_DEFENSE = 95`).
+/// The `SkillLine.dbc` Defense row `UnitDefense` reports (vmangos `SharedDefines.h:961`).
 pub const SKILL_DEFENSE: u32 = 95;
 
-/// One unit's combat-stats snapshot behind a paper doll's stat pane — plain data the app derives
-/// from that unit's descriptor accessors ([`UnitStat`]/[`UnitResistance`]/… read it). Arrays are
-/// in field order: stats 0..4 = Str/Agi/Stam/Int/Spi (`UNIT_FIELD_STAT0..4`), schools 0..6 with
-/// `[0]` = armor/physical. The `*_neg` values are **negative-or-zero** (the stored wire sign; see
-/// the module doc).
-///
-/// Two units carry one: the player and (decision 1057) the pet. A **creature's** descriptor has no
-/// PLAYER block, so every field sourced from one — the stat/resistance buff splits, the
-/// damage-done mods, the skill pairs — keeps its default for a pet, which is exactly the ref pet
-/// sheet's plain white numbers with no buff decomposition in the tooltip.
+/// One unit's combat stats behind a paper doll, from its descriptor. Arrays are in field order:
+/// stats Str/Agi/Sta/Int/Spi, schools with `[0]` armor. A pet leaves the PLAYER-block fields (buff
+/// splits, damage-done mods, skill pairs) at their defaults.
 #[derive(Clone, Debug, PartialEq)]
 pub struct UnitCombatStats {
     /// Effective (post-buff) primary stats (`UNIT_FIELD_STAT0..4`).
@@ -129,14 +80,12 @@ pub struct UnitCombatStats {
     /// Physical damage-done bonuses (`PLAYER_FIELD_MOD_DAMAGE_DONE_POS[0]` / `_NEG[0]`, neg ≤ 0).
     pub physical_bonus_pos: i32,
     pub physical_bonus_neg: i32,
-    /// The physical damage-done multiplier (`PLAYER_FIELD_MOD_DAMAGE_DONE_PCT[0]`, a true float —
-    /// the app fills `1.0` while the field hasn't streamed; the default here is `1.0` too).
+    /// The physical damage multiplier (`PLAYER_FIELD_MOD_DAMAGE_DONE_PCT[0]`), 1.0 until streamed.
     pub damage_percent: f32,
     /// Attack speeds in ms (`UNIT_FIELD_BASEATTACKTIME[0..2]`).
     pub main_attack_time_ms: u32,
     pub offhand_attack_time_ms: u32,
-    /// Whether an offhand **weapon** is equipped — gates `UnitAttackSpeed`'s second return (the
-    /// app decides from the inv slots; the offhand fields stream regardless).
+    /// Whether an off-hand weapon is equipped, which gates `UnitAttackSpeed`'s second return.
     pub has_offhand: bool,
     /// Melee AP + its split mods (`UNIT_FIELD_ATTACK_POWER` / `_MODS`, neg ≤ 0).
     pub attack_power: i32,
@@ -151,60 +100,27 @@ pub struct UnitCombatStats {
     /// Ranged damage range (`UNIT_FIELD_MINRANGEDDAMAGE`/`MAXRANGEDDAMAGE`).
     pub ranged_min_damage: f32,
     pub ranged_max_damage: f32,
-    /// The equipped main-hand weapon's skill line as **`(value + PERM bonus, TEMP bonus)`** — the
-    /// app resolves WHICH skill via [`weapon_subclass_skill`] (unarmed = [`SKILL_UNARMED`]) and
-    /// reads the pair from `PLAYER_SKILL_INFO`; `UnitAttackBothHands` serves it verbatim.
-    ///
-    /// **The permanent half belongs to the BASE, not to the modifier** (`0x5ea460`, VERIFIED —
-    /// wow-re `ui/scratch/unitrangedattack-skill-pair.md` §3; corrected here by decision 1812).
-    /// Every one of these four pairs comes out of that one reader, so all four carry the split.
+    /// The main hand's skill line (picked by [`weapon_subclass_skill`]) as `(value + perm, temp)`,
+    /// the split the reference's skill reader `0x5ea460` makes for all four skill pairs.
     pub main_weapon_skill: (i32, i32),
-    /// The OFF hand's, read the same way. `UnitAttackBothHands` pushes both hands (§4 of wow-re's
-    /// `pet-paperdoll-stat-api.md`: `0x518810` calls `[vtbl+0xb0]` twice, hand 0 then hand 1), and
-    /// an empty or non-weapon off hand is Unarmed exactly as the main hand is.
+    /// The off hand's pair, read the same way; an empty or non-weapon off hand is Unarmed.
     pub offhand_weapon_skill: (i32, i32),
-    /// The ranged weapon's skill pair (`UnitRangedAttack`), same split.
-    ///
-    /// **Player-only, and by a different gate than its two neighbours.** `UnitRangedAttack`
-    /// `0x518b90` is a DIRECT call gated on the PLAYER typemask alone — no vtable slot and **no
-    /// `CGUnit_C` fallback body** (wow-re `unitrangedattack-skill-pair.md` §4). So where
-    /// `UnitDefense` and `UnitAttackBothHands` pass a pet through SELF-OR-MINE and answer
-    /// `level * 5`, this one answers `(0, 0)` for a pet and for every other player too. Mirroring
-    /// [`cgunit_skill`] here would be wrong.
+    /// The ranged weapon's pair, the same split. Player only: `UnitRangedAttack` (`0x518b90`)
+    /// has no creature fallback, so a pet answers `(0, 0)` where `UnitDefense` answers level * 5.
     pub ranged_weapon_skill: (i32, i32),
-    /// The [`SKILL_DEFENSE`] line's pair, in the same `(value + perm, temp)` split as the three
-    /// above and out of the same reader; `UnitDefense` serves it verbatim.
-    ///
-    /// **The player's only.** A creature has no skill block, and the client does not read one for
-    /// it: `UnitDefense` forks on the resolved unit's vtable and gives a non-player
-    /// `UNIT_FIELD_LEVEL * 5` instead ([`cgunit_skill`]), so the pet feed never fills this and the
-    /// binding never reads it for a pet.
+    /// The [`SKILL_DEFENSE`] pair, the same split. The player's only: `UnitDefense` gives a
+    /// non-player level * 5 instead (`cgunit_skill`), so the pet feed leaves it unset.
     pub defense_skill: (i32, i32),
-    /// Whether a wand is equipped (`HasWandEquipped` — the ref swaps the ranged-attack action for
-    /// wand Shoot on it).
+    /// Whether a wand is equipped (`HasWandEquipped`).
     pub has_wand: bool,
-    /// `GetDodgeChance()` / `GetParryChance()` / `GetBlockChance()` — the player's avoidance
-    /// percentages (`PLAYER_DODGE_PERCENTAGE` and its two siblings), already a percent on the
-    /// wire: `2.62` is "2.62%".
-    ///
-    /// **The player's only, and no unit argument.** All three bindings take zero arguments and
-    /// return exactly one number (`reference/1.12-shapes.tsv`: `GetDodgeChance 0x516f00`,
-    /// `GetBlockChance 0x516f60`, `GetParryChance 0x516fc0` — argc 0, arity 1, kind number, all
-    /// `exact`), so there is no pet leg to mirror and no absent answer to model: a field that has
-    /// not streamed reads 0, which is what the wire's own default is.
-    ///
-    /// The shipped 1.12 FrameXML never calls them — the character sheet's own defense block is
-    /// `UnitDefense` — so this trio is addon-facing surface, and the corpus asks for it: four
-    /// vanilla addons read `GetDodgeChance` (FuBar_TankPointsFu, FuBar_DakSmak, Outfitter,
-    /// BetterCharacterStats) and three read each of the other two.
+    /// Avoidance chances, already percents on the wire (`PLAYER_DODGE_PERCENTAGE` and siblings).
     pub dodge_percent: f32,
     pub parry_percent: f32,
     pub block_percent: f32,
 }
 
 impl Default for UnitCombatStats {
-    /// All-zeros except `damage_percent` = `1.0` — the multiplicative identity, so the absent
-    /// shape never feeds the ref's `bonus / percent` math a division by zero.
+    /// All zeros but `damage_percent` 1.0, which stock divides by (`PaperDollFrame.lua:298`).
     fn default() -> Self {
         UnitCombatStats {
             stats: [0; 5],
@@ -244,108 +160,61 @@ impl Default for UnitCombatStats {
     }
 }
 
-/// One resolved equipment/ammo slot view (the `GetInventoryItem*` family reads it), resolved by
-/// the app like [`super::container::ContainerSlot`]: icon from the display catalog, count/quality
-/// from the item object + template. Plain data.
+/// One equipment or ammo slot as the `GetInventoryItem*` family reads it, resolved by the app like
+/// [`super::container::ContainerSlot`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct InvSlotView {
     /// The item's template entry (`GetInventoryItemID`).
     pub item_id: u32,
-    /// The doll twin of [`super::container::ContainerSlot::bar_placeable`] — an equipped item
-    /// dragged straight to the bar goes through the same filter.
+    /// Whether the item may go on an action bar, by the same filter as a bag slot's.
     pub bar_placeable: bool,
     /// Icon texture path (`Interface\Icons\…`); `None` while the template answer is in flight.
     pub icon: Option<String>,
-    /// `ITEM_FIELD_STACK_COUNT` — what `GetInventoryItemCount 0x4c8680` pushes for an ordinary
-    /// item (1 for equipment; the ammo slot's own leg puts the carried total here).
+    /// `ITEM_FIELD_STACK_COUNT`, or for the ammo slot the bag-summed carried total.
     pub count: u32,
-    /// What that same function pushes when the item is a **CONTAINER** (`OBJECT_FIELD_TYPE`'s
-    /// `TYPEMASK_CONTAINER` bit — `0x4c87a6`), which is a different number entirely: the sum of
-    /// its contents' stack counts when its `(class, subclass)` row carries `ItemSubClass.dbc`'s
-    /// `DisplayFlags & 0x4` (`0x4c881a`, set on Soul Bag and the quivers only), and **0**
-    /// otherwise. `None` = not a container, and [`Self::count`] answers.
-    ///
-    /// The slot-dependent half of the law is NOT here — it is at the binding, where the reference
-    /// keeps it: a container whose 0-based slot is past `0x16` (everything but the four equipped
-    /// bag slots — the bank's six bag slots included) short-circuits to 0 at `0x4c87af` before any
-    /// of this is read.
+    /// For a container (`TYPEMASK_CONTAINER`, `0x4c87a6`), what `GetInventoryItemCount` pushes:
+    /// its contents' summed stacks when its `ItemSubClass.dbc` row has `DisplayFlags & 0x4` (Soul
+    /// Bag and quivers, `0x4c881a`), else 0; past 0-based slot `0x16` the binding answers 0 first.
     pub contents_count: Option<u32>,
     /// Item quality 0..6 (`GetInventoryItemQuality`).
     pub quality: i32,
-    /// The item's name, when known (tooltip/link consumers).
+    /// The item's name, once known.
     pub name: Option<String>,
-    /// The instance's live durability `(current, max)` — the equipped-item tooltip's
-    /// "Durability X / Y" line (see [`super::container::ContainerSlot::durability`]).
+    /// Live durability `(current, max)`, the tooltip's "Durability X / Y" line.
     pub durability: Option<(u32, u32)>,
-    /// `ITEM_FIELD_FLAGS` (wire field 21) — the alert/broken laws read two bits (VERIFIED wow-re
-    /// inventory-alert-law `0x4c7ee0`): `0x08` wrapped (a gift — never alerts, never broken),
-    /// `0x10` force-red (alert status 4 regardless of durability).
+    /// `ITEM_FIELD_FLAGS`; the alert recompute `0x4c7ee0` reads two bits: `0x10` force-red
+    /// (status 4) and `0x08` wrapped (no durability alert).
     pub flags: u32,
-    /// `0x5da2c0` — **the instance is runtime-bound**: `ITEM_FIELD_FLAGS & 1` (soulbound), or a
-    /// live enchant slot naming a `SpellItemEnchantment` row that binds. App-resolved off the raw
-    /// descriptor (the doll twin of [`super::container::ContainerSlot::already_bound`]); the
-    /// tooltip's §6 bind line overrides to **Soulbound** on it (B310).
+    /// Bound at runtime (`0x5da2c0`): `ITEM_FIELD_FLAGS & 1`, or an enchant whose
+    /// `SpellItemEnchantment` row binds. The tooltip's bind line then says Soulbound.
     pub already_bound: bool,
-    /// An `|Hitem:…|h[Name]|h` link once the name is known — the doll twin of
-    /// `ContainerSlot::link`; carried onto the cursor payload so a world-drop `DELETE_ITEM_CONFIRM`
-    /// off an equipped item can report its name (decision 0208 phase 1b).
+    /// An `|Hitem:…|h[Name]|h` link once the name is known.
     pub link: Option<String>,
-    /// Whether an outstanding pending op covers `(EQUIPMENT_BAG, this slot)` — the app's
-    /// `PendingItemOps` feed (decision 0216 §4/0218 §3), fed by `ui_char.rs::feed_char` the same
-    /// way `ContainerSlot::locked` is. `IsInventoryItemLocked` ORs this with the payload-held-here
-    /// check.
+    /// Whether a pending item operation covers this slot (`IsInventoryItemLocked`).
     pub locked: bool,
-    /// The 1-based live-API inventory slot ids this item could be EQUIPPED into (empty = not
-    /// equippable; an equipped ring's own two finger slots, say) — decision 0208 phase 1b's "the
-    /// fit rule", resolved app-side via `ui_items::find_equip_slot`.
+    /// The 1-based live-API slots this item could be equipped into; empty if none.
     pub equip_slots: Vec<u8>,
-    /// The RESOLVED `ITEM_FIELD_CREATOR` name — the equipped-item tooltip's green
-    /// "<Made by %s>" line (see [`super::container::ContainerSlot::creator`], the bag twin).
+    /// The resolved `ITEM_FIELD_CREATOR` name, the tooltip's "<Made by %s>" line.
     pub creator: Option<String>,
-    /// The instance's resolved enchant slots, in slot order — the doll twin of
-    /// [`super::container::ContainerSlot::enchants`] (decisions 0915/0920). Our own equipped item
-    /// reads all 7 slots off its streamed item object; an INSPECTED player's record carries 7 too
-    /// and the reference renders all 7 from it — but a 1.12 server fills only PERM and TEMP, so in
-    /// practice that is what an inspect hover shows.
+    /// The resolved enchant slots in slot order. An inspected player's record has all 7 too, but
+    /// vmangos fills only PERM and TEMP (`Player.cpp:10518-10519`).
     pub enchants: Vec<super::EnchantView>,
-    /// **The instance's remaining LIFETIME in milliseconds** — the doll twin of
-    /// [`super::container::ContainerSlot::duration_ms`]. `None` = no timer. In practice an
-    /// equipped duration item is rare (the holiday masks are the shipped case), but the line law
-    /// is one law and the doll hover runs the same builder. Decision 1933.
+    /// The instance's remaining lifetime in ms; `None` without a timer.
     pub duration_ms: Option<u64>,
 }
 
-/// The inventory-slot snapshot: index 0 = ammo, 1..=19 the equipment slots, 20..=23 the four
-/// equipped-bag icons (all the client's `GetInventorySlotInfo` slot ids — decision 0216 slice 2's
-/// bag bar). `None` = an empty slot.
+/// The doll snapshot: 0 ammo, 1..=19 equipment, 20..=23 the equipped bags, as
+/// `GetInventorySlotInfo` numbers them; `None` is an empty slot.
 pub const INVENTORY_SLOT_COUNT: usize = 24;
 pub type InventorySlots = [Option<InvSlotView>; INVENTORY_SLOT_COUNT];
 
-/// The six BANK-BAG slots' snapshot, in button order (live-API ids 64..=69 —
-/// `BankButtonIDToInvSlotID(1..6, isBag)`). `None` = the slot is empty (or not purchased).
-///
-/// **A separate dense array rather than a wider [`InventorySlots`]**, because the live-id space
-/// between them is not ours to fill: 24..=39 is the backpack and 40..=63 the vault, and both of
-/// those the model already holds as CONTAINERS — [`Model::inv_slot`]'s bank band maps them rather
-/// than storing them twice. Growing the doll array to 70 would leave a 40-entry hole whose
-/// emptiness means "look somewhere else", which is exactly the kind of implicit second rule that
-/// lets a tooltip disagree with the icon under it. Three bands, three named sources.
-///
-/// Fed by the same system as the doll snapshot ([`super::UiScript::set_bank_bag_slots`]): these
-/// are player-descriptor inventory slots that exist whether or not the bank window is open, not
-/// part of the bank *window*'s state.
+/// The six bank-bag slots in button order, live-API ids 64..=69; `None` is empty or unbought.
+/// They are player-descriptor slots, present whether or not the bank window is open.
 pub const BANK_BAG_SLOT_COUNT: usize = 6;
 pub type BankBagSlots = [Option<InvSlotView>; BANK_BAG_SLOT_COUNT];
 
-/// The client's own `PaperDollItemFrame.dbc` rows (re-verified against the 1.12.1 (build 5875)
-/// MPQ this session, byte-exact — 36 records, 3 `u32` fields each: `SlotName` offset,
-/// `SlotTexture` offset, `SlotID`): `(slotName, slotId, empty-slot art suffix)` for all 36 rows —
-/// the 20 equipment+ammo rows, `Bag0Slot`..`Bag3Slot` (ids **20..23**, every one pointing at the
-/// same `interface\paperdoll\UI-PaperDoll-Slot-Bag.blp`, matching the reference
-/// `CharacterBag0Slot` bag-bar buttons' `GetID()`s), and `Bag1`..`Bag12` (ids 64..75 — the
-/// bank-bag band; see the note over those rows). The oddballs: `BackSlot` shows the **Chest** art
-/// and `AmmoSlot` the **Ranged** art (both confirmed by their `SlotTexture` offset pointing at
-/// that other row's string, not a fresh one).
+/// `PaperDollItemFrame.dbc`'s 36 rows as `(SlotName, SlotID, art suffix)`. The texture column
+/// shares strings between rows, so `BackSlot` shows the Chest art and `AmmoSlot` the Ranged.
 const SLOT_INFO: [(&str, i64, &str); 36] = [
     ("AmmoSlot", 0, "Ranged"),
     ("HeadSlot", 1, "Head"),
@@ -371,16 +240,7 @@ const SLOT_INFO: [(&str, i64, &str); 36] = [
     ("Bag1Slot", 21, "Bag"),
     ("Bag2Slot", 22, "Bag"),
     ("Bag3Slot", 23, "Bag"),
-    // The twelve rows this table was short of. The shipped DBC has **36 records, not 24**, and
-    // `Bag1`..`Bag12` at SlotNumbers 64..75 are in the very table this binding scans — 64..69 is
-    // exactly the bank-bag band `ContainerIDToInventoryID` produces. This file used to call them
-    // "a different, unrelated numbering — not `GetInventorySlotInfo` names, out of scope"; that is
-    // refuted, and the scan reaches them like any other row.
-    //
-    // All twelve share ONE string-block offset with `Bag0Slot`..`Bag3Slot` — sixteen rows, one
-    // string (`+1001`). Read at the offset rather than resolved from the row name, because that is
-    // how this column works: 36 rows carry only 17 distinct offsets, which is why `BackSlot` shows
-    // the Chest art and `AmmoSlot` the Ranged art rather than art of their own.
+    // The bank-bag band is 64..69; all sixteen bag rows share one texture string.
     ("Bag1", 64, "Bag"),
     ("Bag2", 65, "Bag"),
     ("Bag3", 66, "Bag"),
@@ -395,18 +255,13 @@ const SLOT_INFO: [(&str, i64, &str); 36] = [
     ("Bag12", 75, "Bag"),
 ];
 
-/// The durability-alert regions in the client's own slot table (`0x806eb8`, VERIFIED wow-re
-/// inventory-alert-law — 12 entries): alert index 1..=11 → the live-id equipment slot (Head,
-/// Shoulders, Chest, Waist, Legs, Feet, Wrists, Hands, Weapon, Shield, Ranged — the ref
-/// FrameXML's `INVENTORY_ALERT_STATUS_SLOTS` order), index 12 → the client's low-ammo region
-/// (slot -1 in its table; FrameXML never reads it, the binding answers it). Our live-id 0 IS
-/// the ammo view, so the 12th entry maps there.
+/// The client's 12 durability-alert regions (`0x806eb8`) as live slot ids: stock's 11
+/// `INVENTORY_ALERT_STATUS_SLOTS` (`DurabilityFrame.lua:2-12`), then low ammo, which the client
+/// table holds as slot -1 and we as the ammo view, slot 0.
 const ALERT_SLOTS: [usize; 12] = [1, 3, 5, 6, 7, 8, 9, 10, 16, 17, 18, 0];
 
-/// The broken classification the doll tint (`GetInventoryItemBroken`) and alert status 4 share
-/// (the recompute `0x4c7ee0`, byte-verified): a wrapped item (`flags & 0x08`) is never broken;
-/// `flags & 0x10` forces broken regardless of durability; else broken ⇔ tracks durability
-/// (max > 0) at 0.
+/// Broken for the doll's red tint, from `0x4c7ee0`'s bits: never when wrapped (`0x08`), else when
+/// force-red (`0x10`) or at durability 0 of a nonzero max.
 fn slot_is_broken(v: &InvSlotView) -> bool {
     if v.item_id == 0 || v.flags & 0x08 != 0 {
         return false;
@@ -414,13 +269,9 @@ fn slot_is_broken(v: &InvSlotView) -> bool {
     v.flags & 0x10 != 0 || matches!(v.durability, Some((0, max)) if max > 0)
 }
 
-/// One region's `GetInventoryAlertStatus` value — the recompute `0x4c7ee0`'s per-item
-/// classification (VERIFIED wow-re inventory-alert-law, §5-cross-checked; the enum's own name
-/// is `INV_ALERT_STATUS`): `4` (red) = broken per [`slot_is_broken`]; `3` (yellow) = tracks
-/// durability and **`1..=5` points left — an ABSOLUTE count, no percentage, maxDurability is
-/// only the tracks-durability gate** (`cmp [D+0xa0],5`); `0` otherwise. Statuses 1/2 are the
-/// temp-weapon-enchant alerts (present/expiring-in-30s) — no enchant feed yet, and the 1.12
-/// FrameXML disables their colors anyway; a named deferral.
+/// One region's `GetInventoryAlertStatus` (`0x4c7ee0`): 4 when force-red or broken, 3 with 1..=5
+/// durability points left (an absolute count, not a percentage), else 0. Statuses 1 and 2, the
+/// temporary-enchant alerts, are not fed; stock gives them no color (`DurabilityFrame.lua:18-19`).
 fn alert_status(slot: &Option<InvSlotView>) -> u8 {
     let Some(v) = slot.as_ref().filter(|v| v.item_id != 0) else {
         return 0;
@@ -438,9 +289,7 @@ fn alert_status(slot: &Option<InvSlotView>) -> u8 {
     }
 }
 
-/// The 12th region's low-ammo status (`0x4c7ee0`'s slot −1 arm): an equipped ammo item whose
-/// carried count is `<= 20` reads `3`; no ammo (or plenty) reads `0`. The ammo view's count is
-/// already the bag-summed carried total.
+/// The low-ammo region (`0x4c7ee0`'s slot -1 arm): 3 when the carried ammo is 20 or fewer, else 0.
 fn ammo_alert_status(slot: &Option<InvSlotView>) -> u8 {
     match slot.as_ref().filter(|v| v.item_id != 0) {
         Some(v) if v.count <= 20 => 3,
@@ -449,22 +298,17 @@ fn ammo_alert_status(slot: &Option<InvSlotView>) -> u8 {
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the player's combat-stats snapshot — the app calls this each
-    /// frame any of the backing descriptor fields changed (decision 0208 §3).
+    /// Push, or clear with `None`, the player's combat-stats snapshot.
     pub fn set_player_combat_stats(&mut self, stats: Option<UnitCombatStats>) {
         self.model_mut().player_combat_stats = stats;
     }
 
-    /// The `"pet"` twin (decision 1057) — `None` whenever there is no pet, which is what makes
-    /// every `Unit*("pet")` fall back to the absent shape the moment one is dismissed.
+    /// The pet's snapshot; `None` without a pet, so `Unit*("pet")` reads the absent shape.
     pub fn set_pet_combat_stats(&mut self, stats: Option<UnitCombatStats>) {
         self.model_mut().pet_combat_stats = stats;
     }
 
-    /// Push the equipment/ammo slot snapshot (index 0 = ammo, 1..=19 equipment). Recomputes the
-    /// 11 durability-alert region statuses off the live pairs; a change fires
-    /// `UPDATE_INVENTORY_ALERTS` — the DurabilityFrame's own repaint signal (the real engine
-    /// computes these statuses itself and fires the same event).
+    /// Push the doll snapshot, recompute the 12 alert statuses and fire `UPDATE_INVENTORY_ALERTS`.
     pub fn set_inventory_slots(&mut self, slots: InventorySlots) {
         {
             let mut model = self.model_mut();
@@ -478,42 +322,24 @@ impl super::UiScript {
             model.inventory_slots = slots;
             model.inventory_alerts = alerts;
         }
-        // Unconditionally, the client's own shape (VERIFIED `0x4c7ee0`: the event fires at the
-        // tail of EVERY recompute, never diffed against prior state) — SetAlerts re-derives the
-        // whole frame from the statuses each time, so glyph choices (the off-hand
-        // shield/off-weapon swap) can never go stale. The app pushes only on real slot-view
-        // change, so this stays quiet between changes.
+        // Every recompute fires it, never diffed against the last (`0x4c7ee0`); the app pushes
+        // only on a real change.
         self.fire_event("UPDATE_INVENTORY_ALERTS", vec![]);
     }
 
-    /// Push the six bank-bag slots ([`BankBagSlots`] — live ids 64..=69).
-    ///
-    /// **The repaint signal is `PLAYERBANKSLOTS_CHANGED`, and nothing else will do** (1771). The
-    /// reference's bank buttons register exactly `BANKFRAME_OPENED`, `PLAYERBANKSLOTS_CHANGED`,
-    /// `ITEM_LOCK_CHANGED` and `CURSOR_UPDATE` (`BankFrameBaseButton_OnLoad`); of those, only the
-    /// first two reach `BankFrameItemButton_OnUpdate`, the icon/count/lock repaint. That function
-    /// is NOT an `OnUpdate` handler despite the name — `BankItemButtonTemplate`'s `<OnUpdate>` is
-    /// `CursorOnUpdate()`, and the repaint is only ever reached from
-    /// `BankFrameItemButton_OnEvent`. `UNIT_INVENTORY_CHANGED`, which rides
-    /// [`Self::set_inventory_slots`] beside this push, is not registered by these buttons at all.
-    /// So `ui_char::feed_char` fires `PLAYERBANKSLOTS_CHANGED` for every bag slot whose ITEM
-    /// changed, and leaves the lock to `ITEM_LOCK_CHANGED`.
+    /// Push the six bank-bag slots. The caller fires `PLAYERBANKSLOTS_CHANGED` for a changed item:
+    /// the stock bank buttons repaint only on it and `BANKFRAME_OPENED` (`BankFrame.lua:206-212`).
     pub fn set_bank_bag_slots(&mut self, slots: BankBagSlots) {
         self.model_mut().bank_bag_slots = slots;
     }
 
-    /// Drain the inventory-slot ids `UseInventoryItem` queued (decision 0208 phase 1b) — the app
-    /// resolves each to the equipped item's guid and sends `CMSG_USE_ITEM` (bag 255 + the
-    /// 0-based wire slot).
+    /// Drain the slot ids `UseInventoryItem` queued; the app sends each as `CMSG_USE_ITEM`, bag
+    /// 255 and the 0-based slot.
     pub fn take_inventory_uses(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().inventory_uses)
     }
 }
 
-/// Read a unit's combat-stats snapshot under a short model borrow, routed by token: `"player"` and
-/// `"pet"` each read their own pushed snapshot, anything else — and a snapshot the app has not
-/// pushed yet — reads the default (the absent shape: zeros, `damage_percent` 1.0). See the module
-/// doc for why exactly these two tokens and no more.
 fn with_unit_stats<T>(
     lua: &Lua,
     token: &Option<String>,
@@ -529,43 +355,23 @@ fn with_unit_stats<T>(
     f(pushed.unwrap_or(&absent))
 }
 
-/// The post-processing both skill-shaped bindings share: **`if (mod + base) < 0 then mod = -base`**
-/// — so the pair can never sum below zero (`0x519298` for `UnitDefense`, `0x5188a7` per hand for
-/// `UnitAttackBothHands`; wow-re `ui/scratch/pet-paperdoll-stat-api.md` §4). A debuff deeper than
-/// the skill itself reads as "reduced to 0", never as a negative total.
+/// The clamp `UnitDefense` (`0x519298`) and each hand of `UnitAttackBothHands` (`0x5188a7`) apply:
+/// a modifier below `-base` becomes `-base`, so the total never reads negative.
 fn skill_clamped((base, modifier): (i32, i32)) -> (i64, i64) {
     let base = i64::from(base);
     let modifier = i64::from(modifier);
     (base, if modifier + base < 0 { -base } else { modifier })
 }
 
-/// A **non-player** unit's answer to both skill-shaped questions — `UnitDefense` and
-/// `UnitAttackBothHands` — which is `UNIT_FIELD_LEVEL * 5`, flat.
-///
-/// It is one helper because it is one function in the client: both bindings dispatch through the
-/// resolved unit's vtable, and a `CGUnit_C` lands on a three-line body that multiplies the level by
-/// five and writes 0 to the modifier (`0x613680` / `0x6136b0`, wow-re
-/// `ui/scratch/pet-paperdoll-stat-api.md`). Nothing here is skill data — a creature has no skill
-/// block at all, which is exactly why the client substitutes a formula.
+/// A non-player's `UnitDefense` and `UnitAttackBothHands` answer: `CGUnit_C`'s vtable bodies
+/// (`0x613680`, `0x6136b0`) return level * 5 with a 0 modifier; a creature has no skill block.
 fn cgunit_skill(model: &Model, token: &str) -> i64 {
     model.unit(token).map_or(0, |u| i64::from(u.level)) * 5
 }
 
-/// Read inventory slot `slot` under a short borrow, cloned out so the caller holds no borrow.
-/// `None` = empty / out of range / a token with no equipment source.
-///
-/// **Unit-keyed, and that is the reference's own shape** (decision 0631): the engine answers
-/// `GetInventoryItemTexture(unit, slot)` for any unit whose item data it holds, which is why the
-/// inspect paper doll reuses the very same bindings rather than a parallel `GetInspectItem*`
-/// family. Two sources, by token:
-///
-/// - `"player"` → the self feed ([`Model::inventory_slots`]), resolved from our PRIVATE
-///   `PLAYER_FIELD_INV_SLOT_*` guids → item objects → templates. Carries counts, durability,
-///   locks — everything an owned item object knows.
-/// - the **inspected** token → [`Model::inspect`], resolved from the target's PUBLIC
-///   `PLAYER_VISIBLE_ITEM_*` entries. No item objects exist for a foreign player (their inventory
-///   guids are server-private), so those views carry entry/icon/name/quality and nothing else —
-///   which is exactly why the reference's inspect window shows no stack counts or durability.
+/// `token`'s inventory slot, unit-keyed as in the reference so the inspect doll reuses these
+/// bindings: `"player"` reads our own items, the inspected unit its public
+/// `PLAYER_VISIBLE_ITEM_*` entries, which carry no counts or durability.
 fn player_inv_slot(lua: &Lua, token: &Option<String>, slot: i64) -> Option<InvSlotView> {
     let token = token.as_deref()?;
     let idx = usize::try_from(slot).ok()?;
@@ -573,30 +379,17 @@ fn player_inv_slot(lua: &Lua, token: &Option<String>, slot: i64) -> Option<InvSl
     model.inv_slot(token, idx)
 }
 
-/// The live-API inventory ids the BANK occupies — `BankButtonIDToInvSlotID`'s own two bands
-/// (`super::bank`): the 24 vault slots at 40..=63, the six bank-bag slots at 64..=69.
+/// The bank's live-API ids, `BankButtonIDToInvSlotID`'s two bands: 24 vault slots, 6 bag slots.
 const BANK_INV_SLOTS: std::ops::RangeInclusive<usize> = 40..=63;
 const BANK_BAG_INV_SLOTS: std::ops::RangeInclusive<usize> = 64..=69;
 
-/// The container id the vault's own slots live under — `ui_items`' constant of the same name,
-/// restated here because this file is the other end of the same map.
+/// The vault's container id; must match `ui_items::BANK_CONTAINER` in the app.
 const BANK_CONTAINER: i64 = -1;
 
 impl Model {
-    /// The equipment slot `token` exposes at live-API id `slot`, or `None`. The one place the
-    /// source routing is decided — shared by the `GetInventoryItem*` getters and
-    /// `GameTooltip:SetInventoryItem`, so a tooltip can never disagree with the icon under it.
-    ///
-    /// **THREE sources now, and the third is a VIEW, not a store** (decision 1751's bank swap).
-    /// The reference's bank paints every one of its slots through the *inventory* API —
-    /// `BankFrameItemButton_OnUpdate` reads `GetInventoryItemTexture("player", BankButtonIDToInv
-    /// SlotID(id))` (BankFrame.lua:35) — while benilla feeds the very same items as *containers*
-    /// (`-1` for the vault, `5..10` for the bank bags), which is how our own bank window read
-    /// them. Those are two names for one set of descriptor fields, so the fix is a map, not a
-    /// second copy: a read in the bank band is answered from the container snapshot. Duplicating
-    /// the items into a wider `inventory_slots` array would put two truths in the model and let
-    /// a tooltip disagree with the icon under it, which is the one thing this function exists to
-    /// prevent.
+    /// The item `token` exposes at live-API id `slot`, the one routing the `GetInventoryItem*`
+    /// getters and `GameTooltip:SetInventoryItem` share. Stock paints the bank through this API
+    /// (`BankFrame.lua:35`), so the bank band is answered from the container snapshot.
     pub(super) fn inv_slot(&self, token: &str, slot: usize) -> Option<InvSlotView> {
         if token.eq_ignore_ascii_case("player") {
             if let Some(view) = self.bank_inv_slot(slot) {
@@ -612,7 +405,6 @@ impl Model {
             .clone()
     }
 
-    /// The bank band's answer, or `None` for any id outside it — see [`Model::inv_slot`].
     fn bank_inv_slot(&self, slot: usize) -> Option<InvSlotView> {
         if BANK_INV_SLOTS.contains(&slot) {
             let vault = self.containers.get(&BANK_CONTAINER)?;
@@ -620,12 +412,8 @@ impl Model {
             return vault.slots.get(&n).map(InvSlotView::from_container_slot);
         }
         if BANK_BAG_INV_SLOTS.contains(&slot) {
-            // A bank BAG is not a slot in a container — it IS one, so there is no container slot
-            // to map and this band is a real store ([`BankBagSlots`], fed off the player
-            // descriptor's own `PLAYER_FIELD_BANK_BAG_SLOT_*` guids by the same system that feeds
-            // the doll). It has to be the whole item, not just its icon: the reference picks a
-            // bank bag up with `PickupBagFromSlot(BankButtonIDToInvSlotID(i, 1))` and describes it
-            // with `GameTooltip:SetInventoryItem("player", …)`, both of which read this band.
+            // A bank bag is a container, not a slot in one, so this band is its own store; stock
+            // picks it up and describes it through this API.
             let i = slot - BANK_BAG_INV_SLOTS.start();
             return self.bank_bag_slots.get(i)?.clone();
         }
@@ -633,15 +421,9 @@ impl Model {
     }
 }
 
-/// The shared inventory-slot reader's whitelist (`0x4c8520`), on the **0-based** value it hands
-/// back (`0x4c8546 dec eax`) — Lua ids are one higher. Anything outside it raises the calling
-/// binding's own "Invalid inventory slot in …", which is not the same thing as an empty answer.
-///
-/// The bands are the reader's own, kept apart rather than merged into one 39..=68 range because
-/// they are different stores: the ammo pseudo-slot, the doll (equipment + the four equipped bag
-/// icons), the bank's 24 vault slots, its 6 bag slots, and the keyring. Note what is NOT here —
-/// the backpack's own 16 item slots (0-based 23..=38) and buyback (69..=80): both are addressed
-/// through the container API instead, and a macro handing either to an inventory binding raises.
+/// The inventory-slot reader's whitelist (`0x4c8520`) on its 0-based slot (`0x4c8546`); outside
+/// it the binding raises "Invalid inventory slot in …". The backpack's item slots (23..=38) and
+/// buyback (69..=80) are container-API slots, not in it.
 fn inventory_slot_reader_accepts(slot0: i32) -> bool {
     slot0 == -1                            // Lua 0      the ammo leg
         || (0x00..=0x16).contains(&slot0)  // Lua 1..=23   the doll + the four equipped bags
@@ -650,7 +432,6 @@ fn inventory_slot_reader_accepts(slot0: i32) -> bool {
         || (0x51..=0x70).contains(&slot0) // Lua 82..=113 the keyring
 }
 
-/// The display name inside an item link — the text between `|h[` and `]|h`.
 fn link_item_name(link: &str) -> Option<String> {
     let (_, rest) = link.split_once("|h[")?;
     let (name, _) = rest.split_once("]|h")?;
@@ -658,11 +439,7 @@ fn link_item_name(link: &str) -> Option<String> {
 }
 
 impl InvSlotView {
-    /// The same item, seen through the inventory API instead of the container API — the map
-    /// [`Model::inv_slot`]'s bank band is built on. Every field is the same descriptor field under
-    /// the other name; what a `ContainerSlot` has and this does not (`equip_slots`, `cooldown`,
-    /// `readable`) has no inventory-API reader, and what this has and a container slot does not
-    /// (`flags`) is not carried by the container feed.
+    /// A container slot seen through the inventory API, for `Model::inv_slot`'s bank band.
     fn from_container_slot(slot: &super::container::ContainerSlot) -> Self {
         InvSlotView {
             item_id: slot.item_id,
@@ -670,9 +447,7 @@ impl InvSlotView {
             icon: slot.texture.clone(),
             count: slot.count,
             quality: slot.quality.map_or(0, |q| q as i32),
-            // A container slot carries no `name` of its own — the container API never asks for one
-            // — but its `link` is composed FROM the name (`|Hitem:…|h[Name]|h`), so the one field
-            // the inventory API adds is recoverable rather than absent.
+            // A container slot has no name, but its link is built from it.
             name: slot.link.as_deref().and_then(link_item_name),
             durability: slot.durability,
             already_bound: slot.already_bound,
@@ -680,66 +455,32 @@ impl InvSlotView {
             locked: slot.locked,
             creator: slot.creator.clone(),
             enchants: slot.enchants.clone(),
-            // Every band this mapper serves — the bank vault, Lua 40..=63 — sits past the
-            // binding's `0x16` short-circuit, so a container met here answers 0 whatever is inside
-            // it and only the `Some`/`None` distinction carries information. "Names Bag0Slot as a
-            // place it could be worn" is the same set as TYPEMASK_CONTAINER (`INVTYPE_BAG` is the
-            // only inventory type `FindEquipSlot` maps there — `cursor::bag_verbs::is_container`
-            // states the equivalence in full), and it is what a container slot carries.
+            // Slot 20 (`Bag0Slot`) among `equip_slots` marks a container (`INVTYPE_BAG`). The bank
+            // vault is past the `0x16` short-circuit, so only `Some` versus `None` matters.
             contents_count: slot.equip_slots.contains(&20).then_some(0),
             ..Default::default()
         }
     }
 }
 
-/// The four reference `.data` literals the two indexed stat bindings raise with — read out of the
-/// shipped 5875 image, verbatim, and NOT paraphrased (the house rule `GetInventorySlotInfo` sets:
-/// an addon may compare or key on the message text).
-///
-/// **Each binding has TWO raises with different strings, and the string pool interleaves them so
-/// that "the nearest `Usage:`" picks the WRONG binding's.** The layout is
-/// `Usage: UnitResistance…` (`0x8510fc`) · `Invalid resistance index…` (`0x85112c`) ·
-/// `Usage: UnitStat…` (`0x851158`) · `Invalid stat index…` (`0x85117c`) — so the `Usage:` two
-/// padding bytes after `UnitResistance`'s index message belongs to `UnitStat`. Each literal is
-/// fixed by the `push <VA>` that names it (`0x5187d6`/`0x5187ed` for `UnitStat`,
-/// `0x5185cb`/`0x5185e2` for `UnitResistance`), never by proximity. This is the same trap
-/// `GetInventorySlotInfo`'s transcription records, one degree worse.
-///
-/// The **index** arm is these two — no `Usage:` prefix, and the offending index is *not*
-/// interpolated (`luaL_error` is called cdecl with exactly two dwords at all four sites: the `L`
-/// and the message, no varargs, so the literal is never a format string).
+/// The reference's verbatim index-arm strings, pushed at `0x5187d6` (`0x85117c`) and `0x5185cb`
+/// (`0x85112c`): no `Usage:` prefix, the index not interpolated. The pool interleaves the two
+/// bindings' strings, so each is fixed by its `push`, never by adjacency.
 const STAT_INDEX_ERROR: &str = "Invalid stat index in UnitStat";
 const RESISTANCE_INDEX_ERROR: &str = "Invalid resistance index in UnitResistance";
-/// The **argument-type** arm — a separate, earlier raise, reached only by a value that is neither
-/// numeric nor a numeric string (the guards are coercion-aware: `UnitStat("player", "3")` serves
-/// stat 3). [`binding_abi`] owns that contract.
+/// The argument-type arm, pushed at `0x5187ed` (`0x851158`) and `0x5185e2` (`0x8510fc`), for a
+/// value neither a number nor a numeric string ([`binding_abi`]).
 const STAT_USAGE: &str = "Usage: UnitStat(\"unit\", statIndex)";
 const RESISTANCE_USAGE: &str = "Usage: UnitResistance(\"unit\", resistanceIndex)";
 
-/// Register the paper-doll stat/slot globals (decision 0208 §3).
+/// Register the paper-doll stat/slot globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // UnitStat("player", i /*1..=5*/) → (stat, effectiveStat, posBuff, negBuff).
-    //
-    // **The first two returns are the same field, UNDECOMPOSED** — `UNIT_FIELD_STAT0+i` raw
-    // (`fild`, `0x518689`), then that same value clamped at zero (`0x5186a3`–`0x5186b7`:
-    // `setl cl; dec ecx; and ecx,eax`). Slots 3/4 are `PLAYER_FIELD_POSSTAT0+i` (`0x518712`) and
-    // `NEGSTAT0+i` (`0x518772`), each behind a SELF gate. VERIFIED, wow-re
-    // `ui/scratch/pet-paperdoll-stat-api.md` §4.
-    //
-    // This served `effective − pos − neg` as the first return until decision 1397. Subtracting is
-    // the ref Lua's *own* job — `PaperDollFrame_SetStats` writes the tooltip's base as
-    // `(stat - posBuff - negBuff)` — so a pre-subtracted `stat` deducts the buff twice. It was
-    // invisible only because pos/neg were stuck at 0 by the field-decode bug 1397 fixes; the two
-    // are one repair.
-    //
-    // **Note the contrast with the two resistance bindings below**, whose first return really *is*
-    // the decomposed base (`0x5efcd0`: `*arg2 = raw - pos - neg`). The reference reads the two
-    // families differently, and the ref Lua's own asymmetry — `SetStats` subtracts, `SetResistances`
-    // and `PaperDollFormatStat` do not — is the tell.
-    //
-    // **An out-of-range index RAISES; it does not answer zeros** (see [`STAT_INDEX_ERROR`]).
+    // UnitStat(unit, 1..=5) → (stat, effectiveStat, posBuff, negBuff): `UNIT_FIELD_STAT0+i` raw
+    // (`0x518689`), then clamped at zero (`0x5186a3`-`0x5186b7`), then `POSSTAT0+i` and
+    // `NEGSTAT0+i` behind a SELF gate (`0x518712`, `0x518772`). Unlike `UnitResistance` it is not
+    // decomposed: stock subtracts the buffs itself (`PaperDollFrame.lua:152`). A bad index raises.
     g.set(
         "UnitStat",
         lua.create_function(|lua, (token, i): (Value, Value)| {
@@ -761,11 +502,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitResistance("player", school /*0..=6*/) → (base, resistance, positive, negative) — the
-    // decomposition helper `0x5efcd0` per school ([0] = armor): `base = raw − pos − neg`, computed
-    // BEFORE the clamp, and `resistance = max(raw, 0)`. A school cursed below zero therefore reads
-    // a *displayed* 0 with the real (negative) total still folded out of `base`.
-    // Out-of-range raises too, with its own string ([`RESISTANCE_INDEX_ERROR`]).
+    // UnitResistance(unit, 0..=6) → (base, resistance, positive, negative) through `0x5efcd0`,
+    // school 0 armor: `base = raw - pos - neg` before the clamp, `resistance = max(raw, 0)`.
     g.set(
         "UnitResistance",
         lua.create_function(|lua, (token, school): (Value, Value)| {
@@ -791,9 +529,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitArmor("player") → (base, effectiveArmor, armor, posBuff, negBuff) — school 0 through the
-    // same `0x5efcd0`, whose 3rd and 4th out-params are both the clamped total (the ref reads
-    // effectiveArmor and armor equivalently, and both are zeroed together when raw < 0).
+    // UnitArmor(unit) → (base, effectiveArmor, armor, posBuff, negBuff): school 0 through
+    // `0x5efcd0`, effectiveArmor and armor both its clamped total.
     g.set(
         "UnitArmor",
         lua.create_function(|lua, token: Option<String>| {
@@ -810,10 +547,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitDamage("player") → (minDamage, maxDamage, minOffHandDamage, maxOffHandDamage,
-    // physicalBonusPos, physicalBonusNeg, percent) — the damage fields verbatim plus the
-    // school-0 MOD_DAMAGE_DONE decomposition (percent 1.0 when absent; decision 0208 "to
-    // confirm" flags the buffed decomposition as inferred).
+    // UnitDamage(unit) → (minDamage, maxDamage, minOffHandDamage, maxOffHandDamage,
+    // physicalBonusPos, physicalBonusNeg, percent): the damage fields verbatim, then school 0's
+    // `MOD_DAMAGE_DONE` split, which is inferred, not traced in the reference.
     g.set(
         "UnitDamage",
         lua.create_function(|lua, token: Option<String>| {
@@ -831,9 +567,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitAttackSpeed("player") → (mainSpeed, offhandSpeed|nil) in seconds (BASEATTACKTIME /
-    // 1000). Offhand is nil unless an offhand weapon is equipped — the snapshot's has_offhand,
-    // the app's call (the field itself streams regardless).
+    // UnitAttackSpeed(unit) → (mainSpeed, offhandSpeed) in seconds; nil offhand without a weapon.
     g.set(
         "UnitAttackSpeed",
         lua.create_function(|lua, token: Option<String>| {
@@ -847,8 +581,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitAttackPower("player") → (base, posBuff, negBuff): base = UNIT_FIELD_ATTACK_POWER, the
-    // buffs the MODS field's split signed halves (neg ≤ 0 — StatSystem.cpp:335-336).
+    // UnitAttackPower(unit) → (base, posBuff, negBuff): `UNIT_FIELD_ATTACK_POWER` and the signed
+    // halves of `_MODS` (vmangos `StatSystem.cpp:335-336`).
     g.set(
         "UnitAttackPower",
         lua.create_function(|lua, token: Option<String>| {
@@ -862,7 +596,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitRangedAttackPower("player") → (base, posBuff, negBuff) — the ranged twin.
+    // UnitRangedAttackPower(unit) → (base, posBuff, negBuff), from the ranged fields.
     g.set(
         "UnitRangedAttackPower",
         lua.create_function(|lua, token: Option<String>| {
@@ -876,21 +610,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitAttackBothHands("player") → (mainBase, mainMod, offBase, offMod) — **FOUR** returns, one
-    // pair per hand: each hand's weapon-skill line, value + its temp+perm bonus, resolved app-side
-    // via the weapon_subclass_skill table (unarmed = SKILL_UNARMED for an empty or non-weapon
-    // hand).
-    //
-    // **It answered two until decision 1810**, which is 1793's shape at its quietest: `0x518810`
-    // calls `[vtbl+0xb0]` TWICE, hand 0 then hand 1, and pushes `(base0, mod0, base1, mod1)`
-    // (VERIFIED, wow-re `ui/scratch/pet-paperdoll-stat-api.md` §4). The reference's own
-    // `PaperDollFrame_SetAttackBothHands` destructures only the first two — its next line is
-    // `-- FIXME: The offhand stats aren't displayed yet.` — so putting the stock character sheet on
-    // the chain could never have exposed this. An addon reading four gets two nils.
-    //
-    // A non-player unit takes the same virtual fork `UnitDefense` does (`0x6136b0`) and lands on
-    // the identical `level * 5` — and that one **ignores its hand index outright**, so both hands
-    // answer the same pair. The pet sheet's Attack row reads 300 at level 60, like its Defense row.
+    // UnitAttackBothHands(unit) → (mainBase, mainMod, offBase, offMod): `0x518810` calls
+    // `[vtbl+0xb0]` for hand 0 then hand 1. Stock reads only the first pair
+    // (`PaperDollFrame.lua:398-399`). A pet's `CGUnit_C` body (`0x6136b0`) ignores the hand, so
+    // both pairs are `(level * 5, 0)`.
     g.set(
         "UnitAttackBothHands",
         lua.create_function(|lua, token: Option<String>| {
@@ -913,7 +636,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitRangedAttack("player") → (base, modifier) — the ranged weapon's skill pair.
+    // UnitRangedAttack(unit) → (base, modifier), the ranged weapon's skill pair.
     g.set(
         "UnitRangedAttack",
         lua.create_function(|lua, token: Option<String>| {
@@ -926,19 +649,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitDefense(unit) → (base, modifier). The ref reads exactly two numbers and folds the
-    // modifier's sign itself (PaperDollFrame.lua:259-271: modifier > 0 → a green posBuff, < 0 → a
-    // red negBuff).
-    //
-    // **The fork is a VIRTUAL CALL on the resolved unit, not a token test** (wow-re
-    // `ui/scratch/pet-paperdoll-stat-api.md`, the §5 that corrected decision 1057's INTERIM):
-    // `[vtbl+0xac]` is either `CGPlayer_C 0x5eda20` — resolve the Defense SkillLine (`0x6de040`)
-    // and read `PLAYER_SKILL_INFO` — or `CGUnit_C 0x613680`, which is three lines:
-    // `*out1 = UNIT_FIELD_LEVEL * 5; *out2 = 0`. **A level-60 pet shows 300**, not the 0 that
-    // 1057 shipped while the dispatch was out. The outer gate is SELF **or**
-    // `UNIT_FIELD_SUMMONEDBY == my guid`, which our pet passes and no other token we serve does —
-    // so `"player"` takes the skill leg, `"pet"` the level leg (a warlock's minion included: it is
-    // summoned by us too), and everything else the gate-failure zeros.
+    // UnitDefense(unit) → (base, modifier); stock splits the modifier's sign itself
+    // (`PaperDollFrame.lua:259-271`). The gate is SELF or `UNIT_FIELD_SUMMONEDBY` = us, then
+    // `[vtbl+0xac]`: `CGPlayer_C` `0x5eda20` reads the Defense skill (`0x6de040`), `CGUnit_C`
+    // `0x613680` answers level * 5 and 0. Any other token gets the gate's zeros.
     g.set(
         "UnitDefense",
         lua.create_function(|lua, token: Option<String>| {
@@ -954,10 +668,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetDodgeChance() / GetParryChance() / GetBlockChance() → one number each, no unit argument
-    // (`reference/1.12-shapes.tsv`, all three `exact` on argc, arity and kind). Player-implicit,
-    // like `HasWandEquipped` below; a field that has not streamed reads 0, which is the wire's own
-    // default rather than an absence to model.
+    // GetDodgeChance(), GetParryChance(), GetBlockChance() → one number each, no unit argument
+    // (`0x516f00`, `0x516fc0`, `0x516f60`); 0 before the field streams.
     for (name, pick) in [
         ("GetDodgeChance", 0usize),
         ("GetParryChance", 1),
@@ -979,9 +691,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // UnitRangedDamage("player") → (speed, minDamage, maxDamage, physicalBonusPos,
-    // physicalBonusNeg, percent) — RANGEDATTACKTIME/1000 + the ranged damage range + the same
-    // school-0 mods as UnitDamage.
+    // UnitRangedDamage(unit) → (speed, minDamage, maxDamage, physicalBonusPos, physicalBonusNeg,
+    // percent), with `UnitDamage`'s school-0 mods.
     g.set(
         "UnitRangedDamage",
         lua.create_function(|lua, token: Option<String>| {
@@ -998,8 +709,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasWandEquipped() → 1/nil (the ref's ranged block swaps "Shoot" in on it). No unit arg —
-    // the live global is player-implicit.
+    // HasWandEquipped() → 1 or nil, for the player.
     g.set(
         "HasWandEquipped",
         lua.create_function(|lua, ()| {
@@ -1013,8 +723,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemID("player", slot) → itemId | nil (slot per GetInventorySlotInfo: 0 ammo,
-    // 1..=19 equipment). Player-token-only like the stat block — the INV_SLOT guids are PRIVATE.
+    // GetInventoryItemID(unit, slot) → itemId or nil.
     g.set(
         "GetInventoryItemID",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1025,8 +734,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemTexture("player", slot) → icon path | nil (nil while the template answer is
-    // in flight — the button shows the empty-slot art until the push lands).
+    // GetInventoryItemTexture(unit, slot) → icon path, or nil until the item's template arrives.
     g.set(
         "GetInventoryItemTexture",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1037,12 +745,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemLink(unit, slot) → the full escaped `|cff…|Hitem:…|h[Name]|h|r` | nil (nil
-    // while the template answer is in flight — the link is built from the item's name + quality,
-    // and neither is known until it lands). Unit-keyed like its siblings, so the reference's paper
-    // doll and its inspect twin both reach it from one binding:
-    // `DressUpItemLink(GetInventoryItemLink("player", this:GetID()))` (PaperDollFrame.lua:650) and
-    // the shift-click `ChatFrameEditBox:Insert(...)` beside it (l.653). Decision 1059.
+    // GetInventoryItemLink(unit, slot) → `|cff…|Hitem:…|h[Name]|h|r`, or nil until the template
+    // arrives with the name and quality.
     g.set(
         "GetInventoryItemLink",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1053,33 +757,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The binding's own two `.data` literals, read out of the shipped 5875 image and NOT
-    // paraphrased (the house rule `GetInventorySlotInfo` set: an addon may compare on the text).
-    // Neither carries a period or a newline.
-    //
-    //   `0x8489b4`  arg 1 fails `is-number-or-string 0x6f3510`
-    //   `0x848984`  arg 2 fails `lua_isnumber`, OR names a slot outside the reader's whitelist
-    //
-    // (`0x848b54` is the sibling `Invalid inventory slot in IsInventoryItemLocked`, unclaimed
-    // here: that binding's own argument reader has not been carved, and guessing it is exactly
-    // what this block exists to stop.)
+    // The reference's verbatim strings: `0x8489b4` when arg 1 is neither number nor string
+    // (`0x6f3510`), `0x848984` when arg 2 is not a number or not a whitelisted slot.
     const USAGE_GET_INVENTORY_ITEM_COUNT: &str = "Usage: GetInventoryItemCount(unit, slot)";
     const INVALID_SLOT_GET_INVENTORY_ITEM_COUNT: &str =
         "Invalid inventory slot in GetInventoryItemCount";
-    // GetInventoryItemCount("player", slot) — CARVED (`0x4c8680`, wow-re
-    // `system/ui/scratch/inventory-item-count-law.md`), and it is nothing like the shape every
-    // secondary source describes. Four answers, in the reference's own order:
-    //
-    //  · an EMPTY slot pushes **1**, not 0 (`0x4c8797`). Both FrameXML callers gate on
-    //    `GetInventoryItemTexture` first, which is why nobody ever noticed.
-    //  · a non-container pushes `ITEM_FIELD_STACK_COUNT`.
-    //  · a CONTAINER (`OBJECT_FIELD_TYPE & 4`, `0x4c87a6`) in a slot whose 0-based id is **past
-    //    `0x16`** pushes a literal 0 (`0x4c87af cmp …,0x16` / `jg 0x4c8813`) — before any lookup.
-    //    The bank's six bag slots (Lua 64..69 → 0-based 63..68) are all in that band, which is the
-    //    whole reason `BankFrameBag1` shows no digit in the real client: `SetItemButtonCount`'s
-    //    `isBag and count > 0` arm never fires.
-    //  · a CONTAINER in one of the four equipped bag slots pushes the `ItemSubClass.dbc`-gated
-    //    sum of its contents — see [`InvSlotView::contents_count`].
+    // GetInventoryItemCount(unit, slot) (`0x4c8680`): an empty slot pushes 1 (`0x4c8797`), a
+    // non-container its stack count, a container past 0-based slot `0x16` 0 before any lookup
+    // (`0x4c87af`, so a bank bag shows no digit), and an equipped bag its `contents_count`.
     g.set(
         "GetInventoryItemCount",
         lua.create_function(|lua, (unit, slot): (Value, Value)| {
@@ -1103,8 +788,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemQuality("player", slot) → 0..6 | nil (nil for an empty slot — the wiki
-    // shape; the ref keys quality borders on it).
+    // GetInventoryItemQuality(unit, slot) → 0..6, or nil for an empty slot (the wiki's shape).
     g.set(
         "GetInventoryItemQuality",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1115,10 +799,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemBroken("player", slot) → 1 | nil — the shared broken classification
-    // ([`slot_is_broken`]: durability 0 with a max, or the force-red flag bit; wrapped never).
-    // The ref's PaperDollItemSlotButton_Update keys the red slot tint on it
-    // (PaperDollFrame.lua:670-676).
+    // GetInventoryItemBroken(unit, slot) → 1 or nil, per `slot_is_broken`.
     g.set(
         "GetInventoryItemBroken",
         lua.create_function(|lua, (token, slot): (Option<String>, i64)| {
@@ -1129,22 +810,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryItemCooldown(unit, slot) → (start, duration, enable), the EQUIPPED twin of
-    // `GetContainerItemCooldown` (container.rs) and the same `GetTime`-clock convention.
-    //
-    // **It answers "no cooldown" and that is an absent FEED, not a pretended one.** benilla has no
-    // equipped-item cooldown source yet — the same gap `tooltip_item`'s `SetInventoryItem` already
-    // records where it leaves `hasCooldown` nil — so there is nothing to report and `(0, 0, 1)` is
-    // exactly what the container twin answers for a slot with no record. It is bound rather than
-    // left absent because the SOURCED `PaperDollFrame.lua` calls it UNCONDITIONALLY, once per
-    // `PaperDollItemSlotButton_Update`: without it every button built from
-    // `PaperDollItemSlotButtonTemplate` or `BagSlotButtonTemplate` raises inside its own OnLoad,
-    // which is how pfUI's bag bar would meet it. A raise there is not the loud-and-correct kind
-    // (1203) — it is a raise on a verb whose honest answer we already know.
-    //
-    // When an equipped-cooldown feed lands, this reads it the way the container twin reads
-    // `container_cooldowns`, and the CooldownFrame the doll slots already carry starts sweeping
-    // with no caller change.
+    // GetInventoryItemCooldown(unit, slot) → (start, duration, enable). Not fed: with no
+    // equipped-item cooldown source it answers `(0, 0, 1)`, no cooldown, as the container verb
+    // does; stock calls it on every slot update (`PaperDollFrame.lua:691`).
     g.set(
         "GetInventoryItemCooldown",
         lua.create_function(|_, (_token, _slot): (Option<String>, i64)| {
@@ -1152,10 +820,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventoryAlertStatus(index) → the region's alert status (`INV_ALERT_STATUS`: 0 none,
-    // 3 damaged/low-ammo, 4 broken; 1/2 = temp-enchant alerts, unfed) — DurabilityFrame's
-    // armor-guy read. Valid 1..=12 (the client's own 12-entry table; index 12 = low ammo, which
-    // the 1.12 FrameXML never reads); out-of-range reads 0.
+    // GetInventoryAlertStatus(index) → the status of region 1..=12: 0 none, 3 damaged or low ammo,
+    // 4 broken.
     g.set(
         "GetInventoryAlertStatus",
         lua.create_function(|lua, index: usize| {
@@ -1168,9 +834,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // OffhandHasWeapon() → 1 | nil — whether the off-hand slot holds a WEAPON (item class 2)
-    // rather than a shield/held-in-off-hand; DurabilityFrame.lua swaps the shield glyph for the
-    // off-weapon glyph on it. Read off the equipped slot view + the template store.
+    // OffhandHasWeapon() → 1 or nil: whether the off hand holds a weapon (item class 2).
     g.set(
         "OffhandHasWeapon",
         lua.create_function(|lua, (): ()| {
@@ -1184,64 +848,33 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInventorySlotInfo(slotName) → (slotId, textureName, checkRelic) — the client's own
-    // PaperDollItemFrame.dbc rows (SLOT_INFO above). An unknown name is a Lua error, the client's
-    // own behavior.
-    //
-    // `checkRelic` is the number 1 for the ranged slot and nil elsewhere, unconditionally — it is
-    // a property of the SLOT, not of the player. It pairs with `UnitHasRelicSlot("player")`,
-    // which is the class half, and stock reads the two as a conjunction
-    // (`PaperDollFrame.lua:680`/`:744`). This comment used to say `UnitHasRelicSlot` is a
-    // later-era concept, always false in vanilla; it is not — decision 1796.
+    // GetInventorySlotInfo(slotName) → (slotId, textureName, checkRelic) from `SLOT_INFO`.
+    // `checkRelic` is a property of the slot; stock pairs it with `UnitHasRelicSlot("player")`
+    // (`PaperDollFrame.lua:680`, `:744`).
     g.set(
         "GetInventorySlotInfo",
         lua.create_function(|lua, name: String| {
-            // **The name match is CASE-INSENSITIVE, and that was the whole bug.** `0x4c8215` calls
-            // `0x64a4c0` -> `0x414310`, the CRT `_strnicmp`, whose comparison folds BOTH operands
-            // (`0x414352 add ah,dh` / `0x41435c add al,dh`, with `dh = 0x20` and the A-Z bounds in
-            // `bh`/`bl`) before the byte compare — ASCII folding, which is exactly
-            // `eq_ignore_ascii_case`. Its locale-aware arm folds too, so the verdict does not
-            // depend on one. `maxlen` is `0x7fffffff` and the loop stops at the first NUL on either
-            // side, so it is a FULL-STRING compare, not a prefix. The non-circular control is that
-            // the image also ships a byte-identical case-SENSITIVE wrapper (`0x64a480` ->
-            // `0x40de80`, `rep cmpsb`, no fold) and this binding does not call it.
-            //
-            // Two 1.12-era corpus addons died at session start on this and both worked on the real
-            // client: `FuBar_AmmoFu` passes `"ammoSlot"` and `FuBar_PoisonFu` `"MAINHANDSLOT"`.
-            // The 36 shipped names stay pairwise distinct after folding, so first-match-wins cannot
-            // become ambiguous.
+            // A full-string ASCII case-insensitive match: `0x4c8215` calls `_strnicmp` (`0x64a4c0`
+            // -> `0x414310`) with no length limit. The 36 names stay distinct after folding.
             let Some((_, id, art)) = SLOT_INFO
                 .iter()
                 .find(|(n, _, _)| n.eq_ignore_ascii_case(&name))
             else {
-                // The raise is faithful — there is no nil path, and `0x4c823c xor eax,eax; ret` is
-                // dead code after `luaL_error` longjmps. The message is the reference's own
-                // (`.rdata 0x848894`): no `Usage:` prefix, and the offending name is NOT
-                // interpolated. The `Usage:` literals either side of it in the string pool belong
-                // to `KeyRingButtonIDToInvSlotID` and `GetInventoryItemTexture` — the adjacency
-                // trap.
+                // An unknown name raises, never nil; the string is `0x848894`'s, verbatim.
                 return Err(mlua::Error::runtime(
                     "Invalid inventory slot in GetInventorySlotInfo",
                 ));
             };
             Ok((
                 *id,
-                // The DBC string, VERBATIM. `0x4c825b` pushes `[esi+4]` straight through
-                // (`0x6f3890`, `repne scasb` for the length) with no normalisation anywhere, and
-                // the stored bytes are `interface\paperdoll\UI-PaperDoll-Slot-Bag.blp` — a
-                // LOWERCASE directory, and the `.blp` extension present. Only the
-                // `UI-PaperDoll-Slot-` leaf is mixed case. Texture *loading* would not care (the
-                // asset VFS folds case), but this is a Lua-visible string: anything that compares
-                // it, keys a table by it or concatenates it sees these bytes.
+                // The DBC's bytes verbatim, unnormalised (`0x4c825b`): a lowercase directory and
+                // the `.blp` extension, visible to any Lua that compares the string.
                 Value::String(
                     lua.create_string(format!(
                         "interface\\paperdoll\\UI-PaperDoll-Slot-{art}.blp"
                     ))?,
                 ),
-                // `checkRelic` — the NUMBER 1, never a boolean, and only for `RangedSlot`
-                // (`0x4c8263 dec ecx; cmp ecx,0x11`, i.e. SlotNumber 18); nil for every other slot.
-                // It shipped as a constant `false` here, which is falsey like nil but is the wrong
-                // type for a caller that compares it to 1, and wrong outright for the ranged slot.
+                // `checkRelic`: the number 1 for `RangedSlot` only (`0x4c8263`), not a boolean.
                 if *id == 18 {
                     Value::Integer(1)
                 } else {
@@ -1300,8 +933,7 @@ mod tests {
         }
     }
 
-    /// A pet's snapshot: the UNIT half filled, every PLAYER-block-sourced field at its default —
-    /// what `ui_char::unit_combat_stats` really produces over a creature's descriptor.
+    /// A pet's snapshot: the UNIT fields filled, the PLAYER-block ones at their defaults.
     fn pet_stats() -> UnitCombatStats {
         UnitCombatStats {
             stats: [63, 45, 68, 32, 42],
@@ -1336,26 +968,16 @@ mod tests {
         assert_eq!(weapon_subclass_skill(18), Some(226)); // crossbow
         assert_eq!(weapon_subclass_skill(19), Some(228)); // wand
         assert_eq!(weapon_subclass_skill(20), Some(356)); // fishing pole
-                                                          // The skill-less rows + out of range.
         for sub in [9u32, 11, 12, 14, 21, 100] {
             assert_eq!(weapon_subclass_skill(sub), None, "subclass {sub}");
         }
     }
 
-    /// **The three avoidance verbs are player-implicit and answer ONE number each.**
-    ///
-    /// `reference/1.12-shapes.tsv` has all three at argc 0 / arity 1 / kind number, every column
-    /// `exact` (`GetDodgeChance 0x516f00`, `GetBlockChance 0x516f60`, `GetParryChance 0x516fc0`),
-    /// so an argument is ignored rather than resolved and there is no pet leg. The absent
-    /// snapshot answers 0 — the wire's own default for a field that has not streamed, and the
-    /// only answer a one-number arity can give.
-    ///
-    /// The three values below are exactly representable in `f32`, so the widening to Lua's double
-    /// is lossless and the assertions can be equalities rather than epsilons.
+    /// The values are exact in `f32`, so the assertions compare equal.
     #[test]
     fn the_avoidance_verbs_are_player_implicit_and_answer_one_number() {
         let mut s = UiScript::new().unwrap();
-        // Before anything streams: a number, not nil — the arity is exact.
+        // Before anything streams: 0, not nil.
         assert_eq!(s.eval::<f64>("return GetDodgeChance()").unwrap(), 0.0);
         s.set_player_combat_stats(Some(UnitCombatStats {
             dodge_percent: 5.25,
@@ -1366,8 +988,7 @@ mod tests {
         assert_eq!(s.eval::<f64>("return GetDodgeChance()").unwrap(), 5.25);
         assert_eq!(s.eval::<f64>("return GetParryChance()").unwrap(), 3.5);
         assert_eq!(s.eval::<f64>("return GetBlockChance()").unwrap(), 2.75);
-        // Exactly one return, and a unit token is not a parameter — an addon passing one gets the
-        // player's number, which is what a zero-argc binding does with a stack it never reads.
+        // One return, and a unit argument is ignored.
         assert_eq!(
             s.eval::<i64>("local a, b = GetDodgeChance() return b == nil and 1 or 2")
                 .unwrap(),
@@ -1383,21 +1004,19 @@ mod tests {
     fn unit_stat_serves_the_raw_field_twice_and_the_buff_split() {
         let mut s = UiScript::new().unwrap();
         s.set_player_combat_stats(Some(stats()));
-        // Str: the raw field 25 in BOTH of the first two slots, then the +4/0 split. The ref Lua
-        // does the subtraction itself (`stat - posBuff - negBuff` = 21 for the tooltip's base) —
-        // this binding must not pre-subtract, or the buff is deducted twice.
+        // Str: raw 25 in both first slots; stock subtracts the +4 itself.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("player", 1)"#)
                 .unwrap(),
             (25, 25, 4, 0)
         );
-        // Agi: raw 20 with a −2 debuff (the ref tests negBuff < 0 to pick red over green).
+        // Agi: raw 20 with a −2 debuff.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("player", 2)"#)
                 .unwrap(),
             (20, 20, 0, -2)
         );
-        // Only the SECOND return is clamped: a stat driven below zero keeps its sign in slot 1.
+        // Only the second return is clamped.
         s.set_player_combat_stats(Some(UnitCombatStats {
             stats: [-3, 20, 22, 10, 11],
             ..stats()
@@ -1408,7 +1027,6 @@ mod tests {
             (-3, 0, 4, 0)
         );
         s.set_player_combat_stats(Some(stats()));
-        // A non-player token serves the absent zeros (no other unit streams these fields).
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("target", 1)"#)
                 .unwrap(),
@@ -1416,10 +1034,8 @@ mod tests {
         );
     }
 
-    /// The index arm **raises**, and the truncation that decides which side of the range an
-    /// argument lands on happens FIRST. Both ends converge on one raise (`0x51865a js` and
-    /// `0x518663 jge` → `0x5187d6`), and `_ftol` chops toward zero rather than flooring, so `1.9`
-    /// is a valid `1` while `0.5` and any negative are not.
+    /// The index truncates toward zero (`_ftol`) ahead of the range test (`0x51865a`,
+    /// `0x518663`): 1.9 is stat 1, while 0.5 and any negative raise.
     #[test]
     fn an_out_of_range_stat_index_raises_the_references_own_string() {
         let mut s = UiScript::new().unwrap();
@@ -1433,23 +1049,20 @@ mod tests {
                 msg.contains(STAT_INDEX_ERROR),
                 "UnitStat(\"player\", {arg}) must raise {STAT_INDEX_ERROR:?}, got {msg:?}"
             );
-            // The index arm carries no `Usage:` prefix, and the pool's interleaving makes the
-            // WRONG binding's usage line the nearest one — so assert we took neither.
             assert!(!msg.contains("Usage:"), "no Usage: prefix on the index arm");
         }
-        // Truncation toward zero, ahead of the range test: 1.9 → 1 → stat 0, the valid answer.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("player", 1.9)"#)
                 .unwrap(),
             (25, 25, 4, 0)
         );
-        // The guard is coercion-aware — a numeric STRING is a number here.
+        // A numeric string is a number.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("player", "2")"#)
                 .unwrap(),
             (20, 20, 0, -2)
         );
-        // Neither numeric nor a numeric string takes the OTHER raise, with the other string.
+        // Anything else takes the Usage arm.
         for arg in ["nil", "{}", "true", r#""abc""#] {
             let msg = format!(
                 "{}",
@@ -1461,8 +1074,7 @@ mod tests {
                 "UnitStat(\"player\", {arg}) must take the Usage arm, got {msg:?}"
             );
         }
-        // A missing unit token fails the same way (`0x6f3510` reports NULL past the top as
-        // neither number nor string).
+        // A missing unit fails the same way: `0x6f3510` sees neither number nor string.
         assert!(format!(
             "{}",
             s.eval::<i64>(r#"return UnitStat(nil, 1)"#).unwrap_err()
@@ -1486,27 +1098,24 @@ mod tests {
                 .unwrap(),
             (0, 20, 25, -5)
         );
-        // A school cursed below zero (arcane: −5 total, all from the debuff): the DISPLAYED total
-        // is clamped to 0 (`0x5efcd0`'s tail), while `base` keeps the pre-clamp decomposition.
+        // Arcane cursed to −5: the displayed total clamps to 0, `base` keeps the pre-clamp split.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitResistance("player", 6)"#)
                 .unwrap(),
             (0, 0, 0, -5)
         );
-        // UnitArmor is school 0 with the five-return shape (effectiveArmor = armor = the total).
+        // UnitArmor is school 0, effectiveArmor = armor = the total.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64, i64)>(r#"return UnitArmor("player")"#)
                 .unwrap(),
             (130, 150, 150, 30, -10)
         );
-        // A non-player token: zeros. (UnitArmor takes no index and so has no index raise.)
         assert_eq!(
             s.eval::<(i64, i64, i64, i64, i64)>(r#"return UnitArmor("target")"#)
                 .unwrap(),
             (0, 0, 0, 0, 0)
         );
-        // Out of range RAISES, with UnitResistance's own string — not UnitStat's, which is the
-        // literal sitting two padding bytes away in the reference's string pool.
+        // Out of range raises `UnitResistance`'s own string, not the adjacent `UnitStat` one.
         for arg in ["7", "-1"] {
             let msg = format!(
                 "{}",
@@ -1520,7 +1129,7 @@ mod tests {
                 "UnitResistance(\"player\", {arg}) must raise {RESISTANCE_INDEX_ERROR:?}, got {msg:?}"
             );
         }
-        // School 0 is in range and is armor — the low end is inclusive, unlike UnitStat's.
+        // School 0 is in range, unlike `UnitStat`'s index 0.
         assert!(s
             .eval::<(i64, i64, i64, i64)>(r#"return UnitResistance("player", 0)"#)
             .is_ok());
@@ -1535,11 +1144,10 @@ mod tests {
                 .unwrap(),
             (12.5, 19.5, 5.0, 9.0, 25, -3, f64::from(1.1f32))
         );
-        // No offhand equipped → second return nil.
+        // No off-hand weapon: the second return is nil.
         assert!(s
             .eval::<bool>(r#"local m, o = UnitAttackSpeed("player") return m == 2.9 and o == nil"#)
             .unwrap());
-        // With an offhand: both speeds, in seconds.
         s.set_player_combat_stats(Some(UnitCombatStats {
             has_offhand: true,
             ..stats()
@@ -1549,7 +1157,7 @@ mod tests {
                 .unwrap(),
             (2.9, 1.5)
         );
-        // Absent snapshot / non-player token: zeros, percent 1.0 (the div-safe identity).
+        // Another token, or no snapshot: zeros and percent 1.0.
         assert_eq!(
             s.eval::<(f64, f64, f64, f64, i64, i64, f64)>(r#"return UnitDamage("target")"#)
                 .unwrap(),
@@ -1594,7 +1202,6 @@ mod tests {
                 .unwrap(),
             (2.8, 31.0, 47.0, 25, -3, f64::from(1.1f32))
         );
-        // Non-player: the absent zeros throughout.
         assert_eq!(
             s.eval::<(i64, i64, i64)>(r#"return UnitAttackPower("target")"#)
                 .unwrap(),
@@ -1607,19 +1214,9 @@ mod tests {
         );
     }
 
-    /// **`UnitRangedAttack` does NOT take the pet fork its two neighbours take** (decision 1812).
-    ///
-    /// `UnitDefense` `0x519200` and `UnitAttackBothHands` `0x518810` gate on SELF-OR-MINE and then
-    /// dispatch through the resolved unit's vtable, so a pet passes and lands on `CGUnit_C`'s
-    /// `level * 5`. `UnitRangedAttack` `0x518b90` is a **direct call** gated on the PLAYER typemask
-    /// alone, with no vtable slot and **no `CGUnit_C` fallback body at all** (VERIFIED, wow-re
-    /// `ui/scratch/unitrangedattack-skill-pair.md` §4 — `0x612b40`/`0x5edae0`/`0x5ea460` appear as
-    /// a dword zero times image-wide, against a positive control of one hit each for the four
-    /// addresses that ARE in a vtable).
-    ///
-    /// So a pet's ranged attack is `(0, 0)`, not `level * 5`. The whole reason this is a test and
-    /// not a comment is that the three verbs look interchangeable from the FrameXML side, and
-    /// mirroring the defense handling here would be a plausible, silent, wrong number.
+    /// `UnitDefense` (`0x519200`) and `UnitAttackBothHands` (`0x518810`) fork through the unit's
+    /// vtable to a creature body; `UnitRangedAttack` (`0x518b90`) is a direct call gated on the
+    /// PLAYER typemask (`0x612b40`, `0x5edae0`, `0x5ea460` are in no vtable), so a pet gets zeros.
     #[test]
     fn ranged_attack_gives_a_pet_zeros_where_defense_gives_it_level_times_five() {
         let mut s = UiScript::new().unwrap();
@@ -1645,7 +1242,7 @@ mod tests {
             (0, 0),
             "no fork, no fallback body — a pet fails the PLAYER typemask and gets zeros"
         );
-        // …and so does another PLAYER, which is the same gate seen from the other side.
+        // Another player gets zeros too.
         assert_eq!(
             s.eval::<(i64, i64)>(r#"return UnitRangedAttack("target")"#)
                 .unwrap(),
@@ -1653,18 +1250,7 @@ mod tests {
         );
     }
 
-    /// **`UnitAttackBothHands` pushes FOUR values, one pair per hand — and it pushed two until
-    /// decision 1810.**
-    ///
-    /// The quietest shape decision 1793 describes: `0x518810` calls `[vtbl+0xb0]` twice, hand 0
-    /// then hand 1, and pushes `(base0, mod0, base1, mod1)` (VERIFIED, wow-re
-    /// `ui/scratch/pet-paperdoll-stat-api.md` §4). The reference's own
-    /// `PaperDollFrame_SetAttackBothHands` destructures only the first two — its very next line is
-    /// `-- FIXME: The offhand stats aren't displayed yet.` — so no amount of running the stock
-    /// character sheet could have exposed it. An addon reading four got two nils.
-    ///
-    /// The pet leg is here too because it is the same call: `CGUnit_C 0x6136b0` takes a hand index
-    /// and **never reads it**, so both hands answer the identical `level * 5`.
+    /// `0x518810` pushes `(base0, mod0, base1, mod1)`, one pair per hand.
     #[test]
     fn attack_both_hands_answers_a_pair_per_hand() {
         let mut s = UiScript::new().unwrap();
@@ -1679,8 +1265,7 @@ mod tests {
             (300, 5, 275, -12),
             "each hand's own skill line, in hand order"
         );
-        // …and the per-hand clamp the binding applies after each virtual call
-        // (`0x5188a7`: `if (out2 + out1 < 0) out2 = -out1`), which `UnitDefense` shares.
+        // The per-hand clamp (`0x5188a7`), which `UnitDefense` shares.
         s.set_player_combat_stats(Some(UnitCombatStats {
             main_weapon_skill: (40, -100),
             offhand_weapon_skill: (40, -40),
@@ -1701,18 +1286,13 @@ mod tests {
         );
     }
 
-    /// **The pet routing, end to end** (decision 1057) — the thing no build gate can catch: a
-    /// pushed pet snapshot really is what `Unit*("pet")` answers, while `"player"` still answers
-    /// the player's and a third token still answers the absent shape. The failure this guards is
-    /// silent: a mis-routed reader shows a pet sheet full of the *player's* numbers, or of zeros,
-    /// and nothing errors.
     #[test]
     fn the_pet_token_reads_the_pet_snapshot_and_only_it() {
         let mut s = UiScript::new().unwrap();
         s.set_player_combat_stats(Some(stats()));
         s.set_pet_combat_stats(Some(pet_stats()));
 
-        // Stamina (index 3): the pet's 68 with no buff split, the player's 22 with its own.
+        // Stamina: the pet's 68, the player's 22.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("pet", 3)"#)
                 .unwrap(),
@@ -1723,8 +1303,7 @@ mod tests {
                 .unwrap(),
             (22, 22, 0, 0)
         );
-        // Str, where the two genuinely differ AND the player carries a buff: the pet must not
-        // inherit either number.
+        // Str, where the player carries a buff the pet must not inherit.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("pet", 1)"#)
                 .unwrap(),
@@ -1735,7 +1314,7 @@ mod tests {
                 .unwrap(),
             (25, 25, 4, 0)
         );
-        // Resistances: fire (school 2) — 15 for the pet, 20 (+25/−5) for the player.
+        // Fire resistance: the pet's 15, the player's 20 (+25/−5).
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitResistance("pet", 2)"#)
                 .unwrap(),
@@ -1757,8 +1336,7 @@ mod tests {
                 .unwrap(),
             (130, 150, 150, 30, -10)
         );
-        // The rest of the family routes too — and `percent` stays the divide-safe 1.0 for the pet
-        // (the ref Lua divides the damage range by it).
+        // The rest routes too; the pet's `percent` stays 1.0.
         assert_eq!(
             s.eval::<(f64, f64, f64, f64, i64, i64, f64)>(r#"return UnitDamage("pet")"#)
                 .unwrap(),
@@ -1769,12 +1347,11 @@ mod tests {
                 .unwrap(),
             (178, 12, -4)
         );
-        // No offhand ⇒ the second return is nil, the same gate as the player's.
         assert!(s
             .eval::<bool>(r#"local m, o = UnitAttackSpeed("pet") return m == 2.0 and o == nil"#)
             .unwrap());
 
-        // A third token is still the absent shape…
+        // A third token is still the absent shape.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("target", 1)"#)
                 .unwrap(),
@@ -1785,7 +1362,7 @@ mod tests {
                 .unwrap(),
             (0, 0, 0, 0, 0)
         );
-        // …and so is `"pet"` once the pet is dismissed (the feed pushes None).
+        // So is `"pet"` once the pet is dismissed (the feed pushes `None`).
         s.set_pet_combat_stats(None);
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(r#"return UnitStat("pet", 1)"#)
@@ -1805,12 +1382,8 @@ mod tests {
         );
     }
 
-    /// `UnitDefense` always answers two numbers (the ref reads `local base, modifier`), and **the
-    /// two legs are different functions, not one function with missing data**: the player's is the
-    /// skill pair, a pet's is `level * 5` with a flat 0 modifier (the vtable fork,
-    /// `0x5eda20`/`0x613680`). `UnitAttackBothHands` takes the same fork and must agree with it —
-    /// that agreement is the point, since a mismatch is exactly what a snapshot-only
-    /// implementation would produce.
+    /// The vtable fork (`0x5eda20`, `0x613680`): the player's skill pair, a pet's level * 5 with a
+    /// 0 modifier; `UnitAttackBothHands` takes the same fork.
     #[test]
     fn unit_defense_forks_the_player_skill_from_a_pets_level_times_five() {
         let mut s = UiScript::new().unwrap();
@@ -1841,19 +1414,17 @@ mod tests {
             (300, 0, 300, 0),
             "the Attack row takes the same fork — and ignores its hand index, so both pairs match"
         );
-        // The pet's snapshot carries neither pair, which is the whole point: the numbers above
-        // cannot have come from it.
+        // The pet's snapshot carries neither pair; the numbers above come from its level.
         assert_eq!(pet_stats().defense_skill, (0, 0));
         assert_eq!(pet_stats().main_weapon_skill, (0, 0));
-        // A pet the level feed has not reached yet reads 0 rather than a stale or invented number.
+        // A pet with no level fed yet reads 0.
         s.set_unit("pet", None);
         assert_eq!(
             s.eval::<(i64, i64)>(r#"return UnitDefense("pet")"#)
                 .unwrap(),
             (0, 0)
         );
-        // A token that fails the client's SELF-or-SUMMONEDBY gate gets the failure zeros, not
-        // some other unit's level.
+        // A token failing the SELF-or-SUMMONEDBY gate gets zeros, not its level.
         s.set_unit(
             "target",
             Some(super::super::UnitState {
@@ -1867,8 +1438,7 @@ mod tests {
                 .unwrap(),
             (0, 0)
         );
-        // A negative modifier survives the round trip — the ref branches on `modifier < 0` to
-        // paint the number red.
+        // A negative modifier survives; stock paints it red.
         s.set_player_combat_stats(Some(UnitCombatStats {
             defense_skill: (300, -25),
             ..stats()
@@ -1891,20 +1461,8 @@ mod tests {
         assert!(s.eval::<bool>("return HasWandEquipped()").unwrap());
     }
 
-    /// **`GetInventoryItemCount`'s container fork** (`0x4c8680`, wow-re
-    /// `system/ui/scratch/inventory-item-count-law.md`). Four answers, and three of them are not
-    /// the stack count:
-    ///
-    /// · an equipped QUIVER (its `ItemSubClass.dbc` row has `DisplayFlags & 0x4`) answers the sum
-    ///   of its arrows — the number that shows on the bag bar;
-    /// · an equipped PLAIN BAG answers **0**, which is why the bar shows it no digit even though
-    ///   `BagSlotButtonTemplate` sets `isBag = 1` and `SetItemButtonCount` would print any
-    ///   positive number;
-    /// · the SAME plain bag in a BANK BAG slot answers 0 too, but for a different reason and
-    ///   earlier: `cmp …,0x16 / jg` short-circuits every container past the four equipped bag
-    ///   slots before the DBC is ever consulted. This is the digit the director saw on
-    ///   `BankFrameBag1` (decision 1771's sibling), and asserting it here rather than only through
-    ///   the window is the point — the window can only ever show that the two agree.
+    /// `0x4c8680`'s container fork: an equipped quiver counts its arrows, a plain bag 0, and any
+    /// container in a bank bag slot 0 before the DBC is read.
     #[test]
     fn get_inventory_item_count_forks_on_the_container_bit_and_the_slot() {
         let mut s = UiScript::new().unwrap();
@@ -1948,10 +1506,7 @@ mod tests {
             "0-based 63 is past 0x16: every container short-circuits, quiver or not"
         );
 
-        // The two `.data` literals, and the fact that both arms RAISE rather than answer. A slot
-        // outside the shared reader's whitelist is not an empty slot: the backpack's own item
-        // slots (Lua 24..=39) are addressed through the container API, and handing one here
-        // abandons the statement.
+        // Both arms raise. The backpack's item slots (Lua 24..=39) are outside the whitelist.
         let err = |code: &str| s.run(code).unwrap_err().to_string();
         assert!(
             err(r#"GetInventoryItemCount("player", 30)"#)
@@ -2035,9 +1590,7 @@ mod tests {
                 .unwrap(),
             200
         );
-        // An empty slot: nil id/texture/quality — and **count 1, not 0** (`0x4c8797`). Every
-        // secondary source says 0; the image pushes the literal 1, and both FrameXML callers gate
-        // on `GetInventoryItemTexture` first, which is why nobody ever caught it.
+        // An empty slot: nil id, texture and quality, and count 1 (`0x4c8797`).
         assert!(s
             .eval::<bool>(r#"return GetInventoryItemID("player", 5) == nil"#)
             .unwrap());
@@ -2052,7 +1605,7 @@ mod tests {
         assert!(s
             .eval::<bool>(r#"return GetInventoryItemQuality("player", 5) == nil"#)
             .unwrap());
-        // A non-player token: the empty shape (the INV_SLOT fields are PRIVATE — player only).
+        // A token with no items behind it: the empty shape.
         assert!(s
             .eval::<bool>(r#"return GetInventoryItemID("target", 1) == nil"#)
             .unwrap());
@@ -2096,9 +1649,7 @@ mod tests {
                 "interface\\paperdoll\\UI-PaperDoll-Slot-Ranged.blp".into()
             )
         );
-        // The bag rows: the four equipped-bag icons at 20..23 AND `Bag1`..`Bag12` at 64..75, which
-        // this table was short of until the DBC was re-read (36 records, not 24). All SIXTEEN share
-        // one string-block offset, which is why they answer the same art.
+        // The bag rows, 20..23 and 64..75, share one texture string.
         const BAG_ART: &str = "interface\\paperdoll\\UI-PaperDoll-Slot-Bag.blp";
         for (name, id) in [
             ("Bag0Slot", 20),
@@ -2129,20 +1680,13 @@ mod tests {
                 "interface\\paperdoll\\UI-PaperDoll-Slot-SecondaryHand.blp".into()
             )
         );
-        // An unknown slot name is a Lua error (the client's own behavior).
         assert!(s
             .eval::<i64>(r#"return GetInventorySlotInfo("NoSuchSlot")"#)
             .is_err());
     }
 
-    /// The character and pet paper dolls' facings are **the panes' own `SetRotation` state**, read
-    /// back by name — not the two benilla-named scalars they were until decision 1751.
-    ///
-    /// The two tabs are two `<PlayerModel>`s that can sit at different facings, which is the whole
-    /// reason this is per-pane at all: turning one must leave the other alone. It used to be
-    /// guaranteed by there being two fields on `Model`; now it is guaranteed by there being two
-    /// frames, which is also what the reference relies on (`Model_RotateLeft(model)` takes the
-    /// pane).
+    /// Each paper doll's facing is its pane's own `SetRotation` state, so turning one leaves the
+    /// other alone, as stock `Model_RotateLeft(model)` expects.
     #[test]
     fn each_model_pane_carries_its_own_facing_for_the_app_to_sample() {
         let s = UiScript::new().unwrap();
@@ -2158,10 +1702,10 @@ mod tests {
         "#,
         )
         .unwrap();
-        // The reference's own default, as `Model_OnLoad` writes it.
+        // Stock's default, as `Model_OnLoad` writes it (`UIParent.lua:1422`).
         s.run("CharacterModelFrame:SetRotation(0.61)").unwrap();
         assert_eq!(s.model_pane_facing("CharacterModelFrame"), 0.61);
-        // Persistent, not a drain — two reads see the same value.
+        // Persistent, not a drain.
         assert_eq!(s.model_pane_facing("CharacterModelFrame"), 0.61);
         assert_eq!(
             s.model_pane_facing("PetModelFrame"),
@@ -2180,11 +1724,9 @@ mod tests {
         s.run("CharacterModelFrame:SetRotation(-0.5)").unwrap();
         assert_eq!(s.model_pane_facing("CharacterModelFrame"), -0.5);
 
-        // A name nothing declares reads 0.0 rather than raising — the app samples this every
-        // frame, including before the window's file has loaded.
+        // An undeclared name reads 0.0: the app samples this before the window loads.
         assert_eq!(s.model_pane_facing("NoSuchModelFrame"), 0.0);
-        // …and so does a name that IS declared but is not a model pane, which is the shape a
-        // renamed window would take.
+        // A declared frame that is not a model pane has no pane.
         s.run(r#"CreateFrame("Frame", "NotAPane")"#).unwrap();
         assert!(s.model_pane("NotAPane").is_none());
     }
diff --git a/crates/benilla-ui/src/script/chat_misc.rs b/crates/benilla-ui/src/script/chat_misc.rs
index 5952d866..52b9e29b 100644
--- a/crates/benilla-ui/src/script/chat_misc.rs
+++ b/crates/benilla-ui/src/script/chat_misc.rs
@@ -1,27 +1,21 @@
-//! The chat slash handlers' engine verbs that are not sends, channels, or window state —
-//! `DoEmote`, `RandomRoll`, `AssistByName`, `UninviteByName`, `ConsoleExec`, `LoggingChat`,
-//! `LoggingCombat`. Each is what a stock `ChatFrame.lua` built-in handler calls once it has
-//! parsed the line (`SlashCmdList` walk, decision 1195); the app used to parse these lines
-//! itself (`ui_chat/input/parse.rs`) and now drains what the reference's own Lua decided.
-//!
-//! Every verb is a queue or a flag — the engine-free seam (0068 §3): the VM never sees the wire,
-//! the app drains and sends. Registrar addresses from wow-re `ui/scratch/bindings.md`:
-//! `0x49fd30 DoEmote`, `0x48c7b0 RandomRoll`, `0x489c40 AssistByName`, `0x48a610 UninviteByName`.
+//! The engine verbs stock `ChatFrame.lua`'s slash handlers call that are not sends, channels or
+//! window state: `DoEmote` (`0x49fd30`), `RandomRoll` (`0x48c7b0`), `AssistByName` (`0x489c40`),
+//! `UninviteByName` (`0x48a610`), `ConsoleExec`, `LoggingChat` and `LoggingCombat`. Each is a
+//! queue or a flag the app drains.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// `DoEmote(token [, target])` — the `EmotesText.dbc` **name token** (`"WAVE"`, not `/wave`) and
-/// the optional target name the handler split off the line.
+/// `DoEmote(token [, target])`: the `EmotesText.dbc` name token (`"WAVE"`, not `/wave`) and an
+/// optional target name.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct EmoteRequest {
     pub token: String,
     pub target: Option<String>,
 }
 
-/// Lua number coercion the way the reference's `lua_tonumber` does it: an integer, a float, or a
-/// string that parses; anything else is 0.
+/// The reference's `lua_tonumber` coercion: a number or a numeric string; anything else is 0.
 fn to_u32(v: &Value) -> u32 {
     match v {
         Value::Integer(i) => u32::try_from(*i).unwrap_or(0),
@@ -53,8 +47,7 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().emote_requests)
     }
 
-    /// `RandomRoll(min, max)` calls since the last drain, as the app sends them
-    /// (`CMSG_RANDOM_ROLL`).
+    /// `RandomRoll(min, max)` calls since the last drain, each a `CMSG_RANDOM_ROLL`.
     pub fn take_roll_requests(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().roll_requests)
     }
@@ -64,21 +57,18 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().uninvite_requests)
     }
 
-    /// `ConsoleExec` lines whose first word is not a registered CVar — the console commands the
-    /// app owns (`reloadui`, …). A CVar line is written to the store directly and never appears
-    /// here.
+    /// `ConsoleExec` lines that write no CVar: the app's console commands (`reloadui`, …).
     pub fn take_console_lines(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().console_lines)
     }
 
-    /// `(chat, combat)` — the two logging flags as `LoggingChat`/`LoggingCombat` last set them.
+    /// `(chat, combat)`, as `LoggingChat` and `LoggingCombat` last set them.
     pub fn logging_flags(&self) -> (bool, bool) {
         let model = self.model_mut();
         (model.logging_chat, model.logging_combat)
     }
 
-    /// Whether either logging flag moved since the last drain — the app's cue to open or close
-    /// its log files.
+    /// Whether a logging flag moved since the last drain: the app's cue to open or close its logs.
     pub fn take_logging_changes(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().logging_changed)
     }
@@ -138,12 +128,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConsoleExec("name value") — the console line `/console` hands over. A registered CVar
-    // WITH a value is written the way `SetCVar` writes it (same store, same change queue, no
-    // CVAR_UPDATE token), synchronously, so a script reading it back on the next line sees the
-    // write. Everything else — a command name, or a bare CVar name, which the reference's
-    // per-CVar console command answers with `CVar "%s" is "%s"` (`0x63dde0`) — is a line for
-    // the host's command registry (decision 2303).
+    // `ConsoleExec("name value")`: a registered CVar with a value is written at once, as `SetCVar`
+    // writes it; anything else, a bare CVar name included (the reference answers it with
+    // `CVar "%s" is "%s"`, `0x63dde0`), goes to the app's command registry.
     g.set(
         "ConsoleExec",
         lua.create_function(|lua, line: Option<String>| {
@@ -252,8 +239,7 @@ mod tests {
             "0.8",
             "the CVar store is the same one SetCVar writes, matched case-insensitively"
         );
-        // A bare CVar name is the host's to answer (2303: the reference prints its value from
-        // the per-CVar console command), so it rides the command lane like `reloadui`.
+        // A bare CVar name, whose value the reference prints, goes to the command lane.
         assert_eq!(
             s.take_console_lines(),
             vec!["reloadui".to_string(), "uiScale".to_string()]
diff --git a/crates/benilla-ui/src/script/chat_send.rs b/crates/benilla-ui/src/script/chat_send.rs
index 21d0fcd5..8942e15b 100644
--- a/crates/benilla-ui/src/script/chat_send.rs
+++ b/crates/benilla-ui/src/script/chat_send.rs
@@ -1,77 +1,47 @@
-//! **`SendChatMessage`** — the addon's own line into the chat wire (decision 1199).
+//! `SendChatMessage(text [, chatType [, language [, target]]])` (`0x49f1e0`): the engine verb an
+//! addon speaks through, with no FrameXML between it and the wire. `chatType` defaults to
+//! `"SAY"`; the fourth argument is the whisper target or the channel name or number.
 //!
-//! 24 corpus addons call it, and it is the one verb that makes an addon able to *say* anything:
-//! every "announce the pull", every raid warning helper, every whisper-the-invite bot is this one
-//! call. It is `function engine` in the captured `_G` — the engine takes the line and the wire
-//! sends it, with no FrameXML in between.
+//! It queues a [`ChatSend`] rather than going through the edit box, whose drain runs the slash
+//! grammar: an addon's `SendChatMessage("/dance")` says the characters. The reference splits the
+//! same way, `ChatEdit_SendText` parsing and `SendChatMessage` not.
 //!
-//! ```lua
-//! SendChatMessage(text [, chatType [, language [, channel/target]]])
-//! ```
+//! `language` is accepted and dropped, so every line goes in the speaker's default tongue: the
+//! app's chat command has no language field. The reference sends the named language.
 //!
-//! `chatType` defaults to `"SAY"`; `language` is accepted and **ignored** (§2); the fourth
-//! argument is the whisper target for `"WHISPER"` and the channel name or number for
-//! `"CHANNEL"`, and is unused otherwise.
-//!
-//! ## The seam
-//!
-//! Same shape as [`super::social`]'s: the verb queues a [`ChatSend`] and the app drains it
-//! ([`super::UiScript::take_chat_sends`]) into `ClientCommand::Chat`. It deliberately does **not**
-//! go through the chat edit box's own drain: that path runs the slash grammar, and an addon's
-//! `SendChatMessage("/dance", "SAY")` must *say the four characters*, not dance. The reference has
-//! the same split — `ChatEdit_SendText` parses, `SendChatMessage` does not.
-//!
-//! ## What is not carried, and why
-//!
-//! **`language`.** The reference resolves a language id to the garble table the receiver's client
-//! reverses. benilla sends every line in the speaker's own tongue because the app's chat command
-//! carries no language field yet, and inventing one here would put the id in a queue nothing
-//! reads. Accepted and dropped, said out loud rather than silently — an addon passing it is not
-//! wrong, we are incomplete.
-//!
-//! **No rate limit and no length cap.** The reference truncates at 255 and the *server* throttles.
-//! Ours passes the line through; vmangos enforces both, so a misbehaving addon meets the same wall
-//! it would meet on a real server rather than a client-side one we made up.
+//! Deviation: no truncation at 255 characters (`0x49f604`), because vmangos refuses a longer line
+//! itself (`Chat.cpp:2177`): it is dropped where the reference sends its first 255. The server
+//! throttles in both.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
 impl super::UiScript {
-    /// Push the player's **default chat language** — the name `GetDefaultLanguage()` answers.
-    /// `None` (the default) is the reference's own no-player-object state, which returns **zero
-    /// Lua values**, not `nil`. The app resolves it once per world entry from
-    /// `ChrRaces.BaseLanguage` × `Languages.dbc` (`benilla_formats::DefaultLanguages`).
+    /// Push the name `GetDefaultLanguage()` answers. `None` is the reference's no-player state,
+    /// which returns zero values, not `nil`; the app resolves it per world entry from
+    /// `ChrRaces.BaseLanguage` and `Languages.dbc`.
     pub fn set_default_language(&mut self, name: Option<String>) {
         self.model_mut().default_language = name;
     }
 }
 
-/// One queued outbound chat line (`SendChatMessage`), drained by the app into the wire.
-///
-/// Plain data — [`super::social::SocialRequest`]'s twin, and deliberately *not* the app's own
-/// `ClientCommand::Chat`: this crate has no wire types and must not grow one.
+/// One queued `SendChatMessage` line, plain data: this crate holds no wire types.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ChatSend {
-    /// The line, verbatim. Never parsed here — a leading `/` is four characters, not a command.
+    /// The line, verbatim: a leading `/` is text, not a command.
     pub text: String,
-    /// The chat type token, uppercased (`"SAY"`, `"YELL"`, `"PARTY"`, `"GUILD"`, `"WHISPER"`,
-    /// `"CHANNEL"`, `"EMOTE"`, …). Uppercased because the reference's own token compare is, and
-    /// addons write `"say"` as often as `"SAY"`.
+    /// The chat type token (`"SAY"`, `"WHISPER"`, `"CHANNEL"`, …), uppercased, since the
+    /// reference's compare ignores case.
     pub chat_type: String,
-    /// The whisper target (`"WHISPER"`) or the channel name/number (`"CHANNEL"`); `None`
-    /// otherwise. Kept as a string for the channel case, where an addon passes either `"General"`
-    /// or `1` and the app resolves both.
+    /// The whisper target or the channel name or number, as text; the app resolves either.
     pub target: Option<String>,
 }
 
 impl super::UiScript {
-    /// The languages this character **knows**, in `Languages.dbc` row order — what
-    /// `GetNumLaguages`/`GetLanguageByIndex` walk. The app folds it the reference's way:
-    /// `0x4b25b0` stores `[languageId] = spellId` for every known spell whose `Effect_1 == 39`,
-    /// and `0x5ec720` answers non-zero only when that spell's skill line is in the player's
-    /// skill block (wow-re `chat-language-scramble.md` §8, C6). Fires `LANGUAGE_LIST_CHANGED`
-    /// (`0x49b970`, event 0x102) when the list moves.
+    /// The languages this character knows, in `Languages.dbc` row order: a language counts when a
+    /// known spell with `Effect_1 == 39` teaches it (`0x4b25b0`) and its skill line is in the skill
+    /// block (`0x5ec720`). A change fires `LANGUAGE_LIST_CHANGED` (`0x49b970`, event 0x102).
     pub fn set_known_languages(&mut self, names: Vec<String>) {
         let changed = {
             let mut model = self.model_mut();
@@ -89,9 +59,8 @@ impl super::UiScript {
 }
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // GetNumLaguages() — `0x49fb30`, the binary's own spelling (wow-re
-    // `bag-language-combat-action-bindings.md` §2). Walks `Languages.dbc` and counts the rows
-    // `0x5ec720` answers non-zero for; **one number**.
+    // GetNumLaguages(), `0x49fb30`: one number, the known languages. The misspelling is the
+    // reference's registered name (`0x843628`); the correct spelling is nowhere in the binary.
     lua.globals().set(
         "GetNumLaguages",
         lua.create_function(|lua, _ignored: MultiValue| {
@@ -99,8 +68,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(model.known_languages.len() as i64)
         })?,
     )?;
-    // GetLanguageByIndex(i) — `0x49fbe0`: the same walk, pushing **one string** — the
-    // `Name_lang` of the i-th (1-based) *known* language. Positional among the known rows,
+    // GetLanguageByIndex(i), `0x49fbe0`: the `Name_lang` of the i-th known language, positional,
     // never a row number or a language id; past the end it pushes nothing.
     lua.globals().set(
         "GetLanguageByIndex",
@@ -116,33 +84,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // GetDefaultLanguage() → **exactly ONE value, a string** — or **zero values**, which is not
-    // the same thing (`0x49fcd0`, wow-re `bag-language-combat-action-bindings.md` §2).
-    //
-    // The binding takes **no arguments** (no arg-presence check and no arg-fetch call anywhere in
-    // its 94 bytes — contrast its sibling `GetLanguageByIndex 0x49fbe0`, which opens with
-    // `0x6f34d0`), so the corpus's `GetDefaultLanguage("player")` — `Auctioneer/AucAskPrice.lua:42`
-    // and `Enchantrix/EnchantrixBarker.lua:149` both write it — is harmlessly ignored, here as
-    // there.
-    //
-    // There is exactly one push in the body and it is `0x6f3890` (push-STRING): the numeric
-    // language id is consumed as a table index and never reaches Lua, so this is not `(name, id)`
-    // and not an id. All **four** failure edges — no player object, a negative id, an id past the
-    // language count, a null record — converge on `0x49fd2a xor eax,eax; ret`, i.e. **zero Lua
-    // values**. That is shape 2 of the argument ABI ([`super::binding_abi`]) and it is the one
-    // place in this repo where the distinction is observable: the call's return-list COUNT is `0`
-    // outside the world and `1` inside it, while a single-value caller reads `nil` either way.
-    // Returning `nil` here would be a quiet divergence, so we do not.
-    //
-    // **Its sibling is misspelled in the binary, and is deliberately NOT registered here.** The
-    // `.data` `{const char* name, void* fn}` record at `0x843628` names `0x49fb30`
-    // **`GetNumLaguages`** — and a whole-image byte search for the correct spelling returns **zero
-    // hits** (with `GetNumLaguages` and `GetDefaultLanguage` as satisfied positive controls), so
-    // the typo is the only Lua-visible name and a faithful client would ship it. What is missing
-    // is not the name but the *answer*: `0x49fb30`'s body was not carved beyond "returns through
-    // the push-number helper", no corpus addon calls it at all, and registering it would mean
-    // inventing a count. The name is recorded here so that whoever carves the body knows how to
-    // spell the global.
+    // GetDefaultLanguage(), `0x49fcd0`: one string (`0x6f3890`), or zero values, never `nil`, on
+    // all four failure edges (`0x49fd2a`). It reads no arguments, so an addon's
+    // `GetDefaultLanguage("player")` is ignored.
     lua.globals().set(
         "GetDefaultLanguage",
         lua.create_function(|lua, _ignored: MultiValue| {
@@ -161,13 +105,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "SendChatMessage",
         lua.create_function(
             |lua, (text, chat_type, _language, target): (String, Option<String>, Value, Value)| {
-                // The reference's default is SAY — an addon that passes only a string is saying it.
                 let chat_type = chat_type
                     .unwrap_or_else(|| "SAY".into())
                     .to_ascii_uppercase();
-                // The fourth argument is a name for WHISPER and a name-or-number for CHANNEL, so
-                // it arrives as either a string or a number and is normalised to text here rather
-                // than at every consumer.
+                // A channel arrives as a name or a number; both become text.
                 let target = match target {
                     Value::String(s) => Some(s.to_string_lossy()),
                     Value::Integer(n) => Some(n.to_string()),
@@ -201,11 +142,6 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// The default is SAY, the type is uppercased, and **a leading slash is text**.
-    ///
-    /// That last one is the whole reason this verb has its own queue rather than reusing the chat
-    /// box's: the box's drain runs the slash grammar, and an addon announcing "/dance" wants the
-    /// six characters said, not the emote played. The reference splits the same way.
     #[test]
     fn send_chat_message_queues_a_line_without_parsing_it() {
         let mut s = UiScript::new().unwrap();
@@ -226,12 +162,9 @@ mod tests {
                 },
             ]
         );
-        // Drained, not re-read.
         assert!(s.take_chat_sends().is_empty());
     }
 
-    /// The fourth argument is a whisper target or a channel, and a channel arrives as either a
-    /// name or a number — both normalise to text so one consumer handles both.
     #[test]
     fn the_target_argument_takes_a_name_or_a_channel_number() {
         let mut s = UiScript::new().unwrap();
@@ -248,8 +181,6 @@ mod tests {
         assert_eq!(sent[1].chat_type, "CHANNEL");
     }
 
-    /// `language` is accepted and dropped — an addon passing it must not error, and the module
-    /// doc says why nothing reads it.
     #[test]
     fn the_language_argument_is_accepted_and_ignored() {
         let mut s = UiScript::new().unwrap();
@@ -258,11 +189,7 @@ mod tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// **One string, or ZERO values — never `nil`.** The four failure edges reach
-    /// `0x49fd2a xor eax,eax; ret` *without* passing through `luaL_error`, which is the only place
-    /// the "returns nothing" shape is real. A single-value caller cannot tell the two apart; the
-    /// return-list count can ([`UiScript::arity`]), and both corpus callers feed the result straight to
-    /// `SendChatMessage`, where the difference is an argument that exists versus one that does not.
+    /// The count matters: an addon passes the result straight to `SendChatMessage` as `language`.
     #[test]
     fn get_default_language_is_one_string_or_zero_values() {
         let mut s = UiScript::new().unwrap();
@@ -282,7 +209,7 @@ mod tests {
             s.eval::<String>("return GetDefaultLanguage()").unwrap(),
             "Common"
         );
-        // The binding reads NO arguments; the corpus passes `"player"` anyway and must not error.
+        // The binding reads no arguments; addons pass `"player"` anyway.
         assert_eq!(
             s.eval::<String>(r#"return GetDefaultLanguage("player")"#)
                 .unwrap(),
diff --git a/crates/benilla-ui/src/script/chat_types.rs b/crates/benilla-ui/src/script/chat_types.rs
index 50e1abd2..2f0d0e6c 100644
--- a/crates/benilla-ui/src/script/chat_types.rs
+++ b/crates/benilla-ui/src/script/chat_types.rs
@@ -1,30 +1,6 @@
-//! The chat-type colour registry — `GetChatTypeIndex`, `ChangeChatColor`, `ResetChatColors`.
-//!
-//! The reference keeps one runtime table of chat types (`0xb4e518`, stride 0x43: a 0x40-byte
-//! name and three RGB bytes), seeded at boot from the 94-entry static table at `0x804710` and
-//! then extended with ten extras `CHANNEL1`…`CHANNEL10`, each coloured from the live `CHANNEL`
-//! entry (wow-re `system/ui/scratch/chat-color-table.md`, "Seeding"). The `chat-cache.txt`
-//! `COLORS` block overwrites matched entries in place at load — absent names keep the compiled
-//! defaults — and the app owns that file; here the table is state the app feeds and drains
-//! ([`super::UiScript::set_chat_colors`], [`super::UiScript::take_chat_color_changes`]).
-//!
-//! The Lua surface, from the same node:
-//!
-//! - `GetChatTypeIndex(name)` — a case-insensitive linear scan of the 94 fixed entries, **1-based**
-//!   (`4a0adf: inc ebx` before the match test); no fixed match → the extras, numbered **95, 96, …**
-//!   (`count_before_match + 0x5f`); no match at all → **0**.
-//! - `ChangeChatColor(name, r, g, b)` — `r,g,b` are 0.0–1.0 floats, each `fmul 255.0` then
-//!   `__ftol` (**truncate**, no rounding, bytes `4a085f–4a08a3`), written into the matched entry.
-//!   On success fires `UPDATE_CHAT_COLOR` with `"%s%f%f%f"`: the name and the three
-//!   **just-written bytes re-normalised** by `f32 1/255` — so an addon that passed `0.5` hears
-//!   `127/255`, not `0.5`. (The event's symbolic name is the node's one INFERRED item — it is
-//!   `0xe2` in a runtime-populated listener table; `ChatFrame.lua:1349` registers and reads it
-//!   as `UPDATE_CHAT_COLOR` with exactly those four args.)
-//! - `ResetChatColors()` — the boot seed again: the 94 defaults copied back, then every extra
-//!   recoloured from the live `CHANNEL` entry.
-//!
-//! What the line colours *mean* to a message frame is `ScrollingMessageFrame:UpdateColorByID`,
-//! which lives with the frame (`messageframe/scrolling.rs`); this file is only the registry.
+//! The chat-type colour registry behind `GetChatTypeIndex`, `ChangeChatColor` and
+//! `ResetChatColors`: the reference's runtime table (`0xb4e518`), which the `COLORS` block of
+//! `chat-cache.txt` overwrites in place at load; the app owns that file.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -32,11 +8,11 @@ use super::Model;
 
 /// The fixed segment: 94 entries, in the reference's order (index = position + 1).
 pub const FIXED_CHAT_TYPES: usize = 94;
-/// The extras seeded at boot: `CHANNEL1`…`CHANNEL10`, indices 95–104.
+/// The extras seeded at boot: `CHANNEL1` to `CHANNEL10`, indices 95 to 104.
 pub const EXTRA_CHAT_TYPES: usize = 10;
 
-/// `0x804710` — name and default RGB, verbatim (chat-color-table.md, "The complete default
-/// table"). The order is load-bearing: it *is* the index `GetChatTypeIndex` answers.
+/// The reference's table at `0x804710`, verbatim; its order is the index `GetChatTypeIndex`
+/// answers.
 const DEFAULTS: [(&str, [u8; 3]); FIXED_CHAT_TYPES] = [
     ("SAY", [255, 255, 255]),
     ("PARTY", [170, 170, 255]),
@@ -134,7 +110,7 @@ const DEFAULTS: [(&str, [u8; 3]); FIXED_CHAT_TYPES] = [
     ("BATTLEGROUND_LEADER", [255, 219, 183]),
 ];
 
-/// The 1-based index of the `CHANNEL` entry — the extras' colour source at seed and reset.
+/// The 1-based index of `CHANNEL`, the extras' colour source at seed and reset.
 const CHANNEL_INDEX: usize = 15;
 
 /// One registry entry: the type's name and its live colour bytes.
@@ -144,7 +120,7 @@ pub struct ChatTypeColor {
     pub rgb: [u8; 3],
 }
 
-/// The boot seed: the 94 defaults, then `CHANNEL1`…`CHANNEL10` coloured from the live `CHANNEL`.
+/// The boot seed: the defaults, then the extras coloured from `CHANNEL` (`0x4982c0`).
 pub(super) fn seed() -> Vec<ChatTypeColor> {
     let mut table: Vec<ChatTypeColor> = DEFAULTS
         .iter()
@@ -163,7 +139,7 @@ pub(super) fn seed() -> Vec<ChatTypeColor> {
     table
 }
 
-/// `ResetChatColors`' copy loop: the fixed segment back to `0x804710`, the extras from `CHANNEL`.
+/// `ResetChatColors`: the defaults back first, then the extras from the restored `CHANNEL`.
 fn reset(table: &mut [ChatTypeColor]) {
     for (entry, (_, rgb)) in table.iter_mut().zip(DEFAULTS.iter()) {
         entry.rgb = *rgb;
@@ -174,13 +150,13 @@ fn reset(table: &mut [ChatTypeColor]) {
     }
 }
 
-/// The reference's compare (`0x64a4c0` → `0x414310`): an `'A'–'Z' + 0x20` fold, i.e. ASCII
-/// case-insensitive and nothing wider.
+/// ASCII case-insensitive and nothing wider: the reference's compare folds only `A` to `Z`
+/// (`0x64a4c0`, `0x414310`).
 fn position(table: &[ChatTypeColor], name: &str) -> Option<usize> {
     table.iter().position(|e| e.name.eq_ignore_ascii_case(name))
 }
 
-/// `fmul 255.0; __ftol` — truncation toward zero, then the low byte is what the `mov` stores.
+/// Truncates, never rounds: the reference's `fmul 255.0; __ftol` (`0x4a085f`-`0x4a08a3`).
 fn to_byte(x: f64) -> u8 {
     if !x.is_finite() {
         return 0;
@@ -188,15 +164,15 @@ fn to_byte(x: f64) -> u8 {
     ((x * 255.0).trunc() as i64) as u8
 }
 
-/// `fmul dword [0x8026c8]` — the f32 reciprocal, so the event carries `byte / 255` in single
-/// precision, widened.
+/// `UPDATE_CHAT_COLOR`'s value: the stored byte times the f32 reciprocal of 255 (`0x8026c8`), so
+/// an addon that passed `0.5` hears `127/255`.
 fn from_byte(b: u8) -> f64 {
     f64::from(b as f32 * (1.0f32 / 255.0f32))
 }
 
 impl super::UiScript {
-    /// The `COLORS` block of `chat-cache.txt`, applied the way the loader applies it: each named
-    /// entry overwritten in place, unknown names ignored, absent names left at their defaults.
+    /// Apply the `COLORS` block of `chat-cache.txt` as the loader does: matched entries
+    /// overwritten in place, unknown names ignored.
     pub fn set_chat_colors(&mut self, colors: impl IntoIterator<Item = (String, [u8; 3])>) {
         let mut model = self.model_mut();
         for (name, rgb) in colors {
@@ -211,8 +187,7 @@ impl super::UiScript {
         self.model_mut().chat_colors.clone()
     }
 
-    /// Whether a Lua-side write (`ChangeChatColor`, `ResetChatColors`) has landed since the last
-    /// drain — the app's persist cue.
+    /// Whether Lua changed a colour since the last drain, the app's cue to persist.
     pub fn take_chat_color_changes(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().chat_colors_changed)
     }
@@ -371,8 +346,7 @@ mod tests {
         let s = UiScript::new().unwrap();
         s.run("ChangeChatColor('CHANNEL', 0.0, 0.0, 0.0) ChangeChatColor('CHANNEL2', 1, 1, 1)")
             .unwrap();
-        // Reset copies the fixed defaults first, so CHANNEL is back to FFC0C0 by the time the
-        // extras are recoloured from it.
+        // The defaults come back first, so the extras take `CHANNEL`'s default, not the black.
         s.run("ResetChatColors()").unwrap();
         assert_eq!(s.chat_colors()[FIXED_CHAT_TYPES + 1].rgb, [255, 192, 192]);
     }
diff --git a/crates/benilla-ui/src/script/chat_window.rs b/crates/benilla-ui/src/script/chat_window.rs
index ef90f265..6a19f5eb 100644
--- a/crates/benilla-ui/src/script/chat_window.rs
+++ b/crates/benilla-ui/src/script/chat_window.rs
@@ -1,152 +1,39 @@
-//! The chat **window** surface: `GetChatWindowInfo` (the engine's per-window settings getter) and
-//! `ChatFrame_OpenChat` (the FrameXML verb that opens the edit box prefilled).
+//! The chat window settings bindings: `GetChatWindowInfo`, its setters and `ChatFrame_OpenChat`.
 //!
-//! The windows themselves are frames, declared in the app's shipped `ChatFrame.xml` —
-//! `ChatFrame1`..`ChatFrame7`, of which 1 and 2 are docked and 3..7 ship hidden and undocked, the
-//! reference's own arrangement. This module is the *settings* half: what an addon learns when it
-//! asks about window `i` without touching the frame.
+//! The reference keeps one record per window (`0xb4fe50`, stride 0x98, 10 slots), loaded from and
+//! saved to `chat-cache.txt`: name `+0x00`, message-group flags `+0x20`, channel names and ids
+//! `+0x64`/`+0x74`, font size `i32` `+0x84`, the colour one packed `CImVector` in BGRA order
+//! (`+0x88` B, `+0x89` G, `+0x8a` R, `+0x8b` A), locked `+0x8c`, docked `+0x90`, shown `+0x94`.
+//! `GetChatWindowInfo(id)` (`0x4a0ba0`) answers `name, fontSize, r, g, b, a, shown, locked,
+//! docked`, each colour byte times the f32 1/255 at `0x8026c8`.
 //!
-//! ## `GetChatWindowInfo(id)` → `name, fontSize, r, g, b, a, shown, locked, docked`
+//! Three traps in that tuple. `name` is `""` until a window is named, and FrameXML's
+//! `FCF_SetWindowName` (FloatingChatFrame.lua:681) substitutes "General" and "Combat Log".
+//! `shown`, `locked` and `docked` are a number or nil, never 0, because FrameXML tests them bare
+//! (FloatingChatFrame.lua:59, 69). `docked` is a dock position, the index `FCF_DockFrame` takes.
 //!
-//! A registered Lua binding in the real client (`0x4a0ba0`, wow-re `system/ui/ledger.tsv`), reading
-//! the per-window struct array at `0xb4fe50` — stride 0x98, **10 windows**, colour bytes at
-//! +0xd8..+0xdb renormalised by the f32 1/255 (`system/ui/scratch/chat-color-table.md`). Those
-//! structs are loaded from the character's `chat-cache.txt`, and a real stock one is on disk
-//! (`wow-5875-re/WoW/WTF/Account/ONE/VMaNGOS/Onepaladin/chat-cache.txt`) — every value below is
-//! quoted from it:
-//!
-//! ```text
-//! WINDOW 1   SIZE 0  COLOR 0 0 0 0  LOCKED 1  DOCKED 1  SHOWN 1
-//! WINDOW 2   SIZE 0  COLOR 0 0 0 0  LOCKED 1  DOCKED 2  SHOWN 0
-//! WINDOW 3…10 SIZE 0 COLOR 0 0 0 0  LOCKED 1  DOCKED 0  SHOWN 0
-//! ```
-//!
-//! **Three traps live in that tuple, and all three are load-bearing:**
-//!
-//! 1. **`name` is the empty string, not "General".** Nothing writes a window name until the user
-//!    renames a tab, so a stock client answers `""` for every window including the first two. The
-//!    familiar labels are a *FrameXML fallback*, not data: `FCF_SetWindowName` (FloatingChatFrame.lua
-//!    l.680-684) reads `if ( not name or name == "" )` and substitutes `GENERAL` / `COMBAT_LOG` /
-//!    `format(CHAT_NAME_TEMPLATE, id)`. Our own tab labels are that fallback, hardcoded. An addon
-//!    proves the contract from the other side: `Enchantrix/EnxConfig.lua:113` does
-//!    `local name = GetChatWindowInfo(i); if ( name == "" ) then if (i == 1) then name =
-//!    _ENCH('TextGeneral') …` — it would not have been written if the getter answered "General".
-//!    Answering "General" here would look friendlier and would be a divergence.
-//! 2. **`shown`/`locked`/`docked` are numbers or `nil` — never `0`.** FrameXML branches on them
-//!    bare (`if ( shown ) then chatFrame:Show()`, `if ( docked ) then FCF_DockFrame(…)` —
-//!    FloatingChatFrame.lua l.59/69), and `0` is TRUE in Lua. A getter that returned the cache's
-//!    literal `0` would show every hidden window.
-//! 3. **`docked` is a dock POSITION, not a flag.** Window 1 answers `1`, window 2 answers `2` —
-//!    the order tabs sit in the dock, which is why `FCF_DockFrame(frame, docked)` takes it as an
-//!    index. Reading it as a boolean happens to work; reading it as "is docked" and writing back
-//!    `1` would silently reorder the dock.
-//!
-//! `fontSize` is the cache's `SIZE`, and `0` is what a stock client stores — "use the font's own
-//! height". No FrameXML path applies it (`FloatingChatFrame_Update` destructures it and never
-//! reads it; the options dropdown checks `FCF_GetCurrentChatFrame():GetFont()` instead), and no
-//! corpus addon reads it.
-//!
-//! ## The three setters, and why this getter stopped being a constant (decision 1589)
-//!
-//! Until 1589 the whole tuple above was a frozen table: benilla had no way to *change* a window's
-//! look, so answering with the stock cache row was the honest answer. B246 ("no chat options at
-//! all — background transparency has no home") is the report that ends that, and the reference's
-//! own home for it is the chat tab's right-click menu → **Background**, a colour swatch with an
-//! opacity slider. So three of the nine values are now real state, written by the reference's own
-//! three setters and read straight back out of this getter:
-//!
-//! | binding | address | what it stores |
-//! |---|---|---|
-//! | `SetChatWindowColor(id, r, g, b)` | `0x4a14f0` | `__ftol(x · 255.0)` per channel |
-//! | `SetChatWindowAlpha(id, a)` | `0x4a15d0` | `__ftol(a · 255.0)` |
-//! | `SetChatWindowSize(id, size)` | `0x4a1470` | the cache's `SIZE` |
-//! | `SetChatWindowLocked(id, isLocked)` | `0x4a1650` | the cache's `LOCKED` |
-//!
-//! (wow-re `system/ui/ledger.tsv:9449-9451` + `scratch/item17-frameapi-fullcarve.md` l.17-18,
-//! VERIFIED; `[0x806498]` is the 255.0 the first two multiply by.) **Bytes, not floats** — that is
-//! why the getter renormalises by 1/255, and why [`ChatWindowLook`] stores the colour as `u8`: a
-//! set→get round trip through the real client quantises, and a store of `f32` here would
-//! round-trip values the reference cannot hold. `SetChatWindowAlpha(1, 0.4)` answers
-//! `102/255 = 0.4`, not `0.4`.
-//!
-//! **The record's own layout**, from the §5 dispatched for this work
-//! (`system/ui/scratch/chat-window-record.md`): the colour is ONE packed `CImVector` at
-//! **`+0x88` B, `+0x89` G, `+0x8a` R, `+0x8b` A** — note the **BGRA** order — and the font size is
-//! an `i32` at **`+0x84`**, not a byte and with no `× 255` anywhere near it. (Both correct this
-//! module's earlier `+0xd8..+0xdb`, which was the low half of the *absolute* operand
-//! `[esi + 0xb4fed8]`: `0xb4fed8 − 0xb4fe50 = 0x88`.) `chat-cache.txt`'s `COLOR` line is written
-//! **R G B A** from `+0x8a,+0x89,+0x88,+0x8b` and parsed straight back as bytes, so the file
-//! round-trip is bit-exact and the `×255` / `×1/255` pair exists only at the Lua boundary.
-//!
-//! Two behaviours of the reference's setters that are easy to miss and are transcribed here:
-//!
-//! - **`SetChatWindowSize` silently drops a size `<= 0`** (`0x4a14bc jle`). A stock cache holds
-//!   `SIZE 0`, so "no size stored" and "cannot store 0" coexist: the field is only ever written by
-//!   a real pick off the Font Size menu.
-//! - **Nothing clamps.** `__ftol` (`0x40a2b0`) truncates, and the setters store the low byte of
-//!   the result with no bound: on a real client `SetChatWindowAlpha(1, 2.0)` stores **254**,
-//!   `(1, -1.0)` stores **1**, and `0.5` stores **127**, not 128.
-//!
-//! **We clamp where it wraps, and that is the one deliberate divergence.** Nothing in FrameXML or
-//! the corpus can reach the out-of-domain case (the colour picker's channels and its opacity
-//! slider are all `0..1`), and the camera pose file already set this posture: a value nothing can
-//! produce is not a thing to be faithful to. The truncation itself IS kept — `0.5` stores 127 here
-//! too.
-//!
-//! **`locked` joined them the day the windows could move.** `SetChatWindowLocked(id, isLocked)` is
-//! the fourth setter here now: the chat tab's *Lock/Unlock Window* row is what turns the resize
-//! grips and the tab drag on, so a value that used to be a constant has a player-reachable writer
-//! and belongs in the record with the rest. The other five stay constants, and that is the honest
-//! tree rather than an omission: benilla has no rename, no undock and no window create/close, so
-//! `name`, `shown` and `docked` still have nothing that could move them (0288 §2).
-//!
-//! Measured demand: **3 of the 5 corpus addons that iterate `NUM_CHAT_WINDOWS` call this on the
-//! very next line** — `EnhTooltip/Tooltip.lua:1302`, `MikScrollingBattleText.lua:1951` and
-//! `Enchantrix/EnxConfig.lua:110`. The first two are the same idiom (look for a window the user
-//! named "debug"/"ettdebug"); the third builds a name→index map for its `/enx print-in` config.
-//! Without this getter, declaring `NUM_CHAT_WINDOWS` hands those three a loop that raises on its
-//! first iteration, so the constant and the getter are one change, not two.
-//!
-//! ## `ChatFrame_OpenChat(text, chatFrame)`
-//!
-//! FrameXML in the reference (ChatFrame.lua l.1545), and the same seam as its neighbour
-//! `ChatFrame_SendTell` ([`super::party`]): benilla's chat edit machine is app-side
-//! (`benilla_app::ui_chat::edit`), so the verb queues the request and the app opens the box.
+//! `SetChatWindowColor` (`0x4a14f0`) and `SetChatWindowAlpha` (`0x4a15d0`) store
+//! `__ftol(x · 255.0)` (`[0x806498]` is the 255.0; `__ftol` `0x40a2b0` truncates), so a round trip
+//! quantises: alpha 0.4 reads back 102/255, 0.5 reads 127/255. Deviation: a value outside 0..1
+//! clamps, where the reference keeps the low byte (alpha 2.0 stores 254, -1.0 stores 1), because no
+//! FrameXML or addon caller passes one.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::channel::ZoneChannelRow;
 use super::Model;
 
-/// How many chat windows the client's own settings array holds — **10**, both in the engine
-/// (`0xb4fe50`, stride 0x98) and in `chat-cache.txt`, which writes `WINDOW 1` … `WINDOW 10`.
-/// FrameXML declares `ChatFrame1TabDockRegion`..`ChatFrame10TabDockRegion` to match, and then
-/// builds only seven `ChatFrame`s: `NUM_CHAT_WINDOWS = 7` is the *UI's* count, not the engine's.
-/// Recorded so the 7 below reads as a deliberate choice rather than a miscount.
+/// The reference's record slots (`0xb4fe50`); FrameXML builds only [`NUM_CHAT_WINDOWS`] frames.
 pub(super) const ENGINE_CHAT_WINDOW_SLOTS: usize = 10;
 
-/// The windows benilla actually builds — `ChatFrame1`..`ChatFrame7` in the app's `ChatFrame.xml`,
-/// which is also `NUM_CHAT_WINDOWS`. `benilla_app`'s `chat_tests` cross-checks every entry against
-/// the shipped XML so the two cannot drift.
+/// `NUM_CHAT_WINDOWS = 7` (ChatFrame.lua:5), the frames `ChatFrame1`..`ChatFrame7`.
 pub(super) const NUM_CHAT_WINDOWS: usize = 7;
 
-/// One chat window's **look** — the mutable slice of the engine's per-window record (decision
-/// 1589): the background tint, the background alpha, and the font size. The colour is bytes
-/// because the engine's colour is bytes (`0xb4fe50 + n*0x98 + 0x88..0x8b`, packed BGRA,
-/// `__ftol(x · 255.0)` in and `× 1/255` out); the font size is an `i32` because the engine's is
-/// (`+0x84`). See this module's docs for why that quantisation is kept rather than smoothed over.
-///
-/// [`Self::default`] is the stock `chat-cache.txt` row — `COLOR 0 0 0 0`, `SIZE 0`, `LOCKED 1` —
-/// i.e. a black box at alpha 0 that cannot be dragged, which is the classic "chat is text over the
-/// world until you mouse over it".
-/// `CHATMSGGROUP` — the client's 68-entry message-group table at `0x805fb0` (wow-re
-/// `system/ui/scratch/chat-cache-grammar.md` §2): `(name, defaultOn, addedVersion)`, stride 0xc,
-/// in the order that IS the record's `+0x20` flag index. **Not** the 94-entry colour table: 67
-/// names are shared, `CREATURE` exists only here, and 27 colour names (RAID, OFFICER,
-/// WHISPER_INFORM, EMOTE, TEXT_EMOTE, MONSTER_*, CHANNEL_JOIN/LEAVE/LIST/NOTICE[_USER], AFK, DND,
-/// IGNORED, BG_SYSTEM_*, RAID_LEADER/WARNING/BOSS_EMOTE, FOREIGN_TELL, FILTERED, BATTLEGROUND[_LEADER])
-/// have no group. `defaultOn` is what the boot init copies into window 2's flags (§4);
-/// `addedVersion` is the loader's back-fill for a file older than `ADDEDVERSION 2` (§3).
+/// `CHATMSGGROUP`, the client's 68-entry message-group table (`0x805fb0`, stride 0xc):
+/// `(name, defaultOn, addedVersion)` in the order of the record's `+0x20` flags. Not the 94-entry
+/// colour table: `CREATURE` is only here, and 27 colour types have no group. The boot init
+/// (`0x4982c0`) enables the `defaultOn` groups in window 2; the loader (`0x498a60`) back-fills by
+/// `addedVersion` for a file older than `ADDEDVERSION 2`.
 pub const MESSAGE_GROUPS: [(&str, bool, u8); 68] = [
     ("SYSTEM", true, 0),
     ("SAY", true, 0),
@@ -218,55 +105,35 @@ pub const MESSAGE_GROUPS: [(&str, bool, u8); 68] = [
     ("MONEY", true, 2),
 ];
 
-/// The flag index of a group name, matched the loader's way (`SStrCmpI` — an ASCII case-fold).
+/// The flag index of a group name, case-folded as the loader's `SStrCmpI` matches it.
 pub fn message_group_index(name: &str) -> Option<usize> {
     MESSAGE_GROUPS
         .iter()
         .position(|(n, _, _)| n.eq_ignore_ascii_case(name))
 }
 
+/// One window's record as `chat-cache.txt` persists it, in the reference's own field types.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct ChatWindowLook {
-    /// Background tint, `0..=255` each. The engine renormalises by 1/255 on the way out.
+    /// Background tint, one byte per channel.
     pub r: u8,
-    /// See [`Self::r`].
     pub g: u8,
-    /// See [`Self::r`].
     pub b: u8,
-    /// Background alpha, `0..=255`. `0` is the stock value and what benilla shipped as a constant
-    /// until 1589 — the hover fade lifts it to `DEFAULT_CHATFRAME_ALPHA` and drops it back.
+    /// Background alpha byte; stock 0, which the FrameXML hover fade lifts.
     pub a: u8,
-    /// The cache's `SIZE` — the chat font height in points, or `0` for "the font's own height".
-    /// The reference's own values are `CHAT_FONT_HEIGHTS = {12, 14, 16, 18}`. An `i32` because the
-    /// record's field is (`+0x84`), and never `<= 0` once set: the setter drops those.
+    /// `SIZE`: the font height, or 0 for the font's own; the setter never stores `<= 0`.
     pub font_size: i32,
-    /// The cache's `LOCKED` — whether the window refuses to be dragged or resized.
-    ///
-    /// **`true` out of the box**, because the stock row is `LOCKED 1` for every window: a fresh
-    /// character's chat box cannot be nudged out of place by a stray drag, and unlocking it is a
-    /// deliberate trip through the tab menu (`FCF_ToggleLock`). It joined this struct with the
-    /// move/resize arc: until something could *move* a window, writing the key would have
-    /// persisted state nothing could change, which is the honest-tree rule (1134 §4) at the
-    /// persistence layer, and the reason 1589 §6 left it out.
+    /// `LOCKED`, stock true for every window; the tab menu's `FCF_ToggleLock` moves it.
     pub locked: bool,
-    /// The cache's `DOCKED` — the window's **position in the dock**, 1-based, or `None` for a
-    /// window that is not docked. Not a flag: window 1 answers `1` and window 2 `2`, which is the
-    /// index `FCF_DockFrame(frame, docked)` takes (this module's §3 note), and the order the tabs
-    /// sit in.
-    ///
-    /// It joined this struct with the dock verbs (1714), by the same rule `locked` did: until
-    /// `FCF_DockFrame`/`FCF_UnDockFrame` existed there was nothing that could move it, so it was a
-    /// per-window constant read straight out of [`WINDOW_STATE`]. There is now, so it is state.
+    /// `DOCKED`: the 1-based dock position `FCF_DockFrame(frame, docked)` takes, `None` undocked.
     pub docked: Option<u8>,
-    /// `+0x00` — the window's name as `SetChatWindowName` stored it: `""` until FrameXML names
-    /// it (the getter's first return; the `NAME` line is emitted only when non-empty).
+    /// `+0x00`: `""` until `SetChatWindowName` stores one; `NAME` is written only when non-empty.
     pub name: String,
-    /// `+0x94` — `SHOWN`; the getter answers 1 or nil off it.
+    /// `+0x94`, `SHOWN`.
     pub shown: bool,
-    /// `+0x20` — the enabled message-type names, the `MESSAGES … END` block.
+    /// `+0x20`: the enabled message-group names, the `MESSAGES … END` block.
     pub messages: Vec<String>,
-    /// `+0x64` / `+0x74` — the channels this window shows, `(name, zone channel id)` pairs: the
-    /// `CHANNELS … END` block.
+    /// `+0x64`/`+0x74`: `(name, zone channel id)` pairs, the `CHANNELS … END` block.
     pub channels: Vec<(String, u32)>,
 }
 
@@ -277,7 +144,7 @@ impl Default for ChatWindowLook {
 }
 
 impl ChatWindowLook {
-    /// The stock `chat-cache.txt` row, as a const so [`super::Model`]'s array literal can use it.
+    /// The boot record of windows 3 to 10 (`0x4982c0`), which [`Self::stock`] builds 1 and 2 on.
     pub(super) const DEFAULT: Self = Self {
         r: 0,
         g: 0,
@@ -285,9 +152,6 @@ impl ChatWindowLook {
         a: 0,
         font_size: 0,
         locked: true,
-        // The stock row's `DOCKED` differs per window, so the array literal that uses this const
-        // seeds each slot from [`WINDOW_STATE`] afterwards. `None` here is only the value a
-        // slot holds before that seeding, and the value a *hand-built* look starts at.
         docked: None,
         name: String::new(),
         shown: false,
@@ -295,17 +159,10 @@ impl ChatWindowLook {
         channels: Vec::new(),
     };
 
-    /// The stock row for window `index` (0-based) — [`Self::DEFAULT`] with that window's own
-    /// `DOCKED` position from [`WINDOW_STATE`]. The seed for the model's array and for the
-    /// settings parser's per-line default, so a file that never mentions `DOCKED` keeps the
-    /// shipped dock rather than silently undocking both windows.
-    /// The boot init `0x4982c0` (wow-re chat-cache-grammar.md §4) — the record a client with no
-    /// `chat-cache.txt` runs from, and what FrameXML's own `FloatingChatFrame_Update` then docks,
-    /// hides and saves: window 1 shown and undocked (it IS the dock — `FCF_DockFrame(ChatFrame1, 1)`
-    /// at FloatingChatFrame.xml's file scope), groups 1–10 by a literal fill; window 2 shown and
-    /// `docked 1`, every `defaultOn` group of 11–68 (the 34 the stock file lists); windows 3–10
-    /// hidden with nothing enabled. Every window locked, size 0, colour 0, name empty, ten empty
-    /// channel slots. The init fires no event; the loader does (§8).
+    /// Window `index`'s (0-based) record at boot (`0x4982c0`), what a client with no
+    /// `chat-cache.txt` runs from: window 1 shown and undocked (FrameXML docks it,
+    /// FloatingChatFrame.xml:835) with groups 1-10; window 2 shown, docked at 1, with the
+    /// `defaultOn` groups of 11-68; the rest hidden with no groups.
     pub fn stock(index: usize) -> Self {
         let groups = |range: std::ops::Range<usize>, all: bool| -> Vec<String> {
             MESSAGE_GROUPS[range]
@@ -330,9 +187,8 @@ impl ChatWindowLook {
         }
     }
 
-    /// The loader's discipline over the message set — unknown names dropped, duplicates folded,
-    /// **table order** — so `GetChatWindowMessages` answers the way a flag walk does (§5: "table
-    /// order 0..67") whatever order a file or a caller listed them in.
+    /// Drops unknown names and duplicates and puts the rest in table order, so
+    /// `GetChatWindowMessages` (`0x4a0d20`) answers as the reference's flag walk does.
     pub fn normalize_messages(&mut self) {
         let mut flags = [false; MESSAGE_GROUPS.len()];
         for m in &self.messages {
@@ -349,10 +205,8 @@ impl ChatWindowLook {
     }
 }
 
-/// `x` in the reference's `0..1` float domain → the byte its `__ftol(x · 255.0)` stores, clamped
-/// (see the module docs' divergence note). `NaN` lands on `0` rather than propagating.
-/// `SStrToInt` — the leading decimal integer of a string (an optional sign, then digits), 0 when
-/// there is none.
+/// The leading decimal integer after optional whitespace and a sign, 0 when there is none. The
+/// reference's `SStrToInt` (`0x64ac60`) takes neither the whitespace nor a `+`.
 pub(super) fn leading_int(s: &str) -> i64 {
     let s = s.trim_start();
     let (neg, digits) = match s.strip_prefix('-') {
@@ -373,6 +227,7 @@ pub(super) fn leading_int(s: &str) -> i64 {
     }
 }
 
+/// The byte `__ftol(x · 255.0)` stores, clamped (the module's deviation); non-finite stores 0.
 fn to_byte(x: f64) -> u8 {
     if !x.is_finite() {
         return 0;
@@ -380,13 +235,13 @@ fn to_byte(x: f64) -> u8 {
     (x * 255.0).trunc().clamp(0.0, 255.0) as u8
 }
 
-/// The byte the engine stores → the `0..1` float `GetChatWindowInfo` answers.
 fn from_byte(b: u8) -> f64 {
     f64::from(b) / 255.0
 }
 
-/// The 1-based Lua window id → a live index, or the raise every out-of-range ask gets. Shared by
-/// the getter and the three setters so a window that cannot be read cannot be written either.
+/// The 0-based index of a Lua window id. Deviation: an id outside the seven built windows raises,
+/// where the reference serves ten records and silently ignores any other id (`0x4a0be1`), because
+/// benilla keeps only the seven and every caller loops `1, NUM_CHAT_WINDOWS`.
 fn window_index(id: i64) -> mlua::Result<usize> {
     if id < 1 || id as usize > NUM_CHAT_WINDOWS {
         return Err(mlua::Error::runtime(format!(
@@ -399,11 +254,9 @@ fn window_index(id: i64) -> mlua::Result<usize> {
 }
 
 impl super::Model {
-    /// **Register a channel in window `window`'s list** — the shared tail of `JoinChannelByName`
-    /// (`0x49ec24`–`0x49ede7`) and `AddChatWindowChannel` (`0x4a1000`): `(name, id)` appended
-    /// unless an entry of that name is already there (`SStrCmpI`), and the window marked for the
-    /// persist pass. `name` is the DBC's own Shortcut for a matched row, the argument verbatim for
-    /// a custom channel. Answers whether anything was added.
+    /// Appends `(name, id)` to window `window`'s channels unless the name is there (case-folded):
+    /// the shared tail of `JoinChannelByName` (`0x49ec24`-`0x49ede7`) and `AddChatWindowChannel`
+    /// (`0x4a1000`). `name` is the DBC Shortcut for a matched row, else the argument verbatim.
     pub(super) fn register_window_channel(&mut self, window: usize, name: String, id: u32) -> bool {
         let Some(look) = self.chat_window_looks.get_mut(window) else {
             return false;
@@ -420,11 +273,9 @@ impl super::Model {
         true
     }
 
-    /// **Strip `key` from every window's list** — leave-by-name `0x49ee70`'s `0x49f001`–`0x49f085`
-    /// (wow-re `leavechannelbyname-contract.md` §6): all ten windows, the first entry whose name
-    /// equals `key` case-insensitively, the cell blanked. `key` is the DBC Shortcut when the
-    /// argument matched a row, else the argument verbatim; the numeric form strips nothing,
-    /// because a slot name never equals a window entry. Answers whether anything was stripped.
+    /// Removes the first entry named `key` (case-folded) from every window, as leave-by-name
+    /// `0x49ee70` does (`0x49f001`-`0x49f085`). `key` is the DBC Shortcut for a matched row, else
+    /// the argument; a numeric leave strips nothing, as a slot name never equals a window entry.
     pub(super) fn strip_window_channel(&mut self, key: &str) -> bool {
         let mut stripped = false;
         for (i, look) in self.chat_window_looks.iter_mut().enumerate() {
@@ -443,21 +294,15 @@ impl super::Model {
 }
 
 impl super::UiScript {
-    /// Host-side [`Model::register_window_channel`] — the guild-recruitment cascade's join arm,
-    /// which registers `GuildRecruitment` in window 1 the way `0x49eb70(frameIdx = 0)` does.
+    /// Host-side [`Model::register_window_channel`], for the guild-recruitment join, which
+    /// registers `GuildRecruitment` in window 1 as `0x49eb70(frameIdx = 0)` does.
     pub fn register_chat_window_channel(&mut self, window: usize, name: &str, id: u32) -> bool {
         self.model_mut()
             .register_window_channel(window, name.to_string(), id)
     }
 
-    /// Host-side [`Model::strip_window_channel`] — the cascade's leave arm.
-    pub fn strip_chat_window_channel(&mut self, key: &str) -> bool {
-        self.model_mut().strip_window_channel(key)
-    }
-
-    /// Seed the per-window looks from the host's persisted store — the load path, so it queues no
-    /// change (an echo would re-dirty the file it was just read from; [`Self::set_cvar_host`]'s
-    /// reason, one store over).
+    /// Seeds the records from the host's persisted store. A load queues no change: an echo would
+    /// re-dirty the file just read.
     pub fn set_chat_window_looks(
         &mut self,
         looks: impl IntoIterator<Item = (usize, ChatWindowLook)>,
@@ -471,14 +316,12 @@ impl super::UiScript {
         }
     }
 
-    /// Snapshot every window's look, index 0 = `ChatFrame1` — what the saver writes out.
+    /// Every window's record, index 0 being `ChatFrame1`, for the saver.
     pub fn chat_window_looks(&self) -> Vec<ChatWindowLook> {
         self.model_mut().chat_window_looks.to_vec()
     }
 
-    /// Drain the 0-based indices whose look Lua moved since the last call — the host's cue to
-    /// persist. Deduplicated and ascending, so a slider drag that wrote one window forty times
-    /// costs the saver one entry.
+    /// Drains the 0-based windows Lua changed since the last call, deduplicated and ascending.
     pub fn take_chat_window_changes(&mut self) -> Vec<usize> {
         let mut v: Vec<usize> = std::mem::take(&mut self.model_mut().chat_window_changes)
             .into_iter()
@@ -489,9 +332,7 @@ impl super::UiScript {
 }
 
 impl super::UiScript {
-    /// Drain the `ChatFrame_OpenChat` requests queued since the last call — each is the text the
-    /// caller wants the chat edit box to open prefilled with. The app opens and focuses the box,
-    /// applies its own sticky-type law, and lets the live parse take the text from there.
+    /// Drains the texts `ChatFrame_OpenChat` queued since the last call.
     pub fn take_open_chat_requests(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().open_chat_requests)
     }
@@ -499,12 +340,6 @@ impl super::UiScript {
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     // GetChatWindowInfo(id) → name, fontSize, r, g, b, a, shown, locked, docked.
-    //
-    // Out of range RAISES rather than answering. The reference's array has 10 slots and benilla
-    // builds 7 windows; a question about window 8 is a question about a window that does not exist
-    // here, and the two honest answers are "raise" or "invent a row". Every corpus caller loops
-    // `1, NUM_CHAT_WINDOWS`, so the raise is unreachable from real code and exists to keep the
-    // next caller from reading a fabricated window as a real one.
     lua.globals().set(
         "GetChatWindowInfo",
         lua.create_function(|lua, id: i64| {
@@ -515,43 +350,32 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 .chat_window_looks[i]
                 .clone();
             let shown = if look.shown { Some(1) } else { None };
-            // `docked` is the LIVE position now, not the table's — `FCF_DockFrame`/
-            // `FCF_UnDockFrame` move it through `SetChatWindowDocked` below.
             let docked = look.docked.map(i64::from);
             let num = |v: Option<i64>| match v {
                 Some(n) => Value::Integer(n),
                 None => Value::Nil,
             };
             Ok(MultiValue::from_vec(vec![
-                // name: "" until `SetChatWindowName` stores one — never a label of ours. See
-                // the module docs' trap 1.
                 Value::String(lua.create_string(&look.name)?),
-                // The three the setters below own (1589). Stock is SIZE 0 / COLOR 0 0 0 0 — the
-                // same tuple this getter answered as a constant before those setters existed.
                 Value::Integer(i64::from(look.font_size)),
                 Value::Number(from_byte(look.r)),
                 Value::Number(from_byte(look.g)),
                 Value::Number(from_byte(look.b)),
                 Value::Number(from_byte(look.a)),
                 num(shown), // 1 or nil, never 0
-                // locked — the cache's LOCKED, stock `1`, moved by `SetChatWindowLocked` below.
-                // `1` or nil like `shown`, never `0`: the reference's own boolean-in-a-number.
+                // locked: 1 or nil, never 0
                 if look.locked {
                     Value::Integer(1)
                 } else {
                     Value::Nil
                 },
-                num(docked), // the dock POSITION (1, 2) or nil
+                num(docked), // the dock position or nil
             ]))
         })?,
     )?;
 
-    // SetChatWindowColor(id, r, g, b) — 0x4a14f0, `__ftol(x · 255.0)` per channel.
-    //
-    // FrameXML's caller is `FCF_SetWindowColor` (FloatingChatFrame.lua l.696-704), which tints the
-    // nine CHAT_FRAME_TEXTURES and then saves through here; the tab menu's Background swatch
-    // reaches it via `FCF_SetChatWindowBackGroundColor`. The write is what makes the tint survive
-    // a session — the *visible* tint is the Lua SetVertexColor, not this.
+    // SetChatWindowColor(id, r, g, b) (`0x4a14f0`) only stores: `FCF_SetWindowColor`
+    // (FloatingChatFrame.lua:699) tints the textures itself.
     lua.globals().set(
         "SetChatWindowColor",
         lua.create_function(|lua, (id, r, g, b): (i64, f64, f64, f64)| {
@@ -572,11 +396,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetChatWindowAlpha(id, alpha) — 0x4a15d0, `__ftol(alpha · 255.0)`.
-    //
-    // FrameXML's caller is `FCF_SetWindowAlpha` (l.706-716), the other half of the tab menu's
-    // Background row: its opacity slider drives `FCF_SetChatWindowOpacity` on every drag step.
-    // `frame.oldAlpha` — the value the hover fade returns to — is that same number.
+    // SetChatWindowAlpha(id, alpha) (`0x4a15d0`), called on every opacity-slider step.
     lua.globals().set(
         "SetChatWindowAlpha",
         lua.create_function(|lua, (id, alpha): (i64, f64)| {
@@ -592,23 +412,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetChatWindowLocked(id, isLocked) — `0x4a1650`, writing the record's `+0x8c` locked field
-    // (wow-re `system/ui/ledger.tsv:9325` + `scratch/chat-window-record.md` §2, VERIFIED:
-    // `0x4a16a2 mov [esi+0xb4fedc],eax`, initialised to **1** at `0x4984e4`, read back as
-    // `GetChatWindowInfo`'s 8th return at `0x4a0cbf`).
-    //
-    // **A `bool` is the faithful store even though the field is an `i32`**: the cache writer
-    // booleanises it through `setne` (`0x499e8b`, fmt `LOCKED %d`), so nothing outside `{0,1}`
-    // survives a file round trip — the same note records that as the difference between this field
-    // and `SIZE`, which does round-trip arbitrary values.
-    //
-    // The one value of the tuple the *player* moves rather than the layout: `FCF_SetLocked`
-    // (FloatingChatFrame.lua l.802-805) writes the frame field and this store in the same breath,
-    // and `FloatingChatFrame_Update` (l.56) seats the frame back from here at load.
-    //
-    // Lua truthiness, not a strict boolean, because the reference's callers pass `1` and `nil` —
-    // `FCF_ToggleLock`'s two arms and `FCF_OpenNewWindow`'s `SetChatWindowLocked(i, nil)`. mlua
-    // marshals both the way the reference binding's own `toboolean` does.
+    // SetChatWindowLocked(id, isLocked) (`0x4a1650`): the record's `+0x8c` (`0x4a16a2`), 1 at
+    // boot (`0x4984e4`). A `bool` holds it, as the cache writer stores it through `setne`
+    // (`0x499e8b`). The argument is Lua truthiness, where the reference coerces through `0x6f1c10`
+    // (default 0): `0` and "off" unlock there and lock here. FrameXML passes only 1 and nil.
     lua.globals().set(
         "SetChatWindowLocked",
         lua.create_function(|lua, (id, locked): (i64, bool)| {
@@ -622,21 +429,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetChatWindowDocked(id, position) — the dock half of the record, written by `FCF_SaveDock`
-    // (FloatingChatFrame.lua l.1276-1285) once per docked window on every dock change, and by
-    // `FCF_UnDockFrame` (l.1182) with `nil` to clear it.
-    //
-    // **The argument is a POSITION, not a flag** — this module's §3 trap, and the reason this
-    // takes a number rather than the `bool` `SetChatWindowLocked` takes: `FCF_SaveDock` passes the
-    // running `count`, so window 1 stores `1` and window 2 stores `2`, and that is what
-    // `GetChatWindowInfo`'s 9th return hands back to `FCF_DockFrame(frame, docked)` as its index.
-    // A `nil` clears it (undocked); anything `<= 0` is treated as a clear too, since a dock
-    // position is 1-based and the reference has no zeroth slot.
-    //
-    // **Not persisted yet, and that is a stated gap.** The `chat-cache` writer
-    // (`benilla_app`'s `ui_chat::settings`) renders `DOCKED` alongside `LOCKED`, but an absent key
-    // must keep the *per-window* stock rather than one flat default — see
-    // [`ChatWindowLook::stock`], which is what the parser seeds from.
+    // SetChatWindowDocked(id, position) (`0x4a16b0`): `FCF_SaveDock` (FloatingChatFrame.lua:1282)
+    // writes each docked window's 1-based position, `FCF_UnDockFrame` nil. Nil or a position
+    // outside 1..=255 clears it here; the reference stores a number truncated, a non-number as 0.
     lua.globals().set(
         "SetChatWindowDocked",
         lua.create_function(|lua, (id, position): (i64, Option<i64>)| {
@@ -653,23 +448,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetChatWindowSize(id, fontSize) — 0x4a1470.
-    //
-    // FrameXML's caller is `FCF_SetChatWindowFontSize` (l.752-763), which does the visible half
-    // (`chatFrame:SetFont(file, size, flags)`) and then saves through here. A size the reference
-    // never stores is `0` — "the font's own height" — which is what a stock cache holds and what
-    // benilla ships until the player picks one off the Font Size submenu.
+    // SetChatWindowSize(id, fontSize) (`0x4a1470`) only stores; FrameXML sets the font itself.
     lua.globals().set(
         "SetChatWindowSize",
         lua.create_function(|lua, (id, size): (i64, f64)| {
             let i = window_index(id)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let look = &mut model.chat_window_looks[i];
-            // The cache's SIZE is a small integer; anything unrepresentable clamps rather than
-            // wrapping (the module docs' divergence, same reason).
-            // `<= 0` is dropped, not stored — the reference's own `jle` at `0x4a14bc`. That is
-            // why a stock `SIZE 0` and "the player picked a size" are different states rather
-            // than the same one written twice.
+            // A size `<= 0` after truncation is dropped (`0x4a14bc jle`). Deviation: one past
+            // `i32::MAX` clamps where the reference keeps the low 32 bits, for the colours' reason.
             let s = if size.is_finite() && size >= 1.0 {
                 size.trunc().min(f64::from(i32::MAX)) as i32
             } else {
@@ -683,29 +470,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ChatFrame_OpenChat(text, chatFrame) — open the chat edit box prefilled with `text`.
-    //
-    // **The second argument is inert, and that is the reference's doing, not a shortcut.** The ref
-    // reaches the box through `chatFrame.editBox`, and in 1.12 every chat frame's `.editBox` is
-    // the *same* global `ChatFrameEditBox`: `FloatingChatFrame_OnLoad` sets
-    // `this.editBox = ChatFrameEditBox` for each frame (FloatingChatFrame.lua l.30), and
-    // ChatFrame1 — which loads before the edit box exists and so skips that `if` — is patched by
-    // the box's own OnLoad, `DEFAULT_CHAT_FRAME.editBox = this` (FloatingChatFrame.xml l.742).
-    // Per-frame edit boxes are a 2.x feature. So `ChatFrame_OpenChat(text, ChatFrame5)` opens the
-    // one and only edit box on a real 1.12 client too, and accepting-and-ignoring the frame here
-    // is exact rather than approximate. `benilla_app`'s `chat_tests` states that as a claim.
-    //
-    // Measured demand: 3 distinct addons, and all three are the same shape — check the box is not
-    // already up, then open it prefilled, else fall back to SetText/Insert:
-    //   FuBar_HeyFu/Core.lua:281,292      ChatFrame_OpenChat(reply, DEFAULT_CHAT_FRAME)
-    //   FuBar_FriendsFu/FriendsFu.lua:434 ChatFrame_OpenChat(format("/w %s ", name))   -- 1 arg
-    //   TipBuddy/TipBuddy.xml:2715,2717   ChatFrame_OpenChat("", chatFrame) / ("/", chatFrame)
-    // Two of the three prefill `/w <name> `, which the app's live parse then turns into whisper
-    // mode with the target extracted — the same path a human typing those characters takes.
-    //
-    // The ref's tail — the PARTY/RAID/BATTLEGROUND sticky downgrade (l.1554-1565) — is not skipped,
-    // it is the app's: `ui_chat::edit`'s open path already applies exactly that law (a sticky PARTY
-    // with nobody in the party opens as SAY), so running it here would be running it twice.
+    // ChatFrame_OpenChat(text, chatFrame) queues `text` for the host to open the chat box with. The
+    // frame is inert: in 1.12 every chat frame's `editBox` is the one `ChatFrameEditBox`
+    // (FloatingChatFrame.lua:30, FloatingChatFrame.xml:742). The stock ChatFrame.lua:1545 defines
+    // the same global and replaces this one when it loads.
     lua.globals().set(
         "ChatFrame_OpenChat",
         lua.create_function(|lua, (text, _chat_frame): (Option<String>, Value)| {
@@ -715,14 +483,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The rest of the 0x98 record: name, shown, message types, channels ──────────────────
+    // ── The rest of the record: name, shown, message groups, channels ──────────────────────
     //
-    // `SetChatWindowName 0x4a13f0` / `SetChatWindowShown 0x4a1730` are registrar entries beside
-    // the look setters (chat-window-record.md §8); `Add/Remove/GetChatWindowMessages`
-    // (`0x4a0e80`/`0x4a0f40`/`0x4a0d20`) and `Add/Remove/GetChatWindowChannel(s)`
-    // (`0x4a1000`/`0x4a1260`/`0x4a0dc0`) read and write the `+0x20` flags and the `+0x64`/`+0x74`
-    // arrays the same census bounded (§7). Every write that moves the record queues the window
-    // for the app's persist pass, like the look setters.
+    // `SetChatWindowName` `0x4a13f0`, `SetChatWindowShown` `0x4a1730`,
+    // `Add/Remove/GetChatWindowMessages` `0x4a0e80`/`0x4a0f40`/`0x4a0d20` and
+    // `Add/Remove/GetChatWindowChannel(s)` `0x4a1000`/`0x4a1260`/`0x4a0dc0`.
 
     fn with_look<T>(
         lua: &Lua,
@@ -739,8 +504,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         Ok(out)
     }
 
-    // The names, resolved against `CHATMSGGROUP` the loader's way; a name with no group is
-    // silently nothing (`0x4a0ea9` scan, no match → no write).
+    // Group names, case-folded; an unknown name is skipped (`0x4a0ea9`).
     fn names_of(args: MultiValue) -> Vec<&'static str> {
         args.iter()
             .filter_map(|v| match v {
@@ -751,8 +515,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             .collect()
     }
 
-    // SetChatWindowName(id, name) — `SStrCopy(record+0, name, 0x20)`: 31 bytes and the NUL; a
-    // non-string second argument is the empty string (`0x4a1436`).
+    // SetChatWindowName(id, name): `SStrCopy(record+0, name, 0x20)`, 31 bytes and the NUL. The
+    // reference stores "" for a name neither string nor number (`0x4a1436`); here a missing or nil
+    // name stores "", and a boolean or table raises.
     lua.globals().set(
         "SetChatWindowName",
         lua.create_function(|lua, (id, name): (i64, Option<String>)| {
@@ -768,10 +533,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetChatWindowShown(id [, shown]) — `+0x94 = 0x6f1c10(L, 2, default 1)`: NO second argument
-    // stores 1; an explicit nil, `false`, `0` or `"off"` store 0 — the reference's own flag
-    // coercion (a boolean, a number by `__ftol`, a string by its digits or by
-    // on/off/enabled/disabled).
+    // SetChatWindowShown(id [, shown]): `+0x94` through the flag coercion `0x6f1c10`, default 1.
+    // No argument stores 1; nil, false, 0, "0", "off" and "disabled" store 0. The reference also
+    // stores 0 for a string opening F or N ("false", "no"), which stores 1 here.
     lua.globals().set(
         "SetChatWindowShown",
         lua.create_function(|lua, (id, rest): (i64, MultiValue)| {
@@ -798,7 +562,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AddChatWindowMessages(id, "TYPE", "TYPE", …) — each name set in the window's flags.
     lua.globals().set(
         "AddChatWindowMessages",
         lua.create_function(|lua, (id, names): (i64, MultiValue)| {
@@ -824,8 +587,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetChatWindowMessages(id) — the enabled names as a vararg list, which
-    // `ChatFrame_RegisterForMessages(GetChatWindowMessages(id))` consumes directly.
+    // GetChatWindowMessages(id): the enabled group names as varargs, in table order.
     lua.globals().set(
         "GetChatWindowMessages",
         lua.create_function(|lua, id: i64| {
@@ -839,13 +601,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AddChatWindowChannel(id, "channel") — `0x4a1000` (chat-cache-grammar.md §5): (i) the
-    // `ChatChannels.dbc` walk compares the argument with each row's **Shortcut**, whole, case-
-    // folded; no match → id 0 and the Lua string; a match with no zone text yet → **nil** (0
-    // values) and nothing stored; a match → the row's id and **the DBC's own Shortcut string**,
-    // not the argument. (ii) The id is the one push. (iii) A name already in the window answers
-    // the id and stores nothing. `ChatFrame_AddChannel` keys its bookkeeping on the answer's
-    // truthiness, and 0 is truthy.
+    // AddChatWindowChannel(id, name) (`0x4a1000`): a whole, case-folded match on a
+    // `ChatChannels.dbc` Shortcut stores the DBC's spelling and answers the row id; no match stores
+    // the name and answers 0, which `ChatFrame_AddChannel` reads as truthy; a matched row with no
+    // zone text yet answers and stores nothing. A name already there only answers the id.
     lua.globals().set(
         "AddChatWindowChannel",
         lua.create_function(|lua, (id, name): (i64, Option<String>)| {
@@ -880,10 +639,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RemoveChatWindowChannel(id, "channel" | n) — `0x4a1260`: a numeric argument (`SStrToInt`,
-    // n ≠ 0) names joined slot n, whose name is the key — or nothing, when no such slot; 0 (no
-    // digits) keeps the string. Then the shortcut walk above resolves the key to the DBC's own
-    // spelling, and the slot with that name is freed. 0 values.
+    // RemoveChatWindowChannel(id, name | n) (`0x4a1260`): a numeric key names the joined channel
+    // in slot n, and an empty slot removes nothing; the key then resolves to its DBC Shortcut as
+    // above, and the entry of that name is freed.
     lua.globals().set(
         "RemoveChatWindowChannel",
         lua.create_function(|lua, (id, key): (i64, Option<String>)| {
@@ -921,8 +679,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetChatWindowChannels(id) — name, zoneId, name, zoneId, … which
-    // `ChatFrame_RegisterForChannels` walks two at a time.
+    // GetChatWindowChannels(id): `name, zoneId` pairs in slot order.
     lua.globals().set(
         "GetChatWindowChannels",
         lua.create_function(|lua, id: i64| {
@@ -944,16 +701,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// The tuple is nine values wide and in the reference's own order.
     #[test]
     fn get_chat_window_info_answers_the_nine_value_tuple() {
         let s = UiScript::new().unwrap();
         assert_eq!(s.arity("GetChatWindowInfo(1)").unwrap(), 9);
     }
 
-    /// Trap 1: a stock client has never been told a window's name, so the getter answers `""` and
-    /// FrameXML supplies "General"/"Combat Log". Enchantrix's `if ( name == "" )` fallback is only
-    /// correct because of this.
     #[test]
     fn every_window_name_is_the_empty_string_not_a_label() {
         let s = UiScript::new().unwrap();
@@ -965,11 +718,8 @@ mod tests {
         }
     }
 
-    /// Trap 2: `shown`/`docked` are `nil` where the record stores 0, because FrameXML branches
-    /// on them bare and `0` is true in Lua. At the boot init (chat-cache-grammar.md §4) window 1
-    /// is shown and undocked — it is the dock, `FCF_DockFrame(ChatFrame1, 1)` at file scope —
-    /// window 2 is shown with `docked 1`, and 3..7 are neither; the `DOCKED 1`/`DOCKED 2`,
-    /// `SHOWN 1`/`SHOWN 0` a stock file carries are what FrameXML's own dock pass then saved.
+    /// At boot (`0x4982c0`) window 1 is shown and undocked, window 2 shown and docked at 1, and
+    /// windows 3 to 7 neither.
     #[test]
     fn hidden_and_undocked_windows_answer_nil_never_zero() {
         let s = UiScript::new().unwrap();
@@ -991,7 +741,7 @@ mod tests {
         for id in 3..=7 {
             assert_eq!(probe(id), ("nil".into(), "nil".into()), "window {id}");
         }
-        // And the truthiness FrameXML actually branches on.
+        // The truthiness FrameXML branches on.
         assert!(s
             .eval::<bool>(
                 "for i = 3, 7 do local _,_,_,_,_,_,shown = GetChatWindowInfo(i) \
@@ -1000,9 +750,7 @@ mod tests {
             .unwrap());
     }
 
-    /// Trap 3: `docked` is the dock POSITION `FCF_DockFrame(frame, index)` inserts at — the
-    /// init's window 2 answers 1 (§4, `mov ds:0xb4ff78, 1`), and once FrameXML has saved its
-    /// dock (`FCF_SaveDock`) the stored positions are whatever it wrote.
+    /// The boot init docks window 2 at 1 (`0x4982c0`: `mov ds:0xb4ff78, 1`).
     #[test]
     fn docked_is_a_dock_position_not_a_flag() {
         let mut s = UiScript::new().unwrap();
@@ -1024,8 +772,8 @@ mod tests {
         let _ = s.take_chat_window_changes();
     }
 
-    /// The corpus's own debug-window walk (MikScrollingBattleText, EnhTooltip) runs to completion
-    /// and finds nothing — `string.lower(name)` needs a string, and no window is named "debug".
+    /// The debug-window walk of MikScrollingBattleText and EnhTooltip, whose `string.lower(name)`
+    /// needs a string.
     #[test]
     fn the_corpus_debug_window_walk_completes_and_finds_none() {
         let s = UiScript::new().unwrap();
@@ -1042,7 +790,6 @@ mod tests {
         assert_eq!(found, 0);
     }
 
-    /// A window benilla has no frame for raises rather than answering with an invented row.
     #[test]
     fn a_window_past_the_last_frame_raises() {
         let s = UiScript::new().unwrap();
@@ -1050,8 +797,7 @@ mod tests {
         assert!(s.eval::<i64>("return (GetChatWindowInfo(0))").is_err());
     }
 
-    /// A size `<= 0` is DROPPED, not stored — the reference's own `jle` at `0x4a14bc`, so a stock
-    /// `SIZE 0` cannot be re-written by a caller handing it 0.
+    /// The reference's `jle` at `0x4a14bc`.
     #[test]
     fn a_non_positive_font_size_is_dropped_not_stored() {
         let s = UiScript::new().unwrap();
@@ -1067,10 +813,7 @@ mod tests {
         }
     }
 
-    /// The three setters round-trip through the getter — and they round-trip through the
-    /// reference's BYTE quantisation, not through the float they were handed. `0.4 × 255 = 102`,
-    /// and `102/255` is what comes back — and `0.5` comes back `127/255`, not `128/255`, because
-    /// `__ftol` truncates (§5-verified: a real client stores 127 there).
+    /// `__ftol(x · 255.0)` truncates: 0.4 stores 102 and 0.5 stores 127.
     #[test]
     fn the_setters_round_trip_through_the_engine_byte() {
         let s = UiScript::new().unwrap();
@@ -1092,7 +835,6 @@ mod tests {
             .unwrap();
         assert_eq!(size, 16);
 
-        // The truncation, on the value that shows it: `0.5 × 255 = 127.5`.
         s.run("SetChatWindowAlpha(1, 0.5)").unwrap();
         let a: f64 = s
             .eval("local _,_,_,_,_,a = GetChatWindowInfo(1) return a")
@@ -1104,7 +846,6 @@ mod tests {
         );
     }
 
-    /// Windows are independent: writing window 2 leaves window 1 on the stock row.
     #[test]
     fn a_setter_moves_only_the_window_it_names() {
         let s = UiScript::new().unwrap();
@@ -1119,8 +860,6 @@ mod tests {
         assert_eq!(two, 1.0);
     }
 
-    /// The setters raise on the same range the getter does — a window benilla has no frame for
-    /// cannot be written any more than it can be read.
     #[test]
     fn the_setters_raise_on_a_window_with_no_frame() {
         let s = UiScript::new().unwrap();
@@ -1129,8 +868,8 @@ mod tests {
         assert!(s.run("SetChatWindowSize(8, 14)").is_err());
     }
 
-    /// We clamp where the reference wraps (the module docs' one named divergence): a real client
-    /// stores the low byte of `ftol(2.0 × 255) = 510` and answers `254/255`.
+    /// The deviation: the reference stores the low byte of `__ftol(2.0 · 255) = 510`, answering
+    /// 254/255.
     #[test]
     fn an_out_of_domain_alpha_clamps_rather_than_wrapping() {
         let s = UiScript::new().unwrap();
@@ -1146,8 +885,6 @@ mod tests {
         assert_eq!(a, 0.0);
     }
 
-    /// The host seam: Lua writes queue one index per touched window however many steps the drag
-    /// took, the host load path queues nothing, and the drain is a take.
     #[test]
     fn the_host_seam_dedupes_writes_and_stays_quiet_on_load() {
         let mut s = UiScript::new().unwrap();
@@ -1185,8 +922,6 @@ mod tests {
         assert_eq!(s.chat_window_looks()[0].font_size, 14);
     }
 
-    /// A write that changes nothing queues nothing — the reference's own setters are called on
-    /// every colour-picker drag step, including the ones that land on the value already stored.
     #[test]
     fn a_write_that_moves_nothing_queues_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -1196,8 +931,6 @@ mod tests {
         assert!(s.take_chat_window_changes().is_empty());
     }
 
-    /// `ChatFrame_OpenChat` queues the text for the app; the optional frame argument is accepted
-    /// and dropped (in 1.12 every chat frame shares one edit box — see the install comment).
     #[test]
     fn chat_frame_open_chat_queues_its_text_and_ignores_the_frame() {
         let mut s = UiScript::new().unwrap();
@@ -1219,8 +952,7 @@ mod record_tests {
     use super::{ChatWindowLook, MESSAGE_GROUPS};
     use crate::script::{UiScript, ZoneChannelRow};
 
-    /// The boot init (chat-cache-grammar.md §4): window 1 shown with groups 1–10, window 2 shown
-    /// at dock index 1 with the 34 `defaultOn` groups of 11–68, the rest empty and hidden.
+    /// The boot init (`0x4982c0`); 34 of groups 11 to 68 are `defaultOn`.
     #[test]
     fn the_stock_records_are_the_boot_init() {
         let s = UiScript::new().unwrap();
@@ -1265,7 +997,7 @@ mod record_tests {
         assert_eq!(s.take_chat_window_changes(), vec![0, 2]);
         s.run("SetChatWindowName(3, 'Loot')").unwrap();
         assert!(s.take_chat_window_changes().is_empty(), "no move, no cue");
-        // The flag coercion (`0x6f1c10`, default 1) and the name cap (`SStrCopy`, 0x20).
+        // The flag coercion (`0x6f1c10`, default 1) and the 31-byte name cap.
         s.run(
             "SetChatWindowShown(4, 'off') SetChatWindowShown(5, '1') SetChatWindowShown(6, 0) \
              SetChatWindowName(4, 'abcdefghijklmnopqrstuvwxyz0123456789')",
@@ -1279,8 +1011,6 @@ mod record_tests {
         assert_eq!(looks[3].name.len(), 31, "31 bytes and the NUL");
     }
 
-    /// The flags: a name resolves against `CHATMSGGROUP` case-folded, an unknown name is
-    /// nothing, and the answer is the table's order whatever order the calls came in.
     #[test]
     fn message_types_are_flags_answered_in_table_order() {
         let mut s = UiScript::new().unwrap();
@@ -1299,7 +1029,6 @@ mod record_tests {
         assert!(!general.iter().any(|m| m == "SAY" || m == "LOOT"));
         assert_eq!(general.len(), 8);
         assert_eq!(s.take_chat_window_changes(), vec![0, 2]);
-        // A host-loaded set is normalised the same way.
         s.set_chat_window_looks([(
             4,
             ChatWindowLook {
@@ -1313,9 +1042,6 @@ mod record_tests {
         );
     }
 
-    /// `AddChatWindowChannel`'s legs (chat-cache-grammar.md §5): a shortcut match stores the
-    /// DBC's own spelling with its id, a custom name stores as typed with 0, a shortcut with no
-    /// zone text yet is nil and nothing; a duplicate answers the id and stores nothing.
     #[test]
     fn channels_carry_the_zone_id_and_answer_it_on_add() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/client.rs b/crates/benilla-ui/src/script/client.rs
index bf31c492..9d85cfcc 100644
--- a/crates/benilla-ui/src/script/client.rs
+++ b/crates/benilla-ui/src/script/client.rs
@@ -1,91 +1,39 @@
-//! **Client-identity and script-evaluation verbs** — the small engine globals an addon asks for
-//! before it does anything else (1188 phase 5, prioritised by the phase 6 corpus).
-//!
-//! These are not a guess at what addons want. They are the top of the measured demand list: over a
-//! 218-addon vanilla corpus, `GetBuildInfo` is called by 69 addons and `RunScript` by 52, and both
-//! are called *at file scope* — so a missing one does not degrade an addon, it stops the addon's
-//! very first chunk with `attempt to call global … (a nil value)`. `GetBuildInfo` alone was the
-//! first error for the whole Ace/Atlas/AtlasLoot family, which is a large slice of the ecosystem.
-//!
-//! ## The host-fed pair (decision 1195)
-//!
-//! `GetRealmName` and `GetFramerate` are the next two down that list — 24 addons are stopped dead
-//! by `GetRealmName` at file scope, and it is the **top runtime wall in the corpus** after the
-//! dialect gap. Both read a slot the app pushes, the same shape as the zone-text family: the
-//! engine owns the verb, the host owns the fact.
-//!
-//! `GetRealmName` returning `""` before a realm is known is deliberate and is what the reference
-//! does at the glue screen. An addon keys its saved variables on it (`db[GetRealmName()]`), so
-//! answering `nil` would make that a `table index is nil` error one call deeper — the failure mode
-//! we have been paying for all arc.
+//! The client-identity and script verbs: build, locale, realm, bind location and framerate, with
+//! `RunScript` and `FrameXML_Debug`. The realm, bind location and framerate read slots the app
+//! pushes.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The 1.12.1 client's own build identity, read out of `WoW.exe`'s string table rather than
-/// remembered: `5875` and `1.12.1` sit adjacent in the binary, and `Sep 19 2006` is its only
-/// build-date string.
-///
-/// **Hardcoding is the faithful answer here, not a shortcut.** benilla targets exactly 1.12.1
-/// (decision 1188), so these are constants of the target, not of our build — an addon asking
-/// `GetBuildInfo()` is asking "which client am I on", and the honest answer is the one we
-/// implement the API of. Our *own* build stamp is a different question with a different verb
-/// ([`crate::script`] has no binding for it, and the reference has none either).
+/// The 1.12.1 client's build identity, as the strings in its binary spell it.
 const VERSION: &str = "1.12.1";
 const BUILD: &str = "5875";
 const BUILD_DATE: &str = "Sep 19 2006";
-// There was a `TOC_VERSION = 11200` here, and `GetBuildInfo` pushed it as a fourth value. The
-// in-game registrar pushes three (decision 1842); the interface number is a later expansion's
-// return, and `benilla.toc`'s own `## Interface` line is where that number belongs.
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `GetLocale()` -> one string, and `IsMacClient()` -> nil, both ARITY-EXACT in the reference's
-    // own shape table (`re/audit/binding-shapes.tsv`: `GetLocale 0x46ce40`/`0x48d8b0` is
-    // `0 -> 1 (string?)`, `IsMacClient 0x48c980` is `0 -> 1 (nil)`, both `exact`/`agree`).
-    //
-    // **`IsMacClient` answering nil is the whole verb, not a placeholder.** The table records the
-    // return KIND as `(nil)` — this binding pushes nil on the PC build the reference was carved
-    // from, and there is nothing else for it to say. FrameXML branches on it for Mac-only key
-    // labels; nil takes the PC arm, which is the arm this client wants.
-    //
-    // `GetLocale` is the two-registration case the shape gate warns about (1843): a glue copy and
-    // an in-game copy, same shape. Ours answers the one locale this client ships against — the
-    // enUS `GlobalStrings.lua` the manifest loads and 1804's reference defaults are read from.
-    // Decision 1880.
+    // `GetLocale()` (glue `0x46ce40`, in-game `0x48d8b0`) returns one string, `enUS`, as benilla
+    // is enUS-only. `IsMacClient()` (`0x48c980`) returns one nil, the PC build's answer, which
+    // takes FrameXML's PC key-label arm.
     g.set(
         "GetLocale",
         lua.create_function(|lua, ()| lua.create_string("enUS"))?,
     )?;
     g.set("IsMacClient", lua.create_function(|_, ()| Ok(Value::Nil))?)?;
 
-    // **`FrameXML_Debug([v])` — the XML loader's own trace switch, get-or-set** (decision 2160,
-    // wow-re `ui/scratch/framexml-debug-trace-flag.md`). `0x488440` reads the global `[0xceea30]`
-    // through `0x6edb40`, and:
-    //
-    // - a **Lua-truthy** argument takes the SET arm (`0x48845d je` after `lua_toboolean 0x6f34d0`)
-    //   — so `FrameXML_Debug(0)` genuinely disables it rather than being a masked no-op, because
-    //   the NUMBER zero is truthy in Lua; only `nil`/`false` are not;
-    // - the stored value is `lua_tonumber` truncated **toward zero** (`0x40a2b0`), so `1.9` is 1
-    //   and a non-numeric string is 0, which is 5.0's `tonumber` coercion;
-    // - an absent, nil or false argument is a pure GET and leaves the flag alone;
-    // - it always returns ONE number — the flag's value *after* the call
-    //   (`re/audit/binding-shapes.tsv`: `argc 1 exact, returns 1, (number), agree`).
-    //
-    // The reference ships a call to it commented out in its own `BasicControls.xml:20`; the
-    // corpus's consumer is `ImprovedErrorFrame`, which drives it off a saved `XMLDebug` CVar at
-    // its OnLoad and died on the missing global. What it gates is
-    // [`crate::loader::LoadReport::traces`].
+    // `FrameXML_Debug([v])` (`0x488440`): get-or-set of the XML loader's trace flag `[0xceea30]`,
+    // which gates `crate::loader::LoadReport::traces`. A Lua-truthy argument sets it, truncated
+    // toward zero (`0x40a2b0`), so `FrameXML_Debug(0)` clears it; nil or false only reads. It
+    // returns the flag after the call.
     g.set(
         "FrameXML_Debug",
         lua.create_function(|lua, v: Value| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let truthy = !matches!(v, Value::Nil | Value::Boolean(false));
             if truthy {
-                // `lua_tonumber`'s coercion, then truncate toward zero. Anything that will not
-                // coerce is 0 — the same answer `0x6f3620` gives for a non-numeric argument.
+                // A value that will not coerce is 0, as `lua_tonumber` (`0x6f3620`) answers.
                 let n = lua.coerce_number(v)?.unwrap_or(0.0);
                 model.framexml_debug.set(n.trunc() as i32);
             }
@@ -93,7 +41,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // version, build, date — three, and no fourth (decision 1842)
+    // Version, build and date, and no fourth value (the TOC number is a later expansion's): the
+    // in-game `GetBuildInfo` (`0x4884a0`) pushes three strings, the glue one (`0x46cd70`) five.
     g.set(
         "GetBuildInfo",
         lua.create_function(|lua, ()| {
@@ -101,55 +50,26 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::String(lua.create_string(VERSION)?),
                 Value::String(lua.create_string(BUILD)?),
                 Value::String(lua.create_string(BUILD_DATE)?),
-                // **THREE, not four.** The reference's in-game `GetBuildInfo 0x4884a0` pushes
-                // `(string, string, string)`; the interface/TOC number is a later-expansion return
-                // and 1.12 has no fourth value here. (Its GLUE twin `0x46cd70` pushes five — the
-                // same name with a different shape per registrar table, which is why 1842's gate
-                // keys on the table and not the name.) Decision 1842.
             ]))
         })?,
     )?;
 
-    // `RunScript(text)` — compile and run a chunk in the shared global state.
-    //
-    // `RunScript 0x48b980` (pair `0x83e288`, name `0x83ea60`) is how a macro body, a `/script`
-    // slash command and every addon's "evaluate this snippet" helper reach Lua. It inherits the
-    // same sandbox as our chunk loader: there is no `setfenv` here and none in the reference
-    // either — a script runs with full API access.
-    //
-    // Read end to end, its contract is four facts, and three of them were wrong here (2136's
-    // "left open", closed at the bytes):
-    //
-    // **1 · The chunk name is the SOURCE ITSELF, verbatim.** `0x48b9c7 mov edx,eax` and
-    // `0x48b9c9 mov ecx,eax` hand `lua_tostring 0x6f3690`'s one return to
-    // `0x704cd0 FrameScript_Execute(code, chunkname)` as BOTH arguments. `0x704cd0` strlens the
-    // code (`0x704cd7`) and passes the name straight through `FS_DoBuffer 0x704ae0`
-    // (`0x704b06 push ecx`, the fourth argument of `luaL_loadbuffer 0x6f5690` at `0x704b0c`)
-    // untouched. No `=`, no `@` — so `luaO_chunkid 0x6f5c40` renders it by its third rule,
-    // `[string "…"]`, exactly as `loadstring`'s default source-name does (2136 §4). `=[RunScript]`
-    // was a placeholder that rendered plausibly; `=` is chunkid's *print-verbatim* marker and
-    // `[RunScript]` is not a literal the image contains.
-    //
-    // **2 · A bad argument is a SILENT NO-OP, not a raise.** `0x48b988 call 0x6f3510`
-    // (`lua_isstring` — tag-based, so a *number* passes) failing takes `0x48b98f je` straight to
-    // `0x48b9f3 xor eax,eax; ret`. So does a NULL from `lua_tostring` (`0x48b99f`) and an EMPTY
-    // string (`0x48b9a1 cmp byte ptr [eax],0`). There is no `luaL_error 0x6f4940` anywhere in the
-    // function — `RunScript(nil)` does nothing at all.
-    //
-    // **3 · An error does NOT reach the caller.** `0x704ae0` pushes the registered error handler
-    // from the registry first (`0x704afe`, `[0x8722c8]` at `LUA_REGISTRYINDEX 0xffffd8f0`) and
-    // runs the chunk as `lua_pcall(L, 0, 0, -2)` (`0x704b68`); a *compile* failure takes the other
-    // leg and pcalls that same handler with the message (`0x704b42`). Either way the raise is
-    // consumed, the red line is the handler's doing, and the caller's next statement runs. Raising
-    // here made one bad `RunScript` abort whatever ran it — a macro could take FrameXML down with
-    // it.
-    //
-    // **4 · It answers zero values on every path** (`xor eax,eax` at both exits).
+    // `RunScript(text)` (`0x48b980`) runs a chunk in the shared global state with full API
+    // access, no `setfenv`. Its contract:
+    // 1. The chunk name is the source itself: the one `lua_tostring` result is passed as both
+    //    code and name to `FrameScript_Execute` (`0x704cd0`), so an error renders
+    //    `[string "…"]`, as `loadstring`'s default does.
+    // 2. An argument that is neither a string nor a number, or is empty, is a silent no-op, never
+    //    a raise (`0x48b98f`, `0x48b99f`, `0x48b9a1`); `lua_isstring` (`0x6f3510`) passes a number.
+    // 3. An error never reaches the caller: `0x704ae0` runs the chunk under `lua_pcall` with the
+    //    registered error handler (`0x704b68`), and a compile failure goes to the same handler
+    //    (`0x704b42`).
+    // 4. It returns zero values on every path.
     g.set(
         "RunScript",
         lua.create_function(|lua, text: Value| {
-            // `lua_isstring` + `lua_tostring`, in one: strings and numbers coerce, everything
-            // else is `None` — and `None` is the silent return, per fact 2.
+            // `lua_isstring` and `lua_tostring` in one: strings and numbers coerce, anything else
+            // is the silent return (2).
             let Some(s) = lua.coerce_string(text)? else {
                 return Ok(());
             };
@@ -157,8 +77,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             if raw.is_empty() {
                 return Ok(());
             }
-            // The name is the source bytes as given. Same rule as `loadstring`'s default
-            // (`stdlib::loadstring`), and for the same reason: the image passes one pointer twice.
+            // The chunk name is the source bytes as given (1).
             let name = String::from_utf8_lossy(&raw).into_owned();
             if let Err(e) = lua
                 .load(&*raw)
@@ -174,11 +93,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetRealmName()` — the realm this session is on, as the realm list spells it.
-    //
-    // The corpus's most-wanted engine verb after the dialect fix: 24 addons stop on it, and they
-    // stop *at file scope*, because the idiom is `MyAddonDB[GetRealmName()] = …` in a chunk's
-    // opening lines. `""` until the app pushes one (the glue screen's own answer), never `nil`.
+    // `GetRealmName()`: the realm as the realm list spells it; `""` until the app pushes one, the
+    // glue screen's answer, never nil, as addons index saved variables with it at file scope.
     g.set(
         "GetRealmName",
         lua.create_function(|lua, ()| {
@@ -187,15 +103,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `RequestTimePlayed()` — ask the server for /played, answered by `TIME_PLAYED_MSG`.
-    //
-    // **The request and the answer are two halves and only both are worth having.** The binding
-    // queues a `CMSG_PLAYED_TIME` the app drains; the app fires `TIME_PLAYED_MSG(total, level)`
-    // when `SMSG_PLAYED_TIME` lands. Shipping only this half would be 1203 exactly: `QuestHistory`
-    // calls it and then waits on an event that never comes, which is quieter and worse than the
-    // `attempt to call global` it gets today.
-    //
-    // It returns nothing — the answer arrives as an event, never as a return value.
+    // `RequestTimePlayed()` queues a `CMSG_PLAYED_TIME` and returns nothing; the answer is the
+    // `TIME_PLAYED_MSG(total, level)` the app fires when `SMSG_PLAYED_TIME` lands.
     g.set(
         "RequestTimePlayed",
         lua.create_function(|lua, ()| {
@@ -206,18 +115,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetBindLocation()` — the hearthstone's bind location NAME, as the reference's own hearth
-    // confirmation prints it (`StaticPopup.lua:1742` formats it straight into the dialog text).
-    //
-    // Three corpus addons read it, in three separate files: FuBar_TransporterFu
-    // (`TransporterFu.lua:456`), Necrosis (`Necrosis.lua:1089`) and _LazyPig (`LazyPig.lua:623`).
-    //
-    // **`""` until the app pushes one, never nil — the same choice `GetRealmName` above makes, for
-    // the same reason.** Necrosis CONCATENATES the result (`..GetBindLocation()`), so a nil is a
-    // raise rather than a blank; the reference holds a string buffer that is empty before
-    // `SMSG_BINDPOINTUPDATE` lands, and no logged-in character is ever without a bind point, so the
-    // empty window is ours alone. Conflating "not yet known" with "bound nowhere" is the price, and
-    // it is the price the neighbouring verb already pays deliberately.
+    // `GetBindLocation()`: the hearthstone's bind location name, which the instance-boot dialog
+    // formats into its text (`StaticPopup.lua:1742`). `""` until `SMSG_BINDPOINTUPDATE` lands, as
+    // the reference's empty buffer, never nil, since addons concatenate it.
     g.set(
         "GetBindLocation",
         lua.create_function(|lua, ()| {
@@ -226,12 +126,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetFramerate()` — frames per second, as a number.
-    //
-    // 71 addons in the corpus call it; every performance readout on the ecosystem's FuBar/Titan
-    // panels is this one verb. The app pushes a smoothed value each tick
-    // ([`super::UiScript::set_framerate`]); 0 before the first push, which is what an addon's
-    // `format("%.1f", GetFramerate())` needs to not error.
+    // `GetFramerate()`: frames per second, a smoothed value the app pushes each tick; 0, a number,
+    // before the first push.
     g.set(
         "GetFramerate",
         lua.create_function(|lua, ()| {
@@ -244,18 +140,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 }
 
 impl super::UiScript {
-    /// Drain the `RequestTimePlayed()` asks queued since the last call — each one is a
-    /// `CMSG_PLAYED_TIME`. [`super::UiScript::take_pvp_toggles`]'s shape, and a count for the same
-    /// reason: the request packet is empty, so nothing distinguishes two asks but their number.
+    /// Drain the `RequestTimePlayed()` asks, each a `CMSG_PLAYED_TIME`: a count, as the request
+    /// body is empty.
     pub fn take_played_time_asks(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().played_time_asks)
     }
 
-    /// Push the hearthstone bind location's name — the host's half of `GetBindLocation`.
-    ///
-    /// The app resolves `SMSG_BINDPOINTUPDATE`'s AreaTable id through the same catalog the
-    /// hearthstone's `$z` token already goes through, so the two can never disagree about where the
-    /// player is bound. Idempotent; the empty string means the packet has not landed yet.
+    /// Push the bind location's name, resolved from `SMSG_BINDPOINTUPDATE`'s AreaTable id through
+    /// the catalog the hearthstone's `$z` uses, so the two agree; empty until the packet lands.
     pub fn set_bind_location(&mut self, area_name: &str) {
         let mut model = self.model_mut();
         if model.bind_location != area_name {
@@ -263,25 +155,10 @@ impl super::UiScript {
         }
     }
 
-    /// Push the realm name — the host's half of `GetRealmName` (decision 1195).
-    ///
-    /// Set at world entry from the realm the session actually connected to. Idempotent, and the
-    /// empty string is a legitimate value (no realm yet), not a "clear".
-    /// Seed the **local player record** — the reference's `0xc27d80`, copied from the char-enum
-    /// row at the character-select Enter World commit (decisions 2261/2263, and see
-    /// [`super::PlayerRecord`] for the bytes and the four verbs that read it).
-    ///
-    /// Called from the world-entry UI load beside [`Self::set_realm_name`], and for the same
-    /// reason 1195 put the realm there: the values have to be in the VM before a single addon file
-    /// runs, because `local currentPlayer = UnitName("player")` at file scope is the corpus idiom.
-    /// The reference has them a whole login earlier still.
-    ///
-    /// **A record with no name is refused, not stored.** The only unset state is "no Enter World
-    /// has been committed in this process"; once the record holds a character, nothing in the
-    /// reference's image ever empties it again, so a caller with nothing to say must leave the
-    /// last answer standing rather than blank it. The write is whole-record because the
-    /// reference's is one `rep movsd`: these four fields describe one character and can never
-    /// legitimately be seeded from two.
+    /// Seed the local player record (the reference's `0xc27d80`, [`super::PlayerRecord`]) from the
+    /// char-enum row at Enter World, before any addon file runs, as `UnitName("player")` at file
+    /// scope is common. A record with no name is refused: nothing empties the reference's record
+    /// once it holds a character, so the last one stands.
     pub fn set_player_record(&mut self, record: super::PlayerRecord) {
         if record.name.is_empty() {
             return;
@@ -292,34 +169,21 @@ impl super::UiScript {
         }
     }
 
+    /// Push the realm name, set at world entry from the realm the session connected to; the empty
+    /// string means no realm yet, not a clear.
     pub fn set_realm_name(&mut self, realm: &str) {
         {
             let mut model = self.model_mut();
             if model.realm_name != realm {
                 model.realm_name = realm.to_string();
             }
-            // The `realmName` CVar is the SAME fact, and it is set here so it cannot drift from
-            // `GetRealmName()`. It is a real 1.12 CVar (`0x83f2d0`, persisted — the client builds
-            // its SavedVariables path from it, wow-re `savedvariables-protocol.md`), and it had no
-            // value at all here: `Ace/AceState.lua:27` is
-            // `ace.trim(GetCVar("realmName"))` inside `SetGameState`, which EVERY Ace addon runs at
-            // PLAYER_ENTERING_WORLD, so the nil became `gsub(nil, ...)` and took the family down.
-            //
-            // Through the **engine-write** path, not a bare slot poke. `realmName` is a persisted
-            // CVar — its whole documented job is to be the last realm connected to — and a slot
-            // written in place never reaches `cvar_changes`, so the host never hears it and never
-            // dirties the config file. The value was therefore correct for exactly as long as the
-            // process lived and absent from `config.toml` forever, which is the one thing a
-            // persisted CVar must not be. `set_from_engine` is the same silent-on-unknown-name
-            // write (a bare test VM registers nothing) and additionally queues the change.
+            // The persisted `realmName` CVar (`0x83f2d0`) is the same fact, set here so it cannot
+            // drift from `GetRealmName()`; the engine write queues the change, so it is saved.
             super::cvars::set_from_engine(&mut model, "realmName", realm.to_string());
         }
     }
 
-    /// Push the current framerate — the host's half of `GetFramerate`.
-    ///
-    /// Pushed per tick from the app's own frame clock rather than computed here: this crate has no
-    /// clock, and a number an addon polls every `OnUpdate` should not be re-derived per call.
+    /// Push the current framerate, from the app's frame clock each tick; this crate has no clock.
     pub fn set_framerate(&mut self, fps: f64) {
         self.model_mut().framerate = fps;
     }
@@ -329,21 +193,8 @@ impl super::UiScript {
 mod tests {
     use crate::script::UiScript;
 
-    /// `GetBuildInfo` answers as the 1.12.1 client: **three strings, and no fourth value.**
-    ///
-    /// This used to assert four and explain the fourth as the `tocversion` an addon compares
-    /// against its own `## Interface` — which is a TBC-and-later idiom. The in-game registrar
-    /// `0x4884a0` pushes `(string, string, string)` and nothing else (decision 1842); the
-    /// interface number arrives in a later expansion.
-    ///
-    /// The corpus agrees, and it is worth the count: **458 sites** write
-    /// `local version = GetBuildInfo()` and take one value. **Four** destructure a fourth — and on
-    /// the real 1.12 client those four read `nil`, which is what their authors shipped against.
-    /// Handing them `11200` was benilla being more generous than the client, which is the superset
-    /// 1189 exists to stop.
-    ///
-    /// **The same name has a different shape in the glue registrar** (`0x46cd70`, five strings).
-    /// This VM is the in-game one. That pair is why 1842's gate keys on the table, not the name.
+    /// Three strings and no fourth, as the in-game registrar pushes (`0x4884a0`); this VM is the
+    /// in-game one, not the glue (`0x46cd70`, five).
     #[test]
     fn get_build_info_answers_as_the_1_12_1_client() {
         let s = UiScript::new().unwrap();
@@ -358,9 +209,7 @@ mod tests {
         );
     }
 
-    /// `GetRealmName` answers `""` before the host pushes one — **never `nil`**, because the
-    /// corpus idiom is `MyAddonDB[GetRealmName()] = …` at file scope and a nil index errors one
-    /// call deeper, far from the cause.
+    /// Never nil: addons index with it at file scope, and a nil index errors far from the cause.
     #[test]
     fn get_realm_name_is_empty_before_it_is_known_and_the_host_pushes_it() {
         let mut s = UiScript::new().unwrap();
@@ -377,8 +226,6 @@ mod tests {
         );
     }
 
-    /// `GetFramerate` is a number from the first call, so `format("%.1f", GetFramerate())` in an
-    /// addon's `OnUpdate` cannot error before the app has pushed a frame.
     #[test]
     fn get_framerate_is_a_number_before_the_first_push() {
         let mut s = UiScript::new().unwrap();
@@ -396,16 +243,8 @@ mod tests {
         );
     }
 
-    /// `RunScript` runs its text in the shared global state, and a failure is **recorded, not
-    /// raised** — `0x704ae0` runs the chunk under `lua_pcall(L, 0, 0, -2)` with the registry's
-    /// error handler, so the raise never reaches the caller. (The full contract, and the three
-    /// silent legs, are in `script::tests::stdlib`.)
-    ///
-    /// This test used to assert the opposite, on the reasoning that "a silent nil is a broken
-    /// macro that looks fine". The reasoning was sound and the premise was not: the reference is
-    /// not silent, it hands the message to the error handler and keeps going. Failing loudly *at
-    /// the caller* is the part it does not do, and doing it meant one bad macro could abort the
-    /// FrameXML function that ran it.
+    /// A failure is recorded, not raised: `0x704ae0` runs the chunk under `lua_pcall(L, 0, 0, -2)`
+    /// with the registry's error handler.
     #[test]
     fn run_script_evaluates_in_the_shared_state_and_reports_without_raising() {
         let mut s = UiScript::new().unwrap();
@@ -421,8 +260,8 @@ mod tests {
         );
     }
 
-    /// `GetLocale` answers one string and `IsMacClient` answers nil — the reference's own shapes
-    /// (`binding-shapes.tsv`, both `exact`/`agree`), and the arity is the half a caller branches on.
+    /// The reference's arities: `GetLocale` (`0x48d8b0`) one string, `IsMacClient` (`0x48c980`)
+    /// one nil.
     #[test]
     fn the_client_identity_pair_answers_its_reference_arity() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/clip.rs b/crates/benilla-ui/src/script/clip.rs
index 11b1a945..9284fc9f 100644
--- a/crates/benilla-ui/src/script/clip.rs
+++ b/crates/benilla-ui/src/script/clip.rs
@@ -1,6 +1,4 @@
-//! The ScrollFrame clip (decision 0112 §4/§5) — shared by [`UiScript::extract`](super::UiScript::extract)
-//! and [`pointer`](super::pointer)'s hit-test. Both need the same answer to "which ScrollFrame rects
-//! does this frame draw/hit within?", so the walk lives here once and mod.rs re-exports it.
+//! The ScrollFrame clip, shared by `extract` and the pointer hit-test so drawing and hitting agree.
 
 use std::collections::HashMap;
 
@@ -10,11 +8,8 @@ use crate::widget::{FrameKind, KindState};
 use super::model::Model;
 use super::FrameHandle;
 
-/// Every live ScrollFrame with a resolved rect and a live child, as `child handle → the
-/// scrollframe's resolved rect`. The map [`effective_clip`] walks against; built fresh per
-/// `extract`/`hit_test` call (cheap — one pass over the arena, same cost class as
-/// [`crate::order::traversal`]), never cached, so a `SetScrollChild`/`SetVerticalScroll` between
-/// calls is picked up with no invalidation to track.
+/// Scroll child → its ScrollFrame's resolved rect, for every live ScrollFrame with a rect and a
+/// live child. Rebuilt per call and never cached, so no scroll change needs invalidating.
 pub(super) fn scroll_clip_sources(model: &Model) -> HashMap<FrameHandle, Rect> {
     let mut sources = HashMap::new();
     for (h, frame) in model.arena.iter_frames() {
@@ -35,13 +30,8 @@ pub(super) fn scroll_clip_sources(model: &Model) -> HashMap<FrameHandle, Rect> {
     sources
 }
 
-/// The effective clip a frame `h` draws/hits within: intersecting the resolved rect of every
-/// ScrollFrame whose registered child is `h` itself **or** an ancestor of `h` (walking `h` up
-/// through its parent chain) — so both the scroll child's own quads and every descendant's quads
-/// (a grandchild region, a button nested arbitrarily deep) are clipped, and nested ScrollFrames
-/// (an inner ScrollFrame's child living inside an outer one's) intersect their rects rather than
-/// the inner overriding the outer. `None` = unclipped (the common case — no ancestor is a
-/// registered scroll child).
+/// The clip `h` draws and hits within: the intersection of every ScrollFrame rect whose scroll
+/// child is `h` or an ancestor of it, so nested ScrollFrames intersect; `None` is unclipped.
 pub(super) fn effective_clip(
     model: &Model,
     sources: &HashMap<FrameHandle, Rect>,
@@ -63,10 +53,8 @@ pub(super) fn effective_clip(
     clip
 }
 
-/// Axis-aligned rect intersection (y-up: `top`/`right` shrink to the tighter bound, `bottom`/`left`
-/// grow to the tighter bound). Two ScrollFrame clips that don't overlap collapse to an inverted
-/// (empty) rect — `point_in_rect` ([`pointer`](super::pointer)) then never hits it and the CPU clip
-/// in `ui_pass` already treats a degenerate intersection as "nothing to draw" (see its `clip_quad`).
+/// Rect intersection, y-up. Disjoint rects give an inverted rect, which the pointer never hits
+/// and the app's `clip_quad` draws nothing in.
 pub(super) fn intersect_rect(a: Rect, b: Rect) -> Rect {
     Rect::new(
         a.bottom.max(b.bottom),
diff --git a/crates/benilla-ui/src/script/colorselect.rs b/crates/benilla-ui/src/script/colorselect.rs
index 8bca2606..8217a82b 100644
--- a/crates/benilla-ui/src/script/colorselect.rs
+++ b/crates/benilla-ui/src/script/colorselect.rs
@@ -1,55 +1,10 @@
-//! The `ColorSelect` method surface — the `CSimpleColorSelect` widget behavior over the kind tag
-//! (factory `0x6eef90`; LoadXML `0x78b3f0`, script-map `0x78b4f0`, RF-28
-//! `rf28-typed-widget-loadxml.md`). The widget holds one colour and fires `OnColorSelect` (its own
-//! script slot, `+0x338`) when that colour is set.
-//!
-//! **Why this is engine-side and not four lines of Lua on `ColorPickerFrame`.** The corpus creates
-//! its own: `TipBuddy.xml` declares two `<ColorSelect>` frames (`TBColorPickerFrame`,
-//! `TBColorPickerFrame_Text`), each with its own `<OnColorSelect>` handler, and drives them with
-//! `SetColorRGB`/`GetColorRGB`. A method table hung on the one frame `assets/ui` ships would leave
-//! those two with a widget that has no methods — the "privileged built-in" failure the `.toc`
-//! header names. So it lives with `Slider`/`StatusBar`, in the per-kind dispatcher.
-//!
-//! **The colour law is byte-verified, and it is not what it looks like.** This module was first
-//! written against the obvious model — store three RGB bytes, hand them back — and a §5 cross-check
-//! dispatched into wow-re for exactly this question corrected it
-//! (`system/ui/scratch/colorselect-color-law.md`, 2026-08-11: three independent derivations plus an
-//! emulated Unicorn oracle over the four helpers' own bytes). Two corrections, both load-bearing:
-//!
-//! 1. **The state is HSV `f32`, not RGB** — see [`ColorSelectState`] for the members and why.
-//! 2. **The round trip is not the identity.** Inbound and outbound use *different* quantizers
-//!    (round-half-up vs floor), so `SetColorRGB` → `GetColorRGB` returns a channel one step low on
-//!    **9.7527 % of all 256³ reachable colours** — and, because the map is idempotent-free, the
-//!    FrameXML idiom `r,g,b = f:GetColorRGB() … f:SetColorRGB(r,g,b)` **ratchets** a channel
-//!    downward one step per cycle. `SetColorRGB(0, 1, 1)` fires `OnColorSelect(0, 254/255, 1)`.
-//!    Every Ace2/Dewdrop colour option is that idiom, once per open-and-accept, so this is visible
-//!    behaviour, not a curiosity — it is transcribed because it is what the client computes, and
-//!    [`ColorSelectState`]'s docs record the one-line change that would undo it if it ever must go.
-//!
-//! **`SetColorRGB` fires `OnColorSelect`, synchronously, on every call.** VERIFIED at the bytes:
-//! `0x78ed01 call 0x78bae0` is a plain fall-through of the last basic block, and inside it the only
-//! conditional (`0x78bafd`) tests whether a handler is *bound*. There is deliberately **no
-//! change-gate** — the contrast with [`crate::widget::SliderState::store_value`] is real and was
-//! verified the other way in the same pass (`CSimpleSlider::SetValue 0x789930` skips on equal at
-//! `0x789a16`): two sibling widgets in one band, opposite gating. It matters here because a caller
-//! re-setting the colour it already holds still expects its `func` to run — which is exactly how a
-//! Dewdrop colour row opens, and how the reference's own `ColorPickerFrame.xml` paints its preview
-//! swatch (nothing else ever writes it).
-//!
-//! **The four texture accessors are carried** (`SetColorWheelTexture` `0x78de90` /
-//! `SetColorWheelThumbTexture` `0x78e160` / `SetColorValueTexture` `0x78e450` /
-//! `SetColorValueThumbTexture` `0x78e720`, plus the getters `0x78dd80`/`0x78e070`). They had zero
-//! callers in the 218-addon corpus and waited for one under decision 1195; the customer that
-//! arrived is our own `ColorPickerFrame.xml`, whose four elements the XML loader installs through
-//! exactly these — two of them with **no file at all**, because the disc and the strip are pixels
-//! the client computes and the app renderer now computes too (decision 1592, and wow-re
-//! `system/ui/scratch/colorselect-drawn-appearance.md` for what it draws).
-//!
-//! **NOT carried, still waiting for a customer (decision 1195):** `SetColorHSV`/`GetColorHSV`
-//! (`0x78e920`/`0x78ea00`) — zero corpus callers, though the state they would read and write is
-//! now the right shape for them, and [`ColorSelectState::set_hsv`] is already the store they'd
-//! use (three *raw* `f32` — no clamp, no quantize, zero `fcom` in its body), because the drag path
-//! needs exactly that.
+//! The `ColorSelect` methods: the `CSimpleColorSelect` widget (factory `0x6eef90`, XML load
+//! `0x78b3f0`), one colour held as HSV floats. `SetColorRGB` fires `OnColorSelect` (script map
+//! `0x78b4f0`, slot `+0x338`) on every call: `0x78ed01` calls `0x78bae0`, whose only test
+//! (`0x78bafd`) is for a bound handler, while `CSimpleSlider::SetValue` (`0x789930`) skips an equal
+//! value. The RGB round trip loses a step on 9.75 % of colours, as in the reference: in and out use
+//! different quantizers (round-half-up, then floor), so reading back and setting ratchets a channel
+//! down; see [`ColorSelectState`].
 
 use mlua::{Lua, Table, Value};
 
@@ -61,13 +16,11 @@ use crate::layout::Rect;
 use crate::order::DrawLayer;
 use crate::widget::{ColorSelectState, FrameHandle, KindState, RegionHandle, RegionKind};
 
-/// Registry key of the ColorSelect method table (the MAXCSTACK discipline: Lua-side root, named
-/// key).
+/// Registry key of the ColorSelect method table (the MAXCSTACK discipline: a Lua-side root).
 pub(super) const REG_COLORSELECT_METHODS: &str = "__benilla_colorselect_methods";
 
-/// Run `f` over a frame's ColorSelect state under one short write borrow. Errors if `this` is not a
-/// live ColorSelect (unreachable through the kind dispatcher, but the method table is a plain Lua
-/// value — a caller could fish it out and misapply it).
+/// Run `f` over a frame's ColorSelect state under one short write borrow; errors if `this` is not
+/// a live ColorSelect, as the method table is a plain Lua value a caller can misapply.
 fn with_colorselect<T>(
     lua: &Lua,
     this: &Table,
@@ -85,9 +38,8 @@ fn with_colorselect<T>(
     }
 }
 
-/// One of the widget's four texture sub-objects. The wheel and the strip are the two the press
-/// handler hit-tests (`[+0x318]+0x24` and `[+0x320]+0x24`, wow-re `colorselect-color-law.md` §5);
-/// the two thumbs are pure output, positioned from the HSV at extract.
+/// One of the widget's four texture sub-objects: the press handler (`0x78bf10`) hit-tests the
+/// wheel (`+0x318`) and the strip (`+0x320`); the thumbs are output only, placed at extract.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum Slot {
     Wheel,
@@ -116,9 +68,8 @@ impl Slot {
         *slot = Some(rh);
     }
 
-    /// The layer a slot's region is born on — VERIFIED, not guessed: wow-re
-    /// `colorselect-drawn-appearance.md` reads the wheel bound at layer 2 (ARTWORK) through
-    /// `0x77fd10`, with the two markers on OVERLAY above the art they ride.
+    /// The layer a slot's region is born on: ARTWORK for the art (the wheel's layer 2, through
+    /// `0x77fd10`), OVERLAY for the two markers above it.
     fn layer(self) -> DrawLayer {
         match self {
             Slot::Wheel | Slot::ValueStrip => DrawLayer::Artwork,
@@ -127,8 +78,7 @@ impl Slot {
     }
 }
 
-/// Get-or-create one slot's texture region; `layer` re-layers an existing one. Returns the region
-/// id (for wrapper lookup). The Slider's `ensure_thumb` is the same function one slot wider.
+/// Get-or-create one slot's texture region, `layer` re-layering an existing one; returns its id.
 fn ensure_slot(lua: &Lua, this: &Table, slot: Slot, layer: Option<DrawLayer>) -> mlua::Result<u32> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -156,7 +106,7 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot, layer: Option<DrawLayer>) ->
                 .create_region(h, RegionKind::Texture, layer.unwrap_or(slot.layer()), 0)
                 .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
             model.region_data.insert(rh, RegionData::default());
-            model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+            model.touch_layout(); // a region entered the layout gate's read set
             if let Some(frame) = model.arena.frame_mut(h) {
                 if let KindState::ColorSelect(s) = &mut frame.kind_state {
                     slot.set(s, rh);
@@ -168,10 +118,9 @@ fn ensure_slot(lua: &Lua, this: &Table, slot: Slot, layer: Option<DrawLayer>) ->
     Ok(model.region_id(rh))
 }
 
-/// `Set<Slot>Texture([path [, drawLayer]] | r, g, b [, a])`, the Slider's `SetThumbTexture` two-form
-/// plus a **third**: called with nothing at all it just creates the region. That empty form is not a
-/// convenience — it is the only one the two file-less elements can use, and it is what
-/// `<ColorWheelTexture/>` means. A slot left file-less is where the app renderer paints.
+/// `Set<Slot>Texture([path [, drawLayer]] | r, g, b [, a])`, plus an empty form that only creates
+/// the region: what `<ColorWheelTexture/>` means. A file-less slot is where the app renderer paints
+/// the disc and strip the reference computes (`0x78b580`, `0x78b8a0`).
 fn install_slot_texture(
     lua: &Lua,
     m: &Table,
@@ -235,7 +184,6 @@ fn install_slot_texture(
     Ok(())
 }
 
-/// A Lua number argument as `f32`, 0 for anything else — the Slider's own colour-form helper.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -249,16 +197,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     m.set(
         "SetColorRGB",
-        // Shape C on r, g, b (`ColorSelect:SetColorRGB 0x78eae0`, `2=C 3=C 4=C 5=B`, wow-re
-        // `numeric-arg-coercion-law.md`): bare `lua_tonumber`, nil → 0.0, no raise.
+        // Shape C on r, g, b (`ColorSelect:SetColorRGB 0x78eae0`, `2=C 3=C 4=C 5=B`).
         lua.create_function(|lua, (this, r, g, b): (Table, Value, Value, Value)| {
             let (r, g, b) = (
                 crate::script::object::as_f64(&r),
                 crate::script::object::as_f64(&g),
                 crate::script::object::as_f64(&b),
             );
-            // Store through the client's quantize, then fire with what the widget now *holds* —
-            // the round-tripped values, identical to the next GetColorRGB, not the raw arguments.
+            // Store through the client's quantizer, then fire with what the widget now holds: the
+            // round-tripped values, identical to the next `GetColorRGB`, not the raw arguments.
             let (qr, qg, qb) = with_colorselect(lua, &this, |s| {
                 s.set_rgb(r, g, b);
                 s.rgb_f64()
@@ -271,10 +218,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| with_colorselect(lua, &this, |s| s.rgb_f64()))?,
     )?;
 
-    // The four texture accessors (`0x78de90`/`0x78e160`/`0x78e450`/`0x78e720` and the getters
-    // `0x78dd80`/`0x78e070`). They had zero corpus callers and waited for one (decision 1195); the
-    // customer that arrived is our own `ColorPickerFrame.xml`, whose four elements the XML loader
-    // installs through exactly these.
+    // The four texture accessors (`0x78de90`, `0x78e160`, `0x78e450`, `0x78e720`; getters
+    // `0x78dd80`, `0x78e070`), through which the XML loader installs a ColorSelect's elements.
     install_slot_texture(
         lua,
         &m,
@@ -308,9 +253,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Fire `OnColorSelect(self, r, g, b)` — the widget's own script slot (`+0x338`, RF-28). Fired
-/// outside the model borrow; a handler error goes to [`Model::errors`] rather than back to the
-/// setter's caller, the same posture as the Slider's `OnValueChanged`.
+/// Fire `OnColorSelect(self, r, g, b)`; a handler error goes to [`Model::errors`], not the caller.
 fn fire_color_select(lua: &Lua, this: &Table, r: f64, g: f64, b: f64) -> mlua::Result<()> {
     let id = {
         let h = frame_handle_of(lua, this)?;
@@ -325,33 +268,26 @@ fn fire_color_select(lua: &Lua, this: &Table, r: f64, g: f64, b: f64) -> mlua::R
     ) {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
     Ok(())
 }
 
-/// The wheel's normalised coordinates for a cursor at `(x, y)`: the offset from the wheel rect's
-/// centre, scaled by its **half-extents** — so a non-square wheel normalises to a disc, not an
-/// ellipse (`0x78bdd0`..: `nx=(x−cx)/((right−left)·0.5)`, `ny=(y−cy)/((top−bottom)·0.5)`, wow-re
-/// `colorselect-color-law.md` §5). y is up, this arena's convention and the client's.
+/// The wheel's normalised coordinates for `(x, y)`: the offset from its centre over its
+/// half-extents, so a non-square wheel normalises to a disc (`0x78bdd0`); y is up, as the client's.
 fn wheel_norm(r: Rect, x: f32, y: f32) -> (f32, f32) {
     let hw = (r.right - r.left) * 0.5;
     let hh = (r.top - r.bottom) * 0.5;
     let cx = (r.left + r.right) * 0.5;
     let cy = (r.bottom + r.top) * 0.5;
-    // A degenerate rect (an unresolved region) would divide by zero; the client cannot reach that
-    // state because it only hit-tests a laid-out texture, and neither can we — but 0/0 is NaN, and
-    // NaN in the HSV would poison every colour after it.
+    // A zero-size rect gives 0, not NaN, which would poison every colour after it.
     let nx = if hw != 0.0 { (x - cx) / hw } else { 0.0 };
     let ny = if hh != 0.0 { (y - cy) / hh } else { 0.0 };
     (nx, ny)
 }
 
-/// The hue/saturation a press or drag at `(x, y)` writes, given the wheel's rect. `H` runs from
-/// `atan2(ny, nx) + π` in degrees — so the wheel's **left** edge is 0°/360° (red) and its right edge
-/// 180° (cyan) — and `S` is the radius, clamped at the rim. Raw f32 the whole way: the drag path
-/// never touches a quantizer.
+/// The hue and saturation a press or drag at `(x, y)` writes: the wheel's left edge is 0° (red)
+/// and its right 180° (cyan), `S` is the radius clamped at the rim, and nothing is quantized.
 fn wheel_hs(r: Rect, x: f32, y: f32) -> (f32, f32) {
     let (nx, ny) = wheel_norm(r, x, y);
     let radius = (nx * nx + ny * ny).sqrt();
@@ -359,9 +295,8 @@ fn wheel_hs(r: Rect, x: f32, y: f32) -> (f32, f32) {
     (hue, radius.min(1.0))
 }
 
-/// The brightness a press or drag at `y` writes, given the strip's rect: the fraction of the way up
-/// it, clamped — `V = clamp((y − bottom) / (top − bottom), 0, 1)` (`0x78beed`). x is ignored, which
-/// is why a drag that wanders sideways off the strip keeps working.
+/// The brightness a press or drag at `y` writes: the clamped fraction of the way up the strip
+/// (`0x78beed`); x is ignored, so a drag may wander sideways off it.
 fn strip_value(r: Rect, y: f32) -> f32 {
     let span = r.top - r.bottom;
     if span == 0.0 {
@@ -370,22 +305,11 @@ fn strip_value(r: Rect, y: f32) -> f32 {
     ((y - r.bottom) / span).clamp(0.0, 1.0)
 }
 
-/// The wheel thumb's rect: the marker seated at the point the current `(H, S)` *came from*. It is
-/// the inverse of [`wheel_hs`], which is the whole invariant — click a pixel, the marker lands on
-/// that pixel.
-///
-/// Byte-exact to `0x78bc20` (wow-re `colorselect-drawn-appearance.md` §4), which does
-/// `SetPoint(CENTER, wheel, CENTER, −m·cos θ, −m·sin θ)` with `θ = H·π/180` and
-/// `m = GetWidth(wheel)·0.5·S`. Its two `fchs` are the pick law's `+π` seen from the other side:
-/// drop either sign and the marker sits diametrically opposite the colour it marks.
-///
-/// **The width is used on both axes**, deliberately — the client reads `GetWidth` for the vertical
-/// offset too, while the pick law divides `y` by half-*height*. On a non-square wheel the two
-/// therefore disagree, and that asymmetry is reproduced rather than fixed. The reference's wheel is
-/// square, so it costs nothing there and would cost fidelity anywhere else.
-///
-/// `S == 0` puts it dead centre whatever the hue is, which is what makes the `-1` grey sentinel
-/// (`ColorSelectState::hsv`) harmless here: it is multiplied by a zero radius.
+/// The wheel marker's rect, seated where the current `(H, S)` came from, the inverse of
+/// [`wheel_hs`]: `0x78bc20` sets its `CENTER` at `(−m·cos θ, −m·sin θ)` from the wheel's, with
+/// `m = GetWidth(wheel)·0.5·S`, the negations being the pick's `+π`. The width serves both axes,
+/// as in the reference, though the pick divides y by half the height. `S == 0` centres it, so the
+/// `-1` grey hue sentinel is harmless.
 pub(super) fn wheel_thumb_rect(wheel: Rect, thumb_size: Option<(f32, f32)>, hsv: [f32; 3]) -> Rect {
     let (tw, th) = thumb_size.unwrap_or((0.0, 0.0));
     let cx = (wheel.left + wheel.right) * 0.5;
@@ -396,16 +320,10 @@ pub(super) fn wheel_thumb_rect(wheel: Rect, thumb_size: Option<(f32, f32)>, hsv:
     Rect::new(y - th * 0.5, x - tw * 0.5, y + th * 0.5, x + tw * 0.5)
 }
 
-/// The value thumb's rect: centred on the strip horizontally (the reference's marker is 48 wide
-/// over a 32-wide strip, so it deliberately overhangs) and seated `V` of the way up from its
-/// BOTTOM — `0x78bcf0`'s `SetPoint(CENTER, strip, BOTTOM, 0, V·GetHeight)`.
-///
-/// **The height it scales by is the WHEEL's, not the strip's** — `0x78bcf0` dereferences
-/// `[this+0x318]`, the wheel, with no null guard of its own, while anchoring to the strip. The two
-/// are both 128 tall in the reference, so it is invisible there; it is reproduced because a client
-/// that "fixed" it would place the marker somewhere the real one does not the moment an addon
-/// declares a strip of its own height. A widget with no wheel falls back to the strip, which is the
-/// nearest thing to the client's unguarded read that does not put a NaN in a rect.
+/// The value marker's rect: centred on the strip and `V` of the way up from its bottom
+/// (`0x78bcf0`), scaled by the wheel's height, not the strip's, as the reference reads
+/// `[this+0x318]`. Deviation: with no wheel it scales by the strip's, because the reference reads
+/// the missing wheel unguarded.
 pub(super) fn value_thumb_rect(
     strip: Rect,
     wheel: Option<Rect>,
@@ -419,11 +337,8 @@ pub(super) fn value_thumb_rect(
     Rect::new(y - th * 0.5, cx - tw * 0.5, y + th * 0.5, cx + tw * 0.5)
 }
 
-/// The in-flight colour drag. The client keeps **two independent flags** (`+0x314` wheel, `+0x315`
-/// strip), both set by the same press if the rects overlap at the cursor, and its cursor-position
-/// handler applies whichever are set — so this is a pair of bools, not an enum. It also explains the
-/// feel: a drag that starts on the wheel keeps writing hue and saturation no matter where the cursor
-/// wanders, because the flag, not the current position, decides.
+/// The in-flight colour drag: the reference's two independent flags (`+0x314` wheel, `+0x315`
+/// strip), both set when a press hits both; the flag, not the cursor, decides what a move writes.
 #[derive(Clone, Copy)]
 pub(crate) struct ColorDrag {
     pub(crate) frame: FrameHandle,
@@ -431,8 +346,7 @@ pub(crate) struct ColorDrag {
     strip: bool,
 }
 
-/// The two hit rects of a ColorSelect frame — its wheel region's and its value strip's, as resolved
-/// by layout. `None` for a slot with no region, which is every ColorSelect that never declared one.
+/// The laid-out rects of a ColorSelect's wheel and value strip.
 fn hit_rects(model: &Model, h: FrameHandle) -> (Option<Rect>, Option<Rect>) {
     let (wheel, strip) = match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::ColorSelect(s)) => (s.wheel, s.value_strip),
@@ -442,10 +356,8 @@ fn hit_rects(model: &Model, h: FrameHandle) -> (Option<Rect>, Option<Rect>) {
     (rect(wheel), rect(strip))
 }
 
-/// On a LeftButton press at `(x, y)` whose hit frame is `hit`: if that frame is a ColorSelect and
-/// the cursor is inside its wheel or its value strip, capture the drag and **apply it immediately**
-/// — `0x78bf10` calls the cursor-position handler through `[eax+0x3c]` before it returns, so a
-/// single click jumps the colour to the click point and fires. Returns what the caller must fire.
+/// On a LeftButton press inside a wheel or strip, capture the drag and apply it at once, as
+/// `0x78bf10` does, so a click jumps the colour; returns the id and colour the caller fires.
 pub(super) fn begin_drag(
     model: &mut Model,
     hit: Option<FrameHandle>,
@@ -467,11 +379,8 @@ pub(super) fn begin_drag(
     drag_move(model, x, y)
 }
 
-/// On a pointer move at `(x, y)` while a colour drag is captured: rewrite whichever of H/S and V the
-/// capture owns, straight into the widget's HSV floats, and hand the caller the frame id plus the
-/// colour to fire `OnColorSelect` with. Returns `Some` on **every** captured move, with no
-/// change-gate — the widget deliberately has none (`0x78bafd` tests only whether a handler is
-/// bound), which is the opposite of the Slider next door.
+/// On a pointer move during a drag, write the captured H/S and V into the widget's HSV and return
+/// the frame id and colour to fire with, on every move: there is no change gate (`0x78bafd`).
 pub(super) fn drag_move(model: &mut Model, x: f32, y: f32) -> Option<(u32, f64, f64, f64)> {
     let ColorDrag {
         frame,
@@ -510,15 +419,12 @@ pub(super) fn drag_move(model: &mut Model, x: f32, y: f32) -> Option<(u32, f64,
     Some((model.frame_id(frame), rgb.0, rgb.1, rgb.2))
 }
 
-/// Release any in-flight colour drag (LeftButton up, or the pointer leaving the window) — the
-/// widget's `0x78bf90`, which clears both flags.
+/// Release a colour drag (LeftButton up or the pointer leaving): `0x78bf90` clears both flags.
 pub(super) fn end_drag(model: &mut Model) {
     model.color_drag = None;
 }
 
-/// Fire `OnColorSelect` for a frame the pointer path just recoloured. The setter's own
-/// [`fire_color_select`] needs the caller's `this` table; the pointer has only an id, so this is the
-/// same two lines against [`event::fire_widget_handler`] directly.
+/// Fire `OnColorSelect` by frame id, for the pointer path, which has no `this` table.
 pub(super) fn fire_by_id(lua: &Lua, id: u32, r: f64, g: f64, b: f64) -> mlua::Result<()> {
     event::fire_widget_handler(
         lua,
@@ -533,8 +439,7 @@ mod tests {
     use crate::script::UiScript;
     use crate::widget::ColorSelectState;
 
-    /// A `ColorSelect` starts **white** (the ctor's `H=0, S=0, V=1`), not black. A zero-init store
-    /// would have made it black, which is the tell that the state is HSV and not RGB.
+    /// White, not black: the constructor sets `H=0, S=0, V=1`.
     #[test]
     fn a_fresh_color_select_is_white() {
         let s = UiScript::new().unwrap();
@@ -544,9 +449,7 @@ mod tests {
         assert_eq!((r, g, b), (1.0, 1.0, 1.0));
     }
 
-    /// **The round trip is not the identity, and the deviation is the client's.** `(0, 1, 1)` — cyan,
-    /// a two-channel tie at the maximum — comes back with green one step low, the exact witness
-    /// wow-re's exhaustive sweep names. Greys are its control class and never lose.
+    /// Cyan, a two-channel tie at the maximum, loses one step of green, as in the reference.
     #[test]
     fn the_round_trip_loses_exactly_one_step_on_the_witness_colour() {
         let s = UiScript::new().unwrap();
@@ -567,10 +470,7 @@ mod tests {
         }
     }
 
-    /// **And it ratchets.** The FrameXML idiom — read the colour back, hand it straight to
-    /// `SetColorRGB` — re-applies the same lossy map instead of settling. wow-re's pin: `(0, 8, 132)`
-    /// walks to `(0, 0, 132)` in eight cycles. Every Ace2/Dewdrop colour option is that idiom, once
-    /// per open-and-accept, so this is the shape of a real player-visible drift and it is deliberate.
+    /// Reading back and setting walks `(0, 8, 132)` to `(0, 0, 132)`, as in the reference.
     #[test]
     fn the_read_back_ratchets_a_channel_downward() {
         let s = UiScript::new().unwrap();
@@ -589,7 +489,7 @@ mod tests {
             vec![7, 6, 5, 4, 3, 2, 1, 0],
             "one step down per cycle, to a fixed point at 0"
         );
-        // The fixed point holds — it is a ratchet, not a runaway.
+        // 0 is a fixed point: a ratchet, not a runaway.
         let g: f64 = s
             .eval("local r, g, b = cs:GetColorRGB() cs:SetColorRGB(r, g, b) return g")
             .unwrap();
@@ -599,7 +499,7 @@ mod tests {
     /// The two quantizers, directly. A is round-half-up and clamps; B is a floor with no clamp.
     #[test]
     fn the_two_quantizers_disagree_in_the_verified_way() {
-        // A — inbound. The clamp is part of it, so `2` is white and `-1` is black, not a wrapped byte.
+        // A, inbound, clamps: `2` is white and `-1` black, not a wrapped byte.
         assert_eq!(ColorSelectState::quantize_a(-1.0), 0);
         assert_eq!(ColorSelectState::quantize_a(0.0), 0);
         assert_eq!(ColorSelectState::quantize_a(1.0), 255);
@@ -607,7 +507,7 @@ mod tests {
         // The half-up bias: 0.5·255 = 127.5, +0.5 = 128.0, truncated = 128.
         assert_eq!(ColorSelectState::quantize_a(0.5), 128);
 
-        // B — outbound. Endpoints agree with A; a value a hair below a boundary does NOT.
+        // B, outbound: the endpoints agree with A, a half step does not.
         assert_eq!(ColorSelectState::quantize_b(0.0), 0);
         assert_eq!(ColorSelectState::quantize_b(1.0), 255);
         assert_eq!(ColorSelectState::quantize_b(0.5), 127, "floor, not half-up");
@@ -616,12 +516,11 @@ mod tests {
             ColorSelectState::quantize_a(0.5),
             "the disagreement IS the mechanism behind the drift"
         );
-        // No clamp on B — out of range wraps mod 256 (reachable only through SetColorHSV).
+        // B has no clamp: out of range wraps mod 256 (reachable only through `SetColorHSV`).
         assert_eq!(ColorSelectState::quantize_b(-0.001), 255);
     }
 
-    /// `SetColorRGB` fires `OnColorSelect` with the colour the widget now holds, and fires **again**
-    /// when the same colour is set — no change-gate (the module doc's byte-verified reason).
+    /// It fires with the colour the widget now holds, and again on the same colour: no change gate.
     #[test]
     fn set_color_rgb_fires_on_color_select_every_time() {
         let s = UiScript::new().unwrap();
@@ -641,8 +540,7 @@ mod tests {
         assert_eq!(s.eval::<usize>("return table.getn(fired)").unwrap(), 2);
         assert_eq!(s.eval::<String>("return fired[1]").unwrap(), "1,0,0");
 
-        // The handler's arguments are bit-identical to a GetColorRGB() on the next line — the
-        // binary reaches them through literally the same two calls, and so do we.
+        // The handler's arguments equal the next `GetColorRGB()` bit for bit, as in the reference.
         s.run("fired = {} cs:SetColorRGB(0, 1, 1)").unwrap();
         let (from_handler, from_getter): (String, String) = s
             .eval("local r, g, b = cs:GetColorRGB() return fired[1], r .. \",\" .. g .. \",\" .. b")
@@ -650,8 +548,6 @@ mod tests {
         assert_eq!(from_handler, from_getter);
     }
 
-    /// The methods are the ColorSelect's alone — a plain frame duck-types as *not* one, which is how
-    /// `if frame.SetColorRGB then` reads in an addon.
     #[test]
     fn the_methods_do_not_leak_onto_other_kinds() {
         let s = UiScript::new().unwrap();
@@ -661,13 +557,11 @@ mod tests {
         assert!(s.eval::<bool>("return plain.GetColorRGB == nil").unwrap());
     }
     // ─────────────────────────────────────────────────────────────────────────────────────────
-    // The wheel and the strip — the pick, the drag, and the two markers
+    // The wheel and the strip: the pick, the drag and the two markers
     // ─────────────────────────────────────────────────────────────────────────────────────────
 
-    /// A `ColorSelect` with the reference's own geometry, laid out and ready to click: a 128×128
-    /// wheel at the frame's top-left and a 32×128 strip to its right. Built through the XML loader
-    /// so the four elements' whole install path — `apply_colorselect`, the file-less setter form,
-    /// the getter round-trip that carries `<Size>`/`<Anchors>` — is what these tests exercise.
+    /// A ColorSelect with the reference's geometry, laid out: a 128×128 wheel at the top-left and a
+    /// 32×128 strip to its right, built through the XML loader so the elements' install path runs.
     fn picker() -> UiScript {
         let mut s = UiScript::new().unwrap();
         let xml = r#"<Ui>
@@ -702,7 +596,6 @@ mod tests {
         s
     }
 
-    /// The wheel's rect, from the region the loader published as a global.
     fn wheel_rect(s: &mut UiScript) -> (f32, f32, f32, f32) {
         let (l, b, w, h): (f32, f32, f32, f32) = s
             .eval(
@@ -713,8 +606,7 @@ mod tests {
         (l, b, w, h)
     }
 
-    /// The four elements install as real regions with the authored geometry, and the wheel's name
-    /// publishes as a global — which is what `<ColorValueTexture>`'s own anchor resolves against.
+    /// The wheel's name is a global, which `<ColorValueTexture>`'s anchor resolves against.
     #[test]
     fn the_four_elements_install_with_their_authored_geometry() {
         let mut s = picker();
@@ -738,11 +630,8 @@ mod tests {
         assert!(file.contains("UI-ColorPicker-Buttons"), "got {file}");
     }
 
-    /// **A click on the wheel picks the colour that pixel shows.** The disc's law and the pick law
-    /// are inverses (wow-re `colorselect-color-law.md` §5 / `colorselect-drawn-appearance.md`), so
-    /// this is stated at the four cardinal points, where the hue is nameable: LEFT is red, RIGHT
-    /// cyan, TOP violet, BOTTOM chartreuse. A sign error anywhere in the chain mirrors one axis and
-    /// two of these four flip.
+    /// The disc (`0x78b580`) and the pick (`0x78bdd0`) are inverses: left is red, right cyan, top
+    /// violet, bottom chartreuse, and a sign error flips two of the four.
     #[test]
     fn a_click_on_the_wheel_picks_the_hue_under_the_cursor() {
         let mut s = picker();
@@ -767,8 +656,7 @@ mod tests {
         }
     }
 
-    /// The centre is saturation 0 — white — and it stays white however the hue would have come out,
-    /// because the `-1` grey sentinel is inert on the way back through `hsv_to_rgb`.
+    /// White whatever the hue, as the `-1` grey sentinel is inert in `hsv_to_rgb`.
     #[test]
     fn the_wheels_centre_is_unsaturated() {
         let mut s = picker();
@@ -781,17 +669,15 @@ mod tests {
         );
     }
 
-    /// **The press IS the first move of the gesture**, and the drag keeps writing the wheel even
-    /// after the cursor leaves it — the capture is a flag on the widget, not a hit test per move
-    /// (`0x78bd80` is gated on `+0x314`, never re-tested). Dragging from red round to cyan without
-    /// lifting proves both.
+    /// The press is the first move, and the capture is a flag, not a hit test per move (`0x78bd80`
+    /// is gated on `+0x314`); dragging from red to cyan without lifting proves both.
     #[test]
     fn a_wheel_drag_keeps_the_capture_when_the_cursor_wanders_off() {
         let mut s = picker();
         let (l, b, w, h) = wheel_rect(&mut s);
         let cy = b + h * 0.5;
         s.mouse_button(l + 1.0, cy, "LeftButton", true);
-        // Straight across and well past the right rim — outside the wheel's rect entirely.
+        // Well past the right rim, outside the wheel's rect.
         s.mouse_move(l + w + 200.0, cy);
         let (r, g, bl): (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         assert!(
@@ -810,8 +696,6 @@ mod tests {
         );
     }
 
-    /// The strip writes **only** brightness: dragging it down to black and back up leaves the hue
-    /// exactly where the wheel put it.
     #[test]
     fn a_strip_drag_writes_brightness_and_leaves_the_hue_alone() {
         let mut s = picker();
@@ -834,7 +718,7 @@ mod tests {
         s.mouse_move(sx, sb - 50.0); // dragged below the strip: clamps to black
         let black: (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         assert_eq!(black, (0.0, 0.0, 0.0), "V clamps at 0");
-        // (Black is exact whatever the hue: `hsv_to_rgb` scales every channel by V.)
+        // Black is exact whatever the hue: `hsv_to_rgb` scales every channel by V.
         s.mouse_move(sx, sb + sh + 50.0); // and above it: clamps to full
         let full: (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         assert!(
@@ -845,9 +729,7 @@ mod tests {
         let _ = (w, l);
     }
 
-    /// `OnColorSelect` fires on **every** step of a drag, including one that lands on the colour
-    /// the widget already holds — the widget has no change-gate (`0x78bafd` tests only whether a
-    /// handler is bound), which is the opposite of the Slider next door.
+    /// Even a step onto the colour already held fires (`0x78bafd`).
     #[test]
     fn the_drag_fires_on_every_move_with_no_change_gate() {
         let mut s = picker();
@@ -859,33 +741,24 @@ mod tests {
         let after_press: i64 = s.eval("return fires").unwrap();
         assert_eq!(after_press, 1, "the press itself fires once");
         for _ in 0..3 {
-            s.mouse_move(cx, cy); // the SAME point — no change, still fires
+            s.mouse_move(cx, cy); // the same point: no change, still fires
         }
         let after_moves: i64 = s.eval("return fires").unwrap();
         assert_eq!(after_moves, 4, "no change-gate: every captured move fires");
     }
 
-    /// A press that lands on neither the wheel nor the strip captures nothing — the surrounding
-    /// window is not a giant colour surface.
     #[test]
     fn a_press_outside_both_rects_captures_nothing() {
         let mut s = picker();
         let before: (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         s.mouse_button(340.0, 20.0, "LeftButton", true); // inside the frame, below both
-        s.mouse_move(20.0, 150.0); // ... and now over the wheel, uncaptured
+        s.mouse_move(20.0, 150.0); // then over the wheel, uncaptured
         let after: (f64, f64, f64) = s.eval("return TestPicker:GetColorRGB()").unwrap();
         assert_eq!(after, before, "no capture, no colour change");
     }
 
-    /// The two markers sit where the colour came from. Checked through **extract**, not `GetLeft`:
-    /// the markers carry no anchors — the client `ClearAllPoints`es them and re-`SetPoint`s from
-    /// C++, and benilla derives their rects at extract for the same reason — so the layout resolver
-    /// has nothing to answer with. That is the same shape as the Slider thumb's, and it is the one
-    /// place a corpus addon could tell the difference; nothing in the 218 reads a picker marker's
-    /// rect.
-    ///
-    /// The wheel marker is checked by round trip — click a point, the marker's centre lands back on
-    /// it — which is the invariant that matters and the one either `fchs` breaks.
+    /// Checked through extract: the client places the markers from C++ with no anchors, so the
+    /// resolver has nothing to answer. A click lands the wheel marker's centre on the point.
     #[test]
     fn the_markers_land_where_the_colour_came_from() {
         let mut s = picker();
@@ -904,8 +777,8 @@ mod tests {
                 cy + dy
             );
         }
-        // The value marker rides V from the strip's bottom — and scales by the WHEEL's height,
-        // which is the client's own unguarded `[this+0x318]` read. Both are 128 here.
+        // The value marker rides V from the strip's bottom, scaled by the wheel's height (the
+        // reference's `[this+0x318]` read); both are 128 here.
         let (sb, sh): (f32, f32) = s
             .eval(
                 "local r = TestPicker:GetColorValueTexture(); return r:GetBottom(), r:GetHeight()",
@@ -925,9 +798,8 @@ mod tests {
         }
     }
 
-    /// The extracted rect of the marker whose authored width is `width` — the two markers share
-    /// one BLP and are told apart by their size (10 for the wheel's, 48 for the strip's), which is
-    /// also the assertion that they kept it.
+    /// The extracted rect of the marker `width` wide: the two share one BLP and differ by size, 10
+    /// for the wheel's and 48 for the strip's.
     fn marker_rect(s: &UiScript, width: f32) -> Option<crate::layout::Rect> {
         s.extract().into_iter().find_map(|q| {
             let r = q.rect?;
diff --git a/crates/benilla-ui/src/script/container.rs b/crates/benilla-ui/src/script/container.rs
index 1e068ba4..e0d457d4 100644
--- a/crates/benilla-ui/src/script/container.rs
+++ b/crates/benilla-ui/src/script/container.rs
@@ -1,52 +1,27 @@
-//! The container bindings (decision 0068 T2) — the 1.12 bag verbs, every one of them a plain
-//! top-level global (decision 1198; measured on the corpus: `GetContainerItemLink`,
-//! `GetContainerNumSlots` and `GetContainerItemInfo` are the three most-wanted engine verbs of
-//! all, and Bagnon's data engine is built on exactly these). Same two-way seam as
-//! [`super::action`]: the app pushes a **container snapshot** per bag id
-//! ([`UiScript::set_container`] — slots already resolved to icon/count/quality by the app's
-//! item stores; the engine holds no item knowledge), and `UseContainerItem` queues an outbound
-//! **intent** the app drains into the wire ([`UiScript::take_container_uses`]).
-//!
-//! Bag ids are the live API's space: `0` the backpack, `1..4` the equipped bags (bank later).
-//! Slots are 1-based. One deliberate divergence from the 1.14 documentation:
-//! `containerInfo.iconFileID` carries our icon **texture path** (`Interface\Icons\…`), not a
-//! numeric FileDataID — 5875 has no FileDataIDs, and every measured consumer feeds the value
-//! straight to `SetTexture`, which takes both shapes in the live client.
+//! The 1.12 bag verbs, all bare globals. The app pushes each bag's resolved snapshot and drains
+//! the intents the verbs queue; the engine holds no item knowledge. Bag ids are the 1.12 client's
+//! (0 the backpack, 1-4 the worn bags, -1 the bank's own slots, 5-10 the bank bags, -2 the
+//! keyring); slots are 1-based.
 
 use mlua::{Lua, Table, Value};
 
 use super::cursor::{self, CursorItem, CursorPayload};
 use super::Model;
 
-/// The charter/petition lines an item tooltip prints under its name — wow-re
-/// `system/ui/scratch/tooltip-content-law.md`'s **line 3**: *"(petition/guild-charter items) Title /
-/// Creator / Num-signatures (white; title wraps) — a resolved petition object; keys
-/// `PETITION_*`/`GUILD_CHARTER_*`"*.
-///
-/// The two key families are picked by [`Self::is_charter`], the same record bit that picks
-/// `GetPetitionInfo`'s first return — so a charter reads *"Guild Name:"* / *"Guild Master:"* and a
-/// plain petition reads *"Petition:"* / *"Created by"*.
-///
-/// **The third line, the signature count, is deliberately NOT here.** The law names it, but neither
-/// the carve nor the packet says where the number comes from: the petition record carries no count,
-/// and the only candidate — the item's `ITEM_FIELD_ENCHANTMENT` slot-0 *charges* dword, which
-/// vmangos's own source documents as "the on-item signature count" — has its write **commented
-/// out** server-side, so it is always zero and the guess could never be falsified here. Omitted
-/// rather than invented; the line is one field away the day someone pins the source.
+/// The petition lines an item tooltip prints under the name (`0x854d7c..0x854dd0`): the title and
+/// the creator, keyed `GUILD_CHARTER_*` for a charter, else `PETITION_*`. The signature-count line
+/// is not built: its source is untraced, and vmangos's write of the on-item count is commented out.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionSlotView {
-    /// The record's charter bit: `true` picks the `GUILD_CHARTER_*` keys, `false` the `PETITION_*`
-    /// ones.
+    /// The record's charter bit, also `GetPetitionInfo`'s first return.
     pub is_charter: bool,
     /// The proposed guild's (or petition's) name.
     pub title: String,
-    /// The owner's name, app-resolved through the name cache. `None` while that query is in
-    /// flight — the line is withheld, as the creator line is, rather than printed with a hole.
+    /// The owner's name from the name cache; `None`, and no line, while the query is in flight.
     pub owner: Option<String>,
 }
 
-/// One occupied bag slot, resolved by the app (icon from ItemDisplayInfo, count/quality from the
-/// item object + template). Plain data.
+/// One occupied bag slot, resolved by the app from the item object and its template.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ContainerSlot {
     /// Icon texture path (`Interface\Icons\…`); `None` while the template answer is in flight.
@@ -54,109 +29,65 @@ pub struct ContainerSlot {
     pub count: u32,
     /// Item quality 0..6; `None` while unresolved (the API reports `nil`).
     pub quality: Option<u32>,
-    /// The item's template entry (`containerInfo.itemID`); 0 while unresolved.
+    /// The item's template entry; 0 while unresolved.
     pub item_id: u32,
-    /// An `|Hitem:…|h[Name]|h` link once the name is known; Bagnon's search reads it.
+    /// An `|Hitem:…|h[Name]|h` link once the name is known.
     pub link: Option<String>,
     pub locked: bool,
-    /// The 1-based live-API inventory slot ids this item could be EQUIPPED into (empty = not
-    /// equippable) — the app-resolved "fit rule" decision 0208 phase 1b's cursor arc needs
-    /// (`cursor::CursorItem::equip_slots` captures it at pickup). Derived from the item
-    /// template's `inventoryType` via `ui_items::find_equip_slot`; the engine holds no item
-    /// knowledge of its own.
+    /// The 1-based inventory slots the item equips into, from `inventoryType`; empty if none.
     pub equip_slots: Vec<u8>,
-    /// Whether this item may be placed on an ACTION-BAR slot — app-resolved from the template
-    /// exactly like [`Self::equip_slots`] (the engine holds no item knowledge of its own).
-    /// `PlaceAction`'s only item filter, byte-read: an on-use spell OR equippable
-    /// (`ItemInfo::placeable_on_action_bar`, wow-re `action-item-slot.md` §5 — decision 0666).
+    /// Whether the item may go on an action bar: `PlaceAction`'s only item filter (`0x4e62e0`), an
+    /// on-use spell or equippable.
     pub bar_placeable: bool,
-    /// The instance's live durability `(current, max)` — `ITEM_FIELD_DURABILITY`/`MAXDURABILITY`
-    /// off the streamed item object; `None` for indestructible items (max 0) or while the create
-    /// hasn't landed. The real-instance tooltip's "Durability X / Y" line reads it (a template
-    /// hover keeps the template's full max/max).
+    /// Current and max durability; `None` when the max is 0 or the item object has not arrived.
     pub durability: Option<(u32, u32)>,
-    /// The item's running use-cooldown as `(start_ms on the GetTime clock, duration_ms,
-    /// enabled)` — the same app-computed triple [`super::ActionState::cooldown`] carries;
-    /// `None` = cold. Stored at push ([`super::UiScript::set_container`]) so
-    /// `GetContainerItemCooldown` answers the reference's `(start, duration, enable)`.
+    /// The use cooldown, `(start_ms on the GetTime clock, duration_ms, enabled)`; `None` if cold.
     pub cooldown: Option<(i64, u32, bool)>,
-    /// Right-clicking reads this item (an instance carrying `ITEM_FIELD_ITEM_TEXT_ID` — a mail
-    /// permanent copy). `GetContainerItemInfo`'s `isReadable`; the bag hover shows the Inspect
-    /// magnifier off it (ref ContainerFrame.lua l.638 `this.readable → ShowInspectCursor()`),
-    /// and the tooltip's WRITTEN_BY/READABLE gates key on it.
+    /// The instance carries `ITEM_FIELD_ITEM_TEXT_ID` (a mail copy): `GetContainerItemInfo`'s
+    /// `readable`, which shows the Inspect cursor (`ContainerFrame.lua:638`).
     pub readable: bool,
-    /// The RESOLVED `ITEM_FIELD_CREATOR` name (app: ask-once name cache) — the tooltip's
-    /// "Written by %s" (a letter) / "<Made by %s>" (anything crafted) line. `None` = authorless
-    /// or the name query is in flight (no line; the re-push repaints the hover when it lands).
+    /// The `ITEM_FIELD_CREATOR` name for the "Written by" or "<Made by>" line, once resolved.
     pub creator: Option<String>,
-    /// The instance's `ITEM_FIELD_FLAGS` — the tooltip's openable lock sub-gate reads
-    /// UNLOCKED `0x4`, the wrapped-gift arm WRAPPED `0x8` (see
-    /// [`super::char_stats::InvSlotView::flags`], the doll twin).
+    /// `ITEM_FIELD_FLAGS`; the tooltip reads UNLOCKED `0x4` and WRAPPED `0x8`.
     pub flags: u32,
-    /// `0x5da2c0` — **the instance is runtime-bound**: `ITEM_FIELD_FLAGS & 1` (soulbound), or a
-    /// live enchant slot naming a `SpellItemEnchantment` row that binds. App-resolved off the raw
-    /// descriptor ([`crate::items::already_bound`] in benilla-app — the same predicate the enchant
-    /// cursor's bind question asks), because the binding half needs a DBC join and the engine
-    /// holds no item knowledge of its own. The tooltip's §6 bind line overrides to **Soulbound**
-    /// on it (B310); `false` on any source with no streamed item object.
+    /// Bound at runtime (`0x5da2c0`): `ITEM_FIELD_FLAGS & 1`, or an enchant whose
+    /// `SpellItemEnchantment` row binds. The tooltip's bind line then says Soulbound.
     pub already_bound: bool,
-    /// The instance's enchant slots, resolved by the app ([`super::EnchantView`]) and in
-    /// enchant-slot order: it joins the id through `SpellItemEnchantment.dbc`'s name column and
-    /// hands over the row's name plus the three facts the line law needs to place and paint it.
-    /// Empty = unenchanted, or the enchant DBC never loaded. Decisions 0915/0920.
+    /// The enchant slots in slot order, named from `SpellItemEnchantment.dbc`; empty when none.
     pub enchants: Vec<super::EnchantView>,
-    /// **The instance's remaining LIFETIME in milliseconds** — a duration-limited item counting
-    /// down to its own destruction (a conjured stone, a holiday gift, a timed quest item). Its
-    /// only feed is `SMSG_ITEM_TIME_UPDATE`, parked as an absolute deadline and recomputed on
-    /// read ([`crate::items::Items::duration_remaining_display_ms`] in benilla-app), floored to
-    /// the whole second so the snapshot moves once a second rather than every frame.
-    /// `None` = no timer, which is nearly every item. Decision 1933.
+    /// A timed item's lifetime left in ms (`SMSG_ITEM_TIME_UPDATE`), floored to the second.
     pub duration_ms: Option<u64>,
-    /// The petition this item names, when it is a signable charter — **line 3 of the tooltip's
-    /// emission law**, between the NAME and the green `ITEM_SIGNABLE` line.
-    ///
-    /// `None` for every ordinary item, and also for a charter whose petition record has not
-    /// arrived: the hover is what ISSUES that query, so the first hover of an unopened charter
-    /// shows the name and the green line, and the two guild lines appear on the repaint. Exactly
-    /// [`Self::creator`]'s shape one field up, for exactly its reason.
+    /// A signable charter's petition, printed between the name and the green `ITEM_SIGNABLE`
+    /// line; `None` until the record the hover queries arrives.
     pub petition: Option<PetitionSlotView>,
 }
 
-/// One enchant slot as the tooltip renders it (wow-re `ui/scratch/tooltip-content-law.md` §E3,
-/// byte-verified; decision 0920). The app resolves the DBC row; every rule below is the engine's.
+/// One enchant slot as the tooltip renders it (`0x52c9f9`..`0x52ca23`); the app resolves the row.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct EnchantView {
-    /// `ITEM_FIELD_ENCHANTMENT` slot: **0** permanent · **1** temporary · **2..6** the
-    /// random-property suffix. It decides the colour band — only 0 and 1 are ever coloured.
+    /// `ITEM_FIELD_ENCHANTMENT` slot: 0 permanent, 1 temporary, 2-6 the random suffix; only 0 and
+    /// 1 are coloured.
     pub slot: u8,
-    /// The enchant id was NEGATIVE. `abs(id)` names the row either way — the sign's only effect is
-    /// to paint slots 0/1 pure-red instead of green (`0x52ca29–0x52ca49`).
+    /// The id was negative: `abs(id)` names the row, and slots 0 and 1 paint red, not green
+    /// (`0x52ca29`..`0x52ca49`).
     pub negative: bool,
-    /// The `SpellItemEnchantment` row's name, verbatim (`"Agility +15"`, `"Crusader"`) — the
-    /// reference copies the string with no format at all (`0x52ca8b–0x52caa1`).
+    /// The `SpellItemEnchantment` row's name, copied unformatted (`0x52ca8b`..`0x52caa1`).
     pub name: String,
-    /// The slot's `ITEM_FIELD_ENCHANTMENT` charges dword — nonzero appends " (N Charges)".
+    /// The slot's charges; nonzero appends " (N Charges)".
     pub charges: u32,
-    /// Milliseconds left on a TEMPORARY enchant, from `SMSG_ITEM_ENCHANT_TIME_UPDATE` (the item's
-    /// own duration field is never read for this). `Some` replaces the plain name with the
-    /// countdown phrasing; `None` = no timer, or expired.
+    /// Ms left on a temporary enchant, from `SMSG_ITEM_ENCHANT_TIME_UPDATE`, never the item's own
+    /// duration field; `Some` prints the countdown form.
     pub remaining_ms: Option<u64>,
 }
 
-/// One `ItemRandomProperties` row as the engine renders it — the **random-suffix roll** a dropped,
-/// linked, auctioned or mailed item carries (decision 1547). The app resolves the DBC (both of
-/// them: the roll's table and the `SpellItemEnchantment` names its five ids land on) and pushes the
-/// whole table once at load; a tooltip source supplies only the id, exactly as in the reference.
+/// One `ItemRandomProperties` row, an item's random-suffix roll. The app pushes the whole table at
+/// load, and a tooltip source supplies only the id, as in the reference.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct RandomPropertyView {
-    /// The roll's suffix — `"of the Monkey"`. The reference joins it onto the item name through
-    /// `ITEM_SUFFIX_TEMPLATE` (`"%s %s"`) in its one name formatter `0x5d8b00`; benilla does that
-    /// join app-side, where every display name is composed, so this is carried for reference and
-    /// for the surfaces that name an item the app never composed.
+    /// The suffix (`"of the Monkey"`), joined on by `ITEM_SUFFIX_TEMPLATE` (`0x5d8b00`), for the
+    /// names the app does not compose itself.
     pub suffix: String,
-    /// The enchant lines the roll grants, already named and seated in enchant slots **2..6** —
-    /// the five dwords the builder copies out of the suffix row (`0x52b7e0–0x52b7fb`). Slots 2..6
-    /// are always white, whatever the sign.
+    /// The roll's five enchants, named, in slots 2-6 (`0x52b7e0`..`0x52b7fb`); always white.
     pub enchants: Vec<EnchantView>,
 }
 
@@ -169,11 +100,9 @@ pub struct ContainerState {
     pub slots: std::collections::HashMap<u32, ContainerSlot>,
 }
 
-/// One queued backpack pick/place/swap/split: move the item from `(src_bag, src_slot)` to
-/// `(dst_bag, dst_slot)` (live-API space, 1-based slots). The app maps a backpack-internal move
-/// (both bags 0) onto `CMSG_SWAP_INV_ITEM` player-array slots. `count`: `None` = a whole-stack
-/// move/swap (including a same-item merge — the wire tops the stack up itself); `Some(n)` = a
-/// split placement (`SplitContainerItem`) the app maps onto `CMSG_SPLIT_ITEM` instead.
+/// One queued move from `(src_bag, src_slot)` to `(dst_bag, dst_slot)`. `count` is `None` for a
+/// whole stack (a move, a swap, or a merge the server tops up), `Some(n)` for a split placement
+/// (`CMSG_SPLIT_ITEM`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ContainerMove {
     pub src_bag: i64,
@@ -183,20 +112,15 @@ pub struct ContainerMove {
     pub count: Option<u32>,
 }
 
-/// One queued **auto-store into a bag** — `PutItemInBag`'s third leg and the whole of
-/// `PutItemInBackpack` (`crate::script::cursor::bag_verbs`): take the item at `(src_bag, src_slot)`
-/// and put it anywhere inside container `dst_bag`.
-///
-/// **There is no destination slot, and that is the finding, not an omission**: the reference's
-/// `CMSG_AUTOSTORE_BAG_ITEM 0x10B` carries `(srcbag, srcslot, dstbag)` and nothing else, and its
-/// split sibling `CMSG_SPLIT_ITEM 0x10E` carries the literal `0xFF` where a slot would go. The
-/// server picks. `count`: `None` = the whole stack (AUTOSTORE); `Some(n)` = a split carry, which
-/// the drain sends as SPLIT instead — the same fork the reference makes on `[0xb4b40c]`.
+/// One queued auto-store (`PutItemInBag`, `PutItemInBackpack`): the item at `(src_bag, src_slot)`
+/// into container `dst_bag`, with no slot: `CMSG_AUTOSTORE_BAG_ITEM` (0x10B) carries none and
+/// `CMSG_SPLIT_ITEM` (0x10E) sends `0xFF`, so the server picks. `Some(n)` in `count` is a split,
+/// the fork the reference makes on `[0xb4b40c]`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct BagAutoStore {
     pub src_bag: i64,
     pub src_slot: u32,
-    /// Live-API container id (0 = backpack, 1..=4 an equipped bag, 5..=10 a bank bag).
+    /// The container id: 0 the backpack, 1-4 a worn bag, 5-10 a bank bag.
     pub dst_bag: i64,
     pub count: Option<u32>,
 }
@@ -207,11 +131,8 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().bag_autostores)
     }
 
-    /// Push (or remove, with `None`) one bag's snapshot, keyed by live-API bag id (0 = backpack).
-    /// Each slot's cooldown arrives with its absolute start already on the `GetTime` clock (ms) —
-    /// storing is a pure unit conversion, the same seam shape as
-    /// [`super::UiScript::set_action_state`] — so `GetContainerItemCooldown` answers absolute
-    /// `(start, duration, enable)` without drift.
+    /// Push one bag's snapshot, or remove it with `None`; cooldowns arrive in ms on the `GetTime`
+    /// clock and are stored in seconds.
     pub fn set_container(&mut self, bag: i64, state: Option<ContainerState>) {
         let mut model = self.model_mut();
         model.container_cooldowns.retain(|&(b, _), _| b != bag);
@@ -236,8 +157,7 @@ impl super::UiScript {
         }
     }
 
-    /// Push the app's answer to `HasKey()` — whether the player owns any `BagFamily` KEYS item
-    /// anywhere the reference's own search reaches. The keyring UI's one gate (decision 0765).
+    /// Push `HasKey()`'s answer: whether the player owns a `BagFamily` key item anywhere.
     pub fn set_has_key(&mut self, has_key: bool) {
         self.model_mut().has_key = has_key;
     }
@@ -252,32 +172,25 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().container_moves)
     }
 
-    /// Drain the `(bag, slot)` sources `AutoEquipCursorItem` queued (decision 0208 phase 1b) —
-    /// the app resolves each to wire bag/slot and sends `CMSG_AUTOEQUIP_ITEM`.
+    /// Drain the `(bag, slot)` sources `AutoEquipCursorItem` queued, for `CMSG_AUTOEQUIP_ITEM`.
     pub fn take_container_autoequips(&mut self) -> Vec<(i64, u32)> {
         std::mem::take(&mut self.model_mut().container_autoequips)
     }
 
-    /// Drain the `(bag, slot)` repair clicks the repair-mode pickup intercept queued — the app
-    /// resolves each to its item guid and sends `CMSG_REPAIR_ITEM`.
+    /// Drain the `(bag, slot)` clicks repair mode queued, for `CMSG_REPAIR_ITEM`.
     pub fn take_container_repairs(&mut self) -> Vec<(i64, u32)> {
         std::mem::take(&mut self.model_mut().container_repairs)
     }
 
-    /// Drain the `(bag, slot, count)` destroys `DeleteCursorItem` queued (`count == 0` = the
-    /// whole stack) — the app resolves each to its item guid and sends `CMSG_DESTROYITEM`.
+    /// Drain the `(bag, slot, count)` destroys `DeleteCursorItem` queued, a 0 count being the whole
+    /// stack, for `CMSG_DESTROYITEM`.
     pub fn take_container_destroys(&mut self) -> Vec<(i64, u32, u32)> {
         std::mem::take(&mut self.model_mut().container_destroys)
     }
 
-    /// **Arm the gift-wrap cursor** on the paper at `(bag, slot)` — the app's call when a
-    /// right-click takes the reference's begin-wrap arm (`ItemInfo::begins_gift_wrap`).
-    ///
-    /// Three acts, exactly the three `0x5edea0` performs (wow-re
-    /// `object-layer/scratch/gift-wrap-law.md`): the paper's slot reads **locked**, the displayed
-    /// cursor becomes **mode 2** (`Interface\Cursor\Cast.blp` — the same art the cast cursor
-    /// uses, table `0x853b88` slot 2), and **nothing goes on the wire**. What completes it is the
-    /// next left-click on a container slot. Decision 1934.
+    /// Arm a gift wrap with the paper at `(bag, slot)`, as `0x5edea0` does: the paper locks, the
+    /// cursor takes mode 2 (the cast art, table `0x853b88`), and nothing is sent. The next
+    /// left-click on a container slot completes it.
     pub fn arm_gift_wrap(&mut self, bag: i64, slot: u32) {
         let mut model = self.model_mut();
         model.pending_wrap = Some(PendingWrap { bag, slot });
@@ -286,10 +199,9 @@ impl super::UiScript {
         cursor::queue_lock_changed(&mut model, bag, slot);
     }
 
-    /// **Cancel an armed gift wrap and nothing else** — disarm, unlock the paper, reset the
-    /// cursor. Deliberately narrower than `ClearCursor`, which also drops any held payload:
-    /// what wow-re records is that a right-click "uses the item and cancels the wrap", not by
-    /// which of the two routes, so this touches only the half the finding actually names.
+    /// Disarm a gift wrap, unlocking the paper and resetting the cursor, but keeping any held
+    /// payload, which `ClearCursor` would drop. How the reference's right-click cancels a wrap is
+    /// untraced.
     pub fn cancel_gift_wrap(&mut self) -> Option<PendingWrap> {
         let mut model = self.model_mut();
         let wrap = model.pending_wrap.take()?;
@@ -299,33 +211,25 @@ impl super::UiScript {
         Some(wrap)
     }
 
-    /// Is a gift wrap armed, and on which slot? Read by the app to decide whether a right-click
-    /// is cancelling one.
+    /// The armed gift wrap, if any; the app reads it to tell whether a right-click cancels one.
     pub fn gift_wrap_armed(&self) -> Option<PendingWrap> {
         self.model_ref().pending_wrap
     }
 
-    /// Drain the `(giftBag, giftSlot, itemBag, itemSlot)` quads a completed wrap queued — the app
-    /// resolves each pair to the wire's bag/slot addressing and sends `CMSG_WRAP_ITEM`.
+    /// Drain the `(giftBag, giftSlot, itemBag, itemSlot)` wraps queued, for `CMSG_WRAP_ITEM`.
     pub fn take_container_wraps(&mut self) -> Vec<(i64, u32, i64, u32)> {
         std::mem::take(&mut self.model_mut().container_wraps)
     }
 
-    /// The mode the last FrameXML cursor call armed — `None` after a `ResetCursor`. This is the
-    /// *value* of the most recent write; whether a write happened at all is
-    /// [`Self::take_cursor_write`], and that is what the app acts on (decision 1061).
+    /// The mode the last FrameXML cursor call set, `None` after a `ResetCursor`; the app acts on
+    /// [`Self::take_cursor_write`] instead.
     pub fn ui_cursor(&self) -> Option<UiCursorMode> {
         self.model_ref().ui_cursor
     }
 
-    /// Drain the pending cursor write: `Some(mode)` = a `Show*Cursor` armed `mode`, `Some(None)` =
-    /// a `ResetCursor` asked for the base mode, `None` = **no FrameXML cursor call happened**, so
-    /// the sticky mode stands untouched.
-    ///
-    /// The three-state return is the point. A UI element with no cursor handler must leave the
-    /// cursor exactly as it was — that is how an armed spell keeps its cast cursor while the mouse
-    /// crosses a spellbook button, and reading a two-state latch instead is what made it snap to
-    /// Point (decision 1061).
+    /// Drain the pending cursor write: `Some(mode)` a set, `Some(None)` a reset, `None` no call,
+    /// which must leave the cursor as it was, so an armed spell keeps its cast cursor over a
+    /// spellbook button.
     #[allow(clippy::option_option)]
     pub fn take_cursor_write(&mut self) -> Option<Option<UiCursorMode>> {
         let mut model = self.model_mut();
@@ -333,72 +237,49 @@ impl super::UiScript {
     }
 }
 
-/// **The armed gift wrap** — which piece of wrapping paper the next container click will spend.
-///
-/// The reference holds this as globals beside the displayed-cursor mode rather than as a cursor
-/// *payload*; the distinction is load-bearing and is why this is its own type instead of a
-/// [`cursor::CursorPayload`] variant (see [`super::Model::pending_wrap`]).
+/// The armed gift wrap's paper. The reference keeps it beside the cursor mode, not as a cursor
+/// payload, so `CursorHasItem()` stays false while a wrap is armed.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct PendingWrap {
-    /// The paper's container id, in the same bag space every cursor verb speaks.
+    /// The paper's container id.
     pub bag: i64,
     /// The paper's 1-based slot within that container.
     pub slot: u32,
 }
 
-/// A **displayed-cursor override** the FrameXML cursor family arms (wow-re cursor-system.md §7): the
-/// single "displayed mode" (`0xbe2c2c`) the real client swaps to while a UI element wants a non-base
-/// cursor, restored to the base mode by `ResetCursor`. The app maps each to the matching
-/// `Interface\Cursor\*` art over the world classifier's Point.
+/// A displayed-cursor override from the FrameXML cursor verbs, the reference's one displayed mode
+/// (`0xbe2c2c`), until `ResetCursor`; the app maps each to its `Interface\Cursor` art.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum UiCursorMode {
-    /// Buy(3) — the coin/pouch: selling a bag item to a vendor (`ShowContainerSellCursor`, no
-    /// affordability gate), or a merchant/buyback item you can afford (`Show*SellCursor`).
+    /// Buy (3): selling a bag item, or a merchant or buyback item the player can afford.
     Buy,
-    /// UnableBuy(23) — the grayed coin: a merchant/buyback item you can't afford (`Show*SellCursor`,
-    /// player coin < price).
+    /// UnableBuy (23): a merchant or buyback item the player cannot afford.
     UnableBuy,
-    /// Inspect(7) — the magnifier the Ctrl-hover shows over an item (`ShowInspectCursor`).
+    /// Inspect (7): the magnifier, `ShowInspectCursor`.
     Inspect,
-    /// Point(1) — `SetCursor("POINT_CURSOR")`, and what a `ResetCursor` resolves to.
+    /// Point (1), `SetCursor("POINT_CURSOR")`.
     Point,
-    /// Cast(2) — `SetCursor("CAST_CURSOR")`: the lit cast cursor a unit frame shows while a spell
-    /// that CAN bind that unit is armed (`UnitFrame_OnEnter`).
+    /// Cast (2), `SetCursor("CAST_CURSOR")`: a unit frame the armed spell can target.
     Cast,
-    /// UnableCast(22) — `SetCursor("CAST_ERROR_CURSOR")`: the greyed twin, for a unit the armed
-    /// spell cannot bind, and for `UnitFrame_OnLeave` while still targeting.
+    /// UnableCast (22), `SetCursor("CAST_ERROR_CURSOR")`: a unit frame the armed spell cannot
+    /// target, and leaving one while still targeting.
     CastError,
 }
 
-/// The pick/place/swap gesture behind `PickupContainerItem` (decision 0216 §2, amended by 0218;
-/// unit-testable without Lua). Mirrors the real client's single entry point:
-/// - an empty cursor over a resolved, UNLOCKED slot picks it up (a locked slot refuses — the real
-///   client's refusal; today only the app's `locked` flag drives this, the engine's own
-///   pending-move lock lands with slice 2);
-/// - holding, a click on the SAME slot cancels (a split carry included);
-/// - holding the WHOLE stack (`count: None`), a click elsewhere queues the move and CLEARS —
-///   empty, same-item (the wire merges), and different-item (the wire swaps: the displaced item
-///   lands where the held one came from) all alike. The displaced item never hops onto the
-///   cursor: 0216 §2 shipped that exchange off 0091's gloss; the director's eye caught it and
-///   the same-day §5 verdict refuted it at the bytes — no `SetCursorItem` on the place branch
-///   (`0x5e0c40`/`0x4f9b30`), `ClearCursor(0)`, one put-down sound (decision 0218; wow-re
-///   cursor-dragdrop-slots.md). Bag placements are server-authoritative; only the ACTION bar
-///   hops its displaced payload (client-authoritative — the slice-4 note in 0218).
-/// - holding a SPLIT carry (`count: Some(n)`), a click onto an empty/unresolved/same-item
-///   destination queues the split move and clears; onto a DIFFERENT item it's a no-op (kept —
-///   you can't swap a partial stack).
-/// - a spell/action payload refuses a bag slot outright (no-op, kept).
+/// `PickupContainerItem`'s gesture (`0x4f9b30`):
+/// - an empty cursor picks up a resolved item whose slot is not locked;
+/// - a click on the held item's own slot cancels;
+/// - a whole stack placed anywhere else queues the move and clears the cursor; a swap lands the
+///   displaced item in the source slot, never on the cursor (no `SetCursorItem`, `0x5e0c40`);
+/// - a split carry places onto an empty or same-item slot, and stays held over another item;
+/// - a spell or action payload stays held.
 ///
-/// Returns whether the caller should repaint (the source-slot lock or the held payload changed).
+/// Returns whether the caller should repaint.
 fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool {
-    // **The gift-wrap completion, ahead of the whole gesture** (decision 1934). `0x4f9b30` is the
-    // *only* entry to the wrap sender `0x5edfc0` image-wide — which is why the paper doll cannot
-    // finish a wrap and an equipped item is therefore unwrappable — and it takes this branch
-    // before it looks at the cursor at all.
+    // An armed gift wrap completes here, before the cursor is read. `PickupContainerItem` is the
+    // only caller of the wrap sender `0x5edfc0`, so an equipped item cannot be wrapped.
     if let Some(wrap) = model.pending_wrap {
-        // An empty or unresolved slot **bails and leaves the wrap armed** — the reference's own
-        // edge. Nothing is spent and the cursor keeps its mode, so the next click can still land
-        // on a real item.
+        // An empty or unresolved target leaves the wrap armed, as in the reference.
         if !model
             .containers
             .get(&bag)
@@ -407,10 +288,7 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
         {
             return false;
         }
-        // **The paper has to still be there.** `0x5edfef` bails when the stashed gift GUID no
-        // longer resolves, and — the edge worth transcribing — it then sends *and clears*
-        // nothing: the wrap stays armed and the paper's slot stays locked. So this returns
-        // without touching either.
+        // A vanished paper also bails, the wrap armed and the paper locked (`0x5edfef`).
         if !model
             .containers
             .get(&wrap.bag)
@@ -419,16 +297,12 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
         {
             return false;
         }
-        // No eligibility test of any kind. The wrap arm reads each item's `ITEM_FIELD_CONTAINED`
-        // and nothing else — not flags, not stack count, not bind state — and the client ships six
-        // `ERR_CANT_WRAP_*` strings for the server to answer with (`SMSG_INVENTORY_CHANGE_FAILURE`
-        // reasons 43-48). Same law as the openable click (decision 0896): gating locally would eat
-        // the click in silence and cost the player their error line.
+        // No eligibility test: the server refuses with an `ERR_CANT_WRAP_*` reason
+        // (`SMSG_INVENTORY_CHANGE_FAILURE` 43-48), and a local gate would eat that error line.
         model.pending_wrap = None;
         model.container_wraps.push((wrap.bag, wrap.slot, bag, slot));
-        // The paper unlocks and the cursor resets **immediately**, not on the server's answer:
-        // `0x5edfc0` calls `0x5eded0` at `0x5ee0aa`, right after the send. The target is never
-        // locked at all.
+        // The paper unlocks and the cursor resets right after the send (`0x5eded0` at
+        // `0x5ee0aa`), not on the answer; the target never locks.
         cursor::queue_lock_changed(model, wrap.bag, wrap.slot);
         model.ui_cursor = None;
         model.ui_cursor_dirty = true;
@@ -468,9 +342,7 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
             true
         }
         Some(CursorPayload::Item(held)) => {
-            // Cloned out from under `model.containers` so the moves below can borrow `model`
-            // mutably; a slot present but unresolved (item_id == 0, an in-flight template
-            // answer) reads as absent, same as a truly empty slot.
+            // Cloned so the moves below can borrow `model`; an unresolved slot reads as empty.
             let dest = model
                 .containers
                 .get(&bag)
@@ -478,16 +350,13 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
                 .cloned()
                 .filter(|d| d.item_id != 0);
             match (held.count, dest) {
-                // A split carry onto a DIFFERENT item can't swap a partial stack — no-op, kept.
+                // A split carry cannot swap with a different item: it stays held.
                 (Some(_), Some(d)) if d.item_id != held.item_id => {
                     model.cursor = Some(CursorPayload::Item(held));
                     false
                 }
-                // Every other placement queues its move and clears: empty and same-item take the
-                // carry's count through to the wire (a split placement or a merge the server
-                // tops up); a whole-stack place onto a different item is the plain SWAP — the
-                // displaced item lands where the held one came from, and the cursor empties
-                // (decision 0218, the director's eye over 0216 §2's hop).
+                // Anything else queues the move and clears: a split, a merge the server tops up,
+                // or a swap that lands the displaced item in the source slot.
                 (count, _) => {
                     queue_move(model, &held, bag, slot, count);
                     cursor::queue_cursor_update(model);
@@ -496,18 +365,10 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
                 }
             }
         }
-        // Mode 5 — **the buy**. A held vendor row dropped into a container slot is the whole
-        // point of the merchant cursor: `0x4f9efa` tests `[0xb4d900] == 5` right here and calls
-        // `0x5e1f30` = `CMSG_BUY_ITEM_IN_SLOT 0x1a3`, `{vendorGuid, itemEntry, bagGuid, bagSlot,
-        // count = 1}`. The cursor clears whether or not the server honours it.
-        //
-        // Deliberately NOT gated on the destination being empty. The reference does not look at
-        // the slot at all — the server decides, and answers `SMSG_BUY_FAILED` when it will not.
-        // What we DO refuse is a stale row: the reference's two container drop consumers
-        // dereference the vendor row without re-checking it against a list that may have been
-        // rewritten by a fresh `SMSG_LIST_INVENTORY`, which is a latent null deref there
-        // (`0x4f9f35`, `0x4c7ea5`). We treat a row that no longer resolves as a refusal — that is
-        // the third consumer `0x4c7300`'s own behaviour, and the one of the three that is right.
+        // Mode 5, a held vendor row, buys into this slot whatever it holds (`0x4f9efa` tests
+        // `[0xb4d900] == 5`): `CMSG_BUY_ITEM_IN_SLOT` (0x1a3) with count 1, and the cursor clears
+        // either way. Deviation: a row that no longer resolves is refused, as `0x4c7300` does,
+        // because this path dereferences it unchecked (`0x4f9f35`), a latent null deref.
         Some(CursorPayload::Merchant(held)) => {
             let entry = model
                 .merchant
@@ -526,10 +387,9 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
             | CursorPayload::Action(_)
             | CursorPayload::Macro(_)
             | CursorPayload::PetAction(_)
-            // Mode 10 (decision 1677) — a stabled pet refuses a bag/doll slot exactly as the
-            // spell/action family does, and stays on the cursor for the stable window to take.
+            // Mode 10, a stabled pet, stays held for the stable window.
             | CursorPayload::StablePet(_)
-            // Mode 2 (1962) — coins have no slot to land in; a money frame's DropFunc takes them.
+            // Mode 2, money, stays held for a money frame's DropFunc.
             | CursorPayload::Money(_)),
         ) => {
             model.cursor = Some(other);
@@ -538,7 +398,7 @@ fn pickup_container_item(model: &mut super::Model, bag: i64, slot: u32) -> bool
     }
 }
 
-/// Queue one pick/place/swap/split move (the shared tail of every clearing branch above).
+/// Queue one move, the shared tail of every clearing branch above.
 fn queue_move(
     model: &mut super::Model,
     held: &CursorItem,
@@ -555,35 +415,12 @@ fn queue_move(
     });
 }
 
-/// Register the container verbs — **top-level globals, because that is where 1.12 puts them**
-/// (decision 1198). Every name below is `function engine` in `reference/1.12-globals.tsv` as a
-/// bare global: `GetContainerNumSlots`, never `C_Container.GetContainerNumSlots`. The
-/// `C_Container` namespace 1187 reached for while chasing an Era addon is a *Dragonflight*
-/// reorganisation, and an addon that feature-detects it concludes it is on Dragonflight.
+/// Register the container verbs as bare globals, as `reference/1.12-globals.tsv` lists them;
+/// `C_Container` is a later client's namespace, and an addon that finds it assumes that client.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // ContainerIDToInventoryID(containerID) → the equipment slot the bag is worn in.
-    //
-    // **Two linear arms, one signed compare, and nothing else** (`0x4f94e0`, 124 bytes; wow-re
-    // `bag-language-combat-action-bindings.md` §1, §5-cross-checked). Written as the reference's
-    // own three instructions — `t = id - 1`, `if t < 4` (SIGNED), then `+20` or `+60` — rather
-    // than as the two closed forms `id+19` / `id+59`, because the wrap at the `i32` edge is then
-    // reproduced rather than approximated.
-    //
-    // | containerID | slot |
-    // |---|---|
-    // | **−2 (keyring)** | **17** |
-    // | −1 | 18 |
-    // | **0 (backpack)** | **19** |
-    // | 1 · 2 · 3 · 4 | 20 · 21 · 22 · 23 |
-    // | **5** (first bank bag) | **64** |
-    // | 6 … 10 | 65 … 69 |
-    //
-    // **There is no special case for 0 or for −2** — the "backpack is 0, keyring is −2"
-    // convention is the *caller's*, and this arithmetic merely happens to land on 19 and 17.
-    // **And there is no range check of any kind**: the only guard in the function is the up-front
-    // type test, so an out-of-range id is not clamped, not rejected, and never nil — it returns
-    // `id+19` or `id+59` as an ordinary number, and whatever the receiving binding does with an
-    // invalid slot is that binding's business.
+    // ContainerIDToInventoryID(containerID) (`0x4f94e0`): `id - 1`, then +20 below 4 else +60, so
+    // the keyring -2 → 17, the backpack 0 → 19, bags 1-4 → 20-23 and bank bags 5-10 → 64-69, with
+    // no special case and no range check.
     lua.globals().set(
         "ContainerIDToInventoryID",
         lua.create_function(|lua, id: Value| {
@@ -592,8 +429,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 id,
                 "Usage: ContainerIDToInventoryID(containerID)",
             )?;
-            // `0x4f951b dec eax` · `0x4f951f cmp eax,4` · `0x4f9524 jl` — the compare is signed
-            // and lands on the `id <= 4` arm.
+            // The reference's steps and signed compare (`0x4f9524 jl`), wrapping at the `i32` edge.
             let t = id.wrapping_sub(1);
             Ok(i64::from(if t < 4 {
                 t.wrapping_add(20)
@@ -603,46 +439,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetBagPortaitTexture(texture, containerID) — `0x4fa4f0` (374 B), the reference's own
-    // spelling, typo included, and CARVED (wow-re `system/ui/scratch/bag-portrait-and-appendtext.md`,
-    // §5 four-worker round). The bag window's portrait: `ContainerFrame_GenerateFrame` sets it for
-    // every container except the keyring, which takes `SetPortraitToTexture` with a fixed path one
-    // line above (ContainerFrame.lua l.418-423). benilla runs that file off the player's chain
-    // (1751), so this is a live call site.
-    //
-    // Three arms, and the FIRST is the one nobody would have guessed:
-    //
-    // 1 · **`id == 0` does nothing at all.** `0x4fa5b8 dec edi` / `0x4fa5b9 js 0x4fa65d` returns
-    //     before the clear at `0x4fa5c8` — no texture is set and none is cleared. It is not an
-    //     oversight: `ContainerFrame.xml:67` gives `$parentPortrait` no `file=`, and the backpack
-    //     takes a different ARTWORK background (`UI-BackpackBackground`) that covers the portrait
-    //     slot outright. (`Button-Backpack-Up` is nowhere on this path — its only stock use is the
-    //     main bar's own button, MainMenuBarBagButtons.xml:79.)
-    // 2 · **`id` in 1..=10** clears the texture first, then sets
-    //     `Interface\Icons\<ItemDisplayInfo.InventoryIcon_1>` for the bag in that inventory slot
-    //     — `StringLookups.dbc` row 3 measured as `"Interface\Icons"`, `.TGA` stripped,
-    //     `INV_Misc_QuestionMark` on a display-info miss. Ids 5..10 are additionally gated on the
-    //     bank being open. **An empty slot leaves the texture CLEARED** — there is no fallback art.
-    // 3 · **`id >= 11` raises** `"Invalid slot in SetBagPortaitTexture"`.
-    //
-    // Our icon comes from the same place the item's own button icon does (`GetInventoryItemTexture`
-    // reads the item template's icon), so the DBC walk above is the reference's route to the value
-    // this client already has resolved; the observable — which icon lands on the portrait — is the
-    // same one.
+    // SetBagPortaitTexture(texture, containerID) (`0x4fa4f0`, the reference's spelling): 0 and
+    // below return before the clear (`0x4fa5b9`), 1-10 clear and then set the bag's icon, 11 and
+    // up raise. The reference also needs the bank open for 5-10, which is not checked here.
     lua.globals().set(
         "SetBagPortaitTexture",
         lua.create_function(|lua, (region, container): (Table, i64)| {
-            // Arm 3, before anything is touched.
             if container >= 11 {
                 return Err(mlua::Error::runtime("Invalid slot in SetBagPortaitTexture"));
             }
-            // Arm 1: the backpack is a silent return, not a clear.
             if container <= 0 {
                 return Ok(());
             }
-            // `ContainerIDToInventoryID`'s arithmetic, deliberately re-expressed rather than
-            // called: that binding is a Lua global an addon may replace, and the engine's own
-            // portrait read does not go through Lua.
+            // `ContainerIDToInventoryID`'s arithmetic, inlined: an addon may replace that global,
+            // and the reference's portrait read does not go through Lua.
             let t = container.wrapping_sub(1);
             let inv = if t < 4 {
                 t.wrapping_add(20)
@@ -659,8 +469,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             let rh = crate::script::region::region_handle_of(lua, &region)?;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let data = model.region_data.entry(rh).or_default();
-            // Arm 2. `path` is `None` for an empty slot, and that IS the answer: the reference
-            // clears unconditionally and only then tries to set.
+            // An empty slot's `None` is the answer: the reference clears first, then sets.
             data.texture = path;
             data.circular = true;
             data.portrait_unit = None;
@@ -690,10 +499,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The reference's `GetContainerItemCooldown(bag, slot)` — the bag twin of
-    // `GetActionCooldown`, identical conventions: `GetTime`-clock `(start, duration, enable)`,
-    // enable 0 = an on-hold record (parked, full duration), and the cold-at-expiry guard so an
-    // event-driven re-feed can never replay the finish flash.
+    // GetContainerItemCooldown(bag, slot) (`0x4f99b0`) → start, duration, enable on the `GetTime`
+    // clock, as `GetActionCooldown`; enable 0 is a held cooldown. An expired one reads cold, so a
+    // re-feed cannot replay the finish flash.
     lua.globals().set(
         "GetContainerItemCooldown",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
@@ -726,31 +534,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetContainerItemInfo(bag, slot)` → **`texture, itemCount, locked, quality, readable`**
-    // — the 1.12 shape, five values (decision 1199).
-    //
-    // It used to return a single 1.14-shaped `containerInfo` TABLE, inherited from decision 1187's
-    // reach for the Classic Era surface. That was wrong in a way neither instrument could see:
-    // **36 corpus addons call this and every one of them uses the 1.12 shape. Not one uses the
-    // table.** 34 destructure (`local texture, itemCount = GetContainerItemInfo(bag, slot)`), and
-    // the four that assign a single name take the *first return* — `local texture = …`, or
-    // `GetContainerItemInfo(bag, i) ~= nil` as an occupancy test. All 36 were getting
-    // `texture = <table>` and, where they destructured, `itemCount = nil`. They load clean, so the
-    // harness scores them as passes, and they misbehave silently in play.
-    //
-    // (Decision 1199 §1 says "only one uses the table shape" — that came from a first reading of
-    // the call sites and a recount disproves it. The corrected number makes the case stronger, not
-    // weaker; the record is a point-in-time snapshot and this is where the true count lives.)
-    //
-    // The shipped 1.12 FrameXML settles the shape: `ContainerFrame.lua:241` reads exactly these
-    // five names in exactly this order.
-    //
-    // **A signature is part of the API.** Decision 1198 §3 made that argument about *names*; this
-    // is the same argument one level down, and it is the more dangerous half, because a wrong name
-    // fails loudly and a wrong shape does not.
-    //
-    // `nil` for an empty or unknown slot — the reference returns no values there, and a caller's
-    // `if texture then` reads the same either way.
+    // GetContainerItemInfo(bag, slot) (`0x4f9670`) → texture, itemCount, locked, quality,
+    // readable, the five `ContainerFrame.lua:241` reads; no values for an empty or unknown slot.
     lua.globals().set(
         "GetContainerItemInfo",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
@@ -760,9 +545,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     &model.cursor,
                     Some(CursorPayload::Item(c)) if c.bag == bag && c.slot == slot
                 ) ||
-                // An armed gift wrap locks its paper for as long as it stands (`0x4953e0` at
-                // `0x5edeb5`) — the same dimming a held item's source slot shows, and released by
-                // the send or by any cancel rather than by the server (decision 1934).
+                // An armed wrap's paper reads locked until the send or a cancel (`0x4953e0` at
+                // `0x5edeb5`).
                     matches!(
                         &model.pending_wrap,
                         Some(w) if w.bag == bag && w.slot == slot
@@ -785,9 +569,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     None => Value::Nil,
                 },
                 Value::Integer(i64::from(s.count)),
-                // The picked-up source slot reads locked (the real client dims it while the cursor
-                // carries the item) — derived from the cursor, not a mutated snapshot, so the
-                // app's per-frame re-push cannot wipe it.
+                // A held item's source slot reads locked, derived from the cursor so the app's
+                // re-push cannot wipe it.
                 Value::Boolean(s.locked || held_here),
                 match s.quality {
                     Some(q) => Value::Integer(i64::from(q)),
@@ -798,19 +581,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `BenillaGetContainerItemID(bag, slot)` — the item id behind a slot, for OUR OWN FrameXML.
-    //
-    // 1.12 has no such verb: an addon there takes the id out of `GetContainerItemLink`'s
-    // `|Hitem:12345:…` payload. Our tooltip and delete paths want the id directly, so it rides the
-    // `Benilla` host-bridge prefix — the sanctioned escape hatch for a verb only our own
-    // transcription calls, and the one `reference_surface` covers by prefix rather than by
-    // exception. An addon that wants it parses the link, exactly as it would on the real client.
+    // BenillaGetContainerItemID(bag, slot): the item id behind a slot. Not a 1.12 verb, where the
+    // id is parsed from `GetContainerItemLink`; the `Benilla` prefix keeps it off the 1.12 surface.
     lua.globals().set(
         "BenillaGetContainerItemID",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // `nil` for an unresolved id, not `0` — a slot can carry an entry whose template has
-            // not landed yet, and `0` is a number a caller will happily index a table with.
+            // nil, not 0, while the template is in flight: a caller would index a table with 0.
             Ok(model
                 .containers
                 .get(&bag)
@@ -830,35 +607,21 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The left-click drag gesture: pick up from an occupied slot, or place/swap when holding.
-    // Returns whether the caller should repaint (the source-slot lock changed) — the OnClick calls
-    // the bag's `_Update` on true so the picked slot dims / un-dims immediately (no server round
-    // trip for the local cursor state).
+    // PickupContainerItem(bag, slot) (`0x4f9b30`): pick up, or place and swap. Its boolean return,
+    // whether to repaint, is not 1.12's, whose binding returns nothing.
     lua.globals().set(
         "PickupContainerItem",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // Two intercepts live IN the pickup path, in the reference's own order (decision
-            // 0923 re-read `PickupContainerItem 0x4f9b30` whole; the targeting rung is at
-            // `4f9c54` and the repair test at `4f9c7b`, so targeting wins — a poisoning click at
-            // a repair vendor binds the poison, it does not repair):
-            //
-            //   4f9c54  call 0x6e48a0        ; IsTargeting
-            //   4f9c5d  call 0x6e6330        ; TargetingWantsItem (word & 0x4010)
-            //   4f9c6d  call 0x495d60        ; bind THIS item — then return, nothing picked up
-            //
-            // The held-payload check precedes BOTH (`4f9c38`: a non-empty cursor jumps to the
-            // place/swap arm long before either), so a click while carrying an item is a place —
-            // transcribed by the `cursor.is_none()` gate. The word is one-shot: the app clears it
-            // on completion, cancel, or close.
+            // The reference tests a held payload first (`0x4f9c38`), then an armed item-targeting
+            // spell, which takes the item (`0x4f9c54`, `0x495d60`), then repair mode (`0x4f9c7b`),
+            // so poisoning at a repair vendor binds the poison.
             if model.item_pick_armed && model.cursor.is_none() {
                 model.item_picks.push((bag, slot));
                 return Ok(false);
             }
-            // Repair mode (`0x4f9c7b`, wow-re repair-machinery.md): while the repair cursor is
-            // armed, the click means "repair this item" — queued for the app to send — and
-            // nothing is picked up. The mode STICKS across clicks (only HideRepairCursor /
-            // merchant-close clears it).
+            // Repair mode, until `HideRepairCursor`, queues a repair and picks nothing up. Unlike
+            // the reference, it does not first check for a held item.
             if model.repair_mode {
                 model.container_repairs.push((bag, slot));
                 return Ok(false);
@@ -867,14 +630,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The cursor globals (`GetCursorInfo`/`CursorHasItem`/`CursorHasSpell`/`ClearCursor`/
-    // `SplitContainerItem`/`DeleteCursorItem`) live in [`super::cursor`], the one payload seam
-    // every surface routes through — top-level there for exactly the same reason.
-
-    // ShowContainerSellCursor(bag, slot) — arm the pouch cursor for a sellable hover (5875
-    // `0x4fa460`, wow-re cursor-system.md §7: Buy(3) only when the slot actually holds an item —
-    // an empty slot leaves the cursor unchanged; no Unable twin, no SellPrice check — selling
-    // never grays), and the reference's own `IsTargeting` bail at its first instruction.
+    // ShowContainerSellCursor(bag, slot) (`0x4fa460`): Buy (3) over an occupied slot, with no
+    // price check, so selling never greys; an empty slot leaves the cursor alone.
     lua.globals().set(
         "ShowContainerSellCursor",
         lua.create_function(|lua, (bag, slot): (i64, u32)| {
@@ -884,11 +641,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 .get(&bag)
                 .and_then(|c| c.slots.get(&slot))
                 .is_some();
-            // `IsTargeting` bails at the function's FIRST instruction — an armed spell suppresses
-            // the sell cursor outright (wow-re `item-target-cursor-and-dropitemonunit.md`). Now
-            // that the mode is sticky, this gate has to be here rather than app-side: a write of
-            // Buy would otherwise stamp over the cast cursor and there would be no per-frame world
-            // write to put it back.
+            // An armed spell suppresses it first (`0x4fa469`); the mode is sticky, so a Buy here
+            // would stamp out the cast cursor for good.
             if occupied && !model.spell_targeting {
                 model.ui_cursor = Some(UiCursorMode::Buy);
                 model.ui_cursor_dirty = true;
@@ -896,10 +650,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // ShowInspectCursor() — the Ctrl-hover magnifier (5875 `0x48ac60`: an unconditional
-    // `CursorSetMode(Inspect=7)`). Shared across surfaces (the merchant window's Ctrl-hover, a bag
-    // item's Ctrl-hover, the generic UIParent item hover), so it lives here beside `ResetCursor`
-    // rather than in any one seam. It takes no arguments and reads no state.
+    // ShowInspectCursor() (`0x48ac60`): Inspect (7), unconditionally.
     lua.globals().set(
         "ShowInspectCursor",
         lua.create_function(|lua, ()| {
@@ -909,11 +660,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // HasKey() — "does this player own a key at all?" (5875 `0x48ae90`), the gate the main bar
-    // reads to decide whether the keyring exists in the UI. The reference pushes the NUMBER 1 on a
-    // hit and nil otherwise, not a boolean, and FrameXML only ever tests it for truth — so the
-    // shape is reproduced exactly rather than normalized to a bool. The search itself (BagFamily
-    // == 9 across equipment/bags/backpack/bank/keyring) is the app's, like every other item fact.
+    // HasKey() (`0x48ae90`) → the number 1 if the player owns a key (`BagFamily` 9) anywhere, else
+    // nil, never a boolean; the app does the search.
     lua.globals().set(
         "HasKey",
         lua.create_function(|lua, ()| {
@@ -925,15 +673,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // SetCursor(name) — the reference's `0x489490`: a name->mode table (POINT/CAST/BUY/ATTACK =
-    // 1..4, each with an `*_ERROR` twin at +20) into `CursorSetMode`, falling back to a custom
-    // bitmap for an unknown name. Only the modes FrameXML actually names are mapped here; anything
-    // else is ignored rather than guessed, and a **no-arg call is a `ResetCursor`**, which is the
-    // reference's own documented shape.
-    //
-    // Its one shipped caller is the unit-frame hover pair (`UnitFrame_OnEnter`/`OnLeave`), which is
-    // the ONLY lit/grey cursor split over a UI element in 1.12 — and it is authored in Lua, not in
-    // C++ (wow-re `item-target-cursor-and-dropitemonunit.md` §4.3).
+    // SetCursor(name) (`0x489490`): POINT, CAST, BUY and ATTACK are modes 1-4, each `*_ERROR` 20
+    // higher, and no argument is a `ResetCursor`. The stock UI calls it only from the unit-frame
+    // hover (`UnitFrame.lua:50`).
     lua.globals().set(
         "SetCursor",
         lua.create_function(|lua, name: Option<String>| {
@@ -944,9 +686,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some("CAST_ERROR_CURSOR") => Some(UiCursorMode::CastError),
                 Some("BUY_CURSOR") => Some(UiCursorMode::Buy),
                 Some("BUY_ERROR_CURSOR") => Some(UiCursorMode::UnableBuy),
-                // An unmapped name: the reference would load a custom bitmap. We have no such art,
-                // and silently painting the wrong stock cursor would be worse than leaving the
-                // sticky mode alone, so this is a no-op rather than a guess.
+                // Ignored: the reference loads an unknown name as a custom cursor bitmap, which is
+                // not built.
                 Some(_) => return Ok(()),
             };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -955,8 +696,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // ResetCursor — displayed mode back to the base (the world classifier's) mode (5875
-    // `0x48ac70` → `0x523d30`): clear the whole override, whichever `Show*Cursor` armed it.
+    // ResetCursor() (`0x48ac70` → `0x523d30`): back to the base mode, whatever set the override.
     lua.globals().set(
         "ResetCursor",
         lua.create_function(|lua, ()| {
@@ -1000,7 +740,7 @@ mod tests {
         );
         // An in-flight slot: the create arrived, the template answer hasn't.
         slots.insert(3, ContainerSlot::default());
-        // A readable letter (a mail permanent copy — instance item-text): isReadable true.
+        // A readable letter, a mail copy with item text.
         slots.insert(
             4,
             ContainerSlot {
@@ -1017,16 +757,10 @@ mod tests {
         }
     }
 
-    /// **The gift-wrap state machine** (decision 1934), all four of its edges. Armed by the app's
-    /// right-click on a wrapper, the arm locks the paper and paints cursor mode 2 and sends
-    /// nothing; the next LEFT-click on a container slot spends it; an empty slot bails and leaves
-    /// it armed; and any `ClearCursor` cancels it.
     #[test]
     fn an_armed_gift_wrap_spends_on_the_next_container_click() {
         let mut s = UiScript::new().unwrap();
         s.set_container(0, Some(backpack()));
-        // The arm: nothing on the wire, the paper reads locked, the cursor is mode 2, and the
-        // held-item predicate stays FALSE — this is a cursor mode, not a payload.
         s.arm_gift_wrap(0, 1);
         assert_eq!(s.gift_wrap_armed(), Some(PendingWrap { bag: 0, slot: 1 }));
         assert!(s.take_container_wraps().is_empty(), "arming sends nothing");
@@ -1040,7 +774,7 @@ mod tests {
             !s.eval::<bool>("return CursorHasItem()").unwrap(),
             "the wrap writes no payload, so every stock CursorHasItem() gate stays shut"
         );
-        // A click on an EMPTY slot bails and leaves the wrap armed — the reference's own edge.
+        // A click on an empty slot leaves the wrap armed.
         s.eval::<()>("PickupContainerItem(0, 9)").unwrap();
         assert_eq!(s.gift_wrap_armed(), Some(PendingWrap { bag: 0, slot: 1 }));
         assert!(s.take_container_wraps().is_empty());
@@ -1059,9 +793,7 @@ mod tests {
         );
     }
 
-    /// Any `ClearCursor` cancels an armed wrap — the reference tests it FIRST inside
-    /// `ClearCursor 0x495190` and does so ungated by either parameter, so all 70 of its call
-    /// sites cancel (decision 1934).
+    /// `ClearCursor` (`0x495190`) tests for an armed wrap first, whatever its arguments.
     #[test]
     fn clear_cursor_cancels_an_armed_gift_wrap() {
         let mut s = UiScript::new().unwrap();
@@ -1076,7 +808,6 @@ mod tests {
                 .unwrap(),
             "the paper unlocks with the cancel — the lock never waited on a server"
         );
-        // …and the next container click is an ordinary pickup again.
         s.eval::<()>("PickupContainerItem(0, 1)").unwrap();
         assert!(s.take_container_wraps().is_empty());
         assert!(s.cursor_payload().is_some(), "a plain pickup, as before");
@@ -1085,7 +816,6 @@ mod tests {
     #[test]
     fn container_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
-        // No bag pushed: capacity 0, info nil.
         assert_eq!(s.eval::<i64>("return GetContainerNumSlots(0)").unwrap(), 0);
         assert!(s
             .eval::<bool>("return GetContainerItemInfo(0, 1) == nil")
@@ -1097,8 +827,7 @@ mod tests {
             s.eval::<String>("return GetBagName(0)").unwrap(),
             "Backpack"
         );
-        // The 1.12 five-value shape (decision 1199): texture, itemCount, locked, quality,
-        // readable — the names `ContainerFrame.lua:241` destructures into, in its order.
+        // The five values `ContainerFrame.lua:241` reads, in its order.
         let (icon, count, quality) = s
             .eval::<(String, i64, i64)>(
                 "local texture, itemCount, locked, quality = GetContainerItemInfo(0, 1)\n\
@@ -1107,8 +836,6 @@ mod tests {
             .unwrap();
         assert_eq!(icon, "Interface\\Icons\\INV_Misc_Food_16");
         assert_eq!((count, quality), (5, 1));
-        // The item id is NOT one of the five — 1.12 has no verb for it, and an addon takes it out
-        // of the link. Ours rides the host-bridge prefix.
         assert_eq!(
             s.eval::<i64>("return BenillaGetContainerItemID(0, 1)")
                 .unwrap(),
@@ -1117,7 +844,7 @@ mod tests {
         assert!(s
             .eval::<bool>("return GetContainerItemLink(0, 1) ~= nil")
             .unwrap());
-        // isReadable mirrors the slot's readable bit (the letter in 4, not the jerky in 1).
+        // readable: the letter in 4, not the jerky in 1.
         assert!(!s
             .eval::<bool>("local _, _, _, _, readable = GetContainerItemInfo(0, 1) return readable")
             .unwrap());
@@ -1125,10 +852,7 @@ mod tests {
             .eval::<bool>("local _, _, _, _, readable = GetContainerItemInfo(0, 4) return readable")
             .unwrap());
 
-        // **The in-flight slot**: an entry exists but its template has not landed, so texture and
-        // quality are nil while itemCount is real. This is the state that made the five-value
-        // shape's occupancy test subtle (decision 1199) — the reference's own `if texture then`
-        // would read this as empty, which is why our own FrameXML tests `texture or itemCount`.
+        // An in-flight slot: texture and quality nil, itemCount real.
         assert!(s
             .eval::<bool>(
                 "local texture, itemCount, locked, quality = GetContainerItemInfo(0, 3)\n\
@@ -1138,7 +862,6 @@ mod tests {
         assert!(s
             .eval::<bool>("return BenillaGetContainerItemID(0, 3) == nil")
             .unwrap());
-        // Empty slot: nil.
         assert!(s
             .eval::<bool>("return GetContainerItemInfo(0, 2) == nil")
             .unwrap());
@@ -1161,7 +884,6 @@ mod tests {
         assert!(s.cursor_item().is_none());
         assert!(!s.eval::<bool>("return CursorHasItem()").unwrap());
 
-        // Pick up slot 1 → cursor holds it, the source slot reads locked, no move queued yet.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 1)").unwrap());
         let held = s.cursor_item().expect("cursor holds the picked item");
         assert_eq!((held.bag, held.slot, held.item_id), (0, 1, 117));
@@ -1175,13 +897,11 @@ mod tests {
             .unwrap());
         assert!(s.take_container_moves().is_empty());
 
-        // GetCursorInfo reports the item.
         let (kind, id) = s
             .eval::<(String, i64)>("local k, id = GetCursorInfo() return k, id")
             .unwrap();
         assert_eq!((kind.as_str(), id), ("item", 117));
 
-        // Place onto slot 5 → a move (0,1)->(0,5) queues, cursor clears, source un-locks.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 5)").unwrap());
         assert!(s.cursor_item().is_none());
         assert!(!s.eval::<bool>("return CursorHasItem()").unwrap());
@@ -1195,22 +915,12 @@ mod tests {
                 count: None,
             }]
         );
-        // `local _, _, locked` — the 1.12 five-value shape, the same destructuring the positive
-        // assertion above uses. This read `local i = … return i.isLocked` until 2171: a leftover
-        // of the 1.14 `containerInfo` TABLE that 1187 reached for and 1199 corrected in the
-        // binding without correcting it here. It passed anyway, because 5.1's string metatable
-        // made indexing the `texture` string a silent `nil` and `nil` is a passing `!bool`. Taking
-        // the metatable away — 1.12 has none — is what turned a test that asserted nothing into a
-        // test that raises.
         assert!(!s
             .eval::<bool>("local _, _, locked = GetContainerItemInfo(0, 1) return locked")
             .unwrap());
     }
 
-    /// The sibling of the test above onto an OCCUPIED, DIFFERENT-item slot: the plain SWAP
-    /// (decision 0218, superseding 0216 §2's hop — byte-verified: no `SetCursorItem` on the place
-    /// branch; the wire swaps and the cursor empties, exactly like an empty destination). The
-    /// displaced item never lands on the cursor.
+    /// The reference's place runs no `SetCursorItem`: the displaced item is never held.
     #[test]
     fn pickup_place_onto_occupied_different_item_swaps_and_clears() {
         let mut s = UiScript::new().unwrap();
@@ -1242,8 +952,6 @@ mod tests {
         assert!(s.eval::<bool>("return PickupContainerItem(0, 1)").unwrap());
         assert_eq!(s.cursor_item().unwrap().item_id, 117);
 
-        // Place A onto occupied slot 5 (item B) → move (1→5) queues, the cursor EMPTIES (the
-        // server's swap lands B in slot 1), and the source un-locks.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 5)").unwrap());
         assert!(
             s.cursor_item().is_none(),
@@ -1259,15 +967,12 @@ mod tests {
                 count: None,
             }]
         );
-        // The 1.12 five-value shape — see the sibling test above for what this used to read and
-        // why it passed while asserting nothing (2171).
         assert!(!s
             .eval::<bool>("local _, _, locked = GetContainerItemInfo(0, 1) return locked")
             .unwrap());
     }
 
-    /// Placing onto a SAME-item_id destination merges (the wire tops the stack up itself) —
-    /// still a plain clear-on-move.
+    /// A same-item placement is a plain move: the server merges the stacks.
     #[test]
     fn pickup_place_onto_same_item_merges_and_clears() {
         let mut s = UiScript::new().unwrap();
@@ -1345,7 +1050,6 @@ mod tests {
             (0, 1, 117, Some(3))
         );
 
-        // Placed onto an empty slot: the move carries the split count, and clears.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 2)").unwrap());
         assert!(s.cursor_item().is_none());
         assert_eq!(
@@ -1359,14 +1063,12 @@ mod tests {
             }]
         );
 
-        // Re-split, then place onto a DIFFERENT item: no-op, the split carry is kept.
         s.run("SplitContainerItem(0, 1, 3)").unwrap();
         assert!(!s.eval::<bool>("return PickupContainerItem(0, 9)").unwrap());
         let held = s.cursor_item().expect("kept — can't swap a partial stack");
         assert_eq!(held.count, Some(3));
         assert!(s.take_container_moves().is_empty());
 
-        // Placed onto a SAME-item slot: the server merges — the move queues, cursor clears.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 7)").unwrap());
         assert!(s.cursor_item().is_none());
         assert_eq!(
@@ -1389,7 +1091,7 @@ mod tests {
             .eval::<bool>("return SplitContainerItem(0, 1, 5)")
             .unwrap());
         assert_eq!(s.cursor_item().unwrap().count, None);
-        // Split of MORE than the stack clamps the same way.
+        // A split of more than the stack is a plain pickup too.
         s.run("ClearCursor()").unwrap();
         assert!(s
             .eval::<bool>("return SplitContainerItem(0, 1, 99)")
@@ -1403,7 +1105,6 @@ mod tests {
         s.set_container(0, Some(backpack()));
         assert!(s.eval::<bool>("return PickupContainerItem(0, 1)").unwrap());
         assert!(s.cursor_item().is_some());
-        // Click the same slot again → cancel: cursor clears, nothing queued.
         assert!(s.eval::<bool>("return PickupContainerItem(0, 1)").unwrap());
         assert!(s.cursor_item().is_none());
         assert!(s.take_container_moves().is_empty());
@@ -1413,7 +1114,7 @@ mod tests {
     fn pickup_empty_slot_holds_nothing() {
         let mut s = UiScript::new().unwrap();
         s.set_container(0, Some(backpack()));
-        // Slot 2 is empty, slot 3 is in-flight (unresolved, item_id 0) — neither is pickable.
+        // Slot 2 is empty and slot 3 unresolved: neither can be picked up.
         assert!(!s.eval::<bool>("return PickupContainerItem(0, 2)").unwrap());
         assert!(s.cursor_item().is_none());
         assert!(!s.eval::<bool>("return PickupContainerItem(0, 3)").unwrap());
@@ -1439,10 +1140,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetContainerNumSlots(2)").unwrap(), 0);
     }
 
-    /// `GetContainerItemCooldown` — the `GetActionCooldown` conventions on the bag twin: the
-    /// absolute-start triple stored verbatim in `GetTime` seconds, the cold `(0, 0, 1)` shape
-    /// for no-cooldown slots, the stale-refeed guard at expiry, and the re-push replacing a
-    /// bag's prior triples.
     #[test]
     fn container_item_cooldown_reads_the_gettime_triple() {
         let mut s = UiScript::new().unwrap();
@@ -1452,21 +1149,19 @@ mod tests {
         state.slots.get_mut(&1).unwrap().cooldown = Some((96_000, 10_000, true));
         s.set_container(0, Some(state));
 
-        // The pushed absolute start reads back verbatim in seconds.
         assert!(s
             .eval::<bool>(
                 "local s, d, e = GetContainerItemCooldown(0, 1)\n\
                  return s == 96 and d == 10 and e == 1"
             )
             .unwrap());
-        // A slot with no cooldown reads cold.
         assert!(s
             .eval::<bool>(
                 "local s, d, e = GetContainerItemCooldown(0, 3)\n\
                  return s == 0 and d == 0 and e == 1"
             )
             .unwrap());
-        // Past expiry, the same stored triple reads cold — the no-replayed-flash guard.
+        // Past expiry, the same stored triple reads cold.
         s.tick(7.0);
         assert!(s
             .eval::<bool>(
@@ -1484,12 +1179,8 @@ mod tests {
             .unwrap());
     }
 
-    // ── `ContainerIDToInventoryID` (wow-re `bag-language-combat-action-bindings.md` §1) ─────────
+    // ── `ContainerIDToInventoryID` (`0x4f94e0`) ─────────────────────────────────────
 
-    /// Two linear arms and no range check. **−2 → 17 and 0 → 19 are not special cases** — they are
-    /// ordinary points on the `id <= 4` line that the caller-side "keyring is −2 / backpack is 0"
-    /// convention happens to land on, which is why they are asserted beside the bag slots rather
-    /// than as exceptions.
     #[test]
     fn container_id_to_inventory_id_is_two_lines_with_no_clamp() {
         let s = UiScript::new().unwrap();
@@ -1497,7 +1188,7 @@ mod tests {
             s.eval::<i64>(&format!("return ContainerIDToInventoryID({id})"))
                 .unwrap()
         };
-        // The `id <= 4` line: keyring, the odd −1, the backpack, the four worn bags.
+        // The `id <= 4` line: the keyring, -1, the backpack, the four worn bags.
         assert_eq!(slot("-2"), 17, "keyring — an ordinary point, not a case");
         assert_eq!(slot("-1"), 18);
         assert_eq!(slot("0"), 19, "backpack — likewise");
@@ -1520,13 +1211,12 @@ mod tests {
             1,
             "one value on every non-raising path"
         );
-        // `0x40a2b0` truncates toward zero — a C cast, not `floor`.
+        // `0x40a2b0` truncates toward zero, a C cast, not `floor`.
         assert_eq!(slot("2.9"), 21, "2.9 -> 2");
         assert_eq!(slot("-2.9"), 17, "-2.9 -> -2, NOT -3");
     }
 
-    /// A missing or non-number argument **raises** — the only guard in the function is the type
-    /// test, and `0x6f4940` does not return.
+    /// A missing or non-number argument raises: the type test's error `0x6f4940` does not return.
     #[test]
     fn container_id_to_inventory_id_raises_on_a_bad_argument() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/craft.rs b/crates/benilla-ui/src/script/craft.rs
index 482efdf9..34d98f14 100644
--- a/crates/benilla-ui/src/script/craft.rs
+++ b/crates/benilla-ui/src/script/craft.rs
@@ -1,74 +1,11 @@
-//! The craft bindings (decision 0437 phase 3) — the Era-shaped Enchanting-window surface driving a
-//! faithful port of the real 1.12 `CraftFrame` (extracted from `interface.MPQ`:
-//! `Interface\FrameXML\Blizzard_CraftUI\CraftFrame.{xml,lua}`). The exact twin of [`super::tradeskill`]
-//! (same two-way seam, same "no wire" law, same FLAT-list INTERIM): the app pushes a **craft
-//! snapshot** ([`UiScript::set_craft`] — the recipes already resolved to name/subname/icon/
-//! description/reagents/tools/color by the app from `Spell.dbc`/`SkillLineAbility.dbc`/bag counts),
-//! and the Lua `DoCraft`/`CloseCraft` calls queue outbound **intents** the app drains
-//! ([`UiScript::take_craft_dos`] returns spell ids / [`UiScript::take_craft_close`]). The engine holds
-//! no recipe knowledge — a recipe is name/subname/icon/description/difficulty/reagents/tools, all
-//! app-resolved (0437 §"The decision" item 1). `CraftRecipe` reuses [`super::TradeSkillDifficulty`]
-//! outright (0437's own framing: "one solved pattern") rather than a second color enum — the Era
-//! `CraftTypeColor`/`TradeSkillTypeColor` tables are byte-identical (ref `Blizzard_CraftUI.lua:6-13` vs
-//! `Blizzard_TradeSkillUI.lua`'s own table), so the four color keys really are one vocabulary.
+//! The craft bindings the stock `Blizzard_CraftUI` window calls, over the recipe snapshot the app
+//! pushes ([`UiScript::set_craft`]); `DoCraft` and `CloseCraft` queue intents the app drains. The
+//! window has one action button, `DoCraft(GetCraftSelectionIndex())` (`Blizzard_CraftUI.xml:667`),
+//! and no Create All, so a craft intent is a bare spell id.
 //!
-//! ## Where Craft actually differs from TradeSkill (verified against the ref, not assumed)
-//!
-//! - **No Create All.** The 1.12 `CraftFrame` ships one action button (`DoCraft(GetCraftSelectionIndex())`,
-//!   ref `Blizzard_CraftUI.xml:667`) — no repeat-count EditBox, no `GetCraftskillRepeatCount`. `DoCraft`
-//!   therefore queues a bare spell id, never a `(spell id, count)` pair — [`UiScript::take_craft_dos`]
-//!   returns `Vec<u32>`.
-//! - **`GetCraftInfo` is a 7-tuple, not TradeSkill's 4-tuple**: `craftName, craftSubSpellName, craftType,
-//!   numAvailable, isExpanded, trainingPointCost, requiredLevel` (ref l.37/168/289) — the trailing three
-//!   are Beast Training's own fields (a pet ability's training-point cost + the pet's required level).
-//!   Beast Training is out of scope (0437's own line — the pet arc owns it), so v1 hardcodes
-//!   `trainingPointCost = 0` and `requiredLevel = 0` — never nonzero, so every ref branch gated on them
-//!   (`Craft_UpdateTrainingPoints`, the per-row Cost text, the red/green pet-level Requirements line) is
-//!   unreachable and dropped from the ported XML, not merely stubbed (this file's job is the tuple
-//!   shape; the XML's job is not painting dead branches).
-//! - **A recipe carries a `sub_name`** (`craftSubSpellName`) TradeSkill's own recipes never have — the
-//!   ref's row paints it in parens beside the name (`format(TEXT(PARENS_TEMPLATE), craftSubSpellName)`,
-//!   ref l.218) when non-empty. Enchanting itself rarely uses it (most enchant spells have no sub-rank
-//!   text), but the field is real in the ref's own tuple, so it ships in v1 rather than being folded away.
-//! - **A recipe carries a pre-resolved `description`** (`GetCraftDescription`, ref l.312) TradeSkill's
-//!   own recipe never exposes to Lua at all — Enchanting's detail pane shows the spell's flavor/effect
-//!   text above the reagent grid (ref `CraftDescription`), a region TradeSkill's own detail pane has no
-//!   analogue for.
-//! - **No product-item concept.** TradeSkill's `product_item`/`min_made`/`max_made`/`cooldown_secs`
-//!   have no Craft equivalent: an enchant recipe doesn't "create" a bag item the way a tradeskill recipe
-//!   does (it modifies an item in place, or resolves as a pure effect) — `CraftIcon`'s hover shows the
-//!   **spell**, not a product item (`GameTooltip:SetCraftSpell`, ref l.566, vs TradeSkill's
-//!   `SetTradeSkillItem` with no reagent index) — see [`super::tooltip_item`]'s `SetCraftSpell`.
-//! - **`needs_item_target` has no Lua getter.** It is pure app-side bookkeeping (0437 §"What scoping
-//!   verified": `TARGET_FLAG_ITEM` enchant casts need a client-side item pick after `DoCraft`) — the
-//!   ref XML plays no part in that flow (no such concept exists in the real client's item-target UX
-//!   either; it's the cursor/target machinery, not FrameXML). See `CraftFrame.xml`'s own header note.
-//!
-//! ## v1 is FLAT — no header rows (the law landed for TradeSkill; Craft is a named divergence)
-//!
-//! Exactly [`super::tradeskill`]'s own v1 law: [`CraftState::recipes`] renders as one flat row per
-//! recipe, `index` 1-based straight into the list — though the ORDER of that list is now this
-//! module's, not the app's (decision 1124: [`recipe_order`], the craft type's own byte-verified
-//! comparator, applied in [`UiScript::set_craft`]). `GetCraftInfo` therefore never
-//! returns the `"header"` `craftType` the ref Lua also checks for (ref l.38/77/199/252/292). The
-//! header/grouping law itself is no longer pending — decision 0446 confirmed it byte-exact (wow-re
-//! `tradeskill` TU-B) and TradeSkill grew the real tree engine ([`super::tradeskill`]'s `build_groups`)
-//! on it. Craft never got the same port and stays on this v1 flat render; `Expand/CollapseCraftSkillLine`
-//! are still literal no-ops, wired only so the ported XML's header-click handlers don't error
-//! (TradeSkill's `Expand/CollapseTradeSkillSubClass` precedent). 0446 also confirmed the one live case
-//! (Enchanting) renders flat either way — a single group's header suppresses under TradeSkill's own law
-//! too — so the divergence is currently unobservable, but it is real and named as a follow-up in
-//! decision 0530.
-//!
-//! ## The tooltip channels
-//!
-//! `GameTooltip:SetCraftItem(craftIndex, reagentIndex)` is registered in [`super::tooltip_item`],
-//! beside `SetTradeSkillItem`. `GameTooltip:SetCraftSpell(craftIndex)` lives in
-//! [`super::tooltip_spell`] beside `SetTrainerService`, its structural twin: both are SELECTORS
-//! into the shared spell/item builders rather than renderers of their own. The v1 two-line
-//! "name white, description gold" render is gone — `SetCraftSpell 0x533e90` funnels into the same
-//! `0x52e610`/`0x52b650` pair every other content binding does, so two lines were eight-plus short
-//! (wow-re `ui/scratch/trainer-service-tooltip-law.md` §4.1).
+//! Not built: the reference's header rows (`0x4f60c0`). The list is flat, `GetCraftInfo` never
+//! answers `"header"` and `Expand`/`CollapseCraftSkillLine` do nothing; Enchanting, with a single
+//! group, renders flat in the reference too.
 
 use mlua::{Lua, MultiValue, Value, Variadic};
 
@@ -76,35 +13,28 @@ use super::binding_abi::number_arg;
 use super::item_stats::item_link;
 use super::Model;
 
-/// One reagent a recipe consumes (`GetCraftReagentInfo`): the bag-counted need/have plus the resolved
-/// name/icon — both `None` until the app's ask-once item-template answer lands, the same miss path as
-/// [`super::tradeskill::TradeSkillReagent`] (this struct's exact twin).
+/// One reagent a recipe consumes (`GetCraftReagentInfo`); name and icon are `None` until the item
+/// template answer lands.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CraftReagent {
-    /// The reagent's item entry — the tooltip channel key (`GameTooltip:SetCraftItem(i, j)` resolves
-    /// through this, never through `name`/`icon`).
+    /// The item entry `GameTooltip:SetCraftItem` resolves through.
     pub item: u32,
-    /// The resolved display name, or `None` while the ask-once template answer is still in flight.
     pub name: Option<String>,
-    /// The resolved icon texture path, or `None` while still in flight.
     pub icon: Option<String>,
-    /// How many this recipe consumes.
     pub need: u32,
-    /// How many the player's bags currently hold (`count_of`, decision 0269).
     pub have: u32,
 }
 
-/// What `GameTooltip:SetCraftSpell` describes for one row — the pre-resolved output of the
-/// app-side law (`ui_craft::craft_tooltip`, transcribing `SetCraftSpell 0x533e90`).
-/// [`super::TrainerTooltip`]'s twin in shape and its opposite in law: this one tests the recipe's
-/// **own** `Effect[i]` (24 `CREATE_ITEM` → the item, 36 `LEARN_SPELL` → the taught spell), never
-/// `57`, never sets `altCaster`, and does **not** validate that the hop resolves before taking it.
+/// What `GameTooltip:SetCraftSpell` (`0x533e90`) describes for a row, resolved by the app from the
+/// recipe's own `Effect[i]`: 24 `CREATE_ITEM` picks the item, 36 `LEARN_SPELL` the taught spell.
+/// Unlike the trainer's, it never tests 57 (`LEARN_PET_SPELL`), sets no altCaster and never checks
+/// that the target resolves.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum CraftTooltip {
-    /// The ITEM builder, on `EffectItemType[i]` of the matched `CREATE_ITEM` slot.
+    /// The item builder (`0x52b650`) on the matched `CREATE_ITEM` slot's `EffectItemType`.
     Item(u32),
-    /// The SPELL builder, on `EffectTriggerSpell[i]` of the matched `LEARN_SPELL` slot — or on the
-    /// recipe spell itself when no slot matched, which is every enchant.
+    /// The spell builder (`0x52e610`) on the matched `LEARN_SPELL` slot's `EffectTriggerSpell`, or
+    /// on the recipe itself when no slot matches, as for every enchant.
     Spell(u32),
 }
 
@@ -114,99 +44,62 @@ impl Default for CraftTooltip {
     }
 }
 
-/// One recipe row (`GetCraftInfo` + its detail-pane getters): a known spell carrying attr
-/// `SPELL_ATTR_IS_TRADESKILL`, resolved by the app from `Spell.dbc`/`SkillLineAbility.dbc`/bag counts —
-/// [`super::tradeskill::TradeSkillRecipe`]'s twin, minus the product-item concept, plus `sub_name` +
-/// `description` (module doc, "Where Craft actually differs").
+/// One recipe row: a known `SPELL_ATTR_IS_TRADESKILL` spell, resolved by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CraftRecipe {
-    /// The recipe spell id — what `DoCraft` queues as the `CMSG_CAST_SPELL` target.
+    /// What `DoCraft` queues for `CMSG_CAST_SPELL`.
     pub spell_id: u32,
     pub name: String,
-    /// The rank subtext (`craftSubSpellName`, ref `GetCraftInfo`'s 2nd return) — `""` for most
-    /// enchants; painted in parens beside the name when non-empty (ref l.217-221).
+    /// The rank subtext (`craftSubSpellName`), usually empty for an enchant; the stock window
+    /// paints it in parentheses when set (`Blizzard_CraftUI.lua:217-221`).
     pub sub_name: String,
-    /// The color band `GetCraftInfo`'s `craftType` reports — [`super::TradeSkillDifficulty`] REUSED
-    /// outright (module doc) for the four shared keys. The REAL client's Craft string table is
-    /// WIDER (`0x807e00`, pinned 2026-07-17): tier codes shifted 1..4 with `0 → "none"`, plus a
-    /// 5th `"used"` tier — a still-optimal recipe teaching a learnable `SPELL_EFFECT_LEARN_SPELL`,
-    /// which only Beast Training recipes carry. An Enchanting book (this window's one occupant)
-    /// can never produce either extra key, so the shared enum stays honest until the
-    /// beast-training arc feeds one (that arc grows the vocabulary).
+    /// `GetCraftInfo`'s `craftType`: one of the four keys `CraftTypeColor` colours as
+    /// `TradeSkillTypeColor` does (`Blizzard_CraftUI.lua:6-13`). The reference's table
+    /// (`0x807e00`) adds `"none"` and `"used"` (a still-optimal Beast Training recipe teaching a
+    /// learnable spell); Enchanting never produces either, and neither is built.
     pub difficulty: super::TradeSkillDifficulty,
-    /// `min` over reagents of `floor(have/need)` — `0` when any reagent is short; the count
-    /// `GetCraftInfo` reports as `numAvailable`.
+    /// `numAvailable`: the least `floor(have / need)` over the reagents.
     pub num_available: u32,
-    /// The recipe's own icon (there is no separate "product" icon concept for Craft — module doc);
-    /// `None` only while still in flight.
     pub icon: Option<String>,
-    /// The pre-substituted spell description (`GetCraftDescription`) — app-resolved (the $-token
-    /// engine lives app-side, [`super::tooltip_spell`]'s own law). `None` renders as a blank line (ref
-    /// l.316: `CraftDescription:SetText(" ")`, never hidden).
+    /// `GetCraftDescription`, `$`-tokens substituted by the app; `None` paints a blank line
+    /// (`Blizzard_CraftUI.lua:316`).
     pub description: Option<String>,
-    /// An `ENCHANT_ITEM`-family effect: `DoCraft` on this recipe arms an app-side item-target pick
-    /// (0437 §"What scoping verified": `TARGET_FLAG_ITEM`/`TARGET_FLAG_TRADE_ITEM`) — pure app-side
-    /// bookkeeping, no Lua getter (module doc).
+    /// An `ENCHANT_ITEM` effect (`TARGET_FLAG_ITEM`, `TARGET_FLAG_TRADE_ITEM`): `DoCraft` then arms
+    /// an app-side item pick. No Lua getter reads it.
     pub needs_item_target: bool,
-    /// Consumed reagents, in display order (`GetCraftNumReagents`/`GetCraftReagentInfo`).
     pub reagents: Vec<CraftReagent>,
-    /// The Requirements line's tool list — `(tool name, have)` pairs (e.g. `("Runed Copper Rod", true)`);
-    /// exposed to Lua as `GetCraftSpellFocus`'s alternating multivalue
-    /// ([`super::tradeskill::TradeSkillRecipe::tools`]'s twin).
+    /// The Requirements line's `(tool name, have)` pairs (`GetCraftSpellFocus`).
     pub tools: Vec<(String, bool)>,
-    /// What the detail-icon hover describes ([`CraftTooltip`]) — resolved app-side, because the law
-    /// reads `Spell.dbc` effect columns the engine cannot see.
     pub tooltip: CraftTooltip,
-    /// `Spell.dbc spellLevel` (`+0x74`) — the **rank-ordering key** of the Beast Training comparator
-    /// ([`recipe_order`]). Also what `GetCraftInfo`'s `requiredLevel` return is built from, though
-    /// that surface is still hardcoded `0` here (module doc).
+    /// `Spell.dbc` `spellLevel` (`+0x74`), the Beast Training comparator's rank key. The
+    /// reference's `requiredLevel` return comes from it; here that return is 0.
     pub spell_level: u32,
 }
 
-/// One open craft window: the skill line's name/rank, the craft type, and its recipe list. Pushed
-/// whole by the app ([`UiScript::set_craft`]); `None` means the window is closed.
+/// The open craft window, pushed whole by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CraftState {
-    /// The window's title (`GetCraftName`) — e.g. `"Enchanting"`. Also the skill line's display name
-    /// for the rank StatusBar (`GetCraftDisplaySkillLine`'s first return) — Craft has only the one
-    /// name, unlike TradeSkill's separately-fetched `GetTradeSkillLine`.
+    /// The title `GetCraftName` answers, also `GetCraftDisplaySkillLine`'s name.
     pub name: String,
     pub rank: u32,
     pub max_rank: u32,
-    /// The **craft type** — the opener spell's `EffectMiscValue[0]`, which the client stores at
-    /// `ds:0xbdcfb8` (1 Beast Training · 3 Enchanting). It is the comparator switch: `cmp
-    /// ds:0xbdcfb8,1` @ `0x4f6765` picks `0x4f6920` for Beast Training, `0x4f67a0` otherwise.
+    /// The opener spell's `EffectMiscValue[0]`, stored at `ds:0xbdcfb8`: 1 Beast Training, 3
+    /// Enchanting. It picks the row comparator (`0x4f6765`).
     pub craft_type: u32,
-    /// The window's recipe rows in ANY order — [`UiScript::set_craft`] sorts them ([`recipe_order`]);
-    /// `index` is 1-based into the sorted list.
+    /// In any order; [`UiScript::set_craft`] sorts them.
     pub recipes: Vec<CraftRecipe>,
 }
 
-/// The craft type whose comparator carries the extra `spellLevel` key ([`recipe_order`]) — the
-/// opener spell 5149 "Beast Training"'s `EffectMiscValue[0]`. The only other type this window ever
-/// opens with is Enchanting's **3**, which takes the shorter comparator `0x4f67a0`.
+/// Beast Training's craft type, the `EffectMiscValue[0]` of spell 5149.
 const CRAFT_TYPE_BEAST_TRAINING: u32 = 1;
 
-/// The Craft window's **row order** — `0x4f6920` (craft type 1, Beast Training) / `0x4f67a0` (every
-/// other type, i.e. Enchanting), byte-verified in wow-re
-/// (`system/ui/scratch/trainer-craft-list-order.md`, decision 1124). Both are the same cascade and
-/// the Beast Training one has one extra key:
+/// The craft row order: difficulty tier (`[+0xc]`) ascending, then name (collator `0x64a4c0`),
+/// then, at Beast Training only (`0x4f6920`; every other type uses `0x4f67a0`), `spellLevel`
+/// ascending, which orders a pet ability's ranks.
 ///
-/// 1. the **difficulty tier** `[+0xc]` ascending ([`super::TradeSkillDifficulty::tier`]);
-/// 2. the localized **name** (collator `0x64a4c0`);
-/// 3. **`Spell.dbc spellLevel`** (`+0x74`) ascending — **only** in `0x4f6920`. This is the key that
-///    orders a pet ability's ranks, and the whole reason Beast Training needs its own comparator.
-///
-/// What benilla had instead was `SkillLineAbility.req_skill_value`, descending — a column the client
-/// never reads anywhere in its craft TU, and which is a constant `1` on every row of skill line 261
-/// *and* 333 in the shipped DBC. So the primary key was inert and the order collapsed to the name.
-///
-/// The trailing `spell_id` key is **ours, not the client's**: its cascade ends at `spellLevel`, so
-/// rows tying on everything above (Charge's six ranks all carry `spellLevel = 0`) fall through to its
-/// qsort's residue over an array benilla doesn't reproduce. Something must break that tie, and a
-/// deterministic key is the only honest choice — benilla's was a `HashSet`'s iteration order, which
-/// re-shuffled the pane between runs. Ascending spell id is also ascending rank across every 1.12
-/// pet-ability family, so it agrees with the reference wherever the reference is defined.
+/// Deviation: a last `spell_id` key breaks the remaining ties (Charge's six ranks all have
+/// `spellLevel` 0), because the reference leaves them to its qsort over an array benilla does not
+/// reproduce; ascending id is ascending rank in every 1.12 pet-ability family.
 fn recipe_order(a: &CraftRecipe, b: &CraftRecipe, craft_type: u32) -> std::cmp::Ordering {
     a.difficulty
         .tier()
@@ -222,9 +115,8 @@ fn recipe_order(a: &CraftRecipe, b: &CraftRecipe, craft_type: u32) -> std::cmp::
         .then_with(|| a.spell_id.cmp(&b.spell_id))
 }
 
-/// The WoW enUS collator (`0x64a4c0` — the case-**insensitive** one the craft comparators use, unlike
-/// the trainer rows' `0x64a480`), approximated: case-insensitive alphabetical, with the raw bytes as
-/// a stable tie-break so equal-when-folded names keep a deterministic order.
+/// Approximates the case-insensitive enUS collator the craft comparators call (`0x64a4c0`; the
+/// trainer rows use `0x64a480`): case-folded order, raw bytes breaking ties.
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
@@ -232,14 +124,8 @@ fn collate(a: &str, b: &str) -> std::cmp::Ordering {
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open craft window's recipe snapshot. Snapshots re-push every
-    /// time a resolved field changes — no diffing happens here. On a push, the engine **sorts the
-    /// rows** into the craft type's own order ([`recipe_order`] — the ordering is the engine's, like
-    /// the trainer tree's and the tradeskill list's, so one binding's verified comparator lives in
-    /// exactly one place) and then **preserves the selection across the replace**: if the previously
-    /// selected recipe's spell id still appears in the new list, the selection follows it to its new
-    /// index; otherwise it clears to `0` ([`super::tradeskill::set_trade_skill`]'s own
-    /// selection-survival law, verbatim). Clearing (`None`) always resets the selection.
+    /// Push the open craft window's snapshot, or clear it with `None`. A push sorts the rows and
+    /// keeps the selection on its spell id, clearing it when that recipe is gone.
     pub fn set_craft(&mut self, state: Option<CraftState>) {
         let mut model = self.model_mut();
         match state {
@@ -263,33 +149,27 @@ impl super::UiScript {
         }
     }
 
-    /// Drain the spell id intents `DoCraft` queued since the last call — the engine resolves each
-    /// clicked recipe's INDEX to its spell id, so the app sends `CMSG_CAST_SPELL` without needing the
-    /// index mapping. NO count: unlike [`super::tradeskill::take_trade_skill_dos`], the 1.12 CraftFrame
-    /// has no Create All (module doc) — one `DoCraft` call, one queued spell id.
+    /// Drain the spell ids `DoCraft` queued, one per call, with no count.
     pub fn take_craft_dos(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().craft_dos)
     }
 
-    /// Whether `CloseCraft` was called since the last drain (and clear the flag). Like
-    /// [`super::tradeskill::take_trade_skill_close`], the client-side close sends no packet.
+    /// Whether `CloseCraft` was called since the last drain; the close sends no packet.
     pub fn take_craft_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().craft_close)
     }
 }
 
-/// The recipe at a 1-based index, or `None` when out of range / no window is open.
+/// The recipe at a 1-based index.
 fn recipe(model: &Model, index: usize) -> Option<&CraftRecipe> {
     let n = index.checked_sub(1)?;
     model.craft.as_ref()?.recipes.get(n)
 }
 
-/// The recipe count of the open window (`0` when none is open).
 fn num_recipes(model: &Model) -> usize {
     model.craft.as_ref().map_or(0, |c| c.recipes.len())
 }
 
-/// An optional string as a Lua value (`nil` when absent).
 fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     Ok(match s {
         Some(s) => Value::String(lua.create_string(s)?),
@@ -297,7 +177,7 @@ fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     })
 }
 
-/// A `bool` as the Era `1`/`nil` shape.
+/// A `bool` as the reference's `1` or nil.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -310,9 +190,8 @@ fn era_bool(b: bool) -> Value {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetCraftName() → the window's title ("UNKNOWN" when closed — TradeSkill's own
-    // GetTradeSkillLine no-window convention, since the ref gives Craft no documented closed shape of
-    // its own; CraftFrameTitleText:SetText(GetCraftName()) is called unconditionally, ref l.101).
+    // GetCraftName() → the title, or "UNKNOWN" when closed (the reference's closed answer is
+    // untraced); the stock window sets its title unconditionally (`Blizzard_CraftUI.lua:101`).
     g.set(
         "GetCraftName",
         lua.create_function(|lua, ()| {
@@ -325,9 +204,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftDisplaySkillLine() → name, rank, maxRank; name is NIL when closed (ref l.108-109 tests
-    // it for truthiness to Show/Hide the whole rank StatusBar) — unlike GetCraftName above, which
-    // always returns a string.
+    // GetCraftDisplaySkillLine() → name, rank, maxRank; the name is nil when closed, which hides
+    // the rank bar (`Blizzard_CraftUI.lua:108-109`).
     g.set(
         "GetCraftDisplaySkillLine",
         lua.create_function(|lua, ()| {
@@ -344,7 +222,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the number of recipes the open window offers (0 when closed).
+    // GetNumCrafts() → the recipe count, 0 when closed.
     g.set(
         "GetNumCrafts",
         lua.create_function(|lua, ()| {
@@ -353,19 +231,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftInfo(index) → craftName, craftSubSpellName, craftType, numAvailable, isExpanded,
-    // trainingPointCost, requiredLevel (ref l.37/168/289's own 7-tuple — module doc). `craftType` is
-    // the difficulty color key, never "header"; `isExpanded` is always nil; the trailing two are
-    // Beast Training's own fields, hardcoded 0 (out of scope, module doc). OOB → a single nil.
-    // The two link verbs (wow-re `tradeskill/scratch/tradeskill-craft-item-links.md`, 1973).
-    //
-    // GetCraftItemLink(index) — `0x4f72a0`: the number gate raises its Usage; then the spell's
-    // Spell.dbc `castUI` decides. An Enchanting recipe (`castUI == 3` — this window's craft type,
-    // and the only shipped input: every castUI-3 row, including the twenty that create an item
-    // such as Runed Copper Rod) takes the ENCHANT leg, which cannot fail:
-    // `|cffffffff|Henchant:<spellId>|h[<spell name>]|h|r` — fixed white, the spell's id and name.
-    // Any other craft type would scan the effects for CREATE_ITEM, which no shipped row carries,
-    // and answer ZERO values — Beast Training's rows do.
+    // GetCraftItemLink(index) (`0x4f72a0`): a non-number raises its usage. The reference keys on
+    // the spell's `castUI`: 3, Enchanting's craft type, for which the type stands in here, answers
+    // `|cffffffff|Henchant:<spell id>|h[<spell name>]|h|r` and cannot miss, even for the twenty
+    // recipes that create an item; any other type scans for a `CREATE_ITEM` effect no shipped row
+    // has, so Beast Training answers zero values.
     g.set(
         "GetCraftItemLink",
         lua.create_function(|lua, index: Value| {
@@ -383,9 +253,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftReagentItemLink(index, reagentIndex) — `0x4f7730`, a byte-clone of the trade-skill
-    // one with its own Usage: both arguments number-gated, `reagentIndex` 1-based over the
-    // non-empty slots, ALWAYS one value — the reagent's `|Hitem:` link or nil.
+    // GetCraftReagentItemLink(index, reagentIndex) (`0x4f7730`): both arguments number-gated,
+    // `reagentIndex` counting the non-empty slots from 1; always one value, the item link or nil.
     g.set(
         "GetCraftReagentItemLink",
         lua.create_function(|lua, (index, reagent): (Value, Value)| {
@@ -411,6 +280,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
+    // GetCraftInfo(index) → craftName, craftSubSpellName, craftType, numAvailable, isExpanded,
+    // trainingPointCost, requiredLevel (`Blizzard_CraftUI.lua:168`); one nil past the end.
+    // `isExpanded` is always nil; Beast Training's cost and level answer 0, not built.
     g.set(
         "GetCraftInfo",
         lua.create_function(|lua, index: usize| {
@@ -430,7 +302,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftIcon(index) → icon texture path (nil while in flight / OOB).
+    // GetCraftIcon(index) → the icon path, nil while in flight or past the end.
     g.set(
         "GetCraftIcon",
         lua.create_function(|lua, index: usize| {
@@ -439,8 +311,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftDescription(index) → the pre-substituted description, or nil (no description / OOB) —
-    // ref l.312 tests this return for truthiness before painting it.
+    // GetCraftDescription(index) → the description or nil, which the stock window tests before
+    // painting (`Blizzard_CraftUI.lua:312`).
     g.set(
         "GetCraftDescription",
         lua.create_function(|lua, index: usize| {
@@ -452,7 +324,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftNumReagents(index) → this recipe's reagent count (0 when OOB / no window).
+    // GetCraftNumReagents(index) → the reagent count, 0 past the end or when closed.
     g.set(
         "GetCraftNumReagents",
         lua.create_function(|lua, index: usize| {
@@ -461,8 +333,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftReagentInfo(index, reagentIndex) → name, icon, need, have (a single nil when the
-    // recipe/reagent index is OOB) — TradeSkill's own GetTradeSkillReagentInfo shape, verbatim.
+    // GetCraftReagentInfo(index, reagentIndex) → name, icon, need, have; one nil past the end.
     g.set(
         "GetCraftReagentInfo",
         lua.create_function(|lua, (index, reagent_index): (usize, usize)| {
@@ -481,9 +352,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftSpellFocus(index) → an alternating (name, has) multivalue, one pair per Requirements
-    // tool (e.g. "Runed Copper Rod", 1) — fed into BuildColoredListString (ref l.361), TradeSkill's
-    // own GetTradeSkillTools shape. Empty when the recipe has no tools / index is OOB.
+    // GetCraftSpellFocus(index) → name, has for each required tool, alternating, the shape
+    // `BuildColoredListString` takes (`Blizzard_CraftUI.lua:361`); nothing when there are none.
     g.set(
         "GetCraftSpellFocus",
         lua.create_function(|lua, index: usize| {
@@ -499,17 +369,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCraftButtonToken() → "CREATE" (v1 constant): the ref resolves the Create button's label via
-    // getglobal(GetCraftButtonToken()) (ref l.106), swapping to a "TRAIN" token for Beast Training —
-    // out of scope (module doc), so this always returns the one token.
+    // GetCraftButtonToken() → "CREATE", the global naming the button's label
+    // (`Blizzard_CraftUI.lua:106`); Beast Training's "TRAIN" is not built.
     g.set(
         "GetCraftButtonToken",
         lua.create_function(|lua, ()| Ok(Value::String(lua.create_string("CREATE")?)))?,
     )?;
 
-    // GetCraftSelectionIndex() / SelectCraft(index) — the engine-held selection (1-based, 0 = none).
-    // Out-of-range selects clear it; the getter clamps to the current recipe count — TradeSkill's own
-    // selection contract, verbatim.
+    // SelectCraft(index) / GetCraftSelectionIndex(): the selection, 1-based with 0 for none; an
+    // out-of-range select clears it, and the getter answers 0 past the recipe count.
     g.set(
         "SelectCraft",
         lua.create_function(|lua, index: u32| {
@@ -533,7 +401,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // DoCraft(index) — queue the recipe's SPELL ID (no count, module doc). Out of range → ignored.
+    // DoCraft(index): queue the row's spell id; out of range is ignored.
     g.set(
         "DoCraft",
         lua.create_function(|lua, index: usize| {
@@ -545,8 +413,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseCraft() — client-side close (no packet, vanilla): flag it so the app clears its local
-    // state.
+    // CloseCraft(): no packet; the flag tells the app to clear its state.
     g.set(
         "CloseCraft",
         lua.create_function(|lua, ()| {
@@ -556,10 +423,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Expand/CollapseCraftSkillLine(index) — no-ops in v1: the recipe list is flat (the header law
-    // landed for TradeSkill, decision 0446, but was never ported here — module doc), so the ported
-    // XML's header-click handlers have nothing to fold — TradeSkill's own
-    // Expand/CollapseTradeSkillSubClass precedent.
+    // Expand/CollapseCraftSkillLine(index): no-ops over the flat list (module doc).
     g.set(
         "ExpandCraftSkillLine",
         lua.create_function(|_, _args: Variadic<Value>| Ok(()))?,
@@ -577,10 +441,9 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// Enchanting's `EffectMiscValue[0]` — the craft type whose comparator has no `spellLevel` key.
+    /// Enchanting's craft type, whose comparator has no `spellLevel` key.
     const CRAFT_TYPE_ENCHANTING: u32 = 3;
 
-    /// One recipe fixture — a single-reagent, single-tool row, distinct spell ids per name.
     fn recipe(
         spell_id: u32,
         name: &str,
@@ -589,8 +452,6 @@ mod tests {
     ) -> CraftRecipe {
         CraftRecipe {
             spell_id,
-            // The fixture's default subject: the recipe itself (the enchant case — no matching
-            // effect slot), so a test that cares about the item arm sets it explicitly.
             tooltip: CraftTooltip::Spell(spell_id),
             name: name.into(),
             sub_name: String::new(),
@@ -611,10 +472,7 @@ mod tests {
         }
     }
 
-    /// A two-recipe Enchanting window: Minor Beastslaying (trivial, craftable) and Minor Health
-    /// (optimal, out of reagents). Declared trivial-first on purpose — the engine sorts by
-    /// difficulty tier ascending ([`recipe_order`]), so the window renders **Minor Health at index 1**
-    /// and Beastslaying at 2, whatever order the app pushed.
+    /// Two Enchanting recipes, pushed trivial first; the sort puts Minor Health at index 1.
     fn state() -> CraftState {
         CraftState {
             name: "Enchanting".into(),
@@ -711,11 +569,10 @@ mod tests {
             "CREATE"
         );
 
-        // A header row never appears in v1 — GetCraftInfo's type is always a difficulty band.
         assert!(s
             .eval::<bool>("local _,_,t = GetCraftInfo(1) return t ~= 'header'")
             .unwrap());
-        // Expand/CollapseCraftSkillLine are wired but do nothing observable.
+        // Expand and collapse do nothing.
         s.run("ExpandCraftSkillLine(1) CollapseCraftSkillLine(1)")
             .unwrap();
         assert_eq!(s.eval::<i64>("return GetNumCrafts()").unwrap(), 2);
@@ -729,15 +586,13 @@ mod tests {
         s.run("SelectCraft(2)").unwrap();
         assert_eq!(s.eval::<i64>("return GetCraftSelectionIndex()").unwrap(), 2);
 
-        // A re-list that turns 7418 optimal moves it to index 1 — the selection FOLLOWS the spell
-        // id, not the index (and this is the case the engine-side sort makes reachable).
+        // Turning 7418 optimal moves it to index 1, and the selection follows the spell id.
         let mut promoted = state();
         promoted.recipes[0].difficulty = super::super::TradeSkillDifficulty::Optimal;
         promoted.recipes[0].name = "Aaa Beastslaying".into();
         s.set_craft(Some(promoted));
         assert_eq!(s.eval::<i64>("return GetCraftSelectionIndex()").unwrap(), 1);
 
-        // A re-push that drops the selected recipe entirely clears the selection.
         let mut without_7418 = state();
         without_7418.recipes.remove(0);
         s.set_craft(Some(without_7418));
@@ -757,7 +612,6 @@ mod tests {
         );
         assert!(s.take_craft_dos().is_empty(), "drained");
 
-        // An out-of-range index is ignored.
         s.run("DoCraft(9)").unwrap();
         assert!(s.take_craft_dos().is_empty());
     }
@@ -809,7 +663,7 @@ mod tests {
             ("Runed Copper Rod", Some(1), "Arcanite Rod", None)
         );
 
-        // A recipe with no tools returns an empty multivalue (arity 0, not one nil).
+        // No tools: zero values, not one nil.
         let mut c2 = state();
         c2.recipes[1].tools.clear();
         s.set_craft(Some(c2));
@@ -832,15 +686,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetCraftSelectionIndex()").unwrap(), 0);
     }
 
-    /// **Beast Training's rank order** (decision 1124), pinned against wow-re's emulated run of the
-    /// real `0x4f6920` over real `Spell.dbc` values — and the regression for the director's report
-    /// that "Beast Training lists a skill's ranks out of ascending order" (ledger B229).
-    ///
-    /// The fixture is the reported pane: four Arcane Resistance ranks and four Fire Resistance
-    /// ranks, pushed **shuffled** (as a `HashSet`'s iteration order used to deliver them), all on
-    /// one difficulty tier because pet abilities carry no trivial ranks. Name groups them; the
-    /// `spellLevel` key — 20/30/40/50 per rank — is what orders the ranks inside a group, and it is
-    /// the key the old `req_skill_value`-descending sort did not have.
+    /// The expected order is an emulated run of `0x4f6920` over the shipped `Spell.dbc` values.
     #[test]
     fn beast_training_orders_ranks_by_spell_level() {
         let rank = |spell_id: u32, name: &str, level: u32| CraftRecipe {
@@ -857,7 +703,7 @@ mod tests {
             tools: vec![],
             spell_level: level,
         };
-        // Shuffled on purpose — the exact shape of the report (Arcane read 1, 4, 3, 5).
+        // Shuffled on purpose.
         let recipes = vec![
             rank(24508, "Arcane Resistance", 30),
             rank(24441, "Fire Resistance", 30),
@@ -897,10 +743,8 @@ mod tests {
             ]
         );
 
-        // The falsifiable control wow-re ran: the SAME rows at the Enchanting craft type select
-        // `0x4f67a0`, which has no `spellLevel` key — so the ranks fall to the trailing spell-id
-        // tie-break instead. That they still come out ascending here is benilla's determinism, not
-        // the reference's order; what matters is that the two types differ at all.
+        // The same rows at the Enchanting type take `0x4f67a0`, with no `spellLevel` key: the ranks
+        // fall to the spell-id tie-break, benilla's order rather than the reference's.
         s.set_craft(Some(CraftState {
             name: "Beast Training".into(),
             rank: 0,
@@ -922,15 +766,11 @@ mod tests {
         );
     }
 
-    /// The craft link pair (wow-re `tradeskill-craft-item-links.md`, 1973): an Enchanting recipe
-    /// answers the ENCHANT link — fixed white, the spell's id and name — and cannot miss; another
-    /// craft type answers zero values (no shipped CREATE_ITEM input); the reagent link is nil
-    /// until its template is in the store, then the item link in its quality colour; the raises.
     #[test]
     fn the_craft_link_verbs_answer_the_clients_shapes() {
         let mut s = UiScript::new().unwrap();
         s.set_craft(Some(state()));
-        // Row 1 is whichever recipe the window's own order puts first: the link names THAT spell.
+        // Row 1 is whichever recipe sorts first.
         let first = s.eval::<String>("return (GetCraftInfo(1))").unwrap();
         let spell = state()
             .recipes
diff --git a/crates/benilla-ui/src/script/cursor.rs b/crates/benilla-ui/src/script/cursor.rs
index c5b29e81..5c371459 100644
--- a/crates/benilla-ui/src/script/cursor.rs
+++ b/crates/benilla-ui/src/script/cursor.rs
@@ -1,15 +1,7 @@
-//! The cursor payload (decision 0216, slice 1) — the client's payload-mode global `[0xb4d900]`
-//! as a typed enum, and the drag-gesture mechanics (`RegisterForDrag`/`OnDragStart`/`OnDragStop`/
-//! `OnReceiveDrag`) that transition it. One seam for every surface — bags, the paper doll
-//! ([`doll`], decision 0208 phase 1b), action bars ([`bar`], decision 0216 §7/0218 §4), and the
-//! spellbook ([`super::spellbook`]'s `PickupSpell`, slice 5 — the [`CursorSpell`] producer) — so
-//! sounds, `CURSOR_UPDATE`, grid events, and lock display can't drift apart per window.
-//!
-//! [`container`](super::container)'s `pickup_container_item`, [`doll`]'s
-//! `pickup_inventory_item`, and [`bar`]'s `pickup_action`/`place_action` (the surface-specific
-//! transition bodies) all route through [`queue_cursor_update`]/[`queue_lock_changed`], the one
-//! place those events fire from. [`bar`], [`doll`], and [`drag`] are split out purely for size —
-//! this file keeps the payload types, the shared transition seam, and `install`.
+//! The cursor payload: the client's payload-mode global `[0xb4d900]` as a typed enum, and the drag
+//! gestures ([`drag`]) that change it. Bags, the paper doll ([`doll`]), the action bars ([`bar`])
+//! and the spellbook all transition it through [`queue_cursor_update`] and [`queue_lock_changed`],
+//! so sounds, `CURSOR_UPDATE`, grid events and lock display fire from one place.
 
 use mlua::{Lua, Value};
 
@@ -27,28 +19,17 @@ pub(crate) use drag::{
     abandon_drag, arm_drag, maybe_start_drag, take_drag, DragGesture, DragRelease,
 };
 
-/// The sentinel bag id that folds the player's EQUIPPED slots into the ONE payload space
-/// (decision 0216 §1, extended to the paper doll by decision 0208 phase 1b): a
-/// [`CursorItem`]/[`super::container::ContainerMove`] whose `bag` is `EQUIPMENT_BAG` addresses
-/// `slot` as a 1-based live-API inventory slot id — `GetInventorySlotInfo`'s own numbering
-/// (HeadSlot=1 … TabardSlot=19, `char_stats::SLOT_INFO`'s convention), not a bag's contents.
-/// Disjoint from every real bag id — including the ERA's own negative container ids, which are
-/// real API surface (−1 = `BANK_CONTAINER`, decision 0604; −2 = the keyring) — so a `match` on
-/// `bag` can never confuse the spaces (its original value −1 collided with the bank the day the
-/// bank landed; the sentinel is engine-internal and never crosses the Lua boundary as a value,
-/// verified across the XML fleet at the change). Ammo (id 0) stays OUT of this space — a named
-/// deferral ([`doll::pickup_inventory_item`]'s own range guard).
+/// Sentinel bag id for the player's equipped slots, whose `slot` is a 1-based inventory slot id
+/// (`GetInventorySlotInfo`'s, HeadSlot = 1). Never a Lua value, and disjoint from every real bag
+/// id, -1 the bank and -2 the keyring included. Ammo (slot 0) is outside it.
 pub const EQUIPMENT_BAG: i64 = -100;
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 // The payload
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// What the cursor carries — the client's payload-mode global [0xb4d900] as a typed enum
-/// (wow-re cursor-dragdrop-payload.md §1: 1 = live item, 3 = spell, **4 = pet action**, **8 =
-/// macro**, **10 = stabled pet**; our Action arm is the client's bar-slot pickup; the money arm
-/// is mode 2 ([`CursorMoney`], 1962/1965) and the preview arm stays unbuilt). One transition seam
-/// for every surface, so sounds, CURSOR_UPDATE, and lock display can't drift apart per window (decision 0216).
+/// What the cursor carries, by the client's payload mode `[0xb4d900]`: 1 item, 2 money, 3 spell,
+/// 4 pet action, 5 vendor row, 8 macro, 10 stabled pet; `Action` is the bar-slot pickup.
 #[derive(Clone, Debug, PartialEq)]
 pub enum CursorPayload {
     Item(CursorItem),
@@ -56,125 +37,69 @@ pub enum CursorPayload {
     Action(CursorAction),
     Macro(CursorMacro),
     PetAction(CursorPetAction),
-    /// A vendor row grabbed off the merchant window — **mode 5** (see [`CursorMerchantItem`]).
-    ///
-    /// Deliberately NOT `Item`: the reference's `CursorHasItem 0x4895d0` answers truthy for modes
-    /// **1 and 9 only**, so all thirteen stock `CursorHasItem()` gates (TradeFrame, MailFrame,
-    /// PlayerFrame, TargetFrame, PetFrame, StaticPopup, the keyring…) exclude a vendor cursor.
-    /// Making this an `Item` variant would silently open every one of them.
+    /// Mode 5, a vendor row. Not an `Item`: `CursorHasItem` (`0x4895d0`) is true for modes 1 and 9
+    /// only, so all thirteen stock `CursorHasItem()` gates stay shut while one is held.
     Merchant(CursorMerchantItem),
-    /// A pet picked up from the stable window — **mode 10** (see [`CursorStablePet`]).
-    ///
-    /// Mode 10 was recorded as "class/talent ability (DBC)" until wow-re's stable-master carve
-    /// corrected it (`system/ui/scratch/stable-master-window.md` §9; decision 1677): `0x495020` is
-    /// the stabled-pet grab, `[0xb4d900] = 10` is written at exactly one site image-wide, and it is
-    /// inside it. benilla built the stable's drag frame-locally on the strength of the old note —
-    /// this variant is what puts it back on the shared cursor, so a stable pet dropped on the world
-    /// or another window clears through the same path as every other payload.
+    /// Mode 10, a pet taken from the stable; its grab `0x495010` is the only writer of mode 10.
     StablePet(CursorStablePet),
-    /// Coins picked up off a money frame — **mode 2** (see [`CursorMoney`]).
+    /// Mode 2, coins taken off a money frame.
     Money(CursorMoney),
 }
 
-/// Copper held on the cursor — payload **mode 2**, the client's `[0xb4e2f0]` amount written by
-/// `0x494cc0` from `PickupPlayerMoney 0x48abc0` with `LOOTWINDOWCOINSOUND` (wow-re
-/// `cursor-dragdrop-payload.md` §1's payload table). The purse is never debited by the pickup:
-/// the stock `MoneyTypeInfo["PLAYER"]` shows `GetMoney() - GetCursorMoney() - …`, the subtraction
-/// being how the held coins leave the display while the money stays yours (1962).
+/// Copper held on the cursor, mode 2 (`[0xb4e2f0]`, set by `PickupPlayerMoney`, `0x48abc0`). The
+/// purse is not debited; the stock money frame subtracts `GetCursorMoney()` (`MoneyFrame.lua:17`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct CursorMoney {
     pub copper: u32,
 }
 
-/// A vendor row held on the cursor — payload **mode 5**, set by `PickupMerchantItem 0x4fb760`.
-///
-/// **A buy-on-drop cursor, not an item cursor.** The reference writes three globals and this
-/// mirrors all three: the item entry (`0xb4b41c`), the display id that drives the icon
-/// (`0xb4d8ec` — we carry the resolved texture path, which is the same thing one hop later), and
-/// the **0-based** vendor row (`0xb4b420`). Dropping it on a bag slot sends
-/// `CMSG_BUY_ITEM_IN_SLOT 0x1a3`; dropping it on the world, pressing ESC, or the vendor window
-/// closing is a plain clear with **no packet**.
-///
-/// No Lua predicate reports it. `CursorHasItem`, `CursorHasSpell`, `CursorHasMoney` and
-/// `CursorCanGoInSlot` are all nil for mode 5 — no registered binding exposes it at all.
+/// A vendor row held on the cursor, mode 5, set by `PickupMerchantItem` (`0x4fb760`). A drop on a
+/// bag slot is the buy (`CMSG_BUY_ITEM_IN_SLOT`, `0x1a3`); in the reference a drop on the world,
+/// ESC or the vendor closing clears it with no packet. No registered binding reports mode 5 to Lua.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct CursorMerchantItem {
-    /// The row's item template entry — `0xb4b41c`, and what the buy addresses.
+    /// The row's item entry (`0xb4b41c`), which the buy names.
     pub item_id: u32,
-    /// The vendor row this came from, **0-based** (`0xb4b420` = `trunc(arg) - 1`). Kept because
-    /// the reference keeps it: a second `PickupMerchantItem` naming the same row is a toggle-off,
-    /// which is the only thing that reads it back.
+    /// The 0-based vendor row (`0xb4b420` = `trunc(arg) - 1`): a second `PickupMerchantItem` on the
+    /// same row drops the grab.
     pub row: u32,
-    /// The icon drawn at the mouse. The reference stores `ItemDisplayInfo`'s id (`0xb4d8ec`) and
-    /// resolves the art from it; we hold the already-resolved path, which is the same value one
-    /// hop later and the shape every other payload here uses.
+    /// The icon at the mouse, resolved from the display id the reference stores (`0xb4d8ec`).
     pub texture: Option<String>,
 }
 
-/// A pet held on the cursor from the stable window — payload **mode 10** (`0x495020`, the grab
-/// `0x495010`).
-///
-/// Mode 10 was recorded as "class/talent ability (DBC)" until wow-re's stable-master carve
-/// corrected it (`system/ui/scratch/stable-master-window.md` §9; decision 1677): `[0xb4d900] = 10`
-/// is written at exactly one site image-wide and it is inside the stabled-pet grab, whose id global
-/// `[0xb4e300]` holds a **stable index**, not a spell. benilla first built the stable's drag
-/// frame-locally on the strength of the old note; this puts it on the shared cursor.
+/// A pet held on the cursor from the stable window, mode 10, set by the grab `0x495010`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct CursorStablePet {
-    /// The slot the grab came from, in the Lua index space `PickupStablePet` takes (`0` = the
-    /// summoned pet, `1..=2` a stable slot) — the client's `[0xb4e300]`.
+    /// `[0xb4e300]`, in `PickupStablePet`'s index space: 0 the summoned pet, 1..=2 a stable slot.
     pub slot: u8,
-    /// The family icon drawn at the mouse. Not merely decoration: a **non-empty icon path is the
-    /// grab's own gate** (`0x495010` refuses without one), so a payload of this shape always has
-    /// one.
+    /// The family icon at the mouse, never empty: the grab refuses a pet without one (`0x495010`).
     pub texture: String,
 }
 
-/// The item currently held on the cursor (`PickupContainerItem`/`SplitContainerItem`/
-/// `PickupInventoryItem` set it). The real client's drag state: it names *where the item was
-/// picked from* (so a second click routes the swap) and carries the icon the app draws at the
-/// mouse. Purely transient — cleared on place/cancel; the server's field updates do the actual
-/// move.
+/// An item held on the cursor: where it was picked from, so the next click routes the swap, and
+/// the icon at the mouse. The server's field updates do the actual move.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorItem {
-    /// Live-API bag id the item was picked up from (0 = backpack, 1..=4 an equipped bag,
-    /// [`EQUIPMENT_BAG`] the player's own equipped slots).
+    /// The source bag id in the Lua API's numbering, or [`EQUIPMENT_BAG`].
     pub bag: i64,
-    /// 1-based slot the item was picked up from.
+    /// The 1-based source slot.
     pub slot: u32,
-    /// The picked item's template entry (`GetCursorInfo`'s itemID).
     pub item_id: u32,
-    /// The icon texture path to draw at the mouse (`Interface\Icons\…`); `None` if unresolved.
     pub texture: Option<String>,
-    /// The item link (`GetCursorInfo`'s itemLink), when known.
     pub link: Option<String>,
-    /// A split carry (`SplitContainerItem` picked up `n` of the stack); `None` = the whole stack.
+    /// `Some(n)` for a split of `n`, `None` for the whole stack.
     pub count: Option<u32>,
-    /// The item's quality (0..6) at pickup, carried so `DELETE_ITEM_CONFIRM` (a world drop) can
-    /// report it without a container round-trip.
+    /// Quality (0..6) at pickup, for a world drop's `DELETE_ITEM_CONFIRM`.
     pub quality: Option<u32>,
-    /// The 1-based live-API inventory slot ids this item could be EQUIPPED into (empty = not
-    /// equippable), captured at pickup from the source's own `equip_slots` (the container slot's
-    /// or the doll slot view's — decision 0208 phase 1b's "the fit rule").
-    /// [`doll::pickup_inventory_item`] reads it to decide a place-onto-doll-slot's fit;
-    /// [`doll::cursor_can_go_in_slot`] serves it straight to `CURSOR_UPDATE`'s highlight.
+    /// The 1-based inventory slot ids the item can be equipped into, empty if none: the paper
+    /// doll's place and `CursorCanGoInSlot` read it.
     pub equip_slots: Vec<u8>,
-    /// Whether this item may be placed on an ACTION-BAR slot, captured at pickup from the
-    /// source's own `bar_placeable` — `PlaceAction`'s only item filter (decision 0666).
+    /// Whether `PlaceAction` accepts it, its only item filter.
     pub bar_placeable: bool,
 }
 
-/// How many items the cursor is actually holding, for a payload picked up from a bag.
-///
-/// [`CursorItem::count`] is `None` for a **whole-stack** pickup — it records only what a *split*
-/// carry took — so reading it as `unwrap_or(1)` answers 1 for a stack of twenty. That is a
-/// display wart on a mail attachment and a real arithmetic error on an auction deposit, which is
-/// computed per stack: it would quote a twentieth of what the server then charges. So the true
-/// size comes back from the source slot, which still holds the stack (a pickup locks the slot, it
-/// does not empty it).
-///
-/// Falls back to 1 only when the source slot is genuinely unreadable — a bag the app has not
-/// pushed, or a slot that changed under us.
+/// How many items the cursor holds. A whole-stack pickup has `count: None`, so the size is read
+/// from the source slot, which a pickup locks but does not empty; 1 if that slot is unreadable.
 pub(super) fn held_count(model: &super::Model, item: &CursorItem) -> u32 {
     if let Some(n) = item.count {
         return n.max(1);
@@ -187,23 +112,19 @@ pub(super) fn held_count(model: &super::Model, item: &CursorItem) -> u32 {
         .map_or(1, |s| s.count.max(1))
 }
 
-/// A spell payload ([`super::spellbook`]'s `PickupSpell` produces it): the spellbook slot it was
-/// picked from, its book (`"spell"`/`"pet"`, the Era `GetCursorInfo` shape), and the resolved
-/// spell id.
+/// A spell payload, mode 3, from `PickupSpell` on the player's spellbook.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorSpell {
     pub book_slot: u32,
     pub book_type: String,
     pub spell_id: u32,
     pub texture: Option<String>,
-    /// `Attributes & 0x40` (`SPELL_ATTR_PASSIVE`) — a passive cannot go on the action bar
-    /// (`PlaceAction`'s other filter, `0x4e63ad`; decision 0666).
+    /// `Attributes & 0x40` (`SPELL_ATTR_PASSIVE`): `PlaceAction` refuses a passive (`0x4e63ad`).
     pub passive: bool,
 }
 
-/// An action-slot payload ([`bar`]'s `PickupAction`/`place_action` hop produces it): the source
-/// action slot, the packed action's kind byte (SPELL/MACRO/ITEM — decision 0216's
-/// `CMSG_SET_ACTION_BUTTON` type byte), and the action id itself.
+/// An action-bar payload from `PickupAction`: the source slot, the action's type byte as
+/// `CMSG_SET_ACTION_BUTTON` packs it (spell, macro or item) and its id.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorAction {
     pub src_slot: u32,
@@ -212,72 +133,49 @@ pub struct CursorAction {
     pub texture: Option<String>,
 }
 
-/// A pet-bar payload ([`pet`]'s `PickupPetAction` produces it) — the client's cursor mode **4**,
-/// whose payload global `[0xb4e2f8]` is the picked slot's **packed word, copied verbatim** (its
-/// sole writer `0x494f0c` is a plain `mov edx,[edi]; mov [0xb4e2f8],edx`; decision 1010).
-///
-/// The word is the payload, and that is the whole design: the drop trampoline `0x4bce00` forwards
-/// this dword into the assign core without reading a field of it, so a slot's contents after any
-/// accepted drop is a word that already existed elsewhere in client state. Nothing is encoded at
-/// drop time and nothing here needs decoding.
-///
-/// This payload is **pet-bar-only**. `PlaceAction` refuses it (wow-re `action-item-slot.md`'s
-/// payload table: pet actions and class abilities are the refused modes, macros are not), and
-/// nothing else produces it — which is also why a pet bar can only ever be *rearranged*, never
-/// populated from the spellbook: its contents are the server's.
+/// A pet-bar payload, mode 4, from `PickupPetAction` or the pet spellbook: the packed action word
+/// copied verbatim into `[0xb4e2f8]` (`0x494f0c`) and dropped undecoded (`0x4bce00`). Pet bar
+/// only: `PlaceAction` refuses it (`0x4e62e0`).
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorPetAction {
-    /// The 1-based pet bar slot it was picked from.
+    /// The 1-based pet bar slot it came from, 0 from the spellbook.
     pub src_slot: u32,
-    /// The slot's packed word, verbatim.
+    /// The packed action word, verbatim.
     pub packed: u32,
-    /// `Attributes & 0x40` for a spell word — carried because the assign core's one source filter
-    /// tests it at DROP time, not at pickup (`0x4bc9f8`).
+    /// `Attributes & 0x40` of a spell word, tested at the drop, not the pickup (`0x4bc9f8`).
     pub passive: bool,
     pub texture: Option<String>,
 }
 
-/// A macro payload ([`super::macros`]'s `PickupMacro` produces it) — the client's cursor mode
-/// **8**, whose payload global is the bare macro id (`[0xb4e2fc]`, wow-re `action-item-slot.md`'s
-/// payload table, where mode 8 is the ONE non-item/non-spell payload `PlaceAction` accepts).
-/// Unlike every other arm this one carries no source slot to swap back to: a macro lives in the
-/// macro table, not in the surface it was dragged from, so a refused place just leaves it held.
+/// A macro payload from `PickupMacro`, mode 8: the bare macro id (`[0xb4e2fc]`), which
+/// `PlaceAction` accepts (`0x4e62e0`). It has no source slot, so a refused place leaves it held.
 #[derive(Clone, Debug, PartialEq)]
 pub struct CursorMacro {
-    /// The 1-based macro index (1..=18 account, 19..=36 character — [`super::macros`]'s space).
+    /// The 1-based macro index: 1..=18 account, 19..=36 character.
     pub index: u32,
     pub texture: Option<String>,
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// The one transition seam: CURSOR_UPDATE / ITEM_LOCK_CHANGED / DELETE_ITEM_CONFIRM
+// The transition events
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Queue `CURSOR_UPDATE` — fired on EVERY payload transition (pickup, place/clear, cancel,
-/// `ClearCursor`, `DeleteCursorItem`, a world-drop clear). One push per transition.
-///
-/// Also derives `ACTIONBAR_SHOWGRID`/`ACTIONBAR_HIDEGRID` (decision 0216 §7) off
-/// [`Model::cursor_grid_shown`]'s mirror against the CURRENT `model.cursor` (already the
-/// post-transition state at every call site — every caller mutates `model.cursor` before calling
-/// this): a None→Some edge (any payload arm, any surface — bags/doll/actions alike) shows the
-/// bar's drop grid, Some→None hides it, Some→Some (the action hop) touches neither, so one
-/// gesture never churns HIDE+SHOW. This is the one seam every pickup/place/clear already routes
-/// through, so no call site needs to know about grid events at all.
+/// Queue `CURSOR_UPDATE`, once per payload transition, plus a grid event when what the bars can
+/// take changes. Call it after `model.cursor` holds the new payload; an action hop keeps the grid
+/// up rather than hiding and reshowing it.
 pub(crate) fn queue_cursor_update(model: &mut Model) {
     model
         .pending_events
         .push(("CURSOR_UPDATE".to_string(), Vec::new()));
-    // The two grids are derived off DIFFERENT predicates, because the reference fires them from
-    // different places and the payload spaces do not overlap (decision 1010):
-    //
-    // - the ACTION bar's grid follows "is anything held that could land there" — every arm except
-    //   the pet one, which `PlaceAction` refuses outright;
-    // - the PET bar's grid follows the pet payload alone. The reference fires `PET_BAR_SHOWGRID`
-    //   from inside the pet-action pickup builder itself (`0x494f28`), not from a shared cursor
-    //   transition — so a spell on the cursor lights the action bar's empty slots and leaves the
-    //   pet bar alone, which is also the only honest answer: you cannot drop it there.
+    // The action bar's grid shows for any payload but a pet action, which `PlaceAction` refuses,
+    // or a vendor row, whose grab `0x4950f0` fires `ACTIONBAR_SHOWGRID` for mode 7 only
+    // (`0x495106`, `0x49513a`). The reference fires it (`0x4e58c0`) only from the item, spell and
+    // macro setters and that mode-7 grab, so coins and a stabled pet show it here and not there.
+    // The pet bar's follows the pet action alone (`0x494f28`).
     let pet_held = matches!(model.cursor, Some(CursorPayload::PetAction(_)));
-    let bar_held = model.cursor.is_some() && !pet_held;
+    let bar_held = model.cursor.is_some()
+        && !pet_held
+        && !matches!(model.cursor, Some(CursorPayload::Merchant(_)));
     if bar_held != model.cursor_grid_shown {
         model.cursor_grid_shown = bar_held;
         let event = if bar_held {
@@ -298,9 +196,7 @@ pub(crate) fn queue_cursor_update(model: &mut Model) {
     }
 }
 
-/// Queue `ITEM_LOCK_CHANGED(bag, slot)` — a pickup locking a source slot, or a place/cancel/
-/// clear/destroy unlocking it (decision 0216 §4: the engine-derived held-here lock,
-/// `container.rs`'s `GetContainerItemInfo` `held_here` check).
+/// Queue `ITEM_LOCK_CHANGED(bag, slot)` for a source slot that a pickup locks or a put-down frees.
 pub(crate) fn queue_lock_changed(model: &mut Model, bag: i64, slot: u32) {
     model.pending_events.push((
         "ITEM_LOCK_CHANGED".to_string(),
@@ -308,10 +204,8 @@ pub(crate) fn queue_lock_changed(model: &mut Model, bag: i64, slot: u32) {
     ));
 }
 
-/// Queue `DELETE_ITEM_CONFIRM(name, quality)` for an item payload dropped on the world (the popup
-/// flow transcribed from `StaticPopup.lua`, decision 0216 §3). `name` is parsed out of the link's
-/// `[...]` segment (empty string with no link); the payload is left untouched here — the popup's
-/// `OnAccept`/`OnCancel` (`DeleteCursorItem`/`ClearCursor`) own clearing it.
+/// Queue `DELETE_ITEM_CONFIRM(name, quality)` for an item dropped on the world. The payload stays
+/// held: the popup's `DeleteCursorItem` or `ClearCursor` clears it.
 fn queue_delete_item_confirm(model: &mut Model, item: &CursorItem) {
     let name = item_link_name(item.link.as_deref());
     let quality = item.quality.unwrap_or(0);
@@ -321,8 +215,7 @@ fn queue_delete_item_confirm(model: &mut Model, item: &CursorItem) {
     ));
 }
 
-/// Parse an item link's display name out of its `|h[Name]|h` segment; empty with no link or an
-/// unrecognized shape.
+/// An item link's name, from its `|h[Name]|h` segment; empty for no link or another shape.
 pub(super) fn item_link_name(link: Option<&str>) -> String {
     link.and_then(|l| l.split_once('['))
         .and_then(|(_, rest)| rest.split_once(']'))
@@ -330,15 +223,11 @@ pub(super) fn item_link_name(link: Option<&str>) -> String {
         .unwrap_or_default()
 }
 
-/// `ClearCursor()` — drops whatever the cursor holds, any arm (the right-click/ESC cancel). An
-/// item payload also un-locks its source slot; an already-empty cursor is not a transition (no
-/// event).
+/// `ClearCursor()`: drops any payload and frees an item's source slot; an empty cursor fires
+/// nothing.
 pub(crate) fn clear_cursor(model: &mut Model) {
-    // **An armed gift wrap dies with any cancel** (decision 1934), and this is the FIRST thing
-    // the reference's `ClearCursor 0x495190` does — `0x5edf10` is its opening act and it is
-    // **ungated by either parameter**, including `ClearCursor(0)`, the flavour that deliberately
-    // keeps an ordinary held item's lock. So all 70 of its call sites cancel a wrap. The paper
-    // unlocks and the cursor mode goes back to the base.
+    // Any clear first cancels an armed gift wrap, whatever its parameters (`0x495190` opens with
+    // `0x5edf10`): the wrapping paper unlocks and the cursor mode returns to the base.
     if let Some(wrap) = model.pending_wrap.take() {
         queue_lock_changed(model, wrap.bag, wrap.slot);
         model.ui_cursor = None;
@@ -355,11 +244,9 @@ pub(crate) fn clear_cursor(model: &mut Model) {
             | CursorPayload::Macro(_)
             | CursorPayload::PetAction(_)
             | CursorPayload::StablePet(_)
-            // Mode 2 — coins go back where they never left (the purse was not debited).
+            // Coins: the purse was never debited, so nothing goes back.
             | CursorPayload::Money(_)
-            // Mode 5 clears like every other non-item payload, and clearing it sends NO packet —
-            // a vendor cursor abandoned on the world, on ESC, or by the window closing costs
-            // nothing. `ClearCursor`'s own mode-5 arm is `0x49525f`.
+            // A vendor row clears with no packet (`0x49525f`).
             | CursorPayload::Merchant(_),
         ) => {
             queue_cursor_update(model);
@@ -368,24 +255,10 @@ pub(crate) fn clear_cursor(model: &mut Model) {
     }
 }
 
-/// **The SELL fork's cursor clear** — `0x494b60 SetCursorItem(0, …)`, which is *not* `ClearCursor`
-/// and differs from [`clear_cursor`] in exactly one way that a player can see.
-///
-/// Both drop the payload and fire `CURSOR_UPDATE`. `ClearCursor` also un-locks the source slot;
-/// this does **not**: `0x494b60`'s mode-1 arm is entered with `param1 = 0`, which skips `0x495420`,
-/// so the sold item's slot stays **greyed** until the server's own inventory update removes it
-/// (wow-re `object-layer/scratch/vendor-sell-on-right-click.md` §3, the §5 trio dispatched from
-/// benilla 1905). Leaving the lock set is the point: the item is gone from the cursor but not yet
-/// gone from the bag, and the grey is what says so.
-///
-/// Shared by the two verbs that sell off the cursor — `PickupMerchantItem`'s sell fork
-/// (`0x4fb760`) and the interact ladder's vendor arm (`0x5df5d0`) — because they are the same
-/// clear in the binary, and two copies of it is how one of them quietly grows a different
-/// behaviour. Returns the item so the caller can address the packet by its slot.
-///
-/// A non-item payload is left exactly where it was: the fork answers for **mode 1 only**
-/// (`GetCursorItem 0x494c60`), so a spell, a macro or a vendor row on the cursor is not a sale
-/// and must not be dropped by asking.
+/// The sell fork's clear, `SetCursorItem(0, …)` (`0x494b60`), shared by `PickupMerchantItem`
+/// (`0x4fb760`) and the interact ladder's vendor arm (`0x5df5d0`): unlike [`clear_cursor`] it
+/// leaves the source slot locked, grey until the server removes the item (the mode-1 arm skips
+/// `0x495420`). Any other payload is no sale and stays held (`GetCursorItem`, `0x494c60`).
 pub(crate) fn take_cursor_item_for_sale(model: &mut Model) -> Option<CursorItem> {
     let item = match model.cursor.take() {
         Some(CursorPayload::Item(item)) => item,
@@ -398,48 +271,29 @@ pub(crate) fn take_cursor_item_for_sale(model: &mut Model) -> Option<CursorItem>
     Some(item)
 }
 
-/// What the app's world pick resolves under the cursor this frame — the reference's click-time
-/// pick state `[this+0x350]` (0 = nothing / 1 = terrain / 2 = object; `0x481f60`, decisions
-/// 0571 + 0574). Fed per frame by the app ([`super::UiScript::set_world_pick`]; stays
-/// [`WorldPick::Nothing`] in tests/captures). Routes the left world-drop
-/// ([`world_drop_click`]): over an `Object` no payload drops at all (the object leg `0x492ce0`
-/// clears only the displayId-PREVIEW gate `[0xb4b41c]` — an arm benilla doesn't carry — and
-/// dispatches SELECT/INTERACT with the payload still held); over `Terrain` an ITEM drops (the
-/// `DELETE_ITEM_CONFIRM` popup via `0x5e0320`) and a spell/action payload clears silently
-/// (decision 0843's deliberate divergence — the reference keeps it there); over `Nothing` the
-/// item pops and any other payload silently clears (`0x492d30`).
+/// What is under the cursor in the world this frame: the reference's click-time pick state
+/// `[this+0x350]` (`0x481f60`). The app feeds it; tests and captures leave it `Nothing`.
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 pub enum WorldPick {
-    /// No world hit at all (sky / beyond the world) — the reference's state 0.
+    /// State 0: no world hit (the sky).
     #[default]
     Nothing,
-    /// The cursor ray hits the world (terrain/WMO/doodad) but no unit or GameObject — state 1.
+    /// State 1: terrain, a WMO or a doodad, but no unit or GameObject.
     Terrain,
-    /// A unit or GameObject is the pick — state 2.
+    /// State 2: a unit or GameObject.
     Object,
 }
 
-/// A world drop: a completed left CLICK on the game world while a payload is held — press and
-/// release both on the world (the world frame, or no frame at all where none is loaded — the
-/// caller's `over_world`, decision 2089), no drag (the byte-verified trigger, decision 0218: the
-/// client's `0x495300` runs on the WorldFrame click release only; a drag released over the world
-/// routes as a drag and keeps carrying) — routed by [`Model::world_pick`] (decisions 0571 + 0574,
-/// byte-verified wow-re cursor-dragdrop-payload.md §11):
+/// A left click on the world with a payload held, press and release both over the world and no
+/// drag (`0x495300`); returns whether it was consumed. Over an `Object` (`0x492ce0`) nothing
+/// drops and the click selects. Over `Terrain` (`0x492c90`) or `Nothing` (`0x492d30`) an item
+/// raises `DELETE_ITEM_CONFIRM(name, quality)` (`0x5e0320`) and stays held for the popup to clear;
+/// a spell, action, macro or pet action clears. Coins, a vendor row and a stabled pet stay held
+/// here, where the reference puts a vendor row down on every leg and clears any non-item payload
+/// over `Nothing` (`0x492e04`).
 ///
-/// - `Object`: NOTHING drops — the object leg (`0x492ce0`) keeps every real payload and
-///   dispatches SELECT instead.
-/// - `Terrain`: an item payload fires `DELETE_ITEM_CONFIRM(name, quality)` and STAYS held (the
-///   reference popup's `OnAccept` calls `DeleteCursorItem`, `OnCancel` `ClearCursor`, and its
-///   `OnUpdate` auto-hides when the cursor empties — the engine must not pre-clear); a
-///   spell/action payload clears silently — a DELIBERATE divergence (decision 0843, the
-///   director's call): the reference's terrain leg keeps a non-item payload on the left click
-///   (`0x492c90`/`0x5e0320` clear non-items only on the right button), which leaves a spell
-///   stuck to the cursor with no left-handed way off it.
-/// - `Nothing`: the item pops the same popup; any other payload clears silently (`0x492d30`'s
-///   non-item arm — here the reference agrees).
-///
-/// Returns whether the click was consumed as a drop (an empty cursor or an `Object` pick
-/// consume nothing).
+/// Deviation: on `Terrain` the reference keeps a spell, action, macro or pet action on the left
+/// button; we clear them, because otherwise a spell has no left-click way off the cursor.
 pub(crate) fn world_drop_click(model: &mut Model) -> bool {
     match (&model.cursor, model.world_pick) {
         (Some(CursorPayload::Item(item)), WorldPick::Terrain | WorldPick::Nothing) => {
@@ -463,12 +317,9 @@ pub(crate) fn world_drop_click(model: &mut Model) -> bool {
     }
 }
 
-/// `SplitContainerItem(bag, slot, count)` — a stack-split pickup (`StackSplitFrame.lua`'s
-/// `SplitStack`): only from an EMPTY cursor, onto a resolved and unlocked slot, `count >= 1`.
-/// `count` at or past the whole stack degrades to a plain whole-stack pickup (`count: None` — the
-/// client never "splits" a full stack; vmangos rejects `count == stack` as cheat). Returns
-/// whether a payload was picked up (the repaint gate, matching `pickup_container_item`'s
-/// contract).
+/// `SplitContainerItem(bag, slot, count)`: picks up `count` of an unlocked stack onto an empty
+/// cursor. A count of the whole stack or more is a plain pickup, since vmangos refuses to split a
+/// whole stack or more (`Player.cpp:11139`, `:11147`). Returns whether anything was picked up.
 pub(crate) fn split_container_item(model: &mut Model, bag: i64, slot: u32, count: i64) -> bool {
     if model.cursor.is_some() || count < 1 {
         return false;
@@ -498,9 +349,8 @@ pub(crate) fn split_container_item(model: &mut Model, bag: i64, slot: u32, count
     true
 }
 
-/// `DeleteCursorItem()` — the delete popup's `OnAccept` (decision 0216 §3): an Item payload
-/// queues its `(bag, slot, count)` destroy (`count == 0` = the whole stack) and clears; any other
-/// payload (or an empty cursor) is a no-op — the client's contract for a stale/mismatched confirm.
+/// `DeleteCursorItem()`, the delete popup's accept: a held item queues its `(bag, slot, count)`
+/// destroy, count 0 for the whole stack, and clears; anything else is a no-op.
 pub(crate) fn delete_cursor_item(model: &mut Model) {
     let Some(CursorPayload::Item(item)) = &model.cursor else {
         return;
@@ -519,9 +369,7 @@ pub(crate) fn delete_cursor_item(model: &mut Model) {
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 impl super::UiScript {
-    /// The item currently held on the cursor, or `None` — the Item-arm projection of
-    /// [`UiScript::cursor_payload`], kept for the app's existing extract/sound watchers
-    /// (`ui_script/extract.rs`, `sound/ui.rs`), which only ever cared about items.
+    /// The held item, if the payload is one.
     pub fn cursor_item(&self) -> Option<CursorItem> {
         match self.model_ref().cursor.clone() {
             Some(CursorPayload::Item(item)) => Some(item),
@@ -529,36 +377,28 @@ impl super::UiScript {
         }
     }
 
-    /// The full cursor payload, any arm — what the app's hardware-cursor drive
-    /// (`benilla::cursor`) and capture stand-in draw, and what the world-click consumers gate on.
+    /// The cursor payload, any arm.
     pub fn cursor_payload(&self) -> Option<CursorPayload> {
         self.model_ref().cursor.clone()
     }
 
-    /// Feed: what the app's world pick resolves under the cursor this frame
-    /// ([`Model::world_pick`], decisions 0571 + 0574) — routes [`world_drop_click`]'s legs
-    /// (object keeps everything, terrain drops items only, nothing drops any arm).
+    /// Feed the world pick under the cursor this frame ([`WorldPick`]).
     pub fn set_world_pick(&mut self, pick: WorldPick) {
         self.model_mut().world_pick = pick;
     }
 
-    /// The sell fork's take-and-clear, for the app-side interact ladder — see
-    /// [`take_cursor_item_for_sale`]. `None` for an empty cursor or any non-item payload, and in
-    /// that case the payload is left untouched.
+    /// [`take_cursor_item_for_sale`], for the app's interact ladder.
     pub fn take_cursor_item_for_sale(&mut self) -> Option<CursorItem> {
         take_cursor_item_for_sale(&mut self.model_mut())
     }
 
-    /// `ClearCursor()`'s Rust seam — drops whatever the cursor holds, any arm, silently (fires
-    /// `CURSOR_UPDATE` + the item source un-lock, exactly the Lua `ClearCursor`). The app's
-    /// world-click router calls it for a clean RIGHT-click over empty world (`0x492c90`/
-    /// `0x492d30`'s action-4 leg: `ClearCursor 0x495190(1,1)` unconditionally — decision 0571).
+    /// `ClearCursor()` from Rust, which the app calls on a right-click over empty world: both
+    /// reference legs there (`0x492c90`, `0x492d30`) call `ClearCursor(1, 1)` (`0x495190`).
     pub fn clear_cursor_payload(&mut self) {
         clear_cursor(&mut self.model_mut());
     }
 
-    /// Test-only: set the cursor payload directly, bypassing every Lua binding — drives the
-    /// Spell/Action arms in tests before a spellbook/action-bar slice can produce them.
+    /// Test-only: set the payload directly, bypassing the Lua bindings.
     #[cfg(test)]
     pub(crate) fn set_cursor_for_test(&mut self, payload: CursorPayload) {
         self.model_mut().cursor = Some(payload);
@@ -566,65 +406,53 @@ impl super::UiScript {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Lua globals: GetCursorInfo / CursorHasItem / CursorHasSpell / ClearCursor / SplitContainerItem /
-// DeleteCursorItem — all top-level (the real client's `GetCursorInfo` &c. are not namespaced).
+// The targeting cursor's item pick and the enchant confirms
+// ─────────────────────────────────────────────────────────────────────────────────────────────
 impl super::UiScript {
-    /// Arm (or disarm) **the targeting cursor's item half** — the engine mirror of
-    /// `TargetingWantsItem 0x6e6330`. While armed, a bag click ([`super::container`]) or a
-    /// paper-doll click ([`doll::pickup_inventory_item`]) queues its `(bag, slot)` into the pick
-    /// list instead of running the cursor gesture, exactly as the reference's two pickup
-    /// functions reroute (`0x4f9b30` @ `4f9c54`, `0x4c7300` @ `4c76df`). The app owns the word:
-    /// it arms on a resolved item-targeted cast and clears on the bind, a cancel, or ESC
-    /// (decision 0923 — before it, this was the CraftFrame's private enchant pick).
+    /// Arm or disarm the targeting cursor's item half (`TargetingWantsItem`, `0x6e6330`): while
+    /// armed, a bag or paper-doll click queues its `(bag, slot)` as a pick instead of picking up,
+    /// as the reference's two pickups do (`0x4f9b30` at `0x4f9c54`, `0x4c7300` at `0x4c76df`).
     pub fn set_item_pick_armed(&mut self, armed: bool) {
         self.model_mut().item_pick_armed = armed;
     }
 
-    /// Push what `SpellCanTargetUnit` answers — whether the standing targeting word could bind a
-    /// unit at all (see [`crate::script::Model::spell_can_target_unit`]).
+    /// Push what `SpellCanTargetUnit` answers: whether the armed targeting cast can take a unit.
     pub fn set_spell_can_target_unit(&mut self, can: bool) {
         self.model_mut().spell_can_target_unit = can;
     }
 
-    /// Drain the `(bag, slot)` clicks the armed item half consumed since the last call. A doll
-    /// click reports as [`EQUIPMENT_BAG`] + its 1-based inventory slot — the ONE bag space, so
-    /// the app resolves both seams with one lookup.
+    /// Drain the `(bag, slot)` picks since the last call; a paper-doll pick reports as
+    /// [`EQUIPMENT_BAG`] and its 1-based inventory slot.
     pub fn take_item_picks(&mut self) -> Vec<(i64, u32)> {
         std::mem::take(&mut self.model_mut().item_picks)
     }
 
-    /// Drain the enchant-confirm popups' answers since the last call (decision 0928). Both are
-    /// answers to the *same* pick the app parked, which is why they share one queue.
+    /// Drain the enchant-confirm answers since the last call; both answer the pick the app parked.
     pub fn take_enchant_confirms(&mut self) -> Vec<EnchantConfirm> {
         std::mem::take(&mut self.model_mut().enchant_confirms)
     }
 }
 
-/// A Yes on one of the enchant-apply confirms — the two Lua globals `StaticPopup.lua` calls from
-/// `BIND_ENCHANT`'s and `REPLACE_ENCHANT`'s `OnAccept` (decision 0928). Plain intents; the app
-/// holds the item guid they answer for (the reference's `0xb4e3c0/0xb4e3c4`).
+/// A Yes on an enchant-apply confirm (`StaticPopup.lua:1245`, `:1257`); the app holds the item
+/// guid it answers for (the reference's `0xb4e3c0`/`0xb4e3c4`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum EnchantConfirm {
-    /// `BindEnchant()` — `0x48d2e0`, which re-invokes the enchant-apply gate `0x495d60` over the
-    /// parked guid with its "already confirmed" parameter set. So this is NOT a send: the gate
-    /// runs again and may raise the *replace* popup next.
+    /// `BindEnchant()` (`0x48d2e0`): reruns the enchant-apply gate `0x495d60` as already
+    /// confirmed, so it may raise the replace popup next rather than cast.
     Bind,
-    /// `ReplaceEnchant()` — `0x48d300`, which re-resolves the parked guid and calls the ordinary
-    /// target binder `0x6e5b40` **directly**, skipping the gate. There is no
-    /// `CMSG_REPLACE_ENCHANT` in 5875: the popup is pure client-side gating over the same cast.
+    /// `ReplaceEnchant()` (`0x48d300`): binds the parked guid through `0x6e5b40`, skipping the
+    /// gate. There is no replace packet: the popup only gates the same cast.
     Replace,
 }
 
-// The paper-doll globals (`PickupInventoryItem` &c.) install from [`doll`]; the action-bar
-// globals (`PickupAction`/`PlaceAction`) install from [`bar`].
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// Lua globals
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // BindEnchant() / ReplaceEnchant() — the two enchant-confirm popups' OnAccept (StaticPopup.lua
-    // `BIND_ENCHANT` l.1240 and `REPLACE_ENCHANT` l.1252). Both queue an intent the app answers
-    // over its parked item guid; neither sends anything from here.
+    // `BindEnchant()`, `ReplaceEnchant()`: queue an intent for the app; nothing is sent from here.
     for (name, answer) in [
         ("BindEnchant", EnchantConfirm::Bind),
         ("ReplaceEnchant", EnchantConfirm::Replace),
@@ -639,10 +467,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GetCursorInfo() → per arm: Item ("item", itemID, itemLink); Spell ("spell", book_slot,
-    // book_type, spell_id) — the Era shape; Action ("action", src_slot). Empty ⇒ all nils. A
-    // fixed 4-return shape (padded with nil past each arm's own fields) so one function signature
-    // covers every arm; callers destructuring fewer names simply ignore the tail.
+    // `GetCursorInfo()` is not a 1.12 verb. It answers ("item", id, link), ("spell", book slot,
+    // book, spell id), ("action", slot), ("macro", index) or ("petaction", slot), padded with nil
+    // to four values; any other payload, or none, is four nils.
     g.set(
         "GetCursorInfo",
         lua.create_function(|lua, ()| {
@@ -672,40 +499,24 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     Value::Nil,
                     Value::Nil,
                 )),
-                // The Era `GetCursorInfo` shape for a macro: the kind word + the macro index.
                 Some(CursorPayload::Macro(m)) => Ok((
                     Value::String(lua.create_string("macro")?),
                     Value::Integer(i64::from(m.index)),
                     Value::Nil,
                     Value::Nil,
                 )),
-                // The pet arm follows the Action arm's shape — kind word + the slot it came from.
-                // Nothing in the shipped 1.12 UI reads it (the pet bar's own drag never asks what
-                // it is carrying); it is here so the ONE payload space stays fully describable.
                 Some(CursorPayload::PetAction(p)) => Ok((
                     Value::String(lua.create_string("petaction")?),
                     Value::Integer(i64::from(p.src_slot)),
                     Value::Nil,
                     Value::Nil,
                 )),
-                // Mode 10 — the stabled-pet grab (decision 1677). Reported as nothing: the
-                // reference's `GetCursorInfo` arms are not carved for it, the stable window never
-                // asks, and inventing a type string would put a guess where an addon could read it.
                 Some(CursorPayload::StablePet(_)) => {
                     Ok((Value::Nil, Value::Nil, Value::Nil, Value::Nil))
                 }
-                // Mode 2 — coins (1962). Reported as nothing for the same reason: the money arm
-                // of `GetCursorInfo` is not carved, and `GetCursorMoney` is the reference's own
-                // way of asking. Joins the carve when it lands.
                 Some(CursorPayload::Money(_)) => {
                     Ok((Value::Nil, Value::Nil, Value::Nil, Value::Nil))
                 }
-                // Mode 5 — the vendor grab. Reported as nothing, for the same reason and with a
-                // stronger warrant: **no registered binding in the 5875 image exposes mode 5 to
-                // Lua at all.** `CursorHasItem`, `CursorHasSpell`, `CursorHasMoney` and
-                // `CursorCanGoInSlot` are each nil for it, by census. A vendor cursor is invisible
-                // from Lua and that invisibility is load-bearing — it is what keeps all thirteen
-                // stock `CursorHasItem()` gates closed while one is held.
                 Some(CursorPayload::Merchant(_)) => {
                     Ok((Value::Nil, Value::Nil, Value::Nil, Value::Nil))
                 }
@@ -767,8 +578,7 @@ mod tests {
     use super::{CursorAction, CursorItem, CursorPayload, CursorSpell};
     use crate::script::UiScript;
 
-    /// A one-item, one-slot backpack (mirrors `container::tests::backpack` closely enough for
-    /// these payload-shape tests, which don't need its in-flight slot).
+    /// A backpack holding a five-stack in slot 1.
     fn one_item_backpack() -> crate::script::container::ContainerState {
         let mut slots = std::collections::HashMap::new();
         slots.insert(
@@ -800,24 +610,14 @@ mod tests {
         }
     }
 
-    /// **The sell clear is not `ClearCursor`** — decision 1914, and the difference is the one a
-    /// player sees.
-    ///
-    /// `0x494b60 SetCursorItem(0, …)` drops the payload and fires `CURSOR_UPDATE`, but its mode-1
-    /// arm skips `0x495420` with `param1 = 0`, so it never un-locks the source slot: the item is
-    /// off the cursor and the bag slot stays **greyed** until the server's inventory update takes
-    /// it away. `ClearCursor` un-locks. Firing `ITEM_LOCK_CHANGED` here would un-grey a slot whose
-    /// item is still sitting in it awaiting the server, which is the visible wrong.
-    ///
-    /// The second half is the blast radius: the fork answers for **mode 1 only**, so asking a
-    /// spell or a vendor row must not drop it.
+    /// `SetCursorItem(0, …)` (`0x494b60`) skips `ClearCursor`'s unlock (`0x495420`) and takes only
+    /// a held item.
     #[test]
     fn the_sell_clear_keeps_the_source_slot_locked() {
         let mut s = UiScript::new().unwrap();
         s.set_container(0, Some(one_item_backpack()));
 
-        // Pick the item up, then drain whatever the pickup queued so the assert below sees only
-        // what the SELL clear itself fires.
+        // Drain the pickup's events so only the sell clear's remain.
         s.eval::<()>("PickupContainerItem(0, 1)").unwrap();
         assert!(s.cursor_item().is_some(), "the pickup did not take");
         s.model_mut().pending_events.clear();
@@ -845,7 +645,6 @@ mod tests {
              `SetCursorItem(0, …)`'s) — got {fired:?}"
         );
 
-        // Mode 1 only: every other payload is left exactly where it was.
         let mut s = UiScript::new().unwrap();
         s.set_cursor_for_test(CursorPayload::Spell(CursorSpell {
             book_slot: 1,
@@ -868,14 +667,12 @@ mod tests {
     fn get_cursor_info_and_has_checks_per_arm() {
         let mut s = UiScript::new().unwrap();
 
-        // Empty: all nils, both Has* false.
         assert!(s
             .eval::<bool>("local k = GetCursorInfo() return k == nil")
             .unwrap());
         assert!(!s.eval::<bool>("return CursorHasItem()").unwrap());
         assert!(!s.eval::<bool>("return CursorHasSpell()").unwrap());
 
-        // Item arm.
         s.set_cursor_for_test(CursorPayload::Item(CursorItem {
             bar_placeable: true,
             bag: 0,
@@ -897,7 +694,6 @@ mod tests {
         assert!(s.eval::<bool>("return CursorHasItem()").unwrap());
         assert!(!s.eval::<bool>("return CursorHasSpell()").unwrap());
 
-        // Spell arm — the Era 4-tuple shape.
         s.set_cursor_for_test(CursorPayload::Spell(CursorSpell {
             passive: false,
             book_slot: 3,
@@ -917,7 +713,6 @@ mod tests {
         assert!(!s.eval::<bool>("return CursorHasItem()").unwrap());
         assert!(s.eval::<bool>("return CursorHasSpell()").unwrap());
 
-        // Action arm.
         s.set_cursor_for_test(CursorPayload::Action(CursorAction {
             src_slot: 12,
             kind: 0,
@@ -947,10 +742,7 @@ mod tests {
         assert!(s.cursor_payload().is_none());
     }
 
-    /// The world-drop pick routing (decisions 0571 + 0574 — wow-re §11, amended by 0843): a
-    /// spell/action payload clears silently on BOTH empty-world legs — terrain included, the
-    /// 0843 divergence (the reference keeps it on terrain; the director wants the left click to
-    /// dismiss) — while an item keeps its byte-faithful popup flow.
+    /// Clearing a spell on terrain is the deviation documented on `world_drop_click`.
     #[test]
     fn world_drop_terrain_and_nothing_both_clear_a_spell_payload() {
         use super::{world_drop_click, WorldPick};
@@ -974,7 +766,6 @@ mod tests {
             );
         }
 
-        // An item drops (the popup path) on BOTH empty-world legs, never over an object.
         let item = CursorPayload::Item(CursorItem {
             bar_placeable: true,
             bag: 0,
diff --git a/crates/benilla-ui/src/script/cursor/bag_verbs.rs b/crates/benilla-ui/src/script/cursor/bag_verbs.rs
index 509ddc80..ad17b031 100644
--- a/crates/benilla-ui/src/script/cursor/bag_verbs.rs
+++ b/crates/benilla-ui/src/script/cursor/bag_verbs.rs
@@ -1,29 +1,4 @@
-//! The three BAG-SLOT verbs — `PutItemInBag`, `PutItemInBackpack`, `PickupBagFromSlot`.
-//!
-//! CARVED, not inferred (wow-re `system/ui/ui.md`, "The three bag verbs — one worker, a three-way
-//! fork, and a return value that is not 'did it place'"; `scratch/bag-verbs-law.md`, §5 trio +
-//! orchestrator byte arbitration 2026-08-11). The three findings that shape everything below:
-//!
-//! 1 · **`PutItemInBackpack()` IS `PutItemInBag(0xFF)`.** `0x4c7ed0` is a ten-byte thunk —
-//!   `mov ecx,0xff` / `jmp 0x4c7c00` — so there is one worker here too, and only the destination
-//!   differs. The `0xFF` path is *not* "bag 0": the destination guid is the player's own, which
-//!   makes the empty-slot leg unreachable and `0x4c7d3e je 0x4c7e0c` skip the swap fork outright,
-//!   so a bag dropped on the backpack button is auto-stored INTO it, never swapped with it.
-//!
-//! 2 · **`PutItemInBag` forks three ways**, on the state of the target slot and the held object:
-//!   empty slot → the paper-doll handler equips the held bag ([`super::doll::pickup_inventory_item`],
-//!   which is `0x4c7300` — the same function the byte path calls); occupied + the held object is a
-//!   CONTAINER → a bag↔bag swap; occupied + an ordinary item → auto-store into that container's
-//!   contents, with the client picking no destination slot at all.
-//!
-//! 3 · **The return value answers "was this click consumed as a placement against an existing
-//!   container?", not "did something get placed".** It is the Lua **number `1`**, never the boolean
-//!   `true` — and it is `nil` on the empty-slot leg that really does equip the bag, and whenever
-//!   the cursor is empty. That last one is the whole reason a plain left-click opens a bag:
-//!   `BagSlotButton_OnClick`'s `if ( not hadItem ) then ToggleBag(...)`.
-//!
-//! `PickupBagFromSlot` has its own, much shorter worker (`0x4c7b00`) and is a *destructive*
-//! pickup: it drops whatever the cursor already held before it looks at the slot.
+//! The bag-slot verbs: `PutItemInBag`, `PutItemInBackpack` and `PickupBagFromSlot`.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -33,21 +8,9 @@ use crate::script::Model;
 use super::{clear_cursor, queue_cursor_update, queue_lock_changed, CursorItem, CursorPayload};
 use super::{doll::pickup_inventory_item, EQUIPMENT_BAG};
 
-/// The live-API inventory ids the two verbs' shared argument reader (`0x4c8520`) accepts, minus
-/// what each binding's own floor gate (`cmp ecx,0x13; jl` on the 0-based value — `0x4c8f1f`,
-/// `0x4c8fbf`) then cuts off. In the space a Lua caller writes:
-///
-/// | band | what it is |
-/// |---|---|
-/// | 20..=23 | the four EQUIPPED bag slots (`Bag0Slot`..`Bag3Slot`) |
-/// | 40..=63 | the bank's 24 generic slots |
-/// | 64..=69 | the six BANK BAG slots |
-/// | 82..=113 | the keyring |
-///
-/// The reader rejects the backpack's own item slots (24..=39) and buyback (70..=81); the floor
-/// cuts equipment (1..=19) and ammo. **So a macro may legally hand either verb a bank item slot
-/// or a keyring slot, and nothing downstream catches it** — the reference sends a packet the
-/// server refuses. See [`autostore_container`] for the one place benilla is tighter, and why.
+/// The ids `PutItemInBag` and `PickupBagFromSlot` take: what their argument reader (`0x4c8520`)
+/// accepts above each floor gate (`0x4c8f1f`, `0x4c8fbf`), so the equipped bags 20-23, the
+/// bank's slots 40-63, its bag slots 64-69 and the keyring 82-113.
 fn accepts(live: u32) -> bool {
     (20..=23).contains(&live)
         || (40..=63).contains(&live)
@@ -55,19 +18,9 @@ fn accepts(live: u32) -> bool {
         || (82..=113).contains(&live)
 }
 
-/// The live-API **container** id a bag slot's own inventory id names — the inverse of
-/// `ContainerIDToInventoryID` (`crate::script::container`'s own table): 20..=23 → 1..=4, 64..=69 →
-/// 5..=10. `None` for an inventory id that is not a bag slot.
-///
-/// **This is the one place benilla's gate is tighter than the engine's**, and it is deliberate.
-/// [`accepts`] admits the bank's generic slots and the keyring because the reference's argument
-/// reader does; the reference then auto-stores *into* them, sending
-/// `CMSG_AUTOSTORE_BAG_ITEM(…, dstbag = live − 1)` for a `dstbag` that names no container, which
-/// the server refuses (`EQUIP_ERR_ITEM_DOESNT_GO_TO_SLOT`). benilla has no container id to name
-/// there, so [`put_item_in_bag`]'s auto-store leg answers `nil` and sends nothing. No shipped
-/// window produces the call — the reference's own two callers are `BagSlotButton_OnClick` and
-/// `BankFrameItemButtonBag_OnClick`, both of which pass a bag slot — and a refusal the player
-/// never sees is not worth a packet.
+/// The live container id of a bag slot, the inverse of `ContainerIDToInventoryID`. Deviation:
+/// an auto-store into a bank item or keyring slot sends nothing, because no container id names
+/// it and no stock caller passes one; the reference sends it and the server refuses.
 fn autostore_container(live: u32) -> Option<i64> {
     match live {
         20..=23 => Some(i64::from(live) - 19),
@@ -76,34 +29,23 @@ fn autostore_container(live: u32) -> Option<i64> {
     }
 }
 
-/// `Bag0Slot` — the first of the four EQUIPPED bag slots, and the tell that an item is a
-/// container. See [`is_container`].
+/// `Bag0Slot`, the first equipped bag slot: only a container names it in `equip_slots`.
 const BAG0_SLOT: u8 = 20;
 
-/// The six BANK BAG slots' live-API ids (`BankButtonIDToInvSlotID(1..6, isBag)`).
+/// The six bank bag slots' ids (`BankButtonIDToInvSlotID(1..6, isBag)`).
 pub(super) const BANK_BAG_INV_SLOTS: std::ops::RangeInclusive<u32> = 64..=69;
 
-/// Whether the held item is a CONTAINER — the fork the reference reads straight off the object
-/// (`0x4c7dc4 shr eax,2; test al,1`, `OBJECT_FIELD_TYPE`'s `TYPEMASK_CONTAINER` bit).
-///
-/// benilla has no object-type field on a cursor payload, and asks the equivalent question of the
-/// data it does carry: `equip_slots` is the server's own `Player::FindEquipSlot`, and
-/// `INVTYPE_BAG` is the ONLY inventory type in that table that yields the bag slots
-/// (`ui_items::find_equip_slot`, arm 18). So "this item names Bag0Slot as a place it could be
-/// worn" and "this item is a container" are the same set.
+/// Whether the held item is a container, the reference's `TYPEMASK_CONTAINER` test (`0x4c7dc4`):
+/// only `INVTYPE_BAG` maps to the bag slots in `FindEquipSlot`, so no other item names Bag0Slot.
 fn is_container(item: &CursorItem) -> bool {
     item.equip_slots.contains(&BAG0_SLOT)
 }
 
-/// Whether the held item may be dropped on doll slot `id` — the fit rule, one band wider than
-/// `equip_slots` alone.
-///
-/// The four EQUIPPED bag slots are in `equip_slots` because the server's `FindEquipSlot` names
-/// them; the six BANK BAG slots never are, because `FindEquipSlot` does not know about the bank
-/// (it is `CanBankItem`'s business there). The client's own predicate `CursorCanGoInSlot`
-/// (`0x5ea720`) is 0216 §5's unresolved residual, so the rule here is stated from the observable:
-/// a bank bag slot takes a container and nothing else, and the server's `CanBankItem` referees
-/// either way through `SMSG_INVENTORY_CHANGE_FAILURE`.
+/// Whether the held item may go in doll slot `id`: its `equip_slots`, or a bank bag slot for a
+/// container, which `FindEquipSlot` never names. The reference's fit check behind
+/// `CursorCanGoInSlot` (`0x5ea720`) passes any item at a bank bag slot, as `IsValidForSlot`
+/// answers 1 for every 0-based slot from 23 (`0x5da215`); the server's `CanBankItem` referees
+/// either way.
 pub(super) fn fits_slot(item: &CursorItem, id: u32) -> bool {
     if BANK_BAG_INV_SLOTS.contains(&id) {
         return is_container(item);
@@ -111,17 +53,16 @@ pub(super) fn fits_slot(item: &CursorItem, id: u32) -> bool {
     u8::try_from(id).is_ok_and(|id| item.equip_slots.contains(&id))
 }
 
-/// `PutItemInBag(inventorySlot)` — module doc, finding 2. Returns the reference's own `1`/`nil`
-/// as a bool the binding maps ("was this click consumed as a placement against an existing
-/// container?", NOT "did something get placed").
+/// `PutItemInBag(inventorySlot)` (`0x4c7c00`): true (the reference's `1`) when the click was
+/// consumed against an occupied slot, else false (nil). An empty cursor's nil is what lets
+/// `BagSlotButton_OnClick` open the bag.
 pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
     if !accepts(live) {
         return false;
     }
-    // `0x4c7ce4 je 0x4c7eaf` — an empty cursor is the FIRST thing tested, and it answers `nil`
-    // with nothing sent. A Spell/Action/Macro/PetAction/StablePet payload is not the client's
-    // item cursor either, and takes the same exit: this is what leaves a plain click free to open
-    // the bag.
+    // An empty or non-item cursor answers nil and sends nothing. At an occupied slot the
+    // reference clears such a cursor (`0x4c7ce4`, `0x4c7eaf`), buying a held vendor row first
+    // (`0x4c7e66`).
     let Some(CursorPayload::Item(held)) = model.cursor.clone() else {
         return false;
     };
@@ -131,16 +72,13 @@ pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
         .is_some();
 
     if !occupied {
-        // Leg 1 — the EMPTY slot. The byte path calls `0x4c7300`, the paper-doll handler, which
-        // is `pickup_inventory_item`'s place arm here: the fit predicate, the queued move, the
-        // clear and both events, all of it already the doll's. `0x4c7cae xor eax,eax` is
-        // unconditional, so this answers `nil` whether or not the bag actually went in.
+        // An empty slot: the doll handler equips the bag (`0x4c7300`), and the answer is nil
+        // whether or not it went in (`0x4c7cae xor eax,eax`).
         pickup_inventory_item(model, live);
         return false;
     }
 
-    // A pure cancel: the held item IS this bag (put back where it came from). Sends nothing, and
-    // answers `1` — the click WAS consumed.
+    // The held bag is this slot's own: a cancel that sends nothing and answers 1.
     if held.bag == EQUIPMENT_BAG && held.slot == live {
         model.cursor = None;
         queue_cursor_update(model);
@@ -149,12 +87,8 @@ pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
     }
 
     if is_container(&held) || held.bag == EQUIPMENT_BAG {
-        // Leg 2 — bag↔bag SWAP (`0x5e0c40`, `CMSG_SWAP_ITEM`/`CMSG_SWAP_INV_ITEM`). "Came from a
-        // bag equipment slot" is the reference's second entry to this fork, hence the `||`. The
-        // existing move drain already picks the opcode off the two endpoints.
-        //
-        // A split carry cannot swap: half a stack is not a bag. The reference reaches its SPLIT
-        // sender only from the auto-store leg, so this falls through to a refusal, kept.
+        // A swap (`0x5e0c40`); an item from a bag equipment slot enters this fork too, hence the
+        // `||`. A split stack cannot swap and stays held: the reference splits only when storing.
         if held.count.is_none() {
             model.cursor = None;
             model.container_moves.push(ContainerMove {
@@ -172,9 +106,8 @@ pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
         return true;
     }
 
-    // Leg 3 — AUTO-STORE into the container's contents (`CMSG_AUTOSTORE_BAG_ITEM 0x10B`, or
-    // `CMSG_SPLIT_ITEM 0x10E` for a split carry). **The client never picks a destination slot**:
-    // AUTOSTORE carries none and SPLIT carries the literal `0xFF`.
+    // Store into the bag: `CMSG_AUTOSTORE_BAG_ITEM` (`0x10B`), or `CMSG_SPLIT_ITEM` (`0x10E`) for
+    // a split. The client picks no slot: the store carries none, the split carries `0xFF`.
     let Some(dst_bag) = autostore_container(live) else {
         return false;
     };
@@ -190,9 +123,9 @@ pub(super) fn put_item_in_bag(model: &mut Model, live: u32) -> bool {
     true
 }
 
-/// `PutItemInBackpack()` — module doc, finding 1: the same worker with the destination fixed to
-/// the player's own guid, which makes the empty-slot and swap legs unreachable. Everything that
-/// lands here auto-stores into the backpack.
+/// `PutItemInBackpack()`, a thunk to `PutItemInBag(0xFF)` (`0x4c7ed0`) whose target is the
+/// player's own guid: the empty-slot leg is unreachable and `0x4c7d3e` skips the swap, so even a
+/// bag is stored into the backpack.
 pub(super) fn put_item_in_backpack(model: &mut Model) -> bool {
     let Some(CursorPayload::Item(held)) = model.cursor.clone() else {
         return false;
@@ -209,23 +142,10 @@ pub(super) fn put_item_in_backpack(model: &mut Model) -> bool {
     true
 }
 
-/// `PickupBagFromSlot(inventorySlot)` — a **destructive** pickup, not a restricted
-/// `PickupInventoryItem` (`0x4c7b00`). Returns nothing.
-///
-/// Three things it does that the doll pickup does not:
-///
-/// · **`ClearCursor(1, 1)` unconditionally, before it looks at anything** (`0x4c7b79`) — whatever
-///   was held is dropped and unlocked, even if the slot then turns out to be empty.
-/// · Resolves the occupant with **`TYPEMASK_CONTAINER`** (`0x4c7bb3 mov ecx,4`, where
-///   `PickupInventoryItem` uses `ecx = 2`). This is what makes it silently no-op at the bank item
-///   slots and the keyring that its floor-only gate still admits: those hold ordinary items.
-/// · Has **no place/swap path at all**, and none of `0x4c7300`'s targeting reroute, repair-cursor
-///   leg or slot-`−1` ammo leg.
-///
-/// There is **no client-side "a bag must be empty to be moved" rule** — both workers were read end
-/// to end and neither inspects container occupancy. That refusal is the server's
-/// `Player::CanUnequipItem` (`EQUIP_ERR_CAN_ONLY_DO_WITH_EMPTY_BAGS`), arriving as
-/// `SMSG_INVENTORY_CHANGE_FAILURE`.
+/// `PickupBagFromSlot(inventorySlot)` (`0x4c7b00`): clears the cursor before it looks at the slot,
+/// where the reference clears only a held item (`0x4c7b70`, `0x4c7b79`); takes only a container
+/// (`0x4c7bb3`), and never places or swaps. The client has no empty-bag rule: the server refuses
+/// with `EQUIP_ERR_CAN_ONLY_DO_WITH_EMPTY_BAGS`.
 pub(super) fn pickup_bag_from_slot(model: &mut Model, live: u32) {
     if !accepts(live) {
         return;
@@ -246,8 +166,6 @@ pub(super) fn pickup_bag_from_slot(model: &mut Model, live: u32) {
             bar_placeable: s.bar_placeable,
             equip_slots: s.equip_slots.clone(),
         })
-        // TYPEMASK_CONTAINER, applied after the view is built so the predicate reads off the same
-        // `equip_slots` every other bag decision here does ([`is_container`]).
         .filter(is_container);
     if let Some(item) = picked {
         model.cursor = Some(CursorPayload::Item(item));
@@ -256,14 +174,11 @@ pub(super) fn pickup_bag_from_slot(model: &mut Model, live: u32) {
     }
 }
 
-/// Register the three verbs — top-level globals, like every other cursor binding.
+/// Register the three verbs as globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // The number `1` or nil — `0x6f3810` writes Lua tag 3 (number) with the IEEE-754 double
-    // `0x3FF0000000000000`; tag 1 (boolean) appears in neither body. FrameXML only ever tests it
-    // for truthiness, but an addon that compares against `true` must see what the reference gives
-    // it.
+    // The number 1 or nil, never a boolean: `0x6f3810` pushes Lua tag 3, a number.
     fn consumed(yes: bool) -> mlua::Result<MultiValue> {
         Ok(MultiValue::from_vec(vec![if yes {
             Value::Number(1.0)
@@ -312,8 +227,7 @@ mod tests {
         InventorySlots, UiScript,
     };
 
-    /// An item that IS a bag — `equip_slots` is `find_equip_slot(INVTYPE_BAG)`, the only inventory
-    /// type in that table that names Bag0Slot, which is how [`super::is_container`] reads it.
+    /// An item that is a bag: `equip_slots` is `find_equip_slot(INVTYPE_BAG)`.
     fn bag_slot_view(item_id: u32) -> InvSlotView {
         InvSlotView {
             item_id,
@@ -361,9 +275,6 @@ mod tests {
         bags
     }
 
-    /// Finding 3, the one every caller depends on: an empty cursor answers **nil** and sends
-    /// nothing, which is what leaves `BagSlotButton_OnClick`'s `if ( not hadItem ) then
-    /// ToggleBag(...)` free to open the bag.
     #[test]
     fn an_empty_cursor_answers_nil_and_sends_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -375,9 +286,7 @@ mod tests {
         assert!(s.take_bag_autostores().is_empty());
     }
 
-    /// Leg 1 — the EMPTY slot equips the held bag, and answers **nil** while doing it
-    /// (`0x4c7cae xor eax,eax` is unconditional). That pairing is the reference's, not a slip:
-    /// the click both puts the bag in and opens the window it just created.
+    /// The nil after the equip is the reference's (`0x4c7cae`), so the same click opens the bag.
     #[test]
     fn an_empty_bag_slot_equips_the_held_bag_and_still_answers_nil() {
         let mut s = UiScript::new().unwrap();
@@ -400,9 +309,6 @@ mod tests {
         assert!(s.take_bag_autostores().is_empty(), "an equip, not a store");
     }
 
-    /// Leg 1's fit rule: a bank bag slot takes a CONTAINER and nothing else. An ordinary item
-    /// dropped on an empty bank bag slot is refused and kept — the server's `CanBankItem` would
-    /// refuse it anyway, and there is nothing to auto-store into.
     #[test]
     fn an_empty_bag_slot_refuses_an_ordinary_item() {
         let mut s = UiScript::new().unwrap();
@@ -415,7 +321,6 @@ mod tests {
         assert!(s.take_bag_autostores().is_empty());
     }
 
-    /// Leg 2 — an OCCUPIED slot plus a held container is a bag↔bag swap, and answers `1`.
     #[test]
     fn an_occupied_bag_slot_swaps_with_a_held_bag_and_answers_one() {
         let mut s = UiScript::new().unwrap();
@@ -437,8 +342,6 @@ mod tests {
         );
     }
 
-    /// Leg 3 — an OCCUPIED slot plus an ORDINARY item auto-stores INTO that bag. The intent
-    /// carries no destination slot, because the wire has none.
     #[test]
     fn an_occupied_bag_slot_auto_stores_an_ordinary_item() {
         let mut s = UiScript::new().unwrap();
@@ -454,15 +357,13 @@ mod tests {
             vec![BagAutoStore {
                 src_bag: 0,
                 src_slot: 2,
-                // Live container id 5 — bank bag slot 1 (`ContainerIDToInventoryID(5) == 64`).
+                // Container 5 is bank bag slot 1 (`ContainerIDToInventoryID(5) == 64`).
                 dst_bag: 5,
                 count: None,
             }]
         );
     }
 
-    /// Finding 1 — `PutItemInBackpack()` skips both the empty-slot and the swap legs outright: a
-    /// held BAG dropped on the backpack button is auto-stored, never swapped with it.
     #[test]
     fn the_backpack_button_always_auto_stores_even_a_bag() {
         let mut s = UiScript::new().unwrap();
@@ -482,9 +383,6 @@ mod tests {
         );
     }
 
-    /// Finding 3's literal shape: the reference pushes the Lua **number** `1` (`0x6f3810` writes
-    /// tag 3 with the IEEE-754 double `0x3FF0…`), never the boolean `true`. FrameXML only tests
-    /// truthiness; an addon comparing against `true` must see what the reference gives it.
     #[test]
     fn the_answer_is_the_number_one_not_the_boolean_true() {
         let mut s = UiScript::new().unwrap();
@@ -496,8 +394,6 @@ mod tests {
             .unwrap());
     }
 
-    /// The floor gate (`cmp ecx,0x13; jl`): equipment slots and ammo are below it, so the verb
-    /// never reaches the paper-doll handler through them.
     #[test]
     fn equipment_slots_are_below_the_floor() {
         let mut s = UiScript::new().unwrap();
@@ -514,7 +410,6 @@ mod tests {
         assert!(s.take_bag_autostores().is_empty());
     }
 
-    /// `PickupBagFromSlot` picks a bank bag up, returns NOTHING, and locks the slot.
     #[test]
     fn pickup_bag_from_slot_takes_the_bag_and_returns_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -532,9 +427,6 @@ mod tests {
         assert!(s.eval::<bool>("return IsInventoryItemLocked(64)").unwrap());
     }
 
-    /// **Destructive, and that is the finding**: `ClearCursor(1,1)` runs unconditionally before
-    /// the slot is even looked at (`0x4c7b79`), so a held payload is dropped even when the slot
-    /// turns out to hold nothing to pick up.
     #[test]
     fn pickup_bag_from_slot_drops_whatever_was_held_first() {
         let mut s = UiScript::new().unwrap();
@@ -548,13 +440,10 @@ mod tests {
         assert!(s.take_container_moves().is_empty(), "no place path exists");
     }
 
-    /// The `TYPEMASK_CONTAINER` resolve (`mov ecx,4`, where `PickupInventoryItem` uses 2): the
-    /// bank's own item slots are inside the gate's range and hold ordinary items, so the verb
-    /// silently no-ops there. A locked bag is refused too.
     #[test]
     fn pickup_bag_from_slot_only_takes_containers_and_never_a_locked_one() {
         let mut s = UiScript::new().unwrap();
-        // Bank vault slot 3 → live id 42, an ordinary item: inside the gate, not a container.
+        // Bank slot 3 is live id 42: inside the gate, but an ordinary item.
         let mut vault = std::collections::HashMap::new();
         vault.insert(
             3,
diff --git a/crates/benilla-ui/src/script/cursor/bar.rs b/crates/benilla-ui/src/script/cursor/bar.rs
index 62ffbfa2..38f1a16f 100644
--- a/crates/benilla-ui/src/script/cursor/bar.rs
+++ b/crates/benilla-ui/src/script/cursor/bar.rs
@@ -1,18 +1,7 @@
-//! The action bar (decision 0216 §7, slice 4; byte-verified 0218 §2/§4): `PickupAction`/
-//! `PlaceAction` join the ONE payload space as the [`CursorAction`] arm. Two things set this
-//! surface apart from bags/doll:
-//!
-//! - **The bar is client-authoritative and actions HOP** (0218 §4, `PlaceAction 0x4e62e0`) — the
-//!   opposite of the post-0218 item swap: placing onto an occupied slot puts the DISPLACED action
-//!   on the cursor rather than clearing, because there is no server round-trip to wait on (the
-//!   120-slot table is ours; [`place_action`] IS the mutation, not a request for one).
-//! - **The engine owns the payload + transition, the app owns the 120-table** (0216 §7's
-//!   ownership split): `model.actions` here is the engine's own OPTIMISTIC mirror of the app's
-//!   authoritative store, kept only so `HasAction`/`GetActionTexture`/&c. read right the instant a
-//!   local pickup/place happens, without waiting a frame for the app to re-feed. Every mutation
-//!   also queues `(lua id, packed)` onto [`Model::action_sets`] — the wire intent the app drains
-//!   into `CMSG_SET_ACTION_BUTTON`, one send per queued entry (0218 §4: a drag-swap is two sends,
-//!   never atomic — this module never coalesces them).
+//! The action-bar cursor verbs. The bar is client-authoritative: placing onto an occupied slot
+//! hops the displaced action onto the cursor (`PlaceAction`, `0x4e62e0`). `model.actions` is an
+//! optimistic mirror of the app's table; each change queues one `CMSG_SET_ACTION_BUTTON`, so a
+//! drag-swap is two sends.
 
 use mlua::Lua;
 
@@ -21,30 +10,18 @@ use crate::script::{ActionSlot, Model};
 
 use super::{queue_cursor_update, CursorAction, CursorPayload};
 
-/// The GlobalStrings key the reference's passive-spell refusal shows — errorId `0x9e`'s entry in
-/// the errorId→key table (`0xb4b498 + 0x9e*0x14 = 0xb4c0f0` ← key ptr `0x84133c`), i.e.
-/// `ERR_PASSIVE_ABILITY` = "You can't put a passive ability in the action bar.". Queued onto
-/// `Model::ui_errors` for the app's action feed to resolve and fire.
+/// The passive-spell refusal's error, errorId `0x9e`: entry `0xb4c0f0` of the table at `0xb4b498`
+/// (stride `0x14`) names this key (`0x84133c`).
 const PASSIVE_ON_BAR_ERROR: &str = "ERR_PASSIVE_ABILITY";
 
-/// Pack `(kind, action)` into the wire's `u32` slot word (`kind<<24 | action`, decision 0216 §1).
+/// The `CMSG_SET_ACTION_BUTTON` slot word.
 fn pack(kind: u8, action: u32) -> u32 {
     (u32::from(kind) << 24) | (action & 0x00FF_FFFF)
 }
 
-/// `PickupAction(id)` — the action-bar slot's shift-click/drag-start entry point (ref
-/// `ActionBarFrame.xml:12-38`'s `IsShiftKeyDown()` fork, `OnDragStart`).
-///
-/// - **A payload is already held** → falls through to [`place_action`] (the reference's own
-///   contract: a shift-click while carrying just places, `ActionButtonTemplate`'s `OnClick` never
-///   special-cases it).
-/// - **Empty cursor, an occupied slot** → picks it up: payload `Action { src_slot: id, kind,
-///   action, texture }`, the slot removed from `model.actions` (optimistic — the app re-pushes an
-///   agreeing snapshot once `action_sets` lands), and `action_sets.push((id, 0))` queued — picking
-///   an action OFF the bar empties it immediately on the wire too (the classic drag-off).
-/// - **Empty cursor, an empty slot** → no-op (nothing to pick up).
-///
-/// Returns whether the caller should repaint (mirrors the container/doll pickup contract).
+/// `PickupAction(id)`, the slot's shift-click and drag start (`ActionBarFrame.xml:12-38`). With a
+/// payload held it places instead; a pickup also clears the slot on the wire at once. Returns
+/// whether to repaint.
 pub(super) fn pickup_action(model: &mut Model, id: u32) -> bool {
     if model.cursor.is_some() {
         return place_action(model, id);
@@ -65,40 +42,14 @@ pub(super) fn pickup_action(model: &mut Model, id: u32) -> bool {
     true
 }
 
-/// `PlaceAction(id)` — the action-bar slot's click-with-payload/`OnReceiveDrag` entry point (ref
-/// `UseAction(id, checkCursor=1)`'s place fork, `ActionBarFrame.xml`'s `OnReceiveDrag`).
-///
-/// Every arm writes the held action into `model.actions[id]` optimistically and queues
-/// `action_sets.push((id, packed))`; what happens to the cursor afterward is the byte-verified
-/// divergence from every other surface (0218 §4): an OCCUPIED destination puts the DISPLACED
-/// action on the cursor (referencing `id` as its new `src_slot` — the slot it can now be placed
-/// FROM), an empty destination just clears.
-///
-/// - Payload **Action** → `(kind, action)` straight off the held payload.
-/// - Payload **Item** → `packed = item_id | ITEM<<24`; the item came from a BAG and STAYS there —
-///   a bar item action is a reference, not a move, so no container move is queued here (the app's
-///   `drain_action_sets` never touches `container_moves` either).
-/// - Payload **Spell** → `packed = spell_id | SPELL<<24` (the producer, `PickupSpell`, lands in
-///   slice 5 — this arm already works once something populates the payload).
-/// - **Empty cursor** → no-op.
-///
-/// Returns whether the caller should repaint.
+/// `PlaceAction(id)`, the slot's `OnReceiveDrag` and `UseAction(id, 1)`'s place fork. An occupied
+/// slot's action hops onto the cursor with `id` as its source; an item stays in its bag, since a
+/// bar item is a reference, not a move. Returns whether to repaint.
 pub(crate) fn place_action(model: &mut Model, id: u32) -> bool {
-    // The two accept filters, byte-read (wow-re `action-item-slot.md` §5 — decision 0666). Both
-    // reject with a **bare return**: no store, no clear, no packet — mechanically identical to
-    // clicking with an empty cursor, and the refused payload STAYS on the cursor.
-    //
-    // - ITEM: placeable iff it has an on-use spell OR is equippable (`4e6571`–`4e6598`). There is
-    //   no quality, bind, class/subclass, container or level test anywhere on that path — a BAG
-    //   is placeable; a grey trade good with neither is silently refused.
-    // - SPELL: a passive (`Attributes & 0x40`) is refused (`4e63ad`), and — unlike the ITEM
-    //   refusal, which is mute — it ALSO raises errorId `0x9e` through `CGGameUI::DisplayError`
-    //   (`4e63ad: push 0x9e; call 0x496720`). That id resolves through the errorId→key table at
-    //   base `0xb4b498`, stride `0x14`: entry `0xb4b498 + 0x9e*0x14 = 0xb4c0f0`, whose static-init
-    //   `4861ff: mov [0xb4c0f0], 0x84133c` names [`PASSIVE_ON_BAR_ERROR`] — "You can't put a
-    //   passive ability in the action bar." (The same arithmetic reproduces the independently
-    //   recorded `ERR_ATTACK_MOUNTED` anchor: `0xa4` → `0xb4c168`.) Closes 0666's named
-    //   divergence, which refused silently while the key was unpinned.
+    // The two accept filters (`0x4e62e0`) refuse with a bare return: nothing stored or sent, and
+    // the payload stays held. An item needs an on-use spell or an equip slot (`0x4e6571`), so a
+    // bag is placeable; a passive spell (`Attributes & 0x40`) also raises errorId `0x9e` through
+    // `DisplayError` (`0x4e63ad`, `0x496720`), where the item refusal is mute.
     match &model.cursor {
         Some(CursorPayload::Item(i)) if !i.bar_placeable => return false,
         Some(CursorPayload::Spell(s)) if s.passive => {
@@ -114,24 +65,13 @@ pub(crate) fn place_action(model: &mut Model, id: u32) -> bool {
         CursorPayload::Action(a) => Some((a.kind, a.action, a.texture.clone())),
         CursorPayload::Item(i) => Some((ACTION_KIND_ITEM, i.item_id, i.texture.clone())),
         CursorPayload::Spell(s) => Some((ACTION_KIND_SPELL, s.spell_id, s.texture.clone())),
-        // Mode 8 — the one non-item/non-spell payload the reference's `PlaceAction` accepts
-        // (`action-item-slot.md` §5's payload table: pet actions and class abilities are refused,
-        // macros are not). It packs the bare macro id under the MACRO tag, exactly as the SPELL
-        // and ITEM arms pack theirs.
+        // `PlaceAction` accepts modes 1, 3, 7 and 8 (`0x4e62e0`): a macro, mode 8, packs its id
+        // under the macro tag. Pet actions (4), coins (2), stabled pets (10) and vendor rows (5)
+        // are refused and stay held.
         CursorPayload::Macro(m) => Some((ACTION_KIND_MACRO, m.index, m.texture.clone())),
-        // Mode 4 — the other half of that same table's refusal (decision 1010). A pet action has
-        // no `CMSG_SET_ACTION_BUTTON` encoding at all, so there is nothing to pack: the payload
-        // goes straight back on the cursor, where the pet bar can still take it.
         CursorPayload::PetAction(_) => None,
-        // Mode 10 (decision 1677) — a stabled pet has no `CMSG_SET_ACTION_BUTTON` encoding either,
-        // so the action bar refuses it and it goes back on the cursor.
         CursorPayload::StablePet(_) => None,
-        // Mode 2 (1962) — `PlaceAction`'s table takes modes 1, 2 and 8 … where its mode 2 is the
-        // BAR-slot pickup, not coins; the money payload has no encoding and goes back.
         CursorPayload::Money(_) => None,
-        // Mode 5 — a vendor row is not a bar action. `PlaceAction`'s payload table takes modes
-        // 1, 2 and 8 only, and the merchant grab is none of them, so it goes back on the cursor
-        // where the vendor window can still take it.
         CursorPayload::Merchant(_) => None,
     };
     let Some((kind, action, texture)) = placeable else {
@@ -144,9 +84,7 @@ pub(crate) fn place_action(model: &mut Model, id: u32) -> bool {
             texture,
             kind,
             action,
-            // The engine holds no item knowledge, so neither half of the Count pair can be
-            // answered here: the app's next-frame re-feed resolves the real bag count and the
-            // `IsConsumableAction` gate together, off the item template (decision 1301).
+            // Count and consumable wait for the app's next-frame re-feed, which knows the item.
             count: 0,
             consumable: false,
         },
@@ -164,9 +102,7 @@ pub(crate) fn place_action(model: &mut Model, id: u32) -> bool {
     true
 }
 
-/// Register the action-bar's cursor globals — top-level, matching the reference
-/// (`PickupAction`/`PlaceAction` are not namespaced any more than `PickupContainerItem`'s cursor
-/// siblings are).
+/// Register `PickupAction` and `PlaceAction` as globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -249,9 +185,6 @@ mod tests {
         assert_eq!(s.take_action_sets(), vec![(7, 133)]);
     }
 
-    /// The byte-verified divergence from bags/doll (0218 §4): placing onto an OCCUPIED action
-    /// slot HOPS the displaced action onto the cursor — two `action_sets` entries across the
-    /// gesture (the pickup's clear, then the place's write), never a container move.
     #[test]
     fn place_action_onto_occupied_hops_the_displaced_action() {
         let mut s = UiScript::new().unwrap();
@@ -262,12 +195,10 @@ mod tests {
         assert_eq!(s.take_action_sets(), vec![(1, 0)]);
 
         assert!(s.eval::<bool>("return PlaceAction(2)").unwrap());
-        // Slot 2 now shows the placed action (111).
         assert_eq!(
             s.eval::<String>("return GetActionTexture(2)").unwrap(),
             "Interface\\Icons\\Spell_A"
         );
-        // The displaced action (222) is now the held payload, sourced from slot 2.
         let (kind, src) = s
             .eval::<(String, i64)>("local k, slot = GetCursorInfo() return k, slot")
             .unwrap();
@@ -282,9 +213,6 @@ mod tests {
             }))
         );
         assert_eq!(s.take_action_sets(), vec![(2, 111)]);
-
-        // A hop is Some→Some: no HIDE+SHOW churn out of one gesture.
-        // (Exercised directly by the SHOWGRID/HIDEGRID test below.)
     }
 
     #[test]
@@ -336,8 +264,6 @@ mod tests {
         assert!(s.take_action_sets().is_empty());
     }
 
-    /// Shift-click while ALREADY holding just places (the reference's own `OnClick` never
-    /// special-cases it): `PickupAction` on a held cursor routes straight to [`super::place_action`].
     #[test]
     fn pickup_action_with_a_payload_held_falls_through_to_place() {
         let mut s = UiScript::new().unwrap();
@@ -353,9 +279,6 @@ mod tests {
         assert_eq!(s.take_action_sets(), vec![(5, 111)]);
     }
 
-    /// `ACTIONBAR_SHOWGRID`/`ACTIONBAR_HIDEGRID` fire on the cursor's None↔Some edges (decision
-    /// 0216 §7) — a pickup shows the grid, a place-onto-empty hides it, and a HOP (Some→Some)
-    /// fires neither (no HIDE+SHOW churn out of one gesture).
     #[test]
     fn showgrid_hidegrid_fire_on_gain_and_loss_not_on_a_hop() {
         let mut s = UiScript::new().unwrap();
@@ -391,9 +314,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return hides").unwrap(), 1);
     }
 
-    /// `PlaceAction`'s ITEM filter (decision 0666): an item with neither an on-use spell nor an
-    /// equip slot — a grey trade good — is refused, and the refusal is a **bare return**: nothing
-    /// stored, nothing sent, and the payload is still on the cursor afterwards.
     #[test]
     fn a_non_usable_non_equippable_item_is_refused_and_stays_held() {
         let mut s = UiScript::new().unwrap();
@@ -423,10 +343,6 @@ mod tests {
         );
     }
 
-    /// The SPELL twin: a passive cannot go on the bar (`Attributes & 0x40`) — and unlike the item
-    /// arm this one SPEAKS, raising errorId `0x9e` = `ERR_PASSIVE_ABILITY` (see
-    /// [`super::place_action`]). The refusal and the toast are separate halves: the refusal is
-    /// still a bare return, so nothing is stored, nothing is sent, and the spell stays held.
     #[test]
     fn a_passive_spell_is_refused_with_the_refs_error_and_stays_held() {
         let mut s = UiScript::new().unwrap();
@@ -453,8 +369,6 @@ mod tests {
         );
     }
 
-    /// The other half of the same law: an ACTIVE spell places normally and raises nothing. Guards
-    /// the obvious over-correction — a toast on every spell drop.
     #[test]
     fn an_active_spell_places_without_an_error() {
         let mut s = UiScript::new().unwrap();
@@ -471,8 +385,6 @@ mod tests {
         assert!(s.take_ui_errors().is_empty());
     }
 
-    /// The positive control on the other side of both filters — a BAG (`InventoryType` 18, no
-    /// on-use spell) IS placeable, which is the one answer people find surprising.
     #[test]
     fn a_bag_is_placeable() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/cursor/doll.rs b/crates/benilla-ui/src/script/cursor/doll.rs
index 6347742e..477488e7 100644
--- a/crates/benilla-ui/src/script/cursor/doll.rs
+++ b/crates/benilla-ui/src/script/cursor/doll.rs
@@ -1,9 +1,5 @@
-//! The paper doll (decision 0208 phase 1b): equipment joins the ONE payload space via
-//! [`super::EQUIPMENT_BAG`]. One extra transition ([`pickup_inventory_item`]) plus four small
-//! satellites ([`equip_cursor_item`], [`cursor_can_go_in_slot`], [`auto_equip_cursor_item`],
-//! [`use_inventory_item`], [`is_inventory_item_locked`]) — everything else (cancel, clear, the
-//! world drop, `SplitContainerItem`) already generalizes from [`super`] because it only ever
-//! matches on the `CursorPayload` enum, never on `bag`.
+//! The paper-doll cursor verbs: an equipped slot is an item source under
+//! [`super::EQUIPMENT_BAG`], so the shared cursor code handles its cancel, clear and world drop.
 
 use mlua::Lua;
 
@@ -13,45 +9,18 @@ use crate::script::Model;
 
 use super::{queue_cursor_update, queue_lock_changed, CursorItem, CursorPayload, EQUIPMENT_BAG};
 
-/// `PickupInventoryItem(id)` — the paper-doll slot's left-click entry point (decision 0208 phase
-/// 1b). Mirrors `container::pickup_container_item`'s click model exactly, keyed on the sentinel
-/// [`EQUIPMENT_BAG`] rather than a real bag id (decision 0216 §1's ONE payload space, extended to
-/// equipment). `id` is the 1-based live-API inventory slot (`GetInventorySlotInfo`'s own
-/// numbering — HeadSlot=1 … TabardSlot=19, the four equipped-bag icons Bag0Slot=20 … Bag3Slot=23).
-/// The bag icons ride the SAME transition (a bag's `equip_slots` is `[20,21,22,23]` from
-/// `find_equip_slot(INVTYPE_BAG)`, so the fit rule already routes a bag onto any bag slot, and
-/// `wire_pos`'s `EQUIPMENT_BAG` arm maps live id 20..23 → the wire's equipped-bag inventory slots
-/// 19..22); ammo (0) stays a named deferral — refused outright, cursor untouched.
-///
-/// **The bank-bag band (64..=69) rides this too**, and only through one door: `PutItemInBag`'s
-/// empty-slot leg IS this function in the reference (`0x4c7c00` calls `0x4c7300` there), which is
-/// how a held bag reaches a bank bag slot at all. Its fit rule is one band wider than
-/// `equip_slots` alone — see [`super::bag_verbs::fits_slot`].
-///
-/// - empty cursor + an occupied, UNLOCKED doll slot → picks it up (payload `Item { bag:
-///   EQUIPMENT_BAG, slot: id, … }`), the same lock/event pair as a bag pickup.
-/// - holding + the SAME slot → cancel (mirrors `pickup_container_item`'s own same-slot branch).
-/// - holding an Item payload whose `equip_slots` contains `id` (the fit rule — `equip_slots` rides
-///   the payload from wherever it was picked up, doll or bag alike) → queues the move (dst =
-///   `(EQUIPMENT_BAG, id)`) and CLEARS (decision 0218: a plain clear, no hop) — UNLESS it's a
-///   split carry (`count: Some(_)`): refused outright, kept (you can't equip a partial stack).
-/// - holding a non-fitting Item, or any Spell/Action payload → no-op, kept (mirrors
-///   `pickup_container_item`'s own refusal of a payload a bag slot can't take).
-///
-/// Returns whether the caller should repaint (the source lock, or the held payload, changed).
+/// `PickupInventoryItem(id)` (`0x4c7300`), the doll slot's click, on the bag click's model: a
+/// fitting whole item moves in and the cursor clears, with no hop; a split or a misfit stays
+/// held. Returns whether to repaint.
 pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
-    // Equipment slots (1..=19) + the four equipped-bag icons (20..=23) + the six BANK bag slots
-    // (64..=69, reached only through `PutItemInBag`); ammo (0) is out of scope.
+    // Head 1 to Tabard 19, the bag slots 20-23, and the bank bag slots, which only `PutItemInBag`
+    // reaches (`0x4c7c00` calls `0x4c7300`). Ammo (0) is refused; its leg is not built.
     if !(1..=23).contains(&id) && !super::bag_verbs::BANK_BAG_INV_SLOTS.contains(&id) {
         return false;
     }
-    // The targeting cursor's item half, on the doll (decision 0923). The reference's doll pickup
-    // `0x4c7300` carries the byte-IDENTICAL rung to the bag one — `4c76df: call 0x6e48a0`
-    // (IsTargeting), `4c76e8: call 0x6e6330` (TargetingWantsItem), `4c76fb: call 0x495d60` (bind
-    // this item), then return with nothing picked up — and it is what makes poisoning or
-    // sharpening the weapon you are *wearing* possible at all. Reported in the ONE bag space
-    // ([`EQUIPMENT_BAG`] + the 1-based slot), so the app's drain resolves both seams identically.
-    // A held payload wins, exactly as in the bag path (the ref's own `4c73af` pair precedes it).
+    // An item-targeting spell binds this slot instead of picking it up, as the bag click does
+    // (`0x4c76df`: `0x6e48a0` IsTargeting, `0x6e6330` TargetingWantsItem, `0x495d60` bind), so a
+    // worn weapon can be poisoned. A held payload wins: `0x4c73af` tests it first.
     if model.item_pick_armed && model.cursor.is_none() {
         model.item_picks.push((EQUIPMENT_BAG, id));
         return false;
@@ -88,9 +57,7 @@ pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
             true
         }
         Some(CursorPayload::Item(held)) => {
-            // A split carry can't equip a partial stack, and a non-fitting item has nowhere to
-            // land on this slot — both refuse, kept exactly as picked up (no event: nothing
-            // transitioned).
+            // A split or a misfit stays held, with no event: nothing changed.
             if held.count.is_some() || !super::bag_verbs::fits_slot(&held, id) {
                 model.cursor = Some(CursorPayload::Item(held));
                 return false;
@@ -106,14 +73,9 @@ pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
             queue_lock_changed(model, held.bag, held.slot);
             true
         }
-        // Mode 5 — the buy, aimed at an equipment slot. `0x4c78fd` tests `[0xb4d900] == 5` inside
-        // the paper-doll click and sends the same `CMSG_BUY_ITEM_IN_SLOT 0x1a3` the bag drop does;
-        // the server equips it or refuses. Reported in the ONE bag space ([`EQUIPMENT_BAG`] + the
-        // 1-based inventory slot), the seam this file already uses for every other doll intent.
-        //
-        // Of the reference's three drop consumers this is the one that handles a stale vendor row
-        // correctly — the other two dereference it (`0x4f9f35`, `0x4c7ea5`) — so its refusal is
-        // what we reproduce in all three.
+        // Mode 5, a buy into this slot: `0x4c78fd` sends `CMSG_BUY_ITEM_IN_SLOT` (`0x1a3`) and the
+        // server equips or refuses. A stale row buys nothing: of the reference's three drop sites
+        // only this one checks it; the other two (`0x4f9f35`, `0x4c7ea5`) dereference it.
         Some(CursorPayload::Merchant(held)) => {
             let entry = model
                 .merchant
@@ -132,10 +94,11 @@ pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
             | CursorPayload::Action(_)
             | CursorPayload::Macro(_)
             | CursorPayload::PetAction(_)
-            // Mode 10 (decision 1677) — a stabled pet refuses a bag/doll slot exactly as the
-            // spell/action family does, and stays on the cursor for the stable window to take.
+            // Mode 10: a stabled pet stays held for the stable window.
             | CursorPayload::StablePet(_)
-            // Mode 2 (1962) — coins have no slot to land in; a money frame's DropFunc takes them.
+            // Mode 2: coins stay held for a money frame's drop. On an occupied slot the reference
+            // picks the item up over either, as it tests only for a held item (`0x4c769a`) or a
+            // preview row (`0x4c76a5`) before the pickup (`0x4c7838`).
             | CursorPayload::Money(_)),
         ) => {
             model.cursor = Some(other);
@@ -144,27 +107,15 @@ pub(super) fn pickup_inventory_item(model: &mut Model, id: u32) -> bool {
     }
 }
 
-/// `EquipCursorItem(id)` — the ref's item-context "Equip" popup entry (not built this slice: no
-/// context menu ships yet). Same transition as placing the held item directly onto doll slot
-/// `id` — [`pickup_inventory_item`]'s place arm already IS that transition, so this simply routes
-/// there (decision 0208 phase 1b: "route both through the same transition").
+/// `EquipCursorItem(id)`: placing the held item on doll slot `id`.
 pub(super) fn equip_cursor_item(model: &mut Model, id: u32) -> bool {
     pickup_inventory_item(model, id)
 }
 
-/// `CursorCanGoInSlot(id)` — whether the held payload could be dropped on doll slot `id`
-/// (decision 0208 phase 1b; the reference's `CURSOR_UPDATE` → `LockHighlight`/`UnlockHighlight`
-/// driver, `PaperDollFrame.lua:609-615`). An Item payload whose `equip_slots` contains `id`;
-/// empty cursor or a Spell/Action payload both answer `false` (the same fit-blind refusal
-/// [`pickup_inventory_item`] gives them — asking a hypothetical doesn't relax the rule).
-///
-/// INTERIM: the byte body's terminal equip-fit check (`0x5da1d0`) was left unresolved by 0216 §5
-/// (0218's own residual, §4 "confirmed as built" — everything else on that list is pinned, this
-/// one function wasn't among the byte-verified findings). `equip_slots` derives from the item
-/// template's `inventoryType` via the SERVER's own mapping instead (`ui_items::find_equip_slot`,
-/// transcribed from vmangos `Player::FindEquipSlot`/`ItemPrototype::GetAllowedEquipSlots`) — a
-/// verifiable authority `SMSG_INVENTORY_CHANGE_FAILURE` referees either way, corrected if a
-/// future pin disagrees with the client's own table.
+/// `CursorCanGoInSlot(id)`, the doll slot's highlight on `CURSOR_UPDATE`
+/// (`PaperDollFrame.lua:609-615`): `equip_slots`, which follows vmangos `Player::FindEquipSlot`,
+/// where the reference's `IsValidForSlot` (`0x5da1d0`) tests a static slot mask per
+/// `InventoryType`.
 pub(super) fn cursor_can_go_in_slot(model: &Model, id: u32) -> bool {
     match &model.cursor {
         Some(CursorPayload::Item(item)) => super::bag_verbs::fits_slot(item, id),
@@ -172,17 +123,10 @@ pub(super) fn cursor_can_go_in_slot(model: &Model, id: u32) -> bool {
     }
 }
 
-/// `AutoEquipCursorItem()` — the model-pane's click-with-payload path (decision 0208 phase 1b,
-/// ref `PaperDollFrame.xml`'s frame-level `OnReceiveDrag`/`OnMouseUp`): an Item payload picked up
-/// from a CONTAINER (`bag >= 0`, a whole stack) queues its `(bag, slot)` source as a NEW
-/// `container_autoequips` intent (the app sends `CMSG_AUTOEQUIP_ITEM` — the server picks the
-/// destination slot itself and swaps any displaced piece back, vmangos `ItemHandler.cpp:138-228`)
-/// and clears the cursor — a plain clear, the same contract as every other placement since
-/// decision 0218. A payload already carried FROM the equipment (`bag == EQUIPMENT_BAG` — a
-/// doll→doll re-drop has nothing for the server to "auto" pick) or a split carry (can't
-/// auto-equip a partial stack) is a no-op, kept; so is any Spell/Action payload.
-///
-/// Returns whether the caller should repaint.
+/// `AutoEquipCursorItem()`, a click or drop on the doll's model (`PaperDollFrame.lua:31-35`): a
+/// whole stack from a bag becomes `CMSG_AUTOEQUIP_ITEM`: the server picks the slot and swaps
+/// the displaced piece back (`ItemHandler.cpp:138-228`); an equipped item or a split stays held.
+/// Returns whether to repaint.
 pub(super) fn auto_equip_cursor_item(model: &mut Model) -> bool {
     match model.cursor.take() {
         Some(CursorPayload::Item(item)) if item.bag >= 0 && item.count.is_none() => {
@@ -198,25 +142,15 @@ pub(super) fn auto_equip_cursor_item(model: &mut Model) -> bool {
     }
 }
 
-/// `UseInventoryItem(id)` — the doll slot's right-click entry point (ref
-/// `PaperDollItemSlotButton_OnClick`, `PaperDollFrame.lua:658-659`): queues `id` for the app to
-/// resolve to the equipped item's guid and send (`CMSG_USE_ITEM`, bag 255 + the 0-based wire slot
-/// — vmangos `HandleUseItemOpcode` takes equipped positions the same as bag ones). No engine-side
-/// refusal — an empty/out-of-range slot is a harmless no-op the app's drain silently drops
-/// (mirrors `UseContainerItem`'s own contract: it never checks the slot either).
+/// `UseInventoryItem(id)`, the doll slot's right-click (`PaperDollFrame.lua:658-659`): the app
+/// sends `CMSG_USE_ITEM` with bag 255 and the 0-based slot, and drops an empty slot unsent.
 pub(super) fn use_inventory_item(model: &mut Model, id: u32) {
     model.inventory_uses.push(id);
 }
 
-/// `IsInventoryItemLocked(id)` — true while `id` is the ACTIVE cursor payload's source (the
-/// picked-up slot dims immediately, no server round-trip — the doll twin of
-/// `GetContainerItemInfo`'s `held_here` derivation) OR the app's fed `InvSlotView.locked` says so
-/// (an outstanding pending op the app's `PendingItemOps` tracks, decision 0216 §4/0218 §3).
-///
-/// Reads through [`Model::inv_slot`], not the doll array, so it answers over the WHOLE live-id
-/// space that binding covers — the reference's `BankFrameItemButton_UpdateLock` calls it with
-/// `BankButtonIDToInvSlotID(...)` for every bank slot, and a lock the vault feed reports has to
-/// dim the button the same as an equipped one.
+/// `IsInventoryItemLocked(id)`: true while `id` is the held item's source or the app reports a
+/// pending operation on it. Reads [`Model::inv_slot`], since `BankFrameItemButton_UpdateLock`
+/// asks about bank slots too.
 pub(super) fn is_inventory_item_locked(model: &Model, id: u32) -> bool {
     let held_here = matches!(&model.cursor, Some(CursorPayload::Item(c)) if c.bag == EQUIPMENT_BAG && c.slot == id);
     let fed = usize::try_from(id)
@@ -226,9 +160,7 @@ pub(super) fn is_inventory_item_locked(model: &Model, id: u32) -> bool {
     held_here || fed
 }
 
-/// Register the paper-doll's cursor globals — all top-level, matching the reference
-/// (`PickupInventoryItem` &c. are not namespaced any more than `PickupContainerItem`'s cursor
-/// siblings are).
+/// Register the paper-doll verbs as globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -284,8 +216,7 @@ mod tests {
     use crate::script::cursor::{CursorAction, CursorPayload, CursorSpell, EQUIPMENT_BAG};
     use crate::script::{ContainerMove, ContainerSlot, ContainerState, InvSlotView, UiScript};
 
-    /// Slots 1 (Head) and 19 (Tabard) occupied, plus the two finger rings (11/12) — a doll
-    /// fixture wide enough to exercise the fit rule, the same-slot cancel, and a doll↔doll swap.
+    /// Head (1), a ring in finger slot 11 that also fits 12, and Tabard (19).
     fn doll_slots() -> crate::script::InventorySlots {
         let mut slots: crate::script::InventorySlots = Default::default();
         slots[1] = Some(InvSlotView {
@@ -320,7 +251,7 @@ mod tests {
             name: Some("Test Ring".into()),
             link: Some("|cffffffff|Hitem:555:0:0:0|h[Test Ring]|h|r".into()),
             locked: false,
-            equip_slots: vec![11, 12], // FINGER1|FINGER2 — the doll↔doll swap fixture
+            equip_slots: vec![11, 12], // either finger: the doll-to-doll swap
             creator: None,
             enchants: Vec::new(),
         });
@@ -513,7 +444,7 @@ mod tests {
         });
         s.set_inventory_slots(slots);
 
-        // Ammo (0) is still refused; the bag icon (20) now picks up the equipped bag.
+        // Ammo (0) is refused; Bag0Slot (20) picks up the equipped bag.
         assert!(!s.eval::<bool>("return PickupInventoryItem(0)").unwrap());
         assert!(s.eval::<bool>("return PickupInventoryItem(20)").unwrap());
         let held = s.cursor_item().expect("bag picked up from the bar");
@@ -523,9 +454,6 @@ mod tests {
         );
     }
 
-    /// Drag-to-equip: a bag carried from the backpack drops onto an empty bag slot (id 21), queuing
-    /// the move to `(EQUIPMENT_BAG, 21)` — the same transition the paper doll uses, and the wire the
-    /// app maps onto equipped-bag inventory slot 20.
     #[test]
     fn place_a_bag_onto_a_bag_slot_queues_the_equip_move() {
         let mut s = UiScript::new().unwrap();
@@ -583,17 +511,14 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_inventory_slots(doll_slots());
 
-        // Empty cursor: false everywhere.
         assert!(!s.eval::<bool>("return CursorCanGoInSlot(1)").unwrap());
 
-        // Item arm: true only for a slot its equip_slots names.
         s.set_container(0, Some(one_fitting_bag_item()));
         s.run("PickupContainerItem(0, 1)").unwrap();
         assert!(s.eval::<bool>("return CursorCanGoInSlot(1)").unwrap());
         assert!(!s.eval::<bool>("return CursorCanGoInSlot(2)").unwrap());
         s.run("ClearCursor()").unwrap();
 
-        // Spell/Action arms: always false (the fit-blind refusal).
         s.set_cursor_for_test(CursorPayload::Spell(CursorSpell {
             passive: false,
             book_slot: 1,
@@ -627,14 +552,12 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_inventory_slots(doll_slots());
 
-        // From the doll itself: nothing for the server to "auto" pick.
         s.run("PickupInventoryItem(1)").unwrap();
         assert!(!s.eval::<bool>("return AutoEquipCursorItem()").unwrap());
         assert!(s.cursor_item().is_some(), "kept");
         assert!(s.take_container_autoequips().is_empty());
         s.run("ClearCursor()").unwrap();
 
-        // A split carry: can't auto-equip a partial stack.
         let mut state = one_fitting_bag_item();
         state.slots.get_mut(&1).unwrap().count = 5;
         s.set_container(0, Some(state));
@@ -694,11 +617,8 @@ mod tests {
         );
     }
 
-    /// The targeting cursor's item half reroutes BOTH pickup seams (decision 0923), and the
-    /// held-payload check precedes it in both — the reference's own order (`4f9c38` before
-    /// `4f9c54`; `4c73af` before `4c76df`). Without the doll seam a rogue could not poison the
-    /// weapon they are wearing; without the payload gate, dragging an item across a bag while a
-    /// poison is armed would silently fire the cast at whatever you dropped it on.
+    /// The held-payload test runs first in both seams: `0x4f9c38` before `0x4f9c54` in the bag,
+    /// `0x4c73af` before `0x4c76df` on the doll.
     #[test]
     fn the_armed_item_half_reroutes_bag_and_doll_clicks() {
         let mut s = UiScript::new().unwrap();
@@ -710,7 +630,7 @@ mod tests {
         assert!(s.cursor_item().is_some());
         assert!(s.take_item_picks().is_empty());
 
-        // Armed but HOLDING: the payload wins, exactly as the reference orders it.
+        // Armed but holding: the payload wins.
         s.set_item_pick_armed(true);
         s.run("PickupContainerItem(0, 1)").unwrap();
         assert!(
@@ -718,8 +638,7 @@ mod tests {
             "a click while carrying an item is a place, not a bind"
         );
 
-        // Armed with an empty cursor: both seams bind instead of picking up, and neither
-        // disturbs the cursor.
+        // Armed with an empty cursor: both seams bind and leave the cursor empty.
         s.run("ClearCursor()").unwrap();
         assert!(s.cursor_item().is_none());
         assert!(!s.eval::<bool>("return PickupInventoryItem(1)").unwrap());
diff --git a/crates/benilla-ui/src/script/cursor/drag.rs b/crates/benilla-ui/src/script/cursor/drag.rs
index 43fc9f3f..de883c71 100644
--- a/crates/benilla-ui/src/script/cursor/drag.rs
+++ b/crates/benilla-ui/src/script/cursor/drag.rs
@@ -1,19 +1,13 @@
-//! The drag gesture (decision 0216 §3) — `RegisterForDrag`/`OnDragStart`/`OnDragStop`/
-//! `OnReceiveDrag`'s mechanics: arm on press, start past a threshold, resolve on release. Split
-//! out of [`super`] purely for size — [`super::pointer`](crate::script::pointer) is the only
-//! external caller (via [`super`]'s re-exports), and the payload types/transition seam this
-//! drives live one level up.
+//! The `RegisterForDrag` gesture: armed on a press, started past a threshold, ended on release.
 
 use crate::script::Model;
 use crate::widget::FrameHandle;
 
-/// INTERIM pixel drag-start threshold (0216 §5 (d) is the byte-verified trigger; the reference
-/// almost certainly uses a small OS/engine drag-distance constant, not this one). Compared with
-/// **strict** `>` — a move exactly at the threshold does not start the gesture.
+/// The drag-start distance in pixels, exceeded strictly; the reference starts at 0.01 frame units
+/// or more from the press (`0x81c468`, squared by `0x76b300`).
 pub(crate) const DRAG_START_THRESHOLD: f32 = 4.0;
 
-/// An in-flight drag gesture: armed at mouse-down on a [`Model::drag_registered`] frame,
-/// `started` once the cursor has moved past [`DRAG_START_THRESHOLD`] from the press point.
+/// A drag armed at a press on a [`Model::drag_registered`] frame, `started` past the threshold.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) struct DragGesture {
     pub(crate) button: String,
@@ -22,22 +16,15 @@ pub(crate) struct DragGesture {
     pub(crate) started: bool,
 }
 
-/// A resolved drag release (a gesture whose button matched the release) — [`Model::drag`] is
-/// always cleared alongside this, win or lose.
+/// A gesture whose button matched the release; [`Model::drag`] is cleared either way.
 pub(crate) struct DragRelease {
-    /// Whether the gesture crossed [`DRAG_START_THRESHOLD`] (so `OnDragStart` fired). A released
-    /// gesture that never started fires nothing — the normal click path proceeds untouched.
+    /// `OnDragStart` fired; an unstarted release fires nothing and the click proceeds.
     pub(crate) started: bool,
     pub(crate) source: FrameHandle,
 }
 
-/// Arm (or clear) the drag gesture on a mouse-DOWN. `hit` is the pressed frame (`None` = the
-/// press hit nothing); a press always REPLACES any leftover in-flight gesture — its matching
-/// release should already have cleared it, but a press is the one moment we know for certain no
-/// gesture should still be armed against a *different* earlier press.
-///
-/// **The replaced gesture is abandoned, not forgotten**: the caller runs [`abandon_drag`] first
-/// and fires `OnDragStop` for a started one. See that function for why a silent drop is the bug.
+/// Arm or clear the gesture on a press, replacing any leftover one; the caller runs
+/// [`abandon_drag`] first so a started gesture still gets its `OnDragStop`.
 pub(crate) fn arm_drag(model: &mut Model, hit: Option<FrameHandle>, button: &str, pos: (f32, f32)) {
     model.drag = hit
         .filter(|&h| {
@@ -54,10 +41,8 @@ pub(crate) fn arm_drag(model: &mut Model, hit: Option<FrameHandle>, button: &str
         });
 }
 
-/// Advance the armed gesture on a mouse-move: once the cursor has moved past
-/// [`DRAG_START_THRESHOLD`] from the press point, mark it started. Returns `(source id, button)`
-/// to fire `OnDragStart` with, exactly once per gesture (already-started and no-gesture both
-/// answer `None`); a source that died before starting fires nothing.
+/// Start the armed gesture once the cursor passes the threshold, returning the `OnDragStart`
+/// source id and button once per gesture; a source that died fires nothing.
 pub(crate) fn maybe_start_drag(model: &mut Model, pos: (f32, f32)) -> Option<(u32, String)> {
     let (source, button) = {
         let g = model.drag.as_ref()?;
@@ -72,12 +57,8 @@ pub(crate) fn maybe_start_drag(model: &mut Model, pos: (f32, f32)) -> Option<(u3
         (g.source, g.button.clone())
     };
     model.drag.as_mut().expect("checked Some above").started = true;
-    // **The button's drag-start edge** — `CSimpleButton` overrides `+0x74` with `0x7793f0`, which
-    // un-presses (`0x779410`, guarded on `locked == 0 && state != DISABLED`) and then forwards to
-    // the base notify that fires `<OnDragStart>`. So a button you drag off releases its pushed art
-    // at the THRESHOLD crossing, which is here — not when the cursor leaves its rect, and not for
-    // a frame that never registered for drag (wow-re `scratch/button-state-edge-set.md`;
-    // decision 2134).
+    // A dragged button un-presses at the threshold, not on leaving its rect: `CSimpleButton`'s
+    // `+0x74` override (`0x7793f0`) un-presses (`0x779410`) before firing `OnDragStart`.
     super::super::button::edge(model, source, crate::widget::ButtonState::on_drag_start);
     let id = model
         .arena
@@ -87,26 +68,14 @@ pub(crate) fn maybe_start_drag(model: &mut Model, pos: (f32, f32)) -> Option<(u3
     Some((id, button))
 }
 
-/// **Abandon** an in-flight gesture that will never see its release, and report whether anything
-/// has to be told. Returns the source of a gesture that had **started**, so the caller fires the
-/// same `OnDragStop` a real release would; an armed-but-unstarted press answers `None`, exactly as
-/// releasing one does.
-///
-/// Two callers, and both are situations the reference simply cannot be in: the OS captures the
-/// pointer for the whole of a button-held drag there, so the release always arrives. Ours does
-/// not — the cursor can walk out of the window, and a second button can be pressed mid-gesture —
-/// and dropping the gesture *silently* in either case is what leaves the UI stuck rather than
-/// merely cancelled: the addon's `OnDragStop → StopMovingOrSizing` never runs, so the engine's
-/// single [`Model::moving`] slot stays taken, [`super::super::object::movable::advance_move`]
-/// keeps gluing that frame to the cursor for the rest of the session, and it swallows every press
-/// aimed at anything underneath. (B310 — the raid grid, where one drag off the window edge cost
-/// every later drag.)
+/// Drop a gesture whose release will never come, because the pointer left the window or a second
+/// button was pressed; the reference cannot lose one, as the OS captures the pointer. Returns a
+/// started one's source, which must get `OnDragStop` or a frame it is moving follows the cursor.
 pub(crate) fn abandon_drag(model: &mut Model) -> Option<FrameHandle> {
     model.drag.take().filter(|g| g.started).map(|g| g.source)
 }
 
-/// Resolve (and clear) the in-flight drag gesture matching a mouse-button release's `button`, if
-/// any (case-insensitive, the `RegisterForClicks` precedent).
+/// Take the gesture whose button matches the release.
 pub(crate) fn take_drag(model: &mut Model, button: &str) -> Option<DragRelease> {
     let g = model
         .drag
@@ -152,10 +121,10 @@ mod tests {
         s.resolve();
 
         s.mouse_button(100.0, 300.0, "LeftButton", true); // press inside A
-        s.mouse_move(102.0, 300.0); // 2px — under the threshold
+        s.mouse_move(102.0, 300.0); // 2px: under the threshold
         assert_eq!(s.eval::<i64>("return drag_starts").unwrap(), 0);
 
-        s.mouse_move(110.0, 300.0); // 10px from the press point — starts
+        s.mouse_move(110.0, 300.0); // 10px from the press: starts
         assert_eq!(s.eval::<i64>("return drag_starts").unwrap(), 1);
         assert_eq!(
             s.eval::<String>("return drag_button").unwrap(),
@@ -193,9 +162,7 @@ mod tests {
 
     #[test]
     fn drag_release_on_the_source_still_suppresses_onclick() {
-        // Without the suppression, a same-frame press+release Up would normally fire OnClick
-        // (a plain Frame's OnClick fires on any same-frame release — see `input.rs`'s click
-        // tests) — proving the drag path takes precedence over that default.
+        // A plain Frame fires OnClick on a same-frame release; a started drag suppresses it.
         let mut s = drag_script();
         s.run(
             r#"
@@ -232,7 +199,7 @@ mod tests {
         s.resolve();
 
         s.mouse_button(100.0, 300.0, "LeftButton", true);
-        s.mouse_move(101.0, 300.0); // 1px — never starts
+        s.mouse_move(101.0, 300.0); // 1px: never starts
         s.mouse_button(100.0, 300.0, "LeftButton", false);
         assert_eq!(
             s.eval::<i64>("return clicks").unwrap(),
@@ -242,9 +209,7 @@ mod tests {
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// A drag released over the world does NOTHING to the payload — no popup, no clear (decision
-    /// 0218, byte-verified: `0x495300` runs on the WorldFrame click release only; a drag release
-    /// routes as a drag, never a click — the director's "it should require an outside up+down").
+    /// The world drop (`0x495300`) runs on a world click's release, never on a drag release.
     #[test]
     fn drag_release_over_nothing_keeps_carrying_no_popup() {
         let mut s = drag_script();
@@ -280,7 +245,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return heard").unwrap(), 0, "no popup");
         assert!(s.cursor_item().is_some(), "the payload keeps carrying");
 
-        // The follow-up CLICK on the world (down + up, both over nothing) is the trigger.
+        // The trigger is a full click on the world, down and up over nothing.
         s.mouse_button(-50.0, -50.0, "LeftButton", true);
         assert_eq!(
             s.eval::<i64>("return heard").unwrap(),
@@ -333,17 +298,8 @@ mod tests {
         assert!(s.cursor_item().is_some(), "the payload stays held");
     }
 
-    /// **The world frame IS the world** — B380 / decision 2089, the regression this file's
-    /// other world-drop tests were structurally blind to.
-    ///
-    /// Every one of them clicks at `(-50, -50)`, where the hit test answers `None`, and the gate
-    /// used to be spelled `hit_id.is_none() && pressed.is_none()`. Decision 1983 put the stock
-    /// `WorldFrame` on the manifest — full-screen, mouse-enabled, `SetAllPoints` — so from that
-    /// day every click a player makes on the world hits a frame, the gate went permanently false
-    /// and dropping an item on the ground stopped doing anything at all. It is exactly the
-    /// reference's own click target for a world click (1984: "the press runs the frame's Lua
-    /// `OnMouseDown` (never consuming), then the `BUTTON1`/`BUTTON2` binding — which **is** the
-    /// world click"), so it belongs on the yes side of the predicate.
+    /// A click on the full-screen stock `WorldFrame` is a world click: in the reference, its press
+    /// runs the frame's `OnMouseDown` without consuming, then the `BUTTON1`/`BUTTON2` binding.
     #[test]
     fn a_click_on_the_world_frame_is_a_world_drop() {
         let mut s = drag_script();
@@ -370,7 +326,7 @@ mod tests {
             equip_slots: Vec::new(),
         }));
 
-        // The fixture's own premise: the click really does land on the world frame.
+        // The premise: the click lands on the world frame.
         let hit = s
             .hit_test(400.0, 300.0)
             .expect("the world frame is full-screen");
@@ -384,9 +340,6 @@ mod tests {
         assert!(s.cursor_item().is_some(), "the payload stays held");
     }
 
-    /// …and a UI frame ON TOP of the world frame is still the UI: press and release both land on
-    /// the plate, so no drop — the other half of [`super::over_world`]'s gate, which a predicate
-    /// that merely asked "is a world frame anywhere under the cursor" would get wrong.
     #[test]
     fn a_click_on_a_frame_above_the_world_frame_is_not_a_world_drop() {
         let mut s = drag_script();
@@ -425,8 +378,7 @@ mod tests {
             "the plate ate the click — that IS the UI consuming it"
         );
 
-        // The mixed pair, both ways round: a press on the plate released over the world, and a
-        // press on the world released over the plate. Neither is a completed world click.
+        // A press and release split across the plate and the world, either way: no world click.
         s.mouse_button(100.0, 300.0, "LeftButton", true);
         s.mouse_button(600.0, 300.0, "LeftButton", false);
         s.mouse_button(600.0, 300.0, "LeftButton", true);
@@ -436,9 +388,6 @@ mod tests {
         assert!(s.cursor_item().is_some());
     }
 
-    /// A click on the world frame with an EMPTY cursor is not the UI consuming anything — the
-    /// return the app's arbiter would read if it ever asked. 1984: the world frame's press
-    /// "never consum[es]".
     #[test]
     fn a_world_frame_click_with_no_payload_consumes_nothing() {
         let mut s = drag_script();
@@ -452,10 +401,7 @@ mod tests {
         );
     }
 
-    /// A world object (unit/GameObject) under the cursor suppresses the world drop entirely
-    /// (decisions 0571 + 0574): the reference's object-leg dispatcher (`0x492ce0`) keeps every
-    /// real payload and runs SELECT — no `DELETE_ITEM_CONFIRM`, payload untouched. The app
-    /// feeds the pick (`set_world_pick`); tests/captures default `Nothing`.
+    /// Over a world object the reference's object leg (`0x492ce0`) selects and keeps the payload.
     #[test]
     fn world_click_over_a_world_object_is_not_a_world_drop() {
         let mut s = drag_script();
@@ -493,8 +439,6 @@ mod tests {
         assert!(s.cursor_item().is_some(), "the item payload survives");
     }
 
-    /// A press over a FRAME whose release lands on the world is neither a click on the frame nor
-    /// a world click — the payload is untouched.
     #[test]
     fn frame_press_world_release_is_not_a_world_drop() {
         let mut s = drag_script();
@@ -529,8 +473,7 @@ mod tests {
         assert!(s.cursor_item().is_some());
     }
 
-    /// A spell/action payload world-CLICK clears silently (`0x495300`'s non-item arms); a drag
-    /// release over the world keeps it carrying, same as an item.
+    /// A non-item payload's world click clears it silently (`0x495300`); a drag release keeps it.
     #[test]
     fn world_click_with_a_spell_payload_clears_silently() {
         let mut s = drag_script();
@@ -571,15 +514,6 @@ mod tests {
         assert!(s.cursor_payload().is_none(), "cleared silently");
     }
 
-    /// **A drag the pointer carries out of the window ENDS, and the frame it was moving stops
-    /// following the cursor** (B310).
-    ///
-    /// The reference cannot reach this state — the OS holds the pointer for a button-held drag, so
-    /// the release always arrives — which is exactly why nothing in FrameXML defends against it and
-    /// why the engine has to. Abandoning the gesture *silently* (what this used to do) skips the
-    /// canonical `OnDragStop → StopMovingOrSizing`, so the single move slot stays taken and
-    /// `advance_move` glues the frame to the cursor for the rest of the session, on top of whatever
-    /// the player is trying to click next.
     #[test]
     fn a_gesture_the_pointer_carries_out_of_the_window_still_fires_its_stop() {
         let mut s = drag_script();
@@ -598,10 +532,8 @@ mod tests {
         s.resolve();
 
         s.mouse_button(150.0, 150.0, "LeftButton", true);
-        s.mouse_move(200.0, 200.0); // past the threshold ⇒ OnDragStart ⇒ StartMoving
-                                    // `StartMoving` samples the cursor where it is CALLED, so the starting move moves nothing
-                                    // (`tests::movable`'s own note) — this is the one that carries the frame.
-        s.mouse_move(250.0, 250.0);
+        s.mouse_move(200.0, 200.0); // past the threshold: OnDragStart, StartMoving
+        s.mouse_move(250.0, 250.0); // StartMoving anchors on its call; this move carries
         s.resolve();
         let carried: f32 = s.eval("return A:GetLeft()").unwrap();
         assert_eq!(carried, 150.0, "the frame followed the cursor's 50px");
@@ -613,7 +545,7 @@ mod tests {
             "the abandon fires the same OnDragStop a release would"
         );
 
-        // …and the move slot is free, so nothing follows the cursor any more.
+        // The move slot is free: nothing follows the cursor.
         s.mouse_move(600.0, 500.0);
         s.resolve();
         assert_eq!(
@@ -627,9 +559,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return stops").unwrap(), 1);
     }
 
-    /// The same abandon, by the other door: a fresh press REPLACES an in-flight gesture, and a
-    /// started one has to be told. Pressing a second button mid-drag is an ordinary slip of the
-    /// hand, and it used to leave the same stuck move slot.
     #[test]
     fn a_press_that_replaces_an_in_flight_gesture_stops_it_first() {
         let mut s = drag_script();
@@ -658,8 +587,7 @@ mod tests {
             "the left drag the right press displaced was stopped, not forgotten"
         );
 
-        // An armed-but-UNSTARTED press fires nothing when it is replaced — the same silence a
-        // release of one gets.
+        // Replacing an unstarted press fires nothing, as releasing it would not.
         s.mouse_button(150.0, 150.0, "LeftButton", true);
         s.mouse_button(150.0, 150.0, "MiddleButton", true);
         assert_eq!(s.eval::<i64>("return stops").unwrap(), 1);
diff --git a/crates/benilla-ui/src/script/cursor/money.rs b/crates/benilla-ui/src/script/cursor/money.rs
index 24d0fd64..e70fbf63 100644
--- a/crates/benilla-ui/src/script/cursor/money.rs
+++ b/crates/benilla-ui/src/script/cursor/money.rs
@@ -1,29 +1,6 @@
-//! The money cursor — payload mode 2 (decisions 1962, 1965): coins picked up off a money frame,
-//! and everything the reference does with them. VERIFIED at the bytes throughout — wow-re
-//! `money-cursor-law.md` (commit `a4dc2ff4`), which 1965 folded in:
-//!
-//! * **The purse is never debited.** Nothing on this path writes `PLAYER_FIELD_COINAGE`; the
-//!   backpack's figure is `GetMoney() − GetCursorMoney() − GetPlayerTradeMoney()`, FrameXML
-//!   arithmetic. Dropping credits nothing back because nothing was taken.
-//! * `PickupPlayerMoney(amount)` raises on a non-number, truncates, and refuses SILENTLY on a zero
-//!   amount, on lost player control, and on more than the purse holds (unsigned). It clears the
-//!   cursor first — whose tail fires `CURSOR_UPDATE` before the money lands — then installs mode 2,
-//!   plays `LOOTWINDOWCOINSOUND`, sets the coin bitmap by magnitude and fires `PLAYER_MONEY`.
-//! * `DropCursorMoney()` is an absolute no-op without money on the cursor; otherwise the coin
-//!   sound, `PLAYER_MONEY`, then mode 0 and `CURSOR_UPDATE`. No drop kit, no packet.
-//! * `CursorHasMoney()` answers the number `1` or `nil`, never a boolean.
-//! * `AddTradeMoney()` (0 args) folds the coins into the trade offer as an ABSOLUTE
-//!   `CMSG_SET_TRADE_GOLD` of `offer + cursor`, gated on the purse covering the total; a refusal
-//!   leaves the money held. Success clears the cursor with no `PLAYER_MONEY`.
-//! * `PickupTradeMoney(amount)` raises on a non-number; `amount <= 0` or `> offer` (both SIGNED)
-//!   refuse silently; else `0x11F` with `offer − amount`, then the coins onto the cursor with
-//!   `PLAYER_MONEY`.
-//! * `GetCoinIcon(amount)` raises on a non-number and answers `INV_Misc_Coin_0N` by the signed
-//!   thresholds of [`coin_icon`] — the cursor's own bitmap goes by the same table.
-//!
-//! One thing this engine's deferred event lane cannot reproduce: the reference's `CURSOR_UPDATE`
-//! handler runs synchronously inside the clear, before the coins land, so `CursorHasMoney()` is
-//! nil there; ours runs at the next dispatch and sees the coins. Named, not hidden.
+//! The money cursor, payload mode 2: coins taken off a money frame; the purse is never debited.
+//! Deviation: a `CURSOR_UPDATE` handler already sees the coins, because events are queued; the
+//! reference runs it inside the clear, before they land.
 
 use mlua::{Lua, Value};
 
@@ -31,9 +8,8 @@ use super::{queue_cursor_update, CursorMoney, CursorPayload};
 use crate::script::binding_abi::{flag, number_arg};
 use crate::script::Model;
 
-/// The coin icon for an amount of copper — `GetCoinIcon 0x48d4e0`'s table, SIGNED thresholds
-/// (a negative amount reads as the smallest coin). The loot window's coin slot and the money
-/// cursor's bitmap use the same table.
+/// The coin icon for an amount of copper: `GetCoinIcon`'s table (`0x48d4e0`), thresholds signed.
+/// The loot window's coin slot and the money cursor use it too.
 pub fn coin_icon(copper: i64) -> &'static str {
     if copper < 10 {
         "Interface\\Icons\\INV_Misc_Coin_05"
@@ -50,7 +26,6 @@ pub fn coin_icon(copper: i64) -> &'static str {
     }
 }
 
-/// The copper on the cursor, `0` when it holds anything else or nothing.
 pub(crate) fn cursor_money(model: &Model) -> u32 {
     match &model.cursor {
         Some(CursorPayload::Money(m)) => m.copper,
@@ -58,17 +33,15 @@ pub(crate) fn cursor_money(model: &Model) -> u32 {
     }
 }
 
-/// Queue `PLAYER_MONEY` — the purse frames' repaint, which is how the held coins leave the
-/// backpack's figure without the purse moving.
+/// Queue `PLAYER_MONEY`, which repaints the money frames less the held coins.
 fn queue_player_money(model: &mut Model) {
     model
         .pending_events
         .push(("PLAYER_MONEY".to_string(), Vec::new()));
 }
 
-/// Put `copper` on the cursor the way `0x494cc0` does: the inner clear (whose tail fires
-/// `CURSOR_UPDATE`, and which fires a `PLAYER_MONEY` of its own when the cursor already held
-/// coins), then the payload, then `PLAYER_MONEY`.
+/// Put coins on the cursor as `0x494cc0` does: the inner clear's `CURSOR_UPDATE`, after its own
+/// `PLAYER_MONEY` if coins were already held, then the payload and `PLAYER_MONEY`.
 fn install_money(model: &mut Model, copper: u32) {
     if matches!(model.cursor, Some(CursorPayload::Money(_))) {
         queue_player_money(model);
@@ -79,7 +52,7 @@ fn install_money(model: &mut Model, copper: u32) {
     queue_player_money(model);
 }
 
-/// `PickupPlayerMoney`'s body after the argument gate.
+/// `PickupPlayerMoney` after the argument gate; each refusal is silent.
 pub(crate) fn pickup_player_money(model: &mut Model, copper: u32) -> bool {
     if copper == 0 || !model.player_control || u64::from(copper) > model.money {
         return false;
@@ -88,7 +61,7 @@ pub(crate) fn pickup_player_money(model: &mut Model, copper: u32) -> bool {
     true
 }
 
-/// `DropCursorMoney`'s body.
+/// `DropCursorMoney`: `PLAYER_MONEY`, then the clear's `CURSOR_UPDATE`, and no packet.
 pub(crate) fn drop_cursor_money(model: &mut Model) -> bool {
     if !matches!(model.cursor, Some(CursorPayload::Money(_))) || !model.player_control {
         return false;
@@ -99,9 +72,8 @@ pub(crate) fn drop_cursor_money(model: &mut Model) -> bool {
     true
 }
 
-/// `AddTradeMoney`'s body, and the money arm `ClickTradeButton` / `ClickTargetTradeButton` and
-/// the trade window's open leg run first: the coins into the offer as an absolute total, gated
-/// on the purse covering it; a refusal leaves them held. Returns whether the coins moved.
+/// `AddTradeMoney`, also run first by `ClickTradeButton`, `ClickTargetTradeButton` and the trade
+/// window's open: the offer becomes offer plus cursor, if the purse covers it.
 pub(crate) fn add_trade_money(model: &mut Model) -> bool {
     let copper = cursor_money(model);
     if copper == 0 {
@@ -123,8 +95,8 @@ pub(crate) fn add_trade_money(model: &mut Model) -> bool {
     true
 }
 
-/// `PickupTradeMoney`'s body after the argument gate: signed gates, the trimmed offer on the
-/// wire first, then the coins onto the cursor.
+/// `PickupTradeMoney` after the argument gate: signed gates, then `CMSG_SET_TRADE_GOLD` (`0x11F`)
+/// with the trimmed offer, then the coins onto the cursor.
 pub(crate) fn pickup_trade_money(model: &mut Model, amount: i32) -> bool {
     let offer = model.trade.as_ref().map_or(0, |t| t.player.gold) as i32;
     if amount <= 0 || amount > offer {
@@ -140,8 +112,7 @@ pub(crate) fn pickup_trade_money(model: &mut Model, amount: i32) -> bool {
 }
 
 impl crate::script::UiScript {
-    /// The trade window's open leg (`SetTradePartner 0x4bf4e0`, §4b): coins held on the cursor
-    /// fold into the offer before anything else. Answers the new offer when they did.
+    /// The trade window's open (`SetTradePartner`, `0x4bf4e0`) folds held coins into the offer.
     pub fn fold_cursor_money_into_trade(&mut self) -> Option<u32> {
         let mut model = self.model_mut();
         add_trade_money(&mut model).then(|| model.trade.as_ref().map_or(0, |t| t.player.gold))
@@ -239,7 +210,6 @@ mod tests {
         );
         assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 12_345);
         assert!(s.cursor_item().is_none(), "coins are not an item cursor");
-        // The drop: coin sound and PLAYER_MONEY (the app's), mode 0, CURSOR_UPDATE — no packet.
         s.run("DropCursorMoney()").unwrap();
         assert_eq!(s.eval::<i64>("return GetCursorMoney()").unwrap(), 0);
         assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 12_345);
diff --git a/crates/benilla-ui/src/script/cursor/pet.rs b/crates/benilla-ui/src/script/cursor/pet.rs
index 60b68a4a..96216381 100644
--- a/crates/benilla-ui/src/script/cursor/pet.rs
+++ b/crates/benilla-ui/src/script/cursor/pet.rs
@@ -1,35 +1,8 @@
-//! The pet bar's drag (decision 1010; wow-re `ui/scratch/pet-action-bar-api.md` §10.3/§10.4/§10.7)
-//! — **one** Lua verb, `PickupPetAction`, which forks on whether the cursor is already carrying a
-//! pet payload. The reference's own bar calls it from all three gestures (`PetActionButton_OnClick`
-//! under shift, `OnDragStart`, and `OnReceiveDrag` — `PetActionBarFrame.lua:252-283`), so "pick up"
-//! and "drop" are the same binding seen from either side of an empty cursor.
-//!
-//! **Three things set this surface apart from [`super::bar`]'s**, and each is why this is its own
-//! module rather than an arm of that one:
-//!
-//! - **The payload is a WORD, forwarded verbatim.** `0x4bce00` hands the cursor's dword straight to
-//!   the assign core without reading a field of it, and the core's only write is
-//!   `bar[target] = *source`. There is no drop-time encoding — see [`CursorPetAction`].
-//! - **The bar's contents are the SERVER's.** Nothing but a pet slot can produce this payload and
-//!   nothing but a pet slot accepts it, so the drag can only ever *rearrange* ten words the last
-//!   `SMSG_PET_SPELLS` delivered. That is the opposite of the action bar, where the 120-slot table
-//!   is ours and a drag populates it.
-//! - **A displaced occupant is RELOCATED inside the bar before it is handed back.** The action bar
-//!   hops the displaced action onto the cursor unconditionally; here the core first tries to keep
-//!   it on the bar (a duplicate's slot, or an empty non-token slot), and only a target that was
-//!   *not* a token hands its occupant to the cursor.
-//!
-//! **A drop always empties the cursor first** (`0x495190 ClearCursor(1,1)`, run by all three of
-//! `0x4bce00`'s callers *before* the accept decision), and only a write that relocated nothing
-//! re-fills it, with the displaced occupant (`0x4bce38 test eax,eax; je`). So every refusal loses
-//! the payload — read at the bytes, all six of `0x4bc9a0`'s exits: the no-op on an equal dword
-//! (`0x4bc9ed xor eax,eax`), the passive-source reject (`0x4bca28`), the token abort, and both
-//! never-blocking front gates all return `EAX = 0`. 1010 shipped the inverse of this as a named
-//! divergence — a refused drop kept its payload — and the director retired it (1016): the case it
-//! was protecting against is a drop the reference simply does not make, and dropping a pet spell
-//! *away* from the bar is how you take it off the bar in the first place.
-//!
-//! (The **clamp** on slot 11 is still ours, and still deliberate — see [`PET_SLOTS`].)
+//! The pet bar's one drag verb, `PickupPetAction`: a pickup with an empty cursor, a drop with a
+//! pet payload held (`PetActionBarFrame.lua:252-283`). Only a pet slot makes or takes the
+//! payload, a word carried verbatim (`0x4bce00`), so a drag only rearranges the bar the server
+//! sent. A drop clears the cursor before deciding (`0x495190`) and only a write that relocated
+//! nothing refills it (`0x4bce38`), so a refused drop loses the payload, as in the reference.
 
 use mlua::Lua;
 
@@ -37,51 +10,39 @@ use crate::script::Model;
 
 use super::{queue_cursor_update, CursorPayload, CursorPetAction};
 
-/// Pet bar slots — the reference's `NUM_PET_ACTION_SLOTS` and vmangos's
-/// `MAX_UNIT_ACTION_BAR_INDEX`, the same 10.
-///
-/// **The clamp lives here**, and it is a deliberate divergence from the reference's own arithmetic:
-/// its callers gate `cmp esi,0xa; jbe`, which admits index 10 (Lua argument 11), and neither
-/// `0x4bce00` nor `0x4bc9a0` bounds-checks again — so a real client writes one dword *past* the
-/// ten-slot array. Not reproduced (wow-re §10.7 says so in as many words).
+/// Pet bar slots (`NUM_PET_ACTION_SLOTS`, vmangos `MAX_UNIT_ACTION_BAR_INDEX`). Deviation: slot
+/// 11 is refused, because the reference's gate (`cmp esi,0xa; jbe`) admits it and neither
+/// `0x4bce00` nor `0x4bc9a0` bounds-checks again, so it writes one dword past the array.
 const PET_SLOTS: u32 = 10;
 
-/// The client's slot type, masked as it masks it (`(packed >> 24) & 0x3F`).
+/// The slot type as the client masks it.
 fn kind(packed: u32) -> u8 {
     ((packed >> 24) & 0x3F) as u8
 }
 
-/// A **token** slot — a command (7) or a reaction (6). The core treats the two identically
-/// everywhere it asks the question: a token occupant is what forces the relocation search, and a
-/// token is what disqualifies a slot from being a relocation candidate.
+/// A command (7) or reaction (6) word, which the core treats alike.
 fn is_token(packed: u32) -> bool {
     matches!(kind(packed), 6 | 7)
 }
 
-/// Can this word ride the cursor at all? `0x494e20`'s own jump table (`0x494f40`) routes types
-/// 1–5 / 6 / 7 and **bails on type 0 or ≥ 8** — so an empty or nonsense word produces no payload,
-/// which is what makes "displaced an empty slot" hand back nothing rather than a blank carry.
+/// The word as a payload, if it can be one: `0x494e20`'s jump table (`0x494f40`) takes types 1-7
+/// only, so displacing an empty slot carries nothing.
 fn payload_word(packed: u32) -> Option<u32> {
     (1..=7).contains(&kind(packed)).then_some(packed)
 }
 
-/// The duplicate scan's comparison key (`0x4bca44`/`0x4bca57`, mask `0x3FFFFFFF`) — everything but
-/// the two autocast bits. **Not** type-1-only: the note's earlier prose said the duplicate clear
-/// was, and the bytes say the mask covers the whole type+action field for any source type.
+/// The duplicate scan's compare (`0x4bca44`, `0x4bca57`): all but the autocast bits, any type.
 fn same_action(a: u32, b: u32) -> bool {
     a & 0x3FFF_FFFF == b & 0x3FFF_FFFF
 }
 
-/// The blanked-spell shape `PickupPetAction` writes back into a picked-from slot: type 1 with a
-/// zero id. The duplicate scan is skipped for exactly this source (`0x4bca34`–`0x4bca3e`) — it
-/// would otherwise match every other blanked slot on the bar.
+/// The word a spell pickup leaves in its slot: type 1, id 0. The duplicate scan skips this
+/// source (`0x4bca34`), which would otherwise match every other blanked slot.
 fn is_blanked_spell(packed: u32) -> bool {
     kind(packed) == 1 && packed & 0xFFFF == 0
 }
 
-/// A relocation **candidate** (`0x4bca8b`–`0x4bcab0`): not a token, and its low 16 bits zero. So an
-/// all-zero slot qualifies and so does a blanked type-1 slot — the note's earlier "token-or-empty"
-/// reading was wrong in both directions.
+/// A slot a token occupant may move to (`0x4bca8b`), such as an empty or blanked-spell slot.
 fn is_relocation_candidate(packed: u32) -> bool {
     !is_token(packed) && packed & 0xFFFF == 0
 }
@@ -90,31 +51,15 @@ fn is_relocation_candidate(packed: u32) -> bool {
 struct Assigned {
     /// The slot the target's previous occupant was moved to, if it was moved.
     reloc: Option<usize>,
-    /// The occupant left with nowhere to go — the cursor's new load. `None` when it was relocated,
-    /// and `None` when the target was empty (nothing to carry).
+    /// The occupant with nowhere to go, for the cursor; `None` if it was relocated or empty.
     displaced: Option<u32>,
 }
 
-/// The assign core `0x4bc9a0(target, source, sendFlag = 1)` — "set a pet action", and the whole of
-/// what a drop does. `None` = nothing was written and nothing should be sent.
-///
-/// The gates, in the binary's order:
-///
-/// 1. **no-op** when the source equals the target's current word, compared as the **full unmasked
-///    dword** (`0x4bc9e2`) — autocast bits included, so re-dropping a slot on itself is inert.
-/// 2. **silent reject** of a passive spell source (`0x4bc9f8`–`0x4bca2e`). No error id, unlike the
-///    player bar's `PlaceAction`, which raises `0x9e` for the same test.
-/// 3. **duplicate scan**, slots ascending: the first slot that carries the same action (and is not
-///    the target) becomes the relocation slot, and the token search is **short-circuited entirely**
-///    (`0x4bca78`). This is what makes the ordinary drag a swap.
-/// 4. otherwise, if the target's occupant **is a token**, search for a candidate slot to move it
-///    to; **no candidate ⇒ abort**, nothing written and nothing sent.
-/// 5. write `bar[reloc] = old occupant` (when there is one) and `bar[target] = source`.
-///
-/// The reference's return value is `EAX = 1` iff **no** relocation happened (`0x4bcb92 setl`) —
-/// so an abort and a successful relocation are indistinguishable at the call. That is the one thing
-/// a re-implementation must not read as "did the write happen", which is why this returns
-/// [`Assigned`] and never a bool.
+/// The assign core (`0x4bc9a0`), the whole of a drop; `None` is no write and no send. In order:
+/// an identical dword is a no-op (`0x4bc9e2`), a passive spell is refused silently (`0x4bc9f8`),
+/// a duplicate's slot takes the occupant, which makes a drag a swap (`0x4bca78`), else a token
+/// occupant needs a candidate slot or the drop aborts. The reference's return (`0x4bcb92`), 1
+/// only when nothing was relocated, cannot tell an abort from a relocation; this one can.
 fn assign(slots: &mut [u32], target: usize, source: u32, passive: bool) -> Option<Assigned> {
     let occupant = *slots.get(target)?;
     if occupant == source {
@@ -129,11 +74,9 @@ fn assign(slots: &mut [u32], target: usize, source: u32, passive: bool) -> Optio
         reloc = (0..slots.len()).find(|&i| i != target && same_action(slots[i], source));
     }
     if reloc.is_none() && is_token(occupant) {
-        // No `j != target` guard, and none is needed: this branch only runs when the target's own
-        // occupant IS a token, which disqualifies it as a candidate. The bytes have no guard here
-        // either.
+        // No `j != target` guard, as in the reference: the target's token is never a candidate.
         reloc = (0..slots.len()).find(|&j| is_relocation_candidate(slots[j]));
-        reloc?; // the abort — a token occupant with nowhere to go writes and sends nothing
+        reloc?; // the abort: a token with nowhere to go writes and sends nothing
     }
 
     if let Some(j) = reloc {
@@ -146,21 +89,10 @@ fn assign(slots: &mut [u32], target: usize, source: u32, passive: bool) -> Optio
     })
 }
 
-/// `PickupPetAction(slot)` — the pet bar's one drag verb, 1-based (ref
-/// `PetActionBarFrame.lua:252-283`; the binding `0x4be180`).
-///
-/// - **`UNIT_FLAG_POSSESSED` set** ⇒ nothing at all. The gate sits above the cursor fork
-///   (`0x4be1c1`), so it blocks the drop as well as the pick-up.
-/// - **carrying a pet payload** ⇒ [`place_pet_action`].
-/// - **carrying anything else** ⇒ nothing. The reference only enters its drop trampoline when the
-///   *pet* payload global is non-empty; a held spell or item is not that global and simply stays
-///   held. (Which is the same fact as "a pet bar cannot be populated, only rearranged".)
-/// - **empty cursor** ⇒ pick the slot up: the payload is its word verbatim, and — **for a spell
-///   slot only** (`0x4be268 cmp cl,1`) — the slot is written back with its id zeroed, through the
-///   same assign core and with the same send. A token slot keeps its contents while its word rides
-///   the cursor, which is how a command ends up *copied* onto another slot rather than moved.
-///
-/// Returns whether the caller should repaint.
+/// `PickupPetAction(slot)` (`0x4be180`), 1-based. `UNIT_FLAG_POSSESSED` blocks both ends, its
+/// gate sitting above the cursor fork (`0x4be20a`). Another payload stays held here, where the
+/// reference clears it (`0x4be220`) and picks the slot up. A pickup blanks only a spell slot
+/// (`0x4be268`), so a dragged token is copied, not moved.
 pub(super) fn pickup_pet_action(model: &mut Model, slot: u32) -> bool {
     if !model.pet_bar.pickup_allowed {
         return false;
@@ -184,13 +116,8 @@ pub(super) fn pickup_pet_action(model: &mut Model, slot: u32) -> bool {
         passive: view.passive,
         texture: view.texture.clone(),
     }));
-    // A SPELL slot empties as it is picked up — id zeroed, type and autocast bits kept — and the
-    // server is told. Everything else keeps its slot.
-    //
-    // `passive: false` is not a shortcut: the assign core's passive gate reads the record of the
-    // **source word's own spell id**, and the blanked word's id is 0, which resolves to no record
-    // at all. So a passive spell still empties its slot when picked up — the refusal comes later,
-    // when the payload is dropped somewhere.
+    // A spell slot keeps its type and autocast bits with id 0, and the server is told. `false` is
+    // right: the passive gate reads the source's spell record, and id 0 has none.
     if kind(packed) == 1 {
         write_slot(model, index, packed & 0xFFFF_0000, false);
     }
@@ -198,31 +125,19 @@ pub(super) fn pickup_pet_action(model: &mut Model, slot: u32) -> bool {
     true
 }
 
-/// The drop half. Runs the assign core against the engine's optimistic mirror of the ten words,
-/// queues the resulting `(0-based position, word)` pairs for the app to send as one
-/// `CMSG_PET_SET_ACTION`, and disposes of the cursor:
-///
-/// - **write, occupant homeless** ⇒ the occupant goes onto the cursor (the trampoline's
-///   `0x4bce3d`, reached only on the core's `EAX = 1`) — the familiar swap-in-hand.
-/// - **write, occupant relocated** ⇒ the cursor empties; the displaced word is still on the bar.
-/// - **no write** (self-drop, passive source, or the token abort) ⇒ the cursor empties too, and
-///   the payload is gone. `ClearCursor` ran before the decision and `EAX = 0` never re-fills.
-///
-/// The cursor is therefore emptied on **every** path out of here, including the ones that return
-/// `false` — `false` is "nothing was written", not "nothing happened".
+/// The drop: the cursor always empties, and only a homeless occupant refills it (`0x4bce3d`).
+/// Returns whether anything was written; the cursor empties on `false` too.
 fn place_pet_action(model: &mut Model, slot: u32) -> bool {
     let Some(CursorPayload::PetAction(held)) = model.cursor.clone() else {
         return false;
     };
-    // `ClearCursor(1,1)` — unconditional, and *before* anything is decided. Past the possessed
-    // gate in `PickupPetAction` there is no way back out of here still holding the payload.
+    // `ClearCursor(1,1)`, unconditionally, before anything is decided.
     model.cursor = None;
     let Some(index) = slot_index(model, slot) else {
         queue_cursor_update(model);
         return false;
     };
-    // The target's own view, read BEFORE the write — a displaced word's passive bit and icon are
-    // its slot's, not the payload's we are about to consume.
+    // Read before the write: a displaced word's passive bit and icon are its slot's.
     let occupant_view = model.pet_bar.slots[index].view.clone();
     let Some(assigned) = write_slot(model, index, held.packed, held.passive) else {
         queue_cursor_update(model);
@@ -241,7 +156,7 @@ fn place_pet_action(model: &mut Model, slot: u32) -> bool {
     true
 }
 
-/// The 1-based button index → an in-range slot of a bar that exists.
+/// The 0-based index of a 1-based slot on a bar that exists.
 fn slot_index(model: &Model, slot: u32) -> Option<usize> {
     if !model.pet_bar.has_bar || slot == 0 || slot > PET_SLOTS {
         return None;
@@ -250,20 +165,14 @@ fn slot_index(model: &Model, slot: u32) -> Option<usize> {
     (index < model.pet_bar.slots.len()).then_some(index)
 }
 
-/// Run [`assign`] against the engine's mirror and queue what changed. Split out because the pickup
-/// path needs it too — the reference routes its own slot-blanking through the same core, with the
-/// same send (`0x4be268`+).
-///
-/// The mirror is optimistic in exactly [`super::bar`]'s sense: the app owns the authoritative ten
-/// words and re-pushes them, but a drag must read right in the same frame it happens.
+/// Run [`assign`] on the engine's optimistic mirror of the ten words and queue the send; the
+/// pickup's blank goes through it too, as in the reference (`0x4be268`).
 fn write_slot(model: &mut Model, target: usize, source: u32, passive: bool) -> Option<Assigned> {
     let mut words: Vec<u32> = model.pet_bar.slots.iter().map(|s| s.view.packed).collect();
     let assigned = assign(&mut words, target, source, passive)?;
 
-    // One send carrying one or two `(position, data)` pairs — the optional relocation pair FIRST,
-    // then the mandatory target pair, exactly the order `0x4bcad4`+ builds them and exactly what
-    // `CMSG_PET_SET_ACTION` accepts. The relocation pair goes out whenever there was a relocation,
-    // without re-testing whether the word changed: that is the binary's own `if (relocSlot >= 0)`.
+    // One `CMSG_PET_SET_ACTION`: the relocation pair first whenever there was one, changed or
+    // not, then the target pair (`0x4bcad4`).
     let mut entries: Vec<(u32, u32)> = Vec::with_capacity(2);
     if let Some(j) = assigned.reloc {
         entries.push((j as u32, words[j]));
@@ -277,14 +186,8 @@ fn write_slot(model: &mut Model, target: usize, source: u32, passive: bool) -> O
     Some(assigned)
 }
 
-/// A **token** word's `texture` is the NAME of a global, not a path — `GetPetActionInfo`'s own
-/// convention (§2.4: the two `char[32]` tables hand back `PET_ATTACK_TEXTURE`, and the bar paints
-/// with `getglobal(texture)`). The cursor takes a PATH, so a command or reaction word that reaches
-/// the cursor has to carry one, or the drag is invisible — you pick Attack up and nothing sticks
-/// to the pointer. Resolved here, the one place a slot's view becomes a cursor payload, exactly as
-/// `PetActionBar.xml` resolves it in the one place a slot's view becomes a button.
-///
-/// A spell word already carries a real `Interface\Icons\…` path and is left alone.
+/// A token's texture is a global's name (`GetPetActionInfo`, `0x4bdc50`), which the bar resolves
+/// with `getglobal` (`PetActionBarFrame.lua:102`); the cursor needs the path, resolved here.
 fn resolve_token_icon(lua: &Lua) {
     let name = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -312,8 +215,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let mut model = lua.app_data_mut::<Model>().expect("model app_data");
                 pickup_pet_action(&mut model, slot)
             };
-            // Both halves can leave a TOKEN on the cursor — the pick-up directly, the drop through
-            // its displaced occupant — so the resolution hangs off the binding, not off either arm.
+            // Both the pickup and a drop's displaced occupant can put a token on the cursor.
             resolve_token_icon(lua);
             Ok(took)
         })?,
@@ -326,9 +228,8 @@ mod tests {
     use super::*;
     use crate::script::{PetActionView, UiScript};
 
-    /// The words a hunter's bar actually carries. `FILLER` is vmangos's own unused-slot shape
-    /// (`ACT_DISABLED` + spell id 0) — masked type 1 with a zero low word, which is exactly the
-    /// relocation candidate the core hunts for, and the reason it must not be flattened to 0.
+    /// A hunter's bar words. `FILLER` is vmangos's unused slot, `ACT_DISABLED` with spell 0: type
+    /// 1, not a zero word, so it must stay as sent.
     const ATTACK: u32 = 0x0700_0002;
     const FOLLOW: u32 = 0x0700_0001;
     const DEFENSIVE: u32 = 0x0600_0001;
@@ -337,9 +238,7 @@ mod tests {
     const BITE: u32 = 0x8100_0EC1;
     const FILLER: u32 = 0x8100_0000;
 
-    /// A source that is **still on the bar** swaps with its destination: the duplicate scan finds
-    /// the copy, that slot takes the occupant, and the cursor comes away empty. This is the path a
-    /// TOKEN drag always takes, because a token pickup does not blank its source slot.
+    /// A token drag always takes this path: a token pickup leaves its slot as it was.
     #[test]
     fn a_source_still_on_the_bar_swaps_with_its_destination() {
         let mut bar = [CLAW, GROWL, FILLER, ATTACK];
@@ -350,9 +249,7 @@ mod tests {
         assert_eq!(a.displaced, None, "nothing left over to carry");
     }
 
-    /// A SPELL drag is the other shape, and the pickup's blank is what makes it so: a blanked
-    /// source is the one thing the duplicate scan skips (`0x4bca34`), so nothing matches and the
-    /// occupant is displaced onto the cursor instead.
+    /// The pickup's blank (the duplicate scan skips it, `0x4bca34`) leaves no copy to swap with.
     #[test]
     fn a_blanked_source_displaces_the_occupant_instead_of_swapping() {
         let mut bar = [CLAW, GROWL, FILLER, ATTACK];
@@ -364,8 +261,6 @@ mod tests {
         assert_eq!(a.displaced, Some(GROWL));
     }
 
-    /// A TOKEN occupant is never displaced onto the cursor: the core relocates it to the first
-    /// candidate (not a token, low 16 zero) and the cursor comes away empty.
     #[test]
     fn a_token_occupant_is_relocated_not_displaced() {
         let mut bar = [CLAW, ATTACK, FILLER, DEFENSIVE];
@@ -376,9 +271,6 @@ mod tests {
         assert_eq!(a.displaced, None, "nothing is left over to carry");
     }
 
-    /// …and with nowhere to put it, the whole assignment ABORTS: no write, no send. The reference
-    /// reports this identically to a successful relocation (`EAX = 0`), which is why the outcome
-    /// here is an `Option` and never a bool.
     #[test]
     fn a_token_occupant_with_no_candidate_aborts_entirely() {
         let mut bar = [CLAW, ATTACK, GROWL, DEFENSIVE];
@@ -387,15 +279,12 @@ mod tests {
         assert_eq!(bar, before, "nothing written");
     }
 
-    /// The two silent refusals: dropping a word onto the slot it already occupies (compared as the
-    /// FULL dword, autocast bits and all), and a passive spell source.
     #[test]
     fn the_self_drop_and_the_passive_source_are_no_ops() {
         let mut bar = [CLAW, GROWL, FILLER, ATTACK];
         assert!(assign(&mut bar, 0, CLAW, false).is_none());
         assert!(assign(&mut bar, 1, CLAW, true).is_none(), "passive source");
-        // The autocast bit is part of the compare — the same spell with its ring flipped is a
-        // different word and DOES write.
+        // The autocast bit is part of the compare: flipped, the same spell writes.
         assert!(assign(&mut bar, 0, CLAW & !0x4000_0000, false).is_some());
     }
 
@@ -407,8 +296,7 @@ mod tests {
         }
     }
 
-    /// A token slot as the feed really pushes it: `name` and `texture` are both the NAMES OF
-    /// GLOBALS, which is `GetPetActionInfo`'s own convention for types 6 and 7.
+    /// A token slot as fed: `name` and `texture` are global names, as from `GetPetActionInfo`.
     fn token_view(packed: u32, name: &str, texture: &str) -> PetActionView {
         PetActionView {
             is_token: true,
@@ -417,8 +305,7 @@ mod tests {
         }
     }
 
-    /// A hunter's default bar: three commands, four spell slots (two known, two filler), three
-    /// reactions — the arrangement `CharmInfo::InitPetActionBar` writes.
+    /// A hunter's default bar, as vmangos `CharmInfo::InitPetActionBar` lays it out.
     fn hunter_bar() -> Vec<PetActionView> {
         vec![
             token_view(ATTACK, "PET_ACTION_ATTACK", "PET_ATTACK_TEXTURE"),
@@ -440,8 +327,6 @@ mod tests {
         s
     }
 
-    /// Picking a SPELL slot up empties it — id zeroed, type and autocast bits kept — and tells the
-    /// server in the same breath. The payload is the word verbatim.
     #[test]
     fn picking_up_a_spell_blanks_its_slot_and_sends() {
         let mut s = bar_script();
@@ -458,12 +343,6 @@ mod tests {
         );
     }
 
-    /// A dragged TOKEN carries a real icon PATH, not the name of the global that holds one.
-    ///
-    /// `GetPetActionInfo` hands a token slot `("PET_ACTION_ATTACK", …, "PET_ATTACK_TEXTURE")` —
-    /// two global names — and the bar paints with `getglobal`. The cursor cannot: it needs a path
-    /// to decode, so an unresolved name means dragging Attack, Follow or Stay sticks *nothing* to
-    /// the pointer, which is what the director saw. A spell slot's path is left exactly as it is.
     #[test]
     fn a_dragged_token_carries_a_resolved_icon_path() {
         let mut s = UiScript::new().unwrap();
@@ -481,8 +360,7 @@ mod tests {
             "the global was resolved, not carried as a name"
         );
 
-        // An unset global resolves to nothing rather than to its own name — better a missing icon
-        // than a path that cannot exist.
+        // An unset global resolves to no icon, not to its own name.
         s.run("ClearCursor() PET_ATTACK_TEXTURE = nil PickupPetAction(1)")
             .unwrap();
         let Some(CursorPayload::PetAction(p)) = s.cursor_payload() else {
@@ -491,8 +369,6 @@ mod tests {
         assert_eq!(p.texture, None);
     }
 
-    /// A TOKEN slot keeps its contents while its word rides the cursor (`0x4be268 cmp cl,1` — the
-    /// blank is type-1-only), so a command ends up COPIED onto its destination rather than moved.
     #[test]
     fn picking_up_a_token_leaves_the_slot_alone() {
         let mut s = bar_script();
@@ -503,9 +379,6 @@ mod tests {
         );
     }
 
-    /// The whole gesture, end to end: pick a spell up and drop it two slots along. The pickup's
-    /// blank and the drop's write are two separate sends, and the displaced spell comes back on
-    /// the cursor.
     #[test]
     fn a_drag_between_two_spell_slots_sends_twice_and_carries_the_occupant() {
         let mut s = bar_script();
@@ -522,9 +395,8 @@ mod tests {
         );
     }
 
-    /// Dropping onto a COMMAND relocates that command to a filler slot instead of handing it back
-    /// — the cursor comes away empty, and ONE send carries both pairs (the server tells the two
-    /// forms apart by body size, so they must not be split).
+    /// The relocation and the write share one send: the server counts the pairs by body size
+    /// (vmangos `Server/Packets/Pet.cpp:56`).
     #[test]
     fn dropping_onto_a_token_relocates_it_in_one_send() {
         let mut s = bar_script();
@@ -540,13 +412,8 @@ mod tests {
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
     }
 
-    /// A refused drop **eats** the payload — `ClearCursor` ran before the decision and `EAX = 0`
-    /// never re-fills. 1010 shipped the inverse as a named divergence; 1016 retired it.
-    ///
-    /// The reachable refusal is the passive-spell source: the pickup has no passive gate, so a
-    /// passive slot picks up fine and is then refused everywhere it is dropped. Losing it is not
-    /// the data loss it looks like — the pickup's blank already went to the server, which is
-    /// exactly how a pet spell is taken off the bar.
+    /// The reachable refusal is a passive spell, which the pickup does not gate; its blank
+    /// already went to the server, which is how a pet spell is taken off the bar.
     #[test]
     fn a_refused_drop_eats_the_payload() {
         let mut s = UiScript::new().unwrap();
@@ -569,8 +436,6 @@ mod tests {
         );
     }
 
-    /// The clamp. The reference's callers admit Lua argument 11 and its assign core never bounds
-    /// again, so a real client writes one dword past the array; we refuse instead.
     #[test]
     fn slot_eleven_is_refused_rather_than_written_past_the_array() {
         let mut s = bar_script();
@@ -580,8 +445,7 @@ mod tests {
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
     }
 
-    /// `UNIT_FLAG_POSSESSED` blocks BOTH ends, because the reference's gate sits above the cursor
-    /// fork: you cannot pick a possessed unit's slot up, and you cannot drop onto its bar either.
+    /// The third flag, `pickup_allowed`, is false under `UNIT_FLAG_POSSESSED`.
     #[test]
     fn a_possessed_bar_takes_no_drag_at_all() {
         let mut s = UiScript::new().unwrap();
@@ -590,9 +454,6 @@ mod tests {
         assert!(s.take_pet_set_actions().is_empty());
     }
 
-    /// The two payload spaces do not overlap in either direction, and the two grids follow them:
-    /// a held spell lights the ACTION bar's grid and cannot land on a pet slot; a held pet action
-    /// lights the PET bar's and cannot land on an action slot.
     #[test]
     fn the_pet_payload_and_the_action_bar_refuse_each_other() {
         let mut s = bar_script();
diff --git a/crates/benilla-ui/src/script/cvars.rs b/crates/benilla-ui/src/script/cvars.rs
index bc030772..5a976354 100644
--- a/crates/benilla-ui/src/script/cvars.rs
+++ b/crates/benilla-ui/src/script/cvars.rs
@@ -1,55 +1,34 @@
-//! The **CVar table** — the client's named-console-variable store, engine side (decision 0954).
+//! The CVar table: the reference's store of case-insensitively named string settings with
+//! registered defaults, behind `GetCVar`/`SetCVar`/`GetCVarDefault`/`RegisterCVar`.
 //!
-//! In the reference every player setting is a CVar: a case-insensitively named string value with
-//! a registered default, read and written from Lua through `GetCVar`/`SetCVar`/`GetCVarDefault`
-//! (the 1.12 options panels are thin UI over this table). benilla keeps the same shape at the
-//! same seam: the **host registers** the vars it implements
-//! ([`super::UiScript::register_cvars`] — most backed by an engine knob, a few consumed by Lua
-//! alone), Lua reads/writes them synchronously, and each Lua write lands on the **change queue** the host
-//! drains per frame ([`super::UiScript::take_cvar_changes`]) to sync its resources and mark the
-//! config file dirty. Host-side writes ([`super::UiScript::set_cvar_host`] — the loaded config,
-//! an env override) do NOT ride the queue: the host already knows, and an echo would re-dirty
-//! the file it just loaded.
-//!
-//! Values are **strings**, like the client's (`GetCVar` returns a string; consumers parse and
-//! clamp at their own edge). An unknown name warns once and no-ops — a benilla CVar is either
-//! host-registered or addon-declared through `RegisterCVar` (decision 1195), so an unknown key
-//! is a typo or an unshipped feature, never a storage slot.
-//!
-//! **The table dies with the VM, so persistence bridges it** (decision 1291): in the reference
-//! this store is engine memory and survives every `ReloadUI`; ours is per-VM state, replaced at
-//! every login and reload (1290/1291). The host hands each fresh VM the config file's values
-//! ([`super::UiScript::set_cvar_saved_base`]) before anything registers, and registration —
-//! either kind — starts a key at its saved value. The host folds the dying VM's table back into
-//! its persist state on the session edge, so the two halves meet.
+//! The host registers the vars it backs and drains Lua's writes from a change queue; its own
+//! writes do not queue. The table dies with the VM, where the reference's outlives every
+//! `ReloadUI`, so the host seeds each new VM with the saved values before anything registers.
+//! An unknown name warns once and is ignored (`GetCVar` answers nil), where the reference's
+//! `GetCVar`, `SetCVar` and `GetCVarDefault` raise `Couldn't find CVar named '%s'` (`0x842310`).
 
 use mlua::{Lua, Value};
 
 use super::{Model, ScriptValue};
 
-/// One registered CVar: the host's spelling (for change events and the config file), the live
-/// value, and the registered default (`GetCVarDefault`, and the saver's "only write what moved").
+/// One registered CVar.
 #[derive(Clone, Debug)]
 pub(crate) struct CvarSlot {
-    /// The registered spelling (`MasterVolume`), reported on change events and in snapshots;
-    /// the table key is the lowercase form (the client's lookups are case-insensitive).
+    /// The registered spelling, reported on change events and in snapshots; the table key is
+    /// its lowercase form.
     pub name: String,
     pub value: String,
     pub default: String,
-    /// The reference's flag bit1 (`rec+0x1c & 0x2`, decision 2303): a write lands in
-    /// [`Self::pending`] instead of [`Self::value`], so `GetCVar` keeps answering the applied
-    /// value until the host commits the latch (`CVar::Update 0x63e060` — for the `gx*` rows,
-    /// inside `RestartGx`). Seeded by the host ([`super::UiScript::seed_cvars`]); a row the VM
-    /// registers on its own is never latched, exactly like the console `set` command's create
-    /// path in the reference.
+    /// The reference's flag bit1 (`rec+0x1c & 0x2`): a write goes to [`Self::pending`] and
+    /// `GetCVar` answers the applied value until the host commits it (`CVar::Update 0x63e060`).
+    /// Host-seeded only; a VM-registered row is never latched, like a console-created one.
     pub latched: bool,
-    /// The staged value of a latched row — what the host will commit at the boundary, and what
-    /// it is told about through the change queue the moment it is written.
+    /// A latched row's staged value, reported to the host through the change queue when written.
     pub pending: Option<String>,
 }
 
-/// One row of the host's registry, as the VM's mirror is seeded from it (decision 2303): the
-/// registered spelling, the **applied** value, the registered default, and the latch flag.
+/// One row of the host's registry as the VM's mirror is seeded from it; `value` is the applied
+/// value.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct SeededCvar {
     pub name: String,
@@ -58,16 +37,9 @@ pub struct SeededCvar {
     pub latched: bool,
 }
 
-/// One device-supported multisample format, as the Video options dropdown shows it.
-///
-/// The reference's distilled triple (`[0xb4b444]`, count `[0xb4b440]`, built by `0x48c3e0`), and
-/// the shape `MULTISAMPLING_FORMAT_STRING` formats: `"%d-bit color %d-bit depth %dx multisample"`.
-///
-/// `samples == 1` is the encoding of **no multisampling**, not "one sample of it" — the convention
-/// both of the reference's enumerators normalise to (`0x58b8b1`'s jump table maps
-/// `D3DMULTISAMPLE_NONE → 1`; the GL path at `0x58d5fa`/`0x58d5fe`/`0x58d605` turns a failed
-/// `WGL_SAMPLES_ARB` query or a value of 0 into 1), and the same convention the device paths test
-/// with `> 1`.
+/// One multisample format the device supports, the reference's triple (`[0xb4b444]`, count
+/// `[0xb4b440]`, built by `0x48c3e0`). `samples == 1` means no multisampling, as both reference
+/// enumerators normalise it (D3D `0x58b8b1`, GL `0x58d5fa`) and the device paths test `> 1`.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct MultisampleFormat {
     pub color_bits: u32,
@@ -75,18 +47,10 @@ pub struct MultisampleFormat {
     pub samples: u32,
 }
 
-/// One screen resolution the Video options dropdown offers, in **physical pixels**.
-///
-/// The reference enumerates the graphics device's own display modes; benilla has no exclusive
-/// mode-set to make (`benilla_app::video`'s module doc: Wayland has no client-side mode-setting,
-/// X11's is XRandR on the *desktop*, macOS has none, and WoW itself deleted exclusive fullscreen in
-/// 8.0.1), so the list is the sizes this client can actually present a window at. Either way it is
-/// a fact about the display that the VM cannot ask for itself, so the host pushes it.
-///
-/// **The `"WxH"` spelling is the contract, not a convenience.** `OptionsFrame.lua:281-284` finds
-/// the `x`, `strsub`s both sides and evaluates `width/height > 4/3` for the WIDESCREEN tag, and
-/// `CT_Viewport.lua:107` re-reads it with `string.find(currRes, "(%d+)x(%d+)")`. Two independent
-/// consumers, both of which fail silently on a space, a suffix, or an `X`.
+/// One screen resolution the Video options dropdown offers, in physical pixels. Deviation: the
+/// list is the window sizes this client can present, not the device's display modes, because
+/// benilla makes no exclusive mode-set. `"WxH"` is a contract: `OptionsFrame.lua:281-284` splits
+/// on the `x` and `CT_Viewport.lua:107` matches `"(%d+)x(%d+)"`, both failing silently.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ScreenResolution {
     pub width: u32,
@@ -94,9 +58,9 @@ pub struct ScreenResolution {
 }
 
 impl ScreenResolution {
-    /// The reference's ordering key, made total: **pixel area first** (`0x58be40`'s whole body is
-    /// `a.h*a.w - b.h*b.w`), then width, then height. The tie-break is ours — see
-    /// [`super::UiScript::set_screen_resolutions`].
+    /// Pixel area first, the reference's whole comparator (`0x58be40`), then width, then height.
+    /// Deviation: the tie-break is ours, because area alone with the reference's adjacent-only
+    /// dedupe can leave a duplicate `"WxH"` when two modes share an area (1280x960, 1600x768).
     pub(crate) fn sort_key(&self) -> (u64, u32, u32) {
         (
             u64::from(self.width) * u64::from(self.height),
@@ -112,52 +76,29 @@ impl std::fmt::Display for ScreenResolution {
     }
 }
 
-/// What `GetVideoCaps` answers with — the seven values `OptionsFrame_Load` destructures at
-/// `OptionsFrame.lua:59`, in that order.
-///
-/// ```lua
-/// local hasAnisotropic, hasPixelShaders, hasVertexShaders, hasTrilinear,
-///       hasTripleBuffering, maxAnisotropy, hasHardwareCursor = GetVideoCaps();
-/// ```
-///
-/// In the reference these are the D3D/GL device's own answers, cached at start-up. Here they are
-/// what wgpu and this client's own presentation path really do — pushed by the host, which is the
-/// only side that holds a `RenderAdapter`.
+/// What `GetVideoCaps` answers, in `OptionsFrame.lua:59`'s order: anisotropic, pixel shaders,
+/// vertex shaders, trilinear, triple buffering, max anisotropy, hardware cursor. The host pushes
+/// what wgpu and this client's presentation path really offer.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
 pub struct VideoCaps {
     pub anisotropic: bool,
     pub pixel_shaders: bool,
     pub vertex_shaders: bool,
     pub trilinear: bool,
-    /// **A BACKEND constant, not a device capability** — `caps+0x20` is written by the two device
-    /// constructors only (1 under Direct3D, 0 under OpenGL) and read by `GetVideoCaps` alone, so
-    /// `hasTripleBuffering == 1` means "the backend is Direct3D". Its name is the one INFERRED
-    /// label in the seven (wow-re `ui/scratch/video-options-verbs.md` §2.2).
-    ///
-    /// `false` here, and it is pushed as the **number 0**, never nil: benilla is not Direct3D and
-    /// exposes no buffering knob, so check button 13 is hidden and button 6 re-seated
-    /// (`OptionsFrame.lua:168-175`) — while the file's two `not hasTripleBuffering` clauses stay
-    /// dead, which is what the reference does in both backends.
+    /// A backend constant, not a device capability: 1 under Direct3D, 0 under OpenGL
+    /// (`caps+0x20`, read only by `GetVideoCaps 0x48db40`). False here, pushed as the number 0.
     pub triple_buffering: bool,
-    /// The raw maximum sample count, matched against `ANISOTROPIC_VALUES = {"1","2","4","8","16"}`
-    /// with `tonumber` (`OptionsFrame.lua:124`) — so it must be one of those numbers to move the
-    /// slider's ceiling, and anything else leaves `value.maxValue` where it was. Pushed raw, or
-    /// **nil iff 0**; the reference is effectively never nil here (its base ctor seeds the field
-    /// to 1), which is why its consumers gate on slot 1 or on `< 2` rather than on nil.
+    /// The raw maximum: `OptionsFrame.lua:122-127` makes a value in `ANISOTROPIC_VALUES` the
+    /// slider's ceiling as its index, and any other number the ceiling as is. Pushed as nil when 0.
     pub max_anisotropy: u32,
     pub hardware_cursor: bool,
 }
 
 impl super::UiScript {
-    /// Hand registration the config file's persisted values (decision 1291): name → value, keys
-    /// lowercased here. Set **before** any `register_cvars` / addon `RegisterCVar` runs in this
-    /// VM; a name registered while present here starts at the saved value instead of its default.
-    ///
-    /// This is the bridge that makes the per-VM table behave like the reference's engine-side
-    /// one (where the store outlives every `ReloadUI`): a CVar with no host knob
-    /// (`statusBarText`) and a CVar only an addon declares would otherwise revert to default on
-    /// every VM replacement — and the saver, seeing value == default, would then *strip the
-    /// player's setting from the file*.
+    /// Hand registration the config file's saved values (keys lowercased), before any
+    /// `register_cvars` or `RegisterCVar` runs in this VM: a name registered while present here
+    /// starts at its saved value. Without it a knobless or addon-declared CVar would revert to its
+    /// default in every new VM, and the saver would then drop the player's setting from the file.
     pub fn set_cvar_saved_base(&mut self, entries: impl IntoIterator<Item = (String, String)>) {
         self.model_mut().cvars_saved_base = entries
             .into_iter()
@@ -165,16 +106,10 @@ impl super::UiScript {
             .collect();
     }
 
-    /// Register the host-backed CVars (name, default) — boot-time, idempotent. A re-register of
-    /// a live table refreshes defaults but never clobbers a value someone already set. A fresh
-    /// registration starts at the saved-base value when the config file carries one
-    /// ([`Self::set_cvar_saved_base`]), else at the default.
-    ///
-    /// Takes `&self` rather than `&mut self` because the table lives behind the VM's app-data
-    /// (interior mutability), and the interface loader has to be able to guarantee it from a
-    /// `&UiScript` — the stock `UIOptionsFrame.xml` reads CVars in its own `OnLoad`, so a VM that
-    /// loads the client's interface without the client's CVar table is not the client
-    /// (decision 2115).
+    /// Register the host-backed CVars as `(name, default)`, idempotently: a re-register refreshes
+    /// the default and keeps a live value, and a new row starts at its saved value if the config
+    /// file has one. `&self` so the interface loader can register from a `&UiScript`: the stock
+    /// `UIOptionsFrame.xml` reads CVars in its own `OnLoad`.
     pub fn register_cvars<'a>(&self, vars: impl IntoIterator<Item = (&'a str, &'a str)>) {
         let mut model = self.model_mut();
         for (name, default) in vars {
@@ -202,15 +137,9 @@ impl super::UiScript {
         }
     }
 
-    /// Seed the mirror from the host's registry (decision 2303): every row's spelling, applied
-    /// value, default and latch flag, creating or overwriting the slot. This is what a fresh VM
-    /// gets at claim time and at the world-entry edge — the host's table is the store that
-    /// outlives the VM, so the mirror starts wherever it stands, and a re-seed of a live table
-    /// is the host re-asserting its truth (a staged value is dropped with it: the host holds
-    /// the pending copy and pushes it back through the outbox if it still stands).
-    ///
-    /// `&self` for [`Self::register_cvars`]'s reason — the interface loader seeds from a
-    /// `&UiScript` before the stock files read their first CVar (decision 2115).
+    /// Seed the mirror from the host's registry, creating or overwriting each row. The host's
+    /// table outlives the VM, so a re-seed re-asserts it and drops any staged value (the host
+    /// holds the pending copy). `&self` for [`Self::register_cvars`]'s reason.
     pub fn seed_cvars(&self, rows: impl IntoIterator<Item = SeededCvar>) {
         let mut model = self.model_mut();
         for row in rows {
@@ -228,10 +157,9 @@ impl super::UiScript {
         }
     }
 
-    /// Host-side write (a loaded value, a committed latch, the host registry's outbox): sets
-    /// the value WITHOUT queueing a change event — the host is the caller, an echo would
-    /// re-dirty the file it just read — and clears a staged value, because a host write IS the
-    /// commit. Unknown names warn once, same posture as the Lua side.
+    /// Host-side write (a loaded value, a committed latch): sets the value and clears any staged
+    /// one without queueing a change, since an echo would re-dirty the file the host just read.
+    /// An unknown name warns once.
     pub fn set_cvar_host(&mut self, name: &str, value: &str) {
         let mut model = self.model_mut();
         let key = name.to_ascii_lowercase();
@@ -252,8 +180,8 @@ impl super::UiScript {
             .map(|s| s.value.clone())
     }
 
-    /// Snapshot the whole table as `(name, value, default)` — the saver writes the entries whose
-    /// value moved off the default, and nothing else (the config file stays a diff, not a dump).
+    /// Snapshot the table as `(name, value, default)`; the saver writes only rows off their
+    /// default, so the config file stays a diff.
     pub fn cvars_snapshot(&self) -> Vec<(String, String, String)> {
         self.model_mut()
             .cvars
@@ -262,59 +190,35 @@ impl super::UiScript {
             .collect()
     }
 
-    /// Drain the `(name, new_value)` changes Lua `SetCVar` queued since the last call — the
-    /// host's cue to sync its resources and mark the config dirty. Names are the registered
-    /// spelling regardless of the caller's casing.
+    /// Drain the `(name, new_value)` changes queued since the last call, under the registered
+    /// spelling: the host's cue to sync its resources and mark the config dirty.
     pub fn take_cvar_changes(&mut self) -> Vec<(String, String)> {
         std::mem::take(&mut self.model_mut().cvar_changes)
     }
 
-    /// Drain the `(name, default)` rows an addon's `RegisterCVar` created since the last call
-    /// (decision 2303) — the host's cue to give each one a row in its own registry, which is the
-    /// store that survives this VM. In the reference an addon's registration lands in the same
-    /// engine-side table as the client's own; this is how ours does.
+    /// Drain the `(name, default)` rows an addon's `RegisterCVar` created since the last call; the
+    /// host's registry keeps them beside its own, as the reference's one table does.
     pub fn take_cvar_registrations(&mut self) -> Vec<(String, String)> {
         std::mem::take(&mut self.model_mut().cvar_registrations)
     }
 
-    /// A native surface's write — [`set_from_engine`]'s public face: sets the value AND queues
-    /// the change like a Lua `SetCVar`, so the host's sync dirties the config file. The glue
-    /// AddOns screen's *Load out of date AddOns* checkbox is the caller (decision 1293): a
-    /// native widget editing a CVar is the minimap-zoom pattern, reached from outside the crate.
+    /// A native widget's write (the glue AddOns screen's "Load out of date AddOns" checkbox): sets
+    /// the value and queues the change like a Lua `SetCVar`, so the config file is dirtied.
     pub fn set_cvar_engine(&mut self, name: &str, value: &str) {
         set_from_engine(&mut self.model_mut(), name, value.to_string());
     }
 
-    /// Publish the multisample formats this run's device actually accepts — what the Video
-    /// options dropdown offers, in the order it offers them.
-    ///
-    /// The host's half of the reference's `0x48c3e0`: there, a D3D `CheckDeviceMultiSampleType`
-    /// sweep over the nine-entry candidate table `0x85a83c` or a GL `wglGetPixelFormatAttribivARB`
-    /// sweep over every pixel format; here, `benilla_world::view::supported_sample_counts` asking
-    /// wgpu the same question. Pushed rather than pulled because the VM lives in `benilla-ui`,
-    /// which has no render adapter and should not grow one.
+    /// Publish the multisample formats this run's device accepts, in dropdown order. The
+    /// reference's `0x48c3e0` sweeps its candidate table `0x85a83c` (D3D) or every pixel format
+    /// (GL); here the host asks wgpu.
     pub fn set_multisample_formats(&mut self, formats: Vec<MultisampleFormat>) {
         self.model_mut().multisample_formats = formats;
     }
 
-    /// Publish the screen resolutions the Video options dropdown offers, and which one the client
-    /// is currently at.
-    ///
-    /// **`current` is a promise, not a hint.** `CT_Viewport.lua:201` reads its own screen size as
-    /// `arg[GetCurrentResolution()]` over `GetScreenResolutions()`'s varargs and silently falls
-    /// back to 4:3 on a miss, so a current size that is not in the list is a wrong answer that
-    /// succeeds. The host therefore hands the live size here and this pushes it INTO the list if
-    /// the display's own mode table does not carry it — a windowed client at 1600×900 on a 4K
-    /// panel is exactly that case, and it is the common one.
-    ///
-    /// Both halves land together because they are one fact: a list without its index cannot be
-    /// read, and an index into a list that moved is worse than none.
-    ///
-    /// **Ordered by pixel AREA**, which is the reference's own key (`0x58be40`: `a.w*a.h - b.w*b.h`,
-    /// with no tie-break at all). Ours breaks ties on width then height, deliberately: the
-    /// reference's comparator plus its adjacent-only dedupe can leak a duplicate `"WxH"` when two
-    /// distinct modes share an area — 1280×960 and 1600×768 are both 1 228 800 — and reproducing an
-    /// unstable sort is aping a quirk, not implementing the mechanism.
+    /// Publish the dropdown's resolutions and the client's current one, sorted by
+    /// [`ScreenResolution::sort_key`] and deduplicated. `current` is inserted when the list lacks
+    /// it (a 1600x900 window on a 4K panel): `CT_Viewport.lua:201` reads
+    /// `arg[GetCurrentResolution()]` and silently falls back to 4:3 on a miss.
     pub fn set_screen_resolutions(
         &mut self,
         mut offered: Vec<ScreenResolution>,
@@ -334,41 +238,28 @@ impl super::UiScript {
         model.current_resolution = current;
     }
 
-    /// Publish what this run's device and presentation path really offer, behind `GetVideoCaps`.
+    /// Publish what this run's device and presentation path offer, behind `GetVideoCaps`.
     pub fn set_video_caps(&mut self, caps: VideoCaps) {
         self.model_mut().video_caps = caps;
     }
 
-    /// Drain the `RestartGx()` calls queued since the last call — each is one "apply the staged
-    /// video settings now", and the host answers by re-asserting them against the window.
+    /// Drain the `RestartGx()` calls queued since the last call; the host answers each by
+    /// re-asserting the staged video settings against the window.
     pub fn take_restart_gx_asks(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().restart_gx_asks)
     }
 }
 
-/// An **engine-side** write: a value the engine owns moved, and the CVar table mirrors it. The
-/// minimap's zoom is the case that needs it — the client's `set_zoom` (`0x6da8e0`) writes the live
-/// index *and* `CVar::Set`s `minimapZoom`/`minimapInsideZoom` in the same breath, which is exactly
-/// why the level survives a restart. So this queues the change like a Lua `SetCVar` would (the host
-/// must hear it and dirty the config file), unlike [`super::UiScript::set_cvar_host`], whose whole
-/// point is *not* to echo the value it just loaded.
-///
-/// A name the host never registered is a **silent** no-op here, not a warning: engine writes are
-/// code, not UI content, so a miss means this build's host doesn't back the var (a bare test VM) —
-/// and the registered set is welded to the code truths by `crate::cvars`'s own test.
+/// An engine-side write, for a value the engine owns: queued like a Lua `SetCVar` so the config
+/// file is dirtied, as the reference's minimap `set_zoom` (`0x6da8e0`) also `CVar::Set`s
+/// `minimapZoom`/`minimapInsideZoom`. An unregistered name is a silent no-op (a bare VM).
 pub(super) fn set_from_engine(model: &mut Model, name: &str, value: String) {
     store(model, &name.to_ascii_lowercase(), value);
 }
 
-/// **The one store every write goes through** — Lua's `SetCVar`, `ConsoleExec`, and the engine
-/// writes above. Returns the registered spelling when the write moved something (and queued it
-/// for the host), `None` for an unknown key or a write that changed nothing.
-///
-/// A **latched** slot (decision 2303) takes the write as its staged value and leaves `value`
-/// alone, which is the reference's `Set 0x63df50`: `latchedValue` gets the string, `InternalSet`
-/// does not run, and `GetCVar` keeps answering what is applied. Writing a latched slot back to
-/// its applied value clears the stage instead of staging a no-op. Either way the host hears it
-/// through the change queue — it holds the pending copy and commits it at the boundary.
+/// The one store every write goes through; returns the registered spelling when the value moved
+/// and the change was queued. A latched slot stages the write, as the reference's `Set 0x63df50`
+/// stores `latchedValue` and skips `InternalSet`; writing back the applied value unstages it.
 fn store(model: &mut Model, key: &str, value: String) -> Option<String> {
     let slot = model.cvars.get_mut(key)?;
     if slot.latched {
@@ -391,10 +282,8 @@ fn store(model: &mut Model, key: &str, value: String) -> Option<String> {
     Some(registered)
 }
 
-/// Push the warn-once for an unknown CVar name into the model's warning stream.
-/// The `SetCVar` write, shared with `ConsoleExec` (which is `/console name value`): the slot
-/// matched case-insensitively, the change queued for the host only when the value moved, and
-/// `CVAR_UPDATE` fired only when a token was passed. `false` = no such CVar (warned once).
+/// The `SetCVar` write, shared with `ConsoleExec`: the change is queued only when the value
+/// moved, and `CVAR_UPDATE` fires only when a token was passed. `false` for an unknown name.
 pub(super) fn write_cvar(
     model: &mut Model,
     name: &str,
@@ -426,8 +315,10 @@ fn warn_unknown(model: &mut Model, name: &str) {
     }
 }
 
-/// Coerce the Lua argument to the string the table stores: the client stringifies numbers and
-/// booleans the same way (`SetCVar("MusicVolume", 0.4)` is the common call shape).
+/// Coerce a Lua argument to the stored string; the client takes a number too
+/// (`SetCVar("MusicVolume", 0.4)` is the common call). A boolean becomes "1" or "0", where the
+/// reference's `SetCVar` and `RegisterCVar` store "0" for anything but a string or a number
+/// (`0x488c98`, `0x488b6f`).
 fn value_to_string(v: &Value) -> Option<String> {
     match v {
         Value::String(s) => s.to_str().ok().map(|s| s.to_owned()),
@@ -438,44 +329,29 @@ fn value_to_string(v: &Value) -> Option<String> {
     }
 }
 
-/// Register the `GetCVar`/`SetCVar`/`GetCVarDefault`/`RegisterCVar` globals.
-/// The two nameplate toggles' registered CVar names — **defined here, in the crate that publishes
-/// the four verbs that write them**, so the binding and the name cannot drift apart. The app reads
-/// these consts rather than re-spelling the strings, and welds them to its registered table with
-/// its own test.
-///
-/// They are the LATER era's names: 1.12 registers no nameplate CVar at all (censused — see
-/// [`install_nameplate_verbs`]), so benilla's persistence takes the era spelling rather than
-/// inventing one, the same posture as `autoLootDefault`.
+/// The enemy-plate toggle's CVar, which the app reads rather than re-spelling. Deviation: 1.12
+/// registers no nameplate CVar; the toggles persist under the later clients' names rather than
+/// invented ones.
 pub const CVAR_NAMEPLATE_ENEMIES: &str = "nameplateShowEnemies";
 /// The friendly-plate half of [`CVAR_NAMEPLATE_ENEMIES`].
 pub const CVAR_NAMEPLATE_FRIENDS: &str = "nameplateShowFriends";
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // `RegisterCVar(name, value)` — declare a CVar the client does not ship (decision 1195).
-    //
-    // This is how an addon gets a persisted setting without a saved-variables file, and it is why
-    // `GetCVar` on an unknown name is a *warning* rather than an error: an addon that calls
-    // `RegisterCVar` at load and `GetCVar` after expects the second to answer. Registering an
-    // existing name is a **no-op, not an overwrite** — the reference will not let an addon reset a
-    // client CVar's live value by re-declaring it, and a re-run of the addon's own load must not
-    // wipe the player's setting either.
+    // `RegisterCVar(name, value)` declares a CVar the client does not ship, which is how an addon
+    // persists a setting. Re-declaring a live name is a no-op: the reference never resets a live
+    // value on re-registration.
     lua.globals().set(
         "RegisterCVar",
         lua.create_function(|lua, (name, value): (String, Option<Value>)| {
             let value = value.as_ref().and_then(value_to_string).unwrap_or_default();
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let key = name.to_ascii_lowercase();
-            // The saved base outranks the declared default (decision 1291): an addon-declared
-            // CVar the player has set persists in the config file, and this lookup is how the
-            // saved value survives the VM being replaced — the declared value stays the DEFAULT,
-            // so the saver still knows what "moved off default" means for this key.
+            // A saved value outranks the declared one, which stays the default for the saver.
             let saved = model.cvars_saved_base.get(&key).cloned();
             if model.cvars.contains_key(&key) {
                 return Ok(());
             }
-            // The host learns the row through its own queue (decision 2303): an addon-declared
-            // CVar gets a row in the host's registry, which is the store that survives this VM.
+            // The host gives the row a place in its registry, which outlives this VM.
             model.cvar_registrations.push((name.clone(), value.clone()));
             model.cvars.insert(
                 key,
@@ -518,19 +394,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── The Video options Multisampling dropdown ──────────────────────────────────────────────
-    // Three bindings over one list, exactly as `OptionsFrame.lua` consumes them: `_OnLoad` seeds
-    // the selection with `GetCurrentMultisampleFormat()`, `_Initialize` walks
-    // `GetMultisampleFormats()` three varargs at a time building the menu, and the Okay handler
-    // (l.240) calls `SetMultisampleFormat(UIDropDownMenu_GetSelectedID(...))`. Identities and
-    // behaviour from wow-re `system/console/scratch/gxmultisample-default.md` §7 — registration
-    // table `0x83de68`, records `0x83e2c0`/`0x83e2c8`/`0x83e2d0`.
+    // As `OptionsFrame.lua` drives it: `_OnLoad` seeds the selection from
+    // `GetCurrentMultisampleFormat()`, `_Initialize` walks `GetMultisampleFormats()` three values
+    // at a time, and the Okay handler (l.240) calls `SetMultisampleFormat`. Registration table
+    // `0x83de68`, records `0x83e2c0`/`0x83e2c8`/`0x83e2d0`.
     lua.globals().set(
         "GetMultisampleFormats",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // Flat, three per entry — `0x48c360` "pushes all three fields of every entry", and the
-            // Lua walks `for i=1, arg.n, 3`. A device with nothing to offer returns nothing, and
-            // the loop runs zero times: an empty dropdown, not a fabricated one.
+            // Flat, three per entry (`0x48c360`); no formats is no values and an empty menu.
             let mut out = mlua::MultiValue::new();
             for f in &model.multisample_formats {
                 out.push_back(Value::Number(f.color_bits as f64));
@@ -552,9 +424,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             ) else {
                 return Ok(1.0f64);
             };
-            // **1-based, and 1.0 on no match** — `0x48c580` "returns the 1-based index of the
-            // matching triple, or 1.0 on no match". Not 0 and not nil: `_OnLoad` feeds this
-            // straight to `UIDropDownMenu_SetSelectedID`, so a miss has to name a real row.
+            // 1-based, and 1.0 on no match (`0x48c580`): `_OnLoad` hands it straight to
+            // `UIDropDownMenu_SetSelectedID`, so a miss must still name a real row.
             let idx = model
                 .multisample_formats
                 .iter()
@@ -569,24 +440,23 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "SetMultisampleFormat",
         lua.create_function(|lua, id: Option<f64>| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // 1-based from `UIDropDownMenu_GetSelectedID`; anything off the end is ignored rather
-            // than clamped, because a clamp would silently apply a format the player did not pick.
+            // 1-based from `UIDropDownMenu_GetSelectedID`. Deviation: an id out of range is
+            // ignored, because the reference reads one entry past the last (`0x48c67c`) and a
+            // clamp would apply a format the player did not pick. A missing id is ignored too,
+            // where the reference takes the first entry (`0x48c657`).
             let Some(f) = id
                 .filter(|v| *v >= 1.0)
                 .and_then(|v| model.multisample_formats.get(v as usize - 1).copied())
             else {
                 return Ok(());
             };
-            // All three, from the chosen entry — `0x48c640` "writes those three CVars from the
-            // chosen entry". Through `set_from_engine` so each ride the host's change queue and
-            // the config file is marked dirty, the same route a Lua `SetCVar` takes.
+            // All three from the chosen entry, as `0x48c640` writes them, through the change queue.
             set_from_engine(&mut model, "gxColorBits", f.color_bits.to_string());
             set_from_engine(&mut model, "gxDepthBits", f.depth_bits.to_string());
             set_from_engine(&mut model, "gxMultisample", f.samples.to_string());
-            // The reference then sets `gxRestart` (`0x842978`, `0x63ce00`). We deliberately do not
-            // register that CVar: `gxMultisample` is latched here too (decision 1629 — the camera
-            // reads its sample count once, at spawn), so "applies at next launch" is already the
-            // behaviour and a second flag saying so would be a flag nothing reads.
+            // Deviation: the reference then runs the console command `gxRestart` (`0x842978`
+            // through `0x63ce00`); none is queued here, because `gxMultisample` applies at next
+            // launch anyway: the camera reads its sample count once, at spawn.
             Ok(())
         })?,
     )?;
@@ -604,19 +474,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             let Some(value) = value_to_string(v) else {
                 return Err(mlua::Error::runtime("Usage: SetCVar(\"name\", value)"));
             };
-            // The THIRD argument is the `CVAR_UPDATE` token, and it is the whole mechanism behind
-            // that event (decision 1140). 1.12's own callers are its two options panels —
-            // `SetCVar(value.cvar, value.value, index)` (UIOptionsFrame.lua l.335/343/345,
-            // OptionsFrame.lua l.192) — where `index` is the CheckButtons table's KEY, an
-            // uppercase display name like "STATUS_BAR_TEXT". The engine passes it straight through
-            // as arg1, which is why `UIOptionsFrame_OnEvent` can look the row up with
-            // `UIOptionsFrameCheckButtons[arg1]`, and why `TextStatusBar_OnEvent` compares against
-            // "STATUS_BAR_TEXT" rather than "statusBarText".
-            //
-            // A caller that omits it fires nothing — the event is opt-in per write, not a
-            // property of the variable. (Which means `ReputationFrame.xml`'s
-            // `arg1 == "statusBarText"` arm is dead code in shipped 1.12: nothing ever passes the
-            // CVar's own name as the token. Transcribed as found, not repaired.)
+            // The third argument is the `CVAR_UPDATE` token, passed through as arg1; without one
+            // nothing fires. The 1.12 options panels pass their CheckButtons key, such as
+            // "STATUS_BAR_TEXT" (`UIOptionsFrame.lua` l.335, `OptionsFrame.lua` l.192), which is
+            // how `UIOptionsFrame_OnEvent` finds its row.
             let token = it.next().and_then(value_to_string);
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             write_cvar(&mut model, &name, value, token);
@@ -628,90 +489,41 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_world_detail_verbs(lua)
 }
 
-/// **What `RestoreVideoDefaults` puts back** — the settings this client's video path backs that the
-/// reference's own verb writes, each named by the row it is.
+/// What `RestoreVideoDefaults` puts back: the CVars among the reference verb's writes that benilla
+/// registers, each at its registered default. The verb writes no `uiScale`, `useUiScale` or
+/// `anisotropic`.
 ///
-/// **The reference does NOT restore registered defaults, and this list is not a guess at which it
-/// does** (wow-re `ui/scratch/video-options-verbs.md` §4.3, the round that corrected benilla's
-/// first reading). `0x48dad0` → `0x639a20` maps the already-matched `VideoHardware.dbc` row through
-/// nine lookup tables into a hardware-recommended settings struct, copies the `CGxFormat` **preset**
-/// that row names for this adapter (`[0xc4e6ac]` → `0xc518e0 + 0x38·n`) into the working device
-/// record, writes that record into twelve `gx*` CVars, performs a full synchronous `RestartGx`, and
-/// then writes sixteen further graphics CVars from the recommendations. The registered strings
-/// (`"640x480"`, `"75"`, `"16"`…) are never consulted.
-///
-/// **benilla has no such pass, and that is why its registered defaults ARE its recommended
-/// configuration.** There is no `VideoHardware.dbc` matching here and no preset table: what a fresh
-/// install runs is each `REGISTERED` row's own value, clamped by the device where the device has a
-/// say (`MsaaFormats::clamp`, `tex_filter`'s aniso ceiling). So this restores each row to its
-/// registered default — the same *meaning*, reached the way this client reaches it — and that is a
-/// stated divergence rather than a transcription.
-///
-/// The membership, though, is the reference's: these are the names in its twelve-plus-sixteen that
-/// benilla registers. It does **not** touch `uiScale`, `useUiScale` or `anisotropic` — an earlier
-/// draft of this list did, reasoning from the video window's Lua tables instead of from the verb.
-///
-/// **`WorldDetail` is ours and rides with `frillDensity`**: 2163 welded the panel stop to the
-/// reference's own clutter CVar, so restoring one without the other would leave the pair describing
-/// two different detail levels.
-///
-/// `benilla_app::cvars` holds the matching test that every name here is registered — the weld that
-/// keeps a rename or a retirement from turning a row into a silent no-op.
+/// Deviation: the reference (`0x48dad0` into `0x639a20`) writes hardware-recommended values from
+/// its matched `VideoHardware.dbc` row and the `CGxFormat` preset it names (`[0xc4e6ac]`): twelve
+/// `gx*` CVars, a synchronous `RestartGx`, then sixteen more. benilla has no such matching, so its
+/// registered defaults are its recommended configuration.
 pub const VIDEO_DEFAULT_CVARS: &[&str] = &[
-    // of the twelve `gx*` the device record writes (`0x639c40`), the six benilla registers
+    // Of the twelve `gx*` the device record writes (`0x639c40`), the six benilla registers.
     "gxWindow",
     "gxResolution",
     "gxVSync",
     "gxColorBits",
     "gxDepthBits",
     "gxMultisample",
-    // of the sixteen further graphics CVars (`0x639a60`), the three benilla registers
+    // Of the sixteen further graphics CVars (`0x639a60`), the three benilla registers.
     "farclip",
     "frillDensity",
     "trilinear",
-    // ours, welded to `frillDensity` (2163)
+    // Ours, restored with `frillDensity` so the pair keeps describing one detail level.
     "WorldDetail",
 ];
 
-/// **The Video options window's own engine verbs** — the nine `OptionsFrame.xml` needs that
-/// nothing else in this client provides.
+/// The Video options window's engine verbs that nothing else here provides. Three run at load,
+/// as `UIDropDownMenu_Initialize` calls its initializer at once (`UIDropDownMenu.lua:48-50`):
+/// `GetScreenResolutions`, `GetCurrentResolution` and `GetRefreshRates`.
 ///
-/// The window is loaded off the player's chain and kept hidden (decision 2177, the shape 2115 and
-/// 2147 set for the Interface and Sound windows): nothing of ours shows it, and it exists so that
-/// an addon reaching for the reference's video-options names finds real frames and real functions
-/// instead of an alias onto a window of ours.
-///
-/// **Three of the nine run at LOAD** — `GetScreenResolutions`, `GetCurrentResolution` and
-/// `GetRefreshRates`, from the resolution and refresh dropdowns' `<OnLoad>`, because
-/// `UIDropDownMenu_Initialize` calls the initializer it is handed *immediately*
-/// (`UIDropDownMenu.lua:48-50`). The file cannot load at all without them, and the window being
-/// `hidden="true"` is precisely what keeps the other four out of that set: they hang off `OnShow`
-/// and the three buttons. The **tenth** name that load reaches, which benilla's own census of this
-/// window missed, is plain `GetCVar` (`OptionsFrame.lua:300`, `GetCVar("gxRefresh")`).
-///
-/// The three multisample verbs the same window needs are above; `GetWorldDetail`/`SetWorldDetail`
-/// are in [`install_world_detail_verbs`]. `GetGamma`/`SetGamma` are the last two: 2177 shipped
-/// seven and left that pair **loudly absent** under 1203, because a byte-faithful copy would have
-/// driven a hardware ramp this client never uploads. 2182 built the render feature behind them, so
-/// they have a real reader now and the window's engine verbs are nine of nine.
-///
-/// **What must NOT be defined, which is as load-bearing as what is.** `OptionsFrame_Load:110` does
-/// `getglobal("Get"..value.func)` over the nine slider rows and branches on the result; of the
-/// eighteen composed names, six resolve to real bindings in the reference
-/// (`Get/SetWorldDetail`, `Get/SetTerrainMip`, `Get/SetBaseMip`) and **ten must resolve to nil** —
-/// `Getuiscale`, `Getfarclip`, `Getanisotropic`, `GetspellEffectLevel`, `GetweatherDensity` and
-/// their five setters — so those rows fall through to `GetCVar`/`SetCVar`. Defining any of them
-/// changes this window's behaviour without erroring. The trap is `GetFarclip`/`SetFarclip`, which
-/// DO exist at `0x488f00`/`0x488f30` with a capital F while `value.func` is `"farclip"`: the stock
-/// client takes the CVar path only because `getglobal` is case-sensitive. Pinned by
-/// `benilla_app`'s `the_video_windows_ten_composed_names_stay_nil`.
+/// Ten names must stay nil so their slider rows fall back to `GetCVar`/`SetCVar`
+/// (`OptionsFrame_Load:110` tries `getglobal("Get"..value.func)`): `Getuiscale`, `Getfarclip`,
+/// `Getanisotropic`, `GetspellEffectLevel`, `GetweatherDensity` and their setters.
+/// `GetFarclip`/`SetFarclip` do exist (`0x488f00`/`0x488f30`); `getglobal` is case-sensitive.
 fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
     // ── GetScreenResolutions ─────────────────────────────────────────────────────────────────
-    // A vararg of `"WxH"` strings. The format is pinned by two independent consumers, neither of
-    // which raises on a wrong one: `OptionsFrame.lua:281-284` splits on the `x` and evaluates
-    // `width/height > 4/3` to decide the WIDESCREEN tag, and `CT_Viewport.lua:107` re-parses with
-    // `string.find(currRes, "(%d+)x(%d+)")` to size its viewport. A space, an `X`, or a trailing
-    // suffix silently gives one of them the wrong answer.
+    // A vararg of `"WxH"` strings, the spelling `ScreenResolution` pins.
     lua.globals().set(
         "GetScreenResolutions",
         lua.create_function(|lua, ()| {
@@ -724,25 +536,12 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── GetCurrentResolution ─────────────────────────────────────────────────────────────────
-    // The **1-based index** into that list — `0x48bfa2 inc eax` over the same array, which is the
-    // only reading `arg[GetCurrentResolution()]` (`CT_Viewport.lua:105`) can have.
+    // The 1-based index into that list (`0x48bfa2`), and 1.0 on any miss, never nil or 0
+    // (`0x48bf88`), so a 1 does not prove a match.
     //
-    // **`1.0` on a miss, never nil and never 0** (`0x48bf88 push 0x3ff00000` — the f64 `1.0`), and
-    // the reference takes that path on every failure: no CVar record, a NULL string, an empty
-    // list, or a value simply not in it. It is the family idiom — `GetCurrentMultisampleFormat`
-    // `0x48c580` answers `1.0` the same way, and `SetMultisampleFormat` above already does. A `1`
-    // is therefore not proof of a match, which is exactly the trap the reference walks into: its
-    // `gxResolution` registers at `"640x480"`, below its own list's 800×600 floor, so a fresh
-    // config reports index 1 while running 640×480.
-    //
-    // **Where ours reads from is a stated divergence.** The reference parses the `gxResolution`
-    // CVar (`0x48bf20`), which on a mode-setting client IS the live mode. benilla ships no
-    // exclusive mode-set: `gxResolution` is the WINDOWED size, and while the client is borderless
-    // fullscreen the two differ. The host therefore pushes the live window size, because "what
-    // resolution am I at" is what every consumer means — `CT_Viewport` scales its viewport by it —
-    // and reporting a windowed size while filling a 4K panel would be a wrong answer that
-    // succeeds. A pick made while fullscreen still lands in `gxResolution` and takes effect on the
-    // way out, which is the honest reading of a windowed-size setting.
+    // Deviation: the index is of the live window size, not of the `gxResolution` CVar the
+    // reference parses (`0x48bf20`), because without an exclusive mode-set `gxResolution` is the
+    // windowed size, not the live one in borderless fullscreen, which `CT_Viewport` scales by.
     lua.globals().set(
         "GetCurrentResolution",
         lua.create_function(|lua, ()| {
@@ -751,30 +550,16 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── SetScreenResolution ──────────────────────────────────────────────────────────────────
-    // 1-based, from `UIDropDownMenu_GetSelectedID(OptionsFrameResolutionDropDown)`
-    // (`OptionsFrame.lua:239`). Three things about the argument, all carved at `0x48bfd0`:
+    // 1-based (`OptionsFrame.lua:239`), and `0x48bfd0` never raises: a missing or non-numeric
+    // argument selects the first entry, a numeric string counts (`0x6f7c20`), and a number
+    // truncates toward zero (`0x40a2b0`).
     //
-    // * **The TOLERANT family, not the raising one.** `0x48bfe6 xor esi,esi` seats a default index
-    //   of 0 and there is no `0x6f4940` anywhere in the body, so a missing, nil or non-numeric
-    //   argument silently selects **the first entry** rather than erroring. A numeric string is
-    //   accepted (the `0x6f7c20` coercion).
-    // * **Truncated toward zero** — `0x40a2b0 __ftol` with RC=11, so `2.7` is entry 2.
-    // * **Out of range is where we deliberately diverge.** `0x48c008 dec eax` / `0x48c009 cmp` /
-    //   the failure block at `0x48c00d` converge index 0, negatives and anything past the count on
-    //   `list[count]` — one element past the last, read unguarded. It does not fault only because
-    //   the array keeps a spare slot. We clamp to the last entry instead: reproducing an
-    //   out-of-bounds read to apply an uninitialised resolution is not fidelity.
+    // Deviation: 0, a negative or an index past the count clamps to the nearer end, because the
+    // reference reads one element past the last there (`0x48c00d`), uninitialised memory.
     //
-    // **The same-value guard is real behaviour and is reproduced** (`0x48c081 je 0x48c0c1`): if the
-    // requested size equals the one `gxResolution` already holds, the reference returns having done
-    // nothing at all — no write, no restart — and so does this. `set_from_engine` would swallow the
-    // write anyway; the restart below is what makes the guard observable.
-    //
-    // **And it issues its own `gxRestart`** (`0x48c0b7 mov ecx,0x842978` → the console executor),
-    // which is why `OptionsFrame_Save` calling `RestartGx()` afterwards restarts a resolution
-    // change twice. Ours does the same, through the same counted request the host drains — benilla
-    // applies the size live, so the restart is a re-assertion rather than a device rebuild, but the
-    // CALL is the reference's and belongs here rather than only at the Okay button.
+    // A size equal to `gxResolution`'s does nothing, no write and no restart (`0x48c081`);
+    // otherwise it issues its own `gxRestart` (`0x48c0b7`), so `OptionsFrame_Save`'s later
+    // `RestartGx()` restarts a resolution change twice, here as in the reference.
     lua.globals().set(
         "SetScreenResolution",
         lua.create_function(|lua, id: Option<f64>| {
@@ -782,7 +567,8 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
             if model.screen_resolutions.is_empty() {
                 return Ok(());
             }
-            // nil / non-numeric → 0 → entry 1. Truncate, then clamp both ends.
+            // nil selects entry 1; a non-numeric argument has already raised in the conversion,
+            // where the reference takes entry 1. Truncate, then clamp both ends.
             let idx = id.map_or(0.0, f64::trunc);
             let last = model.screen_resolutions.len() - 1;
             let r = model.screen_resolutions[if idx < 1.0 {
@@ -804,51 +590,19 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── GetRefreshRates ─────────────────────────────────────────────────────────────────────
-    // **Zero return values, and that IS the reference's "nothing to offer" answer** —
-    // `0x48c136 xor eax,eax; ret`. It was written here as a single `0` first, from
-    // `OptionsFrame_GetRefreshRates`'s `if ( arg.n == 1 and arg[1] == 0 )` opening; the binary
-    // contains **no `push 0` path at all**. That FrameXML branch is reachable only when the OS
-    // reports `dmDisplayFrequency == 0` for every matching mode — Win32's encoding for "the
-    // hardware default" — which the adjacent dedupe collapses to one `0`. It does not special-case
-    // the empty answer: `for i = 1, 0` runs zero times and the dropdown is left **empty but
-    // enabled**, which is what the reference does on a device with nothing to say.
-    //
-    // benilla's answer is always the empty one, because a refresh rate is only selectable through
-    // an exclusive mode-set and this client ships none on any target (`benilla_app::video`'s
-    // module doc walks each). Pushing the monitor's rates would be a dropdown whose every pick did
-    // nothing — 2115 §2's wrong answer that succeeds — and pushing a lone `0` to grey the control
-    // would be inventing a value the binary never produces.
-    //
-    // **The optional index argument is tolerated and ignored**, which is the reference's own shape
-    // (`0x48c0ec xor esi,esi`): with no argument it asks for the rates of the FIRST — smallest —
-    // resolution in the list, never the selected one, and the stock caller passes nothing.
+    // No values is the reference's "nothing to offer" (`0x48c136`), an empty but enabled
+    // dropdown. Any argument is accepted; in the reference it picks the resolution, the first
+    // when absent (`0x48c0ec`). Deviation: always empty, because a refresh rate is only
+    // selectable through an exclusive mode-set and benilla has none.
     lua.globals().set(
         "GetRefreshRates",
         lua.create_function(|_, _: mlua::MultiValue| Ok(mlua::MultiValue::new()))?,
     )?;
     // ── GetVideoCaps ─────────────────────────────────────────────────────────────────────────
-    // Seven values in `OptionsFrame.lua:59`'s own order, and **THREE push shapes, not two**
-    // (`0x48db40`, each polarity read through to `lua_pushnil 0x6f37f0`):
-    //
-    // * slots 1,2,3,4,7 — **nil, or the number 1**. `caps+0xa8/0x98/0x94/0xa4/0xc4`. Two of them
-    //   test against `-1` rather than 0, because D3D maps ps_1_1 and vs_1_1 to the *value* 0 and a
-    //   `!= 0` test would report "no shaders" on hardware that has them.
-    // * slot 5 `hasTripleBuffering` — **`0x48dbcb fild dword [edi+0x20]`, straight-line, NO
-    //   branch**: always a number, never nil.
-    // * slot 6 `maxAnisotropy` — **nil iff 0**, else the raw value.
-    //
-    // No `lua_pushboolean` anywhere; the `1` is the f64 `1.0`.
-    //
-    // **Slot 5 is a backend constant, and getting its TYPE right is what reproduces a stock
-    // defect.** `caps+0x20` has two writers image-wide (the two device constructors: 1 under
-    // Direct3D, 0 under OpenGL) and one reader, this verb — so `== 1` means "the backend is
-    // Direct3D", independent of GPU, driver and the `gxTripleBuffer` CVar. `OptionsFrame_Load`
-    // tests `not hasTripleBuffering` twice and `hasTripleBuffering == 1` once; `0` is TRUTHY in
-    // Lua and slot 5 is never nil, so **the two `not` tests can never fire in either backend** and
-    // only the `== 1` one works. benilla is not Direct3D and exposes no buffering knob, so it
-    // answers the number **0**: check button 13 is hidden and button 6 re-seated
-    // (`OptionsFrame.lua:168-175`), and the two dead clauses stay dead, which is correct.
-    // Answering nil instead would *revive* them — a branch the reference cannot reach.
+    // Seven values in `OptionsFrame.lua:59`'s order, never a boolean (`0x48db40`): slots 1-4 and
+    // 7 are nil or the number 1, slot 5 is always a number, slot 6 is nil iff 0. Slot 5 is 0
+    // under OpenGL and 1 under Direct3D; 0 is truthy, so `OptionsFrame_Load`'s two
+    // `not hasTripleBuffering` tests never fire in the reference, and a nil would revive them.
     lua.globals().set(
         "GetVideoCaps",
         lua.create_function(|lua, ()| {
@@ -862,10 +616,9 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
             out.push_back(flag(caps.pixel_shaders));
             out.push_back(flag(caps.vertex_shaders));
             out.push_back(flag(caps.trilinear));
-            // Slot 5: unconditional number, per the straight-line `fild` above.
+            // Slot 5: always a number, a straight-line `fild` (`0x48dbcb`).
             out.push_back(Value::Number(if caps.triple_buffering { 1.0 } else { 0.0 }));
-            // Slot 6: nil iff 0. The reference is effectively never nil here — its base ctor seeds
-            // `caps+0xac = 1` — so a consumer gates on slot 1 or on `< 2`, never on nil.
+            // Slot 6: nil iff 0; the reference's is seeded to 1 (`caps+0xac`), so never nil there.
             out.push_back(if caps.max_anisotropy == 0 {
                 Value::Nil
             } else {
@@ -876,27 +629,12 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── RestartGx ────────────────────────────────────────────────────────────────────────────
-    // "Apply the staged video settings now." `0x48dab0` is three instructions — it hands the line
-    // `"gxRestart"` to the CONSOLE COMMAND EXECUTOR `0x63ce00`, which looks the action up and calls
-    // its handler `0x639f60` **synchronously**. That handler reads no CVar by name: the staging was
-    // done at `SetCVar` time by each gx CVar's own change callback, which writes the pending device
-    // format record and can veto the write outright; the handler validates that record, applies it
-    // with `DeviceSetFormat`, and then COMMITS the fourteen latched CVars so `GetCVar` catches up.
-    //
-    // **benilla has no such latch and no such device rebuild.** Its video settings apply as they
-    // are written — the departure `benilla_app::video`'s module doc already states for `gxVSync`
-    // ("wgpu reconfigures the surface on the next frame") and for the display mode ("ours takes
-    // effect on the click"). So the verb's postcondition is already true when it is called, which
-    // is not the same as the verb having nothing to do: the caller is asking for the settings to be
-    // in effect *now*, and the honest answer is to make the host re-assert them against the window
-    // rather than wait for its change detection to notice something it may already have seen.
-    //
-    // A counted request the host drains (`take_restart_gx_asks`), the shape `Screenshot()` uses and
-    // for the same reason: no payload, and two calls in a frame are two requests. **It is not a
-    // stub** — a stub would be an empty body pretending the settings had been applied.
-    // `gxMultisample` is the one setting no restart can deliver here, and none can in the reference
-    // either: 1629 latches the sample count at camera spawn, which is what `SetMultisampleFormat`
-    // above already documents as "applies at next launch".
+    // "Apply the staged video settings now": `0x48dab0` runs the console command `gxRestart`
+    // (`0x63ce00`), whose handler `0x639f60` applies the staged device format and commits the
+    // fourteen latched CVars. Here it queues a counted request, as `Screenshot()` does; the host
+    // commits its gx stages (`Cvars::commit_latched`) and re-asserts them against the window.
+    // The reference runs each gx change callback at `SetCVar`, where it can veto the write; the
+    // host runs it at the commit. No restart applies `gxMultisample`: the camera reads it once.
     lua.globals().set(
         "RestartGx",
         lua.create_function(|lua, ()| {
@@ -907,22 +645,9 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── RestoreVideoDefaults ─────────────────────────────────────────────────────────────────
-    // **The Defaults button's whole effect, and the FrameXML proves it.** `OptionsFrame_SetDefaults`
-    // sets every check button and slider from `GetCVarDefault` — and then the button's own
-    // `<OnClick>` calls `HideUIPanel(OptionsFrame)` (`OptionsFrame.xml:688-690`), throwing those
-    // widget values away without ever running `_Save`. So the widgets are cosmetic; this verb is
-    // what actually moves the settings, and it must, or Defaults would do nothing at all.
-    //
-    // What it restores, and why that is not the reference's own values, is
-    // [`VIDEO_DEFAULT_CVARS`]'s doc. Each row rides the ordinary change queue, so the host's knob
-    // sync applies it and the config file is marked dirty — the same route a Lua `SetCVar` takes.
-    // `set_from_engine`, not `write_cvar`, because this is the engine moving a value it owns rather
-    // than a script asking: no `CVAR_UPDATE` token, the minimap-zoom shape.
-    //
-    // **The restart is the reference's own, in the reference's own place** — `0x639a51` calls the
-    // `gxRestart` handler directly and synchronously, between the twelve gx writes and the sixteen
-    // quality ones, and it destroys and recreates the device *and the OS window*. Ours issues the
-    // same counted request; here it is a re-assertion rather than a rebuild, but the call belongs.
+    // The Defaults button's whole effect: `OptionsFrame_SetDefaults` only sets the widgets, which
+    // the button's `OnClick` then hides without `_Save` (`OptionsFrame.xml:688-690`). Ends with a
+    // restart, as the reference calls the `gxRestart` handler between its two passes (`0x639a51`).
     lua.globals().set(
         "RestoreVideoDefaults",
         lua.create_function(|lua, ()| {
@@ -933,8 +658,7 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
                     .get(&name.to_ascii_lowercase())
                     .map(|slot| slot.default.clone())
                 else {
-                    // A bare VM with no host behind it registers none of these; there is nothing to
-                    // restore and nothing to warn about, exactly as `set_from_engine` reasons.
+                    // Unregistered in a bare VM: nothing to restore, nothing to warn about.
                     continue;
                 };
                 set_from_engine(&mut model, name, default);
@@ -944,36 +668,22 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     // ── GetGamma / SetGamma ──────────────────────────────────────────────────────────────────
-    // **The display-brightness pair** (2182) — `GetGamma 0x4891c0` and `SetGamma 0x4891f0`, carved
-    // end to end in wow-re `ui/scratch/video-options-verbs.md` §3.
-    //
-    // The one thing about them that is not obvious from the name: **the unit is the SLIDER's
-    // offset, not the CVar's.** `0x4891d0` is `dc 2d`, ModRM reg field 5 = **FSUBR** (`mem − ST(0)`,
-    // not `FSUB`), over `[0x8015b8]` = the f64 `1.0`. So `GetGamma()` answers `1.0 − gamma` and
-    // `SetGamma(v)` writes `gamma := 1.0 − v` — the two compose to the identity, and with the
-    // registered `gamma = "1.0"` the getter answers **0.0**, the exact centre of the stock
-    // slider's `[-0.5, 0.5]`. Reading the pair as "gamma in, gamma out" would put a 1.0 through
-    // `SetGamma` and write `gamma = 0`, i.e. `pow(x, 0) = 1`, a fully white ramp.
-    //
-    // **No clamp exists anywhere in the reference** — not in the binding, not in `CVar::Set`, not
-    // in the change callback, not in the ramp builder — and the absence is earned rather than
-    // assumed: the positive control is `baseMip`'s own callback `0x689090`, which *does* reject
-    // out-of-`[0,1]` with `al = 0`. `SetGamma(5)` is accepted and writes `gamma = "-4.000000"`.
-    // benilla's clamp is at the consumer (`ui_gamma::GAMMA_RANGE`), which is this crate's standing
-    // posture and leaves the store's truth alone.
+    // `GetGamma 0x4891c0` and `SetGamma 0x4891f0` work in the slider's offset, not the CVar's
+    // unit: `0x4891d0` is FSUBR over the f64 1.0 at `[0x8015b8]`, so `GetGamma()` answers
+    // `1.0 - gamma` and `SetGamma(v)` writes `gamma = 1.0 - v`; the registered `"1.0"` reads as
+    // 0.0, the slider's centre. The reference clamps nowhere (`SetGamma(5)` writes
+    // `"-4.000000"`); the clamp is the consumer's (`ui_gamma::GAMMA_RANGE`).
     lua.globals().set(
         "GetGamma",
-        // No argument is read (the getter never calls `lua_gettop`), and one number comes back.
+        // Any argument is ignored (the getter never calls `lua_gettop`); one number comes back.
         lua.create_function(|lua, _: mlua::MultiValue| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let gamma = model
                 .cvars
                 .get(&CVAR_GAMMA.to_ascii_lowercase())
                 .and_then(|slot| slot.value.parse::<f64>().ok())
-                // A VM whose host registered nothing (a bare test kit) answers as if the
-                // registered default were in place, which is 0.0 — the slider's centre. The
-                // reference has no such arm: its `0x63de30` lookup CREATES the record on a miss,
-                // so `[eax+0x24]` is always readable.
+                // A bare VM with no `gamma` row answers as if the default stood; the reference
+                // always finds its record (`0x63de30`).
                 .unwrap_or(1.0);
             Ok(1.0 - gamma)
         })?,
@@ -981,9 +691,8 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set(
         "SetGamma",
         lua.create_function(|lua, value: Value| {
-            // `lua_isnumber` (`0x4891fe`): a number, or a string Lua can convert to one. Anything
-            // else raises through `0x6f4940`, which does not return — the trailing `xor eax,eax`
-            // at `0x489215` is dead code.
+            // `lua_isnumber` (`0x4891fe`): a number or a numeric string; anything else raises
+            // (`0x6f4940`).
             let v = match &value {
                 Value::Integer(i) => *i as f64,
                 Value::Number(n) => *n,
@@ -995,9 +704,8 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
                 }
                 _ => return Err(mlua::Error::runtime(USAGE_SET_GAMMA)),
             };
-            // `SStrPrintf(buf, 0x10, "%f", 1.0 - v)` — six decimals into a SIXTEEN-byte buffer, so
-            // a long value is truncated to 15 characters rather than rejected. Reproduced because
-            // the truncated string is what the CVar then holds and what `GetCVar("gamma")` answers.
+            // `SStrPrintf(buf, 0x10, "%f", 1.0 - v)`: a 16-byte buffer, so the stored string, and
+            // what `GetCVar("gamma")` answers, is cut at 15 characters.
             let mut written = format!("{:.6}", 1.0 - v);
             written.truncate(15);
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -1009,89 +717,38 @@ fn install_video_verbs(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The reference's own display-gamma CVar — `0x402d70`, name string `0x82e924`, registered `"1.0"`,
-/// flags 0. Defined in the crate that publishes the two verbs that read and write it, so the
-/// binding and the name cannot drift apart; the app welds it to its own table.
+/// The reference's display-gamma CVar: registered at `0x402d70` as `"1.0"`, flags 0, name
+/// string `0x82e924`.
 pub const CVAR_GAMMA: &str = "gamma";
 
 /// `0x8424cc`, verbatim.
 const USAGE_SET_GAMMA: &str = "Usage: SetGamma(value)";
 
-/// The `WorldDetail` slider's **stop**, benilla's spelling — the panel position `0`/`1`/`2`, held as
-/// a CVar because 1.12 has no such CVar and our own Graphics page needs somewhere to keep it (the
-/// `autoLootDefault` posture; the app's table carries the reasoning and the `Same` row).
-///
-/// Defined here, in the crate that publishes the two verbs that read and write it, so the binding
-/// and the name cannot drift apart — as for [`CVAR_NAMEPLATE_ENEMIES`]. The app welds both with its
-/// own test.
+/// The `WorldDetail` slider's stop, 0, 1 or 2. Deviation: 1.12 has no such CVar; it exists because
+/// our Graphics page needs somewhere to keep the stop, and takes the API's name.
 pub const CVAR_WORLD_DETAIL: &str = "WorldDetail";
 
-/// The reference's own Environment Detail CVar — cells visited per chunk by the detail-doodad
-/// scatter. [`WORLD_DETAIL_STOPS`] is what the slider writes into it.
+/// The reference's Environment Detail CVar: cells visited per chunk by the detail-doodad scatter.
 pub const CVAR_FRILL_DENSITY: &str = "frillDensity";
 
-/// **`SetWorldDetail`'s preset table, verbatim** — the three dwords at `0x804518`, `{0x10, 0x20,
-/// 0x30}`. Read out of `WoW.exe` rather than transcribed from a note.
+/// `SetWorldDetail`'s `frillDensity` per stop, the three dwords at `0x804518`.
 pub const WORLD_DETAIL_STOPS: [u32; 3] = [16, 32, 48];
 
-/// **The Environment Detail pair** — `SetWorldDetail 0x488dd0` and `GetWorldDetail 0x488d70`, the
-/// two engine bindings 1.12's own options panel drives that slider through (`OptionsFrame.lua`'s
-/// row 3 is `func = "WorldDetail"`, and `OptionsFrame_Save`/`_Load` prefer `getglobal("Set"..func)`
-/// / `getglobal("Get"..func)` over `SetCVar`/`GetCVar`). Decision 2163.
+/// The Environment Detail pair, `SetWorldDetail 0x488dd0` and `GetWorldDetail 0x488d70`, which
+/// `OptionsFrame.lua` row 3 (`func = "WorldDetail"`) drives in place of `SetCVar`/`GetCVar`. The
+/// setter truncates toward zero (`0x40a2b0`), raises outside 0..=2, and writes `frillDensity` from
+/// [`WORLD_DETAIL_STOPS`] and `smallCull` from `{0.07, 0.04, 0.01}` (`0x804524`).
 ///
-/// **The setter, carved end to end** (own decode, agreeing with wow-re
-/// `cvar/scratch/registered-defaults-census.md` §8):
-///
-/// ```text
-/// 488ddf  call 0x6f34d0             ; lua_isnumber(L,1)? else error 0x8423e8
-/// 488e05  call 0x6f3620             ; lua_tonumber(L,1)
-/// 488e0a  call 0x40a2b0             ; -> int, RC forced to CHOP (`or ah,0x0c`): TRUNCATE toward zero
-/// 488e11  test esi,esi; jl  0x488e9b ; n < 0  -> error 0x8423b8
-/// 488e19  cmp  esi,3;   jge 0x488e9b ; n >= 3 -> error 0x8423b8
-/// 488e1e  mov eax,[esi*4 + 0x804518] ; {16,32,48}      -> "%d"  -> CVar::Set "frillDensity"
-/// 488e56  fld dword [esi*4+0x804524] ; {0.07,0.04,0.01} -> "%f" -> CVar::Set "smallCull"
-/// ```
-///
-/// The two error strings are `0x8423e8` `"Usage: SetWorldDetail(value)"` and `0x8423b8` `"value
-/// must be in the range 0, 2"` — both read out of the image, lowercase `v` and all. Every path
-/// returns **zero** Lua values.
-///
-/// Three shapes worth stating because the obvious reading is wrong on each:
-///
-/// - **The truncation is toward zero, not a floor.** `0x40a2b0` saves the FPU control word, ORs
-///   `0x0c` into the high byte (rounding-control = chop) and `fistp`s. So `SetWorldDetail(2.9)`
-///   is stop 2 and `SetWorldDetail(-0.5)` is stop **0** — a negative that truncates to zero is
-///   accepted, and only `<= -1` raises.
-/// - **`lua_isnumber` accepts a numeric string**, so `SetWorldDetail("2")` works there and here.
-/// - **The getter is not the setter's inverse.** `0x488d70` reads only `smallCull`, seeds its
-///   result at **2**, and runs `for i in 0..3 { if v <= tbl[i] { result = i } }` over the
-///   *descending* `{0.07, 0.04, 0.01}` with **no break** — so the last match wins, and any
-///   `smallCull` above `0.07` (legal to 2.0) saturates to 2, i.e. the least detail reads back as
-///   the most. A shipped defect, and one of two: `OptionsFrame_SetDefaults` tests that same
-///   descending table with ascending `elseif`s, so Restore Defaults always parks the slider at 0.
-///
-/// **Where benilla diverges, and why it is not the smallCull ladder.** `SmallCull` is a dead knob
-/// in the reference — `[0x868620]` has one writer and no reader image-wide (wow-re
-/// `cvar/scratch/graphics-cost-cvar-census.md` §8) — so its *only* consumer there is this getter,
-/// which makes it storage for a stop the client keeps nowhere else. benilla keeps the stop:
-/// [`CVAR_WORLD_DETAIL`] is it, and `frillDensity` is the same knob in the reference's unit. So the
-/// getter reads the stop directly and `SmallCull` is not registered, because registering a CVar
-/// whose only purpose is to hold a number we already hold is the silent pretence 1203 forbids.
-///
-/// The observable consequence is **nil at boot and nil for every consumer we know**: a fresh
-/// reference client has `frillDensity 16` with `smallCull 0.04` — stop 0's frill with stop 1's cull
-/// — so its getter answers **1**, and benilla's `WorldDetail` registers at `"1"` for exactly that
-/// reason. The one input that separates them is a bare `frillDensity` write with no stop write,
-/// which there leaves the getter on the stale stop and here moves it; pfUI's `hdgraphic` is the
-/// only known caller and its own replacement short-circuits above 48, so it never reaches the
-/// difference.
+/// Deviation: the getter reads [`CVAR_WORLD_DETAIL`] and `smallCull` is not registered, because
+/// the reference's getter is `smallCull`'s only reader (`[0x868620]` is never read). A fresh
+/// reference client reads stop 1 (`frillDensity 16` with `smallCull 0.04`), hence
+/// `WorldDetail`'s `"1"`; only a bare `frillDensity` write moves ours and not the reference's.
 fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
     g.set(
         "SetWorldDetail",
         lua.create_function(|lua, value: Value| {
-            // `lua_isnumber`: a number, or a string Lua can convert to one. Anything else is the
-            // usage error — NOT a silent no-op.
+            // `lua_isnumber`: a number or a numeric string; anything else is the usage error.
             let n = match &value {
                 Value::Integer(i) => *i as f64,
                 Value::Number(n) => *n,
@@ -1103,9 +760,8 @@ fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
                 }
                 _ => return Err(mlua::Error::runtime(USAGE_SET_WORLD_DETAIL)),
             };
-            // Truncate toward zero (`0x40a2b0`'s chop), then the reference's own two bounds. NaN
-            // has no truncation — the reference's `fistp` yields the integer indefinite, which is
-            // negative and raises, so raising here is the same answer by the same door.
+            // Truncate toward zero, then the reference's bounds: -0.5 is stop 0 and only <= -1
+            // raises. NaN raises too, as the reference's `fistp` gives the negative indefinite.
             if n.is_nan() {
                 return Err(mlua::Error::runtime(RANGE_SET_WORLD_DETAIL));
             }
@@ -1115,11 +771,8 @@ fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
             }
             let stop = stop as usize;
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // TWO CVars per stop, as `0x488dd0` writes two: there it is `frillDensity` + the dead
-            // `smallCull`; here it is `frillDensity` + the stop the panel keeps. Both land on one
-            // clutter knob in the host, so applying both is idempotent — and writing only one
-            // would leave the other stale for a `GetWorldDetail` in the same Lua tick, since the
-            // host does not drain the change queue until the end of the frame.
+            // Two CVars per stop, as `0x488dd0` writes two: `frillDensity` and, here, the stop.
+            // Writing only one would leave `GetWorldDetail` stale until the host drains the queue.
             write_cvar(
                 &mut model,
                 CVAR_FRILL_DENSITY,
@@ -1133,19 +786,16 @@ fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
     )?;
     g.set(
         "GetWorldDetail",
-        // `MultiValue` in: the reference reads argument 1 for the SETTER only; the getter never
-        // calls `lua_gettop`, so an argument is accepted and ignored — and pfUI's replacement is
-        // declared `function _G.GetWorldDetail(arg)`, so it is passed one in practice.
+        // `MultiValue`: an argument is accepted and ignored, as the getter never calls
+        // `lua_gettop`.
         lua.create_function(|lua, _: mlua::MultiValue| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let stop = model
                 .cvars
                 .get(&CVAR_WORLD_DETAIL.to_ascii_lowercase())
                 .and_then(|slot| slot.value.parse::<f64>().ok())
-                // The reference can only ever answer 0, 1 or 2 (its result is an index into a
-                // three-entry table), so an off-grid stop — which ours can hold, because a console
-                // `frillDensity 200` moves the same knob — reports the nearest one rather than a
-                // number no caller has a branch for.
+                // The reference only answers 0, 1 or 2, so an off-grid stop (a console
+                // `frillDensity 200` moves it) reports the nearest.
                 .map_or(0, |v| v.round().clamp(0.0, 2.0) as i64);
             Ok(stop)
         })?,
@@ -1156,37 +806,17 @@ fn install_world_detail_verbs(lua: &Lua) -> mlua::Result<()> {
 /// `0x8423e8`, verbatim.
 const USAGE_SET_WORLD_DETAIL: &str = "Usage: SetWorldDetail(value)";
 
-/// `0x8423b8`, verbatim — lowercase `v`, and the odd comma is the reference's own.
+/// `0x8423b8`, verbatim: the lowercase `v` and the odd comma are the reference's.
 const RANGE_SET_WORLD_DETAIL: &str = "value must be in the range 0, 2";
 
-/// **The four nameplate verbs** — `ShowNameplates 0x489450`, `HideNameplates 0x489460`,
-/// `ShowFriendNameplates 0x489470`, `HideFriendNameplates 0x489480` (wow-re
-/// `ui/scratch/party-leader-and-nameplate-verbs.md`, §5 four-worker round).
+/// The four nameplate verbs: `ShowNameplates 0x489450`, `HideNameplates 0x489460`,
+/// `ShowFriendNameplates 0x489470`, `HideFriendNameplates 0x489480`. Each ignores its arguments
+/// (`ShowNameplates(false)` still shows) and returns zero values, and there is no getter; the
+/// state is bits `0x1` (enemy) and `0x8` (friend) of `[0xc4da34]`.
 ///
-/// Each is a **10-byte body** over one of two setters, and the reference's shape is worth stating
-/// because two obvious readings are wrong:
-///
-/// - **They read NO argument.** `ShowNameplates(false)` still shows. There is no `lua_gettop`, no
-///   `lua_toboolean`, nothing — the verb *is* the value, which is why there are four of them
-///   rather than two taking a flag.
-/// - **They return ZERO Lua values** — not `nil`, nothing. (`eax` at the `ret` is the return
-///   count, read off the VM's own C arm `0x6f61a8`.)
-/// - They are **four separate bodies**, not a masked pair like `UnitIsTapped`/`ByPlayer`:
-///   `0x489450` and `0x489470` are literally identical byte strings, rel32 included, over setters
-///   that differ only in their `or`/`and` masks.
-///
-/// The engine state is bits `0x1` (enemy) and `0x8` (friend) of one runtime dword `[0xc4da34]`.
-/// **There is no getter** — 15 references image-wide, all `.text`, and the 1153 `{name, fn}`
-/// records across all 54 registrar tables intersect the readers in the empty set — so an addon can
-/// set the state and never read it back, and neither can we.
-///
-/// **Where benilla diverges, deliberately and now knowingly.** 1.12 registers no nameplate CVar
-/// (censused: `0x63db90`'s 214 sites, 207 literal names, zero matching `/plate/i`), and the engine
-/// clears **both bits on every `EnterWorld`** — not once at boot. FrameXML replays them from its
-/// own `NAMEPLATES_ON`/`FRIENDNAMEPLATES_ON` saved variables. Our two CVars reproduce *FrameXML's
-/// replay*, not the engine's state model: a benilla player's plates survive a zone-in because the
-/// CVar store outlives it. That is a divergence in favour of the player, recorded here rather than
-/// mistaken for fidelity.
+/// Deviation: the state lives in two CVars, so a player's plates survive a zone-in; the reference
+/// registers no nameplate CVar (none of `0x63db90`'s sites), clears both bits on every
+/// `EnterWorld`, and FrameXML replays its `NAMEPLATES_ON`/`FRIENDNAMEPLATES_ON` saved variables.
 fn install_nameplate_verbs(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
     for (name, cvar, on) in [
@@ -1197,9 +827,8 @@ fn install_nameplate_verbs(lua: &Lua) -> mlua::Result<()> {
     ] {
         g.set(
             name,
-            // `MultiValue` and not `()`: mlua would otherwise reject a call that passes anything,
-            // and the reference accepts and ignores every argument. Returning `MultiValue::new()`
-            // is the zero-value return, which is NOT the same as pushing nil.
+            // Any arguments are ignored, as the reference reads none; the empty `MultiValue`
+            // returns zero values, which is not nil.
             lua.create_function(move |lua, _: mlua::MultiValue| {
                 let mut model = lua.app_data_mut::<Model>().expect("model app_data");
                 let key = cvar.to_ascii_lowercase();
@@ -1232,37 +861,29 @@ mod tests {
     #[test]
     fn the_table_round_trips_and_queues_changes_case_insensitively() {
         let mut s = script_with_volume();
-        // Registration seeds value = default; reads are case-insensitive.
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("musicvolume")"#)
                 .unwrap(),
             "0.4"
         );
-        // A Lua write queues ONE change under the REGISTERED spelling; the number stringifies.
         s.run(r#"SetCVar("MUSICVOLUME", 0.7)"#).unwrap();
         assert_eq!(
             s.take_cvar_changes(),
             vec![("MusicVolume".to_string(), "0.7".to_string())]
         );
         assert!(s.take_cvar_changes().is_empty(), "drained");
-        // The default is unmoved and separately readable.
         assert_eq!(
             s.eval::<String>(r#"return GetCVarDefault("MusicVolume")"#)
                 .unwrap(),
             "0.4"
         );
         assert_eq!(s.cvar("MusicVolume").as_deref(), Some("0.7"));
-        // A write to the same value queues nothing (quiet frames stay quiet).
         s.run(r#"SetCVar("MusicVolume", "0.7")"#).unwrap();
         assert!(s.take_cvar_changes().is_empty());
     }
 
-    /// **A latched row stages the write and keeps answering the applied value** (decision 2303)
-    /// — the reference's `Set 0x63df50` on flag bit1: `latchedValue` takes the string, `InternalSet`
-    /// never runs, so `GetCVar` (which reads `rec+0x20`) answers the old value until
-    /// `CVar::Update 0x63e060` commits it. The host still hears every staged write through the
-    /// change queue (it holds the pending copy), and its commit arrives as a host write, which
-    /// clears the stage. Writing the applied value back over a stage clears the stage too.
+    /// The reference's `Set 0x63df50` on flag bit1: `GetCVar` (`rec+0x20`) answers the old value
+    /// until `CVar::Update 0x63e060` commits, which here arrives as a host write.
     #[test]
     fn a_latched_row_stages_the_write_until_the_host_commits_it() {
         let mut s = UiScript::new().unwrap();
@@ -1292,7 +913,7 @@ mod tests {
             "the host hears the staged write"
         );
         // Staging the same value again is quiet; staging the applied value back clears the stage
-        // and is reported, so the host can drop its pending copy too.
+        // and is reported, so the host drops its pending copy too.
         s.run(r#"SetCVar("gxVSync", "0")"#).unwrap();
         assert!(s.take_cvar_changes().is_empty());
         s.run(r#"SetCVar("gxVSync", "1")"#).unwrap();
@@ -1313,7 +934,6 @@ mod tests {
             "0"
         );
         assert!(s.take_cvar_changes().is_empty());
-        // An unlatched sibling is untouched by any of this.
         s.run(r#"SetCVar("MusicVolume", 0.7)"#).unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("MusicVolume")"#)
@@ -1322,10 +942,6 @@ mod tests {
         );
     }
 
-    /// **An addon's `RegisterCVar` reaches the host** (decision 2303): the row it creates is
-    /// reported once, with the declared default, so the host's registry — the store that
-    /// outlives this VM — can carry it. A re-declaration of a live name is the no-op it always
-    /// was, and reports nothing.
     #[test]
     fn an_addon_registration_is_reported_to_the_host_once() {
         let mut s = UiScript::new().unwrap();
@@ -1343,10 +959,8 @@ mod tests {
         );
     }
 
-    /// **A bare CVar name through `ConsoleExec` is the host's to answer** (decision 2303): the
-    /// reference's per-CVar console command prints `CVar "%s" is "%s"` on an empty argument
-    /// (`0x63dde0`), and that printing lives host-side with the rest of the command registry.
-    /// A name WITH a value is still written synchronously, so the next Lua line reads it back.
+    /// The reference prints `CVar "%s" is "%s"` for a bare name (`0x63dde0`); that printing is the
+    /// host's, while a valued write lands here at once.
     #[test]
     fn console_exec_writes_a_valued_cvar_and_hands_a_bare_name_to_the_host() {
         let mut s = script_with_volume();
@@ -1364,12 +978,6 @@ mod tests {
         assert_eq!(s.take_console_lines(), vec!["MusicVolume".to_string()]);
     }
 
-    /// **`SetCVar`'s third argument is the `CVAR_UPDATE` token** (decision 1140) — the whole
-    /// mechanism behind that event. 1.12's options panels pass their CheckButtons table KEY
-    /// (`SetCVar(value.cvar, value.value, index)`), an uppercase display name, and the engine
-    /// hands it back verbatim as arg1 — which is what lets `UIOptionsFrame_OnEvent` do
-    /// `UIOptionsFrameCheckButtons[arg1]`. Omit it and nothing fires: the event is opt-in per
-    /// write. A write that changes nothing fires nothing either, like the change queue.
     #[test]
     fn the_third_argument_is_the_cvar_update_token() {
         let mut s = script_with_volume();
@@ -1381,13 +989,11 @@ mod tests {
         )
         .unwrap();
 
-        // No token: the value moves, the change queues, the event does not fire.
         s.run(r#"SetCVar("MusicVolume", "0.5")"#).unwrap();
         s.tick(0.0);
         assert_eq!(s.eval::<f64>("return getn(SEEN)").unwrap(), 0.0);
 
-        // With one: arg1 is the token verbatim (the display name, NOT the CVar's own name),
-        // arg2 the new value.
+        // With one: arg1 is the token verbatim, not the CVar's name, and arg2 the new value.
         s.run(r#"SetCVar("MusicVolume", "0.6", "MUSIC_VOLUME")"#)
             .unwrap();
         s.tick(0.0);
@@ -1396,7 +1002,6 @@ mod tests {
             "MUSIC_VOLUME=0.6"
         );
 
-        // A no-op write is silent on both channels.
         s.run(r#"SetCVar("MusicVolume", "0.6", "MUSIC_VOLUME")"#)
             .unwrap();
         s.tick(0.0);
@@ -1439,14 +1044,6 @@ mod tests {
         s.register_cvars([("MusicVolume", "0.4")]);
         assert_eq!(s.cvar("MusicVolume").as_deref(), Some("0.9"));
     }
-    /// **`GetCVar("realmName")` answers the session's realm, set by the one seam that owns it.**
-    ///
-    /// It is a real 1.12 CVar (`0x83f2d0`, persisted — the client builds its SavedVariables path
-    /// from it) and it had no value here at all. `Ace/AceState.lua:27` is
-    /// **Registration honors the saved base** (decision 1291) — the bridge that makes the
-    /// per-VM table behave like the reference's engine-side store: a knobless CVar keeps the
-    /// player's persisted value across a VM replacement, and the default stays the DEFAULT so
-    /// "moved off default" still means something to the saver.
     #[test]
     fn registration_starts_at_the_saved_value_not_the_default() {
         let mut s = UiScript::new().unwrap();
@@ -1472,8 +1069,6 @@ mod tests {
         );
     }
 
-    /// The same law through the Lua half: an addon's `RegisterCVar` (decision 1195) starts at
-    /// the persisted value, so its setting survives the VM being replaced (1290/1291).
     #[test]
     fn an_addon_registered_cvar_starts_at_its_saved_value() {
         let mut s = UiScript::new().unwrap();
@@ -1492,10 +1087,6 @@ mod tests {
         );
     }
 
-    /// The Video options Multisampling dropdown, driven exactly as `OptionsFrame.lua` drives it:
-    /// `_Initialize` walks `GetMultisampleFormats()` three varargs at a time, `_OnLoad` seeds the
-    /// selection from `GetCurrentMultisampleFormat()`, and the Okay handler (l.240) writes back
-    /// through `SetMultisampleFormat(id)`.
     #[test]
     fn the_multisample_dropdown_round_trips_through_the_three_bindings() {
         let mut s = UiScript::new().unwrap();
@@ -1522,7 +1113,6 @@ mod tests {
             },
         ]);
 
-        // Flat triples, in order — the shape `for i=1, arg.n, 3` walks.
         let flat: Vec<f64> = s.eval(r#"return { GetMultisampleFormats() }"#).unwrap();
         assert_eq!(
             flat,
@@ -1530,14 +1120,14 @@ mod tests {
             "three fields per entry, entries in offer order"
         );
 
-        // 1-BASED: the default `gxMultisample "1"` is the FIRST row, not the zeroth.
+        // 1-based: the default `gxMultisample "1"` is the first row.
         assert_eq!(
             s.eval::<f64>("return GetCurrentMultisampleFormat()")
                 .unwrap(),
             1.0
         );
 
-        // Pick 4x — the third row — and all three CVars move together, as `0x48c640` writes them.
+        // Pick 4x, the third row: all three CVars move together, as `0x48c640` writes them.
         s.eval::<()>("SetMultisampleFormat(3)").unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("gxMultisample")"#)
@@ -1556,8 +1146,6 @@ mod tests {
             "the selection round-trips: what Set wrote, GetCurrent finds"
         );
 
-        // The host sees the write, so the config file is dirtied — the same route a Lua SetCVar
-        // takes. Without this the player's choice would live only until they quit.
         let changed: Vec<String> = s
             .take_cvar_changes()
             .into_iter()
@@ -1568,8 +1156,6 @@ mod tests {
             "expected gxMultisample on the change queue, got {changed:?}"
         );
 
-        // Off the end is ignored, never clamped: a clamp would silently apply a format the player
-        // did not choose.
         s.eval::<()>("SetMultisampleFormat(99)").unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("gxMultisample")"#)
@@ -1579,17 +1165,14 @@ mod tests {
         );
     }
 
-    /// `ace.trim(GetCVar("realmName"))` inside `SetGameState`, which EVERY Ace addon runs at
-    /// PLAYER_ENTERING_WORLD, so nil became `gsub(nil, ...)` and took the whole family down.
-    ///
-    /// Asserted through `set_realm_name` rather than by writing the CVar directly, because that is
-    /// the point: the CVar and `GetRealmName()` are the SAME fact and must not be settable apart.
+    /// `realmName` is a real 1.12 CVar (`0x83f2d0`) and must be a string: every Ace addon runs
+    /// `ace.trim(GetCVar("realmName"))` at `PLAYER_ENTERING_WORLD` (`Ace/AceState.lua:28`). Set
+    /// through `set_realm_name`, the seam `GetRealmName()` also reads.
     #[test]
     fn the_realm_name_cvar_and_get_realm_name_are_one_fact() {
         let mut s = UiScript::new().unwrap();
         s.register_cvars([("realmName", "")]);
 
-        // Before a session: empty, never nil — `ace.trim` must have a string to gsub.
         assert_eq!(
             s.eval::<String>(r#"return GetCVar("realmName")"#).unwrap(),
             ""
diff --git a/crates/benilla-ui/src/script/death.rs b/crates/benilla-ui/src/script/death.rs
index 71990984..5330a4d0 100644
--- a/crates/benilla-ui/src/script/death.rs
+++ b/crates/benilla-ui/src/script/death.rs
@@ -1,87 +1,63 @@
-//! The death-arc Lua surface (decisions 0308, 1746): the release/reclaim/resurrect/self-res verbs
-//! and the state getters the reference's DEATH / RECOVER_CORPSE / RESURRECT* / XP_LOSS dialogs
-//! call.
-//!
-//! Engine-free seam like [`super::unit`]: the app pushes a [`DeathUiState`] snapshot per frame
-//! (the countdowns + offer bits it computes from the wire) and drains the queued
-//! [`DeathAction`]s into `ClientCommand`s. The predicates return Lua booleans rather than the
-//! client's `1`/nil — truthy either way, the branch shape callers use is identical (the
-//! [`super::unit`] convention).
+//! The release, reclaim, resurrect and self-res verbs and the getters the `DEATH`,
+//! `RECOVER_CORPSE`, `RESURRECT` and `XP_LOSS` dialogs call, over a snapshot the app pushes.
+//! The three predicates answer Lua booleans where the reference answers `1` or nil
+//! (`ResurrectHasSickness` `0x48aa00`, `ResurrectHasTimer` `0x48aa30`, `CheckSpiritHealerDist`
+//! `0x48d120`).
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// The death snapshot the app pushes each frame ([`super::UiScript::set_death`]). Plain data —
-/// no mlua handles, no ECS types.
+/// The death snapshot the app pushes each frame.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct DeathUiState {
-    /// Seconds until the server force-releases — the client-side mirror of the 6:00
-    /// `CORPSE_REPOP_TIME` the wire never carries (decision 0308 §4), counted from the death
-    /// edge. `None` = no release timer (`PLAYER_FIELD_BYTES` bit 0x08 clear — an instanceable
-    /// map): `GetReleaseTimeRemaining` returns **−1** and the DEATH dialog shows the no-timer
-    /// text.
+    /// Seconds until the server force-releases, counted from death against the 6-minute
+    /// `CORPSE_REPOP_TIME` the wire never carries. `None` (`PLAYER_FIELD_BYTES` bit `0x08` clear,
+    /// an instanceable map) answers -1, which picks the no-timer text (`StaticPopup.lua:380-387`).
     pub release_remaining: Option<f32>,
-    /// Seconds until the corpse becomes reclaimable (`SMSG_CORPSE_RECLAIM_DELAY` anchored at
-    /// arrival; `0` = reclaimable now). `GetCorpseRecoveryDelay`'s value — the RECOVER_CORPSE /
-    /// RESURRECT StartDelay gate.
+    /// Seconds until the corpse is reclaimable, from `SMSG_CORPSE_RECLAIM_DELAY` at arrival; the
+    /// `StartDelay` gate of `RECOVER_CORPSE` and `RESURRECT`.
     pub recovery_delay: f32,
     /// The pending resurrect offer warns of resurrection sickness (`ResurrectHasSickness`).
     pub resurrect_sickness: bool,
     /// The pending offer still honors the reclaim-delay gate (`ResurrectHasTimer`).
     pub resurrect_has_timer: bool,
-    /// The confirm-owning spirit healer is within dialog range (`CheckSpiritHealerDist` — the
-    /// XP_LOSS dialogs' OnUpdate auto-hide).
+    /// The confirming spirit healer is in dialog range (`CheckSpiritHealerDist`).
     pub spirit_healer_in_range: bool,
-    /// The "N minutes"/"N seconds" sickness-duration string a spirit-healer res would apply, or
-    /// `None` below the sickness level (`GetResSicknessDuration` → nil — picks XP_LOSS vs
-    /// XP_LOSS_NO_SICKNESS, ref UIParent.lua's CONFIRM_XP_LOSS arm).
+    /// The sickness duration a spirit-healer res would apply ("N minutes"); `None` below the
+    /// sickness level picks `XP_LOSS_NO_SICKNESS` (`UIParent.lua:399-408`).
     pub sickness_duration: Option<String>,
-    /// What `HasSoulstone()` answers: the **label** of the self-resurrect available right now, or
-    /// `None` for nil (decision 1746, whose Context carries the wow-re decode this shape comes from).
-    ///
-    /// A string, not an id, because that is the whole of what the API returns: the DEATH dialog
-    /// stamps it straight onto its second button (`Button2:SetText(HasSoulstone())`) and uses the
-    /// same call as `DisplayButton2`. The app resolves it, because the script VM has no
-    /// spell-catalog or item-cache binding (the `ui_cast`/`ui_mirror` idiom, decision 0107).
-    ///
-    /// Two sources, and the client's own fork picks between them
-    /// ([`crate::script::death`]'s app-side resolver): `PLAYER_SELF_RES_SPELL` named through
-    /// `Spell.dbc` (3026/20758-20761 are all literally **"Use Soulstone"**, 21169
-    /// **"Reincarnation"**, 23700 **"Twisting Nether"** — Blizzard named those effect spells *as
-    /// button labels*), else a carried item whose on-use spell self-resurrects, named by the
-    /// **item**.
+    /// `HasSoulstone()`'s label (`0x48ac80`), stamped on the DEATH dialog's second button:
+    /// `PLAYER_SELF_RES_SPELL`'s `Spell.dbc` name (3026 and 20758-20761 "Use Soulstone", 21169
+    /// "Reincarnation", 23700 "Twisting Nether"), else a carried self-resurrect item's name.
     pub self_res_label: Option<String>,
 }
 
-/// One drained death intent (the app's [`super::UiScript::take_death_actions`] maps each to its
-/// `ClientCommand`).
+/// One drained death intent.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum DeathAction {
-    /// `RepopMe()` — release the spirit (`CMSG_REPOP_REQUEST`).
+    /// `RepopMe()`: `CMSG_REPOP_REQUEST`.
     Repop,
-    /// `RetrieveCorpse()` — reclaim the corpse (`CMSG_RECLAIM_CORPSE`).
+    /// `RetrieveCorpse()`: `CMSG_RECLAIM_CORPSE`.
     RetrieveCorpse,
-    /// `AcceptResurrect()` — accept the pending offer (`CMSG_RESURRECT_RESPONSE` accept).
+    /// `AcceptResurrect()`: `CMSG_RESURRECT_RESPONSE`, accepting.
     AcceptResurrect,
-    /// `DeclineResurrect()` — decline it (`CMSG_RESURRECT_RESPONSE` decline).
+    /// `DeclineResurrect()`: `CMSG_RESURRECT_RESPONSE`, declining.
     DeclineResurrect,
-    /// `AcceptXPLoss()` — take the spirit healer's res (`CMSG_SPIRIT_HEALER_ACTIVATE`).
+    /// `AcceptXPLoss()`: `CMSG_SPIRIT_HEALER_ACTIVATE`.
     AcceptXpLoss,
-    /// `UseSoulstone()` — spend the self-resurrect. **Which wire that is, is the app's to decide
-    /// at drain time**, exactly as the binding decides it at call time: a non-zero
-    /// `PLAYER_SELF_RES_SPELL` sends `CMSG_SELF_RES`, and a zero one falls through to using the
-    /// carried item instead (decision 1746).
+    /// `UseSoulstone()`: `CMSG_SELF_RES` when `PLAYER_SELF_RES_SPELL` is non-zero, else a use of
+    /// the carried item, decided at drain time as the reference decides it at call time.
     UseSoulstone,
 }
 
 impl super::UiScript {
-    /// Push this frame's death snapshot (the app's per-frame feed, before the event dispatch).
+    /// Push this frame's death snapshot, before the event dispatch.
     pub fn set_death(&mut self, state: DeathUiState) {
         self.model_mut().death = state;
     }
 
-    /// Drain the queued death intents (the app's per-frame drain).
+    /// Drain the queued death intents.
     pub fn take_death_actions(&mut self) -> Vec<DeathAction> {
         std::mem::take(&mut self.model_mut().death_actions)
     }
@@ -107,8 +83,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_action(lua, "AcceptXPLoss", DeathAction::AcceptXpLoss)?;
     install_action(lua, "UseSoulstone", DeathAction::UseSoulstone)?;
 
-    // GetReleaseTimeRemaining() → seconds until the forced release, or −1 = no timer (the DEATH
-    // dialog's no-timer text pick, ref StaticPopup.lua:380-387).
     g.set(
         "GetReleaseTimeRemaining",
         lua.create_function(|lua, ()| {
@@ -120,7 +94,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCorpseRecoveryDelay() → whole seconds until reclaimable (0 = now) — the StartDelay gate.
     g.set(
         "GetCorpseRecoveryDelay",
         lua.create_function(|lua, ()| {
@@ -151,8 +124,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetResSicknessDuration() → the duration string, or nil below the sickness level (the
-    // CONFIRM_XP_LOSS variant pick, ref UIParent.lua:399-408).
     g.set(
         "GetResSicknessDuration",
         lua.create_function(|lua, ()| {
@@ -164,12 +135,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasSoulstone() → the self-resurrect's label, or nil (decision 1746). The DEATH dialog
-    // uses the one call three ways — `DisplayButton2` (show the button at all), `OnShow`
-    // (`Button2:SetText(text)`) and `OnCancel`'s clicked arm (soulstone vs release) — so the
-    // falsey return has to be **nil** and not `0`: Lua's `0` is truthy, and a `0` here would both
-    // show the button forever and stamp "0" on it. The whole answer is computed app-side; this is
-    // a pure read of the pushed snapshot.
+    // Nil, never `0`, when there is none: the DEATH dialog shows its second button on any truthy
+    // answer, stamps the answer on it and picks soulstone over release by it.
     g.set(
         "HasSoulstone",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/diagnostics.rs b/crates/benilla-ui/src/script/diagnostics.rs
index 1ea3ee2d..5ce47a31 100644
--- a/crates/benilla-ui/src/script/diagnostics.rs
+++ b/crates/benilla-ui/src/script/diagnostics.rs
@@ -1,65 +1,12 @@
-//! The **script error log** — what went wrong, kept where the player can read it (decision 1495).
+//! The script error log: this session's script errors, addon load failures and warnings, kept
+//! for the player to read. The reference has no such log: its `_ERRORMESSAGE` shows only the first
+//! message of a burst, and a load failure that never raises reaches no screen. Dispatch and
+//! `_ERRORMESSAGE` are unchanged by it.
 //!
-//! ## Why this exists
-//!
-//! 1305 gave script errors a *screen*: the engine dispatches every caught error to
-//! `geterrorhandler()`, and FrameXML's `_ERRORMESSAGE` puts the red `ScriptErrors` dialog up. That
-//! is the reference's behaviour and it stays exactly as it is. It is also, on its own, not enough,
-//! and the reporters said so within a day of it shipping — Goudy, *minutes after screenshotting
-//! that very dialog working*: *"some kind of lua error frame probably needs to be implemented, as
-//! there are a lot of addons that still doesn't work"*; nazriel_0, two days later: *"probably we
-//! should start using something like Bug Grabber to report those stack traces better"* (ledger
-//! B293, split from B271).
-//!
-//! Both asks are the same three gaps, and all three are about *memory*:
-//!
-//! 1. **`_ERRORMESSAGE` shows a burst's FIRST message only** — its own `ScriptErrors:IsVisible()`
-//!    guard, faithfully transcribed. A world entry that raises 1,113 times (1305 measured exactly
-//!    that) shows one string. This is precisely why BugGrabber exists in the real world.
-//! 2. **An addon can fail to load without ever raising**, and those failures had no channel at all
-//!    — a manifest entry the package does not ship, a document that will not parse, a dependency
-//!    cycle, a missing hard dependency, a broken `Bindings.xml`. They logged to the terminal and
-//!    stopped; the addon simply was not there and the client said nothing. That is the literal
-//!    content of *"a lot of addons that still doesn't work"*.
-//! 3. **Nothing retained anything.** [`super::UiScript::take_errors`] drains to the host log every
-//!    frame, so once a frame passed, the terminal held the only copy. A player cannot read a
-//!    terminal, and a bug report written from one is what B271 was debugged off.
-//!
-//! ## What this is, and what it deliberately is not
-//!
-//! A bounded, deduplicating, ordered log of everything that went wrong this session, written at
-//! the two choke points every failure already passes ([`super::model::Model::record_script_error`]
-//! and [`super::UiScript::report_load_failure`]) and read by whatever wants to show it.
-//!
-//! **"Session" means one world session, not one process.** The log lives on the `Model`, and the
-//! in-game UI is rebuilt onto a fresh VM at every world entry (1290) — so a logout or a `ReloadUI`
-//! starts an empty log. That is the right boundary and it self-heals: the load walk runs again on
-//! the way back in and re-records whatever is still broken. What it is *not* is a place to look for
-//! what happened before the reload you just did.
-//!
-//! It is **purely additive**: no dispatch changes, no `_ERRORMESSAGE` change, no divergence from
-//! the reference's own behaviour. The reference simply never had this instrument, and *"a modern,
-//! idiomatic client"* covers building one.
-//!
-//! It is **not** a transcription of BugGrabber, which is somebody else's addon (and not Blizzard's
-//! either). It is our own equivalent, and an addon that installs its own `seterrorhandler` still
-//! wins outright for the dispatch half exactly as 1195/1305 leave it.
-//!
-//! ## Dedupe, order, and the bound
-//!
-//! **Repeats collapse onto the first occurrence and bump a count.** An `OnUpdate` that raises
-//! every frame is one row reading `×1113`, not 1,113 rows — without that the log is useless within
-//! seconds, and unbounded besides.
-//!
-//! **Order is first-occurrence, oldest first.** The load-time failures are the causes and the
-//! later runtime errors are usually their consequences, so a chronological read is the one that
-//! explains itself. A repeat does *not* move its row to the end: a row that jumps around while you
-//! read it is worse than a stale position.
-//!
-//! **[`DIAGNOSTIC_LOG_CAP`] distinct rows**, evicting oldest-first. `seq` is monotonic and never
-//! reused, so an evicted prefix is visible as a gap rather than silently rewriting history — a
-//! surface can say "showing #251-#500" honestly. The cap binds *distinct* messages, which after
-//! dedupe is a much higher ceiling than it looks: 1305's 1,113-raise run produces **one** row.
+//! A repeat bumps its row's count and keeps its place, rows are oldest first, and past
+//! [`DIAGNOSTIC_LOG_CAP`] distinct messages the oldest is evicted; `seq` is never reused, so an
+//! eviction shows as a gap. The log lives on the `Model`, and every world entry and `ReloadUI`
+//! builds a fresh VM, so each starts an empty log.
 
 use std::collections::VecDeque;
 
@@ -67,43 +14,25 @@ use mlua::{IntoLua, Lua, MultiValue, Value};
 
 use super::Model;
 
-/// How many **distinct** messages the log retains before evicting the oldest.
-///
-/// Sized against the worst real load we have measured rather than a round number: the 218-addon
-/// corpus behind 1306, loaded at once, is the widest set of distinct failures this client has ever
-/// produced. Dedupe means repeats cost nothing, so this bounds *kinds* of problem, not events.
+/// Distinct messages retained before the oldest is evicted, sized for the whole 218-addon corpus
+/// loaded at once.
 pub const DIAGNOSTIC_LOG_CAP: usize = 256;
 
-/// What a retained row *is* — and the split is by **consequence**, not by where it was caught,
-/// because that is the only distinction the player can act on.
+/// What a row reports, split by its consequence to the player.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum DiagnosticKind {
-    /// **Code ran and raised.** The addon is loaded and working apart from this; the failure may
-    /// be harmless, may be one frame's bad luck, may be constant. This is the class that already
-    /// reaches the red dialog.
+    /// Code ran and raised; the addon is otherwise loaded.
     Error,
-    /// **An addon did not load.** Definitely broken, definitely worth telling somebody about, and
-    /// before 1495 invisible unless you were reading the terminal. Both the raising kind (a file
-    /// scope that blew up) and the silent kind (a missing file, an unparseable document, a
-    /// dependency that isn't there) land here — from the player's side they are one thing: *the
-    /// addon isn't running*.
+    /// An addon did not load, whether its file scope raised or a file, document or dependency
+    /// was missing or broken.
     Load,
-    /// **The call was accepted and did not do what it said.** Nothing raised and nothing failed to
-    /// load: an `inherits=` argument that was not a template name and got dropped, a `SetPoint`
-    /// whose `relativeTo` did not resolve and re-anchored to the owner, a `SetCVar` on a name
-    /// nothing registered, a saved variable that could not be serialised, a `CreateMacro` that
-    /// was refused. The addon runs on, believing it got what it asked for.
-    ///
-    /// **This kind exists because the channel was a dead end** (decision 2135). These messages had
-    /// one consumer — a `warn!` line in the host's terminal, drained and discarded every frame —
-    /// so they reached neither the player (who cannot read a terminal, which is the whole
-    /// argument of 1495 above) nor the addon survey (whose columns read `errors`). A warning is
-    /// exactly the class an instrument is *for*: it is the failure that does not announce itself.
+    /// A call was accepted and did not do what it said (a dropped `inherits=`, an unresolved
+    /// `SetPoint` target, a `SetCVar` on an unregistered name, a refused `CreateMacro`).
     Warning,
 }
 
 impl DiagnosticKind {
-    /// The one-word tag a surface prints. Stable — a surface may key colour off it.
+    /// The one-word tag a surface prints; stable, as a surface may key colour off it.
     pub fn tag(self) -> &'static str {
         match self {
             Self::Error => "error",
@@ -116,41 +45,31 @@ impl DiagnosticKind {
 /// One retained row.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Diagnostic {
-    /// Monotonic, 1-based, **never reused** — the "#N" a surface shows. Survives eviction, so a
-    /// gap in the numbers is an honest report that older rows were dropped.
+    /// The "#N" a surface shows: 1-based, monotonic and never reused.
     pub seq: u64,
     pub kind: DiagnosticKind,
-    /// The message exactly as the host logged it — same string, same spelling, so a player's
-    /// screenshot and our terminal line are greppable against each other.
+    /// The message exactly as the host logged it.
     pub message: String,
-    /// How many times this exact `(kind, message)` has occurred. Starts at 1.
+    /// Occurrences of this `(kind, message)`, from 1.
     pub count: u32,
 }
 
-/// The log itself. Lives on the model; see the module header for the shape and the why.
+/// The log, held on the model.
 #[derive(Debug, Default)]
 pub(crate) struct DiagnosticLog {
     rows: VecDeque<Diagnostic>,
-    /// The last `seq` handed out. Kept separately from `rows.len()` precisely so eviction cannot
-    /// renumber anything.
+    /// The last `seq` handed out; kept apart from `rows.len()` so eviction never renumbers.
     seq: u64,
 }
 
 impl DiagnosticLog {
-    /// Record one failure, collapsing it onto an existing identical row if there is one.
-    ///
-    /// The dedupe scan is linear over at most [`DIAGNOSTIC_LOG_CAP`] rows and runs on the failure
-    /// path only. The pathological caller is an `OnUpdate` raising at frame rate, where the scan
-    /// hits its row and returns — cheaper by far than the `String` allocation it saves, and
-    /// arithmetic beside the `mlua` error formatting that produced the message in the first place.
+    /// Record one failure, or bump the count of its identical row.
     pub(crate) fn record(&mut self, kind: DiagnosticKind, message: &str) {
         if let Some(row) = self
             .rows
             .iter_mut()
             .find(|r| r.kind == kind && r.message == message)
         {
-            // Saturating rather than wrapping: a count that rolls over to 0 reads as "this never
-            // happened", which is the one answer that is never true here.
             row.count = row.count.saturating_add(1);
             return;
         }
@@ -176,84 +95,54 @@ impl DiagnosticLog {
         self.rows.len()
     }
 
-    /// Distinct failures **ever** recorded this session, including rows since evicted. The
-    /// difference from [`Self::len`] is how many the cap ate.
+    /// Distinct failures recorded this session, evicted and cleared rows included.
     pub(crate) fn total(&self) -> u64 {
         self.seq
     }
 
-    /// Forget everything — the player's own "I've read these" act. Deliberately does **not** reset
-    /// `seq`: after a clear, the next row is still #N+1, so a screenshot taken before the clear and
-    /// one taken after cannot claim the same number for different failures.
+    /// Forget the rows but not the numbering, so no `#N` ever names two failures.
     pub(crate) fn clear(&mut self) {
         self.rows.clear();
     }
 }
 
 impl super::UiScript {
-    /// Every retained row, oldest first — a clone, because the caller is the app's UI and the
-    /// model is behind `app_data`. The log is capped at [`DIAGNOSTIC_LOG_CAP`] rows, so this is a
-    /// bounded copy of a list nothing reads at frame rate.
+    /// Every retained row, oldest first, cloned out of the model.
     pub fn diagnostics(&self) -> Vec<Diagnostic> {
         self.model_ref().diagnostics.rows().cloned().collect()
     }
 
-    /// `(retained rows, distinct failures ever recorded)`. The two differ once the cap has evicted.
+    /// `(retained rows, distinct failures ever recorded)`.
     pub fn diagnostic_counts(&self) -> (usize, u64) {
         let m = self.model_ref();
         (m.diagnostics.len(), m.diagnostics.total())
     }
 
-    /// Forget the retained rows (the player's "I've read these"). See [`DiagnosticLog::clear`] for
-    /// why the numbering is deliberately *not* reset.
+    /// Forget the retained rows; the numbering carries on.
     pub fn clear_diagnostics(&self) {
         self.model_mut().diagnostics.clear();
     }
 
-    /// Record an addon that **did not load** for a reason that never raised — a manifest entry the
-    /// package does not ship, a document that will not parse, a dependency cycle, a hard
-    /// dependency that is missing, a broken `Bindings.xml`.
-    ///
-    /// **Deliberately does not dispatch.** These are not Lua errors: nothing raised, there is no
-    /// traceback, and handing them to `geterrorhandler()` would put non-errors through
-    /// `_ERRORMESSAGE` and through every addon handler that ever replaces it — a divergence from
-    /// the reference for no gain, since the reference's own answer to an unparseable document is a
-    /// line in `FrameXML.log` and silence on screen. What 1495 changes is that the silence is no
-    /// longer *total*: the failure is retained and readable, it just does not seize the screen.
-    ///
-    /// The caller still logs its own line; this is the retention half, not a replacement for it.
+    /// Retain an addon load failure that never raised (a missing file, an unparseable document, a
+    /// dependency cycle or missing dependency, a broken `Bindings.xml`). It is not dispatched to
+    /// `geterrorhandler()`: the reference logs such a failure and shows nothing. The caller still
+    /// writes its own log line.
     pub fn report_load_failure(&self, msg: &str) {
         record_load_failure(&self.lua, msg);
     }
 
-    /// Retain one non-fatal warning the HOST caught and has already logged — a loader warning off
-    /// an addon's XML, carrying the `<Addon>/<file>` prefix only the caller knows (decision 2135).
-    ///
-    /// The retention half alone, exactly like [`Self::report_script_error`]: the caller writes its
-    /// own `warn!` line, and putting the message on [`Model::warnings`] as well would double it at
-    /// the app's next per-frame drain. For a warning the ENGINE raises, the door is
-    /// [`Model::record_warning`], which owns both halves.
+    /// Retain a warning the host has already logged (a loader warning with its `<Addon>/<file>`
+    /// prefix). Queuing it on `Model::warnings` too would log it twice; an engine-raised warning
+    /// goes through `Model::record_warning`, which does both.
     pub fn report_warning(&self, msg: &str) {
         record_warning(&self.lua, msg);
     }
 }
 
-/// **THE rule for "an addon file did not load"** — one implementation, both loaders (decision
-/// 2107).
-///
-/// The startup walk reaches it through [`super::UiScript::report_load_failure`]; `LoadAddOn`'s
-/// demand load reaches it directly, because it runs inside a Lua binding and holds only `&Lua`
-/// (1191 §4). That was the whole defect 2107 fixes: the two paths had **two copies** of the rule
-/// and the demand-load copy classified a missing manifest entry as a script error, so an addon the
-/// reference loads (logging `Couldn't open %s` and continuing) came back as a session failure here.
-///
-/// The reference's own shape, VERIFIED (wow-re `system/ui/scratch/xml-toc-path-resolution.md` §4
-/// and `include-lua-dispatch.md` §7): a failed open is **non-fatal** — `0x6edaa0` logs
-/// `"Couldn't open %s"` (`0x846ff4`) to the log sink at severity 2 and returns null; every failure
-/// leg "reports through the sink and returns normally, with no throw, no `longjmp` and no abort",
-/// and the enclosing `.toc`/document keeps loading. Nothing on that path reaches the Lua error
-/// handler, which is why this never dispatches (1495) and why 1450 made it a WARN: a broken
-/// package is the *package's* defect, and ERROR means "the client is broken".
+/// Retain an addon file that did not load: the one rule for the startup walk and for `LoadAddOn`,
+/// which holds only `&Lua`. The reference's failed open is non-fatal: `0x6edaa0` logs
+/// `Couldn't open %s` (`0x846ff4`) at severity 2 and loading goes on, never reaching the Lua
+/// error handler.
 pub(crate) fn record_load_failure(lua: &Lua, msg: &str) {
     lua.app_data_mut::<Model>()
         .expect("model app_data set")
@@ -261,13 +150,8 @@ pub(crate) fn record_load_failure(lua: &Lua, msg: &str) {
         .record(DiagnosticKind::Load, msg);
 }
 
-/// **THE rule for "something was accepted and did not do what it said"** — the retention half of
-/// the warning channel, for a caller that holds `&Lua` (decision 2135).
-///
-/// Its `&UiScript` face is [`super::UiScript::report_warning`] and its engine-internal sibling is
-/// [`Model::record_warning`]; the difference is only which of the two channels the caller still
-/// owes. A host caller has already written its own log line and wants retention only; an engine
-/// caller wants both.
+/// Retain a warning its caller, holding `&Lua`, has already logged; `Model::record_warning` also
+/// queues it for the host log.
 pub(crate) fn record_warning(lua: &Lua, msg: &str) {
     lua.app_data_mut::<Model>()
         .expect("model app_data set")
@@ -275,14 +159,10 @@ pub(crate) fn record_warning(lua: &Lua, msg: &str) {
         .record(DiagnosticKind::Warning, msg);
 }
 
-/// Register the error-log reads the `BenillaScriptLogFrame` polls.
-///
-/// **`Benilla`-prefixed because they are ours**, not 1.12's — the prefix rule as
-/// `tests::reference_surface` enforces it (1254: a name we invent must not collide, a name the
-/// reference owns must not be hidden). 1.12 has no error-log API to shadow, so there is nothing
-/// here an addon could have meant by a bare name.
+/// Register the error-log reads `BenillaScriptLogFrame` polls, `Benilla`-prefixed as they are not
+/// 1.12 API (`tests::reference_surface` enforces the prefix).
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // BenillaGetNumScriptErrors() -> retained, totalEverRecorded
+    // BenillaGetNumScriptErrors() → retained, totalEverRecorded
     lua.globals().set(
         "BenillaGetNumScriptErrors",
         lua.create_function(|lua, ()| {
@@ -290,9 +170,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok((model.diagnostics.len(), model.diagnostics.total()))
         })?,
     )?;
-    // BenillaGetScriptErrorInfo(index) -> seq, kind, message, count   (1-based, oldest first;
-    // nil for an out-of-range index, so a stale row index during a repaint reads as "gone"
-    // rather than erroring inside the very frame that lists errors.)
+    // BenillaGetScriptErrorInfo(index) → seq, kind, message, count; 1-based, oldest first, and
+    // nothing for an out-of-range index, so a row gone mid-repaint reads as gone.
     lua.globals().set(
         "BenillaGetScriptErrorInfo",
         lua.create_function(|lua, index: i64| {
@@ -312,7 +191,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             ]))
         })?,
     )?;
-    // BenillaClearScriptErrors()
     lua.globals().set(
         "BenillaClearScriptErrors",
         lua.create_function(|lua, ()| {
@@ -344,9 +222,6 @@ mod tests {
 
     #[test]
     fn a_warning_reaches_the_retained_log_and_the_host_drain() {
-        // 2135's whole subject. Before it, a warning existed for exactly as long as one terminal
-        // line: `take_warnings` drained it and nothing kept a copy, so neither the player's
-        // `/errors` window nor the addon survey could see one.
         let mut s = crate::script::UiScript::new().expect("vm");
         s.run(r#"SetCVar("thisCVarDoesNotExist", "1")"#).unwrap();
 
@@ -362,7 +237,6 @@ mod tests {
             .unwrap_or_else(|| panic!("…and it is RETAINED: {kept:#?}"));
         assert_eq!(row.kind, DiagnosticKind::Warning, "under its own kind");
 
-        // The drain is a drain; the log is a memory. A second frame does not lose the row.
         assert!(s.take_warnings().is_empty());
         assert!(s
             .diagnostics()
@@ -372,10 +246,8 @@ mod tests {
 
     #[test]
     fn a_text_sink_takes_bytes_rather_than_raising_on_them() {
-        // Decision 2138, and 1193's rule finally applied at the boundary 1193 named. `strsub` is
-        // byte-indexed by design, so a slice through a multi-byte character is a string an addon
-        // really does hand to `SetText` — and mlua's `String` conversion raised on it, killing the
-        // handler. A stray byte costs a glyph.
+        // `strsub` is byte-indexed, so an addon can hand `SetText` half a UTF-8 character; that
+        // costs a glyph, never a raise.
         let s = crate::script::UiScript::new().expect("vm");
         s.run(
             r#"
diff --git a/crates/benilla-ui/src/script/dialog_verbs.rs b/crates/benilla-ui/src/script/dialog_verbs.rs
index 0faa4bbf..c5f5d40d 100644
--- a/crates/benilla-ui/src/script/dialog_verbs.rs
+++ b/crates/benilla-ui/src/script/dialog_verbs.rs
@@ -1,31 +1,13 @@
-//! The dialog engine's own verbs (decision 1963) — the bindings the stock `StaticPopup.lua`
-//! bodies call that no window of ours had ever needed, each built to wow-re's
-//! `staticpopup-dialog-bindings.md` (VERIFIED at the bytes unless a line here says INFERRED):
-//!
-//! | binding | args → returns | here |
-//! |---|---|---|
-//! | `GetInstanceBootTimeRemaining()` | 0 → 1 number, whole seconds, 0 idle | reads the app's deadline |
-//! | `AcceptAreaSpiritHeal()` | 0 → 0 | queues the cached healer for the app to send `0x2E3`; SILENT with none cached |
-//! | `CancelAreaSpiritHeal()` | 0 → 0 | the generic cancel-aura of spell 2584 plus `AREA_SPIRIT_HEALER_OUT_OF_RANGE` |
-//! | `GetAreaSpiritHealerTime()` | 0 → 1 number, whole seconds | reads the app's deadline |
-//! | `AcceptBattlefieldPort(index, accept)` | 2 → 0 | raises on a non-number index, silent off 1..3; the optional-bool answer |
-//! | `CancelMeetingStoneRequest()` | 0 → 0 | queued; the app applies the leadership gate |
-//! | `IsInMeetingStoneQueue()` | 0 → the number `1` or `nil`, one value always | `[0xb72038] != 0` (wow-re `meeting-stone-status.md` §3.1, 1974) |
-//! | `GetMeetingStoneStatusText()` | 0 → string or `nil` | the cached text `[0xb7203c]`, `nil` while empty (§3.2) |
-//! | `CheckPetUntrainerDist()` | 0 → `1` or `nil` | the app's latch-and-range flag |
-//! | `ConfirmPetUnlearn()` | 0 → 0 | counted; the app holds the latch and the money gate |
-//!
-//! The pet pair is the talent-wipe pair's twin (`talent.rs`), latch for latch. `ForceLogout` is
-//! `session.rs`'s. `ReplaceTradeEnchant` is not here: it rides the trade-slot enchant targeting
-//! this engine does not build yet, and stays a named gap.
+//! The verbs the stock `StaticPopup.lua` dialogs call: the instance-boot and area spirit healer
+//! clocks, the battlefield port answer, the meeting stone pair and the pet untrain pair.
 
 use mlua::{Lua, Value};
 
 use super::binding_abi::{bool_or_default, coerced_number, flag};
 use super::Model;
 
-/// The area spirit healer's aura, `0xA18` — the one spell id `CancelAreaSpiritHeal` cancels, and
-/// the only cancel-aura argument that also fires `AREA_SPIRIT_HEALER_OUT_OF_RANGE` (`0x6e70b6`).
+/// The area spirit healer's aura (`0xA18`), the only cancel-aura spell that also fires
+/// `AREA_SPIRIT_HEALER_OUT_OF_RANGE` (`0x6e70b6`).
 pub const AREA_SPIRIT_HEALER_SPELL: u32 = 2584;
 
 impl super::UiScript {
@@ -51,7 +33,7 @@ impl super::UiScript {
         model.area_spirit_secs = secs;
     }
 
-    /// `AcceptAreaSpiritHeal()` calls since the last drain (each one a `0x2E3` to send).
+    /// `AcceptAreaSpiritHeal()` calls since the last drain, each a `0x2E3` to send.
     pub fn take_area_spirit_accepts(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().area_spirit_accepts)
     }
@@ -66,9 +48,8 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().meeting_stone_cancels)
     }
 
-    /// The meeting stone's two globals (1974): the queued area id (`[0xb72038]`, `0` = none) and
-    /// the cached status text (`[0xb7203c]`, `None` from process start to world enter and after
-    /// world leave). The app rebuilds the text; the VM only hands it back.
+    /// The meeting stone's two globals: the queued area id (`0xb72038`, 0 for none) and the
+    /// cached status text (`0xb7203c`, `None` outside the world), which the app rebuilds.
     pub fn set_meeting_stone(&mut self, area: u32, status_text: Option<String>) {
         let mut model = self.model_mut();
         model.meeting_stone_area = area;
@@ -79,7 +60,7 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // 0 args → 1 number: `max(deadline − now, 0) / 1000`, truncated (§5).
+    // `0x48b620`: `max(deadline - now, 0) / 1000`, truncated.
     g.set(
         "GetInstanceBootTimeRemaining",
         lua.create_function(|lua, ()| {
@@ -88,7 +69,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // §6: `if (cached healer == 0:0) return;` — SILENT — else `0x2E3` + the cached guid.
+    // `0x48df20`: silent with no healer cached, else `0x2E3` with the cached guid.
     g.set(
         "AcceptAreaSpiritHeal",
         lua.create_function(|lua, ()| {
@@ -99,11 +80,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // §6: `0x6e7040(0xA18)` — the generic cancel-aura routine: the event fires (only for this
-    // spell), then `0x136` + `u32 2584`, no guid. The routine's refusal — AttributesEx bit 13
-    // set, bit 2 clear, and `0x5ee290(player)` — never reaches its third leg for spell 2584:
-    // the shipped Spell.dbc fails the first two, checked against the data by the app's
-    // `spell_2584_never_trips_the_cancel_gate`. So the send is unconditional here.
+    // `0x48df30` runs the generic cancel-aura (`0x6e7040`): the event, then `0x136` with
+    // `u32 2584`, no guid. Its refusal gate (`AttributesEx` bit 13 set, bit 2 clear, then
+    // `0x5ee290`) never trips for 2584 in the shipped `Spell.dbc` (the app's
+    // `spell_2584_never_trips_the_cancel_gate`), so the send is unconditional.
     g.set(
         "CancelAreaSpiritHeal",
         lua.create_function(|lua, ()| {
@@ -115,7 +95,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // 0 → 1 number, whole seconds: `max(0, [0xb4e338] − now) / 1000`.
+    // Whole seconds: `max(0, [0xb4e338] - now) / 1000`.
     g.set(
         "GetAreaSpiritHealerTime",
         lua.create_function(|lua, ()| {
@@ -124,9 +104,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // §7: arg 1 must satisfy `lua_isnumber` (a number or a numeric string) or the binding
-    // RAISES `Usage:`; truncated, 1-based, off 1..=3 SILENT. Arg 2 is the reference's
-    // optional-boolean coercion (`0x6f1c10`, default 0), normalised to one byte.
+    // `0x4ab3b0`: an index failing `lua_isnumber` raises, one off 1..=3 is silent; the answer takes
+    // the reference's optional-boolean coercion (`0x6f1c10`, default no).
     g.set(
         "AcceptBattlefieldPort",
         lua.create_function(|lua, (index, accept): (Value, Value)| {
@@ -154,8 +133,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // §8: `0x293`, empty; gated only on party leadership (the app's, which holds the party) —
-    // it clears nothing, the server's reply does.
+    // `0x4ca5a0`: an empty `0x293` gated on party leadership (the app's); only the reply clears.
     g.set(
         "CancelMeetingStoneRequest",
         lua.create_function(|lua, ()| {
@@ -165,9 +143,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `IsInMeetingStoneQueue()` (`0x4ca570`): `mov eax,1` on BOTH legs — the number `1` when the
-    // queued area is non-zero, else nil; never `0` (truthy in Lua — it would pin the icon shown),
-    // never a boolean.
+    // `0x4ca570`: the number `1` or nil, never `0` (truthy, it would pin the icon) or a boolean.
     g.set(
         "IsInMeetingStoneQueue",
         lua.create_function(|lua, ()| {
@@ -176,8 +152,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetMeetingStoneStatusText()` (`0x4ca5b0`): `lua_pushstring([0xb7203c])`, whose NULL leg
-    // tail-jumps to `lua_pushnil` — a string or nil, one value, never `""` for "nothing".
+    // `0x4ca5b0`: a string or nil, never `""` for nothing.
     g.set(
         "GetMeetingStoneStatusText",
         lua.create_function(|lua, ()| {
@@ -189,8 +164,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // §9: `1` or `nil` — never `0`. The range test (`d² <= INTERACT_DISTANCE²`, a NaN OUT) is the
-    // app's, on the latched trainer.
+    // `0x48d1c0`: `1` or nil, never `0`; the app tests the range to the latched trainer.
     g.set(
         "CheckPetUntrainerDist",
         lua.create_function(|lua, ()| {
@@ -198,8 +172,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(flag(model.pet_untrainer_pending))
         })?,
     )?;
-    // §9: the confirm arm — the latch's guid, the money gate (`ERR_NOT_ENOUGH_MONEY`, no packet)
-    // and `0x2F0`, all the app's; here the call is counted.
+    // `0x48dca0`: the app holds the latch and the money gate, and sends `0x2F0`.
     g.set(
         "ConfirmPetUnlearn",
         lua.create_function(|lua, ()| {
@@ -298,7 +271,6 @@ mod tests {
         );
     }
 
-    /// The meeting stone pair: `1`/nil on the area, string/nil on the text — one value each.
     #[test]
     fn the_meeting_stone_pair_answers_one_or_nil_and_string_or_nil() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/dressup.rs b/crates/benilla-ui/src/script/dressup.rs
index 126bc596..2e787af6 100644
--- a/crates/benilla-ui/src/script/dressup.rs
+++ b/crates/benilla-ui/src/script/dressup.rs
@@ -1,31 +1,8 @@
-//! The **dressing room** surface (decisions 1060, 1969) — the `DressUpModel` widget's own three
-//! verbs (table `0x84f190`: `Undress 0x504c00` · `Dress 0x504cd0` · `TryOn 0x504d90`) and the
-//! ordered intent queue behind them and behind `PlayerModel`'s `SetUnit`/`RefreshUnit` when the
-//! pane is a dressing room.
-//!
-//! ## Why a queue, and why the state is the app's
-//!
-//! In the client the widget clones the unit's live model on `SetUnit`/`Dress` (`0x5059a0`, the
-//! attachment tree deep-copied) and `TryOn` overwrites one bodyslot or one of two hand lanes of
-//! that clone (wow-re `ui/scratch/dressup-model-equipment.md`). benilla renders no FrameXML model:
-//! every model pane is a booth bake the app composes from a look — the player's own visible items
-//! with the tried-on ones substituted in — and the VM holds neither item templates nor the
-//! player's equipment. So the verbs record *intents*, in order, and the app applies them
-//! (`take_dressup_intents`): `DressUpItem` resets *then* tries on in one breath when the window
-//! was closed (ref `DressUpFrame.lua:3-7`), and applying those two out of order would show the
-//! player's own gear instead of the item they clicked.
-//!
-//! ## What each verb means, off the bytes
-//!
-//! - `SetUnit(unit)` / `RefreshUnit()` / `Dress()` all funnel into the same rebuild-from-the-unit
-//!   worker (§1 of the note): every substitution is gone and the model is what the player shows in
-//!   the world. One intent, [`DressUpIntent::Dress`].
-//! - `Undress()` → `0x504490`: clears components bodyslots `0..0xb` — every worn piece, base and
-//!   tried-on alike — and touches no hand lane, so a held weapon stays (§5). [`DressUpIntent::Undress`].
-//! - `TryOn(item)`: the argument is `trunc(tonumber(arg))` (`__ftol 0x40a2b0`) handed to the item
-//!   cache, so a numeric string is an id and anything else is item 0, which previews nothing. The
-//!   stock `DressUpItemLink` hands it the digits it `gsub`bed out of the `|Hitem:` link. It gates
-//!   on nothing — no class, level or proficiency check anywhere in the path (`DressUpFrame.lua:2-16`).
+//! The dressing room: the `DressUpModel` verbs (table `0x84f190`) and the intent queue behind them
+//! and behind `SetUnit`/`RefreshUnit` on a dressing-room pane. The reference edits a clone of the
+//! unit's model (`0x5059a0`, `0x504350`); here the app composes the look from the intents in
+//! order, which matters: on a closed window `DressUpItem` resets, then tries on
+//! (`DressUpFrame.lua:3-7`).
 
 use mlua::{Lua, Table, Value};
 
@@ -33,32 +10,28 @@ use super::object::frame_handle_of;
 use super::Model;
 use crate::widget::FrameKind;
 
-/// Registry key of the `DressUpModel` method table — its **own three** entries. `PlayerModel`'s
-/// three and `Model`'s 23 come through the dispatcher's chain (`object.rs`).
+/// Registry key of the `DressUpModel` method table, its own three; the rest come by the chain.
 pub(super) const REG_DRESSUPMODEL_METHODS: &str = "__benilla_dressupmodel_methods";
 
-/// One queued dressing-room intent (see the module doc on ordering).
+/// One queued dressing-room intent, applied in order.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum DressUpIntent {
-    /// `DressUpModel:SetUnit("player")` (the open), `RefreshUnit()` and `Dress()` (the Reset
-    /// button) — "wear what the player is actually wearing", dropping every substitution.
+    /// `SetUnit`, `RefreshUnit` and `Dress` (the Reset button): the reference's rebuild from the
+    /// unit (`0x505b50`), dropping every substitution.
     Dress,
-    /// `DressUpModel:Undress()` — every worn piece off, base and tried-on; the hands keep what
-    /// they hold.
+    /// `Undress()`: bodyslots `0..0xb` cleared, worn and tried-on alike; the hands keep what they
+    /// hold (`0x504490`).
     Undress,
-    /// `DressUpModel:TryOn(item)` — substitute this item id into whichever slot its
-    /// `InventoryType` belongs to.
+    /// `TryOn(item)`: the item in its `InventoryType`'s slot, with no class, level or proficiency
+    /// check (`DressUpFrame.lua:2-16`).
     TryOn(u32),
-    /// The window was hidden — the app's own intent, derived from the frame going invisible
-    /// (`UiScript::frame_visible`): there is nothing to show, so the booth empties (and stops
-    /// rendering). The reference's widget keeps its state while hidden, but its next `DressUpItem`
-    /// re-issues `SetUnit("player")` precisely *because* the frame was not visible, so the state it
-    /// kept is never observable — dropping it is behaviour-identical and saves the bake.
+    /// The window was hidden, so the booth empties. The reference keeps its state while hidden,
+    /// but the next `DressUpItem` re-issues `SetUnit("player")`, so that state is never seen.
     Close,
 }
 
 impl super::UiScript {
-    /// Drain the dressing room's queued intents, oldest first — the app applies them in order.
+    /// Drain the dressing room's intents, oldest first; the app applies them in order.
     pub fn take_dressup_intents(&mut self) -> Vec<DressUpIntent> {
         std::mem::take(&mut self.model_mut().dressup_intents)
     }
@@ -71,8 +44,7 @@ fn queue(lua: &Lua, intent: DressUpIntent) {
         .push(intent);
 }
 
-/// `PlayerModel`'s `SetUnit`/`RefreshUnit` on a pane that is a `DressUpModel`: the rebuild that
-/// drops every substitution (the module doc). A no-op on any other pane.
+/// Queue the rebuild when `PlayerModel`'s `SetUnit`/`RefreshUnit` lands on a `DressUpModel`.
 pub(super) fn redress_if_dressup(lua: &Lua, this: &Table) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let is_dressup = lua
@@ -87,8 +59,8 @@ pub(super) fn redress_if_dressup(lua: &Lua, this: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `trunc(tonumber(arg))` — `__ftol 0x40a2b0` over `lua_tonumber`: a number or numeric string
-/// truncates toward zero; anything else is 0.
+/// `trunc(tonumber(arg))`, the reference's `__ftol` (`0x40a2b0`) over `lua_tonumber`; anything
+/// else is 0.
 fn item_arg(v: &Value) -> i64 {
     match v {
         Value::Integer(i) => *i,
@@ -105,7 +77,7 @@ fn item_arg(v: &Value) -> i64 {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // `Undress()` — `0x84f190` -> `0x504c00` -> `0x504490`.
+    // `0x504c00`.
     m.set(
         "Undress",
         lua.create_function(|lua, this: Table| {
@@ -115,7 +87,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `Dress()` — `0x504cd0`, the Reset button (`DressUpFrame.xml:182`).
+    // `0x504cd0`, the Reset button (`DressUpFrame.xml:182`).
     m.set(
         "Dress",
         lua.create_function(|lua, this: Table| {
@@ -125,8 +97,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `TryOn(item)` — `0x504d90` -> `0x504540(itemId)`. Item 0 (a non-number, a link string) looks
-    // up nothing in the client's cache and previews nothing; so does a negative one here.
+    // `0x504d90` calls `0x504540(itemId)`; item 0 (a non-number or a link) previews nothing, and
+    // so does a negative id here.
     m.set(
         "TryOn",
         lua.create_function(|lua, (this, item): (Table, Value)| {
@@ -156,8 +128,6 @@ mod tests {
         s
     }
 
-    /// The widget answers its own three, PlayerModel's three and Model's, in a chain five deep —
-    /// and a plain PlayerModel does not answer the three (the chain runs derived → base only).
     #[test]
     fn a_dress_up_model_is_a_player_model_plus_three_and_the_chain_runs_one_way() {
         let s = room();
@@ -200,9 +170,7 @@ mod tests {
         }
     }
 
-    /// The verbs queue intents in call order; `SetUnit`/`RefreshUnit` re-dress on THIS kind only;
-    /// `TryOn`'s argument is `trunc(tonumber(arg))`, so the stock file's digit string is an id and
-    /// a link string is item 0, which queues nothing.
+    /// The stock `DressUpItemLink` passes the link's digits: a digit string is an id, a link is 0.
     #[test]
     fn the_verbs_queue_intents_in_order_and_try_on_reads_its_argument_like_the_client() {
         let mut s = room();
diff --git a/crates/benilla-ui/src/script/duel.rs b/crates/benilla-ui/src/script/duel.rs
index 47183195..ecfb02c0 100644
--- a/crates/benilla-ui/src/script/duel.rs
+++ b/crates/benilla-ui/src/script/duel.rs
@@ -1,37 +1,26 @@
-//! The duel **Era API surface** (decision 0633) — four globals, no state.
-//!
-//! Duels are the smallest possible shape of the [`super::party`] seam: everything the UI needs to
-//! *read* arrives as event arguments (the challenger's name on `DUEL_REQUESTED`), so there is no
-//! snapshot to push — only the outbound half. Each call queues a [`DuelRequest`] the app drains
-//! ([`UiScript::take_duel_requests`]) and turns into its send, keeping the engine free of ECS/net
-//! reach (decision 0068 §3).
-//!
-//! The four are exactly the reference's own duel bindings, registered adjacent in its Lua API
-//! table (`0x849fc8`..`0x849ff0`) and each a one-liner over the same TU: `AcceptDuel` `0x4d4ce0`
-//! → `0x4d4830`, `CancelDuel` `0x4d4cf0` → `0x4d48b0`, `StartDuelUnit` `0x4d4c40` (unit token →
-//! guid, gated on typemask `0x10` = player), `StartDuel` `0x4d4c90` (name → guid). The two
-//! `StartDuel*` calls do **not** send a duel opcode — they cast the duel spell at the guid; the
-//! app owns that resolution.
+//! The four duel globals, registered together at `0x849fa8`. What the UI reads arrives as event
+//! arguments, so each call only queues a [`DuelRequest`] for the app to send. `AcceptDuel`
+//! (`0x4d4ce0`) and `CancelDuel` (`0x4d4cf0`) call `0x4d4830` and `0x4d48b0`; `StartDuel`
+//! (`0x4d4c40`) and `StartDuelUnit` (`0x4d4c90`) send no duel opcode but cast the duel spell at
+//! the guid they resolve (`0x4d4810`).
 
 use mlua::Lua;
 
 use super::Model;
 
-/// Outbound duel intents queued by the Era API calls, drained by the app
-/// ([`UiScript::take_duel_requests`]). Plain data — [`super::party::PartyRequest`]'s twin.
+/// A duel intent queued by the globals, drained by `UiScript::take_duel_requests`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum DuelRequest {
-    /// `AcceptDuel()` — accept the pending challenge (`CMSG_DUEL_ACCEPTED`).
+    /// `AcceptDuel()`, the `DUEL_REQUESTED` popup's Accept: `CMSG_DUEL_ACCEPTED`.
     Accept,
-    /// `CancelDuel()` — decline, cancel, or forfeit (`CMSG_DUEL_CANCELLED`); which one it means
-    /// is the server's read of the duel state, not ours.
+    /// `CancelDuel()`: `CMSG_DUEL_CANCELLED`, which the server reads by duel state as a decline,
+    /// a cancel or a forfeit.
     Cancel,
-    /// `StartDuel(name)` — challenge a player found by name. The app resolves the name to a guid
-    /// and casts the duel spell at it; an unresolvable name is dropped (the reference errors the
-    /// Lua call instead — the deviation is noted in the app-side drain).
+    /// `StartDuel(name)`: the reference resolves the name through `0x493aa0`, players only, and
+    /// does nothing on a miss.
     StartByName(String),
-    /// `StartDuelUnit(unit)` — challenge whoever a unit token points at. The app resolves the
-    /// token to a guid and rejects a non-player (the reference's typemask `0x10` gate).
+    /// `StartDuelUnit(unit)`, the unit popup's Duel row. The app casts only at a player; the
+    /// reference resolves the token (`0x515970`) with no player gate of its own.
     StartByUnit(String),
 }
 
@@ -41,20 +30,17 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().duel_requests)
     }
 
-    /// Queue an intent from the app side — the slash commands. In the reference these ARE Lua
-    /// (`SlashCmdList["DUEL"]` calls `StartDuel`, `SlashCmdList["DUEL_CANCEL"]` calls
-    /// `CancelDuel`); benilla parses slash lines in Rust, so the same intents enter the same
-    /// queue here rather than through the globals.
+    /// Queue an intent from the app's Rust slash parser: `/duel` and `/forfeit`, which the
+    /// reference's `SlashCmdList` handlers send through `StartDuel` and `CancelDuel`.
     pub fn queue_duel_request(&mut self, request: DuelRequest) {
         self.model_mut().duel_requests.push(request);
     }
 }
 
-/// Register the duel globals (the same style/place [`super::party`] registers its actions).
+/// Register the duel globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // AcceptDuel() — the DUEL_REQUESTED popup's Accept.
     g.set(
         "AcceptDuel",
         lua.create_function(|lua, ()| {
@@ -64,7 +50,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelDuel() — the popup's Decline, and /forfeit //concede //yield once under way.
+    // `CancelDuel()`: the popup's Decline, and `/forfeit` (`/concede`, `/yield`) once under way.
     g.set(
         "CancelDuel",
         lua.create_function(|lua, ()| {
@@ -74,7 +60,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // StartDuel(name) — /duel <name>.
     g.set(
         "StartDuel",
         lua.create_function(|lua, name: String| {
@@ -84,7 +69,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // StartDuelUnit(unit) — the unit popup's Duel row.
     g.set(
         "StartDuelUnit",
         lua.create_function(|lua, unit: String| {
diff --git a/crates/benilla-ui/src/script/editbox.rs b/crates/benilla-ui/src/script/editbox.rs
index 0bebc20c..857e136d 100644
--- a/crates/benilla-ui/src/script/editbox.rs
+++ b/crates/benilla-ui/src/script/editbox.rs
@@ -1,50 +1,22 @@
-//! The `EditBox` runtime — keyboard focus, the text buffer + cursor + selection, editing, and the
-//! key/char dispatch (`CSimpleEditBox`, factory `0x6eec70`).
+//! The `EditBox` runtime (`CSimpleEditBox`, factory `0x6eec70`): keyboard focus, the text buffer,
+//! cursor and selection, editing, and key and char dispatch.
 //!
-//! Grounded in wow-5875-re's byte-verified RF-0082 (`rf82-editbox-runtime.md`):
+//! - Focus: one owner ([`Model::focused_editbox`], the client's `DAT_00cf4dc8`). A left click
+//!   focuses and collapses the selection to the clicked byte (`0x77b86f call 0x77ccf0`, before
+//!   `SetFocus` at `0x77b881`), so it never selects all. An `autoFocus` box takes the focus on show
+//!   when none is held and on the first key, and a hidden box drops it ([`visibility_focus`]).
+//! - Routing: a focused box consumes every key and char and fires only its specialized scripts
+//!   (Enter, Escape, Space, Tab, TextChanged, TextSet, focus), never a generic `OnKeyDown`; an
+//!   unfocused box that is not `autoFocus` ignores input.
+//! - Editing: an insert replaces the selection; `numeric` aborts a whole insert on any non-digit;
+//!   caps trim from the end (`maxBytes`, then `maxLetters`).
 //!
-//! - **Focus (§1):** a single class-owned focus owner ([`Model::focused_editbox`], the client's
-//!   `DAT_00cf4dc8`). `SetFocus` gates on effective-visibility, is a no-op if already focused, and
-//!   fires `OnEditFocusLost` on the old box then `OnEditFocusGained` on the new. A LeftButton click
-//!   focuses UNCONDITIONALLY — and **collapses the selection to the clicked byte index** on its way
-//!   (`0x77b86f call 0x77ccf0`, immediately before `0x77b881 SetFocus`), so a fresh click-focus leaves
-//!   an EMPTY selection at the click point, never a select-all. `SetFocus` itself writes no selection
-//!   field, and `0x77e3f6` is the only instruction image-wide that gives a box focus — so *every*
-//!   focus gain, whatever triggers it, is selection-neutral.
+//! Mouse, selection and caret (click to index `0x77d0d0`, drag `0x77a860`) live in [`interact`]
+//! and [`seam`]; the OS clipboard is host-side, [`paste`] in and `UiScript::editbox_copy` or
+//! `editbox_cut` out. The host's per-OS keymap sends editing keys as [`EditAction`]s ([`action`]).
 //!
-//!   **`autoFocus` DOES focus on show** (corrected 2026-08-29, wow-re `editbox-selection-focus-law.md`
-//!   §6): the OnShow override tail-jumps `SetFocus` when nothing else holds focus, and the OnHide
-//!   mirror tail-jumps `ClearFocus`. The old "verified by absence" negative came from a `call`-only
-//!   census that could not see a tail-`jmp`. Both overrides are [`visibility_focus`] here, and the
-//!   construction default is `true` off the bytes (see
-//!   [`EditBoxState::auto_focus`](crate::widget::EditBoxState::auto_focus)). The
-//!   self-acquire-on-first-key half stands beside it.
-//! - **Routing (§2):** a focused box processes and CONSUMES every key/char (`return 1` past the
-//!   guard); an unfocused non-autoFocus box ignores input. The override fires ONLY the specialized
-//!   scripts (Enter/Escape/Space/Tab/TextChanged/TextSet/focus), never generic `OnKeyDown`/`OnChar`.
-//! - **Text/editing (§3/§4):** every insert replaces the selection first; `numeric` aborts an insert
-//!   wholesale on any non-digit; caps trim from the end (`maxBytes` then `maxLetters`); `SetText`
-//!   short-circuits when unchanged; `HighlightText(0,-1)` selects all with the client's clamp.
-//!
-//! The mouse/selection/caret half (click→index `0x77d0d0`, drag `0x77a860`, the clipboard pair,
-//! the 0.5 s blink, the char-granular scroll window) lives in [`interact`]/[`seam`] over the
-//! host-answered advance table — decision 0298. The OS clipboard itself stays host-side (this
-//! crate is engine-free): paste text arrives via [`paste`], copy/cut strings return through
-//! `UiScript::editbox_copy`/`editbox_cut`; Ctrl+A arrives as the SOH control char.
-//!
-//! Editing keys reach the box as semantic [`EditAction`]s ([`action`]) — the *host's* per-OS
-//! keymap decides which physical chord means which action (decision 0301), while the effect of
-//! each action stays this module's byte-verified law. [`key_input`] keeps only the three
-//! box-event keys (ENTER/ESCAPE/TAB).
-//!
-//! ## Stated divergences / gaps
-//! - **`OnCursorChanged`** (the 4-float caret-pos fire) is not fired — no shipped XML consumes it.
-//! - Small INFERRED corners (click rounding, word classes, no shift+click, the password-copy
-//!   placeholder literal) are flagged where they live — decision 0298's list.
-//! - **Word/edge deletes** (`Delete{Word,Edge}`) have no 1.12 counterpart at all — they exist for
-//!   the host's OS-native keymaps (Option/Cmd+Backspace on macOS, Ctrl+Backspace/Delete on
-//!   Windows/Linux; decision 0301) and reuse the byte-verified word classes + selection-first
-//!   delete law.
+//! Deviation: word and edge deletes (`Delete{Word,Edge}`), which 1.12 does not have, exist because
+//! the host's OS-native chords (Option/Cmd+Backspace, Ctrl+Backspace/Delete) expect them.
 
 use mlua::{Lua, Table, Value};
 
@@ -59,43 +31,32 @@ use crate::widget::{EditBoxState, FrameHandle, FrameKind, KindState, RegionHandl
 pub(super) const REG_EDITBOX_METHODS: &str = "__benilla_editbox_methods";
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Public entry points (called from UiScript::char_input / key_input / mouse_button)
+// Public entry points
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// A typed character. Routes per §1/§2; on a focused box, Ctrl+A (delivered as the SOH control char)
-/// selects all, other C0 control chars are consumed-but-inert, and printable text is inserted. Always
-/// consumes when a box is (or becomes) focused.
+/// A typed character: Ctrl+A (arriving as SOH) selects all, other C0 controls are consumed inert,
+/// printable text is inserted.
 pub(super) fn char_input(lua: &Lua, text: &str) -> bool {
     let Some(h) = route(lua) else {
         return false;
     };
     if text == "\u{1}" {
-        // Ctrl+A → select-all (the client's keydown case 0x41/0x61; here via char_input since a
-        // Ctrl-modified letter arrives as its control code).
+        // Ctrl+A selects all (the client's keydown case 0x41/0x61).
         highlight_text(lua, h, 0, -1);
     } else if text.chars().any(|c| (c as u32) >= 0x20) {
-        // A printable char (or string); pure control input is consumed but not inserted.
-        //
-        // A typed `|` goes in as `||` — OnChar `0x77c200` pushes the literal at `0x879cac`, which
-        // is `"||"` (decision 1077). That is why real markup can only enter a box through
-        // `SetText`, `Insert`, a paste or the C++ link-insert path: you cannot type an escape, and
-        // the doubled form draws as one `|` and counts as one letter.
+        // A typed `|` goes in as `||` (`0x77c200` pushes the literal `"||"` at `0x879cac`), so
+        // markup cannot be typed; the pair draws as one `|` and counts as one letter.
         insert(lua, h, &text.replace('|', "||"), true);
     }
     true
 }
 
-/// Paste an OS-clipboard string into the focused box. The engine-free runtime can't reach the OS
-/// clipboard itself (RF-0082's stated gap), so the host reads it and hands the text here. Sanitized
-/// the same way a typed char is gated — every C0 control char is dropped, except a newline in a
-/// `multiLine` box — then inserted as one edit (selection-replace + numeric/caps rules via [`insert`],
-/// no `OnSpacePressed` fire: a paste is not a typed space). Always consumes when a box is focused.
+/// Paste host clipboard text into the focused box as one edit: C0 controls are dropped, except a
+/// newline in a `multiLine` box, and no `OnSpacePressed` fires.
 pub(super) fn paste(lua: &Lua, text: &str) -> bool {
     let Some(h) = route(lua) else {
         return false;
     };
-    // The sanitation + insert is the shared law ([`EditBoxState::paste`]); only the event fire is
-    // this layer's.
     if with_eb(lua, h, |eb| eb.paste(text)).is_some_and(|o| o.text_changed) {
         sync_text_region(lua, h);
         mark_text_changed(lua, h);
@@ -103,9 +64,7 @@ pub(super) fn paste(lua: &Lua, text: &str) -> bool {
     true
 }
 
-/// A non-character key by name — only the three *box-event* keys act (their FrameXML scripts);
-/// every editing key reaches the box as a semantic [`EditAction`] via [`action`] instead. Routes
-/// per §1/§2; a focused box consumes the key even when it does nothing with it.
+/// A named key: only Enter, Escape and Tab act, and a focused box consumes every key.
 pub(super) fn key_input(lua: &Lua, key: &str) -> bool {
     let Some(h) = route(lua) else {
         return false;
@@ -120,31 +79,25 @@ pub(super) fn key_input(lua: &Lua, key: &str) -> bool {
                 fire_script(lua, id, "OnEnterPressed");
             }
         }
-        // Escape fires the script but does NOT release focus (FrameXML calls ClearFocus itself).
+        // Escape does not release focus: FrameXML calls ClearFocus itself.
         "ESCAPE" => fire_script(lua, id, "OnEscapePressed"),
         "TAB" => fire_script(lua, id, "OnTabPressed"),
-        // Any other named key: a focused box still consumes it (past the guard), doing nothing.
         _ => {}
     }
     true
 }
 
-/// One semantic editing operation — the host's per-OS keymap output (decision 0301). Same
-/// routing/consumption law as [`key_input`]: the focused (or self-acquiring per §2) box processes
-/// it; no box → not consumed.
+/// One semantic editing operation from the host's per-OS keymap, routed like [`key_input`].
 pub(super) fn action(lua: &Lua, a: EditAction) -> bool {
     let Some(h) = route(lua) else {
         return false;
     };
     match a {
         EditAction::Move { unit, back, extend } => match unit {
-            // No alt-arrow test here: the gate is on the KEY and lives in the host, which declines
-            // the four arrow codes before the chord is ever built (`editbox_alt_arrow_mode`).
-            // Anything reaching this arm was Alt-held or was not an arrow, and the reference moves
-            // the caret for both.
+            // The alt-arrow gate lives in the host (`editbox_alt_arrow_mode`), which declines the
+            // arrow codes before a chord is built.
             EditUnit::Char => move_horizontal(lua, h, !back, extend),
-            // Ctrl/Option picks the word-granular cursor helper (RF-0082 §4: "char- vs
-            // word-granular by the Ctrl check").
+            // Ctrl (Option on macOS) moves by word (the client's Ctrl check, `0x41f8f0(1)`).
             EditUnit::Word => interact::move_word(lua, h, !back, extend),
             EditUnit::Edge => move_to_edge(lua, h, !back, extend),
         },
@@ -154,15 +107,9 @@ pub(super) fn action(lua: &Lua, a: EditAction) -> bool {
             EditUnit::Edge => delete_span(lua, h, |eb| if back { 0 } else { eb.text.len() }),
         },
         EditAction::SelectAll => highlight_text(lua, h, 0, -1),
-        // History recall (the chat box's `historyLines`): prev = older, next = newer, live draft
-        // restored past the newest. Single-line only (benilla's multiLine box has no vertical
-        // caret nav — survey gap — a multiLine box consumes the step inert). The recall chords
-        // are the host keymap's plain Up/Down (rf82's history controller is untraced; decision
-        // 0301). The alt-arrow gate DOES cover them, upstream: UP and DOWN are two of the four
-        // codes it declines, so on a flagged box — which the reference's own chat box is —
-        // history recall is **Alt**+Up/Down and a plain Up/Down turns the camera. This file used
-        // to say the opposite ("`ignoreArrows` does not gate them"), which followed from reading
-        // the flag as consume-but-inert; the §5 corrected both halves.
+        // History recall (`historyLines`): older, newer, then back to the live draft. A multiLine
+        // box consumes it inert (it has no vertical caret movement). On an alt-arrow box, as the
+        // stock chat box is, recall is Alt+Up/Down; the reference's history controller is untraced.
         EditAction::HistoryPrev | EditAction::HistoryNext => {
             if !with_eb(lua, h, |eb| eb.multi_line).unwrap_or(false) {
                 history_step_key(lua, h, a == EditAction::HistoryPrev);
@@ -172,9 +119,8 @@ pub(super) fn action(lua: &Lua, a: EditAction) -> bool {
     true
 }
 
-// The mouse/selection interaction law (click→index, drag-select, clipboard, blink) — a child
-// module over this file's focus/editing primitives (RF-0082 §1/§4 + the diffed mouse leaves) —
-// and the host-facing seam (`impl UiScript`: the advance round trip + text-UI geometry).
+// Mouse, selection, clipboard and blink (`interact`); the host's advance round trip and text
+// geometry (`seam`).
 mod interact;
 mod seam;
 pub(super) use interact::{
@@ -182,17 +128,12 @@ pub(super) use interact::{
 };
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Focus model (RF-0082 §1)
+// Focus model
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Resolve the box that should process this key/char event, self-acquiring per §2 if needed.
-///
-/// - A live, effectively-visible focused box → process it.
-/// - A focused box that is hidden (still alive) → `None`: the client's guard returns 0 and the focus
-///   global stays set, so no other box self-acquires while it "holds" focus.
-/// - A focused handle that went stale → cleared, then fall through to self-acquire.
-/// - No focus → the topmost effectively-visible `autoFocus` EditBox self-acquires (firing
-///   `OnEditFocusGained`) and processes this same event; otherwise `None` (not consumed).
+/// The box that processes a key or char. A hidden focused box blocks self-acquire (the client's
+/// guard returns 0 with the focus still set); with no focus, the topmost visible `autoFocus` box
+/// takes it and processes this same event.
 fn route(lua: &Lua) -> Option<FrameHandle> {
     {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -209,8 +150,7 @@ fn route(lua: &Lua) -> Option<FrameHandle> {
     Some(h)
 }
 
-/// The topmost-drawn effectively-visible `autoFocus` EditBox (the keyboard self-acquire target), or
-/// `None`. Walks the draw order top-down like [`crate::order::hit_test`].
+/// The topmost-drawn visible `autoFocus` EditBox, the keyboard self-acquire target.
 fn topmost_autofocus(lua: &Lua) -> Option<FrameHandle> {
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     let sorted = order::traversal(&model.arena);
@@ -226,12 +166,9 @@ fn topmost_autofocus(lua: &Lua) -> Option<FrameHandle> {
     None
 }
 
-/// `SetFocus` (`0x77e3d0`): gate on effective-visibility, no-op if already focused; else fire
-/// `OnEditFocusLost` on the old box, move focus, fire `OnEditFocusGained` on the new.
-///
-/// `0x77e3f6` (inside this) is the ONLY instruction image-wide that grants a box the focus, and it
-/// writes no selection field — so every focus gain in the client, whatever triggers it, is
-/// selection-neutral.
+/// `SetFocus` (`0x77e3d0`): needs effective visibility, a no-op when already focused; fires
+/// `OnEditFocusLost` on the old box, then `OnEditFocusGained`. Its store at `0x77e3f6` is the
+/// client's only focus grant and writes no selection, so no focus gain changes the selection.
 fn set_focus_handle(lua: &Lua, h: FrameHandle) {
     let (old_id, new_id) = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -244,9 +181,7 @@ fn set_focus_handle(lua: &Lua, h: FrameHandle) {
         }
         let old = model.focused_editbox;
         model.focused_editbox = Some(h);
-        // A fresh focus starts a fresh history session: the browse position must not leak from
-        // the box's previous open (programmatic SetText deliberately preserves it — the chat
-        // live parse's recall rewrite — so this is where a stale walk gets dropped).
+        // A focus gain ends history browsing (`SetText` keeps it for the chat parser's rewrite).
         if let Some(KindState::EditBox(eb)) = model.arena.frame_mut(h).map(|f| &mut f.kind_state) {
             eb.end_history_browse();
         }
@@ -258,23 +193,13 @@ fn set_focus_handle(lua: &Lua, h: FrameHandle) {
     fire_script(lua, new_id, "OnEditFocusGained");
 }
 
-/// The EditBox's own **OnShow/OnHide vtable overrides** (`0x81c910` slots +0x30/+0x34), run by
-/// [`crate::script::event::fire_visibility_changes`] after the frame's Lua handler — the order the
-/// reference has, since both overrides call the base notify *first* and only then act.
-///
-/// - **Show** (`0x77a750`): `if ([0xcf4dc8] == 0 && (flags & 1)) SetFocus(this)` — an `autoFocus`
-///   box grabs the keyboard when it appears, **iff nothing else holds it**. Not a
-///   "topmost/best" choice: whichever box's show runs first while the focus is free takes it.
-/// - **Hide** (`0x77a780`): tail-jumps `ClearFocus`, whose own guard makes it per-box — hiding a
-///   box that does not hold the keyboard writes nothing and fires nothing.
-///
-/// Both were missing until 2026-08-29 (decision 1686). wow-re had published "autoFocus does NOT
-/// focus on show — VERIFIED by enumerating callers" off a census written over `call` alone, which
-/// cannot see the override's tail-`jmp`; benilla had transcribed the negative.
+/// The EditBox's OnShow/OnHide vtable overrides (`0x81c910` slots +0x30/+0x34), run after the
+/// frame's Lua handler, since both call the base notify first. Show (`0x77a750`) focuses an
+/// `autoFocus` box when nothing holds the focus, first come first served; hide (`0x77a780`)
+/// tail-jumps `ClearFocus`.
 pub(super) fn visibility_focus(lua: &Lua, h: FrameHandle, visible: bool) {
     if !visible {
-        // The guard lives in `clear_focus_handle`, exactly as it does in `0x77e410` — so this is
-        // called unconditionally here, like the reference's own unconditional tail-jmp.
+        // Unconditional, like the reference's tail-jump: the guard is in `clear_focus_handle`.
         clear_focus_handle(lua, h);
         return;
     }
@@ -287,14 +212,13 @@ pub(super) fn visibility_focus(lua: &Lua, h: FrameHandle, visible: bool) {
             )
     };
     if wants {
-        // `SetFocus` re-checks effective-visibility itself, which is the reference's gate too.
+        // `SetFocus` checks effective visibility itself.
         set_focus_handle(lua, h);
     }
 }
 
-/// `ClearFocus` (`0x77e410`): only if this box holds focus; fire `OnEditFocusLost`. The guard is
-/// `mov eax,ecx; mov ecx,[0xcf4dc8]; cmp ecx,eax; jne ret` — verified per-box, which is what makes
-/// the OnHide override's *unconditional* tail-jmp into it harmless.
+/// `ClearFocus` (`0x77e410`): only when this box holds the focus (`[0xcf4dc8]`), then fires
+/// `OnEditFocusLost`.
 fn clear_focus_handle(lua: &Lua, h: FrameHandle) {
     let id = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -308,12 +232,11 @@ fn clear_focus_handle(lua: &Lua, h: FrameHandle) {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Editing primitives (RF-0082 §3/§4) — mutate state under one borrow, then sync + fire
+// Editing primitives: mutate under one borrow, then sync and fire
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Insert `ins` at the cursor (`0x77bee0`): replace any selection first; `numeric` aborts wholesale on
-/// a non-digit; splice + advance; enforce caps; fire `OnTextChanged`, and (when `fire_space`) one
-/// `OnSpacePressed` per space in `ins`.
+/// `Insert` (`0x77bee0`): replace the selection, abort on a non-digit when `numeric`, splice,
+/// enforce caps, mark `OnTextChanged`, and with `fire_space` fire one `OnSpacePressed` per space.
 fn insert(lua: &Lua, h: FrameHandle, ins: &str, fire_space: bool) {
     let Some(out) = with_eb(lua, h, |eb| eb.insert(ins)) else {
         return; // not an EditBox
@@ -323,22 +246,15 @@ fn insert(lua: &Lua, h: FrameHandle, ins: &str, fire_space: bool) {
     }
     sync_text_region(lua, h);
     let id = frame_id_of(lua, h);
-    // **The EditBox DOES fire generic `OnChar`** — with the spliced string as `arg1`, from inside
-    // Insert itself (`0x77c13c`, the varargs firer `0x7026f0` with fmt `"%s"`), before the dirty
-    // flush gets round to `OnTextChanged`. RF-0082's "never generic `OnKeyDown`/`OnChar`" was
-    // scoped to one member of a two-member fire family and missed the varargs half; the
-    // `OnKeyDown` (`+0x188`) half of that claim stands (wow-re, corrected 2026-08-29). It rides
-    // the one choke point every insert path goes through — typed char, the `|`→`||` escape, the
-    // multiLine Enter newline, the Lua `Insert` — and so is absent from `SetText`, which is where
-    // the reference has it absent too.
+    // Insert fires the generic `OnChar` with the spliced string as `arg1` (`0x77c13c`, through the
+    // varargs firer `0x7026f0`), before the deferred `OnTextChanged`; `SetText` does not.
     let on_char = lua
         .create_string(ins)
         .and_then(|s| event::fire_widget_handler(lua, id, "OnChar", vec![mlua::Value::String(s)]));
     if let Err(e) = on_char {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
     mark_text_changed(lua, h);
     if fire_space {
@@ -348,8 +264,8 @@ fn insert(lua: &Lua, h: FrameHandle, ins: &str, fire_space: bool) {
     }
 }
 
-/// `SetText` (`0x77be00`): short-circuit when unchanged (no events); else clear selection, replace,
-/// cursor to end, enforce caps, fire `OnTextSet` then `OnTextChanged`.
+/// `SetText` (`0x77be00`): nothing when unchanged; else clear the selection, replace, cursor to
+/// the end, enforce caps, fire `OnTextSet` and mark `OnTextChanged`.
 fn set_text(lua: &Lua, h: FrameHandle, s: &str) {
     let changed = with_eb(lua, h, |eb| eb.set_text(s));
     if changed == Some(true) {
@@ -360,9 +276,8 @@ fn set_text(lua: &Lua, h: FrameHandle, s: &str) {
     }
 }
 
-/// Word/edge deletes (`Delete{Word,Edge}` — no 1.12 counterpart; the OS-native keymap family):
-/// the selection first when one exists, else the span from the cursor to `target_of(eb)`; sync +
-/// `OnTextChanged` when anything was removed.
+/// Word and edge deletes (no 1.12 counterpart): the selection if any, else the cursor to
+/// `target_of(eb)`.
 fn delete_span(lua: &Lua, h: FrameHandle, target_of: impl FnOnce(&EditBoxState) -> usize) {
     let changed = with_eb(lua, h, |eb| {
         let t = target_of(eb);
@@ -374,8 +289,7 @@ fn delete_span(lua: &Lua, h: FrameHandle, target_of: impl FnOnce(&EditBoxState)
     }
 }
 
-/// BACKSPACE / DELETE: delete the selection if non-empty, else the char before (`forward=false`) or
-/// after (`forward=true`) the cursor; fire `OnTextChanged` if anything was removed.
+/// Backspace and Delete: the selection if any, else one char before or after the cursor.
 fn delete_dir(lua: &Lua, h: FrameHandle, forward: bool) {
     let changed = with_eb(lua, h, |eb| eb.delete_dir(forward));
     if changed == Some(true) {
@@ -384,10 +298,8 @@ fn delete_dir(lua: &Lua, h: FrameHandle, forward: bool) {
     }
 }
 
-/// One UP/DOWN history-recall step: ask the state for the line to show and route it through the
-/// internal `set_text` path (region sync + `OnTextSet`/`OnTextChanged` — a recall resets FrameXML
-/// tab-complete state exactly like any other text change). `set_text` (internal AND Lua) leaves
-/// the browse position intact; typed edits, `AddHistoryLine`, and focus gain end browsing.
+/// One history-recall step through `set_text`, so a recall fires `OnTextSet` like any text change.
+/// `set_text` keeps the browse position; typing, `AddHistoryLine` and a focus gain end it.
 fn history_step_key(lua: &Lua, h: FrameHandle, older: bool) {
     let recalled = with_eb(lua, h, |eb| eb.history_step(older)).flatten();
     if let Some(text) = recalled {
@@ -395,30 +307,26 @@ fn history_step_key(lua: &Lua, h: FrameHandle, older: bool) {
     }
 }
 
-/// LEFT/RIGHT one char: `shift` extends the selection from the fixed anchor; otherwise the caret
-/// collapses to the selection edge (if any) or moves one char. Fires no script (a cursor/selection
-/// move; `OnCursorChanged` geometry is out of scope).
+/// Left/Right: `shift` extends from the anchor, else collapse the selection or move one char.
 fn move_horizontal(lua: &Lua, h: FrameHandle, right: bool, shift: bool) {
     with_eb(lua, h, |eb| eb.move_by_char(right, shift));
 }
 
-/// HOME/END: move the caret to 0 / `len`; `shift` extends from the fixed anchor.
+/// Home/End; `shift` extends from the anchor.
 fn move_to_edge(lua: &Lua, h: FrameHandle, end: bool, shift: bool) {
     with_eb(lua, h, |eb| eb.move_to_edge(end, shift));
 }
 
-/// `HighlightText` (`0x77cca0`), the client's exact clamp: `start = clamp(start, 0..=len)`;
-/// `end = (end < 0 || end > len) ? len : end`; then `if end < start { end = len }` — so `(0, -1)`
-/// selects all. Offsets are bytes, snapped to char boundaries.
+/// `HighlightText` (`0x77cca0`): `start = clamp(start, 0..=len)`; `end = (end < 0 || end > len) ?
+/// len : end`; then `if end < start { end = len }`, so `(0, -1)` selects all. Offsets are bytes,
+/// snapped to char boundaries.
 fn highlight_text(lua: &Lua, h: FrameHandle, start: i64, end: i64) {
     with_eb(lua, h, |eb| eb.highlight_text(start, end));
 }
 
-// ── text-region sync (the '*' mask lives here, RF-0082 §3) ───────────────────────────────────
+// ── text-region sync ─────────────────────────────────────────────────────────────────────────
 
-/// Write the *display* string into the text region's [`RegionData::text`], creating the region lazily
-/// (the implicit FontString) if none exists. `password` shows one `'*'` per **character** (the mask,
-/// never the real text).
+/// Write the display string into the text region; a `password` box shows one `*` per character.
 fn sync_text_region(lua: &Lua, h: FrameHandle) {
     let Some(rh) = ensure_text_region(lua, h) else {
         return;
@@ -437,10 +345,7 @@ fn sync_text_region(lua: &Lua, h: FrameHandle) {
     }
 }
 
-/// `SetTextInsets(l, r, t, b)`: store the insets and re-anchor the text region inside the box by
-/// them (y-up: the top inset pulls the region's top DOWN, the bottom inset pulls its bottom UP).
-/// The chat edit box calls this per header change (`ChatEdit_UpdateHeader`'s
-/// `SetTextInsets(15 + headerWidth, 13, 0, 0)`), so typed text starts past the "Say:" header.
+/// `SetTextInsets(l, r, t, b)`: store the insets and re-anchor the text region by them.
 fn set_text_insets(lua: &Lua, h: FrameHandle, l: f32, r: f32, t: f32, b: f32) {
     if with_eb(lua, h, |eb| eb.text_insets = [l, r, t, b]).is_none() {
         return;
@@ -451,8 +356,8 @@ fn set_text_insets(lua: &Lua, h: FrameHandle, l: f32, r: f32, t: f32, b: f32) {
     write_inset_anchors(lua, h, rh, [l, r, t, b]);
 }
 
-/// Anchor the text region inside its box by the insets — the two corner anchors that pin its rect
-/// (y-up: the top inset pulls the region's top DOWN, the bottom inset pulls its bottom UP).
+/// Pin the text region's corners inside the box by the insets (y-up: the top inset moves its top
+/// down, the bottom inset its bottom up).
 fn write_inset_anchors(lua: &Lua, h: FrameHandle, rh: RegionHandle, [l, r, t, b]: [f32; 4]) {
     let owner = frame_id_of(lua, h);
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -473,14 +378,9 @@ fn write_inset_anchors(lua: &Lua, h: FrameHandle, rh: RegionHandle, [l, r, t, b]
     }
 }
 
-/// The wrapper for an EditBox's **embedded** text FontString — the region its ctor built at
-/// `0x779bee` (`Arena::build_editbox_engine_regions`). `None` when `frame` is not a live EditBox.
-///
-/// The loader's special-`<FontString>` pass uses this instead of `CreateFontString`: RF-0028 lists
-/// `<FontString>` as the EditBox's *embedded* font string (its `bytes` attr writes the box's own
-/// `maxBytes`), so the element DECLARES the ctor's object rather than adding a region. Creating a
-/// second one would leave an orphan on the frame and push the authored `<Layers>` regions one place
-/// down the creation-ordered list `GetRegions` walks.
+/// The wrapper for an EditBox's embedded text FontString, built by its ctor (`0x779bee`). The
+/// loader uses it for `<FontString>`: the reference's EditBox LoadXML (`0x779fb0`) declares the
+/// ctor's font string rather than adding a region (its `bytes` sets the box's `maxBytes`).
 pub(crate) fn editbox_text_region_wrapper(lua: &Lua, frame: &Table) -> Option<Table> {
     let h = frame_handle_of(lua, frame).ok()?;
     let rh = ensure_text_region(lua, h)?;
@@ -491,10 +391,8 @@ pub(crate) fn editbox_text_region_wrapper(lua: &Lua, frame: &Table) -> Option<Ta
     super::region::region_wrapper(lua, id).ok()
 }
 
-/// The loader's special-`<FontString>` slot assignment: adopt `region` as `frame`'s text region,
-/// anchored by the current insets. The engine ASSIGNS an EditBox's font string at LoadXML — it
-/// never searches the region list (a find-first here once grabbed a `<Layers>` FontString, the
-/// chat header, so typing overwrote "Say:" and the insets clobbered the header's anchor).
+/// Adopt `region` as `frame`'s text region, anchored by the current insets: LoadXML assigns an
+/// EditBox's font string, never searching the region list.
 pub(crate) fn adopt_text_region(lua: &Lua, frame: &Table, region: &Table) -> mlua::Result<()> {
     let h = frame_handle_of(lua, frame)?;
     let rh = super::region::region_handle_of(lua, region)?;
@@ -502,11 +400,10 @@ pub(crate) fn adopt_text_region(lua: &Lua, frame: &Table, region: &Table) -> mlu
         eb.text_region = Some(rh);
         (eb.text_insets, eb.multi_line)
     }) else {
-        return Ok(()); // not an EditBox — the loader guards on the tag, but stay safe
+        return Ok(()); // not an EditBox
     };
     write_inset_anchors(lua, h, rh, insets);
-    // A live text region always carries Some(text) — an empty box still emits its Text quad, so
-    // the host's caret has a styled quad to ride before the first keystroke.
+    // Always `Some` text: an empty box still emits its Text quad for the host's caret.
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let data = model.region_data.entry(rh).or_default();
     data.text.get_or_insert_with(String::new);
@@ -514,36 +411,31 @@ pub(crate) fn adopt_text_region(lua: &Lua, frame: &Table, region: &Table) -> mlu
     Ok(())
 }
 
-/// Get-or-create the implicit text FontString (the EditBox's ButtonText analogue). Returns `None` if
-/// `h` is not a live EditBox. An XML-declared `<FontString>` is wired explicitly by the loader's
-/// special pass ([`adopt_text_region`]); the lazy create covers CreateFrame'd boxes.
+/// Get or create the box's text FontString; an XML-declared one is wired by [`adopt_text_region`].
 pub(super) fn ensure_text_region(lua: &Lua, h: FrameHandle) -> Option<RegionHandle> {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let (existing, multi_line) = match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::EditBox(eb)) => (eb.text_region, eb.multi_line),
         _ => return None,
     };
-    // The ctor already built it (`Arena::build_editbox_engine_regions` — the client's own
-    // `0x779bee`, the first of the five regions a CSimpleEditBox is born with). The REGION exists
-    // from birth; its `RegionData` does not, because the arena has no access to it — so seed that
-    // here, once, on whichever call arrives first.
+    // The ctor built the region (`0x779bee`, the first of a CSimpleEditBox's five regions); its
+    // `RegionData` is seeded here, on the first call.
     let rh = match existing {
         Some(rh) => rh,
-        // A box whose ctor pass could not run (a dead handle, or a non-EditBox that slipped the
-        // guard above) still gets a region rather than silently rendering nothing.
+        // A box whose ctor pass did not run still gets a region.
         None => model
             .arena
             .create_region(h, RegionKind::FontString, DrawLayer::Overlay, 0)?,
     };
     if let std::collections::hash_map::Entry::Vacant(slot) = model.region_data.entry(rh) {
         let mut data = RegionData {
-            // Some("") from birth — the empty box still emits its Text quad for the host caret.
+            // Some("") from birth: the empty box still emits its Text quad for the host caret.
             text: Some(String::new()),
             ..RegionData::default()
         };
         apply_text_region_justify(&mut data, multi_line);
         slot.insert(data);
-        model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+        model.touch_layout(); // a region entered the layout gate's read set
     }
     if let Some(KindState::EditBox(eb)) = model.arena.frame_mut(h).map(|f| &mut f.kind_state) {
         eb.text_region = Some(rh);
@@ -551,10 +443,8 @@ pub(super) fn ensure_text_region(lua: &Lua, h: FrameHandle) -> Option<RegionHand
     Some(rh)
 }
 
-/// Re-seat an already-wired text region's justify by the box's CURRENT multiLine flag — the
-/// `SetMultiLine` rider: the loader adopts the declared `<FontString>` (LoadXML step 5·b) before
-/// it applies the editbox flags (5b), so `multiLine="true"` must re-run the law or the body box
-/// keeps the single-line MIDDLE seat.
+/// Re-apply the text region's justify for the current `multiLine` flag: LoadXML adopts the
+/// `<FontString>` before it applies the box's flags.
 pub(super) fn refresh_text_region_justify(lua: &Lua, this: &Table) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -568,12 +458,8 @@ pub(super) fn refresh_text_region_justify(lua: &Lua, this: &Table) -> mlua::Resu
     Ok(())
 }
 
-/// The EditBox text-anchoring law: the box's text region lays out LEFT-justified (the client's
-/// editbox draw `0x77da80` is left-anchored at the insets rect regardless of the font string's
-/// declared justification — RF-0082's windowed draw, focused or not), from the TOP for a
-/// multiline box, vertically centered for a single-line one. Without this, a bare
-/// `<FontString inherits="ChatFontNormal"/>` inherits the FontString CENTER/MIDDLE defaults and
-/// an empty focused box parks its caret mid-box (the mail send tab's original sin).
+/// Left-justified whatever the font string declares (the draw `0x77da80` anchors left at the
+/// insets), from the top in a multiLine box and vertically centered otherwise.
 fn apply_text_region_justify(data: &mut RegionData, multi_line: bool) {
     data.justify.set_h(crate::script::JustifyH::Left);
     data.justify.set_v(if multi_line {
@@ -594,7 +480,6 @@ fn with_eb<T>(lua: &Lua, h: FrameHandle, f: impl FnOnce(&mut EditBoxState) -> T)
     }
 }
 
-/// The stable id of a frame handle (minting one if needed).
 fn frame_id_of(lua: &Lua, h: FrameHandle) -> u32 {
     lua.app_data_mut::<Model>()
         .expect("model app_data")
@@ -606,41 +491,20 @@ fn fire_script(lua: &Lua, id: u32, name: &str) {
     if let Err(e) = event::fire_widget_handler(lua, id, name, Vec::new()) {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
 }
 
-/// **The caret flush's fire — `OnCursorChanged(x, y, w, h)`** (`0x77da80`).
+/// `OnCursorChanged(x, y, w, h)` from the caret flush (`0x77da80`, in UI units via `0x77dd5f`): `x`
+/// is the caret's advance along its line, `y` minus the row index times the row pitch, `w` the
+/// constant 4.0 and `h` the line height. It fires only when the caret moved: the flush's one
+/// caller, `0x77d475`, is gated on dirty bit 2.
 ///
-/// The reference recomputes the caret's anchor inside `0x77da80` and, having done so, fires this
-/// with four floats *"each value scaled by `f`, so all four are in FrameXML UI units"* (wow-re
-/// `system/ui/ui.md`, the RF-0085 caret law, VERIFIED):
+/// Deviation: `h` is the row pitch, which is taller than the line height only for a font with
+/// extra spacing (none in the stock UI), because the host's advance answer carries one measure.
 ///
-/// * `x` — the caret's advance from its line's start, the same number the paint anchors by
-///   ([`EditBoxState::caret_row_x`]).
-/// * `y` — `−lineIndex · (snap(H·scale) + snap(spacing·scale))/scale`, i.e. minus the row index
-///   times the row pitch. **Negative-downward**, which is what `ScrollingEdit_OnCursorChanged`'s
-///   `cursorOffset = y` then `-this.cursorOffset` reads as a positive distance down the page.
-/// * `w` — **`≡ 4.0`**, a constant in the reference (the caret texture's own width, read through
-///   its layout vtable `+0x1c`).
-/// * `h` — the font line height, read through `+0x20`.
-///
-/// Ours takes the row pitch [`EditBoxState::cell_h`] for both the `y` factor and `h`. The two are
-/// the same number whenever the font declares no extra `spacing`, which is every box in the
-/// shipped 1.12 UI; a box that *does* set spacing would report an `h` a little tall. Named rather
-/// than guessed at — the alternative is carrying a second measured number through the advance
-/// answer for a case nothing in the corpus produces.
-///
-/// **The edge is a CHANGE, not a frame.** `0x77da80` has exactly one caller, `0x77d475`, gated on
-/// dirty bit 2, so the handler runs when the caret has actually moved — which is what makes
-/// `ScrollingEdit_OnUpdate`'s `if (this.cursorOffset)` idiom terminate. [`EditBoxState::cursor_fired`]
-/// is that bit's memory here.
-///
-/// **Scoped to the focused box**, because the caret geometry rides the advance table and only the
-/// focused box asks the host for one ([`super::editbox::seam`]). The reference flushes any dirty
-/// box; the difference is invisible for the customer this exists for — you are typing in the box
-/// you are looking at — and an unfocused box's caret is never drawn either way.
+/// Deviation: only the focused box fires, where the reference flushes any dirty box, because only
+/// the focused box gets an advance table from the host.
 pub(in crate::script) fn drain_cursor_changed(lua: &Lua) {
     let fire = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -655,8 +519,7 @@ pub(in crate::script) fn drain_cursor_changed(lua: &Lua) {
         else {
             return;
         };
-        // No answered advance table yet ⇒ no caret geometry to report. The next tick after the
-        // host answers carries it, exactly as the reference's next flush would.
+        // No advance table yet: the tick after the host answers reports it.
         let display = eb.display();
         if eb.advances.len() != display.len() + 1 {
             return;
@@ -692,28 +555,19 @@ pub(in crate::script) fn drain_cursor_changed(lua: &Lua) {
     }
 }
 
-/// The caret's width as `OnCursorChanged` reports it — **a constant in the reference**, not a
-/// measurement (wow-re: `w ≡ 4.0`).
+/// The caret width `OnCursorChanged` reports, a constant in the reference.
 const CARET_WIDTH: f32 = 4.0;
 
-// The Lua method surface (SetText/GetText/HighlightText/SetFocus/…, consulted before the shared
-// frame table only for EditBox frames) — a child module over this file's focus/editing
-// primitives, like `interact`/`seam`.
+// The EditBox Lua methods, consulted before the shared frame table for EditBox frames.
 mod methods;
 pub(super) use methods::install;
 
 #[cfg(test)]
 mod tests;
 
-/// Raise the `textChanged` dirty bit (`[E+0x31c]` bit 0) rather than firing — **`OnTextChanged` is
-/// deferred**, and this is the whole of decision 1831's second half.
-///
-/// The reference never fires it from an edit. `SetText 0x77be00`, `Insert 0x77bee0` and the deletes
-/// all only OR the bit; the single fire site is `0x77d498`, inside the dirty-word drain `0x77d3e0`,
-/// whose three callers are the box's own `OnUpdate` (`0x77a790`), its `OnKeyDown` (`0x77b160`) and
-/// its `OnMouseDown` (`0x77b800`). So a Lua caller gets control back with the handler still
-/// unrun, and repeated changes **coalesce**: the box appears once on the pending list however many
-/// times it is written, and the one fire carries the final text.
+/// Raise the `textChanged` dirty bit (`[E+0x31c]` bit 0): the reference's edits only mark it, and
+/// its one fire site (`0x77d498`) is in the drain `0x77d3e0`, so a Lua caller gets control back
+/// before the handler runs and repeated changes coalesce into one fire with the final text.
 pub(super) fn mark_text_changed(lua: &Lua, h: FrameHandle) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     if !model.dirty_editboxes.contains(&h) {
@@ -721,21 +575,14 @@ pub(super) fn mark_text_changed(lua: &Lua, h: FrameHandle) {
     }
 }
 
-/// The dirty-word drain (`0x77d3e0`): fire the pending `OnTextChanged`s.
+/// The dirty-word drain (`0x77d3e0`): fire the pending `OnTextChanged`s from the frame tick, as the
+/// box's `OnUpdate` (`0x77a790`) does. A hidden box stays pending until shown: `Hide` unlinks it
+/// from the update chain (that it then gets no `OnUpdate` is inferred). The list is taken before
+/// any Lua runs, so a box a handler re-marks fires on the next drain, as the reference clears its
+/// bit before the fire.
 ///
-/// Called from the frame tick — the first of the reference's three callers (`0x77a7a1`, inside the
-/// box's own `OnUpdate` `0x77a790`, which is also where our caret blink lives). Its other two, the
-/// box's `OnKeyDown` and `OnMouseDown`, are **not** wired: they only make a pending fire arrive
-/// sooner within a frame, and our key and mouse paths reach the tick anyway. Decision 1831 says so
-/// out loud rather than leaving it to be discovered.
-///
-/// A box that is **not effectively visible stays pending**: `Hide`
-/// splices it out of the chain the update walk follows, so its fire waits for a `Show` (verified
-/// chain mechanics; the "hidden ⇒ no OnUpdate" step is the RE's own stated inference).
-///
-/// A handler may itself write to a box — including this one — so the list is taken before any Lua
-/// runs and anything re-marked during the sweep lands on the NEXT drain rather than extending this
-/// one. That is the reference's shape too: its bit is cleared before its fire.
+/// Deviation: not drained from `OnKeyDown` (`0x77b160`) or `OnMouseDown` (`0x77b800`), because
+/// those only bring the fire sooner within a frame and our key and mouse paths reach the tick.
 pub(in crate::script) fn drain_text_changed(lua: &Lua) {
     let pending = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
diff --git a/crates/benilla-ui/src/script/editbox/interact.rs b/crates/benilla-ui/src/script/editbox/interact.rs
index 616614cb..c1b4b093 100644
--- a/crates/benilla-ui/src/script/editbox/interact.rs
+++ b/crates/benilla-ui/src/script/editbox/interact.rs
@@ -1,20 +1,4 @@
-//! The EditBox mouse/selection interaction law — click→char-index, drag-select, the clipboard
-//! pair, and the caret blink — a child module over the mother's focus/editing primitives.
-//!
-//! Byte law (RF-0082 §1/§4 + the diffed leaves quoted in wow-re's `rf82-editbox-runtime.md`):
-//!
-//! - **Click `0x77b800`**: on a hit — blink reset, click→index (`0x77d0d0`) places the cursor and
-//!   collapses the selection, the drag flag raises (`E+0x364 = 1`), then `SetFocus`
-//!   UNCONDITIONALLY. No shift+click branch exists in the handler (INFERRED by absence — 1.12
-//!   predates extend-on-click).
-//! - **Drag `0x77a860`** (mouse move while `+0x364`): map x→index, extend the selection there via
-//!   the same helper Shift+arrow uses (`0x77cd10`), cursor following.
-//! - **Release** (`0x77afc0` case 1): `+0x364 = 0`.
-//! - **Clipboard** (§4): Ctrl+C/X act only with a non-empty selection (`0x77e1d0`); X then
-//!   deletes = cut. A password box copies a FIXED placeholder (`0x882748`, runtime literal
-//!   unresolved — flagged live-capture), never the real text; benilla stands in the mask run.
-//! - **Blink `0x77a790`**: the focused box's accumulator (`E+0x374`) advances by dt; crossing the
-//!   period (`E+0x370`, ctor default 0.5 s) toggles the caret and zeroes the accumulator.
+//! EditBox mouse and clipboard interaction: click, drag-select, copy, cut and the caret blink.
 
 use mlua::Lua;
 
@@ -22,13 +6,10 @@ use super::{set_focus_handle, sync_text_region, with_eb};
 use crate::script::Model;
 use crate::widget::{FrameHandle, FrameKind, KindState};
 
-/// Map a screen point (the engine's y-up UI space — the same space resolved rects and the
-/// pointer API live in) to the box's TEXT byte index: x relative to the text region's left edge,
-/// shifted into advance space by the scroll window's origin, nearest char boundary (`0x77d0d0`;
-/// the rounding is INFERRED nearest). A multiline box also reads y — px down from the region's
-/// top pick the wrapped row ([`crate::widget::EditBoxState::index_at_pos`]). Ends up at
-/// end-of-text while the advance table is unanswered — the pre-seam behavior, degrading
-/// gracefully.
+/// A UI-space point (y up) to the box's text byte index at the nearest cursor stop (`0x77d0d0`,
+/// whose own rounding is untraced): x from the text region's left edge plus the scroll origin, and
+/// in a multi-line box y from its top picks the wrapped row. The end of the text until the advance
+/// table is answered.
 fn index_at_screen_pos(lua: &Lua, h: FrameHandle, x: f32, y: f32) -> usize {
     let corner = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -36,8 +17,7 @@ fn index_at_screen_pos(lua: &Lua, h: FrameHandle, x: f32, y: f32) -> usize {
             Some(KindState::EditBox(eb)) => eb.text_region,
             _ => None,
         };
-        // The text region's resolved corner; an unanchored region (no insets) draws over its
-        // owner, so the frame's own edges stand in.
+        // An unanchored text region draws over its owner, so the frame's own corner stands in.
         rh.and_then(|rh| model.region_resolved.get(&rh))
             .or_else(|| model.resolved.get(&h))
             .map(|r| (r.left, r.top))
@@ -53,8 +33,8 @@ fn index_at_screen_pos(lua: &Lua, h: FrameHandle, x: f32, y: f32) -> usize {
     .unwrap_or(0)
 }
 
-/// A LeftButton press landed on frame `id` (`0x77b800`): if it is an EditBox — blink reset, the
-/// cursor to the clicked char (collapsing any selection), drag begins, focus UNCONDITIONALLY.
+/// A LeftButton press on EditBox `id` (`0x77b800`) places the cursor at the clicked char,
+/// collapsing the selection, starts a drag and takes focus unconditionally; no shift+click branch.
 pub(in crate::script) fn click(lua: &Lua, id: u32, x: f32, y: f32) {
     let Some(h) = editbox_of(lua, id) else { return };
     let idx = index_at_screen_pos(lua, h, x, y);
@@ -65,8 +45,8 @@ pub(in crate::script) fn click(lua: &Lua, id: u32, x: f32, y: f32) {
     set_focus_handle(lua, h);
 }
 
-/// Mouse move while the press is held (`0x77a860`): the focused, drag-active box extends its
-/// selection to the hovered index; the cursor follows.
+/// Mouse move with the button held (`0x77a860`): a dragging focused box extends its selection to
+/// the hovered index through the Shift+arrow helper (`0x77cd10`).
 pub(in crate::script) fn drag_update(lua: &Lua, x: f32, y: f32) {
     let Some(h) = focused(lua) else { return };
     if with_eb(lua, h, |eb| eb.drag_active) != Some(true) {
@@ -80,30 +60,27 @@ pub(in crate::script) fn drag_update(lua: &Lua, x: f32, y: f32) {
     });
 }
 
-/// The press released (`0x77afc0` case 1): the drag ends. Fires for any release — a box that
-/// never started a drag ignores it.
+/// Any button release ends the drag (`0x77afc0` case 1).
 pub(in crate::script) fn drag_end(lua: &Lua) {
     if let Some(h) = focused(lua) {
         with_eb(lua, h, |eb| eb.drag_active = false);
     }
 }
 
-/// Ctrl+LEFT/RIGHT — the word-granular cursor move (§4's Ctrl branch; the client walks its
-/// per-byte class array, benilla's alnum-run approximation is INFERRED): `shift` extends the
-/// selection from the fixed anchor like the char move; else the caret collapses there.
+/// Ctrl+Left/Right, the word move: the client walks its per-byte class array (`0x41f8f0(1)`),
+/// benilla stops at alphanumeric runs. `shift` extends the selection from its anchor.
 pub(in crate::script) fn move_word(lua: &Lua, h: FrameHandle, right: bool, shift: bool) {
     with_eb(lua, h, |eb| eb.move_by_word(right, shift));
 }
 
-/// Ctrl+C (`0x77e1d0`): the focused box's selected substring, `None` with no selection. A
-/// password box yields the mask run — the client copies a fixed placeholder, NEVER the text.
+/// Ctrl+C (`0x77e1d0`): the focused box's selection. A password box never yields its text: the
+/// client copies the image's empty string (`0x882748`), benilla the mask run.
 pub(in crate::script) fn copy_selection(lua: &Lua) -> Option<String> {
     let h = focused(lua)?;
     with_eb(lua, h, |eb| eb.selected_text()).flatten()
 }
 
-/// Ctrl+X: copy, then delete the selection (an ordinary edit — the region syncs and
-/// `OnTextChanged` fires).
+/// Ctrl+X (`0x77e1d0`): copy, then delete the selection as an ordinary edit.
 pub(in crate::script) fn cut_selection(lua: &Lua) -> Option<String> {
     let h = focused(lua)?;
     let copied = with_eb(lua, h, |eb| eb.cut_selection()).flatten()?;
@@ -112,9 +89,8 @@ pub(in crate::script) fn cut_selection(lua: &Lua) -> Option<String> {
     Some(copied)
 }
 
-/// The blink tick (`0x77a790`, run from the host's frame tick): the focused box's accumulator
-/// advances; crossing the period toggles the caret and resets. Non-positive period never blinks
-/// (a solid caret).
+/// The caret blink (`0x77a790`), each frame: past the period (0.5 s by default) the focused box's
+/// caret toggles and the accumulator resets; a non-positive period keeps the caret solid.
 pub(in crate::script) fn tick_blink(lua: &Lua, dt: f32) {
     if let Some(h) = focused(lua) {
         with_eb(lua, h, |eb| {
@@ -129,14 +105,12 @@ pub(in crate::script) fn tick_blink(lua: &Lua, dt: f32) {
     }
 }
 
-/// The focused EditBox handle, if any.
 fn focused(lua: &Lua) -> Option<FrameHandle> {
     lua.app_data_ref::<Model>()
         .expect("model app_data")
         .focused_editbox
 }
 
-/// Resolve a frame id to a live EditBox handle.
 fn editbox_of(lua: &Lua, id: u32) -> Option<FrameHandle> {
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     let h = model.id_to_frame.get(&id).copied()?;
diff --git a/crates/benilla-ui/src/script/editbox/methods.rs b/crates/benilla-ui/src/script/editbox/methods.rs
index 250d3025..056a492f 100644
--- a/crates/benilla-ui/src/script/editbox/methods.rs
+++ b/crates/benilla-ui/src/script/editbox/methods.rs
@@ -1,8 +1,5 @@
-//! The EditBox Lua method surface — `install` builds the method table
-//! (`REG_EDITBOX_METHODS`) the dispatcher consults before the shared frame table for EditBox
-//! frames: text/cursor/selection accessors, focus, history, the config setters, and the blink
-//! dial. Every method routes through the mother module's primitives (`set_text`,
-//! `highlight_text`, …), so the byte-verified law lives exactly once.
+//! The EditBox Lua method table (`REG_EDITBOX_METHODS`), consulted before the shared frame
+//! table; each method routes through the parent module's primitives.
 
 use mlua::{Lua, Table, Value};
 
@@ -14,7 +11,6 @@ use super::{
     with_eb, REG_EDITBOX_METHODS,
 };
 
-/// Run `f` over a frame's EditBox state for a Lua method call; errors if `this` is not a live EditBox.
 fn with_editbox<T>(
     lua: &Lua,
     this: &Table,
@@ -32,11 +28,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, (this, s): (Table, Option<mlua::Value>)| {
             let s = crate::script::binding_abi::text_arg(lua, s)?;
             let h = frame_handle_of(lua, &this)?;
-            // Programmatic SetText KEEPS a history browse in progress: the chat live parse
-            // rewrites the box on every recalled slash line ("/s hi" → Say + "hi"), and ending
-            // the browse there reset every UP to the newest entry — "history only goes back 1"
-            // (director's report, 2026-07-26). The browse ends on typed edits, AddHistoryLine,
-            // and focus gain (`set_focus_handle`) — the fresh-session reset.
+            // SetText keeps a history browse going: the chat parser rewrites each recalled slash
+            // line, and ending the browse there would send every Up back to the newest entry.
+            // Typed edits, AddHistoryLine and focus gain end it.
             set_text(lua, h, &s.unwrap_or_default());
             Ok(())
         })?,
@@ -45,30 +39,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         "GetText",
         lua.create_function(|lua, this: Table| with_editbox(lua, &this, |eb| eb.text.clone()))?,
     )?;
-    // SetNumber(v) — **the same function as SetText**. `0x798690` and `0x7984c0` are byte-identical
-    // (245 bytes each, zero differences after masking rel32 and absolute-VA operands; only the
-    // usage string differs), so this does no numeric work of its own: it hands the argument to the
-    // shared `lua_tostring` marshalling and sets the result as text. Decision 1831.
-    //
-    // The GATE is `lua_isstring 0x6f3510`, a pure type test over {number, string} — NOT
-    // `lua_isnumber` and NOT `luaL_checknumber`. So a STRING is accepted and passed through
-    // VERBATIM, never parsed: `SetNumber("abc")` sets the text "abc" and does not raise. Anything
-    // else — nil, boolean, table, or an ABSENT argument — raises the usage string and abandons the
-    // caller's statement.
-    //
-    // The live consumer is `MoneyInputFrame.lua:47/52/57`, on the chain since 1751, whose three
-    // boxes are `numeric="true"`. Our numeric filter already models the reference's wholesale
-    // abort, which matters here: on such a box `SetNumber(-5)` or `SetNumber(0.8)` leaves the box
-    // EMPTY rather than partially filled, because the sign or the point fails the digit test after
-    // the clear-all has already run. The money path only ever passes non-negative integers
-    // (`floor`/`mod` results), so it never takes that branch.
+    // SetNumber is SetText: `0x798690` and `0x7984c0` are byte-identical but for the usage
+    // string. Its gate is `lua_isstring` (`0x6f3510`), so a string is set verbatim, never parsed,
+    // and nil, a boolean, a table or no argument raises the usage string. On a numeric box `-5` or
+    // `0.8` leaves it empty: the sign or point fails the digit test after the clear has run.
     m.set(
         "SetNumber",
         lua.create_function(|lua, (this, v): (Table, Value)| {
             let text = match &v {
                 Value::Integer(i) => crate::script::binding_abi::lua_number_text(*i as f64),
                 Value::Number(n) => crate::script::binding_abi::lua_number_text(*n),
-                // A string is not parsed — it is the text.
                 Value::String(s) => s.to_str()?.to_string(),
                 _ => return Err(mlua::Error::runtime("Usage: EditBox:SetNumber(number)")),
             };
@@ -77,7 +57,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetNumber: atof of the real text (0 on failure), matching `0x798790`.
+    // GetNumber: the real text as a number, else 0. The reference (`0x798790`) is atof, which also
+    // reads the leading number of a text like "12abc".
     m.set(
         "GetNumber",
         lua.create_function(|lua, this: Table| {
@@ -85,19 +66,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(text.trim().parse::<f64>().unwrap_or(0.0))
         })?,
     )?;
-    // Insert(text) — **a nil is a no-op, not an error.** The reference's C `Insert` reads its
-    // argument through `lua_tostring`, which answers NULL for a nil and leaves the buffer alone;
-    // stock FrameXML relies on that. `LootFrame.lua:152` is the plain case:
-    //
-    //     ChatFrameEditBox:Insert(GetLootSlotLink(this.slot));
-    //
-    // with no guard, on a coin row whose `GetLootSlotLink` is nil. Typed as `String`, this raised
-    // — which the loot window only survived while we owned the file and could add a guard the
-    // reference does not have. It bit the moment `LootFrame.xml` came off the player's chain
-    // (1751), and it would bite any addon writing the same unguarded line.
-    //
-    // A NUMBER still inserts its digits: `lua_tostring` converts one in place, and mlua's
-    // `Option<String>` coercion follows it.
+    // Insert: a nil is a no-op, not an error, since the reference reads the argument through
+    // `lua_tostring`, which answers NULL for nil; stock `LootFrame.lua:152` inserts a coin row's
+    // nil link unguarded. A number inserts its digits.
     m.set(
         "Insert",
         lua.create_function(|lua, (this, s): (Table, Option<mlua::Value>)| {
@@ -126,18 +97,11 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // **No `HasFocus`.** 1.12's EditBox table registers the two setters above and no getter at
-    // all, and an addon that wants the answer keeps its own flag around `SetFocus`/`ClearFocus` —
-    // `pfQuest/browser.lua:760` documents exactly that and ships the workaround. Ours was an
-    // unexplained superset a feature-detecting addon would take the wrong branch on (1188, and
-    // the census that removed it, 2142). Host-side, the focus cell reads back through
-    // [`crate::script::UiScript::focused_editbox_name`].
+    // No `HasFocus`: 1.12's EditBox table has these two setters and no getter, and addons keep
+    // their own flag.
 
-    // GetInputLanguage() / ToggleInputLanguage() — `0x799550` / `0x799610`, the edit box's
-    // **IME** language, not the chat language: `ChatEdit_OnInputLanguageChanged` shows
-    // `INPUT_<name>` on the box's language button, and the toggle is what a Korean client
-    // flips between its two input modes. On a client with no IME the answer is the Roman
-    // alphabet and the toggle moves nothing; benilla has no IME.
+    // GetInputLanguage/ToggleInputLanguage (`0x799550`/`0x799610`): the IME's input language, not
+    // the chat language. With no IME, as here, the answer is "ROMAN" and the toggle does nothing.
     m.set(
         "GetInputLanguage",
         lua.create_function(|lua, this: Table| {
@@ -153,7 +117,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HighlightText([start [, end]]) — defaults (0, -1) = select-all.
+    // HighlightText([start [, end]]): the defaults (0, -1) select all.
     m.set(
         "HighlightText",
         lua.create_function(
@@ -166,26 +130,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     m.set(
-        // `GetMaxLetters 0x79929f` — the read half, which we were missing. Not published off the
-        // `strings` hit alone (that is what put `SetUnit` on the wrong widget earlier today):
-        // wow-re's numeric-arg round identified `0x79929f` as the GETTER of `[widget+0x340]`,
-        // the same field the setter below writes, which is table-level evidence rather than a
-        // name that happens to be in the image.
-        //
+        // `GetMaxLetters` (`0x79929f`) reads the field `SetMaxLetters` writes.
         "GetMaxLetters",
         lua.create_function(|lua, this: Table| {
             with_editbox(lua, &this, |eb| eb.max_letters as i64)
         })?,
     )?;
     m.set(
-        // `SetMaxBytes 0x798f30` — `SetMaxLetters`'s sibling in every respect but the sentinel:
-        // the same EXACT count gate (`0x798fbc cmp eax,2`, the second of the four `lua_gettop`
-        // callers), the same raw coerce of the value, and a field of its own at `+0x33c` whose
-        // no-limit value is **-1** where `maxLetters`'s is 0 (`0x799012 jle` → `0x799022`; the
-        // ctor writes -1 at `0x7799df`) — wow-re `numeric-arg-coercion-law.md` and `ui.md`'s
-        // CSimpleEditBox layout. So a non-positive argument is unlimited, a positive one caps
-        // the buffer's BYTES. The stock StaticPopup_Show calls it for any entry carrying
-        // `maxBytes` — none of the reference's own 76 does, so the reach is an addon's (1960).
+        // `SetMaxBytes` (`0x798f30`) has `SetMaxLetters`'s exact count gate (`0x798fbc`) and raw
+        // coercion, but its no-limit value is -1 (`0x799012`; the ctor writes -1 at `0x7799df`):
+        // a non-positive argument is unlimited, a positive one caps the bytes.
         "SetMaxBytes",
         lua.create_function(|lua, (this, args): (Table, mlua::MultiValue)| {
             let args: Vec<Value> = args.into_iter().collect();
@@ -202,30 +156,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     m.set(
-        // The read half: -1 while unlimited, the reference's own stored sentinel.
+        // -1 while unlimited, the reference's stored sentinel.
         "GetMaxBytes",
         lua.create_function(|lua, this: Table| {
             with_editbox(lua, &this, |eb| eb.max_bytes.map_or(-1, |n| n as i64))
         })?,
     )?;
     m.set(
-        // `SetMaxLetters 0x799110` — one of only FOUR widget bindings in the whole registrar that
-        // calls `lua_gettop` (wow-re `numeric-arg-coercion-law.md` Q3), and its gate is EXACT:
-        // `cmp eax,2`. So the count is checked and the type is not, which is the opposite of the
-        // usual pairing and the reason this needs its own body:
-        //
-        //   SetMaxLetters()           -> RAISES `Usage:` (too few)
-        //   SetMaxLetters(50, 60)     -> RAISES `Usage:` (too MANY — an exact gate, not a minimum)
-        //   SetMaxLetters(nil)        -> completes, stores 0
-        //   SetMaxLetters("12")       -> completes, stores 12 (a numeric string coerces)
-        //   SetMaxLetters({})         -> completes, stores 0
-        //
-        // and **0 is "no limit"**, not "no letters": the insert path's trim block is skipped
-        // whole on zero (`0x77c085 test edi,edi; je`), which is what `max_letters == 0` already
-        // means here. So `SetMaxLetters(nil)` is `SetMaxLetters(0)` is unlimited — aux-addon's
-        // `gui/core.lua:288` writes exactly that, and benilla raised on it and killed the addon at
-        // load. (Its neighbour `SetMaxBytes` uses **-1** for the same idea; two adjacent fields,
-        // two different sentinels.)
+        // `SetMaxLetters` (`0x799110`) checks the count exactly, `lua_gettop` (`0x6f3070`) against
+        // 2 at `0x79919c`, and not the type: no argument or two raise `Usage:`, nil or `{}` store
+        // 0, `"12"` stores 12. 0 is no limit: the insert skips its trim on zero (`0x77c085`).
         "SetMaxLetters",
         lua.create_function(|lua, (this, args): (Table, mlua::MultiValue)| {
             let args: Vec<Value> = args.into_iter().collect();
@@ -235,14 +175,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 ));
             }
             let n = crate::script::binding_abi::coerced_number(lua, args.first().cloned());
-            // `__ftol` truncates toward zero; a negative stores as itself there, but our field is
-            // a `usize` and the trim only ever tests `> 0`, so the two agree on every value that
-            // can change behaviour.
+            // Truncated toward zero like `__ftol`; the reference stores a negative as is, but its
+            // trim only acts above 0, so the clamp changes nothing.
             with_editbox(lua, &this, |eb| eb.max_letters = (n as i64).max(0) as usize)
         })?,
     )?;
-    // The submitted-line history (`historyLines`): FrameXML pushes each sent line
-    // (ChatEdit_AddHistory), UP/DOWN recall it (see `key_input`).
+    // The sent-line history (`historyLines`): `ChatEdit_AddHistory` pushes each line, Up and Down
+    // recall them.
     m.set(
         "AddHistoryLine",
         lua.create_function(|lua, (this, line): (Table, Option<String>)| {
@@ -269,7 +208,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             with_editbox(lua, &this, |eb| eb.history_max as i64)
         })?,
     )?;
-    // SetBlinkSpeed/GetBlinkSpeed — the caret half-period (`E+0x370`, XML `blinkSpeed`; ctor 0.5).
+    // SetBlinkSpeed/GetBlinkSpeed: the caret half-period (XML `blinkSpeed`, 0.5 s by default).
     m.set(
         "SetBlinkSpeed",
         lua.create_function(|lua, (this, s): (Table, f32)| {
@@ -311,9 +250,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok((ins[0], ins[1], ins[2], ins[3]))
         })?,
     )?;
-    // GetNumLetters: the LETTER count — `0x7992c0` walks the class array (`0x77bc80`), which
-    // counts classes 2, 3 and 6 only, so escapes are free and a 43-byte item link reports 9
-    // (decision 1077). Not bytes, and not chars either.
+    // GetNumLetters (`0x7992c0`): the class array's letters (`0x77bc80`), classes 2, 3 and 6 only,
+    // so escapes are free and a 43-byte item link counts 9.
     m.set(
         "GetNumLetters",
         lua.create_function(|lua, this: Table| {
@@ -323,33 +261,17 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The config flags. All four mirror the live API. The fifth flag — bit4, the XML's
-    // `ignoreArrows` — is NOT here: its Lua surface is `SetAltArrowKeyMode`/`GetAltArrowKeyMode`
-    // below, which take a different argument coercion and answer a number rather than a boolean,
-    // so it cannot share this loop. benilla used to register a `SetIgnoreArrows` "convenience"
-    // for the loader to drive; 5875 has no such method (the 48-entry table
-    // `[0x87bb68, 0x87bce8)` carries no entry whose name contains "Ignore"), so publishing it was
-    // exactly the error decision 1189 names — and it stood in for the two real names, which were
-    // missing. The loader drives the XML attribute through `SetAltArrowKeyMode` now.
-    // ── SetAltArrowKeyMode / GetAltArrowKeyMode (`0x7996e0` / `0x799790`) ────────────────────
+    // The XML's fifth flag, `ignoreArrows`, is `SetAltArrowKeyMode` in Lua; 1.12 has no
+    // `SetIgnoreArrows` (the 48-entry table `[0x87bb68, 0x87bce8)`).
     //
-    // **The setter's argument is `GetBoolOrDefault(L, 2, default = 1)`** (`0x6f1c10`), not Lua
-    // truthiness and not a plain numeric coercion — `0x7996e0` pushes the default `1` before the
-    // call, so **an absent argument ENABLES** the mode. `nil` disables; a number goes through
-    // `__ftol` so `0` and `0.5` are false and `-1` is true; `""` matches nothing in the
-    // off/disabled/on/enabled chain and falls to the default, so it ENABLES; `"0"` disables.
-    // [`crate::script::binding_abi::bool_or_default`] already models every arm.
-    //
-    // **The getter answers the NUMBER 1 or nil**, never a boolean (`0x799815`: the set arm pushes
-    // the double 1.0 via `0x6f3810`, the clear arm pushes nil via `0x6f37f0`) — the same idiom as
-    // `IsShiftKeyDown`. An addon writing `if box:GetAltArrowKeyMode() then` reads either the same;
-    // one writing `== 1` only reads the number.
+    // SetAltArrowKeyMode (`0x7996e0`) reads `GetBoolOrDefault` (`0x6f1c10`) with default 1: no
+    // argument enables, nil disables, a number truncates (0 and 0.5 off, -1 on), `""` takes the
+    // default and `"0"` disables. GetAltArrowKeyMode (`0x799790`) answers the number 1 or nil,
+    // never a boolean (`0x799815`).
     m.set(
         "SetAltArrowKeyMode",
         lua.create_function(|lua, (this, args): (Table, mlua::MultiValue)| {
-            // `MultiValue`, not `Value`, because the reference DISTINGUISHES absent from nil here
-            // and mlua's `Value` cannot: `0x7996e0` pushes the default `1` before the call, so
-            // `SetAltArrowKeyMode()` enables while `SetAltArrowKeyMode(nil)` disables.
+            // `MultiValue`, since a `Value` cannot tell no argument (on) from nil (off).
             let args: Vec<Value> = args.into_iter().collect();
             let on = crate::script::binding_abi::bool_or_default(args.first(), true);
             with_editbox(lua, &this, |eb| eb.alt_arrow_key_mode = on)?;
@@ -372,9 +294,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 let on = !matches!(v, Value::Nil | Value::Boolean(false));
                 with_editbox(lua, &this, |eb| set(eb, on))?;
                 if refresh_justify {
-                    // The text-anchoring law reads multiLine (TOP vs MIDDLE), and the loader
-                    // wires the declared `<FontString>` BEFORE the editbox flags (LoadXML order
-                    // 5·b vs 5b) — re-seat an already-wired region so `multiLine="true"` lands.
+                    // A multi-line box anchors its text TOP, else MIDDLE, and the loader wires the
+                    // `<FontString>` before the flags, so re-seat it.
                     super::refresh_text_region_justify(lua, &this)?;
                 }
                 Ok(())
@@ -388,43 +309,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// **The font block — entries #0–#15 of the EditBox method table**, and the largest single gap the
-/// per-kind widget-method census found in the 218-addon corpus (decision 1229).
-///
-/// `EditBox` is one of the six text-bearing types, so it re-declares the whole font block in its own
-/// flat table (`.data 0x87bb68`, 48 entries, count read from `mov edx,0x30` at `0x799ab5`; there is
-/// no `FontInstance` class in the 1.12 Lua chain). We had written every one of these verbs already —
-/// on `FontString` and on the `<Font>` object — and never wired them to the kind that wanted them.
-/// The census row is `63 EditBox:SetFontObject (on Texture, FontString)`, and its `(on …)` tail is
-/// exactly that: *a verb we have, on the wrong kinds*.
-///
-/// **The 63 is one library, not 63 independent addons.** Every one of those call sites is the same
-/// three lines of an embedded `Dewdrop-2.0.lua` —
-/// ```lua
-/// local editBox = CreateFrame("EditBox", nil, editBoxFrame)
-/// editBoxFrame.editBox = editBox
-/// editBox:SetFontObject(ChatFontNormal)
-/// ```
-/// — vendored into 63 addon folders (65 copies of the file: `FuBar` and its ~50 plugins, `BigWigs`,
-/// `AtlasLoot`, `oRA2`, …). One library replicated, so 63 chances to hit the *same* next wall
-/// (decision 1207).
-///
-/// Ten of the sixteen are the shared block and come from [`super::super::font_block`], which carries
-/// the per-verb byte evidence and the return-shape traps. Two are deliberately absent and four are
-/// installed here:
-///
-/// - **`SetSpacing`/`GetSpacing` (#10–#11) are NOT installed.** Nothing in this client models line
-///   spacing, so they could only store a number no renderer reads — the silently-ignored-setter
-///   failure of 1203/1205/1211 — while their absence raises a nil-value call that names itself.
-///   Corpus demand is zero: `:SetSpacing(`/`:GetSpacing(` appear in **0** of 218 addons.
-///   `script::font` withholds the same pair for the same reason.
-/// - **The justify four (#12–#15) are installed here**, against the box's own
-///   [`EditBoxState::justify`] word rather than its text region — the field's doc has the why (our
-///   editbox draw law seats that region LEFT unconditionally) and states the divergence.
+/// The font block, entries #0-#15 of the EditBox's own 48-entry method table (`0x87bb68`, count
+/// at `0x799ab5`); 1.12 has no `FontInstance` class, so each text-bearing kind declares it. Ten
+/// come from [`super::super::font_block`]. `SetSpacing`/`GetSpacing` (#10-#11) are not installed:
+/// nothing renders line spacing, and a missing method raises by name. The justify four (#12-#15)
+/// act on the box's own [`EditBoxState::justify`] word, not its text region.
 fn install_font_block(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // Every font method acts on the box's implicit FontString: each binding's shim loads
-    // `[this+0x324]` and hands it to the shared implementation, and that offset is
-    // `EditBoxState::text_region`. Created on demand, exactly like every other text-touching path.
+    // Every font method acts on the box's implicit FontString (`[this+0x324]`, our
+    // `text_region`), created on demand.
     crate::script::font_block::install(
         lua,
         m,
@@ -435,18 +327,9 @@ fn install_font_block(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "EditBox",
     )?;
 
-    // SetJustifyH("LEFT"|"CENTER"|"RIGHT") / SetJustifyV("TOP"|"MIDDLE"|"BOTTOM") → 0 values.
-    //
-    // Two verified traps, both of which a plausible implementation gets wrong. This table was the
-    // only one that got them right; the FontString and `<Font>` copies coerced anything unknown to
-    // CENTER/MIDDLE until 1237 lifted this law into [`crate::justify`], which all three now share:
-    //  · an **unrecognised token RAISES** `Usage: %s:SetJustifyH("justify")` (`0x87c77c`), rather
-    //    than falling back to a default;
-    //  · a token from the **other axis** parses fine and then masks to nothing — `SetJustifyH("TOP")`
-    //    yields 0x08, `0x08 & 0x07 == 0`, so it CLEARS justifyH and `GetJustifyH()` answers
-    //    `"UNKNOWN"`. No error either way.
-    //
-    // `AceGUIWidget-Slider.lua:210` (`editbox:SetJustifyH("CENTER")`, three addons) is the demand.
+    // SetJustifyH/SetJustifyV return nothing. An unknown token raises `Usage:` (`0x87c77c`); a
+    // token of the other axis parses and masks to nothing, so `SetJustifyH("TOP")` clears justifyH
+    // and `GetJustifyH()` answers "UNKNOWN".
     for (name, mask) in [
         ("SetJustifyH", EditBoxState::JUSTIFY_H_MASK),
         ("SetJustifyV", EditBoxState::JUSTIFY_V_MASK),
@@ -461,8 +344,8 @@ fn install_font_block(lua: &Lua, m: &Table) -> mlua::Result<()> {
             })?,
         )?;
     }
-    // GetJustifyH()/GetJustifyV() → exactly 1 string, the first set bit's token in the reference's
-    // own table order, or the literal "UNKNOWN".
+    // GetJustifyH/GetJustifyV: one string, the first set bit's token in the reference's table
+    // order, else "UNKNOWN".
     for (name, mask) in [
         ("GetJustifyH", EditBoxState::JUSTIFY_H_MASK),
         ("GetJustifyV", EditBoxState::JUSTIFY_V_MASK),
@@ -477,10 +360,10 @@ fn install_font_block(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// A `Set<Flag>` name paired with the EditBoxState mutator it drives (Lua truthiness).
+/// A `Set<Flag>` method name and the field write it drives.
 type FlagSetter = (&'static str, fn(&mut EditBoxState, bool));
 
-/// The config-flag setters, in one place so the loader and the Lua surface share the list.
+/// The four config-flag setters, each taking Lua truthiness.
 fn flag_setters() -> [FlagSetter; 4] {
     [
         ("SetAutoFocus", |eb, on| eb.auto_focus = on),
diff --git a/crates/benilla-ui/src/script/editbox/seam.rs b/crates/benilla-ui/src/script/editbox/seam.rs
index 8f6560d1..c9147761 100644
--- a/crates/benilla-ui/src/script/editbox/seam.rs
+++ b/crates/benilla-ui/src/script/editbox/seam.rs
@@ -1,21 +1,17 @@
-//! The EditBox text-UI seam — the `impl UiScript` surface the host drives each frame: the
-//! advance-table round trip (request → host measures → answer), the caret/selection/scroll
-//! geometry derived from it, and the clipboard pair. Split beside its concern per the layout.rs
-//! pattern (the measure-seam siblings live there).
+//! The EditBox seam the host drives each frame: the advance-table round trip, the caret,
+//! selection and scroll geometry derived from it, and the clipboard pair.
 
 use crate::script::{types, UiScript};
 use crate::widget::KindState;
 
 impl UiScript {
-    /// The focused EditBox's advance-table request (the metrics half of the mouse/selection law):
-    /// `Some` when the box's DISPLAY string needs its per-byte cumulative widths measured (text or
-    /// font changed since the last answer). Answer via [`Self::set_editbox_advances`] before
-    /// [`Self::focused_editbox_text_ui`] — an empty display settles engine-side without a trip.
+    /// The focused EditBox's request to measure its display string's per-byte cumulative widths,
+    /// when its text, font, scale or wrap width changed; an empty display needs no trip. Answer it
+    /// with [`Self::set_editbox_advances`] before [`Self::focused_editbox_text_ui`].
     pub fn editbox_advances_request(&mut self) -> Option<types::EditBoxAdvanceRequest> {
         use std::hash::{Hash, Hasher};
         let h = self.model_mut().focused_editbox?;
-        // Materialize the lazy text region first — its resolved font is the table's identity
-        // (a just-focused CreateFrame'd box has none until here).
+        // The lazy text region first: its font keys the table, and a new box has none until now.
         let rh = super::ensure_text_region(self.lua(), h)?;
         let mut model = self.model_mut();
         let (display, multi_line) = match model.arena.frame(h).map(|f| &f.kind_state) {
@@ -26,15 +22,13 @@ impl UiScript {
         let font = d.and_then(|d| d.font_path.clone());
         let height = d.and_then(|d| d.font_height);
         let outline = d.map(|d| d.outline).unwrap_or_default();
-        // The box's effective_scale rides the request ([`types::EditBoxAdvanceRequest::scale`]):
-        // the host measures at the drawn raster size so the advances land on the drawn glyphs.
+        // The host measures at the drawn raster size, so the advances land on the drawn glyphs.
         let scale = model
             .arena
             .frame(h)
             .map(|f| f.effective_scale)
             .unwrap_or(1.0);
-        // A multiline box also needs its wrap rows — at the text region's resolved width, the
-        // same width the draw wraps at. Folded into the cache key: a resize re-wraps.
+        // A multi-line box wraps at the text region's width, as the draw does; a resize re-keys.
         let wrap_width = multi_line
             .then(|| {
                 model
@@ -79,10 +73,8 @@ impl UiScript {
         })
     }
 
-    /// Answer an [`Self::editbox_advances_request`]: the per-byte cumulative laid-out widths of
-    /// the requested display string (len+1 entries, `[0] = 0`), plus the wrapped-row starts and
-    /// row pitch (single-line: `rows = [0]`, `cell_h` the line em — only a multiline box reads
-    /// them, but the answer is uniform).
+    /// Answer an [`Self::editbox_advances_request`]: the cumulative widths (len+1 entries from 0),
+    /// the wrapped-row starts and the row pitch, which only a multi-line box reads.
     pub fn set_editbox_advances(
         &mut self,
         id: u32,
@@ -103,13 +95,9 @@ impl UiScript {
         }
     }
 
-    /// The focused EditBox's text-UI geometry for this frame (RF-0082 leaves caret/highlight
-    /// geometry to the host): which Text quad is the box's (`target`), the scroll window to draw
-    /// (`display_from`), and the caret/selection x-spans within it — all advance-table-derived.
-    /// Clamps the scroll window against the text region's resolved width first (the
-    /// scroll-into-view invariant, `0x77da80`). `None` when nothing is focused, the box is
-    /// off-screen, or the advance table hasn't been answered yet (text still draws; the caret and
-    /// highlight sit that frame out).
+    /// The focused EditBox's text geometry this frame: its text quad, the scroll window and the
+    /// caret and selection spans in it, after scrolling the caret into view (`0x77da80`). `None`
+    /// until the advance table is answered: the text draws, without caret or highlight.
     pub fn focused_editbox_text_ui(&mut self) -> Option<types::EditBoxTextUi> {
         let h = {
             let model = self.model_mut();
@@ -120,12 +108,10 @@ impl UiScript {
             }
             h
         };
-        // Focus means "about to type": materialize the lazy text region (the same lazy
-        // constructor `sync_text_region` uses), so an empty just-focused box has a caret home.
+        // Materialize the lazy text region, so an empty, just-focused box has a caret home.
         let rh = super::ensure_text_region(self.lua(), h)?;
         let mut model = self.model_mut();
-        // The text region's resolved width; an unanchored region (a CreateFrame'd box without
-        // insets) draws over its owner, so the frame's own rect is its width.
+        // An unanchored text region draws over its owner, so the frame's own width stands in.
         let avail = model
             .region_resolved
             .get(&rh)
@@ -141,12 +127,11 @@ impl UiScript {
             return None;
         }
         if display.is_empty() {
-            // Trivial table — no host trip needed for an empty box.
             eb.advances = vec![0.0];
             eb.rows = vec![0];
         }
-        // Keep the caret inside the window, leaving it a pixel to stand in at the right edge
-        // (multiline: pins the window to 0 — the box wraps instead).
+        // Keep the caret inside the window with room at the right edge; a multi-line box wraps
+        // instead, its window pinned at 0.
         eb.clamp_scroll((avail - 2.0).max(0.0));
         let from = eb.scroll_start.min(display.len());
         let origin = eb.advances[from];
@@ -158,8 +143,7 @@ impl UiScript {
         );
         let (caret_row, caret_x, selection) = if eb.multi_line {
             let (row, x) = eb.caret_row_x(cursor_d);
-            // The selection as per-row spans: each touched row contributes the intersection of
-            // its byte range with [da, db), x-measured from the row's own origin.
+            // One span per touched row, its overlap with [da, db), measured from the row's origin.
             let mut spans = Vec::new();
             if da != db {
                 for i in 0..eb.rows.len() {
@@ -197,8 +181,8 @@ impl UiScript {
         })
     }
 
-    /// Ctrl/Cmd+C for the focused EditBox: the selected substring for the OS clipboard (`None` =
-    /// no selection; a password box yields its mask run, never the real text — RF-0082 §4).
+    /// Ctrl/Cmd+C: the focused EditBox's selection for the OS clipboard; a password box yields its
+    /// mask run, never the text, where the client copies the empty string (`0x882748`).
     pub fn editbox_copy(&mut self) -> Option<String> {
         super::copy_selection(self.lua())
     }
@@ -208,11 +192,9 @@ impl UiScript {
         super::cut_selection(self.lua())
     }
 
-    /// Push one submitted line into the named box's recall history — the ref's
-    /// `ChatEdit_AddHistory` slot (the canonical slash line, added by the app's router AFTER it
-    /// parses the send; decision 0301). By name, not focus: the submit pipeline is asynchronous,
-    /// so by the time the router runs, the box has already cleared and dropped focus. Returns
-    /// `false` when `box_name` names no live EditBox.
+    /// Push a sent line, as its canonical slash line, into the named box's history where the
+    /// reference calls `ChatEdit_AddHistory`. By name: the router runs after the box has cleared
+    /// and lost focus. `false` when `box_name` is no live EditBox.
     pub fn editbox_add_history(&mut self, box_name: &str, line: &str) -> bool {
         let lua = self.lua();
         let Ok(t) = lua.globals().get::<mlua::Table>(box_name) else {
diff --git a/crates/benilla-ui/src/script/editbox/tests.rs b/crates/benilla-ui/src/script/editbox/tests.rs
index c59b3e34..b4601a17 100644
--- a/crates/benilla-ui/src/script/editbox/tests.rs
+++ b/crates/benilla-ui/src/script/editbox/tests.rs
@@ -1,8 +1,4 @@
-//! Rust-driven tests of the EditBox runtime (RF-0082): focus acquisition + routing, text/cursor/
-//! selection editing, the specialized script fires, caps, numeric/password, and text-region sync.
-//! Frames are built programmatically via `CreateFrame("EditBox", …)` and driven through the public
-//! keyboard API (`char_input`/`key_input`/`editbox_action`/`has_keyboard_focus`) and the Lua
-//! method surface.
+//! EditBox runtime tests, driven through the public keyboard API and the Lua methods.
 
 use crate::script::{EditAction, EditUnit, QuadContent, UiScript};
 
@@ -10,7 +6,6 @@ fn script() -> UiScript {
     UiScript::new().expect("construct UiScript")
 }
 
-/// The display text of the (single) text quad an extract produces, if any.
 fn text_quad(s: &UiScript) -> Option<String> {
     s.extract().into_iter().find_map(|q| match q.content {
         QuadContent::Text { text, .. } => text,
@@ -18,23 +13,18 @@ fn text_quad(s: &UiScript) -> Option<String> {
     })
 }
 
-// ── §1/§2 focus acquisition + routing ───────────────────────────────────────────────────────
+// ── focus acquisition + routing ─────────────────────────────────────────────────────────────
 
-/// **The self-acquire path**, path 2 of the two: a box that has had no show TRANSITION (created
-/// already visible, so `visibility_focus` never runs for it) still takes the keyboard on the first
-/// key or char event, and processes that same event. Path 1, focus-on-show, is
-/// [`an_autofocus_box_takes_the_keyboard_when_it_is_shown`] below — this test's name used to assert
-/// its absence, which stopped being true at decision 1686.
+/// A box created visible has had no show transition, yet with autoFocus it takes the keyboard on
+/// the first key or char and processes that event.
 #[test]
 fn an_autofocus_box_self_acquires_on_the_first_event() {
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetAutoFocus(true)"#)
         .unwrap();
-    // No show transition has run for this box, so nothing owns the keyboard yet.
     assert!(!s.has_keyboard_focus());
     assert_eq!(s.focused_editbox_name(), None);
 
-    // The first char self-acquires focus AND processes that same event.
     assert!(
         s.char_input("a"),
         "an autoFocus box consumes the acquiring event"
@@ -44,10 +34,8 @@ fn an_autofocus_box_self_acquires_on_the_first_event() {
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "a");
 }
 
-/// **An `autoFocus` box takes the keyboard when it is shown** — the OnShow vtable override
-/// (`0x81c910` slot +0x30, `0x77a750`), missing here until decision 1686 because wow-re's own
-/// "verified by absence" negative came from a `call`-only census that could not see its tail-`jmp`.
-/// Gated on nothing else holding focus, and the gate is the whole of it — no topmost/best choice.
+/// The OnShow override (`0x77a750`, vtable `0x81c910` slot +0x30) focuses an autoFocus box when
+/// nothing holds focus; there is no topmost or best choice.
 #[test]
 fn an_autofocus_box_takes_the_keyboard_when_it_is_shown() {
     let s = script();
@@ -68,7 +56,7 @@ fn an_autofocus_box_takes_the_keyboard_when_it_is_shown() {
         "showing an autoFocus box focuses it",
     );
 
-    // Hiding the box that holds the keyboard releases it (the mirror override, slot +0x34).
+    // Hiding the focused box releases the keyboard (the mirror override, slot +0x34).
     s.run("E:Hide()").unwrap();
     assert!(
         !s.has_keyboard_focus(),
@@ -77,9 +65,8 @@ fn an_autofocus_box_takes_the_keyboard_when_it_is_shown() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The two gates, each shown to bite. A box that opted out does not take the keyboard on show; and
-/// a box that would have is refused while another still holds it — the reference's
-/// `if ([0xcf4dc8] == 0 && (flags & 1))`, both halves.
+/// Focus on show takes both halves of `[0xcf4dc8] == 0 && (flags & 1)`: no focus held, and
+/// autoFocus.
 #[test]
 fn the_show_focus_is_refused_without_autofocus_or_with_the_keyboard_taken() {
     let s = script();
@@ -98,7 +85,6 @@ fn the_show_focus_is_refused_without_autofocus_or_with_the_keyboard_taken() {
         "autoFocus=false is an opt-out that holds on show",
     );
 
-    // Now give the keyboard away, and show an autoFocus box into an occupied focus.
     s.run(
         r#"
         HOLDER = CreateFrame("EditBox", "Holder")
@@ -115,9 +101,7 @@ fn the_show_focus_is_refused_without_autofocus_or_with_the_keyboard_taken() {
         "a shown autoFocus box does not steal a focus that is already held",
     );
 
-    // And hiding a box that does NOT hold the keyboard leaves it where it is — `0x77e410`'s own
-    // per-box guard (`cmp ecx,eax; jne ret`), which is what makes the override's unconditional
-    // tail-jmp harmless.
+    // Hiding a box without the keyboard leaves focus alone (`0x77e410`'s per-box guard).
     s.run("LATE:Hide()").unwrap();
     assert_eq!(
         s.focused_editbox_name().as_deref(),
@@ -130,9 +114,7 @@ fn the_show_focus_is_refused_without_autofocus_or_with_the_keyboard_taken() {
 #[test]
 fn non_autofocus_unfocused_box_ignores_input() {
     let mut s = script();
-    // `SetAutoFocus(false)` explicitly: the ctor's `flags = 1` leaves autoFocus **ON** by default
-    // (`0x779a29`/`0x779a2e`, decision 1686), so a bare `CreateFrame("EditBox")` is an autoFocus
-    // box and would self-acquire on the first char. This test is about the other kind.
+    // The ctor leaves autoFocus on (`0x779a29`/`0x779a2e`), so a bare box would self-acquire.
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetAutoFocus(false)"#)
         .unwrap();
     assert!(!s.char_input("a"), "no focus, no autoFocus → not consumed");
@@ -150,7 +132,6 @@ fn focused_box_consumes_everything() {
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetFocus()"#)
         .unwrap();
-    // Empty text: these do nothing, but a focused box still consumes them.
     assert!(s.editbox_action(EditAction::Move {
         unit: EditUnit::Char,
         back: true,
@@ -211,7 +192,6 @@ fn click_focuses_regardless_of_autofocus_and_transition_order_is_lost_then_gaine
     .unwrap();
     s.resolve();
 
-    // Neither box has autoFocus, yet a click focuses each.
     s.mouse_button(50.0, 10.0, "LeftButton", true);
     s.mouse_button(50.0, 10.0, "LeftButton", false);
     assert_eq!(s.focused_editbox_name().as_deref(), Some("A"));
@@ -225,12 +205,10 @@ fn click_focuses_regardless_of_autofocus_and_transition_order_is_lost_then_gaine
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-// ── §3 text buffer + editing + OnTextChanged/OnTextSet ───────────────────────────────────────
+// ── text buffer + editing + OnTextChanged/OnTextSet ─────────────────────────────────────────
 
-/// **`OnTextChanged` is deferred and coalesced** (decision 1831). An edit only raises the
-/// `textChanged` dirty bit; the fire belongs to the drain (`0x77d3e0`) that the box's own OnUpdate
-/// runs. So three typed characters are three marks on ONE box and produce exactly ONE fire — this
-/// test asserted three before the law was checked.
+/// An edit only raises the box's `textChanged` bit; `OnTextChanged` fires once, at the drain its
+/// OnUpdate runs (`0x77d3e0`).
 #[test]
 fn typing_coalesces_into_one_deferred_ontextchanged() {
     let mut s = script();
@@ -262,15 +240,12 @@ fn typing_coalesces_into_one_deferred_ontextchanged() {
     );
     assert_eq!(s.eval::<String>("return seen").unwrap(), "abc");
 
-    // Nothing is pending now, so a second drain fires nothing.
     s.tick(0.0);
     assert_eq!(s.eval::<i64>("return changed").unwrap(), 1);
 }
 
-/// The two fires part company (decision 1831): **`OnTextSet` is synchronous, inside `SetText`
-/// itself** (`0x77be6b`), while `OnTextChanged` waits for the drain. The equality short-circuit
-/// still suppresses both. So writing "hi", "hi", "bye" before any drain logs two `set`s and then a
-/// SINGLE `changed` carrying only the last value — `A → B` coalesces.
+/// `OnTextSet` fires inside `SetText` (`0x77be6b`), `OnTextChanged` at the drain; an unchanged
+/// text fires neither.
 #[test]
 fn set_text_fires_ontextset_at_once_and_ontextchanged_at_the_drain() {
     let mut s = script();
@@ -325,7 +300,7 @@ fn max_letters_trims_from_the_end() {
     assert_eq!(s.eval::<i64>("return E:GetNumLetters()").unwrap(), 3);
 }
 
-// ── §4 selection / highlight / keys ──────────────────────────────────────────────────────────
+// ── selection / highlight / keys ────────────────────────────────────────────────────────────
 
 #[test]
 fn highlight_all_then_typing_replaces_the_selection() {
@@ -357,14 +332,13 @@ fn paste_inserts_at_the_cursor_and_replaces_the_selection() {
     "#,
     )
     .unwrap();
-    // Cursor sits at end after SetText → paste appends.
+    // SetText leaves the cursor at the end, so the paste appends.
     assert!(s.paste("CD"), "focused box consumes the paste");
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "abCD");
-    // Select-all then paste replaces the whole selection.
     s.run("E:HighlightText(0, -1)").unwrap();
     assert!(s.paste("xyz"));
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "xyz");
-    // Both pastes marked the same box, so the drain owes exactly one fire — not one per paste.
+    // Both pastes marked the one box, so the drain fires once.
     assert_eq!(s.eval::<i64>("return changed").unwrap(), 0);
     s.tick(0.0);
     assert_eq!(s.eval::<i64>("return changed").unwrap(), 1);
@@ -391,7 +365,6 @@ fn paste_strips_newlines_in_a_single_line_box_but_keeps_them_when_multiline() {
         "onetwothree"
     );
 
-    // Multi-line box: the newline survives (a tab is still a dropped control char).
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetMultiLine(true); E:SetFocus()"#)
         .unwrap();
@@ -401,14 +374,12 @@ fn paste_strips_newlines_in_a_single_line_box_but_keeps_them_when_multiline() {
 
 #[test]
 fn paste_honors_max_letters_and_numeric() {
-    // maxLetters trims the paste from the end.
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetMaxLetters(3); E:SetFocus()"#)
         .unwrap();
     assert!(s.paste("abcdef"));
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "abc");
 
-    // numeric aborts a paste that carries any non-digit (matching the typed-insert rule).
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetNumeric(true); E:SetFocus()"#)
         .unwrap();
@@ -474,7 +445,7 @@ fn enter_escape_tab_space_fire_their_slots() {
     )
     .unwrap();
     assert!(s.key_input("ENTER")); // single-line → OnEnterPressed
-    assert!(s.key_input("ESCAPE")); // fires, does NOT release focus
+    assert!(s.key_input("ESCAPE"));
     assert_eq!(
         s.focused_editbox_name().as_deref(),
         Some("E"),
@@ -485,7 +456,7 @@ fn enter_escape_tab_space_fire_their_slots() {
 
     let log: Vec<String> = s.eval("return log").unwrap();
     assert_eq!(log, vec!["enter", "escape", "tab", "space"]);
-    // ENTER on a single-line box must NOT insert; only the space landed.
+    // Enter on a single-line box inserts nothing; only the space landed.
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), " ");
 }
 
@@ -507,23 +478,10 @@ fn multiline_enter_inserts_a_newline_without_onspacepressed() {
     assert_eq!(s.eval::<i64>("return spaces").unwrap(), 0);
 }
 
-/// **Alt-arrow mode: the two real verbs, and the flag they share with the XML attribute.**
-///
-/// The §5 (`ignorearrows-alt-arrow-gate.md`) settled four things this pins:
-///
-///  · 5875 has **no `SetIgnoreArrows`** — the 48-entry EditBox method table
-///    `[0x87bb68, 0x87bce8)` carries `SetAltArrowKeyMode`/`GetAltArrowKeyMode` at 46/47 and no
-///    entry whose name contains "Ignore". benilla published the invented name for two rounds and
-///    was missing both real ones.
-///  · The XML attribute `ignoreArrows` and the Lua verbs drive **one** flag (`[E+0x318] & 0x10`).
-///  · The setter's argument is `GetBoolOrDefault(L, 2, default = 1)` (`0x6f1c10`), not Lua
-///    truthiness — an **absent** argument ENABLES, `""` ENABLES, `0` and `"0"` disable.
-///  · The getter answers the **number 1 or nil**, never a boolean.
-///
-/// And the negative that matters: the engine core no longer swallows anything. The gate is on the
-/// KEY and lives in the host (`UiKeyboardCapture::arrows_fall_through`), so an `EditAction` that
-/// arrives here moves the caret whatever the flag says — it only ever arrives when ALT was held or
-/// the key was not an arrow.
+/// The method table `[0x87bb68, 0x87bce8)` has `SetAltArrowKeyMode`/`GetAltArrowKeyMode` at 46/47
+/// and no `SetIgnoreArrows`; the XML `ignoreArrows` is the same flag (`[E+0x318] & 0x10`). The
+/// gate is on the key, in the host (`UiKeyboardCapture::arrows_fall_through`), so an `EditAction`
+/// that arrives here acts whatever the flag says.
 #[test]
 fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves() {
     let mut s = script();
@@ -536,13 +494,11 @@ fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves()
     )
     .unwrap();
 
-    // The invented name is gone.
     assert!(
         s.eval::<bool>("return E.SetIgnoreArrows == nil").unwrap(),
         "5875 has no SetIgnoreArrows — publishing it was decision 1189's error"
     );
 
-    // The getter: a number or nil, never a boolean.
     assert_eq!(
         s.eval::<Option<i64>>("return E:GetAltArrowKeyMode()")
             .unwrap(),
@@ -560,10 +516,10 @@ fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves()
         "the set arm pushes the double 1.0 (0x6f3810), not a boolean"
     );
 
-    // `GetBoolOrDefault(default = 1)`, arm by arm — three of these are backwards under Lua
-    // truthiness, which is why the coercion has its own helper.
+    // `GetBoolOrDefault` (`0x6f1c10`, default 1), arm by arm; three are backwards under Lua
+    // truthiness.
     for (arg, want) in [
-        ("", Some(1)),      // ABSENT -> the default 1 -> enabled
+        ("", Some(1)),      // absent -> the default 1 -> enabled
         ("nil", None),      // nil -> 0
         ("0", None),        // __ftol(0) -> false
         ("-1", Some(1)),    // __ftol(-1) != 0 -> true
@@ -580,8 +536,8 @@ fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves()
         );
     }
 
-    // The engine core does NOT swallow a Char move any more — the gate is on the key, upstream.
-    // `SetText` leaves the caret at the end, so one back-Char move puts it between 'b' and 'c'.
+    // A flagged box still acts on a Char move. `SetText` leaves the caret at the end, so one back
+    // move puts it between 'b' and 'c'.
     s.run(r#"E:SetAltArrowKeyMode(1) E:SetText("abc")"#)
         .unwrap();
     assert!(s.editbox_action(EditAction::Move {
@@ -600,8 +556,8 @@ fn alt_arrow_key_mode_is_the_flag_and_the_engine_core_no_longer_swallows_moves()
     );
 }
 
-/// The XML attribute is the same flag under its other name (`ignoreArrows` occurs once in the
-/// image, at `0x879b78`, with one xref: the attribute push at `0x77a13a`).
+/// The XML `ignoreArrows` is the same flag: its string (`0x879b78`) has one use, the attribute
+/// read at `0x77a13a`.
 #[test]
 fn the_ignore_arrows_xml_attribute_is_alt_arrow_key_mode() {
     let s = script();
@@ -641,21 +597,17 @@ fn get_number_parses_the_text() {
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetText("12.5")"#)
         .unwrap();
     assert_eq!(s.eval::<f64>("return E:GetNumber()").unwrap(), 12.5);
-    // Non-numeric text → 0.
     s.run(r#"E:SetText("hello")"#).unwrap();
     assert_eq!(s.eval::<f64>("return E:GetNumber()").unwrap(), 0.0);
 }
 
-// ── the EditBox override never fires generic OnChar/OnKeyDown (§2) ────────────────────────────
+// ── the generic OnChar and OnKeyDown ─────────────────────────────────────────────────────────
 
 #[test]
 fn typing_fires_the_generic_on_char_with_what_was_inserted() {
-    // **The half of the old law that was wrong** (wow-re, corrected 2026-08-29; decision 1686).
-    // `CSimpleEditBox` has its own input vtable which does not chain to the base — but Insert
-    // itself fires the generic `OnChar` slot (`+0x180`) at `0x77c13c`, through the **varargs**
-    // firer `0x7026f0` with fmt `"%s"` and the spliced string as the argument. The published
-    // negative came from censusing only the fixed-arity firer `0x702690`: one member of a
-    // two-member family.
+    // The box's input vtable does not chain to the base, but Insert fires the generic `OnChar`
+    // (`+0x180`) at `0x77c13c`, through the varargs firer `0x7026f0` (not the fixed-arity
+    // `0x702690`) with the inserted string.
     let mut s = script();
     s.run(
         r#"
@@ -675,7 +627,7 @@ fn typing_fires_the_generic_on_char_with_what_was_inserted() {
         "OnChar fires once, with the inserted string",
     );
 
-    // `SetText` is NOT an insert path and fires nothing — the seam the reference has too.
+    // `SetText` is not an insert and fires no `OnChar`, as in the reference.
     s.run(r#"E:SetText("zzz")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return table.concat(got, ',')").unwrap(),
@@ -687,10 +639,8 @@ fn typing_fires_the_generic_on_char_with_what_was_inserted() {
 
 #[test]
 fn key_paths_never_fire_the_generic_on_key_down() {
-    // The surviving half (wow-re `frame-key-script-delivery.md` §1): the box's own key-down
-    // vtable (`0x77b160`) handles the event and never chains to the base, so a focused box's
-    // typing does not also run a generic `OnKeyDown` bound on that same box. Only the `OnChar`
-    // half of the original claim was corrected — this one was re-censused and stands.
+    // The box's key-down handler (`0x77b160`) never chains to the base, so a generic `OnKeyDown`
+    // on the focused box does not fire.
     let mut s = script();
     s.run(
         r#"
@@ -712,7 +662,7 @@ fn key_paths_never_fire_the_generic_on_key_down() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-// ── history recall (`historyLines` / AddHistoryLine — decision 0288 P2) ──────────────────────
+// ── history recall (`historyLines`, AddHistoryLine) ──────────────────────────────────────────
 
 #[test]
 fn history_recall_walks_up_and_down_and_restores_the_draft() {
@@ -760,8 +710,8 @@ fn typing_ends_the_history_browse() {
     .unwrap();
     s.editbox_action(EditAction::HistoryPrev);
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "newer");
-    // A typed char turns the recalled line into an ordinary draft: the next UP starts a FRESH
-    // browse from the newest entry (stashing the edited line as the new draft).
+    // A typed char turns the recalled line into a draft: the next UP starts a fresh browse from
+    // the newest entry, stashing the edited line as the draft.
     s.char_input("!");
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "newer!");
     s.editbox_action(EditAction::HistoryPrev);
@@ -783,9 +733,8 @@ fn programmatic_set_text_keeps_the_browse_and_focus_gain_resets_it() {
     "#,
     )
     .unwrap();
-    // Recall the newest, then rewrite the box the way the chat live parse does on a slash
-    // recall ("/g two" → Guild + "two"). The browse walk must survive: the next UP lands on
-    // the OLDER entry, not back on the newest (the "history only goes back 1" bug).
+    // Rewrite the recalled line as the chat parser does ("/g two" → Guild + "two"); the next UP
+    // must reach the older entry, not the newest again.
     s.editbox_action(EditAction::HistoryPrev);
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "/g two");
     s.run(r#"E:SetText("two")"#).unwrap();
@@ -826,14 +775,14 @@ fn history_off_by_default_and_up_is_still_consumed() {
     let mut s = script();
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetText("t"); E:SetFocus()"#)
         .unwrap();
-    // No historyLines: AddHistoryLine is a no-op, UP consumed but inert (a focused box eats every
-    // key — RF-0082 §2).
+    // No historyLines: AddHistoryLine does nothing, and UP is consumed but inert, since a focused
+    // box eats every key (both handlers return 1, `0x77a900`/`0x77b160`).
     s.run(r#"E:AddHistoryLine("x")"#).unwrap();
     assert!(s.editbox_action(EditAction::HistoryPrev));
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "t");
 }
 
-// ── SetTextInsets (0288 P2 — the header-driven text-rect shrink) ─────────────────────────────
+// ── SetTextInsets ────────────────────────────────────────────────────────────────────────────
 
 #[test]
 fn text_insets_shrink_the_text_region_rect() {
@@ -871,16 +820,13 @@ fn text_insets_shrink_the_text_region_rect() {
         (rect.bottom - 53.0).abs() < 0.01,
         "bottom inset 3: {rect:?}"
     );
-    // The getter echoes.
     let (l, r_, t, b) = s
         .eval::<(f32, f32, f32, f32)>("return E:GetTextInsets()")
         .unwrap();
     assert_eq!((l, r_, t, b), (15.0, 13.0, 2.0, 3.0));
 }
 
-// The FontInstance half an EditBox inherits in the client: SetTextColor tints the box's text
-// region (`ChatEdit_UpdateHeader` colors the typed text this way — its absence killed the chat
-// header chunk mid-run and left the /w insets stale, the caret-in-the-header bug).
+// SetTextColor tints the box's text region, as `ChatEdit_UpdateHeader` colours the typed text.
 #[test]
 fn set_text_color_tints_the_text_region() {
     let mut s = script();
@@ -914,8 +860,8 @@ fn set_text_color_tints_the_text_region() {
 
 // ── the host text-UI seam: advances, caret/selection geometry, mouse, clipboard ─────────────
 
-/// Build a focused 200×32 box at BOTTOMLEFT(100,50), resolve it, type `text`, and answer its
-/// advance table with a synthetic monospace 7 px/byte — the standard rig for the geometry tests.
+/// A focused 200×32 box at BOTTOMLEFT(100, 50) holding `text`, its advances answered at 7 px per
+/// byte.
 fn seam_rig(s: &mut UiScript, text: &str) {
     s.set_screen_size(800.0, 600.0);
     s.run(
@@ -942,8 +888,7 @@ fn answer_advances(s: &mut UiScript) {
     }
 }
 
-/// The seam reports caret geometry from the advance table, and vanishes with focus or
-/// visibility — the old prefix-string seam's laws, now in pixels.
+/// Caret geometry comes from the advance table, and there is none without focus or visibility.
 #[test]
 fn text_ui_reports_caret_geometry_and_focus() {
     let mut s = script();
@@ -955,7 +900,6 @@ fn text_ui_reports_caret_geometry_and_focus() {
     assert_eq!(ui.caret_x, 0.0);
     assert_eq!(ui.display_from, 0);
     assert!(ui.selection.is_empty());
-    // The empty box still emits its Text quad (Some("")) — the caret's ride-along.
     assert!(
         s.extract().iter().any(|q| matches!(
             (&q.target, &q.content),
@@ -998,11 +942,10 @@ fn click_places_cursor_and_drag_selects() {
     let ui = s.focused_editbox_text_ui().unwrap();
     assert_eq!(ui.selection, vec![(0, 21.0, 49.0)]);
     assert_eq!(ui.caret_x, 49.0);
-    // Drag back LEFT past the anchor to x=107 (byte 1): the selection flips to 1..3.
+    // Drag back left past the anchor to x=107 (byte 1): the selection flips to 1..3.
     s.mouse_move(107.0, 60.0);
     let ui = s.focused_editbox_text_ui().unwrap();
     assert_eq!(ui.selection, vec![(0, 7.0, 21.0)]);
-    // Release ends the drag: further moves change nothing.
     s.mouse_button(107.0, 60.0, "LeftButton", false);
     s.mouse_move(170.0, 60.0);
     assert_eq!(
@@ -1067,8 +1010,8 @@ fn ctrl_arrows_jump_words() {
     );
 }
 
-/// Copy needs a selection; cut copies then deletes; the password box yields the mask run, never
-/// the real text (RF-0082 §4's placeholder law, mask stand-in).
+/// Copy needs a selection, cut copies then deletes, and a password box copies its mask run, never
+/// the text (the client copies the empty string, `0x882748`).
 #[test]
 fn copy_cut_and_the_password_placeholder() {
     let mut s = script();
@@ -1092,15 +1035,13 @@ fn copy_cut_and_the_password_placeholder() {
     );
 }
 
-/// The OS-native delete family (no 1.12 counterpart — the host keymap's Option/Cmd/Ctrl
-/// Backspace-Delete chords): a word delete takes the adjacent alnum run (+ the separators toward
-/// it), an edge delete clears to the line end — and both collapse to "delete the selection" when
-/// one exists, like every deletion gesture.
+/// Word and edge deletes, the host's OS-native chords with no 1.12 counterpart: a word delete
+/// takes the adjacent alphanumeric run and the separators toward it, an edge delete clears to the
+/// line's end, and either deletes a live selection instead.
 #[test]
 fn word_and_edge_deletes() {
     let mut s = script();
     seam_rig(&mut s, "abc def ghi");
-    // Word-delete back from the end: "ghi" goes (boundary at 8).
     s.editbox_action(EditAction::Delete {
         unit: EditUnit::Word,
         back: true,
@@ -1124,7 +1065,6 @@ fn word_and_edge_deletes() {
     });
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), " ");
 
-    // Selection-first: with a live selection, a word delete removes exactly it.
     s.run(r#"E:SetText("hello world"); E:HighlightText(2, 5)"#)
         .unwrap();
     s.editbox_action(EditAction::Delete {
@@ -1133,7 +1073,7 @@ fn word_and_edge_deletes() {
     });
     assert_eq!(s.eval::<String>("return E:GetText()").unwrap(), "he world");
 
-    // Edge-delete back (macOS Cmd+Backspace): clears to the start — the whole line from the end.
+    // Edge-delete back (macOS Cmd+Backspace) from the end clears the whole line.
     s.run(r#"E:SetText("clear me")"#).unwrap();
     s.editbox_action(EditAction::Delete {
         unit: EditUnit::Edge,
@@ -1150,8 +1090,8 @@ fn word_and_edge_deletes() {
     assert_eq!(s.eval::<i64>("return n").unwrap(), 0);
 }
 
-/// SelectAll (the ref's Ctrl+A → `HighlightText(0, -1)` law): whole text selected, caret to the
-/// end; typing replaces the lot.
+/// SelectAll, the reference's Ctrl+A (`HighlightText(0, -1)`): the whole text selected, the caret
+/// at the end, and typing replaces it all.
 #[test]
 fn select_all_action() {
     let mut s = script();
@@ -1168,9 +1108,8 @@ fn select_all_action() {
     );
 }
 
-/// The scroll window follows the cursor: typing past the box edge advances `display_from`
-/// (whole chars); HOME snaps it back (`0x77da80`'s stay-visible invariant, the char-granular
-/// `E+0x348` window).
+/// The scroll window keeps the cursor visible (`0x77da80`) in whole chars: typing past the edge
+/// advances `display_from`, HOME snaps it back.
 #[test]
 fn scroll_window_keeps_the_cursor_visible() {
     let mut s = script();
@@ -1184,7 +1123,6 @@ fn scroll_window_keeps_the_cursor_visible() {
         (40 - ui.display_from) as f32 * 7.0,
         "caret x measures from the window origin"
     );
-    // HOME: the window snaps back to 0.
     s.editbox_action(EditAction::Move {
         unit: EditUnit::Edge,
         back: true,
@@ -1195,7 +1133,7 @@ fn scroll_window_keeps_the_cursor_visible() {
     assert_eq!(ui.caret_x, 0.0);
 }
 
-/// The blink law (`0x77a790`): 0.5 s half-period toggle, reset shown by every edit.
+/// The caret blink (`0x77a790`): a 0.5 s half-period, reset to shown by every edit.
 #[test]
 fn caret_blinks_on_tick_and_resets_on_edit() {
     let mut s = script();
@@ -1207,19 +1145,15 @@ fn caret_blinks_on_tick_and_resets_on_edit() {
     assert!(s.focused_editbox_text_ui().unwrap().caret_on);
     s.tick(0.6);
     assert!(!s.focused_editbox_text_ui().unwrap().caret_on);
-    // An edit shows the caret immediately (blink reset).
     s.char_input("b");
     answer_advances(&mut s);
     assert!(s.focused_editbox_text_ui().unwrap().caret_on);
 }
 
-// ── A hyperlink is ONE keypress (RF-0087 §6, decision 1077) ──────────────────────────────────
+// ── a hyperlink is one keypress (`AdvanceTokens 0x77bb30`) ─────────────────────
 //
-// The engine-level law lives in `markup`; these drive it the way a player does — through the
-// focused box's public keyboard API — because that is the level the reported defect lived at:
-// backspacing a shift-clicked item link chewed it one invisible byte at a time, and the byte that
-// went first was the `r` of its trailing `|r`, which turned everything typed afterwards the item's
-// colour.
+// Driven through the keyboard API: a Backspace that took only the link's trailing `|r` would
+// colour everything typed after it.
 
 /// An epic link exactly as the client's own builder formats one (`0x52adb0`).
 const LINK: &str = "|cffa335ee|Hitem:11684:0:0:0|h[Ironfoe]|h|r";
@@ -1245,8 +1179,7 @@ fn one_backspace_deletes_a_whole_item_link() {
     }));
     assert_eq!(text_of(&s), "", "colour prefix and trailing |r go with it");
 
-    // And from the far side of following text: the link survives until the text is gone, then goes
-    // whole — never half-eaten, which is what left a dangling `|c` colouring the rest of the line.
+    // Behind following text: the text goes first, then the whole link, never leaving a `|c`.
     let mut s = box_with_link("ab");
     for expected in ["|cffa335ee|Hitem:11684:0:0:0|h[Ironfoe]|h|ra", LINK, ""] {
         s.editbox_action(EditAction::Delete {
@@ -1273,8 +1206,7 @@ fn one_arrow_crosses_a_whole_item_link() {
         });
     };
     cursor(&mut s);
-    // One RIGHT from the start lands past the entire link — so typing there appends, and does not
-    // land between the `]` and its `|h`.
+    // One RIGHT from the start passes the whole link, so typing there appends.
     s.char_input("x");
     assert_eq!(text_of(&s), format!("{LINK}x"));
 }
@@ -1307,8 +1239,7 @@ fn typing_strictly_inside_a_link_is_refused() {
         LINK,
         "the client swallows it rather than splitting the link"
     );
-    // The same keystroke at the link's leading edge is allowed — the guard tests the PREVIOUS
-    // token too, which is what keeps the boundary usable.
+    // At the link's leading edge the keystroke lands: the guard also tests the previous token.
     s.run("E:HighlightText(0, 0)").unwrap();
     s.char_input("x");
     assert_eq!(text_of(&s), format!("x{LINK}"));
@@ -1334,20 +1265,13 @@ fn max_letters_counts_visible_letters_not_escape_bytes() {
     s.run(r#"E = CreateFrame("EditBox", "E"); E:SetFocus(); E:SetMaxLetters(20)"#)
         .unwrap();
     s.run(&format!("E:Insert(\"{LINK}\")")).unwrap();
-    // 43 bytes, but "[Ironfoe]" is 9 letters — comfortably under a 20-letter cap that a raw char
-    // count would have blown through, trimming the link's own tail off.
+    // 43 bytes, but "[Ironfoe]" is 9 letters, under the 20-letter cap.
     assert_eq!(text_of(&s), LINK);
     assert_eq!(s.eval::<i64>("return E:GetNumLetters()").unwrap(), 9);
 }
 
-/// **Creating a box is not showing it** — and that is what keeps the on-show self-focus safe now
-/// that autoFocus defaults ON (decision 1686). A frame born visible is not an effective-visibility
-/// *transition*, so it never runs the OnShow override; only a real `Show()` does. Without this,
-/// loading the shipped chain would hand the keyboard to whichever edit box happened to be
-/// constructed first, and typing would go into it instead of to the game.
-///
-/// Pinned because it is load-bearing by *absence*: nothing in the on-show path mentions creation,
-/// so the day frame construction starts firing OnShow, this is the test that says what it costs.
+/// A box born visible has had no show transition, so the OnShow focus never runs for it; if it
+/// did, loading the UI would hand the keyboard to the first edit box built.
 #[test]
 fn creating_a_box_does_not_focus_it_the_way_showing_one_does() {
     let s = script();
@@ -1360,17 +1284,8 @@ fn creating_a_box_does_not_focus_it_the_way_showing_one_does() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`SetMaxLetters` gates the COUNT and not the type** — one of four widget bindings in the whole
-/// registrar that calls `lua_gettop`, and its gate is exact (`cmp eax,2`), while the value goes
-/// through a bare `lua_tonumber` with no `isnumber` guard (wow-re `numeric-arg-coercion-law.md`
-/// Q1/Q3, VERIFIED).
-///
-/// That pairing is the opposite of the usual one, which is why it earns a test: benilla typed the
-/// argument `i64` and so raised on `SetMaxLetters(nil)` — aux-addon's `gui/core.lua:288` writes
-/// exactly that, and died at load on it — while accepting the wrong *number* of arguments
-/// silently.
-///
-/// And `0` is **no limit**, not "no letters".
+/// `SetMaxLetters` gates the exact count (`lua_gettop`, `0x6f3070`) and reads the value with a bare
+/// `lua_tonumber` (`0x6f3620`); 0 is no limit.
 #[test]
 fn set_max_letters_gates_the_argument_count_and_coerces_the_value() {
     let s = script();
@@ -1381,7 +1296,7 @@ fn set_max_letters_gates_the_argument_count_and_coerces_the_value() {
     s.run("E:SetMaxLetters(12)").unwrap();
     assert_eq!(max(&s), 12);
 
-    // nil is 0 is UNLIMITED — the call completes, which is the whole point.
+    // nil stores 0, which is unlimited.
     s.run("E:SetMaxLetters(nil)").unwrap();
     assert_eq!(max(&s), 0);
     s.run(r#"E:SetMaxLetters(5) E:SetText("abcdefgh")"#)
@@ -1401,7 +1316,6 @@ fn set_max_letters_gates_the_argument_count_and_coerces_the_value() {
     s.run("E:SetMaxLetters({})").unwrap();
     assert_eq!(max(&s), 0);
 
-    // The COUNT is exact — too few AND too many both raise.
     assert!(s.run("E:SetMaxLetters()").is_err(), "too few raises");
     assert!(
         s.run("E:SetMaxLetters(50, 60)").is_err(),
@@ -1409,18 +1323,9 @@ fn set_max_letters_gates_the_argument_count_and_coerces_the_value() {
     );
 }
 
-/// **A `CSimpleEditBox` is born with FIVE regions, and `GetRegions` hands them to Lua before any
-/// authored one.** wow-re `scratch/rf85-editbox-caret.md` §1: the ctor builds the text FontString
-/// (`E+0x328`, `0x779bee`), three selection-highlight `CSimpleTexture`s (`E+0x350/0x354/0x358`,
-/// loop `0x779c41`–`0x779c72`) and the caret (`E+0x368`, `0x779c86`) — in that order. `GetRegions
-/// 0x773f60` walks `[frame+0x1b8]`, one flat creation-ordered list, oldest first, no filter
-/// (`scratch/widget-list-bindings.md`), and insertion is at the TAIL. So the authored `<Layers>`
-/// regions start at index 6.
-///
-/// The report is pfUI's `skins/blizzard/friends.lua` l.379 —
-/// `local _,_,_,_,_,left,right = GuildControlPopupFrameEditBox:GetRegions()` — which skips exactly
-/// those five and takes the box's two border textures. It died on a nil `left` for as long as
-/// benilla returned only the authored regions.
+/// The ctor builds five regions in order, the text FontString (`0x779bee`), three selection
+/// textures (`0x779c41`-`0x779c72`) and the caret (`0x779c86`), and `GetRegions` (`0x773f60`)
+/// walks one creation-ordered list, so authored regions start at index 6.
 #[test]
 fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
     let s = script();
@@ -1443,8 +1348,7 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
     let report = crate::loader::load(&s, &doc, &|_| None);
     assert!(report.errors.is_empty(), "errors: {:?}", report.errors);
 
-    // Five engine regions, then the two authored textures — and NOT a sixth from the embedded
-    // `<FontString>`, which declares the ctor's object rather than adding one (RF-0028).
+    // The embedded `<FontString>` declares the ctor's text region, not a sixth (`0x779fb0`).
     assert_eq!(
         s.eval::<i64>("return Box:GetNumRegions()").unwrap(),
         7,
@@ -1456,7 +1360,6 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
         "GetNumRegions is exactly the length GetRegions enumerates"
     );
 
-    // pfUI's own read, verbatim in shape: skip five, take the authored pair.
     let (left, right) = s
         .eval::<(String, String)>(
             "local _,_,_,_,_,l,r = Box:GetRegions() return l:GetTexture(), r:GetTexture()",
@@ -1468,7 +1371,6 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
     );
     assert_eq!(right, r"Interface\Right", "region 7 is the second");
 
-    // The first is the text FontString the box actually types into.
     s.run(r#"Box:SetText("typed")"#).unwrap();
     assert_eq!(
         s.eval::<String>("local t = Box:GetRegions() return t:GetText()")
@@ -1476,8 +1378,7 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
         "typed",
         "region 1 is the ctor's embedded text FontString"
     );
-    // 2..5 are the three selection quads and the caret: real regions, carrying no art of their own
-    // (benilla paints both host-side — the gap named on EditBoxState).
+    // 2..5, the selection quads and the caret, carry no art: benilla paints both host-side.
     assert!(
         s.eval::<bool>(
             "local a,b,c,d,e = Box:GetRegions() \
@@ -1489,9 +1390,8 @@ fn an_editbox_is_born_with_the_ctors_five_regions_ahead_of_its_authored_ones() {
     );
 }
 
-/// `SetNumber` is `SetText` with Lua's own `%.14g` in front of it — the two bindings are
-/// byte-identical in the reference (`0x798690` / `0x7984c0`), so the numeric verb does no numeric
-/// work of its own. Decision 1831; the expected strings are the reference's executed output.
+/// `SetNumber` is `SetText` (`0x798690` and `0x7984c0` are byte-identical), so a number arrives
+/// through Lua's `%.14g`; the expected strings are the reference's own output.
 #[test]
 fn set_number_formats_like_the_references_printf() {
     let s = UiScript::new().unwrap();
@@ -1522,12 +1422,11 @@ fn set_number_formats_like_the_references_printf() {
         );
     }
 
-    // A STRING is accepted and passed through verbatim — the gate is `lua_isstring`, so the
-    // argument is never parsed as a number.
+    // A string passes verbatim: the gate is `lua_isstring`, and nothing parses it.
     s.run(r#"box:SetNumber("abc")"#).unwrap();
     assert_eq!(s.eval::<String>("return box:GetText()").unwrap(), "abc");
 
-    // Everything else raises, including an ABSENT argument. `luaL_error` does not return.
+    // Anything else raises, no argument included.
     for bad in [
         "box:SetNumber()",
         "box:SetNumber(nil)",
@@ -1537,10 +1436,8 @@ fn set_number_formats_like_the_references_printf() {
     }
 }
 
-/// A `numeric` box takes the reference's wholesale abort: the clear-all has already run when the
-/// insert fails the digit test, so the box is left EMPTY rather than partly filled. The money
-/// boxes (`MoneyInputFrame.xml`) are numeric, which is why this matters — though the money path
-/// itself only ever passes non-negative integers.
+/// A numeric box aborts the whole insert after the clear has run, so text that fails the digit
+/// test leaves it empty, not partly filled.
 #[test]
 fn set_number_on_a_numeric_box_empties_it_when_the_text_is_not_all_digits() {
     let s = UiScript::new().unwrap();
@@ -1550,7 +1447,6 @@ fn set_number_on_a_numeric_box_empties_it_when_the_text_is_not_all_digits() {
     s.run("box:SetNumber(1234)").unwrap();
     assert_eq!(s.eval::<String>("return box:GetText()").unwrap(), "1234");
 
-    // The minus sign fails the digit test, and the abort is wholesale.
     s.run("box:SetNumber(-5)").unwrap();
     assert_eq!(
         s.eval::<String>("return box:GetText()").unwrap(),
@@ -1559,8 +1455,8 @@ fn set_number_on_a_numeric_box_empties_it_when_the_text_is_not_all_digits() {
     );
 }
 
-/// `SetMaxBytes` (1960): the exact count gate and raw coerce of its sibling, a BYTE cap on the
-/// buffer, and -1 as the no-limit sentinel where `SetMaxLetters` reads 0.
+/// `SetMaxBytes`: `SetMaxLetters`'s exact count gate and raw coercion, a byte cap, and -1 as the
+/// no-limit sentinel.
 #[test]
 fn set_max_bytes_caps_the_buffer_in_bytes_with_minus_one_unlimited() {
     let s = script();
@@ -1588,14 +1484,10 @@ fn set_max_bytes_caps_the_buffer_in_bytes_with_minus_one_unlimited() {
     assert!(s.run("E:SetMaxBytes(1, 2)").is_err(), "too many raises");
 }
 
-/// **`OnCursorChanged(x, y, w, h)` fires when the caret moves** — the edge the shipped
-/// `MailFrame.xml` and `HelpFrame.xml` wire `ScrollingEdit_OnCursorChanged` to, and the reason a
-/// multiline box follows its caret as you type past the bottom (decision 2141).
-///
-/// The four args are the reference's (wow-re's RF-0085 caret law, VERIFIED): `x` the caret's
-/// advance along its line, `y` **negative-downward** by row (which is what
-/// `ScrollingEdit_OnCursorChanged`'s `cursorOffset = y` then `-this.cursorOffset` reads back as a
-/// positive distance), `w` the constant `4.0`, `h` the line height.
+/// `OnCursorChanged(x, y, w, h)` fires when the caret moves, with the reference's args
+/// (`0x77dd5f`, each scaled): `x` the advance along the line, `y` negative downward by row, `w`
+/// the constant 4, `h` the line height. Stock `ScrollingEdit_OnCursorChanged` reads `-y` as the
+/// distance down.
 #[test]
 fn the_caret_flush_fires_on_cursor_changed_with_the_references_four_args() {
     let mut s = script();
@@ -1615,14 +1507,13 @@ fn the_caret_flush_fires_on_cursor_changed_with_the_references_four_args() {
     )
     .unwrap();
     s.resolve();
-    // Three bytes on row 0, then a wrap onto row 1 — the host answers the rows and the pitch.
+    // Three bytes on row 0, then a wrap onto row 1; the host answers the rows and the pitch.
     for ch in "abcdef".chars() {
         s.char_input(&ch.to_string());
     }
     s.resolve();
     if let Some(req) = s.editbox_advances_request() {
-        // A plain monotonic 7 px/byte table (the rig's own), wrapped into two rows at byte 3 —
-        // `caret_row_x` subtracts the row start's cumulative advance, which is the whole point.
+        // 7 px per byte, wrapped into two rows at byte 3: `x` must count from the row's start.
         let cum: Vec<f32> = (0..=req.text.len()).map(|i| i as f32 * 7.0).collect();
         s.set_editbox_advances(req.id, req.key, cum, vec![0, 3], 12.0);
     }
@@ -1646,9 +1537,8 @@ fn the_caret_flush_fires_on_cursor_changed_with_the_references_four_args() {
     assert_eq!(w, 4.0, "w is the reference's constant, not a measurement");
     assert_eq!(h, 12.0, "h is the line height");
 
-    // **The edge is a CHANGE.** A tick that moves nothing fires nothing — which is what makes
-    // `ScrollingEdit_OnUpdate`'s `if (this.cursorOffset)` loop terminate instead of re-scrolling
-    // every frame.
+    // It fires on a change only, which lets `ScrollingEdit_OnUpdate`'s `if (this.cursorOffset)`
+    // settle instead of scrolling every frame.
     let before: i64 = s.eval("return table.getn(fires)").unwrap();
     s.tick(0.016);
     s.tick(0.016);
@@ -1658,7 +1548,6 @@ fn the_caret_flush_fires_on_cursor_changed_with_the_references_four_args() {
         "two quiet ticks fire nothing"
     );
 
-    // …and a caret move fires again.
     s.editbox_action(EditAction::Move {
         unit: EditUnit::Char,
         back: true,
diff --git a/crates/benilla-ui/src/script/event.rs b/crates/benilla-ui/src/script/event.rs
index 00d1dc6d..854788fd 100644
--- a/crates/benilla-ui/src/script/event.rs
+++ b/crates/benilla-ui/src/script/event.rs
@@ -1,21 +1,8 @@
-//! Handler firing — the FrameScript calling convention (RF-0025), for events, ticks, and
-//! show/hide transitions.
-//!
-//! Every handler is invoked through the *same* protected path, which reproduces both calling
-//! conventions the transition-era client supported (decision 0068):
-//!
-//! - **Legacy globals (RF-0025, byte-verified):** `this` = the firing frame's wrapper, `event` = the
-//!   event name (OnEvent only), `arg1..argN` = the args — each **set then restored** around the call
-//!   (`luaL_ref` saves the prior value; restored after), so nested fires are safe. The handler reads
-//!   its inputs as globals; the client `pcall`s with **nargs = 0**.
-//! - **Modern args:** the same values are *also* passed positionally as `(self, event, ...)` for
-//!   OnEvent (`(self, elapsed)` for OnUpdate, `(self)` for OnShow/OnHide/OnLoad) — the form Era
-//!   addons are written against.
-//!
-//! So inside one OnEvent handler `this == self` and `arg1` is the first positional argument (5.0's
-//! own `arg[1]`; `...` as a value, and `select` with it, are not in this dialect). Handler errors are
-//! caught (mlua's `Function::call` is a protected call) and returned to the caller, which records
-//! them in [`super::Model::errors`] — never a panic, never a print.
+//! Handler firing: the FrameScript calling convention for events, ticks and show/hide. The
+//! reference sets `this` (`0x872e64`), `event` (`0x84b648`) and `arg1..argN` (`0x8722dc`) around
+//! the call, restoring each after, and `pcall`s with no arguments; the handler here also gets the
+//! same values as `(self, event, ...)` arguments, which 1.12 does not pass.
+//! Handler errors return to the caller, which records them in [`super::Model::errors`].
 
 use std::borrow::Cow;
 
@@ -25,43 +12,14 @@ use super::{Model, ScriptValue, REG_SCRIPTS};
 use crate::script::object::frame_wrapper;
 use crate::widget::{ButtonState, FrameHandle};
 
-/// Fire `event` at every frame registered for it (the engine-internal twin of
-/// `UiScript::fire_event`, for engine code holding only the Lua context — the compare drive's
-/// `SHOW_COMPARE_TOOLTIP`), in registration order with per-step live re-reads (the FIFO law —
-/// see `fire_event`'s doc). Handler errors land in [`Model::errors`].
+/// `UiScript::fire_event` for engine code that holds only the Lua context.
 pub(super) fn fire_global(lua: &Lua, event: &str, args: &[ScriptValue]) {
-    let mut i = 0;
-    loop {
-        let id = {
-            let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            let Some(&h) = model.event_to_frames.get(event).and_then(|l| l.get(i)) else {
-                break;
-            };
-            model.frame_id(h)
-        };
-        if let Err(e) = fire_event_handler(lua, id, event, args) {
-            lua.app_data_mut::<Model>()
-                .expect("model app_data")
-                .errors
-                .push(e.to_string());
-        }
-        i += 1;
-    }
-    fire_all_event_listeners(lua, event, args);
+    super::tick::fire_event_into(lua, event, args.to_vec());
 }
 
-/// The `RegisterAllEvents()` half of one dispatch: every frame that asked for the whole stream,
-/// after the event's own listeners and skipping any frame that was already visited as one of them.
-///
-/// **After, and de-duplicated, because that is where such a frame would sit if the registration
-/// were expanded.** A frame joins the all-events set later than the frames already listening for a
-/// given event, so it takes the tail of that event's list; and a frame holding both an all-events
-/// registration and a `RegisterEvent` for *this* event is one listener, not two — `RegisterEvent`'s
-/// own `if !list.contains(&h)` is the same rule one level down.
-///
-/// Same mid-dispatch discipline as the walk above (`0x703ee8`, decision 1324): the next frame is
-/// re-found by position each step, so a handler that unregisters the walk's successor stops the
-/// dispatch there rather than robbing it.
+/// The `RegisterAllEvents()` half of a dispatch: the all-events frames, after the event's own
+/// listeners and skipping any already visited. The next frame is re-found by position each step
+/// (`0x703ee8`), so a handler that unregisters the walk's successor ends the dispatch there.
 pub(super) fn fire_all_event_listeners(lua: &Lua, event: &str, args: &[ScriptValue]) {
     let model_mut = || lua.app_data_mut::<Model>().expect("model app_data set");
     let mut at = model_mut().all_event_frames.first().copied();
@@ -81,8 +39,7 @@ pub(super) fn fire_all_event_listeners(lua: &Lua, event: &str, args: &[ScriptVal
             if let Err(e) = fire_event_handler(lua, id, event, args) {
                 lua.app_data_mut::<Model>()
                     .expect("model app_data")
-                    .errors
-                    .push(e.to_string());
+                    .record_script_error(e.to_string());
             }
         }
         at = next;
@@ -104,7 +61,7 @@ pub(super) fn fire_event_handler(
     fire(lua, id, "OnEvent", Some(event), extra)
 }
 
-/// Fire a frame's `OnUpdate` (RF-0025: `this` + `arg1 = elapsed`; modern `(self, elapsed)`).
+/// Fire a frame's `OnUpdate` with `arg1 = elapsed`.
 pub(super) fn fire_update_handler(lua: &Lua, id: u32, elapsed: f32) -> mlua::Result<()> {
     fire(
         lua,
@@ -115,12 +72,8 @@ pub(super) fn fire_update_handler(lua: &Lua, id: u32, elapsed: f32) -> mlua::Res
     )
 }
 
-/// Fire a plain widget handler — one that carries no `event` name: the mouse set
-/// (`OnEnter`/`OnLeave(self, motion)`, `OnMouseDown`/`OnMouseUp(self, button)`,
-/// `OnClick(self, button, down)`, `OnMouseWheel(self, delta)`) and the per-kind slots
-/// (`OnValueChanged(self, value)`). `extra` is the handler's arguments (the `arg1..argN` legacy
-/// globals plus the trailing modern positionals after `self`). Reuses the one [`fire`] path (so the
-/// wrapper lookup + set/restore convention stay in a single home); a no-op if no such script is set.
+/// Fire a handler that carries no `event` name (`OnEnter`, `OnClick`, `OnValueChanged`, ...), with
+/// `extra` as its `arg1..argN`; a no-op when the frame has no such script.
 pub(super) fn fire_widget_handler(
     lua: &Lua,
     id: u32,
@@ -130,20 +83,9 @@ pub(super) fn fire_widget_handler(
     fire(lua, id, script, None, extra)
 }
 
-/// Drain [`Model::pending_size_changed`] and fire `OnSizeChanged(self, width, height)` for each.
-///
-/// The resolve pass ([`super::UiScript::resolve_layout`]) only ever holds a `&mut Model` — three of
-/// its callers reach it that way — so it *queues* the frames whose resolved size moved and this
-/// runs at the next `&Lua` seam. Errors are recorded, never propagated: a handler blowing up must
-/// not abort a layout pass.
-///
-/// **Drains exactly once, deliberately.** A handler is free to resize things, `Show()` something,
-/// or call `UpdateScrollChildRect` — each of which can re-enter the resolver and queue *more*
-/// entries. Looping until the queue empties would let a handler that grows its own frame spin the
-/// engine forever inside one call; taking one batch instead leaves the next batch for the next
-/// resolve, which is exactly the reference's shape (its `ApplyRect` fires, the handler dirties the
-/// layout, and the *next* layout pass fires again). A genuinely oscillating handler oscillates at
-/// one fire per frame, visibly, instead of hanging the client.
+/// Drain [`Model::pending_size_changed`], queued by the resolve pass, and fire `OnSizeChanged` for
+/// each, recording errors. It drains once: a size a handler changes fires on the next resolve, as
+/// the reference's `ApplyRect` does, so a handler that grows its own frame cannot spin forever.
 pub(super) fn fire_size_changes(lua: &Lua) {
     let pending = std::mem::take(
         &mut lua
@@ -161,24 +103,15 @@ pub(super) fn fire_size_changes(lua: &Lua) {
         ) {
             lua.app_data_mut::<Model>()
                 .expect("model")
-                .errors
-                .push(e.to_string());
+                .record_script_error(e.to_string());
         }
     }
 }
 
-/// Fire `OnShow`/`OnHide` for a set of frames whose effective visibility just changed (from
-/// [`crate::widget::WidgetArena::set_shown`]/`set_parent`'s changed-list). Errors are recorded in
-/// [`Model::errors`] rather than propagated — a handler error must not abort the `Show()` call.
-///
-/// **This is also where the `toplevel` raise fires** (`effective_visible_show 0x76ae10` @`0x76aee0`,
-/// wow-re `ui/scratch/toplevel-raise.md`): the binary tests the toplevel bit and raises *after* the
-/// subtree's visibility has propagated and *before* that node's OnShow notify — which is exactly
-/// this seam, since the arena has finished propagating by the time it hands back the changed list.
-/// Per node and in list order, so a handler reading `GetFrameLevel()` sees the raised value the way
-/// it would in the reference. It lives here rather than at the Lua `Show` binding because *every*
-/// visibility transition this engine performs runs `0x76ae10` — an arena-level show from the
-/// tooltip path (or a future host one) must raise too, and a second seam is how that gets forgotten.
+/// Fire `OnShow`/`OnHide` for the frames whose effective visibility just changed, recording
+/// errors in [`Model::errors`]. A shown `toplevel` frame raises here, after the subtree has
+/// propagated and before its `OnShow` (`0x76ae10` at `0x76aee0`), so a show that does not come
+/// through Lua `Show` raises too.
 pub(super) fn fire_visibility_changes(lua: &Lua, changed: Vec<FrameHandle>) {
     // Resolve (handle, id, now-visible?) under one short borrow, then fire with no borrow held.
     let items: Vec<(FrameHandle, u32, bool)> = {
@@ -191,28 +124,17 @@ pub(super) fn fire_visibility_changes(lua: &Lua, changed: Vec<FrameHandle>) {
             })
             .collect()
     };
-    // **The hover-hide law** (wow-re `ui/scratch/hover-hide-and-tooltip-owner-law.md`, §5-
-    // arbitrated): hiding the hovered frame — directly or through an ancestor's cascade — fires
-    // its `OnLeave` SYNCHRONOUSLY, inside the hide and **before that frame's `OnHide`**
-    // (`0x764ba0`'s kind-2 tail runs mid-`effective_visible_hide`, the leave at `0x764cce`; the
-    // only silent case is destruction). It clears the hover cache and the drag-arm on that frame
-    // (`+0x100/+0x104`, the arg-1 flavor), and schedules the re-pick — the pump re-hovers
-    // whatever is now topmost at the unchanged cursor next tick ([`Model::hover_repick`]).
-    // A SHOW arms the re-pick too (`0x764b8d`: any mouse-bucket insert): a window opening under
-    // a stationary cursor gets hovered without a mouse move. This is what makes a slot button's
-    // FrameXML `OnLeave → GameTooltip:Hide()` actually run when its window closes under the
-    // cursor — the reference has NO engine-side owner-visibility fallback for the tooltip
-    // (byte-censused negative), so the leave firing here is the whole mechanism.
+    // Hiding the hovered frame, directly or by an ancestor, fires its `OnLeave` inside the hide and
+    // before its `OnHide` (`0x764ba0`'s tail in `0x76ad50`, the leave at `0x764cce`), clears the
+    // hover and the drag-arm (`+0x100`/`+0x104`) and arms the re-pick; a show arms it too
+    // (`0x764b8d`). This leave is how a tooltip closes with its window; the reference has no other.
     let left: Option<(FrameHandle, u32)> = {
         let mut model = lua.app_data_mut::<Model>().expect("model");
         let hidden_hover = model
             .mouseover
             .filter(|&m| items.iter().any(|&(h, _, vis)| h == m && !vis));
-        // The removal tail is a VIRTUAL dispatch — `0x764cce mov edx,[edi]; push 1;
-        // call [edx+0x50]` — so a Button reaches its own `0x7794e0`, whose DISABLED guard skips
-        // the base leave and with it the `<OnLeave>` script. Hiding a disabled hovered button is
-        // therefore as silent as walking off one ([`super::button::hover_notify_runs`]); the
-        // hover cache and the drag-arm still clear, because those are the *caller's* half.
+        // The leave is a virtual call (`0x764cce`, `[vtable+0x50]`): a disabled Button's own
+        // `0x7794e0` skips its `OnLeave`, while the hover and the drag-arm still clear.
         let notified = super::button::hover_notify_runs(&model, hidden_hover);
         if let Some(m) = hidden_hover {
             model.mouseover = None;
@@ -237,15 +159,8 @@ pub(super) fn fire_visibility_changes(lua: &Lua, changed: Vec<FrameHandle>) {
             let mut model = lua.app_data_mut::<Model>().expect("model");
             super::object::toplevel::raise_on_show(&mut model, h);
         } else {
-            // **The button's HIDE edge** — `CSimpleButton` overrides the hide notify (`+0x34`,
-            // `0x7791e0`) to un-press itself before tail-jumping the base, so a button hidden
-            // while held does not come back up wearing its pushed art (wow-re
-            // `scratch/button-state-edge-set.md`; the guard is `state != DISABLED && locked == 0`).
-            //
-            // It hangs off the VISIBILITY transition, not off the hover, which is what it is in
-            // the reference — a button hidden nowhere near the cursor un-presses too, and one
-            // hidden under the cursor no longer needs the hover-drop above to notice
-            // (decision 2134).
+            // `CSimpleButton`'s hide notify (`+0x34`, `0x7791e0`) un-presses it, unless disabled
+            // or locked, before the base notify, so a button hidden while held comes back unpushed.
             let mut model = lua.app_data_mut::<Model>().expect("model");
             super::button::edge(&mut model, h, ButtonState::on_hide);
         }
@@ -255,24 +170,15 @@ pub(super) fn fire_visibility_changes(lua: &Lua, changed: Vec<FrameHandle>) {
                 .expect("model")
                 .record_script_error(e.to_string());
         }
-        // **And the EditBox's own OnShow/OnHide vtable overrides** (`0x81c910` +0x30/+0x34): an
-        // `autoFocus` box grabs the keyboard when it appears if nothing else holds it, and hiding
-        // the box that holds it releases it. Both overrides call the base notify FIRST and act
-        // after, which is why this sits below the `fire` and not above it. A no-op for every frame
-        // that is not an EditBox. Here rather than at the Lua `Show`/`Hide` bindings for the same
-        // reason the toplevel raise is: every visibility transition this engine performs runs
-        // through this seam, and a second one is how a path gets forgotten.
+        // The EditBox show/hide overrides (`0x81c910` `+0x30`/`+0x34`) call the base notify first,
+        // so this runs after the `fire`: an `autoFocus` box takes a free focus, a hidden box
+        // releases its own.
         super::editbox::visibility_focus(lua, h, visible);
     }
 }
 
-/// Is a handler bound under `script` for this frame id? — the **existence** question, asked
-/// without firing anything.
-///
-/// It exists for the keyboard walk ([`super::keyboard`]), where the reference's consumption gate is
-/// the presence of the slot rather than anything the handler does: `0x76b7d0` reads `[+0x188]`/
-/// `[+0x190]`, consumes on either, and fires only the first. A lookup failure reads as "absent" —
-/// the gate must never be able to raise out of the middle of a walk.
+/// Whether a handler is bound under `script`, without firing it: the keyboard walk consumes on
+/// the slot's presence (`0x76b7d0`). A failed lookup reads absent, so the gate never raises.
 pub(super) fn has_widget_handler(lua: &Lua, id: u32, script: &str) -> bool {
     let Ok(scripts) = lua.named_registry_value::<Table>(REG_SCRIPTS) else {
         return false;
@@ -283,9 +189,8 @@ pub(super) fn has_widget_handler(lua: &Lua, id: u32, script: &str) -> bool {
     }
 }
 
-/// The one firing path. `event_name` is the `event` global + first modern positional (OnEvent only);
-/// `extra` are the `arg1..argN` globals + the trailing modern positionals. Globals are saved before
-/// and restored after (even on error) — nesting-safe. Holds no model borrow across the call.
+/// The one firing path: `event_name` is `OnEvent`'s, `extra` the `arg1..argN`. Holds no model
+/// borrow across the call.
 fn fire(
     lua: &Lua,
     id: u32,
@@ -293,7 +198,6 @@ fn fire(
     event_name: Option<&str>,
     extra: Vec<Value>,
 ) -> mlua::Result<()> {
-    // Look up the handler (Lua-side, transient handle). Absent ⇒ nothing to do.
     let scripts: Table = lua.named_registry_value(REG_SCRIPTS)?;
     let func: Function = match scripts.get::<Value>(id)? {
         Value::Table(per) => match per.get::<Value>(script)? {
@@ -304,24 +208,20 @@ fn fire(
     };
 
     let wrapper = frame_wrapper(lua, id)?;
-    // The attribution seam (decision 1395). Tight around the call and *after* `frame_wrapper` —
-    // which documents that callers hold no model borrow here, so the profiler's own borrow cannot
-    // land in the middle of one. Off, it is a relaxed load and a not-taken branch; the guard closes
-    // the fire on the way out of this scope, including an unwind.
+    // The profiler's fire opens after `frame_wrapper`, where no model borrow is held, and closes
+    // when the guard drops, unwinds included.
     let _fire =
         super::handler_prof::armed().then(|| super::handler_prof::Fire::open(lua, id, script));
     invoke_with_globals(lua, wrapper, &func, event_name, extra)
 }
 
-/// The legacy `argN` global names, pre-spelled through the arities that occur in practice so the
-/// per-arg save/set/restore below allocates nothing.
+/// The `argN` global names, spelled out so the common arities allocate nothing.
 const ARG_NAMES: [&str; 16] = [
     "arg1", "arg2", "arg3", "arg4", "arg5", "arg6", "arg7", "arg8", "arg9", "arg10", "arg11",
     "arg12", "arg13", "arg14", "arg15", "arg16",
 ];
 
-/// The global name for arg `i` — **1-based**, matching the globals themselves (`arg1..`). Past
-/// [`ARG_NAMES`] it falls back to allocating.
+/// The global name for arg `i`, 1-based like the globals.
 fn arg_name(i: usize) -> Cow<'static, str> {
     match ARG_NAMES.get(i - 1) {
         Some(&name) => Cow::Borrowed(name),
@@ -329,11 +229,9 @@ fn arg_name(i: usize) -> Cow<'static, str> {
     }
 }
 
-/// The RF-0025 calling convention itself — the single home for it, shared by [`fire`] (registry
-/// handlers: events, OnUpdate, OnShow/OnHide) and the loader's bottom-up `OnLoad` (which holds the
-/// compiled `Function` directly). Sets the legacy `this`/`event`/`arg1..argN` globals and passes the
-/// modern `(self[, event], extra…)` positionals, saving and restoring the globals around the call
-/// (even on error) so nested handler firing is safe.
+/// The calling convention, shared by [`fire`] and the loader's `OnLoad`: sets `this`, `event` and
+/// `arg1..argN`, passes `(self[, event], extra...)`, and restores the globals after the call, even
+/// on error, so nested fires are safe.
 pub(crate) fn invoke_with_globals(
     lua: &Lua,
     wrapper: Table,
@@ -366,7 +264,7 @@ pub(crate) fn invoke_with_globals(
     }
     modern.extend(extra.iter().cloned());
 
-    // Protected call. Capture the outcome, but restore globals first regardless.
+    // A protected call; the globals are restored before its outcome returns.
     let outcome = func.call::<()>(MultiValue::from_vec(modern));
 
     g.set("this", saved_this)?;
diff --git a/crates/benilla-ui/src/script/extract.rs b/crates/benilla-ui/src/script/extract.rs
index eb477f58..a8e6a946 100644
--- a/crates/benilla-ui/src/script/extract.rs
+++ b/crates/benilla-ui/src/script/extract.rs
@@ -1,7 +1,5 @@
-//! [`UiScript::extract`] — the render-list builder (decision 0068): the visible-tree
-//! [`crate::order::traversal`] zipped with the resolved rects and per-kind region visuals, in the
-//! client's painter order. An `impl UiScript` block beside its concern (the `layout.rs` pattern);
-//! the shared ScrollFrame clip it walks lives in [`super::clip`].
+//! [`UiScript::extract`], the render list: the visible-tree [`crate::order::traversal`] zipped
+//! with the resolved rects and region visuals, in the client's painter order.
 
 use crate::layout::Rect;
 use crate::order::{self, ZTarget};
@@ -11,20 +9,8 @@ use super::clip::{effective_clip, scroll_clip_sources};
 use super::{colorselect, slider, ExtractedQuad, FontObject, QuadContent, TexCoords, UiScript};
 
 impl UiScript {
-    /// **Every live draw target in the VM**, whether or not it is currently visible — each frame's
-    /// own slot followed by its region leaves, in arena order.
-    ///
-    /// [`Self::extract`] answers *what is being drawn*; this answers *what exists*, and the two
-    /// together are what let an instrument say **who drew a quad**. Diff this across a load and the
-    /// new targets are exactly the ones that load created: no name prefixes, no heuristics, and no
-    /// dependence on an addon naming anything at all. That is the oracle behind the addon
-    /// harness's render column, and it is written this way because the obvious alternatives are
-    /// both wrong — a with/without **quad-count diff** reads zero for an addon that *replaces* a
-    /// window rather than adding one (Bagnon takes the bags over), and a **name-prefix** match
-    /// cannot see an anonymous frame or a region an addon hangs off one of ours.
-    ///
-    /// Handles are generational, so a destroyed-and-reused slot can never be mistaken for a
-    /// survivor of the baseline.
+    /// Every live draw target, visible or not: each frame's slot then its regions, in arena order.
+    /// Handles are generational, so a diff across a load names exactly what the load created.
     pub fn live_targets(&self) -> Vec<ZTarget> {
         let model = self.model_ref();
         let mut out = Vec::new();
@@ -35,12 +21,7 @@ impl UiScript {
         out
     }
 
-    /// The frame a draw target belongs to — itself for a frame slot, the owner for a region.
-    ///
-    /// The half of the attribution that separates *created a window of its own* from *painted onto
-    /// one of ours*: a new `Region` whose owner frame is **not** new is an addon hooking an
-    /// existing frame, which is precisely what `!OmniCC` does to a cooldown and what a check built
-    /// only on new frames would score as "drew nothing".
+    /// The frame a draw target belongs to: itself for a frame slot, the owner for a region.
     pub fn target_frame(&self, target: ZTarget) -> Option<FrameHandle> {
         match target {
             ZTarget::Frame(fh) => self.model_ref().arena.frame(fh).map(|_| fh),
@@ -48,29 +29,17 @@ impl UiScript {
         }
     }
 
-    /// A frame's parent, or `None` for a top-level frame (or a stale handle).
-    ///
-    /// The other half of the attribution walk: a frame being **new** does not make it the addon's
-    /// own window — `!OmniCC` creates a brand-new anonymous frame *parented to one of our action
-    /// buttons*, and only the chain tells an overlay from a window.
+    /// A frame's parent, or `None` for a top-level frame or a stale handle.
     pub fn frame_parent(&self, frame: FrameHandle) -> Option<FrameHandle> {
         self.model_ref().arena.frame(frame)?.parent
     }
 
-    /// A frame's name, or `None` — it is anonymous, or the handle is stale.
-    ///
-    /// For reporting only. Nothing above depends on a frame being named; this is what turns an
-    /// attributed handle into a row a human can act on.
+    /// A frame's name, or `None` for an anonymous frame or a stale handle.
     pub fn frame_name(&self, frame: FrameHandle) -> Option<String> {
         self.model_ref().arena.frame(frame)?.name.clone()
     }
 
-    /// The nearest **named** frame at or above `target` — its own frame's name, else the closest
-    /// named ancestor.
-    ///
-    /// An addon's slot buttons are usually named and its inner art usually is not, so a bare
-    /// [`Self::frame_name`] would report a hole exactly where the interesting quads are. Walking up
-    /// answers "which window is this part of", which is the question a report is asking.
+    /// The name of the nearest named frame at or above `target`.
     pub fn target_owner_name(&self, target: ZTarget) -> Option<String> {
         let model = self.model_ref();
         let mut frame = match target {
@@ -87,17 +56,12 @@ impl UiScript {
         None
     }
 
-    /// The render list in the client's painter order (decision 0068): the visible-tree
-    /// [`crate::order::traversal`] zipped with the resolved rects and region visuals. Already sorted
-    /// ascending by `ZKey`. Call [`UiScript::resolve`] first for populated rects.
+    /// The render list in painter order, ascending by `ZKey`; call [`UiScript::resolve`] first.
     pub fn extract(&self) -> Vec<ExtractedQuad> {
         let model = self.model_ref();
         let list = order::traversal(&model.arena);
         let mut out = Vec::with_capacity(list.len());
-        // The ScrollFrame clip sources (decision 0112): every live ScrollFrame with a resolved rect
-        // and a live child, `child handle → the scrollframe's resolved rect`. Built once per extract;
-        // [`effective_clip`] walks a quad's owner up through this to find every ancestor ScrollFrame
-        // it is clipped by (nested ScrollFrames intersect).
+        // Scroll child → its ScrollFrame's rect; a quad clips to every ancestor ScrollFrame's.
         let scroll_sources = scroll_clip_sources(&model);
         for &(target, zkey) in list.iter() {
             let (rect, alpha, content, clip, scale) = match target {
@@ -106,18 +70,14 @@ impl UiScript {
                     let alpha = frame.map(|f| f.effective_alpha).unwrap_or(1.0);
                     let scale = frame.map(|f| f.effective_scale).unwrap_or(1.0);
                     let clip = effective_clip(&model, &scroll_sources, fh);
-                    // A Minimap widget's own slot carries its zoom out to the app renderer (the
-                    // tile/mask/arrow draw — decision 0203); every other frame slot is bare.
                     let content = match frame.map(|f| &f.kind_state) {
                         Some(crate::widget::KindState::Minimap(m)) => QuadContent::Minimap {
                             zoom: m.zoom,
                             inside_zoom: m.inside_zoom,
                         },
-                        // A `<Model>`/`<PlayerModel>` pane's content hole, carrying the pane's own
-                        // name so the app can join it to the bake that window keeps (see
-                        // [`QuadContent::ModelPane`]). Both widget kinds share `KindState::Model`
-                        // because the client's `CGCharacterModelBase` extends `CSimpleModel`, and
-                        // both draw the same way here.
+                        // A `<Model>`/`<PlayerModel>` pane's content hole, named so the app can
+                        // join it to that window's bake. Both kinds share `KindState::Model`, as
+                        // the client's `CGCharacterModelBase` extends `CSimpleModel`.
                         Some(crate::widget::KindState::Model(m)) => QuadContent::ModelPane {
                             handle: fh,
                             name: frame.and_then(|f| f.name.clone()),
@@ -145,22 +105,16 @@ impl UiScript {
                     let region = model.arena.region(rh);
                     let owner = region.map(|r| r.owner);
                     let owner_frame = owner.and_then(|o| model.arena.frame(o));
-                    // A draw layer switched off with `Frame:DisableDrawLayer` hides every region
-                    // the frame owns in it. Skipped HERE rather than by touching the regions
-                    // themselves, so each one keeps its own shown state and re-enabling the layer
-                    // restores exactly what was visible before.
+                    // A layer switched off by `Frame:DisableDrawLayer` hides its regions; skipped
+                    // here so each region keeps its own shown state for when the layer returns.
                     if let (Some(r), Some(f)) = (region, owner_frame) {
                         if f.disabled_layers & (1 << r.draw_layer.index()) != 0 {
                             continue;
                         }
                     }
-                    // Regions clip with their owner frame (decision 0112 §4).
                     let clip = owner.and_then(|o| effective_clip(&model, &scroll_sources, o));
                     let mut rect = owner.and_then(|o| model.resolved.get(&o).copied());
-                    // A StatusBar's bar-fill region draws at the value fraction of the frame's rect,
-                    // along the orientation axis (horizontal grows rightward, vertical bottom-up). The
-                    // bar owns its geometry — it never carries anchors, so it skips the region-rect
-                    // precedence below. It also CROPS: see `bar_fill_uv`.
+                    // A StatusBar's fill has no anchors: `bar_fill_rect` places it.
                     let mut bar_fill: Option<&crate::widget::StatusBarState> = None;
                     if let Some(crate::widget::KindState::StatusBar(sb)) =
                         owner_frame.map(|f| &f.kind_state)
@@ -170,30 +124,22 @@ impl UiScript {
                             bar_fill = Some(sb);
                         }
                     }
-                    // A Slider's thumb draws at the value fraction along the track (decision 0250 §4),
-                    // centered on the cross-axis — like the bar-fill, it owns its geometry and skips
-                    // the region-rect precedence below.
+                    // A Slider's thumb likewise: at the value fraction along the track.
                     let mut thumb_fill = false;
                     if let Some(crate::widget::KindState::Slider(sl)) =
                         owner_frame.map(|f| &f.kind_state)
                     {
                         if sl.thumb == Some(rh) {
-                            // The thumb's OWN size getters, not its authored `<Size>` — the same
-                            // `CSimpleTexture::GetWidth`/`GetHeight` fallback the drag law reads
-                            // (`slider::thumb_extent`), so a Lua-built `SetThumbTexture(path)` knob
-                            // draws at its art's texel span instead of smeared over the whole track.
+                            // The thumb's own `CSimpleTexture::GetWidth`/`GetHeight`, as the drag
+                            // reads them (`slider::thumb_extent`), not its authored `<Size>`.
                             let tsize = super::region::virtual_span(&model, rh);
                             rect = rect
                                 .map(|r| slider::thumb_rect(r, tsize, sl.vertical, sl.fraction()));
                             thumb_fill = true;
                         }
                     }
-                    // The colour picker's four sub-textures. The wheel and the strip are ordinary
-                    // authored regions — they keep their own anchors and resolve normally; all
-                    // they need from here is a content kind that says "the app paints this one".
-                    // The two markers are the opposite: their rects are DERIVED from the widget's
-                    // HSV, so the pixel you clicked is the pixel the marker lands on
-                    // (`colorselect::wheel_thumb_rect` is the exact inverse of the pick law).
+                    // The colour picker: the wheel and strip resolve like any region and the app
+                    // paints them; the markers' rects derive from the HSV, inverting the pick.
                     let mut color_art: Option<QuadContent> = None;
                     let mut color_thumb = false;
                     if let Some(crate::widget::KindState::ColorSelect(cs)) =
@@ -207,8 +153,8 @@ impl UiScript {
                                 .map(|w| colorselect::wheel_thumb_rect(w, tsize, cs.hsv));
                             color_thumb = true;
                         } else if cs.value_thumb == Some(rh) {
-                            // The strip anchors it; the WHEEL scales it (the client's own
-                            // unguarded `[this+0x318]` read — `colorselect::value_thumb_rect`).
+                            // The strip anchors it and the wheel scales it: the client's unguarded
+                            // `[this+0x318]` read.
                             let wheel = cs
                                 .wheel
                                 .and_then(|w| model.region_resolved.get(&w).copied());
@@ -226,65 +172,28 @@ impl UiScript {
                             });
                         }
                     }
-                    // A Button's state textures show by interaction state (the texture-array
-                    // "current" pointer): a non-current state texture emits no quad this frame.
-                    // The ButtonText additionally re-points to the current STATE's font instance
-                    // (disabled > highlighted > normal) — the client's per-state label font swap
-                    // (UIPanelButtonTemplate's gold/white/gray trio).
+                    // A Button's non-current state textures emit no quad, and its ButtonText takes
+                    // the current state's font instance (disabled > highlighted > normal).
                     let mut state_font: Option<&FontObject> = None;
                     let mut state_color: Option<[f32; 4]> = None;
-                    // The current instance's OWN justify (`<…Font justifyH=>`, a local write on
-                    // the embedded font — [`crate::widget::ButtonState::normal_justify_h`]).
                     let mut state_justify: Option<super::JustifyH> = None;
-                    // `Button:SetFont` — the face/size/flags written on the button's own embedded
-                    // fonts rather than on any object they inherit.
                     let mut button_font: Option<&crate::widget::ButtonFont> = None;
                     if let Some(crate::widget::KindState::Button(bs)) =
                         owner_frame.map(|f| &f.kind_state)
                     {
                         let hovered = owner.is_some() && model.mouseover == owner;
-                        // The PRESS is not read here. Which state texture shows is latched on the
-                        // transition (`ButtonState::set_state`), so the press reaches the paint
-                        // through the press EDGE at the moment the button goes down — not by
-                        // being re-derived every frame. `hovered` survives because the Highlight
-                        // is not a state texture and carries no latch.
+                        // The press is not read here: the state texture latches on the transition
+                        // (`ButtonState::set_state`). Only the Highlight, unlatched, reads hover.
                         if !bs.region_visible(rh, hovered) {
                             continue;
                         }
                         if bs.text == Some(rh) {
-                            // The label inherits ONE of the button's three embedded font instances
-                            // WHOLE (normal `+0x33c` / highlight `+0x3b8` / disabled `+0x434`): the
-                            // client swaps which instance the label reads, it does not merge axes
-                            // across them. So the object and the colour are picked as a PAIR, and a
-                            // state with no font object of its own is not in force at all — the
-                            // label stays on the normal instance, face and colour together.
-                            //
-                            // The pairing is the load-bearing half, and it is what this used to get
-                            // wrong (the colour fell back to `normal_color` while the font did not).
-                            // `UIDropDownMenu.lua` sets every row colour through `SetTextColor`
-                            // **and** `SetHighlightTextColor` with the same values (l.216-220,
-                            // l.829-830) — a second call it would never need if the first reached
-                            // the hovered state. The tradeskill list leans on the other direction:
-                            // its rows are `SetTextColor`'d to the recipe's difficulty and still
-                            // turn white under the cursor, because `<HighlightFont
-                            // inherits="GameFontHighlight">` is the instance in force there
-                            // (`ClassTrainerFrameTemplates.xml` l.74) and a normal-instance colour
-                            // cannot reach it.
-                            //
-                            // `LockHighlight()` counts as highlighted HERE too, not only for the
-                            // HighlightTexture in `region_visible`. `TradeSkillFrame_Update` blanks
-                            // a recipe row's highlight texture to `""` and *then* locks the row it
-                            // selected (Blizzard_TradeSkillUI.lua l.131/144) — with no texture left
-                            // to pin, the lock's only possible effect on that row is this label
-                            // swap, which is the white text on the selected recipe. Craft
-                            // (l.234) and the class trainer (l.183) lock the same way.
-                            //
-                            // INFERRED, not byte-verified: that an unset state instance leaves the
-                            // label on the normal one. A null slot in the *texture* array draws
-                            // nothing (decision 0227) and a font instance with no object cannot
-                            // work that way — a disabled button with no `<DisabledFont>` still
-                            // shows its label. Every state-colour caller in our own UI ships the
-                            // matching font object, so the two readings agree on all of them.
+                            // The label takes one embedded font instance whole (normal `+0x33c`,
+                            // highlight `+0x3b8`, disabled `+0x434`), so font and colour pair up;
+                            // a state lacking a font object stays on normal (inferred, not traced).
+                            // A locked highlight counts: the trade-skill list blanks the highlight
+                            // texture and locks the selected row (`Blizzard_TradeSkillUI.lua:133`,
+                            // `:144`), so this swap is its white text.
                             let highlighted = hovered || bs.locked_highlight;
                             let (name, color, justify) = if !bs.enabled()
                                 && bs.disabled_font.is_some()
@@ -313,87 +222,50 @@ impl UiScript {
                             state_justify = justify;
                         }
                     }
-                    // A TITLE REGION NEVER DRAWS. It is a hit rectangle, not a visual: wow-re
-                    // carves it as a plain Region with no textures at all
-                    // (`widget-api-batch-benilla.md` Q6). Falling through here would emit the
-                    // texture quad the `else` branch below builds — invisible on screen, but the
-                    // render report counts quads, so every addon that makes one would read as
-                    // "drew something" (1246's lesson about what an instrument is told).
+                    // A title region never draws: `CreateTitleRegion 0x773910` builds a plain
+                    // Region with no textures, a hit rectangle only.
                     if region.map(|r| r.kind) == Some(crate::widget::RegionKind::Title) {
                         continue;
                     }
-                    // Region-level Hide (the VisibleRegion bit): no quad at all — checked on the
-                    // borrow, BEFORE the clone below. `RegionData` is a fat row (text `String`,
-                    // paths, the anchors `Vec`), and paying its clone for a row whose next line
-                    // discards it was a per-hidden-region-per-frame allocation tax the extract
-                    // walk never noticed it was paying.
+                    // Hidden (the VisibleRegion bit): no quad; tested before the clone below.
                     let data_ref = model.region_data.get(&rh);
                     if data_ref.is_some_and(|d| d.hidden) {
                         continue;
                     }
-                    // THE NAMEPLATE GLOW IS SHOWN AND NOT DRAWN — the one region in the engine
-                    // whose paint the director replaced with something else (decision 0184: the
-                    // lit plate brightens its bar instead of wearing the additive rim). It has to
-                    // stay a real, shown, ADD-blended `Nameplate-Glow` region because
-                    // `glow:IsShown()` IS the mouseover signal every 1.12 nameplate addon reads —
-                    // so the deviation lives here, at the paint, and nowhere in the model.
+                    // Deviation: the nameplate glow is shown but never drawn, because its additive
+                    // rim reads as hard edge lines in our linear-blending pipeline; the lit plate
+                    // brightens its bar instead. It stays a real shown ADD region, as
+                    // `glow:IsShown()` is the mouseover signal 1.12 nameplate addons read.
                     if data_ref.is_some_and(super::nameplate::is_unpainted_glow) {
                         continue;
                     }
                     let mut data = data_ref.cloned().unwrap_or_default();
-                    // The single-hop draw multiply (`propagation.md`): the region's own alpha times
-                    // its immediate owner's — never a product up the tree, because the owner's own
-                    // `effective_alpha` was already overwritten by any ancestor's SetAlpha.
+                    // One hop (region combine `0x772180`): the region's alpha times its owner's
+                    // `effective_alpha`, which `SetAlpha 0x76a690` already carries down the tree.
                     let alpha = owner_frame.map(|f| f.effective_alpha).unwrap_or(1.0)
                         * data.alpha.unwrap_or(1.0);
                     if let Some(fo) = state_font {
-                        // The font object's paint, **behind the severance mask on every axis** —
-                        // the same `font_explicit` gate `font::repaint` applies and the
-                        // `button_font` block below names as the law ("it loses to a face the
-                        // label FontString set for *itself*, which severs one level further
-                        // down"). Three of these six axes did not have it: face and height were
-                        // `fo.x.or(data.x)`, which makes the OBJECT outrank an explicit
-                        // `SetFont`, and the outline was written unconditionally — so a label
-                        // that called `SetFont(path, h, "OUTLINE")` for itself had all three put
-                        // back from the object on the very next extract, every frame, forever.
-                        // That is the *shape* of the report this was found under (decision 2112:
-                        // an addon's `SetFont` silently not taking); MSBT's own strings are not
-                        // a button's label and never met it, but any addon that restyles a
-                        // `<ButtonText>` did.
+                        // The font object's paint, behind the severance mask (`font_explicit`) on
+                        // every axis as in `font::repaint`: an axis the label set itself stays.
                         if !data.font_explicit.face {
                             data.font_path = fo.font.clone().or(data.font_path);
                         }
                         if !data.font_explicit.height {
                             data.font_height = fo.height.or(data.font_height);
                         }
-                        // Same severance as the colour below: a region that called
-                        // `SetShadowColor`/`SetShadowOffset` keeps its own, or the font object it
-                        // inherits would silently overwrite the value the addon just set.
                         if !data.font_explicit.shadow {
                             data.font_shadow = fo.shadow.or(data.font_shadow);
                         }
                         if !data.font_explicit.outline {
                             data.outline = fo.outline;
                         }
-                        // Test the severance MASK, which is what the sentence above claims and what
-                        // wow-re pinned, not `vertex_color.is_none()`. The nil-check was an
-                        // equivalent proxy for exactly as long as an explicit `SetTextColor` was the
-                        // only way a button label's colour could be populated at all; the moment
-                        // `SetTextFontObject` began linking the label to its font object (so
-                        // `GetFont`/`GetFontObject` stop answering nil), a label carried the NORMAL
-                        // object's colour and the disabled state's gray silently stopped applying.
-                        // Caught by `button_label_repaints_by_state_font_object`, which is the test
-                        // that exists for this.
+                        // The mask, not `vertex_color.is_none()`: a label linked to its font object
+                        // already carries the normal object's colour.
                         if !data.font_explicit.color {
                             data.vertex_color = fo.color.or(data.vertex_color);
                         }
-                        // The instance's justify: its own `<…Font justifyH=>` (a local write on
-                        // the embedded font, decision 1996), else the object's. Between frames
-                        // the label's own word carries the NORMAL instance's value
-                        // (`button::apply_normal_font`, the live link); a hover or a disable swaps
-                        // it here the way the client re-links the label to another instance
-                        // (`0x779810`) — behind the severance mask like every other axis, so a
-                        // label that `SetJustifyH`'d for itself keeps its own.
+                        // The instance's own `justifyH`, else the object's; a hover or disable
+                        // swaps it here, as the client re-links the label (`0x779810`).
                         if !data.font_explicit.justify_h {
                             if let Some(j) = state_justify.or(fo.justify_h) {
                                 data.justify.set_h(j);
@@ -405,12 +277,9 @@ impl UiScript {
                             }
                         }
                     }
-                    // `Button:SetFont` sits BETWEEN the two: it is a local set on the button's own
-                    // embedded font, so it outranks the font object that font inherits (a locally
-                    // set axis severs inheritance and is never restored — wow-re
-                    // `font-object-lua-surface.md`), but it loses to a face the label FontString
-                    // set for *itself*, which severs one level further down. That is what
-                    // `font_explicit` is, so it is the gate here too.
+                    // `Button:SetFont` sits between: a local set on the embedded font outranks its
+                    // object (clearing the `inheritMask` bit, `CSimpleFontString+0xD4`, for good)
+                    // but loses to the label's own, so `font_explicit` gates it too.
                     if let Some(bf) = button_font {
                         if !data.font_explicit.face {
                             data.font_path = Some(bf.path.clone());
@@ -422,25 +291,14 @@ impl UiScript {
                             data.outline = super::Outline::flags(&bf.flags);
                         }
                     }
-                    // The button-level state color wins over the font object AND the region's own
-                    // explicit color — the client's Button color slots repaint the label outright.
+                    // The state colour repaints the label outright, even over its own colour.
                     if let Some(c) = state_color {
                         data.vertex_color = Some(c);
                     }
-                    // A region draws at its RESOLVED rect, and nothing else (decision 1310,
-                    // superseding 0068 v1's centered/fill-the-owner fallbacks): every drawable
-                    // region carries real anchors — authored, or the creation-path implicit anchor
-                    // (`region::implicit_creation_anchor`) — and the real resolver has no
-                    // zero-anchor fallback (a failed resolve latches unresolvable, `0x768d55`). A
-                    // region with no rect here is a templateless Lua region nobody anchored, and
-                    // the reference draws it nowhere. The bar-fill/thumb regions keep their own
-                    // fraction geometry (computed off the owner rect above) — they never carry
-                    // anchors and skip the resolver entirely, like the reference's own bar path.
-                    // The bar-fill CROPS its texture (wow-re `nameplate-vkey.md`, VERIFIED): every
-                    // `SetValue` rewrites the region's 4-corner UV block with `u1 = fraction` and
-                    // recomputes the quad as `right = left + frac·width`. So the art is sliced, never
-                    // squeezed — a bar texture with a horizontal ramp (`UI-StatusBar` brightens 124→166
-                    // left-to-right) keeps its true gradient at every fill level.
+                    // A region draws at its resolved rect only: drawable regions carry anchors
+                    // (authored, or `region::implicit_creation_anchor`) and a failed resolve
+                    // latches unresolvable (`0x768d55`), so an unanchored Lua region draws nowhere,
+                    // as in the reference. The bar fill and thumbs keep their fraction geometry.
                     if let Some(sb) = bar_fill {
                         data.tex_coords = Some(bar_fill_uv(data.tex_coords, sb));
                     }
@@ -451,9 +309,7 @@ impl UiScript {
                         region.map(|r| r.kind),
                         Some(crate::widget::RegionKind::FontString)
                     );
-                    // The generated art wins only over an EMPTY slot: an addon that sets a real
-                    // texture on the wheel region gets its texture, the way it would on any other
-                    // region. (`ColorPickerFrame.xml` sets none, which is the whole point.)
+                    // Generated art fills only an empty slot (`ColorPickerFrame.xml` sets none).
                     let content = if let Some(art) =
                         color_art.filter(|_| data.texture.is_none() && data.fill.is_none())
                     {
@@ -472,27 +328,14 @@ impl UiScript {
                             shadow: data.font_shadow,
                             outline: data.outline,
                             alpha_gradient: data.alpha_gradient,
-                            // A property of the OWNER, not of the string: the plate's own name
-                            // and level and an addon's replacements for them are all drawn
-                            // inside the same sliding rect.
+                            // The owner's property: an addon's strings on a plate slide with it.
                             world_seat: owner
                                 .is_some_and(|o| super::nameplate::is_world_seated(&model, o)),
                         }
                     } else {
-                        // The draw gate is the TEXTURE slot, never the colour (`0x7706e0`: `+0xcc`
-                        // empty -> emit NOTHING — `texture-color-composition.md` §4, VERIFIED). A
-                        // vertex colour is a tint on whatever texture exists; alone it is not
-                        // drawable content — it survives `SetTexture(nil)` by design ("a tint
-                        // outlives the art it was tinting") and used to leak out of here as a
-                        // solid plate the moment the art was cleared (the white action buttons on
-                        // a character switch; the 2026-07-10 grey wells were the same class).
-                        // A GRADIENT is drawable content in its own right — the client generates it
-                        // into the same texture slot the colour form of `SetTexture` fills, so a
-                        // region carrying only a gradient still paints. Folded to its midpoint here
-                        // because a quad carries ONE tint; the whole gradient stays on the region
-                        // (`RegionData::gradient`) so a renderer that grows a second stop needs no
-                        // API change. The approximation is visible, and it is stated there and here
-                        // rather than discovered later.
+                        // The draw gate is the texture slot, never the colour (`0x7706e0`: empty
+                        // `+0xcc` emits nothing); a vertex colour alone is a tint. A gradient fills
+                        // the texture slot, so it draws, at its midpoint since a quad has one tint.
                         let fill = data.fill.or_else(|| data.gradient.map(|g| g.midpoint()));
                         let has_path = data.texture.is_some();
                         let has_texture = has_path || fill.is_some();
@@ -501,42 +344,28 @@ impl UiScript {
                             color: has_texture
                                 .then(|| texture_color(fill, data.vertex_color))
                                 .flatten(),
-                            // ADD is the one blend mode the renderer acts on; the other four of
-                            // the client's `alphaMode` enum are carried on `RegionData::blend`
-                            // (and answered by `GetBlendMode`) but drawn as straight alpha — the
-                            // stated v1 gap, see [`crate::script::BlendMode`].
+                            // The renderer acts on ADD only: the other four `alphaMode` values
+                            // answer `GetBlendMode` but draw as straight alpha.
                             additive: data.blend == crate::script::BlendMode::Add,
                             tex_coords: data.tex_coords,
                             circular: data.circular,
                             portrait_unit: data.portrait_unit,
                             rotation: data.rotation,
-                            // Only ever set against real ART. A pathless solid has its colour
-                            // FOLDED into `color` two lines up (the renderer draws it as a tint on
-                            // a 1x1 white texel), so a shader that greys the *texel* would grey
-                            // white and change nothing — the flag would read as honoured while
-                            // doing nothing at all. No reference consumer desaturates a solid;
-                            // every one of them is an icon. Stated here rather than discovered.
+                            // Real art only: a solid here is a tint on a white texel, where the
+                            // reference's is a texel block it would grey. No stock caller
+                            // desaturates a solid.
                             desaturated: data.desaturated && has_path,
                         }
                     };
-                    // A region draws at its owner's scale — same single hop as alpha (a region
-                    // has no scale of its own; `propagation.md`'s product lives on frames).
+                    // A region draws at its owner's scale: only frames carry one (`0x76ac90`).
                     let scale = owner_frame.map(|f| f.effective_scale).unwrap_or(1.0);
                     (rect, alpha, content, clip, scale)
                 }
             };
-            // **A `Model` frame's scene draws out of its bucket's ARTWORK batch, last** — wow-re
-            // `ui/scratch/model-frame-draw-order.md` (2026-09-04): the batch object carries a
-            // third sub-array beside the quads and the text, a render-callback list, and
-            // `0x76fb00` drains the three in that order; `0x76d160` registers the model's callback
-            // only for `layer == 2` (`0x76d17f cmp ebx,2`). So a model is neither a separate pass
-            // nor the frame's own layer-0 slot — it is ARTWORK content, after that layer's quads.
-            // This is what puts the world map's player arrow over the zone overlays: both frames
-            // sit at `WorldMapFrame.level + 1`, the overlays are ARTWORK quads there, and the
-            // arrow's callback drains after them (the director's report, and the case the carve
-            // was dispatched on). A model's own OVERLAY/HIGHLIGHT regions still draw over it. The
-            // CALLBACK rank (1995) is what puts the scene after that layer's font strings too,
-            // whatever their link stamps — the content key alone sat at the text rank.
+            // A `Model` frame's scene draws in its bucket's ARTWORK batch, last: `0x76fb00` drains
+            // quads, text, then render callbacks, and `0x76d160` registers the model's callback
+            // for layer 2 only (`0x76d17f cmp ebx,2`). So the world map's player arrow draws over
+            // the zone overlays at the same level, below its own OVERLAY and HIGHLIGHT regions.
             let z = match &content {
                 QuadContent::ModelPane { .. } => zkey.callback(order::DrawLayer::Artwork).raw(),
                 _ => zkey.raw(),
@@ -550,18 +379,11 @@ impl UiScript {
                 clip,
                 scale,
             });
-            // A ScrollingMessageFrame emits, on top of its own (empty) frame slot, one Text quad per
-            // visible ring line — stacked bottom-up (newest at the frame's bottom edge), each carrying
-            // its live fade alpha in the text color. The generic region path can't do this (the lines
-            // aren't declared FontStrings); the ring lives in the frame's kind state.
+            // A ScrollingMessageFrame adds one Text quad per visible ring line, stacked bottom-up
+            // with each line's fade alpha; the ring lives in its kind state, not in FontStrings.
             if let (ZTarget::Frame(fh), Some(fr)) = (target, rect) {
-                // The frame's own draw slot carries its Backdrop, behind its regions (which sort
-                // after the frame slot). A ScrollingMessageFrame's ring lines do NOT: they take the
-                // slot's ARTWORK *content* key ([`crate::order::ZKey::content`]) — the layer the
-                // client's own message font strings live in — so the frame's BACKGROUND textures
-                // stay behind them. At the bare slot the chat window's hover box painted over its
-                // own messages. Both clip like the frame's own slot (the frame IS the clipped owner
-                // when it's a scroll child).
+                // The Backdrop draws at the frame slot; the lines take the ARTWORK content key,
+                // where the client's message strings live, over the BACKGROUND (hover box) art.
                 let paint = super::layout::FramePaint { alpha, scale };
                 Self::emit_backdrop(&model, fh, fr, zkey.raw(), paint, clip, &mut out);
                 Self::emit_message_lines(
@@ -579,25 +401,11 @@ impl UiScript {
     }
 }
 
-/// The single colour a Texture region draws with: **`texel × vertexColour`**, per channel and
-/// **alpha included** (wow-re `system/ui/scratch/texture-color-composition.md`, VERIFIED — the
-/// stage-0 combine's `MODULATE(TEXTURE, DIFFUSE)` for both colour and alpha).
-///
-/// **That law is scoped to a region with no pixel shader bound** (`+0x128 == 0` — wow-re
-/// `texture-desaturate-law.md` §6.1's correction to that note). A DESATURATED region takes the
-/// fragment program instead, which supersedes the whole stage chain and reads the vertex colour's
-/// ALPHA only; its RGB never reaches the pixel. The colour computed here still travels — the
-/// renderer needs the alpha, and the RGB is simply unread on that branch (`ui_quad.wgsl`) — so
-/// nothing changes here, but the note this cites no longer says what it used to.
-///
-/// `fill` is the region's own solid-colour texture ([`RegionData::fill`] — the client generates a
-/// real 8×8 texel block from it), so where it is set it IS the texel and the product is the drawn
-/// colour. Where it isn't, the texel comes from `path`'s art and this returns the tint alone for the
-/// renderer to modulate the sample by; `None` means untinted.
-///
-/// The correction this encodes: a `<Color 1,1,1,0.2>` trough later `SetVertexColor(0,0,0.75,0.5)`'d
-/// draws at alpha **0.1**. benilla used to store one colour slot and let the second call *replace*
-/// the first, which drew it at 0.5.
+/// The colour a Texture region draws with: texel × vertex colour per channel, alpha included (the
+/// stage-0 combine preset at submit, `.data 0x85c250` index 1: `MODULATE(TEXTURE, DIFFUSE)`). A
+/// desaturated region's pixel shader (`+0x128`) reads only the vertex alpha. `fill`, the region's
+/// solid colour, is a real 8×8 texel block in the client, so where set the product is the drawn
+/// colour; otherwise this is the tint the renderer modulates the art by, `None` for untinted.
 fn texture_color(fill: Option<[f32; 4]>, vertex: Option<[f32; 4]>) -> Option<[f32; 4]> {
     match (fill, vertex) {
         (Some(f), Some(v)) => Some([f[0] * v[0], f[1] * v[1], f[2] * v[2], f[3] * v[3]]),
@@ -606,9 +414,8 @@ fn texture_color(fill: Option<[f32; 4]>, vertex: Option<[f32; 4]>) -> Option<[f3
     }
 }
 
-/// A StatusBar's bar-fill rect: the frame rect scaled by the value fraction — rightward from the
-/// left edge (horizontal) or upward from the bottom (vertical), the documented fill directions
-/// (reverse-fill is an Era extension, not modeled yet).
+/// A StatusBar's fill rect: the frame rect scaled by the value fraction, rightward from the left
+/// edge or upward from the bottom (1.12 has no reverse fill).
 fn bar_fill_rect(r: Rect, sb: &crate::widget::StatusBarState) -> Rect {
     let f = sb.fraction();
     if sb.vertical {
@@ -618,18 +425,13 @@ fn bar_fill_rect(r: Rect, sb: &crate::widget::StatusBarState) -> Rect {
     }
 }
 
-/// A StatusBar's bar-fill UV sub-rect: `base` (its `<TexCoords>`/`SetTexCoord`, or the full texture)
-/// sliced to the value fraction along the fill axis — `[left, right, top, bottom]`, 0..1, top-left
-/// origin.
-///
-/// The client CROPS rather than scales (wow-re `nameplate-vkey.md`, VERIFIED): `SetValue`
-/// (`0x7cc450`→`0x7833c0`) drives `0x770410`, which writes the 4-corner UV block (`+0x104..+0x120`)
-/// with `u1 = GetValue()` and recomputes `right = left + frac·width`. Horizontal is the verified
-/// case; VERTICAL mirrors it up the `v` axis (bottom-up fill ⇒ the *bottom* edge of the art is
-/// pinned) — inferred from the same block, not separately pinned.
+/// A StatusBar's fill UVs: `base` (its `<TexCoords>`/`SetTexCoord`, or the full texture) cut to
+/// the value fraction along the fill axis, `[left, right, top, bottom]` in 0..1 from top-left. The
+/// client crops rather than scales: `SetValue` (`0x7cc450` → `0x7833c0`) drives `0x770410`, which
+/// writes the 4-corner UV block (`+0x104..+0x120`) with `u1` set to the fill fraction. Vertical
+/// mirrors it up `v`, pinning the art's bottom edge (inferred, not traced).
 fn bar_fill_uv(base: Option<TexCoords>, sb: &crate::widget::StatusBarState) -> TexCoords {
-    // The fill crop is inherently the 4-edge form; an affine base (no live StatusBar uses one)
-    // contributes its bounding edges.
+    // An affine base contributes its bounding edges (no live StatusBar uses one).
     let [l, r, t, b] = base.map(|tc| tc.edges()).unwrap_or([0.0, 1.0, 0.0, 1.0]);
     let f = sb.fraction();
     TexCoords::Rect(if sb.vertical {
diff --git a/crates/benilla-ui/src/script/follow.rs b/crates/benilla-ui/src/script/follow.rs
index 8d90692c..4fc33bbf 100644
--- a/crates/benilla-ui/src/script/follow.rs
+++ b/crates/benilla-ui/src/script/follow.rs
@@ -1,44 +1,22 @@
-//! The auto-follow **Era API surface** — two globals, no state.
-//!
-//! [`super::duel`]'s shape exactly: everything the UI *reads* about a follow arrives as an event
-//! argument (`AUTOFOLLOW_BEGIN`'s name), so there is no snapshot to push — only the outbound half.
-//! Each call queues a [`FollowRequest`] the app drains ([`super::UiScript::take_follow_requests`])
-//! and turns into its own follow start, keeping the engine free of ECS reach (decision 0068 §3).
-//!
-//! The two are the reference's own follow bindings, and between them they cover every shipped call
-//! site in the 1.12 FrameXML:
-//!
-//! | binding | called by | subject |
-//! |---|---|---|
-//! | `FollowUnit(unit)` | `SlashCmdList["FOLLOW"]` with no argument | a unit token |
-//! | `FollowByName(name, exactMatch)` | `SlashCmdList["FOLLOW"]` with one; `UnitPopup_OnClick`'s FOLLOW row | a name |
-//!
-//! `FollowByName` is `0x489ec0`, one more caller of the shared by-name resolver `0x493aa0` —
-//! typemask `0x10` (players only) and filter mode 2 (`CanAssist` + alive), with **the second Lua
-//! argument steering exact-only matching** (decision 0886's table). That argument is what makes the
-//! popup row different from the slash command: `UnitPopup.lua` passes `FollowByName(name, 1)`, so
-//! clicking *Follow* on a menu that already names the unit exactly must not prefix-match its way
-//! onto somebody else standing nearby, while `/follow rag` still may.
-//!
-//! benilla parses slash lines in Rust rather than in Lua (decision 0881), so the chat half of that
-//! table enters the app's follow funnel directly; these globals are the *other* half — the shipped
-//! UI's, and any addon's.
+//! `FollowUnit` and `FollowByName`; each call queues a [`FollowRequest`] the app drains.
+//! `FollowUnit("target")` is a bare `/follow` and the `FOLLOWTARGET` binding. `FollowByName`
+//! (`0x489ec0`) calls the by-name resolver `0x493aa0` for players (`0x10`) who `CanAssist` and are
+//! alive, with its second argument as the exact-only flag: `UnitPopup.lua:623` passes 1, so the
+//! menu never prefix-matches someone else, while `/follow rag` may. benilla parses `/follow` in
+//! Rust, so these globals serve the stock UI and addons.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// Outbound follow intents queued by the Era API calls, drained by the app
-/// ([`super::UiScript::take_follow_requests`]). Plain data — [`super::duel::DuelRequest`]'s twin.
+/// A follow intent queued by the globals.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum FollowRequest {
-    /// `FollowUnit(unit)` — follow whoever a unit token points at. The app resolves the token;
-    /// `"target"` is the bare `/follow`, and takes the selection **whatever it is** (the reference
-    /// applies no typemask on this path — decision 0890).
+    /// `FollowUnit(unit)`: whoever the token names, of any type; the reference applies no
+    /// typemask here.
     ByUnit(String),
-    /// `FollowByName(name, exactMatch)` — follow a player found by name. `exact` is the second Lua
-    /// argument: set, it skips the resolver's longest-common-prefix tier and admits only a
-    /// whole-string (case-insensitive) hit.
+    /// `FollowByName(name, exactMatch)`: with `exact`, the resolver skips its longest-prefix tier
+    /// and takes only a whole-name, case-insensitive match.
     ByName { name: String, exact: bool },
 }
 
@@ -49,11 +27,10 @@ impl super::UiScript {
     }
 }
 
-/// Register the follow globals (the same style/place [`super::duel`] registers its own).
+/// Register the follow globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // FollowUnit(unit) — `SlashCmdList["FOLLOW"]`'s no-argument arm, `FollowUnit("target")`.
     g.set(
         "FollowUnit",
         lua.create_function(|lua, unit: String| {
@@ -63,16 +40,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // FollowByName(name, exactMatch) — the unit popup's Follow row passes `1`; the slash command
-    // passes nothing, which is the prefix-matching case (`nil` is false here, as in the ref, where
-    // the argument reaches `0x493aa0` as a plain zero).
     g.set(
         "FollowByName",
         lua.create_function(|lua, (name, exact): (String, Option<mlua::Value>)| {
-            // Absent is the slash command's case; the popup row passes `1`. A numeric zero counts
-            // as false as well — no shipped caller passes one, and treating it that way is the
-            // reading both plausible arg-2 fetches on the C side (`lua_toboolean` vs a number
-            // compare) agree on for every value that can actually arrive here.
+            // The reference reads this with `GetBoolOrDefault` (`0x6f1c10`), default false; here
+            // nil, false and 0 are false and any other value is true.
             let exact = match exact {
                 None | Some(mlua::Value::Nil) | Some(mlua::Value::Boolean(false)) => false,
                 Some(mlua::Value::Integer(n)) => n != 0,
diff --git a/crates/benilla-ui/src/script/font.rs b/crates/benilla-ui/src/script/font.rs
index 35f6ac64..cd68b0a2 100644
--- a/crates/benilla-ui/src/script/font.rs
+++ b/crates/benilla-ui/src/script/font.rs
@@ -1,73 +1,25 @@
-//! **Font objects as first-class Lua objects** — a `<Font name="GameFontNormal">` is not merely a
-//! style record the loader flattens, it is an *object* the client publishes as the global
-//! `GameFontNormal`, with its own method table.
+//! Font objects: a `<Font name=…>` or a `CreateFont` font is a Lua object, published as the global
+//! of its name with its own method table. Stock FrameXML never calls this API; addons do.
 //!
-//! ## Why this exists
+//! The reference's class is `CSimpleFont` (`0x87a454`). Its method table (`0x87c7c8`) has 22
+//! entries (`mov edx,0x16` at `0x7a10d5`), and its lookup `0x7a1100` has no base-class fallback.
+//! All are here but the `SetSpacing` pair ([`install`]); `CopyFontObject` is the one a FontString
+//! lacks. A named font is published by `0x783870` through `SetName 0x784150` and `CreateLuaHandle
+//! 0x701bd0`, which leaves a non-nil `_G[name]` alone (`0x701cb8`).
 //!
-//! 1.12's own FrameXML never touches the API — `grep -c FontObject` over
-//! `wow-5875-re/WoW/_extracted_framexml/*.lua` is **0** — so the whole surface is addon-facing, and
-//! the corpus (`/Users/sam/dev/wow-addons-vanilla`, 218 addons) is where the demand is:
+//! A setter repaints every FontString that inherits the font. The reference links dependents into
+//! the font's list (`+0x74`/`+0x78`) and each setter ends in `NotifyDependents 0x784180`, calling
+//! `OnFontChanged` (`0x77e4b0` on a font, `0x773530` then `0x770800` on a FontString); here each
+//! setter writes the [`FontObject`] and calls [`propagate`]. A local setter clears its property's
+//! bit in the dependent's inherit mask (`+0x2c`, FontString `+0xd4`) and nothing restores it, so a
+//! colour set on a FontString survives a later `SetFontObject`: [`RegionData::font_explicit`] is
+//! that mask. `+0x38` is not it; its high bits mark a held value, which the inheriting merge also
+//! sets (`0x7709d3`).
 //!
-//! | call shape | sites | note |
-//! |---|---|---|
-//! | `x:SetFontObject(GameFontNormal)` (bare global) | 3,180 | the form we did **not** accept |
-//! | `x:SetFontObject("GameFontNormal")` (string) | 6 | the only form we did accept |
-//! | `x:GetFontObject():GetTextColor()` | 65 | needs an OBJECT back, not a name |
-//! | `GameTooltipHeaderText:GetFont()` and kin | 268 | `Tablet-2.0`'s header-size probe |
-//! | `GameFont*:GetTextColor/GetShadowOffset/GetShadowColor` | 13 | |
-//! | `CreateFont(name)` | 3 | `_Nameplates`, `!OmniCC`, `FonzAppraiser` |
-//! | `f:CopyFontObject(GameFontHighlightSmall)` | 1 | Font-on-Font |
-//!
-//! ## The method surface, and where it came from
-//!
-//! §5-verified in wow-re, `system/ui/scratch/font-object-lua-surface.md` (landed `0193861a`). The
-//! Font method table is `.data 0x87c7c8` with **22 entries** — the count read from `mov edx,0x16`
-//! at `0x7a10d5`, not from a run-length scan, which merges neighbouring tables and reports a bogus
-//! 54. Its lookup `0x7a1100` has **no base-class fallback**, so 22 is the entire surface:
-//! `GetObjectType · IsObjectType · GetName · SetFontObject · GetFontObject · CopyFontObject ·
-//! SetFont · GetFont · SetAlpha · GetAlpha · SetTextColor · GetTextColor · SetShadowColor ·
-//! GetShadowColor · SetShadowOffset · GetShadowOffset · SetSpacing · GetSpacing · SetJustifyH ·
-//! GetJustifyH · SetJustifyV · GetJustifyV`. All implemented here **except the `Spacing` pair** —
-//! see [`install`]. `CopyFontObject` is the only one of the 22 a FontString does not also have.
-//!
-//! The class is **`CSimpleFont`** (`__FILE__` `0x87a454`), and a named font is published by
-//! `0x783870` → `SetName 0x784150` → `CreateLuaHandle 0x701bd0` → `_G[name] = handle` at
-//! `0x701cb8`, **skipped when the global is already non-nil** — the same non-overwriting rule
-//! [`publish_global`] applies on the frame side.
-//!
-//! ## Mutability — the deliberate part
-//!
-//! `GameFontNormal:SetFont(…)` on the real client repaints every FontString that inherits it, and
-//! the mechanism is not a copy: `SetFontObject` stores a parent pointer (`+0x28`, FontString
-//! `+0xd0`) **and** links the instance into the parent's intrusive dependents list (`+0x74`/`+0x78`,
-//! link offset `+0x70`). Every setter ends in `vtable[+0x14]` = `NotifyDependents 0x784180`, which
-//! walks that list and calls each dependent's `OnFontChanged` — `0x77e4b0` for a font (which
-//! cascades) and `0x773530`→`0x770800` for a FontString (which re-drives its real setters).
-//!
-//! We model that with an eager push instead of an intrusive list, so no reader changes: every
-//! setter here writes the [`FontObject`] record and then calls [`propagate`], which re-paints every
-//! region whose [`RegionData::font_object`] names it.
-//!
-//! **The severance rule, corrected by the bytes.** Our first cut read `FONTINSTANCE+0x038` as an
-//! "explicitly set" mask and reset it on every `SetFontObject`. Both halves were wrong. `+0x38`'s
-//! low bits are a transient broadcast flag and its high bits mean "has a resolved value" — set by
-//! the *inheriting* merge too (`0x7709d3`). The real "stop inheriting this property" signal is a
-//! **cleared** bit in the previously-unrecorded **inheritMask at `+0x2c`** (FontString `+0xd4`,
-//! per-axis justify at `+0x124`), cleared by each local setter and **never restored** — so a
-//! FontString that set its own colour stays severed *across a later `SetFontObject`*.
-//! [`RegionData::font_explicit`] is that mask, and nothing resets it.
-//!
-//! The source side gates too: a merge only copies properties the source actually holds, so a font
-//! freshly minted by [`create_font`] (`mask == 0`) copies **nothing** — see [`repaint`].
-//!
-//! **What we deliberately do not model, now a verified divergence rather than an unknown:** a
-//! `<Font inherits="OtherFont">` chain stays flattened at load (`Loader::do_font`), so mutating
-//! `MasterFont` does not walk down to `GameFontNormal`. The reference links these live as well —
-//! `LoadXML 0x783c30` calls the *same* `0x770c60` link function `SetFontObject` calls
-//! (`0x783ce6`), and `font=` likewise (`0x783d22`). Flattening is what this arc was scoped to keep;
-//! the cost is bounded and measured: **0 corpus addons mutate a declared font object at all** —
-//! every mutation in 218 addons is of the addon's own [`create_font`] object — so the Font→Font
-//! half has no demand behind it and the Font→FontString half has all of it.
+//! Not built: a `<Font inherits=…>` chain is flattened at load (`Loader::do_font`), so mutating
+//! `MasterFont` does not reach `GameFontNormal`, where the reference links it live: `LoadXML
+//! 0x783c30` calls the `SetFontObject` link `0x770c60` for `inherits=` (`0x783ce6`) and `font=`
+//! (`0x783d22`). No corpus addon mutates a declared font object.
 
 use mlua::{Lua, Table, Value};
 
@@ -79,25 +31,18 @@ use super::{FontObject, FontShadow, Model, Outline, RegionData};
 
 /// The shared metatable of every font-object handle.
 const REG_FONT_META: &str = "__benilla_font_meta";
-/// The font-object method table the metatable's `__index` dispatches through.
+/// The font-object method table, which is the metatable's `__index`.
 const REG_FONT_METHODS: &str = "__benilla_font_methods";
 /// name → handle, so `GameFontNormal == GameFontNormal` and a re-declared `<Font>` keeps identity.
 const REG_FONT_WRAPPERS: &str = "__benilla_font_wrappers";
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The handle
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The handle ───────────────────────────────────────────────────────────────────────────────
 
-/// Get-or-create the Lua handle for a named font object.
+/// Get or create the Lua handle for a named font object. Keyed by name, which every font has (an
+/// unnamed `<Font>` is dropped at parse), so a re-declared `<Font>` updates its record in place.
 ///
-/// Identity is the **name**, not a minted id: every font object in 1.12 has one (an unnamed
-/// `<Font>` is warned and dropped at parse time, and [`create_font`] requires one), and keying by
-/// name is what makes a re-declared `<Font name="GameFontNormal">` update the record *in place*
-/// while every `SetFontObject(GameFontNormal)` already taken keeps pointing at the same object.
-///
-/// `T[0]` is the name string rather than the frame/region wrapper's `LightUserData` id, so
-/// [`super::object::decode_id`] rejects a font handle passed where a frame is wanted, with its own
-/// message, instead of decoding a garbage id.
+/// `T[0]` holds the name, not a frame id, so a font handle passed where a frame is wanted is
+/// rejected rather than decoded.
 pub(crate) fn wrapper(lua: &Lua, name: &str) -> mlua::Result<Table> {
     let wrappers: Table = lua.named_registry_value(REG_FONT_WRAPPERS)?;
     if let Value::Table(t) = wrappers.get::<Value>(name)? {
@@ -111,16 +56,13 @@ pub(crate) fn wrapper(lua: &Lua, name: &str) -> mlua::Result<Table> {
     Ok(t)
 }
 
-/// Publish `_G[name]` as this font object's handle — what makes `fs:SetFontObject(GameFontNormal)`
-/// resolve to anything at all. Non-overwriting, exactly like the frame side's [`publish_global`].
-///
-/// Called by `Loader::do_font` for every top-level `<Font name=…>`, and by [`create_font`].
+/// Publish the handle as `_G[name]`, leaving a non-nil global alone as [`publish_global`] does.
 pub(crate) fn publish(lua: &Lua, name: &str) -> mlua::Result<()> {
     let t = wrapper(lua, name)?;
     publish_global(lua, name, &t)
 }
 
-/// The name behind a font handle, or an error naming what was actually passed.
+/// The name a font handle holds in `T[0]`.
 fn name_of(this: &Table) -> mlua::Result<String> {
     match this.raw_get::<Value>(0)? {
         Value::String(s) => Ok(s.to_str()?.to_string()),
@@ -130,18 +72,9 @@ fn name_of(this: &Table) -> mlua::Result<String> {
     }
 }
 
-/// Accept any of the **three** forms the real binding takes and return the registry name, with
-/// `None` for the nil form (clear the link).
-///
-/// The reference's own usage string settles the shape — `.rdata 0x87c5cc` reads verbatim
-/// `Usage: %s:SetFontObject(font or "font" or nil)` (wow-re
-/// `system/ui/scratch/font-object-lua-surface.md`, §5-verified). So all three are real: the object
-/// (3,180 of the corpus's 3,186 sites), the name string (our own shipped `assets/ui` plus 6 corpus
-/// sites), and nil.
-///
-/// Anything else — a frame, a number, a missing argument — is an **error**, and in the reference
-/// too: every rejection there is `luaL_error 0x6f4940`, which longjmps and aborts the call rather
-/// than no-opping. A font that quietly fails to apply is the silent-drop class of 1203/1205/1211.
+/// A font argument as a registry name, `None` for nil: an object, a name or nil, the three forms of
+/// the reference's usage `SetFontObject(font or "font" or nil)` (`0x87c5cc`). Anything else
+/// raises, as the reference's `luaL_error 0x6f4940` does.
 pub(super) fn resolve(verb: &str, v: &Value) -> mlua::Result<Option<String>> {
     match v {
         Value::Nil => Ok(None),
@@ -159,8 +92,7 @@ pub(super) fn resolve(verb: &str, v: &Value) -> mlua::Result<Option<String>> {
     }
 }
 
-/// [`resolve`] for the verbs that genuinely refuse nil — `CopyFontObject` is the one
-/// (`0x7a01b0`: it value-copies and re-parents, so there is nothing to copy *from*).
+/// [`resolve`] refusing nil, for `CopyFontObject`, which has nothing to copy from (`0x7a01b0`).
 fn resolve_required(verb: &str, v: &Value) -> mlua::Result<String> {
     resolve(verb, v)?.ok_or_else(|| {
         mlua::Error::runtime(format!(
@@ -169,23 +101,15 @@ fn resolve_required(verb: &str, v: &Value) -> mlua::Result<String> {
     })
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The live link: font object → the regions that inherit it
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The live link: a font object to the regions that inherit it ──────────────────────────────
 
-/// Copy a font object's paint onto one region, **skipping every property that region severed by
-/// setting for itself** ([`RegionData::font_explicit`]).
+/// Copy a font object's paint onto one region, skipping each property the region set itself
+/// ([`RegionData::font_explicit`]) and each the font does not hold: the reference gates every merge
+/// on the source's held-value bits (`+0x38`, the merge `0x770910`), so an empty `CreateFont` font
+/// changes nothing.
 ///
-/// **A property the source does not hold copies nothing.** The reference gates every merge on the
-/// source's own has-a-value mask (`+0x38`'s high bits, set by the merge `0x770910`): a font freshly
-/// minted by `CreateFont` has `mask == 0`, so `SetFontObject`-ing it onto a FontString leaves that
-/// string exactly as it was — no blanking, no fallback to a default. `_Nameplates` relies on
-/// nothing here, but `!OmniCC`'s probe font would otherwise wipe a label it was pointed at.
-///
-/// Residue: [`Outline`] has no "unset" state distinct from `NONE`, so an outline is still written
-/// unconditionally. Every shipped `<Font>` flattens from `MasterFont`, which declares no outline,
-/// so the two readings coincide for all of them; a `CreateFont` object pointed at an outlined
-/// FontString is the one case that differs, and it has no caller.
+/// The outline is always copied, as [`Outline`] has no unset state; only an empty `CreateFont` font
+/// on an outlined FontString differs from the reference, clearing the outline.
 pub(crate) fn repaint(d: &mut RegionData, fo: &FontObject) {
     let ex = d.font_explicit;
     if !ex.face {
@@ -223,12 +147,9 @@ pub(crate) fn repaint(d: &mut RegionData, fo: &FontObject) {
     }
 }
 
-/// Re-paint every region that inherits `name` — the `SetFont`/`SetTextColor`/… propagation the real
-/// client gets for free from its live `parentFontObject`. Linear in regions, on a human-rate path
-/// (a font-object setter is an addon config action, never a frame path).
-///
-/// Per-state **button** label fonts need no equivalent: they are stored as names and re-resolved at
-/// every `extract`, so a mutated font object reaches them on the next frame by construction.
+/// Repaint every region that inherits `name`, as the reference's live parent link does. Linear in
+/// regions: font-object setters are addon configuration, never per frame. Button state fonts are
+/// stored by name and re-resolved at every `extract`, so they need no push.
 pub(crate) fn propagate(model: &mut Model, name: &str) {
     let Some(fo) = model.font_object(name).cloned() else {
         return;
@@ -238,14 +159,11 @@ pub(crate) fn propagate(model: &mut Model, name: &str) {
             repaint(d, &fo);
         }
     }
-    // A fan-out cannot name its regions one by one without a second pass; a font-object edit is
-    // a human-rate action, so the measure ledger goes conservative and the next sweep walks the
-    // roster once, exactly as every sweep did before the ledger existed.
+    // A fan-out cannot name its regions without a second pass, so every region is re-measured.
     model.touch_measure_all();
 }
 
-/// Run `f` over the named font object's record, then propagate the change to its dependants.
-/// The one write path every setter below goes through.
+/// Run `f` on the named font object's record, then [`propagate`]: every setter's one write path.
 fn edit<R>(lua: &Lua, this: &Table, f: impl FnOnce(&mut FontObject) -> R) -> mlua::Result<R> {
     let name = name_of(this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -257,33 +175,20 @@ fn edit<R>(lua: &Lua, this: &Table, f: impl FnOnce(&mut FontObject) -> R) -> mlu
     Ok(out)
 }
 
-/// Read the named font object's record (a clone — the records are small and this is human-rate).
+/// A copy of the named font object's record.
 fn read(lua: &Lua, this: &Table) -> mlua::Result<FontObject> {
     let name = name_of(this)?;
     let model = lua.app_data_ref::<Model>().expect("model");
     Ok(model.font_object(&name).cloned().unwrap_or_default())
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// install — the method table, the metatable, and CreateFont
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── install: the method table, the metatable and CreateFont ──────────────────────────────────
 
-/// Build the font-object method table and metatable, and register the `CreateFont` global.
+/// Build the font-object method table and metatable, and register `CreateFont`.
 ///
-/// **Implemented** (20 of the reference table's 22): `GetObjectType`, `IsObjectType`, `GetName`,
-/// `SetFontObject`, `GetFontObject`, `CopyFontObject`, `SetFont`, `GetFont`, `SetAlpha`,
-/// `GetAlpha`, `SetTextColor`, `GetTextColor`, `SetShadowColor`, `GetShadowColor`,
-/// `SetShadowOffset`, `GetShadowOffset`, `SetJustifyH`, `GetJustifyH`, `SetJustifyV`,
-/// `GetJustifyV`.
-///
-/// **Deliberately absent: `SetSpacing`/`GetSpacing`.** We model no line spacing anywhere — neither
-/// [`RegionData`] nor the text layout has the field, and the line pitch is the font height — so a
-/// `SetSpacing` here could only store a number nobody draws. That is precisely the silently-ignored
-/// setter this codebase keeps being bitten by (1203, 1205, 1211), and the alternative failure is
-/// the good one: a missing method raises `attempt to call method 'SetSpacing' (a nil value)`, which
-/// names itself. Demand behind it is **zero** — no call on any font-object global anywhere in the
-/// 218-addon corpus, and 1.12's own FrameXML never calls the font API at all. When spacing becomes
-/// a thing the renderer honours, the pair lands with it.
+/// Deviation: `SetSpacing`/`GetSpacing` are absent, because nothing renders line spacing (the line
+/// pitch is the font height): a missing method raises and names itself, where a stored, undrawn
+/// value would fail silently.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.set_named_registry_value(REG_FONT_WRAPPERS, lua.create_table()?)?;
 
@@ -294,17 +199,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "GetObjectType",
         lua.create_function(|_, _this: Table| Ok("Font"))?,
     )?;
-    // **`1`/`nil`, never a Lua boolean** (decision 2118's law; 2142 found this copy). The
-    // reference's Font object has its OWN `IsObjectType` (`0x79fe60`, table `0x87c7c8`) distinct
-    // from the Region base's (`0x7a1290`, `0x87c9b8`), and the shapes table types both
-    // `(nil) | (number)`. This one answered a Rust `bool` — the fourth copy of a house rule that
-    // three neighbours got right, which is exactly the drift 2118 consolidated `flag` to stop, and
-    // it was invisible until the shape gate learned to probe the Font object at all.
-    //
-    // The ARGUMENT contract is a separate question and is not claimed here: `region.rs`'s twin
-    // documents the reference's `Usage: %s:IsObjectType("TYPE")` raise and its number-stringifying
-    // arm from a byte read of `0x7a1290`; nobody has read `0x79fe60`'s, so this copy keeps mlua's
-    // own coercion rather than pretending to that finding.
+    // `1` or nil, never a boolean, like the Region's (`0x7a1290`): the Font's own `IsObjectType`
+    // (`0x79fe60`) answers a number. Its argument handling is untraced; mlua's coercion applies.
     m.set(
         "IsObjectType",
         lua.create_function(|_, (_this, ty): (Table, String)| {
@@ -317,11 +213,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── the font-object-on-font-object pair ─────────────────────────────────────────────────
-    // SetFontObject(other) — adopt another object's whole paint. On a Font (rather than a
-    // FontString) the reference's live-parent distinction is invisible to us because we flatten
-    // Font→Font chains at load (module doc); this is therefore the same copy CopyFontObject makes,
-    // and both are spelled out separately so a later Font→Font link has two named places to land.
-    // It takes nil like its FontString twin — with no Font→Font link to sever, that is a no-op.
+    // SetFontObject(other): on a Font, the same copy as CopyFontObject, since Font chains are
+    // flattened (module doc); nil is a no-op, with no link to sever.
     m.set(
         "SetFontObject",
         lua.create_function(|lua, (this, other): (Table, Value)| {
@@ -331,9 +224,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // CopyFontObject(other) — `FonzAppraiser`'s pattern: mint with CreateFont, copy a shipped
-    // object's paint, then override the face (`gui.lua:27-30`). Unlike `SetFontObject` it
-    // **rejects nil** (`0x7a01b0` value-copies and re-parents, so there is nothing to copy from).
+    // CopyFontObject(other): refuses nil (`0x7a01b0` value-copies and re-parents).
     m.set(
         "CopyFontObject",
         lua.create_function(|lua, (this, other): (Table, Value)| {
@@ -341,28 +232,22 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             copy_from(lua, &this, &other, "CopyFontObject")
         })?,
     )?;
-    // GetFontObject() — a Font object has no parent link in our model (chains are flattened at
-    // load), so this is honestly nil rather than a self-reference that would read as a link.
+    // GetFontObject(): always nil; with Font chains flattened, a Font has no parent link.
     m.set(
         "GetFontObject",
         lua.create_function(|_, _this: Table| Ok(Value::Nil))?,
     )?;
 
     // ── face ────────────────────────────────────────────────────────────────────────────────
-    // SetFont(path, height [, flags]) → **the number 1, or nil** — the reference's exact return
-    // shape (1 value either way; a font file that fails to load yields nil, never an error).
-    // `!OmniCC/main.lua:41` uses it as a *font-file validity probe* (`if not
-    // OmniCCFont:SetFont(saved, size) then revert end`), so it is not decorative. We answer 1 for
-    // any non-empty path — face availability is the renderer's concern here, the atlas falls back
-    // per face — and nil for an empty/absent one, so a probe with a blank saved variable reverts.
+    // SetFont(path, height [, flags]) → 1, or nil when the font file fails to load, which does not
+    // raise. Deviation: any non-empty path answers 1, because the atlas falls back per face and no
+    // load fails; an empty one answers nil.
     m.set(
         "SetFont",
         lua.create_function(
             |lua, (this, file, height, flags): (Table, Value, Value, Option<String>)| {
-                // The same gate the FontString and EditBox tables enter — one `0x79f210`, three
-                // entry points. This side used to take `Option`s, so `SetFont()` answered **nil**
-                // where the reference raises `0x87c69c`; the FontString's copy answered the boolean
-                // `true` for everything. Neither was the shared routine's contract.
+                // The argument gate the FontString and EditBox tables share (`0x79f210`); a
+                // missing argument raises (`0x87c69c`).
                 let (path, height) = super::font_block::set_font_args(&file, &height, "Font")?;
                 let ok = !path.is_empty();
                 edit(lua, &this, |fo| {
@@ -371,9 +256,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     }
                     fo.height = Some(height);
                     if let Some(f) = flags {
-                        // The LUA flags spelling ("OUTLINE"/"THICKOUTLINE"), not the XML
-                        // attribute's ("NORMAL"/"THICK") — this read the XML one, so every
-                        // `GameFontNormal:SetFont(f, h, "OUTLINE")` silently cleared the outline.
+                        // The Lua flag spelling (`OUTLINE`, `THICKOUTLINE`), not the XML
+                        // attribute's (`NORMAL`, `THICK`).
                         fo.outline = Outline::flags(&f);
                     }
                 })?;
@@ -381,15 +265,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // GetFont() → path, height, flags. `Tablet-2.0.lua:289`'s `_, headerSize =
-    // GameTooltipHeaderText:GetFont()` is the corpus's single biggest font-object read (268 sites),
-    // and it does arithmetic on the second value.
-    //
-    // **An unset Font answers `(nil, 0, "")`, all three ctor-determined** — `0x783a40` writes
-    // `[esi+0x48]` and `[esi+0x4c]` from a zeroed register, and its `0x41e3a0(NULL)` stores the
-    // shared empty record whose `char*` is NULL, which `lua_pushstring` turns into nil. So the
-    // height is the NUMBER zero, not nil (wow-re `font-object-lua-surface.md` §9.3,
-    // §5-cross-checked; decision 2129).
+    // GetFont() → path, height, flags. An unset Font answers nil, 0, "": the constructor
+    // `0x783a40` zeroes the height and stores a NULL path (`0x41e3a0`), which pushes as nil.
     m.set(
         "GetFont",
         lua.create_function(|lua, this: Table| {
@@ -403,8 +280,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── colour, and the alpha that is its fourth channel ────────────────────────────────────
-    // Shape C on the three channels (`SetTextColor 0x79f4d0`, `2=C 3=C 4=C 5=B`, wow-re
-    // `numeric-arg-coercion-law.md`): a nil or non-number is 0.0, never a raise (1973).
+    // Shape C on r, g, b (`SetTextColor 0x79f4d0`): nil or a non-number is 0, never a raise.
     m.set(
         "SetTextColor",
         lua.create_function(
@@ -428,11 +304,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok((c[0], c[1], c[2], c[3]))
         })?,
     )?;
-    // SetAlpha/GetAlpha on a FontInstance are its text colour's alpha channel, not a separate
-    // slot: wow-re's field map gives a FontInstance exactly one colour word (`FONTINSTANCE+0x058
-    // textColor`, a packed CImVector) and no alpha field of its own, so there is nowhere else for
-    // an alpha to live. Zero corpus sites; implemented because a duck-typed `if f.SetAlpha` should
-    // find it and because the semantics follow from the storage rather than from a guess.
+    // SetAlpha/GetAlpha are the text colour's alpha: a FontInstance has one packed colour
+    // (`+0x58`) and no alpha of its own.
     m.set(
         "SetAlpha",
         lua.create_function(|lua, (this, a): (Table, f32)| {
@@ -448,13 +321,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── shadow ──────────────────────────────────────────────────────────────────────────────
-    // Either half may be set before the other, so both start from whatever is there (or a zero
-    // offset / opaque black) rather than refusing a shadow that is only half-declared.
     m.set(
         "SetShadowColor",
         lua.create_function(
-            // Shape C on r, g, b (`Font:SetShadowColor 0x79f730`, `2=C 3=C 4=C 5=B`, wow-re
-            // `numeric-arg-coercion-law.md`) — bare `lua_tonumber`, no gate, never raises.
+            // Shape C on r, g, b (`Font:SetShadowColor 0x79f730`): never raises.
             |lua, (this, r, g, b, a): (Table, Value, Value, Value, Option<f32>)| {
                 let (r, g, b) = (
                     crate::script::object::as_f32(&r),
@@ -501,16 +371,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── justification ───────────────────────────────────────────────────────────────────────
-    //
-    // The token table, the whole-string match, the raise on a miss and the cross-axis clear are
-    // [`crate::justify`]'s, shared with the FontString table's identical pair. This side used to
-    // `.trim()` its argument and the other did not — one law, two transcriptions, and at most one
-    // of them could be right (the bytes say no trim: `SStrCmpI` compares the whole string).
-    //
-    // `justify_h`'s `Option` here is *inheritance*, not the reference's cleared axis: `None` means
-    // "this font object does not specify justification", which is what the resolve at
-    // [`resolve_font_object`] and `extract.rs` test. A fresh object therefore reads CENTER/MIDDLE
-    // through `unwrap_or_default`, which is also the client's ctor default `0x212`.
+    // Parsing is [`crate::justify`]'s, shared with the FontString pair: `SStrCmpI` over the whole
+    // string, no trim. `None` means the font does not specify the axis (inheritance), not a
+    // cleared axis; a fresh object reads CENTER/MIDDLE, the constructor default `0x212`.
     m.set(
         "SetJustifyH",
         lua.create_function(|lua, (this, j): (Table, String)| {
@@ -550,14 +413,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    lua.set_named_registry_value(REG_FONT_METHODS, m)?;
-
     let meta = lua.create_table()?;
-    let index = lua.create_function(|lua, (_this, key): (Table, Value)| {
-        let methods: Table = lua.named_registry_value(REG_FONT_METHODS)?;
-        methods.get::<Value>(key)
-    })?;
-    meta.set("__index", index)?;
+    // `__index` is the method table itself, not a function: a table index costs ~9 ns against
+    // ~200 ns through a Rust dispatcher, and nothing mutates the table after this point.
+    meta.set("__index", m.clone())?;
+    lua.set_named_registry_value(REG_FONT_METHODS, m)?;
     lua.set_named_registry_value(REG_FONT_META, meta)?;
 
     lua.globals()
@@ -565,8 +425,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The body behind `SetFontObject`/`CopyFontObject` on a Font: take the *other* object's resolved
-/// paint wholesale.
+/// `SetFontObject`/`CopyFontObject` on a Font: take the other object's paint wholesale.
 fn copy_from(lua: &Lua, this: &Table, other: &Value, verb: &str) -> mlua::Result<()> {
     let src = resolve_required(verb, other)?;
     let paint = {
@@ -580,20 +439,11 @@ fn copy_from(lua: &Lua, this: &Table, other: &Value, verb: &str) -> mlua::Result
     edit(lua, this, |fo| *fo = paint)
 }
 
-/// `CreateFont(name)` — mint a font object at runtime and publish it as the global `name`, the
-/// twin of a `<Font name=…>` declaration. Returns the handle.
+/// `CreateFont(name)`: mint a font object, publish it as the global `name` and return it; addons
+/// use both. An existing name returns that object unchanged and unrepublished (`0x7839ab`).
 ///
-/// Both halves are load-bearing in the corpus and neither can be dropped: `_Nameplates.lua:149` and
-/// `FonzAppraiser/mods/gui/gui.lua:27` keep the **return**, while `!OmniCC/main.lua:40-41` throws it
-/// away and reads the **global** on the very next line.
-///
-/// A name that already names a font object returns the existing one **unchanged, silently** — no
-/// error, no re-publication (`0x7839ab`). We had chosen that as the non-destructive reading before
-/// the bytes were asked; they agree.
-///
-/// The empty string is accepted (the reference's `lua_isstring` gate takes strings *and* numbers,
-/// and unlike the XML path does not require a non-empty name); only a missing/nil argument is an
-/// error. A fresh object holds nothing, so `SetFontObject`-ing it copies nothing — see [`repaint`].
+/// The reference's gate (`0x706048`) takes a number or any string, the empty one included, and
+/// raises on anything else. A fresh object holds nothing, so it copies nothing ([`repaint`]).
 fn create_font(lua: &Lua, name: Option<String>) -> mlua::Result<Table> {
     let name = name.ok_or_else(|| {
         mlua::Error::runtime("CreateFont: a font name is required (it becomes a global)")
diff --git a/crates/benilla-ui/src/script/font_block.rs b/crates/benilla-ui/src/script/font_block.rs
index 43003bcf..fd4cb984 100644
--- a/crates/benilla-ui/src/script/font_block.rs
+++ b/crates/benilla-ui/src/script/font_block.rs
@@ -1,109 +1,18 @@
-//! **The font block** — the ten font methods a text-bearing widget re-declares in its own method
-//! table, implemented once over the [`RegionData`](super::RegionData) the glyphs actually paint
-//! from, and installed onto any widget's table by [`install`].
+//! The font block: the ten font methods a text-bearing widget's own method table declares,
+//! implemented once over the [`RegionData`](super::RegionData) its glyphs paint from.
 //!
-//! ## Why this is a module and not a base class
+//! The 1.12 client has no `FontInstance` class: each text type re-declares the font names in its
+//! own flat method table, and each binding is a shim that tail-calls one shared implementation.
+//! This module is that shared layer, installed by the FontString, EditBox, MessageFrame and
+//! ScrollingMessageFrame tables; the `<Font>` object and `SimpleHTML` write their own records and
+//! share only [`set_font_args`].
 //!
-//! **There is no `FontInstance` class in the 1.12.1 Lua chain.** wow-re's registrar map
-//! (`system/ui/scratch/widget-api-batch-benilla.md`, and the per-table carve in
-//! `font-object-lua-surface.md` §2) shows 23 flat `{const char* name, void* fn}` `.data` tables and
-//! a per-class `vtable[+0x8]` lookup that tail-calls **exactly one** base class's lookup on a miss.
-//! The six text-bearing types each *re-declare* the same font names in their own flat table; the
-//! sharing happens one level **down**, in C++, where every binding is a thin type-guard shim that
-//! tail-calls one shared implementation (`0x79f210` SetFont · `0x79f3b0` GetFont · `0x79f4d0` /
-//! `0x79f680` Set/GetTextColor · `0x79f730` / `0x79f910` Set/GetShadowColor · `0x79f9c0` /
-//! `0x79fad0` Set/GetShadowOffset · `0x79ef10` / `0x79f090` Set/GetFontObject).
-//!
-//! So: **which font methods a type has is a per-table fact, never derivable from "it draws text"** —
-//! and this module is that shared C++ layer, with each widget's own table naming the subset it
-//! really carries. Adding a name a table does not carry is exactly as wrong as missing one.
-//!
-//! ## The membership, read off the binary rather than assumed
-//!
-//! `EditBox`'s table is `.data 0x87bb68`, **48 entries** — the count read from the `mov edx,0x30` at
-//! the registering site `0x799ab5`, never from a run-length scan (adjacent tables are contiguous and
-//! a scan merges them into a bogus blob). Its **first sixteen entries are the font block**, in this
-//! order, and each one is a shim that `call`s the shared implementation and returns **without
-//! touching `eax`** — so every return arity below is the shared implementation's, verbatim:
-//!
-//! | # | EditBox entry | binding | tail-calls | returns |
-//! |---|---|---|---|---|
-//! | 0 | `SetFontObject`   | `0x797090` | `0x79ef10` | **0 values** |
-//! | 1 | `GetFontObject`   | `0x797150` | `0x79f090` | **1 value** (the handle, or nil) |
-//! | 2 | `SetFont`         | `0x797210` | `0x79f210` | **1 value: the NUMBER 1, or nil** |
-//! | 3 | `GetFont`         | `0x7972d0` | `0x79f3b0` | **3 values** (path, height, flags) |
-//! | 4 | `SetTextColor`    | `0x797390` | `0x79f4d0` | **0 values** |
-//! | 5 | `GetTextColor`    | `0x797450` | `0x79f680` | **4 values** |
-//! | 6 | `SetShadowColor`  | `0x797510` | `0x79f730` | **0 values** |
-//! | 7 | `GetShadowColor`  | `0x7975d0` | `0x79f910` | **4 values** (`0x79f9b3 mov eax,0x4`) |
-//! | 8 | `SetShadowOffset` | `0x797690` | `0x79f9c0` | **0 values** |
-//! | 9 | `GetShadowOffset` | `0x797750` | `0x79fad0` | **2 values** |
-//! | 10–11 | `Set/GetSpacing` | `0x797810` / `0x7978d0` | `0x79fb40` / `0x79fbe0` | *not installed — below* |
-//! | 12–15 | `Set/GetJustifyH`, `Set/GetJustifyV` | `0x797990`… | `0x79fc20`… | *EditBox-side — below* |
-//!
-//! **`SetFont` is the trap here, and it points the opposite way to the one this codebase already
-//! pinned.** `Button:SetFont` (`0x780880`) ends `xor eax,eax` and returns **nothing** — that
-//! divergence has its own test. `EditBox:SetFont` does **not**: `0x7972b2 call 0x79f210` is followed
-//! by `pop edi; pop esi; pop ebx; ret` with no `eax` write, so the shared implementation's single
-//! value (`lua_pushnumber(1.0)` at `0x79f345`, or `lua_pushnil` at `0x79f361`) passes straight
-//! through. It is the number `1`, not `true`, and not zero values.
-//!
-//! The table above was read off the PE `.data` section directly (with Font's 22-entry table as a
-//! positive control) and **independently re-derived by a wow-re §5 trio**, which agrees on all 48
-//! names, all 48 binding addresses and all 16 arities —
-//! `system/ui/scratch/editbox-font-surface.md`. Its own control for the "nothing is discarded"
-//! claim is `SetMultiLine`'s binding, which *does* emit `xor eax,eax` (`0x797e9d`) and returns 0.
-//! Entry 47 ends at `0x87bce8`, the first byte of the string `"GetAltArrowKeyMode"` — the table
-//! abuts its own string pool, which pins the count at 48 a second way.
-//!
-//! **A stated divergence, verified and deliberately left consistent rather than fixed on one table:**
-//! the reference's `SetTextColor` and `SetShadowColor` read r, g and b with a **bare `lua_tonumber`**
-//! (a non-number silently becomes `0.0`) and carry **no usage string at all**, so they *cannot
-//! raise* — `SetTextColor()` sets opaque black. Ours take `f32`, so a missing or non-numeric channel
-//! errors instead. Alpha matches (`lua_isnumber`-gated, default 1.0).
-//!
-//! **The collapse below has now landed, which is what was blocking this**: the FontString and
-//! EditBox tables both reach these two verbs *here*, so the correction is a one-place change rather
-//! than three copies drifting. It is deliberately still not made, for a reason of its own: it turns
-//! a loud error into a silent opaque black, which is faithful but is a real behaviour change and
-//! belongs in its own landing with its own corpus A/B. No corpus site is known to depend on it.
-//!
-//! ## Where it lands, and why that is the mechanism rather than an approximation
-//!
-//! Each shim loads **`[this+0x324]`** and hands it to the shared implementation as the target. On a
-//! `CSimpleEditBox` that offset is the box's implicit FontString — the same field
-//! [`EditBoxState::text_region`](crate::widget::EditBoxState::text_region) models (RF-0082, and it is
-//! the EditBox's analogue of `ButtonText`). So `editBox:SetFontObject(ChatFontNormal)` really does
-//! paint *the box's font string*, which is exactly what this module writes: resolve the widget to
-//! the region its glyphs come from, then set the same [`RegionData`](super::RegionData) fields a
-//! `FontString` sets for itself.
-//!
-//! ## Not installed here, and the reason is not laziness
-//!
-//! - **`SetSpacing` / `GetSpacing`.** We model no line spacing anywhere — neither `RegionData` nor
-//!   the text layout carries the field, and the line pitch is the font height — so a setter here
-//!   could only store a number nobody draws. That is the silently-ignored-setter failure this
-//!   codebase keeps being bitten by (1203, 1205, 1211), and the alternative failure is the good one:
-//!   a missing method raises `attempt to call method 'SetSpacing' (a nil value)`, which names itself.
-//!   Demand is **zero** — `grep -r ':SetSpacing(\|:GetSpacing('` over the 218-addon corpus finds
-//!   nothing at all. `script::font`'s own table withholds the pair for the same reason; when spacing
-//!   becomes something the renderer honours, both land together.
-//! - **The justify four.** They are real EditBox entries and they *are* wired — but on the EditBox's
-//!   own state rather than on its text region, because our EditBox draw law forces the region's
-//!   justification (see `script::editbox::methods`). They live there for that reason, not here.
-//!
-//! ## Who installs this, and the duplicates it replaced
-//!
-//! Two tables: the `EditBox`'s (`script::editbox::methods`) and the **`FontString`'s**
-//! (`script::region::text`). The FontString's used to hand-write its own copy of all ten; 1238
-//! collapsed them, deleting 226 lines and carrying the correction that copy had been hiding — its
-//! `SetFont` answered the boolean `true`, where the bytes above say the number `1` or nil.
-//!
-//! The `<Font>` object's table (`script::font`) is **not** installed from here, and that is not an
-//! oversight: it writes a [`FontObject`](super::FontObject) record rather than a
-//! [`RegionData`](super::RegionData), so it shares the *marshalling* ([`set_font_args`]) rather
-//! than the body. Its `SetFont` had drifted the other way — `Option` arguments, so `SetFont()`
-//! answered nil where `0x87c69c` raises — which is why the gate is one function now.
+//! `EditBox`'s table (`0x87bb68`, 48 entries) opens with these ten, then `Set/GetSpacing` and the
+//! four justify methods. Its shims (`0x797090` on) leave `eax` alone, so each returns what the
+//! shared implementation pushes, and act on `[this+0x324]`, the box's implicit FontString
+//! ([`EditBoxState::text_region`](crate::widget::EditBoxState::text_region)). The justify four are
+//! installed by `script::editbox::methods`. `SetSpacing`/`GetSpacing` (`0x79fb40`/`0x79fbe0`) are
+//! not installed: no line spacing is modelled, so a call raises.
 
 use mlua::{Lua, Table, Value};
 
@@ -111,28 +20,14 @@ use super::object::as_f32;
 use super::{FontShadow, Model, Outline};
 use crate::widget::RegionHandle;
 
-/// How a widget's method table resolves `this` to the region its glyphs are painted from.
-///
-/// A `FontString` *is* that region; an `EditBox` owns one and creates it on demand. A resolver
-/// returning an error is how a method called on the wrong receiver reports it.
+/// How a widget's method table finds the region its glyphs paint from: a `FontString` is one, an
+/// `EditBox` creates its own on demand. An error means the wrong receiver.
 pub(super) type ResolveRegion = fn(&Lua, &Table) -> mlua::Result<RegionHandle>;
 
-/// `SetFont(path, fontHeight [, flags])`'s shared **argument gate** — the entry of `0x79f210`,
-/// which Font `0x7a0270`, FontString `0x79d4f0` and EditBox `0x797210` all reach.
-///
-/// arg 2 must pass `lua_isstring` and arg 3 `lua_isnumber` — both of which coerce, so a numeric
-/// string is accepted for either — else `Usage: %s:SetFont("font", fontHeight [, flags])`
-/// (`.rdata 0x87c69c`). That arm is `luaL_error`, which longjmps, so it is an `Err` here and
-/// **never** a nil answer (`super::binding_abi`).
-///
-/// The returned path may be **empty**, which is the caller's *load-failure* edge rather than an
-/// argument error: it answers nil with nothing raised, because `!OmniCC/main.lua:41`'s
-/// `if not f:SetFont(saved, size) then revert end` is a font-file validity probe. The height is
-/// still applied on that edge — only the face is rejected.
-///
-/// Shared because it was not: the `<Font>` table took `Option<String>, Option<f32>` and so answered
-/// nil for `SetFont()` where the reference raises, while the FontString's copy answered the boolean
-/// `true` for everything. One gate is the only way three entry points stay one routine.
+/// `SetFont`'s shared argument gate (`0x79f210`, reached from Font `0x7a0270`, FontString
+/// `0x79d4f0` and EditBox `0x797210`): arg 2 must pass `lua_isstring` and arg 3 `lua_isnumber`,
+/// both coercing, else it raises `Usage: %s:SetFont("font", fontHeight [, flags])` (`0x87c69c`).
+/// An empty path is not an argument error but a failed load, which the caller answers with nil.
 pub(super) fn set_font_args(
     file: &Value,
     height: &Value,
@@ -156,34 +51,24 @@ pub(super) fn set_font_args(
     Ok((path, height))
 }
 
-/// Install the ten shared font-block methods onto `m`, reading `this` through `resolve`.
-///
-/// The caller names the subset: this installs exactly the ten the module doc tabulates, and a
-/// widget whose real table lacks one of them must not use this installer for it.
+/// Install the ten font-block methods onto `m`, reading `this` through `resolve`; only for a
+/// widget whose reference method table carries all ten.
 pub(super) fn install(
     lua: &Lua,
     m: &Table,
     resolve: ResolveRegion,
     widget: &'static str,
 ) -> mlua::Result<()> {
-    // ── the font object, and the live link to it ────────────────────────────────────────────
-    // SetFontObject(font | "font" | nil) → 0 values. All three argument forms the reference's own
-    // usage string names (`.rdata 0x87c5cc`: `Usage: %s:SetFontObject(font or "font" or nil)`).
-    // `Dewdrop-2.0.lua:1675` — `editBox:SetFontObject(ChatFontNormal)`, two lines after
-    // `CreateFrame("EditBox", nil, editBoxFrame)` — passes the OBJECT, and that one line is
-    // replicated into 63 of the corpus's 218 addons.
-    //
-    // A frame, a number, or an unknown name is an ERROR, never a silent no-op: every rejection in
-    // the reference is `luaL_error 0x6f4940`, which longjmps and aborts the call (1203/1205/1211's
-    // silent-drop class).
+    // ── the font object ──
+    // SetFontObject(font | "font" | nil) → nothing (`0x79ef10`, usage string `0x87c5cc`). Any
+    // other argument or an unknown name raises: every rejection is `luaL_error` (`0x6f4940`).
     m.set(
         "SetFontObject",
         lua.create_function(move |lua, (this, font): (Table, Value)| {
             let name = super::font::resolve("SetFontObject", &font)?;
             let rh = resolve(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // The nil form severs the link and leaves the paint standing — the reference stores a
-            // null parent, and nothing re-reads or clears the resolved values.
+            // nil severs the link and keeps the paint; the reference only nulls the parent.
             let Some(name) = name else {
                 model.region_data.entry(rh).or_default().font_object = None;
                 return Ok(());
@@ -195,17 +80,14 @@ pub(super) fn install(
             };
             let d = model.region_data.entry(rh).or_default();
             d.font_object = Some(name);
-            // The severance mask is deliberately NOT reset. §5-verified: the real "stop inheriting
-            // this property" signal is a CLEARED bit in the inheritMask (`FONTINSTANCE+0x2c`),
-            // cleared by each local setter and never restored — so a property the widget set for
-            // itself stays severed across a later `SetFontObject`.
+            // The inherit mask stays: each local setter clears its bit (`FONTINSTANCE+0x2c`) and
+            // nothing restores it, so a property set locally survives a later `SetFontObject`.
             super::font::repaint(d, &fo);
             model.touch_measure(rh);
             Ok(())
         })?,
     )?;
-    // GetFontObject() → exactly 1 value: the font OBJECT last resolved, or nil. The object, never
-    // its name — `Dewdrop-2.0.lua:2181` indexes the result immediately.
+    // GetFontObject() → the font object last set, never its name, or nil (`0x79f090`).
     m.set(
         "GetFontObject",
         lua.create_function(move |lua, this: Table| {
@@ -225,16 +107,10 @@ pub(super) fn install(
         })?,
     )?;
 
-    // ── the face ────────────────────────────────────────────────────────────────────────────
-    // SetFont(path, height [, flags]) → **the NUMBER 1, or nil** — one value either way, never a
-    // boolean and never zero values (the module doc's table; `0x7972b2` does not clobber `eax` the
-    // way `Button:SetFont` does). The shared impl gates arg2 on `lua_isstring` and arg3 on
-    // `lua_isnumber`, raising `Usage: %s:SetFont("font", fontHeight [, flags])` (`0x87c69c`)
-    // otherwise — both accept a numeric string, since `lua_isstring`/`lua_isnumber` coerce.
-    //
-    // nil is the *load-failure* answer, not an argument error: `!OmniCC/main.lua:41`'s
-    // `if not Font:SetFont(saved, size) then revert end` is a font-file validity probe, so an empty
-    // path must come back falsey rather than raising.
+    // ── the face ──
+    // SetFont(path, height [, flags]) → the number 1 (`0x79f345`), or nil on a failed load
+    // (`0x79f361`), never a boolean. The EditBox shim passes it through (`0x7972b2` leaves `eax`
+    // alone), unlike `Button:SetFont` (`0x780880`), which returns nothing.
     m.set(
         "SetFont",
         lua.create_function(
@@ -242,16 +118,13 @@ pub(super) fn install(
                 let (path, height) = set_font_args(&file, &height, widget)?;
                 let rh = resolve(lua, &this)?;
                 let mut model = lua.app_data_mut::<Model>().expect("model");
-                // The verdict is the host's when there is a host: nil is a *load* failure
-                // (`0x5c1ae0` under the `0x44d040` font-factory cache), so a path naming no file
-                // — an addon's TTF the AddOns folder does not hold — has to come back falsey, and
-                // only the store knows. With no probe installed, a non-empty path is 1: a VM with
-                // no font backend has nothing for a load to fail against (decision 2103).
+                // A failed load (`0x5c1ae0` under the `0x44d040` font cache) is the host's probe to
+                // judge, as only the store knows the files; with no probe, a non-empty path loads.
                 let ok =
                     !path.is_empty() && model.font_probe.as_ref().is_none_or(|probe| probe(&path));
                 let d = model.region_data.entry(rh).or_default();
-                // Every argument supplied is an EXPLICIT set: it must survive a later mutation of
-                // the font object this region inherits.
+                // Each supplied argument is an explicit set, kept through a later font-object
+                // change; the height applies even when the face fails to load.
                 if ok {
                     d.font_path = Some(path);
                     d.font_explicit.face = true;
@@ -259,9 +132,8 @@ pub(super) fn install(
                 d.font_height = Some(height);
                 d.font_explicit.height = true;
                 if let Some(f) = flags {
-                    // The LUA flags spelling ("OUTLINE"/"THICKOUTLINE"), not the XML attribute's
-                    // ("NORMAL"/"THICK") — the shared parse `0x6f1a90` is a case-insensitive
-                    // SUBSTRING scan, which is why "THICKOUTLINE" yields both bits.
+                    // The Lua spelling (`OUTLINE`, `THICKOUTLINE`), not the XML one, parsed like
+                    // `0x6f1a90`: a case-insensitive substring scan, so `THICKOUTLINE` sets both.
                     d.outline = Outline::flags(&f);
                     d.font_explicit.outline = true;
                 }
@@ -270,23 +142,11 @@ pub(super) fn install(
             },
         )?,
     )?;
-    // GetFont() → 3 values: path, height, flagsString (`mov eax,3` at `0x79f407`). The flags string
-    // is `""` when there are none — built into a zeroed static buffer at `0xceea60` — never nil.
-    //
-    // **The HEIGHT slot is a number even on a FontString that was never given a font**, and that is
-    // not the obvious reading: §9.3 records that the FontString reads back *through* its resolved
-    // `CGxFont`, so it looks as though a NULL one should nil all three. It does not. `0x7727b0`'s
-    // fifth instruction is an *unconditional* `fld [esi+0xe4]`, and its `+0xe0` test sits behind a
-    // branch `GetFont` never takes (`0x79d499 push 0`) — so slot 2 never touches the `CGxFont` at
-    // all and always pushes a double (wow-re `font-object-lua-surface.md` §9.3a, §5-cross-checked).
-    // We answer 0 there: `+0xe4` has **no constructor writer** in the reference, so its value on
-    // this path is a recycled float that nothing can reproduce, and 0 is what the Font object's own
-    // ctor-determined `+0x48` gives (decision 2129).
-    //
-    // A nil here is not a cosmetic difference. `aux-addon/tabs/search/frame.lua:481` computes
-    // `aux.select(2, child:GetFont()) + arg1*2` in its font-resize wheel handler — `aux.select`,
-    // the addon's own (`util.lua:26`), which is why that line survives 2171 taking the global
-    // `select` away.
+    // GetFont() → path, height, flags (`0x79f3b0`, `mov eax,3` at `0x79f407`); flags is "" when
+    // none (a zeroed buffer at `0xceea60`), never nil. The height is a number even with no font:
+    // `0x7727b0` loads `[esi+0xe4]` unconditionally (`0x79d499` skips its `+0xe0` test). That
+    // field has no constructor writer, so an unset height reads 0 here, like the Font object's
+    // `+0x48`.
     m.set(
         "GetFont",
         lua.create_function(move |lua, this: Table| {
@@ -303,14 +163,11 @@ pub(super) fn install(
         })?,
     )?;
 
-    // ── the text colour ─────────────────────────────────────────────────────────────────────
-    // SetTextColor(r, g, b [, a]) → 0 values; alpha defaults to 1.0 (`lua_isnumber(L,5)`-gated,
-    // `0x3f800000`). A FontString has no texel of its own, so its vertex colour IS the colour it
-    // draws — the same `+0xb8` slot `SetVertexColor` writes. The three channels are SHAPE C
-    // (`FontString:SetTextColor 0x79d9c0`, `2=C 3=C 4=C 5=B`, wow-re `numeric-arg-coercion-law.md`):
-    // a bare `lua_tonumber`, so a nil or a non-number is 0.0 and the call never raises — the stock
-    // trainer/trade-skill rows' OnLeave hands it `this.r, this.g, this.b` before anything set them
-    // (1973).
+    // ── the text colour ──
+    // SetTextColor(r, g, b [, a]) → nothing (`0x79f4d0`). r, g and b are a bare `lua_tonumber`
+    // (`0x79d9c0`), so nil reads 0.0 and the call never raises; alpha defaults to 1.0
+    // (`lua_isnumber`-gated). The colour is the region's vertex colour, the `+0xb8` slot
+    // `SetVertexColor` writes.
     m.set(
         "SetTextColor",
         lua.create_function(
@@ -324,15 +181,13 @@ pub(super) fn install(
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 let d = model.region_data.entry(rh).or_default();
                 d.vertex_color = Some([r, g, b, a.unwrap_or(1.0)]);
-                // The shared impl clears the inheritMask's colour bit on whatever instance it ran
-                // on (`0x79dbd0`'s `and [edi+0xd4],0xfffffffb`), so an explicit colour survives a
-                // later repaint from the font object.
+                // Clears the colour inherit bit (`0x79dbd0`): it survives a font-object repaint.
                 d.font_explicit.color = true;
                 Ok(())
             },
         )?,
     )?;
-    // GetTextColor() → 4 values, r, g, b, a. Never set = the white every region draws at.
+    // GetTextColor() → r, g, b, a (`0x79f680`); white when never set.
     m.set(
         "GetTextColor",
         lua.create_function(move |lua, this: Table| {
@@ -347,20 +202,14 @@ pub(super) fn install(
         })?,
     )?;
 
-    // ── the shadow ──────────────────────────────────────────────────────────────────────────
-    // **`GetShadowColor` returns FOUR values, not three** (`0x79f9b3`, `mov eax,0x4`). Three is the
-    // plausible wrong answer and it silently drops the alpha that
-    // `FuBar_NavigatorFu/NavigatorFu.lua:31` round-trips. `GetShadowOffset` returns two, in UI
-    // units (the same units as `SetWidth`/`SetPoint`), not device pixels.
-    //
-    // Either half may be set before the other, so each starts from whatever is already there —
-    // shadow colour and offset share one inherit slot in the reference too.
+    // ── the shadow ──
+    // `SetShadowColor` `0x79f730`, `GetShadowColor` `0x79f910` (four values, not three: `0x79f9b3`
+    // `mov eax,0x4`), `SetShadowOffset` `0x79f9c0`, `GetShadowOffset` `0x79fad0` (two, in UI
+    // units). Colour and offset share one inherit slot, so each setter keeps the other half.
     m.set(
         "SetShadowColor",
         lua.create_function(
-            // Shape C on r, g, b (`FontString:SetShadowColor 0x79dd40`, `2=C 3=C 4=C 5=B`) — the
-            // same law this module's header already states for its `SetTextColor` sibling, which
-            // 1973 closed there and not here.
+            // r, g and b are a bare `lua_tonumber` (`0x79dd40`), as in `SetTextColor`.
             move |lua, (this, r, g, b, a): (Table, Value, Value, Value, Option<f32>)| {
                 let (r, g, b) = (
                     super::object::as_f32(&r),
@@ -393,8 +242,7 @@ pub(super) fn install(
             Ok((c[0], c[1], c[2], c[3]))
         })?,
     )?;
-    // SetShadowOffset(x, y) → 0 values, and **both arguments are required** — the shared impl
-    // raises `Usage: %s:SetShadowOffset(x, y)` (`0x87c6e8`) rather than defaulting the missing one.
+    // SetShadowOffset(x, y): both required, else `Usage: %s:SetShadowOffset(x, y)` (`0x87c6e8`).
     m.set(
         "SetShadowOffset",
         lua.create_function(move |lua, (this, x, y): (Table, f32, f32)| {
diff --git a/crates/benilla-ui/src/script/gm_ticket.rs b/crates/benilla-ui/src/script/gm_ticket.rs
index bb9b2330..7850e12d 100644
--- a/crates/benilla-ui/src/script/gm_ticket.rs
+++ b/crates/benilla-ui/src/script/gm_ticket.rs
@@ -1,96 +1,60 @@
-//! The GM trouble-ticket **Era API surface** (decision 1673) — the seven globals `HelpFrame.lua`
-//! is written against, and nothing else.
-//!
-//! All seven are engine bindings in 1.12 (`reference/1.12-globals.tsv` lists each as
-//! `function`/`engine`), and the set is closed: the shipped Help window calls exactly
-//! `GetGMTicketCategories`, `GetGMStatus`, `GetGMTicket`, `NewGMTicket`, `UpdateGMTicket`,
-//! `DeleteGMTicket` and `Stuck`, and nothing else in the shipped UI calls any of them.
-//!
-//! **The five ticket verbs share ONE ordered queue** ([`GmTicketIntent`]), rather than a counter
-//! each. Call order is the wire order in the real client, and a per-verb drain cannot preserve it:
-//! with separate queues, `DeleteGMTicket(); GetGMTicket()` in a single chunk puts the *get* on the
-//! wire first and the answer then describes the state before the delete. The shipped Help window
-//! never issues two in one frame, so nothing on screen would ever have shown it — which is exactly
-//! why it is worth getting right rather than leaving as a latent trap for the next addon, or for
-//! our own probe (which hit it).
-//!
-//! A queue, not a set: **two calls are two sends**. That matters more here than for
-//! [`super::binder`], because the ticket toast **re-polls `GetGMTicket()` every 10 minutes** — a
-//! deduplicating drain would silently stop the poll. `Stuck()` keeps its own counter, because it
-//! is not a ticket verb at all (see its registration below) and shares no ordering with them.
-//!
-//! **The category list is DBC data, pushed once.** `GetGMTicketCategories()` returns a flat
-//! `id1, name1, id2, name2, …` vararg list, which `HelpFrameGM_UpdateCategories(...)` walks with
-//! Lua 5.0's `arg`/`arg.n`. The ids are `GMTicketCategory.dbc`'s own and they are the values that
-//! go on the wire, so this is an ordered list of pairs rather than an indexable table — see
-//! [`benilla_formats::gm_ticket_category`] for why renumbering would misfile every ticket.
-//!
-//! **There is no `GetGMTicket` *getter*.** The reference's `GetGMTicket()` is a SEND, not a read:
-//! the answer comes back as the `UPDATE_TICKET` event's arguments, and the window keeps whatever
-//! it needs in its own frame fields. So nothing here holds a ticket snapshot — the same shape as
-//! [`super::duel`] and [`super::binder`], and for the same reason.
+//! The seven GM ticket globals `HelpFrame.lua` calls. The five ticket verbs share one ordered
+//! queue, because call order is the reference's wire order, and two calls are two sends: the
+//! ticket toast re-polls `GetGMTicket()` every 10 minutes. `GetGMTicket()` is a send, answered by
+//! the `UPDATE_TICKET` event, so nothing here holds a ticket.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One ticket verb the window called, in call order — the queue [`super::UiScript::take_gm_ticket_intents`]
-/// drains. Ordered rather than counted so the wire sees what Lua did, in the order Lua did it.
+/// One ticket verb the window called, drained in call order.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum GmTicketIntent {
-    /// `GetGMTicket()` — `CMSG_GMTICKET_GETTICKET`.
+    /// `GetGMTicket()`: `CMSG_GMTICKET_GETTICKET`.
     Ask,
-    /// `GetGMStatus()` — `CMSG_GMTICKET_SYSTEMSTATUS`.
+    /// `GetGMStatus()`: `CMSG_GMTICKET_SYSTEMSTATUS`.
     AskStatus,
-    /// `DeleteGMTicket()` — `CMSG_GMTICKET_DELETETICKET`.
+    /// `DeleteGMTicket()`: `CMSG_GMTICKET_DELETETICKET`.
     Delete,
-    /// `NewGMTicket`/`UpdateGMTicket` — create or edit.
+    /// `NewGMTicket` or `UpdateGMTicket`.
     Write(GmTicketWrite),
 }
 
-/// One `NewGMTicket` / `UpdateGMTicket` call, drained by the app.
+/// One `NewGMTicket` or `UpdateGMTicket` call.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct GmTicketWrite {
-    /// The `GMTicketCategory.dbc` id the window had selected — `HelpFrameOpenTicket.ticketType`,
-    /// which is the clicked category row's own id.
+    /// The selected `GMTicketCategory.dbc` id (`HelpFrameOpenTicket.ticketType`).
     pub category: u32,
-    /// The text as typed. The window's EditBox caps it at 500 letters; the engine's own cap is
-    /// 1999, so nothing here truncates what the UI allowed.
+    /// The text as typed; the EditBox caps it at 500, under the reference's 1999.
     pub text: String,
-    /// `true` for `NewGMTicket` (file), `false` for `UpdateGMTicket` (edit). Two different
-    /// opcodes with two different answers, so the distinction survives to the app rather than
-    /// being re-derived from whether a ticket is believed to exist — the reference picks the verb
-    /// from its own `HelpFrameOpenTicket.hasTicket` flag and we must not second-guess it.
+    /// `NewGMTicket` or `UpdateGMTicket`, two opcodes: the window picks by its own `hasTicket`
+    /// flag, and the app must not re-derive it.
     pub is_new: bool,
 }
 
 impl super::UiScript {
-    /// Publish the ticket categories `GetGMTicketCategories()` returns — the `GMTicketCategory.dbc`
-    /// rows, in file order. Pushed once at load; the table is static client data.
+    /// The `GMTicketCategory.dbc` rows in file order, pushed once; the ids are the wire's values,
+    /// so renumbering them would misfile every ticket.
     pub fn set_gm_ticket_categories(&mut self, categories: Vec<(u32, String)>) {
         self.model_mut().gm_ticket_categories = categories;
     }
 
-    /// Drain every ticket verb the window called since the last drain, **in call order** — the
-    /// module doc's reason. Each entry is exactly one packet.
+    /// Drain the ticket verbs in call order, one packet each.
     pub fn take_gm_ticket_intents(&mut self) -> Vec<GmTicketIntent> {
         std::mem::take(&mut self.model_mut().gm_ticket_intents)
     }
 
-    /// Drain the `Stuck()` calls — each is one cast of spell 7355.
+    /// Drain the `Stuck()` calls, each one cast of spell 7355.
     pub fn take_stuck_casts(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().stuck_casts)
     }
 }
 
-/// Register the seven Help-window globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetGMTicketCategories() — the flat (id, name) vararg list, consumed by
-    // `HelpFrameGM_UpdateCategories` as `arg[i]`/`arg[i+1]` pairs. Empty until the app has pushed
-    // the DBC (a bare-XML harness, or a run with no client data): the window then simply paints no
-    // category rows, which is the honest rendering of "we have no catalog" and cannot error.
+    // A flat `id, name, ...` vararg list, walked in pairs by `HelpFrameGM_UpdateCategories`;
+    // empty until the app pushes the DBC.
     g.set(
         "GetGMTicketCategories",
         lua.create_function(|lua, ()| {
@@ -104,11 +68,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The three payload-free verbs. Each pushes onto the ONE ordered queue, so a chunk that calls
-    // two of them sends two packets in the order it called them.
-    //   GetGMTicket()    — "send me my ticket"; a send, answered as UPDATE_TICKET.
-    //   GetGMStatus()    — "is the petition queue up?"; answered as UPDATE_GM_STATUS.
-    //   DeleteGMTicket() — the HELP_TICKET_ABANDON_CONFIRM dialog's Yes.
+    // Sends: `GetGMTicket` is answered by `UPDATE_TICKET`, `GetGMStatus` by `UPDATE_GM_STATUS`.
     for (name, intent) in [
         ("GetGMTicket", GmTicketIntent::Ask),
         ("GetGMStatus", GmTicketIntent::AskStatus),
@@ -126,9 +86,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // NewGMTicket(category, text) / UpdateGMTicket(category, text) — the window's Submit and its
-    // Save Changes. Same signature, different opcode; the reference's own usage string is
-    // `Usage: UpdateGMTicket(type, text)`, so (number, string) is the declared arity for both.
+    // Submit and Save Changes: one signature, `(type, text)` in the reference's usage string.
     for (name, is_new) in [("NewGMTicket", true), ("UpdateGMTicket", false)] {
         g.set(
             name,
@@ -146,10 +104,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // Stuck() — the Help window's "Auto-Unstuck". NOT a ticket verb despite living only in this
-    // window: it casts spell 7355 "Stuck", whose SPELL_EFFECT_STUCK teleports the player to their
-    // last safe position server-side. It is registered here because HelpFrame is its only caller
-    // in the whole shipped UI, and a module for one binding would be worse than this note.
+    // The Help window's Auto-Unstuck, not a ticket verb: it casts spell 7355, whose
+    // `SPELL_EFFECT_STUCK` moves the player to a safe position server-side.
     g.set(
         "Stuck",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/gossip.rs b/crates/benilla-ui/src/script/gossip.rs
index 87b6a6fd..0dddf537 100644
--- a/crates/benilla-ui/src/script/gossip.rs
+++ b/crates/benilla-ui/src/script/gossip.rs
@@ -1,72 +1,49 @@
-//! The gossip bindings (decision 0081 phase 3) — the Era-shaped NPC-dialog surface, the same
-//! two-way seam as [`super::container`]: the app pushes a **gossip menu snapshot**
-//! ([`UiScript::set_gossip`] — the greeting + option rows already resolved from the wire), and the
-//! Lua `SelectGossipOption`/`CloseGossip` calls queue outbound **intents** the app drains
-//! ([`UiScript::take_gossip_selects`] / [`UiScript::take_gossip_close`]). The engine holds no NPC
-//! knowledge — an option is "a label, an icon type, and whether it's coded".
+//! The gossip bindings: the app pushes the open menu ([`UiScript::set_gossip`]), and
+//! `SelectGossipOption` and `CloseGossip` queue intents it drains.
 //!
-//! ## The Era API shape
+//! `GetGossipOptions()` returns flat `(text, type)` pairs, `type` the lowercase icon name the app
+//! maps from the wire `GOSSIP_ICON`. A coded option is not built: the app drops its select, where
+//! the reference opens a password box (`UIParent.lua:563`). `IsGossipOptionCoded(i)` is benilla's
+//! own, not a 1.12 global, and no stock file calls it.
 //!
-//! 1.12's `GetGossipOptions()` returns a flat vararg of `(text, type)` pairs — the FrameXML's
-//! `GossipFrameUpdate` walks it two-at-a-time, `SetText`ing each `GossipTitleButton` and mapping the
-//! `type` string to an `Interface\GossipFrame\<Type>GossipIcon` texture. Benilla keeps that exact
-//! shape: `GetGossipOptions()` returns `label1, type1, label2, type2, …`, where `type` is the
-//! lowercase Era icon name (`"gossip"`/`"vendor"`/`"taxi"`/`"trainer"`/…) the app derived from the
-//! wire `GOSSIP_ICON` byte. The one addition is `IsGossipOptionCoded(i)` — a benilla-local
-//! predicate the XML uses to grey password-gated options (decision 0081 v1: coded options are
-//! parsed and greyed, never selected; the real client pops a password box, out of scope here).
-//! `GetGossipText()` returns the greeting body (`SMSG_NPC_TEXT_UPDATE`), `nil` when no menu is
-//! open. There is no "menu open, text pending" state: while a greeting is in flight the app
-//! pushes nothing and fires nothing — the VM keeps its last menu (or none), exactly as the
-//! reference's frame keeps its last paint (its handler returns on a cache miss without an event,
-//! and its greeting write and `GOSSIP_SHOW` are adjacent and unconditional on one success path —
-//! wow-re `gossip-npctext-law.md` §1/§4; B292, benilla decisions 1508/1994), which is why
-//! [`GossipMenu::greeting`] is a plain `String`.
+//! A menu is pushed only once its greeting (`SMSG_NPC_TEXT_UPDATE`) has arrived; until then the
+//! VM keeps its last menu, as the reference's frame keeps its last paint: its handler returns on a
+//! cache miss without an event, and the greeting write and `GOSSIP_SHOW` share one success path
+//! (`0x4e2010`, `0x4e22b0`).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One gossip menu option, resolved by the app from the wire `GossipOption` (decision 0081). Plain
-/// data — 1-based order in the menu is its position in [`GossipMenu::options`].
+/// One gossip option; its 1-based index is its place in [`GossipMenu::options`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct GossipOptionView {
-    /// The option label (`SetText` on its row button).
+    /// The option's label.
     pub label: String,
-    /// The Era `GetGossipOptions()` second value — the lowercase icon *type* the app mapped from
-    /// the wire `GOSSIP_ICON` byte (`"gossip"`/`"vendor"`/`"taxi"`/`"trainer"`/…). The XML resolves
-    /// it to a `Interface\GossipFrame\<Type>GossipIcon` texture.
+    /// The lowercase icon type (`"gossip"`, `"vendor"`, `"taxi"`, …); `GossipFrame.lua:123` draws
+    /// `Interface\GossipFrame\<Type>GossipIcon`.
     pub icon_type: String,
-    /// A password-gated (`coded`) option — greyed and unselectable in v1 (decision 0081).
+    /// A password-gated option, which the app never selects.
     pub coded: bool,
 }
 
-/// One quest row riding a gossip menu (`SMSG_GOSSIP_MESSAGE`'s quest-option block). A gossip NPC
-/// that also gives quests lists them above the gossip options; a click sends
-/// `CMSG_QUESTGIVER_QUERY_QUEST` (decision 0088). `active` splits the row into the "current quests"
-/// vs "available quests" headers (the app derives it from the wire dialog-status icon); the app maps
-/// the clicked 1-based row back to its quest id.
+/// One quest row of `SMSG_GOSSIP_MESSAGE`; a click sends `CMSG_QUESTGIVER_QUERY_QUEST`. `active`,
+/// from the wire icon, puts it under current quests rather than available ones.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct GossipQuestRow {
     pub title: String,
-    /// The quest's level — `SMSG_GOSSIP_MESSAGE`'s own third field per quest row.
-    ///
-    /// The app parsed it and dropped it until 1751's twenty-first window, because the invented
-    /// `GetGossipQuestInfo` had nowhere to put it. The reference's two verbs return the rows as
-    /// `(title, level)` PAIRS, and stock `GossipFrame.lua` strides its walk by 2 over them — so
-    /// the level is load-bearing for the stride even though 1.12's own FrameXML never reads it.
+    /// The row's third wire field. 1.12 never shows it, but the verbs return `(title, level)` pairs
+    /// and `GossipFrame.lua:66` strides by 2 over them.
     pub level: u32,
     pub active: bool,
 }
 
-/// One open gossip menu: the greeting body, the quest rows, and the option rows. Pushed whole by
-/// the app; `None` means no menu is open.
+/// One open gossip menu, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct GossipMenu {
-    /// The NPC greeting, always resolved: a menu is only pushed once its `SMSG_NPC_TEXT_UPDATE`
-    /// answered — an open gossip frame with a blank page is not a reachable state (module doc).
+    /// The NPC greeting, always resolved.
     pub greeting: String,
-    /// Quest rows the NPC offers/has active, riding the same packet (decision 0088).
+    /// Quest rows from the same packet.
     pub quests: Vec<GossipQuestRow>,
     pub options: Vec<GossipOptionView>,
 }
@@ -82,14 +59,12 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().gossip_selects)
     }
 
-    /// Whether `CloseGossip` was called since the last drain (and clear the flag). vanilla's
-    /// client-side close sends no packet — the app just clears its local menu state.
+    /// Whether `CloseGossip` was called since the last drain; the 1.12 close sends no packet.
     pub fn take_gossip_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().gossip_close)
     }
 
-    /// Drain the 1-based quest-row positions queued by `SelectGossipQuest` since the last call. The
-    /// app maps each to the row's quest id + the open NPC and sends `CMSG_QUESTGIVER_QUERY_QUEST`.
+    /// Drain the queued 1-based whole-menu quest-row positions.
     pub fn take_gossip_quest_selects(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().gossip_quest_selects)
     }
@@ -99,8 +74,6 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // → the greeting body, or nil while there is no menu (an open menu always has one — the
-    // app-side hold, module doc).
     g.set(
         "GetGossipText",
         lua.create_function(|lua, ()| {
@@ -115,11 +88,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → flat (label, type) pairs, the Era `GetGossipOptions()` vararg shape.
     g.set(
         "GetGossipOptions",
         lua.create_function(|lua, ()| {
-            // Collect owned data under one short borrow, then build the Lua values with none held.
+            // Copy out under one short borrow; build the Lua values with none held.
             let pairs: Vec<(String, String)> = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 model.gossip.as_ref().map_or_else(Vec::new, |m| {
@@ -138,8 +110,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsGossipOptionCoded(i) — benilla-local: the XML greys a coded (password) option (decision
-    // 0081). `i` is 1-based; an out-of-range index is `false`.
     g.set(
         "IsGossipOptionCoded",
         lua.create_function(|lua, i: usize| {
@@ -152,9 +122,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SelectGossipOption(i [, ...]) — queue the 1-based option position; the app maps it to the
-    // wire option index + guid. Extra Era args (the code / a confirm flag) are ignored: v1 never
-    // sends a code (decision 0081).
+    // SelectGossipOption(i [, ...]): queue the 1-based position. Further arguments, a code among
+    // them, are ignored: coded options are not built, so no code is ever sent.
     g.set(
         "SelectGossipOption",
         lua.create_function(|lua, (i, _rest): (u32, mlua::MultiValue)| {
@@ -164,7 +133,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseGossip() — client-side close (no packet, vanilla): flag it so the app clears its menu.
     g.set(
         "CloseGossip",
         lua.create_function(|lua, ()| {
@@ -174,22 +142,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ══ THE TWO QUEST LISTS, and why there are two ══════════════════════════════════════════
-    //
-    // 1.12 splits the gossip packet's quest rows by their WIRE ICON — `{3,4}` are "active", every
-    // other value "available" (decision 0758) — and publishes each list through its own vararg
-    // verb. The reference runs that same test lazily behind these two bindings
-    // (`0x4e2430`/`0x4e2580`); we run it at parse time and keep the answer on the row.
-    //
-    // **Each row is a PAIR: `(title, level)`.** Stock `GossipFrameAvailableQuestsUpdate` /
-    // `…ActiveQuestsUpdate` walk `for i = 1, arg.n, 2` and read only `arg[i]`, so the level is
-    // never displayed in 1.12 — but it is what makes the stride land, and an addon reading the
-    // second slot gets the number the server sent rather than a nil.
-    //
-    // These four REPLACE `GetNumGossipQuests` / `GetGossipQuestInfo` / `SelectGossipQuest`, which
-    // were benilla's own single-list shape and appear nowhere in `reference/1.12-globals.tsv`.
-    // 1189's rule: a superset is not free — an addon that feature-detects on a name the client
-    // does not have takes a branch we cannot honour.
+    // ══ The two quest lists ══
+    // The reference splits the quest rows by wire icon, 3 and 4 active and the rest available,
+    // behind two vararg verbs (`0x4e2430`, `0x4e2580`); the app splits them at parse time.
     fn quest_rows(lua: &Lua, active: bool) -> mlua::Result<MultiValue> {
         let rows: Vec<(String, u32)> = {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -218,14 +173,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, ()| quest_rows(lua, true))?,
     )?;
 
-    // The two selects. Each index is 1-based **within its own list**, which is what
-    // `GossipTitleButton_OnClick` passes: the reference re-numbers the rows per list as it lays
-    // them out (`titleIndex`), so a menu with two available and one active quest hands the active
-    // row a 1, not a 3.
-    //
-    // The queue the app drains is one list, so the index is mapped back to the WHOLE row order
-    // here — the app's own `take_gossip_quest_selects` contract is unchanged, and the two verbs
-    // stay a pure re-expression of it rather than a second drain to wire up.
+    // A select's index is 1-based within its own list, as `GossipFrame.lua:73` numbers the
+    // buttons; it maps back to the whole-menu position the app's queue holds.
     fn select_quest(lua: &Lua, active: bool, index: usize) {
         let whole = {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -291,7 +240,6 @@ mod tests {
     #[test]
     fn gossip_snapshot_reads_and_selects_queue() {
         let mut s = UiScript::new().unwrap();
-        // No menu: text nil, no options.
         assert!(s.eval::<bool>("return GetGossipText() == nil").unwrap());
         assert_eq!(s.arity("GetGossipOptions()").unwrap(), 0);
 
@@ -300,7 +248,6 @@ mod tests {
             s.eval::<String>("return GetGossipText()").unwrap(),
             "Greetings, traveler."
         );
-        // Flat (label, type) pairs: 2 options → 4 return values.
         let (l1, t1, l2, t2) = s
             .eval::<(String, String, String, String)>(
                 "local a,b,c,d = GetGossipOptions()\n\
@@ -314,12 +261,10 @@ mod tests {
         );
         assert_eq!(l2, "I would like to sign the petition.");
         assert_eq!(t2, "gossip");
-        // The coded (petition) option is flagged for greying; the vendor one isn't.
         assert!(!s.eval::<bool>("return IsGossipOptionCoded(1)").unwrap());
         assert!(s.eval::<bool>("return IsGossipOptionCoded(2)").unwrap());
         assert!(!s.eval::<bool>("return IsGossipOptionCoded(9)").unwrap()); // out of range
 
-        // Selecting queues the 1-based position; closing flags the intent.
         s.run("SelectGossipOption(1)").unwrap();
         s.run("SelectGossipOption(2, 'unused-code')").unwrap(); // extra arg ignored
         assert_eq!(s.take_gossip_selects(), vec![1, 2]);
@@ -331,22 +276,11 @@ mod tests {
         assert!(!s.take_gossip_close(), "drained");
     }
 
-    /// **The two quest lists the reference publishes, and the two selects that index INTO them.**
-    ///
-    /// This replaces a test of `GetNumGossipQuests`/`GetGossipQuestInfo`/`SelectGossipQuest` —
-    /// benilla's own single-list shape, and three names that appear nowhere in
-    /// `reference/1.12-globals.tsv`. 1189's rule is why they had to go rather than sit beside the
-    /// real four: an addon that feature-detects on a name this client does not have takes a branch
-    /// we cannot honour.
-    ///
-    /// The row shape is a `(title, level)` PAIR because stock `GossipFrameAvailableQuestsUpdate`
-    /// walks `for i = 1, arg.n, 2` and reads `arg[i]`. 1.12 never displays the level; it is the
-    /// stride that needs it, and an addon reading the second slot should get the server's number.
     #[test]
     fn the_two_gossip_quest_lists_split_by_active_and_select_within_themselves() {
         use super::GossipQuestRow;
         let mut s = UiScript::new().unwrap();
-        // No menu → both lists are empty, and that is `arg.n == 0`, not a nil.
+        // No menu: `arg.n == 0`, not a nil.
         assert_eq!(s.arity("GetGossipAvailableQuests()").unwrap(), 0);
         assert_eq!(s.arity("GetGossipActiveQuests()").unwrap(), 0);
 
@@ -370,7 +304,6 @@ mod tests {
         ];
         s.set_gossip(Some(m));
 
-        // Two available, in menu order, each a pair.
         assert_eq!(
             s.eval::<(String, i64, String, i64)>("return GetGossipAvailableQuests()")
                 .unwrap(),
@@ -381,24 +314,18 @@ mod tests {
                 9
             )
         );
-        // One active, and the active row does NOT appear in the available list even though it
-        // comes first in the menu — the split is the wire icon, not the position.
+        // The active row comes first in the menu but splits by icon, not position.
         assert_eq!(
             s.eval::<(String, i64)>("return GetGossipActiveQuests()")
                 .unwrap(),
             ("Report to Goldshire".to_string(), 5)
         );
 
-        // **Each select is 1-based within its OWN list**, which is what
-        // `GossipTitleButton_OnClick` passes (the reference re-numbers per list as it lays the
-        // rows out). Available #2 is "Kobold Camp Cleanup", the THIRD row of the menu — and the
-        // queue the app drains is still whole-menu positions, so it must come back as 3.
+        // Available #2 is the menu's third row.
         s.run("SelectGossipAvailableQuest(2)").unwrap();
         assert_eq!(s.take_gossip_quest_selects(), vec![3]);
-        // …and the single active row is #1 in its list, the FIRST of the menu.
         s.run("SelectGossipActiveQuest(1)").unwrap();
         assert_eq!(s.take_gossip_quest_selects(), vec![1]);
-        // Out of range queues nothing rather than a wrong row.
         s.run("SelectGossipAvailableQuest(9) SelectGossipActiveQuest(0)")
             .unwrap();
         assert!(s.take_gossip_quest_selects().is_empty(), "drained");
diff --git a/crates/benilla-ui/src/script/guild.rs b/crates/benilla-ui/src/script/guild.rs
index f8d6e08d..b53b4e6b 100644
--- a/crates/benilla-ui/src/script/guild.rs
+++ b/crates/benilla-ui/src/script/guild.rs
@@ -1,76 +1,25 @@
-//! The guild **Era API surface** — roster, ranks, notes, MOTD, and the membership verbs
-//! (decision 1257).
+//! The guild bindings: roster, ranks, notes, MOTD and the membership verbs. The app pushes a
+//! display-ready [`GuildState`] ([`UiScript::set_guild`]) that joins two caches: the roster (MOTD,
+//! info text, rank rights, members) and the guild query (the name and ten rank names). Each verb
+//! queues a [`GuildRequest`] the app drains ([`UiScript::take_guild_requests`]).
 //!
-//! [`super::social`]'s shape exactly: the app pushes a [`GuildState`] snapshot built from its own
-//! wire mirror ([`UiScript::set_guild`]) and the getters here read that plain data; every verb
-//! queues a [`GuildRequest`] the app drains ([`UiScript::take_guild_requests`]) into the matching
-//! `CMSG_*` send. No ECS or net reach from the engine (decision 0068 §3).
-//!
-//! **The snapshot is already display-ready** — member names, localized class names, zone names,
-//! rank names, and the last-online decomposition — because every one of those is a *lookup the
-//! engine owns* in the real client too. Unlike the friend list and `/who`, the guild roster
-//! carries level/class/zone for **offline** members as well (the server keeps them in the guild
-//! table), which is why those columns stay populated and merely grey out.
-//!
-//! **Guild identity and guild roster are two different caches, and this file joins them.**
-//! `SMSG_GUILD_ROSTER` carries the MOTD, the info text, the rank *rights* and the members — but
-//! **not** the guild's name and **not** the rank *names*. Those come only from
-//! `SMSG_GUILD_QUERY_RESPONSE`, which answers a `CMSG_GUILD_QUERY(guildId)` with the name plus a
-//! fixed array of ten rank names. The app does the joining before it pushes; [`GuildState`] is
-//! the joined result.
-//!
-//! **Two index bases coexist, and callers must convert.** A roster row's `rankIndex` (from
-//! `GetGuildRosterInfo`) is **0-based**, `0` = guild master — the reference computes
-//! `maxRankIndex = GuildControlGetNumRanks() - 1` and compares roster indices against it
-//! (`FriendsFrame.lua:338`, `:393-398`). The whole `GuildControl*` family is **1-based**, driven
-//! straight off dropdown IDs `1..GuildControlGetNumRanks()` (`:820-822`, `:855-857`, `:866-868`).
-//! Mixing them silently promotes the wrong rank, so every conversion here is spelled out.
-//!
-//! **Rank-control edits are staged, and the staging is write-only.** `GuildControlSetRank(i)`
-//! loads rank `i` into [`GuildRankEdit`], `GuildControlSetRankFlag(idx, on)` writes one staged
-//! slot, and `GuildControlSaveRank(name)` folds the thirteen slots over a freshly re-read *live*
-//! baseline and queues one intent. The buffer is deliberately *not* part of the pushed snapshot:
-//! it is scratch the popup owns between open and Accept, and a snapshot push mid-edit would
-//! otherwise discard the user's unsaved checkbox clicks.
-//!
-//! The counter-intuitive half, and it is verified: **`GuildControlGetRankFlags` reads the LIVE
-//! rights, never the staging buffer.** A checkbox click is invisible through the getter until the
-//! save round-trips and a fresh roster lands. Reading the buffer back would feel more responsive
-//! and would be a different client.
-//!
-//! **The roster is never filtered.** `GetGuildRosterInfo`, `GetGuildRosterLastOnline` and
-//! `SetGuildRosterSelection` all address the *whole* member list; only `GetNumGuildMembers`
-//! respects the show-offline toggle, and indices past it are valid and return real offline
-//! members. See [`GuildState::num_members`] — this is the opposite of the obvious design, and
-//! collapsing the two is the mistake it exists to prevent.
-//!
-//! **Era booleans are `1`/`nil`, never `true`/`false`** — `IsInGuild`, `IsGuildLeader` and every
-//! `Can*` predicate below. The FrameXML branches on truthiness and stores the result, so a
-//! `false` where the reference gives `nil` survives into places a `nil` would not.
+//! Two index bases: a roster `rankIndex` is 0-based with 0 the guild master
+//! (`FriendsFrame.lua:338`, `:393-398`), while the `GuildControl*` family is 1-based, driven by
+//! the dropdown IDs (`FriendsFrame.lua:820-822`, `:855-857`, `:866-868`).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The thirteen guild rank permissions, **in `GuildControlGetRankFlags`' return order** — which is
-/// also `GuildControlPopupFrameCheckbox1..13`'s order and the index `GuildControlSetRankFlag`
-/// takes. That ordering *is* the API contract: `GuildControlCheckboxUpdate` loops
-/// `for i=1, arg.n` over the returns and drives `getglobal("GuildControlPopupFrameCheckbox"..i)`
-/// (`FriendsFrame.lua:874-884`), so nothing but position connects a flag to its checkbox.
+/// The thirteen rank rights in `GuildControlGetRankFlags`' return order, which is also the
+/// checkbox order and `GuildControlSetRankFlag`'s index: only position ties a flag to its checkbox
+/// (`FriendsFrame.lua:874-884`). The labels are `GUILDCONTROL_OPTION1..13`
+/// (`GlobalStrings.lua:2036-2048`).
 ///
-/// The labels, in this order, are `GUILDCONTROL_OPTION1..13`
-/// (`GlobalStrings.lua:2036-2048`): Guildchat Listen · Guildchat Speak · Officerchat Listen ·
-/// Officerchat Speak · Promote · Demote · Invite Member · Remove Member · Set MOTD ·
-/// Edit Public Note · View Officer Note · Edit Officer Note · Modify Guild Info.
-///
-/// **The map is not monotonic, and that is the whole reason it is a table rather than a shift.**
-/// Promote (index 5) is `0x80` and Demote (6) is `0x100`, both *above* Invite (7) `0x10` and
-/// Remove (8) `0x20` in bit value while *below* them in checkbox order. `1 << (i - 1)` is wrong
-/// for nine of the thirteen. Bits `0x40`, `0x400` and `0x800` are unused.
-///
-/// Bits from vmangos `src/game/Guild/Guild.h:56-74` (`GuildRankRights`), with that enum's
-/// `GR_RIGHT_EMPTY` (`0x40`) stripped — it is OR'd into every one of its entries, so it carries no
-/// per-permission information.
+/// Not bit order: Promote and Demote (5, 6) are `0x80` and `0x100`, above Invite and Remove
+/// (7, 8) at `0x10` and `0x20`, so `1 << (i - 1)` is wrong for nine of the thirteen. The bits are
+/// vmangos `GuildRankRights` (`Guild/Guild.h:56-74`) without the `GR_RIGHT_EMPTY` `0x40` it ORs
+/// into each; `0x40`, `0x400` and `0x800` are none of the thirteen.
 pub const RANK_RIGHT_BITS: [u32; 13] = [
     0x0000_0001, // 1  Guildchat Listen
     0x0000_0002, // 2  Guildchat Speak
@@ -87,9 +36,7 @@ pub const RANK_RIGHT_BITS: [u32; 13] = [
     0x0001_0000, // 13 Modify Guild Info
 ];
 
-/// Named indices into [`RANK_RIGHT_BITS`], for the `Can*` predicates. One-based, matching the
-/// checkbox numbering the reference's strings use, so a reader can check them against
-/// `GUILDCONTROL_OPTION<n>` without arithmetic.
+/// One-based indices into [`RANK_RIGHT_BITS`], numbered as `GUILDCONTROL_OPTION<n>`.
 mod right {
     pub(super) const PROMOTE: usize = 5;
     pub(super) const DEMOTE: usize = 6;
@@ -102,24 +49,16 @@ mod right {
     pub(super) const MODIFY_GUILD_INFO: usize = 13;
 }
 
-/// The lowest and highest rank counts a guild can have — the reference's own guard rails, which
-/// it enforces client-side before the server ever sees the request:
-/// `GuildControlPopupFrameAddRankButton_OnUpdate` disables Add at `>= 10`
-/// (`FriendsFrame.lua:887`) and `..RemoveRankButton_OnUpdate` only shows Remove when the selected
-/// rank is the last *and* the count exceeds 5 (`:908`). Same numbers as vmangos'
-/// `GUILD_RANKS_MIN_COUNT` / `GUILD_RANKS_MAX_COUNT` (`Guild.h:31-32`).
+/// The fewest ranks: `GuildControlDelRank` refuses at it and the Remove button shows only above it
+/// (`FriendsFrame.lua:908`); vmangos `GUILD_RANKS_MIN_COUNT` (`Guild/Guild.h:31`).
 pub const MIN_RANKS: usize = 5;
-/// See [`MIN_RANKS`].
+/// The most ranks: `GuildControlAddRank` refuses at it and the Add button disables there
+/// (`FriendsFrame.lua:887`); vmangos `GUILD_RANKS_MAX_COUNT` (`Guild/Guild.h:32`).
 pub const MAX_RANKS: usize = 10;
 
-/// How long ago a member was last seen, already decomposed into the four units
-/// `GetGuildRosterLastOnline` returns. The wire carries one `f32` — days since last login, sent
-/// only for *offline* members — and the decomposition is engine math, so the app does it once and
-/// the VM just reports it.
-///
-/// The reference reads these largest-unit-first and stops at the first non-zero
-/// (`GuildFrame_GetLastOnline`, `FriendsFrame.lua:957-978`), so the contract that matters is that
-/// exactly the largest applicable unit is non-zero.
+/// `GetGuildRosterLastOnline`'s four units, decomposed by the app from the wire's one `f32` of
+/// days offline. `GuildFrame_GetLastOnline` shows the largest non-zero unit, reading nil as 0
+/// (`FriendsFrame.lua:957-978`).
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct LastOnline {
     pub years: u32,
@@ -128,191 +67,139 @@ pub struct LastOnline {
     pub hours: u32,
 }
 
-/// A unit's guild membership, as `GetGuildInfo(unit)` reports it — hung off
-/// [`super::unit::UnitState`] because the binding is per-unit and the descriptor is public.
-///
-/// `PLAYER_GUILDID` (field 191) and `PLAYER_GUILDRANK` (field 192) are PUBLIC, so these arrive
-/// for *every visible player*, not just us (vmangos `Objects/UpdateFields_1_12_1.h:121-122`;
-/// UNIT_END = 188, the same arithmetic that pins `PLAYER_FLAGS` = 190). The app turns the id into
-/// a name through its guild-identity cache and the rank field into a rank name through that
-/// identity's ten rank names — which is exactly why the query response carries a fixed ten.
+/// A unit's guild as `GetGuildInfo(unit)` reports it. `PLAYER_GUILDID` (191) and
+/// `PLAYER_GUILDRANK` (192) are public descriptor fields (vmangos
+/// `Objects/UpdateFields_1_12_1.h:121-122`), so every visible player carries one; the app names
+/// them through its guild query cache.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct UnitGuild {
-    /// The guild's name — **never empty**.
-    ///
-    /// A cache miss does not produce a blank-named `UnitGuild`: it produces `None`. The binding
-    /// takes the *same* nil path on the cache-miss leg (`0x4c93d7 je 0x4c943c`) as on the
-    /// guildless leg, so "we have not resolved this id yet" and "this unit has no guild" are
-    /// indistinguishable to Lua by design. That matters — `UnitPopup.lua:575` passes the result
-    /// straight into a StaticPopup format, and an empty name would render `<>` there.
+    /// Never empty: an unresolved guild is `None`, as the binding takes the same nil path on a
+    /// cache miss as for no guild (`0x4c93d7 je 0x4c943c`).
     pub name: String,
-    /// The unit's rank name within that guild.
     pub rank_name: String,
-    /// The unit's rank, **0-based**, `0` = guild master.
+    /// 0-based, 0 the guild master.
     pub rank_index: u32,
 }
 
-/// One guild rank: its name (from the query response) and its rights word (from the roster).
+/// One guild rank: its name from the guild query, its rights from the roster.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct GuildRankInfo {
-    /// The rank's display name, e.g. "Guild Master". Empty for a rank the query response has not
-    /// named yet.
+    /// Empty until the guild query names it.
     pub name: String,
-    /// The rank's permission bits — test with [`RANK_RIGHT_BITS`].
+    /// Tested with [`RANK_RIGHT_BITS`].
     pub rights: u32,
 }
 
-/// One roster row, already resolved for display. Mirrors `GetGuildRosterInfo`'s nine returns in
-/// field order, which is how `FriendsFrame.lua` destructures them (`:344`, `:447`, `:479`).
+/// One roster row resolved for display: `GetGuildRosterInfo`'s ten returns in order, then the
+/// last-online time.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct GuildMemberInfo {
-    /// The character's name. Carried on the wire in the roster itself, so unlike a friend row
-    /// this never waits on a name query.
+    /// On the wire in the roster itself, so it never waits on a name query.
     pub name: String,
-    /// The member's rank *name*, e.g. "Officer" — `GetGuildRosterInfo`'s second return.
+    /// The rank's name.
     pub rank: String,
-    /// The member's rank as a **0-based** index, `0` = guild master. See the module doc: this is
-    /// the opposite base from the `GuildControl*` family.
+    /// 0-based, 0 the guild master; the `GuildControl*` family is 1-based.
     pub rank_index: u32,
     pub level: u32,
-    /// Localized class name ("Warrior"). Populated for offline members too.
+    /// The localized class name. The roster carries class, level and zone for offline members too.
     pub class: String,
-    /// Zone name ("Elwynn Forest"), empty when the id has no `AreaTable` row.
+    /// The zone name, empty when the id has no `AreaTable` row.
     pub zone: String,
     /// The public note.
     pub note: String,
-    /// The officer note. The server sends this empty when the *viewer* lacks
-    /// `View Officer Note`, so an empty string here is "not permitted" and "not set" alike —
-    /// which is exactly what the reference can distinguish too (it gates on `CanViewOfficerNote`
-    /// separately rather than on emptiness).
+    /// Empty both when unset and when the server blanks it for a viewer without View Officer
+    /// Note; the frame gates on `CanViewOfficerNote` instead.
     pub officer_note: String,
     pub online: bool,
-    /// The away tag, exactly as the friends list spells it: `""`, `"<AFK>"` or `"<DND>"` —
-    /// `GetGuildRosterInfo`'s **tenth** return.
-    ///
-    /// It is easy to miss that there is a tenth. Six of the reference's seven call sites
-    /// destructure only nine (`FriendsFrame.lua:344`, `:447`, `:479`, `:709`,
-    /// `StaticPopup.lua:1008`, `:1045`) — but the player-status view takes ten
-    /// (`FriendsFrame.lua:541`) and then branches on `status == ""` to choose between the
-    /// "Online" label and the tag itself (`:548-551`). An engine that answered nil there would
-    /// blank that column silently, and every nine-value call site would keep working.
-    ///
-    /// This is also what the wire's presence byte is *for*: `GRF_ONLINE`/`GRF_AFK`/`GRF_DND`
-    /// (0x01/0x02/0x04) would not need three bits if the API only exposed a boolean.
+    /// The tenth return: `""`, `"<AFK>"` or `"<DND>"`. Only the status view reads it, to choose
+    /// between the Online label and the tag (`FriendsFrame.lua:541`, `:548-551`).
     pub status: String,
-    /// How long since this member was last seen — meaningful only when `online` is false. The
-    /// wire omits it entirely for online members.
+    /// Meaningful only offline; the wire omits it for online members.
     pub last_online: LastOnline,
 }
 
-/// The guild snapshot, pushed whole by the app whenever it changes ([`UiScript::set_guild`]).
-/// `default()` is the guildless shape, which is also the fresh-login shape.
+/// The guild snapshot the app pushes whole when it changes ([`UiScript::set_guild`]); the default
+/// is guildless.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct GuildState {
-    /// Whether the player is in a guild at all — `IsInGuild`. Driven by the player's own
-    /// `PLAYER_GUILDID` descriptor field (191), so it is true from the moment the descriptor
-    /// streams, *before* any roster has arrived.
+    /// `IsInGuild`, from the player's own `PLAYER_GUILDID` (191), so true before any roster.
     pub in_guild: bool,
-    /// The guild's name. Only `SMSG_GUILD_QUERY_RESPONSE` carries it, so it stays empty in the
-    /// window between `in_guild` going true and that query answering.
+    /// Only `SMSG_GUILD_QUERY_RESPONSE` carries it, so it is empty until that query answers.
     pub name: String,
-    /// The player's own rank name.
     pub rank_name: String,
-    /// The player's own rank, **0-based**, `0` = guild master.
+    /// The player's own rank, 0-based, 0 the guild master.
     pub rank_index: u32,
-    /// Whether the player is the guild master — `IsGuildLeader`.
+    /// `IsGuildLeader`: the player is the guild master.
     pub is_leader: bool,
-    /// The player's own rank's rights word, which every `Can*` predicate tests.
+    /// The player's own rank's rights, which every `Can*` predicate tests.
     pub rights: u32,
-    /// The message of the day.
     pub motd: String,
-    /// The guild info text (the `GuildInfoFrame` body).
+    /// The `GuildInfoFrame` body.
     pub info_text: String,
-    /// The **whole** roster, sorted — never filtered. `GetGuildRosterInfo` indexes this directly,
-    /// 1-based, and so do `GetGuildRosterLastOnline` and `SetGuildRosterSelection`.
-    ///
-    /// **It is NOT filtered by [`Self::show_offline`], and its length is NOT
-    /// `GetNumGuildMembers()`.** See [`Self::num_members`] — this asymmetry is verified and it is
-    /// the opposite of what the obvious design would do.
+    /// The whole roster, sorted and never filtered: `GetGuildRosterInfo`,
+    /// `GetGuildRosterLastOnline` and `SetGuildRosterSelection` index it 1-based.
     pub roster: Vec<GuildMemberInfo>,
-    /// What `GetNumGuildMembers()` reports: the count the UI loops to, which **does** respect
-    /// [`Self::show_offline`].
-    ///
-    /// **This is an advisory loop bound, not the addressable range.** In the real client the three
-    /// index-taking bindings all bound against the *full* member count (`[0xb73118]`) and never
-    /// read the show-offline flag at all, while `GetNumGuildMembers` answers a different number
-    /// entirely — so **indices past it are valid and return real offline members** (wow-re
-    /// `system/ui/scratch/guild-api-carve.md`, correcting our claim A4).
-    ///
-    /// Collapsing the two — filtering the vector and reporting its length — is the natural design
-    /// and it is wrong: it would make a selection that survives a show-offline toggle address a
-    /// different member, or none.
+    /// `GetNumGuildMembers()`, the UI's loop bound, which respects [`Self::show_offline`]. The
+    /// index-taking bindings bound against the full count (`[0xb73118]`) and never read the flag,
+    /// so an index past this still returns a real offline member.
     pub num_members: usize,
-    /// Every rank, index 0 = guild master. Length is the guild's real rank count, which is what
-    /// `GuildControlGetNumRanks` reports.
+    /// Every rank, 0 the guild master; the length is `GuildControlGetNumRanks`.
     pub ranks: Vec<GuildRankInfo>,
-    /// The selected roster row as a **1-based** index into [`Self::roster`], `0` = none — the
-    /// scale `GetGuildRosterSelection` reports and `FriendsFrame.lua:347` tests with `> 0`.
+    /// The selected row, 1-based into [`Self::roster`], 0 for none (`FriendsFrame.lua:347` tests
+    /// `> 0`).
     pub selection: u32,
-    /// Whether the UI is showing offline members. Affects [`Self::num_members`] only — never
-    /// [`Self::roster`]'s contents.
+    /// Changes [`Self::num_members`] only, never [`Self::roster`].
     pub show_offline: bool,
 }
 
-/// The rank-control popup's staging buffer — the rank it has loaded and the rights word it has
-/// been editing. See the module doc on why this is not part of the pushed snapshot.
+/// The rank-control popup's staging buffer, kept out of [`GuildState`] so a push mid-edit does not
+/// discard unsaved checkbox clicks.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct GuildRankEdit {
-    /// The **1-based** rank `GuildControlSetRank` last loaded; `0` = none loaded yet.
+    /// The 1-based rank `GuildControlSetRank` last loaded, 0 for none.
     pub rank: u32,
-    /// The thirteen staged checkbox states, positionally matching [`RANK_RIGHT_BITS`].
-    ///
-    /// Held per-flag rather than as a packed word because that is what the binding does — it
-    /// stages `mask[k] & rights` into thirteen separate slots and `SetRankFlag` writes exactly
-    /// one of them. Keeping a word here instead would work only as long as nothing outside the
-    /// thirteen bits mattered, and `0x40` is precisely such a bit.
+    /// The thirteen staged checkboxes in [`RANK_RIGHT_BITS`] order, one slot per flag as the
+    /// binding stages them, so the save leaves every other bit of the live rights alone.
     pub staged: [bool; 13],
 }
 
-/// Outbound guild intents queued by the Era API, drained by the app
-/// ([`UiScript::take_guild_requests`]). Plain data — [`super::social::SocialRequest`]'s twin.
+/// Outbound guild intents, drained by the app ([`UiScript::take_guild_requests`]).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum GuildRequest {
-    /// `GuildRoster()` — ask the server for a fresh roster (`CMSG_GUILD_ROSTER`). Throttled
-    /// app-side to one per 10 s, as the reference is; the `GUILD_ROSTER_UPDATE` arg1 path clears
-    /// that throttle first so the FrameXML's response request is never the one swallowed.
+    /// `GuildRoster()` (`CMSG_GUILD_ROSTER`). The app throttles it to one per 10 s as the reference
+    /// does; the `GUILD_ROSTER_UPDATE` arg1 path clears the throttle first, so the FrameXML's own
+    /// request is never the one dropped.
     Roster,
-    /// `GuildInfo()` — the `/ginfo` query (`CMSG_GUILD_INFO`), whose answer is a chat line.
+    /// `GuildInfo()`, the `/ginfo` query (`CMSG_GUILD_INFO`), answered as a chat line.
     Info,
     /// `GuildInviteByName(name)`.
     Invite(String),
-    /// `GuildUninviteByName(name)` — remove a member (`CMSG_GUILD_REMOVE`).
+    /// `GuildUninviteByName(name)` (`CMSG_GUILD_REMOVE`).
     Uninvite(String),
     /// `GuildPromoteByName(name)`.
     Promote(String),
     /// `GuildDemoteByName(name)`.
     Demote(String),
-    /// `GuildSetLeaderByName(name)` — hand over the guild.
+    /// `GuildSetLeaderByName(name)`.
     SetLeader(String),
-    /// `AcceptGuild()` — the `GUILD_INVITE` popup's Accept.
+    /// `AcceptGuild()`.
     Accept,
-    /// `DeclineGuild()` — its Decline.
+    /// `DeclineGuild()`.
     Decline,
     /// `GuildLeave()`.
     Leave,
     /// `GuildDisband()`.
     Disband,
-    /// `GuildSetMOTD(text)`. An empty string is a real value meaning "clear it".
+    /// `GuildSetMOTD(text)`; an empty string clears it.
     SetMotd(String),
     /// `SetGuildInfoText(text)`.
     SetInfoText(String),
-    /// `GuildRosterSetPublicNote(index, note)` — the index is the 1-based display row, which the
-    /// app resolves to the name the wire wants.
+    /// `GuildRosterSetPublicNote(index, note)`: a 1-based display row the app resolves to the name
+    /// the wire takes.
     SetPublicNote { index: u32, note: String },
     /// `GuildRosterSetOfficerNote(index, note)`.
     SetOfficerNote { index: u32, note: String },
-    /// `GuildControlSaveRank(name)` — the staged buffer flushed as one `CMSG_GUILD_RANK`. The
-    /// rank is carried **0-based**, converted here once, because that is the base the wire uses.
+    /// `GuildControlSaveRank(name)` as one `CMSG_GUILD_RANK`; the rank is 0-based, as on the wire.
     SaveRank {
         rank_index: u32,
         rights: u32,
@@ -320,23 +207,21 @@ pub enum GuildRequest {
     },
     /// `GuildControlAddRank(name)`.
     AddRank(String),
-    /// `GuildControlDelRank()` — delete the last rank. **Carries nothing**: the binding reads no
-    /// argument and the packet (`0x233`) is body-less; the server infers which rank.
+    /// `GuildControlDelRank()`: no argument and an empty `0x233`; the server deletes the last rank.
     DelRank,
-    /// `SetGuildRosterSelection(index)` — mirrored into the app so the next push agrees.
+    /// `SetGuildRosterSelection(index)`, mirrored so the next push agrees.
     Select(u32),
-    /// `SetGuildRosterShowOffline(flag)` — the app re-filters and pushes back.
+    /// `SetGuildRosterShowOffline(flag)`, mirrored so the next push agrees.
     SetShowOffline(bool),
-    /// `SortGuildRoster(field)` — one of `"name"`, `"zone"`, `"level"`, `"class"`, `"rank"`,
-    /// `"note"`, `"online"` (the seven the reference's two column sets set as `this.sortType`,
-    /// `FriendsFrame.xml:1895-1940` and `:2086-2131`). Sorting is client-side; the app re-orders
-    /// its own roster and pushes it back.
+    /// `SortGuildRoster(field)`: `"name"`, `"zone"`, `"level"`, `"class"`, `"rank"`, `"note"` or
+    /// `"online"`, the headers' `sortType`s (`FriendsFrame.xml:1895-1940`, `:2086-2131`). Sorting
+    /// is client-side: the app re-orders its roster and pushes it back.
     Sort(String),
 }
 
 impl super::UiScript {
-    /// Push the guild snapshot, replacing whatever was there. A bare setter — firing
-    /// `GUILD_ROSTER_UPDATE`/`PLAYER_GUILD_UPDATE`/`GUILD_MOTD` on the edges is the app's job.
+    /// Push the guild snapshot, replacing it. The app fires `GUILD_ROSTER_UPDATE`,
+    /// `PLAYER_GUILD_UPDATE` and `GUILD_MOTD` on the edges.
     pub fn set_guild(&mut self, state: GuildState) {
         self.model_mut().guild = state;
     }
@@ -346,16 +231,14 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().guild_requests)
     }
 
-    /// Queue an intent from the app side — the slash commands (`/ginvite`, `/gquit`, `/gpromote`,
-    /// …). In the reference these ARE Lua (`SlashCmdList["GUILDINVITE"]` calls
-    /// `GuildInviteByName`); benilla parses slash lines in Rust, so the same intents enter the
-    /// same queue here. [`super::social::SocialRequest`]'s `queue_social_request` twin.
+    /// Queue an intent from a slash command (`/ginvite`, `/gquit`, `/gpromote`, ...). The
+    /// reference's slash commands are Lua calling the same bindings; benilla parses them in Rust.
     pub fn queue_guild_request(&mut self, request: GuildRequest) {
         self.model_mut().guild_requests.push(request);
     }
 }
 
-/// A roster row by 1-based display index, or `None` past the end.
+/// A roster row by 1-based index.
 fn member_at(roster: &[GuildMemberInfo], index: i64) -> Option<&GuildMemberInfo> {
     usize::try_from(index)
         .ok()
@@ -363,9 +246,9 @@ fn member_at(roster: &[GuildMemberInfo], index: i64) -> Option<&GuildMemberInfo>
         .and_then(|i| roster.get(i))
 }
 
-/// The Era truthiness coercion for a flag argument — `nil`, `false` and `0` are off, everything
-/// else is on. [`super::social`]'s `SetWhoToUI` does the same, and for the same reason: the
-/// FrameXML passes a checkbox's `GetChecked()`, which is `1`/`nil`, but addons pass booleans.
+/// A flag argument: `nil`, `false` and `0` are off, anything else on. The reference reads both
+/// flags with `GetBoolOrDefault` (`0x6f1c10`, `binding_abi::bool_or_default`), which differs on
+/// strings and fractions; the FrameXML's checkbox states, `1` or `nil`, read the same in both.
 fn truthy(value: &Value) -> bool {
     match value {
         Value::Nil | Value::Boolean(false) => false,
@@ -375,7 +258,8 @@ fn truthy(value: &Value) -> bool {
     }
 }
 
-/// The Era boolean: `1` for true, `nil` for false. See the module doc — this is not `Boolean`.
+/// The 1.12 boolean, `1` or `nil`: the FrameXML stores what it tests, so a `false` would survive
+/// where the reference's `nil` does not.
 fn era_bool(on: bool) -> Value {
     if on {
         Value::Integer(1)
@@ -384,17 +268,13 @@ fn era_bool(on: bool) -> Value {
     }
 }
 
-/// Whether the player's own rank holds the permission at `index` (1-based into
-/// [`RANK_RIGHT_BITS`]).
+/// Whether the player's own rank holds right `index`, 1-based into [`RANK_RIGHT_BITS`].
 fn has_right(model: &Model, index: usize) -> bool {
     model.guild.in_guild && model.guild.rights & RANK_RIGHT_BITS[index - 1] != 0
 }
 
-/// The **live** rights word of a 1-based rank, `0` for "no rank loaded" or out of range.
-///
-/// The rank editor reads live rights, never its own staging buffer — see
-/// `GuildControlGetRankFlags`. Factored out because `GuildControlSaveRank` needs the same value as
-/// its fold baseline, and the two reading different things is exactly how a save would drop bits.
+/// The live rights of a 1-based rank, 0 for none or out of range. `GuildControlGetRankFlags` and
+/// `GuildControlSaveRank`'s fold both read this, never the staging buffer.
 fn live_rights(model: &Model, rank_one_based: u32) -> u32 {
     (rank_one_based as usize)
         .checked_sub(1)
@@ -403,13 +283,24 @@ fn live_rights(model: &Model, rank_one_based: u32) -> u32 {
         .unwrap_or(0)
 }
 
-/// Register the guild globals against the snapshot store.
+/// The rank-name gate `GuildControlSaveRank` (`0x4d20d0`) and `GuildControlAddRank` (`0x4d2210`)
+/// run before any packet: the name up to the first NUL must be 1 to 16 UTF-16 code units
+/// (`0x65b250`), untrimmed, and is sent as measured. vmangos kicks a name over 15 code points; the
+/// app caps that at the send (`ui_guild::feed::capped_rank_name`).
+fn gated_rank_name(name: &str) -> Option<&str> {
+    let c_name = name.split('\0').next().unwrap_or_default();
+    (1..=16)
+        .contains(&c_name.encode_utf16().count())
+        .then_some(c_name)
+}
+
+/// Register the guild globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
     // ── Membership and identity ──────────────────────────────────────────────────────────────
-    // IsInGuild() (`0x516de0`) — reads the player's own PLAYER_GUILDID, so it is answerable
-    // before any roster arrives. `InGuildCheck` gates the whole tab on it.
+    // IsInGuild() (`0x516de0`) reads the player's own `PLAYER_GUILDID`, so it answers before any
+    // roster arrives.
     g.set(
         "IsInGuild",
         lua.create_function(|lua, ()| {
@@ -418,8 +309,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsGuildLeader() (`0x516e40`) — takes no argument; it reports whether the PLAYER is the
-    // guild master, which is rank 0.
+    // IsGuildLeader() (`0x516e40`) takes no argument: whether the player is the guild master.
     g.set(
         "IsGuildLeader",
         lua.create_function(|lua, ()| {
@@ -428,30 +318,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildInfo(unit) → guildName, rankName, rankIndex (`0x4c9330`). Every call site in 1.12's
-    // FrameXML passes "player" (`FriendsFrame.lua:114`, `:337`, `PaperDollFrame.lua:117`,
-    // `TabardFrame.lua:96`, `UnitPopup.lua:575`), but the binding is per-unit and the wire
-    // supports it: PLAYER_GUILDID (191) and PLAYER_GUILDRANK (192) are PUBLIC descriptor fields,
-    // and the query response's fixed ten rank names exist precisely so another unit's rank field
-    // can be turned into a rank name. So it reads the unit snapshot, not the player's guild.
-    //
-    // A guildless unit answers `nil, nil, 0` — three values, and the third is the NUMBER zero, not
-    // nil. The binding pushes 3 on both legs (`mov eax,3`), so a caller destructuring the third
-    // gets `0`. Returning nil there would be a different contract.
-    //
-    // **RECOGNISED and UNRESOLVABLE are two different things**, and this binding conflated them
-    // until the stock character sheet came off the chain (decision 1751). It resolves its argument
-    // through the GENERAL unit-token resolver `0x515940`, so an *unrecognised* token raises via the
-    // L-less `luaL_error 0x7040e0` at `0x515c1a` — but "a recognised-but-unresolvable token, a
-    // non-player, a guildless player and a not-yet-arrived cache record ALL return (nil, nil, 0)"
-    // (wow-re `system/ui` ledger, `0x4c9330`, VERIFIED, `scratch/guild-api-carve.md`).
-    //
-    // Ours raised on any token the model held no unit for, which includes `"player"` before the
-    // app has pushed the first snapshot. Stock `PaperDollFrame_SetGuild` calls
-    // `GetGuildInfo("player")` UNGUARDED out of `PaperDollFrame_OnShow` (`PaperDollFrame.lua:117`,
-    // reached from `:569`), so opening the character window in the frames before that push raised
-    // where the reference prints an empty guild line. [`check_unit_token`] is the resolver's own
-    // three-way split and every other unit binding already goes through it.
+    // GetGuildInfo(unit) → guildName, rankName, rankIndex (`0x4c9330`), per unit because the rank
+    // fields are public: it reads the unit snapshot, not the player's guild. The general resolver
+    // (`0x515940`) raises on an unrecognised token (`0x515c1a`); a recognised but unresolvable
+    // token, a non-player, a guildless player and an unarrived guild record all answer
+    // `nil, nil, 0`, the third the number 0 (`mov eax,3` on both legs). Stock
+    // `PaperDollFrame_SetGuild` calls it for `"player"` unguarded (`PaperDollFrame.lua:117`).
     g.set(
         "GetGuildInfo",
         lua.create_function(|lua, unit: Option<String>| {
@@ -472,9 +344,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The roster ───────────────────────────────────────────────────────────────────────────
-    // GetNumGuildMembers() (`0x4d1190`) — the loop bound `GuildStatus_Update` iterates to
-    // (`FriendsFrame.lua:446`), NOT the addressable range. It respects show-offline;
-    // GetGuildRosterInfo does not. See `GuildState::num_members` for why the two differ.
+    // GetNumGuildMembers() (`0x4d1190`): the loop bound (`FriendsFrame.lua:446`), which respects
+    // show-offline, not the addressable range (`GuildState::num_members`).
     g.set(
         "GetNumGuildMembers",
         lua.create_function(|lua, ()| {
@@ -484,17 +355,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // GetGuildRosterInfo(index) → name, rank, rankIndex, level, class, zone, note, officernote,
-    // online, status (`0x4d1200`). TEN returns, in that order.
-    //
-    // The tenth is easy to miss and expensive to miss: six of the reference's seven call sites
-    // take only nine (`FriendsFrame.lua:344`, `:447`, `:479`, `:709`, `StaticPopup.lua:1008`,
-    // `:1045`), and only the player-status view takes `status` (`:541`) to choose between the
-    // "Online" label and the `<AFK>`/`<DND>` tag (`:548-551`). Answering nine would leave that one
-    // column permanently blank while every other caller looked correct.
-    //
-    // An out-of-range index answers all-nils rather than erroring: the reference calls it with
-    // `GetGuildRosterSelection()`, which is 0 when nothing is selected, on every single
-    // `GuildStatus_Update` (`:344`) and only afterwards checks `> 0`.
+    // online, status (`0x4d1200`). Ten returns: only the status view takes the tenth
+    // (`FriendsFrame.lua:541`), every other call site nine. Out of range answers ten nils rather
+    // than raising: `GuildStatus_Update` passes the selection, 0 when none, before testing it
+    // (`FriendsFrame.lua:344`, `:347`).
     g.set(
         "GetGuildRosterInfo",
         lua.create_function(|lua, index: i64| {
@@ -517,10 +381,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildRosterLastOnline(index) → years, months, days, hours (`0x4d14a0`). The reference
-    // reads them largest-first and stops at the first non-zero (`GuildFrame_GetLastOnline`,
-    // `FriendsFrame.lua:957-978`), and treats nil exactly as 0, so an online member — for whom
-    // the wire sends no value at all — correctly falls through to "online now".
+    // GetGuildRosterLastOnline(index) → years, months, days, hours (`0x4d14a0`), all 0 for an
+    // online member, whom the wire sends no time for.
     g.set(
         "GetGuildRosterLastOnline",
         lua.create_function(|lua, index: i64| {
@@ -538,7 +400,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildRosterMOTD() / GetGuildInfoText() — the two free-text blocks the roster carries.
+    // GetGuildRosterMOTD() / GetGuildInfoText(): the two free-text blocks the roster carries.
     g.set(
         "GetGuildRosterMOTD",
         lua.create_function(|lua, ()| {
@@ -554,11 +416,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildRosterSelection() (`0x4d1890`) / SetGuildRosterSelection(index) (`0x4d1820`).
-    // 1-based, 0 = nothing selected. The setter mutates the snapshot in place *and* queues the
-    // intent, for [`super::social`]'s stated reason: the same Lua tick reads the new value back —
-    // `GuildStatus_Update` calls `GetGuildRosterSelection()` four times in one pass — and the
-    // app's own state has to follow so the next push agrees.
+    // GetGuildRosterSelection() (`0x4d1890`) / SetGuildRosterSelection(index) (`0x4d1820`):
+    // 1-based, 0 for none. The setter writes the snapshot and queues the intent: the same Lua pass
+    // reads it back, and the app's state must follow so the next push agrees.
     g.set(
         "GetGuildRosterSelection",
         lua.create_function(|lua, ()| {
@@ -578,8 +438,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetGuildRosterShowOffline() (`0x4d1e30`) / SetGuildRosterShowOffline(flag). Same
-    // mutate-and-mirror shape: the checkbox reads its own state back through the getter.
+    // GetGuildRosterShowOffline() (`0x4d1e30`) / SetGuildRosterShowOffline(flag): written in
+    // place and mirrored, as the selection is.
     g.set(
         "GetGuildRosterShowOffline",
         lua.create_function(|lua, ()| {
@@ -587,10 +447,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(era_bool(model.guild.show_offline))
         })?,
     )?;
-    //
-    // **Called with NO argument it defaults to TRUE**, not false — verified, and the opposite of
-    // what `truthy(nil)` would give. So an absent argument and an explicit `nil` differ here, and
-    // the binding must be able to tell them apart: hence `MultiValue` rather than `Value`.
+    // With no argument it turns show-offline on, unlike an explicit `nil`, hence `MultiValue`.
     g.set(
         "SetGuildRosterShowOffline",
         lua.create_function(|lua, args: MultiValue| {
@@ -605,11 +462,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SortGuildRoster(field) (`0x4d1cb0`) — the column headers' only action: their OnClick is
-    // `if (this.sortType) then SortGuildRoster(this.sortType) end` and nothing else
-    // (`FriendsFrame.xml:442-446`). No GuildStatus_Update, no GuildRoster — so the engine both
-    // re-orders and fires GUILD_ROSTER_UPDATE itself, and plainly must not re-request the roster
-    // from the server because a user clicked a header. The app does both on the drain.
+    // SortGuildRoster(field) (`0x4d1cb0`): the header's OnClick calls no `GuildStatus_Update` and
+    // no `GuildRoster` (`FriendsFrame.xml:442-446`), so the app re-orders and fires
+    // `GUILD_ROSTER_UPDATE` on the drain, without asking the server.
     g.set(
         "SortGuildRoster",
         lua.create_function(|lua, field: String| {
@@ -619,14 +474,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseGuildRoster() is `xor eax,eax; ret` in the real client — a TOTAL no-op that sends
-    // nothing and touches nothing. It exists as a symbol and does not do anything. Wiring it to a
-    // packet would invent traffic 1.12 never sends, so it is registered and does nothing here too.
+    // CloseGuildRoster() is `xor eax,eax; ret` in the reference: a no-op that sends nothing.
     g.set("CloseGuildRoster", lua.create_function(|_, ()| Ok(()))?)?;
 
-    // GuildRoster() — ask the server for a fresh roster. Note the app throttles this to one
-    // request per 10 s, as the reference does, and the `GUILD_ROSTER_UPDATE` arg1 path clears that
-    // throttle so the FrameXML's own response request is never the one swallowed.
+    // The argument-less verbs; the app throttles `GuildRoster()` (`GuildRequest::Roster`).
     for (global, request) in [
         ("GuildRoster", GuildRequest::Roster),
         ("GuildInfo", GuildRequest::Info),
@@ -646,10 +497,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     }
 
     // ── The by-name verbs ────────────────────────────────────────────────────────────────────
-    // Five globals of one shape (`0x48aef0`, `0x48afb0`, `0x48b050`, `0x48b0f0`, `0x48b190`): take
-    // a character name, queue the matching CMSG. An empty name is dropped rather than sent — the
-    // server answers a blank lookup with nothing at all, so it would look like a hang
-    // ([`super::social`]'s `AddFriend` note).
+    // Five name-taking verbs (`0x48aef0`, `0x48afb0`, `0x48b050`, `0x48b0f0`, `0x48b190`). An empty
+    // or whitespace name is not sent. vmangos ignores an empty one without a reply, except an
+    // invite, which it answers with `ERR_GUILD_PLAYER_NOT_FOUND_S`
+    // (`Handlers/GuildHandler.cpp:77-83`).
     for (global, make) in [
         ("GuildInviteByName", GuildRequest::Invite as fn(String) -> _),
         (
@@ -678,9 +529,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GuildSetMOTD(text) (`0x48b270`) / SetGuildInfoText(text) (`0x4d2380`). Unlike the by-name
-    // verbs, an EMPTY string is a real value here: it clears the block, and the wire has an
-    // explicit empty-body case for it. So these do not drop empties.
+    // GuildSetMOTD(text) (`0x48b270`) / SetGuildInfoText(text) (`0x4d2380`): an empty string is
+    // sent, and clears the text.
     for (global, make) in [
         ("GuildSetMOTD", GuildRequest::SetMotd as fn(String) -> _),
         (
@@ -698,9 +548,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GuildRosterSetPublicNote(index, note) (`0x4d15e0`) / ...SetOfficerNote (`0x4d1700`) — the
-    // note dialogs address the roster ROW, not a name; the app resolves the row to the name the
-    // wire carries, because only it knows the display order the index refers to.
+    // GuildRosterSetPublicNote(index, note) (`0x4d15e0`) / GuildRosterSetOfficerNote (`0x4d1700`)
+    // take a roster row, which the app resolves to the name the wire carries.
     for (global, make) in [
         (
             "GuildRosterSetPublicNote",
@@ -727,10 +576,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     }
 
     // ── The permission predicates ────────────────────────────────────────────────────────────
-    // Nine one-line globals, each testing one bit of the player's own rank's rights word
-    // (`0x4d18c0`, `0x4d1930`, `0x4d19a0`, `0x4d1a10`, `0x4d1c40` and the four whose names lack
-    // "Guild"). CanEditMOTD/CanEditPublicNote/CanViewOfficerNote/CanEditOfficerNote are called at
-    // `FriendsFrame.lua:427`, `:359`, `:370`, `:371`.
+    // Nine predicates, each one bit of the player's own rank's rights (`0x4d18c0`, `0x4d1930`,
+    // `0x4d19a0`, `0x4d1a10`, `0x4d1c40` among them).
     for (global, index) in [
         ("CanGuildPromote", right::PROMOTE),
         ("CanGuildDemote", right::DEMOTE),
@@ -752,9 +599,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     }
 
     // ── The rank-control popup ───────────────────────────────────────────────────────────────
-    // GuildControlGetNumRanks() (`0x4d1e60`) — the guild's real rank count, which is what
-    // `maxRankIndex = GuildControlGetNumRanks() - 1` turns into the 0-based bottom rank
-    // (`FriendsFrame.lua:338`).
+    // GuildControlGetNumRanks() (`0x4d1e60`): the guild's rank count.
     g.set(
         "GuildControlGetNumRanks",
         lua.create_function(|lua, ()| {
@@ -763,8 +608,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlGetRankName(index) (`0x4d1e90`) — ONE-BASED, straight off the dropdown's ID
-    // (`FriendsFrame.lua:857`, `:868`, `:895`, `:899`). See the module doc on the two bases.
+    // GuildControlGetRankName(index) (`0x4d1e90`): 1-based, the dropdown's ID.
     g.set(
         "GuildControlGetRankName",
         lua.create_function(|lua, index: i64| {
@@ -779,14 +623,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlSetRank(index) (`0x4d1fa0`) — load a rank into the staging buffer. ONE-based;
-    // it stores `index - 1` internally and seeds each of the thirteen staged slots from that
-    // rank's live rights.
-    //
-    // Passing 0 computes -1 and **silently clears the staged selection** — verified, and the
-    // reason this is `checked_sub` rather than a clamp: a caller that handed a raw 0-based roster
-    // `rankIndex` straight in (the standing trap, see the module doc) gets nothing loaded rather
-    // than rank 1 quietly loaded in its place.
+    // GuildControlSetRank(index) (`0x4d1fa0`): load a 1-based rank into the staging buffer, each
+    // slot seeded from its live rights. 0 clears the selection rather than loading rank 1, so a
+    // 0-based `rankIndex` passed by mistake loads nothing.
     g.set(
         "GuildControlSetRank",
         lua.create_function(|lua, index: i64| {
@@ -802,20 +641,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlGetRankFlags() (`0x4d1fe0`) — THIRTEEN returns, one per checkbox, in
-    // RANK_RIGHT_BITS order. `GuildControlCheckboxUpdate` loops `for i=1, arg.n` over them
-    // (`FriendsFrame.lua:874-884`), so both the count and the order are load-bearing.
-    //
-    // It is called at `GuildControlPopupFrame_OnLoad` (`:801`) — BEFORE `_OnShow` ever calls
-    // `GuildControlSetRank`, so it must answer thirteen well-formed values with nothing loaded.
-    // An unloaded buffer reads as all-off, which leaves every checkbox unchecked: the same thing
-    // the reference shows on a popup that has not selected a rank yet.
-    //
-    // **It reads the LIVE rank's rights, NOT the staging buffer** — verified. A checkbox click
-    // stages a change that is invisible through this getter until `GuildControlSaveRank`
-    // round-trips through the server and a fresh roster lands. Reading the buffer here would look
-    // more responsive and would be a different client: the reference's checkboxes genuinely do
-    // not "stick" until the save comes back.
+    // GuildControlGetRankFlags() (`0x4d1fe0`): thirteen returns in `RANK_RIGHT_BITS` order, from
+    // the loaded rank's live rights, never the staging buffer, so a click shows only once the save
+    // round-trips and a new roster lands. `GuildControlPopupFrame_OnLoad` calls it before any rank
+    // is loaded (`FriendsFrame.lua:801`), when all thirteen are nil.
     g.set(
         "GuildControlGetRankFlags",
         lua.create_function(|lua, ()| {
@@ -830,9 +659,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlSetRankFlag(index, enabled) (`0x4d2070`) — toggle one bit in the staging
-    // buffer. The index is the checkbox's, 1..13, and RANK_RIGHT_BITS maps it to the bit. This is
-    // the mapping that a `1 << (index - 1)` would get wrong for nine of the thirteen.
+    // GuildControlSetRankFlag(index, enabled) (`0x4d2070`): stage one checkbox, 1 to 13.
     g.set(
         "GuildControlSetRankFlag",
         lua.create_function(|lua, (index, enabled): (i64, Value)| {
@@ -849,25 +676,23 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlSaveRank(name) (`0x4d20d0`) — flush the staged edits as one CMSG_GUILD_RANK.
-    // The argument is the rank's (possibly renamed) NAME, taken from the popup's edit box
-    // (`FriendsFrame.lua:839`); the rank it applies to is whichever GuildControlSetRank loaded.
-    // Converted to the wire's 0-based rank id here, once.
-    //
-    // **The fold is a masked set-or-clear over a freshly re-read LIVE baseline** — verified: the
-    // binding does `or mask[k]` / `and ~mask[k]` per flag against the current rights, never a
-    // plain OR of a staged word. Two consequences, both of which a naive "send the staged word"
-    // implementation gets wrong:
-    //   · a plain OR could never turn a permission OFF, only on;
-    //   · bits outside the thirteen — notably `0x40`, which is tested NOWHERE in the image and is
-    //     a genuine gap rather than an always-set flag — must ride through untouched from whatever
-    //     the server last sent. Sending the staged word wholesale would clear them.
+    // GuildControlSaveRank(name) (`0x4d20d0`): the edit box's name (`FriendsFrame.lua:839`) and the
+    // staged flags as one `CMSG_GUILD_RANK` for the loaded rank. A name failing `gated_rank_name`
+    // is a silent no-op; vmangos stores an empty one (`Handlers/GuildHandler.cpp:586`). The fold
+    // sets or clears each staged bit over the freshly read live rights (`or mask[k]` /
+    // `and ~mask[k]`), so a right can be turned off and bits outside the thirteen, such as `0x40`,
+    // which the reference never tests, ride through as the server sent them.
     g.set(
         "GuildControlSaveRank",
         lua.create_function(|lua, name: String| {
+            let Some(name) = gated_rank_name(&name).map(str::to_string) else {
+                return Ok(());
+            };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let edit = model.guild_control.clone();
-            if edit.rank >= 1 {
+            // The reference's `[0x84966c] >= [0xb73120]`: no rank loaded (its -1, our 0) or one
+            // past the rank count.
+            if edit.rank >= 1 && (edit.rank as usize) <= model.guild.ranks.len() {
                 let mut rights = live_rights(&model, edit.rank);
                 for (i, bit) in RANK_RIGHT_BITS.iter().enumerate() {
                     if edit.staged[i] {
@@ -886,29 +711,25 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GuildControlAddRank(name) (`0x4d2210`) — append a rank. The client refuses at
-    // `numRanks >= MAX_RANKS` **silently**, before any packet, which is why the reference's Add
-    // button greys itself at ten (`FriendsFrame.lua:887`) rather than relying on a refusal.
+    // GuildControlAddRank(name) (`0x4d2210`): the same name gate, and a silent refusal at
+    // `MAX_RANKS`, both before any packet.
     g.set(
         "GuildControlAddRank",
         lua.create_function(|lua, name: String| {
+            let Some(name) = gated_rank_name(&name).map(str::to_string) else {
+                return Ok(());
+            };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            if !name.trim().is_empty() && model.guild.ranks.len() < MAX_RANKS {
+            if model.guild.ranks.len() < MAX_RANKS {
                 model.guild_requests.push(GuildRequest::AddRank(name));
             }
             Ok(())
         })?,
     )?;
 
-    // GuildControlDelRank() (`0x4d22e0`) — **reads no Lua argument at all**, and its packet
-    // (`0x233`) is body-less: the server deletes the LAST rank and infers which that is. The
-    // reference passes a name (`FriendsFrame.lua:895`) and the binding discards it, which is why
-    // the reference only offers the button when the selected rank IS the last (`:908`).
-    //
-    // Accepting-and-ignoring is the faithful shape. Taking the name and sending it would invent a
-    // wire field; refusing to compile against the reference's call would be worse.
-    //
-    // The client also refuses at `numRanks <= MIN_RANKS`, silently, before any packet.
+    // GuildControlDelRank() (`0x4d22e0`) reads no argument and sends an empty `0x233`: the server
+    // deletes the last rank. The FrameXML passes a name (`FriendsFrame.lua:895`), which is ignored.
+    // It refuses silently at `MIN_RANKS`, before any packet.
     g.set(
         "GuildControlDelRank",
         lua.create_function(|lua, _ignored: MultiValue| {
@@ -927,37 +748,24 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use super::*;
 
-    /// **`GetGuildInfo` splits three ways, not two** — wow-re `0x4c9330` (VERIFIED,
-    /// `scratch/guild-api-carve.md`): only an *unrecognised* token raises; a **recognised**
-    /// token that resolves to nothing answers `(nil, nil, 0)` like a guildless player does.
-    ///
-    /// The distinction is not academic. Stock `PaperDollFrame_SetGuild` calls
-    /// `GetGuildInfo("player")` unguarded from `PaperDollFrame_OnShow`, so before this split
-    /// existed, opening the character window in the frames before the app pushed its first player
-    /// snapshot raised — found by putting the reference's own `PaperDollFrame.xml` on the chain
-    /// (decision 1751). `"player"` with no unit behind it is the whole test.
+    /// `0x4c9330`: only an unrecognised token raises; `"player"` with no unit behind it, the paper
+    /// doll's case at world entry, answers `nil, nil, 0`.
     #[test]
     fn a_recognised_but_unresolved_unit_answers_nils_and_only_an_unknown_token_raises() {
         let s = crate::script::UiScript::new().unwrap();
-        // Recognised, resolves to nothing — the paper doll's own case at world entry.
         let (name, rank, idx): (Option<String>, Option<String>, i64) = s
             .eval(r#"return GetGuildInfo("player")"#)
             .expect("a recognised token must not raise");
         assert_eq!((name, rank, idx), (None, None, 0));
-        // …and the third value is the NUMBER zero on that leg, not nil (`mov eax,3` on both).
+        // The third value is the number 0, not nil (`mov eax,3` on both legs).
         assert!(s
             .eval::<bool>(r#"local a,b,c = GetGuildInfo("party3") return c == 0"#)
             .unwrap());
-        // Unrecognised: the resolver's own raise, unchanged.
         assert!(s
             .eval::<i64>(r#"return GetGuildInfo("nosuchunit")"#)
             .is_err());
     }
 
-    /// The thirteen-bit table is the API contract, and its non-monotonicity is the trap: Promote
-    /// and Demote sit at indices 5 and 6 with bits ABOVE Invite and Remove at 7 and 8. A
-    /// `1 << (i - 1)` implementation passes indices 1-4 and fails the other nine, so this asserts
-    /// the whole table rather than a property of it.
     #[test]
     fn the_rank_right_table_is_not_a_shift() {
         assert_eq!(RANK_RIGHT_BITS.len(), 13, "one bit per GUILDCONTROL_OPTION");
@@ -980,15 +788,8 @@ mod tests {
         }
     }
 
-    /// **`SaveRank` folds over the live baseline, so bits outside the thirteen survive.**
-    ///
-    /// `0x40` is tested nowhere in the 1.12 image — it is a genuine gap in the bit space, not an
-    /// always-set flag — and `SaveRank`'s fold neither sets nor clears it, so whatever the server
-    /// last sent rides through. An implementation that sent the staged word wholesale would clear
-    /// it (and any other unknown bit) on the first rank edit, silently, forever.
-    ///
-    /// The fold must also be able to turn a permission OFF, which a plain `OR` of a staged word
-    /// cannot.
+    /// `0x40`, vmangos's `GR_RIGHT_EMPTY`, is none of the thirteen and never tested by the
+    /// reference.
     #[test]
     fn saving_a_rank_preserves_bits_outside_the_thirteen_and_can_clear() {
         // Live: Invite (0x10) + Set MOTD (0x1000), plus the untouchable 0x40.
@@ -1020,8 +821,75 @@ mod tests {
         );
     }
 
-    /// A 1-based index past the end, and the 0 the reference passes on every `GuildStatus_Update`
-    /// before it checks the selection, both have to answer `None` rather than panic.
+    fn guild_with_ranks(n: usize) -> crate::script::UiScript {
+        let mut s = crate::script::UiScript::new().unwrap();
+        s.set_guild(GuildState {
+            in_guild: true,
+            ranks: (0..n)
+                .map(|i| GuildRankInfo {
+                    name: format!("Rank{i}"),
+                    rights: 0,
+                })
+                .collect(),
+            ..Default::default()
+        });
+        s
+    }
+
+    /// `0x4d20d0` refuses silently: a name outside 1 to 16 UTF-16 units (`0x65b250` counts them
+    /// plus the NUL), no rank loaded, or a rank past the count.
+    #[test]
+    fn saving_a_rank_refuses_what_the_reference_refuses() {
+        let mut s = guild_with_ranks(5);
+        let saves = |s: &mut crate::script::UiScript| {
+            s.take_guild_requests()
+                .into_iter()
+                .filter(|r| matches!(r, GuildRequest::SaveRank { .. }))
+                .count()
+        };
+
+        s.run(r#"GuildControlSetRank(2); GuildControlSaveRank("")"#)
+            .unwrap();
+        assert_eq!(saves(&mut s), 0, "an empty name is a silent no-op");
+
+        // Sixteen UTF-16 units is the ceiling; seventeen is refused.
+        s.run(r#"GuildControlSetRank(2); GuildControlSaveRank(string.rep("a", 16))"#)
+            .unwrap();
+        assert_eq!(saves(&mut s), 1);
+        s.run(r#"GuildControlSetRank(2); GuildControlSaveRank(string.rep("a", 17))"#)
+            .unwrap();
+        assert_eq!(saves(&mut s), 0, "seventeen units");
+        // Units, not bytes: sixteen two-byte letters are sixteen units.
+        s.run(r#"GuildControlSetRank(2); GuildControlSaveRank(string.rep("é", 16))"#)
+            .unwrap();
+        assert_eq!(saves(&mut s), 1, "32 bytes, 16 units");
+        // Whitespace is not empty to the reference.
+        s.run(r#"GuildControlSetRank(2); GuildControlSaveRank(" ")"#)
+            .unwrap();
+        assert_eq!(saves(&mut s), 1);
+
+        // No rank loaded in a fresh popup (the selection persists across saves, as `[0x84966c]`
+        // does), or one past the count.
+        let mut fresh = guild_with_ranks(5);
+        fresh.run(r#"GuildControlSaveRank("Officer")"#).unwrap();
+        assert_eq!(saves(&mut fresh), 0, "nothing selected");
+        s.run(r#"GuildControlSetRank(6); GuildControlSaveRank("Officer")"#)
+            .unwrap();
+        assert_eq!(saves(&mut s), 0, "rank index 5 >= 5 ranks");
+    }
+
+    /// `0x4d2210` runs the same name gate; a whitespace name passes it.
+    #[test]
+    fn adding_a_rank_runs_the_same_name_gate() {
+        let mut s = guild_with_ranks(5);
+        s.run(r#"GuildControlAddRank(""); GuildControlAddRank(string.rep("a", 17))"#)
+            .unwrap();
+        assert!(s.take_guild_requests().is_empty());
+        s.run(r#"GuildControlAddRank(" ")"#).unwrap();
+        assert_eq!(s.take_guild_requests().len(), 1);
+    }
+
+    /// `GuildStatus_Update` passes 0 before it tests the selection.
     #[test]
     fn member_lookup_is_one_based_and_tolerates_zero() {
         let roster = vec![
diff --git a/crates/benilla-ui/src/script/handler_prof.rs b/crates/benilla-ui/src/script/handler_prof.rs
index c2b74c6b..e124a6d1 100644
--- a/crates/benilla-ui/src/script/handler_prof.rs
+++ b/crates/benilla-ui/src/script/handler_prof.rs
@@ -1,42 +1,8 @@
-//! Per-handler cost attribution (`WOW_UI_HANDLERS=<secs>`) — *which* FrameXML handler is spending
-//! the frame. An `impl UiScript` block beside its concern, the `layout.rs` pattern.
-//!
-//! ## Why it exists (decision 1395)
-//!
-//! Three perf hunts in a row — 1383's autocast shine, 1385's cast bar, 1388's layout graph — each
-//! opened with the same question and each answered it **by hand**: read the shipped Lua, guess the
-//! busy handler, add a temporary print, re-run. `[ui-cost] tick=` is one aggregate over the whole
-//! `OnUpdate` sweep, so it can say *that* the sweep got expensive and never *who*. This is the
-//! missing decomposition, and it sits one layer below the one that landed beside it: 1389's HUD
-//! measures the frame's cost and latches its tail (`cpu`/`main` ms, the spike badge), which is
-//! **when** and **how much**; this is **who**, inside the UI's share of it.
-//!
-//! ## What it measures
-//!
-//! Every handler fired through [`super::event::fire`] — the single firing path for `OnUpdate`,
-//! `OnEvent`, `OnShow`/`OnHide`, `OnSizeChanged`, and the whole widget set (`OnClick`, `OnEnter`,
-//! `OnValueChanged`, …). Not just the tick's `OnUpdate` sweep, deliberately: an event storm (the
-//! combat log at 40 lines a second) costs frames the same way a hot `OnUpdate` does, and a `by
-//! script:` rollup on the report line is what tells the two apart at a glance.
-//!
-//! **Self and total, because handler firing nests.** A handler that calls `Show()` fires `OnShow`
-//! inside itself, and a handler that resizes something fires `OnSizeChanged`; charging the parent
-//! for its children would name the wrong frame, which is the one failure this instrument cannot
-//! afford. A stack of per-level child nanos gives both: `total` is what the call cost, `self` is
-//! what it cost *itself*. Sorted by `self`.
-//!
-//! Engine work a handler provokes synchronously **is** its self time, and that is the point — a
-//! geometry getter inside an `OnUpdate` calls `settle()`, which is a whole layout resolve
-//! (1388's opening finding: `OptionsScroll_Fit` does four per frame). That cost belongs to the
-//! handler that asked for it.
-//!
-//! ## What it costs when off
-//!
-//! One relaxed atomic load and a not-taken branch per handler fire ([`armed`]). The state lives in
-//! its own `app_data` slot rather than in [`super::Model`]: mlua keys `app_data` by `TypeId` with a
-//! **`RefCell` per entry** (`mlua-0.11.6`, `types/app_data.rs`), so the profiler's borrow can never
-//! collide with a model borrow held across a fire — a hazard that would otherwise be a panic in the
-//! hottest path in the client, armed only in the sessions where we are already chasing something.
+//! Per-handler cost attribution (`WOW_UI_HANDLERS=<secs>`): self and total time for every handler
+//! fired through [`super::event::fire`], since firing nests; engine work a handler provokes, such
+//! as a layout resolve, is its self time. Off, it costs a relaxed atomic load per fire ([`armed`]).
+//! Its state has its own `app_data` slot, not the model's: mlua keeps a `RefCell` per entry, so the
+//! profiler's borrow cannot collide with a model borrow held across a fire.
 
 use std::collections::HashMap;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -49,12 +15,8 @@ use super::UiScript;
 /// How many rows the periodic report prints before rolling the rest into a `… N more` line.
 const REPORT_ROWS: usize = 12;
 
-/// The fast gate: is *any* VM in this process profiling handlers?
-///
-/// Process-wide and not per-VM on purpose — the check runs per handler fire, and a per-VM answer
-/// would cost the `app_data` lookup this is here to avoid. A false positive (one VM armed, another
-/// not) costs the unarmed VM a hash lookup that finds `on == false`, which is the only case where
-/// the two answers differ and is not a case that ships.
+/// Whether any VM in the process profiles handlers: process-wide, so the per-fire check needs no
+/// `app_data` lookup.
 static ARMED: AtomicBool = AtomicBool::new(false);
 
 #[inline]
@@ -62,9 +24,7 @@ pub(super) fn armed() -> bool {
     ARMED.load(Ordering::Relaxed)
 }
 
-/// `WOW_UI_HANDLERS=<secs>` — the report period, read once. `WOW_UI_HANDLERS=3` reports every three
-/// seconds; anything unparseable or non-positive leaves the instrument off, the `[ui-cost]` /
-/// `[layout-prof]` posture.
+/// The report period from `WOW_UI_HANDLERS=<secs>`, read once; unparseable or non-positive is off.
 fn env_period() -> Option<f32> {
     static PERIOD: std::sync::OnceLock<Option<f32>> = std::sync::OnceLock::new();
     *PERIOD.get_or_init(|| {
@@ -83,37 +43,30 @@ struct Slot {
     self_ns: u64,
 }
 
-/// The profiler's state, one per VM, in its own `app_data` slot (see the module header).
-///
-/// Keyed by frame **id**, not by name: the name is a `String` clone and a two-map walk, so it is
-/// resolved once at report time rather than on every fire. A frame destroyed before the report
-/// reads back as `#<id>` — its cost still counted, which is what a churning pool of frames needs.
+/// The profiler's state, one per VM, keyed by frame id: names resolve at report time, and a frame
+/// destroyed before then still counts, as `#<id>`.
 #[derive(Default)]
 pub(crate) struct HandlerProf {
-    /// Is *this* VM recording? [`armed`] is the process-wide gate; this is the per-VM answer.
+    /// Whether this VM records; [`armed`] is the process-wide gate.
     on: bool,
-    /// Seconds between reports; `0.0` records forever and never prints (what a test wants).
+    /// Seconds between reports; `0.0` records and never prints.
     period: f32,
-    /// Wall seconds and frames since the last report — the window every printed rate divides by.
+    /// Wall seconds and frames since the last report, the divisor of every printed rate.
     window: f32,
     frames: u32,
-    /// Fires that had at least one nested fire inside them. Printed as the one-number answer to
-    /// "should I be reading `self` or `total` here?".
+    /// Fires that had a nested fire inside them.
     nested: u32,
-    /// Nanos already charged to *nested* fires, one entry per open fire. See the module header.
+    /// Nanos already charged to nested fires, one entry per open fire.
     stack: Vec<u64>,
     rows: HashMap<u32, Vec<Slot>>,
 }
 
-/// An open fire, closed by its `Drop` — the balance of the nesting stack is then a property of the
-/// borrow checker rather than of the call site remembering to close what it opened. It also holds
-/// under an unwind, which a hand-written enter/exit pair does not: a panic through a handler would
-/// otherwise leak a stack level and silently inflate every parent attribution after it.
+/// An open fire, closed by its `Drop`, so the nesting stack stays balanced through an unwind too.
 pub(super) struct Fire<'a> {
     lua: &'a Lua,
     id: u32,
     script: &'a str,
-    /// `None` while this VM is not recording — the whole guard is then a no-op.
+    /// `None` while this VM is not recording, which makes the guard a no-op.
     started: Option<Instant>,
 }
 
@@ -138,7 +91,7 @@ impl<'a> Fire<'a> {
 
 impl Drop for Fire<'_> {
     /// Charge `total` to `(id, script)`, `total - children` to its self time, and hand `total` up
-    /// to the enclosing fire as *its* child time.
+    /// to the enclosing fire as its child time.
     fn drop(&mut self) {
         let Some(started) = self.started else {
             return;
@@ -154,9 +107,7 @@ impl Drop for Fire<'_> {
         if children > 0 {
             prof.nested += 1;
         }
-        // `saturating_sub`: children are measured strictly inside this fire, so the subtraction
-        // cannot go negative by construction — but a construction argument is not a reason to hand
-        // a wrapped `u64` to a report if a clock ever disagrees.
+        // Children run inside this fire; saturating only matters if a clock disagrees.
         let self_ns = total.saturating_sub(children);
         let slots = prof.rows.entry(self.id).or_default();
         match slots.iter_mut().find(|s| s.script == self.script) {
@@ -165,8 +116,6 @@ impl Drop for Fire<'_> {
                 slot.total_ns += total;
                 slot.self_ns += self_ns;
             }
-            // The only allocation on this path, and only on a `(frame, script)` pair's first fire
-            // of the window — steady state is a linear scan over one frame's handful of slots.
             None => slots.push(Slot {
                 script: self.script.to_string(),
                 calls: 1,
@@ -180,23 +129,20 @@ impl Drop for Fire<'_> {
 /// One `(frame, script)` pair's cost over the profiler's current window.
 #[derive(Clone, Debug, PartialEq)]
 pub struct HandlerRow {
-    /// The frame's name, or `#<id>` for an anonymous or already-destroyed frame.
+    /// The frame's name, else where its handler was defined, else `#<id>`.
     pub frame: String,
     pub script: String,
     pub calls: u32,
-    /// Microseconds spent in this handler *excluding* handlers it fired — what to sort by.
+    /// Microseconds in this handler, excluding the handlers it fired.
     pub self_us: f64,
-    /// Microseconds spent in this handler *including* handlers it fired.
+    /// Microseconds in this handler, including the handlers it fired.
     pub total_us: f64,
 }
 
 impl UiScript {
-    /// Arm or disarm handler attribution for this VM, reporting every `period_secs` (`0.0` records
-    /// with no periodic report — read it with [`UiScript::handler_profile`] instead).
-    ///
-    /// Call it between ticks. An open [`Fire`] is inert either way (it decided once, at `open`),
-    /// but this clears the nesting stack, so a disarm from *inside* a handler would drop a level
-    /// its enclosing fires are still counting on.
+    /// Arm or disarm attribution for this VM, reporting every `period_secs` (`0.0`: no report, read
+    /// [`UiScript::handler_profile`]). Call it between ticks: it clears the nesting stack that open
+    /// fires count on.
     pub fn profile_handlers(&self, on: bool, period_secs: f32) {
         if on {
             ARMED.store(true, Ordering::Relaxed);
@@ -213,13 +159,9 @@ impl UiScript {
         prof.rows.clear();
     }
 
-    /// This VM's handler costs over the current window, heaviest **self** time first.
-    ///
-    /// Window totals, not per-frame rates — the frame count is [`UiScript::handler_profile_frames`],
-    /// so a caller that wants a rate divides by the number it also has to report.
+    /// This VM's handler costs over the current window as totals, heaviest self time first.
     pub fn handler_profile(&self) -> Vec<HandlerRow> {
-        // Snapshot under the profiler's borrow and then let it go: labelling reaches into the model
-        // *and* back into Lua, neither of which may be touched with a borrow of anything open.
+        // Snapshot, then release the borrow: labelling reaches into the model and back into Lua.
         let raw: Vec<(u32, String, u32, u64, u64)> = match self.lua.app_data_ref::<HandlerProf>() {
             Some(prof) => prof
                 .rows
@@ -257,15 +199,14 @@ impl UiScript {
         rows
     }
 
-    /// Frames ticked since the last report — [`UiScript::handler_profile`]'s denominator.
+    /// Frames ticked since the last report, [`UiScript::handler_profile`]'s denominator.
     pub fn handler_profile_frames(&self) -> u32 {
         self.lua
             .app_data_ref::<HandlerProf>()
             .map_or(0, |prof| prof.frames)
     }
 
-    /// Advance the profiler's window by one tick and print the report if it is due. Called at the
-    /// end of [`UiScript::tick`], so "a frame" means a ticked frame whatever else fired in it.
+    /// Count a ticked frame and print the report when due, at the end of [`UiScript::tick`].
     pub(super) fn report_handler_profile(&mut self, elapsed: f32) {
         if !armed() {
             return;
@@ -281,8 +222,7 @@ impl UiScript {
         if !due {
             return;
         }
-        // The rows first, so the model borrow the label walk takes is released before the profiler
-        // is borrowed mutably to reset it.
+        // The rows first: the label walk's model borrow must end before the profiler's mutable one.
         let rows = self.handler_profile();
         let mut prof = self
             .lua
@@ -297,14 +237,8 @@ impl UiScript {
 }
 
 impl UiScript {
-    /// A row's label: the frame's name, else **where the handler was written**, else `#<id>`.
-    ///
-    /// The definition site is not a nicety. `CreateFrame("Frame")` + `OnUpdate` with no name is
-    /// *the* addon timer idiom, so the anonymous case is not the rare one — it is exactly the set
-    /// of handlers an attribution table exists to catch, and `#4127` is not something anyone can
-    /// act on. `Function::info()` hands back the chunk and line, and every addon chunk is named
-    /// `@Interface\AddOns\<Folder>\<File>` (see [`super::addon_chunk_name`]), so the label reads as
-    /// the addon and the line to open.
+    /// A row's label: the frame's name, else the handler's `<file>:<line>` (an unnamed frame is the
+    /// common addon timer), else `#<id>`.
     fn handler_label(&self, id: u32, script: &str) -> String {
         let named = {
             let model = self.model_ref();
@@ -319,11 +253,9 @@ impl UiScript {
             .unwrap_or_else(|| format!("#{id}"))
     }
 
-    /// `<short_src>:<line>` for the function bound at `(id, script)`, or `None` if there is no such
-    /// binding or the VM cannot say (a C function, a stripped chunk).
+    /// `<short_src>:<line>` of the function bound at `(id, script)`, when the VM can say.
     fn handler_defined_at(&self, id: u32, script: &str) -> Option<String> {
-        // `raw_get` throughout: the registry's script tables are plain data, and a report must not
-        // be able to run a metamethod — that would re-enter Lua from inside an instrument.
+        // `raw_get`, so a report can never run a metamethod.
         let scripts: mlua::Table = self.lua.named_registry_value(super::REG_SCRIPTS).ok()?;
         let per: mlua::Table = scripts.raw_get(id).ok()?;
         let func: mlua::Function = per.raw_get(script).ok()?;
@@ -332,12 +264,8 @@ impl UiScript {
     }
 }
 
-/// The `[ui-handlers]` block: the window's shape, the per-script rollup, then the heaviest
-/// [`REPORT_ROWS`] handlers by self time with the remainder folded into one line.
-///
-/// Everything is **per frame**, because that is the unit every other cost in this client is quoted
-/// in (`[ui-cost] tick=`, the HUD's `cpu ms`) and the whole use of this instrument is comparing
-/// against those.
+/// The `[ui-handlers]` block, per frame like the client's other costs: the window, the per-script
+/// rollup, then the heaviest [`REPORT_ROWS`] handlers by self time and the rest in one line.
 fn print_report(rows: &[HandlerRow], window: f32, frames: u32, nested: u32) {
     let per_frame = f64::from(frames.max(1));
     let total_self: f64 = rows.iter().map(|r| r.self_us).sum();
@@ -379,11 +307,8 @@ fn print_report(rows: &[HandlerRow], window: f32, frames: u32, nested: u32) {
     }
 }
 
-/// Install the profiler's `app_data` slot, and arm it from the environment.
-///
-/// Unconditional (an empty `HandlerProf` is a few words) because mlua refuses to *insert* app data
-/// while any app data is borrowed — so the slot has to exist before the VM starts running, or
-/// [`UiScript::profile_handlers`] would carry a panic that only fires in the sessions using it.
+/// Install the profiler's `app_data` slot, armed from the environment. Unconditional: mlua refuses
+/// to insert app data while any is borrowed, so the slot must exist before the VM runs.
 pub(super) fn install(lua: &Lua) {
     let period = env_period();
     lua.set_app_data(HandlerProf {
diff --git a/crates/benilla-ui/src/script/inspect.rs b/crates/benilla-ui/src/script/inspect.rs
index cf5b17ad..8bdce4ec 100644
--- a/crates/benilla-ui/src/script/inspect.rs
+++ b/crates/benilla-ui/src/script/inspect.rs
@@ -1,38 +1,13 @@
-//! The **inspect** surface (decision 0631) — the intent queues behind the ref's
-//! `NotifyInspect`/`ClearInspectPlayer`, and the foreign-unit equipment view the unit-keyed
-//! `GetInventoryItem*` family reads through.
+//! The inspect bindings: `NotifyInspect` and `ClearInspectPlayer` queue intents, the app pushes
+//! the inspected unit's equipment ([`UiScript::set_inspect`]) for the unit-keyed
+//! `GetInventoryItem*` verbs, and `CanInspect` and `CheckInteractDistance` read a per-token
+//! distance map ([`UiScript::set_unit_reach`]).
 //!
-//! ## Why there is so little here
-//!
-//! Inspect is the thinnest of the item windows because **the data is already local**. A player's
-//! worn gear rides `PLAYER_VISIBLE_ITEM_<n>_0`, which is `UF_FLAG_PUBLIC` — the server streams it
-//! to every observer, and benilla already decodes it to render other players' equipment
-//! (`benilla::entities::equipment`). So the inspect window paints from a descriptor we hold, not
-//! from a reply we wait for; `SMSG_INSPECT` echoes the guid and nothing else, and no reference
-//! handler registers an inspect event. `InspectFrame_Show` calls `NotifyInspect(unit)` and
-//! `ShowUIPanel` in the same breath, and `InspectPaperDollFrame_OnShow` reads all 19 slots
-//! immediately (`Blizzard_InspectUI.lua:6-13`, `InspectPaperDollFrame.lua:57-79`).
-//!
-//! ## The seam
-//!
-//! - **Intents:** `NotifyInspect(unit)` queues the token (the app resolves it → player guid →
-//!   `CMSG_INSPECT`, which server-side also sets our selection); `ClearInspectPlayer()` flags the
-//!   drop, the ref's own `InspectFrame_OnHide` call.
-//! - **Push:** the app pushes an [`InspectView`] each frame the inspected unit's resolved slot
-//!   views change ([`UiScript::set_inspect`]), or `None` when nothing is being inspected.
-//! - **Read:** *no new item getters.* The reference's own `GetInventoryItemTexture(unit, slot)`
-//!   family is already unit-keyed; `super::char_stats::player_inv_slot` routes `"player"` to the
-//!   self feed and the inspected token here.
-//! - **Range:** the two verified d² predicates, `CanInspect` and `CheckInteractDistance`, over one
-//!   app-fed per-token distance map ([`UiScript::set_unit_reach`]) — the VM holds no positions. The
-//!   map itself is unit-general (every held unit, creature included) and is fed by
-//!   `benilla::ui_unit`; only `CanInspect`'s players-only leg is inspect's, and it rides in the
-//!   entry.
-//!
-//! The view is keyed by **unit token**, not guid — the ref stores `InspectFrame.unit` as a token
-//! and re-reads it on `PLAYER_TARGET_CHANGED`, so an inspect window follows a re-target exactly as
-//! the real one does. The `guid` rides along only so the app can tell "same token, different
-//! player" apart when it rebuilds.
+//! Worn gear is public descriptor state (`PLAYER_VISIBLE_ITEM_<n>_0`), so the window paints from
+//! what the client holds: `SMSG_INSPECT` echoes only the guid, `InspectFrame_Show` calls
+//! `NotifyInspect` and `ShowUIPanel` together (`Blizzard_InspectUI.lua:6-13`), and the paper doll
+//! reads all 19 slots on show (`InspectPaperDollFrame.lua:57-79`). The view is keyed by unit token,
+//! as the reference keeps `InspectFrame.unit`, so it follows a re-target.
 
 use std::cmp::Ordering;
 use std::collections::HashMap;
@@ -42,119 +17,71 @@ use mlua::{Lua, Value};
 use super::char_stats::InventorySlots;
 use super::Model;
 
-/// The `CheckInteractDistance` threshold table — `{10², 11.1111², 10², 30²}` for the live API's
-/// `type ∈ 1..4`, read straight out of the binary (wow-re §5-VERIFIED
-/// `PRIMITIVE:check_interact_dist2` @ `0x48ba00`, built from the static `.rdata` at
-/// `0x804498`/`0x804490`/`0x80448c`/`0x8044a4`). Type 1 is the *inspect* row's distance, and shares
-/// its 100.0 with [`super::inspect`]'s own `CanInspect` threshold.
+/// `CheckInteractDistance`'s squared thresholds for types 1..=4, `{10², 11.1111², 10², 30²}`
+/// (`0x48ba00`, from the `.rdata` at `0x804498`, `0x804490`, `0x80448c`, `0x8044a4`).
 pub const INTERACT_DIST_SQ: [f64; 4] = [100.0, 123.45678, 100.0, 900.0];
 
-/// The `CanInspect` threshold, **squared** — `DAT_00b4d918`, which the client's own writer builds by
-/// squaring the static `.rdata` `10.0` at `0x804498` (wow-re §5-VERIFIED
-/// `PRIMITIVE:caninspect_dist2` @ `0x48a1b0`, `ledger.tsv:823`). vmangos enforces the same 10 yards
-/// as `INSPECT_DISTANCE` (`ObjectDefines.h:26`), so client and server agree exactly.
+/// `CanInspect`'s threshold squared (`0xb4d918`, the `.rdata` 10.0 at `0x804498` squared by
+/// `0x48a1b0`); vmangos checks the same 10 yards (`INSPECT_DISTANCE`, `ObjectDefines.h:26`).
 pub const CAN_INSPECT_DIST_SQ: f64 = 100.0;
 
-/// What the app resolved about one unit token's unit this frame — the input both range predicates
-/// read ([`UiScript::set_unit_reach`]).
-///
-/// An entry exists **iff the token resolved to a live unit object**, which is the distinction the
-/// reference's own bindings turn on: `0x515940` maps the token to a GUID and then asks the object
-/// manager for it, and a NULL there is answered `nil` without any distance being computed. A party
-/// member outside the local area is exactly that case — `0x4e81a0` reads their GUID straight out of
-/// the roster array, so the GUID is non-zero and the object lookup misses silently.
+/// One token's unit this frame, as the two range verbs read it. An entry exists only when the
+/// token resolved to a live unit object: the reference maps the token to a GUID (`0x515940`) and
+/// answers nil when the object manager has no such unit, as for a party member out of the area,
+/// whose GUID comes from the roster (`0x4e81a0`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct UnitReach {
-    /// Squared distance from the player, in the binary's own accumulation shape.
+    /// Squared distance from the player.
     pub dist_sq: f64,
-    /// The unit passes the two NON-distance refusals vmangos makes for an inspect
-    /// (`sObjectMgr.GetPlayer` and `!IsValidAttackTarget`, `MiscHandler.cpp:945-956`) — consulted
-    /// by `CanInspect` alone. `CheckInteractDistance` is a pure distance test in the binary and
-    /// must not read this, or following an enemy player would gray a row the reference leaves live.
-    ///
-    /// `sObjectMgr.GetPlayer` is the whole is-it-a-player leg, and it lives **here** rather than in
-    /// the map's membership: the map is fed for every held unit, creature included (B304), so a
-    /// boar 3 yards away is `inspectable: false` while still answering `CheckInteractDistance`
-    /// truthfully.
+    /// A player, and not a valid attack target: vmangos's inspect refusals besides distance
+    /// (`MiscHandler.cpp:945-956`). Only `CanInspect` reads it: `CheckInteractDistance` is a pure
+    /// distance test, so a creature or an enemy player still answers it.
     pub inspectable: bool,
 }
 
-/// What the app has resolved for the unit currently being inspected (decision 0631).
+/// What the app has resolved for the unit currently being inspected.
 #[derive(Clone, Debug, PartialEq)]
 pub struct InspectView {
-    /// The unit token the frame is inspecting — the ref's `InspectFrame.unit` (`"target"`,
-    /// `"party3"`, …). The inventory router matches a binding's `unit` argument against this.
+    /// The inspected unit token, the reference's `InspectFrame.unit`; the inventory verbs match
+    /// their `unit` argument against it.
     pub unit: String,
-    /// The player guid the token resolved to when these slots were read.
+    /// The player the token resolved to, so the app can tell a new player behind the same token.
     pub guid: u64,
-    /// The inspected player's equipment, indexed by live-API inventory slot id exactly like the
-    /// self feed (1..=19). Index 0 (ammo) and 20..=23 (bags) stay `None` — a foreign player
-    /// exposes neither, and the ref's inspect paper doll has no button for them.
+    /// Equipment by inventory slot id 1..=19, like the self feed; ammo (0) and bags (20..=23) stay
+    /// `None`, since another player's are not visible.
     pub slots: InventorySlots,
 }
 
 impl super::UiScript {
-    /// Push the per-token **unit reach** map: unit token → squared distance from the player to
-    /// that unit, for **every** token the app resolved to a live unit object this frame. Nothing
-    /// to do with `UNIT_FIELD_COMBATREACH` — this is where each token's unit *is*, not how far it
-    /// swings.
-    ///
-    /// One app-fed number serves both range predicates, because the binary uses the same d² for
-    /// both: `CanInspect` compares it against `100.0`, and `CheckInteractDistance(unit, type)`
-    /// against [`INTERACT_DIST_SQ`]`[type-1]`.
-    ///
-    /// **The map is unit-general, not a players-only or popup-only one.** It was both, and being
-    /// both was report B304: `CheckInteractDistance` is a pure distance test over any unit token in
-    /// the binary, so a creature `"target"` that never entered the map made Quiver's 30-yard rung
-    /// answer a constant for every mob at every distance. The one typemask that *is* real —
-    /// inspect's — rides in the entry as [`UnitReach::inspectable`], never at the token.
-    ///
-    /// It lives here rather than on [`super::UnitState`] because a distance changes **every
-    /// frame**: the unit snapshots are pushed on diff (1439) and fire `UNIT_*` transitions when
-    /// they move, so folding a moving number into them would re-push and re-fire every token every
-    /// frame. This map is re-pushed wholesale instead, and nothing keys an event off it.
-    ///
-    /// A token absent from the map is a token the object manager holds **no unit for**, and both
-    /// predicates answer `nil` there — the reference's own null-object arm (wow-re
-    /// `system/ui/scratch/dist2-null-unit-arm.md`, VERIFIED: `0x48babe test ecx,ecx; je` →
-    /// `lua_pushnil`). It used to read as *in range*, on the reasoning that missing data must not
-    /// gray a row; the binary says the opposite, and that default was report B316 — every distance
-    /// row lit up for exactly the party member who was too far away to have an object at all.
-    ///
-    /// **Keys are lowercase** — the resolver folds case (`_strnicmp`, 1247), so the lookup does
-    /// too, exactly as `Model::unit` does for the snapshots.
+    /// Push the squared distance of every token that resolved to a live unit this frame, creature
+    /// included; both range verbs read the same d². A token absent from the map answers nil from
+    /// both, the reference's null-object arm (`0x48babe`). It changes every frame, so it stays off
+    /// [`super::UnitState`], whose diffs fire `UNIT_*` events. Keys are lowercase: the token
+    /// resolver folds case (`_strnicmp`).
     pub fn set_unit_reach(&mut self, reach: HashMap<String, UnitReach>) {
         self.model_mut().unit_reach = reach;
     }
 
-    /// Push (or clear, with `None`) the inspected unit's resolved equipment view. The app calls
-    /// this whenever the view changes; it fires no event of its own — the app fires
-    /// `UNIT_INVENTORY_CHANGED` for the inspected token, which is the signal the ref's
-    /// `InspectPaperDollItemSlotButton_OnEvent` actually listens for.
+    /// Push (or clear, with `None`) the inspected unit's equipment. It fires nothing: the app fires
+    /// `UNIT_INVENTORY_CHANGED` for the token, which the stock slot buttons listen for.
     pub fn set_inspect(&mut self, view: Option<InspectView>) {
         self.model_mut().inspect = view;
     }
 
-    /// Drain the unit tokens `NotifyInspect` queued — the app resolves each to a player guid and
-    /// sends `CMSG_INSPECT`.
+    /// Drain the tokens `NotifyInspect` queued; the app sends `CMSG_INSPECT` for each, which also
+    /// sets the server-side selection (`MiscHandler.cpp:945`).
     pub fn take_inspect_notifies(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().inspect_notifies)
     }
 
-    /// Whether `ClearInspectPlayer` was called since the last drain (and clear the flag) — the
-    /// app drops its inspect target, which stops the per-frame slot resolve.
+    /// Whether `ClearInspectPlayer` was called since the last drain; the app drops its target.
     pub fn take_inspect_clear(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().inspect_clear)
     }
 }
 
-/// What the app resolved for `token`, or `None` when it resolved to no live unit at all — the
-/// reference's NULL-object arm, which both predicates answer `nil` to.
-///
-/// Case-folded on the way in, the same shape `Model::unit` uses for the snapshot map: both
-/// predicates reach the unit through the one resolver `0x515970`, whose nine compares are
-/// `_strnicmp` (1247), so `CheckInteractDistance("Target", 4)` is the same question as
-/// `CheckInteractDistance("target", 4)`.
+/// The reach pushed for `token`, case-folded: both verbs resolve the token through `0x515970`,
+/// whose compares are `_strnicmp`.
 fn reach(lua: &Lua, token: &Option<String>) -> Option<UnitReach> {
     let token = token.as_deref()?;
     let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -168,17 +95,10 @@ fn reach(lua: &Lua, token: &Option<String>) -> Option<UnitReach> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // CanInspect(unit) → 1/nil: the gate the ref's `InspectFrame_Show` opens on
-    // (`Blizzard_InspectUI.lua:8`). The real client's `0x48a1b0` is a d² range test — wow-re
-    // §5-VERIFIED `PRIMITIVE:caninspect_dist2`: **out of range iff `threshold < d²`**, where
-    // `threshold = DAT_00b4d918 = 100.0` (10 yards, the same number vmangos enforces as
-    // `INSPECT_DISTANCE`). The operator is theirs too: `test ah,0x41; jne` skips the out-of-range
-    // action on `C0|C3` — Less, Equal, *or unordered* — so the three in-range arms below are that
-    // mask spelled out, and a NaN distance reads as in RANGE, not out. The is-a-player and
-    // not-attackable legs are resolved app-side and ride IN the entry
-    // ([`UnitReach::inspectable`]) — not by keeping the token out of the map, which is the map's
-    // own law (a creature `"target"` is in it, at its real distance, and is not inspectable).
-    // Decision 0631.
+    // CanInspect(unit) → 1/nil (`0x48a1b0`), the gate of `InspectFrame_Show`
+    // (`Blizzard_InspectUI.lua:8`): in range unless `100.0 < d²`, and `test ah,0x41; jne` counts an
+    // unordered compare as in range, so a NaN distance passes. The player and attackability legs
+    // ride in [`UnitReach::inspectable`].
     g.set(
         "CanInspect",
         lua.create_function(|lua, unit: Option<String>| {
@@ -190,33 +110,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                             Some(Ordering::Less | Ordering::Equal) | None
                         )
                 }
-                // No live unit object: the binary reaches its `lua_pushnil` tail through
-                // `0x4944a0`'s null-`this` guard rather than an early return, but the value it
-                // pushes is the same one — nothing to inspect.
+                // No live unit: nil, through `0x4944a0`'s null-`this` guard.
                 None => false,
             };
             Ok(if ok { Value::Integer(1) } else { Value::Nil })
         })?,
     )?;
 
-    // CheckInteractDistance(unit, type) → 1/nil, `type ∈ 1..4` (wow-re §5-VERIFIED
-    // `PRIMITIVE:check_interact_dist2` @ `0x48ba00`): **in range iff `d² < table[type-1]`** —
-    // note the STRICT `<` here against `CanInspect`'s non-strict gate above, which is the
-    // binary's own asymmetry (`test ah,0x5; jp` takes the out path unless `d² < thr` ordered), not
-    // a transcription slip. The UnitPopup rows' `dist` field indexes it.
-    //
-    // The three degenerate arms are the binary's too (`dist2-null-unit-arm.md`, VERIFIED), and
-    // they are three DIFFERENT answers rather than one permissive default:
-    //
-    // - **No live unit for the token** → `nil` (`0x48babe test ecx,ecx; je`). This is the party
-    //   member outside the local area, and answering `1` here was report B316.
-    // - **`type` numeric but outside 1..4** → `nil`. The compare is UNSIGNED on `trunc(type) − 1`
-    //   (`0x48bac5 cmp esi,0x4; jae`), so `0`, negatives and `≥ 5` all take it, and a fractional
-    //   type truncates toward zero first (`__ftol`: `1.9 → 1`, `0.5 → 0 → nil`).
-    // - **`type` missing or not a number** → a **script error**, not `nil`
-    //   (`0x48bb48 call luaL_error`, which longjmps and never returns). Same for a non-string
-    //   unit. A caller that passes neither argument is not asking a question the reference
-    //   answers.
+    // CheckInteractDistance(unit, type) → 1/nil (`0x48ba00`): in range only when
+    // `d² < table[type-1]`, strictly, unlike `CanInspect` (`test ah,0x5; jp`). A token with no unit
+    // answers nil (`0x48babe`), as does a `type` outside 1..=4 once truncated toward zero, the
+    // compare being unsigned (`0x48bac5`); a missing or non-number `type` raises (`0x48bb48`).
+    // The reference also raises for a missing unit (`0x48ba18`) or an unknown token (`0x515c14`),
+    // where this answers nil.
     g.set(
         "CheckInteractDistance",
         lua.create_function(|lua, (unit, kind): (Option<String>, Option<f64>)| {
@@ -225,8 +131,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     "Usage: CheckInteractDistance(\"unit\", distIndex)".into(),
                 ));
             };
-            // `__ftol` chops toward zero; the index is then compared UNSIGNED, so anything that
-            // is not exactly 1..=4 falls out of the table lookup and answers nil.
             let thr = usize::try_from(kind.trunc() as i64)
                 .ok()
                 .and_then(|k| k.checked_sub(1))
@@ -239,9 +143,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // NotifyInspect(unit) — the ref's request verb (`Blizzard_InspectUI.lua:9`). Queues the token;
-    // the app resolves it → guid → CMSG_INSPECT. The window does NOT wait on the reply (see the
-    // module doc), so this is fire-and-forget by design, not an unfinished handshake.
+    // NotifyInspect(unit) (`Blizzard_InspectUI.lua:9`): fire-and-forget, as nothing waits on the
+    // reply.
     g.set(
         "NotifyInspect",
         lua.create_function(|lua, unit: String| {
@@ -253,8 +156,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClearInspectPlayer() — the ref calls it from `InspectFrame_OnHide` (l.58) to drop the
-    // engine's inspected-player state. Ours stops the app's per-frame slot resolve.
+    // ClearInspectPlayer(): called from `InspectFrame_OnHide` (`Blizzard_InspectUI.lua:58`).
     g.set(
         "ClearInspectPlayer",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/instance.rs b/crates/benilla-ui/src/script/instance.rs
index bcea5d53..0b19fa1f 100644
--- a/crates/benilla-ui/src/script/instance.rs
+++ b/crates/benilla-ui/src/script/instance.rs
@@ -1,39 +1,26 @@
-//! The instance-lockout **Era API surface** (decision 1748) — three globals, no snapshot struct.
-//!
-//! `IsInInstance`, `CanShowResetInstances` and `ResetInstances` are all engine bindings in 1.12
-//! (`reference/1.12-globals.tsv` lists the three as `function`/`engine`), and between them they
-//! are the whole Lua side of the lockout family: everything else it does arrives as a
-//! `CHAT_MSG_SYSTEM` line the client composes itself, with no event and no getter.
-//!
-//! Both readers answer off state the app pushes, because both are `Map.dbc` questions and the DBC
-//! is the app's to read — the same split [`super::party::SavedInstanceInfo`] already makes.
-//!
-//! **`IsInInstance` returns a pair**: `1`/`nil` for "is this an instance at all", and the type as a
-//! string. The four strings are the reference's own table at `0x83de58`, indexed by
-//! `Map.dbc`'s `InstanceType` behind a `< 4` guard: `none` (0), `party` (1), `raid` (2),
-//! `pvp` (3) — `IsInInstance 0x48a750`.
+//! `IsInInstance`, `CanShowResetInstances` and `ResetInstances`, the whole Lua side of instance
+//! lockouts; the rest arrives as `CHAT_MSG_SYSTEM` lines. The readers answer off state the app
+//! pushes from `Map.dbc`.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// `Map.dbc`'s `InstanceType` → the word `IsInInstance()` returns for it — the reference's
-/// `0x83de58` string table, with its own out-of-range fallback (`cmp esi,4; jae` → `"none"`).
+/// `IsInInstance()`'s type word for a `Map.dbc` `InstanceType`: the reference's table at
+/// `0x83de58`, and `"none"` from 4 up.
 pub fn instance_type_name(instance_type: u32) -> &'static str {
     match instance_type {
         1 => "party",
         2 => "raid",
         3 => "pvp",
-        // 0 and anything the table cannot index.
         _ => "none",
     }
 }
 
 impl super::UiScript {
-    /// Push the current map's `Map.dbc` `InstanceType` — `IsInInstance()`'s whole input.
-    /// `None` = the map id has no DBC row, which the reference reaches by null-checking the record
-    /// pointer; it then returns without pushing anything at all (a real 1.12 stack bug). We answer
-    /// `nil, "none"` there, which is what every caller of it actually means to read.
+    /// Push the current map's `Map.dbc` `InstanceType`, `None` for a map with no row. Deviation:
+    /// `IsInInstance()` then answers `nil, "none"`, because the reference returns two results
+    /// without pushing either (`0x48a7a9`), a stack bug.
     pub fn set_instance_type(&mut self, instance_type: Option<u32>) {
         let mut model = self.model_mut();
         if model.instance_type != instance_type {
@@ -41,8 +28,8 @@ impl super::UiScript {
         }
     }
 
-    /// Push `CanShowResetInstances()`'s answer — the app owns every term of it (the ownership
-    /// latch, the last dungeon, its age, and the map we are standing on).
+    /// Push `CanShowResetInstances()`'s answer; the app owns its terms (the ownership latch, the
+    /// last dungeon, its age and the current map).
     pub fn set_can_reset_instances(&mut self, can: bool) {
         let mut model = self.model_mut();
         if model.can_reset_instances != can {
@@ -50,21 +37,17 @@ impl super::UiScript {
         }
     }
 
-    /// Drain the `ResetInstances()` calls queued since the last drain — each one is a
-    /// `CMSG_RESET_INSTANCES`. A count, like [`super::UiScript::take_binder_confirms`]: the intent
-    /// has no payload of its own.
+    /// `ResetInstances()` calls since the last drain, each a `CMSG_RESET_INSTANCES`.
     pub fn take_reset_instance_asks(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().reset_instance_asks)
     }
 }
 
-/// Register the three lockout globals ([`super::binder`]'s style).
+/// Register the three lockout globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // IsInInstance() → inInstance, instanceType. The first return is the NUMBER 1 rather than a
-    // boolean because the reference pushes 1.0 (`push 0x3ff00000; push 0` = the double 1.0), and
-    // 1.12 UI code compares it numerically.
+    // `IsInInstance()` (`0x48a750`): 1 if `InstanceType` is nonzero, else nil; then the type word.
     g.set(
         "IsInInstance",
         lua.create_function(|lua, ()| {
@@ -84,8 +67,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CanShowResetInstances() — UnitPopup's gate on the SELF menu's "Reset all instances" row.
-    // 1.0/nil for the same reason as above.
+    // `CanShowResetInstances()`: 1 or nil, the gate on the SELF menu's reset row.
     g.set(
         "CanShowResetInstances",
         lua.create_function(|lua, ()| {
@@ -98,7 +80,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ResetInstances() — the CONFIRM_RESET_INSTANCES dialog's Yes.
+    // `ResetInstances()`: the `CONFIRM_RESET_INSTANCES` dialog's Yes.
     g.set(
         "ResetInstances",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/item_stats.rs b/crates/benilla-ui/src/script/item_stats.rs
index e6fa65e2..cbd3bc73 100644
--- a/crates/benilla-ui/src/script/item_stats.rs
+++ b/crates/benilla-ui/src/script/item_stats.rs
@@ -1,21 +1,9 @@
-//! The **shared item-template store** — one `item id → ItemTemplateView` table every item hover
-//! renders through (decision 0274 P1). In the real client every item tooltip is the same C++
-//! renderer (`0x52b650`, behind 8 of the 9 `Set*Item` bindings — wow-re
-//! `ui/scratch/tooltip-money.md`) over the same item-template cache; benilla mirrors that with
-//! one engine store the app feeds from its ask-once `ITEM_QUERY` template cache, and one engine
-//! renderer ([`super::tooltip_item`]).
+//! The shared item-template store every item tooltip renders through, as the reference's one
+//! renderer (`0x52b650`, behind 8 of the 9 `Set*Item` bindings) reads one template cache.
 //!
-//! Fill flow: the app **pushes** every item template the moment it lands in its cache
-//! ([`super::UiScript::set_item_template`]) — arrival-driven, so a first hover of an item whose
-//! name is already on screen always hits. A renderer read of an id the app never resolved
-//! additionally records the id ([`super::UiScript::take_item_stat_asks`] drains them), which
-//! makes the app send `CMSG_ITEM_QUERY` and push when the answer arrives — the real client's
-//! uncached-item early-out (cleared tooltip + query; the hover's re-enter loop repaints on
-//! arrival).
-//!
-//! The view carries the template's tooltip-relevant fields plus the strings only the app can
-//! resolve (skill/faction names from the DBC catalogs, trigger-spell display text) — the engine
-//! renders lines, it never reads DBCs.
+//! The app pushes each template as it lands; a read of an unknown id records an ask that the app
+//! turns into `CMSG_ITEM_QUERY`, the reference's uncached-item early-out. The app resolves every
+//! DBC string, as the engine reads no DBCs.
 
 use std::collections::HashMap;
 
@@ -23,176 +11,112 @@ use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// An item template's tooltip view (decision 0274 P1) — the fields the line law consumes, in
-/// wire terms (vmangos `SMSG_ITEM_QUERY_SINGLE_RESPONSE`), plus app-resolved display strings.
+/// An item template's tooltip view: the `SMSG_ITEM_QUERY_SINGLE_RESPONSE` fields the tooltip reads,
+/// plus app-resolved display strings.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ItemTemplateView {
-    /// The name line (quality-colored).
     pub name: String,
     pub quality: u32,
-    /// Item class/subclass (the slot line's right column) + the equip slot (its left).
     pub class: u32,
     pub subclass: u32,
     pub inventory_type: u32,
-    /// `GetItemInfo`'s `itemType`: what [`Self::class`] is **called** — "Weapon", "Container",
-    /// "Trade Goods" — app-resolved from `ItemClass.dbc` (byte-verified: `0x48e070` pushes
-    /// `[classRow + 4*locale + 0xc]`). `None` for a class with no row, which the reference
-    /// renders as the empty string.
+    /// `GetItemInfo`'s `itemType`, the `ItemClass.dbc` name (`0x48e070`); `None` answers `""`.
     pub item_type: Option<String>,
-    /// `GetItemInfo`'s `itemSubType`: what `(class, subclass)` is **called** — app-resolved from
-    /// `ItemSubClass.dbc`, **VerboseName first with a DisplayName fallback**
-    /// ([`benilla_formats::ItemSubClassCatalog::name`]), which is the binding's own two-step at
-    /// `0x48e311`: read `[row + 4*locale + 0x4c]` and use it unless its first byte is 0, else
-    /// `[row + 4*locale + 0x28]`.
-    ///
-    /// **This is a different spelling from the tooltip's type cell**, which reads `+0x28`
-    /// (DisplayName) only — a one-handed sword is "One-Handed Swords" here and "Sword" there.
+    /// `GetItemInfo`'s `itemSubType`, "One-Handed Swords": `ItemSubClass.dbc`'s VerboseName
+    /// (`+0x4c`), or its DisplayName (`+0x28`) when that is empty (`0x48e311`).
     pub item_sub_type: Option<String>,
-    /// What `(class, subclass)` is called on the TOOLTIP's own type cell — `ItemSubClass.dbc`'s
-    /// **DisplayName** alone (`row + 4*locale + 0x28`, column 10: the read the builder makes at
-    /// `0x52c0xx` off the `0xc0db90` row cache), which is the SINGULAR spelling: "Sword", not
-    /// [`Self::item_sub_type`]'s "One-Handed Swords". App-resolved, because the engine reads no
-    /// DBCs — and it is the same string the bag line's `CONTAINER_SLOTS` second hole takes.
-    ///
-    /// This used to be a hand-typed `(class, subclass) → &str` table in the renderer, which is
-    /// the shape decision 2080 caught one file over: a stale copy of data the catalog already
-    /// held, missing every container family outright.
+    /// The tooltip's type cell and the bag line's `CONTAINER_SLOTS` name: `ItemSubClass.dbc`'s
+    /// DisplayName alone (`+0x28`, off the `0xc0db90` row cache), the singular "Sword".
     pub sub_class_display: Option<String>,
-    /// The alternate subclass whose proficiency also permits use (ItemSubClass.dbc
-    /// prerequisite/postrequisite, app-resolved with the builder's sentinel walk: prerequisite
-    /// wins, postrequisite only when prerequisite is −1). A weapon missing its own mask bit but
-    /// holding the alternate's reds the SLOT cell instead of the type cell.
+    /// The alternate subclass whose proficiency also permits use: `ItemSubClass.dbc`'s
+    /// prerequisite, or its postrequisite when the prerequisite is -1. A weapon with only the
+    /// alternate's bit reds the slot cell, not the type cell.
     pub proficiency_alt: Option<u32>,
-    /// ItemSubClass displayFlags bit 0 (app-resolved): the type cell never prints — the
-    /// "Miscellaneous" family (rings, trinkets, shirts, consumables, recipes).
+    /// `ItemSubClass.dbc` displayFlags bit 0: the type cell never prints (rings, trinkets, …).
     pub hide_subclass: bool,
-    /// Template flags — bit `0x2` = conjured ("Conjured Item").
+    /// Template flags; `0x2` prints "Conjured Item".
     pub flags: u32,
-    /// Bonding: 1 = binds on pickup, 2 = on equip, 3 = on use, 4/5 = quest item.
+    /// 1 binds on pickup, 2 on equip, 3 on use, 4 and 5 quest item.
     pub bonding: u32,
-    /// `MaxCount` — 1 = "Unique", N > 1 = "Unique (N)", 0 = no line. **Not the stack size**; see
-    /// [`Self::stackable`].
+    /// `MaxCount`: 1 prints "Unique", N > 1 "Unique (N)"; not the stack size.
     pub max_count: u32,
-    /// `Stackable` — the biggest stack one slot can hold (1 = doesn't stack). `GetItemInfo`'s
-    /// `itemStackCount`, read from the cache record's `+0x60` at `0x48e28b` — the dword *after*
-    /// `MaxCount` at `+0x5c`. Linen Cloth is `maxcount 0, stackable 20`, so the two are not
-    /// interchangeable in either direction.
+    /// `Stackable`, `GetItemInfo`'s `itemStackCount` (`+0x60`, `0x48e28b`); `MaxCount` is `+0x5c`.
     pub stackable: u32,
-    /// Nonzero = "This Item Begins a Quest".
     pub start_quest: u32,
-    /// Container size — "N Slot Bag".
     pub container_slots: u32,
-    /// Stat mods `(type, value)` in wire order (types: 0 mana, 1 health, 3 agi, 4 str, 5 int,
-    /// 6 spi, 7 stam — the `ITEM_MOD_*` GlobalStrings family).
+    /// `(ItemModType, value)` in wire order, the `ITEM_MOD_*` lines.
     pub stats: Vec<(u32, i32)>,
-    /// Damage blocks `(min, max, school)` in wire order; school 0 physical, 1..6 =
-    /// Holy/Fire/Nature/Frost/Shadow/Arcane.
+    /// `(min, max, school)` in wire order.
     pub damages: Vec<(f32, f32, u32)>,
     pub delay_ms: u32,
     pub armor: u32,
     pub block: u32,
-    /// Holy..Arcane (armor is its own field), the "+N X Resistance" lines.
+    /// Holy to Arcane.
     pub resistances: [i32; 6],
-    /// "Durability N / N" (a template hover shows full).
     pub max_durability: u32,
-    /// "Requires Level N" — printed only for N > 1 (the real builder's `0x52d2cf` gate); red
-    /// when the player is lower.
+    /// "Requires Level N", printed only for N > 1 (`0x52d2cf`).
     pub required_level: u32,
-    /// Class/race masks; `<= 0` = everyone (no line). Red when the player's bit is absent.
+    /// Class and race masks: `<= 0` prints no line, and a line missing the player's bit is red.
     pub allowable_class: i32,
     pub allowable_race: i32,
-    /// Skill requirement: the SkillLine id + rank, with the display name app-resolved
-    /// (`SkillLine.dbc`). `required_skill_name = None` = no skill line.
+    /// `SkillLine.dbc` id, with its rank and app-resolved name; a `None` name prints no line.
     pub required_skill: u32,
     pub required_skill_rank: u32,
     pub required_skill_name: Option<String>,
-    /// Spell requirement (nonzero = "Requires <name>") — red when the spellbook doesn't know it.
     pub required_spell: u32,
     pub required_spell_name: Option<String>,
-    /// `RequiredHonorRank` — no tooltip line in 1.12, but the item-usable gate (`0x5ea930`)
-    /// compares it against the player's highest honor rank; the merchant list reds on it.
+    /// No tooltip line in 1.12; only the usable gate (`0x5ea930`) reads it.
     pub required_honor_rank: u32,
-    /// `RequiredCityRank` — usable-gate only, like the honor rank. Vanilla data ships no nonzero
-    /// value and vmangos never writes the `PVP_MEDALS` bits the client would test, so a nonzero
-    /// requirement can only fail (see [`item_usable`]).
+    /// Usable gate only; nonzero always fails, as the `PVP_MEDALS` bits it tests are never set.
     pub required_city_rank: u32,
-    /// Reputation requirement, app-resolved to "Requires <Faction> - <Standing>"; the raw
-    /// faction id + rank ride along for the red check against [`PlayerReqState::rep_ranks`].
+    /// "Requires <Faction> - <Standing>", app-resolved; the raw faction and rank drive its red.
     pub required_rep_line: Option<String>,
     pub required_rep_faction: u32,
     pub required_rep_rank: u32,
-    /// Trigger-spell lines `(trigger, spell id, display text)` in wire order: trigger 0/5 =
-    /// "Use:", 1 = "Equip:", 2 = "Chance on hit:", 6 = a taught spell (the "Already known" red
-    /// check, no green line). The text is app-resolved (the spell's name in P1; its substituted
-    /// description in P2) — green lines.
+    /// Green trigger-spell lines `(trigger, spell id, text)` in wire order: 0 and 5 "Use:",
+    /// 1 "Equip:", 2 "Chance on hit:", 6 a taught spell (no line, only the "Already known" red).
     pub spell_triggers: Vec<(u32, u32, String)>,
-    /// `LockID` — nonzero prints the red "Locked" line (the key-item sub-line joins with the
-    /// Lock.dbc resolve, the GO-locks follow-up).
     pub lock_id: u32,
-    /// "N Charge(s)" — the app-resolved count for the first spell slot that survives the real
-    /// builder's charge gate (`0x52db51`: a slot whose value is 0 or the `-1` consume-on-use
-    /// sentinel prints nothing; else `abs`). 0 = no line.
+    /// "N Charge(s)" for the first spell slot past the builder's gate (`0x52db51`: 0 and -1
+    /// print nothing, else the absolute value); 0 prints no line.
     pub charges: i32,
-    /// The yellow quoted flavor text (wrapped).
     pub description: String,
-    /// Nonzero = "<Right Click to Read>" (green).
     pub page_text: u32,
-    /// Copper — the merchant-open money row (the engine fires `OnTooltipAddMoney`), and
-    /// `ITEM_UNSELLABLE` when 0 in a sell context.
+    /// Copper: the merchant money row, or `ITEM_UNSELLABLE` when 0 in a sell context.
     pub sell_price: u32,
-    /// `itemset` — nonzero renders the SET block ([`ItemSetView`], asked once by set id).
     pub item_set: u32,
-    /// The inventory icon as a ready `Interface\Icons\…` path — app-resolved through
-    /// `ItemDisplayInfo.dbc` off the template's `display_info_id`, the same lookup the bag slots
-    /// use. `GetItemInfo`'s `itemTexture`; the reference builds the identical string at
-    /// `0x48e2dd` (`"%s%s%s"` over the icon directory, `"\\"`, and the row's icon name).
-    /// `None` on the ~26% of display rows that carry no icon.
+    /// `GetItemInfo`'s `itemTexture`, the `Interface\Icons\…` path through `ItemDisplayInfo.dbc`
+    /// (`0x48e2dd`); `None` for a display row with no icon.
     pub icon: Option<String>,
-    /// `RandomProperty` (template `+0x1b8`) — the item CAN roll a "… of the Bear" suffix. Its one
-    /// consumer is the enchant family's third arm: with no instance to read a roll from, the
-    /// tooltip prints the `<Random enchantment>` placeholder instead of any per-slot line (wow-re
-    /// §1-ENCHANT §E5). Decision 0920.
+    /// `RandomProperty` (template `+0x1b8`): the item can roll a suffix, so a template tooltip
+    /// prints `<Random enchantment>` (`0x52cc33`).
     pub random_property: u32,
 }
 
-/// The player state the red-line law compares against (decision 0274 P1): pushed by the app
-/// whenever it changes. Level and class also ride the `"player"` unit feed; this carries the
-/// pieces that don't (the class/race IDS as mask bits, and the skill ranks).
+/// The player state the tooltip's red lines and the usable gate compare against.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PlayerReqState {
     pub level: u32,
-    /// Class id (1 warrior … 11 druid) — the `allowable_class` mask bit is `1 << (id-1)`.
+    /// 1 warrior … 11 druid; the `allowable_class` bit is `1 << (id-1)`.
     pub class_id: u32,
-    /// Race id (1 human … 8 troll) — the `allowable_race` mask bit is `1 << (id-1)`.
+    /// 1 human … 8 troll; the `allowable_race` bit is `1 << (id-1)`.
     pub race_id: u32,
-    /// SkillLine id → current rank, for "Requires <skill> (N)" checks.
+    /// SkillLine id → value plus permanent bonus, what the gates compare.
     pub skills: HashMap<u32, u32>,
-    /// Item class (2 weapons / 4 armor) → allowed-subclass bitmask (`SMSG_SET_PROFICIENCY`,
-    /// the client's `0xc4d4a0[class]` store). The slot-line proficiency red: a class WITH an
-    /// entry here reds when the item's `1 << subclass` bit is absent; a class with no entry
-    /// (consumables etc.) never reds.
+    /// Item class → `SMSG_SET_PROFICIENCY` subclass mask (`0xc4d4a0[class]`); a class with no
+    /// entry never reds.
     pub proficiency: HashMap<u32, u32>,
-    /// Faction id → the player's reputation rank (0 hated … 7 exalted; DBC base + wire
-    /// standing, app-ranked) — the "Requires <Faction> - <Standing>" red check.
+    /// Faction id → reputation rank, 0 hated … 7 exalted.
     pub rep_ranks: HashMap<u32, u8>,
-    /// Whether the spellbook holds an effect-40 (SPELL_EFFECT_DUAL_WIELD) spell — the client's
-    /// `0xc4d770` global (stored on learn, cleared on unlearn; reader `0x5eab70`). An off-hand
-    /// weapon (InventoryType 22) reds its SLOT cell without it.
+    /// Whether the spellbook holds a `SPELL_EFFECT_DUAL_WIELD` (40) spell, the client's
+    /// `0xc4d770` (read at `0x5eab70`); without it an off-hand weapon reds its slot cell.
     pub can_dual_wield: bool,
-    /// The player's **highest lifetime honor rank** (`PLAYER_FIELD_BYTES` byte 3) — the
-    /// usable-gate's `RequiredHonorRank` comparand.
+    /// The highest lifetime honor rank (`PLAYER_FIELD_BYTES` byte 3).
     pub honor_rank: u8,
 }
 
-/// [`item_usable`] for an item the caller knows only by **entry** — the shape every window seam
-/// wants, since a row carries an id and the engine holds the templates.
-///
-/// Two conventions are folded in here rather than re-derived per caller: entry `0` (a row with no
-/// item at all) is usable, and a template the app has not answered for yet is usable, which is the
-/// getter's own null-record skip. It was four identical private copies across the merchant, mail,
-/// trade and auction seams before it was one — three had the `item_id == 0` leg and the fourth
-/// reached the same answer through `is_none_or`, which is exactly the kind of agreement that stops
-/// being reliable the moment someone edits one of them.
+/// [`item_usable`] by item entry: entry 0 and a template not yet answered are usable, as the
+/// merchant getter skips an uncached record (`0x4fb298`).
 pub(super) fn item_usable_by_id(model: &super::Model, item_id: u32) -> bool {
     item_id == 0
         || model.item_templates.get(&item_id).is_none_or(|v| {
@@ -201,31 +125,12 @@ pub(super) fn item_usable_by_id(model: &super::Model, item_id: u32) -> bool {
             })
         })
 }
-/// The client's item-usable predicate `0x5ea930(player; itemCacheRecord, &err)` — byte-read from
-/// wow-re's `ui/scratch/disasm-full.txt`. Both merchant getters call it (`GetMerchantItemInfo`
-/// `0x4fb2a3`, `GetBuybackItemInfo` `0x4fb4f7`) and push `1`/`nil` as `isUsable`; the FrameXML
-/// reds the row on `nil`. The legs, in the binary's order:
-///
-/// 1. `requiredLevel > player level` → unusable.
-/// 2. class mask: `allowableClass & 1<<(classId−1)` clear → unusable (−1 = every bit set).
-/// 3. race mask: same test against `allowableRace`.
-/// 4. proficiency: a mask exists for the item class AND the item's **own** subclass bit is clear
-///    → unusable. NO ItemSubClass alternate walk here — the alternate only chooses which tooltip
-///    CELL reds (0297); the usable gate is the raw bit.
-/// 5. `requiredSkill`: unknown skill → unusable; known → `value + permBonus ≥ requiredSkillRank`.
-/// 6. `requiredSpell`: not in the spellbook → unusable.
-/// 7. `requiredHonorRank`: player's highest honor rank (`PLAYER_FIELD_BYTES` byte 3) short →
-///    unusable.
-/// 8. `requiredCityRank`: tests `PLAYER_FIELD_PVP_MEDALS & 1<<(rank−1)` — vanilla never writes
-///    the medals field and ships no city-rank items, so a nonzero requirement always fails;
-///    mirrored as the constant result rather than plumbing a dead field.
-/// 9. reputation: player standing ≥ the required rank's threshold (`0x4d6370` +
-///    the `0x80928c` threshold table) — equivalently rank ≥ requiredRepRank, the tooltip red's
-///    exact compare; an unknown faction counts as rank 0.
-///
-/// A template the cache hasn't answered yet is USABLE (the getter skips the call on a null
-/// record — `0x4fb298`); the engine analog is an unpushed [`PlayerReqState`] (level 0, a state
-/// the real client can't reach), which also declines to judge.
+/// The client's item-usable predicate `0x5ea930`, whose answer the merchant getters push as
+/// `isUsable` (`0x4fb2a3`, `0x4fb4f7`), its legs in the reference's order. Proficiency tests the
+/// item's own subclass bit, with no alternate walk. A nonzero city rank always fails: it tests
+/// `PLAYER_FIELD_PVP_MEDALS`, which is never written. Reputation compares ranks, equivalent to the
+/// reference's standing threshold (`0x4d6370`, table `0x80928c`); an unknown faction is rank 0. An
+/// unpushed state (level 0) declines to judge, answering usable.
 pub fn item_usable(
     v: &ItemTemplateView,
     req: &PlayerReqState,
@@ -280,39 +185,32 @@ pub fn item_usable(
     true
 }
 
-/// An item set's tooltip view (the §22 SET block), app-resolved: the ItemSet.dbc row with
-/// member item NAMES joined from the template cache (a `None` name = the member's template is
-/// still in flight — its line waits; the app re-pushes as answers land) and the threshold
-/// bonuses' TEXT ($-substituted spell descriptions). The engine supplies the live half: the
-/// owned/equipped counts off its own inventory slots.
+/// An item set's tooltip block (`0x854b1c`), app-resolved from `ItemSet.dbc`: member names from
+/// the template cache and the bonuses' substituted text. The engine counts the equipped members.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ItemSetView {
     pub name: String,
-    /// `(item id, resolved name)` per member, DBC order.
+    /// `(item id, name)` per member in DBC order; `None` while its template is uncached.
     pub members: Vec<(u32, Option<String>)>,
-    /// `(required equipped count, bonus text)` per bonus, in the DBC's stored slot order —
-    /// the renderer sorts threshold-ascending at print time, like the builder's qsort
-    /// (`0x52e5c0`; The Gladiator ships 3,2,5,4 and prints 2,3,4,5).
+    /// `(required equipped count, bonus text)` in DBC slot order; the renderer sorts by count, as
+    /// the builder's qsort does (`0x52e5c0`).
     pub bonuses: Vec<(u32, String)>,
-    /// The set-level skill requirement ("Requires <skill> (N)"), app-named; 0/None = no line.
+    /// The set's "Requires <skill> (N)"; 0 prints no line.
     pub required_skill: u32,
     pub required_skill_rank: u32,
     pub required_skill_name: Option<String>,
 }
 
 impl super::UiScript {
-    /// Store (or replace) an item's template view — the app's push half of the ask-once flow.
+    /// Stores or replaces an item's template view, clearing its ask.
     pub fn set_item_template(&mut self, item_id: u32, view: ItemTemplateView) {
         let mut model = self.model_mut();
         model.item_stat_asks.remove(&item_id);
         model.item_templates.insert(item_id, view);
     }
 
-    /// Drain the ids the renderer asked for that the store didn't have.
-    /// Ask the app for the templates of `ids` the store does not hold yet — the trade-skill and
-    /// craft feeds' pre-ask (1973): the client has every product's and reagent's template cached
-    /// by the time its list shows, and the link verbs never query, so the feeds ask on the app's
-    /// behalf when the list lands and the verbs read the answers.
+    /// Asks for the templates of `ids` the store lacks, for the trade-skill and craft lists,
+    /// whose link verbs never query: the reference has them cached before the list shows.
     pub fn ask_item_templates(&mut self, ids: impl IntoIterator<Item = u32>) {
         let mut model = self.model_mut();
         for id in ids {
@@ -322,26 +220,25 @@ impl super::UiScript {
         }
     }
 
+    /// Drains the ids read or asked for that the store did not hold.
     pub fn take_item_stat_asks(&mut self) -> Vec<u32> {
         self.model_mut().item_stat_asks.drain().collect()
     }
 
-    /// Store (or replace) a set's view — the SET block's push half (re-pushed as member names
-    /// resolve).
+    /// Stores or replaces a set's view, re-pushed as member names resolve.
     pub fn set_item_set(&mut self, set_id: u32, view: ItemSetView) {
         let mut model = self.model_mut();
         model.item_set_asks.remove(&set_id);
         model.item_sets.insert(set_id, view);
     }
 
-    /// Drain the set ids the renderer asked for that the store didn't have.
+    /// Drains the set ids the renderer asked for that the store did not hold.
     pub fn take_item_set_asks(&mut self) -> Vec<u32> {
         self.model_mut().item_set_asks.drain().collect()
     }
 
-    /// Push the **whole** random-suffix table (`ItemRandomProperties` id → its resolved view) —
-    /// once, at load. Not an ask-once store: see [`super::Model::random_properties`] for why the
-    /// roll table is pushed whole where the template store is asked for.
+    /// Pushes the whole `ItemRandomProperties` table once, at load: a clicked tooltip cannot
+    /// repaint on a late answer.
     pub fn set_random_properties(
         &mut self,
         rows: std::collections::HashMap<u32, super::RandomPropertyView>,
@@ -349,21 +246,15 @@ impl super::UiScript {
         self.model_mut().random_properties = rows;
     }
 
-    /// Push the red-line law's player state (level/class/race/skills). Cheap to call on change.
+    /// Pushes the player state the red lines compare against.
     pub fn set_player_req_state(&mut self, state: PlayerReqState) {
         self.model_mut().player_req = state;
     }
 }
 
-/// Register the shared item-stats global (the P0 Lua stat-head read — still the merchant
-/// sell-cursor's source and the compat surface while call sites finish moving to the engine
-/// renderer; the tooltip itself no longer routes through it).
-/// The 1.12 item-quality palette, **byte-verified** — wow-5875-re RF-0055
-/// (`scratch/rf55-quality-color-table.md`): the seven ARGB literals the static init `0x5291d0`
-/// writes into the BGRA array at `0xc0d3c8`, and the parallel escape strings at `0x854124`.
-///
-/// `Script::GetItemQualityColor 0x48dfb0` reads `[quality*4 + 0xc0d3c8]`, takes `[+2]=R`,
-/// `[+1]=G`, `[+0]=B`, multiplies each by `1/255`, and returns them with the escape string.
+/// The 1.12 item-quality palette: the ARGB literals the static init `0x5291d0` writes to the BGRA
+/// array `0xc0d3c8`, and the escape strings at `0x854124`. `GetItemQualityColor` (`0x48dfb0`)
+/// answers each channel times 1/255.
 const QUALITY_COLORS: [(u8, u8, u8, &str); 7] = [
     (0x9d, 0x9d, 0x9d, "|cff9d9d9d"), // 0 Poor
     (0xff, 0xff, 0xff, "|cffffffff"), // 1 Common
@@ -374,11 +265,9 @@ const QUALITY_COLORS: [(u8, u8, u8, &str); 7] = [
     (0xe6, 0xcc, 0x80, "|cffe6cc80"), // 6 Artifact
 ];
 
-/// The client's item-link builder `0x52adb0` as the trade-skill and craft link verbs call it
-/// (wow-re `tradeskill/scratch/tradeskill-craft-item-links.md`, 1973): `|c<rrggbb>|Hitem:<id>:0:0:0|h[<name>]|h|r`
-/// — the three tokens literal zeros at those call sites, the colour from `0x52ad90`'s table where
-/// `cmp ecx,7; jb` is UNSIGNED, so a quality of 7 or more, or a negative one, selects index 1
-/// (white): a fixed fallback, not a clamp. The `""`-suffix arm is dead, so every link ends `|h|r`.
+/// The client's item-link builder `0x52adb0` as the trade-skill and craft link verbs call it:
+/// `|c<rrggbb>|Hitem:<id>:0:0:0|h[<name>]|h|r`. A quality of 7 or more selects index 1, white,
+/// by `0x52ad90`'s unsigned `cmp ecx,7; jb`.
 pub(super) fn item_link(item_id: u32, name: &str, quality: u32) -> String {
     let hex = QUALITY_COLORS
         .get(quality as usize)
@@ -387,21 +276,9 @@ pub(super) fn item_link(item_id: u32, name: &str, quality: u32) -> String {
     format!("{hex}|Hitem:{item_id}:0:0:0|h[{name}]|h|r")
 }
 
-/// `InventoryType` → the `INVTYPE_*` token `GetItemInfo` returns as `itemEquipLoc`.
-///
-/// **The reference's own table, read out of the binary**: `0x48e29b` does
-/// `mov eax,[record+0x2c]` (the inventory type) then `mov edx,[eax*4 + 0x83ddb0]` and pushes the
-/// string — an unguarded index into a 30-pointer array at `0x83ddb0`. Its entries, decoded from
-/// the PE image, are exactly the 28 tokens below at 1..=28, with index **0 and 29 both pointing at
-/// the shared empty string `0x882748`**. So a non-equippable item answers `""`, not nil: an addon
-/// doing `getglobal(itemEquipLoc)` gets nil either way, but one doing `itemEquipLoc == ""` — or
-/// concatenating it — sees what the real client shows.
-///
-/// The spellings are the client's, and four of them (`AMMO`, `THROWN`, `RANGEDRIGHT`, `QUIVER`)
-/// have **no matching GlobalString** in the shipped 1.12 `GlobalStrings.lua`, which defines only
-/// 24 `INVTYPE_*` entries. That asymmetry is the reference's, not ours: the binding hands back a
-/// token the FrameXML cannot localize. Note also `SHOULDER`/`WRIST`/`HAND` are singular here where
-/// our numeric equip-slot map's comments say `SHOULDERS`/`WRISTS`/`HANDS`.
+/// `InventoryType` → `GetItemInfo`'s `itemEquipLoc`, the reference's 30-pointer table at
+/// `0x83ddb0` (`0x48e29b`): slots 0 and 29 are the shared `""` (`0x882748`), not nil, and four
+/// tokens (`AMMO`, `THROWN`, `RANGEDRIGHT`, `QUIVER`) have no `GlobalStrings.lua` entry.
 fn equip_loc_token(inventory_type: u32) -> &'static str {
     const TOKENS: [&str; 29] = [
         "",
@@ -434,15 +311,13 @@ fn equip_loc_token(inventory_type: u32) -> &'static str {
         "INVTYPE_QUIVER",
         "INVTYPE_RELIC",
     ];
-    // The reference does not bounds-check (the value always comes off its own cache record); we
-    // do, because a Lua-reachable path must not depend on that. 29 is the array's own trailing "".
+    // Deviation: bounds-checked where the reference indexes unguarded, so none reads past it.
     TOKENS.get(inventory_type as usize).copied().unwrap_or("")
 }
 
-/// The reference's `atoi` (`0x64ac60`), which is what parses each field of an `item:` string:
-/// an optional leading `-`, then decimal digits, stopping at the first byte that is not one.
-/// **No leading-whitespace skip, no `+`, no `0x`** — and no overflow check either, but a saturating
-/// accumulate is the sane read of a value that can only come from a script.
+/// The reference's `SStrToInt` (`0x64ac60`) over an `item:` field: an optional `-`, then digits up
+/// to the first non-digit, with no whitespace skip and no `+`. Deviation: an overflow saturates at
+/// `u32::MAX` where the reference wraps, because only a script can overflow it.
 fn reference_atoi(s: &str) -> i64 {
     let b = s.as_bytes();
     let (neg, mut i) = match b.first() {
@@ -467,25 +342,11 @@ fn reference_atoi(s: &str) -> i64 {
     }
 }
 
-/// `GetItemInfo`'s argument, resolved to the four `item:` fields — **the reference's parser**
-/// (`0x48e0a3`-`0x48e16d`), which is narrower than every later client's and narrower than the
-/// binding's own usage string suggests:
-///
-/// 1. `lua_isnumber` (`0x6f34d0` — LUA_TNUMBER **or a string Lua coerces to one**) → truncate to
-///    an int and that is the whole answer; enchant/random-property/suffix stay 0. This is the arm
-///    `GetItemInfo(2589)` and `GetItemInfo(tostring(id))` both take.
-/// 2. else `lua_isstring` (`0x6f3510`) → `strnicmp(s, "item:", 5)` (`0x64a4c0` → `0x414310`). On a
-///    match, `atoi` the four colon-separated fields; **on a miss the id stays 0** and the caller
-///    returns nothing.
-/// 3. else raise `Usage: GetItemInfo(itemID|"itemlink")` — the literal at `0x842d24`, pushed
-///    through `0x6f4940` (`luaL_where` + `lua_pushvfstring` + concat + `lua_error`: it raises).
-///
-/// **So a bare item NAME and a full `|cff…|Hitem:…|h[Name]|h|r` hyperlink both resolve to nothing**
-/// on the real 1.12 client — neither begins with `item:`. The "itemlink" the usage string means is
-/// the *item string*, which is also what the binding returns as its second value. Auctioneer builds
-/// exactly that (`AucItemDB.lua:333`: `string.format("item:%s:%s:%s:0", …)`) before calling this.
+/// `GetItemInfo`'s argument as the reference parses it (`0x48e0a3`-`0x48e16d`): a number, or a
+/// string `lua_isnumber` (`0x6f34d0`) coerces, is the id alone; another string (`0x6f3510`) must
+/// pass `strnicmp(s, "item:", 5)` (`0x64a4c0`) for its four fields, else it is id 0, so a name or
+/// a hyperlink finds nothing; anything else raises the usage error (`0x842d24`, via `0x6f4940`).
 fn parse_item_arg(v: &Value) -> mlua::Result<(i64, u32, u32, u32)> {
-    // Arm 1 — a number, or a string Lua's own coercion reads as one.
     let as_number = match v {
         Value::Integer(i) => Some(*i as f64),
         Value::Number(n) => Some(*n),
@@ -495,7 +356,7 @@ fn parse_item_arg(v: &Value) -> mlua::Result<(i64, u32, u32, u32)> {
     if let Some(n) = as_number {
         return Ok((n as i64, 0, 0, 0));
     }
-    // Arm 2 — a string. Anything that is not `item:`-prefixed leaves the id at 0.
+    // An `item:` string; any other string is id 0.
     let Value::String(s) = v else {
         return Err(mlua::Error::RuntimeError(
             "Usage: GetItemInfo(itemID|\"itemlink\")".into(),
@@ -518,33 +379,13 @@ fn parse_item_arg(v: &Value) -> mlua::Result<(i64, u32, u32, u32)> {
 }
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // `GetItemQualityColor(quality)` → `r, g, b, escapeString` (decision 1199).
-    //
-    // A **C-registered** binding in the reference (`0x48dfb0`) and `function engine` in the
-    // captured `_G`, which is why it belongs here rather than in `assets/ui`: the shipped
-    // `UIParent.lua` *builds* `ITEM_QUALITY_COLORS` by calling it in a loop (`for i = -1, 6`), so
-    // the table is FrameXML's and the verb underneath is the engine's. 23 corpus addons call it,
-    // and three of our own XML files carry a private copy of the palette this replaces.
-    //
-    // **The clamp is the reference's, not a guess** — and it is ONE clamp, not two, because the
-    // comparison is UNSIGNED. `0x52ad70`/`0x52ad90` both do `cmp ecx,7` / `jb`, so anything at or
-    // above 7 selects index **1** (Common) — not 6, not an error — and a NEGATIVE quality takes the
-    // same branch, because as a `u32` it is at or above 7 too. `GetItemQualityColor(-1)` is
-    // therefore **white**, and so is `ITEM_QUALITY_COLORS[-1]`, the row `UIParent.lua`'s
-    // `for i = -1, 6` builds.
-    //
-    // This corrects 1199, which called the negative arm "the one place this binding is deliberately
-    // not bit-faithful … because the faithful answer is an out-of-bounds read" and answered Poor
-    // (grey). There is no out-of-bounds read: the unsigned compare catches it first. The value
-    // stopped being academic when the loot window went to the chain — `-1` is what
-    // `GetLootSlotInfo` answers for a row whose item template is not cached, and that row's text
-    // colour is this table's `-1` row (wow-re `system/ui/scratch/loot-slot-record.md` §10,
-    // decision 1805).
+    // GetItemQualityColor(quality) → r, g, b, escapeString (`0x48dfb0`). 7 and up, or a negative
+    // quality, answer Common (`0x52ad70`/`0x52ad90`: an unsigned `cmp ecx,7; jb`), so
+    // `ITEM_QUALITY_COLORS[-1]` is white, the colour of an uncached loot row (`0x4c2435`).
     lua.globals().set(
         "GetItemQualityColor",
         lua.create_function(|lua, quality: i64| {
-            // The reference reads its argument as a 32-bit int (`ftol`) and then compares it
-            // unsigned, which is exactly this pair of casts.
+            // A 32-bit int (`__ftol`), compared unsigned.
             let i = match quality as i32 as u32 {
                 q if q >= 7 => 1,
                 q => q as usize,
@@ -559,49 +400,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetItemInfo(itemID | "item:id:enchant:randomProperty:suffix")` →
-    //   itemName, itemLink, itemQuality, itemMinLevel, itemType, itemSubType,
-    //   itemStackCount, itemEquipLoc, itemTexture
-    //
-    // **Nine values, and every one of them byte-verified** against the registered binding
-    // `0x48e070` (wow-5875-re `system/ui/ledger.tsv:891`), which ends `mov eax,0x9; ret`. The
-    // signature is the whole point of the verb (decision 1199): a later client inserts `itemLevel`
-    // at position 4 and pushes the required level to 5, and 36 corpus addons destructure this one
-    // positionally — `Informant/Informant.lua:268` reads all nine and stores position 4 as
-    // `['reqLevel']`, `Auctioneer/Database/AucItemDB.lua:288` as `useLevel`.
-    //
-    // Per value, with the instruction that pushes it:
-    //
-    //  1 `itemName`    `0x5d8b00(buf, 0x400, itemId, randomProperty)` — the template name with the
-    //                  `ItemRandomProperties.dbc` suffix appended. **We push the bare template
-    //                  name**: the suffix table is the same stated gap `ui_items::item_link`
-    //                  already carries, one random-suffix arc, not per-call-site drift.
-    //  2 `itemLink`    `0x48e1c9`: `SStrPrintf(buf, 0x400, "item:%d:%d:%d:%d", id, enchant,
-    //                  randomProperty, suffix)` — the literal at `0x842d4c`. In 1.12 this is the
-    //                  **item string**, NOT the coloured `|cff…|Hitem:…|h[Name]|h|r` hyperlink
-    //                  (that is `GetContainerItemLink`'s shape and stays there). Auctioneer's
-    //                  `getItemInfoFromBlizzard` names the return `itemString` and feeds it
-    //                  straight back in, which only works because both ends are this shape.
-    //  3 `itemQuality` `fild [record+0x1c]` — the same dword wow-re pinned through this function
-    //                  for the drag payload (`scratch/cursor-dragdrop-payload.md:223`).
-    //  4 `itemMinLevel` `fild [record+0x3c]` — the **required** level. `ItemLevel` lives one dword
-    //                  earlier at `+0x38` and is never pushed here. This is the trap.
-    //  5 `itemType`    ItemClass.dbc's localized class name, or `""` (`0x48e236`).
-    //  6 `itemSubType` ItemSubClass.dbc, VerboseName then DisplayName (`0x48e311`), or `""`.
-    //  7 `itemStackCount` `fild [record+0x60]` — `Stackable`, not `MaxCount` (`+0x5c`).
-    //  8 `itemEquipLoc` `[invType*4 + 0x83ddb0]` — the `INVTYPE_*` token; `""` at index 0.
-    //  9 `itemTexture` `"%s%s%s"` over the icon dir, `"\\"` and the ItemDisplayInfo icon name.
-    //
-    // **A template the store has not seen yet returns nothing and records the ask**, exactly like
-    // `BenillaGetItemStats` — and exactly like the reference, whose cache lookup `0x55ba30` fires
-    // the query and returns null, taking the binding straight to `xor eax,eax; ret` (0 values).
-    // The first call comes back empty and the answer arrives later; we never block or fabricate.
+    // GetItemInfo(itemID | "item:id:enchant:randomProperty:suffix") → itemName, itemLink,
+    // itemQuality, itemMinLevel, itemType, itemSubType, itemStackCount, itemEquipLoc, itemTexture:
+    // nine values (`0x48e070` ends `mov eax,0x9`); later clients insert `itemLevel` at 4. The name
+    // is the bare template name, where the reference appends the random suffix (`0x5d8b00`); the
+    // link is the item string (`0x48e1c9`, literal `0x842d4c`), not a hyperlink; the level is the
+    // required one (`[record+0x3c]`; `ItemLevel` at `+0x38` is never pushed). An uncached
+    // template answers no values and records the ask, as the reference's lookup (`0x55ba30`)
+    // queries and returns null, sending the binding to `xor eax,eax; ret`.
     lua.globals().set(
         "GetItemInfo",
         lua.create_function(|lua, arg: Value| {
             let (id, enchant, random_property, suffix) = parse_item_arg(&arg)?;
             let Ok(item_id) = u32::try_from(id) else {
-                return Ok(MultiValue::new()); // negative / past u32: no record can hold it
+                return Ok(MultiValue::new()); // no record holds a negative or past-u32 id
             };
             let view = {
                 let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -626,9 +438,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::String(lua.create_string(str_or_empty(&v.item_sub_type))?),
                 Value::Integer(i64::from(v.stackable)),
                 Value::String(lua.create_string(equip_loc_token(v.inventory_type))?),
-                // The one value that can be genuinely absent rather than empty: a display row
-                // with no icon column. `nil` rather than the reference's `Interface\Icons\`,
-                // which is a path that cannot load — both read as "no icon" to `SetTexture`.
+                // Deviation: nil for a display row with no icon, where the reference answers the
+                // unloadable `Interface\Icons\`, because `SetTexture` shows no icon for either.
                 match &v.icon {
                     Some(icon) => Value::String(lua.create_string(icon)?),
                     None => Value::Nil,
@@ -638,7 +449,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // BenillaGetItemStats(itemId) → name, quality, invType, class, subclass, dmgMin, dmgMax,
-    // dmgType, delayMs, armor, block, sellPrice — or nil (recording the ask).
+    // dmgType, delayMs, armor, block, sellPrice, or nil and an ask.
     lua.globals().set(
         "BenillaGetItemStats",
         lua.create_function(|lua, item_id: u32| {
@@ -677,7 +488,6 @@ mod tests {
     use super::{item_usable, ItemTemplateView, PlayerReqState};
     use crate::script::UiScript;
 
-    /// Every leg of the `0x5ea930` gate, one at a time against a passing baseline.
     #[test]
     fn item_usable_mirrors_the_gate_legs() {
         let base_item = ItemTemplateView {
@@ -694,7 +504,7 @@ mod tests {
         let knows_none = |_: u32| false;
         assert!(item_usable(&base_item, &base_req, knows_none));
 
-        // 1 · level: required 5 vs level 4 fails; exactly 5 passes (jg, not jge).
+        // Level 5 required: level 4 fails, 5 passes (`jg`).
         let mut v = base_item.clone();
         v.required_level = 5;
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -702,7 +512,6 @@ mod tests {
         req.level = 5;
         assert!(item_usable(&v, &req, knows_none));
 
-        // 2/3 · class + race masks: the player's bit must be set; −1 has every bit.
         let mut v = base_item.clone();
         v.allowable_class = 1 << 3; // rogue-only (class 4)
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -710,8 +519,7 @@ mod tests {
         v.allowable_race = 1 << 0; // human-only
         assert!(!item_usable(&v, &base_req, knows_none));
 
-        // 4 · proficiency: a mask for the item class with the subclass bit clear fails — and
-        // there is NO alternate walk here (a 2H axe reds even when the 1H bit is set).
+        // No alternate walk: a 2H axe fails with only the 1H bit set.
         let mut v = base_item.clone();
         (v.class, v.subclass) = (2, 1); // Two-Handed Axe
         let mut req = base_req.clone();
@@ -719,12 +527,12 @@ mod tests {
         assert!(!item_usable(&v, &req, knows_none));
         req.proficiency.insert(2, 1 << 1);
         assert!(item_usable(&v, &req, knows_none));
-        // No mask for the class at all (consumables): the leg never fires.
+        // No mask for the class: the leg never fires.
         let mut v = base_item.clone();
         (v.class, v.subclass) = (0, 0);
         assert!(item_usable(&v, &base_req, knows_none));
 
-        // 5 · skill: unknown skill fails even at rank 0; known compares value ≥ rank.
+        // An unknown skill fails even at rank 0.
         let mut v = base_item.clone();
         v.required_skill = 164; // Blacksmithing
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -736,13 +544,11 @@ mod tests {
         req.skills.insert(164, 100);
         assert!(item_usable(&v, &req, knows_none));
 
-        // 6 · spell: required and not in the spellbook fails.
         let mut v = base_item.clone();
         v.required_spell = 9787; // Weaponsmith
         assert!(!item_usable(&v, &base_req, knows_none));
         assert!(item_usable(&v, &base_req, |id| id == 9787));
 
-        // 7 · honor rank: the player's highest rank must reach it.
         let mut v = base_item.clone();
         v.required_honor_rank = 3;
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -750,14 +556,11 @@ mod tests {
         req.honor_rank = 3;
         assert!(item_usable(&v, &req, knows_none));
 
-        // 8 · city rank: no live data ever sets it, and the medals field it tests is never
-        // written — a nonzero requirement can only fail.
         let mut v = base_item.clone();
         v.required_city_rank = 1;
         assert!(!item_usable(&v, &base_req, knows_none));
 
-        // 9 · reputation: rank below the requirement fails; at it, passes; an unknown faction
-        // is rank 0 (fails any nonzero requirement, passes a zero one).
+        // An unknown faction is rank 0.
         let mut v = base_item.clone();
         (v.required_rep_faction, v.required_rep_rank) = (87, 5);
         assert!(!item_usable(&v, &base_req, knows_none));
@@ -768,14 +571,12 @@ mod tests {
         (v.required_rep_faction, v.required_rep_rank) = (87, 0);
         assert!(item_usable(&v, &base_req, knows_none));
 
-        // An unpushed player state (level 0 — unreachable in the real client) declines to judge.
+        // An unpushed state (level 0) declines to judge.
         let mut v = base_item.clone();
         v.required_level = 60;
         assert!(item_usable(&v, &PlayerReqState::default(), knows_none));
     }
 
-    /// The ask-once loop end-to-end: a miss answers nil AND records the ask; the app's push makes
-    /// the next read answer the stat head; the push clears the pending ask.
     #[test]
     fn miss_records_ask_and_push_serves_the_stats() {
         let mut s = UiScript::new().unwrap();
@@ -801,7 +602,7 @@ mod tests {
             s.eval("return BenillaGetItemStats(25)").unwrap();
         assert_eq!((name.as_str(), quality, inv), ("Worn Shortsword", 1, 21));
         assert!(s.take_item_stat_asks().is_empty(), "push cleared the ask");
-        // id 0 (an unresolved row) never records a junk ask.
+        // Id 0 records no ask.
         assert!(s
             .eval::<bool>("return BenillaGetItemStats(0) == nil")
             .unwrap());
@@ -814,11 +615,7 @@ mod get_item_info_tests {
     use super::{equip_loc_token, reference_atoi, ItemTemplateView};
     use crate::script::UiScript;
 
-    /// **Worn Shortsword (25)**, with every field taken from the live vmangos `item_template`
-    /// row so the assertions below are about real data:
-    /// `class 2, subclass 7, quality 1, inventory_type 21, required_level 1, item_level 2,
-    /// max_count 0, stackable 1`. The two app-resolved names are what the shipped
-    /// `ItemClass.dbc` / `ItemSubClass.dbc` rows hold for `(2, 7)`.
+    /// Worn Shortsword, item 25, as vmangos `item_template` holds it (item level 2).
     fn worn_shortsword() -> ItemTemplateView {
         ItemTemplateView {
             name: "Worn Shortsword".into(),
@@ -827,10 +624,9 @@ mod get_item_info_tests {
             subclass: 7,
             inventory_type: 21,
             item_type: Some("Weapon".into()),
-            // VerboseName, not the tooltip cell's "Sword" — the binding's `0x48e311` two-step.
+            // VerboseName, not the tooltip cell's "Sword" (`0x48e311`).
             item_sub_type: Some("One-Handed Swords".into()),
-            // The pair that makes position 4 falsifiable: this item's REQUIRED level is 1 and its
-            // ITEM level is 2. Ashbringer (13262) is the loud version — required 60, item 76.
+            // Required level 1 against item level 2 makes position 4 falsifiable.
             required_level: 1,
             stackable: 1,
             max_count: 0,
@@ -839,12 +635,7 @@ mod get_item_info_tests {
         }
     }
 
-    /// The whole signature, destructured in order exactly as `Informant/Informant.lua:268` and
-    /// `Auctioneer/Database/AucItemDB.lua:288` destructure it.
-    ///
-    /// **The arity assertion is half the test.** A regression to a later client's shape inserts
-    /// `itemLevel` at position 4 and makes this ten values; the COUNT is the only check that
-    /// notices, because every individual read still "works".
+    /// The arity catches a later client's shape, which inserts `itemLevel` at position 4.
     #[test]
     fn get_item_info_returns_the_1_12_nine_value_shape() {
         let mut s = UiScript::new().unwrap();
@@ -870,8 +661,7 @@ mod get_item_info_tests {
             .eval("local a,b,c,d,e,f,g,h,i = GetItemInfo(25) return a,b,c,d,e,f,g,h,i")
             .unwrap();
         assert_eq!(name, "Worn Shortsword");
-        // Return 2 is the ITEM STRING, not the coloured hyperlink (`"item:%d:%d:%d:%d"` at
-        // 0x842d4c). A number argument leaves the other three fields at 0.
+        // The item string (`0x842d4c`); a number argument leaves the other fields 0.
         assert_eq!(link, "item:25:0:0:0");
         assert_eq!(quality, 1);
         assert_eq!(min_level, 1);
@@ -882,11 +672,7 @@ mod get_item_info_tests {
         assert_eq!(texture.as_deref(), Some("Interface\\Icons\\INV_Sword_04"));
     }
 
-    /// **Position 4 is the REQUIRED level, and position 5 is a string.** This is the whole reason
-    /// decision 1199 exists, one verb later: every client after 1.12 inserts `itemLevel` at 4 and
-    /// pushes `itemMinLevel` to 5, so a regression makes position 5 a *number*. Both halves are
-    /// asserted, against a template whose two levels genuinely differ (Ashbringer: required 60,
-    /// item level 76 — verified in the live vmangos `item_template`).
+    /// Ashbringer, item 13262: required level 60, item level 76 in vmangos `item_template`.
     #[test]
     fn position_four_is_the_required_level_not_the_item_level() {
         let mut s = UiScript::new().unwrap();
@@ -900,7 +686,7 @@ mod get_item_info_tests {
                 inventory_type: 17,
                 item_type: Some("Weapon".into()),
                 item_sub_type: Some("Two-Handed Swords".into()),
-                required_level: 60, // item_level is 76 and is NEVER returned by 1.12
+                required_level: 60, // item level 76 is never returned
                 max_count: 1,
                 stackable: 1,
                 ..Default::default()
@@ -927,10 +713,7 @@ mod get_item_info_tests {
         );
     }
 
-    /// **Position 7 is `Stackable`, not `MaxCount`** — `[record+0x60]`, the dword *after*
-    /// `MaxCount` at `+0x5c`. The view carries both and they are not interchangeable: Linen Cloth
-    /// is `max_count 0, stackable 20` in the live `item_template`, so reading the wrong one gives
-    /// every reagent counter in the corpus a stack size of zero.
+    /// Linen Cloth, item 2589: `max_count 0, stackable 20` in vmangos `item_template`.
     #[test]
     fn position_seven_is_the_stack_size_not_the_unique_cap() {
         let mut s = UiScript::new().unwrap();
@@ -952,14 +735,10 @@ mod get_item_info_tests {
             .eval("local _,_,_,_,_,_,g,h = GetItemInfo(2589) return g,h")
             .unwrap();
         assert_eq!(stack, 20, "Stackable (+0x60), never MaxCount (+0x5c)");
-        // InventoryType 0 answers the EMPTY STRING, not nil — index 0 of the 0x83ddb0 table
-        // points at the shared "" at 0x882748.
+        // InventoryType 0 answers "", not nil.
         assert_eq!(equip, "");
     }
 
-    /// The ask-once loop, the reference's own uncached-item behaviour: the cache lookup
-    /// (`0x55ba30`) fires the query and returns null, and the binding falls to
-    /// `xor eax,eax; ret` — **no values at all**, not a nil.
     #[test]
     fn an_uncached_id_returns_nothing_and_records_the_ask() {
         let mut s = UiScript::new().unwrap();
@@ -986,23 +765,17 @@ mod get_item_info_tests {
         );
         assert!(s.take_item_stat_asks().is_empty(), "the push cleared it");
 
-        // Id 0 and a negative id are not askable — no junk query goes out for them.
+        // Id 0 and a negative id record no ask.
         assert_eq!(s.arity("GetItemInfo(0)").unwrap(), 0);
         assert_eq!(s.arity("GetItemInfo(-5)").unwrap(), 0);
         assert!(s.take_item_stat_asks().is_empty());
     }
 
-    /// **The argument forms, which are narrower than the documentation** (see `parse_item_arg`):
-    /// a number, a string Lua coerces to one, or an `item:`-prefixed *item string*. A bare item
-    /// NAME and a full `|cff…|Hitem:…` hyperlink both resolve to id 0 on the real client, because
-    /// `strnicmp(s, "item:", 5)` is the only string test there is.
     #[test]
     fn the_argument_forms_are_the_references_own() {
         let mut s = UiScript::new().unwrap();
         s.set_item_template(25, worn_shortsword());
 
-        // A number, and a string Lua's own coercion reads as one (`lua_isnumber`, 0x6f34d0) —
-        // `GetItemInfo(tostring(id))` is a real corpus call shape.
         for arg in ["25", "\"25\"", "25.7"] {
             assert_eq!(
                 s.eval::<String>(&format!("return (GetItemInfo({arg}))"))
@@ -1012,24 +785,20 @@ mod get_item_info_tests {
             );
         }
 
-        // The item string — the form Auctioneer builds (`AucItemDB.lua:333`). Its enchant /
-        // random-property / suffix fields are echoed back into return 2 verbatim, which is what
-        // makes Auctioneer's feed-the-answer-back-in round trip.
+        // An item string's other fields echo into return 2 verbatim.
         let (name, link): (String, String) = s
             .eval("local a,b = GetItemInfo(\"item:25:2564:7:0\") return a,b")
             .unwrap();
         assert_eq!(name, "Worn Shortsword");
         assert_eq!(link, "item:25:2564:7:0");
-        // Case-insensitive prefix, and a truncated string still parses (atoi stops at the NUL).
+        // A case-insensitive prefix, and a short string still parses.
         assert_eq!(
             s.eval::<String>("local _, link = GetItemInfo(\"ITEM:25\") return link")
                 .unwrap(),
             "item:25:0:0:0"
         );
 
-        // A bare NAME and a full hyperlink: no values. Neither begins with "item:", so the id
-        // stays 0 and the record lookup fails — the real client answers nothing here too, and
-        // neither records an ask.
+        // A bare name and a full hyperlink are id 0: no values and no ask.
         for arg in [
             "\"Worn Shortsword\"",
             "\"|cffffffff|Hitem:25:0:0:0|h[Worn Shortsword]|h|r\"",
@@ -1043,8 +812,7 @@ mod get_item_info_tests {
         }
         assert!(s.take_item_stat_asks().is_empty());
 
-        // Neither a number nor a string raises the binding's own usage error (`0x842d24`, pushed
-        // through the `luaL_error` shape at `0x6f4940`).
+        // Neither a number nor a string raises the usage error (`0x842d24`).
         let err = s
             .eval::<mlua::Value>("return GetItemInfo(nil)")
             .unwrap_err()
@@ -1055,8 +823,6 @@ mod get_item_info_tests {
         );
     }
 
-    /// The `INVTYPE_*` table, transcribed from the 30-pointer array at `0x83ddb0`: both ends,
-    /// the four tokens the shipped `GlobalStrings.lua` never defines, and the empty-string slots.
     #[test]
     fn the_equip_loc_tokens_are_the_binarys_table() {
         assert_eq!(equip_loc_token(0), "", "index 0 is the shared \"\"");
@@ -1066,7 +832,7 @@ mod get_item_info_tests {
         assert_eq!(equip_loc_token(10), "INVTYPE_HAND", "singular");
         assert_eq!(equip_loc_token(17), "INVTYPE_2HWEAPON");
         assert_eq!(equip_loc_token(20), "INVTYPE_ROBE");
-        // The four with no GlobalString to localize them — the reference's own asymmetry.
+        // The four with no `GlobalStrings.lua` entry.
         assert_eq!(equip_loc_token(24), "INVTYPE_AMMO");
         assert_eq!(equip_loc_token(25), "INVTYPE_THROWN");
         assert_eq!(equip_loc_token(26), "INVTYPE_RANGEDRIGHT");
@@ -1076,8 +842,6 @@ mod get_item_info_tests {
         assert_eq!(equip_loc_token(9999), "", "past the array");
     }
 
-    /// The reference's `atoi` (`0x64ac60`): no whitespace skip, no `+`, stop at the first
-    /// non-digit. The last two cases are why this is not `str::parse`.
     #[test]
     fn the_field_parser_is_the_references_atoi() {
         assert_eq!(reference_atoi("2589"), 2589);
@@ -1094,12 +858,6 @@ mod get_item_info_tests {
 mod quality_color_tests {
     use crate::script::UiScript;
 
-    /// The seven colours, byte-verified against wow-5875-re RF-0055's own table — and the two
-    /// edges, which are where every reimplementation of this goes wrong.
-    ///
-    /// The escape string matters as much as the floats: the reference returns it as the fourth
-    /// value and addons splice it straight into a link (`ITEM_QUALITY_COLORS[q].hex .. name`), so
-    /// a missing or differently-cased one shows as literal text in a chat line.
     #[test]
     fn get_item_quality_color_is_the_references_own_table() {
         let s = UiScript::new().unwrap();
@@ -1121,20 +879,16 @@ mod quality_color_tests {
             assert_eq!(hex(q), want, "quality {q}");
         }
 
-        // The floats are `byte / 255`, not a rounded approximation — Epic's red is 0xa3/255.
+        // The floats are byte / 255: Epic's red is 0xa3.
         let r = s
             .eval::<f64>("local r = GetItemQualityColor(4) return r")
             .unwrap();
         assert!((r - 163.0 / 255.0).abs() < 1e-9, "epic red was {r}");
 
-        // `>= 7` clamps to COMMON (index 1), the accessor `0x52ad70`'s own rule — not to Artifact,
-        // and never to nil, because the caller concatenates the result.
+        // 7 and up answer Common (`0x52ad70`).
         assert_eq!(hex(7), "|cffffffff");
         assert_eq!(hex(99), "|cffffffff");
-        // …and the compare is UNSIGNED, so every negative takes the SAME branch and reads Common.
-        // This is the row `UIParent.lua`'s `for i = -1, 6` builds, and the colour a loot row wears
-        // while its item template is uncached (`GetLootSlotInfo` answers -1 there). It read Poor
-        // until 1805; there is no out-of-bounds read to reproduce, the `jb` catches it first.
+        // The compare is unsigned, so a negative answers Common too.
         assert_eq!(hex(-1), "|cffffffff");
         assert_eq!(hex(-99), "|cffffffff");
     }
diff --git a/crates/benilla-ui/src/script/item_text.rs b/crates/benilla-ui/src/script/item_text.rs
index 2d28bfbb..36bc2466 100644
--- a/crates/benilla-ui/src/script/item_text.rs
+++ b/crates/benilla-ui/src/script/item_text.rs
@@ -1,45 +1,32 @@
-//! The item-text reader seam — the `ItemTextFrame` (letters, books, plaques) Lua surface.
-//!
-//! The app owns the read session (`crate::ui_item_text` on the benilla side): right-clicking a bag
-//! item whose `ITEM_FIELD_ITEM_TEXT_ID` is set opens a read instead of a `CMSG_USE_ITEM`, fetches
-//! the text over the ask-once `CMSG_ITEM_TEXT_QUERY` cache (the same wire mail letter bodies ride),
-//! then pushes an [`ItemTextState`] here and fires the reference event pair `ITEM_TEXT_BEGIN` →
-//! `ITEM_TEXT_READY` (ItemTextFrame.lua l.11/38). This module is only the Lua-facing mirror:
-//!
-//! - Getters over the pushed state: `ItemTextGetItem()` (the title), `ItemTextGetCreator()`,
-//!   `ItemTextGetText()`, `ItemTextGetPage()`, `ItemTextHasNextPage()`, `ItemTextGetMaterial()`
-//!   (`nil` → the Lua's own "Parchment" default, l.19-21).
-//! - Intents the app drains: `CloseItemText()` (the frame's OnHide, l.349 — the app clears the
-//!   session and fires `ITEM_TEXT_CLOSED`), `ItemTextPrevPage()`/`ItemTextNextPage()` (multi-page
-//!   `PageText` books — a named follow-up; single-page letters never show the buttons).
+//! The `ItemTextFrame` Lua surface (letters, books, plaques) over the read session the app owns:
+//! getters over the pushed [`ItemTextState`], and the close and page-turn intents. The app fires
+//! `ITEM_TEXT_BEGIN` then `ITEM_TEXT_READY` (`ItemTextFrame.lua:11`, `:38`), and `ITEM_TEXT_CLOSED`
+//! after `CloseItemText()`, the frame's OnHide (`ItemTextFrame.xml:349`).
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// The open read session's Lua-visible snapshot, pushed whole by the app.
+/// The open read session as Lua sees it, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ItemTextState {
-    /// The read item's name (`ItemTextGetItem()` — the window title, e.g. "Plain Letter").
+    /// `ItemTextGetItem()`: the item's name, the window title.
     pub item: String,
-    /// The letter's author (`ItemTextGetCreator()` — `ITEM_FIELD_CREATOR` resolved through the
-    /// name cache); `None` for an authorless text (books) — the Lua skips the "From," tail.
+    /// `ItemTextGetCreator()`: `ITEM_FIELD_CREATOR`'s name, `None` for an authorless text.
     pub creator: Option<String>,
-    /// The current page's text (`ItemTextGetText()`).
+    /// `ItemTextGetText()`: the current page's text.
     pub text: String,
     /// The 1-based page (`ItemTextGetPage()`); letters are always page 1.
     pub page: u32,
     /// Whether a next page exists (`ItemTextHasNextPage()`); always `false` for letters.
     pub has_next: bool,
-    /// The page material basename (`ItemTextGetMaterial()`, e.g. "Stone"); `None` = the default
-    /// parchment (the Lua substitutes "Parchment" and hides the material corners).
+    /// `ItemTextGetMaterial()`, e.g. "Stone"; `None` reads nil, which the frame shows as
+    /// parchment (`ItemTextFrame.lua:19-21`).
     pub material: Option<String>,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open read session. The app pairs the push with the
-    /// reference event flow: set → `ITEM_TEXT_BEGIN` → (text fetched) → `ITEM_TEXT_READY`;
-    /// clear → `ITEM_TEXT_CLOSED`.
+    /// Push the open read session, or clear it with `None`.
     pub fn set_item_text(&mut self, state: Option<ItemTextState>) {
         self.model_mut().item_text = state;
     }
@@ -173,7 +160,7 @@ mod tests {
     #[test]
     fn getters_mirror_the_pushed_state() {
         let mut s = UiScript::new().unwrap();
-        // No session: benign defaults (the frame only reads these while shown anyway).
+        // No session: empty defaults; the frame reads these only while shown.
         assert_eq!(s.eval::<String>("return ItemTextGetItem()").unwrap(), "");
         assert!(s
             .eval::<bool>("return ItemTextGetCreator() == nil")
diff --git a/crates/benilla-ui/src/script/keybind.rs b/crates/benilla-ui/src/script/keybind.rs
index b3b6acdd..30b3f525 100644
--- a/crates/benilla-ui/src/script/keybind.rs
+++ b/crates/benilla-ui/src/script/keybind.rs
@@ -1,33 +1,7 @@
-//! The **key-binding table** — the client's chord→command store, engine side (decision 0997).
-//!
-//! In the reference every rebindable action is a *binding*: a command name (`MOVEFORWARD`)
-//! carrying a category header and up to two bound key chords, stored key→command and saved to
-//! `bindings-cache.wtf`. 1.12 exposes the whole system to Lua (`Blizzard_BindingUI` is plain
-//! FrameXML over it): `GetNumBindings`/`GetBinding(i)`, `SetBinding(key[, command])` with its
-//! steal-the-key law, `GetBindingKey`/`GetBindingAction`, and the three-set model —
-//! `LoadBindings(0 default | 1 account | 2 character)`, `SaveBindings(which)`,
-//! `GetCurrentBindingSet()`.
-//!
-//! benilla keeps the same shape at the same seam, split like the CVar table (0954): the **host
-//! registers** the commands it actually implements (honest-tree — no row without a real engine
-//! action) with their 1.12 default chords, **this table is the string-domain truth** the window's
-//! Lua reads and writes synchronously, and the app derives its dispatch view (parsed chords →
-//! latched commands) whenever [`super::UiScript::keybinds_generation`] moves, persisting on the
-//! queued [`KeybindRequest::Save`]. Chord strings are the reference's own canon —
-//! `[ALT-][CTRL-][SHIFT-]<TOKEN>` (`W`, `SPACE`, `NUMPAD0`, `BUTTON4`, `MOUSEWHEELUP`) — matched
-//! by string equality exactly as the client does (decision 0585's law, now engine-wide).
-//!
-//! The stored account/character sets live here too (seeded by the app from
-//! `benilla-config/bindings/…`, re-snapshotted on save), so `LoadBindings` is **synchronous** like the
-//! reference's — the window calls it and repaints in the same tick, no host round-trip.
-//!
-//! **Addons register into the same table** (decision 1188 phase 4). An addon's `Bindings.xml`
-//! ([`crate::bindings_xml`]) arrives through [`super::UiScript::register_addon_bindings`] and
-//! becomes ordinary rows: same names, same chords, same window, same save file. The one thing an
-//! addon row carries that a host row does not is a **body** — the Lua chunk the app's dispatch
-//! runs on the press (and, for `runOnUp`, again on the release with `keystate = "up"`) — because a
-//! host command's action is engine-side and has no Lua to hold. That body is the *only* asymmetry;
-//! everything downstream of registration treats the two identically.
+//! The key-binding table behind `GetBinding`, `SetBinding`, `LoadBindings` and their kin: per
+//! command, a category header and its chords, spelled `[ALT-][CTRL-][SHIFT-]<TOKEN>` and matched by
+//! string equality as the reference does. Host commands carry their 1.12 defaults; an addon's
+//! `Bindings.xml` adds ordinary rows that also carry a Lua body.
 
 use std::collections::HashMap;
 
@@ -37,10 +11,9 @@ use crate::bindings_xml::AddonBinding;
 
 use super::Model;
 
-/// One host-registered command: the 1.12 name, its category header's global-string key
-/// (`BINDING_HEADER_MOVEMENT`), whether it has press+release semantics (`runOnUp` — the
-/// release half of a press rides this — `RunCommand 0x4b7bf1`, and nothing else: it is NOT a
-/// bindability rule, see [`normalize_binding_key`]), and the 1.12 default chords.
+/// One host-registered command: the 1.12 name, its category header's global string
+/// (`BINDING_HEADER_MOVEMENT`), whether it also runs on release (`runOnUp`, read only by
+/// `RunCommand` at `0x4b7bf1`, never a bindability rule), and the 1.12 default chords.
 #[derive(Clone, Copy, Debug)]
 pub struct KeybindCommand {
     pub name: &'static str,
@@ -50,17 +23,10 @@ pub struct KeybindCommand {
     pub default2: Option<&'static str>,
 }
 
-/// One addon-declared binding's **runnable half** — what the app's dispatch needs to fire a row
-/// it cannot find in its own `SPECS` registry (decision 1188 phase 4).
-///
-/// The dispatch view is re-derived whenever [`super::UiScript::keybinds_generation`] moves, so
-/// this is a snapshot like [`super::UiScript::keybind_snapshot`] rather than a borrow — same
-/// reason: the app holds it across frames while Lua keeps editing the table underneath.
+/// An addon binding's runnable half: what the app's dispatch needs to fire it.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct AddonBindingBody {
-    /// The command name, exactly as registered — what a [`keybind_snapshot`] row is keyed by.
-    ///
-    /// [`keybind_snapshot`]: super::UiScript::keybind_snapshot
+    /// The command name as registered, the key of a `keybind_snapshot` row.
     pub name: String,
     /// Run the body a second time on the release, with `keystate = "up"` (`runOnUp="true"`).
     pub run_on_up: bool,
@@ -68,36 +34,22 @@ pub struct AddonBindingBody {
     pub body: String,
 }
 
-/// A host request queued by Lua: persist the live table as set `1`/`2` (`Save`), on which the
-/// app writes `benilla-config/bindings/…` — and, for `Save(1)` issued while the character set was
-/// active, deletes the character file (the reference's confirmed delete-on-switch); or fire a
-/// named binding's action outright (`Run`).
+/// A host request queued by Lua. `Save(set)` persists set 1 or 2 under `benilla-config/bindings/`;
+/// `Save(1)` also deletes the character set's file.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum KeybindRequest {
     Save(u32),
-    /// `RunBinding("SCREENSHOT")` — run the command's action as if its chord had been pressed.
-    /// It is a *request* rather than something the VM can do itself because a host command's
-    /// action is engine-side by construction (see this module's header): the VM holds the command
-    /// name and its chords, never its body.
+    /// `RunBinding(command)`: the app runs the command's action as if its chord were pressed.
     Run(String),
 }
 
-/// The reference's key-string gate — the whole of `SetBinding`'s refusal (decision 1295), in its
-/// two halves: the alias normalization at the head of `CBindings::SetBinding 0x4b7490`, and the
-/// validator `IsValidBindingKeyString 0x4b7890` it then calls.
-///
-/// `Some` is the string to STORE — upper-cased, because the table's hash and its bucket compare
-/// both fold case (`0x64b3f0` / `0x64a4c0`), so `"shift-w"` and `"SHIFT-W"` are one key. `None` is
-/// the refusal, and it is the *only* one the reference has: no command is ever consulted.
-///
-/// The two halves disagree about case on purpose, and that is verified, not a guess: the alias
-/// compare is case-insensitive, the validator is case-SENSITIVE at all three of its sites
-/// (`0x64a480` → `0x40de80`). So `SetBinding("mousewheelup", …)` answers nil while
-/// `SetBinding("MOUSEWHEELUP", …)` binds — and a *lookup* for either finds it.
+/// `SetBinding`'s only refusal: the alias step of `CBindings::SetBinding` (`0x4b7490`), then
+/// `IsValidBindingKeyString` (`0x4b7890`); no command is consulted. `Some` is the key to store,
+/// upper-cased because the table's hash and compare fold case (`0x64b3f0`, `0x64a4c0`). The alias
+/// step ignores case but the validator does not (`0x64a480`), so `"mousewheelup"` is refused.
 pub fn normalize_binding_key(key: &str) -> Option<String> {
-    // Eleven punctuation NAMES become their literal character. A WHOLE-STRING compare, so
-    // `SHIFT-LEFTBRACKET` is not normalized — and then fails the validator, where the accepted
-    // spelling `SHIFT-[` passes.
+    // Eleven punctuation names become their character on a whole-string match only, so
+    // `SHIFT-LEFTBRACKET` is refused where `SHIFT-[` passes.
     const ALIASES: [(&str, &str); 11] = [
         ("LEFTBRACKET", "["),
         ("RIGHTBRACKET", "]"),
@@ -120,9 +72,7 @@ pub fn normalize_binding_key(key: &str) -> Option<String> {
 
 /// `IsValidBindingKeyString 0x4b7890`, arm for arm.
 fn is_valid_binding_key(key: &str) -> bool {
-    // 1. Strip `SHIFT-`/`CTRL-`/`ALT-` repeatedly — the loop restarts while any matched
-    //    (`0x4b78a0`–`0x4b78d0`), so the validator takes modifiers in ANY order and REPEATED,
-    //    unlike the fixed ALT-CTRL-SHIFT order the chord builder emits.
+    // 1. Modifier prefixes, in any order and any number of times (`0x4b78a0`-`0x4b78d0`).
     let mut rest = key;
     while let Some(next) = ["SHIFT-", "CTRL-", "ALT-"]
         .iter()
@@ -130,14 +80,11 @@ fn is_valid_binding_key(key: &str) -> bool {
     {
         rest = next;
     }
-    // 2. One character passes (`0x41aab0` decode, `0x4b78e6`) — which is how every letter, digit
-    //    and punctuation key is bindable without being named anywhere. The empty string lands in
-    //    the same arm and passes too; `SHIFT-` alone is therefore a legal (unpressable) key.
+    // 2. One character or none passes (`0x4b78e6`): `SHIFT-` alone is a legal key.
     if rest.chars().count() <= 1 {
         return true;
     }
-    // 3. `F`/`NUMPAD`/`BUTTON` (the table at `0x846c04`) followed by digits and nothing else.
-    //    `NUMPADPLUS` falls through here to arm 4, its remainder not being digits.
+    // 3. `F`, `NUMPAD` or `BUTTON` (`0x846c04`) followed by digits only.
     for prefix in ["F", "NUMPAD", "BUTTON"] {
         if let Some(digits) = rest.strip_prefix(prefix) {
             if !digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit()) {
@@ -145,9 +92,7 @@ fn is_valid_binding_key(key: &str) -> bool {
             }
         }
     }
-    // 4. The 26 names at `0x846c20`…`0x846c84`. `SHIFT`/`CTRL`/`ALT`/`UNKNOWN` are in none of the
-    //    arms, which is why a lone modifier can never be bound — and `SCROLLLOCK`/`PAUSE` are in
-    //    none either, matching the namer that calls their key codes `UNKNOWN` (`0x210`/`0x211`).
+    // 4. The 26 names at `0x846c20`-`0x846c84`: no lone modifier, `SCROLLLOCK` or `PAUSE`.
     const NAMES: [&str; 26] = [
         "SPACE",
         "NUMPADPLUS",
@@ -185,83 +130,49 @@ struct Entry {
     category: String,
     run_on_up: bool,
     defaults: [Option<String>; 2],
-    /// The live bound chords, in bind order (the reference's per-command key list; the first two
-    /// are what `GetBindingKey` and the window's Key 1/Key 2 columns show).
+    /// The live chords in bind order; `GetBindingKey` and the window show the first two.
     keys: Vec<String>,
-    /// `hidden="true"` on an addon's `<Binding>` — bindable, saved and dispatched like any other
-    /// row, but absent from the window's enumeration ([`KeybindState::visible`]). Always `false`
-    /// for a host command: the registry is an honest tree, so there is nothing in it to hide.
+    /// An addon's `hidden="true"`: a full binding, left out of `GetNumBindings`/`GetBinding`.
     hidden: bool,
-    /// An addon binding's Lua chunk; `None` for a host command, whose action is engine-side. This
-    /// is what makes a row an addon's — see the module doc.
+    /// An addon binding's Lua chunk; `None` for a host command, whose action is engine-side.
     body: Option<String>,
 }
 
-/// The table + the stored sets + the Lua→host seams. Lives in [`Model`].
+/// The table, the stored sets and the queued host requests; lives in [`Model`].
 #[derive(Default)]
 pub(crate) struct KeybindState {
     entries: Vec<Entry>,
     by_name: HashMap<String, usize>,
-    /// Saved snapshots: `stored[0]` = account (set 1), `stored[1]` = character (set 2, `None`
-    /// when no character-specific bindings exist). Each is per-entry key lists, entry order.
+    /// Stored sets in entry order: `[0]` account (set 1), `[1]` character (set 2, if any).
     stored: [Option<Vec<Vec<String>>>; 2],
-    /// The same two stored sets **by command name** (decision 1201).
-    ///
-    /// [`Self::stored`] is positional over [`Self::entries`], which is exactly right for the
-    /// commands that exist when a set is seeded and useless for the ones that do not: an addon's
-    /// `Bindings.xml` registers at world entry, long after the account set was seeded at boot, so
-    /// its row in the stored file had no slot to land in and its chord was silently dropped. The
-    /// binding registered, listed in the window, dispatched — and forgot its key every restart
-    /// (the defect 1192 §4 recorded). Keyed by the UPPERCASED name, like `by_name`.
+    /// The same sets by uppercased name, for addon commands registered after the seed.
     stored_by_name: [HashMap<String, Vec<String>>; 2],
-    /// `1` account, `2` character — which set the live table edits (`GetCurrentBindingSet`).
+    /// The set the live table edits (`GetCurrentBindingSet`): 1 account, 2 character.
     current_set: u32,
-    /// Bumped by every live-table mutation and every seed — the app's re-derive-dispatch signal.
+    /// Bumped by every change to the live table: the app's signal to re-derive dispatch.
     generation: u64,
     requests: Vec<KeybindRequest>,
-    /// The Keybindings page's capture arm (`BenillaBindCapture(armed)`): while set, the host
-    /// swallows raw input and calls the page back with the canonical chord string.
+    /// Set by `BenillaBindCapture`: the host swallows raw input and hands the page the chord.
     capture_armed: bool,
 }
 
 impl KeybindState {
-    /// The rows the Key Bindings window enumerates — everything except the `hidden="true"` ones
-    /// (decision 1188 phase 4).
-    ///
-    /// The filter lives at the *Lua enumeration* (`GetNumBindings`/`GetBinding`) rather than at
-    /// registration, because a hidden binding is a real binding everywhere else: `SetBinding` can
-    /// bind it, `GetBindingAction` reports it, the app dispatches it, and the save file carries
-    /// it. That is 1.12's own split — the shipped `Blizzard_BindingUI.lua` filters on nothing but
-    /// the `HEADER` prefix (l.87), so `hidden` can only be the engine's own exclusion from the
-    /// enumeration it walks, and the twelve hidden rows (the debug toggles, `TURNORACTION`,
-    /// `CAMERAORSELECTORMOVE`…) are exactly the ones no 1.12 Key Bindings window shows.
-    ///
-    /// Inert for everything shipped today: no host command is hidden, so the enumeration is
-    /// entry-for-entry what it was before addons could register.
+    /// The rows `GetNumBindings`/`GetBinding` enumerate: all but `hidden="true"`, since the stock
+    /// window skips only `HEADER` rows (`Blizzard_BindingUI.lua:87`).
     fn visible(&self) -> impl Iterator<Item = &Entry> {
         self.entries.iter().filter(|e| !e.hidden)
     }
 
-    /// The reference's `SetBinding(key[, command])`: unbind `key` wherever it is, then (with a
-    /// command) append it to that command's key list.
-    ///
-    /// **The only thing it refuses is a key string that is not a key** (decision 1295). We used to
-    /// refuse a mousewheel chord on a press+release (`runOnUp`) command — the reading everyone
-    /// takes from `Blizzard_BindingUI`'s `if not SetBinding(…) then … KEYBINDINGFRAME_MOUSEWHEEL_
-    /// ERROR`. It is wrong: `CBindings::SetBinding 0x4b7490` never reads a command node at all
-    /// (neither the target's nor the incumbent's), and its one reachable falsey return is the
-    /// validator at `0x4b762c`. `"runOnUp"` has exactly one reader image-wide — `0x4b7bf1`, in
-    /// `RunCommand`, gating the up half. So 1.12 binds the wheel to an action button happily, and
-    /// B265 was ours. wow-re `system/ui/scratch/setbinding-refusal-law.md`.
+    /// `SetBinding(key[, command])`: unbind `key` everywhere, then append it to the command's
+    /// list. The reference refuses only an invalid key (`0x4b762c`) and never reads the command
+    /// (`0x4b7490`), so the wheel binds to a `runOnUp` command despite the stock window's
+    /// MOUSEWHEEL_ERROR branch.
     fn set_binding(&mut self, key: &str, command: Option<&str>) -> bool {
         let Some(key) = normalize_binding_key(key) else {
             return false;
         };
-        // The one divergence left here (1295): the reference stores the action string verbatim,
-        // so `SetBinding("K", "NOSUCHCOMMAND")` answers 1 there and nil here. Our table is
-        // command-centric — a key list per registered command — and has nowhere to put a binding
-        // whose command does not exist. Nothing reachable today can hit it: the window offers
-        // only registered rows, and an addon's own names register from its `Bindings.xml`.
+        // Deviation: an unregistered command answers nil where the reference stores the string
+        // and answers 1, because this table only holds key lists of registered commands.
         let cmd_idx = match command {
             Some(name) => match self.by_name.get(&name.to_ascii_uppercase()) {
                 Some(&i) => Some(i),
@@ -279,14 +190,12 @@ impl KeybindState {
         true
     }
 
-    /// Snapshot the live key lists (entry order) — the stored-set payload.
+    /// The live key lists in entry order, as a stored set holds them.
     fn snapshot(&self) -> Vec<Vec<String>> {
         self.entries.iter().map(|e| e.keys.clone()).collect()
     }
 
-    /// Replace the live key lists from a snapshot (entry-count mismatch pads/truncates — a
-    /// stored set from before a command was registered simply leaves the new command on its
-    /// live value).
+    /// Replace the live key lists from a snapshot; an entry past the snapshot's end keeps its keys.
     fn apply(&mut self, snap: &[Vec<String>]) {
         for (i, e) in self.entries.iter_mut().enumerate() {
             if let Some(keys) = snap.get(i) {
@@ -303,10 +212,9 @@ impl KeybindState {
             .collect()
     }
 
-    /// The reference's `LoadBindings(set)`: 0 = defaults, 1 = account, 2 = character (falling
-    /// back to the account snapshot when no character set exists — the reference's character
-    /// set starts as a copy). Loading 1/2 also moves `current_set`; loading defaults does not
-    /// (you are still *editing* the set you had, as in the window's Reset To Default).
+    /// `LoadBindings(set)`: 0 defaults, 1 account, 2 character, which falls back to the account
+    /// set (the reference's starts as a copy). Loading defaults keeps the current set, as the
+    /// window's Reset To Default does.
     fn load(&mut self, set: u32) {
         match set {
             0 => {
@@ -332,9 +240,8 @@ impl KeybindState {
         }
     }
 
-    /// The reference's `SaveBindings(which)`: snapshot live into set `which`, make it current,
-    /// and — saving account while character bindings exist — drop the character set (the
-    /// window's confirmed permanent delete). Queues the host persist.
+    /// `SaveBindings(which)`: store the live table as set `which` and make it current. Saving the
+    /// account set drops the character set, the window's confirmed delete.
     fn save(&mut self, which: u32) {
         if which != 1 && which != 2 {
             return;
@@ -347,45 +254,19 @@ impl KeybindState {
         self.requests.push(KeybindRequest::Save(which));
     }
 
-    /// Append one addon's parsed `Bindings.xml` (decision 1188 phase 4).
-    ///
-    /// **Append-only and idempotent per uppercased name**, exactly like [`super::UiScript::
-    /// register_bindings`] — which is also what makes a host command win outright: `MOVEFORWARD`
-    /// is already in the table when an addon declares it, so the addon's row is skipped and the
-    /// engine's real action keeps the name. Nothing is ever replaced, so an index handed out
-    /// earlier (the dispatch view's, the window's row) stays valid.
-    ///
-    /// **The section carry-forward** is applied here, where the addon's identity is known: a
-    /// `header` attribute opens a section that runs until the next one (the reference's list is
-    /// flat with `HEADER_*` pseudo-entries in it, so 13 headers cover its 228 bindings — and our
-    /// own `SPECS` table already encodes exactly that reading, giving `MOVEBACKWARD` the
-    /// `MOVEMENT` header its `<Binding>` never states).
-    ///
-    /// **A file whose first bindings declare no header at all gets the addon's own name** as
-    /// their section token, and that is a deliberate divergence: the reference would continue
-    /// whatever section the *previous file* ended in, which under our per-entry category (0997's
-    /// era-shaped `GetBinding`) would file an addon's keys under `BINDING_HEADER_CAMERA` and make
-    /// them unfindable. The window renders an unknown token literally
-    /// (`KeyBindings_String(token, token)`), so the section simply reads as the addon's name —
-    /// which is the honest answer to "where did these come from". A declared header keeps the
-    /// ecosystem's convention (`header="MYADDON"` → `BINDING_HEADER_MYADDON`, the global string
-    /// the addon defines in its own Lua).
+    /// Append one addon's parsed `Bindings.xml`, skipping a name already registered, so a host
+    /// command keeps it and no handed-out index moves. A `header` opens a section
+    /// (`BINDING_HEADER_<header>`) until the next one, as in the reference's flat list.
+    /// Deviation: rows before a file's first header take the addon's name as their section, not
+    /// the previous file's, because under a foreign header the player could not find them.
     fn register_addon(&mut self, addon: &str, bindings: &[AddonBinding]) {
         let mut section = addon.to_string();
         for b in bindings {
-            // **`platform` skips the whole NODE, header and all** — `0x4b70c3`-`0x4b70e5` bails
-            // out of the element before anything on it is read. It matters here and nowhere else:
-            // `header="ITUNES_REMOTE"` rides on `ITUNES_PLAYPAUSE`, the first of the five
-            // `platform="mac"` rows, so on a build that is not the Mac one that category does not
-            // merely come up empty — it never exists. Keeping the header of a skipped row would
-            // leave its section open over whatever followed.
+            // A foreign `platform` skips the whole node, header included (`0x4b70c3`-`0x4b70e5`).
             if b.platform.as_deref().is_some_and(|p| p != THIS_PLATFORM) {
                 continue;
             }
-            // Before the duplicate skip below: a duplicate name still *closes* a section the same
-            // way, because the header is a property of the file's order, not of the row that
-            // survived it. (Not the platform case above — a duplicate is a node the loader read
-            // and rejected; a foreign-platform node it never read at all.)
+            // Before the duplicate skip: a duplicate's header still opens its section.
             if let Some(h) = &b.header {
                 section = format!("BINDING_HEADER_{h}");
             }
@@ -394,9 +275,7 @@ impl KeybindState {
                 continue;
             }
             let idx = self.entries.len();
-            // The player's stored chord for this command, if they ever set one (decision 1201).
-            // The CURRENT set first, then the account set behind it — the same precedence `load`
-            // applies, so an addon binding restores exactly like a shipped one.
+            // The stored chord: the current set first, then the account set, as `load` falls back.
             let stored = {
                 let cur = if self.current_set == 2 { 1 } else { 0 };
                 self.stored_by_name[cur]
@@ -409,9 +288,7 @@ impl KeybindState {
                 name: b.name.clone(),
                 category: section.clone(),
                 run_on_up: b.run_on_up,
-                // 1.12's `<Binding>` carries no default chord — the shipped defaults live in the
-                // engine's own table, which is why every addon binding starts unbound and the
-                // player binds it in the window.
+                // 1.12's `<Binding>` carries no default chord.
                 defaults: [None, None],
                 keys: stored.unwrap_or_default(),
                 hidden: b.hidden,
@@ -422,11 +299,8 @@ impl KeybindState {
     }
 }
 
-/// What `platform="…"` has to equal for a binding to register here — the reference's own two
-/// spellings, read out of both binaries: the Windows build compares against `"windows"`
-/// (`0x846f98`, tested at `0x4b70c3`-`0x4b70e5`) and the Mac slice against `"mac"` (`0x4e28f8`).
-/// Every other OS benilla runs on takes the `"windows"` name rather than inventing a third — the
-/// only thing this attribute has ever distinguished is a 2006 Carbon app from everything else.
+/// The `platform="…"` value that registers here: the Windows client compares against `"windows"`
+/// (`0x846f98`), the Mac client against `"mac"` (`0x4e28f8`); every other OS takes `"windows"`.
 const THIS_PLATFORM: &str = if cfg!(target_os = "macos") {
     "mac"
 } else {
@@ -434,8 +308,7 @@ const THIS_PLATFORM: &str = if cfg!(target_os = "macos") {
 };
 
 impl super::UiScript {
-    /// Register the host-implemented commands (boot-time, order = the 1.12 `Bindings.xml`
-    /// order). Idempotent per name; live keys seed from the defaults.
+    /// Register the host's commands at boot, in 1.12 `Bindings.xml` order, keys from the defaults.
     pub fn register_bindings(&mut self, commands: &[KeybindCommand]) {
         let mut model = self.model_mut();
         for c in commands {
@@ -460,25 +333,13 @@ impl super::UiScript {
         model.keybinds.generation += 1;
     }
 
-    /// Register one addon's parsed `Bindings.xml` — the runtime-`String` sibling of
-    /// [`Self::register_bindings`] (decision 1188 phase 4), called at the reference's own position
-    /// in the addon load: after that addon's `.toc` files, before its saved variables
-    /// (`0x51f400`).
-    ///
-    /// Two methods rather than one because the two payloads are genuinely different: a host
-    /// command is `&'static str` all the way down (it names a Rust action and ships default
-    /// chords), an addon's is owned text read off disk this session (it names nothing and carries
-    /// a Lua body). The rules they register under are identical — see
-    /// [`KeybindState::register_addon`].
+    /// Register one addon's parsed `Bindings.xml`, at the reference's point in the addon load:
+    /// after its `.toc` files, before its saved variables (`0x51f400`).
     pub fn register_addon_bindings(&mut self, addon: &str, bindings: &[AddonBinding]) {
         self.model_mut().keybinds.register_addon(addon, bindings);
     }
 
-    /// Every addon-declared binding's runnable half, in registration order — the app's dispatch
-    /// derivation reads this beside [`Self::keybind_snapshot`] and indexes into it.
-    ///
-    /// Host commands are absent by construction (they have no body), which is what lets the app's
-    /// dispatch target be a two-armed enum rather than an index space with a sentinel in it.
+    /// Every addon binding's runnable half, in registration order; host commands have none.
     pub fn addon_binding_bodies(&self) -> Vec<AddonBindingBody> {
         self.model_mut()
             .keybinds
@@ -494,17 +355,12 @@ impl super::UiScript {
             .collect()
     }
 
-    /// Host-side seed of a stored set (`1` account / `2` character) — the loaded
-    /// `benilla-config/bindings/…` state, already resolved to full per-command key lists by the app's
-    /// diff layer. Passing the character set marks it existing (the window's checkbox state);
-    /// `seed_binding_set(2, None)` clears it. Does not touch the live table — call
-    /// [`Self::load_binding_set`] after seeding to activate one.
+    /// Seed stored set 1 (account) or 2 (character) from `benilla-config/bindings/`; `None` clears
+    /// it. The live table is untouched until [`Self::load_binding_set`].
     pub fn seed_binding_set(&mut self, set: u32, keys: Option<Vec<(String, Vec<String>)>>) {
         let mut model = self.model_mut();
         let kb = &mut model.keybinds;
-        // Keep the pairs BY NAME as well as positionally: a command that does not exist yet
-        // (an addon's, registered at world entry) has no position to occupy, and the by-name map
-        // is what `register_addon` consults when it finally does (decision 1201).
+        // By name as well: an addon command registered later has no position yet.
         let mut by_name_owned: HashMap<String, Vec<String>> = HashMap::new();
         let snap = keys.map(|pairs| {
             let by_name: HashMap<_, _> = pairs.into_iter().collect();
@@ -540,8 +396,7 @@ impl super::UiScript {
         self.model_mut().keybinds.load(set);
     }
 
-    /// The live table as `(command, bound chords)` in registration order — the app's dispatch
-    /// derivation and the save diff read this.
+    /// The live table as `(command, chords)` in registration order, for dispatch and the save.
     pub fn keybind_snapshot(&self) -> Vec<(String, Vec<String>)> {
         self.model_mut()
             .keybinds
@@ -551,13 +406,12 @@ impl super::UiScript {
             .collect()
     }
 
-    /// Bumped by every table mutation (Lua or host) — cheap to poll; re-derive dispatch when it
-    /// moves (the macros-generation pattern).
+    /// Bumped by every table change; re-derive dispatch when it moves.
     pub fn keybinds_generation(&self) -> u64 {
         self.model_mut().keybinds.generation
     }
 
-    /// Drain the queued host requests (persist-on-save).
+    /// Drain the queued host requests.
     pub fn take_keybind_requests(&mut self) -> Vec<KeybindRequest> {
         std::mem::take(&mut self.model_mut().keybinds.requests)
     }
@@ -567,23 +421,19 @@ impl super::UiScript {
         self.model_mut().keybinds.current_set
     }
 
-    /// Whether a character-specific stored set exists (the checkbox's persisted truth).
+    /// Whether a character-specific stored set exists (the window's checkbox).
     pub fn character_bindings_exist(&self) -> bool {
         self.model_mut().keybinds.stored[1].is_some()
     }
 
-    /// The Keybindings page's capture arm — while true, the host swallows raw input and
-    /// calls `KeyBindings_OnHostKey("<chord>")` instead of dispatching it.
+    /// While true, the host swallows raw input and calls `KeyBindings_OnHostKey("<chord>")`.
     pub fn bind_capture_armed(&self) -> bool {
         self.model_mut().keybinds.capture_armed
     }
 }
 
-/// Register one addon's parsed `Bindings.xml` from a bare `&Lua` — the `LoadAddOn` path
-/// ([`super::addon::load_addon`]) runs *inside* a Lua binding, synchronously, and has no
-/// [`super::UiScript`] to reach. The exact shape `load_saved_variables` already uses next door,
-/// and for the same reason: both halves of the addon load must do the same thing at the same
-/// position, whichever entered.
+/// Register one addon's `Bindings.xml` from a bare `&Lua`: `LoadAddOn` runs inside a Lua binding
+/// with no `UiScript` to reach.
 pub(crate) fn register_addon_bindings(lua: &Lua, addon: &str, bindings: &[AddonBinding]) {
     lua.app_data_mut::<Model>()
         .expect("model app_data")
@@ -591,12 +441,9 @@ pub(crate) fn register_addon_bindings(lua: &Lua, addon: &str, bindings: &[AddonB
         .register_addon(addon, bindings);
 }
 
-/// Register the binding globals (1.12 names; `GetBinding` returns the era 4-tuple —
-/// command, category token, key1, key2 — the categorized window's shape).
-///
-/// `GetNumBindings`/`GetBinding` walk [`KeybindState::visible`] — the table minus the
-/// `hidden="true"` rows — while every other verb here keys on name or chord and so sees the whole
-/// table (a hidden binding is bindable, saved and dispatched, just not listed).
+/// The binding globals. `GetBinding` returns command, category, key1, key2, which is not 1.12's
+/// shape: 1.12 returns command, key1, key2, with each header a `HEADER_*` row
+/// (`Blizzard_BindingUI.lua:84`). Only `GetNumBindings` and `GetBinding` skip hidden rows.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set(
         "GetNumBindings",
@@ -633,11 +480,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(if ok { Some(1) } else { None })
         })?,
     )?;
-    // `RunBinding(command)` — the reference's own passthrough verb. Its live caller is
-    // `CinematicFrame`'s `OnKeyDown`, which hands the SCREENSHOT chord back to its binding while
-    // swallowing every other key, so a player can still photograph a fly-by. Anything the VM
-    // holds a body for it could run itself; a host command's action is engine-side, so this
-    // queues and the app fires it in the same frame.
+    // `RunBinding(command)`, as `CinematicFrame.xml:42` passes SCREENSHOT through: a host
+    // command's action is engine-side, so this queues it and the app runs it in the same frame.
     lua.globals().set(
         "RunBinding",
         lua.create_function(|lua, command: String| {
@@ -756,7 +600,7 @@ mod tests {
     fn the_table_reads_like_the_reference() {
         let s = script();
         assert_eq!(s.eval::<usize>("return GetNumBindings()").unwrap(), 3);
-        // Era 4-tuple: command, category token, key1, key2 — defaults seeded live.
+        // Command, category, key1, key2 (not 1.12's three values), the defaults seeded live.
         assert!(s
             .eval::<bool>(
                 r#"local c, cat, k1, k2 = GetBinding(1)
@@ -780,8 +624,7 @@ mod tests {
     fn set_binding_steals_and_refuses_only_a_key_string_that_is_not_a_key() {
         let s = script();
         let g0 = s.keybinds_generation();
-        // Bind W to JUMP: stolen from MOVEFORWARD (its slot 1 empties, UP slides up), appended
-        // to JUMP's list after its defaults.
+        // W leaves MOVEFORWARD (UP slides up) and joins the end of JUMP's list.
         assert!(s
             .eval::<bool>(r#"return SetBinding("W", "JUMP") == 1"#)
             .unwrap());
@@ -794,26 +637,20 @@ mod tests {
             s.eval::<String>(r#"return GetBindingAction("W")"#).unwrap(),
             "JUMP"
         );
-        // Unbind by key: SetBinding(key) with no command.
         s.run(r#"SetBinding("SPACE")"#).unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetBindingAction("SPACE")"#)
                 .unwrap(),
             ""
         );
-        // **The wheel binds to a press+release command** (B265, decision 1295). This assertion
-        // used to read `== nil`, on the universal misreading of `Blizzard_BindingUI`'s
-        // `if not SetBinding(…) then … KEYBINDINGFRAME_MOUSEWHEEL_ERROR`. `0x4b7490` never looks
-        // at a command node, so 1.12 takes it — and the notch runs both halves.
+        // The wheel binds to a `runOnUp` command: `0x4b7490` never reads the command.
         assert!(s
             .eval::<bool>(r#"return SetBinding("SHIFT-MOUSEWHEELUP", "MOVEFORWARD") == 1"#)
             .unwrap());
         assert!(s
             .eval::<bool>(r#"return SetBinding("MOUSEWHEELDOWN", "CAMERAZOOMIN") == 1"#)
             .unwrap());
-        // The refusal that IS there: `IsValidBindingKeyString 0x4b7890`. A lone modifier, a name
-        // in none of its four arms, and an alias that is not the whole string all fail; the
-        // pure unbind runs the same validator, so it fails on the same strings.
+        // Refused by `IsValidBindingKeyString` (`0x4b7890`), on the pure unbind too.
         for bad in ["SHIFT", "ALT", "UNKNOWN", "SCROLLLOCK", "SHIFT-LEFTBRACKET"] {
             assert!(
                 s.eval::<bool>(&format!(r#"return SetBinding("{bad}", "JUMP") == nil"#))
@@ -826,8 +663,6 @@ mod tests {
                 "{bad} fails the same validator on the pure unbind"
             );
         }
-        // …and the ones that pass: one character (with modifiers in any order and repeated),
-        // F/NUMPAD/BUTTON + digits, the 26 names, and a whole-string punctuation alias.
         for good in [
             "SHIFT-CTRL-ALT-K",
             "CTRL-SHIFT-K",
@@ -852,8 +687,7 @@ mod tests {
             "JUMP",
             "the alias is normalized to its literal character before it is stored"
         );
-        // The validator is case-SENSITIVE where the lookup behind it is not: a lower-case key
-        // string never reaches the table at all.
+        // The validator is case-sensitive: a lower-case key string is refused.
         assert!(s
             .eval::<bool>(r#"return SetBinding("shift-w", "JUMP") == nil"#)
             .unwrap());
@@ -868,52 +702,31 @@ mod tests {
         let mut s = script();
         assert_eq!(s.current_binding_set(), 1);
         assert!(!s.character_bindings_exist());
-        // Rebind, save as character: stored set 2 exists, current set moves.
         s.run(r#"SetBinding("F", "JUMP")"#).unwrap();
         s.run("SaveBindings(2)").unwrap();
         assert_eq!(s.current_binding_set(), 2);
         assert!(s.character_bindings_exist());
         assert_eq!(s.take_keybind_requests(), vec![KeybindRequest::Save(2)]);
-        // Reset To Default: LoadBindings(0) restores defaults but stays on the character set.
+        // Reset To Default keeps the character set current.
         s.run("LoadBindings(0)").unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetBindingAction("F")"#).unwrap(),
             ""
         );
         assert_eq!(s.current_binding_set(), 2);
-        // Cancel's revert: LoadBindings(current) restores the saved character set.
+        // Cancel reloads the saved character set.
         s.run("LoadBindings(2)").unwrap();
         assert_eq!(
             s.eval::<String>(r#"return GetBindingAction("F")"#).unwrap(),
             "JUMP"
         );
-        // Okay back to general: SaveBindings(1) drops the character set — the confirmed
-        // permanent delete — and the app is asked to persist (and unlink the character file).
+        // Saving the account set drops the character set, the confirmed delete.
         s.run("SaveBindings(1)").unwrap();
         assert_eq!(s.current_binding_set(), 1);
         assert!(!s.character_bindings_exist());
         assert_eq!(s.take_keybind_requests(), vec![KeybindRequest::Save(1)]);
     }
 
-    /// **An addon's `Bindings.xml` becomes ordinary rows** (decision 1188 phase 4) — same table,
-    /// same window, same `SetBinding` laws — with exactly two things that only an addon row has:
-    /// a Lua body, and the `hidden` bit.
-    ///
-    /// What each assertion would catch, since this is the seam a real addon's keys arrive
-    /// through:
-    /// - **the count and the tuple**: a registration that lands somewhere the window cannot see
-    ///   (the whole symptom 1188 phase 4 exists to remove);
-    /// - **the carried header**: a per-row reading of `header`, which would leave 215 of the
-    ///   reference's own 228 bindings in a nameless category, and a doubled `BINDING_HEADER_`
-    ///   prefix if the parser's job were done twice;
-    /// - **the addon-name fallback**: a header-less file whose rows land in whatever section
-    ///   happened to be last — unfindable in the window, which is why we diverge here;
-    /// - **`MOVEFORWARD`**: an addon quietly *replacing* a host command by declaring its name,
-    ///   which would swap a real engine action for a Lua body;
-    /// - **the hidden row**: `hidden="true"` read as "do not register" rather than "do not list",
-    ///   which would make the binding unbindable and undispatchable;
-    /// - **the bodies**: a host row leaking into [`super::UiScript::addon_binding_bodies`], which
-    ///   is what makes the app's dispatch target a two-armed enum instead of a sentinel index.
     #[test]
     fn an_addons_bindings_xml_registers_as_ordinary_rows() {
         let mut s = script();
@@ -935,8 +748,8 @@ mod tests {
             "registration must move the generation — it is the app's re-derive-dispatch signal"
         );
 
-        // Three host commands + the two listable addon rows. `MOVEFORWARD` did not register
-        // twice, and `PROBEHIDDEN` is registered but not listed.
+        // Three host rows and two addon rows: the addon's `MOVEFORWARD` is skipped and
+        // `PROBEHIDDEN` is not listed.
         assert_eq!(s.eval::<usize>("return GetNumBindings()").unwrap(), 5);
         assert!(s
             .eval::<bool>(
@@ -952,14 +765,13 @@ mod tests {
             .unwrap(),
             "a row with no header of its own belongs to the section the last header opened"
         );
-        // The host's own command kept its row, its keys and its engine action.
         assert!(s
             .eval::<bool>(
                 r#"local k1, k2 = GetBindingKey("MOVEFORWARD"); return k1 == "W" and k2 == "UP""#
             )
             .unwrap());
 
-        // The hidden row is absent from the enumeration…
+        // The hidden row is not enumerated, but binds and is found by key.
         assert!(s
             .eval::<bool>(
                 r#"for i = 1, GetNumBindings() do
@@ -968,7 +780,6 @@ mod tests {
                    return true"#
             )
             .unwrap());
-        // …and is a binding in every other respect: bindable, and found by key.
         assert!(s
             .eval::<bool>(r#"return SetBinding("H", "PROBEHIDDEN") == 1"#)
             .unwrap());
@@ -976,8 +787,7 @@ mod tests {
             s.eval::<String>(r#"return GetBindingAction("H")"#).unwrap(),
             "PROBEHIDDEN"
         );
-        // And it rides the same laws: `runOnUp` decides whether the body runs again on the
-        // release, never whether the row may take a wheel chord (1295) — so both bind.
+        // `runOnUp` never refuses a wheel chord.
         assert!(s
             .eval::<bool>(r#"return SetBinding("MOUSEWHEELUP", "PROBEHOLD") == 1"#)
             .unwrap());
@@ -985,7 +795,7 @@ mod tests {
             .eval::<bool>(r#"return SetBinding("MOUSEWHEELDOWN", "PROBEEDGE") == 1"#)
             .unwrap());
 
-        // A second addon, declaring no header at all: its rows are its own section, named for it.
+        // A file with no header: its rows' section is the addon's name.
         let parsed = crate::bindings_xml::parse(
             r#"<Bindings><Binding name="LIBKEY">Lib();</Binding></Bindings>"#,
         )
@@ -997,8 +807,7 @@ mod tests {
             )
             .unwrap());
 
-        // The runnable halves the app's dispatch indexes — addon rows only, in registration
-        // order, hidden included.
+        // Addon rows only, in registration order, hidden included.
         let bodies = s.addon_binding_bodies();
         let names: Vec<&str> = bodies.iter().map(|b| b.name.as_str()).collect();
         assert_eq!(names, ["PROBEHOLD", "PROBEEDGE", "PROBEHIDDEN", "LIBKEY"]);
@@ -1006,11 +815,6 @@ mod tests {
         assert!(bodies[0].body.contains(r#"keystate == "down""#));
     }
 
-    /// **The file's own OS gate.** `platform="mac"` is 1.12's one OS-specific device in
-    /// `Bindings.xml` — five `ITUNES_REMOTE` rows in the Mac build and nowhere else — and a row
-    /// for the other build is not registered at all. Not hidden, not registered-and-inert:
-    /// registering it would list a command in the Key Bindings window whose body calls functions
-    /// this build does not have, and let the player spend a key on it.
     #[test]
     fn a_binding_for_another_platform_does_not_register() {
         let mut s = script();
@@ -1033,7 +837,6 @@ mod tests {
             !names.iter().any(|n| n == "PROBEELSEWHERE"),
             "a foreign-platform row registered: {names:?}"
         );
-        // …and it is not merely hidden from the window either: nothing can bind it.
         assert!(!s
             .addon_binding_bodies()
             .iter()
@@ -1049,8 +852,7 @@ mod tests {
             s.eval::<String>(r#"return GetBindingAction("F")"#).unwrap(),
             "JUMP"
         );
-        // Commands absent from the seed keep their live keys (a stored set from before a
-        // command was registered leaves the new command alone).
+        // A command the seed lacks keeps its live keys.
         assert_eq!(
             s.eval::<String>(r#"return GetBindingAction("W")"#).unwrap(),
             "MOVEFORWARD"
@@ -1083,18 +885,11 @@ mod addon_persistence_tests {
         }
     }
 
-    /// **An addon's binding remembers its key across a restart** — the defect decision 1192 §4
-    /// recorded and left open: "the binding registers, lists, dispatches, and forgets its key."
-    ///
-    /// The shape is the whole point, so it is reproduced literally: at BOOT the stored set is
-    /// seeded while only the host's own commands exist, and the addon's `Bindings.xml` registers
-    /// hours later at world entry. The stored row therefore has no slot to land in, which is why
-    /// the positional snapshot alone could never carry it.
+    /// The stored set is seeded at boot, before the addon's `Bindings.xml` registers at world
+    /// entry, so its row has no position to land in.
     #[test]
     fn an_addon_binding_restores_its_stored_chord_registered_after_the_seed() {
         let mut s = UiScript::new().unwrap();
-        // Boot: the host's commands, then the account set off disk — which already carries the
-        // player's chord for a command that does not exist in this VM yet.
         s.register_bindings(&[KeybindCommand {
             name: "JUMP",
             category: "BINDING_HEADER_MOVEMENT",
@@ -1111,7 +906,6 @@ mod addon_persistence_tests {
         );
         s.load_binding_set(1);
 
-        // World entry: the addon's Bindings.xml registers.
         s.register_addon_bindings("MyAddon", &[binding("MYADDONTOGGLE")]);
 
         let bound = s
@@ -1126,8 +920,6 @@ mod addon_persistence_tests {
         );
     }
 
-    /// A command the stored set says nothing about still registers **unbound**, which is 1.12's
-    /// own rule for an addon binding (its `<Binding>` carries no default chord).
     #[test]
     fn an_addon_binding_with_no_stored_chord_registers_unbound() {
         let mut s = UiScript::new().unwrap();
@@ -1142,8 +934,6 @@ mod addon_persistence_tests {
         assert!(bound.1.is_empty());
     }
 
-    /// The character set wins over the account set for an addon command too — the same precedence
-    /// `load` applies to every other command, so an addon binding restores like a shipped one.
     #[test]
     fn the_character_set_wins_for_an_addon_command() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/keyboard.rs b/crates/benilla-ui/src/script/keyboard.rs
index 583f6ad0..67a6f303 100644
--- a/crates/benilla-ui/src/script/keyboard.rs
+++ b/crates/benilla-ui/src/script/keyboard.rs
@@ -1,85 +1,35 @@
-//! **Frame keyboard delivery** — the walk, the existence gate, and the key-name argument.
+//! Frame keyboard delivery. One dispatcher per [`Channel`] calls the keyboard-enabled frames in
+//! [`walk_order`] until one consumes. Consumption is the existence of a script slot, not what the
+//! handler does: a key-down consumes on `OnKeyDown` or `OnKeyUp` and fires only `OnKeyDown`, so a
+//! frame with only `OnKeyUp` swallows key-downs and runs nothing; a char consumes on `OnChar`.
+//! Membership is the keyboard-enabled flag (`0x76af00`), never a script: XML `enableKeyboard` and
+//! an XML `<Scripts>` handler set it, Lua `SetScript` does not.
 //!
-//! Until this module, keys went straight to the focused EditBox and a plain frame could not receive
-//! a key at all: `OnChar`/`OnKeyDown`/`OnKeyUp` were the three script names
-//! [`super::object::events_regions`] deliberately *raised* on, because accepting a name this engine
-//! never fires is the silent-drop class 1203/1205/1211 each recorded. This is the machinery that
-//! note was waiting on, so those three names are now accepted there.
+//! The focused EditBox is a frame in the same walk, consuming through its own vtable, so a
+//! keyboard frame in a higher stratum pre-empts it and one in a lower stratum does not. A key no
+//! frame consumes falls through to the editbox routing, focus acquisition included.
 //!
-//! ## The law (wow-re `system/ui/scratch/frame-key-script-delivery.md`, §5 trio — VERIFIED)
-//!
-//! An OS key event reaches **one dispatcher per channel**, and the dispatcher — not the frame — is
-//! what walks: `0x765f10` (key-down, kind-1 buckets, vtable `+0x60`) and `0x765df0` (char, kind-0
-//! buckets, `+0x5c`). Each walks **9 strata records, TOOLTIP (8) down to WORLD (0)**, and within a
-//! record the frame array **index 0 upward**, which the inserter `0x764aa0` keeps ordered by
-//! **level descending, ties oldest-registration-first**. Every frame in that order is *called*
-//! until one returns nonzero; that one **consumes** and both loops stop. So several frames may be
-//! called, at most one consumes.
-//!
-//! **The consumption gate is EXISTENCE, not handling** (`0x76b7d0`/`0x76bba0`/`0x76b760`, §3):
-//!
-//! | slot state | key-down returns | fires |
-//! |---|---|---|
-//! | `OnKeyDown` set | **consume** | `OnKeyDown` |
-//! | only `OnKeyUp` set | **consume** | *nothing* |
-//! | neither | decline | nothing |
-//!
-//! That asymmetry is real and is transcribed below: a frame carrying only an `OnKeyUp` swallows
-//! every key-down and runs no script. `OnChar` gates on its own slot alone; `OnKeyUp` on `+0x190`
-//! alone (no `OnKeyDown` fallback). **A 1.12 handler cannot signal "handled"** — the fire's return
-//! is discarded at all three call sites (§3.1) — so a Lua handler never influences consumption.
-//!
-//! **Bucket membership is the keyboard-enabled flag**, never the presence of a script (§3.2):
-//! `EnableKeyboard(true)` on a script-less frame puts it *in* the walk, where it is called and
-//! declines. XML `enableKeyboard` enables both kinds; an XML `<Scripts>` block auto-enables per
-//! handler; **Lua `SetScript` auto-enables nothing**, so a runtime-created frame needs an explicit
-//! `EnableKeyboard(true)` exactly as in the real client.
-//!
-//! ## Where the EditBox sits — it is a participant, not a separate stage
-//!
-//! The reference has no "editbox first" rule: `CSimpleEditBox` is a frame in the same buckets whose
-//! own vtable (`0x77b160` key-down / `0x77a900` char) consumes while focused and never chains to
-//! the base. Modelling it as a stage before or after the walk would get the order wrong whenever a
-//! keyboard frame and the focused box are in different strata — a TOOLTIP-strata frame really does
-//! pre-empt a focused HIGH-strata box, and a WORLD-strata one really does not. So [`walk`] visits
-//! the focused box **at its own strata/level**, handing it to the RF-0082 routing this crate
-//! already had ([`super::editbox`]) and taking a `true` as consumption.
-//!
-//! What is deliberately NOT re-derived here: the box's own focus acquisition (`autoFocus`
-//! self-acquire, click-to-focus, `SetFocus`) stays entirely in `editbox`, and an event no frame
-//! consumed still falls through to it — so every existing routing test holds unchanged.
-//!
-//! ## Not modelled, named
-//!
-//! The **sticky per-key-code key-up slot** (§2.1: `0x765fd0` routes key-up to `[root+code*4+0x84]`,
-//! the last frame that consumed *some* down for that code, and does **not** clear it on delivery)
-//! is not built: this engine's host feeds no key-up at all today. `OnKeyUp` is therefore accepted,
-//! stored, gated in the table above — and never fired. That is stated rather than hidden, because
-//! its one observable consequence is live: a frame with only an `OnKeyUp` still consumes key-downs.
+//! `OnKeyUp` is stored and gates key-downs but never fires: the host feeds no key-up, so the
+//! reference's key-up gate (`0x76bba0`, `OnKeyUp` alone) and its sticky per-code target
+//! (`0x765fd0`, `[root+code*4+0x84]`, the last frame to consume that code's down) are not built.
 
 use mlua::Lua;
 
 use super::{event, Model};
 use crate::widget::{FrameHandle, FrameKind};
 
-/// Which channel a dispatch is on — the two walks the reference registers separately.
+/// The two walks the reference registers separately.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Channel {
-    /// `0x765df0` — kind-0 buckets, vtable `+0x5c`, fires `OnChar` with the literal character.
+    /// `0x765df0`: kind-0 buckets, vtable `+0x5c`, fires `OnChar` with the literal character.
     Char,
-    /// `0x765f10` — kind-1 buckets, vtable `+0x60`, fires `OnKeyDown` with the key NAME.
+    /// `0x765f10`: kind-1 buckets, vtable `+0x60`, fires `OnKeyDown` with the key name.
     KeyDown,
 }
 
-/// The walk order (§2): every keyboard-enabled, effectively-visible frame, **strata descending,
-/// then level descending, then oldest registration first**.
-///
-/// Built as a sorted `Vec` per dispatch rather than kept as nine live buckets. The reference
-/// maintains the buckets incrementally because it is walking them on every key at 1.12 frame
-/// budgets; here a key press is a human-rate event and the candidate set is the *keyboard-enabled*
-/// frames only — single digits in any real interface — so an index that must be kept coherent with
-/// every Show/Hide/SetFrameLevel/SetFrameStrata would be pure drift surface for no measurable win.
-/// The ORDER is the law; the storage is ours.
+/// The walk order (`0x765f10`): keyboard-enabled, effectively-visible frames, strata TOOLTIP down
+/// to WORLD, then level descending, ties oldest registration first as the inserter keeps them
+/// (`0x764aa0`).
 fn walk_order(model: &Model) -> Vec<FrameHandle> {
     let mut candidates: Vec<(FrameHandle, u8, u16, u32)> = model
         .arena
@@ -87,38 +37,21 @@ fn walk_order(model: &Model) -> Vec<FrameHandle> {
         .filter(|(_, f)| f.effective_visible && f.keyboard_enabled)
         .map(|(h, f)| (h, f.strata as u8, f.level, f.insertion_seq))
         .collect();
-    // strata DESC, level DESC, insertion ASC — the inserter's own ordering (`0x764aa0`), where a
-    // frame goes before the first entry of strictly lower level and equal levels keep registration
-    // order.
     candidates.sort_by(|a, b| b.1.cmp(&a.1).then(b.2.cmp(&a.2)).then(a.3.cmp(&b.3)));
     candidates.into_iter().map(|(h, ..)| h).collect()
 }
 
-/// Does `frame` have a script bound under `name`?
-///
-/// The existence test the C++ gate performs on `+0x180`/`+0x188`/`+0x190` — asked of the script
-/// registry, which is where this engine keeps those slots.
+/// The gate's existence test on slots `+0x180`/`+0x188`/`+0x190`, kept in the script registry.
 fn has_script(lua: &Lua, id: u32, name: &str) -> bool {
     event::has_widget_handler(lua, id, name)
 }
 
-/// Is `h` a `CSimpleEditBox`?
-///
-/// **A box in the walk is asked about FOCUS, never about a script slot.** Its ctor (`0x779ce8`)
-/// registers it in the kind-0 *and* kind-1 buckets, and its vtable `0x81c910` **replaces** the base
-/// input slots — `+0x5c` → `0x77a900` (char), `+0x60` → `0x77b160` (key-down) — and never chains to
-/// them. wow-re `system/ui/scratch/frame-key-script-delivery.md` §3, at the bytes: *"There is no
-/// `call 0x76b760` anywhere in it, so the generic `OnChar` slot `+0x180` is unreachable on an
-/// editbox."* The override's own tail is the decline this predicate exists to reach:
-/// `0x77a952 cmp esi,eax` — I am the focus owner → insert and consume — else
-/// `0x77a956 xor eax,eax`, **return 0, and the walk continues past me**. `0x77b160` has the same
-/// shape at `0x77b1c7`/`0x77b21e`.
-///
-/// Without this, an unfocused box carrying an XML `<OnChar>` ran the base gate and **ate every
-/// keystroke aimed at its neighbours**: stock `SendMailNameEditBox` has one
-/// (`SendMailFrame_SendeeAutocomplete`) and is the first-registered keyboard frame in the mail
-/// window, so the send tab's subject, body and three money boxes took no input at all — the whole
-/// window typed dead except the one box the handler is on (decision 2145).
+/// Whether `h` is a `CSimpleEditBox`, which the walk asks about focus, never a script slot: its
+/// ctor (`0x779ce8`) puts it in both buckets, and its vtable `0x81c910` replaces the input slots
+/// (`+0x5c` with `0x77a900`, `+0x60` with `0x77b160`) without chaining to the base, consuming
+/// when focused and otherwise declining unless it takes a free focus as `autoFocus`
+/// (`0x77a952`/`0x77a956`, `0x77b1c7`/`0x77b21e`). So an unfocused box's `OnChar` (`+0x180`)
+/// never runs and never eats a neighbour's keys.
 fn is_editbox(lua: &Lua, h: FrameHandle) -> bool {
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     model
@@ -127,19 +60,15 @@ fn is_editbox(lua: &Lua, h: FrameHandle) -> bool {
         .is_some_and(|f| f.kind == FrameKind::EditBox)
 }
 
-/// The dispatcher for one channel — [`Channel`]'s walk, gate and fire, in the reference's order.
-///
-/// Returns whether the event was **consumed**, which is what the caller must use to suppress the
-/// keybinding system: consumption is decided by the C++ existence gate alone, never by what the
-/// Lua handler did or returned (§3.1).
+/// One channel's walk, gate and fire. Returns whether a frame consumed the event, which is what
+/// suppresses the keybinding; a handler's own return is discarded (`0x7026f0`).
 fn walk(lua: &Lua, channel: Channel, arg: &str) -> bool {
     let order = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         walk_order(&model)
     };
     for h in order {
-        // The focused EditBox consumes through its OWN vtable, never the base one — so it is asked
-        // in its walk position and its answer is final for this event.
+        // The focused box answers through its own vtable, at its walk position.
         let is_focused_box = {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             model.focused_editbox == Some(h)
@@ -154,10 +83,9 @@ fn walk(lua: &Lua, channel: Channel, arg: &str) -> bool {
             }
             continue;
         }
-        // Someone else holds the focus (or nothing does and this box is not `autoFocus`): the
-        // override returns 0 and the walk moves on. The base slot is unreachable here — see
-        // [`is_editbox`]. A no-focus self-acquire still happens, at [`super::editbox::route`],
-        // when the whole walk declines.
+        // An unfocused box declines here; the topmost `autoFocus` box takes a free focus in
+        // `super::editbox::route` once the whole walk declines, where the reference's takes it
+        // at its own walk position (`0x77a917`, `0x77b1c7`).
         if is_editbox(lua, h) {
             continue;
         }
@@ -173,7 +101,7 @@ fn walk(lua: &Lua, channel: Channel, arg: &str) -> bool {
                     return true;
                 }
             }
-            // `0x76b7d0`: the OR gate — either key slot consumes, only `OnKeyDown` fires.
+            // `0x76b7d0`: either key slot consumes, only `OnKeyDown` fires.
             Channel::KeyDown => {
                 let down = has_script(lua, id, "OnKeyDown");
                 if down || has_script(lua, id, "OnKeyUp") {
@@ -188,52 +116,40 @@ fn walk(lua: &Lua, channel: Channel, arg: &str) -> bool {
     false
 }
 
-/// Fire one key handler with its single string argument (`0x7026f0(frame, &slot, "%s", str)` — the
-/// argument is a string on all three channels). Errors land in [`Model::errors`] like every other
-/// widget handler; a raising handler must not eat the key press.
+/// Fire one key handler with its one argument, a string on all three channels (`0x7026f0`);
+/// errors are recorded in [`Model::errors`], never raised into the dispatch.
 fn fire(lua: &Lua, id: u32, script: &str, arg: &str) {
     let val = mlua::Value::String(match lua.create_string(arg) {
         Ok(s) => s,
         Err(e) => {
             lua.app_data_mut::<Model>()
                 .expect("model app_data")
-                .errors
-                .push(e.to_string());
+                .record_script_error(e.to_string());
             return;
         }
     });
     if let Err(e) = event::fire_widget_handler(lua, id, script, vec![val]) {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
 }
 
-/// The char channel (`0x765df0`) — `arg1` is the literal character, UTF-8 (§4.1: the code is
-/// UTF-8-encoded with no range guard, so a multi-byte codepoint arrives whole).
+/// The char channel (`0x765df0`): `arg1` is the character in UTF-8, a multi-byte codepoint whole
+/// (`0x41abb0` encodes with no range guard).
 pub(super) fn char_input(lua: &Lua, text: &str) -> bool {
     walk(lua, Channel::Char, text)
 }
 
-/// The key-down channel (`0x765f10`) — `arg1` is the key NAME, with no modifier prefix, from the
-/// same table the keybinding chord uses (§4.2). The host speaks those names already
-/// (`crate::script::UiScript::key_input`'s contract), so no decode happens here.
+/// The key-down channel (`0x765f10`): `arg1` is the key name without modifiers, from the same
+/// table as the keybinding chord (`0x76b7d0`, `0x4b66b0`); the host already speaks those names.
 pub(super) fn key_input(lua: &Lua, key: &str) -> bool {
     walk(lua, Channel::KeyDown, key)
 }
 
-/// The same key-down walk, for the keys this engine delivers to a **focused EditBox as a semantic
-/// [`crate::script::EditAction`] chord** rather than by name — BACKSPACE, DELETE, the arrows, HOME,
-/// END (decision 0301: the host's per-OS keymap owns which chord means what, so the box never sees
-/// these as names).
-///
-/// Those keys still have to reach a keyboard frame — a dialog you type into needs its BACKSPACE —
-/// and the ordering question that creates is real: whoever comes FIRST in the walk owns the key.
-/// So this runs the identical order and **declines at the focused box** rather than skipping past
-/// it: a frame above the box in walk order consumes and fires; a box above the frame ends the walk
-/// with `false`, and the caller then dispatches its chord exactly as before. The one thing this
-/// must never do is let a frame *below* the focused box steal the box's editing keys.
+/// The key-down walk for the editing keys a focused box takes as a [`crate::script::EditAction`]
+/// (BACKSPACE, DELETE, the arrows, HOME, END): a frame above the box consumes them, and the walk
+/// stops at the box with `false` for its chord path, so no frame below it takes them.
 pub(super) fn frame_key_input(lua: &Lua, key: &str) -> bool {
     let order = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -243,11 +159,10 @@ pub(super) fn frame_key_input(lua: &Lua, key: &str) -> bool {
         {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             if model.focused_editbox == Some(h) {
-                return false; // the box owns this key; its chord path handles it
+                return false; // the box's chord path owns this key
             }
         }
-        // …and an UNfocused box declines instead of gating on `+0x188`/`+0x190` ([`is_editbox`]),
-        // so it can never steal a neighbour's BACKSPACE either.
+        // An unfocused box declines rather than gating on `+0x188`/`+0x190`.
         if is_editbox(lua, h) {
             continue;
         }
diff --git a/crates/benilla-ui/src/script/layout.rs b/crates/benilla-ui/src/script/layout.rs
index 3ea50794..b8faa294 100644
--- a/crates/benilla-ui/src/script/layout.rs
+++ b/crates/benilla-ui/src/script/layout.rs
@@ -8,52 +8,22 @@ use super::backdrop;
 use super::types::RegionData;
 use super::{ExtractedQuad, MeasureRequest, Model, QuadContent, UiScript, SCREEN};
 
-/// The paint a frame slot's derived quads inherit — its `effective_alpha` and `effective_scale`
-/// travelling together (backdrop pieces and message-frame ring lines are emitted BY the frame,
-/// so they wear the frame's own factors exactly like [`ExtractedQuad::alpha`]/`scale` on the
-/// slot itself).
+/// A frame's `effective_alpha` and `effective_scale`, worn by the quads it emits itself.
 #[derive(Clone, Copy)]
 pub(super) struct FramePaint {
     pub(super) alpha: f32,
     pub(super) scale: f32,
 }
 
-/// A 128-bit rolling fingerprint of everything [`UiScript::resolve_layout`] *reads*, so a resolve
-/// whose inputs are byte-identical to the last one can be skipped outright.
-///
-/// ## Tier 2 of a two-tier gate (decision 0740)
-///
-/// This fingerprint began as the WHOLE gate, chosen over a dirty flag because a flag has sites to
-/// miss and a fingerprint is computed FROM the read set — any change moves it by construction.
-/// That safety cost ~0.6 ms *every idle frame* at a live pin (hashing ~2k inputs to conclude
-/// "quiet"), which is why the mutation epoch ([`Model::touch_layout`], tier 1) now sits in front:
-/// a frame with no layout-visible write skips at a `u64` compare and never reaches this hash. The
-/// fingerprint remains load-bearing where the flag is structurally weak — a *dirty* frame whose
-/// writes were idempotent (the bag-hover re-enter loop clears and rebuilds identical content
-/// every frame; the GameTooltip pre-pass rewrites tooltip sizes every call) hashes clean here and
-/// still skips the solve. And the flag's own failure mode — a missed touch site, a silently stale
-/// layout — is machine-checked: under [`layout_verify_enabled`] (forced on in this crate's tests)
-/// a tier-1-quiet frame asserts the fingerprint agrees, so the tiers police each other.
-///
-/// ## Why 128 bits
-///
-/// A collision here is not self-healing: the skip keeps the stored value, so a colliding change
-/// would stay unresolved until something *else* moved. Two independent lanes put that beyond
-/// physical concern (~2^-128 per frame) at the cost of one extra multiply per item.
-///
-/// ## Order sensitivity is safe
-///
-/// The accumulator is order-dependent, and it is fed by walking `HashMap`s whose iteration order
-/// is arbitrary. That order is nevertheless *stable for an unmutated map*, so an unchanged model
-/// reproduces the value; a mutated map may reorder and merely re-resolves. The failure mode is a
-/// false DIRTY (a wasted resolve), never a false CLEAN (a stale rect).
+/// A 128-bit fingerprint of what [`UiScript::resolve_layout`] reads: tier 2 of the change gate,
+/// behind the mutation epoch ([`Model::touch_layout`]). Two lanes, as a collision keeps a stale
+/// rect; fed in `HashMap` order, stable for an unmutated map, so a reorder only costs a resolve.
 #[derive(Clone, Copy, PartialEq, Eq)]
 pub(crate) struct InputFingerprint(u64, u64);
 
 impl Default for InputFingerprint {
     fn default() -> Self {
-        // Distinct non-zero bases (FNV-1a's, and a 64-bit mix constant) so leading zero-valued
-        // items still move both lanes.
+        // Non-zero bases (FNV-1a's and a mix constant), so leading zeros still move both lanes.
         InputFingerprint(0xcbf2_9ce4_8422_2325, 0x9e37_79b9_7f4a_7c15)
     }
 }
@@ -67,8 +37,7 @@ impl InputFingerprint {
 
     #[inline]
     fn f32(&mut self, v: f32) {
-        // Bit pattern, not value: `resolve` is bit-exact float math, so -0.0 and NaN payloads are
-        // distinctions that matter here even where `==` would call them equal (or unequal).
+        // Bit pattern, not value: the solve is bit-exact, so -0.0 and NaN payloads are distinct.
         self.feed(u64::from(v.to_bits()));
     }
 
@@ -95,9 +64,7 @@ impl InputFingerprint {
         self.f32(i.extent_y);
     }
 
-    /// Collapse to the single `u64` [`LayoutScope`] compares per node. Never [`NO_NODE`]: a
-    /// present node reading as *absent* would be a false CLEAN — the one direction that ships a
-    /// stale rect rather than a wasted resolve.
+    /// The per-node `u64`; never [`NO_NODE`], or a present node would read as absent.
     #[inline]
     fn finish(self) -> u64 {
         let h = self.0 ^ self.1.rotate_left(32);
@@ -117,18 +84,10 @@ impl InputFingerprint {
     }
 }
 
-/// The sentinel in [`LayoutScope::last`]/`now` for "this id was not in that pass's graph". A real
-/// hash colliding with it costs a spurious DIRTY (a node re-solved for nothing), never a stale
-/// rect — the same one-sided failure the fingerprint above is built on.
+/// The sentinel in [`LayoutScope::last`] and `now` for an id not in that pass's graph.
 const NO_NODE: u64 = 0;
 
-/// One FRAME's per-node input hash — [`LayoutScope::last`]'s currency.
-///
-/// Factored out (decision 1388) because two paths now compute it: the full derive, over every
-/// frame, and the incremental pass, over the handful a write named. They must agree *bit for bit* —
-/// a hash that differs by path would read as a change on the frame the paths swap, and (worse) as
-/// no-change on the frame they swap back. One function is the only way to make that true by
-/// construction rather than by matching two listings by eye.
+/// A frame's per-node hash; the full derive and the incremental pass must agree bit for bit.
 #[inline]
 fn frame_node_hash(input: &LayoutInput, over: Option<Anchor>) -> u64 {
     let mut node = InputFingerprint::default();
@@ -140,8 +99,7 @@ fn frame_node_hash(input: &LayoutInput, over: Option<Anchor>) -> u64 {
     node.finish()
 }
 
-/// One REGION's per-node input hash — [`frame_node_hash`]'s twin, over the three things the sweep
-/// reads out of `RegionData`: its anchors, its explicit size, and its measured text extent.
+/// A region's per-node input hash: its anchors, explicit size and measured text extent.
 #[inline]
 fn region_node_hash(data: &RegionData) -> u64 {
     let mut node = InputFingerprint::default();
@@ -160,11 +118,8 @@ fn region_node_hash(data: &RegionData) -> u64 {
         }
         None => node.feed(u64::MAX),
     }
-    // **The ART, on a region whose rect is derived from it** (decision 1349): an axis authored `0`
-    // takes its span from the content ([`content_span`]), so swapping the texture on such a region
-    // MOVES it and the node must re-hash. Fed only on that shape — a sized region's art cannot
-    // change its rect, and hashing every icon path would put a string walk in the derive's hot loop
-    // for a fact with no reader.
+    // The art, only where an axis authored 0 takes its span from it (`content_span`): a new
+    // texture moves such a region, while a sized region's art cannot move its rect.
     if !data.anchors.is_empty() && data.size.is_none_or(|(w, h)| w == 0.0 || h == 0.0) {
         node.feed(data.fill.is_some() as u64);
         match &data.texture {
@@ -180,25 +135,10 @@ fn region_node_hash(data: &RegionData) -> u64 {
     node.finish()
 }
 
-/// A region's **content-derived span**, in FrameXML units — the client's virtual size getters,
-/// which the resolver calls instead of reading a stored width/height (wow-re
-/// `region-size-fallback.md` §1/§2, decision 1349).
-///
-/// `CSimpleTexture::GetWidth 0x770720` returns the authored value only when it is **not exactly
-/// `0.0`**; on `0.0` with a texture loaded it returns the texture's own texel extent, through
-/// bit-for-bit the same converter the `<AbsDimension>` attribute uses — so **one texel is one
-/// FrameXML unit, at every aspect ratio**. `0x770790` is the identical body for height. The
-/// colour form generates an **8×8** surface (`0x770360` → `0x44a900` stamps
-/// `[tex+0x144] = [tex+0x148] = 8`), so a `<Color>`-only texture spans 8 units.
-///
-/// `None` = nothing to measure (no art, or no host oracle to measure it with), and the caller
-/// leaves the axis at zero — which is the client's answer too when a texture has no `CGxTex*`
-/// at all.
-///
-/// This is the TEXTURE half. A `CSimpleFontString`'s span is derived the same way and lives in
-/// the sweep itself, because it needs the measure the sweep already folds in
-/// ([`FONTSTRING_MIN_SPAN`]). Between them they are what let the owner-edge fallback go
-/// (decision 1664): a region's span comes from its content, never from the frame it hangs on.
+/// A texture's content-derived span in FrameXML units. `CSimpleTexture::GetWidth` (`0x770720`,
+/// height `0x770790`) returns the authored value unless it is exactly 0.0, else the texel extent
+/// through the `<AbsDimension>` converter, so one texel is one unit; a `<Color>` texture spans 8.
+/// `None` when there is nothing to measure: the axis stays 0, as in the reference with no texture.
 pub(super) fn content_span(
     data: &RegionData,
     probe: Option<&crate::script::TextureSizeProbe>,
@@ -209,9 +149,7 @@ pub(super) fn content_span(
     texel_span(probe, data.texture.as_deref()?)
 }
 
-/// [`content_span`]'s texture arm, for a caller holding a path rather than a region — the
-/// SimpleHTML flow reservation, which asks the reference's `GetHeight` override the same way
-/// (`simplehtml-markup-engine.md` §7 step 6).
+/// [`content_span`] for a path: SimpleHTML reserves an image's height the same way (`0x770790`).
 pub(super) fn texel_span(
     probe: Option<&crate::script::TextureSizeProbe>,
     path: &str,
@@ -220,116 +158,61 @@ pub(super) fn texel_span(
     Some((w as f32, h as f32))
 }
 
-/// The edge of the surface `CSimpleTexture::SetTexture(const CImVector*)` generates for the colour
-/// form — 64 texels, `0x44a900` stamping `[tex+0x144] = [tex+0x148] = 8` (decision 1349 §1).
+/// The edge of the 8×8 surface the colour `SetTexture` makes (`0x770360`, sized by `0x44a900`).
 const SOLID_TEXTURE_TEXELS: f32 = 8.0;
 
-/// The floor under a **FontString's** derived span, in FrameXML units —
-/// `CSimpleFontString::GetWidth 0x772930` / `GetHeight 0x772a60` end
-/// `fld 1-unit; fcomp candidate; test ah,0x5; jp` and return the floor when the candidate is
-/// smaller (wow-re `region-size-fallback.md` §3, `tooltip-blank-line-height.md` §3). One unit,
-/// not one line: the reference's own blank tooltip spacer is `" \n"` — a real one-line string —
-/// and this floor is what a *genuinely* empty string reads back as, never `0.0`.
+/// The floor under a FontString's derived span: `CSimpleFontString::GetWidth` (`0x772930`, height
+/// `0x772a60`) returns at least one FrameXML unit, not one line, so empty text reads back 1, not 0.
 pub(super) const FONTSTRING_MIN_SPAN: f32 = 1.0;
 
-/// [`LayoutScope::node_of`] holds one roster index per id, and the two rosters are separate
-/// (`plan` for frames, `regions` for regions) — this bit says which one. Node counts run in the
-/// thousands, so the top bit is free forever.
+/// Marks a [`LayoutScope::node_of`] index as one into `regions` rather than `plan`.
 const REGION_TAG: u32 = 0x8000_0000;
 
-/// Per-node layout scope — the state that lets a resolve touch only what MOVED (decision 1350,
-/// the phase 2 decision 0771 left open).
-///
-/// 0771 halved the per-content-change cost by folding two whole-UI solves into one; it also said
-/// plainly that halving it was not fixing it, because *one* solve is still a fixpoint over every
-/// frame and every region for a change that touches ten FontStrings inside one frame. Two later
-/// correctness fixes then tripled what a region costs — `0dd6a559a` (a region whose owner has no
-/// rect resolves from its own anchors) and 1310 (every anchor-less Texture/FontString gets
-/// implicit anchors at creation) each moved a large population out of the sweep's cheap
-/// `continue` and into full resolution. Neither is wrong; both are why the whole-UI shape had to
-/// go.
-///
-/// Everything here is indexed **densely by layout id** — frames and regions are minted from one
-/// monotonic counter (`Model::next_id`), so a single array covers both, and the solver's own rect
-/// array is indexed the same way.
-///
-/// Nothing in here allocates on a steady frame: every buffer is resized once and refilled.
+/// Per-node layout scope, so a resolve touches only what moved. Indexed densely by layout id, as
+/// frames and regions share one counter (`Model::next_id`); nothing allocates on a steady frame.
 #[derive(Default)]
 pub(crate) struct LayoutScope {
-    /// Per id: the input hash the last CONVERGED resolve saw, [`NO_NODE`] if the id was not in
-    /// that graph. A mismatch is a dirty SEED — and a birth is a mismatch for free.
+    /// Per id: the hash the last converged resolve saw, or [`NO_NODE`]; a mismatch seeds dirty.
     last: Vec<u64>,
-    /// How many ids `last` holds a real hash for. Compared against how many of THIS pass's nodes
-    /// were also in the last graph: a shortfall means a node DIED, whose dependents we can no
-    /// longer enumerate (its edges died with it), so that pass falls back to full scope.
+    /// How many ids `last` holds a hash for; a pass matching fewer lost a node: full scope.
     last_count: usize,
-    /// The screen rect the `last` set was hashed under. It is every clamped frame's extent and the
-    /// root of every chain, so a move is a full-scope event.
+    /// The screen `last` was hashed under, every chain's root, so a move is full scope.
     last_screen: Option<Rect>,
     /// This pass's hash per id (parallel to `last`); swapped into `last` on convergence.
     now: Vec<u64>,
     /// Per id: index into this pass's node roster, or [`u32::MAX`].
     node_of: Vec<u32>,
-    /// Per id: head index into `dep_to`/`dep_next` of the nodes that DEPEND on it, or
-    /// [`u32::MAX`]. An intrusive list rather than a CSR so the edges are built in one walk.
+    /// Per id: the head of its dependents' list in `dep_to`/`dep_next`, or [`u32::MAX`].
     dep_head: Vec<u32>,
     dep_to: Vec<u32>,
     dep_next: Vec<u32>,
-    /// Edge slots freed by [`Self::retarget`], for [`Self::edge`] to reuse. Without it a session
-    /// of hovers would grow `dep_to` by one entry per retarget forever — bounded only by the next
-    /// full derivation, which is exactly the event retargeting exists to avoid.
+    /// Edge slots [`Self::retarget`] freed, for [`Self::edge`] to reuse rather than grow `dep_to`.
     dep_free: Vec<u32>,
     /// Per id: in the dirty closure.
     dirty: Vec<bool>,
     /// The closure's worklist.
     stack: Vec<u32>,
-    /// The frame roster this cached graph describes: `(handle, id, ScrollFrame anchor override)`,
-    /// indexed by [`Self::node_of`] (decision 1388).
-    ///
-    /// It holds no borrow of `layout_inputs`, and that is the whole point. The borrowed form 1350
-    /// introduced had to be rebuilt every call, which forced the *derivation* — the ids walk, the
-    /// scroll map, the liveness retain, and the two hash sweeps — to be rebuilt with it: ~1.5 ms of
-    /// whole-roster work per mutated frame, whatever moved. Owning the row instead lets the roster
-    /// outlive the call, and the `layout_inputs` probe it replaces moves to the round loop, where it
-    /// is paid once per frame *this solve actually touches* instead of once per frame in the UI.
+    /// The cached frame roster, `(handle, id, ScrollFrame anchor override)`, kept across resolves.
     plan: Vec<(FrameHandle, u32, Option<Anchor>)>,
-    /// The anchored-region roster — [`Self::plan`]'s twin, and the bigger of the two by a factor of
-    /// three (10,438 anchored regions against 3,218 frames at the Stormwind pin).
+    /// The cached roster of live, anchored regions.
     regions: Vec<RegionRow>,
-    /// An incremental pass's staged [`Self::last`] writes, `(id, hash)`. Applied only on
-    /// convergence, for the reason [`Self::commit`] is: a pass left mid-flight describes a graph
-    /// that never settled, and adopting its hashes would seed the next pass's
-    /// "unchanged ⇒ unmoved" argument from a lie.
+    /// An incremental pass's `(id, hash)` writes to [`Self::last`], applied only on convergence.
     staged: Vec<(u32, u64)>,
 }
 
-/// One anchored, live region as the round loop consumes it — resolved ONCE per *derivation*
-/// instead of re-derived per call (decision 1350) or per round (before it). Before this list the
-/// sweep walked `region_data` itself every round and paid, per region per round, an `arena.region`
-/// probe for liveness/owner/kind and a `region_to_id` probe to publish the result — and it paid
-/// them for the anchor-less entries too, which it then `continue`d past.
-///
-/// It is also the addressable form the scope needs: a dirty set is a list of INDICES into this,
-/// and "sweep only what moved" is `for &i in sweep { … regions[i] … }`.
-///
-/// 1388 took the `&RegionData` borrow back out of it, which is what lets the roster outlive the
-/// call that built it. The sweep re-probes `region_data` for that half — one lookup per region
-/// *swept* rather than one per region in the UI.
+/// One live, anchored region as the round loop consumes it, built once per derivation.
 #[derive(Clone, Copy)]
 struct RegionRow {
     rh: RegionHandle,
-    /// The layout id — the solver's dense array index, and the scope's node key.
+    /// The layout id: the solver's array index and the scope's node key.
     id: u32,
-    /// The owning frame: supplies the fallback edges for the axes this region's own anchors do
-    /// not pin, and is therefore a layout DEPENDENCY of it.
+    /// The owning frame, which supplies the region's scale and so is a layout dependency.
     owner: FrameHandle,
     is_fontstring: bool,
 }
 
 impl LayoutScope {
-    /// Grow every per-id array to cover `n` ids and reset the per-pass ones, ahead of deriving the
-    /// graph from scratch. `last` keeps its contents (it is the memory of the previous converged
-    /// pass); everything else — the roster, the edges, `node_of` — is about to be rebuilt.
+    /// Size the per-id arrays for `n` ids and clear all but `last`, ahead of a full derivation.
     fn begin_full(&mut self, n: usize) {
         self.last.resize(n, NO_NODE);
         self.now.clear();
@@ -349,10 +232,7 @@ impl LayoutScope {
         self.staged.clear();
     }
 
-    /// The incremental entry (decision 1388): the roster, the edges and `node_of` ARE the cached
-    /// graph and must survive; only the per-pass dirty marks are scratch. This is the whole saving
-    /// — `begin_full`'s six resizes and the four whole-roster walks that refill them are what a
-    /// mutated frame used to pay to rediscover a graph that had not changed shape.
+    /// The incremental entry: the cached graph survives, and only the dirty marks reset.
     fn begin_incremental(&mut self) {
         self.dirty.clear();
         self.dirty.resize(self.node_of.len(), false);
@@ -360,21 +240,18 @@ impl LayoutScope {
         self.staged.clear();
     }
 
-    /// Is `id` a node of the cached graph? The precondition every precise touch site
-    /// ([`Model::touch_layout_region`]) has to satisfy before it may name a node instead of
-    /// invalidating the cache.
+    /// Whether `id` is a node of the cached graph, the only kind a precise touch may name.
     pub(crate) fn has_node(&self, id: u32) -> bool {
         self.node_of
             .get(id as usize)
             .is_some_and(|&n| n != u32::MAX)
     }
 
-    /// Record that node `from` reads `to`'s rect — so a change at `to` reaches `from`.
+    /// Record that node `from` reads `to`'s rect, so a change at `to` reaches `from`.
     #[inline]
     fn edge(&mut self, from: u32, to: u32) {
         let Some(head) = self.dep_head.get_mut(to as usize) else {
-            return; // an anchor to an id this pass has no node for (the screen root, a dead
-                    // target): it cannot become dirty, so it constrains nothing.
+            return; // an id with no slot can never turn dirty, so it constrains nothing
         };
         let e = match self.dep_free.pop() {
             Some(e) => {
@@ -392,31 +269,9 @@ impl LayoutScope {
         *head = e;
     }
 
-    /// Re-point node `id`'s outgoing edges after an anchor RETARGET — the write 1388 had to
-    /// classify as structural and answer with a whole-graph derivation.
-    ///
-    /// 1388's reasoning was that "an edge has to disappear and another to appear, and no per-node
-    /// hash can say so, so the cached graph must be thrown away". The first half is true and the
-    /// second does not follow: the write site knows both edge sets, because a node's outgoing
-    /// edges ARE its anchor targets (see the derive's two `scope.edge` loops). What it could not
-    /// do was *say* so — this is the vocabulary that was missing, not a cost that was unavoidable.
-    ///
-    /// It matters because the hottest retarget in the client is `GameTooltip:SetOwner`, which
-    /// re-points the plate at the button under the cursor: every bag slot and every spellbook
-    /// button crossed in a hover sweep was re-deriving the whole roster.
-    ///
-    /// `old`/`new` are the node's FULL anchor-target lists, before and after the write — not the
-    /// one that moved. That is what makes duplicates exact: a node with two anchors onto the same
-    /// target has two edges, and removing one per old entry leaves precisely the right count.
-    ///
-    /// Returns `false` when it cannot do this safely and the caller must fall back to the
-    /// conservative touch. Removing an edge is the only direction that can be WRONG (a missing
-    /// edge under-dirties, and under-dirtying ships a stale rect), so every uncertainty is
-    /// resolved by refusing: an id the cached graph has no node for, or a frame whose edges come
-    /// from a ScrollFrame override rather than from its own anchors (the derive does not consult
-    /// the authored anchors at all in that case). An old target with no edge to remove is NOT an
-    /// uncertainty — `edge` silently drops an anchor onto an id this pass has no node for, so its
-    /// absence is the expected shape, and skipping it removes nothing that exists.
+    /// Re-point node `id`'s outgoing edges after an anchor retarget. `old` and `new` are its full
+    /// anchor-target lists, so duplicate anchors stay exact. `false` means a conservative touch:
+    /// `id` has no node, or a ScrollFrame override, not its anchors, supplies its edges.
     pub(crate) fn retarget(&mut self, id: u32, old: &[u32], new: &[u32]) -> bool {
         let Some(&n) = self.node_of.get(id as usize) else {
             return false;
@@ -436,9 +291,7 @@ impl LayoutScope {
         true
     }
 
-    /// Unlink ONE `to → from` edge, if the list holds one. The lists are short by construction
-    /// (a node's dependents), and even a hub's is walked in microseconds against the ~1.3 ms
-    /// derivation this is replacing, so no bound is imposed on the walk.
+    /// Unlink one `to → from` edge, if the list holds one.
     fn unlink_edge(&mut self, to: u32, from: u32) {
         let Some(&head) = self.dep_head.get(to as usize) else {
             return;
@@ -472,8 +325,7 @@ impl LayoutScope {
         }
     }
 
-    /// Close the dirty set under "depends on": everything that reads a dirty node's rect, and
-    /// everything that reads *those*, must resolve again too.
+    /// Close the dirty set under "depends on": whatever reads a dirty rect, transitively.
     fn close(&mut self) {
         while let Some(id) = self.stack.pop() {
             let mut e = self.dep_head[id as usize];
@@ -485,8 +337,7 @@ impl LayoutScope {
         }
     }
 
-    /// Everything present is dirty — the fallback for the structural cases a per-node diff cannot
-    /// speak about (a death, a screen move, the first pass, a graph left mid-flight by a cycle).
+    /// Mark every node dirty, for what a per-node diff cannot see (a death, a screen move).
     fn dirty_all(&mut self) {
         for (id, &n) in self.node_of.iter().enumerate() {
             if n != u32::MAX {
@@ -502,11 +353,8 @@ impl LayoutScope {
         self.last_screen = Some(screen);
     }
 
-    /// [`Self::commit`] for an incremental pass: only the nodes it re-hashed moved, so only their
-    /// slots in `last` are rewritten. `last_count` and `last_screen` are untouched by
-    /// construction — a node entering or leaving the graph, and the screen moving, are structural
-    /// events, and a structural event never reaches this path (it lands in the conservative
-    /// `Model::layout_touched = None`).
+    /// [`Self::commit`] for an incremental pass: only the re-hashed slots. `last_count` and
+    /// `last_screen` stay, since a structural change always takes the full path.
     fn commit_incremental(&mut self) {
         for &(id, h) in &self.staged {
             self.last[id as usize] = h;
@@ -514,15 +362,12 @@ impl LayoutScope {
         self.staged.clear();
     }
 
-    /// Forget it: the next resolve must derive the graph and run in full scope. Called wherever a
-    /// pass leaves the rects mid-flight (the cycle bail), because the memory would then describe a
-    /// graph that never settled.
+    /// Forget the memory, so the next resolve derives the graph in full scope.
     pub(crate) fn invalidate(&mut self) {
         self.last_count = 0;
         self.last_screen = None;
         self.last.clear();
-        // The roster and `node_of` go with it: `has_node` is the precise touch sites' licence to
-        // name a node, and it must not outlive the memory that makes naming meaningful.
+        // The roster and `node_of` too: `has_node` must not vouch for a node the memory forgot.
         self.plan.clear();
         self.regions.clear();
         self.node_of.clear();
@@ -530,73 +375,45 @@ impl LayoutScope {
     }
 }
 
-/// `WOW_LAYOUT_VERIFY=1` — the change gate's self-check (decision 0022's instruments-first
-/// posture). When set, a resolve the gate wants to SKIP runs in full anyway and asserts it
-/// reproduced the previous rects exactly; a divergence means the fingerprint's read set is
-/// incomplete, and it fails loudly at the resolve that proves it rather than silently rendering a
-/// stale frame days later. It also checks tier 1 against tier 2: a frame the epoch judged quiet
-/// whose fingerprint nevertheless moved names a mutation path missing its `touch_layout()`.
-///
-/// This is what makes the gates' central claims — "the fingerprint covers everything the rounds
-/// read" and "every fingerprint-visible write bumps the epoch" — machine-checked instead of
-/// argued: it is FORCED ON for this crate's own tests, so every UI test (the shipped windows,
-/// driven through real FrameXML + Lua) is a standing probe for a missed input or a missed touch;
-/// set the env to extend that to a live run or another crate's suite. Read once; when off it
-/// costs a relaxed atomic load per resolve.
-/// `WOW_LAYOUT_PROF=1` — per-solve shape reporting (see the read site in [`UiScript::resolve_layout`]).
-/// Read once; off, it costs one relaxed atomic load per resolve and no clock reads at all.
+/// `WOW_LAYOUT_PROF=1`: the per-solve `[layout-prof]` and `[layout-pre]` lines on stderr.
 fn layout_prof_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_LAYOUT_PROF").as_deref() == Ok("1"))
 }
 
+/// `WOW_LAYOUT_VERIFY=1`, on in this crate's tests: every shortcut of the resolve (a gate skip, a
+/// tier-1-quiet frame, an incremental pass, the measure ledger) is checked against the full answer.
 fn layout_verify_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| cfg!(test) || std::env::var("WOW_LAYOUT_VERIFY").as_deref() == Ok("1"))
 }
 
-/// `WOW_LAYOUT_PROF=1`'s **preamble** split — the `[layout-pre]` line, one per LET-THROUGH resolve.
-///
-/// `[layout-prof]` reports the rounds, which 1350 already made proportional to what moved. This
-/// reports everything *before* them: the fixed whole-roster work every let-through solve pays
-/// whatever moved, which 1383 priced at ~1.9 ms/solve at a live roster and named as the next cut
-/// without ever splitting it. A cut needs to know which of the eight walks it is buying back, so
-/// the split is the instrument that has to exist first.
-///
-/// Off (the default) it takes no clock reads at all — [`Self::lap`] returns on the `on` test, so an
-/// unprofiled resolve pays one bool check per phase.
+/// `WOW_LAYOUT_PROF=1`'s `[layout-pre]` line: µs per preamble phase, per resolve past tier 1.
 #[derive(Default)]
 struct PreambleProf {
     on: bool,
     last: Option<std::time::Instant>,
-    /// The GameTooltip auto-size pre-pass (`layout_tooltips`) — a whole-frame-roster filter.
+    /// The GameTooltip auto-size pre-pass (`layout_tooltips`).
     tooltip: u128,
-    /// `OnSizeChanged`'s "before" snapshot — a whole-`scripts`-map filter.
+    /// `OnSizeChanged`'s "before" snapshot.
     watched: u128,
-    /// The ids rebuild + the per-frame scale/clamp sync into `layout_inputs`.
+    /// The ids rebuild and the scale and clamp sync into `layout_inputs`.
     ids: u128,
-    /// The ScrollFrame override map — another whole-frame-roster walk.
+    /// The ScrollFrame override map.
     scroll: u128,
     /// `region_resolved`'s liveness retain.
     retain: u128,
-    /// The per-call solve plan rebuild.
+    /// Never set, so always 0: the frame roster is built inside `fp_frames`.
     plan: u128,
-    /// `LayoutScope::begin` — seven per-id `Vec`s cleared/resized.
+    /// `LayoutScope::begin_full`.
     begin: u128,
-    /// The fingerprint + scope walk over every live FRAME (double-hashed: aggregate + per-node).
+    /// The fingerprint and scope walk over every live frame.
     fp_frames: u128,
-    /// The same over every anchored REGION — the biggest roster (10,438 anchored at the SW pin,
-    /// and by far the biggest single phase: 0.45–1.0 ms of the ~1.0–1.4 ms walk).
+    /// The same over every anchored region.
     fp_regions: u128,
-    /// The INCREMENTAL pass's whole preamble (decision 1388): re-hash the nodes the ledger named,
-    /// seed the ones that moved, close. Every phase above is zero on such a pass, and this is what
-    /// replaced them — read the two side by side to see what a derivation costs.
+    /// An incremental pass's whole preamble: re-hash the named nodes, seed the moved ones, close.
     seed: u128,
-    /// Was this an incremental pass? Reported as its own flag rather than inferred from
-    /// `seed != 0`, which is what it was first written as — and which read `incr=0` on every
-    /// incremental frame of the shipped UI, because the work it times rounds to under a
-    /// microsecond. An instrument that says "this never happens" about the path it was built to
-    /// measure is worse than no instrument.
+    /// A flag of its own, since `seed` rounds to 0 µs on most incremental passes.
     incremental: bool,
 }
 
@@ -620,9 +437,7 @@ impl PreambleProf {
             .map_or(0, |t| now.duration_since(t).as_micros())
     }
 
-    /// One line per let-through resolve, printed once the gate's verdict is known — `skips=1` is
-    /// the walk that concluded "nothing moved" and returns without solving, which costs the same
-    /// preamble as one that does.
+    /// Print the line once the gate's verdict is known; `skips=1` returned without solving.
     fn report(&self, skips: bool, frames: usize, regions: usize) {
         if !self.on {
             return;
@@ -657,17 +472,10 @@ impl PreambleProf {
     }
 }
 
-/// `OnSizeChanged`'s "after": turn the entry-vs-now diff of the watched frames into queued
-/// `(id, width, height)` fires ([`Model::pending_size_changed`]).
-///
-/// The gate is [`crate::layout::size_changed`] — the byte-verified `ApplyRect 0x76b580` test
-/// (`|Δwidth| ≥ ε ∨ |Δheight| ≥ ε`, `ε = _DAT_008029d4`), not a plain `!=`, so a rect that merely
-/// *moved* never fires and a sub-ε float wobble never does either.
-///
-/// A frame with no rect at entry is compared against the ZERO rect, which is the client's own
-/// starting state (`CSimpleFrame`'s ctor zeroes the cached rect, so the first `ApplyRect` is a
-/// 0×0 → w×h change and does fire). A frame that LOSES its rect queues nothing: no rect was
-/// applied, so the reference had no `ApplyRect` to fire from.
+/// `OnSizeChanged`'s "after": queue `(id, width, height)` for each watched frame whose size moved
+/// by the `ApplyRect 0x76b580` test ([`crate::layout::size_changed`], `ε = _DAT_008029d4`), so a
+/// pure move never fires. A frame with no rect at entry compares against the zero rect
+/// `CSimpleFrame`'s ctor leaves; one that loses its rect had no `ApplyRect` and fires nothing.
 fn queue_size_changes(
     watched: &[(FrameHandle, Option<Rect>)],
     resolved: &HashMap<FrameHandle, Rect>,
@@ -690,40 +498,19 @@ fn queue_size_changes(
 }
 
 impl UiScript {
-    /// [`UiScript::resolve`]'s body, taking `&mut Model` directly rather than `&mut self` — so a
-    /// Lua binding holding only a `Model` borrow (via `lua.app_data_mut`, no `&Lua`-wrapping
-    /// `UiScript` in scope) can force a fresh resolve too. [`scrollframe`]'s `UpdateScrollChildRect`
-    /// is the motivating caller: it fires `OnScrollRangeChanged` with the CURRENT range, but
-    /// "current" was a lie for its own primary use (the Era idiom of resize-then-notify in one
-    /// script tick) as long as it only read the LAST full [`UiScript::resolve`]'s cached rects —
-    /// those don't yet reflect a `SetHeight` earlier in the SAME tick (Lua runs before the app's own
-    /// per-frame `resolve()`, `ui_script/mod.rs`'s drive loop), so the fired range was one tick
-    /// stale on every "just resized, tell the scrollbar" call — precisely when a caller most needs
-    /// it fresh. Cheap to call on demand: the fixpoint early-exits in one round on a quiet graph
-    /// (this function's own doc).
+    /// [`UiScript::resolve`]'s body on a bare `Model`, so a Lua binding can force a fresh resolve,
+    /// as `UpdateScrollChildRect` must report a range reflecting a same-tick `SetHeight`.
     pub(super) fn resolve_layout(model: &mut Model) {
         Self::resolve_layout_inner(model);
         if !model.layout_verify_recheck {
             return;
         }
-        // ── `WOW_LAYOUT_VERIFY`: the incremental pass's falsifier (decision 1388) ─────────────
-        // The pass just taken seeded its dirty closure from a LEDGER of named nodes rather than
-        // from a fresh derivation, and it reused a roster and an edge set built some frames ago.
-        // Two things can be wrong with that and neither is visible from inside it: a write that
-        // moved a node's inputs without naming it, and a write that changed an anchor's TARGET
-        // while claiming to be value-only (which leaves the edges describing a graph that no
-        // longer exists). Both ship a stale rect, silently, days later.
-        //
-        // So: re-run the same frame from scratch — no ledger, no cache, full scope — and require
-        // the rects to be identical. That subsumes both failure modes and every one we have not
-        // thought of, because it compares the ANSWER rather than the reasoning. It is forced on
-        // for this crate's tests, which drive the real shipped FrameXML, so every UI test is a
-        // standing probe for a mis-migrated touch site.
+        // ── `WOW_LAYOUT_VERIFY`: the incremental pass's falsifier ─────────────
+        // Re-run the frame from scratch and require identical rects: this catches a write that
+        // moved a node without naming it, or changed an anchor's target as if value-only.
         model.layout_verify_recheck = false;
         let before = (model.resolved.clone(), model.region_resolved.clone());
-        // The meters are the incremental pass's, not the re-run's: `layout_solves` is documented
-        // verify-independent and `layout_last_scope` is decision 1350's own gate. Counting the
-        // falsifier's work in either would make every assertion in the suite read the wrong pass.
+        // The meters keep the incremental pass's values, which tests assert on, not the re-run's.
         let meters = (
             model.layout_solves,
             model.layout_rounds,
@@ -761,44 +548,24 @@ impl UiScript {
 
     fn resolve_layout_inner(model: &mut Model) {
         // ── Tier 1: the mutation epoch ────────────────────────────────────────────────────────
-        // Nothing has called `touch_layout` since the last converged resolve ⇒ the read set the
-        // fingerprint below hashes cannot have moved ⇒ skip everything, including the tooltip
-        // pre-pass and the fingerprint itself (which was the whole idle cost of this function —
-        // ~0.6 ms/frame at the LBRS pin, hashing ~2k inputs per frame to decide "quiet"). Under
-        // verify, fall through: tier 2 then proves the claim (`gate_skips` must agree).
+        // No layout touch since the last converged resolve: nothing the fingerprint reads moved,
+        // so skip everything. Under verify, fall through so tier 2 checks the claim.
         let verify = layout_verify_enabled();
         let tier1_clean = model.layout_epoch_resolved == Some(model.layout_epoch);
         if tier1_clean && !verify {
             return;
         }
         let epoch_at_entry = model.layout_epoch;
-        // Past tier 1 ⇒ this call pays the whole-roster preamble, whatever the fingerprint goes on
-        // to decide. Counted here rather than at the solve, because the walk IS the cost (1385).
-        // Not gated on `verify`: a verify build re-walks skipped resolves and must say so.
+        // Every call past tier 1 counts, verify's re-walks included: the walk is the cost.
         model.layout_gate_walks = model.layout_gate_walks.wrapping_add(1);
-        // `WOW_LAYOUT_PROF=1`'s preamble split — see [`PreambleProf`]. Started here, so the clock
-        // covers everything the tier-1 gate above did NOT skip.
         let mut pre = PreambleProf::new(layout_prof_enabled());
-        // The GameTooltip auto-size + right-flush pre-pass (decision 0274): writes tooltip frame
-        // sizes + right-column anchor offsets from the measure round-trip's cached extents, so
-        // the graph below solves them like any other frame.
+        // The GameTooltip pre-pass writes tooltip sizes and offsets from cached measures.
         super::tooltip::layout_tooltips(model);
         pre.tooltip = pre.lap();
         // ── `OnSizeChanged`'s "before" ───────────────────────────────────────────────────────
-        // The client fires it from `ApplyRect 0x76b580`, per rect application. Ours is a batch
-        // fixpoint, so the faithful *mechanism* — "this frame's resolved size moved" — is the
-        // entry-vs-convergence diff, not a per-round one: an intermediate round's half-solved rect
-        // is an implementation detail of our solver, and firing on it would hand handlers sizes the
-        // reference never produces (and re-fire on the way to the same answer).
-        //
-        // Snapshotted only for frames that actually CARRY a handler (a handful, usually zero), and
-        // only past the tier-1 gate above — an idle frame returns before this line, so the change
-        // costs nothing on the quiet path decision 0740 exists to protect.
-        //
-        // Read off `SetScript`'s maintained list (1446's shape, extended in 1634), NOT by filtering
-        // the whole `scripts` map: "a handful, usually zero" was true of the RESULT and never of
-        // the search, which cost a string compare per frame in a 3,988-frame roster and was the
-        // preamble's biggest phase — larger than everything the graph does with the answer.
+        // The reference fires it per rect application (`ApplyRect 0x76b580`); our batch fixpoint
+        // fires on the entry-vs-convergence diff, never on a half-solved round. Only frames with
+        // a handler are snapshotted, from `SetScript`'s list.
         let watched: Vec<(FrameHandle, Option<Rect>)> = model
             .on_size_changed_frames
             .iter()
@@ -806,13 +573,8 @@ impl UiScript {
             .collect();
         pre.watched = pre.lap();
         // ── The graph: the ledger's cache, or a fresh derivation ─────────────────────────────
-        // `layout_touched` is tier 1's PRECISE form (decision 1388). `Some` carries the claim that
-        // every write since the cached graph was built named its node and left the graph's shape
-        // alone — so the roster, the edge set and the per-node hashes in `layout_scope` still
-        // describe the live model, and this resolve can seed its dirty closure straight from the
-        // list. That skips the derivation below entirely: 1.48 ms of whole-roster walking at the
-        // Stormwind pin (3,218 frames, 10,438 anchored regions), which a single moving castbar
-        // spark used to pay every frame. `None` derives, exactly as every resolve did before 1388.
+        // A `Some` ledger claims every write since the graph was built named its node and kept
+        // the graph's shape, so the cached roster, edges and hashes stand; `None` derives.
         let touched = model.layout_touched.take();
         let fp = touched
             .is_none()
@@ -841,21 +603,14 @@ impl UiScript {
             texture_size_probe,
             ..
         } = model;
-        // ── The incremental seed (decision 1388) ─────────────────────────────────────────────
-        // Re-hash only the nodes the ledger named, and seed the ones whose hash actually moved.
-        // This runs BEFORE the gate's verdict because on this path it IS the verdict: an empty
-        // seed set means no named write moved anything, which is the same conclusion tier 2
-        // reaches by hashing ten thousand nodes — reached here by hashing the handful that were
-        // written, and carrying the scope for the ones that did move as a side effect.
+        // ── The incremental seed ─────────────────────────────────────────────
+        // Re-hash only the named nodes and seed those whose hash moved. It runs before the gate
+        // because on this path it is the verdict: an empty seed set means nothing moved.
         let mut scope_nodes = 0usize;
         let mut full_scope = false;
         if let Some(touched) = &touched {
             scope.begin_incremental();
             for &id in touched {
-                // The node's roster row — which also says whether it is a frame or a region, and
-                // where to find the live inputs to re-hash. `has_node` was already true when the
-                // write named it; re-checking is a formality that costs one bounds check and
-                // survives a roster the ledger somehow outlived.
                 let Some(&n) = scope.node_of.get(id as usize) else {
                     continue;
                 };
@@ -875,9 +630,7 @@ impl UiScript {
                         None => continue,
                     }
                 };
-                // The same absorption the setters' bit-compares give, one level up: a write that
-                // named a node but did not move its hash (the tooltip pre-pass rewriting the same
-                // size, a re-`SetPoint` to the value already there) seeds nothing.
+                // A named write that did not move the hash (a same-value `SetPoint`) seeds nothing.
                 if now != scope.last.get(id as usize).copied().unwrap_or(NO_NODE) {
                     scope.staged.push((id, now));
                     scope.seed(id);
@@ -887,22 +640,14 @@ impl UiScript {
             pre.seed = pre.lap();
             pre.incremental = true;
         }
-        // Tier 2's verdict is a derivation's product, so an incremental pass answers with its own —
-        // and a strictly finer one. Where the fingerprint says "one of these ten thousand moved",
-        // the seed set says which; empty means nothing did, and last frame's rects still stand.
-        // `staged` is exactly the seed set (both are pushed on the same compare), so it is the
-        // question already answered.
+        // An incremental pass has no fingerprint; its verdict is `staged`, exactly the seed set.
         let gate_skips = match fp {
             Some(_) => *layout_fingerprint == fp,
             None => scope.staged.is_empty(),
         };
         pre.report(gate_skips, scope.plan.len(), scope.regions.len());
-        // The tier-1/tier-2 cross-check (only reachable under verify when tier 1 judged quiet):
-        // the epoch said nothing layout-visible was written, so the fingerprint must agree — a
-        // divergence is a mutation path missing its `Model::touch_layout()`, named here at the
-        // frame that proves it instead of shipping as a silently stale rect. An incremental pass
-        // has no fingerprint to cross-check; its own, stronger falsifier is the full re-derivation
-        // `resolve_layout` runs behind it under verify.
+        // Under verify, a frame tier 1 judged quiet must pass tier 2 too; a divergence is a write
+        // path missing its `touch_layout()`.
         if tier1_clean && fp.is_some() {
             assert!(
                 gate_skips,
@@ -910,60 +655,30 @@ impl UiScript {
                  fingerprint moved — a layout write path is missing its touch_layout()"
             );
         }
-        // Nothing in the read set moved since the last CONVERGED resolve, so the rects it left are
-        // still this frame's answer: close tier 1 and skip. (A converged solve closes it too — see
-        // the convergence arm below. This arm is the one that absorbs an epoch bump whose write
-        // changed no input: an id mint, an anchor-less region's creation, a re-`SetPoint` the
-        // setters' own compare let through.)
+        // Nothing read moved since the last converged resolve, whose rects stand: close tier 1.
         if gate_skips {
             *layout_epoch_resolved = Some(epoch_at_entry);
-            // Re-arm the ledger here too (decision 1388). A pass that found nothing to do left the
-            // graph exactly as it found it — derived a moment ago on one path, untouched on the
-            // other — so the cache is as trustworthy as it was. Dropping it here would make every
-            // named-but-idempotent write (the tooltip pre-pass, a re-`SetPoint` to the value
-            // already there) cost the NEXT real write a full derivation.
+            // Re-arm the ledger: the graph is as it was, so the cache is still trustworthy.
             *layout_touched = Some(Vec::new());
             if !verify {
                 return;
             }
         }
-        // Under `WOW_LAYOUT_VERIFY=1` a skippable resolve runs anyway, against a copy of the rects
-        // it is supposed to reproduce — see [`layout_verify_enabled`].
+        // Under verify a skippable resolve runs anyway, against the rects it must reproduce.
         let verify_against = gate_skips.then(|| (resolved.clone(), region_resolved.clone()));
-        // Cleared, not stored, until the fixpoint actually CONVERGES: a run that exhausts the
-        // round cap (a genuine anchor cycle) leaves its rects mid-flight, and the 0294 cross-frame
-        // seed is what lets the next frame carry them further. Storing here would freeze a
-        // pathological graph at whatever partial state it reached. The epoch mirror follows the
-        // same law: a cycle-bailed pass must re-enter tier 1 dirty next frame.
+        // Cleared until the fixpoint converges: a cycle-bailed pass leaves its rects mid-flight
+        // for the next frame to carry further, so it must re-enter both tiers dirty.
         *layout_fingerprint = None;
         *layout_epoch_resolved = None;
-        // Counted on the gate's DECISION, not on the fixpoint running: under
-        // `WOW_LAYOUT_VERIFY=1` a skipped resolve still runs below, and a counter that moved for
-        // it would mean something different in the two modes — exactly the ambiguity the tests
-        // asserting on it exist to remove.
+        // Counted on the gate's decision, so verify's forced runs leave it alone.
         if !gate_skips {
             *layout_solves += 1;
         }
-        // ── The scope: which nodes this solve is actually allowed to touch (decision 1350) ────
-        // A node whose own inputs are unchanged, and none of whose dependencies moved, recomputes
-        // to the rect it already holds — the 0294 seed property, stated per node instead of for
-        // the graph as a whole. So the solve below runs over the dirty CLOSURE and leaves every
-        // other rect at its cached value, feeding it to the solver as an external where a dirty
-        // node anchors to it.
-        //
-        // Four structural cases the per-node diff cannot speak about fall back to full scope,
-        // because getting them wrong ships a stale rect rather than a slow frame:
-        //   * no memory yet (the first resolve, or a pass invalidated below);
-        //   * the SCREEN moved — the root external and every clamped frame's extent;
-        //   * a node DIED: its reverse edges died with it, so its dependents are unreachable.
-        //     Counted, not searched: if fewer of this pass's nodes carry a `last` hash than the
-        //     last pass had nodes, something left;
-        //   * verify, which runs the scoped pass and then the full one and compares.
-        //
-        // An INCREMENTAL pass (decision 1388) reaches the same closure by the other end, and has
-        // already done so above — it re-hashes only the nodes the ledger named and seeds the ones
-        // whose hash moved. None of the four structural cases can reach it: each is a conservative
-        // touch, and a conservative touch is what leaves the ledger `None`.
+        // ── The scope: which nodes this solve may touch ────
+        // A node with unchanged inputs and no moved dependency recomputes to the rect it holds, so
+        // the solve runs over the dirty closure and feeds other rects in as externals. Full scope
+        // when there is no memory yet, the screen moved, a node died (fewer nodes match `last`
+        // than `last_count`), or under verify. The incremental pass seeded its closure above.
         if touched.is_none() {
             let mut matched = 0usize;
             for (id, &n) in scope.node_of.iter().enumerate() {
@@ -992,17 +707,13 @@ impl UiScript {
                 scope.close();
             }
         }
-        // The rosters the rounds walk. A frame in the closure is SOLVED; a region in it is SWEPT;
-        // anything a closure node anchors to is SEEDED as an external at its cached rect. A dirty
-        // REGION is seeded as well as swept: the frame pass runs before the sweep that refreshes
-        // it, so it needs last round's value in front of it — which is exactly what the whole-graph
-        // seeding did before.
+        // A dirty frame is solved, a dirty region swept, and whatever they read is seeded at its
+        // cached rect. A dirty region is seeded too, since the frame pass runs before the sweep.
         let mut solve_frames: Vec<u32> = Vec::new();
         let mut sweep_regions: Vec<u32> = Vec::new();
         let mut seed_frames: Vec<u32> = Vec::new();
         let mut seed_regions: Vec<u32> = Vec::new();
-        // Is any node that reads `id` in the closure? (Seeding is per-node work too, so a rect
-        // nothing dirty reads must not be seeded.)
+        // Whether a node in the closure reads `id`; a rect nothing dirty reads is not seeded.
         let read_by_dirty = |scope: &LayoutScope, id: u32| -> bool {
             let mut e = scope.dep_head[id as usize];
             while e != u32::MAX {
@@ -1034,15 +745,10 @@ impl UiScript {
                 seed_frames.push(idx);
             }
         }
-        // The meter: how WIDE this solve is, beside `layout_solves` (how often) and
-        // `layout_rounds` (how deep). The gate asserts on it, because a scope that tracks the
-        // graph is the regression and milliseconds are not evidence of it (decision 0735's lesson,
-        // paid for twice).
+        // This solve's width, beside `layout_solves` (how often) and `layout_rounds` (how deep).
         *layout_last_scope = (solve_frames.len(), sweep_regions.len());
         let round_cap = scope.plan.len() + region_data.len() + 2;
-        // `WOW_LAYOUT_PROF=1` — the per-solve shape: rounds, the graph's size, and the split
-        // between the frame solve and the region sweep. The numbers that say whether a solve is
-        // expensive because it runs too often or because each pass walks the whole UI.
+        // `WOW_LAYOUT_PROF=1`: rounds, graph size, and the frame-solve and region-sweep split.
         let prof = layout_prof_enabled();
         let mut t_frames = std::time::Duration::ZERO;
         let mut t_regions = std::time::Duration::ZERO;
@@ -1052,11 +758,7 @@ impl UiScript {
             let t_round = prof.then(std::time::Instant::now);
             let mut changed = false;
 
-            // Seed the solver: the screen root, then every rect this pass is NOT recomputing but
-            // something in it reads (regions are externals to the frame solve — the fixpoint is
-            // what closes the loop between them). Frame ids and region ids come from one monotonic
-            // counter, so both live in the solver's single dense rect array and every anchor-target
-            // lookup is an array index.
+            // Seed the screen root and every read rect this pass does not recompute.
             solver.begin();
             solver.set_external(SCREEN, *screen);
             for &i in &seed_regions {
@@ -1072,9 +774,6 @@ impl UiScript {
                 }
             }
             for &i in &solve_frames {
-                // The `layout_inputs` probe the borrowed plan used to hoist out of the round loop
-                // (decision 1350) is back — but paid per frame this solve TOUCHES, not per frame in
-                // the UI, which is what lets the roster itself outlive the call (1388).
                 let (h, id, over) = scope.plan[i as usize];
                 let Some(input) = layout_inputs.get(&h) else {
                     continue;
@@ -1102,17 +801,9 @@ impl UiScript {
                 }
             }
 
-            // Second pass — anchored regions. A region that carries `SetPoint` anchors resolves through
-            // the same [`crate::layout`] leaf math as frames; any edge the anchors + explicit size don't
-            // pin inherits the owner frame's edge (so a single-point FontString gets a real rect, not
-            // `+Inf`). Anchor targets may be frames OR **sibling regions by name** (the real XML does
-            // this everywhere — the merchant label plate anchors to its `$parentSlot` texture; the
-            // owner-fallback that stood in for this was the jutting-plates bug). One region sweep per
-            // outer round: a not-yet-resolved chain target leaves this region on its owner-edge
-            // fallback for now, the fixpoint re-sweeps until every link has settled.
-            //
-            // `scratch` is hoisted out of the loop so the per-region `LayoutInput` refills its
-            // anchors `Vec` in place instead of allocating one per region per round.
+            // Second pass: anchored regions, through the same `crate::layout` math as frames. An
+            // anchor may target a frame or a sibling region; one whose target has no rect yet pins
+            // nothing this round, and the fixpoint re-sweeps until every link settles.
             if let Some(t) = t_round {
                 t_frames += t.elapsed();
             }
@@ -1125,40 +816,19 @@ impl UiScript {
                     owner,
                     is_fontstring,
                 } = scope.regions[ri as usize];
-                // The roster's mutable half, re-probed here rather than borrowed into the row —
-                // once per region SWEPT instead of once per region in the UI (decision 1388). A
-                // row whose data has gone is a region the derive will drop on its next run; it
-                // resolves to nothing in the meantime, exactly as a dead one does.
+                // A row whose data has gone is skipped until the next derivation drops it.
                 let Some(data) = region_data.get(&rh) else {
                     continue;
                 };
                 if prof {
                     n_regions_swept += 1;
                 }
-                // The owner supplies the region's SCALE and nothing else. It used to supply
-                // fallback edges too; it does not any more (decision 1664) — see the `axis`
-                // closure below for why, and what the two shapes that leaned on it get instead.
+                // The owner supplies the region's scale and nothing else: no fallback edges.
                 let scale = arena.frame(owner).map(|f| f.effective_scale).unwrap_or(1.0);
-                // A FontString with no explicit height takes its host-measured wrapped size
-                // (the measure round-trip — the client's layout↔font-engine seam).
-                //
-                // The stored measure is honoured WITHOUT a key check on purpose
-                // ([`RegionData::measure_key`]): it is the LAST-KNOWN box, held so a line whose
-                // text just changed does not collapse for the one frame the re-measure is in
-                // flight. **Empty text is the case where that promise cannot be kept** — nothing
-                // ever measures an empty string (`fontstrings_needing_measure` and
-                // `stale_measure_key` both filter it out), so a cell that goes from text to `""`
-                // would hold its old box FOREVER. There is no round-trip to wait for: an empty
-                // string's extent is known, and it is zero.
-                //
-                // That forever-stale box is B309. Tooltip line cells are POOLED and reused across
-                // hovers (`clear_content` keeps `measured` deliberately, for the hover re-enter
-                // loop), so the item tooltip's two blank gold SET spacers (`render.rs` §22) landed
-                // on cells that had carried real text on an earlier hover: each drew a full row
-                // out of the dead measure while the plate counted it as zero
-                // (`tooltip::cell` calls empty text `(0,0)`), and the set bonuses hung two rows
-                // below the backdrop. The Lua-visible getters never disagreed — they key-check
-                // (`region::measured_wh`) — which is why only the drawn geometry was wrong.
+                // An axis authored 0, width or height, takes the host-measured extent: the
+                // reference sizes a zero width to the unwrapped line. The measure is used without
+                // a key check, so changed text keeps its last box while the re-measure is in
+                // flight; empty text is never measured, so it counts as zero, never a stale box.
                 let measured = data
                     .measured
                     .filter(|_| data.text.as_deref().is_some_and(|t| !t.is_empty()));
@@ -1172,31 +842,16 @@ impl UiScript {
                         width = m.w;
                     }
                 }
-                // …and then the FLOOR. `CSimpleFontString::GetWidth 0x772930` takes the
-                // authored value when it is not exactly `0.0` and the measured extent otherwise,
-                // then returns `max(candidate, ONE FrameXML unit)` — the floor sits past the
-                // `jp 0x772957` that skips the measure, so it applies to BOTH legs. `0x772a60` is
-                // the identical body for height. **A FontString's span is therefore never `0.0`**
-                // (wow-re `region-size-fallback.md` §3), which is what makes a single-anchored
-                // FontString always resolve — and what retires the zero-span collapse this sweep
-                // used to apply in the `axis` closure below.
+                // Then the floor: `CSimpleFontString::GetWidth 0x772930` (height `0x772a60`)
+                // returns at least one unit on both legs, past the `jp 0x772957` that skips the
+                // measure, so a FontString's span is never 0 and a single anchor resolves it.
                 if is_fontstring {
                     width = width.max(FONTSTRING_MIN_SPAN);
                     height = height.max(FONTSTRING_MIN_SPAN);
                 }
-                // A TEXTURE's unset axis is the client's *other* content-derived span: the art's
-                // own texel extent ([`content_span`]). It is the same shape as the FontString
-                // measure above — the reference's size getter is virtual, and both region classes
-                // override it — and it has to be applied HERE, before the resolve, because
-                // `combine_edge` reads a zero span as "no size at all" and leaves the opposite edge
-                // unresolved.
-                //
-                // That vacuum is what B342 fell into. `page_text` 2654 (*A Treatise on Military
-                // Ranks*) carries `<IMG src="…\PvPRankAlliance" align="left"/>` — **no width=, no
-                // height=** — so SimpleHTML sized the block `0 × 0`, one TOPLEFT anchor pinned the
-                // corner, and the owner-edge fallback below stretched a 128×128 crest across the
-                // rest of the 270×304 page with the text over it. The reference draws it at 128×128
-                // units, because a texel is a FrameXML unit.
+                // A texture's unset axis takes its texel extent (`content_span`): the reference's
+                // size getter is virtual for both region classes. It must apply before the
+                // resolve, as `combine_edge` reads a zero span as no size and leaves an edge unset.
                 if !is_fontstring && (width == 0.0 || height == 0.0) {
                     if let Some((cw, ch)) = content_span(data, texture_size_probe.as_ref()) {
                         if width == 0.0 {
@@ -1213,39 +868,16 @@ impl UiScript {
                 scratch.height = height;
                 scratch.scale = scale;
                 let edges = layout::resolve_rect_edges(&scratch, |id| {
-                    // SCREEN is a FRAME-pass external only. The map-pair lookup this replaces
-                    // consulted `id_to_frame` and `id_to_region`, and neither can hold the
-                    // reserved id 0 (`next_id` starts at 1) — so a region anchor to the screen
-                    // root has always fallen through to the owner-edge fallback below. Preserved
-                    // deliberately: the solver's dense array DOES carry the screen rect at 0, and
-                    // quietly starting to resolve it here would be a behaviour change riding in
-                    // on a performance fix.
+                    // The screen root is a frame-pass external only: a region anchor to id 0 finds
+                    // no rect here, though the solver holds one.
                     (id != SCREEN).then(|| solver.rect(id)).flatten()
                 });
-                // **An axis resolves, or the region does not** — there is no owner-edge
-                // fallback and no zero-span collapse (decision 1664, from wow-re's byte-verified
-                // `region-size-fallback.md` §7). A complete memory-operand enumeration of the real
-                // resolver core `[0x7671a0, 0x76761f)` finds no parent or owner pointer in it at
-                // all: the only fallbacks are the object's own nine anchor slots and
-                // `combineEdge`/`combineCenter` over its own opposite edge/centre ± its own size.
-                // `assemble 0x767a20` returns 0 the moment any edge is still UNSET, and
-                // `0x768d20` latches the region unresolvable.
-                //
-                // The two shapes that leaned on the fallback both have their own answer now, which
-                // is why deleting it is a fidelity fix and not a hole:
-                //
-                // * **No anchors at all.** The client anchors those at CREATION, per region type —
-                //   a texture gets `SetAllPoints(parent)`, a FontString one justify-selected
-                //   `SetPoint` — so by the time the resolver sees them they are pinned like
-                //   anything else ([`super::region::implicit_creation_anchor`], decision 1310).
-                //   The ones that reach here still unanchored are the shapes the reference leaves
-                //   rect-less too: a templateless `CreateTexture`, a title region, a plain frame.
-                // * **A pinned edge with a zero span.** The span is content-derived on both region
-                //   classes — the texture's texel extent above, the FontString's measured extent
-                //   floored at one unit — so `combineEdge`'s zero-span leg is nearly unreachable
-                //   for a region at all (`region-size-fallback.md` §4). What is left is a texture
-                //   with no art whatever, which the reference resolves to nothing and draws as a
-                //   degenerate all-zero quad.
+                // An axis resolves, or the region does not. The reference resolver core
+                // `[0x7671a0, 0x76761f)` reads no parent or owner pointer, only the region's own
+                // anchors and `combineEdge`/`combineCenter` over its own size; `assemble 0x767a20`
+                // fails on any unset edge, and `0x768d20` latches the region unresolvable. An
+                // anchor-less region is anchored at creation (`region::implicit_creation_anchor`),
+                // and a texture with no art has a zero span and resolves to nothing (`0x767440`).
                 let axis = |lo: Option<f32>, hi: Option<f32>| -> Option<(f32, f32)> {
                     match (lo, hi) {
                         (Some(l), Some(h)) => Some((l, h)),
@@ -1255,17 +887,14 @@ impl UiScript {
                 let vertical = axis(edges[0], edges[2]);
                 let horizontal = axis(edges[1], edges[3]);
                 let (Some((bottom, top)), Some((left, right))) = (vertical, horizontal) else {
-                    // Unresolvable: drop any rect it used to have, the way the frame pass does —
-                    // a region that stops resolving must stop drawing, not keep a stale position.
+                    // Unresolvable: drop its rect, so it stops drawing instead of going stale.
                     if region_resolved.remove(&rh).is_some() {
                         changed = true;
                     }
                     continue;
                 };
                 let rect = Rect::new(bottom, left, top, right);
-                // Publish into the solver as well as the model: a later region in THIS same sweep
-                // that anchors to this one must see the fresh rect (the sweep has always worked
-                // that way — it read the same `region_resolved` map it was writing).
+                // Into the solver too: a later region in this sweep that anchors here needs it.
                 solver.set_external(region_id, rect);
                 if region_resolved.get(&rh) != Some(&rect) {
                     region_resolved.insert(rh, rect);
@@ -1278,12 +907,7 @@ impl UiScript {
             }
             if !changed {
                 if prof {
-                    // `anchored` (live + anchored regions) is reported beside `regions_total`
-                    // deliberately: the sweep never touched the difference, so a solve's real
-                    // population was invisible in this line — which is exactly why two commits
-                    // that moved a large batch of regions from "skipped" to "resolved" (1350's
-                    // pin) showed up as a cost with no counter behind it. `solved`/`swept` are
-                    // this pass's SCOPE: with the graph settled they should be a handful.
+                    // `anchored` is the sweep's roster, `solved` and `swept` this pass's scope.
                     eprintln!(
                         "[layout-prof] rounds={} frames={} regions_total={} anchored={} \
                          solved={} swept={} scope={} regions_swept={} frame_us={} region_us={}",
@@ -1312,55 +936,28 @@ impl UiScript {
                     );
                 }
                 *layout_fingerprint = fp;
-                // The scope's memory is adopted only HERE, on the converged path, for the same
-                // reason the fingerprint is: a pass left mid-flight describes a graph that never
-                // settled, and seeding the next pass's "unchanged ⇒ unmoved" argument from it
-                // would be seeding it from a lie.
-                //
-                // An incremental pass adopts only the nodes it re-hashed — the rest of `last` is
-                // already the memory of the derivation this pass is standing on (decision 1388).
+                // Adopted only on convergence; an incremental pass adopts only what it re-hashed.
                 if touched.is_some() {
                     scope.commit_incremental();
                 } else {
                     scope.commit(scope_nodes, *screen);
                 }
                 // ── Re-arm the ledger ─────────────────────────────────────────────────────────
-                // The graph in `scope` now describes a CONVERGED model, so the next frame's writes
-                // may name their nodes against it. Empty, not `None`: `None` is the standing claim
-                // that the cache is untrustworthy, and it has just been made trustworthy.
-                //
-                // Armed only on convergence, and only here — the cycle bail below leaves it `None`
-                // along with everything else, because a graph that never settled is exactly the
-                // one a ledger must not vouch for.
+                // The graph now describes a converged model, so writes may name nodes against it.
+                // Only here: the cycle bail below leaves it `None`.
                 *layout_touched = Some(Vec::new());
-                // Under verify, tell `resolve_layout` to re-derive this same frame from scratch and
-                // compare rects — the incremental pass's falsifier. Costs nothing in production,
-                // where `layout_verify_enabled` is false and nothing ever reads this.
+                // Under verify, `resolve_layout` re-derives this frame from scratch and compares.
                 *layout_verify_recheck = touched.is_some() && verify;
-                // **A CONVERGED SOLVE CLOSES TIER 1** (decision 1385) — unconditionally, not only
-                // on the `gate_skips` re-run. The fingerprint above is hashed over INPUTS alone,
-                // and the rounds just drove those inputs to their fixpoint, so the fp stored on
-                // the line above is exactly the one the next mutation-free resolve recomputes:
-                // there is nothing left for a settling pass to discover. Closing here is what
-                // makes a per-frame layout write cost ONE whole-roster walk instead of three
-                // (solve, settle, skip) — the castbar's spark, and every addon that animates a
-                // region, used to pay all three every frame.
-                //
-                // `epoch_at_entry` (not the live epoch) keeps it conservative: anything that
-                // touched the layout WHILE this pass ran — the tooltip pre-pass, a lazily minted
-                // region — leaves the epoch ahead of the stored value, so tier 1 re-opens next
-                // call exactly as it should. The cycle-bail path below never reaches here, so a
-                // graph left mid-flight still re-resolves.
+                // A converged solve closes tier 1, at `epoch_at_entry` rather than the live epoch,
+                // so a touch during this pass (the tooltip pre-pass, a minted id) re-opens it. The
+                // fingerprint hashes inputs only, so the next unmutated resolve would match it.
                 *layout_epoch_resolved = Some(epoch_at_entry);
                 queue_size_changes(&watched, resolved, frame_to_id, pending_size_changed);
                 return;
             }
             if round + 1 == round_cap {
-                // `Model::record_warning`'s two halves, spelled out because this pass holds the
-                // model destructured and cannot call it: the host drain, and the retained log
-                // (2135). `WOW_LAYOUT_VERIFY`'s falsifier re-run truncates `warnings` and does
-                // NOT roll the log back — the log dedupes, so a verify build reads `×2` on a row
-                // that happened once, and that build is not a production path.
+                // `Model::record_warning` inlined, as the model is destructured. Verify's re-run
+                // truncates `warnings` but not the log, so a verify build may count a row twice.
                 let msg = format!(
                     "layout: anchor graph did not converge in {round_cap} rounds — \
                      an anchor cycle? (rects left at their last pass)"
@@ -1369,23 +966,14 @@ impl UiScript {
                 warnings.push(msg);
             }
         }
-        // The cycle bail (the loop ran out of rounds and warned above): the rects it leaves are
-        // still the ones every reader will see this frame, so the sizes that moved get their
-        // `OnSizeChanged` here exactly as on the converged path — and the scope forgets, so the
-        // next resolve rebuilds the whole graph rather than trusting a half-solved one.
+        // The cycle bail: its rects are this frame's, so their size changes still fire, and the
+        // scope forgets a graph that never settled.
         scope.invalidate();
         queue_size_changes(&watched, resolved, frame_to_id, pending_size_changed);
     }
 
-    /// Derive the layout graph from scratch — the roster of live frames and anchored regions, the
-    /// reverse-edge set between them, the per-node input hashes, and the aggregate fingerprint
-    /// that is tier 2 of the change gate.
-    ///
-    /// Every resolve did this, until decision 1388. It is ~1.48 ms at the Stormwind pin, 79% of it
-    /// in two phases (`fp_regions` 919 µs, `retain` 255 µs) that rediscover a graph which had not
-    /// changed shape. It now runs only when the ledger cannot vouch for the cache: the first
-    /// resolve, a cycle-bailed one, and any frame in which a write moved the roster, retargeted an
-    /// anchor, or could not name what it touched.
+    /// Derive the layout graph from scratch: the roster, the reverse edges, the per-node hashes and
+    /// the tier-2 fingerprint. Runs only when the ledger cannot vouch for the cache.
     fn derive_layout_graph(model: &mut Model, pre: &mut PreambleProf) -> InputFingerprint {
         model.layout_derives = model.layout_derives.wrapping_add(1);
         let Model {
@@ -1402,9 +990,7 @@ impl UiScript {
             ..
         } = model;
 
-        // One id per live frame, and its layout input with scale synced from the arena. A flat
-        // `Vec`, not a map: this list is walked (never probed) by every round below, and it is
-        // rebuilt on each call anyway — a `HashMap` bought nothing and cost 1881 hashes per call.
+        // One id per live frame, its layout input's scale and clamp synced from the arena.
         let mut ids: Vec<(FrameHandle, u32)> = Vec::with_capacity(frame_to_id.len());
         for (&h, &id) in frame_to_id.iter() {
             if arena.frame(h).is_some() {
@@ -1418,10 +1004,8 @@ impl UiScript {
                 .unwrap_or((1.0, false));
             let input = layout_inputs.entry(h).or_default();
             input.scale = scale;
-            // Clamp-to-screen is a FRAME property (geometry flags bit4 — SetClampedToScreen, the
-            // XML attribute, the GameTooltip-kind default), synced like scale so EVERY placement
-            // path — SetOwner's anchor law, a caller's SetPoint, the cursor-seated world plates —
-            // resolves through the same clamp, with extents tracking the live window size.
+            // Clamp-to-screen is a frame property (geometry flags bit 4), so every placement path
+            // clamps alike, against the live window size.
             input.clamp = clamp;
             if clamp {
                 input.extent_x = screen.right;
@@ -1430,18 +1014,10 @@ impl UiScript {
         }
         pre.ids = pre.lap();
 
-        // The ScrollFrame mechanism (decision 0112): a live ScrollFrame with a live scroll child
-        // overrides the child's own anchors for this solve — `SetScrollChild` pins the child TOPLEFT
-        // to the scrollframe's TOPLEFT, offset by the two live scroll offsets
-        // (`(horizontal, vertical)`, both RAW and unnegated, exactly as the reference's re-anchor
-        // `0x787100` hands them to `SetPoint`). XML y-positive-up, so a positive vertical lifts the
-        // child, bringing content below the fold into view — `frame top 500, vertical 40 ⇒ child top
-        // 540`; x grows right, so a positive horizontal pushes the child right and it is a NEGATIVE
-        // horizontal that scrolls right (see `ScrollFrameState::horizontal`). This is a LOCAL map, consulted only
-        // while building each round's graph below — the child's authored `LayoutInput.anchors` are
-        // never touched, so `SetScrollChild(nil)` needs no restore: the override just stops being
-        // computed. The child's own width/height (from its own `LayoutInput`) stay whatever they are;
-        // only its anchors are replaced.
+        // A live ScrollFrame's live child is anchored, for this solve only, TOPLEFT to its TOPLEFT
+        // at the raw, unnegated `(horizontal, vertical)` offsets, as the reference's re-anchor
+        // `0x787100` passes them to `SetPoint`: y up, so a positive vertical lifts the child. Its
+        // authored anchors and size are untouched, so `SetScrollChild(nil)` needs no restore.
         let mut scroll_child_anchor: HashMap<FrameHandle, Anchor> = HashMap::new();
         for &(h, id) in &ids {
             let Some(frame) = arena.frame(h) else {
@@ -1470,28 +1046,11 @@ impl UiScript {
         }
         pre.scroll = pre.lap();
 
-        // Alternating frame/region rounds, run to a CHANGE-DRIVEN FIXPOINT: the real client
-        // resolves ONE layout graph in which frames and regions anchor each other freely (the
-        // gossip option rows anchor to the greeting FontString's laid-out bottom; the quest log's
-        // detail pane chains ~15 regions deep with item BUTTONS anchored to the tail). Our frame
-        // pass is a batch graph solve, so each round re-solves it with the latest REGION rects as
-        // externals, re-resolves the regions against the new frame rects, and stops when a full
-        // round changed nothing. The old fixed budget (2 frame rounds × 3 region rounds) silently
-        // left chain links past ~6 on owner-edge fallbacks and dropped tail-anchored frames to the
-        // screen origin — decision 0088 §2's finding, which forced windows into invented fixed
-        // offsets instead of ref-verbatim chains. The round cap is the node count (an honest round
-        // binds at least one new link), so only a genuine anchor CYCLE can exhaust it — warned,
-        // mirroring the client's resolving-flag cycle bail. Convergence compares exact rects: each
-        // pass recomputes from the same inputs through the same arithmetic, so stabilized values
-        // repeat bit-for-bit (no epsilon drift).
-        //
-        // The fixpoint CARRIES ACROSS FRAMES (decision 0294): every rect is recomputed purely from
-        // (inputs, externals), never from its own prior value, so last frame's converged rects are a
-        // legal seed — a quiet frame re-verifies in ONE round instead of re-propagating every anchor
-        // chain link-by-link (measured: the full default UI held 5–10 rounds × ~7 ms/round at
-        // opt-level 0, every frame, ~72 ms of a quiet frame — the director's 60→50 fps). Only
-        // regions that left the model (or lost their anchors) drop; a from-scratch resolve is just
-        // the empty-seed special case, so first-frame behavior is unchanged.
+        // The reference resolves one graph in which frames and regions anchor each other; ours
+        // alternates a frame solve and a region sweep until a round changes no rect, compared
+        // exactly. The round cap is the node count, so only a cycle exhausts it, warned like the
+        // reference's resolving-flag bail. Every rect is recomputed from inputs and externals, so
+        // last frame's rects are a legal seed: only dead or unanchored regions drop.
         region_resolved.retain(|rh, _| {
             arena.region(*rh).is_some()
                 && region_data.get(rh).is_some_and(|d| !d.anchors.is_empty())
@@ -1499,52 +1058,16 @@ impl UiScript {
         pre.retain = pre.lap();
 
         // ── The change gate ───────────────────────────────────────────────────────────────────
-        // Fingerprint exactly what the rounds below read, and skip them outright when nothing has
-        // moved since the last converged resolve. Measured on the shipped default UI: the layout
-        // inputs are byte-identical on 34 of 35 idle frames and 39 of 41 with three windows open,
-        // because almost all per-frame UI traffic (StatusBar values, cooldown sweeps, chat fades,
-        // colour changes) is read by EXTRACT, not by the anchor solve.
-        //
-        // The read set, in the order the rounds consume it:
-        //   * `screen`                      — the root external, and the clamp extents;
-        //   * `plan`                        — every live frame's id, its (already scale/clamp-
-        //                                     synced) `LayoutInput`, and its ScrollFrame override,
-        //                                     which together distil `frame_to_id`, frame liveness,
-        //                                     `effective_scale`, `clamped_to_screen`, and the
-        //                                     ScrollFrame child + vertical offset;
-        //   * `region_data`                 — each region's anchors, explicit size, and measured
-        //                                     text extent;
-        //   * `arena.region(rh)`            — liveness and owner (a dead region drops out of the
-        //                                     sweep; the owner supplies the fallback edges).
-        //
-        // **INPUTS ONLY — the 0294 seeds are deliberately NOT hashed** (decision 1385). They are
-        // the previous pass's OUTPUT, and 0294's own property ("every rect is recomputed purely
-        // from (inputs, externals), never from its own prior value") makes a converged pass's
-        // rects a pure function of the inputs: the seeds change how many ROUNDS convergence
-        // takes, never what it converges to. Hashing them therefore added no verdict the input
-        // half does not already give — and it cost two extra whole-roster walks per mutated
-        // frame, because a solve necessarily outgrows the seeds it hashed, so neither that pass
-        // nor the settling pass behind it could close tier 1. (`resolved`, the FRAME rects, was
-        // never in the read set at all — the seed half was asymmetric as well as redundant.)
-        //
-        // ── …and, in the same walk, the SCOPE (decision 1350) ─────────────────────────────────
-        // Each node's own inputs are hashed a second time on their own, into
-        // [`LayoutScope::now`], and its anchor targets are recorded as reverse edges. That turns
-        // the gate's one verdict ("something moved") into the far more useful one ("*these* moved,
-        // and here is everything downstream of them"), for the cost of a second accumulator over
-        // a read set we were walking anyway. Everything the aggregate `fp` feeds still feeds it,
-        // byte for byte, so tiers 1 and 2 are untouched.
-        // Sized past `next_id` because the region walk below MINTS ids (see there) — every id it
-        // can mint is one more than the anchored regions it walks.
+        // Fingerprint what the rounds read, to skip them when nothing moved since the last
+        // converged resolve: the screen; each live frame's id, synced `LayoutInput` and
+        // ScrollFrame override; each anchored region's anchors, explicit size, measured extent
+        // and liveness. Seeded rects are outputs, a pure function of these, so they are not hashed.
+        // The same walk hashes each node alone into `LayoutScope::now` and records its edges.
+        // Sized past `next_id` for the ids the region walk below may mint.
         scope.begin_full(*next_id as usize + region_data.len() + 1);
         pre.begin = pre.lap();
         let mut fp = InputFingerprint::default();
         fp.rect(*screen);
-        // The frame roster is built HERE rather than in a walk of its own (decision 1388): it is
-        // the same `ids` list, the same `layout_inputs` probe and the same `scroll_child_anchor`
-        // lookup this walk already needs, so a separate pass over every live frame bought nothing
-        // but a second traversal (77 µs of the old preamble) and a borrow that stopped the roster
-        // outliving the call.
         for &(h, id) in &ids {
             let Some(input) = layout_inputs.get(&h) else {
                 continue;
@@ -1563,9 +1086,8 @@ impl UiScript {
                 scope.node_of[id as usize] = i;
             }
             scope.plan.push((h, id, over));
-            // A frame reads the rect of every anchor target it has — its OVERRIDE's target when a
-            // ScrollFrame supplies one (the authored anchors are not consulted at all in that
-            // case, exactly as the round loop's `set_frame_anchored` does not consult them).
+            // A frame reads its anchor targets' rects, or only its ScrollFrame override's target,
+            // as the round loop's `set_frame_anchored` does.
             match over {
                 Some(a) => scope.edge(id, a.relative_to),
                 None => {
@@ -1581,16 +1103,11 @@ impl UiScript {
         }
         pre.fp_frames = pre.lap();
         let mut fed_regions = 0u64;
-        // The round loop's region roster, built in this same walk (decision 1350) — see
-        // [`RegionRow`]. Only LIVE, anchored regions: an anchor-less one is invisible to the
-        // rounds and a destroyed one has already been dropped from `region_resolved` by the retain
-        // above, so both are exactly what the sweep used to `continue` past.
+        // The region roster, built in the same walk: live, anchored regions only.
         scope.regions.reserve(region_data.len());
         for (&rh, data) in region_data.iter() {
-            // Anchor-less entries are invisible to the rounds — the sweep `continue`s on empty
-            // anchors and the seed retain drops them — so they are not inputs and must not be
-            // hashed: a paint-only setter creating a region's entry (`SetTexture`'s
-            // `or_default()`) would otherwise read as a layout change no touch site can own.
+            // Anchor-less entries are not layout inputs: hashing them would make a paint-only
+            // setter that creates one (`SetTexture`'s `or_default()`) read as a layout change.
             if data.anchors.is_empty() {
                 continue;
             }
@@ -1613,14 +1130,8 @@ impl UiScript {
                 None => fp.feed(u64::MAX),
             }
             if let Some(r) = live {
-                // Mint the layout id here if the region has never needed one. The sweep used to
-                // resolve an id-less region and simply not publish its rect (`if let Some(&id) =
-                // region_to_id.get(..)`) — an EditBox's implicit text FontString is exactly that
-                // shape, created and anchored by `SetTextInsets` and given an id only when extract
-                // or a measure first asks. The scope addresses nodes BY id, so it needs one; and
-                // minting it is pure addressing — it moves no rect, so unlike `Model::region_id`
-                // this does not touch the layout epoch (doing so would re-dirty the very resolve
-                // that is running).
+                // Mint an id for a region that never needed one, without `Model::region_id`'s
+                // epoch bump, which would re-dirty the running resolve.
                 let id = match region_to_id.get(&rh) {
                     Some(&id) => id,
                     None => {
@@ -1637,9 +1148,7 @@ impl UiScript {
                     *slot = region_node_hash(data);
                     scope.node_of[id as usize] = idx;
                 }
-                // A region reads its anchor targets' rects, and — for any axis its anchors do not
-                // pin — its OWNER's rect and scale. Both are dependencies; the owner one is the
-                // edge that carries a window moving to every unpinned texture inside it.
+                // A region reads its anchor targets' rects and its owner's scale.
                 for a in &data.anchors {
                     scope.edge(id, a.relative_to);
                 }
@@ -1653,47 +1162,23 @@ impl UiScript {
                     is_fontstring: matches!(r.kind, crate::widget::RegionKind::FontString),
                 });
             }
-            // Liveness only. The sweep also reads the region's `owner` and `kind`, but both are
-            // fixed at creation and can never change under a live handle; the owner's contribution
-            // to the result — its resolved rect and its `effective_scale` — rides the frame half
-            // (the scale is synced into `layout_inputs` by the preamble above, and the rect is the
-            // frame pass's own output). A DESTROYED region does still matter: `WidgetArena::destroy`
-            // drops the arena entry but leaves `region_data` behind, so membership alone would miss
-            // it and the sweep's `continue` would go unnoticed.
+            // Liveness only (`owner` and `kind` never change): `WidgetArena::destroy` leaves
+            // `region_data` behind, so membership alone would miss a destroyed region.
             fp.feed(u64::from(live.is_some()));
         }
-        // The count of FED entries (not the map's len — see the vacuous-entry skip above), so an
-        // entry leaving the anchored set is a change even if a sibling enters the same frame.
+        // The count of anchored entries fed, not the map's len.
         fp.feed(fed_regions);
         pre.fp_regions = pre.lap();
         fp
     }
 
-    /// FontStrings whose layout needs a host text measurement (an auto-sized axis — explicit
-    /// width and/or height of 0, the client's size-to-text idiom — text present, cache stale) —
-    /// the engine side of the measure round-trip. Call after [`UiScript::resolve`]; answer with
-    /// [`UiScript::set_measured_text`] and resolve again (the second solve is cheap and the cache
-    /// keys keep this empty on quiet frames). A zero WIDTH auto-sizes exactly like a zero height
-    /// (the real client sizes the rect to the unwrapped line — `<Size x="0" y="16"/>` labels like
-    /// the mail window's "From:" anchor their RIGHT edge and grow leftward); gating on height
-    /// alone left those rects zero-width and their anchored neighbours overlapping.
+    /// FontStrings with text whose stored measure is stale, for the host to measure: call after
+    /// [`UiScript::resolve`], answer with [`UiScript::set_measured_text`], and resolve again.
     pub fn fontstrings_needing_measure(&mut self) -> Vec<MeasureRequest> {
         let mut model = self.model_mut();
-        // ANY FontString with text — not only the auto-sized ones. A region with both axes
-        // declared needs no measure for its *layout*, but `GetStringWidth` still has to answer
-        // with the string's natural width, and only a measure can supply it (decision 0997: a
-        // kit that reads that number and then SETS a width on the string would otherwise stop
-        // receiving measures the instant it did so, and start reading its own box back).
-        //
-        // Asked off the MEASURE LEDGER, not the roster (the 1388 shape one lane over): the
-        // sweep existed to *discover* silent writes — `SetText` touches no layout until the
-        // extent moves — and discovery cost two whole-roster walks per frame at a city pin
-        // (~300 µs of the `resolve` lap, decision 1370) to conclude, almost always, that
-        // nothing was written. The write sites announce themselves now
-        // ([`Model::touch_measure`]); draining the ledger re-arms it, so the second ask of the
-        // same frame (`fill_measures`, inside `resolve`) sees only what was written *between*
-        // the asks — same-frame semantics unchanged. `None` (a fan-out that could not name its
-        // regions, or the initial state) is the old whole-roster walk, verbatim.
+        // Every FontString with text, sized or not: `GetStringWidth` answers the natural width.
+        // The ledger (`Model::touch_measure`) re-arms empty, so a second ask this frame sees only
+        // the writes since the first; `None` walks every region.
         let ledger = model.measure_dirty.take();
         model.measure_dirty = Some(Vec::new());
         let needy: Vec<RegionHandle> = match ledger {
@@ -1701,13 +1186,8 @@ impl UiScript {
                 dirty.sort_unstable_by_key(|rh| rh.fingerprint_bits());
                 dirty.dedup();
                 dirty.retain(|&rh| stale_measure_key(&model, rh).is_some());
-                // The completeness falsifier (on for every benilla-ui test): the ledger's whole
-                // correctness claim is that its enrolled sites cover every measure-key writer,
-                // and that claim is checked, not argued — the old discovery walk runs beside
-                // the drain and any row it finds that the ledger missed is a stale label
-                // waiting to ship, so it panics with the region named. The other direction is
-                // legal by construction (an enrolled same-value write drops out at the
-                // staleness check above).
+                // Under verify, the full walk runs beside the drain and panics on any stale region
+                // the ledger missed.
                 if layout_verify_enabled() {
                     let roster: Vec<RegionHandle> = model
                         .region_data
@@ -1736,12 +1216,7 @@ impl UiScript {
                 .filter(|&rh| stale_measure_key(&model, rh).is_some())
                 .collect(),
         };
-        // Re-enroll everything still stale: a request handed out is not an answer. The old
-        // discovery walk re-found an unanswered region every frame until `set_measured_text`
-        // landed (the no-measurer engine-test path answers a frame later; a dropped request
-        // would otherwise go stale FOREVER now that nothing walks the roster), so the ledger
-        // keeps asking too. With a synchronous measurer the answer lands before the next drain
-        // and the staleness check drops the re-enrolled handle for free.
+        // Re-enroll every stale region: a request is not an answer, and nothing else asks again.
         if let Some(list) = &mut model.measure_dirty {
             list.extend(needy.iter().copied());
         }
@@ -1754,11 +1229,8 @@ impl UiScript {
         out
     }
 
-    /// Push one [`QuadContent::Backdrop`] per piece of frame `fh`'s installed backdrop (no-op if the
-    /// frame has none). Pieces carry the frame slot's `z` — behind the frame's regions (which sort
-    /// after it) and, among themselves, bg-then-border in paint order (the stable z-sort keeps the
-    /// emission order). Each piece's rect is its screen bounding box; the app resolves the texture
-    /// from the piece path and multiplies the tint by the [`FramePaint`]'s alpha.
+    /// Push one [`QuadContent::Backdrop`] per piece of frame `fh`'s backdrop, at the frame slot's
+    /// `z`: behind its regions, and background before border by the stable sort.
     pub(super) fn emit_backdrop(
         model: &Model,
         fh: FrameHandle,
@@ -1772,8 +1244,8 @@ impl UiScript {
             return;
         };
         for piece in backdrop::pieces(fr, bd) {
-            // The piece's screen bounding box (the render is axis-aligned; the BR-inset bug's slant,
-            // invisible for the symmetric insets every shipping backdrop uses, collapses to the box).
+            // The piece's screen bounding box: the render is axis-aligned, so the reference's slant
+            // under unequal top and bottom insets is not drawn (stock insets are symmetric).
             let xs = piece.corners.map(|c| c[0]);
             let ys = piece.corners.map(|c| c[1]);
             let (left, right) = (
@@ -1813,13 +1285,8 @@ impl UiScript {
     }
 }
 
-/// The [`MeasureRequest`] region `rh` needs right now, or `None` if it needs none — it is not a
-/// FontString, it holds no text, or its stored measure is already this exact string's.
-///
-/// Hoisted out of [`UiScript::fontstrings_needing_measure`] so the **synchronous** measure
-/// ([`super::measure::ensure_measured`]) builds its request with the identical recipe. The two must
-/// agree byte for byte on the cache key, or a same-tick measure and the batch pass would each think
-/// the other's answer was stale and re-measure forever.
+/// The [`MeasureRequest`] region `rh` needs now, if any; shared with the synchronous measure
+/// ([`super::measure::ensure_measured`]), as both must build the same cache key.
 pub(super) fn measure_request_for(model: &mut Model, rh: RegionHandle) -> Option<MeasureRequest> {
     let (key, scale) = stale_measure_key(model, rh)?;
     let d = model.region_data.get(&rh)?;
@@ -1843,18 +1310,14 @@ pub(super) fn measure_request_for(model: &mut Model, rh: RegionHandle) -> Option
     })
 }
 
-/// The staleness half of [`measure_request_for`], allocation-free: `Some((key, scale))` iff `rh`
-/// is a FontString holding text whose stored measure no longer matches its current key. This is
-/// the ONE place the "does this region need a measure?" question is answered — the per-frame
-/// sweep ([`super::UiScript::fontstrings_needing_measure`]) asks it for every FontString, so it
-/// must not clone; the request build above pays the clones only after this says stale.
+/// `Some((key, scale))` iff `rh` is a FontString with text whose stored measure no longer matches
+/// its key: the one staleness test, allocation-free as the sweep asks it of every FontString.
 fn stale_measure_key(model: &Model, rh: RegionHandle) -> Option<(u64, f32)> {
     let region = model.arena.region(rh)?;
     if !matches!(region.kind, crate::widget::RegionKind::FontString) {
         return None;
     }
-    // The owner's effective_scale: the host measures at the drawn raster size
-    // ([`MeasureRequest::scale`]), and the key carries it so a SetScale re-measures.
+    // The host measures at the drawn size, so the key carries the owner's scale.
     let scale = model
         .arena
         .frame(region.owner)
@@ -1864,8 +1327,7 @@ fn stale_measure_key(model: &Model, rh: RegionHandle) -> Option<(u64, f32)> {
     if d.text.as_deref().is_none_or(|t| t.is_empty()) {
         return None;
     }
-    // The shared key recipe ([`RegionData::measure_key`]) — the metric reads (region.rs) check the
-    // stored measure against the same hash.
+    // The metric reads in `region.rs` check the stored measure against this same key.
     let key = d.measure_key(scale);
     if d.measured.map(|m| m.key) == Some(key) {
         return None;
diff --git a/crates/benilla-ui/src/script/layout_cache.rs b/crates/benilla-ui/src/script/layout_cache.rs
index b62bac21..44516c4b 100644
--- a/crates/benilla-ui/src/script/layout_cache.rs
+++ b/crates/benilla-ui/src/script/layout_cache.rs
@@ -1,54 +1,11 @@
-//! The **layout cache** — the consumer `Frame::user_placed` never had.
+//! The layout cache: the reference writes a per-character `layout-cache.txt` at logout and seats
+//! the user-placed frames from it at load (userPlaced is `frame+0xb4 & 0x1000`). This is the
+//! engine half, a snapshot out, a restore in and a dirty bit; the app owns the file
+//! (`benilla_app::ui_layout`).
 //!
-//! `SetUserPlaced` / the drag entries set the client's userPlaced bit (`frame+0xb4 & 0x1000`,
-//! [`super::object::movable`]), and together with the frame's own `movable`/`resizable` flags it
-//! means *"the player put this window here; put it back next time"*. The real client honours that
-//! by writing a per-character `layout-cache.txt` at logout and seating the frames from it at load;
-//! benilla had the bit and nothing that read it, so a dragged or resized window went back to its
-//! authored anchors on the next login.
-//!
-//! **The bit is not the whole gate**, at either end — see [`super::UiScript::user_placed_layouts`]
-//! and [`super::UiScript::restore_user_placed_layouts`] for the conjuncts and their byte sites.
-//! Reading it as the whole gate is what let one addon's stamp seat a stock frame forever
-//! (decision 2193).
-//!
-//! This module is the **engine half** of that: a snapshot out, a restore in, and a dirty bit for
-//! the host to debounce on. Where the file lives, when it is written and which character owns it
-//! are the app's ([`benilla_app::ui_layout`] — `benilla-config/layout/<realm>-<character>.txt`,
-//! through `local_state`, like every other resident of that folder).
-//!
-//! ## Why a host seam at all, when `GetPoint`/`SetPoint` exist
-//!
-//! Everything *about one frame* is already Lua-reachable — `GetNumPoints`, `GetPoint`, `GetWidth`,
-//! `GetHeight`, `IsUserPlaced`, `SetPoint`, `SetWidth`, `SetHeight` — and if the saver knew which
-//! frames to ask about, it would need nothing here. **Enumeration is the part Lua cannot do**:
-//! there is no `EnumerateFrames` in 1.12 and inventing one would be a far wider surface than the
-//! three functions below. The alternative — a hand-maintained list of names in FrameXML — is a
-//! list that goes stale the first time a window becomes movable and nobody remembers to add it,
-//! which is the failure mode the *bit* exists to prevent.
-//!
-//! So the seam is deliberately three calls wide and mirrors the chat-look seam next door
-//! (`chat_window_looks` / `set_chat_window_looks` / `take_chat_window_changes`, decision 1589):
-//! [`super::UiScript::user_placed_layouts`], [`super::UiScript::restore_user_placed_layouts`] and
-//! [`super::UiScript::take_user_placed_change`].
-//!
-//! ## What a saved frame carries
-//!
-//! Its **name**, its **width/height**, and its **whole anchor list** — point, target, relative
-//! point, offsets — because that is what `GetPoint` answers and what `SetPoint` takes. A frame is
-//! addressed by name in the file for the obvious reason: handles are minted per session and mean
-//! nothing across a relog.
-//!
-//! Two anchor targets survive the round trip and everything else drops the frame's row rather than
-//! guessing:
-//!
-//! - the **screen root** ([`super::SCREEN`]) — written as no target, which is exactly what
-//!   `GetPoint` answers there (`nil`, decision 0068's stated `UIParent` divergence);
-//! - a **named frame** — written by name.
-//!
-//! An anchor onto an unnamed frame or onto a *region* cannot be re-addressed at load, so a frame
-//! carrying one is skipped **whole**. Restoring half an anchor set would seat a window somewhere
-//! nobody put it, which is worse than leaving it on its authored anchors.
+//! A saved frame carries its name, size and whole anchor list. An anchor's target is the screen
+//! root (saved as no target, the `nil` `GetPoint` answers there) or a named frame; a frame anchored
+//! to anything else is skipped whole, never half-restored.
 
 use crate::layout::Anchor;
 use crate::widget::FrameHandle;
@@ -61,24 +18,22 @@ use super::{Model, SCREEN};
 pub struct LayoutPoint {
     /// The point on the saved frame (`"BOTTOMLEFT"`, …).
     pub point: String,
-    /// The frame this anchor is relative to, by name; `None` is the screen root, which is what
-    /// `GetPoint` reports as `nil`.
+    /// The target frame's name; `None` is the screen root, which `GetPoint` reports as `nil`.
     pub relative_to: Option<String>,
     /// The point on the target.
     pub relative_point: String,
-    /// The anchor's x offset, in the frame's own (pre-scale) units — `CAnchor+0x4`.
+    /// `CAnchor+0x4`, in the frame's own pre-scale units.
     pub x: f32,
-    /// The anchor's y offset — `CAnchor+0x8`.
+    /// `CAnchor+0x8`.
     pub y: f32,
 }
 
-/// One user-placed frame's persisted geometry: what a layout cache has to hold to put a window
-/// back exactly where the player left it.
+/// One user-placed frame's persisted geometry.
 #[derive(Clone, Debug, PartialEq)]
 pub struct FrameLayout {
-    /// The frame's global name — how the row is addressed across sessions.
+    /// The frame's global name, which addresses the row across sessions.
     pub name: String,
-    /// The frame's authored width (`LayoutInput::width`), which is what a resize drag writes.
+    /// The frame's authored width (`LayoutInput::width`), which a resize drag writes.
     pub width: f32,
     /// The frame's authored height.
     pub height: f32,
@@ -87,24 +42,11 @@ pub struct FrameLayout {
 }
 
 impl super::UiScript {
-    /// Snapshot every frame the reference's writer would write — the save path.
-    ///
-    /// Sorted by name so the file is stable: a rewrite that reorders its own lines makes every
-    /// diff useless and every "did this change?" check a false positive. Frames whose anchors
-    /// cannot be re-addressed by name are dropped (see the module doc), as are unnamed ones —
-    /// there is nothing to write them under.
-    ///
-    /// **The filter is `userPlaced AND (movable OR resizable)`, not the bit alone.** The
-    /// reference's per-frame writer `0x490e60` tests four conjuncts in a row: a non-NULL name
-    /// (`0x490e79`), a non-empty one (`0x490e82`), `userPlaced` (`0x490e8e test ah,0x10` =
-    /// `0x1000`) and **`movable|resizable`** (`0x490e97 test ah,0x3` = `0x100|0x200`). The bit
-    /// alone was benilla's whole filter until decision 2193, and the missing fourth conjunct is
-    /// what made this cache a one-way ratchet: **every** drag entry stamps `userPlaced`
-    /// (`0x7652b0` @`0x7652e5`, with no cursor-movement dependency), so an addon that windows a
-    /// stock frame and stamps it in passing — `Cartographer/Modules/LookNFeel.lua`'s
-    /// `StartMoving(); StopMovingOrSizing()` over `WorldMapFrame` — wrote a row that outlived
-    /// the addon on every character, forever. The reference drops that row at the first logout
-    /// the addon does not load, because the frame's own `movable`/`resizable` flags went with it.
+    /// Snapshot, sorted by name so the file is stable, every frame the reference's writer
+    /// (`0x490e60`) writes: a non-empty name (`0x490e79`, `0x490e82`), `userPlaced` (`0x490e8e`,
+    /// `0x1000`) and `movable` or `resizable` (`0x490e97`, `0x100|0x200`), with every anchor
+    /// nameable. Every drag stamps `userPlaced` (`0x7652b0` at `0x7652e5`), so the last test is
+    /// what drops the row of a stock frame an addon once moved, once that addon is gone.
     pub fn user_placed_layouts(&self) -> Vec<FrameLayout> {
         let model = self.model_ref();
         let mut out: Vec<FrameLayout> = model
@@ -131,40 +73,22 @@ impl super::UiScript {
         out
     }
 
-    /// Seat saved geometry back onto the frames that still exist — the load path.
-    ///
-    /// Each row is applied whole or not at all: a name this build has no frame for, a point name
-    /// that does not parse, or a target frame that is not loaded leaves the frame on its authored
-    /// anchors rather than half-seated. Restoring **sets the userPlaced bit**, which is what keeps
-    /// the position: `UIParent_ManageFramePositions` skips a user-placed frame, so the managed
-    /// bottom-stack pass does not re-seat the window the player moved.
-    ///
-    /// **The apply is gated per ARM, not per row** (`0x4905e0`, decision 2193): the position arm
-    /// is behind the frame's own `movable` bit (`0x490600 test ah,0x1`) and the size arm behind
-    /// `resizable` (`0x490689 test ah,0x2`) — a frame carrying neither is left entirely alone,
-    /// however old and however stamped its row is. The userPlaced stamp itself lives **inside**
-    /// each arm (`0x49067e` in the position arm, `0x490706` in the size one), after that arm's
-    /// own "the row carries no position" bail
-    /// (`0x490613`, the reference's `X == 0 && Y == 0`; the size arm's twin is `0x49069a`'s
-    /// `W == 0 && H == 0`). Both bails are spelled in this payload's own terms rather than the
-    /// reference's integer sentinels: a row that carries no anchors, and a row that carries no
-    /// size, are the same two states in a format that stores an anchor list instead of an X/Y
-    /// pair.
-    ///
-    /// It marks nothing dirty — the values came *from* the file, and an echo would re-dirty what
-    /// was just read (`set_chat_window_looks`' reasoning, one store over).
+    /// Seat saved geometry back onto the frames that exist, each row whole or not at all. The
+    /// apply is per arm (`0x4905e0`): the position needs `movable` (`0x490600`) and anchors (the
+    /// no-position bail, `0x490613`), the size needs `resizable` (`0x490689`) and a non-zero size
+    /// (`0x49069a`), and each arm that applies stamps `userPlaced` (`0x49067e`, `0x490706`), which
+    /// keeps `UIParent_ManageFramePositions` off the frame. Marks nothing dirty: the values came
+    /// from the file.
     pub fn restore_user_placed_layouts(&mut self, layouts: impl IntoIterator<Item = FrameLayout>) {
         let mut model = self.model_mut();
         for l in layouts {
             let Some(h) = model.arena.lookup(&l.name) else {
-                continue; // a window this build does not have — the file outlives a rename
+                continue; // a window this build does not have
             };
             let mut anchors: Vec<Anchor> = Vec::with_capacity(l.points.len());
             let mut usable = true;
             for p in &l.points {
-                // `frame_id`, not a `frame_to_id` read: ids are minted lazily, so a target frame
-                // that nothing has anchored to yet has none — and refusing the row for that would
-                // make the restore depend on load order.
+                // `frame_id` mints the id lazily, so a target nothing has anchored to yet resolves.
                 let rel = match &p.relative_to {
                     None => Some(SCREEN),
                     Some(n) => model.arena.lookup(n).map(|t| model.frame_id(t)),
@@ -210,32 +134,26 @@ impl super::UiScript {
                 input.width = l.width;
                 input.height = l.height;
             }
-            // The stamp is EACH arm's, not the row's: the position arm's is `0x49067e` and the
-            // size arm's `0x490706`, both inside their own gate. A frame that took neither is
-            // left un-stamped, which is what lets its row fall out of the file.
+            // Only an arm that applied stamps, so a row neither arm took falls out of the file.
             if seat_position || seat_size {
                 if let Some(f) = model.arena.frame_mut(h) {
                     f.user_placed = true;
                 }
             }
             if changed {
-                // The whole graph, not the frame alone: a restore REPOINTS anchors (a saved row
-                // may name a different target than the authored one), and decision 1388's
-                // frame-scoped touch is only valid while every anchor keeps its target.
+                // The whole graph, not the frame: a restored row may repoint an anchor.
                 model.touch_layout();
             }
         }
     }
 
-    /// Has a user-placed frame moved or resized since the last call? The host's cue to persist —
-    /// a single bit rather than a set, because the file is written whole either way.
+    /// Whether a user-placed frame moved or resized since the last call: the host's cue to persist.
     pub fn take_user_placed_change(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().user_placed_changed)
     }
 }
 
-/// One live anchor → its saved form, or `None` when the target cannot be named across a session
-/// (an unnamed frame, or a region — see the module doc).
+/// An anchor's saved form, or `None` when its target is an unnamed frame or a region.
 fn saved_point(model: &Model, a: &Anchor) -> Option<LayoutPoint> {
     let relative_to = if a.relative_to == SCREEN {
         None
diff --git a/crates/benilla-ui/src/script/loot.rs b/crates/benilla-ui/src/script/loot.rs
index 5bd75bd2..89fa132d 100644
--- a/crates/benilla-ui/src/script/loot.rs
+++ b/crates/benilla-ui/src/script/loot.rs
@@ -1,201 +1,104 @@
-//! The loot bindings (decision 0084) — the Era-shaped loot-window surface, the same two-way seam as
-//! [`super::merchant`]/[`super::container`]/[`super::gossip`]: the app pushes a **loot snapshot**
-//! ([`UiScript::set_loot`] — the rows already resolved from the wire to name/icon/quantity/quality by
-//! the app's item stores, with the synthesized coin row first) and the Lua `LootSlot`/`CloseLoot`
-//! calls queue outbound **intents** the app drains ([`UiScript::take_loot_picks`] /
-//! [`UiScript::take_loot_close`]). The engine holds no loot knowledge — a row is "a name, an icon
-//! path, a quantity, a quality, and whether it's the coin pile".
+//! The loot-window bindings: the app pushes the open loot ([`UiScript::set_loot`]), a coin row
+//! first when there is gold, and the Lua verbs queue intents it drains. `slot` is 1-based; the app
+//! maps a row to the money intent or the item's wire slot, which Lua never sees.
 //!
-//! ## The Era API shape
-//!
-//! 1.12's loot API is a flat set of globals the FrameXML `LootFrame.lua` drives (VERIFIED against the
-//! extracted `LootFrame.lua`, scratchpad): `GetNumLootItems()`, `GetLootSlotInfo(slot)` →
-//! `texture, item, quantity, quality` (`LootFrame.lua:81`), `LootSlotIsItem(slot)` /
-//! `LootSlotIsCoin(slot)` (`LootFrame.lua:80`), `GetLootSlotLink(slot)` → the row's item link (what
-//! the row click's ctrl/shift arms read, `LootFrame.lua:149`/`:152` — decision 1059),
-//! and `CloseLoot()` (fired from `OnHide`, `LootFrame.lua:143-145`). `slot` is **1-based**; an
-//! out-of-range slot answers `nil`.
-//!
-//! ## The take is TWO verbs, not one (decision 1744)
-//!
-//! `LootSlot(slot)` looks like "loot row n" and is not: in 1.12 it is the **LOOT_BIND confirmation
-//! continuation** alone. The C dispatcher `0x4c2790(slot, flag)` takes the row only on `flag == 0`,
-//! which no Lua binding reaches — the row click is the C `CLootButton`'s own behaviour — while
-//! `LootSlot 0x4c2e70` passes `flag = 1`, whose arm refuses every slot but the one a bind confirm
-//! is pending for. benilla builds that widget — [`crate::widget::FrameKind::LootButton`], decision
-//! 1799 — so the row click's take runs where the reference runs it, in `script::button`'s click
-//! path under the same no-modifier gate; `BenillaTakeLootSlot` is the Lua-reachable entry to the
-//! same queue, and `LootSlot` keeps the reference's meaning exactly.
-//!
-//! The **coin pile is a synthesized client-side row** (first in the list when the loot carries gold):
-//! `LootSlotIsCoin` is true for it, its `item` text is the formatted money amount, and `LootSlot(1)`
-//! on it queues the money intent. The app maps a clicked 1-based row to either the money intent or the
-//! wire loot slot the item lives at (`CMSG_AUTOSTORE_LOOT_ITEM` addresses the **wire** slot, which is
-//! *not* the 1-based display position once a coin row is prepended or a row is removed) — the Lua side
-//! never sees the wire slot, exactly as the merchant's Lua side never sees the item entry.
-//!
-//! ## Master loot (decision 1675)
-//!
-//! Two more globals ride the same seam when the group's loot method is master loot:
-//! `GetMasterLootCandidate(index)` reads [`LootState::master_candidates`] (names, 1-based, dense)
-//! and `GiveMasterLoot(slot, candidateIndex)` queues an assignment the app resolves to a wire slot
-//! and a recipient guid. The *decision* to open the dropdown is not Lua's: the app fires
-//! `OPEN_MASTER_LOOT_LIST` when a picked row's wire `slot_type` is `MASTER`, which is where the
-//! real client puts it too — its take dispatcher branches on the same byte before any Lua runs.
+//! `LootSlot` is only the LOOT_BIND confirmation: `0x4c2e70` passes flag 1 to the take dispatcher
+//! `0x4c2790`, which then refuses every slot but the pending one. The take itself is flag 0, the
+//! row click of [`crate::widget::FrameKind::LootButton`]. Master loot's dropdown opens from the
+//! app, on a picked row whose wire `slot_type` is `MASTER`, as the dispatcher branches on that byte
+//! before any Lua runs.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
 use super::binding_abi::flag;
 use super::Model;
 
-/// `CLootButton`'s own Lua method table (`0x847ce4`) — see [`crate::widget::FrameKind::LootButton`].
-/// Exactly one entry, and the count is read off the registrar's `mov edx,1` rather than off a run
-/// length, so it cannot drift.
+/// `CLootButton`'s own Lua method table (`0x847ce4`): one entry, per the registrar's `mov edx,1`.
 pub(super) const REG_LOOTBUTTON_METHODS: &str = "__benilla_lootbutton_methods";
 
-/// The **item-cache miss** quality `GetLootSlotInfo` answers for a row whose item template has not
-/// landed yet — the reference's own sentinel, and emphatically **not** a nil. `0x4c23a0` reads the
-/// item-cache record's `[rec+0x1c]` and hands back `-1` when the cache has no record for the id
-/// (wow-re `system/ui/scratch/loot-slot-record.md` §4, a §5 trio round).
-///
-/// It is why stock `UIParent.lua` builds `ITEM_QUALITY_COLORS` over **`for i = -1, 6`** (l.66):
-/// index `-1` exists *for this value*. `LootFrame_Update` indexes the table with the raw return and
-/// no guard — `color = ITEM_QUALITY_COLORS[quality]` (`LootFrame.lua:82`), dereferenced one line
-/// later at `color.r` (`:85`) — so a nil here is a Lua runtime error on every loot opened before
-/// its templates arrive, which is every loot on a cold item cache (decision 1805).
+/// The quality `GetLootSlotInfo` answers on an item-cache miss: the reference's -1 (`0x4c23a0`),
+/// never nil. Stock `UIParent.lua:66` builds `ITEM_QUALITY_COLORS` from -1, and `LootFrame_Update`
+/// indexes it unguarded (`LootFrame.lua:82`), so a nil would raise on a cold cache.
 const CACHE_MISS_QUALITY: i64 = -1;
 
-/// The row text on that same miss. The reference composes every loot row's name through `0x5d8b00`,
-/// which leaves its destination buffer **empty** when the item cache has no record (`0x5d8b25`
-/// stores the terminator and returns); the binding then pushes that empty string. Four values, one
-/// of them `""` — never three values, and never a nil.
+/// The row text on that miss: `0x5d8b00` leaves its buffer empty with no cache record
+/// (`0x5d8b25`), and the binding pushes that empty string.
 const CACHE_MISS_NAME: &str = "";
 
-/// The icon on an `ItemDisplayInfo` miss — a row that HAS an item, whose display id the catalog has
-/// no icon for. The reference appends the literal `INV_Misc_QuestionMark` (`0x847fe4`, `0x4c252b`)
-/// to the same `StringLookups.dbc` row-3 prefix (`Interface\\Icons`) a hit uses.
-///
-/// It is deliberately **not** the answer for a slot with no item: `0x4c2460` returns NULL on each of
-/// its three guards (`0x4c2470` no window, `0x4c24a6` out of range, `0x4c24b7` itemId == 0) and
-/// `lua_pushstring 0x6f3890` tail-jumps a NULL to `lua_pushnil`. The question mark needs a live
-/// itemId to be reached at all.
+/// The icon for a row with an item but no display icon: `INV_Misc_QuestionMark` (`0x847fe4`,
+/// `0x4c252b`). A slot with no item gets nil instead: `0x4c2460` returns NULL on its three guards
+/// (`0x4c2470`, `0x4c24a6`, `0x4c24b7`), which `lua_pushstring 0x6f3890` pushes as nil.
 const MISSING_ICON: &str = "Interface\\Icons\\INV_Misc_QuestionMark";
 
-/// The quality a slot with **no item at all** answers — a slot past the end, Lua slot 0, or any slot
-/// while no loot window is open. `0x4c23a0` returns 0 on each of its three guards, and the binding
-/// `fild`s that. Distinct from [`CACHE_MISS_QUALITY`]: a **cleared** slot still has a record, whose
-/// itemId is now 0, and `0x55ba30` short-circuits an entryId of 0 to a NULL record
-/// (`0x55ba3d`/`0x55ba42`) — a guaranteed cache miss, so it takes the `-1` arm at `0x4c2435`.
+/// The quality of a slot with no item (past the end, slot 0, no window): `0x4c23a0`'s guards
+/// return 0. A cleared slot takes -1 instead: its itemId is 0, which `0x55ba30` turns into a NULL
+/// record (`0x55ba3d`/`0x55ba42`), the cache-miss arm at `0x4c2435`.
 const NO_SLOT_QUALITY: i64 = 0;
 
-/// One loot-window row, resolved by the app (decision 0084). Plain data — its 1-based order in the
-/// window is its position in [`LootState::rows`]; the coin row (when present) is always position 1.
+/// One loot-window row, resolved by the app; its 1-based slot is its place in [`LootState::rows`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct LootRow {
-    /// The row text (`GetLootSlotInfo`'s `item` return): an item's name, or the coin row's formatted
-    /// money amount. `None` while the ask-once item-template query is still in flight (items only —
-    /// the coin row's text is always set), and the API reports [`CACHE_MISS_NAME`] — the empty
-    /// string the reference's own name formatter leaves behind on a cache miss — never a nil.
+    /// Item name or the coin's money text; `None` while in flight, answered as [`CACHE_MISS_NAME`].
     pub name: Option<String>,
-    /// Icon texture path (`Interface\Icons\…` — from the wire `display_info_id`, or the coin
-    /// texture). `None` only if the display catalog had no icon for the id, which the API reports as
-    /// [`MISSING_ICON`], the reference's own `INV_Misc_QuestionMark`.
+    /// Icon path; `None` without a display icon, answered as [`MISSING_ICON`].
     pub texture: Option<String>,
-    /// The stack size looted (`GetLootSlotInfo`'s `quantity`); the coin row is always `1`.
+    /// Stack size looted; 1 for the coin row.
     pub quantity: u32,
-    /// Item quality 0..6, for the quality-coloured row text; `None` while the template is in flight,
-    /// which the API reports as [`CACHE_MISS_QUALITY`] (`-1`, the reference's cache-miss sentinel and
-    /// a real row of `ITEM_QUALITY_COLORS`) — never a nil, which is what raised in the stock
-    /// `LootFrame_Update` (decision 1805). The coin row carries a fixed quality.
+    /// Quality 0..6; `None` while the template is in flight, answered as [`CACHE_MISS_QUALITY`].
     pub quality: Option<u32>,
-    /// Whether this is the synthesized coin pile (`LootSlotIsCoin` true, `LootSlotIsItem` false).
+    /// The synthesized coin pile (`LootSlotIsCoin` true, `LootSlotIsItem` false).
     pub is_coin: bool,
-    /// The item id — the shared item-tooltip store's key (`BenillaGetItemStats`); `0` for the coin
-    /// row. A benilla extension riding as a TRAILING return of `GetLootSlotInfo` (the era 4-tuple
-    /// never carried it; tooltip content was C++'s alone), same idiom as the quest item getters.
+    /// The tooltip store's key, 0 for the coin row: `GetLootSlotInfo`'s fifth return, not 1.12's.
     pub item_id: u32,
-    /// The row's full escaped `|cff…|Hitem:…|h[Name]|h|r` link (`GetLootSlotLink`, decision 1059).
-    /// `None` for the synthesized coin row (there is no item to link) and while the ask-once
-    /// template answer is in flight — the link embeds the name, so it cannot exist before `name`
-    /// does; the same `Option` shape [`super::char_stats::InvSlotView::link`] carries. Both arms of
-    /// the STOCK row click take a nil in stride: `DressUpItemLink` returns on one (its own guard,
-    /// `DressUpFrame.lua:10-16`), and `ChatFrameEditBox:Insert` takes an `Option<String>`
-    /// ([`super::editbox`]) so the other drops it silently.
+    /// `GetLootSlotLink`'s answer; `None` for the coin row and while the template is in flight.
     pub link: Option<String>,
-    /// The wire's `randomPropertyId` — the drop's **random-suffix roll**, the id the tooltip
-    /// resolves against [`super::Model::random_properties`] for its enchant lines (decision 1547).
-    /// `0` = unrolled.
-    ///
-    /// The client keeps exactly this, at `+0x14` of its own 0x1c-byte loot record, and
-    /// `SetLootItem 0x533470` copies it into the tooltip's `+0x424` — a loot slot is **not** an
-    /// item object (that leg passes an all-zero item guid), so the roll is the only enchant source
-    /// a loot hover can have (wow-re `loot-slot-record.md`, `tooltip-content-law.md` §E6-LOOT).
-    /// [`Self::name`] already carries the suffix the same id joins on.
+    /// The drop's random-suffix roll (`randomPropertyId`, 0 unrolled), resolved by the tooltip
+    /// against [`super::Model::random_properties`]. A loot slot is no item object, so this is its
+    /// only enchant source (`SetLootItem 0x533470` copies it from the loot record's `+0x14`).
     pub random_property_id: u32,
 }
 
-/// One open loot window: its rows (coin first when present). Pushed whole by the app; `None` means no
-/// loot is open (the window is closed).
+/// One open loot window, pushed whole by the app; `None` means no loot is open.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct LootState {
-    /// The window's **fixed** slot list: positions never shift while the window is open. A looted
-    /// slot becomes `None` — still counted by `GetNumLootItems` (the reference's slot array keeps
-    /// cleared slots; `LootFrame.numLootItems` is captured once at `OnShow`, l.132) but neither
-    /// `LootSlotIsItem` nor `LootSlotIsCoin`, which is exactly how the reference's
-    /// `LootFrame_Update` leaves a cleared slot's button hidden in place (`LootFrame.lua:80`)
-    /// instead of collapsing the rows below it upward.
+    /// The fixed slot list. A looted slot becomes `None`: still counted by `GetNumLootItems`, read
+    /// once at `OnShow` (`LootFrame.lua:132`), but neither item nor coin, so `LootFrame_Update`
+    /// hides its button in place (`LootFrame.lua:80`).
     pub rows: Vec<Option<LootRow>>,
-    /// Whether this loot came from fishing (`IsFishingLoot()` — the wire `SMSG_LOOT_RESPONSE`
-    /// `loot_type == 3`, decision 1086). `LootFrame_OnShow` keys the "FISHING REEL IN" sound and
-    /// the FishingLoot portrait overlay on it (`LootFrame.lua:137-140`).
+    /// `IsFishingLoot` (wire `loot_type` 3): the reel-in sound and portrait (`LootFrame.lua:137`).
     pub fishing: bool,
-    /// The master-loot candidate slots — what `GetMasterLootCandidate(i)` answers for a 1-based
-    /// `i` (decision 1675). Empty unless the group's loot method is master loot and the server
-    /// sent `SMSG_LOOT_MASTER_LIST` for this window.
-    ///
-    /// **A `None` is a real slot that answers nil**, not padding, and the list is deliberately
-    /// not packed: in a raid the client files each candidate into its own subgroup's five-slot
-    /// block, so index `i` carries which raid group the candidate is in. That is what lets
-    /// `GroupLootDropDown_Initialize` walk `1..40` in blocks of five and label each block
-    /// "Group N" (`LootFrame.lua:186-212`). A `None` also covers a candidate whose name has not
-    /// resolved yet — the binding pushes nil for that too, and `UPDATE_MASTER_LOOT_LIST` exists
-    /// to repaint the menu when it lands.
-    ///
-    /// Names, not guids: the seam's standing division is that Lua speaks names and 1-based
-    /// indices while the app owns guids and wire slots, and `GroupLootDropDown_Initialize` puts
-    /// this string straight into `info.text` (`LootFrame.lua:181`/`:229`).
+    /// The names `GetMasterLootCandidate(i)` answers by 1-based slot, from `SMSG_LOOT_MASTER_LIST`.
+    /// Not packed: in a raid each candidate sits in their subgroup's five-slot block, which the
+    /// dropdown labels "Group N" (`LootFrame.lua:197-213`). A `None` (an empty slot, or a name not
+    /// yet resolved) answers nil.
     pub master_candidates: Vec<Option<String>>,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open loot's row snapshot.
+    /// Push (or clear, with `None`) the open loot.
     pub fn set_loot(&mut self, state: Option<LootState>) {
         self.model_mut().loot = state;
     }
 
-    /// Drain the 1-based row indices queued by `BenillaTakeLootSlot` since the last call — the ROW
-    /// CLICK's take. The app maps each to either the coin (money) intent or the item's wire loot
-    /// slot, and applies the bind-on-pickup deferral (decision 1744).
+    /// Drain the 1-based rows the row click took; the app maps each to the coin or the item's wire
+    /// slot and applies the bind-on-pickup deferral.
     pub fn take_loot_picks(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().loot_picks)
     }
 
-    /// Drain the 1-based row indices queued by `LootSlot` — the LOOT_BIND confirmation
-    /// continuations. Each is honoured only if it names the row the app is actually holding a
-    /// confirm open for (the reference's `[0x847cec]` gate); anything else is dropped.
+    /// Drain the 1-based rows `LootSlot` queued; the app honours only the one a LOOT_BIND confirm
+    /// is pending for (the reference's `[0x847cec]` gate).
     pub fn take_loot_confirms(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().loot_confirms)
     }
 
-    /// Whether `CloseLoot` was called since the last drain (and clear the flag). The app maps this to
-    /// `CMSG_LOOT_RELEASE` when a loot is open.
+    /// Whether `CloseLoot` was called since the last drain; the app releases an open loot.
     pub fn take_loot_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().loot_close)
     }
 
-    /// Drain the `GiveMasterLoot(slot, candidateIndex)` assignments queued since the last call —
-    /// both 1-based display numbers. The app resolves the row to its wire slot and the candidate
-    /// to a guid, then sends `CMSG_LOOT_MASTER_GIVE` (decision 1675).
+    /// Drain the `GiveMasterLoot(slot, candidateIndex)` pairs, both 1-based; the app resolves them
+    /// to a wire slot and a guid for `CMSG_LOOT_MASTER_GIVE`.
     pub fn take_loot_master_gives(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().loot_master_gives)
     }
@@ -205,9 +108,7 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumLootItems() → the number of slots the open loot has, cleared ones included (0 when none
-    // is open). Constant while a window is open — the reference reads it once at OnShow (l.132) and
-    // never again; ours is invariant by construction, so the live read is the same value.
+    // GetNumLootItems(): cleared slots included, so it holds still while a window is open.
     g.set(
         "GetNumLootItems",
         lua.create_function(|lua, ()| {
@@ -216,28 +117,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootSlotInfo(slot) → texture, item, quantity, quality — the reference's four, in its order
-    // (`0x4c2c60`, `mov eax,4` at `0x4c2d07`; `LootFrame.lua:81`). `slot` is 1-based.
-    //
-    // **It answers four values on every leg — never three, never a bare nil** (decision 1805).
-    // A slot with no item at all (past the end, slot 0, no window) is `nil, "", 0, 0`; a CLEARED
-    // slot is `nil, "", 0, -1`, because its record survives with a zeroed itemId and that is a
-    // guaranteed item-cache miss.
-    //
-    // A LIVE row is the same story one level down: each producer has a sentinel for the case where
-    // the value it wants is not resolved yet — [`CACHE_MISS_QUALITY`] (`-1`) and [`CACHE_MISS_NAME`]
-    // (`""`) while the item template is in flight, [`MISSING_ICON`] when the display catalog has no
-    // icon for the wire display id. The quality is the load-bearing one: the reference's
-    // `ITEM_QUALITY_COLORS` has a `-1` row precisely so this value can index it.
-    //
-    // The in-flight row is nonetheless one the REFERENCE never paints, because it does not open the
-    // window until every template has landed ([`crate::script`] has no say in that; the app's
-    // `ui_loot` holds `LOOT_OPENED` back). These sentinels are the floor under that, not the plan.
+    // GetLootSlotInfo(slot) → texture, item, quantity, quality (`0x4c2c60`, `LootFrame.lua:81`),
+    // four on every leg (`0x4c2d07 mov eax,4`): no item is `nil, "", 0, 0`, a cleared slot
+    // `nil, "", 0, -1`. The miss sentinels are a floor: the reference opens no window before every
+    // template lands, and the app holds `LOOT_OPENED` back likewise.
     g.set(
         "GetLootSlotInfo",
         lua.create_function(|lua, slot: usize| {
-            // `Some(Some(row))` is a live row; `Some(None)` is a CLEARED one (the slot survives with
-            // its record zeroed); `None` is no such slot at all.
+            // `Some(Some(row))` live, `Some(None)` cleared, `None` no such slot.
             let slot_state = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 model
@@ -247,10 +134,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     .cloned()
             };
             let Some(Some(row)) = slot_state else {
-                // No row — and the reference still pushes four (`0x4c2d07 mov eax,4` is
-                // unconditional; there is no short-return path). A cleared slot's record has a
-                // zeroed itemId, which `0x55ba30` short-circuits to a NULL cache record, so it takes
-                // the cache-miss quality where a genuinely absent slot takes the guard's zero.
                 let cleared = slot_state.is_some();
                 return Ok(MultiValue::from_vec(vec![
                     Value::Nil,
@@ -261,7 +144,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     } else {
                         NO_SLOT_QUALITY
                     }),
-                    // Benilla's trailing item id: there is no item here.
+                    // The trailing item id: none here.
                     Value::Integer(0),
                 ]));
             };
@@ -275,19 +158,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 item,
                 Value::Integer(i64::from(row.quantity)),
                 quality,
-                // Benilla extension (5th): the item id, the shared tooltip store's key.
+                // The item id, a fifth return that is not a 1.12 value.
                 Value::Integer(i64::from(row.item_id)),
             ]))
         })?,
     )?;
 
-    // GetLootSlotLink(slot) → the row's full escaped `|cff…|Hitem:…|h[Name]|h|r` link | nil. 1-based
-    // like GetLootSlotInfo beside it; nil out of range, nil for the coin row, and nil while the
-    // item-template query is in flight (the link embeds the name). The reference's row click reads
-    // it for BOTH modifier arms — `DressUpItemLink(GetLootSlotLink(this.slot))` (`LootFrame.lua:149`)
-    // and `ChatFrameEditBox:Insert(GetLootSlotLink(this.slot))` (`:152`). Since 1751 put the stock
-    // file on the chain both of those are the live call sites — our own `BenillaChatEdit_InsertLink`
-    // detour is not on this path any more — and both survive the nil on their own. Decision 1059.
+    // GetLootSlotLink(slot): nil out of range, for the coin row and while the template is in
+    // flight. The stock row click hands it to `DressUpItemLink` (`LootFrame.lua:149`) and
+    // `ChatFrameEditBox:Insert` (`:152`), both of which take a nil.
     g.set(
         "GetLootSlotLink",
         lua.create_function(|lua, slot: usize| {
@@ -306,7 +185,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LootSlotIsItem(slot) → true for a real item row (in range, not the coin pile, not cleared).
     g.set(
         "LootSlotIsItem",
         lua.create_function(|lua, slot: usize| {
@@ -318,8 +196,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LootSlotIsCoin(slot) → true for the synthesized coin pile row (false once it's been looted —
-    // the cleared slot stays in the count but answers neither predicate, `LootFrame.lua:80`).
     g.set(
         "LootSlotIsCoin",
         lua.create_function(|lua, slot: usize| {
@@ -331,9 +207,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsFishingLoot() → 1/nil, whether the open loot came from fishing (nil when none is open).
-    // `LootFrame_OnShow` keys the reel-in sound + the fishing portrait overlay on it
-    // (`LootFrame.lua:137-140`; decision 1086).
     g.set(
         "IsFishingLoot",
         lua.create_function(|lua, ()| {
@@ -342,16 +215,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── `LootButton`'s own method table — ONE entry, and this is it ─────────────────────────────
+    // ── `LootButton`'s own method table ──────────────────────────────────────────────────────
     //
-    // `SetSlot(index)` (`0x4c1880`, table `0x847ce4`, the registrar's own `mov edx,1` says count
-    // 1). 1-based in, **0-based stored** (`ftol` then `dec eax` into `[this+0x4dc]`), and it
-    // pushes nothing. `LootFrame.lua:94`'s `button:SetSlot(slot)` is its only caller in the
-    // shipped UI — the row's `id="N"` does NOT feed it.
-    //
-    // A non-number raises the client's own usage string. That is worth transcribing exactly: it
-    // is the one place this class talks to a caller, and `LootFrame.lua` would surface a typo'd
-    // call as this text.
+    // `SetSlot(index)` (`0x4c1880`): 1-based in, 0-based stored (`ftol`, `dec eax` into
+    // `[this+0x4dc]`), no returns; a non-number raises the client's usage string. Its one stock
+    // caller is `LootFrame.lua:94`; the row's `id` does not feed it.
     {
         let m = lua.create_table()?;
         m.set(
@@ -360,16 +228,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let n = match &index {
                     Value::Integer(i) => *i as f64,
                     Value::Number(n) => *n,
-                    // `lua_isnumber` accepts a numeric string, as everywhere else in this image.
+                    // `lua_isnumber` accepts a numeric string.
                     Value::String(s) => match s.to_str().ok().and_then(|s| s.parse::<f64>().ok()) {
                         Some(n) => n,
                         None => return Err(mlua::Error::runtime("Usage: SetSlot(index)")),
                     },
                     _ => return Err(mlua::Error::runtime("Usage: SetSlot(index)")),
                 };
-                // `ftol` truncates toward zero, then `dec`. A slot below 1 leaves the row taking
-                // nothing rather than wrapping — the reference stores the decrement raw, but its
-                // consumer is a bounds-checked table walk and ours is an Option.
+                // `ftol` truncates toward zero, then `dec`; below 1 takes nothing, as the
+                // reference's bounds-checked consumer of the raw decrement does.
                 let slot = (n.trunc() >= 1.0).then(|| n.trunc() as u32 - 1);
                 super::button::set_loot_slot(lua, &this, slot)?;
                 Ok(())
@@ -378,16 +245,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.set_named_registry_value(REG_LOOTBUTTON_METHODS, m)?;
     }
 
-    // BenillaTakeLootSlot(slot) — the ROW CLICK's take, queued as a 1-based display row; the app
-    // maps it to the coin or the item's wire slot and applies the bind-on-pickup gate.
-    //
-    // Why this is not `LootSlot`, and why the name is ours (decision 1744): in 1.12 the plain take
-    // is **not a Lua binding at all**. The dispatcher `0x4c2790(slot, flag)` has exactly two
-    // callers — the C `CLootButton::OnClick 0x4c1820` with `flag = 0`, and the `LootSlot` binding
-    // `0x4c2e70` with `flag = 1` — and only the `flag = 0` arm reaches the take. benilla has no
-    // `CLootButton` widget type (our rows are ordinary XML buttons), so the click arm needs a verb,
-    // and giving it the 1.12 NAME would have handed `LootSlot` a second meaning the reference does
-    // not give it. `Benilla`-prefixed like the other seams the reference kept in C.
+    // BenillaTakeLootSlot(slot): not a 1.12 verb. It queues the row click's take by 1-based row,
+    // which has no Lua binding in the reference: only `CLootButton::OnClick 0x4c1820` reaches the
+    // dispatcher `0x4c2790` with flag 0.
     g.set(
         "BenillaTakeLootSlot",
         lua.create_function(|lua, slot: u32| {
@@ -397,11 +257,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LootSlot(slot) — the LOOT_BIND **confirmation continuation**, and nothing else, exactly as
-    // 1.12 has it (`0x4c2e70`: `luaL_checknumber(1)`, `dec eax`, `0x4c2790(slot, flag = 1)`; the
-    // flag-1 arm at `0x4c27c0` starts `cmp edi, [0x847cec]` and returns unless the slot IS the
-    // pending confirm). So an addon calling `LootSlot(n)` on an ordinary row does nothing here,
-    // which is what it does on the real client; the app owns the pending-slot gate.
+    // LootSlot(slot): the LOOT_BIND confirmation only (`0x4c2e70`: `luaL_checknumber(1)`,
+    // `dec eax`, `0x4c2790(slot, 1)`, whose arm at `0x4c27c0` returns unless the slot is the
+    // pending confirm, `cmp edi, [0x847cec]`). On an ordinary row it does nothing.
     g.set(
         "LootSlot",
         lua.create_function(|lua, slot: u32| {
@@ -411,9 +269,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseLoot([failed]) — flag the release intent. The optional arg (the client's "couldn't open
-    // the UI" signal, `LootFrame.lua:18`) is accepted and ignored; the app decides whether to send a
-    // release (only when a loot is actually open).
+    // CloseLoot([failed]): the "unable to open the UI" argument (`LootFrame.lua:18`) is ignored.
     g.set(
         "CloseLoot",
         lua.create_function(|lua, _args: MultiValue| {
@@ -423,13 +279,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMasterLootCandidate(index) → the 1-based candidate's NAME, or nil past the end.
-    //
-    // `GroupLootDropDown_Initialize` probes this sparsely and relies entirely on the nil:
-    // the party arm walks `1..MAX_PARTY_MEMBERS+1` and the raid arm walks `1..40` in blocks of
-    // five, keeping a "Group N" submenu only where the block's first probe answered non-nil
-    // (`LootFrame.lua:169-232`). So an out-of-range index must answer nil rather than raise, and
-    // the list must be DENSE — a hole would silently drop a candidate from the menu.
+    // GetMasterLootCandidate(index): nil, never an error, out of range or on an empty slot, since
+    // `GroupLootDropDown_Initialize` probes slots 1-5 in a party and 1-40 in a raid and reads nil
+    // as nobody (`LootFrame.lua:168-232`).
     g.set(
         "GetMasterLootCandidate",
         lua.create_function(|lua, index: u32| {
@@ -446,9 +298,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GiveMasterLoot(slot, candidateIndex) — queue the assignment; the app owns the wire slot and
-    // the recipient guid. Called from the dropdown's own handler for a below-threshold item and
-    // from the CONFIRM_LOOT_DISTRIBUTION popup's OnAccept above it (`LootFrame.lua:236-244`,
+    // GiveMasterLoot(slot, candidateIndex): from the dropdown below the quality threshold, and from
+    // the `CONFIRM_LOOT_DISTRIBUTION` popup above it (`LootFrame.lua:234-244`,
     // `StaticPopup.lua:85-94`).
     g.set(
         "GiveMasterLoot",
@@ -471,7 +322,6 @@ mod tests {
         LootState {
             master_candidates: Vec::new(),
             rows: vec![
-                // The coin pile, always first. No link: there is no item to link (decision 1059).
                 Some(LootRow {
                     item_id: 0,
                     name: Some("1g 23s 45c".into()),
@@ -482,7 +332,6 @@ mod tests {
                     link: None,
                     random_property_id: 0,
                 }),
-                // A resolved item — name, quality AND link all landed together (one template answer).
                 Some(LootRow {
                     item_id: 0,
                     name: Some("Wool Cloth".into()),
@@ -493,7 +342,7 @@ mod tests {
                     link: Some("|cffffffff|Hitem:2589:0:0:0|h[Wool Cloth]|h|r".into()),
                     random_property_id: 0,
                 }),
-                // An in-flight item: the loot arrived, the item-template answer hasn't.
+                // In flight: the loot arrived, its item template has not.
                 Some(LootRow {
                     item_id: 0,
                     name: None,
@@ -512,14 +361,12 @@ mod tests {
     #[test]
     fn loot_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
-        // No loot open: count 0, info nil.
         assert_eq!(s.eval::<i64>("return GetNumLootItems()").unwrap(), 0);
         assert!(s.eval::<bool>("return GetLootSlotInfo(1) == nil").unwrap());
 
         s.set_loot(Some(loot()));
         assert_eq!(s.eval::<i64>("return GetNumLootItems()").unwrap(), 3);
 
-        // Row 1: the coin pile — IsCoin true, IsItem false, its text the money amount.
         assert!(s.eval::<bool>("return LootSlotIsCoin(1)").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsItem(1)").unwrap());
         let (texture, item, quantity, quality) = s
@@ -529,7 +376,6 @@ mod tests {
         assert_eq!(item, "1g 23s 45c");
         assert_eq!((quantity, quality), (1, 1));
 
-        // Row 2: a resolved item — IsItem true, IsCoin false, quantity + quality present.
         assert!(s.eval::<bool>("return LootSlotIsItem(2)").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsCoin(2)").unwrap());
         let (name, qty) = s
@@ -537,10 +383,7 @@ mod tests {
             .unwrap();
         assert_eq!((name.as_str(), qty), ("Wool Cloth", 3));
 
-        // Row 3: in flight — the reference's cache-miss SENTINELS, not nils (decision 1805). The
-        // quality is the load-bearing one: stock `LootFrame_Update` does
-        // `ITEM_QUALITY_COLORS[quality].r` with no guard, and `-1` is a real row of that table
-        // (`UIParent.lua` builds it `for i = -1, 6`) while a nil is a runtime error.
+        // Row 3 is in flight: the cache-miss sentinels, not nils.
         let (texture, item, quantity, quality) = s
             .eval::<(String, String, i64, i64)>("return GetLootSlotInfo(3)")
             .unwrap();
@@ -550,7 +393,6 @@ mod tests {
             "an in-flight row answers \"\" / -1, never nil"
         );
         assert_eq!(texture, "Interface\\Icons\\INV_Misc_QuestionMark");
-        // …and the same row with NO display-info icon either still answers a texture path.
         let mut iconless = loot();
         iconless.rows[2].as_mut().unwrap().texture = None;
         s.set_loot(Some(iconless));
@@ -561,8 +403,6 @@ mod tests {
         );
         s.set_loot(Some(loot()));
 
-        // GetLootSlotLink: the resolved item's link, nil for the coin row and for the in-flight one
-        // (both arms of the reference's row click hand this straight on — decision 1059).
         assert_eq!(
             s.eval::<String>("return GetLootSlotLink(2)").unwrap(),
             "|cffffffff|Hitem:2589:0:0:0|h[Wool Cloth]|h|r"
@@ -570,8 +410,6 @@ mod tests {
         assert!(s.eval::<bool>("return GetLootSlotLink(1) == nil").unwrap());
         assert!(s.eval::<bool>("return GetLootSlotLink(3) == nil").unwrap());
 
-        // IsFishingLoot: false on an ordinary loot, true when the snapshot says fishing, false
-        // again with no loot open (decision 1086).
         assert!(s.eval::<bool>("return not IsFishingLoot()").unwrap());
         let mut fished = loot();
         fished.fishing = true;
@@ -579,16 +417,13 @@ mod tests {
         assert!(s.eval::<bool>("return IsFishingLoot()").unwrap());
         s.set_loot(Some(loot()));
 
-        // Out of range → nil.
         assert!(s.eval::<bool>("return GetLootSlotInfo(9) == nil").unwrap());
         assert!(s.eval::<bool>("return GetLootSlotLink(9) == nil").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsItem(9)").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsCoin(9)").unwrap());
 
-        // A CLEARED slot (looted): still counted — the slot list is fixed while the window is open,
-        // the reference's own shape (`LootFrame.numLootItems` is read once at OnShow) — but it
-        // answers neither predicate and nil info/link, so the frame hides that button in place
-        // instead of collapsing the rows below it.
+        // A looted slot stays counted but answers neither predicate, and the rows below keep
+        // their slots.
         let mut cleared = loot();
         cleared.rows[0] = None;
         s.set_loot(Some(cleared));
@@ -597,23 +432,18 @@ mod tests {
         assert!(s.eval::<bool>("return GetLootSlotLink(1) == nil").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsItem(1)").unwrap());
         assert!(s.eval::<bool>("return not LootSlotIsCoin(1)").unwrap());
-        // …and the rows below keep their own slots.
         assert!(s.eval::<bool>("return LootSlotIsItem(2)").unwrap());
     }
 
-    /// The master-loot half of the seam (decision 1675). `GetMasterLootCandidate` must answer nil
-    /// past the end rather than raise — `GroupLootDropDown_Initialize` probes it sparsely (the
-    /// raid arm walks 1..40 in blocks of five) and reads the nil as "nobody here".
     #[test]
     fn master_loot_candidates_read_1_based_and_nil_past_the_end() {
         let mut s = UiScript::new().unwrap();
 
-        // No loot open at all: nil, not an error.
         assert!(s
             .eval::<bool>("return GetMasterLootCandidate(1) == nil")
             .unwrap());
 
-        // A window with no candidate list (any loot method but master): still nil everywhere.
+        // No candidate list: any loot method but master.
         s.set_loot(Some(loot()));
         assert!(s
             .eval::<bool>("return GetMasterLootCandidate(1) == nil")
@@ -642,7 +472,7 @@ mod tests {
                 .unwrap(),
             "0 is not a Lua index"
         );
-        // The raid arm's real sweep shape: 40 probes must all answer without raising.
+        // The raid arm's sweep: 40 probes, none raising.
         assert_eq!(
             s.eval::<i64>(
                 "local n = 0
@@ -653,9 +483,7 @@ mod tests {
             2
         );
 
-        // A HOLE in the middle answers nil without ending the list — the raid layout, where a
-        // candidate's index carries which subgroup they are in, so slot 6 can be occupied while
-        // slots 2-5 are empty. A list that stopped at the first nil would lose them.
+        // A raid's slot carries the subgroup, so slot 6 can be filled while 2-5 are empty.
         let mut raid = loot();
         raid.master_candidates = vec![
             Some("Thrall".into()),
@@ -696,7 +524,6 @@ mod tests {
         s.run("GiveMasterLoot(2, 1)").unwrap();
         assert_eq!(s.take_loot_master_gives(), vec![(2, 1)]);
         assert!(s.take_loot_master_gives().is_empty(), "drained");
-        // It is NOT a loot pick — the two intents must not cross wires.
         assert!(s.take_loot_picks().is_empty());
     }
 
@@ -710,9 +537,7 @@ mod tests {
         assert!(s.take_loot_picks().is_empty(), "drained");
     }
 
-    /// `LootSlot` is the confirmation continuation, so it rides its OWN queue — a client that let
-    /// it fall into the pick queue would loot any row an addon named, which the reference refuses
-    /// (decision 1744).
+    /// In the pick queue `LootSlot` would loot any row an addon named, which the reference refuses.
     #[test]
     fn loot_slot_queues_confirms_not_picks() {
         let mut s = UiScript::new().unwrap();
@@ -734,7 +559,6 @@ mod tests {
         s.run("CloseLoot()").unwrap();
         assert!(s.take_loot_close());
         assert!(!s.take_loot_close(), "drained");
-        // The client's failed-open form (CloseLoot(1)) is accepted and flags the same intent.
         s.run("CloseLoot(1)").unwrap();
         assert!(s.take_loot_close());
     }
@@ -748,9 +572,8 @@ mod tests {
         assert!(s.eval::<bool>("return GetLootSlotInfo(1) == nil").unwrap());
     }
 
-    /// A real HARDWARE click on a named frame — through the pointer path, so `scripted` is false
-    /// and the LootButton gate sees what it would see in play. Positions the frame first: the
-    /// input path is a hit test, and an unpositioned frame is nowhere.
+    /// A hardware click on a named frame through the pointer path, which hit-tests, so the frame
+    /// is positioned first.
     fn hardware_click(s: &mut UiScript, name: &str, button: &str) {
         s.set_screen_size(1024.0, 768.0);
         s.run(&format!(
@@ -763,7 +586,6 @@ mod tests {
         s.mouse_button(125.0, 125.0, button, false);
     }
 
-    /// `LootButton` is a real `CreateFrame` type with its own identity — not an alias for Button.
     #[test]
     fn loot_button_is_its_own_registered_type() {
         let s = UiScript::new().unwrap();
@@ -785,7 +607,6 @@ mod tests {
         assert!(!s
             .eval::<bool>(r#"return lb:IsObjectType("CheckButton") and true or false"#)
             .unwrap());
-        // Its one method of its own, plus all of Button's through the chain.
         assert_eq!(
             s.eval::<String>("return type(lb.SetSlot)").unwrap(),
             "function"
@@ -794,14 +615,12 @@ mod tests {
             s.eval::<String>("return type(lb.SetText)").unwrap(),
             "function"
         );
-        // …and the method is NOT on a plain Button — the chain runs derived → base only.
+        // A plain Button lacks it: the chain runs derived to base only.
         s.run(r#"b = CreateFrame("Button", "PlainB", UIParent)"#)
             .unwrap();
         assert_eq!(s.eval::<String>("return type(b.SetSlot)").unwrap(), "nil");
     }
 
-    /// An unmodified hardware click takes the row's slot. The Lua `OnClick` runs first and
-    /// unconditionally, and its outcome does not gate the take.
     #[test]
     fn an_unmodified_click_runs_the_handler_and_then_takes() {
         let mut s = UiScript::new().unwrap();
@@ -818,15 +637,14 @@ mod tests {
         assert_eq!(s.eval::<i64>("return ran").unwrap(), 1, "the handler ran");
         assert_eq!(s.take_loot_picks(), vec![3], "and then the take, 1-based");
 
-        // The handler erroring does not eat the loot — `0x4c1833`'s result is never tested.
+        // An erroring handler still loots: `0x4c1833`'s result is never tested.
         s.run(r#"lb:SetScript("OnClick", function() error("boom") end)"#)
             .unwrap();
         hardware_click(&mut s, "LB1", "LeftButton");
         assert_eq!(s.take_loot_picks(), vec![3], "a broken hook still loots");
     }
 
-    /// Right-click loots exactly like left-click: `0x4c1820` reads the button code once and
-    /// forwards it, with no `cmp` against it anywhere in the body.
+    /// `0x4c1820` forwards the button code without ever comparing it.
     #[test]
     fn right_click_loots_like_left_click() {
         let mut s = UiScript::new().unwrap();
@@ -842,9 +660,7 @@ mod tests {
         assert_eq!(s.take_loot_picks(), vec![2]);
     }
 
-    /// Any of the three modifiers suppresses the take — and only the take. The handler still runs,
-    /// which is exactly how the shipped `LootFrameItem_OnClick` gets to own the ctrl and shift
-    /// cases without the C take firing underneath it.
+    /// The handler still runs, so stock `LootFrameItem_OnClick` owns ctrl and shift alone.
     #[test]
     fn any_modifier_suppresses_the_take_but_not_the_handler() {
         for (i, (shift, ctrl, alt)) in [
@@ -876,9 +692,7 @@ mod tests {
         }
     }
 
-    /// **A scripted `:Click()` is a complete no-op** — it does not even run the row's `OnClick`.
-    /// `0x4c182b` returns before the base call. Surprising enough that it is asserted rather than
-    /// left to be rediscovered.
+    /// A scripted `:Click()` does not even run `OnClick`: `0x4c182b` returns before the base call.
     #[test]
     fn a_scripted_click_does_nothing_at_all() {
         let mut s = UiScript::new().unwrap();
@@ -898,7 +712,7 @@ mod tests {
             "the handler never ran"
         );
         assert!(s.take_loot_picks().is_empty(), "and nothing was taken");
-        // A plain Button's Click() is unaffected — the gate is this type's alone.
+        // A plain Button's Click() is unaffected.
         s.run(
             r#"
             b = CreateFrame("Button", "PlainB", UIParent)
@@ -911,8 +725,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return bran").unwrap(), 1);
     }
 
-    /// `SetSlot` is 1-based in and 0-based stored, takes a numeric string, and refuses `this` that
-    /// is not a LootButton (the reference's own `IsA` guard at `0x4c18ee`).
+    /// The `this` guard is the reference's `IsA` check at `0x4c18ee`.
     #[test]
     fn set_slot_converts_and_guards() {
         let mut s = UiScript::new().unwrap();
@@ -924,25 +737,21 @@ mod tests {
         hardware_click(&mut s, "LB1", "LeftButton");
         assert_eq!(s.take_loot_picks(), vec![4]);
 
-        // A numeric string is a number to `lua_isnumber`.
         s.run(r#"lb:SetSlot("2")"#).unwrap();
         hardware_click(&mut s, "LB1", "LeftButton");
         assert_eq!(s.take_loot_picks(), vec![2]);
 
-        // A non-number raises the client's own usage text.
         let e = s.run("lb:SetSlot('x')").unwrap_err().to_string();
         assert!(e.contains("Usage: SetSlot(index)"), "{e}");
 
-        // Never slotted → takes nothing, rather than silently taking row 1. `LB1` is still parked
-        // under the cursor from the clicks above and, being linked first, would win the tie for the
-        // point (decision 1816) and take row 2 again — get it out of the way first.
+        // Never slotted takes nothing. `LB1` still sits under the cursor and, linked first, would
+        // win the hit test, so it hides first.
         s.run("LB1:Hide()").unwrap();
         s.run(r#"fresh = CreateFrame("LootButton", "LB2", UIParent)"#)
             .unwrap();
         hardware_click(&mut s, "LB2", "LeftButton");
         assert!(s.take_loot_picks().is_empty());
 
-        // And it is a LootButton method, not a Button one.
         s.run(r#"b = CreateFrame("Button", "PlainB", UIParent)"#)
             .unwrap();
         let e = s.run("LB1.SetSlot(b, 1)").unwrap_err().to_string();
diff --git a/crates/benilla-ui/src/script/loot_roll.rs b/crates/benilla-ui/src/script/loot_roll.rs
index bac0c4dc..65edc693 100644
--- a/crates/benilla-ui/src/script/loot_roll.rs
+++ b/crates/benilla-ui/src/script/loot_roll.rs
@@ -1,98 +1,52 @@
-//! The group-loot-roll bindings (decision 0591) — the `GroupLootFrame` half of the loot surface,
-//! the same two-way seam as [`super::loot`]: the app pushes a snapshot of the **open rolls**
-//! ([`UiScript::set_loot_rolls`] — each already resolved to name/icon/quantity/quality/bind and a
-//! live time-remaining) and the Lua `RollOnLoot` call queues an outbound **vote** the app drains
-//! ([`UiScript::take_loot_roll_votes`]). The engine holds no roll knowledge — a roll is "an id, an
-//! item's display fields, and how long is left".
-//!
-//! ## The Era API shape
-//!
-//! 1.12 drives four `GroupLootFrame`s (`NUM_GROUP_LOOT_FRAMES = 4`, `LootFrame.lua:2`) off a flat
-//! set of globals (VERIFIED against the extracted `LootFrame.lua`/`LootFrame.xml`/`UIParent.lua`):
-//!
-//! - `START_LOOT_ROLL` fires with `arg1 = rollID, arg2 = rollTime`; `UIParent.lua:513-515` hands it
-//!   to `GroupLootFrame_OpenNewFrame(id, rollTime)`, which claims the first non-visible frame,
-//!   stores `frame.rollID`, and sets its `Timer` StatusBar's max to `rollTime` (`LootFrame.lua:246-258`).
-//! - `GetLootRollItemInfo(rollID)` → `texture, name, count, quality, bindOnPickUp`
-//!   (`LootFrame.lua:261`) — `bindOnPickUp` swaps the frame to the gold BoP backdrop.
-//! - `GetLootRollTimeLeft(rollID)` → the milliseconds left, polled from the Timer's `OnUpdate`
-//!   (`LootFrame.lua:287-296`).
-//! - `GetLootRollItemLink(rollID)` → the rolled item's link, read by the icon button's ctrl/shift
-//!   arms (`LootFrame.xml:353-361` — decision 1059).
-//! - `RollOnLoot(rollID, rollType)` — `0` Pass, `1` Need, `2` Greed, wired to the frame's
-//!   PassButton/RollButton/GreedButton `OnClick` (`LootFrame.xml:375`/`:398`/`:425`).
-//! - `CANCEL_LOOT_ROLL` fires with `arg1 = rollID`; the matching frame hides (`LootFrame.lua:279-285`).
-//!
-//! `rollID` is **client-internal** — it never reaches the wire (`CMSG_LOOT_ROLL` addresses a roll by
-//! `(lootedTarget, itemSlot)` instead), so the app allocates its own monotonic id per open roll.
-//! An unknown `rollID` answers the reference's own miss values — `nil` for the strings, `0` for
-//! `GetLootRollTimeLeft`, and `GetLootRollItemInfo`'s five-value tail (`0x4c31a3`).
+//! The group loot roll bindings `GroupLootFrame` calls: the app pushes the open rolls and drains
+//! the votes `RollOnLoot` queues, 0 Pass, 1 Need, 2 Greed (`LootFrame.xml:374`/`:398`/`:425`).
+//! `START_LOOT_ROLL` carries `(rollID, rollTime)` and `CANCEL_LOOT_ROLL` the `rollID`
+//! (`UIParent.lua:513-515`, `LootFrame.lua:279-285`). The `rollID` is client-internal, as
+//! `CMSG_LOOT_ROLL` addresses `(lootedTarget, itemSlot)`, so the app allocates its own.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// `rollType` 0 — the one vote the bind-on-pickup gate never intercepts (passing binds nothing).
+/// `rollType` 0, the one vote the bind-on-pickup gate never intercepts.
 const PASS: u8 = 0;
 
-/// What `GetLootRollItemInfo` answers for `count` and `quality` when the item-template cache has no
-/// record — the reference's own shared miss tail `nil, nil, 1.0, 1.0, nil` at `0x4c31a3` (wow-re
-/// `system/object-layer/scratch/lootroll-chat-and-lifecycle.md` §5). `count` is a literal `1.0` on
-/// the hit path too (`0x4c3160` — a group roll is always one stack), so only the quality is really a
-/// sentinel, and it is **`1` (Common), not `GetLootSlotInfo`'s `-1`**: each accessor carries its own,
-/// and copying one to the other would be a guess.
-///
-/// It matters for the same reason 1805's did. Stock `GroupLootFrame_OnShow` reads this value straight
-/// into `ITEM_QUALITY_COLORS[quality]` and dereferences it on the next line (`LootFrame.lua:275-276`)
-/// with no guard; our `GroupLootFrame.xml` carries the `or ITEM_QUALITY_COLORS[1]` that the stock
-/// file does not, so the nil this used to answer is a raise waiting for that file's migration.
+/// The quality `GetLootRollItemInfo` answers on an item-template miss, from the reference's miss
+/// tail `nil, nil, 1.0, 1.0, nil` (`0x4c31a3`): 1, not `GetLootSlotInfo`'s -1. Stock
+/// `GroupLootFrame_OnShow` indexes `ITEM_QUALITY_COLORS` with it unguarded
+/// (`LootFrame.lua:275-276`).
 const CACHE_MISS_QUALITY: i64 = 1;
 
-/// One open group loot roll, resolved by the app (decision 0591). Plain data — the app rebuilds the
-/// whole list each frame, so `time_left_ms` is simply re-derived rather than ticked here.
+/// One open group loot roll, resolved by the app and pushed whole each frame.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct LootRollEntry {
-    /// The client-internal roll id the Lua side addresses this roll by — allocated by the app,
-    /// never on the wire. Stable for the life of the roll.
+    /// The client-internal `rollID`, allocated by the app and stable for the roll's life.
     pub roll_id: u32,
-    /// The item's name (`GetLootRollItemInfo`'s `name`). `None` while the ask-once item-template
-    /// query is still in flight; the API reports `nil` and the frame shows its placeholder.
+    /// `None`, answered as `nil`, while the item-template query is in flight.
     pub name: Option<String>,
     /// Icon texture path (`Interface\Icons\…`). `None` only if the display catalog had no icon.
     pub texture: Option<String>,
-    /// The stack size being rolled for (`GetLootRollItemInfo`'s `count`).
+    /// The stack size, answered as `GetLootRollItemInfo`'s `count`; the reference answers a literal
+    /// `1.0` there, a group roll being one stack (`0x4c3160`).
     pub quantity: u32,
-    /// Item quality 0..6, for the quality-coloured name; `None` while the template is in flight,
-    /// which the API reports as [`CACHE_MISS_QUALITY`] (`1`, Common) rather than a nil — the
-    /// reference's own miss tail, and a real row of `ITEM_QUALITY_COLORS`.
+    /// Item quality 0..6; `None` while the template is in flight, answered as `CACHE_MISS_QUALITY`.
     pub quality: Option<u32>,
-    /// Whether the item binds when picked up — the gold-backdrop swap in `GroupLootFrame_OnShow`.
-    /// `false` while the template is in flight (the plain backdrop is the safe default).
+    /// Bind on pickup, which swaps in the gold backdrop; `false` while the template is in flight.
     pub bind_on_pickup: bool,
-    /// Milliseconds left before the roll times out — re-derived by the app each frame from the
-    /// roll's start and `SMSG_LOOT_START_ROLL`'s countdown. Saturates at `0`.
+    /// Milliseconds left, from `SMSG_LOOT_START_ROLL`'s countdown; saturates at 0.
     pub time_left_ms: u32,
-    /// The item id — the shared item-tooltip store's key (`BenillaGetItemStats`). A benilla
-    /// extension riding as a TRAILING return of `GetLootRollItemInfo`, the same idiom
-    /// [`super::loot::LootRow::item_id`] uses on `GetLootSlotInfo`.
+    /// The item id, the key of the hover's item lookup; `GetLootRollItemInfo` also returns it as a
+    /// sixth value, which 1.12 does not.
     pub item_id: u32,
-    /// The rolled item's full escaped `|cff…|Hitem:…|h[Name]|h|r` link (`GetLootRollItemLink`,
-    /// decision 1059) — what the icon button's ctrl/shift arms hand to `DressUpItemLink` /
-    /// `ChatFrameEditBox:Insert` (`LootFrame.xml:353-361`). `None` while the item-template query is
-    /// in flight: the link embeds the name, so it lands with `name`/`quality`, not before. A roll
-    /// popup shows the instant `START_LOOT_ROLL` fires, so this nil is the common case for the first
-    /// frames of every roll — both click arms drop it rather than posting an empty link.
+    /// The link `GetLootRollItemLink` answers for the icon's ctrl/shift clicks
+    /// (`LootFrame.xml:353-361`); `None` until the item template lands, since it embeds the name.
     pub link: Option<String>,
-    /// `SMSG_LOOT_START_ROLL`'s `randomPropertyId` — the drop's **random-suffix roll**, which the
-    /// hover resolves against [`super::Model::random_properties`] for its enchant lines. `0` =
-    /// unrolled. The reference's `SetLootRollItem 0x5364a0` copies the same value into the
-    /// tooltip's `+0x424` and passes no item object, so the roll is the roll window's only enchant
-    /// source — the loot window's own shape (decision 1547). [`Self::name`] carries the suffix the
-    /// same id joins on.
+    /// `SMSG_LOOT_START_ROLL`'s random suffix, 0 for none: the hover's only enchant source, as
+    /// `SetLootRollItem` (`0x5364a0`) copies it to the tooltip's `+0x424` with no item object.
     pub random_property_id: u32,
 }
 
-/// Every group loot roll currently open, in the order the app opened them. Pushed whole each frame.
+/// Every open group loot roll, in the order the app opened them.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct LootRollsState {
     pub rolls: Vec<LootRollEntry>,
@@ -110,30 +64,22 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().loot_roll_votes)
     }
 
-    /// Drain the `(roll_id, roll_type)` **confirm requests** — a Need or Greed on a bind-on-pickup
-    /// roll, which sends nothing and instead asks for the `CONFIRM_LOOT_ROLL` popup (see
-    /// [`install`]'s `RollOnLoot`). The app fires the event; the popup's OnAccept calls
-    /// `ConfirmLootRoll`, which queues the real vote.
+    /// Drain the `(roll_id, roll_type)` Need or Greed calls on a bind-on-pickup roll: the app fires
+    /// `CONFIRM_LOOT_ROLL`, and the popup's `ConfirmLootRoll` queues the real vote.
     pub fn take_loot_roll_confirms(&mut self) -> Vec<(u32, u8)> {
         std::mem::take(&mut self.model_mut().loot_roll_confirms)
     }
 }
 
-/// Look one roll up by its client-internal id.
 fn find(model: &Model, roll_id: u32) -> Option<&LootRollEntry> {
     model.loot_rolls.rolls.iter().find(|r| r.roll_id == roll_id)
 }
 
-/// Register the group-loot-roll globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetLootRollItemInfo(rollID) → texture, name, count, quality, bindOnPickUp, itemID (`0x4c3050`;
-    // the sixth is ours). An unknown id — the frame is mid-teardown, or an addon asked for a stale
-    // roll — is the reference's own miss leg, and it does not return *nothing*: `0x4c31a3` pushes
-    // `nil, nil, 1.0, 1.0, nil`. So does a roll whose item template has not landed, because the
-    // reference reads every one of these off the item-template cache record and takes the same tail
-    // when it is absent. See [`CACHE_MISS_QUALITY`] — the quality is the one a stock caller indexes.
+    // `0x4c3050`, read at `LootFrame.lua:261`. An unknown id takes the reference's miss tail
+    // `nil, nil, 1.0, 1.0, nil` (`0x4c31a3`), as a roll with no item template does there.
     g.set(
         "GetLootRollItemInfo",
         lua.create_function(|lua, roll_id: u32| {
@@ -160,11 +106,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootRollItemLink(rollID) → the rolled item's full escaped link | nil. Unknown id → nil, and
-    // nil while the item template is in flight (the link embeds the name). The reference's icon
-    // button reads it for both modifier arms — `DressUpItemLink(GetLootRollItemLink(...))` and
-    // `ChatFrameEditBox:Insert(...)`, `LootFrame.xml:353-361`; ours routes the second through
-    // `BenillaChatEdit_InsertLink`, whose whole job is the nil this getter can answer. Decision 1059.
+    // `nil` for an unknown id or while the item template is in flight.
     g.set(
         "GetLootRollItemLink",
         lua.create_function(|lua, roll_id: u32| {
@@ -179,8 +121,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootRollTimeLeft(rollID) → milliseconds remaining; 0 for an unknown id (the reference
-    // OnUpdate clamps anything outside the bar's range to its minimum anyway, LootFrame.lua:290-293).
+    // 0 for an unknown id; the stock `OnUpdate` clamps it to the bar's minimum anyway
+    // (`LootFrame.lua:290-293`).
     g.set(
         "GetLootRollTimeLeft",
         lua.create_function(|lua, roll_id: u32| {
@@ -189,18 +131,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RollOnLoot(rollID, rollType) — queue the vote. rollType is 0 Pass / 1 Need / 2 Greed; the
-    // server hard-rejects anything >= 3 (MAX_ROLL_FROM_CLIENT), so out-of-range votes are dropped
-    // here rather than sent. An unknown rollID is likewise dropped — the app couldn't map it back
-    // to a (lootedTarget, itemSlot) anyway.
-    //
-    // THE BoP GATE (decision 0594, VERIFIED in the 5875 binary at `0x61bdf0`): a Need or Greed on
-    // an item whose template binds on pickup sends **no packet at all** and leaves the dialog up —
-    // it fires `CONFIRM_LOOT_ROLL` and returns (`0x61be8b`). Only `ConfirmLootRoll` (below), which
-    // the popup's OnAccept calls, re-enters past the gate. Pass is never gated: passing binds
-    // nothing. This gate lives here, in the seam, because that is where the real client puts it —
-    // in the C function, not in the Lua — so a stock addon calling RollOnLoot on a BoP item gets
-    // the confirm rather than silently binding the item.
+    // The server ignores a `rollType` of 3 or more (`GroupHandler.cpp:376`), so those and unknown
+    // ids are dropped. Need or Greed on a bind-on-pickup item sends nothing and fires
+    // `CONFIRM_LOOT_ROLL` (`0x61bdf0`, `0x61be8b`); the gate is in the C function, so it holds for
+    // an addon's call too.
     g.set(
         "RollOnLoot",
         lua.create_function(|lua, (roll_id, roll_type): (u32, u8)| {
@@ -220,8 +154,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmLootRoll(rollID, rollType) — the BoP gate's bypass (`0x4c33e0`, which re-enters
-    // `0x61bdf0` with the third argument `1`). Same validation as RollOnLoot minus the bind check.
+    // The gate's bypass: `0x4c33e0` re-enters `0x61bdf0` with a third argument of 1.
     g.set(
         "ConfirmLootRoll",
         lua.create_function(|lua, (roll_id, roll_type): (u32, u8)| {
@@ -244,7 +177,7 @@ mod tests {
     fn rolls() -> LootRollsState {
         LootRollsState {
             rolls: vec![
-                // A resolved BoP item — name, quality and link land together (one template answer).
+                // A resolved BoP item: name, quality and link land together.
                 LootRollEntry {
                     roll_id: 7,
                     name: Some("Staff of Jordan".into()),
@@ -257,7 +190,7 @@ mod tests {
                     link: Some("|cffa335ee|Hitem:17182:0:0:0|h[Staff of Jordan]|h|r".into()),
                     random_property_id: 0,
                 },
-                // An in-flight item: the roll opened, the item-template answer hasn't landed.
+                // In flight: the roll opened, the item template has not landed.
                 LootRollEntry {
                     roll_id: 8,
                     name: None,
@@ -277,7 +210,6 @@ mod tests {
     #[test]
     fn roll_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
-        // No roll open: info nil, time left 0.
         assert!(s
             .eval::<bool>("return GetLootRollItemInfo(7) == nil")
             .unwrap());
@@ -285,7 +217,6 @@ mod tests {
 
         s.set_loot_rolls(rolls());
 
-        // The resolved roll: the full 1.12 five-tuple, in LootFrame.lua's order.
         let (texture, name, count, quality, bop) = s
             .eval::<(String, String, i64, i64, bool)>("return GetLootRollItemInfo(7)")
             .unwrap();
@@ -296,16 +227,13 @@ mod tests {
             s.eval::<i64>("return GetLootRollTimeLeft(7)").unwrap(),
             42_000
         );
-        // The benilla item-id extension rides as the trailing return.
         assert_eq!(
             s.eval::<i64>("local _, _, _, _, _, id = GetLootRollItemInfo(7)\nreturn id")
                 .unwrap(),
             17182
         );
 
-        // The in-flight roll: name/texture nil as the reference's miss tail has them, but the
-        // QUALITY is its sentinel `1` and not a nil — stock `GroupLootFrame_OnShow` indexes it into
-        // `ITEM_QUALITY_COLORS` and dereferences the result with no guard (`LootFrame.lua:275-276`).
+        // In flight: the quality is the miss tail's 1, never nil.
         assert!(s
             .eval::<bool>(
                 "local t, n, c, q, b = GetLootRollItemInfo(8)\n\
@@ -313,8 +241,6 @@ mod tests {
             )
             .unwrap());
 
-        // GetLootRollItemLink: the resolved roll's link; nil while the template is in flight (the
-        // icon button's ctrl/shift arms hand this straight on — decision 1059).
         assert_eq!(
             s.eval::<String>("return GetLootRollItemLink(7)").unwrap(),
             "|cffa335ee|Hitem:17182:0:0:0|h[Staff of Jordan]|h|r"
@@ -323,9 +249,7 @@ mod tests {
             .eval::<bool>("return GetLootRollItemLink(8) == nil")
             .unwrap());
 
-        // An unknown id → the reference's five-value miss tail (`0x4c31a3`), never an error and
-        // never *nothing*: nil, nil, 1, 1, nil — so a stock caller that unpacks all five and indexes
-        // the quality still finds a colour.
+        // An unknown id: the reference's miss tail (`0x4c31a3`).
         assert!(s
             .eval::<bool>("return GetLootRollItemInfo(99) == nil")
             .unwrap());
@@ -348,7 +272,7 @@ mod tests {
     fn roll_on_loot_queues_votes() {
         let mut s = UiScript::new().unwrap();
         s.set_loot_rolls(rolls());
-        // Roll 8 is NOT bind-on-pickup, so every vote on it goes straight out.
+        // Roll 8 is not bind-on-pickup, so every vote goes straight out.
         s.run("RollOnLoot(8, 1)").unwrap(); // Need
         s.run("RollOnLoot(8, 2)").unwrap(); // Greed
         s.run("RollOnLoot(8, 0)").unwrap(); // Pass
@@ -357,10 +281,6 @@ mod tests {
         assert!(s.take_loot_roll_confirms().is_empty(), "nothing to confirm");
     }
 
-    /// The BoP gate (decision 0594): Need/Greed on a bind-on-pickup roll must send NOTHING and ask
-    /// for the confirm popup instead; Pass on the same roll goes straight out. This is the
-    /// behaviour benilla shipped wrong in 0591 — it sent the vote immediately, binding the item
-    /// with no prompt.
     #[test]
     fn need_or_greed_on_a_bop_roll_confirms_instead_of_voting() {
         let mut s = UiScript::new().unwrap();
@@ -373,19 +293,17 @@ mod tests {
         );
         assert_eq!(s.take_loot_roll_confirms(), vec![(7, 1), (7, 2)]);
 
-        // Pass is never gated — passing binds nothing.
+        // Pass is never gated.
         s.run("RollOnLoot(7, 0)").unwrap();
         assert_eq!(s.take_loot_roll_votes(), vec![(7, 0)]);
         assert!(s.take_loot_roll_confirms().is_empty());
 
-        // ConfirmLootRoll is the bypass: the popup's OnAccept lands the real vote.
+        // `ConfirmLootRoll`, the popup's accept, lands the real vote.
         s.run("ConfirmLootRoll(7, 1)").unwrap();
         assert_eq!(s.take_loot_roll_votes(), vec![(7, 1)]);
         assert!(s.take_loot_roll_confirms().is_empty(), "no second prompt");
     }
 
-    /// `ConfirmLootRoll` bypasses only the *bind* gate — it still validates id and range, or a
-    /// stale popup could push a vote the app cannot address.
     #[test]
     fn confirm_still_validates() {
         let mut s = UiScript::new().unwrap();
@@ -395,13 +313,11 @@ mod tests {
         assert!(s.take_loot_roll_votes().is_empty());
     }
 
-    /// The two votes that must never reach the wire: a rollType the server would reject outright
-    /// (`>= MAX_ROLL_FROM_CLIENT`), and an id no open roll owns (nothing to address it with).
     #[test]
     fn bad_votes_are_dropped() {
         let mut s = UiScript::new().unwrap();
         s.set_loot_rolls(rolls());
-        s.run("RollOnLoot(7, 3)").unwrap(); // ROLL_NOT_EMITED_YET — server-only
+        s.run("RollOnLoot(7, 3)").unwrap(); // ROLL_NOT_EMITED_YET, server-only
         s.run("RollOnLoot(7, 200)").unwrap();
         s.run("RollOnLoot(99, 1)").unwrap(); // no such roll
         assert!(s.take_loot_roll_votes().is_empty());
diff --git a/crates/benilla-ui/src/script/lua50.rs b/crates/benilla-ui/src/script/lua50.rs
index 3648cc7a..3966af06 100644
--- a/crates/benilla-ui/src/script/lua50.rs
+++ b/crates/benilla-ui/src/script/lua50.rs
@@ -1,128 +1,38 @@
-//! **The Lua 5.0 dialect** — the layer that makes an mlua 5.1 VM answer the questions a 1.12 addon
-//! asks about its interpreter (decision 1194).
+//! The Lua 5.0 dialect: the 5.1 VM's libraries reshaped to answer as the 1.12 client's Lua 5.0.
 //!
-//! The 1.12.1 client embeds **Lua 5.0**; we embed mlua's `lua51`. Every prior decision in this
-//! crate treated that as a detail — 0068 called the target "stock Lua 5.1", and the WoW stdlib
-//! layer beside this one is written as aliases *onto* 5.1. It is not a detail. It is the single
-//! largest measured blocker in the whole addon arc:
+//! The reference embeds Lua 5.0 (`$Lua: Lua 5.0` at `0x811b30`), and `InitLua 0x7039e0` opens
+//! five libraries: base (`0x811e28`, 36 entries), `string` (`0x822d88`, 12), `table`
+//! (`0x822d40`, 8), `math` (`0x822c60`, 24) and `bit` (`0x822c18`, 8), with no `os`, `io`,
+//! `debug` or `coroutine`. The grammar is the Lua fork's, in `third_party/lua-src`.
 //!
-//! ```text
-//! what stopped them (addons whose FIRST load error was each):
-//!    61  error: 'X' is obsolete          <- table.setn, raised by Lua 5.1
-//! ```
-//!
-//! Sixty-one of 218 real vanilla addons, plus ~23 more that merely depend on one of them, stopped
-//! on their first chunk. The chain is worth spelling out because it is not obvious and because
-//! **we caused the last link ourselves**: `AceLibrary.lua` opens with
-//!
-//! ```lua
-//! local version = GetBuildInfo()
-//! if string.find(version, "^2%.") then
-//!     table_setn = function() end   -- TBC: Lua 5.1, setn is gone
-//! else
-//!     table_setn = table.setn       -- 1.12: Lua 5.0, setn is real
-//! end
-//! ```
-//!
-//! Ace asks the client which client it is and picks the right dialect. We started answering
-//! `"1.12.1"` truthfully (1192 phase 5, `GetBuildInfo`), Ace correctly took the 5.0 branch, and our
-//! 5.1 VM raised. The addon was right, the API was right, and the interpreter underneath was
-//! lying. That is what this module fixes.
-//!
-//! ## What it does, in three parts
-//!
-//! 1. **`table.setn`/`table.getn` get their 5.0 meaning back.** 5.0 remembers a table's size —
-//!    in a numeric `t.n` field if one already exists, otherwise in a private weak-keyed table
-//!    where nothing walking the table can see it. 5.1 removed the concept and made `setn` raise.
-//!    The exact mechanism matters more than it looks: see [`LUA_5_0_TABLE_SIZE`] for the draft
-//!    that got it wrong and the 39 addons that noticed.
-//! 2. **The 5.1-only members are removed.** `string.gmatch`/`match`/`reverse`, `table.maxn`,
-//!    `math.fmod`/`modf`/`huge`/`cosh`/`sinh`/`tanh`, and the whole `coroutine` table — none of
-//!    which 1.12 has. This is 1189's *"a superset is not free"* one level below `_G`: an addon
-//!    that writes `string.gmatch or string.gfind` (Ace does, on the very next line) picks the
-//!    branch we leave standing, so leaving both standing chooses the wrong one for it.
-//! 3. **The 5.0 compat globals the reference actually has get added** — `sort`, `foreach`,
-//!    `foreachi`. `reference/1.12-globals.tsv` lists all three; we had the other seventeen of that
-//!    family and not these.
-//!
-//! ## What this module does NOT have to do: the vararg `arg` table
-//!
-//! Lua 5.0 gives every vararg function an implicit `arg` table with an `n` field, and 1.12's
-//! FrameXML uses it directly — `QuestTimerFrame_Update(...)` walks `for i=1, arg.n`, and so do
-//! `FCFDropDown_LoadChannels`, `TradeSkill_OnEvent` and the GM-ticket and CVar families. Three of
-//! our own transcriptions carry a note saying they rewrote it "the 5.1-native way" with
-//! `select("#", ...)`, which reads as though the dialect demanded it.
-//!
-//! **It does not.** mlua's vendored 5.1 is built with `LUA_COMPAT_VARARG`, so `arg` and `arg.n`
-//! are already there — measured, not assumed: `local function f(...) return arg.n end; f('a','b')`
-//! answers 2 in this VM. That matters for 1751: a stock file using 5.0 varargs needs nothing from
-//! this module, and the rewrite was a precaution against a problem we did not have.
-//!
-//! ## The one known divergence, stated rather than hidden
-//!
-//! `table.insert`/`table.remove` stay on 5.1's `#t` border rather than consulting `getn`. **This
-//! is byte-confirmed as a real divergence, not a suspicion**: the RE dispatch found that 1.12's
-//! whole table library is `n`-based — `luaL_getn` is called by `insert`/`remove`/`concat`/`sort`/
-//! `foreachi` *and* base `unpack`, and `insert`/`remove` **update** the stored size. So
-//! `setn(t, 0)` on a non-empty table makes the next `insert` land at index 1 there and at
-//! `#t + 1` here.
-//!
-//! It stays, and the trade was measured before it was made. Over the 218-addon corpus there are
-//! 1,720 `setn` call sites; **1,471 pass 0** — always immediately after a
-//! `for k in pairs(t) do t[k] = nil end` wipe, where `#t` is already 0 and the two agree — and 290
-//! more pass `table.getn(source)` straight after copying that source, where they agree too. Fewer
-//! than 20 sites could observe the difference, and none of them is reached at load. Replacing
-//! `table.insert` with a Lua-level reimplementation to serve those would put an interpreted
-//! function on the hottest path in every addon in existence. Revisit it if a *runtime* failure is
-//! ever traced here — not before.
-//!
-//! ## Ground truth (decision 1196 — verified, no longer derived)
-//!
-//! This module first shipped with its member lists taken from Lua 5.0's published library
-//! registrations and cross-checked against two artifacts we hold. An RE dispatch into
-//! wow-5875-re then read the binary (`system/ui/scratch/lua-dialect.md`), and every list here is
-//! now the array in the image:
-//!
-//! - **Lua 5.0**, on five independent discriminators — not just the `$Lua: Lua 5.0 …` blob at
-//!   `0x811b30` but `LUA_REGISTRYINDEX = -10000` (5.1 uses −10002), a `luaT_eventname[]` pool with
-//!   no `__mod`/`__len` (so **no `%` and no `#` operator**), and live `luaL_getn`/`luaL_setn`.
-//! - **Five libraries are opened** by `InitLua 0x7039e0` and no more: base (a 36-entry array at
-//!   `0x811e28` looped straight into `_G`), `string` (12, array `0x822d88`), `table` (8,
-//!   `0x822d40`), `math` (24, `0x822c60`), and **`bit`** (8, `0x822c18`). `luaL_openlib` has four
-//!   call sites image-wide, so `os`/`io`/`debug`/`coroutine` are absent by construction.
-//! - **The compat globals are a Lua chunk, not C macros** — a 1310-byte `compat.lua` compiled into
-//!   `.data` at `0x8722e8`, run last at init. That is why the set is a specific subset (`getn`
-//!   aliased, `setn` deliberately not) rather than "whatever `LUA_COMPAT_*` gives you", and it is
-//!   also where the **degree-based** bare `sin`/`cos`/`tan` come from — a convention this crate's
-//!   stdlib layer had already reached independently.
+//! `...` is a parameter-list token only: a vararg function reads its arguments through 5.0's
+//! `arg` table (`arg.n`, `unpack(arg)`). So Lua written here forwards an unknown argument list
+//! only through a table, and a verb whose arity matters (`GetPoint()` against `GetPoint(nil)`)
+//! stays in Rust.
 
 use mlua::{Lua, Table, Value};
 
-/// Members that exist in Lua 5.1 and **not** in Lua 5.0, by library.
-///
-/// Removed rather than left standing, per 1189: a feature-detecting addon branches on presence,
-/// and the branch it should take is the one 1.12 gives it.
+/// The Lua 5.1 library members 5.0 lacks, removed so an addon's feature test
+/// (`string.gmatch or string.gfind`) takes the branch 1.12 gives it.
 const REMOVED: &[(&str, &[&str])] = &[
-    // 5.1 added the new pattern-matching spellings; 5.0 has only `gfind` and no `reverse`.
+    // 5.0 has `gfind`, and no `gmatch`, `match` or `reverse`.
     ("string", &["gmatch", "match", "reverse"]),
-    // 5.1 added `maxn`; 5.0's table library is concat/foreach/foreachi/getn/setn/sort/insert/remove.
+    // 5.0's eight are concat, foreach, foreachi, getn, setn, sort, insert and remove.
     ("table", &["maxn"]),
-    // 5.1 renamed `mod`→`fmod` (we keep `mod`, which 1.12 has as a bare global too) and added
-    // `modf`, `huge`, and the hyperbolics.
+    // 5.0's `mod` is 5.1's `fmod` (and a bare global in 1.12); 5.0 has no `modf`, `huge` or
+    // hyperbolics.
     ("math", &["fmod", "modf", "huge", "cosh", "sinh", "tanh"]),
 ];
 
-/// Lua 5.0's remembered table size, and the whole `n`-based table library that rides it
-/// (decision 2102) — [`table_size`]'s own header is the mechanism, the byte census behind it, and
-/// the runtime failure that retired this module's "revisit if ever traced" note.
+/// Lua 5.0's remembered table size and the `n`-based table library that reads and updates it.
 mod table_size;
 
-/// Install the dialect. Runs **before** the WoW stdlib layer, so its aliases bind the 5.0-shaped
+/// Install the dialect. Runs before the WoW stdlib layer, so its aliases bind the 5.0-shaped
 /// functions rather than the 5.1 ones they replace.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ── 1 · the `n`-based table library gets its 5.0 meaning back ─────────────────────────────
+    // ── 1 · the `n`-based table library ───────────────────────────────────────────────────────
     table_size::install(lua)?;
 
     // ── 2 · the 5.1-only members go ───────────────────────────────────────────────────────────
@@ -134,71 +44,23 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             t.set(*name, Value::Nil)?;
         }
     }
-    // `coroutine` is not in the 1.12 client's `_G` at all — not a member gap, a whole library the
-    // client does not open. It was on `reference_surface`'s beyond-1.12 exception list as
-    // "inherited rather than chosen"; it is now neither.
+    // `InitLua` never opens `coroutine`.
     g.set("coroutine", Value::Nil)?;
 
-    // `select` is 5.1's base library, not 5.0's, and the 1.12 client's `_G` has no row for it.
-    // It sat on `reference_surface`'s beyond-1.12 exception list under a reason that expired twice
-    // over: first "our transcribed FrameXML uses it in 16 files" — 1751's migration retired every
-    // one of those files, measured at zero by 2142 — then "it is mlua's, not ours to remove
-    // without the 5.1 varargs it comes with". 2101 deleted those varargs from the grammar, which
-    // is what turns this from a trade into a deletion: with `...`-as-a-value gone, `select`'s one
-    // idiomatic shape cannot be written at all, and what is left — `select(k, f())` — is a 5.1
-    // spelling of the multiple assignment 5.0 writes with commas.
-    //
-    // **Nothing of ours called it in production**: 177 sites in 55 files were our own TESTS asking
-    // a binding's arity, which is a host-side question and is now asked host-side
-    // ([`super::UiScript::arity`]). The handful that need the count *inside* Lua use 5.0's own
-    // answer, `arg.n` — which this VM hands every vararg function since 2101 deleted the arm that
-    // cleared `VARARG_NEEDSARG`.
+    // `select` is 5.1's base library and has no row in 1.12's `_G`. A vararg function counts its
+    // arguments with `arg.n`, and host code asks `UiScript::arity`.
     g.set("select", Value::Nil)?;
 
-    // **The string type has NO metatable in 1.12**, so `("x"):upper()` — and `s:sub(1, 2)` for a
-    // string `s` — raises `attempt to index a string value` there and quietly worked here. 5.1's
-    // `luaopen_string` ends in a `createmetatable` 5.0's does not have, and mlua runs 5.1.
-    //
-    // Read out of the client, and the claim is stronger than "nobody installs one": the type
-    // *cannot* carry one, on the **reader** side, so the writer side never has to be argued.
-    // `luaT_gettmbyobj 0x6f7bd0` is the one function the VM asks for any value's metamethod (7
-    // rel32 callers, covering TM_INDEX/TM_NEWINDEX/TM_CALL/order/arith). It loads `o->tt` at
-    // `0x6f7be2` and enumerates two tags — `sub ecx,5; je` (LUA_TTABLE), `sub ecx,2; je`
-    // (LUA_TUSERDATA) — then falls through at `0x6f7bee` to `mov eax,0x811bc0`, `&luaO_nilobject`
-    // in **`.rdata`**: sixteen zero bytes with no writers by construction. There is nothing to
-    // read, so a `__index` for a string cannot exist however it were installed. `G+0x80` is
-    // `tmname[15]`, the metamethod *name* strings, not a per-type metatable array; a ModRM/SIB
-    // census of every ×4-indexed operand across the text section finds no such read into writable
-    // `.data` at all.
-    //
-    // The writer agrees from the other end. `lua_setmetatable 0x6f4020` takes the same two arms
-    // (`0x6f409e`, `0x6f40a3`) into one `mov [edx+8], esi` — 5.0 puts `metatable` at offset 8 of
-    // both `Table` and `Udata` — and every other tag falls to `0x6f40a8`'s `xor eax,eax`: return
-    // 0, write nothing. `lua_getmetatable 0x6f3cf0` carries the identical `{5, 7}` switch. And the
-    // layout settles it a third way: `luaS_newlstr 0x6f9d00` puts a string's **hash** at `+8`
-    // (`0x6f9dbb`), the very offset the other two use for the metatable pointer.
-    //
-    // `luaopen_string 0x7fd810` is six instructions, `[0x7fd810, 0x7fd827)` — `push 0;
-    // push 0x822d88; mov edx,0x871938; call luaL_openlib; mov eax,1; ret` — with no
-    // `createmetatable` step, and `luaL_openlib` does not reach `0x6f4020` either. (wow-re
-    // `system/ui/scratch/string-metatable-closure.md`, whose §5 cross-check produced all of the
-    // above and retired `lua-dialect.md` §3's INFERRED flag on it. Two of ours came from that
-    // note before it was re-read: it said "four instructions" while quoting six, and it stopped at
-    // "no `lua_setmetatable` call" where the reader-side argument was available.)
-    //
-    // So this is not a policy choice about a superset — it is the type system. Note the reference
-    // also *raises* rather than no-ops if an addon tries it itself: base `setmetatable 0x702a40`'s
-    // first act is `luaL_checktype(L, 1, LUA_TTABLE)`, which mlua's 5.1 matches.
-    //
-    // Same rule as `coroutine` above, one layer below `_G`: an addon writing `s:gsub(...)` or
-    // testing `getmetatable("")` is asking which interpreter it is on, and the branch it should
-    // get is 1.12's.
+    // 1.12's string type has no metatable, so `("x"):upper()` raises `attempt to index a string
+    // value`. There it cannot carry one: `luaT_gettmbyobj 0x6f7bd0` finds metamethods only on
+    // tables and userdata, `lua_setmetatable 0x6f4020` writes only those two tags, and
+    // `luaopen_string 0x7fd810` installs none, where 5.1's does. Base `setmetatable` (`0x702a40`)
+    // rejects a non-table in both.
     lua.set_type_metatable::<mlua::String>(None);
 
-    // ── 3 · the 5.0 compat globals the reference has and we lacked ────────────────────────────
-    // `sort`/`foreach`/`foreachi` are in `reference/1.12-globals.tsv`; `setn` deliberately is not,
-    // so no bare `setn` is installed even though `table.setn` now works. The client's compat set
-    // is a specific subset, not "all of them".
+    // ── 3 · the 5.0 compat globals ────────────────────────────────────────────────────────────
+    // The client's compat chunk (`0x8722e8`) publishes these three bare, and no bare `setn`
+    // (`reference/1.12-globals.tsv`).
     let table: Table = g.get("table")?;
     for name in ["sort", "foreach", "foreachi"] {
         if let Ok(f) = table.get::<Value>(name) {
@@ -207,21 +69,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         }
     }
-    // `getn` is re-bound here rather than left to the stdlib layer's `table.getn or …` fallback,
-    // so the bare global and the member are the same function and cannot drift apart.
+    // Bound here, not left to the stdlib layer, so the bare `getn` is `table.getn` itself.
     g.set("getn", table.get::<Value>("getn")?)?;
 
-    // ── 4 · what the binary said and nobody had asked (decision 1196) ─────────────────────────
-    // `print` and `_VERSION` are **not in 1.12's `_G`** — the captured table says so and the RE
-    // dispatch found why: the base library is a 36-entry array looped into `_G`, and neither is in
-    // it (`_VERSION`'s literal is not even in the image). Both were on `reference_surface`'s
-    // exception list as "inherited rather than chosen"; nothing of ours uses either.
+    // ── 4 · the base library's own shape ──────────────────────────────────────────────────────
+    // `print` and `_VERSION` are neither in the base array (`0x811e28`) nor in 1.12's `_G`.
     g.set("print", Value::Nil)?;
     g.set("_VERSION", Value::Nil)?;
 
-    // `__pow` is a **global** in 1.12 (`function engine` in the captured table) — Lua 5.0
-    // implements `^` by calling it, and 5.1 made the operator native, so the name simply
-    // disappeared. Present here because an addon can see it, not because anything calls it.
+    // `__pow` is a 1.12 global, which 5.0 calls to implement `^`; nothing here calls it, but an
+    // addon can see it.
     g.set(
         "__pow",
         lua.create_function(|_, (a, b): (f64, f64)| Ok(a.powf(b)))?,
@@ -234,22 +91,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The **`bit` library** — 1.12 opens one, and it is not stock Lua (decision 1196).
-///
-/// `InitLua 0x7039e0` opens exactly five libraries: base, `string`, `table`, `math`, and **`bit`**
-/// (`0x7fadc0`, array `0x822c18`). The captured `_G` agrees — `bit` is there, attributed `engine`.
-/// We had assumed the opposite: `attempt to index global 'bit'` showed up in the corpus survey and
-/// was written off as an addon reaching for something 1.12 lacks. It was reaching for something
-/// **we** lacked.
-///
-/// Eight functions, the array's own order and its own names. Semantics are 32-bit two's
-/// complement, which is what every caller assumes (`band(flags, 0xFF)`); `arshift` is the
-/// sign-propagating shift `rshift` is not, which is the only pair anyone gets wrong.
+/// The `bit` library 1.12 opens (`0x7fadc0`, array `0x822c18`): its eight functions, in the
+/// array's order, on 32-bit two's complement.
 fn install_bit(lua: &Lua) -> mlua::Result<()> {
     let bit = lua.create_table()?;
-    // Lua numbers are doubles; the client's bit ops truncate to a 32-bit int and return a signed
-    // one. `as i64 as u32` is the C cast chain (`(unsigned)(int)x`) rather than a saturating one,
-    // so `bnot(0)` answers -1 exactly as it does there.
+    // The client truncates to a 32-bit int and answers signed. `as i64 as u32` is C's wrapping
+    // `(unsigned)(int)x`, not a saturating cast, so `bnot(0)` is -1 as there.
     fn u32_of(v: f64) -> u32 {
         v as i64 as u32
     }
@@ -272,9 +119,7 @@ fn install_bit(lua: &Lua) -> mlua::Result<()> {
         "bxor",
         lua.create_function(|_, (a, b): (f64, f64)| Ok(out(u32_of(a) ^ u32_of(b))))?,
     )?;
-    // The shifts mask their count to 5 bits, like the x86 shift instructions the client compiles
-    // to — `lshift(1, 32)` is `1`, not `0`, and an addon that shifts by a computed width relies on
-    // it not trapping.
+    // Shift counts mask to 5 bits, as the client's x86 shifts do: `lshift(1, 32)` is 1.
     bit.set(
         "lshift",
         lua.create_function(|_, (a, n): (f64, f64)| Ok(out(u32_of(a) << (u32_of(n) & 31))))?,
@@ -289,7 +134,7 @@ fn install_bit(lua: &Lua) -> mlua::Result<()> {
             Ok(out(((u32_of(a) as i32) >> (u32_of(n) & 31)) as u32))
         })?,
     )?;
-    // `bit.mod` — integer remainder, not `math.mod`'s float one. The library's own eighth entry.
+    // `bit.mod`: an integer remainder, unlike `math.mod`'s float one.
     bit.set(
         "mod",
         lua.create_function(|_, (a, b): (f64, f64)| {
@@ -303,51 +148,14 @@ fn install_bit(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set("bit", bit)
 }
 
-/// The **garbage-collector pair** — `gcinfo` answers TWO numbers and `collectgarbage` answers
-/// NONE and takes a *number* (decision 2136).
-///
-/// Both are 5.0-shaped, and 5.1 changed both in ways that are observable from Lua. Read off the
-/// image by wow-5875-re (`system/ui/scratch/lua-dialect.md` §12), and already carried in
-/// `reference/1.12-shapes.tsv` as `gcinfo … 2 exact (number,number) agree` and
-/// `collectgarbage … 0 exact () agree` — rows the return-shape gate never checked, because it
-/// filters to `table_kind = global` and these two are `baselib`.
-///
-/// **`gcinfo 0x703200`** — extent `[0x703200, 0x703243)`, reads no argument and cannot raise:
-/// `lua_getgccount 0x6f43f0` then `lua_getgcthreshold 0x6f43e0`, each shifted `>> 10`, then
-/// `mov eax, 2`. So it is `(count_KB, threshold_KB)` — 5.1 kept the name and dropped the second
-/// value, which is what we answered.
-///
-/// **`collectgarbage 0x703250`** — extent `[0x703250, 0x703273)`, `luaL_optnumber(L, 1, 0.0)` →
-/// `_ftol` → `lua_setgcthreshold 0x6f4400` → `xor eax,eax`. Zero values, and a **number** argument:
-/// 5.1's string options (`"count"`, `"collect"`, `"step"`, …) do not exist in the 35 bytes. The
-/// two dialects are therefore *inverted* on argument type — 5.1 rejects the number the reference
-/// requires, and accepts the strings the reference refuses:
-///
-/// | call | the reference | stock 5.1 (what we had) |
-/// |---|---|---|
-/// | `collectgarbage()` | threshold 0 → full collect, 0 values | 1 value |
-/// | `collectgarbage(0)` | the same, explicitly | **raises** ``invalid option `0'`` |
-/// | `collectgarbage("count")` | **raises** `number expected, got string` | returns a number |
-///
-/// **The threshold is modelled, and this is the one place a value is ours rather than the
-/// image's.** 5.1 replaced 5.0's stop-the-world collector with an incremental one and deleted
-/// `GCthreshold` outright, so there is no 5.1 counter to read. What a script *can* observe is the
-/// rule that moves it, and that rule is 5.0's own: `luaC_collectgarbage` ends
-/// `G->GCthreshold = 2*G->nblocks`, and `lua_setgcthreshold` writes `n << 10` then immediately
-/// collects if the live count has already reached it. Both are reproduced below against mlua's
-/// real heap, so `gcinfo()`'s second value tracks the first exactly as 5.0's does. The saturation
-/// is the image's: `0x6f4400` compares **unsigned** against `0x3fffff`, so a negative `n` — or one
-/// past 4194303 — saturates the threshold to `0xffffffff` bytes.
-///
-/// **The reach is measured, not assumed.** `local mem, threshold = gcinfo()` is
-/// `AceAddon-2.0.lua`'s memory report (36 copies in the 219-addon corpus), and the next line is
-/// `string.format("… %.3f MiB …", threshold / 1024)` — arithmetic on a nil, i.e. a raise inside
-/// the report. pfUI's `modules/panel.lua:170` reads the same slot as `gckb` and guards it, so it
-/// silently prints `UNAVAILABLE` where the reference prints the number. `collectgarbage` has 14
-/// corpus call sites and every one of them is a bare `collectgarbage()` whose result is
-/// discarded, so its arity has no reach today — the argument contract is what this fixes.
+/// `gcinfo` and `collectgarbage` in their 5.0 shapes. `gcinfo` (`0x703200`) takes nothing and
+/// answers `(count_KB, threshold_KB)` (`lua_getgccount 0x6f43f0`, `lua_getgcthreshold
+/// 0x6f43e0`); `collectgarbage` (`0x703250`) takes an optional number, sets the threshold to that
+/// many KB (`lua_setgcthreshold 0x6f4400`) and answers nothing, so 5.1's string options raise.
+/// 5.1's collector has no threshold, so it is kept here by 5.0's rules against mlua's heap: a
+/// live count that reaches it collects, and a collection resets it to twice the live count.
 fn install_gc(lua: &Lua) -> mlua::Result<()> {
-    /// 5.0's `GCthreshold`, in **bytes** — the registry cell standing in for `[G+0x24]`.
+    /// 5.0's `GCthreshold` (`[G+0x24]`), in bytes.
     const REG_GC_THRESHOLD: &str = "__benilla_gc_threshold";
     /// `lua_setgcthreshold 0x6f4400`'s unsigned bound, in kilobytes.
     const MAX_THRESHOLD_KB: i64 = 0x3f_ffff;
@@ -365,33 +173,30 @@ fn install_gc(lua: &Lua) -> mlua::Result<()> {
 
     settle(lua)?;
 
-    // `gcinfo()` — no argument, two numbers, cannot raise.
+    // `gcinfo()`: no argument, two numbers, never raises.
     lua.globals().set(
         "gcinfo",
         lua.create_function(|lua, ()| {
             let live = live_bytes(lua);
             let mut threshold: f64 = lua.named_registry_value(REG_GC_THRESHOLD).unwrap_or(0.0);
-            // **5.0's invariant, not just its arithmetic.** `luaC_checkGC` runs on allocation, so
-            // the instant `nblocks` reaches `GCthreshold` a collection fires and re-settles the
-            // threshold to `2 * nblocks`. A script therefore never observes a threshold at or
-            // below the live count. We have no allocation hook, so the same rule is applied on
-            // read: without it the cell set at construction goes stale as the heap grows and
-            // `gcinfo()` reports a threshold *under* its own count, a state 5.0 cannot hold.
+            // 5.0 collects the moment the live count reaches the threshold (`luaC_checkGC`), so a
+            // script never sees a threshold at or below the count. With no allocation hook here,
+            // the same rule runs on read.
             if (live as f64) >= threshold {
                 settle(lua)?;
                 threshold = lua.named_registry_value(REG_GC_THRESHOLD).unwrap_or(0.0);
             }
-            // Both shifts are the image's own `shr eax,0xa`.
+            // Both in KB, the reference's `shr eax,0xa`.
             Ok(((live >> 10) as f64, (threshold as u64 >> 10) as f64))
         })?,
     )?;
 
-    // `collectgarbage([n])` — a number, no return values, and a raise on anything that is not one.
+    // `collectgarbage([n])`: a number, no return values, and a raise on anything else.
     lua.globals().set(
         "collectgarbage",
         lua.create_function(|lua, arg: Value| {
-            // `luaL_optnumber(L, 1, 0.0)`: absent or nil takes the default; a numeric STRING is
-            // coerced (the image's `lua_tonumber` runs `strtod`); anything else is a type error.
+            // `luaL_optnumber(L, 1, 0.0)`: absent or nil is the default, a numeric string is
+            // coerced (`lua_tonumber` runs `strtod`), anything else is a type error.
             let n = match &arg {
                 Value::Nil => 0.0,
                 Value::Integer(i) => *i as f64,
@@ -423,8 +228,8 @@ fn install_gc(lua: &Lua) -> mlua::Result<()> {
                 kb * 1024.0
             };
             lua.set_named_registry_value(REG_GC_THRESHOLD, threshold_bytes)?;
-            // `luaC_checkGC`: collect when the live count has reached the threshold, and the
-            // collection then re-settles it to `2 * nblocks`.
+            // `luaC_checkGC`: a live count at the threshold collects, and the collection
+            // re-settles it to `2 * nblocks`.
             if (live_bytes(lua) as f64) >= threshold_bytes {
                 lua.gc_collect()?;
                 settle(lua)?;
@@ -435,37 +240,22 @@ fn install_gc(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The type name `luaL_typerror` would print — `luaT_typenames 0x811cd0`'s spelling.
-/// **`assert` answers ONE value in 5.0, and all of its arguments in 5.1.**
-///
-/// `luaB_assert 0x7031a0` is five calls: `luaL_checkany 0x6f4bb0` on argument 1,
-/// `lua_toboolean 0x6f3660`, and on the truthy leg `0x7031e5 call 0x6f3080` — `lua_settop(L, 1)`
-/// — then `0x7031ea mov eax,1`. The false leg is
-/// `luaL_optlstring(L, 2, "assertion failed!" /*0x872bdc*/)` into `luaL_error 0x6f4940`, which
-/// longjmps. 5.1 replaced the settop/`mov eax,1` pair with `return lua_gettop(L)`, so
-/// `assert(a, b)` answers two values there and one here.
-///
-/// Found by the shape gate's base-library arm once it grew an argument ladder — the row
-/// (`arity 1 exact`) has been in `reference/1.12-shapes.tsv` since it was vendored, and a
-/// no-argument probe could never reach it because `assert()` raises.
-///
-/// **Reach, measured rather than assumed:** 5 647 `assert(` sites across the 219-addon corpus and
-/// 73 in the shipped FrameXML, and **zero** of them bind more than one name from the result. So
-/// this buys the contract, not a fixed addon — the same footing as `collectgarbage`'s argument
-/// (2136 §3). The next caller to write `local a, b = assert(f())` is the one that finds out.
+/// `assert` in its 5.0 shape (`luaB_assert 0x7031a0`): it answers only its first argument
+/// (`lua_settop(L, 1)` at `0x7031e5`) where 5.1 answers them all, and a false value raises
+/// argument 2 or `assertion failed!` (`0x872bdc`) through `luaL_error 0x6f4940`.
 fn install_assert(lua: &Lua) -> mlua::Result<()> {
     let f = lua.create_function(|lua, args: mlua::MultiValue| {
         let mut it = args.into_iter();
-        // `luaL_checkany 0x6f4bb0` — an ABSENT argument 1 raises; an explicit `nil` does not, it
-        // is the falsy leg below.
+        // `luaL_checkany 0x6f4bb0`: an absent argument 1 raises; an explicit `nil` takes the
+        // falsy leg below.
         let Some(v) = it.next() else {
             return Err(mlua::Error::RuntimeError(
                 "bad argument #1 to `assert' (value expected)".into(),
             ));
         };
         if matches!(v, Value::Nil | Value::Boolean(false)) {
-            // `luaL_optlstring` — a string or a number; anything else is its own bad-argument
-            // raise, in 5.0's own quoting (2122).
+            // `luaL_optlstring`: a string or a number; anything else raises its own bad
+            // argument, the type spelled as `luaT_typenames 0x811cd0` spells it.
             let msg = match it.next() {
                 None | Some(Value::Nil) => "assertion failed!".to_string(),
                 Some(other) => match lua.coerce_string(other.clone())? {
@@ -480,7 +270,7 @@ fn install_assert(lua: &Lua) -> mlua::Result<()> {
             };
             return Err(mlua::Error::RuntimeError(msg));
         }
-        // `lua_settop(L, 1)`: the first argument, alone, whatever else was passed.
+        // `lua_settop(L, 1)`: the first argument alone, whatever else was passed.
         Ok(v)
     })?;
     lua.globals().set("assert", f)
@@ -503,16 +293,7 @@ fn type_name(v: &Value) -> &'static str {
 mod tests {
     use crate::script::UiScript;
 
-    /// **`gcinfo()` answers TWO numbers, and the second one is what the corpus reads**
-    /// (decision 2136).
-    ///
-    /// `0x703200` is `lua_getgccount` + `lua_getgcthreshold`, each `>> 10`, then `mov eax, 2`.
-    /// 5.1 kept the name and dropped the second value, so we answered one — and the reach is not
-    /// hypothetical: `AceAddon-2.0.lua`'s memory report is
-    /// `local mem, threshold = gcinfo()` followed by `string.format("… %.3f MiB …",
-    /// threshold / 1024)`, which is arithmetic on a nil, i.e. a raise *inside* the report, in a
-    /// library 36 corpus addons embed. pfUI's `modules/panel.lua:170` reads the same slot as
-    /// `gckb`, guards it, and so prints `UNAVAILABLE` where the reference prints a number.
+    /// `0x703200`: `lua_getgccount` and `lua_getgcthreshold`, each `>> 10`, two values.
     #[test]
     fn gcinfo_answers_two_numbers_as_1_12_does() {
         let s = UiScript::new().unwrap();
@@ -527,15 +308,13 @@ mod tests {
             vec!["number".to_string(), "number".to_string()],
             "(number,number) — `1.12-shapes.tsv` types the row `agree`"
         );
-        // 5.0's collector keeps `GCthreshold` above `nblocks` (`luaC_checkGC` collects the moment
-        // they meet, and the collection re-settles the threshold to `2 * nblocks`), so a script
-        // cannot observe the pair inverted.
+        // `luaC_checkGC` keeps 5.0's threshold above the live count.
         assert!(
             s.eval::<bool>("local c, t = gcinfo() return t > c")
                 .unwrap(),
             "the threshold must sit above the live count, as 5.0's collector guarantees"
         );
-        // AceAddon-2.0's own line, verbatim in shape — this is the raise the fix removes.
+        // AceAddon-2.0's memory report divides the second value by 1024.
         assert!(
             s.eval::<String>(
                 "local mem, threshold = gcinfo() \
@@ -546,12 +325,8 @@ mod tests {
         );
     }
 
-    /// **`collectgarbage` answers NOTHING and takes a NUMBER** (decision 2136) — the two dialects
-    /// are inverted on the argument, so this is not a superset either way.
-    ///
-    /// `0x703250` is 35 bytes: `luaL_optnumber(L, 1, 0.0)` → `_ftol` → `lua_setgcthreshold` →
-    /// `xor eax,eax`. There is no string-option dispatch anywhere in it — that is 5.1's
-    /// `collectgarbage`, and on this client `gcinfo()` is the only way to read the counters.
+    /// `0x703250`: `luaL_optnumber(L, 1, 0.0)`, `_ftol`, `lua_setgcthreshold`, no values, and no
+    /// string options.
     #[test]
     fn collectgarbage_answers_nothing_and_takes_a_number() {
         let s = UiScript::new().unwrap();
@@ -560,12 +335,12 @@ mod tests {
             0,
             "`xor eax,eax` at 0x70326f — 5.1 returns one value here"
         );
-        // The reference's ONLY argument form, which stock 5.1 rejects as ``invalid option `0'``.
+        // The reference's only argument form, a number, which stock 5.1 rejects.
         assert_eq!(s.arity("collectgarbage(0)").unwrap(), 0);
         assert!(s.eval::<()>("collectgarbage(2048)").is_ok());
-        // `lua_tonumber` coerces a numeric string through `strtod`, so this one is accepted.
+        // `lua_tonumber` coerces a numeric string through `strtod`.
         assert!(s.eval::<()>(r#"collectgarbage("100")"#).is_ok());
-        // …and a non-numeric string is a type error, in 5.0's own words.
+        // A non-numeric string is a type error, in 5.0's words.
         let e = s
             .eval::<()>(r#"collectgarbage("count")"#)
             .unwrap_err()
@@ -574,7 +349,7 @@ mod tests {
             e.contains("bad argument #1 to `collectgarbage' (number expected, got string)"),
             "5.1's string options must not exist here: {e}"
         );
-        // An explicit threshold above the live count is what `gcinfo` then reports back.
+        // An explicit threshold above the live count is what `gcinfo` reports back.
         assert!(s
             .eval::<bool>(
                 "local c = gcinfo() collectgarbage(c * 4) local _, t = gcinfo() return t >= c"
@@ -582,15 +357,8 @@ mod tests {
             .unwrap());
     }
 
-    /// **A `loadstring` chunk is named by its own SOURCE, and an explicit name is used verbatim**
-    /// (decision 2136).
-    ///
-    /// `luaB_loadstring 0x703280` pushes the string `luaL_checklstring` just returned as
-    /// `luaL_optlstring`'s `def` (`0x70329a`), so the default chunk name is the source text and
-    /// `luaO_chunkid 0x6f5c40` renders it `[string "…"]`. We prepended `=` — chunkid's
-    /// "print verbatim, undecorated" marker — which stripped the wrapper off every explicit name,
-    /// left a literal `@` on a path-shaped one, and named a nameless chunk `(loadstring)`, a
-    /// literal the image does not contain. All four are the prefix of a player-visible error.
+    /// `luaB_loadstring 0x703280` names a chunk by its source unless given a name (`0x70329a`),
+    /// and `luaO_chunkid 0x6f5c40` renders each form.
     #[test]
     fn a_loadstring_chunk_is_named_by_its_own_source() {
         let s = UiScript::new().unwrap();
@@ -605,16 +373,15 @@ mod tests {
             "the default name is the source: {}",
             raised(r#""error('boom')""#)
         );
-        // `'='` — printed verbatim with the marker removed, exactly once.
+        // `=`: printed verbatim, the marker removed once.
         assert!(raised(r#""error('boom')", "=myname""#).starts_with("myname:1: boom"));
-        // `'@'` — the file branch; the path prints plainly, without the marker.
+        // `@`: the file form, the path printed plainly.
         assert!(raised(r#""error('boom')", "@a/b.lua""#).starts_with("a/b.lua:1: boom"));
-        // No marker — the third branch wraps it, which is what an unprefixed name gets. Four
-        // corpus sites pass one (`loadstring(code, "safecall Dispatcher["..n.."]")`).
+        // No marker: wrapped as a string chunk.
         assert!(raised(r#""error('boom')", "plain""#).starts_with(r#"[string "plain"]:1: boom"#));
 
-        // The failure leg returns Lua's message unchanged — `load_aux` pushes nil and the string
-        // and stops. mlua's `Display` prefixes a category word that the image never adds.
+        // The failure leg returns Lua's message unchanged (`load_aux`), without the category word
+        // mlua's `Display` adds.
         let e: String = s
             .eval(r#"local f, e = loadstring("return 1+") return tostring(e)"#)
             .unwrap();
@@ -624,13 +391,8 @@ mod tests {
         );
     }
 
-    /// **`assert` answers ONE value — 5.0's `lua_settop(L, 1); return 1`, not 5.1's
-    /// `return lua_gettop(L)`** (`luaB_assert 0x7031a0`, settop at `0x7031e5`, `mov eax,1` at
-    /// `0x7031ea`).
-    ///
-    /// Found by the shape gate's base-library arm once it grew an argument ladder; the row has
-    /// said `arity 1 exact` since the table was vendored, and only a call with MORE than one
-    /// argument can tell the two dialects apart.
+    /// `luaB_assert 0x7031a0`: `lua_settop(L, 1)` at `0x7031e5`, then `mov eax,1` at `0x7031ea`;
+    /// only a call with more than one argument tells 5.0 from 5.1.
     #[test]
     fn assert_answers_one_value_and_keeps_5_0_s_messages() {
         let s = UiScript::new().unwrap();
@@ -640,7 +402,7 @@ mod tests {
             "5.0 truncates to the first argument; 5.1 returns them all"
         );
         assert_eq!(s.eval::<i64>("return (assert(7, 'x'))").unwrap(), 7);
-        // A truthy `false`-adjacent value is still truthy: only nil and false take the raise.
+        // 0 is truthy: only nil and false raise.
         assert_eq!(s.arity("assert(0)").unwrap(), 1);
 
         let raised = |call: &str| -> String {
@@ -652,15 +414,14 @@ mod tests {
         // `luaL_optlstring(L, 2, "assertion failed!" /*0x872bdc*/)`, then `luaL_error`.
         assert!(raised("assert(false)").contains("assertion failed!"));
         assert!(raised("assert(nil, 'my message')").contains("my message"));
-        // A number is a string to `luaL_optlstring`; anything else is its own bad-argument raise,
-        // in 5.0's backtick quoting (2122).
+        // A number is a string to `luaL_optlstring`; anything else is a bad argument.
         assert!(raised("assert(false, 42)").contains("42"));
         assert!(
             raised("assert(false, {})").contains("bad argument #2 to `assert' (string expected"),
             "{}",
             raised("assert(false, {})")
         );
-        // `luaL_checkany 0x6f4bb0`: an ABSENT argument 1 raises, an explicit nil does not.
+        // `luaL_checkany 0x6f4bb0`: an absent argument 1 raises, an explicit nil does not.
         assert!(
             raised("assert()").contains("bad argument #1 to `assert' (value expected)"),
             "{}",
@@ -668,12 +429,8 @@ mod tests {
         );
     }
 
-    /// **The 61-addon fix, as the addon actually writes it.**
-    ///
-    /// This is `AceLibrary.lua`'s own opening, verbatim in shape: ask the client which client it
-    /// is, take the 5.0 branch, use `table.setn`. Under mlua's stock 5.1 the last line raises
-    /// `'setn' is obsolete` and the addon's first chunk dies — taking ~84 of 218 corpus addons
-    /// with it, because the Ace/FuBar half of the ecosystem embeds this file.
+    /// `AceLibrary.lua`'s opening: it takes the 5.0 branch from `GetBuildInfo()` and calls
+    /// `table.setn`, which stock 5.1 raises on.
     #[test]
     fn acelibrarys_own_dialect_probe_takes_the_5_0_branch_and_works() {
         let s = UiScript::new().unwrap();
@@ -696,16 +453,11 @@ mod tests {
         assert_eq!(s.eval::<i64>("return AceProbe").unwrap(), 0);
     }
 
-    /// `setn`/`getn` are 5.0's real pair — a remembered size that is **not** a no-op and **not** a
-    /// field the table's owner can see.
-    ///
-    /// Both halves have already been got wrong once each. A no-op passes the Ace probe above and
-    /// fails the round-trip here; an unconditional `rawset(t, "n", …)` passes both and breaks 39
-    /// addons that walk the table (see [`LUA_5_0_TABLE_SIZE`]).
+    /// The remembered size is neither a no-op nor a visible `n` key.
     #[test]
     fn getn_and_setn_remember_a_size_without_polluting_the_table() {
         let s = UiScript::new().unwrap();
-        // No remembered size: the border, exactly as 5.1 answers.
+        // No remembered size: a count from 1 to the first nil.
         assert_eq!(s.eval::<i64>("return table.getn({1,2,3})").unwrap(), 3);
         // The size round-trips...
         assert_eq!(
@@ -713,9 +465,8 @@ mod tests {
                 .unwrap(),
             7
         );
-        // ...and is INVISIBLE to anything walking the table. This is the assertion that would have
-        // caught the first draft: AceOO-2.0's `_Embed` walks a mixin's fields with `next` and
-        // errors on any the target already has.
+        // ...and is invisible to `pairs`: AceOO-2.0's `_Embed` errors on any field its target
+        // already has.
         assert_eq!(
             s.eval::<i64>(
                 "local t = {1,2,3} table.setn(t, 0) \
@@ -725,14 +476,13 @@ mod tests {
             3,
             "a remembered size must not appear as a key — 39 corpus addons died on a stray 'n'"
         );
-        // A table that ALREADY carries a numeric `n` keeps using it, which is 5.0's own branch and
-        // why `arg.n` behaves the way 5.0-era code expects.
+        // A table that already has a numeric `n` keeps its size there, 5.0's own branch.
         assert_eq!(
             s.eval::<i64>("local t = {1,2,3, n=3} table.setn(t, 7) return t.n")
                 .unwrap(),
             7
         );
-        // ...and the bare global is the same function, not a second implementation.
+        // ...and the bare global is the same function.
         assert!(
             s.eval::<bool>("return getn == table.getn").unwrap(),
             "a divergent `getn` global is how the two answers start disagreeing"
@@ -740,10 +490,6 @@ mod tests {
     }
 
     /// The 5.1-only members are gone, so an addon's feature detection picks 1.12's branch.
-    ///
-    /// `string.gmatch or string.gfind` is the line **directly below** Ace's `setn` probe: with
-    /// both present it takes `gmatch`, a function 1.12 does not have. That is 1189's superset
-    /// argument one level below `_G`, and this is the test that keeps it true.
     #[test]
     fn the_5_1_only_members_are_not_offered() {
         let s = UiScript::new().unwrap();
@@ -763,7 +509,7 @@ mod tests {
                 "{expr} is a Lua 5.1 addition — 1.12 does not have it"
             );
         }
-        // ...and the 5.0 spellings that replace them are present.
+        // ...and the 5.0 spellings are present.
         for expr in ["string.gfind", "math.mod", "table.setn", "table.foreach"] {
             assert!(
                 s.eval::<bool>(&format!("return {expr} ~= nil")).unwrap(),
@@ -772,7 +518,7 @@ mod tests {
         }
     }
 
-    /// `mod` still works after `math.fmod` is removed — the stdlib layer aliased the 5.1 name.
+    /// The bare `mod` is `math.mod`, so it survives `math.fmod`'s removal.
     #[test]
     fn the_bare_math_family_survives_the_removals() {
         let s = UiScript::new().unwrap();
@@ -780,7 +526,25 @@ mod tests {
         assert_eq!(s.eval::<f64>("return floor(2.7)").unwrap(), 2.0);
     }
 
-    /// The three compat globals the reference has and we did not.
+    /// `...` parses in a parameter list and nowhere else; `arg` carries the arguments.
+    #[test]
+    fn vararg_is_a_declaration_only() {
+        let s = UiScript::new().unwrap();
+        let parses = |src: &str| s.run(src).is_ok();
+        // Declaration, and 5.0's way to read what it captured.
+        assert!(parses("return function(x, ...) return x end"));
+        assert!(parses("return function(x, ...) return arg.n end"));
+        assert!(parses(
+            "local f = tostring return function(x, ...) return f(x, unpack(arg)) end"
+        ));
+        // Every use of `...` as an expression fails, at chunk level too, where 5.1 allows it.
+        assert!(!parses("return function(x, ...) return ... end"));
+        assert!(!parses(
+            "local f = tostring return function(x, ...) return f(x, ...) end"
+        ));
+        assert!(!parses("local a = ... return a"));
+    }
+
     #[test]
     fn sort_foreach_and_foreachi_are_bare_globals_like_the_reference() {
         let s = UiScript::new().unwrap();
@@ -801,11 +565,6 @@ mod tests {
         );
     }
 
-    /// The `bit` library exists in 1.12 and we did not have it (decision 1196).
-    ///
-    /// `InitLua 0x7039e0` opens exactly five libraries and `bit` is the fifth; the captured `_G`
-    /// lists it as `engine`. The corpus's `attempt to index global 'bit'` had been written off as
-    /// an addon reaching past 1.12 — it was reaching past *us*.
     #[test]
     fn the_bit_library_is_present_with_the_references_eight_functions() {
         let s = UiScript::new().unwrap();
@@ -818,7 +577,7 @@ mod tests {
                 "bit.{name} is one of the array's eight entries"
             );
         }
-        // Two's complement, signed out — `bnot(0)` is -1, not 4294967295.
+        // Two's complement, signed out: `bnot(0)` is -1, not 4294967295.
         assert_eq!(s.eval::<i64>("return bit.bnot(0)").unwrap(), -1);
         assert_eq!(
             s.eval::<i64>("return bit.band(0x1234, 0xFF)").unwrap(),
@@ -827,46 +586,26 @@ mod tests {
         assert_eq!(s.eval::<i64>("return bit.bor(0xF0, 0x0F)").unwrap(), 0xFF);
         assert_eq!(s.eval::<i64>("return bit.bxor(0xFF, 0x0F)").unwrap(), 0xF0);
         assert_eq!(s.eval::<i64>("return bit.lshift(1, 4)").unwrap(), 16);
-        // The pair everyone gets wrong: rshift is logical, arshift propagates the sign.
+        // `rshift` is logical, `arshift` propagates the sign.
         assert_eq!(s.eval::<i64>("return bit.rshift(-1, 28)").unwrap(), 15);
         assert_eq!(s.eval::<i64>("return bit.arshift(-1, 28)").unwrap(), -1);
-        // The shift count masks to 5 bits, like the x86 instruction it compiles to.
+        // The shift count masks to 5 bits, as the x86 instruction does.
         assert_eq!(s.eval::<i64>("return bit.lshift(1, 32)").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return bit.mod(17, 5)").unwrap(), 2);
     }
 
-    /// `print` and `_VERSION` are **not** in 1.12's `_G`, and `__pow` is.
-    ///
-    /// All three are things a `_G`-shaped instrument could always have caught and nobody had
-    /// looked: the first two sat on the beyond-1.12 exception list as "inherited rather than
-    /// chosen", and the third was simply missing.
+    /// `print` and `_VERSION` are not in 1.12's `_G`, and `__pow` is.
     #[test]
     fn the_base_library_matches_the_captured_globals() {
         let s = UiScript::new().unwrap();
         assert!(s.eval::<bool>("return print == nil").unwrap());
         assert!(s.eval::<bool>("return _VERSION == nil").unwrap());
-        // 5.0 implements `^` by calling `__pow`; 5.1 made it native and the global vanished.
+        // 5.0 implements `^` by calling `__pow`.
         assert_eq!(s.eval::<f64>("return __pow(2, 10)").unwrap(), 1024.0);
     }
 
-    /// **The corpus's other dialect probe, answered the way 1.12's parser answers it** (2101,
-    /// closing 1208).
-    ///
-    /// Ace2 asks "am I on Lua 5.1?" by compiling a 5.1-only construct — the vararg *expression*,
-    /// which 5.0 has no grammar for (5.0 collects varargs into `arg`; the shipped 1.12 FrameXML
-    /// reads `arg`/`arg.n` 64 times across 177 files and never once writes `...` as a value):
-    ///
-    /// ```lua
-    /// local lua51 = loadstring("return function(...) return ... end") and true or false
-    /// ```
-    ///
-    /// 170 `loadstring` sites across the 219-addon corpus are that one question. Answering it
-    /// `true` puts every Ace-embedding addon on its client-2.0 branch — which is how Cartographer
-    /// came to hook `CloseSpecialWindows`, a name 1.12's `_G` does not have.
-    ///
-    /// The fix is the parser, not a library: `simpleexp` (client `0x6fd240`) has no `TK_DOTS`
-    /// arm, so `...` as a value falls to `prefixexp` and raises. The exact probe line is asserted
-    /// here in the shape the addons write it.
+    /// Ace2's `lua51` probe, `loadstring("return function(...) return ... end")`, fails as on
+    /// 1.12: the reference's `simpleexp` (`0x6fd240`) has no `...` arm.
     #[test]
     fn the_vararg_expression_is_a_syntax_error_as_it_is_on_1_12() {
         let s = UiScript::new().unwrap();
@@ -877,8 +616,7 @@ mod tests {
             .unwrap(),
             "the Ace2 lua51 probe must answer false, as it does on the 1.12 client"
         );
-        // ...and it fails the way 5.0 fails it: `simpleexp`'s default arm -> `prefixexp`, whose
-        // head accepts only `(` or a NAME. Same reject site, same words, as a stray `;`.
+        // `prefixexp` then accepts only `(` or a name, so this is 5.0's own `unexpected symbol`.
         let msg: String = s
             .eval(r#"local f, e = loadstring("return ...") return tostring(e)"#)
             .unwrap();
@@ -886,36 +624,29 @@ mod tests {
             msg.contains("unexpected symbol"),
             "5.0's own message for this, not a bespoke one: {msg}"
         );
-        // The 5.0 half of the same question, which we already answered correctly (1194): `arg`.
+        // The 5.0 half of the question: `arg`.
         assert_eq!(
             s.eval::<i64>("local f = function(...) return arg.n end return f(1, 2, 3)")
                 .unwrap(),
             3,
             "`arg` is 5.1's compat-vararg table, which is the form all of 1.12 FrameXML uses"
         );
-        // And now EVERY vararg function gets one. 5.1 cleared VARARG_NEEDSARG for any function
-        // that mentioned `...`; with the arm deleted nothing clears it, which is 5.0's rule.
+        // Every vararg function gets `arg`, 5.0's rule: without that arm nothing clears
+        // `VARARG_NEEDSARG`.
         assert_eq!(
             s.eval::<i64>("local f = function(a, ...) return arg.n end return f(1, 2, 3)")
                 .unwrap(),
             2
         );
-        // A `...` in a PARAMETER LIST is 5.0's own grammar and must still parse — the deletion is
-        // `simpleexp`'s arm, not `parlist`'s.
+        // A `...` in a parameter list still parses: the deletion is `simpleexp`'s arm, not
+        // `parlist`'s.
         assert!(s
             .eval::<bool>(r#"return loadstring("return function(...) return arg.n end") ~= nil"#)
             .unwrap());
     }
 
-    /// **`#` and `%` are not in 1.12's grammar either** (2101) — the same class, the same
-    /// byte evidence, gated in the same hunk-set.
-    ///
-    /// `getunopr` (`0x6fe0a0`) is a leaf testing exactly two tokens, `-` and `not`, so its
-    /// `OPR_NOUNOPR` is 2 — a three-member enum, 5.0's, not 5.1's four-member one with
-    /// `OPR_LEN`. `getbinopr` (`0x6fe0c0`) bases its switch at `'*'` (0x2A); `%` is 0x25, below
-    /// the range, and reaches `OPR_NOBINOPR` = 14 — a fifteen-member `BinOpr`, again 5.0's. The
-    /// metamethod-name pool at `0x871896` has neither `__len` nor `__mod`, which is where
-    /// wow-5875-re saw it first (`system/ui/scratch/lua-dialect.md` §1).
+    /// The reference's `getunopr` (`0x6fe0a0`) knows only `-` and `not`, its `getbinopr`
+    /// (`0x6fe0c0`) has no `%`, and its metamethod names (`0x871896`) have no `__len` or `__mod`.
     #[test]
     fn the_length_and_modulo_operators_are_not_in_the_grammar() {
         let s = UiScript::new().unwrap();
@@ -926,21 +657,16 @@ mod tests {
                 "{probe} is 5.1-only syntax; 1.12's parser rejects it"
             );
         }
-        // The 5.0 spellings of both, which the reference has and every 1.12-era addon uses.
+        // 5.0's spellings of both.
         assert_eq!(s.eval::<i64>("return table.getn({1,2,3})").unwrap(), 3);
         assert_eq!(s.eval::<i64>("return getn({1,2,3})").unwrap(), 3);
         assert_eq!(s.eval::<f64>("return math.mod(7, 3)").unwrap(), 1.0);
         assert_eq!(s.eval::<i64>("return string.len('abcd')").unwrap(), 4);
     }
 
-    /// **The shapes the reference's own files are written in still load** — the other half of the
-    /// gate, and the one that would make it a regression if it ever stopped being true.
-    ///
-    /// Measured, not assumed: the three constructs above appear **zero** times in the extracted
-    /// 1.12 FrameXML (177 files), GlueXML, Blizzard's own addons, and the director's installed
-    /// AddOns folder. This chunk is the 5.0 grammar those files actually use, including the three
-    /// 5.0-isms the fork restores (1215's iterator-less generic-for, `LUA_COMPAT_LSTR`'s nesting
-    /// long strings, 1315's constructor semicolon).
+    /// The 5.0 grammar the stock files use still parses, including the three constructs the fork
+    /// restores: the iterator-less generic-for, nested long strings (`LUA_COMPAT_LSTR`) and the
+    /// constructor's extra semicolon.
     #[test]
     fn the_5_0_grammar_the_reference_writes_still_parses() {
         let s = UiScript::new().unwrap();
@@ -967,19 +693,12 @@ mod tests {
         );
     }
 
-    /// **The six `debug*` stubs are the REFERENCE's no-ops, not ours** — and that distinction is
-    /// the whole reason they are allowed to exist under real 1.12 names.
-    ///
-    /// wow-re carved all eight (2026-08-11): `debuginfo`, `debugload`, `debugprint`, `debugdump`,
-    /// `debugbreak` and `debugtimestamp` are byte-identical `xor eax,eax; ret` — three bytes, no
-    /// call, no memory write, **zero Lua return values**. Only `debugprofilestart`/`stop` are real.
-    /// A no-op we invented would be the "capability absent without a failure" class 1203 named;
-    /// a no-op the client itself ships is a transcription.
+    /// Six of the reference's eight `debug*` functions (`[0x7027e0, 0x702840)`) are
+    /// `xor eax,eax; ret`, returning nothing; only `debugprofilestart`/`stop` are real.
     #[test]
     fn the_debug_family_is_six_stubs_and_two_real_ones() {
         let s = UiScript::new().unwrap();
-        // Zero values, not nil — a count is the only check that can tell them apart, and
-        // `arity` is where it is taken now that `select` is gone (2171).
+        // Zero values, not one nil: only a count tells them apart.
         for name in [
             "debuginfo",
             "debugload",
@@ -994,18 +713,14 @@ mod tests {
                 "{name} returns nothing at all"
             );
         }
-        // ...and the two that are real answer a number of milliseconds.
+        // ...and the two real ones answer milliseconds.
         let ms: f64 = s
             .eval("debugprofilestart() return debugprofilestop()")
             .unwrap();
         assert!(ms >= 0.0, "elapsed milliseconds, not nil: {ms}");
     }
 
-    /// The divergence that USED to be pinned here is gone (decision 2102): `table.insert` now
-    /// consults the remembered size, as `0x7fb6d8` does. The behaviour it asserted — an append
-    /// landing at the border after `setn(t, 0)` — was traced to a real addon failure, so the
-    /// mechanism moved to [`super::table_size`] and its tests moved with it. This is the one line
-    /// that used to say otherwise, kept as the shape a reader will look for.
+    /// `table.insert` appends after the remembered size (its `luaL_getn` call, `0x7fb6d8`).
     #[test]
     fn table_insert_consults_the_remembered_size() {
         let s = UiScript::new().unwrap();
@@ -1017,31 +732,15 @@ mod tests {
         );
     }
 
-    /// **`{ [1] = a, [2] = b, … }` is a LIST, and `pairs` walks it 1, 2, 3** — decision 2111, the
-    /// fourth "restore what 5.1 changed" hunk in `third_party/lua-src`.
-    ///
-    /// 1.12's `recfield` keeps `cc->nh++` **inside** its `TK_NAME` arm (`0x6fd5a4`'s
-    /// `cmp [edi+0x10],0x116` / `0x6fd5ad jne 0x6fd5d4` — 5.0's own placement), so a
-    /// `[expr] = value` field credits **neither** `OP_NEWTABLE` size hint. The table is born with
-    /// `B = C = 0`, i.e. on the shared dummy node, so the first store finds no free node, takes
-    /// `luaH_newkey`'s rehash tail, and `rehash` sizes an **array part** for the dense integer
-    /// keys; `luaH_next` walks the array part first, ascending by index, and the node part after.
-    /// Stock 5.1 moved that `cc->nh++` out of the arm, pre-sized a node vector big enough that no
-    /// rehash ever fires, and left all n keys in the hash — where `next` is slot order.
-    ///
-    /// wow-5875-re `system/ui/scratch/lua-table-storage-and-next-order.md` — **executed** on
-    /// `WoW.exe`'s own bytes (`lua_open` → `luaL_loadbuffer` → `lua_pcall` → `lua_next`), not
-    /// derived, including the exact `Bagnon_Core.lua` below; ascending holds for n = 1..24 and
-    /// regardless of the order the fields are written in.
-    ///
-    /// It matters because every saved-variables file we write is that constructor (decision 1128's
-    /// grammar, and the reference's own writer's — it never emits a bare positional entry), so
-    /// before this hunk every list an addon saved came back in hash order. Bagnon 6.10.22 walks
-    /// its saved bag order with `pairs` and drew the keyring first, ahead of the backpack.
+    /// A `{ [1] = a, [2] = b }` constructor builds an array part, so `pairs` walks it in index
+    /// order. The reference's `recfield` credits no size hint for a `[expr] =` field (its
+    /// `TK_NAME` test at `0x6fd5a4`), so the table starts on the dummy node and the first store's
+    /// rehash sizes an array part, which `luaH_next` walks before the hash. Saved variables are
+    /// written in this form, as the reference writes them, so a saved list reloads in order.
     #[test]
     fn a_bracketed_key_constructor_is_an_array_and_walks_in_index_order() {
         let s = UiScript::new().unwrap();
-        // Bagnon's own table, exactly as its saved-variables file spells it.
+        // Bagnon's own table, as its saved-variables file spells it.
         assert_eq!(
             s.eval::<String>(
                 "local t = { [1] = 0, [2] = 1, [3] = 2, [4] = 3, [5] = 4, [6] = -2 }
@@ -1051,7 +750,7 @@ mod tests {
             "0,1,2,3,4,-2,",
             "the keyring (-2) is LAST — this is the director's Bagnon grid"
         );
-        // …and the order the fields are written in does not change it.
+        // The order the fields are written in does not change it.
         assert_eq!(
             s.eval::<String>(
                 "local t = { [3] = 'c', [1] = 'a', [2] = 'b' }
@@ -1069,8 +768,7 @@ mod tests {
             .unwrap(),
             "1,2,3,a,"
         );
-        // The positional spelling was always an array and still is — the control that keeps the
-        // first assertion from reading as vacuous.
+        // Control: the positional spelling is an array too.
         assert_eq!(
             s.eval::<String>(
                 "local t = { 0, 1, 2, 3, 4, -2 }
@@ -1086,30 +784,9 @@ mod tests {
 mod error_quoting_tests {
     use crate::script::UiScript;
 
-    /// **Every error message quotes a program element the way 5.0 does — `` `x' ``, not `'x'``
-    /// (decision 2122).**
-    ///
-    /// 5.1 introduced `LUA_QL` and made it two apostrophes; the fork's `luaconf.h` puts 5.0's
-    /// backquote back. The five formats it feeds are all readable in `WoW.exe`'s own `.rdata`, and
-    /// the assertions below are those strings:
-    ///
-    /// ```text
-    /// bad argument #%d to `%s' (%s)          lauxlib.c luaL_argerror
-    /// calling `%s' on bad self (%s)          lauxlib.c luaL_argerror's method arm
-    /// attempt to %s %s `%s' (a %s value)     ldebug.c  luaG_typeerror
-    /// %s:%d: %s near `%s'                    llex.c    luaX_lexerror (the client's own 0x87217c)
-    ///  in function `%s'                      ldblib.c  the line debugstack renders
-    /// ```
-    ///
-    /// **The traceback line is the one this does NOT reach**, and it is the one with teeth.
-    /// `debugstack` delegates to mlua's own traceback, which is built in mlua's C shim rather than
-    /// in this fork, so `LUA_QL` does not reach it: it still renders `in function 'X'`. That
-    /// matters because AceLibrary — shipped inside ~80 corpus addons — reads its own caller back
-    /// out of `debugstack()` with `string.find(debugstack(), "`argCheck'.-([`<].-['>])")`, whose
-    /// two patterns both require the backquote; the nil it gets is then handed to a `%s`, so an
-    /// argument-check *diagnostic* raises inside the error path. Closing that means rendering the
-    /// traceback ourselves in the reference's own shape, which is dispatched into wow-re
-    /// (`debugstack 0x703760`) rather than copied from stock 5.0's `ldblib.c`.
+    /// Error messages quote a program element as the reference does, `` `x' ``: the fork's
+    /// `luaconf.h` restores 5.0's `LUA_QL`, and `debugstack` renders its own frames the same way
+    /// (`0x703760`).
     #[test]
     fn errors_quote_program_elements_the_way_lua_5_0_does() {
         let s = UiScript::new().unwrap();
@@ -1132,7 +809,7 @@ mod error_quoting_tests {
             e.contains("bad argument #1 to `rep'"),
             "argerror keeps 5.1's quoting: {e}"
         );
-        // luaX_lexerror — the client's own `0x87217c` format.
+        // luaX_lexerror, the client's `0x87217c` format.
         let e = s
             .eval::<String>(r#"local f, e = loadstring("return 1 +") return tostring(e)"#)
             .unwrap();
@@ -1140,10 +817,7 @@ mod error_quoting_tests {
             e.contains("near `<eof>'"),
             "the lexer keeps 5.1's quoting: {e}"
         );
-        // And no message anywhere OPENS a quote with an apostrophe — 5.1's spelling puts one
-        // where 5.0 puts the backquote, so the tell is a `'` right after a space or a paren.
-        // (The closing quote is an apostrophe in both dialects, which is why this looks for the
-        // opening one and not for the character.)
+        // No message opens a quote with an apostrophe; the closing quote is one in both dialects.
         for e in [
             err("local t = nil return t.x"),
             err("return nosuchfn()"),
@@ -1156,22 +830,9 @@ mod error_quoting_tests {
         }
     }
 
-    /// **`select` is not a 1.12 global** (decision 2171) — and 5.0's own answer to the same
-    /// question still is.
-    ///
-    /// The pair matters more than the removal. `select('#', …)` was how 177 of our own tests asked
-    /// a binding's arity, and the property those gates rest on is that **zero returns and one
-    /// `nil` are different answers** (`binding_abi` §2) — a distinction no `Option<T>` return type
-    /// can hold. 5.0 answers it with the implicit vararg table's `n`, which this VM hands every
-    /// vararg function since 2101 deleted the parser arm that cleared `VARARG_NEEDSARG`; the host
-    /// answers it with [`UiScript::arity`]. If either ever stops telling those apart, the arity
-    /// gates start silently passing a binding that returns nothing.
-    ///
-    /// The removal's own reach is in the corpus rather than here: `pfUI/libs/libpredict.lua:141`
-    /// gates its **TBC** HealComm parser on `select and UnitCastingInfo`, and pfUI supplies the
-    /// second name itself (`libs/libcast.lua:86`, loaded 3rd against libpredict's 10th), so
-    /// publishing `select` was the whole reason that branch ran. `BuffCheck2.lua:1157` is
-    /// `select = select or function(idx, ...)` — a 1.12 addon's own polyfill that ours suppressed.
+    /// `select` is 5.1's; 5.0 counts arguments with `arg.n`, and the host with
+    /// [`UiScript::arity`]. Both must tell zero returns from one `nil`, or an arity check passes a
+    /// binding that returns nothing.
     #[test]
     fn select_is_not_a_1_12_global_and_arg_n_answers_instead() {
         let s = UiScript::new().unwrap();
@@ -1180,7 +841,7 @@ mod error_quoting_tests {
             "`select` is 5.1's base library; `reference/1.12-globals.tsv` has no row for it"
         );
 
-        // 5.0's spelling, in the shape an addon writes it.
+        // 5.0's spelling, as an addon writes it.
         assert_eq!(
             s.eval::<Vec<i64>>(
                 "local function n(...) return arg.n end \
@@ -1193,28 +854,14 @@ mod error_quoting_tests {
             "arg.n must count trailing nils AND tell zero returns from one nil"
         );
 
-        // And the host's, which is what our own tests ask now.
+        // And the host's.
         assert_eq!(s.arity("nil").unwrap(), 1, "one nil is one value");
         assert_eq!(s.arity("ShowNameplates()").unwrap(), 0, "and zero is zero");
     }
 
-    /// **1.12 installs no metatable on the string type**, so method-call syntax on a string raises
-    /// there and quietly worked here (decision 2171).
-    ///
-    /// The claim is stronger than "nobody installs one": the reference's `lua_setmetatable
-    /// 0x6f4020` accepts exactly two type tags — `LUA_TTABLE` and `LUA_TUSERDATA`, sharing one
-    /// `mov [edx+8], esi` because 5.0 puts `metatable` at offset 8 of both structs — and returns 0
-    /// without writing for every other tag. 5.0 has no `G(L)->mt[]` array for a string to have a
-    /// slot in, so the type *cannot* carry one; `luaopen_string 0x7fd810`'s four instructions
-    /// (wow-re `lua-dialect.md` §4) are the same fact from the other end.
-    ///
-    /// The **wording** is asserted, not just the raise: it is what a player sees in a script
-    /// error, and 5.0's quoting convention is already load-bearing one file over — `sandbox`'s
-    /// `debugstack` emits 5.0 frames because `AceLibrary.lua:139`'s `argCheck` matches
-    /// ``"([`<].-['>])"`` and cannot see 5.4's `'name'` at all. Both strings are byte-verified
-    /// and executed on the reference: `.data 0x871c10` ``attempt to %s a %s value`` for the
-    /// anonymous form, `.data 0x871c2c` ``attempt to %s %s `%s' (a %s value)`` for the named one —
-    /// **backtick open, apostrophe close**.
+    /// 1.12's string type has no metatable, so a method call on a string raises, in the
+    /// reference's words: ``attempt to %s a %s value`` (`0x871c10`) and
+    /// ``attempt to %s %s `%s' (a %s value)`` (`0x871c2c`).
     #[test]
     fn the_string_type_has_no_metatable() {
         let s = UiScript::new().unwrap();
@@ -1243,9 +890,7 @@ mod error_quoting_tests {
             "the named form, with 5.0's backtick-apostrophe quoting: {named:?}"
         );
 
-        // The other direction, and the one that makes this a regression if it ever fails:
-        // removing the metatable removes a *dispatch*, never a function. The 12-member string
-        // library and the bare aliases the reference publishes over it are untouched.
+        // Only the method dispatch goes: the string library and its bare aliases still work.
         s.run(
             r#"assert(string.upper("ab") == "AB")
                assert(string.sub("hello", 2, 3) == "el")
diff --git a/crates/benilla-ui/src/script/lua50/table_size.rs b/crates/benilla-ui/src/script/lua50/table_size.rs
index eebf0d4c..d666720b 100644
--- a/crates/benilla-ui/src/script/lua50/table_size.rs
+++ b/crates/benilla-ui/src/script/lua50/table_size.rs
@@ -1,54 +1,22 @@
-//! **Lua 5.0's remembered table size, and the whole library that rides it** (decision 2102).
+//! Lua 5.0's remembered table size, and the table library that reads it.
 //!
-//! 5.0 does **not** simply write `t.n`. `luaL_setn` (`0x6f4ea0`) writes `t.n` *only if a
-//! non-negative numeric `t.n` already exists*; otherwise it stores the size in a weak-keyed table
-//! kept in the registry (`getsizes 0x6f4fc0`, registry slot 2), so the size is invisible to
-//! anything walking the table. `luaL_getn` (`0x6f5050`) reads `t.n`, then `sizes[t]`, then counts
-//! `rawgeti` from 1 until the first nil.
+//! `luaL_setn` (`0x6f4ea0`) writes `t.n` only when a non-negative numeric `t.n` exists, else it
+//! stores the size in a weak-keyed registry table (`getsizes` `0x6f4fc0`, slot 2) no walk can see.
+//! `luaL_getn` (`0x6f5050`) reads `t.n`, then that table, then counts `rawgeti` from 1 to the
+//! first nil. `luaL_getn` serves `table.getn`, `insert`, `remove`, `concat`, `sort`, `foreachi`
+//! and base `unpack`; `luaL_setn` serves `table.setn`, `insert` and `remove`: the library is
+//! `n`-based end to end, where 5.1's is `#`-based.
 //!
-//! **And the size is not private to `getn`/`setn` — the whole table library rides it.** wow-re's
-//! exhaustive rel32 census (`system/ui/scratch/lua-dialect.md` §4) lists every call site:
-//! `luaL_getn` is called by `table.getn`, `table.insert`, `table.remove`, `table.concat`,
-//! `table.sort`, `table.foreachi` and **base `unpack`**; `luaL_setn` by `table.setn`,
-//! `table.insert` and `table.remove`. So `insert`/`remove` **update** the remembered size and the
-//! six readers read it — this library is `n`-based end to end, and a `#`-based (5.1) one is a
-//! different observable.
-//!
-//! **This module shipped for months with only `getn`/`setn` converted, and the divergence was
-//! recorded as knowingly-accepted "revisit if a runtime failure is ever traced here". One was.**
-//! Mik's Scrolling Battle Text 4.43 displays nothing at all in combat, because every combat line
-//! it parses runs through
-//!
-//! ```lua
-//! MikCEH.EraseTable(unorderedCaptureData)          -- wipe, then table.setn(t, 0)
-//! … table.insert(unorderedCaptureData, capture) …  -- 5.1: lands at #t+1, size NOT updated
-//! if (table.getn(tempCapturedData) ~= 0) then      -- reads the stale 0 → "no match"
-//! ```
-//!
-//! The captures were *there* (`t[1] = "Kobold Vermin"`, `t[2] = "12"`) and `getn` answered 0, so
-//! every parser returned nil and the addon drew nothing while scoring a clean load. That is the
-//! exact shape the note warned about, and it is why the readers are converted here too rather than
-//! left half-way: a library where the mutators maintain one size and the readers consult another
-//! is a worse place to stand than a uniformly wrong one.
-//!
-//! **The first draft of the `getn`/`setn` half wrote `t.n` unconditionally, and the corpus caught
-//! it inside an hour.** `AceOO-2.0`'s `_Embed` walks its mixin's exports with
-//! `next(state.export, field)` and errors on any field the target already has; a spurious `n` made
-//! that `Method conflict in attempt to mixin. Field "n"` — **39 addons**, a *bigger* wall than the
-//! `setn` gap it was meant to fix. The invisibility of the side store is load-bearing, and its
-//! test is below.
+//! The side store must stay invisible: a stray `n` key breaks mixin walks such as `AceOO-2.0`'s,
+//! which error on any field the target already has.
 
 use mlua::{Function, Lua, MultiValue, Table, Value};
 
-/// Where the weak-keyed side store lives. 5.0 keeps it in registry slot 2; mlua's registry is
-/// its own, so it gets a name instead — the property that matters is that it is reachable from
-/// nothing an addon can see.
+/// The side store's registry name; 5.0 uses slot 2, and either way no addon can reach it.
 const SIZES: &str = "benilla.lua50.sizes";
 
-/// `checkint 0x6f4f80` as `luaL_getn`/`luaL_setn` use it: a stored size counts only when it is
-/// a number **and** non-negative — a negative or absent one selects the next leg. (The
-/// reference coerces a numeric *string* here too, via `lua_tonumber`; we do not, and no corpus
-/// caller writes a string `n`.)
+/// `checkint` (`0x6f4f80`): a stored size counts only if numeric and non-negative. The reference
+/// also takes a numeric string through `lua_tonumber`; this does not.
 fn as_size(v: &Value) -> Option<i64> {
     match v {
         Value::Integer(i) => (*i >= 0).then_some(*i),
@@ -61,21 +29,12 @@ fn as_size(v: &Value) -> Option<i64> {
     }
 }
 
-/// The bound on how many elements one `insert`/`remove`/`unpack` may shift or push.
-///
-/// **Not the reference's** — 5.0 has no such limit, and this is the third knowing divergence in
-/// this module. It exists because a remembered size is an arbitrary number an addon wrote: after
-/// `table.setn(t, 2000000000)`, `table.remove(t, 1)` shifts two billion slots, and this runs in
-/// Rust, where the VM's instruction budget cannot interrupt it — a hung client rather than a slow
-/// one. A UI table never comes near a million entries; a runaway always exceeds it.
+/// The most elements one `insert`/`remove`/`unpack` may shift or push. Deviation: 5.0 has no
+/// bound, but a remembered size is whatever an addon wrote, and a Rust loop over two billion slots
+/// is beyond the VM's instruction budget: a hung client.
 const MAX_SHIFT: i64 = 1_000_000;
 
-/// `luaL_getn 0x6f5050` — `t.n`, then `sizes[t]`, then a linear count.
-///
-/// The count is `rawgeti` from 1 to the first nil, not the `#` border: 1.12's Lua has no length
-/// operator at all (decision 2101) and the two disagree on a table with holes, where `#` is
-/// explicitly undefined. It costs O(n) — exactly as it does in the reference, and only until
-/// the first `insert`/`setn` remembers a size for that table.
+/// `luaL_getn` (`0x6f5050`); its count to the first nil is not the `#` border on a holed table.
 fn get_n(sizes: &Table, t: &Table) -> mlua::Result<i64> {
     if let Some(n) = as_size(&t.raw_get::<Value>("n")?) {
         return Ok(n);
@@ -90,7 +49,7 @@ fn get_n(sizes: &Table, t: &Table) -> mlua::Result<i64> {
     Ok(i - 1)
 }
 
-/// `luaL_setn 0x6f4ea0` — into `t.n` when the table already carries one, else out of sight.
+/// `luaL_setn` (`0x6f4ea0`): into `t.n` when the table has one, else the side store.
 fn set_n(sizes: &Table, t: &Table, n: i64) -> mlua::Result<()> {
     if as_size(&t.raw_get::<Value>("n")?).is_some() {
         t.raw_set("n", n)
@@ -99,25 +58,16 @@ fn set_n(sizes: &Table, t: &Table, n: i64) -> mlua::Result<()> {
     }
 }
 
-/// Install the `n`-based table library over mlua's 5.1 one.
-///
-/// `concat` and `sort` **wrap** the C implementations rather than re-writing them: the only
-/// thing 5.0 changes about either is which number bounds the walk, and the C bodies carry the
-/// error messages (`invalid value (at index %d) in table for 'concat'`, `invalid order
-/// function for sorting`) and the sort algorithm that a Rust re-write would have to reproduce —
-/// including *not* handing a Lua comparator to Rust's `sort_by`, which panics on an
-/// inconsistent one.
+/// Install the `n`-based table library over mlua's 5.1 one. `concat` and `sort` wrap the C bodies
+/// for their error messages and algorithm (Rust's `sort_by` panics on an inconsistent comparator).
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
     let store = lua.create_table()?;
     let meta = lua.create_table()?;
-    // Weak KEYS: a table nobody else holds must still be collectable, and 5.0's own `getsizes`
-    // builds exactly this metatable.
+    // Weak keys, as 5.0's `getsizes` builds it: a table nobody else holds stays collectable.
     meta.set("__mode", "k")?;
     store.set_metatable(Some(meta))?;
-    // Kept in the registry so it survives for the VM's life and nothing an addon can reach
-    // names it — and captured by every closure below, so the hottest function in the whole UI
-    // (`table.insert`) costs two raw gets rather than a registry walk per call.
+    // Held by the registry for the VM's life; each closure below captures it.
     lua.set_named_registry_value(SIZES, store.clone())?;
     let sizes = store;
 
@@ -128,15 +78,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "getn",
         lua.create_function(move |_, t: Table| get_n(&getn_sizes, &t))?,
     )?;
-    // `table.setn 0x7fb670` — 0 results.
+    // `table.setn` (`0x7fb670`): no results.
     let setn_sizes = sizes.clone();
     t.set(
         "setn",
         lua.create_function(move |_, (t, n): (Table, i64)| set_n(&setn_sizes, &t, n))?,
     )?;
 
-    // `table.insert 0x7fb6a0` — `n = getn(t) + 1`; with a position argument the position may
-    // GROW n past it; `setn` first, then shift up from n down to pos, then store.
+    // `table.insert` (`0x7fb6a0`): `n = getn(t) + 1`, raised to a later position; `setn` first,
+    // then shift up from `n` down to `pos`, then store.
     let insert_sizes = sizes.clone();
     t.set(
         "insert",
@@ -182,8 +132,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `table.remove 0x7fb750` — an empty table (remembered size <= 0) returns NO value and
-    // touches nothing; otherwise `setn(n-1)`, take `t[pos]`, close the gap, nil the tail.
+    // `table.remove` (`0x7fb750`): at a size of 0 or less, no value and no change; else
+    // `setn(n - 1)`, take `t[pos]`, close the gap, nil the tail.
     let remove_sizes = sizes.clone();
     t.set(
         "remove",
@@ -207,7 +157,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `table.foreachi 0x7fb4e0` — 1..getn, stop and hand back the first non-nil result.
+    // `table.foreachi` (`0x7fb4e0`): `1..getn`, returning the first non-nil result.
     let foreachi_sizes = sizes.clone();
     t.set(
         "foreachi",
@@ -224,7 +174,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `table.concat 0x7fb860` — `j` defaults to getn, everything else is 5.1's own body.
+    // `table.concat` (`0x7fb860`): `j` defaults to getn; the rest is 5.1's body.
     let concat_sizes = sizes.clone();
     let concat: Function = t.get("concat")?;
     t.set(
@@ -240,12 +190,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // `table.sort 0x7fb900` — sorts `1..getn`, where 5.1's sorts `1..#t`. The two agree unless
-    // a remembered size is SHORTER than the array border, which is the only case that needs
-    // anything: lift the tail out, let the C sort run on exactly the elements 5.0 would have
-    // handed it, put the tail back. (A remembered size LONGER than the border would have 5.0
-    // comparing against nils and raising; we sort the border instead — a knowing divergence
-    // from an error path, not from a mechanism.)
+    // `table.sort` (`0x7fb900`) sorts `1..getn`, 5.1's `1..#t`: a shorter remembered size lifts
+    // the tail out around the C sort. Deviation: a longer one sorts only the border, where 5.0
+    // compares nils and raises: it departs from an error path, not from a mechanism.
     let sort_sizes = sizes.clone();
     let sort: Function = t.get("sort")?;
     t.set(
@@ -270,11 +217,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Base `unpack 0x703080` — `1..getn(t)`, by `rawgeti`. The reference takes only the table
-    // and ignores anything after it, so no 1.12 caller can pass a range meaningfully; we keep
-    // 5.1's optional `i`/`j` because two of this crate's OWN stdlib helpers pass an explicit
-    // range to carry embedded nils (`tostringall`, the positional-`format` shim), and nothing
-    // an addon can write distinguishes the two.
+    // Base `unpack` (`0x703080`): `1..getn(t)` by `rawgeti`. Deviation: the reference ignores
+    // every argument after the table; `i`/`j` stay because the positional-`format` shim passes
+    // a range to carry embedded nils.
     g.set(
         "unpack",
         lua.create_function(move |_, (t, i, j): (Table, Option<i64>, Option<i64>)| {
@@ -283,8 +228,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some(j) => j,
                 None => get_n(&sizes, &t)?,
             };
-            // The reference's `luaL_checkstack(n, "table too big to unpack")`, at the same
-            // bound the shifts take.
+            // The reference's `luaL_checkstack(n, "table too big to unpack")`, at `MAX_SHIFT`.
             if j.saturating_sub(i) >= MAX_SHIFT {
                 return Err(mlua::Error::runtime("too many results to unpack"));
             }
@@ -303,13 +247,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// **The failure that retired the "revisit if ever traced" note**, in the shape Mik's
-    /// Scrolling Battle Text 4.43 writes it (`MikCombatEventHelper.lua`'s `EraseTable` →
-    /// `GetUnorderedCaptureDataTable` → `GetCapturedData`).
-    ///
-    /// The captures are in the table and `getn` answered 0, so every combat line the addon parsed
-    /// came back "no match" and it drew nothing at all — through a clean load, a clean session and
-    /// a `drew=nothing(0)` harness row that read like an addon with nothing to draw.
+    /// Mik's Scrolling Battle Text 4.43's capture tables: wipe, `setn(t, 0)`, then insert.
     #[test]
     fn a_wipe_then_setn_zero_then_insert_is_countable_again() {
         let s = UiScript::new().unwrap();
@@ -330,11 +268,6 @@ mod tests {
         );
     }
 
-    /// `setn`/`getn` are 5.0's real pair, and the side store stays invisible.
-    ///
-    /// Both halves have been got wrong once each: a no-op `setn` fails the round-trip, and an
-    /// unconditional `rawset(t, "n", …)` passes it and breaks the 39 addons whose `AceOO-2.0`
-    /// mixin walk errors on a stray `n` (this module's header).
     #[test]
     fn the_remembered_size_round_trips_and_never_appears_as_a_key() {
         let s = UiScript::new().unwrap();
@@ -353,15 +286,13 @@ mod tests {
             3,
             "a remembered size must not appear as a key"
         );
-        // A table that already carries a numeric `n` keeps using it — 5.0's own first branch, and
-        // why `arg.n` behaves the way 5.0-era code expects.
+        // A table with a numeric `n` keeps using it: 5.0's first branch, which `arg.n` relies on.
         assert_eq!(
             s.eval::<i64>("local t = {1,2,3, n=3} table.setn(t, 7) return t.n")
                 .unwrap(),
             7
         );
-        // A NEGATIVE `n` is `checkint < 0`, which selects the side store rather than the field —
-        // `0x6f4ee4`'s `jl`.
+        // A negative `n` fails `checkint` and selects the side store (`0x6f4ee4`'s `jl`).
         assert_eq!(
             s.eval::<i64>("local t = {1,2, n=-1} table.setn(t, 5) return table.getn(t) + t.n")
                 .unwrap(),
@@ -369,11 +300,6 @@ mod tests {
         );
     }
 
-    /// The count of last resort is `rawgeti` to the first nil, not the `#` border — the two
-    /// disagree on a holed table, and `#` is not even in this VM's grammar (2101).
-    ///
-    /// This is the shape every `local t = { f() }` takes when `f` returns a nil in the middle, and
-    /// it is why `table.getn` is not a way to count returns on 1.12.
     #[test]
     fn the_fallback_count_stops_at_the_first_hole() {
         let s = UiScript::new().unwrap();
@@ -385,11 +311,10 @@ mod tests {
         assert_eq!(s.eval::<i64>("return table.getn({})").unwrap(), 0);
     }
 
-    /// `insert` with a position, and `remove` — the two that write the size back.
     #[test]
     fn insert_and_remove_maintain_the_size_the_way_the_reference_does() {
         let s = UiScript::new().unwrap();
-        // A position past the remembered size GROWS it (`if (pos > n) n = pos`).
+        // A position past the remembered size grows it (`if (pos > n) n = pos`).
         assert_eq!(
             s.eval::<String>(
                 "local t = {} table.insert(t, 3, 'c') \
@@ -398,7 +323,6 @@ mod tests {
             .unwrap(),
             "3:c"
         );
-        // Insert-at-position shifts up.
         assert_eq!(
             s.eval::<String>(
                 "local t = {'a','c'} table.insert(t, 2, 'b') \
@@ -407,7 +331,6 @@ mod tests {
             .unwrap(),
             "abc:3"
         );
-        // Remove returns the element, closes the gap, and shrinks the size.
         assert_eq!(
             s.eval::<String>(
                 "local t = {'a','b','c'} local got = table.remove(t, 1) \
@@ -416,7 +339,7 @@ mod tests {
             .unwrap(),
             "abc:2"
         );
-        // An empty table answers NO value at all and touches nothing (`if (n <= 0) return 0`).
+        // At size 0, no value and no change (`if (n <= 0) return 0`).
         assert_eq!(
             s.eval::<i64>(
                 "local t = {1,2,3} table.setn(t, 0) \
@@ -428,8 +351,6 @@ mod tests {
         );
     }
 
-    /// The four readers take the remembered size, not the border: `concat`, `sort`, `foreachi`,
-    /// and base `unpack` (wow-re's call-site census, this module's header).
     #[test]
     fn concat_sort_foreachi_and_unpack_all_read_the_remembered_size() {
         let s = UiScript::new().unwrap();
@@ -438,7 +359,6 @@ mod tests {
                 .unwrap(),
             "ab"
         );
-        // sort touches only 1..getn — the tail past it keeps both its values and its order.
         assert_eq!(
             s.eval::<String>(
                 "local t = {'c','a','z','y'} table.setn(t, 2) table.sort(t) \
@@ -463,9 +383,6 @@ mod tests {
             .unwrap(),
             "abnil"
         );
-        // The one superset this module keeps: an EXPLICIT range, which two of our own stdlib
-        // helpers pass to carry embedded nils. `tostringall`/the positional-`format` shim break
-        // without it, and no 1.12 caller can observe it (5.0's `unpack` ignores extra arguments).
         assert_eq!(
             s.eval::<String>(
                 "local t = {} t[1] = 'a' t[3] = 'c' \
@@ -475,7 +392,6 @@ mod tests {
             .unwrap(),
             "anilc"
         );
-        // ...and with nothing remembered they answer exactly what they always did.
         assert_eq!(
             s.eval::<String>("return table.concat({'a','b','c'}, '')")
                 .unwrap(),
@@ -488,8 +404,7 @@ mod tests {
         );
     }
 
-    /// The bare `getn` global and `table.getn` are one function, and `tinsert`/`tremove` — bound
-    /// by the stdlib layer, which runs after this one — are the new bodies rather than 5.1's.
+    /// `getn`, `tinsert` and `tremove`, bound by the stdlib layer after this one, are these bodies.
     #[test]
     fn the_bare_aliases_bind_the_5_0_bodies() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/macros.rs b/crates/benilla-ui/src/script/macros.rs
index 7ef1cbd2..9f5d2977 100644
--- a/crates/benilla-ui/src/script/macros.rs
+++ b/crates/benilla-ui/src/script/macros.rs
@@ -1,73 +1,42 @@
-//! Player **macros** (decision 0983) — the one seam in this crate that owns its game state
-//! outright, because the 1.12 macro system has no server side at all: there is no macro opcode on
-//! the wire (vmangos has none, and the client's own `UIMacros.cpp` persists to
-//! `WTF/…/macros-cache.txt`), so the macro table *is* client state. Contrast [`super::action`],
-//! whose 120-slot table the app owns because the server hands it back at login.
+//! Player macros. 1.12 keeps them client-side with no opcode (`macros-cache.txt`), and
+//! `CreateMacro` must return the new index at once, so the table lives here: the app seeds it
+//! ([`UiScript::set_macros`]), saves it when [`UiScript::take_macros_dirty`] says, and pushes the
+//! icon list ([`UiScript::set_macro_icons`]).
 //!
-//! That ownership is forced by the reference's own API shape, not chosen for convenience:
-//! `MacroPopupOkayButton_OnClick` does `index = CreateMacro(…)` and immediately selects `index`,
-//! so the mutation must be synchronous and must return the new slot — a queue-an-intent-and-wait
-//! seam cannot answer it. The app therefore **seeds** the table once ([`UiScript::set_macros`],
-//! from `benilla-config/macros/…`), **reads** it back to persist ([`UiScript::macros`]) whenever
-//! [`UiScript::take_macros_dirty`] says something moved, and pushes the icon-chooser list
-//! ([`UiScript::set_macro_icons`]) it builds off `SpellIcon.dbc`.
-//!
-//! ## The index space (VERIFIED, the shipped `Blizzard_MacroUI`)
-//!
-//! `MAX_MACROS = 18` per tab; `MacroFrame.macroBase` is `0` for the account tab and `18` for the
-//! character tab, and every binding takes `macroBase + i`. So **1..=18 are the account macros and
-//! 19..=36 the character macros**, each list dense from its base — `MacroFrame_Update` draws
-//! `i <= numMacros` and disables the rest, so a gap is not representable. [`MacroIndex`] is that
-//! split, made once at the boundary.
-//!
-//! ## What the engine does NOT know
-//!
-//! A macro's **bound spell** — the spell whose cooldown/usability/range a macro action-bar slot
-//! reports (byte-verified: `0x4e5a50`'s macro arm returns `[rec+0x564]`, wow-re
-//! `action-spell-icon-apis.md` §2) — is the app's derivation, because resolving a name to a spell
-//! id needs the catalog and the player's book. The engine stores the body; `benilla::ui_macro`
-//! parses it. Same split as everywhere else in this crate: data and layout here, game knowledge
-//! there.
+//! Indices 1..=18 are the account macros and 19..=36 the character macros, each list dense from
+//! its base (`MacroFrame.macroBase`). A macro's bound spell (`0x4e5a50`'s macro arm returns
+//! `[rec+0x564]`) is the app's to derive: it needs the spell catalog and the player's book.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::cursor::{queue_cursor_update, CursorMacro, CursorPayload};
 use super::Model;
 
-/// Macros per tab — the shipped `Blizzard_MacroUI.lua`'s own `MAX_MACROS = 18`, and the account
-/// tab's size *and* the character tab's base (`MacroFrame_SetCharacterMacros` sets
-/// `macroBase = MAX_MACROS`).
+/// Macros per tab (`Blizzard_MacroUI.lua:1`), and so the character tab's base.
 pub const MAX_MACROS: usize = 18;
 
-/// The macro **name** length cap — `MacroPopupEditBox`'s `letters="16"` and its label
-/// `MACRO_POPUP_TEXT = "Enter Macro Name (Max 16 Characters):"`. Enforced here as well as in the
-/// box, because `CreateMacro`/`EditMacro` are callable from any script.
+/// The name cap, `MacroPopupEditBox`'s `letters="16"`.
 pub const MAX_MACRO_NAME: usize = 16;
 
-/// The macro **body** length cap — `MacroFrameText`'s `letters="255"` and its counter
-/// `MACROFRAME_CHAR_LIMIT = "%d/255 Characters Used"`.
+/// The body cap, `MacroFrameText`'s `letters="255"`.
 pub const MAX_MACRO_BODY: usize = 255;
 
 /// One macro, as `GetMacroInfo` reports it.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MacroView {
-    /// The player's name for it (≤ [`MAX_MACRO_NAME`] characters).
     pub name: String,
-    /// The chosen icon's **texture path** (`Interface\Icons\Ability_Ambush`). Stored resolved
-    /// rather than as an index into the chooser list: the reference's own save format writes the
-    /// icon by NAME (`MACRO %d "%s" %s`, byte-verified at `0x44cb60`), so a name is what survives
-    /// a restart — an index would silently re-point if the list ever changed.
+    /// The icon's texture path, kept by name because the reference saves the icon by name
+    /// (`MACRO %d "%s" %s`, `0x44cb60`).
     pub texture: Option<String>,
-    /// The macro body: the lines run when the macro is used, `\n`-separated, ≤ [`MAX_MACRO_BODY`].
+    /// The macro's lines, `\n`-separated.
     pub body: String,
-    /// `GetMacroInfo`'s fourth return (`isLocal`) and `CreateMacro`/`EditMacro`'s `local`
-    /// argument. The 1.12 client keeps a second file for these (`macros-local.txt` beside
-    /// `macros-cache.txt`, both byte-verified strings at `0x45de74`/`0x45de88`); the shipped macro
-    /// UI never passes the flag, so it is carried faithfully and is otherwise inert.
+    /// `isLocal` and the `local` argument, carried but not saved here. The 1.12 client saves these
+    /// to `macros-local.txt` beside `macros-cache.txt` (`0x45de74`, `0x45de88`); the stock UI never
+    /// sets it.
     pub local_only: bool,
 }
 
-/// The whole macro table: the two dense lists behind the frame's two tabs (module docs).
+/// The macro table: the account and character lists.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MacroState {
     /// Indices 1..=18.
@@ -76,19 +45,16 @@ pub struct MacroState {
     pub character: Vec<MacroView>,
 }
 
-/// A 1-based Lua macro index resolved into `(which list, position in it)` — the one place the
-/// 1..36 space is split, so no binding re-derives the base.
+/// A 1-based Lua macro index split into its list and 0-based position.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) struct MacroIndex {
-    /// True for 19..=36 (the character tab).
+    /// True for 19..=36.
     per_character: bool,
-    /// 0-based position within that tab's list.
     pos: usize,
 }
 
 impl MacroIndex {
-    /// Split a 1-based Lua index; `None` outside 1..=36. Deliberately NOT range-checked against
-    /// the live lists — callers that need an occupied slot go through [`MacroState::get`].
+    /// `None` outside 1..=36; not checked against the lists, which [`MacroState::get`] does.
     fn split(index: usize) -> Option<Self> {
         let zero = index.checked_sub(1)?;
         match zero {
@@ -104,14 +70,13 @@ impl MacroIndex {
         }
     }
 
-    /// The 1-based Lua index this position occupies.
     fn lua_index(self) -> usize {
         self.pos + 1 + if self.per_character { MAX_MACROS } else { 0 }
     }
 }
 
 impl MacroState {
-    /// The macro at a 1-based Lua index, or `None` for an empty/out-of-range slot.
+    /// The macro at a 1-based Lua index.
     pub fn get(&self, index: usize) -> Option<&MacroView> {
         let at = MacroIndex::split(index)?;
         self.list(at.per_character).get(at.pos)
@@ -133,10 +98,7 @@ impl MacroState {
         }
     }
 
-    /// `GetMacroIndexByName`'s search — case-insensitive, account list first (the reference walks
-    /// the one flat 1..36 space, and the account half is its low end). `0` when nothing matches,
-    /// which is the reference's own miss value (a number, never nil — the shipped
-    /// `Usage: GetMacroIndexByName(name)` binding pushes a number).
+    /// `GetMacroIndexByName`: case-insensitive, account list first; 0 on a miss, as in 1.12.
     pub fn index_by_name(&self, name: &str) -> usize {
         for per_character in [false, true] {
             for (i, m) in self.list(per_character).iter().enumerate() {
@@ -153,16 +115,14 @@ impl MacroState {
     }
 }
 
-/// Clamp a player-supplied string to a character (not byte) cap — the EditBox's own
-/// `max_letters` rule, applied again at the API so a script cannot store what the box refuses.
+/// Clamp to a count of characters, not bytes, as the edit boxes do, so a script cannot store more.
 fn clamp_chars(s: &str, max: usize) -> String {
     s.chars().take(max).collect()
 }
 
 impl super::UiScript {
-    /// Seed the whole macro table, replacing whatever was there — the app's load path
-    /// (`benilla-config/macros/…`). Does **not** mark the table dirty: the app already has what it just
-    /// handed over, and a save triggered by its own load would be a write-back loop.
+    /// Seed the whole table from the app's load. It does not mark the table dirty, or the load
+    /// would trigger a save.
     pub fn set_macros(&mut self, state: MacroState) {
         let mut model = self.model_mut();
         model.macros = state;
@@ -170,43 +130,33 @@ impl super::UiScript {
         model.macros_generation += 1;
     }
 
-    /// Read the live macro table — the app's save path, taken when [`Self::take_macros_dirty`]
-    /// reports a change.
+    /// The live table, for the app's save.
     pub fn macros(&self) -> MacroState {
         self.model_mut().macros.clone()
     }
 
-    /// Did a script mutate the table since the last call (`CreateMacro`/`EditMacro`/`DeleteMacro`)?
-    /// The app persists on a `true` and fires `UPDATE_MACROS` — the reference's own event for
-    /// exactly this transition (byte-verified string at `0x452460`).
+    /// Whether a script changed the table since the last call; the app then saves it and fires
+    /// `UPDATE_MACROS` (`0x452460`).
     pub fn take_macros_dirty(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().macros_dirty)
     }
 
-    /// Push the icon-chooser list — the full texture paths `GetMacroIconInfo` serves, in the order
-    /// the popup's grid shows them. Built by the app off `SpellIcon.dbc` (`benilla::ui_macro`).
+    /// Push the icon chooser's texture paths in grid order, built by the app from `SpellIcon.dbc`.
     pub fn set_macro_icons(&mut self, icons: Vec<String>) {
         self.model_mut().macro_icons = icons;
     }
 
-    /// The macro table's **generation** — bumped by every seed and every mutation, so a per-frame
-    /// consumer can gate an expensive re-resolve on a `u64` compare instead of cloning the table
-    /// to diff it. The action bar's identity feed reads it as a third input beside its `dirty`
-    /// flag and the item-template epoch (the same shape decision 0660 gave that one): a macro's
-    /// icon changes when the macro is edited, which touches neither of the other two.
-    ///
-    /// Distinct from [`Self::take_macros_dirty`] on purpose — that one is a *drained* edge with
-    /// exactly one owner (the save), and a second consumer draining it would silently eat the
-    /// other's save.
+    /// Bumped by every seed and every change, so a per-frame reader such as the action bar compares
+    /// a `u64` instead of diffing the table. Not [`Self::take_macros_dirty`]: that drain has one
+    /// owner, the save, and a second reader would steal its edge.
     pub fn macros_generation(&self) -> u64 {
         self.model_mut().macros_generation
     }
 }
 
-/// `CreateMacro(name, iconIndex, body, local, perCharacter)` — the shipped binding's own argument
-/// list (byte-verified usage string at `0x44cb74`). Returns the new macro's 1-based index, or
-/// `None` on the two failures the client names in its own log lines (`0x44cbb4`/`0x44cbdc`):
-/// an empty name, and a full tab.
+/// `CreateMacro(name, iconIndex, body, local, perCharacter)` (usage string `0x44cb74`): the new
+/// 1-based index, or `None` on the two failures the client logs (`0x44cbb4`, `0x44cbdc`), an empty
+/// name and a full tab.
 fn create_macro(
     model: &mut Model,
     name: &str,
@@ -239,11 +189,9 @@ fn create_macro(
     Some(MacroIndex { per_character, pos }.lua_index())
 }
 
-/// `EditMacro(index, name, icon, body, local)` — every argument is optional past the index, and an
-/// omitted one leaves that field alone. That is load-bearing, not defensive: the shipped UI calls
-/// it **twice with disjoint halves** — `EditMacro(sel, name, icon)` from the rename popup and
-/// `EditMacro(sel, nil, nil, text)` from `MacroFrame_SaveMacro` — so a nil that overwrote would
-/// blank the body every time the name changed.
+/// `EditMacro(index, name, icon, body, local)`: an omitted argument leaves its field alone, since
+/// the stock UI calls it with disjoint halves, `(sel, name, icon)` from the rename popup and
+/// `(sel, nil, nil, text)` from `MacroFrame_SaveMacro`.
 fn edit_macro(
     model: &mut Model,
     index: usize,
@@ -256,8 +204,7 @@ fn edit_macro(
     let entry = model.macros.list_mut(at.per_character).get_mut(at.pos)?;
     if let Some(name) = name {
         let name = clamp_chars(name.trim(), MAX_MACRO_NAME);
-        // An explicit blank is refused rather than stored: `MacroPopupOkayButton_Update` already
-        // keeps OKAY disabled on an empty box, so reaching here means a script did it.
+        // A blank name is ignored; the stock popup cannot send one (`MacroPopupOkayButton_Update`).
         if !name.is_empty() {
             entry.name = name;
         }
@@ -276,11 +223,8 @@ fn edit_macro(
     Some(index)
 }
 
-/// `DeleteMacro(index)` — removes the slot and **closes the gap**, which is why every action-bar
-/// slot holding a higher macro index would now point at the wrong macro. The reference has the
-/// same property (its own list is dense, and `MacroFrame_Update` draws it densely); the app's
-/// action feed re-resolves against the shifted table, so a bar button follows the slot, not the
-/// macro. Named in decision 0983 as faithful-and-surprising rather than fixed.
+/// `DeleteMacro(index)` closes the gap, as the reference's dense list does, so an action-bar
+/// button holding a higher index then shows the next macro.
 fn delete_macro(model: &mut Model, index: usize) -> bool {
     let Some(at) = MacroIndex::split(index) else {
         return false;
@@ -295,14 +239,9 @@ fn delete_macro(model: &mut Model, index: usize) -> bool {
     true
 }
 
-/// `PickupMacro(index)` — the macro button's `OnDragStart` and the selected-macro button's
-/// `OnClick` (both in the shipped `Blizzard_MacroUI.xml`). Loads the cursor with the macro
-/// payload (the client's mode **8**, `[0xb4e2fc]` — wow-re `cursor-dragdrop-payload.md` §1), which
-/// `PlaceAction` then packs as `macroId | 0x40000000` (`action-item-slot.md`'s payload table).
-///
-/// Refuses while the cursor already holds something, matching `PickupSpell`'s precedent: a macro
-/// button is a SOURCE, never a fit-checked drop target, so silently discarding the held payload
-/// would be worse than doing nothing.
+/// `PickupMacro(index)`: the macro payload (cursor mode 8, `[0xb4e2fc]`), which `PlaceAction`
+/// (`0x4e62e0`) packs as `macroId | 0x40000000`. Refused while the cursor holds anything; the
+/// reference's setter (`0x494f80`) clears the cursor first instead.
 fn pickup_macro(model: &mut Model, index: usize) -> bool {
     if model.cursor.is_some() {
         return false;
@@ -319,7 +258,6 @@ fn pickup_macro(model: &mut Model, index: usize) -> bool {
     true
 }
 
-/// Coerce a Lua argument that the shipped UI passes as either a real value or `nil`/`false`.
 fn opt_string(v: Option<&Value>) -> Option<String> {
     match v {
         Some(Value::String(s)) => Some(s.to_string_lossy()),
@@ -327,10 +265,9 @@ fn opt_string(v: Option<&Value>) -> Option<String> {
     }
 }
 
-/// The reference's own truthiness for the `local`/`perCharacter` flags: `MacroPopupOkayButton_OnClick`
-/// passes the Lua boolean `(MacroFrame.macroBase > 0)`, and the shipped `local` argument is always
-/// `nil`. `0` reads falsy here (the numeric convention `UseAction`'s `checkCursor` established —
-/// `super::action::truthy_nonzero`'s law, shared so the two cannot drift).
+/// The `local` and `perCharacter` flags: `nil`, `false` and `0` are false, as in `UseAction`. The
+/// reference reads them with `GetBoolOrDefault` (`0x6f1c10`), which also takes `"0"` and any
+/// number that truncates to 0 as false; the stock popup passes a Lua boolean and never `local`.
 fn flag(v: Option<&Value>) -> bool {
     v.is_some_and(super::action::truthy_nonzero)
 }
@@ -339,7 +276,6 @@ fn flag(v: Option<&Value>) -> bool {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumMacros() -> numAccountMacros, numCharacterMacros.
     g.set(
         "GetNumMacros",
         lua.create_function(|lua, ()| {
@@ -351,8 +287,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMacroInfo(index) -> name, texture, body, isLocal. An empty/out-of-range slot answers a
-    // single nil (the out-of-range shape every list binding in this crate uses).
     g.set(
         "GetMacroInfo",
         lua.create_function(|lua, index: usize| {
@@ -377,7 +311,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMacroIndexByName(name) -> index (0 = no match).
     g.set(
         "GetMacroIndexByName",
         lua.create_function(|lua, name: String| {
@@ -386,7 +319,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumMacroIcons() -> the chooser list's length.
     g.set(
         "GetNumMacroIcons",
         lua.create_function(|lua, ()| {
@@ -395,7 +327,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMacroIconInfo(index) -> texture path; 1-based, out of range -> nil.
     g.set(
         "GetMacroIconInfo",
         lua.create_function(|lua, index: usize| {
@@ -413,10 +344,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CreateMacro(name, iconIndex, body, local, perCharacter) -> index | nil.
-    // `iconIndex` is an index into the chooser list (the shipped popup passes
-    // `MacroPopupFrame.selectedIcon`), resolved to a path HERE so the stored macro keeps a name
-    // that survives a restart.
+    // CreateMacro stores `iconIndex`, an index into the chooser list, as its path.
     g.set(
         "CreateMacro",
         lua.create_function(|lua, args: MultiValue| {
@@ -435,8 +363,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // EditMacro(index, name, icon, body, local) -> index | nil. Absent arguments leave their
-    // field alone (see `edit_macro` — the shipped UI relies on it).
     g.set(
         "EditMacro",
         lua.create_function(|lua, args: MultiValue| {
@@ -445,8 +371,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 return Ok(Value::Nil);
             };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // An icon argument that is present-and-resolvable replaces; an absent/nil one leaves
-            // the icon alone. (`MacroFrame_SaveMacro` passes nil here on every body-only save.)
+            // A nil icon leaves the icon alone: `MacroFrame_SaveMacro` passes nil on every save.
             let texture = match a.get(2) {
                 None | Some(Value::Nil) => None,
                 other => Some(icon_path(&model, other)),
@@ -485,8 +410,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Resolve a chooser-list **index** argument to a texture path. A string is taken as a path
-/// already (nothing shipped does that, but a script may, and the store holds paths anyway).
+/// Resolve a chooser-list index to its texture path; a string is taken as a path already.
 fn icon_path(model: &Model, v: Option<&Value>) -> Option<String> {
     match v {
         Some(Value::String(s)) => Some(s.to_string_lossy()),
@@ -514,8 +438,6 @@ mod tests {
         s
     }
 
-    /// The whole create → read → edit → delete round trip through the reference's own signatures,
-    /// including the index space's account/character split.
     #[test]
     fn the_macro_api_round_trip_over_the_two_tabs() {
         let s = seeded();
@@ -525,12 +447,10 @@ mod tests {
             (0, 0)
         );
 
-        // Account tab: perCharacter falsy -> index 1.
         let i = s
             .eval::<i64>(r#"return CreateMacro("Ambush", 1, "/cast Ambush", nil, nil)"#)
             .unwrap();
         assert_eq!(i, 1);
-        // Character tab: perCharacter truthy -> the 19 base.
         let j = s
             .eval::<i64>(r#"return CreateMacro("Bolt", 3, "/cast Fireball", nil, true)"#)
             .unwrap();
@@ -541,7 +461,6 @@ mod tests {
             (1, 1)
         );
 
-        // GetMacroInfo's four returns, with the icon index resolved to a path at create time.
         let (name, tex, body, is_local) = s
             .eval::<(String, String, String, Value)>(
                 "local n, t, b, l = GetMacroInfo(1) return n, t, b, l",
@@ -553,7 +472,6 @@ mod tests {
         );
         assert_eq!(is_local, Value::Nil);
 
-        // By-name is case-insensitive and searches the account list first; a miss is 0.
         assert_eq!(
             s.eval::<i64>(r#"return GetMacroIndexByName("ambush")"#)
                 .unwrap(),
@@ -570,7 +488,7 @@ mod tests {
             0
         );
 
-        // Delete closes the gap: the character macro keeps its own base.
+        // The character macro keeps its own base after the delete.
         assert!(s.eval::<bool>("return DeleteMacro(1)").unwrap());
         assert_eq!(
             s.eval::<(i64, i64)>("local a, c = GetNumMacros() return a, c")
@@ -581,14 +499,12 @@ mod tests {
         assert_eq!(s.eval::<String>("return GetMacroInfo(19)").unwrap(), "Bolt");
     }
 
-    /// `EditMacro`'s partial-update law — the shipped UI's two disjoint calls. A rename must not
-    /// blank the body, and a body save must not blank the name or icon.
     #[test]
     fn edit_macro_leaves_omitted_fields_alone() {
         let s = seeded();
         s.run(r#"CreateMacro("Old", 1, "/cast Ambush")"#).unwrap();
 
-        // MacroPopupOkayButton_OnClick's edit form: name + icon, no body.
+        // MacroPopupOkayButton_OnClick's form: name and icon.
         s.run(r#"EditMacro(1, "New", 2)"#).unwrap();
         let (name, tex, body) = s
             .eval::<(String, String, String)>("local n, t, b = GetMacroInfo(1) return n, t, b")
@@ -597,7 +513,7 @@ mod tests {
         assert_eq!(tex, "Interface\\Icons\\Ability_BackStab");
         assert_eq!(body, "/cast Ambush", "the body survives a rename");
 
-        // MacroFrame_SaveMacro's form: body only, name and icon nil.
+        // MacroFrame_SaveMacro's form: the body alone.
         s.run(r#"EditMacro(1, nil, nil, "/cast Backstab")"#)
             .unwrap();
         let (name, tex, body) = s
@@ -614,7 +530,6 @@ mod tests {
         );
     }
 
-    /// The two refusals the client names in its own log lines, and the caps the edit boxes carry.
     #[test]
     fn create_refuses_a_blank_name_and_a_full_tab_and_clamps_the_caps() {
         let s = seeded();
@@ -636,14 +551,13 @@ mod tests {
                 .unwrap(),
             "the 19th account macro is refused"
         );
-        // …and the character tab is a separate 18.
+        // The character tab is a separate 18.
         assert_eq!(
             s.eval::<i64>(r#"return CreateMacro("c", 1, "", nil, 1)"#)
                 .unwrap(),
             19
         );
 
-        // The caps are the shipped boxes' own letters= values, enforced at the API too.
         let s = seeded();
         s.run(&format!(
             r#"CreateMacro("{}", 1, "{}")"#,
@@ -658,8 +572,6 @@ mod tests {
         assert_eq!(body.chars().count(), MAX_MACRO_BODY);
     }
 
-    /// The dirty flag is the app's save trigger: every mutation raises it, a seed never does, and
-    /// the drain clears it.
     #[test]
     fn mutations_raise_the_dirty_flag_and_a_seed_does_not() {
         let mut s = seeded();
@@ -675,11 +587,9 @@ mod tests {
         s.run("DeleteMacro(1)").unwrap();
         assert!(s.take_macros_dirty());
 
-        // A no-op delete changes nothing and raises nothing.
         s.run("DeleteMacro(7)").unwrap();
         assert!(!s.take_macros_dirty());
 
-        // The app's own seed must not trigger a save (a write-back loop).
         s.set_macros(MacroState {
             account: vec![MacroView {
                 name: "loaded".into(),
@@ -691,7 +601,6 @@ mod tests {
         assert_eq!(s.macros().account.len(), 1);
     }
 
-    /// `PickupMacro` loads the cursor with the macro payload, and refuses while holding.
     #[test]
     fn pickup_macro_loads_the_cursor_and_refuses_while_holding() {
         use crate::script::cursor::CursorPayload;
@@ -712,7 +621,6 @@ mod tests {
                 texture: Some("Interface\\Icons\\Ability_Ambush".into()),
             }))
         );
-        // GetCursorInfo's Era shape for a macro: the kind word + the index.
         assert_eq!(
             s.eval::<(String, i64)>("local k, i = GetCursorInfo() return k, i")
                 .unwrap(),
@@ -724,8 +632,6 @@ mod tests {
         );
     }
 
-    /// The chooser list is the app's, served 1-based, and an out-of-range index is nil rather
-    /// than an error (`MacroPopupFrame_Update` indexes past the end on the last row every time).
     #[test]
     fn the_icon_chooser_list_is_one_based_with_a_nil_tail() {
         let s = seeded();
diff --git a/crates/benilla-ui/src/script/mail.rs b/crates/benilla-ui/src/script/mail.rs
index 2de6544b..93d57078 100644
--- a/crates/benilla-ui/src/script/mail.rs
+++ b/crates/benilla-ui/src/script/mail.rs
@@ -1,32 +1,6 @@
-//! The mail bindings (decision 0544 P1/P2) — the Era-shaped mailbox surface, the same two-way seam
-//! as [`super::merchant`]/[`super::loot`]: the app pushes a **mail snapshot**
-//! ([`UiScript::set_mail`] — the inbox rows already resolved from the wire to
-//! name/icon/sender/body by the app's item-template + name caches) and the Lua
-//! `CheckInbox`/`TakeInboxItem`/`SendMail`/… calls queue outbound **intents** the app drains. The
-//! engine holds no mail knowledge — a row is a header (sender/subject/money/COD/expiry/flags), an
-//! optional enclosed item (id/name/icon/quality), an ask-once letter body, and a stationery
-//! basename.
-//!
-//! ## The 5875 API shape (VERIFIED against the extracted `MailFrame.lua`)
-//!
-//! `index` is **1-based** everywhere; an out-of-range index answers `nil`/`0`. The inbox getters:
-//! `GetInboxNumItems()`, `GetInboxHeaderInfo(index)` → the reference 13-tuple
-//! `packageIcon, stationeryIcon, sender, subject, money, CODAmount, daysLeft, hasItem(count|nil),
-//! wasRead, wasReturned, textCreated, canReply, isGM` (MailFrame.lua l.105/265/279),
-//! `GetInboxText(index)` → `body, stationeryTexture, isTakeable, isInvoice` (l.292 — a body cache
-//! miss queues the `CMSG_ITEM_TEXT_QUERY` fetch and returns `""`), `GetInboxItem(index)` →
-//! `name, texture, count, quality, canUse` (l.379), `InboxItemCanDelete(index)` → 1/nil (the
-//! delete-vs-return law, l.417/450). `HasNewMail()` reads the app-pushed login-scoped flag
-//! ([`UiScript::set_has_new_mail`], decision 0544 P3) — `nil` (false) until the app's first
-//! `MSG_QUERY_NEXT_MAIL_TIME` answer lands.
-//!
-//! The send tab: `GetSendMailItem()` → `name, texture, stackCount, quality` off the attached cursor
-//! item (l.511), `GetSendMailPrice()` → the flat **30c** postage (vmangos's fee), `SendMail(target,
-//! subject, body)` fires the send, `SetSendMailMoney`/`SetSendMailCOD(copper)` push the money/COD
-//! amounts the app reads at send time, `ClickSendMailItemButton()` attaches (or detaches) the
-//! cursor's held bag item as the send attachment (l.719). Intents `CheckInbox`, `TakeInboxItem`,
-//! `TakeInboxMoney`, `DeleteInboxItem`, `ReturnInboxItem`, `CloseMail` are 1-based row indices /
-//! flags the app maps to the wire.
+//! The mail bindings. The app pushes the open mailbox's inbox, already resolved from the wire
+//! (`UiScript::set_mail`), and the Lua verbs queue intents the app drains and sends. Indices are
+//! 1-based, as `MailFrame.lua` uses them.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -34,143 +8,107 @@ use super::binding_abi::flag;
 use super::cursor::{self, CursorPayload};
 use super::Model;
 
-/// One inbox row, resolved by the app from a wire `MailListEntry` (decision 0544). Plain data — its
-/// 1-based order in the window is its position in [`MailState::inbox`].
+/// One inbox row, resolved by the app from a wire `MailListEntry`; its 1-based index is its
+/// position in [`MailState::inbox`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MailInboxRow {
-    /// The enclosed item's icon (`GetInboxHeaderInfo`'s `packageIcon`); `None` when the mail carries
-    /// no item, or while its template answer is in flight.
+    /// `packageIcon`, the enclosed item's icon; `None` with no item or while its template loads.
     pub package_icon: Option<String>,
-    /// The letter icon (`stationeryIcon`) — the app derives it from the stationery id/GM flag; the
-    /// row shows this when there's no package (or it's GM mail).
     pub stationery_icon: Option<String>,
-    /// The sender name (`sender`), resolved through the name cache; `None` while in flight or for a
-    /// non-player sender (the Lua shows `UNKNOWN`).
+    /// `sender`, from the name cache; `None` while in flight or for a non-player sender.
     pub sender: Option<String>,
     pub subject: String,
     pub money: u32,
     pub cod: u32,
-    /// Days remaining before the mail is deleted/returned (`daysLeft`, the wire `expire_days`).
     pub days_left: f32,
-    /// The enclosed item's stack count (`GetInboxHeaderInfo`'s `hasItem` returns this, or `nil` when
-    /// `0`). `0` = no item.
+    /// The enclosed stack's count, answered as `hasItem`; 0 (nil) is no item.
     pub item_count: u32,
     /// `checked & READ(0x1)`.
     pub was_read: bool,
     /// `checked & RETURNED(0x2)`.
     pub was_returned: bool,
-    /// `checked & COPIED(0x4)` — the letter body was materialized as a text item (`textCreated`).
+    /// `checked & COPIED(0x4)`: the letter was copied to an item (`textCreated`).
     pub text_created: bool,
-    /// `sender_guid.is_some() && !was_returned` — the Reply button gate (l.281).
+    /// `sender_guid.is_some() && !was_returned`, the Reply button's gate (`MailFrame.lua:281`).
     pub can_reply: bool,
-    /// `stationery == 61` — a GM mail (l.108).
+    /// `stationery == 61`: a GM mail (vmangos `MAIL_STATIONERY_GM`, `Mail.h:85`).
     pub is_gm: bool,
-    /// The letter body (`GetInboxText`'s first return); `None` = not fetched yet (the getter returns
-    /// `""` and queues the ask-once `CMSG_ITEM_TEXT_QUERY` when [`Self::has_body`]).
+    /// The letter body; `None` until fetched, while `GetInboxText` answers `""`.
     pub body: Option<String>,
-    /// The stationery texture basename (`GetInboxText`'s second return) — the Lua wraps it as
-    /// `Interface\Stationery\<basename>1`/`2` for the open-letter backdrop.
     pub stationery_texture: String,
-    /// `GetInboxText`'s fourth return. **Narrower than "an auction mail"**: the reference answers
-    /// `1` iff the record carries the three fields its subject parser persisted (`[rec+0x250] != 0`,
-    /// `0x4af2eb`), and the parser persists them *only* for result code 1 (won) or 2 (sold). An
-    /// outbid or expiry notice is an auction mail that is **not** an invoice (decision 1527).
+    /// `isInvoice`: only an auction won (result 1) or sold (2), not an outbid or expiry notice
+    /// (`0x4af2eb`).
     pub is_invoice: bool,
-    /// The auction invoice this mail carries, once it can be answered — `GetInboxInvoiceInfo`'s
-    /// seven values. `None` is the reference's **miss tail**, and it covers four different states
-    /// that all read the same from Lua: not an auction mail at all; an auction mail whose result
-    /// code is not won(1)/sold(2) (an outbid or expiry notice carries no body and no invoice); the
-    /// body not fetched yet; or the counterparty's name still in flight.
+    /// `GetInboxInvoiceInfo`'s answer; `None`, the reference's miss, also while the body or the
+    /// counterparty's name is in flight.
     pub invoice: Option<MailInvoice>,
-    /// The mail carries a fetchable letter body (`item_text_id != 0`) — gates the body ask.
+    /// `item_text_id != 0`: the mail has a letter body to fetch.
     pub has_body: bool,
-    /// The enclosed item's template entry (`0` = none) — the shared item-tooltip store's key
-    /// (`GameTooltip:SetInboxItem`) and `GetInboxItem`'s identity.
+    /// The enclosed item's template entry, 0 for none; the key `SetInboxItem`'s tooltip reads.
     pub item_id: u32,
-    /// The enclosed item's **random-suffix roll** (`SMSG_MAIL_LIST`'s per-item `randomPropId`) —
-    /// what the hover resolves its enchant lines from, and the id whose suffix
-    /// [`Self::item_name`] already carries. `0` = unrolled. The reference's `SetInboxItem` writes
-    /// exactly this into the tooltip's `+0x424` (decision 1547).
+    /// The enclosed item's random-suffix id (the wire `randomPropId`), 0 for none, which the
+    /// reference's `SetInboxItem` hands the tooltip (`+0x424`); `item_name` carries its suffix.
     pub item_random_property_id: u32,
-    /// The enclosed item's name (`GetInboxItem`'s first return); `None` while the template is in
-    /// flight.
+    /// The enclosed item's name; `None` while its template is in flight.
     pub item_name: Option<String>,
-    /// The enclosed item's icon; `None` while in flight.
     pub item_texture: Option<String>,
-    /// The enclosed item's quality (0..6); `None` while in flight.
     pub item_quality: Option<u32>,
-    /// `InboxItemCanDelete` — the delete-vs-return law (`!can_reply`: a not-yet-returned mail from a
-    /// player is returnable, everything else is deletable — l.417/450).
+    /// `InboxItemCanDelete`: `!can_reply`, as a player's unreturned mail is returned instead
+    /// (`MailFrame.lua:417`, `:450`).
     pub can_delete: bool,
 }
 
-/// One auction mail's invoice — what `GetInboxInvoiceInfo(index)` hands back, already parsed.
-///
-/// The invoice is **TEXT**, not wire data: the auction house writes the numbers into the mail's
-/// subject and body and the client `sscanf`s them back out (wow-re `ui/scratch/auction-house.md`
-/// §11.1a). The app owns that parse; this is its result.
+/// One auction invoice, `GetInboxInvoiceInfo`'s answer, parsed by the app from the mail's subject
+/// and body text as the reference `sscanf`s them (`0x4af360`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct MailInvoice {
-    /// `true` → the literal token `"seller"` (your auction sold), `false` → `"buyer"` (you won).
-    /// A bare ASCII token in the reference too, not a GlobalString — the Lua compares it as one.
+    /// `"seller"` (your auction sold) or `"buyer"` (you won), literal tokens, not global strings.
     pub seller: bool,
-    /// The auctioned item's name, composed from the subject's item entry.
     pub item_name: String,
     /// The counterparty: who bought it (seller invoice) or who sold it (buyer invoice).
     pub player_name: String,
-    /// The winning bid. `bid == buyout` is how the window knows it was a buyout rather than a bid.
+    /// The winning bid; the window reads `bid == buyout` as a buyout (`MailFrame.lua:307`).
     pub bid: u32,
     pub buyout: u32,
-    /// Seller invoices only (`0` on a buyer invoice — the body carries three fields, not five).
+    /// Seller invoices only; 0 on a buyer's, whose body carries three fields, not five.
     pub deposit: u32,
     /// The auction house's cut, seller invoices only.
     pub consignment: u32,
 }
 
-/// The open mailbox's inbox snapshot. Pushed whole by the app; `None` means no mailbox is open (the
-/// window is closed).
+/// The open mailbox's inbox, pushed whole by the app; `set_mail(None)` means no mailbox is open.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MailState {
     pub inbox: Vec<MailInboxRow>,
 }
 
-/// One usable stationery, as the send tab's picker lists it (`GetNumStationeries` /
-/// `GetStationeryInfo`, 1970) — the app computes the usable set off `Stationery.dbc` and the
-/// player's bags, sorted by price, and pushes it whole ([`super::UiScript::set_mail_stationeries`]).
+/// One usable stationery in the send tab's picker; the app builds the list from `Stationery.dbc`
+/// and the bags, sorted by price.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct StationeryView {
-    /// The `Stationery.dbc` row id — what `SelectStationery` stores and `CMSG_SEND_MAIL` carries.
+    /// The `Stationery.dbc` row id, which `SelectStationery` stores and `CMSG_SEND_MAIL` carries.
     pub id: u32,
-    /// The stationery item's name (`GetStationeryInfo`'s first return).
     pub name: String,
-    /// The item's icon as a FULL path (`Interface\Icons\…`) — `GetStationeryInfo`'s second
-    /// return is used raw by `SetTexture` (MailFrame.lua l.671), unlike the bare basename below.
+    /// The item's icon as a full `Interface\Icons\` path, which `MailFrame.lua:671` sets as is.
     pub icon: String,
-    /// The item's BuyPrice in copper, or `None` when the player already carries the item
-    /// (`GetStationeryInfo`'s third return is nil then).
+    /// The item's BuyPrice in copper; `None` (nil) when the player carries one.
     pub cost: Option<u32>,
-    /// The bare texture basename (`GetSelectedStationeryTexture`), wrapped by the Lua as
-    /// `STATIONERY_PATH..texture.."1"/"2"`.
+    /// The bare texture basename that `GetSelectedStationeryTexture` answers.
     pub texture: String,
 }
 
-/// A drained `SendMail` intent — the app resolves the attachment `(bag, slot)` to an item guid and
-/// builds `CMSG_SEND_MAIL` from this (decision 0544 P2).
+/// A drained `SendMail` intent, which the app turns into `CMSG_SEND_MAIL`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MailSendRequest {
     pub target: String,
     pub subject: String,
     pub body: String,
-    /// The selected `Stationery.dbc` id — `CMSG_SEND_MAIL`'s sixth field (never 0 here: a send with
-    /// no selection aborts before it is queued, `0x4ae8dd`).
+    /// The selected `Stationery.dbc` id; never 0, as a send with none aborts (`0x4ae8dd`).
     pub stationery: u32,
-    /// Money to enclose (copper) — `SetSendMailMoney`'s last value.
     pub money: u32,
-    /// COD amount (copper) — `SetSendMailCOD`'s last value; `0` when not a COD send.
     pub cod: u32,
-    /// The attached bag item's `(live-API bag, 1-based slot)`; `None` = no attachment. The app
-    /// resolves it to the wire's `u64 itemGuid` at send time (the reference re-reads the bag slot
-    /// when the send fires, so the resolve is lazy).
+    /// The attached item's `(bag, 1-based slot)`; the app resolves its guid when the send fires,
+    /// as the reference re-reads the slot then.
     pub item: Option<(i64, u32)>,
 }
 
@@ -180,14 +118,12 @@ impl super::UiScript {
         self.model_mut().mail = state;
     }
 
-    /// Whether `CheckInbox` was called since the last drain (and clear the flag) — the app maps it to
-    /// a fresh `CMSG_GET_MAIL_LIST`.
+    /// Take the `CheckInbox` flag; the app answers it with `CMSG_GET_MAIL_LIST`.
     pub fn take_mail_check_inbox(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().mail_check_inbox)
     }
 
-    /// Drain the 1-based indices of mails **opened** (`GetInboxText` was called on them) since the
-    /// last drain — the app marks each read and fetches its body ask-once.
+    /// Drain the 1-based indices `GetInboxText` opened; the app marks each read, fetches its body.
     pub fn take_mail_opens(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().mail_opens)
     }
@@ -212,22 +148,18 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().mail_returns)
     }
 
-    /// Drain the 1-based `TakeInboxTextItem` row picks — the letter button's "permanent copy"
-    /// verb; the app maps each to `CMSG_MAIL_CREATE_TEXT_ITEM`.
+    /// Drain the 1-based `TakeInboxTextItem` row picks, each a `CMSG_MAIL_CREATE_TEXT_ITEM`.
     pub fn take_mail_take_texts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().mail_take_texts)
     }
 
-    /// Whether `CloseMail` was called since the last drain (and clear the flag). vanilla's
-    /// client-side close sends no packet — the app clears its local mail session.
+    /// Take the `CloseMail` flag; 1.12 has no close opcode, so the app only ends its mail session.
     pub fn take_mail_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().mail_close)
     }
 
-    /// Drain the `SendMail` intent, if one was queued since the last drain — folds in the last
-    /// `SetSendMailMoney`/`SetSendMailCOD` amounts and the attached item's `(bag, slot)`. The
-    /// attachment is left in place (a failed send keeps it; [`Self::reset_compose_tab`] drops it
-    /// on success).
+    /// Drain the `SendMail` intent with the current money, COD and attachment. The attachment
+    /// stays until [`Self::reset_compose_tab`], so a failed send keeps it.
     pub fn take_mail_send(&mut self) -> Option<MailSendRequest> {
         let mut model = self.model_mut();
         let (target, subject, body) = model.mail_send.take()?;
@@ -243,22 +175,10 @@ impl super::UiScript {
         })
     }
 
-    /// **`0x4acdc0(1)` — the client's compose-tab reset**, whole. Zeroes the send tab's attachment
-    /// (`0xb6ef90/94`), money (`0xb6efa4`) and COD (`0xb6efa8`) globals and then **tail-fires its
-    /// three events**, in this order: `SEND_MAIL_MONEY_CHANGED`, `SEND_MAIL_COD_CHANGED`,
-    /// `MAIL_SEND_SUCCESS` (`@0x4ace14/1e/28` — wow-re `system/ui/scratch/mail-interaction.md`
-    /// §1/§4).
-    ///
-    /// **The fire belongs to the reset, and that is the whole point of this shape.** Both call
-    /// sites used to fire `MAIL_SEND_SUCCESS` themselves, and the send-result one fired it
-    /// *before* clearing — so the stock `SendMailFrame_Reset` ran while `GetSendMailItem()` still
-    /// answered with the item that had just been sent, and its own `SendMailFrame_Update()` tail
-    /// put the item's name straight back into the subject box and its texture back on
-    /// `SendMailPackageButton`. Nothing re-ran the update after the clear landed, so a sent letter
-    /// left its subject and its icon sitting in the form (director's report, decision 2145).
-    ///
-    /// `MAIL_SEND_SUCCESS` is **overloaded** — it means "the compose form is now clean", not "a
-    /// mail was sent" (the anomaly wow-re verified twice: opening a mailbox fires it too).
+    /// The reference's compose-tab reset (`0x4acdc0`): clear the attachment, money and COD, then
+    /// fire `SEND_MAIL_MONEY_CHANGED`, `SEND_MAIL_COD_CHANGED` and `MAIL_SEND_SUCCESS` in that
+    /// order. The events must follow the clear, as `SendMailFrame_Reset` re-reads
+    /// `GetSendMailItem`. `MAIL_SEND_SUCCESS` means the form is clean: opening a mailbox fires it.
     pub fn reset_compose_tab(&mut self) {
         {
             let mut model = self.model_mut();
@@ -266,19 +186,15 @@ impl super::UiScript {
             model.mail_send_money = 0;
             model.mail_send_cod = 0;
         }
-        // Fired here, immediately, rather than queued on `pending_events`: this is a host-side
-        // edge (the mail system driving the VM), not a Lua binding queueing work for the next
-        // tick, and its order against the caller's own `MAIL_SHOW`/`MAIL_FAILED` is the law.
-        // Spelled out one call each — the three are a fixed sequence at three addresses, and the
-        // chain-file event census (`ui_script::reference_ui`) reads producers as literals.
+        // Fired now, not queued: the order against the caller's `MAIL_SHOW`/`MAIL_FAILED` matters.
+        // One literal call each, as the event census (`ui_script::reference_ui`) reads them.
         self.fire_event("SEND_MAIL_MONEY_CHANGED", Vec::new()); // 0x4ace14
         self.fire_event("SEND_MAIL_COD_CHANGED", Vec::new()); // 0x4ace1e
         self.fire_event("MAIL_SEND_SUCCESS", Vec::new()); // 0x4ace28
     }
 
-    /// Drop the attachment alone — `SendMail`'s attached-item-gone abort (`ERR_ITEM_NOT_FOUND`, no
-    /// packet, `MAIL_SEND_INFO_UPDATE` at `0x4ae98d`): the bag slot no longer holds the item the
-    /// send tab shows. The money and COD amounts stay, as the reference leaves them.
+    /// `SendMail`'s abort when the attached item left its slot (`ERR_ITEM_NOT_FOUND`, no packet,
+    /// `MAIL_SEND_INFO_UPDATE` at `0x4ae98d`): drop the attachment, keep the money and COD.
     pub fn drop_send_mail_item(&mut self) {
         let mut model = self.model_mut();
         if model.mail_send_item.take().is_some() {
@@ -288,28 +204,25 @@ impl super::UiScript {
         }
     }
 
-    /// Push the usable stationery list, in the picker's order (1970; see [`StationeryView`]).
+    /// Push the usable stationery list, in the picker's order.
     pub fn set_mail_stationeries(&mut self, list: Vec<StationeryView>) {
         self.model_mut().mail_stationeries = list;
     }
 
-    /// Clear the stationery selection — the client does it at `0x4ace07` on BOTH opening and
-    /// closing the mailbox, which is why the stock `SendMailFrame_Reset` re-selects row 1 on show.
+    /// Clear the stationery selection, as the reference does on mailbox open and close
+    /// (`0x4ace07`).
     pub fn clear_stationery(&mut self) {
         self.model_mut().mail_stationery = 0;
     }
 
-    /// Push `HasNewMail()`'s answer (decision 0544 P3) — login-scoped, independent of whether a
-    /// mailbox window is open. The app computes this off its `MSG_QUERY_NEXT_MAIL_TIME`/
-    /// `SMSG_RECEIVED_MAIL`-fed countdown and calls this on every value change, right before firing
-    /// `UPDATE_PENDING_MAIL` (the reference `MiniMapMailFrame`'s only listened event, Minimap.xml
-    /// l.278-289 — its `OnEvent` just re-reads `HasNewMail()` and shows/hides).
+    /// Push `HasNewMail()`'s answer, independent of any open mailbox. The app sets it before each
+    /// `UPDATE_PENDING_MAIL`, on which the minimap icon re-reads it (`Minimap.xml:278-289`).
     pub fn set_has_new_mail(&mut self, has: bool) {
         self.model_mut().has_new_mail = has;
     }
 }
 
-/// Fetch a cloned inbox row for a 1-based index, or `None` (out of range / no mailbox open).
+/// A clone of the inbox row at a 1-based index.
 fn row_at(model: &Model, index: usize) -> Option<MailInboxRow> {
     model
         .mail
@@ -322,7 +235,6 @@ fn row_at(model: &Model, index: usize) -> Option<MailInboxRow> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetInboxNumItems() → the number of inbox rows (0 when no mailbox is open).
     g.set(
         "GetInboxNumItems",
         lua.create_function(|lua, ()| {
@@ -331,8 +243,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInboxHeaderInfo(index) → the 13-tuple (see the module doc). An out-of-range index answers
-    // nil (the reference callers only read within GetInboxNumItems, but the null shape is faithful).
+    // GetInboxHeaderInfo(index): the 13 values `MailFrame.lua:105` reads; nil out of range.
     g.set(
         "GetInboxHeaderInfo",
         lua.create_function(|lua, index: usize| {
@@ -349,7 +260,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     None => Value::Nil,
                 })
             };
-            // packageIcon shows only for a non-GM mail that carries an item (MailFrame.lua l.108).
+            // packageIcon only for a non-GM mail with an item (`MailFrame.lua:108`).
             let package_icon = if r.item_id != 0 && !r.is_gm {
                 opt_str(&r.package_icon)?
             } else {
@@ -363,7 +274,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::Integer(i64::from(r.money)),
                 Value::Integer(i64::from(r.cod)),
                 Value::Number(f64::from(r.days_left)),
-                // hasItem: the stack count, or nil when there's no item.
                 if r.item_count > 0 {
                     Value::Integer(i64::from(r.item_count))
                 } else {
@@ -378,12 +288,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInboxText(index) → body, stationeryTexture, isTakeable, isInvoice (MailFrame.lua l.292).
-    // Opening a mail is the ask-once trigger: queue the open intent (the app marks it read + fetches
-    // the body when has_body). A cache miss returns "" until the body lands and a fresh snapshot
-    // arrives. isTakeable = the mail carries a fetchable body (`item_text_id != 0`) — with
-    // `not textCreated` it gates the letter button (the "permanent copy" verb, ref l.366; vmangos
-    // `HandleMailCreateTextItem` requires the same pair: an `itemTextId` and no COPIED bit).
+    // GetInboxText(index): body, stationeryTexture, isTakeable, isInvoice (`MailFrame.lua:292`);
+    // reading a mail queues its open. isTakeable with `not textCreated` gates the copy button
+    // (`MailFrame.lua:366`), the pair vmangos requires (`MailHandler.cpp:863`).
     g.set(
         "GetInboxText",
         lua.create_function(|lua, index: usize| {
@@ -391,7 +298,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let mut model = lua.app_data_mut::<Model>().expect("model app_data");
                 let row = row_at(&model, index);
                 if row.is_some() {
-                    // Ask-once dedup: don't re-queue an already-pending open this drain window.
+                    // Queued once per drain.
                     let i = index as u32;
                     if !model.mail_opens.contains(&i) {
                         model.mail_opens.push(i);
@@ -403,13 +310,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 return Ok(MultiValue::from_vec(vec![Value::Nil]));
             };
             Ok(MultiValue::from_vec(vec![
-                // **An invoice's body is `nil`, and that is an explicit carve-out in the reference,
-                // not an accident** (`0x4af1cf cmp [esi+0x4],2` / `je` → `lua_pushnil`, decision
-                // 1527). The auction house's raw `<guid>:<n>:<n>:…` bookkeeping really does sit in
-                // the shared text cache — `GetInboxInvoiceInfo` `sscanf`s exactly that string — but
-                // this binding refuses to hand it back. Two bindings, one cache, opposite purposes.
-                // It is what lets MailFrame lay the invoice pane over the letter page without the
-                // bookkeeping showing through above it.
+                // An invoice's body is nil (`0x4af1cf`): its text is the auction house's
+                // bookkeeping, which only `GetInboxInvoiceInfo` parses.
                 if r.is_invoice {
                     Value::Nil
                 } else {
@@ -422,13 +324,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInboxInvoiceInfo(index) → invoiceType, itemName, playerName, bid, buyout, deposit,
-    // consignment (MailFrame.lua l.302). **SEVEN values, always** — the reference's own
-    // `mov eax,7`, with the miss tail `nil, nil, nil, 0, 0, 0, 0`: three nils then four zeros
-    // (wow-re `ui/scratch/auction-house.md` §11.1a). MailFrame.lua guards on the third
-    // (`if playerName then`), so the shape of the miss is what keeps the invoice pane hidden —
-    // returning one bare nil instead would leave the four numeric destructures nil and the pane's
-    // arithmetic would run on them.
+    // GetInboxInvoiceInfo(index) (`MailFrame.lua:302`): always seven values (`0x4af5a1`), a miss
+    // being three nils and four zeros (`0x4af559`).
     g.set(
         "GetInboxInvoiceInfo",
         lua.create_function(|lua, index: usize| {
@@ -462,10 +359,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInboxItem(index) → name, texture, count, quality, canUse (MailFrame.lua l.379). name/quality
-    // are nil while the item-template answer is in flight; a mail with no item answers all-nil name.
-    // canUse is the shared item-usable gate over the enclosed item's template (merchant's isUsable
-    // path) — usable while the template is still in flight (the null-record skip).
+    // GetInboxItem(index): name, texture, count, quality, canUse (`MailFrame.lua:379`); canUse is
+    // the shared item-usable gate, true while the template is in flight.
     g.set(
         "GetInboxItem",
         lua.create_function(|lua, index: usize| {
@@ -477,11 +372,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     .is_none_or(|r| super::item_stats::item_usable_by_id(&model, r.item_id));
                 (row, usable)
             };
-            // **Five values on every path**, and the empty leg is `(nil, nil, 0, 0, nil)` —
-            // `GetInboxItem 0x4af5d0`, the sibling of the `GetSendMailItem` block above (wow-re
-            // `mail-interaction.md` §5.1; decision 2129). This answered ONE value, which a caller
-            // destructuring five reads as four nils — and the reference's own row
-            // (`(nil,nil,number,number,nil) | …`) has no one-value alternative at all.
+            // Five values on every path; with no item, `nil, nil, 0, 0, nil` (`0x4af5d0`).
             let Some(r) = row.filter(|r| r.item_id != 0) else {
                 return Ok(MultiValue::from_vec(vec![
                     Value::Nil,
@@ -499,7 +390,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some(t) => Value::String(lua.create_string(t)?),
                 None => Value::Nil,
             };
-            // A number on every path, like the send tab's.
+            // A number on every path, as in `GetSendMailItem`.
             let quality = Value::Integer(i64::from(r.item_quality.unwrap_or(0)));
             Ok(MultiValue::from_vec(vec![
                 name,
@@ -511,7 +402,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // InboxItemCanDelete(index) → 1/nil (MailFrame.lua l.417/450): the delete-vs-return law.
     g.set(
         "InboxItemCanDelete",
         lua.create_function(|lua, index: usize| {
@@ -520,8 +410,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasNewMail() → 1/nil off the app's login-scoped countdown flag (decision 0544 P3; see
-    // `UiScript::set_has_new_mail`'s doc for the wire behind it).
     g.set(
         "HasNewMail",
         lua.create_function(|lua, ()| {
@@ -530,7 +418,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CheckInbox() — flag the inbox-refresh intent (the app sends CMSG_GET_MAIL_LIST).
     g.set(
         "CheckInbox",
         lua.create_function(|lua, ()| {
@@ -541,7 +428,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The five 1-based row-pick intents (take item / take money / delete / return / copy letter).
     for (name, field) in [
         ("TakeInboxItem", 0u8),
         ("TakeInboxMoney", 1),
@@ -565,7 +451,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // CloseMail() — client-side close (no packet): flag it so the app clears its mail session.
     g.set(
         "CloseMail",
         lua.create_function(|lua, ()| {
@@ -576,23 +461,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SendMail(target, subject, body) — queue the send; the app folds in money/COD + the attachment.
     g.set(
         "SendMail",
         lua.create_function(|lua, (target, subject, body): (String, String, String)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // `SendMail 0x4ae800` (decision 1965): money and COD are exclusive AT SEND TIME — both
-            // set is a silent abort, no packet — and a COD with no attached item aborts the same
-            // way. 0 returns on every path, so Lua cannot tell.
+            // `SendMail` (`0x4ae800`) aborts silently, no packet and no return value, on money
+            // with COD or on COD with no attached item.
             if model.mail_send_money != 0 && model.mail_send_cod != 0 {
                 return Ok(());
             }
             if model.mail_send_cod != 0 && model.mail_send_item.is_none() {
                 return Ok(());
             }
-            // No stationery selected — `0x4ae8dd je`: the send silently aborts, no packet, 0
-            // returns (1970). The selection is cleared on mailbox open and close, and the stock
-            // `SendMailFrame_Reset` re-selects row 1, so a send from the stock tab always has one.
+            // The same silent abort with no stationery selected (`0x4ae8dd`).
             if model.mail_stationery == 0 {
                 return Ok(());
             }
@@ -601,11 +482,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSendMailMoney(copper) → 1 (the SEND_MONEY popup's OnAccept gates SendMail on the truthy
-    // return, StaticPopup.lua l.252). Stores the enclose-money amount the app reads at send time.
-    // SetSendMailMoney(copper) — `0x4ae0f0` → `0x4adbe0` (decision 1965): a non-number RAISES;
-    // more than the purse (unsigned) shows ERR_NOT_ENOUGH_MONEY and answers nil; else the store,
-    // SEND_MAIL_MONEY_CHANGED, and the number 1 — StaticPopup.lua l.257 branches on that value.
+    // SetSendMailMoney(copper) (`0x4ae0f0`): a non-number raises; more than the purse shows
+    // ERR_NOT_ENOUGH_MONEY and answers nil; else it stores, fires SEND_MAIL_MONEY_CHANGED and
+    // answers 1, which `StaticPopup.lua:257` branches on.
     g.set(
         "SetSendMailMoney",
         lua.create_function(|lua, copper: Value| {
@@ -627,9 +506,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSendMailMoney() / GetSendMailCOD() → the two amounts as stored (`0x4ae150` / `0x4ae1c0`,
-    // one number each — `reference/1.12-shapes.tsv`): what the stock money kit's SEND_MAIL and
-    // SEND_MAIL_COD types display (1962).
+    // GetSendMailMoney() and GetSendMailCOD() (`0x4ae150`, `0x4ae1c0`): the stored amounts.
     g.set(
         "GetSendMailMoney",
         lua.create_function(|lua, ()| {
@@ -651,10 +528,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSendMailCOD(copper) — store the COD amount the app reads at send time (MailFrame.lua l.497).
-    // SetSendMailCOD(copper) — `0x4ae180` → `0x4adc70` (decision 1965): a non-number RAISES;
-    // without an attached item nothing happens at all — no store, no event, no message — and
-    // there is no affordability or sign check; 0 returns on every path.
+    // SetSendMailCOD(copper) (`0x4ae180`): a non-number raises; with no attached item nothing
+    // happens; there is no purse or sign check and no return value.
     g.set(
         "SetSendMailCOD",
         lua.create_function(|lua, copper: Value| {
@@ -675,27 +550,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSendMailItem() → name, texture, stackCount, quality off the attached cursor item
-    // (MailFrame.lua l.511).
-    //
-    // **The empty leg is `(nil, nil, 0, 0)`** — four values, and slots 3 and 4 are NUMBERS. Read at
-    // `0x4ae590`: `0x4ae6d3`/`0x4ae6da` push nil, then two `push 0; push 0; lua_pushnumber` pairs
-    // at `0x4ae6df`/`0x4ae6ea`, `eax = 4` (wow-re `mail-interaction.md` §5.1, §5-cross-checked;
-    // decision 2129). All three of the reference's failure guards share that one block, so "nothing
-    // attached" and "the item template has not loaded yet" are indistinguishable to a script.
-    //
-    // The `1` this used to push in slot 3 was borrowed from the wrong binding: it is
-    // `GetAuctionSellItemInfo 0x4ce590`'s empty leg (`1.0`/`-1.0`), not this one's.
-    //
-    // **Still not faithful, and stated rather than implied:** on the LOADED leg the reference reads
-    // quality from `[rec+0x1c]` gated on `[rec+0x2c] != 0` = InventoryType, so a **non-equippable**
-    // item answers quality `-1` (`0x4ae6bf`). We do not carry an inventory type here, so an item
-    // whose quality we have not cached answers 0 rather than -1.
+    // GetSendMailItem(): name, texture, stackCount, quality (`MailFrame.lua:511`). The reference
+    // answers `nil, nil, 0, 0` both with nothing attached and before the template loads
+    // (`0x4ae590`). It answers quality -1 for an item whose InventoryType is 0 (`0x4ae6bf`); this
+    // answers the cached quality, or 0.
     g.set(
         "GetSendMailItem",
         lua.create_function(|lua, ()| {
-            // The stack count is read while the model is borrowed: a whole-stack pickup records
-            // no count of its own, so the true size comes back from the source slot.
+            // A whole-stack pickup records no count, so the size comes from the source slot.
             let item = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 model.mail_send_item.clone().map(|it| {
@@ -721,7 +583,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Some(t) => Value::String(lua.create_string(t)?),
                 None => Value::Nil,
             };
-            // A number on every path — the reference's row has no nil alternative in this slot.
+            // A number on every path, as in the reference.
             let quality = Value::Integer(i64::from(it.quality.unwrap_or(0)));
             Ok(MultiValue::from_vec(vec![
                 name,
@@ -732,15 +594,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSendMailPrice() → the flat 30c postage (vmangos's fee; the reference reads a C constant).
+    // GetSendMailPrice(): 30 copper, vmangos's fee (`MailHandler.cpp:243`). The reference's is 30
+    // (`0x4ae756`) plus an uncarried stationery's price, the package's and the enclosed money
+    // (`0x4ae7a0`-`0x4ae7d2`); those are not added here.
     g.set(
         "GetSendMailPrice",
         lua.create_function(|_, ()| Ok(Value::Integer(30)))?,
     )?;
 
-    // ClickSendMailItemButton() — attach the cursor's held bag item as the send attachment, or, with
-    // an empty cursor and a filled slot, pick the attachment back onto the cursor (MailFrame.lua
-    // l.719, mirroring pickup_container_item's swap). A spell/action cursor is refused (no-op).
     g.set(
         "ClickSendMailItemButton",
         lua.create_function(|lua, ()| {
@@ -750,12 +611,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The stationery family (wow-re `ui/scratch/stationery-bindings.md`, 1970) ──
-    // The list is the app's (`Stationery.dbc` × the player's bags × the template cache); the
-    // client rebuilds it from `GetNumStationeries` (`0x4ae202` → `0x4ad970`), on world enter and
-    // on the last item-query answer — the app's per-frame recompute covers all three moments.
+    // ── The stationery family ──
+    // The reference rebuilds the list (`0x4ad970`) in `GetNumStationeries` (`0x4ae1f0`), on world
+    // entry and on the last item-query answer; the app recomputes it every frame.
 
-    // `GetNumStationeries()` — 0 args, 1 number: the usable count.
     g.set(
         "GetNumStationeries",
         lua.create_function(|lua, ()| {
@@ -764,9 +623,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetStationeryInfo(index)` — shape A (`lua_isnumber`, truncate), raising its Usage on a
-    // non-number; 1-based, unsigned bound; exactly 3 returns on every exit: name, the FULL icon
-    // path, BuyPrice in copper — cost nil when the player carries the item; 3 nils out of range.
+    // `GetStationeryInfo(index)` (`0x4ae230`): a non-number raises its Usage; three values
+    // always, three nils out of range.
     g.set(
         "GetStationeryInfo",
         lua.create_function(|lua, index: Value| {
@@ -796,8 +654,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `SelectStationery(index)` — shape A, raising its Usage on a non-number; 0 returns. In range
-    // it stores the row's DBC id; **out of range is not an error — it writes 0**, a deselect.
+    // `SelectStationery(index)` (`0x4ae380`): out of range is not an error, it stores 0.
     g.set(
         "SelectStationery",
         lua.create_function(|lua, index: Value| {
@@ -816,8 +673,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetSelectedStationeryTexture()` — 0 args, 1 return: the BARE `Stationery.dbc` texture name
-    // of the selection; nil for no selection (id 0) or an id the table does not carry.
+    // `GetSelectedStationeryTexture()` (`0x4ae3f0`): nil for no selection or an unknown id.
     g.set(
         "GetSelectedStationeryTexture",
         lua.create_function(|lua, ()| {
@@ -836,27 +692,22 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The attach/detach swap of `ClickSendMailItemButton` — the mail send slot as a cursor drop
-/// target (decision 0216's payload rails). Every `model.cursor` mutation is followed by
-/// [`cursor::queue_cursor_update`]/[`cursor::queue_lock_changed`] so `CURSOR_UPDATE`/
-/// `ITEM_LOCK_CHANGED` fire, exactly like a bag slot.
+/// `ClickSendMailItemButton`: the send slot as a cursor drop target, firing `CURSOR_UPDATE` and
+/// `ITEM_LOCK_CHANGED` like a bag slot.
 fn click_send_mail_item(model: &mut Model) {
     match model.cursor.take() {
-        // Cursor holds a bag item → attach it (the item leaves nothing in the bag until send).
+        // A held bag item attaches; it stays in its bag slot until the send.
         Some(CursorPayload::Item(item)) => {
             let (bag, slot) = (item.bag, item.slot);
-            // If a different item was already attached, it returns to nowhere client-side (the
-            // reference simply overwrites); its slot was never locked, so nothing to unlock.
+            // An earlier attachment is overwritten, as in the reference; its slot has no lock.
             model.mail_send_item = Some(item);
             cursor::queue_cursor_update(model);
             cursor::queue_lock_changed(model, bag, slot);
-            // The attachment changed — `MAIL_SEND_INFO_UPDATE` at `0x4ae0de` (0 args, 1970); the
-            // stock tab re-reads `GetSendMailItem` and the postage on it.
+            // `MAIL_SEND_INFO_UPDATE` (`0x4ae0de`): the stock tab re-reads the item and postage.
             model
                 .pending_events
                 .push(("MAIL_SEND_INFO_UPDATE".to_string(), Vec::new()));
         }
-        // Empty cursor, a filled slot → pick the attachment back onto the cursor (detach).
         None => {
             if let Some(item) = model.mail_send_item.take() {
                 let (bag, slot) = (item.bag, item.slot);
@@ -868,7 +719,6 @@ fn click_send_mail_item(model: &mut Model) {
                     .push(("MAIL_SEND_INFO_UPDATE".to_string(), Vec::new()));
             }
         }
-        // A spell/action payload is refused — put it back untouched (container.rs's refuse arm).
         Some(other) => {
             model.cursor = Some(other);
         }
@@ -880,8 +730,7 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// A send needs a stationery selected (1970): seat the default and select it, the way the
-    /// stock `SendMailFrame_Reset` does on MAIL_SHOW.
+    /// A send needs a stationery: select the default, as the stock `SendMailFrame_Reset` does.
     fn select_default_stationery(s: &mut UiScript) {
         s.set_mail_stationeries(vec![super::StationeryView {
             id: 41,
@@ -918,7 +767,7 @@ mod tests {
             item_texture: (item_id != 0)
                 .then(|| "Interface\\Icons\\INV_Fabric_Linen_01".to_string()),
             item_quality: (item_id != 0).then_some(1),
-            can_delete: false, // from a player, not returned → returnable (not deletable)
+            can_delete: false, // a player's unreturned mail is returned, not deleted
             item_random_property_id: 0,
         }
     }
@@ -929,10 +778,6 @@ mod tests {
         }
     }
 
-    /// `GetInboxInvoiceInfo` answers **seven values, always** — the reference's own `mov eax,7`.
-    /// The miss tail is the part that matters and the part that is easy to get wrong: three nils
-    /// then four ZEROS, not one bare nil. MailFrame.lua destructures all seven unguarded and only
-    /// then tests the third, so a short return leaves its arithmetic running on nils.
     #[test]
     fn the_invoice_answers_seven_values_or_a_three_nil_four_zero_miss() {
         let mut s = UiScript::new().unwrap();
@@ -973,7 +818,7 @@ mod tests {
             "a seller invoice, in the reference's own order"
         );
 
-        // Row 2 carries no invoice — and neither does an index off the end.
+        // Row 2 has no invoice, and index 99 is off the end.
         for idx in [2, 99] {
             assert_eq!(
                 s.arity(&format!("GetInboxInvoiceInfo({idx})")).unwrap(),
@@ -993,11 +838,6 @@ mod tests {
         }
     }
 
-    /// `GetInboxText` returns **four** values always, and for an INVOICE the first is `nil`.
-    /// That is the reference's own carve-out (`0x4af1cf cmp [esi+0x4],2` → `lua_pushnil`), and it
-    /// is what lets MailFrame lay the invoice pane over the letter page: the auction house's raw
-    /// bookkeeping is in the text cache — `GetInboxInvoiceInfo` parses exactly that string — and
-    /// this binding refuses to hand it back (decision 1527).
     #[test]
     fn an_invoice_has_no_letter_body() {
         let mut s = UiScript::new().unwrap();
@@ -1017,7 +857,6 @@ mod tests {
             "nil",
             "the bookkeeping is never handed back as a letter body"
         );
-        // Row 2 is an ordinary letter and keeps its text.
         assert_eq!(
             s.eval::<String>("return tostring((GetInboxText(2)))")
                 .unwrap(),
@@ -1025,8 +864,6 @@ mod tests {
         );
     }
 
-    /// A BUYER invoice says so with the bare ASCII token the Lua compares against — not a
-    /// GlobalString, not localized.
     #[test]
     fn a_buyer_invoice_is_the_literal_token_buyer() {
         let mut s = UiScript::new().unwrap();
@@ -1059,8 +896,6 @@ mod tests {
         s.set_mail(Some(state()));
         assert_eq!(s.eval::<i64>("return GetInboxNumItems()").unwrap(), 2);
 
-        // Row 1 (has item): the leading strings + money/COD/days, then the flags — asserted in two
-        // smaller evals so the harness never destructures the whole 13-tuple in one Rust type.
         let (pkg, sta, sender, subject, money, cod, days): (
             String,
             String,
@@ -1080,7 +915,6 @@ mod tests {
         );
         assert_eq!((money, cod), (5000, 0));
         assert!((days - 29.5).abs() < 1e-3);
-        // hasItem = count 3, wasRead nil, wasReturned nil, textCreated nil, canReply 1, isGM nil.
         assert!(s
             .eval::<bool>(
                 "local a,b,c,d,e,f,g, has, read, ret, tc, reply, gm = GetInboxHeaderInfo(1)\n\
@@ -1088,7 +922,6 @@ mod tests {
             )
             .unwrap());
 
-        // Row 2 (no item): hasItem nil, packageIcon nil.
         assert!(s
             .eval::<bool>(
                 "local pkg, sta, s, subj, m, c, d, has = GetInboxHeaderInfo(2)\n\
@@ -1105,9 +938,9 @@ mod tests {
             s.eval("return GetInboxText(1)").unwrap();
         assert_eq!(body, "Lok'tar.");
         assert_eq!(tex, "STATIONERYTEST");
-        assert_eq!(takeable, Value::Integer(1)); // has a fetchable body
+        assert_eq!(takeable, Value::Integer(1)); // has a body to fetch
         assert!(matches!(invoice, Value::Nil));
-        // Opening queued the row for the mark-read/body ask; deduped within the drain window.
+        // The open is queued once per drain.
         s.run("GetInboxText(1)").unwrap();
         assert_eq!(s.take_mail_opens(), vec![1]);
         assert!(s.take_mail_opens().is_empty(), "drained");
@@ -1123,9 +956,8 @@ mod tests {
             (name.as_str(), count, quality, canuse),
             ("Linen Cloth", 3, 1, 1)
         );
-        // Row 2 has no item → nil.
         assert!(s.eval::<bool>("return GetInboxItem(2) == nil").unwrap());
-        // Row 1 is from a player, not returned → returnable, NOT deletable.
+        // A player's unreturned mail is returnable, not deletable.
         assert!(s
             .eval::<bool>("return InboxItemCanDelete(1) == nil")
             .unwrap());
@@ -1157,7 +989,6 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_money(5_000);
         assert!(s.take_mail_send().is_none());
-        // The purse gate (1965): more than the purse answers nil and names the refusal.
         assert!(s
             .eval::<bool>("return SetSendMailMoney(9999) == nil")
             .unwrap());
@@ -1165,7 +996,7 @@ mod tests {
         assert!(s
             .eval::<bool>("return SetSendMailMoney(1234) == 1")
             .unwrap());
-        // A COD with no attached item is completely silent: no store, no event (1965).
+        // COD with no attached item: no store, no event.
         s.run("SetSendMailCOD(50)").unwrap();
         assert_eq!(s.eval::<i64>("return GetSendMailCOD()").unwrap(), 0);
         select_default_stationery(&mut s);
@@ -1189,12 +1020,10 @@ mod tests {
     fn attach_from_cursor_and_get_send_item() {
         use crate::script::cursor::{CursorItem, CursorPayload};
         let mut s = UiScript::new().unwrap();
-        // Nothing attached → nil name, stack 1.
         assert!(s
             .eval::<bool>("local n = GetSendMailItem()\nreturn n == nil")
             .unwrap());
 
-        // Put a bag item on the cursor, then click the send slot: it attaches.
         s.model_mut().cursor = Some(CursorPayload::Item(CursorItem {
             bar_placeable: true,
             bag: 0,
@@ -1207,18 +1036,16 @@ mod tests {
             equip_slots: Vec::new(),
         }));
         s.run("ClickSendMailItemButton()").unwrap();
-        // Cursor is now empty; the send item reads the attachment.
         assert!(s.eval::<bool>("return not CursorHasItem()").unwrap());
         let (name, _tex, count, quality): (String, String, i64, i64) =
             s.eval("return GetSendMailItem()").unwrap();
         assert_eq!((name.as_str(), count, quality), ("Linen Cloth", 7, 1));
 
-        // A send folds in the attachment's (bag, slot).
         select_default_stationery(&mut s);
         s.run("SendMail('Alt', 'stuff', '')").unwrap();
         assert_eq!(s.take_mail_send().unwrap().item, Some((0, 5)));
 
-        // Clicking again with an empty cursor detaches (back onto the cursor).
+        // Clicking with an empty cursor detaches.
         s.run("ClickSendMailItemButton()").unwrap();
         assert!(s.eval::<bool>("return CursorHasItem()").unwrap());
         assert!(s
@@ -1296,10 +1123,6 @@ mod stationery_tests {
         s
     }
 
-    /// The four verbs, shape by shape (wow-re `stationery-bindings.md`): the count; the info
-    /// triple with a nil cost for a carried paper and three nils past the end; a numeric string
-    /// passes the number gate and a non-number raises the Usage; the selection stores the DBC id,
-    /// out of range deselects, and the texture is the bare basename or nil.
     #[test]
     fn the_stationery_family_answers_like_the_client() {
         let s = seated();
@@ -1350,8 +1173,6 @@ mod stationery_tests {
         );
     }
 
-    /// A send with no stationery selected aborts silently — no request, no error; with one
-    /// selected the request carries the DBC id. Opening/closing the mailbox clears it.
     #[test]
     fn a_send_needs_a_stationery_and_carries_its_id() {
         let mut s = seated();
diff --git a/crates/benilla-ui/src/script/measure.rs b/crates/benilla-ui/src/script/measure.rs
index 91a9ae04..1662a9a0 100644
--- a/crates/benilla-ui/src/script/measure.rs
+++ b/crates/benilla-ui/src/script/measure.rs
@@ -1,81 +1,35 @@
-//! **The synchronous text measure** — the host's font engine, installed *into* the VM so a
-//! `GetStringWidth` answers during the Lua call that asked, not a frame later.
-//!
-//! ## Why this exists
-//!
-//! The real client's `GetStringWidth 0x79e510` calls straight through to its font engine
-//! (`0x772890`) and returns. Ours could not: measuring needs the baked glyph atlas, the atlas
-//! lives in the app, and the app only meets the VM at the frame boundary — so the metric was
-//! served from the [`MeasureRequest`](super::MeasureRequest) round-trip, which lands at **extract,
-//! one frame after the tick that set the text**. Every same-tick `SetText` → `GetStringWidth` pair
-//! read **0**.
-//!
-//! That is not a rounding difference, it is the difference between a laid-out UI and a broken one,
-//! and it is the shape the corpus actually writes:
-//!
-//! ```lua
-//! button:SetText(player)                      -- Bagnon_Forever/database/ui.lua:58
-//! if button:GetTextWidth() + 40 > width then   -- …:59, same tick
-//! ```
-//!
-//! With the answer 0, that dropdown sized itself to 40px and seven character names drew outside
-//! their own frame. The reference's own `SmallMoneyFrame` does the same thing (`MoneyFrame.lua`
-//! l.202), which is why `UiScript::set_digit_advances`
-//! existed: a digits-only stand-in for exactly this, built because the general answer was missing.
-//! This is the general answer, and it retires that special case.
-//!
-//! ## The seam
-//!
-//! [`TextMeasure`] is one method over the request type the round-trip already speaks, so the host
-//! answers a same-tick measure and a batch measure with the same code — there is no second
-//! measuring path to drift. The host owns the engine; the engine owns the *when*.
-//!
-//! **Absent by default, and that is a supported state.** A VM with no measurer installed (every
-//! engine test, every headless run without a font atlas) behaves exactly as it did: metrics stay
-//! 0 until the round-trip fills them. Nothing here is load-bearing for correctness of the
-//! round-trip; it only removes the latency.
+//! The synchronous text measure: the host's font engine installed into the VM, so
+//! `GetStringWidth` answers inside the Lua call that asked, as the reference's does (`0x79e510`
+//! calls its font engine, `0x772890`). UI code measures in the tick it sets text
+//! (`MoneyFrame.lua:202`). With no measurer installed, metrics stay 0 until the
+//! [`MeasureRequest`](super::MeasureRequest) round-trip fills them a frame later.
 
 use mlua::Lua;
 
 use super::{MeasureRequest, MeasuredText, Model};
 use crate::widget::RegionHandle;
 
-/// The host's font engine, as the VM sees it — installed with
-/// [`UiScript::set_text_measurer`](super::UiScript::set_text_measurer).
-///
-/// One method, taking the same [`MeasureRequest`] the batch round-trip carries: the host must
-/// answer a synchronous measure with the identical code that answers
-/// [`UiScript::fontstrings_needing_measure`](super::UiScript::fontstrings_needing_measure), or the
-/// two disagree and a string's width depends on *when* it was asked for.
+/// The host's font engine as the VM sees it. It must answer with the same code as the batch
+/// round-trip, or a string's width depends on when it was asked for.
 pub trait TextMeasure {
-    /// `(laid_out_w, laid_out_h, natural_w)` for `req`, in the region's own frame-local units.
-    ///
-    /// `laid_out_*` is the text wrapped inside `req.wrap_width` when it has one; `natural_w` is
-    /// the width it would take **unwrapped**, which is the number `GetStringWidth` reports (see
-    /// [`MeasuredText::natural_w`]). For a request with no wrap width the two are one number.
-    ///
-    /// Must be **pure with respect to the VM** — it is called with the model mutably borrowed and
-    /// must not re-enter Lua.
+    /// `(laid_out_w, laid_out_h, natural_w)` for `req` in frame-local units; `natural_w`, the
+    /// unwrapped width, is what `GetStringWidth` reports. It runs with the model mutably borrowed,
+    /// so it must not re-enter Lua.
     fn measure(&mut self, req: &MeasureRequest) -> (f32, f32, f32);
 }
 
-/// Measure region `rh` **now** if its stored measure is stale and a measurer is installed.
-///
-/// The one entry point for the metric reads (`GetStringWidth`, `GetWidth`/`GetHeight` on a
-/// FontString): they already treat a key-mismatched measure as absent, so filling the cache here
-/// is invisible to them beyond the answer arriving. A no-op without a measurer, and a no-op when
-/// the stored measure is already current — which is what keeps a per-frame poll from re-measuring.
+/// Measure region `rh` now if a measurer is installed and its stored measure is stale; a current
+/// one is left alone, so a per-frame poll does not re-measure.
 pub(super) fn ensure_measured(lua: &Lua, rh: RegionHandle) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     if model.measurer.is_none() {
         return;
     }
     let Some(req) = super::layout::measure_request_for(&mut model, rh) else {
-        return; // not a FontString, no text, or the stored measure is already this string's
+        return; // not a FontString, no text, or already current
     };
-    // Taken out for the call and put straight back: the measurer needs `&mut self` (a font shaper
-    // is stateful) while the model is already mutably borrowed. Safe because the trait forbids
-    // re-entering the VM, so nothing can observe the gap.
+    // Taken out and put back: the measurer needs `&mut self` while the model is borrowed, and it
+    // cannot re-enter the VM, so nothing sees the gap.
     let mut engine = model.measurer.take().expect("checked above");
     let (w, h, natural_w) = engine.measure(&req);
     model.measurer = Some(engine);
@@ -88,44 +42,31 @@ pub(super) fn ensure_measured(lua: &Lua, rh: RegionHandle) {
     let mut moved = false;
     if let Some(d) = model.region_data.get_mut(&rh) {
         moved = super::types::MeasuredText::layout_moved(d.measured, new);
-        // The KEY always lands — this IS the measure cache, and a stale key re-requests forever.
+        // The key always lands: a stale key re-requests forever.
         d.measured = Some(new);
     }
     if moved {
-        // Measured extents are the auto-size axes' inputs — the layout gate's read set, the
-        // same touch `set_measured_text` does. Guarded on a change the LAYOUT can see: a
-        // re-measure that returns the same box (a same-width countdown tick) must not open
-        // tier 1, or it costs a whole-roster hash to conclude nothing moved (decision 1385).
-        // A new extent moves no edge and no roster membership, so it names its node (1388).
+        // Only a box that moved touches the layout, as in `set_measured_text`: a same-width
+        // re-measure (a countdown tick) must not cost a whole-roster hash.
         model.touch_layout_region(rh);
     }
 }
 
 impl super::UiScript {
-    /// Install the host's font engine, so metric reads answer inside the tick that asked.
-    ///
-    /// Call again to replace it — which the host must do whenever its **raster environment**
-    /// changes (window resize, `uiScale`), for the same reason
-    /// `UiScript::forget_text_metrics` exists: glyph
-    /// advances step to whole *physical* pixels, so a measurer built under one seam does not
-    /// answer for another.
+    /// Install the host's font engine, so metric reads answer inside the tick that asked. Replace
+    /// it whenever the window size or `uiScale` changes: glyph advances snap to whole physical
+    /// pixels.
     pub fn set_text_measurer(&mut self, measurer: Box<dyn TextMeasure>) {
         self.model_mut().measurer = Some(measurer);
     }
 
-    /// Whether a [`TextMeasure`] is installed — the host's gate for skipping its own batch measure
-    /// pass, which would find nothing to do anyway.
+    /// Whether a [`TextMeasure`] is installed; the host then skips its batch measure pass.
     pub fn has_text_measurer(&self) -> bool {
         self.model_mut().measurer.is_some()
     }
 
-    /// Answer every pending FontString measure inline. Returns whether anything changed (i.e.
-    /// whether the layout needs another solve). No-op without a measurer.
-    ///
-    /// This is [`UiScript::resolve`](super::UiScript::resolve)'s own half of the round-trip: with
-    /// an engine installed the VM closes the loop itself, so a FontString's box is right in the
-    /// frame its text was set rather than the frame after — and the host's batch pass finds an
-    /// empty request list and does nothing.
+    /// Answer every pending FontString measure inline, so a box is right in the frame its text
+    /// was set; returns whether anything changed.
     pub(super) fn fill_measures(&mut self) -> bool {
         if !self.has_text_measurer() {
             return false;
diff --git a/crates/benilla-ui/src/script/merchant.rs b/crates/benilla-ui/src/script/merchant.rs
index d5e2079b..0768e037 100644
--- a/crates/benilla-ui/src/script/merchant.rs
+++ b/crates/benilla-ui/src/script/merchant.rs
@@ -1,29 +1,11 @@
-//! The merchant bindings (decision 0081 phase 4) — the Era-shaped vendor surface, the same two-way
-//! seam as [`super::container`]/[`super::gossip`]: the app pushes a **merchant snapshot**
-//! ([`UiScript::set_merchant`] — the vendor rows already resolved from the wire to name/icon/price
-//! by the app's item stores), and the Lua `BuyMerchantItem`/`CloseMerchant` calls queue outbound
-//! **intents** the app drains ([`UiScript::take_merchant_buys`] / [`UiScript::take_merchant_close`]).
-//! The engine holds no vendor knowledge — a row is "a name, an icon path, a price, a stack size,
-//! how many are left, and the tooltip's stat head" ([`ItemStatsHead`], read by
-//! `BenillaGetMerchantItemStats`).
+//! The merchant bindings: the app pushes the open vendor ([`UiScript::set_merchant`]), and the
+//! Lua verbs queue intents it drains. A row is 1-based; the app maps it to the item entry
+//! `CMSG_BUY_ITEM` needs.
 //!
-//! ## The 5875 API shape
-//!
-//! 1.12's `GetMerchantItemInfo(index)` returns a flat **6-value** tuple the FrameXML reads
-//! positionally — `name, texture, price, quantity, numAvailable, isUsable` (byte-verified,
-//! `0x4fb150`; the ref's own `MerchantFrame_UpdateMerchantInfo` destructures exactly these six.
-//! The `isPurchasable`/`extendedCost` extras an earlier draft carried are TBC-era, not 5875).
-//! `index` is **1-based**; an invalid index answers the binding's fixed tuple
-//! `(nil, nil, 0, 1, 0, 1)` — same shape as `GetBuybackItemInfo`'s (`0x4fb2be`). `numAvailable`
-//! is `-1` for unlimited stock (the wire's `0xFFFF_FFFF` through `fild`, mapped by the app).
-//! `isUsable` is `1`/`nil` (the client pushes a number or nil, never a boolean): the
-//! [`super::item_stats::item_usable`] gate over the row's template — a template still in flight
-//! reads usable, the getter's null-record skip (`0x4fb298`).
-//!
-//! Buying addresses the row by its **1-based list position** here (`BuyMerchantItem(index)`); the app
-//! maps that position to the item *entry* the wire's `CMSG_BUY_ITEM` needs (buy is by entry, not the
-//! vendor `muid` — decision 0081). vanilla's client-side `CloseMerchant()` sends no packet, so it
-//! just flags the app to clear its local state (the gossip pattern).
+//! `GetMerchantItemInfo(index)` answers `name, texture, price, quantity, numAvailable, isUsable`
+//! (`0x4fb150`), or `(nil, nil, 0, 1, 0, 1)` for an invalid index (`0x4fb2be`). Unlimited stock is
+//! `numAvailable` -1; `isUsable` is 1 or nil, the [`super::item_stats::item_usable`] gate, and a
+//! template still in flight reads usable (`0x4fb298`).
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -31,149 +13,116 @@ use super::container::UiCursorMode;
 use super::cursor::CursorPayload;
 use super::Model;
 
-/// One vendor row, resolved by the app from the wire `VendorItem` (decision 0081). Plain data —
-/// 1-based order in the window is its position in [`MerchantState::items`].
+/// One vendor row, resolved by the app; its 1-based index is its place in [`MerchantState::items`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MerchantItem {
-    /// The item name (`GetMerchantItemInfo`'s first return); `None` while the ask-once item-template
-    /// query is still in flight (the API reports `nil`, the XML shows a placeholder).
+    /// The item name; `None` while its template is in flight, answered as nil.
     pub name: Option<String>,
-    /// Icon texture path (`Interface\Icons\…`); `None` while the template answer is in flight.
+    /// Icon path; `None` while the template is in flight.
     pub texture: Option<String>,
-    /// Buy price in copper (already reputation-discounted server-side).
+    /// Buy price in copper, already reputation-discounted by the server.
     pub price: u32,
-    /// Stack size delivered per purchase (`item_template.buy_count`, the wire's `buy_count`).
+    /// Stack size per purchase (`item_template.buy_count`).
     pub quantity: u32,
-    /// Remaining stock, or `-1` for unlimited (the app maps the wire's `0xFFFF_FFFF`).
+    /// Remaining stock, -1 for unlimited (the wire's `0xFFFF_FFFF`).
     pub num_available: i32,
-    /// The item's template **entry** — what `CMSG_BUY_ITEM` addresses (the app maps the clicked
-    /// 1-based row to this; the Lua side never sees it).
+    /// The template entry `CMSG_BUY_ITEM` addresses; Lua never sees it.
     pub item_id: u32,
-    /// The stat head the hover tooltip renders, from the same ask-once template answer as `name`
-    /// (`None` while it's in flight — the tooltip shows nothing it can't know yet). Still plain
-    /// data: the engine renders whatever numbers the app resolved, it holds no item model.
+    /// The hover tooltip's stat head; `None` while the template is in flight.
     pub stats: Option<ItemStatsHead>,
-    /// The row's full escaped `|cff…|Hitem:…|h[Name]|h|r` link (`GetMerchantItemLink`, decision
-    /// 1059) — what the row click's ctrl/shift arms hand to `DressUpItemLink` /
-    /// `ChatFrameEditBox:Insert` (`MerchantFrame.lua:303`/`:306`). `None` while the template answer
-    /// is in flight (the link embeds the name), and `None` on a **buyback** row: 1.12 has no
-    /// `GetBuybackItemLink` — the reference's buyback arm is an unmodified `BuybackItem(this:GetID())`
-    /// with no ctrl/shift branch at all (`MerchantFrame.lua:358-361`), so nothing would read it.
+    /// `GetMerchantItemLink`'s answer; `None` while in flight and on a buyback row, as 1.12 has no
+    /// `GetBuybackItemLink` and the buyback click takes no modifier (`MerchantFrame.lua:358-361`).
     pub link: Option<String>,
-    /// `Stackable` from the item's own template — what one slot can hold, `1` for an item that
-    /// does not stack. `None` while the ask-once template query is in flight, like `name`.
-    ///
-    /// This is `GetMerchantItemMaxStack`'s answer and it exists for one caller: the reference's
-    /// `MerchantItemButton_OnClick` asks it before a shift-click, and opens the stack-split
-    /// spinner only when it is above 1 (`MerchantFrame.lua:313-326`, and again at :340 for the
-    /// buy-in-bulk arm). The wire has carried it all along — `item_template.stackable`, parsed and
-    /// then dropped, because nothing on the Lua side could ask.
+    /// `GetMerchantItemMaxStack`: the template's `stackable`, 1 if it does not stack; `None` while
+    /// in flight.
     pub max_stack: Option<u32>,
 }
 
-/// An item template's tooltip stat head (the app's `ItemInfo` view, resolved per row): what the
-/// vendor hover tooltip needs beyond name/icon/price. The real client's `GameTooltip:SetMerchantItem`
-/// reads the same template fields C++-side; benilla feeds them to Lua through
-/// `BenillaGetMerchantItemStats(index)` (no 1.12 Lua API carries damage/armor — tooltip content was
-/// C++'s alone — so the feed is benilla-named, not Era-shaped).
+/// An item template's tooltip stat head, resolved per row by the app. The reference's
+/// `GameTooltip:SetMerchantItem` reads these in C++; no 1.12 Lua API carries them.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct ItemStatsHead {
-    /// 0 poor … 6 artifact — colours the tooltip's name line.
+    /// 0 poor to 6 artifact; colours the tooltip's name line.
     pub quality: u32,
-    /// `InventoryType` — the tooltip's slot line ("Main Hand", "Chest", …); 0 = no slot line.
+    /// `InventoryType`, the tooltip's slot line ("Main Hand", "Chest"); 0 for none.
     pub inventory_type: u32,
-    /// Item class (2 weapon, 4 armor, 6 projectile) — with `subclass`, the slot line's right column.
+    /// Item class (2 weapon, 4 armor, 6 projectile); with `subclass`, the slot line's right side.
     pub class: u32,
     /// Item subclass within `class` (7 = sword, 1 = cloth, …).
     pub subclass: u32,
-    /// Damage block 0 per-hit minimum (0 for non-weapons).
+    /// Damage block 0's per-hit minimum, 0 for a non-weapon.
     pub dmg_min: f32,
-    /// Damage block 0 per-hit maximum.
+    /// Damage block 0's per-hit maximum.
     pub dmg_max: f32,
-    /// Damage block 0 school (0 physical, 1 Holy … 6 Arcane).
+    /// Damage block 0's school (0 physical, 1 Holy to 6 Arcane).
     pub dmg_type: u32,
-    /// Attack delay in milliseconds ("Speed" = delay / 1000).
+    /// Attack delay in milliseconds; the tooltip's "Speed" is delay / 1000.
     pub delay_ms: u32,
-    /// The armor line's value; 0 = no line.
+    /// The armor line's value; 0 for none.
     pub armor: u32,
-    /// A shield's block line; 0 = no line.
+    /// A shield's block line; 0 for none.
     pub block: u32,
-    /// `SellPrice` — what a vendor pays per unit (the bag tooltip's money row while a merchant is
-    /// open; 0 = the "No sell price" line).
+    /// What a vendor pays per unit; 0 shows the tooltip's "No sell price" line.
     pub sell_price: u32,
 }
 
-/// One open merchant window: the vendor's rows, the buyback slots, and the repair head. Pushed
-/// whole by the app; `None` means no vendor is open (the window is closed).
+/// One open merchant window, pushed whole by the app; `None` means no vendor is open.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct MerchantState {
     pub items: Vec<MerchantItem>,
-    /// The buyback slots, oldest-first (index 1 = the oldest; the LAST entry is the most recent
-    /// sale — the one the merchant page's single buyback slot shows, ref
-    /// `GetBuybackItemInfo(GetNumBuybackItems())`). Resolved by the app from the player's
-    /// VENDORBUYBACK descriptor fields + the item stores; `price` here is the buyback price
-    /// field, `quantity` the stored item's stack count.
+    /// Buyback slots, oldest first; the last, the latest sale, is the one the merchant page shows
+    /// (`MerchantFrame.lua:133`). From the player's VENDORBUYBACK fields: `price` is the buyback
+    /// price, `quantity` the stored stack.
     pub buyback: Vec<MerchantItem>,
-    /// Whether this vendor repairs (UNIT_NPC_FLAGS repair bit) — shows the repair buttons.
+    /// Whether this vendor repairs (the `UNIT_NPC_FLAGS` repair bit).
     pub can_repair: bool,
-    /// The repair-all cost in copper the app computed (0 = nothing to repair → the repair-all
-    /// button disables, ref MerchantFrame_OnShow).
+    /// The repair-all cost in copper; 0 disables the button (`MerchantFrame_OnShow`).
     pub repair_all_cost: u32,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open merchant's stock snapshot.
+    /// Push (or clear, with `None`) the open vendor.
     pub fn set_merchant(&mut self, state: Option<MerchantState>) {
         self.model_mut().merchant = state;
     }
 
-    /// Drain the `(index, quantity)` buy intents queued by `BuyMerchantItem` since the last call.
-    /// `index` is the 1-based row position; the app maps it to the item entry the wire needs.
+    /// Drain the `(row, quantity)` buys `BuyMerchantItem` queued, the row 1-based.
     pub fn take_merchant_buys(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().merchant_buys)
     }
 
-    /// Drain the `(bag, slot)` sells `PickupMerchantItem`'s cursor arm queued — the item the
-    /// cursor was holding when it was dropped on the vendor window. The app resolves the concrete
-    /// item guid from the pair and sends `CMSG_SELL_ITEM`, the same resolution the bag-click sell
-    /// route already does.
+    /// Drain the `(bag, slot)` of each cursor item dropped on the vendor; the app sells it.
     pub fn take_merchant_cursor_sells(&mut self) -> Vec<(i64, u32)> {
         std::mem::take(&mut self.model_mut().merchant_cursor_sells)
     }
 
-    /// Drain the `(bag, slot, item entry)` buys a held vendor row queued by being dropped into a
-    /// container slot — `CMSG_BUY_ITEM_IN_SLOT 0x1a3`.
+    /// Drain the `(bag, slot, entry)` of held rows dropped into bags (`CMSG_BUY_ITEM_IN_SLOT`).
     pub fn take_merchant_slot_buys(&mut self) -> Vec<(i64, u32, u32)> {
         std::mem::take(&mut self.model_mut().merchant_slot_buys)
     }
 
-    /// Whether `CloseMerchant` was called since the last drain (and clear the flag). vanilla's
-    /// client-side close sends no packet — the app just clears its local merchant state.
+    /// Whether `CloseMerchant` was called since the last drain; the close sends no packet.
     pub fn take_merchant_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().merchant_close)
     }
 
-    /// Drain the 1-based buyback-slot intents queued by `BuybackItem` since the last call. The app
-    /// maps each to the wire's absolute buyback inventory slot.
+    /// Drain the 1-based buyback slots `BuybackItem` queued.
     pub fn take_merchant_buybacks(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().merchant_buybacks)
     }
 
-    /// Whether `RepairAllItems` was called since the last drain (and clear the flag). The app
-    /// sends the repair-all wire message.
+    /// Whether `RepairAllItems` was called since the last drain.
     pub fn take_repair_all(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().repair_all)
     }
 
-    /// The client-side repair-mode latch (`ShowRepairCursor`/`HideRepairCursor`/`InRepairMode`):
-    /// while set, a bag/equipment click means "repair this item" — the app reads this to route
-    /// clicks and swap the hardware cursor.
+    /// The repair-mode latch: while set, a bag or equipment click repairs the item.
     pub fn repair_mode(&self) -> bool {
         self.model_ref().repair_mode
     }
 }
 
-/// `1`/`nil` — how the client pushes a usable flag (`pushnumber(1.0)` / `pushnil`).
+/// 1 or nil, as the client pushes a usable flag (`pushnumber(1.0)` / `pushnil`).
 fn usable_value(usable: bool) -> Value {
     if usable {
         Value::Integer(1)
@@ -182,8 +131,7 @@ fn usable_value(usable: bool) -> Value {
     }
 }
 
-/// The invalid-index tuple both getters answer (`0x4fb2be` / the buyback equivalent):
-/// `(nil, nil, 0, 1, 0, 1)` — still six values.
+/// Both getters' invalid-index six-tuple (`0x4fb2be`, and the buyback one).
 fn invalid_tuple() -> Vec<Value> {
     vec![
         Value::Nil,
@@ -199,7 +147,6 @@ fn invalid_tuple() -> Vec<Value> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // → the number of rows the open vendor has (0 when no vendor is open).
     g.set(
         "GetMerchantNumItems",
         lua.create_function(|lua, ()| {
@@ -208,9 +155,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMerchantItemInfo(index) → name, texture, price, quantity, numAvailable, isUsable — the
-    // byte-verified 5875 6-tuple (0x4fb150; see the module doc). `index` is 1-based; an invalid
-    // index answers the fixed tuple (nil, nil, 0, 1, 0, 1).
     g.set(
         "GetMerchantItemInfo",
         lua.create_function(|lua, index: usize| {
@@ -248,13 +192,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMerchantItemLink(index) → the row's full escaped `|cff…|Hitem:…|h[Name]|h|r` link | nil.
-    // 1-based like GetMerchantItemInfo; nil out of range and nil while the row's template answer is
-    // in flight (the link embeds the name). The reference's row click reads it for both LEFT-button
-    // modifier arms — `DressUpItemLink(GetMerchantItemLink(this:GetID()))` (`MerchantFrame.lua:303`)
-    // and `ChatFrameEditBox:Insert(...)` (`:306`); ours routes the second through
-    // `BenillaChatEdit_InsertLink`, whose whole job is the nil this getter can answer. Merchant rows
-    // only: see [`MerchantItem::link`] for why a buyback row carries none. Decision 1059.
+    // GetMerchantItemLink(index): nil out of range and while in flight; both stock row-click
+    // arms accept a nil (`MerchantFrame.lua:303`, `:306`).
     g.set(
         "GetMerchantItemLink",
         lua.create_function(|lua, index: usize| {
@@ -273,18 +212,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMerchantItemMaxStack(index) → the stack size ONE slot can hold for that row's item, or
-    // nil while its template answer is in flight / the index is out of range.
-    //
-    // Its only caller in 1.12 is the reference's own `MerchantItemButton_OnClick`, which asks it
-    // twice — once on the right-click arm (`MerchantFrame.lua:313`) and once on shift-click
-    // (`:340`) — and takes the plain single-buy path whenever the answer is `<= 1`, opening the
-    // stack-split spinner otherwise. So the number decides whether a vendor click asks "how many?"
-    // at all.
-    //
-    // The value was on the wire and parsed the whole time (`item_template.stackable`); nothing on
-    // the Lua side could reach it until now, which is why the reference's merchant window listed
-    // this as one of its two missing verbs.
+    // GetMerchantItemMaxStack(index): nil while in flight or out of range. A right shift-click, or
+    // a left one with the chat box closed, asks it and opens the stack-split spinner only above 1
+    // (`MerchantFrame.lua:313`, `:340`).
     g.set(
         "GetMerchantItemMaxStack",
         lua.create_function(|lua, index: usize| {
@@ -299,9 +229,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // BenillaGetMerchantItemStats(index) → quality, invType, class, subclass, dmgMin, dmgMax,
-    // dmgType, delayMs, armor, block — the tooltip stat head ([`ItemStatsHead`]), or nil while
-    // the row's template answer is in flight / the index is out of range. Benilla-named: 1.12's Lua
-    // API never carried these (item tooltip content was C++'s alone — `SetMerchantItem 0x534080`).
+    // dmgType, delayMs, armor, block, or nil. Not a 1.12 verb: the reference's tooltip reads the
+    // template in C++ (`SetMerchantItem 0x534080`).
     g.set(
         "BenillaGetMerchantItemStats",
         lua.create_function(|lua, index: usize| {
@@ -331,8 +260,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BuyMerchantItem(index [, quantity]) — queue the 1-based row + stack count (default 1); the app
-    // maps the row to the item entry the wire addresses.
     g.set(
         "BuyMerchantItem",
         lua.create_function(|lua, (index, quantity): (u32, Option<u32>)| {
@@ -342,62 +269,42 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PickupMerchantItem(index) — **two verbs behind one name** (`0x4fb760`, wow-re
-    // `system/ui/scratch/merchant-cursor-law.md`). `0x4fb787` calls `GetCursorItem 0x494c60`,
-    // which answers for **mode 1 only**, and the result forks the whole function:
+    // PickupMerchantItem(index): two verbs in one (`0x4fb760`), forked at `0x4fb787` on
+    // `GetCursorItem 0x494c60`, which answers for mode 1 only; stock never checks
+    // `CursorHasItem()` first (`MerchantFrame.lua:329`). A bag item on the cursor is sold, index
+    // ignored and no merchant-open gate, which stock `MerchantFrame.xml:743`'s
+    // `PickupMerchantItem(0)` relies on; otherwise row `index - 1` is grabbed as cursor mode 5.
     //
-    //   * cursor holds a real bag item  → **SELL it** (`CMSG_SELL_ITEM 0x1a0`), then clear the
-    //     cursor. The index is IGNORED on this arm and there is no merchant-open gate on it. This
-    //     is what stock `MerchantFrame.xml:743`'s `<OnMouseUp>PickupMerchantItem(0)</OnMouseUp>`
-    //     is for: dropping a bag item anywhere on the vendor window sells it.
-    //   * otherwise                     → **grab** vendor row `index - 1` as cursor mode 5.
-    //
-    // Stock FrameXML never guards this call with `CursorHasItem()` — `MerchantFrame.lua:329`'s
-    // `else` is the else of the ctrl/shift modifier chain. An unmodified left-click calls it
-    // whatever the cursor holds, and the binding decides.
-    //
-    // **Every refusal is silent, and every refusal CLEARS THE CURSOR** — there is no `luaL_error`
-    // anywhere in the range, unlike its neighbour `BuyMerchantItem`. The ladder, in order:
-    // non-number argument (`0x4fb7cb`; a numeric *string* is accepted), `index < 1` (`0x4fb7e1`),
-    // `index > count` (`0x4fb7e9`), no merchant open (`0x4fb7f7`), a dead row (`0x4fb80b`), and a
-    // re-click on the row already held (`0x4fb818`, a toggle-off). Conversion is `_ftol` —
-    // **truncate toward zero**, then `-1`, bounded signed.
-    //
-    // It does **not** test stock and does **not** test the item cache: a sold-out row grabs fine
-    // and the buy still goes out, and the server refuses it. `numAvailable` is read exactly once
-    // image-wide, by `GetMerchantItemInfo`, for display.
+    // Every refusal is silent and clears the cursor: a non-number (`0x4fb7cb`; a numeric string
+    // passes), `index < 1` (`0x4fb7e1`), `index > count` (`0x4fb7e9`), no merchant (`0x4fb7f7`), a
+    // dead row (`0x4fb80b`), or the held row again (`0x4fb818`, the toggle-off). Neither stock nor
+    // the item cache is tested: a sold-out row grabs, and the server refuses the buy.
     g.set(
         "PickupMerchantItem",
         lua.create_function(|lua, index: Option<f64>| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
 
-            // The sell fork, and it comes FIRST — before the argument is even looked at. The
-            // clear is the SELL clear, not `ClearCursor`: it fires `CURSOR_UPDATE` and leaves the
-            // source slot greyed until the server's inventory update
-            // (`cursor::take_cursor_item_for_sale`, shared with the interact ladder's vendor arm,
-            // which is the same `0x494b60` call — decision 1914).
+            // The sell fork comes first, before the argument is read. Its clear is the sale's, not
+            // `ClearCursor`: `CURSOR_UPDATE` fires and the source slot stays greyed until the
+            // server's inventory update (`0x494b60`).
             if let Some(item) = crate::script::cursor::take_cursor_item_for_sale(&mut model) {
                 model.merchant_cursor_sells.push((item.bag, item.slot));
                 return Ok(());
             }
 
-            // From here every leg clears the cursor and answers nothing. Holding a mode-5 payload
-            // and calling this again is the toggle-off, which is the same clear.
+            // Every other leg clears with the real `ClearCursor(1,1)` (`0x4fb82d`/`0x4fb83f` on a
+            // refusal, `0x49510b` in the grab), not a bare drop: a held spell fires `CURSOR_UPDATE`
+            // and hides the bar grid, and an armed gift wrap is cancelled (`0x5edf10`).
             let held = match &model.cursor {
                 Some(CursorPayload::Merchant(m)) => Some(m.row),
                 _ => None,
             };
-            model.cursor = None;
+            crate::script::cursor::clear_cursor(&mut model);
 
             let Some(index) = index else { return Ok(()) };
-            // `_ftol` truncates toward zero; the bound is then applied signed, so a negative or
-            // a zero index falls out here rather than wrapping into a row. NaN is written as its
-            // own test rather than as a negated `>=` — same answer, and the intent is on the page.
-            //
-            // The upper bound is ours and it is load-bearing, not defensive: without it a Lua
-            // index of `2^32 + 1` truncates on the cast to row 0 and would grab the FIRST row.
-            // The reference cannot have that bug — its bound is against the vendor count, which
-            // it applies before any narrowing.
+            // `_ftol` truncates toward zero, then the bound applies signed. The upper bound is
+            // load-bearing: `2^32 + 1` would narrow to row 0, where the reference bounds against
+            // the vendor count before any narrowing.
             let row = index.trunc();
             if row.is_nan() || row < 1.0 || row > f64::from(u32::MAX) {
                 return Ok(());
@@ -410,7 +317,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             let Some(item) = merchant.items.get(row0 as usize) else {
                 return Ok(());
             };
-            // The toggle-off: naming the row already on the cursor puts nothing back.
+            // The toggle-off: naming the held row puts nothing back.
             if held == Some(row0) {
                 return Ok(());
             }
@@ -419,12 +326,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 row: row0,
                 texture: item.texture.clone(),
             });
+            // The grab's `SignalEvent(CURSOR_UPDATE)` (`0x495159`); mode 5 skips the mode-7
+            // `ACTIONBAR_SHOWGRID` branch.
             model.cursor = Some(payload);
+            crate::script::cursor::queue_cursor_update(&mut model);
             Ok(())
         })?,
     )?;
 
-    // CloseMerchant() — client-side close (no packet, vanilla): flag it so the app clears its state.
     g.set(
         "CloseMerchant",
         lua.create_function(|lua, ()| {
@@ -434,7 +343,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → how many buyback slots are filled (ref GetNumBuybackItems; 0 with no vendor open).
     g.set(
         "GetNumBuybackItems",
         lua.create_function(|lua, ()| {
@@ -443,11 +351,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetBuybackItemInfo(index) → name, texture, price, quantity, numAvailable, isUsable (the
-    // same 6-tuple; 0x4fb310, wow-re ui/scratch/buyback-data-path.md). `index` is 1-based
-    // oldest-first; an invalid index answers the fixed tuple (nil, nil, 0, 1, 0, 1). isUsable is
-    // the same 0x5ea930 gate over the sold item's template (0x4fb4f7) — yes, even a just-sold
-    // item reds if the seller can't use it (a mule selling a wrong-class drop).
+    // GetBuybackItemInfo(index): the same six-tuple (`0x4fb310`), oldest first. isUsable is the
+    // same `0x5ea930` gate over the sold item (`0x4fb4f7`): one its seller cannot use reads red.
     g.set(
         "GetBuybackItemInfo",
         lua.create_function(|lua, index: usize| {
@@ -485,8 +390,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BenillaGetBuybackItemStats(index) — the buyback hover's tooltip stat head, same shape and
-    // reason as BenillaGetMerchantItemStats.
+    // BenillaGetBuybackItemStats(index): the buyback hover's stat head, as above.
     g.set(
         "BenillaGetBuybackItemStats",
         lua.create_function(|lua, index: usize| {
@@ -516,8 +420,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BuybackItem(index) — queue the 1-based buyback slot; the app maps it to the wire's absolute
-    // inventory slot.
     g.set(
         "BuybackItem",
         lua.create_function(|lua, index: u32| {
@@ -527,7 +429,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CanMerchantRepair() → 1/nil (the Era boolean shape) — whether the open vendor repairs.
     g.set(
         "CanMerchantRepair",
         lua.create_function(|lua, ()| {
@@ -539,8 +440,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetRepairAllCost() → cost, canRepair — the app-computed repair-all total; canRepair is
-    // "there is damage to pay for" (ref MerchantFrame_OnShow enables the button on it).
+    // GetRepairAllCost() → cost, canRepair: whether there is damage to pay for, which enables the
+    // repair-all button (`MerchantFrame.lua:38`).
     g.set(
         "GetRepairAllCost",
         lua.create_function(|lua, ()| {
@@ -555,7 +456,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RepairAllItems() — flag the repair-all intent for the app to send.
     g.set(
         "RepairAllItems",
         lua.create_function(|lua, ()| {
@@ -565,9 +465,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The repair-mode latch trio (ref MerchantRepairItemButton OnClick): ShowRepairCursor arms
-    // "next item click repairs", HideRepairCursor disarms, InRepairMode() → 1/nil reads it. The
-    // app reads UiScript::repair_mode to route clicks + swap the hardware cursor.
     g.set(
         "ShowRepairCursor",
         lua.create_function(|lua, ()| {
@@ -597,14 +494,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ShowMerchantSellCursor(index) (5875 `0x4fbab0`, "buying from vendor") and
-    // ShowBuybackSellCursor(index) (`0x4fbbb0`, "re-buying") — the vendor-item hover cursor
-    // (wow-re cursor-system.md §7). Despite the "Sell" in the names, these arm the BUY cursor with
-    // an affordability gate: player coin vs the row's price → Buy(3) if `coin >= price`, else the
-    // grayed UnableBuy(23). The merchant frame's OnUpdate re-arms this every frame while an item is
-    // hovered (Ctrl-hover swaps to `ShowInspectCursor` instead); OnLeave `ResetCursor`s it. An
-    // unresolvable index leaves the cursor unchanged — the binary's every-fail-path `ret` with no
-    // `CursorSetMode` (the in-flight item lock and base-mode-Point gates live app-side).
+    // ShowMerchantSellCursor(index) (`0x4fbab0`) and ShowBuybackSellCursor(index) (`0x4fbbb0`):
+    // despite the names, the buy cursor, re-armed each frame an item is hovered
+    // (`MerchantFrame.xml:726-733`). Every fail path returns without `CursorSetMode`; the
+    // in-flight item lock and base-mode Point gates live app-side.
     g.set(
         "ShowMerchantSellCursor",
         lua.create_function(|lua, index: usize| {
@@ -627,15 +520,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Arm the vendor-item hover cursor from a `price` picked out of the open merchant snapshot: Buy(3)
-/// if the player can afford it, UnableBuy(23) otherwise. Shared by `ShowMerchantSellCursor` and
-/// `ShowBuybackSellCursor` (which differ only in which price list they read). A `None` price (no
-/// vendor open, or the 1-based index out of range) leaves the cursor untouched — the binary bails
-/// without a `CursorSetMode` (wow-re cursor-system.md §7).
+/// Arm the vendor hover cursor from a row's price: Buy(3) if the player can afford it, else the
+/// greyed UnableBuy(23); no price leaves the cursor untouched.
 fn arm_vendor_cursor(lua: &Lua, price_of: impl FnOnce(&MerchantState) -> Option<u32>) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-    // The sell-cursor family bails on `IsTargeting` at its first instruction (wow-re
-    // `item-target-cursor-and-dropitemonunit.md`) — an armed spell keeps its cast cursor.
+    // The family bails on `IsTargeting` first (`0x6e48a0`): an armed spell keeps its cursor.
     if model.spell_targeting {
         return;
     }
@@ -665,7 +554,6 @@ mod tests {
                     quantity: 1,
                     num_available: -1, // unlimited
                     item_id: 159,
-                    // A consumable's stat head: everything zero but the quality.
                     stats: Some(ItemStatsHead {
                         quality: 1,
                         ..Default::default()
@@ -673,7 +561,7 @@ mod tests {
                     link: Some("|cffffffff|Hitem:159:0:0:0|h[Refreshing Spring Water]|h|r".into()),
                     max_stack: Some(20),
                 },
-                // An in-flight row: the vendor list arrived, the item-template answer hasn't.
+                // In flight: the list arrived, its item template has not.
                 MerchantItem {
                     name: None,
                     texture: None,
@@ -693,7 +581,6 @@ mod tests {
     #[test]
     fn merchant_snapshot_reads() {
         let mut s = UiScript::new().unwrap();
-        // No vendor open: count 0, info nil.
         assert_eq!(s.eval::<i64>("return GetMerchantNumItems()").unwrap(), 0);
         assert!(s
             .eval::<bool>("return GetMerchantItemInfo(1) == nil")
@@ -701,7 +588,6 @@ mod tests {
 
         s.set_merchant(Some(stock()));
         assert_eq!(s.eval::<i64>("return GetMerchantNumItems()").unwrap(), 2);
-        // Row 1 (resolved): the byte-verified 6-tuple (0x4fb150) — isUsable is 1, not a boolean.
         let (name, texture, price, quantity, num, usable) = s
             .eval::<(String, String, i64, i64, i64, i64)>("return GetMerchantItemInfo(1)")
             .unwrap();
@@ -710,15 +596,13 @@ mod tests {
         assert_eq!((price, quantity, num), (25, 1, -1));
         assert_eq!(usable, 1);
 
-        // Row 2 (in flight): name + texture nil, the rest still present — and usable (the
-        // null-record skip: no template answer, nothing to judge).
+        // In flight: name and texture nil, and usable (the null-record skip).
         assert!(s
             .eval::<bool>(
                 "local n, t, p, q, a, u = GetMerchantItemInfo(2)\n\
                  return n == nil and t == nil and p == 1500 and u == 1",
             )
             .unwrap());
-        // An invalid index answers the fixed 6-tuple (nil, nil, 0, 1, 0, 1) — 0x4fb2be.
         assert!(s
             .eval::<bool>(
                 "local n, t, p, q, a, u = GetMerchantItemInfo(9)\n\
@@ -726,8 +610,6 @@ mod tests {
             )
             .unwrap());
 
-        // GetMerchantItemLink: the resolved row's link; nil while the template is in flight and nil
-        // out of range (the row click's ctrl/shift arms hand this straight on — decision 1059).
         assert_eq!(
             s.eval::<String>("return GetMerchantItemLink(1)").unwrap(),
             "|cffffffff|Hitem:159:0:0:0|h[Refreshing Spring Water]|h|r"
@@ -739,14 +621,6 @@ mod tests {
             .eval::<bool>("return GetMerchantItemLink(9) == nil")
             .unwrap());
 
-        // **GetMerchantItemMaxStack** — the one number that decides whether a vendor click asks
-        // "how many?". The reference's `MerchantItemButton_OnClick` reads it twice
-        // (`MerchantFrame.lua:313` on the right-click arm and `:340` on shift-click) and takes the
-        // plain single-buy path whenever it is `<= 1`, opening the stack-split spinner otherwise.
-        //
-        // Nil while the row's template answer is in flight, and nil out of range — the same two
-        // absences `GetMerchantItemLink` above has, and for the same reason: the value is the
-        // template's `stackable`, which the wire has carried all along.
         assert_eq!(
             s.eval::<i64>("return GetMerchantItemMaxStack(1)").unwrap(),
             20
@@ -759,9 +633,6 @@ mod tests {
             .unwrap());
     }
 
-    /// The isUsable leg end-to-end: the gate reads the shared template store + the player req
-    /// state, so a level-short player reds the row (nil), levelling past it whitens (1), and the
-    /// same flag drives the buyback tuple.
     #[test]
     fn merchant_usable_tracks_the_item_gate() {
         use crate::script::{ItemTemplateView, PlayerReqState};
@@ -777,7 +648,7 @@ mod tests {
         }];
         s.set_merchant(Some(state));
         s.set_item_template(
-            159, // row 1: the spring water becomes level-gated for the test
+            159, // row 1, level-gated for the test
             ItemTemplateView {
                 name: "Refreshing Spring Water".into(),
                 required_level: 5,
@@ -813,11 +684,10 @@ mod tests {
                 "local n, t, p, q, a, u = GetBuybackItemInfo(1)\nreturn u == nil and n ~= nil",
             )
             .unwrap());
-        // Row 2 has no template pushed → still usable, whatever the player state.
+        // Row 2 has no template, so it is usable whatever the player state.
         assert!(s
             .eval::<bool>("local n, t, p, q, a, u = GetMerchantItemInfo(2)\nreturn u == 1")
             .unwrap());
-        // Levelling past the requirement whitens both.
         s.set_player_req_state(req(5));
         assert!(s
             .eval::<bool>("local n, t, p, q, a, u = GetMerchantItemInfo(1)\nreturn u == 1")
@@ -831,7 +701,7 @@ mod tests {
     fn merchant_stats_feed_reads_the_tooltip_head() {
         let mut s = UiScript::new().unwrap();
         let mut stock = stock();
-        // Row 1 becomes a sword so every stat column is distinguishable.
+        // A sword, so every stat column is distinct.
         stock.items[0].stats = Some(ItemStatsHead {
             quality: 2,
             inventory_type: 21,
@@ -854,7 +724,6 @@ mod tests {
         assert_eq!((quality, inv, class, sub), (2, 21, 2, 7));
         assert_eq!((dmin, dmax, dtype, delay), (5.0, 9.0, 2, 2600));
         assert_eq!((armor, block), (0, 0));
-        // In flight (row 2) and out of range: nil.
         assert!(s
             .eval::<bool>("return BenillaGetMerchantItemStats(2) == nil")
             .unwrap());
@@ -883,8 +752,6 @@ mod tests {
         assert!(!s.take_merchant_close(), "drained");
     }
 
-    /// The buyback surface: count, the ref tuple (including the 5875 binding's exact empty tuple
-    /// `(nil,nil,0,1,0,1)` for an invalid index — 0x4fb310), and the BuybackItem intent drain.
     #[test]
     fn buyback_reads_and_intents() {
         let mut s = UiScript::new().unwrap();
@@ -922,8 +789,6 @@ mod tests {
         assert!(s.take_merchant_buybacks().is_empty(), "drained");
     }
 
-    /// The repair surface: CanMerchantRepair off the snapshot, GetRepairAllCost's (cost, canRepair)
-    /// pair, the RepairAllItems intent, and the client-side repair-mode latch trio.
     #[test]
     fn repair_reads_intents_and_mode_latch() {
         let mut s = UiScript::new().unwrap();
@@ -942,7 +807,6 @@ mod tests {
         assert!(s.take_repair_all());
         assert!(!s.take_repair_all(), "drained");
 
-        // ShowRepairCursor arms, InRepairMode reads (1/nil), HideRepairCursor disarms.
         assert!(s.eval::<bool>("return InRepairMode() == nil").unwrap());
         s.run("ShowRepairCursor()").unwrap();
         assert!(s.repair_mode());
@@ -962,16 +826,11 @@ mod tests {
             .unwrap());
     }
 
-    /// The vendor-item hover cursor (`ShowMerchantSellCursor`/`ShowBuybackSellCursor`, `0x4fbab0`/
-    /// `0x4fbbb0`): Buy(3) when the player can afford the row, the grayed UnableBuy(23) when they
-    /// can't; `ShowInspectCursor` arms the magnifier; `ResetCursor` clears the whole override; an
-    /// unresolvable index (or no vendor open) leaves the cursor unchanged.
     #[test]
     fn vendor_hover_cursor_gates_on_affordability() {
         use crate::script::UiCursorMode;
         let mut s = UiScript::new().unwrap();
 
-        // No vendor open: the Show* calls resolve nothing and leave the cursor untouched.
         s.run("ShowMerchantSellCursor(1)").unwrap();
         assert_eq!(s.ui_cursor(), None);
 
@@ -983,38 +842,30 @@ mod tests {
         s.set_merchant(Some(state));
         s.set_money(100); // affords row 1 (25) + buyback (47), not row 2 (1500)
 
-        // Row 1: coin ≥ price → Buy(3).
         s.run("ShowMerchantSellCursor(1)").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::Buy));
-        // Row 2: coin < price → the grayed UnableBuy(23).
         s.run("ShowMerchantSellCursor(2)").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::UnableBuy));
 
-        // The Ctrl-hover magnifier, then ResetCursor back to the base mode.
         s.run("ShowInspectCursor()").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::Inspect));
         s.run("ResetCursor()").unwrap();
         assert_eq!(s.ui_cursor(), None);
 
-        // Buyback affords too → Buy(3).
         s.run("ShowBuybackSellCursor(1)").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::Buy));
 
-        // An out-of-range index bails without touching the armed cursor (the binary's no-CursorSetMode
-        // fail path) — the Buy from the buyback hover above survives.
+        // Out of range leaves the armed cursor as it was.
         s.run("ShowMerchantSellCursor(99)").unwrap();
         assert_eq!(s.ui_cursor(), Some(UiCursorMode::Buy));
     }
-    /// `PickupMerchantItem` is TWO verbs, and which one runs is decided by the cursor, never by
-    /// the caller — stock FrameXML never guards it (wow-re `merchant-cursor-law.md`).
     #[test]
     fn pickup_merchant_item_grabs_a_row_as_mode_5() {
         let mut s = UiScript::new().unwrap();
         s.set_merchant(Some(stock()));
 
         s.run("PickupMerchantItem(1)").unwrap();
-        // Mode 5 is INVISIBLE to Lua. This is the load-bearing assertion in the whole file: all
-        // thirteen stock `CursorHasItem()` gates stay closed while a vendor cursor is held.
+        // Mode 5 is invisible to Lua: every stock `CursorHasItem()` gate stays closed.
         assert!(
             s.eval::<bool>("return not CursorHasItem()").unwrap(),
             "CursorHasItem is nil for mode 5"
@@ -1025,15 +876,12 @@ mod tests {
             "GetCursorInfo reports nothing — no binding exposes mode 5"
         );
 
-        // …but it IS held: a second call naming the same row is the toggle-off (`0x4fb818`), and
-        // a third call re-grabs it. Nothing else can observe the difference from Lua, so the
-        // toggle is what the test reads it through.
+        // Yet it is held: a second call toggles it off (`0x4fb818`), a third re-grabs.
         s.run("PickupMerchantItem(1)").unwrap();
         s.run("PickupMerchantItem(1)").unwrap();
         assert!(s.take_merchant_slot_buys().is_empty(), "no drop yet");
     }
 
-    /// Every refusal is silent AND clears the cursor — there is no `luaL_error` in the range.
     #[test]
     fn pickup_merchant_item_refuses_silently_and_clears() {
         let mut s = UiScript::new().unwrap();
@@ -1052,11 +900,10 @@ mod tests {
                 "{bad} cleared the cursor"
             );
         }
-        // A missing argument is the same silent clear, not an error.
+        // A missing argument is the same silent clear.
         s.run("PickupMerchantItem(1)").unwrap();
         s.run("PickupMerchantItem()").unwrap();
-        // A wrapping index must not become a valid row: `2^32 + 1` narrows to 0 on a naive cast
-        // and would grab row 1. It refuses, and the cursor stays empty.
+        // `2^32 + 1` narrows to row 0 on a naive cast.
         s.run("PickupMerchantItem(4294967297)").unwrap();
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
         s.run("PickupContainerItem(0, 3)").unwrap();
@@ -1064,17 +911,12 @@ mod tests {
             s.take_merchant_slot_buys().is_empty(),
             "the wrapping index grabbed nothing"
         );
-        // A numeric STRING is accepted (`_ftol` over a converted argument), and `1.9` truncates
-        // toward zero to row 1 — not rounds to 2.
+        // A numeric string is accepted, and 1.9 truncates to the held row 1, toggling it off.
         s.run(r#"PickupMerchantItem("1")"#).unwrap();
         s.run("PickupMerchantItem(1.9)").unwrap();
-        // …which the toggle proves: 1.9 named the row 1 already held, so it toggled off.
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
     }
 
-    /// The sell arm: a bag item on the cursor makes this a sell, the index is ignored, and the
-    /// cursor empties. This is what stock `MerchantFrame.xml:743`'s `PickupMerchantItem(0)` is —
-    /// an index the grab arm would refuse outright.
     #[test]
     fn pickup_merchant_item_sells_what_the_cursor_holds() {
         use crate::script::cursor::{CursorItem, CursorPayload};
@@ -1102,7 +944,6 @@ mod tests {
         assert!(s.take_merchant_cursor_sells().is_empty(), "drained");
     }
 
-    /// The drop is the buy. A held row placed into a bag slot queues `CMSG_BUY_ITEM_IN_SLOT`.
     #[test]
     fn a_held_vendor_row_dropped_in_a_bag_is_a_buy() {
         let mut s = UiScript::new().unwrap();
@@ -1120,15 +961,15 @@ mod tests {
         );
     }
 
-    /// A stale row is a refusal, not a wrong buy. The reference has a latent null deref on two of
-    /// its three drop paths for exactly this case (a fresh `SMSG_LIST_INVENTORY` rewrites the
-    /// count without clearing the cursor); we take the third path's behaviour on all of them.
+    /// Deviation: a stale row drops without buying on all three drop paths, because two of the
+    /// reference's three dereference a null here (a fresh `SMSG_LIST_INVENTORY` rewrites the count
+    /// without clearing the cursor); we take the third path's behaviour.
     #[test]
     fn a_stale_vendor_row_drops_without_buying() {
         let mut s = UiScript::new().unwrap();
         s.set_merchant(Some(stock()));
         s.run("PickupMerchantItem(2)").unwrap();
-        // The vendor list is replaced while the cursor still holds row 2 of the old one.
+        // The list is replaced while the cursor holds row 2 of the old one.
         let mut shorter = stock();
         shorter.items.truncate(1);
         s.set_merchant(Some(shorter));
@@ -1140,17 +981,98 @@ mod tests {
         assert!(s.eval::<bool>("return GetCursorInfo() == nil").unwrap());
     }
 
-    /// A vendor cursor is not a bar action and not an equip: `PlaceAction` refuses it and hands it
-    /// back, exactly as it does the pet-action and stable-pet payloads.
     #[test]
     fn the_action_bar_refuses_a_vendor_row_and_keeps_it_held() {
         let mut s = UiScript::new().unwrap();
         s.set_merchant(Some(stock()));
         s.run("PickupMerchantItem(1)").unwrap();
         s.run("PlaceAction(1)").unwrap();
-        // Still held, proven positively: dropping it in a bag afterwards still buys. An asserted
-        // *absence* here would pass just as well if the bar had eaten the payload.
+        // Still held: dropping it in a bag afterwards buys.
         s.run("PickupContainerItem(0, 5)").unwrap();
         assert_eq!(s.take_merchant_slot_buys(), vec![(0, 5, 159)]);
     }
+
+    /// Count the cursor's three events from Lua, the way a stock handler would see them.
+    fn listen_cursor_events(s: &mut UiScript) {
+        s.run(
+            r#"
+            updates, shows, hides = 0, 0, 0
+            local f = CreateFrame("Frame", "MerchantCursorListener")
+            f:RegisterEvent("CURSOR_UPDATE")
+            f:RegisterEvent("ACTIONBAR_SHOWGRID")
+            f:RegisterEvent("ACTIONBAR_HIDEGRID")
+            f:SetScript("OnEvent", function()
+                if event == "CURSOR_UPDATE" then updates = updates + 1 end
+                if event == "ACTIONBAR_SHOWGRID" then shows = shows + 1 end
+                if event == "ACTIONBAR_HIDEGRID" then hides = hides + 1 end
+            end)
+            "#,
+        )
+        .unwrap();
+    }
+
+    /// `(CURSOR_UPDATE, ACTIONBAR_SHOWGRID, ACTIONBAR_HIDEGRID)` delivered so far.
+    fn cursor_event_counts(s: &mut UiScript) -> (i64, i64, i64) {
+        s.tick(0.01);
+        let n = |g: &str| s.eval::<i64>(&format!("return {g}")).unwrap();
+        (n("updates"), n("shows"), n("hides"))
+    }
+
+    /// The grab goes through the cursor setter (`0x4950f0`): `CURSOR_UPDATE` at `0x495159`, and
+    /// no `ACTIONBAR_SHOWGRID` since mode 5 is not mode 7.
+    #[test]
+    fn a_vendor_grab_fires_cursor_update_but_not_the_bar_grid() {
+        let mut s = UiScript::new().unwrap();
+        s.set_merchant(Some(stock()));
+        listen_cursor_events(&mut s);
+        s.run("PickupMerchantItem(1)").unwrap();
+        assert_eq!(
+            cursor_event_counts(&mut s),
+            (1, 0, 0),
+            "(CURSOR_UPDATE, ACTIONBAR_SHOWGRID, ACTIONBAR_HIDEGRID) after a vendor grab"
+        );
+        // The toggle-off is a plain clear: one more CURSOR_UPDATE, no HIDEGRID.
+        s.run("PickupMerchantItem(1)").unwrap();
+        assert_eq!(cursor_event_counts(&mut s), (2, 0, 0));
+    }
+
+    #[test]
+    fn a_spell_dropped_on_the_vendor_is_a_real_clear() {
+        use crate::script::cursor::{self, CursorPayload, CursorSpell};
+        let mut s = UiScript::new().unwrap();
+        s.set_merchant(Some(stock()));
+        listen_cursor_events(&mut s);
+        s.set_cursor_for_test(CursorPayload::Spell(CursorSpell {
+            book_slot: 1,
+            book_type: "spell".into(),
+            spell_id: 133,
+            texture: None,
+            passive: false,
+        }));
+        cursor::queue_cursor_update(&mut s.model_mut()); // the pickup's own transition
+        assert_eq!(cursor_event_counts(&mut s), (1, 1, 0), "the spell pickup");
+
+        s.run("PickupMerchantItem(0)").unwrap();
+        assert!(s.cursor_payload().is_none());
+        assert_eq!(
+            cursor_event_counts(&mut s),
+            (2, 1, 1),
+            "(CURSOR_UPDATE, ACTIONBAR_SHOWGRID, ACTIONBAR_HIDEGRID) after the vendor drop"
+        );
+    }
+
+    /// `ClearCursor 0x495190` opens with the gift-wrap cancel (`0x5edf10`), and the grab opens
+    /// with that clear (`0x49510b`).
+    #[test]
+    fn a_vendor_grab_cancels_an_armed_gift_wrap() {
+        let mut s = UiScript::new().unwrap();
+        s.set_merchant(Some(stock()));
+        s.arm_gift_wrap(0, 1);
+        s.run("PickupMerchantItem(1)").unwrap();
+        assert_eq!(
+            s.gift_wrap_armed(),
+            None,
+            "the grab's ClearCursor cancels the wrap"
+        );
+    }
 }
diff --git a/crates/benilla-ui/src/script/messageframe/mod.rs b/crates/benilla-ui/src/script/messageframe/mod.rs
index 12877d8f..f23c9419 100644
--- a/crates/benilla-ui/src/script/messageframe/mod.rs
+++ b/crates/benilla-ui/src/script/messageframe/mod.rs
@@ -1,23 +1,12 @@
-//! The two message-frame widget classes, and the display machinery they share.
+//! The two message-frame classes and the display code they share. In 1.12 they are siblings, not
+//! parent and child, each with its own method table, so a method only one carries is nil on the
+//! other:
 //!
-//! 1.12 ships **two** of them, and msgframe-runtime.md is emphatic that they are *siblings, not
-//! parent and child* (different ctors, different vtables, different Lua type tags, offsets that do
-//! not transfer):
+//! - [`scrolling`]: `CSimpleMessageScrollFrame` (ctor `0x787670`), the chat window's class.
+//! - [`plain`]: `CSimpleMessageFrame` (ctor `0x785640`), `UIErrorsFrame`'s class.
 //!
-//! - [`scrolling`] — `CSimpleMessageScrollFrame` (ctor `0x787670`), the chat window's class: a true
-//!   ring of `maxLines`, a scrollback cursor, `AddMessage(text[,r,g,b[,id]])` with alpha forced
-//!   opaque.
-//! - [`plain`] — `CSimpleMessageFrame` (ctor `0x785640`), `UIErrorsFrame`'s class: no ring, no
-//!   scrollback, `insertMode`, and `AddMessage(text[,r,g,b[,a]])` whose fourth numeric is a real
-//!   **alpha**.
-//!
-//! Each gets its **own** Lua method table, consulted by the frame `__index` dispatcher only for its
-//! own [`FrameKind`](crate::widget::FrameKind) — so a duck-typing addon (`if f.SetInsertMode then`)
-//! sees `nil` everywhere else, exactly as against the client's per-class registrar tables.
-//!
-//! What *is* shared sits here: both classes display a stack of [`MessageLine`] records, so the
-//! wrapped-row measure round-trip, the band emit, and the font/justification read are one code path
-//! over [`KindState::message_lines`]. Everything that actually differs stays on the two states.
+//! Both display a stack of [`MessageLine`] records, so the row measure, the band emit and the font
+//! read are shared here.
 
 use crate::layout::Rect;
 use crate::order::ZTarget;
@@ -35,63 +24,20 @@ mod scrolling;
 pub(super) use plain::REG_MESSAGEFRAME_METHODS;
 pub(super) use scrolling::REG_SCROLLINGMESSAGEFRAME_METHODS;
 
-/// Install both classes' method tables (and the chat input globals the scrolling one carries).
-/// **`AddMessage`'s text argument, and the three ways it silently swallows the whole call**
-/// (wow-5875-re `system/ui/scratch/addmessage-text-gate-silent-skip.md`, 4-worker cross-check
-/// 2026-08-31). `None` means *do nothing at all* — no line, no record, no error.
-///
-/// `CSimpleMessageFrame::AddMessage 0x795590` fetches Lua index 2 through `lua_isstring 0x6f3510`
-/// and then `lua_tostring 0x6f3690`, and **three** results jump to the function's own epilogue at
-/// `0x79582b` (`pop edi / pop esi / xor eax,eax / pop ebx / leave / ret` — zero Lua values, no
-/// push, and the virtual enqueue at `0x795825 call [eax+0x90]` never reached):
-///
-/// ```text
-///   79561b  mov edx,2
-///   795625  call 0x6f3510      ; lua_isstring — tags 4 (string) and 3 (number) only
-///   79562c  je   0x79582b      ; nil / boolean / table / function  -> silent
-///   795642  je   0x79582b      ; lua_tostring returned NULL        -> silent
-///   79564b  je   0x79582b      ; cmp byte ptr [ebx],0 — EMPTY string -> silent
-/// ```
-///
-/// `ScrollingMessageFrame:AddMessage 0x792900` is the same shape (gate `0x79299c`, `je 0x792b81` =
-/// its own epilogue), so `DEFAULT_CHAT_FRAME:AddMessage(nil)` is silent too.
-///
-/// **This is not a general argument law and must not be read as one** (1717's rule: the shape is
-/// settled per binding). The *colour* arguments beside it behave the opposite way — a bad `r`/`g`/
-/// `b`/`a` jumps to `0x79581c`, which still calls the enqueue with the `0xffffffff` opaque white
-/// staged at `0x795658`. Only a bad **text** shows nothing. The three *receiver* guards
-/// (`0x847ef8` "used '.' instead of ':'", `0x847ec0`, `0x847e98`) do still raise, and they are
-/// upstream of this.
-///
-/// **Why it is load-bearing rather than pedantry.** Stock FrameXML takes this path: 1.12's
-/// `ContainerFrame.lua:753` reports a full keyring with
-/// `UIErrorsFrame:AddMessage(NO_EMPTY_KEYRING_SLOTS, 1.0, 0.1, 0.1, 1.0)` and **no such
-/// GlobalString exists** — the shipped `GlobalStrings.lua` defines only
-/// `NO_EMPTY_KEYRING_SLOTS_ERROR`, a rename that updated the definition and not the use. So a
-/// player dropping a key onto a full keyring gets a dead click on a real client. Taking a `String`
-/// here (which is what this did until 1751's fourth window swapped the bag bar in) raised instead,
-/// putting a script-error dialog on an ordinary player gesture that the reference never shows.
-///
-/// A **number** is accepted and rendered as its decimal text — `0x6f7c80` retags the slot in
-/// place — which is exactly [`super::binding_abi::optional_string`]'s coercion.
+/// `AddMessage`'s text; `None` means the whole call does nothing, no line and no error. Both
+/// bindings (`0x795590`, `0x792900`) jump to their epilogue (`0x79582b`, `0x792b81`) when
+/// `lua_isstring` (`0x6f3510`) fails, `lua_tostring` (`0x6f3690`) gives NULL or the string is empty
+/// (`0x79564b`). Stock `ContainerFrame.lua:753` passes the undefined `NO_EMPTY_KEYRING_SLOTS` on a
+/// full keyring and gets a silent click. Only the text is gated so: a bad colour still adds the
+/// line in white (`0x79581c`), and the receiver checks (`0x847ef8`) still raise. A number becomes
+/// its decimal text (`0x6f7c80`).
 pub(super) fn message_text(lua: &mlua::Lua, v: &mlua::Value) -> Option<String> {
     super::binding_abi::optional_string(lua, v).filter(|s| !s.is_empty())
 }
 
-/// Install `SetJustifyH`/`GetJustifyH`/`SetJustifyV`/`GetJustifyV` on a message-frame method
-/// table. Both classes carry all four (see [`crate::widget::ScrollingMessageState::justify`] for
-/// the method-table bytes that settled it), and the law they obey is
-/// [`crate::justify`]'s — shared with FontString, `<Font>` and EditBox since 1237, so the two
-/// verified traps cannot drift apart per widget:
-///
-///  · an **unrecognised token RAISES** `Usage: %s:SetJustifyH("justify")` rather than defaulting;
-///  · a token from the **other axis** parses and then masks to nothing — `SetJustifyH("TOP")`
-///    CLEARS the horizontal axis, and `GetJustifyH()` answers `"UNKNOWN"` while the glyphs keep
-///    drawing at the paint fallback.
-///
-/// `GetJustify*` reports the EFFECTIVE value — the frame's own once set, else the font object's —
-/// so an untouched frame answers what it actually draws with rather than a ctor constant its
-/// `<FontString>` may have overridden.
+/// Install `SetJustifyH`, `GetJustifyH`, `SetJustifyV` and `GetJustifyV`, which both classes carry,
+/// under [`crate::justify`]'s rules: an unknown token raises the usage line, and a token of the
+/// other axis clears this one, so `GetJustifyH()` then answers `"UNKNOWN"`.
 use crate::script::object::frame_handle_of;
 
 pub(super) fn install_justify(
@@ -148,13 +94,8 @@ pub(super) fn install_justify(
         )?;
     }
 
-    // The two getters differ ONLY in what an untouched frame falls back to, and the asymmetry is
-    // real rather than an oversight: horizontally there IS another source — the font object the
-    // lines actually draw with — so reporting anything else would have `GetJustifyH` disagree with
-    // the glyphs on our own chat window, which declares `justifyH="LEFT"` on its `<FontString>`.
-    // Vertically there is no such source: `emit_message_lines` pins each line to the top of its own
-    // band deliberately (the band, not a FontString rect, owns the vertical rhythm), so an untouched
-    // frame reports the ctor default rather than a value invented from our band math.
+    // On an untouched frame `GetJustifyH` answers its font's `justifyH`, what the lines draw with,
+    // and `GetJustifyV` the ctor default, as each line sits at the top of its own band.
     m.set(
         "GetJustifyH",
         lua.create_function(move |lua, this: mlua::Table| {
@@ -191,39 +132,21 @@ pub(super) fn install(lua: &mlua::Lua) -> mlua::Result<()> {
     plain::install(lua)
 }
 
-/// The font a message frame's lines draw with — its declared `<FontString>` child, which is exactly
-/// how both reference frames spell it (`<FontString inherits="ChatFontNormal" justifyH="LEFT"/>` on
-/// a chat frame, `<FontString inherits="ErrorFont" justifyH="CENTER"/>` on `UIErrorsFrame.xml`).
-/// Shared by the emit and the measure round-trip so bands, measures and glyphs agree. Missing ⇒ the
-/// renderer's default face at the ~14px chat default.
+/// The font a message frame's lines draw with: its declared `<FontString>` child, as the stock
+/// chat frames and `UIErrorsFrame.xml` declare it, else the default face at 14 px.
 #[derive(Clone)]
 pub(super) struct MessageFont {
     pub(super) path: Option<String>,
     pub(super) height: Option<f32>,
     pub(super) shadow: Option<FontShadow>,
     pub(super) outline: Outline,
-    /// The child's `justifyH`. **Load-bearing, not decoration**: it is the only reason the
-    /// reference's error toasts sit centred in their 512-wide frame while chat lines run flush
-    /// left, and the class draws its lines through that font instance. A frame with no declared
-    /// FontString falls back to LEFT (the chat shape), never to the FontString default of CENTER —
-    /// there is no region here whose own default could apply.
+    /// The child's `justifyH`, which centres `UIErrorsFrame`'s lines and keeps chat flush left;
+    /// LEFT without a declared FontString, not the FontString default of CENTER.
     pub(super) justify_h: JustifyH,
 }
 
-/// The FontString region a message frame's **style** lives on — found, or created on demand.
-///
-/// Both classes draw their lines through one font instance, and [`UiScript::message_frame_font`]
-/// reads it off the frame's first `FontString` region. That region normally comes from the
-/// declared direct-child `<FontString>` (LoadXML's "special" font string — our ChatFrame has one).
-/// A frame built by `CreateFrame("MessageFrame")` has none, so the ten shared font-block verbs
-/// need somewhere to write: this is that somewhere, and it is created **only** when one of them is
-/// actually called, so a frame nobody styles never grows a region.
-///
-/// **It is seated LEFT deliberately.** A frame with no declared FontString falls back to LEFT (the
-/// chat shape) per [`MessageFont::justify_h`]'s law — but a freshly created `RegionData` defaults
-/// to the *FontString* default of CENTER. Creating the region at the default would silently
-/// re-justify a frame the moment an addon touched its font, which is a visible change nobody
-/// asked for.
+/// The FontString region holding a message frame's font, made on the first font-block call when
+/// the frame declared none. It is made LEFT, not CENTER, so styling a frame never re-justifies it.
 pub(super) fn ensure_font_region(
     lua: &mlua::Lua,
     fh: FrameHandle,
@@ -290,11 +213,8 @@ impl UiScript {
             })
     }
 
-    /// How many display **rows** frame `fh`'s resolved rect holds at its line font's pitch — the
-    /// client's layout-derived `numLinesDisplayed`. `0` when the frame has no resolved rect.
-    ///
-    /// Both classes need it and neither can compute it from its own state: it is the page size for
-    /// the scrolling class's `PageUp`/`PageDown` and the whole capacity law for the plain one.
+    /// How many rows frame `fh`'s resolved rect holds at its font's pitch, the client's
+    /// `numLinesDisplayed`: the scrolling class's page size and the plain class's capacity.
     pub(super) fn message_viewport_rows(model: &Model, fh: FrameHandle) -> usize {
         let pitch = Self::message_frame_font(model, fh)
             .height
@@ -305,16 +225,12 @@ impl UiScript {
         })
     }
 
-    /// Message lines whose wrapped **row count** needs a host measurement (a new line, or the
-    /// frame's width/font changed under it) — the message-frame half of the measure round-trip.
-    /// Call after [`UiScript::resolve`] (widths must be resolved); answer with
-    /// [`UiScript::set_message_line_rows`] before extract. Cache keys keep this empty on quiet
-    /// frames.
+    /// Message lines whose wrapped row count needs a host measure. Call after
+    /// [`UiScript::resolve`]; answer with [`UiScript::set_message_line_rows`] before extract.
     pub fn message_lines_needing_measure(&mut self) -> Vec<LineMeasureRequest> {
         use std::hash::{Hash, Hasher};
         let mut model = self.model_mut();
-        // A plain reborrow so the arena borrow inside the loop and the sweep-token field writes
-        // split by FIELD instead of fighting over the RefMut.
+        // A plain reborrow, so the arena reads and the sweep-token writes borrow disjoint fields.
         let model = &mut *model;
         let mut out = Vec::new();
         let frames: Vec<(FrameHandle, Rect)> = model
@@ -331,7 +247,7 @@ impl UiScript {
         for (fh, fr) in frames {
             let wrap_width = fr.right - fr.left;
             if wrap_width <= 1.0 {
-                continue; // unresolved/degenerate width — nothing meaningful to wrap against
+                continue; // no width to wrap against
             }
             let scale = model
                 .arena
@@ -346,13 +262,9 @@ impl UiScript {
             let Some(lines) = frame.kind_state.message_lines() else {
                 continue;
             };
-            // The skip token (the W4 fix, 1410's lane one door over): a frame whose line set
-            // (lines_gen) and measure environment (font/wrap/scale/outline) both match its last
-            // CLEAN sweep can produce nothing — every line's rows_key was minted under exactly
-            // these inputs and matched then. Environment changes (a resize, a font swap, a
-            // SetScale) miss the env hash; text changes miss the generation. The token is only
-            // stored by a zero-request sweep (below), so an unanswered request keeps
-            // re-requesting — the same rule the region ledger runs under.
+            // Skip a frame whose line generation and measure environment match its last clean
+            // sweep. Only a sweep with no requests stores the token, so an unanswered request
+            // keeps re-requesting.
             let lines_gen = frame.kind_state.lines_gen().unwrap_or(0);
             let env = {
                 use std::hash::{Hash, Hasher};
@@ -402,9 +314,8 @@ impl UiScript {
         out
     }
 
-    /// Store host row-count answers for [`LineMeasureRequest`]s (`(frame, index, rows, key)` —
-    /// frame/index/key verbatim from the request). The key is stored beside the rows, so a line
-    /// whose width/font changed again since the request simply re-requests next frame.
+    /// Store host row counts, `(frame, index, rows, key)` echoed from each [`LineMeasureRequest`].
+    /// The key is stored beside the rows, so a line that changed since its request re-requests.
     pub fn set_message_line_rows(&mut self, rows: &[(u32, u32, u16, u64)]) {
         let mut model = self.model_mut();
         for &(frame_id, index, n, key) in rows {
@@ -424,31 +335,14 @@ impl UiScript {
         }
     }
 
-    /// Push one [`QuadContent::Text`] per visible message of either message-frame class (no-op for
-    /// any other kind). Each message occupies `rows × pitch` (its host-measured wrapped row count —
-    /// the message-line measure round-trip), so a long line pushes its neighbours by its real
-    /// height. The pitch is the **font height itself** — the client's own line-step law
-    /// (`LayoutLines` 0x5cdc20: step = px(size) + spacing, spacing 0), the same law the app's text
-    /// renderer lays wrapped rows at, so band grid and glyph rows coincide by construction. (The
-    /// msgframe's own relayout `0x788750/0x788c00` is only partially read in wow-re — if the look
-    /// pass ever shows the ref spacing chat lines wider than the font height, that residual is the
-    /// place to pin.)
-    ///
-    /// **Which edge the stack grows from is the one place the two classes diverge visibly.** A
-    /// ScrollingMessageFrame always stacks bottom-up with `scroll_offset` picking which message
-    /// sits on the bottom row. A MessageFrame has no scrollback and instead honours `insertMode`:
-    /// BOTTOM (the ctor default) is the same bottom-up stack, TOP hangs the newest message off the
-    /// frame's top edge with older ones stepping *down* — the shape `UIErrorsFrame.xml:4` asks for,
-    /// and the one every corpus `SetInsertMode` caller asks for. The growth *anchor* per mode is
-    /// wow-re's own named residual (it lives in the unwalked wrap/layout pass), so this is the
-    /// INFERRED half: it is the reading that reproduces both shipped usages, and the place to
-    /// re-pin if a reference A/B ever disagrees.
-    ///
-    /// A message that only partially fits at the far edge still draws — clipped to the frame rect,
-    /// so its inner wrapped rows show, never inking outside the frame. A fully-faded scrolling line
-    /// draws nothing but still holds its rows (the reference's chat never re-packs as old lines
-    /// fade); a faded MessageFrame line is gone from the state entirely by then, because that class
-    /// frees its lines instead of holding slots.
+    /// Push one [`QuadContent::Text`] per visible message of either class, each `rows × pitch`
+    /// tall. The pitch is the font height, the client's line step (`LayoutLines` `0x5cdc20`: size
+    /// plus a spacing of 0); the message frame's own relayout (`0x788750`, `0x788c00`) is not fully
+    /// traced. A scrolling frame stacks up from the bottom, `scroll_offset` choosing the bottom
+    /// message. A MessageFrame does too for `insertMode` BOTTOM, and for TOP hangs the newest off
+    /// the top edge (`UIErrorsFrame.xml:4`); the reference's anchor per mode is untraced, and this
+    /// reading reproduces both stock uses. A message that partly fits draws clipped; a faded
+    /// scrolling line keeps its rows, as the reference never re-packs chat.
     pub(super) fn emit_message_lines(
         model: &Model,
         fh: FrameHandle,
@@ -485,23 +379,20 @@ impl UiScript {
             KindState::Message(s) => s.justify,
             _ => None,
         };
-        // The band grid lives in the frame's RESOLVED (scale-multiplied) rect, so the row pitch
-        // rides the frame scale exactly like the glyphs it must coincide with (the font height
-        // itself is frame-local).
+        // The resolved rect is scaled and the font height is frame-local, so the pitch scales.
         let pitch = font.height.unwrap_or(14.0) * paint.scale;
         if pitch <= 0.0 || fr.top <= fr.bottom {
             return;
         }
-        // Message text never inks outside its frame: a partially-fitting outermost message is
-        // scissored at the frame edge (intersected with any ScrollFrame ancestor clip).
+        // Clip to the frame, intersected with any ScrollFrame ancestor's clip.
         let line_clip = Some(match clip {
             Some(c) => super::clip::intersect_rect(c, fr),
             None => fr,
         });
-        let mut used = 0.0f32; // rows already consumed, in px in from the anchored edge
+        let mut used = 0.0f32; // px used from the anchored edge
         for idx in (0..=top_index).rev() {
             if used >= fr.top - fr.bottom {
-                break; // the next band would start outside the frame — nothing more can show
+                break; // the next band starts outside the frame
             }
             let line = &lines[idx];
             let band_h = f32::from(line.rows.max(1)) * pitch;
@@ -512,7 +403,7 @@ impl UiScript {
             };
             used += band_h;
             if line.alpha <= 0.0 {
-                continue; // fully faded — holds its place, draws nothing
+                continue; // faded: holds its rows, draws nothing
             }
             out.push(ExtractedQuad {
                 target: ZTarget::Frame(fh),
@@ -528,27 +419,21 @@ impl UiScript {
                         f32::from(line.color[2]) / 255.0,
                         line.alpha,
                     ]),
-                    // The frame's own justify wins once SetJustifyH has been called; until then
-                    // the font object's governs, which is what `justifyH=` on the frame's
-                    // `<FontString>` set and what this drew with before the verbs existed.
+                    // The frame's own justify once set, else its font's.
                     justify_h: match own_justify {
                         Some(j) => j.paint_h(),
                         None => font.justify_h,
                     },
-                    // The band is our own per-message construct (rows × pitch tall, not a
-                    // FontString rect) — keep the block at its top so the band math, not MIDDLE
-                    // centering, owns the vertical rhythm; the band height equals the wrapped
-                    // block height exactly, so Top means "fills the band".
+                    // The band is exactly the wrapped block's height, so Top fills it.
                     justify_v: JustifyV::Top,
                     font: font.path.clone(),
-                    // The font object's own drop shadow (ChatFontNormal's `(1,-1)` black) — what
-                    // makes the lines read against the world behind the transparent frame.
+                    // The font's own shadow, ChatFontNormal's black at `(1,-1)`.
                     shadow: font.shadow,
                     font_height: font.height,
-                    text_height: None, // message lines are never SetTextHeight'd
+                    text_height: None, // message lines have no SetTextHeight
                     outline: font.outline,
                     alpha_gradient: None,
-                    world_seat: false, // a chat frame is interface, on the interface's grid
+                    world_seat: false, // interface, not world
                 },
                 scale: paint.scale,
             });
diff --git a/crates/benilla-ui/src/script/messageframe/plain.rs b/crates/benilla-ui/src/script/messageframe/plain.rs
index 1b12f646..dac122a5 100644
--- a/crates/benilla-ui/src/script/messageframe/plain.rs
+++ b/crates/benilla-ui/src/script/messageframe/plain.rs
@@ -1,26 +1,9 @@
-//! The `MessageFrame` method surface — `CSimpleMessageFrame` (ctor `0x785640`), the class
-//! `UIErrorsFrame` is and the one `CreateFrame("MessageFrame")` makes.
-//!
-//! Grounded in wow-re's byte-verified reads (msgframe-runtime.md's §5 pair, re-confirmed at the
-//! registrar tables in `widget-api-batch-benilla.md` Q4). Three facts decide this whole file, and
-//! each is one an implementation would otherwise get wrong in a way nothing would catch:
-//!
-//! 1. **`AddMessage(text [, r, g, b [, a]])` — the fifth argument is ALPHA and there is no sixth.**
-//!    Three corpus addons pass six (`EasyCopy.lua:12`, `QuestHistory.lua:1678`, `QuestItem.lua:300`,
-//!    all `UIErrorsFrame:AddMessage(msg, r, g, b, a, holdTime)`), and the real 1.12.1 binding
-//!    `0x795590` reads five and stops. Honouring that trailing number as a per-message hold time
-//!    would be **unfaithful, not generous** — the client shows the message for the *frame's*
-//!    `displayDuration` and nothing else. It is ignored here, deliberately.
-//! 2. **This `AddMessage` is not the scrolling class's.** `0x792900` takes an **id** in the same
-//!    slot and forces alpha `0xFF` (`792add: or edi,0xffffff00`); `0x795590` packs a real
-//!    `0xAARRGGBB` with a default of 1.0. Two bindings, two tables, no sharing.
-//! 3. **`SetInsertMode`/`GetInsertMode` (`0x794ed0`/`0x794ff0`) live on this class only** — the
-//!    scrolling class has neither, and no `insertMode` XML attribute either.
-//!
-//! The state (display lines, fade phases, the vertical cap) is
-//! [`MessageFrameState`](crate::widget::MessageFrameState) in `crate::widget`; this is the thin Lua
-//! binding over it. The band emit and the wrapped-row measure round-trip are shared with the
-//! scrolling class and live in [`super`].
+//! The `MessageFrame` methods over [`MessageFrameState`](crate::widget::MessageFrameState):
+//! `CSimpleMessageFrame` (ctor `0x785640`), `UIErrorsFrame`'s class and what
+//! `CreateFrame("MessageFrame")` makes. Its `AddMessage(text [, r, g, b [, a]])` (`0x795590`) takes
+//! a real alpha and reads nothing after it, where the scrolling class's (`0x792900`) takes an id
+//! there and forces alpha opaque. `SetInsertMode` and `GetInsertMode` (`0x794ed0`, `0x794ff0`)
+//! exist on this class only.
 
 use mlua::{Lua, Table, Value};
 
@@ -28,13 +11,11 @@ use crate::script::object::frame_handle_of;
 use crate::script::Model;
 use crate::widget::{InsertMode, KindState, MessageFrameState};
 
-/// Registry key of the MessageFrame method table (the MAXCSTACK discipline: Lua-side root, named
-/// key).
+/// Registry key of the MessageFrame method table (the MAXCSTACK discipline).
 pub(crate) const REG_MESSAGEFRAME_METHODS: &str = "__benilla_plain_messageframe_methods";
 
-/// Run `f` over a frame's MessageFrame state under one short write borrow. Errors if `this` is not
-/// a live MessageFrame (unreachable through the kind dispatcher, but the method table is a plain
-/// Lua value — a caller could fish it out and misapply it).
+/// Run `f` over a MessageFrame's state under one short borrow; any other frame, reachable only
+/// through a misapplied method table, is an error.
 fn with_mf<T>(
     lua: &Lua,
     this: &Table,
@@ -52,7 +33,7 @@ fn with_mf<T>(
     }
 }
 
-/// A Lua number-ish → f32 (nil/other → 0.0), for the colour args.
+/// A colour argument as f32, 0 for anything but a number.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -64,30 +45,14 @@ fn num_f32(v: &Value) -> f32 {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // The justify quartet, shared with the sibling class — see [`super::install_justify`] for the
-    // method-table bytes that put all four on BOTH tables.
+    // The justify quartet, on both classes ([`super::install_justify`]).
     super::install_justify(lua, &m, "MessageFrame")?;
 
-    // AddMessage(text [, r, g, b [, a]]) — binding 0x795590.
-    //
-    // The TEXT is `super::message_text` — an `lua_isstring` gate whose failure is a silent jump to
-    // this function's own epilogue, not a raise, and the same for a NULL coercion and for the
-    // empty string. Its doc carries the bytes and the reason it matters; the short version is that
-    // stock `ContainerFrame.lua` really does reach `AddMessage(nil, …)` on a full keyring, and
-    // taking a `String` here (which this did until 1751's fourth window) put a script-error dialog
-    // on a gesture the reference answers with a dead click.
-    //
-    // r/g/b are required **as a trio** (three presence checks ANDed at 0x7956xx); absent ⇒ hard
-    // 0xFFFFFFFF white. The fourth numeric is a real alpha, `lua_isnumber`-gated with a default of
-    // 1.0 (`795752: mov [ebp-0x18],0x3f800000`). **Deliberately NOT the same shape as the text:** a
-    // bad colour jumps to `0x79581c`, which still enqueues the line in opaque white. Only a bad
-    // text shows nothing.
-    //
-    // **The signature stops there, and the closure's arity is the enforcement.** The corpus's three
-    // blocked callers all pass a sixth argument they believe is a hold time; mlua hands us the
-    // first five and drops the rest, exactly as the real binding does by reading five stack slots.
-    // Adding a `holdTime` parameter here would make benilla show those messages for a duration no
-    // 1.12 client ever showed them for.
+    // AddMessage(text [, r, g, b [, a]]) (`0x795590`). An unusable text is a silent no-op
+    // ([`super::message_text`]). r, g and b count only as a trio, else white, and a bad colour
+    // still adds the line in white (`0x79581c`); the alpha defaults to 1.0 (`0x795752`). The
+    // closure's arity drops a sixth argument, as the binding reads five: addons that pass a hold
+    // time there get the frame's `displayDuration`, as on the reference.
     m.set(
         "AddMessage",
         lua.create_function(
@@ -104,9 +69,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 } else {
                     (1.0, 1.0, 1.0)
                 };
-                // Alpha only counts when rgb came with it — the client reads arg 5 off the same
-                // parse that required the trio, and a lone `AddMessage(text, nil, nil, nil, 0.5)`
-                // has no colour to apply it to.
+                // The alpha counts only with the trio, read in the same parse.
                 let a = match (&a, has_rgb) {
                     (Value::Number(_) | Value::Integer(_), true) => num_f32(&a),
                     _ => 1.0,
@@ -121,9 +84,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| with_mf(lua, &this, MessageFrameState::clear))?,
     )?;
 
-    // SetInsertMode("TOP"|"BOTTOM") / GetInsertMode — 0x794ed0 / 0x794ff0, THIS CLASS ONLY. The
-    // client compares the string against "BOTTOM" (0x871404) and stores `streq-BOTTOM`, so anything
-    // that is not literally BOTTOM lands on TOP; the ctor default is 1 = BOTTOM.
+    // SetInsertMode (`0x794ed0`) compares against "BOTTOM" (`0x871404`), so anything else is
+    // TOP; the ctor default is BOTTOM.
     m.set(
         "SetInsertMode",
         lua.create_function(|lua, (this, mode): (Table, Value)| {
@@ -135,8 +97,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         InsertMode::Top
                     }
                 }
-                // A non-string argument fails the streq and therefore reads as TOP, like the
-                // client's own comparison against a string it never got.
+                // A non-string fails the compare too.
                 _ => InsertMode::Top,
             };
             with_mf(lua, &this, |mf| mf.insert_mode = mode)
@@ -152,8 +113,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The fade trio — the same names and the same field the scrolling class exposes (the XML attr
-    // is `displayDuration`, the Lua accessors call it `TimeVisible`), over this class's own state.
+    // The fade accessors, as on the scrolling class; XML's `displayDuration` is `TimeVisible`.
     m.set(
         "SetFading",
         lua.create_function(|lua, (this, on): (Table, Value)| {
@@ -161,8 +121,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             with_mf(lua, &this, |mf| mf.fading_enabled = on)
         })?,
     )?;
-    // 1/nil, the reference's predicate shape — `binding-shapes.tsv` has this row as
-    // `(nil) | (number)`, like every other 1.12 predicate (decision 2118).
+    // 1 or nil, the 1.12 predicate shape (`0x795170`).
     m.set(
         "GetFading",
         lua.create_function(|lua, this: Table| {
@@ -193,18 +152,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── the shared font block ───────────────────────────────────────────────────────────────
-    //
-    // `Set/GetFontObject · Set/GetFont · Set/GetTextColor · Set/GetShadowColor ·
-    // Set/GetShadowOffset` are real entries on this class's table, not a courtesy. wow-re's
-    // registrar carve is explicit about the membership — *"Exposed on: FontString, Font object,
-    // EditBox, MessageFrame, ScrollingMessageFrame, SimpleHTML. NOT on Button"* — and names this
-    // class's own shims calling the shared implementations (`GetShadowColor 0x794810`). All six
-    // carry the block now — `SimpleHTML`'s is its own copy rather than `font_block::install`'s
-    // (`script/simplehtml/mod.rs`), because that class computes its own inter-block step.
-    //
-    // Demand is observed, not counted: `BigWigs/Plugins/Messages.lua:212` is
-    // `self.msgframe:SetFontObject(GameFontNormalLarge)` on a frame it has just given
-    // `SetInsertMode("TOP")`, and BigWigs dies there every session.
+    // The ten font verbs are on this class's own table (`GetShadowColor` `0x794810`), as on
+    // FontString, Font, EditBox, ScrollingMessageFrame and SimpleHTML; Button's (`0x879d00`) has
+    // none.
     crate::script::font_block::install(
         lua,
         &m,
@@ -224,10 +174,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// How many display lines a named message frame holds. Read off the state rather than through
-    /// Lua on purpose: `GetNumMessages` is a **ScrollingMessageFrame** binding, and inventing one
-    /// on this class to make its tests convenient is exactly the drift these tests are pinning
-    /// against.
+    /// A named frame's line count, off the state: `GetNumMessages` is not a MessageFrame method.
     fn num_messages(s: &UiScript, name: &str) -> usize {
         let m = s.model_ref();
         let h = m.arena.lookup(name).expect("named frame");
@@ -237,23 +184,18 @@ mod tests {
             .map_or(0, |l| l.len())
     }
 
-    /// The whole point of the arity, pinned: the sixth argument three corpus addons pass is a hold
-    /// time the real client never had, and it must change **nothing**. The frame's own
-    /// `displayDuration` is what governs, so the message with a "hold time" of 999 fades on exactly
-    /// the same tick as the one without.
+    /// A sixth argument, which some addons pass as a hold time, changes nothing.
     #[test]
     fn the_sixth_addmessage_argument_is_ignored_not_a_holdtime() {
         let mut s = UiScript::new().unwrap();
         s.run("CreateFrame('MessageFrame', 'MF')").unwrap();
         s.run("MF:SetTimeVisible(1)").unwrap();
         s.run("MF:SetFadeDuration(0)").unwrap();
-        // The exact shape of EasyCopy.lua:12 / QuestItem.lua:300 / QuestHistory.lua:1678.
         s.run("MF:AddMessage('held', 1.0, 1.0, 1.0, 1.0, 999)")
             .unwrap();
         s.run("MF:AddMessage('plain', 1.0, 1.0, 1.0, 1.0)").unwrap();
         assert_eq!(num_messages(&s, "MF"), 2);
-        // Past timeVisible with no ramp: both retire together. A honoured holdTime would keep the
-        // first alive here, which is exactly the divergence this test exists to catch.
+        // Past timeVisible with no ramp, both retire together.
         s.tick(1.1);
         s.tick(0.1);
         assert_eq!(
@@ -263,31 +205,19 @@ mod tests {
         );
     }
 
-    /// **A text `AddMessage` cannot use is swallowed whole — silently, with nothing added and
-    /// nothing raised** (`0x795590`'s three jumps to its own epilogue; see [`super::super`]'s
-    /// `message_text`).
-    ///
-    /// The defect this pins is not hypothetical and not ours to have guessed at: our binding took
-    /// its text as an mlua `String`, which raises on nil, and 1.12's own `ContainerFrame.lua:753`
-    /// reports a full keyring through `UIErrorsFrame:AddMessage(NO_EMPTY_KEYRING_SLOTS, …)` — a
-    /// GlobalString the shipped `GlobalStrings.lua` never defines. So dropping a key onto a full
-    /// keyring put a script-error dialog on screen where the reference gives a dead click. It
-    /// surfaced the moment 1751's third window made the bag bar the reference's own file.
-    ///
-    /// The three silent cases and the two that are NOT silent are pinned together, because the
-    /// pair is the finding: a bad **colour** still adds the line (opaque white), and the receiver
-    /// guards still raise. Reading the text gate as a general argument law is exactly 1717's error.
+    /// Only an unusable text is silent (`0x795590` jumps to its epilogue): a bad colour still adds
+    /// the line, and the receiver check still raises.
     #[test]
     fn addmessage_swallows_a_text_it_cannot_use_and_only_the_text() {
         let s = UiScript::new().unwrap();
         s.run("CreateFrame('MessageFrame', 'MF')").unwrap();
 
-        // `lua_isstring 0x6f3510` accepts tags 4 and 3 only — everything else jumps to 0x79582b.
+        // `lua_isstring` (`0x6f3510`) passes strings and numbers only; the rest jump to `0x79582b`.
         for bad in ["nil", "", "true", "{}", "print"] {
             s.run(&format!("MF:AddMessage({bad})"))
                 .unwrap_or_else(|e| panic!("AddMessage({bad}) must not raise: {e}"));
         }
-        // …and so does the empty string, on its own `cmp byte ptr [ebx],0` at 0x79564b.
+        // The empty string has its own check (`0x79564b`).
         s.run("MF:AddMessage('')").unwrap();
         assert_eq!(
             num_messages(&s, "MF"),
@@ -295,14 +225,12 @@ mod tests {
             "nil, absent, boolean, table, function and \"\" each add NOTHING"
         );
 
-        // A number IS a usable text — tag 3 passes the gate and `0x6f7c80` retags the slot in
-        // place, so it renders as its decimal form.
+        // A number is a text, retagged in place (`0x6f7c80`).
         s.run("MF:AddMessage(42)").unwrap();
         assert_eq!(num_messages(&s, "MF"), 1, "a number is a text");
 
-        // The colour arguments are the OPPOSITE shape and that is the load-bearing negative: a bad
-        // r/g/b jumps to 0x79581c, which still enqueues with the 0xffffffff white staged at
-        // 0x795658. Suppressing the line here would be the same over-generalisation in reverse.
+        // A bad colour jumps to `0x79581c`, which still adds the line in the white staged at
+        // `0x795658`.
         s.run("MF:AddMessage('kept', {}, nil, 'x')").unwrap();
         assert_eq!(
             num_messages(&s, "MF"),
@@ -310,16 +238,13 @@ mod tests {
             "a bad colour still adds the line"
         );
 
-        // The receiver guards are upstream of all of it and DO raise (0x847ef8 — "used '.' instead
-        // of ':'").
+        // The receiver check still raises (`0x847ef8`).
         assert!(
             s.run("MF.AddMessage('dot')").is_err(),
             "a '.'-instead-of-':' call still raises"
         );
     }
 
-    /// `SetInsertMode` is a MessageFrame method and **only** a MessageFrame method — a plain Frame
-    /// and a ScrollingMessageFrame both resolve it to nil, which is what a duck-typing addon reads.
     #[test]
     fn set_insert_mode_is_messageframe_only() {
         let s = UiScript::new().unwrap();
@@ -344,7 +269,6 @@ mod tests {
             "nil",
             "the scrolling class has no SetInsertMode binding at all"
         );
-        // Default BOTTOM (ctor 1), and the round trip.
         assert_eq!(
             s.eval::<String>("return MF:GetInsertMode()").unwrap(),
             "BOTTOM"
@@ -356,9 +280,7 @@ mod tests {
         );
     }
 
-    /// The two `AddMessage`s are different functions, and the observable tell is the fifth argument:
-    /// on a MessageFrame it is alpha (0.5 ⇒ a half-transparent line), on a ScrollingMessageFrame it
-    /// is an id and the line stays opaque.
+    /// The fifth argument is alpha on a MessageFrame and an id on a ScrollingMessageFrame.
     #[test]
     fn messageframe_addmessage_is_not_the_scrolling_ones() {
         let s = UiScript::new().unwrap();
@@ -398,8 +320,6 @@ mod tests {
         );
     }
 
-    /// `insertMode` decides which edge the stack grows from: TOP hangs the newest message off the
-    /// frame's top, BOTTOM (the default) stacks up from its bottom. Same three messages, mirrored.
     #[test]
     fn insert_mode_picks_the_growth_edge() {
         let bands = |mode: &str| {
@@ -450,8 +370,7 @@ mod tests {
         );
     }
 
-    /// The class has no `maxLines` — its cap is what fits vertically, applied at the tick. A frame
-    /// 3 rows tall holds 3 messages however many arrive.
+    /// No `maxLines`: the cap is what fits vertically, applied at the tick.
     #[test]
     fn the_cap_is_what_fits_vertically() {
         let mut s = UiScript::new().unwrap();
@@ -470,7 +389,6 @@ mod tests {
         s.resolve();
         s.tick(0.1);
         assert_eq!(num_messages(&s, "MF"), 3, "42px / 14px pitch = 3 rows");
-        // ...and it is the OLDEST that went.
         s.resolve();
         let texts: Vec<String> = s
             .extract()
@@ -483,8 +401,7 @@ mod tests {
         assert!(texts.contains(&"m8".to_string()) && !texts.contains(&"m0".to_string()));
     }
 
-    /// A faded line on this class is **freed**, not left blank holding its rows — the difference
-    /// from the scrolling class, whose ring slots persist. `Clear` is the immediate form.
+    /// A faded line is freed, where the scrolling class keeps its rows.
     #[test]
     fn a_finished_line_is_retired_and_clear_empties_now() {
         let mut s = UiScript::new().unwrap();
@@ -505,8 +422,7 @@ mod tests {
         assert_eq!(num_messages(&s, "MF"), 0);
     }
 
-    /// The ctor defaults, straight off msgframe-runtime.md's shared-defaults section, plus the
-    /// setters' round trip.
+    /// The ctor defaults: timeVisible (`0x81cc2c`) and fadeDuration (`0x81cc30`).
     #[test]
     fn ctor_defaults_and_the_fade_accessors() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/messageframe/scrolling.rs b/crates/benilla-ui/src/script/messageframe/scrolling.rs
index e11ba4b4..6060f4c1 100644
--- a/crates/benilla-ui/src/script/messageframe/scrolling.rs
+++ b/crates/benilla-ui/src/script/messageframe/scrolling.rs
@@ -1,22 +1,8 @@
-//! The `ScrollingMessageFrame` method surface — the chat window's per-kind widget behavior
-//! (`CSimpleMessageScrollFrame`, ctor `0x787670`).
-//!
-//! Grounded in wow-re's byte-verified runtime model (msgframe-runtime.md, §5 pair): a **true ring**
-//! of `maxLines` (drop-oldest, `SetMaxLines` destructive), `AddMessage(text[,r,g,b[,id]])` with the
-//! `trunc(x*255+0.5)` color quantization + forced-opaque alpha, per-line fade snapshots ticked only
-//! while **AtBottom** (scrolled up freezes every alpha), 1-slot scrollback, and — the other half of
-//! that fade, `msgframe-fade-rearm-law.md` — **every scroll entry re-arming the displayed lines**,
-//! which is what brings a faded-out chat back. The heavy lifting
-//! (the ring, the fade phases, the scroll clamps) lives on [`ScrollingMessageState`]
-//! (`crate::widget`), unit-tested there; this module is the thin Lua binding over it, plus the
-//! host-facing [`UiScript::add_chat_message`]/fade advance the app drives.
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for ScrollingMessageFrame frames — so duck-typing addons (`if frame.AddMessage then …`) see `nil`
-//! on every other kind, exactly as against the client's per-class method sets. **Its sibling class
-//! `MessageFrame` has its own table next door** ([`super::plain`]) carrying a *different*
-//! `AddMessage`: merging the two would hand a chat frame a `SetInsertMode` it does not have, and a
-//! MessageFrame an id argument where its alpha belongs.
+//! The `ScrollingMessageFrame` methods over [`ScrollingMessageState`]: `CSimpleMessageScrollFrame`
+//! (ctor `0x787670`), the chat window's class. A ring of `maxLines` that drops the oldest, colours
+//! quantized `trunc(x*255+0.5)` with alpha forced opaque, a fade that ticks only at the bottom, and
+//! every scroll call re-arming the displayed lines' fade (`0x788b80` when refused at an end,
+//! `0x788af0` when it moves), which is what brings a faded chat back.
 
 use mlua::{Lua, Table, Value};
 
@@ -24,14 +10,12 @@ use crate::script::object::frame_handle_of;
 use crate::script::{Model, UiScript};
 use crate::widget::{KindState, ScrollingMessageState};
 
-/// Registry key of the ScrollingMessageFrame method table (the MAXCSTACK discipline: Lua-side root,
-/// named key).
+/// Registry key of the ScrollingMessageFrame method table (the MAXCSTACK discipline).
 pub(crate) const REG_SCROLLINGMESSAGEFRAME_METHODS: &str =
     "__benilla_scrollingmessageframe_methods";
 
-/// Run `f` over a frame's message-frame state under one short write borrow. Errors if `this` is not a
-/// live ScrollingMessageFrame (unreachable through the kind dispatcher, but the method table is a
-/// plain Lua value — a caller could fish it out and misapply it).
+/// Run `f` over a ScrollingMessageFrame's state under one short borrow; any other frame, reachable
+/// only through a misapplied method table, is an error.
 fn with_smf<T>(
     lua: &Lua,
     this: &Table,
@@ -49,9 +33,7 @@ fn with_smf<T>(
     }
 }
 
-/// `lua_isnumber` semantics — a number, or a string Lua would coerce to one. The rgb trio's
-/// presence test is three of these (decision 2125), so a caller passing `"1"` still colours the
-/// line and a caller passing `nil` or a table does not.
+/// `lua_isnumber`: a number or a numeric string. The rgb presence test is three of these.
 fn is_number(v: &Value) -> bool {
     match v {
         Value::Integer(_) | Value::Number(_) => true,
@@ -60,7 +42,7 @@ fn is_number(v: &Value) -> bool {
     }
 }
 
-/// A Lua number-ish → f32 (nil/other → 0.0), for the color args.
+/// A colour argument as f32, 0 for anything but a number.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -69,12 +51,8 @@ fn num_f32(v: &Value) -> f32 {
     }
 }
 
-/// Run a scroll entry over a frame's state with the viewport's row budget in hand.
-///
-/// Every scroll method needs it, not just the pages: each one re-arms the **displayed** lines'
-/// fade ([`ScrollingMessageState::reset_all_fade_times`]), and which lines those are depends on the
-/// row budget. It comes from the frame's last resolved rect at the ring font's pitch (the
-/// font-height line-step law, the emit pass's basis); an unresolved frame reads as one row.
+/// Run a scroll call with the viewport's row count, which every scroll needs: each re-arms the
+/// fade of the lines on display ([`ScrollingMessageState::reset_all_fade_times`]).
 fn scroll(
     lua: &Lua,
     this: &Table,
@@ -99,27 +77,16 @@ fn scroll(
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // The justify quartet, shared with the sibling class — see [`super::install_justify`] for the
-    // method-table bytes that put all four on BOTH tables.
+    // The justify quartet, on both classes ([`super::install_justify`]).
     super::install_justify(lua, &m, "ScrollingMessageFrame")?;
 
-    // AddMessage(text [, r, g, b [, id]]) — binding 0x792900. rgb absent ⇒ white; the state
-    // quantizes round-half-up and forces the line opaque, then the fade drives its alpha.
-    //
-    // **The rgb gate is three separate `lua_isnumber` calls on indices 3/4/5, and the id's index
-    // is LEG-DEPENDENT** (decision 2125; wow-re `login-chat-colour-pipeline.md`): 6 when rgb are
-    // present (`0x792b13 mov edx,6`), **3** when they are absent (`0x792b48 mov edx,3`) — which is
-    // what makes the documented `AddMessage(text, id)` shorthand work. So `AceConsole-2.0`'s
-    // `AddMessage(text, nil, nil, nil, nil, 5)` fails the R gate at index 3, takes the absent leg,
-    // re-reads index 3 as the id — still nil — and stores **0**; its trailing `5` sits at index 7
-    // and is never read at all.
-    //
-    // Absent or non-numeric is id 0, and 0 is a line `UpdateColorByID` can never find: that guard
-    // is the reference's own, at `0x788250`'s first branch.
-    //
-    // The TEXT gate is the sibling class's, verbatim — gate `0x79299c`, `je 0x792b81` = this
-    // function's own epilogue — so `DEFAULT_CHAT_FRAME:AddMessage(nil)` is silent too. See
-    // `super::message_text`.
+    // AddMessage(text [, r, g, b [, id]]) (`0x792900`): white without rgb; the state quantizes
+    // the colour and makes the line opaque. The rgb test is three `lua_isnumber` checks; the id
+    // is stack index 6 when they pass (`0x792b13`) and index 3, `r`'s, when they fail
+    // (`0x792b48`), which makes `AddMessage(text, id)` work and gives
+    // `AddMessage(text, nil, nil, nil, nil, 5)` id 0. A missing id is 0, which `UpdateColorByID`
+    // never matches (`0x788250`). The text gate (`0x79299c`) is the plain class's
+    // ([`super::message_text`]).
     m.set(
         "AddMessage",
         lua.create_function(
@@ -128,10 +95,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     return Ok(());
                 };
                 let has_rgb = is_number(&r) && is_number(&g) && is_number(&b);
-                // The id is the chat-type index (`GetChatTypeIndex`) the line is printed under —
-                // `ChatFrame.lua` passes `info.id` — read from the leg's OWN stack slot: the
-                // sixth argument when rgb are present, the third (i.e. where `r` would be) when
-                // they are not.
+                // The chat-type index (`ChatFrame.lua` passes `info.id`), stack index 6 or 3.
                 let id = match if has_rgb { &id } else { &r } {
                     Value::Integer(i) => u32::try_from(*i).unwrap_or(0),
                     Value::Number(n) if n.is_finite() && *n >= 0.0 => *n as u32,
@@ -147,9 +111,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?,
     )?;
 
-    // UpdateColorByID(id, r, g, b) — `0x7932b0`. `ChatFrame_OnEvent`'s UPDATE_CHAT_COLOR arm
-    // calls it with the type's index and the event's floats so the lines already in the
-    // window take the new colour; lines printed under another id are untouched.
+    // UpdateColorByID(id, r, g, b) (`0x7932b0`) recolours the lines printed under `id`; stock
+    // `ChatFrame_OnEvent` calls it on `UPDATE_CHAT_COLOR`.
     m.set(
         "UpdateColorByID",
         lua.create_function(
@@ -214,7 +177,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| with_smf(lua, &this, |smf| smf.at_bottom()))?,
     )?;
 
-    // SetMaxLines is destructive (msgframe-runtime.md) — the state handles the wipe.
+    // SetMaxLines wipes the ring (`0x7938a0`).
     m.set(
         "SetMaxLines",
         lua.create_function(|lua, (this, n): (Table, i64)| {
@@ -237,8 +200,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             with_smf(lua, &this, |smf| smf.fading_enabled = on)
         })?,
     )?;
-    // 1/nil, the reference's predicate shape — `binding-shapes.tsv` has this row as
-    // `(nil) | (number)`, like every other 1.12 predicate (decision 2118).
+    // 1 or nil, the 1.12 predicate shape (`0x793a40`).
     m.set(
         "GetFading",
         lua.create_function(|lua, this: Table| {
@@ -247,8 +209,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // The XML attr is `displayDuration`; the Lua accessors call the same field `TimeVisible`
-    // (msgframe-runtime.md).
+    // XML's `displayDuration` is the Lua `TimeVisible` (`0x788090`).
     m.set(
         "SetTimeVisible",
         lua.create_function(|lua, (this, s): (Table, f32)| {
@@ -271,18 +232,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── the shared font block ───────────────────────────────────────────────────────────────
-    //
-    // `Set/GetFontObject · Set/GetFont · Set/GetTextColor · Set/GetShadowColor ·
-    // Set/GetShadowOffset` are real entries on this class's table, not a courtesy. wow-re's
-    // registrar carve is explicit about the membership — *"Exposed on: FontString, Font object,
-    // EditBox, MessageFrame, ScrollingMessageFrame, SimpleHTML. NOT on Button"* — and names this
-    // class's own shims calling the shared implementations (`GetShadowColor 0x792240`). All six
-    // carry the block now — `SimpleHTML`'s is its own copy rather than `font_block::install`'s
-    // (`script/simplehtml/mod.rs`), because that class computes its own inter-block step.
-    //
-    // Demand is observed, not counted: `BigWigs/Plugins/Messages.lua:212` is
-    // `self.msgframe:SetFontObject(GameFontNormalLarge)` on a frame it has just given
-    // `SetInsertMode("TOP")`, and BigWigs dies there every session.
+    // The ten font verbs are on this class's own table (`GetShadowColor` `0x792240`), as on
+    // FontString, Font, EditBox, MessageFrame and SimpleHTML; Button's (`0x879d00`) has none.
     crate::script::font_block::install(
         lua,
         &m,
@@ -296,12 +247,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     lua.set_named_registry_value(REG_SCROLLINGMESSAGEFRAME_METHODS, m)?;
 
-    // SubmitChatInput(text) — the chat input EditBox's OnEnterPressed hands the typed line here; it
-    // queues into the model for the app to parse into a chat command (the outbound Lua→app seam, the
-    // twin of loot's LootSlot). Empty/whitespace lines are queued as-is; the app treats them as a
-    // cancel. Not an EditBox method — a bare global, called with the line the handler read.
-    // BenillaChatTabPressed() — the chat edit box's OnTabPressed queues a flag the app's
-    // whisper-cycle system drains (UiScript::take_chat_tab), the SubmitChatInput pattern.
+    // BenillaChatTabPressed(): the chat edit box's OnTabPressed sets a flag for the app's whisper
+    // cycle (`UiScript::take_chat_tab`).
     lua.globals().set(
         "BenillaChatTabPressed",
         lua.create_function(|lua, ()| {
@@ -310,6 +257,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
+    // SubmitChatInput(text): the chat edit box's OnEnterPressed queues the line for the app to
+    // parse as a chat command; an empty line is queued too, and the app takes it as a cancel.
     lua.globals().set(
         "SubmitChatInput",
         lua.create_function(|lua, text: Option<String>| {
@@ -340,7 +289,6 @@ mod tests {
             let (t, r, g, b) = white(&format!("line {n}"));
             s.add(t, r, g, b);
         }
-        // Only the last 3 survive, oldest→newest.
         assert_eq!(s.lines.len(), 3);
         let texts: Vec<&str> = s.lines.iter().map(|l| l.text.as_str()).collect();
         assert_eq!(texts, ["line 2", "line 3", "line 4"]);
@@ -362,10 +310,10 @@ mod tests {
     #[test]
     fn color_is_quantized_round_half_up() {
         let mut s = ScrollingMessageState::default();
-        // 0.5*255 = 127.5 → +0.5 → 128.0 → trunc 128 (round-half-up); 1.0 → 255; clamp past 1.0.
+        // trunc(0.5 * 255 + 0.5) = 128; 1.0 is 255, and past 1.0 clamps.
         s.add("q".into(), 0.5, 1.0, 2.0);
         assert_eq!(s.lines[0].color, [128, 255, 255]);
-        // FF8040 (EMOTE) from 1.0, 0.5019.., 0.2509.. → 255,128,64 (spot the table's byte round-trip).
+        // EMOTE's FF8040 survives the byte round trip.
         s.add("e".into(), 1.0, 128.0 / 255.0, 64.0 / 255.0);
         assert_eq!(s.lines[1].color, [255, 128, 64]);
     }
@@ -381,7 +329,7 @@ mod tests {
         // Phase 1: full alpha while timeVisible remains.
         s.tick(0.5);
         assert_eq!(s.lines[0].alpha, 1.0);
-        // Cross into phase 2: 0.5 more spends the last of timeVisible; next ticks ramp fadeDuration.
+        // 0.5 more spends timeVisible; the ticks after ramp over fadeDuration.
         s.tick(0.5);
         assert_eq!(s.lines[0].alpha, 1.0, "phase 1 just expired, ramp not yet");
         s.tick(1.0); // fade_left 2.0 → 1.0 → alpha = trunc(1.0/2.0*255)/255 = 127/255
@@ -398,15 +346,13 @@ mod tests {
             ..Default::default()
         };
         s.add("x".into(), 1.0, 1.0, 1.0);
-        s.tick(0.6); // spends timeVisible (per-tick phase check: still full this tick)
+        s.tick(0.6); // spends timeVisible, still full this tick
         assert_eq!(s.lines[0].alpha, 1.0);
-        s.tick(0.1); // now past phase 1, no ramp ⇒ straight to 0
+        s.tick(0.1); // past phase 1 with no ramp: straight to 0
         assert_eq!(s.lines[0].alpha, 0.0);
     }
 
-    /// The tick's AtBottom gate, isolated from the scroll re-arm that now sits next to it: with a
-    /// one-row viewport only the newest displayed line is re-armed, so the two lines either side of
-    /// it are the ones that show the freeze.
+    /// With a one-row viewport the scroll re-arms one line; the lines either side show the freeze.
     #[test]
     fn scrolled_up_freezes_the_fade() {
         let mut s = ScrollingMessageState {
@@ -421,8 +367,7 @@ mod tests {
         s.tick(2.0); // half-way down the ramp: trunc(2.0/4.0*255) = 127
         let half = 127.0 / 255.0;
         assert_eq!(s.lines[0].alpha, half);
-        // Scroll up one line — no longer AtBottom, so ticks must not advance any alpha. The line
-        // that lands in the one-row viewport (l1) is re-armed by the scroll; l0 and l2 are not.
+        // Scrolled up, ticks stop; the scroll re-arms only l1, the line now in view.
         s.scroll_up(1);
         assert!(!s.at_bottom());
         assert_eq!(s.lines[1].alpha, 1.0, "the displayed line was re-armed");
@@ -430,15 +375,14 @@ mod tests {
         assert_eq!(s.lines[0].alpha, half, "frozen while scrolled up");
         assert_eq!(s.lines[2].alpha, half);
         assert_eq!(s.lines[1].alpha, 1.0);
-        // Back to bottom → the fade resumes (from the re-arm this scroll performs).
+        // Back at the bottom, the fade resumes.
         s.scroll_to_bottom(1);
         s.tick(2.0);
         assert!(s.lines[2].alpha < 1.0);
     }
 
-    /// **The director's bug (2026-08-29): a fully-faded chat could never be brought back.** Every
-    /// scroll entry re-arms the displayed lines — including the ones that move no cursor at all,
-    /// which is what clicking the arrows on an already-at-bottom chat does.
+    /// Every scroll call re-arms the displayed lines, even one that moves no cursor, as clicking
+    /// the arrows on a chat already at the bottom does.
     #[test]
     fn any_scroll_brings_faded_lines_back() {
         let armed = |op: fn(&mut ScrollingMessageState, usize)| {
@@ -452,7 +396,7 @@ mod tests {
                 s.add(format!("l{n}"), 1.0, 1.0, 1.0);
             }
             s.tick(1.5); // spend phase 1
-            s.tick(1.5); // spend phase 2 — everything is gone
+            s.tick(1.5); // spend phase 2: all gone
             assert!(s.lines.iter().all(|l| l.alpha == 0.0), "faded out first");
             op(&mut s, 8);
             s
@@ -469,8 +413,7 @@ mod tests {
             ("PageDown", ScrollingMessageState::page_down),
         ] {
             let s = armed(op);
-            // Whatever the op left in view is what the engine re-arms — `ScrollUp` carries the
-            // newest line off the bottom of the viewport, so the set is the op's, not the ring.
+            // The re-armed set is what the op left in view, not the whole ring.
             let shown = s.displayed_range(8);
             assert!(!shown.is_empty(), "{name} displayed nothing");
             for i in shown {
@@ -482,8 +425,7 @@ mod tests {
         }
     }
 
-    /// `0x788b80` walks the display vector, not the ring: a line scrolled out of view keeps
-    /// whatever fade state it had.
+    /// `0x788b80` walks the lines on display, not the ring.
     #[test]
     fn the_re_arm_reaches_only_the_displayed_lines() {
         let mut s = ScrollingMessageState {
@@ -513,7 +455,7 @@ mod tests {
             s.add(format!("l{n}"), 1.0, 1.0, 1.0);
         }
         assert!(s.at_bottom());
-        s.scroll_down(8); // already at bottom — no cursor move
+        s.scroll_down(8); // already at the bottom: no move
         assert!(s.at_bottom());
         // 3 lines → max_scroll = 2; scroll past it clamps.
         for _ in 0..10 {
@@ -536,7 +478,7 @@ mod tests {
         }
         s.scroll_up(8); // viewing one line back (bottom row = l2)
         let off = s.scroll_offset;
-        s.add("l4".into(), 1.0, 1.0, 1.0); // a new line arrives at the bottom
+        s.add("l4".into(), 1.0, 1.0, 1.0);
         assert_eq!(
             s.scroll_offset,
             off + 1,
@@ -553,14 +495,12 @@ mod tests {
         for n in 0..3 {
             s.add(format!("l{n}"), 1.0, 1.0, 1.0);
         }
-        // Middle line wraps into 3 rows.
         s.lines[1].rows = 3;
-        // Viewport of 4 rows from the bottom: newest (1 row) + middle (3 rows) fill it exactly —
-        // the oldest is off the top. A partially-fitting message counts (it draws, clipped).
+        // 4 rows: the newest (1) and the middle (3) fill it; a partly fitting message counts.
         assert_eq!(s.displayed_count(4), 2);
         assert_eq!(s.displayed_count(3), 2, "partial middle line still counts");
         assert_eq!(s.displayed_count(1), 1);
-        // Page = displayed − 1 (one message of overlap), never 0.
+        // A page is displayed − 1, one message of overlap, never 0.
         s.page_up(4);
         assert_eq!(s.scroll_offset, 1);
         s.page_up(1); // displayed 1 → page clamps to 1 message
@@ -586,11 +526,9 @@ mod tests {
         s.run("CF:AddMessage('wrapped', 1, 1, 1)").unwrap();
         s.run("CF:AddMessage('new', 1, 1, 1)").unwrap();
         s.resolve();
-        // The measure round-trip: every fresh line requests its row count at the resolved width.
         let reqs = s.message_lines_needing_measure();
         assert_eq!(reqs.len(), 3);
         assert!(reqs.iter().all(|r| (r.wrap_width - 430.0).abs() < 0.5));
-        // Host answers: the middle line wraps to 2 rows.
         let answers: Vec<(u32, u32, u16, u64)> = reqs
             .iter()
             .map(|r| (r.frame, r.index, if r.index == 1 { 2 } else { 1 }, r.key))
@@ -600,9 +538,8 @@ mod tests {
             s.message_lines_needing_measure().is_empty(),
             "answered keys satisfy the cache"
         );
-        // Default font (no FontString child) ⇒ pitch 14. Frame [90, 124): 'new' band [90,104),
-        // 'wrapped' 2-row band [104,132) — starts inside, overflows the top, still emitted
-        // (clipped); 'old' would start at 132 ≥ 124 — not emitted.
+        // Default font, pitch 14. Frame [90, 124): 'new' is [90, 104), 'wrapped' [104, 132)
+        // overflows and draws clipped, and 'old' would start at 132, outside, so does not draw.
         let quads = s.extract();
         let texts: Vec<(String, f32, f32)> = quads
             .iter()
@@ -622,7 +559,6 @@ mod tests {
         assert!((texts[0].1 - 90.0).abs() < 0.01 && (texts[0].2 - 104.0).abs() < 0.01);
         assert_eq!(texts[1].0, "wrapped");
         assert!((texts[1].1 - 104.0).abs() < 0.01 && (texts[1].2 - 132.0).abs() < 0.01);
-        // Both clip to the frame rect, so the overflow never inks outside it.
         let clip = quads
             .iter()
             .find_map(|q| match &q.content {
@@ -633,10 +569,8 @@ mod tests {
         assert!((clip.top - 124.0).abs() < 0.01 && (clip.bottom - 90.0).abs() < 0.01);
     }
 
-    /// The ring lines are the frame's ARTWORK content, not its bare draw slot: a BACKGROUND
-    /// texture of the same frame draws BEHIND them, an OVERLAY one in front. The chat window's
-    /// hover box is that background texture — at the bare slot it painted over the messages and
-    /// dimmed them (director, 2026-07-26).
+    /// The lines draw at the frame's ARTWORK layer: a BACKGROUND texture, such as the chat
+    /// window's hover box, behind them, an OVERLAY one in front.
     #[test]
     fn ring_lines_draw_above_the_frames_background_and_below_its_overlay() {
         let mut s = UiScript::new().unwrap();
@@ -731,7 +665,7 @@ mod tests {
         )
         .unwrap();
         s.run("CF:AddMessage('doomed', 1, 1, 1)").unwrap();
-        // Two ticks retire 'doomed' (phase-1 spend, then the no-ramp snap), then fresh lines land.
+        // Two ticks retire 'doomed' (phase 1, then the snap with no ramp); then fresh lines land.
         s.tick(0.1);
         s.tick(0.1);
         s.run("CF:SetTimeVisible(120)").unwrap();
@@ -748,8 +682,7 @@ mod tests {
                 _ => None,
             })
             .collect();
-        // 'doomed' draws nothing but its band (the oldest, topmost) still holds its place: the two
-        // live lines sit at the two bottom bands, nothing re-packs into the faded slot.
+        // 'doomed' draws nothing but keeps its band at the top; the live lines hold the bottom two.
         assert_eq!(texts.len(), 2);
         assert_eq!(texts[0].0, "b");
         assert!((texts[0].1 - 0.0).abs() < 0.01);
@@ -773,7 +706,6 @@ mod tests {
         .unwrap();
         s.run("CF:AddMessage('x', 1, 1, 1)").unwrap();
         s.resolve();
-        // Find the frame handle the extract loop would hand the app (the message line's target).
         let fh = s
             .extract()
             .iter()
@@ -785,8 +717,8 @@ mod tests {
                 _ => None,
             })
             .expect("the ring line extracts");
-        // The app feeds a span (y-up rect) covering [10..60]x[20..34]; a release inside fires the
-        // handler with (link, markup, button); one outside does not.
+        // The app feeds a span (a y-up rect) over [10..60]x[20..34]; a release inside fires the
+        // handler with (link, markup, button), one outside does not.
         s.set_link_spans(vec![(
             fh,
             crate::layout::Rect::new(20.0, 10.0, 34.0, 60.0),
@@ -825,14 +757,8 @@ mod tests {
         assert!(!s.add_chat_message("PlainFrame", "x", 1.0, 1.0, 1.0));
     }
 
-    /// **`AddMessage`'s id lives at a different stack index on each leg** (decision 2125): the
-    /// sixth argument when r,g,b are present, the THIRD when they are not — which is what makes
-    /// the `AddMessage(text, id)` shorthand work at all (`0x792b13 mov edx,6` /
-    /// `0x792b48 mov edx,3`).
-    ///
-    /// `AceConsole-2.0`'s `Print` is the case that matters: `AddMessage(text, nil, nil, nil, nil,
-    /// 5)` fails the R gate at index 3, takes the absent leg, re-reads index 3 as the id — still
-    /// nil — and stores 0. Its trailing `5` sits at index 7 and is never read.
+    /// The id is stack index 6 with rgb and index 3 without (`0x792b13`, `0x792b48`), so
+    /// `AceConsole-2.0`'s `AddMessage(text, nil, nil, nil, nil, 5)` stores 0.
     #[test]
     fn the_addmessage_id_index_follows_the_rgb_leg() {
         let s = UiScript::new().unwrap();
@@ -855,8 +781,6 @@ mod tests {
         );
     }
 
-    /// `UpdateColorByID` recolours exactly the lines printed under that id — the stock
-    /// `ChatFrame_OnEvent` repaints a type's history when its colour changes, and nothing else.
     #[test]
     fn update_color_by_id_recolours_only_that_ids_lines() {
         let mut smf = ScrollingMessageState::default();
@@ -879,10 +803,8 @@ mod tests {
         assert_ne!(smf.lines_gen, gen, "a recolour is a redraw");
         assert_eq!(smf.update_color_by_id(11, 0.0, 0.5, 1.0), 0, "idempotent");
         assert_eq!(smf.update_color_by_id(99, 0.0, 0.0, 0.0), 0, "no such id");
-        // **Id 0 matches nothing** — `0x788250`'s own opening guard (decision 2125). Line "d" was
-        // printed with no id, so it carries 0; so does `ChatTypeInfo["REPLY"]`, which the
-        // `UPDATE_CHAT_COLOR` handler mirrors WHISPER into. Without the guard that pair repainted
-        // every colourless line in the window whisper-pink at every login.
+        // Id 0 matches nothing (`0x788250`). REPLY's chat type has id 0 and `UPDATE_CHAT_COLOR`
+        // mirrors WHISPER into it, so without the guard every id-less line turns whisper pink.
         assert_eq!(
             smf.update_color_by_id(0, 1.0, 0.5, 1.0),
             0,
@@ -894,7 +816,7 @@ mod tests {
             "the colourless line stays the frame's own colour"
         );
 
-        // And the Lua surface: the fifth argument tags, the method recolours, silently.
+        // Through Lua: argument 5 tags the line, and a bad id is silent.
         let s = UiScript::new().unwrap();
         s.run(
             "local f = CreateFrame('ScrollingMessageFrame') \
@@ -922,11 +844,8 @@ mod tests {
         assert_eq!(s.eval::<i64>("return CF:GetNumMessages()").unwrap(), 0);
     }
 
-    /// The W4 skip token: a settled message frame's sweep hashes ZERO lines (the counter is the
-    /// claim — 0735's counts rule), and each side of the token catches its own change class:
-    /// text through the generation, the resolved width through the environment hash. The token
-    /// is only stored by a zero-request sweep, so an UNANSWERED request keeps re-requesting —
-    /// the region ledger's own rule (1410), inherited.
+    /// A settled frame's sweep hashes no lines; a text change reopens it through the line
+    /// generation, a width change through the environment hash.
     #[test]
     fn a_settled_message_frame_hashes_no_lines_until_something_moves() {
         let mut s = UiScript::new().unwrap();
@@ -950,7 +869,7 @@ mod tests {
             again.iter().map(|r| (r.frame, r.index, 1, r.key)).collect();
         s.set_message_line_rows(&answers);
         assert!(s.message_lines_needing_measure().is_empty());
-        // Settled: the NEXT sweep must skip the frame whole — zero lines hashed.
+        // Settled: the next sweep skips the frame whole.
         let hashed_before = s.model_mut().msg_lines_hashed;
         assert!(s.message_lines_needing_measure().is_empty());
         assert_eq!(
@@ -958,7 +877,7 @@ mod tests {
             hashed_before,
             "a settled frame's sweep must hash no lines"
         );
-        // Text change reopens through the GENERATION…
+        // A text change reopens through the generation.
         s.run("CF:AddMessage('three', 1, 1, 1)").unwrap();
         let reqs = s.message_lines_needing_measure();
         assert_eq!(reqs.len(), 1, "the new line re-surfaces");
@@ -967,7 +886,7 @@ mod tests {
             reqs.iter().map(|r| (r.frame, r.index, 1, r.key)).collect();
         s.set_message_line_rows(&answers);
         assert!(s.message_lines_needing_measure().is_empty());
-        // …and a resolved-width change reopens through the ENVIRONMENT: every line re-keys.
+        // A width change reopens through the environment: every line re-keys.
         s.run("CF:SetWidth(300)").unwrap();
         s.resolve();
         let reqs = s.message_lines_needing_measure();
diff --git a/crates/benilla-ui/src/script/minimap.rs b/crates/benilla-ui/src/script/minimap.rs
index 8069ad63..c43a4169 100644
--- a/crates/benilla-ui/src/script/minimap.rs
+++ b/crates/benilla-ui/src/script/minimap.rs
@@ -1,30 +1,7 @@
-//! The `Minimap` method surface — the zoom API the FrameXML zoom buttons drive
-//! (`MinimapZoomIn`/`MinimapZoomOut` → `Minimap:SetZoom(Minimap:GetZoom() ± 1)`).
-//!
-//! Grounded in wow-re's byte-verified minimap node: `get_zoom_levels` (`0x6da9a0`) returns the
-//! constant 6, `set_zoom` clamps at 5 and marks the tile grid dirty, and the zoom index feeds the
-//! `zoom_to_scale` tables (`0x6da9b0`). The engine core carries only the index
-//! ([`MinimapState`]); the app renderer maps it to a world radius and draws the tiles
-//! (decision 0203). The two model attrs (`minimapArrowModel=`/`minimapPlayerModel=`) are modeled
-//! only as far as the Lua surface can see them: [`apply_model_attrs`] names the nine engine
-//! children the ctor built, and the app still draws every arrow from its own art.
-//!
-//! **The ping** (decision 1596) is the same split, one rung further out: the two methods here are
-//! pure seam — `PingLocation` parks a click and `GetPingPosition` reads back what the app
-//! published — because the ping's only stored form is a WORLD point the app pins it to, and the
-//! engine core has no world. Nothing here holds the ping's position, its lifetime, or its art;
-//! putting any of that in Lua is what made the first attempt flaky.
-//!
-//! **The level persists** (decision 1131). The client keeps two halves: the live indices
-//! (`0x86f698` outdoor / `0x86f69c` indoor — our [`MinimapState`]) and the two CVar objects
-//! `minimapZoom`/`minimapInsideZoom` (both registered default `"3"`), which are what `Config.wtf`
-//! actually stores. `set_zoom` writes *both*; the minimap reset path (`0x6d9008`–`0x6d901f`)
-//! re-seeds the live index from the CVar's parsed int. benilla runs the same two halves at the same
-//! seam: `SetZoom` below writes the index and the CVar, and the app seeds the widget from the CVar
-//! table once, when the in-game UI materializes ([`super::UiScript::set_minimap_zoom`]).
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for Minimap frames — the same duck-typing posture as StatusBar's.
+//! The `Minimap` methods: zoom, the mask, the ping and the model attributes. The reference has six
+//! levels (`0x6da9a0`), a live index per mode (`0x86f698` outdoor, `0x86f69c` indoor) and the
+//! `minimapZoom`/`minimapInsideZoom` CVars (default `"3"`) that re-seed it (`0x6d9008`); the app
+//! maps the index to a radius (`0x6da9b0`) and holds the ping as a world point.
 
 use mlua::{Lua, Table};
 
@@ -32,12 +9,11 @@ use super::object::frame_handle_of;
 use super::Model;
 use crate::widget::{KindState, MinimapState, MINIMAP_ZOOM_LEVELS};
 
-/// Registry key of the Minimap method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the Minimap method table.
 pub(super) const REG_MINIMAP_METHODS: &str = "__benilla_minimap_methods";
 
-/// Run `f` over a frame's Minimap state under one short write borrow. Errors if `this` is not a
-/// live Minimap (unreachable through the kind dispatcher, but the method table is a plain Lua
-/// value — a caller can fish it out and misapply it).
+/// Run `f` over a frame's Minimap state; errors on any other receiver, since the method table is
+/// a plain Lua value a caller can misapply.
 fn with_minimap<T>(
     lua: &Lua,
     this: &Table,
@@ -55,18 +31,9 @@ fn with_minimap<T>(
     }
 }
 
-/// `CMinimap::LoadXML 0x4ee2b0`'s model half: assign the two `<Minimap>` model attributes to the
-/// nine engine children the ctor already built. `minimapArrowModel` (engine default
-/// [`crate::widget::MINIMAP_DEFAULT_ARROW_MODEL`]) goes to children **1–8** via `0x4ee170`'s two loops
-/// (`0x4ee1b7` over the five at `+0x320`, `0x4ee204` over the three at `+0x314`);
-/// `minimapPlayerModel` (default [`crate::widget::MINIMAP_DEFAULT_PLAYER_MODEL`]) goes to child **9 alone**, via
-/// `0x4ee260`.
-///
-/// The split is what makes the nine *distinguishable* from Lua: without it `GetModel()` is `""` on
-/// all nine and nothing in the tuple says which one is the player arrow.
-///
-/// Runs before the `<Frames>` descent, because `0x4ee2b0` does its own work and only then chains to
-/// `CSimpleFrame::LoadXML 0x76a2f0`, which is what recurses into the children.
+/// The model half of `CMinimap::LoadXML` (`0x4ee2b0`): `minimapArrowModel` to engine children 1
+/// to 8 (`0x4ee170`), `minimapPlayerModel` to child 9 alone (`0x4ee260`). Runs before the
+/// `<Frames>` descent, as the reference chains to `CSimpleFrame::LoadXML` (`0x76a2f0`) after.
 pub(crate) fn apply_model_attrs(
     lua: &Lua,
     this: &Table,
@@ -102,26 +69,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     m.set(
         "GetZoom",
-        // Reads whichever index is live — the indoor one (`0x86f69c`) while inside a WMO, else the
-        // outdoor one (`0x86f698`). The client's `get_zoom_index` routes on the same flag.
+        // The indoor index while inside a WMO, else the outdoor one, as the reference routes.
         lua.create_function(|lua, this: Table| with_minimap(lua, &this, |m| m.active_zoom()))?,
     )?;
     m.set(
         "SetZoom",
         lua.create_function(|lua, (this, zoom): (Table, f64)| {
-            // The client's set_zoom clamps into [0, levels-1] (`0x6daa10`: clamp at 5). A negative
-            // or fractional Lua number truncates like lua_tonumber → int. It writes the index the
-            // inside flag selects, so the +/- buttons zoom the map you're actually looking at and
-            // each mode keeps its own level.
+            // Truncated and clamped to 0..=5 (`0x6daa10`), into the current mode's index.
             let clamped = (zoom.max(0.0) as u8).min(MINIMAP_ZOOM_LEVELS - 1);
             let inside = with_minimap(lua, &this, |m| {
                 m.set_active_zoom(clamped);
                 m.inside
             })?;
-            // …and it persists the level in the same breath: `set_zoom` writes the live index AND
-            // `CVar::Set`s the matching CVar (`minimapInsideZoom` indoors, `minimapZoom` out), which
-            // is the whole reason a zoom level survives a restart. The borrow above is released
-            // before this one — both reach the same `Model` app_data.
+            // The reference also sets the mode's CVar, which is what survives a restart. The borrow
+            // above is released first: both reach the same `Model`.
             super::cvars::set_from_engine(
                 &mut lua.app_data_mut::<Model>().expect("model app_data"),
                 if inside {
@@ -135,13 +96,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
     m.set(
-        // SetMaskTexture(path) — the disc's mask art. A real 1.12 method (the name is in the 5875
-        // image) with no getter beside it, so this is write-only from Lua, exactly as there.
-        //
-        // An absent or empty path restores the engine default rather than leaving the map
-        // unmasked: `SetMaskTexture` is how a UI replaces the circle, never how it removes one,
-        // and a nil-means-square reading would hand every mistyped path a square minimap with no
-        // error. (pfUI passes a real path; this is about the failure mode, not about pfUI.)
+        // The disc's mask art, write-only as in the reference. An absent or empty path restores
+        // the default circle rather than unmasking the map; what the reference's `0x4ee4a0` does
+        // with one is untraced.
         "SetMaskTexture",
         lua.create_function(|lua, (this, path): (Table, Option<String>)| {
             let path = path.filter(|p| !p.is_empty());
@@ -151,21 +108,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "GetZoomLevels",
         lua.create_function(|lua, this: Table| {
-            // Validate the receiver like every kind method (the constant is per the client's
-            // `get_zoom_levels`, but a non-Minimap receiver is still a caller bug).
+            // The reference's constant, with the receiver still validated.
             with_minimap(lua, &this, |_| MINIMAP_ZOOM_LEVELS)
         })?,
     )?;
     m.set(
         "PingLocation",
-        // The minimap click (our own `Minimap_OnClick`, and any addon that replaced it): centre-
-        // relative offsets in **UI units**, x right / y up — exactly `GetCursorPosition()` minus
-        // `Minimap:GetCenter()`, both of which are UI-space. Parked, not converted: the app owns
-        // the view scale, and it drains this in the SAME frame it draws the map so the click
-        // resolves against the geometry the player actually clicked on (decision 1596).
-        //
-        // The receiver is validated but the value lives on the model — one pending click, not one
-        // per Minimap widget.
+        // Centre-relative offsets in UI units, x right and y up, parked for the app to resolve in
+        // the frame it draws the map; one pending click, not one per widget.
         lua.create_function(|lua, (this, x, y): (Table, f32, f32)| {
             with_minimap(lua, &this, |_| ())?;
             lua.app_data_mut::<Model>()
@@ -176,16 +126,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
     m.set(
         "GetPingPosition",
-        // The ping's normalized offsets from the widget centre (fractions of the widget side,
-        // x right / y up — the `MINIMAP_PING` event's own arg2/arg3 space), recomputed by the app
-        // from the stored world point every frame. So a caller polling this while walking sees
-        // the value MOVE, which is the whole point: the ping is pinned to the world, not to the
-        // map.
-        //
-        // **Two numbers, always** (`0x4eefd0`, wow-re `minimap-ping-law.md`): the reference
-        // recomputes from statics nothing ever clears, and the stock `Minimap_OnUpdate` feeds the
-        // answer straight into `x * Minimap:GetWidth()` for the whole of its 5 s timer — a nil
-        // here is a Lua error on every frame of that window (1974).
+        // Fractions of the widget side from its centre (`MINIMAP_PING`'s arg2/arg3 space), which
+        // the app recomputes from the world point each frame. Always two numbers (`0x4eefd0`): the
+        // stock `Minimap_OnUpdate` multiplies them for 5 s, so a nil would error every frame.
         lua.create_function(|lua, this: Table| {
             with_minimap(lua, &this, |_| ())?;
             let (x, y) = lua
diff --git a/crates/benilla-ui/src/script/mod.rs b/crates/benilla-ui/src/script/mod.rs
index 438f6aa3..49379335 100644
--- a/crates/benilla-ui/src/script/mod.rs
+++ b/crates/benilla-ui/src/script/mod.rs
@@ -1,40 +1,16 @@
-//! The Lua scripting host — the engine-free VM that turns the arena/layout/order *model* into a
-//! live, addon-facing runtime (decision 0068). No Bevy, no GPU: this module embeds mlua's Lua 5.1
-//! (the Classic Era version) and wires it to [`crate::widget`]'s frame arena, [`crate::layout`]'s
-//! anchor resolver, and [`crate::order`]'s draw-order traversal, exposing the WoW FrameScript object
-//! model and the slice-of stdlib addons expect.
+//! The Lua scripting host: the engine-free VM that runs FrameXML and addons over the frame arena,
+//! the anchor resolver and the draw order. It embeds mlua's Lua 5.1, reshaped by [`lua50`] to
+//! answer as the 1.12 client's Lua 5.0.
 //!
-//! ## Ground truth
+//! A frame's Lua value is a table whose `T[0]` lightuserdata (`0x701bd0`) holds a `u32` id where
+//! the reference holds the `CScriptObject*`, with an `__index` metatable (`0x7020b0`). A handler
+//! is `pcall`ed with `this`, `event` and `arg1..argN` set as globals and restored after
+//! (`0x704d50`); it also gets `(self, event, ...)` as arguments, which 1.12 does not pass.
 //!
-//! - **RF-0023** (`wow-5875-re/system/ui/ui.md` §"The Lua frame object model"): a frame's Lua value
-//!   is a table `T` with `T[0] = lightuserdata(handle)`, one *shared* metatable
-//!   `__framescript_meta` whose `__index` dispatches by method name; named frames auto-publish to
-//!   `_G` non-overwriting. See [`object`].
-//! - **RF-0025** (`ui.md` §"FrameScript handler-firing context"): a handler is fired via `pcall`
-//!   with `this`/`event`/`arg1..argN` set as **globals**, saved-then-restored around the call
-//!   (nesting-safe). We also pass the *modern* `(self, event, ...)` arguments the Era addons expect
-//!   (the transition-era client did both). See [`event`].
-//!
-//! ## The `LUAI_MAXCSTACK` discipline (decision 0068, probe A)
-//!
-//! Probe A found the hard constraint that Rust must **never** hold thousands of persistent mlua
-//! handles (each owned `Table`/`Function` occupies a slot on mlua's reference thread, capped by the
-//! vendored build's `LUAI_MAXCSTACK = 8000`). So this host holds **zero** persistent Lua handles in
-//! Rust: every piece of Lua-side state — the two shared metatables, the two method tables, the
-//! wrapper cache (`id → wrapper table`), and every frame's script closures (`id → {name → fn}`) —
-//! lives in the Lua **registry** under named keys and is fetched transiently per call. The Rust-side
-//! [`Model`] is *plain data* (arena, layout inputs, id↔handle maps, region visuals, event
-//! registrations, errors) stored in `lua.app_data`, reachable from callbacks via `RefCell`-style
-//! dynamic borrows. Every callback takes a *short* borrow and drops it before re-entering Lua.
-//!
-//! ## Identity: ids, not handle bits
-//!
-//! RF-0023 stores the `CScriptObject*` in the lightuserdata. Benilla's [`crate::widget::FrameHandle`]
-//! is an opaque generational handle with private fields (no bit accessor), so we mint a stable `u32`
-//! **id** per handle and store *that* in the lightuserdata (`id as *mut c_void`); [`Model`] owns the
-//! `id ↔ handle` bijection. The id doubles as the [`crate::layout::Handle`] used by the layout graph
-//! (frames only; the screen root is the reserved id [`SCREEN`]). This is faithful to RF-0023's intent
-//! (an opaque identity in a lightuserdata) — only the *encoding* differs.
+//! The `LUAI_MAXCSTACK` discipline: Rust holds no persistent Lua handle, since each owned `Table`
+//! or `Function` takes a slot on mlua's reference thread, capped at the vendored 8000. Lua-side
+//! state lives in the registry under named keys, fetched per call; [`Model`] is plain data in
+//! `lua.app_data`, borrowed briefly and released before re-entering Lua.
 
 mod action;
 mod action_bar_toggles;
@@ -52,7 +28,7 @@ mod binding_abi;
 mod dialog_verbs;
 mod tutorial;
 mod worldmap_arrow;
-// The five camera views + FlipCameraYaw — the reference's `UIUtil\Camera.cpp` Lua surface.
+// `camera_view`: the five camera views and `FlipCameraYaw`, the reference's `UIUtil\Camera.cpp`.
 mod button;
 mod camera_view;
 mod channel;
@@ -90,8 +66,6 @@ mod screenshot;
 mod tabard;
 pub use handler_prof::HandlerRow;
 
-/// The widget-method surface measurement — shared by the `dump_widget_methods` example and the
-/// widget-surface gate (decision 2142).
 mod surface;
 pub use surface::widget_method_census;
 mod inspect;
@@ -125,8 +99,6 @@ mod pvp;
 mod quest;
 mod quest_log;
 pub(crate) mod region;
-/// The 19 Region-map methods, shared by frames and regions the way the reference shares them
-/// (decision 1501) — its header is the byte-verified chain and the bug that found the split.
 mod region_map;
 mod reputation;
 mod saved;
@@ -159,8 +131,6 @@ mod trainer;
 mod types;
 mod unit;
 mod weapon_enchant;
-/// The `/who` list's seven-key sort chain and its comparator — its header is the whole
-/// mechanism, including why a repeated header click reverses (decision 2030).
 mod who_sort;
 mod worldmap;
 mod worldstate;
@@ -257,7 +227,7 @@ pub(crate) use simplehtml::{
 };
 pub use skills::{SkillEntry, SkillsState};
 pub use social::{FriendInfo, SocialRequest, SocialState, WhoInfo};
-pub use sound::SoundRequest;
+pub use sound::{MusicRequest, SoundRequest};
 pub use spellbook::{
     resolve_spell_by_name, PetBookState, SpellBookState, SpellSlotView, SpellTabView,
 };
@@ -297,40 +267,28 @@ use crate::layout::Rect;
 use crate::order::ZTarget;
 use crate::widget::{FrameHandle, KindState};
 
-// Registry key names — the only place Lua-side roots are kept alive (the MAXCSTACK discipline).
+// Registry keys, the only roots of Lua-side state (the `LUAI_MAXCSTACK` discipline).
 const REG_FRAME_META: &str = "__benilla_frame_meta";
 const REG_REGION_META: &str = "__benilla_region_meta";
 const REG_FRAME_METHODS: &str = "__benilla_frame_methods";
 const REG_REGION_METHODS: &str = "__benilla_region_methods";
-/// The full table's registry key, exposed for the exhaustiveness gate in `tests::reference_surface`
-/// — the split's correctness is a property of what the VM HOLDS, not of the source that builds it.
 #[cfg(test)]
 pub(crate) const REG_REGION_METHODS_FOR_TEST: &str = REG_REGION_METHODS;
-/// The **title region's** method table + metatable — the 19 Region methods and nothing else.
+/// The title region's method table and metatable: the 19 Region methods and nothing else.
 const REG_TITLE_METHODS: &str = "__benilla_title_methods";
 const REG_TITLE_META: &str = "__benilla_title_meta";
-/// The two region LEAF tables + metatables — Texture and FontString each answer their own map.
+/// The region leaf tables and metatables: Texture and FontString each answer their own map.
 const REG_TEXTURE_METHODS: &str = "__benilla_texture_methods";
 const REG_TEXTURE_META: &str = "__benilla_texture_meta";
 const REG_FONTSTRING_METHODS: &str = "__benilla_fontstring_methods";
 const REG_FONTSTRING_META: &str = "__benilla_fontstring_meta";
-/// The stdlib's out-of-the-box error handler, kept by identity so
-/// [`UiScript::dispatch_script_errors_to_handler`] can tell "nobody chose a handler" (skip — the
-/// default already reports into the host channel) from "FrameXML or an addon installed one"
-/// (dispatch — that is what the pair exists for). Stored at [`stdlib::install`] time, the one
-/// moment the default is known to be what `geterrorhandler()` answers.
+/// The stdlib's default error handler, kept by identity for
+/// [`UiScript::dispatch_script_errors_to_handler`] to skip; stored at [`stdlib::install`].
 const REG_DEFAULT_ERRORHANDLER: &str = "__benilla_default_errorhandler";
 
-/// The **Region method map** (`0xcf54b4`) — the 19 names every region leaf reaches through its own
-/// lookup's fallback, carved in wow-re `system/ui/scratch/font-object-lua-surface.md` and asserted
-/// as a SET by `tests::reference_surface`. Named here because two things need the same list: that
-/// test, and the title region's narrower method table (1250 §5).
-/// Names on **both** region leaves — and each leaf registers its own copy, so these are NOT on the
-/// Region map and must not be hoisted into it (wow-re
-/// `system/ui/scratch/texture-fontstring-method-split.md`, stated there as a trap in as many words).
-/// `GetDrawLayer` is the setter's pair on both leaves (Texture `0x79a6c0`, FontString `0x79c660`)
-/// and is here now — it was carved as absent, which was true and was a gap, not a decision; pfUI's
-/// `GetNoNameObject` reads it off every child of a frame it reskins.
+/// Names on both region leaves, each leaf registering its own copy (Texture's `SetAlpha`
+/// `0x79b580`, FontString's `0x79cb70`), so they are not on the Region map and must not be hoisted
+/// into it. `GetDrawLayer` is on both (Texture `0x79a6c0`, FontString `0x79c660`).
 pub(crate) const REGION_LEAF_SHARED: [&str; 9] = [
     "SetDrawLayer",
     "GetDrawLayer",
@@ -343,24 +301,9 @@ pub(crate) const REGION_LEAF_SHARED: [&str; 9] = [
     "IsShown",
 ];
 
-/// **Texture-only.** Note `GetVertexColor` sits here while `SetVertexColor` is shared — an asymmetry
-/// no reasonable partition invents, and the carve calls it out. Also note the client's Texture map
-/// has `SetGradientAlpha` where FontString has `SetAlphaGradient`: a near-miss pair, and we install
-/// only the FontString one.
-///
-/// **Every name here is the client's own now.** Three of ours were parked in this list pending a
-/// per-name check, and all three are gone: `SetRotation` (1.12 registers it only on PlayerModel,
-/// `0x84f1fc`/`0x505f00`, and the world-map arrow that justified it is a Model frame now — see
-/// `region/paint.rs` at its old site), `SetPortraitToTexture` (1.12 has it as an engine GLOBAL,
-/// never a Texture method — `region.rs` registers it there, and a test pins the absence), and
-/// `SetSize`, the Era geometry verb that was in neither client map and that nothing outside our
-/// own test scaffolding called (decision 2142's census). The 1244/1245 landing partitioned rather
-/// than pruned and said the pruning was a separate question per name; this is the answer to three
-/// of them.
-///
-/// Going the other way: `GetBlendMode`, `SetTexCoordModifiesRect` and `GetTexCoordModifiesRect`
-/// joined the list, all three of them in the client's Texture map `0x87c128` (`0x79a890` /
-/// `0x79c080` / `0x79c120`), and all three of them missing here until then.
+/// Texture-only, each in the client's Texture map (`0x87c128`): `GetVertexColor` though
+/// `SetVertexColor` is shared, and `SetGradientAlpha`, not FontString's `SetAlphaGradient`. 1.12
+/// has no Texture `SetSize` or `SetRotation` (PlayerModel's, `0x84f1fc`/`0x505f00`).
 pub(crate) const TEXTURE_ONLY_METHODS: [&str; 12] = [
     "SetGradient",
     "SetGradientAlpha",
@@ -376,14 +319,8 @@ pub(crate) const TEXTURE_ONLY_METHODS: [&str; 12] = [
     "GetVertexColor",
 ];
 
-/// **FontString-only** — the font/text/justify/shadow block plus the string metrics.
-///
-/// **Every name here is the client's own now.** Three of ours were parked in this list:
-/// `GetStringHeight` went first (1251 — byte-verified absent, and ours was a byte-identical
-/// duplicate of `GetHeight`), and `SetFormattedText` (not among the client's 32) and
-/// `SetSize` (the Era geometry verb the Texture list carried too) went with 2142's census, which
-/// found neither in the stock chain nor in either addon corpus. The era spelling of
-/// `SetFormattedText` is `SetText(format(fmt, ...))`; of `SetSize`, `SetWidth` + `SetHeight`.
+/// FontString-only: the font, text, justify and shadow block and the string metrics.
+/// `GetStringHeight`, `SetFormattedText` and `SetSize` are not 1.12 FontString methods.
 pub(crate) const FONTSTRING_ONLY_METHODS: [&str; 21] = [
     "SetFont",
     "GetFont",
@@ -408,6 +345,7 @@ pub(crate) const FONTSTRING_ONLY_METHODS: [&str; 21] = [
     "SetAlphaGradient",
 ];
 
+/// The Region method map (`0xcf54b4`): the 19 names every region leaf reaches on a miss.
 pub(crate) const REGION_MAP_METHODS: [&str; 19] = [
     "GetObjectType",
     "IsObjectType",
@@ -432,54 +370,25 @@ pub(crate) const REGION_MAP_METHODS: [&str; 19] = [
 const REG_WRAPPERS: &str = "__benilla_wrappers";
 const REG_SCRIPTS: &str = "__benilla_scripts";
 
-/// The reserved layout [`crate::layout::Handle`] of the screen root (the client's `CSimpleTop` /
-/// `UIParent`), whose rect is the physical screen. Top-level frames whose `SetPoint` omits a
-/// `relativeTo` anchor to it. Real frame ids are minted from `1` upward so they never collide.
+/// The layout handle of the screen root (the client's `CSimpleTop`, not the `UIParent` frame),
+/// which a top-level `SetPoint` without `relativeTo` anchors to; frame ids, from 1, are the rest.
 pub const SCREEN: crate::layout::Handle = 0;
 
-/// The FrameScript handler kinds this host models. The first five are the lifecycle/event set; the
-/// six mouse handlers are driven by the hit-testing API in [`pointer`] ([`UiScript::mouse_move`] /
-/// [`mouse_button`](UiScript::mouse_button) / [`mouse_wheel`](UiScript::mouse_wheel)) — the app-side
-/// event feed (net/window → these calls) is the Bevy side's job (decision 0068). `OnValueChanged`
-/// is shared by the StatusBar (RF-28 `+0x32c`) and the Slider (`+0x330`; decision 0250) — one name,
-/// each kind dispatching to its own value-changed slot. The eight
-/// `On*Pressed`/text/focus slots are the EditBox's specialized scripts (RF-0082 §2): a focused EditBox
-/// fires ONLY these, never generic `OnKeyDown`/`OnChar` (its C++ override replaces those slots).
-/// `OnHorizontalScroll`/`OnVerticalScroll`/`OnScrollRangeChanged` are the ScrollFrame's own slots
-/// (decision 0112; the reference's `[+0x32c]`/`[+0x334]`/`[+0x33c]`, script-name map `0x786c40`).
-/// `OnHorizontalScroll` joined the other two with the horizontal offset pair — it is fired by
-/// `SetHorizontalScroll`, which is what earns it the row below.
-/// `OnDragStart`/`OnDragStop`/`OnReceiveDrag` are the drag trio (decision 0216 §3) — driven by
-/// `RegisterForDrag` + the same mouse path as the six mouse handlers above, not a separate one.
-/// `OnColorSelect` is the ColorSelect's own slot (RF-28 `+0x338`), fired by its `SetColorRGB`.
+/// The FrameScript handler kinds `SetScript` accepts, each only with the code that fires it
+/// ([`crate::script::object::events_regions::set_script`]). The list is flat, where the reference
+/// resolves names per widget type (base map `0x76a0d0` plus the type's own; a `<Frame>` has no
+/// `OnClick`), so any widget accepts any kind here.
 ///
-/// **Every name here is FIRED by something.** A kind that the engine can accept but never raise is
-/// strictly worse than the `SetScript: unsupported script` error it replaces — the addon's handler
-/// silently never runs and nothing anywhere says so (the bug class decisions 1203/1205/1211 each
-/// record). So a script name earns its row here only together with the code that fires it, and the
-/// names the reference has that we do NOT fire stay OUT, with the reason recorded at
-/// [`crate::script::object::events_regions::set_script`].
-///
-/// **This list is FLAT; the reference's set is per widget type** (RF-0028's script-name→slot
-/// resolvers: base map `0x76a0d0` + the type's own additions — a `<Frame>` has no `OnClick`). That
-/// divergence is deliberate and measured, and the 1751 migration has been shrinking the debt it
-/// covers. Our own FrameXML used to rely on it in 9 places; seven of them were
-/// `PlayerFrame`/`TargetFrame`/`PetFrame`/`PartyMemberFrame1-4` declared as mouse-enabled
-/// `<Frame>`s carrying `OnClick` in our transcribed `UnitFrames.xml`, and that file is gone — the
-/// reference declares all seven as `<Button>`, which carries `OnClick` by type. What is left of
-/// ours is `ChatFrame1`/`ChatFrame2`, plus the corpus's 21 (20 `EditBox` + 1 `<Frame>`
-/// `OnEscapePressed`), all of which fire today ([`button::click_button`]'s "plain frames can carry
-/// one too" arm). Going per-type is the faithful shape and is what would give us `HasScript` (948
-/// corpus call sites across 91 addons); it removes working behaviour from the 23 sites that remain,
-/// so it is still a change to make deliberately rather than as a side effect of widening this list
-/// — but the FrameXML half of "with FrameXML fixed first" is most of the way there now.
+/// `OnValueChanged` is the StatusBar's (`+0x32c`) and the Slider's (`+0x330`) own slot; the
+/// ScrollFrame's three scroll kinds are `+0x32c`/`+0x334`/`+0x33c` (script-name map `0x786c40`).
+/// The EditBox's vtable (`0x81c910`) replaces the key and char slots: an EditBox never fires
+/// `OnKeyDown`, and fires `OnChar` only from `Insert`, with the inserted text (`0x77c13c`).
 const SCRIPT_KINDS: [&str; 39] = [
     "OnLoad",
     "OnEvent",
     "OnUpdate",
-    // The model pane's two: fired by the tick's model pass — `OnUpdateModel` at the top of every
-    // paint of a visible pane, `OnAnimFinished` when a clamped sequence completes (decision 2007;
-    // `object::events_regions::set_script`'s doc has the sites).
+    // The model pane's two, fired by the tick's model pass (`tick_model_panes`): `OnUpdateModel`
+    // at the top of a visible pane's paint, `OnAnimFinished` when the armed sequence completes.
     "OnUpdateModel",
     "OnAnimFinished",
     "OnShow",
@@ -498,9 +407,7 @@ const SCRIPT_KINDS: [&str; 39] = [
     "OnTextChanged",
     "OnTextSet",
     // The caret flush's own (`0x77da80`), fired by the tick's `drain_cursor_changed` when the
-    // caret has moved — the edge `ScrollingEdit_OnCursorChanged` + `ScrollingEdit_OnUpdate` scroll
-    // a multiline box by. It earns its row here the way this list's rule requires: together with
-    // the code that fires it (decisions 2135/2141).
+    // caret moved: the edge `ScrollingEdit_OnCursorChanged` scrolls a multiline box by.
     "OnCursorChanged",
     "OnEditFocusGained",
     "OnEditFocusLost",
@@ -510,95 +417,53 @@ const SCRIPT_KINDS: [&str; 39] = [
     "OnDragStart",
     "OnDragStop",
     "OnReceiveDrag",
-    // A release over a message-frame hyperlink span (`OnHyperlinkClick(link, text, button)` —
-    // the ChatFrameTemplate wires it to SetItemRef; decision 0288 P2).
+    // A release over a message-frame hyperlink span, `OnHyperlinkClick(link, text, button)`;
+    // `ChatFrameTemplate` passes it to `SetItemRef` (`ChatFrame.xml:15`, `ChatFrame.lua:1534`).
     "OnHyperlinkClick",
-    // The GameTooltip's engine-fired widget scripts (decision 0274; the real template wires all
-    // three: money render, money clear, world-hover default placement).
+    // The GameTooltip's engine-fired scripts: money render, money clear and world-hover default
+    // placement, all three wired by the stock template (`GameTooltipTemplate.xml:617-625`).
     "OnTooltipAddMoney",
     "OnTooltipCleared",
     "OnTooltipSetDefaultAnchor",
-    // The ColorSelect's own slot (RF-28 `0x78b4f0` script-map, `+0x338`): `OnColorSelect(r, g, b)`
-    // — how the colour picker paints its preview swatch, and how TipBuddy's two private
-    // `<ColorSelect>` frames learn a colour changed.
+    // The ColorSelect's own slot (script map `0x78b4f0`, `+0x338`), fired by its `SetColorRGB`.
     "OnColorSelect",
-    // The Button/CheckButton double click (RF-28 script-map `0x778c50`, `+0x4d4`) —
-    // `OnDoubleClick(self, button)`, fired by [`pointer`]'s release-edge detector *instead of* the
-    // second `OnClick`, 300 ms (wow-re `ui/scratch/button-doubleclick-law.md`, a §5 cross-check
-    // dispatched from this work). **The corpus's
-    // single biggest script gap**: 250 call sites across 85 addons, and the *only* thing behind the
-    // harness's entire `SetScript: unsupported script` blocker row — 8 addons, 5 dying at load and
-    // 3 at session start, every one of them a FuBar plugin or a Titan panel button
-    // (`FuBarPlugin-2.0:CreateBasicPluginFrame` wires one, unguarded, on its panel Button).
+    // The Button/CheckButton double click (script map `0x778c50`, `+0x4d4`), fired by
+    // [`pointer`]'s release edge in place of the second `OnClick` within 300 ms (`0x77937b`).
     "OnDoubleClick",
-    // The layout event (base map `0x76a0d0` `+0x120`), fired from the resolve pass by
-    // [`crate::layout::size_changed`]'s byte-verified epsilon test — see
-    // [`UiScript::resolve_layout`]. `OnSizeChanged(self, width, height)`.
+    // The layout event (base map `0x76a0d0`, `+0x120`), fired by the resolve pass on a size change.
     "OnSizeChanged",
-    // The three KEY channels, unblocked by [`keyboard`]'s walk (wow-re
-    // `scratch/frame-key-script-delivery.md`, VERIFIED). They were the standing exception in
-    // [`object::events_regions`]'s note — accepted only once something fired them, which is that
-    // module's whole rule. `OnKeyUp` rides in with the other two deliberately: it is *gated* today
-    // (a frame carrying only an OnKeyUp consumes every key-down and runs nothing — the reference's
-    // own asymmetry) even though this engine's host feeds no key-up to fire it with, and accepting
-    // the name is what makes that consumption reachable.
+    // The key channels, fired by [`keyboard`]'s walk (`0x765f10`). `OnKeyUp` never fires, as the
+    // host feeds no key-up, but a frame carrying only `OnKeyUp` still consumes every key-down and
+    // runs nothing, the reference's own asymmetry.
     "OnChar",
     "OnKeyDown",
     "OnKeyUp",
 ];
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// UiScript — the public host
+// UiScript: the public host
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// The Lua scripting host. Owns the mlua VM; the frame arena, layout store, and event registry live
-/// inside it (in `lua.app_data`, per the MAXCSTACK discipline) and are driven through this API.
-///
-/// Construction sandboxes the VM (removes `io`/`os`/`package`/`require`/`dofile`/`loadfile`/`debug`,
-/// text-only chunk loading — see [`stdlib`]), installs the WoW stdlib layer (the global aliases, the
-/// positional `format`, the `strsplit` family, `getglobal`/`setglobal`, `wipe`, …), and installs the
-/// FrameScript object model (`CreateFrame` + the widget/region method surface, the shared metatables).
-///
-/// The host surface is split, `impl UiScript` blocks beside their concern (the `layout.rs` pattern):
-/// the render-list builder in [`extract`], the per-frame runtime loop in [`tick`], the EditBox text
-/// seam in [`editbox::seam`], the layout resolve in [`layout`], and the pointer/hit-test in
-/// [`pointer`]. What stays here is construction and the small host-facing state pushes/queries.
+/// The Lua scripting host: owns the VM, whose `Model` lives in `lua.app_data`. Its `impl` blocks
+/// sit beside their concerns: [`extract`], [`tick`], [`editbox::seam`], [`layout`] and [`pointer`].
 pub struct UiScript {
     lua: Lua,
-    /// VM instructions executed, counted only while a budget is installed
-    /// ([`UiScript::set_instruction_budget`]). `Arc` because the hook callback outlives this
-    /// borrow; `Relaxed` because nothing orders against it — it is a bound, not a clock.
+    /// VM instructions counted while a budget is installed ([`UiScript::set_instruction_budget`]).
     instructions: std::sync::Arc<std::sync::atomic::AtomicU64>,
-    /// **This VM's identity** — see [`UiScript::session`].
     session: u64,
 }
 
-/// Hands out [`UiScript::session`] ids. Process-global and monotone, so an id is never reused and
-/// two of them can be compared without holding either VM.
+/// Hands out [`UiScript::session`] ids: process-global and monotone, so an id is never reused.
 static NEXT_SESSION: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
 
-/// How often the instruction hook fires — the resolution of an instruction budget.
-///
-/// mlua's own documentation warns that a low value "can incur a very high overhead", and nothing
-/// wants a precise bound: the question a budget answers is "is this chunk ever going to stop?",
-/// where being out by a million instructions costs nothing and firing every instruction would cost
-/// the whole survey's runtime.
+/// How often the instruction hook fires: an instruction budget's resolution (low values cost).
 pub const INSTRUCTION_HOOK_STEP: u32 = 1_000_000;
 
-/// The chunk name the CLIENT gives an addon's file: `Interface\AddOns\<Folder>\<File>`.
-///
-/// Backslashes, and the `Interface\AddOns\` prefix, because addons PARSE this. `FuBarPlugin-2.0`
-/// derives each plugin's own folder from a stack trace —
-/// `string.find(debugstack(6, 1, 0), "\\AddOns\\(.*)\\")` (`FuBarPlugin-2.0.lua:752`) — and
-/// feeds the capture straight into `format("Interface\\AddOns\\%s\\icon", self.folderName)`.
-/// With no name set, mlua defaults the chunk to the Rust caller location, the pattern misses,
-/// `folderName` is nil, and every FuBar plugin dies formatting it. That was 20 addons.
-///
-/// The greedy `(.*)` in their pattern is why the FILE has to be in the name too: it captures up to
-/// the LAST backslash, so `…\AddOns\FuBar_BagFu\FuBar_BagFu.lua` yields `FuBar_BagFu`. A name
-/// stopping at the folder would capture the empty string.
+/// The chunk name the 1.12 client gives an addon's file, `Interface\AddOns\<Folder>\<File>`,
+/// backslashed and with the file, because addons parse it: `FuBarPlugin-2.0` finds its folder with
+/// the greedy `\\AddOns\\(.*)\\` over `debugstack`, which needs the file after the folder.
 pub fn addon_chunk_name(folder: &str, file: &str) -> String {
-    // `@` is Lua's "this chunk is a file" marker; the traceback then prints the path plainly.
+    // `@` marks the chunk as a file, so a traceback prints the path plainly.
     format!("@Interface\\AddOns\\{folder}\\{}", file.replace('/', "\\"))
 }
 
@@ -607,8 +472,8 @@ impl UiScript {
     pub fn new() -> mlua::Result<UiScript> {
         let lua = Lua::new();
         lua.set_app_data(Model::new());
-        // Before anything can fire a handler, and while nothing holds an app-data borrow — the two
-        // conditions the profiler's slot has to be installed under (decision 1395).
+        // Before anything can fire a handler and while no app-data borrow is held, as the
+        // profiler's slot requires.
         handler_prof::install(&lua);
 
         addon::install(&lua)?;
@@ -621,12 +486,12 @@ impl UiScript {
         client::install(&lua)?;
         screenshot::install(&lua)?;
         stdlib::sandbox(&lua)?;
-        // Before the stdlib layer, so its aliases bind the 5.0-shaped functions (decision 1194).
+        // Before the stdlib layer, so its aliases bind the 5.0-shaped functions.
         lua50::install(&lua)?;
         stdlib::install(&lua)?;
         object::install(&lua)?;
-        // After `object` (it reuses the frame side's `publish_global`), before any FrameXML is
-        // loaded — `Loader::do_font` publishes into the tables this builds.
+        // After `object`, whose `publish_global` it reuses, and before any FrameXML loads:
+        // `Loader::do_font` publishes into the tables this builds.
         font::install(&lua)?;
         unit::install(&lua)?;
         party::install(&lua)?;
@@ -712,66 +577,26 @@ impl UiScript {
         Ok(s)
     }
 
-    /// The embedded VM — for the Bevy plugin / TOC-XML loader to add the game-state API bindings
-    /// (decision 0068 §1: "the Bevy side owns … the API bindings that touch ECS/net") on top of the
-    /// object model this crate installs.
+    /// The embedded VM, for the app and the loader to add their bindings over this object model.
     pub fn lua(&self) -> &Lua {
         &self.lua
     }
 
-    /// **Which VM this is** — a fresh number for every [`UiScript::new`], never reused.
+    /// Which VM this is: a fresh number per [`UiScript::new`], never reused, so anything the host
+    /// seeded into a VM is valid only while this still matches.
     ///
-    /// The client destroys its Lua state and builds another several times over a login cycle, so a
-    /// host that remembers *what it last pushed into the VM* is remembering something that may no
-    /// longer exist. Anything the host seeded — a registry, a catalog, a change-detection memo — is
-    /// only valid for the session it was seeded into, and this number is what says so.
-    ///
-    /// **The addresses, corrected** (2226; this doc carried `0x490bd0` ↔ `0x48fbf0` from 1290 and
-    /// that pair is wrong). `ds:0xceef74` is a single global *slot* holding successive instances,
-    /// written at exactly two sites image-wide: `0x7039ed` opens, `0x703bab` closes. The reset
-    /// choke point `0x703b80` closes-if-present and then **tail-jmps** into the open — which is why
-    /// a `call`-only census of it reads "one state per process" and is wrong. Its three callers are
-    /// `0x48fe97` (inside `UI_Init 0x48fbf0`, unconditional), `0x491231` (`ShutdownGame`,
-    /// unconditional) and `0x46a87b` (the glue builder, gated on its arg). `0x490bd0` destroys the
-    /// frame-script *owner object* (`0x490c97`, vtable `0x81c380` slot+4 = `0x764360`) and nils the
-    /// 216 bindings; it never touches `ds:0xceef74`.
-    ///
-    /// So the boundary is `0x48fe97` ↔ `0x491231`/`0x46a87b`: **the rebuild replaces the state, the
-    /// teardown does not** — and the rebuild lives *inside* the function that loads FrameXML, which
-    /// is why benilla's world entry mints its VM at the top of its own load (2226) rather than
-    /// adopting the character screen's. GlueXML and FrameXML never share an instance.
-    ///
-    /// A host keying its memory on this cannot go stale by omission: a new VM simply does not
-    /// match, so the seed happens again. That is the property, and it is why this is a VM-side fact
-    /// rather than a host-side counter the host must remember to bump.
+    /// The reference keeps one Lua state (`0xceef74`), replaced only by the reset `0x703b80`: from
+    /// `UI_Init` (`0x48fbf0`, at `0x48fe97`) as it loads FrameXML, `ShutdownGame` (`0x491231`) and
+    /// the glue builder (`0x46a87b`), never the UI teardown `0x490bd0`. GlueXML and FrameXML never
+    /// share a state, so world entry mints its VM at the top of its load.
     pub fn session(&self) -> u64 {
         self.session
     }
 
-    /// **Bound how long a chunk may run, so an infinite loop reports instead of hanging.**
-    ///
-    /// A missing capability in this engine has always been a silently WRONG ANSWER — a setter that
-    /// ignores you, a getter that says nil (1203/1205/1211/1230). Decision 1247 met the other kind:
-    /// `date("*t")` returned a string where Lua returns a table, so `Accountant_WeekStart`'s
-    /// `while thisDay ~= weekstart` never terminated and the addon spun the VM forever. That is
-    /// invisible to every instrument we own, because an instrument that never returns produces no
-    /// roster to diff, no column to compare and no error row to read — the 218-addon survey simply
-    /// stopped finishing, and the cause was found by bisecting the corpus BY HAND.
-    ///
-    /// So a caller that runs untrusted chunks can bound them. Past `budget` VM instructions the
-    /// hook raises, and the raise propagates like any other Lua error: the addon reports as failed
-    /// with a distinctive message, and everything after it still runs.
-    ///
-    /// **This is opt-in, and the app arms it only on the world-entry load edge** (decision 1306;
-    /// it began harness-only, e463649e). A real session must not kill a player's addon for being
-    /// slow, so steady state — every OnUpdate, every event — runs unhooked; but a load walk that
-    /// never returns is a client frozen on the loading screen with zero diagnostics (B271's
-    /// class), so the entry edge is bounded and [`Self::clear_instruction_budget`] disarms before
-    /// the session's first frame.
-    ///
-    /// The hook fires every [`INSTRUCTION_HOOK_STEP`] instructions rather than every instruction:
-    /// mlua's own docs warn that a low value "can incur a very high overhead", and the step is the
-    /// resolution of the bound, which nothing here needs to be precise.
+    /// Bound how long a chunk may run: past `budget` VM instructions the hook raises a Lua error,
+    /// so a loop that never ends fails its addon and the rest still runs. The app arms it only for
+    /// the world-entry load, so a hung load reports instead of freezing the loading screen, and
+    /// disarms it ([`Self::clear_instruction_budget`]) before the session's first frame.
     pub fn set_instruction_budget(&self, budget: u64) {
         let used = self.instructions.clone();
         used.store(0, std::sync::atomic::Ordering::Relaxed);
@@ -796,36 +621,21 @@ impl UiScript {
         );
     }
 
-    /// Remove an installed instruction budget — the load edge's disarm (decision 1306): the bound
-    /// covers the world-entry walk, and a session's steady state runs unhooked exactly as before.
-    /// The counter keeps its last value, so [`Self::instructions_used`] still answers for the
-    /// phase that just ended.
+    /// Remove the instruction budget; the counter keeps its value for [`Self::instructions_used`].
     pub fn clear_instruction_budget(&self) {
         self.lua.remove_hook();
     }
 
-    /// VM instructions executed since the last [`Self::set_instruction_budget`], to the resolution
-    /// of [`INSTRUCTION_HOOK_STEP`]. Zero when no budget was ever set — the hook is what counts.
-    ///
-    /// Reported rather than merely used, because the budget has to be CHOSEN from the corpus and a
-    /// number nobody can read is a number nobody can revisit.
+    /// VM instructions since the last [`Self::set_instruction_budget`], to the resolution of
+    /// [`INSTRUCTION_HOOK_STEP`]; zero when no budget was ever set.
     pub fn instructions_used(&self) -> u64 {
         self.instructions.load(std::sync::atomic::Ordering::Relaxed)
     }
 
-    /// Set the screen-root rect from a pixel size (`[0,0]` origin, y-up). Top-level frames anchor to
-    /// it; changing it invalidates the next `resolve`. The app calls this every frame with an
-    /// almost-always-identical size — compared before writing so the per-frame idiom doesn't
-    /// dirty the layout gate's tier 1 (`Model::touch_layout`).
-    ///
-    /// **Returns whether the size actually changed.** Anchors follow the new rect on their own, so
-    /// most of the UI needs nothing; what does not follow is anything that *computed* a seat from
-    /// the old height and stored it — the open-bag stack wraps into a fresh column from
-    /// `GetScreenHeight()`, and that answer is stale the moment the window is resized. The 1.12
-    /// client never had to care (its resolution changed through a restart, and its own
-    /// `DISPLAY_SIZE_CHANGED` listeners are three model panes, none of them the manage pass), but
-    /// benilla runs in a freely resizable window, so the caller re-runs
-    /// `UIParent_ManageFramePositions()` on a true return. Decision 1499.
+    /// Set the screen-root rect from a pixel size (origin `[0,0]`, y-up), compared first so the
+    /// app's every-frame call leaves an unchanged layout clean. On a change (`true`) the caller
+    /// re-runs `UIParent_ManageFramePositions()`: the window resizes freely, and a seat computed
+    /// from `GetScreenHeight()`, like the open-bag stack's column wrap, does not follow anchors.
     pub fn set_screen_size(&mut self, width: f32, height: f32) -> bool {
         let new = Rect::new(0.0, 0.0, height, width);
         let mut model = self.model_mut();
@@ -835,36 +645,25 @@ impl UiScript {
         model.screen = new;
         model.touch_layout();
         drop(model);
-        // The implicit rects are measured in layout units, which follow the aspect (2015).
+        // The implicit rects are in layout units, which follow the aspect.
         self.reapply_implicit_rects();
         true
     }
 
-    /// Replace the Era atlas table (decision 0950) — pushed once at boot, before the XML loads.
-    /// Push the modifier-key state (shift, ctrl, alt) behind `IsShiftKeyDown`/`IsControlKeyDown`/
-    /// `IsAltKeyDown`. The app's input pass calls this BEFORE feeding the frame's mouse events, so
-    /// a click handler's modifier fork (the reference's shift-split / ctrl-dressup /
-    /// shift-pickup) reads the state as of the click.
+    /// Push the modifier state behind `IsShiftKeyDown`/`IsControlKeyDown`/`IsAltKeyDown`; the app
+    /// calls it before the frame's mouse events, so a click handler reads the state of its click.
     pub fn set_modifiers(&mut self, shift: bool, ctrl: bool, alt: bool) {
         let mut model = self.model_mut();
         model.modifiers = (shift, ctrl, alt);
     }
 
-    /// Push the player's WMO-containment state onto every Minimap widget (the client's `0xceaa60`).
-    /// It selects which of the two persisted zoom indices `GetZoom`/`SetZoom` act on, so the zoom
-    /// buttons drive the indoor level while indoors and the outdoor level while outside. The app
-    /// owns the containment test, so it owns this push — call it before the script tick. The
-    /// caller pushes on the inside↔outside edge and whenever [`Self::minimap_widgets_created`]
-    /// moved (a widget born after the last transition still gets told, without paying the arena
-    /// walk every frame).
+    /// Push the player's WMO-containment state (the client's `0xceaa60`) onto every Minimap: it
+    /// picks which persisted zoom index `GetZoom`/`SetZoom` act on. Call it before the script
+    /// tick, on each inside/outside edge and whenever [`Self::minimap_widgets_created`] moves.
     pub fn set_minimap_inside(&mut self, inside: bool) {
         self.for_each_minimap(|m| m.inside = inside);
     }
 
-    /// Run `f` over every live Minimap widget's state. Goes through the arena's Minimap registry
-    /// rather than a full `iter_frames_mut`, for the reason that registry exists: a corpus UI is
-    /// three to four thousand frames and there is normally exactly one Minimap, and one of these
-    /// feeds ([`Self::set_minimap_player_facing`]) runs every frame.
     fn for_each_minimap(&mut self, mut f: impl FnMut(&mut crate::widget::MinimapState)) {
         let mut model = self.model_mut();
         for h in model.arena.minimap_kinds().to_vec() {
@@ -876,17 +675,9 @@ impl UiScript {
         }
     }
 
-    /// Push the player's world facing (radians) onto every Minimap's **player-arrow** `Model` —
-    /// the client's `CMinimap::SetPlayerFacing 0x4eb8e0`, whose whole 34-byte body is
-    /// `[minimap+0x33c] = arg` then, guarded on non-null, `[[minimap+0x338]+0x39c] = arg`: a raw
-    /// dword copy into the same field `Model:SetFacing 0x76dce0` writes, with **no negation, offset
-    /// or unit change**. Its one caller (`0x4eb0a4`–`0x4eb0b1`) feeds it the player's `GetFacing()`
-    /// straight off the FPU stack, so what an addon reads back is the unit's orientation exactly.
-    ///
-    /// This is what makes `({Minimap:GetChildren()})[9]:GetFacing()` — Questie's `GetPlayerFacing`,
-    /// and pfQuest's `compat/client.lua` — return the truth rather than the ctor default `0`, which
-    /// is the difference between a waypoint arrow that points at the waypoint and one aimed
-    /// permanently north. Called every frame by the app, which owns the player.
+    /// Push the player's facing (radians) onto every Minimap's player-arrow `Model`, every frame,
+    /// raw: `CMinimap::SetPlayerFacing` (`0x4eb8e0`, fed at `0x4eb0a4`–`0x4eb0b1`) copies it into
+    /// the field `Model:SetFacing` (`0x76dce0`) writes, so the arrow's `GetFacing()` reads it.
     pub fn set_minimap_player_facing(&mut self, facing: f32) {
         let mut model = self.model_mut();
         let arrows: Vec<crate::widget::FrameHandle> = model
@@ -907,32 +698,19 @@ impl UiScript {
         }
     }
 
-    /// Publish the live minimap ping's **normalized** offsets from the widget centre (fractions
-    /// of the widget side, x right / y up), or `None` when no ping is live —
-    /// `Minimap:GetPingPosition()`'s source. The app recomputes this from the ping's WORLD point
-    /// every frame a ping is live, before the tick, so a poller sees it track the world as the
-    /// player walks.
-    ///
-    /// One field, not one per widget: there is exactly one ping (decision 1596), and the old
-    /// per-widget push walked the whole ~3k-frame arena every frame a ping was live.
+    /// Publish `Minimap:GetPingPosition()`'s offsets from the widget centre, as fractions of its
+    /// side (x right, y up); the app recomputes them from the ping's world point each frame.
     pub fn set_minimap_ping(&mut self, ping: (f32, f32)) {
         self.model_mut().minimap_ping = ping;
     }
 
-    /// Drain a `Minimap:PingLocation(x, y)` call — centre-relative offsets in **UI units**
-    /// (x right, y up). The app converts: UI units × the seam scale = window px, ÷ the live
-    /// `px_per_yd` = yards, and the click resolves against the geometry drawn in the same frame.
+    /// Drain a `Minimap:PingLocation(x, y)`: centre-relative offsets in UI units, x right, y up.
     pub fn take_minimap_ping_request(&mut self) -> Option<(f32, f32)> {
         self.model_mut().minimap_ping_request.take()
     }
 
-    /// The mask art the Minimap widget asks its renderer for — `Minimap:SetMaskTexture`'s value,
-    /// or `None` while no widget has set one (the app then keeps
-    /// [`crate::widget::MINIMAP_DEFAULT_MASK`]).
-    ///
-    /// The **first** Minimap in the registry answers, not every one: the mask is a property of the
-    /// map the app draws, and the app draws one. (Everything else in `MinimapState` is per widget
-    /// because the Lua API reads it back per widget; this has no getter in 1.12 to read back.)
+    /// `Minimap:SetMaskTexture`'s value from the first Minimap (the app draws one map), `None`
+    /// until one is set, while the app keeps [`crate::widget::MINIMAP_DEFAULT_MASK`].
     pub fn minimap_mask_texture(&self) -> Option<String> {
         let model = self.model_ref();
         model.arena.minimap_kinds().iter().find_map(|&h| {
@@ -943,20 +721,15 @@ impl UiScript {
         })
     }
 
-    /// Monotonic count of Minimap widgets ever created in this VM — the O(1) signal that a new
-    /// one exists and needs the containment state pushed.
+    /// Minimap widgets ever created in this VM: a move means a new one needs the containment state.
     pub fn minimap_widgets_created(&self) -> u64 {
         self.model_ref().arena.minimap_created()
     }
 
-    /// Seed every Minimap widget's two zoom indices from the persisted levels — the client's
-    /// minimap reset path copying each CVar object's parsed int into its live index
-    /// (`[0x86f698] ← [[0xb4b410]+0x28]`, `[0x86f69c] ← [[0xb4d90c]+0x28]`; wow-re
-    /// `wmo-interior-minimap.md`, VERIFIED). Called **once**, when the in-game UI materializes and
-    /// the widget exists — not per frame: from then on the widget's index is the live truth and
-    /// `Minimap:SetZoom` keeps the CVar following it, so a repeated push would fight the +/- buttons.
-    /// Both indices clamp into `[0, MINIMAP_ZOOM_LEVELS)` exactly like `set_zoom`, so a hand-edited
-    /// `config.toml` cannot seed an out-of-range level (decision 1131).
+    /// Seed every Minimap's two zoom indices from the persisted CVars, as the client's reset path
+    /// does (`[0x86f698] ← [[0xb4b410]+0x28]`, `[0x86f69c] ← [[0xb4d90c]+0x28]`). Call it once,
+    /// when the UI and the widget exist: from then on `Minimap:SetZoom` keeps the CVar following
+    /// the widget, and a repeated seed would fight the +/- buttons.
     pub fn set_minimap_zoom(&mut self, zoom: u8, inside_zoom: u8) {
         let top = crate::widget::MINIMAP_ZOOM_LEVELS - 1;
         let (zoom, inside_zoom) = (zoom.min(top), inside_zoom.min(top));
@@ -966,33 +739,19 @@ impl UiScript {
         });
     }
 
-    /// Load and run a Lua chunk (text-only; the sandbox rejects bytecode). Errors propagate to the
-    /// caller (a *load-time* error is the caller's to see; *handler* errors during events go to
-    /// [`UiScript::errors`]).
+    /// Load and run a text chunk; handler errors during events go to [`UiScript::errors`] instead.
     pub fn run(&self, chunk: &str) -> mlua::Result<()> {
         self.run_chunk(chunk.as_bytes())
     }
 
-    /// [`UiScript::run`] over a chunk that came off disk, which is **bytes** (decision 1193).
-    ///
-    /// The reference slurps the file and hands the buffer to `luaL_loadbuffer` with no conversion
-    /// (wow-5875-re `system/ui/ui.md`), and Lua 5.0 strings are byte strings — so a cp1252 locale
-    /// file runs there and its literals carry the raw bytes. Reading such a file as `String` is
-    /// what made 76 of a real corpus's `.lua` files read as *absent* rather than as text with an
-    /// odd glyph. The two front-door transforms the reference's own compiler applies — the UTF-8
-    /// BOM strip and the `#`-line skip — are applied here ([`crate::source::chunk`]).
+    /// [`UiScript::run`] over a file's bytes: the reference hands the file (`0x704bc0`) to
+    /// `luaL_loadbuffer` (`0x6f5690`) unconverted, so a cp1252 file's literals keep their bytes.
+    /// Its compiler's UTF-8 BOM strip and `#`-line skip apply here ([`crate::source::chunk`]).
     pub fn run_chunk(&self, chunk: &[u8]) -> mlua::Result<()> {
         self.run_chunk_named(chunk, "(chunk)")
     }
 
-    /// Run a chunk under the name the CLIENT would give it — `Interface\AddOns\<Folder>\<File>`
-    /// for an addon file (build it with [`addon_chunk_name`]).
-    ///
-    /// The name is not cosmetic. Without `set_name`, mlua defaults a chunk to the **Rust** caller
-    /// location, so every error an addon raised was reported against `crates/benilla-ui/src/...`
-    /// — wrong in any error an addon shows a player, and load-bearing for the addons that PARSE a
-    /// traceback. `FuBarPlugin-2.0.lua:752` derives a plugin's own folder with
-    /// `string.find(debugstack(6, 1, 0), "\\AddOns\\(.*)\\")`, which cannot match a Rust path.
+    /// Run a chunk under the name the 1.12 client gives it ([`addon_chunk_name`] for addon files).
     pub fn run_chunk_named(&self, chunk: &[u8], name: &str) -> mlua::Result<()> {
         self.lua
             .load(crate::source::chunk(chunk))
@@ -1001,35 +760,20 @@ impl UiScript {
             .exec()
     }
 
-    /// Load and evaluate a Lua chunk, returning its result. Primarily for tests / one-shot queries.
+    /// Load and evaluate a Lua chunk, returning its result: for tests and one-shot queries.
     pub fn eval<T: mlua::FromLuaMulti>(&self, chunk: &str) -> mlua::Result<T> {
         self.lua.load(chunk).set_mode(mlua::ChunkMode::Text).eval()
     }
 
-    /// **How many values does `expr` return?** — the return-shape question, asked at the host
-    /// boundary instead of inside Lua.
-    ///
-    /// This is what `select('#', expr)` used to answer in ~170 of our own tests. `select` is not a
-    /// 1.12 global and is gone (`lua50::install`), and the replacement is not a workaround: a
-    /// binding's arity is a fact about the **binding ABI**, and on this side of it a multiple
-    /// return already *is* a `MultiValue` whose length nothing can round off. It keeps the property
-    /// the arity gates rest on — **zero values and one `nil` are different answers**, `0` and `1`
-    /// (`binding_abi`'s §2), which is exactly what a `Option<T>` return type cannot tell apart.
-    ///
-    /// `expr` is a Lua **expression**, not a chunk: pass `"GetItemInfo(1)"`, not `"return …"`.
-    /// A raise propagates — a call that errors has no arity, and swallowing that into `0` is how a
-    /// broken binding scores as a zero-return verb.
-    ///
-    /// The one place this cannot serve is a probe that has to hold the count *inside* Lua (a
-    /// `pcall` loop over generated calls, as `shape_gate` runs). There the 5.0 spelling is 1.12's
-    /// own and reads the same: `(function(...) return arg.n end)(expr)`.
+    /// How many values the Lua expression `expr` returns (`"GetItemInfo(1)"`, not a chunk), zero
+    /// values and one `nil` told apart; a raise propagates. `select` is not a 1.12 global, so
+    /// inside Lua the count is `(function(...) return arg.n end)(expr)`.
     pub fn arity(&self, expr: &str) -> mlua::Result<usize> {
         let values: mlua::Variadic<mlua::Value> = self.eval(&format!("return {expr}"))?;
         Ok(values.len())
     }
 
-    /// The owning frame's name for an [`ExtractedQuad`] target — a debugging affordance for
-    /// capture/probe tooling, which sees quads but not widgets ("whose quad is this?").
+    /// The owning frame's name for an [`ExtractedQuad`] target, for tooling that sees only quads.
     pub fn quad_owner_name(&self, target: ZTarget) -> Option<String> {
         let model = self.model_ref();
         let fh = match target {
@@ -1039,10 +783,8 @@ impl UiScript {
         model.arena.frame(fh)?.name.clone()
     }
 
-    /// Append a line to a named [`FrameKind::ScrollingMessageFrame`] (the app's chat feed → the seam,
-    /// the analogue of the loot/merchant snapshot pushes). `r`/`g`/`b` are `0..1`; the engine
-    /// byte-quantizes them round-half-up and drives the line's alpha via the fade. A missing frame,
-    /// or one of another kind, is a no-op (returns `false`) — the app decides whether that's a bug.
+    /// Append a line from the app's chat feed to the named ScrollingMessageFrame: `r`/`g`/`b` in
+    /// `0..1` are byte-quantized round-half-up, and the fade drives the line's alpha.
     pub fn add_chat_message(&mut self, frame: &str, text: &str, r: f32, g: f32, b: f32) -> bool {
         let mut model = self.model_mut();
         let Some(h) = model.arena.lookup(frame) else {
@@ -1057,10 +799,7 @@ impl UiScript {
         }
     }
 
-    /// Open the named EditBox for typing: show it and grab keyboard focus (so [`has_keyboard_focus`]
-    /// gates the world's keys). The app's chat-open key (ENTER) drives this; the box's own
-    /// `OnEnterPressed`/`OnEscapePressed` handlers hide + `ClearFocus` it on submit/cancel. A missing
-    /// frame, or one that isn't an EditBox, is a no-op (`false`).
+    /// Show the named EditBox and give it keyboard focus, for the app's chat-open key (ENTER).
     pub fn focus_editbox(&mut self, name: &str) -> bool {
         let mut model = self.model_mut();
         let Some(h) = model.arena.lookup(name) else {
@@ -1077,34 +816,23 @@ impl UiScript {
         true
     }
 
-    // The EditBox text-UI seam (advance table, caret/selection geometry, clipboard) lives in
-    // `editbox/seam.rs` — an `impl UiScript` block beside its concern, the layout.rs pattern.
-
-    /// Drain the chat lines submitted through the input EditBox since the last call (the
-    /// `SubmitChatInput` Lua binding queued them). The app parses each into an outbound chat command.
+    /// Drain the chat lines `SubmitChatInput` queued since the last call, for the app to parse.
     pub fn take_chat_input(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().chat_input)
     }
 
-    /// Queue a line as if it had been typed into the chat EditBox and submitted — the headless
-    /// twin of `SubmitChatInput`, for scripted probes (`WOW_PROBE_CHAT`). Going through this seam
-    /// rather than straight to the wire is what lets a probe drive **client-side** slash commands
-    /// (`/duel`, `/reaction`); a plain line or a `.gm`-style server command still reaches the wire
-    /// exactly as before, because that is what the chat drain does with anything it doesn't own.
+    /// Queue a line as if typed into the chat EditBox and submitted, for probes (`WOW_PROBE_CHAT`).
     pub fn push_chat_input(&mut self, line: String) {
         self.model_mut().chat_input.push(line);
     }
 
-    /// Whether Tab was pressed in the chat edit box since the last call (`BenillaChatTabPressed`)
-    /// — the whisper-target cycle's trigger (decision 0288 P5).
+    /// Whether Tab was pressed in the chat edit box since the last call: the whisper cycle's cue.
     pub fn take_chat_tab(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().chat_tab)
     }
 
-    /// Replace the frame-keyed hyperlink spans (`(frame, rect, link, markup)`, rects in the
-    /// engine's y-up screen space) — the app feeds these each frame after rasterizing message
-    /// lines (it alone knows where the glyphs actually landed). A release inside a span fires
-    /// `OnHyperlinkClick(link, markup, button)` on the owning frame ([`pointer`]).
+    /// Replace the hyperlink spans `(frame, y-up rect, link, markup)` the app rasterized this
+    /// frame; a release inside one fires `OnHyperlinkClick` on its frame ([`pointer`]).
     pub fn set_link_spans(&mut self, spans: Vec<(FrameHandle, Rect, String, String)>) {
         let mut model = self.model_mut();
         model.link_spans.clear();
@@ -1117,16 +845,7 @@ impl UiScript {
         }
     }
 
-    /// Invoke a compiled handler `func` under the RF-0025 frame-globals convention (`this`/`self` =
-    /// `wrapper`), the same set/restore path registry handlers use. For the [`crate::loader`], which
-    /// holds the `OnLoad` `Function` directly (to fire it bottom-up) rather than through the registry:
-    /// this keeps the convention in one home instead of duplicating it. Errors are returned so the
-    /// caller routes them (the loader records them in its own report).
-    /// Whether the frame with this global name is effectively visible — shown, with every ancestor
-    /// shown (`IsVisible()`'s answer, read host-side). `false` for a name no live frame carries.
-    /// The read side of a window for a host that keeps state per window: the dressing-room feed
-    /// empties its booth when `DressUpFrame` hides, and the stock file has no hook of ours in its
-    /// OnHide to say so (1969). A linear scan, like [`Self::model_pane`], for the same reason.
+    /// Whether the frame with this global name is shown with every ancestor (`IsVisible()`).
     pub fn frame_visible(&self, name: &str) -> bool {
         self.model_ref()
             .arena
@@ -1134,12 +853,8 @@ impl UiScript {
             .any(|(_, f)| f.name.as_deref() == Some(name) && f.effective_visible)
     }
 
-    /// The effective alpha of the frame with this global name while it is effectively visible,
-    /// `None` when it is hidden or no live frame carries the name. The read side of a frame whose
-    /// pixels a host draws for the engine: the stock `MiniMapPing` is a `<Model>` this engine
-    /// renders nothing for, so the app's ping sprite follows the frame's own show/hide and alpha
-    /// — the lifetime the reference's `Minimap.lua` owns — instead of keeping a clock of its own
-    /// (1974). A linear scan, like [`Self::frame_visible`].
+    /// The named frame's effective alpha while it is effectively visible: the app's minimap ping
+    /// sprite follows the stock `MiniMapPing` `<Model>` this way.
     pub fn frame_effective_alpha(&self, name: &str) -> Option<f32> {
         self.model_ref()
             .arena
@@ -1148,22 +863,15 @@ impl UiScript {
             .map(|(_, f)| f.effective_alpha)
     }
 
-    /// Resolve every frame's rect: sync each frame's effective scale from the arena into its layout
-    /// input, run the [`crate::layout`] graph (screen root as the external base), and cache the
-    /// resolved rects. `GetWidth`/`GetHeight`/`extract` read this cache.
-    /// Frames whose size moved fire `OnSizeChanged` here, once the borrow is released
-    /// ([`event::fire_size_changes`]) — this is the drain the resolver's queue exists for, and the
-    /// one every per-frame host tick runs.
+    /// Resolve and cache every frame's rect, which `GetWidth`/`GetHeight`/`extract` read, then fire
+    /// `OnSizeChanged` for frames whose size moved ([`event::fire_size_changes`]).
     pub fn resolve(&mut self) {
         {
             let mut model = self.model_mut();
             Self::resolve_layout(&mut model);
         }
-        // With a font engine installed ([`Self::set_text_measurer`]) the VM closes the measure
-        // round-trip itself, right here — solve, measure what the solve revealed, solve again.
-        // That is the same two-solve shape the host's own drive loop already runs, moved inside so
-        // a FontString's box is right in the frame its text was set rather than the frame after.
-        // Without an engine this is a no-op and the host's batch pass stays the only answer.
+        // With a font engine installed ([`Self::set_text_measurer`]), measure what the solve
+        // revealed and solve again, so a FontString's box is right in the frame its text was set.
         if self.fill_measures() {
             let mut model = self.model_mut();
             Self::resolve_layout(&mut model);
@@ -1171,14 +879,9 @@ impl UiScript {
         event::fire_size_changes(&self.lua);
     }
 
-    /// Store host measurements for [`MeasureRequest`]s (`(id, w, h, natural_w, key)` — id/key
-    /// verbatim from the request). The next [`UiScript::resolve`] uses `w`/`h` as the FontStrings'
-    /// implicit size.
-    ///
-    /// `w`/`h` are the text **as laid out** (wrapped inside a declared width); `natural_w` is what
-    /// it would take **unwrapped**, and is what `GetStringWidth` reports — see [`MeasuredText`] for
-    /// why the two must not be conflated. For a region with no declared width they are the same
-    /// number, which is why [`Self::set_measured_text_unwrapped`] exists for tests.
+    /// Store host measurements `(id, w, h, natural_w, key)` for [`MeasureRequest`]s; the next
+    /// [`UiScript::resolve`] sizes the FontStrings by `w`/`h`, the text as laid out (wrapped in a
+    /// declared width), while `natural_w` is its unwrapped width, which `GetStringWidth` reports.
     pub fn set_measured_text(&mut self, measures: &[(u32, f32, f32, f32, u64)]) {
         let mut model = self.model_mut();
         for &(id, w, h, natural_w, key) in measures {
@@ -1193,25 +896,19 @@ impl UiScript {
                     natural_w,
                     key,
                 };
-                // The KEY always lands (or the region re-requests its own measure forever); the
-                // EPOCH moves only if the laid-out extent did — see `MeasuredText::layout_moved`.
+                // The key always lands, or the region re-requests forever; the epoch moves only
+                // with the laid-out extent.
                 moved = MeasuredText::layout_moved(d.measured, new);
                 d.measured = Some(new);
             }
             if moved {
-                // Measured extents are the auto-size axes' inputs — the layout gate's read set.
-                // Touched PER REGION rather than once for the batch (decision 1388): the batch
-                // touch could only say "some extent moved", which is exactly the whole-roster
-                // question the ledger exists to stop asking.
+                // Touched per region, so the layout gate need not re-walk the whole roster.
                 model.touch_layout_region(rh);
             }
         }
     }
 
-    /// [`Self::set_measured_text`] for text with **no wrap constraint**, where the laid-out and
-    /// natural widths are by definition the same number. Test-facing: a hand-fed measure for an
-    /// unconstrained string should not have to say `w` twice, and a test that DOES care about the
-    /// distinction (a declared-width region) should be forced to spell it out.
+    /// [`Self::set_measured_text`] for unwrapped text, whose two widths are one; for tests.
     pub fn set_measured_text_unwrapped(&mut self, measures: &[(u32, f32, f32, u64)]) {
         let widened: Vec<_> = measures
             .iter()
@@ -1220,28 +917,8 @@ impl UiScript {
         self.set_measured_text(&widened);
     }
 
-    /// Drop every cached host text metric — FontString measures, message-line row counts, editbox
-    /// advance tables. The host calls this when its **raster environment** changes (a window
-    /// resize / fullscreen toggle / uiScale move — anything that shifts the px-per-unit seam its
-    /// answers were taken under): glyph advances step to whole pixels at the drawn raster size,
-    /// so a metric measured under one environment does not rescale to another — the font-size
-    /// snap alone moves a string's unit width by several percent, which is exactly enough for a
-    /// boot-size measure to fail the post-resize ellipsis fit test and truncate text that fits
-    /// (the director's fullscreen "Contr..." rows). The environment is the host's to watch — the
-    /// engine deliberately never sees the seam scale — so staleness is the host's to declare; the
-    /// round-trips re-answer on the frames that follow (the same one-frame convergence every
-    /// measure already has).
-    /// Force the next [`UiScript::resolve`] to rebuild the **whole** layout graph rather than the
-    /// dirty closure a scoped resolve would (decision 1350) — and to run at all, rather than stop
-    /// at either change gate.
-    ///
-    /// This is the scoped resolve's own falsifier, and it exists so the claim the scope rests on —
-    /// *a node whose own inputs and whose dependencies did not move recomputes to the rect it
-    /// already holds* — is something a test can **disprove** rather than something the engine
-    /// argues. Drive a change, resolve, read the rects; call this, resolve again, read them again;
-    /// they must be identical. `WOW_LAYOUT_VERIFY` makes the same comparison automatically on every
-    /// SETTLED frame; this is for the frames that never settle, which is exactly the hover sweep
-    /// the scope was built for.
+    /// Force the next [`UiScript::resolve`] past both change gates to rebuild the whole layout
+    /// graph: the scoped resolve's falsifier, as a full rebuild must reach the same rects.
     pub fn force_full_layout_resolve(&mut self) {
         let mut model = self.model_mut();
         model.layout_scope.invalidate();
@@ -1250,14 +927,15 @@ impl UiScript {
         model.touch_layout();
     }
 
+    /// Drop every cached host text metric when the host's raster environment changes (resize,
+    /// fullscreen, uiScale): glyph advances snap to whole pixels at the drawn size, so a stale
+    /// measure can fail the ellipsis fit and truncate text that fits.
     pub fn invalidate_text_measures(&mut self) {
         let mut model = self.model_mut();
         for d in model.region_data.values_mut() {
             d.measured = None;
         }
-        // The frame-side caches key on content hashes; a bumped stored key can never equal the
-        // recomputed one, so the next needing-measure sweep re-requests without this method
-        // having to know what the keys hash.
+        // A bumped key never matches the recomputed content hash, so the next sweep re-requests.
         for (_, frame) in model.arena.iter_frames_mut() {
             match &mut frame.kind_state {
                 KindState::ScrollingMessage(smf) => {
@@ -1271,35 +949,20 @@ impl UiScript {
                 _ => {}
             }
         }
-        // Measured extents are auto-size inputs — the layout gate's read set, same as
-        // [`Self::set_measured_text`]'s.
+        // Measured extents are auto-size inputs, the layout gate's read set.
         model.touch_layout();
         // Every stored measure was just wiped; only the whole-roster sweep can re-request them.
         model.touch_measure_all();
     }
 
-    // ── Input: pointer-leaves-window cleanup (decision 0216 §3; the hit-test/mouse dispatch that
-    // used to sit here now lives in [`pointer`]) ─────────────────────────────────────────────────
+    // ── Input: the pointer leaving the window ────────────────────────────────────────────────────
 
-    /// The OS pointer left the window (decision 0216 §3's drag-gesture leak): clears
-    /// [`Model::drag`] AND [`Model::mouse_down_on`] — the two press-tracked states nothing else
-    /// clears when the pointer leaves the window mid-press, since the matching release is never
-    /// fed. Left uncleared, a stale armed [`Model::drag`] would fire a spurious `OnDragStart` the
-    /// instant the pointer re-enters and crosses the threshold against a press point that no
-    /// longer means anything; a stale [`Model::mouse_down_on`] entry would fire a same-frame
-    /// `OnClick` if the pointer re-enters and releases over the very frame it left from. The app
-    /// calls this from the same branch that fires the synthetic `OnLeave` (`ui_script/input.rs`).
+    /// The OS pointer left the window, so no release will be fed: clears [`Model::drag`], which
+    /// would start a drag on re-entry, and [`Model::mouse_down_on`], which would click the frame
+    /// it left. The app calls it where it fires the synthetic `OnLeave`.
     pub fn pointer_left_window(&mut self) {
-        // **A started drag ENDS here, it is not merely forgotten.** The reference cannot reach
-        // this state at all — the OS holds the pointer for the whole of a button-held drag, so its
-        // release always arrives and `OnDragStop` always runs. Ours has no such capture: walk the
-        // cursor off the window edge mid-drag and no release is ever fed. Dropping the gesture
-        // silently (what this did) leaves the addon's `OnDragStop → StopMovingOrSizing` unrun, so
-        // the engine's single `Model::moving` slot stays taken and `object::movable::advance_move`
-        // glues that frame to the cursor for the rest of the session — where it also swallows
-        // every press aimed at whatever is underneath. That is B310: one raid row dragged off the
-        // window edge, and no row could be dragged again. Firing the stop is the faithful end,
-        // because it is the same end the reference's own release gives the handler.
+        // A started drag ends with `OnDragStop`, as the reference's release always ends it; dropped
+        // silently, its `StopMovingOrSizing` never runs and the frame stays glued to the cursor.
         let abandoned = {
             let mut model = self.model_mut();
             cursor::abandon_drag(&mut model)
@@ -1310,96 +973,61 @@ impl UiScript {
         let mut model = self.model_mut();
         let held: Vec<crate::widget::FrameHandle> = model.mouse_down_on.values().copied().collect();
         model.mouse_down_on.clear();
-        // Every button that capture was holding down goes back to NORMAL — the release edge the
-        // OS never fed us (`0x7793de`), without which a button walked off the window edge
-        // mid-press keeps its pushed art for the rest of the session.
+        // Every held button gets the release edge never fed (`0x7793de`), else it stays pushed.
         for h in held {
             button::edge(&mut model, h, crate::widget::ButtonState::on_mouse_up);
         }
-        // …and its one-slot twin `root+0x80`, which the mouse-down raise reads: a capture left
-        // behind would aim the next press's raise at whatever the pointer was last holding.
+        // The capture slot (`root+0x80`) too: a stale one aims the next press's raise at it.
         model.mouse_capture = None;
-        // [`Model::last_click`] is deliberately NOT cleared here. It looks like it belongs in this
-        // list, and the binary says otherwise: `[CButton+0x334]` has exactly three writers
-        // image-wide (the ctor, the fired-double zero, the fired-single stamp) and none of them is
-        // a hide, a disable, or a mouse-leave — so a half-finished double click really does survive
-        // the cursor leaving the window and coming back inside the 300 ms (wow-re
-        // `ui/scratch/button-doubleclick-law.md`, "state hygiene").
-        // A thumb drag in progress when the pointer leaves is abandoned too (decision 0250 §5) —
-        // the release that would end it is never fed, same leak as the drag gesture above.
+        // [`Model::last_click`] stays: `[CButton+0x334]` has no writer on leave, hide or disable,
+        // so a double click survives the cursor leaving and returning within 300 ms.
+        // A slider thumb drag is abandoned too: its release is never fed either.
         model.slider_drag = None;
     }
 
-    // ── Keyboard entry (RF-0082 §1/§2: the EditBox focus + key/char routing) ─────────────────────
+    // ── Keyboard entry ───────────────────────────────────────────────────────────────────────────
     //
-    // benilla speaks *key names*, not scancodes — the host maps its window keycodes to these. The
-    // routing is the client's exactly: if a box is focused it processes and CONSUMES every event; if
-    // none is focused, the topmost effectively-visible `autoFocus` box self-acquires focus and
-    // processes this same event; otherwise nothing is consumed. Today the ways a box gets focus here
-    // are this self-acquire path, a click, and Lua `SetFocus` — the reference has a fourth, an
-    // `autoFocus` box focusing itself on SHOW, which we do not implement yet (the flag's own doc
-    // carries the correction and what it waits on).
+    // Keys arrive by name; the host maps its keycodes. The box routing: a focused box consumes
+    // every event; with none focused, the topmost visible `autoFocus` box takes focus and
+    // processes that same event; otherwise nothing is consumed.
 
-    /// A typed character (may be multi-byte UTF-8) arriving from the host. Routes per §1/§2 and, on a
-    /// focused box, inserts it (numeric/cap/password rules apply) or — for the Ctrl+A control code —
-    /// selects all. Returns `true` if consumed (a focused box consumes every char).
+    /// A typed character (UTF-8) from the host: a focused box inserts it (numeric, cap and
+    /// password rules apply) or, for Ctrl+A's control code, selects all. `true` if consumed.
     pub fn char_input(&mut self, text: &str) -> bool {
-        // The frame walk first ([`keyboard`]): the focused box is a PARTICIPANT in it, at its own
-        // strata/level, so this is not "frames before boxes" — it is the reference's one dispatcher
-        // in the reference's order. An event no frame consumed still falls through to the box
-        // routing, which owns focus acquisition (`autoFocus` self-acquire and kin).
+        // The frame walk first ([`keyboard`]), the focused box a participant at its own strata and
+        // level, as in the reference's one dispatcher; an unconsumed event goes to the box routing.
         keyboard::char_input(&self.lua, text) || editbox::char_input(&self.lua, text)
     }
 
-    /// Paste text from the host OS clipboard into the focused EditBox. The engine-free runtime can't
-    /// reach the clipboard itself, so the app reads it (Cmd+V on macOS / Ctrl+V elsewhere) and hands
-    /// the string here; newlines survive only in a `multiLine` box, other control chars are dropped,
-    /// and the remainder inserts as one edit. Returns `true` if a box consumed it.
+    /// Paste host clipboard text into the focused EditBox as one edit: newlines survive only in a
+    /// `multiLine` box, other control characters drop. `true` if a box consumed it.
     pub fn paste(&mut self, text: &str) -> bool {
         editbox::paste(&self.lua, text)
     }
 
-    /// A non-character key press arriving from the host, by name — the three *box-event* keys
-    /// (`"ENTER"`, `"ESCAPE"`, `"TAB"`) fire their FrameXML scripts; editing keys arrive as
-    /// semantic [`EditAction`]s via [`Self::editbox_action`] instead (the host's per-OS keymap
-    /// owns which chord means what). Routes per §1/§2; a focused box consumes the key even when
-    /// it does nothing with it. Returns `true` if consumed.
+    /// A non-character key by name (`"ENTER"`, `"ESCAPE"`, `"TAB"`); editing keys come through
+    /// [`Self::editbox_action`]. A focused box consumes a key even when it does nothing with it.
     pub fn key_input(&mut self, key: &str) -> bool {
-        // Same two-stage shape as `char_input` — see its note.
+        // The same two stages as `char_input`.
         keyboard::key_input(&self.lua, key) || editbox::key_input(&self.lua, key)
     }
 
-    /// A key the host delivers to a focused EditBox as an [`EditAction`] chord rather than by name
-    /// (BACKSPACE, DELETE, the arrows, HOME, END), offered to the **keyboard frames** first.
-    ///
-    /// Returns `true` if a frame consumed it, in which case the caller must NOT also dispatch the
-    /// chord — and the key's binding must not fire either (consumption suppresses it, wow-re §3).
-    /// A `false` means either nothing wanted it or the focused box owns it; the caller proceeds
-    /// exactly as it did before this entry point existed. See [`keyboard::frame_key_input`] for
-    /// why declining at the box is the faithful answer rather than skipping it.
+    /// An editing key (BACKSPACE, DELETE, the arrows, HOME, END) offered to the keyboard frames
+    /// before the focused box gets it as an [`EditAction`]. On `true` the caller dispatches neither
+    /// the action nor the key's binding (consumption suppresses it, `0x76b7d0`).
     pub fn frame_key_input(&mut self, key: &str) -> bool {
         keyboard::frame_key_input(&self.lua, key)
     }
 
-    /// One semantic text-editing operation on the focused EditBox — the output of the host's
-    /// per-OS keymap (decision 0301). Same routing/consumption law as [`Self::key_input`].
-    /// Returns `true` if consumed.
+    /// One text-editing operation on the focused EditBox, from the host's per-OS keymap.
     pub fn editbox_action(&mut self, action: EditAction) -> bool {
         editbox::action(&self.lua, action)
     }
 
-    /// Is the focused EditBox in **alt-arrow mode** — the flag the XML spells `ignoreArrows` and
-    /// the Lua surface spells `SetAltArrowKeyMode` (`[editbox+0x318] & 0x10`)?
-    ///
-    /// The host asks this to decide whether an arrow key reaches the box at all. With the flag set
-    /// and ALT not held, the reference's key handler returns 0 at `0x77b1c4` for the four arrow
-    /// codes — **not consumed** — and the strata walk carries down to `CGWorldFrame`, which runs
-    /// the key's binding. That is what lets you turn while the chat box has focus, and it is why
-    /// the gate is on the key rather than on the [`EditAction`]: `Move { unit: Edge }` reaches the
-    /// box from HOME/END as well as from an arrow, and only the arrow is gated.
-    ///
-    /// `false` when nothing is focused, which is the same answer as an unflagged box: neither
-    /// declines the key.
+    /// Whether the focused EditBox is in alt-arrow mode (XML `ignoreArrows`, Lua
+    /// `SetAltArrowKeyMode`, `[editbox+0x318] & 0x10`): without ALT the reference declines the four
+    /// arrows (`0x77b1c4`), so they reach the world's bindings and turn the player while chat has
+    /// focus. The gate is on the key, not the [`EditAction`]: HOME and END also move to an edge.
     pub fn editbox_alt_arrow_mode(&self) -> bool {
         let model = self.model_ref();
         model.focused_editbox.is_some_and(|h| {
@@ -1411,8 +1039,8 @@ impl UiScript {
         })
     }
 
-    /// Whether an EditBox currently holds keyboard focus (and is effectively visible) — the app gates
-    /// world/player key input on this, matching the client's `DAT_00cf4dc8 != 0` test (RF-0082 §1).
+    /// Whether a visible EditBox holds keyboard focus, which gates the world's keys as the client's
+    /// `0xcf4dc8 != 0` test does.
     pub fn has_keyboard_focus(&self) -> bool {
         let model = self.model_ref();
         model
@@ -1420,119 +1048,67 @@ impl UiScript {
             .is_some_and(|h| model.arena.frame(h).is_some_and(|f| f.effective_visible))
     }
 
-    /// **Which** EditBox holds the focus, by name — [`Self::has_keyboard_focus`] answers
-    /// *whether*. Unfiltered by visibility, because the focus cell itself is: a box that hides
-    /// while focused keeps the cell until something clears it, and the tests that watch the
-    /// hand-off between two boxes are watching exactly that cell.
-    ///
-    /// This is the host-side read of `Model::focused_editbox`. There is no Lua verb for it and
-    /// there must not be: 1.12's EditBox table has `SetFocus`/`ClearFocus` and no getter, which
-    /// is why `pfQuest/browser.lua:760` ships its own focus flag rather than asking (decision
-    /// 2142).
+    /// The focused EditBox's name, unfiltered by visibility, unlike [`Self::has_keyboard_focus`].
+    /// Host-side only: 1.12's EditBox table has `SetFocus`/`ClearFocus` and no getter.
     pub fn focused_editbox_name(&self) -> Option<String> {
         let model = self.model_ref();
         let h = model.focused_editbox?;
         model.arena.frame(h)?.name.clone()
     }
 
-    /// How many resolves the layout change gate has let through (`Model::layout_solves`) — the
-    /// gate's effectiveness, readable by tests and the app's cost meters (a per-frame delta of 0
-    /// means the fingerprint judged the frame quiet).
+    /// Resolves the layout change gate let through; a per-frame delta of 0 means a quiet frame.
     pub fn layout_solves(&self) -> u64 {
         self.model_ref().layout_solves
     }
 
-    /// How many resolves got past **tier 1** and paid the whole-roster preamble
-    /// ([`Model::layout_gate_walks`], decision 1385) — the gate's true cost counter, ≥
-    /// [`Self::layout_solves`] because a walk that concludes "nothing moved" pays the same
-    /// preamble and never reaches the solve counter.
+    /// Resolves past tier 1, which pay the whole-roster preamble ([`Model::layout_gate_walks`]):
+    /// the gate's true cost, at least [`Self::layout_solves`], since a walk may find nothing moved.
     pub fn layout_gate_walks(&self) -> u64 {
         self.model_ref().layout_gate_walks
     }
 
-    /// How many times a resolve DERIVED the layout graph from scratch ([`Model::layout_derives`])
-    /// — the whole-roster walk, and since decision 1388 the only expensive thing a resolve can do.
-    /// A UI that merely animates should hold this flat.
+    /// Whole-graph layout derivations, a resolve's one expensive step; flat while a UI animates.
     pub fn layout_derivations(&self) -> u64 {
         self.model_ref().layout_derives
     }
 
-    /// Total fixpoint ROUNDS across every solve ([`Model::layout_rounds`]) — a solve costs
-    /// rounds × the whole graph, so the ratio against [`Self::layout_solves`] is the per-pass
-    /// depth.
+    /// Fixpoint rounds across every solve; over [`Self::layout_solves`], the per-pass depth.
     pub fn layout_rounds(&self) -> u64 {
         self.model_ref().layout_rounds
     }
 
-    /// The last solve's SCOPE — `(frames solved, regions swept)`, decision 1350's meter.
-    ///
-    /// The third axis of a solve's cost, and the one that used to be "all of it": solves says how
-    /// OFTEN, rounds says how DEEP, this says how WIDE. A change that touches ten FontStrings must
-    /// read a handful here however large the UI grows; a scope that tracks the graph is the
-    /// regression, and it is asserted as a COUNT because milliseconds have twice failed to catch
-    /// this class (0735, 0771).
+    /// The last solve's scope, `(frames solved, regions swept)`: a change to ten FontStrings must
+    /// read a handful here however large the UI grows.
     pub fn layout_last_scope(&self) -> (usize, usize) {
         self.model_ref().layout_last_scope
     }
 
-    /// Is `name` a registered FrameXML template — one `CreateFrame`'s fourth argument or an
-    /// `inherits=` can resolve (decision 1203)?
-    ///
-    /// A pure query on the VM's live registry, for the corpus harness: an addon naming a template
-    /// we have not transcribed gets a bare frame and **no load error**, so nothing else can see it.
-    /// **Folded**, because the resolution it reports on is folded. An exact `contains_key` made this
-    /// census disagree with the loader the moment `inherits=` became case-insensitive: it went on
-    /// listing `UIDropdownMenuTemplate`, `CT_RaCheckButtonTemplate` and `MSBTColorSwatchTemplate` as
-    /// missing while the loader was resolving all three. An instrument that reports a gap the code
-    /// does not have is worse than no instrument — it is a build queue pointing at finished work
-    /// (1242/1246, and 1251 §3's rule that a source-derived answer be checked against the runtime
-    /// artefact).
+    /// Whether `name` is a registered FrameXML template, case-folded as the loader resolves it, for
+    /// the corpus harness: an addon naming a missing template gets a bare frame and no load error.
     pub fn has_framexml_template(&self, name: &str) -> bool {
         let model = self.model_ref();
         let templates = model.framexml_templates.borrow();
         templates.contains_key(name) || templates.keys().any(|k| k.eq_ignore_ascii_case(name))
     }
 
-    /// Is `name` a registered FONT object — the *other* thing an `inherits=` may legally name?
-    ///
-    /// [`Self::has_framexml_template`]'s twin, and only useful beside it: `inherits=` is one
-    /// attribute over two namespaces (`<FontString inherits="GameFontNormal">` names a font,
-    /// `<Button inherits="UIPanelButtonTemplate">` names a template — `loader::expand_region` is
-    /// where that fork lives). A census that asks only the template registry reports every font in
-    /// the corpus as a missing template.
+    /// Whether `name` is a registered font object, the other namespace an `inherits=` may name
+    /// (`loader::expand_region` forks on it), so a census counts no font as a missing template.
     pub fn has_font_object(&self, name: &str) -> bool {
         self.model_ref().font_object(name).is_some()
     }
 
-    /// The **widget kind of a published name** — `"MessageFrame"`, `"Button"`, `"Texture"`, … — or
-    /// `None` if nothing by that name is a live widget.
-    ///
-    /// [`Self::has_framexml_template`]'s sibling, and the same kind of thing: a pure Rust-side query
-    /// on the live model, for the corpus harness. The harness needs to know what `UIErrorsFrame` in
-    /// `UIErrorsFrame:AddMessage(…)` actually *is* in our object graph, because a widget-method
-    /// census that asks "does ANY kind answer this name" cannot see a verb wired to one class and
-    /// forgotten on its sibling (decision 1228). Attributing the call site to a kind is what makes
-    /// that question askable, and this is the only honest answer to "what kind is that global": the
-    /// arena's own record, not a name list.
-    ///
-    /// **Deliberately NOT a Lua binding.** The reference publishes this as `GetObjectType`, which we
-    /// do not implement outside font objects; adding it here would put a new verb in front of every
-    /// addon and move the very numbers the census is measured by. An instrument must be able to
-    /// claim it perturbed nothing, so it stays on the Rust side where no addon can observe it.
-    ///
-    /// The spellings are `CreateFrame`'s own (`SimpleHTML`, not `SimpleHtml`), so a caller can
-    /// compare a name here against a kind it passed to `CreateFrame`.
+    /// The widget kind of a published name, in `CreateFrame`'s spelling (`SimpleHTML`): host-side,
+    /// for the corpus harness to attribute a call site to a class unseen by any addon.
     pub fn widget_kind(&self, name: &str) -> Option<&'static str> {
         let model = self.model_ref();
         if let Some(h) = model.arena.lookup(name) {
             return model.arena.frame(h).map(|f| match f.kind {
                 crate::widget::FrameKind::Frame => "Frame",
-                // A `Frame` to Lua (1984): the registered name never becomes a class identity.
+                // A `Frame` to Lua: the registered name never becomes a class.
                 crate::widget::FrameKind::WorldFrame => "Frame",
                 crate::widget::FrameKind::Button => "Button",
                 crate::widget::FrameKind::CheckButton => "CheckButton",
-                // `GetObjectType 0x495b60` is two instructions and returns `"LootButton"`
-                // (`[0x847ce0]` → `0x843414`). It does NOT answer "Button".
+                // `GetObjectType` (`0x495b60`) says "LootButton" (`[0x847ce0]` → `0x843414`).
                 crate::widget::FrameKind::LootButton => "LootButton",
                 crate::widget::FrameKind::EditBox => "EditBox",
                 crate::widget::FrameKind::StatusBar => "StatusBar",
@@ -1551,16 +1127,13 @@ impl UiScript {
                 crate::widget::FrameKind::Minimap => "Minimap",
             });
         }
-        // The region leaves publish into their own name table (`region_names`), not the arena's —
-        // and they matter here: `GameTooltipTextLeft1:GetText()` is a FontString call, and the
-        // corpus scrapes those constantly.
+        // Region leaves publish into their own name table, not the arena's.
         let id = *model.region_names.get(name)?;
         let h = *model.id_to_region.get(&id)?;
         model.arena.region(h).map(|r| match r.kind {
             crate::widget::RegionKind::Texture => "Texture",
             crate::widget::RegionKind::FontString => "FontString",
-            // A title region is a plain Region and says so (Q6) — and it is unreachable by name
-            // anyway: `CreateTitleRegion` takes no name argument at all.
+            // A title region is a plain Region (`0x76c440`); `CreateTitleRegion` takes no name.
             crate::widget::RegionKind::Title => "Region",
         })
     }
@@ -1580,47 +1153,28 @@ impl UiScript {
         self.model_ref().warnings.clone()
     }
 
-    /// Drain the accumulated non-fatal host warnings (an ignored `CreateFrame` template, a layout
-    /// fixpoint that hit its round cap) — the host logs them; un-drained they pile up unseen.
+    /// Drain the non-fatal host warnings, for the host to log.
     pub fn take_warnings(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().warnings)
     }
 
-    /// Report a script error the host caught **outside** the VM's own dispatch — an addon file
-    /// that failed to compile or raised at file scope during the load walk. It joins the
-    /// handler-dispatch queue and the retained log, but **not** `errors`: the caller has already
-    /// logged it (the load walk's per-file `error!` + `failures` contract), so putting it there too
-    /// would double-log at the app's per-frame drain.
-    ///
-    /// Its silent sibling is [`Self::report_load_failure`] (decision 1495) — same retention, no
-    /// dispatch, for the load failures that never raise at all.
+    /// Report a script error the host caught outside the VM's dispatch (an addon file that failed
+    /// to compile or raised at file scope): it joins the handler-dispatch queue and the retained
+    /// log, not `errors`, since the caller has already logged it.
     pub fn report_script_error(&self, msg: &str) {
-        // Retained as a **Load** row, not an Error one (decision 1495): every caller of this is
-        // the load walk, and from the player's side "the addon's file scope raised" and "the
-        // addon's file was missing" are the same fact — the addon is not running. The retention
-        // half is `diagnostics::record_load_failure`, shared with the demand-load path so the
-        // rule has one implementation (2107); the dispatch is what makes this the loud sibling.
+        // A Load row, not an Error one: to the player a file scope that raised and a missing file
+        // are the same fact, the addon is not running.
         diagnostics::record_load_failure(&self.lua, msg);
         self.model_mut()
             .pending_error_dispatch
             .push(msg.to_string());
     }
 
-    /// Hand every queued script error to the Lua-side error handler — the reference's own shape:
-    /// `seterrorhandler`/`geterrorhandler` are engine globals (wow-re `scratch/lua-dialect.md`,
-    /// the captured `_G`), the engine invokes the registered handler on a caught script error
-    /// (that is the pair's contract — a handler nothing invokes would be two dead globals), and
-    /// FrameXML answers with `_ERRORMESSAGE` → the red ScriptErrors dialog (decision 1305).
-    ///
-    /// Called at a safe seam (the app's per-frame drain), never from inside the failed call.
-    /// Three guards keep it bounded and honest:
-    /// - **The stdlib default handler is skipped by identity.** It reports into
-    ///   [`UiScript::errors`] — where every queued message already is — so dispatching it would
-    ///   only duplicate. The queue still drains, so a handler installed later starts clean.
-    /// - **A handler that raises is recorded on the host channel only** and never re-queued:
-    ///   the error path cannot recurse by construction.
-    /// - **One failure stops the batch** — a broken handler fails the same way for every message,
-    ///   and one line names it.
+    /// Hand each queued script error to the Lua error handler, as the reference invokes the one
+    /// `seterrorhandler`/`geterrorhandler` (`0x702900`/`0x702950`) hold on a caught error;
+    /// FrameXML installs `_ERRORMESSAGE`, the ScriptErrors dialog (`BasicControls.xml:16`). The
+    /// stdlib default is skipped, as it already reported into [`UiScript::errors`]; a handler that
+    /// raises is recorded on the host channel only and stops the batch, so the path cannot recurse.
     pub fn dispatch_script_errors_to_handler(&mut self) {
         let pending = std::mem::take(&mut self.model_mut().pending_error_dispatch);
         if pending.is_empty() {
@@ -1651,30 +1205,23 @@ impl UiScript {
         }
     }
 
-    /// Register a named virtual [`FontObject`] (a resolved `<Font>`), overwriting any prior one of
-    /// the same name, **and publish it as the Lua global `name`** — the same pair
-    /// `Loader::do_font` performs, so a font registered from Rust is addressable from Lua exactly
-    /// like one declared in XML (`fs:SetFontObject(Name)`, `Name:GetFont()`). One registration act,
-    /// one outcome: the two paths cannot drift.
+    /// Register a named [`FontObject`] (a resolved `<Font>`), replacing any of that name, and
+    /// publish it as the Lua global `name`, the same pair `Loader::do_font` performs.
     pub fn register_font_object(&self, name: &str, font: FontObject) {
         self.model_mut()
             .font_objects_by_lower
             .insert(name.to_ascii_lowercase(), font);
-        // Publishing cannot fail for a fresh table + a string key; a registry hiccup is not worth
-        // an unwrap in a host-facing setter, and the record is already in place either way.
+        // Publishing a fresh table under a string key cannot fail; the record is in place anyway.
         let _ = font::publish(&self.lua, name);
     }
 
-    /// Look up a registered [`FontObject`] by name (the resolved paint), if any. Used by tests and by
-    /// the `SetFontObject` binding.
+    /// A registered [`FontObject`] by name: its resolved paint.
     pub fn font_object(&self, name: &str) -> Option<FontObject> {
         self.model_ref().font_object(name).cloned()
     }
 
-    /// Every registered [`FontObject`] (the resolved paints of all loaded `<Font>` nodes) — the
-    /// host's bake census: the glyph atlas reads the distinct `(font, height, outline)` triples
-    /// off this to know which outlined cell variants the shipped UI can actually request
-    /// (the outlined-glyph bake, the fade-composite fold-back record).
+    /// Every registered [`FontObject`]: the glyph atlas bakes outlined cells for the distinct
+    /// `(font, height, outline)` triples here.
     pub fn font_objects(&self) -> Vec<FontObject> {
         self.model_ref()
             .font_objects_by_lower
diff --git a/crates/benilla-ui/src/script/model.rs b/crates/benilla-ui/src/script/model.rs
index 5995ef85..f8e1761a 100644
--- a/crates/benilla-ui/src/script/model.rs
+++ b/crates/benilla-ui/src/script/model.rs
@@ -8,27 +8,22 @@ use super::{
     container, craft, cursor, death, duel, follow, gossip, guild, inspect, item_text, loot,
     loot_roll, macros, mail, merchant, party, petition, pvp, quest, quest_log, reputation, session,
     simplehtml, skills, slider, social, spellbook, stable, taxi, trade, tradeskill, trainer,
-    weapon_enchant, ActionSlot, AuraState, FontObject, ItemTemplateView, PlayerReqState,
-    RegionData, ScriptValue, SoundRequest, UnitState,
+    weapon_enchant, ActionSlot, AuraState, FontObject, ItemTemplateView, MusicRequest,
+    PlayerReqState, RegionData, ScriptValue, SoundRequest, UnitState,
 };
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The Rust-side model (plain data; lives in lua.app_data)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The Rust-side model ──
 
-/// The host's texture-path resolvability oracle — see [`Model::texture_probe`].
+/// The host's answer to whether a texture path resolves to a file.
 pub type TextureProbe = Box<dyn Fn(&str) -> bool>;
 
-/// The host's texture **texel-size** oracle — see [`Model::texture_size_probe`].
+/// The host's answer to a texture path's size in texels.
 pub type TextureSizeProbe = Box<dyn Fn(&str) -> Option<(u32, u32)>>;
 
-/// The host's font-path resolvability oracle — see [`Model::font_probe`].
+/// The host's answer to whether a font path loads.
 pub type FontProbe = Box<dyn Fn(&str) -> bool>;
 
-/// A map from a minted object id to its handle, indexed directly: ids are dense (`next_id`
-/// counts from 1), and every scripted method call on a frame or region starts with this lookup
-/// — a few hundred a frame from the stock `OnUpdate` sweep alone (decision 1979's UI tick), so
-/// the hash a `HashMap` paid per call was the wrong price for a one-word index.
+/// Minted id to handle, indexed directly: ids are dense and every scripted call looks one up.
 #[derive(Debug, Clone)]
 pub(crate) struct IdMap<T>(Vec<Option<T>>);
 
@@ -57,1301 +52,645 @@ impl<T: Copy> IdMap<T> {
     }
 }
 
-/// The Rust-side model behind the Lua VM — the arena, the layout inputs + resolved rects, the
-/// id↔handle bijection, region visuals, and the event/script registrations. Held in `lua.app_data`
-/// (interior-mutable) so callbacks reach it; contains **no** mlua handles (the MAXCSTACK discipline).
+/// The Rust-side model behind the Lua VM, in `lua.app_data`. It holds no mlua handles, whose
+/// persistent count the vendored `LUAI_MAXCSTACK` caps.
 pub(crate) struct Model {
-    /// Every discovered addon, in load order — the AddOn API's registry, filled by the host at
-    /// world entry ([`super::UiScript::register_addons`]). See [`super::addon`].
+    /// Every discovered addon in load order: the AddOn API's registry, filled at world entry.
     pub(crate) addons: Vec<super::addon::AddOnInfo>,
-    /// **The Lua index space** — positions into [`Self::addons`], `## Title`-sorted and
-    /// hidden-filtered (decision 2175). NOT the registry: the reference keeps two structures and
-    /// they are different permutations of different sets (wow-re
-    /// `system/ui/scratch/addon-registry-scan-and-order.md` §7).
+    /// The Lua index space into `addons`, a title-sorted, hidden-filtered list (`0x51da70`).
     pub(crate) addon_index: Vec<usize>,
-    /// The lowercased names `SMSG_ADDON_INFO` marked `status = 2`, or **`None` when no reply has
-    /// arrived this session** — and `None` is why [`Self::addon_index`] can be legitimately empty
-    /// (decision 2175). `[0xbe1b90]` is zeroed by the registry reset `0x51fad1` and written
-    /// nowhere but the reply's own rebuild, so `GetNumAddOns()` really is 0 until the server
-    /// answers.
+    /// Lowercased names `SMSG_ADDON_INFO` marked `status = 2`; `None` until the reply arrives, and
+    /// until then `GetNumAddOns()` is 0, as in the reference (`[0xbe1b90]`, reset at `0x51fad1`).
     pub(crate) addon_info_hidden: Option<Vec<String>>,
     /// The AddOns folder, so `LoadAddOn` can read an addon's files from inside a Lua binding.
     pub(crate) addons_root: Option<std::path::PathBuf>,
-    /// The host's reader for a chain-sourced addon's files (`AddOnInfo::chain`), by
-    /// chain-internal path — `None` in a VM with no chain behind it, where such an addon
-    /// answers `MISSING`.
+    /// The host's reader for chain-sourced addon files; without one such an addon is `MISSING`.
     pub(crate) addons_chain_reader: Option<super::addon::SharedChainReader>,
-    /// The host's font engine ([`super::UiScript::set_text_measurer`]) — what lets a metric read
-    /// answer inside the Lua call that asked, instead of a frame later. `None` in every VM without
-    /// a font atlas, which is the measure round-trip's own world and behaves exactly as it did.
+    /// The host's font engine, so a metric answers inside the asking call, not a frame later.
     pub(crate) measurer: Option<Box<dyn super::TextMeasure>>,
-    /// The host's texture-path oracle ([`super::UiScript::set_texture_probe`]): does this sprite
-    /// reference resolve to a file — patch chain or loose addon folder? What lets the path form of
-    /// `SetTexture` return the reference's **1 | nil** load verdict inline (wow-re
-    /// `widget-api-batch-benilla.md` Q1 — Atlas branches on it to pick its map art). `None` in an
-    /// engine-less VM (tests, the addon harness), where the path form keeps answering nil: no
-    /// backend, nothing loads — which is also exactly what those tests always saw.
+    /// Whether a texture path resolves (patch chain or loose addon file), so the path form of
+    /// `SetTexture` returns the reference's 1 or nil inline (`0x79bb40`). `None` answers nil.
     pub(crate) texture_probe: Option<TextureProbe>,
-    /// The host's texture **texel-size** oracle ([`super::UiScript::set_texture_size_probe`]): how
-    /// many texels wide and tall is the art at this path?
-    ///
-    /// What lets a region whose authored size on an axis is exactly `0` take its span from its
-    /// CONTENT, the way the real client's size getters do — `CSimpleTexture::GetWidth 0x770720` /
-    /// `GetHeight 0x770790` return the authored value only when it is not `0.0`, and otherwise read
-    /// the loaded texture's `[tex+0x144]`/`[tex+0x148]` through the same converter `<AbsDimension>`
-    /// uses, so **one texel is one FrameXML unit** (wow-re `region-size-fallback.md` §2, decision
-    /// 1349). The host answers off the same candidate walk the renderer decodes with and memoises,
-    /// so the size layout resolves with is the size the screen shows.
-    ///
-    /// `None` in an engine-less VM (tests, the addon harness), where a zero-size texture keeps the
-    /// rect it always had — there is no art to measure without a backend.
+    /// A path's texel size, which an axis authored as 0 takes, one texel per unit, as the client's
+    /// `GetWidth` (`0x770720`) and `GetHeight` (`0x770790`) do; `None` leaves it as authored.
     pub(crate) texture_size_probe: Option<TextureSizeProbe>,
-    /// The host's font-path oracle ([`super::UiScript::set_font_probe`]): does this font reference
-    /// load — patch chain or loose addon folder? What lets `SetFont`'s path form answer the
-    /// reference's **1 | nil**, whose nil is a *load failure* and not an argument error (wow-re
-    /// `system/ui/ui.md`: `0x79f345`/`0x79f361`, originating at `0x5c1ae0` under the `0x44d040`
-    /// font-factory cache) — `!OmniCC/main.lua:41`'s `if not Font:SetFont(saved, size) then
-    /// revert end` is exactly that probe.
-    ///
-    /// **`None` answers 1 for a non-empty path, which is where this differs from
-    /// [`Self::texture_probe`]** (decision 2103). A VM with no font backend has no font store to
-    /// fail against, so nil there would report a load failure that never happened — and it would
-    /// send `!OmniCC` down its revert branch in every harness run. The texture probe could take
-    /// the opposite default because nil was already what its engine-less callers observed; here 1
-    /// is.
+    /// Whether a font path loads: `SetFont`'s 1 or nil, nil meaning a load failure (`0x79f345`,
+    /// `0x79f361`, from `0x5c1ae0` in the `0x44d040` cache). Unlike `texture_probe`, `None` answers
+    /// 1 for a non-empty path: without a font backend nothing failed, and addons revert their font
+    /// on a nil.
     pub(crate) font_probe: Option<FontProbe>,
-    /// Where per-addon saved variables live: the account-scoped folder, then this character's.
-    /// Both are directories holding one `<Addon>.lua` per declaring addon.
+    /// Saved-variables folders, one `<Addon>.lua` each: the account's, then this character's.
     pub(crate) addons_saved_account: Option<std::path::PathBuf>,
     pub(crate) addons_saved_character: Option<std::path::PathBuf>,
-    /// The FrameXML **template registry**, persisted across [`crate::loader::load`] calls — the
-    /// client's template table is global (`0x6ee500`, rf24), so a file may `inherits=` a template
-    /// an *earlier file* registered (the real MerchantFrame.xml inherits
-    /// CharacterFrameTemplates.xml's tab template). Register-before-use in load order, exactly
-    /// the client's rule; a per-document registry silently dropped every cross-file inherit.
-    ///
-    /// **Here rather than on `UiScript`** so the loader can run from a bare `&Lua`: that is what
-    /// lets `LoadAddOn` load an addon from inside a Lua binding, synchronously, the way the
-    /// reference does (1188 phase 2). `font_objects` below was already here, and these two are
-    /// the same kind of thing — VM-global registries the loader fills.
+    /// FrameXML templates, global across files as the client's (`0x6ee500`); held here so the
+    /// loader runs from a bare `&Lua`, which lets `LoadAddOn` load inside a binding.
     pub(crate) framexml_templates:
         std::cell::RefCell<std::collections::HashMap<String, crate::framexml::Element>>,
-    /// **`FrameXML_Debug`'s flag** — the loader's own trace-severity switch (decision 2160).
-    ///
-    /// `0x488440` is a get-or-set over the single global `[0xceea30]`, which boots at 0 and is
-    /// read at six sites image-wide: the binding itself and five inside the XML loader, each
-    /// gating a severity-0 trace line behind `flag > 0` (`0x6ee298 jle` — **greater than**, not
-    /// non-zero, which is why this is signed). The one site walked to the bytes is
-    /// `Instantiate 0x6ee280`, whose gated line is `0x871154 "-- Creating %s named %s"`.
-    ///
-    /// Here rather than on `UiScript` for `framexml_templates`' reason: the loader runs from a
-    /// bare `&Lua`, and so does the binding that writes this.
+    /// `FrameXML_Debug`'s flag (`0x488440` over `[0xceea30]`, boots 0); the loader's trace lines
+    /// print while it is greater than 0 (`0x6ee298`), so it is signed.
     pub(crate) framexml_debug: std::cell::Cell<i32>,
-    /// The FrameXML **font-element registry** (a separate namespace — a font inherits a font,
-    /// never a frame template), persisted for the same cross-file reason.
+    /// The FrameXML font registry, a namespace apart from templates (a font inherits only a font).
     pub(crate) framexml_fonts:
         std::cell::RefCell<std::collections::HashMap<String, crate::framexml::Element>>,
-    /// The frame arena (create/destroy + show/hide/strata/level/scale/alpha propagation).
     pub(crate) arena: WidgetArena,
-    /// Per-frame layout input (anchors/size/scale). Every live frame has one (created at
-    /// `CreateFrame`); `SetPoint`/`SetWidth`/… mutate it; `resolve` runs the graph over them.
+    /// Per-frame anchors, size and scale; every live frame has one from creation on.
     pub(crate) layout_inputs: HashMap<FrameHandle, LayoutInput>,
-    /// The last [`UiScript::resolve`] result: each resolvable frame's rect. Empty until `resolve`.
+    /// Each resolvable frame's rect from the last resolve.
     pub(crate) resolved: HashMap<FrameHandle, Rect>,
-    /// The anchor-graph solver, kept alive across resolves so its per-handle arrays and the
-    /// per-frame anchor `Vec`s are reused — a steady round allocates nothing (see
-    /// [`LayoutSolver`]). Scratch only: it holds no state between rounds that `begin` doesn't
-    /// clear, and `resolved`/`region_resolved` remain the model's own answer.
+    /// The anchor solver, kept across resolves so a steady round allocates nothing; scratch only.
     pub(crate) solver: LayoutSolver,
-    /// The fingerprint of the input set the last CONVERGED resolve ran against — the change gate
-    /// (see `script::layout::InputFingerprint`). `None` forces the next resolve to run: the
-    /// initial state, and what a non-converging (cyclic) pass leaves behind so its progress can
-    /// carry into the next frame.
+    /// Tier 2 of the resolve gate, the last converged inputs' fingerprint; `None` forces a resolve.
     pub(crate) layout_fingerprint: Option<super::layout::InputFingerprint>,
-    /// The layout mutation epoch — tier 1 of the resolve change gate (the fingerprint is tier 2).
-    /// Bumped by [`Model::touch_layout`] at every write path that can move the anchor solve's
-    /// read set; `resolve` returns immediately while it still equals [`Self::layout_epoch_resolved`],
-    /// paying a `u64` compare instead of fingerprinting ~2k inputs. Tier 2 remains the correctness
-    /// backstop for a write that bumps this without moving anything; it is not a licence to bump
-    /// per frame, because *reaching* it costs the whole-UI hash. The bag-hover re-enter loop used
-    /// to do exactly that (~0.65 ms/frame at solves=0) until its wrap-pin round trip was made
-    /// change-gated — `tooltip::append_line`, and the gate
-    /// `layout_gate::the_hover_re_enter_loop_neither_re_measures_nor_re_solves`.
+    /// Tier 1 of the resolve gate: every layout write bumps it, and a resolve returns at once while
+    /// it equals `layout_epoch_resolved`. Never bump it per frame: tier 2 hashes the whole UI.
     pub(crate) layout_epoch: u64,
-    /// [`Self::layout_epoch`]'s **precise** form: the nodes a write actually NAMED since the last
-    /// converged resolve — tier 1 promoted from "something moved" to "*these* moved" (decision
-    /// 1388).
-    ///
-    /// `Some(nodes)` carries a second, stronger claim than its contents: **every** write since the
-    /// cached graph was built named its node *and* left the graph's SHAPE alone, so
-    /// [`super::layout::LayoutScope`]'s roster, edges and per-node hashes still describe the live
-    /// model and a resolve may seed the dirty closure straight from this list. `None` is the
-    /// conservative state — a write that could not name its node, or one that moved the roster or
-    /// an anchor's TARGET — and forces the next resolve to derive the graph from scratch, which is
-    /// exactly what every resolve did before 1388.
-    ///
-    /// That asymmetry is the safety argument. A site that keeps calling plain
-    /// [`Model::touch_layout`] is *correct by construction* (it lands in `None`, i.e. today's
-    /// behaviour); only a site that opts into [`Model::touch_layout_region`] /
-    /// [`Model::touch_layout_frame`] can be wrong, and `WOW_LAYOUT_VERIFY` re-resolves every
-    /// incremental pass in full scope and compares rects, so being wrong fails a test rather than
-    /// shipping a stale one.
-    /// The list holds **layout ids**, not handles: the touch sites below already have to prove the
-    /// node is in the cached roster before they may name it, and that proof is a `node_of[id]`
-    /// probe — which hands back the roster row, and with it the handle, for free at resolve time.
+    /// Layout ids named by writes since the last converged resolve, each write claiming it left the
+    /// cached graph's shape alone, so a resolve seeds its dirty closure from them. `None` derives
+    /// the graph in full; `WOW_LAYOUT_VERIFY` checks every incremental pass against a full one.
     pub(crate) layout_touched: Option<Vec<u32>>,
-    /// The MEASURE lane's ledger — [`Self::layout_touched`]'s twin for the text-measure sweep
-    /// (`UiScript::fontstrings_needing_measure`), which used to walk every `region_data` row
-    /// twice a frame to *discover* silent writes (`SetText` touches no layout until the extent
-    /// moves — that silence is the lane's defining property, decision 1370's ~300 µs standing
-    /// `resolve` lap at a city pin). `Some(handles)` = every write since the last sweep that
-    /// could move a region's measure key ([`crate::script::types::RegionData::measure_key`]:
-    /// text, font path/height, text height, outline, wrap width, owner scale) named its region
-    /// here, so the sweep asks exactly these. `None` = some write could not name one (a
-    /// font-object fan-out, a scale propagation, `invalidate_text_measures`) and the next sweep
-    /// walks the whole roster exactly as it always did — which is also the initial state.
-    ///
-    /// UNLIKE the layout ledger, `None` is not re-entered by unmigrated sites automatically:
-    /// nothing at a `region_data` field write *had* to announce itself before this existed, so
-    /// completeness of the enrolled sites is the correctness claim — and it is machine-checked,
-    /// not argued: with `WOW_LAYOUT_VERIFY` on (forced for every benilla-ui test) the sweep
-    /// re-runs the whole-roster walk beside the drained ledger and panics on any row the ledger
-    /// missed. A candidate the ledger names that the roster walk doesn't is fine (a same-value
-    /// write — the staleness check absorbs it); the reverse is a stale label waiting to ship.
+    /// Regions a write may have re-keyed for text measure (text, font, outline, wrap, scale) since
+    /// the last sweep, which asks only these; `None` walks all. A site that forgets to name its
+    /// region is caught by `WOW_LAYOUT_VERIFY`, on for every test here, which panics on the miss.
     pub(crate) measure_dirty: Option<Vec<crate::widget::RegionHandle>>,
-    /// The message-line sweep's clean tokens: frame → (lines_gen, env hash) at its last
-    /// ZERO-REQUEST sweep. A frame matching both is skipped whole (`message_lines_needing_measure`
-    /// hashes none of its lines); a sweep that produced requests stores nothing, so an unanswered
-    /// request re-requests forever exactly like the region lane's ledger (1410's rule). Stale
-    /// entries for destroyed frames are inert (generational handles never re-match) and the map
-    /// holds a handful of message frames, so no destroy hook.
+    /// Per message frame, `(lines_gen, env hash)` at its last request-free sweep; a match skips it.
+    /// A destroyed frame's entry is inert: generational handles never match again.
     pub(crate) msg_swept: std::collections::HashMap<crate::widget::FrameHandle, (u64, u64)>,
-    /// Lines actually hashed by the sweep — the skip's honest meter (tests assert 0 on a settled
-    /// second sweep; 0735's counts-never-milliseconds rule).
+    /// Lines the message sweep hashed; a settled second sweep hashes none.
     pub(crate) msg_lines_hashed: u64,
-    /// `WOW_LAYOUT_VERIFY`'s flag that the resolve just taken was the incremental one and owes a
-    /// full-derive re-run to prove it (see `layout::UiScript::resolve_layout`). Always `false` in
-    /// production — nothing reads it unless the verify build set it.
+    /// Under `WOW_LAYOUT_VERIFY`, the resolve just taken was incremental and owes a full re-run.
     pub(crate) layout_verify_recheck: bool,
-    /// Per-node input hashes + the dirty-closure scratch — what makes a resolve cost the nodes
-    /// that MOVED rather than the whole graph (decision 1350; see `script::layout::LayoutScope`).
-    /// Tiers 1 and 2 above decide *whether* to solve; this decides *what*.
+    /// Per-node input hashes and dirty-closure scratch: which nodes a let-through resolve solves.
     pub(crate) layout_scope: super::layout::LayoutScope,
-    /// The [`Self::layout_epoch`] value the last CONVERGED resolve closed on. `None` forces the
-    /// next resolve through tier 1: the initial state, a cycle-bailed pass, and
-    /// [`super::UiScript::force_full_layout_resolve`].
-    ///
-    /// **Every converged resolve closes tier 1** (decision 1385) — a real solve as much as a
-    /// skipping one. It could not, while the fingerprint was hashed over the 0294 seeds as well
-    /// as the inputs: a solve outgrew the value it had just stored, so a mutated frame paid three
-    /// whole-roster walks (solve, settle, skip) instead of one. Hashing inputs alone makes the
-    /// stored fingerprint exactly the one the next mutation-free resolve recomputes, so a
-    /// per-frame layout write — the castbar's spark, any addon that animates a region — costs one.
+    /// The epoch the last converged resolve closed on; `None` sends the next one past tier 1.
     pub(crate) layout_epoch_resolved: Option<u64>,
-    /// How many times the change gate has LET A RESOLVE THROUGH. `UiScript::resolve` is called
-    /// unconditionally every frame, so the gap between call count and this is the gate's whole
-    /// value; it is also what lets a test assert that a no-op resolve really was one, rather than
-    /// merely producing the same rects. Counts the gate's decision, so it reads the same with the
-    /// `WOW_LAYOUT_VERIFY` self-check on (which re-runs skipped resolves) as with it off.
+    /// Resolves the gate let through, counted at its decision, so verify mode reads the same.
     pub(crate) layout_solves: u64,
-    /// How many times a resolve got **past tier 1** — the count of whole-roster preamble WALKS
-    /// (decision 1385). This, not [`Self::layout_solves`], is the honest cost counter for the
-    /// gate: a walk that ends in `gate_skips` still rebuilt the ids/plan, re-synced every frame's
-    /// scale and re-hashed all ~10k anchored regions to conclude "nothing moved" — ~1.0 ms at the
-    /// Stormwind pin — and `layout_solves` cannot see it, because it counts only the walks that
-    /// went on to solve.
-    ///
-    /// The castbar pin is why it exists: one moving spark cost **three** walks per frame and only
-    /// two of them were solves, so the counter the tests asserted on under-reported the bug by a
-    /// third. `resolve_bench::a_region_moving_every_frame_costs_one_gate_walk_on_the_shipped_ui`
-    /// is the guard that reads it.
-    ///
-    /// **Unlike [`Self::layout_solves`], this is NOT verify-independent.** Under
-    /// `layout_verify_enabled` a tier-1-clean resolve falls through and walks anyway, so a verify
-    /// build counts walks production never pays — which is the honest reading (the walk happened)
-    /// but makes the number useless as an assertion there. Assert on it only from a crate that
-    /// consumes `benilla-ui` as a dependency, where `cfg!(test)` is false and the count is
-    /// production's; inside this crate's own tests, assert on `layout_solves`.
+    /// Resolves that got past tier 1, including those that then skipped: the whole-roster walk's
+    /// cost, which `layout_solves` misses. Verify mode walks anyway, so assert on this only from a
+    /// crate that depends on `benilla-ui`; inside this crate, assert on `layout_solves`.
     pub(crate) layout_gate_walks: u64,
-    /// How many times a resolve **derived the layout graph** — the whole-roster walk that rebuilds
-    /// the frame/region roster, the reverse edges and every per-node hash (decision 1388).
-    ///
-    /// This is the cost counter [`Self::layout_gate_walks`] used to be. 1385 got a moving castbar
-    /// spark down from three walks per frame to one; 1388 made that one walk *cheap* by seeding the
-    /// dirty closure from a ledger of named nodes instead of rediscovering it, so "walks" no longer
-    /// separates the 1.48 ms case from the 20 µs one and this does. A UI that animates anything
-    /// should hold this at **zero** frame after frame — a non-zero steady-state reading means some
-    /// write site is falling back to the conservative `touch_layout`, and that is the regression.
-    ///
-    /// Verify-independent in the direction that matters: the `WOW_LAYOUT_VERIFY` re-run's
-    /// derivation is counted, but `resolve_layout` restores the meter afterwards, so a test reads
-    /// the same number in both modes.
+    /// Full layout-graph derivations: 0 on a steady UI, so a rise means a write fell back to
+    /// `touch_layout`. The `WOW_LAYOUT_VERIFY` re-run's derivation is not counted.
     pub(crate) layout_derives: u64,
-    /// The SCOPE of the last solve that ran: `(frames solved, regions swept)` — decision 1350's
-    /// own meter, and the number its gate asserts on. `layout_solves` says how often the gate let
-    /// a solve through and `layout_rounds` how deep each went; this says how WIDE, which is the
-    /// axis that used to be "the whole UI" and is the one a growing UI silently inflates.
+    /// The last solve's width, `(frames solved, regions swept)`.
     pub(crate) layout_last_scope: (usize, usize),
-    /// How many fixpoint ROUNDS those solves ran in total. A solve's cost is rounds × the whole
-    /// graph, so this is what separates "the gate let too much through" from "each pass is doing
-    /// too much" — the two have different fixes.
+    /// Fixpoint rounds run across all solves.
     pub(crate) layout_rounds: u64,
-    /// Hyperlink spans per frame — `(rect, link payload, full |H…|h markup)`, rects in the
-    /// engine's y-up screen space. Fed by the app each frame after it rasterizes message lines
-    /// ([`super::UiScript::set_link_spans`]); consumed by the pointer's release dispatch
-    /// (`OnHyperlinkClick` — decision 0288 P2).
+    /// Per frame, rasterized links `(y-up rect, link, full |H…|h markup)` for `OnHyperlinkClick`.
     pub(crate) link_spans: HashMap<FrameHandle, Vec<(Rect, String, String)>>,
-    /// Tab was pressed in the chat edit box since the last drain (`BenillaChatTabPressed` →
-    /// [`super::UiScript::take_chat_tab`]) — the app's whisper-target cycle reads it.
+    /// Tab was pressed in the chat edit box (`BenillaChatTabPressed`), for the whisper cycle.
     pub(crate) chat_tab: bool,
-    /// Region visuals (texture path/color/text) + region layout (anchors/size/justify).
+    /// Region visuals (texture, colour, text) and layout (anchors, size, justify).
     pub(crate) region_data: HashMap<RegionHandle, RegionData>,
-    /// Per-frame installed [`Backdrop`] (the tooltip/dialog/panel plate — `<Backdrop>` or
-    /// `SetBackdrop`). Absent ⇒ the frame draws no plate. Stored beside the arena like `region_data`
-    /// (the arena models structure, not paint). The client's `frame+0x1ac` pointer.
+    /// Each frame's backdrop plate (`<Backdrop>` or `SetBackdrop`, the client's `frame+0x1ac`).
     pub(crate) backdrops: HashMap<FrameHandle, backdrop::Backdrop>,
-    /// Per-`SimpleHTML` widget state (decision-free transcription of `CSimpleHTML`'s own members):
-    /// the four element fonts `+0x350`, the hyperlink format `+0x360`, and the CONTENTNODE list
-    /// `+0x340` of blocks the last `SetText` built. Stored beside the arena, like `backdrops`,
-    /// because its contents are script-layer types and `widget::kinds` is the layer below.
+    /// `CSimpleHTML`'s state: element fonts `+0x350`, link format `+0x360`, content nodes `+0x340`.
     pub(crate) simple_html: simplehtml::SimpleHtmlStates,
-    /// The named virtual **Font object** registry (`<Font name=…>` → resolved paint), keyed by name.
-    /// Populated by the loader as it walks top-level `<Font>` nodes; read by `SetFontObject` and by
-    /// FontString `inherits=` resolution. Data only — no Lua handles (MAXCSTACK discipline).
-    /// The named `<Font>` objects, **keyed by the ASCII-LOWERCASED name**.
-    ///
-    /// 1.12's font registry hashes the name and compares keys with `SStrCmpI` — case-INSENSITIVE
-    /// (`0x783870`/`0x7838c7`, wow-re `system/ui/scratch/font-object-lua-surface.md`: *"Font names
-    /// are matched case-insensitively"*), and a name string handed to `SetFontObject` folds the
-    /// same way. `Recap/RecapOptions.xml:32` inherits `GameFontHighLightSmall` — the shipped font
-    /// is `GameFontHighlightSmall`, one letter's case apart — and on the real client that resolves.
-    ///
-    /// Read it through [`Model::font_object`], never directly: that is where the fold lives, and
-    /// the name says so because nothing else guards the invariant (1247's shape).
+    /// Named `<Font>` objects by lowercased name, as 1.12 matches them with `SStrCmpI` (`0x783870`,
+    /// `0x7838c7`); read them only through `font_object`, where the fold lives.
     pub(crate) font_objects_by_lower: HashMap<String, FontObject>,
-    /// The last [`UiScript::resolve`] result for **anchored** regions (those with a non-empty
-    /// [`RegionData::anchors`]): the region's own resolved rect, owner-relative (see [`extract`]).
-    /// Regions with no anchors are absent here — they fall to the size-centered / fill-owner path.
+    /// Anchored regions' owner-relative rects from the last resolve; anchor-less ones are absent.
     pub(crate) region_resolved: HashMap<RegionHandle, Rect>,
 
-    /// Monotonic id source (starts at 1; `0` is [`SCREEN`]).
+    /// The next object id to mint; ids start at 1, since 0 is `SCREEN`.
     pub(crate) next_id: u32,
     pub(crate) id_to_frame: IdMap<FrameHandle>,
     pub(crate) frame_to_id: HashMap<FrameHandle, u32>,
     pub(crate) id_to_region: IdMap<RegionHandle>,
     pub(crate) region_to_id: HashMap<RegionHandle, u32>,
-    /// Region name → layout id — the region twin of the arena's frame-name publish (same
-    /// non-overwriting first-wins rule). `SetPoint`'s string `relativeTo` resolves through frames
-    /// first, then here — the real client anchors regions to *sibling regions* by name everywhere
-    /// (e.g. the merchant label plate to its `$parentSlot` texture), which owner-fallback silently
-    /// mis-anchored before (the jutting-plates bug the director's A/B caught).
+    /// Region name to id, first wins: `SetPoint` anchors to a sibling region by name, after frames.
     pub(crate) region_names: HashMap<String, u32>,
 
-    /// Which handler kinds each frame has a script for (presence mirror; the closures live Lua-side
-    /// in the `REG_SCRIPTS` table). Lets `tick` find OnUpdate frames without scanning Lua.
+    /// Which handlers each frame has; the closures themselves live in Lua's `REG_SCRIPTS` table.
     pub(crate) scripts: HashMap<FrameHandle, HashSet<&'static str>>,
-    /// The frames carrying an `OnUpdate` script, maintained by `SetScript` — `scripts`' one
-    /// writer — so the tick iterates exactly the OnUpdate population instead of re-filtering
-    /// (and re-allocating from) the whole scripts map every frame (decision 1446). Order is
-    /// irrelevant here: the tick sorts its visible subset by frame id every pass (the
-    /// deterministic-dispatch law stays where it was).
+    /// Frames with an `OnUpdate` script, kept by `SetScript`; the tick sorts them by frame id.
     pub(crate) on_update_frames: Vec<FrameHandle>,
-    /// The frames carrying an `OnSizeChanged` script — 1446's list, for the layout resolve's
-    /// "before" snapshot instead of the tick. Same one writer, same reason: that snapshot's own
-    /// comment says it covers "a handful, usually zero", and it found them by filtering the WHOLE
-    /// `scripts` map with a string compare per entry, on every let-through resolve — 36–72 µs a
-    /// resolve at a 3,988-frame roster, which made it the biggest phase left in the preamble
-    /// (decision 1634's `[layout-pre] watched=`).
+    /// Frames with an `OnSizeChanged` script, kept by `SetScript`, for the resolve's size snapshot.
     pub(crate) on_size_changed_frames: Vec<FrameHandle>,
-    /// The frames carrying an `OnUpdateModel` script — the list the tick fires at the top of
-    /// every paint of a visible model pane (`0x76d1a0`'s first act; decision 2007). Same one
-    /// writer as the two lists above.
+    /// Frames with an `OnUpdateModel` script, fired as a visible model pane paints (`0x76d1a0`).
     pub(crate) on_update_model_frames: Vec<FrameHandle>,
-    /// What the engine knows about each model **file** a pane has named — the sequences and
-    /// bounds a pane's clock needs ([`crate::widget::ModelFileFacts`]), handed over by the host
-    /// once the asset is resident, keyed by [`crate::widget::model_key`]. The reference reads
-    /// these off the loaded `MD20`; this engine parses no M2, so the facts arrive from the app's
-    /// loader through `UiScript::set_model_facts`.
+    /// Per model file, a pane clock's sequences and bounds, read by the host off the `MD20`.
     pub(crate) model_facts: HashMap<String, std::sync::Arc<crate::widget::ModelFileFacts>>,
-    /// Model files a pane named that no facts have arrived for yet — drained by the host
-    /// (`UiScript::model_facts_wanted`) to load them. Deduplicated on push.
+    /// Model files still waiting for their facts, for the host to load; deduplicated.
     pub(crate) model_facts_wanted: Vec<String>,
-    /// Edit boxes whose text changed and whose `OnTextChanged` has **not fired yet** — the
-    /// reference's `textChanged` dirty bit (`[E+0x31c]` bit 0), which `SetText`/`Insert` raise and
-    /// only the dirty-word drain `0x77d3e0` clears (decision 1831).
-    ///
-    /// The fire is deferred, not immediate: `SetText` returns to Lua before any handler runs, and N
-    /// changes to one box between two drains produce exactly ONE fire carrying the final text. The
-    /// reference's own FrameXML depends on both halves — `MoneyInputFrame_SetCopper` sets three
-    /// boxes while counting the fires it expects back, and errors if one arrives mid-loop.
-    ///
-    /// A hidden box stays on this list: `Hide` splices it out of the chain the update walk follows,
-    /// so its pending fire waits until it is shown again (or a key/mouse-down reaches it).
+    /// Edit boxes owed `OnTextChanged`: the reference's dirty bit (`[E+0x31c]` bit 0), set by
+    /// `SetText`/`Insert`, cleared only by `0x77d3e0`: one fire per drain, with the final text, as
+    /// `MoneyInputFrame_SetCopper` needs. A hidden box's fire waits for a show, key or mouse-down.
     pub(crate) dirty_editboxes: Vec<FrameHandle>,
-    /// `event name → frames registered for it` (RegisterEvent), in **registration order** — an
-    /// ordered Vec, never a set: the client's `SignalEvent 0x703e50` walks a per-event listener
-    /// LIST, so cross-frame dispatch order is a law, not an accident (the abbey territory-line
-    /// bug: two ZoneText frames write the same FontString on one event — last writer decides).
-    /// Re-registering is a no-op (position kept); Unregister removes. Data only — no Lua handles.
+    /// Event name to its frames in registration order, never a set: `SignalEvent` (`0x703e50`)
+    /// dispatches in that order across frames. Re-registering keeps a frame's position.
     pub(crate) event_to_frames: HashMap<String, Vec<FrameHandle>>,
-    /// `frame → its registered events` (for UnregisterEvent / cleanup).
     pub(crate) frame_events: HashMap<FrameHandle, HashSet<String>>,
-    /// The frames registered for **every** event (`RegisterAllEvents`), in registration order —
-    /// the same ordered-Vec-never-a-set discipline as [`Self::event_to_frames`], and dispatched
-    /// after it for the same reason: a frame that asks for all events asks *after* the frames
-    /// already listening for a given one, so it takes the tail of that event's list.
-    ///
-    /// **A flag rather than an expansion.** 1.12's event ids run to `0x225` = 549
-    /// (`FrameScript_InitEvents`), so writing the frame into every per-event list on registration
-    /// would mean 549 vector pushes per call and 549 scans per `UnregisterAllEvents` — and would
-    /// also invent a name list this engine has no business owning (ours registers by string, and
-    /// an event the server sends that no name list knows about would be silently excluded).
-    /// `UnregisterAllEvents` empties this alongside the per-event registrations, which is the half
-    /// AceEvent-2.0 depends on: it calls `frame:UnregisterAllEvents()` and then re-registers each
-    /// individual event it still wants.
+    /// `RegisterAllEvents` frames in registration order, dispatched after an event's own list and
+    /// cleared only by `UnregisterAllEvents`. Deviation: a flag, not the reference's append to
+    /// every event's list (`0x7023e0`, which orders by registration time and lets `UnregisterEvent`
+    /// drop one event), because events register here by name and no list of every name exists.
     pub(crate) all_event_frames: Vec<FrameHandle>,
 
-    /// The EditBox that currently owns keyboard focus — the engine's twin of the client's
-    /// class-owned focus global `DAT_00cf4dc8` (`CSimpleEditBox* E`, 0 = none; RF-0082 §1). A focused
-    /// box consumes every key/char; `None` lets an `autoFocus` box self-acquire on the first event.
-    /// Gated on effective-visibility at read time (a box hidden while focused stops taking input).
+    /// The focused edit box (`0xcf4dc8`), taking all keys while visible; `None` admits `autoFocus`.
     pub(crate) focused_editbox: Option<FrameHandle>,
 
-    /// The frame currently under the cursor (the last [`UiScript::mouse_move`] capture), so the next
-    /// move knows whether to fire `OnLeave`/`OnEnter`. `None` = cursor over no mouse-enabled frame.
+    /// The mouse-enabled frame under the cursor, for the next move's `OnLeave`/`OnEnter`.
     pub(crate) mouseover: Option<FrameHandle>,
-    /// The hover **re-pick** is due: the world under a stationary cursor changed — the hovered
-    /// frame hid (its `OnLeave` already fired at hide time), or a frame was shown that may now
-    /// be the topmost under the cursor. The reference keeps exactly this flag on the frame
-    /// manager (`[root+0x1100]`) and its per-tick pump re-runs the hover walk at the **saved**
-    /// cursor position, explicitly bypassing the didn't-move coalesce — so the newly exposed
-    /// frame gets `OnEnter` with no physical mouse move (wow-re
-    /// `ui/scratch/hover-hide-and-tooltip-owner-law.md`: writers `0x764cbb`/`0x764b8d`, pump
-    /// tail `0x7657a1` → `0x7660d0` self-alias). [`UiScript::tick`] drains it the same way.
+    /// A frame under a still cursor hid or showed, so the tick re-runs the hover walk at the saved
+    /// position and a newly exposed frame gets `OnEnter` without a mouse move: the reference's
+    /// `[root+0x1100]` flag (set at `0x764cbb`/`0x764b8d`, pumped at `0x7657a1` into `0x7660d0`).
     pub(crate) hover_repick: bool,
-    /// Per-button, the frame a mouse-down last captured (`button name → frame`), for the `OnClick`
-    /// same-frame press+release test in [`UiScript::mouse_button`]. Keyed by button so a `LeftButton`
-    /// press is not cleared by a `RightButton` release.
+    /// Per button, the frame its press landed on, for `OnClick`'s same-frame release test.
     pub(crate) mouse_down_on: HashMap<String, FrameHandle>,
-    /// The client's single mouse-capture slot **`root+0x80`** — the frame a press captured, held
-    /// until every button is up. The same fact as [`Model::mouse_down_on`] in the one-slot form,
-    /// and the two differ only while more than one button is held; this is the form the
-    /// mouse-down **raise** reads, which is what needs the precedence to be unambiguous.
-    ///
-    /// Written at `0x7663e6` with the resolved target — capture-**else**-hover, so an existing
-    /// capture survives a chorded press over a different frame — and cleared at `0x7664bb` only
-    /// when the post-event button mask is empty, so a chorded release keeps it. A title-region
-    /// press never reaches `0x7663e6` and so captures nothing.
+    /// The client's one mouse-capture slot (`root+0x80`), read by the mouse-down raise. Set at
+    /// `0x7663e6` to the capture, else the hovered frame, so a chorded press keeps the capture;
+    /// cleared at `0x7664bb` once no button is down. A title-region press captures nothing.
     pub(crate) mouse_capture: Option<FrameHandle>,
-    /// Per **frame**, the [`UiScript::now`] second at which its last single `OnClick` fired — the
-    /// double-click detector's entire state, and the faithful stand-in for the client's per-widget
-    /// timestamp `[CButton+0x334]` (wow-re `ui/scratch/button-doubleclick-law.md`).
-    ///
-    /// Three properties of that field are load-bearing, and are why this is keyed the way it is.
-    /// It lives on the **widget**, so two frames can never pair with each other. It carries **no
-    /// button identity** — the detector is button-agnostic, so a left release followed by a right
-    /// one on a button registered for both completes a double click (with `arg1` = the *second*
-    /// button); what normally confines double-clicks to the left button is `RegisterForClicks`'
-    /// `{"LeftButtonUp"}` default, not the detector. And it is written only when a single click
-    /// actually fires, then **zeroed** when a double completes — which is what makes four rapid
-    /// clicks read `Click · DoubleClick · Click · DoubleClick` rather than one click and three
-    /// doubles. Nothing else clears it: not hide, not disable, not the cursor leaving the frame
-    /// (`[+0x334]` has exactly three writers binary-wide — ctor, the fired-double zero, and the
-    /// fired-single stamp).
+    /// Per frame, when its last single `OnClick` fired: the client's `[CButton+0x334]`, the whole
+    /// double-click state. It has no button identity (left then right makes a double), is zeroed
+    /// when a double fires, and nothing else clears it, not hide, disable or the cursor leaving.
     pub(crate) last_click: HashMap<FrameHandle, f64>,
 
-    /// Frames whose resolved SIZE moved in the last [`UiScript::resolve_layout`], as
-    /// `(frame id, width, height)` — queued there (it holds only a `&mut Model`, so it cannot call
-    /// Lua) and drained by [`super::event::fire_size_changes`] at the next `&Lua` seam, which turns
-    /// each into `OnSizeChanged(self, width, height)`. Same compute-under-borrow / fire-outside
-    /// shape as the pointer path's `OnValueChanged`/`OnDragStart` hand-offs.
+    /// Frames the last resolve resized, `(id, width, height)`, owed `OnSizeChanged` outside it.
     pub(crate) pending_size_changed: Vec<(u32, f32, f32)>,
 
-    /// Script errors collected from `pcall`'d handlers (never panics, never prints — decision 0068).
+    /// Script errors caught from `pcall`'d handlers, drained by the host each frame.
     pub(crate) errors: Vec<String>,
-    /// Script errors awaiting dispatch to the **Lua-side** error handler (decision 1305) — the
-    /// reference calls `geterrorhandler()`'s function on every caught script error, which is how
-    /// FrameXML's `_ERRORMESSAGE` puts the red ScriptErrors dialog on the player's screen. Every
-    /// message recorded through [`Model::record_script_error`] lands here as well as in `errors`;
-    /// [`super::UiScript::dispatch_script_errors_to_handler`] drains it at a safe seam (never from
-    /// inside the failed call). A message produced *by* the handler itself goes to `errors` only —
-    /// that asymmetry is the recursion guard.
+    /// Errors owed to `geterrorhandler()`, which the reference calls on each caught error; one the
+    /// handler itself raises skips this queue, which stops the recursion.
     pub(crate) pending_error_dispatch: Vec<String>,
-    /// The **retained** script-error log — what [`errors`](Self::errors) and the load walk both
-    /// throw away once logged (decision 1495). `errors` is a per-frame drain for the host's
-    /// terminal; this is the session's memory, deduplicated and bounded, and the only thing a
-    /// player can actually read. See [`super::diagnostics`] for why the reference's own dialog is
-    /// not enough on its own.
+    /// The session's retained diagnostic log, deduplicated and bounded; `errors` drains each frame.
     pub(crate) diagnostics: super::diagnostics::DiagnosticLog,
-    /// Non-fatal warnings surfaced to the host (e.g. `CreateFrame`'s ignored `inherits=` template).
+    /// Non-fatal warnings for the host, such as a dropped `inherits=` template.
     pub(crate) warnings: Vec<String>,
     /// The screen-root rect (`[bottom, left, top, right]`), the anchor base for top-level frames.
     pub(crate) screen: Rect,
 
-    /// The per-unit-token game-state snapshot the app pushes in each frame (`"player"`, `"target"`,
-    /// …), read by the `Unit*` Lua bindings ([`unit`]). Plain data — the engine never touches the
-    /// ECS/net; the app's feed writes here via [`UiScript::set_unit`] (decision 0068 §3). A token
-    /// absent from the map is a non-existent unit (`UnitExists` false, numbers `0`/nil).
-    ///
-    /// **Keyed by the ASCII-LOWERCASED token, and the name says so because the invariant has no
-    /// other guard.** 1.12's shared token resolver `0x515970` compares every literal with
-    /// `SStrCmpI` → `_strnicmp`, which folds `'A'..'Z'` by `+0x20`; not one of its ten compares
-    /// reaches the case-sensitive sibling. So `"Player"`, `"PLAYER"` and `"player"` are the same
-    /// unit on the real client, and ~10 corpus addons rely on it — `Accountant.lua:107`'s
-    /// `UnitFactionGroup("Player")` is the one that cost an addon its session.
-    ///
-    /// Read it through [`Model::unit`], never directly: that is where the fold lives. The field was
-    /// called `units` until the fold landed, and it was renamed precisely so that every existing
-    /// reader had to come through here rather than be trusted to remember (wow-re
-    /// `system/ui/scratch/unit-token-grammar.md`).
+    /// Each unit token's state as pushed this frame, keyed lowercased because 1.12's resolver
+    /// (`0x515970`) matches with `SStrCmpI`: read it only through `unit`, where the fold lives.
     pub(crate) units_by_lower: HashMap<String, UnitState>,
-    /// Per-unit-token aura list, **in display order**, pushed by the app's aura feed each frame and
-    /// read by the `UnitAura` family ([`super::aura`]). The order is the app's decision, not the
-    /// engine's: the local player's is a maintained insertion-order cache, every other unit's is
-    /// ascending aura slot (decision 0257). A token absent here has no auras.
+    /// Per unit token, auras in display order: the player's by insertion, the rest by aura slot.
     pub(crate) auras: HashMap<String, Vec<AuraState>>,
-    /// Spell ids `CancelUnitBuff` queued since the app's last drain — one `CMSG_CANCEL_AURA` each.
+    /// Spell ids the cancel verbs queued (`CancelPlayerBuff`, `CancelTrackingBuff`, …), one
+    /// `CMSG_CANCEL_AURA` each.
     pub(crate) cancel_aura_requests: Vec<u32>,
-    /// The player's active tracking aura (the reference's `GetTrackingTexture` global — see
-    /// [`super::aura::TrackingState`]), pushed by the app's aura feed beside `auras`. `None` =
-    /// no tracking active.
+    /// The player's active tracking aura, behind `GetTrackingTexture`.
     pub(crate) tracking: Option<super::aura::TrackingState>,
-    /// Selection asks queued since the app's last [`UiScript::take_selection_requests`] drain — the
-    /// outbound twin of `units` above, carrying `TargetUnit` / `AssistUnit` / `TargetLastEnemy` in
-    /// call order because the reference reaches selection through one helper for all three
-    /// ([`super::SelectionRequest`]). The app resolves each to a streamed entity and commits the
-    /// selection; one it can't resolve is a no-op, as the real client no-ops `TargetUnit` on a
-    /// nonexistent unit ([`unit`]).
+    /// `TargetUnit`, `AssistUnit` and `TargetLastEnemy` calls in call order, one queue as the
+    /// reference routes all three through one helper; an unresolvable one is a no-op, as there.
     pub(crate) selection_requests: Vec<super::SelectionRequest>,
-    /// `TargetNearestFriend([reverse])` presses queued since the app's last
-    /// [`UiScript::take_target_nearest_friend_requests`] drain — one entry per call, `true` for the
-    /// reverse (backward) cycle. The app runs the friendly half of the TAB scan ([`unit`]).
+    /// `TargetNearestFriend` calls, `true` for the reverse cycle.
     pub(crate) target_nearest_friend_requests: Vec<bool>,
-    /// `(name, exactMatch)` pairs `TargetByName` queued since the app's last
-    /// [`UiScript::take_target_by_name_requests`] drain — the by-NAME twin of
-    /// `Self::target_requests`, which takes unit tokens. The app runs the shared by-name
-    /// resolver (`crate::target::by_name`, decision 0886) and commits the selection ([`unit`]).
+    /// `TargetByName(name, exactMatch)` calls, for the app's by-name resolver.
     pub(crate) target_by_name_requests: Vec<(String, bool)>,
-    /// Set when `ClearTarget()` fired with a live target — the ESC chain's LAST leg
-    /// (`ToggleGameMenu`'s order: the clear runs only when nothing earlier ate the press).
-    /// Drained by [`super::UiScript::take_target_clear`]; the app commits the deselect ([`unit`]).
+    /// `ClearTarget()` fired with a live target, the last step of `ToggleGameMenu`'s ESC chain.
     pub(crate) target_clear: bool,
-    /// Unit tokens `DropItemOnUnit` queued since the app's last
-    /// [`UiScript::take_drop_item_on_unit`] drain — the cursor's held item being dropped onto a
-    /// unit (`0x48d960`). The binding queues the token only; **every gate is the app's**, because
-    /// all of them read state the VM does not hold (the pet's owner fields, the learned Feed-Pet
-    /// spell, the held item's guid). A token the app refuses is silent and keeps the payload,
-    /// which is the reference's own behaviour ([`super::cursor`]).
+    /// `DropItemOnUnit` tokens (`0x48d960`), gated by the app; a refusal silently keeps the item.
     pub(crate) drop_item_on_unit: Vec<String>,
 
-    /// The party/raid roster snapshot the app pushes (`GroupState`'s merged view, decision 0434
-    /// §2) — `GetNumPartyMembers`/`GetPartyLeaderIndex`/`GetLootMethod`/… read it ([`party`]).
-    /// `PartyState::default()` = not in a group (every getter reports the solo-player shape).
-    /// Per-member game state rides the `units` map above, under `"party1"`..`"party4"` tokens.
-    /// The channels this session has CONFIRMED joining, in join order — the client-side number
-    /// law `GetChannelName` answers with ([`super::channel`]). Mirrored from `ui_chat`'s
-    /// `ChannelState` by `set_joined_channels`; empty until the server's first YOU_JOINED.
+    /// Channels the server confirmed, in join order: the numbers `GetChannelName` answers.
     pub(crate) joined_channels: Vec<Option<String>>,
+    /// The party or raid roster the app pushes; the default is not in a group.
     pub(crate) party: party::PartyState,
-    /// Party/loot intents (`AcceptGroup`/`InviteToParty`/`SetLootMethod`/…) queued since the
-    /// app's last [`super::UiScript::take_party_requests`] drain — the outbound seam ([`party`]).
+    /// Party and loot-method calls (`AcceptGroup`, `InviteToParty`, `SetLootMethod`, …) queued.
     pub(crate) party_requests: Vec<party::PartyRequest>,
-    /// The ready-check deadline and the unanswered flags the timeout tick reads (decision 1989).
+    /// The ready-check deadline and the unanswered flags the timeout tick reads.
     pub(crate) ready_check: party::ReadyCheckState,
-    /// The saved raid lockouts the Raid tab's info panel reads (decision 1549), pushed by the app
-    /// from `SMSG_RAID_INSTANCE_INFO`. Its own field rather than a [`party::PartyState`] member
-    /// because it arrives on its own packet and survives every roster change.
+    /// Saved raid lockouts from `SMSG_RAID_INSTANCE_INFO`, which outlive any roster change.
     pub(crate) saved_instances: Vec<party::SavedInstanceInfo>,
-    /// `SetRaidRosterSelection`'s cursor — a client-side raid row index, never sent anywhere.
+    /// `SetRaidRosterSelection`'s raid row index, client-side only.
     pub(crate) raid_selection: i64,
-    /// The current map's `Map.dbc` `InstanceType`, pushed by the app — `IsInInstance()`'s whole
-    /// input ([`instance`]). `None` = the map id has no DBC row.
+    /// The current map's `Map.dbc` `InstanceType`, all `IsInInstance()` reads; `None` for no row.
     pub(crate) instance_type: Option<u32>,
-    /// `CanShowResetInstances()`'s answer, pushed by the app (decision 1748) — the four-term
-    /// predicate the reference computes at `0x495c90` over state only the app holds.
+    /// `CanShowResetInstances()`, the reference's four-term predicate (`0x495c90`), app-computed.
     pub(crate) can_reset_instances: bool,
-    /// `ResetInstances()` calls queued since the app's last
-    /// [`super::UiScript::take_reset_instance_asks`] drain — the outbound seam ([`instance`]).
+    /// `ResetInstances()` calls queued.
     pub(crate) reset_instance_asks: u32,
-    /// The social snapshot the app pushes (friends, ignores, the last `/who` — decision 0668):
-    /// `GetNumFriends`/`GetFriendInfo`/`GetWhoInfo`/… read it ([`social`]). Already
-    /// display-resolved (names, class/zone names) because the reference resolves them
-    /// engine-side too.
+    /// Friends, ignores and the last `/who`, display-resolved as the reference resolves them.
     pub(crate) social: social::SocialState,
-    /// Social intents (`AddFriend`/`RemoveFriend`/`SendWho`/…) queued since the app's last
-    /// [`super::UiScript::take_social_requests`] drain — the outbound seam ([`social`]).
+    /// Social calls (`AddFriend`, `RemoveFriend`, `SendWho`, …) queued.
     pub(crate) social_requests: Vec<social::SocialRequest>,
-    /// The client's three LFG slot words (`[0xbc70a0]`) and its comment (`[0xbc6e98]`, a
-    /// 0x80-byte buffer), the BSS `SetLookingForGroup` writes and `GetLookingForGroup` reads
-    /// back — never the server's (wow-re `lfg-set-get-law.md`, 1961). The slots are always zero
-    /// in the reference: see [`social`].
+    /// The client-local LFG slot words (`[0xbc70a0]`) and comment (`[0xbc6e98]`, 0x80 bytes) that
+    /// `SetLookingForGroup` writes and `GetLookingForGroup` reads; the reference's slots stay 0.
     pub(crate) lfg_slots: [u32; 3],
     pub(crate) lfg_comment: String,
-    /// The guild snapshot the app pushes (roster, ranks, MOTD, info text — decision 1257):
-    /// `GetNumGuildMembers`/`GetGuildRosterInfo`/`GuildControlGetRankFlags`/… read it
-    /// ([`guild`]). Already display-resolved and already sorted + filtered, because the sort
-    /// field and the show-offline toggle live app-side where the roster does.
+    /// Guild roster, ranks, MOTD and info, sorted and filtered by the app, which holds the toggles.
     pub(crate) guild: guild::GuildState,
-    /// The rank-control popup's staging buffer ([`guild::GuildRankEdit`]) — deliberately NOT part
-    /// of [`Self::guild`], because a snapshot push mid-edit would discard the user's unsaved
-    /// checkbox clicks. Flushed by `GuildControlSaveRank`.
+    /// The rank editor's unsaved edits, apart from `guild` so a push cannot discard them.
     pub(crate) guild_control: guild::GuildRankEdit,
-    /// Guild intents (`GuildInviteByName`/`GuildSetMOTD`/`GuildControlSaveRank`/…) queued since
-    /// the app's last [`super::UiScript::take_guild_requests`] drain — the outbound seam
-    /// ([`guild`]).
+    /// Guild calls (`GuildInviteByName`, `GuildSetMOTD`, `GuildControlSaveRank`, …) queued.
     pub(crate) guild_requests: Vec<guild::GuildRequest>,
-    /// The guild-charter snapshot the app pushes (the registrar's price and the open petition —
-    /// decision 1672): `GetPetitionInfo`/`GetPetitionNameInfo`/`GetGuildCharterCost`/… read it
-    /// ([`petition`]). Names and the proposed guild's title are already resolved, because in the
-    /// real client too they come from caches the engine owns and not from the packet that opens
-    /// the window.
+    /// The charter price and open petition, names resolved from caches as the reference does.
     pub(crate) petition: petition::PetitionState,
-    /// Charter intents (`BuyGuildCharter`/`SignPetition`/`TurnInGuildCharter`/…) queued since the
-    /// app's last [`super::UiScript::take_petition_requests`] drain — the outbound seam
-    /// ([`petition`]).
+    /// Charter calls (`BuyGuildCharter`, `SignPetition`, `TurnInGuildCharter`, …) queued.
     pub(crate) petition_requests: Vec<petition::PetitionRequest>,
-    /// Whisper targets `ChatFrame_SendTell` queued since the app's last
-    /// [`super::UiScript::take_tell_requests`] drain — the app opens its chat edit box prefilled
-    /// `/w <name> ` (the unit popup's WHISPER action; [`party`] registers the global).
+    /// Names `ChatFrame_SendTell` queued; the app opens the chat box prefilled `/w <name> `.
     pub(crate) tell_requests: Vec<String>,
-    /// Prefill texts `ChatFrame_OpenChat` queued since the app's last
-    /// [`super::UiScript::take_open_chat_requests`] drain — `tell_requests`' sibling, one step
-    /// less resolved: a name there, a whole draft line here ([`chat_window`] registers the global).
+    /// Draft lines `ChatFrame_OpenChat` queued, for the app to prefill the chat box.
     pub(crate) open_chat_requests: Vec<String>,
-    /// Per-chat-window **look** — background tint, background alpha, font size — index 0 =
-    /// `ChatFrame1` (decision 1589, [`chat_window`]). The engine's own per-window record narrowed
-    /// to the three fields the tab menu's Display block can move; the host seeds it from the
-    /// player's saved file and persists what Lua writes back.
+    /// Per chat window from `ChatFrame1`, the tint, alpha and font size its tab menu can change.
     pub(crate) chat_window_looks: [chat_window::ChatWindowLook; chat_window::NUM_CHAT_WINDOWS],
-    /// The 0-based window indices whose look Lua moved since the app's last
-    /// [`super::UiScript::take_chat_window_changes`] drain — the persist cue. A set, so a slider
-    /// drag costs one entry however many steps it took.
+    /// 0-based windows whose look Lua changed, the persist cue.
     pub(crate) chat_window_changes: HashSet<usize>,
-    /// The chat-type colour registry (`0xb4e518`): 94 fixed entries + 10 `CHANNELn` extras
-    /// (`chat_types`). Seeded from the compiled defaults; the app overlays `chat-cache.txt`'s
-    /// `COLORS` block through [`super::UiScript::set_chat_colors`].
+    /// Chat-type colours (`0xb4e518`): 94 fixed and 10 `CHANNELn`, overlaid by `chat-cache.txt`.
     pub(crate) chat_colors: Vec<super::chat_types::ChatTypeColor>,
-    /// A Lua-side colour write landed — [`super::UiScript::take_chat_color_changes`].
     pub(crate) chat_colors_changed: bool,
-    /// The languages this character knows, `Languages.dbc` row order
-    /// ([`super::UiScript::set_known_languages`]).
+    /// The languages this character knows, in `Languages.dbc` row order.
     pub(crate) known_languages: Vec<String>,
-    /// The zone-channel rows for the current zone ([`super::UiScript::set_zone_channel_catalog`]).
     pub(crate) zone_channel_catalog: Vec<super::channel::ZoneChannelRow>,
-    /// Channel verbs since the last [`super::UiScript::take_channel_commands`] drain.
     pub(crate) channel_commands: Vec<super::channel::ChannelCommand>,
-    /// **The guild-recruitment auto-join latch** — the reference's int global `[0x843608]`, which
-    /// `GetGuildRecruitmentMode` returns and `SetGuildRecruitmentMode` writes (decision 2115).
-    ///
-    /// `0` = STANDARD, `1` = AUTO, and those two words are literally what the per-character chat
-    /// cache stores it as (`OPTION_GUILD_RECRUITMENT_CHANNEL STANDARD|AUTO`; wow-re
-    /// `system/ui/scratch/chat-cache-grammar.md` — the reader maps `STANDARD` to 0 and anything
-    /// else, `AUTO` included, to 1). It boots at **1**: every one of the 33 `chat-cache.txt` files
-    /// the reference client itself wrote in this repo's install says `AUTO`, on characters that
-    /// never opened the option.
+    /// The recruitment auto-join latch `[0x843608]`: 0 `STANDARD`, 1 `AUTO` (`0x49ea70` maps any
+    /// other word to 1). Boots at 1, as the reference writes `AUTO` for an untouched option.
     pub(crate) guild_recruitment_mode: u8,
-    /// A `SetGuildRecruitmentMode(1)` since the last drain — `0x49ea70`'s tail-jump into the
-    /// cascade `0x49ea90`, which the app runs (decision 2144). Keyed on the *new value alone*, not
-    /// on a change: the reference's store is unconditional and the jump reads only `ecx == 1`.
+    /// Any `SetGuildRecruitmentMode(1)`, even unchanged: the reference runs the cascade `0x49ea90`.
     pub(crate) guild_recruitment_cascade: bool,
-    /// Whether Lua has moved [`Self::guild_recruitment_mode`] since the last drain — the chat
-    /// cache's dirty signal, the peer of `chat_window_changes`.
+    /// Lua changed the recruitment mode: the chat cache's dirty signal.
     pub(crate) guild_recruitment_changed: bool,
-    /// `DoEmote` calls since the last drain.
+    /// `DoEmote` calls queued.
     pub(crate) emote_requests: Vec<super::chat_misc::EmoteRequest>,
-    /// `RandomRoll` calls since the last drain.
+    /// `RandomRoll` calls queued.
     pub(crate) roll_requests: Vec<(u32, u32)>,
-    /// `UninviteByName` calls since the last drain.
+    /// `UninviteByName` calls queued.
     pub(crate) uninvite_requests: Vec<String>,
     /// `ConsoleExec` lines that were not CVar writes.
     pub(crate) console_lines: Vec<String>,
-    /// `LoggingChat` / `LoggingCombat` — the two flags and their change cue.
+    /// `LoggingChat` and `LoggingCombat`'s flags, and their change cue.
     pub(crate) logging_chat: bool,
     pub(crate) logging_combat: bool,
     pub(crate) logging_changed: bool,
-    /// Whether a **user-placed** frame's geometry moved since the app's last
-    /// [`super::UiScript::take_user_placed_change`] drain — the layout cache's persist cue
-    /// ([`super::layout_cache`]). One bit rather than a set of handles, because the file is
-    /// rewritten whole either way; set by the move/resize pumps and by `SetUserPlaced` itself.
+    /// A user-placed frame moved or resized, or `SetUserPlaced` ran: the layout cache's save cue.
     pub(crate) user_placed_changed: bool,
-    /// The player's default chat language name, app-resolved from `ChrRaces.BaseLanguage` ×
-    /// `Languages.dbc` ([`super::UiScript::set_default_language`]). `None` = the reference's
-    /// no-player-object state, where `GetDefaultLanguage()` returns **zero Lua values**
-    /// ([`chat_send`]).
+    /// The default chat language; `None` is no player, so `GetDefaultLanguage()` returns nothing.
     pub(crate) default_language: Option<String>,
-    /// Duel intents (`AcceptDuel`/`CancelDuel`/`StartDuel*`) queued since the app's last
-    /// [`super::UiScript::take_duel_requests`] drain — the outbound seam ([`duel`]). There is no
-    /// duel *snapshot* beside it: everything the UI reads arrives as event arguments.
+    /// `AcceptDuel`, `CancelDuel` and `StartDuel*` calls; Lua sees duels only through events.
     pub(crate) duel_requests: Vec<duel::DuelRequest>,
-    /// Follow intents (`FollowUnit`/`FollowByName`) queued since the app's last
-    /// [`super::UiScript::take_follow_requests`] drain — the outbound seam ([`follow`]). The duel
-    /// queue's twin, snapshot-less for the same reason: the only thing the UI reads back is the
-    /// `AUTOFOLLOW_BEGIN`/`AUTOFOLLOW_END` pair the app fires, which carries its own argument.
+    /// `FollowUnit` and `FollowByName` calls; Lua sees following only as `AUTOFOLLOW_*` events.
     pub(crate) follow_requests: Vec<follow::FollowRequest>,
-    /// Camera-view intents (`SetView`/`SaveView`/`ResetView`/`NextView`/`PrevView`/
-    /// `FlipCameraYaw`) queued since the app's last
-    /// [`super::UiScript::take_camera_view_requests`] drain — the outbound seam
-    /// ([`camera_view`]). Snapshot-less like the follow queue: the five views live on the app's
-    /// camera rig, and they reach Lua the way the reference's do — as the
-    /// `cameraView` / `camera{Distance,Pitch,Yaw}{,A..D}` CVars — not as a second copy here.
+    /// `SetView`, `SaveView`, `ResetView`, `NextView`, `PrevView` and `FlipCameraYaw` calls; the
+    /// views reach Lua only as CVars, `cameraView` and `camera{Distance,Pitch,Yaw}{,A..D}`.
     pub(crate) camera_view_requests: Vec<camera_view::CameraViewRequest>,
-    /// Session-exit intents (`Logout`/`Quit`/`CancelLogout`/`ForceQuit`) queued since the app's
-    /// last [`super::UiScript::take_session_requests`] drain — the outbound seam ([`session`]).
-    /// Snapshot-less like the duel queue above: what the UI reads back (the camp/quit countdown)
-    /// arrives as the `PLAYER_CAMPING`/`PLAYER_QUITING`/`LOGOUT_CANCEL` events, not as state.
+    /// `Logout`, `Quit`, `CancelLogout`, `ForceQuit` calls; Lua sees the countdown only as events.
     pub(crate) session_requests: Vec<session::SessionRequest>,
-    /// PvP-flag toggles (`TogglePVP`) queued since the app's last
-    /// [`super::UiScript::take_pvp_toggles`] drain — the outbound seam ([`pvp`]). A count, not a
-    /// payload: `CMSG_TOGGLE_PVP` carries no body.
+    /// `TogglePVP` calls, a count because `CMSG_TOGGLE_PVP` has no body.
     pub(crate) pvp_toggles: u32,
-    /// The local player's honor snapshot ([`pvp::HonorState`], decision 1512) — the PRIVATE honor
-    /// descriptor fields the app decodes and pushes ([`super::UiScript::set_honor`]). `None`
-    /// before the first push, which the six self getters read as a zeroed snapshot (see
-    /// [`pvp`]'s module doc for why they never return short).
+    /// The player's private honor fields; before the first push the six self getters read zeros.
     pub(crate) honor: Option<pvp::HonorState>,
-    /// The last `MSG_INSPECT_HONOR_STATS` reply the app pushed ([`pvp::InspectHonorData`]). Its
-    /// PRESENCE is `HasInspectHonorData`'s answer — the latch the reference's inspect pane gates
-    /// its request on — so `None` is a state, not a gap.
+    /// The last `MSG_INSPECT_HONOR_STATS` reply; its presence is `HasInspectHonorData`'s answer.
     pub(crate) inspect_honor: Option<pvp::InspectHonorData>,
-    /// `RequestInspectHonorData` calls since the app's last
-    /// [`super::UiScript::take_inspect_honor_requests`] drain. A count for [`Self::pvp_toggles`]'s
-    /// reason: the binding takes no argument, and the guid the send needs is the app's own inspect
-    /// target. With [`Self::inspect_honor_pending`] gating the binding it can only ever drain `0`
-    /// or `1` — the engine has at most one query outstanding.
+    /// `RequestInspectHonorData` calls; the pending gate keeps this at 0 or 1.
     pub(crate) inspect_honor_requests: u32,
-    /// The engine's `pending` flag (`0xb71fcc`): a `MSG_INSPECT_HONOR_STATS` query is queued and
-    /// no reply has landed. `RequestInspectHonorData` (`0x4c80a0`) refuses while it is set, which
-    /// is what stops a pane shown/hidden/shown in quick succession sending duplicate queries.
-    /// Cleared by **either** arm of [`super::UiScript::set_inspect_honor`] — a reply landed
-    /// (`0x4c6f4c`), or the app invalidated the slot (`0x4c6f9d`).
+    /// An inspect-honor query is out (`0xb71fcc`); `RequestInspectHonorData` (`0x4c80a0`) refuses
+    /// while set. Cleared by a reply (`0x4c6f4c`) or by the app clearing the slot (`0x4c6f9d`).
     pub(crate) inspect_honor_pending: bool,
-    /// The two **equipment-display** preferences as the VM currently believes them —
-    /// `ShowingHelm()` / `ShowingCloak()` ([`worn_display`], decision 1472). Not a setting: the
-    /// truth is `PLAYER_FLAGS`' `HIDE_HELM`/`HIDE_CLOAK` bits, pushed here on the descriptor edge
-    /// by [`super::UiScript::set_worn_display`]. Both start **shown**, which is both the reference's
-    /// panel default and the zero-flags state a fresh character logs in with.
+    /// `ShowingHelm()`: `PLAYER_FLAGS`' `HIDE_HELM` bit as pushed, set ahead on `ShowHelm` because
+    /// the wire verb is a blind toggle. Starts shown, as a fresh character's flags are 0.
     pub(crate) helm_shown: bool,
-    /// The cloak half of [`Self::helm_shown`].
+    /// `ShowingCloak()`, the same for `HIDE_CLOAK`.
     pub(crate) cloak_shown: bool,
-    /// Worn-display flips (`ShowHelm`/`ShowCloak` asked for a state we were not in) queued since
-    /// the app's last [`super::UiScript::take_worn_display_toggles`] drain — one
-    /// `CMSG_TOGGLE_HELM`/`CMSG_TOGGLE_CLOAK` each. A list, not a count like [`Self::pvp_toggles`]:
-    /// the two slots are different packets.
+    /// Flips from `ShowHelm`/`ShowCloak`, one `CMSG_TOGGLE_HELM`/`CMSG_TOGGLE_CLOAK` each.
     pub(crate) worn_display_toggles: Vec<super::worn_display::WornDisplay>,
 
-    /// The server's `PLAYER_FIELD_BYTES` **byte 2** — which of the four extra action bars are on
-    /// ([`action_bar_toggles`], wow-re `system/ui/scratch/action-bar-toggles.md`). `None` until the
-    /// app pushes it ([`super::UiScript::set_action_bar_toggles`]), which is the ONLY thing that
-    /// moves it: the real client never writes this cell, so `SetActionBarToggles` deliberately
-    /// leaves it alone and the value lags the setter by a round trip. That is the opposite
-    /// arrangement to [`Self::helm_shown`] next door, and the difference is the wire verb's — a
-    /// blind flip has to be predicted, an absolute post does not.
+    /// `PLAYER_FIELD_BYTES` byte 2 (descriptor `+0x102a`), which extra action bars are on. Only
+    /// the server moves it, as in the reference: `SetActionBarToggles` leaves it a round trip late.
     pub(crate) action_bar_toggles: Option<u8>,
-    /// `CMSG_SET_ACTIONBAR_TOGGLES` payloads queued since the app's last
-    /// [`super::UiScript::take_action_bar_toggle_sends`] drain — one per `SetActionBarToggles`
-    /// call. A list, because the binding gates nothing: two calls in a frame are two packets.
+    /// One `CMSG_SET_ACTIONBAR_TOGGLES` payload per `SetActionBarToggles` call, ungated.
     pub(crate) action_bar_toggle_sends: Vec<u8>,
 
-    /// Sounds queued by the Lua `PlaySound`/`PlaySoundFile` bindings since the app's last
-    /// [`UiScript::take_sounds`] drain — the outbound Lua→app intent seam ([`sound`]).
+    /// `PlaySound` and `PlaySoundFile` calls queued.
     pub(crate) sound_queue: Vec<SoundRequest>,
 
-    /// **The UI-load sound-suppression depth** — `[0xb05fa0]` in the reference, a counted scope
-    /// with exactly three references image-wide: `0x458f50` (`inc`), `0x458f60` (`dec`), and one
-    /// reader at `0x458046`, inside `PlaySoundByName 0x458030`. The whole-UI load `0x48fbf0`
-    /// brackets ITSELF in it — `0x48fbfa` on entry, `0x49016d` on exit, spanning the TOC walk,
-    /// `Bindings.xml` and the AddOns — and both of its callers, login (`0x48f681`) and `/reloadui`
-    /// (`0x495669`), therefore load silently.
-    ///
-    /// The reader bails at `0x45804d` **before** the `MasterSoundEffects` CVar and the kit-hash
-    /// lookup, so a suppressed call is **dropped**: not muted, not queued, no Lua error, and the
-    /// binding still answers its usual `(willPlay, handle)`. Scoped to the NAME-keyed entry only —
-    /// id-keyed `PlaySound(kitId)` (`0x457fb0`/`0x457ff0`), `PlaySoundFile`, `PlayMusic` and
-    /// `StopMusic` all run normally inside the scope.
-    ///
-    /// This is what makes stock `TargetFrame_OnHide`'s `PlaySound("INTERFACESOUND_LOSTTARGETUNIT")`
-    /// inaudible at every login: the frame really is shown when its `OnLoad` hides it, the OnHide
-    /// really does fire, the call really is made — and the engine throws it away. Decision 1033's
-    /// "no sound during the load" is the client's own law, enforced here rather than by hoping no
-    /// handler rings.
+    /// `PlayMusic` and `StopMusic` calls in call order, for the Lua music stream (`[0xb06ccc]`).
+    pub(crate) music_queue: Vec<MusicRequest>,
+
+    /// The UI-load sound-suppression depth, the reference's `[0xb05fa0]` (`0x458f50` inc,
+    /// `0x458f60` dec), held across the whole UI load `0x48fbf0`, so login and `/reloadui` are
+    /// silent. Only name-keyed `PlaySound` (`0x458030`) reads it: the call is dropped before any
+    /// lookup yet answers `(willPlay, handle)` as usual. `PlaySound(kitId)` (`0x457fb0`),
+    /// `PlaySoundFile` and music play normally.
     pub(crate) sound_suppression: u32,
 
-    /// The CVar table (decision 0954, [`super::cvars`]): lowercase name → slot. Host-registered
-    /// only; Lua reads/writes through `GetCVar`/`SetCVar`/`GetCVarDefault`.
+    /// The CVar table, by lowercased name.
     pub(crate) cvars: HashMap<String, super::cvars::CvarSlot>,
-    /// The persisted values registration honors (decision 1291): lowercase name → the config
-    /// file's value, set by the host **before** any registration. A CVar registered while its
-    /// name is in here — host-registered or an addon's `RegisterCVar` — starts at the saved
-    /// value, not the default. This is what makes a knobless CVar (`statusBarText`) and an
-    /// addon-declared one survive the VM being replaced: in the reference the table is engine
-    /// memory and outlives every `ReloadUI`; ours is per-VM, so the file value is the bridge.
+    /// Saved CVar values, set before any registration so a CVar starts at its saved value: the
+    /// reference's table outlives `ReloadUI`, while ours is per VM.
     pub(crate) cvars_saved_base: HashMap<String, String>,
-    /// `(registered name, new value)` per Lua `SetCVar` since the app's last
-    /// [`super::UiScript::take_cvar_changes`] drain — the knob-sync + config-dirty cue.
+    /// `(registered name, new value)` per Lua `SetCVar`, the app's sync and save cue.
     pub(crate) cvar_changes: Vec<(String, String)>,
-    /// `(name, default)` per addon `RegisterCVar` that created a slot, since the host's last
-    /// [`super::UiScript::take_cvar_registrations`] drain (decision 2303).
+    /// `(name, default)` per addon `RegisterCVar` that created a slot.
     pub(crate) cvar_registrations: Vec<(String, String)>,
-    /// Unknown CVar names already warned about (warn-once, the era-atlas-miss posture).
     pub(crate) cvars_warned: HashSet<String>,
 
-    /// The device-enumerated multisample formats the Video options dropdown offers, in the order
-    /// it offers them — pushed by the host ([`super::UiScript::set_multisample_formats`]) from what
-    /// the render adapter actually accepts, and read by `GetMultisampleFormats` /
-    /// `GetCurrentMultisampleFormat` / `SetMultisampleFormat`.
-    ///
-    /// In the reference this is the distilled `{colorBits, depthBits, multisample}` triple list at
-    /// `[0xb4b444]` (count `[0xb4b440]`), built by `0x48c3e0` from the D3D
-    /// `CheckDeviceMultiSampleType` sweep or the GL `wglGetPixelFormatAttribivARB` sweep. Empty
-    /// until the host pushes it — a VM with no device behind it (every extract test) offers no
-    /// formats rather than inventing some.
+    /// The adapter's multisample formats in dropdown order, the reference's list `[0xb4b444]` of
+    /// `{colorBits, depthBits, multisample}` (count `[0xb4b440]`, built by `0x48c3e0`).
     pub(crate) multisample_formats: Vec<super::cvars::MultisampleFormat>,
 
-    /// The screen resolutions the Video options window's dropdown offers, ascending — pushed by
-    /// the host ([`super::UiScript::set_screen_resolutions`]) from the display this client is on,
-    /// and read by `GetScreenResolutions` / `GetCurrentResolution` / `SetScreenResolution`.
-    ///
-    /// Empty until the host pushes it. A VM with no window behind it (every extract test) offers
-    /// none rather than inventing a ladder, and the reference's own consumer walks it zero times.
+    /// This display's resolutions, ascending, behind `GetScreenResolutions`; empty until pushed.
     pub(crate) screen_resolutions: Vec<super::cvars::ScreenResolution>,
-    /// **Where in that list the client actually is** — the index `GetCurrentResolution` answers,
-    /// 0-based here and reported 1-based, which is the form `CT_Viewport.lua:105` indexes the
-    /// `GetScreenResolutions` varargs with (`arg[GetCurrentResolution()]`).
-    ///
-    /// Held as an index rather than a size so the two can never disagree: the host guarantees the
-    /// live size is IN the list when it pushes, which is what makes that addon's read total.
-    /// `None` while the list is empty.
+    /// The live size's index in that list, which the host always includes; `None` while the list
+    /// is empty. `GetCurrentResolution` answers it 1-based.
     pub(crate) current_resolution: Option<usize>,
-    /// What this run's device and presentation path really offer, behind `GetVideoCaps` — pushed
-    /// by the host, which is the only side holding a `RenderAdapter`.
+    /// What this device and presentation path offer, behind `GetVideoCaps`.
     pub(crate) video_caps: super::cvars::VideoCaps,
-    /// `RestartGx()` calls queued since the host last drained them — the video window's
-    /// "apply the staged settings now" button, counted like [`Self::screenshot_asks`] because the
-    /// request carries no payload.
+    /// `RestartGx()` calls, the video window's apply button.
     pub(crate) restart_gx_asks: u32,
 
-    /// The globals `RegisterForSave` declared, in registration order — the saved-variables set the
-    /// host writes out at logout/exit and re-executes at load (decision 1128, [`super::saved`]).
+    /// Globals `RegisterForSave` declared, in order: written at logout and re-run at load.
     pub(crate) saved_names: Vec<String>,
+    /// Saved-variables files that failed to load; the shutdown write leaves them untouched.
+    pub(crate) held_saved_files: Vec<std::path::PathBuf>,
 
-    /// The key-binding table (decision 0997, [`super::keybind`]) — the chord→command store the
-    /// Key Bindings window edits, plus its stored account/character sets. The CVar table's twin:
-    /// host-registered commands, Lua reads/writes synchronously, the app re-derives dispatch when
-    /// [`super::UiScript::keybinds_generation`] moves and persists on the queued save requests.
+    /// The key-binding table the Key Bindings window edits, with its account and character sets.
     pub(crate) keybinds: super::keybind::KeybindState,
 
-    /// The action-slot snapshot (keyed by Lua action id 1..120) + the stance page offset the app
-    /// pushes, and the `UseAction` intents it drains — the action seam ([`action`]).
+    /// Action slots by Lua action id, 1..120.
     pub(crate) actions: HashMap<u32, ActionSlot>,
-    /// The per-action **dynamic** state (usable/range/current/cooldown — decision 0137 phase 4),
-    /// pushed beside `actions` by the app's feed; the `IsUsableAction`/`GetActionCooldown` family
-    /// reads it ([`action`]). Keyed like `actions`; an absent action reads cold/nil.
+    /// Per action, its usable, range, current and cooldown state; an absent one reads cold.
     pub(crate) action_states: HashMap<u32, super::action::StoredActionState>,
     pub(crate) bonus_bar_offset: u8,
     pub(crate) action_uses: Vec<super::action::ActionUse>,
-    /// `(lua action id, packed)` pairs queued by `PickupAction`/`PlaceAction` (decision 0216 §7,
-    /// slice 4) — one entry per local slot mutation, `packed == 0` clearing the slot. Drained by
-    /// the app into `CMSG_SET_ACTION_BUTTON`, one send per entry (client-authoritative, per-change
-    /// — 0218 §4: a drag-swap is two sends, never atomic).
+    /// `(action id, packed)` per slot `PickupAction`/`PlaceAction` changed, 0 clearing it: one
+    /// `CMSG_SET_ACTION_BUTTON` each, so a drag swap is two sends.
     pub(crate) action_sets: Vec<(u32, u32)>,
-    /// GlobalStrings keys for **client-local refusals the ENGINE raises** — the engine-free half
-    /// of the app's `ui_action::UiErrorKeys`, which cannot reach in here. The reference does this
-    /// inline (`push <errorId>; call CGGameUI::DisplayError 0x496720`) because its engine owns
-    /// both the refusal and the message; ours splits at the crate boundary, so the refusal queues
-    /// its key and the app's action feed resolves it against the VM's own GlobalStrings and fires
-    /// `UI_ERROR_MESSAGE`. Always `&'static str`: every tenant is a literal read out of the ref's
-    /// errorId table (`0xb4b498`, stride `0x14`), never runtime-built.
+    /// GlobalStrings keys of refusals this crate raises, fired by the app as `UI_ERROR_MESSAGE`
+    /// (the reference's `DisplayError` `0x496720`), each a literal from `0xb4b498` (stride `0x14`).
     pub(crate) ui_errors: Vec<&'static str>,
 
-    /// The player's known-spell book (decision 0216 §8, slice 5) — tabs + the flat slot list the
-    /// `GetSpellTabInfo`/`GetSpellName`/… bindings read ([`spellbook`]). Durable player state like
-    /// `actions` above, never `Option` — "no known spells yet" is simply empty vectors.
     pub(crate) spellbook: spellbook::SpellBookState,
-    /// The **pet's** book (decision 1032) — a second flat slot list, no tabs, with its own
-    /// add-gate and its own class token ([`spellbook::PetBookState`]). Held apart from
-    /// [`Self::spellbook`] because the reference holds two arrays too (`0xb700f0` / `0xb6f098`)
-    /// and every `bookType`-taking binding is a fork between them, never a filter over one.
+    /// The pet's spellbook, a second array as in the reference (`0xb700f0`, `0xb6f098`).
     pub(crate) pet_book: spellbook::PetBookState,
-    /// The player's **macros** (decision 0983) — the one game-state table this crate owns
-    /// outright, because 1.12 macros have no server side at all ([`macros`]'s module docs). The
-    /// app seeds it from `benilla-config/macros/…` and reads it back to persist.
+    /// The player's macros, owned here as 1.12 macros have no server side; the app persists them.
     pub(crate) macros: macros::MacroState,
-    /// A script mutated [`Self::macros`] since the app's last
-    /// [`super::UiScript::take_macros_dirty`] drain — the save + `UPDATE_MACROS` trigger.
+    /// A script changed the macros: the save and `UPDATE_MACROS` cue.
     pub(crate) macros_dirty: bool,
-    /// Bumped by every seed and every mutation — the *undrained* change signal per-frame
-    /// consumers gate on ([`super::UiScript::macros_generation`]), so the drained
-    /// [`Self::macros_dirty`] edge keeps its single owner.
+    /// Bumped by every seed and change, for readers that must not drain `macros_dirty`.
     pub(crate) macros_generation: u64,
-    /// The macro-icon chooser list (full texture paths, app-built off `SpellIcon.dbc`) —
-    /// `GetNumMacroIcons`/`GetMacroIconInfo`.
+    /// The macro icon paths from `SpellIcon.dbc`, behind `GetMacroIconInfo`.
     pub(crate) macro_icons: Vec<String>,
-    /// Spell ids `CastSpell` queued since the app's last [`super::UiScript::take_spell_casts`]
-    /// drain.
+    /// Spell ids `CastSpell` queued.
     pub(crate) spell_casts: Vec<u32>,
-    /// Pet spell ids `CastSpell(id, "pet")` queued — a separate list because the wire verb is a
-    /// separate opcode (`CMSG_PET_ACTION` with a synthesized type-1 word, `0x4b34ce`).
+    /// `CastSpell(id, "pet")` ids, sent as `CMSG_PET_ACTION` with a type-1 word (`0x4b34ce`).
     pub(crate) pet_spell_casts: Vec<u32>,
-    /// Pet spell ids `ToggleSpellAutocast` queued — `CMSG_PET_SPELL_AUTOCAST 0x2F3`, which names a
-    /// spell rather than the pet bar's slot ([`Self::pet_autocast_toggles`] is the bar's).
+    /// `ToggleSpellAutocast` ids for `CMSG_PET_SPELL_AUTOCAST` (`0x2F3`), which names a spell.
     pub(crate) pet_spell_autocasts: Vec<u32>,
-    /// Whether the app's own cast lifecycle holds something `SpellStopCasting()` can stop — a
-    /// running auto-repeat or an in-flight cast; a channel is NOT stoppable there (wow-re
-    /// `esc-stopcasting.md`; pushed each frame by the app's cast feed,
-    /// [`super::UiScript::set_casting`]). The 1/nil return is load-bearing:
-    /// `ToggleGameMenu`'s ESC chain (`UIParent.lua:1489`) only falls through to
-    /// `CloseAllWindows()` on nil.
+    /// An auto-repeat or cast that `SpellStopCasting()` can stop, not a channel (`0x6e6e80`). Its
+    /// 1 or nil matters: the ESC chain (`UIParent.lua:1489`) reaches `CloseAllWindows()` on nil.
     pub(crate) casting: bool,
-    /// Set when `SpellStopCasting()` fired while [`Self::casting`] — the ESC local-cancel
-    /// trigger, drained by [`super::UiScript::take_spell_stop`] ([`spellbook`]).
+    /// `SpellStopCasting()` fired while casting: the ESC cancel.
     pub(crate) spell_stop: bool,
-    /// Whether the app's spell-targeting cursor mode is active — the `flag_word != 0` mirror
-    /// (`SpellIsTargeting 0x6e6cd0`, decision 0792). Pushed each frame by the app's targeting
-    /// feed ([`super::UiScript::set_spell_targeting`]); read by `SpellIsTargeting()` and gating
-    /// `SpellStopTargeting()`, whose 1/nil return the ESC chain's rung (`UIParent.lua:1490`)
-    /// falls through on, exactly like [`Self::casting`]'s.
+    /// Spell targeting is on (`SpellIsTargeting`, `0x6e6cd0`); it gates `SpellStopTargeting()`,
+    /// whose nil the ESC chain falls through on (`UIParent.lua:1490`).
     pub(crate) spell_targeting: bool,
-    /// Whether the standing targeting word could bind a UNIT — what `SpellCanTargetUnit` answers
-    /// (`0x6e6d00` → `0x6e6460`'s unit leg). Pushed by the app beside `spell_targeting`.
-    ///
-    /// Always `false` today, and *derived* rather than hardcoded so it stops being false the moment
-    /// that stops being true: benilla's targeting cursor models the location / item / gameobject
-    /// words (0792/0923/0939), and no unit satisfies any of them — a unit-target spell never enters
-    /// targeting mode at all, it resolves to `CastWireTarget::Unit` or refuses.
+    /// `SpellCanTargetUnit` (`0x6e6d00`, `0x6e6460`): false while targeting models only location,
+    /// item and object words; a unit-target spell resolves or refuses without entering targeting.
     pub(crate) spell_can_target_unit: bool,
-    /// Set when `SpellStopTargeting()` fired while [`Self::spell_targeting`] — the ESC-chain
-    /// targeting cancel, drained by [`super::UiScript::take_stop_targeting`] ([`spellbook`]).
+    /// `SpellStopTargeting()` fired while targeting: the ESC targeting cancel.
     pub(crate) spell_stop_targeting: bool,
 
-    /// The player's talent pages (decision 0304) — tabs + per-tab talents the
-    /// `GetNumTalentTabs`/`GetTalentInfo`/… bindings read ([`super::talent`]). Durable player
-    /// state like `spellbook`; "no talents yet" is simply empty.
     pub(crate) talents: super::talent::TalentUiState,
-    /// `LearnTalent(tab, index)` clicks queued since the app's last
-    /// [`super::UiScript::take_talent_learns`] drain.
+    /// `LearnTalent(tab, index)` calls queued.
     pub(crate) talent_learns: Vec<(u32, u32)>,
-    /// `ConfirmTalentWipe()` calls queued since the app last drained them — each is one outbound
-    /// `MSG_TALENT_WIPE_CONFIRM`. A COUNT for [`Self::binder_confirms`]'s reason: the app holds
-    /// the trainer's guid, so the intent carries no payload of its own (decision 1580).
+    /// `ConfirmTalentWipe()` calls, one `MSG_TALENT_WIPE_CONFIRM` each; the app holds the trainer.
     pub(crate) talent_wipe_confirms: u32,
-    /// Is a trainer's respec question still live and in range — the answer
-    /// `CheckTalentMasterDist()` gives, pushed by the app each frame
-    /// ([`super::UiScript::set_talent_master_pending`]). The CONFIRM_TALENT_WIPE dialog polls it
-    /// from OnUpdate and hides itself when it goes false; the binder question's twin, and the same
-    /// range gate stands behind both (decision 1580).
+    /// `CheckTalentMasterDist()`: the respec question is live and in range; false hides its dialog.
     pub(crate) talent_master_pending: bool,
-    // ── The dialog engine's verbs (decision 1963; wow-re `staticpopup-dialog-bindings.md`) ──
-    /// `ConfirmPetUnlearn()` calls since the app's last drain — the pet trainer's twin of
-    /// [`Self::talent_wipe_confirms`]; the app holds the latched trainer and the money gate.
+    // ── The dialog engine's verbs (`0x48dca0` is the first below) ──
+    /// `ConfirmPetUnlearn()` calls; the app holds the trainer and the money gate.
     pub(crate) pet_unlearn_confirms: u32,
-    /// Whether the pet trainer's question is pending AND the trainer is in reach — what
-    /// `CheckPetUntrainerDist()` answers, pushed by the app each frame.
+    /// `CheckPetUntrainerDist()`: the pet trainer's question is pending and in reach.
     pub(crate) pet_untrainer_pending: bool,
-    /// `GetInstanceBootTimeRemaining()`'s answer in whole seconds, 0 when idle — the app derives
-    /// it from the `SMSG_RAID_GROUP_ONLY` deadline each frame.
+    /// `GetInstanceBootTimeRemaining()` in whole seconds, from the `SMSG_RAID_GROUP_ONLY` deadline.
     pub(crate) instance_boot_secs: u32,
-    /// Whether a battleground spirit healer is the cached current-area healer (a non-zero
-    /// `[0xb4e330/334]`), and the seconds to its next wave (`[0xb4e338]`), both the app's.
+    /// A cached area spirit healer (`[0xb4e330/334]`) and seconds to its wave (`[0xb4e338]`).
     pub(crate) area_spirit_healer_cached: bool,
     pub(crate) area_spirit_secs: u32,
-    /// `AcceptAreaSpiritHeal()` calls since the last drain (each one `CMSG_AREA_SPIRIT_HEALER_QUEUE`
-    /// with the cached healer — the app holds the guid).
+    /// `AcceptAreaSpiritHeal()` calls, one `CMSG_AREA_SPIRIT_HEALER_QUEUE` each.
     pub(crate) area_spirit_accepts: u32,
     /// `AcceptBattlefieldPort(index, accept)` calls: the 1-based slot and the normalised answer.
     pub(crate) battlefield_port_requests: Vec<(u8, bool)>,
-    /// The battleground scoreboard (1972): the pushed rows, the faction filter, the sorted order.
+    /// The battleground scoreboard: pushed rows, faction filter, sort order.
     pub(crate) battlefield_board: super::battlefield_score::ScoreBoard,
-    /// `GetBattlefieldInstanceRunTime()`'s answer, pushed each frame by the app's clock.
+    /// `GetBattlefieldInstanceRunTime()`, pushed each frame.
     pub(crate) battlefield_run_time_ms: u32,
-    /// `RequestBattlefieldScoreData()` calls since the last drain.
+    /// `RequestBattlefieldScoreData()` calls.
     pub(crate) battlefield_score_requests: u32,
-    /// `LeaveBattlefield()` calls that passed the "ended" gate since the last drain.
+    /// `LeaveBattlefield()` calls that passed the "ended" gate.
     pub(crate) battlefield_leave_requests: u32,
-    /// The battleground instance list and its scalars (1974), as the app last pushed them.
+    /// The battleground instance list and its scalars, as pushed.
     pub(crate) battlefield_list: super::battlefield_queue::BattlefieldListView,
-    /// `[0xb6eba0]` — the selected instance id (a VALUE; `SetSelectedBattlefield` writes it).
+    /// The selected instance id (`[0xb6eba0]`), not an index; written by `SetSelectedBattlefield`.
     pub(crate) battlefield_selected: u32,
-    /// The three queue slots (1974), pushed each frame with their clock-shaped values reduced.
+    /// The three queue slots, pushed each frame with their clocks reduced to values.
     pub(crate) battlefield_slots: Vec<super::battlefield_queue::BattlefieldQueueSlot>,
-    /// `GetBattlefieldInstanceExpiration()`'s answer, pushed each frame.
+    /// `GetBattlefieldInstanceExpiration()`, pushed each frame.
     pub(crate) battlefield_instance_expiration_ms: u32,
-    /// `JoinBattlefield` calls since the last drain: `(instance id, as group)`.
+    /// `JoinBattlefield` calls, `(instance id, as group)`.
     pub(crate) battlefield_join_requests: Vec<(u32, bool)>,
     /// `ShowBattlefieldList` calls that passed their gates: the queued slot's map id.
     pub(crate) battlefield_list_requests: Vec<u32>,
-    /// The battleground teammates' map positions as the app resolved them (1980), the flag
-    /// carrier, the active map's icon scale, and `RequestBattlefieldPositions()` calls.
+    /// Teammates' map positions, the flag carrier, the icon scale and position requests.
     pub(crate) battlefield_positions: Vec<super::battlefield_positions::BattlefieldPositionView>,
     pub(crate) battlefield_flag: Option<super::battlefield_positions::BattlefieldFlagView>,
     pub(crate) battlefield_icon_scale: f32,
     pub(crate) battlefield_position_requests: u32,
-    /// `CancelMeetingStoneRequest()` calls since the last drain — the app gates on leadership.
+    /// `CancelMeetingStoneRequest()` calls; the app gates on leadership.
     pub(crate) meeting_stone_cancels: u32,
-    /// The meeting stone's queued area (`[0xb72038]`) and cached status text (`[0xb7203c]`), as the
-    /// app last pushed them (1974).
+    /// The meeting stone's queued area (`[0xb72038]`) and status text (`[0xb7203c]`), as pushed.
     pub(crate) meeting_stone_area: u32,
     pub(crate) meeting_stone_status_text: Option<String>,
-    /// The tutorial system's acknowledged bank, as the app last pushed it (1976); `None` before
-    /// `SMSG_TUTORIAL_FLAGS` — `TutorialsEnabled()`'s only input.
+    /// Acknowledged tutorials, `None` before `SMSG_TUTORIAL_FLAGS`; all `TutorialsEnabled()` reads.
     pub(crate) tutorial_bank: Option<Vec<u8>>,
-    /// `FlagTutorial(n)` calls since the last drain (0-based, in range).
+    /// `FlagTutorial(n)` calls, 0-based and in range.
     pub(crate) tutorial_flag_requests: Vec<u32>,
     pub(crate) tutorial_clears: u32,
     pub(crate) tutorial_resets: u32,
 
-    /// The stance/shapeshift bar's form list (bar order) the app pushes — the
-    /// `GetNumShapeshiftForms`/`GetShapeshiftFormInfo` family reads it ([`super::shapeshift`]).
-    /// Durable player state like `spellbook`; "no forms" (a mage) is simply empty.
+    /// The stance bar's forms, in bar order.
     pub(crate) shapeshift_forms: Vec<super::shapeshift::StoredShapeshiftForm>,
-    /// Form spell ids `CastShapeshiftForm` queued since the app's last
-    /// [`super::UiScript::take_shapeshift_casts`] drain.
+    /// Form spell ids `CastShapeshiftForm` queued.
     pub(crate) shapeshift_casts: Vec<u32>,
 
-    /// The pet action bar the app pushes — the ten slots plus the two bar-wide bits the
-    /// `PetHasActionBar`/`GetPetActionsUsable`/`GetPetActionInfo` family reads ([`super::pet`],
-    /// decision 0982). Unlike the stance bar's, this state is **server-authoritative**: it is
-    /// replaced wholesale on every `SMSG_PET_SPELLS`, and is empty whenever there is no pet.
+    /// The pet bar's ten slots and two bar-wide bits, replaced whole by every `SMSG_PET_SPELLS`.
     pub(crate) pet_bar: super::pet::PetBarState,
-    /// 1-based slot indices `CastPetAction` queued since the app's last
-    /// [`super::UiScript::take_pet_actions`] drain.
+    /// 1-based slots `CastPetAction` queued.
     pub(crate) pet_actions_pressed: Vec<u32>,
     /// 1-based slot indices `TogglePetAutocast` queued.
     pub(crate) pet_autocast_toggles: Vec<u32>,
-    /// `PetStopAttack()` calls queued — a count, since the verb takes no argument.
+    /// `PetStopAttack()` calls.
     pub(crate) pet_stop_attacks: u32,
-    /// The pet one-shot orders (`PetAttack`, `PetFollow`, `PetWait`, the three modes), each the
-    /// packed slot word the bar's own command or reaction slot would carry — the app's drain
-    /// presses them exactly as a slot (1958).
+    /// `PetAttack`, `PetFollow`, `PetWait` and mode orders, as the packed word of their bar slot.
     pub(crate) pet_orders: Vec<u32>,
-    /// `HasFullControl`'s flag — the reference's `[0xb4b3e4]`, written by
-    /// `SMSG_CLIENT_CONTROL_UPDATE` naming the local player and read as "if zero, refuse" by
-    /// every cast, item and cursor gate (wow-re `control-loss-and-restore.md`). Boot value 1.
+    /// `HasFullControl`, the reference's `[0xb4b3e4]`: set by `SMSG_CLIENT_CONTROL_UPDATE` for the
+    /// player, boots 1, and every cast, item and cursor gate refuses at 0.
     pub(crate) player_control: bool,
-    /// Pet bar writes queued by the drag ([`cursor::pet`], decision 1010) — **one entry per
-    /// `CMSG_PET_SET_ACTION`**, each holding the one or two `(0-based position, packed word)` pairs
-    /// that send names. The nesting is the point: the server tells the one-pair form from the
-    /// two-pair form **by body size**, so a relocation and its write must travel together and must
-    /// not be flattened into a stream of singles.
+    /// One `CMSG_PET_SET_ACTION` per entry, its one or two `(position, packed word)` pairs: the
+    /// server tells the forms apart by body size, so a move's two pairs must not be flattened.
     pub(crate) pet_set_actions: Vec<Vec<(u32, u32)>>,
-    /// `PetAbandon()` and `PetDismiss()` calls queued — two counts, not one, even though both menu
-    /// rows end at the same opcode (decision 1066). They are two *bindings*, with two Lua names and
-    /// two menu rows the reference shows to different classes, so the seam keeps them apart and
-    /// lets the app decide each one's wire; folding them together here would bake a wire fact into
-    /// an engine that is supposed to hold none.
+    /// `PetAbandon()` and `PetDismiss()` calls, counted apart though both end at one opcode.
     pub(crate) pet_abandons: u32,
     pub(crate) pet_dismisses: u32,
-    /// Names `PetRename(name)` queued, in order — the `PETRENAMECONFIRM` popup's payload.
+    /// Names `PetRename` queued, from the `PETRENAMECONFIRM` popup.
     pub(crate) pet_renames: Vec<String>,
 
-    /// The per-bag container snapshot (keyed by live-API bag id, 0 = backpack) the app pushes,
-    /// and the `UseContainerItem` intents it drains — the container seam ([`container`]).
+    /// Bag contents by API bag id (0 is the backpack), and the queued `UseContainerItem` calls.
     pub(crate) containers: HashMap<i64, container::ContainerState>,
     pub(crate) container_uses: Vec<(i64, u32)>,
-    /// Per-(bag, slot) use-cooldowns in `GetTime` seconds `(start, duration, enabled)` — stamped
-    /// at `set_container` push time (the action-state pattern), read by
-    /// `GetContainerItemCooldown`.
+    /// Per `(bag, slot)`, `(start, duration, enabled)` in `GetTime` seconds, stamped at push.
     pub(crate) container_cooldowns: HashMap<(i64, u32), (f64, f64, bool)>,
-    /// `HasKey()` — whether the player owns any item of `BagFamily` KEYS, anywhere the reference's
-    /// own search reaches (equipment, bags, backpack, **bank**, keyring). App-resolved like every
-    /// other item fact; the engine holds no item knowledge of its own. Gates the whole keyring UI
-    /// (decision 0765).
+    /// `HasKey()`: a keys-family item in equipment, bags, bank or keyring; gates the keyring UI.
     pub(crate) has_key: bool,
-    /// What the cursor carries (`PickupContainerItem`/`SplitContainerItem`/… set it; `None` =
-    /// empty cursor) — the real client's transient drag state, typed by payload arm
-    /// ([`cursor::CursorPayload`], decision 0216). Purely visual + intent-routing: no item moves
-    /// locally, the server's field updates settle the bag ([`container`]). The app draws the
-    /// held icon at the mouse and reads `None`/`Some` to show/hide it.
+    /// What the cursor carries; nothing moves locally, the server's updates settle the bags.
     pub(crate) cursor: Option<cursor::CursorPayload>,
-    /// Mirrors "is `cursor` currently `Some`" across transitions — [`cursor::queue_cursor_update`]
-    /// compares it against the live state on every call to derive `ACTIONBAR_SHOWGRID`/
-    /// `ACTIONBAR_HIDEGRID` (decision 0216 §7): fires exactly on a None↔Some edge, any payload
-    /// arm, any surface (bags/doll/actions alike — the reference's own "any placeable payload
-    /// shows the bar's drop grid"). A Some→Some transition (the action hop) updates nothing here,
-    /// so no spurious HIDE+SHOW churns out of one gesture.
-    ///
-    /// The **pet** payload arm is excluded (decision 1010): `PlaceAction` refuses it, so lighting
-    /// the action bar's empty slots for a payload that cannot land there would be an invitation to
-    /// a no-op. It drives [`Self::pet_grid_shown`] instead.
+    /// The action bar's drop grid: shown on the cursor's empty-to-held edge for any payload but a
+    /// pet action or a vendor row (mode 5; the grab setter `0x4950f0` shows it for mode 7 only).
     pub(crate) cursor_grid_shown: bool,
-    /// The same mirror for the PET bar's grid — `PET_BAR_SHOWGRID`/`PET_BAR_HIDEGRID`, which the
-    /// reference fires from inside the pet-action pickup builder itself (`0x494f28`) rather than
-    /// from a shared cursor transition. So the two grids are disjoint: a spell lights the action
-    /// bar's, a pet action lights the pet bar's, and neither lights both.
+    /// The pet bar's grid, lit only by a pet-action pickup (`0x494f28`); never both grids at once.
     pub(crate) pet_grid_shown: bool,
-    /// The app's world pick under the cursor — the reference's click-time pick state
-    /// (`[this+0x350]`: nothing / terrain / object), fed once per frame
-    /// ([`super::UiScript::set_world_pick`]; stays `Nothing` in tests/captures). Routes
-    /// [`cursor::world_drop_click`]'s legs (decisions 0571 + 0574): an `Object` pick drops no
-    /// payload at all, `Terrain` drops items only (a spell/action survives the ground click),
-    /// `Nothing` drops any arm.
+    /// The world pick under the cursor (`[this+0x350]`): a world click drops no payload on an
+    /// object, only an item on terrain, and anything over nothing.
     pub(crate) world_pick: cursor::WorldPick,
-    /// Backpack pick/place/swap intents queued by `PickupContainerItem`/`SplitContainerItem` when
-    /// the cursor was holding (src bag/slot → dst bag/slot, live-API space, optional split count),
-    /// drained by the app into `CMSG_SWAP_INV_ITEM`/`CMSG_SPLIT_ITEM`.
+    /// Held-item bag moves, sent as `CMSG_SWAP_INV_ITEM` or `CMSG_SPLIT_ITEM`.
     pub(crate) container_moves: Vec<container::ContainerMove>,
-    /// Repair-mode clicks the pickup intercept queued (`(bag, slot)`; [`container`]).
+    /// `(bag, slot)` clicks made in repair mode.
     pub(crate) container_repairs: Vec<(i64, u32)>,
-    /// The targeting cursor's **item** half is up (`TargetingWantsItem 0x6e6330`, decision 0923;
-    /// first built for the CraftFrame enchant pick, 0437 phase 3): while set, a bag OR paper-doll
-    /// click queues into [`Self::item_picks`] instead of running the cursor gesture.
+    /// Targeting wants an item (`0x6e6330`): a bag or paper-doll click becomes a pick.
     pub(crate) item_pick_armed: bool,
-    /// `(bag, slot)` clicks consumed by the armed item pick, drained by the app. A doll click
-    /// reports as [`super::EQUIPMENT_BAG`] + its 1-based inventory slot, so both seams speak the
-    /// one bag space the drain already resolves.
+    /// Picked `(bag, slot)`s; a paper-doll click is `EQUIPMENT_BAG` and its 1-based inventory slot.
     pub(crate) item_picks: Vec<(i64, u32)>,
-    /// `BindEnchant()`/`ReplaceEnchant()` — the two enchant-confirm popups' answers to a pick the
-    /// app already parked, drained by it (decision 0928; [`cursor::EnchantConfirm`]).
+    /// `BindEnchant()` and `ReplaceEnchant()`, the enchant popups' answers.
     pub(crate) enchant_confirms: Vec<cursor::EnchantConfirm>,
-    /// `(bag, slot, count)` triples queued by `DeleteCursorItem` (`count == 0` = the whole
-    /// stack) — the popup-confirmed destroy (decision 0216 §3), drained by the app into
-    /// `CMSG_DESTROYITEM`.
+    /// `DeleteCursorItem`'s `(bag, slot, count)`, 0 for the whole stack, as `CMSG_DESTROYITEM`.
     pub(crate) container_destroys: Vec<(i64, u32, u32)>,
-    /// **The armed gift wrap** — the `(bag, slot)` of a piece of wrapping paper whose right-click
-    /// took the reference's begin-wrap arm (`0x5edea0`: lock the paper, cursor mode 2, no packet).
-    /// `None` = nothing armed, which is nearly always. Decision 1934.
-    ///
-    /// Deliberately **not** a [`cursor::CursorPayload`]: the reference writes no payload global at
-    /// all here, only the displayed-cursor mode, so `CursorHasItem()` stays nil and none of the
-    /// thirteen stock `CursorHasItem()` gates open. Making it a payload would silently open every
-    /// one of them — the same trap decision 1677's mode-5 note names for the vendor cursor.
+    /// The wrapping paper a right-click armed (`0x5edea0`: lock it, cursor mode 2, no packet). Not
+    /// a cursor payload: the reference sets only the cursor mode, so `CursorHasItem()` stays nil.
     pub(crate) pending_wrap: Option<container::PendingWrap>,
-    /// `(giftBag, giftSlot, itemBag, itemSlot)` quads a completed wrap queued, drained by the app
-    /// into `CMSG_WRAP_ITEM`. The paper's pair leads, as the wire does.
+    /// `(giftBag, giftSlot, itemBag, itemSlot)` per completed wrap, in `CMSG_WRAP_ITEM`'s order.
     pub(crate) container_wraps: Vec<(i64, u32, i64, u32)>,
-    /// The Lua-set **displayed-cursor override** (`ShowContainerSellCursor`/`ShowMerchantSellCursor`/
-    /// `ShowBuybackSellCursor`/`ShowInspectCursor` set it, `ResetCursor` clears it; [`container`] +
-    /// [`merchant`]) — the single "displayed mode" the real client keeps at `0xbe2c2c`, restored to
-    /// the base (world-classifier) mode by `ResetCursor`. `None` = no override (show the base mode).
+    /// The cursor mode Lua set (`0xbe2c2c`); `ResetCursor` returns it to the world's mode.
     pub(crate) ui_cursor: Option<container::UiCursorMode>,
-    /// Set by every FrameXML cursor call — `Show*SellCursor` / `ShowInspectCursor` / `SetCursor` /
-    /// `ResetCursor` — and drained by the app each frame ([`UiScript::take_cursor_write`]).
-    ///
-    /// **The cursor mode is a WRITE, not a level** (decision 1061), and that distinction is the
-    /// whole of B208's regression. The reference keeps one sticky global (`0xbe2c2c`): the world
-    /// classifier writes it while the pointer is over the world, FrameXML writes it from a hover
-    /// handler, and in between **nothing** writes it — so the last value simply stands. Reading
-    /// `ui_cursor` as a level made "no override" mean "show the base", which turned every UI
-    /// element with no cursor handler at all (a spellbook button, a panel) into a forced Point and
-    /// killed the armed cast cursor the moment the mouse left the world.
+    /// A FrameXML cursor call ran. The mode is a write, not a level: `0xbe2c2c` keeps its value
+    /// until the world or a hover handler writes it, so a handler-less frame leaves it be.
     pub(crate) ui_cursor_dirty: bool,
-    /// `(bag, slot)` sources queued by `AutoEquipCursorItem` (decision 0208 phase 1b, `cursor`'s
-    /// `doll` submodule) — drained by the app into `CMSG_AUTOEQUIP_ITEM`.
+    /// `AutoEquipCursorItem`'s `(bag, slot)` sources, sent as `CMSG_AUTOEQUIP_ITEM`.
     pub(crate) container_autoequips: Vec<(i64, u32)>,
-    /// Auto-stores queued by `PutItemInBag`/`PutItemInBackpack` (`cursor`'s `bag_verbs` submodule) —
-    /// drained by the app into `CMSG_AUTOSTORE_BAG_ITEM` (or `CMSG_SPLIT_ITEM` for a split carry).
+    /// `PutItemInBag` and `PutItemInBackpack` stores, sent as `CMSG_AUTOSTORE_BAG_ITEM`, or
+    /// `CMSG_SPLIT_ITEM` for a split stack.
     pub(crate) bag_autostores: Vec<container::BagAutoStore>,
 
-    /// Per-frame drag-button registrations (`RegisterForDrag`) — kind-independent (any Frame, not
-    /// just a Button), so it lives beside [`Model::mouse_down_on`] rather than inside a per-kind
-    /// state. Verbatim button-name sets (`"LeftButton"`, …); [`UiScript::mouse_button`]/
-    /// [`UiScript::mouse_move`] compare case-insensitively (RF's `RegisterForClicks` precedent).
-    /// Same destroy-cleanup status as [`Model::scripts`]/[`Model::frame_events`]: nothing in this
-    /// engine destroys a frame yet (no Lua `Destroy`, no call to `WidgetArena::destroy` outside
-    /// its own tests), so none of the three is pruned today — a future destroy path must prune
-    /// all three together.
+    /// `RegisterForDrag` buttons per frame, compared case-insensitively. Nothing destroys a frame,
+    /// so this, `scripts` and `frame_events` are never pruned; a destroy path must prune all three.
     pub(crate) drag_registered: HashMap<FrameHandle, HashSet<String>>,
-    /// The in-flight drag gesture: armed at mouse-down on a [`Model::drag_registered`] frame,
-    /// `started` once the cursor has moved past the drag-start threshold — `None` between
-    /// gestures ([`cursor::DragGesture`], decision 0216 §3).
+    /// The drag gesture, armed by a press on a drag-registered frame, started past the threshold.
     pub(crate) drag: Option<cursor::DragGesture>,
-    /// The one in-flight `StartMoving()` — the client's single root-side drag slot (`root+0xcfc`
-    /// and the cursor sample beside it), `None` between moves ([`super::object::FrameMove`]). Held
-    /// beside [`Model::drag`] because that gesture is what normally opens and closes it: the
-    /// canonical addon idiom is `OnDragStart → StartMoving`, `OnDragStop → StopMovingOrSizing`.
-    /// The two remain separate systems, exactly as in the reference — a drag can carry a payload
-    /// with nothing moving, and a move outlives the mouse button (the reference's mouse-up
-    /// auto-stop skips the Lua drag type).
+    /// The one `StartMoving()` in flight, the client's `root+0xcfc` slot, apart from `drag` as in
+    /// the reference: a move outlives the button, since mouse-up's auto-stop skips a Lua drag.
     pub(crate) moving: Option<super::object::FrameMove>,
-    /// The in-flight `StartSizing` drag — the resize twin of [`Self::moving`], cleared by the same
-    /// `StopMovingOrSizing` (`0x776990`).
+    /// The `StartSizing` in flight, cleared by `StopMovingOrSizing` (`0x776990`).
     pub(crate) sizing: Option<super::object::FrameSizing>,
-    /// The in-flight Slider thumb drag: set when a LeftButton press lands on a Slider's thumb, held
-    /// until release / pointer-leave (decision 0250 §5, the engine's C++-equivalent thumb drag —
-    /// like a scrollbar dragging in the real client, no Lua involved). `None` between drags
-    /// ([`slider::SliderDrag`]).
+    /// A Slider thumb drag, left press to release or pointer leave, handled here with no Lua.
     pub(crate) slider_drag: Option<slider::SliderDrag>,
-    /// The in-flight ColorSelect drag — the colour picker's wheel/value-strip twin of
-    /// [`Self::slider_drag`], held from press to release. The widget keeps two independent capture
-    /// flags rather than one target ([`colorselect::ColorDrag`]).
+    /// A ColorSelect wheel or value-bar drag, press to release.
     pub(crate) color_drag: Option<colorselect::ColorDrag>,
 
-    /// The open gossip menu the app pushes (`None` = no menu), the `SelectGossipOption` intents it
-    /// drains, and whether `CloseGossip` was called — the gossip seam ([`gossip`]).
+    /// The open gossip menu, the `SelectGossipOption` calls and whether `CloseGossip` ran.
     pub(crate) gossip: Option<gossip::GossipMenu>,
     pub(crate) gossip_selects: Vec<u32>,
     pub(crate) gossip_close: bool,
-    /// 1-based quest-row selects queued by `SelectGossipQuest` (decision 0088) — the app maps each
-    /// to the row's quest id and sends `CMSG_QUESTGIVER_QUERY_QUEST`.
+    /// `SelectGossipQuest` 1-based rows, each sent as `CMSG_QUESTGIVER_QUERY_QUEST` for its quest.
     pub(crate) gossip_quest_selects: Vec<u32>,
 
-    /// The open merchant's stock snapshot the app pushes (`None` = no vendor open), the
-    /// `BuyMerchantItem` intents it drains, and whether `CloseMerchant` was called — the merchant
-    /// seam ([`merchant`]).
+    /// The open vendor's stock, the `BuyMerchantItem` calls and whether `CloseMerchant` ran.
     pub(crate) merchant: Option<merchant::MerchantState>,
     pub(crate) merchant_buys: Vec<(u32, u32)>,
-    /// `PickupMerchantItem`'s SELL arm — the `(bag, slot)` the cursor was holding when it was
-    /// called over the vendor window. The app resolves the guid and sends `CMSG_SELL_ITEM`.
+    /// The held `(bag, slot)` when `PickupMerchantItem` sells, sent as `CMSG_SELL_ITEM`.
     pub(crate) merchant_cursor_sells: Vec<(i64, u32)>,
-    /// A held vendor row dropped into a bag — `(bag, slot, item entry)`, the app's
-    /// `CMSG_BUY_ITEM_IN_SLOT`.
+    /// A held vendor row dropped in a bag, `(bag, slot, item entry)`, for `CMSG_BUY_ITEM_IN_SLOT`.
     pub(crate) merchant_slot_buys: Vec<(i64, u32, u32)>,
     pub(crate) merchant_close: bool,
-    /// `BuybackItem` intents (1-based buyback slots), the `RepairAllItems` flag, and the
-    /// client-side repair-mode latch (`ShowRepairCursor`/`InRepairMode`) — the rest of the
-    /// merchant seam.
+    /// `BuybackItem` 1-based slots, the `RepairAllItems` flag and repair mode (`InRepairMode`).
     pub(crate) merchant_buybacks: Vec<u32>,
     pub(crate) repair_all: bool,
     pub(crate) repair_mode: bool,
 
-    /// The stable window's whole state — the pushed snapshot, the selection, the frame-local
-    /// drag, and the queued verbs (the stable seam, [`stable`], decision 1676). One sub-struct
-    /// rather than five loose fields because the close path resets several of them together.
+    /// The stable window: snapshot, selection, drag and queued calls, reset together on close.
     pub(crate) stable: stable::StableModel,
 
-    /// The open bank's purchase-row snapshot the app pushes (`None` = no bank open), the
-    /// `PurchaseSlot` intent, and whether `CloseBankFrame` was called — the bank seam ([`bank`],
-    /// decision 0604; the bank's *contents* ride the container seam as bags −1/5..=10).
+    /// The open bank's slot-purchase row and calls; its contents are bags -1 and 5..=10.
     pub(crate) bank: Option<bank::BankState>,
     pub(crate) bank_purchase: bool,
     pub(crate) bank_close: bool,
 
-    /// The open trainer's service snapshot the app pushes (`None` = no trainer open), the
-    /// `BuyTrainerService` intents it drains, the engine-held selection, and whether `CloseTrainer`
-    /// was called — the trainer seam ([`trainer`], decision 0237).
-    ///
-    /// The selection is the selected service's **spell id**, not its row number. A row number is a
-    /// coordinate in a list that three independent things move under it — the state filter, a
-    /// collapse, and a re-list — and `GetTrainerSelectionIndex` answering with a stale-but-in-range
-    /// one is what left the detail pane describing a spell that had already left the window.
+    /// The open trainer, its buys, selection and close. The selection is a spell id, since
+    /// filters, collapses and re-lists all move row numbers.
     pub(crate) trainer: Option<trainer::TrainerState>,
     pub(crate) trainer_buys: Vec<u32>,
     pub(crate) trainer_selection: Option<u32>,
     pub(crate) trainer_close: bool,
-    /// The three state filters (available / unavailable / used) — the real client hides filtered
-    /// service rows itself ([`trainer`]); all shown by default. A state filter hides *services*, never
-    /// headers (decision 0247).
+    /// Available, unavailable and used filters, all on by default; they hide services, not headers.
     pub(crate) trainer_filter: [bool; 3],
-    /// The skill lines the player has collapsed in the tree — their services hide, the header stays
-    /// (decision 0247). Keyed by skill-line id so it survives a content update (`set_trainer` keeps
-    /// only still-present lines); cleared when the trainer closes.
+    /// Collapsed skill-line ids, kept across a re-push and cleared when the trainer closes.
     pub(crate) trainer_collapsed: HashSet<u32>,
 
-    /// The open taxi map's snapshot the app pushes (`None` = closed), the `TakeTaxiNode` intents
-    /// it drains, whether `CloseTaxiMap` was called, and whether our own player is riding a
-    /// taxi — the taxi seam ([`taxi`], decision 0484).
+    /// The open taxi map, the `TakeTaxiNode` calls, whether `CloseTaxiMap` ran and whether we ride.
     pub(crate) taxi: Option<taxi::TaxiUiState>,
     pub(crate) taxi_takes: Vec<usize>,
     pub(crate) taxi_close: bool,
     pub(crate) taxi_riding: bool,
 
-    /// The open tradeskill window's recipe snapshot the app pushes (`None` = no window open) — the
-    /// tradeskill seam ([`tradeskill`], decision 0437 phase 2).
+    /// The open tradeskill window's recipes.
     pub(crate) trade_skill: Option<tradeskill::TradeSkillState>,
-    /// `(spell id, count)` intents `DoTradeSkill` queued since the app's last
-    /// [`super::UiScript::take_trade_skill_dos`] drain.
+    /// `DoTradeSkill` calls, `(spell id, count)`.
     pub(crate) trade_skill_dos: Vec<(u32, u32)>,
-    /// The engine-held 1-based selection (0 = none), preserved across a `set_trade_skill` re-push by
-    /// the recipe's spell id (see [`super::UiScript::set_trade_skill`]).
+    /// The 1-based selection, 0 for none, carried across a re-push by the recipe's spell id.
     pub(crate) trade_skill_selection: u32,
-    /// Whether `CloseTradeSkill` was called since the app's last
-    /// [`super::UiScript::take_trade_skill_close`] drain.
     pub(crate) trade_skill_close: bool,
-    /// The recipe groups the player has collapsed, by group key `(ItemClass, ItemSubClass)`
-    /// (wow-re `tradeskill` TU-B) — a group's recipes hide, its header stays (the
-    /// trainer/skills-pane precedent, [`Model::trainer_collapsed`]/[`Model::skills_collapsed`]).
-    /// Survives a `set_trade_skill` content re-push (pruned to the groups the fresh recipes still
-    /// produce) AND a same-profession close→reopen (wow-re `tradeskill` TU-G §6 — the collapse
-    /// mask `0x84dd68` round-trips the rebuild by header key); reset on a profession switch
-    /// ([`Model::trade_skill_last_line`]).
+    /// Collapsed recipe groups by `(ItemClass, ItemSubClass)` (`0x55ba30`), kept across a re-push
+    /// and a same-profession reopen like the mask `0x84dd68`; a profession switch resets them.
     pub(crate) trade_skill_collapsed: HashSet<(u32, u32)>,
-    /// Group keys the SubClass filter dropdown has hidden (empty = "All Subclasses"). Keyed like
-    /// [`Model::trade_skill_collapsed`] — the real client's per-header shown flag (`header+0xc`)
-    /// survives a rebuild by exactly this `(ItemClass, ItemSubClass)` key match (`0x4fca20`'s
-    /// save→restore loop; the position mask `0x84dd60` is the derived form — wow-re `tradeskill`
-    /// TU-G). Persists across a same-profession close/reopen; reset on a profession switch
-    /// ([`Model::trade_skill_last_line`]).
+    /// Groups the SubClass filter hides, empty for all, kept by key like the client's header flag
+    /// (`header+0xc`, `0x4fca20`, mask `0x84dd60`); a profession switch resets them.
     pub(crate) trade_skill_subclass_hidden: HashSet<(u32, u32)>,
-    /// The InvSlot filter mask (`0x84dd64`, wow-re `tradeskill` TU-G): **bit set = slot shown**,
-    /// all-ones = "All Slots". The real client's build never touches this static — it is NOT
-    /// pruned on a re-push, and an exclusive pick therefore keeps every OTHER bit clear even for
-    /// slots that appear later. Reset (all-ones) only on a profession switch.
+    /// The InvSlot filter mask (`0x84dd64`), a set bit shown and all ones for all slots. Never
+    /// pruned on a re-push, as in the client, so a later slot stays hidden; a switch resets it.
     pub(crate) trade_skill_invslot_mask: u32,
-    /// The skill line the tradeskill state was last built for (`0xbde064`, wow-re TU-G's cache
-    /// key): a `set_trade_skill` push for a DIFFERENT line resets the two filters, the collapse
-    /// set, and the selection; the same line (including a close→reopen round trip) keeps them.
+    /// The skill line the state was last built for (`0xbde064`): a push for another line resets
+    /// the filters, collapses and selection; the same line keeps them, even across a reopen.
     pub(crate) trade_skill_last_line: u32,
-    /// The selected recipe's SPELL ID (`0xbde044` — the real client stores the selection by spell
-    /// id, not index), shadowing [`Model::trade_skill_selection`]'s flat position so the selection
-    /// survives a same-profession close→reopen (TU-G: untouched on that path) and remaps across a
-    /// re-push.
+    /// The selected recipe's spell id (`0xbde044`), which carries it across reopen and re-push.
     pub(crate) trade_skill_selected_spell: u32,
-    /// Set by the engine-side mutators the real client answers with a `TRADE_SKILL_UPDATE` event
-    /// from inside the C call (`Set*Filter`/`Expand/CollapseTradeSkillSubClass` → the
-    /// `0x4fd710`/`0x4fd730`/`0x4fd750` writer trio → recompute+resort `0x4fd180` + event
-    /// **0x13a**); the app drains it ([`super::UiScript::take_trade_skill_touched`]) and fires
-    /// the event the same frame.
+    /// A filter or subclass collapse changed: `TRADE_SKILL_UPDATE` (`0x13a`) is owed this frame, as
+    /// the client fires it inside the call (`0x4fd710`/`0x4fd730`/`0x4fd750`, `0x4fd180`).
     pub(crate) trade_skill_touched: bool,
 
-    /// The open craft window's recipe snapshot the app pushes (`None` = no window open) — the craft
-    /// seam ([`craft`], decision 0437 phase 3), TradeSkill's exact twin.
+    /// The open craft window's recipes.
     pub(crate) craft: Option<craft::CraftState>,
-    /// Spell id intents `DoCraft` queued since the app's last [`super::UiScript::take_craft_dos`]
-    /// drain — no count (the 1.12 CraftFrame has no Create All, unlike `trade_skill_dos`).
+    /// `DoCraft` spell ids; no count, as the 1.12 CraftFrame has no Create All.
     pub(crate) craft_dos: Vec<u32>,
-    /// The engine-held 1-based selection (0 = none), preserved across a `set_craft` re-push by the
-    /// recipe's spell id (see [`super::UiScript::set_craft`]).
+    /// The 1-based selection, 0 for none, carried across a re-push by the recipe's spell id.
     pub(crate) craft_selection: u32,
-    /// Whether `CloseCraft` was called since the app's last [`super::UiScript::take_craft_close`]
-    /// drain.
     pub(crate) craft_close: bool,
 
-    /// The `EquipPendingItem`/`CancelPendingEquip` answers the app drains, in call order, and the
-    /// `ConfirmBindOnUse()` count — the non-loot soulbind confirmations' whole Lua side
-    /// ([`bind_confirm`], decision 1750). The pending records themselves are the app's.
+    /// `EquipPendingItem`/`CancelPendingEquip` answers in order, and `ConfirmBindOnUse()` calls.
     pub(crate) pending_equip_answers: Vec<bind_confirm::PendingEquipAnswer>,
     pub(crate) bind_on_use_confirms: u32,
 
-    /// The open loot's row snapshot the app pushes (`None` = no loot open), the row-pick intents it
-    /// drains, and whether `CloseLoot` was called — the loot seam ([`loot`]).
-    ///
-    /// **The picks come in two flavours, and the flavour is load-bearing** (decision 1744): the
-    /// reference's take dispatcher `0x4c2790(slot, flag)` is one function with two entries, and the
-    /// flag decides whether a bind-on-pickup row raises the LOOT_BIND confirm or is taken outright.
-    /// `flag == 0` is the row click, which in 1.12 is the C `CLootButton`'s own behaviour and here
-    /// is `BenillaTakeLootSlot`; `flag != 0` is the confirm continuation, which is the ONLY thing
-    /// the 1.12 Lua binding `LootSlot` does (`0x4c2e70` passes `edx = 1`, and its sole FrameXML
-    /// caller is `StaticPopupDialogs["LOOT_BIND"].OnAccept`).
+    /// The open loot, the row clicks and whether `CloseLoot` ran. A click is the reference's take
+    /// `0x4c2790` with flag 0, raising `LOOT_BIND` for a bind-on-pickup row (the C `CLootButton`,
+    /// here `BenillaTakeLootSlot`); `LootSlot` passes 1 (`0x4c2e70`), taking it after the confirm.
     pub(crate) loot: Option<loot::LootState>,
     pub(crate) loot_picks: Vec<u32>,
-    /// The `LootSlot(slot)` confirm continuations — 1-based display rows, drained separately from
-    /// [`Self::loot_picks`] so the app can honour the reference's pending-slot gate.
+    /// `LootSlot(slot)` rows, 1-based, apart from clicks for the reference's pending-slot gate.
     pub(crate) loot_confirms: Vec<u32>,
     pub(crate) loot_close: bool,
-    /// The `GiveMasterLoot(slot, candidateIndex)` assignments the app drains — both 1-based and
-    /// both display-side: the row as the window numbers it, and the candidate's position in
-    /// [`loot::LootState::master_candidates`]. The app owns the translation to the wire slot and
-    /// the recipient's guid (decision 1675).
+    /// `GiveMasterLoot(slot, candidateIndex)`, both 1-based display positions the app translates.
     pub(crate) loot_master_gives: Vec<(u32, u32)>,
 
-    /// The open group-loot rolls the app pushes (empty = none open) and the `RollOnLoot`
-    /// `(roll_id, roll_type)` votes it drains — the roll seam ([`loot_roll`], decision 0591).
+    /// The open group-loot rolls, and the `RollOnLoot` `(roll_id, roll_type)` votes.
     pub(crate) loot_rolls: loot_roll::LootRollsState,
     pub(crate) loot_roll_votes: Vec<(u32, u8)>,
-    /// Need/Greed on a **bind-on-pickup** roll: not a vote but a request for the
-    /// `CONFIRM_LOOT_ROLL` popup, which `ConfirmLootRoll` then re-enters past the gate
-    /// (decision 0594's binary correction).
+    /// Need or Greed on a bind-on-pickup roll: a `CONFIRM_LOOT_ROLL` popup ask, not a vote.
     pub(crate) loot_roll_confirms: Vec<(u32, u8)>,
 
-    /// The open mailbox's inbox snapshot the app pushes (`None` = no mailbox open) and the intents
-    /// the app drains — the mail seam ([`mail`], decision 0544). `mail_opens` are the 1-based rows
-    /// `GetInboxText` touched (the app marks each read + ask-once fetches its body); the take/delete/
-    /// return vecs are 1-based row picks; `mail_send` is the pending `SendMail(target,subject,body)`
-    /// the app folds `mail_send_money`/`mail_send_cod`/`mail_send_item` into at drain.
-    /// The item-text reader session ([`item_text`]): the pushed snapshot + the close/page-turn
-    /// intents the app drains.
+    /// The item-text reader: the pushed page, then the close and page-turn calls.
     pub(crate) item_text: Option<item_text::ItemTextState>,
     pub(crate) item_text_close: bool,
     pub(crate) item_text_page_turns: Vec<i32>,
+    /// The open inbox and mail calls, rows 1-based: `mail_opens` are rows `GetInboxText` read.
     pub(crate) mail: Option<mail::MailState>,
     pub(crate) mail_check_inbox: bool,
     pub(crate) mail_opens: Vec<u32>,
@@ -1364,30 +703,19 @@ pub(crate) struct Model {
     pub(crate) mail_send: Option<(String, String, String)>,
     pub(crate) mail_send_money: u32,
     pub(crate) mail_send_cod: u32,
-    /// The Send tab's attached bag item (a cursor drop, decision 0216) — carried until the send
-    /// fires; the app resolves its `(bag, slot)` to the wire item guid then.
+    /// The Send tab's attached item, resolved to its guid when the send fires.
     pub(crate) mail_send_item: Option<cursor::CursorItem>,
-    /// The usable stationery list the app pushes, in the picker's order (1970).
+    /// The usable stationery, in the picker's order.
     pub(crate) mail_stationeries: Vec<mail::StationeryView>,
-    /// `SelectStationery`'s stored `Stationery.dbc` id — 0 = none, which silences `SendMail`.
+    /// `SelectStationery`'s `Stationery.dbc` id; 0 is none, which silences `SendMail`.
     pub(crate) mail_stationery: u32,
-    /// `HasNewMail()` — login-scoped (survives the mailbox window closing, unlike [`Self::mail`]
-    /// above): the app's `MSG_QUERY_NEXT_MAIL_TIME`/`SMSG_RECEIVED_MAIL`-fed countdown reduced to
-    /// one flag (decision 0544 P3, wow-re §5 `mail-interaction.md`). The reference minimap icon
-    /// (`MiniMapMailFrame`) reads this on `UPDATE_PENDING_MAIL`.
+    /// `HasNewMail()` (`0x4afea0`), from `MSG_QUERY_NEXT_MAIL_TIME` and `SMSG_RECEIVED_MAIL`.
     pub(crate) has_new_mail: bool,
 
-    /// The open auction house's snapshot the app pushes (`None` = no auctioneer session) and the
-    /// intents the app drains — the auction seam ([`auction`], decision 1511). `auction_selected`
-    /// is engine-local per list ([`auction::LIST`]/`BIDDER`/`OWNER`) and holds the selected
-    /// **auction id**, not a row position (wow-re §5 TU-5): an id follows its row through a
-    /// re-sort, where an index would quietly come to mean the auction that took its place. `0` =
-    /// nothing selected. It is engine-local because the reference reads the selection back
-    /// synchronously inside the same handler that sets it, so it cannot be a round trip. `auction_can_query` is the app's 5 s browse
-    /// throttle, pushed separately from the snapshot because the Search button polls it every
-    /// frame and it would otherwise churn the snapshot's diff.
+    /// The open auction house and the auction calls. `auction_selected` is each list's selected
+    /// auction id, 0 for none (`0x4cfda0`/`0x4cfec0`); `auction_can_query` is the 5 s throttle.
     pub(crate) auction: Option<auction::AuctionState>,
-    /// The Browse tab's class tree, login-scoped (`set_auction_item_classes`, 1971).
+    /// The Browse tab's class tree, pushed once per login.
     pub(crate) auction_item_classes: Vec<auction::AuctionCategory>,
     pub(crate) auction_selected: [u32; 3],
     pub(crate) auction_can_query: bool,
@@ -1399,410 +727,214 @@ pub(crate) struct Model {
     pub(crate) auction_start: Option<auction::AuctionStartRequest>,
     pub(crate) auction_sorts: Vec<(usize, String)>,
     pub(crate) auction_close: bool,
-    /// The sell slot's staged item (a cursor drop, decision 0216) — carried until `StartAuction`
-    /// fires, when the app resolves its `(bag, slot)` to the wire item guid.
+    /// The sell slot's item, resolved to its guid when `StartAuction` fires.
     pub(crate) auction_sell_item: Option<cursor::CursorItem>,
 
-    /// The open trade window's snapshot the app pushes (`None` = no trade open) and the intents the
-    /// app drains — the trade seam ([`trade`], decision 0592 P1). `trade_initiates` are the unit
-    /// tokens `InitiateTrade` queued (the app resolves each → guid → `CMSG_INITIATE_TRADE`); the
-    /// three flags are the accept / un-accept / cancel verbs (`CMSG_ACCEPT_TRADE` /
-    /// `CMSG_UNACCEPT_TRADE` / `CMSG_CANCEL_TRADE`). `trade_set_money` is the copper `SetTradeMoney`
-    /// offered (→ `CMSG_SET_TRADE_GOLD`, decision 0592 P2).
+    /// The open trade and its calls: `InitiateTrade` tokens, the accept, unaccept and cancel flags,
+    /// and `SetTradeMoney` copper (`CMSG_SET_TRADE_GOLD`).
     pub(crate) trade: Option<trade::TradeState>,
     pub(crate) trade_initiates: Vec<String>,
     pub(crate) trade_accept: bool,
     pub(crate) trade_unaccept: bool,
     pub(crate) trade_close: bool,
-    /// `BeginTrade()` / `CancelTrade()` since the last drain (decision 1963).
+    /// `BeginTrade()` and `CancelTrade()` calls.
     pub(crate) trade_begin: bool,
     pub(crate) trade_cancel: bool,
     pub(crate) trade_set_money: Option<u32>,
-    /// Cursor-drop placements onto our trade slots: `(trade_id 1-based, bag, slot)` → the app resolves
-    /// `(bag, slot)` → wire position → `CMSG_SET_TRADE_ITEM`. `trade_clear_items` are the 1-based ids
-    /// an empty-cursor click cleared (→ `CMSG_CLEAR_TRADE_ITEM`). Decision 0592 P2.
+    /// Items dropped on our slots, `(1-based trade slot, bag, slot)`, and the slots clicks cleared.
     pub(crate) trade_set_items: Vec<(u32, i64, u32)>,
     pub(crate) trade_clear_items: Vec<u32>,
 
-    /// The open questgiver panel the app pushes (`None` = no window), the greeting-row selects and
-    /// the button intents it drains — the questgiver seam ([`quest`]).
+    /// The open questgiver panel, its greeting-row selects and its button calls.
     pub(crate) quest: Option<quest::QuestState>,
     pub(crate) quest_selects: Vec<quest::QuestSelect>,
     pub(crate) quest_actions: Vec<quest::QuestAction>,
 
-    /// The death-arc seam ([`death`], decision 0308): the snapshot the app pushes (countdowns +
-    /// offer bits) and the drained release/reclaim/resurrect intents.
+    /// Death countdowns and offers, and the release, reclaim and resurrect calls.
     pub(crate) death: death::DeathUiState,
     pub(crate) death_actions: Vec<death::DeathAction>,
 
-    /// The quest-log seam ([`quest_log`]): the snapshot the app pushes, the engine-owned
-    /// synchronous selection + click-time abandon mark (1-based entry indices, `0` = none), and
-    /// the drained abandon intents.
+    /// The quest log, selection (1-based), abandon mark (a quest id, `0xbb7484`) and abandons.
     pub(crate) quest_log: quest_log::QuestLogState,
     pub(crate) quest_log_selection: u32,
     pub(crate) quest_log_abandon_mark: u32,
     pub(crate) quest_log_abandons: Vec<u32>,
-    /// Quest ids `QuestLogPushQuest()` queued for the app to push to the party (decision 1733).
-    /// **Ids, not entry indices** — unlike the abandon mark above, whose two-step confirm is the
-    /// whole reason it pins an index: a push is one click, so the id is resolved right then and a
-    /// log shuffle between click and drain cannot retarget it.
+    /// `QuestLogPushQuest()` quest ids, resolved at the click so a log change cannot retarget one.
     pub(crate) quest_log_pushes: Vec<u32>,
-    /// How many times `ConfirmAcceptQuest()` was called — the escort confirm's Yes. A counter, not
-    /// a quest id: the reference's verb takes no argument and answers whatever confirm the client
-    /// is holding, so the id lives app-side with the pending confirm (decision 1733).
+    /// `ConfirmAcceptQuest()` calls, the escort confirm; the app holds the pending quest.
     pub(crate) quest_confirms: u32,
-    /// The shared item-template store: `item id → full tooltip view` ([`item_stats`] module doc,
-    /// decision 0274 P1).
+    /// Item id to its tooltip view.
     pub(crate) item_templates: HashMap<u32, ItemTemplateView>,
-    /// Item ids the renderer asked for that the store lacks — drained by the app
-    /// ([`UiScript::take_item_stat_asks`]), answered via [`UiScript::set_item_template`].
+    /// Item ids asked for and missing, for the app to answer.
     pub(crate) item_stat_asks: HashSet<u32>,
-    /// The item-set store (`set id → §22 SET-block view`) + its ask-once misses — the same
-    /// push/ask flow as the templates ([`item_stats`] module doc).
+    /// Set id to its tooltip set block (`0x854b1c`), and the misses asked for.
     pub(crate) item_sets: HashMap<u32, super::ItemSetView>,
     pub(crate) item_set_asks: HashSet<u32>,
-    /// The **random-suffix roll** store (`ItemRandomProperties` id → its resolved view) — pushed
-    /// WHOLE at startup, not asked for (decision 1547). It is a static DBC the app has in memory
-    /// from load, and its consumers are click-driven (a chat-link tooltip has no hover re-enter
-    /// loop to repaint on a late answer), so the ask-once shape the template store uses would
-    /// leave a first click showing an item with no lines. This mirrors the reference exactly: the
-    /// builder resolves its `+0x424` against the loaded DBC store `0xc0dbd4` at draw time, and
-    /// every source supplies only the id (wow-re `tooltip-content-law.md` §1-ENCHANT §E5).
+    /// `ItemRandomProperties` id to its view, pushed whole at startup: a clicked tooltip cannot
+    /// repaint on a late answer. The reference reads its loaded store `0xc0dbd4` (`0x52c991`).
     pub(crate) random_properties: HashMap<u32, super::RandomPropertyView>,
-    /// The red-line law's player state (level/class/race/skills — [`item_stats`] module doc).
+    /// The player's level, class, race and skills, for a tooltip's red requirement lines.
     pub(crate) player_req: PlayerReqState,
-    /// The spell-tooltip store: `spell id → resolved view` ([`tooltip_spell`] module doc,
-    /// decision 0274 P2) + the ask-once misses the app drains.
+    /// Spell id to its tooltip view, and the misses asked for.
     pub(crate) spell_tooltips: HashMap<u32, super::SpellTooltipView>,
     pub(crate) spell_tooltip_asks: HashSet<u32>,
-    /// Header collapse/expand intents `(1-based entry index, collapse)` — `CollapseQuestHeader`/
-    /// `ExpandQuestHeader` push, the app drains ([`UiScript::take_quest_log_collapses`]); index 0
-    /// = all headers.
+    /// `CollapseQuestHeader`/`ExpandQuestHeader` as `(1-based entry, collapse)`, entry 0 for all.
     pub(crate) quest_log_collapses: Vec<(u32, bool)>,
-    /// The watched (tracked) quests, by stable quest id in watch order — the tracker HUD's set
-    /// (engine-owned like the selection; pruned by `set_quest_log` when a quest leaves the log).
+    /// Watched quest ids in watch order, pruned when a quest leaves the log.
     pub(crate) quest_log_watched: Vec<u32>,
-    /// The server's wall clock in unix-epoch seconds, pushed by the app each frame it has one
-    /// ([`UiScript::set_server_unix_time`]); `None` before the first `SMSG_QUERY_TIME_RESPONSE`.
-    ///
-    /// Held here rather than folded into the quest-log snapshot because the *engine* owns every
-    /// countdown the Lua reads: a timed quest's deadline is an absolute stamp in this epoch, and
-    /// `GetQuestTimers` subtracts against it **per call**, exactly as the reference's C binding
-    /// does. That is what lets the reference `QuestTimerFrame` tick smoothly from its OnUpdate
-    /// while the log snapshot itself only changes when the log does (decision 1150).
+    /// The server's clock in Unix seconds, `None` before `SMSG_QUERY_TIME_RESPONSE`. A quest
+    /// deadline is a stamp in it, and `GetQuestTimers` subtracts per call, as the reference does.
     pub(crate) server_unix_time: Option<f64>,
-    /// The player's purse in copper (`GetMoney`), pushed each frame it changes by the app's
-    /// `PLAYER_FIELD_COINAGE` feed ([`UiScript::set_money`]). Plain data — the money display + the
-    /// merchant window's coin line read it.
+    /// `GetMoney()` in copper, from `PLAYER_FIELD_COINAGE`.
     pub(crate) money: u64,
 
-    /// The reported connection round trip in ms — `GetNetStats`'s third return, pushed by the app's
-    /// net feed ([`UiScript::set_latency_ms`]). The AVERAGE over the app's RTT ring, not the last
-    /// sample; `0` = nothing measured yet. See [`super::net_stats`].
+    /// `GetNetStats`'s third return, the average round trip in ms; 0 before any sample.
     pub(crate) net_latency_ms: u32,
 
-    /// The player's experience within the current level (`UnitXP("player")`) and the amount required
-    /// to level (`UnitXPMax("player")`), pushed each frame they change by the app's `PLAYER_XP` /
-    /// `PLAYER_NEXT_LEVEL_XP` feed ([`UiScript::set_player_xp`]). A player-level pair (like `money`),
-    /// not a per-unit-token field: PLAYER_XP is a PRIVATE descriptor field, only ever our own avatar's.
+    /// `UnitXP("player")` and `UnitXPMax("player")`, from the private `PLAYER_XP` fields.
     pub(crate) player_xp: u32,
     pub(crate) player_next_level_xp: u32,
 
-    /// The player's banked combo points and the unit they sit on — the raw `PLAYER_FIELD_BYTES`
-    /// byte 1 and `PLAYER_FIELD_COMBO_TARGET` GUID, pushed together each frame either moves
-    /// ([`UiScript::set_combo_points`]). Player-global PRIVATE fields, like `money`.
-    ///
-    /// **Raw wire values, deliberately ungated.** The server banks a point here for a *warrior*
-    /// too (the Overpower window), and the usable walk's leg 5 consumes exactly that. The two
-    /// gates the real `GetComboPoints 0x51a190` applies — rogue-or-druid only, and the banked
-    /// target must be the CURRENT target — live in the binding, where the binary puts them
-    /// (decision 0875). Read [`Self::combo_points`] directly and you are reading the wire, not
-    /// what the reference UI can see.
+    /// Raw combo points (`PLAYER_FIELD_BYTES` byte 1) and target, ungated: a warrior banks them too
+    /// (Overpower); `GetComboPoints` (`0x51a190`) applies the class and current-target gates.
     pub(crate) combo_points: u8,
     pub(crate) combo_target: u64,
 
-    /// The player's rest snapshot, pushed together each frame any part moves
-    /// ([`UiScript::set_rest_state`]) — player-globals like `money`. `rest_state` is the raw
-    /// `PLAYER_BYTES_2` byte 3 (1 = rested, 2 = normal — the server writes it with hysteresis
-    /// off the pool). **Defaults to 2, not 0**: every live 1.12 descriptor carries 2 from
-    /// character creation on, and the tick's faithful FrameXML compares `GetRestState() >= 3`
-    /// unguarded — a pre-feed 0 would render the binary's nil-triple fail path into an event
-    /// handler the real client can only ever run with the byte present. Byte 0 stays reachable
-    /// by explicit push, and the fail path stays faithful there. `rest_pool` is the raw
-    /// `PLAYER_REST_STATE_EXPERIENCE` value in **base kill-XP units**, `resting` the
-    /// `PLAYER_FLAGS_RESTING (0x20)` bit (inside an inn/city). `GetRestState`/`GetXPExhaustion`/
-    /// `IsResting` read these; the pool's display scaling is `exhaustion` row 1's factor,
-    /// applied in the `GetXPExhaustion` binding, where the real client applies it (decisions
-    /// 1082/1087).
+    /// `PLAYER_BYTES_2` byte 3 (1 rested, 2 normal), defaulting to 2 as every 1.12 character has
+    /// it: a 0 has no Exhaustion row, and `GetRestState()`'s nil would raise at the unguarded
+    /// `>= 3` of `MainMenuBar.lua:25`. `rest_pool` is in base kill-XP units, and `resting` is
+    /// `PLAYER_FLAGS_RESTING` (0x20).
     pub(crate) rest_state: u8,
     pub(crate) rest_pool: u32,
     pub(crate) resting: bool,
 
-    /// `PLAYER_FLAGS` bit 12 — **PARTIAL_PLAY_TIME**, what `PartialPlayTime()` answers
-    /// (`0x48eb70`, `shr eax,0xc` / `and al,1`; decision 1746 §"`PLAYER_FLAGS` bit `0x1000` is
-    /// read after all"). The play-time regime a realm with an anti-addiction policy puts an
-    /// account into; on a western realm it never sets.
+    /// `PLAYER_FLAGS` bit 12, `PartialPlayTime()` (`0x48eb70`), an anti-addiction regime's flag.
     pub(crate) partial_play_time: bool,
 
-    /// `PLAYER_FLAGS` bit 13 — what `NoPlayTime()` answers (`0x48ebe0`, the neighbour of the
-    /// above and the harsher half of the same regime).
+    /// `PLAYER_FLAGS` bit 13, `NoPlayTime()` (`0x48ebe0`), the same regime's harsher half.
     pub(crate) no_play_time: bool,
 
-    /// The account's accumulated **rested billing minutes**, from `SMSG_AUTH_RESPONSE` — what
-    /// `GetBillingTimeRested()` returns (decision 1820, binding `0x48ec50`). Minutes is the
-    /// server's convention and the engine converts nothing; stock `PlayerFrame.lua:246` divides by
-    /// 60 for hours. Reached only from inside the two play-time bits above, so with those clear
-    /// nothing in stock FrameXML ever reads it.
+    /// `GetBillingTimeRested()` (`0x48ec50`) in minutes from `SMSG_AUTH_RESPONSE`, unconverted.
     pub(crate) billing_time_rested: u32,
-    /// Is a cinematic playing? What `InCinematic()` reports, pushed by the cinematic plugin.
-    ///
-    /// Read by more than the letterbox: `StaticPopup_Show` refuses any dialog whose entry lacks
-    /// `interruptCinematic` while this is set, exactly as the reference's `StaticPopup.lua:1454`
-    /// does — which is what stops a "your character will be logged out" box from landing on top
-    /// of a first login's race intro.
+    /// `InCinematic()`. While set, `StaticPopup_Show` refuses any dialog without
+    /// `interruptCinematic` (`StaticPopup.lua:1454`).
     pub(crate) in_cinematic: bool,
-    /// Exhaustion.dbc as the rest bindings consume it — rest-state byte → (localized name,
-    /// factor), the table `GetRestState` indexes directly and whose row 1 scales
-    /// `GetXPExhaustion` (wow-re rested-xp-bindings.md; decision 1087). Seeded with the shipped
-    /// 5875 enUS rows so the engine tests and a failed DBC read behave like the shipped client
-    /// (the GlobalStrings-fallback posture); the app overwrites it with the install's real —
-    /// localized — rows at startup ([`UiScript::set_exhaustion_rows`]).
+    /// `Exhaustion.dbc` by rest byte, `(name, factor)`: `GetRestState` indexes it and row 1 scales
+    /// `GetXPExhaustion` (`0x48d3f0`). enUS rows seed it until the app loads the install's own.
     pub(crate) exhaustion: HashMap<u8, (String, f64)>,
 
-    /// The paper doll's combat-stats snapshot (`None` until the app's feed lands), the
-    /// equipment/ammo slot views, and the model pane's persistent bake yaw — the character-window
-    /// seam ([`char_stats`], decision 0208 §3).
+    /// The paper doll's combat stats, `None` until the first push.
     pub(crate) player_combat_stats: Option<char_stats::UnitCombatStats>,
-    /// The **pet's** combat-stats snapshot (decision 1057) — the same shape under the `"pet"`
-    /// token, because the reference's own pet sheet calls the very same `UnitStat`/`UnitResistance`/
-    /// `PaperDollFrame_Set*(unit, prefix)` family with `unit = "pet"` (ref
-    /// `PetPaperDollFrame.lua:73-81`). A second slot rather than a token map: exactly two units
-    /// ever have one, they are fed by two different systems on two different clocks, and every
-    /// binding's route is a fork between them (the [`Self::pet_book`] precedent).
+    /// The pet's combat stats, which the reference's pet sheet reads as `UnitStat("pet", …)`.
     pub(crate) pet_combat_stats: Option<char_stats::UnitCombatStats>,
     pub(crate) inventory_slots: char_stats::InventorySlots,
-    /// The six bank-bag slots (live ids 64..=69) — the third band of
-    /// [`char_stats::Model::inv_slot`], and a store rather than a view because a bank bag has no
-    /// container slot to be read out of: it IS the container. Fed beside
-    /// [`Self::inventory_slots`] off the player descriptor's own guids.
+    /// The six bank-bag slots, ids 64..=69, fed from the player descriptor's guids.
     pub(crate) bank_bag_slots: char_stats::BankBagSlots,
-    /// The 12 alert-region statuses (`GetInventoryAlertStatus`, DurabilityFrame's armor-guy
-    /// feed) in the client's own `0x806eb8` table order (11 equipment regions + the low-ammo
-    /// 12th) — recomputed on every inventory push, which fires `UPDATE_INVENTORY_ALERTS`
-    /// unconditionally, the client's own shape (see [`char_stats`]).
+    /// `GetInventoryAlertStatus` in `0x806eb8` order; every push fires `UPDATE_INVENTORY_ALERTS`.
     pub(crate) inventory_alerts: [u8; 12],
-    /// Inventory-slot ids queued by `UseInventoryItem` (decision 0208 phase 1b, `cursor`'s `doll`
-    /// submodule) — drained by the app into `CMSG_USE_ITEM` against the equipped position.
+    /// `UseInventoryItem` slot ids, sent as `CMSG_USE_ITEM` on the equipped item.
     pub(crate) inventory_uses: Vec<u32>,
-    /// The two weapons' **temporary** enchantments — `[0]` main hand, `[1]` off hand, in the order
-    /// `GetWeaponEnchantInfo` pushes them ([`weapon_enchant`]). A separate slot from
-    /// [`Self::inventory_slots`] on purpose: this one carries a live countdown and is pushed every
-    /// frame, where the slot snapshot is change-gated and fires an event.
+    /// Main- and off-hand temporary enchants in `GetWeaponEnchantInfo`'s order, pushed each frame.
     pub(crate) weapon_enchants: [Option<weapon_enchant::WeaponEnchant>; 2],
 
-    /// The inspected unit's equipment view, keyed by unit token ([`inspect`], decision 0631) —
-    /// the *second* source behind the unit-keyed `GetInventoryItem*` family. Unlike
-    /// [`Self::inventory_slots`] this is PUBLIC descriptor data (`PLAYER_VISIBLE_ITEM_*`), which
-    /// is the whole reason a foreign player's gear can be read at all. `None` = nothing inspected.
+    /// The inspected unit's gear, from its public `PLAYER_VISIBLE_ITEM_*` fields.
     pub(crate) inspect: Option<inspect::InspectView>,
-    /// Unit tokens queued by `NotifyInspect` — drained by the app into `CMSG_INSPECT`.
+    /// `NotifyInspect` unit tokens, sent as `CMSG_INSPECT`.
     pub(crate) inspect_notifies: Vec<String>,
-    /// `ClearInspectPlayer` was called — drained by the app, which drops its inspect target.
+    /// `ClearInspectPlayer` ran; the app drops its inspect target.
     pub(crate) inspect_clear: bool,
-    /// The dressing room's queued intents (decision 1060) — the `DressUpModel` widget's
-    /// `SetUnit`/`Dress`/`Undress`/`TryOn`, drained by the app in order (see [`super::dressup`] on
-    /// why order matters). The pane's yaw is its own `ModelState` facing, like every migrated
-    /// window's (`UiScript::model_pane_facing`, 1751/1969).
+    /// `DressUpModel` `SetUnit`, `Dress`, `Undress` and `TryOn` calls, applied in call order.
     pub(crate) dressup_intents: Vec<super::dressup::DressUpIntent>,
-    /// The tabard designer (1977): each `TabardModel`'s five values, the last seeded/cycled five
-    /// (the app's body preview), the host facts, and the queued intents.
+    /// Tabard designs per `TabardModel`, the app's preview five, the host facts and queued calls.
     pub(crate) tabard_designs: HashMap<crate::widget::FrameHandle, [i32; 5]>,
     pub(crate) tabard_preview: Option<[i32; 5]>,
     pub(crate) tabard_host: super::tabard::TabardHost,
     pub(crate) tabard_intents: Vec<super::tabard::TabardIntent>,
-    /// The WorldFrame type's one-shot registry record (1984): `true` once the first is made.
+    /// The `WorldFrame` type's one-shot record: true once the first is made.
     pub(crate) world_frame_made: bool,
-    /// Unit token (lowercase) → what the app resolved about it this frame, for **every** token
-    /// that named a **live unit object**, creature as readily as player — the input to both
-    /// verified range predicates (`CanInspect`, `CheckInteractDistance`). An absent token is one
-    /// the object manager holds nothing for, and both answer `nil` there (see
-    /// [`UiScript::set_unit_reach`] and [`super::UnitReach`]).
+    /// Per lowercased live-unit token, reach for `CanInspect`/`CheckInteractDistance`; absent: nil.
     pub(crate) unit_reach: HashMap<String, super::UnitReach>,
 
-    /// The skills-pane snapshot the app pushes ([`skills::SkillsState`], decision 0437 phase 4) and
-    /// the synthesized display tree built from it ([`skills::UiScript::set_skills`]) — the skills
-    /// seam ([`skills`]).
+    /// The skills pane's snapshot and the display tree built from it.
     pub(crate) skills: skills::SkillsState,
     pub(crate) skills_groups: Vec<skills::SkillGroup>,
-    /// The categories the player has collapsed (by `category_id`) — survives a content update the
-    /// same way [`Model::trainer_collapsed`] does.
+    /// Collapsed skill categories by id, kept across a re-push.
     pub(crate) skills_collapsed: HashSet<u32>,
-    /// The engine-held selection, by SKILL ID (not visible index — see [`skills`]'s module doc).
+    /// The selection as a skill id, not a row.
     pub(crate) skills_selected: Option<u32>,
-    /// Skill line ids the `AbandonSkill` Lua binding queued since the app's last
-    /// [`UiScript::take_skill_abandons`] drain — the outbound unlearn seam (the app sends each as
-    /// a `CMSG_UNLEARN_SKILL`; the engine mutates NOTHING locally — the real client waits for the
-    /// server's skill-field update, vmangos `SkillHandler.cpp`'s `SetSkill(id, 0, 0)` round trip).
+    /// `AbandonSkill` ids for `CMSG_UNLEARN_SKILL`; nothing changes until the server's update.
     pub(crate) skill_abandons: Vec<u32>,
 
-    /// The reputation-pane snapshot the app pushes ([`reputation::ReputationState`]) and the
-    /// synthesized display tree built from it ([`reputation::UiScript::set_reputation`]) — the
-    /// reputation seam ([`reputation`]).
+    /// The reputation pane's snapshot and the display tree built from it.
     pub(crate) reputation: reputation::ReputationState,
     pub(crate) reputation_groups: Vec<reputation::FactionGroup>,
-    /// The header groups the player has folded, by HEADER KEY (a `Faction.dbc` id, or the
-    /// synthetic `0` "Other" / `-1` "Inactive") — an identity a re-push cannot move, unlike a row
-    /// index. Reset to all-expanded-but-Inactive on every push, exactly as
-    /// [`Model::skills_collapsed`] is: the client's own rebuild does the same.
+    /// Folded headers by key (a `Faction.dbc` id, 0 "Other", -1 "Inactive"), reset on every push
+    /// to all open but Inactive, as the client's rebuild does.
     pub(crate) reputation_collapsed: HashSet<i64>,
-    /// The engine-held selection, by REPUTATION-LIST SLOT (not visible index — see
-    /// [`reputation`]'s module doc).
+    /// The selection as a reputation-list slot, not a row.
     pub(crate) reputation_selected: Option<u32>,
-    /// Reputation verbs the pane's bindings queued since the app's last
-    /// [`UiScript::take_reputation_sends`] drain — the outbound seam. Unlike the skills abandon
-    /// above, the engine DOES mutate locally first: none of the three sends is acked.
+    /// Reputation calls queued, applied locally first because none of the three sends is acked.
     pub(crate) reputation_sends: Vec<reputation::ReputationSend>,
 
-    /// Chat lines the input EditBox submitted (its `OnEnterPressed` → the `SubmitChatInput` Lua
-    /// binding) since the app's last [`UiScript::take_chat_input`] drain — the outbound Lua→app seam
-    /// for the chat input (the twin of `loot_picks`). The app routes each through its slash-command
-    /// parser into a `CMSG_MESSAGECHAT`/`CMSG_TEXT_EMOTE`.
+    /// Lines the chat box submitted (`SubmitChatInput`), for the app's slash-command parser.
     pub(crate) chat_input: Vec<String>,
 
-    /// The world-map seam ([`worldmap`](super::worldmap)): the pushed catalog/feed + the
-    /// engine-owned selection.
+    /// The world map's pushed catalog and feed, and its selection.
     pub(crate) worldmap: super::worldmap::WorldMapState,
-    /// The V-key nameplate pool — engine-owned `Button` widgets under the `WorldFrame`, grown on
-    /// demand and never shrunk, in creation order (decision 2148). Lives here rather than on
-    /// [`super::UiScript`] because it IS model state: the plates are arena frames, and an addon
-    /// walking `WorldFrame:GetChildren()` reaches them like any other.
+    /// Nameplate `Button`s under `WorldFrame`, never shrunk, visible to `GetChildren()`.
     pub(crate) nameplates: super::nameplate::NamePlates,
-    /// The always-up world-state readout's rows ([`worldstate`](super::worldstate)), already
-    /// gated and resolved app-side.
+    /// The world-state readout's rows, gated and resolved by the app.
     pub(crate) worldstate: super::worldstate::WorldStateUiState,
-    /// Events (name + args) queued by Lua bindings (`SetMapZoom` → `WORLD_MAP_UPDATE`;
-    /// `PickupContainerItem`/`ClearCursor`/… → `CURSOR_UPDATE`/`ITEM_LOCK_CHANGED`/
-    /// `DELETE_ITEM_CONFIRM`, decision 0216 §4/§5) to fire at the next
-    /// [`UiScript::tick`](super::UiScript::tick) — a binding executes *inside* Lua, so it can't
-    /// re-enter the handler dispatch synchronously; one tick of deferral is invisible at frame
-    /// rate (the reference fires these synchronously as pure repaint triggers).
+    /// Events bindings raise. Deviation: fired at the next tick, not synchronously as in the
+    /// reference, because a binding runs inside Lua and cannot re-enter handler dispatch.
     pub(crate) pending_events: Vec<(String, Vec<ScriptValue>)>,
-    /// The last cursor position [`UiScript::mouse_move`](super::UiScript::mouse_move)/`mouse_button`
-    /// saw (UI space: logical px, y-up — the same frame `resolve` rects live in). Behind Lua's
-    /// `GetCursorPosition()`; the reference world map polls it every OnUpdate for hover/click math.
+    /// The last cursor position in UI space (logical px, y-up), behind `GetCursorPosition()`.
     pub(crate) cursor_pos: (f32, f32),
 
-    /// A `Minimap:PingLocation(x, y)` call, parked for the app to drain **in the same frame**
-    /// ([`UiScript::take_minimap_ping_request`]): centre-relative offsets in **UI units**
-    /// (x right, y up — `GetCursorPosition`'s own space, which is NOT the window-pixel space
-    /// the app's minimap geometry lives in; the app applies the 0582 seam scale on the way in,
-    /// and getting that wrong is decision 1596's first root cause).
+    /// A `Minimap:PingLocation(x, y)`, drained the same frame: centre-relative offsets in UI units,
+    /// `GetCursorPosition`'s space, not the window pixels of the app's minimap geometry.
     pub(crate) minimap_ping_request: Option<(f32, f32)>,
-    /// The minimap ping's **normalized** offsets from the widget centre (fractions of the widget
-    /// side, x right / y up — the `MINIMAP_PING` event's arg2/arg3 space), republished by the app
-    /// every frame from the stored world point against the player's live position. Behind
-    /// `Minimap:GetPingPosition()`, which answers **two numbers always** — the reference
-    /// recomputes them per call from a pair of statics nothing ever clears (wow-re
-    /// `minimap-ping-law.md`), and the stock `Minimap_OnUpdate` multiplies the answer without a
-    /// nil test for the whole of its 5 s timer (1974; 1596's nil answer stood until then). There
-    /// is exactly one ping, so it lives here rather than on each Minimap widget's
-    /// [`KindState`](crate::widget::KindState) — one write, one read, no arena walk.
+    /// The ping's offsets as fractions of the minimap's side, updated by the app every frame.
+    /// `GetPingPosition()` always answers both, from statics never cleared (`0x4eefd0`).
     pub(crate) minimap_ping: (f32, f32),
-    /// The realm this session is on, behind `GetRealmName()` (decision 1195). `""` until the app
-    /// pushes one — the glue screen's own answer, and never `nil`, because the corpus idiom is
-    /// `db[GetRealmName()] = …` at file scope and a nil index errors one call deeper.
-    /// Lines an addon queued with `SendChatMessage`, drained by the app into the wire
-    /// (decision 1199). Deliberately a different queue from the chat box's input: the box's drain
-    /// runs the slash grammar and this one must not.
+    /// `SendChatMessage` lines, apart from chat-box input, whose drain runs the slash grammar.
     pub(crate) chat_sends: Vec<super::chat_send::ChatSend>,
-    /// Broadcasts an addon queued with `SendAddonMessage`, drained by the app into the wire
-    /// (decision 1235). Its own queue rather than [`Self::chat_sends`] because it is a different
-    /// wire: `LANG_ADDON` in the language field, a four-value distribution set, and a payload the
-    /// binding already composed as `prefix` TAB `message`.
+    /// `SendAddonMessage` broadcasts: `LANG_ADDON`, four distributions, `prefix` TAB `message`.
     pub(crate) addon_sends: Vec<super::addon_message::AddonSend>,
-    /// `RequestTimePlayed()` asks queued since the app last drained them — each is one
-    /// `CMSG_PLAYED_TIME`. A COUNT, not a payload, for [`super::pvp`]'s reason: the packet is
-    /// empty, so two asks in a frame are two sends rather than one collapsed intent.
+    /// `RequestTimePlayed()` calls, one empty `CMSG_PLAYED_TIME` each.
     pub(crate) played_time_asks: u32,
-    /// `Screenshot()` calls queued since the app last drained them — each is one capture
-    /// (decision 1487). A COUNT for [`Self::played_time_asks`]'s reason: the request carries no
-    /// payload, so two calls in a frame are two captures.
+    /// `Screenshot()` calls, one capture each.
     pub(crate) screenshot_asks: u32,
+    /// `GetRealmName()`: `""` until pushed, never nil, since addons index tables with it at load.
     pub(crate) realm_name: String,
-    /// **The local player record — `0xc27d80`, ours** (decisions 2261 and 2263).
-    ///
-    /// The bytes, the four verbs that read it and why `UnitLevel` is not among them are on
-    /// [`super::PlayerRecord`] itself; what belongs here is the *lifetime*, because that is what
-    /// this field's position in the `Model` decides.
-    ///
-    /// **Two writers, and the asymmetry between them is the mechanism.** The world-entry UI load
-    /// seeds it from the roster row of the pick in flight — our copy of the same char-enum record
-    /// — beside [`Self::realm_name`] and before the addon walk (1195's slot, 1230's source); and
-    /// [`super::UiScript::set_unit`] keeps it in step for any `"player"` push that **carries** the
-    /// field. A push that does not carry it leaves it standing. So the record can be corrected but
-    /// never blanked, which is the reference's never-cleared property expressed where it can be
-    /// relied on — and decision 2260 is why that matters: a name-cache miss for our own guid
-    /// reached Lua as a nameless player snapshot and took KLHThreatMeter down with it.
-    ///
-    /// Our VM is rebuilt per login (1290) where the reference's record simply persists, so each new
-    /// VM is told once. That is the whole of the difference, and it is unobservable: the four verbs
-    /// do not exist between logins either — they live only in the in-game table `0x850438`, which
-    /// `UI_Init` installs and the teardown nils, and `GlueScript_RegisterBindings 0x46abb0` skips.
+    /// The local player record (`0xc27d80`), seeded at world entry before addons load, then kept by
+    /// `"player"` pushes that carry it: corrected, never blanked. A per-login rebuild is unseen, as
+    /// its verbs exist only in game (`0x850438`), not at the glue screen (`0x46abb0`).
     pub(crate) player_record: super::PlayerRecord,
-    /// The hearthstone bind location's NAME, behind `GetBindLocation()` — the app resolves the
-    /// `SMSG_BINDPOINTUPDATE` area id through the same AreaTable catalog the hearthstone's `$z`
-    /// token already uses, and pushes the resolved string here.
-    ///
-    /// Empty only before that packet has landed — `""`, never nil, matching [`Self::realm_name`]
-    /// beside it: a consumer concatenates this (`Necrosis.lua:1089`), so nil would be a raise.
+    /// `GetBindLocation()`, the bind point's area name: `""` before it lands, never nil.
     pub(crate) bind_location: String,
-    /// `ConfirmBinder()` calls queued since the app last drained them — each is one
-    /// `CMSG_BINDER_ACTIVATE`. A COUNT for [`Self::played_time_asks`]'s reason: the intent carries
-    /// no payload (the app holds the innkeeper's guid), so two calls are two sends.
-    /// The `GMTicketCategory.dbc` rows behind `GetGMTicketCategories()` — `(id, name)` in file
-    /// order, pushed once by the app ([`super::UiScript::set_gm_ticket_categories`]). The ids are
-    /// the wire values, so this is an ordered pair list rather than an indexable table
-    /// (decision 1673).
+    /// `GMTicketCategory.dbc` `(id, name)` rows in file order; the ids are wire values.
     pub(crate) gm_ticket_categories: Vec<(u32, String)>,
-    /// Every ticket verb the window called since the app's last drain, **in call order** — ask,
-    /// status-ask, delete, create, edit, one packet each. ONE queue rather than a counter per verb
-    /// so that `DeleteGMTicket(); GetGMTicket()` in a single chunk reaches the wire in that order;
-    /// per-verb drains cannot express it, and the get would answer with the pre-delete state
-    /// (decision 1673).
+    /// GM ticket calls in call order, so a delete then a get reach the wire in that order.
     pub(crate) gm_ticket_intents: Vec<super::gm_ticket::GmTicketIntent>,
-    /// `Stuck()` calls queued — each is one cast of spell 7355, the Help window's Auto-Unstuck.
+    /// `Stuck()` calls, each a cast of spell 7355, the Help window's Auto-Unstuck.
     pub(crate) stuck_casts: u32,
+    /// `ConfirmBinder()` calls, one `CMSG_BINDER_ACTIVATE` each; the app holds the innkeeper.
     pub(crate) binder_confirms: u32,
-    /// Is an innkeeper's bind question still live and in range — the answer `CheckBinderDist()`
-    /// gives, pushed by the app each frame ([`super::UiScript::set_binder_pending`]). The
-    /// CONFIRM_BINDER dialog polls it from OnUpdate and hides itself when it goes false, which is
-    /// how walking away from the innkeeper takes the question off screen (decision 1331).
+    /// `CheckBinderDist()`: the innkeeper's question is live and in range; false hides its dialog.
     pub(crate) binder_pending: bool,
-    /// The summon question's three resolved reads, pushed by the app each frame
-    /// ([`super::UiScript::set_summon_confirm`]) — what `GetSummonConfirmSummoner`,
-    /// `GetSummonConfirmAreaName` and `GetSummonConfirmTimeLeft` answer ([`super::summon`]).
-    /// Default (two empty strings and a zero) is exactly what the reference's getters answer with
-    /// nothing pending, so the pre-push window behaves like the post-expiry one (decision 1747).
+    /// The summon getters' answers, defaulting to the reference's `""`, `""`, 0 with none pending.
     pub(crate) summon_confirm: super::summon::SummonConfirmUiState,
-    /// `ConfirmSummon()` calls queued since the app's last drain — each is one outbound
-    /// `CMSG_SUMMON_RESPONSE`. A COUNT for [`Self::binder_confirms`]'s reason: the app holds the
-    /// summoner's guid, so the intent carries no payload of its own.
+    /// `ConfirmSummon()` calls, one `CMSG_SUMMON_RESPONSE` each; the app holds the summoner.
     pub(crate) summon_confirms: u32,
-    /// Frames per second, behind `GetFramerate()`. Pushed per tick by the app, which owns the
-    /// clock this crate does not have.
+    /// `GetFramerate()`, pushed each tick.
     pub(crate) framerate: f64,
-    /// The modifier-key mirror `(shift, ctrl, alt)` behind `IsShiftKeyDown`/`IsControlKeyDown`/
-    /// `IsAltKeyDown` — pushed by the app's input pass ([`UiScript::set_modifiers`]) BEFORE the
-    /// frame's mouse events, so a click handler's fork reads the state at click time.
+    /// `(shift, ctrl, alt)` for `Is*KeyDown`, pushed before the frame's mouse events.
     pub(crate) modifiers: (bool, bool, bool),
 }
 
 impl Model {
-    /// The detail pane of the row `SelectQuestLogEntry` currently names — resolved HERE, per call,
-    /// never baked into the pushed snapshot (decision 2247). The reference's detail bindings read
-    /// the selection variable and peek the quest cache inside the same call, so a select-then-read
-    /// pair within one frame answers about the row just selected; the app's push only supplies the
-    /// per-row data those reads land on. `None` for no selection, an out-of-range one, or a header.
+    /// The selected quest-log row's detail, resolved per call as the reference's bindings do.
     pub(crate) fn selected_quest_detail(&self) -> Option<&quest_log::QuestLogDetail> {
         let index = usize::try_from(self.quest_log_selection.checked_sub(1)?).ok()?;
         self.quest_log.entries.get(index)?.detail.as_ref()
@@ -1810,19 +942,7 @@ impl Model {
 }
 
 impl Model {
-    /// A unit token's snapshot, **case-folded the way the client folds it**.
-    ///
-    /// 1.12's resolver `0x515970` compares each of its literals with `SStrCmpI` → `_strnicmp`,
-    /// whose fold is `'A'..'Z' += 0x20` and nothing else: the `jb`/`ja` bounds are unsigned, so a
-    /// byte ≥ 0x80 is never folded. `to_ascii_lowercase` is exactly that rule, and the reason this
-    /// does not use `to_lowercase()` — a locale-aware fold would map bytes the client leaves alone.
-    ///
-    /// The uppercase scan is a fast path, not an optimisation for its own sake: every internal
-    /// caller passes a lowercase literal (`"player"`, `"target"`), so the common case allocates
-    /// nothing and only an addon's `"Player"` pays for a `String`.
-    /// A named font object, **case-folded the way the client folds it** — `SStrCmpI` over the font
-    /// registry's keys. ASCII only, and the uppercase scan is a fast path: every internal caller
-    /// passes an exact shipped name, so only an addon's odd spelling pays for a `String`.
+    /// A named font object, matched case-insensitively (ASCII) as the client's `SStrCmpI` does.
     pub(crate) fn font_object(&self, name: &str) -> Option<&FontObject> {
         if name.bytes().any(|b| b.is_ascii_uppercase()) {
             self.font_objects_by_lower.get(&name.to_ascii_lowercase())
@@ -1831,34 +951,16 @@ impl Model {
         }
     }
 
-    /// Record one script error on **both** channels: the host's `errors` vec (the instruments'
-    /// channel — the harness blocker tables, the app's log drain) and the handler-dispatch queue
-    /// (the player's channel — decision 1305). Every engine-caught script error goes through here;
-    /// a failure raised by the error handler *itself* is pushed to `errors` directly instead,
-    /// which is what keeps the dispatch from recursing.
+    /// Records a caught script error for the host, the retained log and the Lua error handler; an
+    /// error raised by the handler itself goes to `errors` directly, which stops the recursion.
     pub(crate) fn record_script_error(&mut self, msg: String) {
-        // Three channels now, and the third is the one with a memory (decision 1495): the dialog
-        // shows a burst's first message and the host drain empties every frame, so without this
-        // the 1,112 raises after the first exist nowhere a player can reach.
         self.diagnostics
             .record(super::diagnostics::DiagnosticKind::Error, &msg);
         self.pending_error_dispatch.push(msg.clone());
         self.errors.push(msg);
     }
 
-    /// **Record one non-fatal warning — the channel's one door** (decision 2135). Both halves:
-    /// the host's per-frame `warnings` drain (a `warn!` line in the terminal, for whoever is
-    /// running the client), and the retained diagnostic log, which is the only copy a player or an
-    /// instrument can read after the frame that produced it.
-    ///
-    /// Before this there was only the first half, and it was a dead end: `take_warnings` empties
-    /// every frame, so a warning existed for the length of one terminal line and then nowhere at
-    /// all. The messages it carries are the failures that never announce themselves — a dropped
-    /// `inherits=`, an unresolved anchor, an unregistered CVar — which is precisely the class the
-    /// diagnostic log was built for.
-    ///
-    /// Its sibling is [`Self::warn_host_only`], for the one message already retained under a
-    /// truer kind.
+    /// Records a non-fatal warning for the host's terminal and the retained diagnostic log.
     pub(crate) fn record_warning(&mut self, msg: impl Into<String>) {
         let msg = msg.into();
         self.diagnostics
@@ -1866,15 +968,13 @@ impl Model {
         self.warnings.push(msg);
     }
 
-    /// The host channel **alone** — for a message that is already retained under a kind that says
-    /// more than `Warning` does. Exactly one caller: `LoadAddOn`'s failure line, which
-    /// `record_load_failure` has already filed as a [`Load`](super::diagnostics::DiagnosticKind)
-    /// row ("the addon isn't running", which is the fact worth keeping) and which still wants its
-    /// terminal line. Retaining it twice would put the same sentence in the log under two kinds.
+    /// A warning for the host's terminal only, for a message already retained under another kind.
     pub(crate) fn warn_host_only(&mut self, msg: String) {
         self.warnings.push(msg);
     }
 
+    /// A unit token's state, folded as 1.12's resolver `0x515970` folds (`_strnicmp`: `A`..`Z`
+    /// only, never a byte of 0x80 or more), so `to_ascii_lowercase`, never `to_lowercase`.
     pub(crate) fn unit(&self, token: &str) -> Option<&UnitState> {
         if token.bytes().any(|b| b.is_ascii_uppercase()) {
             self.units_by_lower.get(&token.to_ascii_lowercase())
@@ -1951,8 +1051,7 @@ impl Model {
             pending_error_dispatch: Vec::new(),
             diagnostics: Default::default(),
             warnings: Vec::new(),
-            // Classic Era's UIParent virtual space is 1024×768-ish; a sensible default the host can
-            // override with `set_screen_size`. y-up: [bottom, left, top, right].
+            // 1024x768 until the host calls `set_screen_size`; y-up `[bottom, left, top, right]`.
             screen: Rect::new(0.0, 0.0, 768.0, 1024.0),
             units_by_lower: HashMap::new(),
             auras: HashMap::new(),
@@ -1983,8 +1082,7 @@ impl Model {
             petition_requests: Vec::new(),
             tell_requests: Vec::new(),
             open_chat_requests: Vec::new(),
-            // Seeded per window, because the stock `DOCKED` position is not the same for all
-            // seven (`ChatWindowLook::stock`): 1 and 2 are the dock, 3..7 are undocked.
+            // Per window, as the stock dock differs: 1 and 2 are the dock, the rest undocked.
             chat_window_looks: std::array::from_fn(chat_window::ChatWindowLook::stock),
             chat_window_changes: HashSet::new(),
             chat_colors: super::chat_types::seed(),
@@ -2019,6 +1117,7 @@ impl Model {
             action_bar_toggles: None,
             action_bar_toggle_sends: Vec::new(),
             sound_queue: Vec::new(),
+            music_queue: Vec::new(),
             sound_suppression: 0,
             cvars: HashMap::new(),
             cvars_saved_base: HashMap::new(),
@@ -2031,6 +1130,7 @@ impl Model {
             video_caps: super::cvars::VideoCaps::default(),
             restart_gx_asks: 0,
             saved_names: Vec::new(),
+            held_saved_files: Vec::new(),
             keybinds: super::keybind::KeybindState::default(),
             actions: HashMap::new(),
             action_states: HashMap::new(),
@@ -2321,9 +1421,7 @@ impl Model {
         self.next_id += 1;
         self.frame_to_id.insert(h, id);
         self.id_to_frame.insert(id, h);
-        // A fresh id means a frame just entered the layout graph (`frame_to_id` is the resolve's
-        // roster) — the mint is the one chokepoint every creation path funnels through (bindings,
-        // the XML loader, anchor-target resolution), so the tier-1 gate can't miss a birth.
+        // Every creation path mints here, so a new frame always opens the layout gate.
         self.touch_layout();
         id
     }
@@ -2337,39 +1435,21 @@ impl Model {
         self.next_id += 1;
         self.region_to_id.insert(h, id);
         self.id_to_region.insert(id, h);
-        // A fresh region id can seat the region in the resolve's external set — same birth
-        // chokepoint as `frame_id`'s.
+        // A new region can join the resolve's external set, so it opens the gate too.
         self.touch_layout();
         id
     }
 
-    /// A write that can move [`UiScript::resolve_layout`]'s read set happened: anchors, sizes,
-    /// measured text, scale, clamp, scroll state, frame/region births, or the screen rect. Every
-    /// mutating BINDING (and app-facing setter) on that set calls this — tier 1 of the resolve
-    /// change gate. The resolve's own pre-pass (`tooltip::layout_tooltips`) deliberately does NOT:
-    /// its writes are derived from state that already arrived through touched paths, and a
-    /// self-touch would pin the gate open forever. A missed site is a silently stale layout —
-    /// exactly the failure `WOW_LAYOUT_VERIFY` (on for every benilla-ui test) exists to catch
-    /// loudly, by proving the fingerprint still matches whenever tier 1 claims quiet.
+    /// A layout write that names no node. The resolve's tooltip pre-pass must not call this, or
+    /// the gate never closes; a missed call is caught by `WOW_LAYOUT_VERIFY`.
     pub(crate) fn touch_layout(&mut self) {
-        // The conservative half of the tier-1 ledger (decision 1388): this write did not name a
-        // node, so the cached graph can no longer be trusted to describe the live model and the
-        // next resolve must derive it in full. Every site that has NOT been migrated to a precise
-        // touch lands here, which is why migration can be incremental and a missed one is slow
-        // rather than wrong.
+        // Naming nothing, the next resolve derives the graph in full: slow, never wrong.
         self.give_up_naming();
         self.bump_layout_epoch();
     }
 
-    /// A write that moved **one region's** layout inputs and changed nothing else about the graph:
-    /// its anchor OFFSETS, its explicit size, its measured extent. Not its anchor targets, not its
-    /// membership, not its liveness — those move edges or the roster, and belong on
-    /// [`Self::touch_layout`].
-    ///
-    /// Falls back to the conservative touch whenever it cannot prove the region is a node of the
-    /// **cached** graph: no minted id, an id past the roster's arrays, or an id the last derive
-    /// left unmapped (an anchor-less region, a region born since). That fallback is what makes the
-    /// call safe to reach for — the worst a mistaken one can do is derive the graph again.
+    /// A write that moved one region's offsets, size or measured extent, not its targets or
+    /// liveness; a region missing from the cached graph falls back to `touch_layout`.
     pub(crate) fn touch_layout_region(&mut self, rh: RegionHandle) {
         match self.region_to_id.get(&rh) {
             Some(&id) => self.touch_layout_node(id),
@@ -2377,8 +1457,7 @@ impl Model {
         }
     }
 
-    /// [`Self::touch_layout_region`]'s frame twin — an anchor offset, a width/height, and nothing
-    /// that moves an edge or the roster.
+    /// The same for a frame: an anchor offset or size, nothing that moves an edge or the roster.
     pub(crate) fn touch_layout_frame(&mut self, h: FrameHandle) {
         match self.frame_to_id.get(&h) {
             Some(&id) => self.touch_layout_node(id),
@@ -2386,17 +1465,39 @@ impl Model {
         }
     }
 
-    /// An anchor RETARGET that names its node: the write moved node `h`'s (or `rh`'s) set of
-    /// anchor TARGETS, and hands over both target lists so the cached graph's edges can be
-    /// re-pointed instead of thrown away (decision 1625, extending 1388).
-    ///
-    /// `old`/`new` are the node's FULL anchor-target lists either side of the write. Falls back to
-    /// the conservative touch whenever the scope refuses the patch — the same "worst case is a
-    /// derivation" safety the other precise touches have.
+    /// A `SetParent` under `root`: only the subtree's scale moves, as anchor targets are ids fixed
+    /// at `SetPoint`. Addon pools reparent hundreds of frames a redraw, so this stays precise.
+    pub(crate) fn touch_layout_reparent(&mut self, root: FrameHandle) {
+        let mut subtree = vec![root];
+        let mut at = 0;
+        while at < subtree.len() {
+            let h = subtree[at];
+            at += 1;
+            if let Some(f) = self.arena.frame(h) {
+                subtree.extend(f.children.iter().copied());
+            }
+        }
+        // Write the new scale here: only a full derivation syncs it, and a named node skips that.
+        let Model {
+            arena,
+            layout_inputs,
+            ..
+        } = self;
+        for &h in &subtree {
+            if let Some(f) = arena.frame(h) {
+                layout_inputs.entry(h).or_default().scale = f.effective_scale;
+            }
+        }
+        for h in subtree {
+            self.touch_layout_frame(h);
+        }
+    }
+
+    /// A write changed frame `h`'s anchor targets; `old` and `new` are its full target lists, so
+    /// the cached edges are re-pointed. Falls back to `touch_layout` when the scope refuses.
     pub(crate) fn touch_layout_retarget_frame(&mut self, h: FrameHandle, old: &[u32], new: &[u32]) {
         match self.frame_to_id.get(&h).copied() {
-            // Already conservative ⇒ the next resolve rebuilds every edge from scratch anyway, so
-            // patching them would be work with no reader.
+            // Already conservative: the next resolve rebuilds every edge, so patching is wasted.
             Some(id)
                 if self.layout_touched.is_some() && self.layout_scope.retarget(id, old, new) =>
             {
@@ -2406,7 +1507,7 @@ impl Model {
         }
     }
 
-    /// [`Self::touch_layout_retarget_frame`]'s region twin.
+    /// `touch_layout_retarget_frame` for a region.
     pub(crate) fn touch_layout_retarget_region(
         &mut self,
         rh: RegionHandle,
@@ -2423,36 +1524,20 @@ impl Model {
         }
     }
 
-    /// A write that could move region `rh`'s measure key — its text, its font face/height/
-    /// outline, its text height, its explicit size (the wrap width) — names the region on the
-    /// measure ledger ([`Self::measure_dirty`]). Push-only and unfiltered: non-FontStrings and
-    /// same-value writes cost one `Vec` push here and one staleness probe at the next sweep,
-    /// which is the price of keeping every enrolled site a one-liner.
+    /// Names `rh` on the measure ledger for a write that may move its measure key.
     pub(crate) fn touch_measure(&mut self, rh: RegionHandle) {
         if let Some(list) = &mut self.measure_dirty {
             list.push(rh);
         }
     }
 
-    /// A write that moves measure keys WITHOUT being able to name the regions — a font-object
-    /// edit fanning out to every inheriting region, a scale change propagating down a subtree,
-    /// [`super::UiScript::invalidate_text_measures`]. The next sweep walks the whole roster,
-    /// exactly as every sweep did before the ledger existed. All human-rate paths.
+    /// A measure-key write that names no region, such as a font object: the next sweep walks all.
     pub(crate) fn touch_measure_all(&mut self) {
         self.measure_dirty = None;
     }
 
-    /// Name a node **without opening tier 1** — for the resolve's own pre-pass
-    /// (`tooltip::layout_tooltips`), which writes layout inputs derived from state that already
-    /// arrived through touched paths.
-    ///
-    /// It deliberately does not call [`Self::touch_layout`]: bumping the epoch from inside a
-    /// resolve would pin the gate open forever (the pre-pass runs on every let-through resolve, so
-    /// it would re-dirty the very resolve it is running in). But the ledger still has to hear about
-    /// it, or an incremental pass would inherit a node whose hash the pre-pass moved and no write
-    /// site named — the one shape that could ship a stale rect. Naming it is free: the hash it
-    /// recomputes is unchanged on the frames the pre-pass writes idempotently, which is nearly all
-    /// of them, so no dirty seed comes of it.
+    /// Names a frame without bumping the epoch, for the resolve's own tooltip pre-pass: a bump
+    /// inside a resolve would hold the gate open for good, yet an unnamed write could go stale.
     pub(crate) fn note_layout_frame_write(&mut self, h: FrameHandle) {
         if self.layout_touched.is_some() {
             match self.frame_to_id.get(&h) {
@@ -2467,7 +1552,7 @@ impl Model {
         }
     }
 
-    /// [`Self::note_layout_frame_write`]'s region twin.
+    /// `note_layout_frame_write` for a region.
     pub(crate) fn note_layout_region_write(&mut self, rh: RegionHandle) {
         if self.layout_touched.is_some() {
             match self.region_to_id.get(&rh) {
@@ -2482,8 +1567,7 @@ impl Model {
         }
     }
 
-    /// Name `id` as the only thing this write moved — if the cached graph has a node for it and no
-    /// earlier write in this frame already gave up on naming.
+    /// Names `id` as what this write moved, if the cached graph has it and naming is still on.
     fn touch_layout_node(&mut self, id: u32) {
         let in_graph = self.layout_scope.has_node(id);
         match &mut self.layout_touched {
@@ -2495,17 +1579,8 @@ impl Model {
         self.bump_layout_epoch();
     }
 
-    /// Give up naming what this write moved: the cached graph can no longer be trusted, so the
-    /// next resolve derives it in full. **Every** site that sets [`Self::layout_touched`] to
-    /// `None` goes through here, because that transition is the only event worth a name.
-    ///
-    /// `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>` — backtrace the first `n` of them after `secs`. 1388
-    /// left `layout_derivations` as "the counter to watch", and a non-zero reading as the proof
-    /// that "a write site somewhere fell back to the conservative touch" — but gave nobody a way
-    /// to find out WHICH, and `WOW_LAYOUT_TOUCH_TRACE` cannot answer it: it fires on every touch,
-    /// and the precise ones outnumber the poisoning one by hundreds to one. Only the Some → None
-    /// EDGE is printed: once a frame has given up, the fallbacks behind it are consequences, not
-    /// causes, and printing them buries the one line that matters.
+    /// Every write that gives up naming comes through here, so the next resolve derives in full.
+    /// `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>` backtraces the first `n` of these after `secs`.
     fn give_up_naming(&mut self) {
         if self.layout_touched.is_some() && derive_trace_armed() {
             eprintln!(
@@ -2516,20 +1591,12 @@ impl Model {
         self.layout_touched = None;
     }
 
-    /// Tier 1's counter, shared by every touch above. Bumping it is what re-opens the gate; which
-    /// of [`Self::layout_touched`]'s two states the caller leaves behind is what decides how much
-    /// the re-opened resolve has to derive.
+    /// Bumps tier 1's counter, reopening the gate; `layout_touched` decides how much it derives.
     fn bump_layout_epoch(&mut self) {
         self.layout_epoch = self.layout_epoch.wrapping_add(1);
-        // `WOW_LAYOUT_TOUCH_TRACE=<n>` — name the epoch's per-frame toucher: print a backtrace
-        // for the first n touches (a mechanism probe, meaningful in a debuginfo build). Built
-        // because the SW meters read `resolve≈240 µs, solves=0` on every steady frame: the
-        // tier-1 gate is being defeated by a toucher whose writes never move a fingerprint,
-        // and 48 call sites is too many to tag by hand.
+        // `WOW_LAYOUT_TOUCH_TRACE=<secs>:<n>`: backtraces the first `n` touches after `secs`.
         use std::sync::atomic::{AtomicU32, Ordering};
         use std::sync::OnceLock;
-        // Spec `<secs>:<n>`: arm after `secs` (past UI load + settle, so the trace names the
-        // STEADY toucher, not the thousands of legitimate load-time touches), then print `n`.
         static SPEC: OnceLock<Option<(std::time::Instant, f64, AtomicU32)>> = OnceLock::new();
         let spec = SPEC.get_or_init(|| {
             let v = std::env::var("WOW_LAYOUT_TOUCH_TRACE").ok()?;
@@ -2556,9 +1623,7 @@ impl Model {
     }
 }
 
-/// `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>`'s latch — arm after `secs` (past UI load, whose thousands
-/// of legitimate births are all conservative by construction and would eat the budget), then allow
-/// `n` prints. Same spec shape as `WOW_LAYOUT_TOUCH_TRACE`, deliberately: one thing to remember.
+/// `WOW_LAYOUT_DERIVE_TRACE=<secs>:<n>`: armed after `secs`, past the UI load, then `n` prints.
 fn derive_trace_armed() -> bool {
     use std::sync::atomic::{AtomicU32, Ordering};
     use std::sync::OnceLock;
diff --git a/crates/benilla-ui/src/script/modelframe.rs b/crates/benilla-ui/src/script/modelframe.rs
index f5bd2435..d35c32ab 100644
--- a/crates/benilla-ui/src/script/modelframe.rs
+++ b/crates/benilla-ui/src/script/modelframe.rs
@@ -1,91 +1,21 @@
-//! The model-pane family's method surfaces — `Model` and `PlayerModel`, the 3D panes an addon or a
-//! FrameXML frame parks a model in.
+//! The model-pane widgets' Lua methods, `Model` and `PlayerModel`. The engine holds the scene the
+//! Lua API reads and writes ([`ModelState`]); the app draws it.
 //!
-//! **The same split as [`super::minimap`] and [`super::cooldown`], and for the same reason.** The
-//! engine core holds exactly the scene the Lua API reads and writes ([`ModelState`]); the pixels
-//! are the app renderer's job. That is the posture the `<Minimap>` and cooldown widgets already
-//! run under — a sized hole the game layer draws into.
-//!
-//! ## Two tables, chained — not one table with everything in it
-//!
-//! 1.12 registers **four** model-pane types, and each has its own Lua method table that **never
-//! repeats its base's entries**; a derived pane reaches its base's verbs through the miss leg of
-//! `vtable+0x8` (wow-re `ui/scratch/model-pane-method-tables.md`, byte-enumerated 2026-08-30):
+//! Each 1.12 model-pane class has its own method table that never repeats its base's entries; a
+//! derived pane reaches its base's methods on a miss (`__index` meta `0x7020b0`), never the
+//! reverse, so a plain `<Model>` has no `SetUnit`:
 //!
 //! ```text
 //! CSimpleFrame 0x778590
-//! └─ CSimpleModel          0x76f870   table 0x878948 (23)   <Model>          ← built here
-//!    └─ CGCharacterModelBase 0x506260  table 0x84f1fc (3)   <PlayerModel>    ← built here
-//!       ├─ DressUpModelFrame 0x5050d0  table 0x84f190 (3)   <DressUpModel>   ← `dressup` (1969)
-//!       └─ TabardModel       0x503bd0  table 0x84ee40 (10)  <TabardModel>    ← `tabard` (1977)
+//! └─ CSimpleModel          0x76f870   table 0x878948 (23)   <Model>          ← here
+//!    └─ CGCharacterModelBase 0x506260  table 0x84f1fc (3)   <PlayerModel>    ← here
+//!       ├─ DressUpModelFrame 0x5050d0  table 0x84f190 (3)   <DressUpModel>   ← `dressup`
+//!       └─ TabardModel       0x503bd0  table 0x84ee40 (10)  <TabardModel>    ← `tabard`
 //! ```
 //!
-//! Our `__index` dispatcher already walks a *slice* of registry keys per kind, so the chain is
-//! `&[REG_PLAYERMODEL_METHODS, REG_MODEL_METHODS]` and neither table duplicates the other. The
-//! direction is derived → base **only**: a plain `<Model>` does not acquire `SetUnit`.
-//!
-//! `DressUpModel` (`Undress`/`Dress`/`TryOn`) is `super::dressup` (1969) and `TabardModel` (the ten
-//! tabard verbs) `super::tabard` (1977) — each built the day its stock window came onto the chain,
-//! as 1134 §4 said they would be.
-//!
-//! ## Why this surface, in this order
-//!
-//! It is the wall four of the twenty most-installed 1.12 addons hit at once. pfUI's action-bar
-//! module builds the pet bar's autocast shine as
-//!
-//! ```lua
-//! f.autocast = CreateFrame("Model", nil, f)
-//! f.autocast:SetModel("Interface\\Buttons\\UI-AutoCastButton.mdx")
-//! f.autocast:SetSequence(0)
-//! ```
-//!
-//! and its unit frames build portraits as `CreateFrame("PlayerModel", …)` driven by `SetUnit` +
-//! `SetCamera`. pfUI is embedded in pfQuest, pfQuest-turtle and ShaguDPS as well, so one missing
-//! type stopped all four dead, each of them *after* the whole rest of the UI had built.
-//!
-//! ## Ownership is read off the registrar, never off a string scan
-//!
-//! This module published `SetUnit`, `RefreshUnit` and `SetRotation` on `Model` until 2026-08-30,
-//! on the strength of an isolated-string scan of `WoW.exe` finding one occurrence of each. **A
-//! `strings` hit cannot settle ownership** — it answers *whether a name exists*, and `SetUnit`'s
-//! single pooled string `0x84f22c` is referenced by **two** method-table entries in two different
-//! tables (`PlayerModel 0x84f1fc[0]` and `GameTooltip 0x854290`). All three are `PlayerModel`'s.
-//!
-//! The question a `strings` hit *does* settle, and the reason it was reached for: wow-re's
-//! registrar-dump tool silently missed six of the 23 widget tables — including this whole family —
-//! so the "not in wow-re's scan" half of the old header was a tooling defect, not a fidelity fact.
-//! The enumeration recipe that replaces both is §5.1 of the note above: census `(call|jmp)
-//! 0x701d80`, read the count from the registering `mov edx`, read the pairs at
-//! `base + 8*i`, and settle "which table owns method M" by counting image-wide dword references to
-//! M's name VA.
-//!
-//! ## The clock is the engine's; the pixels are the host's (decision 2007)
-//!
-//! A pane's animation state is not "a sequence index the host interprets": the reference widget
-//! owns a private `CM2Scene` whose clock its own `OnUpdate` advances, arms sequences through
-//! `0x7121a0` with an anchor the sampler re-reads, fires `OnUpdateModel` at the top of every
-//! paint and `OnAnimFinished` from the completion callback (wow-re
-//! `ui/scratch/modelframe-render-law.md` §4). All of that is Lua-observable — the shipped
-//! cooldown is nothing but those two handlers scrubbing `SetSequenceTime` — so it lives here:
-//! [`ModelState::clock_ms`] / [`ModelState::armed`], the tick's model pass, and the bindings
-//! below. What the engine does NOT have is the file: which ids it owns, how long each sequence
-//! runs, whether it loops. Those are the file's **facts** ([`crate::widget::ModelFileFacts`]),
-//! handed over by the host once the asset is resident ([`crate::script::UiScript::set_model_facts`])
-//! — the reference's own "asset ready" edge, on which the loader's Stand seed runs.
-//!
-//! ## What is deliberately NOT here
-//!
-//! Nothing of `Model`'s own 23 — the fog near/far/clear set was the last hold-out and 2027 carved
-//! it (`ClearFog 0x76f540` is `76f5c5 and [edi+0x3a4],-2`, bit 0 and nothing else, so the guess
-//! that kept it out is gone; see the install below).
-//!
-//! Absent, and correctly so: `SetCreature` and `SetCustomRace`. Neither string exists in
-//! 5875 in any form (substring scan of the whole mapped image returns 0, against a positive
-//! control of 27 hits for `Creature`) — they are later-expansion names, and publishing one would
-//! be decision 1189's error.
-//!
-//! And any interpretation of `SetLight`'s numbers — the engine core has no lighting model, so the
-//! tuple is stored verbatim rather than typed into a scene semantics nobody has verified.
+//! The pane's clock is the engine's, since Lua sees it through `OnUpdateModel`, fired at the top of
+//! every paint (`0x76d1bc`), and `OnAnimFinished` (`0x76cdc0`). What only the file knows arrives
+//! from the host once the asset is resident ([`crate::script::UiScript::set_model_facts`]).
 
 use std::sync::Arc;
 
@@ -96,21 +26,17 @@ use super::Model;
 use crate::widget::{model_key, FrameHandle, KindState, ModelFileFacts, ModelLight, ModelState};
 
 impl Model {
-    /// FrameXML units per **layout unit** — `768 · √(a²+1)` for the screen's aspect `a`
-    /// (render law §3; the `G48 = 1/√(a²+1)` root scale against the `768`-tall FrameXML
-    /// space). `SetPosition`'s space, and the unit a size-less pane's implicit rect is measured
-    /// in. `4/3` before a screen exists.
+    /// FrameXML units per layout unit, `768 · √(a²+1)` for the screen aspect `a` (`[0x832a48]`
+    /// holds `1/√(a²+1)`): the unit of `SetPosition` and of the implicit rect. `a` is 4/3 before a
+    /// screen exists.
     pub(crate) fn layout_unit(&self) -> f32 {
         let (w, h) = (self.screen.width(), self.screen.height());
         let a = if h > 0.0 && w > 0.0 { w / h } else { 4.0 / 3.0 };
         768.0 * (a * a + 1.0).sqrt()
     }
 
-    /// The **implicit rect** (decision 2015): a model pane that authored no size takes its
-    /// file's bounding-box extent, in layout units, as its size — the reference's geometry
-    /// overrides (`0x76d080`/`0x76d0d0`) answer the bbox whenever no size is authored, and its
-    /// layout consumes them like any size. Written into the layout input when the facts are
-    /// known; a pane with an authored size, or no file, or no facts yet, is left alone.
+    /// The implicit rect: a pane with no authored size takes its file's bounding-box extent, in
+    /// layout units, as the reference's geometry overrides answer it (`0x76d080`, `0x76d0d0`).
     pub(crate) fn apply_implicit_rect(&mut self, h: FrameHandle) {
         let unit = self.layout_unit();
         let extent = {
@@ -148,17 +74,15 @@ impl Model {
         }
     }
 
-    /// A size was AUTHORED on `h` (`SetWidth`/`SetHeight`, the XML `<Size>` through
-    /// them): an implicit rect no longer applies to it, for good — the reference's override
-    /// yields to any authored size.
+    /// A size was authored on `h` (`SetWidth`, `SetHeight`, or XML `<Size>` through them): the
+    /// implicit rect yields to it for good, as the reference's override does.
     pub(crate) fn note_authored_size(&mut self, h: FrameHandle) {
         if let Some(KindState::Model(m)) = self.arena.frame_mut(h).map(|f| &mut f.kind_state) {
             m.implicit_size = false;
         }
     }
 
-    /// The facts the host has handed over for `path`, or `None` — in which case the path is
-    /// queued for the host to load ([`crate::script::UiScript::model_facts_wanted`]), once.
+    /// The host's facts for `path`; on a miss the path is queued, once, for the host to load.
     pub(crate) fn model_facts_for(&mut self, path: &str) -> Option<Arc<ModelFileFacts>> {
         let key = model_key(path);
         match self.model_facts.get(&key) {
@@ -173,8 +97,7 @@ impl Model {
     }
 }
 
-/// The facts of the file `this` pane currently holds (`None` for an empty pane or a file the
-/// host has not loaded yet).
+/// The facts of the file `this` pane holds, if it holds one the host has loaded.
 fn facts_of_pane(lua: &Lua, this: &Table) -> mlua::Result<Option<Arc<ModelFileFacts>>> {
     let path = with_model(lua, this, |m| m.path.clone())?;
     Ok(path.and_then(|p| {
@@ -184,17 +107,15 @@ fn facts_of_pane(lua: &Lua, this: &Table) -> mlua::Result<Option<Arc<ModelFileFa
     }))
 }
 
-/// Registry key of the `Model` method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the `Model` method table (the MAXCSTACK discipline: a Lua-side root).
 pub(super) const REG_MODEL_METHODS: &str = "__benilla_model_methods";
 
-/// Registry key of the `PlayerModel` method table — its **own three** entries only. The other 23
-/// names a `<PlayerModel>` answers come from [`REG_MODEL_METHODS`] through the dispatcher's chain,
-/// exactly as the client's `0x506260` reaches `0x76f870` on a miss.
+/// Registry key of the `PlayerModel` table, its own three methods only: `Model`'s 23 are reached
+/// on a miss, as `0x506260` falls through to `0x76f870`.
 pub(super) const REG_PLAYERMODEL_METHODS: &str = "__benilla_playermodel_methods";
 
-/// Run `f` over a frame's Model state under one short write borrow. Errors if `this` is not a live
-/// Model (unreachable through the kind dispatcher, but the method table is a plain Lua value — a
-/// caller can fish it out and misapply it).
+/// Run `f` on a frame's Model state under one short write borrow. Errors on a receiver that is not
+/// a live Model: a method taken off the table can be called on anything.
 pub(super) fn with_model<T>(
     lua: &Lua,
     this: &Table,
@@ -212,11 +133,8 @@ pub(super) fn with_model<T>(
     }
 }
 
-/// A Lua number-ish → f32, `nil` and non-numbers → 0.0.
-///
-/// The widget's setters are all coordinates and angles, and the corpus passes them through
-/// arithmetic that can produce a nil (`C.bars[...].icon_size / 25` when the config key is absent).
-/// The reference marshals through `lua_tonumber`, which is this.
+/// `lua_tonumber`, which the reference's coordinate and angle setters read through: a number or a
+/// numeric string, anything else 0.0.
 fn num(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -231,9 +149,8 @@ fn int(v: &Value) -> i32 {
     num(v) as i32
 }
 
-/// `lua_isnumber` — a number, or a string that converts, and **nothing else**. Distinct from
-/// [`num`] on purpose: `SetLight` *raises* on a non-number where the coordinate setters coerce,
-/// so the two questions cannot share one helper.
+/// `lua_isnumber`: a number or a string that converts. Separate from [`num`] because `SetLight`
+/// raises on a non-number where the coordinate setters read 0.
 fn number(v: &Value) -> Option<f32> {
     match v {
         Value::Number(n) => Some(*n as f32),
@@ -243,36 +160,31 @@ fn number(v: &Value) -> Option<f32> {
     }
 }
 
-/// `[0x8029d4]` — the client's "is this float zero" epsilon, shared by `SetLight`'s intensity
-/// gate, `0x71b6a0`'s direction normalise and the paint's degenerate-rect test.
+/// `[0x8029d4]`, the client's float-zero epsilon: `SetLight`'s intensity gate, `0x71b6a0`'s
+/// direction normalise and the paint's degenerate-rect test.
 const FLOAT_EPS: f32 = 2.384_185_8e-7;
 
-/// `Model:SetLight`'s usage string (`0x878c00`), which the binding raises verbatim.
+/// `Model:SetLight`'s usage error. The reference's (`0x878c00`) names the receiver through `%s`
+/// and ends in `)`; this one names `Model` and drops the `)`.
 const SET_LIGHT_USAGE: &str = "Usage: Model:SetLight(enabled[, omni, dirX, dirY, dirZ, \
      ambIntensity[, ambR, ambG, ambB], dirIntensity[, dirR, dirG, dirB]]";
 
 /// What [`parse_set_light`] decided.
 enum SetLight {
-    /// A non-number where the binding requires one — `luaL_error(SET_LIGHT_USAGE)`.
+    /// A non-number where one is required: `luaL_error(SET_LIGHT_USAGE)`.
     Raise,
-    /// **Trap 1.** `enabled == 0` returns at `76e2cb` *before* the local light is copied into the
-    /// widget, so the call writes nothing at all: it neither disables a light nor edits one.
+    /// `enabled == 0` returns (`0x76e2cb`) before the copy, so the call neither disables nor
+    /// edits the light.
     NoOp,
-    /// The light to copy wholesale over the widget's (`76e777 0x76cf30`, `rep movsd 0x1b`).
+    /// The light, copied whole over the widget's (`0x76cf30` at `0x76e777`).
     Set(ModelLight),
 }
 
-/// `Model:SetLight` `0x76e1e0`'s argument walk (render law §5.3), over the arguments **after
-/// `self`** — so `a[0]` is the reference's Lua index 2.
-///
-/// The binding builds a **local** `CGLight` from `0x71b4a0` — type 1, every colour ZERO, which is
-/// not the widget ctor's white — fills it, and copies the whole thing over the widget's at the
-/// end. So an omitted colour block lands the *binding's* black, never the ctor's white.
-///
-/// **Trap 2** is the walking cursor: the ambient colour triple is read only when its intensity is
-/// nonzero **and** all three components are numbers; when either fails, the colour stays white
-/// and the cursor does *not* advance past it — so the second intensity is read at index 8 rather
-/// than 11, and `SetLight(1, 0, x, y, z, ambI, dirI)` is a legal seven-argument form.
+/// `Model:SetLight`'s argument walk (`0x76e1e0`) over the arguments after `self` (`a[0]` is Lua
+/// index 2), into a local light whose colours start black (`0x71b4a0`), not the widget's white.
+/// A colour triple is read only when its intensity is nonzero and all three are numbers; otherwise
+/// it is white and the cursor does not advance, so `SetLight(1, 0, x, y, z, ambI, dirI)` reads the
+/// second intensity at index 8, not 11.
 fn parse_set_light(a: &[Value]) -> SetLight {
     let Some(enabled) = a.first().and_then(number) else {
         return SetLight::Raise;
@@ -280,7 +192,7 @@ fn parse_set_light(a: &[Value]) -> SetLight {
     if enabled as i32 == 0 {
         return SetLight::NoOp;
     }
-    // Indices 3..=7 — omni, x, y, z, ambIntensity — are all mandatory once the light is enabled.
+    // Lua indices 3..=7 (omni, x, y, z, ambient intensity) are required once enabled.
     let mut head = [0.0f32; 5];
     for (i, slot) in head.iter_mut().enumerate() {
         match a.get(i + 1).and_then(number) {
@@ -291,15 +203,13 @@ fn parse_set_light(a: &[Value]) -> SetLight {
     let omni = head[0] as i32 != 0;
     let mut vector = [head[1], head[2], head[3]];
     if !omni {
-        // `0x71b6a0` normalises a DIRECTION on write (`71b6c5`-`71b705`); the position setter
-        // `0x71b650` stores raw.
+        // A direction is normalised on write (`0x71b6a0`); a position is stored raw (`0x71b650`).
         let len = (vector[0] * vector[0] + vector[1] * vector[1] + vector[2] * vector[2]).sqrt();
         if len > FLOAT_EPS {
             vector = vector.map(|v| v / len);
         }
     }
-    // The colour blocks: each packed to 8 bits per channel and unpacked again (`0x76f900`), so a
-    // Set→Get round trip is lossy exactly the way `SetFogColor`'s is.
+    // Each colour is packed to 8 bits a channel and back (`0x76f900`), so a round trip is lossy.
     let quantize = |v: f32| ((v.clamp(0.0, 1.0) * 255.0).round()) / 255.0;
     let block = |at: usize| -> Option<[f32; 3]> {
         let c: Vec<f32> = (at..at + 3)
@@ -328,10 +238,8 @@ fn parse_set_light(a: &[Value]) -> SetLight {
     SetLight::Set(light)
 }
 
-/// **Shape A's gate** (decision 1717's taxonomy, for a *string* position): the client's
-/// `lua_isstring` accepts tags 3|4 — a string **or a number** — and nothing else. A number is
-/// rendered to decimal text and used as the path, which is why this coerces rather than matching
-/// `Value::String` alone.
+/// A string argument as `lua_isstring` gates it: a string or a number (tags 3 and 4), the number
+/// rendered as decimal text.
 fn string_arg(v: &Value) -> Option<std::borrow::Cow<'_, str>> {
     match v {
         Value::String(s) => s
@@ -344,8 +252,7 @@ fn string_arg(v: &Value) -> Option<std::borrow::Cow<'_, str>> {
     }
 }
 
-/// The client's own `Usage:` error, with the receiver's name interpolated the way it interpolates
-/// it — `GetName()`, or `<unnamed>` when the widget has none (`0x84c7f0`).
+/// The client's `Usage:` error, naming the receiver by `GetName()` or `<unnamed>` (`0x84c7f0`).
 fn usage(lua: &Lua, this: &Table, call: &str) -> mlua::Error {
     let name = this
         .get::<mlua::Function>("GetName")
@@ -362,39 +269,27 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     // ── Content: the model, and clearing ────────────────────────────────────────────────────
     //
-    // `SetModel` and `PlayerModel:SetUnit` are the two ways a pane gets content and they are
-    // alternatives, not layers: setting one clears the other, so `GetModel` after a `SetUnit`
-    // cannot answer a stale path from three frames ago. Only the `SetModel` arm is a `Model` verb —
-    // the unit arm is `PlayerModel`'s (`playermodel_install` below), which is why the paper-doll
-    // and dress-up panes are `<PlayerModel>`s and every corpus `<Model>` drives the path arm.
-    // **`SetModel(nil)` RAISES. It is not a clear** — `ClearModel` is the clear, and it is a
-    // separate entry in the same table. This binding said the opposite until 2026-08-30 ("the
-    // documented clear, and how the corpus writes 'no model'"), which was invented: the byte read
-    // (`0x76d950`, shape A) gates the argument with `lua_isstring` and raises
-    // `Usage: %s:SetModel("file")` on nil, absent, boolean, table, function, userdata and thread.
-    // Measured before changing it — all 5 corpus call sites pass a string literal and our own
-    // FrameXML never calls it — so nothing was relying on the leniency.
+    // `SetModel` and `PlayerModel:SetUnit` are alternative contents: setting one clears the other.
+    // `SetModel` raises `Usage: %s:SetModel("file")` on anything `lua_isstring` refuses, nil
+    // included (`0x76d950`); `ClearModel` is the clear.
     //
-    // **What is NOT reproduced, deliberately:** the reference's *second* raise,
-    // `Invalid model file: %s` (`0x878b44`), for a path that does not resolve — its model load is
-    // synchronous, so it knows. We render no FrameXML models at all, so we cannot evaluate that
-    // condition, and a raise whose predicate we have to guess is worse than a named omission
-    // (1134 §4). A path that would be invalid is simply stored.
+    // Deviation: a path that does not resolve is stored, where the reference raises
+    // `Invalid model file: %s` (`0x878b44`), because the file loads asynchronously here and the
+    // call cannot know yet.
     m.set(
         "SetModel",
         lua.create_function(|lua, (this, path): (Table, Value)| {
             let path = string_arg(&path)
                 .ok_or_else(|| usage(lua, &this, "SetModel(\"file\")"))?
                 .to_string();
-            // The file's facts, if the host has handed them over — the reference's "asset
-            // resident" test (`71d5a3`), which decides whether the loader's Stand seed runs
-            // now or when the file lands ([`ModelState::set_file`]).
+            // The reference's asset-resident test (`0x71d5a3`): the loader's Stand seed runs now,
+            // or when the file lands.
             let facts = lua
                 .app_data_mut::<Model>()
                 .expect("model app_data")
                 .model_facts_for(&path);
             with_model(lua, &this, |m| m.set_file(path, facts.as_deref()))?;
-            // A size-less pane takes the file's rect the moment the file is known (2015).
+            // A size-less pane takes the file's rect as soon as the file is known.
             let h = frame_handle_of(lua, &this)?;
             lua.app_data_mut::<Model>()
                 .expect("model app_data")
@@ -410,14 +305,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "ClearModel",
         lua.create_function(|lua, this: Table| with_model(lua, &this, ModelState::clear_file))?,
     )?;
-    // ── Animation (decision 2007) ───────────────────────────────────────────────────────────
+    // ── Animation ───────────────────────────────────────────────────────────
     //
-    // Both verbs are the same arm, `0x7121a0(model, -1, id, 0, ms, 1.0f, 0, 1)` — `SetSequence`
-    // with `ms = 0` (`0x76dec0` → `0x76cf50`), `SetSequenceTime` with the caller's `ms`
-    // (`0x76dfc0` → `0x76cf80`). The arm interrupts whatever plays, resolves the id through the
-    // file's `animationLookup`, and bakes the anchor `cursor_lo = sceneClock − trunc(ms)` that
-    // the sampler re-reads every frame (render law §4.2). The id is an `AnimationData` id, not a
-    // file slot; one the file does not own stops the playing track and arms nothing.
+    // Both verbs are one arm, `0x7121a0(model, -1, id, 0, ms, 1.0f, 0, 1)`: `SetSequence` with
+    // `ms = 0` (`0x76dec0` → `0x76cf50`), `SetSequenceTime` with the caller's (`0x76dfc0` →
+    // `0x76cf80`). It anchors the play head at `clock − trunc(ms)`, re-read every frame
+    // (`0x71273d`). The id is an `AnimationData` id, not a file slot.
     m.set(
         "SetSequence",
         lua.create_function(|lua, (this, seq): (Table, Value)| {
@@ -437,9 +330,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     // ── The pane's view: yaw, scale, camera, position ───────────────────────────────────────
     //
-    // `SetFacing` is `Model`'s yaw setter (`0x878948[4]` -> `0x76dce0`, writing `+0x39c`).
-    // `SetRotation` writes THE SAME FIELD but is `PlayerModel`'s, not a second name here — see
-    // `playermodel_install`. A `<Model>` that wants its pane turned calls this one.
+    // `SetFacing` (`0x878948[4]` → `0x76dce0`) writes the yaw at `+0x39c`, the field
+    // `PlayerModel:SetRotation` also writes.
     m.set(
         "SetFacing",
         lua.create_function(|lua, (this, rad): (Table, Value)| {
@@ -462,10 +354,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "GetModelScale",
         lua.create_function(|lua, this: Table| with_model(lua, &this, |m| m.scale))?,
     )?;
-    // `SetCamera(n)` = `0x76e0e0` -> `0x76cec0`: select the file's camera by **RAW table index**
-    // (`cameraLookup` is not on this path). With the file's facts in hand the index is resolved
-    // now — an index past the table's count installs the NULL camera, which is the orthographic
-    // leg; without them it is deferred, and the pane draws nothing until it resolves.
+    // `SetCamera(n)` (`0x76e0e0` → `0x76cec0`) picks a camera by raw table index, not through
+    // `cameraLookup`; past the table it installs the NULL (orthographic) camera, and until the
+    // facts arrive the pane draws nothing.
     m.set(
         "SetCamera",
         lua.create_function(|lua, (this, c): (Table, Value)| {
@@ -490,9 +381,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The scene: light and fog ────────────────────────────────────────────────────────────
-    //
-    // Typed since decision 2027, off the render law's §5.1-§5.4: the widget's embedded `CGLight`
-    // and the four fog fields, with `SetLight`'s argument walk and both of its traps.
     m.set(
         "SetLight",
         lua.create_function(|lua, args: MultiValue| {
@@ -520,9 +408,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::Number(f64::from(l.vector[1])),
                 Value::Number(f64::from(l.vector[2])),
             ];
-            // Each colour block comes back as `1.0, r, g, b` when ANY component is `> 0`, and as
-            // a lone `0` otherwise (`76e91f`/`76e92f`/`76e93f je 0x76e953` -> `push 1.0`) — which
-            // is what makes the arity 7 | 10 | 13 rather than a fixed 13.
+            // A colour comes back as `1.0, r, g, b` if any component is above 0, else as a lone 0
+            // (`0x76e953`), so the arity is 7, 10 or 13.
             for c in [l.ambient, l.diffuse] {
                 if c.iter().any(|&v| v > 0.0) {
                     out.push(Value::Number(1.0));
@@ -538,16 +425,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "SetFogColor",
         lua.create_function(
             |lua, (this, r, g, b, a): (Table, Value, Value, Value, Option<Value>)| {
-                // FIVE arguments, and the fifth is the alpha — the same numeric path and the same
-                // `[0,1]` clamp as the components, not a flag. It is **guarded with a default of
-                // `1.0`** where r/g/b are read unconditionally and yield `0.0` when absent, so
-                // `SetFogColor(r, g, b)` sets alpha 1.0. Getting that backwards renders the fog
-                // invisible. Decision 1845.
+                // The fifth argument is alpha, clamped like the rest but 1.0 when absent, where an
+                // absent r, g or b reads 0.0: `SetFogColor(r, g, b)` is opaque.
                 let q = |v: f32| (v.clamp(0.0, 1.0) * 255.0).round() as u32;
                 let a = a.as_ref().map_or(1.0, num);
                 let packed = (q(a) << 24) | (q(num(&r)) << 16) | (q(num(&g)) << 8) | q(num(&b));
-                // `76f059 or [edi+0x3a4],1` — setting the colour ARMS the fog. That is the only
-                // arming verb (with the XML `<FogColor>` child); there is no `SetFogEnabled`.
+                // Setting the colour arms the fog (`0x76f059`), the only verb that does.
                 with_model(lua, &this, |m| {
                     m.fog_color = packed;
                     m.fog = true;
@@ -558,17 +441,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "GetFogColor",
         lua.create_function(|lua, this: Table| {
-            // FOUR values, always — the packed dword unpacked. Never set reads `1, 1, 1, 1`,
-            // because the `CSimpleModel` ctor's terminal write is `0xffffffff` (decision 1845).
+            // Always four values; never set reads `1, 1, 1, 1`, the ctor's `0xffffffff`.
             let packed = with_model(lua, &this, |m| m.fog_color)?;
             let ch = |shift: u32| f64::from((packed >> shift) & 0xff) / 255.0;
             Ok((ch(16), ch(8), ch(0), ch(24)))
         })?,
     )?;
 
-    // `SetFogNear 0x76f1e0` / `SetFogFar 0x76f390` store the number RAW — no clamp, no ordering
-    // check (`76f282`/`76f432 fstp`); the `≥ 0` clamp exists only on the XML attribute path. The
-    // getters read the same fields back. Nothing here arms the fog.
+    // `SetFogNear` (`0x76f1e0`) and `SetFogFar` (`0x76f390`) store raw, with no clamp or order
+    // check (the `≥ 0` clamp is XML-only), and do not arm the fog.
     m.set(
         "SetFogNear",
         lua.create_function(|lua, (this, v): (Table, Value)| {
@@ -591,49 +472,26 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "GetFogFar",
         lua.create_function(|lua, this: Table| with_model(lua, &this, |m| m.fog_far))?,
     )?;
-    // `ClearFog 0x76f540`: `76f5c5 and [edi+0x3a4],-2` — **bit 0 and nothing else**. The colour,
-    // the near and the far all survive, so a later `SetFogColor` re-arms the same ramp. A clear
-    // that also reset them would read as knowledge and be wrong.
+    // `ClearFog` (`0x76f540`) clears the armed bit alone (`0x76f5c5`): colour, near and far stay.
     m.set(
         "ClearFog",
         lua.create_function(|lua, this: Table| with_model(lua, &this, |m| m.fog = false))?,
     )?;
 
-    // ── The two verbs that touch no pane state ──────────────────────────────────────────────
+    // ── AdvanceTime and ReplaceIconTexture ─────────────────────────────────────────────────
 
-    // `AdvanceTime()` — `0x878948[14]` -> `0x76eca0`. **It does nothing, and that is the verified
-    // behaviour, not a stub.** The function takes no Lua argument (no `lua_gettop`, no `tonumber`,
-    // no `tostring` anywhere in `[0x76eca0, 0x76ed65)`), returns no value, and its one reachable
-    // call is `0x76cfb0`, whose entire body is `mov eax,1; ret`. It writes no `CSimpleModel` field
-    // and no global. So there is no clock to advance here and no omission to name: a receiver
-    // check and zero returns IS the reference.
-    //
-    // Present because the shipped chain calls it three times — `Cooldown.lua`, and the glue
-    // character screens' `<OnUpdateModel>` on `<ModelFFX>`, which inherits this very table — and
-    // an addon that hooks one of those will call it too.
+    // `AdvanceTime()` (`0x878948[14]` → `0x76eca0`) does nothing: it reads no argument, returns
+    // nothing, writes no field, and its one call, `0x76cfb0`, is `mov eax,1; ret`.
     m.set(
         "AdvanceTime",
         lua.create_function(|lua, this: Table| with_model(lua, &this, |_| ()))?,
     )?;
 
-    // `ReplaceIconTexture(path)` — `0x878948[15]` -> `0x76ed70`. **A material swap, not a content
-    // setter**: `0x76cfe0(0xe, path)` -> `0x710ec0` replaces the refcounted handle in
-    // `[CM2Model+0xa4][i]` for every M2 texture whose `type == 14`, plus the same-typed slots on
-    // the ribbon (`0x7b7950`) and particle (`0x7b4d20`) emitters. It sets no pane content, clears
-    // no unit, and stores nothing on the `0x3dc`-byte widget — the override lives on the CM2Model
-    // and dies with it when `SetModel`/`ClearModel` releases the instance.
-    //
-    // The reference's two "not ready" cases behave OPPOSITELY: with a `CM2Model` present but its
-    // data not resident the call is queued on `[cm2+0x3c]` and replayed; with **no CM2Model at
-    // all** (`[widget+0x318] == 0`) it is **dropped and never replayed**. Since decision 2007 a
-    // pane with a file has an instance the host renders, so the override is STORED on the pane
-    // (`ModelState::icon`, the queued-and-replayed case — the host applies it whenever the file
-    // is resident) and a pane with no file drops it, as the client does. The stock
-    // `MainMenuBarBagButtons.lua` is the caller: `ItemAnim_OnEvent` puts the pushed item's icon
-    // on `ForcedBackpackItem.mdx`, whose one batch carries no texture of its own.
-    //
-    // The argument gate is shape A: `lua_isstring` (tags 3|4) then `lua_tostring`, raising
-    // `Usage: %s:ReplaceIconTexture("texture")` on anything else.
+    // `ReplaceIconTexture(path)` (`0x878948[15]` → `0x76ed70`): `0x76cfe0(0xe, path)` → `0x710ec0`
+    // retextures every type-14 texture of the model instance and of its ribbon (`0x7b7950`) and
+    // particle (`0x7b4d20`) emitters, so `SetModel` and `ClearModel` drop it with the instance.
+    // With no instance (`[widget+0x318] == 0`) the call is dropped; with one not yet resident it is
+    // replayed on load, so the pane stores the override for the host to apply.
     m.set(
         "ReplaceIconTexture",
         lua.create_function(|lua, (this, path): (Table, Value)| {
@@ -653,14 +511,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     playermodel_install(lua)
 }
 
-/// `PlayerModel`'s **own three** verbs (table `0x84f1fc`) — nothing else. Everything a
-/// `<PlayerModel>` else answers is `Model`'s, reached through the dispatcher's chain.
+/// `PlayerModel`'s own three methods (table `0x84f1fc`); the rest are `Model`'s, reached on a miss.
 fn playermodel_install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // `SetUnit(unit)` — `0x84f1fc[0]` -> `0x505d70`. The pane's other content arm, and `SetModel`'s
-    // alternative: each clears the other, so `GetModel` after a `SetUnit` cannot answer a stale
-    // path. Ours stores the unit TOKEN and resolves it at render.
+    // `SetUnit(unit)` (`0x84f1fc[0]` → `0x505d70`) clears the `SetModel` path; the unit token is
+    // resolved at render.
     m.set(
         "SetUnit",
         lua.create_function(|lua, (this, unit): (Table, Value)| {
@@ -672,40 +528,27 @@ fn playermodel_install(lua: &Lua) -> mlua::Result<()> {
                 m.unit = unit;
                 m.path = None;
             })?;
-            // On the dressing room's pane the same call rebuilds the model from the unit — the
-            // reference's `0x5059a0` duplicates the live model, substitutions and all gone — which
-            // is app state here (`super::dressup`, 1969).
+            // A dress-up pane rebuilds from the unit's live model, dropping try-ons (`0x5059a0`).
             super::dressup::redress_if_dressup(lua, &this)
         })?,
     )?;
 
-    // `RefreshUnit()` — `0x84f1fc[1]` -> `0x505e40`. Re-reads the unit the pane already shows; for
-    // us a no-op with a live receiver check, because the pane holds the TOKEN and resolves it at
-    // render, so there is no cached appearance here to invalidate. Present because the reference's
-    // own `DressUpFrame`/`PaperDollFrame` call it (3 sites) and addons that hook them will too.
+    // `RefreshUnit()` (`0x84f1fc[1]` → `0x505e40`) re-reads the pane's unit; the token already
+    // resolves at render, so only a dress-up pane has work to do.
     m.set(
         "RefreshUnit",
         lua.create_function(|lua, this: Table| {
             with_model(lua, &this, |_| ())?;
-            super::dressup::redress_if_dressup(lua, &this) // the same worker as SetUnit's (§1)
+            // The same worker as `SetUnit`'s (`0x505b50`).
+            super::dressup::redress_if_dressup(lua, &this)
         })?,
     )?;
 
-    // `SetRotation(rad)` — `0x84f1fc[2]` -> the Lua glue `0x505f00` -> the worker `0x505bb0`, whose
-    // final instruction is `0x505c44 mov [esi+0x39c], eax`: **the same yaw field `SetFacing`
-    // writes**, so the Lua-observable effect of the two verbs is identical and `GetFacing` reads
-    // either back. That equality is the whole reason this can be one line.
-    //
-    // What `0x505bb0` does BESIDES the yaw write is deliberately not modeled, and is worth naming
-    // because it is real: it picks a turn animation from the sign of the change (`0xc`
-    // ShuffleRight when the current facing is **<** the argument, `0xb` ShuffleLeft when **>**,
-    // `0` Stand on equality or NaN — the mapping wow-re CORRECTED on 2026-08-23 after publishing
-    // it inverted), plays it unless that id is already armed on bone slot 0, and then
-    // UNCONDITIONALLY sets `[+0x3e8] = 1` and `[+0x3ec] = now_ms + 100` — a 100 ms turn hold that
-    // the per-paint `0x505c50` expires. Every one of those is invisible to Lua (no getter reads
-    // them). The app's `<Model>` renderer (`benilla-app` `ui_models`, 2013/2019/2027) draws its
-    // pane off the file's own clock and does not model a turn hold, so storing the pair here
-    // would be state nobody writes and nobody reads. The addresses are the pin if it ever does.
+    // `SetRotation(rad)` (`0x84f1fc[2]` → `0x505f00` → `0x505bb0`) writes the yaw `SetFacing`
+    // writes (`0x505c44`). Not built: the reference also plays a turn animation, ShuffleRight
+    // (`0xc`) when the facing grows, ShuffleLeft (`0xb`) when it shrinks, else Stand (0), unless
+    // already armed on bone slot 0, and holds the turn 100 ms (`[+0x3e8]`, `[+0x3ec]`, expired by
+    // `0x505c50`).
     m.set(
         "SetRotation",
         lua.create_function(|lua, (this, rad): (Table, Value)| {
@@ -718,22 +561,8 @@ fn playermodel_install(lua: &Lua) -> mlua::Result<()> {
 }
 
 impl crate::script::UiScript {
-    /// A named model pane's scene state, or `None` if no live frame carries that name as a
-    /// `Model`/`PlayerModel`.
-    ///
-    /// **The read side of the pane, for a host that draws it.** The app keeps one off-screen body
-    /// bake per window (this module's header: the scene is ours, the pixels are the host's), and
-    /// every frame it has to ask the pane the reference drives which way it is turned. Before
-    /// decision 1751 that came from benilla-named globals a file of ours called
-    /// (`BenillaPaperDollModel_SetFacing` and its four siblings, one scalar per window on
-    /// [`Model`]); the stock FrameXML instead calls
-    /// `Model_OnLoad`/`Model_RotateLeft`/`Model_RotateRight`/`Model_OnUpdate`, which write
-    /// `PlayerModel:SetRotation` — i.e. this state, on the pane itself. So the host reads the pane.
-    ///
-    /// By NAME rather than by handle because that is what the host knows: the character sheet's
-    /// bake belongs to `CharacterModelFrame`, and since 1751 that name is the reference's own. A
-    /// linear scan, because a name index would be a second store to keep true and a loaded
-    /// interface holds single-digit model panes.
+    /// The scene state of the model pane named `name`, for the host that draws it, which knows the
+    /// pane by its stock name (`CharacterModelFrame`).
     pub fn model_pane(&self, name: &str) -> Option<ModelState> {
         self.model_ref()
             .arena
@@ -744,30 +573,22 @@ impl crate::script::UiScript {
             })
     }
 
-    /// A named model pane's yaw in radians — [`Self::model_pane`]'s one hot field, and `0.0` for a
-    /// pane that does not exist yet (its window's file not loaded, or its `OnLoad` not run).
-    ///
-    /// `0.0` rather than an `Option` because every caller is a per-frame booth mirror whose only
-    /// other answer would be "keep the last one", and a pane that has not loaded has no last one.
-    /// The reference's own default, 0.61, is authored in `Model_OnLoad`, so a real pane only reads
-    /// 0.0 before it loads.
+    /// A named pane's yaw in radians, 0.0 before the pane exists; the stock `Model_OnLoad` sets
+    /// 0.61 (`UIParent.lua:1422`).
     pub fn model_pane_facing(&self, name: &str) -> f32 {
         self.model_pane(name).map_or(0.0, |m| m.facing)
     }
 
-    /// The host hands over what it knows about a model **file** (decision 2007): its sequences
-    /// and bounds, read off the loaded asset. Every pane holding that file then runs the
-    /// reference's residency completion — the loader's Stand seed for a pane that was waiting,
-    /// the ownership check for an arm that was queued ([`ModelState::seed_from_facts`]) — and
-    /// its clock starts answering ([`ModelState::play_head`]).
+    /// The host's facts for a model file, read off the loaded asset: every pane holding it runs the
+    /// reference's load completion ([`ModelState::seed_from_facts`]) and takes its implicit rect.
     pub fn set_model_facts(&mut self, path: &str, facts: ModelFileFacts) {
         let key = model_key(path);
         let facts = Arc::new(facts);
         let mut model = self.model_mut();
         model.model_facts.insert(key.clone(), facts.clone());
         model.model_facts_wanted.retain(|k| *k != key);
-        // A one-off walk per file, not per frame: the panes that named this file are the
-        // waiters the reference links on the streaming drain (`0x71d640`).
+        // The panes holding this file: the waiters the reference links on its streaming drain
+        // (`0x71d640`).
         let handles: Vec<_> = model
             .arena
             .iter_frames()
@@ -786,8 +607,7 @@ impl crate::script::UiScript {
         }
     }
 
-    /// The screen's aspect moved: every implicit rect is measured in layout units, which scale
-    /// with `√(a²+1)`, so each one is re-derived (decision 2015). An authored size is untouched.
+    /// The screen aspect changed: re-derive every implicit rect, whose unit scales with `√(a²+1)`.
     pub(crate) fn reapply_implicit_rects(&mut self) {
         let mut model = self.model_mut();
         let panes: Vec<FrameHandle> = model
@@ -806,23 +626,19 @@ impl crate::script::UiScript {
         }
     }
 
-    /// The model files panes have named that no facts have arrived for — drained: the host
-    /// loads each once and answers through [`Self::set_model_facts`]. Keys are
-    /// [`crate::widget::model_key`]s (case-folded, `/`-separated, no extension).
+    /// Drain the model files panes named with no facts yet, as [`crate::widget::model_key`]s; the
+    /// host loads each once and answers through [`Self::set_model_facts`].
     pub fn model_facts_wanted(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().model_facts_wanted)
     }
 
-    /// Does the engine hold facts for `path`'s file — the host's "already answered" test.
+    /// Whether the engine holds facts for `path`'s file.
     pub fn has_model_facts(&self, path: &str) -> bool {
         self.model_ref().model_facts.contains_key(&model_key(path))
     }
 
-    /// **The paint list**: every effectively-visible model pane holding a file whose facts the
-    /// engine has — with its scene clock and, when something is armed, its play head. The host's
-    /// renderer reads this once per frame (decision 2008) instead of the extract carrying a
-    /// cursor that moves every tick (`QuadContent::ModelPane`'s doc says why). Handle order —
-    /// the arena's registry order, stable across frames.
+    /// The paint list: every visible model pane whose file's facts are known, with its clock and
+    /// play head, in the arena's registry order, which is stable across frames.
     pub fn visible_model_panes(&self) -> Vec<ModelPaneFrame> {
         let model = self.model_ref();
         model
@@ -839,10 +655,8 @@ impl crate::script::UiScript {
                 };
                 let path = m.path.as_deref()?;
                 let facts = model.model_facts.get(&model_key(path))?;
-                // The reference's draw gate (`76d5f0 cmp [this+0x320],-1 ; jne`): a pane whose
-                // camera question is still open paints NOTHING — not the model, not its
-                // `OnUpdateModel`. Reachable from Lua by `SetCamera(n)` on a pane whose file has
-                // not landed yet (decision 2027).
+                // A pane whose camera is still pending paints nothing, not even its
+                // `OnUpdateModel` (`0x76d5f0`).
                 if m.camera_pending.is_some() {
                     return None;
                 }
@@ -856,15 +670,12 @@ impl crate::script::UiScript {
     }
 }
 
-/// One visible model pane as the host's renderer sees it this frame —
-/// [`UiScript::visible_model_panes`]'s row.
+/// One row of [`UiScript::visible_model_panes`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ModelPaneFrame {
     pub handle: crate::widget::FrameHandle,
-    /// The pane's private scene clock, ms ([`ModelState::clock_ms`]) — the global-sequence
-    /// clock of everything the pane draws.
+    /// The pane's scene clock in ms, which also drives the file's global sequences.
     pub clock_ms: u64,
-    /// Where the armed sequence stands, or `None` while nothing is armed (the file draws at its
-    /// rest pose).
+    /// The armed sequence's play head; `None` draws the rest pose.
     pub play: Option<crate::widget::ModelPlayHead>,
 }
diff --git a/crates/benilla-ui/src/script/nameplate.rs b/crates/benilla-ui/src/script/nameplate.rs
index 78eba700..de8eb154 100644
--- a/crates/benilla-ui/src/script/nameplate.rs
+++ b/crates/benilla-ui/src/script/nameplate.rs
@@ -1,74 +1,9 @@
-//! **The nameplate widgets** — `CGNamePlateFrame` as the frame-system object it actually is
-//! (decision 2148; wow-re `system/ui/scratch/nameplate-lua-surface.md`, §5 eight-worker round +
-//! orchestrator byte arbitration 2026-09-09, benilla dispatch).
-//!
-//! benilla drew V-plates for a year as quads pushed straight into the UI pass, which made them
-//! invisible to Lua: a live run's `WorldFrame:GetChildren()` returned the two named FrameXML
-//! frames and nothing else, and every 1.12 nameplate addon — all of which find plates by walking
-//! exactly that list — found nothing to work with. The reference does the opposite, and this
-//! module is that difference closed.
-//!
-//! ## What the reference builds, byte for byte
-//!
-//! The plate is a `CSimpleButton` subclass (ctor `0x7cb250`, `…\Ui\NamePlateFrame.cpp`, vtable
-//! `0x81de50`, size `0x518`) whose **base constructor parents it to the `CGWorldFrame` singleton**
-//! `ds:0xb4b2bc` (`0x7786a3` → `0x769318` → `SetParent 0x76ab10`, tail-appending at `0x76abdb`) —
-//! so it is a real member of `[worldframe+0x300]`, returned by `GetChildren` and counted by
-//! `GetNumChildren`, inheriting strata **0 (WORLD)** and taking level **1**.
-//!
-//! - **Identity:** `GetObjectType()` = `"Button"`, `IsObjectType` accepts Button/Frame/Region, and
-//!   `GetName()` is **nil** — `[this+0x98]` is zeroed at `0x76c50b` and only XML `name=` ever
-//!   writes it. Anonymity is load-bearing: `_Nameplates` and pfUI both reject a *named*
-//!   `WorldFrame` child.
-//! - **Six regions, in creation order**: Border `0x7cb2c2`, Glow `0x7cb361`, Name `0x7cb3d7`,
-//!   Level `0x7cb479`, Skull `0x7cb512`, RaidIcon `0x7cb5b4`.
-//! - **One child**, the health bar (`GetObjectType()` = `"StatusBar"`), whose own single region is
-//!   the BarFill texture `GetStatusBarTexture()` returns. **No cast bar exists in 1.12** — a second
-//!   child would be blanked by pfUI, which destructures `healthbar, castbar`.
-//! - **Real anchors.** The ctor writes them through `0x767c70` — the *same* primitive and the same
-//!   `[layoutObj + 4 + 4·point]` storage the Lua `SetPoint` binding ends in — so `GetPoint`,
-//!   `GetLeft` and `GetWidth` answer truthfully. Name = `("BOTTOM", plate, "CENTER", 0, 0)`
-//!   (`0x7cb456`), Level = `("CENTER", plate, "BOTTOMRIGHT", …)` (`0x7cb7f5`); `_Nameplates`
-//!   *validates* both pairs and rejects a plate that fails them.
-//! - **Levels, and this is the surprise:** the bar is put **below** the plate, not above it —
-//!   `0x7cb32e mov edx,[plate+0xc4]` (=1) · `0x7cb33c dec edx` · `0x7cb33e call 0x76a4f0(bar,0,0)`,
-//!   an absolute level that overrides what `SetParent` had just given it. Plate level 1, **bar
-//!   level 0**. Since the draw walk's layer loop is *outer* and its frame walk *inner* (`0x765920`:
-//!   layer counter `0x76593c`, frame walk `0x7659d0`–`0x7659f8`, `cmp eax,5` at `0x765a63`), the
-//!   whole bar frame drains before any plate layer — which is why the border's bevels cap the
-//!   fill's ends. The director pinned that look off a reference crop while `nameplate-vkey.md` §7
-//!   recorded the opposite order; the §5 round settled it in the director's favour and corrected
-//!   the note.
-//! - **Layers** (`GetDrawLayer 0x79a6c0`, table `0x811a80`): Border ARTWORK, Glow **HIGHLIGHT**,
-//!   Name/Level/Skull OVERLAY (the ctor re-layers Name and Level off ARTWORK at `0x7cb438`/
-//!   `0x7cb4ea`), RaidIcon ARTWORK, BarFill ARTWORK on the bar. **No sub-level exists in 5875**;
-//!   within a layer it is creation order.
-//! - **Scripts:** the engine installs none, and every C++ override tails into the base
-//!   unconditionally, so an addon's `SetScript` on OnShow/OnHide/OnUpdate/OnEnter/OnLeave/
-//!   OnMouseDown/OnMouseUp/OnClick fires. `RegisterForClicks(0x500)` = Left/Right on mouse-**up**.
-//! - **Pooling:** destroy (`0x608a10`) never unparents — it hides and pushes onto a free list, and
-//!   reuse re-runs neither the ctor nor `SetParent`. So **the child-list index is stable for the
-//!   session**, and a retired plate is still returned *and counted* (the list walk has no
-//!   visibility filter). Every corpus addon's `registry[plate]` identity map rests on that.
-//!
-//! ## The consumer contract this has to keep
-//!
-//! Four independent 1.12 addons (`_Nameplates`, `CustomNameplates`, pfUI's vanilla branch,
-//! ShaguTweaks' vanilla branch — all `## Interface: 11200`) destructure the two tuples
-//! *positionally* and identify a plate by `regions[1]:GetTexture()` being exactly
-//! `Interface\Tooltips\Nameplate-Border`. The byte-derived order and the corpus's agree element for
-//! element — an independent empirical control on a byte derivation. So the composition is not ours
-//! to choose; it is an ABI, and the tests transcribe each addon's own walk.
-//!
-//! **An addon takes the plate over**, which is the half a painter never had to respect: pfUI blanks
-//! all six regions and paints its own, sets `SetAlpha(.95)` on non-targets itself, and ShaguTweaks
-//! reparents the raid icon. So [`Plate::create`] writes the static properties (paths, fonts,
-//! layers) exactly **once**, [`Plate::lay_out`] rewrites the window-derived anchors only when the
-//! window moves, and [`Plate::drive`] writes only what actually changed this frame. The one
-//! deliberate exception is the plate's own anchor, which the reference itself re-issues every dirty
-//! frame from the seat `0x509ec0` (`ClearAllPoints` + `SetPoint`), wiping an addon anchor *on the
-//! plate* there too — which is why every corpus addon anchors its overlay **to** the plate and
-//! re-anchors the **bar**, never the plate.
+//! The nameplate widgets: the reference's `CGNamePlateFrame` (ctor `0x7cb250`), an anonymous
+//! `Button` parented to the `WorldFrame` (`0x7786a3`) at strata WORLD, level 1. Plate addons
+//! (`_Nameplates`, `CustomNameplates`, pfUI, ShaguTweaks) find it in `WorldFrame:GetChildren()`
+//! and read it positionally: six regions in creation order, then one child, the health bar (1.12
+//! has no cast bar). Addons take plates over, so static properties are written once, anchors
+//! when the window changes and state when it moves.
 
 use crate::layout::{Anchor, Point};
 use crate::order::DrawLayer;
@@ -78,34 +13,29 @@ use super::model::Model;
 use super::UiScript;
 use super::{BlendMode, FontShadow, JustifyV, RegionData, TexCoords};
 
-/// Region 1's art — and the identification test every corpus addon runs, which is why it is a
-/// constant here rather than a caller's argument.
+/// Region 1's art, and the path plate addons identify a plate by.
 pub const BORDER_TEXTURE: &str = "Interface\\Tooltips\\Nameplate-Border";
-/// Region 2's. `glow:IsShown()` is how pfUI reads *mouseover* (`nameplates.lua:601`).
+/// Region 2's art; pfUI reads mouseover from `glow:IsShown()` (`nameplates.lua:601`).
 pub const GLOW_TEXTURE: &str = "Interface\\Tooltips\\Nameplate-Glow";
-/// Region 5's — the boss / out-of-range skull (`levelicon` to pfUI, `Boss` to CustomNameplates).
+/// Region 5's art, the boss and out-of-range skull.
 pub const SKULL_TEXTURE: &str = "Interface\\TargetingFrame\\UI-TargetingFrame-Skull";
-/// Region 6's 4-column atlas.
+/// Region 6's art, a 4-column atlas.
 pub const RAID_ICON_TEXTURE: &str = "Interface\\TargetingFrame\\UI-RaidTargetingIcons";
-/// The health bar's fill — what `healthbar:GetStatusBarTexture()` hands back.
+/// The health bar's fill, which `GetStatusBarTexture()` returns.
 pub const BAR_FILL_TEXTURE: &str = "Interface\\TargetingFrame\\UI-TargetingFrame-BarFill";
-/// `NAMEPLATE_FONT` — Friz Quadrata, the plate's own face.
+/// `NAMEPLATE_FONT`: Friz Quadrata.
 pub const PLATE_FONT: &str = "Fonts\\FRIZQT__.TTF";
 
-/// The plate's frame level, and the bar's — `plate.level − 1`, absolute and clamped ≥ 0
-/// (`0x7cb32e`/`0x7cb33c`/`0x7cb33e` → `0x76a4f0`). The pair is what puts the border over the fill.
+/// The plate's level; the bar's is one less, set absolutely (`0x7cb33e` → `0x76a4f0`). The draw
+/// walks levels outermost and each level's layers inside (`0x765920`), so the whole bar draws
+/// before the border that caps it.
 const PLATE_LEVEL: u16 = 1;
 const BAR_LEVEL: u16 = 0;
 
-/// Everything about a plate's geometry that follows from the *window* rather than from the unit,
-/// in FrameXML units (the driver has already divided out the seam scale).
-///
-/// Applied to every pooled plate at once, and only when it changes — these are exactly the writes
-/// that must not happen per frame, because an addon that re-anchors the bar would otherwise have
-/// its anchor stamped over at 60 Hz.
+/// The plate geometry that follows from the window rather than the unit, in FrameXML units with
+/// the seam scale divided out. Written only when it changes, so an addon's bar anchor survives.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct PlateGeometry {
-    /// The plate frame's own size.
     pub width: f32,
     pub height: f32,
     /// The health bar, from the plate's BOTTOMLEFT.
@@ -113,74 +43,47 @@ pub struct PlateGeometry {
     pub bar_off_y: f32,
     pub bar_width: f32,
     pub bar_height: f32,
-    /// The level text / skull seat, from the plate's BOTTOMRIGHT (x is subtracted, y added).
+    /// The level text and skull seat, from the plate's BOTTOMRIGHT (x is subtracted, y added).
     pub level_off_x: f32,
     pub level_off_y: f32,
-    /// The skull's square side.
     pub skull_size: f32,
-    /// The raid icon's square side; it hangs off the plate's LEFT edge, vertically centred.
     pub raid_size: f32,
-    /// Font heights for the name and the level.
     pub name_height: f32,
     pub level_height: f32,
-    /// The plate text's drop-shadow step, in the same FrameXML units — **the driver divides the
-    /// seam out of it like everything else here**, because the director tuned it as a constant
-    /// ONE LOGICAL PIXEL (2026-07-07) and the shared text arm multiplies whatever it finds by the
-    /// seam on the way out.
-    ///
-    /// Left as a bare `1.0` unit by the widget port, it became `round(windowH/768 × uiScale)`
-    /// drawn px — 2 px from a 1152-tall window up, 3 px at 2160 — which is exactly the "chunky"
-    /// the recorded ±0.001 gx law was tuned away from, and it made the shadow the one part of a
-    /// plate that was not uiScale-blind.
+    /// The text's drop-shadow step, seam divided out like the rest: one logical pixel at any
+    /// window size, since the text path multiplies it by the seam.
     pub shadow_offset: f32,
 }
 
-/// One plate's per-frame state, as the app hands it over: everything that can move while a plate is
-/// alive. Anything that cannot is written once, at creation.
+/// One plate's per-frame state: everything that can move while the plate is alive.
 #[derive(Clone, Debug, PartialEq)]
 pub struct PlateState {
-    /// The unit this plate belongs to — its GUID, and **the plate's identity**.
-    ///
-    /// The reference binds a plate to its unit for as long as the plate lives (`[unit+0xe60]`
-    /// holds the pointer; the free list hands out a plate at create and takes it back at destroy),
-    /// and every corpus addon depends on that: pfUI caches the name, level, colour and its own
-    /// overlay ON the frame (`registry[plate]`, `nameplate.original.*`) and only refreshes what
-    /// its `OnDataChanged` says moved. Handing widget *i* to whichever unit happens to sort i-th
-    /// this frame would make every plate's cached state wrong on the frame two units swap places —
-    /// which is why the pool is keyed by this rather than indexed by the driver's sort order.
+    /// The unit's GUID and the plate's identity: a plate is bound to its unit for its life
+    /// (`[unit+0xe60]`), and addons cache per-plate state on the frame.
     pub key: u64,
-    /// Where the plate's **TOP-CENTRE** lands, in FrameXML units from the screen's bottom-left —
-    /// the reference's own seat (`nameplate-vkey.md` §8.5: the plate hangs below the point).
+    /// Where the plate's top centre lands, in FrameXML units from the screen's bottom-left; the
+    /// plate hangs below it (`0x509ec0`).
     pub top_centre: (f32, f32),
-    /// `UNIT_FIELD_HEALTH` and `UNIT_FIELD_MAXHEALTH`, **raw**: `healthbar:GetValue()` is
-    /// `[bar+0x320]` (`0x78f5d0`), not a fraction, and `GetMinMaxValues()` answers `(0, max)`.
-    /// pfUI and CustomNameplates both divide, so a fraction here would read as 1 hp out of 1.
+    /// `UNIT_FIELD_HEALTH` and `UNIT_FIELD_MAXHEALTH`, raw: `GetValue()` is the health, not a
+    /// fraction (`0x78f5d0`), and `GetMinMaxValues()` is `(0, max)`; plate addons divide.
     pub health: f32,
     pub max_health: f32,
-    /// The bar's reaction colour — the four confirmed dwords. Addons reverse-engineer the unit's
-    /// faction from `GetStatusBarColor`, so these have to be exact.
+    /// The bar's reaction colour, exact: addons read the unit's reaction from `GetStatusBarColor`.
     pub bar_colour: [f32; 3],
-    /// The unit's name.
     pub name: String,
-    /// The level number to show, or `None` when the unit has no `UNIT_FIELD_LEVEL` yet.
-    ///
-    /// **`None` is not the skull** — that is [`Self::skull`], and conflating them is what made a
-    /// unit whose level had not arrived wear a world boss's skull. The old painter kept the whole
-    /// level/skull block inside `if let Some(level)`, so no level meant neither.
+    /// The level to show, or `None` before `UNIT_FIELD_LEVEL` arrives: an empty seat, not a skull.
     pub level: Option<u32>,
-    /// Show the SKULL in the level's seat instead of a number — the boss / far-out-of-range mark.
+    /// Show the skull in the level's seat instead of a number.
     pub skull: bool,
-    /// The level text's con colour.
     pub level_colour: [f32; 3],
-    /// The raid-target mark, 0-based (`col = idx & 3`, `row = idx >> 2`), or `None`.
+    /// The raid-target mark, 0-based, or `None`.
     pub raid_icon: Option<u8>,
-    /// The plate's own alpha: **exactly 1.0 for the target**, dimmed otherwise. `GetAlpha() == 1`
-    /// is how pfUI and CustomNameplates detect the target plate — a contract, not a look.
+    /// The plate's alpha: exactly 1.0 for the target, dimmed otherwise. Addons find the target
+    /// plate by `GetAlpha() == 1`.
     pub alpha: f32,
-    /// Mouseover ∪ target: the bar's brighten.
+    /// Mouseover or target: the bar brightens.
     pub lit: bool,
-    /// The plate rect is hovered right now — the name goes yellow (`0x7cb850` OnEnter, name-only)
-    /// and the glow region is shown, which is the mouseover signal addons read.
+    /// The pointer is on the plate: the name goes yellow (`0x7cb850`) and the glow region shows.
     pub hovered: bool,
 }
 
@@ -196,85 +99,55 @@ struct Plate {
     raid: RegionHandle,
     bar: FrameHandle,
     fill: RegionHandle,
-    /// Last frame's state, so [`Plate::drive`] writes only what moved. `None` = retired.
+    /// Last frame's state, so [`Plate::drive`] writes only what moved; `None` while retired.
     last: Option<PlateState>,
-    /// **The geometry this plate's anchors were written under**, or `None` while it has never been
-    /// laid out — the fix for a plate that was born invisible.
-    ///
-    /// [`Plate::lay_out`] used to be driven by one per-frame `relayout` flag ("did the window
-    /// move?"), which is true exactly once per window size. A plate the pool grew on any LATER
-    /// frame — a unit walking into range with no free slot — therefore kept `width: 0`, `height: 0`
-    /// and no region anchors, resolved to nothing, and drew nothing for the rest of the session.
-    /// The number of plates on screen was capped at however many were up on the frame V was first
-    /// pressed. Per-plate state instead of a per-frame flag makes the condition unfalsifiable: a
-    /// plate whose anchors are not the current geometry's gets them, whatever the reason.
+    /// The geometry its anchors were written under, `None` before the first lay-out. Kept per
+    /// plate, so a plate the pool grows later is laid out too.
     laid_out: Option<PlateGeometry>,
 }
 
 impl Plate {
-    /// The unit this plate is currently bound to, or `None` while it sits in the pool.
     fn key(&self) -> Option<u64> {
         self.last.as_ref().map(|s| s.key)
     }
 }
 
-/// The plate pool — grown on demand, **never shrunk**, in creation order.
-///
-/// The reference's pool is unbounded and its free list FIFO; what matters to an addon is only that
-/// an index, once handed out, keeps meaning the same Lua object, and that a retired plate stays in
-/// the child list (hidden). pfUI and ShaguTweaks scan `initialized + 1 .. GetNumChildren()` and
-/// never reset `initialized`, so a client that reordered or compacted this list would make them
-/// miss every plate created afterwards — permanently, and silently.
+/// The plate pool, grown on demand and never shrunk or reordered: addons scan only the children
+/// past the count they last saw, so a compacted list would hide every later plate from them.
 #[derive(Debug, Default)]
 pub(crate) struct NamePlates {
     plates: Vec<Plate>,
-    /// Which pool slot each live unit holds, by [`PlateState::key`] — the reference's
-    /// `[unit+0xe60]`, from this side. A slot leaves this map only when its unit's plate is
-    /// retired, and the slot itself never moves.
+    /// Each live unit's pool slot, by [`PlateState::key`]: the reference's `[unit+0xe60]`.
     assigned: std::collections::HashMap<u64, usize>,
-    /// The reverse of the arena's own structure: which slot a frame handle is. Filled at
-    /// creation and never removed (plates are never destroyed), so the pointer boundary and the
-    /// click funnel can ask "is this frame a plate, and whose?" in one lookup.
+    /// Frame to pool slot, never removed: plates are never destroyed.
     by_frame: std::collections::HashMap<FrameHandle, usize>,
-    /// Completed clicks on plates, drained by the app each frame
-    /// ([`UiScript::take_nameplate_clicks`]).
+    /// Completed clicks, drained by [`UiScript::take_nameplate_clicks`].
     clicks: Vec<NamePlateClick>,
-    /// **The plate's own hit-test veto** — `0x7cba30`, the `+0x3c` override, set while a
-    /// ground-targeted spell is armed ([`UiScript::set_nameplate_hit_test_veto`]).
-    ///
-    /// Deliberately NOT the mouse-enabled bit: the reference has two distinct mechanisms here and
-    /// only one of them is visible from Lua. `0x60f830` (freelook) toggles input kind 2 on every
-    /// plate, so `IsMouseEnabled()` answers `false` — while `0x7cba30` refuses the *hit test*
-    /// before testing the rect and never touches the bit, so an addon asking a plate whether it
-    /// takes the mouse during ground targeting is told `true`, truthfully. Folding the two into
-    /// one flag would have been simpler here and wrong there.
+    /// The hit-test veto (`0x7cba30`). Not the mouse-enabled bit: it leaves `IsMouseEnabled()`
+    /// true, where freelook (`0x60f830`) clears the bit.
     hit_test_vetoed: bool,
-    /// The geometry every live plate is currently laid out under.
     geometry: Option<PlateGeometry>,
 }
 
 impl NamePlates {
-    /// Does the `0x7cba30` veto refuse `frame` this point? True only for a plate, and only while
-    /// the veto stands.
+    /// Whether the `0x7cba30` veto refuses `frame`: only a plate, only while the veto stands.
     pub(crate) fn vetoes(&self, frame: FrameHandle) -> bool {
         self.hit_test_vetoed && self.by_frame.contains_key(&frame)
     }
 }
 
-/// A completed click on a plate — what the reference's own `CGNamePlateFrame` click slot
-/// (`0x7cb910`) turns into a selection.
+/// A completed click on a plate. The reference's click slot (`0x7cb910`) selects the unit on the
+/// left button (`0x4925d0`) and selects and interacts on the right (`0x492820`).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct NamePlateClick {
     /// The unit whose plate was clicked ([`PlateState::key`]).
     pub key: u64,
-    /// `"LeftButton"` / `"RightButton"` — the plate registers for both, on mouse-UP only
-    /// (`RegisterForClicks(0x500)` at `0x7cb637`).
+    /// `"LeftButton"` or `"RightButton"`.
     pub button: String,
 }
 
-/// What a sync produced that has to be fired **outside** the model borrow: the frames whose
-/// effective visibility flipped (their `OnShow`/`OnHide`), and the bars whose value moved (their
-/// `OnValueChanged`, which pfUI hooks — `nameplates.lua:393` — and reads `this:GetParent()` in).
+/// What a sync fires outside the model borrow: `OnShow`/`OnHide` for frames whose visibility
+/// flipped and `OnValueChanged` for moved bars (pfUI hooks it, `nameplates.lua:393`).
 #[derive(Default)]
 struct SyncEffects {
     visibility: Vec<FrameHandle>,
@@ -282,17 +155,13 @@ struct SyncEffects {
 }
 
 impl UiScript {
-    /// Drive the plate pool from the app's per-frame verdict: `states[i]` is the i-th **shown**
-    /// plate, and every pooled plate past `states.len()` is retired (hidden, never destroyed).
-    ///
-    /// `geometry` is the window-derived half; passing an unchanged value costs nothing.
+    /// Drive the pool from the app's per-frame states, one per shown plate; a unit with no state
+    /// has its plate retired (hidden, never destroyed). An unchanged `geometry` costs nothing.
     pub fn sync_nameplates(&mut self, geometry: PlateGeometry, states: &[PlateState]) {
         let lua = self.lua();
         let effects = {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // No WorldFrame, no plates: a VM with no interface loaded (a bare test app, the addon
-            // harness) has nowhere to parent them, and inventing a root would put plates somewhere
-            // an addon's walk could never find them anyway.
+            // No WorldFrame (no interface loaded), no plates: no addon walks an invented root.
             let Some(world) = model.arena.lookup("WorldFrame") else {
                 return;
             };
@@ -304,15 +173,8 @@ impl UiScript {
         }
     }
 
-    /// **The unit whose plate the pointer is inside**, or `None` — the reference's plate OnEnter
-    /// (`0x7cb850`) publishing the mouseover global `[0xb4e2c8]`, read from the app's side instead
-    /// of pushed.
-    ///
-    /// The app needs this because a plate is real UI here: with the plate mouse-enabled, the UI
-    /// pointer pass owns the cursor over it and `target::hover`'s world pick correctly stands
-    /// down — so the mouseover has to come from the frame that took it. Exactly the hovered frame,
-    /// never an ancestor: an addon frame parented to a plate takes the hover in the reference too,
-    /// and its OnEnter is the one that fires.
+    /// The unit whose plate is the hovered frame, the mouseover its OnEnter publishes (`0x7cb850`
+    /// → `0x492890`, `[0xb4e2c8]`); an addon frame on a plate takes the hover from it.
     pub fn hovered_nameplate(&self) -> Option<u64> {
         let lua = self.lua();
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -321,21 +183,15 @@ impl UiScript {
         model.nameplates.plates.get(slot)?.key()
     }
 
-    /// Drain the completed plate clicks — the app turns each into a selection, which is what the
-    /// reference's own click slot does. Both a physical click and Lua's `plate:Click("LeftButton")`
-    /// arrive here, because both go through the one click funnel.
+    /// Drain the completed plate clicks, physical or `plate:Click()`, for the app to select from.
     pub fn take_nameplate_clicks(&mut self) -> Vec<NamePlateClick> {
         let lua = self.lua();
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
         std::mem::take(&mut model.nameplates.clicks)
     }
 
-    /// **The mouselook toggle** (`0x60f830`): entering camera freelook disables mouse input on
-    /// every plate, leaving re-enables it — the reference walks its own intrusive plate list at
-    /// `ds:0xc4d92c` doing exactly this, called from `0x483e80` (enter) and `0x483e70` (leave).
-    ///
-    /// Without it a right-drag that starts over a plate would be a plate click instead of a camera
-    /// turn, and the plates would keep taking a pointer that is no longer on screen.
+    /// The freelook toggle (`0x60f830`): entering camera freelook disables mouse input on every
+    /// plate and leaving re-enables it (called from `0x483e80` and `0x483e70`).
     pub fn set_nameplate_mouse(&mut self, enabled: bool) {
         let lua = self.lua();
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -345,32 +201,18 @@ impl UiScript {
         }
     }
 
-    /// **The plate hit-test veto** (`0x7cba30`, the plate's `+0x3c` override — the one of the six
-    /// that can refuse *before* testing the rect): while a ground-targeted spell is armed the
-    /// plates stop taking the mouse and the click falls through to the `WorldFrame`, so the reticle
-    /// can be placed through a plate.
-    ///
-    /// The reference's predicate is `IsTargeting() && TargetingWantsLocation(flag & 0x60) &&
-    /// !0x6e6180()`. The caller supplies the first two verbatim — benilla's `TargetingWants::
-    /// Location` **is** that `& 0x60` mask. The third is another mask predicate over the same
-    /// pending-spell word (`& 0x878e`, per wow-re `item-target-cursor-and-dropitemonunit.md`) whose
-    /// meaning is not settled; a word that reaches our targeting cursor with location bits is a
-    /// pure ground target (the resolver binds or refuses a unit word before then), so it is left
-    /// unmodelled rather than guessed at.
+    /// The plate hit-test veto (`0x7cba30`): while a ground-targeted spell is armed, clicks fall
+    /// through plates to the `WorldFrame`. The caller supplies the first two terms of the
+    /// reference's `IsTargeting() && (flag & 0x60) && !0x6e6180()`; the third, a test of the same
+    /// word against `0x878e` whose meaning is unsettled, is not applied.
     pub fn set_nameplate_hit_test_veto(&mut self, vetoed: bool) {
         let lua = self.lua();
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
         model.nameplates.hit_test_vetoed = vetoed;
     }
 
-    /// **Retire every live plate** — hide them all and return them to the pool, without touching
-    /// the geometry they are laid out under.
-    ///
-    /// The app's every early return owes this: a painter that stopped drawing left no plates
-    /// behind, but widgets stay until something hides them, so a V press that turns plates off, a
-    /// frame with no camera, or a world exit would otherwise leave the last frame's plates standing
-    /// on screen. It is `0x608a10` applied to the whole active list, which is what the reference
-    /// does when the master toggle clears.
+    /// Retire every live plate (`0x608a10` over the active list, as when the master toggle
+    /// clears); the app's every early return owes this, since a widget stays up until hidden.
     pub fn retire_nameplates(&mut self) {
         let lua = self.lua();
         let effects = {
@@ -385,7 +227,7 @@ impl UiScript {
         super::event::fire_visibility_changes(lua, effects.visibility);
     }
 
-    /// How many plate widgets the pool holds — the plate driver's census, and the tests'.
+    /// How many plate widgets the pool holds.
     pub fn nameplate_pool_len(&self) -> usize {
         let lua = self.lua();
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -393,8 +235,7 @@ impl UiScript {
     }
 }
 
-/// Record a completed click on `id` if that frame is a live plate — [`super::button::click_button`]
-/// calls this for every button click, physical or scripted.
+/// Record a click on `id` if it is a live plate; every button click comes here.
 pub(super) fn note_click(lua: &mlua::Lua, id: u32, button: &str) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let Some(frame) = model.id_to_frame.get(&id).copied() else {
@@ -403,7 +244,6 @@ pub(super) fn note_click(lua: &mlua::Lua, id: u32, button: &str) {
     let Some(&slot) = model.nameplates.by_frame.get(&frame) else {
         return;
     };
-    // A pooled (retired) plate has no unit, and clicking one is not possible anyway — it is hidden.
     let Some(key) = model.nameplates.plates.get(slot).and_then(Plate::key) else {
         return;
     };
@@ -413,8 +253,7 @@ pub(super) fn note_click(lua: &mlua::Lua, id: u32, button: &str) {
     });
 }
 
-/// The whole per-frame drive: grow, re-lay-out if the window moved, write what changed, retire the
-/// tail.
+/// The per-frame drive: retire departed units, bind the rest, lay out, write what changed.
 fn sync(
     model: &mut Model,
     world: FrameHandle,
@@ -425,8 +264,8 @@ fn sync(
     let relayout = model.nameplates.geometry != Some(geometry);
     model.nameplates.geometry = Some(geometry);
 
-    // Retire first, so a unit that left this frame frees its slot for one that arrived — the
-    // reference's destroy-then-create through the same free list, in the same tick.
+    // Retire first, so a departing unit's slot is free for an arriving one, as the reference
+    // destroys then creates through one free list in the same tick.
     let gone: Vec<u64> = model
         .nameplates
         .assigned
@@ -444,9 +283,8 @@ fn sync(
         let slot = match model.nameplates.assigned.get(&state.key) {
             Some(&i) => i,
             None => {
-                // The lowest free slot, else a new one at the tail. Lowest-free rather than the
-                // reference's FIFO free list: both keep every existing index meaning what it did,
-                // which is the only property an addon can observe.
+                // The lowest free slot, else a new one at the tail. Deviation: the reference's
+                // free list is FIFO; either keeps every index stable, all an addon can observe.
                 let free = (0..model.nameplates.plates.len())
                     .find(|i| model.nameplates.plates[*i].last.is_none());
                 let i = free.unwrap_or_else(|| {
@@ -464,8 +302,7 @@ fn sync(
         Plate::drive(model, slot, world, state, &mut effects);
     }
 
-    // A geometry change reaches the retired plates too: they are still in the child list, an addon
-    // can still read them, and they must not come back next frame laid out for the old window.
+    // A geometry change reaches retired plates too: addons still read them in the child list.
     if relayout {
         for i in 0..model.nameplates.plates.len() {
             if model.nameplates.plates[i].laid_out != Some(geometry) {
@@ -477,13 +314,11 @@ fn sync(
 }
 
 impl Plate {
-    /// Build one plate: the Button under the WorldFrame, its six regions in the reference's
-    /// creation order, and the health-bar child with its fill.
-    ///
-    /// Everything here is written **once**. An addon that blanks a region (pfUI's `DisableObject`
-    /// does `SetTexture("")`) must find it still blank on the next frame.
+    /// Build one plate: the Button, its six regions in the reference's order, and the health bar.
+    /// Written once, so a region an addon blanks stays blank.
     fn create(model: &mut Model, world: FrameHandle, effects: &mut SyncEffects) -> Plate {
-        // Anonymous, and that is a requirement rather than an omission (module doc).
+        // Anonymous, as the reference's name is zeroed (`0x76c50b`): plate addons reject a named
+        // `WorldFrame` child.
         let frame = model.arena.create(FrameKind::Button, None, Some(world));
         let strata = model
             .arena
@@ -492,21 +327,9 @@ impl Plate {
             .unwrap_or_default();
         model.arena.set_frame_strata(frame, strata);
         model.arena.set_frame_level(frame, PLATE_LEVEL, true);
-        // The plate takes the mouse, which it is born with: `CSimpleButton`'s ctor writes
-        // `[+0xcc] = 0x4` (`0x7786a3`), so the reference's plate needs no `EnableMouse` of its own
-        // and neither does ours. Hovering it publishes the mouseover (`0x7cb850` → `0x492890`) and
-        // a completed click selects through the button's click slot (`0x7cb910`); both reach the
-        // app through [`UiScript::hovered_nameplate`] and [`UiScript::take_nameplate_clicks`].
-        // `EnableMouse`/`IsMouseEnabled` are in the corpus's own call set, and pfUI's vanilla
-        // click-through block drives them.
-        //
-        // **And it takes BOTH buttons, on the UP edge**: `RegisterForClicks(0x500)` at `0x7cb637`
-        // (`0x779730` → `[this+0x330] = 0x500` = LeftButtonUp | RightButtonUp). The arena's Button
-        // default is `{"LeftButtonUp"}` alone, so without this a physical right-click on a plate
-        // fired no click at all — [`super::button::wants_click`] refused the release, the funnel
-        // never ran, and since 2233 took the camera off a press that lands on a plate there was no
-        // other path left: right-clicking a nameplate did nothing. The reference's own slot
-        // (`0x7cb910`) takes mask 1 → `0x4925d0` select and mask 4 → `0x492820` select+interact.
+        // Mouse-enabled from birth by `CSimpleButton`'s ctor (`0x7786a3`), and registered for
+        // both buttons on the up edge (`RegisterForClicks(0x500)`, `0x7cb637`); the arena's
+        // Button default is the left alone.
         if let Some(KindState::Button(bs)) = model.arena.frame_mut(frame).map(|f| &mut f.kind_state)
         {
             bs.registered_clicks = ["LeftButtonUp", "RightButtonUp"]
@@ -515,10 +338,8 @@ impl Plate {
                 .collect();
         }
 
-        // The blend modes are the ctor's own, one `0x7703f0` call per texture (wow-re
-        // `nameplate-vkey.md` §8.1, byte-arbitrated): everything is BLEND(2) except the **glow,
-        // which is ADD(3)** (`push 3` at `0x7cb36a` → `0x7cb374`). Getting that one wrong is not a
-        // subtlety — see [`is_unpainted_glow`].
+        // The ctor's blend modes, one `0x7703f0` call per texture: BLEND, but the glow is ADD
+        // (`0x7cb36a`), which [`is_unpainted_glow`] depends on.
         let border = texture(
             model,
             frame,
@@ -549,9 +370,10 @@ impl Plate {
             RAID_ICON_TEXTURE,
             BlendMode::Blend,
         );
-        // ↑ THE ORDER. Six regions, and this sequence is the ABI (module doc).
+        // The order above is the ABI addons walk and, as 5875 has no sub-level, the draw order
+        // within a layer.
 
-        // The one child, below the plate's own level so the border draws over the fill.
+        // The one child, below the plate's level so the border draws over the fill.
         let bar = model.arena.create(FrameKind::StatusBar, None, Some(frame));
         model.arena.set_frame_strata(bar, strata);
         model.arena.set_frame_level(bar, BAR_LEVEL, true);
@@ -561,9 +383,7 @@ impl Plate {
             .expect("live bar");
         let fill_data = model.region_data.entry(fill).or_default();
         fill_data.texture = Some(BAR_FILL_TEXTURE.to_string());
-        // Not overridden by the ctor — the `CSimpleTexture` ctor's own `[+0xd0] = 2` stands
-        // (`0x76fc40`; vkey §8.1). Written explicitly because the default is a FACT here, not an
-        // omission.
+        // The fill keeps `CSimpleTexture`'s default BLEND (`0x76fc40`), written out as a fact.
         fill_data.blend = BlendMode::Blend;
         if let Some(KindState::StatusBar(sb)) =
             model.arena.frame_mut(bar).map(|f| &mut f.kind_state)
@@ -574,14 +394,11 @@ impl Plate {
             sb.value = 0.0;
         }
 
-        // The skull and the raid icon are the two regions that only sometimes show; the glow is
-        // shown on hover alone. The rest are always up while the plate is.
         for rh in [glow, skull, raid] {
             model.region_data.entry(rh).or_default().hidden = true;
         }
 
-        // Born retired: a fresh plate belongs to no unit yet, and `IsShown()` is what an addon
-        // reads to tell a live plate from a pooled one.
+        // Born retired and hidden: addons tell a live plate from a pooled one by `IsShown()`.
         effects
             .visibility
             .extend(model.arena.set_shown(frame, false));
@@ -606,8 +423,8 @@ impl Plate {
         }
     }
 
-    /// (Re)lay the static anchors — everything that follows from the window's size rather than the
-    /// unit. Called on the first drive and on a geometry change, never per frame.
+    /// Write the window-derived sizes and anchors, on the first drive and a geometry change. The
+    /// reference's are real anchors too, through `SetPoint`'s own store (`0x767c70`).
     fn lay_out(model: &mut Model, i: usize, g: PlateGeometry) {
         let p = &model.nameplates.plates[i];
         let (frame, bar) = (p.frame, p.bar);
@@ -615,12 +432,11 @@ impl Plate {
             (p.border, p.glow, p.name, p.level, p.skull, p.raid);
         let plate_id = model.frame_id(frame);
 
-        // The plate's own size; its position is per-frame and lives in `drive`.
+        // The plate's size; its position is per-frame, in `drive`.
         let input = model.layout_inputs.entry(frame).or_default();
         input.width = g.width;
         input.height = g.height;
 
-        // The border fills the plate, and so does the glow — a rim over the whole frame.
         for rh in [border, glow] {
             model.region_data.entry(rh).or_default().anchors = vec![
                 Anchor::new(Point::TopLeft, plate_id, Point::TopLeft, 0.0, 0.0),
@@ -628,7 +444,6 @@ impl Plate {
             ];
         }
 
-        // The health bar: BOTTOMLEFT + (off_x, off_y), explicit size.
         let bar_input = model.layout_inputs.entry(bar).or_default();
         bar_input.anchors = vec![Anchor::new(
             Point::BottomLeft,
@@ -640,7 +455,7 @@ impl Plate {
         bar_input.width = g.bar_width;
         bar_input.height = g.bar_height;
 
-        // The name — ("BOTTOM", plate, "CENTER", 0, 0), the pair `_Nameplates` validates.
+        // The name's (`0x7cb456`) and level's (`0x7cb7f5`) anchors, which `_Nameplates` checks.
         let name_data = model.region_data.entry(name).or_default();
         name_data.anchors = vec![Anchor::new(
             Point::Bottom,
@@ -651,7 +466,6 @@ impl Plate {
         )];
         name_data.font_height = Some(g.name_height);
 
-        // The level — ("CENTER", plate, "BOTTOMRIGHT", −x, +y), the other validated pair.
         for rh in [name, level] {
             model.region_data.entry(rh).or_default().font_shadow = Some(FontShadow {
                 offset: [g.shadow_offset, -g.shadow_offset],
@@ -671,7 +485,6 @@ impl Plate {
         level_data.font_explicit.height = true;
         model.touch_measure(level);
 
-        // The skull replaces the level number, in the level's own seat.
         let skull_data = model.region_data.entry(skull).or_default();
         skull_data.anchors = vec![Anchor::new(
             Point::Center,
@@ -682,19 +495,16 @@ impl Plate {
         )];
         skull_data.size = Some((g.skull_size, g.skull_size));
 
-        // The raid icon hangs off the LEFT edge, vertically centred.
         let raid_data = model.region_data.entry(raid).or_default();
         raid_data.anchors = vec![Anchor::new(Point::Right, plate_id, Point::Left, 0.0, 0.0)];
         raid_data.size = Some((g.raid_size, g.raid_size));
 
-        // Anchor TARGETS moved (from nothing to the plate) on the first lay-out, so this is the
-        // conservative touch — the only one in this module, and it runs once per geometry change.
+        // The first lay-out adds anchor targets, so the full touch; once per geometry change.
         model.touch_layout();
         model.nameplates.plates[i].laid_out = Some(g);
     }
 
-    /// The per-frame write: position, health, texts, colours, shown flags, alpha — **and nothing
-    /// else**, each only when it moved.
+    /// The per-frame write, each property only when it moved.
     fn drive(
         model: &mut Model,
         i: usize,
@@ -709,10 +519,8 @@ impl Plate {
         let last = p.last.clone();
         let world_id = model.frame_id(world);
 
-        // The seat, re-issued whenever it moves, exactly like the reference's own (`0x509ec0`:
-        // ClearAllPoints then SetPoint) — which is why an addon anchor on the plate does not
-        // survive there either. A moved OFFSET keeps the graph's edges, so the precise touch
-        // applies; the first seat adds an edge and takes the retarget.
+        // Re-seated whenever it moves, as the reference does (`0x509ec0`). A moved offset keeps
+        // the graph's edges, so the precise touch; the first seat adds an edge, so the retarget.
         if last
             .as_ref()
             .is_none_or(|l| l.top_centre != state.top_centre)
@@ -745,9 +553,7 @@ impl Plate {
             model.arena.set_alpha(frame, state.alpha);
         }
 
-        // The bar reports RAW health (module doc). Its fill carries the reaction colour, lifted by
-        // a uniform brighten while the unit is the mouseover or the target — 0184's form of the
-        // highlight, in place of the additive `Nameplate-Glow` rim.
+        // Raw health on the bar; the fill's reaction colour brightens while lit (`LIT_BOOST`).
         if last
             .as_ref()
             .is_none_or(|l| l.health != state.health || l.max_health != state.max_health)
@@ -771,7 +577,6 @@ impl Plate {
                 Some([c[0] * boost, c[1] * boost, c[2] * boost, 1.0]);
         }
 
-        // The name: white, yellow while the plate itself is hovered.
         if last.as_ref().is_none_or(|l| l.name != state.name) {
             model.region_data.entry(name).or_default().text = Some(state.name.clone());
             model.touch_measure(name);
@@ -784,17 +589,15 @@ impl Plate {
                 [1.0, 1.0, 1.0, 1.0]
             };
             model.region_data.entry(name).or_default().vertex_color = Some(c);
-            // `glow:IsShown()` IS the mouseover signal (pfUI `nameplates.lua:601`). The region is
-            // shown for real; that it paints nothing is 0184's deviation, not a missing region.
+            // The glow really shows, as addons read mouseover from it; it only paints nothing.
             model.region_data.entry(glow).or_default().hidden = !state.hovered;
         }
 
-        // Level text and skull are mutually exclusive, in one seat.
         if last.as_ref().is_none_or(|l| {
             l.level != state.level || l.skull != state.skull || l.level_colour != state.level_colour
         }) {
             match (state.level, state.skull) {
-                // The skull wins the seat, and it is the SKULL FLAG that puts it there.
+                // The skull flag wins the seat, whatever the level.
                 (_, true) => {
                     model.region_data.entry(level).or_default().hidden = true;
                     model.region_data.entry(skull).or_default().hidden = false;
@@ -809,7 +612,7 @@ impl Plate {
                     model.touch_measure(level);
                     model.touch_layout_region(level);
                 }
-                // No level yet and no skull: the seat stays EMPTY, the old painter's behaviour.
+                // No level yet and no skull: the seat stays empty.
                 (None, false) => {
                     model.region_data.entry(level).or_default().hidden = true;
                     model.region_data.entry(skull).or_default().hidden = true;
@@ -817,7 +620,6 @@ impl Plate {
             }
         }
 
-        // The raid mark: the 4-column atlas cell, shown only while the unit carries one.
         if last.as_ref().is_none_or(|l| l.raid_icon != state.raid_icon) {
             match state.raid_icon {
                 Some(idx) => {
@@ -833,10 +635,8 @@ impl Plate {
         model.nameplates.plates[i].last = Some(state.clone());
     }
 
-    /// Retire a plate: **hide it, never destroy it** (`0x608a10` — unlink from the active list,
-    /// push onto the free list, `Hide`). It keeps its slot in `WorldFrame`'s child list, keeps its
-    /// index, and comes back as the same Lua object, which is the contract every addon's
-    /// `registry[plate]` identity map rests on.
+    /// Retire a plate: hide it, never destroy it (`0x608a10`), so it keeps its child-list index and
+    /// comes back as the same Lua object addons key their per-plate state by.
     fn retire(model: &mut Model, i: usize, effects: &mut SyncEffects) {
         if model.nameplates.plates[i].last.is_none() {
             return;
@@ -849,10 +649,7 @@ impl Plate {
     }
 }
 
-/// One of the plate's texture regions, with its path and its blend mode — created in the ABI's
-/// order by the caller. The mode is not decoration: the ctor sets one on every texture it makes
-/// (`0x7703f0`, storing `[texture+0xd0]`), and the glow's is the one that differs — see
-/// [`is_unpainted_glow`].
+/// One of the plate's textures, with its path and the blend mode the ctor sets (`0x7703f0`).
 fn texture(
     model: &mut Model,
     frame: FrameHandle,
@@ -870,18 +667,9 @@ fn texture(
     rh
 }
 
-/// One of the plate's two FontStrings. Both are OVERLAY — the ctor re-layers them off ARTWORK
-/// (`0x7cb438`, `0x7cb4ea`) — and both take `NAMEPLATE_FONT` with the plate's black 1 px drop
-/// shadow; the heights arrive with the geometry.
-///
-/// The black drop shadow is written in [`Plate::lay_out`] instead of here: its step is a
-/// WINDOW-derived number ([`PlateGeometry::shadow_offset`]), not a create-time constant.
-///
-/// `justify_v` is the one benilla-side compensation here, and it is the old painter's, kept: the
-/// plate's name is seated by its **ink**, not by the line box. Our shaper's box is ascent-heavy
-/// for Friz, so a box-seated `BOTTOM` anchor drops the name ~8 px — half of it over the plate —
-/// which is the director's old "the level is not aligned" in its other half. `Bottom` puts the
-/// text where the reference's own metrics put it.
+/// One of the plate's two FontStrings, OVERLAY as the ctor re-layers them (`0x7cb438`,
+/// `0x7cb4ea`). `justify_v` seats the name by its ink: our shaper's Friz line box is ascent-heavy
+/// and would drop it ~8 px below where the reference's metrics put it.
 fn font_string(model: &mut Model, frame: FrameHandle, justify_v: JustifyV) -> RegionHandle {
     let rh = model
         .arena
@@ -894,61 +682,21 @@ fn font_string(model: &mut Model, frame: FrameHandle, justify_v: JustifyV) -> Re
     rh
 }
 
-/// **Is this frame a V-plate?** — the seat question, asked of the OWNER (decision 2172).
-///
-/// A plate is a WorldFrame overlay: the driver snaps its rect to the DEVICE pixel grid
-/// (`vplates::device_snap`, 0188/1398) because it slides continuously over the world, and
-/// everything drawn inside it has to be rigid to that rect. The renderer's UI seat snap quantizes
-/// a text block's top on the coarser LOGICAL grid, so with both laws in force a plate's name and
-/// level pop a whole logical pixel every second step the border takes — two quantizers on one
-/// sliding object, and the "janky text walking up to a mob" the director reported the day after
-/// decision 2148 moved these strings out of a painter that never snapped them (its host-measure
-/// rects were degenerate, and a degenerate rect skips the snap — the carve-out the port silently
-/// stopped selecting).
-///
-/// **Asked of the frame rather than written on our six regions**, because it is the frame that
-/// slides: pfUI and ShaguTweaks blank the stock regions and hang their *own* FontStrings on the
-/// plate, and those are drawn inside the same rect and want the same answer. (A string an addon
-/// puts on the plate's health-BAR child is one level further down and still takes the UI grid —
-/// the named residual, and the shape of the fix if it ever bites is an ancestor walk.)
+/// Whether a text's owner is a plate. A plate's rect snaps to device pixels as it slides, and its
+/// text must follow that rect, not the UI's coarser grid, or it jumps. Asked of the frame so an
+/// addon's strings on the plate get it too; a string on the plate's health bar does not.
 pub(super) fn is_world_seated(model: &Model, frame: FrameHandle) -> bool {
     model.nameplates.by_frame.contains_key(&frame)
 }
 
-/// **The plate's glow region paints nothing here** — the region is real, shown, textured and ADD,
-/// and the quad walk skips it ([`super::extract`]). Decision 0184, and it is the director's call
-/// rather than a gap we could close by trying harder.
-///
-/// The reference draws this region `(SRC_ALPHA, ONE)` over the health bar: an additive
-/// reaction-tinted lift of the bar's cavity. 0183 built exactly that and the director rejected it
-/// on sight — *"you should not change the gradient or anything — just make the color of the yellow
-/// bar brighter"* — so 0184 replaced the rim with [`LIT_BOOST`], and the paint has been the bar's
-/// own brighten ever since. That is what this predicate keeps true now that the plate is a widget
-/// and its regions go through the shared frame→quad path instead of a painter that simply never
-/// emitted a glow quad.
-///
-/// **Why the mode matters even though nothing is drawn.** `Nameplate-Glow.blp` is DXT1 with **no
-/// alpha channel** — every one of its 4096 texels is alpha 255 — and 80.5% of it is exactly
-/// `rgb(0,0,0)`, the surround; the signal is a grey rounded bar (rim 140, interior ~46) in rows
-/// 20-26 that only reads as a glow when it is *added*. Blitted with straight `BLEND` it is
-/// `dst·(1−1) + black·1` — **an opaque black rectangle over the whole plate**, which is precisely
-/// what shipped when the widget port left the mode at the ctor default (director report,
-/// 2026-09-10; wow-re `nameplate-vkey.md` §8.1 had already named this exact bug and its cause in
-/// July). So `GetBlendMode()` answers `"ADD"` truthfully, an addon that re-textures the region
-/// gets its own art painted normally, and only the reference's own glow art on an ADD region is
-/// the one thing this engine declines to draw.
+/// Whether this is the plate's own glow art on its ADD mode, which the quad walk
+/// ([`super::extract`]) skips. Deviation: the reference adds this rim over the bar; we brighten
+/// the bar ([`LIT_BOOST`]), because the rim reads as hard edge lines in our linear-blending
+/// pipeline. The art has no alpha and is mostly black, so as BLEND it would be an opaque box.
 pub(super) fn is_unpainted_glow(data: &RegionData) -> bool {
     data.blend == BlendMode::Add && data.texture.as_deref() == Some(GLOW_TEXTURE)
 }
 
-/// The LIT (mouseover ∪ target) bar brighten — a uniform multiplicative lift of the fill tint,
-/// gradient untouched (0184: the recorded additive `Nameplate-Glow` rim read as hard edge lines on
-/// our linear-blending pipeline, and the director pinned the brighten instead).
-///
-/// Quad colours are client-space sRGB (`srgb_quad_color` linearizes them), so this multiplies
-/// ENCODED texels ~1:1 — the gamma-space modulate the client's FFP would do. **255/215 is the
-/// largest clean value**: the fill texture's encoded peak (215) lands exactly on white, no row
-/// clips, and every row scales by the same visible factor. (A first cut of 1.45 assumed a
-/// linear-space multiply and flattened six rows against white — the very gradient change the
-/// director banned.)
+/// The lit bar's brighten, a multiply of the fill tint in encoded sRGB like the client's modulate:
+/// 255/215 takes the fill texture's encoded peak exactly to white, so no gradient row clips.
 const LIT_BOOST: f32 = 255.0 / 215.0;
diff --git a/crates/benilla-ui/src/script/net_stats.rs b/crates/benilla-ui/src/script/net_stats.rs
index eb81e418..5732662c 100644
--- a/crates/benilla-ui/src/script/net_stats.rs
+++ b/crates/benilla-ui/src/script/net_stats.rs
@@ -1,27 +1,15 @@
-//! `GetNetStats()` — the connection-telemetry read the main bar's performance ("ping") meter polls.
-//!
-//! One global over one pushed number. The reference binding (`0x48b8b0`, wow-re
-//! `system/ui/scratch/bindings.md`) returns `bandwidthIn, bandwidthOut, latency`; its latency is
-//! **not** the last round trip but the average over the connection's RTT ring — wow-re net W1
-//! records `HandlePong 0x537d60` as "RTT into ring, head/tail wrap 16" feeding
-//! `0x537f20 throughput/avg-RTT math (host telemetry; no wire bytes)". The app owns that ring
-//! ([`crate`]'s consumer keeps it beside its ping clock) and pushes the average here; the engine
-//! stays free of ECS/net reach (decision 0068 §3), exactly as [`super::unit`]'s `GetMoney` does.
-//!
-//! **The two bandwidth returns are `0`.** benilla measures no throughput — its socket threads tally
-//! no bytes — and nothing in the 1.12 UI reads them: `MainMenuBarPerformanceBarFrame` is the whole
-//! shipped caller of `GetNetStats` and discards both. They stay in the signature (numbers, not
-//! `nil`, so arithmetic on them can't error) as a named gap, not a claim.
+//! `GetNetStats()` (`0x48b8b0`): `bandwidthIn, bandwidthOut, latency` for the main bar's latency
+//! meter. The latency is the average over the connection's 16-slot RTT ring (`HandlePong`
+//! `0x537d60`, `0x537f20`), which the app keeps and pushes here. Both bandwidths read 0: benilla
+//! measures no throughput, and the one stock caller, `MainMenuBarPerformanceBarFrame`, drops them.
 
 use mlua::Lua;
 
 use super::Model;
 
 impl super::UiScript {
-    /// Push the reported round trip (ms) — the app's average over its RTT ring. `None` = no sample
-    /// yet (before the connection's first pong, or after a disconnect), which reads as `0` through
-    /// `GetNetStats`: the reference reports 0 for an unmeasured connection too, and the bar's
-    /// thresholds put 0 in the green band, which is what the real client shows at login.
+    /// Push the average round trip in ms; `None`, before the first pong, reads 0, as the reference
+    /// reports an unmeasured connection.
     pub fn set_latency_ms(&mut self, ms: Option<u32>) {
         self.model_mut().net_latency_ms = ms.unwrap_or(0);
     }
@@ -29,7 +17,6 @@ impl super::UiScript {
 
 /// Register the net-stats globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // GetNetStats() → bandwidthIn, bandwidthOut, latency (see the module doc for the two zeros).
     lua.globals().set(
         "GetNetStats",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/object.rs b/crates/benilla-ui/src/script/object.rs
index d62eb158..848cf82b 100644
--- a/crates/benilla-ui/src/script/object.rs
+++ b/crates/benilla-ui/src/script/object.rs
@@ -1,18 +1,10 @@
-//! The FrameScript object model, frame side (RF-0023) — `CreateFrame`, the frame metatable +
-//! wrapper cache, and the shared frame method surface (decision 0068 v1). The region side lives in
-//! [`super::region`]; per-kind frame methods in their own modules ([`super::statusbar`], …),
-//! dispatched by [`kind_method_registries`] before the shared table.
+//! The FrameScript object model, frame side: `CreateFrame`, the frame wrappers and metatables, and
+//! the shared frame methods; the region side is [`super::region`].
 //!
-//! A frame's Lua value is a table `T` with `T[0] = lightuserdata(id)` (the id encoding stands in for
-//! RF-0023's `CScriptObject*`; see the module docs on ids) and one **shared** metatable whose
-//! `__index` is a Rust function that dispatches a method name to its implementation. Wrappers are
-//! cached in a Lua-side registry table keyed by id, so `GetParent()` (etc.) returns the *same* table
-//! every time (stable identity). Named frames auto-publish to `_G`, non-overwriting (RF-0023). Region
-//! leaves (`Texture`/`FontString`) use the same `T[0]` scheme but a *distinct* metatable (the "tag"
-//! that separates their method surface from frames').
-//!
-//! The whole surface honors the MAXCSTACK discipline: the two metatables, the two method tables, and
-//! the wrapper cache live in the Lua registry (named keys); Rust holds none of them across calls.
+//! A frame's Lua value is a table `T` with `T[0] = lightuserdata(id)` (`0x701bd0`), cached by id
+//! and published to `_G` by name without overwriting; its metatable is its kind's
+//! ([`frame_meta_for`]). Every table lives in the Lua registry under a named key, and Rust holds
+//! none across calls (the MAXCSTACK discipline).
 
 use std::ffi::c_void;
 
@@ -24,8 +16,7 @@ use crate::layout::Point;
 use crate::order::{DrawLayer, Strata};
 use crate::widget::{FrameHandle, FrameKind};
 
-// The frame method-table clusters — split out purely for size (each module's own doc says what
-// lives there); this file keeps the shared id/handle plumbing, `install`, and `CreateFrame`.
+// The frame method clusters, split out for size.
 pub(crate) mod anchor_args;
 mod events_regions;
 mod frame_state;
@@ -44,7 +35,7 @@ pub(super) fn id_to_lud(id: u32) -> LightUserData {
     LightUserData(id as usize as *mut c_void)
 }
 
-/// Read the id out of a wrapper table's `T[0]` lightuserdata (RF-0023).
+/// Read the id out of a wrapper table's `T[0]` lightuserdata (`0x701bd0` writes it).
 pub(crate) fn decode_id(this: &Table) -> mlua::Result<u32> {
     match this.raw_get::<Value>(0)? {
         Value::LightUserData(l) => Ok(l.0 as usize as u32),
@@ -66,12 +57,11 @@ pub(super) fn frame_handle_of(lua: &Lua, this: &Table) -> mlua::Result<FrameHand
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Wrapper cache (RF-0023: lazy bind + named _G publish, non-overwriting)
+// Wrapper cache (`0x701bd0`)
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Get-or-create the wrapper table for a frame id, caching it and (if the frame is named and `_G`
-/// has no such global yet) publishing it to `_G`. Callers must hold **no** model borrow (this takes
-/// a short one to read the frame's name).
+/// The wrapper table for a frame id, created and cached on first use and published to `_G` under
+/// the frame's name if that global is free. Call it with no model borrow alive.
 pub(super) fn frame_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     let wrappers: Table = lua.named_registry_value(REG_WRAPPERS)?;
     if let Value::Table(t) = wrappers.get::<Value>(id)? {
@@ -79,25 +69,25 @@ pub(super) fn frame_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     }
     let t = lua.create_table()?;
     t.raw_set(0, Value::LightUserData(id_to_lud(id)))?;
-    let meta: Table = lua.named_registry_value(REG_FRAME_META)?;
-    t.set_metatable(Some(meta))?;
-    wrappers.set(id, t.clone())?;
-
-    let name: Option<String> = {
+    // The kind picks the metatable once, here: a frame's kind never changes and `id_to_frame`
+    // never loses an entry, so the choice cannot go stale.
+    let (kind, name): (Option<FrameKind>, Option<String>) = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
-        model
+        let frame = model
             .id_to_frame
             .get(&id)
-            .and_then(|h| model.arena.frame(*h))
-            .and_then(|f| f.name.clone())
+            .and_then(|h| model.arena.frame(*h));
+        (frame.map(|f| f.kind), frame.and_then(|f| f.name.clone()))
     };
+    t.set_metatable(Some(frame_meta_for(lua, kind)?))?;
+    wrappers.set(id, t.clone())?;
     if let Some(name) = name {
         publish_global(lua, &name, &t)?;
     }
     Ok(t)
 }
 
-/// Publish a wrapper to `_G[name]`, non-overwriting (RF-0023).
+/// Publish a wrapper to `_G[name]`, non-overwriting (`0x701bd0`).
 pub(super) fn publish_global(lua: &Lua, name: &str, wrapper: &Table) -> mlua::Result<()> {
     let g = lua.globals();
     if g.get::<Value>(name)?.is_nil() {
@@ -106,45 +96,21 @@ pub(super) fn publish_global(lua: &Lua, name: &str, wrapper: &Table) -> mlua::Re
     Ok(())
 }
 
-/// A widget **name string** argument, already looked up in `_G` — every Lua binding that takes
-/// "a frame or its name" resolves one of these ([`prefetch_named_target`] then
-/// [`resolve_named_target`]).
-///
-/// **The client has ONE widget namespace and it is the Lua globals table.** The wrapper binder
-/// `0x701bd0` publishes `_G[name] = T` for a named widget (non-overwriting, via `lua_settable`),
-/// and every by-name resolver reads that table back — `0x76c760` (globals index → Lua type 5 →
-/// **raw** `t[0]` → `lua_touserdata` → `IsA`; `SetParent`'s string arm `0x7a1550`, `SetScrollChild`
-/// `0x790fa0`, the XML `parent=` chain) and the layout-vtable `+0x28` entry `0x76c700`, which
-/// expands a leading `$parent` (`0x76c5b0`) and then calls `0x76c760`. There is no engine-side
-/// name→frame map behind either: for frames and regions a name's only effects are the copy into
-/// `[widget+0x98]` and that `_G` publish. (`CSimpleFont` names are the one exception — they key a
-/// Storm hash at `0xcf4e78` — and fonts are not anchor targets.) `wow-5875-re`
-/// `system/ui/scratch/name-string-widget-resolution.md`; `system/ui/ledger.tsv` rows
-/// `0x76c5b0`/`0x76c700`/`0x76c760`/`0x7a2540`.
-///
-/// So the name is not a *frame name* — it is a **global**, and a frame's published name is only the
-/// commonest way one comes to exist. Resolving against a private registry instead makes an alias
-/// invisible: `Bar8Button1 = CharacterBag3Slot` at an addon's file scope is a global that is no
-/// frame's name, and Bartender2 anchors every bar's buttons through exactly those (decision 2105).
-///
-/// ## Why the lookup is its own phase
-///
-/// The reference's read is **`lua_gettable 0x6f3a40` → `luaV_index 0x6f7cf0`**, not `lua_rawget`
-/// (the binary holds both, 0xc0 apart; only the former walks `__index`, MAXTAGLOOP 100). So a
-/// metatable on `_G` is honoured — and a `__index` can be a *Lua* function that calls straight back
-/// into a widget binding. Running that under a live `Model` guard would take a second borrow and
-/// panic, so the `_G` read is done with **no guard alive** and the decode happens after.
+/// A widget name argument already looked up in `_G` ([`prefetch_named_target`], then
+/// [`resolve_named_target`]). The globals table is the client's only widget namespace (`0x701bd0`
+/// publishes there; `0x76c760` and the anchor resolver `0x76c700` read back), so a global alias
+/// of a frame (`Bar8Button1 = CharacterBag3Slot`) resolves like its name. The read is
+/// `lua_gettable` (`0x6f3a40` → `0x6f7cf0`), which honours an `__index` on `_G` that may call back
+/// into a widget binding, so it runs with no `Model` borrow alive and the decode comes after.
 pub(crate) struct NamedTarget {
-    /// The name as the client looked it up — after `$parent` expansion where the caller allows it.
-    /// This is the spelling a diagnostic must quote.
+    /// The name as looked up, after any `$parent` expansion: the spelling a diagnostic quotes.
     pub(crate) name: String,
-    /// `_G[name]`, kept only when it is a table (the Lua-type-5 gate). Identity is checked later.
+    /// `_G[name]` if it is a table (Lua type 5); its identity is decoded later.
     wrapper: Option<Table>,
 }
 
 impl NamedTarget {
-    /// A name argument we could not even read (a non-UTF-8 Lua string) — it names nothing, and the
-    /// caller's miss path quotes this placeholder the way it always has.
+    /// A name that is not UTF-8: it names nothing, and the miss path quotes `<non-utf8>`.
     pub(crate) fn unreadable() -> Self {
         Self {
             name: "<non-utf8>".into(),
@@ -153,14 +119,11 @@ impl NamedTarget {
     }
 }
 
-/// Read `_G[name]` for a name-string argument. **Call with no `Model` borrow alive** — see
-/// [`NamedTarget`].
-///
-/// `parent_base` is the name a leading `$parent` expands to, or `None` for the bindings that do not
-/// expand it. `0x76c5b0` has exactly two call sites — `SetName 0x76c691` and `0x76c71c` inside the
-/// layout resolver `0x76c700` — so `SetPoint`/`SetAllPoints`' `relativeTo` **is** expanded at
-/// runtime, and `SetParent`, `SetScrollChild` and the XML `parent=` chain (which call `0x76c760`
-/// directly) are **not**.
+/// Read `_G[name]` for a name argument, with no `Model` borrow alive. `parent_base` is what a
+/// leading `$parent` expands to, `None` where the binding does not expand: `0x76c5b0` is called
+/// only from `SetName` (`0x76c691`) and the anchor resolver (`0x76c71c` in `0x76c700`), so
+/// `SetPoint`/`SetAllPoints`' `relativeTo` expands, and `SetParent`, `SetScrollChild` and XML
+/// `parent=`, which call `0x76c760` directly, do not.
 pub(crate) fn prefetch_named_target(
     lua: &Lua,
     name: &str,
@@ -177,23 +140,17 @@ pub(crate) fn prefetch_named_target(
     NamedTarget { name, wrapper }
 }
 
-/// Decode a [`NamedTarget`] to the stable id of a live frame **or** region (the namespace is one —
-/// a Texture or FontString publishes into `_G` on the same rule a Frame does).
-///
-/// `SetPoint` type-checks against the **root** `CScriptRegion` id `[0xcf0c3c]`, which every widget
-/// accepts; `SetParent`/`SetScrollChild` use the narrower Frame id `[0xcf0c10]`, so those callers
-/// narrow the result to `id_to_frame` themselves.
+/// Decode a [`NamedTarget`] to a live frame's or region's id: `SetPoint` accepts any widget (the
+/// `CScriptRegion` type id `[0xcf0c3c]`), while `SetParent` and `SetScrollChild` check the Frame
+/// id `[0xcf0c10]` and narrow the result themselves.
 pub(crate) fn resolve_named_target(model: &Model, target: &NamedTarget) -> Option<u32> {
     let id = decode_id(target.wrapper.as_ref()?).ok()?;
     (model.id_to_frame.contains_key(&id) || model.id_to_region.contains_key(&id)).then_some(id)
 }
 
-/// The name a leading `$parent` expands to: the first widget at or above `start` with a non-empty
-/// name (`0x76c5b0`'s `+0x9c` walk, skipping an empty `GetName`), and
-/// [`crate::framexml::DEFAULT_PARENT_NAME`] (`"Top"`) when there is none (rf27 rules 3/5).
-///
-/// `start` is the anchoring widget's **parent**: a frame's own anchors say `$parent` of its
-/// enclosing frame, and a region's say `$parent` of its owner — which is that region's `+0x9c`.
+/// What a leading `$parent` expands to: the first non-empty name at or above `start` (`0x76c5b0`'s
+/// `+0x9c` walk), else [`crate::framexml::DEFAULT_PARENT_NAME`] (`0x76c5dd`). `start` is the
+/// anchoring widget's parent: a frame's enclosing frame, a region's owner.
 pub(crate) fn parent_token_base(model: &Model, start: Option<FrameHandle>) -> String {
     let mut cur = start;
     while let Some(p) = cur {
@@ -206,13 +163,13 @@ pub(crate) fn parent_token_base(model: &Model, start: Option<FrameHandle>) -> St
     crate::framexml::DEFAULT_PARENT_NAME.to_string()
 }
 
-/// [`parent_token_base`] for a frame's own anchors — the walk starts at its parent.
+/// [`parent_token_base`] for a frame's own anchors: the walk starts at its parent.
 pub(crate) fn frame_parent_token_base(model: &Model, h: FrameHandle) -> String {
     parent_token_base(model, model.arena.frame(h).and_then(|f| f.parent))
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// String → enum parsing (the client's tables, transcribed in order.rs / layout.rs)
+// String → enum parsing
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 pub(super) fn point_from_str(s: &str) -> Option<Point> {
@@ -230,10 +187,7 @@ pub(super) fn point_from_str(s: &str) -> Option<Point> {
     })
 }
 
-/// The inverse of [`point_from_str`] (the client's point-id table `0x811a38`, names back out).
-///
-/// `pub(super)` because the REGION cluster reports the same names from the same table — one
-/// spelling of the point set, not two (`region/layout.rs`'s `GetPoint`).
+/// The inverse of [`point_from_str`]: the names of the client's point table `0x811a38`.
 pub(super) fn point_name(p: Point) -> &'static str {
     match p {
         Point::TopLeft => "TOPLEFT",
@@ -248,21 +202,16 @@ pub(super) fn point_name(p: Point) -> &'static str {
     }
 }
 
-/// Every closed-vocabulary attribute parser **trims** before it matches (decision 1204).
-///
-/// Not tidiness: `zBar.xml:146` — a shipped, working 1.12 addon — declares
-/// `frameStrata="BACKGROUND "` with a trailing space, and the real client took it. Ours refused,
-/// the frame's whole `<Frames>` subtree went with it, and the addon never loaded. Whitespace is
-/// never meaningful in an enum token, so trimming is both the lenient answer and the correct one;
-/// it is applied at the three parsers rather than at the attribute read, because a `text=`
-/// attribute's leading space IS meaningful and must not be touched.
+/// An enum token, trimmed and uppercased; trimmed here rather than at the attribute read, since a
+/// `text=` value's spaces count. The reference's strata lookup compares the whole token,
+/// case-insensitively (`0x6f17ee`), so a padded `"BACKGROUND "` misses there.
 fn enum_token(s: &str) -> String {
     s.trim().to_ascii_uppercase()
 }
 
-/// The reference's strata NAME table (`0x8119f8`) has eight rows, `BACKGROUND`..`TOOLTIP`; stratum
-/// 0 (`WORLD`) has no name and no XML or Lua can put a frame there — the WorldFrame's constructor
-/// is its only writer (decision 1984, wow-re `worldframe-widget.md` §4).
+/// A strata name. The reference's table (`0x8119f8`) holds the eight `BACKGROUND`..`TOOLTIP`;
+/// `BLIZZARD` is a later client's, not 1.12's. Stratum 0, `WORLD`, has no name: only the
+/// WorldFrame's constructor sets it (`0x481aff`).
 pub(crate) fn strata_from_str(s: &str) -> Option<Strata> {
     Some(match enum_token(s).as_str() {
         "BACKGROUND" => Strata::Background,
@@ -289,8 +238,7 @@ pub(super) fn draw_layer_from_str(s: &str) -> Option<DrawLayer> {
     })
 }
 
-/// The inverse of [`draw_layer_from_str`] — the token `GetDrawLayer` answers, in the client's own
-/// spelling (uppercase, the five `<Layer level=>` names).
+/// The inverse of [`draw_layer_from_str`]: the uppercase token `GetDrawLayer` answers.
 pub(super) fn draw_layer_name(l: DrawLayer) -> &'static str {
     match l {
         DrawLayer::Background => "BACKGROUND",
@@ -301,25 +249,16 @@ pub(super) fn draw_layer_name(l: DrawLayer) -> &'static str {
     }
 }
 
-/// A widget tag or `CreateFrame` type string → its [`FrameKind`], case- and separator-insensitive
-/// ([`enum_token`]). Public because it is the ONE mapping: `benilla-app`'s `frame_flag_gate` sweep
-/// needs it to ask the engine whether a tag is mouse-enabled by construction, and a second copy
-/// there is exactly what drifted.
+/// A widget tag or `CreateFrame` type → its [`FrameKind`] ([`enum_token`]). Public so the app asks
+/// this one mapping rather than keeping a copy.
 pub fn frame_kind_from_tag(s: &str) -> Option<FrameKind> {
     frame_kind_from_str(s)
 }
 
-/// **The type registry lookup both doors share** (`0x6ee280`'s table `[0xcee9d8]`, its only
-/// reader) — the tag's [`FrameKind`] if a factory is registered under it right now, else `None`.
-///
-/// "Right now" is the WorldFrame's one-shot: the reference unlinks and releases that record the
-/// moment the first `<WorldFrame>` is instantiated (`0x6ee439`), so a second one — from any XML, or
-/// `CreateFrame("WorldFrame")` — takes the lookup's miss leg (decision 1984).
-///
-/// One function because the two doors disagree only in what a MISS does, never in what a miss is
-/// (decision 2191): the Lua binding raises ([`create_frame`]), the XML loader logs
-/// `"Unknown frame type: %s"` and skips the node (`crate::loader`), and wow-re's
-/// `taxiroute-widget-type.md`/`lootbutton-widget-type.md` verify both legs off the same `0x6ee280`.
+/// The type registry lookup `CreateFrame` and the XML loader share (`0x6ee280`, table
+/// `[0xcee9d8]`): the tag's [`FrameKind`] if a factory is registered for it now. The WorldFrame's
+/// record is released once the first one is made (`0x6ee439`), so a second one misses. On a miss
+/// Lua raises and XML logs `Unknown frame type: %s` and skips the node.
 pub(crate) fn registered_frame_kind(lua: &Lua, kind: &str) -> Option<FrameKind> {
     let frame_kind = frame_kind_from_str(kind)?;
     let one_shot_spent = frame_kind == FrameKind::WorldFrame
@@ -333,33 +272,17 @@ pub(crate) fn registered_frame_kind(lua: &Lua, kind: &str) -> Option<FrameKind>
 fn frame_kind_from_str(s: &str) -> Option<FrameKind> {
     Some(match enum_token(s).as_str() {
         "FRAME" => FrameKind::Frame,
-        // The world frame's own registered type (decision 1983; `0x495948` in the registration
-        // batch, the one row passing `1` as its third argument).
+        // Registered at `0x495948`, the one row passing `1` as its third argument.
         "WORLDFRAME" => FrameKind::WorldFrame,
-        // `TaxiRouteFrame` — a registered `CreateFrame` type that is a `CSimpleFrame` and NOTHING
-        // else, so it maps to `Frame` rather than earning a kind (decision 1828; wow-re
-        // `ui/scratch/taxiroute-widget-type.md`). Factory `0x495ba0` allocates `0x314`, the same
-        // size the plain-`<Frame>` factory `0x6eec10` allocates for the same base ctor `0x769090`,
-        // and the ctor `0x506950` adds no field. Its vtables are the base's length exactly (36 + 11
-        // slots), so it declares no new virtual; it overrides four slots, of which two are lifetime
-        // plumbing and the other two — `EmitLayer 0x506a60` and a scale hook `0x506ac0` — are DEAD
-        // in 5875: the paint callback `0x506a90` tail-calls `0x506aa0`, which is a bare `ret`, and
-        // every module global it would fill is written by nothing.
-        //
-        // Mapping it to `Frame` is therefore the faithful answer, not a 1203 shortcut — and it is
-        // faithful in the strong sense that `GetObjectType()` must return **"Frame"** and
-        // `IsObjectType("TaxiRouteFrame")` must be **false**: `0x484800` is not overridden, so the
-        // name lives only in the 22-entry tag→factory registry and never becomes a class identity.
-        // The flight-path lines are plain `<Texture>` children the FrameXML creates and rotates
-        // with the 8-argument `SetTexCoord` we already support; `TaxiRouteFrame.cpp` is a vestigial
-        // C++ renderer that draws nothing.
+        // A plain `CSimpleFrame`: factory `0x495ba0` allocates `0x314` like `<Frame>`'s `0x6eec10`,
+        // the ctor `0x506950` adds no field, and its paint `0x506a90` does nothing, so
+        // `GetObjectType()` is "Frame" and `IsObjectType("TaxiRouteFrame")` false (`0x484800` is
+        // not overridden). The flight lines are the FrameXML's own rotated textures.
         "TAXIROUTEFRAME" => FrameKind::Frame,
         "BUTTON" => FrameKind::Button,
         "CHECKBUTTON" => FrameKind::CheckButton,
-        // A real registered type (`0x4959a6`), not an alias for Button — decision 1799. Registering
-        // it AS a Button would load `LootFrame.xml` and leave every row dead, because 1.12 has no
-        // Lua verb for "take slot N": `LootSlot` is the bind-confirm continuation, hard-wired to
-        // `flag = 1`.
+        // Its own registered type (`0x4959a6`), not a Button: 1.12 has no Lua verb to take loot
+        // slot N (`LootSlot` only continues a bind confirm), so a Button row could loot nothing.
         "LOOTBUTTON" => FrameKind::LootButton,
         "EDITBOX" => FrameKind::EditBox,
         "STATUSBAR" => FrameKind::StatusBar,
@@ -389,9 +312,8 @@ pub(super) fn as_f32(v: &Value) -> f32 {
     }
 }
 
-/// [`as_f32`]'s double-width sibling, for the shape-C positions whose store is `f64` — today only
-/// `ColorSelect:SetColorRGB`, whose channels go through a quantizer where a detour via `f32` could
-/// move a value across a rounding boundary (`colorselect`'s module doc).
+/// [`as_f32`] in `f64`, for `ColorSelect:SetColorRGB`, whose quantizer an `f32` detour could push
+/// across a rounding boundary.
 pub(super) fn as_f64(v: &Value) -> f64 {
     match v {
         Value::Number(n) => *n,
@@ -401,52 +323,37 @@ pub(super) fn as_f64(v: &Value) -> f64 {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// install — build the method tables, metatables, CreateFrame, and registry roots
+// install
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // The wrapper cache + the per-frame script tables (Lua-side roots — the MAXCSTACK discipline).
+    // The wrapper cache and the per-frame script tables, as registry roots.
     lua.set_named_registry_value(REG_WRAPPERS, lua.create_table()?)?;
     lua.set_named_registry_value(REG_SCRIPTS, lua.create_table()?)?;
 
+    // Opened before any method table is built; `region_map::install` below closes it.
+    super::region_map::open_arms(lua);
     install_frame_methods(lua)?;
     super::region::install(lua)?;
     super::statusbar::install(lua)?;
     super::button::install(lua)?;
     super::editbox::install(lua)?;
-    // AFTER every table above exists: collapse the 19 Region-map names to one shared
-    // implementation each, so a method pulled off a frame works on a texture (decision 1501).
+    // After every table above exists: each of the 19 Region-map names gets one shared
+    // implementation, so a method taken off a frame works on a texture.
     super::region_map::install(lua)?;
 
-    // Shared frame metatable: __index is a Rust dispatcher over the frame method table (RF-0023),
-    // checking the frame's *kind-specific* method table first. Per-kind resolution matters beyond
-    // correctness: addons duck-type widgets (`if frame.SetValue then …`), so a plain frame must
-    // resolve `SetValue` to nil — one shared table would make every frame quack like every widget.
-    let frame_meta = lua.create_table()?;
-    let frame_index = lua.create_function(|lua, (this, key): (Table, Value)| {
-        for reg in kind_method_registries(lua, &this) {
-            let methods: Table = lua.named_registry_value(reg)?;
-            let v = methods.get::<Value>(key.clone())?;
-            if !v.is_nil() {
-                return Ok(v);
-            }
-        }
-        let methods: Table = lua.named_registry_value(REG_FRAME_METHODS)?;
-        methods.get::<Value>(key)
-    })?;
-    frame_meta.set("__index", frame_index)?;
+    // The per-kind metatable cache, holding the plain `Frame`'s, whose `__index` is the frame
+    // method table.
+    lua.set_named_registry_value(REG_KIND_METAS, lua.create_table()?)?;
+    let frame_meta = frame_meta_for(lua, None)?;
     lua.set_named_registry_value(REG_FRAME_META, frame_meta.clone())?;
-    // RF-0023 publishes the shared metatable as _G["__framescript_meta"].
+    // FrameScript init publishes it as `_G["__framescript_meta"]` (`0x7039f7`).
     lua.globals().set("__framescript_meta", frame_meta)?;
 
-    // CreateFrame(kind, name?, parent?, inherits?) — a global (RF-0024's factory is the loader's;
-    // this is the runtime one). `inherits` (4th) applies a registered template to the frame this
-    // call just made, through `crate::loader::apply_template`.
     let create_frame = lua.create_function(create_frame)?;
     lua.globals().set("CreateFrame", create_frame)?;
 
-    // GetScreenWidth/Height — the screen-root rect in UI units (the ref's tooltip side-pick reads
-    // them: ContainerFrameItemButton_OnEnter anchors LEFT when the slot sits in the right half).
+    // `GetScreenWidth`/`GetScreenHeight`: the screen root's size in UI units.
     lua.globals().set(
         "GetScreenWidth",
         lua.create_function(|lua, ()| {
@@ -462,15 +369,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetupFullscreenScale(frame) — the registered binding `0x48c270` the stock WorldMapFrame.xml,
-    // CinematicFrame.xml and UIOptionsFrame.xml call from OnShow (decision 1980; wow-re
-    // `system/ui/scratch/setup-fullscreen-scale.md`, VERIFIED at the bytes): the frame's scale
-    // becomes `min(0.75 · a, 1.0)` for the CONFIGURED aspect `a` — the `gxResolution` width over
-    // height (the `widescreen` CVar's default of 1 selects it; at 0 the aspect is 4:3 and the
-    // scale 1) — and nothing else is written: no anchor, size or position, and `UIParent`'s
-    // scale never enters. It is the same `CSimpleFrame::SetScale` the Lua method calls. The
-    // window's aspect is the configured one here (the UI-unit rect keeps the pixel ratio); NaN
-    // takes the 1.0 leg as the reference's `fcomp` does. The three raises are the binding's own.
+    // `SetupFullscreenScale(frame)` (`0x48c270`) sets only the frame's scale, through `SetScale`:
+    // `min(0.75 · a, 1.0)` for the configured aspect `a`, the `gxResolution` width over height,
+    // which is the window's here (the reference's `widescreen` CVar at 0 would make it 4:3).
+    // `UIParent`'s scale does not enter.
     lua.globals().set(
         "SetupFullscreenScale",
         lua.create_function(|lua, frame: Value| {
@@ -495,12 +397,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCursorPosition() → x, y — the last cursor position the host fed (`mouse_move`/
-    // `mouse_button`), UI units y-up like every other coordinate read — the SCREEN's units, which
-    // is what the reference hands Lua too; a caller inside a scaled frame divides by its
-    // `GetEffectiveScale()` (the reference's own `MouseIsOver` does, and the stock world map at
-    // a scale under 1 is the case that made the division load-bearing here — decision 1985). The
-    // world map polls this every OnUpdate for hover/click math.
+    // `GetCursorPosition()`: the last cursor position the host fed, in screen UI units, y up, as
+    // the reference returns it; a caller in a scaled frame divides by its `GetEffectiveScale()`.
     lua.globals().set(
         "GetCursorPosition",
         lua.create_function(|lua, ()| {
@@ -509,15 +407,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The modifier-key mirror ([`UiScript::set_modifiers`], fed by the app's input pass before
-    // any mouse event each frame) — the reference handlers fork on these at click time
-    // (ContainerFrame.lua's shift-split / ctrl-dressup, ActionBarFrame.xml's shift-pickup,
-    // SpellBookFrame.lua's shift-pickup).
-    //
-    // **1/nil, not a Lua boolean.** These three shipped Era booleans on 0068's reasoning that
-    // "every transcribed `if IsShiftKeyDown()` reads both identically" — true while we wrote every
-    // caller, and false the day real 1.12 addons load (1188/1751). `ColorPickerPlus.lua:121` is
-    // `if IsShiftKeyDown() == 1 then`, and a `true` reads there as "not held" (decision 2118).
+    // The modifier keys the app feeds each frame before any mouse event
+    // ([`UiScript::set_modifiers`]), answered 1 or nil as in 1.12, never a boolean: an addon
+    // testing `IsShiftKeyDown() == 1` (`ColorPickerPlus.lua:121`) reads `true` as not held.
     for (name, pick) in [
         ("IsShiftKeyDown", 0usize),
         ("IsControlKeyDown", 1),
@@ -536,34 +428,56 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The registry keys of a frame's kind-specific method tables, in resolution order — the `__index`
-/// dispatcher walks them before the shared table, mirroring the client's class chain (CheckButton
-/// resolves through Button's map, RF-28). Empty for plain kinds (and for anything that isn't a live
-/// frame, e.g. a region wrapper passing through).
-fn kind_method_registries(lua: &Lua, this: &Table) -> &'static [&'static str] {
-    let Ok(id) = decode_id(this) else { return &[] };
-    let model = lua.app_data_ref::<Model>().expect("model app_data");
-    let Some(h) = model.id_to_frame.get(&id) else {
-        return &[];
-    };
-    match model.arena.frame(*h).map(|f| f.kind) {
+/// Registry key of the per-kind frame metatables, each keyed by its kind's first method-table key,
+/// `""` for a kind with none.
+const REG_KIND_METAS: &str = "__benilla_frame_meta_by_kind";
+
+/// The metatable a frame of `kind` wears, built once per kind and cached in [`REG_KIND_METAS`].
+/// Its `__index` is a table, so a method lookup never leaves `luaV_gettable` for Rust. The kind's
+/// method tables are linked, not merged, in the reference's probe order, each class's lookup
+/// tail-calling its base's (`CheckButton`, `Button`, `Frame`): a later write to a table shows
+/// through, and a plain Frame never reaches `StatusBar`'s methods, so `frame.SetValue` stays nil.
+fn frame_meta_for(lua: &Lua, kind: Option<FrameKind>) -> mlua::Result<Table> {
+    let chain = kind_method_registries(kind);
+    let key = chain.first().copied().unwrap_or("");
+    let metas: Table = lua.named_registry_value(REG_KIND_METAS)?;
+    if let Value::Table(meta) = metas.raw_get::<Value>(key)? {
+        return Ok(meta);
+    }
+    // Link `own -> base -> ... -> Frame`; relinking a base several kinds share is idempotent.
+    let frame_methods: Table = lua.named_registry_value(REG_FRAME_METHODS)?;
+    let mut below = frame_methods.clone();
+    for reg in chain.iter().rev() {
+        let own: Table = lua.named_registry_value(reg)?;
+        let link = lua.create_table()?;
+        link.set("__index", below)?;
+        own.set_metatable(Some(link))?;
+        below = own;
+    }
+    let meta = lua.create_table()?;
+    meta.set("__index", below)?;
+    metas.raw_set(key, meta.clone())?;
+    Ok(meta)
+}
+
+/// The registry keys of a kind's own method tables in the client's lookup order (`CheckButton`'s
+/// `0x79a5d0` tail-calls `Button`'s); empty for a plain kind or no live frame. Each chain must be
+/// its own table followed by its base's whole chain, or [`frame_meta_for`] cannot link it.
+fn kind_method_registries(kind: Option<FrameKind>) -> &'static [&'static str] {
+    match kind {
         Some(FrameKind::StatusBar) => &[super::statusbar::REG_STATUSBAR_METHODS],
         Some(FrameKind::EditBox) => &[super::editbox::REG_EDITBOX_METHODS],
         Some(FrameKind::ScrollingMessageFrame) => {
             &[super::messageframe::REG_SCROLLINGMESSAGEFRAME_METHODS]
         }
-        // Its SIBLING, with its own table — not a fallthrough to the scrolling one. Until this arm
-        // existed a `<MessageFrame>` resolved no kind-specific method at all, which is what blocked
-        // `EasyCopy`, `QuestHistory` and `QuestItem` on `UIErrorsFrame:AddMessage` (three of the
-        // corpus's six method-class blockers) and made `SetInsertMode` unreachable.
+        // A sibling of `ScrollingMessageFrame` with its own table, not a fallthrough to it.
         Some(FrameKind::MessageFrame) => &[super::messageframe::REG_MESSAGEFRAME_METHODS],
         Some(FrameKind::ScrollFrame) => &[super::scrollframe::REG_SCROLLFRAME_METHODS],
         Some(FrameKind::SimpleHtml) => &[super::simplehtml::REG_SIMPLEHTML_METHODS],
         Some(FrameKind::Slider) => &[super::slider::REG_SLIDER_METHODS],
         Some(FrameKind::ColorSelect) => &[super::colorselect::REG_COLORSELECT_METHODS],
         Some(FrameKind::Button) => &[super::button::REG_BUTTON_METHODS],
-        // One method of its own, then all of Button's — the miss order of `0x4c1be0`, which probes
-        // its own 1-entry map `0xb71b64` and tail-calls `Button`'s `0x782c90`.
+        // Its one method, then `Button`'s: `0x4c1be0` probes its map `0xb71b64`, then `0x782c90`.
         Some(FrameKind::LootButton) => &[
             super::loot::REG_LOOTBUTTON_METHODS,
             super::button::REG_BUTTON_METHODS,
@@ -572,27 +486,20 @@ fn kind_method_registries(lua: &Lua, this: &Table) -> &'static [&'static str] {
             super::button::REG_CHECKBUTTON_METHODS,
             super::button::REG_BUTTON_METHODS,
         ],
-        // The Model pane's own surface. Its absence is what stopped pfUI — and, through pfUI's
-        // embedded copies, pfQuest, pfQuest-turtle and ShaguDPS — on `SetModel` after the whole
-        // rest of their UI had already built (`super::modelframe`'s header).
         Some(FrameKind::Model) => &[super::modelframe::REG_MODEL_METHODS],
-        // The chain, not a repetition: `CGCharacterModelBase`'s lookup `0x506260` probes its own
-        // 3-entry map and on a miss tail-calls `CSimpleModel`'s `0x76f870`. Order is the miss
-        // order — three names of its own, then all 23 of `Model`'s.
+        // Its 3 methods, then `Model`'s 23: `0x506260` misses into `0x76f870`.
         Some(FrameKind::PlayerModel) => &[
             super::modelframe::REG_PLAYERMODEL_METHODS,
             super::modelframe::REG_MODEL_METHODS,
         ],
-        // Three of its own, then PlayerModel's three, then Model's 23: `CGDressUpModelFrame`'s
-        // lookup probes `0x84f190` and misses into `CGCharacterModelBase`'s `0x506260`, which
-        // misses into `CSimpleModel`'s `0x76f870` (1969).
+        // 3 of its own (`0x84f190`), then `PlayerModel`'s 3 (`0x506260`), then `Model`'s 23
+        // (`0x76f870`).
         Some(FrameKind::DressUpModel) => &[
             super::dressup::REG_DRESSUPMODEL_METHODS,
             super::modelframe::REG_PLAYERMODEL_METHODS,
             super::modelframe::REG_MODEL_METHODS,
         ],
-        // Ten of its own (`0x84ee40`), then PlayerModel's three, then Model's 23 — the same
-        // derived → base probe as its sibling (1977).
+        // 10 of its own (`0x84ee40`), then `PlayerModel`'s 3, then `Model`'s 23.
         Some(FrameKind::TabardModel) => &[
             super::tabard::REG_TABARDMODEL_METHODS,
             super::modelframe::REG_PLAYERMODEL_METHODS,
@@ -604,58 +511,30 @@ fn kind_method_registries(lua: &Lua, this: &Table) -> &'static [&'static str] {
     }
 }
 
-/// `CreateFrame(kind, name?, parent?, inherits?)` — the runtime frame factory.
-///
-/// The fourth argument is a **template name list**, and honouring it is what makes
-/// `CreateFrame("Button", "MyButton", UIParent, "UIPanelButtonTemplate")` — the corpus's most
-/// common single line — produce a button with art, regions, scripts and a fired `OnLoad` rather
-/// than an empty frame. The frame is created first and decorated second
-/// ([`crate::loader::apply_template`]), in that order and never the other way: the template's own
-/// `OnLoad` must be able to see the frame's real name, and `$parent` inside the template must
-/// resolve against **the caller's** name, not the template's.
-///
-/// An **unresolvable** template name raises `CreateFrame(): Couldn't find inherited node "%s"` and
-/// creates nothing — the reference's own behaviour, byte-verified (`0x7061dd` → `luaL_error`, which
-/// never returns). A template that resolves but is *unusable in some other way* — declared without
-/// `virtual="true"`, or of a shape that does not fit the kind asked for — is still a warning plus a
-/// working frame, because the registry lookup itself succeeded and that is the only thing the miss
-/// branch tests.
+/// `CreateFrame(kind, name?, parent?, inherits?)` (`0x7060b0`), the runtime frame factory.
+/// `inherits` names one template, applied after the frame is made
+/// ([`crate::loader::apply_template`]) so its `OnLoad` sees the frame's real name and its `$parent`
+/// resolves against the caller's name. An unknown template raises `Couldn't find inherited node`
+/// and creates nothing (`0x7061dd`); a known but unusable one (not virtual, or the wrong shape)
+/// only warns, since the lookup itself succeeded.
 pub(super) fn create_frame(
     lua: &Lua,
     (kind, name, parent, inherits): (String, Option<Value>, Option<Value>, Option<Value>),
 ) -> mlua::Result<Table> {
-    // The Lua door's miss RAISES: `0x7060b0` reaches `"CreateFrame: Unknown frame type '%s'"`
-    // (`0x872fa8`) through `luaL_error 0x6f4940`, which never returns. The XML door's does not —
-    // see [`registered_frame_kind`].
+    // An unknown type raises. The reference's message (`0x872fa8`) capitalises `Unknown`, and it
+    // tests the template first (`0x7061dd`), raising for the type only at `0x7062a0`.
     let frame_kind = registered_frame_kind(lua, &kind)
         .ok_or_else(|| mlua::Error::runtime(format!("CreateFrame: unknown frame type '{kind}'")))?;
-    // **`name` and `inherits` are `lua_tostring` positions, and a NUMBER is a string to it.**
-    // `0x7060b0` reads both through `0x6f3690` with no type guard at all, so `CreateFrame("Frame",
-    // 5)` names the frame `"5"` — a `Value::String`-only match drops it (wow-re
-    // `ui/scratch/xml-template-name-lookup.md` §5.2).
-    //
-    // The fourth argument's quirk, which is real and reads like a bug in the client: `lua_tostring`
-    // runs at `0x70613f` **before** the `cmp 4` gate, and `0x6f7cb1 mov dword ptr [esi],0x4`
-    // retags the number's stack slot **in place** — so by the time the tag is tested it IS a
-    // string. `CreateFrame("Frame", nil, nil, 5)` therefore raises `Couldn't find inherited node
-    // "5"`, while `f:CreateTexture(nil, nil, 5)` silently ignores the 5, because the region
-    // constructors ask `lua_type` first and never coerce. Same value, opposite outcome, decided by
-    // argument order alone — which is why this is spelled out rather than shared with them.
+    // `name` and `inherits` go through `lua_tostring` (`0x6f3690`) unguarded, so a number is a
+    // string: `CreateFrame("Frame", 5)` names the frame "5". For `inherits` the conversion runs
+    // before the string-type gate and retags the slot (`0x70613f`, `0x6f7cb1`), so a number there
+    // raises as a missing template, where `CreateTexture` ignores one.
     let name: Option<String> = name.as_ref().and_then(|v| optional_string(lua, v));
     let template: Option<String> = inherits.as_ref().and_then(|v| optional_string(lua, v));
 
-    // Resolve the parent handle (a wrapper table, or a name string) under a short read borrow.
-    //
-    // **The name-string arm is OURS, and the reference RAISES on it** — `0x7060b0` asks
-    // `lua_type` three times and `cmp eax,5`: a table is the parent, nil/absent means no parent,
-    // and a string takes the error leg (`xml-template-name-lookup.md` §5.2's per-position table).
-    //
-    // It is **parked, not pruned**, on the same footing as `TEXTURE_ONLY_METHODS`' tail three: the
-    // §5 established *that* it raises but did not quote the message, and inventing the text of a
-    // client error is exactly what decision 1721 was written about — a plausible string in the
-    // voice of a finding. Measured meanwhile: **zero** call sites pass a string parent, in the
-    // 109-folder corpus or in our own FrameXML, so the superset is unreachable in practice and
-    // removing it blind would buy nothing. Pruning it needs the message, not more confidence.
+    // A table is the parent and a name string is looked up; anything else is no parent. The
+    // reference raises `Usage: CreateFrame(...)` (`0x872f60`) for anything but a table or nil
+    // (`0x706112`).
     let parent_handle: Option<FrameHandle> = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         match &parent {
@@ -667,10 +546,8 @@ pub(super) fn create_frame(
         }
     };
 
-    // A 4th argument that is present but neither a string nor a number is **silently ignored by
-    // the reference** — `lua_tostring` returns NULL for it and the `cmp 4` gate then falls into
-    // the ordinary construction path. So this is a benilla-only diagnostic and stays a WARNING,
-    // never a raise: it tells a reader something was dropped without changing what runs.
+    // The reference silently ignores a fourth argument that is neither string nor number
+    // (`0x7061cb`); the warning is ours and changes nothing.
     if template.is_none() {
         if let Some(v) = inherits.as_ref().filter(|v| !v.is_nil()) {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -683,30 +560,15 @@ pub(super) fn create_frame(
         }
     }
 
-    // ── THE TEMPLATE LOOKUP HAPPENS HERE — before anything is constructed or published ──────────
-    //
-    // `0x7061dd` calls the registry lookup `0x6ee6f0` and, on NULL, falls into
-    // `luaL_error(L, "CreateFrame(): Couldn't find inherited node \"%s\"")` at `0x7061ed`. That
-    // never returns — `luaG_errormsg`/`luaD_throw` contain no `ret` at all and end in `longjmp`, so
-    // the `xor eax,eax; ret` after the call is dead code. The frame is **not created**, no global
-    // is published, and the calling statement is abandoned; the error is ordinary Lua propagation
-    // and `pcall`-catchable, which is how the widget dispatcher (`0x704f10`, every handler under
-    // `lua_pcall`) turns it into one dead handler rather than a dead client.
-    //
-    // We used to warn and hand back a usable bare frame, and the doc above said the reference
-    // "creates the frame anyway". That claim is refuted at the bytes. It is the same class as 1249:
-    // a failure the client reports and we swallowed — and swallowing is the worse half, because the
-    // addon then runs on a frame with none of the art, regions or scripts it asked for and fails
-    // later, somewhere unrelated.
-    //
-    // Ordering is the carved part, not a detail: the miss branch precedes the synthetic-node build
-    // (`0x706208`) and the `name` store (`0x70622d`), so a miss leaves no partial widget and no
-    // orphan global behind. Doing this after construction would leave both.
+    // The template lookup comes before anything is built: a miss (`0x7061dd` → `0x6ee6f0`) raises
+    // at `0x7061ed`, before the node build (`0x706208`) and the name store (`0x70622d`), so it
+    // leaves no partial widget and no global. The raise never returns and `pcall` catches it, as
+    // the widget dispatcher (`0x704f10`) does for every handler.
     if let Some(t) = template.as_deref().filter(|t| !t.is_empty()) {
         let known = {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let templates = model.framexml_templates.borrow();
-            // One name, verbatim, folded — the law `framexml::expand` resolves under.
+            // One name, verbatim, case-folded, as `framexml::expand` resolves it.
             templates.contains_key(t) || templates.keys().any(|k| k.eq_ignore_ascii_case(t))
         };
         if !known {
@@ -716,20 +578,9 @@ pub(super) fn create_frame(
         }
     }
 
-    // **A leading `$parent` in the NAME is expanded, here as in XML.** `CreateFrame 0x7060b0`
-    // does not store the name itself: it builds a synthetic node, sets `name=` on it
-    // (`0x706225 push 0x838090 "name"` → `0x70622d` SetAttribute) alongside `parent=` and
-    // `inherits=`, and hands it to the XML frame builder `0x6ee280` with the parent object in
-    // `edx` — so the name reaches `CScriptRegion::SetName 0x76c650` by exactly the route an XML
-    // `name=` does, and `0x76c691` is one of the expander's two call sites (wow-re
-    // `name-string-widget-resolution.md` §5/§6).
-    //
-    // The base is the frame's **parent's** first named ancestor — the same walk `$parent` in a
-    // `relativeTo` takes, one link higher than the anchoring frame's own.
-    //
-    // Not academic: `FonzAppraiser` names every widget it builds this way (`"$parentDropdown"..n`,
-    // `"$parentCloseButton"`, ~30 sites), and until decision 2176 made an unresolvable anchor
-    // raise, the unexpanded name only showed up as a warning nobody read.
+    // A leading `$parent` in the name expands as in XML: `CreateFrame` sets `name=` on a synthetic
+    // node (`0x70622d`) for the XML builder `0x6ee280`, so the name reaches `SetName` (`0x76c650`),
+    // whose `0x76c691` call expands it against the parent's first named ancestor.
     let name = name.map(|n| {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         crate::framexml::resolve_name(&n, &parent_token_base(&model, parent_handle))
@@ -742,12 +593,8 @@ pub(super) fn create_frame(
         if frame_kind == FrameKind::WorldFrame {
             model.world_frame_made = true;
         }
-        // The client's CreateFrame inheritance (the ctor doc's "loader/CreateFrame concern" —
-        // widget/mod.rs `create`): a child enters its PARENT's stratum at the parent's level + 1.
-        // The ctor's bare MEDIUM/0 left a DIALOG-strata popup drawing its own translucent
-        // backdrop OVER its buttons (the children stayed in MEDIUM — the abandon dialog's dark
-        // buttons, pixel-diffed against the raw art). An explicit frameStrata/frameLevel attr
-        // still overrides right after (apply_attrs).
+        // A child enters its parent's stratum at the parent's level + 1; an explicit
+        // `frameStrata` or `frameLevel` still overrides it afterwards.
         if let Some(p) = parent_handle {
             if let Some((pstrata, plevel)) = model.arena.frame(p).map(|f| (f.strata, f.level)) {
                 model.arena.set_frame_strata(h, pstrata);
@@ -759,10 +606,8 @@ pub(super) fn create_frame(
         id
     };
 
-    // The wrapper exists (and, if named, is published to `_G`) BEFORE the template runs — a
-    // template's `OnLoad` fires inside this call, and the reference's addons rely on both facts:
-    // `local b = CreateFrame(...)` hands back a frame whose OnLoad has already run, and that
-    // handler can reach itself by name.
+    // The wrapper exists, published under its name, before the template's `OnLoad` runs inside
+    // this call, so the handler can reach the frame by name.
     let wrapper = frame_wrapper(lua, id)?;
     if let Some(template) = template {
         let messages = crate::loader::apply_template(lua, &wrapper, &kind, &template);
@@ -777,11 +622,10 @@ pub(super) fn create_frame(
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// Frame method surface — the table itself is built by the three clusters above
+// Frame method surface
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 
-/// Build the shared frame method table from the five clusters ([`frame_state`], [`layout_methods`],
-/// [`events_regions`], [`movable`], [`toplevel`]) and publish it to the registry.
+/// Build the shared frame method table from its five clusters and publish it to the registry.
 fn install_frame_methods(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
     frame_state::install(lua, &m)?;
@@ -793,8 +637,8 @@ fn install_frame_methods(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `0x48c270`'s law: `g = 0.75 · aspect`, and the scale is `g` below 1.0, else 1.0 — NaN lands on
-/// the 1.0 leg (the `fcomp` compare fails every ordered test).
+/// `0x48c270`'s scale: `0.75 · aspect` below 1.0, else 1.0; NaN takes the 1.0 leg, as the
+/// reference's `fcomp` fails every ordered test.
 pub(crate) fn fullscreen_scale(aspect: f32) -> f32 {
     let g = 0.75 * aspect;
     if g < 1.0 {
diff --git a/crates/benilla-ui/src/script/object/anchor_args.rs b/crates/benilla-ui/src/script/object/anchor_args.rs
index 2b9cb7cd..fade7e05 100644
--- a/crates/benilla-ui/src/script/object/anchor_args.rs
+++ b/crates/benilla-ui/src/script/object/anchor_args.rs
@@ -1,23 +1,6 @@
-//! `SetPoint`/`SetAllPoints`' argument ladder — **one** transcription of `0x7a2540` / `0x7a2940`.
-//!
-//! The two bindings are `CScriptRegion` methods registered **once**, at `.data 0x87ca38` and
-//! `0x87ca40` inside the 19-record table `[0x87c9b8, 0x87ca50)` whose registrar `0x7a2e70` supplies
-//! base and count — so Frame, Texture, FontString and Model all run the *same* function (wow-re
-//! `system/ui/ui.md` §(b2), `scratch/name-string-widget-resolution.md` §3-4, ledger rows
-//! `0x7a2540`/`0x7a2940`). This module is that single function's argument half; what each caller
-//! keeps for itself is only the thing the reference reads off the receiver — the layout parent's
-//! default id, and where the anchor is stored.
-//!
-//! **Every failure leg RAISES**, which is the point of the module (decision 2176, closing 2105's
-//! "Named, not done"). `luaL_error` does not return: `luaG_errormsg [0x6fc780,0x6fc861)` and
-//! `luaD_throw [0x6f5d80,0x6f5da5)` hold zero `ret`s, and `luaD_throw`'s *elided* epilogue is the
-//! positive control that says so. There is no fallback and no silent no-op on any of them.
-//!
-//! The **XML** `<Anchor relativeTo=>` path is a different function and a different law — it
-//! resolves through the same `0x76c700` but reports `"Couldn't find relative frame: %s"` at
-//! severity 1 and **skips the anchor** (`0x767969 test ebx,ebx` → `0x76796d` → `jmp 0x7679dd`,
-//! past the `0x7679c8 call 0x767c70`). That half lives in `crate::loader::geometry`, which
-//! therefore resolves its own names and never reaches the ladder here.
+//! The argument ladder of `SetPoint` (`0x7a2540`) and `SetAllPoints` (`0x7a2940`): the reference
+//! registers both once, in the Region method table (`0x87c9b8`), so every widget type runs the
+//! same function. Every failure leg raises; none falls back to the parent or does nothing.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -26,30 +9,19 @@ use crate::script::{Model, SCREEN};
 
 use super::{decode_id, point_from_str, prefetch_named_target, resolve_named_target, NamedTarget};
 
-/// What the reference prints where a widget has no name — the literal `0x84c7f0`, reached from
-/// `call [primary_vt+0x4]` (`GetName` → `[widget+0x98]`) returning NULL.
+/// The name the reference prints for a widget that has none (the literal at `0x84c7f0`).
 pub(crate) const UNNAMED: &str = "<unnamed>";
 
-/// `relativeTo`, decoded — the four tags `lua_type(L,3)` accepts (`0x7a25e6`–`0x7a2620`); anything
-/// else, **absent included** (`TNONE` = −1), is a Usage raise on the `SetPoint` side.
+/// `relativeTo` by the four tags `lua_type(L,3)` accepts (`0x7a25e6`..`0x7a2620`); any other tag,
+/// absent included, raises Usage in `SetPoint`.
 pub(crate) enum RelTarget {
-    /// A widget wrapper table (`0x7a26c9`: `rawgeti(3,0)` → `touserdata` → `+0x24`).
-    ///
-    /// **The reference runs no `IsA` check on this arm** — unlike the `this` ladder and unlike the
-    /// string arm, whose check lives inside `0x76c760` — so `add eax,0x24` is applied to whatever
-    /// `lua_touserdata` returned and a table carrying any light userdata at `[0]` is accepted as a
-    /// widget. That is a wild pointer, not a behaviour: [`resolve_rel_target`] takes the layout
-    /// parent for a table that decodes to no live widget, and says so there.
+    /// A widget wrapper table (`0x7a26c9`); the reference runs no `IsA` check on it.
     Wrapper(Table),
     /// A name string, already read out of `_G` with no `Model` guard alive ([`NamedTarget`]).
     Named(NamedTarget),
-    /// An explicit `nil` — the **screen root** `ds:[0xcf0bd8]` (`0x7a2710`), *not* the parent. One
-    /// stock site takes it (`UIParent.lua:1549`) and fourteen corpus sites do, every one of them
-    /// meaning "the screen" (`pfUI`'s screenshot caption, `FixCTGroups`' cursor-space plate).
+    /// An explicit `nil`: the screen root `ds:[0xcf0bd8]` (`0x7a2710`), not the parent.
     Screen,
-    /// A NUMBER in the `relativeTo` slot: `edi` stays 3 and the number is `offsetX` — the
-    /// `SetPoint(point, x, y)` shorthand (`0x7a270e`). `relativeTo` keeps the layout parent's
-    /// default (`0x76c6e0`: `[+0x9c]`'s layout sub-object, else the screen root).
+    /// A number: the `SetPoint(point, x, y)` shorthand (`0x7a270e`), against the default parent.
     DefaultParent,
 }
 
@@ -62,7 +34,7 @@ pub(crate) struct PointArgs {
     pub(crate) y: f32,
 }
 
-/// `Usage: %s:SetPoint(…)` — `luaL_error(0x87cc28)`, the string read out of the reference image.
+/// The reference's `Usage:` raise (`0x87cc28`).
 fn usage(who: &str) -> mlua::Error {
     mlua::Error::runtime(format!(
         "Usage: {who}:SetPoint(\"point\" [, region or nil] [, \"relativePoint\"] \
@@ -70,28 +42,24 @@ fn usage(who: &str) -> mlua::Error {
     ))
 }
 
-/// `%s:SetPoint(): Unknown region point` — `0x87cd04`, raised by the 9-entry name scan `0x6f1840`
-/// for either the `point` or a `relativePoint` that is a string it rejects.
+/// `0x87cd04`: the point-name scan `0x6f1840` rejected `point` or a string `relativePoint`.
 fn unknown_point(who: &str) -> mlua::Error {
     mlua::Error::runtime(format!("{who}:SetPoint(): Unknown region point"))
 }
 
-/// `%s:%s(): Couldn't find region named '%s'` — `0x87ccd4` for `SetPoint`, `0x87cd84` for
-/// `SetAllPoints`. **No fallback and no no-op**: this is the leg benilla answered with the parent
-/// plus a warning until 2176.
+/// `0x87ccd4` for `SetPoint`, `0x87cd84` for `SetAllPoints`: a raise, never a fallback.
 pub(crate) fn no_such_region(who: &str, verb: &str, name: &str) -> mlua::Error {
     mlua::Error::runtime(format!(
         "{who}:{verb}(): Couldn't find region named '{name}'"
     ))
 }
 
-/// `%s:%s(): trying to anchor to itself` — `0x87cca8` / `0x87cd54`, the `[ebp-4] == this+0x24`
-/// compare at `0x7a2764` / `0x7a2aa8`.
+/// `0x87cca8` / `0x87cd54`, from the self compare at `0x7a2764` / `0x7a2aa8`.
 fn anchor_to_self(who: &str, verb: &str) -> mlua::Error {
     mlua::Error::runtime(format!("{who}:{verb}(): trying to anchor to itself"))
 }
 
-/// `lua_isnumber 0x6f34d0` — a number, or a string Lua can read as one.
+/// `lua_isnumber` (`0x6f34d0`): a number, or a string Lua reads as one.
 fn as_number(lua: &Lua, v: &Value) -> Option<f32> {
     lua.coerce_number(v.clone())
         .ok()
@@ -99,7 +67,7 @@ fn as_number(lua: &Lua, v: &Value) -> Option<f32> {
         .map(|n| n as f32)
 }
 
-/// `lua_isstring 0x6f3510` — tag 4 **or** 3, so a number is a string here.
+/// `lua_isstring` (`0x6f3510`): a string or a number.
 fn as_string(lua: &Lua, v: &Value) -> Option<String> {
     match v {
         Value::String(_) | Value::Number(_) | Value::Integer(_) => lua
@@ -111,29 +79,20 @@ fn as_string(lua: &Lua, v: &Value) -> Option<String> {
     }
 }
 
-/// Parse `SetPoint(point [, relativeTo [, relativePoint]] [, x, y])` in the reference's own order:
-/// the two tag gates first (both Usage), then the point-name scan, then `relativePoint`, then the
-/// offsets. The order is observable — an unknown point with an *absent* `relativeTo` raises Usage,
-/// not "Unknown region point".
-///
-/// `who` names the receiver for the error strings, and `parent_base` is what a leading `$parent`
-/// expands to. Both are the caller's to compute, under a short `Model` borrow, **before** this
-/// runs: the `_G` read here is a `lua_gettable` and an `__index` on `_G` can call straight back
-/// into a binding ([`NamedTarget`]).
+/// Parse `SetPoint` in the reference's order: both tag gates (Usage), the point-name scan,
+/// `relativePoint`, the offsets; so an unknown point with no `relativeTo` raises Usage. The caller
+/// computes `who` and `parent_base` first, since an `__index` on `_G` can call back into a binding.
 pub(crate) fn parse_set_point(
     lua: &Lua,
     args: &MultiValue,
     who: &str,
     parent_base: &str,
 ) -> mlua::Result<PointArgs> {
-    // arg 2 = point. `lua_isstring(L,2)` false → `0x7a290d` Usage (`0x7a25d2`).
     let point_str = args.front().and_then(|v| as_string(lua, v));
     let Some(point_str) = point_str else {
         return Err(usage(who));
     };
 
-    // arg 3 = relativeTo. `lua_type(L,3)` ∈ {4 STRING, 5 TABLE, 0 NIL, 3 NUMBER}, else Usage —
-    // and an **absent** argument is `TNONE` = −1, which fails all four (`0x7a25e6`–`0x7a2620`).
     let Some(rel_arg) = args.get(1) else {
         return Err(usage(who));
     };
@@ -148,13 +107,10 @@ pub(crate) fn parse_set_point(
         _ => return Err(usage(who)),
     };
 
-    // The point name, scanned by `0x6f1840` only now (`0x7a264a`) — after both tag gates.
     let point = point_from_str(&point_str).ok_or_else(|| unknown_point(who))?;
 
-    // `relativePoint` is seeded from `point` (`0x7a2697`) and read at index `edi`, which the
-    // number arm above left at 3 and every other arm advanced to 4. **Only a STRING is consumed**
-    // (`0x7a2810 lua_type == 4`, strictly — not `lua_isstring`); anything else leaves the seed and
-    // the offsets are taken from here.
+    // `relativePoint` defaults to `point` (`0x7a2697`) and is consumed only when strictly a string
+    // (`0x7a2810`), else the offsets start here; the number arm reads one slot earlier.
     let mut cur = if matches!(target, RelTarget::DefaultParent) {
         1
     } else {
@@ -167,8 +123,7 @@ pub(crate) fn parse_set_point(
         cur += 1;
     }
 
-    // **Both offsets, or neither** (`0x7a2888 je 0x7a28e6`): each is gated on `lua_isnumber`, and
-    // one failing zeroes the pair rather than only itself.
+    // Both offsets or neither: one failing `lua_isnumber` zeroes both (`0x7a2888` → `0x7a28e6`).
     let (x, y) = match (
         args.get(cur).and_then(|v| as_number(lua, v)),
         args.get(cur + 1).and_then(|v| as_number(lua, v)),
@@ -186,20 +141,13 @@ pub(crate) fn parse_set_point(
     })
 }
 
-/// Parse `SetAllPoints([relativeTo])` (`0x7a2940`) — **the same resolver, a different argument
-/// law**, and the three differences are per-binding facts rather than a family rule:
-///
-/// 1. An **omitted** argument is legal: it falls through to the layout parent with no raise, where
-///    `SetPoint` raises Usage.
-/// 2. The name path is gated on **`lua_isstring`** (`0x7a29ea`), tag 4 **or** 3 — so
-///    `f:SetAllPoints(42)` stringifies and looks up `_G["42"]`, where `SetPoint` tests
-///    `lua_type == 4` strictly and routes a number to the offset shorthand.
-/// 3. There is no `relativePoint` or offset parsing at all.
+/// Parse `SetAllPoints([relativeTo])` (`0x7a2940`). Unlike `SetPoint`, an omitted argument takes
+/// the layout parent, and a number is a name (`lua_isstring`, `0x7a29ea`): `SetAllPoints(42)`
+/// looks up `_G["42"]`.
 pub(crate) fn parse_set_all_points(lua: &Lua, arg: Option<&Value>, parent_base: &str) -> RelTarget {
     match arg {
         Some(Value::Table(t)) => RelTarget::Wrapper(t.clone()),
         Some(Value::Nil) => RelTarget::Screen,
-        // `lua_isstring` — a NUMBER takes the name path here, unlike `SetPoint`.
         Some(v) => match as_string(lua, v) {
             Some(n) => RelTarget::Named(prefetch_named_target(lua, &n, Some(parent_base))),
             None => RelTarget::DefaultParent,
@@ -208,11 +156,9 @@ pub(crate) fn parse_set_all_points(lua: &Lua, arg: Option<&Value>, parent_base:
     }
 }
 
-/// Turn a parsed [`RelTarget`] into the layout id to anchor against, raising the reference's own
-/// errors. `me` is the receiver's own id — the self-anchor compare (`0x7a2764` / `0x7a2aa8`).
-///
-/// The **wrapper** arm takes `default_parent` where the reference would take a wild pointer (see
-/// [`RelTarget::Wrapper`]); every other arm is the reference's.
+/// Resolve a [`RelTarget`] to the layout id to anchor to, raising the reference's errors; `me` is
+/// the receiver, for the self-anchor check. Deviation: a wrapper that decodes to no live widget
+/// takes `default_parent`, because the reference, with no `IsA` check, reads a wild pointer.
 pub(crate) fn resolve_rel_target(
     model: &Model,
     target: &RelTarget,
@@ -238,25 +184,14 @@ pub(crate) fn resolve_rel_target(
     Ok(id)
 }
 
-/// The **XML** `<Anchor relativeTo="name">` resolution — `CLayoutFrame::LoadXML 0x767800`'s own,
-/// which is a different law from the Lua ladder above and belongs to `crate::loader`.
-///
-/// `0x767964 call [eax+0x28]` is the same `0x76c700` the Lua string arm uses, so the *lookup* is
-/// identical; what differs is the miss. `0x767969 test ebx,ebx` → `0x76796d` pushes
-/// `0x878440 "Couldn't find relative frame: %s"` at severity 1 through the XML report's
-/// `[ecx+0xc]` and then `jmp 0x7679dd`, which lands **past** the `0x7679c8 call 0x767c70` — the
-/// anchor is reported and SKIPPED. It does not raise (there is no Lua state to unwind here) and it
-/// does not fall back to the parent, which is what benilla did until 2176.
-///
-/// `$parent` is already expanded by the caller, so no base is taken.
+/// The XML `<Anchor relativeTo>` lookup (`CLayoutFrame::LoadXML 0x767800`), `$parent` already
+/// expanded: the Lua string arm's resolver (`0x76c700`), but a miss reports "Couldn't find
+/// relative frame" (`0x878440`) and skips the anchor (`0x767969`) without raising or falling back.
 pub(crate) fn resolve_xml_relative_to(lua: &Lua, name: &str) -> Option<Table> {
-    // ONE `_G` read, and the wrapper it produced is the one handed back — re-reading `_G` to fetch
-    // the table again would be a second `lua_gettable`, and an `__index` is allowed to answer
-    // twice differently.
+    // One `_G` read, its wrapper returned: an `__index` may answer a second read differently.
     let nt = prefetch_named_target(lua, name, None);
     let model = lua.app_data_ref::<Model>().expect("model");
     resolve_named_target(&model, &nt)?;
-    // The wrapper the ladder's TABLE arm takes — resolved here so the binding never sees a name
-    // from the XML path and so its raise can never reach a loading document.
+    // A wrapper, not a name, so the Lua ladder's raise can never reach a loading document.
     nt.wrapper.clone()
 }
diff --git a/crates/benilla-ui/src/script/object/events_regions.rs b/crates/benilla-ui/src/script/object/events_regions.rs
index 866eedf2..750d880f 100644
--- a/crates/benilla-ui/src/script/object/events_regions.rs
+++ b/crates/benilla-ui/src/script/object/events_regions.rs
@@ -1,8 +1,4 @@
-//! Frame method-table cluster: event registration + script handlers (`RegisterEvent`/
-//! `UnregisterEvent`/`SetScript`/`GetScript`), the drag-gesture registration (`RegisterForDrag`,
-//! decision 0216 §3), and region creation (`CreateTexture`/`CreateFontString`). Split out of
-//! [`super`] purely for size — see its module doc for the shared id/handle plumbing and
-//! method-table wiring.
+//! Frame methods: event registration, script handlers, drag registration and region creation.
 
 use std::collections::HashSet;
 
@@ -15,7 +11,7 @@ use crate::widget::RegionKind;
 
 use super::{decode_id, draw_layer_from_str, frame_handle_of, publish_global};
 
-/// Populate `m`'s event/script and region-creation methods (see the module doc).
+/// Populate `m`'s event, script and region-creation methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     // Events + scripts
     m.set(
@@ -23,8 +19,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, (this, event): (Table, String)| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Ordered listener list (the client's SignalEvent walks a LIST — order is law);
-            // re-register keeps the original position (no duplicate fire).
+            // Dispatch follows registration order, as the reference's listener list does; a
+            // re-register keeps its place and never fires twice.
             let list = model.event_to_frames.entry(event.clone()).or_default();
             if !list.contains(&h) {
                 list.push(h);
@@ -47,59 +43,32 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `RegisterAllEvents()` — this frame's `OnEvent` receives EVERY event that is dispatched
-    // (`0x774c20`, table `0x878ec0`, argc 1, arity 0). Cleared by `UnregisterAllEvents` below, and
-    // by nothing else: there is no `UnregisterAllEvents`-less way back out, which is exactly how
-    // the reference's pair reads.
-    //
-    // **Latent, not live, and the widest-carried gap the corpus census found.** Nothing in either
-    // addon corpus calls it *today*, but 63 vanilla addons and 6 of the top 20 ship
-    // **AceEvent-2.0**, whose `AceEvent:RegisterAllEvents(handler)` runs
-    // `AceEvent.frame:RegisterAllEvents()` the first time any addon asks for all events — so the
-    // first one that does raised here. AceEvent is also why the *clearing* half is load-bearing
-    // rather than tidy: while all-events is on it deliberately stops calling
-    // `frame:UnregisterEvent(event)` at all, and `AceEvent:UnregisterAllEvents()` gets back to a
-    // per-event registration by calling `frame:UnregisterAllEvents()` and then re-registering each
-    // event it still wants. A `RegisterAllEvents` that outlived that call would leave every Ace2
-    // addon on the whole event stream forever.
-    //
-    // Registered as a FLAG (the frame joins `Model::all_event_frames`), never as an expansion into
-    // a name list — see that field for why, and `tick::fire_event_into` for the dispatch.
+    // `RegisterAllEvents()` (`0x774c20`): the frame's `OnEvent` receives every event until
+    // `UnregisterAllEvents`, the only way out. A flag (`Model::all_event_frames`), not a name list.
     m.set(
         "RegisterAllEvents",
         lua.create_function(|lua, this: Table| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Registration order, and re-registering keeps the original position — the same law
-            // `RegisterEvent` above holds, for the same reason.
             if !model.all_event_frames.contains(&h) {
                 model.all_event_frames.push(h);
             }
             Ok(())
         })?,
     )?;
-    // `UnregisterAllEvents()` — drop every registration this frame holds, in one call.
-    //
-    // 10 corpus addons stop on it (decision 1195), and the idiom is why: an addon's "disable me"
-    // path is `self.frame:UnregisterAllEvents()`, and a library that pools frames calls it before
-    // handing one out. Unregistering them one by one is not equivalent — the caller does not know
-    // what it registered, which is the whole point of the verb.
+    // `UnregisterAllEvents()`: drops every registration the frame holds.
     m.set(
         "UnregisterAllEvents",
         lua.create_function(|lua, this: Table| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Take the frame's OWN set first, then walk only the events it actually held — the
-            // alternative (sweeping every listener list in the model) is O(all events) per call,
-            // and libraries call this in loops over a frame pool.
             let events = model.frame_events.remove(&h).unwrap_or_default();
             for event in events {
                 if let Some(list) = model.event_to_frames.get_mut(&event) {
                     list.retain(|x| x != &h);
                 }
             }
-            // …and the all-events registration, which is a registration like any other. See
-            // `RegisterAllEvents` above: AceEvent-2.0's own re-registration path depends on this.
+            // All-events mode too: AceEvent-2.0 leaves it through this call.
             model.all_event_frames.retain(|x| x != &h);
             Ok(())
         })?,
@@ -116,33 +85,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "GetScript",
         lua.create_function(|lua, (this, name): (Table, String)| get_script(lua, &this, &name))?,
     )?;
-    // HasScript(name) — "can this widget carry that script kind at all", NOT "does it have one
-    // set". The distinction is the whole point of the verb: every caller in the corpus uses it to
-    // decide whether it is safe to hook, then reads the current handler separately.
-    //
-    //     if parent:HasScript("OnMouseDown") then                    -- Tablet-2.0.lua:2409
-    //         local script = parent:GetScript("OnMouseDown")         -- FuBar-compat:2422
-    //         parent:SetScript("OnMouseDown", function() … end)
-    //     end
-    //
-    // It was the top session-start blocker: 32 of the 39 `attempt to call method` failures were
-    // this one name, across the Tablet/FuBar/oRA2 stack.
-    //
-    // ANSWERED FROM THE FLAT `SCRIPT_KINDS`, and that is a deliberate, stated approximation rather
-    // than the full answer. The reference's table is PER WIDGET TYPE — a plain Frame really does
-    // answer false for `OnClick` — so ours is over-permissive for the type-specific kinds. It is
-    // exactly right for the base kinds, which is what every corpus caller asks about
-    // (`OnMouseDown` here; a Frame genuinely has it). The cost of the over-permission is small and
-    // worth naming: an addon that asks about a type-specific kind installs a handler that never
-    // fires, where the reference would have had it skip. That is the same latitude `SetScript`
-    // already takes — this verb does not widen it, it just stops lying about its existence.
-    //
-    // Making it exact means per-type SCRIPT_KINDS, which newly RAISES on 30 sites that work today
-    // (9 in our own FrameXML). That is behaviour removal and belongs in its own change, with its
-    // own measurement; it is not a tail on this one.
-    //
-    // 1/nil, not a Lua boolean: the reference's row is `(nil) | (number)` like every other
-    // predicate (decision 2118).
+    // `HasScript(name)`: 1 if the widget can carry that script kind, else nil, whether or not one
+    // is set. Answered from the flat `SCRIPT_KINDS`, so another type's kind reads 1 too, where the
+    // reference's tables are per widget type (base `0x76a0d0`; a plain Frame has no `OnClick`).
     m.set(
         "HasScript",
         lua.create_function(|_, (_this, name): (Table, String)| {
@@ -151,13 +96,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // RegisterForDrag(...varargs of button names) — the drag-gesture twin of `RegisterForClicks`
-    // (decision 0216 §3), but on the SHARED table: any Frame can be a drag source, not just a
-    // Button. Replace-the-set semantics (empty varargs clears); `crate::script::cursor`'s
-    // arm/start/release path consults the set case-insensitively (the `RegisterForClicks`
-    // precedent). Pruning on frame destroy: see [`Model::drag_registered`]'s doc — nothing in
-    // this engine destroys a frame yet, so this map is in the same boat as `scripts`/
-    // `frame_events`.
+    // `RegisterForDrag(button, ...)` (`0x776d60`): on the shared table, since any frame can be a
+    // drag source; each call replaces the set (none clears it), matched case-insensitively.
     m.set(
         "RegisterForDrag",
         lua.create_function(|lua, (this, args): (Table, MultiValue)| {
@@ -174,28 +114,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
     // Regions
-    // `CreateTexture(name, layer, inheritsFrom)` — the third argument accepted for the same reason
-    // and with the same resolver, though the demand is a rounding error beside FontString's: of
-    // 1329 corpus call sites exactly TWO pass a third argument, and one of those passes `nil`
-    // (CustomNameplates:437, a four-argument later-client form). Accepted rather than skipped
-    // because dropping it silently is the very class this fixes, and one real site is still a site.
+    // `CreateTexture(name, layer, inherits)` (`0x773a20`).
     m.set(
-        // **The three argument positions are NOT one rule, and the fourth is the odd one.** Verified
-        // together in wow-re `ui/scratch/xml-template-name-lookup.md` §5.2:
-        //
-        //  · `name` and `layer` go through `0x6f3510` (is-number-**or**-string) then `0x6f3690`, and
-        //    **the result is never tested** — so a table is simply absent (unnamed / the pre-staged
-        //    default layer), and a NUMBER is accepted and stringified.
-        //  · `inherits` is gated by a raw `lua_type(L, 4) == LUA_TSTRING` (`0x773d28` / `0x773b06`)
-        //    asked BEFORE anything reads the slot — so a table AND a number are both ignored, and the
-        //    non-string leg jumps to the very block the two template-HIT legs jump to, with both
-        //    template handles NULL. It is the success path, not a bolted-on case.
-        //
-        // **Nothing here raises.** This mattered: benilla typed all three `Option<String>`, so mlua
-        // raised `bad argument #4: error converting Lua table to String` — and pfUI, the most-installed
-        // 1.12 addon, builds every buff-stack label as
-        // `f.buffs[i]:CreateFontString(nil, "OVERLAY", f.buffs[i])`, passing the BUTTON as the third
-        // argument. The real client constructs it, ignores the argument, and logs nothing.
+        // `name` and `layer` pass `lua_isstring` (`0x6f3510`, then `0x6f3690`) with the result
+        // unchecked, so a table is absent and a number is stringified: no argument type raises.
         "CreateTexture",
         lua.create_function(
             |lua, (this, name, layer, inherits): (Table, Value, Value, Value)| {
@@ -209,32 +131,12 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // ── The title region: Frame:CreateTitleRegion() / GetTitleRegion() ──────────────────────────
+    // ── Title region: CreateTitleRegion / GetTitleRegion ──
     //
-    // wow-re `system/ui/scratch/widget-api-batch-benilla.md` Q6 (`0x773910` / `0x773820`). Four
-    // details, each one a coin-flip a reimplementation loses:
-    //
-    //  · **It reads NO argument at all** — nothing in `0x773910`-`0x773a1f` touches Lua index 2. So
-    //    `CustomNameplates/options.lua:73`'s `CreateTitleRegion(optionsFrame)` is harmless and
-    //    identical to the no-arg call, rather than an error or a differently-parented region.
-    //  · **It is IDEMPOTENT, destructively.** One region per frame (`CSimpleFrame+0xA8`): a second
-    //    call runs ClearAllPoints on the existing one and returns THE SAME OBJECT — so calling it
-    //    on an XML-declared `<TitleRegion>` silently wipes that region's anchors. Returning a
-    //    fresh region instead would leave the first one hit-testing forever.
-    //  · **A fresh one has NO anchors** and does nothing until `SetPoint`/`SetAllPoints`. Both
-    //    corpus consumers immediately call `SetAllPoints`, which is the whole-window drag idiom.
-    //  · **`GetTitleRegion` answers 1 value (nil)** when there is none — note the asymmetry with
-    //    `GetBackdrop`, which answers 0 values. Q6 flags it explicitly; both converged
-    //    independently there, so both are reproduced here.
-    // **ONE NAMED DIVERGENCE, because it is a superset and 1189 is what a superset costs.** Q6 says
-    // the object answers *exactly* the 19 Region methods — no Show/Hide, no scripts, no textures.
-    // Ours answers the whole shared region table, because Texture/FontString/Title use one
-    // metatable here, so `titleRegion:SetTexture(…)` is accepted where the reference would raise
-    // `attempt to call method`. It is inert rather than wrong — a title region never draws (the
-    // extract skips its kind outright), so a texture or a Hide set on one changes nothing — but an
-    // addon that FEATURE-DETECTS would see a method the real client does not have. Splitting the
-    // metatable is the fix; it is not free, and nothing in the corpus asks, so this is recorded
-    // rather than hidden.
+    // `CreateTitleRegion` (`0x773910`) reads no argument and keeps one region per frame
+    // (`CSimpleFrame+0xA8`): a second call clears that region's anchors and returns it, and a new
+    // one has none. The reference's region answers only the 19 Region methods (`0x7a2ea0`); ours
+    // shares the region metatable, so it also accepts the texture methods, inertly.
     m.set(
         "CreateTitleRegion",
         lua.create_function(|lua, this: Table| {
@@ -283,27 +185,13 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             };
             match found {
                 Some(id) => Ok(Value::Table(region_wrapper(lua, id)?)),
-                // ONE value, and it is nil — not zero values. See the `GetBackdrop` asymmetry above.
+                // One nil value (`0x773820`), where `GetBackdrop` answers none.
                 None => Ok(Value::Nil),
             }
         })?,
     )?;
 
-    // The THIRD argument is `inheritsFrom`, and we were dropping it on the floor.
-    //
-    // 49 corpus call sites across 5 distinct addons pass one — AckisRecipeList (28),
-    // CustomNameplates (10), _LazyPig (6), LibAboutPanel (4), ColorPickerPlus (1) — and **every one
-    // of them names a FONT OBJECT**: GameFontNormalSmall (15), GameFontNormal (11),
-    // GameFontHighlightSmall (10), GameFontHighlight (9), GameFontNormalLarge (3), GameFontDisable.
-    // Five separate addons, so this is not one library file replicated (1207 checked, not assumed).
-    // Ignoring it is 1203's class exactly: the addon asks for a font, we accept the call, and the
-    // string comes out in whatever the default is with no failure anywhere.
-    //
-    // The resolution order is carved (`0x773c30`): the FONT-object registry FIRST (`0x773d39`,
-    // create=0), and only on a font miss the template registry (`0x773d47`). This routes through
-    // the `SetFontObject` binding rather than reaching into the model, which is the same call the
-    // XML `<FontString inherits=>` path makes — one implementation of "apply a font object", not
-    // two that can drift.
+    // `CreateFontString(name, layer, inherits)` (`0x773c30`), with the same argument rules.
     m.set(
         "CreateFontString",
         lua.create_function(
@@ -322,53 +210,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `SetScript(name, func)` — store the closure against one of [`SCRIPT_KINDS`], or **raise**.
-///
-/// ## Why raising is the right answer for a script we cannot fire
-///
-/// The error is loud and it blocks the addon at load, which looks like the worse outcome and is
-/// not: a script name this host *accepts* and never *fires* is a handler that silently never runs,
-/// with nothing anywhere saying so. That is the failure mode decisions 1203, 1205 and 1211 each
-/// recorded from a different direction, and it is strictly harder to find than a load error naming
-/// the exact call. So the rule for this list is one line long: **a name is accepted only once
-/// something fires it.**
-///
-/// The 1.12 script set is fully carved (wow-re `system/ui/scratch/rf28-typed-widget-loadxml.md`
-/// l.10-18 for the base map `0x76a0d0`, the per-type sections for each widget's additions;
-/// `system/ui/ui.md` l.544-556 summarises it), so what is missing here is never a mystery — it is a
-/// deliberate not-yet. What the corpus actually asks for, and why each answer is what it is:
-///
-/// * **`OnKeyDown` / `OnKeyUp` / `OnChar`** (14 + 1 + 4 corpus sites over 13 addons) — **accepted**
-///   since decision 1319 built the delivery walk ([`crate::script::keyboard`], whose module doc is
-///   the mechanism: the kind buckets, the strata 8→0 order, the key-name table, and the
-///   existence-not-handling consumption gate). They were this list's standing exception; the rule
-///   above let them in the moment something fired them.
-/// * **`OnCursorChanged`** (4 sites over 3 addons, plus two in the SHIPPED FrameXML — all of them
-///   the `ScrollingEdit_OnCursorChanged` auto-scroll idiom) — **accepted since decision 2141**,
-///   which built the edge this entry said was missing. The EditBox's own slot (RF-28 `+0x428`),
-///   fired by the caret flush `0x77da80` with four float caret-position args in UI units;
-///   `editbox::drain_cursor_changed` is our counterpart, on the tick, gated on the caret having
-///   actually moved. The stock `MailFrame.xml` and `HelpFrame.xml` declare it, so until 2141 the
-///   mail body and the GM ticket box did not scroll as you typed past their bottom — a bug nobody
-///   could see, because the load-time refusal only reached a terminal (decision 2135).
-/// * **`OnAttributeChanged`** (1 site, `Roid-Macros`) — **raising, permanently.** It is 2.0's secure
-///   frame/attribute system; there is no such slot in any 1.12 resolver. That addon is asking for a
-///   later client and should hear so.
-/// * **`OnHyperlinkEnter` · `OnHyperlinkLeave` · `OnMessageScrollChanged` ·
-///   `OnMovieFinished`/`ShowSubtitle`/`HideSubtitle` · `OnInputLanguageChanged`** — **raising.**
-///   Real 1.12 slots that we do not fire, and measured at **zero** call sites across the
-///   218-addon corpus, so there is nothing to weigh against the trap: they land when their
-///   mechanism does.
-/// * **`OnHorizontalScroll`** — **accepted, because `SetHorizontalScroll` fires it.** It was on
-///   the line above while "horizontal scroll isn't modeled at all", which stopped being true when
-///   the ScrollFrame's horizontal offset pair landed beside the vertical one
-///   ([`crate::script::scrollframe`]); `aux-addon` reads and writes both axes.
-/// * **`OnUpdateModel` · `OnAnimFinished`** — **accepted since decision 2007**, because the tick
-///   fires them: the model pane's scene clock runs in this engine now (`tick.rs`), `OnUpdateModel`
-///   at the top of every paint of a visible pane with a file (`0x76d1a0`) and `OnAnimFinished`
-///   from a sequence's natural completion (`0x76cdc0`, mode 0 — once per arm, a loop's first
-///   pass included). The shipped
-///   `Cooldown.xml` and `MainMenuBarBagButtons.xml` declare both.
+/// `SetScript(name, func)`: stores the closure under one of [`SCRIPT_KINDS`], else raises.
+/// Deviation: real 1.12 kinds nothing fires yet raise too (`OnHyperlinkEnter`, `OnHyperlinkLeave`,
+/// `OnMessageScrollChanged`, `OnInputLanguageChanged`, the movie frame's), because an accepted
+/// handler that never runs fails silently. `OnAttributeChanged` is 2.0's, with no 1.12 slot.
 fn set_script(lua: &Lua, this: &Table, name: &str, func: Option<Function>) -> mlua::Result<()> {
     let kind = SCRIPT_KINDS
         .iter()
@@ -378,7 +223,7 @@ fn set_script(lua: &Lua, this: &Table, name: &str, func: Option<Function>) -> ml
     let h = frame_handle_of(lua, this)?;
     let id = lua.app_data_mut::<Model>().expect("model").frame_id(h);
 
-    // Store the closure Lua-side (REG_SCRIPTS[id][kind]); update the Rust presence mirror.
+    // The closure lives Lua-side in `REG_SCRIPTS[id][kind]`; Rust keeps a presence mirror.
     let scripts: Table = lua.named_registry_value(REG_SCRIPTS)?;
     let per: Table = match scripts.get::<Value>(id)? {
         Value::Table(t) => t,
@@ -392,8 +237,7 @@ fn set_script(lua: &Lua, this: &Table, name: &str, func: Option<Function>) -> ml
         Some(f) => {
             per.set(kind, f)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // `insert` answering true = this frame did not have the kind before — the tick's
-            // OnUpdate list rides that edge (decision 1446; `scripts` has no other writer).
+            // The first handler of a kind joins that kind's list; nothing else writes `scripts`.
             if model.scripts.entry(h).or_default().insert(kind) {
                 match kind {
                     "OnUpdate" => model.on_update_frames.push(h),
@@ -440,24 +284,12 @@ fn get_script(lua: &Lua, this: &Table, name: &str) -> mlua::Result<Value> {
     }
 }
 
-/// `CreateTexture`/`CreateFontString`'s third argument — `inheritsFrom` — in the carved order.
-///
-/// **Font-object registry first, template registry second** (`0x773d39` then `0x773d47`). That
-/// order is not cosmetic: `inherits=` is one attribute over two namespaces, and every corpus caller
-/// of this argument names a font object, so a template-first resolver would miss all 49 of them.
-///
-/// A name in NEITHER registry raises, which is the same contract 1253 established for `CreateFrame`
-/// and the same bytes (`luaL_error`, `0x87957c` / `0x879544`, which never returns).
-///
-/// A name that IS a registered template but not a font object is a deliberate gap rather than a
-/// silent one: the lookup succeeded, so the reference would not raise, and re-interpreting a
-/// template node onto an existing region is a different mechanism from applying a font object. It
-/// warns and leaves the region usable — the distinction 1253 drew between *the lookup missing* and
-/// *the result being unusable*. Zero corpus callers reach it.
+/// Apply the `inherits` argument: the font-object registry first (`0x773d39`), then the template
+/// registry (`0x773d47`); a name in neither raises (`0x87957c` / `0x879544`). A template that is
+/// not a font object only warns: the reference applies the template, which is not built here.
 fn apply_region_inherits(lua: &Lua, wrapper: &Table, from: &str) -> mlua::Result<()> {
     use mlua::ObjectLike;
-    // The font object is applied through the binding the XML path uses, so there is one
-    // implementation of "apply a font object" rather than two that can drift apart.
+    // Through `SetFontObject`, the binding the XML `inherits=` path uses.
     if wrapper.call_method::<()>("SetFontObject", from).is_ok() {
         return Ok(());
     }
@@ -478,16 +310,9 @@ fn apply_region_inherits(lua: &Lua, wrapper: &Table, from: &str) -> mlua::Result
     )))
 }
 
-/// **The `lua_type(L, idx) == LUA_TSTRING` gate, asked before anything reads the slot** — the
-/// region constructors' `inherits` argument and nowhere else (`0x773d28` for `CreateFontString`,
-/// `0x773b06` for `CreateTexture`).
-///
-/// Strictly narrower than [`optional_string`]: a **number is refused here**, because the tag is
-/// tested raw with no coercion. That one-argument difference is the whole reason
-/// `f:CreateTexture(nil, nil, 5)` silently ignores the 5 while `CreateFrame("Frame", nil, nil, 5)`
-/// **raises** `Couldn't find inherited node "5"` — `CreateFrame` runs `lua_tostring(L, 4)` BEFORE
-/// its own `cmp 4`, and that retags the number's stack slot in place, so it arrives as a string.
-/// Same value, opposite outcome, from argument order alone.
+/// The region constructors' strict `lua_type == LUA_TSTRING` gate on `inherits` (`0x773d28`
+/// `CreateFontString`, `0x773b06` `CreateTexture`): unlike [`optional_string`], a number is
+/// ignored, where `CreateFrame` stringifies it first and looks it up as a name.
 fn strict_string_arg(v: &Value) -> Option<String> {
     match v {
         Value::String(s) => s.to_str().ok().map(|s| s.to_owned()),
@@ -520,23 +345,15 @@ fn create_region(
 
     let wrapper = region_wrapper(lua, id)?;
     if let Some(name) = name {
-        // **A leading `$parent` in the NAME is expanded, here as in XML** — `CreateTexture
-        // 0x773a20` and `CreateFontString 0x773c30` build a synthetic node carrying
-        // `name=<the Lua string>` and read it back through the same `GetAttribute(node, "name")` →
-        // `CScriptRegion::SetName 0x76c650` the XML path uses, and `0x76c691` is one of that
-        // expander's two call sites (wow-re `name-string-widget-resolution.md` §5/§6, whose
-        // `name=` reader census names `0x773ba1` and `0x773dc4` — the addresses *inside* these two
-        // bindings). A region's `$parent` is its OWNER frame, so the walk starts there.
-        //
-        // `pfQuest/browser.lua:723` is `pfBrowser.input:CreateTexture("$parentSearchIcon",
-        // "OVERLAY")`, and every named widget FonzAppraiser builds is this idiom.
+        // A leading `$parent` expands as in XML, its walk to a named frame starting at the owner:
+        // both bindings name the region through `CScriptRegion::SetName 0x76c650` (`0x773ba1`,
+        // `0x773dc4`).
         let name = {
             let model = lua.app_data_ref::<Model>().expect("model");
             crate::framexml::resolve_name(&name, &super::parent_token_base(&model, Some(owner)))
         };
         publish_global(lua, &name, &wrapper)?;
-        // Publish into the region-name registry too (first-wins, the frame rule) — this is what
-        // lets a sibling region's SetPoint name us as its `relativeTo` (see `resolve_target`).
+        // First name wins, as for frames; a sibling's `SetPoint` can then name this region.
         let mut model = lua.app_data_mut::<Model>().expect("model");
         model.region_names.entry(name).or_insert(id);
     }
@@ -547,12 +364,7 @@ fn create_region(
 mod tests {
     use crate::script::UiScript;
 
-    /// `UnregisterAllEvents` drops every registration the frame holds and leaves every other
-    /// frame's alone — the "disable me" path 10 corpus addons stop on (decision 1195).
-    ///
-    /// The second half is the one worth asserting: the cheap implementation (sweep every listener
-    /// list) and the correct one differ only when a *second* frame shares an event, which is the
-    /// normal case for `PLAYER_ENTERING_WORLD`.
+    /// Both frames share both events, so clearing one must leave the other's registrations.
     #[test]
     fn unregister_all_events_clears_one_frame_and_only_that_frame() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/object/frame_state.rs b/crates/benilla-ui/src/script/object/frame_state.rs
index 39930b2d..6238f280 100644
--- a/crates/benilla-ui/src/script/object/frame_state.rs
+++ b/crates/benilla-ui/src/script/object/frame_state.rs
@@ -1,23 +1,18 @@
-//! Frame method-table cluster: Show/Hide/visibility, identity/hierarchy (`GetName`/`GetParent`/
-//! `SetParent`), strata/level/scale/alpha, the Backdrop mechanism (`SetBackdrop`/`SetBackdropColor`/
-//! `SetBackdropBorderColor`), and mouse-enable. Split out of [`super`] purely for size — the shared
-//! id/handle plumbing, `CreateFrame`, and the method-table wiring stay there; this module's
-//! [`install`] just populates its share of the one shared method table.
+//! Frame methods: visibility, hierarchy, strata, level, scale, alpha, backdrop and input flags.
 
 use mlua::{Lua, Table, Value};
 
+use crate::script::region_map::{set_shared, Side};
+
 use crate::order::Strata;
 use crate::script::{event, Backdrop, Insets, Model};
 use crate::widget::FrameKind;
 
 use super::{decode_id, draw_layer_from_str, frame_handle_of, frame_wrapper, strata_from_str};
 
-/// Populate `m`'s visibility/hierarchy/strata/backdrop/mouse methods (see the module doc).
+/// Populate `m`'s visibility, hierarchy, strata, backdrop and input methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // Show / Hide / visibility. **`SetShown` is not here and must not come back**: the branchless
-    // setter belongs to a later expansion — no 1.12 method table registers it, and neither the
-    // stock chain nor either addon corpus calls it (decision 2142's census). A frame is shown or
-    // hidden by the two verbs the era has.
+    // Show / Hide / visibility. No `SetShown`: no 1.12 method table registers it.
     m.set(
         "Show",
         lua.create_function(|lua, this: Table| set_shown(lua, &this, true))?,
@@ -51,22 +46,18 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
     // Identity / hierarchy
-    m.set(
-        "GetName",
-        lua.create_function(|lua, this: Table| {
-            let h = frame_handle_of(lua, &this)?;
-            let name = {
-                let model = lua.app_data_ref::<Model>().expect("model");
-                model.arena.frame(h).and_then(|f| f.name.clone())
-            };
-            match name {
-                Some(n) => Ok(Value::String(lua.create_string(&n)?)),
-                None => Ok(Value::Nil),
-            }
-        })?,
-    )?;
-    // GetID/SetID — the app-meaning-free numeric label (XML `id=`, the client's `+0xb4`): a
-    // dropdown row's list position, a tab index. Default 0 (see `Frame::wow_id`).
+    set_shared(lua, m, Side::Frame, "GetName", |lua, this: Table| {
+        let h = frame_handle_of(lua, &this)?;
+        let name = {
+            let model = lua.app_data_ref::<Model>().expect("model");
+            model.arena.frame(h).and_then(|f| f.name.clone())
+        };
+        match name {
+            Some(n) => Ok(Value::String(lua.create_string(&n)?)),
+            None => Ok(Value::Nil),
+        }
+    })?;
+    // GetID/SetID (`0x775280`/`0x775340`): a plain numeric label at `+0xb0` (XML `id=`), default 0.
     m.set(
         "GetID",
         lua.create_function(|lua, this: Table| {
@@ -86,47 +77,24 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // ── GetObjectType / IsObjectType, frame side (wow-re `widget-type-identity.md` §6) ──────────
+    // ── GetObjectType / IsObjectType, frame side (`0x7a11d0`/`0x7a1290`) ──
     //
-    // The region side landed first because a FontString found it; `_Nameplates` is why this half
-    // exists too — `_Nameplates.lua:164` tests `Nameplate:GetObjectType() ~= "Button"` and `:191`
-    // tests `== "StatusBar"`, on FRAMES, in the same file whose `Region:GetObjectType()` calls the
-    // region verbs answer.
-    //
-    // The chains are a hardcoded straight-line list per class in the binary, not a runtime parent
-    // walk, so they are a table here too. Three of them are things a reasonable person invents
-    // wrongly:
-    //
-    //  · **`ScrollingMessageFrame` derives from `Frame`, NOT from `MessageFrame`.** The name says
-    //    otherwise and the roster is explicit (`0x787940`).
-    //  · **`SimpleHTML` is spelled with a capitalised HTML.** Our enum variant is `SimpleHtml`, so
-    //    anything derived from the variant name — `format!("{:?}")` and friends — would hand
-    //    addons `"SimpleHtml"`, and `GetObjectType` is compared with `==` (`IsObjectType`'s
-    //    case-folding would hide it; the getter's would not).
-    //  · **There is no `Cooldown` type.** 1.12.1's census finds 23 type-name globals and none is
-    //    that: the reference builds its cooldown as a `Model` playing `UI-Cooldown-Indicator.mdx`
-    //    (`CooldownFrameTemplate`), and since decision 2019 so does this engine — the Era-shaped
-    //    `FrameKind::Cooldown` that modelled the mechanism first-class (0137 phase 4) is gone, so
-    //    `CreateFrame("Cooldown")` is the reference's own unknown-type refusal, never an announced
-    //    Era type to a Lua ecosystem that branches on presence (the superset 1189 took back out).
+    // Each class's chain is a fixed list in the reference, so a table here. `ScrollingMessageFrame`
+    // derives from `Frame`, not `MessageFrame` (`0x787940`); `SimpleHTML` keeps its capitals,
+    // unlike the `SimpleHtml` variant; there is no `Cooldown` type (the reference's is a `Model`).
     fn type_chain(kind: FrameKind) -> &'static [&'static str] {
         match kind {
             FrameKind::Frame => &["Frame", "Region"],
             FrameKind::WorldFrame => &["Frame", "Region"],
             FrameKind::Button => &["Button", "Frame", "Region"],
             FrameKind::CheckButton => &["CheckButton", "Button", "Frame", "Region"],
-            // `CLootButton::IsObjectType 0x495af0` prepends its own name to the base's three
-            // (`"Button"` `[0x879954]`, `"Frame"` `[0x878560]`, `"Region"` `[0x878870]`) — read
-            // off the function, not assumed from the class hierarchy.
+            // `CLootButton::IsObjectType` (`0x495af0`) prepends its name to `Button`'s chain.
             FrameKind::LootButton => &["LootButton", "Button", "Frame", "Region"],
             FrameKind::EditBox => &["EditBox", "Frame", "Region"],
             FrameKind::StatusBar => &["StatusBar", "Frame", "Region"],
             FrameKind::Slider => &["Slider", "Frame", "Region"],
             FrameKind::ScrollFrame => &["ScrollFrame", "Frame", "Region"],
             FrameKind::Model => &["Model", "Frame", "Region"],
-            // 4 deep: `PlayerModel` derives from `Model`, and `DressUpModel` (1969) and
-            // `TabardModel` (1977) derive from it in turn, for the roster's maximum depth of 5
-            // (wow-re `ui/scratch/widget-type-identity.md` §6).
             FrameKind::PlayerModel => &["PlayerModel", "Model", "Frame", "Region"],
             FrameKind::DressUpModel => &["DressUpModel", "PlayerModel", "Model", "Frame", "Region"],
             FrameKind::TabardModel => &["TabardModel", "PlayerModel", "Model", "Frame", "Region"],
@@ -148,19 +116,18 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             .map_or(&["Frame", "Region"][..], |f| type_chain(f.kind)))
     }
 
-    m.set(
-        "GetObjectType",
-        lua.create_function(|lua, this: Table| {
-            Ok(Value::String(lua.create_string(chain_of(lua, &this)?[0])?))
-        })?,
-    )?;
+    set_shared(lua, m, Side::Frame, "GetObjectType", |lua, this: Table| {
+        Ok(Value::String(lua.create_string(chain_of(lua, &this)?[0])?))
+    })?;
 
-    // Same four traps as the region twin (see `script::region`): case-insensitive whole-string,
-    // number 1 on a hit and nil on a miss, exactly one value either way, and a non-string
-    // non-number argument raises the reference's own `Usage:` text.
-    m.set(
+    // A case-insensitive whole-string match answering 1 or nil; a non-string, non-number argument
+    // raises the reference's `Usage:`.
+    set_shared(
+        lua,
+        m,
+        Side::Frame,
         "IsObjectType",
-        lua.create_function(|lua, (this, want): (Table, Value)| {
+        |lua, (this, want): (Table, Value)| {
             let chain = chain_of(lua, &this)?;
             let want = match &want {
                 Value::String(s) => s.to_str()?.to_string(),
@@ -184,42 +151,14 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             } else {
                 Value::Nil
             })
-        })?,
+        },
     )?;
 
-    // ── GetFrameType / IsFrameType: the FRAME-side spellings of the pair above (decision 2106) ──
+    // ── GetFrameType / IsFrameType ──
     //
-    // 1.12 registers the type-identity pair **twice, under two names**. The Region script
-    // (`CScriptRegion`) publishes `GetObjectType`/`IsObjectType` — that is the pair above, and its
-    // `IsObjectType` binding is `0x7a1290`. The *frame* script (`CSimpleFrameScript.cpp`,
-    // `__FILE__` `0x879504`) publishes `GetFrameType 0x773640` and `IsFrameType 0x773700` as well,
-    // and wow-5875-re carved both (`system/ui/scratch/item17-frameapi-batch1.md`, 76-entry
-    // registrar table verified at the bytes). `GetObjectType`/`IsObjectType` are what LATER
-    // clients kept; `GetFrameType`/`IsFrameType` are 1.12's own, and we shipped only the first
-    // pair. That is 1189's superset argument inverted — not an extra name we invented, a real one
-    // we were missing — and it cost the world map:
-    //
-    //     Cartographer 2.02, LookNFeel.lua:368, inside OnEnable:
-    //         if v:GetFrameType() == "Model" and not v:GetName() then self.playerModel = v end
-    //
-    // With the verb nil that line raised, AceAddon swallowed it, `self.playerModel` stayed nil,
-    // and the next `Cartographer_ChangeZone` → `SetAlpha` put a red script error on screen from
-    // `LookNFeel.lua:737` every time the map opened. FuBar's own `FuBar.lua:576`
-    // (`type(frame:GetFrameType()) ~= "string"`) is the same call.
-    //
-    // Both delegate to the same `type_chain` the `Object` pair reads: `GetFrameType` is
-    // `call [edx+0x1c]` — the identical per-class type-name slot `GetObjectType` reads — then
-    // `lua_pushstring`, one value, extra arguments ignored. `IsFrameType` walks the chain through
-    // `[eax+0x18]`, the same case-insensitive whole-string compare, and answers the NUMBER 1 or
-    // nil.
-    //
-    // **One edge is INFERRED and named rather than guessed silently:** wow-re's note glosses
-    // `IsFrameType`'s *absent-argument* branch as "pushes the frame's own typename (`call [eax+4]`
-    // GetName)", which is self-contradictory — a typename and a name are different slots — so the
-    // branch is not settled. We take the sibling's behaviour (the `Usage:` raise) pending a byte
-    // read. No caller in the 219-addon corpus, the director's AddOns, or the shipped FrameXML ever
-    // omits the argument: `JIM_toolbox/Config2/Pulse_Config.lua:118` is the corpus's only
-    // `IsFrameType` site and it passes `"Slider"`.
+    // The frame script's own spellings of the pair above (`GetFrameType 0x773640`, `IsFrameType
+    // 0x773700`), reading the same per-class type slot: one name, or 1 or nil. An absent argument
+    // raises `Usage:` like `IsObjectType`; the reference's absent-argument branch is untraced.
     m.set(
         "GetFrameType",
         lua.create_function(|lua, this: Table| {
@@ -255,87 +194,26 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    m.set(
-        "GetParent",
-        lua.create_function(|lua, this: Table| {
-            let h = frame_handle_of(lua, &this)?;
-            let parent_id = {
-                let mut model = lua.app_data_mut::<Model>().expect("model");
-                model
-                    .arena
-                    .frame(h)
-                    .and_then(|f| f.parent)
-                    .map(|p| model.frame_id(p))
-            };
-            match parent_id {
-                Some(pid) => Ok(Value::Table(frame_wrapper(lua, pid)?)),
-                None => Ok(Value::Nil),
-            }
-        })?,
-    )?;
-    // ── The four structure queries: GetChildren / GetNumChildren / GetRegions / GetNumRegions ──
+    set_shared(lua, m, Side::Frame, "GetParent", |lua, this: Table| {
+        let h = frame_handle_of(lua, &this)?;
+        let parent_id = {
+            let mut model = lua.app_data_mut::<Model>().expect("model");
+            model
+                .arena
+                .frame(h)
+                .and_then(|f| f.parent)
+                .map(|p| model.frame_id(p))
+        };
+        match parent_id {
+            Some(pid) => Ok(Value::Table(frame_wrapper(lua, pid)?)),
+            None => Ok(Value::Nil),
+        }
+    })?;
+    // ── GetChildren / GetNumChildren / GetRegions / GetNumRegions ──
     //
-    // Registered bindings in 1.12 (`GetNumRegions 0x773e60`, `GetRegions 0x773f60`,
-    // `GetNumChildren 0x774080`, `GetChildren 0x774180` — wow-re `ui/ledger.tsv`, classified
-    // ORCHESTRATION: each marshals and delegates, with no fidelity math of its own).
-    //
-    // **Why these four are worth more than their size.** They are how an addon walks a frame it did
-    // not build, which is the whole basis of the "reskin the default UI" genre — and that genre is
-    // the top of the 1.12 popularity list. `pfUI.api.StripTextures` is the canonical shape:
-    //
-    //     for _, v in ipairs({ frame:GetRegions() }) do
-    //       if v.SetTexture then ... v:SetTexture(nil) end
-    //     end
-    //
-    // With `GetRegions` absent that is `attempt to call method 'GetRegions' (a nil value)`, raised
-    // out of a library file every one of pfUI, pfQuest, pfQuest-turtle and ShaguDPS embeds — four
-    // separate top-20 addons dying on one missing verb, plus Questie on `GetChildren`.
-    //
-    // **Two lists, one walk each, in the arena's own order.** `Frame::children` is insertion order,
-    // which our own arena documents as the client's `+0x300` child-list order; `Frame::regions` is
-    // creation order. Neither is re-sorted here — a structure query reports the structure, and the
-    // draw order is `crate::order`'s separate concern.
-    //
-    // **A detached region is not in the list.** `Region:SetParent(nil)` sets `Region::detached`
-    // rather than removing the entry, because the owner's `Vec` is what `WidgetArena::destroy`
-    // frees from — but the client's re-link virtual `0x77fd10` with a null parent genuinely
-    // **unlinks from the old parent's draw layer and region list** (wow-re
-    // `widget-api-batch-benilla.md` Q7, VERIFIED), so a detached region must be invisible to both
-    // region verbs. Our flag is a representation choice; the list these report is the client's.
-    //
-    // **The count and the list come from ONE function** ([`regions_of`] / [`children_of`]), never
-    // two walks with the same filter written twice. `GetNumRegions` disagreeing with
-    // `#{GetRegions()}` is a bug an addon would hit as an off-by-one deep inside a loop it did not
-    // write, and the only way to make it impossible is to have one of them BE the other.
-    //
-    // **Settled by a wow-re §5 quartet** (`ui/scratch/widget-list-bindings.md`), which confirmed two
-    // of these choices and corrected a third:
-    //
-    //  · **The order is link order, oldest first, and no reversal.** `CSimpleFrame` embeds a punned
-    //    `TSList` header whose ctor sets `tail = &header`, `head = (&header)|1`, and BOTH linkers
-    //    append at the TAIL (`0x76a750` for regions, `0x76aa20` for children — one caller each).
-    //    Our insertion-order `Vec` is the same order. (wow-re's own `draw-order-law.md` said
-    //    "tail→head"; that was a direction mislabel and was corrected in the same round.)
-    //  · **Hidden children and regions are returned and counted** — a VERIFIED negative: the
-    //    counting loops never load the visibility word at all.
-    //  · **The TITLE REGION IS NOT RETURNED**, and that one corrected us. Both creation paths
-    //    (`0x773910`, `0x769b79`) dispatch a vtable slot that is a bare `[this+0x9c] = parent` and
-    //    never reach the linker `0x77fd10`, so a title region is not in the list this walks —
-    //    corroborated by `Hide`/`Show` carrying an explicit extra `[frame+0xa8]` case *because* the
-    //    list walk misses it. Ours is in `Frame::regions` (so the arena can free it), so
-    //    [`regions_of`] filters it out.
-    //  · **A Button's label (`+0x338`) and its four state textures ARE in the list** — they link
-    //    through `0x77fd10` like any region, which is what ours do too.
-    //  · **The return shape**: N separate values, never a table; a frame with none returns ZERO
-    //    values (no `lua_newtable` in either body), and `GetNum*` returns one number — `0` when
-    //    empty, never nil.
-    //
-    // The one thing still out of reach is not these bindings': Questie reads
-    // `({Minimap:GetChildren()})[9]` for the player arrow, and the §5 found why that index works —
-    // `CMinimap`'s ctor `0x4edbc0` builds NINE engine-owned `Model` children before the XML
-    // `<Frames>` descent, the ninth (`[Minimap+0x338]`) being the arrow `SetPlayerFacing 0x4eb8e0`
-    // writes. We create none of them, so index 9 is nil here until the minimap grows its engine
-    // children.
+    // `0x774180` / `0x774080` / `0x773f60` / `0x773e60`: link order, oldest first (both linkers,
+    // `0x76a750` and `0x76aa20`, append at the tail), hidden ones included; the list as separate
+    // values, none when empty, the count as one number. Each count shares its list's walk.
     m.set(
         "GetChildren",
         lua.create_function(|lua, this: Table| {
@@ -368,19 +246,16 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "GetNumRegions",
         lua.create_function(|lua, this: Table| Ok(regions_of(lua, &this)?.len()))?,
     )?;
-    // SetParent — the runtime reparent, per the byte-verified law (wow-re
-    // `ui/scratch/setparent-runtime-strata-level.md`; decision 1323). The binding half
-    // (`0x7a1550`): the parent argument is a frame table, a NAME string (`0x76c760`), or an
-    // explicit nil — an ABSENT argument is NOT the nil path (`0x6f3400` returns −1) and raises
-    // like an unresolvable name; the cycle guard is the binding's own inline ancestor walk and
-    // RAISES (`0x87cb14`), it does not silently no-op. The arena half is
-    // `reparent_begin`/`reparent_finish`, split so `OnHide` fires between them the way the
-    // reference's hide→show round-trip does — `fire_visibility_changes` reads each frame's live
-    // state for direction, so hide and show must be fired from their own phase, never one
-    // combined list.
-    m.set(
+    // `SetParent` (`0x7a1550`): a frame, a name (`0x76c760`) or an explicit nil; an absent argument
+    // raises like an unknown name (`0x6f3400` gives -1), and so does a cycle (`0x87cb14`). As in
+    // the reference, hide fires before show, between `reparent_begin` and `reparent_finish`,
+    // since `fire_visibility_changes` reads each frame's live state for the direction.
+    set_shared(
+        lua,
+        m,
+        Side::Frame,
         "SetParent",
-        lua.create_function(|lua, args: mlua::MultiValue| {
+        |lua, args: mlua::MultiValue| {
             let mut it = args.into_iter();
             let this = match it.next() {
                 Some(Value::Table(t)) => t,
@@ -396,9 +271,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     .unwrap_or_else(|| "<unnamed>".to_string())
             };
             let parent_arg = it.next();
-            // `_G[name]` is read with no guard alive (`object::NamedTarget`), and **without**
-            // `$parent` expansion: `0x7a1550` calls `0x76c760` directly, and only the layout
-            // vtable's `0x76c700` runs the token.
+            // `_G[name]` is read with no guard alive and no `$parent` expansion: `0x7a1550` calls
+            // `0x76c760` directly, and only the layout path's `0x76c700` expands the token.
             let named = match &parent_arg {
                 Some(Value::String(s)) => Some(match s.to_str() {
                     Ok(n) => super::prefetch_named_target(lua, n.as_ref(), None),
@@ -409,7 +283,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let new_parent = {
                 let model = lua.app_data_ref::<Model>().expect("model");
                 match &parent_arg {
-                    // Explicit nil reparents to the screen root (the strata/level RESET path).
+                    // An explicit nil reparents to the screen root, resetting strata and level.
                     Some(Value::Nil) => None,
                     Some(Value::Table(t)) => Some(
                         decode_id(t)
@@ -422,10 +296,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             })?,
                     ),
                     Some(Value::String(_)) => {
-                        // `_G[name]` + the **Frame** tag check — the reference's `0x76c760`
-                        // (`0x7a1550`'s NAME-string path) type-guards against `[0xcf0c10]`, the
-                        // narrow Frame id, not `SetPoint`'s root `[0xcf0c3c]`. So a global naming
-                        // a REGION fails here exactly as an absent one does.
+                        // `0x76c760` accepts only a frame (`[0xcf0c10]`), not any region
+                        // (`[0xcf0c3c]`), so a region's name fails like an absent one.
                         let nt = named.as_ref().expect("a String argument is prefetched");
                         let hit = super::resolve_named_target(&model, nt)
                             .and_then(|id| model.id_to_frame.get(&id).copied());
@@ -436,8 +308,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             ))
                         })?)
                     }
-                    // Absent argument, or any other type: the reference never reaches the
-                    // reparent slot (`0x87cb48` raise).
+                    // Absent, or any other type: the reference raises first (`0x87cb48`).
                     _ => {
                         return Err(mlua::Error::runtime(format!(
                             "{who}:SetParent(): Couldn't find region named ''"
@@ -445,8 +316,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     }
                 }
             };
-            // The cycle guard raises — `"%s:SetParent(): Would create a loop parenting to %s"`
-            // (`0x7a177f`'s inline `+0x9c` walk, `newParent == self` included).
+            // The cycle guard raises (`0x7a177f`'s ancestor walk, the frame itself included).
             if let Some(np) = new_parent {
                 let model = lua.app_data_ref::<Model>().expect("model");
                 if np == h || model.arena.is_ancestor(h, np) {
@@ -464,24 +334,22 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 model.arena.reparent_begin(h, new_parent)
             };
-            // None = the verified total no-op (same parent, `0x76ab20`): nothing runs, not even
-            // the layout touch.
+            // None: the same parent, a total no-op (`0x76ab20`), not even a layout touch.
             let Some(hidden) = hidden else { return Ok(()) };
             let was_visible = !hidden.is_empty();
             event::fire_visibility_changes(lua, hidden);
             let shown = {
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 let shown = model.arena.reparent_finish(h, new_parent, was_visible);
-                // A real reparent moves the subtree's effective scale and anchors — a
-                // layout-gate input, and the scale is a measure-key input the subtree's
-                // FontStrings cannot name one by one (human-rate; the sweep walks once).
-                model.touch_layout();
+                // A reparent moves the subtree's effective scale, a layout input and part of every
+                // descendant FontString's measure key.
+                model.touch_layout_reparent(h);
                 model.touch_measure_all();
                 shown
             };
             event::fire_visibility_changes(lua, shown);
             Ok(())
-        })?,
+        },
     )?;
     // Strata / level / scale / alpha
     m.set(
@@ -511,12 +379,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, (this, level): (Table, i64)| {
             let h = frame_handle_of(lua, &this)?;
             let lvl = level.clamp(0, i64::from(u16::MAX)) as u16;
-            // **A script level change carries no children** — the binding `0x774560` calls
-            // `set_frame_level 0x76a4f0` with `propagate=0` (wow-re `ui/ui.md`, default levels).
-            // Only the toplevel raise shifts a subtree. Stock `BonusActionButtonTemplate` is written
-            // for this: it raises the button +2 and then its cooldown +2 by hand, landing the sweep
-            // one level over the button — carrying the children made it three, over the
-            // cooldown-count text an addon hangs at button + 2 (decision 2189).
+            // A script level change moves no children: `0x774560` calls `set_frame_level 0x76a4f0`
+            // with `propagate = 0`, which stock `BonusActionButtonTemplate` relies on.
             lua.app_data_mut::<Model>()
                 .expect("model")
                 .arena
@@ -539,8 +403,6 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, (this, scale): (Table, f32)| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Effective-scale changes ride the propagation's own eps gate; the own-scale compare
-            // is the cheap superset (same own scale => no effective change is possible).
             let changed = model.arena.frame(h).is_some_and(|f| f.scale != scale);
             model.arena.set_scale(h, scale);
             if changed {
@@ -563,8 +425,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "SetAlpha",
         lua.create_function(|lua, (this, alpha): (Table, f32)| {
             let h = frame_handle_of(lua, &this)?;
-            // The 1.12 API clamps to 0..1 — ref Lua leans on it (fade code that passes a 0..255
-            // alpha stays fully opaque until the value falls below 1/255).
+            // The reference clamps to 0..1; stock fade code passing a 0..255 alpha relies on it.
             lua.app_data_mut::<Model>()
                 .expect("model")
                 .arena
@@ -580,10 +441,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(model.arena.frame(h).map(|f| f.alpha).unwrap_or(1.0))
         })?,
     )?;
-    // Backdrop (backdrop-mechanism.md): SetBackdrop(table|nil) installs (or, with nil, tears down)
-    // the frame's tiled bg + 8-piece border plate. The two color setters tint the bg / all 8 border
-    // pieces (never the reverse — spec §4). The Lua-table SetBackdrop defaults both colors to WHITE
-    // (the ctor), so a caller must SetBackdropColor after to tint (the tooltip's OnLoad does).
+    // `SetBackdrop(table|nil)` (`0x7776e0` → `0x76a5d0`) installs or removes the tiled background
+    // and 8-piece border, both white until tinted; the two colour setters tint the background and
+    // the border respectively (`0x77f410`/`0x77f440`).
     m.set(
         "SetBackdrop",
         lua.create_function(|lua, (this, arg): (Table, Value)| {
@@ -610,50 +470,22 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `GetBackdrop()` (`0x777370`; wow-re `ui/scratch/widget-api-batch-benilla.md` Q5) — five things
-    // a plausible implementation gets wrong, so each is spelled out with its reason:
-    //
-    // 1. It is a **reconstruction from the struct**, never the caller's table. The reference stores
-    //    no Lua reference anywhere: `SetBackdrop` reads six keys into a fresh 0x68-byte struct at
-    //    `frame+0x1ac` and drops the table, so `0x777426`–`0x7776b9` re-push every key from those
-    //    fields. Handing back a stored clone would leak keys the reader never accepted and would
-    //    keep stale values a later `SetBackdropColor` changed.
-    // 2. **No backdrop ⇒ ZERO Lua values, not `nil`** — the early bail is `xor eax,eax; ret`, which
-    //    for a *return* path really is "no values" (contrast `binding_abi`'s note: the same two
-    //    bytes after a `luaL_error` are unreachable boilerplate). Observable through the count,
-    //    and it is the shape our `GetTitleRegion` will *not* have when it lands — that one pushes
-    //    nil, i.e. one value. The client cannot distinguish "never set" from `SetBackdrop(nil)`.
-    // 3. **A partial `SetBackdrop` omits nothing on the way out.** Every `SetBackdrop` allocates a
-    //    fresh struct (`0x777801`, ctor `0x77e5f0`), so a key the caller left out is a *ctor
-    //    default* here, not an absent key and not the previous backdrop's value: `bgFile`/`edgeFile`
-    //    `""`, `tileSize` 0, `edgeSize` **32**. Our `backdrop_from_table` already builds on
-    //    `Backdrop::default()`, so this falls out — but only because `None` maps to `""` below
-    //    rather than to nil.
-    // 4. **`tile` is the NUMBER `1`, or the key is ABSENT — never `true`/`false`.** The push is
-    //    `0x3ff00000` (the double 1.0) on true and `lua_pushnil` on false, and `lua_settable` with a
-    //    nil value creates no key (and *erases* one from a recycled table, which is why the nil is
-    //    written rather than skipped). An addon reading `if backdrop.tile then` sees the same truth
-    //    either way; one that round-trips the table into `SetBackdrop` is why the number matters,
-    //    since `tile` there goes through a coercer that takes numbers.
-    // 5. The undocumented **in-place form** (`0x77740e`): `lua_type(L,2) == LUA_TTABLE` skips
-    //    `lua_newtable` and fills arg 2, reusing an existing `insets` subtable rather than replacing
-    //    it. Implemented — it is four lines, and an addon caching one table across frames would
-    //    otherwise silently get a new one each call. A non-table arg 2 is ignored, not an error.
-    //
-    // No `bgColor`/`edgeColor`/`alpha` key exists: the two colors live in the struct but the reader
-    // never pushes them (`GetBackdropColor`/`GetBackdropBorderColor` are their only accessors).
+    // `GetBackdrop([table])` (`0x777370`) rebuilds the table from the stored struct: no backdrop is
+    // zero values, not nil; an omitted key reads its ctor default (files `""`, `tileSize` 0,
+    // `edgeSize` 32; `0x77e5f0`); `tile` is 1 or absent, never a boolean; a table argument is
+    // filled in place, its `insets` reused (`0x77740e`). No colour keys.
     m.set(
         "GetBackdrop",
         lua.create_function(|lua, (this, target): (Table, Value)| {
             let h = frame_handle_of(lua, &this)?;
-            // Copied out before a single Lua write: filling a *caller-supplied* table can run a
-            // `__newindex` metamethod, which can re-enter us and would panic on the app-data borrow.
+            // Copied out before any Lua write: filling a caller's table can run a `__newindex` that
+            // re-enters and would panic on the app-data borrow.
             let bd = {
                 let model = lua.app_data_ref::<Model>().expect("model");
                 model.backdrops.get(&h).cloned()
             };
             let Some(bd) = bd else {
-                return Ok(mlua::MultiValue::new()); // trap 2 — zero values, not nil
+                return Ok(mlua::MultiValue::new());
             };
             let t = match target {
                 Value::Table(t) => t,
@@ -664,15 +496,15 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             t.set(
                 "tile",
                 if bd.tile {
-                    Value::Number(1.0) // trap 4
+                    Value::Number(1.0)
                 } else {
-                    Value::Nil // trap 4 — erases the key from a recycled table
+                    Value::Nil // erases the key from a reused table
                 },
             )?;
             t.set("tileSize", f64::from(bd.tile_size))?;
             t.set("edgeSize", f64::from(bd.edge_size))?;
             let insets = match t.get::<Value>("insets") {
-                Ok(Value::Table(existing)) => existing, // trap 5 — reuse, don't replace
+                Ok(Value::Table(existing)) => existing,
                 _ => {
                     let fresh = lua.create_table()?;
                     t.set("insets", &fresh)?;
@@ -742,7 +574,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // Mouse interaction (EnableMouse gates hit-testing; keyboard focus is out of scope)
+    // Mouse interaction: `EnableMouse` gates hit-testing.
     m.set(
         "EnableMouse",
         lua.create_function(|lua, (this, enable): (Table, bool)| {
@@ -764,21 +596,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // EnableKeyboard(flag) / IsKeyboardEnabled() — `0x776f90` / `0x776ff0`, real Frame entries in
-    // wow-re's frame-API carve, beside the mouse pair above.
-    //
-    // 8 corpus addons call this and were RAISING on it (`ColorPickerPlus:258`,
-    // `Dewdrop-2.0.lua:2021-2022` — which is in ~65 addons — `AckisRecipeList/ARLFrame.lua:1650`).
-    // The flag round-trips; **key delivery is not gated on it**, exactly as the wheel's flag
-    // shipped in 1198, because the machinery it would gate does not exist here yet.
-    //
-    // Why that is the right half rather than a silent stub, which this codebase has been bitten by
-    // three times (1203/1205/1211): the majority of the corpus calls pass **false**, and for those
-    // our behaviour is already the reference's — we deliver no keys to arbitrary frames either. The
-    // `true` callers want delivery we do not do, but they did not get it before this landed; they
-    // got a raise that killed the enclosing function. And per
-    // `frame-key-script-delivery.md` §3.2 being enabled genuinely is separable from having a
-    // handler, so the flag is a real piece of the model, not a placeholder for one.
+    // EnableKeyboard / IsKeyboardEnabled (`0x776ec0`/`0x776f90`): the flag key delivery gates on
+    // (`script::keyboard`), separate from having a handler (`0x76af00`).
     m.set(
         "EnableKeyboard",
         lua.create_function(|lua, (this, enable): (Table, bool)| {
@@ -800,29 +619,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // `EnableMouseWheel(flag)` / `IsMouseWheelEnabled()` — the wheel's own gate, a separate flag
-    // from `EnableMouse` in the reference and separate here (decision 1198).
-    //
-    // The flag is real and round-trips. **The dispatch is NOT gated on it yet, deliberately.**
-    // Our wheel dispatch keys off "does this frame carry an `OnMouseWheel` handler", walking up to
-    // the nearest ancestor that does — more permissive than the reference, which also requires the
-    // frame to be wheel-enabled so a scroll region can hand the wheel to the window behind it
-    // without tearing its handler out.
-    //
-    // Gating it today would break our own UI: 44 `OnMouseWheel` sites across 14 shipped files and
-    // **not one of them declares `enableMouseWheel`**, because the loader has never read that
-    // attribute. The condition to flip it is concrete rather than someday — teach the loader the
-    // attribute, declare it on those 44 sites, then gate. Until then this is a disclosed superset
-    // (1189's argument, pointed the other way), and the two corpus addons that stopped on the
-    // missing *method* are unblocked either way.
-    // EnableDrawLayer(layer) / DisableDrawLayer(layer) — Frame method table `0x878ec0`, entries
-    // `0x7755b0` / `0x775680`, between `IsToplevel` and `Show`. See [`crate::widget::Frame`]'s
-    // `disabled_layers` for what was read and why the mask lives on the frame.
-    //
-    // An unknown layer name is a NO-OP here rather than a raise. That is the honest state, not a
-    // decision: `draw_layer_from_str` is the same parser `SetDrawLayer` and `CreateTexture` use,
-    // and what the reference does with an unparseable name in THIS pair has not been read out of
-    // the binary. Both corpus callers (pfUI, MoveAnything) pass literals from the five-name set.
+    // EnableDrawLayer / DisableDrawLayer (`0x7755b0`/`0x775680`): the frame's layer mask. An
+    // unknown layer name is a no-op here; the reference's handling of one is untraced.
     for (name, disable) in [("EnableDrawLayer", false), ("DisableDrawLayer", true)] {
         m.set(
             name,
@@ -847,6 +645,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             })?,
         )?;
     }
+    // EnableMouseWheel / IsMouseWheelEnabled: the wheel's own flag, separate from `EnableMouse` as
+    // in the reference, and the one the wheel hit test gates on.
     m.set(
         "EnableMouseWheel",
         lua.create_function(|lua, (this, enable): (Table, bool)| {
@@ -868,9 +668,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // Clamp-to-screen (`0x776c00`/`0x776cb0`, geometry flags bit4 — layout.md): the layout resolve
-    // keeps the frame's assembled rect inside the window, size preserved. GameTooltip frames
-    // default true by construction (widget::Frame::clamped_to_screen — decision 0352).
+    // Clamp-to-screen (`0x776c00`/`0x776cb0`, geometry flags bit 4): the layout resolve keeps the
+    // frame's rect inside the window, size preserved.
     m.set(
         "SetClampedToScreen",
         lua.create_function(|lua, (this, clamp): (Table, bool)| {
@@ -894,10 +693,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // Hit-rect insets — the MOUSE rect only (widget::Frame::hit_rect_insets): the hit test shrinks
-    // the resolved rect by these four before testing the cursor, and nothing else reads them, so a
-    // frame's geometry/draw/anchor answers are unchanged. The ref sets them wherever a button's
-    // frame is larger than its art (the micro buttons' 18 px empty header).
+    // Hit-rect insets shrink only the mouse hit rect; geometry, drawing and anchors ignore them.
     m.set(
         "SetHitRectInsets",
         lua.create_function(
@@ -923,12 +719,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Parse a Lua `SetBackdrop` table into a [`Backdrop`] (backdrop-mechanism.md §1). The keys read —
-/// exactly the compiled reader's set — are `bgFile`/`edgeFile` (strings), `tile` (boolean, default
-/// false), `tileSize`/`edgeSize` (numbers; a missing number leaves the ctor default: tileSize 0,
-/// edgeSize 32), and `insets{left,right,top,bottom}` (numbers, each default 0). A non-string file or
-/// non-number size is treated as absent (the client's per-key type gate). Colors stay the ctor
-/// white — SetBackdrop never reads a color key; the color setters do that.
+/// Parse a `SetBackdrop` table (`0x7776e0`): exactly the reference's keys, a wrong-typed one read
+/// as absent and a missing one left at the ctor default (`edgeSize` 32); no colour keys.
 fn backdrop_from_table(t: &Table) -> mlua::Result<Backdrop> {
     let mut bd = Backdrop::default();
     if let Ok(Value::String(s)) = t.get::<Value>("bgFile") {
@@ -937,7 +729,6 @@ fn backdrop_from_table(t: &Table) -> mlua::Result<Backdrop> {
     if let Ok(Value::String(s)) = t.get::<Value>("edgeFile") {
         bd.edge_file = Some(s.to_str()?.to_string());
     }
-    // `tile` — Lua truthiness (nil/false ⇒ false; a missing key reads as Nil).
     bd.tile = !matches!(
         t.get::<Value>("tile").unwrap_or(Value::Nil),
         Value::Nil | Value::Boolean(false)
@@ -995,8 +786,7 @@ fn set_shown(lua: &Lua, this: &Table, shown: bool) -> mlua::Result<()> {
     Ok(())
 }
 
-/// This frame's child frames as stable ids, in the arena's insertion order — the one walk
-/// `GetChildren` and `GetNumChildren` share (see their comment on why they must share it).
+/// The frame's child ids in link order, the one walk `GetChildren` and `GetNumChildren` share.
 fn children_of(lua: &Lua, this: &Table) -> mlua::Result<Vec<u32>> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -1006,26 +796,10 @@ fn children_of(lua: &Lua, this: &Table) -> mlua::Result<Vec<u32>> {
     Ok(children.into_iter().map(|c| model.frame_id(c)).collect())
 }
 
-/// This frame's live regions as stable ids, in creation order — **the title region and detached
-/// ones excluded** — the one walk `GetRegions` and `GetNumRegions` share.
-///
-/// Both exclusions are the client's list, not tidiness, and both are VERIFIED (wow-re
-/// `ui/scratch/widget-list-bindings.md`, §5 quartet):
-///
-/// - **Detached.** `SetParent(nil)` reaches `0x77fd55` → the removal virtual `0x76a7f0`, which
-///   unlinks the node and frees it, and then skips every re-link. We keep the entry only so the
-///   arena can still free the slot; reporting it would hand an addon an object the reference never
-///   would, and `StripTextures`-shaped code would "strip" a region already off the screen.
-/// - **The title region.** Its two creation paths (`0x773910`, `0x769b79`) dispatch a vtable slot
-///   that is a bare `[this+0x9c] = parent` and never reach the linker at all, so it was never in
-///   this list — corroborated by `Hide`/`Show` needing an explicit extra `[frame+0xa8]` case
-///   *because* the walk misses it. Ours is in [`crate::widget::Frame::regions`] so that
-///   `WidgetArena::destroy` still frees it, which makes that a representation detail this walk
-///   must not leak.
-///
-/// A Button's label and its four state textures are deliberately NOT excluded: they link through
-/// `0x77fd10` like any other region in the reference, and ours go through `create_region` like any
-/// other region here.
+/// The frame's region ids in link order, the one walk `GetRegions` and `GetNumRegions` share. A
+/// detached region is left out (`SetParent(nil)` unlinks it, `0x76a7f0`), and so is the title
+/// region, which never reaches the linker `0x77fd10` (`0x773910`, `0x769b79`); a Button's label
+/// and state textures are in.
 fn regions_of(lua: &Lua, this: &Table) -> mlua::Result<Vec<u32>> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -1044,42 +818,23 @@ fn regions_of(lua: &Lua, this: &Table) -> mlua::Result<Vec<u32>> {
     Ok(live.into_iter().map(|r| model.region_id(r)).collect())
 }
 
-/// One backdrop colour channel, the reference's own conversion (`SetBackdropColor 0x777d30` /
-/// `SetBackdropBorderColor 0x7780d0` — instruction-identical bar the delegate; wow-re
-/// `scratch/numeric-arg-coercion-law.md` Q4, VERIFIED).
-///
-/// **r/g/b are UNGATED and alpha is not**, and that asymmetry is the whole of this function:
-///
-///  · r/g/b (`lua` indices 2/3/4) go through a bare `lua_tonumber`, so a `nil` channel is `0.0`
-///    and the call completes — no raise. ShaguTweaks `helpers.lua:248` passes `color.r` from a
-///    table that does not always have one, and benilla raised on it, killing the addon.
-///  · alpha (index 5) is `lua_isnumber`-gated at `0x778227` with `1.0f` staged at `0x778220`, so a
-///    **missing or nil** alpha is OPAQUE. Reading the asymmetry the other way — nil alpha as `0.0`
-///    like its neighbours — would turn every one of those borders transparent, which is a worse
-///    bug than the raise it replaced and would look like a rendering fault.
-///
-/// Then the reference clamps to `[0,1]` with **NaN landing on 1.0** (the compare's unordered arm
-/// takes the high clamp), and quantizes `×255 + 0.5` through `__ftol` — round-half-up, not the
-/// bare truncate `chat-window-record.md`'s colour path uses. The field is a packed `0xAARRGGBB`
-/// byte quad, so nothing finer survives the store and we quantize on the way in rather than
-/// pretend to a precision `GetBackdropColor` could not read back.
+/// One backdrop colour channel as `SetBackdropColor` (`0x777d30`) and `SetBackdropBorderColor`
+/// (`0x7780d0`) convert it: r, g, b through a bare `lua_tonumber` (nil is 0), alpha gated by
+/// `lua_isnumber` with 1.0 staged (`0x778220`, `0x778227`); clamped to 0..1 with NaN at 1, then
+/// stored as a byte, rounded half up (`×255 + 0.5`, `__ftol`).
 fn backdrop_channel(lua: &Lua, v: Option<Value>, gated: bool) -> f32 {
     let x = if gated {
-        // `lua_isnumber` — a number or a numeric string; anything else takes the staged default.
         v.and_then(|v| lua.coerce_number(v).ok().flatten())
             .unwrap_or(1.0)
     } else {
         crate::script::binding_abi::coerced_number(lua, v)
     };
     let clamped = if x.is_nan() { 1.0 } else { x.clamp(0.0, 1.0) };
-    // `×255 + 0.5` then `__ftol` (truncate toward zero) = round-half-up over `[0,1]`.
     let byte = (clamped * 255.0 + 0.5) as u8;
     f32::from(byte) / 255.0
 }
 
-/// The four channels of a backdrop colour setter, in the reference's own gating (see
-/// [`backdrop_channel`]). Takes the raw stack so a missing argument and an explicit `nil` reach
-/// the same place they do there.
+/// A backdrop colour setter's four channels; a missing argument and an explicit nil read alike.
 fn backdrop_color(lua: &Lua, args: mlua::MultiValue) -> [f32; 4] {
     let a: Vec<Value> = args.into_iter().collect();
     [
diff --git a/crates/benilla-ui/src/script/object/layout_methods.rs b/crates/benilla-ui/src/script/object/layout_methods.rs
index 962c90d6..b646c2fe 100644
--- a/crates/benilla-ui/src/script/object/layout_methods.rs
+++ b/crates/benilla-ui/src/script/object/layout_methods.rs
@@ -1,20 +1,17 @@
-//! Frame method-table cluster: anchoring and size — `SetPoint`/`ClearAllPoints`/`GetPoint`/
-//! `SetAllPoints`/`SetWidth`/`SetHeight`/`GetWidth`/`GetHeight` and the resolved-edge readers
-//! (`GetLeft`/`GetRight`/`GetTop`/`GetBottom`). Split out of [`super`] purely for size — see
-//! its module doc for the shared id/handle plumbing and method-table wiring.
+//! Frame methods: anchors, size, and the resolved geometry readers.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
 use crate::layout::{Anchor, Point};
+use crate::script::region_map::{set_shared, Side};
 use crate::script::{Model, SCREEN};
 use crate::widget::FrameHandle;
 
 use super::anchor_args::{parse_set_all_points, parse_set_point, resolve_rel_target, UNNAMED};
 use super::{frame_handle_of, frame_parent_token_base, frame_wrapper, point_name};
 
-/// The two things the shared ladder needs off the receiver, read under **one short** `Model`
-/// borrow that is dropped before the `_G` read: the name the reference puts in its error strings
-/// (`GetName`, else the literal `"<unnamed>"`), and the name a leading `$parent` expands to.
+/// The receiver's name for the error strings and its `$parent` base, read under one short `Model`
+/// borrow that ends before the ladder's `_G` read.
 fn frame_ladder_context(lua: &Lua, h: FrameHandle) -> (String, String) {
     let model = lua.app_data_ref::<Model>().expect("model");
     let who = model
@@ -25,52 +22,42 @@ fn frame_ladder_context(lua: &Lua, h: FrameHandle) -> (String, String) {
     (who, frame_parent_token_base(&model, h))
 }
 
-/// Populate `m`'s layout (anchor/size) methods (see the module doc).
+/// Populate `m`'s anchor and size methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     // Layout: SetPoint / ClearAllPoints / SetWidth / SetHeight / GetWidth / GetHeight
-    m.set(
+    set_shared(
+        lua,
+        m,
+        Side::Frame,
         "SetPoint",
-        lua.create_function(|lua, (this, rest): (Table, MultiValue)| set_point(lua, &this, &rest))?,
+        |lua, (this, rest): (Table, MultiValue)| set_point(lua, &this, &rest),
     )?;
-    m.set(
-        "ClearAllPoints",
-        lua.create_function(|lua, this: Table| {
-            let h = frame_handle_of(lua, &this)?;
-            let mut model = lua.app_data_mut::<Model>().expect("model");
-            // Every layout setter here follows one law: mutate ONLY on an actual value change,
-            // and report the change to the tier-1 epoch (`touch_layout`). The compare is what
-            // keeps an idempotent per-frame caller (the classic OnUpdate re-SetPoint idiom) from
-            // pinning the gate open — the same absorption the fingerprint gives, paid once at
-            // the write instead of per-frame over the whole model.
-            //
-            // **And it NAMES its node** (decision 2114, completing 1625's migration). Dropping
-            // every anchor is a retarget whose NEW target list is empty, and both lists are right
-            // here — so the cached graph's edges get unlinked instead of thrown away. Left on the
-            // conservative touch, this was the one recurring `[layout-derive]` site in a live
-            // hover sweep: `Bagnon_AnchorTooltip` opens with `GameTooltip:ClearAllPoints()` and
-            // then asks `frame:GetLeft()`, so the whole graph was re-derived INSIDE the handler,
-            // once per hovered item, and billed to `[ui-handlers]`' `OnEnter`.
-            let old: Option<Vec<u32>> = match model.layout_inputs.get_mut(&h) {
-                Some(input) if !input.anchors.is_empty() => {
-                    let old = input.anchors.iter().map(|a| a.relative_to).collect();
-                    input.anchors.clear();
-                    Some(old)
-                }
-                _ => None,
-            };
-            if let Some(old) = old {
-                model.touch_layout_retarget_frame(h, &old, &[]);
+    set_shared(lua, m, Side::Frame, "ClearAllPoints", |lua, this: Table| {
+        let h = frame_handle_of(lua, &this)?;
+        let mut model = lua.app_data_mut::<Model>().expect("model");
+        // Every layout setter mutates only on a real change, so a per-frame caller setting the
+        // same value never reopens the layout gate. Clearing is a retarget to no targets.
+        let old: Option<Vec<u32>> = match model.layout_inputs.get_mut(&h) {
+            Some(input) if !input.anchors.is_empty() => {
+                let old = input.anchors.iter().map(|a| a.relative_to).collect();
+                input.anchors.clear();
+                Some(old)
             }
-            Ok(())
-        })?,
-    )?;
-    // GetPoint([n]) → point, relativeTo, relativePoint, xOfs, yOfs — the n-th (1-based, default
-    // first) anchor. relativeTo is nil when the target is the screen root (the client returns
-    // UIParent there; ours is the distinct `script::SCREEN` sentinel, which has no wrapper of its
-    // own — the arena's `UIParent` frame is a different handle — stated, a consensus-list call).
-    m.set(
+            _ => None,
+        };
+        if let Some(old) = old {
+            model.touch_layout_retarget_frame(h, &old, &[]);
+        }
+        Ok(())
+    })?;
+    // GetPoint([n]) → point, relativeTo, relativePoint, x, y of the n-th anchor (default 1);
+    // relativeTo is nil for a screen-root anchor, since `SCREEN` has no wrapper.
+    set_shared(
+        lua,
+        m,
+        Side::Frame,
         "GetPoint",
-        lua.create_function(|lua, (this, n): (Table, Option<i64>)| {
+        |lua, (this, n): (Table, Option<i64>)| {
             let h = frame_handle_of(lua, &this)?;
             let anchor = {
                 let model = lua.app_data_ref::<Model>().expect("model");
@@ -96,31 +83,27 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 Value::Number(f64::from(a.x_off)),
                 Value::Number(f64::from(a.y_off)),
             ))
-        })?,
+        },
     )?;
-    // GetNumPoints() → how many anchors this frame carries. On the Region map (`0x87c9b8`), so
-    // every widget answers it — the region twin shipped first and noted this side was missing;
-    // collapsing the map to one implementation each (decision 1501) is what made the gap fatal
-    // rather than merely absent, and this is the arm it was missing.
-    m.set(
-        "GetNumPoints",
-        lua.create_function(|lua, this: Table| {
-            let h = frame_handle_of(lua, &this)?;
-            let model = lua.app_data_ref::<Model>().expect("model");
-            Ok(model
-                .layout_inputs
-                .get(&h)
-                .map_or(0, |i| i.anchors.len() as i64))
-        })?,
-    )?;
-    // SetAllPoints([relativeTo]) — pin TOPLEFT+BOTTOMRIGHT to the target (default: the parent),
-    // the XML `setAllPoints="true"` behavior as a method (rf24 `0x767800`'s SetAllPoints path).
-    m.set(
+    // GetNumPoints(): on the Region method table (`0x87c9b8`), so every widget answers it.
+    set_shared(lua, m, Side::Frame, "GetNumPoints", |lua, this: Table| {
+        let h = frame_handle_of(lua, &this)?;
+        let model = lua.app_data_ref::<Model>().expect("model");
+        Ok(model
+            .layout_inputs
+            .get(&h)
+            .map_or(0, |i| i.anchors.len() as i64))
+    })?;
+    // SetAllPoints([relativeTo]): pins TOPLEFT and BOTTOMRIGHT to the target, default the parent,
+    // as XML `setAllPoints="true"` does (`0x767800`).
+    set_shared(
+        lua,
+        m,
+        Side::Frame,
         "SetAllPoints",
-        lua.create_function(|lua, (this, rest): (Table, MultiValue)| {
+        |lua, (this, rest): (Table, MultiValue)| {
             let h = frame_handle_of(lua, &this)?;
-            // `who`/`$parent` first, then the `_G` read, then the guard — see `set_point` and
-            // `object::NamedTarget`.
+            // `who` and `$parent`, then the `_G` read, then the model guard, as in `set_point`.
             let (who, base) = frame_ladder_context(lua, h);
             let target = parse_set_all_points(lua, rest.front(), &base);
             let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -145,27 +128,33 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 model.touch_layout();
             }
             Ok(())
-        })?,
+        },
     )?;
-    m.set(
+    set_shared(
+        lua,
+        m,
+        Side::Frame,
         "SetWidth",
-        lua.create_function(|lua, (this, w): (Table, f32)| {
+        |lua, (this, w): (Table, f32)| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let input = model.layout_inputs.entry(h).or_default();
             let changed = input.width.to_bits() != w.to_bits();
             input.width = w;
             if changed {
-                // A size write moves no edge and no roster membership (decision 1388).
+                // A size write moves no edge and no roster membership.
                 model.touch_layout_frame(h);
             }
             model.note_authored_size(h);
             Ok(())
-        })?,
+        },
     )?;
-    m.set(
+    set_shared(
+        lua,
+        m,
+        Side::Frame,
         "SetHeight",
-        lua.create_function(|lua, (this, ht): (Table, f32)| {
+        |lua, (this, ht): (Table, f32)| {
             let h = frame_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let input = model.layout_inputs.entry(h).or_default();
@@ -176,60 +165,43 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             }
             model.note_authored_size(h);
             Ok(())
-        })?,
-    )?;
-    // **No `SetSize`.** It is an Era geometry verb, in neither the Frame nor the Region method
-    // table of 1.12 — and neither the stock chain nor either addon corpus writes it (decision
-    // 2142's census). The two setters above are the era's whole size surface.
-    m.set(
-        "GetWidth",
-        lua.create_function(|lua, this: Table| {
-            let h = frame_handle_of(lua, &this)?;
-            settle(lua);
-            let model = lua.app_data_ref::<Model>().expect("model");
-            Ok(size_read(&model, h, true))
-        })?,
-    )?;
-    m.set(
-        "GetHeight",
-        lua.create_function(|lua, this: Table| {
-            let h = frame_handle_of(lua, &this)?;
-            settle(lua);
-            let model = lua.app_data_ref::<Model>().expect("model");
-            Ok(size_read(&model, h, false))
-        })?,
+        },
     )?;
+    // No `SetSize`: neither 1.12 method table has it.
+    set_shared(lua, m, Side::Frame, "GetWidth", |lua, this: Table| {
+        let h = frame_handle_of(lua, &this)?;
+        settle(lua);
+        let model = lua.app_data_ref::<Model>().expect("model");
+        Ok(size_read(&model, h, true))
+    })?;
+    set_shared(lua, m, Side::Frame, "GetHeight", |lua, this: Table| {
+        let h = frame_handle_of(lua, &this)?;
+        settle(lua);
+        let model = lua.app_data_ref::<Model>().expect("model");
+        Ok(size_read(&model, h, false))
+    })?;
 
-    // GetCenter() → centerX, centerY — the resolved rect's center in LOCAL units (y-up; screen ÷
-    // the frame's effective scale — the client's convention: coordinate getters report the frame's
-    // own scaled space, and callers divide GetCursorPosition (screen px) by GetEffectiveScale to
-    // meet them there; the ref world map's hover math does exactly that). nil pair before the
-    // first resolve, like the edge readers.
-    m.set(
-        "GetCenter",
-        lua.create_function(|lua, this: Table| {
-            let h = frame_handle_of(lua, &this)?;
-            settle(lua);
-            let model = lua.app_data_ref::<Model>().expect("model");
-            let inv = 1.0 / eff_scale(&model, h);
-            Ok(match model.resolved.get(&h) {
-                Some(r) => (
-                    Value::Number(f64::from((r.left + r.right) * 0.5 * inv)),
-                    Value::Number(f64::from((r.bottom + r.top) * 0.5 * inv)),
-                ),
-                None => (Value::Nil, Value::Nil),
-            })
-        })?,
-    )?;
+    // GetCenter(): the resolved rect's centre in the frame's own units (screen ÷ effective scale,
+    // y-up), as the reference's coordinate getters report; nil before the first resolve.
+    set_shared(lua, m, Side::Frame, "GetCenter", |lua, this: Table| {
+        let h = frame_handle_of(lua, &this)?;
+        settle(lua);
+        let model = lua.app_data_ref::<Model>().expect("model");
+        let inv = 1.0 / eff_scale(&model, h);
+        Ok(match model.resolved.get(&h) {
+            Some(r) => (
+                Value::Number(f64::from((r.left + r.right) * 0.5 * inv)),
+                Value::Number(f64::from((r.bottom + r.top) * 0.5 * inv)),
+            ),
+            None => (Value::Nil, Value::Nil),
+        })
+    })?;
 
-    // GetEffectiveScale() — the frame's real effective scale (parentScale · ownScale, the arena's
-    // propagated product). The ROOT factor is 1, and that is not because benilla lacks a `uiScale`
-    // CVar (it has one, `cvars.rs`, default 0.9): the dial is applied at the RASTER seam — it sets
-    // how many UI units tall the virtual screen is, `768/uiScale` (`ui_script::seam_scale`, 0584) —
-    // rather than as a scale on UIParent. So every coordinate the VM hands Lua is already in those
-    // units, `GetCursorPosition()` included, and the reference's
-    // `GetCursorPosition()/GetEffectiveScale()` transcriptions convert screen→local correctly with
-    // a root of 1; a SetScale'd subtree (the windowed world map) still reports its true factor.
+    // GetEffectiveScale(): parent scale times own scale, from a root of 1: `uiScale` is applied at
+    // the raster seam (a screen `768/uiScale` units tall), so every coordinate Lua sees,
+    // `GetCursorPosition()` included, is already in UI units. The reference instead makes
+    // `uiScale` `UIParent`'s own scale (`0x494550` calls `SetScale`), so there
+    // `UIParent:GetEffectiveScale()` answers it.
     m.set(
         "GetEffectiveScale",
         lua.create_function(|lua, this: Table| {
@@ -239,71 +211,36 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLeft/GetRight/GetTop/GetBottom — the frame's RESOLVED edges in LOCAL units (y-up, so
-    // GetBottom is height-from-screen-bottom, the era semantics; `GetRect 0x768320`'s Lua faces,
-    // layout.rs's module doc; screen ÷ effective scale like GetCenter). `nil` before the first
-    // resolve — callers treat that as "not laid out yet" (the ref's own FauxScrollFrame code
-    // nil-checks these too).
+    // GetLeft/GetRight/GetTop/GetBottom: the resolved edges in the frame's own units, y-up from
+    // the screen bottom (`GetRect 0x768320`); nil before the first resolve.
     for (name, pick) in [
         ("GetLeft", 0u8),
         ("GetRight", 1u8),
         ("GetTop", 2u8),
         ("GetBottom", 3u8),
     ] {
-        m.set(
-            name,
-            lua.create_function(move |lua, this: Table| {
-                let h = frame_handle_of(lua, &this)?;
-                settle(lua);
-                let model = lua.app_data_mut::<Model>().expect("model");
-                let inv = 1.0 / eff_scale(&model, h);
-                Ok(model.resolved.get(&h).map(|r| {
-                    inv * match pick {
-                        0 => r.left,
-                        1 => r.right,
-                        2 => r.top,
-                        _ => r.bottom,
-                    }
-                }))
-            })?,
-        )?;
+        set_shared(lua, m, Side::Frame, name, move |lua, this: Table| {
+            let h = frame_handle_of(lua, &this)?;
+            settle(lua);
+            let model = lua.app_data_mut::<Model>().expect("model");
+            let inv = 1.0 / eff_scale(&model, h);
+            Ok(model.resolved.get(&h).map(|r| {
+                inv * match pick {
+                    0 => r.left,
+                    1 => r.right,
+                    2 => r.top,
+                    _ => r.bottom,
+                }
+            }))
+        })?;
     }
     Ok(())
 }
 
-/// The frame's effective scale, ε-guarded (a zero would poison the local-unit division).
-/// **Resolve the layout graph NOW if anything has moved since the last pass.**
-///
-/// The client answers a geometry query against current layout; ours cached rects in a per-frame
-/// `resolve()` pass, so a query made EARLIER IN THE SAME CALL STACK than that pass read nil. That
-/// is not an edge case — it is what every menu does. `Dewdrop-2.0.lua` (embedded in ~65 corpus
-/// addons) creates its menu frame, anchors it, shows it and then measures it inside one `OnClick`:
-///
-/// ```lua
-/// local left = frame:GetLeft()                                              -- l.1942, nil for us
-/// frame:SetPoint(point, parent, relativePoint, curX - left - width / 2, 0)  -- l.1960, dies
-/// ```
-///
-/// **97 of the 108 addons that drew and then raised on being touched died on that one line.** No
-/// missing verb: `GetLeft` was always there, and always answered nil.
-///
-/// Cheap on a SETTLED tree: `resolve_layout`'s tier-1 gate is one epoch comparison that returns
-/// immediately when nothing has been touched, so a run of getters pays a compare each.
-///
-/// **The interleaved case is not, and this is measured rather than asserted.** A write bumps the
-/// epoch, so `SetPoint; GetLeft; SetPoint; GetLeft; …` resolves the whole graph once per iteration.
-/// Timed on a 200-frame tree: 30 alternating pairs cost **1.41 ms** against **54 µs** for the same
-/// writes with a single read at the end — ~26x, about 47 µs per settle, and the per-settle half
-/// scales with the GRAPH, not the loop.
-///
-/// That is exactly the shape Dewdrop's menu builder has, so opening a menu pays it once. It buys a
-/// menu that works at all, which is the trade taken here. If it ever reads as a hitch, the fix is a
-/// narrower resolve (the queried frame's subtree), not a return to the stale cache.
-///
-/// **It deliberately does NOT fire `OnSizeChanged`.** That drain runs Lua handlers, and re-entering
-/// Lua from inside a binding is how a borrow panic or an unbounded recursion happens. The
-/// size-change queue is drained by the next real `UiScript::resolve`, one tick later than the
-/// reference's per-rect-application fire (`ApplyRect 0x76b580`). Stated rather than hidden.
+/// Resolve the layout now if anything moved, as the reference answers a geometry query against
+/// current layout; a settled tree costs one epoch compare. Deviation: `OnSizeChanged` fires at the
+/// next `UiScript::resolve`, a tick after the reference's (`ApplyRect 0x76b580`), because running
+/// Lua handlers inside a binding risks a borrow panic or unbounded recursion.
 fn settle(lua: &Lua) {
     let mut model = lua.app_data_mut::<Model>().expect("model");
     crate::script::UiScript::resolve_layout(&mut model);
@@ -322,10 +259,8 @@ pub(crate) fn eff_scale(model: &Model, h: FrameHandle) -> f32 {
     }
 }
 
-/// `GetWidth`/`GetHeight`: the resolved rect's span in LOCAL units (screen ÷ effective scale — the
-/// client returns the value as authored, and `SetWidth(w)` on a scaled frame resolves to `w·scale`
-/// screen px) if `resolve` has produced one, else the explicit size the frame was given
-/// (`SetWidth`/`SetHeight`, already local) — matching the client's "0 = derive".
+/// `GetWidth`/`GetHeight`: the resolved span in the frame's own units (screen ÷ effective scale),
+/// else the size it was given, where 0 means derived, as in the reference.
 fn size_read(model: &Model, h: FrameHandle, width: bool) -> f32 {
     if let Some(r) = model.resolved.get(&h) {
         let span = if width { r.width() } else { r.height() };
@@ -338,15 +273,13 @@ fn size_read(model: &Model, h: FrameHandle, width: bool) -> f32 {
         .unwrap_or(0.0)
 }
 
-/// `SetPoint(point [, relativeTo [, relativePoint]] [, x, y])` — `0x7a2540`, whose argument ladder
-/// (and whose five raises) live in [`super::anchor_args`] because the reference runs **one**
-/// function for frames and regions alike. What is this side's own is only what the reference reads
-/// off a *frame*: the layout parent's default id, and the anchor list the commit writes.
+/// `SetPoint` (`0x7a2540`) for a frame: the argument ladder is [`super::anchor_args`], shared with
+/// regions; this side supplies the default parent and commits the anchor.
 fn set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     let (who, base) = frame_ladder_context(lua, h);
-    // The `_G` read inside the ladder runs with NO model guard alive — the reference's read is a
-    // gettable, so an `__index` on `_G` can run Lua that calls back in (`object::NamedTarget`).
+    // No model guard is alive across the ladder: its `_G` read is a `lua_gettable`, and an
+    // `__index` can call back in.
     let p = parse_set_point(lua, args, &who, &base)?;
 
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -357,12 +290,8 @@ fn set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
 
     let input = model.layout_inputs.entry(h).or_default();
     let new = Anchor::new(point, rel_to_id, rel_point, x, y);
-    // No-op detection must mirror the retain+push below EXACTLY (the fingerprint hashes the vec
-    // in order, so a same-anchor call that would still REORDER the vec is a real change): a call
-    // is idempotent only when the identical anchor already sits at the tail and no earlier entry
-    // carries this point. Anchor's derived PartialEq compares f32 by value, which calls -0.0 ==
-    // 0.0 where the fingerprint's bit-compare would not — compare bits, or the verify assert
-    // trips on that (authored-XML-real) edge.
+    // A no-op only when the identical anchor is already last and no earlier one has this point,
+    // mirroring the retain and push below; bits compared, as the fingerprint tells -0.0 from 0.0.
     let same_at_tail = input
         .anchors
         .last()
@@ -371,14 +300,8 @@ fn set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
             .iter()
             .any(|a| a.point == point);
     if !same_at_tail {
-        // Value-only unless the target moved (decision 1388) — the per-frame `SetPoint` idiom
-        // (a dragged window, a moving spark) re-points the SAME anchor at the SAME target with new
-        // offsets, so it names its node and the cached graph survives the frame.
-        //
-        // A retarget names its node too now (decision 1625): the edge set is not derivable from a
-        // per-node hash, but it IS derivable from the anchors, and both lists are right here. The
-        // target lists are collected only on the structural path — the value-only one is the hot
-        // idiom and must stay allocation-free.
+        // Target lists are collected only for a retarget: the value-only change is the per-frame
+        // idiom (a dragged window) and must stay allocation-free.
         let structural = anchor_retarget_is_structural(&input.anchors, &new);
         let old_targets: Option<Vec<u32>> =
             structural.then(|| input.anchors.iter().map(|a| a.relative_to).collect());
@@ -399,24 +322,8 @@ fn set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Would this `SetPoint` change the node's set of anchor TARGETS — i.e. is it structural?
-///
-/// The layout scope's reverse edges are built from `Anchor::relative_to` (decision 1350): "this
-/// node reads that node's rect". An anchor whose OFFSETS moved is a value change — the node
-/// re-solves and nothing else does, which is exactly what a precise touch claims. An anchor whose
-/// TARGET moved is not: an edge has to disappear and another to appear, and no per-node hash can
-/// say so.
-///
-/// 1388 answered that by throwing the cached graph away. **Since decision 1625 it does not have
-/// to be**: the write site holds both target lists, so the node's edges are re-pointed in place
-/// (`Model::touch_layout_retarget_frame`) and the roster and every other node's hash survive.
-/// What this predicate decides is therefore no longer "value change or catastrophe" but which of
-/// two precise touches to use — and it still earns its place, because the value-only answer is
-/// the hot per-frame idiom and must stay allocation-free.
-///
-/// Mirrors the `retain(point) + push` the setters do. It is value-only in exactly one shape — one
-/// existing anchor carries this point and keeps the same target. Zero (an edge appears) and two or
-/// more (edges disappear) are both structural, and so is any change of target.
+/// Whether this `SetPoint` changes the node's anchor targets, mirroring the setters' retain and
+/// push: value-only exactly when one existing anchor has this point and keeps its target.
 pub(crate) fn anchor_retarget_is_structural(anchors: &[Anchor], new: &Anchor) -> bool {
     let mut same_point = anchors.iter().filter(|a| a.point == new.point);
     match (same_point.next(), same_point.next()) {
@@ -425,9 +332,7 @@ pub(crate) fn anchor_retarget_is_structural(anchors: &[Anchor], new: &Anchor) ->
     }
 }
 
-/// Bit-exact anchor equality — the same lens the layout gate's fingerprint reads anchors through
-/// (`InputFingerprint::anchors` feeds `f32::to_bits`), so the setters' no-op detection and the
-/// gate can never disagree about whether a write "changed" something.
+/// Bit-exact anchor equality, as the layout gate's fingerprint compares, so the two always agree.
 pub(crate) fn anchor_bits_eq(a: &Anchor, b: &Anchor) -> bool {
     a.point == b.point
         && a.relative_to == b.relative_to
@@ -436,8 +341,7 @@ pub(crate) fn anchor_bits_eq(a: &Anchor, b: &Anchor) -> bool {
         && a.y_off.to_bits() == b.y_off.to_bits()
 }
 
-/// The default `relativeTo` id for a `SetPoint` with no explicit target: the frame's parent id, or
-/// [`SCREEN`] if it is top-level (the client anchors top-level frames to `UIParent`/the screen root).
+/// The default `relativeTo`: the parent, or [`SCREEN`] for a top-level frame (`0x76c6e0`).
 fn default_parent_id(model: &mut Model, h: FrameHandle) -> u32 {
     match model.arena.frame(h).and_then(|f| f.parent) {
         Some(p) => model.frame_id(p),
diff --git a/crates/benilla-ui/src/script/object/movable.rs b/crates/benilla-ui/src/script/object/movable.rs
index 7bfb3fe1..fbfa6ff8 100644
--- a/crates/benilla-ui/src/script/object/movable.rs
+++ b/crates/benilla-ui/src/script/object/movable.rs
@@ -1,82 +1,14 @@
-//! Frame method-table cluster: the movable/resizable window family — `SetMovable`/`IsMovable`,
-//! `StartMoving`/`StopMovingOrSizing`, `SetUserPlaced`/`IsUserPlaced`, `SetResizable`/
-//! `IsResizable`. Split out of [`super`] purely for size — see its module doc for the shared
-//! id/handle plumbing and method-table wiring.
+//! Frame methods: movable and resizable windows, and the drag pumps behind `StartMoving` and
+//! `StartSizing`. The gesture that usually calls them, `OnDragStart`/`OnDragStop` (`0x76bf70`/
+//! `0x76c040`), is [`crate::script::cursor`]'s.
 //!
-//! This is "drag this bar somewhere", and after events it is the most-used addon frame feature.
-//! The canonical idiom is four lines, of which only the two engine verbs were missing here:
+//! The flags are bits of `[frame+0xb4]`, set by `0x76a3c0`: movable `0x100`, resizable `0x200`,
+//! userPlaced `0x1000`. A drag (`0x7652b0`) re-anchors the frame to one TOPLEFT against the screen
+//! root at its current rect (`0x768430`), raises it, sets userPlaced and takes the one drag slot
+//! (`root+0xcfc`). The pump (`0x7655b0`) adds each cursor delta, over the frame's scale, straight
+//! into that anchor's offsets (`0x768710` case 4), so stopping (`0x765640`) writes nothing.
 //!
-//! ```lua
-//! f:SetMovable(true)
-//! f:RegisterForDrag("LeftButton")
-//! f:SetScript("OnDragStart", function() this:StartMoving() end)
-//! f:SetScript("OnDragStop",  function() this:StopMovingOrSizing() end)
-//! ```
-//!
-//! and that layering is the reference's own: `RegisterForDrag 0x776d60` + the threshold-gated
-//! `OnDragStart`/`OnDragStop` pair (wow-re `cursor-dragdrop-payload.md` §9, our decision 0216 §3 —
-//! [`crate::script::cursor`], dispatched from [`crate::script::pointer`]) are a **separate**
-//! system from the engine move below. The gesture decides *when* the handlers run; this module
-//! owns only what happens between `StartMoving` and `StopMovingOrSizing`.
-//!
-//! ## The mechanism (wow-re `system/ui`, VERIFIED unless said otherwise)
-//!
-//! The three flags are bits of the frame's flag word `[frame+0xb4]`, all written by the one
-//! generic setter `0x76a3c0` (`if (v) flags |= mask; else flags &= ~mask;` — no calls, no side
-//! effects): **movable `0x100`** (`SetMovable 0x776420` / `IsMovable 0x7764d0`), **resizable
-//! `0x200`** (`SetResizable 0x776590` / `IsResizable 0x776640`), **userPlaced `0x1000`**
-//! (`SetUserPlaced 0x776a50` / `IsUserPlaced 0x776b40`). The XML attributes land on the same
-//! setter (`movable="true"` → `0x76a3c0(0x100)`, `resizable="true"` → `0x200` — wow-re
-//! `rf24-framexml-loader.md`), which is why the loader now *calls* these instead of warning.
-//!
-//! `StartMoving 0x776700` tests the movable bit and raises when it is clear, then enters the drag
-//! at `0x7652b0`, which `Raise()`s the frame, **sets the userPlaced bit itself**, and records the
-//! whole drag in ONE root-side slot: `root+0xcfc` = the dragged frame, `+0xd00` = the drag type
-//! (Lua `StartMoving` passes **3**), `+0xd08/+0xd0c` = the cursor at the last sample. One slot
-//! means one drag: there is no second frame to move, which is why `StartMoving` carries a
-//! `root+0xcfc != 0` guard at `7767e8` and why `StopMovingOrSizing 0x776990` compares
-//! `[root+0xcfc] == self` before clearing.
-//!
-//! Movement is a **pump**, run from the mouse-move handler: `0x7655b0` (a diffed-bit-exact
-//! PRIMITIVE) takes `dx = x − root+0xd08`, `dy = y − root+0xd0c`, and — only if either is
-//! non-zero — applies them and re-centers the sample. The application (`0x76a660` → the 9-case
-//! `geo_768710`, also a diffed-bit-exact PRIMITIVE) selects on the 3×3 region the drag grabbed:
-//! the eight edge/corner cases resize, and **case 4, the plain move, accumulates the scaled delta
-//! straight into the anchor's offsets in place** — `xOffset += dx/scale`, `yOffset += dy/scale`
-//! (`CAnchor+0x4`/`+0x8`, wow-re `frame-model.md`) — then invalidates the layout (`0x7680e0`).
-//!
-//! Two consequences worth stating, because both are easy to get wrong:
-//!
-//! - **Nothing is written at stop.** `0x765640` is a fifteen-byte state clear (`root+0xcfc = 0;
-//!   root+0xd00 = 0`) — there is no `SetPoint`, no `ClearAllPoints`, no rewrite of the anchor set
-//!   to a single point. The frame keeps where it was dragged to because the *anchors themselves*
-//!   were being moved the whole time, so `GetPoint()` afterwards reports the frame's own point
-//!   with the dragged offsets — exactly what an addon then saves.
-//! - **The mouse button does not end a Lua move.** The mouse-up handler `0x766420` auto-stops
-//!   only drag types 1 and 2 (the built-in title-bar/edge drags); type 3 — the one `StartMoving`
-//!   starts — must be stopped by an explicit `StopMovingOrSizing`. That is why the idiom above
-//!   wires `OnDragStop` at all.
-//!
-//! ## What benilla does NOT take from that, and why
-//!
-//! - **All anchors translate, not just one.** wow-re's note reads the case-4 accumulate as hitting
-//!   a single anchor record; it is their composition of verified pieces, not a recorded finding,
-//!   and a one-anchor translation would *deform* a frame stretched between two anchors instead of
-//!   moving it. Every movable frame in practice carries exactly one anchor, where the two readings
-//!   are identical, so translating the whole set is the same behaviour everywhere it is observable
-//!   and the sane behaviour where it is not.
-//! - **No clamp rebate.** `geo_768710` rebates the residual delta when the clamp pushes back
-//!   (`SetClampedToScreen`); we do not, so dragging a clamped frame into the screen edge and back
-//!   out can lag the cursor. Named, not hidden — the rebate is one of the two halves of that
-//!   primitive we have not transcribed (the other is the eight resize cases).
-//! - **The `Raise()` is wired** (it used to be listed here as a deferral): `0x7652b0` raises the
-//!   dragged frame before it takes the drag slot, and [`start_moving`] does the same through
-//!   [`super::toplevel::raise`]. Like every raise it is occlusion-gated and confined to the frame's
-//!   own stratum, so grabbing a movable window that overlaps nothing still changes no draw order.
-//! - **The resize drag is built** (`StartSizing 0x776830` + [`advance_size`]), including the
-//!   min/max clamp and its rebate; what is *not* transcribed is which edges travel — the reference
-//!   collapses the frame to one planted TOPLEFT anchor at `StartSizing` and we keep the authored
-//!   anchor set, which [`advance_size`]'s own note states rather than hides.
+//! Here nothing re-anchors: a move translates every authored anchor, and a resize keeps the set.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -86,29 +18,15 @@ use crate::widget::FrameHandle;
 use super::frame_handle_of;
 use super::layout_methods::eff_scale;
 
-/// The one in-flight `StartMoving` — the client's `root+0xcfc`/`+0xd08`/`+0xd0c` drag slot, held
-/// in [`Model::moving`] beside the drag gesture that normally drives it.
-///
-/// `sample` is the cursor at the last pump, not at the grab: [`advance_move`] applies the
-/// *difference* and re-centers, which is `0x7655b0`'s own shape. Nothing else is needed, because
-/// the position being edited lives in the frame's anchors rather than here.
-///
-/// Pruning on frame destroy: the same boat as [`Model::drag_registered`] — nothing in this engine
-/// destroys a frame yet; [`advance_move`] ends a move whose frame went away regardless.
+/// The one in-flight move, the reference's drag slot, held in [`Model::moving`].
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) struct FrameMove {
     /// The frame being moved (`root+0xcfc`).
     frame: FrameHandle,
     /// The cursor position at the last pump (`root+0xd08`/`+0xd0c`), UI px, y-up.
     sample: (f32, f32),
-    /// Whether releasing the mouse ends this move on its own.
-    ///
-    /// **The reference's drag MODE, reduced to the one bit that is observable from Lua.** The
-    /// mouse-up handler `0x766420` auto-cancels modes 1 (modifier-drag) and 2 (title region) and
-    /// leaves mode 3 (`StartMoving`) running until `StopMovingOrSizing`
-    /// (wow-re `widget-api-batch-benilla.md` Q6). So a title drag ends on release while a scripted
-    /// one outlives the button — which is exactly the distinction this module's own doc already
-    /// records for the drag/move split.
+    /// Whether mouse-up ends the move, the drag mode as Lua sees it: `0x766420` ends modes 1
+    /// (modifier drag) and 2 (title region), never 3 (`StartMoving`).
     pub(crate) auto_stop: bool,
 }
 
@@ -116,8 +34,7 @@ pub(crate) struct FrameMove {
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) struct FrameSizing {
     frame: FrameHandle,
-    /// The grip the caller named — the EDGES this drag moves. `LEFT` moves the left edge and
-    /// leaves the right where it is, `BOTTOMRIGHT` moves both of those, and so on.
+    /// The edges the named grip moves: `LEFT` the left edge, `BOTTOMRIGHT` the bottom and right.
     left: bool,
     right: bool,
     top: bool,
@@ -125,14 +42,10 @@ pub(crate) struct FrameSizing {
     sample: (f32, f32),
 }
 
-/// Populate `m`'s movable/resizable methods (see the module doc).
+/// Populate `m`'s movable and resizable methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // SetMovable(flag) / IsMovable() — flag word bit 0x100 (`0x776420`/`0x7764d0` through the
-    // generic setter `0x76a3c0`). A pure flag write: it moves nothing, and clearing it mid-drag
-    // stops nothing either (the setter has no side effects — wow-re ledger `0x76a3c0`); it is the
-    // guard `StartMoving` tests, and the XML `movable="true"` attribute writes the same bit.
-    // mlua's bool conversion is Lua truthiness, so the corpus's `SetMovable(1)` reads as true —
-    // matching the reference binding's own `toboolean` marshal.
+    // SetMovable / IsMovable (`0x776420`/`0x7764d0`): a pure flag write, so clearing it mid-drag
+    // stops nothing. The argument is Lua truthiness, as the reference's `toboolean`.
     m.set(
         "SetMovable",
         lua.create_function(|lua, (this, flag): (Table, bool)| {
@@ -143,8 +56,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "IsMovable",
         lua.create_function(|lua, this: Table| get_flag(lua, &this, Flag::Movable))?,
     )?;
-    // SetResizable(flag) / IsResizable() — bit 0x200 (`0x776590`/`0x776640`), `SetMovable`'s exact
-    // shape. Stored and reported; no resize DRAG is built (see the module doc).
+    // SetResizable / IsResizable (`0x776590`/`0x776640`): the same pure flag write.
     m.set(
         "SetResizable",
         lua.create_function(|lua, (this, flag): (Table, bool)| {
@@ -155,27 +67,12 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "IsResizable",
         lua.create_function(|lua, this: Table| get_flag(lua, &this, Flag::Resizable))?,
     )?;
-    // ── The resize-bounds quad — `Set/GetMinResize`, `Set/GetMaxResize` ────────────────────────
+    // ── Resize bounds ──
     //
-    // Frame method table `0x878ec0`: `GetMinResize 0x775f20` · `SetMinResize 0x776020` ·
-    // `GetMaxResize 0x7761a0` · `SetMaxResize 0x7762a0`. Byte-carved end to end by wow-re
-    // (`system/ui/scratch/resize-bounds-and-button-fontstring.md` §2), and every clause below is
-    // from that read rather than from the shape of the name:
-    //
-    //  · **The argument gate is `lua_isnumber`, not a strict number** (`0x6f34d0` on BOTH slots 2
-    //    and 3), so a numeric STRING passes and is coerced — while a missing argument, an explicit
-    //    `nil`, a boolean, a table or a non-numeric string fails. Either slot failing raises
-    //    `Usage: %s:SetMinResize(minWidth, minHeight)` (`0x8797b8`) / the `MaxResize` twin
-    //    (`0x8797e4`), with `%s` the frame's name or `<unnamed>`. Arguments past slot 3 are
-    //    ignored; there is no upper arity check.
-    //  · **Stored RAW, and nothing else happens.** After the store-backs each setter is
-    //    `pop/pop/xor eax,eax/pop/…/ret` — no layout invalidate, no dirty mark, no `min > max`
-    //    reconciliation, and the frame's current size is never read. Setting a bound a frame
-    //    already violates does nothing at all until the next drag tick.
-    //  · **Zero return values from the setters; TWO from the getters, always** — `(width, height)`
-    //    as plain numbers, `0, 0` on a frame nobody bounded. Never `nil`: `0.0` is the client's
-    //    unbounded sentinel, so the "unset" answer and the "explicitly unbounded" answer are the
-    //    same answer, by construction.
+    // `SetMinResize 0x776020`, `GetMinResize 0x775f20`, `SetMaxResize 0x7762a0`,
+    // `GetMaxResize 0x7761a0`. Both arguments must pass `lua_isnumber` (`0x6f34d0`), else `Usage:`
+    // (`0x8797b8`/`0x8797e4`); the pair is stored raw, with no layout touch and no `min > max`
+    // check. The getters always answer two numbers, 0 meaning unbounded.
     for (name, upper) in [("MinResize", false), ("MaxResize", true)] {
         m.set(
             format!("Set{name}"),
@@ -187,7 +84,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 };
                 let h = frame_handle_of(lua, &this)?;
                 let pair = (it.next(), it.next());
-                // `lua_isnumber`'s own set: a number, or a string 5.0's `luaV_tonumber` converts.
+                // `lua_isnumber`: a number, or a string Lua 5.0's `luaV_tonumber` converts.
                 let num = |v: &Option<Value>| match v {
                     Some(Value::Number(n)) => Some(*n as f32),
                     Some(Value::Integer(i)) => Some(*i as f32),
@@ -238,17 +135,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?;
     }
 
-    // SetUserPlaced(flag) / IsUserPlaced() — bit 0x1000 (`0x776a50`/`0x776b40`), the client's "the
-    // user placed this frame; persist its position across sessions" bit, and the one setter of the
-    // three that is GUARDED: `776adb: test ah,0x3` refuses unless the frame is movable OR
-    // resizable, raising the third of this family's error strings.
-    //
-    // **The consumer is [`crate::script::layout_cache`]**, which is where it belongs: persisting a
-    // frame's position is the layout cache's job, not the drag's, and a private position store
-    // here would have put a second one beside the one that should own it. The bit is what that
-    // module enumerates on, so setting it is how a frame opts into being remembered — and the
-    // overwhelmingly common addon shape (set the bit, then save your own coordinates) still works
-    // either way.
+    // SetUserPlaced / IsUserPlaced (`0x776a50`/`0x776b40`): the bit that makes the layout cache
+    // save the frame's position; the one guarded setter, refusing a frame that is neither movable
+    // nor resizable (`0x776adb`).
     m.set(
         "SetUserPlaced",
         lua.create_function(|lua, (this, flag): (Table, bool)| {
@@ -264,9 +153,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             if let Some(f) = model.arena.frame_mut(h) {
                 if f.user_placed != flag {
                     f.user_placed = flag;
-                    // The layout cache's persist cue ([`crate::script::layout_cache`]): a frame
-                    // that has just BECOME user-placed owes the file a row, and one that stopped
-                    // owes it the row's removal. Both are the same "rewrite it" bit.
+                    // Either transition owes the layout cache a rewrite: a row added or removed.
                     model.user_placed_changed = true;
                 }
             }
@@ -277,10 +164,6 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         "IsUserPlaced",
         lua.create_function(|lua, this: Table| get_flag(lua, &this, Flag::UserPlaced))?,
     )?;
-    // StartMoving() — enter the drag (`0x776700` → `0x7652b0`). Raises on a frame that is not
-    // movable, sets the userPlaced bit like the reference's drag-start does, and takes the one
-    // drag slot; a second call while a move is in flight is refused, since there is only ever one
-    // slot to take.
     m.set(
         "StartMoving",
         lua.create_function(|lua, this: Table| {
@@ -289,21 +172,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             start_moving(&mut model, h)
         })?,
     )?;
-    // StartSizing(point) — begin a resize drag from a named grip (`0x776830`, verified in wow-re's
-    // ledger; the reference's own caller is `FloatingChatFrame.lua:600`,
-    // `this:GetParent():StartSizing(anchorPoint)`).
-    //
-    // **What is verified and what is read, kept apart on purpose.** Verified: the verb exists, it
-    // takes the grip name, it returns nothing, and `StopMovingOrSizing` ends it (the same slot
-    // clear as a move). NOT recorded anywhere in wow-re — the ledger has it as ORCHESTRATION with
-    // no inline math — is WHICH EDGES a given grip moves. Taken here as the plain meaning of an
-    // anchor point, which is how the reference's own caller uses it (its resize grips pass the
-    // corner they sit in): the named edges follow the cursor and the opposite ones stay put. If an
-    // RE pass ever contradicts that, this comment is where to correct it.
-    //
-    // Four corpus addons reach it through ONE line — `FuBar_Panel.lua:980`, replicated into
-    // FuBar_CorkFu, FuBar_FuXPFu, FuBar_SpellStatusFu and oRA2 — which is 1207's rule and why the
-    // count is not four independent votes.
+    // StartSizing(point) (`0x776830`; stock caller `FloatingChatFrame.lua:600`): a resize from the
+    // named grip, ended by `StopMovingOrSizing`. The reference's per-grip switch (`0x768710`)
+    // moves the named edges with the cursor and keeps the opposite ones.
     m.set(
         "StartSizing",
         lua.create_function(|lua, (this, point): (Table, Option<String>)| {
@@ -319,33 +190,22 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let p = point.unwrap_or_default().to_ascii_uppercase();
             let (left, right) = (p.contains("LEFT"), p.contains("RIGHT"));
             let (top, bottom) = (p.contains("TOP"), p.contains("BOTTOM"));
-            // The raise and the userPlaced bit are the ENTRY's, not the grip's: `0x7652b0` runs
-            // for every `StartSizing` whatever it was handed, and only the pump's per-grip switch
-            // is selective. So both happen before the grip is looked at.
+            // The raise and userPlaced belong to the drag entry `0x7652b0`, whatever the grip.
             super::toplevel::raise(&mut model, h);
             set_user_placed(&mut model, h);
             let sample = model.cursor_pos;
-            // **`StartSizing("CENTER")` is a MOVE, not a resize** — and it is a real case, not a
-            // caller error. The pump's switch is on the anchor point-id, and case 4 (CENTER) is the
-            // one arm that never touches width or height: it shifts the frame's anchor offsets and
-            // returns before the clamp is ever reached, so a CENTER grip is unbounded by
-            // construction (wow-re `resize-bounds-and-button-fontstring.md` §3.6). This file used
-            // to say *"a grip naming no edge would resize nothing; the reference has no such call
-            // and we refuse rather than invent one"* — the bytes have since answered that, and the
-            // answer is the translate below, which is exactly what [`advance_move`] already does.
+            // A CENTER grip is a move: the pump's case 4 shifts the anchor offsets and returns
+            // before the size clamp (`0x768bfb`).
             if p == "CENTER" {
                 model.moving = Some(FrameMove {
                     frame: h,
                     sample,
-                    // `StartSizing` enters at `0x7652b0(frame, 3, …)` — drag mode 3, the one the
-                    // mouse-up handler does NOT auto-cancel — whatever grip it was handed. So a
-                    // CENTER grip outlives the button release, like `StartMoving`'s.
+                    // `StartSizing` enters as drag mode 3 (`0x7652b0`), which mouse-up never ends.
                     auto_stop: false,
                 });
                 return Ok(());
             }
-            // Any other name resolves to no point-id at all, so the pump falls to its default tail
-            // and the drag is inert — started (raised, userPlaced) but moving nothing.
+            // A name that is no point starts an inert drag: raised and userPlaced, moving nothing.
             model.sizing = Some(FrameSizing {
                 frame: h,
                 left,
@@ -357,11 +217,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // StopMovingOrSizing() — leave the drag (`0x776990` → `0x765640`): a state clear, and only
-    // when `self` IS the frame in the slot. Nothing is written back — the pump has been moving the
-    // anchors all along, so the frame simply keeps the last position it was dragged to. Harmless
-    // when nothing is moving, or when something else is (a double call, an addon that also wires
-    // it to OnMouseUp, an OnDragStop that never had a StartMoving).
+    // StopMovingOrSizing (`0x776990` → `0x765640`): clears the slot only when it holds this frame.
     m.set(
         "StopMovingOrSizing",
         lua.create_function(|lua, this: Table| {
@@ -379,8 +235,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Which bit of the frame's flag word a `Set*`/`Is*` pair addresses (`[frame+0xb4]`, written by
-/// `0x76a3c0`) — the three benilla models, as arena fields rather than a packed word.
+/// A bit of the frame's flag word (`[frame+0xb4]`), kept here as an arena field.
 #[derive(Clone, Copy)]
 enum Flag {
     /// `0x100`.
@@ -404,8 +259,7 @@ fn set_flag(lua: &Lua, this: &Table, which: Flag, value: bool) -> mlua::Result<(
     Ok(())
 }
 
-/// `IsMovable`/`IsResizable`/`IsUserPlaced` — the NUMBER 1 or nil, never a boolean (1830,
-/// [`crate::script::binding_abi::flag`]).
+/// `IsMovable`/`IsResizable`/`IsUserPlaced`: 1 or nil, never a boolean.
 fn get_flag(lua: &Lua, this: &Table, which: Flag) -> mlua::Result<Value> {
     let h = frame_handle_of(lua, this)?;
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -418,13 +272,8 @@ fn get_flag(lua: &Lua, this: &Table, which: Flag) -> mlua::Result<Value> {
     ))
 }
 
-/// The family's refusal, named frame and all — the reference's own shape (it formats the frame's
-/// `GetName()`, substituting a literal when the frame is anonymous).
-///
-/// **The text is OURS.** wow-re records the guards and the three `.rdata` addresses
-/// (`0x879810` StartMoving, `0x879828` StartSizing, `0x879844` SetUserPlaced) but not the strings
-/// at them — only the truncated IDA symbol stubs `aFrameSIsNotMov` / `aFrameSIsNotRes` /
-/// `aFrameSIsNotM_0`, which is what this wording is shaped after. Nothing should match on it.
+/// The family's refusal, naming the frame as the reference does. The wording is ours: the strings
+/// at `0x879810`, `0x879828` and `0x879844` are unread, known only by their symbol names.
 fn not_flagged(model: &Model, h: FrameHandle, want: &str) -> mlua::Error {
     let who = model
         .arena
@@ -434,46 +283,31 @@ fn not_flagged(model: &Model, h: FrameHandle, want: &str) -> mlua::Error {
     mlua::Error::runtime(format!("Frame {who} is not {want}"))
 }
 
-/// `StartMoving()`'s body (`0x776700` → `0x7652b0`): refuse a frame that is not movable, refuse a
-/// second move while one is in flight (there is one drag slot), **raise**, then take the slot —
-/// setting the userPlaced bit, which the reference's drag-start does itself rather than leaving to
-/// `SetUserPlaced`.
+/// `StartMoving` (`0x776700` → `0x7652b0`): errors on a frame that is not movable (`0x77678b`),
+/// ignores a second move, then raises the frame, sets userPlaced and takes the slot, in that order.
 fn start_moving(model: &mut Model, h: FrameHandle) -> mlua::Result<()> {
     if !model.arena.frame(h).is_some_and(|f| f.movable) {
         return Err(not_flagged(model, h, "movable"));
     }
-    // `7767e8`'s `root+0xcfc != 0` guard. What the reference does past *not starting a second
-    // move* is not recorded; refusing silently is the reading that cannot invent behaviour.
+    // The `root+0xcfc != 0` guard (`0x7767e8`); what the reference does beyond not starting a
+    // second move is untraced.
     if model.moving.is_some() {
         return Ok(());
     }
-    // The drag-start raise — `0x7652b0` @`0x7652d7`, before it sets the userPlaced bit and records
-    // the drag slot, which is the order kept here. Grabbing a window brings it forward; the worker
-    // supplies the toplevel gate (a non-toplevel movable frame raises nothing).
+    // The drag-start raise (`0x7652d7`); the worker applies the toplevel gate.
     super::toplevel::raise(model, h);
     set_user_placed(model, h);
     model.moving = Some(FrameMove {
         frame: h,
         sample: model.cursor_pos,
-        // Lua `StartMoving` is mode 3: it survives the button and ends only at
-        // `StopMovingOrSizing`.
+        // Mode 3: only `StopMovingOrSizing` ends it.
         auto_stop: false,
     });
     Ok(())
 }
 
-/// Begin a **title-region** move — mode 2, the drag a mouse-down inside `frame:GetTitleRegion()`
-/// starts (wow-re Q6, `0x7662c0` → `0x765320(frame, mode=2, …)` → `0x7652b0`).
-///
-/// [`start_moving`]'s body **minus the movable gate**, and that omission is the carved part rather
-/// than a shortcut: the movable bit is `frame+0xb4 & 0x100`, tested by `StartMoving` (`0x77678b`,
-/// else `"Frame %s is not movable"`) and by the modifier-drag path — and **not read anywhere** on
-/// `0x7662c0`→`0x765320`→`0x7652b0`→`0x768430`. Q6 marks the no-gate reading VERIFIED and the
-/// observable claim INFERRED, because both FrameXML users happen to be `movable="true"`; a title
-/// region on a non-movable frame is the case that would tell them apart, and it drags here.
-///
-/// Returns whether a move actually started — `false` when one was already in flight, which is
-/// `0x7767e8`'s `root+0xcfc != 0` guard and the same refusal [`start_moving`] makes.
+/// Begin a title-region move, drag mode 2 (`0x7662c0` → `0x765320` → `0x7652b0`), with no movable
+/// check, since nothing on that path reads the bit. False when a move is already in flight.
 pub(crate) fn start_title_move(model: &mut Model, h: FrameHandle) -> bool {
     if model.moving.is_some() {
         return false;
@@ -488,9 +322,8 @@ pub(crate) fn start_title_move(model: &mut Model, h: FrameHandle) -> bool {
     true
 }
 
-/// Set the userPlaced bit the way the client's drag entry `0x7652b0` does, and dirty the layout
-/// cache **only on the transition** — a press inside a title region runs this on every click, and
-/// dirtying on each would put the saver's debounce back to work for a frame nothing moved.
+/// Set userPlaced as the drag entry `0x7652b0` does; the layout cache is dirtied only on the
+/// transition, since every title-region click runs this.
 fn set_user_placed(model: &mut Model, h: FrameHandle) {
     if let Some(f) = model.arena.frame_mut(h) {
         if !f.user_placed {
@@ -500,41 +333,16 @@ fn set_user_placed(model: &mut Model, h: FrameHandle) {
     }
 }
 
-/// A drag pump moved a frame; if that frame is **user-placed**, the layout cache owes the player's
-/// file a rewrite ([`crate::script::layout_cache`]).
-///
-/// The gate is the bit rather than "any drag" on purpose: `StartMoving`/`StartSizing` set the bit
-/// themselves, so the only frames this can miss are ones an addon moves with `SetPoint` — and those
-/// are the frames whose position the addon is saving itself, which is the reference's own division
-/// of labour (the engine's layout cache holds userPlaced frames; addons hold their own).
+/// A drag moved the frame: if it is user-placed, the layout cache owes its file a rewrite.
 fn mark_user_placed_change(model: &mut Model, h: FrameHandle) {
     if model.arena.frame(h).is_some_and(|f| f.user_placed) {
         model.user_placed_changed = true;
     }
 }
 
-/// Apply a frame's `SetMinResize`/`SetMaxResize` bounds to a proposed size, per axis.
-///
-/// The reference's predicate, transcribed (decision 1505; wow-re
-/// `system/ui/scratch/resize-bounds-and-button-fontstring.md` §3.5 — decoded from `geo_768710`'s
-/// **emitted** `jcc`, not from the FPU status mask, and deliberately not from the dead `geo_768550`
-/// copy whose operand order differs):
-///
-/// ```text
-/// if (min != 0.0) and (v < min):  v = min
-/// if (max != 0.0) and (v > max):  v = max
-/// ```
-///
-/// Three things a plausible implementation gets wrong, all VERIFIED:
-///
-///  · **There is NO floor when no bound is set.** benilla had a hardcoded `1.0` here (inherited
-///    from the drag pump before the bounds existed) and the client has nothing of the kind — a
-///    drag can carry an unbounded frame to zero and through it into negative extents.
-///  · **Only an exactly-`0.0` bound is the sentinel**, so a *negative* bound clamps normally.
-///  · **min first, then max — so when `min > max`, MAX wins.** Nothing in the client warns,
-///    rejects or reconciles the pair.
-///
-/// The returned residual per axis is what the caller rebates out of the drag delta ([`advance_size`]).
+/// Apply the `SetMinResize`/`SetMaxResize` bounds to a proposed size per axis, as `0x768710`
+/// does: only an exact 0.0 is unbounded, min applies before max so max wins a crossed pair, and
+/// with no bound there is no floor, so a size can go negative.
 fn clamp_resize(model: &Model, h: FrameHandle, w: f32, hgt: f32) -> (f32, f32) {
     let (min, max) = model
         .arena
@@ -551,13 +359,7 @@ fn clamp_resize(model: &Model, h: FrameHandle, w: f32, hgt: f32) -> (f32, f32) {
     (axis(w, min.0, max.0), axis(hgt, min.1, max.1))
 }
 
-/// Pump an in-flight `StartSizing`: move the gripped edges to the cursor, leave the others.
-///
-/// The mirror of [`advance_move`] — same sample-and-recentre, same dead-frame bail, same
-/// local-unit scaling (offsets are pre-scale, so a cursor delta divides by the frame's own scale on
-/// the way in). Where a move translates every anchor, a resize moves the gripped edges only: the
-/// width/height change, and the anchor offsets follow only for the edges that actually moved, which
-/// is what keeps the OPPOSITE edge planted.
+/// Pump an in-flight `StartSizing`: the gripped edges follow the cursor, the opposite ones stay.
 pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
     let Some(sz) = model.sizing else { return };
     if model.arena.frame(sz.frame).is_none() {
@@ -570,8 +372,6 @@ pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
     }
     let inv = 1.0 / eff_scale(model, sz.frame);
     let (dx, dy) = (dx * inv, dy * inv);
-    // Width grows when the RIGHT grip goes right, or the LEFT grip goes left. Height likewise with
-    // y-up: the TOP grip going up grows it, the BOTTOM grip going down grows it.
     let dw = if sz.right {
         dx
     } else if sz.left {
@@ -593,23 +393,11 @@ pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
     else {
         return;
     };
-    // The frame's own `SetMinResize`/`SetMaxResize` bounds — read before the mutable borrow, and
-    // the only path in the client that consults them at all (`clamp_resize`, and wow-re's §3.1
-    // reachability census behind it).
+    // The resize bounds are read only here, as only `0x76a660` reads them in the reference.
     let (new_w, new_h) = clamp_resize(model, sz.frame, w0 + dw, h0 + dh);
-    // **The rebate.** A saturated clamp is not a bare `max`/`min` in the reference: the residual
-    // it swallowed is subtracted back out of the drag delta before the delta reaches the anchors
-    // (`0x768770`/`0x7687a2` — `dx := dx ∓ residual·scale`). Without it the size pins at the bound
-    // while the anchor keeps sliding, so a window held past its minimum stops shrinking and starts
-    // *walking* across the screen. With it the moving edge lands exactly on the bound and stays.
-    //
-    // Both are already in LOCAL units here (`dx`/`dy` were divided by the effective scale above,
-    // and the anchor offsets they feed are pre-scale), so the rebate is a plain subtraction — the
-    // reference's `·layoutScale` is its own conversion back out of cursor units, not part of the
-    // rule. The sign follows the grip: a growing edge (`dw = +dx`) adds the residual, a shrinking
-    // one (`dw = -dx`) subtracts it, so the delta always agrees with the size the clamp allowed.
-    // An axis nobody gripped is left alone rather than rebated against a bound the frame was
-    // already outside of — that frame stays put until a drag touches its axis, which is §3.8.
+    // The rebate (`0x768770`/`0x7687a2`): the residual a clamp swallowed comes back out of the
+    // drag delta, so the moving edge stops at the bound instead of the window walking. The delta
+    // is already in local units, and an ungripped axis is not rebated.
     let rebate = |d: f32, want: f32, got: f32, grew: bool, gripped: bool| {
         if !gripped {
             return d;
@@ -629,15 +417,9 @@ pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
     input.width = new_w;
     input.height = new_h;
     let mut moved = input.width.to_bits() != w0.to_bits() || input.height.to_bits() != h0.to_bits();
-    // The planted edge: a frame anchored by its LEFT that is gripped on the LEFT has to move too,
-    // or the resize would push the right edge instead. Only the gripped axis shifts.
-    //
-    // **Which edges travel is OURS, and the byte carve does not settle it** — stated rather than
-    // quietly aligned. The reference collapses the frame to a single planted TOPLEFT anchor at
-    // `StartSizing` (`0x768430`), so *its* travelling edges are necessarily LEFT and TOP; we keep
-    // the authored anchor set intact and shift every anchor's offsets, which is a different model
-    // with a different answer. The rebate above is the part the carve does settle, and it applies
-    // either way.
+    // A LEFT or BOTTOM grip also shifts the anchors on its axis, so a frame anchored by that side
+    // keeps its opposite edge. The reference instead re-anchors the frame to one TOPLEFT point at
+    // `StartSizing` (`0x768430`).
     if !input.anchors.is_empty() && (sz.left || sz.bottom) {
         for a in &mut input.anchors {
             if sz.left {
@@ -649,31 +431,19 @@ pub(crate) fn advance_size(model: &mut Model, pos: (f32, f32)) {
         }
         moved |= (sz.left && dx != 0.0) || (sz.bottom && dy != 0.0);
     }
-    // The zero-delta return above is on the RAW cursor delta, which is not the same question: a
-    // single-axis grip dragged purely across its axis gives `dw == dh == 0`, and so does a grip
-    // held against a bound. Both used to bump the epoch and then hash all ~10k anchored regions to
-    // conclude nothing had moved — the castbar's bug class in miniature, for every frame of such a
-    // drag (decision 1385).
+    // A nonzero cursor delta can still move nothing (a grip dragged across its axis, or held at a
+    // bound), so the layout is touched only on a real change.
     if moved {
-        // Offsets only — a resize grip never repoints an anchor, so the frame names itself and the
-        // cached graph survives the drag (decision 1388). A drag is per-frame by nature: this is
-        // the difference between a smooth window resize and one that re-derives 13,656 nodes on
-        // every mouse-move.
+        // No anchor is retargeted, so only this node is touched.
         model.touch_layout_frame(sz.frame);
         mark_user_placed_change(model, sz.frame);
     }
     model.sizing = Some(FrameSizing { sample: pos, ..sz });
 }
 
-/// Pump an in-flight move to the cursor at `pos` — the engine half of `0x7655b0`, run from
-/// [`crate::script::UiScript::mouse_move`] beside [`crate::script::cursor::maybe_start_drag`] and,
-/// like it, BEFORE the hover-boundary early return (a frame dragged around underneath the cursor
-/// crosses no boundary at all, so a move parked behind that return would only advance when the
-/// cursor happened to leave the frame).
-///
-/// Applies `(pos − sample)` scaled into the frame's anchor offsets and re-centers the sample; a
-/// zero delta does nothing at all, and a frame that died mid-move ends the move rather than
-/// writing to a dead handle.
+/// Pump an in-flight move to the cursor at `pos` (`0x7655b0`). Called from
+/// [`crate::script::UiScript::mouse_move`] before its hover-boundary early return, since a frame
+/// dragged under the cursor crosses no boundary.
 pub(crate) fn advance_move(model: &mut Model, pos: (f32, f32)) {
     let Some(mv) = model.moving else { return };
     if model.arena.frame(mv.frame).is_none() {
@@ -684,23 +454,17 @@ pub(crate) fn advance_move(model: &mut Model, pos: (f32, f32)) {
     if dx == 0.0 && dy == 0.0 {
         return;
     }
-    // Offsets are LOCAL units — the resolver multiplies them by the frame's own layoutScale
-    // (`anchor_resolve_x`), so the cursor's screen delta divides by it on the way in, exactly the
-    // `dx/scale` of `geo_768710`'s case 4.
+    // Anchor offsets are in the frame's own units, so the screen delta divides by its scale, as
+    // `0x768710`'s case 4 does.
     let inv = 1.0 / eff_scale(model, mv.frame);
     let (dx, dy) = (dx * inv, dy * inv);
     if let Some(input) = model.layout_inputs.get_mut(&mv.frame) {
-        // Translating the whole set, not slot 0 — see the module doc. An anchorless frame is not
-        // resolvable and so is not on screen to drag; it simply does not move.
         if !input.anchors.is_empty() {
             for a in &mut input.anchors {
                 a.x_off += dx;
                 a.y_off += dy;
             }
-            // The one mutation path every layout setter shares — the tier-1 epoch, never the
-            // solver's arrays (see [`super::layout_methods`]'s mutate-only-on-change law; a zero
-            // delta returned above, so this write always moved something). Translating every
-            // anchor moves no TARGET, so the frame names itself (decision 1388).
+            // No target moves, so only this node is touched; a zero delta already returned above.
             model.touch_layout_frame(mv.frame);
             mark_user_placed_change(model, mv.frame);
         }
diff --git a/crates/benilla-ui/src/script/object/toplevel.rs b/crates/benilla-ui/src/script/object/toplevel.rs
index 8aec43bf..7d58fe3a 100644
--- a/crates/benilla-ui/src/script/object/toplevel.rs
+++ b/crates/benilla-ui/src/script/object/toplevel.rs
@@ -1,102 +1,18 @@
-//! Frame method-table cluster: the `toplevel` flag and the **raise law** — `SetToplevel`/
-//! `IsToplevel`, `Raise`/`Lower`, and the engine-side worker every raise trigger runs. Split out of
-//! [`super`] beside [`super::movable`], whose flag word this shares.
+//! Frame methods: the `toplevel` flag, `Raise` and `Lower`, and the raise every trigger runs.
 //!
-//! This is "bring the window I just opened to the front". 82 corpus addons declare `toplevel=` in
-//! XML and eleven call `SetToplevel` from Lua; our own shipped windows declare it on thirteen
-//! frames. Until this module it was parsed and thrown away with a warn-once, so a benilla dialog
-//! opened behind another one stayed behind it.
+//! The flag is bit `0x1` of `[frame+0xb4]`, set by `0x76a3c0` from XML (`0x7698ec`) or
+//! `SetToplevel` (`0x775440`), and setting it raises nothing. `CSimpleTop::Raise` (`0x7650f0`):
 //!
-//! ## The law (wow-re `system/ui/scratch/toplevel-raise.md`, §5 fan-out 2026-07-21 — VERIFIED)
+//! 1. Walks up `+0x9c` to the nearest toplevel self-or-ancestor; with none it does nothing.
+//! 2. With `force`, resolves the frame's layout and tests whether it is overlapped: a visible frame
+//!    of its stratum at its level or above, neither itself nor a descendant, meets its rect.
+//! 3. Only then compacts the stratum's levels, hidden frames included (`0x764eb0`), and sets its
+//!    level to the top plus one, moving same-stratum children by the same delta (`0x76a4f0`).
 //!
-//! The flag is **`[frame+0xb4]` bit `0x1`**, written by the same pure bit-setter `0x76a3c0` as
-//! `movable` (`0x100`) and `resizable` (`0x200`): `if (v) flags |= mask; else flags &= ~mask;`, no
-//! calls, no list touch. XML `toplevel` lands there at `0x7698ec`; Lua `SetToplevel 0x775440` at
-//! `0x7754d4`. **Setting the flag raises nothing** — it only marks the frame.
-//!
-//! The raise itself is `CSimpleTop::Raise(frame, force) 0x7650f0`, reached from
-//! `CSimpleFrame::Raise 0x76a5b0` = `this->root->Raise(this, force = 1)`:
-//!
-//! 1. **Resolve to the nearest TOPLEVEL self-or-ancestor** up `+0x9c` (`0x7650fb..0x765135`).
-//!    No toplevel in the chain ⇒ **total no-op**. So the gate lives in the worker, not the callers:
-//!    every trigger may hand it an arbitrary frame, and the frame that visibly moves may be an
-//!    *ancestor* of the one that was clicked or shown.
-//! 2. **`force != 0` ⇒ recompute the OVERLAPPED bit** (`0x76513e..0x765290`): resolve the frame's
-//!    pending layout, then scan its stratum bucket from **its own level upward** for a frame that is
-//!    not itself, is not one of its descendants (`is_descendant 0x767010`), and whose screen rect
-//!    intersects non-emptily. The answer is stored as `+0xb4` bit `0x10`.
-//! 3. **The raise, gated on that bit** (`0x7651ac..0x7651e7`): `level_compact 0x764eb0` squeezes the
-//!    free levels out of the stratum — over **every live frame of it, hidden included**
-//!    (`ui/scratch/level-compact-law.md`) — then `set_frame_level(bucket->count, propagate = 1)`.
-//!
-//! Three consequences the tests pin: a raise is **`level := top occupied level + 1`**, not a list
-//! reshuffle; it is **occlusion-gated** — `Raise()` on a frame that overlaps nothing changes nothing
-//! at all; and it **never changes the stratum** (`0x7650f0` never writes `+0xc0`), so a LOW frame can
-//! never be lifted over a MEDIUM one by any number of raises. `propagate = 1` shifts same-strata
-//! children by the **same delta** (`0x76a4f0` @`0x76a58a`–`0x76a595`), so the raised subtree keeps
-//! its internal order; cross-strata children are untouched.
-//!
-//! ## How that maps onto benilla's order model, clause by clause
-//!
-//! Our draw order is a derived total order over the arena ([`crate::order`]), not a materialized
-//! array of per-stratum buckets of intrusive level lists. Every clause above still lands, but two
-//! of them land as *derivations* and one is deliberately not stored:
-//!
-//! - **"the stratum bucket"** = the effective-visible frames whose `strata` matches. Bucket
-//!   membership is exactly the client's link-gate: a frame is in a level list only while
-//!   effectively visible, which is the same condition [`crate::widget::WidgetArena::resequence_to_tail`]
-//!   already mirrors for the link stamp.
-//! - **"raise within the strata"** = a **frame-level bump**, and it is the honest mapping rather
-//!   than a re-stamp: the binary writes `+0xc4` through `set_frame_level 0x76a4f0`, and level is the
-//!   term *above* the link stamp in our key, so a bump lifts the frame over every same-strata frame
-//!   regardless of when each was last shown. The arithmetic is pinned in
-//!   `tests/toplevel.rs::a_raise_is_top_occupied_level_plus_one_after_compaction`.
-//! - **`level_compact`** is [`crate::widget::WidgetArena::compact_levels`] — an order-preserving
-//!   renumber of **every frame** in one stratum, hidden ones included: `0x764eb0` walks the client's
-//!   master frame list filtering on strata and level alone, and never reads `+0xd4`
-//!   (`ui/scratch/level-compact-law.md`, decision 2104). It changes no draw order by itself; it is
-//!   what keeps `level := max + 1` from ratcheting upward for the length of a session. Renumbering
-//!   only the *bucket* (the visible half) is the one shape it may not have: the raise's `propagate`
-//!   delta is computed in the new numbering and applied to levels that are still in the old one, so
-//!   a squeeze taken out of a visible child and not out of its hidden sibling inverts a pair that
-//!   `parent.level + 1` made equal — see that method's own doc for the window it broke, and for the
-//!   two places ours is deliberately simpler than the bytes.
-//! - **The OVERLAPPED bit is computed, never stored** — and that is *exact*, not a shortcut. The bit
-//!   is written only by `0x7650f0` and the per-tick pass `0x7657d0`, and read only by `0x7650f0`,
-//!   which with `force = 1` recomputes it immediately before reading it. The stored value is
-//!   therefore observable **only** through the one `force = 0` call site, `0x764a20`
-//!   (bucket-invalidate), which rides an already-computed bit. benilla has no bucket-invalidate
-//!   call — every trigger we have is a `force = 1` one — so the per-tick maintenance `0x7657d0`
-//!   would be state nothing could read. A local `bool` per raise is bit-for-bit what `force = 1`
-//!   does. **If a `force = 0` trigger is ever built, the bit has to become a field and `0x7657d0` a
-//!   per-tick pass; there is no other clause of this law that is unmodelled.**
-//!
-//! ## The screen rects the gate reads
-//!
-//! Step 2 needs rects, which live on [`Model::resolved`], not on the arena. `0x7650f0` starts by
-//! resolving the frame's *own* pending layout (`0x76513e`: `if (T->+0x60 & 1) …0x7680e0`) and then
-//! reads every other frame's cached rect as-is; [`raise`] does the same thing with the one resolve
-//! we have — [`crate::script::UiScript::resolve_layout`], whose epoch gate makes it a `u64` compare
-//! on the overwhelmingly common quiet call (showing a frame writes no layout input, so a Show-driven
-//! raise never pays a solve unless the caller moved something in the same tick). Our solve covers
-//! hidden frames too, so a frame being shown for the first time already has a rect to test. A frame
-//! with **no** resolved rect (anchorless, so not on screen) overlaps nothing and raises nothing.
-//!
-//! ## Triggers — the census, and which ones benilla wires
-//!
-//! wow-re's complete rel32 + absolute-dword census finds six call sites. Ours:
-//!
-//! | site | what it is | benilla |
-//! |---|---|---|
-//! | `0x775b0a` (Lua `Frame:Raise()`) | the explicit script call | [`install`] |
-//! | `0x76aeec` in `effective_visible_show 0x76ae10` | **the Show trigger** | [`raise_on_show`], run from [`crate::script::event::fire_visibility_changes`] |
-//! | `0x7652d7` in begin-move `0x7652b0` | drag start | [`super::movable`]'s `start_moving` |
-//! | `0x766392` in the mouse-down handler `0x7662c0` | **the click trigger** | [`crate::script::UiScript::mouse_button`]'s down arm, first thing — capture-else-hover, unguarded, ahead of the title-region swallow |
-//! | `0x764a4c` (`force = 0`) | re-applies an already-computed bit `0x10` | no counterpart (see the OVERLAPPED note above) |
-//! | `0x7650d6` | dead — zero references binary-wide | — |
-//!
-//! **`Frame:Lower()` is inert in build 5875** and inert here: `0x775b20` → `0x76a5c0` → `0x7652a0`,
-//! which is `xor eax,eax; ret 4` — a verified no-op stub whose frame argument is never read.
+//! The stratum never changes. The overlapped bit is recomputed per raise, never stored: only the
+//! `force = 0` trigger (`0x764a4c`) reads a stored bit, and it is not wired, so neither is the
+//! per-tick pass that keeps it (`0x7657d0`). The wired triggers are `Raise` (`0x775b0a`), Show
+//! (`0x76aeec`), drag start (`0x7652d7`) and mouse-down (`0x766392`).
 
 use mlua::{Lua, Table, Value};
 
@@ -106,12 +22,9 @@ use crate::widget::FrameHandle;
 
 use super::frame_handle_of;
 
-/// Populate `m`'s toplevel/raise methods (see the module doc).
+/// Populate `m`'s toplevel and raise methods.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // SetToplevel(flag) / IsToplevel() — flag word bit 0x1 (`0x775440`/`0x76a3c0`). A pure flag
-    // write; the raise is entirely separate. The argument is an **optional** boolean defaulting to
-    // TRUE (`0x775440` marshals it that way) — unlike `SetMovable`'s, so this takes a `Value` and
-    // reads absence as true rather than leaning on mlua's nil-is-false bool conversion.
+    // SetToplevel's argument is optional and defaults to true (`0x775440`), unlike `SetMovable`'s.
     m.set(
         "SetToplevel",
         lua.create_function(|lua, (this, flag): (Table, Option<Value>)| {
@@ -135,10 +48,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(crate::script::binding_abi::flag(model.arena.is_toplevel(h)))
         })?,
     )?;
-    // Raise() — `0x775a50` → `0x76a5b0` → `0x7650f0(this, force = 1)`. Note it is legal on any
-    // frame: the worker substitutes the nearest toplevel self-or-ancestor and does nothing at all
-    // when there is none, so an addon calling it on a plain frame gets the reference's silence, not
-    // an error.
+    // Raise() (`0x775a50` → `0x76a5b0` → `0x7650f0`, `force = 1`): legal on any frame, and silent
+    // when no toplevel self-or-ancestor exists.
     m.set(
         "Raise",
         lua.create_function(|lua, this: Table| {
@@ -148,30 +59,22 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // Lower() — `0x775b20` → `0x76a5c0` → `0x7652a0` = `xor eax,eax; ret 4`. A VERIFIED no-op stub
-    // in build 5875 (the frame argument is never read, and the call is direct, so this is
-    // unconditionally what runs). Present because absence is a different behaviour — a nil-call
-    // error where the reference silently does nothing.
+    // Lower() does nothing in the reference: `0x775b20` → `0x76a5c0` → `0x7652a0`, which is
+    // `xor eax,eax; ret 4`.
     m.set("Lower", lua.create_function(|_, _this: Table| Ok(()))?)?;
     Ok(())
 }
 
-/// `CSimpleTop::Raise(frame, force = 1)` — `0x7650f0`, the worker every trigger runs. Returns
-/// whether a toplevel self-or-ancestor was found at all (the binary's `bool` return); a `true` with
-/// nothing moved is the occlusion gate declining, which is the common and correct case.
-///
-/// The three numbered steps of the module doc, in order.
+/// `CSimpleTop::Raise(frame, force = 1)` (`0x7650f0`), the module doc's three steps; true, as in
+/// the reference, when a toplevel self-or-ancestor was found, whether or not it moved.
 pub(in crate::script) fn raise(model: &mut Model, frame: FrameHandle) -> bool {
-    // 1. The nearest TOPLEVEL self-or-ancestor. None ⇒ total no-op.
+    // 1. The nearest toplevel self-or-ancestor, else nothing.
     let Some(t) = nearest_toplevel(model, frame) else {
         return false;
     };
-    // 2. force = 1: resolve the pending layout, then recompute OVERLAPPED (a local — see the
-    //    module doc's note on why storing the bit would be unobservable state).
-    //    Any `OnSizeChanged` that resolve produces is QUEUED, not fired: this path holds a bare
-    //    `&mut Model` (no Lua reachable from a raise), so the host's next `UiScript::resolve` —
-    //    which runs every frame — drains it one tick later. The alternative, threading a `&Lua`
-    //    through the raise, would put a Lua handler in the middle of a strata compaction.
+    // 2. Resolve the pending layout (`0x76513e`), then test for overlap. Deviation: an
+    //    `OnSizeChanged` that resolve produces fires at the next `UiScript::resolve`, because a
+    //    Lua handler must not run in the middle of a level compaction.
     UiScript::resolve_layout(model);
     if !overlapped(model, t) {
         return true;
@@ -185,25 +88,17 @@ pub(in crate::script) fn raise(model: &mut Model, frame: FrameHandle) -> bool {
     true
 }
 
-/// The Show trigger — `effective_visible_show 0x76ae10` @`0x76aee0`: on a genuine `+0xd4`
-/// false→true transition, **test the frame's own toplevel bit** and raise if it is set.
-///
-/// The own-bit test is load-bearing and is why this is not just [`raise`]: the worker would walk up
-/// to a toplevel *ancestor*, so calling it unconditionally would lift a whole window every time any
-/// non-toplevel child of it became visible. The binary tests `[esi+0xb4], 0x1` first, and only then
-/// calls `0x76a5b0`.
+/// The Show trigger (`0x76ae10` at `0x76aee0`): on becoming visible, raise only if the frame's own
+/// toplevel bit is set, so showing a child never lifts its window.
 pub(in crate::script) fn raise_on_show(model: &mut Model, h: FrameHandle) {
     if model.arena.is_toplevel(h) {
         raise(model, h);
     }
 }
 
-/// Step 1 — walk `+0x9c` from the frame up, returning the first node with the toplevel bit
-/// (`0x7650fb..0x765135`). Loop-guarded like the arena's own ancestry walk; a well-formed tree
-/// never loops.
+/// Step 1: the first frame up `+0x9c` with the toplevel bit (`0x7650fb..0x765135`).
 fn nearest_toplevel(model: &Model, frame: FrameHandle) -> Option<FrameHandle> {
-    // The bound is read once, not per hop: a chain longer than the frame count is a cycle, which
-    // `set_parent`'s own guard already makes unreachable — this is defence, not a hot path.
+    // A chain longer than the frame count is a cycle, which `SetParent` already refuses.
     let bound = model.arena.iter_frames().count();
     let mut cur = Some(frame);
     let mut guard = 0usize;
@@ -221,24 +116,15 @@ fn nearest_toplevel(model: &Model, frame: FrameHandle) -> Option<FrameHandle> {
     None
 }
 
-/// Step 2's predicate — the scan `0x7650f0` runs inline and `0x765a90` runs standalone: within `t`'s
-/// own stratum bucket, from **`t`'s own level upward**, is there a frame that is not `t`, is not one
-/// of `t`'s descendants, and whose screen rect meets `t`'s?
-///
-/// Every clause matters, and each is a separate test:
-/// - **`level >= t.level` only.** A toplevel frame that overlaps solely something *below* it is
-///   already on top of it, so there is nothing to raise over.
-/// - **`is_descendant 0x767010` exclusion.** A window overlaps its own children by construction;
-///   without this every toplevel frame with content would raise on every trigger.
-/// - **non-empty intersection.** Frames that merely share an edge do not overlap — the intersection
-///   has to have positive width *and* height, so a zero-area touch is not an occlusion.
+/// Step 2 (`0x7650f0` inline, `0x765a90` standalone): a visible frame of `t`'s stratum at `t`'s
+/// level or above, neither `t` nor its descendant (`0x767010`), whose rect meets `t`'s with area.
 fn overlapped(model: &Model, t: FrameHandle) -> bool {
     let Some(tf) = model.arena.frame(t) else {
         return false;
     };
     let (strata, level) = (tf.strata, tf.level);
     let Some(t_rect) = model.resolved.get(&t).copied() else {
-        // No resolved rect ⇒ the frame is not on screen ⇒ it occludes nothing.
+        // No resolved rect: not on screen, so nothing overlaps it.
         return false;
     };
     model.arena.iter_frames().any(|(h, f)| {
@@ -254,8 +140,8 @@ fn overlapped(model: &Model, t: FrameHandle) -> bool {
     })
 }
 
-/// `rect_intersect_nonempty` (`0x768320` / `0x766c70` / `0x766bc0`) — reusing the one axis-aligned
-/// intersection this crate already has and asking whether what comes out has area.
+/// Whether two rects intersect with area: the reference reads both (`0x768320`), intersects them
+/// (`0x766c70`) and tests the result (`0x766bc0`).
 fn rects_overlap(a: Rect, b: Rect) -> bool {
     let i = crate::script::clip::intersect_rect(a, b);
     i.width() > 0.0 && i.height() > 0.0
diff --git a/crates/benilla-ui/src/script/party.rs b/crates/benilla-ui/src/script/party.rs
index 87a52758..3c3200de 100644
--- a/crates/benilla-ui/src/script/party.rs
+++ b/crates/benilla-ui/src/script/party.rs
@@ -1,258 +1,167 @@
-//! The party/raid **Era API surface** (decision 0434 §2, phase 2) — the engine-free seam mirroring
-//! [`super::unit`]: the app pushes a roster **snapshot** ([`UiScript::set_party`]) built from its own
-//! `GroupState` wire mirror, and the `GetNumPartyMembers`/`GetPartyLeaderIndex`/`GetLootMethod`/…
-//! globals here read that plain data. The invite/uninvite/promote/loot-config calls are the outbound
-//! half: they queue a [`PartyRequest`] the app drains ([`UiScript::take_party_requests`]) and turns
-//! into the matching `CMSG_GROUP_*`/`CMSG_LOOT_METHOD` send — no ECS/net reach from the engine
-//! (decision 0068 §3), exactly [`super::unit`]'s split.
+//! The party and raid bindings. The app pushes a roster snapshot ([`UiScript::set_party`]) that
+//! the getters read; the verbs queue a [`PartyRequest`] the app drains
+//! ([`UiScript::take_party_requests`]) into the send. Per-member game state is the unit snapshot
+//! under `party1`..`party4` ([`super::unit::UnitState`]).
 //!
-//! Per-member game state (health/mana/level/reaction/…) does **not** live here — it rides the
-//! existing per-unit snapshots under the `"party1"`..`"party4"` tokens (decision 0434 §3), the same
-//! feed `"player"`/`"target"` use ([`super::unit::UnitState`]). This module owns only the
-//! roster-level facts a unit snapshot can't carry: how many members, who leads, the loot
-//! configuration. `PartyState::default()` is "not in a group" — every getter then answers the
-//! solo-player shape a fresh client reports (`GetNumPartyMembers()` `0`, `GetLootMethod()`
-//! `("group", nil)`, …).
-//!
-//! The **raid roster** ([`PartyState::raid`]) is the same shape one level out: the app pushes the
-//! whole array — the player included, which is why `UnitInRaid("player")` needs no token special
-//! case the way `UnitInParty` does — and `GetNumRaidMembers`/`GetRaidRosterInfo`/`UnitInRaid` read
-//! it. It is deliberately ONE list rather than a count beside a list: the reference indexes the
-//! array `0xb712a8` bounded by the count `0xb713e0`, and two of the three bindings walk exactly
-//! that pair, so a client whose count and array can disagree hands an addon looping
-//! `for i = 1, GetNumRaidMembers()` a miss tuple it will then index. The per-member grid/UI is
-//! the RaidFrame (decision 1549), which reads exactly this array.
-//!
-//! The **raid management verbs** (decision 1549) are the outbound half again, and they address
-//! members three different ways because the reference's own bindings do: by **raid index**
-//! (`SetRaidSubgroup`, `SwapRaidSubgroup`, `UninviteFromRaid` — the RaidFrame has the index in
-//! hand), by **name** (`PromoteByName`, `PromoteToAssistant`, `DemoteAssistant` — UnitPopup
-//! carries a name, never an index), and by **nothing at all** (`ConvertToRaid`, `DoReadyCheck`,
-//! `RequestRaidInfo`). Resolving index/name to whatever the wire wants is the app's job at the
-//! drain, exactly as `InviteToParty`'s token resolution already is: this side stays plain data.
-//!
-//! The **saved-instance list** ([`SavedInstanceInfo`]) is a second app-pushed snapshot, separate
-//! from [`PartyState`] because it arrives on its own packet (`SMSG_RAID_INSTANCE_INFO`) and
-//! outlives every roster change — folding it into the roster push would clear it every time the
-//! group moved.
+//! The raid roster ([`PartyState::raid`]) is one list, the player included, because the
+//! reference's count (`0xb713e0`) bounds the very array `GetRaidRosterInfo` indexes (`0xb712a8`).
+//! The saved-instance list ([`SavedInstanceInfo`]) is a separate push, as a roster push replaces
+//! [`PartyState`] whole.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::number_arg;
 use super::Model;
 
-/// One roster member's engine-owned facts (decision 0434 §2/§3) — deliberately thin: everything else
-/// (health, class, reaction, …) is the unit snapshot under its `"partyN"` token.
+/// One party member; everything else about them is the unit snapshot under their `partyN` token.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PartyMemberInfo {
     pub name: String,
-    /// The member's GUID — the identity `UnitInParty` matches arbitrary tokens (the target)
-    /// against (decision 0434 §5's popup menu pick). `0` = unknown, never matches.
+    /// The identity `UnitInParty` matches any token against; `0` never matches.
     pub guid: u64,
 }
 
-/// One saved raid lockout — `GetSavedInstanceInfo`'s three returns (decision 1549). Pushed whole
-/// by the app ([`UiScript::set_saved_instances`]) from `SMSG_RAID_INSTANCE_INFO`, with the map
-/// **name** already resolved: the wire carries a `Map.dbc` id and the DBC is the app's to read.
+/// One saved raid lockout, `GetSavedInstanceInfo`'s three returns, from `SMSG_RAID_INSTANCE_INFO`
+/// with the `Map.dbc` name resolved by the app ([`UiScript::set_saved_instances`]).
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct SavedInstanceInfo {
-    /// The instance's display name (`Map.dbc`'s own), e.g. `"Molten Core"`.
+    /// The `Map.dbc` name, e.g. `"Molten Core"`.
     pub name: String,
-    /// The instance id — what the panel prints in its ID column.
     pub instance: u32,
-    /// Seconds remaining until the lockout resets; the panel runs it through `SecondsToTime`.
+    /// Seconds until the lockout resets.
     pub reset: u32,
 }
 
-/// One **raid roster** row — `GetRaidRosterInfo`'s nine returns, as the app resolved them
-/// (wow-re `ui/scratch/raid-roster-bindings.md` §2, §5-cross-checked with orchestrator
-/// byte-arbitration). Field order is the push order of the reference's success tuple.
-///
-/// The row is the *record*, not the answer: two of the nine are computed at the binding
-/// ([`Self::subgroup`]'s 1-based exposure, [`Self::zone`]'s offline substitution), because both
-/// adjustments live in the binding's own bytes and doing them at the feed would put a Lua-facing
-/// convention in the app.
+/// One raid roster row, `GetRaidRosterInfo`'s nine returns in push order (`0x4bb560`). The
+/// binding, not the row, applies the subgroup's +1 and the offline zone.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct RaidMemberInfo {
-    /// Return 1 — the member's name, from the guid-keyed name cache (`0x4bb5ee`).
-    ///
-    /// **Empty means "not cached yet", and that is not a cosmetic difference**: the reference
-    /// sends a cache miss to the *same* arm an out-of-range index takes (`0x4bb5f8 je 0x4bb7b9`),
-    /// so an occupied slot whose name has not arrived is indistinguishable from no slot at all.
-    /// Reproduced — [`raid_roster_info`] answers the miss tuple for an empty name.
+    /// Return 1, from the name cache (`0x4bb5ee`). Empty means not cached, which the reference
+    /// answers with the miss tuple, as for an empty slot (`0x4bb5f8 je 0x4bb7b9`).
     pub name: String,
-    /// The member's GUID — what `UnitInRaid` matches an arbitrary token against. `0` = unknown,
-    /// never matches (the reference's membership helper `0x4baee0` short-circuits GUID `0:0` to
-    /// false at its entry).
+    /// The identity `UnitInRaid` matches a token against; `0` never matches, as the reference's
+    /// membership test rejects a zero guid (`0x4baee0`).
     pub guid: u64,
-    /// Return 2 — the rank, **exposed exactly as stored** (`0x4bb607 fild [edi+0xc]`, no
-    /// adjustment). wow-re could not derive the numeric convention from the binding, and does not
-    /// claim one; the corpus does, consistently: `ChatLog.lua:351-353` prints `@` for `2` and `*`
-    /// for `1`, i.e. **0 member · 1 assistant · 2 leader**, which is what the app fills.
+    /// Return 2, exposed as stored (`0x4bb607 fild [edi+0xc]`): 0 member, 1 assistant, 2 leader,
+    /// the convention addons read (`ChatLog.lua:351-353`).
     pub rank: u32,
-    /// Return 3 — the subgroup **as stored, 0-based**. The binding exposes `subgroup + 1`
-    /// (`0x4bb61a inc eax`, a VERIFIED adjustment); keeping the record 0-based means the wire's
-    /// own value (`GroupMemberEntry::flags` bits 0-2) lands here unconverted and the +1 has one
-    /// home.
+    /// Return 3, stored 0-based as the wire's `GroupMemberEntry::flags` bits 0-2 carry it; the
+    /// binding exposes it 1-based (`0x4bb61a inc eax`).
     pub subgroup: u32,
-    /// Return 4 — the member's level. `0` when neither a streamed object nor a stats packet has
-    /// carried one (the reference's own third arm pushes `0` there too).
+    /// Return 4, `0` until an object or a stats packet carries it, as in the reference's third arm.
     pub level: u32,
-    /// Return 5 — the **localized** class name ("Warrior"), `None` → `nil`.
+    /// Return 5, the localized class name.
     pub class: Option<String>,
-    /// Return 6 — the class file/token ("WARRIOR"), the one non-localized string in the tuple.
+    /// Return 6, the class token (`"WARRIOR"`), the one unlocalized string.
     pub class_file: Option<String>,
-    /// Return 7 — the member's zone name while [`Self::online`]; `None` → `nil`. **When offline
-    /// this field is not read at all**: the reference's third arm pushes the localized global
-    /// `PLAYER_OFFLINE` in the zone slot rather than `nil`, and the binding does that itself.
+    /// Return 7 while [`Self::online`]; offline, the binding pushes the `PLAYER_OFFLINE` global
+    /// instead and never reads this.
     pub zone: Option<String>,
-    /// Return 8 — connected. Also the switch for return 7's two arms, because it is in the
-    /// reference: return 8 is `1` on exactly the two arms that produced a real zone and `nil` on
-    /// the `PLAYER_OFFLINE` one.
+    /// Return 8, which also picks return 7's offline arm.
     pub online: bool,
-    /// Return 9 — **deliberately unlabelled.** wow-re verified the mechanism and refused the
-    /// name: a streamed member answers `1` iff `[obj+0x110 +0x40] <= 0` (UNIT_FIELD_HEALTH by the
-    /// descriptor line this repo already anchors), and an unstreamed one iff the roster record's
-    /// `[+0x18]` carries **both** bits `0x4` and `0x1`. Two independent workers guessed "isDead"
-    /// positionally and the note declined to adopt it (§5 Open).
-    ///
-    /// Three things corroborate that guess without settling it, recorded here so whoever settles
-    /// it starts ahead: the whole corpus destructures position 9 as `isDead`
-    /// (`ChatLog.lua:347`, `CT_RaidAssist/CT_RAOptions.lua:89`, `oRA2/Leader/Ready.lua:241`);
-    /// health ≤ 0 is this client's own dead test; and our wire's status byte —
-    /// `benilla_protocol::messages::member_status`, from vmangos `Group.cpp:45-63` — spells
-    /// `ONLINE = 0x01` and `DEAD = 0x04`, which is *exactly* the bit pair the second arm tests.
-    /// The app fills this from that pair, so we reproduce the mechanism whatever it turns out to
-    /// be called.
+    /// Return 9, unnamed: `1` for a streamed member whose health (`[obj+0x110 +0x40]`) is 0 or
+    /// below, or an unstreamed one whose roster status (`[+0x18]`) has both `0x1` and `0x4`,
+    /// vmangos's `ONLINE` and `DEAD`, from which the app fills it. Addons read it as `isDead`.
     pub ninth: bool,
 }
 
-/// The party/raid roster snapshot, pushed whole by the app each frame it changes
-/// ([`UiScript::set_party`]) — the `GroupState` merged view's roster-level facts (decision 0434 §2).
-/// `PartyState::default()` = not in a group.
+/// The party and raid roster snapshot the app pushes whole when it changes
+/// ([`UiScript::set_party`]); the default is ungrouped.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PartyState {
-    /// The other party members, `"party1"`..`"party4"` order (the recipient never appears in its own
-    /// list, matching `SMSG_GROUP_LIST`); empty = not in a group. Never more than 4 — in a raid
-    /// this is our own subgroup's slice and the whole roster is [`Self::raid`].
+    /// The other party members in `party1`..`party4` order, empty when ungrouped. The player is
+    /// never in it, as in `SMSG_GROUP_LIST`; in a raid it is our own subgroup's slice.
     pub members: Vec<PartyMemberInfo>,
-    /// The party leader, on the Lua `GetPartyLeaderIndex` scale: `0` the player leads, `1..=4` that
-    /// `members` slot (1-based) leads.
+    /// `GetPartyLeaderIndex`: `0` the player, `1..=4` that `members` slot.
     pub leader_index: u32,
-    /// **The cached group-leader GUID** — the reference's `[0xbc75f8]:[0xbc75fc]` pair, `0` when
-    /// ungrouped. Fed straight from the wire's leader GUID, not derived from
-    /// [`Self::leader_index`].
-    ///
-    /// It exists because `UnitIsPartyLeader`'s second leg is a GUID compare and an index cannot
-    /// stand in for it: the leg has to answer for a member whose object the client does **not**
-    /// hold — an out-of-range `party3`, any `raidN` — where there is no descriptor to read the
-    /// flag from, and it has to answer for the *resolved token's* GUID rather than for a slot.
-    ///
-    /// **Compared WITHOUT a zero guard**, which is the load-bearing part and reads like a bug:
-    /// `IsPartyLeader 0x4e9130` short-circuits on a `0:0` cached leader, and
-    /// `UnitIsPartyLeader 0x516210` does not. So an unresolvable-but-non-raising argument (none,
-    /// `nil`, `""`, `"target"` with no target) resolves to `0:0`, matches the zeroed leader, and
-    /// the reference answers **`1` while solo**. A client that answers `nil` there is not
-    /// reproducing 1.12 (wow-re `ui/scratch/party-leader-and-nameplate-verbs.md`).
+    /// The cached group-leader guid (the reference's `[0xbc75f8]:[0xbc75fc]`), `0` when
+    /// ungrouped, fed from the wire rather than derived from [`Self::leader_index`].
+    /// `UnitIsPartyLeader` (`0x516210`) compares a resolved token's guid with it and, unlike
+    /// `IsPartyLeader` (`0x4e9130`), has no zero guard, so an unresolvable token answers `1` while
+    /// solo.
     pub leader_guid: u64,
-    /// **The active player's own GUID** — the reference's `0x468550` read (`[0xb41414]+0xc0`),
-    /// `0` out of world. Fed by the app beside the leader; the pair is the leader gate the
-    /// ready-check timeout runs on (`CheckReadyCheckTime`, decision 1989): the reference compares
-    /// the two guids and nothing else, so a solo player (leader `0`, own non-zero) never matches.
+    /// The player's own guid (`0x468550`, `[0xb41414]+0xc0`), `0` out of world. With
+    /// [`Self::leader_guid`] it is the ready-check timeout's leader gate, a bare guid compare, so a
+    /// solo player never matches.
     pub own_guid: u64,
-    /// The **whole raid roster**, `GetRaidRosterInfo`'s 1-based array — empty outside a raid,
-    /// and **including the player** (the reference's array does; it is why `UnitInRaid("player")`
-    /// answers `1` in a raid and why this list is not `members`'s recipient-excluded shape).
-    /// `GetNumRaidMembers()` is its length: one list, no count beside it (module doc).
+    /// The whole raid roster, 1-based for `GetRaidRosterInfo`, empty outside a raid. It includes
+    /// the player, as the reference's array does, so `UnitInRaid("player")` answers `1`;
+    /// `GetNumRaidMembers()` is its length.
     pub raid: Vec<RaidMemberInfo>,
-    /// `GetLootMethod`'s method string: `"freeforall"` | `"roundrobin"` | `"master"` | `"group"` |
-    /// `"needbeforegreed"`. `Default::default()` is `""` — the *native* reports it as `"group"` (the
-    /// live shape for a solo/fresh player) when empty; the app is expected to always push a real
-    /// method once grouped.
+    /// `GetLootMethod`'s method: `"freeforall"`, `"roundrobin"`, `"master"`, `"group"` or
+    /// `"needbeforegreed"`. Empty, the default, reads as `"freeforall"`, the reference's answer
+    /// before any group.
     pub loot_method: String,
-    /// The master looter, as a party index (`0` the player, `1..=4` that `members` slot) — the loot
-    /// method's second return, `masterlooterPartyID`. `None` = no master looter (any method but
-    /// `"master"`, or a master-loot group with none assigned yet).
+    /// The master looter as a party index (`0` the player, `1..=4` a `members` slot),
+    /// `GetLootMethod`'s second return.
     pub master_looter: Option<u32>,
-    /// `GetLootThreshold`'s quality floor (`2..=4`) below which non-leader loot isn't round-robin/
-    /// master gated. `0` (the default) is fine while ungrouped — the getter has nothing to floor.
+    /// `GetLootThreshold`'s item quality, `2..=4` once grouped.
     pub loot_threshold: u32,
 }
 
-/// Outbound party/loot intents queued by the Era API's action calls, drained by the app
-/// ([`UiScript::take_party_requests`]) into the matching `CMSG_*` send. Plain data — no mlua/ECS
-/// types, [`super::unit::UnitState`]'s `TargetUnit` seam's twin.
+/// Outbound party and raid intents, drained by the app ([`UiScript::take_party_requests`]) into
+/// the matching send.
 #[derive(Clone, Debug, PartialEq)]
 pub enum PartyRequest {
-    /// `AcceptGroup()` — accept the pending invite.
+    /// `AcceptGroup()`.
     Accept,
-    /// `DeclineGroup()` — decline the pending invite.
+    /// `DeclineGroup()`.
     Decline,
-    /// `LeaveParty()` — leave the current group (no confirmation popup, decision 0434 §4).
+    /// `LeaveParty()`.
     Leave,
-    /// `InviteByName(name)` — invite by character name.
+    /// `InviteByName(name)`.
     InviteName(String),
-    /// `InviteToParty(unit)` — invite by unit TOKEN (e.g. `"target"`); the app resolves it to a name.
+    /// `InviteToParty(unit)`, by unit token; the app resolves it to a name.
     InviteUnit(String),
-    /// `UninviteFromParty(unit)` — kick a roster member, addressed by unit token (e.g. `"party2"`).
+    /// `UninviteFromParty(unit)`, by unit token.
     UninviteUnit(String),
-    /// `PromoteToPartyLeader(unit)` — hand leadership to a roster member, by unit token.
+    /// `PromoteToPartyLeader(unit)`, by unit token.
     PromoteUnit(String),
-    /// `SetLootMethod(method[, masterName])` — the master-looter argument is a character NAME (the
-    /// reference's own shape); the app resolves it to a roster member for the send.
+    /// `SetLootMethod(method[, masterName][, threshold])`; the app resolves the master looter's
+    /// name to a roster member.
     LootMethod {
         method: String,
         master_name: Option<String>,
-        /// `SetLootMethod`'s optional THIRD argument. The binding reads it whatever the method is
-        /// (`0x4e92a0`, presence-checked via `0x6f34d0`), unlike the master-looter argument, which
-        /// it reads only for `"master"` (decision 1675).
+        /// The reference reads it for every method (`0x4e92a0`, presence-checked by `0x6f34d0`),
+        /// the master looter's name only for `"master"`.
         threshold: Option<u32>,
     },
-    /// `SetLootThreshold(n)` — the new quality floor.
+    /// `SetLootThreshold(n)`.
     LootThreshold(u32),
-    /// `SetRaidTarget(unit, index)` — mark (1..=8) or clear (0) the raid-target icon on a
-    /// unit, addressed by token; the app resolves the token to a guid for the
-    /// `MSG_RAID_TARGET_UPDATE` send (decision 0434 §5's submenu, §6's board law).
+    /// `SetRaidTarget(unit, index)`: icon 1 to 8, or 0 to clear; the app resolves the token to a
+    /// guid for `MSG_RAID_TARGET_UPDATE`.
     SetRaidTarget { unit: String, index: u8 },
-    // ── The raid-management verbs (decision 1549's RaidFrame) ───────────────────────────────
-    /// `ConvertToRaid()` — the Raid tab's own button (`CMSG_GROUP_RAID_CONVERT`, leader only).
+    // ── The raid-management verbs ───────────────────────────────────────────────────────────
+    /// `ConvertToRaid()`, leader only (`CMSG_GROUP_RAID_CONVERT`).
     ConvertToRaid,
-    /// `SetRaidSubgroup(index, group)` — move raid row `index` (1-based) into subgroup `group`
-    /// (1-based). The wire (`CMSG_GROUP_CHANGE_SUB_GROUP`) takes a NAME and a 0-based subgroup;
-    /// resolving both is the app's, because only it holds the roster the index means.
+    /// `SetRaidSubgroup(index, group)`, both 1-based. The wire (`CMSG_GROUP_CHANGE_SUB_GROUP`)
+    /// takes a name and a 0-based subgroup, which the app resolves.
     SetSubgroup { index: u32, group: u32 },
-    /// `SwapRaidSubgroup(index, other)` — trade two raid rows' subgroups
-    /// (`CMSG_GROUP_SWAP_SUB_GROUP`, two names on the wire). The drag's "dropped on an occupied
-    /// slot" arm; [`Self::SetSubgroup`] is its "dropped on an empty one".
+    /// `SwapRaidSubgroup(index, other)`: trade two raid rows' subgroups
+    /// (`CMSG_GROUP_SWAP_SUB_GROUP`, two names on the wire).
     SwapSubgroup { index: u32, other: u32 },
-    /// `PromoteByName(name)` — hand leadership over, addressed by name rather than by token
-    /// (`CMSG_GROUP_SET_LEADER`, whose body is a guid — the app resolves it). UnitPopup's
-    /// RAID_LEADER row; [`Self::PromoteUnit`] is the same send from a party token.
+    /// `PromoteByName(name)` (`CMSG_GROUP_SET_LEADER`, whose guid the app resolves).
     PromoteName(String),
-    /// `PromoteToAssistant(name)` / `DemoteAssistant(name)` — the raid assistant flag
-    /// (`CMSG_GROUP_ASSISTANT_LEADER`: guid + grant byte).
+    /// `PromoteToAssistant(name)` / `DemoteAssistant(name)` (`CMSG_GROUP_ASSISTANT_LEADER`).
     AssistantLeader { name: String, grant: bool },
-    /// `UninviteFromRaid(index)` — kick raid row `index` (1-based). The reference's own row-index
-    /// form; `CMSG_GROUP_UNINVITE` takes a name, which the app resolves from the same roster the
-    /// index addresses.
+    /// `UninviteFromRaid(index)`: a 1-based raid row the app resolves to the name
+    /// `CMSG_GROUP_UNINVITE` takes.
     UninviteRaid(u32),
-    /// `DoReadyCheck()` — start one (`MSG_RAID_READY_CHECK`, empty body; leader only).
+    /// `DoReadyCheck()`, leader only (`MSG_RAID_READY_CHECK`, empty body).
     ReadyCheckStart,
-    /// `ConfirmReadyCheck(ready)` — answer one (`MSG_RAID_READY_CHECK`, one byte).
+    /// `ConfirmReadyCheck(ready)` (`MSG_RAID_READY_CHECK`, one byte).
     ReadyCheckAnswer(bool),
-    /// `RequestRaidInfo()` — ask for the saved-instance list (`CMSG_REQUEST_RAID_INFO`).
+    /// `RequestRaidInfo()` (`CMSG_REQUEST_RAID_INFO`).
     RequestRaidInfo,
 }
 
 impl super::UiScript {
-    /// Push the roster snapshot, replacing whatever was there. A bare setter (the `spellbook`/
-    /// `action` shape) — firing any `PARTY_*`/roster-changed event is the app's own diff-and-fire
-    /// job, never auto-fired here.
+    /// Push the roster snapshot, replacing it, and run `SMSG_GROUP_LIST`'s ready-check leg over the
+    /// new roster. The app fires the `PARTY_*` events.
     pub fn set_party(&mut self, state: PartyState) {
         self.model_mut().party = state;
-        // `SMSG_GROUP_LIST`'s ready-check leg (`0x4ba5f0`, reached only from the `0x7d` handler):
-        // the roster scan over the NEW roster — a member who left took their pending flag with
-        // them — and when nobody is left pending, a forced close (decision 1989).
+        // The ready-check leg (`0x4ba5f0`, from the `0x7d` handler): a member who left drops their
+        // pending flag, and nobody left pending force-closes the check.
         let lua = self.lua();
         let mut model = self.model_mut();
         if model.ready_check.deadline.is_some() {
@@ -264,12 +173,9 @@ impl super::UiScript {
         }
     }
 
-    /// The `MSG_RAID_READY_CHECK` open form arrived (decision 1989). The handler `0x4ba360` splits
-    /// on the leader guid: the **leader** takes the response-collection arm — reads the per-member
-    /// records the body carries (none, on vmangos) and force-closes if nobody is left pending;
-    /// everyone **else** arms the 30 s deadline (`0x4ba535`) that the leader-gated tick never
-    /// acts on for them, and gets the `READY_CHECK` popup — which the app fires on its own
-    /// ticket edge, so this method carries only the state half.
+    /// The `MSG_RAID_READY_CHECK` open form arrived (handler `0x4ba360`). The leader force-closes
+    /// if nobody is left pending; anyone else arms the 30 s deadline (`0x4ba535`), which their
+    /// leader-gated tick never acts on. The app fires the `READY_CHECK` popup.
     pub fn ready_check_request(&mut self, we_lead: bool) {
         let lua = self.lua();
         let now = clock(lua);
@@ -283,17 +189,11 @@ impl super::UiScript {
         }
     }
 
-    /// One member's answer, forwarded to the leader (`{guid, status}`, decisions 1989/1997).
-    /// The handler's leader arm (`0x4ba360`, wow-re `ui/scratch/readycheck-response-store.md`):
-    /// the record's guid is matched against the roster entry in full (`0x4ba3f9`/`0x4ba405`),
-    /// and a match stores **the constant 0** into the "has not answered" flag whatever the status
-    /// byte says (`0x4ba40e`; `ecx` is zeroed before the loop and never written) — so any answer,
-    /// ready or not, clears the member. The status byte gates one thing: a `0` prints
-    /// `RAID_MEMBER_NOT_READY` ("%s is not ready") for that member at arrival (`0x4ba414`), the
-    /// same raw-`_G` → format → `CHAT_MSG_SYSTEM` path as the summary. Then the close test: once
-    /// no member is both pending and ONLINE the check closes at once (`0x4ba4ce` → the worker)
-    /// rather than at the deadline — an offline member who never answered does not hold the
-    /// check open, and is still listed as AFK when it closes.
+    /// One member's answer, relayed to the leader (handler `0x4ba360`, guid matched in full at
+    /// `0x4ba3f9`/`0x4ba405`). Any answer clears the member's pending flag, as the handler stores a
+    /// constant 0 whatever the status byte (`0x4ba40e`); a `0` also prints `RAID_MEMBER_NOT_READY`
+    /// for them (`0x4ba414`). Once no member is both pending and online the check closes at once
+    /// (`0x4ba4ce`), so an offline member never holds it open but is still listed as AFK.
     pub fn ready_check_answered(&mut self, guid: u64, ready: bool) {
         let lua = self.lua();
         let mut model = self.model_mut();
@@ -317,9 +217,8 @@ impl super::UiScript {
         }
     }
 
-    /// The summary lines the timeout worker composed since the last drain — the reference's
-    /// `0x49a870(text, 10)` = a `CHAT_MSG_SYSTEM` line the client prints itself; the app pushes
-    /// them into the chat log the way every other client-composed system line goes.
+    /// Drain the ready-check lines composed since the last call; the reference prints each as a
+    /// `CHAT_MSG_SYSTEM` line (`0x49a870(text, 10)`).
     pub fn take_ready_check_lines(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().ready_check.lines)
     }
@@ -329,55 +228,33 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().party_requests)
     }
 
-    /// Push the saved raid-lockout list, replacing whatever was there (decision 1549). A bare
-    /// setter like [`Self::set_party`] — firing `UPDATE_INSTANCE_INFO` is the app's diff-and-fire
-    /// job, never auto-fired here.
+    /// Push the saved raid-lockout list, replacing it; the app fires `UPDATE_INSTANCE_INFO`.
     pub fn set_saved_instances(&mut self, saved: Vec<SavedInstanceInfo>) {
         self.model_mut().saved_instances = saved;
     }
 
-    /// Drain the whisper targets `ChatFrame_SendTell` queued since the last call — the app opens
-    /// its chat edit box prefilled `/w <name> ` for each (in practice the popup queues one).
+    /// Drain the names `ChatFrame_SendTell` queued; the app opens the chat edit box on
+    /// `/w <name> ` for each.
     pub fn take_tell_requests(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().tell_requests)
     }
 }
 
-/// **The leader predicate — ONE function, because the reference has one.**
-///
-/// `IsRaidLeader 0x4bb8c0` opens `mov esi,[0xbc75f8]` · `mov edi,[0xbc75fc]` and compares the pair
-/// against the local player's own GUID (`0x468550`). `IsPartyLeader 0x4e9130` opens
-/// `mov eax,[0xbc75fc]` · `mov esi,[0xbc75f8]` and compares **the same two globals** against the
-/// same GUID; its only extra instruction is an `or ecx,eax; je` short-circuit on a `0:0` cached
-/// leader, which is behaviourally inert (a zero GUID can never equal a live player's). wow-re's
-/// orchestrator re-read both prologues and they are byte-identical in the globals they load
-/// (`raid-roster-bindings.md` §3, VERIFIED).
-///
-/// **So `IsRaidLeader()` is TRUE for an ordinary 5-man party leader**, and its body reads no
-/// raid-vs-party flag and never touches the roster array/count the other two raid bindings use.
-/// Stubbing it `nil` "because there is no raid" would be a divergence — which is exactly why the
-/// two registrations below share this function rather than each growing their own rule.
+/// Whether the player leads the group. `IsRaidLeader` (`0x4bb8c0`) and `IsPartyLeader`
+/// (`0x4e9130`) both compare the cached leader guid (`[0xbc75f8]`, `[0xbc75fc]`) with the player's
+/// own (`0x468550`) and read no raid flag, so `IsRaidLeader()` is true for a party leader.
 fn leads_the_group(model: &Model) -> bool {
-    // Our stand-in for "the cached leader GUID equals mine": the app's leader index is `0` when
-    // the player leads. The `members.is_empty()` guard is the reference's `0:0` case — ungrouped,
-    // the cached pair is zero and matches nobody, whereas our `leader_index` defaults to `0`.
+    // Stand-in for that compare: `leader_index` is `0` when we lead but also when ungrouped, where
+    // the reference's zero leader guid matches nobody, hence the empty-roster guard. In a raid both
+    // cover only our subgroup: a leader elsewhere also reads `0`, and a leader alone in theirs has
+    // no `members`, so there it can differ from the guid compare.
     !model.party.members.is_empty() && model.party.leader_index == 0
 }
 
-/// `GetRaidRosterInfo`'s nine values for a **1-based** index — the whole binding's behaviour,
-/// pulled out of the registration so the arity and the miss tuple are testable as one unit.
-///
-/// **Nine values on every path** (`0x4bb560`, every return site `mov eax,9`): there is no arm that
-/// returns fewer and none that returns nothing. Out of range, index ≤ 0, a null slot and a
-/// name-cache miss all converge on `0x4bb7b9`, which pushes — in order — `nil`, the number `0`,
-/// the number `1`, the number `1`, then five `nil`s. A client that models "no such member" as zero
-/// values breaks `local name = GetRaidRosterInfo(i)` differently from the real client, and one
-/// that models it as `nil, nil, …` breaks `ChatLog.lua:346`'s `for i = 1, MAX_RAID_MEMBERS` sweep
-/// in the subgroup slot.
-///
-/// Takes the row **by value**, not the model: every arm below re-enters Lua (`create_string`, and
-/// the `PLAYER_OFFLINE` global read), and this crate's rule is that a callback drops its `app_data`
-/// borrow before it does (the module doc's MAXCSTACK/borrow discipline).
+/// `GetRaidRosterInfo`'s values for one row, or the miss tuple for `None`. Nine on every path
+/// (`0x4bb560`, every return `mov eax,9`): out of range, an empty slot and a name-cache miss all
+/// reach `0x4bb7b9`, which pushes `nil, 0, 1, 1` and five `nil`s. Takes the row by value because
+/// every arm re-enters Lua, and a callback drops its `app_data` borrow before that.
 fn raid_roster_info(lua: &Lua, row: Option<RaidMemberInfo>) -> mlua::Result<MultiValue> {
     let Some(m) = row else {
         return Ok(MultiValue::from_vec(vec![
@@ -396,10 +273,9 @@ fn raid_roster_info(lua: &Lua, row: Option<RaidMemberInfo>) -> mlua::Result<Mult
         Some(s) => lua.create_string(s).map(Value::String),
         None => Ok(Value::Nil),
     };
-    // Return 7: a real zone while online, else the **localized global** `PLAYER_OFFLINE` — read
-    // out of the VM exactly as `0x703bf0` reads it, so a translated GlobalStrings.lua translates
-    // this too. A missing global lands on `0x6f3890`'s NULL guard, which pushes `nil` and still
-    // reports one value; `Value::Nil` here is that.
+    // Return 7: the zone while online, else the `PLAYER_OFFLINE` global read from the VM
+    // (`0x703bf0`), so a translated GlobalStrings.lua translates it; a missing global pushes `nil`
+    // (`0x6f3890`).
     let zone = if m.online {
         opt_str(&m.zone)?
     } else {
@@ -412,7 +288,7 @@ fn raid_roster_info(lua: &Lua, row: Option<RaidMemberInfo>) -> mlua::Result<Mult
     Ok(MultiValue::from_vec(vec![
         lua.create_string(&m.name).map(Value::String)?,
         Value::Integer(i64::from(m.rank)),
-        // `0x4bb61a inc eax` — stored 0-based, exposed 1-based (VERIFIED adjustment).
+        // Stored 0-based, exposed 1-based (`0x4bb61a inc eax`).
         Value::Integer(i64::from(m.subgroup) + 1),
         Value::Integer(i64::from(m.level)),
         opt_str(&m.class)?,
@@ -423,13 +299,11 @@ fn raid_roster_info(lua: &Lua, row: Option<RaidMemberInfo>) -> mlua::Result<Mult
     ]))
 }
 
-/// Register the party/raid globals reading the roster snapshot store (the same style/place `unit`
-/// registers the `Unit*` globals).
+/// Register the party and raid globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumPartyMembers() → the roster's member count (0 = not in a group; never counts the player
-    // themself, matching SMSG_GROUP_LIST's recipient-excluded array).
+    // GetNumPartyMembers() → the other members, never counting the player; 0 when ungrouped.
     g.set(
         "GetNumPartyMembers",
         lua.create_function(|lua, ()| {
@@ -438,9 +312,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumRaidMembers() → the raid roster's length (0 outside a raid). The count the reference
-    // reads (`0xb713e0`) bounds the very array `GetRaidRosterInfo` indexes (`0xb712a8`), so it is
-    // the same list here, not a number beside one.
+    // GetNumRaidMembers() → the raid roster's length, 0 outside a raid.
     g.set(
         "GetNumRaidMembers",
         lua.create_function(|lua, ()| {
@@ -449,21 +321,18 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetRaidRosterInfo(index) → name, rank, subgroup, level, class, fileName, zone, online, <9th>
-    //
-    // 1-BASED, and **exactly nine values on every path** — see [`raid_roster_info`] for the arity
-    // law and the fixed miss tuple. The ONLY raise in `0x4bb560` is a non-number argument
-    // (`0x4bb582 call 0x6f34d0` → `0x4bb591 call 0x6f4940`, usage string `0x8474a0`); an index of
-    // 0, of −1, of 500, or of a live-but-uncached member all return the tuple.
+    // GetRaidRosterInfo(index) → name, rank, subgroup, level, class, fileName, zone, online and an
+    // unnamed ninth, 1-based. Its only raise is a non-number argument (`0x4bb582 call 0x6f34d0`,
+    // `0x4bb591 call 0x6f4940`, usage string `0x8474a0`).
     g.set(
         "GetRaidRosterInfo",
         lua.create_function(|lua, index: Value| {
             let index = number_arg(lua, index, "Usage: GetRaidRosterInfo(index)")?;
             let row = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
-                // `0x4bb5bb dec eax` then `0x4bb5be jae` — an UNSIGNED compare after the
-                // decrement, so ONE branch catches index ≤ 0 and index > count together (and the
-                // `dec` wraps rather than trapping, which `wrapping_sub` keeps true of `i32::MIN`).
+                // One unsigned compare after the decrement (`0x4bb5bb dec eax`, `0x4bb5be jae`)
+                // catches an index of 0 or below and one past the count; `dec` wraps, and
+                // `wrapping_sub` keeps that true of `i32::MIN`.
                 usize::try_from(index.wrapping_sub(1))
                     .ok()
                     .and_then(|i| model.party.raid.get(i))
@@ -475,8 +344,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsRaidLeader() → 1 / nil, and TRUE FOR A PARTY LEADER — the shared predicate's whole point
-    // ([`leads_the_group`]). No arguments, never raises.
+    // IsRaidLeader() → 1 or nil, true for a party leader too (`leads_the_group`).
     g.set(
         "IsRaidLeader",
         lua.create_function(|lua, ()| {
@@ -489,7 +357,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPartyMember(id) → 1 if id is a live 1-based roster slot, else nil (era 1/nil shape).
+    // GetPartyMember(id) → 1 for a filled 1-based slot, else nil.
     g.set(
         "GetPartyMember",
         lua.create_function(|lua, id: i64| {
@@ -512,8 +380,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsPartyLeader() → 1 iff we're grouped AND lead it, else nil (a solo player doesn't "lead").
-    // Shares [`leads_the_group`] with `IsRaidLeader` because the reference shares the globals.
+    // IsPartyLeader() → 1 when grouped and leading, else nil; the same predicate as IsRaidLeader.
     g.set(
         "IsPartyLeader",
         lua.create_function(|lua, ()| {
@@ -526,16 +393,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootMethod() → lootmethod, masterlooterPartyID (the era 2-tuple return; later clients add
-    // a raid index third return we don't carry). An unset method (never pushed) reports the
-    // fresh-player shape: "group", nil.
+    // GetLootMethod() → lootmethod, masterlooterPartyID: two returns in 1.12.
     g.set(
         "GetLootMethod",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // **`freeforall`, not `group`.** The three cells this reads sit past `.data`'s raw end
-            // in the zero-filled tail, so a client that has never been in a group answers the
-            // zeroth method — which is `freeforall`. Decision 1840.
+            // Never grouped, the reference reads zero-filled cells past `.data`'s end, and method
+            // 0 is `freeforall`.
             let method = if model.party.loot_method.is_empty() {
                 "freeforall"
             } else {
@@ -549,7 +413,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetLootThreshold() → the quality floor (0 while ungrouped is fine — nothing to floor).
+    // GetLootThreshold() → the loot quality threshold.
     g.set(
         "GetLootThreshold",
         lua.create_function(|lua, ()| {
@@ -558,8 +422,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The outbound half: each call queues a PartyRequest, the app drains and sends. No-return, era
-    // shape (fire-and-forget, like TargetUnit/CastSpell).
+    // The party verbs queue a `PartyRequest` and return nothing.
     g.set(
         "AcceptGroup",
         lua.create_function(|lua, ()| {
@@ -616,9 +479,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetLootMethod("method" [,master] [,threshold]) — the reference's own usage string
-    // (`0x84c42c`). The master-looter argument is read ONLY for "master"; the threshold argument
-    // is optional for every method (decision 1675).
+    // SetLootMethod("method" [,master] [,threshold]), the reference's usage string (`0x84c42c`).
     g.set(
         "SetLootMethod",
         lua.create_function(
@@ -641,13 +502,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetRaidTarget(unit, index) — the ENGINE verb. `SetRaidTargetIcon` is NOT one: it is FrameXML,
-    // `function SetRaidTargetIcon(unit, index)` at `TargetFrame.lua:486`, a toggle wrapper that
-    // calls this with 0 when the unit already wears `index`. We had registered the wrapper's name on
-    // this body, which behaved correctly and so never showed — until 1751 put `TargetFrame.lua` on
-    // the chain and the wrapper started calling a `SetRaidTarget` that did not exist. Proof both
-    // ways: no `function SetRaidTarget(` anywhere in the reference's FrameXML, and both
-    // `TargetFrame.lua:488`/`:490` and `Bindings.xml:1160` call it bare.
+    // SetRaidTarget(unit, index) is the engine verb. `SetRaidTargetIcon` is FrameXML's toggle
+    // around it (`TargetFrame.lua:486`), and `TargetFrame.lua:488`, `:490` and `Bindings.xml:1160`
+    // call it bare.
     g.set(
         "SetRaidTarget",
         lua.create_function(|lua, (unit, index): (String, u8)| {
@@ -659,29 +516,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsRaidOfficer() → nil, always: a 1.12 PARTY has no officer rank (the assistant flag is a
-    // raid concept). The popup's leader-or-assistant gates read this and fall back to the leader
-    // half. The roster now carries the assistant rank ([`RaidMemberInfo::rank`], `1`), so the
-    // *data* to answer this exists — what does not is a carve of `IsRaidOfficer`'s own body, and
-    // "it is probably rank ≥ 1 for the player's row" is a guess, not a mechanism. Left nil until
-    // someone reads the bytes.
+    // IsRaidOfficer() → always nil: its reference body (`0x4bb910`) is untraced. So the RaidFrame
+    // enables its add-member button for the leader only, where the reference also enables it for
+    // an assistant.
     g.set(
         "IsRaidOfficer",
         lua.create_function(|_, ()| Ok(Value::Nil))?,
     )?;
 
-    // ── The raid-management verbs (decision 1549) ────────────────────────────────────────────
-    //
-    // All nine are `ORCHESTRATION` in wow-re's own classification (`ui/scratch/bindings.md`:
-    // `ConvertToRaid 0x4bbc90`, `SetRaidSubgroup 0x4bb990`, `SwapRaidSubgroup 0x4bbb00`,
-    // `PromoteToAssistant 0x4bbd20`, `RequestRaidInfo 0x4a1850`, `GetSavedInstanceInfo 0x4a1920`;
-    // `UninviteFromRaid 0x48a580` and `SetRaidRosterSelection 0x4bb820` in
-    // `item17-frameapi-fullcarve.md`) — "marshals + delegates to a C++ method/net-send; no inline
-    // fidelity math". So the *binding* has no law of its own to reproduce: the law is the wire's,
-    // which `benilla-protocol`'s `group` family already carries byte-golden, and the marshalling
-    // is the queue below. Nothing here is a guess about a body nobody has read.
-    //
-    // They queue rather than send for the module doc's reason: this crate cannot reach the net.
+    // ── The raid-management verbs ────────────────────────────────────────────
+    // Each only marshals its arguments into a client call or a send (`ConvertToRaid 0x4bbc90`,
+    // `SetRaidSubgroup 0x4bb990`, `SwapRaidSubgroup 0x4bbb00`, `PromoteToAssistant 0x4bbd20`,
+    // `RequestRaidInfo 0x4a1850`, `GetSavedInstanceInfo 0x4a1920`, `UninviteFromRaid 0x48a580`,
+    // `SetRaidRosterSelection 0x4bb820`), so the verbs here queue a request.
     g.set(
         "ConvertToRaid",
         lua.create_function(|lua, ()| {
@@ -690,9 +537,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // SetRaidSubgroup(index, group) / SwapRaidSubgroup(index, other) — the drag's two landings.
-    // Both take numbers through the shared argument gate, so a non-number raises the reference's
-    // usage error rather than silently queueing a zero.
+    // SetRaidSubgroup(index, group) / SwapRaidSubgroup(index, other), the drag's two drops: a
+    // non-number raises the usage error rather than queueing a zero.
     g.set(
         "SetRaidSubgroup",
         lua.create_function(|lua, (index, group): (Value, Value)| {
@@ -755,10 +601,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, ()| {
             let now = clock(lua);
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // The worker `0x4bb1d0` (decision 1989): every roster member except the caller is
-            // flagged "has not answered" (`0x4bb24c`), the caller cleared (`0x4bb258`), the 30 s
-            // deadline armed (`0x4bb2b6`) — then the packet. A party has no raid roster, so the
-            // flags are empty there and the leader's own echo closes the check at once.
+            // The worker `0x4bb1d0` flags every roster member but the caller as pending
+            // (`0x4bb24c`, `0x4bb258`) and arms the 30 s deadline (`0x4bb2b6`), then sends. A
+            // party has no raid roster, so nothing is flagged and the leader's echo closes it.
             let own = model.party.own_guid;
             model.ready_check.unanswered = model
                 .party
@@ -772,17 +617,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `CheckReadyCheckTime` (`0x4bc120` → `0x4bb310`) — the ready-check timeout tick, called from
-    // the stock `UIParent.xml`'s `<OnUpdate>` every frame and driving the 30-second expiry alone
-    // (nothing in the engine polls it). Four conjuncts, any failure writing nothing: a deadline is
-    // armed, it has been reached, and the active player's guid equals the group leader's — a
-    // LEADER gate, so it is observably inert for anyone else. On expiry it disarms the deadline
-    // (the only clear-to-zero outside module init), lists every roster member still flagged as
-    // unanswered, and prints `RAID_MEMBERS_AFK` with the `", "`-joined names — or
-    // `READY_CHECK_NO_AFK` — as a `CHAT_MSG_SYSTEM` line. Both keys are read raw off `_G`
-    // (`0x704350`: `lua_gettable` on GLOBALSINDEX, empty-string default), never through
-    // `GetText`. Sends no packet, raises nothing, returns nothing (decision 1989; wow-re
-    // `ui/scratch/uiparent-onupdate-engine-verbs.md` §3).
+    // CheckReadyCheckTime() (`0x4bc120` → `0x4bb310`), called every frame from stock
+    // `UIParent.xml`'s `OnUpdate`, alone drives the 30 s expiry. Once an armed deadline passes, and
+    // only on the leader's client, it disarms and prints `RAID_MEMBERS_AFK` with the pending names
+    // joined by `", "`, or `READY_CHECK_NO_AFK`, as a `CHAT_MSG_SYSTEM` line. Both strings are read
+    // raw from `_G` with an empty default (`0x704350`), not through `GetText`; nothing is sent.
     g.set(
         "CheckReadyCheckTime",
         lua.create_function(|lua, ()| {
@@ -792,9 +631,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // ConfirmReadyCheck(ready) — the popup's two buttons, and the argument is read for TRUTH, not
-    // for a number: the reference's own No button calls it with no argument at all
-    // (`ConfirmReadyCheck()`) while Yes passes `1`, so "absent" has to mean "not ready".
+    // ConfirmReadyCheck(ready) reads its argument as truth: the reference's No button passes no
+    // argument, Yes passes `1`.
     g.set(
         "ConfirmReadyCheck",
         lua.create_function(|lua, ready: Value| {
@@ -815,9 +653,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumSavedInstances() / GetSavedInstanceInfo(index) — the Raid Info panel's pair, over the
-    // app-pushed list. 1-based like every other indexed getter here, and a miss answers a plain
-    // `nil` (the panel's own loop only ever indexes inside the count it just read).
+    // GetNumSavedInstances() / GetSavedInstanceInfo(index), 1-based over the pushed list; a miss
+    // returns nothing.
     g.set(
         "GetNumSavedInstances",
         lua.create_function(|lua, ()| {
@@ -847,9 +684,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetRaidRosterSelection(index) / GetRaidRosterSelection() — a purely CLIENT-SIDE cursor (the
-    // reference's `0x4bb820` writes a global; nothing is sent). The RaidFrame sets it when a row
-    // is picked up so the menu and the drag agree on who is being acted on.
+    // SetRaidRosterSelection(index) / GetRaidRosterSelection(): a client-side cursor; the
+    // reference's `0x4bb820` writes a global and sends nothing.
     g.set(
         "SetRaidRosterSelection",
         lua.create_function(|lua, index: Value| {
@@ -867,10 +703,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ChatFrame_SendTell(name) — the popup's WHISPER action. In the ref this is ChatFrame.lua
-    // filling the edit box with "/w name "; our chat edit is app-side (ui_chat), so the call
-    // queues the name for the app to open the edit box prefilled (UiScript::take_tell_requests
-    // drains — the PartyRequest seam's chat sibling).
+    // ChatFrame_SendTell(name) is FrameXML in the reference (`ChatFrame.lua:1606`, opening the
+    // edit box on `/w name `); the chat edit box is app-side here, so this queues the name for
+    // `UiScript::take_tell_requests`.
     g.set(
         "ChatFrame_SendTell",
         lua.create_function(|lua, name: String| {
@@ -886,11 +721,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 /// The ready-check deadline, `0x7530` ms after the arm (`0x4ba535`, `0x4bb2b6`).
 const READY_CHECK_SECONDS: f64 = 30.0;
 
-/// The client's ready-check state (`RaidInfo.cpp`, decision 1989): the armed deadline
-/// (`[0xb713f4]`, `None` = disarmed) and the roster members whose "has not answered yet" flag
-/// (`[entry+0x158]`) is set, plus the summary lines the timeout worker composed and the app has
-/// not yet pushed into chat. Outside [`PartyState`] because a roster push replaces that whole
-/// snapshot and this survives one — the reference keeps the two in different tables too.
+/// The ready-check state: the armed deadline (`[0xb713f4]`), the members whose pending flag
+/// (`[entry+0x158]`) is set, and summary lines not yet pushed to chat. Outside [`PartyState`]
+/// because a roster push replaces that and this survives it.
 #[derive(Debug, Default)]
 pub(crate) struct ReadyCheckState {
     pub(crate) deadline: Option<f64>,
@@ -898,12 +731,12 @@ pub(crate) struct ReadyCheckState {
     pub(crate) lines: Vec<String>,
 }
 
-/// `GetTime()`'s clock — the session seconds `UiScript::tick` advances.
+/// `GetTime()`'s clock, the session seconds `UiScript::tick` advances.
 fn clock(lua: &Lua) -> f64 {
     lua.globals().get("__benilla_now").unwrap_or(0.0)
 }
 
-/// The timeout worker `0x4bb310` — see `CheckReadyCheckTime`'s note for the contract.
+/// The timeout worker `0x4bb310`.
 fn ready_check_tick(lua: &Lua, model: &mut Model, now: f64) {
     let Some(deadline) = model.ready_check.deadline else {
         return;
@@ -915,8 +748,7 @@ fn ready_check_tick(lua: &Lua, model: &mut Model, now: f64) {
         return;
     }
     model.ready_check.deadline = None;
-    // The roster walk: an unresolved name is silently skipped (`0x55f080` with its query arm
-    // off), so a flagged member the roster cannot name contributes nothing to the list.
+    // A pending member the roster cannot name is skipped (`0x55f080`, its query arm off).
     let names: Vec<&str> = model
         .ready_check
         .unanswered
@@ -934,9 +766,9 @@ fn ready_check_tick(lua: &Lua, model: &mut Model, now: f64) {
     model.ready_check.lines.push(text);
 }
 
-/// The `0x322` handler's close predicate (`0x4ba498`–`0x4ba4cc`, decision 1997): a member still
-/// holds the check open only while they are BOTH flagged unanswered AND online (`[entry+0x18]`
-/// bit 0, the `SMSG_GROUP_LIST` online byte). An empty roster closes at once (`0x4ba3ea`).
+/// The `0x322` handler's close test (`0x4ba498`-`0x4ba4cc`): a member holds the check open only
+/// while pending and online (`[entry+0x18]` bit 0, `SMSG_GROUP_LIST`'s online bit). An empty
+/// roster closes at once (`0x4ba3ea`).
 fn ready_check_pending_online(model: &Model) -> bool {
     model
         .ready_check
@@ -945,8 +777,8 @@ fn ready_check_pending_online(model: &Model) -> bool {
         .any(|g| model.party.raid.iter().any(|m| m.guid == *g && m.online))
 }
 
-/// The two C-side force-close sites (`0x4ba4d4`, `0x4bacb4`): the deadline is set to `now − 1`
-/// and the worker runs at once. The arm test is theirs too — both force only an armed check.
+/// The force-close sites (`0x4ba4d4`, `0x4bacb4`): an armed deadline becomes `now - 1` and the
+/// worker runs at once.
 fn ready_check_force_close(lua: &Lua, model: &mut Model) {
     if model.ready_check.deadline.is_none() {
         return;
@@ -994,7 +826,6 @@ mod tests {
         assert!(s.eval::<bool>("return GetPartyMember(3) == nil").unwrap());
         assert!(s.eval::<bool>("return GetPartyMember(0) == nil").unwrap());
         assert_eq!(s.eval::<i64>("return GetPartyLeaderIndex()").unwrap(), 1);
-        // Alice (party1) leads, not us.
         assert!(s.eval::<bool>("return IsPartyLeader() == nil").unwrap());
         let (method, master) = s
             .eval::<(String, Option<i64>)>("return GetLootMethod()")
@@ -1034,18 +865,12 @@ mod tests {
         let (method, master) = s
             .eval::<(String, Option<i64>)>("return GetLootMethod()")
             .unwrap();
-        // **`freeforall` is the UNGROUPED answer**, not `group`: the cells the reference reads
-        // sit in `.data`'s zero-filled tail, so a client that has never been in a group reports
-        // the zeroth method (decision 1840). The `group` above is a real party's, and stays.
+        // Never grouped reads method 0, `freeforall`; the `group` above is a real party's.
         assert_eq!(method, "freeforall");
         assert_eq!(master, None);
     }
 
-    // ── The raid trio (wow-re `ui/scratch/raid-roster-bindings.md`) ─────────────────────────────
-    //
-    // One test per return-shape trap, in `item_stats`'s `get_item_info_tests` style: the ARITY
-    // assertion is half of each, because a signature regression is the failure every individual
-    // read still survives.
+    // ── The raid trio (`UnitInRaid`, `GetRaidRosterInfo`, `IsRaidLeader`) ────────────────────
 
     fn raider(name: &str, guid: u64) -> crate::script::RaidMemberInfo {
         crate::script::RaidMemberInfo {
@@ -1068,16 +893,14 @@ mod tests {
             .collect();
         raid[0].rank = 2; // the leader
         raid[0].name = "Me".into();
-        raid[3].subgroup = 1; // stored 0-based — the binding exposes 2
+        raid[3].subgroup = 1; // stored 0-based, exposed 2
         PartyState {
             raid,
             ..Default::default()
         }
     }
 
-    /// **Nine values on every path**, including the paths that have no member to describe. Every
-    /// return site in `0x4bb560` is `mov eax,9`; the out-of-range arm `0x4bb7b9` pushes nine
-    /// values of its own rather than returning nothing.
+    /// Every return site in `0x4bb560` is `mov eax,9`, the miss arm `0x4bb7b9` included.
     #[test]
     fn get_raid_roster_info_returns_nine_values_on_every_path() {
         let mut s = UiScript::new().unwrap();
@@ -1090,13 +913,11 @@ mod tests {
                 "index {index} must still be a nine-value answer"
             );
         }
-        // And with no raid at all — the shape does not depend on being in one.
         let s = UiScript::new().unwrap();
         assert_eq!(s.arity("GetRaidRosterInfo(1)").unwrap(), 9);
     }
 
-    /// The miss tuple is `(nil, 0, 1, 1, nil, nil, nil, nil, nil)` — **not** nine nils, and not
-    /// nothing. `0x4bb7b9` pushes nil, then the number 0, then 1, then 1, then five nils.
+    /// `0x4bb7b9` pushes `nil, 0, 1, 1` and five nils.
     #[test]
     fn get_raid_roster_info_misses_with_the_fixed_tuple() {
         let mut s = UiScript::new().unwrap();
@@ -1113,8 +934,7 @@ mod tests {
         );
         assert!(e && f && g && h && i, "the last five are nil");
 
-        // An in-range member whose NAME has not been cached takes the same arm — the reference's
-        // `0x4bb5f8 je 0x4bb7b9`, which is why a client must not model this as "returns nothing".
+        // An in-range member with no cached name takes the same arm (`0x4bb5f8 je 0x4bb7b9`).
         let mut party = ten_player_raid();
         party.raid[1].name = String::new();
         s.set_party(party);
@@ -1124,8 +944,6 @@ mod tests {
         assert!(name_nil && rank == 0, "an uncached name is a full miss");
     }
 
-    /// The success tuple, destructured positionally exactly as `ChatLog.lua:347` and
-    /// `oRA2/Leader/Ready.lua:241` destructure it.
     #[test]
     fn get_raid_roster_info_reports_the_pushed_row() {
         let mut s = UiScript::new().unwrap();
@@ -1159,8 +977,7 @@ mod tests {
         );
     }
 
-    /// An OFFLINE member's zone slot carries the localized `PLAYER_OFFLINE` global, never nil —
-    /// and return 8 goes nil on that same arm (`0x4bb705`).
+    /// Return 8 goes nil on the same arm (`0x4bb705`).
     #[test]
     fn get_raid_roster_info_puts_player_offline_in_the_zone_slot() {
         let mut s = UiScript::new().unwrap();
@@ -1168,7 +985,7 @@ mod tests {
         party.raid[1].online = false;
         party.raid[1].zone = Some("Molten Core".into()); // ignored on the offline arm
         s.set_party(party);
-        // GlobalStrings.lua is the app's to load; the binding reads whatever the VM has.
+        // The binding reads whatever `PLAYER_OFFLINE` the VM holds.
         s.run(r#"PLAYER_OFFLINE = "Offline""#).unwrap();
         let (zone, online): (String, Option<i64>) = s
             .eval("local _,_,_,_,_,_,g,h = GetRaidRosterInfo(2) return g, h")
@@ -1177,8 +994,7 @@ mod tests {
         assert_eq!(online, None);
     }
 
-    /// A non-number argument is the ONLY raise in the whole function (`0x4bb591`), and it raises
-    /// rather than returning nil or nothing — `0x6f4940` never returns.
+    /// The raise at `0x4bb591` goes through `0x6f4940`, which never returns.
     #[test]
     fn get_raid_roster_info_raises_only_on_a_non_number() {
         let s = UiScript::new().unwrap();
@@ -1187,12 +1003,11 @@ mod tests {
             format!("{err}").contains("Usage: GetRaidRosterInfo(index)"),
             "got {err}"
         );
-        // A numeric string coerces (Lua 5.1's `lua_isnumber`) and does NOT raise.
+        // A numeric string coerces (`lua_isnumber`) and does not raise.
         assert_eq!(s.arity(r#"GetRaidRosterInfo("3")"#).unwrap(), 9);
     }
 
-    /// `UnitInRaid` answers the **constant 1**, not a roster index — the value is the hard-coded
-    /// double at `0x51637e`, and the helper underneath never exposes a counter.
+    /// The 1 is the constant double at `0x51637e`.
     #[test]
     fn unit_in_raid_answers_one_not_an_index() {
         let mut s = UiScript::new().unwrap();
@@ -1210,23 +1025,16 @@ mod tests {
         assert!(s
             .eval::<bool>(r#"return UnitInRaid("mouseover") == nil"#)
             .unwrap());
-        // **The input partition, and it is NOT "never raises".** This test used to assert that a
-        // missing, wrong-typed or unknown token is all nil, on a wow-re finding that published "no
-        // error path". That claim was refuted by a later §5 cross-check and corrected at the source
-        // (`raid-roster-bindings.md` §1: *"The grammar is now enumerated and it settles the other
-        // way"*), which named `UnitInRaid` as one of exactly three verbs carrying the wrong claim.
-        //
-        // Quiet nil: `0x6f3690` returns NULL for a missing or uncoercible argument, `0x515970` maps
-        // NULL/empty to GUID `0:0`, and `0x4baee0` short-circuits `0:0` to false at entry.
+        // Nil for a missing, wrong-typed or unmatched token: `0x6f3690` gives NULL, `0x515970` maps
+        // it to guid 0, and `0x4baee0` rejects guid 0.
         for call in ["UnitInRaid()", "UnitInRaid(nil)", r#"UnitInRaid("party3")"#] {
             assert!(
                 s.eval::<bool>(&format!("return {call} == nil")).unwrap(),
                 "{call} must answer nil"
             );
         }
-        // Raise: a token matching none of the nine prefixes reaches
-        // `luaL_error("Unknown unit name: %s")` and longjmps — and a NUMBER is coerced to a string
-        // first, so it raises too. `UnitInRaid("bogus")` never returns on the real client.
+        // A token matching none of the nine prefixes raises `Unknown unit name: %s`, and a number
+        // is coerced to a string first.
         for call in ["UnitInRaid(7)", r#"UnitInRaid("nosuchtoken")"#] {
             assert!(
                 s.run(call).is_err(),
@@ -1235,15 +1043,12 @@ mod tests {
         }
     }
 
-    /// **`IsRaidLeader()` is true for an ordinary 5-man party leader.** Its body reads the same
-    /// two leader-GUID globals `IsPartyLeader` does and carries no raid-vs-party flag at all
-    /// (`0x4bb8c0` vs `0x4e9130`, both prologues re-read by wow-re's orchestrator). Answering nil
-    /// "because there is no raid" would be the divergence.
+    /// `0x4bb8c0` reads the same leader guid as `0x4e9130`, and no raid flag.
     #[test]
     fn is_raid_leader_is_true_for_a_party_leader() {
         let mut s = UiScript::new().unwrap();
         let mut party = two_member_party();
-        party.leader_index = 0; // we lead — a PARTY, with an empty raid roster
+        party.leader_index = 0; // we lead a party, with no raid roster
         s.set_party(party);
         assert!(
             s.eval::<i64>("return GetNumRaidMembers()").unwrap() == 0,
@@ -1252,18 +1057,15 @@ mod tests {
         assert_eq!(s.eval::<i64>("return IsRaidLeader()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return IsPartyLeader()").unwrap(), 1);
 
-        // Somebody else leads: both go nil, together.
         s.set_party(two_member_party()); // leader_index 1 = Alice
         assert!(s.eval::<bool>("return IsRaidLeader() == nil").unwrap());
         assert!(s.eval::<bool>("return IsPartyLeader() == nil").unwrap());
 
-        // Ungrouped: nil (the reference's cached leader pair is `0:0` and matches nobody).
+        // Ungrouped: the cached leader guid is 0 and matches nobody.
         let s = UiScript::new().unwrap();
         assert!(s.eval::<bool>("return IsRaidLeader() == nil").unwrap());
     }
 
-    /// One list, not a count beside one: `GetNumRaidMembers` and `GetRaidRosterInfo` cannot
-    /// disagree about how many members there are.
     #[test]
     fn get_num_raid_members_bounds_the_roster_it_indexes() {
         let mut s = UiScript::new().unwrap();
@@ -1280,7 +1082,6 @@ mod tests {
     #[test]
     fn intent_natives_queue_the_exact_request_sequence() {
         let mut s = UiScript::new().unwrap();
-        // Nothing queued until a call lands.
         assert!(s.take_party_requests().is_empty());
 
         s.run("AcceptGroup()").unwrap();
@@ -1311,7 +1112,6 @@ mod tests {
                 PartyRequest::LootThreshold(3),
             ]
         );
-        // The drain is a take — a second read is empty.
         assert!(s.take_party_requests().is_empty());
     }
 
@@ -1328,8 +1128,7 @@ mod tests {
             }]
         );
 
-        // The optional THIRD argument, which the real binding reads for every method — not only
-        // for "master", the way the master-looter argument is read (decision 1675).
+        // The third argument is read for every method.
         s.run(r#"SetLootMethod("group", nil, 4)"#).unwrap();
         assert_eq!(
             s.take_party_requests(),
@@ -1361,13 +1160,7 @@ mod tests {
         );
     }
 
-    /// `IsRaidOfficer()` still answers nil, and the raid arc landing (decision 1549) did NOT
-    /// change that — it is not waiting on a feature, it is waiting on a carve of `0x4bb910`'s own
-    /// body. The binding's doc carries the refusal; this pins the behaviour so a later "surely it
-    /// is just rank >= 1" edit has to argue with a test.
-    ///
-    /// What it costs today, stated where someone will find it: `RaidFrameAddMemberButton` is
-    /// enabled for the raid LEADER only, where the reference also enables it for an assistant.
+    /// Nil until `0x4bb910`'s body is traced; "rank >= 1" would be a guess.
     #[test]
     fn is_raid_officer_is_still_nil_and_that_is_a_missing_carve_not_a_missing_feature() {
         let s = UiScript::new().unwrap();
@@ -1383,7 +1176,7 @@ mod tests {
         assert!(s.take_tell_requests().is_empty());
     }
 
-    // ── The identity predicates (decision 0434 §5 — the popup's menu pick + gating) ─────────────
+    // ── The identity predicates ─────────────────────────────────────────────
 
     fn unit(exists: bool, guid: u64) -> crate::script::UnitState {
         crate::script::UnitState {
@@ -1399,7 +1192,6 @@ mod tests {
         s.set_unit("player", Some(unit(true, 0x10)));
         s.set_unit("target", Some(unit(true, 0x10)));
         s.set_unit("party1", Some(unit(true, 0x20)));
-        // Same guid across tokens; same token trivially; different guids nil.
         assert_eq!(
             s.eval::<i64>(r#"return UnitIsUnit("target", "player")"#)
                 .unwrap(),
@@ -1413,21 +1205,19 @@ mod tests {
         assert!(s
             .eval::<bool>(r#"return UnitIsUnit("party1", "player") == nil"#)
             .unwrap());
-        // Zero guids never match across tokens (unknown identity is not identity).
+        // Zero guids never match across tokens.
         s.set_unit("target", Some(unit(true, 0)));
         s.set_unit("mouseover", Some(unit(true, 0)));
         assert!(s
             .eval::<bool>(r#"return UnitIsUnit("target", "mouseover") == nil"#)
             .unwrap());
-        // A missing token is nil.
         assert!(s
             .eval::<bool>(r#"return UnitIsUnit("pet", "player") == nil"#)
             .unwrap());
     }
 
-    /// `UnitPlayerOrPetInParty`/`InRaid` (1958): a member's own guid, or a unit whose OWNER is a
-    /// member — the party's for the one, the raid roster's for the other; a stranger's pet is
-    /// nobody's; ungrouped is nil.
+    /// A member's own guid, or a unit whose owner is a member: the party's for
+    /// `UnitPlayerOrPetInParty`, the raid roster's for `UnitPlayerOrPetInRaid`.
     #[test]
     fn unit_player_or_pet_in_party_reads_the_owner() {
         let mut s = UiScript::new().unwrap();
@@ -1460,7 +1250,6 @@ mod tests {
                 .unwrap(),
             1
         );
-        // The raid twin over the raid roster.
         s.set_party(ten_player_raid());
         let mut raiders_pet = unit(true, 0xC0FFEE);
         raiders_pet.owner = ten_player_raid().raid[0].guid;
@@ -1482,11 +1271,9 @@ mod tests {
         s.set_party(two_member_party());
         s.set_unit("player", Some(unit(true, 0x10)));
         s.set_unit("party1", Some(unit(true, 0xA11CE)));
-        // The target IS Alice (guid match through an arbitrary token).
         s.set_unit("target", Some(unit(true, 0xA11CE)));
         assert_eq!(s.eval::<i64>(r#"return UnitInParty("target")"#).unwrap(), 1);
         assert_eq!(s.eval::<i64>(r#"return UnitInParty("party1")"#).unwrap(), 1);
-        // A stranger's guid is nil.
         s.set_unit("target", Some(unit(true, 0xDEAD)));
         assert!(s
             .eval::<bool>(r#"return UnitInParty("target") == nil"#)
@@ -1510,7 +1297,6 @@ mod tests {
                 .unwrap(),
             1
         );
-        // A hostile player, and a friendly NPC, both fail the gate.
         let mut hostile = friendly.clone();
         hostile.reaction = 2;
         s.set_unit("target", Some(hostile));
@@ -1525,8 +1311,6 @@ mod tests {
             .unwrap());
     }
 
-    /// Every raid-management verb queues the request it names, with its arguments in the order
-    /// the reference's binding takes them — the seam the whole pane acts through (decision 1549).
     #[test]
     fn the_raid_verbs_queue_what_they_name() {
         let mut s = UiScript::new().unwrap();
@@ -1570,9 +1354,7 @@ mod tests {
         assert!(s.take_party_requests().is_empty(), "the drain empties");
     }
 
-    /// `ConfirmReadyCheck` reads its argument for TRUTH, not for a number — the reference's No
-    /// button calls it with **no argument at all** while Yes passes `1`, so "absent" has to be the
-    /// not-ready answer or every declined ready check reads as accepted.
+    /// The reference's No button passes no argument, Yes passes `1`.
     #[test]
     fn confirm_ready_check_treats_an_absent_argument_as_not_ready() {
         let mut s = UiScript::new().unwrap();
@@ -1584,14 +1366,12 @@ mod tests {
                 PartyRequest::ReadyCheckAnswer(true),
                 PartyRequest::ReadyCheckAnswer(false),
                 PartyRequest::ReadyCheckAnswer(false),
-                // `0` is TRUTHY in Lua, and the binding is a truth test — so this is ready.
+                // `0` is true in Lua.
                 PartyRequest::ReadyCheckAnswer(true),
             ]
         );
     }
 
-    /// The saved-lockout pair: 1-based, three returns, and a miss is a plain nothing (the panel's
-    /// own loop only ever indexes inside the count it just read).
     #[test]
     fn saved_instance_info_reads_the_pushed_list() {
         use crate::script::SavedInstanceInfo;
@@ -1625,13 +1405,11 @@ mod tests {
                 "index {miss} is a miss"
             );
         }
-        // A non-number still raises, like every other indexed getter here.
         assert!(s
             .eval::<i64>(r#"return GetSavedInstanceInfo("x")"#)
             .is_err());
     }
 
-    /// `SetRaidRosterSelection` is purely client-side: it moves a cursor and sends nothing.
     #[test]
     fn the_raid_roster_selection_is_a_local_cursor() {
         let mut s = UiScript::new().unwrap();
@@ -1664,9 +1442,9 @@ mod tests {
             .unwrap());
     }
 
-    // ── The ready-check timeout (decision 1989) ─────────────────────────────────────────────
+    // ── The ready-check timeout ─────────────────────────────────────────────
 
-    /// A raid we lead: us, Alice and Bob on the roster; the two strings the summary reads raw.
+    /// Us, Alice and Bob, with the two summary strings set.
     fn raid_we_lead(s: &UiScript) -> PartyState {
         s.run(
             r#"RAID_MEMBERS_AFK = "The following players are AFK: %s"
@@ -1704,9 +1482,6 @@ mod tests {
         }
     }
 
-    /// `DoReadyCheck` flags every roster member but the caller and arms 30 s; the tick is a no-op
-    /// before the deadline, prints the `", "`-joined unanswered names on it, and — the only
-    /// clear-to-zero — disarms, so the next tick prints nothing.
     #[test]
     fn the_leaders_check_times_out_into_the_afk_list_and_disarms() {
         let mut s = UiScript::new().unwrap();
@@ -1733,9 +1508,7 @@ mod tests {
         );
     }
 
-    /// An answer clears its member's flag; the answer that leaves nobody pending (and online)
-    /// closes the check at once (`0x4ba4d9`), well before the deadline. (A "not ready" answer
-    /// does the same and prints its line first — the test below.)
+    /// The answer that leaves nobody pending closes the check at once (`0x4ba4d9`).
     #[test]
     fn an_answer_clears_its_member_and_the_last_one_closes_the_check_at_once() {
         let mut s = UiScript::new().unwrap();
@@ -1757,10 +1530,7 @@ mod tests {
         assert!(s.take_ready_check_lines().is_empty());
     }
 
-    /// A "not ready" answer prints `RAID_MEMBER_NOT_READY` for that member the moment it arrives —
-    /// and clears their flag all the same, because the leader arm stores the constant 0 whatever
-    /// the byte says (`0x4ba40e`, wow-re `readycheck-response-store.md`). A guid the roster does
-    /// not hold writes nothing.
+    /// The leader arm stores a constant 0 whatever the status byte (`0x4ba40e`).
     #[test]
     fn a_not_ready_answer_prints_its_line_and_still_clears_the_member() {
         let mut s = UiScript::new().unwrap();
@@ -1787,9 +1557,8 @@ mod tests {
         );
     }
 
-    /// An OFFLINE member who never answers does not hold the check open (`0x4ba4a7 test byte
-    /// [eax+0x18],dl`), but the summary that closes it still lists them: the worker walks the
-    /// flags with no online test (`0x4bb3a8`).
+    /// The close tests online (`0x4ba4a7 test byte [eax+0x18],dl`); the summary's walk does not
+    /// (`0x4bb3a8`).
     #[test]
     fn an_offline_member_never_blocks_the_close_but_is_still_listed() {
         let mut s = UiScript::new().unwrap();
@@ -1808,9 +1577,7 @@ mod tests {
         );
     }
 
-    /// The tick is leader-gated: a member's client arms the same 30 s on the open form and the
-    /// four conjuncts fail on the guid compare, every frame, forever — the deadline stays armed
-    /// (nothing on the member's side ever clears it) and nothing is ever printed.
+    /// A member's client arms the deadline, never clears it, and never prints.
     #[test]
     fn the_tick_is_inert_for_a_non_leader() {
         let mut s = UiScript::new().unwrap();
@@ -1824,8 +1591,6 @@ mod tests {
         assert_eq!(s.model_mut().ready_check.deadline, Some(130.0));
     }
 
-    /// `SMSG_GROUP_LIST`'s leg: a member who left took their pending flag with them, and a roster
-    /// scan that finds nobody pending force-closes the check.
     #[test]
     fn a_roster_change_with_nobody_left_pending_closes_the_check() {
         let mut s = UiScript::new().unwrap();
@@ -1833,7 +1598,6 @@ mod tests {
         s.set_party(party.clone());
         s.run("__benilla_now = 100 DoReadyCheck()").unwrap();
         s.ready_check_answered(0xA11CE, true);
-        // Bob leaves: the roster without him.
         let mut without_bob = party;
         without_bob.raid.retain(|m| m.guid != 0xB0B);
         without_bob.members.retain(|m| m.guid != 0xB0B);
@@ -1844,8 +1608,7 @@ mod tests {
         );
     }
 
-    /// A plain party has no raid roster, so `DoReadyCheck` flags nobody — and the leader's own
-    /// echo of the open form, taking the response-collection arm, closes it on the spot.
+    /// A party has no raid roster, so `DoReadyCheck` flags nobody.
     #[test]
     fn the_leaders_own_echo_closes_an_empty_check_at_once() {
         let mut s = UiScript::new().unwrap();
@@ -1860,8 +1623,7 @@ mod tests {
         );
     }
 
-    /// The two keys are read raw off `_G` with an empty-string default — a missing GlobalStrings
-    /// prints an empty line and never raises.
+    /// Both keys are read raw from `_G` with an empty default.
     #[test]
     fn a_missing_summary_string_prints_an_empty_line() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/pet.rs b/crates/benilla-ui/src/script/pet.rs
index 6385d873..3310515c 100644
--- a/crates/benilla-ui/src/script/pet.rs
+++ b/crates/benilla-ui/src/script/pet.rs
@@ -1,33 +1,16 @@
-//! The pet action bar seam (decision 0982) — the eight bindings `PetActionBarFrame.lua` consumes
-//! (`GetPetActionInfo`/`GetPetActionsUsable`/`GetPetActionCooldown`/`PetHasActionBar`/
-//! `CastPetAction`/`TogglePetAutocast`/`IsPetAttackActive`/`PetStopAttack`) over an app-pushed
-//! slot snapshot, in [`super::shapeshift`]'s two-way shape: the app resolves everything (which
-//! slot is a command, a reaction or a spell; its icon, name, checked and autocast bits; its
-//! cooldown) and pushes it ([`super::UiScript::set_pet_actions`]); the engine drains the click
-//! intents ([`super::UiScript::take_pet_actions`] and kin) back out.
-//!
-//! **The engine holds no pet knowledge**: a slot here is "a name, a subtext, a texture, four bits
-//! and a cooldown triple". In particular it does not know that a token slot's `name`/`texture` are
-//! *the names of globals* rather than values — that convention belongs to the reference's own
-//! `GetPetActionInfo` and is reproduced faithfully by the app, which sets `is_token` and lets the
-//! Lua do the `getglobal` (the shipped `PetActionBarFrame.lua:98-104` fork).
-//!
-//! Return conventions are the 1.12 API's own, matching [`super::action`]: 1/nil booleans, and the
-//! cooldown as `(start_s on the GetTime clock, duration_s, enable)` with the same
-//! elapsed-goes-cold rule `GetActionCooldown` uses.
-//!
-//! Two later families joined the bar's eight through the same two-way seam, because they are about
-//! the same unit and move on the same push: the **hunter stat block** ([`PetStats`], decision 1005)
-//! that the pet paper doll and the happiness icon read, and the **right-click menu**
-//! (`PetCanBeAbandoned`/`PetCanBeRenamed`/`PetAbandon`/`PetDismiss`/`PetRename`, decision 1066).
+//! The pet bindings: the action bar `PetActionBarFrame.lua` drives, the stat block the pet frames
+//! read, and the pet menu's predicates and verbs. The app resolves every slot and pushes it
+//! ([`super::UiScript::set_pet_actions`]); presses queue back out for the app to send. A token
+//! slot's name and texture are the names of globals, which the stock Lua resolves
+//! (`PetActionBarFrame.lua:98-104`). Booleans are 1/nil and cooldowns go cold once elapsed, as in
+//! [`super::action`].
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-// The slot-word bytes the one-shot orders synthesize — the same values
-// `benilla_protocol::messages::pet` names for the wire (the engine stays protocol-free, 0068 §3,
-// so they are restated here rather than imported): the type byte, then the command / reaction.
+// The slot-word values the one-shot orders synthesize, restated from
+// `benilla_protocol::messages::pet` because this crate does not depend on the protocol.
 const PET_ACT_COMMAND: u8 = 0x07;
 const PET_ACT_REACTION: u8 = 0x06;
 const PET_COMMAND_STAY: u32 = 0;
@@ -37,184 +20,110 @@ const PET_REACT_PASSIVE: u32 = 0;
 const PET_REACT_DEFENSIVE: u32 = 1;
 const PET_REACT_AGGRESSIVE: u32 = 2;
 
-/// A synthesized slot word: the type byte in the top byte, the action in the low bits — the
-/// server's own packing (`PetActionEntry`).
+/// A slot word as the server packs it: the type in the top byte, the action in the low bits.
 const fn order(kind: u8, action: u32) -> u32 {
     (kind as u32) << 24 | action
 }
 
-/// One pet bar slot, fully resolved by the app before pushing.
+/// One pet bar slot, resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PetActionView {
-    /// `GetPetActionInfo`'s first return, and the slot's OCCUPANCY test — `None` hides the button
-    /// (`PetActionBarFrame.lua:122-128`). For a spell slot this is the spell's name; for a token
-    /// slot it is **the name of a global** (`"PET_ACTION_ATTACK"`), which the Lua resolves.
+    /// `GetPetActionInfo`'s first return and the occupancy test: `None` hides the button
+    /// (`PetActionBarFrame.lua:122-128`). The spell's name, or for a token the name of a global.
     pub name: Option<String>,
-    /// The second return — the spell's rank line, or `None` for a token.
+    /// The second return: the spell's rank line, `None` for a token.
     pub subtext: Option<String>,
-    /// The third return: an icon path for a spell, **the name of a global**
-    /// (`"PET_ATTACK_TEXTURE"`) for a token. `None` leaves the button art empty and swaps its
-    /// NormalTexture to the unfilled `UI-Quickslot`.
+    /// The third return: an icon path, or for a token the name of a global.
     pub texture: Option<String>,
-    /// Is this a command/reaction token (so `name`/`texture` are global names)?
+    /// A command or reaction token, whose `name` and `texture` are global names.
     pub is_token: bool,
-    /// The slot's spell, when it has one — what `GameTooltip:SetPetAction` renders. `None` for a
-    /// token and for an empty slot. Not a `GetPetActionInfo` return: the reference's tooltip
-    /// channel reaches the pet spellbook itself, and this is that reach.
+    /// The slot's spell, for `GameTooltip:SetPetAction`; not a `GetPetActionInfo` return.
     pub spell_id: Option<u32>,
     /// The checked ring.
     pub active: bool,
-    /// This slot CAN autocast — the static `UI-AutoCastableOverlay` ring.
+    /// The slot can autocast: the static `UI-AutoCastableOverlay` ring.
     pub autocast_allowed: bool,
-    /// …and it currently does — the sparkle trail.
+    /// Autocast is on: the sparkle trail.
     pub autocast_enabled: bool,
-    /// Whether a left click on this slot means "call the pet off" rather than "do this"
-    /// (`IsPetAttackActive`, the Attack button's second press).
+    /// `IsPetAttackActive`: a left click calls the pet off instead of running the slot.
     pub attack_active: bool,
-    /// `(start_ms on the GetTime clock, duration_ms, enabled)` — [`super::action::ActionState`]'s
-    /// exact shape; `None` = no cooldown.
+    /// `(start_ms on the GetTime clock, duration_ms, enabled)`, as [`super::action::ActionState`].
     pub cooldown: Option<(i64, u32, bool)>,
-    /// **The slot's packed word, verbatim** — the one place this seam's "the engine holds no pet
-    /// knowledge" rule bends, and deliberately (decision 1010).
-    ///
-    /// The drag ([`super::cursor::pet`]) is word arithmetic in the reference and cannot be
-    /// anything else: `0x4bc9a0` compares occupants under `& 0x3FFFFFFF`, tests a candidate's low
-    /// 16 bits, and **writes the source word through unchanged** — `0x4bce00` forwards the cursor's
-    /// payload dword without reading a field of it, and the payload itself is only ever a verbatim
-    /// copy of a word that already existed in a slot. There is no drop-time encoding to model, so
-    /// re-deriving a word from `(kind, action, bits)` at the engine boundary would be inventing one.
-    ///
-    /// `0` is the empty slot, which is also the reference's own test (the zero dword).
+    /// The slot's packed word, verbatim, for the drag ([`super::cursor::pet`]): the reference
+    /// compares occupants under `& 0x3FFFFFFF` and writes the source word through unchanged
+    /// (`0x4bc9a0`, `0x4bce00`). `0` is the empty slot.
     pub packed: u32,
-    /// `Attributes & 0x40` (`SPELL_ATTR_PASSIVE`) for a spell slot — the drop core's one source
-    /// filter (`0x4bc9f8`–`0x4bca2e`: a type-1 source whose `SpellRec+0x18 & 0x40` is set is
-    /// refused, silently). False for a token and for an empty slot.
+    /// `SPELL_ATTR_PASSIVE` (`Attributes & 0x40`) on a spell slot: the drop silently refuses a
+    /// passive source (`0x4bc9f8`-`0x4bca2e`).
     pub passive: bool,
 }
 
-/// [`PetActionView`] as stored: the cooldown converted to the `GetTime` clock at push time (the
-/// [`super::shapeshift::StoredShapeshiftForm`] pattern).
+/// [`PetActionView`] as stored, its cooldown converted to `GetTime` seconds at push time.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct StoredPetAction {
     pub(crate) view: PetActionView,
-    /// `(start_s, duration_s, enabled)` in `GetTime` seconds; `None` = no cooldown.
     pub(crate) cooldown: Option<(f64, f64, bool)>,
 }
 
-/// The hunter-pet stat block behind `GetPetHappiness`/`GetPetLoyalty`/`GetPetTrainingPoints`/
-/// `GetPetExperience` and `HasPetUI`'s second return (decision 1005; wow-re §11b), plus the two
-/// **family**-derived answers `UnitCreatureFamily("pet")` and `GetPetFoodTypes()` (decision 1062).
-///
-/// **The four stat bindings share one gate** — `0x6116e0(pet)`, "is this a hunter's pet" — which is
-/// why they share one pushed struct: a warlock's imp resolves perfectly well and still answers
-/// nothing, because happiness, loyalty and training points are hunter machinery.
-///
-/// **The two family fields sit on OPPOSITE sides of that gate, and the split is carved.**
-/// [`Self::family`] is outside it — `UnitCreatureFamily 0x51a310` has no class test, so a warlock
-/// minion shows "Imp" and gating it would blank a line the reference fills. [`Self::food_types`] is
-/// inside it — `GetPetFoodTypes 0x4bea10` shares `0x6116e0` with the four stats.
-///
-/// **The stat failure conventions differ, and the difference is the API.** `GetPetLoyalty` fails to
-/// **nil**; the two pairs fail to **`(0, 0)` — numbers, not nil**; `GetPetHappiness` fails to
-/// **`(nil, 100.0, 0.0)`**, nil in the first slot and numbers in the other two. `PetFrame.lua`
-/// hides the happiness icon on `not happiness` alone, so collapsing any of these into a uniform
-/// nil-everything would hide the frame in cases the reference shows it.
+/// The pet stat block: the four hunter stat bindings and `HasPetUI`'s second return
+/// (`0x4be670`), plus the family word, icon and diet. The stats share one hunter-pet gate
+/// (`0x6116e0`) and fail their own ways: loyalty to nil, the pairs to `(0, 0)`, happiness to
+/// `(nil, 100.0, 0.0)`. The family word has no gate (`0x51a310`); the diet shares the stats'.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PetStats {
-    /// `HasPetUI`'s second return — the hunter-pet discriminator. False makes every field below
-    /// answer its own failure convention regardless of what is in it.
+    /// `HasPetUI`'s second return; false makes every gated binding answer its failure form.
     pub hunter_pet: bool,
-    /// `GetPetHappiness`'s first return: the **pre-bucketed** `0..=3`. `None` is the gate
-    /// failure's nil; `Some(0)` is a real answer and must stay distinguishable from it.
+    /// `GetPetHappiness`'s first return, bucketed `0..=3` by the client; `Some(0)` is not nil.
     pub happiness: Option<u32>,
-    /// Return 2 — the damage percentage, already scaled by the client's own `100.0f`.
+    /// Return 2: the damage percentage, already scaled by 100.
     pub damage_percentage: f32,
-    /// Return 3 — the loyalty rate, unscaled and possibly negative.
+    /// Return 3: the loyalty rate, unscaled and possibly negative.
     pub loyalty_rate: f32,
-    /// `GetPetLoyalty`'s single return — the `PetLoyalty.dbc` name, verbatim including the shipped
-    /// `"(Loyalty Level N) "` prefix. `None` = nil (level 0, or off the table).
+    /// `GetPetLoyalty`: the `PetLoyalty.dbc` name verbatim, `"(Loyalty Level N) "` prefix included.
     pub loyalty: Option<String>,
-    /// `GetPetTrainingPoints` → `(totalPoints, spent)`, high word first.
+    /// `GetPetTrainingPoints`: `(totalPoints, spent)`, high word first.
     pub training_points: (u16, u16),
-    /// `GetPetExperience` → `(currXP, nextXP)`.
+    /// `GetPetExperience`: `(currXP, nextXP)`.
     pub experience: (u32, u32),
-    /// `UnitCreatureFamily("pet")` — the localized `CreatureFamily.dbc` word ("Imp", "Wind
-    /// Serpent"), read from the cached creature-query record (`0x51a310`: `[[unit+0xb30]+0x1c]` →
-    /// column `8 + locale`). Exactly **one** return on every path.
-    ///
-    /// `None` is the binding's **nil**, and the reference reaches it four ways that all mean "no
-    /// word to print": no cached record yet (the creature query is still in flight), family id `0`,
-    /// an id past the table, and — the one nobody guesses — **a null row in the middle of the id
-    /// space**: 10/13/14/18/22 have no row in the shipped file, so this is a lookup miss, never a
-    /// bounds check. The page guards its whole level-line `SetText` on this
-    /// (ref `PetPaperDollFrame.lua:68-70`), so nil renders no line rather than a half one.
+    /// `UnitCreatureFamily("pet")`: the localized `CreatureFamily.dbc` word off the cached creature
+    /// record (`0x51a310`). `None` is nil: no record yet, id 0, or an id with no row (10, 13, 14,
+    /// 18 and 22 have none). `PetPaperDollFrame.lua:68-70` guards its level line on it.
     pub family: Option<String>,
-    /// `GetPetIcon()` — the pet's icon path, from the family row's own `CreatureFamily.dbc` icon
-    /// column (`Interface\\Icons\\Ability_Hunter_Pet_<Family>` for all 22 shipped families). A pet
-    /// has no item behind it, so this column is the only icon there is. `None` = nil, on the same
-    /// four lookup-miss paths as [`Self::family`], which is why it sits beside it.
-    ///
-    /// **Outside the hunter gate, like [`Self::family`] and unlike [`Self::food_types`] — and that
-    /// placement is INFERRED, not carved** (decision 1676). `GetPetIcon 0x4beb10` is registered
-    /// adjacent to both in the same table (wow-re §11b's neighbour list) and has not been read.
-    /// It is grouped with the family word because it is a pure family-row lookup like that one,
-    /// where the diet's gate is shared with the four *stat* bindings. The choice is unobservable
-    /// in the reference's own call sites — every one of them (`PetStable.lua:51`, `161-162`) sits
-    /// downstream of the window's own warlock early-return — so a warlock can never reach it there
-    /// either way; only an addon could tell the difference.
+    /// `GetPetIcon()`: the family row's `CreatureFamily.dbc` icon, `None` on the family word's
+    /// misses. Ungated like the family word; whether the reference gates it (`0x4beb10`) is
+    /// untraced, and no warlock reaches its stock callers (`PetStable.lua:51`, `161-162`).
     pub icon: Option<String>,
-    /// `GetPetFoodTypes()` — the localized diet names the family's pet-food mask selects, in
-    /// **record order** (`0x4bea10`: bit `1 << (recordID - 1)` against `CreatureFamily` column 7,
-    /// the name from `ItemPetFood` column `1 + locale`). Varargs; the client returns the count and
-    /// **never a nil**, so empty is zero values rather than one nil.
-    ///
-    /// **Empty is a real answer**, and it has two independent causes: a family whose mask is `0`
-    /// (every warlock minion), and the binding's own `0x6116e0` gate — owner-is-me *and* the local
-    /// player is a Hunter — which a charmed beast under a non-hunter fails even though its family
-    /// row has a mask. The app applies that gate; this field is what it produced.
+    /// `GetPetFoodTypes()`: the diet names the family's food mask selects, in record order
+    /// (`0x4bea10`: bit `1 << (id - 1)` of `CreatureFamily` column 7, names from `ItemPetFood`).
+    /// Empty for a zero mask (every warlock minion) or a failed hunter gate, which the app applies.
     pub food_types: Vec<String>,
 }
 
-/// The pet bar's pushed state: the slots plus the two bar-wide bits the reference exposes
-/// separately from them.
+/// The pushed pet state: the bar's slots and bar-wide bits, the stat block, the menu predicates.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct PetBarState {
-    /// `PetHasActionBar()` — is there a bar at all. Distinct from "the slot list is empty": a
-    /// possessed minion has a bar of pure commands, and a bar of ten empty slots is still a bar.
+    /// `PetHasActionBar()`: there is a bar, even one of ten empty slots.
     pub(crate) has_bar: bool,
-    /// `GetPetActionsUsable()` — false desaturates every icon on the bar at once.
+    /// `GetPetActionsUsable()`: false desaturates the whole bar.
     pub(crate) actions_usable: bool,
     pub(crate) slots: Vec<StoredPetAction>,
-    /// `HasPetUI`'s FIRST return — "there is a pet with a UI at all", which the reference derives
-    /// from the pet resolving plus its `UNIT_FIELD_PETNUMBER` being nonzero (`0x4be697`). Separate
-    /// from `has_bar`: the action bar's gate is the cached guid alone, with no pet-number test.
+    /// `HasPetUI`'s first return: a pet with a nonzero `UNIT_FIELD_PETNUMBER` (`0x4be697`). Not
+    /// `has_bar`, whose gate is the cached guid alone.
     pub(crate) has_ui: bool,
     pub(crate) stats: PetStats,
-    /// May the bar be **rearranged** — `PickupPetAction`'s own gate, and nobody else's
-    /// (`0x4be1c1`: `[[pet+0x110]+0xA3] & 1 == 0`, i.e. `UNIT_FLAG_POSSESSED` clear).
-    ///
-    /// A third bar-wide bit rather than a fold into `actions_usable`, because the reference is
-    /// deliberate about keeping them apart: possession is expressly **not** among the flags that
-    /// grey the bar (a possessed unit is exactly the case where the buttons must still work), and
-    /// the crowd-control flags that do grey it do **not** block a drag. Two gates, two questions.
-    ///
-    /// It sits before the cursor fork, so it blocks the DROP as well as the pick-up.
+    /// `PickupPetAction`'s gate, `UNIT_FLAG_POSSESSED` clear (`0x4be1c1`), which blocks the drop
+    /// as well as the pick-up. Not `actions_usable`: possession does not grey the bar, and the
+    /// flags that grey it do not block a drag.
     pub(crate) pickup_allowed: bool,
-    /// `PetCanBeAbandoned()` — **the pet right-click menu's whole fork** (decision 1066).
-    ///
-    /// Three of the PET menu's four rows show only when this is true (paperdoll, rename, abandon)
-    /// and the fourth — Dismiss — shows only when it is *false* (`UnitPopup.lua:402-417`). So it is
-    /// not "am I allowed to abandon"; it is "is this a pet I keep rather than a summon I called",
-    /// and it is what makes one menu read *Abandon* on a hunter's pet and *Dismiss* on a demon.
+    /// `PetCanBeAbandoned()`: a kept pet rather than a summon. It forks the pet menu: paperdoll,
+    /// rename and abandon show when true, dismiss only when false (`UnitPopup.lua:402-417`).
     pub(crate) can_be_abandoned: bool,
-    /// `PetCanBeRenamed()` — an independent predicate, ANDed with the one above for the rename row
-    /// alone. One-shot server-side: a hunter pet carries it only until its first rename.
+    /// `PetCanBeRenamed()`, ANDed with the above for the rename row; set until the first rename.
     pub(crate) can_be_renamed: bool,
 }
 
 impl super::UiScript {
-    /// Push the whole pet bar, replacing whatever was there. A bare setter — firing
-    /// `PET_BAR_UPDATE` is the app's diff-and-fire job, mirroring `set_shapeshift_forms`.
+    /// Push the whole pet bar; the app diffs and fires `PET_BAR_UPDATE`.
     pub fn set_pet_actions(
         &mut self,
         has_bar: bool,
@@ -222,10 +131,7 @@ impl super::UiScript {
         pickup_allowed: bool,
         slots: Vec<PetActionView>,
     ) {
-        // Field-by-field, never `pet_bar = PetBarState { .. }`: the struct also holds state that
-        // moves on OTHER clocks (the stat block, the menu predicates), and rebuilding it wholesale
-        // meant every one of those had to be hand-carried across this assignment or be silently
-        // reset once a frame. Assigning what this setter owns cannot forget them.
+        // Field by field: the stat block and the menu predicates beside them move on other clocks.
         let bar = &mut self.model_mut().pet_bar;
         bar.has_bar = has_bar;
         bar.actions_usable = actions_usable;
@@ -233,8 +139,7 @@ impl super::UiScript {
         bar.slots = slots
             .into_iter()
             .map(|view| {
-                // The cooldown arrives with its absolute start already on the `GetTime` clock
-                // (ms) — storing is a pure unit conversion, `set_shapeshift_forms`' seam.
+                // The start is already on the `GetTime` clock, in ms.
                 let cooldown = view.cooldown.map(|(start_ms, duration_ms, enabled)| {
                     (
                         start_ms as f64 / 1000.0,
@@ -247,28 +152,22 @@ impl super::UiScript {
             .collect();
     }
 
-    /// Push the hunter-pet stat block ([`PetStats`]) — the four paper-doll bindings plus
-    /// `HasPetUI`. Separate from [`Self::set_pet_actions`] because it changes on a different clock:
-    /// `SMSG_PET_SPELLS` replaces the bar wholesale, but happiness moves every few seconds off a
-    /// plain descriptor field, so tying the two together would make the bar's diff-and-fire churn
-    /// on a number no button draws.
+    /// Push the stat block and `HasPetUI`'s first return, which move on descriptor updates rather
+    /// than with the bar.
     pub fn set_pet_stats(&mut self, has_ui: bool, stats: PetStats) {
         let bar = &mut self.model_mut().pet_bar;
         bar.has_ui = has_ui;
         bar.stats = stats;
     }
 
-    /// Push the right-click menu's two predicates (decision 1066) — a third clock again, the pet's
-    /// own `UNIT_FIELD_FLAGS`, which the rename's one-shot bit moves independently of both.
+    /// Push the menu's two predicates, which move with the pet's `UNIT_FIELD_FLAGS`.
     pub fn set_pet_menu(&mut self, can_be_abandoned: bool, can_be_renamed: bool) {
         let bar = &mut self.model_mut().pet_bar;
         bar.can_be_abandoned = can_be_abandoned;
         bar.can_be_renamed = can_be_renamed;
     }
 
-    /// Drain the 1-based slot indices `CastPetAction` queued since the last call. What each index
-    /// *means* on the wire (a command, a reaction, a cast) is the app's to decide at drain time
-    /// from the slot it still owns.
+    /// Drain the 1-based slots `CastPetAction` queued; the app decides what each one sends.
     pub fn take_pet_actions(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().pet_actions_pressed)
     }
@@ -278,34 +177,29 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().pet_autocast_toggles)
     }
 
-    /// Drain the `PetStopAttack()` calls queued (a count — the verb carries no argument).
+    /// Drain the count of `PetStopAttack()` calls.
     pub fn take_pet_stop_attacks(&mut self) -> u32 {
         std::mem::replace(&mut self.model_mut().pet_stop_attacks, 0)
     }
 
-    /// Drain the pet one-shot orders (`PetAttack` & co.), each a packed slot word (1958).
+    /// Drain the one-shot orders (`PetAttack` and the rest), each a packed slot word.
     pub fn take_pet_orders(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().pet_orders)
     }
 
-    /// `HasFullControl`'s flag, from the host's control edge (`ui_unit::feed_player_control`).
+    /// Set the flag `HasFullControl` answers.
     pub fn set_player_control(&mut self, in_control: bool) {
         self.model_mut().player_control = in_control;
     }
 
-    /// Drain the pet bar writes the drag queued (decision 1010) — **one `Vec` per
-    /// `CMSG_PET_SET_ACTION`**, each of one or two `(0-based position, packed word)` pairs.
-    ///
-    /// Already-applied on the engine's side: the app's job is to mirror each pair into its own
-    /// authoritative ten words and put the batch on the wire whole. Flattening the batches would
-    /// break the server's body-size fork between the one- and two-entry forms.
+    /// Drain the drag's bar writes, already applied here: one `Vec` per `CMSG_PET_SET_ACTION` of
+    /// one or two `(0-based position, packed word)` pairs. Send each whole: the server tells the
+    /// two forms apart by body size.
     pub fn take_pet_set_actions(&mut self) -> Vec<Vec<(u32, u32)>> {
         std::mem::take(&mut self.model_mut().pet_set_actions)
     }
 
-    /// Drain the `PetAbandon()` and `PetDismiss()` calls queued, as `(abandons, dismisses)` —
-    /// counts, since neither verb carries an argument. Kept apart for the reason on the model's
-    /// fields: two bindings, not one, whatever they end up sharing on the wire.
+    /// Drain the `PetAbandon()` and `PetDismiss()` call counts, as `(abandons, dismisses)`.
     pub fn take_pet_gives_up(&mut self) -> (u32, u32) {
         let m = &mut *self.model_mut();
         (
@@ -320,7 +214,7 @@ impl super::UiScript {
     }
 }
 
-/// The 1-based button index → stored slot, the reference's own indexing.
+/// The stored slot at a 1-based button index.
 fn slot_at(model: &Model, i: u32) -> Option<&StoredPetAction> {
     usize::try_from(i.checked_sub(1)?)
         .ok()
@@ -333,7 +227,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     let flag = |b: bool| if b { Value::Integer(1) } else { Value::Nil };
 
-    // PetHasActionBar() → 1/nil. The bar frame's whole show/hide gate.
     g.set(
         "PetHasActionBar",
         lua.create_function(move |lua, ()| {
@@ -342,7 +235,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetActionsUsable() → 1/nil — one answer for the whole bar (the SetDesaturation sweep).
     g.set(
         "GetPetActionsUsable",
         lua.create_function(move |lua, ()| {
@@ -351,9 +243,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetActionInfo(i) → name, subtext, texture, isToken, isActive, autoCastAllowed,
-    // autoCastEnabled. An out-of-range index answers a single nil, which the Lua's `if (name)`
-    // occupancy test reads exactly as an empty slot (the spellbook bindings' shape).
+    // An out-of-range index answers a single nil, which the Lua reads as an empty slot.
     g.set(
         "GetPetActionInfo",
         lua.create_function(move |lua, i: u32| {
@@ -378,9 +268,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetActionCooldown(i) → start, duration, enable — GetActionCooldown's triple and its
-    // elapsed-goes-cold rule (an elapsed/absent cooldown answers (0, 0, 1) so a re-feed never
-    // replays the sweep).
+    // An elapsed or absent cooldown answers (0, 0, 1), so a re-feed never replays the sweep.
     g.set(
         "GetPetActionCooldown",
         lua.create_function(|lua, i: u32| {
@@ -395,14 +283,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsPetAttackActive(i) → a BOOLEAN — the left-click fork: true means the press should call
-    // the pet OFF (`PetStopAttack`) instead of running the slot.
-    //
-    // The odd one out of this file's returns, and deliberately so: it is the single pet binding
-    // that pushes a real Lua boolean (`0x6f39f0`) rather than the 1/nil the rest use, so it
-    // answers `false`, never nil, even out of range. Consumers only ever test it for truth, so
-    // the difference is invisible in use — but a seam that quietly upgraded it to the house
-    // convention would be lying about the API.
+    // The one pet binding that answers a real boolean (`0x6f39f0`), `false` even out of range.
     g.set(
         "IsPetAttackActive",
         lua.create_function(move |lua, i: u32| {
@@ -411,9 +292,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CastPetAction(i) — queue the press. An EMPTY slot queues nothing: the reference's bar hides
-    // an unnamed button, so a press on one can only come from the show-grid state, where it must
-    // be inert.
+    // An empty slot, whose button shows only under show-grid, queues nothing; the reference sends
+    // its zero word (`0x4bd230` falls to the send at `0x4bd444`), which vmangos ignores
+    // (`PetHandler.cpp:178`).
     g.set(
         "CastPetAction",
         lua.create_function(|lua, i: u32| {
@@ -425,8 +306,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // TogglePetAutocast(i) — queue the right-click. Only a slot that CAN autocast queues: the
-    // wire verb names a spell id, and a command token has none.
+    // Only a slot that can autocast queues: the wire verb names a spell, and a token has none.
     g.set(
         "TogglePetAutocast",
         lua.create_function(|lua, i: u32| {
@@ -438,9 +318,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasPetUI() → hasUI, isHunterPet — ALWAYS exactly two returns (`EAX=2` on every path of
-    // `0x4be670`), with `(nil, nil)` when there is no pet with a UI. The second return is the
-    // gate every stat binding below shares.
+    // Two returns on every path (`0x4be670`), `(nil, nil)` with no pet UI.
     g.set(
         "HasPetUI",
         lua.create_function(move |lua, ()| {
@@ -450,13 +328,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetHappiness() → happiness, damagePercentage, loyaltyRate.
-    //
-    // The client thresholds; Lua does not. Return 1 is a PRE-BUCKETED 0..3 read off
-    // PetPersonality.dbc's three columns, and `0` is a real bucket that answers the NUMBER 0 —
-    // `PetFrame.lua` hides the icon on `not happiness`, and a 0 leaves it showing with whatever
-    // texcoords it had. Only the gate failure is nil, and even then returns 2 and 3 are the
-    // numbers (100.0, 0.0), never nil.
+    // The client buckets return 1 off `PetPersonality.dbc` (`0x4be900`), and bucket 0 is the
+    // number 0; only the gate failure is nil, and even then returns 2 and 3 are `(100.0, 0.0)`.
     g.set(
         "GetPetHappiness",
         lua.create_function(move |lua, ()| {
@@ -479,8 +352,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetLoyalty() → the localized level name, or NIL. The one stat binding whose failure is
-    // nil rather than a number — level 0 (no loyalty yet) included.
+    // The one stat binding that fails to nil, level 0 included.
     g.set(
         "GetPetLoyalty",
         lua.create_function(move |lua, ()| {
@@ -493,8 +365,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetTrainingPoints() → totalPoints, spent — the two halves of one packed dword, HIGH word
-    // first. Numbers on every path: a gate failure is (0, 0), not nil.
+    // The high then low word of one packed dword; a gate failure is (0, 0), not nil.
     g.set(
         "GetPetTrainingPoints",
         lua.create_function(move |lua, ()| {
@@ -509,8 +380,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetExperience() → currXP, nextXP. Numbers on every path, like the pair above; the client
-    // converts both `fild qword` off a zero-extended dword, so neither can arrive negative.
+    // Numbers on every path; the client reads both unsigned, so neither is negative.
     g.set(
         "GetPetExperience",
         lua.create_function(move |lua, ()| {
@@ -521,25 +391,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCreatureFamily(unit) → the localized family word, or NIL. Exactly ONE return on every
-    // path (`0x51a310`, wow-re-VERIFIED) — decision 1062.
-    //
-    // **Scoped to the `"pet"` token, and that narrowing is stated rather than hidden.** The real
-    // binding resolves any unit and reads `[[unit+0xb30]+0x1c]` off its cached creature-query
-    // record, so `UnitCreatureFamily("target")` on a wild boar answers "Boar" there and nil here —
-    // INTERIM, exactly the shape `UnitDefense`'s non-player answer took in 1057. The pet page is
-    // the only consumer in the shipped FrameXML, and a pet is the one unit whose record we cannot
-    // reach through `guid::entry` (its guid slot holds a pet number, not a template id), so the pet
-    // feed resolves it explicitly and the other tokens wait for a second consumer — at which point
-    // this moves onto `UnitState` beside `creature_type_name`.
-    //
-    // Note there is NO class gate here: a warlock's imp answers "Imp". That is the carved shape,
-    // and it is what makes the family word and `GetPetFoodTypes` below behave differently for the
-    // same pet.
-    //
-    // All four of the reference's nil paths arrive as one pushed `None` — no cached record, id 0,
-    // id past the table, and a null row (ids 10/13/14/18/22 are absent from the shipped file). A
-    // missing or absent token is nil too, through the same match.
+    // One return on every path, with no class gate (`0x51a310`). Answers the `"pet"` token only:
+    // the reference resolves any unit off its cached creature record (`[[unit+0xb30]+0x1c]`), so
+    // a wild boar's `"target"` answers "Boar" there and nil here. The pet page is the only stock
+    // caller.
     g.set(
         "UnitCreatureFamily",
         lua.create_function(move |lua, token: Option<String>| {
@@ -554,10 +409,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetIcon() → the pet's icon path, or NIL. One return. The stable window reads it both as a
-    // predicate ("is there a current pet?", `PetStable.lua:51`) and as the texture itself (`161`),
-    // so the nil must be a real nil rather than an empty string — `SetItemButtonTexture` would
-    // happily take "" and a path resolving to nothing draws WHITE (decision 1046).
+    // A real nil, never "": the stable reads it as a predicate and as a texture
+    // (`PetStable.lua:51`, `161-162`), and an empty path would draw white.
     g.set(
         "GetPetIcon",
         lua.create_function(move |lua, ()| {
@@ -569,16 +422,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetFoodTypes() → the diet names as VARARGS, one Lua return per food type, in record
-    // order — the shape `BuildListString(GetPetFoodTypes())` needs (ref
-    // `PetPaperDollFrame.xml:269`). `0x4bea10` returns the pushed COUNT and never a nil, so the
-    // empty case is zero values.
-    //
-    // An empty diet returns NOTHING, not an empty string: the reference's `BuildListString` then
-    // reads `arg[1]` as nil and returns nil, which is the behaviour a single empty-string return
-    // would silently break. It is reachable two ways, both real — a family whose mask is 0 (every
-    // warlock minion), and the binding's own `0x6116e0` hunter gate, which the app applies before
-    // filling this list.
+    // One return per diet and never a nil (`0x4bea10`): an empty diet is zero values, for which
+    // `BuildListString` answers nil (`PetPaperDollFrame.xml:269`).
     g.set(
         "GetPetFoodTypes",
         lua.create_function(move |lua, ()| {
@@ -594,16 +439,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetStopAttack() — queue the call-off. No argument: the wire carries only the pet's guid.
-    // The six one-shot orders (`0x4be450`…`0x4be4a0`, wow-re `pet-action-bar-api.md` §10.9,
-    // carved 2026-09-03): each writes the literal slot word the bar's own reaction or command
-    // slot carries — `0x06000000`/1/2 PASSIVE/DEFENSIVE/AGGRESSIVE, `0x07000000`/1/2
-    // WAIT/FOLLOW/ATTACK — and re-enters `0x4bd1d0`, the identical call a `CastPetAction` press
-    // makes, PetAttack with the current selection's guid as a bar ATTACK click would. No
-    // arguments, no returns; the no-pet gate is silent, so a session without a pet bar has
-    // nothing to order and drops it, as the bar's own press would (1958; §10.9 confirmed the
-    // reading, including that a target-less PetAttack raises the bar press's own `ERR_ATTACK_*`
-    // after its auto-acquire — that leg is the drain's, shared with the press).
+    // The six one-shot orders (`0x4be450`..`0x4be4a0`) each write the slot word the bar's own
+    // reaction or command slot carries and re-enter `0x4bd1d0`, as a `CastPetAction` press does;
+    // PetAttack takes the current selection. With no pet bar the order is silently dropped.
     for (name, packed) in [
         ("PetPassiveMode", order(PET_ACT_REACTION, PET_REACT_PASSIVE)),
         (
@@ -639,12 +477,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The right-click menu (decision 1066) ─────────────────────────────────────────────────
-    // Two predicates that decide what the PET menu SHOWS, and three verbs it can pick. The
-    // predicates are 1/nil like the rest of this file, which is all `UnitPopup.lua` needs — every
-    // one of its four uses is a bare `not PetCanBeAbandoned()` or an AND of the two.
+    // ── The pet menu ─────────────────────────────────────────────────────────
 
-    // PetCanBeAbandoned() → 1/nil. Do not read this as "may I abandon": it forks the whole menu.
     g.set(
         "PetCanBeAbandoned",
         lua.create_function(move |lua, ()| {
@@ -653,7 +487,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetCanBeRenamed() → 1/nil. Independent of the above; the rename row wants both.
     g.set(
         "PetCanBeRenamed",
         lua.create_function(move |lua, ()| {
@@ -662,7 +495,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetAbandon() — the ABANDON_PET popup's OnAccept, i.e. the confirmed permanent one.
+    // The `ABANDON_PET` popup's OnAccept, after its confirm.
     g.set(
         "PetAbandon",
         lua.create_function(|lua, ()| {
@@ -672,8 +505,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetDismiss() — the menu row itself, with NO confirm in front of it (`UnitPopup.lua:590`
-    // calls it directly, unlike abandon). Nothing is lost when a summon is sent away.
+    // The menu row itself, with no confirm (`UnitPopup.lua:591`).
     g.set(
         "PetDismiss",
         lua.create_function(|lua, ()| {
@@ -683,14 +515,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // PetRename(name) — the PETRENAMECONFIRM popup's OnAccept, carrying the text the RENAME_PET
-    // edit box collected.
-    //
-    // The argument reaches `lua_tostring`, so a NUMBER coerces (wow-re §11c) — `mlua::String`
-    // accepts one the same way. What the reference does with the RESULT is the app's business and
-    // is queued for it rather than dropped here: an empty name raises `ERR_NULL_PETNAME` and an
-    // over-long one is truncated, both at the send. Only a missing or unconvertible argument dies
-    // here, because there is nothing to queue.
+    // A number coerces, as `lua_tostring` does (`0x6f3690` → `0x6f7c80`); an empty or over-long
+    // name is still queued, since the reference raises `ERR_NULL_PETNAME` or truncates at send.
     g.set(
         "PetRename",
         lua.create_function(|lua, name: Option<mlua::String>| {
@@ -712,9 +538,7 @@ mod tests {
     use super::{PetActionView, PetStats};
     use crate::script::UiScript;
 
-    /// A hunter's bar, cut down to the three slot classes that matter: the Attack command (a
-    /// token, currently attacking), Claw (a spell with autocast ON and a running cooldown), and an
-    /// empty middle slot.
+    /// Attack (a token, attacking), Claw (a spell, autocasting, cooling down), an empty slot.
     fn slots() -> Vec<PetActionView> {
         vec![
             PetActionView {
@@ -748,7 +572,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return PetHasActionBar()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return GetPetActionsUsable()").unwrap(), 1);
 
-        // The token slot returns GLOBAL NAMES, and says so with isToken.
         let (name, subtext, texture, is_token, active, allowed, enabled) = s
             .eval::<(
                 String,
@@ -781,7 +604,6 @@ mod tests {
             )
         );
 
-        // The spell slot returns a real name, a rank line and an icon PATH, and is not a token.
         assert!(s
             .eval::<bool>(
                 "local n, sub, tex, tok, act, allow, on = GetPetActionInfo(2) \
@@ -790,8 +612,7 @@ mod tests {
             )
             .unwrap());
 
-        // The empty slot exists (so it is not the out-of-range single nil) but has no name — the
-        // reference's own "hide this button" test.
+        // The empty slot has returns, unlike the out-of-range single nil, but no name.
         assert!(s
             .eval::<bool>("local n, _, tex = GetPetActionInfo(3) return n == nil and tex == nil")
             .unwrap());
@@ -825,9 +646,6 @@ mod tests {
         );
     }
 
-    /// The three intent queues, and the two gates that keep a meaningless intent off the wire: an
-    /// empty slot cannot be pressed, and a slot with no autocast cannot be toggled (its wire verb
-    /// names a spell id, which a command token has not got).
     #[test]
     fn intents_queue_and_the_meaningless_ones_are_dropped() {
         let mut s = UiScript::new().unwrap();
@@ -855,11 +673,6 @@ mod tests {
         assert_eq!(s.take_pet_stop_attacks(), 0, "drain empties");
     }
 
-    /// `IsPetAttackActive` is per-slot, and it is what turns the Attack button's second press into
-    /// a call-off — the reference's `PetActionButton_OnClick` fork.
-    ///
-    /// It answers a **boolean** on every path, including out of range — the one binding here that
-    /// does not use the 1/nil convention.
     #[test]
     fn attack_active_is_a_per_slot_boolean() {
         let mut s = UiScript::new().unwrap();
@@ -871,21 +684,17 @@ mod tests {
             .unwrap());
     }
 
-    /// The right-click menu's two predicates and three verbs (decision 1066).
-    ///
-    /// The predicate half is checked the way `UnitPopup.lua` actually reads them — as the four
-    /// row conditions — because that is the only thing they are for, and getting the Dismiss row's
-    /// **inverted** sense wrong would show a hunter both Abandon and Dismiss.
+    /// The predicates are checked the way `UnitPopup.lua`'s row conditions read them.
     #[test]
     fn the_menu_predicates_fork_the_rows_and_the_verbs_queue() {
         let mut s = UiScript::new().unwrap();
 
-        // No pet pushed: every row is off, which is what keeps a menu of dead rows from opening.
+        // No pet pushed: every row is off.
         assert!(s
             .eval::<bool>("return PetCanBeAbandoned() == nil and PetCanBeRenamed() == nil")
             .unwrap());
 
-        // A hunter's freshly tamed pet: abandon/rename/paperdoll show, dismiss hides.
+        // A hunter's freshly tamed pet.
         s.set_pet_menu(true, true);
         assert_eq!(s.eval::<i64>("return PetCanBeAbandoned()").unwrap(), 1);
         assert!(
@@ -895,24 +704,21 @@ mod tests {
         );
         assert!(!s.eval::<bool>("return not PetCanBeAbandoned()").unwrap());
 
-        // The same pet after one rename — the bit is one-shot, so only the rename row goes.
+        // The same pet after one rename.
         s.set_pet_menu(true, false);
         assert!(s.eval::<bool>("return PetCanBeAbandoned() ~= nil").unwrap());
         assert!(s.eval::<bool>("return PetCanBeRenamed() == nil").unwrap());
 
-        // A warlock's demon: the fork flips whole. Dismiss is the row that shows.
+        // A warlock's demon: only Dismiss shows.
         s.set_pet_menu(false, false);
         assert!(s.eval::<bool>("return not PetCanBeAbandoned()").unwrap());
 
-        // The verbs. Abandon and dismiss are counted apart; rename carries its text.
         assert_eq!(s.take_pet_gives_up(), (0, 0));
         s.run("PetAbandon() PetDismiss() PetDismiss()").unwrap();
         assert_eq!(s.take_pet_gives_up(), (1, 2));
         assert_eq!(s.take_pet_gives_up(), (0, 0), "drain empties");
 
-        // An empty name IS queued — the reference's empty check raises `ERR_NULL_PETNAME` at the
-        // send, so swallowing it here would swallow the error with it. A number coerces
-        // (`lua_tostring`); a missing argument has nothing to queue.
+        // An empty name is queued for the send's error, a number coerces, no argument queues none.
         s.run("PetRename(\"Bruce\") PetRename(\"\") PetRename(7) PetRename()")
             .unwrap();
         assert_eq!(
@@ -922,9 +728,6 @@ mod tests {
         assert!(s.take_pet_renames().is_empty(), "drain empties");
     }
 
-    /// A bar push must not wipe the state that rides other clocks — the trap the old wholesale
-    /// `pet_bar = PetBarState { .. }` assignment set, and the reason [`UiScript::set_pet_actions`]
-    /// assigns field by field.
     #[test]
     fn pushing_the_bar_leaves_the_stats_and_the_menu_alone() {
         let mut s = UiScript::new().unwrap();
@@ -946,8 +749,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetPetHappiness()").unwrap(), 3);
     }
 
-    /// A disabled bar still EXISTS — `PetHasActionBar` stays true while `GetPetActionsUsable`
-    /// goes false. The pair is what greys every icon without taking the bar off screen.
     #[test]
     fn a_disabled_bar_is_still_a_bar() {
         let mut s = UiScript::new().unwrap();
@@ -958,14 +759,7 @@ mod tests {
             .unwrap());
     }
 
-    /// `GetPetIcon` — one return, a real nil when there is no pet. The stable window reads it BOTH
-    /// as a predicate and as the texture it passes to `SetItemButtonTexture`, so an empty string
-    /// standing in for the nil would draw a white square rather than the empty-slot art
-    /// (decision 1046's law, decision 1676's consumer).
-    /// The six one-shot orders synthesize the bar's own slot words (1958): the three reactions
-    /// as type 6 with the react byte, the three commands as type 7 with the command byte — the
-    /// same words `CastPetAction` on those slots would send. Without a bar there is nothing to
-    /// order, and none is queued.
+    /// Reactions are type 6 and commands type 7, each with its state in the low byte.
     #[test]
     fn the_pet_one_shots_synthesize_the_bars_slot_words() {
         let mut s = UiScript::new().unwrap();
@@ -992,8 +786,6 @@ mod tests {
         assert!(s.take_pet_orders().is_empty(), "drained");
     }
 
-    /// `HasFullControl()` is the host's control flag — 1 at boot, nil while a possession or fear
-    /// holds the body, 1 again after (1958).
     #[test]
     fn has_full_control_follows_the_hosts_flag() {
         let mut s = UiScript::new().unwrap();
@@ -1015,7 +807,6 @@ mod tests {
             "Interface\\Icons\\Ability_Hunter_Pet_Boar"
         );
 
-        // Exactly one return — the reference assigns it straight into a single local.
         assert_eq!(s.arity("GetPetIcon()").unwrap(), 1);
     }
 
@@ -1041,8 +832,6 @@ mod tests {
         }
     }
 
-    /// The four stat bindings on a hunter's pet — arities and values, including the pair ORDER
-    /// (`total` before `spent`, `curr` before `next`), which is the half a swap makes invisible.
     #[test]
     fn a_hunters_pet_answers_every_stat_binding() {
         let mut s = UiScript::new().unwrap();
@@ -1070,13 +859,6 @@ mod tests {
             .unwrap());
     }
 
-    /// **The failure conventions are three different shapes and the API is those shapes.** A
-    /// warlock's imp has a pet UI and is not a hunter pet: loyalty goes nil, both pairs go to
-    /// `(0, 0)` as NUMBERS, and happiness goes `(nil, 100, 0)` — nil in the first slot only.
-    ///
-    /// Flattening any of these to nil-everything breaks a different consumer: `PetFrame.lua` hides
-    /// its happiness icon on `not happiness`, but `PetPaperDollFrame` does arithmetic on the pairs
-    /// and would error on a nil.
     #[test]
     fn a_non_hunter_pet_fails_three_different_ways() {
         let mut s = UiScript::new().unwrap();
@@ -1103,15 +885,11 @@ mod tests {
         assert!(s
             .eval::<bool>("local c, n = GetPetExperience() return c == 0 and n == 0")
             .unwrap());
-        // HasPetUI still reports the UI — it is the SECOND return that discriminates.
         assert!(s
             .eval::<bool>("local ui, hunter = HasPetUI() return ui == 1 and hunter == nil")
             .unwrap());
     }
 
-    /// **Bucket 0 is a number, not nil**, and this is the trap the RE calls out by name: the
-    /// shipped `PetFrame.lua` branches on 1/2/3 and hides only on `not happiness`, so a 0 must
-    /// leave the icon up. Collapsing it into the failure path hides a frame the reference shows.
     #[test]
     fn happiness_bucket_zero_is_not_the_failure_case() {
         let mut s = UiScript::new().unwrap();
@@ -1134,8 +912,6 @@ mod tests {
         );
     }
 
-    /// With no pet at all every binding takes its failure path and `HasPetUI` answers `(nil, nil)`
-    /// — two returns on every path, never zero.
     #[test]
     fn no_pet_still_answers_two_values_from_has_pet_ui() {
         let s = UiScript::new().unwrap();
@@ -1148,21 +924,15 @@ mod tests {
             .unwrap());
     }
 
-    /// **`UnitCreatureFamily`'s nil paths — all four of them** (decision 1062). The reference
-    /// guards its whole level-line `SetText` on this binding, so an accidental `""` in place of
-    /// nil would print a bare "Level 58 " with a trailing space instead of nothing at all.
     #[test]
     fn unit_creature_family_is_nil_on_every_absent_path() {
         let mut s = UiScript::new().unwrap();
-        // 1. No pet at all — nothing has ever been pushed.
+        // No pet pushed.
         assert!(s
             .eval::<bool>(r#"return UnitCreatureFamily("pet") == nil"#)
             .unwrap());
 
-        // 2. A pet whose template carries family 0, and 3. a pet whose creature query has not
-        //    answered yet. Both arrive here as the same pushed `None` (the app resolves which is
-        //    which); what matters at this seam is that a live pet with no family word is nil and
-        //    not an empty string.
+        // Family 0 and an unanswered creature query both arrive as `None`.
         s.set_pet_stats(
             true,
             PetStats {
@@ -1180,7 +950,7 @@ mod tests {
              and print a bare 'Level 58 ' with a trailing space"
         );
 
-        // 4. Any other token: the INTERIM narrowing, stated in the binding's own comment.
+        // With a family: `"pet"` answers it, any other token nil.
         s.set_pet_stats(true, hunter_stats());
         assert_eq!(
             s.eval::<String>(r#"return UnitCreatureFamily("pet")"#)
@@ -1196,13 +966,9 @@ mod tests {
         }
     }
 
-    /// `GetPetFoodTypes` returns **varargs**, one value per diet — the shape
-    /// `BuildListString(GetPetFoodTypes())` depends on. A single comma-joined string would read
-    /// identically in the tooltip and be wrong for every other caller.
     #[test]
     fn get_pet_food_types_returns_one_value_per_diet() {
         let mut s = UiScript::new().unwrap();
-        // No pet: ZERO returns, which is what makes the ref's `BuildListString` answer nil.
         assert_eq!(s.arity("GetPetFoodTypes()").unwrap(), 0);
 
         s.set_pet_stats(true, hunter_stats());
@@ -1218,8 +984,6 @@ mod tests {
             )
             .unwrap());
 
-        // An empty diet is a real answer (every warlock family ships a zero food mask) and is
-        // still zero returns, not one empty string.
         s.set_pet_stats(
             true,
             PetStats {
@@ -1230,12 +994,7 @@ mod tests {
         assert_eq!(s.arity("GetPetFoodTypes()").unwrap(), 0);
     }
 
-    /// The family **word** answers regardless of the hunter gate — `UnitCreatureFamily 0x51a310`
-    /// has no class test at all, so a warlock's minion shows "Imp" on the page's level line while
-    /// every hunter-gated binding beside it says nothing.
-    ///
-    /// (The **diet** is the other way round — it shares `0x6116e0` — but that gate is the app's to
-    /// apply, so at this seam it is simply an empty list. `ui_pet_stats` pins the gate itself.)
+    /// The diet's hunter gate is the app's to apply, so here a non-hunter's diet is just empty.
     #[test]
     fn the_family_word_answers_for_a_non_hunter_pet() {
         let mut s = UiScript::new().unwrap();
@@ -1253,7 +1012,6 @@ mod tests {
                 .unwrap(),
             "Imp"
         );
-        // …while every hunter-gated binding still says nothing.
         assert!(s.eval::<bool>("return GetPetLoyalty() == nil").unwrap());
         assert_eq!(s.arity("GetPetFoodTypes()").unwrap(), 0);
     }
diff --git a/crates/benilla-ui/src/script/petition.rs b/crates/benilla-ui/src/script/petition.rs
index 2c42ee46..03a8e0c6 100644
--- a/crates/benilla-ui/src/script/petition.rs
+++ b/crates/benilla-ui/src/script/petition.rs
@@ -1,143 +1,86 @@
-//! The guild-charter **Era API surface** — the guild registrar and the petition window
-//! (decision 1672, **re-derived against the byte law in 1678**).
-//!
-//! [`super::guild`] is *being* in a guild; this is *founding* one, which 1257 §2 deliberately left
-//! out and named as the next slice. Fifteen registered globals across two windows (the three tabard
-//! ones are the adjacent family and are not built), and the same shape as every other domain here:
-//! the app pushes a [`PetitionState`] snapshot ([`UiScript::set_petition`]) and the getters read
-//! that plain data; every verb queues a [`PetitionRequest`] the app drains
-//! ([`UiScript::take_petition_requests`]). No ECS or net reach from the engine (decision 0068 §3).
-//!
-//! Every contract below is **VERIFIED at the bytes** — wow-re
-//! `system/ui/scratch/petition-charter-api.md`, a §5 round commissioned by this slice, which carved
-//! the whole `PetitionInfo.cpp` TU (`0x84cfb8`). Where it corrected what this file first shipped,
-//! the correction is named on the binding.
-//!
-//! **The snapshot mirrors the module's own `.data` state, and that is why it looks split.** The
-//! real client keeps the signature list (`[0xbdce20]` + the `0x10`-stride signer array) and the
-//! cached `CGPetition` record (`[0xbdce28]`) as two independent things, because the bindings read
-//! them independently: `GetNumPetitionNames`/`GetPetitionNameInfo` answer off the *packet's* list
-//! while `GetPetitionInfo` answers off the *record*, and either can exist without the other. So
-//! [`PetitionState`] carries them separately rather than as one "is the window open" struct — a
-//! collapsed model cannot express `CanSignPetition`'s no-record leg below, and gets it wrong.
-//!
-//! **This client has no `lua_pushboolean`.** Every predicate is the number `1` or `nil`
-//! (`0x6f3810` / `0x6f37f0`), and a name the `NameCache` has not resolved is **`nil`**, not `""`.
-//!
-//! **`PETITION_SHOW` is deferred, which is what makes the partial states below unreachable in
-//! practice.** The event fires only when no signer name is still resolving *and* the record has
-//! arrived (`0x4f419b`-`0x4f41ad`), so the window never paints a blank title or a blank row. The
-//! deferral lives app-side in `crate::ui_petition`; the getters here still answer honestly at any
-//! moment, because an addon may call them whenever it likes.
+//! The guild-charter globals of the guild registrar and the petition window. The snapshot keeps
+//! the signer list (`[0xbdce20]`) and the cached `CGPetition` record (`[0xbdce28]`) apart, as the
+//! reference does, since the bindings read them independently. Predicates are `1` or nil (no
+//! `lua_pushboolean`: `0x6f3810`, `0x6f37f0`) and an unresolved name is nil. `PETITION_SHOW` waits
+//! for every signer name and the record (`0x4f419b`), a deferral `crate::ui_petition` owns.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// `GetPetitionInfo`'s first return when the record's `"charter"` bit is SET — `0x84cf8c`, selected
-/// by `0x4f43fb test BYTE PTR [edi+0x1110],0x1`. The literal the reference compares against
-/// (`PetitionFrame.lua:22`).
+/// `GetPetitionInfo`'s first return when the record's charter bit is set (`0x84cf8c`, selected at
+/// `0x4f43fb`): the literal `PetitionFrame.lua:21` compares against.
 pub const PETITION_TYPE_CHARTER: &str = "charter";
 
-/// …and when it is clear — `0x84b8f8`. **Reachable**, not dead: the bit is the record's own, so a
-/// server that sent a non-charter petition would land here, and `CanSignPetition`'s guild-membership
-/// and full-charter refusals are *both* gated on the same bit. 1.12 servers only ever send charters,
-/// which is why the reference's `else` arm merely writes the bare word.
+/// `GetPetitionInfo`'s first return when the charter bit is clear (`0x84b8f8`). 1.12 servers send
+/// only charters, but `CanSignPetition`'s guild and full-charter refusals test the same bit.
 pub const PETITION_TYPE_PETITION: &str = "petition";
 
-/// The cached `CGPetition` record, as [`GetPetitionInfo`] reads it — `[0xbdce28]`'s six fields.
-///
-/// `None` on [`PetitionState::record`] is the no-record leg, which is a real state with its own
-/// return tuple; see [`GetPetitionInfo`].
+/// The cached `CGPetition` record `[0xbdce28]`, as `GetPetitionInfo` reads it; `None` in
+/// [`PetitionState::record`] is the no-record leg.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionRecordView {
-    /// [`PETITION_TYPE_CHARTER`] or [`PETITION_TYPE_PETITION`] — the record's `+0x1110` bit 0.
+    /// [`PETITION_TYPE_CHARTER`] or [`PETITION_TYPE_PETITION`], from the record's `+0x1110` bit 0.
     pub petition_type: String,
-    /// The record's inline `char[0x100]` title (`+0x10`) — the proposed guild's name.
+    /// The proposed guild's name, the record's `char[0x100]` at `+0x10`.
     pub title: String,
-    /// The record's inline `char[0x1000]` body text (`+0x110`). Empty on every 1.12 server.
+    /// The record's `char[0x1000]` body at `+0x110`; empty on every 1.12 server.
     pub body_text: String,
-    /// The record's `+0x1118`, pushed as a **signed** i32 (`fild DWORD`, not the zero-extending
-    /// `fild QWORD` the two counters use).
-    ///
-    /// **That this field is the signature cap is settled inside the binary rather than inferred
-    /// from the packet's field order**: `CanSignPetition` refuses at `0x4f4634 cmp ecx,[esi+0x1118]`
-    /// against the live signature count. It is *not* the nine name rows — see the module doc of
-    /// `crate::ui_petition`.
+    /// The record's signature cap (`+0x1118`), which `CanSignPetition` tests (`0x4f4634`), not the
+    /// nine name rows; pushed signed (`fild DWORD`).
     pub max_signatures: i32,
-    /// The owner's name through the `NameCache` — **`nil` when uncached** (`0x4f446d`), never `""`.
+    /// The owner's name from the `NameCache`, nil while uncached (`0x4f446d`), never `""`.
     pub originator: Option<String>,
-    /// Whether the active player's guid equals the record's owner (`0x4f447a`/`0x4f4481`).
+    /// Whether the active player owns the record (`0x4f447a`, `0x4f4481`).
     pub is_originator: bool,
 }
 
-/// What the two charter windows read — the module's `.data` state, in the same three pieces.
+/// What the two charter windows read, mirroring the reference module's `.data` state.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct PetitionState {
-    /// `GetGuildCharterCost()` — showlist **entry\[0\]**'s fourth dword (`[0xbdce50]`), in copper.
-    ///
-    /// **Unsigned**, because the binding pushes it through the `fild QWORD` idiom with the high
-    /// dword forced to zero (`0x4f5245`): a negative `charterCost` on the wire surfaces in Lua as
-    /// ~4.29e9, not as a negative number. `0` before any showlist has arrived, and after the
-    /// world-enter clear.
-    ///
-    /// That it is **copper** is settled without going through the UI: `0x4f50ed` compares this cell
-    /// directly against `PLAYER_FIELD_COINAGE` and refuses with `ERR_NOT_ENOUGH_MONEY`.
+    /// `GetGuildCharterCost()`: showlist entry 0's cost (`[0xbdce50]`) in copper, which `0x4f50ed`
+    /// compares against `PLAYER_FIELD_COINAGE`. Unsigned, as the binding zero-extends it
+    /// (`0x4f5245`), so a negative wire cost reads ~4.29e9; 0 before any showlist.
     pub charter_cost: u32,
-    /// The open petition's signers in wire order, each resolved through the `NameCache` — `None`
-    /// where the name has not landed. Its length is `GetNumPetitionNames()`, which counts
-    /// **signatures only**: the petition's owner is not among them.
-    ///
-    /// Independent of [`Self::record`] on purpose (module doc): the packet fills this, the cache
-    /// fills that, and the bindings read one each.
+    /// The signers in wire order, `None` until the `NameCache` resolves one; filled by the packet,
+    /// apart from [`Self::record`]. `GetNumPetitionNames()` counts these, never the owner.
     pub signers: Vec<Option<String>>,
-    /// The cached record, or `None` — the no-record leg.
+    /// The cached record; `None` is the no-record leg.
     pub record: Option<PetitionRecordView>,
-    /// `CanSignPetition()`, computed app-side because three of its four refusals need state the
-    /// engine does not hold. See [`PetitionState::can_sign`]'s own note in `crate::ui_petition`;
-    /// the shape to remember here is that **it is `1` when nothing is open at all**.
+    /// `CanSignPetition()`, computed app-side as three of its four refusals need state the engine
+    /// lacks; it is `1` with nothing open, as in the reference.
     pub can_sign: bool,
 }
 
-/// A charter intent queued from Lua, drained by the app into its send.
-///
-/// **Almost every one is fire-and-forget, and that is the wire's shape**: buying is answered only by
-/// the item appearing, offering is answered to the *target*, and a refusal comes back on the guild
-/// family's own error channel. Nothing here may update local state optimistically.
+/// A charter intent queued from Lua for the app to send. Most get no answer of their own (a
+/// purchase shows only as the item, an offer answers the target, a refusal comes on the guild error
+/// channel), so none may update local state optimistically.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum PetitionRequest {
-    /// `BuyGuildCharter(name)` — the registrar's Purchase button, **after** the name passed
-    /// [`validate_guild_name`]. The app supplies the NPC guid from the latched registrar, which is
-    /// the petition module's own `[0xbdceb0]` and *not* `CGGameUI`'s interaction pair.
+    /// `BuyGuildCharter(name)`, after [`validate_guild_name`]; the app adds the registrar NPC
+    /// latched at `[0xbdceb0]`, not `CGGameUI`'s interaction pair.
     Buy(String),
-    /// `TurnInGuildCharter()` — no argument. The app scans the bags, because the real client does
-    /// (`0x5ef2b0`, and it latches nothing: it re-scans on every call).
+    /// `TurnInGuildCharter()`: the app scans the bags on every call, as the reference does
+    /// (`0x5ef2b0`).
     TurnIn,
-    /// `CloseGuildRegistrar()` — **sends nothing of its own**, VERIFIED by a closure walk over
-    /// `0x4f5010` that finds no `CDataStore` build and no send, with this TU's own four sends as
-    /// the positive control.
+    /// `CloseGuildRegistrar()`: sends nothing (`0x4f5010`).
     CloseRegistrar,
-    /// `SignPetition([n])` — the optional argument is a **byte on the wire** and defaults to `1`
-    /// (`0x4f46d9`), not to `0`. vmangos skips it, so only a golden can tell the difference.
+    /// `SignPetition([n])`: a wire byte defaulting to 1, not 0 (`0x4f46d9`); vmangos skips it.
     Sign(i8),
-    /// `OfferPetition()` — no argument; the app resolves the **current target** (`CGGameUI`'s
-    /// *selection* pair, not its interaction pair) and runs the eight guards.
+    /// `OfferPetition()`: the app resolves the current target (`CGGameUI`'s selection pair, not its
+    /// interaction pair) and runs the eight guards.
     Offer,
-    /// `RenamePetition(name)` — after [`validate_guild_name`].
+    /// `RenamePetition(name)`, after [`validate_guild_name`].
     Rename(String),
-    /// `ClosePetition()` — **and this one can put bytes on the wire.** `0x4f3f60`'s decline leg
-    /// sends `MSG_PETITION_DECLINE` whenever a petition was open, no sign is in flight, a record is
-    /// cached, and we are **not** its owner. The app decides that; the verb just says "close".
+    /// `ClosePetition()`: `0x4f3f60` sends `MSG_PETITION_DECLINE` when a petition was open, no sign
+    /// is in flight, a record is cached and we do not own it; the app decides.
     ClosePetition,
-    /// A name the client itself refused ([`validate_guild_name`]) — carries the GlobalStrings key
-    /// of the message to show. **No packet is built**: the real client's validator runs before the
-    /// send and emits through the message catalog on its own.
+    /// A name [`validate_guild_name`] refused, with the GlobalStrings key to show; no packet.
     NameRefused(&'static str),
 }
 
 impl super::UiScript {
-    /// Push the charter snapshot, replacing whatever was there. A bare setter — firing the four
-    /// events on their edges (and *deferring* `PETITION_SHOW`) is the app's job.
+    /// Replace the charter snapshot; the app fires the four events and defers `PETITION_SHOW`.
     pub fn set_petition(&mut self, state: PetitionState) {
         self.model_mut().petition = state;
     }
@@ -147,19 +90,10 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().petition_requests)
     }
 
-    /// Drop any queued close intent, reporting how many went — **the close-intent consumption
-    /// decision 0096 named**, and the one thing a window switch cannot work without.
-    ///
-    /// Firing `PETITION_CLOSED` runs the frame's `OnHide` synchronously, and that handler calls
-    /// `ClosePetition()`, which queues a close. On a *switch* — a charter offered to us while ours
-    /// is open — the feed fires `PETITION_CLOSED` then `PETITION_SHOW` for the new charter, and the
-    /// close queued by the first would be drained onto the session the second just opened: the new
-    /// charter's window flashes and shuts. **And here it would also put a `MSG_PETITION_DECLINE` on
-    /// the wire for a charter we did not decline**, which is the sharper reason it must go.
-    ///
-    /// It cannot eat a *user's* close by mistake, and the ordering is what guarantees that rather
-    /// than a flag: the feed runs `before(UiInput)`, so a click's own `OnHide` queues its close
-    /// after this has already run.
+    /// Drop the queued close intents, returning how many. Firing `PETITION_CLOSED` runs `OnHide`,
+    /// whose `ClosePetition()` queues a close; on a switch to a newly offered charter that close
+    /// would shut the new window and decline it on the wire. A user's close survives, as the feed
+    /// runs `before(UiInput)` and a click's `OnHide` queues after this.
     pub fn drop_petition_close_intents(&mut self) -> usize {
         let requests = &mut self.model_mut().petition_requests;
         let before = requests.len();
@@ -172,40 +106,18 @@ impl super::UiScript {
         before - requests.len()
     }
 
-    /// Queue one charter intent directly — the test seam.
+    /// Queue one charter intent directly: the test seam.
     #[cfg(test)]
     pub fn queue_petition_request(&mut self, request: PetitionRequest) {
         self.model_mut().petition_requests.push(request);
     }
 }
 
-/// The client-side guild-name check `BuyGuildCharter` and `RenamePetition` **share** — `0x4f5160`,
-/// which runs the name through the locale-aware string checker `0x6c9b70` and maps its code to one
-/// of seven messages, accepting **only** code `0xd`. `Ok(())` is that acceptance; `Err(key)` is the
-/// GlobalStrings key of the line to show, and **no packet is built**.
-///
-/// **Partial, deliberately, and here is exactly how far it goes.** The code space belongs to
-/// `0x6c9b70`, which that round did not carve, so only the checks whose meaning is unambiguous from
-/// the message keys are implemented — empty, a leading or trailing space, and consecutive spaces.
-/// The three that need data we do not have (`ERR_GUILD_NAME_TOO_SHORT`'s minimum,
-/// `ERR_GUILD_NAME_PROFANE`'s word list, `ERR_GUILD_NAME_MIXED_LANGUAGES`' script rules) **pass**
-/// rather than guess: refusing a name the server would have accepted is the worse failure, and the
-/// server re-checks every one of them anyway (`ObjectMgr::IsValidCharterName`). What this buys over
-/// sending blindly is the case the reference makes loudest and the server answers with silence —
-/// clicking Purchase with an empty box.
-///
-/// The full table, from the note, with what each maps to:
-///
-/// | code | key | implemented |
-/// |---|---|---|
-/// | 0 | `ERR_GUILD_ENTER_NAME` | **yes** — the empty string |
-/// | 1 | `ERR_GUILD_NAME_TOO_SHORT` | no — the minimum is inside `0x6c9b70` |
-/// | 4 | `ERR_GUILD_NAME_MIXED_LANGUAGES` | no |
-/// | 5 | `ERR_GUILD_NAME_PROFANE` | no |
-/// | 6 | `ERR_GUILD_NAME_RESERVED` | no |
-/// | 10 | `ERR_GUILD_NAME_INVALID_SPACE` | **yes** — a leading or trailing space |
-/// | 11 | `ERR_GUILD_NAME_NAME_CONSECUTIVE_SPACES` | **yes** |
-/// | 2,3,7,8,9,>0xb | `ERR_GUILD_NAME_INVALID` | no |
+/// The guild-name check `BuyGuildCharter` and `RenamePetition` share (`0x4f5160`), which maps the
+/// checker `0x6c9b70`'s code to a message and accepts only `0xd`; `Err` carries the GlobalStrings
+/// key to show, and no packet is built. Only codes 0 (empty), 10 (an edge space) and 11
+/// (consecutive spaces) are built; the rest pass, as the checker's rules are untraced and the
+/// server re-checks every name (`ObjectMgr::IsValidCharterName`).
 pub fn validate_guild_name(name: &str) -> Result<(), &'static str> {
     if name.is_empty() {
         return Err("ERR_GUILD_ENTER_NAME");
@@ -219,7 +131,7 @@ pub fn validate_guild_name(name: &str) -> Result<(), &'static str> {
     Ok(())
 }
 
-/// 1.12's `1`/`nil`, never `true`/`false` — this client has no `lua_pushboolean`.
+/// 1.12's `1` or nil, never `true`/`false`: this client has no `lua_pushboolean`.
 fn era_bool(on: bool) -> Value {
     if on {
         Value::Integer(1)
@@ -228,7 +140,7 @@ fn era_bool(on: bool) -> Value {
     }
 }
 
-/// A cached name pushes as a string; an uncached one pushes **nil**.
+/// A cached name as a string, an uncached one as nil.
 fn name_value(lua: &Lua, name: Option<&String>) -> mlua::Result<Value> {
     match name {
         Some(n) => Ok(Value::String(lua.create_string(n)?)),
@@ -241,14 +153,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
     // ── The petition window ──────────────────────────────────────────────────────────────────
-    // GetPetitionInfo() (`0x4f43d0`) — **exactly six values on BOTH legs** (`mov eax,0x6` at
-    // `0x4f4493` and `0x4f44d4`), in the order the reference destructures them
-    // (`PetitionFrame.lua:10`).
-    //
-    // The no-record leg is NOT "return nothing": it is `nil, nil, nil, 0, nil, nil`, with the
-    // fourth pushed as the *number* zero (`0x4f44b4 push 0; push 0; call 0x6f3810`). This file
-    // first shipped an empty return, which reads identically through the reference's own
-    // destructure and differently to anything that counts its arguments.
+    // GetPetitionInfo() (`0x4f43d0`): six values on both legs (`0x4f4493`, `0x4f44d4`), in the
+    // order `PetitionFrame.lua:9` destructures them; with no record, `nil, nil, nil, 0, nil, nil`,
+    // the fourth the number 0 (`0x4f44b4`).
     g.set(
         "GetPetitionInfo",
         lua.create_function(|lua, ()| {
@@ -274,9 +181,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumPetitionNames() (`0x4f44e0`, 44 bytes — one field read) — `[0xbdce20]`, pushed
-    // UNSIGNED. It counts **signatures only**; the owner is painted separately by the window and is
-    // never in this list.
+    // GetNumPetitionNames() (`0x4f44e0`): `[0xbdce20]`, unsigned; signatures only, never the owner.
     g.set(
         "GetNumPetitionNames",
         lua.create_function(|lua, ()| {
@@ -285,13 +190,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPetitionNameInfo(index) (`0x4f4510`) — **1-based** (`0x4f4569 dec eax`), one value on
-    // every leg. The bound test `0x4f456c jae` is UNSIGNED, so index `< 1` wraps to `0xffffffff`
-    // and fails the same comparison — which is why a zero or negative index answers nil rather
-    // than the last row. An uncached name is **nil**, not `""`.
-    //
-    // A non-numeric argument is `luaL_error("Usage: GetPetitionNameInfo(index)")`, which longjmps;
-    // mlua's coercion raises for us on the same input, so the shape is preserved.
+    // GetPetitionNameInfo(index) (`0x4f4510`): 1-based, one value on every leg. The bound test is
+    // unsigned (`0x4f456c`), so 0 or a negative index wraps and answers nil. A non-numeric
+    // argument raises, through mlua's coercion as through the reference's `Usage:`.
     g.set(
         "GetPetitionNameInfo",
         lua.create_function(|lua, index: i64| {
@@ -307,13 +208,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CanSignPetition() (`0x4f45e0`) — the Sign button's only gate.
-    //
-    // **It returns `1` with NO petition open**, and that is the reference's own asymmetry rather
-    // than a reading error: `0x4f45f7 je 0x4f4655` jumps past the three record-dependent refusals
-    // straight into the signer scan, over an array the close path has already zeroed. A client that
-    // treats this as a sufficient precondition lets the user click Sign with nothing to sign — so
-    // the window's own `isOriginator` branch is what actually keeps the button off screen.
+    // CanSignPetition() (`0x4f45e0`), the Sign button's only gate, is `1` with no petition open:
+    // `0x4f45f7` jumps past the three record refusals into a scan of the zeroed signer array. The
+    // window's `isOriginator` branch is what hides the button.
     g.set(
         "CanSignPetition",
         lua.create_function(|lua, ()| {
@@ -323,7 +220,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The registrar window ─────────────────────────────────────────────────────────────────
-    // GetGuildCharterCost() (`0x4f5230`) — copper, unsigned, `0` before any showlist.
+    // GetGuildCharterCost() (`0x4f5230`): copper, unsigned, 0 before any showlist.
     g.set(
         "GetGuildCharterCost",
         lua.create_function(|lua, ()| {
@@ -333,8 +230,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The verbs ────────────────────────────────────────────────────────────────────────────
-    // The four that carry nothing and push nothing. None may touch the snapshot: none of them is
-    // acknowledged, so a local update would show a charter as signed that the server refused.
+    // The four that carry and push nothing; none may touch the snapshot, which the server owns.
     for (global, request) in [
         ("TurnInGuildCharter", PetitionRequest::TurnIn),
         ("CloseGuildRegistrar", PetitionRequest::CloseRegistrar),
@@ -351,10 +247,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // SignPetition([n]) (`0x4f46d0`) — the argument is OPTIONAL and rides the wire as a byte,
-    // defaulting to **1**, not 0 (`0x4f46d9 edi = 1`, `0x4f4749 Put8`). The server skips the byte,
-    // so nothing observable depends on it — which is exactly why it is easy to ship as 0 and never
-    // find out.
+    // SignPetition([n]) (`0x4f46d0`): the optional argument rides the wire as a byte defaulting to
+    // 1, not 0 (`0x4f46d9`, `0x4f4749 Put8`); the server skips it.
     g.set(
         "SignPetition",
         lua.create_function(|lua, n: Option<f64>| {
@@ -366,10 +260,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BuyGuildCharter(guildName) (`0x4f5260`) — **returns the number `1` or `nil`**, and what it
-    // reports is NAME VALIDITY, not that a packet was sent: `0x4f5294` runs the shared validator and
-    // only its non-zero return reaches the action, which then has five silent refusals of its own.
-    // Nothing in the shipped FrameXML reads the return; an addon can.
+    // BuyGuildCharter(guildName) (`0x4f5260`) returns 1 or nil for name validity, not for a send:
+    // `0x4f5294` runs the shared validator, and the action behind it has five silent refusals.
     g.set(
         "BuyGuildCharter",
         lua.create_function(|lua, name: String| {
@@ -389,11 +281,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RenamePetition(name) (`0x4f4930`) — **0 values**, the SAME validator, and silent on refusal
-    // beyond the validator's own message. (Its usage string is literally
-    // `Usage(RenamePetition("name")` in the binary — Blizzard's own unbalanced parenthesis. It is
-    // unreachable from our binding, which raises through mlua's coercion instead, and is recorded
-    // here rather than reproduced.)
+    // RenamePetition(name) (`0x4f4930`): zero values, the same validator, silent beyond its
+    // message. A bad argument raises mlua's coercion error; the reference's usage string is
+    // `Usage(RenamePetition("name")`, unbalanced.
     g.set(
         "RenamePetition",
         lua.create_function(|lua, name: String| {
@@ -467,13 +357,6 @@ mod tests {
         );
     }
 
-    /// **The no-record leg is six values, not none** — `nil, nil, nil, 0, nil, nil`, with the
-    /// fourth the *number* zero.
-    ///
-    /// This file first shipped an empty return, which the reference's own six-way destructure
-    /// cannot tell apart (both give six nils… except the fourth, which is `0` here and `nil`
-    /// there). The COUNT is what separates them — [`UiScript::arity`] — and it is the whole point
-    /// of the test.
     #[test]
     fn the_no_record_leg_is_six_values_with_a_numeric_zero() {
         let s = UiScript::new().unwrap();
@@ -496,8 +379,7 @@ mod tests {
         );
     }
 
-    /// The name list is 1-based and bounded, an uncached name is **nil**, and the count excludes
-    /// the owner. The zero/negative cases matter because the binary's bound test is *unsigned*.
+    /// The zero and negative indices matter because the reference's bound test is unsigned.
     #[test]
     fn petition_names_are_one_based_and_uncached_reads_nil() {
         let mut s = UiScript::new().unwrap();
@@ -536,8 +418,7 @@ mod tests {
         }
     }
 
-    /// `CanSignPetition()` is era-boolean **and answers `1` with nothing open** — the reference's
-    /// own asymmetry, pinned so nobody "fixes" it into a nil.
+    /// The `1` with nothing open is the reference's own asymmetry, not a bug to fix.
     #[test]
     fn can_sign_petition_answers_one_with_nothing_open() {
         let s = UiScript::new().unwrap();
@@ -559,7 +440,6 @@ mod tests {
         );
     }
 
-    /// The cost is copper, unsigned, and belongs to the registrar rather than to any petition.
     #[test]
     fn charter_cost_is_unsigned_copper_and_the_registrars() {
         let mut s = UiScript::new().unwrap();
@@ -569,7 +449,7 @@ mod tests {
         });
         assert_eq!(s.eval::<i64>("return GetGuildCharterCost()").unwrap(), 1000);
 
-        // A negative wire cost surfaces as ~4.29e9, not as a negative — the `fild QWORD` idiom.
+        // A negative wire cost reads ~4.29e9: the binding zero-extends it (`fild QWORD`).
         s.set_petition(PetitionState {
             charter_cost: (-1i32) as u32,
             ..PetitionState::default()
@@ -583,7 +463,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetGuildCharterCost()").unwrap(), 0);
     }
 
-    /// `SignPetition`'s optional argument rides the wire as a byte and **defaults to 1**.
     #[test]
     fn sign_petition_defaults_its_wire_byte_to_one() {
         let mut s = UiScript::new().unwrap();
@@ -600,8 +479,7 @@ mod tests {
         );
     }
 
-    /// `BuyGuildCharter` reports **name validity** as `1`/`nil`, and a refused name queues its
-    /// message instead of a packet. `RenamePetition` shares the validator and returns nothing.
+    /// A refused name queues its message instead of a packet.
     #[test]
     fn the_name_validator_gates_both_verbs_and_only_buy_reports_it() {
         let mut s = UiScript::new().unwrap();
@@ -633,8 +511,6 @@ mod tests {
         );
     }
 
-    /// The validator's three implemented codes, and — just as load-bearing — the names it lets
-    /// through rather than guessing at.
     #[test]
     fn the_validator_refuses_only_what_it_can_prove() {
         assert_eq!(validate_guild_name(""), Err("ERR_GUILD_ENTER_NAME"));
@@ -650,9 +526,8 @@ mod tests {
             validate_guild_name("Legacy  of Steel"),
             Err("ERR_GUILD_NAME_NAME_CONSECUTIVE_SPACES")
         );
-        // Passed through on purpose: the minimum length, the profanity list and the script rules
-        // all live inside a function that round did not carve, and refusing a name the server would
-        // accept is the worse failure. The server re-checks every one of them.
+        // Passed through: the length, profanity and script rules live in the untraced `0x6c9b70`,
+        // and the server re-checks them.
         for ok in ["Legacy of Steel", "A", "Ab", "Éclair", "x y z"] {
             assert_eq!(
                 validate_guild_name(ok),
@@ -662,8 +537,6 @@ mod tests {
         }
     }
 
-    /// The close-intent consumption removes exactly the two close verbs and preserves the order of
-    /// everything else.
     #[test]
     fn dropping_close_intents_leaves_the_other_verbs_untouched() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/pointer.rs b/crates/benilla-ui/src/script/pointer.rs
index 418222fc..3239e0af 100644
--- a/crates/benilla-ui/src/script/pointer.rs
+++ b/crates/benilla-ui/src/script/pointer.rs
@@ -1,48 +1,11 @@
-//! Pointer input dispatch: hit-testing and the mouse-move/-button/-wheel entry points that turn
-//! host pointer events into FrameScript handler calls (decision 0068). The pipeline is
-//! **hit-test → hover → click/drag**:
+//! Pointer input dispatch: the hit test, and the mouse move, button and wheel entry points that
+//! turn host pointer events into FrameScript handler calls. [`cursor`] owns the payload and
+//! gesture state; this file dispatches.
 //!
-//! - [`UiScript::hit_test`] answers "what's under `(x, y)`" — the topmost-drawn, mouse-enabled,
-//!   effective-visible frame whose resolved rect (and effective ScrollFrame clip, decision 0112
-//!   §5) contains the point. Pure query; fires nothing, mutates nothing.
-//! - [`UiScript::mouse_move`] hit-tests every move and, on a captured-frame **change**, fires the
-//!   `OnLeave`/`OnEnter` pair (RF-0025's `motion=true` hover boundary) — and, before that,
-//!   advances an armed drag gesture, an in-flight **Slider thumb drag**, and an in-flight
-//!   **frame move** (`StartMoving`, [`super::object`]'s `movable` cluster). All three move within
-//!   one frame, crossing no hover boundary, so they must run before the boundary test.
-//! - [`UiScript::mouse_button`] resolves `OnMouseDown`/`OnMouseUp`, the `OnClick`
-//!   press/release-registration rules ([`button::wants_click`]), the **drag trio** + **world
-//!   drop** below, the **Slider thumb-drag** capture (a left press on a thumb, decision 0250 §5),
-//!   and EditBox click-to-focus — all keyed off the same hit-test. The **double-click detector**
-//!   ([`DOUBLE_CLICK_SECS`]) rides the release edge here too: a click on a frame whose previous
-//!   click landed within 300 ms fires `OnDoubleClick` **instead of** that second `OnClick`.
-//! - [`UiScript::mouse_wheel`] fires `OnMouseWheel`, bubbling to the nearest ancestor with a
-//!   handler when the hit frame has none (a ScrollFrame under a non-scrolling child).
-//!
-//! ## The drag trio + world drop (decisions 0216 §3, corrected by 0218)
-//!
-//! A press on a [`super::Model::drag_registered`] frame **arms** a gesture ([`cursor::arm_drag`]); once
-//! the cursor crosses the drag-start threshold it **starts** (firing `OnDragStart`) — that
-//! threshold check is [`cursor::maybe_start_drag`], run from `mouse_move` on every move. A
-//! release **resolves** the gesture ([`cursor::take_drag`]): a STARTED gesture fires
-//! `OnDragStop` on the source and `OnReceiveDrag` on whatever the release hit (a no-op if that
-//! frame carries no such script), and SUPPRESSES `OnClick` for that release — an un-started
-//! gesture leaves the ordinary click path untouched. The **world drop**
-//! ([`cursor::world_drop_click`]) fires only on a completed left CLICK over the game world:
-//! press AND release both landed on **the world** ([`over_world`] — the world frame, or no frame
-//! at all where none is loaded), no drag started (the byte-verified trigger — the client's
-//! `0x495300` runs on the WorldFrame click release; a drag release routes as a drag, never a
-//! click), routed by the app-fed pick ([`super::Model::world_pick`], decisions 0571 + 0574 — an
-//! object pick keeps everything, terrain drops items only, nothing drops any arm).
-//!
-//! ## Division of labor with [`cursor`]
-//!
-//! [`cursor`] owns the payload/gesture **STATE**: [`super::Model::cursor`] (what the cursor
-//! carries), [`super::Model::drag`] (the in-flight gesture), and the pure functions that
-//! arm/advance/resolve them. This file owns the input **DISPATCH** — turning raw
-//! `(x, y, button, down)` host events into a hit-test plus the right sequence of Lua handler
-//! calls, calling into `cursor`'s state machine at the right points rather than touching
-//! [`super::Model::drag`]/[`super::Model::cursor`] directly.
+//! A frame captures the cursor when it is mouse-enabled and effective-visible and its rect and
+//! effective ScrollFrame clip hold the point (the reference's probe `0x76b020`), taking the first
+//! in the order of the hover walk (`0x7661cd` in `0x7660d0`), which [`crate::order::hit_test`]
+//! implements.
 
 use mlua::Value;
 
@@ -53,41 +16,14 @@ use crate::widget::{ButtonState, FrameHandle};
 use super::clip::{effective_clip, scroll_clip_sources};
 use super::{button, cursor, editbox, event, Model, UiScript};
 
-/// The double-click interval — **300 ms, VERIFIED off the bytes**, a hardcoded instruction
-/// immediate: `0x77937b  81 f9 2c 01 00 00  cmp ecx, 0x12c`, comparing `now − [this+0x334]` inside
-/// the Button mouse-UP dispatcher `0x7792d0` (wow-re `ui/scratch/button-doubleclick-law.md`, a §5
-/// cross-check dispatched from here).
-///
-/// The units are verified too, not assumed: `now` comes from `0x42c010` → `0x42b790`, whose
-/// scale is stored as `1.0/freq × 1000.0` and whose counter is `KERNEL32!GetTickCount` (import
-/// `[0x7ff310]`) — milliseconds either way.
-///
-/// **What it is NOT**, because all three were live hypotheses and each is closed at the bytes:
-/// it is not the OS setting (`CS_DBLCLKS` is never requested — all four `RegisterClassExA` sites
-/// pass `style = 0x20` = `CS_OWNDC` alone — and `GetDoubleClickTime` is not imported), it is not a
-/// CVar (no such `.rdata` string; nothing near the compare reaches `CVar::Register 0x63db90`), and
-/// there is **no position gate** (the `0x766122`–`0x766140` "double-click detector" this was first
-/// chased through is really the zero-motion cursor-move coalescing filter — that gloss in
-/// `world-click-drag-arbitration.md` l.238 is refuted and corrected). The only spatial constraint
-/// is that each release hit-tests inside the frame, applied independently; the two clicks may land
-/// arbitrarily far apart.
-///
-/// So the interval does not follow the host OS double-click speed and the player cannot change it.
+/// The double-click interval, 300 ms, a constant in the Button mouse-up dispatcher `0x7792d0`
+/// (`0x77937b cmp ecx, 0x12c` on the `0x42c010` millisecond clock). It is not the OS double-click
+/// time (`GetDoubleClickTime` is not imported) and not a CVar, and there is no distance limit:
+/// each release only has to hit the frame.
 pub(super) const DOUBLE_CLICK_SECS: f64 = 0.300;
 
-// ── Input / hit-testing (decision 0068; spec-faithful, not byte-pinned) ─────────────────────
-//
-// The mouse-focus model (`propagation.md`): focus walks frames top-down in reverse draw order;
-// the first mouse-enabled, effective-visible frame whose resolved rect contains the cursor
-// captures. This is faithful to the *documented model*, **not** bit-exact — the real hit-test
-// leaf is a flagged RE-time item, not byte-pinned (`anchors.md`; see [`crate::order::hit_test`]).
-// Coordinates are WoW UI space (y-up, pixels) — the same space [`resolve`]/[`extract`] use.
-// Call [`resolve`] first so rects are populated; a frame with no resolved rect never captures.
-
-/// Install the pointer-adjacent Lua globals: `GetCursorPosition()` → the model's live cursor in
-/// the engine's y-up UI space (fed by the host's mouse_move/mouse_button) — what the ref's
-/// `MouseIsOver`/FCF hover logic reads (1.12 returns UI-scaled coords; benilla's UI space is
-/// 1:1 logical px, so no scale factor applies).
+/// Install `GetCursorPosition()` and `GetMouseFocus()`. The cursor is in UI units, as 1.12
+/// answers it; the engine's y-up UI space is 1:1 logical pixels, so no scale factor applies.
 pub(super) fn install(lua: &mlua::Lua) -> mlua::Result<()> {
     lua.globals().set(
         "GetCursorPosition",
@@ -97,23 +33,14 @@ pub(super) fn install(lua: &mlua::Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `GetMouseFocus()` — the frame the mouse is over, or nil.
-    //
-    // **The corpus's most-wanted engine verb**: 78 of 218 addons call it (decision 1195). Every
-    // tooltip scanner, every "what am I hovering" helper and every mouseover-macro library is this
-    // one call. It is a pure read of the hover state [`UiScript::mouse_move`] already maintains —
-    // `Model::mouseover`, the frame that owns the `OnEnter`/`OnLeave` boundary — so the answer is
-    // exactly the frame whose `OnEnter` last fired, which is what an addon means by "focus".
-    //
-    // Returns the frame's **wrapper table**, not its name: the reference returns a frame object and
-    // callers immediately write `GetMouseFocus():GetName()`.
+    // `GetMouseFocus()` (`0x48df40`): the hover frame `[root+0x7c]`, a disabled Button included, as
+    // its frame object (not its name), or nil.
     lua.globals().set(
         "GetMouseFocus",
         lua.create_function(|lua, ()| {
             let id = {
                 let mut model = lua.app_data_mut::<super::Model>().expect("model app_data");
-                // Re-check liveness: a frame can be destroyed between the hover and this call, and
-                // handing back a wrapper for a dead handle is worse than answering nil.
+                // A frame destroyed since the hover answers nil.
                 model
                     .mouseover
                     .filter(|&h| model.arena.frame(h).is_some())
@@ -128,11 +55,8 @@ pub(super) fn install(lua: &mlua::Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Whether `h` is the world frame — the one frame whose mouse hits belong to the 3D world
-/// (decisions 1983/1984, `worldframe-widget.md`: "the hover walk probes strata 8→0 and the world
-/// frame wins exactly when nothing else mouse-enabled is under the cursor; the press runs the
-/// frame's Lua `OnMouseDown` (never consuming), then the `BUTTON1`/`BUTTON2` binding — which
-/// **is** the world click; the release mirrors it").
+/// Whether `h` is the world frame, whose mouse hits belong to the 3D world; it wins the hover walk
+/// only when nothing else mouse-enabled is under the cursor.
 fn is_world_handle(model: &Model, h: FrameHandle) -> bool {
     model
         .arena
@@ -140,21 +64,13 @@ fn is_world_handle(model: &Model, h: FrameHandle) -> bool {
         .is_some_and(|f| f.kind == crate::widget::FrameKind::WorldFrame)
 }
 
-/// Whether a press/release target is **the world** rather than the UI — the predicate the world
-/// drop is gated on, and the one thing decision 1983 silently changed the meaning of.
-///
-/// Before the stock `WorldFrame` joined the manifest (1983, 2026-09-04) the world was simply
-/// *where no frame is*, and this was spelled `hit.is_none()` throughout. The stock file anchors a
-/// mouse-enabled frame over the whole screen, so from that day every world click hit a frame and
-/// the world drop stopped firing — B380 (decision 2089). The world frame IS the reference's click
-/// target for a world click, so it answers **yes** here; `None` still answers yes too, because a
-/// harness with no `WorldFrame.xml` loaded (most tests, an install-less checkout) has nothing
-/// under the cursor at all and means the same thing by it.
+/// Whether a press or release target is the world: the world frame, the reference's world click
+/// target, or no frame where `WorldFrame.xml` is not loaded (most tests).
 fn over_world(model: &Model, target: Option<FrameHandle>) -> bool {
     target.is_none_or(|h| is_world_handle(model, h))
 }
 
-/// Whether `(x, y)` falls inside one of this frame's hyperlink spans — the engine half of the
+/// Whether `(x, y)` falls inside one of this frame's hyperlink spans, the engine half of the
 /// reference's per-span `CSimpleHyperlinkButton` children.
 fn link_span_hit(model: &Model, fh: FrameHandle, x: f32, y: f32) -> bool {
     model
@@ -164,24 +80,8 @@ fn link_span_hit(model: &Model, fh: FrameHandle, x: f32, y: f32) -> bool {
 }
 
 impl UiScript {
-    /// Hit-test the cursor at `(x, y)` and return the **handle** of the captured frame (the
-    /// topmost-drawn mouse-enabled, effective-visible frame whose rect contains the point **and**
-    /// whose effective ScrollFrame clip, if any, also contains it — decision 0112 §5: a button
-    /// scrolled out of its ScrollFrame's rect must not hit), or `None`. Pure query — fires nothing,
-    /// mutates nothing. Call [`Self::resolve`] first; a frame with no resolved rect never captures.
-    ///
-    /// **The handle form exists because a name is not always available and an id is not always
-    /// comparable.** [`Self::hit_test`] answers in ids (what the app and the Lua bindings speak) and
-    /// [`Self::hit_test_name`] answers in names (what a human reads). An instrument that has to ask
-    /// *whose* frame ate a click needs neither: the frame may be **anonymous**, and the only set it
-    /// can be checked against is a handle set snapshotted earlier ([`Self::live_targets`]'s). The
-    /// addon harness's use probe asks exactly that — a pointer event is only an addon's to be
-    /// judged by when the frame under the cursor is one the addon itself created.
-    /// Whether a frame id names a [`FrameKind::WorldFrame`] — the reference's world frame, whose
-    /// mouse hits belong to the 3D world (decisions 1983/1984). The hit test still answers it (it
-    /// is mouse-enabled by construction, so an addon's `OnEnter`/`OnMouseDown` on it fire — the
-    /// reference runs those, then the click's `BUTTON1`/`BUTTON2` binding, which IS the world
-    /// click), but the app's pointer arbiter does not count it as being over the UI.
+    /// Whether a frame id names the world frame: hit-tested like any frame, so scripts on it fire,
+    /// but not counted by the app as over the UI.
     pub fn is_world_frame(&self, id: u32) -> bool {
         let model = self.model_ref();
         model
@@ -190,33 +90,21 @@ impl UiScript {
             .is_some_and(|h| is_world_handle(&model, *h))
     }
 
+    /// The handle of the frame that captures `(x, y)`, for a caller that checks it against a
+    /// handle set taken earlier (an anonymous frame has no name). Needs [`Self::resolve`] first.
     pub fn hit_test_frame(&self, x: f32, y: f32) -> Option<FrameHandle> {
         let model = self.model_ref();
         let sorted = order::traversal(&model.arena);
         let scroll_sources = scroll_clip_sources(&model);
         order::hit_test(&sorted, |fh| {
-            // Mouse-enabled, **or inside one of this frame's hyperlink spans**.
-            //
-            // That second half is how the reference makes a chat link clickable on a frame that
-            // takes no mouse at all. `CSimpleMessageScrollFrame`'s ctor leaves `[+0xcc] = 0`, so
-            // `ChatFrame1` is never in the hit-test index — instead the engine synthesises one
-            // mouse-enabled `CSimpleHyperlinkButton` child PER SPAN (`0x7a3240`, born through the
-            // `CSimpleButton` ctor) and routes the three hyperlink scripts back to the parent
-            // (wow-re `mouse-enable-law.md` + the follow-up round `68987021`).
-            //
-            // We hold the spans as rects on the parent rather than as child frames, so the same
-            // law expresses as a disjunct here. What it buys is everything the reference gets from
-            // the split: the chat window is a hit candidate only over a LINK, so `GetMouseFocus()`
-            // answers what is behind it elsewhere, its `movable="true"` +
-            // `<TitleRegion setAllPoints="true"/>` stay inert so it drags by its tab and not its
-            // body, and a hover over plain text reassigns to whatever is underneath.
+            // Mouse-enabled, or over one of the frame's hyperlink spans. The chat frame takes no
+            // mouse (`[+0xcc] = 0`); the reference gives each span a mouse-enabled
+            // `CSimpleHyperlinkButton` child (`0x7a3240`) that routes its scripts to the parent, so
+            // a chat window hits only over a link and drags by its tab, not its body.
             (model.arena.is_mouse_enabled(fh) || link_span_hit(&model, fh, x, y))
-                // **The nameplate's own `+0x3c` veto** (`0x7cba30`): while a ground-targeted spell
-                // is armed a plate refuses the hit test *before* the rect is tested, and the point
-                // falls through to the `WorldFrame` behind it so the reticle can be placed through
-                // a plate. It is not the mouse-enabled bit — see
-                // [`super::UiScript::set_nameplate_hit_test_veto`] for why that distinction is
-                // load-bearing rather than pedantic.
+                // The nameplate's `+0x3c` veto (`0x7cba30`), not its mouse-enabled bit: while a
+                // ground-targeted spell is armed a plate refuses the hit before its rect is
+                // tested, so the reticle is placed through it.
                 && !model.nameplates.vetoes(fh)
                 && model.resolved.get(&fh).is_some_and(|r| {
                     point_in_rect(inset_rect(*r, model.arena.hit_rect_insets(fh)), x, y)
@@ -226,22 +114,15 @@ impl UiScript {
         })
     }
 
-    /// [`Self::hit_test`] over the frames that take the WHEEL — either bit, since a mouse-enabled
-    /// frame with an `<OnMouseWheel>` is a candidate for both. Same rect and clip rules; only the
-    /// enable predicate differs.
+    /// [`Self::hit_test`] over the frames that take the wheel: the same rect and clip rules, gated
+    /// on the wheel flag alone.
     fn hit_test_wheel(&self, x: f32, y: f32) -> Option<u32> {
         let model = self.model_ref();
         let sorted = order::traversal(&model.arena);
         let scroll_sources = scroll_clip_sources(&model);
         let fh = order::hit_test(&sorted, |fh| {
-            // **The wheel gates on the handler and CONTINUES** — the one genuine fall-through in
-            // the engine (wow-re `ui/scratch/hittest-no-fallthrough-law.md`). Down/up deliberately
-            // do not use the idiom; the wheel does. So this asks for the WHEEL flag alone and lets
-            // the sweep walk past a frame that merely takes the mouse, which is what puts the wheel
-            // through a scroll pane's chrome and into the pane.
-            //
-            // It used to also accept `is_mouse_enabled` as a stand-in, because the loader did not
-            // arm the wheel kind and no frame ever carried the flag. The loader arms it now.
+            // The wheel flag alone: the wheel index is separate from the mouse's, so the wheel
+            // passes a frame that only takes the mouse, as a scroll pane's chrome does.
             model.arena.is_mouse_wheel_enabled(fh)
                 && model.resolved.get(&fh).is_some_and(|r| {
                     point_in_rect(inset_rect(*r, model.arena.hit_rect_insets(fh)), x, y)
@@ -252,18 +133,13 @@ impl UiScript {
         model.frame_to_id.get(&fh).copied()
     }
 
-    /// Hit-test the cursor at `(x, y)` and return the **id** of the captured frame, or `None` —
-    /// [`Self::hit_test_frame`] with the id lookup every caller in the input path wants. The id is
-    /// the same one used across this host (e.g. the layout [`crate::layout::Handle`]); the app can
-    /// hand it back or map it as it likes.
+    /// [`Self::hit_test_frame`] as a frame id, the id the app and the Lua bindings use.
     pub fn hit_test(&self, x: f32, y: f32) -> Option<u32> {
         let hit = self.hit_test_frame(x, y)?;
         self.model_ref().frame_to_id.get(&hit).copied()
     }
 
-    /// The NAME of the frame [`Self::hit_test`] captures at `(x, y)` — the pointer twin of
-    /// [`super::UiScript::quad_owner_name`] ("who eats a click here?"), for tests and probe
-    /// tooling. `None` when nothing captures the point or the captured frame is anonymous.
+    /// The name of the frame [`Self::hit_test`] captures at `(x, y)`, for tests and probes.
     pub fn hit_test_name(&self, x: f32, y: f32) -> Option<String> {
         let id = self.hit_test(x, y)?;
         let model = self.model_ref();
@@ -271,18 +147,12 @@ impl UiScript {
         model.arena.frame(fh)?.name.clone()
     }
 
-    /// Move the cursor to `(x, y)`: hit-test, and if the captured frame **changed** since the last
-    /// move, fire `OnLeave(self, motion=true)` on the frame being left (if any and still live) and
-    /// `OnEnter(self, motion=true)` on the newly-captured frame (if any). Tracks the current
-    /// mouseover in the model. Also advances an armed [`super::Model::drag`] gesture (decision 0216 §3)
-    /// and an in-flight [`super::Model::moving`] frame ([`super::object`]'s `movable` cluster):
-    /// both run BEFORE the boundary test below, since dragging within one frame crosses no hover
-    /// boundary at all. A **DISABLED Button** takes the hover — `GetMouseFocus()` answers it — but
-    /// fires neither script ([`button::hover_notify_runs`]). Returns the captured frame id (so the app can drive
-    /// `PointerOverUi`). Handler errors are collected into [`UiScript::errors`], never panicking.
+    /// Move the cursor to `(x, y)`. When the hovered frame changes, fires `OnLeave(self, true)` on
+    /// the old one if still live and `OnEnter(self, true)` on the new; a disabled Button takes the
+    /// hover but fires neither ([`button::hover_notify_runs`]). Drags and frame moves advance
+    /// first. Returns the hovered frame id.
     pub fn mouse_move(&mut self, x: f32, y: f32) -> Option<u32> {
-        // A drag-active EditBox tracks every move (`0x77a860`): extend the selection to the
-        // hovered char, cursor following — before any hover-boundary early return.
+        // A drag-active EditBox extends its selection on every move (`0x77a860`).
         editbox::drag_update(&self.lua, x, y);
         let new_id = self.hit_test(x, y);
         #[allow(clippy::type_complexity)]
@@ -295,25 +165,18 @@ impl UiScript {
         ) = {
             let mut model = self.model_mut();
             model.cursor_pos = (x, y);
-            // Advance an in-flight Slider thumb drag first — dragging within one frame crosses no
-            // hover boundary, so this must run before the early return below (decision 0250 §5).
+            // Drags advance on every move, before the hover test: a drag within one frame crosses
+            // no hover boundary.
             let slider_change = super::slider::drag_move(&mut model, x, y);
-            // The colour picker's wheel/strip drag, for the identical reason — and it fires on
-            // every move, not only on a change (the widget has no change-gate).
+            // The colour picker fires on every move, not only on a change: it has no change gate.
             let color_change = super::colorselect::drag_move(&mut model, x, y);
-            // A frame in flight from `StartMoving()` follows the cursor here for the same reason
-            // (`object::movable`): the frame moves *under* the cursor, so the hover boundary never
-            // crosses and a pump behind the early return would only ever advance when the cursor
-            // left the frame it is dragging.
             super::object::advance_move(&mut model, (x, y));
             super::object::advance_size(&mut model, (x, y));
             let drag_start = cursor::maybe_start_drag(&mut model, (x, y));
             let new_handle = new_id.and_then(|id| model.id_to_frame.get(&id).copied());
             if new_handle == model.mouseover {
-                // no boundary crossed
                 (None, drag_start, None, slider_change, color_change)
             } else {
-                // Fire OnLeave only if the frame we're leaving is still live.
                 let old_id = model.mouseover.and_then(|h| {
                     model
                         .arena
@@ -324,32 +187,17 @@ impl UiScript {
                 });
                 let old_handle = model.mouseover;
                 model.mouseover = new_handle;
-                // **Crossing a button's boundary moves NO button state**, and the comment that
-                // used to sit here claimed the opposite off two mis-attributed addresses:
-                // `0x7793f0` is the drag-start override, not a leave, and `0x7791e0` is the hide
-                // override, not an enter. The real enter/leave notifies `0x779490`/`0x7794e0`
-                // read `[+0x328]` only as a DISABLED guard and never write it (wow-re
-                // `scratch/button-state-edge-set.md`, a §5 census of every store to the field).
-                //
-                // So a press held over a button and walked off it stays PUSHED in the reference —
-                // it is the *drag threshold* (below) that un-presses one, and only for a frame
-                // that registered for drag. Decision 2134.
-                //
-                // **A DISABLED Button swallows its own hover notify** and so runs neither script:
-                // both `0x779490` and `0x7794e0` open `mov eax,[esi+0x328]; test eax,eax; je`,
-                // branching past the base notify that owns the `<OnEnter>`/`<OnLeave>` slots
-                // ([`button::hover_notify_runs`]). The gate is per-side — leaving a button that
-                // was disabled *while* hovered is as silent as entering one — and it is applied
-                // AFTER `model.mouseover` moves, because the reference reassigns the hover target
-                // `[root+0x7c]` before it fires either notify: a disabled button is still the
-                // mouse focus, it just says nothing.
+                // Crossing a button's boundary changes no button state: the enter/leave notifies
+                // (`0x779490`/`0x7794e0`) read `[+0x328]` only as a disabled guard, so a press
+                // walked off a button stays pushed until the drag start (`0x7793f0`) un-presses a
+                // drag-registered one. A disabled Button runs neither script, on either side, and
+                // is still the hover: the reference moves `[root+0x7c]` before either notify.
                 let old_id = old_id.filter(|_| button::hover_notify_runs(&model, old_handle));
                 let enter_id = new_id.filter(|_| button::hover_notify_runs(&model, new_handle));
                 (old_id, drag_start, enter_id, slider_change, color_change)
             }
         };
-        // The thumb-drag value change fires OnValueChanged (outside the borrow) — the scrollbar's
-        // OnValueChanged→SetVerticalScroll wiring runs here, exactly as the arrow buttons drive it.
+        // A thumb drag fires `OnValueChanged`, outside the borrow.
         if let Some((id, value)) = slider_change {
             if let Err(e) = event::fire_widget_handler(
                 &self.lua,
@@ -394,12 +242,8 @@ impl UiScript {
         new_id
     }
 
-    /// Is `(x, y)` inside this frame's title region?
-    ///
-    /// **False whenever the region has no resolved rect**, which is the common case and the correct
-    /// one: a freshly created title region has NO anchors at all and does nothing until
-    /// `SetPoint`/`SetAllPoints` (Q6). Both corpus consumers call `SetAllPoints` immediately, so
-    /// theirs covers the whole window — the whole-window-as-drag-handle idiom.
+    /// Whether `(x, y)` is inside the frame's title region. A new title region has no anchors and
+    /// hits nothing until `SetPoint`/`SetAllPoints` (`CreateTitleRegion 0x773910`).
     fn title_region_hit(&self, h: crate::widget::FrameHandle, x: f32, y: f32) -> bool {
         let model = self.model_ref();
         model
@@ -410,66 +254,20 @@ impl UiScript {
             .is_some_and(|r| point_in_rect(*r, x, y))
     }
 
-    /// A mouse button transition at `(x, y)`: `button` is the WoW name (`"LeftButton"`,
-    /// `"RightButton"`, …), `down` is press vs release. Fires `OnMouseDown(self, button)` on press or
-    /// `OnMouseUp(self, button)` on release. **The press fires on the hit frame and the release on
-    /// the frame that took the press** — the client's mouse capture (`root+0x80`); see the dispatch
-    /// itself for the bytes and for the stuck-resize it prevents.
-    ///
-    /// Separately, `OnClick` fires per the hit frame's `RegisterForClicks` set
-    /// ([`button::wants_click`]): a **press** fires immediately when the frame registered
-    /// `"<Button>ButtonDown"` (`OnClick(self, button, down=true)`); a **release** whose matching
-    /// **press** captured the *same* frame fires when the frame registered `"<Button>ButtonUp"`
-    /// (`OnClick(self, button, down=false)` — the Era signature,
-    /// `warcraft.wiki.gg/wiki/UIHANDLER_OnClick`). The default set is `{"LeftButtonUp"}`, so
-    /// unregistered buttons (a bare right-click, say) reach neither. Press targets are tracked per
-    /// button.
-    ///
-    /// The drag trio + world drop (decision 0216 §3, corrected by 0218) ride the same
-    /// transition: a press ARMS a [`super::Model::drag`] gesture on a [`super::Model::drag_registered`] frame
-    /// ([`cursor::arm_drag`]); a release RESOLVES it ([`cursor::take_drag`]) — a STARTED gesture
-    /// fires `OnDragStop` on the source and `OnReceiveDrag` on whatever the release hit (a no-op
-    /// if that frame carries no such script), and SUPPRESSES `OnClick` for this release (an
-    /// un-started gesture leaves the ordinary click path untouched). The **world drop**
-    /// ([`cursor::world_drop_click`]) fires ONLY on a completed left CLICK over the world —
-    /// press AND release both [`over_world`], no started drag (the byte-verified trigger: the
-    /// client's `0x495300` runs on the WorldFrame click release; a drag release routes as a
-    /// drag, never a click — wow-re cursor-dragdrop-payload.md, and the director's report it
-    /// confirmed) — routed by the app-fed pick (decisions 0571 + 0574): over an object nothing
-    /// drops (the reference keeps an item payload and selects); over terrain an item fires
-    /// `DELETE_ITEM_CONFIRM` and stays held while a spell/action survives; over nothing the
-    /// item pops and any other payload clears silently. A drag released over nothing keeps its
-    /// payload untouched.
-    ///
-    /// Handler errors are collected into [`UiScript::errors`]. Returns whether the UI consumed
-    /// the event (`hit_id.is_some()` or a world drop was handled) — a new public return; existing
-    /// statement-position calls (`script.mouse_button(...);`) are unaffected.
+    /// A mouse button press or release at `(x, y)`; `button` is the WoW name (`"LeftButton"`, …).
+    /// `OnClick` follows `RegisterForClicks` ([`button::wants_click`], default `{"LeftButtonUp"}`):
+    /// a press fires it for `"<Button>ButtonDown"`, a release on the pressed frame for
+    /// `"<Button>ButtonUp"`. Its `down` argument is not 1.12, whose firer (`0x779540`) passes only
+    /// the button name. Returns whether the UI consumed the event.
     pub fn mouse_button(&mut self, x: f32, y: f32, button: &str, down: bool) -> bool {
         let hit_id = self.hit_test(x, y);
-        // ── The RAISE, and it happens FIRST ─────────────────────────────────────────────────────
+        // ── The raise, first ────────────────────────────────────────────────────────────────────
         //
-        // wow-re ledger `0x7662c0` (VERIFIED, the `toplevel-raise.md` §5 fan-out): the
-        // mouse-button-DOWN handler "resolves target = root+0x80 (existing capture) else
-        // root+0x7c (hover frame), calls `0x76a5b0` Raise() **UNGUARDED** @`0x766392` (the
-        // toplevel gate is inside `0x7650f0`, so the raised frame may be an ancestor of the
-        // clicked one), then title-region drag or capture+OnMouseDown".
-        //
-        // Four clauses, each load-bearing and each visible:
-        //
-        //  · **DOWN only.** The sibling category-`0xe` handler `0x766420` never raises — a window
-        //    comes forward on the press, not on the release.
-        //  · **Before the title-region swallow below**, so grabbing a window by its title bar
-        //    raises it too, even though that path dispatches no `OnMouseDown` at all.
-        //  · **Unguarded** — no toplevel test out here. [`toplevel::raise`] walks to the nearest
-        //    toplevel self-or-ancestor and does nothing when there is none, which is exactly what
-        //    makes a click on a *child* (a button, a tab, the window's own background texture)
-        //    bring the whole window forward.
-        //  · **Capture else hover.** [`Model::mouse_capture`] is `root+0x80`; while a button is
-        //    held it wins, so a chorded press over a different window raises the one being
-        //    dragged, not the one under the cursor.
-        //
-        // Nothing here is gated on the frame being mouse-enabled: the "hover frame" is the
-        // hit-test result, which already applies that gate.
+        // The press handler `0x7662c0` raises the capture (`root+0x80`) else the hover frame
+        // (`root+0x7c`) through `0x76a5b0`, called unguarded at `0x766392` (the toplevel walk is
+        // inside `0x7650f0`), before the title-region test: a click on a child or a title bar
+        // brings its window forward, and a chorded press raises the window being dragged. The
+        // release handler `0x766420` never raises.
         if down {
             let target = self.model_ref().mouse_capture;
             if let Some(t) = target.or_else(|| self.hit_test_frame(x, y)) {
@@ -477,16 +275,11 @@ impl UiScript {
                 super::object::toplevel::raise(&mut model, t);
             }
         }
-        // ── The title region, and it SWALLOWS the press ─────────────────────────────────────────
+        // ── The title region swallows the press ─────────────────────────────────────────────────
         //
-        // A mouse-down inside `frame:GetTitleRegion()` starts a mode-2 move and never reaches the
-        // ordinary path: the reference's `0x7662c0` tests `titleRegion+0x24` point-in-rect FIRST
-        // and only a MISS falls through to `0x7663e6`, which sets the captured frame and dispatches
-        // `vtable[0x68]` — the OnMouseDown script. So a hit takes `OnMouseDown`/`OnMouseUp` and
-        // `RegisterForDrag`'s `OnDragStart` with it (wow-re `widget-api-batch-benilla.md` Q6).
-        //
-        // Returning early is what implements that swallow: no OnMouseDown, no drag arm, no OnClick,
-        // no double-click bookkeeping. It reports the event CONSUMED, because it was.
+        // A press inside the title region starts a mode-2 move and ends there: `0x7662c0` tests
+        // the region first and only a miss reaches `0x7663e6`, the capture and `OnMouseDown`. So
+        // no `OnMouseDown`, drag arm, `OnClick` or double-click stamp, and the event is consumed.
         if down {
             if let Some(h) = self.hit_test_frame(x, y) {
                 if self.title_region_hit(h, x, y) {
@@ -496,13 +289,11 @@ impl UiScript {
                 }
             }
         }
-        // ── …and the release ends it, where a scripted move would survive ───────────────────────
+        // ── The release ends a title move ───────────────────────────────────────────────────────
         //
-        // `0x766420` auto-cancels modes 1 (modifier-drag) and 2 (title region) and leaves mode 3
-        // (`StartMoving`) alone — so a window grabbed by its title bar stops when the button comes
-        // up, while `OnDragStart → StartMoving` keeps moving until the addon's
-        // `StopMovingOrSizing`. Reduced to [`FrameMove::auto_stop`], because that one bit is all
-        // of the mode that is observable from Lua.
+        // `0x766420` cancels move modes 1 (modifier drag) and 2 (title region) on release and
+        // leaves mode 3 (`StartMoving`) to the addon's `StopMovingOrSizing`;
+        // `FrameMove::auto_stop` is that distinction.
         if !down
             && self
                 .model_ref()
@@ -512,9 +303,7 @@ impl UiScript {
         {
             self.model_mut().moving = None;
         }
-        // The capture this release belongs to — read HERE because the borrow below *drains*
-        // `mouse_down_on` for this button. See the `OnMouseUp` dispatch further down for why the
-        // press target rather than the hit frame.
+        // The press this release belongs to, read before the borrow below drains `mouse_down_on`.
         let captured_id: Option<u32> = if down {
             None
         } else {
@@ -524,8 +313,7 @@ impl UiScript {
                 .get(button)
                 .and_then(|h| model.frame_to_id.get(h).copied())
         };
-        // The session clock, read before the borrow below — the double-click detector's only input
-        // beyond the hit ([`Model::last_click`]). Same `GetTime()` seconds every script sees.
+        // The `GetTime()` clock for the double-click detector, read before the borrow.
         let now = self.now();
         self.model_mut().cursor_pos = (x, y);
         let btn = match self.lua.create_string(button) {
@@ -535,10 +323,6 @@ impl UiScript {
                 return hit_id.is_some();
             }
         };
-        // Resolve the OnClick target (if any), arm/resolve the drag gesture, and handle a world
-        // drop — all under one short borrow. A press fires OnClick when the hit frame registered
-        // "<Button>ButtonDown"; a release fires it when press+release landed on the same frame AND
-        // it registered "<Button>ButtonUp" — UNLESS a started drag is being resolved instead.
         #[allow(clippy::type_complexity)]
         let (
             click_id,
@@ -564,50 +348,34 @@ impl UiScript {
                     Some(h) => model.mouse_down_on.insert(button.to_string(), h),
                     None => model.mouse_down_on.remove(button),
                 };
-                // `0x7792b1`: the press edge, `SetButtonState(PUSHED, 0)`.
-                //
-                // It is unconditional *past* `0x779210`'s own two gates, and the first of them is
-                // the registration mask `[this+0x330]` tested as `m | m << 8` at `0x77924b` —
-                // "registered for this mouse button EITHER WAY, up or down". That is
-                // [`button::wants_press_visual`], and it is why a right-click lights up an action
-                // slot (it registers `RightButtonUp`) and does nothing at all to a plain
-                // `LeftButtonUp` button. Past it the edge is gated only on the button's own
-                // `locked == 0 && state != DISABLED`.
+                // The press edge, `SetButtonState(PUSHED)` (`0x7792b1`), for a button registered
+                // for this mouse button up or down (`0x779210` tests `m | m << 8` at `0x77924b`).
                 if let Some(h) = hit_handle.filter(|&h| button::wants_press_visual(&model, h, button))
                 {
                     button::edge(&mut model, h, ButtonState::on_mouse_down);
                 }
-                // A press arriving while this same mouse button was already holding another
-                // frame is a release we never got (the OS ate it — a focus loss, a modal). Give
-                // the displaced frame that release rather than leaving it pushed forever; the
-                // reference never reaches this because its capture guarantees the release.
+                // A press while this mouse button still holds another frame means a release was
+                // lost (a focus loss); that frame gets it so it does not stay pushed. The
+                // reference's capture never loses one.
                 if let Some(h) = displaced {
                     button::edge(&mut model, h, ButtonState::on_mouse_up);
                 }
-                // `0x7663e6` writes the resolved target into `root+0x80` — capture-else-hover, so
-                // this is an `or`, not an assignment: an existing capture is not displaced by a
-                // second button pressed elsewhere. (This is the point the reference reaches only
-                // on a title-region MISS, which is why the swallow above returns before it.)
+                // `0x7663e6` sets the capture `root+0x80` only when none is held: a second button
+                // pressed elsewhere does not displace it.
                 model.mouse_capture = model.mouse_capture.or(hit_handle);
-                // A press REPLACES any in-flight gesture, so a started one has to be ended first
-                // — `abandon_drag`'s own doc carries why a silent drop is a stuck UI rather than a
-                // cancelled drag. Its `OnDragStop` fires below, outside this borrow.
+                // A press replaces any in-flight gesture; a started one gets its `OnDragStop`
+                // below, outside this borrow.
                 let abandoned = cursor::abandon_drag(&mut model);
                 cursor::arm_drag(&mut model, hit_handle, button, (x, y));
-                // A left press on a Slider begins the engine drag (0250 §5): a thumb press grabs
-                // it in place; a track press seats the thumb under the cursor first (the returned
-                // value jump — 0989), independent of the click/drag-trio path above (a Slider
-                // isn't drag_registered).
+                // A left press on a Slider grabs the thumb, or on the track seats the thumb under
+                // the cursor first (the returned value jump).
                 let jump = if button == "LeftButton" {
                     super::slider::begin_drag(&mut model, hit_handle, x, y)
                 } else {
                     None
                 };
-                // A left press inside a ColorSelect's wheel or value strip captures the colour
-                // drag AND jumps the colour to the click point in the same call — the widget's
-                // press handler invokes its own cursor-position handler before returning
-                // (`0x78bf70 call [eax+0x3c]`), so there is no such thing as a press that only
-                // arms.
+                // A left press in a ColorSelect's wheel or value strip also jumps the colour to the
+                // click point: its press handler calls its cursor handler (`0x78bf70`).
                 let color_jump = if button == "LeftButton" {
                     super::colorselect::begin_drag(&mut model, hit_handle, x, y)
                 } else {
@@ -620,13 +388,11 @@ impl UiScript {
                 (click, None, false, jump, None, abandoned, color_jump)
             } else {
                 let pressed = model.mouse_down_on.remove(button);
-                // `root+0x80` is cleared at `0x7664bb` **only when the post-event button mask is
-                // zero** — a chorded release keeps the capture for the button still held. With the
-                // per-button map already drained above, "mask is zero" is "the map is empty".
+                // `0x7664bb` clears the capture only when no button is still held, so a chorded
+                // release keeps it.
                 if model.mouse_down_on.is_empty() {
                     model.mouse_capture = None;
                 }
-                // A left release ends any in-flight thumb drag (decision 0250 §5).
                 if button == "LeftButton" {
                     super::slider::end_drag(&mut model);
                     super::colorselect::end_drag(&mut model);
@@ -637,27 +403,15 @@ impl UiScript {
                 );
                 let release = cursor::take_drag(&mut model, button);
                 let started = release.as_ref().is_some_and(|r| r.started);
-                // **The release edge** — `0x7793de`'s `SetButtonState(NORMAL, 0)`, on the frame
-                // the PRESS captured and regardless of where the cursor now is (`0x7792d0` runs
-                // no hit test of its own). It is guarded on the button's own `locked == 0` and on
-                // the state actually being PUSHED, and it is **skipped when the base finalized a
-                // drag** — `0x7792df`'s `0x76c040` test, which is this `started` (the button
-                // already un-pressed at the drag-start edge below, and un-pressing again would
-                // fire nothing but would be a second transition the reference does not make).
+                // The release edge, `SetButtonState(NORMAL)` (`0x7793de`), on the pressed frame
+                // wherever the cursor is, skipped after a started drag (`0x7792df` tests
+                // `0x76c040`), which already un-pressed it.
                 if let (Some(h), false) = (pressed, started) {
                     button::edge(&mut model, h, ButtonState::on_mouse_up);
                 }
-                // The world drop: press AND release both over THE WORLD, no drag started —
-                // a completed left click on the game world (never a drag release, which just
-                // keeps carrying; decision 0218's byte-verified trigger). What actually drops
-                // is routed inside `world_drop_click` by the app-fed world pick (decisions
-                // 0571 + 0574): an object pick keeps everything, terrain drops items only,
-                // nothing drops any arm.
-                //
-                // "Over the world" is [`over_world`], not `is_none()`: since 1983 the stock
-                // `WorldFrame` is a real mouse-enabled frame covering the screen, so a world
-                // click hits IT — which is exactly what the reference's own world click is
-                // (1984). Spelling this as "no frame" is what B380 was (decision 2089).
+                // The world drop: a completed left click on the world, never a drag release, which
+                // keeps carrying (`0x495300` runs on the WorldFrame click release). The world is
+                // `over_world`, not "no frame": the stock `WorldFrame` covers the screen.
                 let dropped = button == "LeftButton"
                     && !started
                     && over_world(&model, hit_handle)
@@ -671,22 +425,11 @@ impl UiScript {
                         .filter(|&h| same_frame && button::wants_click(&model, h, &wants))
                         .and(hit_id)
                 };
-                // ── The double-click adjudication — on the RELEASE edge, on the click that just
-                // qualified, and STRICTLY EXCLUSIVE with it.
-                //
-                // All three of those are byte-verified (wow-re `ui/scratch/button-doubleclick-law.md`):
-                // the only site that fires the `+0x4d4` slot is `0x77938d`, inside the mouse-UP
-                // dispatcher `0x7792d0` — the mouse-DOWN dispatcher `0x779210` has no double-click
-                // leg at all — and `0x77939d jmp 0x7793b5` skips *past* the single leg's
-                // `call [edx+0x94]`, so **`OnDoubleClick` REPLACES the second `OnClick`; it is not
-                // additive**. Whatever suppresses the click (a resolved drag, a release on another
-                // frame, a button this widget never registered) suppresses this too, by
-                // construction: it hangs off `click`.
-                //
-                // The handler-presence test is load-bearing, not an optimisation. The binary's
-                // chain includes `[+0x4d4] != 0`, so a widget with no `OnDoubleClick` script takes
-                // the ordinary single leg every time — without that gate, rattling any button in
-                // the UI would silently swallow every second `OnClick`.
+                // The double click, on the release that qualified as a click: `0x77938d` in the
+                // mouse-up dispatcher `0x7792d0` fires `OnDoubleClick` instead of the second
+                // `OnClick` (`0x77939d jmp 0x7793b5` skips the single leg), only for a frame with
+                // an `OnDoubleClick` script (`[+0x4d4] != 0`). What suppresses the click
+                // suppresses it too.
                 let target = click.and(hit_handle);
                 let double = target.filter(|&h| {
                     model
@@ -699,24 +442,20 @@ impl UiScript {
                             .is_some_and(|&t| now - t <= DOUBLE_CLICK_SECS)
                 });
                 if let Some(h) = double {
-                    // A completed double ZEROES the stamp (`0x779393`), so clicks PAIR: four fast
-                    // clicks are Click · DoubleClick · Click · DoubleClick, never one click and
-                    // three doubles.
+                    // A double clears the stamp (`0x779393`), so clicks pair: four fast clicks are
+                    // click, double, click, double.
                     model.last_click.remove(&h);
                 } else if let Some(h) = target {
-                    // A fired single ARMS the detector (`0x7793af`) — on the click *predicate*,
-                    // not on an `OnClick` handler existing: the binary stamps after calling the
-                    // firer, which is itself a no-op when no script is bound.
+                    // A single stamps the detector (`0x7793af`) whether or not an `OnClick` script
+                    // is bound.
                     model.last_click.insert(h, now);
                 }
                 let double_id = double.and_then(|h| model.frame_to_id.get(&h).copied());
-                // Exclusive, not additive — the double leg is taken *instead of* the single one.
                 let click = if double_id.is_some() { None } else { click };
                 (click, release, dropped, None, double_id, None, None)
             }
         };
-        // A track press's value jump fires OnValueChanged first (outside the borrow), the same
-        // seam as `mouse_move`'s in-drag changes — the press IS the first move of the gesture.
+        // A track press's value jump fires `OnValueChanged` first, outside the borrow.
         if let Some((id, value)) = slider_jump {
             if let Err(e) = event::fire_widget_handler(
                 &self.lua,
@@ -727,61 +466,25 @@ impl UiScript {
                 self.push_error(e);
             }
         }
-        // The press's colour jump fires OnColorSelect the same way.
         if let Some((id, r, g, b)) = color_jump {
             if let Err(e) = super::colorselect::fire_by_id(&self.lua, id, r, g, b) {
                 self.push_error(e);
             }
         }
-        // ── `OnMouseUp` goes to the frame that took the PRESS, not to whatever is under the
-        // cursor now — the mouse CAPTURE (`root+0x80`).
+        // ── `OnMouseUp` goes to the capture ─────────────────────────────────────────────────────
         //
-        // The client's mouse-DOWN handler `0x7662c0` takes the pointer: "resolves target =
-        // root+0x80 (existing capture) else root+0x7c (hover frame) … then title-region drag or
-        // **capture**+OnMouseDown" (wow-re ledger `0x7662c0`).
-        //
-        // The **release** half is `0x766420`, and it is VERIFIED — wow-re
-        // `system/ui/scratch/mouseup-dispatch-law.md`, a §5 dispatched from this repo for exactly
-        // this line after it first landed on an extrapolation (decision 1599). It reads the capture
-        // and **nothing else**: `[mgr+0x80]` is snapshotted into `ebx` at entry (`0x76642b`),
-        // before anything, and `[mgr+0x7c]` — the hover frame — is **never read** anywhere in
-        // `[0x766420, 0x7664f0)`. One dispatch, `0x7664a4 call [eax+0x6c]`.
-        //
-        // So a press on A released over B fires `OnMouseUp` on **A**, and B gets nothing on the
-        // release edge. We already track exactly that capture — [`Model::mouse_down_on`], the press
-        // target per button, which `OnClick`'s same-frame rule reads — and firing `OnMouseUp` at
-        // the *hit* frame was the one place it went unused. This function's doc always said "on the
-        // captured frame"; the code did not.
-        //
-        // It is not a nicety: a chat window's resize grip is a 16×16 button that the drag pulls
-        // out from under the cursor the moment the size clamps at `SetMinResize`/`SetMaxResize`
-        // (the rebate plants the edge on the bound while the cursor keeps going). Its
-        // `OnMouseUp → FCF_StopResize` then never ran, and `Model::sizing` stayed held for the
-        // rest of the session — the stuck-drag failure `cursor::abandon_drag` exists to prevent on
-        // the other path.
-        //
-        // **A press that captured NOTHING fires nothing**, and this is the half the first version
-        // of this code got wrong: it fell back to the frame under the cursor, reading the DOWN
-        // handler's `+0x80`-else-`+0x7c` precedence as if the UP handler shared it. It does not —
-        // `0x766498 test ebx,ebx / je 0x7664cd` returns with no virtual call at all. The fallback
-        // was a divergence that let a press over open space deliver a release to whatever the
-        // cursor had wandered onto.
-        //
-        // (Two things the same §5 settled that are invisible from here: the capture is cleared at
-        // `0x7664bb`, **after** the dispatch — so a C++ consumer inside `OnMouseUp` still sees it,
-        // though no Lua binding reads it, `GetMouseFocus 0x48df40` being `+0x7c`; and the clear is
-        // gated on `evt+0x18 == 0`, the button mask *after* the event, so a **chorded** release
-        // fires `OnMouseUp` and keeps the capture for the button still held.)
+        // The release handler `0x766420` reads only the capture `[mgr+0x80]` (`0x76642b`), never
+        // the hover frame, so a press on A released over B fires `OnMouseUp` on A, and a press
+        // that captured nothing fires nothing (`0x766498`). A resize grip dragged out from under
+        // the cursor still gets its `OnMouseUp`, so its resize ends.
         let script = if down { "OnMouseDown" } else { "OnMouseUp" };
         if let Some(id) = if down { hit_id } else { captured_id } {
             if let Err(e) = event::fire_widget_handler(&self.lua, id, script, vec![btn.clone()]) {
                 self.push_error(e);
             }
         }
-        // A release inside a hyperlink span fires `OnHyperlinkClick(link, markup, button)` on the
-        // owning frame — the ChatFrameTemplate wires it to `SetItemRef` (decision 0288 P2). Never
-        // on a drag resolution (same suppression as OnClick); spans were fed by the app after the
-        // last rasterize (`UiScript::set_link_spans`), so they match what's on screen.
+        // A release in a hyperlink span fires `OnHyperlinkClick(link, markup, button)` on the
+        // owning frame, except after a started drag.
         if !down && !drag_release.as_ref().is_some_and(|r| r.started) {
             if let Some(id) = hit_id {
                 let span = {
@@ -817,9 +520,8 @@ impl UiScript {
                 }
             }
         }
-        // The EditBox click law (`0x77b800`): a LeftButton press inside an EditBox places the
-        // cursor at the clicked char, starts the drag, and focuses it UNCONDITIONALLY
-        // (independent of autoFocus), before any OnClick fires. A release ends any drag.
+        // A left press in an EditBox places the cursor, starts a selection drag and focuses it
+        // whatever its `autoFocus`, before any `OnClick` (`0x77b800`).
         if button == "LeftButton" {
             if down {
                 if let Some(id) = hit_id {
@@ -829,14 +531,11 @@ impl UiScript {
                 editbox::drag_end(&self.lua);
             }
         }
-        // A gesture this press REPLACED gets its `OnDragStop` too, before anything the new press
-        // does: the handler on the other end has a `StopMovingOrSizing` in it, and until that runs
-        // the engine's one move slot is still held (see `cursor::abandon_drag`).
+        // A gesture this press replaced gets its `OnDragStop` first: its handler's
+        // `StopMovingOrSizing` frees the engine's one move slot.
         if let Some(source) = abandoned {
             self.fire_drag_stop(source);
         }
-        // The drag trio's stop/receive pair, fired outside the model borrow above (only for a
-        // gesture that actually started — see `cursor::DragRelease::started`).
         if let Some(release) = drag_release.filter(|r| r.started) {
             self.fire_drag_stop(release.source);
             if let Some(id) = hit_id {
@@ -848,34 +547,26 @@ impl UiScript {
             }
         }
         if let Some(id) = click_id {
-            // One click home for the physical and programmatic (`Click()`) paths: gated on a
-            // Button's enabled flag, a CheckButton toggles before OnClick fires (button.rs).
+            // Shared with `Click()`: gated on the Button being enabled; a CheckButton toggles
+            // before `OnClick` fires.
             button::click_button(&self.lua, id, button, down, false);
         }
-        // `OnDoubleClick(self, button)` — fired where `OnClick` would have been and instead of it
-        // (`0x77938d call [edx+0x98]`, the mouse-UP dispatcher's exclusive second leg). One
-        // argument, the button name of the *completing* release, and it plays the same click sound
-        // as a single: the base firer `0x779650` is the byte-twin of the single leg's `0x779540`.
-        //
-        // `arg2` is 0 in both legs; we pass it only for `OnClick`, where our binding already spells
-        // it as the documented `down` flag, and drop it here to match the Era-facing
-        // `OnDoubleClick(self, button)` signature the corpus is written against.
+        // `OnDoubleClick(self, button)` in place of `OnClick` (`0x77938d call [edx+0x98]`), with
+        // the same click sound: its firer `0x779650` is the twin of `OnClick`'s `0x779540` and
+        // passes only the button name of the completing release.
         if let Some(id) = double_id {
             if let Err(e) = event::fire_widget_handler(&self.lua, id, "OnDoubleClick", vec![btn]) {
                 self.push_error(e);
             }
         }
-        // Whether the **UI** consumed the event. A hit on the world frame is not the UI
-        // consuming anything — "the press runs the frame's Lua `OnMouseDown` (never consuming),
-        // then the `BUTTON1`/`BUTTON2` binding" (1984) — so it answers no unless the click was
-        // itself the world drop. Without that clause the stock `WorldFrame` would report every
-        // click in the game as eaten by the interface.
+        // A world-frame hit is not the UI consuming the event: the reference runs its
+        // `OnMouseDown` without consuming (`0x483c40`), then the `BUTTON1`/`BUTTON2` binding, the
+        // world click. Only a world drop counts.
         hit_id.is_some_and(|id| !self.is_world_frame(id)) || world_dropped
     }
 
-    /// Fire `OnDragStop` on a gesture's source — the ONE place that ends a started drag, so the
-    /// release path and the two abandon paths ([`cursor::abandon_drag`]) cannot drift apart.
-    /// A source that died between the press and here fires nothing.
+    /// Fire `OnDragStop` on a gesture's source, the one place a started drag ends; a source that
+    /// died since the press fires nothing.
     pub(super) fn fire_drag_stop(&mut self, source: crate::widget::FrameHandle) {
         let id = {
             let model = self.model_ref();
@@ -893,21 +584,14 @@ impl UiScript {
         }
     }
 
-    /// A mouse-wheel spin at `(x, y)`: fires `OnMouseWheel(self, delta)` on the hit frame — or,
-    /// when the hit frame carries no OnMouseWheel handler, on its NEAREST ANCESTOR that does (the
-    /// client's bubbling: a reward-row Button inside a ScrollFrame doesn't eat the wheel, the
-    /// pane keeps scrolling under the cursor). WoW's convention is `+1` per notch up / `-1` down
-    /// (`warcraft.wiki.gg/wiki/UIHANDLER_OnMouseWheel`); `delta` is passed through as given, so
-    /// the app-side feed picks the magnitude/sign. Handler errors are collected into
-    /// [`UiScript::errors`].
+    /// A wheel spin at `(x, y)`: fires `OnMouseWheel(self, delta)` on the hit frame, or on its
+    /// nearest ancestor with the script when it has none; the reference instead lets its wheel
+    /// sweep continue past a frame with no script (`0x76c180`). `delta` passes through as given;
+    /// the reference passes only its sign, `+1` or `-1` (`0x76c1a2`).
     pub fn mouse_wheel(&mut self, x: f32, y: f32, delta: f32) {
         let target: Option<u32> = {
-            // **Wheel-enabled OR mouse-enabled**, not mouse-enabled alone. The reference's wheel
-            // dispatcher `0x7664f0` walks its OWN index and calls the hit probe directly, ignoring
-            // hover, capture and the mouse bit — `EnableMouse` is not a prerequisite
-            // (wow-re `mouse-enable-law.md` §6). Ours went through the mouse hit test, which
-            // coupled the two: correcting the ctor list to the reference's (ScrollFrame is inert
-            // on the mouse bit) silently stopped every scroll pane from taking the wheel.
+            // The wheel flag, not the mouse bit: the reference's wheel dispatcher `0x7664f0` walks
+            // its own index and ignores hover, capture and `EnableMouse`.
             let hit = self.hit_test_wheel(x, y);
             let model = self.model_ref();
             hit.and_then(|id| {
@@ -938,19 +622,14 @@ impl UiScript {
     }
 }
 
-/// Point-in-rect for hit-testing, in WoW UI coords (**y-up**): the cursor `(x, y)` is inside `r` when
-/// it lies within `[left, right] × [bottom, top]` (edges inclusive). This is the same space
-/// [`UiScript::resolve`]/[`UiScript::extract`] produce rects in — the verified `point_in_rect
-/// 0x76b020` primitive (`propagation.md`), modeled on our [`Rect`] convention.
+/// Point-in-rect in UI space (y-up), inclusive on all four edges, as the reference's probe
+/// `0x76b020` tests it.
 pub(super) fn point_in_rect(r: Rect, x: f32, y: f32) -> bool {
     x >= r.left && x <= r.right && y >= r.bottom && y <= r.top
 }
 
-/// A frame's **mouse** rect: its resolved rect shrunk by `[left, right, top, bottom]`
-/// ([`crate::widget::Frame::hit_rect_insets`]). y-up, so a `top` inset lowers `top` and a `bottom`
-/// inset raises `bottom`. Insets that over-shrink collapse the rect rather than inverting it — an
-/// empty rect simply captures nothing, which is what the API's own "inset past the far edge" case
-/// means.
+/// A frame's mouse rect: its resolved rect shrunk by its `[left, right, top, bottom]` hit-rect
+/// insets (y-up); an over-shrunk rect collapses to empty rather than inverting.
 fn inset_rect(r: Rect, [left, right, top, bottom]: [f32; 4]) -> Rect {
     Rect {
         left: r.left + left,
diff --git a/crates/benilla-ui/src/script/pvp/mod.rs b/crates/benilla-ui/src/script/pvp/mod.rs
index e4284926..53c9734b 100644
--- a/crates/benilla-ui/src/script/pvp/mod.rs
+++ b/crates/benilla-ui/src/script/pvp/mod.rs
@@ -1,107 +1,20 @@
-//! The **PvP + honor** surface — `TogglePVP` (decision 0646) and the vanilla honor system's
-//! thirteen bindings (decision 1512): the character window's Honor tab, the inspect window's Honor
-//! tab, and the rank every unit frame can read off a *foreign* player.
+//! `TogglePVP` and the thirteen honor bindings: the character and inspect windows' Honor tabs and
+//! the rank any unit frame can read off another player.
 //!
-//! ## The three seams
+//! The local player's counters are private descriptor fields the app pushes as a [`HonorState`];
+//! another player's arrive as a `MSG_INSPECT_HONOR_STATS` reply ([`InspectHonorData`]), whose
+//! presence is `HasInspectHonorData`. With nothing held every getter answers zeros at full width,
+//! as the reference reads zero-initialised slots ungated. A foreign player's current rank is
+//! public (`PLAYER_BYTES_3` byte 3) and rides [`UnitState::pvp_rank`](super::UnitState::pvp_rank).
 //!
-//! The crate's usual split (decision 0068 §3 — no ECS, no wire, no DBC in here):
+//! The internal rank (0 none, 1..=4 dishonorable, 5..=18 Scout or Private to High Warlord or
+//! Grand Marshal, 19 the racial "Leader") is what the wire carries and what keys the
+//! `PVP_RANK_<rank>_<team>` GlobalStrings; the visual rank indexes the badge texture, and every
+//! conversion goes through [`visual_rank`].
 //!
-//! - **Pushed state.** The local player's honor counters are PRIVATE descriptor fields
-//!   (`PLAYER_FIELD_SESSION_KILLS` … `PLAYER_FIELD_BYTES2`), so the app decodes them and pushes a
-//!   [`HonorState`] ([`UiScript::set_honor`]); the six self getters read it and nothing else.
-//!   The inspect pane's numbers are **not** a descriptor: `MSG_INSPECT_HONOR_STATS` (`0x2D6`) is a
-//!   request/reply pair, so they arrive separately as an [`InspectHonorData`]
-//!   ([`UiScript::set_inspect_honor`]) — and *whether one is held* is exactly what
-//!   `HasInspectHonorData` reports, which is the latch the reference's `OnShow` gates its request
-//!   on. That is why the inspect half is an `Option`, and the self half too — but the `Option` is
-//!   the **latch only**: the engine's data slots are zero-initialised BSS that every getter reads
-//!   ungated, so "nothing held" answers **zeros at full width**, never nils and never a short
-//!   return. The one thing an empty slot changes is `HasInspectHonorData`.
-//! - **Intents.** `TogglePVP` queues a `CMSG_TOGGLE_PVP` ([`UiScript::take_pvp_toggles`]) and
-//!   `RequestInspectHonorData` queues the honor query
-//!   ([`UiScript::take_inspect_honor_requests`]) — both counts rather than payloads, because
-//!   neither packet carries anything the VM knows: the toggle has an empty body, and the honor
-//!   query's body is the *inspected player's* guid, which the app already holds
-//!   ([`super::inspect`]'s target). Same reasoning as `NotifyInspect`, one argument smaller.
-//!   The honor query carries a second piece of engine state with it — the **`pending` latch**
-//!   (`0xb71fcc`), which refuses a second query while one is in flight; see the binding.
-//! - **The unit snapshot.** A *foreign* player's rank is knowable at all because `PLAYER_BYTES_3`
-//!   is a PUBLIC field — byte 3 of it is the CURRENT rank — so it rides
-//!   [`UnitState::pvp_rank`](super::UnitState::pvp_rank) with the other public per-unit facts and
-//!   `UnitPVPRank("target")` answers for the inspect pane exactly as the reference's does.
-//!
-//! ## Two ranks, and neither is the other
-//!
-//! - **Internal rank**, `0..=19`: the byte on the wire, and the number `GetPVPRankInfo` keys its
-//!   title lookup on. `0` is "no rank"; `1..=4` are the dishonorable ranks; `5..=18` are
-//!   Scout/Private through High Warlord/Grand Marshal; `19` is the racial-leader "Leader", which
-//!   the server sends in `SMSG_PVP_CREDIT` and **`GetPVPRankInfo` refuses** (see below).
-//! - **Visual rank**, `-4..=14`: `rank >= 5 ? rank - 4 : rank - 5` (`0x51aa31`) — what
-//!   `GetPVPRankInfo` *returns* as its second value, and what FrameXML indexes the badge texture by
-//!   (`"…PvPRank"..format("%02d", rankNumber)`, drawn only when it is positive).
-//!
-//! **The negative half runs the other way from the server's.** vmangos's `HonorMgr.cpp:991`
-//! computes `visualRank = rank > 4 ? rank - 4 : rank * -1`, which gives rank 1 → −1 and rank 4 →
-//! −4; the *binding* subtracts 5 instead of negating, so it gives rank 1 → **−4** and rank 4 →
-//! **−1**. They genuinely disagree, and the client is the authority for what the client's binding
-//! returns — [`visual_rank`] implements the binding. Nothing here reads the server's form, and a
-//! reader "fixing" this back to `-rank` would be reverting a §5 cross-check.
-//!
-//! Conflating the two scales puts Sergeant's badge on a Corporal, so [`visual_rank`] is the one
-//! place the conversion happens and every caller goes through it. The trap is that both numbers
-//! travel: the badge and `GetPVPRankInfo`'s second return are **visual**, while the wire —
-//! `PLAYER_BYTES_3` byte 3, `GetInspectHonorData`'s `lifetimeRank`, and `SMSG_PVP_CREDIT`'s
-//! `victimRank` (decision 1512 §2's second-pass correction: `HonorMgr::SendPVPCredit` sends
-//! `GetRank().rank`) — is **internal** throughout, which is what lets a rank byte index a
-//! `PVP_RANK_*` GlobalString with no conversion at all.
-//!
-//! ## Why the rank titles come out of the VM's own globals
-//!
-//! A rank's name is the GlobalString `PVP_RANK_<internal>_<team>` — the engine's one format string
-//! (`"PVP_RANK_%d_%d"` @ `0x8445b4`), team `0` Horde and `1` Alliance (VERIFIED against the shipped
-//! `FactionGroup.dbc` *and* `GlobalStrings.lua`: `PVP_RANK_5_0` is "Scout", `PVP_RANK_5_1` is
-//! "Private"). The real `GlobalStrings.lua` is executed off the player's own install at boot, so
-//! those keys are already sitting on `_G` when `GetPVPRankInfo` runs, and reading them there is the
-//! only correct answer: a table of titles shipped in this repo would be Blizzard text we may not
-//! carry (the contract's install-content rule) *and* wrong in every non-enUS locale. There is **no
-//! `PVP_RANK_0_*`** — internal rank 0 names nothing, and both reference panes lean on that nil to
-//! fall back to the `NONE` GlobalString, so a missing key answers nil here rather than an empty
-//! string or a raise.
-//!
-//! The team digit is a **tri-state**, not a bool: `0x5efe00` answers `0` Horde, `1` Alliance, or
-//! **`-1`** for a unit with no side, and −1 is not special-cased anywhere — it is formatted into
-//! the key, `PVP_RANK_9_-1` matches no GlobalString, and the miss *is* the "no title" answer.
-//!
-//! ## `_FEMALE` is real, and the honor pane never sees it
-//!
-//! The `_FEMALE` twins ship in `GlobalStrings.lua`, and the engine cannot build their keys: the
-//! byte sequence `FEMALE` does not occur anywhere in `WoW.exe`. It reaches them by asking
-//! **FrameXML** — `0x703bf0(key, ordinal, gender)` takes a Lua path whenever `gender != 0`, calling
-//! `GetText(token, gender, ordinal)`, which appends the suffix for gender 3. So the *suffix* is
-//! Lua's and the *request* is the engine's, per call site:
-//!
-//! - **`GetPVPRankInfo` passes gender 0** (`0x51aa0f`) and takes the fast path — so the character
-//!   and inspect honor panes render the **male/default title even for a female character**.
-//! - **`UnitPVPName`'s title is gendered** by the subject unit (`0x612bf0`), and
-//!   **`SMSG_PVP_CREDIT`'s is gendered by the LOCAL PLAYER** even though the *team* digit is the
-//!   victim's (`0x625374`) — the app's chat line owns that asymmetry, through
-//!   [`UiScript::pvp_rank_title`].
-//!
-//! So [`rank_title_ungendered`] and [`rank_title_gendered`] are two functions on purpose, and
-//! `GetPVPRankInfo` calls the first. **A client that gendered the pane's title would be more
-//! "correct" than the reference and would diverge from it**, which is not what we build.
-//!
-//! ## The counter-intuitive four (wow-re `system/ui/scratch/honor-panel-law.md`, §5, 2026-08-21)
-//!
-//! Everything below is byte law from that carve, and every one of them looks like a bug:
-//!
-//! 1. `GetPVPRankProgress` **multiplies by a slightly-wrong f32 reciprocal** and does not clamp —
-//!    [`rank_progress`].
-//! 2. The four dishonorable ranks' visual numbers run **backwards** from the server's — see "Two
-//!    ranks" above.
-//! 3. `GetPVPRankInfo` **rejects rank 19**, whose GlobalString exists and which the credit line and
-//!    `UnitPVPName` both render.
-//! 4. `GetPVPLifetimeStats` **suppresses a highest-lifetime rank below 5**, reporting `0`.
+//! Rank titles are read off the VM's globals, which the install's `GlobalStrings.lua` fills: the
+//! key is `"PVP_RANK_%d_%d"` (`0x8445b4`) with team 0 Horde and 1 Alliance. There is no
+//! `PVP_RANK_0_*`, and both panes fall back to `NONE` on its nil.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -109,26 +22,20 @@ use super::binding_abi::{number_arg, string_arg};
 use super::unit::{check_unit_token, is_civilian_kill};
 use super::Model;
 
-/// The local player's honor snapshot — every number the character window's Honor tab shows, as the
-/// app decoded it from the PRIVATE honor descriptor fields (decision 1512 §1). EXACT shape the app
-/// feed is written against; do not rename.
-///
-/// The kill counters are `u16` because their fields are `TWO_SHORT` descriptors read as halves
-/// (`PLAYER_FIELD_SESSION_KILLS` low = honorable, high = dishonorable); the honor totals are the
-/// whole-dword `*_CONTRIBUTION` fields.
+/// The local player's honor snapshot, decoded by the app from the private honor descriptor
+/// fields. Kill counts are halves of `TWO_SHORT` fields, low honorable and high dishonorable.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct HonorState {
-    /// `PLAYER_FIELD_SESSION_KILLS` low half — honorable kills this session.
+    /// `PLAYER_FIELD_SESSION_KILLS` low half.
     pub session_hk: u16,
-    /// `PLAYER_FIELD_SESSION_KILLS` high half — dishonorable kills this session.
+    /// `PLAYER_FIELD_SESSION_KILLS` high half.
     pub session_dk: u16,
     /// `PLAYER_FIELD_YESTERDAY_KILLS` halves.
     pub yesterday_hk: u16,
     pub yesterday_dk: u16,
-    /// `PLAYER_FIELD_YESTERDAY_CONTRIBUTION` — yesterday's honor.
+    /// `PLAYER_FIELD_YESTERDAY_CONTRIBUTION`.
     pub yesterday_honor: u32,
-    /// `PLAYER_FIELD_THIS_WEEK_KILLS` low half. There is no this-week DK getter: the reference
-    /// destructures exactly two values from `GetPVPThisWeekStats`.
+    /// `PLAYER_FIELD_THIS_WEEK_KILLS` low half; `GetPVPThisWeekStats` has no dishonorable count.
     pub this_week_hk: u16,
     /// `PLAYER_FIELD_THIS_WEEK_CONTRIBUTION`.
     pub this_week_honor: u32,
@@ -137,37 +44,26 @@ pub struct HonorState {
     pub last_week_dk: u16,
     /// `PLAYER_FIELD_LAST_WEEK_CONTRIBUTION`.
     pub last_week_honor: u32,
-    /// `PLAYER_FIELD_LAST_WEEK_RANK` — last week's **standing** (the ladder position), which is
-    /// `GetPVPLastWeekStats`'s fourth return and is not a rank at all.
+    /// `PLAYER_FIELD_LAST_WEEK_RANK`: last week's ladder standing, not a rank.
     pub last_week_standing: u32,
     /// `PLAYER_FIELD_LIFETIME_HONORBALE_KILLS` / `…_DISHONORBALE_KILLS` (the server's spellings).
     pub lifetime_hk: u32,
     pub lifetime_dk: u32,
-    /// `PLAYER_FIELD_BYTES` byte 3 — the HIGHEST LIFETIME rank, internal scale. PRIVATE, and
-    /// already decoded elsewhere in the app as the honor-rank byte.
-    ///
-    /// **Carried raw.** `GetPVPLifetimeStats` suppresses a value below 5 to `0` (`0x51a843`), and
-    /// that suppression is the *binding's*, not the feed's — push the true byte and let the
-    /// binding hide it, because the same field read through any other door is not hidden.
+    /// `PLAYER_FIELD_BYTES` byte 3: the highest lifetime rank, internal scale. Carried raw: only
+    /// `GetPVPLifetimeStats` hides a value below 5 (`0x51a843`).
     pub highest_rank: u8,
-    /// `PLAYER_BYTES_3` byte 3 — the **current** rank, internal scale, `0` = no rank. The same
-    /// PUBLIC byte that reaches every observer as [`UnitState::pvp_rank`](super::UnitState).
+    /// `PLAYER_BYTES_3` byte 3: the current rank, internal scale, 0 for none; the same public
+    /// byte as [`UnitState::pvp_rank`](super::UnitState).
     pub rank: u8,
-    /// `PLAYER_FIELD_BYTES2` byte 0 — progress through the current rank, `0..=255`. Carried as the
-    /// raw byte: the fraction is [`rank_progress`]'s business, not the feed's.
+    /// `PLAYER_FIELD_BYTES2` byte 0: progress through the current rank, the raw byte.
     pub rank_bar: u8,
 }
 
-/// One `MSG_INSPECT_HONOR_STATS` reply (decision 1512 §2), as the app decoded its 50-byte body.
-///
-/// Fourteen numbers and the guid they were about. **There is no per-period DK here** — the reply
-/// carries a session HK/DK pair and then bare HK counts for yesterday/last week/this week (the
-/// three `unknownOld` shorts between them are written as zero by the server), which is why
-/// `GetInspectHonorData` returns twelve values while the self getters together return more.
+/// One `MSG_INSPECT_HONOR_STATS` reply as the app decoded it. It has no dishonorable counts past
+/// the session pair (the server writes zeros there), so `GetInspectHonorData` returns twelve.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct InspectHonorData {
-    /// The player guid the reply was for — the app's key for "is this still the player we are
-    /// looking at?". Never returned to Lua; the reference's pane is keyed by its own unit token.
+    /// The player the reply was for, the app's key; never returned to Lua.
     pub guid: u64,
     pub session_hk: u16,
     pub session_dk: u16,
@@ -177,119 +73,70 @@ pub struct InspectHonorData {
     pub this_week_honor: u32,
     pub last_week_hk: u16,
     pub last_week_honor: u32,
-    /// The ladder position, the reply's `lastWeekRank` — `GetInspectHonorData`'s ninth return.
+    /// The reply's `lastWeekRank`, the ladder standing: `GetInspectHonorData`'s ninth return.
     pub last_week_standing: u32,
     pub lifetime_hk: u32,
     pub lifetime_dk: u32,
-    /// The reply's `highestRank` byte — `GetInspectHonorData`'s twelfth return, which the
-    /// reference names `lifetimeRank`. Internal scale, like every other rank here.
-    ///
-    /// **Passed through, where its self-side twin is suppressed below 5.** The carve pins
-    /// `GetPVPLifetimeStats`'s `cmp al,5; jb` at `0x51a843` and records `0x4c9620` as twelve plain
-    /// pushes with no such gate, so this one is not filtered here. That is a *recorded absence*
-    /// rather than an asserted negative: if a re-read of `0x4c9620` ever turns up the same
-    /// compare, this field's getter is the one place it belongs — and nothing else should be
-    /// harmonised to match it in the meantime.
+    /// The reply's `highestRank`, internal scale: `GetInspectHonorData`'s twelfth return
+    /// (`lifetimeRank`), unfiltered, as `0x4c9620` pushes it with no below-5 gate.
     pub highest_rank: u8,
-    /// The reply's trailing `rankBar` byte — read only by `GetInspectPVPRankProgress`.
+    /// The reply's trailing `rankBar`, read only by `GetInspectPVPRankProgress`.
     pub rank_bar: u8,
 }
 
 impl super::UiScript {
-    /// Drain the PvP-flag toggles queued since the last call — each one is a `CMSG_TOGGLE_PVP`.
-    /// A count rather than a payload: the packet is empty, so two toggles in a frame are two
-    /// sends, not one collapsed intent.
+    /// Drain the queued `TogglePVP` calls, one `CMSG_TOGGLE_PVP` each; the packet is empty, so
+    /// two toggles in a frame are two sends.
     pub fn take_pvp_toggles(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().pvp_toggles)
     }
 
-    /// Queue a toggle from the app side — the `/pvp` slash command. In the reference that slash
-    /// handler *is* Lua (a one-liner over `TogglePVP`); benilla parses slash lines in Rust, so the
-    /// same intent enters the same queue here rather than through the global ([`super::duel`]'s
-    /// `queue_duel_request` reasoning, verbatim).
+    /// Queue a toggle for `/pvp`, which benilla parses in Rust; the reference's `/pvp` is Lua over
+    /// `TogglePVP`.
     pub fn queue_pvp_toggle(&mut self) {
         self.model_mut().pvp_toggles += 1;
     }
 
-    /// Push (or clear, with `None`) the local player's honor snapshot — the six self getters'
-    /// only source. Pushed on the honor descriptor edge, not per frame; it fires no event of its
-    /// own, because the events the reference's pane listens for (`PLAYER_PVP_KILLS_CHANGED`,
-    /// `PLAYER_PVP_RANK_CHANGED`) are the app's to fire alongside the push.
+    /// Push or clear the local player's honor snapshot, the self getters' only source. It fires
+    /// no event: the app fires `PLAYER_PVP_KILLS_CHANGED`/`PLAYER_PVP_RANK_CHANGED` alongside.
     pub fn set_honor(&mut self, honor: Option<HonorState>) {
         self.model_mut().honor = honor;
     }
 
-    /// Push (or clear, with `None`) the last `MSG_INSPECT_HONOR_STATS` reply.
-    ///
-    /// **The presence of this is `HasInspectHonorData`'s answer**, so clearing it is as
-    /// load-bearing as pushing it: the app clears when it drops the inspected player
-    /// (`ClearInspectPlayer`), which is what makes the reference's `OnShow` re-request for the
-    /// next one instead of painting the previous player's numbers. Pair it with the pane's
-    /// `INSPECT_HONOR_UPDATE` event.
-    ///
-    /// **Both arms clear the in-flight latch**, exactly as the engine's two writers do: a reply
-    /// landing zeroes `pending` at `0x4c6f4c`, and re-keying or clearing the slot zeroes it at
-    /// `0x4c6f9d`. So an invalidation also says "whatever was in flight is no longer wanted",
-    /// which is what lets the *next* `RequestInspectHonorData` through.
+    /// Push or clear the last `MSG_INSPECT_HONOR_STATS` reply, paired with the pane's
+    /// `INSPECT_HONOR_UPDATE`. Its presence is `HasInspectHonorData`, so the app clears it on
+    /// `ClearInspectPlayer` and the pane's `OnShow` asks again for the next player. Either way
+    /// the in-flight latch clears, as the engine's reply (`0x4c6f4c`) and re-key (`0x4c6f9d`) do.
     pub fn set_inspect_honor(&mut self, data: Option<InspectHonorData>) {
         let mut model = self.model_mut();
         model.inspect_honor = data;
         model.inspect_honor_pending = false;
     }
 
-    /// Drain the `RequestInspectHonorData` calls queued since the last call — each one is a
-    /// `MSG_INSPECT_HONOR_STATS` send carrying the app's current inspect target guid.
-    ///
-    /// A count, for [`Self::take_pvp_toggles`]'s reason: the binding takes no argument, so there
-    /// is no payload to carry, and the request the *app* addresses is its own inspect target. It
-    /// drains **0 or 1** and never more, because the binding's `pending` latch (`0x4c80b6`)
-    /// refuses a second query until [`Self::set_inspect_honor`] resolves the first — a count kept
-    /// rather than a `bool` because that latch is the engine's, not this signature's, and the app
-    /// loop over it is identical either way.
+    /// Drain the queued `RequestInspectHonorData` calls, each a `MSG_INSPECT_HONOR_STATS` send for
+    /// the app's inspect target. At most 1: the `pending` latch (`0x4c80b6`) refuses another until
+    /// [`Self::set_inspect_honor`] resolves the first.
     pub fn take_inspect_honor_requests(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().inspect_honor_requests)
     }
 
-    /// A PvP rank's localized title for the app's `SMSG_PVP_CREDIT` chat line — the
-    /// `PVP_RANK_<rank>_<team>` GlobalString off the VM's own globals (`team` `0` Horde, `1`
-    /// Alliance), **gendered**: the `_FEMALE` twin when `female`, falling back to the base key.
-    /// A missing or empty key is `None`, never an empty string.
+    /// A rank's localized title for the app's `SMSG_PVP_CREDIT` chat line, `None` if missing or
+    /// empty. Gendered, unlike the pane's: the credit formatter resolves through `0x612bf0`. No
+    /// range check, so rank 19 names "Leader"; `rank` is the internal rank the credit carries
+    /// (`HonorMgr::SendPVPCredit` sends `GetRank().rank`).
     ///
-    /// **Gendered is right *here* and wrong in the pane**, which is the whole reason this is not
-    /// simply `GetPVPRankInfo`'s lookup: the credit formatter resolves through `0x612bf0`
-    /// (§4.3-VERIFIED) while `GetPVPRankInfo` passes gender 0. It shares [`rank_title_gendered`]
-    /// with `UnitPVPName`, the engine's other gendered caller.
-    ///
-    /// The number `SMSG_PVP_CREDIT` carries is the **INTERNAL** rank — the GlobalString index
-    /// itself, which is precisely why it can be passed straight in — and NOT the visual rank the
-    /// badge indexes; see the module doc's "Two ranks". Unlike the pane's binding this path applies
-    /// **no range check**, so rank 19 legitimately names "Leader" here.
-    ///
-    /// Two facts the caller owns, both from the same carve, because neither is expressible in this
-    /// signature: the gender is the **local player's** while the team is the **victim's**
-    /// (`0x625374` hands `0x612bf0` the entry `this`, still the local player), and a victim whose
-    /// team resolves to **−1 emits no line at all** (`0x625321 js` bails the whole formatter) —
-    /// which is a `u8` here precisely so that decision cannot be smuggled into a key that misses.
+    /// The caller owns two facts: the gender is the local player's while the team is the
+    /// victim's (`0x625374`), and a victim whose team is -1 gets no line at all (`0x625321`),
+    /// hence `team: u8`.
     pub fn pvp_rank_title(&self, rank: u8, team: u8, female: bool) -> Option<String> {
         rank_title_gendered(self.lua(), i64::from(rank), i64::from(team), female)
     }
 }
 
-/// Internal rank → **visual** rank, `0x51aa31`'s two-legged subtraction:
-///
-/// ```text
-/// 51aa31  cmp edi,0x5
-/// 51aa36  jge 0x51aa55        ; SIGNED
-/// 51aa38  edi += -5           ; ranks 1..4  -> -4 .. -1
-/// 51aa55  edi += -4           ; ranks 5..18 ->  1 .. 14
-/// ```
-///
-/// Defined on `1..=18` only, because that is the whole domain that reaches it: `GetPVPRankInfo`
-/// range-gates first and answers `0` for everything outside, so there is no "rank 0 maps to 0" case
-/// to write here — the badge stays off an unranked player through the gate, not through this.
-///
-/// The negative leg **subtracts 5**; it does not negate. See the module doc — the server's
-/// `visualRank` negates and the two therefore disagree for exactly ranks 1..4.
+/// Internal rank to visual rank (`0x51aa31`): 5..=18 subtract 4, and 1..=4 subtract 5 to give
+/// -4..=-1 (`0x51aa38`). The server's `visualRank` negates instead (`HonorMgr.cpp:991`), so the
+/// two disagree on ranks 1..=4; this is the client's. Only 1..=18 reach it, as `GetPVPRankInfo`
+/// gates first.
 fn visual_rank(rank: i64) -> i64 {
     if rank >= 5 {
         rank - 4
@@ -298,47 +145,29 @@ fn visual_rank(rank: i64) -> i64 {
     }
 }
 
-/// The f32 constant at `0x8026c8` — the four bytes `81 80 80 3b` — that `GetPVPRankProgress` and
-/// `GetInspectPVPRankProgress` multiply the rank-bar byte by. It is the f32 *nearest* `1/255`
-/// (`0.003921568859368563`, against `1/255`'s `0.00392156862745098`) and it is **not** `1/255`.
+/// The f32 at `0x8026c8` (bytes `81 80 80 3b`) that both rank-progress getters multiply the bar
+/// byte by: the f32 nearest 1/255, `0.003921568859368563`, and not 1/255.
 const RANK_BAR_SCALE: f64 = f32::from_bits(0x3B80_8081) as f64;
 
-/// The rank progress bar's byte → the fraction the reference feeds straight to a `StatusBar` whose
-/// `minValue`/`maxValue` are `0`/`1`.
-///
-/// **A multiply by [`RANK_BAR_SCALE`], not a division by 255, and no clamp** — both halves are the
-/// §5 verdict correcting the natural reading, and both are deliberate:
-///
-/// - `0x51aace` is `fild DWORD` then `fmul DWORD PTR ds:0x8026c8`. Under the client's PC_53 x87
-///   invariant `(double)b * (double)K` and `(double)b / 255.0` differ for **255 of the 256** byte
-///   values (all but 0), so `bar as f64 / 255.0` is bit-wrong on every non-zero input. A byte of
-///   255 comes out as `1.0000000091389835`, *above* 1.0, and a byte of 51 is not exactly 0.2.
-/// - There is no `fcom`, no min/max and no compare anywhere in either function. The value is
-///   `byte * K` and nothing else. Clamping would be tidier and would be a divergence — and it
-///   would hide precisely the >1.0 overshoot that proves the multiply.
-///
-/// A full bar therefore hands `StatusBar:SetValue` a number a hair over its `maxValue`. That is
-/// what the real client does; how our `StatusBar` treats an out-of-range value is that widget's
-/// business, not this binding's.
+/// The rank bar's byte as the fraction the reference feeds a 0..1 `StatusBar`: `fild` then `fmul`
+/// by [`RANK_BAR_SCALE`] (`0x51aace`), with no clamp. It differs from `bar / 255.0` for every byte
+/// but 0, and a full bar gives `1.0000000091389835`, over the bar's maximum.
 fn rank_progress(bar: u8) -> f64 {
     f64::from(bar) * RANK_BAR_SCALE
 }
 
-/// The local player's honor snapshot, or `None` before the first push.
 fn honor(lua: &Lua) -> Option<HonorState> {
     lua.app_data_ref::<Model>().expect("model app_data").honor
 }
 
-/// The last inspect-honor reply, or `None` when none is held.
 fn inspect_honor(lua: &Lua) -> Option<InspectHonorData> {
     lua.app_data_ref::<Model>()
         .expect("model app_data")
         .inspect_honor
 }
 
-/// A GlobalString off the VM's own globals, `None` when it is absent **or empty** — the
-/// no-install / bare-VM path. (`GetPVPRankInfo` tests both explicitly: `0x51aa1c` NULL,
-/// `0x51aa20` empty first byte.)
+/// A GlobalString off the VM's globals, `None` when absent or empty, as `GetPVPRankInfo` tests
+/// both (`0x51aa1c` NULL, `0x51aa20` empty).
 fn global_string(lua: &Lua, key: &str) -> Option<String> {
     lua.globals()
         .get::<Option<String>>(key)
@@ -347,47 +176,26 @@ fn global_string(lua: &Lua, key: &str) -> Option<String> {
         .filter(|s| !s.is_empty())
 }
 
-/// A unit's PvP **team digit** — `0x5efe00`'s tri-state: `0` Horde, `1` Alliance, `-1` for a unit
-/// whose race resolves to no side.
-///
-/// The engine walks race → `ChrRaces` → `FactionTemplate` and tests `[rec+0xc]`'s factionGroupMask
-/// `& 4` → 0, `& 2` → 1, else −1. This crate holds no DBC (decision 0068 §3), so the walk is the
-/// app's and the answer arrives pre-resolved as [`UnitState::pvp_team`](super::UnitState).
-///
-/// **It is not [`UnitState::faction_group`](super::UnitState), which this used to read.** That
-/// field is `UnitFactionGroup`'s — the unit's LIVE `UNIT_FIELD_FACTIONTEMPLATE` — and the two
-/// part company the moment anything moves a unit off its racial faction. A vmangos GM is forced
-/// to template 35 (group mask 0), so every rank title in the Honor tab read `NONE` for a Grand
-/// Marshal while the 1.12 client on the same server read "Grand Marshal" off his unchanged race:
-/// report B378, decision 2227.
-///
-/// −1 needs no special case: it formats into the key, and `PVP_RANK_9_-1` matches no GlobalString.
+/// A unit's PvP team digit, `0x5efe00`'s tri-state from its race (`ChrRaces` to `FactionTemplate`,
+/// group mask `& 4` then `& 2`): 0 Horde, 1 Alliance, -1 no side; resolved by the app as
+/// [`UnitState::pvp_team`](super::UnitState). Not `faction_group`, the live faction template: a
+/// vmangos GM's template 35 has no side while his race keeps one. -1 misses every key.
 fn team_of(u: &super::UnitState) -> i64 {
     i64::from(u.pvp_team)
 }
 
-/// `GetPVPRankInfo`'s **second argument** → the team digit, the engine's three-way dispatch
-/// (`0x51a98c` / `0x51a9af` / `0x51a9c8`, converging on `0x51a9ee mov ebx,eax`):
-///
-/// | argument | team |
-/// |---|---|
-/// | a **number** | the number itself, truncated toward zero — no unit is resolved at all |
-/// | a **string** | that unit token's [`team_of`], or **0** if the token names nothing or names a non-player |
-/// | absent / anything else | the local player's [`team_of`], or **0** if there is no player |
-///
-/// The 0 on the two "not found" edges is the team register's initial value, not a decision — so a
-/// rank asked for on a client with no player snapshot is named off the HORDE list. That is the
-/// engine's behaviour and it is deliberately reproduced; a unit that *is* found but has no side
-/// answers −1 instead, and −1 misses the key ([`team_of`]).
-///
-/// An unrecognised token raises `Unknown unit name`, as `0x515970` does for every unit binding.
+/// `GetPVPRankInfo`'s second argument as a team digit, the engine's three-way dispatch
+/// (`0x51a98c`/`0x51a9af`/`0x51a9c8`): a number is the digit itself, truncated; a string is that
+/// unit's [`team_of`], or 0 if it names nothing or a non-player; anything else is the local
+/// player's, or 0 with no player. That 0 is the team register's initial value, so a miss names
+/// off the Horde list, as in the reference. An unknown token raises, as `0x515970` does.
 fn team_arg(lua: &Lua, v: Value) -> mlua::Result<i64> {
     // `lua_isnumber` before `lua_isstring`, which is what puts a numeric string on the number arm.
     if let Some(n) = lua.coerce_number(v.clone())? {
         return Ok(i64::from(n as i64 as i32));
     }
     let Some(token) = lua.coerce_string(v)? else {
-        // Absent, boolean, table — the local-player preamble.
+        // Absent, boolean or table: the local player.
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         return Ok(model.unit("player").map_or(0, team_of));
     };
@@ -397,35 +205,22 @@ fn team_arg(lua: &Lua, v: Value) -> mlua::Result<i64> {
     Ok(token
         .as_ref()
         .and_then(|t| model.unit(t))
-        // `0x51a9af`'s `shr edx,4; test dl,1` player gate. Applied here, unlike in `UnitPVPRank`
-        // (see there), because on this arm nothing else can tell a creature from a player: a
-        // creature carries a race byte and a faction template like anything else, and the two
-        // misses are different numbers anyway (this gate's 0 against `0x5efe00`'s −1) — it is
-        // this gate the engine reaches first. The cost is the mirror-image miss — an un-enriched player snapshot reads as a non-player — which
-        // lands on a different title rather than on none, and this arm is addon surface: neither
-        // pane passes a second argument at all.
+        // `0x51a9af`'s player gate (`shr edx,4; test dl,1`), applied here unlike in `UnitPVPRank`:
+        // on this arm nothing else tells a creature, which has a race too, from a player.
         .filter(|u| u.is_player)
         .map_or(0, team_of))
 }
 
-/// A rank's localized title, read out of the VM's own globals (see the module doc):
-/// `PVP_RANK_<internal>_<team>`, **ungendered** — `0x703bf0(key, -1, 0)`, the fast path that never
-/// enters Lua.
-///
-/// This is `GetPVPRankInfo`'s lookup (`0x51aa0f push 0`), and the reason the honor panes show a
-/// male/default title to a female character. Do not "fix" it; see the module doc's `_FEMALE`
-/// section.
+/// `PVP_RANK_<internal>_<team>`, ungendered: `GetPVPRankInfo`'s lookup, `0x703bf0(key, -1, 0)`
+/// (`0x51aa0f` pushes gender 0), so the panes show a female character the default title. Do not
+/// gender it: that would diverge from the reference.
 fn rank_title_ungendered(lua: &Lua, rank: i64, team: i64) -> Option<String> {
     global_string(lua, &format!("PVP_RANK_{rank}_{team}"))
 }
 
-/// The same title, **gendered** by the subject — `0x612bf0`: it hands the gender selector (2 male /
-/// 3 female) to `0x703bf0`, which routes into FrameXML's `GetText` and gets `_FEMALE` appended for
-/// 3, then **retries ungendered** when that misses (`0x612c2d`).
-///
-/// Two callers, both verified to be gendered: `UnitPVPName`'s decoration (by the *subject unit*)
-/// and [`UiScript::pvp_rank_title`], the app's `SMSG_PVP_CREDIT` line (by the *local player*, even
-/// though the team digit is the victim's — `0x625374`).
+/// The same title gendered, `0x612bf0`: it passes 2 (male) or 3 (female) to `0x703bf0`, which
+/// asks FrameXML's `GetText` to append `_FEMALE` for 3 (the engine never builds that key), and
+/// retries ungendered on a miss (`0x612c2d`). Used by `UnitPVPName` and the credit line.
 fn rank_title_gendered(lua: &Lua, rank: i64, team: i64, female: bool) -> Option<String> {
     female
         .then(|| global_string(lua, &format!("PVP_RANK_{rank}_{team}_FEMALE")))
@@ -433,14 +228,10 @@ fn rank_title_gendered(lua: &Lua, rank: i64, team: i64, female: bool) -> Option<
         .or_else(|| rank_title_ungendered(lua, rank, team))
 }
 
-/// Fill a **two-`%s` C format string** — the shape `snprintf(buf, size, GlobalString(...), a, b)`
-/// needs, and no more than that shape: the engine pushes exactly two varargs (`0x6093f2 add
-/// esp,0x14`), so any further specifier in a locale's template would read uninitialised stack
-/// there and is simply dropped here.
-///
-/// It substitutes rather than hardcoding `"{a} {b}"` because the template is *install data*: enUS
-/// ships `UNIT_PVP_NAME = "%s %s"`, and a locale that punctuates or spaces it differently must come
-/// out differently. `%%` is a literal `%`; anything else after a `%` is passed through untouched.
+/// Fill a two-`%s` C format string, the install's template (enUS `UNIT_PVP_NAME` is `"%s %s"`);
+/// `%%` is a literal `%` and any other specifier passes through. Deviation: a third `%s` gets an
+/// empty string, because the reference pushes two varargs (`0x6093f2 add esp,0x14`) and would
+/// read uninitialised stack.
 fn format_two_strings(fmt: &str, a: &str, b: &str) -> String {
     let mut out = String::with_capacity(fmt.len() + a.len() + b.len());
     let mut args = [a, b].into_iter();
@@ -463,10 +254,10 @@ fn format_two_strings(fmt: &str, a: &str, b: &str) -> String {
     out
 }
 
-/// `0x609370` — the name builder behind `UnitPVPName`, called with its flag set. `name` is the
-/// unit's plain `UnitName`; see the binding for the three legs and the two divergences.
+/// `0x609370`, the name builder behind `UnitPVPName` (its legs are at the binding); `name` is the
+/// plain `UnitName`.
 fn pvp_name(lua: &Lua, u: &super::UnitState, name: &str, player_level: u32) -> String {
-    // Leg A: a player with a rank. The title is gendered by THIS unit and range-unchecked.
+    // Leg A: a ranked player; the title is gendered by this unit and range-unchecked.
     if u.is_player && u.pvp_rank != 0 {
         let title = rank_title_gendered(lua, i64::from(u.pvp_rank), team_of(u), u.sex == 3);
         if let (Some(fmt), Some(title)) = (global_string(lua, "UNIT_PVP_NAME"), title) {
@@ -496,11 +287,8 @@ fn pvp_name(lua: &Lua, u: &super::UnitState, name: &str, player_level: u32) -> S
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // TogglePVP() — /pvp and the unit popup's PvP row. Takes no argument in 1.12: the *state*
-    // form of the opcode (a one-byte body) has no binding, so there is nothing to pass. The
-    // reference registers it at `0x48d700` and calls it from exactly one place in the whole
-    // shipped 1.12 UI: `SlashCmdList["PVP"]` (ChatFrame.lua); benilla's popup row is a deliberate
-    // second caller — decision 0646 §3.
+    // TogglePVP(): no argument in 1.12, as the opcode's one-byte state form has no binding.
+    // Registered at `0x48d700`; the shipped UI calls it only from `SlashCmdList["PVP"]`.
     g.set(
         "TogglePVP",
         lua.create_function(|lua, ()| {
@@ -511,10 +299,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── The self getters ─────────────────────────────────────────────────────────────────────
-    // Every one of them answers at full arity on every path, zeros included: the reference
-    // destructures the return straight into `format()` arguments, so a short return would leave a
-    // pane painting nils where the real client paints `0`. Before the first push (`None`) they
-    // therefore read as a zeroed snapshot — which is also exactly what a fresh character has.
+    // Full arity on every path: the panes destructure straight into `format()` arguments, so
+    // before the first push they read as a zeroed snapshot, as a new character's would.
 
     // GetPVPSessionStats() → hk, dk.
     g.set(
@@ -525,7 +311,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPYesterdayStats() → hk, dk, contribution (THREE — the weekly pair below is different).
+    // GetPVPYesterdayStats() → hk, dk, contribution.
     g.set(
         "GetPVPYesterdayStats",
         lua.create_function(|lua, ()| {
@@ -538,8 +324,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPThisWeekStats() → hk, contribution. **Two, not three**: the reference destructures
-    // `local hk, contribution = GetPVPThisWeekStats()` and shows no this-week DK column at all.
+    // GetPVPThisWeekStats() → hk, contribution: two, with no this-week dishonorable count.
     g.set(
         "GetPVPThisWeekStats",
         lua.create_function(|lua, ()| {
@@ -548,9 +333,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPLastWeekStats() → hk, dk, contribution, standing. **Four**: the fourth is
-    // `PLAYER_FIELD_LAST_WEEK_RANK`, which is the ladder STANDING, not a rank — the pane prints it
-    // through `format(PVP_RANK_LAST_WEEK, standing)` and never looks a title up for it.
+    // GetPVPLastWeekStats() → hk, dk, contribution, standing: the ladder standing, which the pane
+    // prints through `PVP_RANK_LAST_WEEK`, not a rank.
     g.set(
         "GetPVPLastWeekStats",
         lua.create_function(|lua, ()| {
@@ -564,15 +348,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPLifetimeStats() → hk, dk, highestRank. The third is the HIGHEST LIFETIME rank
-    // (`PLAYER_FIELD_BYTES` byte 3), internal scale — not the current one `UnitPVPRank` answers.
-    //
-    // **A highest rank below 5 is reported as 0, not as itself** (`0x51a843 cmp al,5; jb`,
-    // UNSIGNED, falling into the same `0.0` push the absent-player tail uses). Ranks 1..4 are the
-    // dishonorable titles, and this is why the reference pane shows NONE for a character whose
-    // best was one of them: the suppression is here, in the binding, not in the pane's Lua.
-    // Suppressed to 0 — not to nil — so the pane's `GetPVPRankInfo(highestRank)` still gets a
-    // number.
+    // GetPVPLifetimeStats() → hk, dk, highestRank, the highest lifetime rank (internal). One
+    // below 5 answers 0 (`0x51a843 cmp al,5; jb`, unsigned), so the pane shows NONE for a
+    // dishonorable best; 0, not nil, so its `GetPVPRankInfo(highestRank)` still gets a number.
     g.set(
         "GetPVPLifetimeStats",
         lua.create_function(|lua, ()| {
@@ -590,37 +368,17 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPVPRankProgress() → the bar fraction. A multiply, and unclamped — see `rank_progress`,
-    // which is the whole law of this binding. Absent player → `0.0`, still one value.
+    // GetPVPRankProgress() → the bar fraction (`rank_progress`), 0.0 before the first push.
     g.set(
         "GetPVPRankProgress",
         lua.create_function(|lua, ()| Ok(rank_progress(honor(lua).unwrap_or_default().rank_bar)))?,
     )?;
 
-    // GetPVPRankInfo(rank [, unit]) → rankName, rankNumber — the title off the VM's globals
-    // (module doc) and the VISUAL rank. **Always two values**: every failure edge answers
-    // `nil, 0`, and that nil is what both reference panes branch on to substitute the `NONE`
-    // GlobalString. The first argument is the INTERNAL rank, which is what `UnitPVPRank` and the
-    // `*LifetimeStats`/`InspectHonorData` rank returns all carry.
-    //
-    // Three things the name gives no hint of, all `0x51a930`:
-    //
-    //  * **The accepted range is [1, 18], SIGNED** (`0x51a9f0 cmp edi,1; jl` / `0x51a9f5 cmp
-    //    edi,0x12; jg`). Rank 0 fails it, and so does **rank 19** — the racial-leader "Leader",
-    //    whose `PVP_RANK_19_*` GlobalStrings exist and which the server really does send in
-    //    `SMSG_PVP_CREDIT`. The pane simply cannot name it. That rejection is why the engine's own
-    //    badge table has fifteen entries while FrameXML only ever indexes fourteen: rank 19 →
-    //    `PvPRank15` is reachable from the world-text kill toast (`0x6c7f10`, badge index
-    //    `rank − 5`) and from nowhere on this path.
-    //  * **The second argument exists**, and it is a three-way dispatch, not a unit token: a
-    //    NUMBER is the team digit itself (no unit resolution at all), a STRING is a unit token, and
-    //    absent-or-anything-else means the local player. Lua's own `isnumber` accepts a numeric
-    //    string, so `"1"` takes the number arm and `"player"` the token arm — `coerce_number`
-    //    first is that same order.
-    //  * **A team the engine cannot resolve is 0, not a failure.** An unresolvable token, a
-    //    non-player unit, or no local player leaves the team register at its initial 0 — the HORDE
-    //    list — while a unit that resolves but has no *side* gets −1 and misses the key. The two
-    //    are different answers and this reproduces both.
+    // GetPVPRankInfo(rank [, unit]) → rankName, rankNumber: the title and the visual rank for an
+    // internal rank, always two values; every failure answers `nil, 0`, which both panes turn
+    // into `NONE`. `0x51a930` accepts [1, 18], signed (`0x51a9f0`/`0x51a9f5`), so rank 19,
+    // "Leader", is refused although its GlobalStrings exist and the server sends it. The second
+    // argument is `team_arg`'s three-way dispatch.
     g.set(
         "GetPVPRankInfo",
         lua.create_function(|lua, (rank, unit): (Value, Value)| {
@@ -646,28 +404,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitPVPRank(unit) → the unit's CURRENT rank, internal scale, 0 for no rank.
+    // UnitPVPRank(unit) → the unit's current rank, internal, 0 for none. `0x51a8a0` reads the
+    // named object's own byte (`[+0xe68]+0x1f`, in public `PLAYER_BYTES_3`), which is how the
+    // inspect pane reads a foreign rank. Anything unresolved reads 0, never nil (`0x51a916`); a
+    // non-string argument raises (`0x51a8ac`).
     //
-    // It answers for a FOREIGN unit on purpose: `0x51a8a0` resolves the named token and reads
-    // **that object's own** `[+0xe68]+0x1f` — no cache, no local-player special case — and the byte
-    // lives in `PLAYER_BYTES_3`, a PUBLIC descriptor field the server streams to every observer.
-    // That is why the reference's inspect pane can call `UnitPVPRank("target")` at all, and why a
-    // foreign rank never comes from the inspect reply.
-    //
-    // A creature, a non-player, and an unresolvable token all read **0 — a number, never nil**
-    // (`0x51a916`), so a genuine rank-0 player and an unknown token are indistinguishable to
-    // script. A **non-string argument raises** (`0x51a8ac`), which is why this takes its token
-    // through `string_arg` rather than an `Option`: `UnitPVPRank()` abandons the caller's
-    // statement, it does not answer 0.
-    //
-    // **The engine's player gate (`0x51a8e1 shr edx,4; test dl,1`) is deliberately NOT re-applied
-    // here**, and the reason is a real one rather than laziness: the engine gates on the object's
-    // TYPE MASK, and our nearest equivalent — `UnitState::is_player` — is not that. It is filled by
-    // the app's *guid-keyed enrichment* step, one hop after the descriptor snapshot the rank byte
-    // itself rides on, so a snapshot pushed without enrichment would read as a non-player and
-    // silently zero a real player's rank in a pane that repaints every event. The creature case
-    // needs no gate anyway: a creature has no PLAYER descriptor block, so the byte the app decodes
-    // is already 0 — the reference's own answer for one, by its own path.
+    // The engine's player gate (`0x51a8e1`) is not re-applied: it tests the type mask, while our
+    // `is_player` comes from the app's later guid-keyed enrichment, so a snapshot pushed before
+    // it would zero a real player's rank. A creature has no player block, so its byte is 0.
     g.set(
         "UnitPVPRank",
         lua.create_function(|lua, token: Value| {
@@ -681,31 +425,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitPVPName(unit) → the unit's name, rank-title-decorated — `0x5172b0` into the builder
-    // `0x609370`, whose three legs are:
+    // UnitPVPName(unit) → the name decorated by rank, `0x5172b0` into the builder `0x609370`:
+    //   A  a ranked player: `UNIT_PVP_NAME` filled title first, then name; the title is gendered
+    //      by this unit (`0x5efe60`, `0x612bf0`) with no range check, so rank 19 renders "Leader".
+    //   A′ and, if `PLAYER_BYTES_3` byte 2 (the city-protector title) is set, a second line with
+    //      `PVP_MEDAL<n>`, ungendered.
+    //   B  else a unit passing the civilian predicate (`0x612550`): `PVP_RANK_CIVILIAN`, a space
+    //      and the name. Only creatures reach it.
+    //   C  else the plain name.
+    // No snapshot or an unresolved name answers nil, and so does a token resolving to guid 0,
+    // where the reference returns one value it never pushed (`0x517343`).
     //
-    //   A  a PLAYER with a non-zero rank byte → snprintf(GlobalString("UNIT_PVP_NAME"),
-    //      rankName, plainName). The `add esp,0x14` at `0x6093f2` proves exactly two varargs, and
-    //      the shipped template is "%s %s" — RANK FIRST. The title is `0x5efe60` → `0x612bf0`, so
-    //      it is GENDERED by this unit (unlike the pane's, module doc) and has NO range check, so
-    //      a rank-19 racial leader really does render as "Leader Whoever".
-    //   A′ …and if PLAYER_BYTES_3 byte 2 (the city-protector title) is non-zero, a second line:
-    //      "\n" + GlobalString("PVP_MEDAL<n>"), ungendered.
-    //   B  otherwise, a unit that passes the CIVILIAN predicate `0x612550` →
-    //      GlobalString("PVP_RANK_CIVILIAN") + " " + plainName. Reached by creatures: leg A takes
-    //      every ranked player first, and our snapshot only ever flags creatures civilian.
-    //   C  otherwise the plain name.
-    //
-    // Two edges answer **nil**: no snapshot for the token, and a snapshot whose name has not
-    // resolved. The engine distinguishes a third — a token resolving to GUID 0 returns one value
-    // having pushed nothing (`0x517343`), i.e. non-nil and unspecified. That is an INFERRED
-    // reading of a `luaD_poscall` detail, not a fact about this function, and reproducing an
-    // unspecified value is not something a client can honestly do: we answer nil there too.
-    //
-    // The no-install divergence, stated rather than hidden: with `UNIT_PVP_NAME` or the rank title
-    // missing from `_G`, the engine would snprintf through an empty format and hand back an empty
-    // string. We answer the plain name instead — the decoration is install data, and without the
-    // data there is no decoration.
+    // Deviation: with `UNIT_PVP_NAME` or the title missing from `_G` (no install) this answers
+    // the plain name, where the reference would format an empty string, because the decoration
+    // is install data.
     g.set(
         "UnitPVPName",
         lua.create_function(|lua, token: Value| {
@@ -731,26 +464,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 
     // ── The inspect half ─────────────────────────────────────────────────────────────────────
 
-    // RequestInspectHonorData() — the reference's `InspectHonorFrame_OnShow` calls it iff
-    // `HasInspectHonorData()` is false. Queues the intent; the app pairs it with the guid it is
-    // already inspecting and sends `MSG_INSPECT_HONOR_STATS` (see `NotifyInspect`, which is the
-    // same shape with a token to carry). Zero Lua return values on every path (`0x4c9610`).
+    // RequestInspectHonorData(): `InspectHonorFrame_OnShow` calls it while
+    // `HasInspectHonorData()` is false; the app sends `MSG_INSPECT_HONOR_STATS` for its inspect
+    // target. Zero return values (`0x4c9610`).
     //
-    // **`0x4c80a0` has three silent gates**, and they are the binding's, not the pane's: bail if
-    // data is already held (`0x4c80a6`), bail if a query is already in flight (`0x4c80b6`), bail
-    // if the target guid is zero (`0x4c80c2`). Two of the three are ours to keep:
-    //
-    //  * `hasData` — modelled here even though the reference's own `OnShow` tests it first,
-    //    because it is the engine that refuses; a pane (or addon) that asks anyway must get the
-    //    engine's silence, not a second query.
-    //  * `pending` — modelled here, and this is the one that earns its keep: it is what stops a
-    //    pane shown/hidden/shown before the reply lands sending duplicates.
-    //  * the guid — **not** modelled here and it cannot be: this crate never sees a guid
-    //    (decision 0068 §3). The app drops a queued request with no inspect target, which is the
-    //    same outcome one seam further out. The cost is that our `pending` latches on *queue*
-    //    where the engine's latches on *send*, so a request the app drops leaves the latch set
-    //    until the next `set_inspect_honor` — which the app's own `ClearInspectPlayer` path
-    //    calls, exactly as `0x4c6f70` clears the engine's.
+    // `0x4c80a0` bails silently if data is held (`0x4c80a6`), if a query is in flight (`pending`,
+    // `0x4c80b6`, `[0xb71fcc]`) or if the target guid is 0 (`0x4c80c2`). The first two are here;
+    // the guid is the app's, which drops a request with no target. Our `pending` latches on
+    // queue, not send, so a dropped request holds it until the next `set_inspect_honor`, which
+    // `ClearInspectPlayer` calls as `0x4c6f70` clears the engine's.
     g.set(
         "RequestInspectHonorData",
         lua.create_function(|lua, ()| {
@@ -764,9 +486,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasInspectHonorData() → 1/nil. The latch the request above is gated on: true exactly while a
-    // reply is held, so dropping the inspected player (which clears the push) makes the next
-    // `OnShow` re-request instead of repainting the last player's numbers.
+    // HasInspectHonorData() → 1 or nil: whether a reply is held.
     g.set(
         "HasInspectHonorData",
         lua.create_function(|lua, ()| {
@@ -778,19 +498,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInspectHonorData() → the reference's twelve, in its own order:
+    // GetInspectHonorData() → the reference's twelve, in its order:
     //   sessionHK, sessionDK, yesterdayHK, yesterdayHonor, thisweekHK, thisweekHonor,
     //   lastweekHK, lastweekHonor, lastweekStanding, lifetimeHK, lifetimeDK, lifetimeRank
-    // Note there is no per-period DK past the session pair — the reply carries yesterday/last
-    // week/this week DK halves (vmangos's `unknownOld1/2/3`) and the client surfaces none of them.
-    //
-    // **Twelve on every path, zeros included.** `0x4c9620` is UNGATED — it never consults the
-    // has-data flag; it reads sixteen zero-initialised BSS globals, so a client with no reply held
-    // answers twelve zeros, not nils and not a short return. (The engine's slots are also never
-    // *cleared*: re-keying the cache zeroes the two flags and leaves the data, so the real client
-    // can answer a previous target's numbers here while `HasInspectHonorData` says no. We cannot —
-    // our data and our latch are one `Option` — and that is the one place this pair diverges: it
-    // needs the app to own the flag separately, which is a seam change, not a fix here.)
+    // Twelve on every path: `0x4c9620` never checks for data and reads zero-initialised slots.
+    // Clearing drops the data here, while the reference's re-key zeroes only the flags and can
+    // still answer the previous target's numbers; matching that needs a latch apart from the data.
     g.set(
         "GetInspectHonorData",
         lua.create_function(|lua, ()| {
@@ -814,11 +527,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetInspectPVPRankProgress() → the same bar fraction as GetPVPRankProgress, off the reply's
-    // trailing `rankBar` byte. `0x51ab00` is the same three-instruction kernel over the cached
-    // byte — the `fild`/`fmul ds:0x8026c8`/`fstp` at `0x51ab04` is byte-identical to `0x51aace` —
-    // with no object lookup, no gate and no clamp, so it too reads 0.0 from an empty slot rather
-    // than nil ([`rank_progress`]).
+    // GetInspectPVPRankProgress() → the reply's `rankBar` through `rank_progress`: `0x51ab00`'s
+    // kernel at `0x51ab04` is byte-identical to `0x51aace`, so it too reads 0.0 when empty.
     g.set(
         "GetInspectPVPRankProgress",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/pvp/tests.rs b/crates/benilla-ui/src/script/pvp/tests.rs
index 11bc8bf7..3d71138c 100644
--- a/crates/benilla-ui/src/script/pvp/tests.rs
+++ b/crates/benilla-ui/src/script/pvp/tests.rs
@@ -1,17 +1,11 @@
-//! The PvP + honor binding tests (the parent module is the unit under test).
-//!
-//! Several of these pin facts that look like bugs — the multiply-not-divide rank bar, the
-//! backwards negative visual ranks, rank 19's rejection, the ungendered pane title, the suppressed
-//! sub-5 lifetime rank. They are wow-re `system/ui/scratch/honor-panel-law.md` (§5, 2026-08-21)
-//! and each one would pass just as happily against the wrong reading if it were written loosely,
-//! so they are written tightly on purpose.
+//! Tests for the PvP and honor bindings. Several pin reference facts that look like bugs, so each
+//! is written to fail against the natural reading.
 
 use super::*;
 use crate::script::{UiScript, UnitState};
 
-/// A snapshot whose every number is distinct, so a swapped return order cannot pass: the tens
-/// digit is the block (session 1x, yesterday 2x, this week 3x, last week 4x, lifetime 5x) and
-/// the units digit is the position within it.
+/// Every number distinct, so a swapped return cannot pass: the tens digit is the block (session
+/// 1x to lifetime 5x), the units digit the position in it.
 fn honor_state() -> HonorState {
     HonorState {
         session_hk: 11,
@@ -29,14 +23,13 @@ fn honor_state() -> HonorState {
         lifetime_dk: 52,
         highest_rank: 11,
         rank: 9,
-        // 51 is 0.2 of 255 exactly — which the engine's multiply does NOT produce, and that
-        // near-miss is the whole point of the byte chosen here.
+        // 51/255 is exactly 0.2, which the engine's multiply does not produce.
         rank_bar: 51,
     }
 }
 
-/// The inspect reply's twelve, same trick: 6x is the session block, then one number per return
-/// so the ninth (the standing) cannot hide behind the eighth.
+/// The inspect reply's twelve, distinct in return order, so the ninth (the standing) cannot hide
+/// behind the eighth.
 fn inspect_state() -> InspectHonorData {
     InspectHonorData {
         guid: 0xDEAD_BEEF,
@@ -56,18 +49,15 @@ fn inspect_state() -> InspectHonorData {
     }
 }
 
-/// A female Alliance player carrying rank 9 (visual 5) — the snapshot `UnitPVPRank("player")`
-/// and every title lookup read.
+/// A female Alliance player at rank 9 (visual 5).
 fn player() -> UnitState {
     UnitState {
         exists: true,
         name: Some("Benilla".into()),
         sex: 3, // female
         is_player: true,
-        // Both, because a real Alliance player has both — and they are not the same field.
-        // `faction_group` is `UnitFactionGroup`'s live faction template; `pvp_team` is
-        // `0x5efe00`'s race walk, which is what every rank title is keyed by. The GM-mode test
-        // below is the one that drives them apart.
+        // Both, and they differ: `faction_group` is the live faction template, `pvp_team` the
+        // race walk (`0x5efe00`) that keys every rank title.
         faction_group: Some("Alliance".into()),
         pvp_team: 1,
         pvp_rank: 9,
@@ -82,12 +72,8 @@ fn seated() -> UiScript {
     s
 }
 
-/// Install the rank titles the real `GlobalStrings.lua` puts on `_G` at boot — the only place
-/// `GetPVPRankInfo` reads names from (see the module doc). Both teams, one female twin, the
-/// dishonorable end and rank 19, so the key construction is pinned rather than assumed.
-///
-/// Rank **17** is deliberately left unseated: it is the "the key exists in no locale" case the nil
-/// tests need, now that 19 is a real title here.
+/// The rank titles `GlobalStrings.lua` puts on `_G`: both teams, one female twin, the dishonorable
+/// end and rank 19. Rank 17 is left out as the key no locale has.
 fn seat_rank_globals(s: &UiScript) {
     let g = s.lua().globals();
     for (key, value) in [
@@ -99,7 +85,6 @@ fn seat_rank_globals(s: &UiScript) {
         ("PVP_RANK_9_1", "Sergeant Major"),
         ("PVP_RANK_9_1_FEMALE", "Sergeant Major (f)"),
         ("PVP_RANK_18_1", "Grand Marshal"),
-        // The racial-leader rank: a real GlobalString the pane's binding still refuses.
         ("PVP_RANK_19_1", "Leader"),
         ("PVP_RANK_19_1_FEMALE", "Leader (f)"),
     ] {
@@ -107,8 +92,7 @@ fn seat_rank_globals(s: &UiScript) {
     }
 }
 
-/// The GlobalStrings `UnitPVPName`'s decoration reads — the enUS templates, which is what makes
-/// the two-`%s` substitution testable at all (see [`format_two_strings`]).
+/// The enUS GlobalStrings `UnitPVPName`'s decoration reads.
 fn seat_name_globals(s: &UiScript) {
     let g = s.lua().globals();
     for (key, value) in [
@@ -120,10 +104,7 @@ fn seat_name_globals(s: &UiScript) {
     }
 }
 
-/// **The reference's own destructuring**, line for line — the highest-value assertion
-/// available, because it is the exact code `HonorFrame.lua` runs. Four from last week, three
-/// from yesterday, two from this week: the arities are not symmetric and getting one wrong
-/// shifts a whole pane by a column.
+/// `HonorFrame.lua`'s own destructuring, line for line; the arities differ per period.
 #[test]
 fn the_reference_destructuring_lands_every_value_in_the_right_slot() {
     let s = seated();
@@ -165,10 +146,7 @@ fn the_reference_destructuring_lands_every_value_in_the_right_slot() {
     );
 }
 
-/// **`GetPVPLifetimeStats` suppresses a highest-lifetime rank below 5** (`0x51a843 cmp al,5; jb`),
-/// reporting `0` instead of the true byte — which is why the reference pane shows NONE for a
-/// character whose best rank was one of the four dishonorable ones. The boundary is the whole test:
-/// 4 vanishes, 5 survives.
+/// `0x51a843 cmp al,5; jb`: 4 vanishes, 5 survives.
 #[test]
 fn a_lifetime_rank_below_five_is_reported_as_zero() {
     let mut s = seated();
@@ -184,8 +162,7 @@ fn a_lifetime_rank_below_five_is_reported_as_zero() {
         assert_eq!(third(&s), reported, "highest lifetime rank {highest}");
     }
 
-    // Suppressed to a NUMBER, not to nil: the pane feeds it straight to `GetPVPRankInfo`, which
-    // raises on a non-number.
+    // A number, not nil: the pane passes it to `GetPVPRankInfo`, which raises on a non-number.
     s.set_honor(Some(HonorState {
         highest_rank: 3,
         ..honor_state()
@@ -198,8 +175,7 @@ fn a_lifetime_rank_below_five_is_reported_as_zero() {
         .unwrap());
 }
 
-/// Arity, measured at the host boundary ([`UiScript::arity`]). A getter that returned one value
-/// too many would still pass the destructuring test above; the count is what catches it.
+/// A getter returning one value too many passes the destructuring test; the count catches it.
 #[test]
 fn every_getter_returns_exactly_the_reference_arity() {
     let s = seated();
@@ -218,8 +194,7 @@ fn every_getter_returns_exactly_the_reference_arity() {
     }
 }
 
-/// Before the first push every self getter still answers at full width, with zeros — the
-/// reference feeds these straight into `format()`, so a nil would raise inside its pane.
+/// The reference feeds these straight into `format()`, where a nil would raise.
 #[test]
 fn the_self_getters_answer_zeroed_before_the_first_push() {
     let s = UiScript::new().expect("VM");
@@ -231,22 +206,17 @@ fn the_self_getters_answer_zeroed_before_the_first_push() {
     assert_eq!(s.eval::<f64>("return GetPVPRankProgress()").unwrap(), 0.0);
 }
 
-/// **The rank bar is a MULTIPLY by a slightly-wrong f32 reciprocal, and it does not clamp.**
-///
-/// Written to fail against the natural `byte / 255.0` reading rather than to describe the shape:
-/// the constant is asserted at its bits, every byte is compared to the exact product, and the two
-/// values a divisor would round prettier (51 → 0.2, 255 → 1.0) are asserted **not** to be those
-/// numbers. A full bar comes out *above* 1.0, which is the clamp's absence made visible.
+/// Written to fail against `byte / 255.0`: the constant is checked at its bits, and 51 and 255
+/// must not land on 0.2 and 1.0.
 #[test]
 fn the_rank_bar_multiplies_by_the_f32_reciprocal_and_never_clamps() {
-    // The four bytes at `0x8026c8`, and the fact that makes this test necessary at all.
+    // The four bytes at `0x8026c8`.
     assert_eq!(f64::from(f32::from_bits(0x3B80_8081)), RANK_BAR_SCALE);
     assert_ne!(RANK_BAR_SCALE, 1.0 / 255.0, "the f32 is NOT 1/255");
 
     let mut s = seated();
     let bar = |s: &UiScript| s.eval::<f64>("return GetPVPRankProgress()").unwrap();
 
-    // 51 is the fixture's byte, and 51/255 would be exactly 0.2. The multiply is not.
     assert_eq!(bar(&s), 51.0 * RANK_BAR_SCALE);
     assert_ne!(bar(&s), 0.2, "a divisor would land exactly on 0.2");
     assert_ne!(bar(&s), 51.0 / 255.0);
@@ -259,8 +229,6 @@ fn the_rank_bar_multiplies_by_the_f32_reciprocal_and_never_clamps() {
         assert_eq!(bar(&s), f64::from(byte) * RANK_BAR_SCALE, "byte {byte}");
     }
 
-    // The ends. Zero is the one input the two readings agree on; a full bar OVERSHOOTS, and
-    // nothing clamps it back.
     s.set_honor(Some(HonorState {
         rank_bar: 0,
         ..honor_state()
@@ -281,9 +249,7 @@ fn the_rank_bar_multiplies_by_the_f32_reciprocal_and_never_clamps() {
     );
 }
 
-/// **Rank 0 names nothing.** There is no `PVP_RANK_0_*` GlobalString, and both reference panes
-/// depend on that nil to fall back to `NONE` — so this runs the fallback the way the pane
-/// writes it, not just the nil.
+/// Runs the panes' own `NONE` fallback, not just the nil.
 #[test]
 fn rank_zero_names_nothing_and_the_pane_falls_back_to_none() {
     let s = seated();
@@ -305,19 +271,13 @@ fn rank_zero_names_nothing_and_the_pane_falls_back_to_none() {
     );
 }
 
-/// The title key: the team digit (0 Horde / 1 Alliance) off the player's faction group — and
-/// **the pane's title is NOT gendered**, which is the half a plausible implementation gets wrong.
-///
-/// `GetPVPRankInfo` hands `0x703bf0` gender 0 (`0x51aa0f`) and takes the fast path, so a female
-/// character sees the male/default title in her own honor pane while the `_FEMALE` twin sits right
-/// there on `_G`. The seated player is female and a twin exists for rank 9 precisely so that this
-/// test fails the moment somebody "fixes" the resolver to prefer it.
+/// `GetPVPRankInfo` passes gender 0 (`0x51aa0f`), so a female character gets the default title
+/// with the `_FEMALE` twin right there on `_G`.
 #[test]
 fn the_pane_title_is_keyed_by_team_and_is_never_gendered() {
     let mut s = seated();
     seat_rank_globals(&s);
 
-    // Female Alliance → the BASE key, with `PVP_RANK_9_1_FEMALE` seated and ignored.
     assert_eq!(
         s.eval::<String>("return (GetPVPRankInfo(9))").unwrap(),
         "Sergeant Major"
@@ -328,15 +288,12 @@ fn the_pane_title_is_keyed_by_team_and_is_never_gendered() {
         "the twin is on _G — the binding declines it, it does not miss it"
     );
 
-    // Male Alliance → the same answer, which is the point.
     s.set_unit("player", Some(UnitState { sex: 2, ..player() }));
     assert_eq!(
         s.eval::<String>("return (GetPVPRankInfo(9))").unwrap(),
         "Sergeant Major"
     );
 
-    // Horde is team 0 — an entirely different word list, which is why an unknown side must
-    // not be guessed at.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -352,21 +309,13 @@ fn the_pane_title_is_keyed_by_team_and_is_never_gendered() {
     );
 }
 
-/// The **Rust-side** title lookup the app's `SMSG_PVP_CREDIT` line uses shares the key
-/// construction with the binding and **deliberately differs on gender**: the credit formatter
-/// resolves through `0x612bf0` with the local player's gender selector, the pane's binding passes
-/// 0. One function each, and the pair of them is asserted apart here so neither drifts into the
-/// other.
-///
-/// The credit packet carries the INTERNAL rank, which is why its number goes straight in with no
-/// visual conversion — and unlike the binding this path applies **no range check**, so rank 19
-/// names "Leader" here and `(nil, 0)` there.
+/// The credit line's lookup resolves through `0x612bf0` with the local player's gender, where the
+/// binding passes 0, and has no range check, so rank 19 names "Leader" here.
 #[test]
 fn the_rust_side_title_lookup_is_gendered_where_the_binding_is_not() {
     let s = seated();
     seat_rank_globals(&s);
 
-    // The app names a side and a sex outright — no player snapshot involved.
     assert_eq!(
         s.pvp_rank_title(9, 0, false).as_deref(),
         Some("Senior Sergeant")
@@ -389,15 +338,13 @@ fn the_rust_side_title_lookup_is_gendered_where_the_binding_is_not() {
         "same key construction once the gender is out of it"
     );
 
-    // Gendered means PREFERRED, not required: a rank with no twin falls back to the base key.
+    // Gendered means preferred: a rank with no twin falls back to the base key.
     assert_eq!(s.pvp_rank_title(5, 1, true).as_deref(), Some("Private"));
 
-    // No range check on this path — rank 19 is a name here and a refusal in the binding.
     assert_eq!(s.pvp_rank_title(19, 1, false).as_deref(), Some("Leader"));
     assert_eq!(s.pvp_rank_title(19, 1, true).as_deref(), Some("Leader (f)"));
     assert!(s.eval::<bool>("return GetPVPRankInfo(19) == nil").unwrap());
 
-    // Same nil semantics either side: rank 0, an absent key, and an empty one.
     assert_eq!(s.pvp_rank_title(0, 1, false), None);
     assert_eq!(s.pvp_rank_title(17, 1, false), None, "no PVP_RANK_17_1");
     s.lua().globals().set("PVP_RANK_17_1", "").expect("global");
@@ -408,14 +355,11 @@ fn the_rust_side_title_lookup_is_gendered_where_the_binding_is_not() {
     );
 }
 
-/// A missing GlobalString — the bare VM with no install behind it — reads as **nil**, never as
-/// an empty string and never as a raise: the panes' `if not rankName` fallback is the only
-/// thing standing between that and a blank title.
+/// The panes' `if not rankName` fallback needs a nil, not an empty string or a raise.
 #[test]
 fn a_missing_rank_global_reads_nil_not_empty() {
     let s = seated(); // no rank globals seated at all
     assert!(s.eval::<bool>("return GetPVPRankInfo(9) == nil").unwrap());
-    // …and so does an empty one.
     s.lua().globals().set("PVP_RANK_9_1", "").expect("global");
     assert!(s.eval::<bool>("return GetPVPRankInfo(9) == nil").unwrap());
     // A player with no side names nothing either, rather than picking a list.
@@ -431,12 +375,9 @@ fn a_missing_rank_global_reads_nil_not_empty() {
     assert!(s.eval::<bool>("return GetPVPRankInfo(9) == nil").unwrap());
 }
 
-/// **The team digit is NOT the faction group** — report B378 at the binding level (decision 2227).
-///
-/// `UnitFactionGroup` reads the unit's live `UNIT_FIELD_FACTIONTEMPLATE` (`0x516630`) and the rank
-/// title's team digit reads the unit's RACE (`0x5efe00`), so a vmangos GM — template 35, group
-/// mask 0 — has no side and keeps his rank. Both `0x5efe00` surfaces are asserted here: the
-/// binding's key and `UnitPVPName`'s decoration (`0x5efe60`, the same walk).
+/// `UnitFactionGroup` reads the live faction template (`0x516630`) and the title's team digit the
+/// race (`0x5efe00`), so a vmangos GM (template 35, no side) keeps his title, in both the key and
+/// `UnitPVPName`'s decoration (`0x5efe60`).
 #[test]
 fn a_sideless_player_still_has_a_team_digit_because_his_race_has_one() {
     let mut s = seated();
@@ -448,10 +389,10 @@ fn a_sideless_player_still_has_a_team_digit_because_his_race_has_one() {
     s.set_unit(
         "player",
         Some(UnitState {
-            // `.gm on` — the template names nothing …
+            // `.gm on`: the template names nothing…
             faction_group: None,
             faction_group_localized: None,
-            // … and the race still names Alliance.
+            // …and the race still names Alliance.
             pvp_team: 1,
             sex: 2,
             pvp_rank: 18,
@@ -468,7 +409,7 @@ fn a_sideless_player_still_has_a_team_digit_because_his_race_has_one() {
         "Grand Marshal Benilla",
         "and the name decoration reads the same digit"
     );
-    // The control: a unit whose RACE resolves to nothing is still −1, and −1 still misses.
+    // The control: a unit whose race has no side is -1, and -1 misses.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -484,11 +425,8 @@ fn a_sideless_player_still_has_a_team_digit_because_his_race_has_one() {
     );
 }
 
-/// The internal→visual conversion across its whole range — **and the negative half runs the
-/// opposite way from the server's `visualRank`**, which is the assertion that matters: rank 1 is
-/// −4 and rank 4 is −1, because `0x51aa38` subtracts 5 rather than negating. vmangos's
-/// `HonorMgr.cpp:991` gives 1 → −1 and 4 → −4; the binding's second return is the client's, and
-/// this pins it so nobody restores the server's arithmetic here.
+/// `0x51aa38` subtracts 5 rather than negating, so rank 1 is -4 and rank 4 is -1, the opposite of
+/// vmangos's `visualRank` (`HonorMgr.cpp:991`).
 #[test]
 fn the_visual_rank_arithmetic_runs_backwards_through_the_dishonorable_ranks() {
     for (internal, visual) in [
@@ -501,7 +439,7 @@ fn the_visual_rank_arithmetic_runs_backwards_through_the_dishonorable_ranks() {
         (18, 14),
     ] {
         assert_eq!(visual_rank(internal), visual, "internal {internal}");
-        // The server's form, stated as the thing this is NOT.
+        // The server's form, which this is not.
         let servers = if internal > 4 {
             internal - 4
         } else {
@@ -514,8 +452,6 @@ fn the_visual_rank_arithmetic_runs_backwards_through_the_dishonorable_ranks() {
         );
     }
 
-    // …and the binding reports the same number, which is what indexes the badge texture: only a
-    // positive one is drawn, so all four dishonorable ranks hide it.
     let s = seated();
     seat_rank_globals(&s);
     for (internal, visual) in [(1i64, -4i64), (4, -1), (5, 1), (18, 14)] {
@@ -530,14 +466,7 @@ fn the_visual_rank_arithmetic_runs_backwards_through_the_dishonorable_ranks() {
     }
 }
 
-/// **The range gate is `[1, 18]`, so rank 19 — "Leader" — is refused**, GlobalString and all.
-///
-/// The consequence is real and visible: the engine's own badge table has fifteen entries because
-/// rank 19 → `PvPRank15` is reachable from the world-text kill toast (`0x6c7f10`, index
-/// `rank − 5`), never from this binding, which is why FrameXML only ever names fourteen.
-///
-/// Both failure edges answer `(nil, 0)` — **two** values, never one — because the panes destructure
-/// a pair and then branch on the nil.
+/// Both failure edges answer two values, `(nil, 0)`, since the panes destructure a pair.
 #[test]
 fn the_range_gate_refuses_rank_zero_and_rank_nineteen_alike() {
     let s = seated();
@@ -558,19 +487,15 @@ fn the_range_gate_refuses_rank_zero_and_rank_nineteen_alike() {
         );
     }
 
-    // The refusal is the GATE, not a missing key: `PVP_RANK_19_1` is right there.
+    // The refusal is the gate, not a missing key: `PVP_RANK_19_1` is seated.
     assert_eq!(s.eval::<String>("return PVP_RANK_19_1").unwrap(), "Leader");
-    // …and the ends of the accepted range do answer.
     assert!(s.eval::<bool>("return GetPVPRankInfo(1) ~= nil").unwrap());
     assert!(s.eval::<bool>("return GetPVPRankInfo(18) ~= nil").unwrap());
 }
 
-/// **The second argument**, which the reference's own panes never pass and which is therefore easy
-/// to miss entirely: a NUMBER is the team digit itself, a STRING is a unit token, and absent means
-/// the local player.
 #[test]
 fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
-    let mut s = seated(); // an ALLIANCE player
+    let mut s = seated(); // an Alliance player
     seat_rank_globals(&s);
     s.set_unit(
         "target",
@@ -585,12 +510,12 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         }),
     );
 
-    // Absent → the local player's side.
+    // Absent: the local player's side.
     assert_eq!(
         s.eval::<String>("return (GetPVPRankInfo(9))").unwrap(),
         "Sergeant Major"
     );
-    // A NUMBER is the digit, with no unit resolved at all — including a digit the player is not.
+    // A number is the digit, with no unit resolved, even one the player is not.
     assert_eq!(
         s.eval::<String>("return (GetPVPRankInfo(9, 0))").unwrap(),
         "Senior Sergeant"
@@ -599,7 +524,7 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         s.eval::<String>("return (GetPVPRankInfo(9, 1))").unwrap(),
         "Sergeant Major"
     );
-    // Lua's `isnumber` accepts a numeric string, so "0" is a DIGIT and not a token.
+    // `lua_isnumber` accepts a numeric string, so "0" is a digit, not a token.
     assert_eq!(
         s.eval::<String>(r#"return (GetPVPRankInfo(9, "0"))"#)
             .unwrap(),
@@ -610,12 +535,11 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         s.eval::<String>("return (GetPVPRankInfo(9, 0.9))").unwrap(),
         "Senior Sergeant"
     );
-    // A team digit no GlobalString matches simply misses.
     assert!(s
         .eval::<bool>("return GetPVPRankInfo(9, 7) == nil")
         .unwrap());
 
-    // A STRING is a unit token — the FOREIGN unit's side, not the player's.
+    // A string is a unit token: the foreign unit's side, not the player's.
     assert_eq!(
         s.eval::<String>(r#"return (GetPVPRankInfo(9, "target"))"#)
             .unwrap(),
@@ -623,8 +547,7 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         "Thrall is Horde, so his ladder names rank 9"
     );
 
-    // A token that names nothing, and a token naming a non-player, both fall to team 0 — the
-    // engine's uninitialised team register, not a failure.
+    // A token naming nothing or a non-player falls to team 0, the register's initial value.
     assert_eq!(
         s.eval::<String>(r#"return (GetPVPRankInfo(9, "mouseover"))"#)
             .unwrap(),
@@ -646,8 +569,7 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         "a non-player is gated out before its side is read"
     );
 
-    // A unit that resolves but has NO side is −1, which misses the key — a different answer from
-    // the not-found 0 above, and the one the panes render as NONE.
+    // A unit that resolves with no side is -1 and misses the key, unlike the not-found 0 above.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -661,14 +583,12 @@ fn get_pvp_rank_info_takes_a_second_argument_three_different_ways() {
         .eval::<bool>(r#"return GetPVPRankInfo(9, "target") == nil"#)
         .unwrap());
 
-    // An unrecognised token raises, as it does for every unit binding.
     assert!(s
         .eval::<Option<String>>(r#"return (GetPVPRankInfo(9, "wombat"))"#)
         .is_err());
 }
 
-/// The first argument's `Usage:` gate — `0x51a930` tests `lua_isnumber` and **raises**, abandoning
-/// the caller's statement. It is not a `(nil, 0)` edge, and the two are not interchangeable.
+/// `0x51a930` tests `lua_isnumber` and raises: not a `(nil, 0)` edge.
 #[test]
 fn get_pvp_rank_info_raises_without_a_numeric_first_argument() {
     let s = seated();
@@ -685,14 +605,13 @@ fn get_pvp_rank_info_raises_without_a_numeric_first_argument() {
             "{call}: {err}"
         );
     }
-    // A numeric string is a number to Lua, so it does NOT raise.
+    // A numeric string is a number to Lua, so it does not raise.
     assert!(s
         .eval::<Option<String>>(r#"return (GetPVPRankInfo("9"))"#)
         .is_ok());
 }
 
-/// `UnitPVPRank` must answer for a **foreign** unit: `PLAYER_BYTES_3` is PUBLIC, and the
-/// reference's inspect pane calls it as `UnitPVPRank("target")`. An unknown token reads 0.
+/// `PLAYER_BYTES_3` is public, and the reference's inspect pane calls `UnitPVPRank("target")`.
 #[test]
 fn unit_pvp_rank_answers_for_a_foreign_unit() {
     let mut s = seated();
@@ -713,9 +632,8 @@ fn unit_pvp_rank_answers_for_a_foreign_unit() {
         14
     );
     assert_eq!(s.eval::<i64>(r#"return UnitPVPRank("player")"#).unwrap(), 9);
-    // A creature reads 0 because it has no PLAYER descriptor block to decode a rank byte from —
-    // the engine's own path to the same answer. The binding does NOT re-gate on `is_player`; see
-    // the binding for why our `is_player` is not the engine's type mask.
+    // A creature reads 0 because it has no player descriptor block to decode a rank from; the
+    // binding does not re-gate on `is_player`.
     s.set_unit(
         "mouseover",
         Some(UnitState {
@@ -735,37 +653,30 @@ fn unit_pvp_rank_answers_for_a_foreign_unit() {
         0,
         "no snapshot reads 0, like every other numeric Unit* getter"
     );
-    // A non-string argument RAISES (`0x51a8ac`) — it does not answer 0. A number is a string to
-    // Lua, so it resolves the token "5" and raises for a different reason: an unknown token.
+    // A non-string argument raises (`0x51a8ac`) rather than answering 0.
     assert!(s.eval::<i64>("return UnitPVPRank()").is_err());
     assert!(s.eval::<i64>("return UnitPVPRank({})").is_err());
 }
 
-/// **`UnitPVPName`'s three legs** (`0x609370`), which is the whole binding: the decorated player
-/// name, the civilian prefix, and the plain name.
-///
-/// The template is `UNIT_PVP_NAME` off `_G` and it is filled rank-FIRST — `add esp,0x14` proves two
-/// varargs and enUS ships `"%s %s"`. The title here **is** gendered (by this unit), which is the
-/// opposite of the pane's and the reason the two lookups are separate functions.
+/// `UnitPVPName`'s three legs (`0x609370`); the title fills `UNIT_PVP_NAME` rank first and is
+/// gendered by this unit, unlike the pane's.
 #[test]
 fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
     let mut s = seated();
     seat_rank_globals(&s);
     seat_name_globals(&s);
 
-    // Leg A — the seated player is a female Alliance rank 9, so the FEMALE twin wins here.
+    // Leg A: the seated player is a female Alliance rank 9, so the `_FEMALE` twin wins.
     assert_eq!(
         s.eval::<String>(r#"return UnitPVPName("player")"#).unwrap(),
         "Sergeant Major (f) Benilla"
     );
-    // …male takes the base key, and the order is rank then name either way.
     s.set_unit("player", Some(UnitState { sex: 2, ..player() }));
     assert_eq!(
         s.eval::<String>(r#"return UnitPVPName("player")"#).unwrap(),
         "Sergeant Major Benilla"
     );
 
-    // No range check on this path: the racial-leader rank really does render.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -780,7 +691,7 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
         "rank 19 names here and is refused by GetPVPRankInfo"
     );
 
-    // Leg A′ — the city-protector medal, appended on its own line.
+    // Leg A′: the city-protector medal, on its own line.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -794,7 +705,7 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
         "Sergeant Major Benilla\nGuardian of Stormwind"
     );
 
-    // Leg C — an unranked player is just a name, and so is a plain creature.
+    // Leg C: an unranked player is just a name, and so is a plain creature.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -820,8 +731,8 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
         "Timber Wolf"
     );
 
-    // Leg B — the civilian prefix, on the same `0x612550` gate the tooltip's CIVILIAN line uses:
-    // PvP-flagged, hostile and grey to the player. A friendly civilian is still just a name.
+    // Leg B: the civilian prefix, on the tooltip's `0x612550` gate: PvP-flagged, hostile and grey
+    // to the player.
     s.set_player_req_state(crate::script::PlayerReqState {
         level: 30,
         ..Default::default()
@@ -853,7 +764,6 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
         "…nor an unflagged one"
     );
 
-    // The two nil edges, and the raise.
     assert!(s
         .eval::<bool>(r#"return UnitPVPName("mouseover") == nil"#)
         .unwrap());
@@ -873,9 +783,7 @@ fn unit_pvp_name_decorates_a_ranked_player_and_falls_back_three_ways() {
     assert!(s.eval::<String>("return UnitPVPName()").is_err());
 }
 
-/// With no install behind the VM there is no template and no title, and the decoration is install
-/// data: we answer the **plain name**. (The engine would snprintf through an empty format and hand
-/// back an empty string — a stated divergence, not an oversight.)
+/// No install: the plain name, where the reference would format an empty string.
 #[test]
 fn unit_pvp_name_without_the_globalstrings_answers_the_plain_name() {
     let s = seated(); // nothing seated on _G
@@ -883,7 +791,7 @@ fn unit_pvp_name_without_the_globalstrings_answers_the_plain_name() {
         s.eval::<String>(r#"return UnitPVPName("player")"#).unwrap(),
         "Benilla"
     );
-    // The template alone is not enough — the title has to resolve too.
+    // The template alone is not enough: the title has to resolve too.
     s.lua()
         .globals()
         .set("UNIT_PVP_NAME", "%s %s")
@@ -894,9 +802,7 @@ fn unit_pvp_name_without_the_globalstrings_answers_the_plain_name() {
     );
 }
 
-/// The template is *filled*, not assumed: a locale that punctuates `UNIT_PVP_NAME` differently
-/// comes out differently, and a `%%` is a literal per cent. Two varargs is the engine's own limit
-/// (`add esp,0x14`), so a third specifier has nothing to consume.
+/// Two varargs is the engine's limit (`add esp,0x14`), so a third `%s` has nothing to consume.
 #[test]
 fn the_two_string_template_is_substituted_not_hardcoded() {
     assert_eq!(format_two_strings("%s %s", "Rank", "Name"), "Rank Name");
@@ -924,8 +830,6 @@ fn the_two_string_template_is_substituted_not_hardcoded() {
     );
 }
 
-/// The inspect latch: false before any reply, true while one is held, false again once the app
-/// clears it — which is what makes the reference's `OnShow` re-request for the next player.
 #[test]
 fn has_inspect_honor_data_latches_on_the_push_and_clears_with_it() {
     let mut s = seated();
@@ -935,9 +839,7 @@ fn has_inspect_honor_data_latches_on_the_push_and_clears_with_it() {
     s.set_inspect_honor(Some(inspect_state()));
     assert!(s.eval::<bool>(held()).unwrap());
 
-    // `0x4c95e0` pushes the NUMBER 1, not a boolean — one value either way, and the truthy arm is
-    // `1` rather than `true`. (The carve says `lua_pushnumber(1.0)`; in a VM whose numbers are all
-    // doubles there is no observable integer/float distinction, and `tostring` proves it.)
+    // `0x4c95e0` pushes the number 1 (`lua_pushnumber(1.0)`), not a boolean.
     assert_eq!(
         s.eval::<String>("return type(HasInspectHonorData())")
             .unwrap(),
@@ -979,10 +881,8 @@ fn get_inspect_honor_data_returns_the_twelve_in_the_reference_order() {
     );
 }
 
-/// **With no reply held `GetInspectHonorData` still answers twelve — zeros.** `0x4c9620` is
-/// UNGATED: it never consults the has-data flag, and the sixteen globals it reads are
-/// zero-initialised BSS. A short return would leave the pane painting `SetText(nil)` — a blank row
-/// — where the real client paints a `0` row, and the two look different on screen.
+/// `0x4c9620` is ungated and reads zero-initialised slots; a short return would paint blank rows
+/// where the reference paints zeros.
 #[test]
 fn get_inspect_honor_data_answers_twelve_zeros_when_no_reply_is_held() {
     let mut s = seated();
@@ -999,15 +899,13 @@ fn get_inspect_honor_data_answers_twelve_zeros_when_no_reply_is_held() {
     assert!(s
         .eval::<bool>("return (GetInspectHonorData()) == 0")
         .unwrap());
-    // The bar reads its own zeroed byte, for the same reason.
     assert_eq!(
         s.eval::<f64>("return GetInspectPVPRankProgress()").unwrap(),
         0.0
     );
 
-    // And after the app drops the reply it is zeros again — our `Option` is the latch AND the
-    // data, where the engine keeps them apart and would answer the previous target's numbers
-    // here (§5.1/§5.2: re-keying zeroes the two flags and leaves the sixteen slots alone).
+    // Zeros again after a clear; the reference would still hold the previous target's numbers
+    // (`0x4c6f70` zeroes only the flags).
     s.set_inspect_honor(Some(inspect_state()));
     s.set_inspect_honor(None);
     assert_eq!(
@@ -1017,27 +915,24 @@ fn get_inspect_honor_data_answers_twelve_zeros_when_no_reply_is_held() {
     );
 }
 
-/// The two intent queues drain to the app and reset — and the honor query **does not queue twice**:
-/// `0x4c80a0` bails while one is in flight (`pending`) and bails again once data is held
-/// (`hasData`), which is what stops a pane shown/hidden/shown sending duplicates. The PvP toggle
-/// has no such latch and genuinely does send twice.
+/// `0x4c80a0` refuses a query while one is in flight and once data is held; `TogglePVP` has no
+/// latch.
 #[test]
 fn the_intent_queues_drain_and_the_honor_query_refuses_to_double_up() {
     let mut s = seated();
     assert_eq!(s.take_inspect_honor_requests(), 0);
 
-    // Two calls, ONE query: the second sees `pending`.
+    // Two calls, one query: the second sees `pending`.
     s.eval::<()>("RequestInspectHonorData() RequestInspectHonorData()")
         .unwrap();
     assert_eq!(s.take_inspect_honor_requests(), 1);
     assert_eq!(s.take_inspect_honor_requests(), 0);
 
-    // Still latched after the drain — the app has sent, nothing has replied.
+    // Still latched after the drain: sent, not yet answered.
     s.eval::<()>("RequestInspectHonorData()").unwrap();
     assert_eq!(s.take_inspect_honor_requests(), 0, "still in flight");
 
-    // The reply clears `pending` — and immediately sets `hasData`, so the next ask is refused for
-    // the *other* reason.
+    // The reply clears `pending` and sets `hasData`, which refuses the next ask instead.
     s.set_inspect_honor(Some(inspect_state()));
     s.eval::<()>("RequestInspectHonorData()").unwrap();
     assert_eq!(s.take_inspect_honor_requests(), 0, "data already held");
diff --git a/crates/benilla-ui/src/script/quest.rs b/crates/benilla-ui/src/script/quest.rs
index a151f789..456dce4a 100644
--- a/crates/benilla-ui/src/script/quest.rs
+++ b/crates/benilla-ui/src/script/quest.rs
@@ -1,80 +1,48 @@
-//! The questgiver bindings (decision 0088) — the Era-shaped quest-dialog surface, the same two-way
-//! seam as [`super::gossip`]/[`super::merchant`]: the app pushes a **quest panel snapshot**
-//! ([`UiScript::set_quest`] — the greeting/detail/progress/reward text + item rows already resolved
-//! from the wire), and the Lua `AcceptQuest`/`CompleteQuest`/`GetQuestReward`/`SelectActiveQuest`/…
-//! calls queue outbound **intents** the app drains ([`UiScript::take_quest_selects`] /
-//! [`UiScript::take_quest_actions`]). The engine holds no quest knowledge — a row is "a name, an
-//! icon, a count, a quality, and whether it's usable"; a button press is a bare intent the app maps
-//! to `(npc, questId)` from its own live state.
-//!
-//! ## The Era API shape
-//!
-//! 1.12's `QuestFrame.lua` reads flat getters positionally, one panel at a time: the greeting panel
-//! walks `GetNumActiveQuests()`/`GetActiveTitle(i)` (+ the available twins), the detail panel reads
-//! `GetTitleText()`/`GetQuestText()`/`GetObjectiveText()`, the progress panel reads
-//! `GetProgressText()`/`IsQuestCompletable()`/`GetNumQuestItems()`/`GetQuestItemInfo("required",i)`,
-//! the reward panel reads `GetRewardText()`/`GetNumQuestChoices()`/`GetNumQuestRewards()`/
-//! `GetRewardMoney()`/`GetQuestItemInfo("choice"|"reward",i)`. Benilla keeps those exact names on a
-//! single pushed [`QuestState`]; which panel is live is [`QuestState::panel`], surfaced to the XML
-//! through the `QUEST_GREETING`/`QUEST_DETAIL`/`QUEST_PROGRESS`/`QUEST_COMPLETE` events the app
-//! fires. `GetRewardSpell()` returns `nil` in v1 (spell-reward rows are out of scope, decision 0088).
+//! The questgiver bindings: the app pushes the open panel ([`UiScript::set_quest`]), and the panel
+//! verbs queue selects and button intents it drains. One [`QuestState`] serves the flat getters
+//! `QuestFrame.lua` reads on each panel; the app fires `QUEST_GREETING`, `QUEST_DETAIL`,
+//! `QUEST_PROGRESS` or `QUEST_COMPLETE` for the live one.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::binding_abi::flag;
 use super::Model;
 
-/// Which of the four questgiver sub-panels a [`QuestState`] is for (the app sets it from the wire
-/// packet; the XML's event routing mirrors it).
+/// Which questgiver panel a [`QuestState`] is for, set from the wire packet.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum QuestPanel {
-    /// `SMSG_QUESTGIVER_QUEST_LIST` — the multi-quest greeting (active + available lists).
+    /// `SMSG_QUESTGIVER_QUEST_LIST`: the greeting, with the active and available lists.
     Greeting,
-    /// `SMSG_QUESTGIVER_QUEST_DETAILS` — the accept panel.
+    /// `SMSG_QUESTGIVER_QUEST_DETAILS`: the accept panel.
     Detail,
-    /// `SMSG_QUESTGIVER_REQUEST_ITEMS` — the turn-in progress panel.
+    /// `SMSG_QUESTGIVER_REQUEST_ITEMS`: the turn-in progress panel.
     Progress,
-    /// `SMSG_QUESTGIVER_OFFER_REWARD` — the reward panel.
+    /// `SMSG_QUESTGIVER_OFFER_REWARD`: the reward panel.
     Reward,
 }
 
-/// One quest item row (choice reward / fixed reward / required item), resolved by the app from the
-/// wire triple + its item stores. Plain data — 1-based order is its position in the owning vector.
+/// One choice, reward or required item row; its 1-based index is its place in its list.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestItemView {
-    /// Item name (`GetQuestItemInfo`'s first return); `None` while the ask-once template query is in
-    /// flight (the API reports `nil`, the XML shows a placeholder).
+    /// `None`, answered as nil, while the item template is in flight.
     pub name: Option<String>,
-    /// Icon texture path (`Interface\Icons\…`); `None` while the template answer is in flight (the
-    /// icon comes from the wire display id, so it's usually present immediately).
     pub texture: Option<String>,
-    /// Stack count for the row (`numItems`).
     pub count: u32,
-    /// Item quality (0 poor .. 5 legendary); colours the reward name. `1` (common/white) when the
-    /// template hasn't landed.
+    /// 0 poor to 5 legendary; 1 until the template lands.
     pub quality: u32,
-    /// The item id — the shared item-tooltip store's key (`BenillaGetItemStats`); `0` while the
-    /// wire row hasn't resolved. A benilla extension: the era 5-tuple never carried it (tooltip
-    /// content was C++'s alone), so it rides as a TRAILING 6th return, invisible to era callers.
+    /// The item id the quest tooltips render by; 0 until the wire row resolves.
     pub item_id: u32,
-    /// Whether the reward is usable by the player's class/race — v1 always `true` (soft gray only,
-    /// the server stays authoritative).
+    /// Whether the player can use the item; stock tints the row red when not
+    /// (`QuestFrame.lua:393`). The app always sends `true`.
     pub usable: bool,
-    /// The full escaped `|cff…|Hitem:…|h[Name]|h|r` link (`GetQuestItemLink` /
-    /// `GetQuestLogItemLink` serve it) — the ctrl/shift click arms' payload (decisions 1059/1060).
-    /// `None` until the ask-once item template lands: the link is built from the name **and** the
-    /// quality, and neither is known before then, exactly like [`super::InvSlotView::link`].
+    /// The escaped item link `GetQuestItemLink` and `GetQuestLogItemLink` serve; `None` until the
+    /// template lands, since it embeds the name and the quality.
     pub link: Option<String>,
 }
 
-/// One open questgiver panel: the active sub-panel plus every field the four panels might read.
-/// Pushed whole by the app; `None` means no quest window is open.
-/// The quest's reward spell — `rewSpell` on `SMSG_QUESTGIVER_QUEST_DETAILS` /
-/// `SMSG_QUESTGIVER_OFFER_REWARD` and on `SMSG_QUEST_QUERY_RESPONSE` — resolved by the app to
-/// the name and icon `GetRewardSpell` / `GetQuestLogRewardSpell` answer (stock
-/// `QuestFrameItems_Update` counts it as one more reward slot, `rewardType = "spell"`, and the
-/// slot's hover is `GameTooltip:SetQuestRewardSpell()`). `tradeskill` is the third return the
-/// reference derives from the spell itself (1944 — the derivation is wow-re's to pin).
+/// The reward spell, `rewSpell` on the giver packets and `SMSG_QUEST_QUERY_RESPONSE`, as
+/// `GetRewardSpell` and `GetQuestLogRewardSpell` answer it; stock counts it as one more reward slot
+/// (`QuestFrame.lua:332`). `tradeskill` is the third return, `isTradeskillSpell`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestRewardSpell {
     pub spell_id: u32,
@@ -83,6 +51,7 @@ pub struct QuestRewardSpell {
     pub tradeskill: bool,
 }
 
+/// One open questgiver panel, with every field the four panels read; pushed whole by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct QuestState {
     pub panel: QuestPanel,
@@ -90,31 +59,25 @@ pub struct QuestState {
     pub greeting: String,
     pub active_titles: Vec<String>,
     pub available_titles: Vec<String>,
-    // Detail / progress / reward.
-    /// The quest title (`GetTitleText`).
+    // Detail, progress and reward panels.
     pub title: String,
-    /// The panel body text: quest description (detail), request text (progress), or reward text
-    /// (reward). One field — only one of the three panels is live at a time.
+    /// The text of whichever panel is live: quest, progress or reward.
     pub body: String,
-    /// The quest objectives line (`GetObjectiveText`, detail panel only).
     pub objectives: String,
-    /// Choice rewards (the player picks one) — reward/detail panel.
+    /// Rewards the player picks one of.
     pub choices: Vec<QuestItemView>,
-    /// Fixed rewards (all granted) — reward/detail panel.
+    /// Rewards all granted.
     pub rewards: Vec<QuestItemView>,
-    /// Required items — progress panel.
+    /// Items the progress panel asks for.
     pub required: Vec<QuestItemView>,
-    /// Reward money in copper (`GetRewardMoney`, detail/reward panels).
+    /// In copper.
     pub reward_money: u32,
-    /// Required money in copper (`GetQuestMoneyToGet`, progress panel).
+    /// In copper.
     pub required_money: u32,
-    /// Whether the turn-in is completable (`IsQuestCompletable`, progress panel).
     pub completable: bool,
-    /// The reward spell, if the quest teaches one (`GetRewardSpell`; detail/reward panels).
     pub reward_spell: Option<QuestRewardSpell>,
-    /// The panel's background material (`GetQuestBackgroundMaterial` — nil is the reference's own
-    /// "Parchment" fallback in `QuestFrame_GetMaterial`). What fills it on the wire is 1944's
-    /// wow-re question; until the binary says, nothing does, and the verb answers nil honestly.
+    /// `GetQuestBackgroundMaterial`, which the app fills from an item or GameObject source, never
+    /// from the wire; nil reads as "Parchment" (`QuestFrame.lua:598-604`).
     pub background_material: Option<String>,
 }
 
@@ -140,38 +103,31 @@ impl Default for QuestState {
     }
 }
 
-/// A greeting-panel row click queued by `SelectActiveQuest`/`SelectAvailableQuest`: the 1-based row
-/// in its list. `active` picks between the active and available lists (the app maps the index to the
-/// quest id).
+/// A greeting row picked by `SelectActiveQuest` or `SelectAvailableQuest`, 1-based in its list.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct QuestSelect {
     pub active: bool,
     pub index: u32,
 }
 
-/// A questgiver button intent queued by the Lua panel verbs; the app maps each to `(npc, questId)`
-/// from its own live state and the matching `CMSG_QUESTGIVER_*`.
+/// A questgiver button intent; the app sends the matching message for its NPC and quest.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum QuestAction {
     /// Detail panel Accept → `CMSG_QUESTGIVER_ACCEPT_QUEST`.
     Accept,
-    /// Progress panel Continue → `CMSG_QUESTGIVER_REQUEST_REWARD` (advance to the reward panel).
+    /// Progress panel Continue → `CMSG_QUESTGIVER_REQUEST_REWARD`.
     Continue,
-    /// Reward panel Complete → `CMSG_QUESTGIVER_CHOOSE_REWARD` with the chosen choice index (0 when
-    /// the quest has no choice rewards).
+    /// Reward panel Complete → `CMSG_QUESTGIVER_CHOOSE_REWARD` with the 0-based choice.
     Reward(u32),
-    /// **The quest session's end**, however it was reached: `DeclineQuest()` (the detail panel's
-    /// Decline, the progress/reward panels' Cancel, the greeting's Goodbye) and `CloseQuest()`
-    /// (the window's own OnHide — ESC, a UIPanel eviction) alike.
-    ///
-    /// **One action, because the reference has one routine.** 1733 briefly split this into
-    /// `Decline` and `Close` on the assumption that only the first was an answer on the wire; the
-    /// §5 that landed after it found both Lua verbs calling `0x501130`, along with the walk-away
-    /// watchdog and the leave-world teardown, and that routine both answers a share
-    /// (`MSG_QUEST_PUSH_RESULT{DECLINE_QUEST}`) and re-opens an NPC's list
-    /// (`CMSG_QUESTGIVER_HELLO`/`CMSG_GOSSIP_HELLO`). Which of the two it does is decided by the
-    /// GIVER, never by the button — so the app owns that fork and the engine reports one intent
-    /// (decision 1738).
+    /// `DeclineQuest()`: the detail panel's Decline and the progress and reward panels' Cancel.
+    /// Its binding (`0x501d30`) re-opens the giver through `0x5013f0`: `CMSG_GOSSIP_HELLO` for a
+    /// gossip unit, `CMSG_QUESTGIVER_HELLO` for another unit, the teardown `0x501130(0,1)` for an
+    /// item or a player (or with `0xbe0824` set), a GameObject's interact call. The app owns this.
+    Decline,
+    /// `CloseQuest()`, from `QuestFrame_OnHide`: ESC, the close button, the greeting's Goodbye, a
+    /// panel eviction. Its binding (`0x501a10`) calls only the teardown `0x501130(0,1)`, whose one
+    /// send is `MSG_QUEST_PUSH_RESULT` DECLINE for a player source, so closing an NPC's window
+    /// sends nothing. It stays apart from `Decline`: the re-open is `DeclineQuest`'s alone.
     Close,
 }
 
@@ -192,9 +148,7 @@ impl super::UiScript {
     }
 }
 
-/// `GetQuestItemInfo(type, index)` reads from this vector by `type`; unknown types → `None`.
-/// The three returns of `GetRewardSpell` / `GetQuestLogRewardSpell`: `texture, name,
-/// isTradeskillSpell` — the third a 1/nil boolean in the reference's convention.
+/// `GetRewardSpell`'s three returns: `texture, name, isTradeskillSpell`, the third 1 or nil.
 pub(super) fn reward_spell_returns(
     lua: &Lua,
     spell: Option<QuestRewardSpell>,
@@ -222,6 +176,7 @@ pub(super) fn reward_spell_returns(
     Ok(MultiValue::from_vec(vec![texture, name, tradeskill]))
 }
 
+/// The list `GetQuestItemInfo(type, index)` reads for `type`.
 pub(super) fn item_vec<'a>(state: &'a QuestState, kind: &str) -> Option<&'a Vec<QuestItemView>> {
     match kind {
         "choice" => Some(&state.choices),
@@ -235,7 +190,7 @@ pub(super) fn item_vec<'a>(state: &'a QuestState, kind: &str) -> Option<&'a Vec<
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ── Text getters (one per panel field; nil/"" when no window is open) ─────────────────────────
+    // ── Text getters ──
     fn install_text(lua: &Lua, name: &str, pick: fn(&QuestState) -> String) -> mlua::Result<()> {
         lua.globals().set(
             name,
@@ -255,7 +210,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_text(lua, "GetRewardText", |q| q.body.clone())?;
     install_text(lua, "GetObjectiveText", |q| q.objectives.clone())?;
 
-    // ── Count + money getters ─────────────────────────────────────────────────────────────────────
+    // ── Count and money getters ──
     fn install_count(lua: &Lua, name: &str, pick: fn(&QuestState) -> i64) -> mlua::Result<()> {
         lua.globals().set(
             name,
@@ -275,7 +230,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_count(lua, "GetRewardMoney", |q| i64::from(q.reward_money))?;
     install_count(lua, "GetQuestMoneyToGet", |q| i64::from(q.required_money))?;
 
-    // IsQuestCompletable() → 1/nil (progress panel gate for the Continue button).
     g.set(
         "IsQuestCompletable",
         lua.create_function(|lua, ()| {
@@ -284,7 +238,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetActiveTitle(i) / GetAvailableTitle(i) — 1-based; "" when out of range.
     fn install_title(lua: &Lua, name: &str, active: bool) -> mlua::Result<()> {
         lua.globals().set(
             name,
@@ -307,8 +260,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_title(lua, "GetActiveTitle", true)?;
     install_title(lua, "GetAvailableTitle", false)?;
 
-    // GetQuestItemInfo(type, index) → name, texture, numItems, quality, isUsable (the Era tuple).
-    // `type` is "choice" / "reward" / "required"; `index` 1-based; out of range → nil.
+    // GetQuestItemInfo(type, index) → name, texture, numItems, quality, isUsable.
     g.set(
         "GetQuestItemInfo",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -337,18 +289,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::Integer(i64::from(it.count)),
                 Value::Integer(i64::from(it.quality)),
                 Value::Boolean(it.usable),
-                // Benilla extension (6th): the item id, the shared tooltip store's key.
+                // Not 1.12's: a sixth return, the item id, after its five; nothing reads it.
                 Value::Integer(i64::from(it.item_id)),
             ]))
         })?,
     )?;
 
-    // GetQuestItemLink(type, index) → the full escaped `|cff…|Hitem:…|h[Name]|h|r` | nil. The
-    // questgiver panels' ctrl/shift click arms read it — `DressUpItemLink(GetQuestItemLink(
-    // this.type, this:GetID()))` (ref QuestFrame.lua:118/130) and the shift-click
-    // `ChatFrameEditBox:Insert(...)` beside it (l.122/134). Same `type`/`index` addressing as
-    // `GetQuestItemInfo` above; nil for an out-of-range row, an unknown type, or a row whose
-    // template answer is still in flight (see [`QuestItemView::link`]). Decisions 1059/1060.
+    // GetQuestItemLink(type, index), for a row's ctrl and shift clicks (`QuestFrame.lua:118`).
     g.set(
         "GetQuestItemLink",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -367,10 +314,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetRewardSpell() → texture, name, isTradeskillSpell (three returns, 0x501df0; three nils on
-    // every empty path, the reference's own `(nil,nil,nil)` kind — 1842). Real since 1944: the
-    // app resolves `rewSpell` off the giver packets; stock's `if ( GetRewardSpell() ) then` counts
-    // the slot.
+    // GetRewardSpell() (`0x501df0`): three nils without a spell.
     g.set(
         "GetRewardSpell",
         lua.create_function(|lua, ()| {
@@ -382,8 +326,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── Intents ───────────────────────────────────────────────────────────────────────────────────
-    // SelectActiveQuest(i) / SelectAvailableQuest(i) — queue a greeting-row select (1-based).
+    // ── Intents ──
     fn install_select(lua: &Lua, name: &str, active: bool) -> mlua::Result<()> {
         lua.globals().set(
             name,
@@ -409,17 +352,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             })?,
         )
     }
-    // AcceptQuest → Accept; DeclineQuest / CloseQuest → Close (the ONE session-end routine, see
-    // `QuestAction::Close`); CompleteQuest (the progress panel's Continue) → Continue.
     install_action(lua, "AcceptQuest", super::QuestAction::Accept)?;
-    install_action(lua, "DeclineQuest", super::QuestAction::Close)?;
+    install_action(lua, "DeclineQuest", super::QuestAction::Decline)?;
     install_action(lua, "CloseQuest", super::QuestAction::Close)?;
     install_action(lua, "CompleteQuest", super::QuestAction::Continue)?;
 
-    // GetQuestBackgroundMaterial() → nil | string (0x502230; 0 args, 1 return). The reference's
-    // `QuestFrame_GetMaterial` (QuestFrame.lua:597-603) treats nil as "Parchment" and any string
-    // as the name of a material whose four `$parentMaterial*` quadrants and text colours
-    // (`GetMaterialTextColors`) the panel switches to. Answered from the pushed panel state.
+    // GetQuestBackgroundMaterial() → nil or a material name (`0x502230`).
     g.set(
         "GetQuestBackgroundMaterial",
         lua.create_function(|lua, ()| {
@@ -437,14 +375,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // QuestChooseRewardError() — 0x5021a0, 0 args, 0 returns: the Complete button pressed with
-    // choices on offer and none picked (stock `QuestRewardCompleteButton_OnClick`,
-    // QuestFrame.lua:96-100). Sixteen bytes — `push 0x98; call 0x496720` — the game-error row
-    // `ERR_QUEST_MUST_CHOOSE` (wow-re quest-material-reward-spell-bindings.md §2): the row's sound
-    // cue `igQuestFailed` plays first, then kind 2 routes the GlobalStrings text through
-    // `UI_ERROR_MESSAGE` — synchronously, as SignalEvent is — and UIErrorsFrame prints it. The
-    // text is read from the same global the FrameXML shows, so a localised chain shows its own
-    // string; the shipped English is the fallback when no GlobalStrings is loaded.
+    // QuestChooseRewardError() (`0x5021a0`), no returns: Complete pressed with choices and none
+    // picked (`QuestFrame.lua:98`). It shows game error `0x98` through `0x496720`: the sound
+    // `igQuestFailed`, then `ERR_QUEST_MUST_CHOOSE` through `UI_ERROR_MESSAGE`, synchronously.
     g.set(
         "QuestChooseRewardError",
         lua.create_function(|lua, ()| {
@@ -467,9 +400,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmAcceptQuest() — the escort confirm's Yes (ref StaticPopup.lua:731-733, raised by
-    // QUEST_ACCEPT_CONFIRM). No argument and no quest id: the client answers whichever confirm it
-    // is holding, so the engine counts the calls and the app supplies the id (decision 1733).
+    // ConfirmAcceptQuest(): the escort confirm's Yes (`StaticPopup.lua:731-733`). It takes no quest
+    // id, as the client answers the confirm it holds, so calls are counted and the app adds the id.
     g.set(
         "ConfirmAcceptQuest",
         lua.create_function(|lua, ()| {
@@ -479,12 +411,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestReward(choice) — the reward panel's Complete button. FrameXML passes the 1-based row
-    // (`QuestFrameRewardPanel.itemChoice = this:GetID()`, stock QuestFrame.lua:97-101) and the
-    // wire wants the 0-based choice (`CMSG_QUESTGIVER_CHOOSE_REWARD`'s reward index — vmangos
-    // indexes `RewChoiceItemId[reward]` with it), so the conversion is the binding's, as it is the
-    // client's; our own Lua used to do the -1 itself (1944). A quest with no choice rewards
-    // passes 0, which stays 0.
+    // GetQuestReward(choice): stock passes the 1-based row (`QuestFrame.lua:100`), and the wire
+    // takes it less one, floored at 0, as in the reference (`0x501d80`); vmangos indexes
+    // `RewChoiceItemId` with it.
     g.set(
         "GetQuestReward",
         lua.create_function(|lua, choice: Option<u32>| {
@@ -601,7 +530,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumQuestRewards()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return GetRewardMoney()").unwrap(), 1234);
 
-        // Row 1 (resolved): the Era tuple.
         let (name, texture, count, quality, usable) = s
             .eval::<(String, String, i64, i64, bool)>("return GetQuestItemInfo(\"reward\", 1)")
             .unwrap();
@@ -609,14 +537,14 @@ mod tests {
         assert_eq!(texture, "Interface\\Icons\\INV_Boots_01");
         assert_eq!((count, quality, usable), (1, 2, true));
 
-        // Choice row 2 (in flight): name + texture nil, the rest present.
+        // Choice row 2 is in flight: name and texture nil, the rest present.
         assert!(s
             .eval::<bool>(
                 "local n, t, c = GetQuestItemInfo(\"choice\", 2)\n\
                  return n == nil and t == nil and c == 1"
             )
             .unwrap());
-        // Out of range / unknown type → nil.
+        // Out of range, and an unknown type: nil.
         assert!(s
             .eval::<bool>("return GetQuestItemInfo(\"reward\", 9) == nil")
             .unwrap());
@@ -624,9 +552,7 @@ mod tests {
             .eval::<bool>("return GetQuestItemInfo(\"bogus\", 1) == nil")
             .unwrap());
 
-        // GetQuestItemLink: the resolved row's full escaped link; nil for a row still waiting on
-        // its template (choice 2 has no name yet, so no link either), and nil out of range /
-        // unknown type — the three nils the ref's ctrl/shift arms hand to DressUpItemLink.
+        // The link is nil for the in-flight row, out of range, and for an unknown type.
         assert_eq!(
             s.eval::<String>("return GetQuestItemLink(\"reward\", 1)")
                 .unwrap(),
@@ -731,7 +657,7 @@ mod tests {
                 QuestAction::Continue,
                 QuestAction::Reward(1),
                 QuestAction::Reward(0),
-                QuestAction::Close,
+                QuestAction::Decline,
             ]
         );
         assert!(s.take_quest_actions().is_empty(), "drained");
@@ -747,24 +673,18 @@ mod tests {
         assert!(s.eval::<bool>("return GetRewardSpell() == nil").unwrap());
     }
 
-    /// `DeclineQuest` and `CloseQuest` are the SAME intent — one reference routine, `0x501130`
-    /// (decision 1738, correcting 1733's split). What differs between a decline and a close is
-    /// nothing; what differs between an NPC's quest and a shared one is everything, and that fork
-    /// belongs to the app, which knows the giver.
     #[test]
-    fn decline_and_close_are_one_intent() {
+    fn decline_and_close_are_two_intents() {
         let mut s = UiScript::new().unwrap();
         s.set_quest(Some(detail()));
         s.run("DeclineQuest()").unwrap();
         s.run("CloseQuest()").unwrap();
         assert_eq!(
             s.take_quest_actions(),
-            vec![QuestAction::Close, QuestAction::Close]
+            vec![QuestAction::Decline, QuestAction::Close]
         );
     }
 
-    /// `ConfirmAcceptQuest` counts rather than carrying a quest id — the reference's verb takes no
-    /// argument and answers whichever confirm the client holds (decision 1733).
     #[test]
     fn confirm_accept_quest_counts_and_drains() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/quest_log.rs b/crates/benilla-ui/src/script/quest_log.rs
index 11121f36..e0e91efa 100644
--- a/crates/benilla-ui/src/script/quest_log.rs
+++ b/crates/benilla-ui/src/script/quest_log.rs
@@ -1,45 +1,13 @@
-//! The quest-**log** bindings (the 0088 arc's second slice) — the Era-shaped `GetQuestLog*` surface
-//! the reference `QuestLogFrame.lua` reads, over the same two-way seam as the questgiver panels
-//! ([`super::quest`]): the app pushes a whole [`QuestLogState`] snapshot (entries from the
-//! `PLAYER_QUEST_LOG` descriptor slots, the selected quest's detail resolved from the
-//! `SMSG_QUEST_QUERY_RESPONSE` template cache), and the Lua drains back the **abandon** intent.
+//! The quest-log verbs the stock `QuestLogFrame.lua` calls, over a [`QuestLogState`] the app
+//! pushes (rows from the `PLAYER_QUEST_LOG` descriptor slots, text from the quest template cache),
+//! with the abandon, share and fold intents drained back. The selection lives in the engine, as
+//! `QuestLog_SetSelection` sets and re-reads it in one call (`QuestLogFrame.lua:318`, `:342`). The
+//! abandon mark and the share hold the quest id selected at the click, as the reference's mark
+//! does (`0x4dfb50` copies the selection `0xbb7480`, a quest id, to `0xbb7484`), so a re-index
+//! before the popup's Yes cannot retarget them.
 //!
-//! Two engine-owned bits deliberately live *in the model*, not the pushed state:
-//!
-//! - **The selection** (`SelectQuestLogEntry`/`GetQuestLogSelection`). In the reference client the
-//!   selection is native and *synchronous* — `QuestLogTitleButton_OnClick` calls
-//!   `SelectQuestLogEntry(i)` then immediately re-reads `GetQuestLogSelection()` in the same click
-//!   (ref `QuestLogFrame.lua:318,308-346`); a drain-next-frame intent would read stale. The app
-//!   reads it back each frame ([`super::UiScript::quest_log_selection`]) only to RE-POINT it across
-//!   a rebuild. The **detail that selection names is resolved at call time**, off the row's own
-//!   [`QuestLogEntryView::detail`] — never from a selection baked into the push (decision 2247).
-//!   The reference's detail bindings peek its quest cache inside the same call, so
-//!   `SelectQuestLogEntry(i)` immediately changes what `GetQuestLogQuestText()` answers; resolving
-//!   one detail per push instead made a whole log walk answer with a single row's text.
-//! - **The abandon mark** (`SetAbandonQuest`/`GetAbandonQuestName`/`AbandonQuest`) — the ref's
-//!   two-step confirm (mark on button click, act on the popup's Yes — ref `QuestLogFrame.xml:463-472`,
-//!   `StaticPopup.lua:749-761`). The mark pins the *entry index at click time* so a log shuffle
-//!   between click and confirm can't retarget the abandon.
-//!
-//! A third engine-owned bit joined later: the **watch set** (`IsQuestWatched`/`AddQuestWatch`/
-//! `RemoveQuestWatch`/`GetNumQuestWatches`/`GetQuestIndexForWatch`) — keyed by the entries' stable
-//! [`QuestLogEntryView::quest_id`] under the index-based Era API, pruned on push, cap 5.
-//!
-//! A fourth engine-owned bit is the **countdown** (`GetQuestTimers`/`GetQuestIndexForTimer`/
-//! `GetQuestLogTimeLeft`, decision 1150): the snapshot carries each row's absolute deadline and the
-//! bindings subtract the live server clock per call, so the reference's `QuestTimerFrame` can tick
-//! from its OnUpdate without the log snapshot changing under it. [`seconds_left`] carries the
-//! reference's byte-verified formula and the ways a row has no timer to show (decision 1154).
-//!
-//! A fifth is the **share** (`GetQuestLogPushable`/`QuestLogPushQuest`, decision 1733): the
-//! pushable bit rides each entry (from the app's template cache) and the click resolves the
-//! selection to a quest id before it queues, so a log shuffle cannot retarget it.
-//!
-//! v1 scope (the deliberate `nil`/false stubs, each a later slice): the party quest-log tooltip
-//! (`IsUnitOnQuest` — it needs the party members' own logs, which is a different wire),
-//! reward spells (`GetQuestLogRewardSpell`), and zone
-//! **headers** ([`QuestLogEntryView::is_header`] is plumbed but the app pushes a flat list —
-//! headers need the QuestSort/AreaTable DBC join).
+//! Not built: `IsUnitOnQuest` and `GetAbandonQuestItems` answer nil; the first needs the party
+//! members' quest logs.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -47,236 +15,168 @@ use super::binding_abi::{flag, number_arg};
 use super::quest::QuestItemView;
 use super::Model;
 
-/// One quest-log list row — the `GetQuestLogTitle` tuple's data half. Plain data; its 1-based
-/// position in [`QuestLogState::entries`] is the quest-log index the whole API keys on.
+/// One quest-log row; its 1-based position in [`QuestLogState::entries`] is the index every verb
+/// takes.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestLogEntryView {
-    /// The quest id occupying the row's descriptor slot. Never surfaced to Lua (no Era API returns
-    /// it) — it is the engine's *stable identity* for the watch set ([`install`]'s
-    /// `AddQuestWatch`/…): watching by id survives the log shuffling under the index-based API
-    /// (an abandon compacts the rows; a watched *index* would silently retarget).
+    /// The slot's quest id, never returned to Lua; watches, marks and shares key on it, as
+    /// indexes shift.
     pub quest_id: u32,
-    /// The quest title (row label).
     pub title: String,
-    /// The quest's display level (`GetQuestLogTitle` return 2; the ref colors the row by it).
+    /// `GetQuestLogTitle`'s return 2, which colors the stock row.
     pub level: u32,
-    /// The quest tag suffix — the bare word, no parentheses: `Elite`, `Dungeon`, `Raid`, `PvP`,
-    /// `Life`, `World Event`, `Legendary`. `None` for a plain quest, which is most of them, and
-    /// always `None` on a header row. The app resolves it from the cached
-    /// `SMSG_QUEST_QUERY_RESPONSE` template's `Type` through `QuestInfo.dbc`
-    /// ([`benilla_formats::QuestTagNames`]); `Type` 0 names no row and takes no tag.
-    ///
-    /// `None`, never `Some("")` — the reference's row Lua branches on the tag's PRESENCE
-    /// (`if ( questTag )`, ref `QuestLogFrame.lua:194`) to decide whether to shrink the title and
-    /// reseat the watch check, so an empty string would take the wrong branch.
+    /// The bare tag word (`Elite`, `Dungeon`, `Raid`, …) from the template's `Type` through
+    /// `QuestInfo.dbc`; the stock row adds the parentheses (`QuestLogFrame.lua:195`). `None`,
+    /// never `Some("")`, for no tag: the row branches on its presence (`QuestLogFrame.lua:194`).
     pub tag: Option<String>,
-    /// A zone header row (the app synthesizes these from each quest's ZoneOrSort).
+    /// A zone header row, which the app builds from each quest's `ZoneOrSort`.
     pub is_header: bool,
-    /// Whether this quest may be SHARED with the party — `GetQuestLogPushable`'s answer for the
-    /// row (decision 1733). Computed app-side from the cached `SMSG_QUEST_QUERY_RESPONSE`
-    /// template's `QUEST_FLAGS_SHARABLE` (`0x8`), so a row whose template has not answered yet is
-    /// `false` and turns true when it lands — the reference's own shape, since it reads the same
-    /// cache. Never surfaced as a per-index Lua getter: the Era API asks only about the current
-    /// selection.
+    /// `GetQuestLogPushable`: the template's `QUEST_FLAGS_SHARABLE` (`0x8`), false until the
+    /// template arrives, as the reference reads the same cache.
     pub pushable: bool,
-    /// A COLLAPSED header (`GetQuestLogTitle`'s isCollapsed; meaningless on quest rows). The app
-    /// owns the collapse set and omits a collapsed header's quests from `entries` — the engine
-    /// only reports the flag and drains the toggle intents ([`super::UiScript::take_quest_log_collapses`]).
+    /// A collapsed header (`isCollapsed`), whose quests the app leaves out of `entries`.
     pub collapsed: bool,
-    /// Whole-quest state from the descriptor slot's state byte: `1` complete, `-1` failed, `0`
-    /// in progress (`GetQuestLogTitle`'s `isComplete` is `1`/`-1`/`nil` off this).
+    /// The slot state: `1` complete, `-1` failed, `0` in progress (`isComplete` 1, -1 or nil).
     pub complete: i32,
-    /// A timed quest's **deadline**, as the descriptor slot carries it: absolute unix-epoch
-    /// seconds (`time(nullptr) + limitTime`, vmangos `Player::AddQuest`), `0` when the quest is
-    /// untimed. Deliberately the raw stamp and not a remaining-seconds count: a remaining count
-    /// would change every second, and this snapshot is diffed by the app to decide whether to fire
-    /// `QUEST_LOG_UPDATE` — a live number in here would rebuild the whole quest log every frame.
-    /// The countdown is subtracted per call instead, against [`super::Model::server_unix_time`]
-    /// (decision 1150).
+    /// The slot's deadline in unix seconds (`time(nullptr) + limitTime`, vmangos
+    /// `Player::AddQuest`), 0 when untimed. A stamp, not a countdown: the app diffs this snapshot
+    /// to fire `QUEST_LOG_UPDATE`, so a live number here would rebuild the log every frame.
     pub timer: u32,
-    /// The formatted objective lines for THIS entry (`GetNumQuestLeaderBoards(i)` /
-    /// `GetQuestLogLeaderBoard(j, i)` serve any index off these — the watch tracker HUD reads
-    /// non-selected quests' lines). The selection's no-arg reads come from here too; the
-    /// [`QuestLogDetail`] carries only what exists for the selection alone
-    /// (description/rewards/money).
+    /// This row's objective lines; the leaderboard verbs serve any row, selected or not.
     pub objectives: Vec<QuestLogObjectiveView>,
-    /// This row's detail pane — description, money, rewards, reward spell. **Per row, not per
-    /// selection** (decision 2247): the reference's detail bindings read `ds:0xbb7480` (what
-    /// `SelectQuestLogEntry 0x4dfae0` wrote, synchronously) and then PEEK the quest cache in the
-    /// same call (`0x4e1130` -> `0xc0e1b0`/`0x562a40`, wow-re `ui/ledger.tsv`), so a
-    /// select-then-read pair inside ONE frame answers about the row just selected. Carrying one
-    /// detail for "the selection" instead made `SelectQuestLogEntry` inert until the next push:
-    /// every entry of an addon's log walk answered with whichever row the snapshot happened to be
-    /// built against. `None` on a header row.
+    /// This row's detail pane, `None` on a header. Per row, not per selection: the reference's
+    /// detail verbs read the selection `0xbb7480` that `SelectQuestLogEntry` (`0x4dfae0`) wrote and
+    /// look the quest up in the same call (`0x4e1130` to `0xc0e1b0`, `0x562a40`), so a
+    /// select-then-read answers about the row just selected.
     pub detail: Option<QuestLogDetail>,
 }
 
-/// One objective ("leaderboard") line of the selected quest — the `GetQuestLogLeaderBoard` tuple.
-/// The app pre-formats `text` ("Kobold Vermin slain: 3/10") from the template + slot counters.
+/// One objective line (`GetQuestLogLeaderBoard`), `text` formatted by the app, as
+/// "Kobold Vermin slain: 3/10".
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestLogObjectiveView {
-    /// The display line, fully formatted.
     pub text: String,
-    /// The objective kind (`"monster"` / `"item"` / `"object"` — the Era type string).
+    /// The type string: `"monster"`, `"item"` or `"object"`.
     pub kind: String,
-    /// Whether this objective is done (darkens the line + `(Complete)` suffix in the ref).
+    /// Done: the stock log greys the line and appends `(Complete)` (`QuestLogFrame.lua:389`).
     pub finished: bool,
-    /// The progress numbers `text` was formatted from — the `%d/%d` of the line (`cur` already
-    /// clamped to `req`). Not exposed to Lua (`GetQuestLogLeaderBoard` returns text/type/finished
-    /// only); they exist so the app's progress announce can ask *"did this ADVANCE?"* instead of
-    /// *"did the rendered line change?"*. A text-only diff cannot tell progress from a regression,
-    /// and a quest turn-in produces exactly that regression — the required items are destroyed a
-    /// frame or two before the log slot clears, so the line dips to `0/req` while the quest is
-    /// still in the log (decision 1152 / B237).
+    /// The line's `%d/%d`, `cur` clamped to `req`, not returned to Lua. The app's progress
+    /// announce compares these, as a turn-in destroys the items a frame or two before the slot
+    /// clears and the line dips to `0/req`, which text alone cannot tell from progress.
     pub cur: u32,
     /// See [`Self::cur`].
     pub req: u32,
 }
 
-/// The selected quest's detail pane — resolved by the app from the `QUEST_QUERY_RESPONSE` template
-/// cache (+ item/creature name caches). `None` while the template is still in flight.
+/// A quest's detail pane, from the app's template and name caches.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestLogDetail {
-    /// The long description (`GetQuestLogQuestText` return 1).
+    /// `GetQuestLogQuestText`'s return 1.
     pub description: String,
-    /// The objectives flavor paragraph (`GetQuestLogQuestText` return 2) — *not* the leaderboard
-    /// lines (those live on every [`QuestLogEntryView::objectives`], selection or not).
+    /// `GetQuestLogQuestText`'s return 2, the objectives paragraph, not the leaderboard lines.
     pub objectives_text: String,
-    /// Money the turn-in demands (`GetQuestLogRequiredMoney`), copper.
+    /// `GetQuestLogRequiredMoney`, in copper.
     pub required_money: u32,
-    /// Reward money (`GetQuestLogRewardMoney`), copper.
+    /// `GetQuestLogRewardMoney`, in copper.
     pub reward_money: u32,
-    /// Choice rewards (`GetNumQuestLogChoices`/`GetQuestLogChoiceInfo`).
+    /// `GetNumQuestLogChoices`/`GetQuestLogChoiceInfo`.
     pub choices: Vec<QuestItemView>,
-    /// Fixed rewards (`GetNumQuestLogRewards`/`GetQuestLogRewardInfo`).
+    /// `GetNumQuestLogRewards`/`GetQuestLogRewardInfo`.
     pub rewards: Vec<QuestLogQuestItem>,
-    /// The selected quest's reward spell (`rewSpell` on `SMSG_QUEST_QUERY_RESPONSE`), as
-    /// `GetQuestLogRewardSpell` answers it.
+    /// The template's `rewSpell`, as `GetQuestLogRewardSpell` answers it.
     pub reward_spell: Option<super::quest::QuestRewardSpell>,
 }
 
 /// A quest-log reward row is the same shape as a questgiver panel row.
 pub type QuestLogQuestItem = QuestItemView;
 
-/// The whole quest-log snapshot the app pushes each time it changes. Unlike the questgiver panels
-/// this is durable state, not a window session — an empty log is `entries: []`, never `None`.
+/// The quest-log snapshot the app pushes on each change; an empty log is empty `entries`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct QuestLogState {
-    /// The list rows, in quest-log (descriptor slot) order. 1-based indexing on the Lua side.
-    /// A collapsed header's quests are OMITTED here (the app filters) — indexes are visible rows.
+    /// The visible rows, in log order; a collapsed header's quests are left out.
     pub entries: Vec<QuestLogEntryView>,
-    /// The total quest count INCLUDING quests hidden under collapsed headers — the "Quests: N/20"
-    /// pill must not shrink when a header collapses (`GetNumQuestLogEntries` return 2).
+    /// `GetNumQuestLogEntries`'s return 2: every quest, folded ones included, for the
+    /// "Quests: N/20" count (`QuestLogFrame.lua:290`).
     pub num_quests: u32,
+    /// Quests folded under a collapsed header: in the log, not in `entries`. Their watches and
+    /// abandon marks hold, as the reference's watch prune (`0x4de7a7` to `0x4de80f`) and abandon
+    /// search (`0xbb71c0`) cover every row, folded ones included.
+    pub hidden_quest_ids: Vec<u32>,
 }
 
 impl super::UiScript {
-    /// Push the quest-log snapshot (the app calls this whenever slots/templates/selection change).
-    /// Also prunes the watch set: a watched quest that left the log (abandon/turn-in) drops its
-    /// watch, exactly as the real client's RemoveQuestWatch-on-removal does.
+    /// Push the quest-log snapshot, dropping the watch of a quest that left the log: the
+    /// reference's prune (`0x4de7a7` to `0x4de80f`) keeps a watch while any quest row, visible or
+    /// folded, carries its id, and a collapse (`0x4ded30`) never prunes.
     pub fn set_quest_log(&mut self, state: QuestLogState) {
         let mut model = self.model_mut();
-        model
-            .quest_log_watched
-            .retain(|id| state.entries.iter().any(|e| e.quest_id == *id));
+        model.quest_log_watched.retain(|id| {
+            state
+                .entries
+                .iter()
+                .any(|e| !e.is_header && e.quest_id == *id)
+                || state.hidden_quest_ids.contains(id)
+        });
         model.quest_log = state;
     }
 
-    /// The watched quest ids, in watch order — the app fires `QUEST_WATCH_UPDATE` when a watched
-    /// quest's objectives change, and this is how it knows which those are.
+    /// The watched quest ids, in watch order.
     pub fn quest_log_watched(&self) -> Vec<u32> {
         self.model_ref().quest_log_watched.clone()
     }
 
-    /// The engine-owned 1-based selection (`SelectQuestLogEntry`'s last value; `0` = none) — the
-    /// app reads it each frame to know which quest's detail to resolve and push.
+    /// The 1-based selection, 0 for none; the app reads it to re-point it across a rebuild.
     pub fn quest_log_selection(&self) -> u32 {
         self.model_ref().quest_log_selection
     }
 
-    /// Drain the abandon intents: the 1-based entry index pinned by `SetAbandonQuest` at
-    /// click time, confirmed by the popup's `AbandonQuest()`. The app maps index → descriptor
-    /// slot → `CMSG_QUESTLOG_REMOVE_QUEST`.
+    /// Drain the abandons, quest ids marked by `SetAbandonQuest` and confirmed by
+    /// `AbandonQuest()`; the app sends each slot's `CMSG_QUESTLOG_REMOVE_QUEST`.
     pub fn take_quest_log_abandons(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().quest_log_abandons)
     }
 
-    /// Drain the share intents: the quest ids `QuestLogPushQuest()` queued, already resolved from
-    /// the selection at click time. The app sends one `CMSG_PUSHQUESTTOPARTY` per id.
+    /// Drain the shares `QuestLogPushQuest()` queued, as quest ids; the app sends one
+    /// `CMSG_PUSHQUESTTOPARTY` each.
     pub fn take_quest_log_pushes(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().quest_log_pushes)
     }
 
-    /// Drain the escort-confirm answers: how many times `ConfirmAcceptQuest()` was called. A
-    /// count, because the verb carries no quest id (decision 1733) — the app answers the confirm
-    /// it is holding.
+    /// Drain the `ConfirmAcceptQuest()` calls as a count: the verb carries no quest id, so the app
+    /// answers the confirm it holds.
     pub fn take_quest_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().quest_confirms)
     }
 
-    /// Drain the header collapse/expand intents: `(1-based entry index, collapse)` from
-    /// `CollapseQuestHeader`/`ExpandQuestHeader` — index `0` = ALL headers (the ref's
-    /// collapse-all button passes 0, QuestLogFrame.lua:557/:561). The app owns the collapse
-    /// set and re-feeds the filtered list (same intent pattern as the abandons above).
+    /// Drain `CollapseQuestHeader`/`ExpandQuestHeader` as `(1-based index, collapse)`; index 0
+    /// is every header, as the collapse-all button passes (`QuestLogFrame.lua:557`, `:561`).
     pub fn take_quest_log_collapses(&mut self) -> Vec<(u32, bool)> {
         std::mem::take(&mut self.model_mut().quest_log_collapses)
     }
 
-    /// Set the engine-owned 1-based selection from the app side — the collapse/expand rebuild
-    /// shifts entry indexes, and the app re-points the selection at the SAME quest's new index
-    /// (selection is an index to the Era API, but an identity to the player).
+    /// Set the selection, re-pointed by the app at the same quest when a rebuild shifts the rows.
     pub fn set_quest_log_selection(&mut self, i: u32) {
         self.model_mut().quest_log_selection = i;
     }
 
-    /// Push the server's wall clock (unix-epoch seconds) — the app's `SMSG_QUERY_TIME_RESPONSE`
-    /// sample, advanced monotonically. Every countdown the engine answers is subtracted against
-    /// this, so it is pushed each frame rather than on change (decision 1150).
-    ///
-    /// This is the reference's `G` in a different frame of reference, and it is worth naming the
-    /// equivalence because the two look nothing alike. The client stores only an **offset**
-    /// `G = local_epoch@sync − server_epoch@sync` and computes `deadline + G − localNow()`; we
-    /// store the server stamp and advance it monotonically, i.e. `deadline − serverNow()`.
-    /// Expand either and both reduce to `remaining_at_sync − elapsed`. The one behavioural
-    /// difference is deliberate and in our favour: a local wall-clock step mid-session (an NTP
-    /// correction, a manual change) jumps the reference's countdown and cannot move ours
-    /// (decision 1154).
+    /// Push the server clock in unix seconds each frame: the app's `SMSG_QUERY_TIME_RESPONSE`
+    /// sample, advanced monotonically. The reference keeps an offset `G = local - server` from the
+    /// sync and computes `deadline + G - localNow()`, the same value. Deviation: a local clock
+    /// step mid-session (an NTP correction) jumps the reference's countdown but not ours, because
+    /// the step changes no time the quest has left.
     pub fn set_server_unix_time(&mut self, unix_secs: f64) {
         self.model_mut().server_unix_time = Some(unix_secs);
     }
 }
 
-/// The signed seconds remaining on a quest-log row's timer, or `None` when the row has no timer at
-/// all. **This is the reference's own formula**, byte-verified (wow-re
-/// `system/ui/scratch/quest-timer-law.md`, the 2026-08-09 §5 trio; decision 1154):
-///
-/// ```text
-/// value = slot.timer + G − now − 1
-/// ```
-///
-/// — computed identically by all four of its consumers (`0x4e0905`, `0x4e14b9`, `0x4e16c9`,
-/// `0x4de6b6`). Our `now` already carries `G` folded in (see [`super::UiScript::set_server_unix_time`]),
-/// so what is left here is the deadline, the clock, and **the `−1`**.
-///
-/// That `−1` is not a rounding artefact to tidy away: a quest expiring exactly `N` seconds after
-/// the sampled clock reads `N − 1`, and its last second reads `0`. The bias is downward by
-/// construction — the reference never overstates the time a player has left, and neither do we.
-///
-/// Three ways there is nothing to show, each a deliberate answer rather than a fallthrough:
-///
-/// - `timer == 0` — the quest is untimed. The overwhelming majority of rows, and header rows too
-///   (the app pushes them with no timer, matching the reference's own header skip at `0x4e1460`).
-/// - The row is **failed** (`complete < 0`). vmangos writes the slot timer to the literal `1` and
-///   sets the state's FAIL bit when a timed quest runs out (`Player::FailQuest`,
-///   `Player.cpp:13430`), and the row *stays in the log* until the player abandons it. The
-///   reference tests the same bit **before** the arithmetic (`test byte [slot+0x7],0x2` at each of
-///   the four sites), so that `1` never reaches a subtraction there either.
-/// - No server clock yet — the deadline is an absolute stamp in the server's epoch and there is
-///   nothing honest to subtract from it. The reference agrees exactly: its `G == 0` is the
-///   never-synced sentinel and `GetQuestLogTimeLeft` answers nil on it.
-///
-/// A **negative** result is returned as such: the two list bindings drop the row (the reference's
-/// `js` at `0x4e14c5`), while `GetQuestLogTimeLeft` clamps it at 0. Same split, same reason.
+/// Signed seconds left on a row's timer, by the reference's formula at all four of its sites
+/// (`0x4e0905`, `0x4e14b9`, `0x4e16c9`, `0x4de6b6`): `slot.timer + G - now - 1`, `G` folded into
+/// `now`, so a quest's last second reads 0. A negative value drops the row from the lists (`js` at
+/// `0x4e14c5`) and clamps to 0 in `GetQuestLogTimeLeft`. `None` when there is nothing to show:
+/// - an untimed row, or a header (skipped at `0x4e1460`);
+/// - a failed row: vmangos sets its timer to 1 (`Player.cpp:13430`), and the reference tests the
+///   fail bit `[slot+0x7] & 0x2` first;
+/// - no server clock yet, the reference's never-synced `G == 0`.
 fn seconds_left(entry: &QuestLogEntryView, now: Option<f64>) -> Option<i64> {
     if entry.timer == 0 || entry.complete < 0 {
         return None;
@@ -285,8 +185,7 @@ fn seconds_left(entry: &QuestLogEntryView, now: Option<f64>) -> Option<i64> {
     Some((f64::from(entry.timer) - now - 1.0).floor() as i64)
 }
 
-/// The list bindings' view: seconds remaining, and only for a row that still has some. Drops the
-/// expired rows the reference's `js` drops.
+/// [`seconds_left`] for the list verbs, which drop an expired row as the reference's `js` does.
 fn live_seconds_left(entry: &QuestLogEntryView, now: Option<f64>) -> Option<i64> {
     seconds_left(entry, now).filter(|&s| s >= 0)
 }
@@ -295,8 +194,7 @@ fn live_seconds_left(entry: &QuestLogEntryView, now: Option<f64>) -> Option<i64>
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumQuestLogEntries() → numEntries, numQuests (headers count toward the first only —
-    // ref QuestLogFrame.lua:108; flat v1 pushes no headers so the two are equal).
+    // `numEntries` counts header rows, `numQuests` only quests (`QuestLogFrame.lua:108`).
     g.set(
         "GetNumQuestLogEntries",
         lua.create_function(|lua, ()| {
@@ -306,20 +204,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogTitle(i) → title, level, tag, isHeader, isCollapsed, isComplete
-    // (the load-bearing 6-tuple — ref QuestLogFrame.lua:144/:272/:321/:571).
-    // `tag` is the bare word (`Elite`, `Raid`, …) or nil — the ref's Lua wraps it in the
-    // parentheses itself (`"("..questTag..")"`, ref l.195). isComplete is 1 / -1 / nil.
-    //
-    // **The arity is always SIX, and the two failure shapes are different** (wow-re
-    // `ui/scratch/questlog-title-tag.md`, §5-verified at `0x4df930`): a MISSING or non-number
-    // argument raises `Usage:` (shape A — [`number_arg`], truncating toward zero like the
-    // reference's `_ftol`), while an out-of-range NUMBER is not an error at all — it returns
-    // `nil, 0, nil, nil, nil, nil` off `mov eax,6` at all three exits. Return 2 is the NUMBER
-    // `0` there, never nil, and it is `0` for a header row too. We used to answer a single
-    // `Nil` for both, which reads the same through the reference's own
-    // `local t, l, … = GetQuestLogTitle(i)` (Lua pads with nil) but hands an addon doing
-    // arithmetic on the level a nil where the client gives it a zero.
+    // `title, level, tag, isHeader, isCollapsed, isComplete`, always six (`0x4df930`). The index
+    // truncates as `_ftol` does, and a missing or non-number one raises `Usage:`; out of range it
+    // answers `nil, 0, nil, nil, nil, nil`, and a header's level is 0 too.
     g.set(
         "GetQuestLogTitle",
         lua.create_function(|lua, i: Value| {
@@ -350,13 +237,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 0 => Value::Nil,
                 c => Value::Integer(i64::from(c.signum())),
             };
-            // **Returns 4 and 5 are `1`/`nil`, NOT booleans** (wow-re
-            // `ui/scratch/questlog-title-tag.md` §7's table): `isHeader` is `1` on a header row
-            // and `nil` on a quest; `isCollapsed` is `1` only for a header whose bit in
-            // `[0xbb748c]` is clear — a quest row and an EXPANDED header both answer `nil`. We
-            // pushed `true`/`false`, which every `if ( isHeader )` in FrameXML reads the same and
-            // which `isHeader == false` or a `type()` test does not. The two are one expression
-            // here because `collapsed` is meaningless off a header (the field's own doc).
+            // Returns 4 and 5 are 1 or nil, never booleans; `isCollapsed` is 1 only on a header
+            // whose bit in `[0xbb748c]` is clear.
             let flag = |b: bool| if b { Value::Integer(1) } else { Value::Nil };
             Ok(MultiValue::from_vec(vec![
                 Value::String(lua.create_string(&e.title)?),
@@ -369,7 +251,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SelectQuestLogEntry(i) — the synchronous, engine-owned selection (see module doc).
     g.set(
         "SelectQuestLogEntry",
         lua.create_function(|lua, i: u32| {
@@ -379,7 +260,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogSelection() → the 1-based selection, 0 = none.
+    // The 1-based selection, 0 for none.
     g.set(
         "GetQuestLogSelection",
         lua.create_function(|lua, ()| {
@@ -388,8 +269,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogQuestText() → description, objectivesText (for the selection — the app already
-    // resolved `detail` against it).
     g.set(
         "GetQuestLogQuestText",
         lua.create_function(|lua, ()| {
@@ -407,9 +286,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumQuestLeaderBoards([questIndex]) — objective-line count for the given entry (1-based),
-    // defaulting to the selection. Any index answers (the watch tracker HUD reads non-selected
-    // quests' lines — ref QuestLogFrame.lua:613-663).
+    // Any row's line count, the selection's by default: the watch tracker reads unselected quests
+    // (`QuestLogFrame.lua:616`).
     g.set(
         "GetNumQuestLeaderBoards",
         lua.create_function(|lua, i: Option<u32>| {
@@ -423,7 +301,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogLeaderBoard(i[, questIndex]) → text, type, finished — same any-index rule.
+    // `text, type, finished` of line `i`, for any row as above (`QuestLogFrame.lua:635`).
     g.set(
         "GetQuestLogLeaderBoard",
         lua.create_function(|lua, (i, quest): (usize, Option<u32>)| {
@@ -447,7 +325,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── Detail counts + money ─────────────────────────────────────────────────────────────────────
+    // ── Detail counts + money ────────────────────────────────────────────────────────────────────
     fn install_detail_count(
         lua: &Lua,
         name: &str,
@@ -468,9 +346,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         i64::from(d.required_money)
     })?;
 
-    // GetQuestLogChoiceInfo(i) / GetQuestLogRewardInfo(i) → name, texture, numItems, quality,
-    // isUsable — the same 5-tuple as the giver panels' GetQuestItemInfo (they share one layout
-    // routine in the ref — QuestFrame.lua:311-522).
+    // `name, texture, numItems, quality, isUsable`, the giver panels' shape, as one stock routine
+    // lays out both (`QuestFrameItems_Update`, `QuestFrame.lua:311`).
     fn install_detail_item(
         lua: &Lua,
         name: &str,
@@ -502,7 +379,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     Value::Integer(i64::from(it.count)),
                     Value::Integer(i64::from(it.quality)),
                     Value::Boolean(it.usable),
-                    // Benilla extension (6th): the item id, the shared tooltip store's key.
+                    // The item id, `BenillaGetItemStats`'s key, a sixth return that is not 1.12's.
                     Value::Integer(i64::from(it.item_id)),
                 ]))
             })?,
@@ -511,14 +388,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_detail_item(lua, "GetQuestLogChoiceInfo", |d| &d.choices)?;
     install_detail_item(lua, "GetQuestLogRewardInfo", |d| &d.rewards)?;
 
-    // GetQuestLogItemLink(type, index) → the full escaped `|cff…|Hitem:…|h[Name]|h|r` | nil — the
-    // quest log's twin of `GetQuestItemLink` ([`super::quest`]), read by the reward rows' ctrl/shift
-    // click arms: `DressUpItemLink(GetQuestLogItemLink(this.type, this:GetID()))` (ref
-    // QuestLogFrame.lua:545) and the `ChatFrameEditBox:Insert(...)` beside it (l.549). Unlike the
-    // *Info* pair above this one is kind-DISPATCHED, because that is the shape the reference's own
-    // handler calls it with (`this.type` is "choice"/"reward", set by the shared
-    // `QuestFrameItems_Update`); an unknown type, an out-of-range index, or a row whose template
-    // answer is still in flight all read nil. Decisions 1059/1060.
+    // The item's escaped link, for the reward rows' ctrl and shift clicks (`QuestLogFrame.lua:545`,
+    // `:549`), keyed by `this.type`, "choice" or "reward" (set by `QuestFrameItems_Update`). An
+    // unknown type, an index out of range or a template not yet arrived answers nil.
     g.set(
         "GetQuestLogItemLink",
         lua.create_function(|lua, (kind, index): (String, usize)| {
@@ -543,8 +415,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsCurrentQuestFailed() → 1/nil: the selection's slot state is FAIL (ref appends
-    // " - (Failed)").
+    // 1 or nil, whether the selected slot has failed; the stock title then appends " - (Failed)"
+    // (`QuestLogFrame.lua:354`).
     g.set(
         "IsCurrentQuestFailed",
         lua.create_function(|lua, ()| {
@@ -558,10 +430,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The abandon two-step (mark → confirm) ─────────────────────────────────────────────────────
-    // CollapseQuestHeader(i)/ExpandQuestHeader(i) — header fold intents, drained by the app
-    // (which owns the collapse set and re-feeds the filtered list). Index 0 = ALL headers (the
-    // ref's collapse-all button, QuestLogFrame.lua:557/:561). Same intent pattern as the abandons.
+    // Header folds, drained by the app, which owns the collapse set; index 0 is every header.
     g.set(
         "CollapseQuestHeader",
         lua.create_function(|lua, i: u32| {
@@ -579,60 +448,73 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetAbandonQuest() — pin the current selection as the abandon target (ref
-    // QuestLogFrame.xml:464).
+    // ── The abandon two-step (mark → confirm) ────────────────────────────────────────────────────
+    // Marks the selected quest (`QuestLogFrame.xml:464`). The reference's `0x4dfb50` copies the
+    // selection, which there is a quest id (`0x4def30` stores it at `0x4def5d`); ours is a row
+    // index, so the id is resolved here, at the click, before the rows can move.
     g.set(
         "SetAbandonQuest",
         lua.create_function(|lua, ()| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            model.quest_log_abandon_mark = model.quest_log_selection;
+            let sel = model.quest_log_selection as usize;
+            model.quest_log_abandon_mark = sel
+                .checked_sub(1)
+                .and_then(|n| model.quest_log.entries.get(n))
+                .filter(|e| !e.is_header)
+                .map_or(0, |e| e.quest_id);
             Ok(())
         })?,
     )?;
-    // GetAbandonQuestName() → the pinned target's title ("" when none — the popup shows it).
+    // The marked quest's title, "" for none; the reference (`0x4dfb60`) reads the quest cache by
+    // id, the source of the rows' titles too.
     g.set(
         "GetAbandonQuestName",
         lua.create_function(|lua, ()| {
             let title = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
-                (model.quest_log_abandon_mark as usize)
-                    .checked_sub(1)
-                    .and_then(|n| model.quest_log.entries.get(n))
+                let mark = model.quest_log_abandon_mark;
+                model
+                    .quest_log
+                    .entries
+                    .iter()
+                    .find(|e| mark != 0 && !e.is_header && e.quest_id == mark)
                     .map(|e| e.title.clone())
                     .unwrap_or_default()
             };
             Ok(Value::String(lua.create_string(&title)?))
         })?,
     )?;
-    // GetAbandonQuestItems() → nil in v1 (the "you will also lose these quest items" list needs
-    // the template's SrcItem/required-item join against the bags — a dressing follow-up).
+    // Not built: nil, so the popup never lists the quest items an abandon destroys.
     g.set(
         "GetAbandonQuestItems",
         lua.create_function(|_, ()| Ok(Value::Nil))?,
     )?;
-    // AbandonQuest() — queue the pinned target as an outbound intent (the popup's Yes).
+    // The popup's Yes (`0x4dfe00` to `0x4df070`): the reference searches every row, folded ones
+    // included (`0xbb71c0`), for the marked id; a hit sends and clears the mark, a miss keeps it.
     g.set(
         "AbandonQuest",
         lua.create_function(|lua, ()| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            let mark = std::mem::take(&mut model.quest_log_abandon_mark);
-            if mark != 0 {
+            let mark = model.quest_log_abandon_mark;
+            let in_log = mark != 0
+                && (model
+                    .quest_log
+                    .entries
+                    .iter()
+                    .any(|e| !e.is_header && e.quest_id == mark)
+                    || model.quest_log.hidden_quest_ids.contains(&mark));
+            if in_log {
+                model.quest_log_abandon_mark = 0;
                 model.quest_log_abandons.push(mark);
             }
             Ok(())
         })?,
     )?;
 
-    // ── Timed quests (decision 1150) ─────────────────────────────────────────────────────────────
-    // The engine owns the countdown, as the reference's C bindings do: the pushed snapshot carries
-    // each row's absolute DEADLINE, and these subtract the live server clock per call. That split
-    // is what lets the ref's QuestTimerFrame re-read GetQuestTimers() every OnUpdate and paint a
-    // ticking number, while `set_quest_log` only fires QUEST_LOG_UPDATE when the log really moves.
+    // ── Timed quests ─────────────────────────────────────────────────────────────
 
-    // GetQuestTimers() → seconds remaining, ONE RETURN PER TIMED QUEST, in quest-log order — a
-    // genuine vararg return (the ref reads it as `QuestTimerFrame_Update(GetQuestTimers())` and
-    // walks `arg.n`, QuestTimerFrame.lua:11/:19). No timed quests → no values at all, which is the
-    // ref's own "hide the frame" signal.
+    // One return per live timer, in log order, re-read every OnUpdate: `QuestTimerFrame_Update`
+    // takes them as varargs and hides on none (`QuestTimerFrame.lua:11`, `:26`, `:37`).
     g.set(
         "GetQuestTimers",
         lua.create_function(|lua, ()| {
@@ -650,11 +532,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestIndexForTimer(timerIndex) → the 1-based QUEST-LOG index that timer belongs to (the
-    // same index space GetQuestLogTitle takes — headers included, since the app pushes them into
-    // the same list). The ref's timer buttons carry their 1-based ordinal as the frame id and map
-    // back through this for the click and the hover tooltip (QuestTimerFrame.lua:43,
-    // QuestTimerFrame.xml:20). Out of range → nil.
+    // A timer's 1-based row, headers counted, for the timer buttons' click and tooltip
+    // (`QuestTimerFrame.lua:43`, `QuestTimerFrame.xml:20`).
     g.set(
         "GetQuestIndexForTimer",
         lua.create_function(|lua, t: usize| {
@@ -677,9 +556,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestLogTimeLeft() → the SELECTION's seconds remaining, or nil when it has no timer —
-    // the ref branches on exactly that nil to show or hide its "Time Remaining:" row and to
-    // re-anchor the objectives beneath it (QuestLogFrame.lua:364-374).
+    // The selection's seconds left, nil without a timer, which hides the stock "Time Remaining:"
+    // row (`QuestLogFrame.lua:364`).
     g.set(
         "GetQuestLogTimeLeft",
         lua.create_function(|lua, ()| {
@@ -689,17 +567,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 .and_then(|n| model.quest_log.entries.get(n))
                 .and_then(|e| seconds_left(e, model.server_unix_time));
             Ok(match left {
-                // Clamped, not dropped — the reference's own asymmetry against the two list
-                // bindings above (decision 1154).
+                // Clamped where the lists drop the row, as in the reference.
                 Some(s) => Value::Integer(s.max(0)),
                 None => Value::Nil,
             })
         })?,
     )?;
 
-    // ── v1 stubs (each the seam of a named later slice — see the module doc) ─────────────────────
-    // GetQuestLogRewardSpell() → texture, name, isTradeskillSpell (0x4e1130): the selected
-    // quest's reward spell, three nils when it has none.
+    // ── Reward spell and party ───────────────────────────────────────────────────────────────────
+    // `texture, name, isTradeskillSpell` (`0x4e1130`), three nils without a reward spell.
     g.set(
         "GetQuestLogRewardSpell",
         lua.create_function(|lua, ()| {
@@ -716,15 +592,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "IsUnitOnQuest",
         lua.create_function(|_, (_q, _unit): (Value, Value)| Ok(flag(false)))?,
     )?;
-    // ── The quest watch (the on-screen tracker's state — ref QuestLogFrame.lua:469-505 shift-click
-    // toggle, :613-663 QuestWatch_Update). The set lives engine-side, keyed by the entries' stable
-    // quest ids (see QuestLogEntryView::quest_id) while the whole Era API speaks 1-based log
-    // indices; set_quest_log prunes watches whose quest left the log. MAX_WATCHABLE_QUESTS = 5
-    // (ref QuestLogFrame.lua:494) — AddQuestWatch past the cap is a no-op (the Lua shows the
-    // QUEST_WATCH_TOO_MANY error itself, mirroring the ref's guard order).
-    /// The entry the current selection points at — what every no-argument getter on this surface
-    /// reads (`GetQuestLogPushable`, and the C side of `QuestLogPushQuest`). `None` when nothing
-    /// is selected or the selection is out of range.
+    // ── The party share and the quest watch ──────────────────────────────────────────────────────
+    /// The selected row, which the share verbs read.
     fn selected_quest(model: &Model) -> Option<&QuestLogEntryView> {
         (model.quest_log_selection as usize)
             .checked_sub(1)
@@ -737,14 +606,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             .and_then(|n| model.quest_log.entries.get(n))
             .map(|e| e.quest_id)
     }
-    // ── The party share (decision 1733) — the ref's `QuestFramePushQuestButton`, whose enable
-    // predicate is `GetQuestLogPushable() and GetNumPartyMembers() > 0` (QuestLogFrame.lua:299-305)
-    // and whose OnClick is `QuestLogPushQuest()` (QuestLogFrame.xml:511-513). Both speak about the
-    // CURRENT SELECTION and take no argument, exactly as the reference declares them.
-    // `GetQuestLogPushable` returns `1` or **nil**, never `false` (`0x4e12b0` tail-calls
-    // `0x6f3810`/`0x6f37f0`, decision 1738). Both are falsy to the `and` in the reference's own
-    // predicate, so the button reads the same either way — but an addon testing `== nil` would
-    // not, and this is the Era idiom the rest of this surface already speaks (`GetPartyMember`).
+    // The share button enables on `GetQuestLogPushable() and GetNumPartyMembers() > 0`
+    // (`QuestLogFrame.lua:301`) and clicks `QuestLogPushQuest()` (`QuestLogFrame.xml:512`), both
+    // about the selection. `GetQuestLogPushable` answers 1 or nil, never false (`0x4e12b0`).
     g.set(
         "GetQuestLogPushable",
         lua.create_function(|lua, ()| {
@@ -759,12 +623,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         "QuestLogPushQuest",
         lua.create_function(|lua, ()| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // The C verb re-tests everything the Lua predicate tests **and one thing it does not**:
-            // a party check of its own (`0x4e13a6`, decision 1738). The reference does not trust
-            // its own button — an addon or a macro can call this solo, and the send is refused
-            // here rather than reaching the server. Resolve the id HERE rather than queueing the
-            // index (see `Model::quest_log_pushes`); a HEADER row carries `quest_id` 0, so an
-            // unguarded resolve would queue a push for quest 0.
+            // The verb checks the party and the sharable bit itself (`0x4e13a6`), as a macro can
+            // call it solo. The id is resolved now; a header's `quest_id` is 0 and never queues.
             if model.party.members.is_empty() {
                 return Ok(());
             }
@@ -777,6 +637,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
+    // The watch tracker's set (`QuestLogFrame.lua:469`, `:613`), keyed by quest id. At most
+    // `MAX_WATCHABLE_QUESTS`, 5 (`QuestLogFrame.lua:8`), which the stock Lua checks before adding
+    // (`:494`); an add past it is a no-op.
     g.set(
         "GetNumQuestWatches",
         lua.create_function(|lua, ()| {
@@ -815,8 +678,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetQuestIndexForWatch(watchSlot) → the watched quest's CURRENT 1-based log index (nil if it
-    // somehow isn't in the log — pruning makes that transient at worst).
+    // The watched quest's current 1-based row, nil when it is not a visible row.
     g.set(
         "GetQuestIndexForWatch",
         lua.create_function(|lua, w: usize| {
@@ -850,6 +712,7 @@ mod tests {
     fn two_quests() -> QuestLogState {
         QuestLogState {
             num_quests: 2,
+            hidden_quest_ids: Vec::new(),
             entries: vec![
                 QuestLogEntryView {
                     quest_id: 783,
@@ -912,7 +775,6 @@ mod tests {
     #[test]
     fn entries_and_title_tuple() {
         let mut s = UiScript::new().unwrap();
-        // Empty log: 0, 0; out-of-range title is nil.
         assert_eq!(
             s.eval::<(i64, i64)>("return GetNumQuestLogEntries()")
                 .unwrap(),
@@ -926,7 +788,6 @@ mod tests {
                 .unwrap(),
             (2, 2)
         );
-        // The 6-tuple, in order; complete=0 → nil, complete=1 → 1.
         assert!(s
             .eval::<bool>(
                 "local t, l, tag, h, c, done = GetQuestLogTitle(1)\n\
@@ -942,21 +803,16 @@ mod tests {
             .unwrap());
     }
 
-    /// The §5-verified arity contract (wow-re `ui/scratch/questlog-title-tag.md`, `0x4df930`):
-    /// six values ALWAYS, an out-of-range number is not an error, and return 2 is the number `0`
-    /// — while a missing or non-number argument raises `Usage:`.
+    /// The shape of `0x4df930`.
     #[test]
     fn out_of_range_is_six_values_with_a_zero_level_and_a_bad_arg_raises() {
         let mut s = UiScript::new().unwrap();
-        // Empty log: the first return is still nil (so the ref's `if ( questLogTitleText )`
-        // reads the same), but the tuple is full and the level is a NUMBER.
         assert_eq!(s.arity("GetQuestLogTitle(1)").unwrap(), 6);
         assert!(s
             .eval::<bool>("local t, l = GetQuestLogTitle(1) return t == nil and l == 0")
             .unwrap());
 
         s.set_quest_log(two_quests());
-        // Index 0 and a negative index are out of range, not errors — same six values.
         for i in ["0", "-1", "99"] {
             assert!(
                 s.eval::<bool>(&format!(
@@ -966,12 +822,11 @@ mod tests {
                 "index {i} is out of range, not an error"
             );
         }
-        // `_ftol` truncates toward zero, so 1.9 addresses entry 1.
+        // `_ftol` truncates toward zero: 1.9 is entry 1.
         assert!(s
             .eval::<bool>("return GetQuestLogTitle(1.9) == 'A Threat Within'")
             .unwrap());
 
-        // A missing / non-number argument is the other shape.
         for bad in ["", "nil", "{}", "print"] {
             let e = format!(
                 "{:?}",
@@ -985,8 +840,6 @@ mod tests {
         }
     }
 
-    /// §7's table for returns 4 and 5: `1` on a header, `nil` on a quest; `isCollapsed` is `1`
-    /// only for a COLLAPSED header — an expanded one and every quest row answer `nil`.
     #[test]
     fn is_header_and_is_collapsed_are_one_or_nil_never_booleans() {
         let mut s = UiScript::new().unwrap();
@@ -1011,17 +864,14 @@ mod tests {
         );
         s.set_quest_log(state);
 
-        // A collapsed header: both flags are the number 1.
         assert!(s
             .eval::<bool>(
                 "local _, l, _, h, c = GetQuestLogTitle(1) return h == 1 and c == 1 and l == 0"
             )
             .unwrap());
-        // An EXPANDED header: isHeader 1, isCollapsed nil.
         assert!(s
             .eval::<bool>("local _, _, _, h, c = GetQuestLogTitle(2) return h == 1 and c == nil")
             .unwrap());
-        // A quest row: both nil — and `false` would be wrong, so pin the type too.
         assert!(s
             .eval::<bool>(
                 "local _, _, _, h, c = GetQuestLogTitle(3)\n\
@@ -1032,10 +882,6 @@ mod tests {
 
     #[test]
     fn tag_is_the_bare_word_and_nil_when_absent() {
-        // The third return is the BARE word — the ref's own Lua adds the parentheses
-        // (`"("..questTag..")"`, ref QuestLogFrame.lua:195), so pushing "(Elite)" here would
-        // paint "((Elite))". An untagged quest pushes nil, not "", because the ref branches on
-        // presence (`if ( questTag )`, ref l.194).
         let mut s = UiScript::new().unwrap();
         let mut state = two_quests();
         state.entries[1].tag = Some("Elite".into());
@@ -1053,7 +899,6 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_quest_log(two_quests());
         assert_eq!(s.eval::<i64>("return GetQuestLogSelection()").unwrap(), 0);
-        // The ref's click flow: select then immediately re-read in the same chunk.
         assert_eq!(
             s.eval::<i64>("SelectQuestLogEntry(2); return GetQuestLogSelection()")
                 .unwrap(),
@@ -1062,13 +907,6 @@ mod tests {
         assert_eq!(s.quest_log_selection(), 2);
     }
 
-    /// **The bug decision 2247 fixes, in the shape every addon hits it.** The classic quest-log
-    /// walk — `SelectQuestLogEntry(i)` then `GetQuestLogQuestText()`, once per entry, all inside
-    /// ONE frame with no push between — must answer about the row just selected. It used to answer
-    /// with whichever row the snapshot had been built against, for every entry: Questie 3.7.1 fed
-    /// that text to its `getQuestHash` Levenshtein match and wrote the WRONG same-name chain step
-    /// into a character's saved history (two of the director's Tirisfal quests, both resolved to
-    /// the shortest sibling — the signature of matching against an unrelated string).
     #[test]
     fn a_log_walk_answers_per_entry_without_a_push_between() {
         let mut s = UiScript::new().unwrap();
@@ -1090,7 +928,6 @@ mod tests {
         );
     }
 
-    /// The same seam for the money/reward getters, which read the detail through their own path.
     #[test]
     fn the_detail_counts_follow_the_selection_too() {
         let mut s = UiScript::new().unwrap();
@@ -1112,8 +949,6 @@ mod tests {
         );
     }
 
-    /// A header row has no quest under it, so its detail reads as nothing at all rather than as
-    /// the previous selection's — the same staleness, one row over.
     #[test]
     fn a_header_selection_has_no_detail() {
         let mut s = UiScript::new().unwrap();
@@ -1149,7 +984,6 @@ mod tests {
             s.eval::<i64>("return GetNumQuestLeaderBoards()").unwrap(),
             1
         );
-        // The optional-arg form answers for ANY entry (the tracker HUD's path).
         assert_eq!(
             s.eval::<i64>("return GetNumQuestLeaderBoards(1)").unwrap(),
             1
@@ -1185,9 +1019,6 @@ mod tests {
             .eval::<bool>("return GetQuestLogChoiceInfo(1) == nil")
             .unwrap());
 
-        // GetQuestLogItemLink: kind-dispatched (the shape the ref's QuestLogRewardItem_OnClick
-        // calls it with — `this.type`), nil for the empty choice list, an out-of-range index and
-        // an unknown type.
         assert_eq!(
             s.eval::<String>("return GetQuestLogItemLink(\"reward\", 1)")
                 .unwrap(),
@@ -1213,11 +1044,10 @@ mod tests {
             s.eval::<String>("return GetAbandonQuestName()").unwrap(),
             "Kobold Camp Cleanup"
         );
-        // Selection moves before the confirm — the mark must not follow it.
+        // The mark is the quest id (`0x4dfb50`), not the selection: entry 2 is quest 7.
         s.run("SelectQuestLogEntry(1); AbandonQuest()").unwrap();
-        assert_eq!(s.take_quest_log_abandons(), vec![2]);
+        assert_eq!(s.take_quest_log_abandons(), vec![7]);
         assert!(s.take_quest_log_abandons().is_empty(), "drained");
-        // A bare AbandonQuest with no mark queues nothing.
         s.run("AbandonQuest()").unwrap();
         assert!(s.take_quest_log_abandons().is_empty());
     }
@@ -1241,16 +1071,14 @@ mod tests {
     fn watch_set_is_id_keyed_and_survives_a_log_shuffle() {
         let mut s = UiScript::new().unwrap();
         s.set_quest_log(two_quests());
-        // Watch entry 2 (quest 7); the index-based API reads it back.
-        s.run("AddQuestWatch(2)").unwrap();
+        s.run("AddQuestWatch(2)").unwrap(); // quest 7
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 1);
         assert!(s.eval::<bool>("return IsQuestWatched(2)").unwrap());
         assert!(!s.eval::<bool>("return IsQuestWatched(1)").unwrap());
         assert_eq!(s.eval::<i64>("return GetQuestIndexForWatch(1)").unwrap(), 2);
         assert_eq!(s.quest_log_watched(), vec![7]);
 
-        // The log shuffles: entry 1 (quest 783) is abandoned, quest 7 compacts to index 1 — the
-        // watch FOLLOWS THE QUEST, not the index.
+        // Quest 783 leaves and quest 7 moves to row 1, keeping its watch.
         let mut shuffled = two_quests();
         shuffled.entries.remove(0);
         s.set_quest_log(shuffled);
@@ -1258,7 +1086,6 @@ mod tests {
         assert!(s.eval::<bool>("return IsQuestWatched(1)").unwrap());
         assert_eq!(s.eval::<i64>("return GetQuestIndexForWatch(1)").unwrap(), 1);
 
-        // Unwatch by the new index; and a watched quest leaving the log prunes its watch.
         s.run("RemoveQuestWatch(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 0);
         s.run("AddQuestWatch(1)").unwrap();
@@ -1266,39 +1093,70 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 0);
     }
 
-    /// The countdown trio (decisions 1150/1154). One deadline stamp in the snapshot, one clock
-    /// pushed beside it, and every read is a live subtraction — so advancing the clock alone (no
-    /// re-push of the log) makes the number fall, which is precisely what the reference's
-    /// per-OnUpdate `GetQuestTimers()` depends on.
-    ///
-    /// Every number below carries the reference's `−1` (`value = deadline + G − now − 1`,
-    /// byte-verified at all four of its consumers): 500 seconds of wall gap reads 499.
+    /// The prune (`0x4de7a7` to `0x4de80f`) counts folded quests; a collapse never prunes.
+    #[test]
+    fn a_collapsed_header_keeps_its_quests_watched() {
+        let header = |collapsed| QuestLogEntryView {
+            title: "Elwynn Forest".into(),
+            is_header: true,
+            collapsed,
+            ..Default::default()
+        };
+        let expanded = || {
+            let mut state = two_quests();
+            state.entries.insert(0, header(false));
+            state
+        };
+        let mut s = UiScript::new().unwrap();
+        s.set_quest_log(expanded());
+        s.run("AddQuestWatch(3)").unwrap(); // quest 7
+        assert_eq!(s.quest_log_watched(), vec![7]);
+
+        // Collapsed: only the header is visible.
+        s.set_quest_log(QuestLogState {
+            entries: vec![header(true)],
+            num_quests: 2,
+            hidden_quest_ids: vec![783, 7],
+        });
+        assert_eq!(
+            s.eval::<i64>("return GetNumQuestWatches()").unwrap(),
+            1,
+            "a collapse must not prune the watch of a quest still in the log"
+        );
+        s.set_quest_log(expanded());
+        assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 1);
+        assert_eq!(s.eval::<i64>("return GetQuestIndexForWatch(1)").unwrap(), 3);
+
+        // Quest 7 leaves the log, neither visible nor folded.
+        let mut gone = expanded();
+        gone.entries.retain(|e| e.quest_id != 7);
+        gone.num_quests = 1;
+        s.set_quest_log(gone);
+        assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 0);
+    }
+
+    /// Every value carries the reference's `-1`: 500 seconds to the deadline reads 499.
     #[test]
     fn timers_count_down_against_the_pushed_server_clock() {
         let mut s = UiScript::new().unwrap();
         let mut state = two_quests();
-        // Quest 2 is on a 15-minute leash that ends at unix 1_000_900; quest 1 is untimed.
         state.entries[1].timer = 1_000_900;
         s.set_quest_log(state);
 
-        // No clock sample yet: nothing to subtract from, so nothing is claimed.
+        // No server clock yet.
         assert_eq!(s.arity("GetQuestTimers()").unwrap(), 0);
         assert!(s
             .eval::<bool>("return GetQuestLogTimeLeft() == nil")
             .unwrap());
 
-        // 400 s in.
         s.set_server_unix_time(1_000_400.0);
         assert_eq!(s.arity("GetQuestTimers()").unwrap(), 1);
         assert_eq!(s.eval::<i64>("return (GetQuestTimers())").unwrap(), 499);
-        // The timer maps back to entry 2 — the untimed row 1 does not shift the mapping.
         assert_eq!(s.eval::<i64>("return GetQuestIndexForTimer(1)").unwrap(), 2);
         assert!(s
             .eval::<bool>("return GetQuestIndexForTimer(2) == nil")
             .unwrap());
 
-        // The selection's own reading: nil on the untimed row, the count on the timed one — the
-        // exact branch the ref's "Time Remaining:" row keys on.
         s.run("SelectQuestLogEntry(1)").unwrap();
         assert!(s
             .eval::<bool>("return GetQuestLogTimeLeft() == nil")
@@ -1306,16 +1164,15 @@ mod tests {
         s.run("SelectQuestLogEntry(2)").unwrap();
         assert_eq!(s.eval::<i64>("return GetQuestLogTimeLeft()").unwrap(), 499);
 
-        // Only the CLOCK moves — no set_quest_log — and the number falls anyway.
+        // Only the clock moves, and the number falls.
         s.set_server_unix_time(1_000_880.0);
         assert_eq!(s.eval::<i64>("return GetQuestLogTimeLeft()").unwrap(), 19);
 
-        // The last second reads 0, not 1 — the `−1`'s downward bias at the very end of the window.
+        // The last second reads 0.
         s.set_server_unix_time(1_000_899.0);
         assert_eq!(s.eval::<i64>("return GetQuestLogTimeLeft()").unwrap(), 0);
 
-        // Past the deadline the two bindings SPLIT, exactly as the reference's do: the list drops
-        // the row (its `js`), while GetQuestLogTimeLeft clamps at 0 and keeps answering.
+        // Past the deadline the lists drop the row and `GetQuestLogTimeLeft` clamps to 0.
         s.set_server_unix_time(1_000_910.0);
         assert_eq!(s.eval::<i64>("return GetQuestLogTimeLeft()").unwrap(), 0);
         assert_eq!(s.arity("GetQuestTimers()").unwrap(), 0);
@@ -1324,15 +1181,13 @@ mod tests {
             .unwrap());
     }
 
-    /// A FAILED timed quest shows no timer. vmangos writes the slot timer to the literal `1` and
-    /// sets the FAIL state bit (`Player::FailQuest`), leaving the row in the log until the player
-    /// abandons it — so without the state test the frame would show a clamped "0" for ever.
+    /// vmangos sets a failed quest's timer to 1 and leaves it in the log (`Player::FailQuest`).
     #[test]
     fn a_failed_timed_quest_drops_out_of_the_timer_list() {
         let mut s = UiScript::new().unwrap();
         let mut state = two_quests();
         state.entries[0].timer = 1_000_900;
-        state.entries[1].timer = 1; // failed: the server's own sentinel
+        state.entries[1].timer = 1; // failed: the server's sentinel
         state.entries[1].complete = -1;
         s.set_quest_log(state);
         s.set_server_unix_time(1_000_400.0);
@@ -1362,16 +1217,13 @@ mod tests {
         for i in 1..=6 {
             s.run(&format!("AddQuestWatch({i})")).unwrap();
         }
-        // The sixth add is a no-op (MAX_WATCHABLE_QUESTS = 5, ref QuestLogFrame.lua:494).
+        // `MAX_WATCHABLE_QUESTS` is 5 (`QuestLogFrame.lua:8`).
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 5);
-        // A duplicate add neither grows nor reorders.
         s.run("AddQuestWatch(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetNumQuestWatches()").unwrap(), 5);
         assert_eq!(s.quest_log_watched(), vec![1, 2, 3, 4, 5]);
     }
 
-    /// `GetQuestLogPushable` answers about the SELECTION, and only about the selection — the Era
-    /// API has no per-index form (decision 1733). Selecting the other quest changes the answer.
     #[test]
     fn pushable_follows_the_selection() {
         let mut s = UiScript::new().unwrap();
@@ -1379,8 +1231,6 @@ mod tests {
         state.entries[0].pushable = true; // 783 is sharable, 7 is not
         s.set_quest_log(state);
 
-        // `1` or nil, never true/false (`0x4e12b0`, decision 1738) — an addon testing `== nil`
-        // sees the reference's own shape.
         assert_eq!(
             s.eval::<Option<i64>>("return GetQuestLogPushable()")
                 .unwrap(),
@@ -1401,11 +1251,52 @@ mod tests {
         );
     }
 
-    /// `QuestLogPushQuest` queues the selected entry's **quest id**, resolved at click time — not
-    /// its index, so a log that reshuffles between the click and the app's drain cannot retarget
-    /// the push. (Contrast the abandon mark, which pins an index on purpose: its two-step confirm
-    /// is what makes the index the right thing to hold.)
-    /// A party of one other, so the C verb's own party check (below) passes.
+    /// A miss keeps the mark, as `0x4df070` returns before the clear at `0x4df0cf`.
+    #[test]
+    fn abandon_mark_is_a_quest_id_that_survives_a_reindex() {
+        let mut s = UiScript::new().unwrap();
+        s.set_quest_log(two_quests());
+        s.run("SelectQuestLogEntry(2); SetAbandonQuest()").unwrap(); // quest 7
+
+        // Quest 7 moves to row 1 and a stranger takes row 2.
+        let mut moved = two_quests();
+        moved.entries.swap(0, 1);
+        moved.entries[1].quest_id = 999;
+        s.set_quest_log(moved.clone());
+        assert_eq!(
+            s.eval::<String>("return GetAbandonQuestName()").unwrap(),
+            "Kobold Camp Cleanup"
+        );
+        s.run("AbandonQuest()").unwrap();
+        assert_eq!(s.take_quest_log_abandons(), vec![7]);
+
+        // Folded away: still abandonable.
+        s.run("SelectQuestLogEntry(1); SetAbandonQuest()").unwrap();
+        let mut folded = moved.clone();
+        folded.entries.remove(0);
+        folded.hidden_quest_ids = vec![7];
+        s.set_quest_log(folded);
+        s.run("AbandonQuest()").unwrap();
+        assert_eq!(s.take_quest_log_abandons(), vec![7]);
+
+        // Gone from the log: nothing queues, and the mark stays.
+        s.set_quest_log(moved.clone());
+        s.run("SelectQuestLogEntry(1); SetAbandonQuest()").unwrap();
+        let mut gone = moved.clone();
+        gone.entries.remove(0);
+        s.set_quest_log(gone);
+        s.run("AbandonQuest()").unwrap();
+        assert!(s.take_quest_log_abandons().is_empty());
+        s.set_quest_log(moved);
+        s.run("AbandonQuest()").unwrap();
+        assert_eq!(
+            s.take_quest_log_abandons(),
+            vec![7],
+            "the kept mark still names 7"
+        );
+    }
+
+    /// A party of one other, so `QuestLogPushQuest`'s party check passes.
     fn in_a_party(s: &mut UiScript) {
         s.set_party(crate::script::PartyState {
             members: vec![crate::script::PartyMemberInfo {
@@ -1429,9 +1320,6 @@ mod tests {
         assert!(s.take_quest_log_pushes().is_empty(), "drained");
     }
 
-    /// A push with nothing selected is silently nothing — the window's button is disabled in that
-    /// state, so this is only reachable from a macro or an addon, and the client has no quest id
-    /// to send.
     #[test]
     fn push_without_a_selection_queues_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -1441,9 +1329,7 @@ mod tests {
         assert!(s.take_quest_log_pushes().is_empty());
     }
 
-    /// **The C verb re-tests the party and the sharable bit itself** (`0x4e13a6`, decision 1738) —
-    /// the reference does not trust its own button, because a macro or an addon can call this with
-    /// the window shut. Each guard is moved alone, against an otherwise-valid push.
+    /// `0x4e13a6` checks the party and the sharable bit itself; each guard is tested alone.
     #[test]
     fn push_refuses_solo_and_refuses_an_unsharable_quest() {
         let sharable = || {
@@ -1452,19 +1338,16 @@ mod tests {
             state
         };
 
-        // Solo: everything else is right and it still sends nothing.
         let mut s = UiScript::new().unwrap();
         s.set_quest_log(sharable());
         s.run("SelectQuestLogEntry(1)").unwrap();
         s.run("QuestLogPushQuest()").unwrap();
         assert!(s.take_quest_log_pushes().is_empty(), "solo pushes nothing");
 
-        // In a party, the same call goes.
         in_a_party(&mut s);
         s.run("QuestLogPushQuest()").unwrap();
         assert_eq!(s.take_quest_log_pushes(), vec![783]);
 
-        // In a party, on a quest without the sharable bit: nothing again.
         s.run("SelectQuestLogEntry(2)").unwrap();
         s.run("QuestLogPushQuest()").unwrap();
         assert!(
@@ -1473,9 +1356,6 @@ mod tests {
         );
     }
 
-    /// A HEADER row carries `quest_id` 0, so pushing one must queue nothing at all — an unguarded
-    /// id resolve would send `CMSG_PUSHQUESTTOPARTY{0}`. The window's button is disabled on a
-    /// header, so only a macro or an addon can get here.
     #[test]
     fn push_on_a_header_row_queues_nothing() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/region.rs b/crates/benilla-ui/src/script/region.rs
index 569364d9..db7c064c 100644
--- a/crates/benilla-ui/src/script/region.rs
+++ b/crates/benilla-ui/src/script/region.rs
@@ -1,8 +1,5 @@
-//! The **region** side of the object model (RF-0023's distinct-tag leaves): the `Texture`/
-//! `FontString` wrapper cache, their shared metatable, and the region method surface. Split from
-//! [`super::object`] (which keeps the frame side + `CreateFrame`) so each grows along its own
-//! axis — frames grow per-kind method tables ([`super::statusbar`], [`super::button`]), regions
-//! grow paint/coords methods here.
+//! The region side of the object model ([`super::object`] is the frame side): the region wrapper
+//! cache, the Region, Texture, FontString and title-region method tables, and the portrait globals.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -10,6 +7,7 @@ use super::object::anchor_args::{parse_set_point, resolve_rel_target, UNNAMED};
 use super::object::{
     anchor_bits_eq, anchor_retarget_is_structural, decode_id, id_to_lud, NamedTarget,
 };
+use super::region_map::{set_shared, Side};
 use super::{
     Model, REG_FONTSTRING_META, REG_FONTSTRING_METHODS, REG_REGION_META, REG_REGION_METHODS,
     REG_TEXTURE_META, REG_TEXTURE_METHODS, REG_TITLE_META, REG_TITLE_METHODS, REG_WRAPPERS, SCREEN,
@@ -28,21 +26,10 @@ pub(super) fn region_handle_of(lua: &Lua, this: &Table) -> mlua::Result<RegionHa
         .ok_or_else(|| mlua::Error::runtime("stale or invalid region handle"))
 }
 
-/// Apply the font parts an **XML element** supplies — `font=`, `<FontHeight>`, `outline=` — any
-/// subset of which may be absent.
-///
-/// **This is deliberately not the `SetFont` binding, and that separation is the point.** The
-/// reference applies XML font attributes in C++ (`LoadXML`), never through the Lua method, and its
-/// `SetFont` therefore *requires* both a path and a height, raising
-/// `Usage: %s:SetFont("font", fontHeight [, flags])` (`0x87c69c`) without them. Our loader used to
-/// call the binding with three `Option`s — `SetFont(nil, nil, "OUTLINE")` for an outline-only
-/// `<FontString>` — which is why that binding could not be made faithful: one name was doing two
-/// jobs, and the more lenient job won. Splitting them lets `SetFont` be the reference's `SetFont`
-/// and lets the loader keep the partial application XML actually needs.
-///
-/// Each part supplied is an **explicit** set (`FontExplicit`), so it survives a later mutation of
-/// the font object this region inherits. An empty `font=` is treated as absent — it keeps the
-/// inherited face, rather than being the binding's load-failure edge.
+/// Apply the font parts an XML element supplies (`font=`, `<FontHeight>`, `outline=`), any of
+/// which may be absent. Not the `SetFont` binding: the reference applies XML fonts in `LoadXML`,
+/// and its `SetFont` requires a path and a height (`0x87c69c`). Each part is an explicit set, so it
+/// survives a change to the inherited font object; an empty `font=` keeps the inherited face.
 pub(crate) fn apply_font_parts(
     lua: &Lua,
     this: &Table,
@@ -69,7 +56,7 @@ pub(crate) fn apply_font_parts(
     Ok(())
 }
 
-/// Get-or-create the wrapper table for a region id (distinct metatable — the region "tag").
+/// Get or create the wrapper table for a region id, with its kind's metatable.
 pub(super) fn region_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     let wrappers: Table = lua.named_registry_value(REG_WRAPPERS)?;
     if let Value::Table(t) = wrappers.get::<Value>(id)? {
@@ -77,11 +64,8 @@ pub(super) fn region_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     }
     let t = lua.create_table()?;
     t.raw_set(0, Value::LightUserData(id_to_lud(id)))?;
-    // **A title region gets a NARROWER metatable, chosen here rather than per lookup.** wow-re Q6
-    // carves the object as answering *exactly* the 19 Region methods — no Show/Hide, no textures,
-    // no text — and this cache is created once per region, so picking the table at construction
-    // costs nothing on the call path (dispatching inside `__index` would put a model borrow and a
-    // kind lookup in front of EVERY region method call in the UI).
+    // The metatable is chosen once, here, not per call: a title region
+    // (`CreateTitleRegion 0x773910`) answers only the 19 Region methods.
     let kind = {
         let model = lua.app_data_ref::<Model>().expect("model");
         model
@@ -94,9 +78,7 @@ pub(super) fn region_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
         Some(RegionKind::Texture) => REG_TEXTURE_META,
         Some(RegionKind::FontString) => REG_FONTSTRING_META,
         Some(RegionKind::Title) => REG_TITLE_META,
-        // A wrapper for an id with no live region: the full table, which is what this cache did for
-        // every region before the leaves were split. Nothing can call through it — every method
-        // resolves the handle first and raises on a dead one.
+        // No live region: the full table, harmless since every method raises on a dead handle.
         None => REG_REGION_META,
     })?;
     t.set_metatable(Some(meta))?;
@@ -104,27 +86,19 @@ pub(super) fn region_wrapper(lua: &Lua, id: u32) -> mlua::Result<Table> {
     Ok(t)
 }
 
-/// Install the region method table + the shared region metatable.
+/// Install the region method tables and the region globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     install_region_methods(lua)?;
 
-    // SetPortraitTexture(textureRegion, unit) — the live API's **global** (ref-UnitFrame.lua:
-    // `SetPortraitTexture(this.portrait, this.unit)`), distinct from the region-method
-    // `SetPortraitToTexture(path)` icon crop. It binds a Texture region to a unit token; the app
-    // renders that unit's model off-screen and feeds the bake back through the region's
-    // [`super::QuadContent::Texture::portrait_unit`], with `circular` marking the round stencil
-    // (the bake is square with an opaque backdrop; the frame-ring portraits cut the inscribed
-    // circle, exactly what the app's quad shader does with the flag). `texture`/`color` drop —
-    // the bake replaces them. A later `SetTexture`/`SetPortraitToTexture` clears the binding.
+    // SetPortraitTexture(texture, unit) (`UnitFrame.lua:26`): binds the region to a unit whose
+    // model the app bakes off-screen, drawn masked to its inscribed circle; a later `SetTexture`
+    // or `SetPortraitToTexture` clears it.
     lua.globals().set(
         "SetPortraitTexture",
         lua.create_function(|lua, (region, unit): (Table, Value)| {
-            // `0x519ef0` gates its unit argument at `0x519fb4` with `lua_isstring` and fails into
-            // `luaL_error` with this exact string (`0x8513b8`); `luaL_error` does not return, so
-            // nil/absent/boolean/table abandon the caller's statement. Stock
-            // `Blizzard_InspectUI.lua:49` reaches it on a re-open, which is how it was found.
-            // A token that RESOLVES to nothing is a different, quiet case — it blanks the portrait
-            // and returns no values. Decision 1834.
+            // A non-string unit raises this exact error (`0x519fb4`, `0x8513b8`), which stock
+            // `Blizzard_InspectUI.lua:49` hits on a re-open; a token that resolves to nothing only
+            // blanks the portrait.
             let unit = crate::script::binding_abi::string_arg(
                 lua,
                 unit,
@@ -133,14 +107,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             let rh = region_handle_of(lua, &region)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let data = model.region_data.entry(rh).or_default();
-            // CANONICAL (lowercase) on the way in, like `set_unit`'s map key: the binding
-            // resolves its token through the one resolver every `Unit*` binding shares
-            // (`0x519ef0` → `0x515970`), whose every compare is `_strnicmp` — so the stock
-            // `MerchantFrame.lua:68`, `GuildRegistrarFrame.lua:4` and `TradeFrame.lua:41` all
-            // write `"NPC"` and mean `"npc"`. The app samples the booth by this string
-            // (`portrait::PortraitImages`, keyed by the lowercase slot names), and a raw `"NPC"`
-            // reached it and matched nothing: an empty portrait ring on all three windows
-            // (decision 2022).
+            // Lowercased: the reference resolves the token case-insensitively (`0x519ef0` →
+            // `0x515970`), stock `MerchantFrame.lua:68` passes `"NPC"`, and the app's bakes are
+            // keyed lowercase.
             data.portrait_unit = Some(unit.to_ascii_lowercase());
             data.texture = None;
             data.fill = None;
@@ -149,25 +118,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetPortraitToTexture(textureName, path) — the ENGINE GLOBAL, which is what 1.12 has.
-    //
-    // `reference/1.12-globals.tsv` marks it `engine`, and the reference's own two call sites both
-    // pass a texture NAME: `ContainerFrame.lua:419` writes
-    // `SetPortraitToTexture(frame:GetName().."Portrait", "…KeyRing-Bag-Icon")` and
-    // `MailFrame.lua:174` writes `SetPortraitToTexture("OpenMailFrameIcon", stationeryIcon)`.
-    // **That first one matters here: we SOURCE `ContainerFrame.lua` off the patch chain, so the
-    // client's own file calls this global inside our VM.**
-    //
-    // A NAME, not a region handle — strictly what the reference's callers are attested to pass.
-    // Whether the real binding also accepts a texture object is not carved, so it is not accepted
-    // here: inventing the wider signature is how a superset starts (1189), and nothing needs it —
-    // both of our own callers already hold the name.
-    //
-    // The behaviour is the crop it was always: set the texture AND mark the region a portrait, so
-    // it draws masked to its inscribed circle. The client's portraits are circular and the frame
-    // ring is a thin band whose transparent corners would otherwise show the square texture's
-    // edges. Distinct from `SetPortraitTexture(region, unit)`'s live model bake, so it drops any
-    // live-unit binding; a later `SetTexture` clears the flag again.
+    // SetPortraitToTexture(textureName, path), an engine global: sets the texture, drawn masked
+    // to its inscribed circle, and drops any unit binding. It takes the name, as both stock
+    // callers pass (`ContainerFrame.lua:419`, `MailFrame.lua:174`); whether the reference also
+    // takes a region object is untraced.
     lua.globals().set(
         "SetPortraitToTexture",
         lua.create_function(|lua, (name, path): (String, String)| {
@@ -186,17 +140,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BenillaSetBoothTexture(textureRegion, slotToken) — the **square** twin of
-    // SetPortraitTexture (decision 0208 §5): the same `portrait_unit` booth-image binding
-    // WITHOUT the circular mask, for a body pane whose texture region samples the booth's bake
-    // edge to edge (no frame ring to mask for). Benilla-named because it is not the live API: it
-    // is the pane→booth join written in Lua.
-    //
-    // **RETIRING.** A migrated window's file is the reference's, which declares a bare
-    // `<PlayerModel>` and no texture at all, so the join moved app-side
-    // (`portrait::MODEL_PANE_BOOTHS`) and the widget draws itself (decision 1810). Two callers are
-    // left — the dressing room and the inspect window, both still our own files — and this goes
-    // with the later of them.
+    // BenillaSetBoothTexture(texture, slotToken): `SetPortraitTexture` without the circular mask;
+    // not a 1.12 global.
     lua.globals().set(
         "BenillaSetBoothTexture",
         lua.create_function(|lua, (region, token): (Table, String)| {
@@ -211,12 +156,13 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
+    // `__index` is the method table itself, here and on the leaf metatables, not a function
+    // (~9 ns against ~195 ns per method access); sound while nothing replaces these tables.
     let region_meta = lua.create_table()?;
-    let region_index = lua.create_function(|lua, (_this, key): (Table, Value)| {
-        let methods: Table = lua.named_registry_value(REG_REGION_METHODS)?;
-        methods.get::<Value>(key)
-    })?;
-    region_meta.set("__index", region_index)?;
+    region_meta.set(
+        "__index",
+        lua.named_registry_value::<Table>(REG_REGION_METHODS)?,
+    )?;
     lua.set_named_registry_value(REG_REGION_META, region_meta)?;
     Ok(())
 }
@@ -228,69 +174,42 @@ mod text;
 fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // GetName() → this region's global name, or nil when it was declared anonymously — the pair
-    // the frame side already answers. Real FrameXML round-trips a region through its name wherever
-    // it can't hold a reference to itself: `ComboFrame.lua`'s shine chain hands `frame:GetName()`
-    // to a fade `finishedFunc` and `getglobal`s it back ("hack since a frame can't have a
-    // reference to itself in it" — its own comment).
-    //
-    // Resolution is [`region_name_of`], shared with `IsObjectType`'s `Usage:` text so the two can
-    // never disagree about what this region is called.
-    m.set(
-        "GetName",
-        lua.create_function(|lua, this: Table| {
-            let id = decode_id(&this)?;
-            let model = lua.app_data_ref::<Model>().expect("model app_data");
-            match region_name_of(&model, id) {
-                Some(n) => Ok(Value::String(lua.create_string(&n)?)),
-                None => Ok(Value::Nil),
-            }
-        })?,
-    )?;
+    // GetName(): the global name, or nil for an anonymous region.
+    set_shared(lua, &m, Side::Region, "GetName", |lua, this: Table| {
+        let id = decode_id(&this)?;
+        let model = lua.app_data_ref::<Model>().expect("model app_data");
+        match region_name_of(&model, id) {
+            Some(n) => Ok(Value::String(lua.create_string(&n)?)),
+            None => Ok(Value::Nil),
+        }
+    })?;
 
-    // ── GetObjectType / IsObjectType: the last two of the Region map (1244 §4 closed) ───────────
+    // ── GetObjectType / IsObjectType ─────────────────────────────────────────────────────────
     //
-    // 1244 shipped four of the six missing Region-map members and deliberately left these two
-    // DISPATCHED rather than guessed, because every interesting detail is one a plausible
-    // implementation gets wrong. wow-re answered (§5 trio + byte cross-check,
-    // `system/ui/scratch/widget-type-identity.md`), and every one of those details is below.
-    //
-    // `GetObjectType` is a per-class `.data` `const char*` read through `vtable[+0x1c]` — Texture
-    // `0x773480` → `"Texture"`, FontString `0x7735d0` → `"FontString"` — pushed with
-    // `lua_pushstring`, exactly one value, extra arguments ignored with no arity check.
-    m.set(
+    // GetObjectType: a per-class string through `vtable[+0x1c]` (Texture `0x773480`, FontString
+    // `0x7735d0`), one value, extra arguments ignored.
+    set_shared(
+        lua,
+        &m,
+        Side::Region,
         "GetObjectType",
-        lua.create_function(|lua, this: Table| {
+        |lua, this: Table| {
             let rh = region_handle_of(lua, &this)?;
             let model = lua.app_data_ref::<Model>().expect("model");
             Ok(region_type_name(&model, rh))
-        })?,
+        },
     )?;
 
-    // `IsObjectType(name)` — binding `0x7a1290`. Four traps, all verified, all here:
-    //
-    //  · **Case-INSENSITIVE, whole-string.** `vtable[+0x18]` → `SStrCmpI 0x64a4c0` → `_strnicmp`,
-    //    which folds both operands before comparing and breaks at the first NUL on either side —
-    //    so no prefix or substring match either. (The *method-name* lookup `0x702000` uses the
-    //    case-SENSITIVE sibling; the two are easy to conflate and behave differently.)
-    //  · **A short, hardcoded chain — and there is no root type.** Texture answers `"Texture"` and
-    //    `"Region"`; FontString answers `"FontString"` and `"Region"`. **1.12.1 has no
-    //    `"LayoutFrame"`, `"ScriptObject"` or `"Object"` type at all** — those strings exist only
-    //    inside `__FILE__` paths and allocator tags — so `tex:IsObjectType("LayoutFrame")` is nil.
-    //    That is the single most likely thing to invent from knowing later clients.
-    //  · **A hit is the NUMBER 1 and a miss is nil — never a boolean**, read off the pushed tags
-    //    (`lua_pushnumber` tag 3 vs `lua_pushnil` tag 0; tag 1 is never written), and exactly one
-    //    value on both paths.
-    //  · **A bad argument RAISES.** The gate is `lua_isstring`, which accepts strings and NUMBERS
-    //    only; anything else (missing, nil, boolean, table, function, userdata) hits
-    //    `luaL_error(L, "Usage: %s:IsObjectType(\"TYPE\")")` with `%s` the region's name or
-    //    `<unnamed>`, and that longjmps rather than returning. A number is ACCEPTED and stringified
-    //    in place, so `tex:IsObjectType(5)` compares against `"5"` and quietly answers nil — we
-    //    format it and compare for real rather than short-circuiting, though no type name is
-    //    numeric so the answer is nil either way.
-    m.set(
+    // IsObjectType(name) (`0x7a1290`): a case-insensitive whole-string match (`0x64a4c0`) against
+    // the leaf or "Region" only, as 1.12 has no LayoutFrame, ScriptObject or Object type; a hit is
+    // the number 1, a miss nil. A number is stringified and compared; anything else raises the
+    // usage error, naming the region or `<unnamed>`.
+    set_shared(
+        lua,
+        &m,
+        Side::Region,
         "IsObjectType",
-        lua.create_function(|lua, (this, want): (Table, Value)| {
+        |lua, (this, want): (Table, Value)| {
             let rh = region_handle_of(lua, &this)?;
             let model = lua.app_data_ref::<Model>().expect("model");
             let want = match &want {
@@ -308,36 +227,19 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
             let leaf = region_type_name(&model, rh);
             let hit = want.eq_ignore_ascii_case(leaf) || want.eq_ignore_ascii_case("Region");
             Ok(if hit { Value::Number(1.0) } else { Value::Nil })
-        })?,
+        },
     )?;
 
-    // SetParent(frame) — **a Texture/FontString really does have this**, and we were the ones
-    // missing it. `SetParent` lives in the REGION method table (`0x7a1550`); Texture's class lookup
-    // falls back to Region's at `0x79c650` and FontString's at `0x79ee50`, so both reach it (wow-re
-    // `system/ui/scratch/widget-api-batch-benilla.md` Q7, §5-verified). `FuBar_FuXPFu.lua:210`'s
-    // `self.Spark:SetParent(self.XPBar)` is not a broken addon.
-    //
-    // Four contract traps, each spelled out because each is a plausible implementation's silent
-    // divergence:
-    //
-    //  · **The argument must be a FRAME.** `0x7a16ea` runs `IsA(FrameTag)` on it, and a Texture or
-    //    Region argument raises `"…Wrong parent object type, expected frame"` (`0x87cb78`). Ours
-    //    raises too — a re-parent that quietly did nothing is the silent-drop class of 1203/1205.
-    //  · **A missing argument is NOT the nil form.** TNONE fails the `== LUA_TNIL` test and falls
-    //    through to `"…Couldn't find region named '%s'"` (`0x87cb48`), so `tex:SetParent()` raises
-    //    while `tex:SetParent(nil)` detaches. That is why this reads a `MultiValue`: mlua cannot
-    //    tell an absent argument from an explicit nil any other way.
-    //  · **Anchors are untouched.** The re-link moves draw-layer/region-list membership only; a
-    //    re-parented Texture still anchors to whatever `SetPoint` named — which is why FuXPFu
-    //    re-points its spark afterwards, and why our anchors (which store the resolved target id)
-    //    need no fixing up at all.
-    //  · **Zero return values**, on every path.
-    //
-    // The mechanism half — full re-link, layer and sub-level preserved, `nil` = orphaned but not
-    // destroyed — is [`crate::widget::WidgetArena::set_region_owner`]'s doc.
-    m.set(
+    // SetParent(frame) lives in the Region table (`0x7a1550`), which Texture and FontString
+    // lookups fall back to (`0x79c650`, `0x79ee50`); `FuBar_FuXPFu.lua:210` calls it on a texture.
+    // A non-frame raises (`0x7a16ea`, `0x87cb78`); no argument raises (`0x87cb48`) where nil
+    // detaches, hence the `MultiValue`. Anchors are untouched, and nothing is returned.
+    set_shared(
+        lua,
+        &m,
+        Side::Region,
         "SetParent",
-        lua.create_function(|lua, args: mlua::MultiValue| {
+        |lua, args: mlua::MultiValue| {
             let mut it = args.into_iter();
             let Some(Value::Table(this)) = it.next() else {
                 return Err(mlua::Error::runtime("SetParent: expected a region"));
@@ -350,8 +252,7 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
             };
             let wrong_type =
                 || mlua::Error::runtime("SetParent(): Wrong parent object type, expected frame");
-            // `_G[name]` before the guard, and **without** `$parent` expansion — the reparent
-            // bindings call `0x76c760` directly (`super::object::NamedTarget`).
+            // `_G[name]` is read before the model borrow, with no `$parent` expansion (`0x76c760`).
             let named = match &parent {
                 Value::String(s) => Some(match s.to_str() {
                     Ok(n) => super::object::prefetch_named_target(lua, n.as_ref(), None),
@@ -362,17 +263,14 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let new_owner = match &parent {
                 Value::Nil => None,
-                // A region/font-object wrapper decodes to an id that is not a frame's (or to no id
-                // at all) — both land on the same "expected frame" the reference raises.
+                // A region or font-object wrapper is no frame: the same "expected frame" raise.
                 Value::Table(t) => Some(
                     decode_id(t)
                         .ok()
                         .and_then(|id| model.id_to_frame.get(&id).copied())
                         .ok_or_else(wrong_type)?,
                 ),
-                // A name resolves through `_G[name]` + the narrow **Frame** tag check
-                // (`[0xcf0c10]`), as every other frame-target argument does — the reference's
-                // `0x76c760`; see `object::NamedTarget`.
+                // A name resolves through `_G[name]` and the Frame tag check (`[0xcf0c10]`).
                 Value::String(_) => {
                     let nt = named.as_ref().expect("a String argument is prefetched");
                     let hit = super::object::resolve_named_target(&model, nt)
@@ -387,19 +285,14 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
                 _ => return Err(wrong_type()),
             };
             if model.arena.set_region_owner(rh, new_owner) {
-                // An un-anchored region draws relative to its owner, and an anchored one resolves
-                // against the owner's rect and effective scale (`layout.rs`'s region sweep) — the
-                // owner is a layout input, so a re-link is a layout change.
+                // The owner supplies the region's scale to layout, so a re-link is a layout change.
                 model.touch_layout();
             }
             Ok(())
-        })?,
+        },
     )?;
 
-    // Region-level visibility — the real VisibleRegion Show/Hide on Textures/FontStrings (the
-    // ref kit hides tab slices, cooldown swipes, money coins…). A hidden region draws nothing;
-    // IsVisible additionally requires the owner frame's effective visibility, mirroring the
-    // frame-side pair.
+    // A hidden region draws nothing; `IsVisible` also needs the owner frame visible.
     m.set(
         "Show",
         lua.create_function(|lua, this: Table| {
@@ -449,52 +342,26 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The three clusters this file was split into (0716's budget). Order is immaterial —
-    // every one of them only writes into the same method table.
+    // In any order: each only adds to the same method table.
     paint::install(lua, &m)?;
     text::install(lua, &m)?;
     layout::install(lua, &m)?;
 
-    // ── The title region's own, narrower table ──────────────────────────────────────────────────
+    // ── The title region's table ─────────────────────────────────────────────────────────────
     //
-    // 1250 §5 recorded this as a named divergence: our region metatable was shared, so a title
-    // region answered `SetTexture`/`Show`/`Hide` where the reference raises `attempt to call
-    // method`. Inert — the kind never draws — but a **superset in PRESENCE**, and 1189 is the
-    // record of what a superset costs when an addon feature-detects.
-    //
-    // Closed by copying exactly the Region map (the 19 names 1244/1245 landed and assert as a set)
-    // out of the full table. It is a copy rather than a second install because the two must never
-    // disagree about what, say, `GetPoint` does — one implementation, two visibilities.
-    //
-    // **The Texture/FontString superset is NOT closed here, deliberately.** They still share one
-    // table, so a Texture answers `SetText` and a FontString answers `SetTexture`. Splitting those
-    // needs the per-table membership facts, and the naive partition is WRONG: `paint.rs` installs
-    // `SetDrawLayer`/`SetVertexColor`/`SetAlpha`/`SetAlphaGradient`, all of which the font carve
-    // says a FontString legitimately has. A wrong split REMOVES verbs addons use, which is worse
-    // than the superset it fixes — so that half waits for the membership read (1238's shape).
+    // Exactly the Region map, copied from the full table so both share one implementation; the
+    // reference's title region has no `Show`, `Hide` or texture methods.
     let title = lua.create_table()?;
     for name in super::REGION_MAP_METHODS {
         let f: Value = m.get(name)?;
         title.set(name, f)?;
     }
-    // ── The two LEAF tables (wow-re `texture-fontstring-method-split.md`) ───────────────────────
+    // ── The leaf tables ──────────────────────────────────────────────────────────────────────
     //
-    // Texture's map is `0x87c128` (22 entries, lookup `0x79c620`), FontString's is `0xcf5400` (32,
-    // lookup `0x79ee20`); both tail-call the Region map and stop there — no third table. Until now
-    // ours was ONE table for both, so a Texture answered `SetText` and a FontString answered
-    // `SetTexture`: a superset in both directions.
-    //
-    // **Partitioned first, then pruned name by name.** The 1244/1245 split only decided which
-    // leaf could SEE each name, because getting a split wrong REMOVES verbs addons use, which is
-    // worse than the superset it fixes. The five that were in NEITHER client map were left in
-    // place as a separate question per name, and all five have since been answered:
-    // `GetStringHeight` (1251), `SetRotation` and `SetPortraitToTexture` (the latter a 1.12
-    // GLOBAL, and it lives there now), and `SetFormattedText` and `SetSize` (2142). Both leaves
-    // are the client's own lists now.
-    //
-    // Copied out of the full table rather than installed twice, so one implementation stands behind
-    // both visibilities — and note the carve's warning that the shared names use the IDENTICAL
-    // `const char*` in the client's two tables, so de-duplicating by name would drop one side.
+    // Texture's map (`0x87c128`, 22 entries, lookup `0x79c620`) and FontString's (`0xcf5400`, 32,
+    // lookup `0x79ee20`) each fall back to the Region map and nothing else. Copied from the full
+    // table; a name both leaves list (one `const char*` in the client, e.g. `GetDrawLayer` at
+    // `0x87c41c`) goes into both.
     for (key, extra) in [
         (REG_TEXTURE_METHODS, &super::TEXTURE_ONLY_METHODS[..]),
         (REG_FONTSTRING_METHODS, &super::FONTSTRING_ONLY_METHODS[..]),
@@ -515,20 +382,12 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
         (REG_FONTSTRING_META, REG_FONTSTRING_METHODS),
     ] {
         let meta = lua.create_table()?;
-        let index = lua.create_function(move |lua, (_this, key): (Table, Value)| {
-            let methods: Table = lua.named_registry_value(methods_key)?;
-            methods.get::<Value>(key)
-        })?;
-        meta.set("__index", index)?;
+        meta.set("__index", lua.named_registry_value::<Table>(methods_key)?)?;
         lua.set_named_registry_value(meta_key, meta)?;
     }
 
     let title_meta = lua.create_table()?;
-    let title_index = lua.create_function(|lua, (_this, key): (Table, Value)| {
-        let methods: Table = lua.named_registry_value(REG_TITLE_METHODS)?;
-        methods.get::<Value>(key)
-    })?;
-    title_meta.set("__index", title_index)?;
+    title_meta.set("__index", title.clone())?;
     lua.set_named_registry_value(REG_TITLE_METHODS, title)?;
     lua.set_named_registry_value(REG_TITLE_META, title_meta)?;
 
@@ -536,13 +395,8 @@ fn install_region_methods(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The layout [`super::layout::Handle`] a region anchors to by default: its **owner frame**'s id
-/// (minted if needed), or [`SCREEN`] if the region has somehow lost its owner.
-/// This region's global name, or `None` when it was declared anonymously.
-///
-/// Scans the region-name registry rather than mirroring the name onto the region: that registry is
-/// the single authority (the widget arena deliberately holds none), and a second copy is one more
-/// thing to drift. Linear in NAMED regions, and every caller is human-rate.
+/// This region's global name, or `None` when anonymous: a scan of the region-name registry, the
+/// one authority, linear in named regions.
 pub(super) fn region_name_of(model: &Model, id: u32) -> Option<String> {
     model
         .region_names
@@ -551,16 +405,9 @@ pub(super) fn region_name_of(model: &Model, id: u32) -> Option<String> {
         .map(|(k, _)| k.clone())
 }
 
-/// Publish a region's global name into the **region-name registry** — the table a sibling's
-/// `SetPoint`/`SetAllPoints` resolves a named `relativeTo` through
-/// ([`super::object::layout_methods`]). First-wins, the same rule frames follow.
-///
-/// `CreateTexture(name)` does this for itself; the paths that *don't* are the typed widgets' own
-/// sub-textures, which are created by a setter (`SetThumbTexture`, `SetColorWheelTexture`, …) and
-/// named afterwards by the XML loader. Without this they land in `_G` and nowhere else, and a
-/// `relativeTo="ColorPickerWheel"` on a sibling silently falls back to the parent frame — which is
-/// exactly how the colour picker's value strip first ended up 224 px to the right of where the
-/// reference puts it, anchored to the window instead of to the wheel.
+/// Publish a region's name into the registry a named `relativeTo` resolves through, first name
+/// winning as for frames. For sub-textures a setter creates and the XML loader names later
+/// (`SetThumbTexture`, `SetColorWheelTexture`); `CreateTexture(name)` publishes its own.
 pub(crate) fn publish_region_name(lua: &Lua, name: &str, region: &Table) {
     let Ok(id) = super::object::decode_id(region) else {
         return;
@@ -569,48 +416,29 @@ pub(crate) fn publish_region_name(lua: &Lua, name: &str, region: &Table) {
     model.region_names.entry(name.to_string()).or_insert(id);
 }
 
-/// The string `GetObjectType()` answers for this region, and the leaf `IsObjectType` matches.
-///
-/// The reference reads a per-class `.data` `const char*` through `vtable[+0x1c]`; ours reads the
-/// arena's [`RegionKind`], which is the same fact stored once. A handle whose region has been
-/// destroyed answers `"Region"` — the base every leaf also matches, so an identity question about
-/// a dead handle degrades to the truthful half rather than naming a leaf it no longer is.
+/// The type `GetObjectType()` answers and `IsObjectType` matches; `"Region"` for a dead handle.
 pub(super) fn region_type_name(model: &Model, rh: RegionHandle) -> &'static str {
     match model.arena.region(rh).map(|r| r.kind) {
         Some(RegionKind::Texture) => "Texture",
         Some(RegionKind::FontString) => "FontString",
-        // The title region's own type name — it is a Region and nothing more (Q6).
+        // A title region is a bare Region (`CreateTitleRegion 0x773910`).
         Some(RegionKind::Title) => "Region",
         None => "Region",
     }
 }
 
-/// Free one region and **every trace of its identity** — the arena slot, its paint, its resolved
-/// rect, its name registration, and the stable id both directions.
-///
-/// Anything that had fetched its wrapper now resolves to a stale-handle error, which is the honest
-/// answer for an object the widget destroyed. That matters because the client really does destroy:
-/// `CSimpleButton::SetFontString 0x778d20` runs the *scalar deleting* destructor on the label it
-/// replaces (`old->vtable[0](1)`, returning the storage to the FontString pool), so a caller
-/// holding the old string is holding a freed object — orphaning it instead would leave a live,
-/// parentless label that still answers every getter, which is a different and quieter bug.
-///
-/// One law, two callers ([`super::simplehtml`]'s block free and the button's label swap); it lives
-/// here because the region side owns region lifetime, and because two hand-written copies of a
-/// five-map teardown is how one of them ends up forgetting a map.
+/// Free a region and every trace of its identity (arena slot, paint, rect, name, id), so a held
+/// wrapper raises as stale; the reference frees too, as `CSimpleButton::SetFontString 0x778d20`
+/// deletes the label it replaces.
 pub(crate) fn free_region(model: &mut Model, rh: RegionHandle) {
     model.region_data.remove(&rh);
     model.region_resolved.remove(&rh);
     if let Some(id) = model.region_to_id.remove(&rh) {
         model.id_to_region.remove(&id);
-        // A NAMED region also holds a slot in the name registry — anonymous ones (every SimpleHTML
-        // block, most labels) do not, which is why the first caller of this law never needed it.
         model.region_names.retain(|_, v| *v != id);
     }
     model.arena.destroy_region(rh);
-    // A death is the archetypal STRUCTURAL change — it takes a node out of the layout roster and
-    // its reverse edges with it, which is exactly what a per-node ledger cannot describe
-    // (decision 1388).
+    // A removed node takes its edges with it: a structural change, so the full touch.
     model.touch_layout();
 }
 
@@ -621,30 +449,12 @@ pub(super) fn region_owner_id(model: &mut Model, rh: RegionHandle) -> u32 {
     }
 }
 
-/// The client's **creation-path implicit anchor** (wow-re `system/ui/scratch/`
-/// `region-implicit-anchor.md`, §5 VERIFIED; decision 1310): a per-region-type post-step the real
-/// engine runs immediately after a region's LoadXML returns (`0x7701c0` texture / `0x771480`
-/// fontstring — the same two fire from the Button state-texture and ButtonText paths, and from Lua
-/// `CreateTexture`/`CreateFontString` only on a template-registry hit). Condition: the region has a
-/// parent AND every one of its nine anchor slots is empty — any anchor from any source suppresses
-/// it. Then:
-///
-/// - a **Texture** gets `SetAllPoints(parent)` — two corner anchors, TOPLEFT→TOPLEFT and
-///   BOTTOMRIGHT→BOTTOMRIGHT at (0,0). Two opposing corners pin all four edges, so an authored
-///   `<Size>` is **structurally unread** (the resolver law) — which is why the reference's
-///   stack-split plate authors a vestigial 256×32 and renders 172×96 (B180).
-/// - a **FontString** gets ONE middle-row `SetPoint` chosen by its live justify word
-///   (`[this+0x120] & 7`: 1 → LEFT→LEFT, 4 → RIGHT→RIGHT, else CENTER→CENTER, offsets (0,0)) —
-///   and its `<Size>` stays live (single anchor + W/H sizes the opposite edges).
-///   [`RegionData::justify`] *is* that word — `SetJustifyH` writes it and a font-object link
-///   merges into it behind the explicit mask — so reading it here is reading `+0x120`.
-/// - a **Title region** gets nothing (verified negative), and a templateless Lua region is never
-///   routed here at all: it stays rect-less and does not render.
-///
-/// These are ordinary anchors once installed: a later same-point `SetPoint` replaces only its own
-/// slot and the other implicit corner survives (verified) — callers that re-apply authored anchors
-/// over a materialized region must `ClearAllPoints` first, exactly as the reference's XML path
-/// avoids the mix by running this step *after* `<Anchors>` load.
+/// The reference's implicit anchor for a region with a parent and no anchors, run after its XML
+/// loads (texture `0x7701c0`, fontstring `0x771480`), and from Lua `CreateTexture` or
+/// `CreateFontString` only on a template hit. A Texture gets `SetAllPoints(parent)`, so an
+/// authored `<Size>` goes unread; a FontString gets one middle-row point picked by its justify
+/// word (`[+0x120]`, our [`RegionData::justify`]) and keeps its size; a title region gets none.
+/// They are ordinary anchors after: re-applying authored ones needs `ClearAllPoints` first.
 pub(crate) fn implicit_creation_anchor(model: &mut Model, rh: RegionHandle) {
     let Some((kind, owner)) = model.arena.region(rh).map(|r| (r.kind, r.owner)) else {
         return;
@@ -671,12 +481,8 @@ pub(crate) fn implicit_creation_anchor(model: &mut Model, rh: RegionHandle) {
     model.touch_layout();
 }
 
-/// The middle-row point a justify word selects — the compare chain the FontString creation
-/// post-step (`0x771480`) and the Button label adopter (`CSimpleButton::SetFontString 0x778d20`)
-/// share: `& 7`, then equality against LEFT (1) and RIGHT (4); every other value — the CENTER bit
-/// and a cleared axis alike — falls to CENTER. What differs between the two callers is only WHOSE
-/// word is read: the post-step reads the string's own (`+0x120`), the adopter reads the button's
-/// normal font's (`+0x390`) — see [`super::button`]'s `adopt_label` (decision 1996).
+/// The middle-row point a justify word selects, as the FontString post-step (`0x771480`) and the
+/// button label adopter (`0x778d20`) both compute it: LEFT for 1, RIGHT for 4, else CENTER.
 pub(crate) fn justify_anchor_point(word: u32) -> crate::layout::Point {
     use crate::layout::Point;
     match word & crate::justify::H_MASK {
@@ -686,10 +492,7 @@ pub(crate) fn justify_anchor_point(word: u32) -> crate::layout::Point {
     }
 }
 
-/// One middle-row anchor `point → the owner's same point, (0,0)`, installed only when the region
-/// has no anchor of its own — the nine-slot scan every implicit-anchor site runs first, so any
-/// anchor from any source suppresses it. [`implicit_creation_anchor`]'s FontString arm is this
-/// with the region's own justify word; the Button adopter is this with the button's.
+/// Anchor `point` to the owner's same point at (0, 0), only when the region has no anchor at all.
 pub(crate) fn anchor_unanchored_at(
     model: &mut Model,
     rh: RegionHandle,
@@ -707,8 +510,7 @@ pub(crate) fn anchor_unanchored_at(
     model.touch_layout();
 }
 
-/// [`implicit_creation_anchor`] behind a wrapper table — the loader-facing form (the loader holds
-/// region wrappers, not handles), same seam as [`apply_font_parts`].
+/// [`implicit_creation_anchor`] for the loader, which holds region wrappers.
 pub(crate) fn implicit_creation_anchor_lua(lua: &Lua, wrapper: &Table) -> mlua::Result<()> {
     let rh = region_handle_of(lua, wrapper)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -716,15 +518,8 @@ pub(crate) fn implicit_creation_anchor_lua(lua: &Lua, wrapper: &Table) -> mlua::
     Ok(())
 }
 
-/// The two things the shared ladder needs off a **region** receiver, read under one short `Model`
-/// borrow that is dropped before the `_G` read (`super::object::anchor_args`'s contract, and the
-/// frame twin's `frame_ladder_context`): the name the reference puts in its error strings, and the
-/// name a leading `$parent` expands to.
-///
-/// A region's `$parent` is its **owner** frame (the region's own `+0x9c`), so the walk starts
-/// there rather than one link higher. Its own name comes back out of `Model::region_names` — the
-/// registry is name→id, and this is the only place that wants the inverse, so it is a scan on the
-/// **error path** rather than a second map kept in step.
+/// The receiver's name for error strings and what a leading `$parent` expands to, the owner frame
+/// (`+0x9c`), read under a borrow dropped before the ladder reads `_G`.
 pub(super) fn region_ladder_context(lua: &Lua, rh: RegionHandle) -> (String, String) {
     let mut model = lua.app_data_mut::<Model>().expect("model");
     let id = model.region_id(rh);
@@ -739,9 +534,7 @@ pub(super) fn region_ladder_context(lua: &Lua, rh: RegionHandle) -> (String, Str
     (who, base)
 }
 
-/// Bit-exact equality for a region's explicit size — the layout gate's own lens
-/// (`InputFingerprint::input` feeds `f32::to_bits`), so a setter's no-op detection and the gate
-/// can never disagree; see [`anchor_bits_eq`].
+/// Bit-exact size equality, the layout gate's own test, so a setter's no-op check agrees with it.
 pub(super) fn size_bits_eq(a: Option<(f32, f32)>, b: Option<(f32, f32)>) -> bool {
     match (a, b) {
         (None, None) => true,
@@ -752,15 +545,12 @@ pub(super) fn size_bits_eq(a: Option<(f32, f32)>, b: Option<(f32, f32)>) -> bool
     }
 }
 
-/// `Region:SetPoint(point [, relativeTo [, relativePoint]] [, x, y])` — the *same* binding as the
-/// frame's (`0x7a2540` is registered once, on `CScriptRegion`), so the argument ladder and every
-/// one of its raises come from [`super::object::anchor_args`]; this side supplies only what the
-/// reference reads off a region — the owner as the layout parent, and
-/// [`super::RegionData::anchors`] as the store.
+/// `Region:SetPoint`, the same binding as the frame's (`0x7a2540`, on `CScriptRegion`): the shared
+/// argument ladder ([`super::object::anchor_args`]), with the owner as layout parent.
 pub(super) fn region_set_point(lua: &Lua, this: &Table, args: &MultiValue) -> mlua::Result<()> {
     let rh = region_handle_of(lua, this)?;
     let (who, base) = region_ladder_context(lua, rh);
-    // The `_G` read inside the ladder runs with no model guard alive — see `region_ladder_context`.
+    // No model borrow is alive across the ladder's `_G` read.
     let p = parse_set_point(lua, args, &who, &base)?;
 
     let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -771,17 +561,14 @@ pub(super) fn region_set_point(lua: &Lua, this: &Table, args: &MultiValue) -> ml
 
     let data = model.region_data.entry(rh).or_default();
     let new = Anchor::new(point, rel_to_id, rel_point, x, y);
-    // Same no-op law as the frame twin (`layout_methods::set_point`): idempotent only when the
-    // bit-identical anchor already holds the tail and no earlier entry carries this point.
+    // A no-op only when the bit-identical anchor is already the tail and no earlier entry has
+    // this point, as for frames.
     let same_at_tail = data.anchors.last().is_some_and(|a| anchor_bits_eq(a, &new))
         && !data.anchors[..data.anchors.len() - 1]
             .iter()
             .any(|a| a.point == point);
     if !same_at_tail {
-        // The frame twin's law (decision 1388): re-pointing the same anchor at the same target is
-        // a VALUE change and names its node; anything that moves the target set is structural.
-        // This is the castbar spark's and every combat-text string's per-frame write.
-        // …and a retarget names its node too (decision 1625) — see the frame twin.
+        // The same targets are a value change on this node; a moved target set is a retarget.
         let structural = anchor_retarget_is_structural(&data.anchors, &new);
         let old_targets: Option<Vec<u32>> =
             structural.then(|| data.anchors.iter().map(|a| a.relative_to).collect());
@@ -802,45 +589,23 @@ pub(super) fn region_set_point(lua: &Lua, this: &Table, args: &MultiValue) -> ml
     Ok(())
 }
 
-/// `Region:GetWidth()`/`GetHeight()` — **the virtual size getters**, per region class.
-///
-/// The Lua bindings are not field reads. `GetWidth 0x7a1e00` ends `ff 52 1c` and
-/// `GetHeight 0x7a2030` ends `ff 52 20` (wow-re `minimap-ping-law.md`): both dispatch through the
-/// receiver's own **geometry vtable** — slots `+0x1c`/`+0x20` — which is the identical call the
-/// rect resolver makes (`0x767579`). So a region's Lua-visible size and the size its rect is built
-/// from are one number BY CONSTRUCTION on the reference, and this function is how they are one
-/// number here (decision 1670; the resolver half is `layout::content_span` +
-/// `layout::FONTSTRING_MIN_SPAN`, and both are read from here).
-///
-/// | class | law |
-/// |---|---|
-/// | plain frame / title region | the flat authored field, `0x768420` / `0x768410`. No content. |
-/// | `CSimpleTexture` | `0x770720` / `0x770790`: authored when **not exactly `0.0`**, else the art's own texel extent, else `0.0`. |
-/// | `CSimpleFontString` | `0x772930` / `0x772a60`: authored when not `0.0`, else the cached measure — and then **floored at one FrameXML unit**. |
-///
-/// Two details of the FontString row are worth spelling out, because both were wrong here before
-/// and neither is guessable from the name:
-///
-/// * **The authored value WINS.** The old code preferred the measure and fell back to the
-///   authored size;
-///   the reference's `jp` at `0x77294a` skips the measure entirely when the authored value is
-///   non-zero. Per axis, not per region — `<Size x="290" y="0"/>` takes 290 from the author and
-///   the height from the text.
-/// * **The width is the NATURAL, unwrapped extent** — `0x772890`'s `[fs+0xfc]`, measured with no
-///   wrap constraint, the very cell `GetStringWidth 0x79e510` returns. The *height* is the other
-///   cell, `0x7729b0`'s `[fs+0x100]`, which IS the wrapped line count × line height. So a wrapped
-///   string reports a width wider than its own box and a height taller than one line, and that
-///   asymmetry is the client's (wow-re `fontstring-overflow.md` "The measurement echo").
+/// `Region:GetWidth()`/`GetHeight()` (`0x7a1e00`, `0x7a2030`): the geometry-vtable call the rect
+/// resolver also makes (`0x767579`), so the Lua size is the rect's. Per axis, a Texture answers
+/// its authored size unless exactly 0, else its texel extent (`0x770720`, `0x770790`). A
+/// FontString answers its authored size unless 0 (`0x77294a`), else its measure, either floored
+/// at one unit (`0x772930`, `0x772a60`); the width is unwrapped, as `GetStringWidth` gives it
+/// (`0x772890`, `0x79e510`), the height wrapped (`0x7729b0`). A title region answers its field
+/// (`0x768420`, `0x768410`).
 pub(super) fn measured_wh(lua: &Lua, this: &Table) -> mlua::Result<(f32, f32)> {
     let rh = region_handle_of(lua, this)?;
-    // Same-tick measure when a host font engine is installed — see `region::text`'s `natural_w`.
-    // A no-op for a Texture (not a FontString) and for an already-current measure.
+    // Measures this tick when a host font engine is installed; a no-op for a Texture or a
+    // current measure.
     super::measure::ensure_measured(lua, rh);
     let model = lua.app_data_ref::<Model>().expect("model");
     Ok(virtual_span(&model, rh))
 }
 
-/// [`measured_wh`]'s body, on a borrowed model — the form the engine's own callers want.
+/// [`measured_wh`]'s body on a borrowed model, for the engine's own callers.
 pub(super) fn virtual_span(model: &Model, rh: RegionHandle) -> (f32, f32) {
     let Some(d) = model.region_data.get(&rh) else {
         return (0.0, 0.0);
@@ -848,12 +613,9 @@ pub(super) fn virtual_span(model: &Model, rh: RegionHandle) -> (f32, f32) {
     let (aw, ah) = d.size.unwrap_or((0.0, 0.0));
     match model.arena.region(rh).map(|r| r.kind) {
         Some(RegionKind::FontString) => {
-            // The key carries the owner's effective_scale ([`RegionData::measure_key`]) — the same
-            // recipe the request loop stamps, or every read under a SetScale'd owner reports
-            // stale. Unlike the layout sweep, the getter DOES key-check: the sweep holds a
-            // last-known box so a line whose text just changed does not flicker for the frame the
-            // re-measure is in flight, and a getter that did the same would hand a caller the
-            // previous string's metric (the whisper header's latched inset).
+            // The measure key carries the owner's effective scale, as the request loop stamps it.
+            // Unlike the layout sweep, which keeps the last box, the getter refuses a stale
+            // measure rather than answer with the previous string's.
             let scale = model
                 .arena
                 .region(rh)
@@ -861,29 +623,9 @@ pub(super) fn virtual_span(model: &Model, rh: RegionHandle) -> (f32, f32) {
                 .map(|f| f.effective_scale)
                 .unwrap_or(1.0);
             let m = d.measured.filter(|m| m.key == d.measure_key(scale));
-            // **The floor applies to a KNOWN extent, and a pending measure is not one.** On the
-            // reference every extent is known — the getter measures inline — so `0.0` never comes
-            // back and the question never arises. Ours can be *waiting*, which is not a size but
-            // the absence of an answer. **Where that state still lives is a VM with no measurer
-            // installed** (`script::measure`'s is optional): the app seats one at the load edge
-            // (2028), so no in-app caller observes a pending measure any more, and the three
-            // convergence drivers this used to name went with their windows —
-            // `BenillaGossipRow_Resize` (gossip, 1751), our tab fit (1993/2028) and our quest
-            // panel (1944). Flooring a pending measure to one unit hands a measurer-less caller a
-            // number where it should read "not yet"; the surviving `OnUpdate` fits
-            // (`OptionsScroll_Fit`, `BenillaScroll_ResizeChild`) guard on RECTS, not on this.
-            //
-            // A genuinely EMPTY string is a different thing: its extent is known and it is zero, so
-            // it floors — which is the case the reference's floor exists for. The layout sweep
-            // floors unconditionally because a rect has to exist on every frame and nothing reads
-            // it as a sentinel (decision 1664); the difference between the two is exactly this
-            // pending state, which the reference does not have.
-            //
-            // "Known" is the same test the layout sweep applies: **empty text needs no
-            // round-trip** — nothing ever measures an empty string, and its extent is known
-            // without asking. So `""` is a known zero (⇒ one unit) while a pending measure on real
-            // text is no answer at all (⇒ `0.0`), and the two are only indistinguishable if you
-            // look at `measured` alone.
+            // The floor applies to a known extent. Empty text is a known zero and floors; a pending
+            // measure, possible only in a VM with no measurer installed, answers 0, where the
+            // reference measures inline and always knows.
             let floor = super::layout::FONTSTRING_MIN_SPAN;
             let known = |from_measure: fn(&crate::script::types::MeasuredText) -> f32| {
                 if d.text.as_deref().is_none_or(str::is_empty) {
@@ -921,8 +663,7 @@ pub(super) fn virtual_span(model: &Model, rh: RegionHandle) -> (f32, f32) {
                 },
             )
         }
-        // A title region is a bare `CScriptRegion` — geometry vtable `0x81c9c8`, whose `+0x1c`
-        // is the unoverridden `0x768420`. The flat field, like a frame.
+        // A title region: the flat field, like a frame (vtable `0x81c9c8`, `+0x1c` = `0x768420`).
         _ => (aw, ah),
     }
 }
diff --git a/crates/benilla-ui/src/script/region/layout.rs b/crates/benilla-ui/src/script/region/layout.rs
index f4e92332..9f27a217 100644
--- a/crates/benilla-ui/src/script/region/layout.rs
+++ b/crates/benilla-ui/src/script/region/layout.rs
@@ -1,26 +1,28 @@
-//! Region method-table cluster: **layout** — size, anchors and the resolved-rect readers.
-//! Split out of `region.rs` at the 0716 file-size budget.
+//! The Region layout methods: size, anchors and the resolved-rect readers.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
 use crate::layout::{Anchor, Point};
 use crate::script::object::anchor_args::{parse_set_all_points, resolve_rel_target};
 use crate::script::object::{anchor_bits_eq, frame_wrapper, point_name};
+use crate::script::region_map::{set_shared, Side};
 use crate::script::{Model, SCREEN};
 
-/// Resolve `self` (a region wrapper) to its live [`RegionHandle`].
 use super::{
     measured_wh, region_handle_of, region_ladder_context, region_owner_id, region_set_point,
     size_bits_eq,
 };
 
-/// Populate `m`'s layout methods (see the module doc).
+/// Install the layout methods into `m`.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // Region explicit size — fills the axes the region's anchors don't pin (unread under an
-    // implicit SetAllPoints's two corners; decision 1310).
-    m.set(
+    // The explicit size fills the axes the anchors do not pin, so SetAllPoints's two corners
+    // leave it unread.
+    set_shared(
+        lua,
+        m,
+        Side::Region,
         "SetWidth",
-        lua.create_function(|lua, (this, w): (Table, f32)| {
+        |lua, (this, w): (Table, f32)| {
             let rh = region_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let d = model.region_data.entry(rh).or_default();
@@ -28,19 +30,20 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let changed = !size_bits_eq(d.size, new);
             d.size = new;
             if changed {
-                // A size write moves no edge and no roster membership (decision 1388) — and on
-                // a FontString the width is the WRAP width, a measure-key input, so it names
-                // itself on the measure ledger too.
+                // No edge or roster change; the width, as wrap width, keys a FontString's measure.
                 model.touch_layout_region(rh);
                 model.touch_measure(rh);
             }
             Ok(())
-        })?,
+        },
     )?;
 
-    m.set(
+    set_shared(
+        lua,
+        m,
+        Side::Region,
         "SetHeight",
-        lua.create_function(|lua, (this, h): (Table, f32)| {
+        |lua, (this, h): (Table, f32)| {
             let rh = region_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let d = model.region_data.entry(rh).or_default();
@@ -48,80 +51,67 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let changed = !size_bits_eq(d.size, new);
             d.size = new;
             if changed {
-                // A size write moves no edge and no roster membership (decision 1388) — and on
-                // a FontString the width is the WRAP width, a measure-key input, so it names
-                // itself on the measure ledger too.
+                // No edge or roster change; the width, as wrap width, keys a FontString's measure.
                 model.touch_layout_region(rh);
                 model.touch_measure(rh);
             }
             Ok(())
-        })?,
+        },
     )?;
 
-    // **No `SetSize`** — the frame twin's note in `object/layout_methods.rs` applies here
-    // unchanged: an Era verb 1.12's Region map does not carry (decision 2142).
+    // No `SetSize`: not a 1.12 verb.
 
-    m.set(
-        "GetWidth",
-        lua.create_function(|lua, this: Table| Ok(measured_wh(lua, &this)?.0))?,
-    )?;
+    set_shared(lua, m, Side::Region, "GetWidth", |lua, this: Table| {
+        Ok(measured_wh(lua, &this)?.0)
+    })?;
 
-    m.set(
-        "GetHeight",
-        lua.create_function(|lua, this: Table| Ok(measured_wh(lua, &this)?.1))?,
-    )?;
+    set_shared(lua, m, Side::Region, "GetHeight", |lua, this: Table| {
+        Ok(measured_wh(lua, &this)?.1)
+    })?;
 
-    // GetLeft/GetRight/GetTop/GetBottom — the region's RESOLVED edges in its OWNER's units (y-up;
-    // screen ÷ the owner's effective scale, the frame twin's law in `object/layout_methods.rs` —
-    // a region shares its owner's scale, and a texture inside the scaled world map answered
-    // screen units here while its owner answered local ones, decision 1985). Every drawable
-    // region carries anchors (authored or the creation-path implicit anchor, decision 1310) and
-    // reads its resolved rect; a templateless Lua region nobody anchored never resolves → nil,
-    // same as pre-resolve.
+    // GetLeft/GetRight/GetTop/GetBottom: the resolved edges in the owner's units (y up, screen
+    // over the owner's effective scale, which a region shares); nil for a region never resolved.
     for (name, pick) in [
         ("GetLeft", 0u8),
         ("GetRight", 1u8),
         ("GetTop", 2u8),
         ("GetBottom", 3u8),
     ] {
-        m.set(
-            name,
-            lua.create_function(move |lua, this: Table| {
-                let rh = region_handle_of(lua, &this)?;
-                let model = lua.app_data_ref::<Model>().expect("model");
-                let inv = 1.0 / owner_scale(&model, rh);
-                Ok(model.region_resolved.get(&rh).map(|r| {
-                    inv * match pick {
-                        0 => r.left,
-                        1 => r.right,
-                        2 => r.top,
-                        _ => r.bottom,
-                    }
-                }))
-            })?,
-        )?;
+        set_shared(lua, m, Side::Region, name, move |lua, this: Table| {
+            let rh = region_handle_of(lua, &this)?;
+            let model = lua.app_data_ref::<Model>().expect("model");
+            let inv = 1.0 / owner_scale(&model, rh);
+            Ok(model.region_resolved.get(&rh).map(|r| {
+                inv * match pick {
+                    0 => r.left,
+                    1 => r.right,
+                    2 => r.top,
+                    _ => r.bottom,
+                }
+            }))
+        })?;
     }
 
-    // Region anchors: SetPoint/ClearAllPoints/SetAllPoints mirror the frame versions
-    // ([`super::object`]) but write [`super::RegionData::anchors`]. An unspecified `relativeTo`
-    // defaults to the **owner frame**; a named one may be a frame or a sibling region (the real
-    // XML anchors regions to sibling regions everywhere — merchant label plate → `$parentSlot`).
-    m.set(
+    // SetPoint, ClearAllPoints and SetAllPoints write the region's anchors. `relativeTo` defaults
+    // to the owner frame, and a named one may be a frame or a sibling region, as stock XML uses.
+    set_shared(
+        lua,
+        m,
+        Side::Region,
         "SetPoint",
-        lua.create_function(|lua, (this, rest): (Table, MultiValue)| {
-            region_set_point(lua, &this, &rest)
-        })?,
+        |lua, (this, rest): (Table, MultiValue)| region_set_point(lua, &this, &rest),
     )?;
 
-    m.set(
+    set_shared(
+        lua,
+        m,
+        Side::Region,
         "ClearAllPoints",
-        lua.create_function(|lua, this: Table| {
+        |lua, this: Table| {
             let rh = region_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let d = model.region_data.entry(rh).or_default();
-            // Names its node, the frame twin's rule and for the frame twin's reason (decision
-            // 2114): clearing every anchor is a retarget onto an EMPTY target list, so the cached
-            // graph's edges are unlinked rather than the whole graph re-derived.
+            // A retarget onto no targets: the cached graph unlinks the edges, no re-derive.
             let old: Option<Vec<u32>> =
                 (!d.anchors.is_empty()).then(|| d.anchors.iter().map(|a| a.relative_to).collect());
             d.anchors.clear();
@@ -129,14 +119,17 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 model.touch_layout_retarget_region(rh, &old, &[]);
             }
             Ok(())
-        })?,
+        },
     )?;
 
-    m.set(
+    set_shared(
+        lua,
+        m,
+        Side::Region,
         "SetAllPoints",
-        lua.create_function(|lua, (this, rest): (Table, MultiValue)| {
+        |lua, (this, rest): (Table, MultiValue)| {
             let rh = region_handle_of(lua, &this)?;
-            // `who`/`$parent` first, then the `_G` read, then the guard — `region_ladder_context`.
+            // `who` and `$parent` first, then the `_G` read, then the guard.
             let (who, base) = region_ladder_context(lua, rh);
             let target = parse_set_all_points(lua, rest.front(), &base);
             let mut model = lua.app_data_mut::<Model>().expect("model");
@@ -160,80 +153,56 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 model.touch_layout();
             }
             Ok(())
-        })?,
+        },
     )?;
 
-    // ── The rest of the Region map `0xcf54b4` (wow-re `font-object-lua-surface.md`) ──────────────
+    // ── the rest of the Region map (`0xcf54b4`) ─────────────────────────────────────────────────
     //
-    // These four landed together because the MAP is the unit, not the name. `SetParent` shipped
-    // alone when one addon line named it, and its own getter stayed missing for months — which is
-    // how `TheoryCraft\TheoryCraftUI.lua:720` (`buttontext:GetParent()`, a FontString) died every
-    // session, and how the per-kind census came to read `115 GetParent (missing on Texture,
-    // FontString)`. The set is closed and byte-verified, so it is asserted as a set in
-    // `tests/reference_surface.rs` rather than grown a name at a time.
+    // The map is a closed set, `script::REGION_MAP_METHODS`, and a test asserts it whole.
 
-    // GetParent() → the OWNER frame's wrapper. A region always has one (`region_owner_id` falls
-    // back to the owner for every unresolved case), so unlike the frame twin this never answers nil.
-    m.set(
-        "GetParent",
-        lua.create_function(|lua, this: Table| {
-            let rh = region_handle_of(lua, &this)?;
-            let owner = {
-                let mut model = lua.app_data_mut::<Model>().expect("model");
-                region_owner_id(&mut model, rh)
-            };
-            frame_wrapper(lua, owner)
-        })?,
-    )?;
+    // GetParent: the owner frame, which a region always has, so never nil.
+    set_shared(lua, m, Side::Region, "GetParent", |lua, this: Table| {
+        let rh = region_handle_of(lua, &this)?;
+        let owner = {
+            let mut model = lua.app_data_mut::<Model>().expect("model");
+            region_owner_id(&mut model, rh)
+        };
+        frame_wrapper(lua, owner)
+    })?;
 
-    // GetCenter() → the resolved rect's midpoint, or a nil PAIR before the first resolve — the same
-    // contract, and the same source, as the GetLeft/GetRight/GetTop/GetBottom readers above.
-    //
-    // **Deliberately unscaled, where the frame twin divides by GetEffectiveScale.** The region edge
-    // readers report raw resolved units; scaling only the centre would make `GetCenter()` disagree
-    // with `(GetLeft() + GetRight()) / 2` on any scaled subtree — a contradiction inside one method
-    // table is worse than a missing division, and regions have no scale of their own to divide by.
-    m.set(
-        "GetCenter",
-        lua.create_function(|lua, this: Table| {
-            let rh = region_handle_of(lua, &this)?;
-            let model = lua.app_data_ref::<Model>().expect("model");
-            let inv = 1.0 / owner_scale(&model, rh);
-            Ok(match model.region_resolved.get(&rh) {
-                Some(r) => (
-                    Value::Number(f64::from(inv * (r.left + r.right) * 0.5)),
-                    Value::Number(f64::from(inv * (r.bottom + r.top) * 0.5)),
-                ),
-                None => (Value::Nil, Value::Nil),
-            })
-        })?,
-    )?;
+    // GetCenter: the resolved rect's midpoint in the owner's units, as the edge readers answer, or
+    // two nils before the first resolve.
+    set_shared(lua, m, Side::Region, "GetCenter", |lua, this: Table| {
+        let rh = region_handle_of(lua, &this)?;
+        let model = lua.app_data_ref::<Model>().expect("model");
+        let inv = 1.0 / owner_scale(&model, rh);
+        Ok(match model.region_resolved.get(&rh) {
+            Some(r) => (
+                Value::Number(f64::from(inv * (r.left + r.right) * 0.5)),
+                Value::Number(f64::from(inv * (r.bottom + r.top) * 0.5)),
+            ),
+            None => (Value::Nil, Value::Nil),
+        })
+    })?;
 
-    // GetNumPoints() → how many anchors this region carries. Absent on our FRAMES too, which is the
-    // same drift one table up; this side is what the corpus named.
-    m.set(
-        "GetNumPoints",
-        lua.create_function(|lua, this: Table| {
-            let rh = region_handle_of(lua, &this)?;
-            let model = lua.app_data_ref::<Model>().expect("model");
-            Ok(model
-                .region_data
-                .get(&rh)
-                .map_or(0, |d| d.anchors.len() as i64))
-        })?,
-    )?;
+    set_shared(lua, m, Side::Region, "GetNumPoints", |lua, this: Table| {
+        let rh = region_handle_of(lua, &this)?;
+        let model = lua.app_data_ref::<Model>().expect("model");
+        Ok(model
+            .region_data
+            .get(&rh)
+            .map_or(0, |d| d.anchors.len() as i64))
+    })?;
 
-    // GetPoint([n]) → point, relativeTo, relativePoint, xOfs, yOfs — the n-th (1-based, default
-    // first) anchor, mirroring the frame twin including its out-of-range answer (five nils).
-    //
-    // **The relativeTo dispatch is the part a frame-shaped copy gets wrong.** Region anchors live in
-    // ONE id space with frames and may target a sibling REGION — the real XML does it everywhere
-    // (`region.rs`'s `resolve_target`: frames first, then the region-name registry). So the id is
-    // matched against both tables and answered with the matching wrapper kind; handing back a frame
-    // wrapper for a region id would be a working-looking handle onto the wrong object.
-    m.set(
+    // GetPoint([n]): the n-th anchor (1-based, default 1) as point, relativeTo, relativePoint, x
+    // and y, or five nils. Frames and regions share one id space and a region may anchor to a
+    // sibling region, so relativeTo is answered with the matching wrapper kind.
+    set_shared(
+        lua,
+        m,
+        Side::Region,
         "GetPoint",
-        lua.create_function(|lua, (this, n): (Table, Option<i64>)| {
+        |lua, (this, n): (Table, Option<i64>)| {
             let rh = region_handle_of(lua, &this)?;
             let anchor = {
                 let model = lua.app_data_ref::<Model>().expect("model");
@@ -267,13 +236,13 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 Value::Number(f64::from(a.x_off)),
                 Value::Number(f64::from(a.y_off)),
             ))
-        })?,
+        },
     )?;
     Ok(())
 }
 
-/// The region's owner frame's effective scale (1 for an orphan) — the divisor that turns a
-/// resolved screen rect into the owner's units, the space every region getter answers in.
+/// The owner frame's effective scale (1 for an orphan), the divisor from a resolved screen rect to
+/// the owner's units every region getter answers in.
 fn owner_scale(model: &Model, rh: crate::widget::RegionHandle) -> f32 {
     model
         .arena
diff --git a/crates/benilla-ui/src/script/region/paint.rs b/crates/benilla-ui/src/script/region/paint.rs
index e61a09d3..6c6691a2 100644
--- a/crates/benilla-ui/src/script/region/paint.rs
+++ b/crates/benilla-ui/src/script/region/paint.rs
@@ -1,20 +1,17 @@
-//! Region method-table cluster: **paint** — what a Texture shows and how it is tinted,
-//! blended, cropped and layered. Split out of `region.rs` at the 0716 file-size budget.
+//! The region paint methods: what a Texture shows and how it is tinted, blended, cropped and
+//! layered.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
 use crate::script::object::{as_f32, draw_layer_from_str, draw_layer_name};
 use crate::script::{BlendMode, Model, TexCoords};
 
-/// Resolve `self` (a region wrapper) to its live [`RegionHandle`].
 use super::region_handle_of;
 
-/// Populate `m`'s paint methods (see the module doc).
+/// Install the paint methods into `m`.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // SetAlpha/GetAlpha — the region's own alpha, distinct from the owner frame's. The ref kit reads
-    // it back to ramp a texture (CastingBarFrame's completion flash does
-    // `CastingBarFlash:SetAlpha(GetAlpha() + CASTING_BAR_FLASH_STEP)`), so the getter must return the
-    // region's value, never the frame's. Draw law + the open question: [`RegionData::alpha`].
+    // SetAlpha/GetAlpha: the region's own alpha, not the owner frame's; stock
+    // `CastingBarFrame.lua:133` reads it back to ramp its flash. `RegionData::alpha` has the draw.
     m.set(
         "SetAlpha",
         lua.create_function(|lua, (this, alpha): (Table, f32)| {
@@ -38,29 +35,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // **KNOWN DIVERGENCE, byte-pinned and deliberately not closed here (decision 1782).** An
-    // ABSENT alpha argument is 1.0 below; in the reference it is *the alpha already on the region*.
-    // `0x79abd0` reads the current colour back (`0x79ac81` -> `0x77f8c0`), packs the caller's rgb
-    // against an `a` default of 1.0 (`0x79ad43`), and then asks a SECOND time whether argument 5
-    // was present — when it was not, it copies byte 3 of the read-back colour over the packed
-    // alpha (`0x79adfe`/`0x79ae0a`) before the store. So `SetVertexColor(r, g, b)` on 1.12.1 is
-    // `SetVertexColor(r, g, b, currentAlpha)`, and a three-argument call CANNOT restore opacity.
-    // wow-re `system/ui/scratch/button-state-texture-path-setter.md` §7.
-    //
-    // Why it still says 1.0: the fix is one line, but its blast radius is every three-argument
-    // call in FrameXML and in the addon corpus, and it only bites where a region already carries
-    // alpha < 1 — where it would surface as art going permanently translucent, which is a LOOK and
-    // therefore the director's call, not a quiet correction to fold into an unrelated slice. The
-    // known live case is the action bar's grid ring: stock `ActionButton_ShowGrid` passes the
-    // fourth argument explicitly (`SetVertexColor(1.0, 1.0, 1.0, 0.5)`), so closing this cannot
-    // silently change that file.
-    //
-    // **Shape C on r, g, b** (`Texture:SetVertexColor `0x79abd0``, `2=C 3=C 4=C 5=B`, wow-re
-    // `numeric-arg-coercion-law.md`): a bare `lua_tonumber` with no `lua_isnumber` gate, so a nil,
-    // a table or a string is **0.0** and the call never raises. Taking them as `f32` made mlua's
-    // converter the gate instead — the 2176 class — and the stock
-    // `QuestLogFrame.lua:337` idiom hands three nils (`titleButton.r/g/b` are only assigned in
-    // `QuestLog_Update`) on any path that selects a quest-log entry before the window has painted.
+    // SetVertexColor (`0x79abd0`) reads r, g and b with a bare `lua_tonumber`, so nil or a table is
+    // 0 and never raises; stock `QuestLogFrame.lua:337` can pass three nils. A missing alpha is 1
+    // here; the reference keeps the region's current alpha (read back at `0x79ac81`, copied over
+    // at `0x79adfe`/`0x79ae0a`), so there a three-argument call cannot restore opacity.
     m.set(
         "SetVertexColor",
         lua.create_function(
@@ -70,17 +48,14 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 let mut model = lua.app_data_mut::<Model>().expect("model");
                 let d = model.region_data.entry(rh).or_default();
                 d.vertex_color = Some([r, g, b, a.unwrap_or(1.0)]);
-                // The same slot `SetTextColor` writes on a FontString, so it is the same explicit
-                // colour set as far as font-object inheritance is concerned.
+                // The slot `SetTextColor` writes on a FontString, so it overrides the font object.
                 d.font_explicit.color = true;
                 Ok(())
             },
         )?,
     )?;
 
-    // GetVertexColor — the setter's own pair, a real 5875 binding (`0x79aa50`, wow-re
-    // `system/ui/ledger.tsv`; it sits directly above `SetVertexColor 0x79abd0` in the same region
-    // method family). Never set = the untinted white every region draws at by default.
+    // GetVertexColor (`0x79aa50`): white when never set.
     m.set(
         "GetVertexColor",
         lua.create_function(|lua, this: Table| {
@@ -95,19 +70,10 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetGradientAlpha(orientation, r1,g1,b1,a1, r2,g2,b2,a2) and its alpha-less twin
-    // SetGradient(orientation, r1,g1,b1, r2,g2,b2) — the two-stop linear gradient the client
-    // generates into the same `+0xcc` texture slot the colour form of SetTexture fills.
-    //
-    // These were missing, and they were the single wall in front of the corpus's largest family:
-    // `FuBar\FuBar_Panel.lua:144` calls SetGradientAlpha while building the bar, so all 20 FuBar
-    // plugins died there — after the debugstack/chunk-name fix got them that far.
-    //
-    // The orientation token is matched case-insensitively and anything that is not "VERTICAL" is
-    // horizontal, which is the client's own leniency and matters because addons spell it both ways.
-    // The gradient is stored WHOLE (see `RegionData::gradient`); the paint folds it to its midpoint
-    // because a quad carries one tint today. That approximation is visible and is recorded at the
-    // field, not hidden here.
+    // SetGradientAlpha(orientation, r1, g1, b1, a1, r2, g2, b2, a2) and SetGradient without the
+    // alphas: a two-stop gradient the client generates into the texture slot (`+0xcc`); here it is
+    // stored whole and drawn as its midpoint. Any orientation but "VERTICAL", in any case, is
+    // horizontal.
     for (name, with_alpha) in [("SetGradientAlpha", true), ("SetGradient", false)] {
         m.set(
             name,
@@ -119,7 +85,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 };
                 let orientation = match it.next() {
                     Some(Value::String(s)) => s.to_str()?.to_string(),
-                    // A missing/!string orientation is horizontal, like any non-"VERTICAL" token.
+                    // A missing or non-string orientation is horizontal.
                     _ => String::new(),
                 };
                 let n = if with_alpha { 8 } else { 6 };
@@ -148,101 +114,50 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
 
     m.set(
         "SetTexture",
-        // The trailing three are `Value`, not `Option<f32>`, and that is a fidelity fix rather than
-        // laxity. The path form reads ONE argument (`0x770200`); only the colour form
-        // (`0x770360`) reads up to four. A C function takes what it wants off the Lua stack and
-        // ignores the rest, so `SetTexture(path, true)` is fine on the real client — and typing
-        // these as `Option<f32>` made us raise on it, `bad argument #3: error converting Lua
-        // boolean to f32`, in a call the client accepts silently.
-        //
-        // Found by `_LazyPig/LazyPigMenu.lua:182`
-        // (`texture_title:SetTexture("Interface\DialogFrame\UI-DialogBox-Header", true)`), which
-        // reached us only once the survey started seating the addon registry — the whole point of
-        // that instrument fix. The stray `true` is meaningless in 1.12 and the addon author
-        // presumably meant a later client's second parameter; either way the client shrugs.
-        // The RETURN is part of the contract (wow-re `widget-api-batch-benilla.md` Q1, VERIFIED):
-        // the path form answers **1 | nil — nil meaning the file did not load** — and the colour
-        // and clear forms answer 1. Atlas is the load-bearing caller: `Atlas_Refresh` does
-        // `local builtIn = AtlasMap:SetTexture("…\Images\Maps\"..zoneID)` and walks its plugin
-        // fallback chain on nil, so a binding that returns nothing draws no map at all whatever
-        // the file resolver does. The load verdict comes from the host's [`Model::texture_probe`]
-        // (existence across patch chain + loose addon folder — the same candidate walk the
-        // renderer resolves with); a VM with no probe installed has no backend, so its path form
-        // stays nil, which is both literally true and what every engine-less test always observed.
+        // The path form reads one argument (`0x770200`), the colour form (`0x770360`) up to four,
+        // and extras such as `SetTexture(path, true)` are ignored. `SetTexture` (`0x79bb40`)
+        // answers 1, or nil when the path form's file does not load, as the host's
+        // `Model::texture_probe` judges; with no probe the path form answers nil.
         lua.create_function(
             |lua, (this, arg, g, b, a): (Table, Value, Value, Value, Value)| {
                 let rh = region_handle_of(lua, &this)?;
-                // Scoped, so the model borrow is provably gone before the layout touch below —
-                // the path arm hands it back mid-way (to call the host probe without holding a
-                // mutable borrow across a host callback) and the others do not.
+                // Scoped so the model borrow ends before the layout touch; the path arm drops it
+                // mid-way to call the host probe.
                 let (loaded, derived) = {
                     let mut model = lua.app_data_mut::<Model>().expect("model");
-                    // A plain SetTexture makes the region ordinary again — drop any portrait circular mask
-                    // and any live-unit-portrait binding.
+                    // SetTexture drops any portrait mask and live-unit binding.
                     let data = model.region_data.entry(rh).or_default();
                     data.circular = false;
                     data.portrait_unit = None;
-                    // **`SetTexture` CLEARS the desaturation** (wow-re `texture-desaturate-law.md` §2.3,
-                    // VERIFIED): `+0x128` is a `CGxShader*`, and `CSimpleTexture::SetTexture`
-                    // (`0x770200`) writes it from its 4th stack arg, for which the Lua binding
-                    // (`0x79bb40`) pushes slot 0 — permanently NULL — on both of its legs. A
-                    // re-implementation that keeps a desaturate boolean independent of the texture
-                    // handle diverges on every `icon:SetDesaturated(1)` followed by `icon:SetTexture(t)`.
-                    //
-                    // Scoped exactly as the binary scopes it:
-                    //  · the **same path** is inert — `0x770225` returns before ever reaching the write,
-                    //    so a repaint that re-sets the icon it already shows keeps its grey;
-                    //  · `nil`/`""` DO clear — the `test esi,esi` leg falls through to the write;
-                    //  · the **colour form** does NOT — that is `0x770360`, which is not among the four
-                    //    writers of the field.
+                    // SetTexture clears the desaturation: `0x770200` writes the shader slot
+                    // (`+0x128`) from an argument the binding (`0x79bb40`) always passes NULL. The
+                    // same path returns first (`0x770225`) and keeps it, nil or "" clear it, and
+                    // the colour form (`0x770360`) never writes it.
                     let same_path = matches!((&arg, &data.texture),
                     (Value::String(s), Some(cur)) if s.to_str().is_ok_and(|s| *s == **cur));
                     let colour_form = matches!(&arg, Value::Number(_) | Value::Integer(_));
                     if !same_path && !colour_form {
                         data.desaturated = false;
                     }
-                    // Does this region's rect come from its ART? An axis authored `0` takes its span
-                    // from the content (decision 1349, `script::layout::content_span`), so on that
-                    // shape — and only there — swapping the texture MOVES the region and the resolve
-                    // has to hear about it. Read before the match, which writes the art and never the
-                    // size.
-                    //
-                    // **An ANCHOR-LESS region is not that shape**, whatever its size: with no
-                    // pinned edge and no center there is nothing for a span to be added to
-                    // (`combine_edge` needs one), so every edge stays unset — which is why the
-                    // resolve sweep skips such regions outright. Painting one is a paint, not a
-                    // layout change, and saying otherwise would re-open the change gate on every
-                    // `CreateTexture(…):SetTexture(…)` in the UI (decisions 0740/1385/1388).
+                    // An anchored region with an axis sized 0 takes that span from its art, so a
+                    // new texture moves it; an anchorless region never resolves, so for it this
+                    // is only a paint.
                     let derived = !data.anchors.is_empty()
                         && data.size.is_none_or(|(w, h)| w == 0.0 || h == 0.0);
-                    // Both forms write the SAME `+0xcc` texture slot — the path form loads a file
-                    // there (`0x770200`), the colour form generates an 8×8 solid into it
-                    // (`0x770360`) — so each clears the other. NEITHER touches the vertex colour at
-                    // `+0xb8`: a tint outlives the art it was tinting.
+                    // Both forms write the one texture slot (`+0xcc`), a file or an 8×8 solid, so
+                    // each clears the other; neither touches the vertex colour (`+0xb8`), so a
+                    // tint outlives its art.
                     let loaded = match &arg {
-                        // SetTexture("") clears, same as SetTexture(nil) — the ref lua blanks state
-                        // art with the empty string (QuestLogFrame.lua:165-166). The return for ""
-                        // is read as the path form's failure (nothing loads from an empty name);
-                        // INFERRED — no corpus caller reads it.
+                        // "" clears, as nil does (stock `QuestLogFrame.lua:166`), and answers nil
+                        // like a failed load; the reference's answer for "" is untraced.
                         Value::String(s) if s.to_str()?.is_empty() => {
                             data.texture = None;
                             data.fill = None;
                             false
                         }
-                        // **Ask the probe BEFORE writing the slot.** The reference's load-FAILURE
-                        // arm (`cmp [ebp-4],2; jl` at `0x770288` → `0x77028e`–`0x7702b2`) releases
-                        // the handle it just built and returns 0 **leaving `+0xcc` and `+0x128` as
-                        // they were** — "the widget keeps whatever texture it already had"
-                        // (wow-re `texture-service-name-resolution.md` §161-169). Storing the path
-                        // first and letting the verdict drive only the *return value* meant a
-                        // mistyped or not-yet-shipped path ERASED the art it failed to replace,
-                        // and did it silently: `GetTexture()` echoed the missing path and the quad
-                        // was dropped, so the region went blank with nothing said (decision 2124).
-                        //
-                        // The store and the return ask deliberately different questions. A VM with
-                        // **no probe installed** has no backend to ask, so it stores — that is
-                        // every engine-less test's world, and the module head already states that
-                        // such a VM's path form "stays nil", which is the return, not the slot.
+                        // Ask the probe before writing: on a failed load the reference returns 0
+                        // and keeps the texture it had (`0x770288`, `0x77028e`-`0x7702b2`). With
+                        // no probe the path is stored, though the answer is nil.
                         Value::String(s) => {
                             let path = s.to_str()?.to_string();
                             drop(model);
@@ -262,9 +177,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             }
                             resolvable && had_probe
                         }
-                        // The colour form, and the ONLY branch that looks at the trailing three. A
-                        // non-numeric there takes the same default a missing one does, which is what
-                        // reading off a C stack does: `lua_tonumber` on a non-number yields 0.
+                        // The colour form, the only one to read the trailing three; a non-number
+                        // there takes the default a missing one does.
                         Value::Number(_) | Value::Integer(_) => {
                             let chan = |v: &Value, dflt: f32| match v {
                                 Value::Number(_) | Value::Integer(_) => as_f32(v),
@@ -280,8 +194,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             data.texture = None;
                             true
                         }
-                        // SetTexture(nil) clears (the live API's blank-the-region form); a cleared
-                        // texture region draws nothing. Returns 1 (Q1's `SetTexture(nil) / ()` row).
+                        // nil clears, so the region draws nothing, and answers 1 (`0x79bb40`).
                         Value::Nil => {
                             data.texture = None;
                             data.fill = None;
@@ -291,10 +204,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     };
                     (loaded, derived)
                 };
-                // Named precisely, and only on the content-derived shape: an ordinary sized icon's
-                // rect cannot move here, and touching the layout on every icon repaint would
-                // re-open the resolve's change gate every frame for a rect nobody moved
-                // (decisions 0740/1385/1388).
+                // Only the art-sized shape can move; touching the layout on every repaint would
+                // reopen the resolve's change gate each frame.
                 if derived {
                     lua.app_data_mut::<Model>()
                         .expect("model")
@@ -309,41 +220,12 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // SetDesaturated(flag) -> shaderSupported — Texture only (`0x79c1e0`, wow-re ledger; the
-    // reference's own `ItemButtonTemplate.lua:69` is `local shaderSupported =
-    // icon:SetDesaturated(desaturated)`).
-    //
-    // **The RETURN is the whole design, and it is the half a plausible implementation drops.**
-    // 1.12 ran on cards that could not do the shader, so the verb reports whether it took effect
-    // and FrameXML falls back by hand:
-    //
-    //     if ( not desaturated ) then r,g,b = 1,1,1
-    //     elseif ( not r or not shaderSupported ) then r,g,b = 0.5,0.5,0.5 end
-    //     icon:SetVertexColor(r, g, b)
-    //
-    // The renderer now greys the texel (decision 1327 — `ui_quad.wgsl`'s luminance fold), so we
-    // answer **1 — supported**, and the branch above takes its shader arm: the icon goes greyscale
-    // AND wears the caller's own dim tint. Until 1327 this answered nil, which is a real 1.12
-    // card's answer and was the honest one while nothing greyed — but it costs the *look*: a 0.65
-    // grey multiply on colourful art is a dimmer, still-colourful icon, which is precisely what
-    // B162 reported against the talent tree.
-    //
-    // Why it matters far past one verb: **98 of the 109 addons that draw and then raise on being
-    // used, raise here** — `FuBar_Panel.lua:43`'s right-click reaches Dewdrop's `AddLine`
-    // (`Dewdrop-2.0.lua:2172`), which calls `button.arrow:SetDesaturated(true)` unguarded. A
-    // static scan costed this at 61 addons and it was declined; the use-probe costed it at 98 the
-    // moment anyone right-clicks.
-    //
-    // **The argument's truth table is not `if flag then`** (wow-re `texture-desaturate-law.md` §1.1,
-    // VERIFIED — `0x6f1c10(L, 2, default=1)` dispatched through the jump table at `0x6f1ce8`). Two
-    // of its arms are the opposite of the obvious reading, and both are reachable:
-    //  · **no argument at all is ON**, not off — `LUA_TNONE` takes the `ja` default arm, so
-    //    `tex:SetDesaturated()` greys. This is why the flag arrives as a `MultiValue`: mlua hands a
-    //    missing `Value` parameter through as `Nil`, which is the one arm that means OFF.
-    //  · **a number truncating to 0 is OFF** (`0x6f3620`+`0x40a2b0`), so `SetDesaturated(0)` clears.
-    //  · a table/function/userdata is ON (same default arm as absent).
-    // The string arm (`0x6f1c51`, comparing against `0x871460`/`0x853758`) is NOT modelled — no
-    // corpus caller passes one, and the comparands were not read; a string takes the ON arm here.
+    // SetDesaturated(flag) (`0x79c1e0`), Texture only, answers shaderSupported, which stock
+    // `ItemButtonTemplate.lua:69` reads to fall back to a grey tint; the renderer greys the texel,
+    // so this answers 1. The flag is `GetBoolOrDefault` (`0x6f1c10`, default 1, jump table
+    // `0x6f1ce8`): no argument is on, hence the `MultiValue`, nil is off, a number truncating to 0
+    // is off (`0x6f3620`, `0x40a2b0`), and a table, function or userdata is on. Every string is on
+    // here; the reference's string arm (`0x6f1c51`, against `0x871460` and `0x853758`) is not.
     m.set(
         "SetDesaturated",
         lua.create_function(|lua, args: MultiValue| {
@@ -363,29 +245,14 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let rh = region_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             model.region_data.entry(rh).or_default().desaturated = on;
-            // 1, not true: the reference's `shaderSupported` is a 1|nil C answer (byte-verified —
-            // `0x6f3810 lua_pushnumber(L, 1.0)`, never `false`, never zero values) and callers
-            // write `not shaderSupported`.
+            // 1, not true: the reference pushes the number 1 (`0x6f3810`).
             Ok(Value::Number(1.0))
         })?,
     )?;
 
-    // GetTexture() — Texture only (`0x79ba70`), verified in wow-re's widget-method batch
-    // (`system/ui/scratch/widget-api-batch-benilla.md`). Three contract details are each the kind a
-    // plausible implementation gets silently wrong, so each is spelled out:
-    //
-    //  · **Exactly ONE return value**, never a multi-return.
-    //  · **The colour form returns the literal string `"Solid Texture"`** (`0x835708`), NOT nil.
-    //    `SetTexture(r,g,b)` synthesizes an 8x8 solid, and the getter reports that name — so an
-    //    addon's `if not tex then` passes straight through on a colour-filled region. Returning nil
-    //    here would look tidier and would be wrong in the one direction callers test for.
-    //  · **The path is stripped at the LAST `.`** (`0x79baf0`): the loader appends `.blp`/`.tga` to
-    //    what was set and the getter strips an extension back off. Taken verbatim rather than
-    //    "strip only a real extension" — a directory containing a dot is mangled by the real client
-    //    too, and this surface is a transcription, not an improvement.
-    //
-    // Four corpus addons: `AtlasQuest.lua:228` (`AQATLASMAP = AtlasMap:GetTexture()`) and
-    // `FuBarPlugin-2.0.lua:343` (`return self.iconFrame:GetTexture()`), each reached by two addons.
+    // GetTexture (`0x79ba70`), Texture only, answers one value: "Solid Texture" for the colour
+    // form (`0x835708`), not nil, and a path cut at its last `.` (`0x79baf0`), even a dot in a
+    // directory name, as the client cuts it.
     m.set(
         "GetTexture",
         lua.create_function(|lua, this: Table| {
@@ -404,9 +271,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetAlphaGradient(start, length) — the per-character write-on reveal (CSimpleFontString;
-    // the quest-description machinery, ref QuestFrame.lua:548/558). Returns whether `start` is
-    // still inside the text (chars) — the ref's OnUpdate loop advances until this goes false.
+    // SetAlphaGradient(start, length), a FontString's write-on reveal: answers whether `start` is
+    // still inside the text in chars, and stock `QuestFrame.lua:558` advances until it is not.
     m.set(
         "SetAlphaGradient",
         lua.create_function(|lua, (this, start, length): (Table, f32, f32)| {
@@ -419,14 +285,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetBlendMode("DISABLE"|"ALPHAKEY"|"BLEND"|"ADD"|"MOD") — `0x79a950`, the shared alphaMode
-    // enum `0x811aa8`. Only ADD changes draw behavior in v1 (DISABLE/ALPHAKEY/MOD are accepted as
-    // straight alpha, a stated gap — see [`BlendMode`]); an unrecognised name leaves the mode
-    // alone, which is what the enum-table lookup does with a string it cannot match.
-    //
-    // The mode is STORED as the mode. It used to collapse to `additive = (mode == "ADD")` on the
-    // way in, which is everything the renderer needs and strictly less than `GetBlendMode` has to
-    // answer — a texture set to `"MOD"` would have read back as `"BLEND"`.
+    // SetBlendMode (`0x79a950`, the alphaMode enum `0x811aa8`) stores the mode as given; an
+    // unknown name leaves it alone, as the enum lookup does. Only ADD draws differently here, the
+    // others as straight alpha.
     m.set(
         "SetBlendMode",
         lua.create_function(|lua, (this, mode): (Table, String)| {
@@ -438,18 +299,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GetBlendMode() — ONE string, the enum's own spelling (`0x79a890`, table `0x87c128`, argc 1,
-    // arity 1, kinds `(string?)`). A Texture nothing has called the setter on answers `"BLEND"`,
-    // the CSimpleTexture ctor's `[+0xd0] = 2` (`0x76fc64`).
-    //
-    // **This one was answering nil, and nil is not an error here — it is a wrong picture.**
-    // `ShaguTweaks/mods/dark-ui-elements.lua:169` reads
-    // `elseif region.GetBlendMode and region:GetBlendMode() == "ADD" then` while recolouring a
-    // Blizzard frame's children: the `and` guard means a missing method never raised, it just took
-    // the other branch, so every additive texture in the frame got the dark recolour the reference
-    // leaves alone. The kinds column's `string?` is the reference's own nil leg (the name pointer
-    // can be NULL for a mode outside the table); the five modes are all this engine can hold, so
-    // nothing here reaches it.
+    // GetBlendMode (`0x79a890`, table `0x87c128`): one string, the enum's spelling, "BLEND" when
+    // never set (the ctor's `[+0xd0] = 2`, `0x76fc64`). The reference's nil, for a mode outside
+    // its table, cannot arise from the five modes here.
     m.set(
         "GetBlendMode",
         lua.create_function(|lua, this: Table| {
@@ -463,30 +315,16 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetTexCoordModifiesRect(flag) / GetTexCoordModifiesRect() — `0x79c080` / `0x79c120`, table
-    // `0x87c128`. The setter writes the reference's `[texture+0x124]` and is its only writer; the
-    // getter answers `1`/`nil` (kinds `(nil) | (number)`, the predicate law — decision 2118 — not a
-    // Lua boolean).
-    //
-    // **The flag's GEOMETRY effect is not wired, and that is stated rather than implied.** In the
-    // reference the flag gates a rect-recompute leg (`ui.md:4619`, `0x770462`): with it set, a
-    // `SetTexCoord` re-derives the region's own rect from the UV quad instead of leaving the rect
-    // where the anchors put it and resampling inside it. Wiring that means the region resolve in
-    // `region::layout` reading this flag and taking the rect from `RegionData::tex_coords` — a
-    // resolve-order change. Nothing in the stock UI or in either addon corpus calls the SETTER, so
-    // there is no measured case to build it against; what has a caller is the GETTER —
-    // `pfUI/modules/thirdparty-tbc.lua:319` does a bare `if icon:GetTexCoordModifiesRect() then` on
-    // a Texture to choose between two `SetTexCoord` rectangles, and against this VM that raised.
-    // So: the flag is stored, answered truthfully, and read by nothing. See
-    // [`RegionData::tex_coord_modifies_rect`].
+    // SetTexCoordModifiesRect/GetTexCoordModifiesRect (`0x79c080`/`0x79c120`, table `0x87c128`):
+    // the setter is the only writer of `[texture+0x124]`, the getter answers 1 or nil. Stored, not
+    // applied: there a set flag makes `SetTexCoord` re-derive the rect from the UV quad
+    // (`0x770462`).
     m.set(
         "SetTexCoordModifiesRect",
         lua.create_function(|lua, (this, arg): (Table, Value)| {
             let rh = region_handle_of(lua, &this)?;
-            // The reference's shared flag-argument truth table (`0x6f1c10(L, 2, default)`), whose
-            // DEFAULT byte for this binding is unread — no corpus site calls the setter at all, so
-            // the no-argument leg is doubly unreachable and `false` is the conservative pick rather
-            // than a claim about `0x79c080`.
+            // `GetBoolOrDefault` (`0x6f1c10`) with default 1 (`0x79c105`), but a missing argument
+            // arrives here as nil and reads false, where the reference sets the flag.
             let on = crate::script::binding_abi::bool_or_default(Some(&arg), false);
             let mut model = lua.app_data_mut::<Model>().expect("model");
             model
@@ -528,17 +366,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetDrawLayer() — the setter's pair, present on BOTH region leaves in the client (Texture
-    // `0x79a6c0`, FontString `0x79c660`, each its own copy — read off the method-table pair bytes).
-    //
-    // This module's own note used to end "GetDrawLayer is in the client's pair and absent here;
-    // absent is absent" — accurate, and a gap rather than a decision. pfUI's `GetNoNameObject`
-    // (api/api.lua:1342) reads it off every child while reskinning a Blizzard frame, and died
-    // there; that is the measurement (1719).
-    //
-    // Returns the layer NAME alone. The sub-level we store beside it is not a second return here:
-    // 1.12's pair is layer-only, and `SetDrawLayer`'s optional sub-level argument above is already
-    // marked as this engine's extension point.
+    // GetDrawLayer (Texture `0x79a6c0`, FontString `0x79c660`): the layer name alone, since
+    // 1.12's pair is layer-only; the sub-level `SetDrawLayer` accepts is not 1.12's.
     m.set(
         "GetDrawLayer",
         lua.create_function(|lua, this: Table| {
@@ -552,49 +381,30 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `SetRotation` WAS here, on the Texture leaf, and is GONE. 1.12 registers the name once, in
-    // the **PlayerModel** table `0x84f1fc` (`0x505f00`, argc 2 — the paper doll's rotate arrows),
-    // which we already answer through `modelframe`; it is in neither region map, and the carve
-    // above lists it among the five names that are in NEITHER (`texture-fontstring-method-split.md`).
-    // Ours was a later-era Texture verb shipped early for the world-map player arrow's stand-in
-    // rotation — and that arrow has since become a real Model frame driven by `ModelState::facing`
-    // (`script::worldmap_arrow`), so the verb's own reason went with it.
-    //
-    // Removal is safe by census, not by assumption: every `SetRotation` in this repo, in
-    // `assets/ui`, in the stock FrameXML/GlueXML and in both addon corpora has a MODEL receiver —
-    // `pfUI/api/ui-widgets.lua:580`'s `EnableClickRotate` hooks a modelframe's OnUpdate, and
-    // `CustomNameplates/options.lua:308` is `optionsFrame.preview.model:SetRotation(0.61)`. Not one
-    // texture receiver anywhere.
-    //
-    // `RegionData::rotation` and `QuadContent::Texture::rotation` now have no writer left. They are
-    // deliberately NOT pruned in the same change: that plumbing runs into the app's quad emit and
-    // its removal is a wider prune with its own review, not a tail on a method-surface fix.
+    // No Texture `SetRotation`: 1.12 registers it only on PlayerModel (`0x505f00`, table
+    // `0x84f1fc`), in neither region map (`0x87c128`, `0xcf5400`).
 
-    // SetTexCoord(left, right, top, bottom) — the 4-edge form (XML `<TexCoords>`): a UV sub-rect in
-    // 0..1 texture space (top-left origin) the Texture region samples, slicing quadrant/atlas art
-    // (decision 0084). SetTexCoord(ULx,ULy, LLx,LLy, URx,URy, LRx,LRy) — the 8-arg affine form: an
-    // arbitrary UV quad (rotation/shear — the reference's `DrawRouteLine` route lines), stored per
-    // corner in the renderer's screen winding.
+    // SetTexCoord(left, right, top, bottom), XML `<TexCoords>`: a UV sub-rect in 0..1, origin top
+    // left. SetTexCoord(ULx, ULy, LLx, LLy, URx, URy, LRx, LRy): any UV quad, as stock
+    // `TaxiFrame.lua:223` draws route lines, stored per corner in screen winding.
     m.set(
         "SetTexCoord",
-        // Every coordinate is **shape C** (`Texture:SetTexCoord 0x79beb0`, all positions C,
-        // wow-re `numeric-arg-coercion-law.md`): bare `lua_tonumber`, nil/table/string → 0.0. Only
-        // the ARITY raises (`0x79bf5d dec eax ; cmp eax,4 ; je ; cmp eax,8 ; je`), which is the
-        // match below. `Variadic<f32>` made mlua the per-coordinate gate; it is not one.
+        // Each coordinate is a bare `lua_tonumber` (`0x79beb0`), so nil or a table is 0; only the
+        // count is gated, 4 or 8 (`0x79bf5d`).
         lua.create_function(|lua, (this, args): (Table, mlua::Variadic<Value>)| {
             let rest: Vec<f32> = args.iter().map(as_f32).collect();
             let rh = region_handle_of(lua, &this)?;
             let coords = match rest.len() {
                 4 => Some(TexCoords::Rect([rest[0], rest[1], rest[2], rest[3]])),
-                // The live arg order is UL, LL, UR, LR (corner pairs); [`TexCoords::Corners`]
-                // stores screen order [TL, TR, BR, BL].
+                // The arguments come UL, LL, UR, LR; `TexCoords::Corners` stores TL, TR, BR, BL.
                 8 => Some(TexCoords::Corners([
                     [rest[0], rest[1]], // UL → TL
                     [rest[4], rest[5]], // UR → TR
                     [rest[6], rest[7]], // LR → BR
                     [rest[2], rest[3]], // LL → BL
                 ])),
-                // No args resets to the full texture (the live API's clear form).
+                // No arguments resets to the full texture, which is not 1.12's: its gate takes 4
+                // or 8.
                 0 => None,
                 n => {
                     return Err(mlua::Error::runtime(format!(
@@ -612,29 +422,21 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTexCoord() → left, right, top, bottom (the 4-edge form; full texture if never set; an
-    // affine mapping reports its bounding edges).
+    // GetTexCoord: the four corners, the full texture when never set.
     m.set(
         "GetTexCoord",
         lua.create_function(|lua, this: Table| {
             let rh = region_handle_of(lua, &this)?;
             let model = lua.app_data_ref::<Model>().expect("model");
-            // EIGHT values — a 4-iteration loop of 2 pushes, `mov eax,8`. There is no 4-value
-            // getter in this API at all: the 4-argument `(minX, maxX, minY, maxY)` min/max rect is
-            // **setter-only**, and returning it here was a shape that exists nowhere in the client.
-            // Order is `SetTexCoord`'s own usage string (`0x87c538`):
-            // `ULx, ULy, LLx, LLy, URx, URy, LRx, LRy`. Decision 1840.
-            //
-            // `GetTexCoord` has zero call sites in 1.12 FrameXML, so nothing on the chain could
-            // ever have caught this — only the binary could.
+            // Eight values in the order of `SetTexCoord`'s usage string (`0x87c538`): ULx, ULy,
+            // LLx, LLy, URx, URy, LRx, LRy. The four-edge form is setter-only.
             let corners = model
                 .region_data
                 .get(&rh)
                 .and_then(|d| d.tex_coords)
                 .map_or([[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]], |tc| {
                     match tc {
-                        // Stored per corner in SCREEN order `[TL, TR, BR, BL]`; Lua wants
-                        // UL, LL, UR, LR.
+                        // Stored as TL, TR, BR, BL; Lua wants UL, LL, UR, LR.
                         crate::script::types::TexCoords::Corners(c) => [c[0], c[3], c[1], c[2]],
                         crate::script::types::TexCoords::Rect(_) => {
                             let [l, r, t, b] = tc.edges();
@@ -658,26 +460,21 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
 }
 
 impl crate::script::UiScript {
-    /// Install the host's texture-path oracle — the resolver behind the path form of
-    /// `SetTexture`'s **1 | nil** return ([`Model::texture_probe`]). The host hands in existence
-    /// over its real stores (patch chain + loose addon folder); a VM that never gets one keeps
-    /// answering nil for every path, the engine-less truth.
+    /// Install the host's texture-path check behind the path form of `SetTexture`'s 1-or-nil
+    /// answer; without one every path answers nil.
     pub fn set_texture_probe(&mut self, probe: crate::script::TextureProbe) {
         self.model_mut().texture_probe = Some(probe);
     }
 
-    /// Install the host's font-path oracle — the resolver behind `SetFont`'s **1 | nil** return
-    /// ([`Model::font_probe`], decision 2103). The host hands in load-ability over its real stores
-    /// (patch chain + the one AddOns folder); a VM that never gets one keeps answering 1 for every
-    /// non-empty path, because it has no font store a load could fail against.
+    /// Install the host's font-path check behind `SetFont`'s 1-or-nil answer; without one every
+    /// non-empty path answers 1.
     pub fn set_font_probe(&mut self, probe: crate::script::FontProbe) {
         self.model_mut().font_probe = Some(probe);
     }
 
-    /// Install the host's texture **texel-size** oracle — what lets a region with an authored size
-    /// of `0` on an axis take that span from its art, as the client's virtual size getters do
-    /// ([`Model::texture_size_probe`], decision 1349 / wow-re `region-size-fallback.md` §2). A VM
-    /// that never gets one leaves such a region exactly where it was.
+    /// Install the host's texel-size check, which lets an axis sized 0 take its span from the art
+    /// as `CSimpleTexture::GetWidth` (`0x770720`) falls back to the texels; without one such a
+    /// region stays where it was.
     pub fn set_texture_size_probe(&mut self, probe: crate::script::TextureSizeProbe) {
         self.model_mut().texture_size_probe = Some(probe);
     }
diff --git a/crates/benilla-ui/src/script/region/text.rs b/crates/benilla-ui/src/script/region/text.rs
index 97f3ffa5..0fea2769 100644
--- a/crates/benilla-ui/src/script/region/text.rs
+++ b/crates/benilla-ui/src/script/region/text.rs
@@ -1,85 +1,39 @@
-//! Region method-table cluster: **text** — what a `FontString` carries that other text-bearing
-//! widgets do not. Split out of `region.rs` at the 0716 file-size budget.
-//!
-//! **This file is now the FontString-only half.** The ten names it used to hand-write a second copy
-//! of — `Set/GetFontObject`, `Set/GetFont`, `Set/GetTextColor`, `Set/GetShadowColor`,
-//! `Set/GetShadowOffset` — are not FontString-specific at all: in the binary each is a thin
-//! type-guard shim tail-calling one shared implementation, so they come from
-//! [`crate::script::font_block`] via one `install` at the bottom of this file, exactly as the
-//! EditBox's table gets them. The justify law likewise lives once in [`crate::justify`].
-//!
-//! What legitimately stays here is the surface a FontString alone has: the string itself
-//! (`SetText`/`GetText`), the measured extents, `Set/GetJustifyH`/`V`, `SetNonSpaceWrap`/
-//! `CanNonSpaceWrap`, and `SetTextHeight`.
-//!
-//! The per-property override a region has over its inherited font object is unaffected — that is
-//! the severance mask (`FontExplicit`), which the shared block writes the same way this file did.
+//! The FontString-only methods: the string, its measured width, justification, non-space wrap and
+//! text height. The font block it shares with EditBox comes from [`crate::script::font_block`].
 
 use mlua::{Lua, Table, Value};
 
 use crate::justify;
 use crate::script::Model;
 
-/// Resolve `self` (a region wrapper) to its live [`RegionHandle`].
 use super::region_handle_of;
 
-/// Populate `m`'s text methods (see the module doc).
+/// Install the FontString methods into `m`.
 pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
     m.set(
         "SetText",
         lua.create_function(|lua, (this, text): (Table, Option<mlua::Value>)| {
-            // `text_arg`, not `Option<String>`: a Lua string is bytes and a sliced one need not be
-            // valid UTF-8 (decision 2138 — this raise took the whole handler down).
+            // `text_arg`, since a Lua string is bytes and a slice of one need not be valid UTF-8.
             let text = crate::script::binding_abi::text_arg(lua, text)?;
             let rh = region_handle_of(lua, &this)?;
             let mut model = lua.app_data_mut::<Model>().expect("model");
             let data = model.region_data.entry(rh).or_default();
             data.text = text;
-            // Fresh text draws whole — an armed write-on gradient belongs to the old string.
+            // Fresh text draws whole: an armed write-on gradient belongs to the old string.
             data.alpha_gradient = None;
-            // SetText is the measure lane's canonical SILENT write (it must not touch the
-            // layout — the extent hasn't moved yet), so it names itself on the measure ledger.
+            // SetText must not touch the layout, since the extent has not moved yet; it names
+            // itself on the measure ledger.
             model.touch_measure(rh);
             Ok(())
         })?,
     )?;
 
-    // **No `SetFormattedText`.** A later-expansion name: absent from the client's 32-entry
-    // FontString map, from the stock 1.12 chain, and from both addon corpora (2142's census). The
-    // era spelling is `SetText(format(fmt, ...))`, and `format` here is already the
-    // positional-aware one ([`crate::strings`]), so `%N$s` behaves at the call site the same way
-    // it behaved inside this shim.
+    // No `SetFormattedText`: not a 1.12 verb; 1.12 writes `SetText(format(fmt, ...))`.
 
-    // GetText — **an EMPTY string comes back as `nil`, and that substitution is the getter's own**
-    // (`FontString:GetText 0x79d690`, wow-re
-    // `system/ui/scratch/fontstring-text-cell-and-gettext-contract.md`, §5 five-worker round):
-    //
-    // ```text
-    // 79d72f  mov  eax,[eax+0xf0]        ; the text cell
-    // 79d735  test eax,eax
-    // 79d739  je   0x79d740              ; NULL      -> substitute
-    // 79d73b  cmp  byte ptr [eax],0x0    ; the FIRST-BYTE test
-    // 79d73e  jne  0x79d742              ; non-empty -> keep
-    // 79d740  xor  eax,eax               ; EMPTY     -> NULL
-    // 79d746  call 0x6f3890              ; pushstring; NULL -> pushnil
-    // ```
-    //
-    // So `FontString:GetText` **cannot return `""`**. Not the setter's doing: `SetText 0x771d80`
-    // never writes NULL to `+0xf0` on any leg — NULL and `""` share one leg that truncates the
-    // buffer in place (`0x771e7e mov byte ptr [eax],0x0`, the pointer surviving) — so the cell
-    // really does hold a non-NULL empty string and this getter is what collapses it.
-    //
-    // The law is **per binding, not per family**, and the two neighbours differ:
-    // `Button:GetText 0x780e10` carries the same substitution (`0x780ec5`, three nil conditions —
-    // see `button.rs`), while `EditBox:GetText 0x7985c0` carries **none** (`0x79867b` reads
-    // `[edit+0x32c]` straight through), which is what stock `MailFrame.lua`'s
-    // `GetText() == ""`/`strlen(GetText())` is written against. Do not hoist this.
-    //
-    // What it costs to get wrong (decision 2110): the stock world map blanks
-    // `WorldMapFrameAreaDescription` with `SetText("")` on every POI hover, and Cartographer 2.02
-    // reads `if WorldMapFrameAreaDescription:GetText() then` as "this POI has a status line" —
-    // answering `""` there put the zone's level range on the description's own line under a
-    // whitened label and left it on screen forever.
+    // GetText answers nil for "" (`0x79d690`, its first-byte test at `0x79d73b`), though `SetText`
+    // (`0x771d80`) keeps a non-NULL empty buffer (`0x771e7e`). The rule is per binding, not per
+    // family: `Button:GetText` (`0x780e10`, `0x780ec5`) does the same, `EditBox:GetText`
+    // (`0x7985c0`, `0x79867b`) does not, and stock `MailFrame.lua:521` compares that one with "".
     m.set(
         "GetText",
         lua.create_function(|lua, this: Table| {
@@ -99,41 +53,15 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetStringWidth (FontString): the host-measured text extent from the measure
-    //
-    // **There is no `GetStringHeight` beside it, and that asymmetry is the client's.** 1.12 has no
-    // such method on any table — byte-verified absent in every encoding, with `GetStringWidth`
-    // itself as the positive control — and Blizzard's own FrameXML calls it zero times. Ours was a
-    // byte-identical duplicate of `GetHeight`, which is what the reference uses for this
-    // (`0x7a2030` falls through to the same cached measurement), so it was pruned rather than
-    // reimplemented (1251).
-    // round-trip ([`super::UiScript::set_measured_text`]) — the client asks its font engine for the
-    // laid-out string's metrics exactly here (`fontstring.md`), and the tooltip's auto-size sums
-    // these to fit its lines. `0` until the string has been measured (a frame's latency; converges).
-    // The stored measure only counts while its key matches the CURRENT text/font/wrap
-    // ([`RegionData::measure_key`]): after a SetText the old string's width is not this string's
-    // metric — serving it is how the whisper header's `GetWidth()` latched the edit-box insets on
-    // the previous header's width. A poll-until-nonzero caller (the chat header machine) now
-    // converges on the RIGHT measure instead of settling on a stale one.
-    // `GetWidth`/`GetHeight` are the neighbouring law and NOT this one ([`super::virtual_span`]):
-    // they take the authored size first and the measure only on an axis authored `0` — and on that
-    // axis the width they return is *this* number, because the reference reads both getters out of
-    // the one cell `[fs+0xfc]` (`0x772890` is `0x79e510`'s callee). So the two agree exactly where
-    // the reference makes them agree, and differ exactly where a width was declared.
-    // GetStringWidth is the **natural, unwrapped** extent — never the declared box, and never the
-    // wrapped one (wow-re `fontstring-overflow.md`, "The measurement echo": the reference's getter
-    // re-measures the raw text with NO wrap constraint). Unlike `GetWidth` below it deliberately
-    // does NOT fall back to a declared `SetWidth`: that width is the very thing a caller
-    // asks this to be independent of. A kit that sizes a box from this number and then sets a width
-    // on the string — which is what the reference's own `PanelTemplates_TabResize` does — would
-    // otherwise read its own output back as its next input and never settle (decision 0997, the
-    // macro window's character tab changing width every frame). `0` until measured, as ever.
+    // GetStringWidth (`0x79e510`): the natural, unwrapped width of the current text, 0 until
+    // measured. Never the declared width, which `PanelTemplates_TabResize` sets from this; on an
+    // axis sized 0, `GetWidth` reads the same cell (`[fs+0xfc]`, `0x772890`). 1.12 has no
+    // `GetStringHeight`; `GetHeight` (`0x7a2030`) serves.
     fn natural_w(lua: &Lua, this: &Table) -> mlua::Result<f32> {
         let rh = region_handle_of(lua, this)?;
-        // Measure NOW if a host font engine is installed — the reference answers this getter from
-        // its font engine inline (`0x79e510` → `0x772890`), and a same-tick `SetText` →
-        // `GetStringWidth` is the corpus's own idiom (`Bagnon_Forever/database/ui.lua:58-59`).
-        // Without an engine this is a no-op and the number below stays 0 until the round-trip.
+        // Measure now when a host font engine is installed, as the reference measures inline, so
+        // `SetText` then `GetStringWidth` works in one tick; without one it is 0 until the host
+        // answers.
         crate::script::measure::ensure_measured(lua, rh);
         let model = lua.app_data_ref::<Model>().expect("model");
         let Some(d) = model.region_data.get(&rh) else {
@@ -155,10 +83,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| natural_w(lua, &this))?,
     )?;
 
-    // SetJustifyH("LEFT"|"CENTER"|"RIGHT") — a FontString's horizontal justification (XML
-    // `justifyH`). The token table, the whole-string match, the raise on a miss and the cross-axis
-    // clear are all [`crate::justify`]'s, shared with the `<Font>` object's identical pair
-    // so the two cannot drift apart again.
+    // SetJustifyH (XML `justifyH`): the parse, the raise on a miss and the cross-axis clear are
+    // `crate::justify`'s, shared with the `<Font>` object.
     m.set(
         "SetJustifyH",
         lua.create_function(|lua, (this, j): (Table, String)| {
@@ -171,20 +97,19 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let d = model.region_data.entry(rh).or_default();
             match parsed {
                 justify::Set::To(jh) => d.justify.set_h(jh),
-                // A cross-axis token erases the axis. `GetJustifyH()` then answers "UNKNOWN"
-                // while the glyphs draw centred — `0x44d420`'s pre-set `1`.
+                // A cross-axis token erases the axis: `GetJustifyH()` answers "UNKNOWN" while the
+                // glyphs draw centred (`0x44d420` presets 1).
                 justify::Set::Clears => d.justify.clear_h(),
                 justify::Set::NoMatch => unreachable!("returned above"),
             }
-            // Severance is UNCONDITIONAL on a successful parse — the FontString's own setter
-            // `0x79e6b0` stores the per-axis mask `+0x124` at `0x79e780`, *before* the `je`, so
-            // the erasing path severs too. Only a failed parse escapes, and that raised already.
+            // Every successful parse overrides the font object, the erasing one too: `0x79e6b0`
+            // sets the per-axis mask (`+0x124`) at `0x79e780`, before the branch.
             d.font_explicit.justify_h = true;
             Ok(())
         })?,
     )?;
 
-    // SetJustifyV("TOP"|"MIDDLE"|"BOTTOM") — a FontString's vertical justification (XML `justifyV`).
+    // SetJustifyV (XML `justifyV`), as SetJustifyH.
     m.set(
         "SetJustifyV",
         lua.create_function(|lua, (this, j): (Table, String)| {
@@ -197,7 +122,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
             let d = model.region_data.entry(rh).or_default();
             match parsed {
                 justify::Set::To(jv) => d.justify.set_v(jv),
-                // 13 corpus sites reach this arm: `SetJustifyV("CENTER")` meaning "middle".
+                // Addons reach this arm with `SetJustifyV("CENTER")`, meaning middle.
                 justify::Set::Clears => d.justify.clear_v(),
                 justify::Set::NoMatch => unreachable!("returned above"),
             }
@@ -206,13 +131,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetJustifyH()/GetJustifyV() → **1 string**. Real entries on the reference's FontString table
-    // (`0x79e5f0` / `0x79e7f0`, the FontString column of wow-re's two-column accessor table) that
-    // this side had simply never grown: a FontString could set its justification and not read it
-    // back, while the `<Font>` object — the same law, transcribed separately — could do both.
-    //
-    // An untouched FontString answers CENTER/MIDDLE, which is `RegionData`'s default *and* the
-    // client's ctor default `0x212` (`CENTER | MIDDLE | 0x200`) read through each axis mask.
+    // GetJustifyH/GetJustifyV (`0x79e5f0`/`0x79e7f0`): one string; CENTER and MIDDLE when
+    // untouched, the ctor's `0x212` read through each axis mask.
     fn justify_of(lua: &Lua, this: &Table) -> mlua::Result<justify::Justify> {
         let rh = region_handle_of(lua, this)?;
         let model = lua.app_data_ref::<Model>().expect("model");
@@ -231,14 +151,8 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         lua.create_function(|lua, this: Table| Ok(justify_of(lua, &this)?.name_v()))?,
     )?;
 
-    // SetNonSpaceWrap(enable) / CanNonSpaceWrap() — FontString only (`0x79e9f0` / `0x79ead0`).
-    //
-    // Two contract details from wow-re's batch, both easy to get wrong:
-    //  · the getter is **`CanNonSpaceWrap`**, not `GetNonSpaceWrap`, and it answers **`1` or nil**,
-    //    not a boolean — 1.12 predates that convention and an addon may compare against 1.
-    //  · a **no-argument call ENABLES** it (the default is on), rather than being a query.
-    //
-    // `oRA2/Leader/Item.lua:561` is `f.textname:SetNonSpaceWrap(false)`, reached by two addons.
+    // SetNonSpaceWrap/CanNonSpaceWrap (`0x79e9f0`/`0x79ead0`), FontString only: the getter
+    // answers 1 or nil, and a call with no argument enables.
     m.set(
         "SetNonSpaceWrap",
         lua.create_function(|lua, (this, enable): (Table, Value)| {
@@ -268,11 +182,9 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetTextHeight(height) — switch the FontString to the scaled-string regime (§5-verified,
-    // wow-re `fontstring-overflow.md`: `0x771600` is the ONLY clearer of the one-to-one bit
-    // `0x200`; the literal size then flows through UNCAPPED, magnified from the raster). Stored
-    // as the distinct [`RegionData::text_height`] — the font object is untouched, so GetFont
-    // keeps reporting the face's own height like the real API.
+    // SetTextHeight: the scaled-string mode (`0x771600` alone clears the one-to-one bit `0x200`),
+    // the size magnified from the raster, uncapped. The font is untouched, so GetFont keeps the
+    // face's own height.
     m.set(
         "SetTextHeight",
         lua.create_function(|lua, (this, height): (Table, f32)| {
@@ -286,14 +198,7 @@ pub(super) fn install(lua: &Lua, m: &Table) -> mlua::Result<()> {
 
     // ── the shared font block ───────────────────────────────────────────────────────────────
     //
-    // `SetFontObject · GetFontObject · SetFont · GetFont · Set/GetTextColor · Set/GetShadowColor ·
-    // Set/GetShadowOffset` are **not** FontString-specific. In the binary each is a thin type-guard
-    // shim that tail-calls one shared implementation (`0x79f210` SetFont, `0x79f3b0` GetFont, …),
-    // which is what [`super::super::font_block`] models — so a FontString and an EditBox are two
-    // entry points to one routine, not two routines that happen to agree.
-    //
-    // They lived here as a hand-written second copy because `region.rs` was over the file-size
-    // budget when the block was written; that split has since landed, and `font_block`'s own doc
-    // named this collapse as the follow-on. 226 lines of duplicate go with it.
+    // The font object, font, text colour and shadow getters and setters are type-guard shims over
+    // one implementation each (`0x79f210` SetFont, `0x79f3b0` GetFont), shared with EditBox.
     super::super::font_block::install(lua, m, region_handle_of, "FontString")
 }
diff --git a/crates/benilla-ui/src/script/region_map.rs b/crates/benilla-ui/src/script/region_map.rs
index 7038af59..2fce44ce 100644
--- a/crates/benilla-ui/src/script/region_map.rs
+++ b/crates/benilla-ui/src/script/region_map.rs
@@ -1,63 +1,28 @@
-//! **The Region method map, reached by frames and regions alike** — the 19 names of the client's
-//! `0x87c9b8` table, each ONE callable that works on a Frame, a Texture or a FontString.
+//! The Region method map: the 19 names of the reference's `0x87c9b8` table, each one callable
+//! that works on a Frame, a Texture or a FontString.
 //!
-//! ## The fact this exists for (byte-verified in `WoW.exe`, decision 1501)
-//!
-//! 1.12.1's widget inheritance is not a Lua metatable chain: every class owns a flat
-//! `{name, lua_CFunction}` `.data` table, and its lookup probes that table and, on a miss,
-//! **tail-calls exactly one base class's lookup** (wow-re
-//! `system/ui/scratch/widget-api-batch-benilla.md`):
+//! Each widget class owns a flat method table whose lookup, on a miss, tail-calls its base's:
 //!
 //! ```text
-//! Region   0x87c9b8 (19)  lookup 0x7a2ea0  → TERMINAL (root)
-//! ├─ Frame        0x878ec0 (68)  lookup 0x778590 → 0x7a2ea0
-//! ├─ Texture      0x87c128 (22)  lookup 0x79c620 → 0x7a2ea0
-//! └─ FontString   0x87c1d8 (32)  lookup 0x79ee20 → 0x7a2ea0
+//! Region      0x87c9b8 (19)  lookup 0x7a2ea0, the root
+//! Frame       0x878ec0 (68)  lookup 0x778590 → 0x7a2ea0
+//! Texture     0x87c128 (22)  lookup 0x79c620 → 0x7a2ea0
+//! FontString  0x87c1d8 (32)  lookup 0x79ee20 → 0x7a2ea0
 //! ```
 //!
-//! Parsing the two tables out of the image directly, **`Frame ∩ Region = ∅`**: not one of the 19
-//! is re-registered by Frame, so every Frame-derived class reaches the *same* function a Texture
-//! does. `WorldFrame.GetHeight` **is** `0x7a2030`, byte-for-byte the function
-//! `someTexture:GetHeight()` resolves to.
+//! Frame re-registers none of the 19, so `WorldFrame.GetHeight` is the function
+//! `someTexture:GetHeight()` resolves to (`0x7a2030`), and addons pull a method off one widget to
+//! apply to another. Each name is one function that resolves the receiver and hands the call to
+//! that kind's arm, as `0x7a2030` calls a vtable slot `CSimpleFontString` overrides; it goes into
+//! every table the chain reaches, so `WorldFrame.GetHeight == someTexture.GetHeight` holds.
 //!
-//! That is why this is not a curiosity. The idiom
-//!
-//! ```lua
-//! local _Height = WorldFrame.GetHeight     -- pull the method off ANY widget, once
-//! …
-//! local h = _Height(someTexture)           -- and apply it to ANY other
-//! ```
-//!
-//! is ordinary, correct 1.12 Lua. Quiver's `Api/Index.wow.lua` is built on it
-//! (`_Height = WorldFrame.GetHeight`, `_Width = WorldFrame.GetWidth`), and benilla raised
-//! `stale or invalid frame handle` on it, from inside the addon's `VARIABLES_LOADED` handler,
-//! **before** the handler's last line got to publish `Quiver.CastPetAction` — which is the whole
-//! of bug B267. One split method surface, one nil field, one dead addon.
-//!
-//! ## Why it is a bridge rather than a merge
-//!
-//! Our two implementations of each name are not redundant: a frame's size reads `layout_inputs`
-//! and divides its edges by `GetEffectiveScale`, a region's reads `region_data` and does not; a
-//! frame's `GetParent` can answer nil, a region's never can; a region's `GetPoint` resolves a
-//! `relativeTo` that may be a sibling *region*. Those differences are correct, and they are the
-//! same shape the reference has: `Region:GetHeight 0x7a2030` reads the receiver's layout
-//! sub-object and calls `[vtable+0x20]`, which `CSimpleFontString` **overrides**. One name, one
-//! entry point, per-kind behaviour behind it.
-//!
-//! So each of the 19 becomes one function that resolves the receiver *first* and then hands the
-//! whole argument list to the arm that owns that kind — and that single function is written into
-//! every method table the reference's chain would reach: the frame table, the region table, the
-//! Texture and FontString leaf tables, and the title region's narrower copy. Identity holds the
-//! way the binary's does — `WorldFrame.GetHeight == someTexture.GetHeight` is true here too.
-//!
-//! **Exactly the 19, and no more.** `Show`/`Hide`/`IsShown`/`IsVisible`/`SetAlpha`/`GetAlpha` look
-//! like they belong and do not: Frame and Texture each register their *own*, at different
-//! addresses (`texture-fontstring-method-split.md` §3), so `WorldFrame.Show(someTexture)` fails on
-//! the real client and must keep failing here. (`SetSize` used to sit outside the 19 for the
-//! opposite reason — in neither table because 1.12 has no such verb at all; decision 2142 removed
-//! it rather than filing it.) The map is the unit.
+//! Exactly the 19: `Show`, `Hide`, `SetAlpha` and the like are per class (`SetAlpha` is `0x774e90`
+//! on Frame, `0x79b580` on Texture), so `WorldFrame.Show(someTexture)` fails, as in the reference.
 
-use mlua::{Function, Lua, MultiValue, Table, Value};
+use std::collections::HashMap;
+use std::rc::Rc;
+
+use mlua::{FromLuaMulti, IntoLuaMulti, Lua, MultiValue, Table, Value};
 
 use super::object::decode_id;
 use super::{
@@ -65,15 +30,15 @@ use super::{
     REG_TEXTURE_METHODS, REG_TITLE_METHODS,
 };
 
-/// Which side of the object model a wrapper's `T[0]` id names. Ids come from one counter
-/// ([`Model::next_id`]), so a region id can never be mistaken for a frame's.
-enum Side {
+/// Which side of the object model a wrapper's `T[0]` id names; ids share one counter
+/// ([`Model::next_id`]), so a region id is never a frame's.
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+pub(super) enum Side {
     Frame,
     Region,
 }
 
-/// `Err` when the table is not a widget wrapper at all (that error names the real problem and is
-/// worth keeping); `Ok(None)` when it *is* one whose widget no longer exists.
+/// `Err` for a table that is no widget wrapper; `Ok(None)` for a wrapper whose widget is gone.
 fn side_of(lua: &Lua, this: &Table) -> mlua::Result<Option<Side>> {
     let id = decode_id(this)?;
     let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -86,11 +51,52 @@ fn side_of(lua: &Lua, this: &Table) -> mlua::Result<Option<Side>> {
     })
 }
 
-/// Replace each of the 19 Region-map entries in every table the chain reaches with one shared
-/// function that dispatches on the receiver.
-///
-/// Runs **after** `region::install` (which is what builds the region, leaf and title tables) and
-/// after `install_frame_methods`; every table it names is already populated by then.
+/// One side's implementation of one of the 19, erased to the variadic ABI so dispatch is a plain
+/// Rust call: a `Function::call` would re-enter Lua through a `lua_pcall` on the hottest verbs.
+/// Built only by [`set_shared`], it converts arguments exactly as `create_function` does.
+pub(super) type Arm = Rc<dyn Fn(&Lua, MultiValue) -> mlua::Result<MultiValue>>;
+
+/// The arms the method-table installers register, held in `app_data` from [`open_arms`] until
+/// [`install`] consumes them.
+#[derive(Default)]
+pub(super) struct Arms(HashMap<(Side, &'static str), Arm>);
+
+/// Register one of the [`REGION_MAP_METHODS`] into its side's table and record its arm; [`install`]
+/// fails if a name lacks either arm. The entry written here keeps the tables complete until
+/// [`install`] replaces it, since the leaf tables are copied from the region table meanwhile.
+pub(super) fn set_shared<A, R, F>(
+    lua: &Lua,
+    m: &Table,
+    side: Side,
+    name: &'static str,
+    f: F,
+) -> mlua::Result<()>
+where
+    A: FromLuaMulti + 'static,
+    R: IntoLuaMulti + 'static,
+    F: Fn(&Lua, A) -> mlua::Result<R> + 'static,
+{
+    let arm: Arm =
+        Rc::new(move |lua, args| f(lua, A::from_lua_multi(args, lua)?)?.into_lua_multi(lua));
+    let entry = arm.clone();
+    m.set(
+        name,
+        lua.create_function(move |lua, args: MultiValue| entry(lua, args))?,
+    )?;
+    lua.app_data_mut::<Arms>()
+        .expect("Region-map arms — installed by `super::object::install`")
+        .0
+        .insert((side, name), arm);
+    Ok(())
+}
+
+/// Open the arm collection, before either method table is built.
+pub(super) fn open_arms(lua: &Lua) {
+    lua.set_app_data(Arms::default());
+}
+
+/// Replace each of the 19 in every table the chain reaches with one function that dispatches on
+/// the receiver. Runs after `region::install` and `install_frame_methods` have built the tables.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let frame: Table = lua.named_registry_value(REG_FRAME_METHODS)?;
     let region: Table = lua.named_registry_value(REG_REGION_METHODS)?;
@@ -103,31 +109,36 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     .map(|k| lua.named_registry_value::<Table>(k))
     .collect::<mlua::Result<_>>()?;
 
+    let arms = lua
+        .remove_app_data::<Arms>()
+        .expect("Region-map arms — opened by `open_arms`");
+
     for name in REGION_MAP_METHODS {
-        // Both arms must already exist. A missing one is not a thing to paper over with a
-        // one-sided shared function: the reference gives every widget all 19, so a gap on either
-        // side is a hole in the surface and says so here rather than at some addon's call site.
-        // (`GetNumPoints` was exactly that hole on the frame side until this module went in.)
-        let on_frame: Function = frame.get(name).map_err(|_| {
-            mlua::Error::runtime(format!("Region map: the FRAME table has no {name}"))
-        })?;
-        let on_region: Function = region.get(name).map_err(|_| {
-            mlua::Error::runtime(format!("Region map: the REGION table has no {name}"))
-        })?;
+        // The reference gives every widget all 19, so a missing arm fails here, not at an addon.
+        let arm = |side: Side, which: &str| -> mlua::Result<Arm> {
+            arms.0.get(&(side, name)).cloned().ok_or_else(|| {
+                mlua::Error::runtime(format!(
+                    "Region map: the {which} side never registered {name} through `set_shared`"
+                ))
+            })
+        };
+        let on_frame = arm(Side::Frame, "FRAME")?;
+        let on_region = arm(Side::Region, "REGION")?;
         let shared = lua.create_function(move |lua, args: MultiValue| {
-            // The receiver is argument 1 on every one of the 19 — a method call always passes it,
-            // and a pulled-off `Api._Height(x)` call passes it as the only argument.
-            let Some(Value::Table(this)) = args.iter().next().cloned() else {
-                return Err(mlua::Error::runtime(
-                    "expected a frame or region as the first argument",
-                ));
+            // The receiver is argument 1, borrowed: a `Value::Table` clone would register a second
+            // ref-thread reference on the hottest verbs.
+            let side = {
+                let Some(Value::Table(this)) = args.iter().next() else {
+                    return Err(mlua::Error::runtime(
+                        "expected a frame or region as the first argument",
+                    ));
+                };
+                side_of(lua, this)?
             };
-            match side_of(lua, &this)? {
-                Some(Side::Frame) => on_frame.call::<MultiValue>(args),
-                Some(Side::Region) => on_region.call::<MultiValue>(args),
-                // A wrapper whose widget is gone. Deliberately ONE message for both sides — at
-                // this point the receiver's kind is exactly what could not be established, and
-                // each side's old wording claimed it.
+            match side {
+                Some(Side::Frame) => on_frame(lua, args),
+                Some(Side::Region) => on_region(lua, args),
+                // A wrapper whose widget is gone: one message, since its kind is unknown.
                 None => Err(mlua::Error::runtime("stale or invalid widget handle")),
             }
         })?;
diff --git a/crates/benilla-ui/src/script/reputation.rs b/crates/benilla-ui/src/script/reputation.rs
index 79f15454..6da59f20 100644
--- a/crates/benilla-ui/src/script/reputation.rs
+++ b/crates/benilla-ui/src/script/reputation.rs
@@ -1,75 +1,12 @@
-//! The reputation-pane bindings — the twelve `ReputationFrame` globals, driving a faithful port of
-//! the real 1.12 Reputation tab (reference FrameXML `ReputationFrame.{xml,lua}`).
-//!
-//! **The display law here is byte-pinned**, not inferred: wow-5875-re
-//! `system/ui/scratch/reputation-panel-law.md`, carved from the client's whole reputation TU
-//! (`[0x4d5200, 0x4d6d80)`) by a §5 cross-check. Addresses below are that node's.
-//!
-//! Same split as [`super::skills`]: the app pushes a flat, unordered snapshot
-//! ([`UiScript::set_reputation`], each row already resolved from `Faction.dbc` + the player's live
-//! wire slot) and the ENGINE groups, sorts and folds. Every index the Lua API takes or returns is
-//! 1-based into the resulting visible row list.
-//!
-//! ## The tree: a header is a FLAG, the parent pointer is only the key
-//!
-//! Two separate facts, and conflating them is what this module was written wrong for once:
-//!
-//! - **A row is a header because the server said so** — flag bit `0x08`, tested as
-//!   `entry.isHeader = (flags >> 3) & 1` at `0x4d5acb`. Every emulator names that bit
-//!   `INVISIBLE_FORCED`; the binary disagrees, and the binary wins. The two readings select the
-//!   *same five factions* on 1.12's data (Alliance, Horde, Steamwheedle Cartel and the two
-//!   battleground blocs all carry it), which is exactly why the wrong one survives a screenshot.
-//! - **`Faction.dbc`'s `team` is the grouping key** — which header a row files under. An `INACTIVE`
-//!   row (flag `0x20`) is re-parented under the key `-1` instead of its own.
-//!
-//! A key whose header row is absent gets one **synthesized** (`0x4d5a70`) carrying that faction's
-//! real id, so `GetFactionInfo` names it the ordinary way. Two keys name no faction at all and take
-//! their text from global strings: `0` → `FACTION_OTHER`, `-1` → `FACTION_INACTIVE`.
-//!
-//! **A childless header is not drawn.** `GetNumFactions` (`ds:0xb73764`) is the total minus each
-//! collapsed child *and each empty header*, over an array re-sorted so `[0, visible)` is exactly the
-//! visible prefix — a flattened materialized view, not a skip.
-//!
-//! ## Ordering (the two real `qsort`s in `0x4d5c40`)
-//!
-//! Headers (`0x4d5dc0`): localized name ascending, with the two unresolved keys last and the
-//! **larger raw key first**, so `0` "Other" precedes `-1` "Inactive". Rows (`0x4d5e70`): within a
-//! header, the header row itself, then its children by localized name ascending.
-//!
-//! ## Collapse
-//!
-//! Client-side only — no opcode carries it, and it is persisted nowhere. The client's mask
-//! (`ds:0x84a0a4`) stores **expanded** bits, so `isCollapsed` is its negation. **Every rebuild
-//! resets it to all-expanded and then collapses the "Inactive" header**, which is why a fold here
-//! does not survive a push (the skills pane's `expandedMask = 0xFFFFFFFF`, one door along).
-//! `CollapseFactionHeader`/`ExpandFactionHeader` given `0` — or any non-header row — act on **every**
-//! header.
-//!
-//! ## Where the numbers come from — all of them, the app
-//!
-//! This crate is engine-free by design (decision 0068: roxmltree + mlua, no DBC, no wire), so every
-//! fidelity number arrives already computed, the same division [`super::skills`] draws.
-//! `crates/benilla-app/src/ui_reputation.rs` owns: the race/class slot pick that gates membership,
-//! adding `Faction.dbc`'s base to the wire standing (`wire + base` at `0x4d6370`), ranking the
-//! total, and the rank's absolute window (`.rdata 0x80928c` — the same nine edges
-//! `benilla_formats::reputation_rank` thresholds against).
-//!
-//! `standing_id` is `rank + 1`, 1..=8 (`FACTION_STANDING_LABEL<n>`, `FACTION_BAR_COLORS[1..8]`).
-//! `barMin`/`barMax`/`barValue` are **absolute**; the reference normalizes them itself (ref l.80-82).
-//! `GetWatchedFactionInfo`'s `reaction` is that **same** 1..8 scale (`0x4d68a0` is `0x4d658a`'s
-//! instruction), not the three-way unit-reaction one.
-//!
-//! ## The three sends, and which are optimistic
-//!
-//! `FactionToggleAtWar` (`0x4d6950` → `CMSG 0x125`) and `SetFactionInactive`/`SetFactionActive`
-//! (`0x4d69b0`/`0x4d6a00` → `CMSG 0x317`) write the local flag **first** and then send; the inactive
-//! pair also re-sorts locally, since the row changes header. `SetWatchedFactionIndex` (`0x4d6b60` →
-//! `CMSG 0x318`) is **not** optimistic: the watched slot is `PLAYER_FIELD_WATCHED_FACTION_INDEX`, a
-//! server field with no client mirror, so the bar moves only once the descriptor update lands.
-//!
-//! The at-war *toggle* enforces more than `canToggleAtWar` reports (`0x4d5fd0`): it also refuses
-//! while the player is in combat, and applies the −3000 floor only when moving toward peace. Only
-//! the reported predicate lives here; the combat half needs state this crate cannot see.
+//! The reputation pane's twelve `ReputationFrame` globals: the app pushes a flat snapshot, and
+//! the engine groups, sorts and folds it as the reference does (`[0x4d5200, 0x4d6d80)`); every
+//! index the API takes or returns is 1-based into the visible rows. A row is a header by flag
+//! `0x08` (`0x4d5acb`), which emulators name `INVISIBLE_FORCED`, and files under its
+//! `Faction.dbc` `team`, or under `-1` while inactive (flag `0x20`); key `0` reads `FACTION_OTHER`
+//! and `-1` `FACTION_INACTIVE`. A childless header is not a row (`GetNumFactions`, `0xb73764`).
+//! Headers sort by name with the synthetic keys last, `0` first (`0x4d5dc0`); children sort by
+//! name (`0x4d5e70`). The at-war toggle also refuses in combat and applies the -3000 floor only
+//! toward peace (`0x4d5fd0`); only `canToggleAtWar`, what the pane reports, lives here.
 
 use std::collections::HashMap;
 
@@ -79,55 +16,51 @@ use super::Model;
 
 /// The synthetic header key for factions the player moved to the inactive bucket.
 const KEY_INACTIVE: i64 = -1;
-/// The synthetic header key for factions with no parent — the "Other" bucket.
+/// The synthetic header key for factions with no parent, the "Other" bucket.
 const KEY_OTHER: i64 = 0;
 
-/// One reputation faction, app-resolved from `Faction.dbc` plus the player's live wire slot.
-/// EXACT shape the app feed (`crates/benilla-app/src/ui_reputation.rs`) is written against — do not
-/// rename.
+/// One reputation faction, resolved app-side from `Faction.dbc` and the player's wire slot.
 #[derive(Clone, Debug, PartialEq)]
 pub struct FactionEntry {
-    /// `Faction.dbc` id — the row's identity, and what a child's [`Self::parent_id`] names.
+    /// `Faction.dbc` id: the row's identity, and what a child's [`Self::parent_id`] names.
     pub faction_id: u32,
-    /// `reputationIndex` — the slot every send addresses and the selection is held by.
+    /// `reputationIndex`: the slot every send addresses and the selection is held by.
     pub rep_list_id: u32,
-    /// `Faction.dbc`'s `team`: the header key this row files under, `0` being the "Other" bucket.
-    /// Overridden to the "Inactive" bucket while [`Self::inactive`] is set.
+    /// `Faction.dbc`'s `team`: the header key this row files under, `0` the "Other" bucket, and
+    /// "Inactive" instead while [`Self::inactive`] is set.
     pub parent_id: u32,
-    /// The localized `Faction.dbc` name — the bar's left-hand label, or a header's text.
+    /// The localized name: the bar's label, or a header's text.
     pub name: String,
-    /// The localized `Faction.dbc` description — the detail popup's paragraph. Often empty.
+    /// The localized description, for the detail popup; often empty.
     pub description: String,
-    /// Total standing: the DBC race/class base plus the wire standing (the app adds them) —
-    /// `GetFactionInfo`'s `barValue`, absolute.
+    /// The DBC race/class base plus the wire standing (`0x4d6370`): `barValue`, absolute.
     pub standing: i32,
-    /// The 1-based standing rank, `1`..=`8` (`FACTION_STANDING_LABEL<n>`), app-ranked.
+    /// The rank, 1..=8 (`FACTION_STANDING_LABEL<n>`); `GetWatchedFactionInfo`'s `reaction` is this
+    /// same scale (`0x4d68a0`), not the unit-reaction one.
     pub standing_id: u8,
-    /// The rank's absolute floor and ceiling — `GetFactionInfo`'s `barMin`/`barMax`.
+    /// The rank's absolute bounds (`.rdata 0x80928c`), `barMin`/`barMax`; the stock pane
+    /// normalizes them itself (`ReputationFrame.lua:80-82`).
     pub bar_min: i32,
     pub bar_max: i32,
-    /// Flag `0x01` — whether the pane lists this faction at all. The **only** flag gating list
-    /// membership; off until the player first meets them.
+    /// Flag `0x01`, the only flag gating list membership: off until the player meets the faction.
     pub visible: bool,
-    /// Flag `0x08` — **this row is a header**, not "force-invisible" (see the module doc).
+    /// Flag `0x08`: this row is a header.
     pub is_header: bool,
-    /// Flag `0x02`. **Engine-mutable**: the toggle flips it here, optimistically, unacked.
+    /// Flag `0x02`; the toggle flips it here, unacked.
     pub at_war: bool,
-    /// Flag `0x10` clear **and** `standing >= -3000` — what `GetFactionInfo` reports. The toggle
-    /// itself is stricter; see the module doc.
+    /// Flag `0x10` clear and `standing >= -3000`: what `GetFactionInfo` reports.
     pub can_toggle_at_war: bool,
-    /// Flag `0x20`. **Engine-mutable**, same reason as [`Self::at_war`]; it re-parents the row under
-    /// the "Inactive" header rather than hiding it.
+    /// Flag `0x20`; flipped here like [`Self::at_war`], it moves the row under "Inactive" rather
+    /// than hiding it.
     pub inactive: bool,
 }
 
-/// A flat, unordered push of every reputation faction the player has a slot for — the ENGINE groups
-/// and sorts (see the module doc). EXACT shape the app feed is written against.
+/// A flat, unordered push of every faction the player has a slot for; the engine groups and sorts.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct ReputationState {
     pub entries: Vec<FactionEntry>,
-    /// `PLAYER_FIELD_WATCHED_FACTION_INDEX` as a reputation-list slot, or `None` for none. A server
-    /// field with no client mirror, so it rides the push and is never written here.
+    /// `PLAYER_FIELD_WATCHED_FACTION_INDEX` as a slot, `None` for none: a server field with no
+    /// client mirror, never written here.
     pub watched: Option<u32>,
 }
 
@@ -138,25 +71,24 @@ pub enum ReputationSend {
     AtWar { rep_list_id: u32, at_war: bool },
     /// `CMSG_SET_FACTION_INACTIVE`.
     Inactive { rep_list_id: u32, inactive: bool },
-    /// `CMSG_SET_WATCHED_FACTION`; `None` is the wire's `-1`, NOT slot 0.
+    /// `CMSG_SET_WATCHED_FACTION`; `None` is the wire's `-1`, not slot 0.
     Watch(Option<u32>),
 }
 
-/// One header group: its key, its header text, and the positions of its children.
-/// Engine-internal; `pub(crate)` only because [`super::model::Model`] stores a `Vec` of them.
+/// One header group; `pub(crate)` only because [`super::model::Model`] stores them.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct FactionGroup {
-    /// The header key — a `Faction.dbc` id, or [`KEY_OTHER`] / [`KEY_INACTIVE`].
+    /// A `Faction.dbc` id, or [`KEY_OTHER`] or [`KEY_INACTIVE`].
     key: i64,
-    /// The header row's text. Empty for the two synthetic keys, whose text is resolved against the
-    /// VM's own global strings when read.
+    /// The header row's text; empty for the two synthetic keys, resolved against the VM's global
+    /// strings when read.
     name: String,
     /// Positions into [`ReputationState::entries`], sorted by [`collate`]d name.
     entries: Vec<usize>,
 }
 
-/// One visible row: a **header** (carrying its group index) or a faction **bar** (carrying its
-/// position into [`ReputationState::entries`]).
+/// One visible row: a header (its group index) or a faction bar (its position in
+/// [`ReputationState::entries`]).
 #[derive(Clone, Copy)]
 enum Row {
     Header(usize),
@@ -164,11 +96,9 @@ enum Row {
 }
 
 impl super::UiScript {
-    /// Push the player's reputation snapshot, rebuilding the display tree.
-    ///
-    /// A rebuild resets the folds to **all expanded** and then collapses the "Inactive" header — the
-    /// client's own behaviour, and the reason a fold does not survive a standing tick. The selection
-    /// is re-anchored by reputation-list slot, dropped only if that faction left the push.
+    /// Push the reputation snapshot and rebuild the tree: as in the reference, whose fold mask
+    /// (`0x84a0a4`) holds expanded bits, every header expands and then "Inactive" collapses, so a
+    /// fold does not survive a standing tick. The selection is kept by slot.
     pub fn set_reputation(&mut self, state: ReputationState) {
         let mut model = self.model_mut();
         let groups = build_groups(&state.entries);
@@ -183,13 +113,12 @@ impl super::UiScript {
         model.reputation = state;
     }
 
-    /// Drain the reputation verbs the pane queued since the last call — the app's outbound seam.
+    /// Drain the reputation verbs the pane queued since the last call.
     pub fn take_reputation_sends(&mut self) -> Vec<ReputationSend> {
         std::mem::take(&mut self.model_mut().reputation_sends)
     }
 }
 
-/// The header key a row files under: its parent, or the inactive bucket while that flag is set.
 fn header_key(e: &FactionEntry) -> i64 {
     if e.inactive {
         KEY_INACTIVE
@@ -198,8 +127,7 @@ fn header_key(e: &FactionEntry) -> i64 {
     }
 }
 
-/// The VM's own text for a synthetic header key, so a localized client gets its own word. Falls back
-/// to the enUS literals when the strings are absent (a bare test VM).
+/// The VM's text for a synthetic header key; the enUS literal in a bare test VM.
 fn synthetic_header(lua: &Lua, key: i64) -> String {
     let (global, fallback) = if key == KEY_INACTIVE {
         ("FACTION_INACTIVE", "Inactive")
@@ -211,16 +139,14 @@ fn synthetic_header(lua: &Lua, key: i64) -> String {
         .unwrap_or_else(|_| fallback.into())
 }
 
-/// Case-insensitive name ordering, raw bytes breaking a tie — the client's own `stricmp`.
-/// Per-module copy, as every seam module here keeps one.
+/// Case-insensitive name order, raw bytes breaking a tie: the client's `stricmp`.
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
         .then_with(|| a.as_bytes().cmp(b.as_bytes()))
 }
 
-/// Era booleans: `1` / `nil`, never `0` — `0` is truthy in Lua and every ref branch here is a bare
-/// `if ( atWarWith )`. Per-module copy, as every seam module here keeps one.
+/// `1` or nil, never `0`: `0` is truthy in Lua, and the stock pane tests `if ( atWarWith )`.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -229,15 +155,9 @@ fn era_bool(b: bool) -> Value {
     }
 }
 
-/// Build the header groups (the module doc's law).
-///
-/// Children are the **visible, non-header** rows, grouped by [`header_key`] and sorted by collated
-/// name. A group's text comes from the header ROW carrying that key when there is one, and is left
-/// empty for the two synthetic keys, resolved against the VM's global strings at read time.
-/// **A childless header is not a group at all** — the client's own count drops it.
-///
-/// Group order: named headers by collated name ascending, then the synthetic keys last with the
-/// larger raw key first, so "Other" (`0`) precedes "Inactive" (`-1`).
+/// Build the header groups: the visible non-header rows by [`header_key`], sorted by name. A group
+/// is named by its pushed header row (the reference synthesizes a missing one, `0x4d5a70`), or left
+/// empty for a synthetic key; a childless header is no group, as the client's count drops it.
 fn build_groups(entries: &[FactionEntry]) -> Vec<FactionGroup> {
     let name_of: HashMap<i64, &str> = entries
         .iter()
@@ -276,7 +196,6 @@ fn build_groups(entries: &[FactionEntry]) -> Vec<FactionGroup> {
     groups
 }
 
-/// The visible row list: every group's header, plus the children of the expanded ones.
 fn rows(model: &Model) -> Vec<Row> {
     let mut out = Vec::new();
     for (gi, g) in model.reputation_groups.iter().enumerate() {
@@ -294,7 +213,6 @@ fn num_rows(model: &Model) -> usize {
     rows(model).len()
 }
 
-/// The entry at a 1-based visible index, or `None` on a header or out of range.
 fn entry_at(model: &Model, index: usize) -> Option<&FactionEntry> {
     match rows(model).get(index.checked_sub(1)?)? {
         Row::Entry(ei) => model.reputation.entries.get(*ei),
@@ -302,7 +220,6 @@ fn entry_at(model: &Model, index: usize) -> Option<&FactionEntry> {
     }
 }
 
-/// The mutable twin of [`entry_at`] — the at-war/inactive flips write through it.
 fn entry_at_mut(model: &mut Model, index: usize) -> Option<&mut FactionEntry> {
     let row = *rows(model).get(index.checked_sub(1)?)?;
     match row {
@@ -311,9 +228,8 @@ fn entry_at_mut(model: &mut Model, index: usize) -> Option<&mut FactionEntry> {
     }
 }
 
-/// Fold or unfold by 1-based visible index. Index `0` — **or any index that is not a header** — acts
-/// on every header, which is the client's own fall-through (`0x4d6a50`/`0x4d6aa0`), not a tolerance
-/// invented here.
+/// Fold or unfold by 1-based visible index; `0` or any non-header index acts on every header, the
+/// reference's own fall-through (`0x4d6a50`, `0x4d6aa0`).
 fn set_collapsed(model: &mut Model, index: usize, collapse: bool) {
     let one = index
         .checked_sub(1)
@@ -335,10 +251,8 @@ fn set_collapsed(model: &mut Model, index: usize, collapse: bool) {
     }
 }
 
-/// `GetFactionInfo`'s out-of-range answer — **eleven values, not one nil** (`0x4d5fa0`'s miss path):
-/// `nil, nil, 1, 0, 0, 0, nil, nil, nil, nil, nil`. The `1` in the `standingID` slot is the
-/// client's, and it is load-bearing: the reference indexes `FACTION_BAR_COLORS[standingID]`
-/// unguarded, so a `nil` there would be an error rather than a blank row.
+/// `GetFactionInfo`'s miss (`0x4d5fa0`): eleven values, standingID 1, which the stock pane indexes
+/// `FACTION_BAR_COLORS` with unguarded.
 fn unknown_faction() -> MultiValue {
     let mut out = vec![Value::Nil, Value::Nil, Value::Integer(1)];
     out.extend(std::iter::repeat_n(Value::Integer(0), 3));
@@ -347,7 +261,6 @@ fn unknown_faction() -> MultiValue {
     MultiValue::from_vec(out)
 }
 
-/// Register the reputation-pane globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -360,9 +273,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetFactionInfo(index) → the ref's own eleven (ref-ReputationFrame.lua l.51):
-    // name, description, standingID, barMin, barMax, barValue, atWarWith, canToggleAtWar,
-    // isHeader, isCollapsed, isWatched. 1-based; ELEVEN wide on every path, a miss included.
+    // GetFactionInfo(index) → the stock pane's eleven (`ReputationFrame.lua:51`): name,
+    // description, standingID, barMin, barMax, barValue, atWarWith, canToggleAtWar, isHeader,
+    // isCollapsed, isWatched; eleven wide on every path, a miss included.
     g.set(
         "GetFactionInfo",
         lua.create_function(|lua, index: usize| {
@@ -416,8 +329,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedFaction() → the selected row's VISIBLE index, or 0 for none (the ref compares
-    // against 0 outright). The selection is HELD by slot, so this re-finds the row each call.
+    // GetSelectedFaction() → the selected row's visible index, or 0 for none, as
+    // `ReputationFrame.lua:146` tests; re-found each call, since the selection is held by slot.
     g.set(
         "GetSelectedFaction",
         lua.create_function(|lua, ()| {
@@ -433,7 +346,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSelectedFaction(index) — a VISIBLE index; a header or an out-of-range index clears it.
+    // SetSelectedFaction(index): a visible index; a header or an out-of-range index clears it.
     g.set(
         "SetSelectedFaction",
         lua.create_function(|lua, index: usize| {
@@ -443,16 +356,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CollapseFactionHeader(index) / ExpandFactionHeader(index) — a VISIBLE header index; `0` or a
-    // non-header row acts on EVERY header (the client's own fall-through).
-    // **Both fire `UPDATE_FACTION`, and that is the engine's own doing, not a convenience.**
-    // `CollapseFactionHeader 0x4d6a50` and `ExpandFactionHeader 0x4d6aa0` both reach `0x4d6400`,
-    // which tail-jumps to `0x4d5c40` — and `0x4d5dab`, inside that function, is one of the FOUR
-    // whole-image fire sites of `UPDATE_FACTION` (wow-re `reputation-panel-law.md` §7.5 and §8,
-    // both VERIFIED). The stock pane has no other repaint path after a fold: its header `<OnClick>`
-    // calls the binding and nothing else (ReputationFrame.xml:9-15), and `ReputationFrame_OnEvent`
-    // repaints on `UPDATE_FACTION` alone. Our own retired file repainted itself, which is why this
-    // was invisible until the pane went stock (1875).
+    // CollapseFactionHeader(index) / ExpandFactionHeader(index): a visible header index. Both fire
+    // `UPDATE_FACTION`, as the reference's do (`0x4d6a50`, `0x4d6aa0` → `0x4d6400` → `0x4d5c40`,
+    // fire site `0x4d5dab`): the stock header's `OnClick` only calls the binding
+    // (`ReputationFrame.xml:9-15`), and the pane repaints on `UPDATE_FACTION` alone.
     g.set(
         "CollapseFactionHeader",
         lua.create_function(|lua, index: usize| {
@@ -476,8 +383,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // FactionToggleAtWar(index) — flip our own AT_WAR bit and queue the send, optimistically
-    // (`0x4d6950` writes locally first, and nothing acks it).
+    // FactionToggleAtWar(index): flip the at-war bit and queue the send; `0x4d6950` writes locally
+    // first, and nothing acks it.
     g.set(
         "FactionToggleAtWar",
         lua.create_function(|lua, index: usize| {
@@ -498,10 +405,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsFactionInactive(index) / SetFactionInactive(index) / SetFactionActive(index) — optimistic
-    // too, and the flip RE-PARENTS the row under the "Inactive" header, so the tree is rebuilt
-    // locally (`0x4d69b0`'s own `0x4d5c40` call). The folds are kept across that regroup: it is not
-    // a server rebuild, which is the thing that resets them.
+    // IsFactionInactive / SetFactionInactive / SetFactionActive (`0x4d69b0`, `0x4d6a00`): the flip
+    // is local first too, and moves the row under "Inactive", so the tree regroups here
+    // (`0x4d69b0` calls `0x4d5c40`); the folds survive, as only a server rebuild resets them.
     g.set(
         "IsFactionInactive",
         lua.create_function(|lua, index: usize| {
@@ -532,8 +438,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GetWatchedFactionInfo() → name, reaction, min, max, value — or a single nil when nothing is
-    // watched (the ref's `if ( name )` gate). `reaction` is the SAME 1-based standingID scale.
+    // GetWatchedFactionInfo() → name, reaction, min, max, value; `reaction` is the standingID
+    // scale, and a nil name is `ReputationFrame.lua:167`'s nothing-watched gate.
     g.set(
         "GetWatchedFactionInfo",
         lua.create_function(|lua, ()| {
@@ -546,14 +452,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     .find(|e| e.rep_list_id == slot)
             });
             let Some(e) = watched else {
-                // FIVE values on the nothing-watched branch too — `0x4d6820` has four guards onto
-                // one label and no raise, so the shape is `nil, 0, 0, 0, 0` (decision 1845).
-                //
-                // Worth carrying with it: the `[0, 64)` bound is **not in the binding**.
-                // `0x4d5620` maps an out-of-range index to `0`, so the "nothing watched" sentinel
-                // passes the `< 0` and `> max` guards and dies at the NULL-DBC-row guard instead.
-                // A port that range-checks inside the binding implements a branch the reference
-                // does not have.
+                // Five values here too, `nil, 0, 0, 0, 0`: `0x4d6820`'s four guards share one exit
+                // and none raises. `0x4d5620` maps the out-of-range sentinel to 0, so it is refused
+                // at the null-row guard, not by a range check.
                 return Ok(MultiValue::from_vec(vec![
                     Value::Nil,
                     Value::Integer(0),
@@ -572,10 +473,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetWatchedFactionIndex(index) — a VISIBLE index, `0` meaning "stop watching". **Not
-    // optimistic** (`0x4d6b60`): the watched slot lives in PLAYER_FIELD_WATCHED_FACTION_INDEX with
-    // no client mirror, so the bar only moves once the descriptor update comes back. The `0` → `-1`
-    // translation happens at the app's wire edge, since slot 0 is a real faction.
+    // SetWatchedFactionIndex(index): a visible index, 0 to stop watching. Not local first
+    // (`0x4d6b60`): the watched slot is a server field with no client mirror, so the bar moves when
+    // the descriptor update returns. The app sends none as `-1`, since slot 0 is a real faction.
     g.set(
         "SetWatchedFactionIndex",
         lua.create_function(|lua, index: usize| {
@@ -614,9 +514,8 @@ mod tests {
         }
     }
 
-    /// A header row as the real wire delivers one: flag `0x08` set, and **not** `VISIBLE` — the
-    /// Steamwheedle Cartel's actual byte is `0x08` alone. A header is used for its name, never
-    /// drawn as a bar, so its own visibility is irrelevant and this fixture proves it.
+    /// A header row as the wire delivers one: flag `0x08` without `VISIBLE`, as the Steamwheedle
+    /// Cartel's byte is; a header is never drawn as a bar, so its own visibility is irrelevant.
     fn header(faction_id: u32, rep_list_id: u32, name: &str) -> FactionEntry {
         FactionEntry {
             visible: false,
@@ -625,10 +524,9 @@ mod tests {
         }
     }
 
-    /// Two named groups and the bucket, pushed OUT of order so the engine's own sort is what shows:
-    /// Alliance (469) over Stormwind + Ironforge, Steamwheedle (169) over Booty Bay, and two
-    /// parentless factions. Bloodsail Buccaneers is here because it really does hold slot **0** —
-    /// the value that must never be confused with "watch nothing".
+    /// Pushed out of order so the engine's sort shows: Alliance (469) over Stormwind and Ironforge,
+    /// Steamwheedle (169) over Booty Bay, and two parentless factions. Bloodsail Buccaneers holds
+    /// slot 0, which must never read as "watch nothing".
     fn state() -> ReputationState {
         ReputationState {
             entries: vec![
@@ -650,7 +548,6 @@ mod tests {
         s
     }
 
-    /// Every visible row's name, in order — the shape assertion the rest lean on.
     fn names(s: &UiScript) -> Vec<String> {
         s.eval::<Vec<String>>(
             "local t = {} for i = 1, GetNumFactions() do t[i] = (GetFactionInfo(i)) end return t",
@@ -658,12 +555,8 @@ mod tests {
         .expect("names")
     }
 
-    /// **The tree.** Headers are the rows the server FLAGGED as headers (`0x08`), grouped by the
-    /// children's `team`; a header is never also a bar; groups and children sort by name; and the
-    /// parentless bucket comes last under `FACTION_OTHER`.
-    ///
-    /// The fixture's headers are pushed WITHOUT the visible flag, which is what the real wire
-    /// sends — so this also pins that a header's own visibility does not gate its group.
+    /// The fixture's headers lack the visible flag, as on the wire, so this also pins that a
+    /// header's own visibility does not gate its group.
     #[test]
     fn the_header_flag_builds_the_tree_and_other_comes_last() {
         let s = seated();
@@ -693,8 +586,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **A childless header is not a row at all** — the client's own count drops it, so a header
-    /// whose children are all unmet must not leave an empty group behind.
     #[test]
     fn a_header_with_no_visible_children_is_dropped() {
         let mut s = UiScript::new().expect("VM");
@@ -715,9 +606,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **`GetFactionInfo`'s eleven, on a bar** — and eleven on a MISS too, which is the client's own
-    /// shape (`nil, nil, 1, 0, 0, 0, nil×5`). The `1` matters: the reference indexes
-    /// `FACTION_BAR_COLORS[standingID]` unguarded, so a nil there would raise rather than blank.
     #[test]
     fn a_bar_row_returns_the_references_eleven_and_so_does_a_miss() {
         let s = seated();
@@ -756,8 +644,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **Folding hides a group's children and shrinks the count**, and index `0` (or any non-header
-    /// row) acts on EVERY header — the client's own fall-through, not a tolerance invented here.
     #[test]
     fn folding_shrinks_the_list_and_index_zero_folds_everything() {
         let s = seated();
@@ -782,14 +668,14 @@ mod tests {
         s.run("ExpandFactionHeader(1)").unwrap();
         assert_eq!(names(&s).len(), 8, "expanded again");
 
-        // A BAR row is not a header, so it takes the same fall-through: index 2 is Ironforge.
+        // A bar row is not a header, so it takes the same fall-through: index 2 is Ironforge.
         s.run("CollapseFactionHeader(2)").unwrap();
         assert_eq!(
             names(&s),
             ["Alliance", "Steamwheedle Cartel", "Other"],
             "a non-header index folds every header"
         );
-        // …and so does index 0, and so does an index off the end of the list.
+        // So do index 0 and an index past the end.
         s.run("ExpandFactionHeader(0)").unwrap();
         assert_eq!(names(&s).len(), 8, "index 0 unfolds every header");
         s.run("CollapseFactionHeader(99)").unwrap();
@@ -797,8 +683,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **A push RESETS the folds** — all expanded, then "Inactive" collapsed. The client rebuilds
-    /// its expand mask on every server refresh, so a fold cannot survive a standing tick.
     #[test]
     fn a_push_resets_the_folds() {
         let mut s = seated();
@@ -811,8 +695,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **Inactive re-parents a row under the synthetic "Inactive" header, which starts collapsed.**
-    /// It does not hide the faction, and it does not touch the bucket the row came from.
     #[test]
     fn an_inactive_faction_moves_under_the_inactive_header() {
         let mut s = UiScript::new().expect("VM");
@@ -839,8 +721,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **Selection is held by reputation slot, not by row.** `GetSelectedFaction` answers `0` for
-    /// none — what the ref's own teardown compares against — and re-finds the row after a reorder.
     #[test]
     fn selection_follows_the_faction_not_the_row_index() {
         let mut s = seated();
@@ -852,7 +732,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetSelectedFaction()").unwrap(), 0);
         s.run("ExpandFactionHeader(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetSelectedFaction()").unwrap(), 3);
-        // Selecting a HEADER clears the selection rather than selecting the group.
+        // Selecting a header clears the selection rather than selecting the group.
         s.run("SetSelectedFaction(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetSelectedFaction()").unwrap(), 0);
         // A push that drops the faction entirely drops the selection with it.
@@ -864,9 +744,8 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **The two unacked toggles flip locally and queue their sends**; a peace-forced faction
-    /// refuses (the ref disables the box, but an addon can still call the global), and going
-    /// inactive re-groups on the spot without waiting for a server rebuild.
+    /// A peace-forced faction refuses: the stock pane disables the box, but an addon can still call
+    /// the global.
     #[test]
     fn the_war_and_inactive_toggles_flip_locally_and_queue_their_sends() {
         let mut s = seated();
@@ -911,10 +790,6 @@ mod tests {
         assert!(s.errors().is_empty(), "{:#?}", s.errors());
     }
 
-    /// **The watch bar's five, the `0` that means "nothing", and the fact that watching is NOT
-    /// optimistic.** The watched slot is a server field with no client mirror, so the pane shows a
-    /// new bar only after the descriptor update comes back as a fresh push — clicking alone must
-    /// change nothing on screen.
     #[test]
     fn watching_queues_a_send_but_does_not_move_the_bar_itself() {
         let mut s = seated();
@@ -934,7 +809,7 @@ mod tests {
         );
         assert_eq!(s.take_reputation_sends(), [ReputationSend::Watch(Some(19))]);
 
-        // The descriptor update arrives as the next push, and NOW the bar reads.
+        // The descriptor update arrives as the next push, and now the bar reads.
         let mut watched = state();
         watched.watched = Some(19);
         s.set_reputation(watched);
@@ -950,7 +825,7 @@ mod tests {
             "and the row reports itself watched"
         );
 
-        // Watching the row that IS slot 0, then clearing — the two must not collapse together.
+        // Watching slot 0, then clearing: the two must stay distinct.
         s.run("SetWatchedFactionIndex(8)").unwrap(); // Bloodsail Buccaneers, rep slot 0
         assert_eq!(s.take_reputation_sends(), [ReputationSend::Watch(Some(0))]);
         s.run("SetWatchedFactionIndex(0)").unwrap();
diff --git a/crates/benilla-ui/src/script/saved.rs b/crates/benilla-ui/src/script/saved.rs
index fb551242..f19409f4 100644
--- a/crates/benilla-ui/src/script/saved.rs
+++ b/crates/benilla-ui/src/script/saved.rs
@@ -1,70 +1,60 @@
-//! **Saved variables** — the Lua-level settings that survive a restart (decision 1128).
+//! Saved variables: the Lua settings that survive a restart. The reference saves FrameXML's
+//! `RegisterForSave` globals to one file read back by a line parser (`0x4913b0`, strings and
+//! numbers only), and an addon's `## SavedVariables` to its own file, executed as a chunk before
+//! `ADDON_LOADED` (`AddOn_Load` `0x51f240`). Deviation: the `RegisterForSave` file is executed as a
+//! chunk too, because the line parser cannot carry a table. The app owns the files (`ui_saved`).
 //!
-//! The reference client has *two* mechanisms for this, byte-verified in wow-re
-//! (`system/ui/scratch/savedvariables-protocol.md`):
-//!
-//! 1. **`RegisterForSave("NAME")`** — the Lua API FrameXML uses for its **38** globals
-//!    (`LOCK_ACTIONBAR`, `CHAT_LOCKED`, the eleven `COMBAT_TEXT_*`, …), written to the flat
-//!    `WTF/Account/<ACC>/SavedVariables.lua` and read back by a hand-rolled line parser
-//!    (`0x4913b0`, strings and numbers only) before `VARIABLES_LOADED` fires.
-//! 2. **`## SavedVariables` in a `.toc`** — one file per addon, *executed as a Lua chunk*
-//!    (`AddOn_Load 0x51f240` step 4, before `ADDON_LOADED` at step 6). Exactly one stock addon
-//!    uses it: `Blizzard_TrainerUI`, for the trainer window's three filter globals.
-//!
-//! benilla's ported UI is **one FrameXML tree, not addons** ([`crate::script`]'s manifest), so the
-//! two collapse into one here: the *declaration* API is (1) — the one our XML can call — and the
-//! *load* is (2)'s, a real chunk, because we already have a Lua VM and executing beats a line
-//! parser that cannot carry a table. One file, install-scoped (the `benilla/` folder is already
-//! per-install, so it IS the reference's account scope — decision 0954). The host side — path,
-//! load seam, write triggers — is the app's `ui_saved` module's.
-//!
-//! **Deliberate divergences from the reference's serializer**, all recorded in 1128: LF and no
-//! leading blank line (its `"\r\n"`-per-variable prefix means every file it writes *starts* with a
-//! blank line); Rust's shortest round-tripping float formatting instead of `%.16g` (which loses a
-//! double needing 17 digits); table entries emitted in a **sorted** order instead of raw `pairs`
-//! order, so a settings file diffs cleanly; `\r` escaped rather than written raw (raw CR inside a
-//! quoted string is what the reference emits and it does not re-parse); and a cycle is dropped
-//! rather than cut by writing a lightuserdata sentinel *into the caller's table*. What is faithful
-//! is the grammar — `NAME = value`, `nil` written out, bracketed keys, TAB indent, trailing comma —
-//! so a file is readable by, and swappable with, the reference's own.
+//! The grammar is the reference's: `NAME = value`, `nil` written out, bracketed keys, tab indent,
+//! trailing comma. Deviations, so a file diffs cleanly and reloads exactly: LF line ends with no
+//! leading blank line, the shortest round-tripping float where the reference's `%.16g` can lose a
+//! digit, entries sorted rather than in `pairs` order, `\r` escaped where the reference writes it
+//! raw and cannot read it back, and a cycle dropped where the reference writes a sentinel into the
+//! caller's table.
 
 use std::collections::HashSet;
 use std::ffi::c_void;
-use std::fmt::Write as _;
 
 use mlua::{Lua, Table, Value};
 
 use super::Model;
 
-/// How deep a table may nest before the serializer gives up. The reference recurses uncapped (only
-/// its indent saturates at `0x80`); a settings file is not a place where 32 levels is anything but
-/// a bug, and a bound is what keeps a hostile or accidental structure from eating the stack.
+/// Deviation: nesting stops at 32 where the reference recurses uncapped (its indent saturates at
+/// `0x80`), so a hostile structure cannot exhaust the stack.
 const MAX_DEPTH: usize = 32;
 
 impl super::UiScript {
-    /// The registered names, in registration order — what the host writes out (the reference's
-    /// own emission order, and stable across runs because the load order is).
+    /// Hold a saved-variables file that failed to load, so the shutdown write leaves it alone.
+    /// Deviation: the reference rewrites it from the live defaults (`0x51f865`–`0x51f970`), which
+    /// would cost the player the whole file for one typo in a hand edit.
+    pub fn hold_saved_file(&self, path: &std::path::Path) {
+        let mut model = self.model_mut();
+        if !model.held_saved_files.iter().any(|p| p == path) {
+            model.held_saved_files.push(path.to_path_buf());
+        }
+    }
+
+    /// Whether this session's load failed on `path`.
+    pub fn saved_file_held(&self, path: &std::path::Path) -> bool {
+        self.model_ref().held_saved_files.iter().any(|p| p == path)
+    }
+
+    /// The registered names in registration order, the reference's own write order.
     pub fn saved_variable_names(&self) -> Vec<String> {
         self.model_mut().saved_names.clone()
     }
 
-    /// Serialize every registered global into the settings file's body, `NAME = value` per line.
-    ///
-    /// A name whose value cannot round-trip through a Lua chunk (a function, a widget reference,
-    /// any userdata — and `inf`/`NaN`, which are not Lua literals) is **skipped with a warning**
-    /// rather than written as something that would fail to load; the reference loses the same set,
-    /// silently. `nil` IS written (`NAME = nil`), which is how the reference records a toggle that
-    /// has never been touched.
-    pub fn saved_variables_text(&self) -> String {
-        self.saved_variables_text_for(&self.saved_variable_names())
+    /// Serialize every registered global as `NAME = value` lines, in bytes, since a Lua string is
+    /// bytes and the reference writes them raw. A value with no literal (a function, userdata,
+    /// `inf`, `NaN`) is skipped with a warning where the reference drops it silently; `nil` is
+    /// written, as the reference records an untouched toggle.
+    pub fn saved_variables_bytes(&self) -> Vec<u8> {
+        self.saved_variables_bytes_for(&self.saved_variable_names())
     }
 
-    /// [`UiScript::saved_variables_text`] over an explicit name list — an addon's own
-    /// `## SavedVariables` set (1188 phase 3), which is declared in its manifest rather than
-    /// through `RegisterForSave`. Same grammar, same skip rules; only the source of the names
-    /// differs, which is exactly the difference between the reference's two mechanisms.
-    pub fn saved_variables_text_for(&self, names: &[String]) -> String {
-        let mut out = String::new();
+    /// [`UiScript::saved_variables_bytes`] over an explicit name list, an addon's own
+    /// `## SavedVariables` set.
+    pub fn saved_variables_bytes_for(&self, names: &[String]) -> Vec<u8> {
+        let mut out = Vec::new();
         let mut unwritable = Vec::new();
         for name in names {
             let value: Value = match self.lua().globals().get(name.as_str()) {
@@ -77,7 +67,10 @@ impl super::UiScript {
             let mut seen = HashSet::new();
             match serialize(&value, 1, &mut seen) {
                 Some(text) => {
-                    let _ = writeln!(out, "{name} = {text}");
+                    out.extend_from_slice(name.as_bytes());
+                    out.extend_from_slice(b" = ");
+                    out.extend_from_slice(&text);
+                    out.push(b'\n');
                 }
                 None => unwritable.push(name.clone()),
             }
@@ -92,29 +85,25 @@ impl super::UiScript {
     }
 }
 
-/// One Lua value as the text of a Lua expression, or `None` when it cannot be one.
-///
-/// `depth` is the indent level of the *contents* of a table at this position (so a top-level value
-/// starts at 1); `seen` carries the table identities on the current path — a repeat is a cycle and
-/// drops that entry. Note it is the *path*, not every table ever visited: a shared subtable is
-/// legitimately written twice (as it must be, since the file has no way to express aliasing).
-fn serialize(v: &Value, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<String> {
+/// One Lua value as Lua expression text, or `None` when it has none. `depth` is the indent of a
+/// table's contents here (1 at top level); `seen` holds the tables on the current path, so a repeat
+/// is a cycle and drops, while a shared subtable is written each time it appears.
+fn serialize(v: &Value, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<Vec<u8>> {
     match v {
-        Value::Nil => Some("nil".to_string()),
-        Value::Boolean(b) => Some(b.to_string()),
-        Value::Integer(i) => Some(i.to_string()),
-        Value::Number(n) => number(*n),
-        Value::String(s) => Some(quote(&s.to_string_lossy())),
+        Value::Nil => Some(b"nil".to_vec()),
+        Value::Boolean(b) => Some(b.to_string().into_bytes()),
+        Value::Integer(i) => Some(i.to_string().into_bytes()),
+        Value::Number(n) => number(*n).map(String::into_bytes),
+        Value::String(s) => Some(quote(&s.as_bytes())),
         Value::Table(t) => table(t, depth, seen),
-        // Functions, threads, userdata (every widget reference is one — a frame's Lua value is a
-        // table whose `[0]` is a lightuserdata handle, RF-0023) cannot be written as a literal.
+        // Functions, threads and userdata have no literal; a frame's `[0]` handle is a
+        // lightuserdata (`0x701bd0`).
         _ => None,
     }
 }
 
-/// A Lua number literal. Integral values print without a fractional part (`1`, not `1.0` — the
-/// reference's `%.16g` does the same, and our XML compares these against integers); everything
-/// else takes Rust's shortest form that round-trips exactly. `inf`/`NaN` have no literal at all.
+/// A Lua number literal: integral values bare, as the reference's `%.16g` prints them, others in
+/// the shortest form that round-trips; `inf` and `NaN` have none.
 fn number(n: f64) -> Option<String> {
     if !n.is_finite() {
         return None;
@@ -125,45 +114,35 @@ fn number(n: f64) -> Option<String> {
     Some(format!("{n}"))
 }
 
-/// A quoted Lua string. The reference escapes exactly four characters (`\000`, `\n`, `\"`, `\\`)
-/// and writes CR and every high byte raw; we add `\r` (raw CR in a quoted string is not something
-/// its own loader could read back) and keep high bytes raw, so localized text stays legible.
-fn quote(s: &str) -> String {
-    let mut out = String::with_capacity(s.len() + 2);
-    out.push('"');
-    for c in s.chars() {
-        match c {
-            '\\' => out.push_str("\\\\"),
-            '"' => out.push_str("\\\""),
-            '\n' => out.push_str("\\n"),
-            '\r' => out.push_str("\\r"),
-            '\0' => out.push_str("\\000"),
-            c => out.push(c),
+/// A quoted Lua string: the reference's four escapes (`\000`, `\n`, `\"`, `\\`) plus `\r`, every
+/// other byte raw.
+fn quote(s: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(s.len() + 2);
+    out.push(b'"');
+    for &b in s {
+        match b {
+            b'\\' => out.extend_from_slice(b"\\\\"),
+            b'"' => out.extend_from_slice(b"\\\""),
+            b'\n' => out.extend_from_slice(b"\\n"),
+            b'\r' => out.extend_from_slice(b"\\r"),
+            0 => out.extend_from_slice(b"\\000"),
+            b => out.push(b),
         }
     }
-    out.push('"');
+    out.push(b'"');
     out
 }
 
-/// A table constructor: `{\n<tabs>[key] = value,\n<tabs-1>}`. Keys are always bracketed (the
-/// reference's shape — its writer emits `[key] = value` for **every** table shape and never a bare
-/// positional entry, byte-verified in wow-re `system/ui/scratch/lua-table-storage-and-next-order.md`
-/// §Q5 — and it sidesteps every reserved-word and non-identifier question); entries are **sorted**
-/// — integer keys ascending, then strings alphabetically — so the file is stable across runs
-/// instead of following Lua's hash order.
-///
-/// **A list written this way still reloads as a list**, and that is a property of the *parser*, not
-/// of this emitter: 1.12's `recfield` gives a `[expr] = v` field neither size hint, so the table is
-/// born on the dummy node, the first store rehashes, and the dense integer keys land in an array
-/// part that `next` walks ascending. Our vendored parser was restored to that placement in decision
-/// 2111 — before it, this exact file shape came back keyed 1..n in the *hash* part and Bagnon's
-/// keyring drew first.
-fn table(t: &Table, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<String> {
+/// A table constructor, `{\n<tabs>[key] = value,\n<tabs-1>}`: every key bracketed, as the
+/// reference writes for every table shape (`[0x704607, 0x704989)`), integer keys ascending, then
+/// strings. It reloads a list as a list through the 1.12 parser: `recfield` gives a `[k] = v` field
+/// no size hint, so dense integer keys land in the array part, which `next` walks in order.
+fn table(t: &Table, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<Vec<u8>> {
     if depth > MAX_DEPTH || !seen.insert(t.to_pointer()) {
         return None;
     }
-    let mut ints: Vec<(i64, String)> = Vec::new();
-    let mut strs: Vec<(String, String)> = Vec::new();
+    let mut ints: Vec<(i64, Vec<u8>)> = Vec::new();
+    let mut strs: Vec<(Vec<u8>, Vec<u8>)> = Vec::new();
     for pair in t.pairs::<Value, Value>() {
         let Ok((k, v)) = pair else { continue };
         let Some(value) = serialize(&v, depth + 1, seen) else {
@@ -173,36 +152,39 @@ fn table(t: &Table, depth: usize, seen: &mut HashSet<*const c_void>) -> Option<S
             Value::Integer(i) => ints.push((i, value)),
             // A float key that is integral is the same slot as the integer in Lua 5.1.
             Value::Number(n) if n.fract() == 0.0 => ints.push((n as i64, value)),
-            Value::String(s) => strs.push((s.to_string_lossy(), value)),
+            Value::String(s) => strs.push((s.as_bytes().to_vec(), value)),
             _ => continue, // a table/bool/function key cannot be written as a literal
         }
     }
     seen.remove(&t.to_pointer());
     ints.sort_by_key(|(k, _)| *k);
+    // Byte order, the same as `str` order for UTF-8 keys.
     strs.sort_by(|a, b| a.0.cmp(&b.0));
 
     let indent = "\t".repeat(depth);
     let close = "\t".repeat(depth.saturating_sub(1));
-    let mut out = String::from("{\n");
+    let mut out = b"{\n".to_vec();
+    let mut entry = |key: &[u8], value: &[u8]| {
+        out.extend_from_slice(indent.as_bytes());
+        out.push(b'[');
+        out.extend_from_slice(key);
+        out.extend_from_slice(b"] = ");
+        out.extend_from_slice(value);
+        out.extend_from_slice(b",\n");
+    };
     for (k, v) in ints {
-        let _ = writeln!(out, "{indent}[{k}] = {v},");
+        entry(k.to_string().as_bytes(), &v);
     }
     for (k, v) in strs {
-        let _ = writeln!(out, "{indent}[{}] = {v},", quote(&k));
+        entry(&quote(&k), &v);
     }
-    out.push_str(&close);
-    out.push('}');
+    out.extend_from_slice(close.as_bytes());
+    out.push(b'}');
     Some(out)
 }
 
-/// Register the `RegisterForSave` global.
-///
-/// Divergence, disclosed: the reference's binding is **taint-gated to Blizzard code**
-/// (`0x4884e0`), because a third-party addon writing into the shared account file would be a
-/// security surface. benilla has no taint model yet and loads no third-party addons, so the gate
-/// has nothing to gate; when addon loading lands, this is one of the bindings that needs it (and
-/// an addon's own `## SavedVariables` file is the mechanism it should use instead — the `.toc`
-/// directive [`crate::toc::Toc::list`] already parses).
+/// Register `RegisterForSave`, with no taint gate: the reference refuses it outside Blizzard code
+/// (`0x4884e0`), and benilla has no taint model.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set(
         "RegisterForSave",
@@ -220,17 +202,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// **A saved LIST comes back a list** — Bagnon's inventory grid, at 1:1 scale, and the
-    /// round-trip half of decision 2111 (the dialect half is `lua50`'s own tests).
-    ///
-    /// `Bagnon_Core` keeps its frame's bag order in a saved table, sorts it so the keyring
-    /// (`KEYRING_CONTAINER` = -2) lands last, and then lays the grid out by walking it with
-    /// **`pairs`** (`BagnonFrame_Generate`'s `for _, bagID in pairs(BagnonSets[frameName].bags)`).
-    /// Session one has no file: the table is the literal `{-2,0,1,2,3,4}`, an array table, and
-    /// `pairs` walks it 1..6 — keyring last, as the reference shows it. Session two reads the
-    /// serializer's `[k] = v` form back, and before 2111 that came back keyed 1..6 in the **hash**
-    /// part, walked in slot order, with key 6 — the keyring — **first**, ahead of the backpack.
-    /// That is the director's report; the writer is unchanged and the parser is what was wrong.
+    /// Bagnon's shape: a saved bag list sorted with the keyring (-2) last, laid out by `pairs`.
     #[test]
     fn a_saved_list_still_walks_in_index_order_after_a_restart() {
         let s = UiScript::new().unwrap();
@@ -254,18 +226,17 @@ mod tests {
         };
         assert_eq!(walk(&s), "0,1,2,3,4,-2,", "the live table, before any save");
 
-        let text = s.saved_variables_text();
+        let text = s.saved_variables_bytes();
         let fresh = UiScript::new().unwrap();
-        fresh.run(&text).unwrap();
+        fresh.run_chunk(&text).unwrap();
         assert_eq!(
             walk(&fresh),
             "0,1,2,3,4,-2,",
-            "the restart must walk the same order the live session did; wrote:\n{text}"
+            "the restart must walk the same order the live session did; wrote:\n{}",
+            String::from_utf8_lossy(&text)
         );
     }
 
-    /// The round trip that is the whole point: what the writer emits, the loader's own chunk
-    /// restores — through a fresh VM, exactly as a restart does.
     #[test]
     fn the_declared_globals_round_trip_through_a_fresh_vm() {
         let mut s = UiScript::new().unwrap();
@@ -299,9 +270,8 @@ mod tests {
             ],
             "registration order, and a re-register is not a second entry"
         );
-        let text = s.saved_variables_text();
-        // The grammar: one statement per line, `nil` written out, integral numbers bare, keys
-        // bracketed and SORTED (integers ascending, then strings), tab-indented, trailing comma.
+        let bytes = s.saved_variables_bytes();
+        let text = String::from_utf8(bytes).expect("every value here is UTF-8");
         assert_eq!(
             text,
             "TRAINER_FILTER_AVAILABLE = 1\n\
@@ -320,7 +290,6 @@ mod tests {
         );
         assert!(s.take_warnings().is_empty(), "nothing was unserializable");
 
-        // A fresh VM (the restart), the file's chunk, and every value is back.
         let fresh = UiScript::new().unwrap();
         fresh.run(&text).unwrap();
         assert_eq!(
@@ -346,8 +315,6 @@ mod tests {
             .unwrap());
     }
 
-    /// A value with no Lua literal is skipped and named, never written as something that would
-    /// break the next load — the one place we improve on the reference, which loses these silently.
     #[test]
     fn unserializable_values_are_skipped_with_one_warning() {
         let mut s = UiScript::new().unwrap();
@@ -365,13 +332,37 @@ mod tests {
         "#,
         )
         .unwrap();
-        let text = s.saved_variables_text();
+        let text = s.saved_variables_bytes();
         // The cycle's own entry drops; the table itself still writes (empty here).
-        assert_eq!(text, "KEPT = 7\nCYCLE = {\n}\n", "got:\n{text}");
+        assert_eq!(text, b"KEPT = 7\nCYCLE = {\n}\n");
         let warns = s.take_warnings();
         assert_eq!(warns.len(), 1, "one line, not one per name: {warns:?}");
         assert!(warns[0].contains("A_FUNCTION") && warns[0].contains("NOT_A_NUMBER"));
-        // And what it wrote is loadable.
-        UiScript::new().unwrap().run(&text).unwrap();
+        UiScript::new().unwrap().run_chunk(&text).unwrap();
+    }
+
+    #[test]
+    fn a_byte_string_that_is_not_utf8_round_trips_unchanged() {
+        let s = UiScript::new().unwrap();
+        s.run(
+            r#"
+            PACKED = string.char(65, 200, 255, 0, 66)
+            KEYS = { [string.char(200)] = 1, [string.char(201)] = 2 }
+            RegisterForSave("PACKED")
+            RegisterForSave("KEYS")
+        "#,
+        )
+        .unwrap();
+        let fresh = UiScript::new().unwrap();
+        fresh.run_chunk(&s.saved_variables_bytes()).unwrap();
+        assert!(fresh
+            .eval::<bool>(
+                "return string.len(PACKED) == 5 and string.byte(PACKED, 2) == 200 \
+                 and string.byte(PACKED, 3) == 255 and string.byte(PACKED, 4) == 0"
+            )
+            .unwrap());
+        assert!(fresh
+            .eval::<bool>("return KEYS[string.char(200)] == 1 and KEYS[string.char(201)] == 2")
+            .unwrap());
     }
 }
diff --git a/crates/benilla-ui/src/script/screenshot.rs b/crates/benilla-ui/src/script/screenshot.rs
index 7a69c3ee..091d0330 100644
--- a/crates/benilla-ui/src/script/screenshot.rs
+++ b/crates/benilla-ui/src/script/screenshot.rs
@@ -1,25 +1,13 @@
-//! **`Screenshot()`** — the engine verb behind the print-screen key (decision 1487).
-//!
-//! One global and one counter. The reference's binding is `SCREENSHOT` → `TakeScreenshot()`
-//! (FrameXML `Bindings.xml`), whose body hides the status text and then calls this engine
-//! function; the engine answers later with `SCREENSHOT_SUCCEEDED` or `SCREENSHOT_FAILED`, which
-//! is what puts "Screen Captured" on screen. **The answer is an EVENT, never a return value** —
-//! and that is the whole mechanism that keeps the message out of the file it announces: the
-//! capture is already taken by the time anything can say so.
-//!
-//! A **count**, like [`super::client`]'s `RequestTimePlayed` and `ConfirmBinder`: the request
-//! carries no payload (the app owns the window, the folder and the clock), so two calls in a frame
-//! are two captures rather than one collapsed intent. The app drains it in
-//! [`crate::script::UiScript::take_screenshot_asks`].
+//! `Screenshot()`, the engine verb behind the print-screen key: the `SCREENSHOT` binding calls
+//! `TakeScreenshot()` (`WorldFrame.lua:46`), which hides the status text and calls this. It
+//! returns nothing; the outcome arrives later as `SCREENSHOT_SUCCEEDED` or `SCREENSHOT_FAILED`,
+//! so the "Screen Captured" message never lands in the capture.
 
 use mlua::Lua;
 
 use super::Model;
 
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // `Screenshot()` — take one. Returns nothing: the reference's does not either, because the
-    // capture completes after the frame that asked for it and the outcome arrives as
-    // SCREENSHOT_SUCCEEDED / SCREENSHOT_FAILED.
     lua.globals().set(
         "Screenshot",
         lua.create_function(|lua, ()| {
@@ -33,8 +21,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 }
 
 impl super::UiScript {
-    /// Drain the `Screenshot()` calls queued since the last call — each one is one capture.
-    /// [`super::UiScript::take_played_time_asks`]'s shape, for the same reason.
+    /// `Screenshot()` calls since the last drain, each one capture.
     pub fn take_screenshot_asks(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().screenshot_asks)
     }
diff --git a/crates/benilla-ui/src/script/scrollframe.rs b/crates/benilla-ui/src/script/scrollframe.rs
index dc24cd7e..c4470781 100644
--- a/crates/benilla-ui/src/script/scrollframe.rs
+++ b/crates/benilla-ui/src/script/scrollframe.rs
@@ -1,32 +1,9 @@
-//! The `ScrollFrame` method surface (`CSimpleScrollFrame`) — the ScrollFrame mechanism (decision
-//! 0112, the engine's last structural gap): `SetScrollChild`/`GetScrollChild`, the two scroll
-//! offsets (`Set`/`GetVerticalScroll`, `Set`/`GetHorizontalScroll`), and the live ranges
-//! (`Get{Vertical,Horizontal}ScrollRange`/`UpdateScrollChildRect`). The offset setters and the
-//! ranges are byte-pinned (decisions 1338, 2017): `0x786db0` stores the offset VERBATIM — the
-//! engine never clamps it — and `0x786e30` measures both ranges off the scroll child's subtree. The
-//! rest is spec-faithful to the documented widget contract (the Era `ScrollFrameTemplate` Lua
-//! drives its scrollbar off exactly these), same posture as StatusBar's fill.
-//!
-//! **The two axes are one mechanism, not a mechanism and a special case.** The reference's nine
-//! ScrollFrame bindings are four symmetric pairs plus `UpdateScrollChildRect`, and the C++ under
-//! them is literally cloned: `0x786d30` (horizontal) is the byte-clone of `0x786db0` (vertical)
-//! against `[+0x324]`/`[+0x32c]` instead of `[+0x328]`/`[+0x334]`, and one `0x786e30` computes
-//! both ranges out of one subtree union (wow-re `scrollframe-offset-and-range-law.md`). This module
-//! is written that way too — one helper per concept, taken on the axis asked for. That the
-//! horizontal half went unwritten until the corpus asked for it (`aux-addon` reads and writes both
-//! axes in one function) is why this doc used to say horizontal scroll "is out of scope: no 1.12
-//! template drives it" — true of the stock templates, and never true of the addons.
-//!
-//! The actual geometry — the scroll child's anchors pinned to the frame + the scroll offsets, and
-//! the clip every descendant of the child draws/hits within — lives in [`super::mod@super`]'s
-//! `resolve`/`extract`/`hit_test` (the layout-graph override + the ancestor-walk clip helper); this
-//! module is the thin Lua binding over the per-frame [`ScrollFrameState`], plus the three script
-//! hooks (`OnVerticalScroll`/`OnHorizontalScroll`/`OnScrollRangeChanged`) a scrollbar's
-//! `OnValueChanged`/`OnLoad` wires to.
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for ScrollFrame frames — so duck-typing addons (`if frame.SetScrollChild then …`) see `nil` on
-//! every other kind, exactly as against the client's per-class method sets.
+//! The `ScrollFrame` methods (`CSimpleScrollFrame`): the scroll child, the two offsets, the two
+//! ranges and `UpdateScrollChildRect`, over [`ScrollFrameState`]; the layout's `resolve`,
+//! `extract` and `hit_test` place and clip the child. The axes are one mechanism: `0x786d30`
+//! (horizontal) is a byte-clone of `0x786db0` (vertical) on `[+0x324]`/`[+0x32c]` for
+//! `[+0x328]`/`[+0x334]`, and `0x786e30` measures both ranges in one pass. The methods sit in
+//! their own table, so on every other frame kind `SetScrollChild` is nil, as in the client.
 
 use mlua::{Lua, Table, Value};
 
@@ -34,12 +11,11 @@ use super::object::{decode_id, frame_handle_of, frame_wrapper};
 use super::{event, Model};
 use crate::widget::{FrameHandle, KindState, ScrollFrameState};
 
-/// Registry key of the ScrollFrame method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the ScrollFrame method table.
 pub(super) const REG_SCROLLFRAME_METHODS: &str = "__benilla_scrollframe_methods";
 
-/// Run `f` over a frame's ScrollFrame state under one short write borrow. Errors if `this` is not a
-/// live ScrollFrame (unreachable through the kind dispatcher, but the method table is a plain Lua
-/// value — a caller could fish it out and misapply it).
+/// Run `f` over a frame's ScrollFrame state; errors when `this` is not a live ScrollFrame, which a
+/// script reaches only by applying a method taken off the table to another frame.
 fn with_scroll<T>(
     lua: &Lua,
     this: &Table,
@@ -57,48 +33,21 @@ fn with_scroll<T>(
     }
 }
 
-/// Which axis a scroll offset, span or range is taken on.
-///
-/// One type rather than two code paths, because the reference computes both ranges in ONE pass
-/// over ONE subtree union (`0x786e30`: `[+0x31c] = max(0, maxRIGHT − minLEFT − width) / scale`,
-/// `[+0x320] = max(0, maxTOP − minBOTTOM − height) / scale`) — the axes differ only in which pair
-/// of edges the union tracks and which frame dimension is subtracted.
+/// The axis of an offset or a range. `0x786e30` computes both ranges in one pass over one subtree
+/// union: `[+0x31c] = max(0, maxRIGHT − minLEFT − width) / scale`, and `[+0x320]` the same with
+/// top, bottom and height.
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum Axis {
-    /// `maxRIGHT − minLEFT` against the frame's width — `GetHorizontalScrollRange`, `[+0x31c]`.
     Horizontal,
-    /// `maxTOP − minBOTTOM` against the frame's height — `GetVerticalScrollRange`, `[+0x320]`.
     Vertical,
 }
 
-/// `Get{Vertical,Horizontal}ScrollRange()`'s live computation: `max(0, contentExtent − frameExtent)`
-/// from the **resolved** rects — `0.0` when the frame is unresolved or there is no child. Never
-/// cached: the scroll offset always clamps against the current layout, not a stale snapshot.
-///
-/// **The content extent is the scroll child's whole SUBTREE, not the child frame's own height**
-/// (wow-re `system/ui/scratch/simplehtml-markup-engine.md` §4.5, byte-identified during the
-/// SimpleHTML RE; decision 1338 corrects what 0112 shipped). `0x786e30` seeds a bounding box
-/// `{FLT_MAX, FLT_MAX, 0, 0}` and calls the **recursive** `0x786f80(scrollChild, &bbox)`, which
-/// unions the frame's REGION list (head `+0x1b4`, link `+0x1b8`, guard `[entry+8]+0xc4`) and
-/// re-enters itself for every CHILD FRAME (head `+0x2fc`, link `+0x300`, guard `[entry+8]+0xd0`);
-/// the range stored at `[+0x31c]` is `max(0, bboxExtent − viewportExtent)`.
-///
-/// The distinction is not academic: stock `ItemTextPageScrollChild` is declared **10×10**
-/// (`ItemTextFrame.xml` l.198) around a 270×304 SimpleHTML whose blocks extend well past it.
-/// Measured as the child's own height the range is zero and a book cannot be scrolled at all;
-/// measured as the subtree box it tracks the rendered text. Every ScrollFrame whose child is sized
-/// directly — the guild-info EditBox, the options panes, every faux list — is unchanged, because
-/// there its own rect already IS its subtree.
-///
-/// In **LOCAL units**, each extent divided by the owning frame's effective scale — i.e. exactly
-/// `child:GetHeight() - self:GetHeight()`, the widget contract this method states. The resolved
-/// rects are screen px, and the scroll offset is NOT: `SetVerticalScroll` becomes the scroll
-/// child's anchor y-offset, which the solver multiplies by that child's scale (`resolve`'s
-/// override; `anchor_resolve_y`). Reporting a screen-px range against a local-unit offset makes
-/// every SCALED ScrollFrame under-scroll by exactly its scale — the bar's max is the range, so it
-/// stops short of the end and the tail of the content is unreachable. Invisible at scale 1.0,
-/// which is every 1.12-native window; the era-scaled options window (ERA_WINDOW_SCALE 0.78) is the
-/// first real-scroll customer that isn't, and it lost 22% of its travel.
+/// `Get{Vertical,Horizontal}ScrollRange()`: `max(0, content − frame)` from the resolved rects,
+/// computed on every call, where the reference caches both (`[+0x31c]`, `[+0x320]`) and recomputes
+/// them only once marked dirty. The content is the scroll child's whole subtree, not its own rect
+/// (`0x786e30` calls the recursive `0x786f80`): stock `ItemTextPageScrollChild` is 10×10 around a
+/// 270×304 SimpleHTML (`ItemTextFrame.xml:198`). Each extent is divided by its frame's effective
+/// scale, since the offset is in local units; a range in screen px under-scrolls a scaled frame.
 fn scroll_range(model: &Model, h: FrameHandle, axis: Axis) -> f32 {
     let child = match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::Scroll(s)) => s.child,
@@ -128,13 +77,9 @@ fn scroll_range(model: &Model, h: FrameHandle, axis: Axis) -> f32 {
     ((far - near) / scale_of(child) - viewport).max(0.0)
 }
 
-/// The span of `f`'s subtree along `axis`, in SCREEN px, as `(far, near)` — `(top, bottom)`
-/// vertically, `(right, left)` horizontally — its own resolved rect unioned with every VISIBLE
-/// descendant region and child frame, recursively (`0x786f80`). `None` when nothing in the subtree
-/// resolved.
-///
-/// Visibility is the client's own guard on both lists: a hidden block contributes no scroll range,
-/// which is what stops a window's parked art from inventing travel nobody can use.
+/// The span of `f`'s subtree along `axis` in screen px, as `(far, near)`: its own rect unioned with
+/// its shown regions and visible child frames, recursively (`0x786f80`). Hidden parts add no range:
+/// the client guards both lists on visibility.
 fn subtree_span(model: &Model, f: FrameHandle, axis: Axis) -> Option<(f32, f32)> {
     let edges = |r: &crate::layout::Rect| match axis {
         Axis::Horizontal => (r.right, r.left),
@@ -194,14 +139,12 @@ fn subtree_font_strings(model: &Model, f: FrameHandle) -> Vec<crate::widget::Reg
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // SetScrollChild(frame|name|nil) — a wrapper table or a name string resolves like every other
-    // frame-target arg (SetParent, SetPoint's relativeTo); nil (or an unresolvable target) clears.
+    // SetScrollChild(frame | name | nil): nil or an unresolvable target clears.
     m.set(
         "SetScrollChild",
         lua.create_function(|lua, (this, target): (Table, Value)| {
-            // `_G[name]` before the guard, no `$parent` — `0x790fa0`'s string arm calls `0x76c760`
-            // directly, the same narrow-Frame-tag resolver `SetParent` uses
-            // (`object::NamedTarget`).
+            // A name is `_G[name]` with no `$parent`: `0x790fa0` calls `SetParent`'s resolver
+            // `0x76c760`.
             let named = match &target {
                 Value::String(s) => s
                     .to_str()
@@ -228,8 +171,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 changed
             })?;
             if changed {
-                // The child override is part of the resolve's read set (decision 0112's local
-                // anchor map — a fingerprint input), so a real re-target dirties tier 1.
+                // The child is an input of the layout resolve, so a real change dirties it.
                 lua.app_data_mut::<Model>().expect("model").touch_layout();
             }
             Ok(())
@@ -252,20 +194,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetVerticalScroll(px) — stores the offset VERBATIM and, only when it actually changed,
-    // re-lays the child out and fires OnVerticalScroll(self, offset) — the scrollbar's
-    // OnValueChanged wiring's other half.
-    //
-    // **No clamp** (decision 2017). The reference's `0x786db0` compares the new value against the
-    // OLD one alone (an epsilon change-gate: unchanged → nothing happens, not even the script),
-    // writes it to `[+0x328]`, re-anchors the scroll child off it (`0x787100` →
-    // `SetPoint(child, self, hScroll, vScroll)`) and fires the handler. `[+0x320]` — the range —
-    // is never read on this path. Every clamp the reference exhibits is FrameXML's own, through
-    // the scroll bar's `[min, max]` (`ScrollFrameTemplate_OnMouseWheel`,
-    // `ScrollFrame_OnScrollRangeChanged`). The clamp this carried from 07-05 (a3fce6a76) to 2017
-    // cost every faux list whose frame is taller than `rows × step` its last rows (B370): the
-    // reference's `FauxScrollFrame_Update` drives the bar to `(n − rows) × step`, which is past
-    // `n × step − frameHeight` whenever the frame has slack under its last row.
+    // SetVerticalScroll(px) (`0x786db0`): stores the offset unclamped (`[+0x328]`), re-anchors the
+    // child (`0x787100`) and fires `OnVerticalScroll(self, offset)`, all only on a change; the
+    // reference skips a change under 2⁻²² from the old offset, where this compares bits. The range
+    // is never read here: every clamp is FrameXML's, through the scroll bar's min and max.
     m.set(
         "SetVerticalScroll",
         lua.create_function(|lua, (this, px): (Table, f32)| {
@@ -294,23 +226,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The horizontal axis: the same three verbs on `[+0x324]`/`[+0x31c]` ─────────────────────
-    //
-    // `SetHorizontalScroll(px)` `0x7912f0` → `0x786d30`, which is the BYTE-CLONE of
-    // `SetVerticalScroll`'s `0x786db0` against the horizontal fields (wow-re
-    // `scrollframe-offset-and-range-law.md` §2.2; `item9-firing34-glue786.md` identified the pair).
-    // So every law stated above holds verbatim on this axis: no clamp, the same 2⁻²² change-gate
-    // against the OLD offset alone, the same re-anchor, and `OnHorizontalScroll(self, offset)`
-    // fired only on a real change. Nothing here is a horizontal special case.
-    //
-    // The one thing that IS specific to this axis is the SIGN, and it is the reference's:
-    // `0x787100` passes both offsets to `SetPoint(TOPLEFT, self, TOPLEFT, +hScroll, +vScroll)`
-    // unnegated, so positive x pushes the child right (revealing nothing) where positive y lifts it
-    // (revealing content below). `aux-addon/tabs/search/filter.lua:315-322` — the corpus caller
-    // that made this pair worth writing, reading both axes in one line and writing both in the next
-    // — bounds x into `[min(0, frameWidth - contentWidth - 10), 0]` and y into
-    // `[0, contentHeight - frameHeight]`, which is the same asymmetry read off the other side of
-    // the API. See [`ScrollFrameState::horizontal`].
+    // ── The horizontal axis ──
+    // SetHorizontalScroll(px) (`0x7912f0` → `0x786d30`) is the vertical setter's byte-clone on
+    // `[+0x324]`, firing `OnHorizontalScroll`. The sign is the reference's: `0x787100` anchors the
+    // child at `(+hScroll, +vScroll)`, so a positive x moves it right, where a positive y lifts it.
     m.set(
         "SetHorizontalScroll",
         lua.create_function(|lua, (this, px): (Table, f32)| {
@@ -338,28 +257,17 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(scroll_range(&model, h, Axis::Horizontal))
         })?,
     )?;
-    // UpdateScrollChildRect() — the Era template calls this after resizing its content to re-drive
-    // its scrollbar. Our range is always live (never cached) against the RESOLVED rects — but a
-    // script resize (`child:SetHeight(...)`) lands in `LayoutInput` immediately, while `resolved`
-    // only catches up on the app's own next `resolve()` call (Lua runs before that each tick,
-    // `ui_script/mod.rs`'s drive loop). This is precisely the Era idiom this method exists to
-    // serve — resize the content, then immediately ask for the new range — so a stale `resolved`
-    // would make its very own primary caller see a one-tick-old (often wrong-by-a-lot, e.g. still
-    // "nothing to scroll") answer. Force a fresh resolve first: cheap on a quiet graph (the
-    // fixpoint's own doc — an unrelated resize elsewhere converges in one round), and correctness
-    // here matters more than dodging a resolve pass a caller who wants nothing stale already asked
-    // for by name.
+    // UpdateScrollChildRect(): recomputes both ranges and fires `OnScrollRangeChanged` at once,
+    // where the reference only marks them dirty (`0x791943`) for its next pump, which fires on a
+    // change. A script resize reaches the resolved rects only at the app's next resolve, so this
+    // resolves first.
     m.set(
         "UpdateScrollChildRect",
         lua.create_function(|lua, this: Table| {
             let h = frame_handle_of(lua, &this)?;
-            // The reference derives the range from a child whose text is already laid out — its
-            // measure is synchronous. Ours measures on the metric reads and on the host's
-            // round-trip, which lands a frame later; stock `QuestLog_UpdateQuestDetails` calls
-            // this right after the SetTexts that fill the pane, and read a range of 0 (1944). So
-            // the child's FontStrings are measured here, through the installed measurer, before
-            // the layout that the range reads; with no measurer installed the round-trip fills
-            // them as before.
+            // The reference measures text synchronously and ours lands a frame later, so the
+            // child's FontStrings are measured first: `QuestLog_UpdateQuestDetails` calls this
+            // right after its SetTexts (`QuestLogFrame.lua:458`).
             let strings: Vec<crate::widget::RegionHandle> = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
                 match model.arena.frame(h).map(|f| &f.kind_state) {
@@ -380,18 +288,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 let y_range = scroll_range(&model, h, Axis::Vertical);
                 (model.frame_id(h), x_range, y_range)
             };
-            // That forced resolve can have MOVED sizes — this method exists precisely because the
-            // caller just resized its content — so drain the queue before the range notify: the
-            // reference fires `OnSizeChanged` from `ApplyRect`, i.e. during the layout, not after.
+            // The resolve can move sizes, and the reference fires `OnSizeChanged` during layout, so
+            // those fire before the range notify.
             event::fire_size_changes(lua);
-            // `OnScrollRangeChanged(self, xRange, yRange)` — **horizontal first**, and that order is
-            // byte-derived rather than assumed: at `0x786eff` the vertical result is on top of the
-            // x87 stack, is `fstp`'d first and therefore pushed DEEPEST, so it lands as `arg2`
-            // (wow-re `scrollframe-offset-and-range-law.md` §3.6, where two of the round's own
-            // workers published it the other way round). It is why stock
-            // `UIPanelScrollFrameTemplate` hands `arg2` to `ScrollFrame_OnScrollRangeChanged`.
-            // `arg1` was a hardcoded `0.0` here for as long as there was no horizontal range to
-            // put in it.
+            // `OnScrollRangeChanged(self, xRange, yRange)`: horizontal first (`0x786eff`), which is
+            // why stock passes `arg2` on as the vertical range (`UIPanelTemplates.xml:188`).
             if let Err(e) = event::fire_widget_handler(
                 lua,
                 id,
@@ -403,8 +304,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             ) {
                 lua.app_data_mut::<Model>()
                     .expect("model app_data")
-                    .errors
-                    .push(e.to_string());
+                    .record_script_error(e.to_string());
             }
             Ok(())
         })?,
@@ -414,9 +314,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Fire `On{Vertical,Horizontal}Scroll(self, offset)` (the ScrollFrame's own script slots — the
-/// reference's `[+0x334]`/`[+0x32c]`, fired from the setter clones `0x786db0`/`0x786d30`). Fired
-/// outside any model borrow; errors go to [`Model::errors`] like every other widget handler.
+/// Fire `On{Vertical,Horizontal}Scroll(self, offset)`, the reference's script slots `[+0x334]` and
+/// `[+0x32c]`, outside any model borrow.
 fn fire_scroll(lua: &Lua, this: &Table, script: &str, value: f32) -> mlua::Result<()> {
     let id = {
         let h = frame_handle_of(lua, this)?;
@@ -428,8 +327,7 @@ fn fire_scroll(lua: &Lua, this: &Table, script: &str, value: f32) -> mlua::Resul
     {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
     Ok(())
 }
diff --git a/crates/benilla-ui/src/script/session.rs b/crates/benilla-ui/src/script/session.rs
index 52e80ef9..4b1a7f82 100644
--- a/crates/benilla-ui/src/script/session.rs
+++ b/crates/benilla-ui/src/script/session.rs
@@ -1,83 +1,48 @@
-//! The **session API** (decisions 0674, 1291) — the four exit globals the game menu's Logout and
-//! Exit Game buttons call, the two dialogs' answers to them, and `ReloadUI()`.
-//!
-//! The shape is [`super::duel`]'s: nothing to read, only the outbound half. Each call queues a
-//! [`SessionRequest`] the app drains ([`super::UiScript::take_session_requests`]) and turns into a
-//! packet or a process exit, so the engine keeps no reach into ECS/net (decision 0068 §3).
-//!
-//! What each one means, and where the reference puts it:
-//!
-//! - `Logout()` — ask to leave the world (`CMSG_LOGOUT_REQUEST`; the client's own
-//!   `ClientServices::SendLogout`, wow-re `system/net/ledger.tsv` 0x5ab000). The **server** decides
-//!   whether that is instant or a 20-second countdown, and says so in `SMSG_LOGOUT_RESPONSE`; the
-//!   client's whole job is to narrate the answer, which is the CAMP dialog.
-//! - `Quit()` — the same request, plus a standing intent to end the *process* rather than return to
-//!   character select when the logout completes. That is why Exit Game shows the same countdown
-//!   under a different name (QUIT_TIMER "%d %s until exit").
-//! - `CancelLogout()` — call off either one (`CMSG_LOGOUT_CANCEL`); the server acks with
-//!   `SMSG_LOGOUT_CANCEL_ACK`, which is what fires `LOGOUT_CANCEL` and takes the dialog down.
-//! - `ForceQuit()` — the QUIT dialog's "Exit now": end the process immediately, without waiting out
-//!   the server's clock. (Its logout sibling `ForceLogout()` is deliberately absent: the reference's
-//!   own CAMP dialog has the force button commented out — "uncomment once forced logouts are
-//!   completely implemented (they currently have a failure case)" — so 1.12 ships no way to call it
-//!   from the UI, and neither do we.)
+//! The session verbs: the game menu's Logout and Exit Game, their dialogs' answers, `ReloadUI`
+//! and the cinematic pair. Each queues a [`SessionRequest`] the app turns into a packet or an
+//! exit; the server decides whether a logout is instant or a 20-second countdown.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// Outbound session-exit intents queued by the Era API calls, drained by the app
-/// ([`super::UiScript::take_session_requests`]). Plain data — [`super::DuelRequest`]'s twin.
+/// A session intent queued by a Lua call, drained by the app.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum SessionRequest {
-    /// `Logout()` — leave the world back to character select.
+    /// `Logout()`: `CMSG_LOGOUT_REQUEST` (`0x5ab000`), back to character select.
     Logout,
-    /// `Quit()` — leave the world and end the process once it completes.
+    /// `Quit()`: the same request, then the process ends once the logout completes.
     Quit,
-    /// `CancelLogout()` — call off a pending logout or quit.
+    /// `CancelLogout()`: `CMSG_LOGOUT_CANCEL`; the server's ack fires `LOGOUT_CANCEL`.
     CancelLogout,
-    /// `ForceQuit()` — end the process now, no server round trip.
+    /// `ForceQuit()`: end the process now, with no server round trip.
     ForceQuit,
-    /// `ForceLogout()` — the session dispatcher with `force = 1`: `CMSG_PLAYER_LOGOUT` (`0x4A`,
-    /// empty) instead of `Logout`'s `0x4B`, the pending-logout latch bypassed, and nothing at all
-    /// without a live in-world session (decision 1963; wow-re `staticpopup-dialog-bindings.md`
-    /// §4).
+    /// `ForceLogout()` (`0x48ab50`): an empty `CMSG_PLAYER_LOGOUT` (`0x4A`), bypassing the
+    /// pending-logout latch, and nothing without a live in-world session (`0x5ab020`).
     ForceLogout,
-    /// `ReloadUI()` — tear this VM down and build a fresh one, without leaving the world.
-    ///
-    /// The reference's `ReloadUI 0x4884d0` reads no arguments and returns no values; it only sets
-    /// `ds:0xb4b3f4`, and the per-frame callback `0x495590` runs the teardown/rebuild pair
-    /// (`0x490bd0` → `0x48fbf0`) on the NEXT frame — a deferral that doubles as the reentrancy
-    /// guard: the Lua state being destroyed is never the one mid-way through executing the call.
-    /// Queuing an intent the app runs outside any VM call is that same guard in this engine's
-    /// shape (wow-re `system/ui/scratch/savedvariables-protocol.md` §2, byte-verified).
+    /// `ReloadUI()` (`0x4884d0`) only sets `0xb4b3f4`; the next frame's `0x495590` tears the VM
+    /// down and rebuilds it, so it is never destroyed mid-call. The app's drain, outside any call,
+    /// is the same guard.
     ReloadUi,
-    /// `StopCinematic()` — skip the cinematic that is playing.
-    ///
-    /// **The only skip path there is.** In the reference this binding (`0x48b970`) has *zero*
-    /// native callers: nothing in the engine calls it, and it is absent from `Bindings.xml`, so
-    /// ESC reaches it purely through `CinematicFrame`'s own `OnKeyDown` handler while that
-    /// fullscreen frame holds keyboard focus. A cinematic with no `CinematicFrame` on screen is
-    /// therefore un-skippable — which is why benilla starts playback only once the in-game UI
-    /// exists.
+    /// `StopCinematic()` (`0x48b970`), the only skip: no native caller and no binding, so ESC
+    /// reaches it only through `CinematicFrame`'s `OnKeyDown`; playback therefore waits for the
+    /// in-game UI.
     StopCinematic,
 }
 
 impl super::UiScript {
-    /// Drain the session-exit intents queued since the last call.
+    /// Drain the session intents queued since the last call.
     pub fn take_session_requests(&mut self) -> Vec<SessionRequest> {
         std::mem::take(&mut self.model_mut().session_requests)
     }
 
-    /// Queue an intent from the app side — the `/logout` and `/camp` slash commands, which benilla
-    /// parses in Rust rather than through `SlashCmdList` (the [`super::UiScript::queue_duel_request`]
-    /// posture), so they enter the same queue and get the same dialog.
+    /// Queue an intent from the app: `/logout`, `/camp`, `/quit` and `/reload`, which benilla
+    /// parses in Rust rather than through `SlashCmdList`, take their Lua verbs' route this way.
     pub fn queue_session_request(&mut self, request: SessionRequest) {
         self.model_mut().session_requests.push(request);
     }
 }
 
-/// Register the session globals — the four exit verbs, `ReloadUI`, and the cinematic skip.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -100,9 +65,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // `InCinematic()` — the reference's `0x48c930`: reads the "a cinematic is playing" global and
-    // answers the **number 1** while one is, `nil` otherwise (both legs push exactly one result).
-    // Era convention, not `true`/`false`.
+    // `0x48c930`: the number 1 while a cinematic plays, else nil, one result either way.
     g.set(
         "InCinematic",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/shapeshift.rs b/crates/benilla-ui/src/script/shapeshift.rs
index 45b4ccef..6a5b2c9c 100644
--- a/crates/benilla-ui/src/script/shapeshift.rs
+++ b/crates/benilla-ui/src/script/shapeshift.rs
@@ -1,58 +1,40 @@
-//! The shapeshift/stance bar seam — the ref's four bindings
-//! (`GetNumShapeshiftForms`/`GetShapeshiftFormInfo`/`GetShapeshiftFormCooldown`/
-//! `CastShapeshiftForm`, consumed by `BonusActionBarFrame.lua`'s `ShapeshiftBar_*` family) over
-//! an app-pushed form list, the [`super::spellbook`]/[`super::action`] two-way shape: the app
-//! resolves everything (which known spells are forms, their icon/name/active/castable/cooldown —
-//! the wow-re-pinned mechanism lives app-side), pushes a snapshot
-//! ([`super::UiScript::set_shapeshift_forms`]), and drains the click intents
-//! ([`super::UiScript::take_shapeshift_casts`]) onto the wire. The engine holds no form
-//! KNOWLEDGE — a form is "a spell id, a texture, a name, two bits, and a cooldown triple".
-//!
-//! Return conventions are the 1.12 API's own, matching [`super::action`]: 1/nil booleans, and
-//! the cooldown pushed as `(start_ms on the GetTime clock, duration_ms, enabled)` (the
-//! [`super::action::ActionState::cooldown`] pattern — absolute start, app-converted at feed
-//! time) so `GetShapeshiftFormCooldown` answers the ref's `(start, duration, enable)`.
+//! The stance bar's four bindings, which `BonusActionBarFrame.lua`'s `ShapeshiftBar_*` calls, over
+//! a form list the app resolves and pushes; flags answer 1/nil and the cooldown is the reference's
+//! `(start, duration, enable)`.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One stance-bar button, fully resolved by the app before pushing.
+/// One stance-bar button, resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ShapeshiftFormView {
-    /// The form spell (the app resolves a queued cast/cancel from it at drain time).
+    /// The form spell a click queues.
     pub spell_id: u32,
     /// The icon texture path; `None` shows the slot's fallback.
     pub texture: Option<String>,
-    /// The spell name (`GetShapeshiftFormInfo`'s second return — the ref's tooltip/debug read).
+    /// The spell name, `GetShapeshiftFormInfo`'s second return.
     pub name: String,
-    /// This form is the player's CURRENT form (the checked ring).
+    /// The player's current form (the checked ring).
     pub active: bool,
-    /// Castable right now (the ref greys the icon 0.4 when not).
+    /// Castable now; the reference greys the icon to 0.4 when not.
     pub castable: bool,
-    /// The form spell's cooldown as `(start_ms on the GetTime clock, duration_ms, enabled)`
-    /// ([`super::action::ActionState::cooldown`]'s exact shape); `None` = no cooldown.
+    /// `(start_ms on the GetTime clock, duration_ms, enabled)`, as an action's cooldown.
     pub cooldown: Option<(i64, u32, bool)>,
 }
 
-/// [`ShapeshiftFormView`] as stored: the cooldown converted to the `GetTime` clock at push time
-/// (the [`super::action::StoredActionState`] pattern).
+/// A pushed form with its cooldown in `GetTime` seconds.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct StoredShapeshiftForm {
     pub(crate) view: ShapeshiftFormView,
-    /// `(start_s, duration_s, enabled)` in `GetTime` seconds; `None` = no cooldown.
+    /// `(start_s, duration_s, enabled)`.
     pub(crate) cooldown: Option<(f64, f64, bool)>,
 }
 
 impl super::UiScript {
-    /// Push the whole form list (bar order = list order), replacing whatever was there. A bare
-    /// setter — firing `UPDATE_SHAPESHIFT_FORMS` (and the state-refresh events the transcribed
-    /// bar listens to) is the app's own diff-and-fire job, mirroring `set_spellbook`.
+    /// Replace the form list, in bar order; the app fires `UPDATE_SHAPESHIFT_FORMS` itself.
     pub fn set_shapeshift_forms(&mut self, forms: Vec<ShapeshiftFormView>) {
         let mut model = self.model_mut();
-        // The cooldown arrives with its absolute start already on the `GetTime` clock (ms) —
-        // storing is a pure unit conversion, the same seam shape as
-        // [`super::UiScript::set_action_state`].
         model.shapeshift_forms = forms
             .into_iter()
             .map(|view| {
@@ -68,21 +50,20 @@ impl super::UiScript {
             .collect();
     }
 
-    /// Drain the form spell ids `CastShapeshiftForm` queued since the last call. Whether a queued
-    /// id becomes a cast or a cancel (clicking the ACTIVE form) is the app's call at drain time.
+    /// Drain the form spells `CastShapeshiftForm` queued; the app casts each, or cancels it when it
+    /// is the active form.
     pub fn take_shapeshift_casts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().shapeshift_casts)
     }
 }
 
-/// The 1-based button index → stored form, the ref's own indexing.
+/// A 1-based button index, as the reference indexes.
 fn form_at(model: &Model, i: u32) -> Option<&StoredShapeshiftForm> {
     usize::try_from(i.checked_sub(1)?)
         .ok()
         .and_then(|n| model.shapeshift_forms.get(n))
 }
 
-/// Register the shapeshift globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -94,8 +75,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetShapeshiftFormInfo(i) → texture, name, isActive (1/nil), isCastable (1/nil); out of
-    // range → a single nil (the spellbook bindings' out-of-range shape).
     g.set(
         "GetShapeshiftFormInfo",
         lua.create_function(|lua, i: u32| {
@@ -117,9 +96,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetShapeshiftFormCooldown(i) → start, duration, enable — GetActionCooldown's exact triple
-    // and elapsed-goes-cold rule (an elapsed/absent cooldown answers (0, 0, 1) so a re-feed never
-    // replays the sweep).
+    // As `GetActionCooldown`: an elapsed or absent cooldown answers `(0, 0, 1)`, so a re-feed never
+    // replays the sweep.
     g.set(
         "GetShapeshiftFormCooldown",
         lua.create_function(|lua, i: u32| {
@@ -134,7 +112,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CastShapeshiftForm(i) — queues the form's spell id; an out-of-range index is a no-op.
     g.set(
         "CastShapeshiftForm",
         lua.create_function(|lua, i: u32| {
@@ -154,8 +131,6 @@ mod tests {
     use super::ShapeshiftFormView;
     use crate::script::UiScript;
 
-    /// A warrior mid-career: Battle Stance (active, castable), Defensive Stance (castable, on a
-    /// 1.5 s cooldown started at GetTime 9.4 s).
     fn forms() -> Vec<ShapeshiftFormView> {
         vec![
             ShapeshiftFormView {
@@ -200,7 +175,6 @@ mod tests {
                 Some(1)
             )
         );
-        // Form 2: not active (nil), castable (1).
         assert!(s
             .eval::<bool>("local _, _, a, c = GetShapeshiftFormInfo(2) return a == nil and c == 1")
             .unwrap());
@@ -215,13 +189,11 @@ mod tests {
         s.tick(10.0); // GetTime == 10
         s.set_shapeshift_forms(forms());
 
-        // No cooldown → the cold (0, 0, 1).
         assert_eq!(
             s.eval::<(f64, f64, i32)>("return GetShapeshiftFormCooldown(1)")
                 .unwrap(),
             (0.0, 0.0, 1)
         );
-        // The pushed absolute start (9400 ms) reads back verbatim in seconds.
         let (start, duration, enable) = s
             .eval::<(f64, f64, i32)>("return GetShapeshiftFormCooldown(2)")
             .unwrap();
@@ -229,7 +201,6 @@ mod tests {
         assert!((duration - 1.5).abs() < 1e-9);
         assert_eq!(enable, 1);
 
-        // Past the end the read goes cold.
         s.tick(2.0); // now == 12 > 9.4 + 1.5
         assert_eq!(
             s.eval::<(f64, f64, i32)>("return GetShapeshiftFormCooldown(2)")
diff --git a/crates/benilla-ui/src/script/simplehtml/mod.rs b/crates/benilla-ui/src/script/simplehtml/mod.rs
index 0a9f683b..af8870f6 100644
--- a/crates/benilla-ui/src/script/simplehtml/mod.rs
+++ b/crates/benilla-ui/src/script/simplehtml/mod.rs
@@ -1,63 +1,23 @@
-//! The **`SimpleHTML` widget** (`CSimpleHTML`, class size `0x374`, ctor `0x789dd0`) — its markup
-//! engine, its block layout, its four element fonts, and its 19-entry Lua method table.
+//! The `SimpleHTML` widget (`CSimpleHTML`, size `0x374`, ctor `0x789dd0`): the blocks [`parse`]
+//! produces, built as regions, its four element fonts, and its Lua method table.
 //!
-//! Ground truth: wow-5875-re `system/ui/scratch/simplehtml-markup-engine.md` (a §5 trio plus the
-//! orchestrator's own byte read and arbitration). The parse itself is [`parse`]; this module is
-//! the half that touches the model — turning a block list into real FontString/Texture regions
-//! anchored bottom-to-top, and exposing the widget's Lua surface.
+//! `SetText` drops the previous blocks and builds the parsed ones. A text block is a FontString at
+//! the frame's declared width with no height; block 0 hangs from the frame's TOPLEFT and block N
+//! from block N-1's BOTTOMLEFT, `spacing` lower (0 by default).
 //!
-//! ## What the widget is, in one paragraph
+//! A block is LEFT unless its `align` says otherwise, never the FontString ctor's CENTER
+//! (`0x78a7c8`, `0x78ae78`). An element font starts empty, and `H1` to `H3` use `P`'s while their
+//! path is empty (`0x78ae30`), with no header scaling. There is no `GetContentHeight`: the hosting
+//! ScrollFrame measures the blocks as regions (`0x786e30`).
 //!
-//! `SetText(s)` throws away every block of the previous parse, runs `s` through a **strict XML**
-//! parser, and — if and only if the document is well-formed, rooted at `HTML`, and has a `BODY`
-//! child — walks that BODY emitting one block per `<H1>`/`<H2>`/`<H3>`/`<P>`/`<BR/>`/`<IMG>`.
-//! Anything else falls to the plain-text path: the **raw** string as one `P` block, left-aligned,
-//! whitespace intact. Each text block is one `CSimpleFontString` at the frame's declared width
-//! with **no height set**, so its rect is the intrinsic height of the wrapped text; block 0 hangs
-//! from the frame's TOPLEFT and block *N* from block *N−1*'s BOTTOMLEFT at `−spacing`. Spacing
-//! defaults to 0, so blocks are flush.
+//! Deviation: the block step is not pixel-snapped (`0x766750`), because layout here is in logical
+//! units; the two differ by under a pixel, and not at all at the default spacing of 0. Line spacing
+//! inside a block is not applied, as nothing here models line spacing; `SetSpacing` sets the step
+//! between blocks. Deviation: a block of width 0, in a frame sized by anchors, gets its text's
+//! natural width where the reference keeps 0, because every width-less FontString here does.
 //!
-//! ## Three defaults a re-implementation gets wrong, and this one does not
-//!
-//! - **Block justifyH is LEFT**, never the `CSimpleFontString` ctor's CENTER: `align` is
-//!   pre-loaded with `1` before the attribute is read (`0x78a7c8`) and `0x78ae78` writes it into
-//!   the block after `SetFontObject`, so the element font's own `justifyH` can never reappear.
-//! - **Element fonts start with no font at all**, and `H1`/`H2`/`H3` fall back to `P`'s whenever
-//!   their own resolved path is empty (`0x78ae30` measures `SStr::Length(&font->path)`). **Nothing
-//!   in this TU scales a header** — no height multiply, no size table — so an `<H1>` under a
-//!   single `<FontString>` declaration renders at exactly the `<P>` size. That is the reference
-//!   `ItemTextFrame` render, not an approximation of it.
-//! - **`GetContentHeight` does not exist in 1.12.1.** The method table has no height getter and
-//!   nothing in the TU aggregates one; the hosting ScrollFrame measures the subtree generically
-//!   instead (§4.5), which is what ours does too — the blocks are real regions of the SimpleHTML,
-//!   so `GetVerticalScrollRange` sees them without SimpleHTML publishing anything.
-//!
-//! ## Where this diverges from the note, deliberately
-//!
-//! - **`nextYOffset` is not pixel-snapped.** The reference stores
-//!   `−pixelSnap(spacing)` (`0x766750`, quantising to whole *device* pixels). Our layout is in
-//!   logical units and the solver has no device-pixel quantiser to reach for; at the default
-//!   spacing of 0 the two agree exactly, and at any other value they differ by under a pixel.
-//! - **Intra-block line spacing is not modelled**, because nothing in this engine models line
-//!   spacing at all (see `script::font_block`'s own note on the withheld `Set/GetSpacing`). What
-//!   `SimpleHTML:SetSpacing` *does* honour here is the half SimpleHTML itself owns and computes:
-//!   the inter-block step. That is a real, drawn effect rather than a stored-and-ignored number,
-//!   which is why this pair ships where the FontString/Font ones do not.
-//! - **A block's wrap width of 0** (a SimpleHTML sized only by anchors) lets the measure
-//!   round-trip supply the natural text width, where the reference leaves the block at width 0.
-//!   That is this engine's standing law for every height-less/width-less FontString, and inverting
-//!   it here would make a SimpleHTML the one widget whose text vanishes when it is anchor-sized.
-//!
-//! ## The Lua table, and the one name that is NOT on it
-//!
-//! §5.1 dumps `.data 0x87ba80` as **19 `{name, fn}` pairs**, and all 19 are installed here. The
-//! first sixteen take an **optional leading element-name string** resolved by `0x795d80`; the last
-//! three (`SetText`, `SetHyperlinkFormat`, `GetHyperlinkFormat`) do not.
-//!
-//! **There is no `GetText`.** Later clients grew one; build 5875's table does not have it, and
-//! adding a name a table does not carry is exactly as wrong as missing one (`script::font_block`'s
-//! module doc states the same law for the font block). A caller that wants the source string keeps
-//! it — the reference's own `ItemTextFrame` calls `ItemTextGetText()`.
+//! The method table (`0x87ba80`) has 19 entries, all installed; the first sixteen take an optional
+//! leading element name (`0x795d80`). Build 5875 has no `GetText`.
 
 use std::collections::HashMap;
 
@@ -75,30 +35,22 @@ mod parse;
 pub(crate) use parse::Block;
 use parse::{ELEMENT_NAMES, ELEM_P};
 
-/// Registry key of the SimpleHTML method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the SimpleHTML method table (the MAXCSTACK discipline).
 pub(super) const REG_SIMPLEHTML_METHODS: &str = "__benilla_simplehtml_methods";
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// State
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── State ────────────────────────────────────────────────────────────────────────────────────
 
-/// One of the four **element fonts** (`CSimpleHTML+0x350`…`+0x35c`, index `0 = P, 1 = H1, 2 = H2,
-/// 3 = H3`), each a `0x80`-byte subclass of `CSimpleFont` the ctor loop `0x789e61`–`0x789ea3`
-/// allocates.
-///
-/// Modelled as "the named object it points at, plus the properties it set for itself" rather than
-/// as a flattened snapshot, so a later `GameFontNormal:SetFont(…)` reaches the *next* parse — the
-/// live `parentFontObject` link the real `CFontInstance` carries. The explicit mask is the same
-/// `FONTINSTANCE+0x038` severance record a region keeps ([`super::FontExplicit`]); reusing it is
-/// what lets a block inherit the mask and stay correct under `script::font::propagate`.
+/// One of the four element fonts (`CSimpleHTML+0x350`, P, H1, H2, H3; made at
+/// `0x789e61`-`0x789ea3`): the font object it inherits, a live link as the reference's
+/// `parentFontObject` is, plus what it set itself.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct ElementFont {
-    /// `inherits=` / `SetFontObject(elem, obj)` — the object this element resolves through.
+    /// `inherits=` or `SetFontObject`: the object this element resolves through.
     pub(crate) font_object: Option<String>,
-    /// Which properties this element set for **itself** (and so must survive a re-read of the
-    /// object above).
+    /// What this element set itself, the region's severance mask (`FONTINSTANCE+0x038`), which a
+    /// block inherits.
     pub(crate) explicit: super::FontExplicit,
-    /// `FieldBlock.path +0x3c`, ctor `""` — the field `0x78ae30` measures for the H1→P fallback.
+    /// `+0x3c`, empty at the ctor: the path `0x78ae30` tests for the fallback to `P`.
     pub(crate) font_path: Option<String>,
     /// `FieldBlock` height.
     pub(crate) font_height: Option<f32>,
@@ -108,26 +60,21 @@ pub(crate) struct ElementFont {
     pub(crate) color: Option<[f32; 4]>,
     /// `SetShadowColor`/`SetShadowOffset` / `<Shadow>`.
     pub(crate) shadow: Option<FontShadow>,
-    /// `CSimpleFont+0x54`, ctor `0x212` (`0x783a98`) — CENTER | MIDDLE | the one-to-one bit.
+    /// `CSimpleFont+0x54`, ctor `0x212` (`0x783a98`): CENTER, MIDDLE and the one-to-one bit.
     pub(crate) justify: Justify,
-    /// `FieldBlock.spacing +0x50`, ctor **0** (`0x783a81`). Both the inter-block step
-    /// (`nextYOffset = −pixelSnap(spacing)`) and, in the reference, the intra-block line gap.
+    /// `+0x50`, ctor 0 (`0x783a81`): the step between blocks and, in the reference, the line gap.
     pub(crate) spacing: f32,
 }
 
-/// A `SimpleHTML` frame's runtime state — the members `CSimpleHTML` adds over `CSimpleFrame`.
-///
-/// Held in a [`Model`]-side map rather than in [`crate::widget::KindState`] for the reason
-/// `Model::backdrops` is: its contents are script-layer types ([`FontObject`], [`FontShadow`],
-/// [`Outline`]), and `widget::kinds` is the layer *below* `script` and does not depend on it.
+/// A `SimpleHTML` frame's state, the members `CSimpleHTML` adds; in a [`Model`] map, not
+/// [`crate::widget::KindState`], because it holds script-layer types.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) struct SimpleHtmlState {
-    /// `+0x350`…`+0x35c`.
+    /// `+0x350` to `+0x35c`.
     pub(crate) fonts: [ElementFont; 4],
     /// `+0x360`, ctor `"|H%s|h%s|h"` (`0x87a838`).
     pub(crate) hyperlink_format: String,
-    /// The CONTENTNODE list `+0x340` — every region the last `SetText` built, in emission order,
-    /// text blocks and images alike. This is the free list the next `SetText` walks.
+    /// The content list (`+0x340`): every region the last `SetText` built, freed by the next.
     pub(crate) blocks: Vec<RegionHandle>,
 }
 
@@ -141,9 +88,8 @@ impl Default for SimpleHtmlState {
     }
 }
 
-/// The paint one block copies out of its element font — the result of `CFontInstance::
-/// SetFontObject 0x770c60`, which forces all five property groups changed (`0x770d06 or …,0x1F`)
-/// and pulls immediately, with the element's own explicit sets layered back on top.
+/// The paint a block copies from its element font: `SetFontObject` (`0x770c60`) pulls all five
+/// property groups at once (`0x770d06`), with the element's own sets on top.
 #[derive(Clone, Debug, Default)]
 struct BlockPaint {
     font_object: Option<String>,
@@ -208,17 +154,13 @@ fn resolve_font(model: &Model, ef: &ElementFont) -> BlockPaint {
     p
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// SetText — the rebuild
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── SetText, the rebuild ─────────────────────────────────────────────────────────────────────
 
-/// `CSimpleHTML::SetText 0x78a3a0`, whole: free the old blocks, parse, and build the new ones.
-///
-/// Returns `usedMarkup` (`0x78a519`'s `al`) — the Lua shim discards it, our tests do not.
+/// `CSimpleHTML::SetText` (`0x78a3a0`): free the old blocks, parse, build. Returns `usedMarkup`
+/// (`0x78a519`), which the Lua shim drops.
 pub(crate) fn set_text(model: &mut Model, fh: FrameHandle, raw: &str) -> bool {
-    // §10 step 1. The reference pool-frees the previous parse's widgets; ours must too, or a
-    // second `SetText` leaves the first one's FontStrings standing behind the new ones — the
-    // failure a book with a "next page" button hits on its very first turn.
+    // Free the previous parse's regions first, as the reference does, or a book's next page
+    // draws over the last.
     let old = model
         .simple_html
         .get_mut(&fh)
@@ -242,8 +184,8 @@ pub(crate) fn set_text(model: &mut Model, fh: FrameHandle, raw: &str) -> bool {
         (name, fmt)
     };
     let parsed = parse::parse_markup(raw, &frame_name, &hyperlink_format);
-    // The reference pushes these through the frame's error sink to the console. Ours are host
-    // warnings: a malformed page is the player's content being wrong, not a script raising.
+    // Deviation: the reference prints these to the console; here they are host warnings, because
+    // a malformed page is bad content, not a script error.
     for e in &parsed.errors {
         model.record_warning(e.clone());
     }
@@ -252,19 +194,18 @@ pub(crate) fn set_text(model: &mut Model, fh: FrameHandle, raw: &str) -> bool {
     parsed.used_markup
 }
 
-/// §10's `ADD_BLOCK`/`ADD_IMAGE` loop — the anchor chain, the fonts, and the `nextY` bookkeeping.
+/// The block loop of `AddTextBlock` (`0x78adb0`) and the `<IMG>` handler (`0x78ab40`): anchors,
+/// fonts and the running `nextY`.
 fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
     let frame_id = model.frame_id(fh);
-    // `0x78ae19 call [CLayoutFrame vtbl + 0x1c]` = `0x768420`, `fld [ecx+0x50]` — the frame's
-    // **declared** width, not its resolved rect. Every block is exactly that wide, which is what
-    // makes each one word-wrap at the frame width; §4.6's corollary is that a later resize does
-    // NOT re-wrap, because each block snapshotted the width at creation.
+    // The frame's declared width, not its resolved rect (`0x78ae19`, `0x768420`); a later resize
+    // does not re-wrap (`OnRectChanged` `0x78a320`), as each block keeps the width it was built at.
     let width = model
         .layout_inputs
         .get(&fh)
         .map_or(0.0, |input| input.width);
 
-    // `+0x348 prevBlock` — the last **text** block, and `+0x34c nextYOffset` (always <= 0).
+    // `prevBlock` (`+0x348`), the last text block, and `nextYOffset` (`+0x34c`), never positive.
     let mut prev_block: Option<u32> = None;
     let mut next_y = 0.0f32;
     let mut made: Vec<RegionHandle> = Vec::with_capacity(blocks.len());
@@ -272,9 +213,8 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
     for block in blocks {
         match block {
             Block::Text { text, elem, align } => {
-                // §5.3, the empty-path fallback: `elementFont[elem]`, unless its resolved path is
-                // empty, in which case `elementFont[0]` — so a declaration that supplies only
-                // `<FontString>` supplies the font for every element, headers included.
+                // An element with an empty path uses `P`'s font (`0x78ae29`-`0x78ae54`), so a
+                // lone `<FontString>` serves every element.
                 let paint = {
                     let st = model.simple_html.entry(fh).or_default().clone();
                     let own = resolve_font(model, &st.fonts[*elem]);
@@ -289,18 +229,14 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
                         .arena
                         .create_region(fh, RegionKind::FontString, DrawLayer::Artwork, 0)
                 else {
-                    // The frame died under us — unreachable (we hold its handle and just made
-                    // regions on it), but stop rather than orphan what is already built: the
-                    // blocks so far are still recorded below, so the next `SetText` frees them.
+                    // Unreachable; stop, keeping what was built recorded for the next `SetText`.
                     break;
                 };
                 let id = model.region_id(rh);
                 let mut d = RegionData {
                     anchors: vec![anchor_for(prev_block, frame_id, Point::TopLeft, next_y)],
-                    // `SetWidth(frame.GetWidth())` and **no height** — the block's rect height is
-                    // the FontString's intrinsic wrapped height, which the engine's measure
-                    // round-trip supplies exactly as the client's font engine supplies
-                    // `0x7729b0` → `0x5c2070`.
+                    // No height: the rect takes the wrapped text's height from the measure round
+                    // trip, as the client's font engine gives it (`0x7729b0`, `0x5c2070`).
                     size: Some((width, 0.0)),
                     text: Some(text.clone()),
                     font_object: paint.font_object.clone(),
@@ -312,21 +248,15 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
                     font_shadow: paint.shadow,
                     ..RegionData::default()
                 };
-                // §5.4: `block->+0x120 = (block->+0x120 & ~7) | (align & 7)` (`0x78ae78`), written
-                // AFTER `SetFontObject`, so the tag's `align` always wins over the element font's
-                // own justifyH. justifyV is left alone and keeps whatever the element font
-                // supplied (ctor MIDDLE) — visually inert here, because the block's rect height IS
-                // its text height.
+                // The tag's `align` is written after `SetFontObject` (`0x78ae78`), so it beats
+                // the font's justifyH; justifyV stays the font's, inert in a rect its text fills.
                 d.justify = Justify(justify::set_axis(paint.justify.0, justify::H_MASK, *align));
-                // …and it can never be RE-inherited: `0x78ae68` clears the per-bit justifyH
-                // inherit mask (`+0x124 &= ~7`) and `0x78ae95` the whole CFontInstance justify
-                // group bit (`+0xd4 &= ~2`). Marking both axes explicit is what that pair means
-                // here — it is what stops `script::font::propagate` from re-centering a built
-                // block the moment somebody mutates the font object it drew from.
+                // Neither axis is inherited again (`0x78ae68`, `0x78ae95` clear the inherit bits),
+                // so a later font-object change never re-justifies a built block.
                 d.font_explicit.justify_h = true;
                 d.font_explicit.justify_v = true;
                 model.region_data.insert(rh, d);
-                model.touch_measure(rh); // a text block arrives text-in-hand
+                model.touch_measure(rh); // a text block arrives with its text
                 prev_block = Some(id);
                 next_y = -paint.spacing;
                 made.push(rh);
@@ -343,15 +273,12 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
                         .arena
                         .create_region(fh, RegionKind::Texture, DrawLayer::Artwork, 0)
                 else {
-                    break; // as above
+                    break; // unreachable, as above
                 };
-                // Minted even though nothing anchors TO an image (`prevBlock` is never written by
-                // the image path): the id is what the resolve seats the region's rect under, and
-                // what `free_block` unmaps on the next `SetText`.
+                // Minted though nothing anchors to an image; the resolve and `free_block` use it.
                 model.region_id(rh);
-                // §7 step 4 — the anchor corner is selected by `align`, and 8/16/32 get **no
-                // `SetPoint` at all** (`0x78ac61 jne 0x78ace8`). An anchorless region never
-                // resolves here either, so it draws nothing, which is the same outcome.
+                // `align` picks the corner; 8, 16 and 32 get no anchor at all (`0x78ac61`, a jump
+                // to `0x78ace8`), so the image draws nothing, here as there.
                 let point = match *align {
                     parse::ALIGN_LEFT => Some(Point::TopLeft),
                     parse::ALIGN_CENTER => Some(Point::Top),
@@ -370,16 +297,10 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
                         ..RegionData::default()
                     },
                 );
-                // §7 step 6/7: an unfloated image reserves its own height in the flow, and
-                // `prevBlock` is **never** written by the image path (three reads of `+0x348` in
-                // the whole function, zero writes) — the next block still hangs off the last TEXT
-                // block, only lower.
-                //
-                // The height it reserves is `texture.GetHeight()`, which is `CSimpleTexture`'s
-                // **override**: a `<IMG>` with no `height=` reserves its art's own texel height,
-                // not nothing (decision 1349 — one texel is one FrameXML unit). Asked of the same
-                // host oracle the resolve derives the region's rect from, so the space the flow
-                // leaves and the space the image fills are one number.
+                // An unfloated image moves the flow down by its height (`0x78ad07`-`0x78ad1b`), but
+                // the next block still hangs off the last text block: the image path never writes
+                // `prevBlock`. Without `height=` it reserves its texture's texel height
+                // (`CSimpleTexture`'s `GetHeight`), from the probe the resolve sizes it by.
                 if !*floated {
                     let reserved = if *h == 0.0 {
                         src.as_deref()
@@ -401,8 +322,8 @@ fn build(model: &mut Model, fh: FrameHandle, blocks: &[Block]) {
     model.touch_layout();
 }
 
-/// The two anchor forms of §4.2 step 2: block 0 pins to the frame, block *N* to its predecessor's
-/// bottom edge at `nextYOffset` (negative, i.e. downward).
+/// A block's anchor (`SetPoint` `0x767c70`): block 0 to the frame, block N to the previous text
+/// block's bottom edge, `nextYOffset` lower.
 fn anchor_for(prev_block: Option<u32>, frame_id: u32, point: Point, next_y: f32) -> Anchor {
     match prev_block {
         None => Anchor::new(point, frame_id, point, 0.0, 0.0),
@@ -418,26 +339,15 @@ fn anchor_for(prev_block: Option<u32>, frame_id: u32, point: Point, next_y: f32)
     }
 }
 
-/// Free one block region — [`crate::script::region::free_region`], which is where this function's
-/// body went when the button's label swap needed the same five-map teardown. Kept as a name
-/// because `set_text`'s call sites read better with it, and because the doc that explains *why* a
-/// destroyed region must answer stale rather than linger lives on the shared law now.
 fn free_block(model: &mut Model, rh: RegionHandle) {
     crate::script::region::free_region(model, rh);
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The loader's seam
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The loader's seam ────────────────────────────────────────────────────────────────────────
 
-/// Apply the font parts an **XML** `<FontString>`/`<FontStringHeaderN>` child of a `<SimpleHTML>`
-/// supplies — `font=`, `<FontHeight>`, `outline=` — any subset of which may be absent.
-///
-/// The region-side twin of this is [`super::apply_font_parts`], and it exists for the same reason:
-/// the reference applies XML font attributes in C++ (`CSimpleFont::LoadXML 0x783c30`, reached from
-/// `0x78a1fe`…`0x78a26e`), never through the Lua `SetFont`, whose usage string *requires* both a
-/// path and a height. Routing the loader through the binding is what forces the binding to be
-/// lenient; keeping them separate lets each be right.
+/// Apply the `font=`, `<FontHeight>` and `outline=` an XML `<FontString>` or `<FontStringHeaderN>`
+/// child supplies, any of them absent. The reference applies these in C++ (`CSimpleFont::LoadXML`
+/// `0x783c30`, from `0x78a1fe`), not through `SetFont`, which requires both path and height.
 pub(crate) fn apply_element_font_parts(
     lua: &Lua,
     this: &Table,
@@ -464,8 +374,9 @@ pub(crate) fn apply_element_font_parts(
     Ok(())
 }
 
-/// The element index an XML child tag names: `<FontString>` → `P`, `<FontStringHeader1|2|3>` →
-/// `H1`/`H2`/`H3` (`0x8786cc`, `0x87a8b4`/`0x87a8a0`/`0x87a88c`; assigned at `0x78a1fe`…`0x78a26e`).
+/// The element index an XML child tag names: `<FontString>` is `P`, `<FontStringHeader1|2|3>`
+/// `H1`, `H2`, `H3` (names `0x8786cc`, `0x87a8b4`, `0x87a8a0`, `0x87a88c`; read at `0x78a1fe` to
+/// `0x78a26e`).
 pub(crate) fn element_of_xml_tag(tag: &str) -> Option<usize> {
     if tag.eq_ignore_ascii_case("FontString") {
         Some(0)
@@ -480,13 +391,9 @@ pub(crate) fn element_of_xml_tag(tag: &str) -> Option<usize> {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The Lua surface
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The Lua surface ──────────────────────────────────────────────────────────────────────────
 
-/// Resolve `this` to a live `SimpleHTML` frame. Reached through the kind dispatcher, so the guard
-/// only fires when a caller fishes the method table out and misapplies it — the same posture
-/// `script::scrollframe`'s `with_scroll` takes.
+/// Resolve `this` to a live `SimpleHTML` frame; only a misapplied method table fails.
 fn html_handle(lua: &Lua, this: &Table) -> mlua::Result<FrameHandle> {
     let h = frame_handle_of(lua, this)?;
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -496,22 +403,9 @@ fn html_handle(lua: &Lua, this: &Table) -> mlua::Result<FrameHandle> {
     }
 }
 
-/// `0x795d80` — the **optional leading element-name string**, consumed by the first sixteen
-/// methods.
-///
-/// ```text
-/// if (lua_type(L, 2) != LUA_TSTRING)      return 0;          ; 0x795d91
-/// if (SStrCmpI(s,"P" )==0) { lua_remove(L,2); return 0; }    ; 0x795db3
-/// if (SStrCmpI(s,"H1")==0) { lua_remove(L,2); return 1; }    ; 0x795ddb
-/// if (SStrCmpI(s,"H2")==0) { lua_remove(L,2); return 2; }    ; 0x795e06
-/// if (SStrCmpI(s,"H3")==0) { lua_remove(L,2); return 3; }    ; 0x795e2e
-/// return 0;                                                   ; 0x795e50 (NO lua_remove)
-/// ```
-///
-/// Two silent behaviours fall out and are reproduced exactly: omitting the name addresses **`P`**,
-/// and a *string* first argument that is not one of the four is **not** an error and is **not**
-/// removed — it stays and is consumed as the shared implementation's first real argument, so
-/// `SetFont("h4", path, 15)` targets `P` and hands `"h4"` to `SetFont` as the path.
+/// The optional leading element name of the first sixteen methods (`0x795d80`). `P`, `H1`, `H2`
+/// or `H3`, in any case, is removed and selects that element; anything else selects `P` and stays
+/// (`0x795e50`), so `SetFont("h4", path, 15)` sets `P`'s font with `"h4"` as the path.
 fn take_element(args: &mut MultiValue) -> usize {
     let matched = match args.front() {
         Some(Value::String(s)) => s.to_str().ok().and_then(|s| {
@@ -535,8 +429,7 @@ fn arg(args: &MultiValue, i: usize) -> Value {
     args.get(i).cloned().unwrap_or(Value::Nil)
 }
 
-/// Run `f` over one element font under a short write borrow, then dirty the layout — every one of
-/// these can change what the *next* `SetText` draws with, and several change nothing until then.
+/// Run `f` over one element font under a short borrow; it shapes the next `SetText`'s blocks.
 fn edit_font<T>(
     lua: &Lua,
     this: &Table,
@@ -548,8 +441,7 @@ fn edit_font<T>(
     Ok(f(&mut model.simple_html.entry(h).or_default().fonts[elem]))
 }
 
-/// Read one element font's **resolved** paint (the object it inherits, with its own sets on top) —
-/// what the getters answer and what a block would be built with.
+/// One element font's resolved paint: what the getters answer and a block would be built with.
 fn read_font(lua: &Lua, this: &Table, elem: usize) -> mlua::Result<BlockPaint> {
     let h = html_handle(lua, this)?;
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -563,10 +455,9 @@ fn read_font(lua: &Lua, this: &Table, elem: usize) -> mlua::Result<BlockPaint> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // ── 0/1 · the font object, and the live link to it ──────────────────────────────────────
-    // `SetFontObject([element,] font | "font" | nil)` → 0 values. Unlike a region's, this cannot
-    // repaint anything already on screen: the element fonts are prototypes, and only the next
-    // `SetText` copies them into blocks (§4.6 — a built block is never re-fonted).
+    // ── 0/1 · the font object ────────────────────────────────────────────────────────────────
+    // SetFontObject([element,] font | "font" | nil) returns nothing and changes only the next
+    // `SetText`'s blocks; a built block is never re-fonted (`0x795d3e`).
     m.set(
         "SetFontObject",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -580,11 +471,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     )));
                 }
             }
-            // The **nil form severs the link and leaves the paint standing** — the reference
-            // stores a null parent and nothing re-reads or clears the resolved values. A region
-            // gets that for free (its paint was copied into `RegionData`); an element font
-            // resolves its object lazily, so the standing paint has to be pinned down here or the
-            // sever would blank the element instead.
+            // nil severs the link and keeps the paint, as the reference stores a null parent; an
+            // element font resolves its object lazily, so the standing paint is pinned here.
             let standing = name
                 .is_none()
                 .then(|| read_font(lua, &this, elem))
@@ -607,12 +495,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         justify_v: true,
                     };
                 }
-                // The severance mask is deliberately **not** reset on a re-point. §5-verified for
-                // the region side (`script::font_block`'s `SetFontObject`): the real "stop
-                // inheriting this property" signal is a CLEARED bit in the inheritMask
-                // (`FONTINSTANCE+0x2c`), cleared by each local setter and never restored — so a
-                // property this element set for itself stays severed across a later
-                // `SetFontObject`. The two sides of one law must not disagree.
+                // A re-point keeps the severance mask, as on a region: each local setter clears
+                // its bit of the inherit mask (`FONTINSTANCE+0x2c`) for good.
                 ef.font_object = name;
             })
         })?,
@@ -638,9 +522,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── 2/3 · the face ──────────────────────────────────────────────────────────────────────
-    // `SetFont([element,] file, height [, flags])` → the NUMBER 1, or nil on an empty path (the
-    // load-failure probe shape); the argument gate is the shared `0x79f210` entry, so a numeric
-    // string is accepted for either and anything else raises `0x87c69c`'s usage string.
+    // SetFont([element,] file, height [, flags]) returns 1, or nil on an empty path; the shared
+    // gate (`0x79f210`) takes numeric strings and raises `0x87c69c`'s usage line on anything else.
     m.set(
         "SetFont",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -660,8 +543,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 ef.font_height = Some(height);
                 ef.explicit.height = true;
                 if let Some(f) = flags {
-                    // The **Lua** flags spelling ("OUTLINE"/"THICKOUTLINE"), a different
-                    // vocabulary from the XML `outline=` attribute — see [`Outline::flags`].
+                    // The Lua flags spelling, not XML's `outline=` ([`Outline::flags`]).
                     ef.outline = Outline::flags(&f);
                     ef.explicit.outline = true;
                 }
@@ -669,7 +551,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(if ok { Value::Number(1.0) } else { Value::Nil })
         })?,
     )?;
-    // `GetFont([element])` → 3 values: path, height, flags string (`""`, never nil).
+    // GetFont([element]): path, height and a flags string, `""` rather than nil.
     m.set(
         "GetFont",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -707,8 +589,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── 6..9 · the shadow ───────────────────────────────────────────────────────────────────
-    // `GetShadowColor` returns **four** values (`0x79f9b3 mov eax,0x4`), `GetShadowOffset` two.
-    // Either half may be set before the other, so each starts from whatever is already there.
+    // `GetShadowColor` returns four values (`0x79f9b3`), `GetShadowOffset` two; each setter keeps
+    // the other half.
     m.set(
         "SetShadowColor",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -731,8 +613,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok((c[0], c[1], c[2], c[3]))
         })?,
     )?;
-    // Both arguments are required — the shared impl raises `Usage: %s:SetShadowOffset(x, y)`
-    // (`0x87c6e8`) rather than defaulting the missing one.
+    // Both arguments are required: the shared code raises its usage line (`0x87c6e8`).
     m.set(
         "SetShadowOffset",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -761,10 +642,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── 10/11 · spacing ─────────────────────────────────────────────────────────────────────
-    // `SetSpacing([element,] n)` — `0x772240` clamps a negative argument to 0 before storing
-    // (`0x772246 fcomp [0x7ffd74 = 0.0]`). This is the ONE way to open a gap between blocks: the
-    // ctor default is 0, so out of the box they stack perfectly flush, with no per-element
-    // constant, no half-line and no margin anywhere.
+    // SetSpacing([element,] n) clamps a negative to 0 (`0x772240`, `0x772246`); it is the only gap
+    // between blocks, which stack flush at the ctor default of 0.
     m.set(
         "SetSpacing",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -782,13 +661,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // ── 12..15 · justification ──────────────────────────────────────────────────────────────
-    // Both resolve through the same `0x811ad0` table as `align`, masked `&7` / `&0x38`, so a
-    // cross-axis token CLEARS its axis and a non-token raises (see [`crate::justify`]).
-    //
-    // **`SetJustifyH` is inert for rendered text**, and that is the byte law rather than a gap:
-    // it writes the element font's justify, which `0x78adb0` overwrites on every block it builds
-    // with the tag's own `align`. It is installed because the table has it and `GetJustifyH` must
-    // answer what was stored.
+    // Both parse through `align`'s table (`0x811ad0`), masked `&7` or `&0x38` ([`crate::justify`]).
+    // `SetJustifyH` never shows: `0x78adb0` overwrites it with each block's `align`.
     m.set(
         "SetJustifyH",
         lua.create_function(|lua, (this, mut rest): (Table, MultiValue)| {
@@ -830,15 +704,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── 16..18 · the three with NO element argument ─────────────────────────────────────────
-    // `SetText(s)` → 0 values (`0x796a90` discards the shared implementation's `usedMarkup`).
-    // A nil argument reaches `lua_tostring` as NULL; an empty string is the closest thing to that
-    // this engine can hand a parser, and it takes the same fallback route a NULL would.
+    // ── 16..18 · the three without an element argument ──────────────────────────────────────
+    // SetText(s) returns nothing (`0x796a90` drops `usedMarkup`); nil parses as an empty string,
+    // which takes the fallback a NULL takes.
     m.set(
         "SetText",
         lua.create_function(|lua, (this, text): (Table, Value)| {
             let raw = match &text {
-                // Bytes, lossily — never a raise (2138).
+                // Bytes, lossily; never a raise.
                 Value::String(s) => s.to_string_lossy(),
                 Value::Number(_) | Value::Integer(_) => super::object::as_f32(&text).to_string(),
                 _ => String::new(),
@@ -849,8 +722,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // `SetHyperlinkFormat(s)` raises `Usage: %s:SetHyperlinkFormat("format")` (`0x87bb40`) if
-    // argument 2 is not a string (`0x796bcc`–`0x796c29`). It takes effect on the NEXT parse.
+    // SetHyperlinkFormat(s) raises its usage line (`0x87bb40`) on a non-string
+    // (`0x796bcc`-`0x796c29`); it applies from the next parse.
     m.set(
         "SetHyperlinkFormat",
         lua.create_function(|lua, (this, fmt): (Table, Value)| {
@@ -883,8 +756,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `(r, g, b [, a])` off the post-element argument list — alpha `lua_isnumber`-gated with the
-/// default `1.0`, r/g/b required, exactly as the shared colour setters take them.
+/// `(r, g, b [, a])` after the element argument, as the shared colour setters take it: r, g and b
+/// required, alpha 1 unless a number.
 fn rgba(lua: &Lua, rest: &MultiValue) -> mlua::Result<[f32; 4]> {
     let r = f32::from_lua(arg(rest, 0), lua)?;
     let g = f32::from_lua(arg(rest, 1), lua)?;
@@ -896,5 +769,5 @@ fn rgba(lua: &Lua, rest: &MultiValue) -> mlua::Result<[f32; 4]> {
     Ok([r, g, b, a])
 }
 
-/// The per-frame state store — `Model`'s side of this module (see [`SimpleHtmlState`]).
+/// The per-frame [`SimpleHtmlState`] store `Model` holds.
 pub(crate) type SimpleHtmlStates = HashMap<FrameHandle, SimpleHtmlState>;
diff --git a/crates/benilla-ui/src/script/simplehtml/parse.rs b/crates/benilla-ui/src/script/simplehtml/parse.rs
index fa0d066a..236df3dd 100644
--- a/crates/benilla-ui/src/script/simplehtml/parse.rs
+++ b/crates/benilla-ui/src/script/simplehtml/parse.rs
@@ -1,70 +1,42 @@
-//! The **markup parse** half of `CSimpleHTML::SetText` — `&str` in, a block list out.
+//! The markup parse of `CSimpleHTML::SetText`: a string in, a block list out, with no Lua or model.
 //!
-//! Pure: no Lua, no model, no arena. Everything here is one transcription of
-//! wow-5875-re `system/ui/scratch/simplehtml-markup-engine.md` §10's algorithm and the §0–§7
-//! derivations behind it; [`super`] does the materialization (regions, anchors, fonts).
-//!
-//! ## The one fact everything else follows from
-//!
-//! **The markup is parsed as strict XML, not as lenient HTML.** `0x78a422` calls
-//! `XMLTree::Parse 0x6f2a30`, which is embedded **expat 1.95.5** (version string `0x882094`,
-//! wrapper `__FILE__` `…\FrameXML\XMLTree.cpp` at `0x8715ec`). So an unclosed `<BR>`, a `</p>`
-//! closing a `<P>` (XML open/close matching is case-SENSITIVE, even though *SimpleHTML's own*
-//! name compares are not — §1.3, `SStrCmpI 0x414310`), a bare `&`, a non-predefined entity such
-//! as `&nbsp;`, a duplicate attribute, or any non-whitespace after `</HTML>` all fail the parse
-//! outright, and the widget renders the **raw** string instead (§3).
-//!
-//! [`roxmltree`] stands in for expat here, and it is the right stand-in rather than a convenient
-//! one: it is a well-formedness-checking XML parser with exactly the five XML predefined entities
-//! plus numeric character references, and it was checked case by case against the note's error
-//! table before this module was written — plain prose, a bare `&`, a bare `<`, an unclosed `<BR>`,
-//! a case-mismatched close tag, `&nbsp;`, junk after the root and a duplicate attribute are each
-//! an `Err` (expat codes 4/4/4/7/7/11/9/8), while trailing whitespace after `</HTML>`, a leading
-//! newline, numeric refs, comments and CDATA are each an `Ok`. Its interleaved text/element child
-//! order also hands us the `<A>`/`<BR>` splice positions directly, so none of the note's
-//! `offsetInParentText` arithmetic (`XMLTree` node `+0x18`) is needed.
-//!
-//! **The one behavioural difference found**, stated rather than hidden: roxmltree refuses a
-//! document carrying an internal DTD subset (`XML with DTD detected`) where expat 1.95.5 may
-//! accept one and honour its `<!ENTITY>` declarations. §9 of the note leaves expat's build options
-//! unread for exactly this case and observes that no `page_text` body carries a DOCTYPE; for us a
-//! DOCTYPE simply takes the plain-text fallback, which is the same place a rejected parse lands.
+//! The markup is strict XML: `0x78a422` calls `XMLTree::Parse` (`0x6f2a30`), an embedded expat
+//! 1.95.5 (`0x882094`). An unclosed `<BR>`, a `</p>` closing a `<P>` (XML matching is
+//! case-sensitive, SimpleHTML's own name compares are not), a bare `&`, an entity such as `&nbsp;`,
+//! a duplicate attribute or text after `</HTML>` fails the parse, and the widget renders the raw
+//! string (`0x78a501`). [`roxmltree`] gives expat's outcome on each of those and on what passes
+//! (trailing whitespace, numeric references, comments, CDATA), and its interleaved children give
+//! the `<A>` and `<BR>` splice points directly. A DOCTYPE takes the fallback here; whether the
+//! reference's expat accepts one is untraced, and no `page_text` body carries one.
 
 use crate::justify;
 
-/// The four block elements, indexed as the client indexes `elementFont[4]` at `+0x350`:
-/// `0 = P, 1 = H1, 2 = H2, 3 = H3` (`0x789e3e` creates them in that order, `0x78ae29` reads them,
-/// and the Lua element-name resolver `0x795d80` answers the same four numbers).
+/// The four block elements in the client's `elementFont` order (`+0x350`), the numbering the ctor
+/// (`0x789e3e`), the block builder (`0x78ae29`) and the Lua resolver (`0x795d80`) share.
 pub(crate) const ELEMENT_NAMES: [&str; 4] = ["P", "H1", "H2", "H3"];
 
-/// `P` — the element every unqualified path addresses: the plain-text fallback's block (`0x78a503
-/// push 0`), the `<BR/>` block, and the element a missing or unrecognised Lua element-name
-/// argument resolves to (`0x795e50`).
+/// `P`: the element of the fallback block (`0x78a503`), of `<BR/>`, and of a Lua call without a
+/// known element name (`0x795e50`).
 pub(crate) const ELEM_P: usize = 0;
 
-/// The `align` default, pre-loaded into the local before the attribute is even looked at
-/// (`0x78a7c8 mov [ebp-0xc],1` for a block, `0x78ab59 mov [ebp-8],1` for an `<IMG>`): **LEFT**,
-/// and emphatically *not* the `CSimpleFontString` ctor's CENTER, which `0x78ae78` overwrites on
-/// every block it builds.
+/// The `align` default, set before the attribute is read (`0x78a7c8` for a block, `0x78ab59` for
+/// an `<IMG>`): LEFT, which `0x78ae78` writes over the FontString ctor's CENTER.
 pub(crate) const ALIGN_LEFT: u32 = 0x01;
-/// `align="center"` — the value `0x6f1990` writes from the shared enum table `.rdata 0x811ad0`.
+/// `align="center"`: the value `0x6f1990` writes from the shared enum table (`0x811ad0`).
 pub(crate) const ALIGN_CENTER: u32 = 0x02;
 /// `align="right"`.
 pub(crate) const ALIGN_RIGHT: u32 = 0x04;
 
-/// The ctor default of `hyperlinkFormat` (`+0x360`, string `0x87a838`, installed by
-/// `0x789ea7`→`0x78a540`): `<A href="X">Y</A>` becomes `|HX|hY|h`, which the font engine then
-/// parses as an ordinary hyperlink (§6.5 — nothing disables `|H` on a `CSimpleFontString`).
+/// The ctor's `hyperlinkFormat` (`0x87a838`, set at `0x789ea7` and `0x78a540`): `<A href="X">Y</A>`
+/// becomes `|HX|hY|h`, a hyperlink to the FontString, which never disables `|H` (`0x771d80`).
 pub(crate) const DEFAULT_HYPERLINK_FORMAT: &str = "|H%s|h%s|h";
 
-/// One block the walk produced — the arguments of `AddTextBlock 0x78adb0` / `AddImage 0x78ab40`,
-/// in the order the BODY walker emitted them.
+/// One block, the arguments of `AddTextBlock` (`0x78adb0`) or `AddImage` (`0x78ab40`).
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) enum Block {
     /// A text block: one `CSimpleFontString`, `SetWidth(frame width)`, no height.
     Text {
-        /// The already-spliced, already-collapsed string handed to `SetText` — except on the
-        /// plain-text fallback path, which hands over the **raw** input (§3).
+        /// The spliced, collapsed string, or the raw input on the fallback path (`0x78a501`).
         text: String,
         /// The `elementFont[]` index this block draws with, before the empty-path fallback.
         elem: usize,
@@ -73,19 +45,17 @@ pub(crate) enum Block {
     },
     /// An `<IMG>`: one `CSimpleTexture`, sized by `width`/`height` and anchored by `align`.
     Image {
-        /// `src=`, used **verbatim** as a texture path — no prefix, no extension fix-up, no
-        /// validation in this TU (`0x78ad02`).
+        /// `src=`, used verbatim as the texture path (`0x78ad02`).
         src: Option<String>,
-        /// `width=`/`height=` in logical UI pixels (§7 step 2 — the same units as
-        /// `<AbsDimension>`); `0` when the attribute is absent.
+        /// `width=` and `height=` in UI units, as `<AbsDimension>` (`0x78ab9e`, `0x78abd6`); 0
+        /// when absent.
         width: f32,
         height: f32,
         /// The `align` bits; selects which corner anchors to the previous block.
         align: u32,
-        /// The **separate** float byte `[ebp-1]` (§7 step 1): a floated image reserves no height
-        /// in the flow, so the following text overlaps it. Set only inside the
-        /// attribute-present branch, which is why a bare `<IMG src=…/>` and
-        /// `<IMG align="left" src=…/>` anchor identically and flow differently.
+        /// Reserves no height, so the text after overlaps it (`0x78ab55`). Set only when `align`
+        /// is present, so `<IMG src=…/>` and `<IMG align="left" src=…/>` anchor alike but flow
+        /// differently.
         floated: bool,
     },
 }
@@ -93,36 +63,29 @@ pub(crate) enum Block {
 /// The outcome of one `SetText` parse.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) struct Parse {
-    /// The blocks to build, in order.
     pub(crate) blocks: Vec<Block>,
-    /// `SetText`'s own return value in `al` (`0x78a519`): whether the markup path ran. The Lua
-    /// shim `0x796a90` discards it; we keep it because it is exactly "did this render as markup
-    /// or as raw text", which is the thing a reader of a `page_text` body wants to know.
+    /// `SetText`'s return (`0x78a519`): whether the markup path ran. The Lua shim (`0x796a90`)
+    /// drops it.
     pub(crate) used_markup: bool,
-    /// The console lines the error sink received (`"Frame %s: Unknown element type: %s"` and its
-    /// two `(expected …)` variants), already formatted with the frame's name.
+    /// The console lines the error sink received, formatted with the frame's name.
     pub(crate) errors: Vec<String>,
 }
 
-/// `CSimpleHTML::SetText 0x78a3a0`'s parse half — §10's `SetText`/`WALK_BODY`/`ADD_PARAGRAPH`.
-///
-/// `frame` is the widget's name, the `%s` of the error strings. `hyperlink_format` is
-/// `+0x360`'s current value, used by the `<A>` splice.
+/// The parse half of `SetText` (`0x78a3a0`). `frame` names the widget in error lines;
+/// `hyperlink_format` is the current `+0x360`.
 pub(crate) fn parse_markup(raw: &str, frame: &str, hyperlink_format: &str) -> Parse {
     let mut out = Parse {
         blocks: Vec::new(),
         used_markup: false,
         errors: Vec::new(),
     };
-    // `usedMarkup` is `[ebp+0xf]`, zeroed at `0x78a415` and raised at exactly ONE site,
-    // `0x78a4b6` — immediately BEFORE the BODY walker runs. That ordering is the whole reason an
-    // empty `<BODY/>` renders nothing at all rather than falling back to the raw string.
+    // `usedMarkup` is raised before the BODY walk (`0x78a4b6`), so an empty `<BODY/>` renders
+    // nothing rather than the raw string.
     if let Ok(doc) = roxmltree::Document::parse(raw) {
         let root = doc.root_element();
         if root.tag_name().name().eq_ignore_ascii_case("HTML") {
-            // Only the FIRST `BODY` is walked: `0x78a4ba call 0x78a660` is followed by
-            // `0x78a4bf jmp 0x78a4ef`, which leaves the sibling loop — a second `<BODY>` is never
-            // visited and never even errors.
+            // Only the first `BODY` is walked, and a second never errors (`0x78a4bf` leaves the
+            // loop after `0x78a660` returns).
             for child in root.children().filter(roxmltree::Node::is_element) {
                 if child.tag_name().name().eq_ignore_ascii_case("BODY") {
                     out.used_markup = true;
@@ -142,12 +105,9 @@ pub(crate) fn parse_markup(raw: &str, frame: &str, hyperlink_format: &str) -> Pa
         }
     }
     if !out.used_markup {
-        // The three routes here — a failed parse, a non-`HTML` root, an `HTML` with no `BODY`
-        // child — all land on `0x78a501`: the ORIGINAL, unmodified string as ONE block, element
-        // `P`, justifyH LEFT. **Without the whitespace collapse**, because the collapse lives in
-        // the paragraph builder `0x78a7b0` which this path never enters — so embedded `\n` stay
-        // real line breaks. Stock `ItemTextFrame.lua` depends on exactly that, padding its page
-        // with `SetText("\n" .. ItemTextGetText() .. "\n")`.
+        // A failed parse, a non-`HTML` root or no `BODY` all land on `0x78a501`: the raw string
+        // as one LEFT `P` block, without the collapse, as `0x78a7b0` is never entered, so its `\n`
+        // stay line breaks, which stock `ItemTextFrame.lua` relies on.
         out.blocks.push(Block::Text {
             text: raw.to_string(),
             elem: ELEM_P,
@@ -157,11 +117,8 @@ pub(crate) fn parse_markup(raw: &str, frame: &str, hyperlink_format: &str) -> Pa
     out
 }
 
-/// The BODY walker `0x78a660` — dispatch by child element name, case-insensitively.
-///
-/// **`BODY`'s own character data is DROPPED**: the walker reads only `firstChild`/`nextSibling`
-/// and nothing ever reads `body->+0x0c`. The inter-tag newlines of a typical `page_text` body are
-/// exactly that, which is why they contribute no blank lines.
+/// The BODY walker (`0x78a660`), by child name, case-insensitively. BODY's own text is dropped, as
+/// nothing reads it (`+0x0c`), so the newlines between a `page_text` body's tags add nothing.
 fn walk_body(body: roxmltree::Node, frame: &str, hyperlink_format: &str, out: &mut Parse) {
     for node in body.children().filter(roxmltree::Node::is_element) {
         let tag = node.tag_name().name();
@@ -172,10 +129,7 @@ fn walk_body(body: roxmltree::Node, frame: &str, hyperlink_format: &str, out: &m
             let block = paragraph(node, elem, frame, hyperlink_format, &mut out.errors);
             out.blocks.push(block);
         } else if tag.eq_ignore_ascii_case("BR") {
-            // `0x78a726` → `0x78adb0("\n" @0x835144, elem 0, align 1)`: a block of its own whose
-            // text is the single byte `\n`. The height kernel `0x5c2070` takes the class-2 arm
-            // once and exits with `lines == 1`, so it is **exactly one blank line** — not two,
-            // not a paragraph gap.
+            // A `\n` block of its own (`0x78a726`), one blank line tall (`0x5c2070`).
             out.blocks.push(Block::Text {
                 text: "\n".to_string(),
                 elem: ELEM_P,
@@ -184,16 +138,14 @@ fn walk_body(body: roxmltree::Node, frame: &str, hyperlink_format: &str, out: &m
         } else if tag.eq_ignore_ascii_case("IMG") {
             out.blocks.push(image(node));
         } else {
-            // `0x78a762`–`0x78a793`: the name is formatted into `"Frame %s: Unknown element type:
-            // %s"` (`0x87a95c`), pushed through the sink, and the node contributes NOTHING; the
-            // sibling walk continues at `0x78a796`.
+            // Logged (`0x87a95c`) and skipped; the walk goes on (`0x78a762`-`0x78a796`).
             out.errors
                 .push(format!("Frame {frame}: Unknown element type: {tag}"));
         }
     }
 }
 
-/// `0x78a7b0(node, elem, sink)` — one `<P>`/`<H1>`/`<H2>`/`<H3>` into one block.
+/// One `<P>`, `<H1>`, `<H2>` or `<H3>` into one block (`0x78a7b0`).
 fn paragraph(
     node: roxmltree::Node,
     elem: usize,
@@ -202,12 +154,8 @@ fn paragraph(
     errors: &mut Vec<String>,
 ) -> Block {
     let align = align_of(node);
-    // §6.1/§6.2 in one pass. The reference seeds the buffer with the node's whole accumulated
-    // character data (expat concatenates the text either side of an inline child into the SAME
-    // `+0x0c`) and then splices each child in at its recorded `+0x18` offset plus the running
-    // `extra`. roxmltree hands us text and elements interleaved in document order instead, so
-    // appending as we walk lands every splice exactly where the tag was, with no offset
-    // arithmetic to get wrong.
+    // The reference splices each inline child into the node's text at its recorded offset
+    // (`+0x18`); appending roxmltree's interleaved children in order puts each at the same place.
     let mut buf = String::new();
     for child in node.children() {
         if child.is_text() {
@@ -215,27 +163,24 @@ fn paragraph(
             continue;
         }
         if !child.is_element() {
-            // A comment or PI: expat never delivers it as character data either.
+            // A comment or PI, which expat does not deliver as text either.
             continue;
         }
         let tag = child.tag_name().name();
         if tag.eq_ignore_ascii_case("BR") {
-            // `0x78a86b` appends the two literal bytes `|n` (`0x87a9a0`) — a real line break
-            // WITHIN this block, not a block of its own, and `extra += 2`.
+            // An inline `<BR/>` is `|n`, a break inside this block (`0x78a86b`, `0x87a9a0`).
             buf.push_str("|n");
         } else if tag.eq_ignore_ascii_case("A") {
-            // `0x78a8f0` requires **both** a non-empty `href` and non-empty inner text
-            // (`0x78a914`–`0x78a922`); otherwise the whole `<A>` contributes nothing at all.
+            // `<A>` needs a non-empty `href` and text, or adds nothing (`0x78a8f0`,
+            // `0x78a914`-`0x78a922`).
             let href = attr_ci(child, "href").unwrap_or("");
             let inner = direct_text(child);
             if !href.is_empty() && !inner.is_empty() {
                 buf.push_str(&sprintf_two(hyperlink_format, href, &inner));
             }
         } else {
-            // `0x78a9f9`–`0x78aa2c`: the same message and the same outcome as at BODY level. The
-            // child's own character data went into the CHILD's `+0x0c`, never the parent's, so
-            // the text of an unknown inline element is silently lost while the text either side
-            // of it is kept — which is what dropping the node here reproduces.
+            // Logged as at BODY level (`0x78a9f9`-`0x78aa2c`); its own text, which expat keeps on
+            // the child, is lost and the text around it kept.
             errors.push(format!("Frame {frame}: Unknown element type: {tag}"));
         }
     }
@@ -246,17 +191,14 @@ fn paragraph(
     }
 }
 
-/// `0x78ab40(node, sink)` — one `<IMG>`.
+/// One `<IMG>` (`0x78ab40`).
 fn image(node: roxmltree::Node) -> Block {
     let mut align = ALIGN_LEFT;
     let mut floated = false;
-    // §7 step 1, the round's arbitration point. The float byte `[ebp-1]` is zeroed at `0x78ab55`
-    // and set only INSIDE the attribute-present branch (`0x78ab67`/`0x78ab6c` both skip past it),
-    // so it is a property of *the attribute being written*, not of the value:
-    //
-    //   absent / empty  → align 1, floated 0        `left`/`right` → 1 / 4, floated 1
-    //   `center`        → 2, floated 0              `top`/`middle`/`bottom` → 8/16/32, floated 0
-    //   anything else   → align stays 1, floated **1** (`0x6f1990` left the local at its default)
+    // Floating is decided only when `align` is present and non-empty (`0x78ab55`-`0x78ab6c`):
+    //   absent or empty: align 1, not floated     `left`, `right`: 1, 4, floated
+    //   `center`: 2, not floated                  `top`, `middle`, `bottom`: 8, 16, 32, not floated
+    //   anything else: align stays 1, floated (`0x6f1990` leaves the default)
     if let Some(v) = attr_ci(node, "align").filter(|v| !v.is_empty()) {
         if let Some(bits) = justify::parse_bits(v) {
             align = bits;
@@ -272,13 +214,9 @@ fn image(node: roxmltree::Node) -> Block {
     }
 }
 
-/// `align` on a `<P>`/`<H1>`/`<H2>`/`<H3>` (`0x78a7cf`): the shared 6-entry enum at
-/// `.rdata 0x811ad0`, which [`justify::parse_bits`] already owns one transcription of.
-///
-/// `0x6f1990` writes `*out` only on a hit, and the local was pre-loaded with `1`, so an **absent,
-/// empty or unrecognised** `align` leaves the block at LEFT. `top`/`middle`/`bottom` are accepted
-/// and yield 8/16/32, which mask to `& 7 == 0` — a block with no justifyH bit set at all. That is
-/// a degenerate state the binary really reaches, not a rejection.
+/// A block's `align` (`0x78a7cf`) through the shared enum (`0x811ad0`, [`justify::parse_bits`]):
+/// absent, empty or unknown stays LEFT, as `0x6f1990` writes only on a hit. `top`, `middle` and
+/// `bottom` give 8, 16 and 32, which leave no justifyH bit, in the reference too.
 fn align_of(node: roxmltree::Node) -> u32 {
     attr_ci(node, "align")
         .filter(|v| !v.is_empty())
@@ -286,18 +224,16 @@ fn align_of(node: roxmltree::Node) -> u32 {
         .unwrap_or(ALIGN_LEFT)
 }
 
-/// Attribute lookup, **case-insensitively** — every attribute-name compare in this engine goes
-/// through `0x64a4c0` → `SStrCmpI 0x414310` (§1.3), so `ALIGN`/`Align`/`align` are one attribute.
-/// roxmltree's own `Node::attribute` is case-sensitive, which is why this scan exists.
+/// Case-insensitive attribute lookup, as the reference compares names (`0x64a4c0`, `SStrCmpI`
+/// `0x414310`); roxmltree's own lookup is case-sensitive.
 fn attr_ci<'a>(node: roxmltree::Node<'a, '_>, name: &str) -> Option<&'a str> {
     node.attributes()
         .find(|a| a.name().eq_ignore_ascii_case(name))
         .map(|a| a.value())
 }
 
-/// An element's own direct character data, concatenated in document order — the `<A>`'s inner
-/// text. roxmltree's `Node::text` answers only the FIRST text child, which a comment or an entity
-/// boundary is enough to split.
+/// An element's direct text, all of it: roxmltree's `Node::text` gives only the first text child,
+/// which a comment splits.
 fn direct_text(node: roxmltree::Node) -> String {
     node.children()
         .filter(roxmltree::Node::is_text)
@@ -305,14 +241,9 @@ fn direct_text(node: roxmltree::Node) -> String {
         .collect()
 }
 
-/// `SStrPrintf(tmp, len, hyperlinkFormat, href, innerText)` (`0x78a97b` → `0x64a7f0`) — a C
-/// `printf` with exactly two arguments, both strings.
-///
-/// Only `%s` and `%%` are honoured; any other spec is copied through verbatim rather than
-/// consuming an argument. A real `printf` given `%d` and a `char*` would read the pointer as an
-/// integer, which is not behaviour worth reproducing, and `SetHyperlinkFormat` is a
-/// player-reachable string — the ctor default `"|H%s|h%s|h"` and every format an addon writes are
-/// two-`%s` templates.
+/// `SStrPrintf` of the format with `href` and the inner text (`0x78a97b`, `0x64a7f0`). Deviation:
+/// only `%s` and `%%` are expanded and other specs copied, because the real `printf` would read the
+/// string pointers as other types.
 fn sprintf_two(fmt: &str, a: &str, b: &str) -> String {
     let mut out = String::with_capacity(fmt.len() + a.len() + b.len());
     let mut used = 0usize;
@@ -342,10 +273,8 @@ fn sprintf_two(fmt: &str, a: &str, b: &str) -> String {
     out
 }
 
-/// C's `atof` (`0x64aaa0`), as `<IMG width=>`/`height=` reach it: leading whitespace skipped, the
-/// longest valid numeric prefix parsed, **0 on no parse at all** — `"12px"` is 12, `"px"` is 0.
-/// Rust's `str::parse` rejects a trailing suffix outright, which would turn a sloppy but working
-/// `width="100 "` into a zero-width image.
+/// C's `atof` (`0x64aaa0`) for `width=` and `height=`: the longest numeric prefix after leading
+/// whitespace, 0 when there is none, so `"12px"` is 12.
 fn atof(s: &str) -> f32 {
     let b = s.as_bytes();
     let mut i = 0;
@@ -365,7 +294,7 @@ fn atof(s: &str) -> f32 {
             i += 1;
         }
     }
-    // An exponent counts only when it is complete — `"1e"` is 1, matching strtod's own backtrack.
+    // An exponent counts only when complete: `"1e"` is 1, as `strtod` backtracks.
     if i < b.len() && (b[i] | 0x20) == b'e' {
         let mut j = i + 1;
         if j < b.len() && (b[j] == b'+' || b[j] == b'-') {
@@ -381,31 +310,16 @@ fn atof(s: &str) -> f32 {
     s[start..i].parse::<f32>().unwrap_or(0.0)
 }
 
-/// The HTML-style whitespace collapse, §6.3 — `0x78a8af`–`0x78aa87`, a three-arm dispatch through
-/// the jump table at `.text 0x78aab8` with the byte remap at `.text 0x78aac4`.
-///
-/// | arm | characters | behaviour |
-/// |---|---|---|
-/// | 0 `0x78aa34` | `\t` `\n` `\r` ` ` | suppress-leading → drop; a space already pending → drop; else emit one `0x20` and set pending |
-/// | 1 `0x78aa46` | `\|` followed by `n` | un-emit a pending space (`0x78aa54 dec eax`), clear pending, emit `\|n`, set suppress-leading, skip both bytes |
-/// | 2 `0x78aa66` | everything else, `\|` **not** followed by `n` included | clear suppress-leading and pending, emit the byte verbatim |
-///
-/// Tail `0x78aa7b` removes a trailing pending space. Net: **leading and trailing whitespace
-/// trimmed, every internal run of tabs/newlines/CRs/spaces collapsed to one space, and a space
-/// immediately before a `|n` removed** — exactly HTML's rule.
-///
-/// It is byte-wise and can still never split a UTF-8 sequence: the index is computed with the
-/// **signed** widening `0x78a8c5 movsx edi,bl`, so every byte `>= 0x80` goes negative and the
-/// unsigned `cmp edi,0x73; ja` sends it to arm 2 — lead and continuation bytes alike are copied
-/// verbatim. Operating on `&[u8]` here reproduces that exactly, and the result is valid UTF-8 by
-/// construction because only ASCII whitespace is ever dropped.
-///
-/// **This applies to markup blocks only.** The §3 plain-text path bypasses it entirely.
+/// The whitespace collapse of markup blocks (`0x78a8af`-`0x78aa87`; the fallback at `0x78a501`
+/// skips it): leading and trailing whitespace dropped, each run of tabs, newlines, CRs and spaces
+/// made one space, and whitespace on either side of `|n` removed. Its arms: whitespace
+/// (`0x78aa34`), `|n` (`0x78aa46`, `0x78aa54`), any other byte (`0x78aa66`), and a tail that drops
+/// a pending space (`0x78aa7b`). A byte from `0x80` up widens negative (`0x78a8c5`) and takes the
+/// verbatim arm, so UTF-8 is never split.
 fn collapse(buf: &str) -> String {
     let src = buf.as_bytes();
     let mut out: Vec<u8> = Vec::with_capacity(src.len());
-    // `dl` — "a space is already pending" — and `[ebp+0xb]`, "suppress leading whitespace",
-    // initialised to **1** so a block never starts with a space.
+    // Suppression starts on, so a block never starts with a space.
     let mut pending_space = false;
     let mut suppress_leading = true;
     let mut i = 0;
@@ -458,14 +372,13 @@ mod tests {
     fn collapse_is_htmls_rule() {
         assert_eq!(collapse("  a \t\n b  "), "a b");
         assert_eq!(collapse("a \n\n b"), "a b");
-        // A space immediately before a `|n` is removed; whitespace right after one is suppressed.
+        // A space right before `|n` is removed; whitespace right after one is suppressed.
         assert_eq!(collapse("a |n b"), "a|nb");
-        // A `|` not followed by `n` is verbatim — colour spans and hyperlinks survive.
+        // A `|` not before `n` is verbatim, so colour codes survive.
         assert_eq!(
             collapse("  |cffff0000red|r  text  "),
             "|cffff0000red|r text"
         );
-        // Multi-byte sequences are never split (the signed-widening arm-2 fall-through).
         assert_eq!(collapse("  héllo  wörld "), "héllo wörld");
         assert_eq!(collapse("   "), "");
     }
@@ -530,7 +443,7 @@ mod tests {
 
     #[test]
     fn an_empty_body_renders_nothing_at_all() {
-        // `usedMarkup` is raised BEFORE the walker runs (`0x78a4b6`), so this does NOT fall back.
+        // `usedMarkup` rises before the walk (`0x78a4b6`), so this does not fall back.
         let p = parse_markup("<HTML><BODY/></HTML>", "F", DEFAULT_HYPERLINK_FORMAT);
         assert!(p.used_markup);
         assert!(p.blocks.is_empty());
@@ -670,8 +583,7 @@ mod tests {
         }
     }
 
-    /// The `page_text` shape §8 quotes, end to end: an `<H1>` title, a `<BR/>`, and centred
-    /// paragraphs, with the body's own inter-tag newlines contributing nothing.
+    /// A stock `page_text` body: an `<H1>` title, `<BR/>`s and centred paragraphs.
     #[test]
     fn the_page_text_shape_walks_to_the_block_list_a_reader_would_draw() {
         let p = parse_markup(
@@ -703,9 +615,8 @@ mod tests {
         assert!(p.errors.is_empty());
     }
 
-    /// The §8 signed-page consequence: `ItemTextFrame.lua` appends `From: <creator>` **after**
-    /// `</HTML>`, which is expat error 9 — so a signed HTML page renders as raw markup on the
-    /// reference client too. Our fallback must reach the same place rather than "fixing" it.
+    /// Stock `ItemTextFrame.lua` appends `From: <creator>` after `</HTML>`, expat error 9
+    /// (`0x881fec`), so a signed page renders as raw markup on the reference too.
     #[test]
     fn a_signed_html_page_falls_back_exactly_as_the_reference_does() {
         let raw = "\n<HTML><BODY><P>The letter body.</P></BODY></HTML>\n\nFrom:\nMankrik\n\n";
diff --git a/crates/benilla-ui/src/script/skills.rs b/crates/benilla-ui/src/script/skills.rs
index 6e081251..9f639f6a 100644
--- a/crates/benilla-ui/src/script/skills.rs
+++ b/crates/benilla-ui/src/script/skills.rs
@@ -1,79 +1,16 @@
-//! The skills-pane bindings (decision 0437 phase 4) — the Era-shaped `SkillFrame` surface driving
-//! a faithful port of the real 1.12 Skills tab (extracted from `interface.MPQ`: FrameXML
-//! `SkillFrame.{xml,lua}`). Unlike [`super::tradeskill`]'s deliberately FLAT v1 recipe list, this
-//! pane needs the trainer's own GROUP/TREE machinery ([`super::trainer`], decision 0247): the app
-//! pushes a flat, unordered snapshot ([`UiScript::set_skills`] — [`SkillsState::entries`], each
-//! already resolved to name/category by the app from `SkillLine.dbc`/`SkillLineCategory.dbc`), and
-//! the ENGINE groups by category, sorts, and folds — the trainer's synthesized-tree pattern, minus
-//! the state filter (a skill line carries no green/red/gray category) and minus the wire skill-line
-//! id doing double duty as both the row's identity and the group key (here the GROUP key is the
-//! category, the row's identity is the skill id).
+//! The skills-pane bindings behind the stock `SkillFrame`. The app pushes a flat snapshot of known
+//! skill lines, resolved from `SkillLine.dbc` and `SkillLineCategory.dbc`, and the engine groups,
+//! sorts and folds it as the client's list build (`0x4d2cb0`, comparator `0x4d3070`) does: one
+//! header per category, by `category_order` (category id breaks a tie), and within a category the
+//! untrained lines (rank 0) after the trained ones, each by name. A push re-expands every group.
+//! Every Lua index is 1-based into the visible rows, headers plus the entries of expanded groups;
+//! the selection is held by skill id, so it survives a re-push, and selecting a header clears it.
+//! Which lines reach the engine at all is the app's half (`feed_skills`).
 //!
-//! ## The engine grouping law (PINNED at the bytes — decision 1091; wow-re
-//! `system/tradeskill/scratch/skillframe-display-list.md`, the list build `0x4d2cb0` + its
-//! comparator `0x4d3070`. The 0530 follow-up this once carried is closed.)
-//!
-//! Groups ordered by `category_order` ascending (`category_id` breaks a tie, for determinism);
-//! one header row per non-empty group (text = `category_name`); within a group, **untrained lines
-//! (rank 0) sink below trained ones**, then name ascending ([`collate`] — case-insensitive,
-//! raw-byte tie-break; the client's own `stricmp`). Every group starts EXPANDED and is **re-expanded
-//! on every push** ([`UiScript::set_skills`] — the client's own `expandedMask = 0xFFFFFFFF`).
-//! Visible rows are headers always, plus the entries of expanded groups; every index the Lua API
-//! takes/returns is 1-based into that visible list.
-//!
-//! **Which lines reach the engine at all is the app's half** of the same law (`ui_char.rs`'s
-//! `feed_skills`): the client's list build drops a line with no `SkillLine`/`SkillRaceClassInfo`/
-//! `SkillLineCategory` row, one whose `SkillRaceClassInfo.flags` carries `0x2`, and an untrained
-//! one that no flag admits. The engine sorts what survives.
-//!
-//! ## The Era API shape (matched to the real `SkillFrame.lua`, transcribed onto this engine)
-//!
-//! `GetNumSkillLines()` → the visible row count. `GetSkillLineInfo(i)` → the ref's own tuple
-//! (`name, isHeader, isExpanded, skillRank, numTempPoints, skillModifier, skillMaxRank,
-//! isAbandonable, stepCost, rankCost, minLevel, skillCostType, skillDescription`) — **13 values on
-//! a skill row, 12 on a header** (`0x4d3a20` vs `0x4d3768`; a header stops after `skillCostType`
-//! and carries no description slot at all). A header shapes
-//! `(category_name, 1, expanded, 0, 0, 0, 0, nil, nil, nil, 0, 0)`, an entry
-//! `(name, nil, nil, rank, 0, tempBonus, max, abandonable, nil, nil, minLevel, costIndex+1,
-//! description)`, with `rank`/`max` computed by [`displayed_ranks`] — the permanent bonus folded
-//! in, then `max` forced to `1` on a **single-rank** line whatever the server said
-//! ([`SkillEntry::mono`]; the pane's proficiency gate is `skillMaxRank == 1`).
-//!
-//! `numTempPoints` is a **REAL FIELD** (`entry->+0x10`) that this client answers as `0`. The
-//! distinction matters and this comment used to blur it (decision 1919): the field has four writers
-//! in the real client — zeroed per list rebuild (`0x4d2e2e`), incremented by `AddSkillUp`'s worker
-//! (`0x4d345b`), decremented at `0x4d358a`, reset by `CancelSkillUps` (`0x4d35c9`) — and
-//! `SkillFrame.xml:697` wires `AddSkillUp` for real. What is true is a **data-reachability** verdict
-//! about the shipped tables, not a property of the field: the `rankCost or numTempPoints > 0` guard
-//! never opens on 1.12's data, so nothing a player can hold moves it off `0`. Say `0` because the
-//! model carries no temp points, never because the field is fictional — the day we model training
-//! points this is a value to push, not a constant to keep. `stepCost`/`rankCost` are always **nil** —
-//! for DATA reasons, not code ones (`SkillLine.skillCostsID` is 0 in all 123 rows, and the
-//! step-cost gate's flag bits are set on no line a player can hold) — and nil, not `0`, is what
-//! the ref's `if (stepCost)` / `elseif (rankCost or …)` branches read, since `0` is truthy in Lua.
-//! `minLevel` and `skillCostType` are REAL numbers off the `SkillRaceClassInfo` row (visually inert
-//! on this build: every branch they colour is repainted by the normal-skill/proficiency branches
-//! after it). `skillDescription` is REAL (`SkillLine.dbc` col 12 through the app feed — the detail
-//! pane's body text); `isAbandonable` is REAL too ([`SkillEntry::abandonable`], the unlearn
-//! button's gate — and `AbandonSkill(i)` is its outbound half, a VISIBLE index queued out by skill
-//! id for the app's `CMSG_UNLEARN_SKILL`, [`UiScript::take_skill_abandons`]).
-//!
-//! `ExpandSkillHeader(i)`/`CollapseSkillHeader(i)` take a header's VISIBLE index (`0` = all
-//! groups, the trainer's own collapse-all shape). `SetSelectedSkill(i)`/`GetSelectedSkill()` are a
-//! VISIBLE index too, but the engine holds the selection BY SKILL ID internally (the tradeskill's
-//! own by-spell-id persistence pattern, [`super::tradeskill::UiScript::set_trade_skill`]) so it
-//! survives a re-push that reorders or regroups; selecting a header (or an out-of-range index)
-//! clears it. `GetAdjustedSkillPoints()` is a vestigial 1.12 leftover the ref reads; it always
-//! returns `0` — there is no training-point economy behind a skill line in this client.
-//!
-//! `CancelSkillUps()` is bound (the page's Close button calls it, 1956): the temp-point reset
-//! over a table this model keeps empty.
-//!
-//! The ref Lua's other globals (`SkillBar_OnClick`'s `RemoveSkillUp`/`AddSkillUp`/`BuySkillTier`,
-//! `UnitCharacterPoints`) back the training-up machinery this pane doesn't ship (0437's named
-//! out-of-scope) — none are transcribed, engine-side or XML-side, rather than stubbing dead call
-//! sites nothing in [`SkillFrame.xml`] ever reaches. (The `UNLEARN_SKILL` popup, once in that
-//! list, ships for real now — the abandon slice above.)
+//! `numTempPoints` answers 0: the model carries no temp points, and on 1.12's data nothing a player
+//! holds moves the reference's field (`+0x10`), which only `AddSkillUp` increments (`0x4d345b`).
+//! `stepCost` and `rankCost` are always nil, by the data: `SkillLine.skillCostsID` is 0 in every
+//! row and no line a player holds carries the step-cost flags.
 
 use std::collections::HashMap;
 
@@ -81,95 +18,64 @@ use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One known skill line off the player's `PLAYER_SKILL_INFO` block, app-resolved (0437 phase 4).
-/// EXACT shape the app feed (`crates/benilla/src/ui_char.rs`) is written against — do not rename.
+/// One known skill line off the player's `PLAYER_SKILL_INFO` block, resolved by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct SkillEntry {
     pub skill_id: u32,
-    /// `SkillLine.dbc` name ("First Aid").
+    /// The `SkillLine.dbc` name.
     pub name: String,
-    /// Current rank, raw off the descriptor. `0` = **untrained**, which is a sort key of its own
-    /// (untrained lines sink under their category's trained ones — the client's comparator
-    /// `0x4d3070`).
+    /// The raw rank off the descriptor; 0 is untrained, which sorts below the trained lines.
     pub value: u32,
-    /// Max rank, as the server's own `PLAYER_SKILL_INFO` descriptor holds it — see [`Self::mono`]
-    /// for the DBC override the API return goes through.
+    /// The raw max rank off the descriptor; [`Self::mono`] overrides it at the API return.
     pub max: u32,
-    /// `SkillRaceClassInfo.flags & 0x400` (`SKILL_FLAG_MONO_VALUE`) for the player's race/class:
-    /// a **single-rank** line. The real client's `GetSkillLineInfo` overrides `skillMaxRank` to
-    /// `1` for these, whatever the descriptor says (wow-re
-    /// `system/tradeskill/scratch/skillframe-seed-abandon.md`: `0x4d3610`, `4d38b1 test ah,0x4`) —
-    /// so a hunter's `Beast Mastery`, which vmangos happily reports as `300/300`, reads as a
-    /// proficiency and `SkillFrame.lua`'s `skillMaxRank == 1` branch draws it gray with no rank
-    /// text. The raw [`Self::max`] stays untouched here; the override lives at the API return,
-    /// exactly where the binary puts it.
+    /// `SkillRaceClassInfo.flags & 0x400` (`SKILL_FLAG_MONO_VALUE`): a single-rank line, whose
+    /// `skillMaxRank` the client reports as 1 whatever the descriptor says (`0x4d3610`), so
+    /// vmangos's 300/300 Beast Mastery reads as a proficiency.
     pub mono: bool,
-    /// The **temporary** bonus (auras/consumables/enchants; negative possible) — and only that:
-    /// `GetSkillLineInfo`'s `skillModifier` is a signed read of the descriptor's temp half alone
-    /// (`+0x850`), the green "+n" in the rank text. The permanent half is [`Self::perm_bonus`],
-    /// which the client folds into the numbers instead.
+    /// The temporary bonus, possibly negative: `skillModifier`, a signed read of the descriptor's
+    /// temp half alone (`+0x850`).
     pub temp_bonus: i32,
-    /// The **permanent** bonus (talents; `+0x852`, negative possible). Not a return of its own:
-    /// the client adds it into BOTH `skillRank` and `skillMaxRank` before the mono override
-    /// (`0x4d380c`/`0x4d385d`), and only when the raw value is nonzero — so a line the player
-    /// doesn't have stays at a flat `0`, never `0 + bonus`.
+    /// The permanent bonus (`+0x852`), possibly negative, folded into both ranks when they are
+    /// nonzero (`0x4d380c`/`0x4d385d`).
     pub perm_bonus: i32,
-    /// `SkillRaceClassInfo.reqLevel` — `GetSkillLineInfo`'s 11th return, pushed as a real number
-    /// (`0x4d39ef`; nonzero in practice: Mail 40, Dual Wield 20).
+    /// `SkillRaceClassInfo.reqLevel`, `GetSkillLineInfo`'s 11th return (`0x4d39ef`).
     pub min_level: u32,
-    /// `SkillRaceClassInfo.skillCostID` — `GetSkillLineInfo`'s 12th return is this **plus one**
-    /// (`0x4d3a06`), which is why the engine adds the 1, not the feed.
+    /// `SkillRaceClassInfo.skillCostID`; the 12th return is this plus one (`0x4d3a06`), added by
+    /// the engine.
     pub cost_index: u32,
     /// `SkillLine.dbc` categoryId.
     pub category_id: u32,
-    /// Resolved category name ("Professions") — the header text.
+    /// The category name, the header text.
     pub category_name: String,
-    /// `SkillLineCategory` displayOrder — the group sort key.
+    /// `SkillLineCategory` displayOrder, the group sort key.
     pub category_order: u32,
-    /// `SkillLine.dbc` description (enUS column 12) — `GetSkillLineInfo`'s 13th return, the
-    /// detail pane's body text (empty when the row carries none; the XML's `SKILL_DESCRIPTION`
-    /// format renders it verbatim).
+    /// `SkillLine.dbc` description (enUS column 12), `GetSkillLineInfo`'s 13th return.
     pub description: String,
-    /// Whether the line can be unlearned — `GetSkillLineInfo`'s 8th return (`isAbandonable`), the
-    /// detail pane's unlearn-button gate. App-resolved, and a **conjunction**: the descriptor's
-    /// skill **step** must be nonzero AND `SkillRaceClassInfo.flags & 0x20` must be set
-    /// (`SKILL_FLAG_UNLEARNABLE` — the server's own `CMSG_UNLEARN_SKILL` gate, vmangos
-    /// `SkillHandler.cpp`). Both halves are the client's (`0x4d3953`–`0x4d3975`).
+    /// `isAbandonable`, the 8th return: a nonzero skill step and `SkillRaceClassInfo.flags & 0x20`
+    /// (`SKILL_FLAG_UNLEARNABLE`), both checked by the client (`0x4d3953`–`0x4d3975`).
     pub abandonable: bool,
 }
 
-/// A flat, unordered push of every known skill line (0437 phase 4) — the ENGINE groups and sorts
-/// (see the module doc's grouping law). EXACT shape the app feed is written against — do not
-/// rename.
+/// A flat, unordered push of every known skill line; the engine groups and sorts it.
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct SkillsState {
     pub entries: Vec<SkillEntry>,
 }
 
-/// One category group in the synthesized display tree: the header's id/name/sort key and the
-/// positions (into [`SkillsState::entries`]) of the category's lines, pre-sorted by name —
-/// mirrors [`super::trainer::TrainerGroup`], but the group key is a *category*, never the wire
-/// skill line itself. Engine-internal (never crosses the app seam, unlike [`SkillsState`]);
-/// `pub(crate)` only because [`super::model::Model`] stores a `Vec` of them.
+/// One category of the display tree, with its lines' positions in [`SkillsState::entries`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct SkillGroup {
     category_id: u32,
     name: String,
     order: u32,
-    /// Positions into [`SkillsState::entries`], sorted by [`collate`]d name.
+    /// Positions into [`SkillsState::entries`], in display order.
     entries: Vec<usize>,
 }
 
 impl super::UiScript {
-    /// Replace the skills snapshot (0437 phase 4). Builds the display tree ([`build_groups`]) from
-    /// the flat entries, **re-expands every group**, and re-anchors the selection to the SAME
-    /// skill id if it's still present — else clears it (the tradeskill's own by-spell-id
-    /// selection-persistence precedent).
-    ///
-    /// The re-expand is the client's, not a convenience: its list rebuild writes
-    /// `expandedMask = 0xFFFFFFFF` unconditionally (`0x4d2cb0`, store at `0x4d2ce2`), so a fold
-    /// survives only until the next skill-field change — the trainer's collapse-survives-an-update
-    /// rule this pane once borrowed is simply a different window's law (decision 1091).
+    /// Replace the skills snapshot: rebuild the tree, re-expand every group (the client's rebuild
+    /// stores `expandedMask = 0xFFFFFFFF` at `0x4d2ce2`) and keep the selection if its skill is
+    /// still present.
     pub fn set_skills(&mut self, state: SkillsState) {
         let mut model = self.model_mut();
         let groups = build_groups(&state.entries);
@@ -183,34 +89,29 @@ impl super::UiScript {
         model.skills = state;
     }
 
-    /// Drain the skill line ids `AbandonSkill` queued (the unlearn seam) — the app sends each as
-    /// one `CMSG_UNLEARN_SKILL` and otherwise does nothing: the removal arrives back as a server
-    /// skill-field update, never a local mutation ([`Model::skill_abandons`]).
+    /// Drain the skill ids `AbandonSkill` queued, one `CMSG_UNLEARN_SKILL` each; the removal comes
+    /// back as a skill-field update.
     pub fn take_skill_abandons(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().skill_abandons)
     }
 }
 
-/// One visible row of the display tree: a category **header** (carrying its group index) or an
-/// **entry** (carrying its position into [`SkillsState::entries`]).
+/// One visible row: a header (its group index) or an entry (its position in
+/// [`SkillsState::entries`]).
 #[derive(Clone, Copy)]
 enum Row {
     Header(usize),
     Entry(usize),
 }
 
-/// The WoW enUS collator, approximated (the trainer's own [`super::trainer`] helper, duplicated
-/// here rather than shared — each seam module keeps its own copy, the established local
-/// convention): case-insensitive alphabetical, raw bytes as a stable tie-break.
+/// The client's `stricmp`, approximated: case-insensitive, raw bytes as the tie-break.
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
         .then_with(|| a.cmp(b))
 }
 
-/// Build the display tree from the flat entries (the module doc's grouping law): group by
-/// category, sort each group's entries by name, sort the groups by `category_order` (category id
-/// breaks a tie). Entry positions index back into the unchanged `entries` slice.
+/// Build the display tree by the module doc's grouping rule.
 fn build_groups(entries: &[SkillEntry]) -> Vec<SkillGroup> {
     let mut map: HashMap<u32, SkillGroup> = HashMap::new();
     for (i, e) in entries.iter().enumerate() {
@@ -226,9 +127,8 @@ fn build_groups(entries: &[SkillEntry]) -> Vec<SkillGroup> {
     }
     let mut groups: Vec<SkillGroup> = map.into_values().collect();
     for g in &mut groups {
-        // Within a category the client sorts UNTRAINED (rank 0) lines below trained ones, then by
-        // name (`0x4d3070`: the `untrained` byte set at build time, `0x4d2e19 sete`, compared
-        // before the `stricmp` at `0x4d318d`).
+        // Untrained below trained, then by name (`0x4d3070` compares the untrained byte, set at
+        // `0x4d2e19`, before the `stricmp` at `0x4d318d`).
         g.entries.sort_by(|&a, &b| {
             (entries[a].value == 0)
                 .cmp(&(entries[b].value == 0))
@@ -243,8 +143,7 @@ fn build_groups(entries: &[SkillEntry]) -> Vec<SkillGroup> {
     groups
 }
 
-/// The visible rows in display order: each group's header (always shown), then — when the group
-/// isn't collapsed — its entries. The Lua's 1-based `index` is a position in *this* list.
+/// The visible rows; the Lua's 1-based index is a position in this list.
 fn rows(model: &Model) -> Vec<Row> {
     let mut out = Vec::new();
     for (gi, g) in model.skills_groups.iter().enumerate() {
@@ -258,13 +157,11 @@ fn rows(model: &Model) -> Vec<Row> {
     out
 }
 
-/// The count of visible rows (headers + the entries of expanded groups).
 fn num_rows(model: &Model) -> usize {
     rows(model).len()
 }
 
-/// The entry at a 1-based VISIBLE index, or `None` when that row is a header (or OOB) — so the
-/// selection/info getters that read an entry safely no-op on a header row.
+/// The entry at a 1-based visible index; `None` for a header.
 fn entry_at(model: &Model, index: usize) -> Option<&SkillEntry> {
     let n = index.checked_sub(1)?;
     match rows(model).get(n)? {
@@ -273,10 +170,8 @@ fn entry_at(model: &Model, index: usize) -> Option<&SkillEntry> {
     }
 }
 
-/// Collapse (`collapse = true`) or expand a category by the **display index of its header row**
-/// (the trainer's own `Collapse/ExpandTrainerSkillLine` shape). `id == 0` targets ALL groups (the
-/// collapse-all button); `id > 0` resolves the header at that visible index to its category. A
-/// non-header (or OOB) index is a no-op.
+/// Collapse or expand the category whose header is at visible index `id`; 0 is every group, and a
+/// non-header index does nothing.
 fn set_collapsed(model: &mut Model, id: usize, collapse: bool) {
     if id == 0 && !collapse {
         model.skills_collapsed.clear();
@@ -304,19 +199,10 @@ fn set_collapsed(model: &mut Model, id: usize, collapse: bool) {
     }
 }
 
-/// `SetSelectedSkill(index)` — resolve the 1-based VISIBLE index to a skill id and hold THAT (the
-/// module doc's by-id persistence); a header row or an out-of-range index clears the selection.
-/// `GetSkillLineInfo`'s **out-of-range tuple** — thirteen values, four of them numeric zeros.
-///
-/// Byte-verified in wow-re's `system/tradeskill/scratch/skillframe-selection-and-oob.md` (pushes
-/// `0x4d3a2c`…`0x4d3a98`, `mov eax,0xd` at `0x4d3a9f`); decision 1919. One shape serves five
-/// distinct conditions — index 0, a negative index, an index past the end, no active player, and an
-/// in-range row whose DBC record is missing — because the reference's bounds test (`0x4d3675`) is a
-/// single UNSIGNED compare that funnels them all to the same exit.
-///
-/// The numeric slots are 4 (`skillRank`), 5 (`numTempPoints`), 6 (`skillModifier`), 7
-/// (`skillMaxRank`), 11 (`minLevel`) and 12 (`skillCostType`). Slots 4 and 5 must be numbers or the
-/// reference's own unguarded `skillRank + numTempPoints` raises.
+/// `GetSkillLineInfo`'s out-of-range answer, thirteen values (`0x4d3a2c`…`0x4d3a98`): the
+/// reference's one unsigned bounds test (`0x4d3675`) sends index 0, a negative or past-the-end
+/// index, no player and a missing DBC row here. Slots 4 and 5 must be numbers: stock
+/// `SkillFrame.lua:194` adds them unguarded, and `SkillFrame_OnLoad` calls `SetSelectedSkill(0)`.
 fn out_of_range_tuple(_lua: &Lua) -> mlua::Result<MultiValue> {
     Ok(MultiValue::from_vec(vec![
         Value::Nil,        // 1  skillName
@@ -339,8 +225,7 @@ fn set_selected(model: &mut Model, index: u32) {
     model.skills_selected = entry_at(model, index as usize).map(|e| e.skill_id);
 }
 
-/// `GetSelectedSkill()` — the selection's CURRENT visible index (`0` when nothing is selected, or
-/// the selected id isn't visible right now, e.g. its group just got collapsed).
+/// `GetSelectedSkill()`: the selection's current visible index, 0 when none or folded away.
 fn selected_index(model: &Model) -> u32 {
     let Some(sid) = model.skills_selected else {
         return 0;
@@ -351,19 +236,15 @@ fn selected_index(model: &Model) -> u32 {
         .map_or(0, |p| (p + 1) as u32)
 }
 
-/// `GetSkillLineInfo`'s `(skillRank, skillMaxRank)` pair for one entry — the client's own
-/// arithmetic, in its own order (`0x4d380c`–`0x4d38cb`):
+/// `GetSkillLineInfo`'s `(skillRank, skillMaxRank)`, in the client's order (`0x4d380c`–`0x4d38cb`):
 ///
 /// ```text
-/// skillRank    = rank > 0 ? rank + permBonus : rank        // a line at 0 stays flat 0
+/// skillRank    = rank > 0 ? rank + permBonus : rank
 /// skillMaxRank = max  > 0 ? max  + permBonus : max
-/// if mono { skillMaxRank = 1; if skillRank > 1 { skillRank = 1 } }   // override, then a MIN
+/// if mono { skillMaxRank = 1; if skillRank > 1 { skillRank = 1 } }
 /// ```
 ///
-/// The mono arm is an unconditional **override** of the max (not a clamp) and a **min** on the
-/// rank — the asymmetry is the binary's, and it is what makes a `300/300` class line read as the
-/// `1/1` proficiency `SkillFrame.lua` draws gray. Saturating at 0 keeps a negative permanent
-/// malus from wrapping the unsigned descriptor values.
+/// Saturating at 0 keeps a negative permanent bonus from wrapping.
 fn displayed_ranks(e: &SkillEntry) -> (i64, i64) {
     let fold = |v: u32| {
         if v > 0 {
@@ -380,8 +261,7 @@ fn displayed_ranks(e: &SkillEntry) -> (i64, i64) {
     (rank, max)
 }
 
-/// A `bool` as the Era `1`/`nil` shape (the trainer/tradeskill's own helper, duplicated per the
-/// established per-module convention).
+/// A `bool` as the 1.12 `1`/nil shape.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -403,24 +283,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSkillLineInfo(index) → the ref's own tuple: 13 values on a skill row (`0x4d3a20`), 12 on
-    // a header (`0x4d3768`). `index` 1-based.
-    //
-    // **OUT OF RANGE IS THE 13-VALUE FALLBACK, NOT A SINGLE NIL.** This comment used to say the
-    // opposite and it was wrong; the correction is decision 1919, from a wow-re trio cross-check
-    // (`system/tradeskill/scratch/skillframe-selection-and-oob.md`). `0x4d3675`'s bounds test is
-    // UNSIGNED against the total row count, so index 0, a negative index, an index past the end, no
-    // active player, and an in-range row whose DBC record is missing all fall to `0x4d3a2a` and push
-    // the same thirteen: `nil, nil, nil, 0, 0, 0, 0, nil, nil, nil, 0, 0, nil` (`0x4d3a2c`…
-    // `0x4d3a98`, then `mov eax,0xd`).
-    //
-    // **Slots 4 and 5 being NUMBERS is the whole point.** The reference's own
-    // `SkillDetailFrame_SetStatusBar` does `skillRank = skillRank + numTempPoints`
-    // (`SkillFrame.lua:193-194`) with NO guard, straight off `SkillFrame_OnLoad`'s
-    // `SetSelectedSkill(0)` — so a single nil here raises "attempt to perform arithmetic on a nil
-    // value" the moment the stock file drives us. Slot 1 being nil is what drives its
-    // `if (not skillName …) then … return` at l.211. The selection verbs are NOT the divergence:
-    // `GetSelectedSkill 0x4d4090` always pushes exactly one number and legitimately answers 0.
+    // GetSkillLineInfo(index) → 13 values on a skill row (`0x4d3a20`), 12 on a header
+    // (`0x4d3768`); out of range, the 13-value tuple (`0x4d3a2a`), whose nil first slot drives
+    // stock `SkillFrame.lua:211`'s early return.
     g.set(
         "GetSkillLineInfo",
         lua.create_function(|lua, index: usize| {
@@ -440,14 +305,14 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         Value::Integer(1), // isHeader
                         era_bool(expanded),
                         Value::Integer(0), // skillRank
-                        Value::Integer(0), // numTempPoints — a real field; 0 because we model no temp points (1919)
+                        Value::Integer(0), // numTempPoints
                         Value::Integer(0), // skillModifier
                         Value::Integer(0), // skillMaxRank
                         Value::Nil,        // isAbandonable
                         Value::Nil,        // stepCost
                         Value::Nil,        // rankCost
                         Value::Integer(0), // minLevel
-                        Value::Integer(0), // skillCostType — the 12th and LAST header return
+                        Value::Integer(0), // skillCostType, the last header return
                     ]))
                 }
                 Row::Entry(ei) => {
@@ -458,18 +323,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         Value::Nil, // isHeader
                         Value::Nil, // isExpanded
                         Value::Integer(rank),
-                        Value::Integer(0), // numTempPoints — a real field; 0 because we model no temp points (1919)
-                        Value::Integer(i64::from(e.temp_bonus)), // skillModifier — TEMP only
+                        Value::Integer(0),                       // numTempPoints
+                        Value::Integer(i64::from(e.temp_bonus)), // skillModifier: temp only
                         Value::Integer(max),
                         era_bool(e.abandonable), // isAbandonable
-                        // stepCost/rankCost are nil on this build for DATA reasons, not code
-                        // ones (module doc) — and nil is load-bearing: `0` is truthy in Lua, so
-                        // returning it would send SkillFrame.lua down its "learnable skill"
-                        // branch on every row.
+                        // stepCost, rankCost: nil, since Lua reads `0` as true.
                         Value::Nil,
                         Value::Nil,
-                        Value::Integer(i64::from(e.min_level)), // minLevel — a real number
-                        // skillCostType — SkillCostIndex + 1, the client's own `0x4d3a06`.
+                        Value::Integer(i64::from(e.min_level)), // minLevel
+                        // skillCostType: the cost index plus one (`0x4d3a06`).
                         Value::Integer(i64::from(e.cost_index) + 1),
                         Value::String(lua.create_string(&e.description)?), // skillDescription
                     ]))
@@ -478,8 +340,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Collapse/ExpandSkillHeader(id) — fold a category by the display index of its header row (id
-    // 0 = all groups); a non-header (or OOB) index no-ops.
+    // Collapse/ExpandSkillHeader(id): by the header's visible index, 0 for every group.
     g.set(
         "CollapseSkillHeader",
         lua.create_function(|lua, id: usize| {
@@ -497,8 +358,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSelectedSkill(index) / GetSelectedSkill() — the engine-held selection, VISIBLE index in,
-    // VISIBLE index out, held BY SKILL ID internally (module doc).
+    // SetSelectedSkill(index) / GetSelectedSkill(): visible indices, held by skill id;
+    // `GetSelectedSkill` (`0x4d4090`) always answers one number, 0 included.
     g.set(
         "SetSelectedSkill",
         lua.create_function(|lua, index: u32| {
@@ -515,18 +376,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetAdjustedSkillPoints() → 0 — a vestigial 1.12 leftover the ref reads (module doc); this
-    // client has no training-point economy behind a skill line.
+    // GetAdjustedSkillPoints() → 0 here; the reference answers `PLAYER_CHARACTER_POINTS2` less the
+    // points `AddSkillUp` has pending (`0x4d3cb0`). The stock pane reads it only under its
+    // `stepCost` and `rankCost` branches, which 1.12 data never opens.
     g.set(
         "GetAdjustedSkillPoints",
         lua.create_function(|_, ()| Ok(0i64))?,
     )?;
 
-    // AbandonSkill(index) — VISIBLE index in (the ref's UNLEARN_SKILL popup passes the row it was
-    // opened for), queued out BY SKILL ID for the app's CMSG_UNLEARN_SKILL send. Mutates NOTHING
-    // locally: the real client waits for the server's skill-field update (vmangos SetSkill(id,0,0)
-    // → our descriptor watcher → a fresh set_skills push → SKILL_LINES_CHANGED). A header or
-    // out-of-range index no-ops (only entries carry the unlearn button).
+    // AbandonSkill(index): queue the entry's skill id for `CMSG_UNLEARN_SKILL`, changing nothing
+    // locally: the reference waits for the skill-field update (vmangos `SetSkill(id,0,0)`).
     g.set(
         "AbandonSkill",
         lua.create_function(|lua, index: usize| {
@@ -538,14 +397,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CancelSkillUps() — `0x4d3e30` → `0x4d35c9` (reference `1.12-shapes.tsv`: no arguments, no
-    // returns): the reset leg of the temp-point table, zeroing every entry's `numTempPoints` and
-    // giving the points back to the pool. The stock page's LIVE Close button calls it before
-    // hiding (`SkillFrame.xml`'s SkillFrameCancelButton, decision 1496), so it is reached on
-    // every close. This model carries no temp points (module docs, 1919): the table it resets is
-    // empty by construction, so the reset moves nothing — the binding's whole effect on this
-    // client's data, not a stand-in for it. The day temp points are modelled, this is where
-    // they are cleared.
+    // CancelSkillUps() (`0x4d3e30`): zeroes every `numTempPoints` (`0x4d35c9`); the stock Close
+    // button calls it (`SkillFrame.xml:352`). No temp points are modelled, so nothing resets.
     g.set("CancelSkillUps", lua.create_function(|_, ()| Ok(()))?)?;
 
     Ok(())
@@ -579,18 +432,14 @@ mod tests {
             category_name: category_name.into(),
             category_order,
             description: format!("About {name}."),
-            // Fixture rule: the Professions category (id 2) is abandonable, weapons are not —
-            // the real SkillRaceClassInfo 0x20 split's shape.
+            // Fixture rule: Professions (id 2) is abandonable, as the 0x20 flag splits it.
             abandonable: category_id == 2,
-            // Fixture rule: the Class Skills category (id 3) is single-rank, the real 0x400
-            // split's shape (a hunter's Beast Mastery).
+            // Fixture rule: Class Skills (id 3) is single-rank, as the 0x400 flag splits it.
             mono: category_id == 3,
         }
     }
 
-    /// Two categories: "Weapon Skills" (order 1: Defense, Swords) and "Professions" (order 2:
-    /// First Aid, Fishing) — a flat, unordered push (Swords precedes Defense in push order; the
-    /// engine's own name sort must still show Defense first).
+    /// Weapon Skills (order 1) and Professions (order 2), pushed unordered: Swords before Defense.
     fn state() -> SkillsState {
         SkillsState {
             entries: vec![
@@ -616,7 +465,7 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 0);
 
         s.set_skills(state());
-        // 2 headers + 4 entries = 6 visible rows, category_order ascending, name ascending within.
+        // 2 headers + 4 entries, category_order ascending, name ascending within.
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 6);
         assert_eq!(
             row_kind(&mut s, 1),
@@ -628,7 +477,7 @@ mod tests {
         assert_eq!(row_kind(&mut s, 5), ("First Aid".into(), "entry".into()));
         assert_eq!(row_kind(&mut s, 6), ("Fishing".into(), "entry".into()));
 
-        // Every group starts EXPANDED (the module doc's default rule).
+        // Every group starts expanded.
         let (_, h1, e1) = s
             .eval::<(String, i64, Option<i64>)>("local n,h,e = GetSkillLineInfo(1) return n,h,e")
             .unwrap();
@@ -639,8 +488,7 @@ mod tests {
     fn abandon_skill_queues_the_entrys_skill_id_and_mutates_nothing() {
         let mut s = UiScript::new().unwrap();
         s.set_skills(state());
-        // The 8th return: Professions rows are abandonable (fixture rule), weapon rows and
-        // headers are not — 1/nil, the 1.12 boolean shape.
+        // The 8th return, 1/nil: only Professions rows are abandonable (fixture rule).
         let ab = |s: &mut UiScript, i: i64| {
             s.eval::<Option<i64>>(&format!(
                 "local _,_,_,_,_,_,_,ab = GetSkillLineInfo({i}) return ab"
@@ -651,8 +499,7 @@ mod tests {
         assert_eq!(ab(&mut s, 5), Some(1), "First Aid is abandonable");
         assert_eq!(ab(&mut s, 1), None, "a header never is");
 
-        // AbandonSkill queues BY SKILL ID; headers and out-of-range indices no-op; the list
-        // itself is untouched (the server round trip owns the removal).
+        // Queued by skill id; a header or an out-of-range index does nothing; the list stays.
         s.run("AbandonSkill(5)").unwrap();
         s.run("AbandonSkill(1)").unwrap();
         s.run("AbandonSkill(99)").unwrap();
@@ -673,8 +520,7 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_skills(state());
 
-        // Fold "Weapon Skills" (header at visible index 1): its two entries vanish, the header
-        // stays and now reports isExpanded=nil. 6 → 4.
+        // Fold Weapon Skills (row 1): its two entries go, the header stays with isExpanded nil.
         s.run("CollapseSkillHeader(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 4);
         let (name, _, expanded) = s
@@ -698,14 +544,12 @@ mod tests {
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 6);
     }
 
-    /// A re-push keeps the SELECTION (by skill id) but throws every fold away — the client's list
-    /// rebuild re-expands unconditionally (`expandedMask = 0xFFFFFFFF`, decision 1091).
     #[test]
     fn a_repush_keeps_the_selection_and_re_expands_every_group() {
         let mut s = UiScript::new().unwrap();
         s.set_skills(state());
 
-        // Selecting a HEADER clears the selection (module doc).
+        // Selecting a header clears the selection.
         s.run("SetSelectedSkill(1)").unwrap();
         assert_eq!(s.eval::<i64>("return GetSelectedSkill()").unwrap(), 0);
 
@@ -715,8 +559,7 @@ mod tests {
         s.run("CollapseSkillHeader(4)").unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 4);
 
-        // A re-push (values ticked up): the fold is GONE — all 6 rows are back — while the
-        // selection still points at Swords, which is still row 3.
+        // A re-push unfolds every group and keeps Swords selected at row 3.
         let mut ticked = state();
         ticked.entries[0].value = 201; // Swords
         s.set_skills(ticked);
@@ -739,8 +582,7 @@ mod tests {
         let mut s = UiScript::new().unwrap();
         s.set_skills(state());
 
-        // Header row 1 ("Weapon Skills"): 12 values — (name, 1, expanded, 0, 0, 0, 0, nil, nil,
-        // nil, 0, 0), and NO 13th (the client's header path pushes 12, `0x4d3768`).
+        // Header row 1: twelve values, no description (`0x4d3768`).
         let (name, is_header, is_expanded, rank, temp, modifier, max) = s
             .eval::<(String, i64, Option<i64>, i64, i64, i64, i64)>(
                 "local n,h,e,r,t,m,mx = GetSkillLineInfo(1) return n,h,e,r,t,m,mx",
@@ -773,8 +615,7 @@ mod tests {
         assert_eq!((min_level, cost_type), (0, 0));
         assert_eq!(count, 12, "a header row returns 12 values, not 13");
 
-        // Entry row 2 ("Defense", value 180, max 300, temp bonus +5): (name, nil, nil, 180, 0, 5,
-        // 300, nil, nil, nil, 0, 1, description) — 13 values.
+        // Entry row 2 (Defense 180/300, temp +5): thirteen values.
         let (name, is_header, is_expanded, rank, temp, modifier, max) = s
             .eval::<(String, Option<i64>, Option<i64>, i64, i64, i64, i64)>(
                 "local n,h,e,r,t,m,mx = GetSkillLineInfo(2) return n,h,e,r,t,m,mx",
@@ -792,15 +633,12 @@ mod tests {
             ),
             ("Defense", None, None, 180, 0, 5, 300)
         );
-        // The 13th return is the REAL description (SkillLine.dbc col 12 through the feed) — an
-        // entry row's alone: a header stops at 12 (asserted above).
         let count = s.arity("GetSkillLineInfo(2)").unwrap();
         let desc = s
             .eval::<String>("local _,_,_,_,_,_,_,_,_,_,_,_,d = GetSkillLineInfo(2) return d")
             .unwrap();
         assert_eq!((count, desc.as_str()), (13, "About Defense."));
-        // minLevel and skillCostType are real NUMBERS on an entry — and the cost type is the
-        // row's index PLUS ONE (the client's own `0x4d3a06`), so a fixture at index 0 reads 1.
+        // The cost type is the cost index plus one, so index 0 reads 1.
         let (min_level, cost_type) = s
             .eval::<(i64, i64)>(
                 "local _,_,_,_,_,_,_,_,_,_,ml,ct = GetSkillLineInfo(2) return ml,ct",
@@ -809,8 +647,6 @@ mod tests {
         assert_eq!((min_level, cost_type), (0, 1));
     }
 
-    /// The permanent bonus folds into BOTH numbers, the temporary one is the `skillModifier`
-    /// return on its own, and a line at 0 stays flat 0 (the client's `rank > 0 ?` guard).
     #[test]
     fn the_permanent_bonus_folds_into_the_numbers_and_the_temporary_one_does_not() {
         let mut s = UiScript::new().unwrap();
@@ -821,22 +657,19 @@ mod tests {
         st.entries.last_mut().unwrap().perm_bonus = 10;
         s.set_skills(st);
 
-        // Defense (row 2): 190/310, modifier still the temp +5 alone.
+        // Defense (row 2): 190/310, the modifier still the temp +5 alone.
         let (rank, modifier, max) = s
             .eval::<(i64, i64, i64)>("local _,_,_,r,_,m,mx = GetSkillLineInfo(2) return r,m,mx")
             .unwrap();
         assert_eq!((rank, modifier, max), (190, 5, 310));
 
-        // Herbalism 0/0 (row 7, an untrained line sorted under the trained ones): a flat 0/0 —
-        // the bonus is not added to a zero.
+        // Herbalism 0/0 (row 7, untrained so last): the bonus is not added to a zero.
         let (name, rank, max) = s
             .eval::<(String, i64, i64)>("local n,_,_,r,_,_,mx = GetSkillLineInfo(7) return n,r,mx")
             .unwrap();
         assert_eq!((name.as_str(), rank, max), ("Herbalism", 0, 0));
     }
 
-    /// Within a category, untrained (rank 0) lines sink below the trained ones, whatever their
-    /// name — the client's comparator (`0x4d3070`), which tests `untrained` before `stricmp`.
     #[test]
     fn untrained_lines_sort_under_the_trained_ones_of_their_category() {
         let mut s = UiScript::new().unwrap();
@@ -854,14 +687,11 @@ mod tests {
         assert_eq!(names, ["First Aid", "Fishing", "Alchemy"]);
     }
 
-    /// A single-rank line reports `1/1` however high the server's descriptor is (the client's own
-    /// `SkillRaceClassInfo.flags & 0x400` arm: an override on the max, a min on the rank) — the
-    /// pane's proficiency gate. A normal line is unaffected.
     #[test]
     fn a_mono_line_reports_max_rank_one_whatever_the_server_said() {
         let mut s = UiScript::new().unwrap();
         let mut st = state();
-        // Beast Mastery: category 3 ⇒ mono by the fixture rule, server-side 300/300.
+        // Beast Mastery: category 3, so mono by the fixture rule; 300/300 from the server.
         st.entries.push(entry(
             50,
             "Beast Mastery",
@@ -874,7 +704,7 @@ mod tests {
         ));
         s.set_skills(st);
 
-        // Row 1/2 = the Class Skills header + its single entry (category_order 0 sorts first).
+        // Rows 1 and 2: the Class Skills header and its entry (category_order 0 sorts first).
         let (name, rank, modifier, max) = s
             .eval::<(String, i64, i64, i64)>(
                 "local n,_,_,r,_,m,mx = GetSkillLineInfo(2) return n,r,m,mx",
@@ -885,7 +715,7 @@ mod tests {
             ("Beast Mastery", 1, 0, 1),
             "the descriptor's 300/300 reads 1/1 — max overridden, rank clamped under it"
         );
-        // Defense (a weapon line, not mono) still reports its real 300.
+        // Defense, not mono, still reports its real 300.
         assert_eq!(
             s.eval::<i64>("local _,_,_,_,_,_,mx = GetSkillLineInfo(4) return mx")
                 .unwrap(),
@@ -893,17 +723,8 @@ mod tests {
         );
     }
 
-    /// **Out of range answers the reference's THIRTEEN-value tuple, not a bare nil** — decision
-    /// 1919, byte-verified in wow-re's `skillframe-selection-and-oob.md`.
-    ///
-    /// The COUNT is the whole assertion. `GetSkillLineInfo(0) == nil` reads true either way,
-    /// because Lua compares only the first returned value — which is precisely how the old
-    /// one-nil shape passed for as long as it did. What breaks a caller is slots 4 and 5: the
-    /// reference's own `SkillDetailFrame_SetStatusBar` does `skillRank = skillRank + numTempPoints`
-    /// with NO guard, straight off `SkillFrame_OnLoad`'s `SetSelectedSkill(0)`, so those two must be
-    /// NUMBERS or the stock file raises the moment it loads. One shape serves index 0, a negative
-    /// index, past-the-end, no active player and a DBC miss — the reference funnels all five
-    /// through one unsigned bounds test (`0x4d3675`).
+    /// The count is the assertion: `GetSkillLineInfo(0) == nil` holds for a single nil too, since
+    /// Lua compares only the first value.
     #[test]
     fn out_of_range_answers_the_thirteen_value_tuple() {
         let s = UiScript::new().unwrap();
@@ -933,14 +754,13 @@ mod tests {
     fn no_push_reports_zero_rows() {
         let s = UiScript::new().unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 0);
-        // The empty pane answers the out-of-range tuple; the test above holds its ARITY, which is
-        // the load-bearing half. This line only pins slot 1.
+        // The empty pane answers the out-of-range tuple; this pins slot 1.
         assert!(s
             .eval::<bool>("return (GetSkillLineInfo(1)) == nil")
             .unwrap());
         assert_eq!(s.eval::<i64>("return GetSelectedSkill()").unwrap(), 0);
         assert_eq!(s.eval::<i64>("return GetAdjustedSkillPoints()").unwrap(), 0);
-        // Collapse/expand/select on an empty pane are harmless no-ops.
+        // Collapse, expand and select on an empty pane do nothing.
         s.run("CollapseSkillHeader(0) ExpandSkillHeader(1) SetSelectedSkill(1)")
             .unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSkillLines()").unwrap(), 0);
diff --git a/crates/benilla-ui/src/script/slash.rs b/crates/benilla-ui/src/script/slash.rs
index c7f8025d..46f8d6a0 100644
--- a/crates/benilla-ui/src/script/slash.rs
+++ b/crates/benilla-ui/src/script/slash.rs
@@ -1,87 +1,39 @@
-//! **`SlashCmdList` dispatch** — how an addon gets a `/command` (decision 1195).
-//!
-//! The single most-wanted *table* in the corpus. 26 of 218 addons stop on
-//! `attempt to index global 'SlashCmdList'` — the top runtime wall after the dialect gap — because
-//! the registration idiom is three lines at file scope:
-//!
-//! ```lua
-//! SLASH_MYADDON1 = "/myaddon"
-//! SLASH_MYADDON2 = "/ma"
-//! SlashCmdList["MYADDON"] = function(msg) … end
-//! ```
-//!
-//! …and the third line raises the moment the table is missing.
-//!
-//! ## The resolution is the reference's own, transcribed
-//!
-//! `ChatEdit_ParseText` (ChatFrame.lua) walks **`SlashCmdList`'s keys**, not a name list: for each
-//! `index` it reads `SLASH_<index>1`, `SLASH_<index>2`, … until the first gap, comparing each
-//! against the typed command case-insensitively. The aliases are data and the handlers are code,
-//! joined by the index name — decision 0881 built our own table on exactly that shape, and this is
-//! the same walk over the half addons own.
-//!
-//! Two details of that walk are load-bearing and both are easy to get wrong:
-//!
-//! - **The handler's argument is the rest of the line, not the rest of the *word*.** The reference
-//!   passes `strsub(text, strlen(cmdString) + 2)` — everything after the alias and one space — so
-//!   `/myaddon set foo 3` hands the handler `"set foo 3"`, spaces intact. An addon's own parser
-//!   starts there.
-//! - **The walk stops at the first gap.** `SLASH_X1` and `SLASH_X3` with no `SLASH_X2` means `X3`
-//!   is unreachable, in the reference and here. That is a property of the data format, not a bug
-//!   to repair.
-//!
-//! ## Where the table lives, and the divergence that comes with it
-//!
-//! `SlashCmdList` is **FrameXML's**, not the engine's (`reference/1.12-globals.tsv` says
-//! `table framexml`), so ours is declared in our transcribed `ChatFrame.xml` exactly as the
-//! reference declares it in `ChatFrame.lua` — 1190's engine/FrameXML split applied to a table
-//! rather than a function.
-//!
-//! **The divergence, stated:** benilla's *own* commands (`/who`, `/invite`, `/cast`, …) are
-//! dispatched in Rust ([`crate`]'s host owns them) and are **not** entries in `SlashCmdList`. In
-//! the reference they are, so an addon that tests `if SlashCmdList["WHO"] then` or hooks one by
-//! wrapping the entry sees an empty table here and does nothing. That is a real, observable gap;
-//! it is bounded (nothing in the corpus does it) and the fix is to move our command handlers into
-//! transcribed FrameXML, which is a much larger piece of work than this one.
+//! `SlashCmdList` dispatch from the host, for a line that reaches it without passing the stock
+//! `ChatEdit_ParseText` (`ChatFrame.lua`): the same walk, over the table the stock `ChatFrame.lua`
+//! declares, where the stock commands and benilla's own are entries.
 
 use mlua::{Table, Value};
 
 impl super::UiScript {
-    /// Try to dispatch `/cmd args` through `SlashCmdList`. Returns whether a handler ran.
-    ///
-    /// The host calls this **after** its own command table misses, so a shipped command can never
-    /// be shadowed by an addon — which is also the reference's precedence, since its own commands
-    /// are registered in the same table before any addon loads.
-    ///
-    /// A handler that raises is collected into [`super::UiScript::errors`] like any other script
-    /// error rather than propagated: a broken `/command` must not take down the chat drain that
-    /// invoked it. It still counts as *handled* — the command existed and was called.
+    /// Dispatch `/cmd args` through `SlashCmdList`, returning whether a handler ran. The host calls
+    /// this after its own commands miss, so an addon never shadows one; a handler that raises is
+    /// recorded as a script error, not propagated, and still counts as handled.
     pub fn run_slash_command(&mut self, cmd: &str, args: &str) -> bool {
         let Some(handler) = self.find_slash_handler(cmd) else {
             return false;
         };
-        // The reference passes `strsub(text, strlen(cmdString) + 2)` — everything after the alias
-        // and one space. The host has already made that split, so `args` IS that string.
+        // The rest of the line after the alias and one space, spaces intact: the reference's
+        // `strsub(text, strlen(cmdString) + 2)`.
         if let Err(e) = handler.call::<()>(args.to_string()) {
             self.model_mut().record_script_error(format!("/{cmd}: {e}"));
         }
         true
     }
 
-    /// Is `cmd` a command some `SlashCmdList` entry claims? Pure query, fires nothing — the
-    /// completion/echo paths want to know without running anything.
+    /// Whether a `SlashCmdList` entry claims `cmd`, without running it.
     pub fn has_slash_command(&self, cmd: &str) -> bool {
         self.find_slash_handler(cmd).is_some()
     }
 
-    /// The reference's walk: over `SlashCmdList`'s keys, then `SLASH_<key><n>` until a gap.
+    /// The reference's walk: over `SlashCmdList`'s keys, then `SLASH_<key><n>` to the first gap,
+    /// case-insensitive.
     fn find_slash_handler(&self, cmd: &str) -> Option<mlua::Function> {
         let globals = self.lua.globals();
         let list: Table = globals.get("SlashCmdList").ok()?;
         let want = cmd.to_ascii_uppercase();
         for pair in list.pairs::<String, Value>() {
             let Ok((index, Value::Function(handler))) = pair else {
-                continue; // a non-function entry is not a command; the reference would error on it
+                continue; // Deviation: skipped because it is no command; the reference raises
             };
             for n in 1.. {
                 let alias: Option<String> = globals.get(format!("SLASH_{index}{n}")).ok().flatten();
@@ -100,13 +52,10 @@ impl super::UiScript {
 mod tests {
     use crate::script::UiScript;
 
-    /// **The registration idiom, exactly as an addon writes it** — and the reason 26 corpus addons
-    /// died at file scope before this landed.
     #[test]
     fn an_addon_registers_a_slash_command_and_it_dispatches() {
         let mut s = UiScript::new().unwrap();
-        // Our shipped ChatFrame.xml declares the table; a bare VM has to stand it up itself, which
-        // is also the smallest possible statement of what an addon depends on.
+        // A bare VM has no `ChatFrame.xml`, so the test declares the table itself.
         s.run("SlashCmdList = {}").unwrap();
         s.run(
             r#"
@@ -132,8 +81,7 @@ mod tests {
         assert!(!s.run_slash_command("nosuchthing", ""));
     }
 
-    /// The alias walk stops at the first gap — the reference's `while cmdString` loop, and a
-    /// property of the data format rather than a bug to repair.
+    /// The reference's `while cmdString` loop.
     #[test]
     fn the_alias_walk_stops_at_the_first_gap() {
         let s = UiScript::new().unwrap();
@@ -153,8 +101,6 @@ mod tests {
         );
     }
 
-    /// A handler that raises is collected, not propagated: a broken addon command must not take
-    /// down the chat drain that invoked it.
     #[test]
     fn a_raising_handler_is_collected_and_still_counts_as_handled() {
         let mut s = UiScript::new().unwrap();
@@ -176,7 +122,6 @@ mod tests {
         );
     }
 
-    /// A `SlashCmdList` entry that is not a function is skipped rather than called.
     #[test]
     fn a_non_function_entry_is_not_a_command() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/slider.rs b/crates/benilla-ui/src/script/slider.rs
index a944d0a6..ac2a4299 100644
--- a/crates/benilla-ui/src/script/slider.rs
+++ b/crates/benilla-ui/src/script/slider.rs
@@ -1,27 +1,10 @@
-//! The `Slider` method surface — the `CSimpleSlider` widget behavior over the kind tag (factory
-//! `0x6eee40`). A value in `[min, max]` with a step and orientation, driving a thumb texture along
-//! the track.
-//!
-//! Grounded in wow-re's byte-verified LoadXML table (RF-28, `rf28-typed-widget-loadxml.md`): the
-//! `<ThumbTexture>` sub-element (default layer OVERLAY=3), `minValue`/`maxValue`/`valueStep`/
-//! `defaultValue`, the `orientation` shared enum (HORIZONTAL=0/VERTICAL=1, `0x811b00`), and the
-//! widget's own `OnValueChanged` script slot (`+0x330`). The **thumb-position** mechanism — the
-//! thumb's rect placed at the value fraction along the orientation axis, applied at extract — is
-//! faithful to the *documented* widget model, not byte-pinned (same posture as StatusBar's fill and
-//! ScrollFrame's scroll; decisions 0112/0250).
-//!
-//! `SetValue` fires `OnValueChanged` on the **first-ever** value and after that **only on an
-//! actual change** ([`SliderState::store_value`] — the client's `+0x314` bit2, wow-re
-//! `slider-mouse-law.md` §6). The change-gate is load-bearing, not an optimization: the real
-//! scrollbar template wires `OnValueChanged → this:GetParent():SetVerticalScroll(arg1)` and the
-//! ScrollFrame's `OnVerticalScroll → scrollbar:SetValue(arg1)` back the other way, so a fire-always
-//! `SetValue` would recurse forever (`UIPanelTemplates.xml`); the gate breaks the loop after one
-//! hop. `SetMinMaxValues` re-clamps through the same gate only once a value exists, so a range set
-//! from `<OnLoad>` never runs a handler the addon has not armed yet.
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for Slider frames — so duck-typing addons (`if frame:GetThumbTexture() then …`) see `nil` on
-//! every other kind, exactly as against the client's per-class method sets.
+//! The `Slider` methods of `CSimpleSlider` (factory `0x6eee40`, `Slider::LoadXML` `0x789580`): a
+//! value in `[min, max]` with a step and an orientation (`0x811b00`), driving a thumb texture along
+//! the track, whose placement follows the documented widget model, untraced in the reference.
+//! `SetValue` fires `OnValueChanged` (slot `+0x330`) on the first value and then only on a change
+//! (`+0x314` bit 2, `0x789a06` in `SetValue` `0x789930`), which ends the loop between the stock
+//! scrollbar's `OnValueChanged` and its ScrollFrame's `OnVerticalScroll`. The methods exist only on
+//! Slider frames, as in the client's per-class method sets.
 
 use mlua::{Lua, Table, Value};
 
@@ -35,12 +18,10 @@ use crate::widget::{
     slider_fraction, slider_grab, FrameHandle, KindState, RegionKind, SliderState,
 };
 
-/// Registry key of the Slider method table (the MAXCSTACK discipline: Lua-side root, named key).
 pub(super) const REG_SLIDER_METHODS: &str = "__benilla_slider_methods";
 
-/// Run `f` over a frame's Slider state under one short write borrow. Errors if `this` is not a live
-/// Slider (unreachable through the kind dispatcher, but the method table is a plain Lua value — a
-/// caller could fish it out and misapply it).
+/// Run `f` over a frame's Slider state under one short write borrow; errors unless `this` is a live
+/// Slider, since a caller can lift the method table onto another frame.
 fn with_slider<T>(
     lua: &Lua,
     this: &Table,
@@ -58,9 +39,8 @@ fn with_slider<T>(
     }
 }
 
-/// Get-or-create the thumb texture region (`SetThumbTexture`/`<ThumbTexture>`); `layer` re-layers an
-/// existing thumb. Returns the region's id (for wrapper lookup). The widget default layer is OVERLAY
-/// (RF-28 — the Slider's `drawLayer` attr defaults OVERLAY=3, unlike StatusBar's ARTWORK bar).
+/// Get or create the thumb texture region and return its id; `layer` re-layers an existing thumb,
+/// and a new one defaults to OVERLAY (`0x789580`).
 fn ensure_thumb(lua: &Lua, this: &Table, layer: Option<DrawLayer>) -> mlua::Result<u32> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -93,7 +73,7 @@ fn ensure_thumb(lua: &Lua, this: &Table, layer: Option<DrawLayer>) -> mlua::Resu
                 )
                 .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
             model.region_data.insert(rh, RegionData::default());
-            model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+            model.touch_layout(); // a region entered the layout gate's read set
             if let Some(frame) = model.arena.frame_mut(h) {
                 if let KindState::Slider(s) = &mut frame.kind_state {
                     s.thumb = Some(rh);
@@ -111,10 +91,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "SetMinMaxValues",
         lua.create_function(|lua, (this, min, max): (Table, f32, f32)| {
-            // Unlike StatusBar, a reversed pair is NOT swapped (the Slider LoadXML stores min +
-            // (max−min) and does no swap, RF-28). A held value re-clamps into the new range and a
-            // move fires OnValueChanged — but only once a value EXISTS (`SliderState::set_min_max`,
-            // the client's bit2): on a fresh slider this sets the range and fires nothing.
+            // A reversed pair is kept, not swapped (`0x789580`). A held value re-clamps and fires
+            // on a move; a fresh slider with no value yet fires nothing (bit 2).
             let changed = with_slider(lua, &this, |s| s.set_min_max(min, max))?;
             fire_value_changed(lua, &this, changed)
         })?,
@@ -136,9 +114,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
     m.set(
         "SetValueStep",
-        // Not a field write (2143): past the step store it re-pushes the range through
-        // `SetMinMaxValues`, which re-clamps and re-quantises the held value onto the new lattice
-        // and fires `OnValueChanged` if it moved — so this binding fires like the other two.
+        // Stores the step, then re-pushes the range as `SetMinMaxValues` does, so a held value
+        // moved onto the new step fires `OnValueChanged`.
         lua.create_function(|lua, (this, step): (Table, f32)| {
             let changed = with_slider(lua, &this, |s| s.set_value_step(step))?;
             fire_value_changed(lua, &this, changed)
@@ -171,27 +148,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `Enable`/`Disable`/`IsEnabled` WERE here and are GONE, with the `enabled` state they drove.
-    // **A 1.12 Slider has no enabled state at all**: the three names are registered once each, in
-    // the BUTTON table `0x879d00` (`0x77fef0`/`0x77ffd0`/`0x7800b0`), and the Slider's own LoadXML
-    // `0x789580` takes `drawLayer`/`minValue`/`maxValue`/`valueStep`/`defaultValue`/`orientation`
-    // and nothing else (wow-re `rf28-typed-widget-loadxml.md` §Slider) — so there was no way in
-    // from Lua *or* from XML, and the flag could only ever read `true`.
-    //
-    // They were a superset in PRESENCE, which is what 1189 records the cost of: a duck-typing addon
-    // that branches on `if widget.IsEnabled then` reads a Slider as a Button. Ours also answered a
-    // Lua BOOLEAN, which the reference has no query that does (decision 2118) — `IsEnabled 0x7800b0`
-    // is number-1/number-0 and never even nil.
-    //
-    // Removed rather than corrected because nothing calls them on a Slider receiver: a
-    // receiver-typed grep over this repo, `assets/ui`, the stock FrameXML/GlueXML and both addon
-    // corpora (110 top-20 + 219 vanilla) finds zero `slider*:Enable/Disable/IsEnabled` sites.
-    // `begin_drag` below lost its `enabled` gate with them — behaviour-neutral, since no caller
-    // could clear the flag.
+    // A 1.12 Slider has no enabled state: `Enable`/`Disable`/`IsEnabled` exist only in the Button
+    // table (`0x879d00`: `0x77fef0`, `0x77ffd0`, `0x7800b0`), so a Slider must not answer them.
 
-    // SetThumbTexture(path [, drawLayer]) | SetThumbTexture(r, g, b [, a]) — the same two forms as a
-    // region's SetTexture, targeting the thumb region (created on first use). Mirrors
-    // SetStatusBarTexture; the thumb defaults to the OVERLAY layer.
+    // `SetThumbTexture(path [, layer])` or `(r, g, b [, a])`, a region's two `SetTexture` forms, on
+    // the thumb region, created on first use.
     m.set(
         "SetThumbTexture",
         lua.create_function(
@@ -212,7 +173,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         data.texture = Some(s.to_str()?.to_string());
                         data.fill = None;
                     }
-                    // A solid thumb writes the same slot the path form does — each clears the other.
+                    // A solid thumb and a path share one slot; each clears the other.
                     Value::Number(_) | Value::Integer(_) => {
                         data.texture = None;
                         data.fill = Some([
@@ -250,8 +211,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Fire `OnValueChanged(self, value)` if `changed` carries the new value (RF-28: the Slider's own
-/// script slot `+0x330`). Fired outside any model borrow; errors go to [`Model::errors`].
+/// Fire `OnValueChanged` (slot `+0x330`) when `changed` carries a new value, outside any model
+/// borrow; errors are recorded in [`Model::errors`].
 fn fire_value_changed(lua: &Lua, this: &Table, changed: Option<f32>) -> mlua::Result<()> {
     let Some(value) = changed else { return Ok(()) };
     let id = {
@@ -267,13 +228,11 @@ fn fire_value_changed(lua: &Lua, this: &Table, changed: Option<f32>) -> mlua::Re
     ) {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
     Ok(())
 }
 
-/// A Lua number-ish → f32 (nil/other → 0.0), for the color-form arguments.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
@@ -282,18 +241,11 @@ fn num_f32(v: &Value) -> f32 {
     }
 }
 
-// ── Thumb geometry + drag (decision 0250 §4/§5) ──────────────────────────────────────────────
+// ── Thumb geometry and drag ──────────────────────────────────────────────────────────────────
 
-/// A Slider's thumb rect: the thumb of size `thumb_size` placed at `fraction` along the slider `r`'s
-/// track and centered on the cross-axis. The thumb stays **inset** within the track (travel =
-/// trackLen − thumbLen), the way WoW scrollbar knobs visibly do. VERTICAL runs y-up-inverted —
-/// `fraction` 0 (value=min) sits the thumb flush at the **top** (a scrollbar at 0 is scrolled to the
-/// top), `fraction` 1 flush at the bottom. This is the single geometry source shared by `extract`
-/// (render) and [`begin_drag`] (hit-test), so render and input never disagree. Returns a [`Rect`] as
-/// `(bottom, left, top, right)`.
-///
-/// `thumb_size` is [`thumb_extent`]'s — the thumb region's OWN size getters, never its authored
-/// `<Size>` alone.
+/// The thumb's rect at `fraction` along the track, centred across it and inset so it travels
+/// `trackLen - thumbLen`; vertical puts fraction 0 at the top. Render and [`begin_drag`] both use
+/// it, so they never disagree. `thumb_size` is [`thumb_extent`]'s.
 pub(super) fn thumb_rect(r: Rect, thumb_size: (f32, f32), vertical: bool, fraction: f32) -> Rect {
     let (tw, th) = thumb_size;
     if vertical {
@@ -309,51 +261,27 @@ pub(super) fn thumb_rect(r: Rect, thumb_size: (f32, f32), vertical: bool, fracti
     }
 }
 
-/// The thumb's extent along both axes — **the thumb region's own `GetWidth`/`GetHeight`**, which
-/// is what the client asks for and is not the same thing as its authored `<Size>`.
-///
-/// `CSimpleSlider`'s pixel→value law reads the thumb through its geometry vtable
-/// (`0x789ba0`: `ff 50 1c call [eax+0x1c]` for the horizontal branch, `+0x20` for the vertical), and
-/// on a `CSimpleTexture` those slots are `0x770720`/`0x770790` — the **native-texel fallback**:
-/// authored span when it is non-zero on that axis, else the art's own texel span through the same
-/// `<AbsDimension>` converter, else `0.0` when there is no art at all (wow-re
-/// `region-size-fallback.md` §2, VERIFIED; ours is [`super::region::virtual_span`], decision 1349).
-///
-/// Reading `RegionData::size` instead is what broke every Lua-built slider: `SetThumbTexture(path)`
-/// authors no size, all four stock `<ThumbTexture>`s declare one, and the old fallback — *the thumb
-/// fills the track* — is not a client behaviour at all. It smeared the knob over the whole bar and
-/// left `trackLen − thumbLen == 0`, i.e. a slider that cannot move (Dewdrop-2.0's popout, B-report).
-/// A thumb with **no region at all** is `None`: `0x789ba0` gates the value math on `+0x328` being
-/// non-null, so a thumbless slider takes the press and the capture but never warps.
+/// The thumb region's own width and height, as `0x789ba0` reads them through the texture's
+/// geometry slots (`[vtable+0x1c]`/`+0x20`, `0x770720`/`0x770790`): the authored span, else the
+/// art's texel span, else 0. `None` without a thumb region: `0x789ba0` gates the value math on
+/// `+0x328`, so a thumbless slider captures a press but never moves.
 fn thumb_extent(model: &Model, thumb: Option<crate::widget::RegionHandle>) -> Option<(f32, f32)> {
     Some(super::region::virtual_span(model, thumb?))
 }
 
-/// The in-flight thumb drag (decision 0250 §5): the slider being dragged + the grab offset
-/// [`slider_grab`] returned, so the thumb tracks the cursor without jumping. Engine C++-equivalent
-/// — no Lua, like the real client's scrollbar.
+/// The in-flight thumb drag and the grab offset [`slider_grab`] returned, so the thumb tracks the
+/// cursor without jumping.
 #[derive(Clone, Copy)]
 pub(crate) struct SliderDrag {
     pub(crate) slider: FrameHandle,
-    /// The grab, in **distance from the track's leading edge** — the axis-neutral frame
-    /// [`slider_grab`]/[`slider_fraction`] are stated in, so this arena's y-up rects and the glue
-    /// screens' y-down nodes run the identical arithmetic.
+    /// The grab as distance from the track's leading edge, the axis-neutral frame [`slider_grab`]
+    /// and [`slider_fraction`] share with the glue screens.
     pub(crate) grab_offset: f32,
 }
 
-/// On a LeftButton press at `(x, y)` whose hit frame is `hit`: if that frame is a Slider with a
-/// resolved rect, begin a drag capture (records [`Model::slider_drag`]). Where the press grabs is
-/// [`slider_grab`]'s to say — one law, shared with the glue lane's scrollbars, so an in-game bar
-/// and a character-screen bar cannot drift apart on feel.
-///
-/// There is no enabled gate: 1.12 gives a Slider no enabled state to gate on (see `install`'s note
-/// where `Enable`/`Disable`/`IsEnabled` used to be). A slider that should not take the press is
-/// kept off it the way the reference keeps anything off it — `EnableMouse(false)`, upstream of here
-/// in the hit test.
-///
-/// Returns `Some((frame id, new value))` when the press itself changed the value (the track jump)
-/// — the caller fires `OnValueChanged` outside the model borrow, exactly like [`drag_move`]'s
-/// changes — else `None`.
+/// On a LeftButton press on a Slider `hit`, capture a drag at the [`slider_grab`] offset, with no
+/// enabled gate since a 1.12 Slider has no enabled state. Returns `(frame id, new value)` when the
+/// press jumps the value, for the caller to fire `OnValueChanged` outside the model borrow.
 pub(super) fn begin_drag(
     model: &mut Model,
     hit: Option<FrameHandle>,
@@ -366,8 +294,8 @@ pub(super) fn begin_drag(
         Some(KindState::Slider(s)) => (s.vertical, s.fraction(), s.thumb),
         _ => return None,
     };
-    // No thumb region → `0x789ba0`'s `+0x328` gate: the press still captures (the dispatcher's
-    // `mov [ebx+0x80],esi` is unconditional), the value never moves.
+    // No thumb region: the press still captures, the dispatcher's store being unconditional, but
+    // the value never moves (`0x789ba0`, `+0x328`).
     let Some(size) = thumb_extent(model, thumb) else {
         model.slider_drag = Some(SliderDrag {
             slider: h,
@@ -377,9 +305,8 @@ pub(super) fn begin_drag(
     };
     let trect = thumb_rect(r, size, vertical, fraction);
     let on_thumb = point_in_rect(trect, x, y);
-    // Everything below is stated as distance from the TRACK'S LEADING EDGE — the end the thumb
-    // sits at when the value is `min`. Vertical tracks run downward from `r.top` in this y-up
-    // arena, so that distance is `top − y`; horizontal ones run rightward from `r.left`.
+    // Distances from the track's leading edge, where the thumb sits at `min`: `top - y` on a
+    // vertical track in this y-up arena, `x - left` on a horizontal one.
     let (cursor, thumb_lead, thumb_len) = if vertical {
         (r.top - y, r.top - trect.top, trect.top - trect.bottom)
     } else {
@@ -395,11 +322,8 @@ pub(super) fn begin_drag(
     drag_move(model, x, y)
 }
 
-/// On a pointer move at `(x, y)` while a thumb is captured: recompute the value from the cursor
-/// position via [`slider_fraction`] (absolute, drift-free — the grab offset keeps the same thumb
-/// point under the cursor) and store it. Returns `Some((frame id, new value))` if the value
-/// actually changed — the caller fires `OnValueChanged` outside the model borrow — else `None` (no
-/// capture, no travel, or no change).
+/// On a pointer move during a capture, set the value from the cursor through [`slider_fraction`];
+/// returns `(frame id, new value)` when it changed, for the caller to fire.
 pub(super) fn drag_move(model: &mut Model, x: f32, y: f32) -> Option<(u32, f32)> {
     let SliderDrag {
         slider,
@@ -411,13 +335,13 @@ pub(super) fn drag_move(model: &mut Model, x: f32, y: f32) -> Option<(u32, f32)>
         _ => return None, // slider destroyed mid-drag
     };
     let (tw, th) = thumb_extent(model, thumb)?;
-    // The same leading-edge frame [`begin_drag`] stored the grab in.
+    // The leading-edge frame `begin_drag` stored the grab in.
     let (cursor, track_extent, thumb_len) = if vertical {
         (r.top - y, r.height(), th)
     } else {
         (x - r.left, r.width(), tw)
     };
-    // `None` = nothing to scroll (a thumb as long as its track).
+    // `None` when the thumb is as long as its track.
     let fraction = slider_fraction(cursor, grab_offset, track_extent, thumb_len)?;
     let value = min + fraction * (max - min);
     let changed = match model.arena.frame_mut(slider).map(|f| &mut f.kind_state) {
diff --git a/crates/benilla-ui/src/script/social.rs b/crates/benilla-ui/src/script/social.rs
index 0ad80c22..8b58504a 100644
--- a/crates/benilla-ui/src/script/social.rs
+++ b/crates/benilla-ui/src/script/social.rs
@@ -1,23 +1,8 @@
-//! The social **Era API surface** — friends, ignores, and `/who` (decision 0668).
-//!
-//! The [`super::party`] shape exactly: the app pushes a [`SocialState`] snapshot built from its
-//! own wire mirror ([`UiScript::set_social`]) and the getters here read that plain data; every
-//! verb queues a [`SocialRequest`] the app drains ([`UiScript::take_social_requests`]) into the
-//! matching `CMSG_*` send. No ECS or net reach from the engine (decision 0068 §3).
-//!
-//! **The snapshot is already display-ready** — names, class name, zone name, the `<AFK>` tag —
-//! because every one of those is a *lookup the engine owns* in the real client too: the friend
-//! slot on the wire holds a bare guid + class/area **ids**, and `FriendList`'s formatter
-//! (`0x5ae160`) resolves them through the ObjectMgr name cache and the race/class/area GameTables
-//! before Lua ever sees them. Pushing ids here and resolving in Lua would invent a client the
-//! reference isn't.
-//!
-//! **Selection lives in the engine, not in Lua** — the reference keeps the selected friend and
-//! ignore as *guids* on the FriendList object (`+0x648` / `+0x720`, read back by
-//! `GetSelectedFriend` `0x5ad260` / `0x5ae510`), which is why `SetSelectedFriend(i)` here mutates
-//! the snapshot in place *and* queues the intent: the same Lua tick reads the new value back
-//! (`FriendsList_Update` does exactly that), and the app's own state follows so the next push
-//! agrees.
+//! The social API: friends, ignores and `/who`. The app pushes a display-ready [`SocialState`]
+//! (the reference's formatter `0x5ae160` also resolves names engine-side) and drains the queued
+//! [`SocialRequest`]s. Selection is engine state in the reference (guids at FriendList `+0x648` and
+//! `+0x720`, read back by `0x5ad260` and `0x5ae510`), so a set changes the snapshot at once and
+//! queues the change for the app.
 
 use mlua::{Lua, Value};
 
@@ -25,114 +10,83 @@ use super::binding_abi::string_arg;
 use super::who_sort::WhoSortChain;
 use super::Model;
 
-/// One friend row, already resolved for display — see the module doc on why the app resolves
-/// rather than the VM. Mirrors `GetFriendInfo`'s six returns in field order.
+/// One friend row in `GetFriendInfo`'s order; offline, the level is 0 and class and area empty.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct FriendInfo {
-    /// The character's name, from the name cache. Empty while the `CMSG_NAME_QUERY` is still in
-    /// flight — the FrameXML's own `if ( not name ) then name = UNKNOWN` covers that frame, so
-    /// the row shows "Unknown" rather than vanishing.
+    /// From the name cache; empty while the name query is in flight.
     pub name: String,
-    /// Level, `0` when offline (the wire sends no level for an offline friend).
     pub level: u32,
-    /// Localized class name ("Warrior"), empty when offline.
     pub class: String,
-    /// Zone name ("Elwynn Forest"), empty when offline or when the id has no `AreaTable` row.
+    /// The zone name, also empty when the id has no `AreaTable` row.
     pub area: String,
-    /// Online at all — `GetFriendInfo`'s fifth return, and what enables the Send Message /
-    /// Group Invite buttons.
     pub connected: bool,
-    /// The away tag as the friends-list template wants it: `""`, `"<AFK>"`, or `"<DND>"`.
+    /// The away tag the friends-list template takes: `""`, `"<AFK>"` or `"<DND>"`.
     pub status: String,
 }
 
-/// One `/who` row — `GetWhoInfo`'s six returns in order (note the wire's class/race order is
-/// swapped relative to this Lua-facing one: the API returns race *before* class).
+/// One `/who` row in `GetWhoInfo`'s order, names localized; race comes before class, where the
+/// wire has class first.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct WhoInfo {
     pub name: String,
     pub guild: String,
     pub level: u32,
-    /// Localized race name ("Night Elf").
     pub race: String,
-    /// Localized class name ("Druid").
     pub class: String,
-    /// Zone name.
     pub zone: String,
 }
 
-/// The social snapshot, pushed whole by the app whenever it changes ([`UiScript::set_social`]).
-/// `default()` is the fresh-login shape: no friends, no ignores, no `/who` run yet.
+/// The social snapshot the app pushes whole; the default is a fresh login's.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct SocialState {
-    /// The friend list, in the order the list frame shows it (the app sorts — the reference's
-    /// own `FriendList` comparator `0x5ada00` does the same engine-side).
+    /// In display order: the app sorts, as the reference's comparator `0x5ada00` does.
     pub friends: Vec<FriendInfo>,
-    /// The selected friend as a **1-based** index, `0` = none — `GetSelectedFriend`'s scale
-    /// (`0x5ad260` returns the stored slot + 1).
+    /// The selected friend, 1-based, 0 for none (`0x5ad260` returns the stored slot + 1).
     pub selected_friend: u32,
-    /// The ignore list: names only, which is all `GetIgnoreName` returns.
     pub ignores: Vec<String>,
-    /// The selected ignore, same 1-based scale.
+    /// The selected ignore, on the same scale.
     pub selected_ignore: u32,
-    /// The last `/who` answer's rows (≤ 49).
+    /// The last `/who` answer's rows, at most 49.
     pub who: Vec<WhoInfo>,
-    /// The last `/who` answer's *total* match count — `GetNumWhoResults`'s second return, which
-    /// can exceed `who.len()` and is what drives the "(50 displayed)" suffix.
+    /// The total match count, `GetNumWhoResults`'s second return; it can exceed `who.len()`.
     pub who_total: u32,
-    /// The `/who` sort chain ([`WhoSortChain`]) as the app holds it. Pushed with the rows because
-    /// `SortWho` has to promote it and re-sort **inside the binding** — the reference's
-    /// `WHO_LIST_UPDATE` is synchronous, so the redraw it triggers reads the new order before the
-    /// click script returns, a tick before the app's own copy could have pushed it back.
-    /// [`super::SocialRequest::SortWho`] carries the same click to the app, whose next push then
-    /// agrees. Same shape as `SetSelectedFriend`'s (module doc).
+    /// The `/who` sort chain, pushed so `SortWho` can re-sort before its synchronous redraw.
     pub who_sort: WhoSortChain,
 }
 
-/// Outbound social intents queued by the Era API, drained by the app
-/// ([`UiScript::take_social_requests`]). Plain data — [`super::party::PartyRequest`]'s twin.
+/// Outbound social intents, drained by the app.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum SocialRequest {
-    /// `ShowFriends()` — refresh the list (`CMSG_FRIEND_LIST`).
+    /// `ShowFriends()`: `CMSG_FRIEND_LIST`.
     RefreshFriends,
     /// `AddFriend(name)`.
     AddFriend(String),
-    /// `RemoveFriend(index)` — the friends frame's button, which addresses the *row*.
+    /// `RemoveFriend(index)`, from the friends frame's button.
     RemoveFriendIndex(u32),
-    /// `RemoveFriend(name)` — `/removefriend`, which addresses a name. One Era global takes
-    /// either, so the queue carries both shapes and the app resolves each to the guid the wire
-    /// wants.
+    /// `RemoveFriend(name)`, from `/removefriend`; the app resolves either shape to the guid.
     RemoveFriendName(String),
     /// `AddIgnore(name)`.
     AddIgnore(String),
     /// `DelIgnore(name)`.
     DelIgnore(String),
-    /// `AddOrDelIgnore(name)` — `/ignore`'s toggle: ignore if not ignored, un-ignore if it is.
-    /// The app decides which, because only it holds the list.
+    /// `AddOrDelIgnore(name)`, `/ignore`'s toggle; the app decides which, as it holds the list.
     ToggleIgnore(String),
-    /// `SetLookingForGroup(...)` committed a change: the slots as stored and the comment, for
-    /// `CMSG_SET_LOOKING_FOR_GROUP` (1961).
+    /// A changed `SetLookingForGroup`: slots and comment for `CMSG_SET_LOOKING_FOR_GROUP`.
     SetLookingForGroup { slots: [u32; 3], comment: String },
-    /// `SetSelectedFriend(index)` — mirrored into the app so the next push agrees.
+    /// `SetSelectedFriend(index)`, mirrored so the next push agrees.
     SelectFriend(u32),
     /// `SetSelectedIgnore(index)`.
     SelectIgnore(u32),
-    /// `SendWho(filter)` — the raw filter string as typed; parsing it into wire fields needs the
-    /// DBCs, so it happens app-side.
+    /// `SendWho(filter)`, the raw filter; parsing it needs the DBCs, so the app does it.
     Who(String),
-    /// `SortWho(sortType)` — `"name"`/`"level"`/`"class"`/`"zone"`/`"guild"`/`"race"`, the raw
-    /// argument as the click passed it. Sorting is client-side and the binding has **already**
-    /// done it to the snapshot ([`SocialState::who_sort`]); this carries the same click to the
-    /// app so its authoritative chain promotes identically and the next push agrees.
+    /// `SortWho(sortType)`, the raw argument; the binding has already sorted the snapshot.
     SortWho(String),
-    /// `SetWhoToUI(flag)` — where the *next* `/who` answer goes: the Who frame (true) or the chat
-    /// frame (false). The WhoFrame's own OnShow/OnHide drive it.
+    /// `SetWhoToUI(flag)`: the next `/who` answer goes to the Who frame (true) or chat (false).
     SetWhoToUi(bool),
 }
 
 impl super::UiScript {
-    /// Push the social snapshot, replacing whatever was there. A bare setter — firing
-    /// `FRIENDLIST_UPDATE`/`IGNORELIST_UPDATE`/`WHO_LIST_UPDATE` on the edges is the app's job.
+    /// Replace the social snapshot; firing `FRIENDLIST_UPDATE` and kin is the app's job.
     pub fn set_social(&mut self, state: SocialState) {
         self.model_mut().social = state;
     }
@@ -142,9 +96,7 @@ impl super::UiScript {
         std::mem::take(&mut self.model_mut().social_requests)
     }
 
-    /// Queue an intent from the app side — the slash commands. In the reference these ARE Lua
-    /// (`SlashCmdList["FRIENDS"]` calls `AddFriend`, …); benilla parses slash lines in Rust, so
-    /// the same intents enter the same queue here. [`super::duel`]'s `queue_duel_request` twin.
+    /// Queue an intent from the app side.
     pub fn queue_social_request(&mut self, request: SocialRequest) {
         self.model_mut().social_requests.push(request);
     }
@@ -154,8 +106,8 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // ── The friend list ──────────────────────────────────────────────────────────────────────
-    // GetNumFriends() → how many friends are listed (`0x5ad000` over CountFriends `0x5ae490`).
+    // ── The friend list ──
+    // GetNumFriends(): `0x5ad000` over CountFriends `0x5ae490`.
     g.set(
         "GetNumFriends",
         lua.create_function(|lua, ()| {
@@ -164,9 +116,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetFriendInfo(index) → name, level, class, area, connected, status (`0x5ad060`). An index
-    // past the end returns nothing at all — the FrameXML tests `if ( not name )`, so nil-per-
-    // return is the shape it expects, not an error.
+    // GetFriendInfo(index) (`0x5ad060`): an index past the end answers nils, not an error;
+    // FrameXML tests `if ( not name )`.
     g.set(
         "GetFriendInfo",
         lua.create_function(|lua, index: i64| {
@@ -186,7 +137,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 Value::Integer(i64::from(friend.level)),
                 Value::String(lua.create_string(&friend.class)?),
                 Value::String(lua.create_string(&friend.area)?),
-                // `connected` is the era 1/nil boolean the list frame branches on.
                 if friend.connected {
                     Value::Integer(1)
                 } else {
@@ -197,7 +147,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedFriend() → the 1-based selected row, 0 when nothing is selected.
     g.set(
         "GetSelectedFriend",
         lua.create_function(|lua, ()| {
@@ -206,8 +155,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetSelectedFriend(index) — mutate now (the caller reads it back this tick) and mirror the
-    // intent to the app (module doc: selection is engine state in the reference too).
+    // SetSelectedFriend(index): set now, since `FriendsList_Update` reads it back in the same
+    // call, and queue it for the app.
     g.set(
         "SetSelectedFriend",
         lua.create_function(|lua, index: i64| {
@@ -221,14 +170,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The LFG pair, as the bytes define it (wow-re `lfg-set-get-law.md`, 1961 — which corrects
-    // 1959's flag): the stock 1.12.1 FrameXML never calls either (FriendsFrame.xml's two call
-    // sites sit inside its l.1212-1301 XML comment), so this is an addon surface.
-    //
-    // `GetLookingForGroup()` → FOUR values: the three slot NAMES — each nil for a slot word whose
-    // id maps to nothing, and the reference's own pack (below) leaves every slot word 0, so nil
-    // is the only value a name can take here — then the comment, always a string. Never a
-    // number, never `1|nil`.
+    // The LFG pair (`0x4e95d0`, `0x4e96b0`) is for addons: stock FrameXML's only calls sit inside
+    // an XML comment. GetLookingForGroup() → the three slot names, each nil as the pack below
+    // always stores 0, then the comment string.
     g.set(
         "GetLookingForGroup",
         lua.create_function(|lua, ()| {
@@ -241,17 +185,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             ]))
         })?,
     )?;
-    // `SetLookingForGroup(type1, entry1, type2, entry2, type3, entry3, comment)` → nothing. Up to
-    // three pairs, read at arguments 1/3/5 and 2/4/6; the loop ENDS (it does not skip a pair) on
-    // a non-number type, a type >= 6, or an entry at or past the per-type eligible count, and the
-    // word it stores is `(type << 24) & entry` — an AND where every consumer decodes an OR
-    // (`0x4e9713`), so the stored word is 0 for every admissible input. Which is why the
-    // eligible-count table is not modelled: with the pack as it is, no admissible pair can store
-    // anything but 0, and an inadmissible one ends the loop leaving 0 — the slots never change.
-    // The comment is gated on argument 4 being a number or a string (`lua_isstring(L, 4)`) and
-    // read from argument 7 (`lua_tostring(L, 7)`, nil for an absent one); both immediates raw.
-    // The commit stores what changed and sends `CMSG_SET_LOOKING_FOR_GROUP` only then — so only a
-    // changed comment ever sends. `SStrCopy(…, 0x80)`: the comment keeps 127 bytes.
+    // SetLookingForGroup(type1, entry1, type2, entry2, type3, entry3, comment): the loop over the
+    // pairs ends at a non-number type or one >= 6. The stored word is `(type << 24) & entry`
+    // (`0x4e9713`), an AND every reader decodes as an OR, so an admissible pair stores 0; the
+    // per-type eligible-count check that also ends the reference's loop is not modelled. The
+    // comment is argument 7, read only when argument 4 passes `lua_isstring`, and keeps 127 bytes
+    // (`SStrCopy(…, 0x80)`). `CMSG_SET_LOOKING_FOR_GROUP` goes out only on a change.
     g.set(
         "SetLookingForGroup",
         lua.create_function(|lua, args: mlua::MultiValue| {
@@ -271,7 +210,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                     break;
                 }
                 let entry = number(&arg(i + 1)).unwrap_or(0.0).trunc();
-                // `(type << 24) & entry`, the reference's own pack.
+                // `&`, not `|`: the reference's own pack.
                 *slot = ((ty as u32) << 24) & (entry as i64 as u32);
             }
             let comment = match arg(4) {
@@ -317,7 +256,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ShowFriends() — ask the server for the list again.
     g.set(
         "ShowFriends",
         lua.create_function(|lua, ()| {
@@ -327,8 +265,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AddFriend(name) — an empty name is dropped here rather than sent: the server answers a
-    // blank lookup with nothing at all, so it would look like a hang.
+    // AddFriend(name): a blank name is not sent, as vmangos drops it without a reply
+    // (`MiscHandler.cpp:468`).
     g.set(
         "AddFriend",
         lua.create_function(|lua, name: String| {
@@ -340,8 +278,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // RemoveFriend(indexOrName) — the one global with two callers of different shapes (the
-    // frame's button passes a row index, /removefriend a name).
+    // RemoveFriend(indexOrName): the friends frame passes a row, `/removefriend` a name.
     g.set(
         "RemoveFriend",
         lua.create_function(|lua, who: Value| {
@@ -362,8 +299,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ── The ignore list ──────────────────────────────────────────────────────────────────────
-    // GetNumIgnores() → CountIgnores `0x5ae550` (the 25 slots at +0x650).
+    // ── The ignore list ──
+    // GetNumIgnores(): CountIgnores `0x5ae550`, over the 25 slots at `+0x650`.
     g.set(
         "GetNumIgnores",
         lua.create_function(|lua, ()| {
@@ -372,9 +309,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetIgnoreName(index) → the name, or nil past the end. The ignore list frame calls this for
-    // all 20 of its rows every update, most of them empty — nil is the ordinary case, not an
-    // error.
     g.set(
         "GetIgnoreName",
         lua.create_function(|lua, index: i64| {
@@ -389,8 +323,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedIgnore() / SetSelectedIgnore(index) — the friend pair's twin (`0x5ae630` /
-    // `0x5ae5f0`).
+    // GetSelectedIgnore / SetSelectedIgnore (`0x5ae630` / `0x5ae5f0`), as the friend pair.
     g.set(
         "GetSelectedIgnore",
         lua.create_function(|lua, ()| {
@@ -411,7 +344,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AddIgnore / DelIgnore / AddOrDelIgnore(name).
     for (global, make) in [
         ("AddIgnore", SocialRequest::AddIgnore as fn(String) -> _),
         ("DelIgnore", SocialRequest::DelIgnore as fn(String) -> _),
@@ -432,9 +364,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // ── /who ─────────────────────────────────────────────────────────────────────────────────
-    // GetNumWhoResults() → displayed, total. The second return is the server's true match count,
-    // which is why the frame can say "132 players total (50 displayed)".
+    // ── /who ──
+    // GetNumWhoResults() → displayed, total, the server's full match count.
     g.set(
         "GetNumWhoResults",
         lua.create_function(|lua, ()| {
@@ -446,7 +377,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetWhoInfo(index) → name, guild, level, race, class, zone.
     g.set(
         "GetWhoInfo",
         lua.create_function(|lua, index: i64| {
@@ -475,7 +405,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SendWho(filter) — the filter string as typed, parsed app-side.
     g.set(
         "SendWho",
         lua.create_function(|lua, filter: Option<String>| {
@@ -487,24 +416,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `SortWho(sortType) 0x5ad890` — the column-header and dropdown sorts, and three things at
-    // once (wow-re `who-list-sort-law.md`; decision 2030):
-    //
-    //  1. **promote** the key into the seven-slot chain, flipping its direction only if it was
-    //     already at the front — so a repeated click on the same header REVERSES;
-    //  2. **sort right here**, through the chain-walking comparator; and
-    //  3. fire `WHO_LIST_UPDATE` **synchronously**, inside the binding (`0x5ad9ed
-    //     mov ecx,0x184; call SignalEvent 0x703e50`), so `FriendsFrame_OnEvent` has already
-    //     re-read the list through `GetWhoInfo` by the time the header's OnClick plays its sound.
-    //     Queueing it would redraw a tick late — the visible half of B365.
-    //
-    // The intent still goes to the app, which owns the same chain and re-sorts the answers it
-    // receives; sorting the snapshot here is what makes the synchronous redraw show the new
-    // order, exactly as `SetSelectedFriend` mutates the snapshot it also queues (module doc).
-    //
-    // Zero return values, and a non-string/number argument RAISES with the client's own typo
-    // (`.rdata 0x85db88`) rather than answering nil — `0x5ad898`'s `0x6f3510` guard into
-    // `luaL_error`, [`super::binding_abi`]'s shape A.
+    // SortWho(sortType) (`0x5ad890`): promotes the key in the seven-slot chain, reversing it if
+    // it is already in front, sorts the list, and fires `WHO_LIST_UPDATE` synchronously
+    // (`0x5ad9ed`, `SignalEvent` `0x703e50`), so the list redraws before the click's sound. The
+    // app gets the same click for its own chain. Returns nothing; an argument neither string nor
+    // number raises with the client's own typo (`0x85db88`, `0x5ad898`'s `0x6f3510` guard).
     g.set(
         "SortWho",
         lua.create_function(|lua, sort_type: Value| {
@@ -523,8 +439,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetWhoToUI(flag) — the WhoFrame's OnShow/OnHide. Era passes 0/1, so anything but a falsey
-    // 0/nil is "the frame wants them".
+    // SetWhoToUI(flag): the Who frame passes 1 on show and 0 on hide; nil, false and 0 are off.
     g.set(
         "SetWhoToUI",
         lua.create_function(|lua, flag: Value| {
@@ -548,8 +463,7 @@ fn friend_at(friends: &[FriendInfo], index: i64) -> Option<&FriendInfo> {
     usize::try_from(index - 1).ok().and_then(|i| friends.get(i))
 }
 
-/// Clamp a selection index to `0..=len` — `0` means "nothing selected", and a row past the end
-/// selects nothing rather than a phantom.
+/// A selection index in `1..=len`, else 0, nothing selected.
 fn clamp_index(index: i64, len: usize) -> u32 {
     if index >= 1 && index <= len as i64 {
         index as u32
@@ -574,9 +488,7 @@ mod tests {
         }
     }
 
-    /// A VM seeded with two hits and a watcher that records the order it can SEE from inside the
-    /// `WHO_LIST_UPDATE` handler — which is the only vantage point that can tell a synchronous
-    /// fire from a queued one.
+    /// Two `/who` hits and a `WHO_LIST_UPDATE` handler that records the order it sees.
     fn seated() -> UiScript {
         let mut s = UiScript::new().unwrap();
         s.run(
@@ -606,10 +518,7 @@ mod tests {
         s
     }
 
-    /// **B365.** `SortWho` sorts the list it already holds, fires `WHO_LIST_UPDATE`
-    /// **synchronously** so the handler reads the NEW order (`0x5ad9ed`, `SignalEvent 0x703e50`
-    /// running every listener inline), and queues the same click for the app. A queued event
-    /// would leave `order` one click stale here — which is exactly what the bug looked like.
+    /// A queued event would leave `order` one click stale.
     #[test]
     fn sort_who_sorts_in_place_and_fires_the_event_synchronously() {
         let mut s = seated();
@@ -627,14 +536,11 @@ mod tests {
             vec![SocialRequest::SortWho("name".into())],
             "and the app hears the same click, so its copy of the chain follows"
         );
-        // Zero return values (`0x5ad9f8 xor eax,eax; ret`).
+        // Returns nothing (`0x5ad9f8`, `xor eax,eax; ret`).
         assert_eq!(s.arity(r#"SortWho("name")"#).unwrap(), 0);
         assert!(s.errors().is_empty(), "{:?}", s.errors());
     }
 
-    /// The visible half of the report: **clicking the same header twice reverses**, and clicking
-    /// a different one in between does not undo that — the direction is remembered per key and
-    /// flipped only when the key was already at the front of the chain.
     #[test]
     fn a_repeated_header_click_reverses_and_the_direction_is_remembered() {
         let s = seated();
@@ -652,8 +558,7 @@ mod tests {
         s.run(r#"SortWho("level")"#).unwrap();
         assert_eq!(s.eval::<String>("return order").unwrap(), "Erdrin,Galas,");
 
-        // Back to name: promoted from slot 1, so it CARRIES its descending direction rather than
-        // flipping to ascending.
+        // Back to name, promoted from slot 1: it keeps its descending direction.
         s.run(r#"SortWho("name")"#).unwrap();
         assert_eq!(
             s.eval::<String>("return order").unwrap(),
@@ -667,9 +572,8 @@ mod tests {
         );
     }
 
-    /// The argument ABI: a number is stringified and falls through to the name key; anything that
-    /// is neither number nor string RAISES with the client's own misspelt usage string
-    /// (`.rdata 0x85db88`), abandoning the caller's statement rather than answering nil.
+    /// A number is stringified and falls to the name key; anything else raises with the client's
+    /// misspelt usage string (`0x85db88`).
     #[test]
     fn sort_who_takes_the_reference_argument_abi() {
         let mut s = seated();
@@ -693,9 +597,6 @@ mod tests {
         );
     }
 
-    /// The LFG pair as the bytes define it (1961, correcting 1959): four string-or-nil returns,
-    /// the slots zeroed by the reference's own pack, the comment from argument 7 behind the gate
-    /// on argument 4, and the wire only on a change.
     #[test]
     fn the_lfg_pair_stores_the_comment_and_sends_only_on_a_change() {
         let mut s = UiScript::new().unwrap();
@@ -705,7 +606,7 @@ mod tests {
                 "local a, b, c, d = GetLookingForGroup() return a == nil and b == nil and c == nil and d == \"\""
             )
             .unwrap());
-        // Three admissible pairs: every word packs to 0, nothing changed, nothing sent.
+        // Three admissible pairs: every word packs to 0, so nothing changes or sends.
         s.run("SetLookingForGroup(1, 3, 3, 12, 5, 0)").unwrap();
         assert!(
             s.take_social_requests().is_empty(),
@@ -726,11 +627,10 @@ mod tests {
                 .unwrap(),
             "LF2M UBRS"
         );
-        // The same comment again: no change, no send.
         s.run(r#"SetLookingForGroup(1, 3, 3, 12, 5, 0, "LF2M UBRS")"#)
             .unwrap();
         assert!(s.take_social_requests().is_empty());
-        // Fewer than four arguments: the comment at 7 is never read.
+        // Argument 4 nil: the comment at 7 is not read.
         s.run(r#"SetLookingForGroup(1, 3, nil, nil, nil, nil, "ignored")"#)
             .unwrap();
         assert!(s.take_social_requests().is_empty());
diff --git a/crates/benilla-ui/src/script/sound.rs b/crates/benilla-ui/src/script/sound.rs
index a1a82112..1883d433 100644
--- a/crates/benilla-ui/src/script/sound.rs
+++ b/crates/benilla-ui/src/script/sound.rs
@@ -1,59 +1,63 @@
-//! The `PlaySound`/`PlaySoundFile` bindings — the first **Lua→app intent queue** (decisions
-//! 0068 §3 / 0070 §4).
+//! The sound bindings: `PlaySound`, `PlaySoundFile`, `PlayMusic` and `StopMusic` each queue a
+//! plain request for the app to drain, since the engine does not touch the app's mixer.
 //!
-//! The engine must not touch the app's systems (the same seam that keeps [`super::unit`]'s
-//! bindings reading a pushed snapshot), so an outbound *action* can't call the mixer either:
-//! `PlaySound` pushes a plain [`SoundRequest`] onto a queue in [`super::Model`], and the app
-//! drains it each frame via [`UiScript::take_sounds`](super::UiScript::take_sounds) into its kit
-//! player. This queue-drain shape is the pattern every Lua→app intent follows (`CastSpell`,
-//! `UseAction`, … ride the same seam as they land).
+//! `PlaySound` takes a kit name, as the reference's binding does (`0x4586d0` reaches only
+//! `PlaySoundByName`, `0x458030`), and also Era's numeric kit id, which 1.12's binding does not
+//! take (the client plays a kit id internally through `0x458850`). Both verbs answer Era's
+//! `willPlay, soundHandle`, true and nil, not 1.12's shapes: the reference's `PlaySound` answers
+//! nothing and its `PlaySoundFile` one value (`reference/1.12-shapes.tsv`).
 //!
-//! Surface: the Era signature `PlaySound(soundKitID[, channel, forceNoDuplicates])` (addons pass
-//! numeric `SOUNDKIT.*` ids), plus the 1.12-native by-name form `PlaySound("KitName")` — the
-//! client resolved both (`PlaySoundById 0x458850` / `PlaySoundByName 0x458030`), and our kit
-//! player keeps both entries. Returns `willPlay, soundHandle`: `willPlay` reports "queued" —
-//! whether the kit actually plays is decided at drain time by the kit player's own gates
-//! (audibility, duplicate suppression), which the client also treats as silent non-errors; the
-//! handle is nil (no stop-by-handle surface yet). The `channel`/`forceNoDuplicates` extras are
-//! accepted and ignored for now — the kit's own `SoundType`/flags decide category and dedup.
-//!
-//! `PlaySoundFile("Sound\\...\\file.wav")` is the sibling by-path form (the 1.12 client resolves
-//! it through the same file layer as kit entries — MPQ chain, loose files shadowing): no kit, so
-//! no gates and no variation; same queue, same returns.
+//! The music pair drives its own slot: the reference gives Lua a stream of its own (`[0xb06ccc]`,
+//! opened in `0x460450` at `0x4604a7`) beside the zone track's (`[0xb06cc4]`), one of the client's
+//! two endlessly looping streams (`0x7a5592`). `StopMusic` (`0x458770`) is `0x460450` with a null
+//! name, so a [`MusicRequest`] is the argument, not the verb. Neither answers anything.
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// One queued `PlaySound` intent, drained by the app (plain data — the engine-free seam).
+/// One queued sound for the app's kit player.
 #[derive(Clone, Debug, PartialEq)]
 pub enum SoundRequest {
-    /// `PlaySound(id)` — a `SoundEntries` kit id (the Era `SOUNDKIT.*` form).
+    /// `PlaySound(id)`: a `SoundEntries` kit id, Era's form.
     KitId(u32),
-    /// `PlaySound("name")` — a kit name (the 1.12 `PlaySoundByName` form).
+    /// `PlaySound("name")`: a kit name, the 1.12 form.
     KitName(String),
-    /// `PlaySoundFile("path")` — a raw file path, no kit.
+    /// `PlaySoundFile("path")`: a file path, no kit.
     File(String),
 }
 
+/// One queued `PlayMusic` or `StopMusic`, for the app's Lua music slot.
+#[derive(Clone, Debug, PartialEq)]
+pub enum MusicRequest {
+    /// `PlayMusic("path")`: start the caller's looping stream.
+    Play(String),
+    /// `StopMusic()`: `0x460450` with no name.
+    Stop,
+}
+
 impl super::UiScript {
-    /// Drain the sounds queued by `PlaySound` since the last call. The app plays each through its
-    /// kit player (2D — UI sounds have no world position).
-    /// Queue a kit play from the APP side (the client's C++-fired UI sounds — QUESTADDED on a
-    /// log add, QUESTCOMPLETED on the turn-in packet — which no Lua handler owns). Drained by the
-    /// same [`UiScript::take_sounds`] as every Lua `PlaySound`.
+    /// Queue a kit play from the app side, for the UI sounds the client fires from C++
+    /// (`QUESTADDED` on a log add, `QUESTCOMPLETED` on the turn-in) that no Lua handler owns.
     pub fn queue_sound_kit(&mut self, name: &str) {
         self.model_mut()
             .sound_queue
             .push(SoundRequest::KitName(name.to_string()));
     }
 
+    /// Drain the queued sounds; the app plays each in 2D, as UI sounds have no world position.
     pub fn take_sounds(&mut self) -> Vec<SoundRequest> {
         std::mem::take(&mut self.model_mut().sound_queue)
     }
+
+    /// Drain the music intents in call order: a play and a stop in one frame are a track or
+    /// silence by their order.
+    pub fn take_music(&mut self) -> Vec<MusicRequest> {
+        std::mem::take(&mut self.model_mut().music_queue)
+    }
 }
 
-/// Register the `PlaySound` and `PlaySoundFile` globals.
+/// Register the sound and music globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.globals().set(
         "PlaySoundFile",
@@ -78,33 +82,57 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 _ => None,
             };
             let Some(req) = req else {
-                // The client raises a usage error on a bad argument; in a handler this lands in
-                // the host's collected script errors, never a panic.
+                // A bad argument raises a usage error, as the reference's does.
                 return Err(mlua::Error::runtime(
                     "Usage: PlaySound(soundKitID or \"KitName\")",
                 ));
             };
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // `PlaySoundByName 0x458030`'s first act: read the UI-load suppression depth
-            // (`0x458046`) and bail at `0x45804d` if it is non-zero — BEFORE the
-            // `MasterSoundEffects` CVar and before the kit-hash lookup. So the call is dropped
-            // rather than muted or queued, and the binding still answers as if it had played.
-            // NAME-keyed only: the id-keyed entry (`0x457fb0`) has no such gate, which is why the
-            // arm above pushes unconditionally.
+            // During the UI load a by-name play is dropped before any other gate (`0x458046`,
+            // `0x45804d`), while the binding still answers; the id entry (`0x457fb0`) has no
+            // such gate.
             let suppressed = matches!(req, SoundRequest::KitName(_)) && model.sound_suppression > 0;
             if !suppressed {
                 model.sound_queue.push(req);
             }
             drop(model);
-            // willPlay (queued), soundHandle (nil — module docs).
             Ok((true, Value::Nil))
         })?,
+    )?;
+    lua.globals().set(
+        "PlayMusic",
+        lua.create_function(|lua, args: mlua::MultiValue| {
+            // `0x458720`: `lua_isstring` (`0x6f3510`), then `lua_tostring` (`0x6f3690`), so a
+            // number becomes a file name and anything else raises this literal (`0x835f7c`,
+            // `0x458758`); the path goes to the file layer verbatim.
+            let path = super::binding_abi::string_arg(
+                lua,
+                args.front().cloned().unwrap_or(Value::Nil),
+                "Usage: PlayMusic(\"music\")",
+            )?;
+            lua.app_data_mut::<Model>()
+                .expect("model app_data")
+                .music_queue
+                .push(MusicRequest::Play(path));
+            Ok(())
+        })?,
+    )?;
+    lua.globals().set(
+        "StopMusic",
+        // Reads no argument (`0x458770`), so an extra one is ignored.
+        lua.create_function(|lua, ()| {
+            lua.app_data_mut::<Model>()
+                .expect("model app_data")
+                .music_queue
+                .push(MusicRequest::Stop);
+            Ok(())
+        })?,
     )
 }
 
 #[cfg(test)]
 mod tests {
-    use super::SoundRequest;
+    use super::{MusicRequest, SoundRequest};
     use crate::script::UiScript;
 
     #[test]
@@ -114,7 +142,7 @@ mod tests {
             .eval("local w, h = PlaySound(1234) return w, h == nil")
             .unwrap();
         assert!(will_play && handle_is_nil);
-        // Era extras accepted and ignored; the by-name 1.12 form works too.
+        // Era's extra arguments are ignored.
         s.run(r#"PlaySound(841, "SFX", true)"#).unwrap();
         s.run(r#"PlaySound("GAMEOBJECT_DOOROPEN")"#).unwrap();
         s.run(r#"PlaySoundFile("Sound\\Doodad\\BellTollHorde.wav")"#)
@@ -129,10 +157,54 @@ mod tests {
                 SoundRequest::File("Sound\\Doodad\\BellTollHorde.wav".into()),
             ]
         );
-        // Drained: the queue is empty until the next PlaySound.
         assert!(s.take_sounds().is_empty());
     }
 
+    #[test]
+    fn the_music_pair_queues_in_call_order_and_answers_nothing() {
+        let mut s = UiScript::new().unwrap();
+        // Counted with `table.getn`: Lua 5.0 has no `select`.
+        let (played, stopped): (usize, usize) = s
+            .eval(
+                r#"return table.getn({PlayMusic("Sound\\Music\\x.mp3")}),
+                          table.getn({StopMusic()})"#,
+            )
+            .unwrap();
+        assert_eq!((played, stopped), (0, 0));
+        s.run(r#"PlayMusic("Sound\\Music\\ZoneMusic\\Elwynn\\DayElwynn01.mp3")"#)
+            .unwrap();
+        s.run("StopMusic()").unwrap();
+        assert_eq!(
+            s.take_music(),
+            vec![
+                MusicRequest::Play("Sound\\Music\\x.mp3".into()),
+                MusicRequest::Stop,
+                MusicRequest::Play("Sound\\Music\\ZoneMusic\\Elwynn\\DayElwynn01.mp3".into()),
+                MusicRequest::Stop,
+            ]
+        );
+        assert!(s.take_music().is_empty());
+        assert!(s.take_sounds().is_empty());
+    }
+
+    #[test]
+    fn playmusic_takes_a_string_or_a_number_and_stopmusic_takes_anything() {
+        let mut s = UiScript::new().unwrap();
+        assert!(s.run("PlayMusic()").is_err());
+        assert!(s.run("PlayMusic(nil)").is_err());
+        assert!(s.run("PlayMusic(true)").is_err());
+        assert!(s.run("PlayMusic({})").is_err());
+        assert!(s.take_music().is_empty(), "a raise queues nothing");
+
+        // The reference asks the file layer for `"42"` and plays nothing.
+        s.run("PlayMusic(42)").unwrap();
+        s.run("StopMusic(1, 2)").unwrap();
+        assert_eq!(
+            s.take_music(),
+            vec![MusicRequest::Play("42".into()), MusicRequest::Stop]
+        );
+    }
+
     #[test]
     fn playsound_with_a_bad_argument_is_a_usage_error() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/spellbook.rs b/crates/benilla-ui/src/script/spellbook.rs
index f1d02b92..0fdf347a 100644
--- a/crates/benilla-ui/src/script/spellbook.rs
+++ b/crates/benilla-ui/src/script/spellbook.rs
@@ -1,52 +1,13 @@
-//! The spellbook (decision 0216 §8, slice 5) — the spell **source** for the cursor payload
-//! system: a read-only book model the app builds from `PlayerActions.spells`
-//! (`SMSG_INITIAL_SPELLS`), the same two-way seam shape as [`super::merchant`]/[`super::action`]:
-//! the app pushes a **book snapshot** ([`UiScript::set_spellbook`] — tabs + the flat slot list,
-//! already resolved to name/rank/icon/passive by the app's `benilla_formats::SpellCatalog` ×
-//! skill-line join), and `CastSpell`/`PickupSpell` queue outbound intents the app drains
-//! ([`UiScript::take_spell_casts`] / the cursor seam's own `CursorPayload::Spell` arm — decision
-//! 0216 §1). The engine holds no spell KNOWLEDGE (icons/ranks/skill lines are the app's job) — a
-//! slot is "a spell id, a name, a rank, a texture, and a passive bit".
+//! The spellbook bindings, over a book the app pushes (tabs and a flat slot list, already resolved
+//! to name, rank, icon and passive); `CastSpell` and `PickupSpell` queue intents the app drains.
 //!
-//! ## The book-id seam (decision 0218 §4's byte-verified 0-based book slot)
+//! FrameXML passes every binding a 1-based book id (`SpellBook_GetSpellID`), and the reference's
+//! marshaller (`0x4b3ec0`) subtracts 1, as [`slot_index`] does. `BOOKTYPE_PET` selects the pet's
+//! slot list, fed from `SMSG_PET_SPELLS`, where `PickupSpell` and `CastSpell` produce a pet action
+//! word and a `CMSG_PET_ACTION` instead.
 //!
-//! The ref's own FrameXML computes a **1-based, per-tab-cumulative "book id"**
-//! (`SpellBookFrame.lua`'s `SpellBook_GetSpellID`: `buttonId + tabOffset + 12*(page-1)`, where
-//! `buttonId` is a spell button's own 1..12 `id=` attribute and `tabOffset` is
-//! `GetSpellTabInfo`'s own `offset` return) and passes that SAME id, unmodified, to every one of
-//! `GetSpellName`/`GetSpellTexture`/`IsSpellPassive`/`CastSpell`/`PickupSpell`. 0218 §4 byte-read
-//! `PickupSpell`'s own argument as a **0-based book slot** — so the real client's Lua↔C++ glue
-//! does the `-1` itself, invisibly to FrameXML. This engine keeps the ref's exact Lua-facing
-//! convention (every binding below takes the SAME 1-based-cumulative `id` a transcribed
-//! `SpellBookFrame.xml` computes and passes verbatim, so the transcription needs no special
-//! casing) and does the byte-verified `-1` at THIS one seam ([`slot_index`]) before indexing
-//! [`SpellBookState::slots`] (0-based, flat, tab order). `GetSpellTabInfo`'s pushed `offset` is
-//! therefore exactly each tab's 0-based START index into `slots` — the app computes it as the
-//! running sum of every earlier tab's `num_spells` (tab 1's is `0`, so its first spell's book id
-//! is `1`, matching the ref's own "first tab's first spell is id 1").
-//!
-//! ## The pet book (decision 1032 — live; 0216 §8's deferral is retired)
-//!
-//! `BOOKTYPE_PET` selects a **second slot list** ([`PetBookState`]), fed from `SMSG_PET_SPELLS`'
-//! own spell tail. Every `bookType`-taking binding is a two-way fork ([`book_slot`]) exactly as the
-//! reference's are — `isPet ? [0xb6f098 + 4*i] : [0xb700f0 + 4*i]`, written out once per binding —
-//! and the three pet-only bindings (`HasPetSpells`, `GetSpellAutocast`, `ToggleSpellAutocast`) live
-//! here with them.
-//!
-//! Two asymmetries are the API and not tidiable away:
-//!
-//! - `GetNumSpellTabs`/`GetSpellTabInfo` take **no** `bookType` and only ever answer the player's
-//!   skill lines. That is the reference's own signature: the pet book has no tabs, and
-//!   `SpellBookFrame_Update` hides the whole skill-line strip while it is up.
-//! - `PickupSpell` and `CastSpell` produce a **different kind of thing** on the pet side — a pet
-//!   action word on the cursor (`0x494e20`, cursor modes 1-7) and a `CMSG_PET_ACTION` on the wire
-//!   (`0x4b34ce`) — rather than a spell payload and a player cast. See each binding.
-//!
-//! `BOOKTYPE_SPELL`/`BOOKTYPE_PET` are installed as plain Lua globals here rather than left to the
-//! transcribed XML's own `<Script>` block (the ref's actual home for them, `SpellBookFrame.lua:
-//! 5-6`, and this crate's usual house rule for Era top-level constants) — the one deliberate
-//! exception, so this module's OWN engine-level tests can drive the pet-deferral path without
-//! loading a real `SpellBookFrame.xml`.
+//! Deviation: `BOOKTYPE_SPELL`/`BOOKTYPE_PET` are engine globals here, where the reference defines
+//! them in `SpellBookFrame.lua:5-6`, so this module's tests run without the stock file.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -57,14 +18,13 @@ use super::Model;
 const BOOKTYPE_SPELL: &str = "spell";
 const BOOKTYPE_PET: &str = "pet";
 
-/// `HasPetSpells`' second return when the app has not resolved a token — the reference's own
-/// literal at `0x846a40`, pushed by `0x4b44a6` whenever the player object fails to resolve. Never
-/// nil: FrameXML concatenates it (`"PET_TYPE_"..token`), which would error on one.
+/// `HasPetSpells`' second return when no token is resolved: the reference's literal (`0x846a40`),
+/// pushed at `0x4b44a6` when the player object does not resolve. FrameXML concatenates it, so
+/// never nil.
 const PET_TOKEN_FALLBACK: &str = "PET";
 
-/// One skill-line tab (`GetSpellTabInfo`'s own Era tuple shape). `offset` is the tab's 0-based
-/// START index into [`SpellBookState::slots`] (module docs' book-id seam) — pushed by the app,
-/// trusted here (the engine holds no spell knowledge to derive it from itself).
+/// One skill-line tab as `GetSpellTabInfo` returns it; `offset` is the tab's 0-based start in
+/// [`SpellBookState::slots`], computed by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct SpellTabView {
     pub name: String,
@@ -73,72 +33,49 @@ pub struct SpellTabView {
     pub num_spells: u32,
 }
 
-/// One spell in the flat book (0-based [`SpellBookState::slots`] index; module docs' book-id
-/// seam). Every field is pre-resolved by the app — the engine draws whatever it's given.
+/// One spell in the flat book, every field resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct SpellSlotView {
     pub spell_id: u32,
     pub name: String,
-    /// The rank/subtext line (`Spell.dbc`'s `NameSubtext`, `benilla-formats`' own pin); `None`
-    /// shows no second line.
+    /// The rank line, `Spell.dbc`'s `NameSubtext`; `None` shows no second line.
     pub rank: Option<String>,
     pub texture: Option<String>,
-    /// `SPELL_ATTR_PASSIVE` (`benilla-formats`' `SpellDisplay::passive`) — grays the name in the
-    /// transcribed XML and refuses both [`CastSpell`]-family casts (this module) and, faithfully,
-    /// nothing else: a passive can still be picked up/placed on a bar (the ref never blocks that).
+    /// `SPELL_ATTR_PASSIVE`: grays the name and refuses `CastSpell` and `CastSpellByName`, never
+    /// a pickup (the reference does not block one).
     pub passive: bool,
-    /// The `IsCurrentCast` verdict for this slot — the checked ring (`SpellButton_UpdateSelection`'s
-    /// gold glow). The delegate `0x4b3600` has exactly two arms (wow-re
-    /// `spellbook-checked-predicate.md`): a shapeshift spell whose form is the player's current
-    /// form byte, or the open trade-skill window's own spell — never an ordinary in-flight cast.
-    /// App-resolved (`benilla::ui_spellbook`), pushed with the book; the app fires
-    /// `CURRENT_SPELL_CAST_CHANGED` on its edges.
+    /// `IsCurrentCast`, the checked ring: the reference (`0x4b3600`) answers it only for a
+    /// shapeshift into the player's current form or the open trade-skill window's spell, never an
+    /// ordinary cast.
     pub current: bool,
-    /// The spell's running cooldown as `(start_ms on the GetTime clock, duration_ms, enabled)` —
-    /// the same app-computed triple [`super::ActionState::cooldown`] and the container slots
-    /// carry, resolved by the ONE cooldown store (`benilla::cooldowns::Cooldowns::info` — id,
-    /// category and GCD reads alike); `GetSpellCooldown` answers the reference's
-    /// `(start, duration, enable)`. `None` = cold. Frame-stable per arm (the absolute start), so
-    /// a running cooldown never churns the book diff.
+    /// `(start_ms on the GetTime clock, duration_ms, enabled)`, the triple the action bar carries;
+    /// `None` is cold. The start is absolute, so a running cooldown never churns the book diff.
     pub cooldown: Option<(i64, u32, bool)>,
-    /// `GetSpellAutocast`'s `(allowed, enabled)` pair — **pet-book only**, and `None` is not
-    /// "neither": it is the reference's own player-book answer, `(nil, nil)`, because `0x4b4180`
-    /// short-circuits on the book flag (`0x4b41cb`/`0x4b41d6`) before it looks a spell up at all.
-    /// Read off the pet's **raw** word (`0x4bd160` → bits 31/30), never off the filtered book.
+    /// `GetSpellAutocast`'s `(allowed, enabled)`, pet book only, read off the pet's raw word
+    /// (`0x4bd160`, bits 31 and 30).
     pub autocast: Option<(bool, bool)>,
-    /// The pet slot's packed word **verbatim** — what `PickupSpell(id, "pet")` puts on the cursor.
-    /// `0x4b3260`'s pet arm hands `0x494e20` a *pointer* to this very word, so the payload is the
-    /// server's own dword, type byte and autocast bits included, not a synthesized one. `0` for a
-    /// player-book slot, which has no word.
+    /// The pet slot's packed word as the server sent it, which `PickupSpell(id, "pet")` puts on the
+    /// cursor (`0x4b3260` hands `0x494e20` a pointer to it); 0 in the player book.
     pub packed: u32,
 }
 
-/// The **pet's** book — the reference's second flat array (`0xb6f098`, count `0xb71174`), which is
-/// a genuinely different object from the player's rather than a variant of it:
+/// The pet's book, the reference's second flat array (`0xb6f098`, count `0xb71174`):
 ///
-/// - **no tabs.** `GetNumSpellTabs`/`GetSpellTabInfo` take no `bookType` and only ever answer the
-///   player's skill lines; `SpellBookFrame_Update` hides every skill-line tab while the pet book is
-///   up (`SpellBookFrame.lua:124`), and `SpellBook_GetSpellID` returns the button's own 1..12 id
-///   with no tab offset at all (`l.460-462`).
-/// - **a different add-gate.** `0x4b2f90` admits a spell iff it resolves in `Spell.dbc` **and**
-///   `Attributes & 0x80` (DO_NOT_DISPLAY) is clear — `0x4b2fa8 mov dl,[rec+0x18]; test dl,dl; js`.
-///   That is *one* of the three tests the player book's own gate makes: no `IS_TRADESKILL` leg and
-///   no `castUI == 0` leg. Reusing the player book's gate here would be the same class of mistake
-///   as reusing its tab routing.
-/// - **the same order.** `0x4b2fd0(ecx = 0, edx = 1)` sorts it with `0x4b30c0`, the player book's
-///   own comparator (name, then parsed rank), and tail-jumps `SPELLS_CHANGED`.
+/// - no tabs, so `GetNumSpellTabs` and `GetSpellTabInfo` take no book type: `SpellBookFrame_Update`
+///   hides the skill-line tabs for it (`SpellBookFrame.lua:124`) and `SpellBook_GetSpellID` adds
+///   no tab offset (`SpellBookFrame.lua:460-462`);
+/// - its own add gate (`0x4b2f90`): in `Spell.dbc` with `Attributes & 0x80` (DO_NOT_DISPLAY)
+///   clear, without the player book's tradeskill and `castUI` tests;
+/// - the player book's order: `0x4b2fd0` sorts it with `0x4b30c0` (spell-line group, name, rank).
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PetBookState {
-    /// `HasPetSpells`'s second return: `ChrClasses.dbc` field 4 for the player's class — `"PET"`
-    /// or `"DEMON"` (`benilla_formats::PetNameTokens`). A **key**, not display text: FrameXML does
-    /// `getglobal("PET_TYPE_"..token)`. `None` only while there is no book at all.
+    /// `HasPetSpells`' second return, `ChrClasses.dbc` field 4 (`"PET"` or `"DEMON"`), a key
+    /// FrameXML looks up as `PET_TYPE_<token>`; `None` only while there is no book.
     pub token: Option<String>,
     pub slots: Vec<SpellSlotView>,
 }
 
-/// The player's known-spell book: tabs (skill lines) + the flat slot list every tab indexes into
-/// (module docs). Durable player state, not a session window (like [`super::action`]'s
-/// `actions` map) — never `Option`; "no known spells yet" is simply empty vectors.
+/// The player's book: the skill-line tabs and the flat slot list they index into.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct SpellBookState {
     pub tabs: Vec<SpellTabView>,
@@ -146,99 +83,75 @@ pub struct SpellBookState {
 }
 
 impl super::UiScript {
-    /// Push the whole book snapshot (tabs + flat slots), replacing whatever was there. A bare
-    /// setter — firing `SPELLS_CHANGED` is the app's own diff-and-fire job (mirroring
-    /// `set_action`/`set_container`; never auto-fired here).
+    /// Replace the book; the app fires `SPELLS_CHANGED` on its own diff.
     pub fn set_spellbook(&mut self, state: SpellBookState) {
         self.model_mut().spellbook = state;
     }
 
-    /// Push the pet's book ([`PetBookState`]), replacing whatever was there. A bare setter for the
-    /// same reason as its sibling: the reference fires `SPELLS_CHANGED` for **both** books off the
-    /// one re-sort (`0x4b2fd0` → `SignalEvent(0x104)`), and whose diff moved is the app's to know.
+    /// Replace the pet's book; the app fires `SPELLS_CHANGED`, which the reference fires for both
+    /// books off one re-sort (`0x4b2fd0`).
     pub fn set_pet_book(&mut self, state: PetBookState) {
         self.model_mut().pet_book = state;
     }
 
-    /// Drain the pet spell ids `CastSpell(id, "pet")` queued. Separate from
-    /// [`Self::take_spell_casts`] because the wire verb is different in kind: the dispatcher's pet
-    /// arm sends **`CMSG_PET_ACTION`** with a synthesized type-1 word (`0x4b34ce`), not a player
-    /// cast, so folding them into one queue would lose which end of the leash the cast came from.
+    /// Drain the pet spell ids `CastSpell(id, "pet")` queued: each is a `CMSG_PET_ACTION` with a
+    /// type-1 word (`0x4b34ce`), not a player cast.
     pub fn take_pet_spell_casts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().pet_spell_casts)
     }
 
-    /// Drain the pet spell ids `ToggleSpellAutocast` queued — the pet **book**'s autocast verb,
-    /// which is a different opcode from the pet **bar**'s ([`super::pet::UiScript::…`]'s
-    /// `take_pet_autocast_toggles` → `CMSG_PET_SET_ACTION`): this one is
-    /// `CMSG_PET_SPELL_AUTOCAST 0x2F3` and names a spell id rather than a bar slot
-    /// (`0x4b4291` → `0x4bccb0`).
+    /// Drain the spell ids `ToggleSpellAutocast` queued: `CMSG_PET_SPELL_AUTOCAST` (0x2F3, sent by
+    /// `0x4bccb0`) names a spell id, where the pet bar's toggle sends `CMSG_PET_SET_ACTION`.
     pub fn take_pet_spell_autocasts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().pet_spell_autocasts)
     }
 
-    /// Read the book back — for the ONE app-side consumer that must resolve a spell name by the
-    /// same law `CastSpellByName` does: a macro's bound spell (`benilla::ui_macro`, decision
-    /// 0983). Going through the pushed book rather than re-deriving from the catalog is what
-    /// stops the bar's cooldown swirl and the macro's own cast disagreeing about which rank a
-    /// bare `/cast Fireball` means.
+    /// The pushed book, for resolving a macro's spell by the rule `CastSpellByName` uses, so the
+    /// bar and the cast agree on which rank a bare `/cast` means.
     pub fn spellbook(&self) -> SpellBookState {
         self.model_mut().spellbook.clone()
     }
 
-    /// Drain the spell ids `CastSpell` queued since the last call.
+    /// Drain the spell ids `CastSpell` and `CastSpellByName` queued.
     pub fn take_spell_casts(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().spell_casts)
     }
 
-    /// Push whether the app's cast lifecycle holds something `SpellStopCasting()` can stop — a
-    /// running auto-repeat or an in-flight cast, but NOT a channel (the ref's `0x6e6e80` reads
-    /// only the auto-repeat key `0xceac30` and the inflight id `0xceca88`, and the inflight id
-    /// is already 0 during a channel — wow-re `esc-stopcasting.md`). Pushed each frame by the
-    /// app's cast feed (`benilla::ui_cast`), before the input pass runs the ESC chain.
+    /// Whether `SpellStopCasting()` has something to stop: an auto-repeat or an in-flight cast,
+    /// never a channel (`0x6e6e80` reads only the auto-repeat key `0xceac30` and the in-flight
+    /// id `0xceca88`, which is 0 mid-channel). Pushed each frame before the ESC chain runs.
     pub fn set_casting(&mut self, casting: bool) {
         self.model_mut().casting = casting;
     }
 
-    /// Drain the `SpellStopCasting()` trigger: `true` if it fired on a stoppable state since
-    /// the last call — the ESC leg of the local self-cancel (`benilla::ui_cast` resolves WHICH
-    /// thing dies: auto-repeat first, else the in-flight cast — the ref's branch order).
+    /// Drain the `SpellStopCasting()` trigger; the app stops the auto-repeat first, else the
+    /// in-flight cast, the reference's order.
     pub fn take_spell_stop(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().spell_stop)
     }
 
-    /// Push whether the app's spell-targeting cursor mode is active (decision 0792) — what
-    /// `SpellIsTargeting()` reads and `SpellStopTargeting()` gates on. Pushed each frame by the
-    /// app's targeting feed (`benilla::ui_action`), before the input pass runs the ESC chain.
+    /// Whether the spell-targeting cursor is up, for `SpellIsTargeting()` and
+    /// `SpellStopTargeting()`; pushed each frame before the input pass runs the ESC chain.
     pub fn set_spell_targeting(&mut self, targeting: bool) {
         self.model_mut().spell_targeting = targeting;
     }
 
-    /// Drain the `SpellStopTargeting()` trigger: `true` if it fired while targeting since the
-    /// last call — the ESC-chain rung (`UIParent.lua:1490`); the app clears its targeting mode.
+    /// Drain the `SpellStopTargeting()` trigger, the ESC chain's rung (`UIParent.lua:1490`); the
+    /// app clears its targeting mode.
     pub fn take_stop_targeting(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().spell_stop_targeting)
     }
 }
 
-/// Which book a `bookType` argument names — the reference's own one-line test, and it is a
-/// **case-insensitive compare against `"pet"` alone** (`0x4b3f27` → `SStrCmpI(arg2, "pet")`), so
-/// every other string, `"spell"` included, is the player's book. Reproduced rather than tightened:
-/// the shared parser also *requires* a string second argument (`0x4b3ee8 lua_isstring(2)`), which
-/// is why these bindings take `String` and not `Option<String>`.
+/// Whether `bookType` names the pet book: a case-insensitive compare with `"pet"` alone
+/// (`0x4b3f27`), so any other string, `"spell"` included, is the player's book.
 fn is_pet_book(book_type: &str) -> bool {
     book_type.eq_ignore_ascii_case(BOOKTYPE_PET)
 }
 
-/// The shared argument marshaller of the reference's spell-slot bindings (`0x4b3ec0`, wow-re
-/// `getspellname-return-contract.md` §6 — `GetSpellName`, `GetSpellTexture`, `IsCurrentCast`,
-/// `GetSpellCooldown`, `IsSpellPassive`, `CastSpell`, `PickupSpell` and the two autocast verbs all
-/// call it): arg 1 must be a number and arg 2 a number or string — the book type is **not**
-/// optional; the index is `trunc(arg1 - 1)` and must land in `[0, 0x400)`, else the binding
-/// raises `Invalid spell slot in <Verb>` and abandons the caller's statement. `"pet"`
-/// (case-insensitively) selects the pet list; any other book type, `"spell"` included, reads the
-/// player's. Answers the 1-based id the rest of this module indexes by ([`slot_index`]), and the
-/// book type normalised to the two names the model knows.
+/// The reference's shared spell-slot marshaller (`0x4b3ec0`): arg 1 a number, arg 2 a number or
+/// string (`0x4b3ee8`), and the index `trunc(arg1 - 1)` in `[0, 0x400)`, else the binding raises
+/// `Invalid spell slot in <Verb>`. Answers the 1-based id and the normalised book type.
 fn spell_slot_args(id: Value, book_type: Value, verb: &str) -> mlua::Result<(u32, String)> {
     let invalid = || mlua::Error::runtime(format!("Invalid spell slot in {verb}"));
     // `lua_isnumber` + `lua_tonumber` (`0x6f34d0`/`0x6f3620`): a numeric string is a number.
@@ -269,18 +182,14 @@ fn spell_slot_args(id: Value, book_type: Value, verb: &str) -> mlua::Result<(u32
     Ok((index as u32 + 1, book.to_string()))
 }
 
-/// The book-id → 0-based slot-list index seam (module docs).
+/// The 1-based book id as a 0-based slot index.
 fn slot_index(id: u32) -> Option<usize> {
     usize::try_from(id.checked_sub(1)?).ok()
 }
 
-/// The one lookup every `bookType`-taking binding shares: pick the book, then the slot. This is
-/// literally the reference's shape — `isPet ? [0xb6f098 + 4*i] : [0xb700f0 + 4*i]`, one fork
-/// repeated verbatim inside each binding (`0x4b3f5d`, `0x4b40e6`, `0x4b3735`, `0x4b3339`, …).
-///
-/// Shared with the tooltip channel (`super::tooltip_spell`'s `SetSpell`), which is a `GameTooltip`
-/// method rather than a global but repeats the identical fork at `0x532e1c`/`0x532e2a` — and which
-/// read the player's book for a pet hover until 1050, because it took the argument and dropped it.
+/// The slot a `bookType` binding reads. The reference forks `isPet ? [0xb6f098 + 4*i] :
+/// [0xb700f0 + 4*i]` in each binding (`0x4b3f5d`, `0x4b40e6`, `0x4b3735`, `0x4b3339`) and in
+/// `GameTooltip:SetSpell` (`0x532e1c`/`0x532e2a`), which shares this.
 pub(super) fn book_slot<'a>(
     model: &'a Model,
     id: u32,
@@ -294,28 +203,17 @@ pub(super) fn book_slot<'a>(
     slots.get(slot_index(id)?)
 }
 
-/// Resolve a spell **by name** against the player's book — the law behind `CastSpellByName` and,
-/// through it, `/cast` and every macro's `/cast` line (decision 0983).
+/// Resolve a spell by name against the player's book, for `CastSpellByName` and so `/cast`, whose
+/// grammar the client's help text gives as `/cast <name> (<subtext>)` (`MACRO_HELP_TEXT_LINE4`):
 ///
-/// The grammar is the one the client documents in its own help text:
-/// `MACRO_HELP_TEXT_LINE4 = "- To cast a spell from a macro use the following syntax:
-/// /cast <name> (<subtext>)"`. So:
+/// - `Fireball`: the highest known rank, by the subtext's leading number (unranked is 0, and a tie
+///   goes to the later slot, the order the book lists ranks in);
+/// - `Fireball(Rank 1)` or `Fireball (Rank 1)`: that subtext, case-insensitively.
 ///
-/// - **`Fireball`** — the highest-ranked *known* Fireball. Rank order is the book's own
-///   `NameSubtext` number (`"Rank 8"` → 8) through the reference's own leading-number parse
-///   ([`super::super::…`]'s twin lives in `benilla::ui_spellbook`); an unranked subtext sorts as 0,
-///   and ties fall to the later book slot, which is the order the book itself lists ranks in.
-/// - **`Fireball(Rank 1)`** / **`Fireball (Rank 1)`** — that exact subtext, case-insensitively.
-///   Both spacings, because vanilla macros in the wild are written both ways and the reference's
-///   own help text prints the spaced form while its FrameXML never re-spaces the argument.
-///
-/// Name matching is case-insensitive and whole-name — a *prefix* rule would silently cast
-/// "Frostbolt" for "Frost" and there is nothing in the reference suggesting one. A spell the
-/// player does not know resolves to `None` and the cast simply does not happen: the reference has
-/// no error line for it either (`SlashCmdList["CAST"]` discards the binding's result).
-///
-/// Passives are skipped, matching [`pickup_spell`]'s sibling rule in `CastSpell`: a passive is
-/// permanent player state, never something a macro casts.
+/// Names match whole and case-insensitively; passives never match. An unknown spell casts nothing
+/// and prints no error, as in the reference (`SlashCmdList["CAST"]` discards the result). The
+/// reference cuts the name at `(` untrimmed (`0x4b3950`), so its spaced form keeps a trailing space
+/// and misses, and it matches name and rank alone, across the pet's book too (`0x4b3a10`).
 pub fn resolve_spell_by_name<'a>(
     book: &'a SpellBookState,
     query: &str,
@@ -334,15 +232,13 @@ pub fn resolve_spell_by_name<'a>(
                 .is_some_and(|r| r.eq_ignore_ascii_case(want)),
             None => true,
         })
-        // Highest rank wins when no subtext pinned one; the book's own later slot breaks a tie.
         .enumerate()
         .max_by_key(|(i, s)| (rank_number(s.rank.as_deref()), *i))
         .map(|(_, s)| s)
 }
 
-/// `Name(Subtext)` / `Name (Subtext)` → `("Name", Some("Subtext"))`; a bare name → `(name, None)`.
-/// An unclosed parenthesis is not a subtext — the whole string stays the name, so a spell whose
-/// own name holds a `(` cannot be silently truncated.
+/// `Name(Subtext)` or `Name (Subtext)` to `("Name", Some("Subtext"))`; without a closing
+/// parenthesis after the opening one, the whole string is the name.
 fn split_subtext(query: &str) -> (&str, Option<&str>) {
     let q = query.trim();
     let Some(open) = q.find('(') else {
@@ -357,9 +253,8 @@ fn split_subtext(query: &str) -> (&str, Option<&str>) {
     (q[..open].trim(), Some(q[open + 1..close].trim()))
 }
 
-/// The rank number inside a `NameSubtext` (`"Rank 8"` → 8), by the reference's own leading-number
-/// parse: skip to the first digit, fold the digit run. A subtext with no digits (`"Racial"`,
-/// `"Passive"`) and an absent one both read 0.
+/// The rank in a `NameSubtext` (`"Rank 8"` is 8) by the reference's parse, the first digit run;
+/// a subtext without digits, or none, reads 0.
 fn rank_number(subtext: Option<&str>) -> u32 {
     subtext
         .unwrap_or("")
@@ -369,13 +264,9 @@ fn rank_number(subtext: Option<&str>) -> u32 {
         .fold(0u32, |acc, c| acc * 10 + c.to_digit(10).unwrap_or(0))
 }
 
-/// `PickupSpell(id, bookType)` — the drag/shift-click entry point (ref `SpellButton_OnClick`'s
-/// other two forks, `SpellBookFrame.lua:263-290`). The book is a SOURCE, never a placement
-/// target — the ref's plain click always casts unconditionally, never checking `GetCursorInfo`
-/// first (unlike `UseAction`'s `checkCursor` fork) — so this refuses outright when the cursor
-/// already holds ANYTHING rather than silently discarding it: the doll's own refusal precedent
-/// (`cursor::doll::pickup_inventory_item`) for a payload with nowhere faithful to go, since a
-/// spell button is not a fit-checked drop target the way a doll slot or bar button is.
+/// `PickupSpell(id, bookType)`, the spell button's drag and shift-click
+/// (`SpellBookFrame.lua:266-290`). It refuses while the cursor holds anything, where the
+/// reference's setters clear the cursor first (`0x495190`, called at `0x494dab` and `0x494f00`).
 fn pickup_spell(model: &mut Model, id: u32, book_type: &str) -> bool {
     if model.cursor.is_some() {
         return false;
@@ -383,22 +274,16 @@ fn pickup_spell(model: &mut Model, id: u32, book_type: &str) -> bool {
     let Some(slot) = book_slot(model, id, book_type) else {
         return false;
     };
-    // **The pet book's payload is a different KIND**, not a Spell payload with a flag on it: the
-    // pet arm of `0x4b3260` calls `0x494e20` with a pointer to the pet's raw word (cursor modes
-    // 1-7), while the player arm calls `0x494d20` with a spell id (mode 9). That is why a pet
-    // spell can be dropped onto the pet bar and a player spell cannot — the bar's drop accepts
-    // exactly one payload kind, and the book is the *second* place that kind is produced.
+    // The pet arm of `0x4b3260` puts the pet's raw word on the cursor (`0x494e20`, cursor mode 4),
+    // the player arm a spell id (`0x494d20`, mode 3); only the pet word drops on the pet bar.
     let payload = if is_pet_book(book_type) {
-        // `0x494e20`'s own jump table refuses type 0 and type >= 8, so a word that could not sit
-        // on the bar cannot ride the cursor either (`cursor::pet::payload_word`, same rule).
+        // `0x494e20` refuses type 0 and types 8 and up.
         let packed = slot.packed;
         if !(1..=7).contains(&((packed >> 24) & 0x3F)) {
             return false;
         }
         CursorPayload::PetAction(super::cursor::CursorPetAction {
-            // No source slot: this word came out of the BOOK, not off the bar, so there is
-            // nothing to blank behind it and nothing to swap back to. The reference is the same
-            // shape — its cursor holds a pointer into the raw spell array, not into the bar.
+            // No source slot: the word comes from the book, not the bar.
             src_slot: 0,
             packed,
             passive: slot.passive,
@@ -425,32 +310,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     g.set("BOOKTYPE_SPELL", BOOKTYPE_SPELL)?;
     g.set("BOOKTYPE_PET", BOOKTYPE_PET)?;
 
-    // `UpdateSpells()` — twelve bytes in the reference (`[0x4b43e0,0x4b43ec)`), and its entire
-    // content is a bare `SignalEvent(SPELLS_CHANGED)`: event 260, **no arguments**, and NO state
-    // mutation whatsoever. Byte-carved by a wow-re cross-check (decision 1924, their
-    // `system/ui/scratch/updatespells-verb.md`). Entered with both sort flags zero the worker
-    // performs exactly one memory write — a `push esi` undone nine instructions later — and
-    // `0x4b302f` is the sole fire site for event 260 image-wide.
-    //
-    // **`argc = 0` is PROVEN, not observed**: the binding overwrites `ecx` at its second
-    // instruction, so an extra argument is structurally unobservable. Zero return values.
-    //
-    // **It is NOT a no-op, and it is not a repaint.** Two readings were tried and both are wrong.
-    // A no-op breaks the five stock call sites (`ToggleSpellBook`, `SpellBookFrame_Update`'s
-    // showing leg, both page-turn OnClicks, `SpellBookSkillLineTab_OnClick`). And our old
-    // `BenillaUpdateSpells` stand-in — a loop repainting `SpellButton1..N` — was wrong in BOTH
-    // directions: narrower (it missed the skill-line tab strip, the pet/spell tab buttons,
-    // `SpellBook_UpdatePageArrows` and every other registrant) and wider (the reference gates the
-    // frame update on `IsVisible()`). The repaint is FrameXML's, reached through the event; there
-    // is no native listener mechanism at all.
-    //
-    // Fired SYNCHRONOUSLY, through [`super::tick::fire_event_into`] — the reference's
-    // `SignalEvent` is synchronous, so queueing it for the next tick would be a real divergence.
-    //
-    // Firing `SPELLS_CHANGED` from the other six reference sites (spell learned/removed/
-    // superseded, `SMSG_PET_SPELLS`, the bring-up rebuild, two UpdateFields reflexes) is a
-    // SEPARATE obligation and is where the spell-list re-sort lives; `UpdateSpells` is the one
-    // caller of the seven that never performed that recompute.
+    // `UpdateSpells()` (`[0x4b43e0,0x4b43ec)`) only signals `SPELLS_CHANGED` (event 260, whose one
+    // fire site is `0x4b302f`): no arguments read, no returns, no state change, and no re-sort,
+    // which the other `SPELLS_CHANGED` sites do. The repaint is FrameXML's, through the event.
+    // `SignalEvent` is synchronous, so this fires now, not on the next tick.
     g.set(
         "UpdateSpells",
         lua.create_function(|lua, ()| {
@@ -459,10 +322,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `PlayerHasSpells()` — a hard-coded `1` in the reference: `push 0x3ff00000; push 0;
-    // lua_pushnumber; mov eax,1; ret`. No branch, no store read, so it cannot answer anything else
-    // (1924, found by the same dispatch). `MainMenuBarMicroButtons.lua` gates the spellbook micro
-    // button on it, which is the only reason it exists here.
+    // `PlayerHasSpells()` is a constant 1 in the reference (it pushes 1.0 with no branch);
+    // `MainMenuBarMicroButtons.xml:80` picks the spellbook micro button's tooltip by it.
     g.set("PlayerHasSpells", lua.create_function(|_, ()| Ok(1_i64))?)?;
 
     g.set(
@@ -473,42 +334,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSpellTabInfo(i) -> name, texture, offset, numSpells. **FOUR values on every path that
-    // returns** — `0x4b3ce0` has two live `ret`s and both `mov eax,4`; the `eax=0` one at `0x4b3d0d`
-    // is dead code after `luaL_error` longjmps. Byte-carved by a wow-re cross-check (decision 1931,
-    // `system/ui/scratch/spelltabinfo-return-contract.md`).
-    //
-    // **OUT OF RANGE IS `nil, nil, 0, 0` — LITERAL zeros, not a single nil.** This comment used to say
-    // "out of range -> a single nil (GetMerchantItemInfo's own out-of-range shape)", i.e. one
-    // binding's shape copied onto another on the assumption that they generalise. They do not
-    // (1919 proved it for GetSkillLineInfo; this is the same bug one verb over). Leg `0x4b3e12`
-    // pushes nil, nil, then `push 0; push 0; lua_pushnumber` twice — `0x6f3810` copies its two
-    // stack dwords VERBATIM, so that is exactly +0.0, not a stale offset and nothing off the array
-    // base. Index 0, a negative, past-the-count and the empty/no-player registry all reach it via
-    // ONE unsigned branch (`0x4b3d26 dec ebx / cmp ebx,eax / jae`).
-    //
-    // Why the zeros are load-bearing rather than cosmetic: `SpellBookFrame_OnLoad` runs
-    // `SpellBookSkillLineTab_OnClick(1)` -> `GetSpellTabInfo(1)` UNCONDITIONALLY at load, and
-    // `SpellBookFrame_Update` can pass `SpellBookFrame:GetID()`, which is 0. The stock file then
-    // does `id > (offset + numSpells)` unguarded (l.295) — a nil there raises, and `(0+0)` makes it
-    // true, so the reference HIDES EVERY BUTTON ON THE PAGE. That is the behaviour to match.
-    //
-    // **The argument RAISES when absent or not number-coercible** — `luaL_error(L, "Usage:
-    // GetSpellTabInfo(index)")`, a numeric string accepted. [`number_arg`] is that exact shape
-    // (coerce, truncate toward zero, raise the usage string), and the decrement happens AFTER it.
-    // Do NOT share `GetSpellName`'s marshaller: `0x4b3ec0` does `fsub 1.0` BEFORE truncating, and
-    // the two disagree below 1 (`0.5` is out-of-range here and index 0 there).
-    //
-    // Slot 1 is also nil on an IN-RANGE tab whose skillLineId has no DBC row (`0x4b3dbd`), and
-    // `(string?, nil, num, num)` is live in shipped data (SkillLine.dbc 733/753/754 have
-    // spellIconID 0) — both already the shape the in-range arm below produces.
+    // GetSpellTabInfo(i) -> name, texture, offset, numSpells, four values on every path
+    // (`0x4b3ce0`). Out of range, 0 and negatives included (`0x4b3d26`), is `nil, nil, 0, 0`
+    // (`0x4b3e12`): `SpellBookFrame.lua:295` and `:328` compare `id > (offset + numSpells)`
+    // unguarded, so the zeros hide every button where a nil would raise. In range, the reference
+    // answers a nil name and texture for a skill line with no DBC row (`0x4b3dbd`) and a nil
+    // texture for one with no icon (SkillLine 733, 753, 754); here the name is always a string.
+    // The index is truncated before the decrement, unlike in `0x4b3ec0`, so 0.5 is out of range.
     g.set(
         "GetSpellTabInfo",
         lua.create_function(|lua, i: Value| {
             let i = super::binding_abi::number_arg(lua, i, "Usage: GetSpellTabInfo(index)")?;
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // Truncate (done), THEN decrement, then the unsigned compare: a negative or zero
-            // index lands below 0 and `usize::try_from` refuses it — the `jae` leg.
+            // Zero or a negative fails `usize::try_from`, as the unsigned compare fails it.
             let tab = usize::try_from(i64::from(i) - 1)
                 .ok()
                 .and_then(|n| model.spellbook.tabs.get(n));
@@ -533,43 +371,19 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSpellName(id, bookType) -> name, rank. **Always TWO values, never one, and the rank of a
-    // rankless spell is the EMPTY STRING, never nil** (wow-re
-    // `scratch/getspellname-return-contract.md`, §5-derived from the bytes alone).
-    //
-    // Both returns go through the same push helper with **no rank-specific branch anywhere in the
-    // binding** — a ranked and a rankless spell run byte-identical code: `0x4b4063 call 0x6f3890`
-    // pushes `SpellRec.Name[locale]`, `0x4b4076` pushes `NameSubtext[locale]`, and the single
-    // DBC-resolved exit is `mov eax,0x2` at `0x4b407c`. `0x6f3890` decides on **pointer nullity
-    // alone** (`test edx,edx`), and the DBC pointer is never NULL: `SpellRec::Read 0x583750` fixes
-    // up every string column with an unconditional `add offset, stringBlockBase`, so an on-disk
-    // offset of 0 materializes as a pointer to the string block's own byte 0 — a NUL. `0x6f3840`
-    // then writes tag 4 (`LUA_TSTRING`) unconditionally; `len == 0` is not a special case. So the
-    // rankless rank is a real, interned, zero-length Lua string.
-    //
-    // This is not an edge case: **14,403 of the shipped Spell.dbc's 22,357 rows carry NameSubtext
-    // offset 0** — 64%, `Attack` (6603) among them. Our `Option<String>::None` pushed nil there,
-    // and two 1.12 corpus addons walking the whole book die on it in two different idioms:
-    // `Roid-Macros/Generic.lua:35` uses the rank as a TABLE KEY (nil is illegal), and
-    // `CT_MasterMod/CT_Master.lua:16` passes it straight to `string.find` (nil raises). Both were
-    // invisible until the survey seated a spellbook.
-    //
-    // The `Option` is still the right shape for the MODEL — it records "this spell has no
-    // NameSubtext", which is a fact about the DBC row. What was wrong was rendering that absence
-    // as nil at the Lua boundary; the reference renders it as the empty string the pointer targets.
+    // GetSpellName(id, bookType) -> name, rank, always two values; a rankless spell's rank is "",
+    // never nil: `0x4b4076` pushes `NameSubtext` through `0x6f3890`, which tests only pointer
+    // nullity, and `SpellRec::Read` (`0x583750`) makes every string offset a pointer. 14,403 of
+    // the 22,357 `Spell.dbc` rows have an empty one, `Attack` (spell 6603) among them.
     g.set(
         "GetSpellName",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
             let (id, book_type) = spell_slot_args(id, book_type, "GetSpellName")?;
-            // An out-of-range index RAISES rather than answering nil (`spell_slot_args`); the
-            // in-binding bound check at `0x4b4018` is unreachable-as-taken. This file previously
-            // assumed the bound was "enforced by our slot lists being shorter than that anyway" —
-            // a short list answers nil, which is a different thing entirely.
+            // Out of `[0, 0x400)` already raised in `spell_slot_args`; the binding's own bound
+            // check (`0x4b4018`) is never taken.
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let Some(slot) = book_slot(&model, id, &book_type) else {
-                // An unfilled slot inside the range answers **two** nils (`0x4b4086` → `mov eax,0x2`
-                // at `0x4b4095`), not one — which a return-list count and a two-name assignment can
-                // both tell apart.
+                // An empty slot inside the range answers two nils (`0x4b4086`).
                 return Ok(MultiValue::from_vec(vec![Value::Nil, Value::Nil]));
             };
             Ok(MultiValue::from_vec(vec![
@@ -592,17 +406,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsCurrentCast(id, bookType) — the spellbook button's checked ring (binding `0x4b4370` →
-    // delegate `0x4b3600`; ref
-    // `SpellButton_UpdateSelection` SetChecks on it). The verdict itself is app-resolved per slot
-    // ([`SpellSlotView::current`]); this only reads it back.
+    // IsCurrentCast(id, bookType) (`0x4b4370`) reads back the app's per-slot verdict,
+    // `SpellSlotView::current`.
     g.set(
         "IsCurrentCast",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
             let (id, book_type) = spell_slot_args(id, book_type, "IsCurrentCast")?;
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let current = book_slot(&model, id, &book_type).is_some_and(|s| s.current);
-            // The ref's binding convention: 1 or nil, never false.
+            // 1 or nil, never false, as the reference's bindings answer.
             match current {
                 true => Ok(Value::Integer(1)),
                 false => Ok(Value::Nil),
@@ -610,11 +422,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSpellCooldown(id, bookType) → start, duration, enable — the book twin of
-    // `GetActionCooldown`/`GetContainerItemCooldown`, identical conventions: `GetTime`-clock
-    // `(seconds, seconds, 0/1)`, enable 0 = an on-hold record (parked, full duration), and the
-    // cold-at-expiry guard so an event-driven re-feed can never replay the finish flash. Pet or
-    // out-of-range answers the cold `(0, 0, 1)` — the ref's own no-cooldown shape.
+    // GetSpellCooldown(id, bookType) -> start, duration, enable in `GetTime` seconds, as
+    // `GetActionCooldown`: enable 0 for an on-hold cooldown; an expired or empty one answers the
+    // reference's no-cooldown `(0, 0, 1)`, so a re-feed cannot replay the finish flash.
     g.set(
         "GetSpellCooldown",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
@@ -648,17 +458,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CastSpell(id, bookType) — the plain click (ref SpellButton_OnClick's `else` branch): queues
-    // the resolved spell id UNLESS the slot is passive (module doc: a passive is permanent player
-    // state, never something the player casts) or bookType/id resolve to nothing.
-    //
-    // **The pet arm is a different verb, not a flag.** `0x4b3300`'s tail forks on the book byte
-    // one instruction before the send (`0x4b34c8 cmp ecx, 0; je` → the player's own cast
-    // `0x6e5a90`), and the pet side builds `CMSG_PET_ACTION 0x175` by hand:
-    // `{ u64 [0xb714a0], u32 (spellId & 0xFFFF) | 0x01000000, u64 target }` (`0x4b34ce`-`0x4b3524`)
-    // — a **synthesized type-1 word**, which is why the pet book can cast a spell that is not on
-    // the bar at all. The target is the passed one, falling back to the current selection
-    // (`0x4b34af`-`0x4b34bb`), exactly as `CastPetAction` does; the app supplies it at the drain.
+    // CastSpell(id, bookType), the plain click, queues the slot's spell unless it is passive. On
+    // the pet book `0x4b3300` forks at `0x4b34c8` (the player's cast is `0x6e5a90`) to send
+    // `CMSG_PET_ACTION` (0x175), `{ u64 [0xb714a0], u32 (spellId & 0xFFFF) | 0x01000000, u64
+    // target }` (`0x4b34ce`), so the pet book casts a spell not on the bar; the target falls back
+    // to the selection (`0x4b34af`), as in `CastPetAction`. The app sends both at the drain.
     g.set(
         "CastSpell",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
@@ -678,12 +482,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // HasPetSpells() → numPetSpells, petToken — no arguments, and **always exactly two returns**
-    // (`0x4b4410`, `EAX = 2` on every path). Zero spells answers `(nil, nil)` (`0x4b4420`), which
-    // is the gate `ToggleSpellBook` and `SpellBookFrame_Update` both read: no pet book, no tab row.
-    //
-    // Return 1 is the **count as a number**, not a boolean — `SpellBook_GetCurrentPage` divides by
-    // it (`ceil(numPetSpells/12)`), so answering 1/nil would silently pin the pet book to one page.
+    // HasPetSpells() -> numPetSpells, petToken: always two returns (`0x4b4410`), `(nil, nil)` with
+    // no pet spells (`0x4b4420`). The count is a number: `SpellBook_GetCurrentPage` divides by it.
     g.set(
         "HasPetSpells",
         lua.create_function(|lua, ()| {
@@ -694,20 +494,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             }
             let token = match &model.pet_book.token {
                 Some(t) => Value::String(lua.create_string(t)?),
-                // The reference's own unresolved-player arm pushes the literal "PET"
-                // (`0x4b44a6`), never nil — a nil here would make `"PET_TYPE_"..token` error.
                 None => Value::String(lua.create_string(PET_TOKEN_FALLBACK)?),
             };
             Ok(MultiValue::from_vec(vec![Value::Integer(n as i64), token]))
         })?,
     )?;
 
-    // GetSpellAutocast(id, bookType) → autoCastAllowed, autoCastEnabled (1/nil each) — the
-    // AutoCastable overlay and the sparkle model on a pet book button.
-    //
-    // **Pet-only, and it fails to (nil, nil) rather than (nil) for the player book**: `0x4b4180`
-    // tests the book flag twice (`0x4b41cb`, `0x4b41d6`) and falls into the same two nil pushes the
-    // no-record path uses, so the arity is 2 on every path including a bad index.
+    // GetSpellAutocast(id, bookType) -> autoCastAllowed, autoCastEnabled, 1 or nil each: always
+    // two returns, `(nil, nil)` for the player book (`0x4b4180` tests the book at `0x4b41cb` and
+    // `0x4b41d6`) and for an empty slot.
     g.set(
         "GetSpellAutocast",
         lua.create_function(move |lua, (id, book_type): (Value, Value)| {
@@ -721,16 +516,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ToggleSpellAutocast(id, bookType) — the pet book's right click (ref `SpellButton_OnClick`'s
-    // `arg1 ~= "LeftButton"` fork). **A different binding and a different opcode from the pet
-    // BAR's `TogglePetAutocast`**: `0x4b4240` indexes the pet spellbook and calls `0x4bccb0`, which
-    // sends `CMSG_PET_SPELL_AUTOCAST 0x2F3` naming a **spell id**, where the bar's verb sends
-    // `CMSG_PET_SET_ACTION` naming a slot. Confusing them is a wire bug that looks like a UI one.
-    //
-    // The gate here is the same one `0x4bccb0` applies before it sends: the word must be
-    // autocast-ALLOWED (`0x4bccf5 test cl,1`). Everything else the sender does — flipping bit 30
-    // in place and mirroring it onto every bar slot carrying the same action — is state the app
-    // owns, so it happens at the drain.
+    // ToggleSpellAutocast(id, bookType), the pet book's right click (`0x4b4240`): queued only for
+    // an autocast-allowed word, the gate `0x4bccb0` applies before sending (`0x4bccf5`). The app
+    // sends `CMSG_PET_SPELL_AUTOCAST` and flips bit 30 on the book and the bar at the drain.
     g.set(
         "ToggleSpellAutocast",
         lua.create_function(|lua, (id, book_type): (Value, Value)| {
@@ -747,14 +535,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CastSpellByName(name [, onSelf]) — the reference binding `0x4b4ab0`, whose only two callers
-    // share the `0x4b3300` dispatcher with `CastSpell` above (wow-re ledger), so this queues onto
-    // the same `spell_casts` list and the app's one cast tail handles both. `SlashCmdList["CAST"]`
-    // is literally `CastSpellByName(msg)`, which is why `/cast` needs nothing else, and it is the
-    // command the whole macro system is built to run.
-    //
-    // `onSelf` is accepted and carried no further (benilla has no self-cast modifier yet — the
-    // same named gap `UseAction`'s third argument already has).
+    // CastSpellByName(name [, onSelf]) (`0x4b4ab0`) shares the dispatcher `0x4b3300` with
+    // `CastSpell`, so it queues on the same list; `SlashCmdList["CAST"]` calls it. `onSelf` is
+    // accepted and ignored: self-cast is not built.
     g.set(
         "CastSpellByName",
         lua.create_function(|lua, (name, _on_self): (String, MultiValue)| {
@@ -776,18 +559,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellStopCasting() — the ref's Script::SpellStopCasting (`0x6e6e80`, §5-verified whole,
-    // wow-re `esc-stopcasting.md`): stop the FIRST of {running auto-repeat (`0x6ea080`,
-    // CMSG_CANCEL_AUTO_REPEAT_SPELL), in-flight cast (`AbortCast` → CMSG_CANCEL_CAST)} and
-    // return 1; nil when neither runs. A CHANNEL is nil — the body's whole callee closure
-    // never reaches the channel canceler `0x6e9b70`, and the inflight id `0xceca88` it gates
-    // on is already 0 mid-channel (the launch CAST_RESULT(OKAY) clears it at `0x6e7408`) —
-    // the vanilla "/stopcasting can't stop a channel" quirk, kept faithfully. The falsy leg is
-    // load-bearing ground truth from the artifact: `ToggleGameMenu`'s ESC chain (extracted
-    // `UIParent.lua:1489`, `elseif ( SpellStopCasting() ) then`) only reaches
-    // `CloseAllWindows()`/the game menu through nil, so an unconditional true would eat every
-    // ESC press forever. The host feeds the stoppable mirror (`set_casting`) and resolves the
-    // branch order at the drain (`benilla::ui_cast::local_self_cancel`).
+    // SpellStopCasting() (`0x6e6e80`) stops the first of a running auto-repeat (`0x6ea080`,
+    // `CMSG_CANCEL_AUTO_REPEAT_SPELL`) or an in-flight cast (`CMSG_CANCEL_CAST`) and answers 1,
+    // else nil. A channel answers nil: the channel canceler `0x6e9b70` is never reached, and the
+    // in-flight id `0xceca88` is 0 mid-channel (cleared at `0x6e7408`). The nil matters: the ESC
+    // chain (`UIParent.lua:1489`) reaches the game menu only through it.
     g.set(
         "SpellStopCasting",
         lua.create_function(|lua, ()| {
@@ -801,9 +577,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellIsTargeting() — the ref's Script::SpellIsTargeting (`0x6e6cd0`, wow-re
-    // `wave-cast.md`): true while the targeting cursor is up (`flag_word != 0`), nil otherwise.
-    // Read by FrameXML (PetFrame's right-click bind fork) and by the ESC chain's callers.
+    // SpellIsTargeting() (`0x6e6cd0`): true while the targeting cursor is up, else nil.
     g.set(
         "SpellIsTargeting",
         lua.create_function(|lua, ()| {
@@ -816,16 +590,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellCanTargetUnit("unit") — the ref's `0x6e6d00`: resolve the token, then ask `0x6e6460`'s
-    // UNIT leg whether the standing word can bind it. Its one shipped caller is
-    // `UnitFrame_OnEnter`, and it is what picks CAST_CURSOR over CAST_ERROR_CURSOR — the only
-    // lit/grey cursor split over a UI element in 1.12.
-    //
-    // The token is not consulted yet, and that is honest rather than lazy: the answer is `false`
-    // for **every** unit while any word benilla can arm is standing (location / item / gameobject —
-    // no unit satisfies those), so no token can change it. The app derives the flag from the word
-    // itself, so this starts discriminating by unit the moment the residual unit-word machine
-    // lands rather than silently staying wrong.
+    // SpellCanTargetUnit("unit") (`0x6e6d00`) asks `0x6e6460`'s unit leg whether the targeting
+    // word can take the unit. The token is not read: no word benilla can arm (location, item,
+    // gameobject) takes a unit, and unit words are not built.
     g.set(
         "SpellCanTargetUnit",
         lua.create_function(|lua, _unit: Option<String>| {
@@ -838,12 +605,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellStopTargeting() — the ref's Script::SpellStopTargeting (`0x6e6e30`: if IsTargeting →
-    // StopTargeting `0x6e4900` → AbortCast(0x1c), which in targeting mode just clears the word,
-    // no packet). The 1/nil return is load-bearing exactly like SpellStopCasting's above: the
-    // ESC chain's rung (`UIParent.lua:1490`, `elseif ( SpellStopTargeting() ) then`) must fall
-    // through to the game menu when nothing was targeting. The host drains the trigger
-    // (`benilla::ui_action::targeting`) and clears its mode.
+    // SpellStopTargeting() (`0x6e6e30`): while targeting, `0x6e4900` clears the word with no
+    // packet and the binding answers 1, else nil, so the ESC chain (`UIParent.lua:1490`) falls
+    // through to the game menu.
     g.set(
         "SpellStopTargeting",
         lua.create_function(|lua, ()| {
@@ -866,8 +630,7 @@ mod tests {
     use crate::script::cursor::{CursorAction, CursorPayload};
     use crate::script::UiScript;
 
-    /// Two tabs: "Fire" (2 spells: Fireball rank1 active, Fire Blast PASSIVE — an artificial
-    /// fixture just to exercise the gray/refuse gate) and "Frost" (1 spell).
+    /// Two tabs: Fire (Fireball, and Fire Blast marked passive) and Frost (Frost Armor).
     fn book() -> SpellBookState {
         SpellBookState {
             tabs: vec![
@@ -900,7 +663,7 @@ mod tests {
                     name: "Fire Blast".into(),
                     rank: Some("Rank 1".into()),
                     texture: Some("Interface\\Icons\\Spell_Fire_FireBolt02".into()),
-                    passive: true, // artificial: exercises the refusal gate
+                    passive: true, // not really passive: exercises the refusal
                     current: false,
                     cooldown: None,
                     ..Default::default()
@@ -919,7 +682,6 @@ mod tests {
         }
     }
 
-    /// `IsCurrentCast` reads the app-resolved per-slot verdict back as the ref's 1-or-nil.
     #[test]
     fn is_current_cast_reads_the_slot_verdict() {
         let mut s = UiScript::new().unwrap();
@@ -945,17 +707,13 @@ mod tests {
             .unwrap());
     }
 
-    /// `GetSpellCooldown` reads the app-pushed per-slot triple back as the ref's GetTime-clock
-    /// `(start, duration, enable)` — cold `(0, 0, 1)` for absent/pet/out-of-range, enable 0 for
-    /// an on-hold record regardless of expiry, and the cold-at-expiry guard once
-    /// `start + duration` passes (`GetActionCooldown`'s own conventions, the book twin).
     #[test]
     fn get_spell_cooldown_reads_the_slot_triple() {
         let mut s = UiScript::new().unwrap();
         s.set_spellbook(book());
         s.tick(20.0); // GetTime = 20
 
-        // Cold slot: the ref's no-cooldown shape.
+        // Cold slot: the reference's no-cooldown shape.
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(1, BOOKTYPE_SPELL)")
                 .unwrap(),
@@ -965,26 +723,26 @@ mod tests {
         let mut b = book();
         b.slots[0].cooldown = Some((14_000, 10_000, true)); // running: 4 s elapsed of 10
         b.slots[1].cooldown = Some((2_000, 8_000, false)); // on hold: parked since t=2
-        b.slots[2].cooldown = Some((5_000, 10_000, true)); // elapsed at t=15 — cold
+        b.slots[2].cooldown = Some((5_000, 10_000, true)); // elapsed at t=15: cold
         s.set_spellbook(b);
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(1, BOOKTYPE_SPELL)")
                 .unwrap(),
             (14.0, 10.0, 1)
         );
-        // On hold survives the expiry guard (enable 0 = the parked "hasn't begun").
+        // On hold survives the expiry guard.
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(2, BOOKTYPE_SPELL)")
                 .unwrap(),
             (2.0, 8.0, 0)
         );
-        // Elapsed goes cold — an event-driven re-feed can never replay the finish flash.
+        // Elapsed goes cold.
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(3, BOOKTYPE_SPELL)")
                 .unwrap(),
             (0.0, 0.0, 1)
         );
-        // The pet deferral and out-of-range answer cold too.
+        // No pet book, and past the book, answer cold too.
         assert_eq!(
             s.eval::<(f64, f64, i64)>("return GetSpellCooldown(1, BOOKTYPE_PET)")
                 .unwrap(),
@@ -1001,8 +759,7 @@ mod tests {
     fn tab_info_shapes_and_book_id_offsets() {
         let mut s = UiScript::new().unwrap();
         assert_eq!(s.eval::<i64>("return GetNumSpellTabs()").unwrap(), 0);
-        // `== nil` reads true either way — Lua compares only the first value. The ARITY is the
-        // load-bearing half and lives in `out_of_range_answers_four_values` below (1931).
+        // Lua compares only the first value; `out_of_range_answers_four_values` checks the arity.
         assert!(s
             .eval::<bool>("return (GetSpellTabInfo(1)) == nil")
             .unwrap());
@@ -1022,13 +779,11 @@ mod tests {
             .unwrap();
         assert_eq!((name2.as_str(), offset2, num2), ("Frost", 2, 1));
 
-        // Out of range -> nil.
+        // Out of range: nil first.
         assert!(s.eval::<bool>("return GetSpellTabInfo(3) == nil").unwrap());
     }
 
-    /// The shared marshaller's law (`0x4b3ec0`): the index is `trunc(arg - 1)` gated to
-    /// `[0, 0x400)` and a miss RAISES; the book type is mandatory and `"pet"` is matched without
-    /// case; anything else is the player's book.
+    /// The reference's marshaller, `0x4b3ec0`.
     #[test]
     fn the_slot_marshaller_gates_the_index_and_names_the_book() {
         let mut s = UiScript::new().unwrap();
@@ -1051,8 +806,7 @@ mod tests {
                 .contains("Invalid spell slot in GetSpellTexture"),
             "the book type is not optional"
         );
-        // Inside the range but past the book: nil, not an error — the bound is the marshaller's,
-        // the emptiness is the slot's.
+        // Inside the range but past the book: nil, not an error.
         assert!(s
             .eval::<bool>("return GetSpellTexture(1024, BOOKTYPE_SPELL) == nil")
             .unwrap());
@@ -1105,7 +859,7 @@ mod tests {
             .unwrap();
         assert_eq!(name3, "Frost Armor");
 
-        // Out of range and the pet deferral both answer nil.
+        // Past the book, and an absent pet book, answer nil.
         assert!(s
             .eval::<bool>(r#"return GetSpellName(99, BOOKTYPE_SPELL) == nil"#)
             .unwrap());
@@ -1132,9 +886,8 @@ mod tests {
             ("spell", 1, "spell", 133)
         );
 
-        // CURSOR_UPDATE fired (the shared cursor seam, not duplicated here) — a listener sees it.
-        // Tick first to flush the FIRST pickup's already-queued CURSOR_UPDATE before the listener
-        // registers, so the count below is purely about the second (refused) call.
+        // Tick first to flush the first pickup's `CURSOR_UPDATE`, so the count below is the
+        // refused call's alone.
         s.tick(0.0);
         s.run(
             r#"
@@ -1152,8 +905,7 @@ mod tests {
             0,
             "refused pickup fires no CURSOR_UPDATE"
         );
-        // Still holding spell 133 (book slot 1) from the first pickup — a refusal never clobbers
-        // it (GetCursorInfo's Spell arm: kind, book_slot, book_type, spell_id).
+        // Still holding the first pickup: a refusal never clobbers it.
         assert_eq!(
             s.eval::<(String, i64, String, i64)>(
                 "local k, slot, book, id = GetCursorInfo() return k, slot, book, id"
@@ -1204,9 +956,8 @@ mod tests {
             .unwrap());
     }
 
-    /// **With no pet book fed, every pet arm answers nothing** — the old deferral's behaviour,
-    /// which is also the reference's whenever `[0xb71174] == 0`. Kept as its own case so the
-    /// pet-book tests below can never pass by the player book leaking into them.
+    /// With no pet book, as when the reference's count `[0xb71174]` is 0, every pet arm answers
+    /// nothing.
     #[test]
     fn an_absent_pet_book_answers_empty_everywhere() {
         let mut s = UiScript::new().unwrap();
@@ -1235,8 +986,8 @@ mod tests {
         assert!(s.cursor_payload().is_none(), "pet pickup is a no-op");
     }
 
-    /// A hunter's pet book: Growl (autocastable, ON, on cooldown), Claw (autocastable, OFF) and
-    /// Avoidance (a passive — no autocast, `ACT_PASSIVE 0x01`).
+    /// A hunter's pet book: Growl (autocastable, on, cooling down), Claw (autocastable, off) and
+    /// Avoidance (a passive, no autocast, `ACT_PASSIVE` 0x01).
     fn pet_book() -> PetBookState {
         PetBookState {
             token: Some("PET".into()),
@@ -1273,8 +1024,6 @@ mod tests {
         }
     }
 
-    /// `HasPetSpells` is **the count and a token**, always two returns, and the count is a NUMBER
-    /// — `SpellBook_GetCurrentPage` divides by it, so a 1/nil boolean would pin the page count.
     #[test]
     fn has_pet_spells_answers_a_count_and_a_class_token() {
         let mut s = UiScript::new().unwrap();
@@ -1283,8 +1032,7 @@ mod tests {
             .eval::<bool>(r#"local n, t = HasPetSpells() return n == 3 and t == "PET""#)
             .unwrap());
 
-        // A warlock's book carries the other token, which is the whole of what makes the tab read
-        // "Demon" — FrameXML does `getglobal("PET_TYPE_"..token)`.
+        // A warlock's token, which FrameXML reads as `PET_TYPE_DEMON`.
         let mut demon = pet_book();
         demon.token = Some("DEMON".into());
         s.set_pet_book(demon);
@@ -1294,8 +1042,7 @@ mod tests {
             "DEMON"
         );
 
-        // No token resolved (no ChrClasses.dbc) still answers a STRING, never nil — a nil would
-        // make the reference's own concatenation error.
+        // No token resolved (no `ChrClasses.dbc`) still answers a string.
         let mut untokened = pet_book();
         untokened.token = None;
         s.set_pet_book(untokened);
@@ -1306,8 +1053,6 @@ mod tests {
         );
     }
 
-    /// The two books are separate lists reached by the SAME id — the reference's `isPet ? petArray
-    /// : playerArray` fork. Book id 1 means Fireball in one and Growl in the other.
     #[test]
     fn one_id_reads_two_different_books() {
         let mut s = UiScript::new().unwrap();
@@ -1324,8 +1069,7 @@ mod tests {
                 .unwrap(),
             "Growl"
         );
-        // The book type is a case-insensitive compare against "pet" ALONE (`0x4b3f27`), so every
-        // other string is the player's book — including a typo'd one.
+        // `"pet"` alone, without case (`0x4b3f27`); any other string, a typo too, is the player's.
         assert_eq!(
             s.eval::<String>(r#"return GetSpellName(1, "PeT")"#)
                 .unwrap(),
@@ -1336,15 +1080,12 @@ mod tests {
                 .unwrap(),
             "Fireball"
         );
-        // Past the pet book's end: one nil, the out-of-range shape.
+        // Past the pet book's end: nil.
         assert!(s
             .eval::<bool>(r#"return GetSpellName(4, BOOKTYPE_PET) == nil"#)
             .unwrap());
     }
 
-    /// `GetSpellAutocast` is **pet-only and always two returns**: the player book short-circuits
-    /// to `(nil, nil)` before it looks anything up (`0x4b41cb`/`0x4b41d6`), and so does an
-    /// out-of-range pet index.
     #[test]
     fn autocast_is_a_pet_only_pair() {
         let mut s = UiScript::new().unwrap();
@@ -1384,9 +1125,6 @@ mod tests {
         );
     }
 
-    /// `ToggleSpellAutocast` queues only what `0x4bccb0` would actually send: a pet-book slot whose
-    /// word is autocast-ALLOWED. A passive, a player-book id and an out-of-range id all queue
-    /// nothing — and none of them may leak into the player's cast queue.
     #[test]
     fn only_an_autocastable_pet_slot_queues_a_toggle() {
         let mut s = UiScript::new().unwrap();
@@ -1405,8 +1143,6 @@ mod tests {
         assert!(s.take_spell_casts().is_empty());
     }
 
-    /// A pet cast is a **different queue** from a player cast, because it is a different opcode at
-    /// the far end (`CMSG_PET_ACTION`, not a player cast). A passive still refuses on both.
     #[test]
     fn a_pet_cast_queues_apart_from_a_player_cast() {
         let mut s = UiScript::new().unwrap();
@@ -1424,9 +1160,6 @@ mod tests {
         assert!(s.take_pet_spell_casts().is_empty(), "drain empties");
     }
 
-    /// A pet-book pickup puts a **pet action word** on the cursor, not a spell payload — which is
-    /// exactly what makes it droppable on the pet bar (`cursor::pet`'s payload). The word is the
-    /// server's own, autocast bits and all.
     #[test]
     fn a_pet_book_pickup_carries_the_packed_word() {
         let mut s = UiScript::new().unwrap();
@@ -1445,7 +1178,7 @@ mod tests {
         assert_eq!(p.packed, 0xC100_0000 | 2649);
         assert_eq!(p.src_slot, 0, "it came out of the book, not off the bar");
 
-        // The player book still produces a SPELL payload — the two are not interchangeable.
+        // The player book still produces a spell payload.
         s.run("ClearCursor()").unwrap();
         assert!(s
             .eval::<bool>(r#"return PickupSpell(1, BOOKTYPE_SPELL)"#)
@@ -1453,9 +1186,8 @@ mod tests {
         assert!(matches!(s.cursor_payload(), Some(CursorPayload::Spell(_))));
     }
 
-    /// `GetSpellCooldown(id, "pet")` reads the PET's slot — the reference reaches bank 1 with the
-    /// same `0x6e2ea0(edx = isPet)` `GetPetActionCooldown` uses, so a spell on the bar and the same
-    /// spell in the book must never disagree. The elapsed-goes-cold rule is the player book's.
+    /// The reference reads a pet book cooldown through `0x6e2ea0` (`edx = isPet`), as
+    /// `GetPetActionCooldown` does, so the book and the bar agree.
     #[test]
     fn the_pet_books_cooldown_is_the_pets_own() {
         let mut s = UiScript::new().unwrap();
@@ -1469,7 +1201,7 @@ mod tests {
         assert!((start - 9.4).abs() < 1e-9, "start {start}");
         assert!((duration - 5.0).abs() < 1e-9);
         assert_eq!(enable, 1);
-        // The player book's slot 1 has none — proof the fork reached the right list.
+        // The player book's slot 1 has none.
         assert_eq!(
             s.eval::<(f64, f64, i32)>(r#"return GetSpellCooldown(1, BOOKTYPE_SPELL)"#)
                 .unwrap(),
@@ -1484,16 +1216,6 @@ mod tests {
         );
     }
 
-    /// **A rankless spell's rank is the empty string, not nil** — and the arity is always two.
-    ///
-    /// Both returns go through one push helper with no rank-specific branch (`0x4b4063`/`0x4b4076`,
-    /// single exit `mov eax,0x2` at `0x4b407c`), and the DBC pointer is never NULL, so an on-disk
-    /// NameSubtext offset of 0 becomes a pointer to the string block's byte 0 — a real zero-length
-    /// Lua string. 64% of the shipped Spell.dbc's rows are in that state, `Attack` among them.
-    ///
-    /// The two corpus idioms this was breaking are both asserted here, because "falsey either way"
-    /// is exactly the reasoning that made nil look acceptable: a nil is an ILLEGAL TABLE KEY
-    /// (Roid-Macros) and an ILLEGAL `string.find` argument (CT_MasterMod), while `""` is neither.
     #[test]
     fn a_rankless_spell_answers_an_empty_rank_and_still_two_values() {
         let mut s = UiScript::new().unwrap();
@@ -1525,7 +1247,7 @@ mod tests {
                 .unwrap(),
             "the rankless rank must be a STRING, not nil"
         );
-        // Roid-Macros/Generic.lua:35 and CT_MasterMod/CT_Master.lua:16, in miniature.
+        // Two addon idioms that a nil rank breaks: a table key and a `string.find` argument.
         s.run(r#"local _, r = GetSpellName(1, "spell") local t = {} t[r] = 1"#)
             .expect("a rankless rank must be a legal table key");
         s.run(r#"local _, r = GetSpellName(1, "spell") string.find(r, "(%d+)")"#)
@@ -1537,14 +1259,13 @@ mod tests {
             ("Heroic Strike".to_string(), "Rank 1".to_string())
         );
 
-        // An unfilled slot INSIDE the range is two nils, not one — distinguishable by the count.
+        // An empty slot inside the range is two nils.
         assert_eq!(s.arity(r#"GetSpellName(9, "spell")"#).unwrap(), 2);
         assert!(s
             .eval::<bool>(r#"local a, b = GetSpellName(9, "spell") return a == nil and b == nil"#)
             .unwrap());
 
-        // Past the reference's [0, 0x400) gate — an id of 1025 is index 1024 — it RAISES rather
-        // than answering nil.
+        // Id 1025 is index 1024, past the `[0, 0x400)` gate: it raises.
         let err = s
             .run(r#"GetSpellName(1025, "spell")"#)
             .expect_err("an out-of-range slot must raise");
@@ -1552,18 +1273,11 @@ mod tests {
             format!("{err}").contains("Invalid spell slot in GetSpellName"),
             "got {err}"
         );
-        // ...and 1023 is inside it, so it answers rather than raising.
+        // Id 1023 is inside it and answers.
         assert_eq!(s.arity(r#"GetSpellName(1023, "spell")"#).unwrap(), 2);
     }
 
-    /// **`UpdateSpells()` fires `SPELLS_CHANGED` and does nothing else** — decision 1924, from a
-    /// wow-re byte read of `[0x4b43e0,0x4b43ec)`.
-    ///
-    /// The assertion is that a registered handler RAN, not that any frame repainted: the reference
-    /// verb mutates no state at all, and the repaint is FrameXML's, reached only through the event.
-    /// Asserting a repaint here would re-encode the `BenillaUpdateSpells` guess this replaces —
-    /// which was both narrower than the reference (it repainted `SpellButton1..N` and nothing else)
-    /// and wider (the reference gates its frame update on `IsVisible()`).
+    /// The assertion is that a handler ran, not that a frame repainted: the repaint is FrameXML's.
     #[test]
     fn update_spells_fires_spells_changed_and_touches_nothing() {
         let s = UiScript::new().unwrap();
@@ -1583,16 +1297,12 @@ mod tests {
             1,
             "UpdateSpells must fire SPELLS_CHANGED synchronously, as SignalEvent does"
         );
-        // Zero return values — `arity = 0 (exact)` in `reference/1.12-shapes.tsv`.
+        // Zero returns, `reference/1.12-shapes.tsv`'s `arity = 0 (exact)`.
         assert_eq!(s.arity("UpdateSpells()").unwrap(), 0);
         assert!(s.errors().is_empty(), "errors: {:?}", s.errors());
     }
 
-    /// **`PlayerHasSpells()` is a hard-coded `1`** (1924): `push 0x3ff00000; push 0;
-    /// lua_pushnumber; mov eax,1; ret` — no branch and no store read, so it cannot answer anything
-    /// else. Asserted on an EMPTY spellbook precisely because that is the state where a
-    /// plausible-looking "does the player have any spells?" implementation would answer 0 and
-    /// diverge silently.
+    /// On an empty book, where a "has any spells" reading would answer 0.
     #[test]
     fn player_has_spells_is_one_even_with_an_empty_book() {
         let s = UiScript::new().unwrap();
@@ -1601,11 +1311,7 @@ mod tests {
         assert_eq!(s.arity("PlayerHasSpells()").unwrap(), 1);
     }
 
-    /// **Out of range answers `nil, nil, 0, 0` — four values, the last two NUMBERS** (1931). The
-    /// count is the assertion: `GetSpellTabInfo(0) == nil` is true either way, which is exactly how
-    /// the old one-nil shape passed. Stock `SpellBookFrame.lua:295` does `id > (offset + numSpells)`
-    /// unguarded straight off `SpellBookFrame_OnLoad`, so slots 3+4 nil is a raise on load, and
-    /// `(0+0)` is what makes the reference hide every button — the behaviour this pins.
+    /// The count is the assertion: `(GetSpellTabInfo(0)) == nil` holds for a single nil too.
     #[test]
     fn out_of_range_answers_four_values() {
         let s = UiScript::new().unwrap();
@@ -1629,9 +1335,6 @@ mod tests {
         }
     }
 
-    /// The argument is shape A (1931): absent or non-numeric RAISES the reference's own usage
-    /// string; a numeric STRING is coerced; a negative is truncated and falls to the fallback
-    /// rather than raising. `-1` and `0.5` are covered by the test above.
     #[test]
     fn tab_index_raises_when_absent_and_coerces_a_numeric_string() {
         let mut s = UiScript::new().unwrap();
@@ -1648,7 +1351,7 @@ mod tests {
             );
         }
         s.set_spellbook(book());
-        // "1" coerces exactly as 1 does — same name comes back.
+        // "1" coerces as 1 does.
         assert_eq!(
             s.eval::<String>("return (GetSpellTabInfo('1'))").unwrap(),
             s.eval::<String>("return (GetSpellTabInfo(1))").unwrap()
diff --git a/crates/benilla-ui/src/script/stable.rs b/crates/benilla-ui/src/script/stable.rs
index d17bee3e..72d07a57 100644
--- a/crates/benilla-ui/src/script/stable.rs
+++ b/crates/benilla-ui/src/script/stable.rs
@@ -1,161 +1,99 @@
-//! The stable-master bindings (decision 1676) — the hunter stable window's Lua surface, the same
-//! two-way seam as [`super::bank`] and [`super::trainer`]: the app pushes a **stable snapshot**
-//! ([`UiScript::set_stable`] — the wire's pet rows already resolved to icon/family/loyalty/diet
-//! strings), and the Lua's click/purchase/close calls queue outbound **intents** the app drains.
+//! The stable-master bindings: the app pushes a snapshot of the hunter's stable
+//! ([`UiScript::set_stable`], every wire row resolved to strings) and the Lua's clicks queue verbs
+//! the app drains.
 //!
-//! ## Three slots, and the current pet is one of them
+//! The window shows slots 0..=2: 0 is the current pet, 1 and 2 the stable slots a hunter buys
+//! (`NUM_PET_STABLE_SLOTS` 2, two `StableSlotPrices.dbc` rows, vmangos `MAX_PET_STABLES` 2). The
+//! wire's 1-based slot arrives rebased ([`benilla_protocol::messages::StabledPet::slot`]). Slot 0
+//! can hold a row with no pet out: a dismissed or distant pet still comes from the server's
+//! character-pet cache, and the stock window falls back to `GetStablePetInfo(0)` when
+//! `UnitExists("pet")` is false (`PetStable.lua:138`).
 //!
-//! The window shows **`0..=2`**: slot `0` is the pet at the player's side, slots `1` and `2` are the
-//! two stable slots a hunter buys (5875 ships exactly two — `StableSlotPrices.dbc` has two rows,
-//! vmangos's `MAX_PET_STABLES` is 2, and the reference's `NUM_PET_STABLE_SLOTS` is 2). The wire is
-//! 1-based over these; [`benilla_protocol::messages::StabledPet::slot`] already rebased it, so
-//! everything here speaks the reference UI's own indices.
-//!
-//! **Slot 0 can be occupied while the player has no pet out.** A hunter whose pet is dismissed (or
-//! merely too far away to be summoned) still gets a slot-0 row from the server, read off the
-//! character-pet cache — which is exactly why the reference falls back to `GetStablePetInfo(0)`
-//! when `UnitExists("pet")` is false (`PetStable.lua:131-146`) instead of showing an empty slot.
-//!
-//! ## What the snapshot resolves, and why the app does it
-//!
-//! The wire names a `creature_template` entry and a loyalty *level*; the window wants an icon, a
-//! localized family word, a loyalty *name* and a diet list. Every one of those is a catalog join
-//! the app already owns for the live pet ([`super::pet`], decisions 1005/1062), so the app does the
-//! join once and pushes strings — this module never sees a DBC. The one join with no live-pet twin
-//! is the icon of a pet that is *not* summoned: it comes from the creature query's display id,
-//! which is why that field stopped being discarded (decision 1676).
-//!
-//! ## The drag rides the cursor at mode 10
-//!
-//! `PickupStablePet` puts the pet on the **global cursor** under payload mode 10
-//! ([`super::cursor::CursorPayload::StablePet`]), carrying the stable index the grab recorded.
-//!
-//! This corrects what benilla shipped first. The original build made the drag frame-local on the
-//! strength of wow-re's payload-mode table, which recorded mode 10 as "class/talent ability (DBC)"
-//! — so the census read as "there is no stable-pet mode". The stable-master carve found that
-//! `0x495020` **is** the stabled-pet grab and that `[0xb4d900] = 10` is written at exactly one site
-//! image-wide, inside it; wow-re corrected its own note in the same round
-//! (`system/ui/scratch/stable-master-window.md` §9). Decision 1677.
-//!
-//! ## Two return conventions that are the API, not details
-//!
-//! `ClickStablePet` returns **exactly one value, always**, and which one is keyed *solely* on
-//! whether the cursor was holding a pet — never on whether a packet went out:
-//!
-//! - **a plain click** (no payload) is a pure select and pushes the number `1.0` on all three of
-//!   its legs, so it is **always truthy** and the reference always repaints;
-//! - **a drop** pushes **nil** on every leg, including the ones that send a packet, so the
-//!   reference never repaints from the drop — the repaint comes from the server's next list.
-//!
-//! Getting this backwards is invisible in a test that only checks the packets and very visible in
-//! play: the window would repaint off a stale snapshot on every drag and skip the repaint on every
-//! click.
+//! `PickupStablePet` puts the pet on the global cursor as payload mode 10
+//! ([`super::cursor::CursorPayload::StablePet`]): `[0xb4d900] = 10` is written at one site,
+//! `0x4950ae`, in the stabled-pet grab `0x495010`.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// Window slots: the current pet (`0`) plus the two stable slots — the reference's
-/// `NUM_PET_STABLE_SLOTS = 2` counted inclusively from zero (`PetStable.lua:1`).
+/// The current pet plus the `NUM_PET_STABLE_SLOTS` (2) stable slots (`PetStable.lua:1`).
 pub const NUM_STABLE_SLOTS: usize = 3;
 
-/// One row of the stable window, with every wire field already resolved to what the Lua renders.
-/// `None` in [`StableState::slots`] is an empty slot — which the window draws differently from an
-/// *unbought* one (that distinction is [`StableState::num_stable_slots`]'s).
+/// One stable window row, every wire field resolved to what the Lua renders. An empty slot is
+/// `None` in [`StableState::slots`]; an unbought one lies past [`StableState::num_stable_slots`].
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct StablePetSlot {
-    /// The pet's own id — what [`StableIntent::Unstable`]/[`StableIntent::Swap`] name on the wire.
-    /// Never its slot: the two disagree for any hunter whose stable is not in id order.
+    /// The pet's id, which the unstable and swap verbs name; never its slot.
     pub pet_number: u32,
-    /// `Interface\Icons\…` for the pet's family, or `None` while the creature query is in flight.
-    /// The reference passes this straight to `SetItemButtonTexture`, which takes an empty texture
-    /// for a missing icon — so `None` renders the empty-slot art, not a white square (decision
-    /// 1046's sweep).
+    /// The family icon path, `None` while the creature query is in flight; the stock window passes
+    /// it to `SetItemButtonTexture`, which draws the empty-slot art for nil.
     pub icon: Option<String>,
     /// The name the hunter gave the pet, not the creature template's.
     pub name: String,
     pub level: u32,
-    /// The localized `CreatureFamily.dbc` word ("Wolf", "Cat"). `None` when the creature query has
-    /// not landed — the reference concatenates it into the level line unguarded, so the binding
-    /// substitutes an empty string rather than handing Lua a nil to concatenate.
+    /// The localized `CreatureFamily.dbc` word ("Wolf"), `None` until the creature query lands.
     pub family: Option<String>,
     /// The localized `PetLoyalty.dbc` name for the wire's loyalty level.
     pub loyalty: Option<String>,
-    /// The localized pet-food names this pet's family eats — `GetStablePetFoodTypes`'s returns,
-    /// which the reference joins with `BuildListString` into the diet tooltip.
+    /// The localized food names the pet's family eats: `GetStablePetFoodTypes`'s returns.
     pub diet: Vec<String>,
 }
 
-/// The open stable window's snapshot. Pushed whole while a stable session is open; `None` = no
-/// stable open (the window is closed).
+/// The open stable's snapshot, pushed whole; `None` when no stable is open.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct StableState {
-    /// Stable slots **purchased**, `0..=2` (the wire's `numStableSlots`). Not a count of occupied
-    /// ones: it is what enables slot buttons `1..=num` and greys the rest, and what prices the next
-    /// purchase.
+    /// Stable slots bought, 0..=2 (the wire's `numStableSlots`), not occupied: it enables buttons
+    /// `1..=n` and prices the next slot.
     pub num_stable_slots: u32,
-    /// The next slot's price in copper (`StableSlotPrices.dbc` row `num_stable_slots + 1`), or `0`
-    /// past the table — a state in which the reference has already hidden the purchase row.
+    /// The next slot's price in copper (`StableSlotPrices.dbc` row `num_stable_slots + 1`), 0 past
+    /// the table, where the stock window has hidden the purchase row.
     pub next_slot_cost: u32,
-    /// The three window slots; index `0` is the current pet.
+    /// The three window slots; index 0 is the current pet.
     pub slots: [Option<StablePetSlot>; NUM_STABLE_SLOTS],
-    /// The player has a **live** pet out — the client's own `[0xb714a0]|[0xb714a4]` guid test, the
-    /// gate that forks a stabled pet's drop between swap and unstable (§6.2).
-    ///
-    /// **Deliberately not `slots[0].is_some()`.** A dismissed pet, or one left out of range, still
-    /// has a slot-0 row from the server's character-pet cache while the live guid is zero — so the
-    /// two disagree exactly there, and the client follows the guid.
+    /// A live pet is out: the client's pet-guid test (`[0xb714a0]|[0xb714a4]`), which forks a
+    /// stabled pet's drop between swap and unstable. Not `slots[0].is_some()`: a dismissed or
+    /// distant pet keeps its slot-0 row with no live guid.
     pub has_live_pet: bool,
 }
 
 impl StableState {
-    /// How many of the three slots hold a pet — `GetNumStablePets()`.
+    /// `GetNumStablePets()`: how many of the three slots hold a pet.
     fn num_pets(&self) -> u32 {
         self.slots.iter().filter(|s| s.is_some()).count() as u32
     }
 }
 
-/// An outbound stable verb the Lua asked for, drained by the app (which addresses it to the open
-/// session's NPC — the guid is the app's, never Lua's).
+/// An outbound stable verb, drained by the app, which addresses it to the open stable master.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum StableIntent {
-    /// `CMSG_STABLE_PET` — put the current pet away. **Carries no destination**: the server takes
-    /// the first free bought slot itself, so there is no "stable into slot 2" to express.
+    /// `CMSG_STABLE_PET`: stable the current pet; the server picks the first free bought slot.
     Stable,
-    /// `CMSG_UNSTABLE_PET` — summon this pet number, valid only with no current pet.
+    /// `CMSG_UNSTABLE_PET`: summon this pet number, valid only with no current pet.
     Unstable(u32),
-    /// `CMSG_STABLE_SWAP_PET` — trade the current pet for this pet number, in one step.
+    /// `CMSG_STABLE_SWAP_PET`: trade the current pet for this pet number in one step.
     Swap(u32),
-    /// `CMSG_BUY_STABLE_SLOT` — buy the next slot; the *which* is implicit, as with the bank's.
+    /// `CMSG_BUY_STABLE_SLOT`: buy the next slot.
     BuySlot,
 }
 
-/// The window's own transient state — selection and the frame-local drag (module doc: the cursor is
-/// not involved). Lives beside the snapshot rather than inside it because the app *replaces* the
-/// snapshot on every list packet, and a repaint must not drop what the player has selected.
+/// The window's own state beside the snapshot: the selection, the queued verbs and the close flag.
 #[derive(Debug)]
 pub(crate) struct StableModel {
     pub(crate) state: Option<StableState>,
-    /// The selection, held **as the client holds it** (`[0xb72250]`): `-1` = the summoned pet,
-    /// `0` = nothing, otherwise a **petNumber**.
-    ///
-    /// A petNumber rather than a slot index because that is what the binary stores, and it is what
-    /// makes a *stale* selection degrade correctly: `GetSelectedStablePet` searches the array for
-    /// the number and answers `-1` when the pet is no longer there (§7.1's fall-through).
+    /// The selection as the client holds it (`[0xb72250]`): -1 the summoned pet, 0 nothing, else
+    /// a pet number, so a pet no longer listed reads back as nothing (`0x4cb84c`).
     pub(crate) selected: i32,
     pub(crate) intents: Vec<StableIntent>,
     pub(crate) close: bool,
 }
 
-/// The zero state is the client's `0` — "nothing selected" — not `-1`, which is its encoding for
-/// *the summoned pet*. The Lua-facing `-1` that `PetStable.lua:44` tests is
-/// [`super::UiScript::stable_selection`]'s translation of this, not this field (§7.1).
+/// Nothing selected, the client's reset (`0x4caad3`); Lua reads it as -1 through
+/// [`super::UiScript::stable_selection`] (`PetStable.lua:50`).
 impl Default for StableModel {
     fn default() -> Self {
         Self {
             state: None,
-            // `0` is "nothing selected" in the client's own encoding — NOT `-1`, which means the
-            // summoned pet. The window's zero state is the reset `0x4caad3` writes.
             selected: 0,
             intents: Vec::new(),
             close: false,
@@ -164,46 +102,36 @@ impl Default for StableModel {
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open stable's snapshot.
-    ///
-    /// **Every list message clears the selection**, and that is the client's own behaviour
-    /// (`0x4cadf8` writes `[0xb72250] = 0` on each one), not a simplification. The first build kept
-    /// it across a refresh on the reasoning that benilla re-lists after every action and a reset
-    /// would "fight the player" — the carve says the reference re-lists on exactly the same
-    /// successes and clears every time. It does not fight anything, because `PetStable_Update`
-    /// immediately re-picks: the current pet if there is one, else the first occupied slot
-    /// (`PetStable.lua:44-59`). Keeping a selection across a list is what would be wrong — it can
-    /// name a pet the new list no longer contains.
+    /// Push the open stable's snapshot, or clear it with `None`. Every push clears the selection,
+    /// as each list does in the client (`0x4cadf8`); the stock window then re-picks the current pet
+    /// or the first occupied slot (`PetStable.lua:49-62`).
     pub fn set_stable(&mut self, state: Option<StableState>) {
         let mut model = self.model_mut();
         model.stable.selected = 0;
-        // The held payload is NOT dropped here: closing the window clears only the stable-master
-        // guid in the reference (`0x4cae10`), and a picked-up pet lives on the shared cursor, whose
-        // own ClearCursor arms own it.
+        // A held pet stays on the cursor: the reference's close clears only the stable-master
+        // guid (`0x4cae10`).
         model.stable.state = state;
     }
 
-    /// Drain the queued stable verbs (module doc: the app addresses them to the open NPC).
+    /// Drain the queued stable verbs.
     pub fn take_stable_intents(&mut self) -> Vec<StableIntent> {
         std::mem::take(&mut self.model_mut().stable.intents)
     }
 
-    /// Whether `ClosePetStables()` was called since the last drain (and clear the flag). No packet
-    /// exists for it — the app just clears its local session, the bank/merchant pattern.
+    /// Whether `ClosePetStables()` was called since the last drain; no packet exists for it.
     pub fn take_stable_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().stable.close)
     }
 
-    /// `GetSelectedStablePet()`'s answer — **`0` = the summoned pet, `1..=2` a stable slot, `-1`
-    /// nothing** — translated out of the petNumber the model holds, exactly as `0x4cb800` does
-    /// (find the number in the array, `inc eax`; a number no longer present falls through to `-1`).
+    /// `GetSelectedStablePet()`'s answer, translated from the held pet number: 0 the summoned
+    /// pet, 1..=2 a stable slot, -1 nothing.
     pub fn stable_selection(&mut self) -> i32 {
         let model = self.model_mut();
         selected_slot(&model.stable)
     }
 }
 
-/// The petNumber→slot translation behind `GetSelectedStablePet` (§7.1).
+/// The pet number to slot translation behind `GetSelectedStablePet` (`0x4cb810`).
 fn selected_slot(m: &StableModel) -> i32 {
     match m.selected {
         -1 => 0,
@@ -222,53 +150,31 @@ fn selected_slot(m: &StableModel) -> i32 {
                     })
                     .map(|(i, _)| i as i32)
             })
-            // A selection whose pet is gone after a refresh degrades to "nothing", never to a
-            // wrong slot — the loop's own fall-through at `0x4cb84c`.
+            // A pet no longer listed reads as nothing, the loop's fall-through at `0x4cb84c`.
             .unwrap_or(-1),
     }
 }
 
-/// Read a slot argument into an index into [`StableState::slots`]. Out-of-range answers `None`, so
-/// every binding below degrades to the reference's empty-slot behaviour rather than panicking on a
-/// stray addon call.
+/// A slot argument as an index into [`StableState::slots`], `None` out of range.
 fn slot_index(i: i64) -> Option<usize> {
     usize::try_from(i).ok().filter(|&i| i < NUM_STABLE_SLOTS)
 }
 
-/// Commit a drag from slot `from` onto slot `to` — the **one** place the stable's move law lives,
-/// now read off the binary (`ClickStablePet 0x4cb420` regime B, wow-re
-/// `system/ui/scratch/stable-master-window.md` §6.2; decision 1677).
-///
-/// The first build inferred this from the server's constraint set and got the shape right and the
-/// **three edges wrong**. Each of them is a real case:
-///
-/// 1. **The summoned pet onto an OCCUPIED stable slot sends `SWAP`, not `STABLE`.** "Drag out ⇒
-///    stable it" only holds when the target slot is empty. The inferred version sent `STABLE` for
-///    both, which vmangos then refuses whenever both bought slots are full — the pet stays put and
-///    nothing says why.
-/// 2. **A drop onto an UNPURCHASED slot sends nothing**, and is still a completed drop (cursor
-///    cleared, falsy return).
-/// 3. **A stabled pet onto the summoned slot forks on the LIVE PET GUID**, not on whether slot 0
-///    has a row. A dismissed pet has a row and no guid, and the client sends `UNSTABLE` there —
-///    the inferred version read the row and sent `SWAP`.
-///
-/// Stable→stable remains a no-op: 5875 has no opcode for it, which the first build did get right.
+/// The verb a drop from slot `from` onto slot `to` sends (`ClickStablePet 0x4cb420`): the summoned
+/// pet onto an occupied slot swaps, onto an empty bought slot stables, onto an unbought slot sends
+/// nothing; a stabled pet onto slot 0 swaps when a live pet is out, else unstables. Stable to
+/// stable has no opcode.
 fn drag_verb(from: u8, to: u8, state: &StableState) -> Option<StableIntent> {
     if from == to {
         return None;
     }
     let occupied = |i: u8| state.slots.get(usize::from(i)).and_then(|s| s.as_ref());
     match (from, to) {
-        // The summoned pet is held.
         (0, _) => match occupied(to) {
-            // …onto an occupied stable slot: trade places.
             Some(target) => Some(StableIntent::Swap(target.pet_number)),
-            // …onto an empty slot the player owns: stable it (the server picks the destination).
             None if u32::from(to) <= state.num_stable_slots => Some(StableIntent::Stable),
-            // …onto a slot they have not bought: nothing.
             None => None,
         },
-        // A stabled pet is held, dropped on the summoned slot.
         (_, 0) => occupied(from).map(|held| {
             if state.has_live_pet {
                 StableIntent::Swap(held.pet_number)
@@ -276,7 +182,6 @@ fn drag_verb(from: u8, to: u8, state: &StableState) -> Option<StableIntent> {
                 StableIntent::Unstable(held.pet_number)
             }
         }),
-        // Stable slot → stable slot: no opcode exists in 5875.
         _ => None,
     }
 }
@@ -285,10 +190,8 @@ fn drag_verb(from: u8, to: u8, state: &StableState) -> Option<StableIntent> {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetStablePetInfo(i) → icon, name, level, family, loyalty — **5 values on every reachable
-    // exit** (`0x4cb280`: `eax = 5` at both returns). A miss pushes `nil, nil, 0.0, nil, nil`, NOT
-    // nothing: the reference both tests the call for truthiness and destructures all five, and a
-    // bare nil would make `level` nil where the client answers 0.
+    // GetStablePetInfo(i) → icon, name, level, family, loyalty: five values on every exit
+    // (`0x4cb280`), a miss answering nil, nil, 0, nil, nil.
     g.set(
         "GetStablePetInfo",
         lua.create_function(|lua, i: i64| {
@@ -324,9 +227,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetStablePetFoodTypes(i) → the localized diet names, one return each (the reference feeds the
-    // lot to BuildListString). Nothing at all for an empty slot or a pet whose family has no diet —
-    // the reference guards with `if ( GetStablePetFoodTypes(i) )` before formatting the tooltip.
+    // GetStablePetFoodTypes(i) → one localized diet name per value; none for an empty slot or a
+    // family with no diet.
     g.set(
         "GetStablePetFoodTypes",
         lua.create_function(|lua, i: i64| {
@@ -346,8 +248,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumStableSlots() → slots PURCHASED (0..=2). The reference both enables buttons `i <= n`
-    // and hides the purchase row at `n == NUM_PET_STABLE_SLOTS` off this one number.
+    // GetNumStableSlots() → slots bought, 0..=2.
     g.set(
         "GetNumStableSlots",
         lua.create_function(|lua, ()| {
@@ -373,9 +274,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNextStableSlotCost() → the next slot's price in copper (the app read it from
-    // StableSlotPrices.dbc). 0 with no stable open, and 0 past the table — where the reference has
-    // already hidden the row that would show it.
+    // GetNextStableSlotCost() → the next slot's price in copper, 0 with no stable open or past the
+    // table.
     g.set(
         "GetNextStableSlotCost",
         lua.create_function(|lua, ()| {
@@ -386,34 +286,25 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSelectedStablePet() → the selected slot, or -1. The sentinel is the API: the reference
-    // tests `selectedPet == -1` to decide whether to pick a slot for the player.
+    // GetSelectedStablePet() → the selected slot, or -1, on which the stock window picks one itself
+    // (`PetStable.lua:50`).
     g.set(
         "GetSelectedStablePet",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
-            // NOT the raw field: the model holds the client's petNumber encoding, and this binding
-            // is its translation to slot indices (`selected_slot`).
             Ok(i64::from(selected_slot(&model.stable)))
         })?,
     )?;
 
-    // ClickStablePet(i) → **exactly one value, always**, and which one is keyed SOLELY on whether
-    // the cursor held a pet — never on whether a packet went out (§6.2).
-    //
-    //   plain click  -> pure select, no packet, pushes 1.0 on ALL THREE legs  => always TRUTHY
-    //   drop         -> clears the cursor, pushes nil on EVERY leg            => always FALSY
-    //
-    // So the reference repaints on every click and on NO drop; a drop's repaint arrives with the
-    // server's next list. The first build had this inverted (true on a committed drag, false on a
-    // no-op) — invisible to a packet-only test, and in play a window that repaints off a stale
-    // snapshot on every drag and skips the repaint on every click.
+    // ClickStablePet(i) → one value (`0x4cb420`), keyed only on whether the cursor held a pet: a
+    // plain click selects and answers 1, so the stock window repaints; a drop answers nil, packet
+    // or not, and the repaint comes with the server's next list.
     g.set(
         "ClickStablePet",
         lua.create_function(|lua, i: i64| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             let Some(to) = slot_index(i) else {
-                // Out of range still takes the select leg's "nothing" arm below.
+                // Out of range: a click selects nothing, a drop clears the cursor.
                 if !matches!(
                     model.cursor,
                     Some(super::cursor::CursorPayload::StablePet(_))
@@ -426,7 +317,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             };
             let to = to as u8;
 
-            // Regime B — a drop.
+            // A drop.
             if let Some(super::cursor::CursorPayload::StablePet(held)) = model.cursor.clone() {
                 let from = held.slot;
                 let intent = model
@@ -441,7 +332,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 return Ok(Value::Nil);
             }
 
-            // Regime A — a plain click: pure select, always truthy.
+            // A plain click: select only.
             let pet_number = model
                 .stable
                 .state
@@ -449,21 +340,18 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                 .and_then(|s| s.slots[usize::from(to)].as_ref())
                 .map(|p| p.pet_number);
             model.stable.selected = match (to, pet_number) {
-                // Slot 0 selects the summoned pet by its own sentinel, not by a petNumber.
+                // Slot 0 selects the summoned pet by its sentinel, not a pet number.
                 (0, _) => -1,
                 (_, Some(n)) => n as i32,
-                // An empty (or unowned) slot selects NOTHING, rather than the slot itself.
+                // An empty slot selects nothing.
                 (_, None) => 0,
             };
             Ok(Value::Number(1.0))
         })?,
     )?;
 
-    // PickupStablePet(i) — the mode-10 grab. **0 Lua values, always.**
-    //
-    // The client's gate is the family ICON path, not occupancy (`0x495010`: resolve the record,
-    // require a non-empty `CreatureFamily` icon, then set the payload). Ours is the resolved icon,
-    // which is the same test one step later: no icon, no grab.
+    // PickupStablePet(i): the mode-10 cursor grab, returning nothing. The gate is the family icon,
+    // not occupancy (`0x495010`): no icon, no grab.
     g.set(
         "PickupStablePet",
         lua.create_function(|lua, i: i64| {
@@ -484,9 +372,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // StablePet() — 0 args, and it makes no Lua call at all in the reference: its only gate is a
-    // stable master being open, which for us is the snapshot's existence. Not called by the shipped
-    // FrameXML (the drag path sends this verb); it exists because the binding does.
+    // StablePet(): no arguments, gated only on an open stable; stock FrameXML stables by drag.
     g.set(
         "StablePet",
         lua.create_function(|lua, ()| {
@@ -498,9 +384,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnstablePet(i) — carries a gate the drag path does NOT (§7.1): it requires no charmed unit
-    // and **no pet out**, and bails SILENTLY otherwise, with no packet and no error. Its unsigned
-    // bound also rejects index 0 outright, where the drag path treats 0 as the summoned pet.
+    // UnstablePet(i): silently refused with a pet out (`0x468550`), a gate the drag path lacks; its
+    // unsigned bound rejects slot 0. The reference's other gate, no charmed unit, is not built.
     g.set(
         "UnstablePet",
         lua.create_function(|lua, i: i64| {
@@ -526,27 +411,20 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetPetStablePaperdoll(model) — inert here, deliberately, and this is the same divergence
-    // PetPaperDollFrame.xml records for `PetModelFrame:SetUnit("pet")`: benilla's model panes are
-    // app-side booths that follow the selection every frame, so there is no VM-side unit to point.
-    // The binding still exists because the reference calls it (four sites) and an addon may.
+    // Deviation: SetPetStablePaperdoll(model) is inert, because the model pane is an app-side
+    // booth that follows the selection every frame, with no VM-side unit to point.
     g.set(
         "SetPetStablePaperdoll",
         lua.create_function(|_, _model: Value| Ok(()))?,
     )?;
 
-    // BuyStableSlot() — 0 args, with the client's own **silent** local gates in order (§7.1): a
-    // stable master open · the hard cap `slots != 2` · a price row exists · **affordability**.
-    // None of them shows a message; the reference disables the button instead. Applying them here
-    // rather than trusting the button matters because an addon can call the binding directly, and
-    // the server's refusal for the cap is the same indistinguishable ERR_STABLE as everything else.
+    // BuyStableSlot(): the client's silent gates, in order: an open stable, fewer than 2 slots
+    // (`0x4cb0c4`), a price row and affordability (`0x4cb122`).
     g.set(
         "BuyStableSlot",
         lua.create_function(|lua, ()| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // Affordability reads the VM's own purse — the same `model.money` the reference's
-            // `GetMoney()` returns and its own button-state ladder compares (`PetStable.lua:203`),
-            // rather than a second copy of the number in the stable snapshot.
+            // Affordability reads `model.money`, the purse `GetMoney()` answers.
             let money = model.money;
             let allowed = model.stable.state.as_ref().is_some_and(|s| {
                 s.num_stable_slots as usize != NUM_STABLE_SLOTS - 1
@@ -560,8 +438,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClosePetStables() — client-side close, no packet exists (vmangos has no close opcode): flag
-    // the app to clear its session.
+    // ClosePetStables(): no packet exists; the flag tells the app to clear its session.
     g.set(
         "ClosePetStables",
         lua.create_function(|lua, ()| {
@@ -609,7 +486,6 @@ mod tests {
         ])));
     }
 
-    /// The read surface, through the reference's own destructuring.
     #[test]
     fn the_read_surface_answers_the_reference_calls() {
         let mut s = UiScript::new().unwrap();
@@ -626,7 +502,7 @@ mod tests {
             50_000
         );
 
-        // `PetStable.lua:76` — the exact five-value destructuring the window renders from.
+        // `PetStable.lua:77`'s five-value destructuring.
         assert_eq!(
             s.eval::<(String, String, i64, String, String)>(
                 "local i, n, l, f, loy = GetStablePetInfo(1) return i, n, l, f, loy"
@@ -651,17 +527,13 @@ mod tests {
             .unwrap());
     }
 
-    /// **`GetStablePetInfo` returns five values on EVERY exit** (`eax = 5` at both returns), with a
-    /// miss pushing `nil, nil, 0, nil, nil`. The reference both tests the call for truthiness and
-    /// destructures all five, so a bare nil would leave `level` nil where the client answers 0 —
-    /// and would silently change the arity an addon sees.
     #[test]
     fn a_missing_pet_still_answers_five_values() {
         let mut s = UiScript::new().unwrap();
         open(&mut s);
         for call in ["GetStablePetInfo(2)", "GetStablePetInfo(9)"] {
             assert_eq!(s.arity(call).unwrap(), 5, "{call} arity");
-            // Still falsy on the reference's own `if ( GetStablePetInfo(i) )` test.
+            // Still falsy for the stock window's `if ( GetStablePetInfo(i) )`.
             assert!(s.eval::<bool>(&format!("return not {call}")).unwrap());
             assert_eq!(
                 s.eval::<i64>(&format!("local _, _, l = {call} return l"))
@@ -672,9 +544,6 @@ mod tests {
         }
     }
 
-    /// **A plain click always returns truthy**, on all three of its legs — including a re-click of
-    /// the same slot and a click on an empty one. The reference repaints on the return, so a
-    /// falsy answer anywhere here is a window that stops repainting on click.
     #[test]
     fn every_plain_click_returns_truthy() {
         let mut s = UiScript::new().unwrap();
@@ -697,9 +566,6 @@ mod tests {
         );
     }
 
-    /// The selection's three encodings, read back through `GetSelectedStablePet`'s translation:
-    /// slot 0 answers 0, an occupied stable slot answers its index, and an **empty** slot selects
-    /// nothing (`-1`) rather than itself.
     #[test]
     fn the_selection_translates_back_to_slot_indices() {
         let mut s = UiScript::new().unwrap();
@@ -716,8 +582,6 @@ mod tests {
         );
     }
 
-    /// A selection is held as a **petNumber**, so a refresh that no longer contains that pet
-    /// degrades to "nothing" rather than to a wrong slot — and every list clears it anyway.
     #[test]
     fn a_list_clears_the_selection_and_a_stale_pet_degrades() {
         let mut s = UiScript::new().unwrap();
@@ -725,34 +589,28 @@ mod tests {
         s.eval::<()>("ClickStablePet(1)").unwrap();
         assert_eq!(s.stable_selection(), 1);
 
-        // Every list message clears it (`0x4cadf8`) — the reference re-picks in PetStable_Update.
+        // Every list clears it (`0x4cadf8`).
         open(&mut s);
         assert_eq!(s.stable_selection(), -1, "a list clears the selection");
     }
 
-    /// **A drop always returns nil**, on every leg — the ones that send a packet included. The
-    /// reference therefore never repaints from a drop; the repaint arrives with the server's next
-    /// list. This is the convention the first build had inverted.
     #[test]
     fn every_drop_returns_falsy_even_when_it_sends() {
         let mut s = UiScript::new().unwrap();
         open(&mut s);
-        // A drop that DOES send.
+        // A drop that sends.
         assert!(s
             .eval::<bool>("PickupStablePet(1) return ClickStablePet(0) == nil")
             .unwrap());
         assert_eq!(s.take_stable_intents(), vec![StableIntent::Swap(8)]);
 
-        // A drop that sends nothing is equally falsy.
+        // A drop that sends nothing.
         assert!(s
             .eval::<bool>("PickupStablePet(1) return ClickStablePet(1) == nil")
             .unwrap());
         assert!(s.take_stable_intents().is_empty());
     }
 
-    /// **The summoned pet onto an OCCUPIED stable slot is a SWAP, not a STABLE** — the first of the
-    /// three edges the inferred law got wrong. Sending STABLE there is refused by the server
-    /// whenever both bought slots are full, and nothing says why.
     #[test]
     fn dropping_onto_an_occupied_slot_swaps() {
         let mut s = UiScript::new().unwrap();
@@ -762,8 +620,6 @@ mod tests {
         assert_eq!(s.take_stable_intents(), vec![StableIntent::Swap(8)]);
     }
 
-    /// …and onto an EMPTY slot the player owns it is a STABLE, whose destination the wire cannot
-    /// carry; onto one they have **not bought**, nothing at all — but the cursor still clears.
     #[test]
     fn an_unpurchased_slot_takes_the_drop_and_sends_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -776,14 +632,11 @@ mod tests {
         s.eval::<()>("PickupStablePet(0) ClickStablePet(2)")
             .unwrap();
         assert!(s.take_stable_intents().is_empty(), "slot 2 is not bought");
-        // The drop completed: the cursor is empty, so the next click SELECTS.
+        // The drop completed: the cursor is empty, so the next click selects.
         assert!(s.eval::<bool>("return ClickStablePet(1) and true").unwrap());
         assert!(s.take_stable_intents().is_empty());
     }
 
-    /// **The stabled→summoned fork reads the LIVE PET GUID, not slot 0's row** — the third edge.
-    /// A dismissed pet still has a row from the server's character-pet cache while the guid is
-    /// zero, and the client sends UNSTABLE there.
     #[test]
     fn the_fork_follows_the_live_pet_not_the_row() {
         let mut s = UiScript::new().unwrap();
@@ -805,7 +658,6 @@ mod tests {
         );
     }
 
-    /// Stable→stable has no opcode in 5875, and an empty slot carries nothing to grab.
     #[test]
     fn stable_to_stable_is_a_no_op_and_empty_slots_do_not_grab() {
         let mut s = UiScript::new().unwrap();
@@ -824,8 +676,6 @@ mod tests {
         assert!(s.take_stable_intents().is_empty());
     }
 
-    /// `BuyStableSlot`'s gates are the client's own, and all silent: the hard cap, and
-    /// affordability.
     #[test]
     fn buy_stable_slot_gates_locally_and_silently() {
         let mut s = UiScript::new().unwrap();
@@ -840,7 +690,7 @@ mod tests {
         s.eval::<()>("BuyStableSlot()").unwrap();
         assert!(s.take_stable_intents().is_empty(), "unaffordable is silent");
 
-        // Both slots owned — the hard cap (and money restored, so only the cap can refuse).
+        // Both slots owned, with money restored so only the cap refuses.
         s.set_money(1_000_000);
         let mut full = state([None, None, None]);
         full.num_stable_slots = 2;
@@ -849,8 +699,6 @@ mod tests {
         assert!(s.take_stable_intents().is_empty(), "the cap is silent");
     }
 
-    /// `UnstablePet` carries a gate the drag path does not: no pet out, else silence. And its
-    /// unsigned bound rejects index 0, where the drag path reads 0 as the summoned pet.
     #[test]
     fn the_unstable_binding_gates_where_the_drag_path_does_not() {
         let mut s = UiScript::new().unwrap();
@@ -867,8 +715,6 @@ mod tests {
         assert_eq!(s.take_stable_intents(), vec![StableIntent::Unstable(8)]);
     }
 
-    /// The close intent, and that closing does NOT drop a held pet — the reference's close clears
-    /// only the stable-master guid.
     #[test]
     fn close_drains_and_leaves_the_cursor_alone() {
         let mut s = UiScript::new().unwrap();
@@ -879,7 +725,6 @@ mod tests {
         assert!(!s.take_stable_close(), "drain clears");
     }
 
-    /// `SetPetStablePaperdoll` exists and is harmless — the reference calls it at four sites.
     #[test]
     fn the_paperdoll_setter_is_callable() {
         let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/statusbar.rs b/crates/benilla-ui/src/script/statusbar.rs
index ad65e561..d7047bd4 100644
--- a/crates/benilla-ui/src/script/statusbar.rs
+++ b/crates/benilla-ui/src/script/statusbar.rs
@@ -1,17 +1,8 @@
-//! The `StatusBar` method surface — the first *per-kind* widget behavior over the kind tag
-//! (`CSimpleStatusBar`, factory `0x6eef20`).
-//!
-//! Grounded in wow-re's byte-verified LoadXML table (RF-28, `rf28-typed-widget-loadxml.md`):
-//! a reversed `min > max` pair is swapped, `defaultValue` routes through SetValue, orientation is
-//! the shared enum HORIZONTAL=0/VERTICAL=1 (`0x811b00`), the bar texture's layer defaults ARTWORK,
-//! and the widget adds the `OnValueChanged` script slot (`+0x32c`). The **fill** mechanism is
-//! byte-pinned too (`nameplate-vkey.md`): `SetValue` writes the bar region's 4-corner UV block with
-//! `u1 = GetValue()` *and* recomputes `right = left + frac·width`, so the fill is a left-anchored
-//! **crop** — the art is sliced, never squeezed. Applied at extract (`bar_fill_rect`/`bar_fill_uv`).
-//!
-//! The methods live in their own registry table, consulted by the frame `__index` dispatcher only
-//! for StatusBar frames — so duck-typing addons (`if frame.SetValue then …`) see `nil` on every
-//! other kind, exactly as against the client's per-class method sets.
+//! The `StatusBar` methods (`CSimpleStatusBar`, factory `0x6eef20`, `LoadXML` `0x782ef0`,
+//! orientations `0x811b00`). The fill is a left-anchored crop, the art sliced and never squeezed:
+//! `SetValue` sets the UV's `u1` to the fill fraction and the right edge with it (`0x770410`),
+//! applied at extract.
+//! Only StatusBar frames answer these, so a duck-typing addon sees nil on every other kind.
 
 use mlua::{Lua, Table, Value};
 
@@ -21,12 +12,11 @@ use super::{event, Model, RegionData};
 use crate::order::DrawLayer;
 use crate::widget::{KindState, RegionKind, StatusBarState};
 
-/// Registry key of the StatusBar method table (the MAXCSTACK discipline: Lua-side root, named key).
+/// Registry key of the StatusBar method table.
 pub(super) const REG_STATUSBAR_METHODS: &str = "__benilla_statusbar_methods";
 
-/// Run `f` over a frame's StatusBar state under one short write borrow. Errors if `this` is not a
-/// live StatusBar (unreachable through the kind dispatcher, but the method table is a plain Lua
-/// value — a caller can fish it out and misapply it).
+/// Run `f` over a frame's StatusBar state; errors on any other receiver, since the method table
+/// is a plain Lua value a caller can misapply.
 fn with_bar<T>(
     lua: &Lua,
     this: &Table,
@@ -44,8 +34,8 @@ fn with_bar<T>(
     }
 }
 
-/// Store a (clamped) value; returns `Some(new_value)` if it actually changed — the caller fires
-/// `OnValueChanged`. Degenerate range (`max <= min`) pins to `min` (zero-init members).
+/// Store the value clamped to the range, `Some` when it changed (the caller fires
+/// `OnValueChanged`); a degenerate range pins to `min`.
 fn store_value(sb: &mut StatusBarState, v: f32) -> Option<f32> {
     let clamped = v.clamp(sb.min, sb.max.max(sb.min));
     (clamped != sb.value).then(|| {
@@ -54,8 +44,8 @@ fn store_value(sb: &mut StatusBarState, v: f32) -> Option<f32> {
     })
 }
 
-/// Get-or-create the bar-fill texture region (`SetStatusBarTexture`/`<BarTexture>`); `layer`
-/// re-layers an existing bar. Returns the region's id (for wrapper lookup).
+/// Get or create the bar texture region, `ARTWORK` by default as in the reference; `layer`
+/// re-layers an existing one.
 fn ensure_bar(lua: &Lua, this: &Table, layer: Option<DrawLayer>) -> mlua::Result<u32> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -88,7 +78,7 @@ fn ensure_bar(lua: &Lua, this: &Table, layer: Option<DrawLayer>) -> mlua::Result
                 )
                 .ok_or_else(|| mlua::Error::runtime("stale frame handle"))?;
             model.region_data.insert(rh, RegionData::default());
-            model.touch_layout(); // a region entered the layout gate's read set (decision 0740)
+            model.touch_layout(); // a region entered the layout gate's read set
             if let Some(frame) = model.arena.frame_mut(h) {
                 if let KindState::StatusBar(sb) = &mut frame.kind_state {
                     sb.bar = Some(rh);
@@ -106,9 +96,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     m.set(
         "SetMinMaxValues",
         lua.create_function(|lua, (this, min, max): (Table, f32, f32)| {
-            // A reversed pair is swapped (RF-28's LoadXML does exactly this) — one behavior for the
-            // XML and API paths. The held value re-clamps into the new range; a move fires
-            // OnValueChanged, as a value change the caller didn't make explicitly is still a change.
+            // A reversed pair is swapped, as `LoadXML` does; the held value re-clamps, and a move
+            // fires `OnValueChanged`.
             let changed = with_bar(lua, &this, |sb| {
                 (sb.min, sb.max) = if min <= max { (min, max) } else { (max, min) };
                 store_value(sb, sb.value)
@@ -154,8 +143,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetStatusBarTexture(path [, drawLayer]) | SetStatusBarTexture(r, g, b [, a]) — the same two
-    // forms as a region's SetTexture, targeting the bar region (created on first use).
+    // A region's two `SetTexture` forms, `(path [, layer])` and `(r, g, b [, a])`, on the bar.
     m.set(
         "SetStatusBarTexture",
         lua.create_function(
@@ -176,9 +164,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         data.texture = Some(s.to_str()?.to_string());
                         data.fill = None;
                     }
-                    // A solid bar writes the same slot the path form does — each clears the other.
-                    // `SetStatusBarColor` is the TINT (the fill region's vertex colour) and is a
-                    // separate slot entirely: a bar can carry art AND a colour, and they multiply.
+                    // A solid fill and a path clear each other; `SetStatusBarColor` is a separate
+                    // tint that multiplies either.
                     Value::Number(_) | Value::Integer(_) => {
                         data.texture = None;
                         data.fill = Some([
@@ -211,12 +198,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // **Shape C on r, g, b** (`StatusBar:SetStatusBarColor `0x78fc20``, `2=C 3=C 4=C 5=B`, wow-re
-    // `numeric-arg-coercion-law.md`): a bare `lua_tonumber` with no `lua_isnumber` gate, so a nil,
-    // a table or a string is **0.0** and the call never raises. Taking them as `f32` made mlua's
-    // converter the gate instead — the 2176 class — and the stock
-    // `QuestLogFrame.lua:337` idiom hands three nils (`titleButton.r/g/b` are only assigned in
-    // `QuestLog_Update`) on any path that selects a quest-log entry before the window has painted.
+    // `0x78fc20` reads r, g, b by a bare `lua_tonumber`, so nil, a table or a non-numeric string
+    // is 0.0 and the call never raises (a numeric string also reads 0.0 here). Stock hands colour
+    // setters nils: `QuestLogFrame.lua:337` passes three to `SetVertexColor`.
     m.set(
         "SetStatusBarColor",
         lua.create_function(
@@ -252,8 +236,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Fire `OnValueChanged(self, value)` if `changed` carries the new value (RF-28: the StatusBar's own
-/// script slot `+0x32c`). Fired outside any model borrow; errors go to [`Model::errors`].
+/// Fire `OnValueChanged` (the StatusBar's script slot, `+0x32c`) for a changed value, outside any
+/// model borrow.
 fn fire_value_changed(lua: &Lua, this: &Table, changed: Option<f32>) -> mlua::Result<()> {
     let Some(value) = changed else { return Ok(()) };
     let id = {
@@ -269,20 +253,14 @@ fn fire_value_changed(lua: &Lua, this: &Table, changed: Option<f32>) -> mlua::Re
     ) {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
     Ok(())
 }
 
-/// `OnValueChanged` for a bar the ENGINE moved rather than Lua — the nameplate health bars, whose
-/// value the plate driver re-sets from the unit's descriptor each time it changes (decision 2148).
-///
-/// The reference fires the same script from the same place: the plate's bar is driven by a
-/// GUID-watch callback (`0x7cc570`, registered `0x467e70`) that re-reads health and re-sets the bar
-/// synchronously on every server update, and `SetValue` is `SetValue`. pfUI hooks this
-/// (`nameplates.lua:393` `HookScript(healthbar, "OnValueChanged", …)`) and reads `this:GetParent()`
-/// inside the handler, so a driver that moved the value silently would leave it blind.
+/// `OnValueChanged` for a bar the engine moved, the nameplate health bars: the reference re-sets
+/// them from a GUID-watch callback (`0x7cc570`, registered at `0x467e70`) on every server update,
+/// and that `SetValue` fires the script as any other does.
 pub(super) fn fire_engine_value_changed(lua: &Lua, bar: crate::widget::FrameHandle, value: f32) {
     let id = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -296,12 +274,10 @@ pub(super) fn fire_engine_value_changed(lua: &Lua, bar: crate::widget::FrameHand
     ) {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
 }
 
-/// A Lua number-ish → f32 (nil/other → 0.0), for the color-form arguments.
 fn num_f32(v: &Value) -> f32 {
     match v {
         Value::Number(n) => *n as f32,
diff --git a/crates/benilla-ui/src/script/stdlib.rs b/crates/benilla-ui/src/script/stdlib.rs
index 549d7400..86f5cb75 100644
--- a/crates/benilla-ui/src/script/stdlib.rs
+++ b/crates/benilla-ui/src/script/stdlib.rs
@@ -1,32 +1,18 @@
-//! The sandbox + the WoW stdlib layer — the global aliases and helpers FrameXML/addon Lua assumes
-//! exist on top of stock Lua 5.1 (decision 0068).
+//! The sandbox and the 1.12 stdlib layer on top of stock Lua 5.1.
 //!
-//! - **Sandbox** ([`sandbox`]): remove `io`/`os`/`package`/`require`/`dofile`/`loadfile`/`debug`
-//!   (keeping a `debugstack` stub returning `""`), and replace chunk loading with a **text-only**
-//!   `loadstring` (bytecode rejected). Decision 0068's threat model is "addon-observable behavior",
-//!   not anti-automation, but running untrusted addon Lua still means no filesystem/OS/native reach.
-//! - **Stdlib** ([`install`]): the nine bare-global aliases probe A found in the real corpus
-//!   (`format`/`strlen`/`gsub`/`strsub`/`strupper`/`tinsert`/`getn`/`tremove`/`strfind`), plus
-//!   `strlower`/`strrep`, `getglobal`/`setglobal`, and — the one non-trivial piece — a
-//!   `string.format` replacement
-//!   that supports Blizzard's positional `%N$` extension (probe A confirmed stock 5.1 rejects it).
-//!
-//! ## The positional `format` (`%N$`)
-//!
-//! Blizzard patched `string.format` to accept `printf`-style positional specs (`"%2$s %1$s"`) for
-//! localization. Stock Lua 5.1 does not (probe A, `semantics.rs` check (b)). We reimplement the
-//! reordering in Lua: scan the format, and if any spec carries `N$`, rewrite it into a plain
-//! sequential format with the arguments reordered, then delegate to the real `string.format`.
-//! **Mixing** positional and sequential specs in one string is an error — and it is in Blizzard's
-//! build too (their patch tracks a single "arg cursor" that a positional spec desyncs), so we match
-//! by erroring rather than guessing a blend. The wrapper is installed as both `string.format` and
-//! the bare global `format`.
+//! - [`sandbox`]: no filesystem, OS or native reach (`io`, `os`, `package`, `require`, `dofile`,
+//!   `loadfile`, `load`, `module`, `newproxy` and `debug` removed), the reference's `debugstack`,
+//!   and a text-only `loadstring`.
+//! - [`install`]: the 1.12 bare globals (string, table and math aliases, the `debug*` family, the
+//!   error-handler pair, the clock and zone getters), `time` and `date`, and a `string.format`
+//!   that accepts positional `%N$` specs as the 1.12 client's does, rewriting them into a
+//!   sequential format. Mixing positional and sequential specs raises, as in the reference,
+//!   whose single argument cursor a positional spec desyncs.
 
 use mlua::{Lua, Value, Variadic};
 
-/// The Lua-level message inside an mlua error — mlua decorates its `Display` with a category
-/// word (`syntax error: `, `runtime error: `) that the reference's own `lua_pushstring` leg never
-/// adds. `loadstring`'s second return is that message verbatim, so the decoration is stripped.
+/// An mlua error's bare Lua message, as `loadstring` returns it: without the `syntax error: ` or
+/// `runtime error: ` word mlua's `Display` adds and the reference never does.
 pub(super) fn lua_message(e: &mlua::Error) -> String {
     match e {
         mlua::Error::SyntaxError { message, .. } => message.clone(),
@@ -35,13 +21,12 @@ pub(super) fn lua_message(e: &mlua::Error) -> String {
     }
 }
 
-/// Sandbox the VM: strip filesystem/OS/native reach, keep a `debugstack` stub, and make chunk
-/// loading text-only.
+/// Sandbox the VM: no filesystem, OS or native reach, the reference's `debugstack`, and text-only
+/// chunk loading.
 pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // Remove the dangerous surface. (Some may already be absent under mlua's safe stdlib; setting
-    // nil is idempotent and makes the guarantee explicit rather than mlua-version-dependent.)
+    // Set to nil explicitly, whatever mlua's safe stdlib already leaves out.
     for name in [
         "io", "os", "package", "require", "dofile", "loadfile", "load", "module", "newproxy",
         "debug",
@@ -49,46 +34,12 @@ pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
         g.set(name, Value::Nil)?;
     }
 
-    // `debugstack([start [, count1 [, count2]]])` — the client's own traceback, **frames only**.
-    //
-    // The stub this replaced returned `""`, which was justified as "real addons only display it".
-    // False: the corpus PARSES it, three different ways, and every one of them reads the string's
-    // shape rather than its contents.
-    //
-    // **There is no `stack traceback:` header, and line 1 is the caller's frame** (decision 2121).
-    // mlua's `Lua::traceback` is `luaL_traceback`, which emits that header — and the header cost a
-    // whole addon family its saved variables. `AceDB-2.0:RegisterDB` (`AceDB-2.0.lua:742`) does
-    //
-    //     local addonName = string.gsub(debugstack(), ".-\n.-\\AddOns\\(.-)\\.*", "%1")
-    //
-    // — skip exactly ONE line (its own frame), read the folder out of the NEXT one (its caller's).
-    // With a header in front, the "next" line is AceDB's own chunk, so every Ace2 addon resolved to
-    // whichever addon happened to ship the winning copy of the library. `AceDB.addonsLoaded` has
-    // that one flagged already, so `RegisterDB` took its *immediate* branch and bound `db.raw` to a
-    // fresh table at the addon's FILE SCOPE — before the SavedVariables chunk runs. The chunk then
-    // rebound the global and `db.raw` kept pointing at the orphan, so Bartender2 printed
-    // `Creating new DB` at every login and its file was frozen at what a first-run reset writes.
-    // Measured live: `Bartender.db.raw == BarDB` was **false**.
-    //
-    // Two more corpus readers pin the same shape independently, and they are the reason this emits
-    // Lua 5.0's frame wording rather than 5.4's:
-    //   - `AceLibrary.lua:70` takes the FIRST line whole (`string.gsub(stack, "\n.*", "")`) and
-    //     matches it against `".*\\(.*).lua:%d+: .*"` — so line 1 is a frame, `<src>:<line>: …`,
-    //     with no leading newline and no header above it.
-    //   - `AceLibrary.lua:139`'s `argCheck` reads the function name with `"([`<].-['>])"` — a
-    //     BACKTICK or `<` opening it. 5.0 writes ``in function `name'``; 5.4 writes
-    //     `in function 'name'`, which that pattern cannot match at all.
-    //
-    // So the body is `db_errorfb`'s (Lua 5.0 `ldblib.c`) with its header line removed: per frame
-    // `short_src`, then `:line` when there is one, then one of ``  in function `name' ``,
-    // `" in main chunk"`, `" ?"` (a C function) or `" in function <src:linedefined>"`.
-    //
-    // `start` is the level to begin at, default 1 = the caller (level 0 is this binding itself).
-    // `count1`/`count2` are 5.0's `LEVELS1`/`LEVELS2`: show `count1` frames from the top, then
-    // `...`, then the last `count2`. They are honoured rather than ignored because
-    // `FuBarPlugin-2.0.lua:752` passes `debugstack(6, 1, 0)` and reads the capture with a GREEDY
-    // `"\\AddOns\\(.*)\\"` — extra frames would hand it the LAST addon on the stack instead
-    // of its own.
+    // debugstack([start [, count1 [, count2]]]): the reference's traceback, frames only, in Lua
+    // 5.0's wording. There is no `stack traceback:` header and line 1 is the caller's frame:
+    // `AceDB-2.0.lua:742` skips one line to read its caller's addon folder, and `AceLibrary.lua:70`
+    // reads line 1 as a frame. `AceLibrary.lua:139` needs 5.0's ``in function `name'`` quoting,
+    // not later Luas' `'name'`. `start` defaults to 1, the caller; `count1`/`count2` are 5.0's
+    // `LEVELS1`/`LEVELS2`, which `FuBarPlugin-2.0.lua:752` relies on with `debugstack(6, 1, 0)`.
     g.set(
         "debugstack",
         lua.create_function(|lua, args: Variadic<Value>| {
@@ -104,33 +55,16 @@ pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // Text-only `loadstring`: compile a *source* string (never bytecode). Returns `function` on
-    // success or `(nil, errmsg)` on failure — the stock `loadstring` contract. `set_mode(Text)`
-    // makes mlua reject a binary chunk (the `\27Lua` signature), the "loadstring of bytecode
-    // rejected" guarantee.
-    // The BOM strip and the `#`-line skip ride along, because in the reference they live *inside*
-    // `luaL_loadbuffer`/`luaX_setinput` — the same door `loadstring` goes through (decision 1193).
+    // Text-only `loadstring`: a binary chunk is rejected. The BOM strip and `#`-line skip apply,
+    // as in the reference they live inside `luaL_loadbuffer`/`luaX_setinput`.
     let loadstring = lua.create_function(
         |lua, (src, chunkname): (mlua::String, Option<mlua::String>)| {
             let raw = src.as_bytes();
             let bytes = crate::source::chunk(&raw).to_vec();
-            // **The chunk name is the caller's string VERBATIM, and it defaults to the SOURCE.**
-            // `luaB_loadstring 0x703280` is stock 5.0: `0x70329a` pushes `edi` — the pointer
-            // `luaL_checklstring` just returned — as `luaL_optlstring`'s `def`, so a nameless
-            // chunk is named by its own text and `luaO_chunkid 0x6f5c40` renders it by its third
-            // rule, `[string "…"]`, cut at the first newline and at the budget. There is no
-            // `.rdata` literal on that path at all (wow-5875-re `lua-dialect.md` §11, executed).
-            //
-            // We used to prepend `=`, which is `luaO_chunkid`'s "print this verbatim, undecorated"
-            // marker — so an explicit name lost its `[string "…"]` wrapper and a `@path` name kept
-            // a literal `@`, and a nameless chunk answered to `(loadstring)`, a literal the image
-            // does not contain. Both are player-visible: they are the prefix of every error a
-            // `loadstring` chunk raises.
-            //
-            // The name is taken from the **un-advanced** bytes on purpose: `luaL_loadbuffer
-            // 0x6f5690` strips a UTF-8 BOM from the buffer, but `0x703296` computed the name
-            // before that, so a BOM'd source compiles without its BOM while its chunk name still
-            // begins with one.
+            // The chunk name is the caller's string verbatim, defaulting to the source itself
+            // (`luaB_loadstring` `0x703280`, `0x70329a`), which `luaO_chunkid` `0x6f5c40` renders
+            // as `[string "…"]`. It comes from the raw bytes: `luaL_loadbuffer` `0x6f5690` strips
+            // a BOM only after `0x703296` took the name.
             let name = match &chunkname {
                 Some(n) => String::from_utf8_lossy(&n.as_bytes()).into_owned(),
                 None => String::from_utf8_lossy(&raw).into_owned(),
@@ -141,10 +75,8 @@ pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
                 .set_mode(mlua::ChunkMode::Text);
             match chunk.into_function() {
                 Ok(f) => Ok((Value::Function(f), Value::Nil)),
-                // `load_aux`'s failure leg pushes Lua's own message unchanged (`0x7032c6` nil,
-                // `0x7032d2` insert, `mov eax,2`). mlua's `Display` prefixes it with
-                // `syntax error: `, which is mlua's word and not the image's — an addon that shows
-                // the second return to a player would show that prefix too.
+                // The failure leg returns nil and Lua's own message, unprefixed (`0x7032c6`,
+                // `0x7032d2`).
                 Err(e) => Ok((
                     Value::Nil,
                     Value::String(lua.create_string(lua_message(&e))?),
@@ -157,12 +89,10 @@ pub(super) fn sandbox(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Install the WoW stdlib layer (the bare-global aliases, positional `format`, …).
+/// Install the stdlib layer: the bare globals, `time`/`date` and the positional `format`.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
-    // The default `geterrorhandler()` reports into the same channel a failed handler uses, so an
-    // addon's `geterrorhandler()(msg)` surfaces where every other script error does rather than
-    // vanishing (decision 1195). Named with the `__benilla_` prefix because it is host plumbing,
-    // not a 1.12 global — the reference's default handler is FrameXML's `_ERRORMESSAGE`.
+    // The default `geterrorhandler()` reports into the host's script-error channel; the
+    // `__benilla_` prefix marks host plumbing, not a 1.12 global.
     lua.globals().set(
         "__benilla_script_error",
         lua.create_function(|lua, msg: mlua::Value| {
@@ -183,21 +113,18 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         .set_name("=[benilla wow stdlib]")
         .set_mode(mlua::ChunkMode::Text)
         .exec()?;
-    // Remember the default handler BY IDENTITY, right after installing it — the engine-side
-    // dispatch (decision 1305) skips it (it reports into the host channel, where every dispatched
-    // message already is) and fires only a handler somebody *chose*: FrameXML's `_ERRORMESSAGE`
-    // or an addon's own.
+    // Kept by identity: dispatch skips the default handler, whose channel already has the
+    // message, and fires only one that FrameXML or an addon set.
     let default: mlua::Function = lua.load("return geterrorhandler()").eval()?;
     lua.set_named_registry_value(super::REG_DEFAULT_ERRORHANDLER, default)?;
     Ok(())
 }
 
-/// The stdlib layer, in Lua. One place, so each alias is the one-liner the task calls for and the
-/// `format` logic is readable. Runs once at construction.
+/// The stdlib layer in Lua, run once at construction.
 const WOW_STDLIB: &str = r#"
 -- ── the bare string family ─────────────────────────────────────────────────────────────────────
 -- Every name here is present in the REAL 1.12 client's global table — the in-world `_G` captured
--- from the running reference client (wow-5875-re's item-13 fixture, 19,572 entries), which is the
+-- from the running reference client (19,572 entries), which is the
 -- authority this file now answers to (decision 1189).
 --
 -- 1187 also installed `strmatch`, `strrev`, `gmatch`, `strlenutf8` and `strcmputf8i` from
@@ -265,7 +192,7 @@ ldexp = math.ldexp
 
 -- ── the debug* family: six verified STUBS and two real ones ────────────────────────────────────
 --
--- wow-re carved all eight (`system/ui/scratch/lua-dialect.md` §3a, and the 2026-08-11 batch):
+-- All eight, read at the bytes (`0x7027e0`..`0x702860`):
 -- `debuginfo`, `debugload`, `debugprint`, `debugdump`, `debugbreak` and `debugtimestamp` are
 -- **byte-identical `xor eax,eax; ret` stubs** — three bytes, no `call`, no memory write. They
 -- cannot print, log, write or set a global, and they return ZERO Lua values. So these are not
@@ -308,7 +235,7 @@ do
     function geterrorhandler() return handler end
 end
 
--- ── _G accessors (RF-0023 getglobal/setglobal: _G[name] get/set) ───────────────────────────────
+-- ── _G accessors (getglobal/setglobal: _G[name] get/set) ───────────────────────────────
 function getglobal(name) return _G[name] end
 function setglobal(name, value) _G[name] = value end
 
@@ -322,8 +249,8 @@ function GetLocale() return "enUS" end
 __benilla_now = 0.0
 function GetTime() return __benilla_now end
 
--- ── The zone-text family (decisions 0203 phase 1 + 0287, byte-pinned by its fold-back; wow-re
--- ui zonetext-pvpinfo.md). The app pushes the host globals on an area change (the same shape as
+-- ── The zone-text family (decisions 0203 phase 1 + 0287).
+-- The app pushes the host globals on an area change (the same shape as
 -- GetTime) and fires MINIMAP_ZONE_CHANGED / the ZONE_CHANGED family; these getters just read the
 -- cached slots, like the real bindings (0x48a0a0/c0/e0/100 read BSS caches). GetZoneText = the
 -- zone name, replaced by the WMO interior's name indoors; GetRealZoneText = the WMO-immune zone
@@ -446,21 +373,12 @@ do
 end
 "#;
 
-/// `time()` and `date([format [, when]])` — engine globals in the 1.12 client's own `_G`, slots 34
-/// and 33 of its base registry (`0x7035a0` / `0x7033a0`, wow-re `lua-dialect.md`).
+/// `time()` and `date([format [, when]])`: 1.12 engine globals (`0x7035a0`, `0x7033a0`), Lua 5.0's
+/// `os.time`/`os.date` hoisted. `time` is wall-clock epoch seconds, as addons persist it across
+/// sessions.
 ///
-/// They are Lua 5.0's `os.time`/`os.date` hoisted to globals, and we lacked both because the
-/// sandbox strips `os` wholesale. `time` was the top name in the session-start
-/// `attempt to call global` row (6 addons); `date` is a handful more. Every corpus `time()` site is
-/// the same shape — an epoch stamp persisted into SavedVariables and compared across sessions
-/// (`FTC_Save[k].LastCheck = time()`) — so it has to be real wall-clock seconds, not a
-/// session-relative clock like `GetTime`.
-///
-/// **UTC, and that is a stated divergence.** `os.date` uses LOCAL time and this uses UTC, because
-/// resolving a local offset needs a timezone database and this tree has no date dependency at all
-/// (deliberately — the format crates here are all in-repo). The corpus's uses are a debug
-/// timestamp, a "last scanned" string, and `%M:%S` over a DURATION; only the first two shift, and
-/// they shift by a constant. Fixing it means a tz source, not a different algorithm.
+/// Deviation: `date` formats UTC where the reference uses local time, because the tree has no
+/// timezone database.
 fn install_time(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
     g.set(
@@ -470,23 +388,13 @@ fn install_time(lua: &Lua) -> mlua::Result<()> {
     g.set(
         "date",
         lua.create_function(|lua, (fmt, when): (Option<String>, Option<i64>)| {
-            // Bare `date()` is `%c`, as in Lua — `Recap.lua:2690` calls it with no arguments.
+            // Bare `date()` is `%c`, as in Lua.
             let fmt = fmt.unwrap_or_else(|| "%c".to_string());
             let secs = when.unwrap_or_else(crate::civil::unix_seconds);
-            // A leading `!` selects UTC. Every timestamp this engine holds is already UTC — there
-            // is no local-time conversion anywhere here — so the flag only has to be CONSUMED, not
-            // acted on. Left in the format string it would print as a literal `!`.
+            // A leading `!` selects UTC, which every time here already is, so it is only consumed.
             let body = fmt.strip_prefix('!').unwrap_or(&fmt);
-            // `date("*t")` returns a TABLE, not a string, and leaving it unimplemented was not a
-            // missing feature — it was a HANG. `Accountant_WeekStart` walks a day at a time until
-            // the weekday matches its stored `weekstart`:
-            //
-            //     dt = date("*t", ct); thisDay = dt["wday"]
-            //     while thisDay ~= …weekstart do ct = ct - 86400; … end
-            //
-            // Against a string return, `dt["wday"]` is nil, `nil ~= 3` forever, and the addon spins
-            // the client — which is exactly what it did to the survey the moment a separate fix let
-            // Accountant reach this function at all.
+            // `*t` answers a table, as in Lua: an addon that loops until its `wday` matches
+            // (`Accountant_WeekStart`) spins forever on anything else.
             if body == "*t" {
                 let c = crate::civil::from_unix(secs);
                 let t = lua.create_table()?;
@@ -496,12 +404,11 @@ fn install_time(lua: &Lua) -> mlua::Result<()> {
                 t.set("hour", c.hour)?;
                 t.set("min", c.min)?;
                 t.set("sec", c.sec)?;
-                // Lua counts weekdays 1..7 from SUNDAY; ours is the 0-based index into `DAYS`.
+                // Lua counts weekdays 1..7 from Sunday; ours is the 0-based index into `DAYS`.
                 t.set("wday", c.weekday + 1)?;
-                // `yday` is already 1-based out of the conversion, which is Lua's convention too.
+                // Already 1-based, as in Lua.
                 t.set("yday", c.yearday)?;
-                // No timezone and no DST rules here, and `false` is the honest answer rather than
-                // the nil an absent field would give: this clock never observes daylight saving.
+                // UTC has no daylight saving.
                 t.set("isdst", false)?;
                 return Ok(mlua::Value::Table(t));
             }
@@ -537,12 +444,7 @@ const MONTHS: [&str; 12] = [
     "December",
 ];
 
-/// The `strftime` subset the corpus actually uses, plus the obvious neighbours.
-///
-/// Bounded on purpose: the specifiers here are the ones read off real call sites —
-/// `%H:%M:%S` (AceDebug), `%A, %B %d, %Y - %H:%M` (FuBar_PotHerbFu), `%M:%S` (FuBar_AnkhTimerFu),
-/// `%c` (bare `date()`). An unknown specifier is emitted VERBATIM rather than swallowed, so a
-/// format this does not know shows up in the output instead of silently vanishing.
+/// The `strftime` subset addons use; an unknown specifier is emitted verbatim.
 fn format_epoch(secs: i64, fmt: &str) -> String {
     let crate::civil::Civil {
         year,
@@ -598,7 +500,6 @@ fn format_epoch(secs: i64, fmt: &str) -> String {
             'y' => out.push_str(&format!("{:02}", year.rem_euclid(100))),
             'Y' => out.push_str(&format!("{year}")),
             '%' => out.push('%'),
-            // Unknown: verbatim, so it is visible rather than swallowed.
             other => {
                 out.push('%');
                 out.push(other);
@@ -607,16 +508,9 @@ fn format_epoch(secs: i64, fmt: &str) -> String {
     }
     out
 }
-/// `luaO_chunkid` (`0x6f5c40`), the reference's own — because `debugstack`'s frames carry
-/// `short_src`, and **it truncates from the FRONT** (decision 2121, wow-re
-/// `system/ui/scratch/debugstack-return-shape.md`).
-///
-/// An `@`-named chunk longer than [`CHUNKID_KEEP`] characters after the `@` becomes `"..."` plus
-/// its LAST [`CHUNKID_KEEP`], so the head of the path is what is lost. That is not a detail: over a
-/// 2189-file vanilla corpus, 60% of addon `.lua` chunk names truncate and **38% lose `\AddOns\`
-/// entirely**, which is exactly the substring three different corpus libraries search for. A client
-/// that keeps the whole name matches at a different frame than the reference for a third of library
-/// frames — silently, and in the addon's favour, which is worse than failing the same way.
+/// `luaO_chunkid` (`0x6f5c40`), for `debugstack`'s `short_src`. An `@` name longer than
+/// [`CHUNKID_KEEP`] keeps only its tail behind `"..."`, so a long addon path loses the `\AddOns\`
+/// that corpus libraries search for.
 fn chunk_id(source: &str) -> String {
     if let Some(rest) = source.strip_prefix('=') {
         // A `=name` chunk is taken verbatim, clipped to the buffer from the front.
@@ -641,24 +535,19 @@ fn chunk_id(source: &str) -> String {
     }
 }
 
-/// `LUA_IDSIZE` — the `short_src` buffer, 60 bytes including the terminator.
+/// `LUA_IDSIZE`: the `short_src` buffer, 60 bytes with the terminator.
 const LUA_IDSIZE: usize = 60;
 
-/// How many characters of an `@`-named chunk survive truncation, tail-first: the reference keeps
-/// the last 52 behind a `"..."` (wow-re's measurement off `0x6f5c40`).
+/// Characters an `@` name keeps, tail-first, behind `"..."` (`0x6f5c40`).
 const CHUNKID_KEEP: usize = 52;
 
 /// What `[string "…"]` costs the budget in the third `luaO_chunkid` arm.
 const STRING_CHUNK_OVERHEAD: usize = 17;
 
-/// One `debugstack` frame, in the reference's own wording (decision 2121):
-/// `short_src ":" [currentline ":"] DESC`, with the `\n` pushed **after** it by the caller.
-///
-/// `DESC` is the `*namewhat` switch at `0x7038fa`: a `f`/`g`/`l`/`m` name renders
-/// `` in function `%s' `` (`0x872c98`) — Lua **5.0**'s backtick quoting, which is what
-/// `AceLibrary.lua:139`'s `"([`<].-['>])"` needs and what 5.4's `'%s'` cannot satisfy — and
-/// otherwise the `*what` arms decide: `m` → `" in main chunk"` (`0x872c88`), `C` or `t` → `" ?"`
-/// (`0x872c6c`), else `" in function <%s:%d>"` (`0x872c70`).
+/// One `debugstack` frame, `short_src ":" [currentline ":"] DESC`, the caller pushing its `\n`.
+/// DESC (`0x7038fa`) is `` in function `%s' `` for a named frame (`0x872c98`), else by `what`:
+/// `" in main chunk"` (`0x872c88`), `" ?"` for C or a tail call (`0x872c6c`), or
+/// `" in function <%s:%d>"` (`0x872c70`).
 fn traceback_frame(d: &mlua::Debug) -> String {
     let src = d.source();
     let names = d.names();
@@ -675,9 +564,8 @@ fn traceback_frame(d: &mlua::Debug) -> String {
         line.push_str(&n.to_string());
         line.push(':');
     }
-    // A tail call has no calling instruction to name it from. 5.0 gave that frame `what == "tail"`
-    // and the `" ?"` arm; 5.4 hands us a `(tail call)` pseudo-frame instead, which lands in the
-    // same arm by the same rule.
+    // A tail call has nothing to name it from and takes the `" ?"` arm, known by its `what` or as
+    // the `(tail call)` pseudo-frame.
     let tail_call = src.what == "t" || short == "(tail call)";
     match names.name.as_deref() {
         Some(name) if !name.is_empty() && !tail_call => {
@@ -698,18 +586,11 @@ fn traceback_frame(d: &mlua::Debug) -> String {
     line
 }
 
-/// `debugstack`'s body — `0x703760`'s walk, which is stock Lua 5.0's `db_errorfb` with its header
-/// and its `"\n\t"` prefix replaced by a `"\n"` pushed **after** each frame (`0x703971`). That one
-/// substitution is the whole difference in shape, and it is why line 1 is a frame and why
-/// `AceDB-2.0`'s skip-one-line lands on its caller (decision 2121).
-///
-/// **`count1` bounds nothing on its own.** The loop formats while the level is `<= start + count1`
-/// (`0x703857` is `jbe`, unsigned ≤), and past that it probes `getstack(level + count2)`: a probe
-/// that FAILS steps back and prints that level as an ordinary frame, so `count1 = 1` returns *two*
-/// frames on a two-deep stack and one frame plus `"...\n"` on a three-deep one. Clamping to
-/// `count1` instead would diverge from the reference at exactly `depth == count1 + 1` — which is
-/// `FuBarPlugin-2.0.lua:752`'s `debugstack(6, 1, 0)`, whose greedy `"\\AddOns\\(.*)\\"` reads the
-/// LAST path in the string. wow-re `debugstack-return-shape.md` maps the whole regime.
+/// `debugstack`'s walk (`0x703760`): Lua 5.0's `db_errorfb` without its header, each frame
+/// followed by `"\n"` (`0x703971`) rather than preceded by `"\n\t"`, so line 1 is a frame.
+/// Frames print while the level is `<= start + count1` (`0x703857`, `jbe`); then a failed
+/// `getstack(level + count2)` probe prints that level as an ordinary frame, else `"...\n"` and
+/// the last `count2` follow. So `count1 = 1` gives two frames on a two-deep stack, not one.
 fn traceback_frames(lua: &Lua, start: usize, count1: usize, count2: usize) -> String {
     let mut out = String::new();
     let mut level = start;
@@ -719,7 +600,7 @@ fn traceback_frames(lua: &Lua, start: usize, count1: usize, count2: usize) -> St
         if level > start + count1 && first_part {
             first_part = false;
             if lua.inspect_stack(level + count2, |_| ()).is_none() {
-                level -= 1; // the probe found nothing to elide — print this level after all
+                level -= 1; // nothing to elide: print this level after all
             } else {
                 out.push_str("...\n");
                 while lua.inspect_stack(level + count2, |_| ()).is_some() {
@@ -740,15 +621,12 @@ fn traceback_frames(lua: &Lua, start: usize, count1: usize, count2: usize) -> St
 mod date_table_tests {
     use crate::script::UiScript;
 
-    /// **`date("*t")` returns a TABLE, and the reason this test exists is that its absence HUNG the
-    /// client.** `Accountant_WeekStart` (`Accountant.lua:364-375`) walks backwards a day at a time
-    /// until the weekday matches its stored `weekstart`; with a string return `dt["wday"]` is nil,
-    /// `nil ~= 3` never becomes false, and the loop never ends.
+    /// `Accountant.lua:364-375` steps back a day until `date("*t", ct).wday` matches, which a
+    /// string return never does.
     #[test]
     fn date_star_t_answers_a_table_that_walks_with_its_argument() {
         let s = UiScript::new().unwrap();
-        // 2026-08-12 00:00:00 UTC is a Wednesday. Lua counts wday from SUNDAY = 1, so Wednesday
-        // is 4 — the off-by-one a 0-based weekday index would get wrong.
+        // A Wednesday at 00:00 UTC: wday 4, counting from Sunday = 1.
         let t: i64 = 1_786_492_800;
         assert_eq!(
             s.eval::<(i64, i64, i64, i64, bool)>(&format!(
@@ -757,7 +635,6 @@ mod date_table_tests {
             .unwrap(),
             (2026, 8, 12, 4, false)
         );
-        // hour/min/sec and yday come through too — an addon reading any of them must not get nil.
         assert_eq!(
             s.eval::<(i64, i64, i64, i64)>(&format!(
                 "local d = date(\"*t\", {t} + 3661) return d.hour, d.min, d.sec, d.yday"
@@ -766,8 +643,7 @@ mod date_table_tests {
             (1, 1, 1, 224)
         );
 
-        // **The loop Accountant actually runs.** Stepping back a day must move `wday`, and the walk
-        // must terminate — this is the hang, expressed as the addon expresses it.
+        // Accountant's loop: one step back from Wednesday reaches Tuesday.
         assert_eq!(
             s.eval::<i64>(&format!(
                 "local ct = {t} local n = 0 \
@@ -779,8 +655,7 @@ mod date_table_tests {
             "Wednesday(4) back to Tuesday(3) is exactly one step; a constant wday would spin"
         );
 
-        // A `!` prefix selects UTC, which every timestamp here already is — it must be CONSUMED
-        // rather than printed, and it works on the table form as well as the string form.
+        // `!` is consumed, in the table form and the string form.
         assert_eq!(
             s.eval::<i64>(&format!("return date(\"!*t\", {t}).wday"))
                 .unwrap(),
@@ -792,7 +667,6 @@ mod date_table_tests {
                 .contains('!'),
             "the UTC flag is consumed, not printed"
         );
-        // …and an ordinary format still answers a string.
         assert_eq!(
             s.eval::<String>(&format!("return date(\"%A\", {t})"))
                 .unwrap(),
diff --git a/crates/benilla-ui/src/script/summon.rs b/crates/benilla-ui/src/script/summon.rs
index 8c6d48bf..b3fe993b 100644
--- a/crates/benilla-ui/src/script/summon.rs
+++ b/crates/benilla-ui/src/script/summon.rs
@@ -1,53 +1,27 @@
-//! The player-summon **Era API surface** (decision 1747) — four globals, one snapshot.
-//!
-//! These are the whole Lua side of being summoned, and they exist because the reference's
-//! `CONFIRM_SUMMON` dialog is written against exactly them (`StaticPopup.lua:1336-1357` +
-//! `UIParent.lua:551-552`): the `CONFIRM_SUMMON` event raises the dialog with **no arguments at
-//! all**, `OnShow` seeds its countdown from [`GetSummonConfirmTimeLeft`], the popup engine's
-//! per-tick text re-reads [`GetSummonConfirmSummoner`] and [`GetSummonConfirmAreaName`], and
-//! `OnAccept` calls [`ConfirmSummon`]. `reference/1.12-globals.tsv` lists all four as
-//! `function`/`engine`, and there is **no fifth**: 1.12 has no `CancelSummon`, because declining
-//! sends no packet.
-//!
-//! **Why the three getters read a pushed snapshot rather than arguments.** The reference keeps the
-//! request in four engine globals — `[0xb4e358]/[0xb4e35c]` the summoner guid, `[0xb4e354]` the
-//! zone id, `[0xb4e350]` the deadline — and each getter resolves *at call time*: the summoner
-//! through the name cache (`DBCache::NameCache::GetRecord 0x55f080`, `""` on a miss), the area
-//! through `AreaTable.dbc` (`""` when the row is missing), the time left as
-//! `(deadline − now) / 1000`. Both resolves need host state this crate does not have, so the app
-//! does them and pushes the answers every frame ([`super::UiScript::set_summon_confirm`]). The
-//! observable is identical, including the one that matters: a summoner whose name has not arrived
-//! yet renders `""` and then fills itself in on a later tick, because the dialog re-reads the
-//! getter every OnUpdate.
-//!
-//! `ConfirmSummon()` takes no arguments and queues only a count, [`super::binder`]'s shape and for
-//! its reason: the app holds the guid that goes on the wire.
+//! The four summon globals the `CONFIRM_SUMMON` dialog calls (`StaticPopup.lua:1336-1357`); 1.12
+//! has no `CancelSummon`, as declining sends nothing. The reference resolves the summoner
+//! (`0xb4e358`), zone (`0xb4e354`) and deadline (`0xb4e350`) at call time; the app pushes the
+//! answers each frame, so a name still in flight reads `""` and fills in on a later tick.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// The `CONFIRM_SUMMON` dialog's three reads, resolved by the app and pushed each frame.
-///
-/// All three are the *reference's* fallbacks when nothing is pending or nothing resolves — two
-/// empty strings and a zero — because every one of its getters pushes a value on every path
-/// (`""` is the shared static `0x882748`; the time-left reader returns 0 for a zeroed deadline).
-/// Nothing here is ever nil, which is what lets the dialog's `format` run unguarded.
+/// The dialog's three reads, never nil: with nothing pending or resolved they are `""`, `""` and
+/// 0, as the reference's getters answer (`0x882748` is its shared `""`).
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct SummonConfirmUiState {
-    /// The summoner's resolved name, or `""` while the name query is still out.
+    /// The summoner's name from the name cache (`0x55f080`), `""` while the query is out.
     pub summoner: String,
     /// The summoner's zone name out of `AreaTable.dbc`, or `""` if the id names no row.
     pub area: String,
-    /// Milliseconds left before the offer expires — `0` when nothing is pending or the window has
-    /// already run out. **Milliseconds, not seconds**, because the reference's truncation to whole
-    /// seconds happens inside the binding (`0x48b660`'s `/1000`), and that is where it happens
-    /// here too: the floor is part of the API's contract, not part of the host's bookkeeping.
+    /// Milliseconds left, 0 when nothing is pending or it ran out; the binding truncates to
+    /// seconds, as `0x48b660` does.
     pub time_left_ms: u32,
 }
 
 impl super::UiScript {
-    /// Push the summon question's three resolved reads (the app's per-frame feed).
+    /// Push the three resolved reads, each frame.
     pub fn set_summon_confirm(&mut self, state: SummonConfirmUiState) {
         let mut model = self.model_mut();
         if model.summon_confirm != state {
@@ -55,19 +29,16 @@ impl super::UiScript {
         }
     }
 
-    /// Drain the `ConfirmSummon()` calls queued since the last drain — each one is a
-    /// `CMSG_SUMMON_RESPONSE`. [`Self::take_binder_confirms`]'s shape, and a count for the same
-    /// reason: the intent has no payload of its own.
+    /// Drain the `ConfirmSummon()` calls, each a `CMSG_SUMMON_RESPONSE`.
     pub fn take_summon_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().summon_confirms)
     }
 }
 
-/// Register the four summon globals (the style [`super::binder`] registers its two).
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetSummonConfirmSummoner() — who is summoning you (`0x48b6a0`). A string on every path.
+    // `0x48b6a0`: a string on every path.
     g.set(
         "GetSummonConfirmSummoner",
         lua.create_function(|lua, ()| {
@@ -76,9 +47,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSummonConfirmAreaName() — where to (`0x48b720`). The **summoner's** zone, straight out of
-    // `AreaTable.dbc` with no parent walk and no GlobalString tail: unlike the innkeeper question's
-    // three-step chain (`0x5dfe5e`), an id this table cannot name renders as `""`.
+    // `0x48b720`: the summoner's zone straight from `AreaTable.dbc`, with no parent walk and no
+    // GlobalString fallback, unlike the innkeeper question's chain (`0x5dfe5e`).
     g.set(
         "GetSummonConfirmAreaName",
         lua.create_function(|lua, ()| {
@@ -87,10 +57,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetSummonConfirmTimeLeft() — whole SECONDS left, truncated (`0x48b660`: the `0x10624dd3`
-    // magic multiply is an integer `/1000` over the millisecond remainder, then `lua_pushnumber`).
-    // The dialog seeds `this.timeleft` from it in OnShow and the popup engine counts down locally
-    // from there, so the floor lands once, at open.
+    // Whole seconds, truncated (`0x48b660`); the dialog reads it once in `OnShow` and counts down
+    // locally from there.
     g.set(
         "GetSummonConfirmTimeLeft",
         lua.create_function(|lua, ()| {
@@ -99,7 +67,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmSummon() — the CONFIRM_SUMMON dialog's Accept, and the only packet in the whole flow.
+    // The dialog's Accept, the only packet in the flow.
     g.set(
         "ConfirmSummon",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/surface.rs b/crates/benilla-ui/src/script/surface.rs
index 746dfeb8..a6e4ae9f 100644
--- a/crates/benilla-ui/src/script/surface.rs
+++ b/crates/benilla-ui/src/script/surface.rs
@@ -1,36 +1,16 @@
-//! **benilla's widget METHOD surface, asked of a running VM** — the shared measurement behind
-//! the `dump_widget_methods` example and the widget-surface gate
-//! (`script::tests::widget_surface`, decision 2142).
-//!
-//! It exists for the same reason `dump_globals` does (decisions 1188, 1189): **it is a run, not a
-//! grep**. `_G` is not the whole surface an addon can tell apart — most of what an addon touches
-//! is reached through a *widget*, and an addon's test for "does this client have X" is
-//! `if frame.SetBackdrop then`, i.e. what the `__index` chain answers on a live instance. A regex
-//! over `m.set("Name", …)` cannot answer that: it cannot see which registry table a kind actually
-//! chains to, it cannot see the Texture/FontString leaf split ([`super::region`]), and it reads a
-//! name registered under a `format!` family as one method.
-//!
-//! So every row is one live object being asked `type(obj.Name) == "function"`, exactly as an addon
-//! asks it. The only thing **not** asked of the VM is the *candidate name list* — a metatable whose
-//! `__index` is a Rust dispatcher is not enumerable from Lua, so the candidates are the union of
-//! the keys of the VM's own method tables ([`METHOD_TABLES`]), read out of the Lua registry at
-//! runtime rather than out of the source. A key that no longer resolves to a table is a hard error
-//! rather than a silent loss of candidates: a quietly-missing candidate source would under-report
-//! the surface, which is the exact failure this measurement exists to prevent.
+//! benilla's widget method surface asked of a running VM, shared by the `dump_widget_methods`
+//! example and the widget-surface gate (`script::tests::widget_surface`). Each row is a live
+//! instance asked `type(obj.Name) == "function"`, as an addon asks it; only the candidate names
+//! come from elsewhere, the keys of the VM's method tables ([`METHOD_TABLES`]), since a Rust
+//! `__index` dispatcher cannot be enumerated from Lua.
 use std::collections::BTreeSet;
 
 use mlua::{Table, Value};
 
 use super::UiScript;
 
-/// The named-registry method tables the VM installs — the **candidate name source**, read from the
-/// live registry.
-///
-/// This is not the class chain (the chain is `object::kind_method_registries`' business and this
-/// instrument deliberately does not model it — it asks the instance instead). It is only the
-/// universe of names worth probing: every name benilla registers on any widget appears as a key in
-/// one of these, so the union is a superset of our surface and the per-instance probe decides
-/// membership.
+/// The VM's named-registry method tables: every widget method benilla registers is a key in one,
+/// and the per-instance probe decides which a class answers.
 const METHOD_TABLES: &[&str] = &[
     "__benilla_frame_methods",
     "__benilla_region_methods",
@@ -57,14 +37,9 @@ const METHOD_TABLES: &[&str] = &[
     "__benilla_tooltip_methods",
 ];
 
-/// Every widget/region/font class benilla can hand an addon, and one Lua expression that makes one.
-///
-/// **Ordered, and the order is load-bearing**: the region and font rows are made *by* the plain
-/// frame the first row creates, so `Frame` comes first. Each instance is published as the global
-/// `DW_<Class>`; the frame kinds also publish their own `CreateFrame` name, which is harmless.
-///
-/// `TaxiRouteFrame` is absent on purpose — it is a registered `CreateFrame` type that *is* a
-/// `Frame` and nothing else (decision 1828), so it would be the `Frame` row twice.
+/// Every class benilla can hand an addon, with a Lua expression making one, published as
+/// `DW_<Class>`. `Frame` must come first: the region and font rows are made by it.
+/// `TaxiRouteFrame` is left out, being a plain `Frame` to Lua.
 const CLASSES: &[(&str, &str)] = &[
     ("Frame", r#"CreateFrame("Frame", "DWFrameN", UIParent)"#),
     (
@@ -137,12 +112,8 @@ const CLASSES: &[(&str, &str)] = &[
     ("Font", r#"CreateFont("DWFontN")"#),
 ];
 
-/// Every `(class, method)` pair this VM answers — one live instance per class, probed with the
-/// membership test an addon writes.
-///
-/// **A class that cannot be instantiated is REPORTED, never skipped**: its row is
-/// `(class, "!NOT-INSTANTIABLE")`. A census that silently drops a class reads as "that class has
-/// no methods", which is the wrong answer to a different question.
+/// Every `(class, method)` pair this VM answers, one live instance per class. A class that cannot
+/// be made reports `(class, "!NOT-INSTANTIABLE")` rather than dropping out.
 pub fn widget_method_census(script: &UiScript) -> mlua::Result<Vec<(String, String)>> {
     let mut candidates: BTreeSet<String> = BTreeSet::new();
     for key in METHOD_TABLES {
diff --git a/crates/benilla-ui/src/script/tabard.rs b/crates/benilla-ui/src/script/tabard.rs
index 5c3fcfc8..9c9a3116 100644
--- a/crates/benilla-ui/src/script/tabard.rs
+++ b/crates/benilla-ui/src/script/tabard.rs
@@ -1,23 +1,7 @@
-//! The guild tabard designer's engine surface (decision 1977; wow-re
-//! `system/ui/scratch/tabard-designer.md`, VERIFIED at the bytes unless marked): the
-//! `TabardModel` kind's own method table (`0x84ee40`, ten verbs) and the window's two globals.
-//!
-//! **The designer's whole state is five ints on the frame** — emblem style, emblem colour,
-//! border style, border colour, background colour — bounded by a `.rdata` constant table
-//! (`0x808220`: 170 · 17 · 6 · 17 · 51) that no DBC feeds. A `TabardModel` is well-defined only
-//! once `InitializeTabardColors()` has run: the constructor writes nothing.
-//!
-//! **What is the app's.** The guild record the seed reads and the save-in-flight latch
-//! `CanSaveTabardNow` tests are pushed by the app ([`TabardHost`]); `Save()` and
-//! `CloseTabardCreation()` queue [`TabardIntent`]s the app drains — the fourteen pre-flight checks
-//! of the save (`0x5e03f0`) need the purse, the guild rank and the interaction target, none of
-//! which this crate holds. The two `…EmblemTexture(texture)` methods are **setters**: the reference
-//! decodes the emblem BLP and installs a white-carrying-its-alpha 128×64 / 128×32 texture into the
-//! passed Texture widget. Here they set the region's texture to an [`EMBLEM_MASK_TOKEN`] path the
-//! app resolves to exactly that image (`ui_script::extract`).
-//!
-//! `GetTabardCreationCost()` is a **hard-coded constant**: `0x6d6de0` is `mov eax,0x186a0; ret`
-//! — 100 000 copper, ten gold, no `.data` cell and no server input.
+//! The guild tabard designer: the `TabardModel` method table (`0x84ee40`) and the window's two
+//! globals. Its state is five ints on the frame, which the constructor leaves unwritten until
+//! `InitializeTabardColors()` seeds them; the app pushes the guild record and save latch and runs
+//! the save's fourteen checks (`0x5e03f0`).
 
 use mlua::{Lua, Value};
 
@@ -27,21 +11,18 @@ use super::region::region_handle_of;
 use super::Model;
 use crate::widget::{FrameHandle, FrameKind, RegionKind};
 
-/// Registry key of the TabardModel method table — probed before PlayerModel's and Model's
-/// (`object.rs`'s kind chain).
+/// Registry key of the TabardModel method table, probed before PlayerModel's and Model's.
 pub(super) const REG_TABARDMODEL_METHODS: &str = "__benilla_tabardmodel_methods";
 
-/// `0x6d6de0`: the designer's price, in copper.
+/// The designer's price in copper, a constant in the reference (`0x6d6de0`).
 pub const TABARD_CREATION_COST: u32 = 100_000;
 
-/// `0x808220`, the five slot counts in `CycleVariation` order: emblem style, emblem colour, border
-/// style, border colour, background colour. A constant — the client consults no DBC.
+/// The five slot counts in `CycleVariation` order (emblem style and colour, border style and
+/// colour, background colour): the reference's constant table at `0x808220`, not a DBC.
 pub const TABARD_COUNTS: [i32; 5] = [170, 17, 6, 17, 51];
 
-/// The token a Texture region carries after `Get{Upper,Lower}EmblemTexture(texture)`: the prefix
-/// plus the emblem path (`Textures\GuildEmblems\Emblem_%02d_%02d_T{U,L}_U`). The app draws
-/// it as the reference's generated image — white RGB carrying the emblem's own alpha, a tintable
-/// mask (`0x503431`: `(a << 24) | 0x00FFFFFF`).
+/// The prefix a Texture carries before the emblem path after `Get{Upper,Lower}EmblemTexture`; the
+/// app draws the reference's generated mask, white carrying the emblem's alpha (`0x503431`).
 pub const EMBLEM_MASK_TOKEN: &str = "benilla:emblem-mask:";
 
 /// The BLP path inside an [`EMBLEM_MASK_TOKEN`] texture, or `None` for an ordinary path.
@@ -49,21 +30,19 @@ pub fn emblem_mask_path(texture: &str) -> Option<&str> {
     texture.strip_prefix(EMBLEM_MASK_TOKEN)
 }
 
-/// What the app pushes for the designer's two host-side facts.
+/// The designer's two host-side facts, pushed by the app.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
 pub struct TabardHost {
-    /// The local player's guild record as the DBCache holds it — `Some` once cached (its five
-    /// emblem fields, `-1` each for an undesigned tabard), `None` while it has not arrived or the
-    /// player has no guild.
+    /// The cached guild record's emblem fields, `-1` each when undesigned; `None` until cached.
     pub guild_record: Option<[i32; 5]>,
-    /// `[0xc4d780]`, the save-in-flight latch: set when the save is sent, cleared by the reply.
+    /// The save-in-flight latch (`0xc4d780`): set when the save is sent, cleared by the reply.
     pub save_pending: bool,
 }
 
 /// What the designer asks the app to do.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum TabardIntent {
-    /// `TabardModel:Save()` — the five values, for the fourteen pre-flight checks and the send.
+    /// `Save()`: the five values, for the checks and the send.
     Save([i32; 5]),
     /// `CloseTabardCreation()`.
     Close,
@@ -75,8 +54,7 @@ impl super::UiScript {
         self.model_mut().tabard_host = host;
     }
 
-    /// The designer's current five values — the preview the app dresses the player's body in
-    /// while the frame is up — or `None` before `InitializeTabardColors()` has seeded them.
+    /// The design the app previews on the player's body, `None` before the seed.
     pub fn tabard_design(&self) -> Option<[i32; 5]> {
         self.model_ref().tabard_preview
     }
@@ -87,8 +65,7 @@ impl super::UiScript {
     }
 }
 
-/// The three `this` raises every method shares (`0x847ef8` / `0x847ec0` / `0x847e98`), then the
-/// frame handle of a `TabardModel`.
+/// The three `this` raises every method shares (`0x847ef8`, `0x847ec0`, `0x847e98`).
 fn this_tabard(lua: &Lua, this: &Value) -> mlua::Result<FrameHandle> {
     let Value::Table(t) = this else {
         return Err(mlua::Error::runtime(
@@ -114,9 +91,8 @@ fn this_tabard(lua: &Lua, this: &Value) -> mlua::Result<FrameHandle> {
     Ok(h)
 }
 
-/// The five values of a designer that has been seeded, else nothing — the file-name getters and
-/// the texture setters read the raw fields, which the reference leaves uninitialised before the
-/// seed; here an unseeded designer reads as all zeros, the first legal design.
+/// The seeded design, or all zeros. Deviation: the reference reads uninitialised fields before
+/// the seed; we answer the first legal design because that value is undefined.
 fn design(model: &Model, h: FrameHandle) -> [i32; 5] {
     model.tabard_designs.get(&h).copied().unwrap_or([0; 5])
 }
@@ -127,12 +103,12 @@ fn store(lua: &Lua, h: FrameHandle, five: [i32; 5]) {
     model.tabard_preview = Some(five);
 }
 
-/// `0x455c70`: `(count · rand) >> 32` — a draw in `[0, count)` (INFERRED uniform, VERIFIED scaling).
+/// `(count * rand) >> 32`, a draw in `[0, count)` (`0x455c70`).
 fn draw(rand: u32, count: i32) -> i32 {
     ((u64::from(count as u32) * u64::from(rand)) >> 32) as i32
 }
 
-/// A clock-seeded generator standing in for the client's table-driven one (`0x4531e0`); only the
+/// A clock-seeded generator in place of the reference's table-driven one (`0x4531e0`); only the
 /// range law above is the reference's.
 fn random_words() -> impl Iterator<Item = u32> {
     let nanos = std::time::SystemTime::now()
@@ -148,8 +124,8 @@ fn random_words() -> impl Iterator<Item = u32> {
     })
 }
 
-/// `InitializeTabardColors()`'s worker `0x5028e0`: the guild record's five when the record is
-/// cached and none is `-1`, else five random draws — never zeros.
+/// `InitializeTabardColors()`'s worker (`0x5028e0`): the cached guild record unless a field is
+/// `-1`, else five random draws.
 fn seed(host: TabardHost) -> [i32; 5] {
     match host.guild_record {
         Some(rec) if rec.iter().all(|v| *v != -1) => rec,
@@ -160,8 +136,8 @@ fn seed(host: TabardHost) -> [i32; 5] {
     }
 }
 
-/// `0x502ac0`: `v ← (v + count + delta) mod count`, a signed `idiv`; `|delta| ≥ count` is a silent
-/// no-op (no repaint either). Returns whether anything changed.
+/// `(v + count + delta) mod count`, a signed `idiv` (`0x502ac0`); `|delta| >= count` is a silent
+/// no-op, with no repaint.
 fn cycle(five: &mut [i32; 5], slot: usize, delta: i32) -> bool {
     let count = TABARD_COUNTS[slot];
     if delta.wrapping_abs() >= count {
@@ -171,9 +147,8 @@ fn cycle(five: &mut [i32; 5], slot: usize, delta: i32) -> bool {
     true
 }
 
-/// The emblem path for a half (`TU` upper, `TL` lower) — `0x47a520`'s format. The reference's
-/// setters append `.BLP` before decoding (`0x503396`); here the path stays extensionless, the
-/// form every region texture carries and the app's resolver completes.
+/// The emblem path for a half (`TU` upper, `TL` lower) in `0x47a520`'s format, left without the
+/// `.BLP` the reference appends (`0x503396`), as every region texture path is.
 fn emblem_path(five: [i32; 5], half: &str) -> String {
     format!(
         "Textures\\GuildEmblems\\Emblem_{:02}_{:02}_{half}_U",
@@ -181,8 +156,8 @@ fn emblem_path(five: [i32; 5], half: &str) -> String {
     )
 }
 
-/// `Get{Upper,Lower}EmblemTexture(texture)` — the Texture-widget argument's three raises
-/// (`0x84efc8` / `0x84f050` / `0x84f010` and the lower twins), then the install.
+/// `Get{Upper,Lower}EmblemTexture(texture)`: the argument's three raises (`0x84efc8`,
+/// `0x84f050`, `0x84f010` for the upper), then the install.
 fn emblem_texture(lua: &Lua, this: Value, texture: Value, upper: bool) -> mlua::Result<()> {
     let h = this_tabard(lua, &this)?;
     let (name, half) = if upper {
@@ -226,7 +201,7 @@ fn emblem_texture(lua: &Lua, this: Value, texture: Value, upper: bool) -> mlua::
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // `InitializeTabardColors()` — `0x502b10`: the active player gates the seed; zero returns.
+    // `0x502b10`: the seed needs an active player.
     m.set(
         "InitializeTabardColors",
         lua.create_function(|lua, this: Value| {
@@ -243,7 +218,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `Save()` — `0x502bd0`: the intent carries the five; the app does the fourteen checks.
+    // `0x502bd0`: the app runs the fourteen checks on the queued five.
     m.set(
         "Save",
         lua.create_function(|lua, this: Value| {
@@ -258,9 +233,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CycleVariation(variationIndex, delta)` — `0x502ca0`: both args `lua_isnumber` else the
-    // usage raise; the index 1..5 (unsigned-checked, so 0 is out) else its own raise; both
-    // `ftol`-truncated; the worker's silent no-op for a delta past the count.
+    // `0x502ca0`: a non-number raises the usage, an index off 1..=5 its own error; both truncate.
     m.set(
         "CycleVariation",
         lua.create_function(|lua, (this, index, delta): (Value, Value, Value)| {
@@ -284,8 +257,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The four `…FileName` getters (`0x502dc0` / `0x502ea0` / `0x502f80` / `0x503070`): one
-    // string each, no extension — the loader appends `.blp`.
+    // `0x502dc0`, `0x502ea0`, `0x502f80`, `0x503070`: one string each, without `.blp`.
     for (name, upper, background) in [
         ("GetUpperBackgroundFileName", true, true),
         ("GetLowerBackgroundFileName", false, true),
@@ -313,7 +285,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // The two texture SETTERS (`0x503160` / `0x503540`), zero returns.
+    // Setters despite their names (`0x503160`, `0x503540`): the reference installs a 128x64 or
+    // 128x32 mask into the passed texture.
     m.set(
         "GetUpperEmblemTexture",
         lua.create_function(|lua, (this, texture): (Value, Value)| {
@@ -327,8 +300,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `CanSaveTabardNow()` — `0x503910` never resolves `this`: the number 1, or nil, from
-    // `player && guildRecordCached && !savePending` (`0x5f0800`). Not a would-it-succeed test.
+    // `0x503910` never resolves `this`: the number 1 or nil, from a player, a cached record and
+    // no save pending (`0x5f0800`), not a would-it-succeed test.
     m.set(
         "CanSaveTabardNow",
         lua.create_function(|lua, _: mlua::MultiValue| {
@@ -343,13 +316,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     lua.set_named_registry_value(REG_TABARDMODEL_METHODS, m)?;
 
     let g = lua.globals();
-    // `GetTabardCreationCost()` — 0 args, one number, the constant.
     g.set(
         "GetTabardCreationCost",
         lua.create_function(|_, ()| Ok(i64::from(TABARD_CREATION_COST)))?,
     )?;
-    // `CloseTabardCreation()` — `0x4f5900`: zero args, zero returns, no packet; the close core
-    // (`0x4f58a0`) and its `CLOSE_TABARD_FRAME` are the app's, gated on a stored vendor.
+    // `0x4f5900`, no packet: the app runs the close (`0x4f58a0`) and its `CLOSE_TABARD_FRAME`,
+    // gated on a stored vendor.
     g.set(
         "CloseTabardCreation",
         lua.create_function(|lua, _: mlua::MultiValue| {
diff --git a/crates/benilla-ui/src/script/talent.rs b/crates/benilla-ui/src/script/talent.rs
index feb72cf7..0d3f3038 100644
--- a/crates/benilla-ui/src/script/talent.rs
+++ b/crates/benilla-ui/src/script/talent.rs
@@ -1,126 +1,98 @@
-//! The talent window's engine seam (decision 0304) — the same two-way shape as
-//! [`super::spellbook`]: the app pushes a **talent snapshot** ([`UiScript::set_talents`] — the
-//! class's tabs + each tab's talents, already resolved to name/icon/rank/availability by the
-//! app's `Talent.dbc` × `Spell.dbc` join), the Era bindings below read it verbatim, and
-//! `LearnTalent(tab, index)` queues outbound intents the app drains
-//! ([`UiScript::take_talent_learns`]) into `CMSG_LEARN_TALENT`. The engine holds no talent
-//! KNOWLEDGE — grid seats, ranks, prerequisites, and availability are the app's resolve.
+//! The talent bindings: the app pushes the class's pages and talents, resolved from `Talent.dbc`
+//! and `Spell.dbc` ([`UiScript::set_talents`]), and `LearnTalent(tab, index)` queues clicks for
+//! `CMSG_LEARN_TALENT`. Grid seats, ranks, prerequisites and availability are the app's.
 //!
-//! The **respec** pair rides here too (decision 1580) and is the binder question's twin, not a
-//! talent-window affordance: `ConfirmTalentWipe()` answers a class trainer's
-//! `CONFIRM_TALENT_WIPE`, and `CheckTalentMasterDist()` is the range poll that takes the dialog
-//! away when you walk off. Both are 1.12 engine bindings (`reference/1.12-globals.tsv`), and
-//! neither reads the snapshot above — the question arrives as the event's argument.
+//! The tuples are what `Blizzard_TalentUI.lua` reads (`:154`, `:180`): `GetTalentTabInfo(i)` gives
+//! name, texture, pointsSpent, fileName; `GetTalentInfo(tab, i)` name, icon, tier, column, rank,
+//! maxRank, isExceptional, meetsPrereq. Tiers and columns are 1-based, as the stock frame indexes
+//! `TALENT_BRANCH_ARRAY[tier][column]`. The respec pair answers a class trainer's
+//! `CONFIRM_TALENT_WIPE` and reads no snapshot.
 //!
-//! The Era tuple shapes are the 1.12 addon's own reads (`Blizzard_TalentUI.lua`, extracted from
-//! the patch chain — decision 0304's pin §3):
-//! `GetTalentTabInfo(i) → name, texture, pointsSpent, fileName`;
-//! `GetTalentInfo(tab, i) → name, icon, tier, column, rank, maxRank, isExceptional, meetsPrereq`;
-//! `GetTalentPrereqs(tab, i) → tier, column, isLearnable, …` (flat triplets);
-//! `UnitCharacterPoints(unit) → cp1, cp2`. Tiers/columns are **1-based** Lua-facing (the
-//! reference indexes `TALENT_BRANCH_ARRAY[tier][column]` directly) — the app pushes them
-//! 1-based; `isExceptional` is pushed but unused by the reference frame's own render.
-//!
-//! ## The tooltip (`GameTooltip:SetTalent(tab, index)`)
-//!
-//! The 1.12 talent tooltip IS the spell builder `0x52e610` with the talent params (wow-re
-//! `tooltip-content-law.md` §3: line 2 `TOOLTIP_TALENT_RANK` "Rank %d/%d" white iff
-//! `param7≠0 && param8==0`; line 13 `TOOLTIP_TALENT_LEARN` "Click to learn" green on a learnable
-//! higher rank) — so `SetTalent` renders THROUGH the spell channel: the talent's display-rank
-//! spell view comes from the same ask-once store `SetSpell` uses (a miss queues the id for the
-//! app's resolver), interleaved with the talent lines ([`TalentLines`]). The red requirement
-//! lines' position (here: after the rank line) is CONFIRMED — decision 0305's residue: it
-//! matches the builder law. Still open: the "Next rank:" block's composition (here:
-//! `TOOLTIP_TALENT_NEXT_RANK` white + the next rank spell's description gold — its view from the
-//! same store) — 0305 didn't walk it.
+//! `GameTooltip:SetTalent` is the spell builder (`0x52e610`) with talent lines: the rank line
+//! (`TOOLTIP_TALENT_RANK`, `0x854a2c`), the red requirement lines after it, and "Click to learn"
+//! (`TOOLTIP_TALENT_LEARN`, `0x8549f8`) in green on a learnable rank. The "Next rank:" block,
+//! `TOOLTIP_TALENT_NEXT_RANK` in white and the next rank's description in gold, is untraced in
+//! the reference.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
 use super::tooltip_spell::{spell_view_of, TalentLines};
 use super::Model;
 
-/// One talent page (`TalentTab.dbc` row, app-resolved) — `GetTalentTabInfo`'s source.
+/// One talent page, a `TalentTab.dbc` row: `GetTalentTabInfo`'s source.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TalentTabView {
     pub name: String,
-    /// The `Interface\TalentFrame\<base>-` art base (`fileName` in the Era tuple).
+    /// The `Interface\TalentFrame\<base>-` art base, the tuple's `fileName`.
     pub background: String,
-    /// Points spent across this page's talents (the app's sum of ranks).
     pub points_spent: u32,
 }
 
-/// One prerequisite edge for the branch drawing — `GetTalentPrereqs`' triplet.
+/// One prerequisite edge, a `GetTalentPrereqs` triplet.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct TalentPrereqView {
-    /// 1-based, Lua-facing (module doc).
     pub tier: u32,
     pub column: u32,
-    /// The prereq is learned to its required rank (drives arrow color + availability).
+    /// The prerequisite is learned to its required rank.
     pub learnable: bool,
 }
 
-/// One talent button's full render state — `GetTalentInfo`'s source plus the tooltip context.
+/// One talent button: `GetTalentInfo`'s source and the tooltip's context.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TalentView {
     pub name: String,
     pub texture: Option<String>,
-    /// 1-based, Lua-facing (module doc).
     pub tier: u32,
     pub column: u32,
-    /// Current rank (0 = unlearned) / the talent's own rank count.
+    /// Current rank, 0 when unlearned.
     pub rank: u32,
     pub max_rank: u32,
-    /// `Talent.dbc` flags bit 0 — the Era tuple's `isExceptional` (byte-verified
-    /// `TalentRec+0x4c` bit0; the reference frame reads and ignores it).
+    /// `Talent.dbc` flags bit 0 (`TalentRec+0x4c`), the tuple's `isExceptional`; the stock frame
+    /// ignores it.
     pub exceptional: bool,
-    /// The non-prereq requirements hold — the required-spell known-check only, prereqs live in
-    /// the triplets (decision 0305: `meetsPrereq`'s derivation, confirmed as built).
+    /// The required spell is known; prerequisite talents live in the triplets.
     pub meets_prereq: bool,
     pub prereqs: Vec<TalentPrereqView>,
-    /// The tooltip's spell part: the display rank's spell id (rank max(1, rank)) — its view
-    /// rides the spell channel's ask-once store.
+    /// The spell id of rank `max(1, rank)`, the tooltip's spell part.
     pub display_spell: u32,
-    /// The next rank's spell id when `0 < rank < max_rank` (the "Next rank:" block); 0 = none.
+    /// The next rank's spell id when `0 < rank < max_rank`, else 0.
     pub next_spell: u32,
-    /// App-composed red requirement lines (`TOOLTIP_TALENT_TIER_POINTS`/`_PREREQ[_P1]`), shown
-    /// while the talent is locked.
+    /// Red requirement lines (`TOOLTIP_TALENT_TIER_POINTS`, `TOOLTIP_TALENT_PREREQ`), shown while
+    /// the talent is locked.
     pub req_lines: Vec<String>,
-    /// The green `TOOLTIP_TALENT_LEARN` hint: a learnable higher rank (tier unlocked, prereqs
-    /// met, points available) — the same gate the frame's green border wears.
+    /// A higher rank is learnable now: the green `TOOLTIP_TALENT_LEARN` line and border.
     pub learnable: bool,
 }
 
-/// The pushed snapshot: the player's own pages + unspent points.
+/// The pushed snapshot: the player's own pages and unspent points.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TalentUiState {
     pub tabs: Vec<TalentTabView>,
-    /// `talents[t]` = tab `t+1`'s talents, in the enumeration order the app pinned.
+    /// `talents[t]` holds tab `t+1`'s talents, in the app's enumeration order.
     pub talents: Vec<Vec<TalentView>>,
-    /// `UnitCharacterPoints("player")`: (unspent talent points, free primary professions).
+    /// `UnitCharacterPoints("player")`: unspent talent points, free primary professions.
     pub points: (u32, u32),
 }
 
 impl super::UiScript {
-    /// Push the whole talent snapshot (the app's feed on SPELLS_CHANGED/points change).
+    /// Push the whole talent snapshot.
     pub fn set_talents(&mut self, state: TalentUiState) {
         self.model_mut().talents = state;
     }
 
-    /// Drain the queued `LearnTalent(tab, index)` clicks (both 1-based, as the Lua passed them).
+    /// Drain the queued `LearnTalent(tab, index)` clicks, both 1-based.
     pub fn take_talent_learns(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().talent_learns)
     }
 
-    /// Drain the `ConfirmTalentWipe()` calls queued since the last drain — each one is an outbound
-    /// `MSG_TALENT_WIPE_CONFIRM` ([`Self::take_binder_confirms`]'s shape, and a count for the same
-    /// reason: the app holds the trainer's guid).
+    /// Drain the count of `ConfirmTalentWipe()` calls, each an outbound `MSG_TALENT_WIPE_CONFIRM`;
+    /// a count, since the app holds the trainer's guid.
     pub fn take_talent_wipe_confirms(&mut self) -> u32 {
         std::mem::take(&mut self.model_mut().talent_wipe_confirms)
     }
 
-    /// Push whether a trainer's respec question is live and still in range — the host's half of
-    /// `CheckTalentMasterDist()`. Idempotent; `false` covers both "no question pending" and "you
-    /// walked away", which is all the dialog's OnUpdate needs in order to decide to hide.
+    /// Push whether a trainer's respec question is live and in range, which
+    /// `CheckTalentMasterDist()` answers; false for none pending or walked away.
     pub fn set_talent_master_pending(&mut self, pending: bool) {
         let mut model = self.model_mut();
         if model.talent_master_pending != pending {
@@ -129,7 +101,7 @@ impl super::UiScript {
     }
 }
 
-/// Look up one talent by the Lua-facing (tab, index) pair (both 1-based).
+/// One talent by its 1-based (tab, index).
 fn talent_at(model: &Model, tab: usize, index: usize) -> Option<&TalentView> {
     model
         .talents
@@ -150,8 +122,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTalentTabInfo(i) -> name, texture, pointsSpent, fileName. `texture` is nil — the
-    // reference frame never reads it (module doc); out of range -> a single nil.
+    // `texture` is nil: the stock frame never reads it. Out of range answers a single nil.
     g.set(
         "GetTalentTabInfo",
         lua.create_function(|lua, i: usize| {
@@ -180,8 +151,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTalentInfo(tab, i) -> name, icon, tier, column, rank, maxRank, isExceptional,
-    // meetsPrereq. `isExceptional` is 0 (pushed nowhere; the reference render ignores it).
     g.set(
         "GetTalentInfo",
         lua.create_function(|lua, (tab, i): (usize, usize)| {
@@ -206,8 +175,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTalentPrereqs(tab, i) -> tier, column, isLearnable per prerequisite, flattened (the
-    // reference walks `for i=5, arg.n, 3`); none -> empty.
+    // Flat (tier, column, isLearnable) triplets, as `Blizzard_TalentUI.lua:385` walks them.
     g.set(
         "GetTalentPrereqs",
         lua.create_function(|lua, (tab, i): (usize, usize)| {
@@ -224,9 +192,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // LearnTalent(tab, i): queue the click for the app's wire drain. The availability gate is
-    // the app's at send time (mirroring its own pushed `learnable`) — the server re-validates
-    // regardless (vmangos Player::LearnTalent).
+    // The app gates the send on its own `learnable`; the server re-validates
+    // (vmangos `Player::LearnTalent`).
     g.set(
         "LearnTalent",
         lua.create_function(|lua, (tab, i): (u32, u32)| {
@@ -236,10 +203,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ConfirmTalentWipe() — the CONFIRM_TALENT_WIPE dialog's Accept, and the one call in the
-    // client that unlearns talents: the trainer's question changed nothing (decision 1580).
-    // Zero-arg because the guid it sends is one the client latched from that question — the
-    // reference's own `0xc4d7a0` (wow-re `talent-api.md` §ConfirmTalentWipe); here the app holds it.
+    // ConfirmTalentWipe(): the `CONFIRM_TALENT_WIPE` Accept, the one call that unlearns talents.
+    // No argument: the reference sends the trainer guid it latched (`0xc4d7a0`); the app holds it.
     g.set(
         "ConfirmTalentWipe",
         lua.create_function(|lua, ()| {
@@ -249,10 +214,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CheckTalentMasterDist() — polled from that dialog's OnUpdate; false hides it. The reference
-    // re-runs its interact-range test against the latched trainer (`0x5df980`, the same
-    // `d² <= [0xc4c28c]` gate `CheckBinderDist` runs), so walking away takes the question off
-    // screen with no packet either way.
+    // CheckTalentMasterDist(): polled by that dialog's OnUpdate, false hides it. The reference
+    // re-runs its interact-range test on the latched trainer (`0x5df980`, `d² <= [0xc4c28c]`);
+    // no packet either way.
     g.set(
         "CheckTalentMasterDist",
         lua.create_function(|lua, ()| {
@@ -261,9 +225,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCharacterPoints(unit) -> cp1 (unspent talent points), cp2 (free professions). The
-    // pair is our own player's (PLAYER_CHARACTER_POINTS1/2 are PRIVATE fields) — any other
-    // unit token answers the same store, matching the fields only we ever receive.
+    // Every unit token answers the player's own pair: `PLAYER_CHARACTER_POINTS1/2` are private
+    // fields only we receive.
     g.set(
         "UnitCharacterPoints",
         lua.create_function(|lua, _unit: String| {
@@ -276,8 +239,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// Register `GameTooltip:SetTalent(tab, index)` into the tooltip kind method table (module doc:
-/// the spell builder with talent lines).
+/// Register `GameTooltip:SetTalent(tab, index)` into the tooltip method table.
 pub(super) fn install_tooltip_method(lua: &Lua, m: &Table) -> mlua::Result<()> {
     m.set(
         "SetTalent",
@@ -287,8 +249,7 @@ pub(super) fn install_tooltip_method(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 let Some(t) = talent_at(&model, tab, i) else {
                     return Ok(());
                 };
-                // The "Next rank:" block needs the next rank's description — from the same
-                // ask-once spell store (a miss shows the block on the hover's re-enter).
+                // From the ask-once spell store; a miss shows on the next hover.
                 let next_desc = (t.next_spell != 0)
                     .then(|| {
                         model
@@ -297,9 +258,8 @@ pub(super) fn install_tooltip_method(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             .map(|v| v.description.clone())
                     })
                     .flatten();
-                // `TOOLTIP_TALENT_RANK` = "Rank %d/%d" (`0x854a2c`, pushed at `0x52b213`) —
-                // the key, filled with the two counts, never a sentence of ours (decision 2045).
-                // An install whose string table lacks it shows no rank line at all.
+                // `TOOLTIP_TALENT_RANK`, "Rank %d/%d" (`0x854a2c`, pushed at `0x52b213`); an
+                // install without it shows no rank line.
                 let rank_line = crate::strings::global(lua, "TOOLTIP_TALENT_RANK").map(|tmpl| {
                     crate::strings::fill(
                         &tmpl,
@@ -326,9 +286,7 @@ pub(super) fn install_tooltip_method(lua: &Lua, m: &Table) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The spell-store ask for the next-rank description (kept beside [`install_tooltip_method`] so
-/// the ask-once discipline stays in one place): a `SetTalent` render whose next-rank view is
-/// missing queues it exactly like a primary-view miss.
+/// Ask the spell store for the next rank's description; a miss queues it as a primary view's does.
 pub(super) fn ask_next_rank(lua: &Lua, next_spell: u32) {
     if next_spell != 0 {
         let _ = spell_view_of(lua, next_spell); // a miss records the ask as a side effect
diff --git a/crates/benilla-ui/src/script/taxi.rs b/crates/benilla-ui/src/script/taxi.rs
index d1864020..32f5b55a 100644
--- a/crates/benilla-ui/src/script/taxi.rs
+++ b/crates/benilla-ui/src/script/taxi.rs
@@ -1,52 +1,28 @@
-//! The taxi-map bindings (decision 0484) — the Era-shaped flight-master surface driving a faithful
-//! port of the real 1.12 `TaxiFrame` (extracted from the patch chain:
-//! `Interface\FrameXML\TaxiFrame.{xml,lua}`). Same two-way seam as [`super::trainer`]: the app
-//! pushes a **taxi snapshot** ([`UiScript::set_taxi`] — the known-node mask, DBC positions, route
-//! and cost computation already resolved app-side to a flat node list), and the Lua
-//! `TakeTaxiNode`/`CloseTaxiMap` calls queue outbound **intents** the app drains
-//! ([`UiScript::take_taxi_node`] / [`UiScript::take_taxi_close`]). The engine holds no taxi
-//! knowledge — a node is name/type/position/cost/route-segments, all app-resolved.
-//!
-//! ## The Era API shape (matched to the real `TaxiFrame.lua`)
-//!
-//! The reference window's `.lua` runs verbatim on these bindings: `NumTaxiNodes`,
-//! `TaxiNodeGetType(i) → "CURRENT"/"REACHABLE"/"DISTANT"/"NONE"`, `TaxiNodePosition(i) → x, y`
-//! (normalized 0..1, **BOTTOMLEFT** origin — the Lua multiplies by the 316×352 map size and anchors
-//! from the map's BOTTOMLEFT), `TaxiNodeName(i)`, `TaxiNodeCost(i)` (copper),
-//! `GetNumRoutes(i)` + `TaxiGetSrcX/Y(i, hop)`/`TaxiGetDestX/Y(i, hop)` (the hover route's
-//! per-hop segment endpoints, same normalized space), `TakeTaxiNode(i)`, `CloseTaxiMap()`,
-//! `SetTaxiMap(texture)` (assigns the continent art onto the given Texture region),
-//! `TaxiNodeSetCurrent(i)` (a no-op here: the real client computes the hovered node's route arrays
-//! behind it; the app precomputes every node's route, so there is nothing to arm), and
-//! `UnitOnTaxi(unit)`. Indices are 1-based into the pushed node list.
-//!
-//! Node classification, projection, and the route metric are the app's job — and are INTERIM
-//! behind decision 0484's in-flight §5 (I1/I2); this seam only carries the results.
+//! The taxi-map bindings the stock `TaxiFrame.lua` runs on, over a node list the app resolves
+//! and pushes (types, positions, fares and routes); `TakeTaxiNode` and `CloseTaxiMap` queue
+//! intents the app drains. Positions are normalized 0..1 from the map's bottom-left, which the Lua
+//! scales by the 316x352 map.
 
 use mlua::{Lua, Table};
 
 use super::region::region_handle_of;
 use super::Model;
 
-/// A visible node's icon state (`TaxiNodeGetType`) — the reference maps these to the green
-/// (current) / white (reachable) / yellow (distant) icons.
+/// A visible node's icon state (`TaxiNodeGetType`): green, white or yellow in the reference.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum TaxiNodeType {
-    /// The flight master's own node ("You are here" — green).
+    /// The flight master's own node, "You are here".
     Current,
-    /// Known, and a route from the current node exists (white; clickable).
+    /// Known and routable from the current node; clickable.
     #[default]
     Reachable,
-    /// Known, but no route connects it to the current node (yellow). **Never produced**: the real
-    /// client's DISTANT classification is a dead branch (byte-verified — decision 0496 §TU-3; an
-    /// unroutable node simply doesn't render), so the app drops such nodes instead. The variant
-    /// stays because the reference Lua's `TaxiButtonTypes` table names it — a faithful surface
-    /// with no live writer.
+    /// Known but unroutable. Never produced: the reference's DISTANT branch is dead and an
+    /// unroutable node does not render; the variant stays because `TaxiButtonTypes` names it.
     Distant,
 }
 
 impl TaxiNodeType {
-    /// The Era type string (`TaxiFrame.lua`'s `TaxiButtonTypes` keys).
+    /// The type string, a `TaxiButtonTypes` key.
     fn era_str(self) -> &'static str {
         match self {
             TaxiNodeType::Current => "CURRENT",
@@ -56,24 +32,23 @@ impl TaxiNodeType {
     }
 }
 
-/// One node on the open taxi map — everything the window shows for it, app-resolved.
+/// One node on the open taxi map, resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TaxiUiNode {
-    /// `TaxiNodeName` (the DBC's localized name, e.g. `"Stormwind, Elwynn"`).
+    /// `TaxiNodeName`, the DBC's localized name.
     pub name: String,
-    /// `TaxiNodeGetType`. A node the reference would type `"NONE"` (hidden) is simply not pushed.
+    /// `TaxiNodeGetType`; a node the reference types `"NONE"` is not pushed.
     pub node_type: TaxiNodeType,
-    /// `TaxiNodePosition` — normalized `(x, y)` on the map art, 0..1, BOTTOMLEFT origin.
+    /// `TaxiNodePosition`: normalized `(x, y)` on the map art, from the bottom-left.
     pub pos: (f32, f32),
-    /// `TaxiNodeCost` — the route's fare in copper (0 for the current node / an unroutable one).
+    /// `TaxiNodeCost`: the fare in copper, 0 for the current node.
     pub cost: u32,
-    /// The hover route's per-hop segments, `[src_x, src_y, dest_x, dest_y]` each, in the same
-    /// normalized space (`GetNumRoutes` / `TaxiGetSrcX…DestY`). Empty for current/distant nodes.
+    /// The hover route's hops as `[src_x, src_y, dest_x, dest_y]` in the same space, for
+    /// `GetNumRoutes` and `TaxiGetSrcX` to `TaxiGetDestY`; empty for the current node.
     pub routes: Vec<[f32; 4]>,
 }
 
-/// The open taxi map: the continent art and the visible nodes. Pushed whole by the app; `None`
-/// means no taxi map is open.
+/// The open taxi map: the continent art and the visible nodes.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TaxiUiState {
     /// The map art `SetTaxiMap` assigns (e.g. `Interface\TaxiFrame\TAXIMAP1`).
@@ -88,21 +63,18 @@ impl super::UiScript {
         self.model_mut().taxi = state;
     }
 
-    /// Whether our own player is currently riding a taxi (`UnitOnTaxi("player")` — the action-bar
-    /// dim and the reference's flight-state checks read it).
+    /// Whether the player is riding a taxi, for `UnitOnTaxi("player")`.
     pub fn set_on_taxi(&mut self, riding: bool) {
         self.model_mut().taxi_riding = riding;
     }
 
-    /// Drain the **1-based node indices** `TakeTaxiNode` queued since the last call (the app maps
-    /// each back to its node id and sends the activate packet).
+    /// Drain the 1-based indices `TakeTaxiNode` queued; the app sends the activate for each.
     pub fn take_taxi_node(&mut self) -> Vec<usize> {
         std::mem::take(&mut self.model_mut().taxi_takes)
     }
 
-    /// Whether `CloseTaxiMap` was called since the last drain (and clear the flag). The window
-    /// closed client-side; the app clears its taxi state (no packet — the server holds no
-    /// open-window session for the map).
+    /// Whether `CloseTaxiMap` was called since the last drain; it sends no packet, as the server
+    /// holds no window session for the map.
     pub fn take_taxi_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().taxi_close)
     }
@@ -117,11 +89,9 @@ fn node(model: &Model, i: i64) -> Option<&TaxiUiNode> {
         .and_then(|i| nodes.get(i))
 }
 
-/// Register the taxi globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // → how many nodes the open map shows (0 when closed).
     g.set(
         "NumTaxiNodes",
         lua.create_function(|lua, ()| {
@@ -130,7 +100,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the node's icon-state string; "NONE" out of range (the reference hides that button).
+    // "NONE" out of range, a button the reference hides.
     g.set(
         "TaxiNodeGetType",
         lua.create_function(|lua, i: i64| {
@@ -139,7 +109,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the node's normalized map position (x, y; BOTTOMLEFT origin).
     g.set(
         "TaxiNodePosition",
         lua.create_function(|lua, i: i64| {
@@ -157,7 +126,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the fare to fly there, in copper (`SetTooltipMoney` renders it).
     g.set(
         "TaxiNodeCost",
         lua.create_function(|lua, i: i64| {
@@ -166,14 +134,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The real client arms the hovered node's route computation here; the app pushes every node's
-    // route precomputed, so this is a faithful no-op (kept so the reference Lua runs verbatim).
+    // The reference computes the hovered node's route here; the app precomputes every route.
     g.set(
         "TaxiNodeSetCurrent",
         lua.create_function(|_, _: i64| Ok(()))?,
     )?;
 
-    // → the hover route's hop count for node `i`.
     g.set(
         "GetNumRoutes",
         lua.create_function(|lua, i: i64| {
@@ -182,8 +148,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → one endpoint coordinate of route hop `hop` (1-based) of node `i` — the four accessors the
-    // reference's `DrawRouteLine` loop reads.
+    // One coordinate of 1-based hop `hop`, for the reference's `DrawRouteLine` loop.
     for (name, pick) in [
         ("TaxiGetSrcX", 0usize),
         ("TaxiGetSrcY", 1),
@@ -203,7 +168,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // Queue the click — the app maps the index to a node id and sends the activate packet.
     g.set(
         "TakeTaxiNode",
         lua.create_function(|lua, i: i64| {
@@ -225,8 +189,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetTaxiMap(textureRegion) — assign the open map's continent art onto the given Texture
-    // region (the engine picked `TAXIMAP<map>`, app-side; the region draws it like any SetTexture).
+    // The open map's continent art (`TAXIMAP<map>`, the app's pick) onto the given texture.
     g.set(
         "SetTaxiMap",
         lua.create_function(|lua, this: Table| {
@@ -240,20 +203,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `UnitOnTaxi(unit)` (`0x517a40`) → **the number 1 or nil**, never a Lua boolean — the unit
-    // predicate family's one return shape (decisions 1830, 2043; the push law is
-    // `crate::script::binding_abi::flag`). It lives here rather than beside its 22 siblings
-    // because the ride flag it reads is this module's, not `UnitState`'s — which is exactly how it
-    // came to be the one predicate still answering a `bool` after the family was fixed.
-    //
-    // Only our own player is tracked (the reference UI only ever asks about `"player"`); any other
-    // token reads nil.
-    //
-    // The token argument is `Value`, not `String`, so the miss is the reference's own message: the
-    // binding carries an `lua_isstring` gate at `0x517a48` whose failure arm is
-    // `luaL_error("Usage: UnitOnTaxi(\"unit\")")` (wow-re
-    // `ui/scratch/nil-unit-token-arg-law.md` §10, row 33). A Rust `String` parameter raised mlua's
-    // own type-conversion error there instead.
+    // `0x517a40`: the number 1 or nil, never a boolean; an argument neither string nor number
+    // raises the reference's usage (`0x517a48`). Only the player is tracked, as the stock UI asks
+    // about no other unit.
     g.set(
         "UnitOnTaxi",
         lua.create_function(|lua, unit: mlua::Value| {
diff --git a/crates/benilla-ui/src/script/tests/addon_argument_abi.rs b/crates/benilla-ui/src/script/tests/addon_argument_abi.rs
index 06d14e7c..283a148b 100644
--- a/crates/benilla-ui/src/script/tests/addon_argument_abi.rs
+++ b/crates/benilla-ui/src/script/tests/addon_argument_abi.rs
@@ -1,11 +1,7 @@
-//! **The `index or "name"` prologue every in-game addon verb opens with, and its two raises**
-//! (2139's "left open", closed at the bytes).
-//!
-//! Eight bindings — `GetAddOnInfo 0x48e390`, `GetAddOnMetadata 0x48e530`,
+//! The `index or "name"` prologue of `GetAddOnInfo 0x48e390`, `GetAddOnMetadata 0x48e530`,
 //! `GetAddOnDependencies 0x48e5e0`, `EnableAddOn 0x48e690`, `DisableAddOn 0x48e760`,
-//! `IsAddOnLoadOnDemand 0x48e840`, `IsAddOnLoaded 0x48e8e0`, `LoadAddOn 0x48e980` — share one
-//! eleven-instruction prologue, and `luaL_error 0x6f4940` does not return from either of its
-//! failure arms. We answered a placeholder, a `nil` or a silent no-op for all of them.
+//! `IsAddOnLoadOnDemand 0x48e840`, `IsAddOnLoaded 0x48e8e0` and `LoadAddOn 0x48e980`; both its
+//! raises are `luaL_error` (`0x6f4940`), which does not return.
 
 use crate::script::{AddOnInfo, UiScript};
 
@@ -31,15 +27,11 @@ fn seeded() -> UiScript {
         None,
         None,
     );
-    // **The index space exists only once the server has answered** (decision 2175). These tests
-    // are about the prologue's bounds and raises, and a bound of zero would make every one of
-    // them pass vacuously — so the fixture seats the reply an in-world VM has always had, hiding
-    // nothing.
+    // The index space exists only once the server answers; with no reply every bound is zero.
     s.note_addon_info_reply(&[]);
     s
 }
 
-/// The message of a raise, or `"<no raise>"` if the call completed.
 fn raised(s: &UiScript, call: &str) -> String {
     s.eval::<String>(&format!(
         "local ok, e = pcall(function() {call} end) \
@@ -48,9 +40,7 @@ fn raised(s: &UiScript, call: &str) -> String {
     .unwrap()
 }
 
-/// **Every verb raises its own `Usage:` literal on a non-number, non-string argument.** Read out
-/// of `.data` (`0x842d68` … `0x842e98`) rather than reconstructed: the message reaches an addon's
-/// error handler, so the spelling is the contract.
+/// The client's own literals (`.data` `0x842d68` to `0x842e98`); addons see the spelling.
 #[test]
 fn a_bad_argument_type_raises_each_verbs_own_usage_string() {
     let s = seeded();
@@ -82,8 +72,7 @@ fn a_bad_argument_type_raises_each_verbs_own_usage_string() {
             "{call} must raise `{usage}`, got: {got}"
         );
     }
-    // `nil` and a missing argument fail the same two tests a table does — `lua_isnumber` reports
-    // NULL past `L->top` as "not a number" — so they take the same raise.
+    // `lua_isnumber` reports a slot past `L->top` as not a number, so nil or no argument raises.
     for call in ["LoadAddOn(nil)", "LoadAddOn()", "IsAddOnLoaded(true)"] {
         assert!(
             raised(&s, call).contains("index or \"name\""),
@@ -91,16 +80,12 @@ fn a_bad_argument_type_raises_each_verbs_own_usage_string() {
             raised(&s, call)
         );
     }
-    // The second argument has its own `lua_isstring` (`0x48e59c`) onto the SAME raise.
+    // The second argument's own `lua_isstring` (`0x48e59c`) fails onto the same raise.
     assert!(raised(&s, "GetAddOnMetadata(1)").contains("Usage: GetAddOnMetadata"));
 }
 
-/// **An out-of-range numeric index raises, on every verb, with the count in the message** —
-/// `"AddOn index must be in the range of 1 to %d"` (`0x837d70`), `%d` from `0x51def0()`.
-///
-/// The bound is **unsigned** (`0x51df00 cmp ecx,[0xbe1b90]; jb`), so `f(0)` decrements to
-/// `0xFFFFFFFF` and raises by the same route as `f(count+1)`. Only three of the eight raised at
-/// all before this, and those three said something the image does not.
+/// `"AddOn index must be in the range of 1 to %d"` (`0x837d70`, `%d` from `0x51def0()`). The
+/// bound is unsigned (`0x51df00 cmp ecx,[0xbe1b90]; jb`): 0 wraps to `0xFFFFFFFF` and raises.
 #[test]
 fn an_out_of_range_index_raises_with_the_registrys_own_count() {
     let s = seeded();
@@ -115,8 +100,7 @@ fn an_out_of_range_index_raises_with_the_registrys_own_count() {
         "LoadAddOn",
     ] {
         for arg in ["0", "3", "-1", "2.9"] {
-            // 2.9 truncates toward zero (`_ftol 0x40a2b0` chops) to 2, which is IN range — the
-            // one of the four that must NOT raise.
+            // 2.9 truncates to 2 (`_ftol 0x40a2b0`), which is in range.
             let got = raised(&s, &format!("{verb}({arg})"));
             if arg == "2.9" {
                 assert!(!got.contains("must be in the range"), "{verb}(2.9): {got}");
@@ -128,8 +112,7 @@ fn an_out_of_range_index_raises_with_the_registrys_own_count() {
     assert!(raised(&s, "GetAddOnMetadata(3, \"Version\")").contains(want));
 }
 
-/// **A numeric STRING is an index, not a name** — `lua_isnumber 0x6f34d0` coerces one, so the
-/// number arm claims it before `lua_isstring` is ever reached.
+/// `lua_isnumber` (`0x6f34d0`) coerces a numeric string, so the index arm claims it first.
 #[test]
 fn a_numeric_string_takes_the_index_arm() {
     let s = seeded();
@@ -141,11 +124,7 @@ fn a_numeric_string_takes_the_index_arm() {
     assert!(raised(&s, r#"GetAddOnInfo("9")"#).contains("must be in the range"));
 }
 
-/// **`GetAddOnInfo`'s string miss echoes the caller's own name back** (`0x48e401`, non-NULL by
-/// `lua_isstring`), then five metadata misses, `"MISSING"` and `"INSECURE"`. We answered the
-/// literal `"NoSuchAddon"` — which is wow-re's *example call*, not a constant in the image.
-///
-/// The name form is never existence-checked by the prologue; only the numeric one is.
+/// A name miss echoes the caller's string (`0x48e401`); only an index is existence-checked.
 #[test]
 fn an_unknown_name_echoes_itself_rather_than_a_placeholder_literal() {
     let s = seeded();
@@ -165,7 +144,7 @@ fn an_unknown_name_echoes_itself_rather_than_a_placeholder_literal() {
             "INSECURE".into(),
         ]
     );
-    // The other name-miss answers are each verb's own, and they do not agree with GetAddOnInfo's.
+    // Each verb has its own name-miss answer.
     assert_eq!(
         s.eval::<String>(r#"return tostring(IsAddOnLoaded("Nope"))"#)
             .unwrap(),
diff --git a/crates/benilla-ui/src/script/tests/addon_index_space.rs b/crates/benilla-ui/src/script/tests/addon_index_space.rs
index 9277f681..5e0d39f8 100644
--- a/crates/benilla-ui/src/script/tests/addon_index_space.rs
+++ b/crates/benilla-ui/src/script/tests/addon_index_space.rs
@@ -1,21 +1,11 @@
-//! **The Lua index space is not the registry** (decision 2175) — a different order, over a
-//! different set, that does not exist until the server answers.
-//!
-//! `GetNumAddOns` and the *index* form of every AddOn verb address a flat array the client
-//! rebuilds in exactly one place: the tail of `AddOn_ReadAddonInfoReply 0x51da70`
-//! (`[0x51dc30, 0x51dcdf)`), driven by `SMSG_ADDON_INFO`. It is `## Title`-sorted with
-//! `SStrCmpI`, filtered by `[rec+0x29]`, and empty before the reply — three properties benilla had
-//! none of, because it indexed the registry list directly. wow-re
-//! `system/ui/scratch/addon-registry-scan-and-order.md` §7 (byte-read, and §11-executed over the
-//! binary's own `qsort 0x73f727` and comparator `0x51deb0`).
+//! The addon index space that `GetNumAddOns` and every verb's index form address: an array, not
+//! the registry, rebuilt only by `SMSG_ADDON_INFO` (`AddOn_ReadAddonInfoReply 0x51da70`,
+//! `[0x51dc30, 0x51dcdf)`). It is `## Title`-sorted with `SStrCmpI` (`qsort 0x73f727`, comparator
+//! `0x51deb0`), filtered by `[rec+0x29]`, and empty before the reply.
 
 use crate::script::{AddOnInfo, UiScript};
 
-/// Three addons whose FOLDER order and TITLE order are deliberately different permutations, so a
-/// test cannot pass by accident on a registry that happens to be sorted.
-///
-/// Folder order (registration): `Zulu`, `Alpha`, `Mike`.
-/// Title order: `Zulu` (`"aardvark"`), `Mike` (`"Middle"`), `Alpha` (`"zebra"`).
+/// Folder order `Zulu`, `Alpha`, `Mike`; title order `Zulu`, `Mike`, `Alpha`.
 fn seeded() -> UiScript {
     let mut s = UiScript::new().unwrap();
     let row = |name: &str, title: Option<&str>| AddOnInfo {
@@ -38,7 +28,6 @@ fn seeded() -> UiScript {
     s
 }
 
-/// The names `GetAddOnInfo(i)` answers, in index order.
 fn by_index(s: &UiScript) -> Vec<String> {
     s.eval::<Vec<String>>(
         "local t = {} for i = 1, GetNumAddOns() do t[i] = (GetAddOnInfo(i)) end return t",
@@ -46,14 +35,8 @@ fn by_index(s: &UiScript) -> Vec<String> {
     .unwrap()
 }
 
-/// **The index space is `## Title`-sorted, case-insensitively — not folder order.**
-///
-/// Comparator `0x51deb0` resolves both sides through `AddOn_GetTitle 0x51df20` and compares with
-/// `SStrCmpI` (`0x64a4c0` → `_strnicmp 0x414310`, which folds `'A'..'Z'` by `+0x20` on both
-/// operands — ASCII only, which is what `to_ascii_lowercase` is).
-///
-/// `"Middle"` is the case control: a byte-wise sort would put every capital before every
-/// lowercase and answer `Middle, aardvark, zebra`.
+/// Comparator `0x51deb0` compares `AddOn_GetTitle` (`0x51df20`) with `SStrCmpI` (`0x64a4c0`,
+/// `_strnicmp 0x414310`), folding ASCII only; a byte-wise sort would put `"Middle"` first.
 #[test]
 fn the_index_space_is_title_sorted_case_insensitively_and_not_registry_order() {
     let mut s = seeded();
@@ -61,9 +44,8 @@ fn the_index_space_is_title_sorted_case_insensitively_and_not_registry_order() {
     assert_eq!(by_index(&s), vec!["Zulu", "Mike", "Alpha"]);
 }
 
-/// **A record with no `## Title` sorts under its FOLDER name**, which is the comparator's
-/// fallback: `AddOn_GetTitle` misses (`0x51e046` returns 0) and `0x51ded0`/`0x51ded6` substitute
-/// the name the array holds.
+/// The comparator's fallback: `AddOn_GetTitle` misses (`0x51e046`) and `0x51ded0`/`0x51ded6`
+/// substitute the folder name.
 #[test]
 fn a_titleless_addon_sorts_under_its_folder_name() {
     let mut s = UiScript::new().unwrap();
@@ -76,7 +58,6 @@ fn a_titleless_addon_sorts_under_its_folder_name() {
                 enabled: true,
                 ..Default::default()
             },
-            // No title at all — sorts as "bravo", between nothing and "zzz".
             AddOnInfo {
                 name: "bravo".into(),
                 interface: 11200,
@@ -92,11 +73,8 @@ fn a_titleless_addon_sorts_under_its_folder_name() {
     assert_eq!(by_index(&s), vec!["bravo", "Yankee"]);
 }
 
-/// **There is no index space until `SMSG_ADDON_INFO` arrives** — `[0xbe1b90]` is zeroed by the
-/// registry reset `0x51fad1` and written nowhere but the reply's own rebuild.
-///
-/// The registry is fully populated here; only the array is absent. The raise is the same one an
-/// out-of-range index takes, because it *is* the same unsigned bound against a count of zero.
+/// The count `[0xbe1b90]` is zeroed by the registry reset (`0x51fad1`) and written only by the
+/// reply's rebuild, so before it an index raises the ordinary range error against 0.
 #[test]
 fn there_is_no_index_space_until_the_server_answers() {
     let s = seeded();
@@ -111,25 +89,19 @@ fn there_is_no_index_space_until_the_server_answers() {
         raised.contains("AddOn index must be in the range of 1 to 0"),
         "{raised}"
     );
-    // The registry is there all along — the NAME form never went through the array, it probes the
-    // master registry hash (`0x51df20`'s own lookup), so it answers for an addon the index space
-    // cannot reach.
+    // The name form probes the registry hash (`0x51df20`), not the array.
     assert_eq!(
         s.eval::<String>("return (GetAddOnInfo('Alpha'))").ok(),
         Some("Alpha".into())
     );
 }
 
-/// **A record the server hid is gone from the index space and still answers by name.**
-///
-/// `status = 2` sets `[rec+0x29] = 1` (`0x51db84`) and the rebuild's `0x51dc4f`/`0x51dc54` drops
-/// it. On a stock install that is all twelve `Blizzard_*` addons, which is why the reference's own
-/// AddOns list shows the player's addons and none of Blizzard's — and it is why the name form has
-/// to keep working, since `LoadAddOn("Blizzard_TalentUI")` is how the talent window opens.
+/// `status = 2` sets `[rec+0x29]` (`0x51db84`) and the rebuild drops it (`0x51dc4f`/`0x51dc54`);
+/// a stock install hides the twelve `Blizzard_*` addons this way, and they still load by name.
 #[test]
 fn a_hidden_addon_leaves_the_index_space_but_still_answers_by_name() {
     let mut s = seeded();
-    s.note_addon_info_reply(&["mike".into()]); // case-insensitive, as every name compare here is
+    s.note_addon_info_reply(&["mike".into()]); // names match case-insensitively
     assert_eq!(s.eval::<i64>("return GetNumAddOns()").ok(), Some(2));
     assert_eq!(by_index(&s), vec!["Zulu", "Alpha"]);
     assert_eq!(
@@ -138,8 +110,6 @@ fn a_hidden_addon_leaves_the_index_space_but_still_answers_by_name() {
     );
 }
 
-/// **An empty reply is not the same as no reply.** A server that hides nothing still brings the
-/// array into existence; only silence leaves it at zero.
 #[test]
 fn a_reply_that_hides_nothing_still_builds_the_array() {
     let mut s = seeded();
diff --git a/crates/benilla-ui/src/script/tests/anchors.rs b/crates/benilla-ui/src/script/tests/anchors.rs
index 923ca467..63394d14 100644
--- a/crates/benilla-ui/src/script/tests/anchors.rs
+++ b/crates/benilla-ui/src/script/tests/anchors.rs
@@ -1,12 +1,10 @@
-//! SetPoint + resolve → GetWidth/GetHeight + rect.
+//! `SetPoint` and the anchor resolve: sizes, rects, and the reference's `SetPoint` raises.
 
 use super::common::script;
 use crate::layout::Rect;
 
-// Regression: an *explicit* `nil` relativeTo must still consume its argument slot, so the
-// relativePoint + offsets that follow line up. The `SetPoint("P", nil, "P", x, y)` form is the
-// common FrameXML idiom for "anchor to the screen at an offset"; a leading nil that failed to
-// advance the cursor silently dropped the offsets (screen-anchored frames pinned to the corner).
+// FrameXML's anchor-to-the-screen idiom, `SetPoint("P", nil, "P", x, y)`: the explicit `nil`
+// still takes its argument slot, so the offsets after it apply.
 #[test]
 fn setpoint_explicit_nil_relative_to_keeps_offsets() {
     let mut s = script();
@@ -52,8 +50,8 @@ fn setpoint_resolve_size_and_rect() {
     assert_eq!(w, 200.0);
     assert_eq!(h, 50.0);
 
-    // Hand-computed (layout.md oracle): TOPLEFT anchored to screen [0,0,600,800] at (10,-5), size
-    // 200×50 → Rect(bottom 545, left 10, top 595, right 210).
+    // Hand-computed against the reference rect assembly (`0x767a20`): TOPLEFT anchored to screen
+    // [0,0,600,800] at (10,-5), size 200×50 → Rect(bottom 545, left 10, top 595, right 210).
     let quads = s.extract();
     let frame_rect = quads
         .iter()
@@ -68,22 +66,16 @@ fn setpoint_resolve_size_and_rect() {
 #[test]
 fn getwidth_falls_back_to_explicit_size_before_resolve() {
     let s = script();
-    // No SetPoint ⇒ unresolvable; GetWidth returns the explicit SetWidth value.
     let w: f32 = s
         .eval(r#"local f = CreateFrame("Frame"); f:SetWidth(123); return f:GetWidth()"#)
         .unwrap();
     assert_eq!(w, 123.0);
 }
 
-/// A *named* `relativeTo` that does not resolve **RAISES** and abandons the call — the reference's
-/// `luaL_error(0x87ccd4, "%s:SetPoint(): Couldn't find region named '%s'")`, with no fallback and
-/// no no-op (decision 2176; 2105 pinned the bytes and deferred the change until the addon survey
-/// could see engine warnings). The region path is the same registered function, so it raises the
-/// same way — and both quote the receiver's own name, `<unnamed>` (`0x84c7f0`) when it has none.
-///
-/// **This replaces a parent/owner fallback plus a warning.** That fallback is what misdirected
-/// ItemTextFrame's scrollbar track onto the parchment; the XML half of the same miss is a
-/// different law and keeps its warning (`Loader::apply_anchor`, `0x767800`).
+/// A named `relativeTo` that does not resolve raises and abandons the call, with no fallback
+/// (`0x87ccd4`); the region path raises the same, both quoting the receiver's name, `<unnamed>`
+/// (`0x84c7f0`) when it has none. An XML anchor's miss warns instead (`Loader::apply_anchor`,
+/// `0x767800`).
 #[test]
 fn setpoint_unresolved_name_raises() {
     let mut s = script();
@@ -110,12 +102,11 @@ fn setpoint_unresolved_name_raises() {
         "region path (anonymous receiver): {e}"
     );
 
-    // The anchor was ABANDONED, not applied to the parent: the frame still has none.
     let n: i64 = s.eval("return Orphan:GetNumPoints()").unwrap();
     assert_eq!(n, 0, "the raise must leave no anchor behind");
 
-    // `SetAllPoints` has its own string, and a NUMBER takes the name path there (`lua_isstring`)
-    // where `SetPoint` would read it as an offset.
+    // `SetAllPoints` has its own message, and a number takes the name path there (`lua_isstring`)
+    // where `SetPoint` reads it as an offset.
     let e = s
         .run(r#"Orphan:SetAllPoints("NoSuchFrame")"#)
         .unwrap_err()
@@ -130,22 +121,16 @@ fn setpoint_unresolved_name_raises() {
         "a number is a string to `lua_isstring`, so it is looked up as `_G[\"42\"]`: {e}"
     );
 
-    // A resolvable name still works, and warns about nothing.
     s.run(r#"CreateFrame("Frame", "Target"); Orphan:SetPoint("BOTTOMLEFT", "Target", "TOPLEFT")"#)
         .unwrap();
     assert!(s.take_warnings().is_empty());
 }
 
-/// The other four raises of the same ladder, each read out of the reference image.
-///
-/// * **Usage** `0x87cc28` — an absent `relativeTo` is `TNONE` and fails the `lua_type(L,3)` gate
-///   (`0x7a25e6`–`0x7a2620`), so a one-argument `SetPoint` is an error on a 1.12 client. Stock
-///   content makes none (349 call sites, arity histogram `{3:5, 4:1, 5:343}`); five sites in the
-///   219-addon vanilla corpus do, all of them in multi-client code.
-/// * **Unknown region point** `0x87cd04`, from the 9-entry scan `0x6f1840`.
-/// * **trying to anchor to itself** `0x87cca8` / `0x87cd54`.
-/// * And the ORDER is observable: the two tag gates run before the point-name scan, so an unknown
-///   point with an absent `relativeTo` answers Usage, not "Unknown region point".
+/// The reference's other `SetPoint` raises: Usage (`0x87cc28`) when `relativeTo` is absent, since
+/// `lua_type(L,3)` is `TNONE` at the gate (`0x7a25e6-0x7a2620`); "Unknown region point"
+/// (`0x87cd04`, the 9-entry scan `0x6f1840`); "trying to anchor to itself" (`0x87cca8`,
+/// `0x87cd54`). The type gates run before the point scan, so an unknown point with no
+/// `relativeTo` answers Usage.
 #[test]
 fn the_other_setpoint_raises() {
     let s = script();
@@ -163,7 +148,6 @@ fn the_other_setpoint_raises() {
         .to_string();
     assert!(e.contains("Ladder:SetPoint(): Unknown region point"), "{e}");
 
-    // Unknown point AND absent relativeTo: the tag gate is first, so this is Usage.
     let e = s
         .run(r#"Ladder:SetPoint("MIDDLE")"#)
         .unwrap_err()
@@ -180,18 +164,14 @@ fn the_other_setpoint_raises() {
     );
 }
 
-/// **A trailing explicit `nil` is PRESENT, and absent is absent** — the one thing that would make
-/// the Usage raise over-fire. `lua_type(L,3)` distinguishes `LUA_TNIL` (0, the screen-root arm)
-/// from `LUA_TNONE` (−1, which fails the gate), so the ladder must see the argument count Lua saw
-/// and not a tuple padded or trimmed on the way in.
+/// `lua_type(L,3)` tells `LUA_TNIL` (0, the screen root) from `LUA_TNONE` (-1, Usage), so the
+/// raise ladder must see the argument count Lua saw, not a padded or trimmed tuple.
 #[test]
 fn a_trailing_nil_relative_to_is_present_where_an_absent_one_is_not() {
     let s = script();
     s.run(r#"f = CreateFrame("Frame", "Trail")"#).unwrap();
-    // Present-and-nil: legal, the screen root, no offsets.
     s.run(r#"Trail:SetPoint("CENTER", nil)"#).unwrap();
     assert_eq!(s.eval::<i64>("return Trail:GetNumPoints()").unwrap(), 1);
-    // Absent: Usage.
     let e = s
         .run(r#"Trail:SetPoint("CENTER")"#)
         .unwrap_err()
@@ -199,10 +179,8 @@ fn a_trailing_nil_relative_to_is_present_where_an_absent_one_is_not() {
     assert!(e.contains("Usage:"), "{e}");
 }
 
-/// An explicit `nil` `relativeTo` is the **SCREEN ROOT** (`0x7a2710 mov eax,ds:0xcf0bd8`), not the
-/// parent — the arm benilla answered with the parent until 2176. `UIParent.lua:1549` is the one
-/// stock site; fourteen corpus sites take it, every one of them meaning "the screen"
-/// (`pfUI`'s screenshot caption, `FixCTGroups`' cursor-space plate).
+/// An explicit `nil` `relativeTo` is the screen root, not the parent (`0x7a2710` loads it from
+/// `0xcf0bd8`); the one stock site is `UIParent.lua:1549`.
 #[test]
 fn an_explicit_nil_relative_to_is_the_screen_not_the_parent() {
     let mut s = script();
@@ -226,21 +204,8 @@ fn an_explicit_nil_relative_to_is_the_screen_not_the_parent() {
     );
 }
 
-/// **A region whose OWNER has no rect still resolves from its own anchors.**
-///
-/// `layout.rs`'s region pass used to `continue` when `resolved` held nothing for the owner frame.
-/// But the owner's rect is only the *fallback* for axes the region's own anchors do not pin — a
-/// region anchored fully to some other frame needs nothing from its owner, and the reference
-/// resolves it. Skipping made an ordinary addon shape silently invisible: a bare container frame
-/// (`CreateFrame("Frame", n, parent)` with no size and no `SetPoint`) holding a region anchored
-/// elsewhere.
-///
-/// Found by reproducing the director's MapCoords report. Its world-map readout computed the right
-/// string every single frame — `Cursor Coords: … Player Coords: …` — and was never given a
-/// position, with no error raised anywhere. Three of its four frames are this shape.
-///
-/// The control matters as much as the subject: a SIZED owner must be unaffected, or the fix has
-/// traded one wrong layout for another.
+/// A region resolves from its own anchors and size; its owner supplies only the scale, so a region
+/// anchored elsewhere resolves under an unpositioned owner. A sized owner is the control.
 #[test]
 fn a_region_resolves_even_when_its_owner_frame_has_no_rect() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -268,14 +233,13 @@ fn a_region_resolves_even_when_its_owner_frame_has_no_rect() {
     .unwrap();
     s.resolve();
 
-    // The owner genuinely has no rect — that part is correct and must stay true.
     assert_eq!(
         s.eval::<Option<f32>>("return BareOwner:GetLeft()").unwrap(),
         None,
         "an unpositioned frame has no rect; the fix must not invent one for it"
     );
 
-    // ...and its region resolves anyway, from its own anchor: host's BOTTOMLEFT (100,50) + (5,7).
+    // Host's BOTTOMLEFT (100,50) plus the (5,7) offset.
     assert_eq!(
         s.eval::<Option<f32>>("return BareMark:GetLeft()").unwrap(),
         Some(105.0),
@@ -286,7 +250,6 @@ fn a_region_resolves_even_when_its_owner_frame_has_no_rect() {
             .unwrap(),
         Some(57.0)
     );
-    // The control is unmoved.
     assert_eq!(
         s.eval::<Option<f32>>("return SizedMark:GetLeft()").unwrap(),
         Some(105.0),
@@ -294,19 +257,10 @@ fn a_region_resolves_even_when_its_owner_frame_has_no_rect() {
     );
 }
 
-/// **…but a region the owner's rect is the ONLY candidate for stays unresolved with it.**
-///
-/// The other half of the law above, and the half that shipped wrong: an unpinned axis on an
-/// unpositioned owner has nothing to fall back to, so standing a zero rect in for the missing owner
-/// puts the region at the **screen origin** instead of nowhere. That is not a degenerate rect, it is
-/// a wrong position — and a template whose textures chain off each other turns it into real,
-/// visible geometry a few links down.
-///
-/// Reported as B264 (carni, 2026-08-13): opening the social pane drew a stray dropdown capsule at
-/// the bottom of the screen next to the action bar. `FriendsDropDown` carries no anchors —
-/// *exactly* as the reference's own `FriendsDropDown` does (`FriendsFrame.xml` l.598), and the
-/// reference draws nothing — so every texture of `UIDropDownMenuTemplate` hung off a phantom rect
-/// at (0,0). The shape below is that template's first two textures verbatim.
+/// A region anchored to an unpositioned owner has no rect, nor does the chain off it; a zero rect
+/// in its place would draw at the screen origin. The shape is `UIDropDownMenuTemplate`'s first two
+/// textures under the anchorless `FriendsDropDown` (`FriendsFrame.xml:598`), which the reference
+/// does not draw.
 #[test]
 fn an_unanchored_owners_region_chain_resolves_nowhere() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -349,24 +303,14 @@ fn an_unanchored_owners_region_chain_resolves_nowhere() {
     );
 }
 
-/// **Geometry answers inside the same call stack that moved it** — the seam that killed 97 addons.
-///
-/// A handler creates a frame, anchors it, shows it and then measures it, all before any resolve
-/// pass can run. `Dewdrop-2.0.lua` — embedded in ~65 corpus addons — does exactly this in its menu
-/// `Open`: `local left = frame:GetLeft()` (l.1942) then `curX - left - width/2` (l.1960). Our
-/// getters read a cache filled by the per-frame `resolve()`, so `left` was nil and the arithmetic
-/// died. **97 of the 108 addons that drew and then raised on being touched died on that one line**,
-/// with no missing verb anywhere.
-///
-/// The readers settle the graph on demand now. The second half of the test is the one that keeps
-/// it honest: a *further* move inside the same stack must also be visible, or the fix is just a
-/// one-shot warm-up.
+/// The geometry readers settle the layout on demand, so a frame moved inside a call stack reports
+/// its new rect in that stack, again after a second move.
 #[test]
 fn geometry_answers_within_the_call_stack_that_moved_it() {
     let mut s = crate::script::UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
 
-    // Dewdrop's shape, in one eval — no resolve() between the writes and the read.
+    // Dewdrop-2.0's menu `Open` in one eval: no `resolve()` between the writes and the read.
     let (left, bottom): (Option<f32>, Option<f32>) = s
         .eval(
             r#"
@@ -384,7 +328,6 @@ fn geometry_answers_within_the_call_stack_that_moved_it() {
         "a frame must report its geometry in the stack that anchored it"
     );
 
-    // ...and a LATER move in the same stack is visible too — not a stale first answer.
     let moved: Option<f32> = s
         .eval(
             r#"
@@ -396,7 +339,6 @@ fn geometry_answers_within_the_call_stack_that_moved_it() {
         .unwrap();
     assert_eq!(moved, Some(200.0), "the settle must re-run after each move");
 
-    // Width/height and the centre reader take the same path.
     assert_eq!(
         s.eval::<(f32, f32)>("return MenuLike:GetWidth(), MenuLike:GetHeight()")
             .unwrap(),
diff --git a/crates/benilla-ui/src/script/tests/backdrop.rs b/crates/benilla-ui/src/script/tests/backdrop.rs
index 9007afd0..5a4a8d1d 100644
--- a/crates/benilla-ui/src/script/tests/backdrop.rs
+++ b/crates/benilla-ui/src/script/tests/backdrop.rs
@@ -1,10 +1,9 @@
-//! Backdrop: Lua verbs + extract emission (backdrop-mechanism.md).
+//! The backdrop Lua verbs and extract emission (the reference's Backdrop object, `0x77e5f0`).
 
 use super::common::script;
 use crate::script::*;
 
-// SetBackdrop installs the plate; SetBackdropColor tints the bg only, SetBackdropBorderColor all 8
-// border pieces; extract emits bg-then-border at the frame's own slot with those colors.
+// SetBackdropColor tints only the bg, SetBackdropBorderColor the 8 border pieces.
 #[test]
 fn backdrop_installs_and_extracts_pieces_with_colors() {
     let mut s = script();
@@ -35,24 +34,17 @@ fn backdrop_installs_and_extracts_pieces_with_colors() {
         .collect();
     // bg (1) + 8 border pieces.
     assert_eq!(pieces.len(), 9);
-    // First is the bg, tinted the tooltip background color — QUANTIZED. The reference's colour
-    // field is a packed `0xAARRGGBB` byte quad and the setter converts `×255 + 0.5` through
-    // `__ftol` (wow-re `numeric-arg-coercion-law.md` Q4), so `0.09` stores as 23 and reads back
-    // as `23/255`. This assertion used to hold `0.09` exactly, which was our lossless `[f32; 4]`
-    // showing through a store the client cannot make.
+    // The colour is a packed `0xAARRGGBB` byte quad, stored as `×255 + 0.5` through `__ftol`
+    // (`SetBackdropColor 0x777d30`), so 0.09 reads back as 23/255.
     assert_eq!(pieces[0].0, "bg");
     let q = |x: f32| f32::from((x * 255.0 + 0.5) as u8) / 255.0;
     assert_eq!(pieces[0].1, [q(0.09), q(0.09), q(0.19), 1.0]);
-    // The remaining 8 are the border, white, from the edge file.
     assert!(pieces[1..]
         .iter()
         .all(|(p, c)| p == "edge" && *c == [1.0, 1.0, 1.0, 1.0]));
 }
 
-// `GetBackdrop()` — the four traps of `0x777370` (wow-re `widget-api-batch-benilla.md` Q5), pinned
-// where an addon can observe them. The corpus caller is `BuffCheck2.lua:448`, which reads the table
-// back, edits `insets`, and feeds it straight to `SetBackdrop` — so a wrong `tile` type or a missing
-// ctor default does not just read wrong, it round-trips wrong.
+// The four traps of `GetBackdrop()` (`0x777370`), as an addon observes them.
 #[test]
 fn get_backdrop_reconstructs_from_the_struct() {
     let s = script();
@@ -123,8 +115,7 @@ fn get_backdrop_reconstructs_from_the_struct() {
     .unwrap();
 }
 
-// BuffCheck2.lua:448's exact shape: read the plate back, edit `insets`, push it straight back in.
-// It is the whole reason this method exists in our client, so it is the test that must not rot.
+// The shape of `BuffCheck2.lua:448`: read the plate back, edit `insets`, set it again.
 #[test]
 fn get_backdrop_round_trips_through_set_backdrop() {
     let mut s = script();
@@ -151,7 +142,7 @@ fn get_backdrop_round_trips_through_set_backdrop() {
     )
     .unwrap();
     s.resolve();
-    // The plate still draws: bg + 8 border pieces, unchanged by the round trip.
+    // bg (1) + 8 border pieces.
     assert_eq!(
         s.extract()
             .iter()
@@ -161,7 +152,6 @@ fn get_backdrop_round_trips_through_set_backdrop() {
     );
 }
 
-// SetBackdrop(nil) tears the plate down (no pieces after).
 #[test]
 fn set_backdrop_nil_tears_down() {
     let mut s = script();
@@ -183,18 +173,8 @@ fn set_backdrop_nil_tears_down() {
         .all(|q| !matches!(q.content, QuadContent::Backdrop { .. })));
 }
 
-/// **The colour setters' argument gating is asymmetric, and getting it backwards is worse than
-/// the bug it replaces** (wow-re `numeric-arg-coercion-law.md` Q4, VERIFIED at `0x777d30` /
-/// `0x7780d0`).
-///
-/// r/g/b go through a bare `lua_tonumber` — a `nil` channel is `0.0` and the call COMPLETES.
-/// benilla typed them `f32` and raised, which killed ShaguTweaks at `helpers.lua:248`, where
-/// `color.r` comes off a table that does not always have one.
-///
-/// Alpha is different: `lua_isnumber`-gated at `0x778227` with `1.0f` staged at `0x778220`, so a
-/// missing **or nil** alpha is OPAQUE. The tempting blanket fix — "treat every nil as 0.0, like
-/// its neighbours" — would have turned every one of those borders transparent, which reads as a
-/// rendering fault rather than an API bug and is the reason this test names both halves.
+/// The colour setters (`0x777d30`, `0x7780d0`) read r/g/b with a bare `lua_tonumber` (nil is 0.0)
+/// and gate alpha on `lua_isnumber` (`0x778227`) over a staged 1.0 (`0x778220`).
 #[test]
 fn backdrop_colors_coerce_rgb_but_default_alpha_opaque() {
     let s = script();
@@ -206,7 +186,6 @@ fn backdrop_colors_coerce_rgb_but_default_alpha_opaque() {
     )
     .unwrap();
 
-    // A nil channel is 0.0 and the call completes — no raise.
     s.run("f:SetBackdropBorderColor(nil, 1, 1, 1)").unwrap();
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return f:GetBackdropBorderColor()")
@@ -214,7 +193,6 @@ fn backdrop_colors_coerce_rgb_but_default_alpha_opaque() {
         (0.0, 1.0, 1.0, 1.0)
     );
 
-    // A missing alpha is 1.0, and so is an explicit nil one — NOT 0.0.
     s.run("f:SetBackdropColor(0.2, 0.4, 0.6)").unwrap();
     let (_, _, _, a) = s
         .eval::<(f32, f32, f32, f32)>("return f:GetBackdropColor()")
@@ -235,7 +213,6 @@ fn backdrop_colors_coerce_rgb_but_default_alpha_opaque() {
         .eval::<(f32, f32, f32, f32)>("return f:GetBackdropColor()")
         .unwrap();
     assert_eq!((r, g, b), (1.0, 0.0, 0.0));
-    // Quantized `×255 + 0.5` through `__ftol`: 0.5 -> 128/255, not 0.5 exactly. The field is a
-    // packed 0xAARRGGBB byte quad and nothing finer survives the store.
+    // Stored as a byte: 0.5 reads back as 128/255.
     assert_eq!(a, 128.0 / 255.0);
 }
diff --git a/crates/benilla-ui/src/script/tests/button.rs b/crates/benilla-ui/src/script/tests/button.rs
index 3df14a6a..4ebf3132 100644
--- a/crates/benilla-ui/src/script/tests/button.rs
+++ b/crates/benilla-ui/src/script/tests/button.rs
@@ -14,7 +14,6 @@ fn button_methods_exist_only_on_buttons() {
     "#,
     )
     .unwrap();
-    // Duck-typing honesty across the class chain (RF-28 method sets).
     assert!(s.eval::<bool>("return f.SetText == nil").unwrap());
     assert!(s.eval::<bool>("return f.SetChecked == nil").unwrap());
     assert!(s.eval::<bool>("return b.SetText ~= nil").unwrap());
@@ -22,7 +21,7 @@ fn button_methods_exist_only_on_buttons() {
     assert!(s.eval::<bool>("return b.SetValue == nil").unwrap());
     assert!(s.eval::<bool>("return cb.SetChecked ~= nil").unwrap());
     assert!(s.eval::<bool>("return cb.SetNormalTexture ~= nil").unwrap());
-    // Buttons are mouse-enabled by construction (the client ctor enables input).
+    // The 1.12 client's Button constructor enables mouse input; a Frame's does not.
     assert!(s.eval::<bool>("return b:IsMouseEnabled()").unwrap());
     assert!(!s.eval::<bool>("return f:IsMouseEnabled()").unwrap());
 }
@@ -55,22 +54,18 @@ fn button_state_textures_switch_with_interaction() {
             .collect()
     };
 
-    // Idle: normal only (pushed/disabled suppressed; not hovered ⇒ no highlight).
     assert_eq!(visible(&s), vec!["Interface\\N.blp".to_string()]);
-    // The ButtonText always draws.
     assert!(s
         .extract()
         .iter()
         .any(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "Go")));
 
-    // Hover: normal + additive highlight.
     s.mouse_move(50.0, 50.0);
     let v = visible(&s);
     assert!(
         v.contains(&"Interface\\N.blp".to_string()) && v.contains(&"Interface\\H.blp".to_string())
     );
 
-    // Held down over it: pushed replaces normal (highlight still hovering).
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     let v = visible(&s);
     assert!(
@@ -78,31 +73,18 @@ fn button_state_textures_switch_with_interaction() {
     );
     s.mouse_button(50.0, 50.0, "LeftButton", false);
 
-    // Disabled: disabled texture only, and no highlight even under the cursor.
     s.run("StateBtn:Disable()").unwrap();
     assert_eq!(visible(&s), vec!["Interface\\D.blp".to_string()]);
-    // 0, not false, and not nil — the number the real client answers.
+    // The 1.12 client answers the number 0, not false or nil.
     assert_eq!(s.eval::<i64>("return StateBtn:IsEnabled()").unwrap(), 0);
     s.run("StateBtn:Enable()").unwrap();
     assert_eq!(s.eval::<String>("return StateBtn:GetText()").unwrap(), "Go");
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The shown texture is STICKY: a state with no art of its own changes nothing.**
-///
-/// `SetState 0x779790` gates the hide-old step *and* the show-new step on the NEW state's slot
-/// being non-null (wow-re `button-check-and-state-texture.md` §2), so the shown pointer `+0x4c4`
-/// only ever moves onto a real texture — it is never cleared, and there is no fallback path in the
-/// function at all. Three consequences, and they are one mechanism seen from three sides:
-///
-/// - a press with no `<PushedTexture>` keeps the normal art (which our old model hard-coded as a
-///   `pushed.or(normal)` fallback — the special case *was* this rule, seen from one side);
-/// - **`Disable()` with no `<DisabledTexture>` keeps the normal art** — B369, where the reference's
-///   `ReputationDetailAtWarCheckBox` stays a visible box for a faction whose war flag is locked
-///   while ours went to a bare grey label;
-/// - a state texture assigned while the button is in a *different* state is not displayed
-///   (`0x778fd0`'s `idx == [this+0x328]` gate), so a button disabled *before* it is given normal
-///   art draws nothing — the two disabled cases differ only in whether anything was ever shown.
+/// `SetState 0x779790` moves the shown texture (`+0x4c4`) only onto a non-null slot, so a press or
+/// a disable with no art of its own keeps what was shown; art written into another state's slot
+/// is stored, not shown (`0x778fd0`'s `idx == [this+0x328]` gate).
 #[test]
 fn a_state_with_no_texture_leaves_the_shown_one_standing() {
     let mut s = script();
@@ -131,22 +113,18 @@ fn a_state_with_no_texture_leaves_the_shown_one_standing() {
 
     assert_eq!(visible(&s, "StickyBtn"), n, "resting on its normal art");
 
-    // Pressed with no PushedTexture: SetState(2) finds a null slot, so nothing moves.
     s.mouse_move(50.0, 50.0);
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     assert_eq!(visible(&s, "StickyBtn"), n, "a press with no pushed art");
     s.mouse_button(50.0, 50.0, "LeftButton", false);
     s.mouse_move(400.0, 400.0);
 
-    // Disabled with no DisabledTexture: the same null slot, the same nothing. **B369.**
     s.run("StickyBtn:Disable()").unwrap();
     assert_eq!(
         visible(&s, "StickyBtn"),
         n,
         "a disable with no disabled art leaves the box on screen"
     );
-    // Giving it disabled art NOW does show it — `0x778fd0` pushes to `+0x4c4` because the slot
-    // being written IS the current state's.
     s.run("StickyBtn:SetDisabledTexture(\"Interface\\\\D.blp\")")
         .unwrap();
     assert_eq!(
@@ -157,8 +135,6 @@ fn a_state_with_no_texture_leaves_the_shown_one_standing() {
     s.run("StickyBtn:Enable()").unwrap();
     assert_eq!(visible(&s, "StickyBtn"), n, "back to normal on Enable");
 
-    // The other side of the same gate: a button disabled BEFORE it has normal art shows nothing,
-    // because the write lands in a slot that is not the current state's.
     s.run(
         r#"
         local b = CreateFrame("Button", "BornDeadBtn")
@@ -176,14 +152,9 @@ fn a_state_with_no_texture_leaves_the_shown_one_standing() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`Disable()` switches off the HIGHLIGHT draw LAYER, not just the HighlightTexture.**
-///
-/// The helper both `Enable`/`Disable` and the constructor reach (`0x779160`) does two things: the
-/// `SetState` above, and `0x7791bb push 4; call 0x76a730` — the per-layer enable for layer 4,
-/// written into the same `[frame+0x198]` array `Enable/DisableDrawLayer` writes. So a region the
-/// button owns in HIGHLIGHT that is not its HighlightTexture goes dark with it, and an explicit
-/// `EnableDrawLayer` brings the whole layer back on a still-disabled button. Our old rule gated
-/// the HighlightTexture alone on `enabled`, which agreed on the common case and not on this one.
+/// The enable helper `0x779160` (reached by `Enable`, `Disable` and the constructor) also writes
+/// layer 4, HIGHLIGHT, into the array `Enable/DisableDrawLayer` write (`[frame+0x198]`, `0x7791bb`
+/// → `0x76a730`), so a disable darkens every HIGHLIGHT region and `EnableDrawLayer` relights them.
 #[test]
 fn disabling_a_button_takes_its_whole_highlight_layer() {
     let mut s = script();
@@ -213,7 +184,6 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
             .collect()
     };
 
-    // Hovered and enabled: normal art, the button's own HIGHLIGHT region, and the HighlightTexture.
     s.mouse_move(50.0, 50.0);
     let v = art(&s);
     for want in ["Interface\\N.blp", "Interface\\Own.blp", "Interface\\H.blp"] {
@@ -223,8 +193,6 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
         );
     }
 
-    // Disabled under the same cursor: the layer is off, so BOTH highlight-layer regions go — and
-    // the normal art stays, because no state texture moved (the sticky rule).
     s.run("LayerBtn:Disable()").unwrap();
     assert_eq!(
         art(&s),
@@ -232,7 +200,6 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
         "the whole HIGHLIGHT layer goes with the disable"
     );
 
-    // The layer is a layer: turning it back on lights both again, disabled or not.
     s.run(r#"LayerBtn:EnableDrawLayer("HIGHLIGHT")"#).unwrap();
     let v = art(&s);
     assert!(
@@ -246,7 +213,6 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
         "and it really is still disabled"
     );
 
-    // …and Enable() writes the same one array, so it undoes an addon's DisableDrawLayer.
     s.run(r#"LayerBtn:DisableDrawLayer("HIGHLIGHT") LayerBtn:Enable()"#)
         .unwrap();
     let v = art(&s);
@@ -257,12 +223,8 @@ fn disabling_a_button_takes_its_whole_highlight_layer() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A right-click lights a button up too** — the director's report, and `0x77924b`'s law.
-///
-/// `CButton::OnMouseDown` gates the PushedTexture on `[this+0x330] & (m | m << 8)`: the button
-/// registered for that mouse button in **either** variant. Not on the click firing, not on the
-/// handler doing anything — which is why right-clicking an action, spellbook or pet slot flashes,
-/// while right-clicking a default `LeftButtonUp` button does not.
+/// `CButton::OnMouseDown` shows the pushed texture when the button is registered for that mouse
+/// button, up or down (`0x77924b`: `[this+0x330] & (m | m << 8)`), whether or not a click fires.
 #[test]
 fn any_registered_mouse_button_shows_the_pushed_texture() {
     let mut s = script();
@@ -290,7 +252,6 @@ fn any_registered_mouse_button_shows_the_pushed_texture() {
             .any(|q| matches!(&q.content, QuadContent::Texture { path: Some(p), .. } if p == path))
     };
 
-    // The bar slot lights under EITHER button.
     for button in ["LeftButton", "RightButton"] {
         s.mouse_move(50.0, 50.0);
         s.mouse_button(50.0, 50.0, button, true);
@@ -307,7 +268,6 @@ fn any_registered_mouse_button_shows_the_pushed_texture() {
         assert!(shows(&s, "Interface\\BarN.blp"), "the release restores it");
     }
 
-    // The plain button lights under the left only — `0x77924b` is a real gate, not a formality.
     s.mouse_move(250.0, 50.0);
     s.mouse_button(250.0, 50.0, "RightButton", true);
     assert!(
@@ -321,9 +281,8 @@ fn any_registered_mouse_button_shows_the_pushed_texture() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `SetButtonState`/`GetButtonState` (`0x780270`/`0x780180`) — the scripted press state the ref's
-/// `ActionButtonDown/Up` keybind pair drives: PUSHED shows the pushed texture with no mouse
-/// involved, NORMAL restores, unknown states error, and a disabled button answers DISABLED.
+/// `SetButtonState`/`GetButtonState` (`0x780270`/`0x780180`), the press state stock
+/// `ActionButtonDown`/`Up` drive; an unknown state raises, a disabled button reads DISABLED.
 #[test]
 fn set_button_state_drives_the_pushed_visual() {
     let mut s = script();
@@ -356,9 +315,7 @@ fn set_button_state_drives_the_pushed_visual() {
     assert!(shows(&s, "Interface\\P.blp") && !shows(&s, "Interface\\N.blp"));
     s.run(r#"PushBtn:SetButtonState("NORMAL")"#).unwrap();
     assert!(shows(&s, "Interface\\N.blp") && !shows(&s, "Interface\\P.blp"));
-    // Unknown state: a runtime error, not a silent no-op.
     assert!(s.run(r#"PushBtn:SetButtonState("SIDEWAYS")"#).is_err());
-    // Disabled wins the read (Enable/Disable owns that state, not SetButtonState).
     s.run("PushBtn:Disable()").unwrap();
     assert_eq!(
         s.eval::<String>("return PushBtn:GetButtonState()").unwrap(),
@@ -385,20 +342,17 @@ fn disabled_button_swallows_clicks_checkbutton_toggles_before_onclick() {
     .unwrap();
     s.resolve();
 
-    // Physical click: the checked state flips BEFORE OnClick (the documented contract).
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     s.mouse_button(50.0, 50.0, "LeftButton", false);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 1);
-    // `seen_checked` is whatever `GetChecked()` handed the handler — the NUMBER 1 (1830).
+    // `GetChecked()` answers the number 1, not true.
     assert!(s.eval::<bool>("return seen_checked == 1").unwrap());
     assert!(s.eval::<bool>("return Toggler:GetChecked()").unwrap());
 
-    // Programmatic Click() rides the same path: toggles back off.
     s.run("Toggler:Click()").unwrap();
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
     assert!(!s.eval::<bool>("return Toggler:GetChecked()").unwrap());
 
-    // Disabled: the click is swallowed — no OnClick, no toggle.
     s.run("Toggler:Disable()").unwrap();
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     s.mouse_button(50.0, 50.0, "LeftButton", false);
@@ -406,7 +360,6 @@ fn disabled_button_swallows_clicks_checkbutton_toggles_before_onclick() {
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
     assert!(!s.eval::<bool>("return Toggler:GetChecked()").unwrap());
 
-    // SetChecked takes 1/true/nil (1.12 and Era forms).
     s.run("Toggler:SetChecked(1)").unwrap();
     assert!(s.eval::<bool>("return Toggler:GetChecked()").unwrap());
     s.run("Toggler:SetChecked(nil)").unwrap();
@@ -429,8 +382,7 @@ fn default_registration_is_left_click_only_right_click_reaches_nothing() {
     .unwrap();
     s.resolve();
 
-    // A right-click (press+release, same frame) reaches OnMouseDown/OnMouseUp but never OnClick —
-    // the client's own default registered-click set is {"LeftButtonUp"} only.
+    // The 1.12 client's default registered-click set is {"LeftButtonUp"} alone.
     s.mouse_button(50.0, 50.0, "RightButton", true);
     s.mouse_button(50.0, 50.0, "RightButton", false);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 0);
@@ -463,7 +415,6 @@ fn register_for_clicks_grows_right_click_and_carries_the_button_name() {
     assert_eq!(s.eval::<String>("return click_btn").unwrap(), "RightButton");
     assert_eq!(s.eval::<String>("return arg1_btn").unwrap(), "RightButton");
 
-    // RegisterForClicks replaces the set with its whole vararg list — LeftButtonUp still fires.
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     s.mouse_button(50.0, 50.0, "LeftButton", false);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
@@ -489,14 +440,12 @@ fn down_registration_fires_on_press_and_toggles_checked_once() {
     .unwrap();
     s.resolve();
 
-    // The press alone fires OnClick (down=true) and toggles Checked exactly once.
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 1);
     assert!(s.eval::<bool>("return seen_down == true").unwrap());
     assert!(s.eval::<bool>("return QuickSell:GetChecked()").unwrap());
 
-    // The release does not fire again — "LeftButtonUp" is no longer in the registered set
-    // (RegisterForClicks replaced it, it did not add to it).
+    // `RegisterForClicks` replaced the set, so "LeftButtonUp" no longer fires.
     s.mouse_button(50.0, 50.0, "LeftButton", false);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 1);
     assert!(s.errors().is_empty(), "{:?}", s.errors());
@@ -526,24 +475,20 @@ fn highlight_is_additive_and_state_textures_fill_then_anchor() {
             .find(|q| matches!(&q.content, QuadContent::Texture { path: Some(p), .. } if p == path))
             .expect(path)
     };
-    // The highlight carries the ADD contract (the client's SetHighlightTexture default).
+    // The 1.12 client's `SetHighlightTexture` defaults the texture to ADD.
     assert!(matches!(
         &find("Interface\\Hi.blp").content,
         QuadContent::Texture { additive: true, .. }
     ));
-    // A fresh state texture gets the creation-path implicit SetAllPoints (decision 1310 — the
-    // reference's string setters anchor a freshly built texture to the button outright), whose
-    // two corners pin all four edges: the later 64px size is structurally unread and the ring
-    // FILLS the 36px button.
+    // The reference's string setter anchors a texture it builds with `SetAllPoints`, so the later
+    // 64px size is unread and the ring fills the 36px button.
     let r = find("Interface\\Ring.blp").rect.unwrap();
     assert_eq!(
         (r.left, r.right, r.bottom, r.top),
         (100.0, 136.0, 100.0, 136.0)
     );
-    // The real quickslot-overhang idiom is an ANCHOR, not an anchorless size (ActionButton's
-    // 66×66 UI-Quickslot2 authors `<Anchor point="CENTER">`): one CENTER point replaces only its
-    // own slot, but clearing first leaves the single anchor + the 64px size → the centered
-    // overhang, 100..136 → 86..150.
+    // The quickslot overhang is an anchor (`ActionButtonTemplate.xml`'s 66x66 UI-Quickslot2 is
+    // `<Anchor point="CENTER">`): cleared, then one CENTER point and the 64px size give 86..150.
     s.run(
         r#"
         local n = AddBtn:GetNormalTexture()
@@ -563,7 +508,6 @@ fn highlight_is_additive_and_state_textures_fill_then_anchor() {
         (r.left, r.right, r.bottom, r.top),
         (86.0, 150.0, 86.0, 150.0)
     );
-    // SetBlendMode overrides back to straight alpha.
     s.run(r#"AddBtn:GetHighlightTexture():SetBlendMode("BLEND")"#)
         .unwrap();
     let quads = s.extract();
@@ -581,10 +525,8 @@ fn highlight_is_additive_and_state_textures_fill_then_anchor() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The per-state label fonts (`SetTextFontObject`/`SetDisabledFontObject`, XML `<NormalFont>` etc.):
-/// the ButtonText re-points to the CURRENT state's font object at extract — gold while enabled,
-/// gray after Disable() — with no Lua repaint (the client's UIPanelButtonTemplate label behavior).
-/// An explicit SetTextColor survives the re-point (the client's explicitly-set mask).
+/// The label wears the current state's font object (`SetTextFontObject`, `SetDisabledFontObject`)
+/// with no Lua repaint; its own `SetTextColor` clears the colour's inherit bit and survives that.
 #[test]
 fn button_label_repaints_by_state_font_object() {
     let mut s = script();
@@ -649,30 +591,16 @@ fn button_label_repaints_by_state_font_object() {
         "re-enabled: gold again"
     );
 
-    // An explicit SetTextColor wins over the state font's color (explicitly-set mask).
     s.run("b:GetFontString():SetTextColor(0.1, 0.2, 0.3)")
         .unwrap();
     let c = label_color(&mut s).expect("colored");
     assert!((c[0] - 0.1).abs() < 1e-6 && (c[1] - 0.2).abs() < 1e-6);
 }
 
-/// **The highlighted label is its own font instance — and `LockHighlight` enters it.** The two
-/// halves of the recipe-list look the director asked for: a row turns white under the cursor, and
-/// the SELECTED row stays white with the cursor elsewhere.
-///
-/// Both are one mechanism in the reference. `ClassTrainerSkillButtonTemplate` (the base under
-/// TradeSkill's, Craft's and the class trainer's rows) declares
-/// `<HighlightFont inherits="GameFontHighlight">`, and each window paints its rows by difficulty
-/// with `skillButton:SetTextColor(...)` — orange, yellow, green, gray. If a `SetTextColor` reached
-/// the highlighted state, hovering a row would leave it orange; it does not, because the highlight
-/// instance is a different font instance and the normal one's colour cannot reach it. That is the
-/// first assertion below.
-///
-/// The second is `LockHighlight`. `TradeSkillFrame_Update` blanks a recipe row's highlight texture
-/// (`getglobal("TradeSkillSkill"..i.."Highlight"):SetTexture("")`, Blizzard_TradeSkillUI.lua l.131)
-/// and *then* locks the row it selected (l.144) — with no texture left to pin, the lock can only be
-/// reaching the label. Craft (Blizzard_CraftUI.lua l.234) and the trainer
-/// (Blizzard_TrainerUI.lua l.183) do the same.
+/// The highlight label is its own font instance, put in force by a hover or `LockHighlight`, so the
+/// normal instance's `SetTextColor` cannot reach it: `ClassTrainerSkillButtonTemplate`'s recipe
+/// rows (`<HighlightFont inherits="GameFontHighlight">`) turn white, and
+/// `Blizzard_TradeSkillUI.lua:144` locks the selected row after blanking its highlight texture.
 #[test]
 fn a_locked_or_hovered_button_wears_its_highlight_font_over_its_normal_color() {
     let mut s = script();
@@ -737,7 +665,6 @@ fn a_locked_or_hovered_button_wears_its_highlight_font_over_its_normal_color() {
         "hovered: the HIGHLIGHT instance is in force, and the normal colour cannot reach it"
     );
 
-    // Cursor away again, but the row is the selected one.
     s.resolve();
     s.mouse_move(400.0, 300.0);
     s.run("b:LockHighlight()").unwrap();
@@ -753,8 +680,6 @@ fn a_locked_or_hovered_button_wears_its_highlight_font_over_its_normal_color() {
         "unlocked: back to the difficulty colour"
     );
 
-    // A button with no highlight instance keeps the normal one whole, hover or not — the shape
-    // every plain labelled Button in the corpus has.
     s.run(r#"b:SetHighlightFontObject(nil); b:SetText("Rough Copper Vest")"#)
         .unwrap();
     s.resolve();
@@ -767,14 +692,8 @@ fn a_locked_or_hovered_button_wears_its_highlight_font_over_its_normal_color() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`Button:GetTextWidth` / `GetTextHeight`** — the reference's own Button text-extent readers
-/// (`0x782290` / `0x782390`; wow-re `widget-api-batch-benilla.md` Q8 carves them present on Button
-/// and `GetStringWidth` **absent**). Both forward to the label FontString's own extent slots, which
-/// is what this asserts: answer a host measure for the label, and the BUTTON must report it.
-///
-/// `Bagnon_Forever/database/ui.lua:61` sizes its character-switch dropdown from
-/// `button:GetTextWidth() + 40`, so a nil method took the whole dropdown down — the director could
-/// not switch characters in Bagnon at all.
+/// `Button:GetTextWidth`/`GetTextHeight` (`0x782290`/`0x782390`; Button has no `GetStringWidth`)
+/// forward to the label FontString's extent.
 #[test]
 fn a_button_reports_its_labels_extent() {
     let mut s = script();
@@ -791,7 +710,7 @@ fn a_button_reports_its_labels_extent() {
     .unwrap();
     s.resolve();
 
-    // Unmeasured is 0 — the same "converges next frame" contract every other metric read has.
+    // 0 until the host's measure lands, like every metric read here.
     assert_eq!(
         s.eval::<f64>("return WidthBtn:GetTextWidth()").unwrap(),
         0.0
@@ -814,27 +733,22 @@ fn a_button_reports_its_labels_extent() {
         14.0
     );
 
-    // A Button with no label at all answers 0 rather than raising: the reference dereferences a
-    // FontString pointer (`+0x338`) here that a bare CreateFrame("Button") leaves null, and what it
-    // does then is not byte-read — so this takes the harmless number instead of guessing a crash.
+    // A label-less Button answers 0; the reference reads the label pointer (`+0x338`), null here,
+    // and what it does then is untraced.
     assert_eq!(
         s.eval::<f64>("return LabellessBtn:GetTextWidth()").unwrap(),
         0.0
     );
 
-    // …and it is a BUTTON method: a plain Frame must not have grown one.
     assert!(
         s.eval::<bool>(r#"return CreateFrame("Frame").GetTextWidth == nil"#)
             .unwrap(),
-        "GetTextWidth is Button's, not Region's (wow-re Q8's own split)"
+        "GetTextWidth is Button's, not Region's (the reference's own split)"
     );
 }
 
-/// **`Button:SetFontString` adopts aggressively, and it RAISES** — wow-re
-/// `system/ui/scratch/resize-bounds-and-button-fontstring.md` §5, byte-carved.
-///
-/// The first cut of this binding was a lenient no-op on a bad argument and a bare pointer swap on
-/// a good one. Every line below is a clause of that carve that the plausible reading got wrong.
+/// `Button:SetFontString` (`0x780a60`) re-parents the string, adopts it as the label and destroys
+/// the old one, and raises on anything but a FontString.
 #[test]
 fn set_font_string_adopts_the_label_and_raises_on_anything_else() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -849,28 +763,20 @@ fn set_font_string_adopts_the_label_and_raises_on_anything_else() {
     )
     .unwrap();
 
-    // Adoption binds the string as the label the whole rest of the surface reads.
     s.run("b:SetFontString(fs)").unwrap();
     assert!(s.eval::<bool>("return b:GetFontString() == fs").unwrap());
     s.run("b:SetText(\"Okay\")").unwrap();
     assert_eq!(s.eval::<String>("return fs:GetText()").unwrap(), "Okay");
     assert_eq!(s.eval::<String>("return b:GetText()").unwrap(), "Okay");
 
-    // Re-parented — always, whatever it was parented to before.
     assert!(s.eval::<bool>("return fs:GetParent() == b").unwrap());
-    // The draw layer is forced to ARTWORK on the same call (`0x77fd10(parent, 2, 1)`), and that
-    // half is NOT asserted here for a stated reason: `GetDrawLayer` is one of the client's nine
-    // per-leaf verbs we deliberately do not install (`script::REGION_LEAF_SHARED`'s own note —
-    // "absent is absent"), so there is no Lua way to read it back yet. The binding does it; when
-    // that verb lands, this is where it gets pinned.
+    // It also forces the draw layer to ARTWORK (`0x77fd10(parent, 2, 1)`); not asserted here.
 
-    // Adopting the SAME string again is a total no-op — the first compare in the client, and the
-    // one path that must not run the destroy below.
+    // The same string again is a no-op, the client's first compare, so it is not destroyed.
     s.run("b:SetFontString(fs)").unwrap();
     assert!(s.eval::<bool>("return b:GetFontString() == fs").unwrap());
     assert_eq!(s.eval::<String>("return fs:GetText()").unwrap(), "Okay");
 
-    // A SECOND adoption DESTROYS the first label rather than orphaning it.
     s.run("fs2 = b:CreateFontString(\"MyLabel2\", \"OVERLAY\") b:SetFontString(fs2)")
         .unwrap();
     assert!(s.eval::<bool>("return b:GetFontString() == fs2").unwrap());
@@ -880,8 +786,7 @@ fn set_font_string_adopts_the_label_and_raises_on_anything_else() {
         "the replaced label must be destroyed, not left live: {err}"
     );
 
-    // Three distinct raises, all naming the BUTTON — never a silent no-op, and `nil` cannot clear
-    // the label from Lua at all.
+    // Three distinct raises, each naming the button; `nil` cannot clear the label from Lua.
     for (call, want) in [
         ("b:SetFontString()", "Usage: Btn:SetFontString(fontstring)"),
         (
@@ -905,19 +810,16 @@ fn set_font_string_adopts_the_label_and_raises_on_anything_else() {
         let err = s.run(call).unwrap_err().to_string();
         assert!(err.contains(want), "`{call}` → {err}");
     }
-    // A TEXTURE is the near-miss the type gate exists for: it is a Region, and it still fails.
+    // A Texture is a Region and still fails the FontString type gate.
     s.run("tex = b:CreateTexture(nil, \"ARTWORK\")").unwrap();
     let err = s.run("b:SetFontString(tex)").unwrap_err().to_string();
     assert!(
         err.contains("Wrong object type, expected fontstring"),
         "{err}"
     );
-    // …and none of that changed the label.
     assert!(s.eval::<bool>("return b:GetFontString() == fs2").unwrap());
 }
 
-/// Adoption anchors the string **only when it has none of its own** — and leaves an already
-/// anchored one exactly where the caller put it.
 #[test]
 fn set_font_string_anchors_only_an_unanchored_label() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -947,7 +849,7 @@ fn set_font_string_anchors_only_an_unanchored_label() {
     );
     assert_eq!(s.eval::<i64>("return placed:GetNumPoints()").unwrap(), 1);
 
-    // The unanchored one gets the justify-derived point, to the matching point on the button.
+    // With no normal-font justify, the unanchored one is anchored CENTER to CENTER.
     s.run("b:SetFontString(bare)").unwrap();
     assert_eq!(s.eval::<i64>("return bare:GetNumPoints()").unwrap(), 1);
     let (p, _rel, rp, x, y): (String, mlua::Value, String, f64, f64) =
@@ -958,15 +860,10 @@ fn set_font_string_anchors_only_an_unanchored_label() {
     );
 }
 
-/// A label the button makes for itself (`SetText`'s lazy creator `0x778dc0`) or adopts
-/// (`SetFontString`) is anchored by the BUTTON's normal font justify, not by the fresh string's
-/// own ctor-default word: both funnel through `CSimpleButton::SetFontString 0x778d20`, whose
-/// unanchored-label leg reads `[button+0x390]` — the NORMAL embedded `CSimpleFont`'s justify —
-/// LEFT→LEFT / RIGHT→RIGHT / else CENTER, then links the label to that font (`0x779810`).
-/// wow-re `resize-bounds-and-button-fontstring.md` §5.2, VERIFIED; decision 1996.
-///
-/// `<NormalFont justifyH=>` is what writes that word in FrameXML (`UIMenuButtonTemplate`,
-/// `MailFrame.xml`'s RIGHT money button), so this is the chat menu's "Macro/macro" in miniature.
+/// A label made lazily (`SetText`, `0x778dc0`) or adopted goes through
+/// `CSimpleButton::SetFontString 0x778d20`, which anchors it by the button's normal font justify
+/// (`[button+0x390]`: LEFT, RIGHT, else CENTER), not the string's own, then links it to that font
+/// (`0x779810`). FrameXML writes that justify with `<NormalFont justifyH=>`.
 #[test]
 fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
     let mut s = script();
@@ -1007,8 +904,8 @@ fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
         "#,
     )
     .unwrap();
-    // `<NormalFont>` alone creates no label — the reference's LoadXML never touches `+0x338` on
-    // that leg — so `GetFontString()` is nil until something sets text.
+    // `<NormalFont>` alone creates no label (the reference's LoadXML leaves `+0x338` null), so
+    // `GetFontString()` is nil until text is set.
     assert!(s
         .eval::<bool>("return left:GetFontString() == nil")
         .unwrap());
@@ -1043,7 +940,6 @@ fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
             1
         );
     }
-    // The link is applied on the spot: the label's own word and object answer the normal font's.
     assert_eq!(
         s.eval::<String>("return left:GetFontString():GetJustifyH()")
             .unwrap(),
@@ -1053,7 +949,6 @@ fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
         .eval::<bool>("return left:GetFontString():GetFontObject() == ProbeFont")
         .unwrap());
 
-    // Adoption reads the same word: an unanchored string handed to the LEFT button seats LEFT.
     s.run(
         r#"
         bare = left:CreateFontString(nil, "OVERLAY")
@@ -1068,24 +963,14 @@ fn a_lazily_made_label_is_anchored_by_the_normal_fonts_justify() {
         "SetFontString anchors by the normal font's justify too"
     );
 
-    // A later `SetTextFontObject` re-links the normal font but does NOT re-anchor — the anchor
-    // was decided at adoption and is an ordinary anchor from then on.
+    // A later `SetTextFontObject` re-links the normal font but does not re-anchor.
     s.run("left:SetTextFontObject(ProbeFontRight)").unwrap();
     assert_eq!(point(&s, "left"), ("LEFT".into(), "LEFT".into(), 0.0, 0.0));
 }
 
-/// **A label that set its own face keeps it — the severance mask covers every axis, not three of
-/// six** (decision 2112).
-///
-/// `font_explicit` is the client's explicitly-set mask (`FONTINSTANCE+0x38`): an axis a widget
-/// writes for *itself* severs inheritance from the font instance it reads, and is never restored
-/// (wow-re `font-object-lua-surface.md`; the `button_font` block in `script::extract` cites it by
-/// name). `font::repaint` honours it on all seven axes. The extract's per-state re-point honoured
-/// it on shadow, colour and both justifies — and not on **face, height or outline**: the face and
-/// height read `fo.x.or(data.x)`, which makes the object outrank an explicit `SetFont`, and the
-/// outline was written unconditionally. A `<ButtonText>` that called
-/// `SetFont(path, h, "OUTLINE")` for itself therefore had all three silently put back from the
-/// button's font object on the very next extract — every frame, so no Lua could win the race.
+/// A label's own `SetFont` clears its font inherit bit (the reference's `FONTINSTANCE+0x2c`
+/// inherit mask, a FontString's `+0xd4`), and nothing sets it back, so its face, height and
+/// outline outlast every state font re-point while its other axes still inherit.
 #[test]
 fn a_button_labels_own_setfont_survives_the_state_font_repoint() {
     let mut s = script();
@@ -1135,7 +1020,6 @@ fn a_button_labels_own_setfont_survives_the_state_font_repoint() {
         ),
         "the label's own SetFont severs face, height AND outline from the state font object"
     );
-    // …and it survives a state change, which is what re-runs the re-point.
     s.run("b:Disable()").unwrap();
     assert_eq!(
         painted(&mut s),
@@ -1146,7 +1030,6 @@ fn a_button_labels_own_setfont_survives_the_state_font_repoint() {
         ),
         "…and a disable re-points the instance without restoring what the label severed"
     );
-    // The axes the label did NOT set still follow the object: the colour is the template's gold.
     s.resolve();
     let color = s
         .extract()
@@ -1167,21 +1050,9 @@ fn a_button_labels_own_setfont_survives_the_state_font_repoint() {
     );
 }
 
-/// **A state-texture setter takes an OBJECT and takes nil**, not only a path — the reference's
-/// `0x781970` forks on `lua_type(L, 2)` into four legs and benilla honoured one of them
-/// (wow-re `button-state-texture-path-setter.md` §1; decision 2124).
-///
-/// Both missing legs are silent no-ops rather than errors, which is why nothing caught them:
-///
-/// * **the object leg** (`0x781b0b` → `0x778fd0`) installs the handed Texture *into the slot*.
-///   Three corpus addons build a highlight this way and every one of them drew nothing —
-///   `Bongos/bar.lua:64-71`, `_Nameplates/_Nameplates.lua:217-222`,
-///   `Quiver/Quiver.bundle.lua:8949-8953`. The idiom below is Bongos', verbatim in shape.
-/// * **the nil leg** (`0x781b5a` → `0x778fd0` with 0) clears the slot and dtors what was in it.
-///   `TheoryCraft/TheoryCraftUI.lua:215-217` strips a talent-rank button with three of these.
-///   Clearing the *pointer* alone would be worse than the no-op: `region_visible` draws any region
-///   that is not one of the button's slots unconditionally, so a merely unhooked state texture
-///   would appear in every state instead of none — which is what this test's last assertion pins.
+/// A state-texture setter forks on `lua_type(L, 2)` (`0x781970`): a Texture object is installed
+/// into the slot (`0x781b0b` → `0x778fd0`), and nil clears the slot and destroys its texture
+/// (`0x781b5a`), which merely unhooked would draw in every state.
 #[test]
 fn a_state_texture_slot_takes_an_object_and_a_nil() {
     let mut s = script();
@@ -1211,8 +1082,6 @@ fn a_state_texture_slot_takes_an_object_and_a_nil() {
             .collect()
     };
 
-    // The handed object IS the slot now: it draws on hover and only on hover, exactly as a
-    // path-loaded highlight does.
     assert_eq!(drawn(&s), vec!["Interface\\N.blp".to_string()]);
     assert!(
         s.eval::<bool>("return b:GetHighlightTexture() == hl")
@@ -1229,7 +1098,6 @@ fn a_state_texture_slot_takes_an_object_and_a_nil() {
         ]
     );
 
-    // nil clears — and the cleared art is gone from every state, not merely unhooked.
     s.run("b:SetHighlightTexture(nil) b:SetNormalTexture(nil)")
         .unwrap();
     s.resolve();
@@ -1245,14 +1113,9 @@ fn a_state_texture_slot_takes_an_object_and_a_nil() {
     );
 }
 
-/// **The unlocked scripted push is released by the next mouse release — Tablet-2.0's rows**
-/// (decision 2134).
-///
-/// `SetButtonState(state[, lock])` writes `[+0x32c]` unconditionally, and the mouse-up edge
-/// `0x7793de` un-presses whenever `locked == 0`. Tablet-2.0 (`Tablet-2.0.lua:1645`) pushes a row it
-/// finds `clicked` and calls `SetButtonState("NORMAL")` *nowhere in the library* — it relies on
-/// exactly this. Ours kept a scripted push until Lua cleared it, so a Questie/FuBar/oRA2 row stayed
-/// depressed for the rest of the session.
+/// `SetButtonState(state[, lock])` always writes the lock (`[+0x32c]`), and the mouse-up edge
+/// (`0x7793de`) un-presses an unlocked button; `Tablet-2.0.lua:1645` pushes a row and never
+/// releases it itself.
 #[test]
 fn an_unlocked_scripted_push_is_released_by_the_next_mouse_release() {
     let mut s = script();
@@ -1274,7 +1137,6 @@ fn an_unlocked_scripted_push_is_released_by_the_next_mouse_release() {
         "PUSHED"
     );
 
-    // A press and release over the row: the release edge finds it PUSHED and unlocked.
     s.mouse_move(50.0, 50.0);
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     s.mouse_button(50.0, 50.0, "LeftButton", false);
@@ -1287,13 +1149,8 @@ fn an_unlocked_scripted_push_is_released_by_the_next_mouse_release() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`lock` pins the state against the mouse — the micro buttons** (`0x780270`'s third index,
-/// `GetBoolOrDefault` with default 0; wow-re `binding-shape-arity-law.md` §3).
-///
-/// `MainMenuBarMicroButtons.lua` calls `SetButtonState("PUSHED", 1)` when its panel opens, and the
-/// button must stay depressed through every press and release until the panel closes. The same
-/// flag pins a NORMAL button *against* being pushed, which is the half a "sticky push" model
-/// cannot express at all.
+/// `SetButtonState`'s third argument (`0x780270`, default 0) locks the state against the mouse,
+/// PUSHED or NORMAL; `MainMenuBarMicroButtons.lua:22` holds a micro button PUSHED this way.
 #[test]
 fn a_locked_state_ignores_the_mouse_and_enable_disable_clears_the_lock() {
     let mut s = script();
@@ -1331,8 +1188,7 @@ fn a_locked_state_ignores_the_mouse_and_enable_disable_clears_the_lock() {
     );
     s.mouse_button(250.0, 50.0, "LeftButton", false);
 
-    // `0x779160` passes `locked = 0` on both arms, so Enable/Disable UNLOCK. The panel closing
-    // with a plain `SetButtonState("NORMAL")` (flag defaulting to 0) does the same.
+    // `0x779160` passes `locked = 0` on both arms, so Enable and Disable unlock.
     s.run("MicroButton:Disable() MicroButton:Enable()").unwrap();
     assert_eq!(
         s.eval::<String>("return MicroButton:GetButtonState()")
@@ -1352,14 +1208,9 @@ fn a_locked_state_ignores_the_mouse_and_enable_disable_clears_the_lock() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **Walking off a held button does NOT un-press it, and walking back on does not re-press it.**
-///
-/// The correction decision 2134 is built on. Our old model derived the press as
-/// `(held && hovered) || pushed_state` and re-evaluated it whenever the hover moved; the
-/// reference's enter and leave notifies (`0x779490`/`0x7794e0`) read `[+0x328]` only as a DISABLED
-/// guard and **never write it** — proved by a §5 census of every store to the field image-wide.
-/// The only thing that un-presses a held button before its release is the drag-threshold crossing,
-/// and only for a frame that registered for drag.
+/// The enter and leave notifies (`0x779490`/`0x7794e0`) read the button state (`[+0x328]`) only as
+/// a DISABLED guard and never write it; before the release, only a drag-threshold crossing on a
+/// drag-registered frame un-presses a held button.
 #[test]
 fn the_hover_is_not_an_input_to_the_press_state() {
     let mut s = script();
@@ -1384,7 +1235,6 @@ fn the_hover_is_not_an_input_to_the_press_state() {
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     assert!(shows(&s, "Interface\\HeldP.blp"), "the press pushed it");
 
-    // Walk the cursor right off it, still holding.
     s.mouse_move(500.0, 400.0);
     assert!(
         shows(&s, "Interface\\HeldP.blp"),
@@ -1396,7 +1246,7 @@ fn the_hover_is_not_an_input_to_the_press_state() {
         "PUSHED"
     );
 
-    // The release, off the button, still un-presses it — `0x7792d0` runs no hit test of its own.
+    // The release un-presses it off the button too: `0x7792d0` runs no hit test.
     s.mouse_button(500.0, 400.0, "LeftButton", false);
     assert!(
         shows(&s, "Interface\\HeldN.blp"),
@@ -1405,10 +1255,8 @@ fn the_hover_is_not_an_input_to_the_press_state() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A button hidden while held comes back NORMAL** — `CSimpleButton`'s hide override
-/// (`+0x34` = `0x7791e0`), which un-presses and then tail-jumps the base notify so `<OnHide>`
-/// still fires. It hangs off the visibility transition, not off the hover, so it reaches a button
-/// hidden nowhere near the cursor too.
+/// `CSimpleButton`'s hide override (`+0x34` = `0x7791e0`) un-presses the button, then runs the
+/// base notify so `<OnHide>` still fires.
 #[test]
 fn hiding_a_held_button_un_presses_it() {
     let mut s = script();
@@ -1439,14 +1287,7 @@ fn hiding_a_held_button_un_presses_it() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `Button:GetTextColor()` — **FOUR** values, r/g/b/a (`0x781100`, table `0x879d00`, argc 1,
-/// arity 4, kinds `(number,number,number,number)`). Three is the plausible wrong answer, and the
-/// shapes table flags the name `name-not-unique` because seven tables register it — this asserts
-/// the BUTTON one, on a Button, and its two inheritance legs.
-///
-/// Completeness rather than a live break: no corpus site has a Button receiver today (every
-/// measured `GetTextColor` is on a FontString or a font object). It is here because the reference
-/// registers it, so the widget shape gate can cover it from now on.
+/// `Button:GetTextColor()` returns four values, r, g, b, a (`0x781100`, table `0x879d00`).
 #[test]
 fn button_get_text_color_answers_four_values_through_the_state_font() {
     let s = script();
@@ -1480,8 +1321,7 @@ fn button_get_text_color_answers_four_values_through_the_state_font() {
         .unwrap();
     assert_eq!(kinds, "number,number,number,number");
 
-    // A button with nothing set anywhere is the untinted white every other colour getter here
-    // (`GetVertexColor`, `FontString:GetTextColor`) answers.
+    // Nothing set: the untinted white the other colour getters here answer.
     let plain: Vec<f32> = (1..=4)
         .map(|i| {
             let discards = "_, ".repeat(i - 1);
@@ -1493,8 +1333,7 @@ fn button_get_text_color_answers_four_values_through_the_state_font() {
         .collect();
     assert_eq!(plain, vec![1.0, 1.0, 1.0, 1.0]);
 
-    // With no local colour it reads THROUGH what the normal state inherits — the same leg
-    // `Button:GetFont` takes, and the one a stock `GameMenuButtonTemplate` button relies on.
+    // Unset locally, it reads through the normal state's font object, as `Button:GetFont` does.
     let themed: Vec<f32> = (1..=4)
         .map(|i| {
             let discards = "_, ".repeat(i - 1);
@@ -1506,7 +1345,6 @@ fn button_get_text_color_answers_four_values_through_the_state_font() {
         .collect();
     assert_eq!(themed, vec![1.0, 0.82, 0.0, 1.0]);
 
-    // A local SetTextColor wins, alpha included, and round-trips.
     s.run("ThemedBtn:SetTextColor(0.1, 0.2, 0.3, 0.4)").unwrap();
     let set: Vec<f32> = (1..=4)
         .map(|i| {
@@ -1519,7 +1357,7 @@ fn button_get_text_color_answers_four_values_through_the_state_font() {
         .collect();
     assert_eq!(set, vec![0.1, 0.2, 0.3, 0.4]);
 
-    // A CheckButton reaches it through Button's table, as it does the rest of the trio.
+    // A CheckButton reaches it through Button's table.
     s.run(r#"CreateFrame("CheckButton", "ChkColorBtn")"#)
         .unwrap();
     assert_eq!(s.arity("ChkColorBtn:GetTextColor()").unwrap(), 4);
diff --git a/crates/benilla-ui/src/script/tests/channel.rs b/crates/benilla-ui/src/script/tests/channel.rs
index 1b752564..1561afcd 100644
--- a/crates/benilla-ui/src/script/tests/channel.rs
+++ b/crates/benilla-ui/src/script/tests/channel.rs
@@ -1,22 +1,16 @@
-//! `GetChannelName` — the joined-channel lookup ([`crate::script::channel`]).
-//!
-//! The verb is small; the contract around it is not, and every test here is named after one claim.
-//! The load-bearing one is [`a_channel_that_is_not_joined_answers_the_number_zero_never_nil`]: the
-//! reference's own callers and the corpus both compare the first return numerically, so a nil there
-//! does not degrade — it raises, at four call sites that work today.
+//! The joined-channel verbs `GetChannelName` and `GetChannelList` ([`crate::script::channel`])
+//! and the guild-recruitment latch.
 
 use super::common::script;
 
-/// Two channels joined in order, the way `ui_chat::feed` mirrors them after the server's
-/// YOU_JOINED. Join ORDER is the whole numbering law, so the fixture is deliberately not sorted.
+/// Two channels in join order, which is the numbering; deliberately not sorted.
 fn joined() -> crate::script::UiScript {
     let mut s = script();
     s.set_joined_channels(vec![Some("World".into()), Some("Trade - City".into())]);
     s
 }
 
-/// **A joined channel answers its 1-based slot, its name, and an instanceID.** The slot is the
-/// position in JOIN order — not a DBC id, not an alphabetical rank.
+/// The slot is the 1-based position in join order, not a DBC id or an alphabetical rank.
 #[test]
 fn a_joined_channel_answers_its_slot_name_and_instance() {
     let s = joined();
@@ -29,9 +23,7 @@ fn a_joined_channel_answers_its_slot_name_and_instance() {
     );
 }
 
-/// **The name form resolves, case-insensitively, and yields the same slot as the index form.**
-/// Half the corpus sites look up by name (`GetChannelName("world")`, `GetChannelName("Trade -
-/// City")`), and `_LazyPig` passes `"world"` for a channel the server names `"World"`.
+/// Addons look up by name in any case: `_LazyPig` passes `"world"` for the server's `"World"`.
 #[test]
 fn the_name_form_resolves_case_insensitively_to_the_same_slot() {
     let s = joined();
@@ -49,16 +41,7 @@ fn the_name_form_resolves_case_insensitively_to_the_same_slot() {
     );
 }
 
-/// **Not joined ⇒ the NUMBER 0. Never nil.** This is the trap, and it is the only way this verb can
-/// break working code rather than merely fail to help it.
-///
-/// Verified from both sides. The reference compares it numerically at `ChatFrame.lua:2114`
-/// (`if ( channelNum > 0 )`) and `l.2232` (`if ( channelNum <= 0 ) then return end`); so does the
-/// corpus at `_LazyPig/LazyPig.lua:1996` (`if id > 0 then`). A nil first return turns every one of
-/// those into "attempt to compare nil with number" — a loud failure in code that works today.
-///
-/// Asserted by DOING the comparison, not by inspecting the type, because the comparison is the
-/// thing that must not raise.
+/// Stock callers compare the first return numerically (`ChatFrame.lua:2114`, `:2232`).
 #[test]
 fn a_channel_that_is_not_joined_answers_the_number_zero_never_nil() {
     let s = joined();
@@ -66,7 +49,6 @@ fn a_channel_that_is_not_joined_answers_the_number_zero_never_nil() {
     let id: i64 = s.eval("return GetChannelName('NoSuchChannel')").unwrap();
     assert_eq!(id, 0);
 
-    // The reference's own guard shape, run for real: it must evaluate, not raise.
     let guard: bool = s
         .eval("local id = GetChannelName('NoSuchChannel') return id > 0")
         .unwrap();
@@ -89,9 +71,7 @@ fn a_channel_that_is_not_joined_answers_the_number_zero_never_nil() {
     );
 }
 
-/// **A numeric STRING resolves as a number**, because `ChatFrame.lua:2113` hands one straight in:
-/// it `gsub`s `/1` down to `"1"` and calls `GetChannelName(channel)`. On the real client Lua's own
-/// coercion makes that work; ours must not treat it as a channel literally named "1".
+/// `ChatFrame.lua:2113` passes the `"1"` it cuts out of `/1`, which Lua coerces to a number.
 #[test]
 fn a_numeric_string_resolves_as_an_index_not_as_a_name() {
     let s = joined();
@@ -99,9 +79,7 @@ fn a_numeric_string_resolves_as_an_index_not_as_a_name() {
     assert_eq!(id, 2, "the `/2` slash-command path depends on this");
 }
 
-/// **Empty until the server confirms a join.** `ui_chat::feed` appends on the server's YOU_JOINED
-/// notice, never on the request, so a session that has asked and not been answered has no slots —
-/// and the verb must still answer 0 rather than raise on an empty list.
+/// `ui_chat::feed` appends on the server's YOU_JOINED notice, never on the request.
 #[test]
 fn nothing_is_joined_before_the_server_confirms_it() {
     let s = script();
@@ -109,30 +87,22 @@ fn nothing_is_joined_before_the_server_confirms_it() {
     assert_eq!(id, 0);
 }
 
-/// **`GetChannelList()` is a FLAT vararg of (slot, name) pairs in join order** — not a table, and
-/// not name-first.
-///
-/// Neither wow-re nor any recorded signature pins the shape; two independent consumers do, and the
-/// test asserts what each of them relies on. The reference's `FCFDropDown_LoadChannels` walks
-/// `for i=1, arg.n, 2` and reads `arg[i+1]` as the name, so the pair order is (slot, name) and the
-/// stride is 2. `ChatLog.lua:424` packs it with `{ GetChannelList() }` and tests
-/// `type(value) == "number"` to spot an id, so the values must interleave rather than nest.
+/// The shape its consumers pin: `FCFDropDown_LoadChannels` walks `for i=1, arg.n, 2` reading
+/// `arg[i+1]` as the name, and `ChatLog.lua:424` packs it and spots an id by `type == "number"`.
 #[test]
 fn get_channel_list_is_a_flat_slot_name_vararg_in_join_order() {
     let s = joined();
 
-    // Exactly two pairs for two joined channels — the arity `FCFDropDown_LoadChannels` steps over.
+    // Two pairs for two joined channels.
     assert_eq!(s.arity("GetChannelList()").unwrap(), 4);
 
-    // Pair order and join order, both at once: slot 1 is the FIRST joined, not the alphabetical
-    // first ("Trade - City" would sort ahead of "World").
+    // Slot 1 is the first joined; alphabetically "Trade - City" would come first.
     let (s1, n1, s2, n2) = s
         .eval::<(i64, String, i64, String)>("return GetChannelList()")
         .unwrap();
     assert_eq!((s1, n1.as_str()), (1, "World"));
     assert_eq!((s2, n2.as_str()), (2, "Trade - City"));
 
-    // ChatLog's own walk: packed, the odd entries are numbers and the even ones are names.
     assert!(s
         .eval::<bool>(
             "local t = { GetChannelList() } \
@@ -140,25 +110,16 @@ fn get_channel_list_is_a_flat_slot_name_vararg_in_join_order() {
         )
         .unwrap());
 
-    // The slot agrees with GetChannelName's, which is the point of sharing the numbering.
     assert!(s
         .eval::<bool>("local i = GetChannelName('Trade - City') return i == 2")
         .unwrap());
 
-    // No channels joined is ZERO returns, so `{ GetChannelList() }` is an empty table rather than
-    // a table of nils — every consumer above already handles that shape.
     let empty = crate::script::tests::common::script();
     assert_eq!(empty.arity("GetChannelList()").unwrap(), 0);
 }
 
-/// **The guild-recruitment latch boots at AUTO and round-trips as a NUMBER** (decision 2115).
-///
-/// `GetGuildRecruitmentMode 0x4a0040` is 23 bytes and one path — `fild` the int global,
-/// `lua_pushnumber`, `mov eax,1`, `ret` — so it has no nil leg at all, and
-/// `UIOptionsFrame_Load`'s `== 1` would read a nil as a silent "not auto". The boot value is 1
-/// from a `.data` initialiser (`raw 0x443608` = `01 00 00 00`), corroborated by
-/// `UIOptionsFrame_SetDefaults`'s `SetGuildRecruitmentMode(1)` and by all 33 `chat-cache.txt`
-/// files the reference client itself wrote in this repo's install.
+/// `GetGuildRecruitmentMode` (`0x4a0040`) always pushes its int global as a number; it boots at 1
+/// from a `.data` initialiser (`raw 0x443608`), the value `UIOptionsFrame_SetDefaults` sets.
 #[test]
 fn the_guild_recruitment_mode_boots_auto_and_answers_a_number() {
     let s = script();
@@ -177,29 +138,19 @@ fn the_guild_recruitment_mode_boots_auto_and_answers_a_number() {
     );
 }
 
-/// **The setter is shape A — it RAISES rather than swallowing a bad argument** (decision 2115).
-///
-/// `0x4a0060` gates on `lua_isnumber 0x6f34d0` (so a numeric STRING passes) and otherwise
-/// `luaL_error`s `Usage: SetGuildRecruitmentMode(mode)`; it then truncates toward zero through
-/// `__ftol 0x40a2b0` and range-gates `0 <= mode < 2`, raising
-/// `SetGuildRecruitmentMode: invalid mode` outside it. Most 1.12 numeric bindings swallow a nil
-/// as 0.0 — this one does not, and a client that guessed the common shape would turn an addon's
-/// own bug into silence (wow-re `numeric-arg-coercion-law.md`; the per-binding split is the whole
-/// point of that note).
-///
-/// Success pushes **0 values**, not nil.
+/// `0x4a0060` raises `Usage:` unless `lua_isnumber` (`0x6f34d0`), truncates through `__ftol`
+/// (`0x40a2b0`), and raises `invalid mode` outside `0 <= mode < 2`; success pushes no values.
 #[test]
 fn the_guild_recruitment_setter_gates_its_argument_the_way_the_reference_does() {
     let s = script();
 
-    // A numeric string is a number to `lua_isnumber`.
     s.run(r#"SetGuildRecruitmentMode("0")"#).unwrap();
     assert_eq!(
         s.eval::<f64>("return GetGuildRecruitmentMode()").unwrap(),
         0.0
     );
 
-    // Truncation toward zero, not rounding: 1.7 is a legal 1.
+    // 1.7 truncates to a legal 1.
     s.run("SetGuildRecruitmentMode(1.7)").unwrap();
     assert_eq!(
         s.eval::<f64>("return GetGuildRecruitmentMode()").unwrap(),
@@ -222,7 +173,7 @@ fn the_guild_recruitment_setter_gates_its_argument_the_way_the_reference_does()
         assert!(e.to_string().contains("invalid mode"), "{bad}: {e}");
     }
 
-    // …and none of the refused calls moved the latch.
+    // None of the refused calls moved the latch.
     assert_eq!(
         s.eval::<f64>("return GetGuildRecruitmentMode()").unwrap(),
         1.0
@@ -234,10 +185,8 @@ fn the_guild_recruitment_setter_gates_its_argument_the_way_the_reference_does()
     );
 }
 
-/// **The setter is not inert** (decision 2144). `0x49ea70` stores the latch and tail-jumps into
-/// the cascade `0x49ea90` on the new value alone — `Set(1)` raises the app's cue whether or not
-/// the value moved; `Set(0)` never does — and `0x4a00a4`/`0x4a00a9` fire `UPDATE_CHAT_WINDOWS`
-/// on every successful call, before any cascade fires it again.
+/// `0x49ea70` stores the latch and jumps into the cascade `0x49ea90` whenever the new value is 1,
+/// moved or not; `0x4a00a4`/`0x4a00a9` fire `UPDATE_CHAT_WINDOWS` on every successful call.
 #[test]
 fn the_setter_asks_for_the_cascade_on_one_and_fires_update_chat_windows() {
     let mut s = script();
@@ -252,8 +201,7 @@ fn the_setter_asks_for_the_cascade_on_one_and_fires_update_chat_windows() {
     .unwrap();
     assert!(!s.take_guild_recruitment_cascade(), "nothing asked yet");
 
-    // Boots at 1; a Set(1) that moves nothing still asks — the reference's store is
-    // unconditional and the jump reads only `ecx == 1`.
+    // Boots at 1; a Set(1) that moves nothing still asks for the cascade.
     s.run("SetGuildRecruitmentMode(1)").unwrap();
     assert!(s.take_guild_recruitment_cascade());
     assert!(!s.take_guild_recruitment_cascade(), "drained");
@@ -282,9 +230,8 @@ fn the_setter_asks_for_the_cascade_on_one_and_fires_update_chat_windows() {
     );
 }
 
-/// **A manual join or leave of `GuildRecruitment` forces the latch to 0** — `0x49ed3d`/
-/// `0x49ef8f`, `call 0x49ea70(0)`. A player gesture, so it dirties the file; and mode 0 is the
-/// latch alone, so it asks for no cascade.
+/// A manual join or leave of `GuildRecruitment` calls `0x49ea70(0)` (`0x49ed3d`, `0x49ef8f`): it
+/// dirties the file and, as mode 0, asks for no cascade.
 #[test]
 fn a_manual_guild_recruitment_verb_resets_the_latch() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/cooldown.rs b/crates/benilla-ui/src/script/tests/cooldown.rs
index be3003b5..b2581398 100644
--- a/crates/benilla-ui/src/script/tests/cooldown.rs
+++ b/crates/benilla-ui/src/script/tests/cooldown.rs
@@ -1,17 +1,14 @@
-//! The cooldown **bindings**: the per-action dynamic-state read API and the `GetTime`-space
-//! cooldown triples the stock `Cooldown.lua` machine consumes (the widget itself is the
-//! reference's own `<Model>` since decision 2019 — `tests::model_clock` runs that file verbatim).
+//! The cooldown bindings: per-action state and the `GetTime`-space triples stock `Cooldown.lua`
+//! consumes (its `<Model>` widget runs in `tests::model_clock`).
 
 use super::common::script;
 use crate::script::*;
 
-/// The per-action dynamic-state API: the 1/nil conventions, IsActionInRange's tri-state, and
-/// GetActionCooldown's GetTime-space triple that goes cold at expiry.
+/// The 1/nil conventions, `IsActionInRange`'s tri-state, and a cooldown that goes cold at expiry.
 #[test]
 fn action_state_bindings_answer_the_reference_conventions() {
     let mut s = script();
 
-    // No state pushed: everything nil / cold.
     assert!(s.eval::<bool>("return IsUsableAction(3) == nil").unwrap());
     assert!(s.eval::<bool>("return IsActionInRange(3) == nil").unwrap());
     assert!(s
@@ -35,7 +32,6 @@ fn action_state_bindings_answer_the_reference_conventions() {
         }),
     );
 
-    // The 1/nil pairs, exactly as the transcribed `if` reads them.
     assert!(s
         .eval::<bool>("local u, oom = IsUsableAction(3); return u == nil and oom == 1")
         .unwrap());
@@ -45,8 +41,7 @@ fn action_state_bindings_answer_the_reference_conventions() {
     assert!(s
         .eval::<bool>("return IsAutoRepeatAction(3) == nil")
         .unwrap());
-    // IsConsumableAction reads the SLOT, not this map (decision 1301) — it is a pure query over
-    // the item template, so it arrives with the icon it gates the count beside.
+    // `IsConsumableAction` reads the slot, not this state: it arrives with the icon.
     assert!(s
         .eval::<bool>("return IsConsumableAction(3) == nil")
         .unwrap());
@@ -62,7 +57,6 @@ fn action_state_bindings_answer_the_reference_conventions() {
     );
     assert!(s.eval::<bool>("return IsConsumableAction(3) == 1").unwrap());
 
-    // GetActionCooldown: the pushed absolute start, verbatim in seconds.
     assert!(s
         .eval::<bool>(
             "local st, d, e = GetActionCooldown(3); \
@@ -70,9 +64,8 @@ fn action_state_bindings_answer_the_reference_conventions() {
         )
         .unwrap());
 
-    // 5 s later the same stored pair still answers (4 s window has 0 left → but 100+? no: it
-    // expires at start+10 = now+4) …after the remaining 4 s pass, the read goes cold — the
-    // stale-refeed guard (a re-fed finished pair must not replay the sweep/flash).
+    // It ends at 94 + 10 = 104: live at 103.9 and cold after, so a re-fed finished pair cannot
+    // replay the sweep.
     s.tick(3.9);
     assert!(s
         .eval::<bool>("local st, d = GetActionCooldown(3); return d == 10")
@@ -82,7 +75,7 @@ fn action_state_bindings_answer_the_reference_conventions() {
         .eval::<bool>("local st, d, e = GetActionCooldown(3); return st == 0 and d == 0 and e == 1")
         .unwrap());
 
-    // An on-hold (enable == 0) cooldown never goes cold on its own — parked until the event.
+    // An on-hold cooldown (enable 0) never goes cold on its own; it waits for the event.
     s.set_action_state(
         3,
         Some(ActionState {
@@ -95,17 +88,12 @@ fn action_state_bindings_answer_the_reference_conventions() {
         .eval::<bool>("local st, d, e = GetActionCooldown(3); return d == 30 and e == 0")
         .unwrap());
 
-    // Clearing the state clears the reads.
     s.set_action_state(3, None);
     assert!(s.eval::<bool>("return IsCurrentAction(3) == nil").unwrap());
 }
 
-/// The absolute-start triple is the anchor — both director regressions pin here. Reset-on-kill
-/// ("the cooldown indicator resets when you kill a mob"): an unrelated field flip re-pushes the
-/// same running cooldown, whose triple carries the SAME start, so the sweep holds. The vanished
-/// GCD pie ("spamming Rend during Charge never shows the pie"): a fail-clear + re-arm between
-/// feeds pushes a triple with a NEW start — under the old `(remaining, duration)` shape the two
-/// arms read byte-identical and the seam kept the first, long-elapsed anchor.
+/// The absolute start anchors the sweep: re-pushing a running cooldown (a kill flipping `usable`)
+/// keeps it, so the sweep does not reset, and a re-arm moves it even at the same duration.
 #[test]
 fn the_absolute_start_triple_holds_the_anchor_and_a_rearm_moves_it() {
     let mut s = script();
@@ -120,8 +108,6 @@ fn the_absolute_start_triple_holds_the_anchor_and_a_rearm_moves_it() {
         .eval::<bool>("local st = GetActionCooldown(3); return math.abs(st - 100) < 1e-3")
         .unwrap());
 
-    // 8 s later the kill drops combat and `usable` flips; the re-push carries the same start.
-    // The anchor holds at 100 — the sweep never restarts (the reset-on-kill invariant).
     s.tick(8.0);
     s.set_action_state(3, Some(cooling(true)));
     assert!(s
@@ -131,8 +117,6 @@ fn the_absolute_start_triple_holds_the_anchor_and_a_rearm_moves_it() {
         )
         .unwrap());
 
-    // A RE-ARM carries a fresh start and moves the anchor — even with the same duration (the
-    // vanished-pie shape: same spell, same 15 s, armed again at t=107).
     s.set_action_state(
         3,
         Some(ActionState {
@@ -145,8 +129,6 @@ fn the_absolute_start_triple_holds_the_anchor_and_a_rearm_moves_it() {
         .unwrap());
 }
 
-/// The same absolute-start law on the other two converters: the stance bar's form cooldown and
-/// the bag slot's item cooldown hold their anchors across unchanged re-pushes.
 #[test]
 fn shapeshift_and_container_cooldowns_keep_their_anchors_too() {
     let mut s = script();
@@ -177,7 +159,7 @@ fn shapeshift_and_container_cooldowns_keep_their_anchors_too() {
         .eval::<bool>("local st = GetContainerItemCooldown(0, 1); return math.abs(st - 50) < 1e-3")
         .unwrap());
 
-    // Re-push both with the SAME raw triples 5 s later: the anchors hold at 50.
+    // The same triples re-pushed 5 s later: the anchors hold at 50.
     s.tick(5.0);
     s.set_shapeshift_forms(vec![form()]);
     s.set_container(0, Some(bag()));
diff --git a/crates/benilla-ui/src/script/tests/create_frame_template.rs b/crates/benilla-ui/src/script/tests/create_frame_template.rs
index 5f2fb40a..15b954e4 100644
--- a/crates/benilla-ui/src/script/tests/create_frame_template.rs
+++ b/crates/benilla-ui/src/script/tests/create_frame_template.rs
@@ -1,20 +1,10 @@
-//! `CreateFrame(kind, name, parent, inherits)` — the **runtime** template path
-//! ([`crate::loader::apply_template`]).
-//!
-//! `local b = CreateFrame("Button", "MyButton", UIParent, "UIPanelButtonTemplate")` is the single
-//! most common line in the addon corpus, and until the loader's post-`CreateFrame` steps were
-//! factored into `Loader::decorate` the fourth argument was dropped on the floor: the addon got a
-//! bare frame with no art, no regions, no scripts, and a warning on a channel it never reads.
-//!
-//! The load-bearing property every test here turns on is that **the caller's own name wins** — a
-//! template instantiated as `Mine` publishes `MineTexture`, never `ThatTemplateTexture`, because
-//! `getglobal("MineTexture")` is what the addon's next line calls.
+//! The runtime template path, `CreateFrame`'s fourth argument ([`crate::loader::apply_template`]),
+//! and `<ScrollChild>`. The caller's name wins: a template made as `Mine` publishes `MineTexture`.
 
 use super::common::script;
 use crate::script::UiScript;
 
-/// Register templates by loading a small FrameXML document — the same door an addon's own `.xml`
-/// comes through, so nothing here is a test-only shortcut into the registry.
+/// Registers templates by loading a FrameXML document, the path an addon's own `.xml` takes.
 fn register(s: &UiScript, xml: &str) {
     let doc = crate::framexml::parse(xml).expect("valid FrameXML");
     let report = crate::loader::load(s, &doc, &|_| None);
@@ -25,9 +15,6 @@ fn register(s: &UiScript, xml: &str) {
     );
 }
 
-/// The whole shape at once: a virtual template's `<Size>`, `<Anchors>`, `<Layers>` texture and
-/// `<Scripts><OnLoad>` all reach a frame built by `CreateFrame`'s fourth argument — and the region
-/// is named against **the instance**, not the template.
 #[test]
 fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
     let mut s = script();
@@ -65,8 +52,8 @@ fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
         "the template's <Size>"
     );
 
-    // The template's own <Anchors> substitute `$parent` against the frame's PARENT (rf27) — the
-    // instance's enclosing frame, not the instance itself.
+    // A template's `$parent` in `<Anchors>` is the frame's first named ancestor, not the frame
+    // (`0x76c5b0`).
     let (point, rel, rel_point, x, y): (String, String, String, f32, f32) = s
         .eval(
             "local p, r, rp, ox, oy = Mine:GetPoint(1) \
@@ -78,8 +65,6 @@ fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
         ("TOPLEFT", "Host", "BOTTOMLEFT", 7.0, -3.0)
     );
 
-    // The region carries the INSTANCE's name. This is the whole point: `MineTexture` is what an
-    // addon reaches for, and `ProbeTemplateTexture` would be useless to it.
     assert!(
         s.eval::<bool>(r#"return getglobal("MineTexture") ~= nil"#)
             .unwrap(),
@@ -91,8 +76,7 @@ fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
         "nothing may be named after the template"
     );
 
-    // OnLoad fired inside CreateFrame, after the frame was decorated — the reference's ordering,
-    // and what `local f = CreateFrame(...); f:Foo()` on the next line assumes.
+    // The reference fires OnLoad inside `CreateFrame`, after the template is applied.
     assert_eq!(s.eval::<String>("return ProbeLoadedAs").unwrap(), "Mine");
     assert_eq!(s.eval::<f32>("return ProbeLoadWidth").unwrap(), 160.0);
 
@@ -100,8 +84,7 @@ fn a_runtime_template_brings_size_anchors_regions_and_a_fired_onload() {
     assert!(s.take_warnings().is_empty());
 }
 
-/// A template's nested `<Frames>` child is named against the caller too, and is really parented to
-/// the new frame — the `$parent` chain composes through `CreateFrame` exactly as through XML.
+/// A nested child is parented to the new frame, and `$parent` composes as it does through XML.
 #[test]
 fn a_nested_frames_child_is_named_against_the_caller() {
     let mut s = script();
@@ -146,15 +129,8 @@ fn a_nested_frames_child_is_named_against_the_caller() {
     assert!(s.take_warnings().is_empty());
 }
 
-/// The template argument is **one name**, on this path exactly as on the XML one — and a chain
-/// through a single name still resolves.
-///
-/// This asserted the opposite until the registry lookup was carved. `"TemplA, TemplB"` is not a
-/// list, it is a literal name nothing declared: 1.12's `CreateFrame` reaches the same `0x6ee6f0`
-/// the XML loader does (call site `0x7061dd`) with the string Lua handed it, and the loader has no
-/// splitter anywhere — comma lists are a **later**-client feature. Corroborated by the corpus:
-/// 6842 `inherits=` across 282 vanilla XML files contain **zero** comma lists, while the modern
-/// Blizzard UI source is full of them.
+/// The template argument is one name: 1.12's `CreateFrame` hands the string to the XML loader's
+/// lookup (`0x6ee6f0`, called at `0x7061dd`), which has no splitter; comma lists came later.
 #[test]
 fn a_comma_list_is_one_name_and_a_single_name_still_chains() {
     let mut s = script();
@@ -175,8 +151,6 @@ fn a_comma_list_is_one_name_and_a_single_name_still_chains() {
            </Ui>"#,
     );
 
-    // A single name still walks its whole chain. This is what keeps the narrowing honest: it
-    // removes the list, not the inheritance.
     s.run(r#"One = CreateFrame("Frame", "One", nil, "TemplA")"#)
         .unwrap();
     assert_eq!(
@@ -188,8 +162,6 @@ fn a_comma_list_is_one_name_and_a_single_name_still_chains() {
     assert!(s.take_errors().is_empty());
     assert!(s.take_warnings().is_empty());
 
-    // The comma form is one literal name, nothing declared it, so it RAISES — naming the whole
-    // unsplit string, which is the proof it was never split.
     let err = s
         .run(r#"Both = CreateFrame("Frame", "Both", nil, "TemplA, TemplB")"#)
         .expect_err("a comma list is one name, and it misses");
@@ -205,12 +177,8 @@ fn a_comma_list_is_one_name_and_a_single_name_still_chains() {
     );
 }
 
-/// The case fold, with the four names the corpus actually mis-cases.
-///
-/// The compare is `SStrCmpI` → `_strnicmp`, and the trap that decides it is the bucket hash:
-/// `SStrHash 0x64b3f0` uppercases before mixing, so a mis-cased name lands in the same bucket and
-/// the stored-hash pre-check passes rather than short-circuiting. ASCII-only, like every other fold
-/// in this engine.
+/// The lookup folds ASCII case: `SStrHash` (`0x64b3f0`) uppercases before hashing, so a mis-cased
+/// name lands in the same bucket, and the compare is `SStrCmpI`.
 #[test]
 fn a_template_name_is_matched_case_insensitively() {
     let mut s = script();
@@ -222,7 +190,7 @@ fn a_template_name_is_matched_case_insensitively() {
              </Frame>
            </Ui>"#,
     );
-    // Exactly the shape `CT_RaidAssist/CT_RAOptions.xml` ships: `RA` written `Ra`.
+    // The mis-casing `CT_RaidAssist/CT_RAOptions.xml` ships: `RA` written `Ra`.
     s.run(r#"Cased = CreateFrame("Frame", "Cased", nil, "CT_RaCheckButtonTemplate")"#)
         .unwrap();
     assert_eq!(
@@ -234,21 +202,9 @@ fn a_template_name_is_matched_case_insensitively() {
     assert!(s.take_warnings().is_empty());
 }
 
-/// An unresolvable template name **raises, and creates nothing**.
-///
-/// This test asserted the exact opposite — *"the reference creates the frame anyway, and an addon's
-/// next line already assumes it did"* — until the bytes were read. `0x7061dd` looks the name up and
-/// on NULL falls into `luaL_error(L, "CreateFrame(): Couldn't find inherited node \"%s\"")`, which
-/// **never returns**: `luaG_errormsg` and `luaD_throw` contain no `ret` between them and end in
-/// `longjmp`, so the `xor eax,eax; ret` that follows the call is dead code. (That trailing `ret` is
-/// a fact about `luaL_error`'s `int` return type in C, not about reachability — which is exactly
-/// how the old claim was arrived at.)
-///
-/// Both flavours of "unusable" raise, because the registry only ever holds `virtual="true"`
-/// elements, so a name declared without it misses the lookup identically to a name nothing declared.
-///
-/// The ordering is asserted too: the miss precedes construction and name publication (`0x706208` /
-/// `0x70622d`), so nothing partial is left behind — no frame, and no global.
+/// A template name that misses the lookup raises at `0x7061dd`, before the frame is built or its
+/// name published (`0x706208`, `0x70622d`). The registry holds only `virtual="true"` elements, so
+/// a non-virtual name misses like an undeclared one.
 #[test]
 fn an_unresolvable_template_raises_and_creates_nothing() {
     let s = script();
@@ -266,7 +222,6 @@ fn an_unresolvable_template_raises_and_creates_nothing() {
             "the raise must carry the reference's message and the name: {text}"
         );
 
-        // Nothing partial: no global published, and the name never reached the arena.
         assert!(
             s.eval::<bool>(&format!(r#"return getglobal("{frame}") == nil"#))
                 .unwrap(),
@@ -274,9 +229,7 @@ fn an_unresolvable_template_raises_and_creates_nothing() {
         );
     }
 
-    // And it is ordinary Lua propagation — `pcall` catches it, which is what keeps one bad
-    // CreateFrame inside a handler from taking the client down (the widget dispatcher runs every
-    // handler under `lua_pcall`).
+    // An ordinary Lua error: `pcall` catches it, as the widget dispatcher's `lua_pcall` does.
     assert!(
         !s.eval::<bool>(
             r#"return (pcall(CreateFrame, "Button", "Caught", nil, "NoSuchTemplate"))"#
@@ -286,15 +239,8 @@ fn an_unresolvable_template_raises_and_creates_nothing() {
     );
 }
 
-/// The two shape mismatches, neither of which may panic or drop the frame.
-///
-/// A **region** template (a virtual `<Texture>`) asked for as a frame: its frame-shaped content
-/// still lands, its region-only content cannot, and the message says which.
-///
-/// A **kind that disagrees with the template's tag**: the frame keeps the kind `CreateFrame` was
-/// given — no template can retype a frame that already exists — so the `<Button>`-only parts of a
-/// Button template simply do not apply to a Frame, and, crucially, are not *attempted* (calling
-/// `SetNormalTexture` on a plain Frame would be an error, not a warning).
+/// A region template on a frame applies its frame-shaped content and warns; a template whose tag
+/// disagrees with the kind keeps the kind, and its tag-only parts are skipped, not attempted.
 #[test]
 fn a_region_template_or_a_mismatched_kind_is_named_never_fatal() {
     let mut s = script();
@@ -355,7 +301,7 @@ fn a_region_template_or_a_mismatched_kind_is_named_never_fatal() {
         "the Button-only steps are SKIPPED, not attempted and failed"
     );
 
-    // 3 · the same template, asked for as the kind it was written as — the control.
+    // 3 · the control: the same template, asked for as the kind it was written as.
     s.run(r#"AsButton = CreateFrame("Button", "AsButton", nil, "ProbeButtonTemplate")"#)
         .unwrap();
     assert_eq!(s.eval::<f32>("return AsButton:GetWidth()").unwrap(), 90.0);
@@ -371,14 +317,8 @@ fn a_region_template_or_a_mismatched_kind_is_named_never_fatal() {
     );
 }
 
-/// **`<ScrollChild>` gives a ScrollFrame its range** — the loader element that was missing, and
-/// the whole remaining distance for an addon's scrolling list (decision 1205).
-///
-/// wow-5875-re `rf28-typed-widget-loadxml.md`: the single child is instantiated via the same
-/// RF-0026 path `<Frames>` uses, then stored as the scroll child. Without it a `ScrollFrame` has
-/// nothing to pan, so `GetVerticalScrollRange()` is 0, `SetVerticalScroll` clamps to 0, and
-/// `OnVerticalScroll` fires with 0 forever — the list never moves and nothing errors, which is why
-/// no instrument could see it.
+/// `<ScrollChild>` builds its one child through the `<Frames>` path (`0x6ee280`) and stores it as
+/// the scroll child, which gives the frame its range.
 #[test]
 fn a_scroll_child_element_gives_the_frame_a_real_scroll_range() {
     let mut s = script();
@@ -399,19 +339,18 @@ fn a_scroll_child_element_gives_the_frame_a_real_scroll_range() {
     );
     s.resolve();
 
-    // The child exists, is named against the FRAME (rf27's `$parent`), and is the scroll child.
+    // `$parent` names the child against the scroll frame (`0x76c5b0`).
     assert!(s.eval::<bool>("return RollerChild ~= nil").unwrap());
     assert!(s
         .eval::<bool>("return Roller:GetScrollChild() == RollerChild")
         .unwrap());
-    // ...and the range is the overhang: a 400-tall child in a 100-tall window scrolls 300.
+    // The range is the overhang: a 400-tall child in a 100-tall window scrolls 300.
     assert_eq!(
         s.eval::<f64>("return Roller:GetVerticalScrollRange()")
             .unwrap(),
         300.0,
         "no child means range 0, which is the silent failure this element fixes"
     );
-    // The scroll actually takes, rather than clamping to zero.
     s.run("Roller:SetVerticalScroll(120)").unwrap();
     assert_eq!(
         s.eval::<f64>("return Roller:GetVerticalScroll()").unwrap(),
@@ -420,14 +359,9 @@ fn a_scroll_child_element_gives_the_frame_a_real_scroll_range() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The scroll range is the child's SUBTREE, not the child frame's own height** (decision 1338,
-/// wow-re `simplehtml-markup-engine.md` §4.5: `0x786e30` seeds a bbox and walks `0x786f80`
-/// recursively over the child's region and child-frame lists).
-///
-/// The geometry is the reference reader's own: `ItemTextPageScrollChild` is declared **10×10**
-/// around a 270×304 page. Measured as the child's height that is range 0 — a book that cannot be
-/// scrolled — which is exactly what shipped before this. The second assertion is the mutation
-/// check welded in: it is the number the old law returned.
+/// The scroll range is the child's whole subtree, not its own height: `0x786e30` seeds a box and
+/// `0x786f80` walks the child's regions and child frames. The shape is `ItemTextPageScrollChild`,
+/// 10×10 around a 270×304 page (`ItemTextFrame.xml:198`).
 #[test]
 fn the_scroll_range_is_the_childs_whole_subtree() {
     let mut s = script();
@@ -460,16 +394,13 @@ fn the_scroll_range_is_the_childs_whole_subtree() {
         204.0,
         "the 304-tall page inside the 10-tall child, less the 100-tall window"
     );
-    // The mutation check: under the old law the child's own 10 never reaches the window's 100, so
-    // the range clamps to zero and the reader's scrollbar has nowhere to go.
     assert_eq!(
         s.eval::<f64>("return ReaderChild:GetHeight()").unwrap(),
         10.0,
         "and the child itself really is the reference's 10 — the range does not come from it"
     );
 
-    // A hidden branch contributes nothing: the client guards both list walks on visibility, which
-    // is what stops a window's parked art from inventing travel nobody can use.
+    // A hidden branch adds nothing: the reference guards both list walks on visibility.
     s.run("Page:Hide()").unwrap();
     s.resolve();
     assert_eq!(
@@ -480,8 +411,7 @@ fn the_scroll_range_is_the_childs_whole_subtree() {
     );
 }
 
-/// An empty `<ScrollChild>` is an error — the reference's own behaviour (`rf28`), and the honest
-/// one: a ScrollFrame that declares a child and has none is a typo, not a design.
+/// The reference reports an empty `<ScrollChild>` as an error (`0x786bc0`) and keeps the frame.
 #[test]
 fn an_empty_scroll_child_is_reported() {
     let s = script();
@@ -498,6 +428,5 @@ fn an_empty_scroll_child_is_reported() {
         "errors: {:?}",
         report.errors
     );
-    // ...and the frame still exists — the client logs and carries on (decision 0068).
     assert!(s.eval::<bool>("return Hollow ~= nil").unwrap());
 }
diff --git a/crates/benilla-ui/src/script/tests/dispatch_bench.rs b/crates/benilla-ui/src/script/tests/dispatch_bench.rs
new file mode 100644
index 00000000..a4fcb08e
--- /dev/null
+++ b/crates/benilla-ui/src/script/tests/dispatch_bench.rs
@@ -0,0 +1,162 @@
+//! What one widget method lookup through the wrapper's `__index` costs: every call pays a hit,
+//! and a miss (the duck-type probe `if f.SetValue then`) walks every registry in the kind chain.
+//!
+//! Run: `cargo test --release -p benilla-ui --lib -- --ignored --nocapture dispatch_bench`.
+
+use std::time::Instant;
+
+use super::common::script;
+
+/// Lookups per timed loop, enough that the loop's own overhead is noise at nanosecond scale.
+const N: usize = 400_000;
+
+/// Timed repeats per row; each row reports the fastest.
+const ROUNDS: usize = 5;
+
+fn ns_per(t: Instant, n: usize) -> f64 {
+    t.elapsed().as_secs_f64() * 1e9 / n as f64
+}
+
+#[test]
+#[ignore = "bench — run explicitly with --release --nocapture"]
+fn dispatch_bench() {
+    let s = script();
+    s.run(
+        r#"
+        F = CreateFrame("Frame")
+        B = CreateFrame("Button")
+        T = F:CreateTexture()
+        S = F:CreateFontString()
+        "#,
+    )
+    .expect("fixtures");
+
+    // The minimum of `ROUNDS` runs: a mean would measure whatever else was running.
+    let floor = |what: &str, chunk: &str| {
+        let mut best = f64::INFINITY;
+        for _ in 0..ROUNDS {
+            let t = Instant::now();
+            s.run(chunk).expect("bench chunk");
+            best = best.min(ns_per(t, N));
+        }
+        println!("[dispatch] {what:>26}  {best:7.1} ns");
+    };
+
+    // The floor: a plain table with a table `__index`, like the reference's flat C method probe.
+    floor(
+        "baseline (table meta)",
+        &format!(
+            "local base = {{ GetWidth = function() end }}
+             local o = setmetatable({{}}, {{ __index = base }})
+             for _ = 1, {N} do local m = o.GetWidth end"
+        ),
+    );
+    floor(
+        "Frame hit",
+        &format!("for _ = 1, {N} do local m = F.GetWidth end"),
+    );
+    floor(
+        "Frame miss",
+        &format!("for _ = 1, {N} do local m = F.NoSuchMethod end"),
+    );
+    floor(
+        "Button hit",
+        &format!("for _ = 1, {N} do local m = B.GetWidth end"),
+    );
+    floor(
+        "Button own hit",
+        &format!("for _ = 1, {N} do local m = B.SetText end"),
+    );
+    floor(
+        "Button miss",
+        &format!("for _ = 1, {N} do local m = B.NoSuchMethod end"),
+    );
+    floor(
+        "Texture hit",
+        &format!("for _ = 1, {N} do local m = T.GetWidth end"),
+    );
+    floor(
+        "Texture miss",
+        &format!("for _ = 1, {N} do local m = T.NoSuchMethod end"),
+    );
+    floor(
+        "FontString hit",
+        &format!("for _ = 1, {N} do local m = S.GetWidth end"),
+    );
+
+    // Whole calls: `GetFrameLevel` is a frame-only binding (one Rust hop); `GetWidth` is one of
+    // `region_map`'s shared names, whose bridge re-enters Lua for the per-side arm.
+    floor(
+        "GetFrameLevel() call",
+        &format!("for _ = 1, {N} do local l = F:GetFrameLevel() end"),
+    );
+    floor(
+        "GetWidth() call (bridged)",
+        &format!("for _ = 1, {N} do local w = F:GetWidth() end"),
+    );
+    floor(
+        "SetPoint() call (bridged)",
+        &format!("for _ = 1, {N} do F:SetPoint(\"CENTER\", 0, 0) end"),
+    );
+
+    // Every geometry getter runs `layout_methods::settle`: free while nothing has moved, a whole
+    // `resolve_layout` after any layout write, so read-after-write pays one per read.
+    floor(
+        "write only",
+        &format!("for i = 1, {N} do F:SetPoint(\"CENTER\", i, 0) end"),
+    );
+    floor(
+        "write + read (settles)",
+        &format!("for i = 1, {N} do F:SetPoint(\"CENTER\", i, 0) local w = F:GetWidth() end"),
+    );
+    floor(
+        "write + read x3 (settles)",
+        &format!(
+            "for i = 1, {N} do F:SetPoint(\"CENTER\", i, 0) local w = F:GetWidth() local h = F:GetHeight() local l = F:GetLeft() end"
+        ),
+    );
+
+    // Controls: `__direct` is one mlua closure, `__wrapped` one that calls another through
+    // `Function::call` as `region_map`'s shared arm does; their gap is one re-entrant Lua call.
+    {
+        let lua = s.lua();
+        let direct = lua
+            .create_function(|_, n: i64| Ok(n + 1))
+            .expect("direct fn");
+        lua.globals().set("__direct", direct.clone()).expect("set");
+        let wrapped = lua
+            .create_function(move |_, n: i64| direct.call::<i64>(n))
+            .expect("wrapped fn");
+        lua.globals().set("__wrapped", wrapped).expect("set");
+
+        // The same pair in the bridge's shape: a variadic `MultiValue` led by the receiver table.
+        let mv_direct = lua
+            .create_function(|_, args: mlua::MultiValue| Ok(args.len() as i64))
+            .expect("mv direct");
+        lua.globals()
+            .set("__mv_direct", mv_direct.clone())
+            .expect("set");
+        let mv_relay = lua
+            .create_function(move |_, args: mlua::MultiValue| {
+                mv_direct.call::<mlua::MultiValue>(args)
+            })
+            .expect("mv relay");
+        lua.globals().set("__mv_relay", mv_relay).expect("set");
+    }
+    floor(
+        "ctrl: 1 mlua hop",
+        &format!("for _ = 1, {N} do local v = __direct(1) end"),
+    );
+    floor(
+        "ctrl: mlua hop + relay",
+        &format!("for _ = 1, {N} do local v = __wrapped(1) end"),
+    );
+    floor(
+        "ctrl: variadic hop",
+        &format!("for _ = 1, {N} do local v = __mv_direct(F, 1, 2) end"),
+    );
+    floor(
+        "ctrl: variadic hop + relay",
+        &format!("for _ = 1, {N} do local v = __mv_relay(F, 1, 2) end"),
+    );
+}
diff --git a/crates/benilla-ui/src/script/tests/end_to_end.rs b/crates/benilla-ui/src/script/tests/end_to_end.rs
index b2d5ee21..566e7499 100644
--- a/crates/benilla-ui/src/script/tests/end_to_end.rs
+++ b/crates/benilla-ui/src/script/tests/end_to_end.rs
@@ -37,9 +37,8 @@ fn end_to_end_two_frame_tree_extracts_in_zkey_order() {
     s.resolve();
     let quads = s.extract();
 
-    // The renderable content, in painter order: parent's bg, child's bg, child's text — parent frame
-    // draws before child (earlier insertion, same strata/level), each frame's regions grouped behind
-    // it (order.rs ZKey).
+    // Painter order: the parent draws before the child (earlier insertion, same strata and level),
+    // each frame's regions with it.
     let content: Vec<String> = quads
         .iter()
         .filter_map(|q| match &q.content {
@@ -57,14 +56,13 @@ fn end_to_end_two_frame_tree_extracts_in_zkey_order() {
         ]
     );
 
-    // SetAllPoints resolves each region to its owner frame's rect. Parent → Rect(300,0,600,400);
-    // child (TOPLEFT+10,-10 of parent, 100×50) → Rect(540,10,590,110).
+    // `SetAllPoints` gives each region its frame's rect: the parent Rect(300, 0, 600, 400), the
+    // child (TOPLEFT +10, -10 of the parent, 100×50) Rect(540, 10, 590, 110).
     let child_text = quads
         .iter()
         .find(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "Hello"))
         .unwrap();
     assert_eq!(child_text.rect, Some(Rect::new(540.0, 10.0, 590.0, 110.0)));
-    // The fontstring got a red vertex color via SetVertexColor(1,0,0,1).
     assert!(
         matches!(&child_text.content, QuadContent::Text { color: Some(c), .. } if *c == [1.0, 0.0, 0.0, 1.0])
     );
@@ -75,7 +73,6 @@ fn end_to_end_two_frame_tree_extracts_in_zkey_order() {
         .unwrap();
     assert_eq!(parent_bg.rect, Some(Rect::new(300.0, 0.0, 600.0, 400.0)));
 
-    // ZKey order is ascending and strictly increasing across the emitted list.
     let zs: Vec<u64> = quads.iter().map(|q| q.z).collect();
     let mut sorted = zs.clone();
     sorted.sort_unstable();
diff --git a/crates/benilla-ui/src/script/tests/events.rs b/crates/benilla-ui/src/script/tests/events.rs
index 1aaea2ec..2a244eee 100644
--- a/crates/benilla-ui/src/script/tests/events.rs
+++ b/crates/benilla-ui/src/script/tests/events.rs
@@ -1,9 +1,5 @@
-//! RegisterEvent + fire_event via BOTH conventions (RF-0025).
-//!
-//! The handler's extra arguments are read through 5.0's implicit `arg` table, not `select(n, ...)`:
-//! `...` as a value is not in this VM's grammar (decision 2101), because it is not in the 1.12
-//! client's. The point of the test is unchanged — the same handler sees the legacy globals
-//! (`this`, `event`, `arg1`) AND the positional arguments.
+//! Event registration and dispatch (`0x704d50`, `0x704f10`). Handlers read varargs through Lua
+//! 5.0's implicit `arg` table: `...` is not a value in the 1.12 client's grammar.
 
 use super::common::script;
 use crate::script::*;
@@ -57,7 +53,7 @@ fn globals_are_restored_after_firing_nesting_safe() {
     )
     .unwrap();
     s.fire_event("E", vec![ScriptValue::Str("x".into())]);
-    // After firing, the prior global values must be restored (RF-0025 set-then-restore).
+    // `0x704f10` sets the globals for the handler and restores the prior values after.
     let (t, e, a): (String, String, String) = s.eval("return this, event, arg1").unwrap();
     assert_eq!(
         (t.as_str(), e.as_str(), a.as_str()),
@@ -82,11 +78,8 @@ fn handler_errors_are_collected_not_panicked() {
     assert!(errs[0].contains("boom"), "{errs:?}");
 }
 
-/// The cross-frame dispatch ORDER law (wow-re `event-dispatch-order.md`, VERIFIED): the client's
-/// per-event listener list is tail-appended (`0x7052d0`) and walked head-first (`0x703e50`) —
-/// **FIFO: registration order = firing order**. Duplicate registration keeps the original
-/// position (`0x702264` dup ret); unregister+re-register moves to the tail. The ZoneText frames
-/// depend on this: both write PVPInfoTextString on one event — the last writer decides.
+/// Each event's listener list is tail-appended (`0x7052d0`) and walked head-first (`0x703e50`);
+/// a duplicate registration returns early (`0x702264`).
 #[test]
 fn events_fire_in_registration_order_fifo() {
     let mut s = script();
@@ -106,43 +99,26 @@ fn events_fire_in_registration_order_fifo() {
     s.fire_event("E", vec![]);
     assert_eq!(s.eval::<String>("return order").unwrap(), "ABC");
 
-    // Duplicate registration keeps A's position (the client's dup early-ret).
+    // A duplicate registration keeps A's position.
     s.run("FA:RegisterEvent('E'); order = ''").unwrap();
     s.fire_event("E", vec![]);
     assert_eq!(s.eval::<String>("return order").unwrap(), "ABC");
 
-    // Unregister + re-register moves B to the TAIL (the node is freed, the re-add appends).
+    // Unregistering frees B's node, so re-registering appends it at the tail.
     s.run("FB:UnregisterEvent('E'); FB:RegisterEvent('E'); order = ''")
         .unwrap();
     s.fire_event("E", vec![]);
     assert_eq!(s.eval::<String>("return order").unwrap(), "ACB");
 }
 
-/// **`HasScript` answers "can this widget CARRY that kind", not "does it have one set".**
-///
-/// That distinction is the verb's whole purpose, and every corpus caller depends on it: they ask
-/// before hooking, precisely when nothing is set yet.
-///
-/// ```lua
-/// if parent:HasScript("OnMouseDown") then          -- Tablet-2.0.lua:2409
-///     local script = parent:GetScript("OnMouseDown")
-///     parent:SetScript("OnMouseDown", function() … end)
-/// end
-/// ```
-///
-/// It was the top session-start blocker — 32 of 39 `attempt to call method` failures were this one
-/// name — and implementing it took survivors from 41 to 69.
-///
-/// The known over-permission is asserted too, so it is a recorded divergence rather than a
-/// discovery: our table is flat where the reference's is per widget type, so a plain Frame answers
-/// true for a Button-only kind. Exact for the base kinds, which is what the corpus asks about.
+/// Callers ask before hooking, when nothing is set yet (`Tablet-2.0.lua:2409`). Our kind table is
+/// flat where the reference's is per widget type, so a Frame also answers true for `OnClick`.
 #[test]
 fn has_script_reports_the_kind_is_supported_not_that_one_is_set() {
     let s = script();
     s.run(r#"f = CreateFrame("Frame", "HasScriptProbe")"#)
         .unwrap();
 
-    // True with NOTHING set — the case every caller is actually in.
     assert!(
         s.eval::<bool>(r#"return f:HasScript("OnMouseDown")"#)
             .unwrap(),
@@ -154,7 +130,7 @@ fn has_script_reports_the_kind_is_supported_not_that_one_is_set() {
         "an unknown kind is false, not true"
     );
 
-    // Tablet's exact idiom, run end to end: guard, read the (absent) handler, install one, fire it.
+    // Tablet's idiom, end to end.
     let fired: bool = s
         .eval(
             r#"
@@ -170,19 +146,15 @@ fn has_script_reports_the_kind_is_supported_not_that_one_is_set() {
         .unwrap();
     assert!(fired, "the guarded hook must install and run");
 
-    // The recorded divergence: flat table, so a Frame says true for a Button-only kind. The
-    // reference says false. Pinned so making SCRIPT_KINDS per-type has to come here and decide.
+    // The flat table: a Frame says true for a Button-only kind, where the reference says false.
     assert!(
         s.eval::<bool>(r#"return f:HasScript("OnClick")"#).unwrap(),
         "over-permissive by design today — see the comment at the binding"
     );
 }
 
-/// **The walk steps by a next saved BEFORE the handler runs** (`0x703ee8`; decision 1324): a
-/// handler that unregisters ITSELF mid-dispatch cannot rob its successor. This is AceEvent-2.0's
-/// fire-once idiom for `PLAYER_LOGIN`/`VARIABLES_LOADED` — its frame unregisters inside the
-/// handler, and the index-walk this replaces skipped whichever addon registered right after it
-/// (Bagnon_Forever's DB never initialized; the director's SaveBagData error dialogs).
+/// The walk saves the next node before the handler runs (`0x703ee8`); AceEvent-2.0's fire-once
+/// idiom unregisters inside its own handler.
 #[test]
 fn a_self_unregistering_handler_does_not_rob_its_successor() {
     let mut s = script();
@@ -208,15 +180,13 @@ fn a_self_unregistering_handler_does_not_rob_its_successor() {
         vec!["WalkA", "WalkB", "WalkC"],
         "the once-idiom's self-removal must not skip the next listener"
     );
-    // The removal held: a second fire reaches only A and C.
     s.fire_event("E", vec![]);
     let log: Vec<String> = s.eval("return log").unwrap();
     assert_eq!(log, vec!["WalkA", "WalkB", "WalkC", "WalkA", "WalkC"]);
 }
 
-/// A handler that unregisters the walk's SAVED next ends the dispatch there — the reference frees
-/// that node and walks into zeroed links (an accident we render as a deterministic stop) — while a
-/// frame registered mid-dispatch tail-appends and is still visited.
+/// Unregistering the walk's saved next ends the dispatch, as the reference frees that node and
+/// walks into its zeroed links; a frame registered mid-dispatch tail-appends and is still visited.
 #[test]
 fn mid_dispatch_removal_of_the_next_stops_and_append_is_visited() {
     let mut s = script();
@@ -271,16 +241,9 @@ fn mid_dispatch_removal_of_the_next_stops_and_append_is_visited() {
     );
 }
 
-/// `Frame:RegisterAllEvents()` — the frame's `OnEvent` receives every event dispatched
-/// (`0x774c20`, table `0x878ec0`, argc 1, arity 0), and `UnregisterAllEvents` clears that state
-/// along with the per-event ones.
-///
-/// **The clearing half is the load-bearing one.** AceEvent-2.0 — shipped by 63 vanilla addons and
-/// 6 of the top 20 — turns all-events on once (`AceEvent.frame:RegisterAllEvents()`), deliberately
-/// stops calling `frame:UnregisterEvent(event)` while it is on, and gets back to per-event
-/// registration by calling `frame:UnregisterAllEvents()` and then re-registering each event it
-/// still wants. A `RegisterAllEvents` that survived that call would leave every Ace2 addon on the
-/// whole event stream for the session.
+/// `RegisterAllEvents` (`0x774c20`, table `0x878ec0`, argc 1, arity 0) sends every event to the
+/// frame's `OnEvent`; `UnregisterAllEvents` clears it too, which is how AceEvent-2.0 gets back to
+/// per-event registration.
 #[test]
 fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
     let mut s = script();
@@ -293,10 +256,8 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
     )
     .unwrap();
 
-    // Arity 0 — the verb answers nothing.
     assert_eq!(s.arity("All:RegisterAllEvents()").unwrap(), 0);
 
-    // Anything dispatched now reaches it, including an event no name list could have enumerated.
     for ev in [
         "PLAYER_LOGIN",
         "UNIT_HEALTH",
@@ -314,9 +275,7 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
         "SOME_SERVER_EVENT_NOBODY_LISTED"
     );
 
-    // Registering twice is a no-op, and a frame holding BOTH an all-events registration and a
-    // RegisterEvent for the same event is one listener, not two — the same rule `RegisterEvent`'s
-    // own `if not already in the list` holds one level down.
+    // All-events plus an explicit registration of the same event is still one listener.
     s.run(r#"seen = {}; All:RegisterAllEvents(); All:RegisterEvent("UNIT_HEALTH")"#)
         .unwrap();
     s.fire_event("UNIT_HEALTH", vec![]);
@@ -326,7 +285,7 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
         "fired once, not twice"
     );
 
-    // UnregisterAllEvents clears BOTH: the explicit UNIT_HEALTH registration and the all-events one.
+    // UnregisterAllEvents clears both registrations.
     s.run("seen = {}; All:UnregisterAllEvents()").unwrap();
     for ev in ["UNIT_HEALTH", "PLAYER_LOGIN"] {
         s.fire_event(ev, vec![]);
@@ -337,7 +296,7 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
         "the all-events registration does not outlive UnregisterAllEvents"
     );
 
-    // …and the AceEvent path back: re-register the individual events it still wants.
+    // AceEvent's way back: re-register the events it still wants.
     s.run(r#"All:RegisterEvent("UNIT_HEALTH")"#).unwrap();
     for ev in ["UNIT_HEALTH", "PLAYER_LOGIN"] {
         s.fire_event(ev, vec![]);
@@ -350,10 +309,6 @@ fn register_all_events_takes_every_event_and_unregister_all_clears_it() {
     assert!(s.take_errors().is_empty());
 }
 
-/// An all-events frame dispatches AFTER the event's own listeners — where it would sit if the
-/// registration were expanded into every per-event list, since it joined later than they did.
-/// Cross-frame order is a law consumers depend on (the two ZoneText frames writing one FontString);
-/// it does not stop being one because a listener asked for everything.
 #[test]
 fn an_all_events_listener_runs_after_the_events_own() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/font_object.rs b/crates/benilla-ui/src/script/tests/font_object.rs
index 57e9b3ed..695f5909 100644
--- a/crates/benilla-ui/src/script/tests/font_object.rs
+++ b/crates/benilla-ui/src/script/tests/font_object.rs
@@ -1,9 +1,5 @@
-//! Font objects as first-class Lua objects ([`crate::script::font`]).
-//!
-//! Every test here is driven **the way the 218-addon corpus drives it** — the bare-global argument,
-//! the no-arg `CreateFontString`, `CreateFont` — rather than the way our own shipped XML does,
-//! because the string-name form our XML uses was the only one we accepted and it is the form
-//! almost nobody writes (6 corpus sites against 3,180).
+//! Font objects as first-class Lua objects ([`crate::script::font`]), driven as addons drive them:
+//! the bare global, the no-argument `CreateFontString`, `CreateFont`.
 
 use super::common::script;
 use crate::script::{FontObject, JustifyH, JustifyV, Outline, QuadContent, UiScript};
@@ -36,14 +32,8 @@ fn painted(s: &UiScript, text: &str) -> (Option<String>, Option<f32>, Option<[f3
         .unwrap_or_else(|| panic!("no text quad reading {text:?}"))
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Publication
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Publication ──
 
-/// A `<Font name="X">` in FrameXML becomes the **global `X`**, an object of type `Font`.
-///
-/// This is the whole gap: we registered the resolved record and never named it, so every
-/// `SetFontObject(GameFontNormal)` in the ecosystem was handed nil.
 #[test]
 fn a_declared_font_is_published_as_a_global_object() {
     let s = script();
@@ -69,13 +59,11 @@ fn a_declared_font_is_published_as_a_global_object() {
         s.eval::<String>("return GameFontNormal:GetName()").unwrap(),
         "GameFontNormal"
     );
-    // Object identity is stable: two reads of the global are the same object, which is what makes
-    // `if fs:GetFontObject() == GameFontNormal` work at all.
+    // Two reads of the global are one object, which `fs:GetFontObject() == GameFontNormal` needs.
     assert!(s
         .eval::<bool>("return GameFontNormal == GameFontNormal")
         .unwrap());
 
-    // The declared paint reads back through the FontInstance getters.
     assert_eq!(
         s.eval::<(String, f32, String)>("return GameFontNormal:GetFont()")
             .unwrap(),
@@ -102,9 +90,7 @@ fn a_declared_font_is_published_as_a_global_object() {
     );
 }
 
-/// **`Tablet-2.0.lua:289`, verbatim.** `_, headerSize = GameTooltipHeaderText:GetFont()` — the
-/// single most-called font-object read in the corpus (268 sites across the four embedded Ace
-/// libraries). Until the global existed, Tablet fell to its hardcoded 14/12 guard branch.
+/// The header-size read at `Tablet-2.0.lua:289`, verbatim.
 #[test]
 fn tablet_reads_the_tooltip_header_size_off_the_global() {
     let s = script();
@@ -140,9 +126,8 @@ fn tablet_reads_the_tooltip_header_size_off_the_global() {
     assert_eq!((header, normal), (14.0, 12.0));
 }
 
-/// **Requirement 5: publishing must not change what `inherits=` resolves to.** The chain is still
-/// flattened once, at load, and the published object carries the *flattened* values — the derived
-/// font sees the parent's face and its own height override.
+/// `inherits=` is flattened once, at load, where the reference links it live (`0x770c60`), and
+/// the published object carries the flattened values.
 #[test]
 fn an_inheriting_font_still_flattens_to_the_same_values() {
     let s = script();
@@ -159,7 +144,6 @@ fn an_inheriting_font_still_flattens_to_the_same_values() {
              </Font>
            </Ui>"#,
     );
-    // The Rust-side record — unchanged by publication.
     let derived = s.font_object("DerivedFont").expect("registered");
     assert_eq!(derived.font.as_deref(), Some("Fonts\\FRIZQT__.TTF"));
     assert_eq!(derived.height, Some(18.0));
@@ -167,7 +151,6 @@ fn an_inheriting_font_still_flattens_to_the_same_values() {
     assert_eq!(derived.outline, Outline::Normal);
     assert_eq!(derived.justify_h, Some(JustifyH::Center));
     assert!(derived.shadow.is_some(), "the shadow inherits too");
-    // …and the same values through the published object.
     assert_eq!(
         s.eval::<(String, f32, String)>("return DerivedFont:GetFont()")
             .unwrap(),
@@ -179,16 +162,10 @@ fn an_inheriting_font_still_flattens_to_the_same_values() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// SetFontObject / GetFontObject
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── SetFontObject and GetFontObject ──
 
-/// **`Gratuity-2.0.lua:47-59`, verbatim** — the block that took five corpus addons down at load
-/// with `bad argument #2: error converting Lua nil to String`.
-///
-/// Three separate things have to hold for it: `CreateFontString()` with **no arguments**,
-/// `SetFontObject` taking the **object**, and `AddFontStrings` existing at all (fixing only the
-/// first two moves the death one line down).
+/// The tooltip build at `Gratuity-2.0.lua:47-59`: it needs a no-argument `CreateFontString`,
+/// `SetFontObject` taking the object, and `AddFontStrings`.
 #[test]
 fn gratuity_builds_its_thirty_line_scan_tooltip() {
     let s = script();
@@ -218,7 +195,6 @@ fn gratuity_builds_its_thirty_line_scan_tooltip() {
     .expect("Gratuity's CreateTooltip must not raise");
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 
-    // The font object actually landed on the lines it made.
     assert_eq!(
         s.eval::<(String, f32)>("return vars.Llines[7]:GetFont()")
             .unwrap(),
@@ -229,13 +205,10 @@ fn gratuity_builds_its_thirty_line_scan_tooltip() {
             .unwrap(),
         "GameFontNormal"
     );
-    // And Gratuity's own next move — `ClearLines` over the grown stack — still works.
+    // Gratuity's next call: `ClearLines` over the grown line stack.
     s.run("vars.tooltip:ClearLines()").unwrap();
 }
 
-/// The object form and the string form must resolve to **the same paint**. Both are kept: the
-/// object is what 3,180 of 3,186 corpus sites pass, the string is what our own `assets/ui` and 6
-/// corpus sites pass.
 #[test]
 fn set_font_object_takes_the_object_or_the_name() {
     let mut s = script();
@@ -275,14 +248,12 @@ fn set_font_object_takes_the_object_or_the_name() {
             Some([0.25, 0.5, 0.75, 1.0])
         )
     );
-    // …and both name the same object back.
     assert!(s
         .eval::<bool>("return byObject:GetFontObject() == byName:GetFontObject()")
         .unwrap());
 
-    // nil is the THIRD form the reference's own usage string names
-    // (`SetFontObject(font or "font" or nil)`, `.rdata 0x87c5cc`): it severs the link and leaves
-    // the paint standing.
+    // nil, the third form in the reference's usage string (`.rdata 0x87c5cc`), unlinks the object
+    // and leaves the paint.
     s.run("byName:SetFontObject(nil)").unwrap();
     assert!(s
         .eval::<bool>("return byName:GetFontObject() == nil")
@@ -293,14 +264,11 @@ fn set_font_object_takes_the_object_or_the_name() {
         Some(11.0),
         "unlinking must not repaint"
     );
-    // A frame or an unknown name is still an ERROR, never a silent no-op (1203/1205/1211's class).
     assert!(s.run("byName:SetFontObject(f)").is_err());
     assert!(s.run("byName:SetFontObject('NoSuchFont')").is_err());
 }
 
-/// `GetFontObject` returns the **object**, not a name — because `Dewdrop-2.0.lua:2181` indexes the
-/// result immediately: `button.text:SetTextColor(button.text:GetFontObject():GetTextColor())`.
-/// 65 sites across 62 corpus addons do exactly this.
+/// `GetFontObject` returns the object, not a name, which `Dewdrop-2.0.lua:2181` indexes at once.
 #[test]
 fn dewdrop_recolors_a_row_from_its_own_font_object() {
     let mut s = script();
@@ -332,17 +300,10 @@ fn dewdrop_recolors_a_row_from_its_own_font_object() {
     assert_eq!(painted(&s, "row").2, Some([1.0, 1.0, 1.0, 1.0]));
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Mutability — the decision, pinned
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Mutability ──
 
-/// **The mutability decision.** A font object is a shared record with a **live** link: mutating it
-/// re-paints every FontString that inherits it, which is why addons mutate one at all. What a
-/// FontString set *for itself* since its own `SetFontObject` survives that re-paint — our
-/// `FONTINSTANCE+0x038 explicitlySetMask`.
-///
-/// If this ever regresses to a one-shot copy, `inherited` stops moving and the test says so; if the
-/// mask is dropped, `overridden` loses its red.
+/// A font object is a live link: mutating it repaints every FontString that inherits it, except
+/// what a FontString set for itself, whose setter cleared that property's inherit-mask bit.
 #[test]
 fn mutating_a_font_object_repaints_everything_that_inherits_it() {
     let mut s = script();
@@ -375,7 +336,6 @@ fn mutating_a_font_object_repaints_everything_that_inherits_it() {
     assert_eq!(painted(&s, "inherited").1, Some(12.0));
     assert_eq!(painted(&s, "overridden").2, Some([1.0, 0.0, 0.0, 1.0]));
 
-    // The mutation the whole feature exists for.
     s.run(
         r#"
         ThemeFont:SetFont("Fonts\\MORPHEUS.TTF", 20)
@@ -385,7 +345,6 @@ fn mutating_a_font_object_repaints_everything_that_inherits_it() {
     .unwrap();
     s.resolve();
 
-    // Both followed the face and size…
     assert_eq!(
         painted(&s, "inherited"),
         (
@@ -399,17 +358,14 @@ fn mutating_a_font_object_repaints_everything_that_inherits_it() {
         Some("Fonts\\MORPHEUS.TTF".into())
     );
     assert_eq!(painted(&s, "overridden").1, Some(20.0));
-    // …but the one that had set its own colour kept it.
     assert_eq!(
         painted(&s, "overridden").2,
         Some([1.0, 0.0, 0.0, 1.0]),
         "an explicitly-set property must survive a font-object mutation"
     );
 
-    // §5-verified: severance SURVIVES a re-point. The reference's inheritMask bit (`+0x2c`,
-    // FontString `+0xd4`) is cleared by the local setter and never restored, so "a FontString that
-    // set its own colour stays severed even across a later SetFontObject". Our first cut reset the
-    // mask here and this assertion was its inverse.
+    // Severance survives a re-point: the local setter clears the reference's inheritMask bit
+    // (`+0x2c`, FontString `+0xd4`) and nothing restores it.
     s.run("b:SetFontObject(ThemeFont)").unwrap();
     s.resolve();
     assert_eq!(
@@ -417,16 +373,13 @@ fn mutating_a_font_object_repaints_everything_that_inherits_it() {
         Some([1.0, 0.0, 0.0, 1.0]),
         "a re-point must not restore inheritance of a severed property"
     );
-    // Dewdrop still works, because it re-reads the colour off the new object explicitly every
-    // refresh (`Dewdrop-2.0.lua:2181`) rather than relying on inheritance.
+    // Dewdrop re-reads the colour off the object every refresh (`Dewdrop-2.0.lua:2181`).
     s.run("b:SetTextColor(b:GetFontObject():GetTextColor())")
         .unwrap();
     s.resolve();
     assert_eq!(painted(&s, "overridden").2, Some([0.0, 1.0, 0.0, 1.0]));
 }
 
-/// A mutation of a font object nobody inherits touches nothing, and a FontString that inherits a
-/// *different* object is not caught in the sweep.
 #[test]
 fn propagation_is_scoped_to_the_object_that_changed() {
     let mut s = script();
@@ -458,14 +411,10 @@ fn propagation_is_scoped_to_the_object_that_changed() {
     assert_eq!(painted(&s, "two").1, Some(12.0));
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// CreateFont
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── CreateFont ──
 
-/// **`_Nameplates.lua:149` + `:129` + `:212`, end to end** — mint a font object at runtime, set it
-/// up, then paint a FontString with it. Plus `!OmniCC/main.lua:40-41`'s half: the name is published
-/// as a global even when the return value is thrown away, and `SetFont`'s return is the font-file
-/// validity probe OmniCC uses it as.
+/// `_Nameplates.lua:149`, `:129` and `:212`, then `!OmniCC/main.lua:40-41`: the name is published
+/// even when the return is dropped, and `SetFont`'s return says whether the face loaded.
 #[test]
 fn create_font_mints_publishes_and_paints() {
     let mut s = script();
@@ -494,7 +443,6 @@ fn create_font_mints_publishes_and_paints() {
         )
     );
 
-    // The return value and the published global are the SAME object — OmniCC reads only the global.
     assert!(s
         .eval::<bool>("return _NameplatesNameplateFont == Nameplate.Font")
         .unwrap());
@@ -504,8 +452,7 @@ fn create_font_mints_publishes_and_paints() {
         "Font"
     );
 
-    // `!OmniCC/main.lua:40-41` verbatim: create, discard the return, use the global, and branch on
-    // SetFont's return to detect a saved font path that is no longer usable.
+    // `!OmniCC/main.lua:40-41`: create, drop the return, then branch on the global's `SetFont`.
     let reverted = s
         .eval::<bool>(
             r#"
@@ -528,9 +475,7 @@ fn create_font_mints_publishes_and_paints() {
         ("Fonts\\FRIZQT__.TTF".to_string(), 20.0, String::new())
     );
 
-    // A name that already names a font object hands the existing one back UNCHANGED — the
-    // non-destructive reading (see `create_font`'s doc). The alternative would let
-    // `CreateFont("GameFontNormal")` blank the shipped registry entry the whole UI inherits.
+    // A name that already names a font object returns that object unchanged (`0x7839ab`).
     s.run("again = CreateFont('_NameplatesNameplateFont')")
         .unwrap();
     assert!(s.eval::<bool>("return again == Nameplate.Font").unwrap());
@@ -540,14 +485,12 @@ fn create_font_mints_publishes_and_paints() {
         ("Fonts\\SKURRI.TTF".to_string(), 10.0, String::new())
     );
 
-    // A nameless CreateFont is an error: the name IS the publication. The EMPTY name is not —
-    // the reference's `lua_isstring` gate takes it (unlike the XML path), so we do too.
+    // A nameless `CreateFont` raises; the empty name passes the reference's `lua_isstring` gate.
     assert!(s.run("CreateFont()").is_err());
     s.run("CreateFont('')").unwrap();
 }
 
-/// **`FonzAppraiser/mods/gui/gui.lua:27-30`** — `CreateFont` then `CopyFontObject(<a shipped
-/// object>)` then override the face. The corpus's only Font-on-Font call.
+/// The sequence at `FonzAppraiser/mods/gui/gui.lua:27-30`.
 #[test]
 fn fonz_appraiser_copies_a_shipped_object_then_overrides_the_face() {
     let s = script();
@@ -571,7 +514,6 @@ fn fonz_appraiser_copies_a_shipped_object_then_overrides_the_face() {
     "#,
     )
     .expect("FonzAppraiser's font setup must not raise");
-    // The copy brought the colour and justification over; the SetFont replaced the face and size.
     assert_eq!(
         s.eval::<(String, f32, String)>("return small_number_font:GetFont()")
             .unwrap(),
@@ -587,7 +529,6 @@ fn fonz_appraiser_copies_a_shipped_object_then_overrides_the_face() {
             .unwrap(),
         "RIGHT"
     );
-    // …and the object it copied FROM is untouched.
     assert_eq!(
         s.eval::<(String, f32, String)>("return GameFontHighlightSmall:GetFont()")
             .unwrap(),
@@ -595,10 +536,8 @@ fn fonz_appraiser_copies_a_shipped_object_then_overrides_the_face() {
     );
 }
 
-/// The `Spacing` pair is **deliberately absent** (we model no line spacing, and a stored-but-never
-/// drawn setter is this codebase's recurring silent-drop bug). It must fail LOUDLY rather than
-/// quietly accept a number nobody honours — this test is the tripwire on that choice, and it flips
-/// the day spacing becomes real.
+/// Line spacing is not built: the reference's `SetSpacing` is absent here, so a call raises rather
+/// than store a number nothing draws.
 #[test]
 fn the_unmodelled_spacing_pair_fails_loudly() {
     let s = script();
@@ -607,9 +546,8 @@ fn the_unmodelled_spacing_pair_fails_loudly() {
     assert!(s.eval::<bool>("return SomeFont.SetSpacing == nil").unwrap());
 }
 
-/// A button's per-state label fonts take the object or the name too (the corpus splits 5 to 4
-/// across the trio), and — because they are stored as NAMES and re-resolved at every extract — a
-/// later mutation of that font object reaches the label with no further call.
+/// A button's state fonts take the object or the name; they are stored as names and re-resolved at
+/// every extract, so a later mutation of the object reaches the label.
 #[test]
 fn button_state_fonts_take_the_object_and_follow_its_mutation() {
     let mut s = script();
@@ -647,14 +585,11 @@ fn button_state_fonts_take_the_object_and_follow_its_mutation() {
         )
     );
 
-    // The string form still works alongside it.
     s.run("b:SetHighlightFontObject('GameFontNormal')").unwrap();
 }
 
-/// **A `CreateFont` object holds nothing, so pointing a FontString at it copies nothing.**
-/// §5-verified: the reference gates every merge on the source's own has-a-value mask, and a fresh
-/// font has `mask == 0` — the FontString keeps exactly what it had, no blanking and no fallback to
-/// a default. Our first cut wrote face/height through unconditionally and would have wiped it.
+/// The reference gates every merge (`0x770910`/`0x770800`) on the source's has-a-value mask, and a
+/// fresh `CreateFont` object's mask is 0, so the FontString keeps what it had.
 #[test]
 fn an_empty_font_object_copies_nothing_onto_a_fontstring() {
     let mut s = script();
@@ -690,7 +625,7 @@ fn an_empty_font_object_copies_nothing_onto_a_fontstring() {
         ),
         "an unset property must copy nothing, not blank the region"
     );
-    // The link still moved, so once the blank font is dressed the string follows it.
+    // The link still moves: once the blank font is dressed, the string follows it.
     assert_eq!(
         s.eval::<String>("return fs:GetFontObject():GetName()")
             .unwrap(),
@@ -701,8 +636,7 @@ fn an_empty_font_object_copies_nothing_onto_a_fontstring() {
     assert_eq!(painted(&s, "keep").0, Some("Fonts\\MORPHEUS.TTF".into()));
 }
 
-/// `SetFont` returns **1 or nil**, not a boolean — the reference's exact return shape, and what
-/// `!OmniCC/main.lua:41` branches on.
+/// The reference's return shape, not a boolean; `!OmniCC/main.lua:41` branches on it.
 #[test]
 fn set_font_returns_one_or_nil() {
     let s = script();
@@ -715,15 +649,8 @@ fn set_font_returns_one_or_nil() {
     assert!(s.eval::<bool>("return f:SetFont('', 12) == nil").unwrap());
 }
 
-/// The justify law is **one** table in the binary (`.rdata 0x811ad0`) and must be one
-/// transcription here: a `FontString` and a `<Font>` object have to answer identically, token for
-/// token and raise for raise.
-///
-/// They did not. Both sides were written separately from the same law and each drifted its own
-/// way — the FontString had no `GetJustifyH`/`GetJustifyV` at all (real entries `0x79e5f0` /
-/// `0x79e7f0`), the Font object silently `.trim()`ed its argument where `SStrCmpI` compares the
-/// whole string, and both quietly answered CENTER for a string the reference raises on. Every
-/// test on both sides passed throughout. This is the net that makes the next drift fail.
+/// The justify tokens are one reference table (`.rdata 0x811ad0`) matched whole and case-blind by
+/// `SStrCmpI`; a FontString (getters `0x79e5f0`/`0x79e7f0`) and a `<Font>` object answer alike.
 #[test]
 fn both_tables_speak_one_justify_law() {
     let s = script();
@@ -735,7 +662,7 @@ fn both_tables_speak_one_justify_law() {
     .unwrap();
 
     for obj in ["fs", "fo"] {
-        // The client's ctor default `0x212` = CENTER | MIDDLE | 0x200, read through each mask.
+        // The reference's constructor default `0x212`, CENTER | MIDDLE | 0x200, read per axis.
         let h = s
             .eval::<String>(&format!("return {obj}:GetJustifyH()"))
             .unwrap();
@@ -758,7 +685,7 @@ fn both_tables_speak_one_justify_law() {
             }
         }
 
-        // A non-token raises the reference's own usage string rather than coercing to CENTER.
+        // A non-token raises the reference's usage string rather than coercing to CENTER.
         for verb in ["SetJustifyH", "SetJustifyV"] {
             let err = s
                 .run(&format!("{obj}:{verb}('MIDDLE_LEFT')"))
@@ -770,27 +697,21 @@ fn both_tables_speak_one_justify_law() {
             );
         }
 
-        // Whole-string: a trailing space is a miss. The Font object used to trim it away.
+        // The match is whole-string: a trailing space is a miss.
         assert!(
             s.run(&format!("{obj}:SetJustifyH('LEFT ')")).is_err(),
             "{obj}:SetJustifyH must not trim its argument"
         );
 
-        // A cross-axis token matches the table, so it is accepted with no error — the one place
-        // we knowingly stop short of the law (the reference clears the axis; see `script::justify`).
+        // A cross-axis token is in the table and raises nothing. The reference then clears the
+        // axis; the FontString does too, the `<Font>` object leaves it as it was.
         s.run(&format!("{obj}:SetJustifyH('TOP')")).unwrap();
         s.run(&format!("{obj}:SetJustifyV('LEFT')")).unwrap();
     }
 }
 
-/// `SetFont` is one routine (`0x79f210`) with three entry points — Font `0x7a0270`, FontString
-/// `0x79d4f0`, EditBox `0x797210` — so all three must answer identically, and none of them did.
-///
-/// The FontString's hand-written copy answered the boolean `true` for *everything*, including the
-/// empty-path load failure that `!OmniCC/main.lua:41`'s `if not f:SetFont(saved, size)` probes;
-/// the `<Font>` object's took `Option` arguments and so answered **nil** for `SetFont()` where the
-/// reference raises `Usage: %s:SetFont("font", fontHeight [, flags])` (`0x87c69c`). A behavioural
-/// differential across both tables is what surfaced it — arity alone had matched.
+/// `SetFont` is one routine (`0x79f210`) behind three entries, Font `0x7a0270`, FontString
+/// `0x79d4f0` and EditBox `0x797210`; a bad argument raises its usage string (`0x87c69c`).
 #[test]
 fn set_font_is_one_routine_on_both_tables() {
     let s = script();
@@ -798,7 +719,6 @@ fn set_font_is_one_routine_on_both_tables() {
         .unwrap();
 
     for obj in ["fs", "fo"] {
-        // Success is the NUMBER 1 — never a boolean, and never zero values.
         let n = s
             .eval::<f32>(&format!(
                 "return {obj}:SetFont('Fonts\\\\FRIZQT__.TTF', 12)"
@@ -813,15 +733,14 @@ fn set_font_is_one_routine_on_both_tables() {
             "{obj}:SetFont must answer the number 1, not true"
         );
 
-        // An empty path is the LOAD FAILURE edge: nil, falsey, and nothing raised.
+        // An empty path is a load failure: nil, and nothing raised.
         assert!(
             s.eval::<bool>(&format!("return {obj}:SetFont('', 12) == nil"))
                 .unwrap(),
             "{obj}:SetFont('') must answer nil"
         );
 
-        // A missing or non-string path, or a missing height, is an ARGUMENT error — it raises,
-        // which is a different thing from the nil above and used to be conflated with it.
+        // A missing or non-string path, or a missing height, is an argument error and raises.
         for bad in ["", "'Fonts\\\\FRIZQT__.TTF'", "nil, 12", "{}, 12"] {
             let err = s
                 .run(&format!("{obj}:SetFont({bad})"))
@@ -832,7 +751,7 @@ fn set_font_is_one_routine_on_both_tables() {
             );
         }
 
-        // Both `lua_isstring` and `lua_isnumber` coerce, so a numeric string is accepted for either.
+        // Both `lua_isstring` and `lua_isnumber` coerce, so either accepts a numeric string.
         assert!(
             s.eval::<bool>(&format!(
                 "return {obj}:SetFont('Fonts\\\\FRIZQT__.TTF', '14') == 1"
@@ -843,17 +762,9 @@ fn set_font_is_one_routine_on_both_tables() {
     }
 }
 
-/// A cross-axis token **erases** its axis, and the two readers then disagree — faithfully.
-///
-/// `SetJustifyH("TOP")` parses (`0x08`), contributes nothing to mask `0x07`, and raises nothing.
-/// `GetJustifyH()` afterwards answers the literal `"UNKNOWN"` (`0x6f1a00` → `.data 0x838044`),
-/// while the glyphs keep drawing **centred**: the ui→gx translator `0x44d420` is a priority ladder
-/// whose per-axis register is pre-set to `1` between the `test` and the `jcc`, so an all-clear axis
-/// exits with CENTER still in it. Reading the getter's answer into the draw path — or mapping the
-/// bitmask onto the gx enum with a `0` default — inverts the axis to LEFT.
-///
-/// Reached by 13 corpus sites (`FonzAppraiser` ×12, `Roid-Macros`) writing
-/// `SetJustifyV("CENTER")` when they mean MIDDLE.
+/// `SetJustifyH("TOP")` parses (`0x08`), sets nothing in the axis mask `0x07` and raises nothing;
+/// `GetJustifyH` then answers `"UNKNOWN"` (`0x6f1a00`, `.data 0x838044`), yet the ui-to-gx
+/// translator `0x44d420` pre-sets each axis to 1, so the text still draws centred, not LEFT.
 #[test]
 fn a_cross_axis_token_erases_the_axis_but_still_draws_centred() {
     let mut s = script();
@@ -866,13 +777,13 @@ fn a_cross_axis_token_erases_the_axis_but_still_draws_centred() {
     )
     .unwrap();
 
-    // A real token lands, so the erase below is visibly an erase and not a no-op.
+    // A real token first, so the erase below is not a no-op.
     s.run("fs:SetJustifyH('LEFT') fs:SetJustifyV('TOP')")
         .unwrap();
     assert_eq!(s.eval::<String>("return fs:GetJustifyH()").unwrap(), "LEFT");
     assert_eq!(s.eval::<String>("return fs:GetJustifyV()").unwrap(), "TOP");
 
-    // The cross-axis pair: each erases the OTHER axis it was aimed at, raising nothing.
+    // Each setter gets the other axis's token: it clears its own axis and raises nothing.
     s.run("fs:SetJustifyH('TOP')").unwrap();
     s.run("fs:SetJustifyV('CENTER')").unwrap();
     assert_eq!(
@@ -885,7 +796,6 @@ fn a_cross_axis_token_erases_the_axis_but_still_draws_centred() {
         "UNKNOWN"
     );
 
-    // ...and the draw path answers CENTER/MIDDLE for that same state.
     s.resolve();
     let (h, v) = s
         .extract()
@@ -907,16 +817,9 @@ fn a_cross_axis_token_erases_the_axis_but_still_draws_centred() {
     );
 }
 
-/// The font block is a **per-table membership fact**, and wow-re's registrar carve names the six:
-/// *"Exposed on: FontString, Font object, EditBox, MessageFrame, ScrollingMessageFrame,
-/// SimpleHTML. NOT on Button."* We shipped it on two; these are the third and fourth.
-///
-/// `BigWigs/Plugins/Messages.lua:212` — `self.msgframe:SetFontObject(GameFontNormalLarge)` on a
-/// frame it has just given `SetInsertMode("TOP")` — died there every session.
-///
-/// The second assertion is the trap: a message frame's lines fall back to **LEFT** when it has no
-/// declared `<FontString>`, while a freshly created `RegionData` defaults to the FontString's own
-/// CENTER. Creating the style region on demand must not silently re-justify the frame.
+/// The shared font block (`0x79f910`, FontString's `0x79dbe0`) is on six tables: FontString, Font,
+/// EditBox, MessageFrame, ScrollingMessageFrame and SimpleHTML, not Button. A message frame with no
+/// `<FontString>` draws LEFT, and creating its style region (CENTER by default) must keep it LEFT.
 #[test]
 fn the_font_block_reaches_both_message_frame_tables() {
     let mut s = script();
@@ -938,7 +841,7 @@ fn the_font_block_reaches_both_message_frame_tables() {
             "MsgBlockFont",
             "{obj}:GetFontObject must answer the OBJECT it was given"
         );
-        // The shared `0x79f210` contract, same as every other table that carries it.
+        // The shared `SetFont` contract (`0x79f210`).
         assert!(
             s.eval::<bool>(&format!(
                 "return {obj}:SetFont('Fonts\\\\MORPHEUS.TTF', 16) == 1"
@@ -950,11 +853,10 @@ fn the_font_block_reaches_both_message_frame_tables() {
             .eval::<(mlua::Value, f32, String)>(&format!("return {obj}:GetFont()"))
             .unwrap();
         assert_eq!(height, 16.0, "{obj}:GetFont reads back what SetFont wrote");
-        // The four-value getters the carve pins at 4 for every one of the six tables.
+        // The four-value getters return four values on all six tables (`0x79f9b3`).
         assert_eq!(s.arity(&format!("{obj}:GetShadowColor()")).unwrap(), 4);
     }
 
-    // Styling the frame must not move its text: the lines still run flush LEFT.
     s.run("mf:AddMessage('flush left please')").unwrap();
     s.resolve();
     let j = s
@@ -976,18 +878,8 @@ fn the_font_block_reaches_both_message_frame_tables() {
     );
 }
 
-/// `CreateFontString`'s **third argument** applies a font object — the argument we accepted and
-/// then dropped on the floor (decision 1255).
-///
-/// 49 corpus call sites across 5 distinct addons pass one, and every one names a font object:
-/// AckisRecipeList (28), CustomNameplates (10), _LazyPig (6), LibAboutPanel (4), ColorPickerPlus.
-/// Five separate addons, so this is not one library file replicated. Ignoring it was 1203's class —
-/// the addon asks for a font, the call succeeds, and the text comes out in the default with no
-/// failure anywhere to point at.
-///
-/// The **order** is the part a reimplementation loses: the font-object registry is tried FIRST and
-/// the template registry only on a font miss (`0x773d39` then `0x773d47`). A template-first
-/// resolver would miss all 49 of these, because `inherits=` is one argument over two namespaces.
+/// The third argument is looked up as a font object first, and as a template only on a miss
+/// (`0x773d39`, then `0x773d47`).
 #[test]
 fn create_font_string_applies_the_font_object_named_by_its_third_argument() {
     let s = script();
@@ -1002,7 +894,7 @@ fn create_font_string_applies_the_font_object_named_by_its_third_argument() {
            </Ui>"#,
     );
 
-    // Exactly `_LazyPig/LazyPigMenu.lua:88`'s line.
+    // The call at `_LazyPig/LazyPigMenu.lua:88`.
     s.run(r#"FS = Host:CreateFontString(nil, "ARTWORK", "GameFontNormalSmall")"#)
         .expect("the font-object form must be accepted");
     let (face, height, _flags) = s
@@ -1011,8 +903,7 @@ fn create_font_string_applies_the_font_object_named_by_its_third_argument() {
     assert_eq!(face, "Fonts\\FRIZQT__.TTF");
     assert_eq!(height, 12.0);
 
-    // A name in NEITHER registry raises — the same contract 1253 set for CreateFrame, and the same
-    // bytes (`luaL_error`, which never returns).
+    // A name in neither registry raises (`luaL_error`), as an unknown `CreateFrame` template does.
     let err = s
         .run(r#"Bad = Host:CreateFontString(nil, "ARTWORK", "NoSuchFontOrTemplate")"#)
         .expect_err("a name in neither registry must raise");
@@ -1021,22 +912,13 @@ fn create_font_string_applies_the_font_object_named_by_its_third_argument() {
         "the raise must name what was looked up: {err}"
     );
 
-    // Texture takes the same argument through the same resolver (1 real corpus site).
+    // `CreateTexture` takes the same third argument through the same resolver.
     s.run(r#"TX = Host:CreateTexture(nil, "OVERLAY")"#)
         .expect("the two-argument form still works");
 }
 
-/// **`SetFont`'s nil is a LOAD failure, and only the host knows** (decision 2103).
-///
-/// The reference answers the number 1 or nil (`0x79f345`/`0x79f361`), and the nil originates in
-/// the font factory at `0x5c1ae0` — a path that names no readable file. `!OmniCC/main.lua:41`
-/// reads it exactly that way (`if not Font:SetFont(saved, size) then revert end`), and an addon
-/// that ships its own faces (MSBT ships thirty-one, under `Interface\Addons\…\Fonts\`) is the
-/// case that makes the answer depend on a store rather than on the string.
-///
-/// The engine-less default is the other half: with no probe a non-empty path answers 1, because a
-/// VM with no font backend has nothing for a load to fail against. That is the opposite default to
-/// `SetTexture`'s (1322) and the reason is in `Model::font_probe`.
+/// The reference answers 1 or nil (`0x79f345`/`0x79f361`), nil when the font factory (`0x5c1ae0`)
+/// finds no readable file; with no host probe, any non-empty path answers 1.
 #[test]
 fn set_font_answers_the_hosts_load_verdict_when_there_is_a_host() {
     let mut s = script();
@@ -1049,8 +931,7 @@ fn set_font_answers_the_hosts_load_verdict_when_there_is_a_host() {
         .unwrap());
     assert!(s.eval::<bool>("return FS:SetFont('', 12) == nil").unwrap());
 
-    // With one, the store decides — and the face it refused is NOT adopted, so the region keeps
-    // the last font that did load.
+    // With a probe the store decides, and a refused face is not adopted.
     s.set_font_probe(Box::new(|path| {
         path.eq_ignore_ascii_case("interface\\addons\\msbt\\fonts\\porky.ttf")
             || path.eq_ignore_ascii_case("fonts\\frizqt__.ttf")
@@ -1078,20 +959,8 @@ fn set_font_answers_the_hosts_load_verdict_when_there_is_a_host() {
     assert_eq!(height, 18.0, "…while the height, which never fails, is set");
 }
 
-/// **Mik's Scrolling Battle Text, end to end** — the exact sequence the addon runs per event,
-/// pinned because it is the shape a whole class of "the addon's font did not take" reports wears
-/// (decisions 2103, 2112).
-///
-/// MSBT's twenty scroll-area FontStrings are declared `inherits="MasterFont"` — the reference's
-/// root font object, which carries a `<Shadow>` and **nothing else**: no face, no height, no
-/// outline. Each animation then does, in this order, on the string it recycles:
-/// `ClearAllPoints · SetFont(<its own TTF>, 18, "OUTLINE") · SetTextColor · SetText · SetAlpha ·
-/// SetPoint`. Every one of those five paint axes has to reach the extracted quad *unmodified* by
-/// the object the string inherits — the addon's face over the object's absent one, the addon's
-/// height over the renderer default, the addon's outline over the object's `NONE` (which is
-/// indistinguishable from "unset", see [`Outline`]), its colour over the object's absent one, and
-/// the animation's fade as the quad's own alpha. The `<Shadow>` is the one thing that IS inherited,
-/// and it must still be there.
+/// MSBT's per-event sequence over the stock `MasterFont` (`Fonts.xml:55`, a `<Shadow>` only): its
+/// own face, size, outline, colour and fade reach the quad, and the shadow is inherited.
 #[test]
 fn msbt_paints_its_own_face_size_outline_and_fade_over_the_font_object_it_inherits() {
     let mut s = script();
@@ -1159,7 +1028,6 @@ fn msbt_paints_its_own_face_size_outline_and_fade_over_the_font_object_it_inheri
         }
         ref other => panic!("expected a Text quad, got {other:?}"),
     }
-    // The Lua-visible echo agrees with the quad — the readback an addon branches on.
     assert_eq!(
         s.eval::<(String, f32, String)>("return MSBTFrameIncomingText1:GetFont()")
             .unwrap(),
diff --git a/crates/benilla-ui/src/script/tests/frame_api.rs b/crates/benilla-ui/src/script/tests/frame_api.rs
index c1ce8bfc..fc9c20c5 100644
--- a/crates/benilla-ui/src/script/tests/frame_api.rs
+++ b/crates/benilla-ui/src/script/tests/frame_api.rs
@@ -1,18 +1,12 @@
-//! Small frame-API wins: GetLocale, SetAllPoints, and GetPoint readback.
+//! Frame-API basics: `GetLocale`, `SetAllPoints` and `GetPoint` readback.
 
 use super::common::script;
 
-/// Two era names, asserted together because neither earns a file of its own.
-///
-/// This test carried two more legs until decision 2142, `SetFormattedText` and `SetShown`, and
-/// both went with the verbs: neither is in a 1.12 method table. What the first of them actually
-/// proved — that `%N$s` reorders rather than consumes — is `string.format`'s own behaviour and is
-/// pinned where it lives, in [`crate::strings`].
 #[test]
 fn get_locale_and_set_all_points() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
-    // GetLocale — benilla is enUS-data-only.
+    // `GetLocale`: benilla is enUS-only.
     assert_eq!(s.eval::<String>("return GetLocale()").unwrap(), "enUS");
 
     s.run(
@@ -28,7 +22,6 @@ fn get_locale_and_set_all_points() {
     .unwrap();
     s.resolve();
 
-    // SetAllPoints pins the full target rect, parent-default and by-name forms alike.
     let ok: bool = s
         .eval(
             r#"
@@ -53,7 +46,7 @@ fn getpoint_reads_back_anchors() {
     "#,
     )
     .unwrap();
-    // Screen-anchored: relativeTo is nil (no UIParent wrapper yet — stated).
+    // Screen-anchored: `relativeTo` reads nil.
     let ok: bool = s
         .eval(
             r#"
@@ -63,7 +56,7 @@ fn getpoint_reads_back_anchors() {
         )
         .unwrap();
     assert!(ok, "screen anchor reads back");
-    // Frame-anchored: relativeTo is the same wrapper table (stable identity).
+    // Frame-anchored: `relativeTo` is the same wrapper table.
     let ok: bool = s
         .eval(
             r#"
diff --git a/crates/benilla-ui/src/script/tests/generic_for.rs b/crates/benilla-ui/src/script/tests/generic_for.rs
index ee7589ec..1b8051ff 100644
--- a/crates/benilla-ui/src/script/tests/generic_for.rs
+++ b/crates/benilla-ui/src/script/tests/generic_for.rs
@@ -1,21 +1,9 @@
-//! Lua 5.0's iterator-less generic-for, restored in the vendored VM (decision 1215).
-//!
-//! `for k, v in someTable do` is Lua 5.0 syntax that 5.1 removed at the OPCODE level. 183 of 218
-//! corpus addons are reached by it and it is the first session-start error for 60 of them — three
-//! quarters of everything that breaks in a running session. The fix is 5.0's `OP_TFORPREP` folded
-//! into `OP_TFORLOOP` in `third_party/lua-src/lua-5.1.5/lvm.c`.
-//!
-//! Each test below pins one detail that was byte-verified in the real 1.12.1 client (wow-5875-re
-//! `system/ui/scratch/lua-generic-for.md`), because each is a place where a *reasonable* guess
-//! diverges from what the client does. The `__call` case is the sharpest: two of the three
-//! conditions somebody would naturally write for this behave differently there.
+//! The Lua 5.0 dialect the vendored 5.1 VM restores: the iterator-less generic-for (5.0's
+//! `OP_TFORPREP` folded into `OP_TFORLOOP` in `third_party/lua-src/lua-5.1.5/lvm.c`), long-string
+//! nesting and the constructor compat-semicolon.
 
 use super::common::script;
 
-/// **The construct works at all** — the whole point, in the shape the corpus uses.
-///
-/// `Ace.lua`'s is the canonical one and Ace is embedded across half the ecosystem:
-/// `for _, lang in self.langs do … end`, with no `pairs` and no iterator function.
 #[test]
 fn a_table_generator_iterates_like_lua_50() {
     let s = script();
@@ -31,7 +19,7 @@ fn a_table_generator_iterates_like_lua_50() {
         .unwrap();
     assert_eq!(seen, 6, "every pair must be visited exactly once");
 
-    // The array shape too, and the KEY must be the real key rather than a counter.
+    // The array shape: the key is the real key, not a counter.
     let keys: String = s
         .eval(
             r#"
@@ -45,12 +33,7 @@ fn a_table_generator_iterates_like_lua_50() {
     assert_eq!(keys, "1x2y");
 }
 
-/// **The condition is a bare type-tag test, so a table carrying `__call` STILL gets `next`.**
-///
-/// This is the discriminating case, and the reason the patch does not test "is not callable" or
-/// "has no `__call`" — both of those are reasonable readings and both diverge from the client here.
-/// The 1.12 handler makes **no** metatable access whatsoever (no `luaT_gettmbyobj`, no
-/// `tryfuncTM`), so the `__call` is never consulted and the table is iterated.
+/// The 1.12 handler tests only the type tag, never the metatable, so `__call` is not consulted.
 #[test]
 fn a_table_with_a_call_metamethod_is_still_iterated_not_called() {
     let s = script();
@@ -72,11 +55,7 @@ fn a_table_with_a_call_metamethod_is_still_iterated_not_called() {
     );
 }
 
-/// **The callee is the global `next`, read fresh at each loop entry — so an addon can replace it.**
-///
-/// Observable behaviour of the real client, not an accident: the lookup is a raw read of the
-/// thread's globals table, performed once per loop entry. An addon that assigns `next = myfn`
-/// changes every later generic-for in the session. Reproduced rather than improved on.
+/// The callee is a raw read of the global `next` at each loop entry, so an addon can replace it.
 #[test]
 fn the_substituted_generator_is_the_live_global_next() {
     let s = script();
@@ -100,14 +79,11 @@ fn the_substituted_generator_is_the_live_global_next() {
     );
 }
 
-/// **Only a table is substituted.** A function generator is untouched (the ordinary 5.1 path), and
-/// a non-table, non-function generator still raises on the FIRST ITERATION rather than at entry —
-/// the client's tag mismatch falls through to the normal call path.
+/// Any other generator takes the normal call path, so a number raises on the first iteration.
 #[test]
 fn only_a_table_is_substituted_and_other_types_still_raise() {
     let s = script();
 
-    // The ordinary iterator form is completely unaffected.
     let via_pairs: i64 = s
         .eval(
             r#"
@@ -120,7 +96,6 @@ fn only_a_table_is_substituted_and_other_types_still_raise() {
         .unwrap();
     assert_eq!(via_pairs, 3);
 
-    // A custom iterator function still drives its own loop.
     let custom: i64 = s
         .eval(
             r#"
@@ -139,7 +114,6 @@ fn only_a_table_is_substituted_and_other_types_still_raise() {
         "an explicit generator/state/control triple is untouched"
     );
 
-    // A number generator is not a table: it must still raise, and say so.
     let err = s
         .eval::<i64>("local n = 0 for k, v in 42 do n = n + 1 end return n")
         .unwrap_err()
@@ -150,8 +124,6 @@ fn only_a_table_is_substituted_and_other_types_still_raise() {
     );
 }
 
-/// **An empty table terminates immediately** rather than looping — `next(t, nil)` on an empty table
-/// returns nil, and the loop's own continue test is unchanged by the substitution.
 #[test]
 fn an_empty_table_generator_terminates() {
     let s = script();
@@ -161,9 +133,7 @@ fn an_empty_table_generator_terminates() {
     assert_eq!(n, 0);
 }
 
-/// **Nested and repeated loops each get their own substitution.** The patch rewrites the loop's own
-/// registers, so an inner loop must not disturb an outer one, and a loop entered twice must
-/// substitute twice (the registers are reloaded from the expression each entry).
+/// The patch rewrites the loop's own registers, reloaded from the expression at each entry.
 #[test]
 fn nested_and_repeated_loops_each_substitute_independently() {
     let s = script();
@@ -184,7 +154,6 @@ fn nested_and_repeated_loops_each_substitute_independently() {
     // Each of the 2 outer pairs runs the full inner loop (30) plus its own value.
     assert_eq!(out, 30 + 30 + 1 + 2);
 
-    // Entering the same loop a second time must work identically.
     let twice: i64 = s
         .eval(
             r#"
@@ -197,15 +166,8 @@ fn nested_and_repeated_loops_each_substitute_independently() {
     assert_eq!(twice, 4);
 }
 
-/// **5.0's long-string NESTING, restored** — the second dialect divergence in this file's family.
-///
-/// `[[ ... [[ ... ]] ... ]]` nests in Lua 5.0, which is what 1.12.1 ships. 5.1 kept the machinery
-/// (`llex.c` `read_long_string`'s `cont` counter, guarded by `LUA_COMPAT_LSTR == 2`) and put an
-/// advisory error in front of it — *"nesting of [[...]] is deprecated"* — which is a 5.1 opinion
-/// about a dialect we are not targeting. Two corpus addons stopped LOADING on it.
-///
-/// The fix is Lua's own documented switch, `LUA_COMPAT_LSTR` 1 -> 2 in our vendored `luaconf.h`,
-/// not a patch to the lexer: the code path was already there and already correct.
+/// `[[ ... [[ ... ]] ... ]]` nests in Lua 5.0, as 1.12.1 ships it; the vendored `luaconf.h` sets
+/// `LUA_COMPAT_LSTR` to 2, which enables 5.1's own nesting path in `read_long_string`.
 #[test]
 fn a_nested_long_string_parses_as_lua_50_does() {
     let s = crate::script::UiScript::new().unwrap();
@@ -214,27 +176,19 @@ fn a_nested_long_string_parses_as_lua_50_does() {
         .unwrap();
     assert_eq!(s.eval::<i64>("return NESTED_OK").unwrap(), 1);
 
-    // And a nested long STRING keeps its inner brackets, 5.0's own semantics: the outer runs to
-    // the matching close, so the inner `]]` does not terminate it.
+    // A nested long string keeps its inner brackets: the inner `]]` does not close it.
     let v = s
         .eval::<String>("return [[a [[b]] c]]")
         .expect("nested long string must parse");
     assert_eq!(v, "a [[b]] c");
 }
 
-/// **5.0's constructor compat-semicolon, restored** — the third dialect divergence (decision 1315).
-///
-/// Lua 5.0's `constructor()` opens its field loop with `testnext(ls, ';')  /* compatibility
-/// only */` — a Lua 4.0 leftover (4.0 separated a constructor's list part from its record part
-/// with `;`) that silently eats ONE extra `;` per separator position inside a table constructor.
-/// 5.1 deleted the line. AtlasLoot's `ButtonRegistry.lua` writes `Back_Title = AL["Factions"];;`
-/// twenty times; the real client loads it (director-verified on the live 1.12.1 client), stock
-/// 5.1 answered "unexpected symbol near ';'" and the addon's registry global never existed (B266).
+/// Lua 5.0's `constructor()` opens its field loop with `testnext(ls, ';')`, eating one extra `;`
+/// per separator position; 5.1 deleted the line, and AtlasLoot's `ButtonRegistry.lua` writes `;;`.
 #[test]
 fn a_double_semicolon_inside_a_constructor_parses_as_lua_50_does() {
     let s = script();
 
-    // The exact corpus shape: a record field, its `;` separator, and the compat extra.
     let out: String = s
         .eval(
             r#"
@@ -248,19 +202,15 @@ fn a_double_semicolon_inside_a_constructor_parses_as_lua_50_does() {
         .expect("the ButtonRegistry shape must parse");
     assert_eq!(out, "Factions");
 
-    // The compat skip runs at loop TOP, so a lone `;` before `}` — legal 5.0, an empty record
-    // part in 4.0 terms — is eaten the same way.
+    // The skip runs at the loop's top, so the lone `;` in `{;}` is eaten too.
     assert_eq!(s.eval::<i64>("local t = {;} return 1").unwrap(), 1);
 
-    // List context too: the separator may be `;` and the extra one is still absorbed.
     let n: i64 = s.eval("local t = { 1;; 2 } return t[1] + t[2]").unwrap();
     assert_eq!(n, 3);
 }
 
-/// **The restoration is exactly one semicolon wide, and constructor-only.** Both halves of the
-/// boundary are the client's: 5.0 eats ONE extra `;` per position (a third dies in `listfield`),
-/// and statement-level `;;` is rejected by 5.0 and 5.1 alike — the half wow-5875-re byte-verified
-/// in the client's `luaL_loadbuffer` first (`system/ui/scratch/lua-dialect.md`).
+/// A third `;` dies in `listfield`, and statement-level `;;` is rejected by the client's own parser
+/// too (`luaL_loadbuffer`, `chunk 0x6fcc90`).
 #[test]
 fn the_compat_semicolon_is_one_wide_and_statement_level_stays_rejected() {
     let s = script();
diff --git a/crates/benilla-ui/src/script/tests/gm_ticket.rs b/crates/benilla-ui/src/script/tests/gm_ticket.rs
index 6a3d7277..d2a4f909 100644
--- a/crates/benilla-ui/src/script/tests/gm_ticket.rs
+++ b/crates/benilla-ui/src/script/tests/gm_ticket.rs
@@ -1,9 +1,4 @@
-//! The Help window's seven engine globals ([`crate::script::gm_ticket`], decision 1673).
-//!
-//! Two claims carry the whole feature and each has a test named after it: the category list is
-//! **flat pairs consumed by Lua 5.0 varargs** (that is what `HelpFrameGM_UpdateCategories` reads),
-//! and the four payload-free verbs **count** rather than latch (that is what keeps the window's
-//! 10-minute ticket poll alive).
+//! The Help window's seven engine globals ([`crate::script::gm_ticket`]).
 
 use super::common::script;
 use crate::script::{GmTicketIntent, GmTicketWrite, UiScript};
@@ -19,9 +14,7 @@ fn with_categories() -> UiScript {
     s
 }
 
-/// **`GetGMTicketCategories()` returns a FLAT (id, name) vararg list**, which the shipped window
-/// walks as `arg[i]` / `arg[i+1]` pairs with `arg.n` — the Lua 5.0 convention. A table here, or a
-/// list of names alone, would leave every category button unlabelled or unclickable.
+/// The stock window walks it as `arg[i]`, `arg[i+1]` pairs up to `arg.n`.
 #[test]
 fn the_categories_come_back_as_a_flat_id_name_vararg_list() {
     let s = with_categories();
@@ -37,17 +30,14 @@ fn the_categories_come_back_as_a_flat_id_name_vararg_list() {
         )
         .unwrap();
     assert_eq!((id1, name1.as_str()), (1, "Stuck"));
-    // The THIRD pair is at 5/6 — pairs, not a parallel pair of lists.
     assert_eq!((id3, name3.as_str()), (3, "Guild"));
 }
 
-/// **The ids are the DBC's, not indices.** `HelpFrameGM_UpdateCategories` stores `arg[index]` as
-/// both `button.key` (an index into `HELPFRAME_FRAMES`) and `button.ticketType` (what goes on the
-/// wire), so a renumbered list would misfile every ticket under the wrong heading.
+/// `HelpFrameGM_UpdateCategories` stores the id as `button.key` and as the wire `ticketType`.
 #[test]
 fn the_ids_are_the_dbc_ids_not_list_positions() {
     let mut s = script();
-    // A deliberately gappy, unsorted catalog — nothing may re-index it.
+    // Gappy and unsorted on purpose.
     s.set_gm_ticket_categories(vec![(10, "Character".into()), (4, "Item".into())]);
     let (a, b): (i64, i64) = s
         .eval("local f = function(...) return arg[1], arg[3] end return f(GetGMTicketCategories())")
@@ -55,8 +45,7 @@ fn the_ids_are_the_dbc_ids_not_list_positions() {
     assert_eq!((a, b), (10, 4), "ids and order pass through untouched");
 }
 
-/// No catalog is not an error: the window paints no category rows and cannot raise. This is the
-/// bare-XML harness, and a run with no client data.
+/// The bare-XML harness and a run with no client data have no catalog.
 #[test]
 fn an_absent_catalog_returns_nothing_rather_than_erroring() {
     let s = script();
@@ -66,9 +55,7 @@ fn an_absent_catalog_returns_nothing_rather_than_erroring() {
     assert_eq!(n, 0);
 }
 
-/// **The verbs queue, they do not latch.** Two `GetGMTicket()` calls are two packets, because the
-/// ticket toast re-polls every 10 minutes from `TicketStatus_OnUpdate` — a latch would collapse the
-/// second poll into the first and the window would look hung.
+/// Two `GetGMTicket()` calls are two packets: `TicketStatus_OnUpdate` re-polls every 10 minutes.
 #[test]
 fn the_payload_free_verbs_queue_rather_than_latch() {
     let mut s = script();
@@ -84,15 +71,11 @@ fn the_payload_free_verbs_queue_rather_than_latch() {
         ]
     );
     assert_eq!(s.take_stuck_casts(), 3, "Stuck is not a ticket verb");
-    // Drained means drained — the next frame must not re-send.
     assert!(s.take_gm_ticket_intents().is_empty());
     assert_eq!(s.take_stuck_casts(), 0);
 }
 
-/// **Call order is wire order.** A chunk that abandons and then re-asks must reach the server in
-/// that order — reversed, the get answers with the state *before* the delete and the window is
-/// told it still has the ticket it just abandoned. Per-verb drains cannot express this, which is
-/// why there is one queue (decision 1673).
+/// Call order is wire order: reversed, the get would answer with the ticket just deleted.
 #[test]
 fn the_queue_preserves_call_order_across_different_verbs() {
     let mut s = script();
@@ -103,15 +86,13 @@ fn the_queue_preserves_call_order_across_different_verbs() {
         "delete first, exactly as Lua called them"
     );
 
-    // And the other way round, so the test cannot pass on a fixed per-verb ordering that merely
-    // happens to match one of the two cases.
+    // The other way round, so a fixed per-verb order cannot pass.
     s.run("GetGMTicket() DeleteGMTicket()").unwrap();
     assert_eq!(
         s.take_gm_ticket_intents(),
         vec![GmTicketIntent::Ask, GmTicketIntent::Delete]
     );
 
-    // Writes interleave with the bare verbs on the same queue.
     s.run("NewGMTicket(1, \"a\") GetGMTicket()").unwrap();
     assert!(matches!(
         s.take_gm_ticket_intents().as_slice(),
@@ -119,9 +100,7 @@ fn the_queue_preserves_call_order_across_different_verbs() {
     ));
 }
 
-/// **The window's verb survives to the app.** `NewGMTicket` and `UpdateGMTicket` share a signature
-/// but not an opcode, and the shipped window picks between them from its own `hasTicket` flag —
-/// so the choice is carried, never re-derived from what the client believes.
+/// Same signature, different opcodes; the stock window picks one from its own `hasTicket` flag.
 #[test]
 fn new_and_update_are_distinguishable_and_keep_their_order() {
     let mut s = script();
@@ -144,10 +123,9 @@ fn new_and_update_are_distinguishable_and_keep_their_order() {
     );
 }
 
-/// The Era arity is `(number, string)` — the reference's own usage string is
-/// `Usage: UpdateGMTicket(type, text)`. An empty ticket is the *window's* refusal to make, not
-/// ours: the binding queues whatever it is handed, and the engine's own emptiness check sits
-/// upstream of the send.
+/// The reference's usage string is `Usage: UpdateGMTicket(type, text)`. The binding queues any
+/// text; the reference refuses an empty one before the send (`ERR_TICKET_NO_TEXT`, `0x5ef808`,
+/// `0x5efae7`).
 #[test]
 fn an_empty_ticket_body_is_queued_not_swallowed() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/handler_prof.rs b/crates/benilla-ui/src/script/tests/handler_prof.rs
index 171daf99..3e741447 100644
--- a/crates/benilla-ui/src/script/tests/handler_prof.rs
+++ b/crates/benilla-ui/src/script/tests/handler_prof.rs
@@ -1,22 +1,16 @@
-//! Per-handler cost attribution (decision 1395) — the instrument that answers *which* handler.
-//!
-//! These assert on **names, call counts, and the self/total relation**, never on a duration
-//! (0735): "this handler cost 2 ms" is not a fact a test can own. The one relational assertion
-//! (`self < total` under nesting) carries its own exact control — the same shape with nothing
-//! nested inside it must report `self == total` to the last nanosecond, which is what proves the
-//! difference came from the subtraction rather than from the clock.
+//! Per-handler cost attribution. The tests assert names, call counts and the self/total relation,
+//! never a duration; `self == total` with nothing nested is the control for `self < total`.
 
 use super::common::script;
 use crate::script::{HandlerRow, ScriptValue, UiScript};
 
-/// The row for `frame:script`, or `None`.
 fn row(rows: &[HandlerRow], frame: &str, script: &str) -> Option<HandlerRow> {
     rows.iter()
         .find(|r| r.frame == frame && r.script == script)
         .cloned()
 }
 
-/// Recording, with no periodic report — the tests read the window directly.
+/// Recording, with no periodic report: the tests read the window directly.
 fn armed() -> UiScript {
     let s = script();
     s.profile_handlers(true, 0.0);
@@ -69,8 +63,7 @@ fn every_fired_handler_is_attributed_to_its_own_frame_and_script() {
 
 #[test]
 fn a_handler_with_nothing_nested_inside_it_is_all_self_time() {
-    // The control for the nesting test below: with no nested fire, the subtraction is by zero and
-    // the two numbers must be *identical*, not merely close.
+    // The control for the nesting test: nothing nested subtracts zero, so the two are identical.
     let mut s = armed();
     s.run(
         r#"
@@ -122,14 +115,13 @@ fn a_handler_that_fires_another_is_not_charged_for_its_child() {
         outer.self_us < outer.total_us,
         "the child's cost must come off the parent's self time: {outer:#?}"
     );
-    // And the nested row must be the one holding it — the whole point is naming Inner, not Outer.
     assert!(
         inner.self_us > 0.0,
         "the child's own cost lands on the child: {inner:#?}"
     );
 
-    // A second tick must behave like the first: a leaked stack level would start charging Outer's
-    // child time to a phantom parent and the relation above would quietly stop holding.
+    // A second tick behaves like the first: a leaked stack level would charge the child's time to
+    // a phantom parent.
     s.tick(0.016);
     let rows = s.handler_profile();
     let outer = row(&rows, "Outer", "OnUpdate").expect("outer");
@@ -140,8 +132,7 @@ fn a_handler_that_fires_another_is_not_charged_for_its_child() {
 
 #[test]
 fn an_anonymous_frames_handler_is_labelled_by_where_it_was_written() {
-    // `CreateFrame("Frame")` + OnUpdate with no name is the addon timer idiom, so this is the
-    // common case, not the exotic one — and `#4127` would be an unusable row.
+    // An unnamed frame's OnUpdate is the addon timer idiom, and `#4127` would be a useless label.
     let mut s = armed();
     s.run(
         r#"
@@ -164,9 +155,8 @@ fn an_anonymous_frames_handler_is_labelled_by_where_it_was_written() {
 
 #[test]
 fn an_unarmed_vm_records_nothing() {
-    // The off-state is the shipped state, so it gets a guard of its own: a VM that was never armed
-    // must report an empty profile even while another VM in this process is recording (the gate is
-    // process-wide, the state is per-VM — see `handler_prof::ARMED`).
+    // An unarmed VM records nothing while another records: the gate (`handler_prof::ARMED`) is
+    // process-wide, the state per VM.
     let _recording = armed();
     let mut s = script();
     s.run(
diff --git a/crates/benilla-ui/src/script/tests/input.rs b/crates/benilla-ui/src/script/tests/input.rs
index eda3e22d..6f94e00a 100644
--- a/crates/benilla-ui/src/script/tests/input.rs
+++ b/crates/benilla-ui/src/script/tests/input.rs
@@ -1,4 +1,4 @@
-//! Input / hit-testing (decision 0068; spec-faithful, not byte-pinned).
+//! Mouse input: hit order, hover, clicks, double clicks and the release capture.
 
 use super::common::script;
 
@@ -38,11 +38,8 @@ fn enable_mouse_gates_hit_testing() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The hit sweep's key, all three terms: strata, then level, then — at a tie — the **earlier-linked**
-/// frame, NOT the later one that draws on top (decision 1816; wow-re
-/// `ui/scratch/hittest-no-fallthrough-law.md` §4, `0x764aa0`'s strict `ja` appending equal keys and
-/// `0x7660d0` sweeping from index 0). This test used to assert the opposite at the tie and was named
-/// for it — draw order and hit order agree on strata and level and disagree on exactly this.
+/// At a strata and level tie the earlier-linked frame takes the hit, though the later one draws on
+/// top: `0x764aa0` appends equal keys after (strict `ja`) and `0x7660d0` sweeps from index 0.
 #[test]
 fn hit_order_is_strata_then_level_then_the_earlier_linked_frame() {
     let mut s = script();
@@ -61,24 +58,21 @@ fn hit_order_is_strata_then_level_then_the_earlier_linked_frame() {
     .unwrap();
     s.resolve();
 
-    // Same strata/level: A was linked FIRST, so the sweep reaches it first and it captures —
-    // even though B, linked later, draws on top of it.
+    // Same strata and level: A, linked first, captures though B draws on top.
     s.mouse_move(400.0, 300.0);
     assert_eq!(s.eval::<String>("return who").unwrap(), "A");
 
     // Move off everything to clear the mouseover (fires OnLeave, resets focus) before re-testing.
     s.mouse_move(-10.0, -10.0);
 
-    // Raise A above B by strata (no rect change ⇒ no re-resolve needed): strata outranks the tie,
-    // and A keeps the point for the stronger reason.
+    // Strata outranks the tie; no rect changes, so no re-resolve.
     s.run("A:SetFrameStrata('DIALOG')").unwrap();
     s.mouse_move(400.0, 300.0);
     assert_eq!(s.eval::<String>("return who").unwrap(), "A");
 
     s.mouse_move(-10.0, -10.0);
 
-    // Put B in the same (DIALOG) strata but a higher frame level: level outranks link order, so
-    // B takes it back — the tie rule only decides frames that are equal on both.
+    // Same strata, higher level: level outranks link order, so B captures.
 
     s.run("B:SetFrameStrata('DIALOG'); B:SetFrameLevel(10)")
         .unwrap();
@@ -137,13 +131,11 @@ fn onclick_fires_on_press_release_same_frame_not_when_release_lands_elsewhere()
     .unwrap();
     s.resolve();
 
-    // Press + release both on A ⇒ OnClick on A (button arg == "LeftButton").
     s.mouse_button(200.0, 300.0, "LeftButton", true);
     s.mouse_button(200.0, 300.0, "LeftButton", false);
     assert_eq!(s.eval::<i64>("return clicks_a").unwrap(), 1);
     assert_eq!(s.eval::<String>("return click_btn").unwrap(), "LeftButton");
 
-    // Press on A, release on B ⇒ no OnClick on either frame.
     s.mouse_button(200.0, 300.0, "LeftButton", true);
     s.mouse_button(600.0, 300.0, "LeftButton", false);
     assert_eq!(
@@ -225,8 +217,8 @@ fn mouse_wheel_passes_delta_to_the_captured_frame() {
 fn hit_rect_insets_shrink_the_mouse_rect_only() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
-    // A 100×100 frame at the origin with the micro-button shape: an 18-unit dead header at the
-    // top, and 5 off each other side.
+    // A 100×100 frame at the origin; the top inset is the micro buttons' 18
+    // (`MainMenuBarMicroButtons.xml:9`), with 5 off each other side.
     s.run(
         r#"
         entered = false
@@ -241,24 +233,20 @@ fn hit_rect_insets_shrink_the_mouse_rect_only() {
     .unwrap();
     s.resolve();
 
-    // Geometry is untouched — insets move the MOUSE rect, never the frame.
     assert_eq!(s.eval::<f64>("return A:GetHeight()").unwrap(), 100.0);
     assert_eq!(s.eval::<f64>("return A:GetTop()").unwrap(), 100.0);
 
-    // Inside the frame but inside the dead header ⇒ no capture (the case the ref's top=18 buys:
-    // the empty band above a micro button's art must not eat the click).
     assert!(
         s.hit_test(50.0, 90.0).is_none(),
         "a point in the inset header is outside the hit rect"
     );
     assert!(s.mouse_move(50.0, 90.0).is_none());
     assert!(!s.eval::<bool>("return entered").unwrap());
-    // …and each of the other three insets bites too.
     assert!(s.hit_test(2.0, 50.0).is_none(), "left inset");
     assert!(s.hit_test(98.0, 50.0).is_none(), "right inset");
     assert!(s.hit_test(50.0, 2.0).is_none(), "bottom inset");
 
-    // Just below the header, still inside the shrunken rect ⇒ captures.
+    // Just below the header, inside the shrunken rect: captures.
     assert!(s.hit_test(50.0, 80.0).is_some());
     assert!(s.mouse_move(50.0, 80.0).is_some());
     assert!(s.eval::<bool>("return entered").unwrap());
@@ -277,13 +265,6 @@ fn hit_rect_insets_default_to_zero() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `EnableMouseWheel`/`IsMouseWheelEnabled` round-trip, and the two kinds born wheel-enabled
-/// (decision 1198).
-///
-/// The flag is real and settable; **the dispatch is deliberately not gated on it yet** — see
-/// `object::frame_state`'s note for the 44 shipped `OnMouseWheel` sites that declare no
-/// `enableMouseWheel` and the concrete condition for flipping it. This test pins the flag's own
-/// behaviour so that flip is a one-line change with a test already standing behind it.
 #[test]
 fn the_mouse_wheel_flag_round_trips_and_the_scrolling_kinds_are_born_enabled() {
     let s = script();
@@ -296,12 +277,11 @@ fn the_mouse_wheel_flag_round_trips_and_the_scrolling_kinds_are_born_enabled() {
     )
     .unwrap();
 
-    // A plain frame is born wheel-deaf, like WoW's own default.
+    // A plain frame is born wheel-disabled, as in the reference; the two scrolling kinds' own
+    // constructors enable it.
     assert!(!s
         .eval::<bool>("return Plain:IsMouseWheelEnabled()")
         .unwrap());
-    // ...and the two kinds whose ctor takes the wheel are born enabled, the same by-construction
-    // argument `mouse_enabled` already makes for a Button.
     assert!(s
         .eval::<bool>("return Scroll:IsMouseWheelEnabled()")
         .unwrap());
@@ -323,14 +303,8 @@ fn the_mouse_wheel_flag_round_trips_and_the_scrolling_kinds_are_born_enabled() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A closed-vocabulary attribute survives stray whitespace (decision 1204).
-///
-/// The corpus case: `zBar.xml:146` — a shipped, working 1.12 addon — declares
-/// `frameStrata="BACKGROUND "` with a trailing space. The real client took it; we refused, and the
-/// refusal took the frame's whole `<Frames>` subtree with it, so the addon never loaded at all.
-///
-/// The three parsers are covered together because the next one to meet a stray space should not
-/// need its own bug report.
+/// The reference takes a closed-vocabulary value with stray whitespace: the zBar addon ships
+/// `frameStrata="BACKGROUND "` (`zBar.xml:146`). Frame kind, strata and draw layer all trim.
 #[test]
 fn an_enum_attribute_tolerates_the_whitespace_a_real_addon_ships() {
     let s = script();
@@ -348,25 +322,19 @@ fn an_enum_attribute_tolerates_the_whitespace_a_real_addon_ships() {
         "BACKGROUND",
         "the frame took the strata, and reports it in the canonical spelling"
     );
-    // ...and the padded frame KIND resolved too — an unknown kind raises from CreateFrame, so
-    // reaching this line at all is the assertion.
+    // The padded kind resolved: an unknown kind would have raised from `CreateFrame`.
     assert!(s.eval::<bool>("return PaddedKind ~= nil").unwrap());
     assert!(s.eval::<bool>("return PaddedTex ~= nil").unwrap());
 }
 
-// ── OnDoubleClick — the corpus's biggest script gap (250 sites / 85 addons) ───────────────────
+// ── OnDoubleClick ──
 //
-// Every rule below is byte-verified, from the §5 cross-check this work dispatched into wow-re
-// (`system/ui/scratch/button-doubleclick-law.md`): the interval is a hardcoded **300 ms**
-// (`0x77937b cmp ecx, 0x12c`), the fire site is the mouse-**UP** dispatcher `0x7792d0` alone, the
-// double leg **replaces** the second `OnClick` (`0x77939d jmp` past `call [edx+0x94]`), a completed
-// double **zeroes** the stamp so clicks pair up, the detector is armed only when the frame carries
-// an `OnDoubleClick` script (`[+0x4d4] != 0`), and it carries **no button identity** — what
-// normally confines it to the left button is `RegisterForClicks`, not the detector.
+// The interval is a fixed 300 ms (`0x77937b`, `cmp ecx, 0x12c`) and the only fire site is the
+// mouse-up dispatcher `0x7792d0`. The double replaces the second `OnClick` (`0x77939d` jumps past
+// it), a completed double zeroes the stamp so clicks pair up, the detector arms only when the frame
+// has an `OnDoubleClick` script (`[+0x4d4] != 0`), and it keys on no button: `RegisterForClicks`
+// is what confines it to the left button.
 
-/// Two fast clicks fire `OnDoubleClick(self, button)` — and the second `OnClick` does **not** fire,
-/// because the two legs are exclusive. (This was the interim implementation's mistake: it fired
-/// both, on the press edge, at 500 ms. All three were corrected at the bytes.)
 #[test]
 fn a_second_fast_click_fires_on_double_click_instead_of_the_second_on_click() {
     let mut s = script();
@@ -383,7 +351,6 @@ fn a_second_fast_click_fires_on_double_click_instead_of_the_second_on_click() {
     .unwrap();
     s.resolve();
 
-    // Click one. Note the press alone does nothing: the fire site is the mouse-UP dispatcher.
     s.mouse_button(50.0, 50.0, "LeftButton", true);
     assert_eq!(
         s.eval::<i64>("return clicks").unwrap(),
@@ -420,10 +387,8 @@ fn a_second_fast_click_fires_on_double_click_instead_of_the_second_on_click() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The gate that keeps rapid clicking from breaking every button in the UI.** The binary's chain
-/// tests `[+0x4d4] != 0`, so a widget with no `OnDoubleClick` script takes the single leg every
-/// time. Without that test, the exclusivity above would silently swallow every second `OnClick` on
-/// every frame in the game.
+/// The detector tests `[+0x4d4] != 0`, so a widget with no `OnDoubleClick` script always takes
+/// the single-click leg.
 #[test]
 fn a_frame_with_no_double_click_handler_keeps_every_rapid_on_click() {
     let mut s = script();
@@ -450,9 +415,6 @@ fn a_frame_with_no_double_click_handler_keeps_every_rapid_on_click() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The boundary: too slow, a different frame, and the PAIRING rule (a completed double zeroes the
-/// stamp, so four rapid clicks read Click · Double · Click · Double — there is no triple-click and
-/// no run of doubles).
 #[test]
 fn the_double_click_boundary_is_time_and_frame_and_clicks_pair_up() {
     let mut s = script();
@@ -477,14 +439,14 @@ fn the_double_click_boundary_is_time_and_frame_and_clicks_pair_up() {
         s.mouse_button(x, 50.0, "LeftButton", false);
     };
 
-    // (1) TOO SLOW — 0.35 s > 300 ms, so the second click is a fresh first half.
+    // (1) Too slow: 0.35 s is past the 300 ms, so the second click starts afresh.
     click(&mut s, 50.0);
     s.tick(0.35);
     click(&mut s, 50.0);
     assert_eq!(s.eval::<i64>("return doubles").unwrap(), 0);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
 
-    // (2) A DIFFERENT FRAME — fast, but the timestamp lives on the WIDGET, so B has its own.
+    // (2) A different frame: the stamp lives on the widget, so B has its own.
     s.run("clicks, doubles = 0, 0").unwrap();
     s.tick(1.0);
     click(&mut s, 50.0);
@@ -492,7 +454,7 @@ fn the_double_click_boundary_is_time_and_frame_and_clicks_pair_up() {
     assert_eq!(s.eval::<i64>("return doubles").unwrap(), 0);
     assert_eq!(s.eval::<i64>("return clicks").unwrap(), 2);
 
-    // (3) PAIRING — four rapid clicks on one frame are Click · Double · Click · Double.
+    // (3) Pairing: four rapid clicks on one frame are click, double, click, double.
     s.run("clicks, doubles = 0, 0").unwrap();
     s.tick(1.0);
     for _ in 0..4 {
@@ -509,11 +471,8 @@ fn the_double_click_boundary_is_time_and_frame_and_clicks_pair_up() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The detector carries no button identity** — the surprising half of the law, and the one an
-/// implementation keyed by mouse button would get wrong. `[CButton+0x334]` is a bare timestamp, so
-/// a widget registered for two `…Up` types completes a double click across them, with `arg1` = the
-/// button of the SECOND click. A stock button never sees this only because `RegisterForClicks`
-/// defaults to `{"LeftButtonUp"}`.
+/// `[CButton+0x334]` is a bare timestamp, so a button registered for two `…Up` types completes a
+/// double click across them, and `arg1` is the second click's button.
 #[test]
 fn a_multi_registered_button_pairs_a_left_click_with_a_right_one() {
     let mut s = script();
@@ -543,10 +502,9 @@ fn a_multi_registered_button_pairs_a_left_click_with_a_right_one() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **Nothing clears a half-finished double click** — not hide, not disable, not the cursor leaving
-/// the window. `[+0x334]` has three writers image-wide and none of them is any of those, so this
-/// pins the *absence* of the tidy-up that looks like it belongs in
-/// [`crate::script::UiScript::pointer_left_window`].
+/// Nothing clears a half-finished double click, not hide, disable or the cursor leaving the
+/// window: none of `[+0x334]`'s three writers is one of those, so
+/// [`crate::script::UiScript::pointer_left_window`] must not reset it.
 #[test]
 fn a_half_finished_double_click_survives_the_cursor_leaving_the_window() {
     let mut s = script();
@@ -574,9 +532,7 @@ fn a_half_finished_double_click_survives_the_cursor_leaving_the_window() {
     );
 }
 
-/// The load-bearing regression guard for the whole job: accepting `OnDoubleClick` in
-/// `SCRIPT_KINDS` without wiring the detector would make this test's `SetScript` succeed and its
-/// handler never run — the silent-capability trap. Asserting the *fire* is what makes the row real.
+/// A name in `SCRIPT_KINDS` must have something that fires it, so this asserts the fire.
 #[test]
 fn set_script_on_double_click_is_accepted_because_something_fires_it() {
     let mut s = script();
@@ -603,30 +559,16 @@ fn set_script_on_double_click_is_accepted_because_something_fires_it() {
     assert!(s.eval::<bool>("return ran").unwrap(), "…and it FIRED");
 }
 
-/// The script names that deliberately still raise, and why each is out (the reasons live at
-/// `object::events_regions::set_script`). This is the other half of the rule "a name is accepted
-/// only once something fires it": a future widening has to delete a line here, which is exactly
-/// the moment to check something fires it.
+/// Script names nothing fires still raise; a name leaves this list only when something fires it.
 #[test]
 fn the_unfired_script_kinds_still_raise_rather_than_silently_accepting() {
     let s = script();
     s.run(r#"Raiser = CreateFrame("EditBox", "RaiserBox")"#)
         .unwrap();
     for name in [
-        // `OnKeyDown`/`OnKeyUp`/`OnChar` are NOT in this list any more: decision 1319 built the
-        // delivery walk, so they are fired and therefore accepted — the rule this test enforces,
-        // applied in the other direction. Their law lives in `script::tests::keyboard`.
-        //
-        // `OnCursorChanged` left this list with decision 2141: the tick's caret flush fires it
-        // (`editbox::drain_cursor_changed`), which is the rule applied in the other direction
-        // again — its law lives in `script::editbox::tests`.
-        //
-        // 2.0's secure-frame system — no such slot exists in any 1.12 resolver.
+        // A 2.0 secure-frame slot; no 1.12 resolver has it.
         "OnAttributeChanged",
-        // Real 1.12 slots we do not fire, and zero corpus call sites. (`OnUpdateModel` and
-        // `OnAnimFinished` left this list with decision 2007: the tick's model pass fires
-        // them — `script::tests::model_clock`. `OnHorizontalScroll` left it with the ScrollFrame's
-        // horizontal offset pair, which fires it — `script::tests::scrollframe`.)
+        // Real 1.12 slots that benilla does not fire.
         "OnHyperlinkEnter",
         "OnMessageScrollChanged",
         "OnInputLanguageChanged",
@@ -641,10 +583,8 @@ fn the_unfired_script_kinds_still_raise_rather_than_silently_accepting() {
     }
 }
 
-/// The hover-hide law (wow-re `ui/scratch/hover-hide-and-tooltip-owner-law.md`, §5-arbitrated):
-/// hiding the hovered frame fires its `OnLeave` synchronously, BEFORE its own `OnHide`
-/// (`0x764ba0`'s kind-2 tail runs mid-hide, the leave at `0x764cce`; OnHide fires at the hide
-/// body's tail) — and an ancestor's `Hide()` reaches the hovered descendant through the cascade.
+/// Hiding the hovered frame fires its `OnLeave` inside the hide, before its `OnHide` (`0x764ba0`'s
+/// removal tail, the leave at `0x764cce`), and an ancestor's `Hide()` reaches it by the cascade.
 #[test]
 fn hiding_the_hovered_frame_fires_its_onleave_before_onhide() {
     let mut s = script();
@@ -663,7 +603,7 @@ fn hiding_the_hovered_frame_fires_its_onleave_before_onhide() {
     .unwrap();
     s.resolve();
     s.mouse_move(150.0, 150.0); // hover the slot
-    s.run("Win:Hide()").unwrap(); // the ANCESTOR hides — the cascade reaches the slot
+    s.run("Win:Hide()").unwrap(); // the ancestor hides; the cascade reaches the slot
     assert_eq!(
         s.eval::<String>("return table.concat(log, ',')").unwrap(),
         "leave,hide",
@@ -672,9 +612,8 @@ fn hiding_the_hovered_frame_fires_its_onleave_before_onhide() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The removal tail's own DISABLED case: `0x764cce` dispatches `[edx+0x50]` **virtually**, so a
-/// Button lands in `0x7794e0` and the guard swallows the leave there too. The `OnHide` half is the
-/// control — that one is not the hover notify and fires either way.
+/// `0x764cce` dispatches the leave virtually (`[edx+0x50]`), so a disabled Button's own guard
+/// (`0x7794e0`) swallows it; `OnHide` is not the hover notify and fires either way.
 #[test]
 fn hiding_a_hovered_disabled_button_fires_onhide_but_no_onleave() {
     let mut s = script();
@@ -701,8 +640,7 @@ fn hiding_a_hovered_disabled_button_fires_onhide_but_no_onleave() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The negative: hiding a frame the cursor is NOT over fires no OnLeave (the reference's removal
-/// tail acts only when the removed frame IS the cached hover).
+/// The reference's removal tail acts only when the removed frame is the cached hover.
 #[test]
 fn hiding_an_unhovered_frame_fires_no_onleave() {
     let mut s = script();
@@ -723,10 +661,9 @@ fn hiding_an_unhovered_frame_fires_no_onleave() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The re-pick (`[root+0x1100]` + the pump tail `0x7660d0` on the SAVED event): after the hovered
-/// frame hides, the next tick re-hovers whatever is now topmost at the unchanged cursor — OnEnter
-/// with no physical mouse move. And the symmetric insert law: a frame SHOWN under a stationary
-/// cursor gets hovered on the next tick too (`0x764b8d`).
+/// After the hovered frame hides, the next tick re-hovers what is topmost at the unmoved cursor
+/// (`[root+0x1100]`, the pump tail `0x7660d0` on the saved event); a frame shown under the cursor
+/// is hovered the same way (`0x764b8d`).
 #[test]
 fn the_repick_re_hovers_without_a_mouse_move() {
     let mut s = script();
@@ -749,14 +686,13 @@ fn the_repick_re_hovers_without_a_mouse_move() {
     s.resolve();
     s.mouse_move(150.0, 150.0); // hovers Over (topmost)
     s.run("Over:Hide()").unwrap();
-    s.tick(0.016); // the pump's re-pick — cursor has not moved
+    s.tick(0.016); // the pump's re-pick; the cursor has not moved
     assert_eq!(
         s.eval::<String>("return table.concat(entered, ',')")
             .unwrap(),
         "over,under",
         "the frame beneath is entered on the next tick with no mouse move"
     );
-    // The insert half: re-showing the top frame under the stationary cursor re-hovers it.
     s.run("Over:Show()").unwrap();
     s.tick(0.016);
     assert_eq!(
@@ -768,9 +704,7 @@ fn the_repick_re_hovers_without_a_mouse_move() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The mouse-UP dispatch law (decision 1599) — byte-verified, wow-re `mouseup-dispatch-law.md`
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The mouse-up dispatch (`0x766420`) ──
 
 /// Two side-by-side frames, each recording every `OnMouseDown`/`OnMouseUp` it gets.
 fn two_frames() -> crate::script::UiScript {
@@ -799,14 +733,9 @@ fn log_of(s: &mut crate::script::UiScript) -> String {
     s.eval::<String>("return table.concat(log, ' ')").unwrap()
 }
 
-/// **The release goes to the frame that took the press, wherever the cursor has got to.** The
-/// client's `0x766420` snapshots `[mgr+0x80]` — the capture — at entry (`0x76642b`) and dispatches
-/// through it alone; `[mgr+0x7c]`, the hover frame, is never read in the whole function. So B, which
-/// the cursor is over at release, gets nothing on that edge.
-///
-/// The concrete thing this buys: a chat window's 16×16 resize grip is pulled out from under the
-/// cursor the instant the size clamps at a resize bound, and its `OnMouseUp → FCF_StopResize` has
-/// to run anyway or the sizing drag is held for the rest of the session.
+/// `0x766420` reads the capture `[mgr+0x80]` at entry (`0x76642b`) and never the hover
+/// `[mgr+0x7c]`, so the release reaches the pressed frame wherever the cursor is; a chat resize
+/// grip's `FCF_StopResize` relies on it (`FloatingChatFrame.xml:292`).
 #[test]
 fn the_release_goes_to_the_frame_that_took_the_press() {
     let mut s = two_frames();
@@ -820,13 +749,8 @@ fn the_release_goes_to_the_frame_that_took_the_press() {
     );
 }
 
-/// **A press that captured nothing fires nothing on release** — and this is the half that is easy
-/// to get wrong, because the DOWN handler *does* have a hover fallback (`root+0x80` else
-/// `root+0x7c`) and the UP handler does **not** share it: `0x766498 test ebx,ebx / je 0x7664cd`
-/// returns with no virtual call at all.
-///
-/// This shipped briefly as `captured.or(hit)` — a press over open space then delivered its release
-/// to whatever the cursor had wandered onto, which is a frame that never saw the press.
+/// The down handler falls back to the hover (`root+0x80` else `root+0x7c`), the up handler does
+/// not: with no capture, `0x766498` jumps to `0x7664cd` and dispatches nothing.
 #[test]
 fn a_press_that_captured_nothing_delivers_no_release() {
     let mut s = two_frames();
@@ -840,7 +764,6 @@ fn a_press_that_captured_nothing_delivers_no_release() {
     );
 }
 
-/// The ordinary case still behaves: press and release on the same frame is down-then-up on it.
 #[test]
 fn a_press_and_release_on_one_frame_is_unchanged() {
     let mut s = two_frames();
@@ -849,15 +772,13 @@ fn a_press_and_release_on_one_frame_is_unchanged() {
     assert_eq!(log_of(&mut s), "A:down A:up");
 }
 
-/// The capture is **per button**, so a right-button release cannot be answered by a left-button
-/// press's capture — `Model::mouse_down_on` is keyed by button name, which is what makes this fall
-/// out rather than needing its own arm.
+/// `Model::mouse_down_on` is keyed by button name, so the capture is per button.
 #[test]
 fn the_capture_is_per_button() {
     let mut s = two_frames();
-    s.mouse_button(200.0, 300.0, "LeftButton", true); // A holds the LEFT button
+    s.mouse_button(200.0, 300.0, "LeftButton", true); // A holds the left button
     s.mouse_move(500.0, 300.0);
-    s.mouse_button(500.0, 300.0, "RightButton", false); // a RIGHT release, never pressed
+    s.mouse_button(500.0, 300.0, "RightButton", false); // a right release, never pressed
     assert_eq!(
         log_of(&mut s),
         "A:down",
@@ -865,16 +786,9 @@ fn the_capture_is_per_button() {
     );
 }
 
-/// **A DISABLED Button runs neither `<OnEnter>` nor `<OnLeave>`** — `CSimpleButton::OnEnter
-/// 0x779490` / `OnLeave 0x7794e0` open `mov eax,[esi+0x328]; test eax,eax; je`, branching past the
-/// base notify that owns both script slots (wow-re `scratch/button-state-edge-set.md` §3.1). It
-/// still TAKES the hover, because the walk reassigns `[root+0x7c]` before it fires the notify.
-///
-/// The customer is every 1.12 addon that wrote `if this:IsEnabled() then` at the top of an
-/// `<OnEnter>` and expected it to be false: `IsEnabled()` is the NUMBER `1`/`0`, always truthy, so
-/// the body runs unless the ENGINE holds it back. AtlasLoot's four QuickLook buttons are the live
-/// case — unset, they disable themselves in `<OnShow>` and their `<OnEnter>` indexes a nil
-/// `AtlasLootCharDB.QuickLooks[n]`.
+/// A disabled Button fires neither `OnEnter` nor `OnLeave`: `CSimpleButton::OnEnter` (`0x779490`)
+/// and `OnLeave` (`0x7794e0`) test `[esi+0x328]` and skip the base notify (`0x76b6a0`,
+/// `0x76b6f0`). It still takes the hover: the walk sets `[root+0x7c]` before the notify.
 #[test]
 fn a_disabled_button_takes_the_hover_but_fires_no_enter_or_leave() {
     let mut s = script();
@@ -913,7 +827,6 @@ fn a_disabled_button_takes_the_hover_but_fires_no_enter_or_leave() {
         "entering a disabled button fires nothing"
     );
 
-    // Leaving it is as silent as entering it, and the enabled neighbour is the control.
     s.mouse_move(250.0, 50.0);
     assert_eq!(
         s.eval::<String>("return table.concat(log, ',')").unwrap(),
@@ -921,7 +834,7 @@ fn a_disabled_button_takes_the_hover_but_fires_no_enter_or_leave() {
         "no leave from the disabled button; the enabled one notifies normally"
     );
 
-    // Disabled WHILE hovered: the leave is gated on the state at leave time, not at enter time.
+    // Disabled while hovered: the leave is gated on the state at leave time.
     s.run("On:Disable()").unwrap();
     s.mouse_move(400.0, 50.0);
     assert_eq!(
diff --git a/crates/benilla-ui/src/script/tests/keyboard.rs b/crates/benilla-ui/src/script/tests/keyboard.rs
index f6c05ec2..e1d2571a 100644
--- a/crates/benilla-ui/src/script/tests/keyboard.rs
+++ b/crates/benilla-ui/src/script/tests/keyboard.rs
@@ -1,13 +1,8 @@
-//! The frame keyboard delivery law (decision 1319; wow-re
-//! `system/ui/scratch/frame-key-script-delivery.md`, §5 trio — VERIFIED).
-//!
-//! Each test pins one clause that a plausible-but-wrong implementation gets backwards.
+//! Frame keyboard delivery: the walk (`0x765f10`) and its existence gate (`0x76b7d0`).
 
 use super::common::script;
 
-/// The bucket gate (§3.2): membership is the **keyboard-enabled flag**, not the presence of a
-/// script. A Lua-created frame auto-enables nothing (the reference's `SetScript` doesn't either),
-/// so its handler is unreachable until `EnableKeyboard(true)` puts it in the walk.
+/// Bucket membership (`0x76af00`) is the keyboard-enabled flag, which `SetScript` never sets.
 #[test]
 fn a_key_script_alone_does_not_put_a_frame_in_the_walk() {
     let mut s = script();
@@ -37,9 +32,8 @@ fn a_key_script_alone_does_not_put_a_frame_in_the_walk() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The existence gate's asymmetry (§3): a frame carrying **only** an `OnKeyUp` consumes every
-/// key-down and runs nothing. This is the clause an implementation "tidies away" — and doing so
-/// silently un-suppresses that frame's keybindings.
+/// The existence gate (`0x76b7d0`) takes either key slot, so a frame with only an `OnKeyUp`
+/// consumes every key-down and runs nothing.
 #[test]
 fn only_an_onkeyup_still_swallows_the_key_down() {
     let mut s = script();
@@ -59,15 +53,12 @@ fn only_an_onkeyup_still_swallows_the_key_down() {
         "…and fires nothing"
     );
 
-    // Neither slot: declines outright.
     s.run("f:SetScript(\"OnKeyUp\", nil)").unwrap();
     assert!(!s.key_input("ESCAPE"), "no key slot at all: declines");
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The walk order (§2): **strata descending first**, and only then level. A LOW frame can never
-/// take a key from a HIGH one, however high its level — the same "a raise never changes stratum"
-/// shape the toplevel law has.
+/// The walk (`0x765f10`, `0x764ae2`) runs strata descending, then level, then registration order.
 #[test]
 fn the_walk_is_strata_then_level_then_registration() {
     let mut s = script();
@@ -95,7 +86,6 @@ fn the_walk_is_strata_then_level_then_registration() {
         "strata beats level"
     );
 
-    // Within one stratum: higher level wins, and equal levels keep registration order.
     s.run(
         r#"
         winner = nil
@@ -113,8 +103,7 @@ fn the_walk_is_strata_then_level_then_registration() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **At most one frame consumes** (§2, "Delivery"): the walk stops at the first consumer, so a
-/// second keyboard frame below it never sees the key.
+/// The walk stops at the first consumer (`0x765f10`).
 #[test]
 fn the_first_consumer_ends_the_walk() {
     let mut s = script();
@@ -138,8 +127,7 @@ fn the_first_consumer_ends_the_walk() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A hidden frame is in no bucket (the link gate the walk shares with the draw order), so it
-/// neither fires nor consumes — and the frame below it gets the key instead.
+/// The walk shares the draw order's link gate, so a hidden frame is in no bucket.
 #[test]
 fn a_hidden_frame_is_not_in_the_walk() {
     let mut s = script();
@@ -164,8 +152,7 @@ fn a_hidden_frame_is_not_in_the_walk() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A raising handler must not eat the key or abort the walk's caller: the error is recorded, the
-/// frame still consumed (consumption is the C++ gate's, never the handler's — §3.1).
+/// Consumption is the gate's decision, never the handler's (`0x7026f0`).
 #[test]
 fn a_raising_handler_still_consumes_and_is_recorded() {
     let mut s = script();
@@ -185,16 +172,9 @@ fn a_raising_handler_still_consumes_and_is_recorded() {
     );
 }
 
-/// **A `CSimpleEditBox` in the walk is asked about FOCUS, never about a script slot** (§1's vtable
-/// table + `0x77a900`). Its ctor registers it in both key buckets, and vtable `0x81c910` replaces
-/// `+0x5c`/`+0x60` with overrides that *never chain to the base* — "there is no `call 0x76b760`
-/// anywhere in it, so the generic `OnChar` slot `+0x180` is unreachable on an editbox". An
-/// unfocused box therefore takes the `0x77a956 xor eax,eax` leg: decline, walk continues.
-///
-/// Modelling the box as a plain frame here is not a subtle divergence. Stock
-/// `SendMailNameEditBox` carries an XML `<OnChar>` (`SendMailFrame_SendeeAutocomplete`), which
-/// auto-enables it, and it registers first in the mail window — so it consumed every keystroke and
-/// the send tab's other four boxes took no input at all (decision 2145).
+/// An editbox in the walk is asked about focus, never a script slot (`0x77a900`): vtable
+/// `0x81c910` overrides `+0x5c`/`+0x60` without calling the base gate `0x76b760`, so an unfocused
+/// box declines at `0x77a956` and the walk continues.
 #[test]
 fn an_unfocused_editbox_declines_rather_than_eating_its_neighbours_keys() {
     let mut s = script();
@@ -223,8 +203,7 @@ fn an_unfocused_editbox_declines_rather_than_eating_its_neighbours_keys() {
         "the unfocused box's own OnChar is unreachable from the walk — it declines"
     );
 
-    // Give the decoy the focus and its handler is reachable again — through the INSERT, which is
-    // where an editbox's `OnChar` is fired from (`0x77c200`), not through the walk's base gate.
+    // Focused, the decoy's `OnChar` fires from the insert (`0x77c200`), not from the walk's gate.
     s.run("KbDecoyBox:SetFocus()").unwrap();
     assert!(s.char_input("j"), "…and now it is the one that consumes");
     assert_eq!(s.eval::<i64>("return decoyChars").unwrap(), 1);
@@ -240,10 +219,8 @@ fn an_unfocused_editbox_declines_rather_than_eating_its_neighbours_keys() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The same clause on the key-down channel (`+0x60` → `0x77b160`, focus guard at `0x77b1c7`), which
-/// is the [`super::super::keyboard::frame_key_input`] walk: an unfocused box carrying only an
-/// `OnKeyUp` must not swallow a BACKSPACE the focused box is waiting for. The plain-frame
-/// asymmetry above is real *for plain frames*; on a box the base gate is not reached at all.
+/// The same on the key-down channel (`+0x60` is `0x77b160`, focus guard at `0x77b1c7`): an
+/// editbox never reaches the base gate, so an `OnKeyUp` alone does not make it consume.
 #[test]
 fn an_unfocused_editbox_does_not_swallow_a_focused_boxs_editing_key() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/layout_gate.rs b/crates/benilla-ui/src/script/tests/layout_gate.rs
index 73ec05b7..cb409817 100644
--- a/crates/benilla-ui/src/script/tests/layout_gate.rs
+++ b/crates/benilla-ui/src/script/tests/layout_gate.rs
@@ -1,9 +1,6 @@
-//! The layout change gate: a resolve whose inputs are byte-identical to the last converged one is
-//! skipped outright (`script::layout::InputFingerprint`).
-//!
-//! These assert on `Model::layout_solves` — the count of times the fixpoint actually ran — rather
-//! than on the rects, because rect equality alone cannot distinguish "the gate skipped" from "the
-//! gate re-solved and got the same answer". The value of the gate is precisely the difference.
+//! The layout change gate: a resolve whose inputs match the last converged one is skipped
+//! (`script::layout::InputFingerprint`). The tests count solves (`Model::layout_solves`), since
+//! equal rects cannot tell a skip from a re-solve.
 
 use super::common::script;
 use crate::script::{Model, UiScript};
@@ -24,8 +21,7 @@ fn solves(s: &UiScript) -> u64 {
         .layout_solves
 }
 
-/// A frame anchored to the screen, plus a child hanging off it — enough that a move has to
-/// propagate, so a wrongly-skipped resolve would be visible in the child too.
+/// A screen-anchored frame and a child off it, so a move has to propagate.
 fn setup(s: &UiScript) {
     s.run(
         r#"
@@ -50,7 +46,6 @@ fn an_unchanged_resolve_does_not_run_the_fixpoint() {
     let after_first = solves(&s);
     assert_eq!(after_first, 1, "the first resolve must run");
 
-    // Nothing touched in between: every further resolve is a no-op.
     for _ in 0..5 {
         s.resolve();
     }
@@ -84,7 +79,6 @@ fn moving_a_frame_reopens_the_gate_and_propagates() {
         child_left(&s)
     );
 
-    // And it closes again once the move has settled.
     let after = solves(&s);
     s.resolve();
     assert_eq!(
@@ -94,7 +88,6 @@ fn moving_a_frame_reopens_the_gate_and_propagates() {
     );
 }
 
-/// Resizing the window moves every top-level frame — the gate must never swallow it.
 #[test]
 fn a_screen_resize_reopens_the_gate() {
     let mut s = script();
@@ -113,8 +106,7 @@ fn a_screen_resize_reopens_the_gate() {
     );
 }
 
-/// A region's own `SetPoint` writes `region_data`, not `layout_inputs` — the half of the read set
-/// that is easiest to leave out of a change gate, and the one the region sweep consumes.
+/// A region's `SetPoint` writes `region_data`, not `layout_inputs`; the region sweep reads it.
 #[test]
 fn moving_a_region_reopens_the_gate() {
     let mut s = script();
@@ -142,10 +134,8 @@ fn moving_a_region_reopens_the_gate() {
     );
 }
 
-/// Hiding a frame does NOT move any rect (the client resolves hidden frames too — visibility is an
-/// extract-time filter), so the gate is right to stay closed. Pinned deliberately: it is the one
-/// place where "nothing to re-solve" is surprising, and a future reader tempted to dirty on
-/// show/hide should see that the current model does not need it.
+/// Hidden frames still resolve (visibility is an extract-time filter), so a hide moves no rect and
+/// the gate stays closed.
 #[test]
 fn hiding_a_frame_does_not_reopen_the_gate() {
     let mut s = script();
@@ -164,22 +154,9 @@ fn hiding_a_frame_does_not_reopen_the_gate() {
     );
 }
 
-/// The hover re-enter loop must be FREE while the content is unchanged.
-///
 /// `ContainerFrameItemButton_OnUpdate` re-runs `OnEnter` every frame while the tooltip is the
-/// button's own — faithful, and UNTHROTTLED in 1.12 (its `updateTooltip` throttle is commented
-/// out; the reference's `ContainerFrameItemButton_OnUpdate` ships the same loop). So a bag hover clears and
-/// rebuilds the SAME tooltip 60×/sec, and the engine must absorb that: identical content re-derives
-/// an identical model, so the measure cache re-validates on its content key and the gate stays shut.
-///
-/// This is the regression gate for the live report (a bag hover cost +10 CPU ms/frame, ~2 full
-/// arena solves + a re-shape of every line, every frame): `clear_content` wiped
-/// `RegionData::measured` — an invalidation the content-hash key already performs — so every
-/// re-enter re-measured every line, and the non-empty measure list forced a second full resolve
-/// that the gate could never close over.
-///
-/// It drives the app's real per-frame order (`ui_script::extract::tick_script`): Lua tick →
-/// resolve → measure round-trip → resolve.
+/// button's, its throttle commented out (`ContainerFrame.lua:645`), so rebuilding identical
+/// tooltip content must neither re-measure nor re-solve.
 #[test]
 fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
     let mut s = script();
@@ -206,8 +183,7 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
     )
     .expect("setup");
 
-    // The host's font engine: every distinct string has one deterministic size. Counts every
-    // string it is asked to shape, so the test can assert on shaping work directly.
+    // The host's font engine: one fixed size per string.
     let sizes: &[(&str, f32, f32)] = &[
         ("Small Shield", 80.0, 14.0),
         ("Shield", 50.0, 12.0),
@@ -216,8 +192,8 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
         ("Restores 243 health over 21 sec.", 118.0, 24.0),
         ("Durability 45 / 45", 96.0, 12.0),
     ];
-    // One frame of `tick_script`: tick (the re-enter) → resolve → measure round-trip → resolve.
-    // Returns how many strings the font engine was asked to shape this frame.
+    // One frame in the app's order (`ui_script::extract::tick_script`): tick, resolve, measure
+    // round-trip, resolve. Returns how many strings were shaped.
     let frame = |s: &mut UiScript| -> usize {
         s.run("reenter()").expect("re-enter");
         s.resolve();
@@ -241,8 +217,7 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
         shaped
     };
 
-    // Settle: the first frames legitimately shape the five strings and re-solve as the auto-size
-    // pre-pass converges on the fresh measures.
+    // The first frames shape the strings and re-solve while the auto-size pre-pass converges.
     for _ in 0..4 {
         frame(&mut s);
     }
@@ -264,12 +239,7 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
         solves_before,
         "a re-enter with identical content must not reopen the layout gate"
     );
-    // …and it must not even reach tier 2. Tier 1 (the mutation epoch) is what makes a quiet frame
-    // FREE; tier 2 still hashes the whole UI's read set to decide "quiet" (~0.65 ms/frame measured
-    // with `WOW_UI_COST=1` on `WOW_CAPTURE=ui-tooltip`, at solves=0). The re-enter loop used to
-    // pay that on every single hover frame, because `clear_content` wiped each line's wrap pin and
-    // `append_line` re-pinned the same width — a round trip inside one frame, two epoch bumps.
-    // Idempotent content must be epoch-silent, not merely fingerprint-absorbed.
+    // Nor may it reach tier 2, which hashes the whole UI: identical content leaves the epoch alone.
     let epoch_before = epoch(&s);
     for _ in 0..10 {
         frame(&mut s);
@@ -281,9 +251,8 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
          hold, or every hover frame pays the whole-UI fingerprint"
     );
 
-    // The gate is shut because nothing MOVED — not because the tooltip went stale. Changed content
-    // must still re-measure exactly its own line, and a measure that resizes the auto-sized plate
-    // (this one overtakes the double line as the widest) must reopen the gate.
+    // Changed content re-measures only its own line, and a measure that widens the auto-sized
+    // plate reopens the gate.
     s.run(
         r#"function reenter()
             TT:SetOwner(Slot, "ANCHOR_RIGHT")
@@ -328,28 +297,16 @@ fn the_hover_re_enter_loop_neither_re_measures_nor_re_solves() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// Tier 1 of the gate (decision 0740): the mutation epoch. **Any CONVERGED resolve closes it**
-/// (decision 1385) — the fingerprint is hashed over inputs alone, so a solve cannot outgrow the
-/// value it stores — and from then on a quiet frame skips at a `u64` compare without computing
-/// the fingerprint at all.
+/// Whether tier 1, the mutation epoch, is closed: any converged resolve closes it, and a quiet
+/// frame then skips at a `u64` compare without hashing the fingerprint.
 fn tier_one_closed(s: &UiScript) -> bool {
     let m = s.lua().app_data_ref::<Model>().expect("model app_data");
     m.layout_epoch_resolved == Some(m.layout_epoch)
 }
 
-/// **The castbar law** (decision 1385, ledger B283): a region that MOVES every frame — the classic
-/// OnUpdate animation idiom, our own `CastingBarSpark:SetPoint`, and every addon that slides a
-/// texture — must cost exactly **one** let-through resolve per frame.
-///
-/// It used to cost three. The fingerprint was hashed over the 0294 SEEDS as well as the inputs, so
-/// a solve necessarily outgrew the fingerprint it had just stored: neither that pass nor the
-/// settling pass behind it could close tier 1, and the frame paid solve + settle + skip — three
-/// whole-roster walks at ~1.0–1.4 ms each. Measured live at the Stormwind pin: **+4.2 ms of CPU
-/// per frame for one 32×32 spark**, on a default UI with no addons loaded.
-///
-/// This is the regression guard for that whole bug class. `solves` is the honest counter — a
-/// wasted walk that concludes "nothing moved" still costs the full preamble — so the assertion is
-/// on the count, never on a duration (0735: milliseconds are not evidence of a scope regression).
+/// A region moved every frame, as `CastingBarSpark:SetPoint` does (`CastingBarFrame.lua:114`),
+/// costs exactly one solve per frame: the fingerprint hashes inputs alone, so that solve closes
+/// tier 1.
 #[test]
 fn a_region_moving_every_frame_costs_exactly_one_solve_per_frame() {
     let mut s = script();
@@ -366,13 +323,8 @@ fn a_region_moving_every_frame_costs_exactly_one_solve_per_frame() {
     s.resolve();
     assert!(tier_one_closed(&s), "the setup must settle in one resolve");
 
-    // Ten frames of the castbar's own inner loop: one region re-pointed to a NEW offset, then the
-    // host's per-frame resolve. Nothing else in the model moves.
-    //
-    // The offsets start at 1.7, not 0 — a `frame * 1.7` sequence opens with a re-write of the
-    // seed value, which the setters' bit-exact compare absorbs (no epoch bump, no solve at all).
-    // That is the *right* answer and `an_idempotent_setter_call_leaves_tier_one_closed` pins it;
-    // here it would have measured the guard instead of the gate.
+    // Ten castbar frames: the spark re-pointed to a new offset, then the per-frame resolve. The
+    // offsets start at 1.7, not 0, since the setters' compare absorbs a write of the seed value.
     for frame in 0..10 {
         let before = solves(&s);
         s.run(&format!(
@@ -396,8 +348,7 @@ fn a_region_moving_every_frame_costs_exactly_one_solve_per_frame() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The other half of the same law: once it has settled, an untouched frame costs NOTHING — no
-/// solve, and (tier 1) not even the fingerprint walk that would decide so.
+/// A settled, untouched frame costs no solve, and tier 1 spares it the fingerprint walk too.
 #[test]
 fn a_quiet_frame_after_a_move_costs_no_solve_at_all() {
     let mut s = script();
@@ -421,9 +372,7 @@ fn a_settled_resolve_closes_tier_one_and_a_real_write_reopens_it() {
     s.set_screen_size(800.0, 600.0);
     setup(&s);
 
-    // ONE resolve closes the epoch (decision 1385): the fingerprint is hashed over inputs alone,
-    // and the rounds just drove those inputs to their fixpoint, so there is nothing left for a
-    // settling pass to discover. This used to need two.
+    // One resolve closes the epoch: the fingerprint hashes inputs alone, now at their fixpoint.
     s.resolve();
     assert!(
         tier_one_closed(&s),
@@ -448,9 +397,7 @@ fn an_idempotent_setter_call_leaves_tier_one_closed() {
     s.resolve();
     assert!(tier_one_closed(&s));
 
-    // The classic per-frame OnUpdate idiom: re-assert the exact same geometry every frame. The
-    // setters' compare-before-write keeps the epoch untouched, so an idle UI never re-enters
-    // the fingerprint path at all.
+    // The OnUpdate idiom of re-setting the same geometry: the setters compare before writing.
     s.run(
         r#"
         parent:SetWidth(100); parent:SetHeight(40)
@@ -473,8 +420,8 @@ fn a_paint_only_write_leaves_tier_one_closed() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     setup(&s);
-    // A paint region with NO anchors: its region_data entry is created by a paint setter and
-    // must stay invisible to the layout gate (the resolve sweep skips anchor-less entries).
+    // A region with no anchors: a paint setter creates its `region_data` entry, which the resolve
+    // sweep skips, so the gate must ignore it.
     s.run(r#"tex = parent:CreateTexture(nil, "ARTWORK")"#)
         .expect("region");
     s.resolve();
@@ -491,17 +438,8 @@ fn a_paint_only_write_leaves_tier_one_closed() {
     assert_eq!(solves(&s), before);
 }
 
-/// **The retarget falsifier** (decision 1625): after a node is re-pointed from target A to target
-/// B, the cached graph's EDGES must describe the new shape — moving B must move the node.
-///
-/// This is the one direction that can be silently wrong. 1625 keeps the cached graph across an
-/// anchor retarget by patching one node's edges instead of re-deriving all of them, and a patch
-/// that dropped the *new* edge would under-dirty: the node would sit at a stale rect while the
-/// thing it is anchored to moved. (The other direction — a leftover edge to the OLD target — only
-/// costs a needless re-solve, so it is asserted second and separately.)
-///
-/// It asserts on RECTS, not on counts, because a wrong edge set is a wrong picture: the failure
-/// this guards against is a tooltip left behind at the last button's position.
+/// A retarget patches one node's edges in the cached graph instead of re-deriving it, so the new
+/// edge must land: moving the new target moves the node, and moving the old one does not.
 #[test]
 fn a_retargeted_anchor_follows_its_new_target() {
     let mut s = script();
@@ -521,8 +459,7 @@ fn a_retargeted_anchor_follows_its_new_target() {
     s.resolve();
     s.resolve();
 
-    // The retarget: the plate now hangs off B, exactly as `GameTooltip:SetOwner` re-points the
-    // plate at the next button under the cursor.
+    // The plate now hangs off B, as `GameTooltip:SetOwner` re-points it at the next button.
     s.run(r#"plate:SetPoint("TOPLEFT", b, "TOPRIGHT", 0, 0)"#)
         .expect("retarget");
     s.resolve();
@@ -532,9 +469,6 @@ fn a_retargeted_anchor_follows_its_new_target() {
         "the retargeted plate must sit at B's right edge (110), not {after_retarget}"
     );
 
-    // …and it must keep following B. This is the assertion the edge patch exists to satisfy: the
-    // graph was NOT re-derived across the retarget, so if the new edge never made it into the
-    // cached edge set, B moving reaches nothing and the plate stays put.
     s.run(r#"b:SetPoint("TOPLEFT", nil, "TOPLEFT", 300, 0)"#)
         .expect("move B");
     s.resolve();
@@ -545,7 +479,6 @@ fn a_retargeted_anchor_follows_its_new_target() {
          retarget's edge patch dropped the new edge and the node is under-dirtied (decision 1625)"
     );
 
-    // …and it must NOT follow the old one any more.
     s.run(r#"a:SetPoint("TOPLEFT", nil, "TOPLEFT", 0, -50)"#)
         .expect("move A");
     s.resolve();
diff --git a/crates/benilla-ui/src/script/tests/measure.rs b/crates/benilla-ui/src/script/tests/measure.rs
index c2f4bee7..b280da10 100644
--- a/crates/benilla-ui/src/script/tests/measure.rs
+++ b/crates/benilla-ui/src/script/tests/measure.rs
@@ -1,12 +1,11 @@
-//! The measure round-trip + frame→region anchors, end to end.
+//! Text measurement: the host round-trip, the same-tick font engine, and the layout they feed.
 
 use super::common::script;
 use crate::script::*;
 
-/// The measure round-trip + frame→region anchors, end to end: a height-less FontString reports a
-/// [`MeasureRequest`]; the host answer becomes its implicit size; and a FRAME anchored to that
-/// FontString by name binds to its measured bottom in resolve's second round — the real gossip
-/// structure (option rows hang off the greeting's laid-out height, ref-GossipFrame.xml l.258-261).
+/// A height-less FontString's [`MeasureRequest`] answer becomes its size, and a frame anchored to
+/// it binds to the measured bottom in resolve's second round, as gossip option rows hang off the
+/// greeting text (`GossipFrame.xml:258`).
 #[test]
 fn measured_fontstring_height_feeds_frame_anchors() {
     let mut s = script();
@@ -48,7 +47,7 @@ fn measured_fontstring_height_feeds_frame_anchors() {
         })
         .expect("greeting rect");
     assert_eq!((g.top, g.bottom, g.left), (409.0, 361.0, 33.0));
-    // Row1: TOPLEFT → Greeting BOTTOMLEFT +(-10,-20) ⇒ top 341, left 23 — bound in round 2.
+    // Row1: TOPLEFT → Greeting BOTTOMLEFT +(-10,-20) ⇒ top 341, left 23, bound in round 2.
     let row = quads
         .iter()
         .find_map(|q| match q.target {
@@ -60,13 +59,9 @@ fn measured_fontstring_height_feeds_frame_anchors() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A stored measure serves ONLY the current text: after `SetText` to a DIFFERENT string, the old
-/// string's width must not leak through `GetWidth`/`GetStringWidth` — the whisper-header cursor
-/// bug: the chat edit box ran `SetTextInsets(15 + header:GetWidth(), …)` on a type switch
-/// (Say → "Tell Alice:") and its `w > 1` settle gate passed with the PREVIOUS header's measure,
-/// latching the caret inside the new header. The metric read is key-checked
-/// ([`crate::script::RegionData`]'s measure key): a changed string reads 0 until its own measure
-/// lands, so poll-until-nonzero callers converge on the RIGHT width.
+/// A stored measure serves only its own text: reads check [`crate::script::RegionData`]'s measure
+/// key, so a changed string reads 0 until its measure lands, never the old width. The chat header
+/// reads its width right after a `SetText` (`ChatFrame.lua:1912`).
 #[test]
 fn a_changed_text_reads_zero_until_its_own_measure_lands() {
     let mut s = script();
@@ -92,7 +87,7 @@ fn a_changed_text_reads_zero_until_its_own_measure_lands() {
             .unwrap(),
         30.0
     );
-    // The type switch: same region, new text. The old measure must NOT serve.
+    // The type switch: same region, new text.
     s.run(r#"getglobal("Header"):SetText("Tell Alice: ")"#)
         .unwrap();
     assert_eq!(
@@ -101,7 +96,6 @@ fn a_changed_text_reads_zero_until_its_own_measure_lands() {
         0.0,
         "a stale measure must not serve for changed text"
     );
-    // The round-trip re-measures the new string; the true width serves.
     s.resolve();
     let reqs = s.fontstrings_needing_measure();
     assert_eq!(reqs.len(), 1, "the changed text wants re-measuring");
@@ -117,11 +111,9 @@ fn a_changed_text_reads_zero_until_its_own_measure_lands() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A zero-WIDTH FontString with an explicit height auto-sizes its width to the measured line —
-/// the reference label idiom (`<Size x="0" y="16"/>` anchored TOPRIGHT→TOPLEFT: MailFrame's
-/// "From:"/"Subject:" labels end at the anchor and grow leftward, and the value string anchored
-/// LEFT→label RIGHT starts past them, never overlapping). Gating the measure on height alone
-/// left these rects zero-width — "From" and the sender name painted on top of each other.
+/// A zero-width FontString with a height auto-sizes its width to the measured line: MailFrame's
+/// `OpenMailSenderLabel` (`MailFrame.xml:1391`) grows leftward from its anchor, and the sender
+/// name anchored to its right edge starts past it.
 #[test]
 fn zero_width_fontstring_autosizes_to_its_line() {
     let mut s = script();
@@ -163,17 +155,14 @@ fn zero_width_fontstring_autosizes_to_its_line() {
         .eval("return FromLabel:GetLeft(), FromLabel:GetRight(), FromLabel:GetStringWidth()")
         .unwrap();
     assert_eq!((l_left, l_right, l_w), (74.0, 114.0, 40.0));
-    // Value: starts 5 past the label's real right edge — no overlap.
+    // Value: 5 past the label's measured right edge.
     let v_left: f32 = s.eval("return FromValue:GetLeft()").unwrap();
     assert_eq!(v_left, 119.0);
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The frame-scale seam (0219 §2's divergence, closed): a `SetScale`'d frame's quads carry its
-/// `effective_scale` out to the renderer — the rect is already scale-multiplied by layout, and
-/// the renderer needs the same factor for the GLYPH raster size — and the measure round-trip
-/// rides it too: the request names the scale (the host measures at the drawn size), the cache
-/// key holds it (a re-scale re-measures), all before any quad draws stale text.
+/// A scaled frame's quads carry its effective scale for the glyph raster (layout already scaled
+/// the rect), and the measure request and its cache key carry it too.
 #[test]
 fn frame_scale_rides_the_quads_and_the_measure_key() {
     let mut s = script();
@@ -190,7 +179,6 @@ fn frame_scale_rides_the_quads_and_the_measure_key() {
     )
     .unwrap();
     s.resolve();
-    // The measure request carries the owner's effective scale.
     let reqs = s.fontstrings_needing_measure();
     assert_eq!(reqs.len(), 1);
     let r = &reqs[0];
@@ -200,18 +188,15 @@ fn frame_scale_rides_the_quads_and_the_measure_key() {
     s.set_measured_text_unwrapped(&[(id, 50.0, 16.0, key)]);
     s.resolve();
     assert!(s.fontstrings_needing_measure().is_empty(), "cache warm");
-    // Every quad of the scaled frame carries the scale — frame slot and region alike.
     let quads = s.extract();
     let label = quads
         .iter()
         .find(|q| matches!(&q.content, QuadContent::Text { text: Some(t), .. } if t == "Options"))
         .expect("label quad");
     assert_eq!(label.scale, 0.8);
-    // The label's rect is scale-multiplied by layout (width 50 × 0.8 = 40) — the quad's scale is
-    // for the glyph raster, not a second rect multiply.
+    // Layout already scaled the rect (50 × 0.8 = 40); the quad's scale is for the glyphs only.
     let lr = label.rect.expect("label rect");
     assert!((lr.width() - 40.0).abs() < 0.01, "width {}", lr.width());
-    // A re-scale invalidates the measure key: the same text re-measures at the new drawn size.
     s.run(r#"Win:SetScale(1.25)"#).unwrap();
     s.resolve();
     let reqs = s.fontstrings_needing_measure();
@@ -221,12 +206,9 @@ fn frame_scale_rides_the_quads_and_the_measure_key() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The host's raster-environment invalidation ([`UiScript::invalidate_text_measures`]): a warm
-/// FontString measure cache re-requests after the call — same content, same key (the key hashes
-/// content, not the host's seam scale; the STALENESS is the host's to declare, which is the whole
-/// seam). This is the engine half of the fullscreen-truncation fix: measures answered under one
-/// seam scale kept satisfying fit tests run under another, and the ellipsis ate fitting text
-/// ("Contr...", director 2026-08-04; reproduced end-to-end by `WOW_RESIZE`).
+/// [`UiScript::invalidate_text_measures`] re-requests every warm measure under the same key: the
+/// key hashes content, not the host's raster scale, so only the host knows when a measure is
+/// stale, and a stale one truncates text that fits.
 #[test]
 fn invalidate_text_measures_reopens_the_round_trip() {
     let mut s = script();
@@ -254,14 +236,11 @@ fn invalidate_text_measures_reopens_the_round_trip() {
     );
 
     s.invalidate_text_measures();
-    // The measured extent is gone (GetStringWidth back to its unmeasured 0)…
     assert_eq!(
         s.eval::<f64>("return Label:GetStringWidth()").unwrap(),
         0.0,
         "stale measure dropped, not served"
     );
-    // …and the round-trip reopens with the SAME content key — the request is the host's cue to
-    // re-measure under its new environment; nothing about the region itself changed.
     let reqs = s.fontstrings_needing_measure();
     assert_eq!(reqs.len(), 1, "re-requests after invalidation");
     assert_eq!(
@@ -271,20 +250,9 @@ fn invalidate_text_measures_reopens_the_round_trip() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`GetStringWidth` is the NATURAL width — never the box, never the wrapped extent** (wow-re
-/// `fontstring-overflow.md`, "The measurement echo": the reference re-measures the raw text with no
-/// wrap constraint, so "Lua sees the natural, unwrapped, un-truncated width at the DRAWN size").
-///
-/// This is the distinction whose absence made the reference's own `PanelTemplates_TabResize` a
-/// feedback loop in this engine (decision 0997): the kit sized a tab from `GetStringWidth`, set that
-/// width on the label, and read its own output back next frame — a tab that changed width every
-/// single frame. Three separate things are pinned here because each one was wrong on its own:
-///
-/// 1. a region with a DECLARED width still gets a measure request (it used to be skipped: no
-///    auto-sized axis, no request — so a constrained label could never learn its natural width);
-/// 2. `GetStringWidth` answers with the natural width, while `GetWidth` keeps echoing the laid-out
-///    extent that auto-size depends on;
-/// 3. the answer does not move when the declared width does.
+/// `GetStringWidth` is the natural width, unwrapped and untruncated at the drawn size: the
+/// reference re-measures the raw text with no wrap (`0x79e510`, `0x772890`). `GetWidth` stays the
+/// laid-out box.
 #[test]
 fn get_string_width_is_the_natural_width_not_the_box() {
     let mut s = UiScript::new().unwrap();
@@ -303,8 +271,7 @@ fn get_string_width_is_the_natural_width_not_the_box() {
     .unwrap();
     s.resolve();
 
-    // 1 · Both axes are declared, so nothing about the LAYOUT needs a measure — and the request is
-    //     issued anyway, because `GetStringWidth` has no other way to learn the natural width.
+    // 1 · A fully declared box still requests a measure, for the natural width.
     let reqs = s.fontstrings_needing_measure();
     assert_eq!(reqs.len(), 1, "a fully-sized FontString still measures");
     let r = &reqs[0];
@@ -326,8 +293,7 @@ fn get_string_width_is_the_natural_width_not_the_box() {
         "GetWidth is the laid-out box the auto-size path depends on"
     );
 
-    // 3 · Narrowing the box re-opens the round trip (the key carries the wrap) and, once answered,
-    //     leaves the natural width exactly where it was. This is the loop that used to close.
+    // 3 · A narrower box re-measures (the key carries the wrap); the natural width stays put.
     s.run("Label:SetWidth(30)").unwrap();
     s.resolve();
     let reqs = s.fontstrings_needing_measure();
@@ -341,14 +307,10 @@ fn get_string_width_is_the_natural_width_not_the_box() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The SYNCHRONOUS measure — a host font engine installed into the VM ([`TextMeasure`])
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The synchronous measure: a host font engine installed in the VM (`TextMeasure`) ──
 
-/// A stand-in font engine: every character is `PER_CHAR` wide and every line `LINE_H` tall, wrapped
-/// greedily at the request's wrap width. Deliberately not the real one — what these tests are about
-/// is *when* the answer arrives, and a fake with arithmetic anyone can do in their head is what
-/// makes the assertions readable. The real engine's own numbers are the app's to test.
+/// A stand-in font engine: each character is `PER_CHAR` wide and each line `LINE_H` tall, wrapped
+/// greedily at the request's wrap width.
 struct BlockFont;
 
 const PER_CHAR: f32 = 7.0;
@@ -367,13 +329,8 @@ impl TextMeasure for BlockFont {
     }
 }
 
-/// **The director's bug, at the engine.** `SetText` then `GetStringWidth` in ONE tick must answer
-/// with the string's width — the shape `Bagnon_Forever/database/ui.lua:58-59` writes over every
-/// saved character (`button:SetText(player)` then `button:GetTextWidth() + 40`), and the shape the
-/// reference's own `SmallMoneyFrame` writes (MoneyFrame.lua l.202).
-///
-/// Without an engine installed this is 0 until the host's round-trip lands at extract — a frame
-/// later. That is what sized Bagnon's character dropdown to 40px with seven names hanging out of it.
+/// With a font engine installed, `SetText` then a width read in the same tick gets the string's
+/// width, as the money frame's `SetText` then `GetTextWidth` expects (`MoneyFrame.lua:202`).
 #[test]
 fn a_width_read_in_the_tick_that_set_the_text_is_not_zero() {
     let mut s = script();
@@ -398,9 +355,8 @@ fn a_width_read_in_the_tick_that_set_the_text_is_not_zero() {
     );
 }
 
-/// The same read WITHOUT an engine stays 0 and stays served by the round-trip — the pre-existing
-/// behaviour, still exactly itself. Every engine test and every headless run is this VM, so the
-/// synchronous path may never be a correctness precondition for anything.
+/// Without an engine the read is 0 until the round-trip answers; headless runs and most tests have
+/// no engine, so nothing may depend on the synchronous path.
 #[test]
 fn with_no_engine_installed_the_round_trip_is_still_the_only_answer() {
     let mut s = script();
@@ -424,9 +380,8 @@ fn with_no_engine_installed_the_round_trip_is_still_the_only_answer() {
     );
 }
 
-/// A FontString's **box** is right in the frame its text was set, not the frame after: `resolve`
-/// closes the round-trip itself when an engine is installed, so a caller reading `GetWidth()` (the
-/// laid-out extent, not the natural one) gets this string's number and not the previous string's.
+/// With an engine installed, `resolve` answers its own measure requests, so `GetWidth()` is right
+/// in the frame the text was set.
 #[test]
 fn resolve_closes_the_round_trip_when_an_engine_is_installed() {
     let mut s = script();
@@ -458,9 +413,8 @@ fn resolve_closes_the_round_trip_when_an_engine_is_installed() {
     );
 }
 
-/// The same-tick measure and the batch round-trip write the **same cache**, so asking twice costs
-/// one measure — and a caller polling `GetStringWidth` every frame does not re-measure a string
-/// that has not changed.
+/// The same-tick measure and the batch round-trip share one cache, so an unchanged string is
+/// measured once however often it is read.
 #[test]
 fn a_synchronous_measure_satisfies_the_batch_request_too() {
     let mut s = script();
@@ -482,7 +436,6 @@ fn a_synchronous_measure_satisfies_the_batch_request_too() {
         s.fontstrings_needing_measure().is_empty(),
         "the Lua read already filled the cache the batch pass keys on"
     );
-    // …and a new string invalidates it exactly as it always did.
     s.run("Label:SetText('a longer label')").unwrap();
     assert_eq!(
         s.eval::<f32>("return Label:GetStringWidth()").unwrap(),
@@ -491,13 +444,8 @@ fn a_synchronous_measure_satisfies_the_batch_request_too() {
     );
 }
 
-/// The measure LEDGER's completeness guard: `fontstrings_needing_measure` no longer walks the
-/// roster on the armed path — a measure-input write the ledger never hears about is a label
-/// whose box silently never updates again. The exposing sequence is SETTLE (drain the ledger
-/// dry), then one silent write, then sweep: enrolled, the sweep names exactly that region;
-/// missed, it returns empty and this test is the red light. (Watched red with the `SetText`
-/// enrollment removed — the earlier tests in this file stay green through that removal, because
-/// their regions ride the ledger's own re-enrollment of still-unanswered requests.)
+/// `fontstrings_needing_measure` sweeps only the regions a write enrolled, so every measure-input
+/// write must enroll its region: settle, write once, and the sweep must name that region.
 #[test]
 fn a_settled_region_is_refound_after_each_measure_input_write() {
     let mut s = script();
@@ -514,17 +462,13 @@ fn a_settled_region_is_refound_after_each_measure_input_write() {
     .unwrap();
     let writes: &[(&str, &str)] = &[
         ("SetText", "Label:SetText('two')"),
-        // `SetFormattedText` was a second row here; it is gone (2142), and its era spelling
-        // `SetText(format(...))` is the row above's path exactly.
         (
             "SetFont",
             r#"Label:SetFont("Fonts\\FRIZQT__.TTF", 14, "OUTLINE")"#,
         ),
         ("SetTextHeight", "Label:SetTextHeight(20)"),
         ("SetWidth (the wrap width)", "Label:SetWidth(123)"),
-        // The conservative lane: a scale write cannot name descendants one by one, so it must
-        // put the ledger back on the whole-roster walk — which refinds Label (scale is in the
-        // measure key).
+        // A scale write cannot name its descendants, so it falls back to the whole-roster walk.
         ("SetScale (conservative)", "Host:SetScale(2.0)"),
     ];
     for (label, lua) in writes {
@@ -546,8 +490,7 @@ fn a_settled_region_is_refound_after_each_measure_input_write() {
             "{label}: a silent measure-input write must re-surface its region to the sweep"
         );
     }
-    // The button label lane writes through its own binding (`Button:SetText` routes to the
-    // ButtonText region) — same guard, second write path.
+    // `Button:SetText` writes its ButtonText region through its own binding.
     s.run(
         r#"
         local b = CreateFrame("Button", "Btn")
diff --git a/crates/benilla-ui/src/script/tests/minimap.rs b/crates/benilla-ui/src/script/tests/minimap.rs
index 9675f278..87e4dcb0 100644
--- a/crates/benilla-ui/src/script/tests/minimap.rs
+++ b/crates/benilla-ui/src/script/tests/minimap.rs
@@ -1,11 +1,10 @@
-//! The Minimap widget kind (decision 0203): zoom API + the extracted content hole.
+//! The Minimap widget kind: the zoom API and the extracted content hole.
 
 use super::common::script;
 use crate::script::*;
 use crate::widget::{MINIMAP_DEFAULT_ZOOM, MINIMAP_ENGINE_CHILDREN, MINIMAP_ZOOM_LEVELS};
 
-/// A `<Minimap>`-kind frame carries its zoom out through extraction as [`QuadContent::Minimap`]
-/// at the frame's own draw slot, and the zoom API clamps like the client's `set_zoom` (0..=5).
+/// The zoom rides extraction as [`QuadContent::Minimap`]; `SetZoom` clamps to 0..=5.
 #[test]
 fn minimap_zoom_api_and_extract() {
     let mut s = script();
@@ -18,7 +17,7 @@ fn minimap_zoom_api_and_extract() {
     )
     .unwrap();
 
-    // Defaults + the clamp law. Both indices seed from the CVar default "3", not 0.
+    // Both indices seed from the CVar default "3", not 0.
     assert_eq!(
         s.eval::<u8>("return m:GetZoom()").unwrap(),
         MINIMAP_DEFAULT_ZOOM
@@ -38,7 +37,6 @@ fn minimap_zoom_api_and_extract() {
     s.run("m:SetZoom(-2)").unwrap();
     assert_eq!(s.eval::<u8>("return m:GetZoom()").unwrap(), 0);
 
-    // The widget's own slot extracts as the Minimap content hole, carrying the zoom.
     s.resolve();
     let mm = s
         .extract()
@@ -62,7 +60,7 @@ fn minimap_zoom_api_and_extract() {
         "a sized+anchored Minimap resolves a rect"
     );
 
-    // Duck-typing: the zoom API must NOT leak onto other kinds (per-kind method registries).
+    // The zoom methods exist only on the Minimap kind; addons duck-type on them.
     s.run(r#"plain = CreateFrame("Frame", "PlainF")"#).unwrap();
     assert!(
         s.eval::<bool>("return plain.SetZoom == nil").unwrap(),
@@ -70,9 +68,8 @@ fn minimap_zoom_api_and_extract() {
     );
 }
 
-/// The client keeps **two** zoom indices and routes `GetZoom`/`SetZoom` on WMO containment (the
-/// inside flag `0xceaa60` → outdoor `0x86f698` / indoor `0x86f69c`). Each persists across the
-/// transition: zooming the inn's map right in must not disturb the zoom you left outside.
+/// Two zoom indices, outdoor `0x86f698` and indoor `0x86f69c`, picked by the WMO inside flag
+/// `0xceaa60`; each persists across the transition.
 #[test]
 fn minimap_indoor_and_outdoor_zoom_indices_are_independent() {
     let mut s = script();
@@ -85,11 +82,9 @@ fn minimap_indoor_and_outdoor_zoom_indices_are_independent() {
     )
     .unwrap();
 
-    // Outside: the zoom API drives the outdoor index.
     s.run("m:SetZoom(2)").unwrap();
     assert_eq!(s.eval::<u8>("return m:GetZoom()").unwrap(), 2);
 
-    // Step inside: the API now reads/writes the indoor index, still at its own untouched default.
     s.set_minimap_inside(true);
     assert_eq!(
         s.eval::<u8>("return m:GetZoom()").unwrap(),
@@ -118,7 +113,6 @@ fn minimap_indoor_and_outdoor_zoom_indices_are_independent() {
         mm.content
     );
 
-    // Step back outside: the outdoor zoom is exactly where we left it.
     s.set_minimap_inside(false);
     assert_eq!(
         s.eval::<u8>("return m:GetZoom()").unwrap(),
@@ -127,10 +121,8 @@ fn minimap_indoor_and_outdoor_zoom_indices_are_independent() {
     );
 }
 
-/// **The level persists** (decision 1131). `SetZoom` writes the live index *and* the matching CVar
-/// — `minimapInsideZoom` while inside a WMO, `minimapZoom` outside — the client's own `set_zoom` →
-/// `CVar::Set` pair, which is the whole reason a zoom survives a restart. The host push in the
-/// other direction (the seed) does *not* echo back as a change.
+/// `SetZoom` writes the live index and its CVar (`minimapInsideZoom` inside a WMO, `minimapZoom`
+/// outside), as the client's `set_zoom` calls `CVar::Set`; the host's seed does not echo back.
 #[test]
 fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     let mut s = script();
@@ -138,13 +130,11 @@ fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     s.run(r#"m = CreateFrame("Minimap", "TestMinimap")"#)
         .unwrap();
 
-    // The seed is a HOST write: it moves both live indices and queues nothing (the host is the
-    // one that just read them off disk — an echo would re-dirty the file it loaded).
+    // The seed is a host write: it moves both indices and queues nothing.
     s.set_minimap_zoom(1, 4);
     assert_eq!(s.eval::<u8>("return m:GetZoom()").unwrap(), 1);
     assert!(s.take_cvar_changes().is_empty(), "the seed must not echo");
 
-    // Outdoors, a zoom writes the outdoor CVar and only that one.
     s.run("m:SetZoom(5)").unwrap();
     assert_eq!(
         s.take_cvar_changes(),
@@ -152,7 +142,6 @@ fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     );
     assert_eq!(s.cvar("minimapInsideZoom").as_deref(), Some("3"));
 
-    // Indoors it writes the indoor one — the two levels persist separately, like the indices.
     s.set_minimap_inside(true);
     s.run("m:SetZoom(0)").unwrap();
     assert_eq!(
@@ -161,11 +150,11 @@ fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     );
     assert_eq!(s.cvar("minimapZoom").as_deref(), Some("5"));
 
-    // A no-op zoom queues nothing: quiet frames stay quiet, and the config stays clean.
+    // A no-op zoom queues nothing.
     s.run("m:SetZoom(0)").unwrap();
     assert!(s.take_cvar_changes().is_empty());
 
-    // The seed clamps like `set_zoom` does, so a hand-edited config.toml cannot seed out of range.
+    // The seed clamps like `set_zoom`.
     s.set_minimap_zoom(99, 99);
     s.set_minimap_inside(false);
     assert_eq!(
@@ -174,9 +163,7 @@ fn setzoom_persists_the_level_through_the_cvar_it_belongs_to() {
     );
 }
 
-/// A VM whose host registered nothing (a bare test harness, a glue-only run) still zooms — the
-/// engine-side CVar write is a silent no-op there, not a warning: engine writes are code, not UI
-/// content, so a miss means this build's host does not back the var.
+/// With no host CVars (a bare harness, a glue-only run) the engine-side write is a silent no-op.
 #[test]
 fn zooming_without_a_registered_cvar_table_is_silent() {
     let mut s = script();
@@ -190,17 +177,9 @@ fn zooming_without_a_registered_cvar_table_is_silent() {
     );
 }
 
-/// **The nine engine-created `Model` children, and why `[9]` is the player arrow.**
-///
-/// The `CMinimap` ctor `0x4edbc0` builds nine `CSimpleModel` children parented to the Minimap
-/// before anything else touches the widget, in three source-ordered groups (`__LINE__` 1424 / 1438
-/// / 1450 — wow-re `ui/scratch/widget-list-bindings.md` §5, VERIFIED), the last being
-/// `[Minimap+0x338]`, the player arrow. Because both linkers append at the tail and the ctor runs
-/// before the XML `<Frames>` descent, `({Minimap:GetChildren()})[9]` is that arrow on a stock
-/// client — which is exactly what Questie's `QuestieArrow.lua` and pfQuest's `compat/client.lua`
-/// index, unguarded, to read the player's heading.
-///
-/// This test is written the way those addons read it, not the way we store it.
+/// The `CMinimap` ctor (`0x4edbc0`) builds nine `CSimpleModel` children before the XML `<Frames>`
+/// descent, the last being the player arrow `[Minimap+0x338]`, so `({Minimap:GetChildren()})[9]`
+/// is the arrow; Questie and pfQuest read the player's heading from it.
 #[test]
 fn a_minimap_is_born_with_nine_model_children_and_the_ninth_is_the_player_arrow() {
     let mut s = script();
@@ -225,20 +204,17 @@ fn a_minimap_is_born_with_nine_model_children_and_the_ninth_is_the_player_arrow(
         )
         .unwrap());
 
-    // Questie's `GetPlayerFacing()`, verbatim. It is `0` until the app pushes, which is the
-    // client's own ctor default (`[frame+0x39c] = 0` at `0x76c92d`) — not nil, and not an error.
+    // Questie's `GetPlayerFacing()`; 0 until the app pushes, the ctor default (`0x76c92d`).
     s.run("function GetPlayerFacing() return ({Minimap:GetChildren()})[9]:GetFacing() end")
         .unwrap();
     s.run(r#"Minimap = m"#).unwrap();
     assert_eq!(s.eval::<f32>("return GetPlayerFacing()").unwrap(), 0.0);
 
-    // `SetPlayerFacing 0x4eb8e0` writes the argument into `[[minimap+0x338]+0x39c]` VERBATIM — no
-    // negation, no offset, no unit change (a `mov [ecx+0x39c],edx` of the dword it was handed).
+    // `SetPlayerFacing 0x4eb8e0` stores the argument into `[[minimap+0x338]+0x39c]` unchanged.
     s.set_minimap_player_facing(2.5);
     assert_eq!(s.eval::<f32>("return GetPlayerFacing()").unwrap(), 2.5);
 
-    // It reaches the arrow through the Minimap's own slot, so an addon appending its own child
-    // cannot displace it: a later `CreateFrame(_, _, Minimap)` lands at index 10.
+    // An addon's own child lands at index 10 and does not displace the arrow.
     s.run(r#"extra = CreateFrame("Frame", nil, m)"#).unwrap();
     s.set_minimap_player_facing(-1.25);
     assert_eq!(s.eval::<f32>("return GetPlayerFacing()").unwrap(), -1.25);
@@ -252,22 +228,15 @@ fn a_minimap_is_born_with_nine_model_children_and_the_ninth_is_the_player_arrow(
         "Frame"
     );
 
-    // The ctor only *constructs* them; the model files are `CMinimap::LoadXML 0x4ee2b0`'s to
-    // assign, so a Lua-built Minimap with no XML behind it has nine file-less Models — exactly as
-    // the reference does.
+    // The model files come from `CMinimap::LoadXML` (`0x4ee2b0`), so a Lua-built one has none.
     assert!(s
         .eval::<Option<String>>("return ({m:GetChildren()})[9]:GetModel()")
         .unwrap()
         .is_none_or(|p| p.is_empty()));
 }
 
-/// **`Minimap:SetMaskTexture` is state, and an empty path restores the default rather than
-/// unmasking the map.**
-///
-/// A real 1.12 method (the name is in the 5875 image) with no getter beside it, so the readback
-/// here is through the arena — the same shape `simplehtml`'s and `modelframe`'s tests use for a
-/// write-only verb. pfUI's `modules/minimap.lua:27` is the caller that matters: swapping this art
-/// is how its square minimap becomes square.
+/// A 1.12 method with no getter, so the test reads the arena; pfUI's `modules/minimap.lua:27`
+/// squares its minimap with it.
 #[test]
 fn set_mask_texture_is_state_and_empty_restores_the_default() {
     let s = script();
@@ -282,21 +251,17 @@ fn set_mask_texture_is_state_and_empty_restores_the_default() {
         Some("Interface\\AddOns\\pfUI\\img\\minimap")
     );
 
-    // Empty and nil both mean "back to the engine's circle" — never "no mask at all". A
-    // nil-means-unmasked reading would hand every mistyped path a silently square minimap.
+    // Empty and nil both restore the engine's circle, never "no mask".
     s.run(r#"m:SetMaskTexture("")"#).unwrap();
     assert_eq!(s.minimap_mask_texture(), None);
     s.run(r#"m:SetMaskTexture("Interface\\Foo") m:SetMaskTexture(nil)"#)
         .unwrap();
     assert_eq!(s.minimap_mask_texture(), None);
 
-    // There is no getter in 1.12, and we do not invent one (decision 1189).
     assert!(s.eval::<bool>("return m.GetMaskTexture == nil").unwrap());
 }
 
-/// `frame_effective_alpha` — the host-side read behind a frame whose pixels the app draws (the
-/// stock `MiniMapPing` model, 1974): `None` while hidden, or hidden through a parent; the
-/// effective alpha while effectively visible.
+/// The host-side alpha read for a frame the app draws itself, such as the stock `MiniMapPing`.
 #[test]
 fn frame_effective_alpha_reads_the_shown_frames_alpha() {
     let s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/tests/mod.rs b/crates/benilla-ui/src/script/tests/mod.rs
index 2c597e4f..035b35c9 100644
--- a/crates/benilla-ui/src/script/tests/mod.rs
+++ b/crates/benilla-ui/src/script/tests/mod.rs
@@ -1,8 +1,5 @@
-//! Rust-driven tests of the Lua host: the object model, layout+size reads, show/hide + event + tick
-//! firing (both RF-0025 conventions), the WoW stdlib (positional `format`, the aliases,
-//! `getglobal`), the sandbox holes, and an end-to-end extract in ZKey order.
-//!
-//! Split by subject; the shared `script()` fixture lives in [`common`].
+//! Rust-driven tests of the Lua host, one module per subject; the shared `script()` fixture lives
+//! in [`common`].
 
 mod addon_argument_abi;
 mod addon_index_space;
@@ -13,6 +10,7 @@ mod channel;
 mod common;
 mod cooldown;
 mod create_frame_template;
+mod dispatch_bench;
 mod end_to_end;
 mod events;
 mod font_object;
@@ -57,11 +55,6 @@ mod widget_surface;
 mod worldframe;
 mod worldmap;
 
-/// **A bounded chunk reports instead of hanging** — the guard decision 1247's hang called for.
-///
-/// Without it, a `while true do end` inside an addon takes the whole process with it, and every
-/// instrument downstream produces nothing at all: no roster, no columns, no error row. The bound
-/// turns that into an ordinary Lua error, which every caller already knows how to report.
 #[test]
 fn an_instruction_budget_turns_a_runaway_loop_into_an_error() {
     let s = crate::script::UiScript::new().unwrap();
@@ -80,9 +73,6 @@ fn an_instruction_budget_turns_a_runaway_loop_into_an_error() {
         s.instructions_used()
     );
 
-    // **The VM survives it.** The bound must not poison the interpreter — a survey has 217 more
-    // addons to run after the one that looped, and each gets its own VM only because this one
-    // returned at all.
     assert_eq!(
         s.eval::<i64>("return 2 + 3").unwrap(),
         5,
@@ -97,16 +87,10 @@ fn an_instruction_budget_turns_a_runaway_loop_into_an_error() {
     assert_eq!(t.eval::<i64>("return BudgetOk").unwrap(), 500_500);
 }
 
-/// **`GetBindLocation()` — the hearth location's name, `""` before the packet lands.**
-///
-/// Three corpus addons read it (FuBar_TransporterFu `TransporterFu.lua:456`, Necrosis
-/// `Necrosis.lua:1089`, _LazyPig `LazyPig.lua:623`), and the reference's own hearth confirmation
-/// formats it straight into the dialog (`StaticPopup.lua:1742`).
+/// The hearth location's name, `""` before the packet; `StaticPopup.lua:1742` formats it.
 #[test]
 fn get_bind_location_answers_the_pushed_name_and_never_nil() {
     let mut s = crate::script::UiScript::new().unwrap();
-    // Before the app pushes anything: the empty string, NOT nil. Necrosis concatenates the result,
-    // so nil would be a raise rather than a blank — the same choice `GetRealmName` beside it makes.
     assert_eq!(s.eval::<String>("return GetBindLocation()").unwrap(), "");
     assert_eq!(
         s.eval::<String>("return type(GetBindLocation())").unwrap(),
@@ -119,13 +103,11 @@ fn get_bind_location_answers_the_pushed_name_and_never_nil() {
         s.eval::<String>("return GetBindLocation()").unwrap(),
         "Stormwind City"
     );
-    // Concatenation is the idiom that matters, so it is the one asserted.
     assert_eq!(
         s.eval::<String>(r#"return "Bound: " .. GetBindLocation()"#)
             .unwrap(),
         "Bound: Stormwind City"
     );
-    // A re-bind replaces it rather than accumulating.
     s.set_bind_location("Ironforge");
     assert_eq!(
         s.eval::<String>("return GetBindLocation()").unwrap(),
@@ -133,19 +115,13 @@ fn get_bind_location_answers_the_pushed_name_and_never_nil() {
     );
 }
 
-/// **`RequestTimePlayed()` queues the ask; `TIME_PLAYED_MSG` carries the answer.**
-///
-/// The two halves are one feature: `QuestHistory` calls the verb and then waits on the event, so
-/// shipping the request alone would be 1203 — an addon waiting forever is quieter and worse than
-/// the `attempt to call global` it got before.
+/// `RequestTimePlayed()` queues the ask; `TIME_PLAYED_MSG` carries the answer.
 #[test]
 fn request_time_played_queues_an_ask_and_the_answer_arrives_as_an_event() {
     let mut s = crate::script::UiScript::new().unwrap();
 
-    // The verb returns NOTHING — the answer is an event, never a return value.
     assert_eq!(s.arity("RequestTimePlayed()").unwrap(), 0);
-    // …and that call queued one ask. A COUNT, not a payload: the packet is empty, so two asks in a
-    // frame are two sends rather than one collapsed intent (the pvp queue's rule).
+    // A count, not a latch: the packet is empty, so two asks in a frame are two sends.
     s.run("RequestTimePlayed() RequestTimePlayed()").unwrap();
     assert_eq!(
         s.take_played_time_asks(),
@@ -154,7 +130,6 @@ fn request_time_played_queues_an_ask_and_the_answer_arrives_as_an_event() {
     );
     assert_eq!(s.take_played_time_asks(), 0, "the drain empties the queue");
 
-    // The answer half: the app fires the event with (total, level) in seconds.
     s.run(
         r#"
         TPSeen = nil
@@ -178,9 +153,7 @@ fn request_time_played_queues_an_ask_and_the_answer_arrives_as_an_event() {
     );
 }
 
-/// **The engine hands caught script errors to the CHOSEN Lua error handler** (decision 1305) —
-/// the reference's `seterrorhandler` contract, which is how `_ERRORMESSAGE`'s dialog (or an
-/// addon's own ImprovedErrorFrame-style handler) ever hears about a failure the engine caught.
+/// `seterrorhandler`'s contract: an engine-caught script error goes to the chosen handler.
 #[test]
 fn a_chosen_error_handler_hears_engine_caught_errors_and_the_default_does_not_duplicate() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -192,8 +165,7 @@ fn a_chosen_error_handler_hears_engine_caught_errors_and_the_default_does_not_du
     )
     .unwrap();
 
-    // Nobody chose a handler: the error lands on the host channel ONCE, and the dispatch —
-    // recognising the stdlib default by identity — adds nothing.
+    // With the stdlib default handler, recognised by identity, the dispatch adds nothing.
     s.fire_event("B271_PROBE", vec![]);
     s.dispatch_script_errors_to_handler();
     let errors = s.take_errors();
@@ -203,8 +175,7 @@ fn a_chosen_error_handler_hears_engine_caught_errors_and_the_default_does_not_du
         "one error, once — the default handler must not double-report: {errors:?}"
     );
 
-    // An addon chose one: the dispatch fires it with the message, and the host channel STILL
-    // records the error (the dual channel is what keeps the harness's instruments sighted).
+    // A chosen handler gets the message, and the host channel still records it.
     s.run("caught = {} seterrorhandler(function(msg) table.insert(caught, msg) end)")
         .unwrap();
     s.fire_event("B271_PROBE", vec![]);
@@ -225,8 +196,46 @@ fn a_chosen_error_handler_hears_engine_caught_errors_and_the_default_does_not_du
     );
 }
 
-/// **A handler that itself raises cannot recurse the error path** — its failure is recorded on
-/// the host channel only, never re-queued, and the batch stops on the first handler failure.
+#[test]
+fn a_widget_handler_error_reaches_the_chosen_error_handler() {
+    let mut s = crate::script::UiScript::new().unwrap();
+    s.set_screen_size(1024.0, 768.0);
+    s.run(
+        "caught = {} seterrorhandler(function(m) table.insert(caught, m) end) \
+         local b = CreateFrame('Button') \
+         b:SetScript('OnClick', function() error('click boom') end) \
+         b:Click() \
+         local sl = CreateFrame('Slider') \
+         sl:SetMinMaxValues(0, 10) \
+         sl:SetScript('OnValueChanged', function() error('slide boom') end) \
+         sl:SetValue(5)",
+    )
+    .unwrap();
+    s.dispatch_script_errors_to_handler();
+    let caught = s
+        .eval::<String>("return table.concat(caught, ' | ')")
+        .unwrap();
+    assert!(caught.contains("click boom"), "OnClick: {caught}");
+    assert!(caught.contains("slide boom"), "OnValueChanged: {caught}");
+}
+
+/// `fire_global` carries `UPDATE_FACTION` from the faction-header verbs.
+#[test]
+fn a_self_unregistering_listener_does_not_rob_its_successor_on_the_internal_dispatch() {
+    let s = crate::script::UiScript::new().unwrap();
+    s.run(
+        r#"log = ""
+        local a = CreateFrame("Frame") a:RegisterEvent("UPDATE_FACTION")
+        a:SetScript("OnEvent", function() log = log .. "a" this:UnregisterEvent("UPDATE_FACTION") end)
+        local b = CreateFrame("Frame") b:RegisterEvent("UPDATE_FACTION")
+        b:SetScript("OnEvent", function() log = log .. "b" end)
+        ExpandFactionHeader(0)"#,
+    )
+    .unwrap();
+    assert_eq!(s.eval::<String>("return log").unwrap(), "ab");
+}
+
+/// The handler's own failure goes to the host channel only, never re-queued; the batch stops.
 #[test]
 fn an_error_handler_that_errors_does_not_recurse() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -251,7 +260,6 @@ fn an_error_handler_that_errors_does_not_recurse() {
             .any(|e| e.contains("error handler itself failed")),
         "and so is the handler's own failure, named as such: {errors:?}"
     );
-    // A second dispatch finds an EMPTY queue — the handler's failure was never re-queued.
     s.dispatch_script_errors_to_handler();
     assert!(
         s.take_errors().is_empty(),
diff --git a/crates/benilla-ui/src/script/tests/model_clock.rs b/crates/benilla-ui/src/script/tests/model_clock.rs
index 512a7fd0..2420bda3 100644
--- a/crates/benilla-ui/src/script/tests/model_clock.rs
+++ b/crates/benilla-ui/src/script/tests/model_clock.rs
@@ -1,16 +1,5 @@
-//! **The model pane's clock, arm, and two handlers** (decision 2007; wow-re
-//! `ui/scratch/modelframe-render-law.md` §4).
-//!
-//! A `<Model>` widget owns a private scene whose clock its own `OnUpdate` advances while the
-//! frame is visible; `SetSequence`/`SetSequenceTime` arm a sequence with an anchor the sampler
-//! re-reads; `OnUpdateModel` fires at the top of every paint and `OnAnimFinished` from the
-//! completion of a clamped sequence. Every one of those is Lua-observable — the shipped cooldown
-//! sweep is nothing but those handlers driving `SetSequenceTime` — so the law is tested here
-//! against the stock `Cooldown.lua`, transcribed verbatim.
-//!
-//! The engine parses no M2, so a file's sequences and bounds are **facts** the host hands over
-//! ([`ModelFileFacts`]); these tests hand over the facts `benilla-extract m2seq` reads off the
-//! shipped files.
+//! The model pane's clock, sequence arm and handlers (`0x76d7f0`, `0x7121a0`, `0x76cac0`). The
+//! engine parses no M2: a file's sequences and bounds are [`ModelFileFacts`] the host hands over.
 
 use super::common::script;
 use crate::script::{Model, UiScript};
@@ -32,15 +21,13 @@ fn facts(rows: &[(u16, u32, bool)]) -> ModelFileFacts {
     }
 }
 
-/// `UI-Cooldown-Indicator.m2` (`m2seq`): seq 0 = id 0, 1000 ms, clamp; seq 1 = id 1, 1000 ms,
-/// clamp.
+/// `UI-Cooldown-Indicator.m2`'s sequences as `m2seq` reads them.
 const COOLDOWN_FILE: &str = r"Interface\Cooldown\UI-Cooldown-Indicator.mdx";
 fn cooldown_facts() -> ModelFileFacts {
     facts(&[(0, 1000, false), (1, 1000, false)])
 }
 
-/// `MinimapPing.m2` (`m2seq`): seq 0 = id 127, 1333 ms, clamp; seq 1 = id 0, 833 ms, LOOP; seq
-/// 2 = id 1, 333 ms, clamp. `SetSequence(0)` is the looping one.
+/// `MinimapPing.m2`'s sequences as `m2seq` reads them; `SetSequence(0)` is the looping one.
 const PING_FILE: &str = r"Interface\MiniMap\Ping\MinimapPing.mdx";
 fn ping_facts() -> ModelFileFacts {
     facts(&[(127, 1333, false), (0, 833, true), (1, 333, false)])
@@ -64,9 +51,7 @@ fn play_head(s: &UiScript, name: &str, path: &str) -> Option<(u16, u32)> {
     m.play_head(facts).map(|p| (p.anim_id, p.cursor_ms))
 }
 
-/// The widget's `OnUpdate` (`0x76d7f0`) advances the scene clock by `trunc(elapsed · 1000)` —
-/// only while the frame is visible (the UI pump walks visible frames), so a hidden pane's clock
-/// stands still and a re-shown pane resumes where it stopped.
+/// `OnUpdate` (`0x76d7f0`) adds `trunc(elapsed · 1000)` ms, for visible frames only.
 #[test]
 fn the_clock_runs_only_while_the_pane_is_shown_and_truncates() {
     let mut s = script();
@@ -97,20 +82,18 @@ fn the_clock_runs_only_while_the_pane_is_shown_and_truncates() {
         "re-shown: resumes where it stopped"
     );
 
-    // The looping sequence wraps on its 833 ms and never completes.
+    // The looping sequence wraps on its 833 ms.
     assert_eq!(play_head(&s, "Ping", PING_FILE), Some((0, 616)));
     s.tick(0.5); // clock 1116 → 1116 mod 833
     assert_eq!(play_head(&s, "Ping", PING_FILE), Some((0, 283)));
 }
 
-/// `SetModel` runs the loader's completion (`0x70ebd0`) — arm **Stand** (id 0 if the file owns
-/// it, else `animations[0]`'s id), variation 0 — synchronously when the facts are known, and when
-/// they land otherwise; until then the pane is a waiter and the host is asked for the file.
+/// The loader's completion (`0x70ebd0`) arms Stand (id 0 if the file owns it, else
+/// `animations[0]`'s id), at `SetModel` when the facts are known or when they land.
 #[test]
 fn set_model_seeds_stand_now_or_when_the_facts_land() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
-    // Facts first: the arm is immediate.
     s.set_model_facts(COOLDOWN_FILE, cooldown_facts());
     s.run(&format!(
         r#"a = CreateFrame("Model", "Known", UIParent) a:SetModel("{}")"#,
@@ -126,7 +109,6 @@ fn set_model_seeds_stand_now_or_when_the_facts_land() {
     );
     assert_eq!(play_head(&s, "Known", COOLDOWN_FILE), Some((0, 0)));
 
-    // Facts unknown: a waiter, and the file goes on the host's list once.
     s.run(&format!(
         r#"b = CreateFrame("Model", "Waiting", UIParent) b:SetModel("{0}")
            c = CreateFrame("Model", "Waiting2", UIParent) c:SetModel("{0}")"#,
@@ -142,7 +124,6 @@ fn set_model_seeds_stand_now_or_when_the_facts_land() {
     );
     assert!(s.model_facts_wanted().is_empty(), "drained");
 
-    // The facts land: every waiter holding the file arms its Stand at its own clock.
     s.tick(0.25);
     s.set_model_facts(PING_FILE, ping_facts());
     for name in ["Waiting", "Waiting2"] {
@@ -155,7 +136,6 @@ fn set_model_seeds_stand_now_or_when_the_facts_land() {
         );
     }
 
-    // A file that does not own id 0 seeds `animations[0]`'s own id.
     s.set_model_facts(
         r"Interface\Odd.mdx",
         facts(&[(204, 500, true), (166, 500, true)]),
@@ -165,9 +145,7 @@ fn set_model_seeds_stand_now_or_when_the_facts_land() {
     assert_eq!(pane(&s, "Odd").armed.map(|a| a.anim_id), Some(204));
 }
 
-/// `SetSequence(id)` with an id the file does not own **stops what was playing and arms
-/// nothing** — `0x7121a0`'s interrupt runs before its bounds check (§4.2). A queued arm on a
-/// file still loading is kept until the facts say otherwise.
+/// `0x7121a0` interrupts the track before its bounds check; a queued arm waits for the facts.
 #[test]
 fn an_unowned_id_stops_the_track_and_arms_nothing() {
     let mut s = script();
@@ -183,7 +161,6 @@ fn an_unowned_id_stops_the_track_and_arms_nothing() {
     assert_eq!(pane(&s, "P").sequence, 42, "the raw id is still recorded");
     assert!(pane(&s, "P").armed.is_none(), "…but nothing plays");
 
-    // Queued on an unloaded file, then refused when the facts land.
     s.run(r#"q = CreateFrame("Model", "Q", UIParent) q:SetModel("Interface\\Late.mdx") q:SetSequence(7)"#)
         .unwrap();
     assert_eq!(
@@ -198,8 +175,7 @@ fn an_unowned_id_stops_the_track_and_arms_nothing() {
          own — nothing plays"
     );
 
-    // The other order of the same replay: a queued arm the file DOES own wins over the seed,
-    // at its original offset, re-anchored on the clock the file landed on.
+    // A queued arm the file owns wins over the seed, re-anchored on the landing clock.
     s.run(r#"r = CreateFrame("Model", "R", UIParent) r:SetModel("Interface\\Later.mdx") r:SetSequenceTime(5, 40)"#)
         .unwrap();
     s.tick(0.3);
@@ -211,17 +187,13 @@ fn an_unowned_id_stops_the_track_and_arms_nothing() {
     assert_eq!((a.anim_id, a.armed_at_ms, a.anchor_ms), (5, 300, 300 - 40));
 }
 
-/// The shipped cooldown, on the two handlers and nothing else — `Cooldown.lua` verbatim:
-/// `SetTimer` arms sequence 0 and shows; every paint `OnUpdateModel` scrubs
-/// `SetSequenceTime(0, elapsed/duration · 1000)` until done, then flips to sequence 1 at 0; the
-/// flash's completion (`OnAnimFinished`, 1000 ms later) hides the frame.
+/// The stock `Cooldown.lua`, which runs on `OnUpdateModel` and `OnAnimFinished` alone.
 #[test]
 fn the_cooldown_machine_runs_on_the_two_handlers() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     s.set_model_facts(COOLDOWN_FILE, cooldown_facts());
-    // `SetTimer`'s gate is `start > 0`: a session clock still at 0 refuses the timer, as the
-    // reference's would — so the session is a second old before the button is pressed.
+    // `SetTimer` gates on `start > 0`, so the session clock must be past 0.
     s.tick(1.0);
     s.run(&format!(
         r#"
@@ -272,22 +244,18 @@ fn the_cooldown_machine_runs_on_the_two_handlers() {
     assert!(s.frame_visible("CD"));
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((0, 0)));
 
-    // The sweep: each paint scrubs sequence 0 to the elapsed fraction.
     s.tick(0.5);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((0, 250)));
     s.tick(1.0);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((0, 750)));
-    // A scrub is an ANCHOR, not a freeze: between two paints the clock runs on from it. The
-    // cooldown never sees that (it re-scrubs every paint), the ping relies on it.
+    // A scrub is an anchor, not a freeze: between paints the clock runs on from it.
     assert_eq!(pane(&s, "CD").armed.map(|a| a.anchor_ms), Some(1500 - 750));
 
-    // Done: the flip to the flash, sequence 1 at 0.
     s.tick(0.6);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((1, 0)));
     assert!(s.frame_visible("CD"));
     assert_eq!(s.eval::<i64>("return cd.stopping").unwrap(), 1);
 
-    // The flash runs its 1000 ms; the completion fires once, and the handler hides the frame.
     s.tick(0.5);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((1, 500)));
     assert!(s.eval::<bool>("return table.getn(fired) == 0").unwrap());
@@ -301,15 +269,13 @@ fn the_cooldown_machine_runs_on_the_two_handlers() {
         !s.frame_visible("CD"),
         "…which the stock handler turns into Hide()"
     );
-    // Hidden: no paint, no second completion, the cursor holds at the end.
     s.tick(1.0);
     assert_eq!(s.eval::<i64>("return table.getn(fired)").unwrap(), 1);
     assert_eq!(play_head(&s, "CD", COOLDOWN_FILE), Some((1, 1000)));
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `OnUpdateModel` runs with `this` set, once per paint of a **visible** pane, before the
-/// completion is read — so a handler that re-arms in the same paint completes nothing.
+/// `OnUpdateModel` runs before the completion is read, so re-arming each paint completes nothing.
 #[test]
 fn on_update_model_fires_per_visible_paint_with_this() {
     let mut s = script();
@@ -342,7 +308,6 @@ fn on_update_model_fires_per_visible_paint_with_this() {
         2,
         "no paint while hidden"
     );
-    // Re-arming every paint keeps the clamped sequence from ever completing.
     s.run("M:Show() M:SetScript(\"OnUpdateModel\", function() this:SetSequenceTime(1, 0) end)")
         .unwrap();
     for _ in 0..30 {
@@ -351,10 +316,8 @@ fn on_update_model_fires_per_visible_paint_with_this() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A LOOPING sequence fires `OnAnimFinished` once too — at the end of its first pass — and keeps
-/// looping (`0x719370` enqueues the completion before it tests the loop flag; wow-re
-/// `modelframe-texanim-and-sequence-law.md` Q4). And a pane with no file fires no
-/// `OnUpdateModel` at all (`76d24c`'s gate), however visible.
+/// `0x719370` enqueues the completion before it tests the loop flag, so a loop's first pass fires
+/// `OnAnimFinished`; a pane with no file fails `0x76d24c`'s gate and never paints.
 #[test]
 fn a_loop_completes_once_and_a_fileless_pane_paints_nothing() {
     let mut s = script();
@@ -410,14 +373,13 @@ fn a_loop_completes_once_and_a_fileless_pane_paints_nothing() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The implicit rect** (decision 2015): a model pane that authored no size takes its file's
-/// bounding-box extent in LAYOUT units — `768·√(a²+1)` FrameXML units per unit, `1280` at 4:3
-/// — the moment the facts are known; it follows the screen's aspect; an authored size wins.
+/// A pane with no authored size takes its file's bounding box in layout units, `768·√(a²+1)`
+/// FrameXML units each (1280 at 4:3), following the screen's aspect.
 #[test]
 fn a_size_less_pane_takes_its_files_rect_in_layout_units() {
     let mut s = script();
     s.set_screen_size(1024.0, 768.0);
-    // The map arrow's own box (`MinimapArrow.m2`, render law §2): 0.0262 × 0.0263 units.
+    // The map arrow's own box (`MinimapArrow.m2`, `0x76d080`/`0x76d0d0`): 0.0262 × 0.0263 units.
     let arrow = |s: &mut UiScript| {
         s.set_model_facts(
             r"Interface\Minimap\MinimapArrow.mdx",
@@ -464,7 +426,7 @@ fn a_size_less_pane_takes_its_files_rect_in_layout_units() {
     assert_eq!((bw, bh), (50.0, 20.0), "an authored size is untouched");
     assert!(pane(&s, "Sized").implicit_size && !pane(&s, "Authored").implicit_size);
 
-    // 16:9 — a layout unit is 768·√((16/9)²+1) = 1566.4 FrameXML units.
+    // At 16:9 a layout unit is 768·√((16/9)²+1) = 1566.4 FrameXML units.
     s.set_screen_size(1600.0, 900.0);
     s.resolve();
     let w: f32 = s.eval("return Sized:GetWidth()").unwrap();
@@ -478,9 +440,7 @@ fn a_size_less_pane_takes_its_files_rect_in_layout_units() {
     assert_eq!(s.eval::<f32>("return Sized:GetWidth()").unwrap(), 10.0);
 }
 
-/// `ReplaceIconTexture` is the type-14 texture override on the INSTANCE: stored over a file
-/// (queued and replayed while it streams), dropped with no file, released by `SetModel` and
-/// `ClearModel`.
+/// The type-14 texture override belongs to the model instance and dies with it.
 #[test]
 fn replace_icon_texture_lives_and_dies_with_the_instance() {
     let mut s = script();
@@ -524,8 +484,7 @@ fn replace_icon_texture_lives_and_dies_with_the_instance() {
     );
 }
 
-/// The XML `scale=` on a model pane is the MODEL's scale (`0x76cac0` → `+0x3a0`), never the
-/// frame's — the cooldown template's 0.75 must not shrink the widget's rect.
+/// A model pane's XML `scale=` is the model's scale (`0x76cac0`, `+0x3a0`), never the frame's.
 #[test]
 fn the_model_scale_attribute_is_the_models_own() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/modelframe.rs b/crates/benilla-ui/src/script/tests/modelframe.rs
index b2709aad..9c0bbbd9 100644
--- a/crates/benilla-ui/src/script/tests/modelframe.rs
+++ b/crates/benilla-ui/src/script/tests/modelframe.rs
@@ -1,22 +1,9 @@
-//! **The model-pane family's Lua surface** — `Model` and `PlayerModel`, read back through the API
-//! that wrote them.
-//!
-//! The property under test throughout is that these widgets are *state the app renders*, not state
-//! the engine interprets: every setter's value must come back out unchanged, and the places where
-//! the widget does have an opinion (one yaw slot written by two verbs on two classes; content being
-//! an either/or) must hold.
-//!
-//! Plus the one structural property, guarded as a whole block:
-//! [`the_two_model_tables_are_the_references_own`] asserts our surfaces against the reference's
-//! enumerated tables in **both** directions, so neither a missing verb nor an invented one can slip
-//! past — and so `Model` can never re-acquire the three that are `PlayerModel`'s.
+//! The `Model` and `PlayerModel` Lua surface, read back through the API that wrote it, and checked
+//! against the reference's method tables in both directions.
 
 use super::common::script;
 use crate::script::UiScript;
 
-/// The whole scene, set and read back — plus the widget's three actual behaviours: `SetRotation`
-/// and `SetFacing` are one slot, `SetModel` and `SetUnit` displace each other, and `ClearModel`
-/// empties both.
 #[test]
 fn the_model_pane_holds_the_scene_it_was_given() {
     let mut s = script();
@@ -24,8 +11,7 @@ fn the_model_pane_holds_the_scene_it_was_given() {
     s.run(r#"m = CreateFrame("Model", "MPane", UIParent)"#)
         .unwrap();
 
-    // A fresh pane: no content, unit SCALE (not zero — a model at scale 0 is invisible, which is
-    // why ModelState hand-writes its Default), no yaw, at the origin.
+    // A fresh pane: no model, scale 1 (not 0, which would draw nothing), no yaw.
     assert_eq!(
         s.eval::<(Option<String>, f64, f64)>(
             "return MPane:GetModel(), MPane:GetModelScale(), MPane:GetFacing()"
@@ -35,8 +21,7 @@ fn the_model_pane_holds_the_scene_it_was_given() {
         "a fresh pane has no model and unit scale"
     );
 
-    // The path round-trips verbatim — the client's own path space, backslashes and `.mdx` intact.
-    // pfUI's autocast shine is exactly this call.
+    // The path round-trips verbatim, backslashes and `.mdx` intact (pfUI's autocast shine).
     s.run(r#"MPane:SetModel("Interface\\Buttons\\UI-AutoCastButton.mdx")"#)
         .unwrap();
     assert_eq!(
@@ -44,12 +29,10 @@ fn the_model_pane_holds_the_scene_it_was_given() {
         r"Interface\Buttons\UI-AutoCastButton.mdx"
     );
 
-    // The yaw. `SetFacing` is the `Model` verb for it (`0x878948[4]`); `SetRotation` writes the
-    // same field but belongs to `PlayerModel` and is tested there.
+    // `SetFacing` is the `Model` yaw verb (`0x878948[4]`).
     s.run("MPane:SetFacing(-0.25)").unwrap();
     assert_eq!(s.eval::<f64>("return MPane:GetFacing()").unwrap(), -0.25);
 
-    // Scale, camera, position — plain storage, read back through their own getters.
     s.run("MPane:SetModelScale(0.4) MPane:SetCamera(2) MPane:SetPosition(0.1, -0.2, 3)")
         .unwrap();
     assert_eq!(
@@ -63,8 +46,6 @@ fn the_model_pane_holds_the_scene_it_was_given() {
         "GetPosition returns the three numbers SetPosition took"
     );
 
-    // `SetModel(nil)` is the documented clear and reaches the same place `ClearModel` does — not
-    // everything in the corpus calls the dedicated verb.
     s.run("MPane:ClearModel()").unwrap();
     assert_eq!(
         s.eval::<Option<String>>("return MPane:GetModel()").unwrap(),
@@ -72,16 +53,9 @@ fn the_model_pane_holds_the_scene_it_was_given() {
     );
 }
 
-/// **A `<PlayerModel>` is a `<Model>` plus exactly three verbs — and the inheritance runs one way.**
-///
-/// The client registers four model-pane types and each has its own Lua method table that never
-/// repeats its base's; a derived pane reaches its base through the miss leg of `vtable+0x8`
-/// (wow-re `ui/scratch/model-pane-method-tables.md` §3). So `PlayerModel`'s three-entry table
-/// `0x84f1fc` must sit *over* `Model`'s 23-entry `0x878948`, and nothing may chain the other way:
-/// `CSimpleModel`'s lookup `0x76f870` has no leg into `CGCharacterModelBase`'s `0x506260`.
-///
-/// This is the shape pfUI's unit frames need — `CreateFrame("PlayerModel", ...)` driven by
-/// `SetUnit` + `SetCamera`, one verb from each table on the same frame.
+/// Each model-pane type has its own method table and reaches its base's through the miss leg of
+/// `vtable+0x8` (`0x7020b0`): `PlayerModel`'s three (`0x84f1fc`) sit over `Model`'s 23
+/// (`0x878948`), and `CSimpleModel`'s lookup `0x76f870` has no leg into `0x506260`.
 #[test]
 fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
     let mut s = script();
@@ -94,7 +68,6 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
     )
     .unwrap();
 
-    // Its own three resolve on the PlayerModel...
     for verb in ["SetUnit", "RefreshUnit", "SetRotation"] {
         assert_eq!(
             s.eval::<String>(&format!("return type(PMPane.{verb})"))
@@ -102,8 +75,6 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
             "function",
             "PlayerModel must answer its own {verb}"
         );
-        // ...and on the plain Model they are ABSENT. This is the assertion that would have caught
-        // three years of `SetUnit` published on the wrong class.
         assert_eq!(
             s.eval::<String>(&format!("return type(MOnly.{verb})"))
                 .unwrap(),
@@ -112,7 +83,7 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
         );
     }
 
-    // ...and the base's verbs resolve through the chain, unrepeated. pfUI's portrait line.
+    // pfUI's portrait line: `SetUnit`, then the base's `SetCamera` through the chain.
     s.run(r#"PMPane:SetUnit("player") PMPane:SetCamera(0)"#)
         .unwrap();
     assert_eq!(
@@ -129,8 +100,7 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
         "...and back the other way, the direction an addon reskinning a paper doll takes"
     );
 
-    // `SetRotation` writes THE SAME yaw field `SetFacing` does — `0x505bb0`'s last instruction is
-    // `mov [esi+0x39c], eax`, and `+0x39c` is what `0x76dce0` writes. `GetFacing` reads either.
+    // `SetRotation` (`0x505bb0`) and `SetFacing` (`0x76dce0`) write the same yaw field, `+0x39c`.
     s.run("PMPane:SetRotation(1.5)").unwrap();
     assert_eq!(s.eval::<f64>("return PMPane:GetFacing()").unwrap(), 1.5);
     s.run("PMPane:SetFacing(-0.25)").unwrap();
@@ -140,12 +110,11 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
         "one slot: SetFacing overwrites what SetRotation wrote"
     );
 
-    // RefreshUnit is a live no-op: the pane stores the unit TOKEN and resolves it at render, so
-    // there is no cached appearance to invalidate. It must still exist — the reference's own
-    // DressUp/PaperDoll frames call it, so an addon hooking them will too.
+    // `RefreshUnit` is a no-op, as the pane resolves its unit token at render; stock
+    // `PaperDollFrame.xml:221` calls it.
     assert!(s.run("PMPane:RefreshUnit()").is_ok());
 
-    // ClearModel — a `Model` verb reached through the chain — empties BOTH content slots.
+    // `ClearModel`, reached through the chain, empties both content slots.
     s.run(r#"PMPane:SetUnit("player") PMPane:ClearModel()"#)
         .unwrap();
     assert_eq!(
@@ -155,19 +124,8 @@ fn a_player_model_is_a_model_plus_three_and_the_chain_runs_one_way() {
     );
 }
 
-/// **`SetModel(nil)` raises; `ClearModel()` clears. They are not the same verb.**
-///
-/// This binding asserted the opposite until 2026-08-30 — "the documented clear, and how the corpus
-/// writes 'no model'" — which was invented, not read. `0x76d950` is shape A (decision 1717's
-/// taxonomy): `lua_isstring` gates the argument and `Usage: %s:SetModel("file")` is raised on
-/// anything that is not a string or a number. `ClearModel 0x76db20` is a separate table entry.
-///
-/// The same gate on `ReplaceIconTexture 0x76ed70`, whose *whole* observable behaviour it is: the
-/// swap itself lands on a `CM2Model` we do not have, and with no CM2Model the reference drops the
-/// call and never replays it.
-///
-/// A NUMBER is accepted by both — `lua_isstring` takes tags 3|4 and the client renders it to
-/// decimal text — which is the half a `Value::String`-only match would get wrong.
+/// `SetModel` (`0x76d950`) and `ReplaceIconTexture` (`0x76ed70`) gate on `lua_isstring`, raising
+/// their usage string on anything but a string or a number; `ClearModel` (`0x76db20`) is the clear.
 #[test]
 fn the_string_setters_gate_their_argument_and_a_number_is_a_string() {
     let mut s = script();
@@ -183,26 +141,23 @@ fn the_string_setters_gate_their_argument_and_a_number_is_a_string() {
             "SetModel({bad}) must raise — it is not the clear"
         );
     }
-    // ...and none of those raises disturbed the path that was already set.
     assert_eq!(
         s.eval::<String>("return GateM:GetModel()").unwrap(),
         r"Interface\Buttons\A.mdx",
         "a raised setter leaves the pane alone"
     );
-    // A number IS a string to `lua_isstring`, and the client renders it to decimal text.
+    // A number passes `lua_isstring` and is stored as its decimal text.
     s.run("GateM:SetModel(42)").unwrap();
     assert_eq!(s.eval::<String>("return GateM:GetModel()").unwrap(), "42");
 
-    // ClearModel is the clear, takes no argument, and empties the pane.
     s.run("GateM:ClearModel()").unwrap();
     assert_eq!(
         s.eval::<Option<String>>("return GateM:GetModel()").unwrap(),
         None
     );
 
-    // `ReplaceIconTexture` — same gate, and that gate is all of it. A good argument is accepted
-    // and changes NOTHING observable: the swap targets the CM2Model's type-14 textures, and a
-    // pane with no CM2Model drops the call (the reference's own `[widget+0x318] == 0` leg).
+    // `ReplaceIconTexture` swaps the CM2Model's type-14 textures, and a pane with none
+    // (`[widget+0x318] == 0`) drops the call, so only the gate is observable.
     for bad in ["nil", "{}", "true", ""] {
         assert!(
             s.run(&format!("GateM:ReplaceIconTexture({bad})")).is_err(),
@@ -219,7 +174,7 @@ fn the_string_setters_gate_their_argument_and_a_number_is_a_string() {
         "it is a MATERIAL swap, not a content setter — the pane's model is untouched"
     );
 
-    // `AdvanceTime` takes nothing, returns nothing, and does nothing — verified, not stubbed.
+    // The reference's `AdvanceTime` takes nothing, returns nothing and does nothing.
     assert_eq!(
         s.eval::<usize>("return table.getn({ GateM:AdvanceTime() })")
             .unwrap(),
@@ -228,25 +183,11 @@ fn the_string_setters_gate_their_argument_and_a_number_is_a_string() {
     );
 }
 
-/// **The whole block, both directions** — decision 1718's rule applied to the two model tables.
-///
-/// The lists below are the reference's OWN enumerations, transcribed entry-for-entry from
-/// wow-re's `ui/scratch/model-pane-method-tables.md` §2.1 and §2.2 (each table's count fixed twice:
-/// the registering `mov edx, imm32`, and the dword at `base + 8*count` being the start of the
-/// string pool). They are **not** the names anyone noticed were missing — that is exactly the
-/// mistake 1718 records, and it was re-made inside the test written to enforce it.
-///
-/// Guarding both directions is the point:
-///
-/// - **no gap** — every reference name we claim to publish must resolve;
-/// - **no superset** — a name the reference does not have on a table must not resolve there
-///   (1189: a name we have and the reference lacks routes an addon down a path the real client
-///   never takes);
-/// - **the `UNBUILT` set must stay absent** — it is empty since 2027, so "unbuilt" cannot
-///   quietly become "stubbed" without this test being edited to say so.
+/// The reference's own method tables, entry for entry (`Model` `0x878948`, `PlayerModel`
+/// `0x84f1fc`), checked both ways: every name resolves, and a name a table lacks does not.
 #[test]
 fn the_two_model_tables_are_the_references_own() {
-    /// `Model` — `CSimpleModel`, table `0x878948`, 23 entries, in table order.
+    /// `Model`, `CSimpleModel`'s table `0x878948`, in table order.
     const MODEL_23: [&str; 23] = [
         "SetModel",
         "GetModel",
@@ -272,14 +213,9 @@ fn the_two_model_tables_are_the_references_own() {
         "GetFogFar",
         "ClearFog",
     ];
-    /// `PlayerModel` — `CGCharacterModelBase`, table `0x84f1fc`, 3 entries, in table order.
+    /// `PlayerModel`, `CGCharacterModelBase`'s table `0x84f1fc`, in table order.
     const PLAYERMODEL_3: [&str; 3] = ["SetUnit", "RefreshUnit", "SetRotation"];
-    /// The subset of [`MODEL_23`] this client does not build. Named, not stubbed (1134 §4).
-    /// **Empty since decision 2027** — the last five were the fog near/far set, held back only
-    /// because `ClearFog`'s effect on the colour/near/far triple was uncarved; the render law
-    /// (§5.4) reads it as `76f5c5 and [edi+0x3a4],-2`, bit 0 alone, so the guess is gone and the
-    /// verbs are real. Kept as an empty array rather than deleted: the wall below is the thing
-    /// that notices when a name arrives or leaves.
+    /// The names in [`MODEL_23`] this client leaves unbuilt, absent rather than stubbed: none.
     const UNBUILT: [&str; 0] = [];
 
     let mut s = script();
@@ -299,7 +235,7 @@ fn the_two_model_tables_are_the_references_own() {
 
     for name in MODEL_23 {
         let want = !UNBUILT.contains(&name);
-        // A `Model` verb resolves on BOTH panes — on the PlayerModel through the chain.
+        // A `Model` verb resolves on both panes, on the PlayerModel through the chain.
         for frame in ["GuardM", "GuardPM"] {
             assert_eq!(
                 is_fn(&s, frame, name),
@@ -318,9 +254,7 @@ fn the_two_model_tables_are_the_references_own() {
             "GuardM.{name}: 0x84f1fc is NOT reachable from CSimpleModel's lookup"
         );
     }
-    // The two names a `strings` scan of the model band would tempt anyone into, which do not exist
-    // in 5875 in ANY form (substring scan of the mapped image returns 0, positive control 27 hits
-    // for `Creature`). They are later-expansion verbs; publishing one is decision 1189's error.
+    // Later-expansion verbs, absent from the 1.12 client image in any form.
     for name in ["SetCreature", "SetCustomRace"] {
         for frame in ["GuardM", "GuardPM"] {
             assert!(
@@ -331,11 +265,8 @@ fn the_two_model_tables_are_the_references_own() {
     }
 }
 
-/// **`SetSequence` and `SetSequenceTime` are one arm** (`0x7121a0`): each interrupts what plays
-/// and anchors the new sequence's cursor — at 0, or at the caller's `ms` — on the pane's own
-/// clock. The clock law itself (advance, wrap, completion, the two handlers) is
-/// `script::tests::model_clock`; this is the binding-level shape, with no file facts known, which
-/// is the state the reference's queued replay covers.
+/// `SetSequence` and `SetSequenceTime` share one arm (`0x7121a0`): each interrupts what plays and
+/// anchors the new sequence's cursor, at 0 or at the caller's `ms`, on the pane's own clock.
 #[test]
 fn the_two_sequence_verbs_arm_the_pane_on_its_own_clock() {
     let mut s = script();
@@ -350,8 +281,7 @@ fn the_two_sequence_verbs_arm_the_pane_on_its_own_clock() {
     )
     .unwrap();
 
-    // 1.12 has no `GetSequence`, so the arm is read off the model the way `simplehtml`'s tests
-    // read their blocks — through the arena, because there is no Lua getter to read it through.
+    // 1.12 has no `GetSequence`, so the arm is read off the arena.
     let armed = |s: &UiScript| {
         let lua = s.lua();
         let model = lua.app_data_ref::<crate::script::Model>().expect("model");
@@ -373,19 +303,14 @@ fn the_two_sequence_verbs_arm_the_pane_on_its_own_clock() {
         "a new sequence starts at its own 0 — the old anchor is not carried across"
     );
 
-    // ...and ClearModel releases the instance, arm included.
+    // `ClearModel` releases the instance, arm included.
     s.run("MSeq:SetSequenceTime(3, 40) MSeq:ClearModel()")
         .unwrap();
     assert_eq!(armed(&s).1, None);
 }
 
-/// `SetLight` writes the widget's embedded `CGLight` by the reference's own argument walk
-/// (`0x76e1e0`, render law §5.3), and `GetLight` reads it back at arity **7 | 10 | 13**.
-///
-/// This test is the law, not a round trip: the tuple used to be stored verbatim because nobody
-/// had carved the binding, and "what went in comes out" is the one thing the reference does NOT
-/// do — the intensities are folded into the colours, the direction is normalised, and both of
-/// §5.3's traps change what a call means.
+/// `SetLight` writes the pane's `CGLight` by the reference's argument walk (`0x76e1e0`), folding
+/// intensities into colours and normalising the direction; `GetLight` answers 7, 10 or 13 values.
 #[test]
 fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
     let mut s = script();
@@ -393,8 +318,7 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
     s.run(r#"m = CreateFrame("Model", "MLight", UIParent)"#)
         .unwrap();
 
-    // A fresh pane: the ctor's white, switched off. Both colour blocks are `> 0`, so both come
-    // back as `1.0, r, g, b` — arity 13 before anything has ever been set.
+    // The constructor's light is off and white; both colour blocks are non-zero, so arity 13.
     let fresh: Vec<f64> = s.eval("return { MLight:GetLight() }").unwrap();
     assert_eq!(
         fresh,
@@ -402,19 +326,17 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
         "the <Model> ctor: disabled, omni, at the origin, white ambient and diffuse"
     );
 
-    // The commented-out GlueXML line, which is the corpus's only example of the shape.
+    // The commented-out call at `CharacterCreate.lua:61`.
     s.run("MLight:SetLight(1, 0, 0, -0.707, -0.707, 0.7, 1, 1, 1, 0.8, 1, 1, 0.8)")
         .unwrap();
     let l: Vec<f64> = s.eval("return { MLight:GetLight() }").unwrap();
     assert_eq!(l.len(), 13);
     assert_eq!((l[0], l[1]), (1.0, 0.0), "enabled, directional");
-    // The direction is NORMALISED on write (`0x71b6a0`), so `(0, -0.707, -0.707)` comes back as
-    // a unit vector — the one place a naive round trip would disagree.
+    // The direction is normalised on write (`0x71b6a0`).
     let dir = [l[2], l[3], l[4]];
     let len = (dir[0] * dir[0] + dir[1] * dir[1] + dir[2] * dir[2]).sqrt();
     assert!((len - 1.0).abs() < 1e-5, "normalised on write: {dir:?}");
-    // The intensity is FOLDED into the colour: ambient `1,1,1` at `0.7` is `(0.7, 0.7, 0.7)`,
-    // and the reported intensity is a constant 1.0.
+    // The intensity is folded into the colour, so ambient `1,1,1` at 0.7 reads 0.7 at intensity 1.
     assert_eq!(l[5], 1.0);
     for c in &l[6..9] {
         assert!((c - 0.7).abs() < 1e-5, "ambient folded: {c}");
@@ -424,17 +346,14 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
         assert!((c - want).abs() < 1e-5, "diffuse folded: {c} vs {want}");
     }
 
-    // TRAP 1: `SetLight(0, …)` returns before the local is copied, so it changes NOTHING — it is
-    // not a way to switch a light off, and a `<PlayerModel>`'s built-in one cannot be killed.
+    // `SetLight(0, …)` returns before the copy: a no-op, not a way to switch a light off.
     s.run("MLight:SetLight(0, 1, 5, 5, 5, 1, 1, 1, 1, 1, 1, 1, 1)")
         .unwrap();
     let after: Vec<f64> = s.eval("return { MLight:GetLight() }").unwrap();
     assert_eq!(after, l, "SetLight(0, …) is a no-op, not a disable");
 
-    // TRAP 2: an ambient intensity of 0 makes the walk skip its colour triple WITHOUT advancing
-    // the cursor, so the second intensity is read at index 8 — the seven-argument form. Here
-    // `1, 1, 1` are the ambient rgb the walk never reaches, and `0.5` is index 8 = the diffuse
-    // intensity against a white colour.
+    // A zero ambient intensity skips its colour triple without advancing the cursor, so the next
+    // argument (stack index 8) is the diffuse intensity: 0.5, against a white colour.
     s.run("MLight:SetLight(1, 1, 0, 0, 0, 0, 0.5)").unwrap();
     let t2: Vec<f64> = s.eval("return { MLight:GetLight() }").unwrap();
     assert_eq!(t2.len(), 10, "a zero ambient block collapses the arity");
@@ -448,11 +367,8 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
     assert!(s.run(r#"MLight:SetLight(1, 0, 0, 0, 0)"#).is_err());
     assert!(s.run(r#"MLight:SetLight("x")"#).is_err());
 
-    // **Fog is NOT the same shape, and this used to assert the opposite.** It read "unset fog
-    // returns NOTHING rather than three zeros — a pane with no fog and a pane fogged to black are
-    // different states", which is a good argument about a model the client does not have: there is
-    // no unset state. The fog colour is one packed `0xAARRGGBB` dword whose ctor writes
-    // `0xffffffff`, so a fresh pane reads **four** values, `1, 1, 1, 1` (decision 1845).
+    // The fog colour is one packed `0xAARRGGBB` dword, `0xffffffff` from the constructor, so a
+    // fresh pane reads four values, all 1; there is no unset state.
     assert_eq!(
         s.eval::<usize>("return table.getn({ MLight:GetFogColor() })")
             .unwrap(),
@@ -465,9 +381,7 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
         "never set is white and opaque, not four zeros"
     );
 
-    // Three arguments set alpha to **1.0**, not 0 — the fifth is guarded with that default where
-    // r/g/b are read unconditionally. The round trip is LOSSY by 8 bits a channel, because the
-    // store is that packed dword: 0.1 does not survive, 0.2 does.
+    // With three arguments alpha defaults to 1.0; the packed store keeps 8 bits a channel.
     s.run("MLight:SetFogColor(0.1, 0.2, 0.3)").unwrap();
     let (r, g, b, a): (f64, f64, f64, f64) = s.eval("return MLight:GetFogColor()").unwrap();
     assert_eq!(a, 1.0, "the omitted alpha defaults to 1.0");
@@ -478,7 +392,7 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
         );
     }
 
-    // …and the alpha really is the fifth argument, on the same clamp as the rest.
+    // Alpha is the fourth argument, clamped like the rest.
     s.run("MLight:SetFogColor(1, 1, 1, 0)").unwrap();
     assert_eq!(
         s.eval::<f64>("local _, _, _, a = MLight:GetFogColor() return a")
@@ -487,13 +401,9 @@ fn the_light_tuple_is_opaque_and_survives_the_round_trip() {
     );
 }
 
-/// `SetCamera(n)` selects by **raw table index**, is bounds-checked against the file's camera
-/// count, defers until the file's facts land, and gates the paint until the question is settled —
-/// the four halves of `0x76cec0`/`0x76ce80`/`0x76ce00`/`76d5f0` (decision 2027).
-///
-/// The whole point of the state is which render leg a pane takes: an installed camera is the
-/// perspective leg, the NULL camera is the orthographic one, and an index past the count is a
-/// NULL camera rather than an error or a clamp to the last record.
+/// `SetCamera(n)` picks by raw index, checked against the file's camera count once the file is
+/// known, and the pane waits to draw until then (`0x76cec0`, `0x76ce80`, `0x76ce00`, `0x76d5f0`).
+/// A camera draws in perspective; none, or an index past the count, draws orthographic.
 #[test]
 fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     use super::model_clock::pane;
@@ -518,23 +428,21 @@ fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     s.set_screen_size(800.0, 600.0);
     s.run(r#"m = CreateFrame("Model", "MCam", UIParent) m:SetModel("Creature\\Wolf\\Wolf.mdx")"#)
         .unwrap();
-    // The ctor's standing request for camera 0 (`0x76c910` writes `+0x320 = 0`), still pending
-    // because the file's facts have not arrived — so the pane is NOT on the paint list.
+    // The constructor's request for camera 0 (`0x76c910` writes `+0x320 = 0`) waits for the file.
     assert_eq!(state(&s, "MCam"), (Some(0), None));
     assert!(s.visible_model_panes().is_empty(), "the draw gate holds");
 
-    // The facts land: the model-ready hook applies the pending index. Wolf has two cameras, so
-    // index 0 installs and the pane takes the perspective leg.
+    // The file lands with two cameras, so the pending index 0 installs: perspective.
     s.set_model_facts(FILE, facts(2));
     assert_eq!(state(&s, "MCam"), (None, Some(0)));
     assert_eq!(s.visible_model_panes().len(), 1, "the gate is settled");
 
-    // With the facts in hand `SetCamera` resolves immediately — raw index 1 is a real record.
+    // With the file known, `SetCamera` resolves at once.
     s.run("MCam:SetCamera(1)").unwrap();
     assert_eq!(state(&s, "MCam"), (None, Some(1)));
 
-    // An index past the count installs the NULL camera: the ORTHOGRAPHIC leg, and the pane keeps
-    // drawing. Not a clamp to the last record, not a raise.
+    // An index past the count installs no camera, not the last one, and the pane draws on,
+    // orthographic.
     s.run("MCam:SetCamera(7)").unwrap();
     assert_eq!(state(&s, "MCam"), (None, None));
     assert_eq!(s.visible_model_panes().len(), 1);
@@ -542,8 +450,7 @@ fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     s.run("MCam:SetCamera(1) MCam:SetCamera(-1)").unwrap();
     assert_eq!(state(&s, "MCam"), (None, None));
 
-    // A file with no camera table at all: every index is out of range, so a plain <Model> on it
-    // is always the orthographic leg — which is every shipped in-game UI M2.
+    // A file with no cameras, like every shipped UI M2, always draws orthographic.
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     s.run(r#"m = CreateFrame("Model", "MFlat", UIParent) m:SetModel("Interface\\Cooldown\\UI-Cooldown-Indicator.mdx")"#)
@@ -551,8 +458,7 @@ fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     s.set_model_facts(r"Interface\Cooldown\UI-Cooldown-Indicator.mdx", facts(0));
     assert_eq!(state(&s, "MFlat"), (None, None));
 
-    // `SetCamera` before the file is known DEFERS, and the deferred index is what the facts
-    // apply — bounds-checked then, not at the call.
+    // `SetCamera` before the file is known defers, and the index is checked when the file lands.
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     s.run(r#"m = CreateFrame("Model", "MLate", UIParent) m:SetCamera(1) m:SetModel("Creature\\Wolf\\Wolf.mdx")"#)
@@ -563,9 +469,8 @@ fn set_camera_is_a_raw_index_bounds_checked_against_the_file() {
     assert_eq!(state(&s, "MLate"), (None, Some(1)));
 }
 
-/// The fog block: `SetFogColor` **arms** it, `ClearFog` disarms **bit 0 alone**, and near/far are
-/// stored raw by the Lua setters (render law §5.4, decision 2027). The five verbs held back as
-/// uncarved since 1134 §4 are real now.
+/// `SetFogColor` arms the fog, `ClearFog` clears bit 0 alone (`0x76f5c5`), and the Lua setters
+/// store near and far raw (`0x76ee60`/`0x76f540`).
 #[test]
 fn the_fog_block_arms_on_colour_and_clears_only_its_bit() {
     use super::model_clock::pane;
@@ -579,8 +484,7 @@ fn the_fog_block_arms_on_colour_and_clears_only_its_bit() {
     s.set_screen_size(800.0, 600.0);
     s.run(r#"m = CreateFrame("Model", "MFog", UIParent)"#)
         .unwrap();
-    // The ctor: fog OFF, near 0.0, far **1.0** (`76c950`) — not far 0, which would be a
-    // degenerate ramp the batch would refuse.
+    // The constructor's fog: off, near 0, far 1 (`0x76c950`).
     assert_eq!(fog(&s), (false, 0.0, 1.0));
     assert_eq!(
         s.eval::<(f64, f64)>("return MFog:GetFogNear(), MFog:GetFogFar()")
@@ -588,14 +492,13 @@ fn the_fog_block_arms_on_colour_and_clears_only_its_bit() {
         (0.0, 1.0)
     );
 
-    // The glue's own call shape. `SetFogColor` is the arming verb; near/far are not.
+    // `GlueParent.lua:213-215` with the Tauren row (`:18`); only `SetFogColor` arms the fog.
     s.run("MFog:SetFogNear(0) MFog:SetFogFar(153)").unwrap();
     assert_eq!(fog(&s), (false, 0.0, 153.0), "near/far do not arm the fog");
     s.run("MFog:SetFogColor(1.0, 0.61, 0.42)").unwrap();
     assert!(fog(&s).0, "the colour arms it");
 
-    // `ClearFog` touches bit 0 and nothing else: the colour, the near and the far all survive, so
-    // a later SetFogColor re-arms the same ramp.
+    // `ClearFog` keeps the colour, near and far, so a later `SetFogColor` re-arms the same ramp.
     s.run("MFog:ClearFog()").unwrap();
     assert_eq!(fog(&s), (false, 0.0, 153.0));
     let (r, g, b, _): (f64, f64, f64, f64) = s.eval("return MFog:GetFogColor()").unwrap();
@@ -604,8 +507,7 @@ fn the_fog_block_arms_on_colour_and_clears_only_its_bit() {
         "the colour survives a clear: {r}, {g}, {b}"
     );
 
-    // The Lua setters store RAW — no clamp, no ordering check. Only the XML attribute path
-    // clamps at `>= 0`.
+    // The Lua setters store raw, with no clamp or ordering check; only the XML path clamps at 0.
     s.run("MFog:SetFogNear(-40) MFog:SetFogFar(-1)").unwrap();
     assert_eq!(fog(&s), (false, -40.0, -1.0));
 }
diff --git a/crates/benilla-ui/src/script/tests/movable.rs b/crates/benilla-ui/src/script/tests/movable.rs
index f3462a61..cfaf53e1 100644
--- a/crates/benilla-ui/src/script/tests/movable.rs
+++ b/crates/benilla-ui/src/script/tests/movable.rs
@@ -1,9 +1,6 @@
-//! The movable-frame family — `SetMovable`/`StartMoving`/`StopMovingOrSizing`/`SetUserPlaced`/
-//! `SetResizable` (the mechanism and its wow-re addresses are in `script::object::movable`).
-//!
-//! Every test here drives the PRODUCTION path: the Lua bindings, and the real
-//! `mouse_button`/`mouse_move` entry points, so the drag gesture that fires `OnDragStart` is the
-//! same one an addon gets.
+//! The movable-frame family (`SetMovable`, `StartMoving`, `StopMovingOrSizing`, `SetUserPlaced`,
+//! `SetResizable`), title regions and the user-placed layout cache, driven through the Lua
+//! bindings and the real mouse entry points.
 
 use super::common::script;
 use crate::script::UiScript;
@@ -38,16 +35,13 @@ fn corner(s: &mut UiScript) -> (f32, f32) {
     (left, bottom)
 }
 
-/// The whole point of the family: the four-line addon idiom actually moves the frame, and the
-/// position it was dragged to SURVIVES the stop — nothing snaps it back to the `SetPoint` it was
-/// born with, and nothing keeps moving it after the button is up.
 #[test]
 fn the_canonical_addon_idiom_moves_a_frame_and_the_position_survives_the_stop() {
     let mut s = movable_panel();
     assert_eq!(corner(&mut s), (100.0, 100.0), "born where SetPoint put it");
 
     s.mouse_button(150.0, 140.0, "LeftButton", true); // press inside the panel
-    s.mouse_move(152.0, 140.0); // 2 px — under the drag threshold, nothing yet
+    s.mouse_move(152.0, 140.0); // 2 px, under the drag threshold
     assert_eq!(s.eval::<i64>("return starts").unwrap(), 0);
     assert_eq!(corner(&mut s), (100.0, 100.0));
 
@@ -64,27 +58,23 @@ fn the_canonical_addon_idiom_moves_a_frame_and_the_position_survives_the_stop()
     assert_eq!(s.eval::<i64>("return stops").unwrap(), 1);
     assert_eq!(corner(&mut s), (200.0, 150.0), "the position survives");
 
-    // And the move is really over: further cursor motion moves nothing.
     s.mouse_move(500.0, 400.0);
     assert_eq!(corner(&mut s), (200.0, 150.0), "no longer following");
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 
-    // GetPoint reads back the frame's OWN point with the dragged offsets — the reference writes
-    // the anchors in place rather than rewriting them, so what an addon saves is what it set.
+    // The reference moves the anchors in place, so GetPoint reads the frame's own point, dragged.
     let (point, x, y) = s
         .eval::<(String, f64, f64)>("local p, _, _, x, y = MovePanel:GetPoint() return p, x, y")
         .unwrap();
     assert_eq!((point.as_str(), x, y), ("BOTTOMLEFT", 200.0, 150.0));
 }
 
-/// A moving frame follows SUCCESSIVE moves, each one applying only that step's delta (the pump
-/// re-centers its sample — a bug that integrated from the grab instead would double the second
-/// step, and one that forgot to re-center would freeze after the first).
+/// Each move applies only its own delta: the pump re-centers its sample after every step.
 #[test]
 fn a_moving_frame_follows_successive_mouse_moves() {
     let mut s = movable_panel();
     s.mouse_button(150.0, 140.0, "LeftButton", true);
-    s.mouse_move(160.0, 140.0); // the move that STARTS the drag
+    s.mouse_move(160.0, 140.0); // the move that starts the drag
     assert_eq!(
         corner(&mut s),
         (100.0, 100.0),
@@ -102,9 +92,7 @@ fn a_moving_frame_follows_successive_mouse_moves() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `StartMoving` on a frame that is not `SetMovable(true)` RAISES and moves nothing — the
-/// reference's own guard (`0x776700`'s movable-bit test). The error is a real Lua error, so an
-/// addon's `pcall` sees it.
+/// The reference's `StartMoving` raises on a frame that is not movable (`0x776700`).
 #[test]
 fn start_moving_on_a_frame_that_is_not_movable_raises_and_moves_nothing() {
     let mut s = script();
@@ -128,13 +116,11 @@ fn start_moving_on_a_frame_that_is_not_movable_raises_and_moves_nothing() {
         "the refusal names why"
     );
 
-    // Nothing is in flight, so the cursor moves nothing.
     s.mouse_move(400.0, 400.0);
     s.resolve();
     let left = s.eval::<f64>("return FixedPanel:GetLeft()").unwrap();
     assert_eq!(left, 100.0, "a refused StartMoving started no move");
 
-    // The same frame, once made movable, moves — proving the guard was the only thing stopping it.
     s.run("FixedPanel:SetMovable(true) FixedPanel:StartMoving()")
         .unwrap();
     s.mouse_move(450.0, 400.0);
@@ -142,10 +128,8 @@ fn start_moving_on_a_frame_that_is_not_movable_raises_and_moves_nothing() {
     assert_eq!(s.eval::<f64>("return FixedPanel:GetLeft()").unwrap(), 150.0);
 }
 
-/// `StopMovingOrSizing` with nothing moving is harmless — the double call, the OnDragStop that
-/// never had a StartMoving, the addon that also wires it to OnMouseUp. And it only stops the
-/// frame that is actually in the drag slot (the reference's `[root+0xcfc] == self` compare), so
-/// one frame's stop cannot end another's move.
+/// `StopMovingOrSizing` is harmless with nothing moving, and stops only the frame in the drag slot
+/// (the reference compares `[root+0xcfc]` with self).
 #[test]
 fn stop_moving_or_sizing_is_harmless_with_nothing_moving_and_stops_only_its_own_frame() {
     let mut s = movable_panel();
@@ -163,7 +147,6 @@ fn stop_moving_or_sizing_is_harmless_with_nothing_moving_and_stops_only_its_own_
     assert!(s.errors().is_empty(), "{:?}", s.errors());
     assert_eq!(corner(&mut s), (100.0, 100.0), "nothing moved");
 
-    // Now start a real move and have the OTHER frame try to stop it.
     s.run("MovePanel:StartMoving()").unwrap();
     s.mouse_move(50.0, 50.0); // cursor_pos was (0,0) ⇒ +50, +50
     assert_eq!(corner(&mut s), (150.0, 150.0));
@@ -180,10 +163,7 @@ fn stop_moving_or_sizing_is_harmless_with_nothing_moving_and_stops_only_its_own_
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A frame stretched between two anchors — no explicit size at all — moves RIGIDLY and keeps its
-/// derived size. This is the case a single-point rewrite gets wrong (it would drop the opposing
-/// anchor and leave the frame under-constrained, i.e. gone), and the case that decides between
-/// translating one anchor and translating the set.
+/// A move translates every anchor, so a frame sized by two anchors keeps its size.
 #[test]
 fn a_frame_stretched_between_two_anchors_moves_rigidly() {
     let mut s = script();
@@ -219,8 +199,8 @@ fn a_frame_stretched_between_two_anchors_moves_rigidly() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// A SCALED frame moves with the cursor 1:1 on screen — the anchor offsets it writes are in local
-/// units, so they carry the inverse of the frame's own scale (`geo_768710`'s `dx/scale`).
+/// A scaled frame tracks the cursor 1:1 on screen: the offsets it writes are in local units
+/// (`0x768710` divides by the frame's scale).
 #[test]
 fn a_scaled_frame_tracks_the_cursor_one_to_one_on_screen() {
     let mut s = script();
@@ -244,7 +224,7 @@ fn a_scaled_frame_tracks_the_cursor_one_to_one_on_screen() {
     );
     s.mouse_move(40.0, 0.0);
     s.resolve();
-    // GetLeft reports LOCAL units: 40 screen px is 20 local, on top of the local 100.
+    // GetLeft reports local units: 40 screen px is 20 local, on top of the local 100.
     assert_eq!(
         s.eval::<f64>("return ScaledPanel:GetLeft()").unwrap(),
         120.0
@@ -256,9 +236,8 @@ fn a_scaled_frame_tracks_the_cursor_one_to_one_on_screen() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The flags: default off, round-trip through their setters, and `SetUserPlaced`'s guard — the
-/// reference refuses it unless the frame is movable OR resizable (`776adb: test ah,0x3`).
-/// `StartMoving` sets the bit itself, which is the reference's drag-start doing it, not us.
+/// The reference refuses `SetUserPlaced` unless the frame is movable or resizable (`0x776adb`),
+/// and its drag start sets the bit itself (`0x7652b0`).
 #[test]
 fn the_three_flags_default_off_round_trip_and_user_placed_is_guarded() {
     let mut s = script();
@@ -282,7 +261,6 @@ fn the_three_flags_default_off_round_trip_and_user_placed_is_guarded() {
         "no frame is born flagged"
     );
 
-    // SetUserPlaced before either flag: refused, exactly like the reference.
     assert!(
         !s.eval::<bool>("return (pcall(function() FlagPanel:SetUserPlaced(true) end))")
             .unwrap(),
@@ -305,7 +283,6 @@ fn the_three_flags_default_off_round_trip_and_user_placed_is_guarded() {
         "truthy 1 sets, false clears"
     );
 
-    // The drag start sets userPlaced itself (`0x7652b0`).
     s.resolve();
     s.run("FlagPanel:StartMoving()").unwrap();
     assert!(
@@ -316,9 +293,6 @@ fn the_three_flags_default_off_round_trip_and_user_placed_is_guarded() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `movable="true"` / `resizable="true"` in XML land on the real methods — they were a warn-once
-/// gap in the loader until this family existed, which left every reference window authored
-/// movable undraggable while `SetMovable` worked fine from Lua.
 #[test]
 fn the_xml_movable_and_resizable_attributes_reach_the_methods() {
     let s = script();
@@ -349,17 +323,9 @@ fn the_xml_movable_and_resizable_attributes_reach_the_methods() {
     );
 }
 
-/// **`StartSizing(grip)` moves the gripped edges and plants the opposite ones.**
-///
-/// `0x776830`, verified in wow-re's ledger; the reference's own caller is
-/// `FloatingChatFrame.lua:600`. Four corpus addons reach it through ONE line —
-/// `FuBar_Panel.lua:980`, replicated into FuBar_CorkFu, FuBar_FuXPFu, FuBar_SpellStatusFu and oRA2
-/// (1207: one library, not four votes).
-///
-/// What the ledger does NOT record is which edges a grip moves — it has the verb as pure
-/// orchestration with no inline math. Taken here as the plain meaning of an anchor point, which is
-/// how the reference's caller uses it. This test is where that reading is pinned, so an RE pass
-/// that contradicts it fails here first.
+/// `StartSizing(grip)` (`0x776830`, called from `FloatingChatFrame.lua:600`) moves the gripped
+/// edges and plants the opposite ones. Which edges a grip moves is untraced in the reference, whose
+/// verb has no inline math; this takes the anchor point's plain meaning, as that caller does.
 #[test]
 fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -375,7 +341,7 @@ fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
     .unwrap();
     s.resolve();
 
-    // Grip the RIGHT edge and drag 40 right: width grows, the left edge stays planted.
+    // Grip the right edge and drag 40 right: the width grows, the left edge stays planted.
     s.mouse_move(300.0, 100.0);
     s.run("Sizer:StartSizing(\"RIGHT\")").unwrap();
     s.mouse_move(340.0, 100.0);
@@ -384,8 +350,7 @@ fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
     assert_eq!(s.eval::<f32>("return Sizer:GetLeft()").unwrap(), 100.0);
     s.run("Sizer:StopMovingOrSizing()").unwrap();
 
-    // Grip the LEFT edge and drag 30 right: width SHRINKS and the left edge follows the cursor,
-    // so the right edge is the one that stays put.
+    // Grip the left edge and drag 30 right: the width shrinks and the right edge stays put.
     let right_before = s.eval::<f32>("return Sizer:GetRight()").unwrap();
     s.run("Sizer:StartSizing(\"LEFT\")").unwrap();
     s.mouse_move(370.0, 100.0);
@@ -398,13 +363,11 @@ fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
         "the ungripped edge must not move"
     );
 
-    // StopMovingOrSizing ends it: further motion changes nothing.
     s.run("Sizer:StopMovingOrSizing()").unwrap();
     s.mouse_move(500.0, 100.0);
     s.resolve();
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 210.0);
 
-    // A frame that is not resizable refuses, like the movable family's siblings.
     s.run("g = CreateFrame(\"Frame\", \"NotSizer\", UIParent)")
         .unwrap();
     assert!(
@@ -413,10 +376,7 @@ fn start_sizing_moves_the_gripped_edge_and_plants_the_other() {
     );
 }
 
-/// **`CreateTitleRegion` / `GetTitleRegion` — the object half** (wow-re
-/// `widget-api-batch-benilla.md` Q6, `0x773910` / `0x773820`).
-///
-/// Four details, each one a coin-flip a reimplementation loses, and each one asserted.
+/// `CreateTitleRegion` (`0x773910`) and `GetTitleRegion` (`0x773820`): the object half.
 #[test]
 fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
     let mut s = script();
@@ -430,15 +390,14 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
     )
     .unwrap();
 
-    // GetTitleRegion answers ONE value and it is nil — not zero values, which is the asymmetry
-    // Q6 flags against `GetBackdrop`.
+    // With none, it returns one nil, where `GetBackdrop` (`0x777370`) returns no value at all.
     assert_eq!(s.arity("TFrame:GetTitleRegion()").unwrap(), 1);
     assert!(s
         .eval::<Option<bool>>("return TFrame:GetTitleRegion() ~= nil and true or nil")
         .unwrap()
         .is_none());
 
-    // It is a plain REGION — not a Texture wearing a hat.
+    // A plain Region, not a Texture.
     s.run("TR = TFrame:CreateTitleRegion()").unwrap();
     assert_eq!(
         s.eval::<String>("return TR:GetObjectType()").unwrap(),
@@ -456,14 +415,12 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
         .eval::<bool>("return TFrame:GetTitleRegion() == TR")
         .unwrap());
 
-    // **It takes NO argument**: `CreateTitleRegion(frame)` is the no-arg call, which is exactly
-    // what `CustomNameplates/options.lua:73` writes.
+    // It takes no argument: `CreateTitleRegion(frame)` is the no-argument call.
     assert!(s
         .eval::<bool>("return TFrame:CreateTitleRegion(TFrame) == TR")
         .unwrap());
 
-    // **Idempotent, and DESTRUCTIVELY so.** A second call returns the same object after clearing
-    // its anchors — so it silently wipes the points a caller already set.
+    // A second call returns the same region with its anchors cleared.
     s.run("TR:SetAllPoints(TFrame)").unwrap();
     s.resolve();
     assert_eq!(s.eval::<i64>("return TR:GetNumPoints()").unwrap(), 2);
@@ -476,9 +433,8 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
         "the second call ran ClearAllPoints on the region it returned"
     );
 
-    // **It answers the 19 Region methods and NOTHING else** — 1250 §5's named divergence, closed.
-    // Q6: no Show/Hide, no scripts, no textures. Ours used to share one metatable with Texture and
-    // FontString, so a title region answered `SetTexture` where the reference raises.
+    // It answers the 19 Region methods and nothing else (`0x81c554`, `0x81c528`): no Show/Hide,
+    // no scripts, no textures.
     for name in crate::script::REGION_MAP_METHODS {
         assert_eq!(
             s.eval::<String>(&format!("return type(TR.{name})"))
@@ -521,8 +477,7 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
         "a title region emits no quad of its own (the frame's own quad is not one): {region_quads:?}"
     );
 
-    // The full region kinds are untouched by the split — asserted LAST, because creating a real
-    // texture would otherwise put a legitimate quad into the check above.
+    // Checked last: a real texture would add a legitimate quad to the check above.
     s.run("TTex = TFrame:CreateTexture(nil, 'ARTWORK')")
         .unwrap();
     assert_eq!(
@@ -532,10 +487,8 @@ fn a_title_region_is_a_plain_region_and_creating_it_twice_is_destructive() {
     );
 }
 
-/// **The drag half — and the three things that make it not just `StartMoving`.**
-///
-/// A mouse-down inside the title region starts a move that (1) SWALLOWS `OnMouseDown`, (2) ends on
-/// release where a scripted move persists, and (3) does not consult `SetMovable`.
+/// A press in the title region starts a move that, unlike `StartMoving`, swallows `OnMouseDown`,
+/// ends on release and skips the movable check.
 #[test]
 fn a_title_region_drag_swallows_the_press_and_ends_on_release() {
     let mut s = script();
@@ -559,7 +512,6 @@ fn a_title_region_drag_swallows_the_press_and_ends_on_release() {
     };
     assert_eq!(corner(&mut s), 100.0);
 
-    // Press inside the title region: the move starts and OnMouseDown never runs.
     s.mouse_button(150.0, 150.0, "LeftButton", true);
     assert_eq!(
         s.eval::<i64>("return downs").unwrap(),
@@ -569,7 +521,7 @@ fn a_title_region_drag_swallows_the_press_and_ends_on_release() {
     s.mouse_move(250.0, 150.0);
     assert_eq!(corner(&mut s), 200.0, "the frame followed the cursor");
 
-    // **Release ends it** — mode 2 auto-cancels. Moving the cursor afterwards must not drag it.
+    // Release ends it: the title-region move (mode 2) cancels itself.
     s.mouse_button(250.0, 150.0, "LeftButton", false);
     s.mouse_move(400.0, 150.0);
     assert_eq!(
@@ -578,16 +530,12 @@ fn a_title_region_drag_swallows_the_press_and_ends_on_release() {
         "the move ended at the release; a scripted StartMoving would still be running"
     );
 
-    // **No `SetMovable` gate on this path** — TP was never made movable, and it dragged. Q6 marks
-    // the no-gate reading VERIFIED (the movable bit is simply not read on
-    // 0x7662c0->0x765320->0x7652b0->0x768430); a title region on a non-movable frame is the case
-    // that tells it apart from `StartMoving`, which raises "Frame %s is not movable".
+    // The movable bit is not read on this path (`0x7662c0`, `0x765320`, `0x7652b0`, `0x768430`).
     assert!(!s.eval::<bool>("return TP:IsMovable()").unwrap());
 }
 
-/// A region's rect getters answer in its OWNER's units — screen ÷ the owner's effective scale —
-/// exactly as the frame getters do (decision 1985): a texture inside a frame scaled to 0.5 that
-/// covers the frame answers the frame's own width, not half of it.
+/// A region's rect getters answer in its owner's units, screen ÷ the owner's effective scale, as
+/// the frame getters do.
 #[test]
 fn region_getters_answer_in_the_owners_units_under_scale() {
     let mut s = UiScript::new().unwrap();
@@ -616,14 +564,9 @@ fn region_getters_answer_in_the_owners_units_under_scale() {
     assert!((cx - (fl + fr) * 0.5).abs() < 1e-3);
 }
 
-/// **The layout cache's filter is the flags AND the bit, at both ends** (decision 2193).
-///
-/// `SetUserPlaced` is already guarded by `movable|resizable` at its own setter (`0x776adb`), but
-/// the drag entry (`0x7652b0` @`0x7652e5`) and the cache's own apply stamp the bit without going
-/// through it — so a frame can carry the stamp while carrying neither flag, and the reference's
-/// writer tests for both: `0x490e8e test ah,0x10` (userPlaced) AND `0x490e97 test ah,0x3`
-/// (`movable|resizable`). Clearing the flags is how a window stops being persisted, which is what
-/// an addon's `:OnDisable` does on the way out.
+/// The layout cache writes a frame only when it is user-placed (`0x490e8e`) and movable or
+/// resizable (`0x490e97`): the drag start (`0x7652b0` at `0x7652e5`) and the cache's own apply
+/// set the bit past `SetUserPlaced`'s guard (`0x776adb`), so clearing the flags stops the save.
 #[test]
 fn the_write_filter_is_user_placed_and_movable_or_resizable() {
     let mut s = script();
@@ -659,11 +602,9 @@ fn the_write_filter_is_user_placed_and_movable_or_resizable() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The apply is gated per ARM** (decision 2193): position behind `movable` (`0x490600 test
-/// ah,0x1`), size behind `resizable` (`0x490689 test ah,0x2`), and each arm stamps the userPlaced
-/// bit itself (`0x49067e` / `0x490706`) only if it ran. A stock frame carrying neither flag is
-/// left entirely alone, however old its row — which is what stops one addon's stamp from seating
-/// a window forever.
+/// The cache's apply seats position only when movable (`0x490600`) and size only when resizable
+/// (`0x490689`), and each arm that runs sets userPlaced (`0x49067e`, `0x490706`); a frame with
+/// neither flag is left alone.
 #[test]
 fn the_apply_seats_position_behind_movable_and_size_behind_resizable() {
     use crate::script::{FrameLayout, LayoutPoint};
diff --git a/crates/benilla-ui/src/script/tests/name_targets.rs b/crates/benilla-ui/src/script/tests/name_targets.rs
index 57128077..13156ad8 100644
--- a/crates/benilla-ui/src/script/tests/name_targets.rs
+++ b/crates/benilla-ui/src/script/tests/name_targets.rs
@@ -1,25 +1,11 @@
-//! **A widget NAME argument is a Lua GLOBAL, not a frame name** — the one rule behind every
-//! binding that takes "a frame or its name": `SetPoint`'s `relativeTo`, `SetAllPoints`,
-//! `SetParent`, `SetScrollChild`.
-//!
-//! The client has a single widget namespace and it is `_G`. The wrapper binder `0x701bd0`
-//! publishes `_G[name] = T` for a named widget (non-overwriting), and the by-name resolvers read
-//! that table back and nothing else — `0x76c760` (FrameScript globals **rawget** + Lua-type-5 +
-//! the `vtbl+0x10` tag check) and its geometry-vtable `+0x28` twin `0x76c700`
-//! (`_G[name]` → `t[0]` userdata → `IsA`). `wow-5875-re` `system/ui/ledger.tsv` rows 7972/7973,
-//! `system/ui/scratch/worldmap-arrow-and-positions.md` §2.4, `system/ui/ui.md` §RF-0023(c).
-//!
-//! A frame's published name is therefore only the commonest way such a global comes to exist —
-//! **an alias is just as good a name**, and 1.12 addons lean on that. Bartender2 2.0 aliases every
-//! stock button (`Bar8Button1 = CharacterBag3Slot`, file scope, `Alias.lua`) and then lays each bar
-//! out by anchoring button *i* to the string `"Bar8Button"..(i-1)`. Resolving those against a
-//! private frame-name registry finds nothing, every anchor falls back to the parent, and all five
-//! bag buttons land in one spot on the bar's far corner. Decision 2105.
+//! A widget name argument (`SetPoint`'s `relativeTo`, `SetAllPoints`, `SetParent`,
+//! `SetScrollChild`) is a Lua global, so an alias resolves too: the binder `0x701bd0` publishes
+//! `_G[name]` without overwriting, and the resolvers `0x76c760` (rawget, type 5, `vtbl+0x10` tag)
+//! and `0x76c700` (`_G[name]`, `t[0]`, `IsA`) read `_G` and nothing else.
 
 use super::common::script;
 
-/// Bartender2's exact shape: stock buttons, addon alias globals that no frame is named, a row laid
-/// out through those aliases alone. The row must come out at the addon's pitch.
+/// Bartender2's shape: a row laid out through alias globals that are no frame's own name.
 #[test]
 fn setpoint_relative_to_resolves_an_alias_global() {
     let mut s = script();
@@ -74,8 +60,7 @@ fn setpoint_relative_to_resolves_an_alias_global() {
     );
 }
 
-/// The namespace is ONE: a **region** published under a global resolves as a `relativeTo` exactly
-/// as a frame does (the real XML anchors frames to FontStrings by name — gossip option rows).
+/// One namespace: stock XML anchors frames to FontStrings by name (the gossip option rows).
 #[test]
 fn setpoint_relative_to_resolves_a_region_alias_global() {
     let mut s = script();
@@ -107,9 +92,7 @@ fn setpoint_relative_to_resolves_a_region_alias_global() {
     assert_eq!(bottom, 20.0);
 }
 
-/// A global that is not a widget resolves to nothing — the reference's type-5 + tag check — and
-/// the binding then takes its unresolved-name leg, which **raises** (`0x87ccd4`; decision 2176).
-/// The value is never used, and no anchor is left behind.
+/// The type-5 and tag check reject it, and the unresolved-name leg raises (`0x87ccd4`).
 #[test]
 fn setpoint_relative_to_ignores_a_non_widget_global() {
     let mut s = script();
@@ -137,11 +120,9 @@ fn setpoint_relative_to_ignores_a_non_widget_global() {
     assert_eq!(n, 0, "the raise leaves no anchor behind");
 }
 
-/// **`$parent` is expanded at RUNTIME, on the anchor path only.** `0x76c5b0` has exactly two call
-/// sites — `SetName 0x76c691` and `0x76c71c` *inside* the layout resolver `0x76c700` — so
-/// `SetPoint`/`SetAllPoints` run the token against the anchoring frame's first **named** ancestor
-/// (skipping anonymous links, `"Top"` when there is none), while `SetParent` and `SetScrollChild`,
-/// which call `0x76c760` directly, do not.
+/// The expander `0x76c5b0` is called only from `SetName` (`0x76c691`) and the layout resolver
+/// (`0x76c71c` in `0x76c700`), so anchors expand `$parent` against the first named ancestor
+/// (`"Top"` if none); `SetParent` and `SetScrollChild` call `0x76c760` directly and do not.
 #[test]
 fn setpoint_relative_to_expands_parent_against_the_first_named_ancestor() {
     let mut s = script();
@@ -175,8 +156,6 @@ fn setpoint_relative_to_expands_parent_against_the_first_named_ancestor() {
     assert!(s.take_warnings().is_empty());
 }
 
-/// The other half of the same fact: the reparent bindings never see the token, so a
-/// `$parent`-prefixed name reaches them literally and fails to resolve.
 #[test]
 fn setparent_does_not_expand_parent() {
     let s = script();
@@ -197,8 +176,7 @@ fn setparent_does_not_expand_parent() {
     );
 }
 
-/// `SetParent` takes the same namespace (`0x7a1550`'s NAME-string path → `0x76c760`) — Bartender2
-/// re-parents every stock button by alias before it anchors it.
+/// `SetParent`'s name path (`0x7a1550`) resolves through `0x76c760` too.
 #[test]
 fn setparent_resolves_an_alias_global() {
     let s = script();
@@ -218,7 +196,6 @@ fn setparent_resolves_an_alias_global() {
     );
 }
 
-/// `SetAllPoints` shares the resolver, so it shares the rule.
 #[test]
 fn setallpoints_resolves_an_alias_global() {
     let mut s = script();
@@ -243,15 +220,8 @@ fn setallpoints_resolves_an_alias_global() {
     assert_eq!((l, b, w, h), (30.0, 40.0, 120.0, 60.0));
 }
 
-/// **A leading `$parent` in a Lua constructor's NAME argument is expanded**, exactly as in XML —
-/// `CreateFrame 0x7060b0`, `CreateTexture 0x773a20` and `CreateFontString 0x773c30` all build a
-/// synthetic node carrying `name=` and read it back through `CScriptRegion::SetName 0x76c650`,
-/// which is one of the expander `0x76c5b0`'s two call sites.
-///
-/// Found by decision 2176's raise, which is the point of a raise: the unexpanded name had been
-/// there all along, degrading quietly into a parent-anchored fallback. `FonzAppraiser` names
-/// roughly thirty widgets this way and `pfQuest/browser.lua:723` builds its search icon as
-/// `input:CreateTexture("$parentSearchIcon", "OVERLAY")`.
+/// `CreateFrame 0x7060b0`, `CreateTexture 0x773a20` and `CreateFontString 0x773c30` read their
+/// `name=` back through `CScriptRegion::SetName 0x76c650`, which calls the expander `0x76c5b0`.
 #[test]
 fn a_constructor_name_expands_parent() {
     let s = script();
@@ -269,7 +239,7 @@ fn a_constructor_name_expands_parent() {
         "RootKid",
         "the base is the first NAMED ancestor of the frame's parent, not the parent itself"
     );
-    // …and the expanded name is what reached `_G`, which is the only widget namespace (2105).
+    // The expanded name is what reached `_G`.
     assert_eq!(
         s.eval::<String>("return RootKid:GetName()").unwrap(),
         "RootKid"
@@ -279,12 +249,12 @@ fn a_constructor_name_expands_parent() {
             .unwrap(),
         "the raw token names nothing"
     );
-    // A region's `$parent` is its OWNER frame, so the walk starts one link lower.
+    // A region's `$parent` is its owner frame.
     assert_eq!(
         s.eval::<String>("return RootKidIcon:GetName()").unwrap(),
         "RootKidIcon"
     );
-    // The payoff: an anchor by the built name resolves instead of raising.
+    // An anchor by the built name resolves.
     s.run(r#"Icon:SetPoint("TOPLEFT", "RootKid", "TOPLEFT", 0, 0)"#)
         .unwrap();
 }
diff --git a/crates/benilla-ui/src/script/tests/nameplate.rs b/crates/benilla-ui/src/script/tests/nameplate.rs
index 5ff89c55..af972473 100644
--- a/crates/benilla-ui/src/script/tests/nameplate.rs
+++ b/crates/benilla-ui/src/script/tests/nameplate.rs
@@ -1,18 +1,10 @@
-//! The nameplate ABI, as the four vanilla addons actually read it (decision 2148).
-//!
-//! These are not "does the pool work" tests. Each is a transcription of a real corpus idiom — the
-//! same walk, the same destructuring, the same identification test — so a change that would break
-//! a shipped addon fails **here** rather than on the director's screen.
-//!
-//! Sources, all `## Interface: 11200`: `pfUI/modules/nameplates.lua` (+ `compat/vanilla.lua`),
-//! `ShaguTweaks/libs/libnameplate.lua`, `CustomNameplates/CustomNameplates.lua`,
-//! `_Nameplates/_Nameplates.lua`. The byte side is wow-re
-//! `system/ui/scratch/nameplate-lua-surface.md` (§5, 2026-09-09).
+//! The nameplate ABI as four vanilla addons read it, one idiom per test:
+//! `pfUI/modules/nameplates.lua`, `ShaguTweaks/libs/libnameplate.lua`,
+//! `CustomNameplates/CustomNameplates.lua` and `_Nameplates/_Nameplates.lua`.
 
 use crate::script::{PlateGeometry, PlateState, UiScript};
 
-/// A VM with a `WorldFrame` to hang plates off — the only thing [`UiScript::sync_nameplates`]
-/// requires of a session.
+/// A VM with a `WorldFrame` to hang plates off, all [`UiScript::sync_nameplates`] requires.
 fn vm() -> UiScript {
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
@@ -22,8 +14,7 @@ fn vm() -> UiScript {
     s
 }
 
-/// The plate size at the capture window (`vplates` scenario: one gx unit = 1280 px, so the
-/// 0.1 × 0.025 plate is 128 × 32 px, and at seam scale 1.0 that is 128 × 32 units).
+/// A 1280 px window, where one gx unit is 1280 px, so the 0.1 × 0.025 plate is 128 × 32.
 fn geometry() -> PlateGeometry {
     PlateGeometry {
         width: 128.0,
@@ -44,8 +35,7 @@ fn geometry() -> PlateGeometry {
 
 fn plate(name: &str, health: f32, max: f32) -> PlateState {
     PlateState {
-        // The unit's GUID stands in as a hash of its name: what matters to these tests is that the
-        // same unit keeps the same key across frames and two units never share one.
+        // A hash of the name stands in for the GUID: stable per unit, distinct between units.
         key: name.bytes().map(u64::from).sum(),
         top_centre: (500.0, 400.0),
         health,
@@ -68,11 +58,8 @@ fn drive(s: &mut UiScript, states: &[PlateState]) {
     s.resolve();
 }
 
-/// pfUI + ShaguTweaks share one lineage: `GetNumChildren` grew, so walk the tail.
-///
-/// `initialized` is never reset in either addon, so a client whose child list SHRANK or REORDERED
-/// would make them miss every plate created after the old high-water mark — permanently, and with
-/// no error. This is the test that a retired plate keeps its slot.
+/// pfUI and ShaguTweaks walk only the children past a count they never reset, so the list must not
+/// shrink or reorder: a retired plate keeps its slot.
 #[test]
 fn the_worldframe_child_list_only_grows_and_keeps_its_order() {
     let mut s = vm();
@@ -90,7 +77,7 @@ fn the_worldframe_child_list_only_grows_and_keeps_its_order() {
         2
     );
 
-    // One unit leaves: the plate is HIDDEN, and the child list does not shrink.
+    // One unit leaves: its plate hides, and the list keeps its length.
     drive(&mut s, &[plate("Wolf", 30.0, 40.0)]);
     assert_eq!(
         s.eval::<i64>("return WorldFrame:GetNumChildren()").unwrap(),
@@ -102,7 +89,7 @@ fn the_worldframe_child_list_only_grows_and_keeps_its_order() {
         )
         .unwrap());
 
-    // A third unit arrives: it takes the pooled plate back — the count goes to 2, not 3.
+    // A new unit takes the pooled plate back: the count stays 2.
     drive(
         &mut s,
         &[plate("Wolf", 30.0, 40.0), plate("Boar", 5.0, 50.0)],
@@ -114,12 +101,8 @@ fn the_worldframe_child_list_only_grows_and_keeps_its_order() {
     assert_eq!(s.nameplate_pool_len(), 2);
 }
 
-/// pfUI's `IsNamePlate` (`nameplates.lua:70`) and ShaguTweaks' (`libnameplate.lua:12`), verbatim in
-/// shape: the object type is `"Button"`, and region #1 is a `Texture` whose `GetTexture()` is
-/// exactly `Interface\Tooltips\Nameplate-Border`.
-///
-/// `CustomNameplates` runs the texture half against **every** WorldFrame child
-/// (`CustomNameplates.lua:93`), so `GetRegions()` must also be safe to call on a frame with none.
+/// pfUI's `IsNamePlate` (`nameplates.lua:70`) and ShaguTweaks' (`libnameplate.lua:12`): a `Button`
+/// whose first region is a `Texture` reading `Interface\Tooltips\Nameplate-Border`.
 #[test]
 fn a_plate_identifies_by_button_plus_the_border_texture() {
     let mut s = vm();
@@ -138,12 +121,8 @@ fn a_plate_identifies_by_button_plus_the_border_texture() {
         .unwrap());
 }
 
-/// The two tuples, positionally — the ABI decision 2148 §3 records.
-///
-/// `CustomNameplates.lua:212` binds `Border, Glow, Name, Level, Boss, RaidTargetIcon`; pfUI and
-/// ShaguTweaks bind the same six by the `NAMEPLATE_OBJECTORDER` table. A **seventh** region is a
-/// bug (pfUI blanks any extra with `SetTexture("")`), and a **second** child is a bug too (pfUI
-/// destructures `healthbar, castbar` and would blank ours as a TBC cast bar).
+/// Six regions in `CustomNameplates.lua:212`'s order (`Border, Glow, Name, Level, Boss,
+/// RaidTargetIcon`) and one child; pfUI blanks a seventh region, and a second child as a cast bar.
 #[test]
 fn the_region_and_child_tuples_are_six_and_one() {
     let mut s = vm();
@@ -173,8 +152,8 @@ fn the_region_and_child_tuples_are_six_and_one() {
         "#
         )
         .unwrap());
-    // ShaguTweaks `libnameplate.lua:39`: `plate.healthbar = plate:GetChildren()` — one child, and
-    // it is the StatusBar. Its own single region is the fill `GetStatusBarTexture()` hands back.
+    // `libnameplate.lua:39` takes the one child as the health bar: a StatusBar whose only region
+    // is its fill.
     assert!(s
         .eval::<bool>(
             r#"
@@ -189,10 +168,8 @@ fn the_region_and_child_tuples_are_six_and_one() {
         .unwrap());
 }
 
-/// `_Nameplates.Nameplate.Initialize` (`_Nameplates.lua:163`) is the strictest consumer: it
-/// content-addresses the regions and **validates the two FontString anchors**, rejecting any plate
-/// whose name is not `BOTTOM`→`CENTER` and whose level is not `CENTER`→`BOTTOMRIGHT`. Those are the
-/// reference's own (ctor `0x7cb456`, bind `0x7cb7f5`).
+/// `_Nameplates.lua:163` rejects a plate unless its name is anchored `BOTTOM` to `CENTER` and its
+/// level `CENTER` to `BOTTOMRIGHT`, the reference's own anchors (`0x7cb456`, `0x7cb7f5`).
 #[test]
 fn the_two_fontstring_anchors_are_what_nameplates_validates() {
     let mut s = vm();
@@ -215,12 +192,8 @@ fn the_two_fontstring_anchors_are_what_nameplates_validates() {
         .unwrap());
 }
 
-/// The bar reports **raw** health, not a fraction — `GetValue 0x78f5d0` → `[bar+0x320]`, and
-/// `GetMinMaxValues` → `(0, maxHealth)`. pfUI (`:595`) and CustomNameplates (`:471`) both divide,
-/// so a fraction here would read as full health on every plate.
-///
-/// This one corrected wow-re's own note: `nameplate-vkey.md` §4 had recorded `0x783380`, which is
-/// the internal fill *fraction*, as the Lua getter.
+/// `GetValue` (`0x78f5d0`) is raw health, `[bar+0x320]`, not the fill fraction (`0x783380`), and
+/// `GetMinMaxValues` is `(0, maxHealth)`; pfUI (`:595`) and CustomNameplates (`:471`) divide them.
 #[test]
 fn the_healthbar_reports_raw_health_and_its_max() {
     let mut s = vm();
@@ -236,8 +209,7 @@ fn the_healthbar_reports_raw_health_and_its_max() {
         .unwrap());
 }
 
-/// The plate is anonymous. `_Nameplates.lua:164` rejects any WorldFrame child with a name, and
-/// pfUI's bubble filter does the same — a named plate is invisible to both.
+/// `_Nameplates.lua:164` and pfUI's bubble filter skip any WorldFrame child with a name.
 #[test]
 fn a_plate_is_anonymous() {
     let mut s = vm();
@@ -247,9 +219,8 @@ fn a_plate_is_anonymous() {
         .unwrap());
 }
 
-/// The pooling contract: a retired plate comes back as the **same Lua object**. Every addon keys
-/// its per-plate state off exactly that identity — pfUI's `registry[plate]` (`:342`),
-/// `_Nameplates.Frames[Nameplate]` (`:205`) — and re-runs `OnCreate` for an object it has not seen.
+/// Addons key per-plate state on the plate object: pfUI's `registry[plate]` (`:342`) and
+/// `_Nameplates.Frames[Nameplate]` (`:205`).
 #[test]
 fn a_retired_plate_returns_as_the_same_lua_object() {
     let mut s = vm();
@@ -262,14 +233,8 @@ fn a_retired_plate_returns_as_the_same_lua_object() {
         .unwrap());
 }
 
-/// **A plate belongs to its UNIT, not to this frame's sort order.**
-///
-/// The driver hands plates over in distance-sorted order — the seat priority the reference solves
-/// overlap in — and that order changes whenever two units cross. If the pool were indexed by it,
-/// widget #1 would swap units mid-session, and every addon that caches state on the frame would be
-/// reading the other unit's: pfUI's `nameplate.original.name`/`level`, its `registry[plate]`
-/// bookkeeping, `_Nameplates`' per-plate button. So the pool is keyed by the unit's GUID, and this
-/// is the test that says so.
+/// The pool is keyed by the unit's GUID, not by the driver's distance order, which changes when two
+/// units cross; addons cache per-unit state on the plate.
 #[test]
 fn a_plate_belongs_to_its_unit_across_a_sort_order_swap() {
     let mut s = vm();
@@ -289,8 +254,7 @@ fn a_plate_belongs_to_its_unit_across_a_sort_order_swap() {
     .unwrap();
     assert!(s.eval::<bool>("return WolfPlate ~= nil").unwrap());
 
-    // The two units cross: the driver now sorts Bear first. Nothing about either plate's identity
-    // may move with it.
+    // The units cross: the driver now sorts Bear first.
     drive(
         &mut s,
         &[plate("Bear", 10.0, 90.0), plate("Wolf", 30.0, 40.0)],
@@ -305,8 +269,8 @@ fn a_plate_belongs_to_its_unit_across_a_sort_order_swap() {
         .unwrap());
 }
 
-/// `plate:GetAlpha() == 1` is how pfUI (`:879`) and CustomNameplates (`:287`) detect the TARGET
-/// plate: with a target up, every other plate is dimmed. So alpha is a contract, not a look.
+/// pfUI (`:879`) and CustomNameplates (`:287`) find the target plate as the one at alpha 1; with a
+/// target up, every other plate is dimmed.
 #[test]
 fn the_target_plate_is_the_opaque_one() {
     let mut s = vm();
@@ -322,9 +286,8 @@ fn the_target_plate_is_the_opaque_one() {
         .unwrap());
 }
 
-/// pfUI hooks the bar's `OnValueChanged` (`:393`) and reads `this:GetParent()` inside the handler
-/// to find the plate. The driver moves that value from Rust, so the handler has to fire from there
-/// too — the reference's own bar is driven by a GUID-watch callback and fires it the same way.
+/// pfUI's bar `OnValueChanged` (`:393`) finds the plate by `this:GetParent()`; the reference sets
+/// the bar from a GUID-watch callback that fires the handler, as the driver's write does here.
 #[test]
 fn an_engine_health_write_fires_onvaluechanged_with_the_plate_as_parent() {
     let mut s = vm();
@@ -350,10 +313,8 @@ fn an_engine_health_write_fires_onvaluechanged_with_the_plate_as_parent() {
     assert_eq!(s.eval::<i64>("return Fired").unwrap(), 1);
 }
 
-/// **An addon takes the plate over.** pfUI blanks all six regions (`DisableObject` →
-/// `SetTexture("")`) and paints its own art; ShaguTweaks reparents the raid icon. A driver that
-/// re-stamped every property every frame would undo that at 60 Hz — so static properties are
-/// written once, at creation, and never again.
+/// The driver writes a plate's static properties once, at creation, so an addon's takeover (pfUI
+/// blanks all six regions, ShaguTweaks reparents the raid icon) survives.
 #[test]
 fn the_driver_does_not_overwrite_an_addons_takeover() {
     let mut s = vm();
@@ -367,7 +328,7 @@ fn the_driver_does_not_overwrite_an_addons_takeover() {
     "#,
     )
     .unwrap();
-    // Several frames of ordinary driving — health moving, the unit renamed, the plate re-seated.
+    // Several frames of driving: health moves and the plate re-seats.
     for hp in [29.0, 28.0, 27.0] {
         let mut state = plate("Wolf", hp, 40.0);
         state.top_centre = (500.0 + hp, 400.0);
@@ -383,18 +344,9 @@ fn the_driver_does_not_overwrite_an_addons_takeover() {
         .unwrap());
 }
 
-/// **A hovered plate wears no black box** — the defect the widget port shipped (director report,
-/// 2026-09-10: "they look totally fucked when I hover or click them"), and the two halves that
-/// keep it fixed.
-///
-/// `Nameplate-Glow.blp` is DXT1 with **no alpha channel** and 80.5% pure-black texels. The
-/// reference blends it `ADD` (`push 3` @`0x7cb36a`); blitted with straight `BLEND` it is an opaque
-/// rectangle over the entire plate — which is exactly what the ctor's default mode produced here.
-/// 0184 is the director's call that benilla paints **no rim at all**, so the region has to be ADD
-/// *and* emit nothing, while staying shown and textured for the addons that read it.
-///
-/// The border assert is not decoration: without it the test would pass on an extract that produced
-/// no quads whatsoever.
+/// The glow art has no alpha and is mostly black, so the reference blends it ADD (`0x7cb36a`); as
+/// BLEND it is an opaque box. Deviation: we paint no rim, which reads as hard edges in our
+/// pipeline, but the region stays shown, ADD and textured. The border check fails an empty extract.
 #[test]
 fn a_hovered_plate_emits_no_glow_quad() {
     use crate::script::QuadContent;
@@ -404,7 +356,6 @@ fn a_hovered_plate_emits_no_glow_quad() {
     p.lit = true;
     drive(&mut s, &[p]);
 
-    // The model tells the truth: shown, textured, and the reference's own blend mode.
     assert!(s
         .eval::<bool>(
             r#"local _, glow = WorldFrame:GetChildren():GetRegions()
@@ -432,23 +383,9 @@ fn a_hovered_plate_emits_no_glow_quad() {
     );
 }
 
-/// **The plate's name and level seat off the UI pixel grid** (decision 2172).
-///
-/// The plate is a WorldFrame overlay: the driver snaps its rect to the DEVICE pixel grid
-/// (`vplates::device_snap` — half a logical pixel at 2×) because it slides continuously over the
-/// world, and everything drawn inside it has to be rigid to that. The renderer's UI seat snap
-/// quantizes a text block's top on the coarser LOGICAL grid, so with both laws in force the name
-/// and the level pop a whole pixel every second step the border takes.
-///
-/// The painter this port replaced never snapped them — it measured into degenerate rects, which
-/// the renderer's carve-out skips — so this flag is what carries that seating law across decision
-/// 2148's move into the frame system. It rides the extract, one field per Text quad, because the
-/// renderer is the only thing that can act on it.
-///
-/// It is answered from the OWNER, which is why the third block here matters: pfUI and
-/// ShaguTweaks blank the stock regions and hang their own FontStrings on the plate, and a rule
-/// written on our six regions would have left an addon's strings jittering inside a plate whose
-/// own text had stopped.
+/// Text on a plate skips the UI grid snap: the plate's rect snaps to the finer device grid as it
+/// slides, and a text top snapped to the logical grid would jump a pixel against it. The flag is
+/// the owning frame's, so an addon's own string on the plate gets it too.
 #[test]
 fn the_plates_texts_carry_the_world_seat_and_its_textures_do_not() {
     use crate::script::QuadContent;
@@ -473,8 +410,7 @@ fn the_plates_texts_carry_the_world_seat_and_its_textures_do_not() {
         "the plate draws exactly its name and level, both seated off the UI grid"
     );
 
-    // A FontString on an ordinary frame is interface, and interface is ON the grid — the flag has
-    // to be the plate's claim, not something every string picked up.
+    // A FontString on an ordinary frame stays on the grid.
     s.run(
         r#"local f = CreateFrame("Frame", "Chrome", UIParent) f:SetAllPoints()
            local t = f:CreateFontString("ChromeText") t:SetAllPoints() t:SetText("Chrome")"#,
@@ -486,8 +422,7 @@ fn the_plates_texts_carry_the_world_seat_and_its_textures_do_not() {
         QuadContent::Text { text: Some(t), world_seat: false, .. } if t == "Chrome"
     )));
 
-    // An addon's own string on the plate — pfUI's whole vanilla branch — is drawn inside the same
-    // sliding rect, so it gets the same seat.
+    // An addon's own string on the plate, as pfUI draws its text, gets the same seat.
     s.run(
         r#"local plate = WorldFrame:GetChildren()
            local t = plate:CreateFontString() t:SetAllPoints() t:SetText("pfName")"#,
@@ -503,11 +438,7 @@ fn the_plates_texts_carry_the_world_seat_and_its_textures_do_not() {
     );
 }
 
-/// The suppression is **the reference's own glow art on an ADD region**, and nothing wider: an
-/// addon that re-textures the region gets its art painted like any other texture.
-///
-/// pfUI's vanilla branch does exactly this — it blanks the six regions and paints its own — so a
-/// blanket "plate glow regions never draw" would silently eat an addon's work.
+/// Only the stock glow art on an ADD region goes unpainted; an addon's own glow texture paints.
 #[test]
 fn an_addon_that_retextures_the_glow_gets_its_art_painted() {
     use crate::script::QuadContent;
@@ -532,10 +463,8 @@ fn an_addon_that_retextures_the_glow_gets_its_art_painted() {
         .any(|p| p.contains("pfUI")));
 }
 
-/// pfUI reads `glow:IsShown()` as the MOUSEOVER signal (`:601`, `:880`). benilla does not paint the
-/// additive rim (0184 — it read as hard edge lines on our pipeline, and the director pinned a bar
-/// brighten instead), but the region is structurally present and really shown, because the
-/// deviation is about pixels and this is about data.
+/// pfUI reads `glow:IsShown()` as the mouseover signal (`:601`, `:880`), so the glow shows on hover
+/// though it paints nothing.
 #[test]
 fn the_glow_region_is_the_mouseover_signal() {
     let mut s = vm();
@@ -555,9 +484,8 @@ fn the_glow_region_is_the_mouseover_signal() {
         .unwrap());
 }
 
-/// The level number and the skull share one seat and are mutually exclusive — `skull` is how the
-/// driver says "world boss, or ten levels up". pfUI gates on `levelicon:IsShown()` and
-/// CustomNameplates on `Boss:IsVisible()`, so both flags have to move.
+/// The level and the skull (a world boss, or ten levels up) share one seat; pfUI reads
+/// `levelicon:IsShown()` and CustomNameplates `Boss:IsVisible()`.
 #[test]
 fn the_skull_replaces_the_level_number() {
     let mut s = vm();
@@ -575,9 +503,7 @@ fn the_skull_replaces_the_level_number() {
         .unwrap());
 }
 
-/// **A unit whose level has not arrived is not a world boss.** `level: None` with no skull leaves
-/// the seat EMPTY — the old painter's behaviour, which the widget port inverted by making one
-/// `Option` carry both facts (audit, 2026-09-10).
+/// A level not yet known, with no skull, leaves the seat empty.
 #[test]
 fn a_unit_with_no_level_yet_wears_no_skull() {
     let mut s = vm();
@@ -594,15 +520,11 @@ fn a_unit_with_no_level_yet_wears_no_skull() {
         .unwrap());
 }
 
-/// **A plate the pool grows on any frame but the first is laid out too.** The lay-out used to ride
-/// a per-frame "did the window move?" flag, so a unit that walked into range later got a plate with
-/// no size and no anchors: invisible, permanently, and the number of plates on screen was capped at
-/// however many were up when V was first pressed (audit, 2026-09-10).
 #[test]
 fn a_plate_created_after_the_first_frame_is_laid_out() {
     let mut s = vm();
     drive(&mut s, &[plate("Wolf", 30.0, 40.0)]);
-    // A second unit arrives on a LATER frame, with no free slot and no geometry change.
+    // A second unit on a later frame, with no free slot and no geometry change.
     drive(
         &mut s,
         &[plate("Wolf", 30.0, 40.0), plate("Bear", 10.0, 90.0)],
@@ -611,7 +533,7 @@ fn a_plate_created_after_the_first_frame_is_laid_out() {
         .eval("local _, b = WorldFrame:GetChildren() return b:GetWidth(), b:GetHeight()")
         .unwrap();
     assert_eq!((w, h), (128.0, 32.0), "the second plate has the plate size");
-    // …and its regions are anchored to it, which is what `GetLeft` answering at all proves.
+    // Its regions are anchored to it, or `GetLeft` would not answer.
     assert!(s
         .eval::<bool>(
             r#"local _, b = WorldFrame:GetChildren()
@@ -621,9 +543,8 @@ fn a_plate_created_after_the_first_frame_is_laid_out() {
         .unwrap());
 }
 
-/// An addon's own frame parented to `WorldFrame` shares the list with the plates —
-/// `_NameplatesFrame` and `pfUICombatScreen` both are — which is why the identification test in
-/// §2 is load-bearing and why the count-grew heuristic re-scans. It must not be mistaken for one.
+/// An addon's frame under `WorldFrame` (`pfUICombatScreen`, `_NameplatesFrame`) shares the list
+/// with the plates, whose `GetName` is always nil (`0x7a1390`).
 #[test]
 fn an_addon_frame_under_the_worldframe_is_not_a_plate() {
     let mut s = vm();
@@ -653,11 +574,9 @@ fn an_addon_frame_under_the_worldframe_is_not_a_plate() {
     );
 }
 
-/// **The plate takes the mouse, and hands its unit back.** It is a `Button` and born mouse-enabled
-/// (`CSimpleButton`'s ctor writes `[+0xcc] = 0x4`), so hovering it makes it the mouse focus — which
-/// on this engine means the UI pointer pass owns the cursor and the world pick stands down. What
-/// keeps the mouseover alive is the seam: the widget layer answers WHICH unit's plate the pointer
-/// is inside, exactly as the reference's OnEnter (`0x7cb850`) publishes `[0xb4e2c8]`.
+/// A plate is a mouse-enabled `Button` (`CSimpleButton`'s constructor writes `[+0xcc] = 0x4`), so
+/// hovering it takes the mouse focus from the world; the widget layer then names the plate's unit,
+/// as the reference's OnEnter (`0x7cb850`) publishes `[0xb4e2c8]`.
 #[test]
 fn hovering_a_plate_names_its_unit() {
     let mut s = vm();
@@ -666,19 +585,16 @@ fn hovering_a_plate_names_its_unit() {
     drive(&mut s, &[wolf]);
 
     assert_eq!(s.hovered_nameplate(), None, "nothing hovered yet");
-    // The plate's TOP-CENTRE is (500, 400) and it hangs 32 units below, so this is its middle.
+    // The plate hangs 32 units below its top centre (500, 400), so this is its middle.
     s.mouse_move(500.0, 384.0);
     assert_eq!(s.hovered_nameplate(), Some(key));
-    // Off the plate: the WorldFrame takes the focus again, and no plate is named.
+    // Off the plate the WorldFrame takes the focus again.
     s.mouse_move(50.0, 50.0);
     assert_eq!(s.hovered_nameplate(), None);
 }
 
-/// A completed click on a plate reaches the app — the reference's click slot (`0x7cb910`), whose
-/// tail is the same `SetSelection` a click on the body runs.
-///
-/// **Mouse-UP only**: the plate registers `LeftButtonUp | RightButtonUp` (`RegisterForClicks(0x500)`
-/// at `0x7cb637`), so a press alone selects nothing.
+/// The reference's click slot (`0x7cb910`) ends in the same `SetSelection` as a click on the body,
+/// and fires on the up edge only: `RegisterForClicks(0x500)` at `0x7cb637`.
 #[test]
 fn a_completed_click_on_a_plate_reaches_the_app() {
     let mut s = vm();
@@ -703,15 +619,9 @@ fn a_completed_click_on_a_plate_reaches_the_app() {
     );
 }
 
-/// **The right button too** — `RegisterForClicks(0x500)` is LeftButtonUp | **RightButtonUp**
-/// (`0x7cb637` → `[this+0x330]`), and the reference's slot forks on it: mask 1 → `0x4925d0`
-/// select, mask 4 → `0x492820` select **and interact** (decision 2233, wow-re
-/// `ui/scratch/mouselook-mouseover-and-nameplate-click-law.md` §6.4).
-///
-/// The regression this pins: a plate is created as a plain `Button`, whose default registered set
-/// is `{"LeftButtonUp"}` alone, so the release was refused before the click funnel — and with 2233
-/// taking the camera off a press that lands on a plate, that left right-clicking a nameplate doing
-/// nothing whatsoever.
+/// `0x500` includes RightButtonUp (`0x7cb637` writes `[this+0x330]`), where a plain `Button`
+/// registers LeftButtonUp alone; the slot forks on the mask: 1 selects (`0x4925d0`), 4 selects and
+/// interacts (`0x492820`).
 #[test]
 fn a_physical_right_click_on_a_plate_reaches_the_app() {
     let mut s = vm();
@@ -732,8 +642,6 @@ fn a_physical_right_click_on_a_plate_reaches_the_app() {
     assert_eq!(clicks[0].button, "RightButton");
 }
 
-/// A button the plate never registered fires nothing — the mask is exactly `0x500`, not "any
-/// button".
 #[test]
 fn a_middle_click_on_a_plate_fires_nothing() {
     let mut s = vm();
@@ -747,10 +655,8 @@ fn a_middle_click_on_a_plate_fires_nothing() {
     );
 }
 
-/// pfUI's click-through calls `plate:Click("LeftButton")` (`nameplates.lua:1274`), and
-/// CustomNameplates and `_Nameplates` do the same. A scripted click has to select the unit like a
-/// physical one — in the reference both go through the button's one click slot, and here they go
-/// through the one funnel that slot's twin lives on.
+/// pfUI's click-through (`nameplates.lua:1274`) calls `plate:Click`; in the reference a scripted
+/// and a physical click go through the button's one click slot.
 #[test]
 fn a_scripted_click_selects_too() {
     let mut s = vm();
@@ -765,15 +671,9 @@ fn a_scripted_click_selects_too() {
     assert_eq!(clicks[0].button, "RightButton");
 }
 
-/// **The mouselook toggle** (`0x60f830`): entering freelook hands the mouse back on every plate,
-/// leaving takes it again — the reference walks its own intrusive plate list doing exactly this,
-/// from `0x483e80` (enter) and `0x483e70` (leave).
-///
-/// **What it is for is NOT "a drag that begins over a plate"** — that gesture never reaches
-/// mouselook at all, because `0x7662c0` hands the mouse-down to the plate and stops the bus walk
-/// before any binding runs (decision 2233, which reversed the inference this doc used to carry).
-/// It is for a turn that started on the **world** and then dragged the pointer across a plate: the
-/// plates must not take a pointer that is hidden and locked to the camera.
+/// Entering mouselook turns the mouse off on every plate and leaving turns it back on (`0x60f830`,
+/// from `0x483e80` and `0x483e70`), for a turn begun on the world that drags across a plate; a
+/// press on a plate never reaches mouselook (`0x7662c0`).
 #[test]
 fn freelook_hands_the_mouse_back() {
     let mut s = vm();
@@ -797,14 +697,9 @@ fn freelook_hands_the_mouse_back() {
     );
 }
 
-/// **The plate's own `+0x3c` veto** (`0x7cba30`) — a DIFFERENT mechanism from the freelook toggle
-/// above, and the reason it is not folded into the same flag.
-///
-/// While a ground-targeted spell is armed the plate refuses the hit test *before* testing its rect
-/// (`0x6e48a0() && 0x6e6320() && !0x6e6180()` → `xor eax,eax; ret 4`, never calling the base), so
-/// the point falls through to the `WorldFrame` at (strata 0, level 0) behind it and the reticle can
-/// be placed through a plate. Crucially it never touches `[+0xcc]`: `IsMouseEnabled()` still
-/// answers **true** throughout, which is exactly what `0x60f830` does not do.
+/// The plate's `+0x3c` hit test (`0x7cba30`) refuses the point while a ground-targeted spell is
+/// armed (`0x6e48a0() && 0x6e6320() && !0x6e6180()`), so it falls through to the `WorldFrame`.
+/// It never touches `[+0xcc]`: `IsMouseEnabled` stays true, unlike under mouselook (`0x60f830`).
 #[test]
 fn a_ground_target_veto_refuses_the_hit_without_disabling_the_mouse() {
     let mut s = vm();
@@ -819,15 +714,13 @@ fn a_ground_target_veto_refuses_the_hit_without_disabling_the_mouse() {
         None,
         "the reticle must be placeable through a plate"
     );
-    // …and the press falls through with it, which is what lets the WorldFrame win the gesture and
-    // the ground cast commit where the player clicked.
+    // The press falls through too, so the WorldFrame takes the ground cast.
     s.mouse_button(500.0, 384.1, "LeftButton", true);
     s.mouse_button(500.0, 384.1, "LeftButton", false);
     assert!(
         s.take_nameplate_clicks().is_empty(),
         "a vetoed plate takes no click either"
     );
-    // The bit the veto must NOT have touched — an addon asking is told the truth.
     assert_eq!(
         s.eval::<i64>("local p = WorldFrame:GetChildren() return p:IsMouseEnabled()")
             .unwrap(),
diff --git a/crates/benilla-ui/src/script/tests/numeric_shape_gate.rs b/crates/benilla-ui/src/script/tests/numeric_shape_gate.rs
index 5115ea16..7aa212c7 100644
--- a/crates/benilla-ui/src/script/tests/numeric_shape_gate.rs
+++ b/crates/benilla-ui/src/script/tests/numeric_shape_gate.rs
@@ -1,33 +1,9 @@
-//! **Shape C, closed as a CLASS**: every numeric position wow-re's
-//! `system/ui/scratch/numeric-arg-coercion-law.md` records as shape C must take a `nil` — or a
-//! table, or a string — as **0.0** and complete, because the reference reads it with a bare
-//! `lua_tonumber 0x6f3620` and no `lua_isnumber` gate at all.
-//!
-//! The law's own framing is why this is one test and not six: *"which shape a given argument takes
-//! is per binding, not a global law"* — it censused all 408 widget-registrar positions (110 gated,
-//! 64 ungated) precisely so a re-implementation could be checked against a table rather than an
-//! instinct. Our half of that table had drifted: 1973 closed `SetTextColor` and left every sibling
-//! strict, so mlua's converter went on being the gate for five more years' worth of call sites.
-//!
-//! The live symptom that forced the audit: stock `QuestLogFrame.lua:337` does
-//! `QuestLogSkillHighlight:SetVertexColor(titleButton.r, titleButton.g, titleButton.b)`, and those
-//! three fields are only ever assigned in `QuestLog_Update` — so **any** path that selects a
-//! quest-log entry before the window has painted hands `SetVertexColor` three nils. Questie's
-//! `syncQuestWatch` (`QuestieTracker.lua:1160`) is exactly such a path: it calls
-//! `QuestLog_SetSelection` first. On the reference that is a no-op that stores black; for us it
-//! raised, and because the raise happened inside Questie's own event-queue drain — which nils an
-//! entry only *after* its handler returns — the queue jammed at that entry permanently. Every
-//! later entry (`SYNCLOG`, `DRAWNOTES`, `TRACKER`) was stranded for the rest of the session, which
-//! is why the minimap button's right-click could turn the quest icons OFF (a direct call) but
-//! never back ON (a `DRAWNOTES` enqueue).
-//!
-//! **Shape B is not shape C and is not tested here.** The alpha slot of every colour setter is B —
-//! a pre-staged default, `1.0f` at `0x778220` — so its absence is a *default*, not a zero, and
-//! `SetVertexColor`'s own B-slot carries a separate, deliberately-open divergence (1782).
+//! Shape C: a numeric position the reference reads with a bare `lua_tonumber` (`0x6f3620`) and no
+//! `lua_isnumber` gate, so nil, a table or a string is 0.0 and the call completes. Shape B, not
+//! tested here, is a pre-staged default, such as every colour setter's alpha (1.0 at `0x778220`).
 
 use super::common::script;
 
-/// Each row: the Lua that must not raise, and what a reader must say afterwards.
 #[test]
 fn every_shape_c_colour_position_takes_nil_as_zero_and_never_raises() {
     let s = script();
@@ -42,7 +18,7 @@ fn every_shape_c_colour_position_takes_nil_as_zero_and_never_raises() {
     )
     .unwrap();
 
-    // `Texture:SetVertexColor 0x79abd0` — `2=C 3=C 4=C`. The QuestLogFrame.lua:337 shape verbatim.
+    // `Texture:SetVertexColor 0x79abd0` (`2=C 3=C 4=C`), as stock `QuestLogFrame.lua:337` calls it.
     s.run("T:SetVertexColor(nil, nil, nil)")
         .expect("SetVertexColor(nil,nil,nil) is three bare lua_tonumbers, not a raise");
     s.run(
@@ -52,11 +28,11 @@ fn every_shape_c_colour_position_takes_nil_as_zero_and_never_raises() {
         "#,
     )
     .unwrap();
-    // A table and a string are the same 0.0 — `lua_tonumber` tests nothing.
+    // A table and a string are 0.0 too: `lua_tonumber` tests nothing.
     s.run("T:SetVertexColor({}, \"abc\", true)")
         .expect("no tag is rejected at a shape-C position");
 
-    // `Texture:SetTexCoord 0x79beb0` — every coordinate C; only the ARITY raises.
+    // `Texture:SetTexCoord 0x79beb0`: every coordinate C; only the arity raises.
     s.run("T:SetTexCoord(nil, nil, nil, nil)")
         .expect("four nil coordinates are four zeroes");
     s.run("T:SetTexCoord(0, 1, 0, 1, 0, 1, 0, 1)")
@@ -77,18 +53,17 @@ fn every_shape_c_colour_position_takes_nil_as_zero_and_never_raises() {
     )
     .unwrap();
 
-    // `ColorSelect:SetColorRGB 0x78eae0` — C on all three, and it fires OnColorSelect either way.
+    // `ColorSelect:SetColorRGB 0x78eae0`: C on all three; it fires OnColorSelect either way.
     s.run("CS:SetColorRGB(nil, nil, nil)")
         .expect("ColorSelect:SetColorRGB is shape C on r/g/b");
 
-    // `Texture:SetGradient 0x79ae30` / `SetGradientAlpha 0x79b180` — already C before this pass;
-    // pinned so they cannot regress into the family's old strictness.
+    // `Texture:SetGradient 0x79ae30` and `SetGradientAlpha 0x79b180`.
     s.run("T:SetGradient(\"HORIZONTAL\", nil, nil, nil, nil, nil, nil)")
         .expect("SetGradient's six stops are all C");
     s.run("T:SetGradientAlpha(\"VERTICAL\", nil, nil, nil, nil, nil, nil, nil, nil)")
         .expect("SetGradientAlpha's eight are C/B");
 
-    // `FontString:SetTextColor 0x79d9c0` — closed by 1973; pinned here so the class stays closed.
+    // `FontString:SetTextColor 0x79d9c0`.
     s.run("FS:SetTextColor(nil, nil, nil)")
         .expect("the sibling 1973 already fixed");
 }
diff --git a/crates/benilla-ui/src/script/tests/object_model.rs b/crates/benilla-ui/src/script/tests/object_model.rs
index 87f4a26b..29a137b7 100644
--- a/crates/benilla-ui/src/script/tests/object_model.rs
+++ b/crates/benilla-ui/src/script/tests/object_model.rs
@@ -1,4 +1,4 @@
-//! The frame object model (RF-0023).
+//! The frame object model (`0x701bd0`).
 
 use super::common::script;
 
diff --git a/crates/benilla-ui/src/script/tests/reference_surface.rs b/crates/benilla-ui/src/script/tests/reference_surface.rs
index cdd871b1..f45f05d7 100644
--- a/crates/benilla-ui/src/script/tests/reference_surface.rs
+++ b/crates/benilla-ui/src/script/tests/reference_surface.rs
@@ -1,21 +1,6 @@
-//! **The 1.12 surface is the contract** (decisions 1188 §2, 1189) — enforced here rather than
-//! trusted to memory.
-//!
-//! benilla targets the 1.12.1 API. Anything beyond it is a *listed, justified* exception, and the
-//! point of this file is that the list cannot go unknown: every global our VM exposes must either
-//! be one 1.12 has, or appear below with a reason. A session that adds an Era-shaped verb has to
-//! delete or extend an assertion that says why not — which is exactly what did not happen when
-//! 1187 shipped eight Era globals on Era's authority and 1189 had to take them back out.
-//!
-//! **Why a superset is not free.** Lua branches on presence. An addon writing `if strmatch then`
-//! takes a path we cannot honour, and the failure surfaces far from the cause. Extra functions are
-//! harmless only if nothing feature-detects, which is not true of this ecosystem.
-//!
-//! The reference side is `reference/1.12-globals.tsv` — the running 1.12.1 client's own in-world
-//! `_G` (see `reference/README.md`). This test reads the `engine` and `lua` rows: the surface a VM
-//! is responsible for. It deliberately does **not** assert the converse — that we have everything
-//! 1.12 has — because that is a multi-year backlog, not a regression gate;
-//! `scripts/api-coverage.sh` is where that number is read.
+//! The 1.12 surface as a gate: every global benilla's VM exposes is one the 1.12.1 client has
+//! (`reference/1.12-globals.tsv`) or a listed exception, since addons branch on a global's
+//! presence; what 1.12 has and benilla lacks is `scripts/api-coverage.sh`'s count.
 
 use std::collections::HashSet;
 
@@ -39,72 +24,17 @@ fn reference() -> Vec<(String, String)> {
         .collect()
 }
 
-/// Names benilla exposes that 1.12 does not, each with the reason it is allowed to stay.
-///
-/// **`Benilla*` and `__benilla_*` are covered by prefix**, not enumerated: the first is our host
-/// bridge (verbs only our own transcribed FrameXML calls — a paperdoll model's facing, an item's
-/// stat block) and the second is the tick's pushed state. Neither is an API-target claim, and
-/// neither is reachable by accident from an addon that means to call a WoW function.
+/// Globals benilla exposes that 1.12 does not. `Benilla*` (the host bridge our own UI files call)
+/// and `__benilla_*` (the tick's pushed state) pass by prefix.
 fn allowed_beyond_1_12() -> HashSet<&'static str> {
     [
-        // ── our Lua runtime is 5.1 where 1.12's is 5.0 ────────────────────────────────────────
-        // `_G` is the last of these inherited rather than chosen: 1.12's base library does not
-        // export it (an addon reaches the globals with `getfenv(0)`, which is what AceLibrary
-        // does), but our own `getglobal`/`setglobal` are written over it. Closing it means
-        // rewriting those against the registry first.
-        //
-        // **This list has been shrinking as the dialect got measured**: `coroutine` left in 1194
-        // with the 5.1-only members of `string`/`table`/`math`; `print` and `_VERSION` left in
-        // 1197, when the RE dispatch read the base library's 36-entry array and neither was in it.
-        // `select` left last, and it is the one that shows what a written reason is worth — it
-        // carried two and outlived both. The first ("our transcribed FrameXML uses it in 16 files
-        // as the 5.1 spelling of 5.0's implicit `arg` table") was retired by 1751's migration and
-        // caught by 2142's census at *zero* sites. The second, written in its place, was that
-        // removing it meant giving up the 5.1 varargs it comes with — which 2101 had already given
-        // up, three days earlier, in the parser. A reason nobody re-derives is a reason with an
-        // expiry date; this list's job is to make the expiry visible, and twice it did not.
-        // The list only ever covered globals — the members needed `dump_globals --members` before
-        // anyone could see them at all.
+        // ── our Lua runtime is 5.1 where 1.12's is 5.0 ──
+        // 1.12's base library does not export `_G` (an addon reaches the globals with
+        // `getfenv(0)`); ours does, as our `getglobal`/`setglobal` are written over it.
         "_G",
-        // ── WoW API past 1.12 — 1188 phase 5's list, and the reason that phase exists ─────────
-        // **The reason written here was "every one of these is used by our own transcribed
-        // FrameXML today", and as of 2026-09-09 that is true of exactly ONE of the sixteen**
-        // (`SubmitChatInput`, in the dev-only `ScriptLogFrame.xml`) — a corpus census measured it
-        // and this file's own claim was checked against `assets/ui`'s seven remaining files, name
-        // by name, before this comment was rewritten (decision 2142). 1751's migration retired the
-        // windows that used the rest; the list outlived its justification, which is exactly how
-        // 2118 found the modifier keys still answering booleans years after 0068's reason for it
-        // had gone.
-        //
-        // **What they are NOT is load-bearing for the addon corpus, and 2143 corrects 2142 for
-        // saying so.** The claim written here was that the vanilla ecosystem assumes several of
-        // these exist — `pfUI/modules/loot.lua` calling `wipe` 25 times and defining it nowhere,
-        // so ours "makes that module run at all". That is wrong twice over, and the error is
-        // instructive: **a "1.12 addon" in that corpus is usually a MULTI-CLIENT addon**. pfUI
-        // ships one codebase for three clients and gates per module —
-        // `pfUI:RegisterModule("loot", "vanilla:tbc", …)`, matched by
-        // `strfind(version, pfUI.expansion)` at `pfUI.lua:250` — so a TBC-era habit sits in code
-        // the vanilla client reaches. The `wipe` calls are in `RequestRolls`,
-        // `BuildSpecialRecipientsMenu` and `ClearRolls`: the master-looter's roll helper, not the
-        // loot window, and that path throws on a real 1.12 client too. And `strsplit` was worse —
-        // pfUI has its own `pfUI.api.strsplit` (`api/api.lua:16`) and ShaguTweaks its own
-        // `ShaguTweaks.strsplit`; the bare calls are inside the vendored `libs/libpredict.lua`,
-        // which has TBC branches of its own.
-        //
-        // So our superset was HIDING those latent nil-calls, never enabling anything. The one
-        // real interaction left is the other direction: `AtlasLoot/Core/AtlasLoot.lua:2119`/`:2148`
-        // define GLOBAL `strsplit`/`strtrim` unconditionally, with incompatible pattern-based
-        // two-return semantics, and clobber ours for everything loaded after them — so ours is not
-        // authoritative at runtime either.
-        //
-        // Resolving each means replacing it with its 1.12 equivalent (`UnitPower` → `UnitMana`,
-        // which 1.12 has and we do not), deleting it, or recording why it stays.
-        //
-        // Three left with 1751's gossip work: `GetNumGossipQuests`, `GetGossipQuestInfo` and
-        // `SelectGossipQuest` were benilla's own single-list shape over the gossip packet's quest
-        // rows, and 1.12 has none of them — it publishes `GetGossipAvailableQuests` /
-        // `GetGossipActiveQuests` and a select for each, which is what this client answers now.
-        // The window that needed them is ours until it migrates; it calls the reference's four.
+        // ── WoW API past 1.12 ──
+        // Only `SubmitChatInput` is called from our UI files (`ScriptLogFrame.xml`'s slash
+        // commands); each of the rest awaits its 1.12 equivalent, removal or a reason.
         "CancelUnitBuff",
         "GetCursorInfo",
         "GetInventoryItemID",
@@ -121,9 +51,6 @@ fn allowed_beyond_1_12() -> HashSet<&'static str> {
 }
 
 /// Every global benilla's VM exposes is one 1.12 has, or a listed exception.
-///
-/// The failure message is the point: it names what is new and tells you the two ways out, so the
-/// next session cannot resolve it by deleting a bare assertion.
 #[test]
 fn our_globals_stay_inside_the_1_12_surface() {
     let reference = reference();
@@ -164,10 +91,7 @@ fn our_globals_stay_inside_the_1_12_surface() {
     );
 }
 
-/// The exception list is exact — no entry outlives the global it excuses.
-///
-/// Without this, a removed global leaves its excuse behind, and the list slowly stops describing
-/// the code. That is how a "listed, justified exception" decays into residue nobody can explain.
+/// The exception list is exact: no entry outlives its global, and none excuses a 1.12 name.
 #[test]
 fn the_exception_list_has_no_dead_entries() {
     let known: HashSet<String> = reference().into_iter().map(|(n, _)| n).collect();
@@ -193,7 +117,6 @@ fn the_exception_list_has_no_dead_entries() {
         dead.join(" ")
     );
 
-    // An entry that 1.12 turns out to have is a different bug: the excuse is wrong, not stale.
     let mut wrong: Vec<&str> = allowed_beyond_1_12()
         .into_iter()
         .filter(|n| known.contains(*n))
@@ -207,17 +130,8 @@ fn the_exception_list_has_no_dead_entries() {
     );
 }
 
-/// **`Texture:GetTexture()` — the three contract details that a plausible implementation gets
-/// silently wrong.** Verified in wow-re's widget-method batch (`0x79ba70`/`0x79baf0`/`0x835708`,
-/// `system/ui/scratch/widget-api-batch-benilla.md`).
-///
-/// Four corpus addons reach it: `AtlasQuest.lua:228` is `AQATLASMAP = AtlasMap:GetTexture()` and
-/// `FuBarPlugin-2.0.lua:343` is `return self.iconFrame:GetTexture()`, each behind two addons.
-///
-/// The colour case is the one worth a test of its own. `SetTexture(r,g,b)` synthesizes an 8x8 solid
-/// and the getter reports the literal name `"Solid Texture"` — so an addon's `if not tex then`
-/// guard passes straight through. Returning nil there would read as tidier and would be wrong in
-/// exactly the direction callers test for.
+/// `Texture:GetTexture()` (`0x79ba70`/`0x79baf0`/`0x835708`): one value, nil when unset, the path
+/// without its extension, and the literal `"Solid Texture"` for a colour fill.
 #[test]
 fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
     let s = crate::script::UiScript::new().unwrap();
@@ -230,22 +144,17 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
     )
     .unwrap();
 
-    // Never set: nil, and exactly one value.
     assert_eq!(
         s.eval::<Option<String>>("return GTFTex:GetTexture()")
             .unwrap(),
         None
     );
     assert_eq!(
-        // `.unwrap()`, not the `.unwrap_or(1)` this carried while it was spelled with `select`:
-        // that default made a raise indistinguishable from the answer being asserted, which is the
-        // one thing an arity check must not do (2171).
         s.arity("GTFTex:GetTexture()").unwrap(),
         1,
         "exactly one return value"
     );
 
-    // A path with no extension comes back unchanged.
     s.run(r#"GTFTex:SetTexture("Interface\\Icons\\Spell_Fire_FlameBolt")"#)
         .unwrap();
     assert_eq!(
@@ -253,8 +162,6 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
         "Interface\\Icons\\Spell_Fire_FlameBolt"
     );
 
-    // ...and one WITH an extension is stripped at the last `.` — the loader appends it, the getter
-    // takes it back off.
     s.run(r#"GTFTex:SetTexture("Interface\\Icons\\Foo.blp")"#)
         .unwrap();
     assert_eq!(
@@ -262,7 +169,6 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
         "Interface\\Icons\\Foo"
     );
 
-    // The colour form: the literal name, NOT nil.
     s.run("GTFFill:SetTexture(1, 0, 0, 1)").unwrap();
     assert_eq!(
         s.eval::<String>("return GTFFill:GetTexture()").unwrap(),
@@ -270,7 +176,6 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
         "a colour-filled region reports a NAME — `if not tex then` must not fire"
     );
 
-    // And a plain SetTexture makes it ordinary again.
     s.run(r#"GTFFill:SetTexture("Interface\\Buttons\\UI-Quickslot2")"#)
         .unwrap();
     assert_eq!(
@@ -279,17 +184,8 @@ fn get_texture_returns_the_stripped_path_and_solid_texture_for_a_fill() {
     );
 }
 
-/// **The shadow accessors on a REGION, and `GetShadowColor`'s four values.**
-///
-/// They existed on the font-object table; a FontString from `CreateFontString` had none, which is
-/// exactly where the corpus calls them. `FuBar_NavigatorFu/NavigatorFu.lua:31` is
-/// `coordText:SetShadowColor(GameFontNormal:GetShadowColor())` — getter on a font object, setter on
-/// a fresh region, in one line — and `KLHThreatMeter/.../KTM_Gui.lua:404` is
-/// `fontstring:SetShadowColor(0,0,0,0.3)`.
-///
-/// **Four values, not three** (`0x79dd2f`, `mov eax,0x4` — wow-re's widget-method batch). Three is
-/// the plausible wrong answer and it silently drops the alpha NavigatorFu round-trips: the whole
-/// point of its line is that whatever `GameFontNormal` carries arrives intact.
+/// A FontString's shadow accessors; `GetShadowColor` returns four values, alpha included
+/// (`0x79dd2f`, `mov eax,0x4`).
 #[test]
 fn region_shadow_accessors_round_trip_four_values() {
     let s = crate::script::UiScript::new().unwrap();
@@ -303,7 +199,6 @@ fn region_shadow_accessors_round_trip_four_values() {
     );
     assert_eq!(s.arity("SHFText:GetShadowOffset()").unwrap(), 2);
 
-    // NavigatorFu's line, in shape: a font object's shadow piped straight into a region's.
     s.run("SHFText:SetShadowColor(0, 0, 0, 0.3) SHFText:SetShadowOffset(1, -1)")
         .unwrap();
     let (r, g, b, a) = s
@@ -316,7 +211,6 @@ fn region_shadow_accessors_round_trip_four_values() {
         (1.0, -1.0)
     );
 
-    // Either half may be set first: setting only the offset must not blank the colour.
     s.run("SHFText:SetShadowOffset(2, -2)").unwrap();
     assert_eq!(
         s.eval::<f32>("local _,_,_,a = SHFText:GetShadowColor() return a")
@@ -326,18 +220,9 @@ fn region_shadow_accessors_round_trip_four_values() {
     );
 }
 
-/// **`Region:SetParent(frame)` — it exists on a Texture/FontString, and we were the ones missing
-/// it.** `SetParent` is in the Region method table (`0x7a1550`) and both leaf lookups fall back to
-/// Region's (`0x79c650` / `0x79ee50`), so `FuBar_FuXPFu.lua:210`'s
-/// `self.Spark:SetParent(self.XPBar)` — a texture from `XPBar:CreateTexture` — is a working line on
-/// the real client (wow-re `system/ui/scratch/widget-api-batch-benilla.md` Q7).
-///
-/// The two traps pinned here are the ones a plausible implementation gets wrong in opposite
-/// directions. **A non-Frame argument RAISES** (`IsA(FrameTag)` at `0x7a16ea`, message
-/// `"…Wrong parent object type, expected frame"`) rather than no-opping; and **anchors are NOT
-/// touched** by the re-link, which moves draw-layer/region-list membership only — so a re-parented
-/// texture keeps resolving against whatever `SetPoint` named, and FuXPFu's re-point on the next
-/// line is the correct pattern rather than a workaround.
+/// `Region:SetParent` (`0x7a1550`, reached by both leaf lookups' fallback: `0x79c650`, `0x79ee50`)
+/// moves the region's draw-list membership and leaves its anchors alone; a non-Frame argument
+/// raises (`IsA(FrameTag)` at `0x7a16ea`).
 #[test]
 fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
     /// The resolved rect of the one texture quad whose path contains `needle`, if it draws at all.
@@ -370,7 +255,6 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
     let before = tex_rect(&s, "SPGlow").expect("the spark draws under A");
     assert_eq!(before, crate::layout::Rect::new(22.0, 4.0, 46.0, 28.0));
 
-    // FuXPFu's line, and it returns nothing at all.
     assert_eq!(
         s.arity("Spark:SetParent(B)").unwrap(),
         0,
@@ -383,8 +267,6 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
         "the anchors are untouched — the spark still resolves against A, 300px from B"
     );
 
-    // …and the re-link is real, not merely recorded: the spark now draws with B. Hiding B takes it
-    // off the screen; hiding A (which it is still anchored to) does not.
     s.run("B:Hide()").unwrap();
     assert_eq!(
         tex_rect(&s, "SPGlow"),
@@ -399,8 +281,6 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
         "and not with the frame it is merely anchored to"
     );
 
-    // A non-Frame argument raises. A texture is the case the reference names, and it is the one an
-    // addon actually hits (a mixed table of frames and textures walked in a loop).
     for bad in ["Spark:SetParent(Spark)", "Spark:SetParent(5)"] {
         let e = s
             .run(bad)
@@ -411,11 +291,10 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
             "wanted the reference's 'expected frame' rejection, got: {e}"
         );
     }
-    // A MISSING argument is not the nil form: TNONE never reaches the nil branch.
+    // A missing argument is `TNONE`, which never reaches the nil branch.
     assert!(s.run("Spark:SetParent()").is_err(), "no argument raises");
 
-    // The nil form detaches without error: orphaned and unrendered, not destroyed — a later
-    // re-parent brings the same region back.
+    // nil detaches the region without destroying it.
     s.run("A:Show() Spark:SetParent(nil)").unwrap();
     s.resolve();
     assert_eq!(
@@ -432,19 +311,9 @@ fn region_set_parent_relinks_the_draw_owner_and_leaves_anchors_alone() {
     );
 }
 
-/// **`Button:SetFont(file, height [, flags])` — it exists, it returns NOTHING, and it never
-/// touches the label.** `0x780880`, wow-re's widget-method batch Q8 (§5-verified).
-/// `_LazyPig/LazyPigMenu.lua:214` calls it straight on a `CreateFrame("Button", …)` and is blocked
-/// on it today.
-///
-/// Three traps, each pinned here because each is a plausible implementation's silent divergence.
-/// **Zero return values**: the shared impl pushes `1`/nil (a real font-load probe on a Font object)
-/// and Button *discards* it (`xor eax,eax`), so answering `true` would hand an addon a probe the
-/// client does not have. **`GetFont` returns three values**, off the normal embedded font — which
-/// resolves through what that state inherits when nothing set it locally. And **a bare Button with
-/// no `<ButtonText>` is a silent no-op**: `SetFont`/`GetFont` never dereference the FontString
-/// pointer `+0x338`, so there is no error and — the observable half — **no lazy label creation**,
-/// which `GetFontString()` would report.
+/// `Button:SetFont` (`0x780880`) returns nothing, discarding the shared impl's `1`/nil
+/// (`xor eax,eax`), and sets the button's normal font without touching the label pointer
+/// (`+0x338`), so a bare Button makes no label; `GetFont` returns three values off that font.
 #[test]
 fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
     let s = crate::script::UiScript::new().unwrap();
@@ -457,7 +326,6 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
     )
     .unwrap();
 
-    // _LazyPig's line, on a Button that has no label at all.
     assert_eq!(
         s.arity(r#"SFBare:SetFont("Fonts\\FRIZQT__.TTF", 8)"#)
             .unwrap(),
@@ -480,13 +348,12 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
             .unwrap(),
         ("Fonts\\FRIZQT__.TTF".to_string(), 8.0, String::new())
     );
-    // Still three when nothing has ever set a font — path and height are nil, not absent.
+    // Nothing set: still three values, the path and height nil.
     assert_eq!(s.arity("SFLabelled:GetFont()").unwrap(), 3);
     assert!(s
         .eval::<bool>("local f = SFLabelled:GetFont() return f == nil")
         .unwrap());
 
-    // The flags argument is normalized to its OUTLINETYPE token, like every other GetFont.
     s.run(r#"SFBare:SetFont("Fonts\\SKURRI.TTF", 12, "THICKOUTLINE")"#)
         .unwrap();
     assert_eq!(
@@ -497,8 +364,7 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
     // Both arguments are required (`lua_isstring` + `lua_isnumber`, else the usage error).
     assert!(s.run(r#"SFBare:SetFont("Fonts\\SKURRI.TTF")"#).is_err());
 
-    // Unset locally, GetFont reads through what the NORMAL state inherits — how a
-    // GameMenuButtonTemplate button answers its template's face before anything calls SetFont.
+    // Unset locally, GetFont reads through the normal state's font object.
     s.run(
         r#"
         CreateFont("SFInherited")
@@ -513,8 +379,7 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
         ("Fonts\\MORPHEUS.TTF".to_string(), 14.0)
     );
 
-    // …and a local SetFont outranks that inherited object on the label's PAINT, not only in the
-    // getter — the whole point of the call `_LazyPig` makes.
+    // A local SetFont outranks that object on the label's paint too.
     s.run(r#"SFLabelled:SetFont("Fonts\\SKURRI.TTF", 9)"#)
         .unwrap();
     let (font, height) = s
@@ -537,21 +402,14 @@ fn button_set_font_returns_nothing_and_is_a_no_op_without_a_label() {
     );
 }
 
-/// **`SetNonSpaceWrap` / `CanNonSpaceWrap`** — FontString only (`0x79e9f0`/`0x79ead0`, wow-re's
-/// widget-method batch). `oRA2/Leader/Item.lua:561` is `f.textname:SetNonSpaceWrap(false)`, reached
-/// by two addons.
-///
-/// Two contract details, both easy to get wrong and both pinned here: the getter is
-/// **`CanNonSpaceWrap`**, not `GetNonSpaceWrap`, and it answers **`1` or nil** rather than a
-/// boolean — 1.12 predates that convention and an addon may compare against 1. And a **no-argument
-/// call ENABLES** it; the default is on, so it is not a query.
+/// FontString's `SetNonSpaceWrap`/`CanNonSpaceWrap` (`0x79e9f0`/`0x79ead0`): on by default, the
+/// getter answers `1` or nil, and a bare `SetNonSpaceWrap()` turns it on.
 #[test]
 fn non_space_wrap_defaults_on_and_answers_one_or_nil() {
     let s = crate::script::UiScript::new().unwrap();
     s.run(r#"f = CreateFrame("Frame", "NSF") fs = f:CreateFontString("NSFText", "ARTWORK")"#)
         .unwrap();
 
-    // Default is ON, and the answer is the NUMBER 1 — not `true`.
     assert_eq!(
         s.eval::<Option<i64>>("return NSFText:CanNonSpaceWrap()")
             .unwrap(),
@@ -564,7 +422,6 @@ fn non_space_wrap_defaults_on_and_answers_one_or_nil() {
         "it must NOT be a boolean — an addon comparing against 1 would break"
     );
 
-    // oRA2's line.
     s.run("NSFText:SetNonSpaceWrap(false)").unwrap();
     assert_eq!(
         s.eval::<Option<i64>>("return NSFText:CanNonSpaceWrap()")
@@ -573,7 +430,6 @@ fn non_space_wrap_defaults_on_and_answers_one_or_nil() {
         "off answers nil, not 0 and not false"
     );
 
-    // A no-argument call ENABLES rather than querying.
     s.run("NSFText:SetNonSpaceWrap()").unwrap();
     assert_eq!(
         s.eval::<Option<i64>>("return NSFText:CanNonSpaceWrap()")
@@ -583,23 +439,10 @@ fn non_space_wrap_defaults_on_and_answers_one_or_nil() {
     );
 }
 
-/// **The EditBox font block — the first sixteen entries of its own registrar table, and the largest
-/// single gap the per-kind widget-method census found** (decision 1229, whose ranking opens
-/// `63  EditBox:SetFontObject   (on Texture, FontString)`).
-///
-/// `EditBox`'s table is `.data 0x87bb68`, **48 entries** — the count read from the `mov edx,0x30` at
-/// the registering site `0x799ab5`, never from a run-length scan. There is no `FontInstance` class
-/// in the 1.12 Lua chain (wow-re `widget-api-batch-benilla.md`): each of the six text-bearing types
-/// re-declares the block in its own flat table, so membership is a per-table fact and **a name we
-/// add that the table does not carry is exactly as wrong as one we miss**.
-///
-/// The two halves pinned here are therefore both directions. Present: the fourteen we wire.
-/// Absent: `SetSpacing`/`GetSpacing`, which the table *does* carry (#10–#11) and we deliberately
-/// withhold because nothing here models line spacing — a stored-but-undrawn setter is the silent
-/// divergence of 1203/1205/1211, while a nil-value call names itself, and corpus demand is zero.
-/// Absent too: the names that belong to *other* tables and must not leak onto an EditBox through
-/// ours — `CopyFontObject` (Font object only), `SetNonSpaceWrap`/`CanNonSpaceWrap` and
-/// `SetTextHeight`/`GetStringWidth` (FontString only).
+/// EditBox's registrar table (`.data 0x87bb68`, 48 entries, `mov edx,0x30` at `0x799ab5`) opens
+/// with the font block each text-bearing type re-declares over the shared impl `0x79f210`: its
+/// fourteen font verbs answer, its `SetSpacing`/`GetSpacing` (#10, #11) are not installed as
+/// nothing models line spacing, and other tables' names do not leak onto it.
 #[test]
 fn editbox_carries_the_font_block_its_registrar_table_declares() {
     let s = crate::script::UiScript::new().unwrap();
@@ -630,10 +473,10 @@ fn editbox_carries_the_font_block_its_registrar_table_declares() {
     }
 
     for name in [
-        // On EditBox's real table, withheld on purpose (nothing models spacing).
+        // On EditBox's table, not installed: nothing models line spacing.
         "SetSpacing",
         "GetSpacing",
-        // Not on EditBox's table at all — adding one is the same class of error as missing one.
+        // Not on EditBox's table.
         "CopyFontObject",
         "SetNonSpaceWrap",
         "CanNonSpaceWrap",
@@ -648,21 +491,10 @@ fn editbox_carries_the_font_block_its_registrar_table_declares() {
     }
 }
 
-/// **Every EditBox font binding is a type-guard shim that returns whatever the shared implementation
-/// returned**, so the arities below are the shared ones verbatim — verified at the bytes: each
-/// binding ends `call <shared>` then `pop edi; pop esi; pop ebx; ret`, with **no `mov eax,N` and no
-/// `xor eax,eax`** after the call.
-///
-/// The trap is `SetFont`, and it points the opposite way to the one already pinned for Button.
-/// `Button:SetFont` (`0x780880`) ends `xor eax,eax` and returns **nothing** —
-/// [`button_set_font_returns_nothing_and_is_a_no_op_without_a_label`]. `EditBox:SetFont`
-/// (`0x797210` → `0x79f210`) does not discard, so the shared `lua_pushnumber(1.0)` (`0x79f345`) /
-/// `lua_pushnil` (`0x79f361`) passes straight through: **one value, the number `1`, not `true` and
-/// not zero values**. A probe written `if not eb:SetFont(f, s) then` needs the nil half; a probe
-/// written `== 1` needs the number half.
-///
-/// `GetShadowColor` returns **four** values (`0x79f9b3 mov eax,0x4`); three is the plausible wrong
-/// answer and silently drops the alpha.
+/// Each EditBox font binding returns what the shared implementation returns (no `mov eax,N` or
+/// `xor eax,eax` after the call), so unlike `Button:SetFont` (`0x780880`), `EditBox:SetFont`
+/// (`0x797210` → `0x79f210`) answers the number `1` or nil (`0x79f345`/`0x79f361`), and
+/// `GetShadowColor` returns four values (`0x79f9b3 mov eax,0x4`).
 #[test]
 fn editbox_font_block_return_shapes_are_the_shared_implementations() {
     let s = crate::script::UiScript::new().unwrap();
@@ -675,7 +507,6 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
     )
     .unwrap();
 
-    // The mutators push nothing at all.
     for call in [
         "SetFontObject(EBProbeFont)",
         "SetTextColor(1, 0, 0)",
@@ -691,7 +522,6 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
         );
     }
 
-    // The getters' exact widths.
     for (call, want) in [
         ("GetFontObject()", 1),
         ("GetFont()", 3),
@@ -708,7 +538,6 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
         );
     }
 
-    // SetFont: ONE value, and it is the number 1 — not `true`, and not nothing (the Button shape).
     assert_eq!(
         s.arity(r#"EBShape:SetFont("Fonts\\SKURRI.TTF", 12)"#)
             .unwrap(),
@@ -724,14 +553,13 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
     assert!(s
         .eval::<bool>(r#"return EBShape:SetFont("Fonts\\SKURRI.TTF", 12) == 1"#)
         .unwrap());
-    // An unloadable (empty) path is the FALSEY answer, not an error — `!OmniCC`'s probe idiom.
+    // An unloadable (empty) path answers nil, not an error.
     assert!(s
         .eval::<bool>(r#"return EBShape:SetFont("", 12) == nil"#)
         .unwrap());
     // Both arguments are gated (`lua_isstring` + `lua_isnumber`, else the usage error).
     assert!(s.run(r#"EBShape:SetFont("Fonts\\SKURRI.TTF")"#).is_err());
 
-    // The shadow round-trips all four channels — three would drop the alpha.
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return EBShape:GetShadowColor()")
             .unwrap(),
@@ -742,7 +570,7 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
             .unwrap(),
         (1.0, -1.0)
     );
-    // GetFontObject answers the OBJECT, never its name — the corpus indexes the result immediately.
+    // GetFontObject answers the object, not its name.
     assert_eq!(
         s.eval::<String>("return type(EBShape:GetFontObject())")
             .unwrap(),
@@ -750,20 +578,8 @@ fn editbox_font_block_return_shapes_are_the_shared_implementations() {
     );
 }
 
-/// **The real `Dewdrop-2.0` shape, which is the whole reason this landed.**
-///
-/// `Dewdrop-2.0.lua:1673-1675` is verbatim:
-/// ```lua
-/// local editBox = CreateFrame("EditBox", nil, editBoxFrame)
-/// editBoxFrame.editBox = editBox
-/// editBox:SetFontObject(ChatFontNormal)
-/// ```
-/// — an **anonymous** EditBox parented to a frame, then `SetFontObject` on it two lines later. That
-/// file is vendored into **63 addon folders** of the 218-addon corpus (65 copies: `FuBar` plus ~50
-/// FuBar plugins, `BigWigs`, `AtlasLoot`, `oRA2`, `SnaFu`, …), so the census's `63` is **one library
-/// replicated**, not 63 independent addons (decision 1207).
-///
-/// `AceGUIWidget-Slider.lua:204-210` is the same shape with `SetJustifyH("CENTER")` on the end.
+/// `Dewdrop-2.0.lua:1673-1675`'s shape: an anonymous EditBox under a frame, then
+/// `SetFontObject(ChatFontNormal)`.
 #[test]
 fn the_dewdrop_editbox_font_shape_resolves_and_paints() {
     let s = crate::script::UiScript::new().unwrap();
@@ -783,12 +599,10 @@ fn the_dewdrop_editbox_font_shape_resolves_and_paints() {
     )
     .unwrap();
 
-    // The link is live and readable back as the object.
     assert!(s
         .eval::<bool>("return DewdropEBFrame.editBox:GetFontObject() == ChatFontNormal")
         .unwrap());
-    // …and the object's paint really reached the box's implicit FontString (the `[this+0x324]` the
-    // reference's shim hands the shared implementation).
+    // The object's paint reaches the box's own FontString (`[this+0x324]`, what the shim passes).
     assert_eq!(
         s.eval::<(String, f32)>("local p, h = DewdropEBFrame.editBox:GetFont() return p, h")
             .unwrap(),
@@ -799,34 +613,22 @@ fn the_dewdrop_editbox_font_shape_resolves_and_paints() {
         .unwrap();
     assert_eq!((r, g, b), (0.9, 0.9, 0.9));
 
-    // The AceGUI slider's tail, on the same box.
+    // `AceGUIWidget-Slider.lua:204-210` ends the same shape with this.
     s.run(r#"DewdropEBFrame.editBox:SetJustifyH("CENTER")"#)
         .unwrap();
 }
 
-/// **`SetJustifyH`/`SetJustifyV` mask to their own axis, and a token from the other axis silently
-/// clears rather than erroring.** The enum is `.rdata 0x811ad0`, `{bits, token}`: `LEFT` 0x01,
-/// `CENTER` 0x02, `RIGHT` 0x04, `TOP` 0x08, `MIDDLE` 0x10, `BOTTOM` 0x20, stored in one dword with
-/// bits 0–2 horizontal and 3–5 vertical.
-///
-/// Two traps, both of which our older FontString/Font copies of these verbs get wrong by coercing
-/// anything unrecognised to CENTER/MIDDLE:
-///  · **an unknown token RAISES** `Usage: %s:SetJustifyH("justify")` (`0x87c77c`);
-///  · **a valid token from the wrong axis parses and then masks to nothing** — `SetJustifyH("TOP")`
-///    yields 0x08 and `0x08 & 0x07 == 0`, so justifyH is CLEARED and `GetJustifyH()` answers the
-///    literal `"UNKNOWN"` (`0x6f1a00`, `.data 0x838044`). No error is raised either way.
+/// The justify enum (`.rdata 0x811ad0`) keeps both axes in one dword, bits 0-2 horizontal and 3-5
+/// vertical: an unknown token raises (`0x87c77c`), and a token from the other axis masks to
+/// nothing, so `GetJustifyH()` answers `"UNKNOWN"` (`0x6f1a00`, `.data 0x838044`).
 #[test]
 fn editbox_justify_masks_to_its_axis_and_answers_unknown() {
     let s = crate::script::UiScript::new().unwrap();
     s.run(r#"EB = CreateFrame("EditBox", "EBJustify")"#)
         .unwrap();
 
-    // **LEFT, not the generic font default CENTER.** The `CSimpleFont` ctor really does default to
-    // `0x212` (CENTER | MIDDLE | 0x200), but the EditBox ctor overrides the horizontal axis right
-    // after linking its font instance (`0x779bcd … and eax,~6; or eax,1;` stored at `0x779be4`), so
-    // a fresh box starts at `0x211`. Taking the generic default is the plausible wrong answer, and
-    // it is exactly what this test asserted until wow-re's §5 trio read that ctor
-    // (`system/ui/scratch/editbox-font-surface.md` §6.2).
+    // A fresh EditBox is LEFT: its ctor turns the font default `0x212` (CENTER | MIDDLE | 0x200)
+    // into `0x211` (`0x779bcd`, stored at `0x779be4`).
     assert_eq!(
         s.eval::<String>("return EBJustify:GetJustifyH()").unwrap(),
         "LEFT"
@@ -836,7 +638,6 @@ fn editbox_justify_masks_to_its_axis_and_answers_unknown() {
         "MIDDLE"
     );
 
-    // Each axis is replaced independently — setting V leaves H alone.
     s.run(r#"EBJustify:SetJustifyH("LEFT") EBJustify:SetJustifyV("BOTTOM")"#)
         .unwrap();
     assert_eq!(
@@ -845,7 +646,6 @@ fn editbox_justify_masks_to_its_axis_and_answers_unknown() {
         ("LEFT".to_string(), "BOTTOM".to_string())
     );
 
-    // The cross-axis trap: "TOP" parses, masks to 0, and CLEARS justifyH.
     s.run(r#"EBJustify:SetJustifyH("TOP")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return EBJustify:GetJustifyH()").unwrap(),
@@ -858,23 +658,13 @@ fn editbox_justify_masks_to_its_axis_and_answers_unknown() {
         "and it leaves the vertical axis untouched"
     );
 
-    // An unrecognised token is the usage error, never a silent fallback to CENTER.
     assert!(s.run(r#"EBJustify:SetJustifyH("SIDEWAYS")"#).is_err());
 }
 
-/// **`EditBox:SetJustifyV` echoes through its getter and never reaches the pixels — on the real
-/// client too, permanently and by construction.** wow-re `editbox-font-surface.md` §6 (§5 trio +
-/// byte arbitration): `CSimpleFontString+0x124` is a per-bit *inherit* mask over the rendered
-/// justify `+0x120`, and `SetMultiLine 0x77a4a0` clears the whole vertical group `0x38` from it on
-/// **both** legs while writing the V bits locally — multi-line → TOP, single-line → MIDDLE. The
-/// EditBox ctor calls `SetMultiLine` unconditionally at birth (`0x779c2f`, with the ctor's zero
-/// register), and a census of all 256 `+0x124` operands image-wide found every `CSimpleFontString`
-/// writer to be an AND: **nothing ever ORs an inherit bit back in.** So the value written by
-/// `SetJustifyV` is masked out at `0x77086e`, while `GetJustifyV` reads the font *instance*
-/// (`0x79fd73`) and answers it faithfully.
-///
-/// This pins the shape rather than the accident: a future change that "fixes" the getter by wiring
-/// V justify through to the region would match neither the client nor our own draw law.
+/// `EditBox:SetJustifyV` reaches the getter (`0x79fd73` reads the font instance) but never the
+/// pixels: `SetMultiLine 0x77a4a0`, which the ctor always calls (`0x779c2f`), clears the vertical
+/// inherit bits (`CSimpleFontString+0x124`, over the drawn justify `+0x120`) and writes TOP or
+/// MIDDLE itself; nothing sets those bits back, so `0x77086e` masks the setter's value out.
 #[test]
 fn editbox_justify_v_echoes_but_multiline_alone_decides_the_pixels() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -906,55 +696,38 @@ fn editbox_justify_v_echoes_but_multiline_alone_decides_the_pixels() {
     // A single-line box renders MIDDLE, the `0x77a599` leg.
     assert_eq!(drawn_v(&s), crate::script::JustifyV::Middle);
 
-    // SetJustifyV("TOP") is echoed by the getter…
     s.run(r#"EBJV:SetJustifyV("TOP")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return EBJV:GetJustifyV()").unwrap(),
         "TOP",
         "the getter reads the font instance and echoes faithfully"
     );
-    // …and does NOT move the pixels. This is the disagreement, and it is faithful.
     assert_eq!(
         drawn_v(&s),
         crate::script::JustifyV::Middle,
         "SetJustifyV is masked out of the rendered justify — multiLine alone decides it"
     );
 
-    // multiLine is what actually moves it, on the `0x77a509` leg.
+    // Multi-line moves it, the `0x77a509` leg.
     s.run("EBJV:SetMultiLine(true)").unwrap();
     assert_eq!(drawn_v(&s), crate::script::JustifyV::Top);
-    // …and the getter still echoes whatever was last set, unaffected.
     assert_eq!(
         s.eval::<String>("return EBJV:GetJustifyV()").unwrap(),
         "TOP"
     );
 }
 
-/// **`Texture:SetDesaturated(flag)` answers `shaderSupported`, and since 1327 ours says yes.**
-///
-/// `0x79c1e0` (wow-re ledger). The reference's own `ItemButtonTemplate.lua:69` is
-/// `local shaderSupported = icon:SetDesaturated(desaturated)`, and lines 70-78 fall back to a 0.5
-/// grey vertex tint when that answer is falsy — 1.12 shipped on cards without the shader, so the
-/// verb reporting "no" is a real machine's answer, not a stub.
-///
-/// benilla answered nil for exactly as long as nothing greyed. Decision 1327 gave the renderer the
-/// luminance fold, so the honest answer flipped: a caller that asks for grey now gets grey, and
-/// keeps its own tint instead of having it overwritten by the 0.5 fallback. The test pins the
-/// return SHAPE, because the return is what callers branch on — `1`, not `true`, because the C
-/// answer is `1|nil` and every reference consumer writes `not shaderSupported`.
-///
-/// 98 of the 109 draw-then-raise addons in the corpus die on this one verb, via
-/// `FuBar_Panel.lua:43` → Dewdrop `AddLine` → `button.arrow:SetDesaturated(true)`, unguarded.
+/// `Texture:SetDesaturated` (`0x79c1e0`) answers `shaderSupported`, `1` or nil; benilla's renderer
+/// greys, so it answers `1`, and stock `ItemButtonTemplate.lua:69` keeps the caller's tint rather
+/// than its 0.5 fallback.
 #[test]
 fn set_desaturated_reports_shader_support_and_does_not_raise() {
     let s = crate::script::UiScript::new().unwrap();
     s.run(r#"f = CreateFrame("Frame", "DsF") tex = f:CreateTexture("DsTex", "ARTWORK")"#)
         .unwrap();
 
-    // Dewdrop's exact call — the one 98 addons reach. It must not raise.
     s.run("DsTex:SetDesaturated(true)").unwrap();
 
-    // ...and it answers truthy, so the reference's shader arm is taken.
     assert!(
         s.eval::<bool>("return DsTex:SetDesaturated(true) == 1")
             .unwrap(),
@@ -966,9 +739,7 @@ fn set_desaturated_reports_shader_support_and_does_not_raise() {
         "one return value"
     );
 
-    // The reference's own consumer, transcribed: a truthy answer keeps the CALLER's tint, and the
-    // 0.5 fallback never fires. This is the half B162 turned on — the talent tree asks for
-    // `(1, 0.65, 0.65, 0.65)` and must get 0.65, greyscale, not a flat 0.5 colour multiply.
+    // `SetItemButtonDesaturated`'s branch, transcribed: a truthy answer keeps the caller's tint.
     s.run(
         r#"
         local shaderSupported = DsTex:SetDesaturated(true)
@@ -986,18 +757,12 @@ fn set_desaturated_reports_shader_support_and_does_not_raise() {
         "the shader arm keeps the caller's tint, got {r},{g},{b}"
     );
 
-    // Both spellings of "off" are off — nil and false.
     s.run("DsTex:SetDesaturated(nil) DsTex:SetDesaturated(false)")
         .unwrap();
 }
 
-/// `UnitCreatureType(unit)` — `0x51a280`'s three-stage resolver, of which we model stages 2 and 3.
-///
-/// The load-bearing assertion is the **player** one. `0x605570` falls through the (never populated)
-/// creature record to a `ChrRaces.dbc` col-9 lookup that is **7 for all nine shipped races**, and
-/// `CreatureType[7]` is `"Humanoid"` — so a player answers a word, not nil. Reading only the
-/// creature record, which is what our data alone suggested, would have been wrong for every
-/// `UnitCreatureType("player")` call in the corpus.
+/// `UnitCreatureType` (`0x51a280`, stages 2 and 3 of three built): a creature's cached record,
+/// else (`0x605570`) the race's `ChrRaces.dbc` column 9, which is 7, "Humanoid", for every race.
 #[test]
 fn unit_creature_type_answers_the_record_then_falls_back_to_humanoid() {
     let mut s = script();
@@ -1018,24 +783,20 @@ fn unit_creature_type_answers_the_record_then_falls_back_to_humanoid() {
         }),
     );
 
-    // Stage 2: a creature's cached record wins.
     assert_eq!(
         s.eval::<String>(r#"return UnitCreatureType("target")"#)
             .unwrap(),
         "Beast"
     );
-    // Stage 3: a player has no record and falls through to race -> Humanoid.
     assert_eq!(
         s.eval::<String>(r#"return UnitCreatureType("player")"#)
             .unwrap(),
         "Humanoid"
     );
-    // An unresolved TOKEN is nil — not a raise.
+    // An unresolved token is nil; a missing argument fails `lua_isstring` and raises.
     assert!(s
         .eval::<bool>(r#"return UnitCreatureType("party4") == nil"#)
         .unwrap());
-    // A non-string ARGUMENT is a raise, which is a different failure from the nil above:
-    // `lua_isstring` gates it and `luaL_error` longjmps, so a missing arg abandons the statement.
     let err = s
         .run("UnitCreatureType()")
         .expect_err("a missing arg must raise");
@@ -1045,23 +806,13 @@ fn unit_creature_type_answers_the_record_then_falls_back_to_humanoid() {
     );
 }
 
-/// `GetInventorySlotInfo(slotName)` — `0x4c81b0`, three returns and a **case-insensitive**,
-/// full-string name match.
-///
-/// The case-insensitivity is the whole point: two 1.12-era corpus addons died at session start on
-/// case variants of real names — `FuBar_AmmoFu` passes `"ammoSlot"`, `FuBar_PoisonFu`
-/// `"MAINHANDSLOT"` — and both worked on the real client, because `0x4c8215` reaches the CRT
-/// `_strnicmp`, which folds both operands.
-///
-/// The other two assertions are things a plausible implementation gets wrong and nothing notices:
-/// the third return is the **number 1**, only for `RangedSlot`, never a boolean; and a miss
-/// **raises** with the reference's own message, which carries no `Usage:` prefix and does not
-/// interpolate the offending name.
+/// `GetInventorySlotInfo` (`0x4c81b0`) matches the whole name case-insensitively (`0x4c8215`,
+/// `_strnicmp`) and returns three values, the third the number 1 for `RangedSlot` alone; a miss
+/// raises the reference's message, with no `Usage:` and no name.
 #[test]
 fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
     let s = script();
 
-    // The exact spelling, and the two case variants the corpus actually ships.
     for name in ["AmmoSlot", "ammoSlot", "AMMOSLOT"] {
         assert_eq!(
             s.eval::<i64>(&format!("return GetInventorySlotInfo('{name}')"))
@@ -1076,18 +827,14 @@ fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
         16
     );
 
-    // Three values, and the second is the empty-slot background art the paper-doll buttons use.
     assert_eq!(s.arity("GetInventorySlotInfo('HeadSlot')").unwrap(), 3);
     let (id, art) = s
         .eval::<(i64, String)>("return GetInventorySlotInfo('HeadSlot')")
         .unwrap();
     assert_eq!(id, 1);
-    // The DBC string verbatim: LOWERCASE directory and the `.blp` extension. The binding pushes
-    // `[esi+4]` with no normalisation, so a caller that keys a table by this sees these bytes.
+    // The DBC string verbatim, lowercase directory and `.blp`: the binding pushes `[esi+4]` as is.
     assert_eq!(art, "interface\\paperdoll\\UI-PaperDoll-Slot-Head.blp");
 
-    // checkRelic: the NUMBER 1 for the ranged slot alone, nil everywhere else — not `false`, which
-    // is falsey like nil but the wrong type for a caller that compares it against 1.
     assert!(s
         .eval::<bool>("local _,_,r = GetInventorySlotInfo('RangedSlot') return r == 1")
         .unwrap());
@@ -1095,9 +842,8 @@ fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
         .eval::<bool>("local _,_,r = GetInventorySlotInfo('HeadSlot') return r == nil")
         .unwrap());
 
-    // The twelve rows this table was short of — `Bag1`..`Bag12` at SlotNumbers 64..75, of which
-    // 64..69 is the bank-bag band. They share ONE string offset with Bag0Slot..Bag3Slot, so all
-    // sixteen bag rows answer the same art.
+    // `Bag1`..`Bag12` are SlotNumbers 64..75 (64..69 the bank bags) and share one string offset
+    // with `Bag0Slot`..`Bag3Slot`, so all sixteen answer the same art.
     assert_eq!(
         s.eval::<i64>("return GetInventorySlotInfo('Bag1')")
             .unwrap(),
@@ -1116,14 +862,13 @@ fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
             .unwrap(),
         "all sixteen bag rows share one string-block offset"
     );
-    // ...and `Bag1` (64) is NOT `Bag1Slot` (21): different names, different ids, both real rows.
+    // `Bag1` (64) and `Bag1Slot` (21) are different rows.
     assert_eq!(
         s.eval::<i64>("return GetInventorySlotInfo('Bag1Slot')")
             .unwrap(),
         21
     );
 
-    // A miss raises — there is no nil path — with the reference's own string.
     let err = s
         .run("GetInventorySlotInfo('NoSuchSlot')")
         .expect_err("an unknown slot name must raise");
@@ -1138,33 +883,12 @@ fn get_inventory_slot_info_folds_case_and_flags_only_the_ranged_slot() {
     );
 }
 
-/// **The whole Region method map, on both leaves that chain to it.**
-///
-/// `SetParent` above landed as one name because one addon line named it. That is how this table has
-/// always grown, and it is why `GetParent` — its own getter — was still absent while `SetParent`
-/// worked. wow-re carves the map as a SET, not as names: FontString's lookup `0x79ee20` chains its
-/// own map `0xcf5400` to the Region map `0xcf54b4`, whose 19 entries are
-///
-/// ```text
-/// GetObjectType IsObjectType GetName GetParent SetParent GetCenter GetLeft GetRight GetTop
-/// GetBottom GetWidth SetWidth GetHeight SetHeight GetNumPoints GetPoint SetPoint SetAllPoints
-/// ClearAllPoints
-/// ```
-///
-/// (`system/ui/scratch/font-object-lua-surface.md` — the same note whose point is that a `<Font>`
-/// object does NOT chain and so has none of these. Texture reaches the identical map through its
-/// own leaf lookup, which is why both are asserted here.)
-///
-/// So this asserts membership rather than behaviour: each name is *present and callable* on a
-/// Texture and on a FontString. Behaviour belongs in the focused tests around it — what is pinned
-/// here is that the set cannot quietly lose a member again, which is the failure `GetParent` was.
+/// Every Region-map name (`0xcf54b4`, 19 entries) is callable on a Texture and a FontString, whose
+/// lookups fall back to it (FontString's `0x79ee20` chains its own `0xcf5400`); a Font object's
+/// lookup (`0x7a1100`) has no fallback.
 #[test]
 fn every_region_map_method_is_callable_on_a_texture_and_a_fontstring() {
-    /// All 19. `GetObjectType`/`IsObjectType` were held out of this list when 1244 landed the other
-    /// four — dispatched rather than guessed — and joined it when wow-re answered
-    /// (`system/ui/scratch/widget-type-identity.md`). The list is the whole map again.
-    // The one list, shared with the title region's narrower table (`script::REGION_MAP_METHODS`)
-    // so the two can never disagree about what "the Region map" is.
+    /// All 19, `GetObjectType`/`IsObjectType` (`0x7a11d0`/`0x7a1290`) among them.
     const REGION_MAP: [&str; 19] = crate::script::REGION_MAP_METHODS;
     let mut s = crate::script::UiScript::new().unwrap();
     s.set_screen_size(800.0, 600.0);
@@ -1195,11 +919,8 @@ fn every_region_map_method_is_callable_on_a_texture_and_a_fontstring() {
     );
 }
 
-/// **The four Region-map readers, on the cases a frame-shaped copy gets wrong.**
-///
-/// `TheoryCraftUI.lua:720` is the line that found them: `buttontext:GetParent():GetID()`, where
-/// `buttontext` is a FontString — a working line on the real client, and `attempt to call method
-/// 'GetParent' (a nil value)` here, every session.
+/// The Region-map readers where a region differs from a frame: `GetParent` is the owner frame
+/// (`TheoryCraftUI.lua:720` calls it on a FontString), and `GetPoint` answers a sibling region.
 #[test]
 fn the_region_map_readers_answer_the_way_the_edges_do() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -1218,7 +939,6 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
     .unwrap();
     s.resolve();
 
-    // GetParent is the OWNER frame — the identity TheoryCraft then calls :GetID() on.
     assert!(
         s.eval::<bool>("return RRPlate:GetParent() == RRFrame")
             .unwrap(),
@@ -1230,15 +950,13 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
         "…and it is a real frame handle, not a bare id"
     );
 
-    // GetCenter agrees with the edge readers BY CONSTRUCTION — the invariant that forbids scaling
-    // one and not the others.
+    // GetCenter agrees with the edge readers by construction, so none of them is scaled alone.
     let (cx, cy): (f64, f64) = s.eval("return RRPlate:GetCenter()").unwrap();
     let (l, r, t, b): (f64, f64, f64, f64) = s
         .eval("return RRPlate:GetLeft(), RRPlate:GetRight(), RRPlate:GetTop(), RRPlate:GetBottom()")
         .unwrap();
     assert_eq!((cx, cy), ((l + r) * 0.5, (t + b) * 0.5));
 
-    // GetNumPoints counts what SetPoint wrote, and ClearAllPoints takes it back to 0.
     assert_eq!(s.eval::<i64>("return RRPlate:GetNumPoints()").unwrap(), 1);
     assert_eq!(
         s.eval::<i64>("return RRLabel:GetNumPoints()").unwrap(),
@@ -1246,8 +964,8 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
         "the sibling-anchored label carries its one point"
     );
 
-    // GetPoint's relativeTo must come back as the SIBLING REGION, not a frame wrapper onto the same
-    // id — the one place regions genuinely differ from frames, since both share an id space.
+    // Frames and regions share an id space, so `relativeTo` must come back as the region handle,
+    // not a frame wrapper onto its id.
     let (p, rp, x, y): (String, String, f64, f64) = s
         .eval("local p, _, rp, x, y = RRLabel:GetPoint(1) return p, rp, x, y")
         .unwrap();
@@ -1257,7 +975,6 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
             .unwrap(),
         "relativeTo is the sibling REGION handle itself"
     );
-    // Out of range is five nils, like the frame twin.
     assert_eq!(
         s.arity("RRPlate:GetPoint(7)").unwrap(),
         5,
@@ -1269,13 +986,7 @@ fn the_region_map_readers_answer_the_way_the_edges_do() {
     );
 }
 
-/// **`GetObjectType`/`IsObjectType` — every detail wow-re had to answer, asserted.**
-///
-/// 1244 shipped four Region-map members and left these two out rather than guess them, because
-/// each of the four traps below is a coin-flip a reimplementation loses (1203/1205/1211 are three
-/// records of losing it). The carve is `system/ui/scratch/widget-type-identity.md`; this is that
-/// answer turned into a gate, so the next person to touch these has to disagree with the binary
-/// rather than with me.
+/// A region's `GetObjectType`/`IsObjectType` (`0x7a11d0`/`0x7a1290`).
 #[test]
 fn the_type_identity_verbs_answer_what_the_binary_answers() {
     let s = crate::script::UiScript::new().unwrap();
@@ -1289,7 +1000,7 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
     )
     .unwrap();
 
-    // The leaf names, one value each (`lua_pushstring`, no arity check on extra args).
+    // One value each (`lua_pushstring`); extra arguments are ignored.
     assert_eq!(
         s.eval::<String>("return TITex:GetObjectType()").unwrap(),
         "Texture"
@@ -1304,7 +1015,7 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
         "one value, and a stray argument is ignored rather than an arity error"
     );
 
-    // The chain is TWO deep and stops there.
+    // The chain is two deep: the leaf, then Region.
     for (obj, leaf) in [("TITex", "Texture"), ("TIStr", "FontString")] {
         assert_eq!(
             s.eval::<i64>(&format!("return {obj}:IsObjectType('{leaf}')"))
@@ -1318,9 +1029,7 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
             1,
             "{obj} is a Region"
         );
-        // **The invented root.** 1.12.1 has no LayoutFrame/ScriptObject/Object type at all — those
-        // strings live only in __FILE__ paths and allocator tags. Knowing later clients is exactly
-        // what would put them here.
+        // 1.12.1 has no LayoutFrame, ScriptObject or Object type at all.
         for absent in ["LayoutFrame", "ScriptObject", "Object", "Frame", "Font"] {
             assert!(
                 s.eval::<Option<i64>>(&format!("return {obj}:IsObjectType('{absent}')"))
@@ -1330,14 +1039,12 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
             );
         }
     }
-    // …and the two leaves are not each other.
     assert!(s
         .eval::<Option<i64>>("return TITex:IsObjectType('FontString')")
         .unwrap()
         .is_none());
 
-    // Case-INSENSITIVE and WHOLE-string (SStrCmpI folds both operands; the compare stops at the
-    // first NUL, so no prefix or substring match either).
+    // Case-insensitive and whole-string (`SStrCmpI`).
     for spelling in ["texture", "TEXTURE", "TeXtUrE", "region", "REGION"] {
         assert_eq!(
             s.eval::<i64>(&format!("return TITex:IsObjectType('{spelling}')"))
@@ -1355,7 +1062,6 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
         );
     }
 
-    // A hit is the NUMBER 1, never a boolean; a miss is nil. Both paths push exactly one value.
     assert_eq!(
         s.eval::<String>("return type(TITex:IsObjectType('Texture'))")
             .unwrap(),
@@ -1370,8 +1076,7 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
         );
     }
 
-    // A NUMBER is accepted (lua_isstring takes tags 4 and 3) and stringified in place — it simply
-    // never matches, because no type name is numeric.
+    // A number passes `lua_isstring` and never matches a type name.
     assert!(
         s.eval::<Option<i64>>("return TITex:IsObjectType(5)")
             .unwrap()
@@ -1379,8 +1084,6 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
         "a number argument is accepted and quietly answers nil, NOT a raise"
     );
 
-    // Everything else RAISES with the reference's own Usage text, naming the region — or
-    // `<unnamed>` for one declared anonymously.
     for bad in ["", "nil", "true", "{}", "print"] {
         let err = s
             .run(&format!("TITex:IsObjectType({bad})"))
@@ -1401,20 +1104,8 @@ fn the_type_identity_verbs_answer_what_the_binary_answers() {
     );
 }
 
-/// **`GetFrameType`/`IsFrameType` — 1.12's own names for the pair above, on the FRAME side**
-/// (decision 2106).
-///
-/// The client registers type identity twice: `CScriptRegion` publishes
-/// `GetObjectType`/`IsObjectType` (the test above), and `CSimpleFrameScript.cpp` publishes
-/// `GetFrameType 0x773640` / `IsFrameType 0x773700` — both carved at the bytes in wow-5875-re
-/// `system/ui/scratch/item17-frameapi-batch1.md`. Later clients kept the first pair and dropped
-/// the second; we had shipped only the first, which is the inverse of 1189's usual failure — a
-/// real 1.12 name we were *missing*, not an invented one we offered.
-///
-/// It cost the world map. Cartographer 2.02's `LookNFeel.lua:368` finds the map's player arrow
-/// with `v:GetFrameType() == "Model" and not v:GetName()`; with the verb nil that raised inside
-/// `OnEnable`, AceAddon swallowed it, and every map open then put
-/// `LookNFeel.lua:737: attempt to index field 'playerModel'` on screen.
+/// Frames also carry 1.12's frame-side pair, `GetFrameType 0x773640`/`IsFrameType 0x773700`
+/// (`CSimpleFrameScript.cpp`), beside `CScriptRegion`'s `GetObjectType`/`IsObjectType`.
 #[test]
 fn the_frame_side_type_identity_verbs_are_1_12s_own_names() {
     let s = crate::script::UiScript::new().unwrap();
@@ -1428,8 +1119,7 @@ fn the_frame_side_type_identity_verbs_are_1_12s_own_names() {
     )
     .unwrap();
 
-    // `GetFrameType` reads the same per-class type-name slot `GetObjectType` does (`[edx+0x1c]`),
-    // so the two agree by construction — one value, extra arguments ignored.
+    // Both read the same per-class type-name slot (`[edx+0x1c]`).
     for (obj, leaf) in [
         ("FTFrame", "Frame"),
         ("FTButton", "Button"),
@@ -1448,15 +1138,13 @@ fn the_frame_side_type_identity_verbs_are_1_12s_own_names() {
         );
     }
 
-    // The exact line Cartographer walks the world map with.
+    // How Cartographer's `LookNFeel.lua:368` finds the world map's player arrow.
     assert!(
         s.eval::<bool>(r#"return FTModel:GetFrameType() == "Model" and not FTModel:GetName()"#)
             .unwrap(),
         "an anonymous Model must answer its type AND a nil name — LookNFeel.lua:368"
     );
 
-    // `IsFrameType` walks the same chain: the leaf, every base, the number 1 on a hit and nil on
-    // a miss, case-insensitive and whole-string.
     assert_eq!(
         s.eval::<i64>("return FTButton:IsFrameType('Button')")
             .unwrap(),
@@ -1481,18 +1169,13 @@ fn the_frame_side_type_identity_verbs_are_1_12s_own_names() {
         );
     }
 
-    // A REGION does not get the frame-side pair — the two registrars are distinct, and offering
-    // both names on everything would be the superset 1189 forbids.
+    // A region has no frame-side pair: the two registrars are distinct.
     assert!(s.eval::<bool>("return FTTex.GetFrameType == nil").unwrap());
     assert!(s.eval::<bool>("return FTTex.IsFrameType == nil").unwrap());
 }
 
-/// **The frame side of the type identity, and the three chains a guess gets wrong.**
-///
-/// `_Nameplates.lua` is why this half exists: it asks `Region:GetObjectType()` (the region twin)
-/// AND `Nameplate:GetObjectType() ~= "Button"` / `Frame:GetObjectType() == "StatusBar"` in the same
-/// file. The chains come from wow-re's 23-class roster, which is a hardcoded straight-line list per
-/// class in the binary rather than a runtime parent walk.
+/// A frame's type chain follows the reference's 23-class roster, a hardcoded list per class rather
+/// than a runtime parent walk.
 #[test]
 fn a_frames_type_chain_matches_the_roster() {
     let s = crate::script::UiScript::new().unwrap();
@@ -1500,7 +1183,6 @@ fn a_frames_type_chain_matches_the_roster() {
     let cases: &[(&str, &str, &[&str])] = &[
         ("Frame", "Frame", &["Frame", "Region"]),
         ("Button", "Button", &["Button", "Frame", "Region"]),
-        // Depth 4 — the longest chain we can build.
         (
             "CheckButton",
             "CheckButton",
@@ -1519,14 +1201,13 @@ fn a_frames_type_chain_matches_the_roster() {
             "MessageFrame",
             &["MessageFrame", "Frame", "Region"],
         ),
-        // **NOT via MessageFrame**, despite the name (roster `0x787940`).
+        // Not via MessageFrame, despite the name (roster `0x787940`).
         (
             "ScrollingMessageFrame",
             "ScrollingMessageFrame",
             &["ScrollingMessageFrame", "Frame", "Region"],
         ),
-        // **Capital HTML** — the enum variant is `SimpleHtml`, and `GetObjectType` is compared with
-        // `==` by addons, so a variant-derived string would be silently wrong here.
+        // Capital HTML, unlike the `SimpleHtml` variant; addons compare the string with `==`.
         (
             "SimpleHTML",
             "SimpleHTML",
@@ -1543,10 +1224,9 @@ fn a_frames_type_chain_matches_the_roster() {
             &["GameTooltip", "Frame", "Region"],
         ),
         ("Minimap", "Minimap", &["Minimap", "Frame", "Region"]),
-        // `PlayerModel` derives from `Model`, which is why `SetUnit` on a portrait pane finds
-        // `SetCamera` too (wow-re `ui/scratch/widget-type-identity.md` §6) — and `DressUpModel`
-        // derives from it in turn: the roster's maximum depth, 5 (1969; `TabardModel` is the
-        // other depth-5 chain — built by 1977).
+        // `PlayerModel` derives from `Model` (`0x505830`/`0x5057c0`), so a `SetUnit` portrait pane
+        // has `SetCamera` too; `DressUpModel`, like `TabardModel`, derives from `PlayerModel`: the
+        // roster's maximum depth, 5.
         (
             "PlayerModel",
             "PlayerModel",
@@ -1574,8 +1254,6 @@ fn a_frames_type_chain_matches_the_roster() {
                 "{kind} must be a {want}"
             );
         }
-        // Every OTHER leaf in the roster must be absent from this chain — the assertion that
-        // catches a chain built by "sounds related".
         for (other, other_leaf, _) in cases {
             if chain.contains(other_leaf) {
                 continue;
@@ -1589,8 +1267,6 @@ fn a_frames_type_chain_matches_the_roster() {
         }
     }
 
-    // The frame verbs share the region twin's contract: number 1 / nil, one value, and a raise
-    // naming the frame.
     s.run(r#"TCNamed = CreateFrame("Button", "TCNamed")"#)
         .unwrap();
     assert_eq!(
@@ -1609,16 +1285,8 @@ fn a_frames_type_chain_matches_the_roster() {
     );
 }
 
-/// **Every region method belongs to a leaf — no name may be installed and invisible to both.**
-///
-/// The split (`script::region`) copies names out of the full table into a Texture leaf and a
-/// FontString leaf. A name in neither list is still installed, still costs a closure, and is
-/// reachable from NOTHING — the silent half of a wrong partition.
-///
-/// This is not hypothetical: the partition was first built from a grep, and that grep missed
-/// `SetGradient`/`SetGradientAlpha` because they are installed from a LOOP rather than a literal
-/// `m.set("…")`. One test caught one of them; this gate catches the whole class, and it reads the
-/// table the VM actually holds rather than the source that builds it.
+/// Every name on the full region table the VM holds is in a leaf list: `script::region` copies
+/// names out of it into the Texture and FontString leaves, and one in neither is unreachable.
 #[test]
 fn every_installed_region_method_lands_in_a_leaf() {
     use crate::script::{
@@ -1650,10 +1318,7 @@ fn every_installed_region_method_lands_in_a_leaf() {
     );
 }
 
-/// **The Environment Detail pair — `SetWorldDetail 0x488dd0` / `GetWorldDetail 0x488d70`.**
-///
-/// Every assertion below is a byte read out of `WoW.exe`, not a shape chosen here; decision 2163
-/// carries the carve and `script::cvars::install_world_detail_verbs` the reasoning.
+/// The Environment Detail pair, `SetWorldDetail 0x488dd0`/`GetWorldDetail 0x488d70`.
 #[test]
 fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
     let s = script();
@@ -1684,8 +1349,7 @@ fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
         "the table is the reference's, not a transcription that can drift"
     );
 
-    // **Truncation is toward zero** (`0x40a2b0` forces RC = chop), so a fractional stop floors
-    // toward 0 from both sides — and -0.5 is therefore stop 0, ACCEPTED.
+    // Truncation is toward zero (`0x40a2b0` sets RC = chop), so -0.5 is stop 0 and accepted.
     s.run("SetWorldDetail(2.9)").unwrap();
     assert_eq!(frill(&s).as_deref(), Some("48"));
     s.run("SetWorldDetail(-0.5)").unwrap();
@@ -1695,11 +1359,10 @@ fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
         "-0.5 truncates to 0, which is in range: only <= -1 raises"
     );
 
-    // **`lua_isnumber` accepts a numeric string.**
+    // `lua_isnumber` accepts a numeric string.
     s.run(r#"SetWorldDetail("2")"#).unwrap();
     assert_eq!(frill(&s).as_deref(), Some("48"));
 
-    // Both raise paths, with the reference's own strings.
     for bad in [
         "SetWorldDetail(3)",
         "SetWorldDetail(-1)",
@@ -1724,7 +1387,6 @@ fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
         );
     }
 
-    // Zero return values from the setter; exactly one number from the getter.
     s.run("SetWorldDetail(1)").unwrap();
     assert_eq!(
         s.arity("SetWorldDetail(1)").unwrap(),
@@ -1736,17 +1398,13 @@ fn set_world_detail_writes_the_stop_table_and_validates_like_the_reference() {
         s.eval::<String>("return type(GetWorldDetail())").unwrap(),
         "number"
     );
-    // The getter reads no argument — pfUI declares its replacement `function(arg)` and the stock
-    // one it chains to is called with one.
+    // The getter ignores an argument; pfUI's hook passes one.
     assert_eq!(s.eval::<i64>("return GetWorldDetail(7)").unwrap(), 1);
     assert_eq!(stop(&s).as_deref(), Some("1"));
 }
 
-/// **pfUI's `hdgraphic` module, run against the real bindings.**
-///
-/// The module hooks both verbs and drives `frillDensity` past the panel's top stop; this is that
-/// arm executed verbatim (`modules/hdgraphic.lua` l.4-39), because "the verbs exist" and "the
-/// module works" are different claims and only the second one is the point.
+/// pfUI's `hdgraphic` module (`modules/hdgraphic.lua:4-39`), which hooks both verbs to drive
+/// `frillDensity` past the top stop, run against the bindings.
 #[test]
 fn the_pfui_hdgraphic_extended_arm_runs() {
     let s = script();
@@ -1771,8 +1429,6 @@ fn the_pfui_hdgraphic_extended_arm_runs() {
     )
     .unwrap();
 
-    // The hook's own precondition: `local Hook... = SetWorldDetail` captured a FUNCTION. Before
-    // 2163 both were nil and this line took the module down with it.
     assert_eq!(
         s.eval::<i64>("SetWorldDetail(9); return GetWorldDetail()")
             .unwrap(),
@@ -1784,7 +1440,7 @@ fn the_pfui_hdgraphic_extended_arm_runs() {
         Some("160"),
         "(9+1)*16 — inside the reference's own [1, 256], which is why its range is wider than its slider"
     );
-    // ...and the low arm falls through to the stock getter, which is where a nil hook used to bite.
+    // The low arm falls through to the stock getter.
     assert_eq!(
         s.eval::<i64>("SetWorldDetail(2); return GetWorldDetail()")
             .unwrap(),
@@ -1792,19 +1448,9 @@ fn the_pfui_hdgraphic_extended_arm_runs() {
     );
 }
 
-/// **The four nameplate verbs take no argument and return nothing.**
-///
-/// `ShowNameplates 0x489450` / `HideNameplates 0x489460` / `ShowFriendNameplates 0x489470` /
-/// `HideFriendNameplates 0x489480` — four 10-byte bodies over two setters, differing only in an
-/// `or`/`and` mask (wow-re `ui/scratch/party-leader-and-nameplate-verbs.md`).
-///
-/// Both halves of the shape are asserted because both are easy to invent differently:
-///
-/// - **No argument is read.** `ShowNameplates(false)` still shows — there is no `lua_gettop` and
-///   no `lua_toboolean` in any of the four. That is *why* there are four verbs instead of two
-///   taking a flag, and a binding typed `fn(bool)` would reject a call the reference accepts.
-/// - **Zero return values, not nil.** The return-list count is 0, which is observably different
-///   from one nil for a caller that counts.
+/// `ShowNameplates 0x489450`, `HideNameplates 0x489460`, `ShowFriendNameplates 0x489470` and
+/// `HideFriendNameplates 0x489480` read no argument and return nothing: four 10-byte bodies over
+/// two setters, differing only in an `or`/`and` mask.
 #[test]
 fn the_nameplate_verbs_ignore_their_arguments_and_return_nothing() {
     let s = script();
@@ -1819,7 +1465,6 @@ fn the_nameplate_verbs_ignore_their_arguments_and_return_nothing() {
         Some("1")
     );
 
-    // Each verb writes its own bit and leaves the other alone.
     s.run("HideNameplates()").unwrap();
     assert_eq!(
         get(&s, crate::script::CVAR_NAMEPLATE_ENEMIES).as_deref(),
@@ -1841,8 +1486,6 @@ fn the_nameplate_verbs_ignore_their_arguments_and_return_nothing() {
         "...and back the other way"
     );
 
-    // **An argument is accepted and IGNORED.** `ShowNameplates(false)` shows, which is the whole
-    // reason the reference ships four verbs rather than two taking a flag.
     s.run("ShowNameplates(false)").unwrap();
     assert_eq!(
         get(&s, crate::script::CVAR_NAMEPLATE_ENEMIES).as_deref(),
@@ -1854,7 +1497,6 @@ fn the_nameplate_verbs_ignore_their_arguments_and_return_nothing() {
             .unwrap_or_else(|e| panic!("{call} must not raise: {e}"));
     }
 
-    // ZERO return values, not one nil.
     assert_eq!(
         s.arity("ShowNameplates()").unwrap(),
         0,
diff --git a/crates/benilla-ui/src/script/tests/region_map.rs b/crates/benilla-ui/src/script/tests/region_map.rs
index 1e4bd6f3..1b3b16e9 100644
--- a/crates/benilla-ui/src/script/tests/region_map.rs
+++ b/crates/benilla-ui/src/script/tests/region_map.rs
@@ -1,15 +1,5 @@
-//! **The Region map is ONE function per name, reached by frames and regions alike** — the
-//! [`crate::script::region_map`] law, and the regression guard for bug B267.
-//!
-//! Its header carries the byte evidence (`Frame ∩ Region = ∅`, parsed out of the two `.data`
-//! method tables). What is pinned here is the two things a reader of the code could not otherwise
-//! check: that the sharing is real *by identity*, and that it stops exactly at the 19.
-//!
-//! The reported symptom this file exists for: Quiver's `Api/Index.wow.lua` opens
-//! `_Height = WorldFrame.GetHeight`, applies it to a Texture and a FontString, and benilla raised
-//! `stale or invalid frame handle` — inside the addon's `VARIABLES_LOADED` handler, four lines
-//! before it published `Quiver.CastPetAction`. The addon's own field was nil at macro time because
-//! the handler never finished, which is what got filed.
+//! The Region map ([`crate::script::region_map`]): one function per name for frames and regions
+//! alike, shared by identity and stopping at the 19.
 
 use crate::script::UiScript;
 
@@ -34,12 +24,7 @@ fn vm() -> UiScript {
     s
 }
 
-/// Every one of the 19 is the **same Lua value** on a Frame, a Texture and a FontString.
-///
-/// Not a stand-in for the behaviour tests below: identity is what makes the pulled-off-method
-/// idiom work *for a method the test author never thought of*. In the client it holds because
-/// Frame's table does not carry any of the 19 and its lookup tail-calls Region's; here it holds
-/// because one function is written into every table that chain reaches.
+/// In the client, Frame's table carries none of the 19 and its lookup tail-calls Region's.
 #[test]
 fn the_region_map_is_one_function_on_every_widget() {
     let s = vm();
@@ -56,12 +41,10 @@ fn the_region_map_is_one_function_on_every_widget() {
     }
 }
 
-/// **The bug, reduced to its four lines.** A method pulled off a frame and applied to a region.
 #[test]
 fn a_method_pulled_off_a_frame_works_on_a_texture_and_a_fontstring() {
     let s = vm();
-    // Quiver's own shape: `Api._Height = WorldFrame.GetHeight`, applied to `r.Icon` (a Texture)
-    // and `r.Label` (a FontString), from a table built at file scope.
+    // Quiver's shape: `Api._Height = WorldFrame.GetHeight`, applied to a Texture and a FontString.
     let (th, sh): (f32, f32) = s
         .eval(
             r#"
@@ -82,13 +65,10 @@ fn a_method_pulled_off_a_frame_works_on_a_texture_and_a_fontstring() {
         .unwrap();
     assert_eq!((tw, sw), (64.0, 50.0));
 
-    // …and the setter half, which is the same split and would have been the next wall.
     s.run("local _SetW = Host.SetWidth _SetW(Tex, 99)").unwrap();
     assert_eq!(s.eval::<f32>("return Tex:GetWidth()").unwrap(), 99.0);
 }
 
-/// The other direction — a method pulled off a **region** and applied to a **frame**. Same one
-/// function, so this cannot be made to work by special-casing the reported direction.
 #[test]
 fn a_method_pulled_off_a_texture_works_on_a_frame() {
     let s = vm();
@@ -102,9 +82,7 @@ fn a_method_pulled_off_a_texture_works_on_a_frame() {
     assert_eq!(kind, "Frame");
 }
 
-/// Each receiver keeps its OWN behaviour behind the shared name — the per-kind arms are not
-/// collapsed into one. `GetObjectType` is the cleanest witness (three different answers), and
-/// `GetParent` is the one whose two arms genuinely differ (a region's owner is never nil).
+/// The shared function keeps a per-kind arm; a region's `GetParent` is its owner, never nil.
 #[test]
 fn one_name_still_dispatches_per_kind() {
     let s = vm();
@@ -115,14 +93,12 @@ fn one_name_still_dispatches_per_kind() {
         (f.as_str(), t.as_str(), g.as_str()),
         ("Frame", "Texture", "FontString")
     );
-    // The region arm answers its OWNER; the frame arm answers nil for a parentless top frame.
     let owner: String = s.eval("return Tex:GetParent():GetName()").unwrap();
     assert_eq!(owner, "Host");
     assert!(s.eval::<bool>("return Host:GetParent() == nil").unwrap());
 }
 
-/// `GetNumPoints` — on the Region map, so **every** widget answers it. The frame arm did not
-/// exist until the map was collapsed to one implementation; the region arm shipped alone.
+/// `GetNumPoints` is on the Region map, so every widget answers it.
 #[test]
 fn get_num_points_answers_on_a_frame_too() {
     let s = vm();
@@ -135,12 +111,8 @@ fn get_num_points_answers_on_a_frame_too() {
     assert_eq!(s.eval::<i64>("return Host:GetNumPoints()").unwrap(), 0);
 }
 
-/// **The carve's other edge, and the control that keeps it honest.** These six look like they
-/// belong to the Region map and do not: Frame, Texture and FontString each register their *own*
-/// at different addresses (`texture-fontstring-method-split.md` §3 — Texture `SetAlpha 0x79b580`
-/// vs FontString `0x79cb70`, and Frame's own `0x79b...` twin). So `WorldFrame.Show(someTexture)`
-/// fails on the real client, and hoisting them here to make more addon code work would be the
-/// superset decision 1189 had to take back out.
+/// Frame, Texture and FontString each register their own copy of these six (Texture `SetAlpha`
+/// `0x79b580`, FontString's `0x79cb70`, Frame's `0x774e90`), so `WorldFrame.Show(tex)` fails.
 #[test]
 fn the_six_look_alikes_are_not_shared() {
     let s = vm();
@@ -160,8 +132,7 @@ fn the_six_look_alikes_are_not_shared() {
     }
 }
 
-/// A receiver that is not a widget at all raises, and says *why* — the bridge resolves the
-/// receiver before either arm runs, so this error must not be flattened into a generic one.
+/// The bridge resolves the receiver before either arm runs, and its error names the reason.
 #[test]
 fn a_non_widget_receiver_raises_and_names_the_reason() {
     let s = vm();
diff --git a/crates/benilla-ui/src/script/tests/regions.rs b/crates/benilla-ui/src/script/tests/regions.rs
index 21b0aafa..d0fe9e05 100644
--- a/crates/benilla-ui/src/script/tests/regions.rs
+++ b/crates/benilla-ui/src/script/tests/regions.rs
@@ -1,10 +1,5 @@
-//! Regions join the anchor layout (decision 0068).
-//!
-//! The smeared-merchant root cause: region `<Size>`/`<Anchors>` used to be dropped — a region either
-//! filled its owner or (with a size) drew centered, and its anchors were ignored. Regions now resolve
-//! through the same leaf math as frames, off their own anchors and their own span; an edge nothing
-//! pins does NOT fall back to the owner's (decision 1664 retired that — the owner supplies scale and
-//! nothing else), because the span is content-derived and a pinned edge plus a span is a rect.
+//! Regions in the anchor layout: they resolve through the frames' leaf math, off their own anchors
+//! and content-derived span; the owner supplies scale, never a fallback edge.
 
 use super::common::script;
 use crate::layout::Rect;
@@ -56,11 +51,8 @@ fn region_texture_anchored_topleft_resolves_exact_rect() {
     );
 }
 
-/// A FontString's implicit extent is its measured TEXT, **floored at one FrameXML unit**
-/// (`CSimpleFontString::GetWidth 0x772930` / `GetHeight 0x772a60` — decision 1664). So a
-/// single-anchored FontString whose measure has not landed is a 1×1 box seated on its anchor,
-/// not a collapse onto the pinned edge and not the owner's rect: the floor is what makes such a
-/// FontString **always resolve**, and it is why the resolver needs no owner-edge fallback at all.
+/// A FontString's extent is its measured text floored at one unit (`GetWidth 0x772930`,
+/// `GetHeight 0x772a60`), so an unmeasured one is a 1x1 box on its anchor.
 #[test]
 fn region_fontstring_span_floors_at_one_unit_until_measured() {
     let mut s = script();
@@ -78,8 +70,7 @@ fn region_fontstring_span_floors_at_one_unit_until_measured() {
     )
     .unwrap();
     s.resolve();
-    // Pending measure: both spans floor at one unit. x runs right from the pinned left (5→6);
-    // a LEFT point pins the y-CENTER only (25), so y is the centre ± half a unit.
+    // Unmeasured: x runs 5..6 from the pinned left; LEFT pins the y centre (25), so y is ±0.5.
     assert_eq!(
         region_text_rect(&s, "Name"),
         Rect::new(24.5, 5.0, 25.5, 6.0)
@@ -98,16 +89,9 @@ fn region_fontstring_span_floors_at_one_unit_until_measured() {
     );
 }
 
-/// `ExhaustionLevelFillBar`'s exact shape, both ways (wow-re `region-size-fallback.md` §5, and
-/// the counterfactual it states): authored width **0**, one TOPLEFT anchor, and a `<Color>`.
-///
-/// The colour form installs a real 8×8 texture before any resolve (`0x7700a9` → `0x770360` →
-/// `0x44a900`), so `CSimpleTexture::GetWidth 0x770720` answers **8** for the authored zero and
-/// `combineEdge`'s first leg fires: RIGHT = LEFT + 8, and `assemble 0x767a20` returns 1. Strip the
-/// colour and there is no `CGxTex*` at all — the getter answers `0.0`, both `combineEdge` legs
-/// fail their `span != 0.0` test, and the rect never resolves. Our owner-edge fallback used to
-/// turn that second case into the owner's **full width** (1348's 1024-point white band); it is
-/// gone, so the two cases now differ by 8 points and a rect, exactly as they do on the reference.
+/// `ExhaustionLevelFillBar`'s shape, width 0 and one TOPLEFT anchor: its `<Color>` installs an 8x8
+/// texture (`0x7700a9` → `0x770360` → `0x44a900`), so `GetWidth 0x770720` answers 8; with no art
+/// it answers 0.0, and `assemble 0x767a20` leaves the rect unresolved.
 #[test]
 fn a_zero_width_solid_spans_eight_units_and_its_artless_twin_gets_no_rect() {
     let mut s = script();
@@ -142,11 +126,8 @@ fn a_zero_width_solid_spans_eight_units_and_its_artless_twin_gets_no_rect() {
 
 #[test]
 fn templateless_lua_region_without_anchors_never_draws() {
-    // Decision 1310 (wow-re `region-implicit-anchor.md`, VERIFIED): the creation-path implicit
-    // anchor fires from Lua CreateTexture only on a template-registry hit — a templateless region
-    // gets NOTHING, stays rect-less (the resolver has no zero-anchor fallback), and never renders,
-    // its explicit size notwithstanding. This replaced the old draws-centered-at-its-size
-    // fallback, which was refuted at the bytes (it was B180's squashed stack-split dialog).
+    // `CreateTexture 0x773a20` anchors a new texture only on a template hit, so a templateless one
+    // has no anchor, no rect and no draw, whatever its size.
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
     s.run(
@@ -193,11 +174,8 @@ fn region_set_all_points_fills_owner() {
     );
 }
 
-/// A region anchored to a **sibling region by name** resolves against the sibling's rect — the
-/// merchant label-plate shape (`plate LEFT → $parentSlot RIGHT −9`), which the old owner-fallback
-/// mis-anchored to the row's right edge (the jutting-plates bug the director's A/B caught). The
-/// plate is declared BEFORE the slot so only the resolve fixpoint (not declaration order) can
-/// order the chain; the slot itself is region-anchored to the row, one deeper than owner-direct.
+/// A region anchored by name to a sibling declared after it: `MerchantItemTemplate`'s label plate
+/// (`LEFT` to `$parentSlotTexture`'s `RIGHT`, -9, -18), ordered by the resolve alone.
 #[test]
 fn region_anchors_to_sibling_region_by_name() {
     let mut s = script();
@@ -232,7 +210,7 @@ fn region_anchors_to_sibling_region_by_name() {
             .and_then(|q| q.rect)
             .unwrap_or_else(|| panic!("no rect for {name}"))
     };
-    // Slot: row TOPLEFT (100..253, 100..144) → slot at (87, 157)-(151, 93)… y-up: top = 144+13 = 157.
+    // The row's TOPLEFT (100, 144) plus (-13, 13): the slot spans 87..151 by 93..157.
     let slot = rect("RowSlot");
     assert_eq!(
         (slot.left, slot.top),
@@ -240,24 +218,20 @@ fn region_anchors_to_sibling_region_by_name() {
         "slot at row TOPLEFT (-13,13)"
     );
     assert_eq!(slot.right, 151.0);
-    // Plate LEFT anchors to the SLOT's RIGHT (151) − 9 = 142 — NOT the row's right edge (253),
-    // which is where the old owner-fallback shoved it (253 − 9 + 128 = jutting past everything).
+    // The plate's LEFT is the slot's RIGHT (151) - 9 = 142, not the row's right edge (253).
     let plate = rect("RowPlate");
     assert_eq!(plate.left, 142.0, "plate.LEFT = slot.RIGHT − 9");
     assert_eq!(
         plate.right, 270.0,
         "plate spans its 128 width from the slot edge"
     );
-    // The LEFT single-point anchor centers the plate vertically on the target point (y-up):
-    // slot center-y = (93+157)/2 = 125, −18 → 107; ±39.
+    // A LEFT point centres the plate vertically: the slot's centre 125, -18 = 107, ±39.
     assert_eq!((plate.bottom, plate.top), (68.0, 146.0));
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `SetPortraitTexture(region, unit)` (the live model-bake portrait) binds a Texture region to a unit
-/// token, carried out through [`QuadContent::Texture::portrait_unit`] with no BLP path/color of its
-/// own (the app supplies the off-screen bake). A later `SetTexture` makes it an ordinary texture again,
-/// dropping the binding.
+/// `SetPortraitTexture` binds a Texture to a unit token, carried on the quad as `portrait_unit`
+/// with no path or colour (the app supplies the bake); a later `SetTexture` drops the binding.
 #[test]
 fn set_portrait_texture_binds_unit_token_then_settexture_clears_it() {
     let mut s = script();
@@ -291,7 +265,6 @@ fn set_portrait_texture_binds_unit_token_then_settexture_clears_it() {
     assert_eq!(color, None, "the model bake carries no vertex color");
     assert!(circular, "the frame-ring portrait is the round stencil");
 
-    // SetTexture reverts the region to an ordinary texture — the live-unit binding drops.
     s.run(r#" PFramePortrait:SetTexture("Interface\\Icons\\INV_Misc_QuestionMark") "#)
         .unwrap();
     s.resolve();
@@ -308,9 +281,8 @@ fn set_portrait_texture_binds_unit_token_then_settexture_clears_it() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `BenillaSetBoothTexture(region, token)` — the paper doll's **square** booth binding (decision
-/// 0208 §5): the same `portrait_unit` carriage as `SetPortraitTexture`, but `circular` stays
-/// false (the model pane samples the body bake edge to edge, no frame ring to mask for).
+/// `BenillaSetBoothTexture`, the paper doll's square booth binding: `SetPortraitTexture`'s
+/// carriage with `circular` false, as the model pane has no ring to mask for.
 #[test]
 fn benilla_set_booth_texture_binds_square() {
     let mut s = script();
@@ -344,13 +316,8 @@ fn benilla_set_booth_texture_binds_square() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The quest-log detail pane's shape (the 0109 look fix): a LONG region anchor chain — the real
-/// client's QuestLogFrame chains ~15 regions deep (title → objectives → obj1..10 → description →
-/// rewards) — with a frame (the reward item button) anchored to the chain's tail. The resolver
-/// must run to a true fixpoint: the old bounded rounds (2 frame × 3 region passes) left links past
-/// ~6 on silent owner-edge fallbacks and dropped the tail-anchored FRAME to the screen origin —
-/// decision 0088 §2's "button anchored to a chained region falls to the screen origin" finding,
-/// which forced every window into invented fixed offsets instead of ref-verbatim chains.
+/// The quest log detail pane's shape: a region anchor chain about 15 deep (title, objectives,
+/// description, rewards) with a frame anchored to its tail, which the resolve runs to a fixpoint.
 #[test]
 fn long_region_chain_resolves_and_a_frame_binds_to_its_tail() {
     let mut s = script();
@@ -402,10 +369,7 @@ fn long_region_chain_resolves_and_a_frame_binds_to_its_tail() {
     );
 }
 
-/// Decision 0088 §2 pinned "a child frame shown at runtime does not draw its own `<Layers>`
-/// FontStrings" — the engine constraint that forced every window FLAT. Re-tested after the
-/// resolver fixpoint (decision 0112): a child frame created and SHOWN at runtime, carrying its own
-/// text + texture regions, must extract both quads at the child's resolved position.
+/// A child frame created and shown at runtime draws its own regions where it resolves.
 #[test]
 fn child_frame_layers_regions_render_after_the_fixpoint() {
     let mut s = script();
@@ -449,11 +413,9 @@ fn child_frame_layers_regions_render_after_the_fixpoint() {
     );
 }
 
-/// `SetAlpha`/`GetAlpha` on a Texture/FontString — the region's *own* alpha, distinct from its
-/// owner frame's. A region draws at `ownAlpha × ownerFrame.alpha`: a single hop to the immediate
-/// owner (wow-re `propagation.md` — frame SetAlpha overwrite-cascades onto child *frames* and only
-/// invalidates child regions). The getter must return the region's value, never the frame's: the
-/// ref kit ramps a texture by reading it back (`CastingBarFlash:SetAlpha(GetAlpha() + step)`).
+/// A region draws at its own alpha times its owner frame's, one hop (`SetAlpha 0x76a690` cascades
+/// onto child frames, not regions), and `GetAlpha` answers its own: stock `CastingBarFrame.lua:133`
+/// ramps `CastingBarFlash` by reading it back.
 #[test]
 fn region_alpha_is_its_own_and_multiplies_the_owner_frames() {
     let mut s = script();
@@ -480,12 +442,10 @@ fn region_alpha_is_its_own_and_multiplies_the_owner_frames() {
     };
     assert_eq!(quad_alpha(&s), 1.0);
 
-    // The region's own alpha alone.
     s.run("tex:SetAlpha(0.5)").unwrap();
     assert_eq!(s.eval::<f32>("return tex:GetAlpha()").unwrap(), 0.5);
     assert_eq!(quad_alpha(&s), 0.5);
 
-    // …times the owner frame's. The frame's SetAlpha does NOT overwrite the region's own value.
     s.run("f:SetAlpha(0.5)").unwrap();
     assert_eq!(
         s.eval::<f32>("return tex:GetAlpha()").unwrap(),
@@ -494,7 +454,6 @@ fn region_alpha_is_its_own_and_multiplies_the_owner_frames() {
     );
     assert_eq!(quad_alpha(&s), 0.25, "0.5 region × 0.5 frame");
 
-    // A hidden region draws nothing regardless of alpha.
     s.run("tex:SetAlpha(1); tex:Hide()").unwrap();
     assert!(
         !s.extract()
@@ -504,14 +463,9 @@ fn region_alpha_is_its_own_and_multiplies_the_owner_frames() {
     );
 }
 
-/// **The texture-colour composition law** (wow-re `system/ui/scratch/texture-color-composition.md`,
-/// VERIFIED): a region's own solid colour is a real *texel* (`SetTexture(r,g,b,a)` generates an 8×8
-/// block at `+0xcc`), its vertex colour is a *separate* slot (`+0xb8`), and the draw
-/// **multiplies** them per channel, alpha included — it does not replace.
-///
-/// This is the reference `SkillFrame` row trough, verbatim: declared `<Color 1,1,1,0.2>`, then
-/// `SetVertexColor(0, 0, 0.75, 0.5)`'d. It draws at alpha `0.2 × 0.5 = 0.1`. benilla stored ONE
-/// colour slot until this test, which made the second call replace the first and drew it at 0.5.
+/// A solid colour is a texel (`0x770360`, an 8x8 block at `+0xcc`) and the vertex colour a
+/// separate slot (`SetVertexColor 0x77f750`, `+0xb8`); the draw multiplies them, alpha included,
+/// as stock `SkillFrame`'s row trough needs (`SkillFrame.xml:35`, `SkillFrame.lua:158`).
 #[test]
 fn a_solid_colour_texel_multiplies_with_the_vertex_colour() {
     let mut s = script();
@@ -551,15 +505,14 @@ fn a_solid_colour_texel_multiplies_with_the_vertex_colour() {
         Some([0.0, 0.0, 0.75, 0.1]),
         "texel x vertex, alpha included: 0.2 x 0.5 = 0.1, NOT 0.5"
     );
-    // The API readback is the vertex slot itself, not the product — the two are distinct storage.
+    // `GetVertexColor` reads the vertex slot, not the product.
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return trough:GetVertexColor()")
             .unwrap(),
         (0.0, 0.0, 0.75, 0.5)
     );
 
-    // Art and a solid colour share the `+0xcc` slot: setting a path releases the generated texel,
-    // and what is left is the tint alone for the renderer to modulate the sample by.
+    // Art and a solid colour share `+0xcc`: a path releases the texel and leaves the tint.
     s.run(r#"trough:SetTexture("Interface\\Bar.blp")"#).unwrap();
     let tinted = s
         .extract()
@@ -580,14 +533,8 @@ fn a_solid_colour_texel_multiplies_with_the_vertex_colour() {
     );
 }
 
-/// **`SetDesaturated` rides the extract, and only against real ART** (decision 1327).
-///
-/// The state was stored from the day the verb landed and read by nobody, which is why every
-/// greyed-out affordance in the UI was a brightness tint (B162's talent tree). The flag now travels
-/// on the quad, so this pins the two ends of that wire — set/clear — plus the one carve-out: a
-/// PATHLESS solid has its colour folded into the quad's tint and draws against a 1x1 white texel,
-/// so a shader that greys the texel would grey white and change nothing. Carrying the flag there
-/// would read as honoured while doing nothing at all, so extract drops it.
+/// The desaturate flag rides an art quad only: a pathless solid draws its colour as the quad's tint
+/// over a white texel, which greying leaves white, so extract drops the flag there.
 #[test]
 fn desaturation_rides_the_extract_for_art_and_never_for_a_solid() {
     let mut s = script();
@@ -628,17 +575,12 @@ fn desaturation_rides_the_extract_for_art_and_never_for_a_solid() {
         "a pathless solid never carries it — greying a white texel is a no-op dressed as a feature"
     );
 
-    // And it clears — the reference's own `SetItemButtonDesaturated(button, nil)` restore.
     s.run("art:SetDesaturated(nil)").unwrap();
     assert!(!grey(&s, true), "clearing the flag restores full colour");
 }
 
-/// Read a Texture region's desaturation state straight off the model, by name.
-///
-/// It has no getter in Lua on purpose — `IsDesaturated` (`0x79c2c0`) is in wow-re's ledger but its
-/// return shape is not carved, and inventing one to make a test convenient is how an unverified API
-/// gets shipped (decision 1327's own residual). The extract quad is the other way to see it, but a
-/// cleared texture emits no quad at all, which is exactly the case these tests need to observe.
+/// A Texture region's desaturation state, read off the model by name: `IsDesaturated`
+/// (`0x79c2c0`) is not built, and a cleared texture emits no quad to read it from.
 fn desaturated(s: &UiScript, name: &str) -> bool {
     let lua = s.lua();
     let model = lua.app_data_ref::<crate::script::Model>().expect("model");
@@ -647,15 +589,8 @@ fn desaturated(s: &UiScript, name: &str) -> bool {
     model.region_data.get(&h).is_some_and(|d| d.desaturated)
 }
 
-/// **`SetTexture` clears the desaturation — except when the path does not actually change**
-/// (wow-re `texture-desaturate-law.md` §2.3, VERIFIED; decision 1330).
-///
-/// `+0x128` is a `CGxShader*`, and `CSimpleTexture::SetTexture` writes it from a shader index the
-/// Lua binding always passes as slot 0 (permanently NULL). Storing a desaturate boolean *beside*
-/// the texture handle — which is what benilla did on 1327 — diverges on the single most common
-/// FrameXML shape there is: a repaint that re-sets the icon and expects the grey to follow the art.
-/// The same-path early-out (`0x770225`) is what makes the *idempotent* repaint keep its grey, and
-/// it is the half a plausible implementation drops.
+/// The desaturation is the shader slot `+0x128`, which `CSimpleTexture::SetTexture` rewrites with
+/// the binding's always-NULL slot 0, except that the same path returns early (`0x770225`).
 #[test]
 fn set_texture_clears_desaturation_unless_the_path_is_unchanged() {
     let s = script();
@@ -670,34 +605,28 @@ fn set_texture_clears_desaturation_unless_the_path_is_unchanged() {
     .unwrap();
     let grey = |s: &UiScript| desaturated(s, "ClrIcon");
 
-    // The idempotent repaint: same file, so the client returns before it can clear anything.
     s.run(r#"icon:SetTexture("Interface\\Icons\\Spell_Nature_Sleep")"#)
         .unwrap();
     assert!(grey(&s), "re-setting the SAME art keeps the grey");
 
-    // A different file reaches the write and zeroes the slot.
     s.run(r#"icon:SetTexture("Interface\\Icons\\Spell_Fire_Fireball")"#)
         .unwrap();
     assert!(!grey(&s), "a texture CHANGE clears the desaturation");
 
-    // The clear forms take the same leg (`test esi,esi` falls through to the write).
+    // nil takes the same leg (`test esi,esi` falls through to the write).
     s.run("icon:SetDesaturated(1) icon:SetTexture(nil)")
         .unwrap();
     assert!(!grey(&s), "SetTexture(nil) clears it too");
 
-    // The COLOUR form is a different function (`0x770360`) and is not one of the field's writers.
+    // The colour form (`0x770360`) does not write the shader slot.
     s.run(r#"icon:SetTexture("Interface\\Icons\\Spell_Nature_Sleep") icon:SetDesaturated(1)"#)
         .unwrap();
     s.run("icon:SetTexture(1, 0, 0)").unwrap();
     assert!(grey(&s), "the colour form does not touch the shader slot");
 }
 
-/// **`SetDesaturated`'s argument truth table has two arms that read backwards** (wow-re
-/// `texture-desaturate-law.md` §1.1, VERIFIED at `0x6f1c10`'s jump table; decision 1330).
-///
-/// `0x6f1c10(L, 2, default=1)` takes its DEFAULT on `LUA_TNONE`, so a bare `SetDesaturated()` greys
-/// — the opposite of the `if flag then` an implementation writes without looking. And a number is
-/// truncated to an int, so `SetDesaturated(0)` clears where truthiness would have greyed.
+/// `SetDesaturated` reads its flag with `0x6f1c10(L, 2, default=1)`: no argument (`LUA_TNONE`)
+/// greys, and a number is truncated to an int, so 0 and 0.5 clear.
 #[test]
 fn set_desaturated_takes_the_clients_argument_truth_table() {
     let s = script();
@@ -705,7 +634,6 @@ fn set_desaturated_takes_the_clients_argument_truth_table() {
         .unwrap();
     let grey = |s: &UiScript| desaturated(s, "ArgTex");
 
-    // NO ARGUMENT is ON — the LUA_TNONE default arm, not the nil arm.
     s.run("ArgTex:SetDesaturated()").unwrap();
     assert!(
         grey(&s),
@@ -715,26 +643,20 @@ fn set_desaturated_takes_the_clients_argument_truth_table() {
     s.run("ArgTex:SetDesaturated(nil)").unwrap();
     assert!(!grey(&s), "nil clears");
 
-    // A number truncating to zero clears; a non-zero one greys.
     s.run("ArgTex:SetDesaturated(1) ArgTex:SetDesaturated(0)")
         .unwrap();
     assert!(!grey(&s), "0 clears — the number arm truncates to int");
     s.run("ArgTex:SetDesaturated(0.5)").unwrap();
     assert!(!grey(&s), "0.5 truncates to 0 and clears");
 
-    // Both booleans, and Dewdrop's `true` (the call 98 corpus addons reach).
     s.run("ArgTex:SetDesaturated(true)").unwrap();
     assert!(grey(&s), "true greys");
     s.run("ArgTex:SetDesaturated(false)").unwrap();
     assert!(!grey(&s), "false clears");
 }
 
-/// The draw gate is the TEXTURE slot, never the colour (`texture-color-composition.md` §4,
-/// VERIFIED): `0x7706e0` tests `+0xcc` and emits NOTHING when it is empty, whatever the vertex
-/// colour holds. Since the tint deliberately survives `SetTexture(nil)` ("a tint outlives the art
-/// it was tinting"), a cleared region used to leak its tint out of extract as a solid plate — an
-/// occupied action button going empty on a character switch drew its surviving 1/1/1 usable-tint
-/// as a solid WHITE square (decision 1108; the 2026-07-10 grey wells were the same class).
+/// The draw gate is the texture slot, never the colour: `0x7706e0` emits nothing when `+0xcc` is
+/// empty, though the tint survives `SetTexture(nil)`.
 #[test]
 fn a_vertex_colour_without_a_texture_draws_nothing() {
     let mut s = script();
@@ -762,7 +684,6 @@ fn a_vertex_colour_without_a_texture_draws_nothing() {
     };
     assert_eq!(drawn(&s), 1, "tinted art draws");
 
-    // The slot empties: the art clears, the tint stays (distinct storage) — and nothing draws.
     s.run("icon:SetTexture(nil)").unwrap();
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return icon:GetVertexColor()")
@@ -777,21 +698,8 @@ fn a_vertex_colour_without_a_texture_draws_nothing() {
     );
 }
 
-/// **`SetTexture` ignores arguments past the path**, because the client's does.
-///
-/// The path form reads ONE argument (`0x770200`); only the colour form (`0x770360`) reads up to
-/// four, and a C function takes what it wants off the Lua stack and ignores the rest. We typed the
-/// trailing three as `Option<f32>` and so RAISED on a stray extra — `bad argument #3: error
-/// converting Lua boolean to f32` — where the client silently accepts.
-///
-/// The live case is `_LazyPig/LazyPigMenu.lua:182`:
-/// `texture_title:SetTexture("Interface\DialogFrame\UI-DialogBox-Header", true)`. The `true` is
-/// meaningless in 1.12; the addon reached us only once the survey began seating the addon registry.
-///
-/// Asserted as "does not raise", which is the whole claim — there is no `GetTexture` binding to read
-/// the path back through, and inventing one to satisfy a test would be the tail wagging the dog.
-/// The colour form is exercised alongside so the fix cannot have made it lax: a non-numeric channel
-/// must take the same default a missing one does, exactly as `lua_tonumber` of a non-number is 0.
+/// `SetTexture`'s path form reads one argument (`0x770200`) and its colour form up to four
+/// (`0x770360`), ignoring the rest; a non-numeric channel reads as `lua_tonumber` reads it, 0.
 #[test]
 fn set_texture_ignores_arguments_past_the_path_like_the_client_does() {
     let s = script();
@@ -804,25 +712,15 @@ fn set_texture_ignores_arguments_past_the_path_like_the_client_does() {
     )
     .expect("a stray extra argument must not raise — the client ignores it");
 
-    // The colour form, with a boolean and a numeric string among the channels.
     s.run("t:SetTexture(0.25, '0.5', true)")
         .expect("the colour form must tolerate what lua_tonumber tolerates");
 
-    // And the ordinary shapes still work.
     s.run("t:SetTexture(nil) t:SetTexture('') t:SetTexture(1, 0, 0, 1)")
         .expect("clear, blank and the plain colour form are unaffected");
 }
 
-/// **`SetGradientAlpha` / `SetGradient` exist, store both stops, and paint.**
-///
-/// These were the single wall in front of the corpus's largest family: `FuBar\FuBar_Panel.lua:144`
-/// calls `SetGradientAlpha` while building the bar, so all 20 FuBar plugins died there — right after
-/// the chunk-name/`debugstack` fix got them that far.
-///
-/// Asserted on the region PAINTING (a gradient-only region must emit a quad, because the client
-/// generates the gradient into the same texture slot the colour form fills) and on the midpoint
-/// being what a one-tint quad shows. The full gradient stays on the region for a renderer that
-/// grows a second stop.
+/// A gradient fills the texture slot the colour form fills, so a gradient-only region paints;
+/// both stops are stored, and the quad paints their midpoint, not the gradient.
 #[test]
 fn a_gradient_is_stored_whole_and_painted_as_its_midpoint() {
     let mut s = script();
@@ -850,7 +748,7 @@ fn a_gradient_is_stored_whole_and_painted_as_its_midpoint() {
         "a region carrying only a gradient must paint, at the midpoint of its two stops"
     );
 
-    // The alpha-less twin: both stops opaque, and a non-"VERTICAL" token is horizontal.
+    // Any orientation token but "VERTICAL" is horizontal.
     s.run("t:SetGradient('HORIZONTAL', 1, 0, 0, 0, 0, 1)")
         .expect("SetGradient takes six colour arguments and no alpha");
     s.resolve();
@@ -865,12 +763,8 @@ fn a_gradient_is_stored_whole_and_painted_as_its_midpoint() {
     );
 }
 
-/// **The split itself: a Texture answers texture verbs and NOT text ones, and vice versa.**
-///
-/// Until this landed, one shared table meant a Texture answered `SetText` and a FontString answered
-/// `SetTexture` — a superset in both directions (wow-re
-/// `system/ui/scratch/texture-fontstring-method-split.md`: Texture's map `0x87c128` is 22 entries,
-/// FontString's `0xcf5400` is 32, both tail-calling the Region map and stopping there).
+/// Texture's map (`0x87c128`, 22 entries) and FontString's (`0xcf5400`, 32) each answer their own
+/// verbs, then fall back to the Region map and stop there.
 #[test]
 fn the_two_region_leaves_answer_their_own_maps() {
     let s = crate::script::UiScript::new().unwrap();
@@ -888,8 +782,7 @@ fn the_two_region_leaves_answer_their_own_maps() {
             == "function"
     };
 
-    // Texture-only, and the asymmetry the carve calls out: `SetVertexColor` is on BOTH leaves while
-    // `GetVertexColor` is Texture-only. No reasonable partition invents that.
+    // Texture-only; `GetVertexColor` is here though `SetVertexColor` is on both leaves.
     for m in [
         "SetTexture",
         "GetTexture",
@@ -903,8 +796,7 @@ fn the_two_region_leaves_answer_their_own_maps() {
         assert!(has(&s, "Tex", m), "a Texture answers {m}");
         assert!(!has(&s, "Str", m), "a FontString must NOT answer {m}");
     }
-    // `SetRotation` is 1.12's PLAYERMODEL verb (`0x84f1fc`/`0x505f00`), not a region one — it is in
-    // neither leaf map, and ours used to put it on Texture.
+    // `SetRotation` is 1.12's PlayerModel verb (`0x84f1fc`/`0x505f00`), in neither leaf map.
     for leaf in ["Tex", "Str"] {
         assert!(
             !has(&s, leaf, "SetRotation"),
@@ -922,8 +814,7 @@ fn the_two_region_leaves_answer_their_own_maps() {
         assert!(has(&s, "Str", m), "a FontString answers {m}");
         assert!(!has(&s, "Tex", m), "a Texture must NOT answer {m}");
     }
-    // On BOTH — and each leaf registers its own copy in the client, so these are NOT on the Region
-    // map and must not be hoisted into it.
+    // On both leaves, each registering its own copy, so not on the Region map.
     for m in [
         "SetVertexColor",
         "SetAlpha",
@@ -937,19 +828,13 @@ fn the_two_region_leaves_answer_their_own_maps() {
             "{m} is on both leaves"
         );
     }
-    // The Region map reaches both, through each leaf's own fallback.
     for m in crate::script::REGION_MAP_METHODS {
         assert!(
             has(&s, "Tex", m) && has(&s, "Str", m),
             "{m} is the Region map"
         );
     }
-    // **`GetStringHeight` is GONE and must stay gone.** 1.12 has no such method on any table (0
-    // hits in every encoding; the control `GetStringWidth` has 1), Blizzard's own FrameXML calls it
-    // 0 times, and ours was a byte-identical duplicate of `GetHeight` — which is the method the
-    // reference itself uses for this, falling through to the same cached measurement
-    // `GetStringWidth` reads. Keeping the width and dropping the height is not an oversight: the
-    // client really is asymmetric here.
+    // 1.12 has no `GetStringHeight` on any table; `GetHeight` reads the same measurement.
     assert!(
         !has(&s, "Str", "GetStringHeight"),
         "1.12 has no GetStringHeight"
@@ -968,12 +853,8 @@ fn the_two_region_leaves_answer_their_own_maps() {
     assert!(has(&s, "Str", "SetAlphaGradient") && !has(&s, "Tex", "SetAlphaGradient"));
 }
 
-/// **`SetPortraitToTexture` is a GLOBAL in 1.12, not a Texture method.**
-///
-/// `reference/1.12-globals.tsv` marks it `engine`, and both of the reference's own call sites pass a
-/// texture NAME: `ContainerFrame.lua:419` and `MailFrame.lua:174`. The first is the one that binds
-/// us — we SOURCE `ContainerFrame.lua` off the patch chain, so the client's own file calls this
-/// global inside our VM.
+/// `SetPortraitToTexture` is a 1.12 global, not a Texture method; stock `ContainerFrame.lua:419`
+/// and `MailFrame.lua:174` pass it a texture name.
 #[test]
 fn set_portrait_to_texture_is_a_global_taking_a_name() {
     let s = crate::script::UiScript::new().unwrap();
@@ -989,33 +870,23 @@ fn set_portrait_to_texture_is_a_global_taking_a_name() {
         s.eval::<String>("return Port:GetTexture()").unwrap(),
         "Interface\\ContainerFrame\\KeyRing-Bag-Icon"
     );
-    // The Texture METHOD is gone — 1.12's Texture map has no such entry.
     assert_eq!(
         s.eval::<String>("return type(Port.SetPortraitToTexture)")
             .unwrap(),
         "nil",
         "1.12 has no Texture:SetPortraitToTexture — it is a global"
     );
-    // An unknown name is not an error: the reference's callers compose names that may not exist
-    // yet, and nothing here may raise on the sourced file's behalf.
+    // An unknown name does not raise here; the reference raises "Couldn't find texture named"
+    // (`0x48d7db`).
     s.run(r#"SetPortraitToTexture("NoSuchPortrait", "Interface\\X")"#)
         .unwrap();
     assert!(s.errors().is_empty());
 }
 
-/// **`Region:GetWidth`/`GetHeight` are the VIRTUAL getters** — the same content-derived law the
-/// rect resolver calls, because the Lua bindings dispatch through the same geometry-vtable slots
-/// (`GetWidth 0x7a1e00` ends `ff 52 1c`, `GetHeight 0x7a2030` ends `ff 52 20`; decision 1670).
-///
-/// Both halves of the FontString row, each of which we had backwards:
-///
-/// * the **authored** value wins per axis — `0x772930`'s `jp 0x77294a` skips the measure entirely
-///   when the authored width is not `0.0`, so `<Size x="300" y="0"/>` reports 300 from the author
-///   and the height from the text (`CharacterNameText` is exactly that, in the reference's own
-///   file), where we used to report the 37-point measure;
-/// * on an axis authored `0` the **width** is the NATURAL, unwrapped extent — the very cell
-///   `GetStringWidth` returns (`0x772890`'s `[fs+0xfc]`) — while the **height** is the *wrapped*
-///   one (`0x7729b0`'s `[fs+0x100]`). We used to report the laid-out width for both.
+/// `Region:GetWidth`/`GetHeight` (`0x7a1e00`/`0x7a2030`) call the virtual size getters the rect
+/// resolver uses: a FontString's authored axis wins (`0x772930` skips the measure, `jp 0x77294a`),
+/// else its width is the unwrapped extent `GetStringWidth` reads (`0x772890`, `[fs+0xfc]`) and its
+/// height the wrapped one (`0x7729b0`, `[fs+0x100]`).
 #[test]
 fn the_size_getters_take_the_author_first_then_the_natural_width_and_wrapped_height() {
     let mut s = script();
@@ -1052,12 +923,8 @@ fn the_size_getters_take_the_author_first_then_the_natural_width_and_wrapped_hei
     assert!(s.take_errors().is_empty());
 }
 
-/// The floor, and the state the reference does not have. `0x772930`/`0x772a60` end in a one-unit
-/// clamp, so a genuinely empty string reads back **1**, never `0.0`. But a measure that has not
-/// LANDED is not an extent at all — it is the host round-trip a VM with **no measurer installed**
-/// still takes, which the reference has no equivalent of. A caller that guards
-/// `if h <= 0 then return end` reads that zero as "not yet"; flooring it would tell them to stop
-/// waiting. So: floor a known extent, not the absence of one.
+/// `0x772930`/`0x772a60` clamp to one unit, so an empty string reads 1. A host measure still in
+/// flight, a state the reference does not have, reads 0, so an `if h <= 0` guard keeps waiting.
 #[test]
 fn an_empty_string_reads_back_one_unit_and_a_pending_measure_reads_back_zero() {
     let mut s = script();
@@ -1079,10 +946,8 @@ fn an_empty_string_reads_back_one_unit_and_a_pending_measure_reads_back_zero() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A TEXTURE's getters are the same virtual law with the other override behind them
-/// (`0x770720`/`0x770790`): the authored value when it is not exactly `0.0`, else the art's own
-/// texel extent, else `0.0` — and **no floor**, which only the FontString override carries. This
-/// is the getter half of 1662; before it, Lua saw `0` for a size the screen was already drawing.
+/// A Texture's size getters (`0x770720`/`0x770790`): the authored value unless exactly `0.0`, else
+/// the art's texel extent, else `0.0`, with no floor.
 #[test]
 fn a_textures_getters_report_its_texel_span_on_an_unsized_axis() {
     let mut s = script();
@@ -1107,22 +972,12 @@ fn a_textures_getters_report_its_texel_span_on_an_unsized_axis() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **The three constructors' string arguments are FOUR different shapes, not one rule.**
-///
-/// Verified together in wow-re `ui/scratch/xml-template-name-lookup.md` §5.2 (§5 pair, orchestrator
-/// byte-arbitration). The discriminator is **not** the argument's type — it is whether the binding
-/// *tests* its parser's return, which is the sentence `numeric-arg-coercion-law.md` §6 had wrong:
-///
-/// | position | fetch | a table there | a number there |
-/// |---|---|---|---|
-/// | `CreateFontString`/`CreateTexture` `name`, `layer` | `0x6f3510` → `0x6f3690`, untested | absent | **accepted, stringified** |
-/// | `CreateFontString`/`CreateTexture` `inherits` | raw `lua_type == LUA_TSTRING`, no coercion | ignored | **ignored** |
-/// | `CreateFrame` `name`, `inherits` | `0x6f3690` **unguarded** | absent | **accepted, stringified** |
-/// | `CreateFrame` `kind` | `0x6f3510`, tested | **raises** | accepted |
-///
-/// The last two rows are the same value taking opposite paths from argument order alone:
-/// `CreateFrame` coerces at `0x70613f` *before* its `cmp 4`, and `0x6f7cb1` retags the number's
-/// stack slot **in place**, so a number arrives at the gate already a string.
+/// The constructors' string arguments take four shapes, by whether the binding tests its parser's
+/// return: a region constructor's `name` and `layer` (`0x6f3510` → `0x6f3690`, untested) and
+/// `CreateFrame`'s `name` and `inherits` (`0x6f3690`, unguarded) read a table as absent and
+/// stringify a number; a region constructor's `inherits` (a raw `lua_type == LUA_TSTRING`) ignores
+/// both; `CreateFrame`'s `kind` (`0x6f3510`, tested) raises on a table and takes a number, which
+/// `CreateFrame` coerces in place before its gate (`0x70613f`, `0x6f7cb1`).
 #[test]
 fn the_constructors_string_arguments_are_four_shapes_not_one() {
     let mut s = script();
@@ -1130,10 +985,7 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
     s.run(r#"host = CreateFrame("Frame", "ArgHost", UIParent)"#)
         .unwrap();
 
-    // ── pfUI's line, verbatim. `f.buffs[i]:CreateFontString(nil, "OVERLAY", f.buffs[i])` passes
-    //    the BUTTON as `inheritsFrom`. The real client constructs it, ignores the argument, and
-    //    logs nothing — this raised `bad argument #4` until 2026-08-30 and stopped pfUI, and with
-    //    it pfQuest, pfQuest-turtle and ShaguDPS.
+    // ── A table in `inherits` is ignored and the string still built; pfUI passes a button there.
     s.run(r#"fs = ArgHost:CreateFontString(nil, "OVERLAY", ArgHost)"#)
         .unwrap_or_else(|e| panic!("a table in `inherits` must be ignored, not raise: {e}"));
     assert_eq!(
@@ -1141,7 +993,6 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
         "table",
         "...and the FontString is really constructed"
     );
-    // Every other non-string in every region-constructor position: also silent, also constructed.
     for pos in ["{}, \"OVERLAY\"", "nil, {}", "true, false"] {
         for ctor in ["CreateFontString", "CreateTexture"] {
             s.run(&format!("r = ArgHost:{ctor}({pos})"))
@@ -1150,15 +1001,14 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
         }
     }
 
-    // ── A NUMBER is a string to `lua_isstring` — so it NAMES the region.
+    // ── A number passes `lua_isstring`, so it names the region.
     s.run("named = ArgHost:CreateTexture(4242)").unwrap();
     assert_eq!(
         s.eval::<String>("return named:GetName()").unwrap(),
         "4242",
         "a number in `name` is stringified, not dropped"
     );
-    // ...but NOT in `inherits`, whose gate reads the raw tag and never coerces. A number there is
-    // ignored, where the same number in CreateFrame's fourth argument would raise.
+    // `inherits` reads the raw tag, so a number there is ignored.
     s.run("ArgHost:CreateTexture(nil, nil, 5)")
         .unwrap_or_else(|e| panic!("a number in a region ctor's `inherits` is ignored: {e}"));
 
@@ -1169,21 +1019,15 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
         "77",
         "CreateFrame reads `name` through an UNGUARDED lua_tostring"
     );
-    // ...and an unresolvable `inherits` still raises, which is the pre-existing contract and the
-    // control for the changes above: loosening the OTHER positions must not have loosened this.
     assert!(
         s.run(r#"CreateFrame("Frame", nil, nil, "NoSuchTemplateAnywhere")"#)
             .is_err(),
         "an unresolvable template name still raises — the miss branch is luaL_error"
     );
 
-    // ── The layer argument is PERMISSIVE, and an unrecognised one is ARTWORK, not an error.
-    //    `0x6f18b0` returns 0 with its out-param unwritten and neither constructor reads the
-    //    result, so the pre-staged ARTWORK (2) stands. Matching is case-insensitive.
+    // ── The layer: case-insensitive, and an unrecognised one leaves the pre-staged ARTWORK.
     s.run(r#"lay = ArgHost:CreateTexture(nil, "not-a-layer")"#)
         .unwrap_or_else(|e| panic!("an unrecognised layer must not raise: {e}"));
-    // Read off the arena — 1.12 publishes no `GetDrawLayer`, so there is no Lua getter to ask,
-    // the same reason the sequence scrub is read this way in `modelframe`'s tests.
     let layer_of = |s: &UiScript, name: &str| {
         let lua = s.lua();
         let model = lua.app_data_ref::<crate::script::Model>().expect("model");
@@ -1211,12 +1055,9 @@ fn the_constructors_string_arguments_are_four_shapes_not_one() {
     );
 }
 
-/// The token is CANONICAL on the way out — `"NPC"`, which the stock merchant, guild registrar
-/// and trade windows all write (`MerchantFrame.lua:68`, `GuildRegistrarFrame.lua:4`,
-/// `TradeFrame.lua:41`), binds as `"npc"`. The reference resolves every unit token
-/// case-insensitively (`0x515970`'s ten compares are all `_strnicmp`), and the app samples the
-/// booth by this exact string — a raw `"NPC"` matched no slot and left the ring empty on all
-/// three windows (decision 2022).
+/// `SetPortraitTexture` lowercases the token, which the app matches exactly: the reference reads
+/// unit tokens case-insensitively (`0x515970`, `_strnicmp`), and stock `MerchantFrame.lua:68`
+/// passes `"NPC"`.
 #[test]
 fn set_portrait_texture_folds_the_token_to_lowercase() {
     let mut s = script();
@@ -1245,32 +1086,9 @@ fn set_portrait_texture_folds_the_token_to_lowercase() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **`FontString:GetText` substitutes nil for an EMPTY string, and that substitution is the
-/// getter's own** — `0x79d690` reads the cell, and eleven bytes before the pushstring it does a
-/// FIRST-BYTE test and zeroes the pointer on `'\0'`:
-///
-/// ```text
-/// 79d735 test eax,eax / je 0x79d740     ; NULL      -> substitute
-/// 79d73b cmp byte ptr [eax],0x0         ; the first-byte test
-/// 79d73e jne 0x79d742                   ; non-empty -> keep
-/// 79d740 xor eax,eax                    ; EMPTY     -> NULL
-/// 79d746 call 0x6f3890                  ; NULL -> pushnil
-/// ```
-///
-/// So it cannot return `""`, whatever the cell holds — and the cell really does hold non-NULL
-/// empty strings, because `SetText 0x771d80` never writes NULL to `+0xf0` on any leg: NULL and
-/// `""` share one leg that truncates the buffer in place. Per binding, not per family:
-/// `Button:GetText 0x780e10` carries the same substitution (`0x780ec5`), `EditBox:GetText
-/// 0x7985c0` carries none (wow-re `fontstring-text-cell-and-gettext-contract.md`, a §5 round;
-/// decision 2110).
-///
-/// The director's shape (Cartographer 2.02, the world map's hover label): the stock
-/// `WorldMapFrameAreaDescription` is blanked with `SetText("")` by `WorldMapPOI_OnEnter`/`_OnLeave`
-/// on **every** POI hover, and Cartographer's ZoneInfo reads
-/// `if WorldMapFrameAreaDescription:GetText() then` as "this POI has a status line, so put the
-/// zone's level range there instead of on the label". Answering `""` made that true forever after
-/// the first POI touch — the name lost its faction colour, the range moved to the description's own
-/// line beneath it, and nothing ever cleared it again.
+/// `FontString:GetText` (`0x79d690`) pushes nil for an empty string by a first-byte test
+/// (`0x79d73b`), though `SetText 0x771d80` keeps an empty buffer; `Button:GetText 0x780e10` does
+/// the same (`0x780ec5`), and `EditBox:GetText 0x7985c0` returns `""`.
 #[test]
 fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
     let s = script();
@@ -1287,15 +1105,12 @@ fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
             .unwrap()
     };
 
-    // Never written, and every shape of an empty write, all nil.
     assert_eq!(text_of(&s, "fresh"), None);
     for write in [r#"fresh:SetText("")"#, r#"fresh:SetText(nil)"#] {
         s.run(write).unwrap();
         assert_eq!(text_of(&s, "fresh"), None, "after `{write}`");
     }
 
-    // A string that HAS held text still reads nil once blanked — the substitution is the getter's,
-    // so it does not matter that the cell keeps a (truncated) buffer.
     s.run(r#"held:SetText("In Conflict")"#).unwrap();
     assert_eq!(text_of(&s, "held").as_deref(), Some("In Conflict"));
     s.run(r#"held:SetText("")"#).unwrap();
@@ -1307,7 +1122,7 @@ fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
     s.run(r#"held:SetText("back"); held:SetText(nil)"#).unwrap();
     assert_eq!(text_of(&s, "held"), None);
 
-    // Button:GetText carries the SAME substitution; Button:SetText(nil) is its own no-op guard.
+    // `Button:SetText(nil)` leaves the label alone.
     s.run(
         r#"
         local b = CreateFrame("Button", "TextCellButton")
@@ -1324,8 +1139,7 @@ fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
     s.run(r#"TextCellButton:SetText("")"#).unwrap();
     assert_eq!(text_of(&s, "TextCellButton"), None, "an empty label is nil");
 
-    // And the EditBox is the counter-example that keeps this from being hoisted: stock
-    // `MailFrame.lua` compares `GetText() == ""` and calls `strlen(GetText())` on one.
+    // Stock `MailFrame.lua:521` compares an EditBox's `GetText() == ""`.
     s.run(
         r#"
         local e = CreateFrame("EditBox", "TextCellEdit")
@@ -1341,18 +1155,8 @@ fn an_empty_fontstring_reads_back_nil_and_an_edit_box_does_not() {
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// **A `SetTexture` the host cannot resolve leaves the region's art alone** — it does not overwrite
-/// it with the path that failed (decision 2124).
-///
-/// The reference's load-failure arm is explicit about it: `0x770288 cmp [ebp-4],2; jl` →
-/// `0x77028e`–`0x7702b2` releases the handle it just built and returns 0 **without ever touching
-/// `+0xcc`** (wow-re `texture-service-name-resolution.md`). Ours stored the path first and used the
-/// probe's verdict only for the return value, so a mistyped or not-yet-shipped path erased the art
-/// it failed to replace — `GetTexture()` echoed the miss, and the extract dropped the quad, so the
-/// region went blank with nothing said anywhere.
-///
-/// The control that must not change is the second half: a resolvable path still replaces, and a VM
-/// with **no probe at all** still stores, because it has no backend to ask.
+/// A path that fails to load leaves the art alone (`0x770288` → `0x77028e`-`0x7702b2` returns 0
+/// without touching `+0xcc`); with no probe installed, every path is stored.
 #[test]
 fn an_unresolvable_set_texture_keeps_the_art_the_region_had() {
     let mut s = script();
@@ -1370,7 +1174,6 @@ fn an_unresolvable_set_texture_keeps_the_art_the_region_had() {
         "Interface\\Real"
     );
 
-    // The miss: nil back, and the art it could not replace is still there.
     assert!(
         s.eval::<bool>(r#"return t:SetTexture("Interface\\Nope") == nil"#)
             .unwrap(),
@@ -1382,7 +1185,6 @@ fn an_unresolvable_set_texture_keeps_the_art_the_region_had() {
         "the failed load overwrote the art the region was holding"
     );
 
-    // The control: a hit still replaces, and an explicit clear still clears.
     assert!(s
         .eval::<bool>(r#"return t:SetTexture("Interface\\Other") == 1"#)
         .unwrap());
@@ -1394,15 +1196,8 @@ fn an_unresolvable_set_texture_keeps_the_art_the_region_had() {
     assert!(s.eval::<bool>("return t:GetTexture() == nil").unwrap());
 }
 
-/// `Texture:GetBlendMode()` — ONE string, the reference's own spelling, round-tripping whatever
-/// `SetBlendMode` was given (`0x79a890`/`0x79a950`, table `0x87c128`, argc 1, arity 1, kinds
-/// `(string?)`).
-///
-/// The untouched default is asserted alongside the round trip because it is the load-bearing half:
-/// `ShaguTweaks/mods/dark-ui-elements.lua:169` guards a recolour with
-/// `region.GetBlendMode and region:GetBlendMode() == "ADD"`, so the answer an ordinary texture gives
-/// decides whether the reference's additive art is left alone. `"BLEND"` is the CSimpleTexture
-/// ctor's `[+0xd0] = 2` (`0x76fc64`).
+/// `Texture:GetBlendMode` (`0x79a890`, table `0x87c128`) answers one string, the mode
+/// `SetBlendMode` (`0x79a950`) set, `"BLEND"` by default (the ctor's `[+0xd0] = 2`, `0x76fc64`).
 #[test]
 fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
     let s = crate::script::UiScript::new().unwrap();
@@ -1414,7 +1209,6 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
     )
     .unwrap();
 
-    // Arity 1 and kind string, measured the way the shape gate measures it.
     assert_eq!(s.arity("BTex:GetBlendMode()").unwrap(), 1, "arity 1");
     assert_eq!(
         s.eval::<String>("return type(BTex:GetBlendMode())")
@@ -1428,7 +1222,6 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
         "an untouched texture is the ctor's mode 2"
     );
 
-    // Every one of the enum's five round-trips, including the three the renderer flattens.
     for mode in ["DISABLE", "ALPHAKEY", "BLEND", "ADD", "MOD"] {
         s.run(&format!(r#"BTex:SetBlendMode("{mode}")"#)).unwrap();
         assert_eq!(
@@ -1437,13 +1230,12 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
             "round trip through the setter"
         );
     }
-    // Case-insensitive in, canonical out — the setter coerces, the getter answers the table's name.
+    // Case-insensitive in, canonical out.
     s.run(r#"BTex:SetBlendMode("add")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return BTex:GetBlendMode()").unwrap(),
         "ADD"
     );
-    // A name outside the enum leaves the mode alone rather than inventing one.
     s.run(r#"BTex:SetBlendMode("NOT_A_MODE")"#).unwrap();
     assert_eq!(
         s.eval::<String>("return BTex:GetBlendMode()").unwrap(),
@@ -1451,7 +1243,6 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
         "an unknown name changes nothing"
     );
 
-    // A FontString is not a Texture: neither half of the pair is on its map.
     assert!(s
         .eval::<bool>(
             r#"local fs = BlendOwner:CreateFontString("BStr", "ARTWORK")
@@ -1460,14 +1251,8 @@ fn get_blend_mode_answers_one_string_and_defaults_to_the_ctors_blend() {
         .unwrap());
 }
 
-/// `Texture:GetTexCoordModifiesRect()` — the 1.12 predicate return, `1`/`nil` and never a Lua
-/// boolean (`0x79c120`, table `0x87c128`, argc 1, arity 1, kinds `(nil) | (number)`; decision 2118).
-/// `pfUI/modules/thirdparty-tbc.lua:319` calls it bare on a Texture.
-///
-/// The flag's effect on the region's rect is deliberately NOT wired (see
-/// `RegionData::tex_coord_modifies_rect`), so this asserts the state and the shape — and asserts
-/// the un-wiring too, by checking that setting the flag moves no rect: a future change that wires
-/// the geometry will fail here and have to say so.
+/// `Texture:GetTexCoordModifiesRect` (`0x79c120`, table `0x87c128`) answers `1` or nil. The flag is
+/// stored, not applied: on the reference it makes `SetTexCoord` re-derive the rect (`0x770462`).
 #[test]
 fn tex_coord_modifies_rect_is_one_slash_nil_and_moves_no_rect_yet() {
     let mut s = crate::script::UiScript::new().unwrap();
@@ -1511,8 +1296,7 @@ fn tex_coord_modifies_rect_is_one_slash_nil_and_moves_no_rect_yet() {
         "kind number, never boolean"
     );
 
-    // The flag is state only: a SetTexCoord under it still leaves the rect where the anchors and
-    // the size put it. When the geometry leg is built, this assertion is the one that must change.
+    // The assertion that changes when the rect re-derivation is built.
     s.run("TCMTex:SetTexCoord(0, 0.25, 0, 0.5)").unwrap();
     s.resolve();
     assert_eq!(
diff --git a/crates/benilla-ui/src/script/tests/resize_bounds.rs b/crates/benilla-ui/src/script/tests/resize_bounds.rs
index b98c0142..6f1d7df6 100644
--- a/crates/benilla-ui/src/script/tests/resize_bounds.rs
+++ b/crates/benilla-ui/src/script/tests/resize_bounds.rs
@@ -1,21 +1,8 @@
-//! **The resize-bounds quad**, pinned to wow-re's byte carve
-//! (`system/ui/scratch/resize-bounds-and-button-fontstring.md`, §5 trio, 2026-08-21).
-//!
-//! Every assertion here is one the first cut of this code got *wrong* by writing the plausible
-//! thing instead of the read thing — which is why they are pinned rather than trusted:
-//!
-//! | the plausible thing | the byte thing |
-//! |---|---|
-//! | an unset bound is "no bound" and reads back `nil` | all four fields are `0.0`, the getters push two numbers |
-//! | a floor of `1.0` keeps a drag sane | there is **no floor** — a drag goes through zero into negatives |
-//! | a bound is a bound | only an exactly-`0.0` bound is the disable sentinel; a **negative** one clamps |
-//! | `min > max` is a caller error to reconcile | nothing reconciles it; **max wins** |
-//! | setting a bound fixes a frame already outside it | nothing happens until the next drag tick |
-//! | `StartSizing("CENTER")` grips no edge, so it is a no-op | it is the **move** arm, and it is never bounded |
+//! The resize-bounds quad, as the reference stores it (`CLayoutFrame 0x767680`).
 
 use crate::script::UiScript;
 
-/// A resizable 200×100 frame planted at its BOTTOMLEFT, the shape the sibling sizing test uses.
+/// A resizable 200×100 frame planted at its BOTTOMLEFT.
 fn sizer() -> UiScript {
     let mut s = UiScript::new().unwrap();
     s.set_screen_size(1024.0, 768.0);
@@ -32,7 +19,6 @@ fn sizer() -> UiScript {
     s
 }
 
-/// The getters answer **two numbers**, `0, 0` on a frame nobody bounded — never `nil`.
 #[test]
 fn a_virgin_frames_bounds_read_back_as_zero_not_nil() {
     let s = sizer();
@@ -58,8 +44,7 @@ fn a_virgin_frames_bounds_read_back_as_zero_not_nil() {
         s.eval::<(f64, f64)>("return Sizer:GetMaxResize()").unwrap(),
         (400.0, 300.0)
     );
-    // Setting one pair rewrites the other verbatim — the reference reads all four and writes all
-    // four, so the untouched pair round-trips rather than being cleared.
+    // The reference writes all four fields, so the untouched pair round-trips.
     s.run("Sizer:SetMinResize(10, 10)").unwrap();
     assert_eq!(
         s.eval::<(f64, f64)>("return Sizer:GetMaxResize()").unwrap(),
@@ -67,8 +52,6 @@ fn a_virgin_frames_bounds_read_back_as_zero_not_nil() {
     );
 }
 
-/// The argument gate is `lua_isnumber` — a numeric **string** passes; everything else raises the
-/// reference's own `Usage:` text, naming the frame.
 #[test]
 fn the_setters_gate_is_lua_isnumber_and_the_usage_text_is_the_references() {
     let s = sizer();
@@ -78,7 +61,7 @@ fn the_setters_gate_is_lua_isnumber_and_the_usage_text_is_the_references() {
         (120.0, 60.0),
         "a numeric string is coerced, as 5.0's lua_isnumber does"
     );
-    // Arguments past the third are ignored — no upper arity check.
+    // Arguments past the third are ignored.
     s.run("Sizer:SetMaxResize(400, 300, 999, \"x\")").unwrap();
     assert_eq!(
         s.eval::<(f64, f64)>("return Sizer:GetMaxResize()").unwrap(),
@@ -102,17 +85,13 @@ fn the_setters_gate_is_lua_isnumber_and_the_usage_text_is_the_references() {
     assert!(err.contains("Usage: Sizer:SetMaxResize(maxWidth, maxHeight)"));
 }
 
-/// **A drag clamps against the bounds, and the anchor stops exactly on them.**
-///
-/// The second half is the rebate: without it the size pins at the bound while the delta keeps
-/// feeding the anchor, so a window held past its minimum stops shrinking and starts *walking*.
+/// A saturated grip stops the gripped edge on the bound rather than letting the frame walk.
 #[test]
 fn a_drag_clamps_and_the_planted_edge_stops_on_the_bound() {
     let mut s = sizer();
     s.run("Sizer:SetMinResize(150, 60) Sizer:SetMaxResize(260, 300)")
         .unwrap();
 
-    // RIGHT grip, dragged far right: width saturates at the max, the left edge never moves.
     s.mouse_move(300.0, 100.0);
     s.run("Sizer:StartSizing(\"RIGHT\")").unwrap();
     s.mouse_move(900.0, 100.0);
@@ -121,8 +100,7 @@ fn a_drag_clamps_and_the_planted_edge_stops_on_the_bound() {
     assert_eq!(s.eval::<f32>("return Sizer:GetLeft()").unwrap(), 100.0);
     s.run("Sizer:StopMovingOrSizing()").unwrap();
 
-    // LEFT grip, dragged far right: width saturates at the MIN — and the left edge lands exactly
-    // on it (100 + 260 − 150 = 210), not wherever the raw cursor delta would have carried it.
+    // LEFT grip dragged far right: width saturates at the min, the left edge at 100 + 260 - 150.
     let right_before = s.eval::<f32>("return Sizer:GetRight()").unwrap();
     s.mouse_move(300.0, 100.0);
     s.run("Sizer:StartSizing(\"LEFT\")").unwrap();
@@ -139,7 +117,6 @@ fn a_drag_clamps_and_the_planted_edge_stops_on_the_bound() {
         right_before,
         "the ungripped edge must not move"
     );
-    // Dragging further while saturated moves nothing at all.
     s.mouse_move(1500.0, 100.0);
     s.resolve();
     assert_eq!(
@@ -149,7 +126,7 @@ fn a_drag_clamps_and_the_planted_edge_stops_on_the_bound() {
     s.run("Sizer:StopMovingOrSizing()").unwrap();
 }
 
-/// **`0.0` is the disable sentinel, per field** — and a NEGATIVE bound is live.
+/// Only an exact 0.0 is the disable sentinel, per field.
 #[test]
 fn zero_disables_and_a_negative_bound_still_clamps() {
     let mut s = sizer();
@@ -168,7 +145,7 @@ fn zero_disables_and_a_negative_bound_still_clamps() {
     assert_eq!(s.eval::<f32>("return Sizer:GetHeight()").unwrap(), 90.0);
     s.run("Sizer:StopMovingOrSizing()").unwrap();
 
-    // A negative maximum is NOT a sentinel: it clamps, and the width really does go negative.
+    // A negative maximum clamps, and the width goes negative.
     s.run("Sizer:SetMaxResize(-50, 0) Sizer:SetMinResize(0, 0)")
         .unwrap();
     s.mouse_move(300.0, 100.0);
@@ -178,7 +155,6 @@ fn zero_disables_and_a_negative_bound_still_clamps() {
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), -50.0);
 }
 
-/// With no bound at all there is **no floor** — the client has no `1.0` and neither do we.
 #[test]
 fn an_unbounded_drag_goes_through_zero() {
     let mut s = sizer();
@@ -193,7 +169,7 @@ fn an_unbounded_drag_goes_through_zero() {
     );
 }
 
-/// **`min > max` ends at `max`** — min is applied first, then max, and nothing reconciles them.
+/// Min is applied first, then max, and nothing reconciles them.
 #[test]
 fn a_min_above_the_max_resolves_to_the_max() {
     let mut s = sizer();
@@ -206,8 +182,7 @@ fn a_min_above_the_max_resolves_to_the_max() {
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 200.0);
 }
 
-/// **Setting a bound a frame already violates does nothing** until the next drag tick — the setter
-/// does not touch the size, and no other write path consults the bounds.
+/// Only a drag tick consults the bounds; the setter and every other write path do not.
 #[test]
 fn a_bound_set_late_does_not_resize_the_frame() {
     let mut s = sizer();
@@ -215,12 +190,10 @@ fn a_bound_set_late_does_not_resize_the_frame() {
     s.resolve();
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 200.0);
     assert_eq!(s.eval::<f32>("return Sizer:GetHeight()").unwrap(), 100.0);
-    // A programmatic SetWidth past the bound is not clamped either — VERIFIED: no layout vtable
-    // in the client overrides the plain, non-clamping SetWidth/SetHeight.
+    // No layout vtable in the client overrides the plain, non-clamping SetWidth/SetHeight.
     s.run("Sizer:SetWidth(50)").unwrap();
     s.resolve();
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 50.0);
-    // The first drag tick is what snaps it into range.
     s.mouse_move(300.0, 100.0);
     s.run("Sizer:StartSizing(\"RIGHT\")").unwrap();
     s.mouse_move(301.0, 100.0);
@@ -228,7 +201,7 @@ fn a_bound_set_late_does_not_resize_the_frame() {
     assert_eq!(s.eval::<f32>("return Sizer:GetWidth()").unwrap(), 400.0);
 }
 
-/// **`StartSizing("CENTER")` translates the frame and is never bounded** — the pump's case 4.
+/// `StartSizing("CENTER")` is the sizing pump's case 4, a move.
 #[test]
 fn a_center_grip_moves_the_frame_and_ignores_the_bounds() {
     let mut s = sizer();
@@ -253,8 +226,7 @@ fn a_center_grip_moves_the_frame_and_ignores_the_bounds() {
     assert_eq!(s.eval::<f32>("return Sizer:GetLeft()").unwrap(), 140.0);
 }
 
-/// `<ResizeBounds>` in XML reaches the same four fields — and a block naming only `<minResize>`
-/// **resets the max pair to unbounded**, because the client writes all four unconditionally.
+/// The client's `<ResizeBounds>` writes all four fields, so a lone `<minResize>` zeroes the max.
 #[test]
 fn the_xml_element_writes_both_pairs() {
     let mut s = UiScript::new().unwrap();
@@ -281,8 +253,7 @@ fn the_xml_element_writes_both_pairs() {
             .unwrap(),
         (608.0, 400.0)
     );
-    // An authored `<Size>` outside the authored bounds survives load unchanged — neither path
-    // clamps, whatever the document order.
+    // An authored `<Size>` outside the bounds survives load unclamped.
     assert_eq!(s.eval::<f32>("return Chatty:GetWidth()").unwrap(), 400.0);
 
     let partial = benilla_ui_doc(
diff --git a/crates/benilla-ui/src/script/tests/scrollframe.rs b/crates/benilla-ui/src/script/tests/scrollframe.rs
index 8d936239..650d5cfb 100644
--- a/crates/benilla-ui/src/script/tests/scrollframe.rs
+++ b/crates/benilla-ui/src/script/tests/scrollframe.rs
@@ -1,13 +1,11 @@
-//! ScrollFrame (decision 0112 — the ScrollFrame mechanism): the scroll-child layout override, the
-//! live vertical-scroll range, the ScrollFrame clip on `extract`, and the clip-gated `hit_test`.
+//! ScrollFrame: the scroll-child layout override, the live scroll ranges, the clip on `extract`
+//! and the clip-gated `hit_test`.
 
 use super::common::script;
 use crate::layout::Rect;
 use crate::script::QuadContent;
 
-/// The rect of the first Texture quad whose path equals `marker` (a bare texture with no anchors of
-/// its own draws at exactly its owner frame's resolved rect — the cheapest way to read a frame's
-/// resolved rect back out through the public `extract` surface).
+/// The rect of the first Texture quad whose path is `marker`.
 fn marker_rect(quads: &[crate::script::ExtractedQuad], marker: &str) -> Option<Rect> {
     quads.iter().find_map(|q| match &q.content {
         QuadContent::Texture { path: Some(p), .. } if p == marker => q.rect,
@@ -15,8 +13,7 @@ fn marker_rect(quads: &[crate::script::ExtractedQuad], marker: &str) -> Option<R
     })
 }
 
-/// `Some(clip)` when a marker quad was found (`clip` itself `Option<Rect>`); `None` if no such
-/// marker quad exists at all (a test-authoring mistake, not a legitimate "unclipped").
+/// The clip of the first Texture quad whose path is `marker`; `None` if there is no such quad.
 fn marker_clip(quads: &[crate::script::ExtractedQuad], marker: &str) -> Option<Option<Rect>> {
     quads.iter().find_map(|q| match &q.content {
         QuadContent::Texture { path: Some(p), .. } if p == marker => Some(q.clip),
@@ -72,11 +69,8 @@ fn get_scroll_child_roundtrips_wrapper_and_name_and_clears_on_nil() {
     .unwrap();
 }
 
-/// The sign convention (verified against the design's own worked example): frame top 500, vertical
-/// 40 ⇒ child top 540. Also covers 0, an offset PAST the range and one below zero — both stored and
-/// applied verbatim, since the reference's `0x786db0` never reads the range (decision 2017) — and
-/// that `SetScrollChild(nil)` restores the child's own authored anchor (never mutated — the
-/// override is a local map).
+/// A positive offset lifts the child; offsets past the range or below zero are stored and applied
+/// as given, since `0x786db0` never reads the range.
 #[test]
 fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
     let mut s = script();
@@ -119,9 +113,7 @@ fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
         "vertical=40 -> child top = frame top + 40 (a positive offset lifts the child)"
     );
 
-    // range = child_h(600) - frame_h(200) = 400, and the offset is NOT clamped to it: 450 is
-    // stored and applied as 450. (Keeping the bar inside the range is FrameXML's job, through the
-    // Slider's [min, max] — the engine has no opinion.)
+    // The range is 600 - 200 = 400; keeping the bar inside it is the FrameXML slider's job.
     s.run("SF:SetVerticalScroll(450)").unwrap();
     s.resolve();
     assert_eq!(
@@ -135,7 +127,6 @@ fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
         Some(950.0),
         "applied verbatim: frame top 500 + 450"
     );
-    // Nor at zero.
     s.run("SF:SetVerticalScroll(-30)").unwrap();
     s.resolve();
     assert_eq!(
@@ -149,8 +140,7 @@ fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
         "a negative offset lowers the child: frame top 500 - 30"
     );
 
-    // SetScrollChild(nil): the override stops being computed — the child's own authored anchor
-    // (TOPLEFT, screen, +20,-20) re-applies with no restore step needed (it was never touched).
+    // Clearing the child stops the override, and its own untouched anchor applies again.
     s.run("SF:SetScrollChild(nil)").unwrap();
     s.resolve();
     let quads = s.extract();
@@ -161,11 +151,8 @@ fn scroll_child_top_tracks_vertical_scroll_unclamped_then_restores_on_clear() {
     );
 }
 
-/// The reference's `0x786db0` is gated on the offset actually CHANGING (a compare against the
-/// stored value, nothing else): a `SetVerticalScroll` to the value already held re-lays nothing out
-/// and fires no `OnVerticalScroll`. The same shape as the Slider's `SetValue` change-gate (decision
-/// 0250) — the other half of what keeps the bar ↔ frame wiring from ringing — and a value past the
-/// range is a change like any other.
+/// `0x786db0` acts only when the offset differs from the stored one; a value past the range is
+/// still a change.
 #[test]
 fn set_vertical_scroll_fires_on_vertical_scroll_only_on_a_change() {
     let mut s = script();
@@ -211,7 +198,6 @@ fn vertical_scroll_range_is_live_and_zero_when_unresolved_or_childless_or_shorte
     "#,
     )
     .unwrap();
-    // Before resolve: no resolved rects yet -> 0.
     assert_eq!(
         s.eval::<f32>("return SF:GetVerticalScrollRange()").unwrap(),
         0.0,
@@ -225,7 +211,6 @@ fn vertical_scroll_range_is_live_and_zero_when_unresolved_or_childless_or_shorte
         "600 - 200"
     );
 
-    // A child shorter than the frame: 0, not negative.
     s.run("Child:SetWidth(300); Child:SetHeight(150)").unwrap();
     s.resolve();
     assert_eq!(
@@ -234,7 +219,6 @@ fn vertical_scroll_range_is_live_and_zero_when_unresolved_or_childless_or_shorte
         "child shorter than frame -> 0, not negative"
     );
 
-    // No child at all: 0.
     s.run("SF:SetScrollChild(nil)").unwrap();
     assert_eq!(
         s.eval::<f32>("return SF:GetVerticalScrollRange()").unwrap(),
@@ -243,11 +227,8 @@ fn vertical_scroll_range_is_live_and_zero_when_unresolved_or_childless_or_shorte
     );
 }
 
-/// The range is in LOCAL units, not screen px — `child:GetHeight() - self:GetHeight()`, the
-/// contract the method states. It has to be: `SetVerticalScroll` becomes the child's anchor
-/// y-offset, which the solver multiplies by the child's scale, so a screen-px range against a
-/// local-unit offset makes a SCALED frame stop short of its own end and strand the tail of its
-/// content. (Found on the era-scaled options window's page scroll, which lost 22% of its travel.)
+/// The range is `child:GetHeight() - self:GetHeight()` in local units, like the offset, which
+/// becomes the child's anchor y-offset and is scaled with it.
 #[test]
 fn vertical_scroll_range_is_local_units_on_a_scaled_frame() {
     let mut s = script();
@@ -276,8 +257,6 @@ fn vertical_scroll_range_is_local_units_on_a_scaled_frame() {
         400.0,
         "…which is exactly what the widget contract says it is"
     );
-    // And the clamp agrees, so scrolling to the range really reaches the end: the child's bottom
-    // lands on the frame's.
     s.run("SF:SetVerticalScroll(400)").unwrap();
     s.resolve();
     assert_eq!(
@@ -293,9 +272,8 @@ fn vertical_scroll_range_is_local_units_on_a_scaled_frame() {
     );
 }
 
-/// `OnVerticalScroll` carries the value AS STORED — past the range too (decision 2017: the
-/// reference's `0x786db0` fires with `[+0x328]`, which it never clamps) — under the RF-0025
-/// conventions, and `UpdateScrollChildRect` fires `OnScrollRangeChanged` with the live range.
+/// `0x786db0` fires `OnVerticalScroll` with the unclamped stored value `[+0x328]`, under the
+/// handler conventions of `0x704f10`.
 #[test]
 fn vertical_scroll_fires_as_given_and_update_rect_fires_range_changed() {
     let mut s = script();
@@ -312,7 +290,7 @@ fn vertical_scroll_fires_as_given_and_update_rect_fires_range_changed() {
         seen_v = nil
         frame:SetScript("OnVerticalScroll", function(self, offset)
             seen_v = offset
-            assert(self == frame and arg1 == offset, "RF-0025 conventions carry the value")
+            assert(self == frame and arg1 == offset, "handler-firing conventions carry the value")
         end)
         seen_lo, seen_hi = nil, nil
         frame:SetScript("OnScrollRangeChanged", function(self, lo, hi)
@@ -336,12 +314,8 @@ fn vertical_scroll_fires_as_given_and_update_rect_fires_range_changed() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The Era idiom `UpdateScrollChildRect` exists to serve — resize the content, then immediately ask
-/// for the new range, in ONE script tick with no intervening [`UiScript::resolve`] call in between
-/// (exactly how the app's own drive loop runs Lua: `ui_script/mod.rs` resolves once per FRAME, not
-/// once per script statement) — must see the JUST-set size, not the last frame's stale `resolved`
-/// rect. Before `UpdateScrollChildRect` forced its own fresh resolve, this fired the OLD (here,
-/// zero) range on the very call whose whole job is reporting the new one.
+/// `UpdateScrollChildRect` resolves for itself, so a resize earlier in the same tick counts; the
+/// app resolves only once per frame.
 #[test]
 fn update_scroll_child_rect_sees_a_same_tick_resize_with_no_intervening_resolve() {
     let mut s = script();
@@ -375,17 +349,12 @@ fn update_scroll_child_rect_sees_a_same_tick_resize_with_no_intervening_resolve(
         "UpdateScrollChildRect must resolve the JUST-set height itself, not report the stale \
          (pre-resize) range from the last full UiScript::resolve"
     );
-    // GetVerticalScrollRange() also benefits (same fresh `resolved`), and a same-tick
-    // SetVerticalScroll now clamps against the true, current range instead of the stale one.
     assert_eq!(
         s.eval::<f32>("return SF:GetVerticalScrollRange()").unwrap(),
         400.0
     );
 }
 
-/// The clip on `extract`: the scroll child's own quads, and a grandchild region nested arbitrarily
-/// deep under it, carry `clip = Some(the scrollframe's resolved rect)`; a sibling outside the
-/// ScrollFrame entirely carries `None`.
 #[test]
 fn extract_clips_the_scroll_childs_whole_subtree_and_leaves_a_sibling_unclipped() {
     let mut s = script();
@@ -435,9 +404,6 @@ fn extract_clips_the_scroll_childs_whole_subtree_and_leaves_a_sibling_unclipped(
     );
 }
 
-/// Nested ScrollFrames intersect their rects (decision 0112 §4): an inner ScrollFrame living inside
-/// an outer one's scroll child clips its own content to the intersection of both rects, not just
-/// the innermost.
 #[test]
 fn nested_scrollframes_intersect_their_clip_rects() {
     let mut s = script();
@@ -473,8 +439,7 @@ fn nested_scrollframes_intersect_their_clip_rects() {
     let quads = s.extract();
 
     let outer_rect = Rect::new(250.0, 0.0, 550.0, 400.0);
-    // Inner's OWN rect (unclipped by itself): TOPLEFT anchored to C1 (top 550) at (350,-30) -> top
-    // 520, left 350; size 200x150 -> bottom 370, right 550.
+    // Inner's own rect: TOPLEFT at C1's (350, -30), so top 520 and left 350, sized 200x150.
     let inner_rect = Rect::new(370.0, 350.0, 520.0, 550.0);
     let intersection = Rect::new(
         inner_rect.bottom.max(outer_rect.bottom),
@@ -482,8 +447,7 @@ fn nested_scrollframes_intersect_their_clip_rects() {
         inner_rect.top.min(outer_rect.top),
         inner_rect.right.min(outer_rect.right),
     );
-    // A genuine intersection, not just "pick the smaller rect": inner's right edge (550) is cut
-    // back to outer's (400), while inner's tighter bottom/left/top edges win.
+    // Outer cuts inner's right edge from 550 to 400; inner's other edges are tighter.
     assert_eq!(intersection, Rect::new(370.0, 350.0, 520.0, 400.0));
 
     assert_eq!(
@@ -508,9 +472,6 @@ fn nested_scrollframes_intersect_their_clip_rects() {
     );
 }
 
-/// Hit-testing (decision 0112 §5): a button inside the scroll child, scrolled out of the frame's
-/// rect, must not hit even though its own resolved rect contains the cursor; scrolled into view, it
-/// hits normally.
 #[test]
 fn hit_test_denies_a_button_clipped_out_and_admits_it_once_scrolled_into_view() {
     let mut s = script();
@@ -534,16 +495,14 @@ fn hit_test_denies_a_button_clipped_out_and_admits_it_once_scrolled_into_view()
     .unwrap();
     s.resolve();
 
-    // vertical=0: child top 500, button top 500-400=100, bottom 80 — its OWN rect contains (25,90),
-    // but that's well outside the frame's clip [300,500].
+    // At 0 the button spans 80..100, outside the frame's clip of 300..500.
     assert_eq!(
         s.hit_test(25.0, 90.0),
         None,
         "the button's own rect contains the point, but the ScrollFrame's clip excludes it"
     );
 
-    // Scroll 250px: button top 500+250-400=350, bottom 330 — now inside both its own rect AND the
-    // frame's clip window.
+    // Scrolled by 250 the button spans 330..350, inside the clip.
     s.run("SF:SetVerticalScroll(250)").unwrap();
     s.resolve();
     assert!(
@@ -552,9 +511,7 @@ fn hit_test_denies_a_button_clipped_out_and_admits_it_once_scrolled_into_view()
     );
 }
 
-/// `UpdateScrollChildRect` right after the SetTexts that fill a pane reads a range that already
-/// counts the wrapped text — the reference's measure is synchronous, and with a font engine
-/// installed so is ours (1944; stock `QuestLog_UpdateQuestDetails` is the caller that found it).
+/// The reference measures text synchronously, as stock `QuestLog_UpdateQuestDetails` relies on.
 #[test]
 fn update_scroll_child_rect_measures_the_childs_text_before_it_reads_the_range() {
     struct Rows;
@@ -592,16 +549,9 @@ fn update_scroll_child_rect_measures_the_childs_text_before_it_reads_the_range()
     );
 }
 
-/// The horizontal axis is the vertical one's byte-clone (`0x786d30` against `0x786db0`), so this is
-/// the vertical trio's test on the other axis: the offset is stored VERBATIM and re-anchors the
-/// child, `OnHorizontalScroll` fires only on a real change, and the range is
-/// `max(0, subtreeWidth - frameWidth)`.
-///
-/// **The sign is the point.** `0x787100` hands both offsets to `SetPoint(TOPLEFT, self, TOPLEFT,
-/// +hScroll, +vScroll)` unnegated, and x grows right — so a positive horizontal pushes the child
-/// RIGHT where a positive vertical lifts it. `aux-addon/tabs/search/filter.lua:315-322` corroborates
-/// it from the caller's side (it bounds x into `[frameWidth - contentWidth - 10, 0]` and y into
-/// `[0, contentHeight - frameHeight]`), which is why it is asserted here rather than assumed.
+/// The horizontal axis clones the vertical (`0x786d30` against `0x786db0`); `0x787100` passes both
+/// offsets to `SetPoint(TOPLEFT, self, TOPLEFT, +h, +v)` unnegated, so a positive horizontal
+/// offset pushes the child right.
 #[test]
 fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
     let mut s = script();
@@ -639,7 +589,6 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "horizontal=0 -> child left = frame left"
     );
 
-    // Positive pushes the child RIGHT (the reference's unnegated xOff) …
     s.run("HSF:SetHorizontalScroll(40)").unwrap();
     s.resolve();
     assert_eq!(
@@ -647,7 +596,6 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         Some(40.0),
         "a positive horizontal offset moves the child right"
     );
-    // … and it is the NEGATIVE direction that scrolls right, which is the half aux-addon relies on.
     s.run("HSF:SetHorizontalScroll(-60)").unwrap();
     s.resolve();
     assert_eq!(
@@ -656,8 +604,7 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "a negative horizontal offset scrolls right"
     );
 
-    // No clamp — the range is 500-300 = 200 and 450 is stored and applied whole (decision 2017's
-    // law, which is `0x786d30`'s as much as `0x786db0`'s: neither reads the range).
+    // Neither `0x786d30` nor `0x786db0` reads the range, so 450 is stored whole.
     assert_eq!(
         s.eval::<f32>("return HSF:GetHorizontalScrollRange()")
             .unwrap(),
@@ -672,7 +619,6 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "stored verbatim, past the range"
     );
 
-    // Arity/kind, the way the shape gate measures them.
     assert_eq!(s.arity("HSF:GetHorizontalScroll()").unwrap(), 1);
     assert_eq!(s.arity("HSF:GetHorizontalScrollRange()").unwrap(), 1);
     assert_eq!(
@@ -691,7 +637,7 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "the setter answers nothing"
     );
 
-    // The change-gate: four setter calls moved the value (40, -60, 450, and 450 again is not one).
+    // Four setter calls, but the second 450 is no change.
     let fired: Vec<f32> = (1..=s.eval::<i64>("return table.getn(hfired)").unwrap())
         .map(|i| s.eval::<f32>(&format!("return hfired[{i}]")).unwrap())
         .collect();
@@ -701,7 +647,6 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
         "OnHorizontalScroll fires once per ACTUAL change, with the new offset"
     );
 
-    // The two axes are independent state, not one offset behind two names.
     s.run("HSF:SetVerticalScroll(25)").unwrap();
     assert_eq!(
         s.eval::<f32>("return HSF:GetHorizontalScroll()").unwrap(),
@@ -713,12 +658,8 @@ fn scroll_child_left_tracks_horizontal_scroll_unclamped_and_fires_on_change() {
     );
 }
 
-/// `UpdateScrollChildRect` notifies `OnScrollRangeChanged(self, xRange, yRange)` — **horizontal
-/// first**. Byte-derived, not guessed: the vertical result leaves `0x786e30` on top of the x87
-/// stack, is `fstp`'d first and so pushed deepest, landing as `arg2` (wow-re
-/// `scrollframe-offset-and-range-law.md` §3.6 — two of that round's own workers published it the
-/// other way round, which is why it is asserted here). `arg1` was a hardcoded `0.0` for as long as
-/// there was no horizontal range to put in it.
+/// The vertical range leaves `0x786e30` on top of the x87 stack and is `fstp`'d first, so it is
+/// pushed deepest and lands as `arg2`.
 #[test]
 fn update_scroll_child_rect_reports_both_ranges_horizontal_first() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/setparent.rs b/crates/benilla-ui/src/script/tests/setparent.rs
index 15802774..5cee982b 100644
--- a/crates/benilla-ui/src/script/tests/setparent.rs
+++ b/crates/benilla-ui/src/script/tests/setparent.rs
@@ -1,13 +1,10 @@
-//! The runtime `SetParent` law — strata/level re-assignment, the hide→show round-trip, and the
-//! binding's error surface, per wow-re `ui/scratch/setparent-runtime-strata-level.md` (decision
-//! 1323). Every test drives the production Lua binding; the arena split
-//! (`reparent_begin`/`reparent_finish`) is exercised through it.
+//! Runtime `SetParent` (`0x7a1550`): strata and level re-assignment, the hide and show round-trip,
+//! and the binding's errors.
 
 use super::common::script;
 
-/// `strata := parent.strata`, `level := parent.level + 1` (`0x76ab5a`/`0x76ab65`) — and the
-/// subtree is NOT re-based (`propagate = 0`): an existing child keeps its absolute level, landing
-/// below its own parent, exactly as shipped.
+/// `strata := parent.strata`, `level := parent.level + 1` (`0x76ab5a`/`0x76ab65`); the subtree's
+/// levels are not re-based (`propagate = 0`), so a child can land below its own parent.
 #[test]
 fn reparent_relevels_the_moved_frame_only() {
     let s = script();
@@ -44,8 +41,7 @@ fn reparent_relevels_the_moved_frame_only() {
     );
 }
 
-/// `SetParent(nil)` is a RESET — strata MEDIUM, level 0 (`0x76aba3`/`0x76abac`) — never "keep
-/// current".
+/// `SetParent(nil)` resets to strata MEDIUM, level 0 (`0x76aba3`/`0x76abac`).
 #[test]
 fn reparent_to_nil_resets_strata_and_level() {
     let s = script();
@@ -66,11 +62,8 @@ fn reparent_to_nil_resets_strata_and_level() {
     assert_eq!(s.eval::<i64>("return F:GetFrameLevel()").unwrap(), 0);
 }
 
-/// A reparent of an effectively-visible frame is a hide→show round-trip: `OnHide` fires (under the
-/// OLD parent), then `OnShow` refires down the subtree — and an `OnShow` doing
-/// `SetFrameLevel(GetParent():GetFrameLevel()+1)` lands the child back above its parent. That
-/// hand-repair is AtlasLoot's own idiom and the reason its browse panel works on the reference —
-/// the round-trip is what makes it run.
+/// A visible frame's reparent fires `OnHide` under the old parent, then `OnShow` down the subtree,
+/// where AtlasLoot's `SetFrameLevel(GetParent():GetFrameLevel()+1)` lifts a child back up.
 #[test]
 fn a_visible_reparent_refires_onhide_then_onshow() {
     let s = script();
@@ -115,10 +108,8 @@ fn a_visible_reparent_refires_onhide_then_onshow() {
     );
 }
 
-/// A reparent of a hidden frame fires neither event, and does not recompute effective visibility:
-/// the `+0xd4` cascade only runs inside the show half (`0x76abfd` gates on the captured `ebx`), so
-/// a shown-but-invisible frame moved under a visible parent STAYS effectively invisible until
-/// something shows it. Shipped behaviour, byte-verified — not an oversight.
+/// The `+0xd4` visibility cascade runs only in the show half (`0x76abfd` gates on the captured
+/// `ebx`), so a hidden frame moved under a visible parent stays invisible until shown.
 #[test]
 fn a_hidden_reparent_fires_nothing_and_leaves_visibility_stale() {
     let s = script();
@@ -145,9 +136,7 @@ fn a_hidden_reparent_fires_nothing_and_leaves_visibility_stale() {
             .unwrap(),
         "shown bit intact, effective visibility stale-false under the visible new parent"
     );
-    // An explicit Show is what recomputes it — but Show() no-ops while the bit is already set, so
-    // a real transition needs the toggle. The Hide half fires no OnHide (the frame was already
-    // effectively invisible — transition-gated); only the Show half's false→true fires.
+    // Show() no-ops while the shown bit is set, so it takes a toggle; only its Show half fires.
     s.run("STF:Hide(); STF:Show()").unwrap();
     assert!(s.eval::<bool>("return STF:IsVisible()").unwrap());
     assert_eq!(
@@ -157,9 +146,8 @@ fn a_hidden_reparent_fires_nothing_and_leaves_visibility_stale() {
     );
 }
 
-/// The binding's error surface: a cycle RAISES (`0x87cb14` — including `newParent == self`), an
-/// unresolvable name raises `Couldn't find region named`, and an ABSENT argument is the same raise
-/// — not the nil path. The same-parent call is a total no-op that fires nothing.
+/// A cycle, self included, raises (`0x87cb14`); an absent argument takes the bad-name raise, not
+/// the nil path.
 #[test]
 fn the_binding_raises_on_cycle_bad_name_and_absent_argument() {
     let s = script();
@@ -185,7 +173,7 @@ fn the_binding_raises_on_cycle_bad_name_and_absent_argument() {
     let absent = s.run("A:SetParent()").unwrap_err().to_string();
     assert!(absent.contains("Couldn't find region named"), "{absent}");
 
-    // Same parent: the total no-op — no events, no level rewrite.
+    // B's parent is already A: the same-parent call is a total no-op, firing nothing.
     s.run(
         r#"
         B:SetFrameLevel(9)
@@ -203,3 +191,54 @@ fn the_binding_raises_on_cycle_bad_name_and_absent_argument() {
         "0x76ab20 skips everything — the level is not re-derived"
     );
 }
+
+/// Under `WOW_LAYOUT_VERIFY`, on for this crate's tests, every incremental pass is checked against
+/// a full one, so the test only needs a reparent that changes the child's scale.
+#[test]
+fn a_reparent_under_a_scale_change_moves_the_childs_rect() {
+    let mut s = script();
+    s.set_screen_size(800.0, 600.0);
+    s.run(
+        r#"
+        one = CreateFrame("Frame", "ScaleOne")
+        one:SetPoint("BOTTOMLEFT", 0, 0); one:SetWidth(800); one:SetHeight(600)
+        two = CreateFrame("Frame", "ScaleTwo")
+        two:SetPoint("BOTTOMLEFT", 0, 0); two:SetWidth(800); two:SetHeight(600)
+        two:SetScale(2)
+        kid = CreateFrame("Frame", "ScaleKid", one)
+        kid:SetPoint("BOTTOMLEFT", one, "BOTTOMLEFT", 10, 20); kid:SetWidth(100); kid:SetHeight(50)
+    "#,
+    )
+    .unwrap();
+    s.resolve();
+    let at_one: (f32, f32, f32) = s
+        .eval("return ScaleKid:GetLeft(), ScaleKid:GetBottom(), ScaleKid:GetWidth()")
+        .unwrap();
+
+    // Own-space reads (`GetLeft`, `GetWidth`) stay put while the screen rect doubles.
+    s.run("kid:SetParent(two)").unwrap();
+    s.resolve();
+    let at_two: (f32, f32, f32) = s
+        .eval("return ScaleKid:GetLeft(), ScaleKid:GetBottom(), ScaleKid:GetWidth()")
+        .unwrap();
+
+    assert_eq!(at_one, (10.0, 20.0, 100.0), "seated in the unscaled parent");
+    assert_eq!(
+        at_two,
+        (10.0, 20.0, 100.0),
+        "own-space coordinates are scale-relative, so these do not move"
+    );
+    // The extraction is in screen units.
+    let widths: Vec<f32> = s
+        .extract()
+        .iter()
+        .filter_map(|q| match q.target {
+            crate::order::ZTarget::Frame(_) => q.rect.map(|r| r.right - r.left),
+            _ => None,
+        })
+        .collect();
+    assert!(
+        widths.iter().any(|w| (w - 200.0).abs() < 1e-3),
+        "the reparented child should be 100 x scale 2 = 200 screen units wide; got {widths:?}"
+    );
+}
diff --git a/crates/benilla-ui/src/script/tests/simplehtml.rs b/crates/benilla-ui/src/script/tests/simplehtml.rs
index a0061bc0..0da4387e 100644
--- a/crates/benilla-ui/src/script/tests/simplehtml.rs
+++ b/crates/benilla-ui/src/script/tests/simplehtml.rs
@@ -1,18 +1,12 @@
-//! The `SimpleHTML` widget end to end — the markup engine's *model* half.
-//!
-//! The parse itself (strict XML, the three fallback routes, the collapse, the splices) is unit
-//! tested in `script::simplehtml::parse`, against the byte law directly. What is asserted here is
-//! everything that only exists once the blocks are real regions: the anchor chain, the width
-//! snapshot, the element-font resolution and its H1→P fallback, the spacing step, the free on
-//! rebuild, and the 19-name Lua table.
+//! The `SimpleHTML` widget once its blocks are regions: the anchor chain, block widths, element
+//! fonts and their `P` fallback, spacing, the free on rebuild and the 19-name Lua table.
 
 use super::common::script;
 use crate::layout::Point;
 use crate::script::{Model, UiScript};
 use crate::widget::RegionKind;
 
-/// One block as a reader would describe it: what it says, how it is justified, what face it is in,
-/// how wide it was told to be, and where it hangs from.
+/// One block as a reader would describe it.
 #[derive(Clone, Debug, PartialEq)]
 struct Blk {
     text: Option<String>,
@@ -20,21 +14,18 @@ struct Blk {
     justify_h: &'static str,
     font: Option<String>,
     font_height: Option<f32>,
-    /// The `size` the widget wrote: `(frame width, 0)` for a text block — a zero height is how the
-    /// measure round-trip is asked for the intrinsic one.
+    /// `(frame width, 0)` for a text block: a 0 height takes the measured one.
     size: Option<(f32, f32)>,
-    /// `(own point, relative point, x, y, target)`, `None` when the block carries no anchor at all.
+    /// `(own point, relative point, x, y, target)`.
     anchor: Option<(Point, Point, f32, f32, Rel)>,
 }
 
 /// What a block's single anchor points at.
 #[derive(Clone, Copy, Debug, PartialEq)]
 enum Rel {
-    /// The SimpleHTML frame itself — only block 0 ever does this.
+    /// The SimpleHTML frame; only block 0 anchors to it.
     Frame,
-    /// A previous block, by index in the block list.
     Block(usize),
-    /// Something else entirely (never expected; a failure would print it).
     Other,
 }
 
@@ -73,8 +64,6 @@ fn blocks(s: &UiScript, name: &str) -> Vec<Blk> {
                 font_height: d.font_height,
                 size: d.size,
                 anchor,
-                // A texture block has no text; keeping the kind out of the struct and asserting it
-                // here keeps the expected-value literals readable.
             }
             .tap_kind(kind)
         })
@@ -82,9 +71,7 @@ fn blocks(s: &UiScript, name: &str) -> Vec<Blk> {
 }
 
 impl Blk {
-    /// A tiny consistency check folded into the read: a text block is a FontString, an image block
-    /// is a Texture. A regression that made blocks the wrong region kind would otherwise pass
-    /// every text assertion below.
+    /// Asserts a text block is a FontString and an image block a Texture.
     fn tap_kind(self, kind: RegionKind) -> Blk {
         match (&self.text, &self.texture) {
             (Some(_), None) => assert_eq!(kind, RegionKind::FontString),
@@ -95,7 +82,6 @@ impl Blk {
     }
 }
 
-/// Just the strings, for the tests that only care about the walk.
 fn texts(s: &UiScript, name: &str) -> Vec<String> {
     blocks(s, name)
         .into_iter()
@@ -103,8 +89,7 @@ fn texts(s: &UiScript, name: &str) -> Vec<String> {
         .collect()
 }
 
-/// How many regions the frame owns in total — the free-on-rebuild check's instrument. A block that
-/// was orphaned rather than destroyed still sits in its owner's region list and still draws.
+/// The frame's region count, which still counts a block orphaned rather than freed.
 fn region_count(s: &UiScript, name: &str) -> usize {
     let lua = s.lua();
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -112,8 +97,8 @@ fn region_count(s: &UiScript, name: &str) -> usize {
     model.arena.frame(fh).expect("live frame").regions.len()
 }
 
-/// A `SimpleHTML` named `Page`, 270×304 like the reference's `ItemTextPageText`, with one font
-/// object behind it (the `<FontString inherits="ItemTextFontNormal"/>` shape).
+/// A `SimpleHTML` named `Page`, 270×304 and in `ItemTextFontNormal` like the stock
+/// `ItemTextPageText` (`ItemTextFrame.xml:203`).
 fn page(s: &UiScript) {
     s.run(
         r#"
@@ -129,13 +114,9 @@ fn page(s: &UiScript) {
     .unwrap();
 }
 
-/// Answer every pending measure at 16px a line and 100 wide, so the resolved rects below are
-/// arithmetic a reader can check.
-///
-/// The line count is the client's own kernel `0x5c2070`, not "breaks + 1": it counts a line per
-/// class-2 token consumed and exits at the terminator, so a **trailing** break opens no new line
-/// and the one-byte `"\n"` a `<BR/>` block carries is **one** line, not two (§4.4). An empty string
-/// never enters the loop body at all and measures 0 — the empty-`<P>` edge.
+/// Answer every pending measure at 16 px a line and 100 wide, with the reference's line count
+/// (`0x5c2070`): a trailing break opens no line, so a `<BR/>` block's `"\n"` is one line, and an
+/// empty string is none.
 fn measure_at_16px(s: &mut UiScript) {
     s.resolve();
     let reqs = s.fontstrings_needing_measure();
@@ -160,12 +141,9 @@ fn client_lines(text: &str) -> usize {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The walk, as blocks on the frame
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The walk, as blocks on the frame ──
 
-/// A well-formed body: one block per tag, each carrying the tag's own `align` and — because only
-/// `<FontString>` was declared — every one of them in `P`'s face, the `<H1>` included.
+/// Each tag's block carries its `align`, and with only `P` declared every block is in `P`'s face.
 #[test]
 fn a_well_formed_body_is_one_block_per_tag() {
     let mut s = script();
@@ -192,20 +170,18 @@ fn a_well_formed_body_is_one_block_per_tag() {
             ("Right body.".to_string(), "RIGHT"),
         ]
     );
-    // §5.3 — `elementFont[1]`'s path is empty, so `0x78ae30` substitutes `elementFont[0]`. There
-    // is NO header scaling anywhere in the TU: the H1 is the same 15px as the paragraphs.
+    // `elementFont[1]` has no path, so `0x78ae30` substitutes `elementFont[0]`; nothing scales a
+    // header.
     for blk in &b {
         assert_eq!(blk.font.as_deref(), Some("Fonts\\MORPHEUS.TTF"));
         assert_eq!(blk.font_height, Some(15.0));
-        // `SetWidth(frame.GetWidth())`, and NO height — the intrinsic one comes from the measure.
         assert_eq!(blk.size, Some((270.0, 0.0)));
     }
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The anchor chain of §4.2 step 2, and the flush default of §4.3: block 0 pins TOPLEFT→frame
-/// TOPLEFT, every later block TOPLEFT→**the previous block's** BOTTOMLEFT at `−spacing` — which
-/// is `0` out of the box, so the blocks touch.
+/// Block 0 pins TOPLEFT to the frame's TOPLEFT and each later block TOPLEFT to the previous one's
+/// BOTTOMLEFT at `-spacing` (`0x767c70`); spacing starts at 0 (`0x770d89`), so the blocks touch.
 #[test]
 fn blocks_chain_bottom_to_top_and_are_flush_at_spacing_zero() {
     let mut s = script();
@@ -224,15 +200,13 @@ fn blocks_chain_bottom_to_top_and_are_flush_at_spacing_zero() {
         ]
     );
 
-    // …and the resolved rects really do stack with no gap. Frame top is 600 (screen top, TOPLEFT
-    // at 0,0); three 16px lines run 600→584→568→552.
+    // The frame top is the screen top, 600; three 16 px lines run down to 552.
     measure_at_16px(&mut s);
     let tops = resolved_tops(&s, "Page");
     assert_eq!(tops, [(600.0, 584.0), (584.0, 568.0), (568.0, 552.0)]);
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `SetSpacing` is the only thing that opens a gap, and it opens it by exactly its own value.
 #[test]
 fn spacing_steps_the_blocks_apart() {
     let mut s = script();
@@ -264,8 +238,7 @@ fn spacing_steps_the_blocks_apart() {
     );
 }
 
-/// `<BR/>` at BODY level is its own `"\n"` block, and `0x5c2070` counts **one** line for it — one
-/// blank line, not two and not a paragraph gap.
+/// A BODY-level `<BR/>` is its own `"\n"` block, which `0x5c2070` counts as one line.
 #[test]
 fn a_body_level_br_is_exactly_one_blank_line() {
     let mut s = script();
@@ -282,8 +255,7 @@ fn a_body_level_br_is_exactly_one_blank_line() {
     );
 }
 
-/// Inline `<BR/>` is a different animal: it splices the two bytes `|n` into the SAME block, which
-/// the font engine turns into a line break within it.
+/// An inline `<BR/>` splices `|n` into the enclosing block, a line break within it.
 #[test]
 fn an_inline_br_stays_inside_its_block() {
     let s = script();
@@ -293,8 +265,8 @@ fn an_inline_br_stays_inside_its_block() {
     assert_eq!(texts(&s, "Page"), ["a|nb"]);
 }
 
-/// All three fallback routes land on ONE block holding the RAW string — no collapse, so embedded
-/// newlines survive as real line breaks. This is the common case for a vmangos `page_text`.
+/// Each fallback route is one block holding the raw, uncollapsed string; most vmangos `page_text`
+/// rows are plain text and take it.
 #[test]
 fn the_three_fallback_routes_each_land_on_one_raw_block() {
     let s = script();
@@ -317,7 +289,6 @@ fn the_three_fallback_routes_each_land_on_one_raw_block() {
     }
 }
 
-/// Malformed markup **falls back**; it never raises and never renders half a document.
 #[test]
 fn malformed_markup_falls_back_rather_than_erroring() {
     let s = script();
@@ -333,8 +304,7 @@ fn malformed_markup_falls_back_rather_than_erroring() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A second `SetText` destroys the first parse's blocks.** Not hides, not orphans — the regions
-/// are gone from the frame, so nothing of the old page can draw behind the new one.
+/// A second `SetText` frees the first parse's regions, so nothing of the old page draws.
 #[test]
 fn a_second_set_text_replaces_the_blocks() {
     let mut s = script();
@@ -363,9 +333,8 @@ fn a_second_set_text_replaces_the_blocks() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The real `page_text` shape §8 quotes, driven through the widget: the `<H1>` at the `<P>` size,
-/// every block centred, each `<BR/>` one blank line, and the body's own inter-tag newlines adding
-/// nothing at all.
+/// A real `page_text` body: the `<H1>` at the `<P>` size, each `<BR/>` one blank line, and the
+/// newlines between tags adding nothing.
 #[test]
 fn the_page_text_body_renders_the_block_list_a_reader_would_draw() {
     let mut s = script();
@@ -406,7 +375,7 @@ fn the_page_text_body_renders_the_block_list_a_reader_would_draw() {
         ],
         "the H1 renders at the P size — nothing in the TU scales a header"
     );
-    // Five blocks flush at 16px each: 600 → 520.
+    // Five flush 16 px blocks: 600 down to 520.
     measure_at_16px(&mut s);
     let tops = resolved_tops(&s, "Page");
     assert_eq!(tops.first(), Some(&(600.0, 584.0)));
@@ -414,14 +383,9 @@ fn the_page_text_body_renders_the_block_list_a_reader_would_draw() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The exact string the reader builds**, on the exact body B240 reports — `ItemTextFrame.xml`'s
-/// READY handler pads an authorless page as `"\n" .. ItemTextGetText() .. "\n"`, and that padding
-/// is the one thing standing between a formatted page and the raw markup Goudy photographed.
-/// Whitespace before and after the root element is legal XML, so this must take the MARKUP path;
-/// if it ever takes the fallback, every book in the world silently renders as its own source.
-///
-/// The body is vmangos `page_text` 2676 verbatim — the *Alliance Military Ranks* plaque in
-/// Stormwind's Old Town, `GameObject` 3011, the object in the report's screenshots.
+/// `ItemTextFrame.lua:44` pads an authorless page as `"\n" .. ItemTextGetText() .. "\n"`, and
+/// whitespace around the root element is legal XML, so it still takes the markup path. The body is
+/// vmangos `page_text` 2676, the Alliance Military Ranks plaque (`GameObject` 3011).
 #[test]
 fn the_readers_own_newline_padding_still_parses_as_markup() {
     let mut s = script();
@@ -460,7 +424,7 @@ fn the_readers_own_newline_padding_still_parses_as_markup() {
         "the padded page took the markup path — one block per tag, one blank line per <BR/>, and \
          BODY's own inter-tag newlines adding nothing"
     );
-    // The falsification, stated: the fallback would put the WHOLE source in one block.
+    // The fallback would put the whole source in one block.
     assert!(
         !texts[0].contains('<'),
         "a fallback would render the markup itself — the reported symptom"
@@ -468,10 +432,8 @@ fn the_readers_own_newline_padding_still_parses_as_markup() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The other half of the same guard: `page_text` **1510** (the Crystal Pylon manual) ends
-/// `</HTML.` — a typo in Blizzard's own shipped data. Strict XML rejects it, so it falls back to
-/// raw markup **on the reference client too**, and ours must do the same rather than paper over
-/// it. This is the one of the world's 62 HTML bodies that is not well-formed.
+/// `page_text` 1510, the Crystal Pylon manual, ends `</HTML.`, so strict XML rejects it and the
+/// reference shows the raw markup too; it is the only malformed one of the 62 HTML bodies.
 #[test]
 fn blizzards_own_malformed_page_falls_back_exactly_as_the_reference_does() {
     let s = script();
@@ -490,8 +452,6 @@ fn blizzards_own_malformed_page_falls_back_exactly_as_the_reference_does() {
     );
 }
 
-/// A declared header font **is** honoured — the fallback fires only on an element with no font
-/// from any source, so this is the control for the test above.
 #[test]
 fn a_declared_header_font_wins_over_the_p_fallback() {
     let s = script();
@@ -516,8 +476,7 @@ fn a_declared_header_font_wins_over_the_p_fallback() {
     );
 }
 
-/// An `<IMG>` sizes itself, anchors by `align`, and — when it is NOT floated — reserves its own
-/// height in the flow while leaving `prevBlock` pointing at the last **text** block.
+/// An unfloated `<IMG>` reserves its height in the flow, but `prevBlock` stays the last text block.
 #[test]
 fn an_unfloated_image_reserves_height_without_becoming_the_anchor() {
     let s = script();
@@ -542,20 +501,9 @@ fn an_unfloated_image_reserves_height_without_becoming_the_anchor() {
     );
 }
 
-/// **B342, at the engine.** Goudy, 2026-08-27 (`#bugs` `1542371921486811236`): *"html images in
-/// books are not scaled correctly"* — the Alliance crest on *A Treatise on Military Ranks* drawn
-/// several times the reference's size, with the page's text over the top of it.
-///
-/// The body is `page_text` 2654 and its `<IMG>` carries **no `width=` and no `height=`**, so the
-/// block is sized `0 × 0`. In the reference that is not "no size": the resolver's size call is
-/// VIRTUAL, and `CSimpleTexture::GetWidth 0x770720` / `GetHeight 0x770790` answer an authored `0.0`
-/// with the loaded texture's own texel extent, through bit-for-bit the converter `<AbsDimension>`
-/// uses — **one texel is one FrameXML unit** (wow-re `region-size-fallback.md` §2, decision 1349).
-/// `PvPRankAlliance.blp` is 128×128, so the crest is a 128-unit square.
-///
-/// The falsification is the reported shape itself, asserted below: a zero span leaves the opposite
-/// edge unresolved (`combine_edge`'s `span != 0.0` leg), and the region sweep's owner-edge fallback
-/// then hands the image the rest of the **270-wide** page.
+/// The `<IMG>` in `page_text` 2654 has no `width=` or `height=`, and the reference's
+/// `CSimpleTexture::GetWidth 0x770720`/`GetHeight 0x770790` answer an authored 0 with the art's
+/// texel size, a texel to a FrameXML unit: the 128×128 crest is a 128-unit square.
 #[test]
 fn the_books_unsized_crest_is_its_arts_texel_square_not_the_whole_page() {
     const CREST: &str = "Interface\\PvPRankBadges\\PvPRankAlliance";
@@ -597,18 +545,15 @@ fn the_books_unsized_crest_is_its_arts_texel_square_not_the_whole_page() {
         (128.0, 128.0),
         "a texel is a FrameXML unit: the 128x128 crest is a 128-unit square, not the page"
     );
-    // The reported symptom, stated as the thing that must not come back: the page is 270 wide and
-    // 304 tall, and the crest used to take all of the first and everything left of the second.
+    // The page is 270 wide; the crest must not span it.
     assert!(
         rect.right - rect.left < 270.0,
         "the crest is stretched across the page width again"
     );
 }
 
-/// The flow half of the same law (`simplehtml-markup-engine.md` §7 step 6): an **unfloated** image
-/// reserves `texture.GetHeight()` — `CSimpleTexture`'s override — so one with no `height=` reserves
-/// its art's texel height, and the next text block hangs that far lower. A floated one (the book's
-/// `align="left"`) still reserves nothing, which is why its text overlaps it in both clients.
+/// An unfloated image reserves `GetHeight()` in the flow (`0x78ad07`), its art's texel height when
+/// it has no `height=`; a floated one reserves nothing, so text runs over it in the reference too.
 #[test]
 fn an_unsized_image_reserves_its_arts_texel_height_unless_it_is_floated() {
     let mut s = script();
@@ -642,12 +587,8 @@ fn an_unsized_image_reserves_its_arts_texel_height_unless_it_is_floated() {
     );
 }
 
-/// A VM with no host oracle has no art to measure, so a zero-size image has **no span on either
-/// axis** — and with one corner pinned and nothing to add to it, it does not resolve at all. That
-/// is the reference's own answer for a texture with no `CGxTex*`: `combineEdge`'s legs both fail
-/// their `span != 0.0` test, `assemble 0x767a20` returns 0, and the texture emits a degenerate
-/// all-zero quad (wow-re `region-size-fallback.md` §5's counterfactual and §7). Stated so the
-/// engine-less path cannot quietly go back to borrowing the page's width.
+/// With no size oracle a zero-size image has no span and does not resolve, as in the reference for
+/// a texture with no `CGxTex*`: `assemble 0x767a20` returns 0 and the quad is all zeros.
 #[test]
 fn without_a_size_oracle_an_unsized_image_does_not_resolve() {
     let mut s = script();
@@ -667,12 +608,9 @@ fn without_a_size_oracle_an_unsized_image_does_not_resolve() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The Lua table
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The Lua table ──
 
-/// The 19 names of `.data 0x87ba80`, and only those 19 — `GetText` is **not** one of them in
-/// build 5875, and a name a table does not carry is as wrong as a missing one.
+/// The 19 names of `.data 0x87ba80`, and only those: there is no `GetText`.
 #[test]
 fn the_method_table_is_the_nineteen_names() {
     let s = script();
@@ -707,16 +645,15 @@ fn the_method_table_is_the_nineteen_names() {
         !s.eval::<bool>("return H.GetText ~= nil").unwrap(),
         "1.12.1's SimpleHTML table has no GetText"
     );
-    // The names are the SimpleHTML's own — no other widget kind answers them.
+    // The names are the SimpleHTML's own: a Frame does not answer them.
     s.run(r#"F = CreateFrame("Frame")"#).unwrap();
     assert!(!s
         .eval::<bool>("return F.SetHyperlinkFormat ~= nil")
         .unwrap());
 }
 
-/// The optional element-name argument (`0x795d80`): omitting it addresses `P`, the four names are
-/// case-insensitive, and a **string that is not one of the four is not removed** — it becomes the
-/// shared implementation's first real argument.
+/// The optional element name (`0x795d80`): absent means `P`, the four names match in any case, and
+/// any other string stays as the first real argument.
 #[test]
 fn the_element_name_argument_is_optional_case_insensitive_and_non_matching_falls_through() {
     let s = script();
@@ -738,8 +675,7 @@ fn the_element_name_argument_is_optional_case_insensitive_and_non_matching_falls
             .unwrap(),
         ("Fonts\\B.TTF".to_string(), 20.0)
     );
-    // "h4" is not an element: it stays on the stack and is consumed as SetFont's PATH, so this
-    // targets P and sets the face to the literal "h4".
+    // "h4" is no element, so it is `SetFont`'s path and the call targets `P`.
     s.run(r#"H:SetFont("h4", 12)"#).unwrap();
     assert_eq!(
         s.eval::<(String, f32)>("local p, h = H:GetFont(); return p, h")
@@ -748,7 +684,6 @@ fn the_element_name_argument_is_optional_case_insensitive_and_non_matching_falls
     );
 }
 
-/// `SetHyperlinkFormat` governs how an `<A>` is spliced, and takes effect on the next parse.
 #[test]
 fn the_hyperlink_format_shapes_the_a_splice() {
     let s = script();
@@ -768,12 +703,10 @@ fn the_hyperlink_format_shapes_the_a_splice() {
         .unwrap();
     assert_eq!(texts(&s, "Page"), ["see |cff33ff99|Hitem:1|h[this]|h|r"]);
 
-    // A non-string argument raises the reference's own usage string rather than no-opping.
+    // A non-string argument raises the reference's usage string.
     assert!(s.run("Page:SetHyperlinkFormat(7)").is_err());
 }
 
-/// The colour/shadow/justify getters answer per element, and `SetTextColor` reaches the blocks the
-/// next parse builds.
 #[test]
 fn the_paint_setters_land_on_the_element_and_reach_the_next_parse() {
     let s = script();
@@ -792,7 +725,7 @@ fn the_paint_setters_land_on_the_element_and_reach_the_next_parse() {
             .unwrap(),
         (1.0, 0.0, 0.0, 1.0)
     );
-    // P keeps the font object's own colour — the element arg really did scope the write.
+    // `P` keeps the font object's colour: the element argument scoped the write.
     let (r, g, b, _) = s
         .eval::<(f32, f32, f32, f32)>("return Page:GetTextColor(\"P\")")
         .unwrap();
@@ -809,13 +742,9 @@ fn the_paint_setters_land_on_the_element_and_reach_the_next_parse() {
     );
 }
 
-/// **The empty-path fallback substitutes the WHOLE element font, colour included** — so an `H1`
-/// given a colour and nothing else renders in `P`'s colour, and its own red is never drawn.
-///
-/// That is the shape of `0x78ae29`–`0x78ae54`: the register holding `elementFont[elem]` is
-/// *replaced* by `elementFont[0]` before the single `SetFontObject` call, so the test is on the
-/// path and the consequence is on everything. Surprising, faithful, and exactly the sort of thing
-/// a re-implementation gets wrong by merging property-by-property instead.
+/// An element with no font path takes `elementFont[0]` whole, colour included: `0x78ae29` to
+/// `0x78ae54` swap the register before the one `SetFontObject`, so an `H1` given only a colour
+/// draws in `P`'s.
 #[test]
 fn an_element_with_no_font_of_its_own_loses_its_own_colour_too() {
     let s = script();
@@ -827,8 +756,8 @@ fn an_element_with_no_font_of_its_own_loses_its_own_colour_too() {
     "#,
     )
     .unwrap();
-    // The getter still answers the red — the element font really does hold it (`0x795d3e` reads
-    // `[this + idx*4 + 0x350]`, never a block).
+    // The getter still answers red: it reads the element font, never a block (`0x795d3e` reads
+    // `[this + idx*4 + 0x350]`).
     assert_eq!(
         s.eval::<(f32, f32, f32, f32)>("return Page:GetTextColor(\"H1\")")
             .unwrap(),
@@ -840,7 +769,7 @@ fn an_element_with_no_font_of_its_own_loses_its_own_colour_too() {
         "the block took elementFont[0] wholesale, so H1's red never reaches it"
     );
 
-    // Give H1 a path of its own and the fallback stops firing — now the red draws.
+    // With a path of its own, `H1` draws its red.
     s.run(
         r#"
         Page:SetFont("H1", "Fonts\\SKURRI.TTF", 24)
@@ -851,8 +780,7 @@ fn an_element_with_no_font_of_its_own_loses_its_own_colour_too() {
     assert_eq!(block_color(&s, "Page", 0), Some([1.0, 0.0, 0.0, 1.0]));
 }
 
-/// The `vertex_color` of block `i` — a FontString has no texel, so its vertex colour IS the colour
-/// it draws.
+/// Block `i`'s `vertex_color`, which for a FontString is the colour it draws.
 fn block_color(s: &UiScript, name: &str, i: usize) -> Option<[f32; 4]> {
     let lua = s.lua();
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -861,14 +789,9 @@ fn block_color(s: &UiScript, name: &str, i: usize) -> Option<[f32; 4]> {
     model.region_data.get(&st.blocks[i])?.vertex_color
 }
 
-/// The two halves of `SetFontObject`'s severance law, which the element font has to reproduce by
-/// hand because it resolves its object lazily rather than copying the paint at the call:
-///
-/// - a **re-point does not reset** the explicit mask (§5-verified for the region side: the
-///   inheritMask bit a local setter clears is never restored), so a face set on the element
-///   survives being pointed at a different object;
-/// - the **nil form severs the link and leaves the paint standing** — it does not blank the
-///   element.
+/// `SetFontObject` on an element font: a re-point keeps what a local setter set (the inheritMask
+/// bit at `CSimpleFont+0x2c`/`CSimpleFontString+0xD4` is never restored), and nil unlinks the
+/// object but leaves the paint.
 #[test]
 fn set_font_object_keeps_local_overrides_and_the_nil_form_leaves_the_paint_standing() {
     let s = script();
@@ -905,8 +828,8 @@ fn set_font_object_keeps_local_overrides_and_the_nil_form_leaves_the_paint_stand
     );
 }
 
-/// `SetJustifyH` is **inert for rendered text** — the byte law, not a gap: `0x78adb0` overwrites
-/// every block's justifyH with the tag's `align`. The getter still answers what was stored.
+/// `0x78adb0` gives every block its tag's `align`, so `SetJustifyH` is stored and answered but
+/// never drawn.
 #[test]
 fn set_justify_h_is_stored_and_answered_but_never_drawn() {
     let s = script();
@@ -927,13 +850,11 @@ fn set_justify_h_is_stored_and_answered_but_never_drawn() {
         "LEFT",
         "the tag's absent align (LEFT) wins over the element font's justify"
     );
-    // A non-token raises, exactly as `0x87c77c`'s usage arm does.
+    // A non-token raises the usage string (`0x87c77c`).
     assert!(s.run(r#"Page:SetJustifyH("sideways")"#).is_err());
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Helpers that need the resolve
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Helpers that need the resolve ──
 
 /// Every block's resolved `(top, bottom)`, in block order.
 fn resolved_tops(s: &UiScript, name: &str) -> Vec<(f32, f32)> {
@@ -950,7 +871,6 @@ fn resolved_tops(s: &UiScript, name: &str) -> Vec<(f32, f32)> {
         .collect()
 }
 
-/// One block's resolved rect if it HAS one — the shape a region with no span reaches.
 fn maybe_resolved_rect(s: &UiScript, name: &str, block: usize) -> Option<crate::layout::Rect> {
     let lua = s.lua();
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -959,7 +879,6 @@ fn maybe_resolved_rect(s: &UiScript, name: &str, block: usize) -> Option<crate::
     model.region_resolved.get(&st.blocks[block]).copied()
 }
 
-/// One block's resolved rect, by index in the block list.
 fn resolved_rect(s: &UiScript, name: &str, block: usize) -> crate::layout::Rect {
     let lua = s.lua();
     let model = lua.app_data_ref::<Model>().expect("model");
@@ -971,7 +890,7 @@ fn resolved_rect(s: &UiScript, name: &str, block: usize) -> crate::layout::Rect
         .expect("block rect")
 }
 
-/// The text of every quad the extract emits for the page — what is actually on screen.
+/// The text of every quad the extract emits: what is on screen.
 fn page_texts_on_screen(s: &UiScript) -> Vec<String> {
     s.extract()
         .into_iter()
@@ -982,8 +901,7 @@ fn page_texts_on_screen(s: &UiScript) -> Vec<String> {
         .collect()
 }
 
-/// A Rust string as a Lua long-bracket literal — the bodies here are full of quotes and
-/// backslashes, and escaping them twice is how a test asserts on the wrong string.
+/// A Rust string as a Lua long-bracket literal, so quotes and backslashes need no second escape.
 fn lua_str(s: &str) -> String {
     format!("[==[{s}]==]")
 }
diff --git a/crates/benilla-ui/src/script/tests/size_changed.rs b/crates/benilla-ui/src/script/tests/size_changed.rs
index 8ddb5af0..cd950a35 100644
--- a/crates/benilla-ui/src/script/tests/size_changed.rs
+++ b/crates/benilla-ui/src/script/tests/size_changed.rs
@@ -1,16 +1,11 @@
-//! `OnSizeChanged` — the base-map layout script (`0x76a0d0` `+0x120`), fired from the resolve pass.
-//!
-//! Two things are being pinned here, and they are different in kind. The **gate** is byte-verified:
-//! `ApplyRect 0x76b580` fires iff `|Δwidth| ≥ ε ∨ |Δheight| ≥ ε` with `ε = _DAT_008029d4`
-//! ([`crate::layout::SIZE_EPS`]), which is why a frame that merely MOVES fires nothing. The
-//! **seam** is ours: the client applies rects one at a time and fires per application, benilla
-//! solves the whole graph to a fixpoint, so we fire on the entry-vs-convergence diff — one fire per
-//! resolve per frame whose size actually moved, never one per solver round.
+//! `OnSizeChanged`, the base-map layout script (`0x76a0d0` `+0x120`). `ApplyRect 0x76b580` fires
+//! it only when width or height moves by `ε = _DAT_008029d4` ([`crate::layout::SIZE_EPS`]).
+//! Deviation: the client fires per rect application; we fire once per resolve on the size before
+//! and after, because our solver settles the whole graph to a fixpoint.
 
 use super::common::script;
 
-/// The size moves ⇒ `OnSizeChanged(self, width, height)` fires with the NEW size; a pure move fires
-/// nothing (the byte-verified gate is on width/height, not on the rect).
+/// `OnSizeChanged(self, width, height)` carries the new size.
 #[test]
 fn a_resize_fires_on_size_changed_and_a_move_does_not() {
     let mut s = script();
@@ -28,18 +23,15 @@ fn a_resize_fires_on_size_changed_and_a_move_does_not() {
     )
     .unwrap();
 
-    // The FIRST layout is a change too: the client's cached rect starts zeroed, so its first
-    // ApplyRect is 0×0 → 200×50 and does fire.
+    // The client's cached rect starts zeroed, so the first layout fires too.
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 1);
     assert_eq!(s.eval::<f64>("return w").unwrap(), 200.0);
     assert_eq!(s.eval::<f64>("return h").unwrap(), 50.0);
 
-    // A second resolve with nothing touched fires nothing — the size did not move.
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 1);
 
-    // A MOVE is not a resize.
     s.run(r#"Panel:SetPoint("BOTTOMLEFT", 400, 300)"#).unwrap();
     s.resolve();
     assert_eq!(
@@ -48,7 +40,6 @@ fn a_resize_fires_on_size_changed_and_a_move_does_not() {
         "the rect moved but width/height did not — ApplyRect's gate is on the size alone"
     );
 
-    // A real resize does.
     s.run("Panel:SetHeight(120)").unwrap();
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 2);
@@ -57,10 +48,7 @@ fn a_resize_fires_on_size_changed_and_a_move_does_not() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// It fires for a size the frame did not set on itself — the case the corpus actually uses it for
-/// (`MoveAnything`, `CleanMinimap`, `FuBar`, `Outfitter`, `AckisRecipeList` all watch a frame whose
-/// size is decided by something else). Here the child is anchored to two edges of a parent that
-/// resizes, so its own `LayoutInput` never changes at all and only the SOLVE knows it moved.
+/// Addons watch frames sized by their anchors; only the solve knows this child moved.
 #[test]
 fn an_anchor_driven_resize_fires_it_too() {
     let mut s = script();
@@ -93,11 +81,8 @@ fn an_anchor_driven_resize_fires_it_too() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The loop guard.** A handler that resizes its own frame is the classic `OnSizeChanged` hazard,
-/// and it must not spin the engine. The drain takes ONE batch per resolve
-/// ([`crate::script::event::fire_size_changes`]), so a handler that settles on a constant size
-/// settles — one extra fire for the size it forced, then silence — and one that never settles costs
-/// one fire per resolve rather than hanging inside a single call.
+/// The drain takes one batch per resolve ([`crate::script::event::fire_size_changes`]), so a
+/// handler that resizes its own frame costs one fire per resolve instead of hanging.
 #[test]
 fn a_handler_that_resizes_its_own_frame_settles_instead_of_spinning() {
     let mut s = script();
@@ -117,14 +102,12 @@ fn a_handler_that_resizes_its_own_frame_settles_instead_of_spinning() {
     )
     .unwrap();
 
-    // Resolve returns (does not hang) even though the handler dirties the layout from inside it.
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 1);
-    // The next resolve sees the handler's own 200×200 and fires once for it…
+    // The next resolve fires once for the handler's own 200×200.
     s.resolve();
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 2);
     assert_eq!(s.eval::<f64>("return Sq:GetHeight()").unwrap(), 200.0);
-    // …and then it is stable: no further fires, however many passes run.
     for _ in 0..5 {
         s.resolve();
     }
@@ -136,9 +119,6 @@ fn a_handler_that_resizes_its_own_frame_settles_instead_of_spinning() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The regression guard that makes the `SCRIPT_KINDS` row real: `SetScript("OnSizeChanged", …)`
-/// stopped raising, and what replaced the error is a handler that actually runs — not a stored
-/// closure nobody ever calls.
 #[test]
 fn set_script_on_size_changed_is_accepted_because_the_resolve_pass_fires_it() {
     let mut s = script();
@@ -160,15 +140,8 @@ fn set_script_on_size_changed_is_accepted_because_the_resolve_pass_fires_it() {
     assert!(s.eval::<bool>("return ran").unwrap(), "…and it FIRED");
 }
 
-/// **The watch list is exactly the frames carrying the script.** The resolve's "before" snapshot
-/// reads `SetScript`'s maintained `on_size_changed_frames` rather than filtering the whole scripts
-/// map (decision 1634), so the list itself is now load-bearing: `SetScript(…, nil)` must remove
-/// the frame, and re-registering must not enrol it twice.
-///
-/// Asserted on the LIST, not on the fire count, and that is the point. A stale entry fires nothing
-/// — `fire` looks the handler up in Lua and finds nil — so behaviour hides the bug completely and
-/// the only symptom is the snapshot silently growing forever, one dead frame at a time. (Written
-/// as a fire-count test first; it passed with the `retain` deleted.)
+/// The resolve snapshots `on_size_changed_frames`, which `SetScript` maintains. Asserted on the
+/// list itself: a stale entry fires nothing, so only the list would show it.
 #[test]
 fn the_on_size_changed_watch_list_is_exactly_the_frames_carrying_the_script() {
     use crate::script::model::Model;
diff --git a/crates/benilla-ui/src/script/tests/slider.rs b/crates/benilla-ui/src/script/tests/slider.rs
index d3868348..dc66bc6d 100644
--- a/crates/benilla-ui/src/script/tests/slider.rs
+++ b/crates/benilla-ui/src/script/tests/slider.rs
@@ -1,12 +1,10 @@
-//! Slider (per-kind behavior; RF-28-grounded, decision 0250). The value/step/orientation contract,
-//! the VERTICAL ctor default, the no-swap divergence from StatusBar, and the change-gate that keeps
-//! the real scrollbar wiring from recursing.
+//! Slider (LoadXML `0x789580`): value, step and orientation, the vertical default, the unswapped
+//! min/max, the value quantiser, and the change gate that keeps scrollbar wiring from recursing.
 
 use super::common::script;
 use crate::script::QuadContent;
 
-/// Find the thumb quad (the texture whose path carries `needle`) and return its
-/// `(left, right, bottom, top)` rect. Panics if absent — the render must emit it.
+/// The `(left, right, bottom, top)` rect of the thumb quad whose texture path contains `needle`.
 fn thumb_rect(quads: &[crate::script::ExtractedQuad], needle: &str) -> (f32, f32, f32, f32) {
     let q = quads
         .iter()
@@ -37,15 +35,14 @@ fn slider_thumb_draws_at_value_fraction_along_the_track() {
     )
     .unwrap();
     s.resolve();
-    // value=min: the thumb sits flush at the track TOP (a scrollbar at 0 is scrolled to the top).
-    // travel = 100 - 16 = 84; thumb centered on cx=108 -> [100,116], top edge at track.top=200.
+    // value=min puts the thumb flush at the track top (a scrollbar at 0 is scrolled up); travel
+    // 100 - 16 = 84, thumb centered on x=108 -> [100,116], top edge at 200.
     assert_eq!(
         thumb_rect(&s.extract(), "Knob"),
         (100.0, 116.0, 184.0, 200.0),
         "value=min: thumb flush at track top, centered on the cross-axis"
     );
 
-    // value=max: the thumb sits flush at the track BOTTOM.
     s.run(r#"SlRender:SetValue(100)"#).unwrap();
     assert_eq!(
         thumb_rect(&s.extract(), "Knob"),
@@ -53,7 +50,6 @@ fn slider_thumb_draws_at_value_fraction_along_the_track() {
         "value=max: thumb flush at track bottom"
     );
 
-    // Halfway: thumb centered in the track (midpoint 150).
     s.run(r#"SlRender:SetValue(50)"#).unwrap();
     let (_, _, bottom, top) = thumb_rect(&s.extract(), "Knob");
     assert_eq!(
@@ -65,8 +61,7 @@ fn slider_thumb_draws_at_value_fraction_along_the_track() {
 
 #[test]
 fn slider_thumb_drag_maps_cursor_to_value() {
-    // The same vertical scrollbar as the render test: track y in [100, 200], 16x16 thumb. At value=0
-    // the thumb spans y[184,200] (its top edge at the track top), centered on x=108.
+    // The render test's scrollbar: track y in [100, 200]; at value 0 the thumb spans y[184,200].
     let mut s = script();
     s.set_screen_size(1024.0, 768.0);
     s.run(
@@ -83,8 +78,7 @@ fn slider_thumb_drag_maps_cursor_to_value() {
     .unwrap();
     s.resolve();
 
-    // Grab the thumb at its center (108, 192) and drag down the track. travel = 84; the grab keeps
-    // the same thumb point under the cursor, so the value tracks the cursor absolutely.
+    // Grab the thumb's center (108, 192); the grab keeps that thumb point under the cursor.
     s.mouse_button(108.0, 192.0, "LeftButton", true);
     s.mouse_move(108.0, 150.0);
     let v: f32 = s.eval("return SlDrag:GetValue()").unwrap();
@@ -96,7 +90,6 @@ fn slider_thumb_drag_maps_cursor_to_value() {
         "cursor at the track bottom -> value 100 (clamped)"
     );
 
-    // Release ends the capture: a later move must not move the value.
     s.mouse_button(108.0, 108.0, "LeftButton", false);
     s.mouse_move(108.0, 192.0);
     let v: f32 = s.eval("return SlDrag:GetValue()").unwrap();
@@ -123,10 +116,8 @@ fn slider_track_press_seats_the_thumb_and_a_mouseless_slider_ignores_it() {
     .unwrap();
     s.resolve();
 
-    // A press on the TRACK below the thumb (108, 120) — inside the slider, not on the thumb
-    // [184,200] — SEATS the thumb's center under the cursor and fires OnValueChanged from the
-    // press itself (0989's track-press law; 0250 §5 covered only the thumb grab). Track
-    // y in [100, 200], travel 84: cursor 120 → thumb top 128 → fraction (200−128)/84 = 72/84.
+    // A press on the track below the thumb seats the thumb's center under the cursor and fires
+    // OnValueChanged from the press: cursor 120 → thumb top 128 → fraction (200−128)/84 = 72/84.
     s.mouse_button(108.0, 120.0, "LeftButton", true);
     let v: f32 = s.eval("return SlTrack:GetValue()").unwrap();
     assert!(
@@ -136,17 +127,13 @@ fn slider_track_press_seats_the_thumb_and_a_mouseless_slider_ignores_it() {
     let n: usize = s.eval("return table.getn(fired)").unwrap();
     assert_eq!(n, 1, "the jump fired OnValueChanged once, from the press");
 
-    // The SAME press keeps dragging — the capture began at the track press.
     s.mouse_move(108.0, 108.0);
     let v: f32 = s.eval("return SlTrack:GetValue()").unwrap();
     assert_eq!(v, 100.0, "the gesture drags on without re-grabbing");
     s.mouse_button(108.0, 108.0, "LeftButton", false);
 
-    // A slider the mouse cannot reach ignores a press anywhere — thumb and track alike. This was
-    // `SlTrack:Disable()` until the Button-only `Enable`/`Disable`/`IsEnabled` trio came off the
-    // Slider table (1.12 registers them on `0x879d00` alone, and the Slider's LoadXML has no
-    // `enabled` attribute either). `EnableMouse(false)` is how the reference keeps a slider off a
-    // press, and it gates upstream in the hit test rather than inside `begin_drag`.
+    // A mouse-disabled slider ignores a press on thumb and track alike. A 1.12 Slider has no
+    // `Disable`: the trio is registered on the Button table (`0x879d00`) alone.
     s.run(r#"SlTrack:SetValue(0); SlTrack:EnableMouse(false); fired = {}"#)
         .unwrap();
     for y in [192.0, 150.0] {
@@ -184,8 +171,8 @@ fn slider_methods_exist_only_on_sliders() {
 
 #[test]
 fn slider_default_orientation_is_vertical() {
-    // The load-bearing fact of decision 0250: every scrollbar omits `orientation` and is vertical,
-    // so the CSimpleSlider ctor default is VERTICAL — the opposite of StatusBar's HORIZONTAL.
+    // Every scrollbar omits `orientation` and is vertical, so the CSimpleSlider default is
+    // `VERTICAL`, where StatusBar's is `HORIZONTAL`.
     let s = script();
     s.run(
         r#"
@@ -211,7 +198,7 @@ fn slider_value_clamps_and_does_not_swap_minmax() {
         assert(sl:GetValue() == 100, "clamped to max")
         sl:SetValue(-5)
         assert(sl:GetValue() == 0, "clamped to min")
-        -- Unlike StatusBar, a reversed pair is NOT swapped (Slider LoadXML stores min + range, RF-28).
+        -- Unlike StatusBar, a reversed pair is NOT swapped (LoadXML `0x789580` stores min + range).
         sl:SetMinMaxValues(80, 20)
         local mn, mx = sl:GetMinMaxValues()
         assert(mn == 80 and mx == 20, "reversed pair kept as given, not swapped")
@@ -230,7 +217,7 @@ fn slider_setvalue_fires_onvaluechanged_only_on_change() {
         seen = {}
         sl:SetScript("OnValueChanged", function(self, value)
             table.insert(seen, value)
-            assert(self == sl and arg1 == value, "RF-0025 conventions carry the value")
+            assert(self == sl and arg1 == value, "handler-firing conventions carry the value")
         end)
         sl:SetValue(4)
         sl:SetValue(4)          -- no change, no fire
@@ -242,11 +229,8 @@ fn slider_setvalue_fires_onvaluechanged_only_on_change() {
     .unwrap();
 }
 
-/// `Enable`/`Disable`/`IsEnabled` are a **Button** trio in 1.12 (table `0x879d00`), and a Slider
-/// must not answer them: a duck-typing addon that branches on `if widget.IsEnabled then` reads a
-/// superset as the wrong class (1189/1250 §5). This asserts the removal *and* its control — the
-/// same three names still present on a Button, so a regression that emptied the Button table would
-/// fail here rather than pass by accident.
+/// `Enable`/`Disable`/`IsEnabled` are Button methods in 1.12 (table `0x879d00`), so a Slider must
+/// not answer them: addons duck-type on `if widget.IsEnabled then`. A Button is the control.
 #[test]
 fn a_slider_does_not_answer_the_buttons_enable_trio() {
     let s = script();
@@ -262,7 +246,7 @@ fn a_slider_does_not_answer_the_buttons_enable_trio() {
         end
         -- The Button's own predicate is the NUMBER 1 / the NUMBER 0, never a Lua boolean — its
         -- false leg is 0 rather than nil, settled per body at `0x7800b0`'s `setne`+`fild`
-        -- (wow-re `button-enabled-state.md`; decision 2118's `binding_abi::flag` doc).
+        -- (decision 2118's `binding_abi::flag` doc).
         assert(b:IsEnabled() == 1, "1, not true")
         b:Disable()
         assert(b:IsEnabled() == 0, "0, not false and not nil")
@@ -288,11 +272,9 @@ fn slider_get_thumb_texture_returns_a_stable_region() {
 
 #[test]
 fn slider_scrollbar_wiring_does_not_recurse() {
-    // The real FauxScrollFrame wiring (UIPanelTemplates.xml): the scrollbar Slider's OnValueChanged
-    // drives the ScrollFrame's SetVerticalScroll, whose OnVerticalScroll drives the Slider's
-    // SetValue back the other way. A fire-always SetValue would recurse forever; the change-gate
-    // (SliderState::store_value returns Some only on an actual change) breaks the loop after one hop.
-    // This test *is* the recursion — if the gate regressed it would stack-overflow, not assert-fail.
+    // Stock wiring: the slider's OnValueChanged scrolls the frame (`UIPanelTemplates.xml:157`),
+    // whose OnVerticalScroll sets the slider back (`:193`). The change gate
+    // (`SliderState::store_value`) ends it after one hop; without it the stack overflows.
     let mut s = script();
     s.set_screen_size(1024.0, 768.0);
     s.run(
@@ -325,12 +307,9 @@ fn slider_scrollbar_wiring_does_not_recurse() {
 
 #[test]
 fn slider_value_bits_gate_the_first_fire_and_the_range_reclamp() {
-    // The client's `+0x314` bit1 (has a range) and bit2 (has a value), wow-re
-    // `slider-mouse-law.md` §3/§6, byte-read off `SetValue 0x789930` / `SetMinMaxValues 0x7898f0`:
-    // rangeless SetValue is a no-op; the FIRST SetValue always fires, even at the zero-init value;
-    // SetMinMaxValues re-clamps through SetValue only once a value exists. Decision 2095 — Atlas's
-    // option sliders raised from their own <OnLoad> because our SetMinMaxValues clamped the
-    // zero-init value into (0.25, 1) and ran a handler the addon had not armed yet.
+    // The reference's `+0x314` bit1 (has a range) and bit2 (has a value), from `SetValue`
+    // (`0x789930`) and `SetMinMaxValues` (`0x7898f0`): a rangeless SetValue is a no-op, the
+    // first SetValue always fires, and SetMinMaxValues re-clamps only once a value exists.
     let s = script();
     s.run(
         r#"
@@ -364,10 +343,8 @@ fn slider_value_bits_gate_the_first_fire_and_the_range_reclamp() {
 
 #[test]
 fn slider_onload_range_does_not_run_an_unarmed_onvaluechanged() {
-    // Atlas's exact shape (AtlasOptions.xml): the slider's <OnLoad> sets a range whose low end is
-    // above zero, and its <OnValueChanged> indexes a saved-variables global that only exists after
-    // ADDON_LOADED. In the reference the load raises nothing; before 2095 ours raised
-    // "attempt to index global 'AtlasOptions' (a nil value)" out of the OnLoad.
+    // Atlas's options slider (`AtlasOptions.xml`): its `<OnValueChanged>` reads a saved variable
+    // that exists only after ADDON_LOADED; in the reference the `<OnLoad>` range raises nothing.
     let mut s = script();
     let doc = crate::framexml::parse(
         r#"<Ui>
@@ -398,14 +375,10 @@ fn slider_onload_range_does_not_run_an_unarmed_onvaluechanged() {
 
 #[test]
 fn a_thumb_with_no_authored_size_takes_its_arts_texel_span_and_still_drags() {
-    // Dewdrop-2.0's `OpenSlider` (Cartographer 2.02 → Look 'n' Feel → Overlay transparency), in
-    // its own construction order — the shape that has no `<ThumbTexture><Size>` anywhere:
-    // `SetThumbTexture(path)` from Lua and nothing else. The reference asks the thumb for its own
-    // `GetWidth`/`GetHeight` (`0x789ba0` → `[thumb_vt+0x1c]/[+0x20]` = `CSimpleTexture::0x770720`
-    // /`0x770790`), which falls back to the art's native texel span — 32×32 for
-    // `UI-SliderBar-Button-Vertical` — so the thumb is a 32-unit knob on a 128-unit track with
-    // 96 units of travel. Ours read the *authored* size only and, finding none, sized the thumb to
-    // the whole track: zero travel, a thumb smeared over the bar, and a drag that cannot move.
+    // Dewdrop-2.0's `OpenSlider`, in its construction order: `SetThumbTexture(path)` and no size.
+    // The reference sizes the thumb by its own `GetWidth`/`GetHeight` (`0x789ba0` calls
+    // `0x770720`, `0x770790`), which fall back to the art's texel span: 32×32 for
+    // `UI-SliderBar-Button-Vertical`, leaving 96 units of travel on the 128-unit track.
     let mut s = script();
     s.set_screen_size(1024.0, 768.0);
     s.set_texture_size_probe(Box::new(|p| {
@@ -449,7 +422,7 @@ fn a_thumb_with_no_authored_size_takes_its_arts_texel_span_and_still_drags() {
         "a sizeless thumb is its art's 32×32, flush at the track top — not the whole 16×128 track"
     );
 
-    // And it drags: grab the thumb at its centre and pull to the bottom of the track.
+    // Grab the thumb at its centre and pull to the bottom of the track.
     s.mouse_button(123.0, 233.0, "LeftButton", true);
     s.mouse_move(123.0, 137.0);
     let v: f32 = s.eval("return DdSlider:GetValue()").unwrap();
@@ -461,10 +434,8 @@ fn a_thumb_with_no_authored_size_takes_its_arts_texel_span_and_still_drags() {
 
 #[test]
 fn slider_setvalue_quantises_onto_the_min_anchored_lattice() {
-    // `SetValue 0x789930` rounds the clamped value onto `min + n·step` (round-half-away-from-zero,
-    // truncated by `__ftol`) BEFORE it stores — so `GetValue` on a stepped slider can only ever
-    // answer a lattice point, and the lattice is anchored at `min`, not at zero. Decision 2095
-    // named this divergence and left it; this is it closed.
+    // `SetValue` (`0x789930`) rounds the clamped value onto `min + n·step` (half away from zero,
+    // then `__ftol`) before storing, so the lattice is anchored at `min`, not at zero.
     let s = script();
     s.run(
         r#"
@@ -474,8 +445,7 @@ fn slider_setvalue_quantises_onto_the_min_anchored_lattice() {
     "#,
     )
     .unwrap();
-    // The lattice is 0.2 / 0.7 / 1.2 — 0.5 and 1.0 are NOT on it, which is the whole point of
-    // anchoring at `min`.
+    // The lattice is 0.2, 0.7, 1.2; 0.5 and 1.0 are not on it.
     for (set, want) in [
         (0.6, 0.7),
         (0.95, 0.7),
@@ -495,9 +465,8 @@ fn slider_setvalue_quantises_onto_the_min_anchored_lattice() {
 
 #[test]
 fn a_zero_step_leaves_the_value_continuous() {
-    // The gate that keeps every scrollbar working: `UIPanelScrollBarTemplate` declares no
-    // `valueStep`, so `[+0x324]` stays at the ctor's 0.0 and `0x78999c`'s `fcomp(step, 0.0)`
-    // skips the quantiser outright. A stepless slider stores exactly what it was handed.
+    // `UIPanelScrollBarTemplate` declares no `valueStep`, so `[+0x324]` stays at the constructor's
+    // 0.0 and `0x78999c` skips the quantiser: a stepless slider stores what it is handed.
     let s = script();
     s.run(
         r#"
@@ -515,11 +484,9 @@ fn a_zero_step_leaves_the_value_continuous() {
 
 #[test]
 fn the_quantised_value_is_not_re_clamped_and_may_pass_max() {
-    // The clamp runs BEFORE the quantiser and there is no second clamp after it (`0x789a06`
-    // stores whatever `fild n; fmul step; fadd min` produced). So a range that is not a whole
-    // number of steps rounds *past* its own max at the top of the travel. This looks like a bug
-    // and is the client's arithmetic; it is unreachable in the shipped UI because every stepped
-    // slider the reference ships is an exact multiple of its step.
+    // The clamp runs before the quantiser and nothing clamps after it (`0x789a06` stores
+    // `min + n·step` as computed), so a range that is not a whole number of steps rounds past
+    // its max. This looks like a bug but is the reference's arithmetic; no stock slider hits it.
     let s = script();
     s.run(
         r#"
@@ -542,11 +509,9 @@ fn the_quantised_value_is_not_re_clamped_and_may_pass_max() {
 
 #[test]
 fn a_faux_scrollframes_rows_snap_and_its_bottom_is_exact() {
-    // The falsifier decision 2095 named for this change, run on the shape it names.
-    // `FauxScrollFrame_Update` builds its range as `(numItems − numToDisplay) · valueStep`
-    // (`UIPanelTemplates.lua:180`) and then sets that same step, so the range IS a whole number
-    // of steps: every drag lands on a row boundary and the bottom of the travel is exactly max.
-    // 20 items, 10 on screen, 16 units a row ⇒ range 0..160, step 16.
+    // `FauxScrollFrame_Update` sets the range `(numItems − numToDisplay) · valueStep` and that
+    // same step (`UIPanelTemplates.lua:180`), so every drag lands on a row and the bottom is
+    // exactly max. 20 items, 10 on screen, 16 units a row: range 0..160, step 16.
     let s = script();
     s.run(
         r#"
@@ -560,13 +525,13 @@ fn a_faux_scrollframes_rows_snap_and_its_bottom_is_exact() {
         (23.9, 16.0), // just under the half-step boundary: the row below
         (24.1, 32.0), // just over it: the row above
         (37.0, 32.0),
-        (160.0, 160.0), // the bottom is exact — no overshoot, the range is 10 steps
+        (160.0, 160.0), // the bottom is exact: the range is 10 steps
         (0.0, 0.0),
     ] {
         s.run(&format!("SlFaux:SetValue({set})")).unwrap();
         let v: f32 = s.eval("return SlFaux:GetValue()").unwrap();
         assert_eq!(v, want, "SetValue({set}) snaps to the row at {want}");
-        // FauxScrollFrame_GetOffset's own arithmetic, which is what the row list reads.
+        // The row offset; stock rounds it (`UIPanelTemplates.lua:231`), equal on a snapped value.
         let off: f32 = s.eval("return floor(SlFaux:GetValue() / 16)").unwrap();
         assert_eq!(off, (want / 16.0).floor(), "and the row offset follows it");
     }
@@ -574,10 +539,8 @@ fn a_faux_scrollframes_rows_snap_and_its_bottom_is_exact() {
 
 #[test]
 fn a_move_inside_one_step_fires_nothing() {
-    // The quantiser sits INSIDE the change-gate (`0x789a0b`'s `fcom` is against the stored value,
-    // and what is stored is already quantised), so a drag that stays within one step's band
-    // resolves to the same lattice point and never reaches `OnValueChanged`. Before this, every
-    // pixel of a stepped drag fired.
+    // The change gate compares against the stored, already quantised value (`0x789a0b`), so a
+    // drag within one step's band never reaches `OnValueChanged`.
     let s = script();
     s.run(
         r#"
@@ -609,9 +572,8 @@ fn a_move_inside_one_step_fires_nothing() {
 
 #[test]
 fn set_value_step_re_quantises_the_held_value_and_can_fire() {
-    // `SetValueStep 0x789a60` stores the step and then re-pushes the range through
-    // `SetMinMaxValues`, which re-clamps the held value through `SetValue` — onto the NEW lattice
-    // (decision 2143). A step handed to a slider that already holds a value moves it and fires.
+    // `SetValueStep` (`0x789a60`) stores the step and re-pushes the range, which re-clamps a held
+    // value through `SetValue` onto the new lattice, and that move fires.
     let s = script();
     s.run(
         r#"
@@ -626,7 +588,7 @@ fn set_value_step_re_quantises_the_held_value_and_can_fire() {
     assert_eq!(s.eval::<f32>("return SlStep:GetValue()").unwrap(), 37.0);
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 1);
 
-    // A step arriving AFTER the value snaps it: 37 → 40 on a 10-lattice, and the move fires.
+    // A step arriving after the value snaps it: 37 → 40 on a 10-lattice.
     s.run("SlStep:SetValueStep(10)").unwrap();
     assert_eq!(
         s.eval::<f32>("return SlStep:GetValue()").unwrap(),
@@ -639,7 +601,6 @@ fn set_value_step_re_quantises_the_held_value_and_can_fire() {
         "…and the move fired OnValueChanged, exactly as a SetValue would"
     );
 
-    // A step that moves nothing fires nothing — the same change gate, one level up.
     s.run("SlStep:SetValueStep(20)").unwrap();
     assert_eq!(s.eval::<f32>("return SlStep:GetValue()").unwrap(), 40.0);
     assert_eq!(s.eval::<i64>("return fires").unwrap(), 2);
@@ -647,10 +608,8 @@ fn set_value_step_re_quantises_the_held_value_and_can_fire() {
 
 #[test]
 fn a_step_before_any_range_is_the_whole_call() {
-    // `0x789a6c test byte [+0x314],2` — bit1 clear ⇒ the step is stored and the function returns.
-    // No range is pushed, nothing is clamped, nothing fires. It is what keeps an `<OnLoad>` that
-    // sets a step before a range from running a handler the addon has not armed (2095's subject,
-    // one verb over).
+    // With no range (bit1 clear at `0x789a6c`) the step is stored and nothing else happens, so an
+    // `<OnLoad>` that sets a step before a range runs no handler.
     let s = script();
     s.run(
         r#"
diff --git a/crates/benilla-ui/src/script/tests/statusbar.rs b/crates/benilla-ui/src/script/tests/statusbar.rs
index 28e585e3..62eb5925 100644
--- a/crates/benilla-ui/src/script/tests/statusbar.rs
+++ b/crates/benilla-ui/src/script/tests/statusbar.rs
@@ -1,4 +1,4 @@
-//! StatusBar (per-kind behavior; RF-28-grounded).
+//! StatusBar behaviour (`LoadXML` `0x782ef0`).
 
 use super::common::script;
 use crate::script::*;
@@ -32,7 +32,7 @@ fn statusbar_value_clamps_and_minmax_swaps() {
         assert(b:GetValue() == 100, "clamped to max")
         b:SetValue(-5)
         assert(b:GetValue() == 0, "clamped to min")
-        -- A reversed pair is swapped (RF-28's LoadXML behavior, one rule for both paths).
+        -- A reversed pair is swapped (LoadXML `0x782ef0`'s behavior, one rule for both paths).
         b:SetMinMaxValues(80, 20)
         local mn, mx = b:GetMinMaxValues()
         assert(mn == 20 and mx == 80, "reversed pair swapped")
@@ -52,7 +52,7 @@ fn statusbar_setvalue_fires_onvaluechanged() {
         seen = {}
         b:SetScript("OnValueChanged", function(self, value)
             table.insert(seen, value)
-            assert(self == b and arg1 == value, "RF-0025 conventions carry the value")
+            assert(self == b and arg1 == value, "handler-firing conventions carry the value")
         end)
         b:SetValue(4)
         b:SetValue(4)          -- no change, no fire
@@ -126,9 +126,8 @@ fn statusbar_bar_region_scales_by_fraction_on_extract() {
     );
 }
 
-/// The fill CROPs its art, never squeezes it (wow-re `nameplate-vkey.md`, VERIFIED): `SetValue`
-/// rewrites the region's 4-corner UV block with `u1 = GetValue()` *and* shrinks the quad. Squeezing
-/// instead would run a bar texture's whole horizontal ramp inside every partial fill.
+/// The fill crops its art, never squeezes it (`0x770410`): `SetValue` sets the UV `u1` to the fill
+/// fraction `(value - min) / (max - min)` and shrinks the quad by the same fraction.
 #[test]
 fn statusbar_bar_region_crops_its_texture_rather_than_stretching_it() {
     let mut s = script();
@@ -164,7 +163,7 @@ fn statusbar_bar_region_crops_its_texture_rather_than_stretching_it() {
         "horizontal: u cropped to the fill fraction, v whole"
     );
 
-    // Vertical fills bottom-up, so the art's BOTTOM edge is the one pinned.
+    // Vertical fills bottom-up, so the art's bottom edge is pinned.
     s.run(r#"SbCrop:SetOrientation("VERTICAL")"#).unwrap();
     assert_eq!(
         uv(&s),
diff --git a/crates/benilla-ui/src/script/tests/stdlib.rs b/crates/benilla-ui/src/script/tests/stdlib.rs
index 3348dd35..c53ff6b0 100644
--- a/crates/benilla-ui/src/script/tests/stdlib.rs
+++ b/crates/benilla-ui/src/script/tests/stdlib.rs
@@ -1,9 +1,9 @@
-//! The WoW stdlib: positional `format`, the `getglobal` alias layer, and the
-//! sandbox holes (`loadstring` text-only, dangerous globals removed).
+//! The WoW stdlib: positional `format`, the bare-global aliases, the sandbox, `debugstack`,
+//! `GetTime`, `time`/`date`, `RunScript` and the Lua 5.0 dialect.
 
 use super::common::script;
 
-// ── The positional format wrapper ───────────────────────────────────────────────────────────────
+// ── The positional format wrapper ──
 
 #[test]
 fn positional_format_reorders_and_mix_is_an_error() {
@@ -18,7 +18,7 @@ fn positional_format_reorders_and_mix_is_an_error() {
         s.eval::<String>(r#"return format("%1$05d", 42)"#).unwrap(),
         "00042"
     );
-    // sequential still works (and via string.format too, which we patched)
+    // sequential still works, through the patched `string.format` too
     assert_eq!(
         s.eval::<String>(r#"return string.format("%d-%s", 1, "x")"#)
             .unwrap(),
@@ -29,14 +29,14 @@ fn positional_format_reorders_and_mix_is_an_error() {
         s.eval::<String>(r#"return format("%1$d%%", 50)"#).unwrap(),
         "50%"
     );
-    // mixing positional and sequential is an error (matches Blizzard erroring)
+    // mixing positional and sequential is an error, as in the reference
     let mixed_ok: bool = s
         .eval(r#"return pcall(format, "%1$s %s", "a", "b")"#)
         .unwrap();
     assert!(!mixed_ok, "mixed positional+sequential must error");
 }
 
-// ── getglobal / the alias layer ───────────────────────────────────────────────
+// ── getglobal and the alias layer ──
 
 #[test]
 fn stdlib_aliases_and_helpers() {
@@ -65,7 +65,7 @@ fn stdlib_aliases_and_helpers() {
     .unwrap();
 }
 
-// ── Sandbox holes ───────────────────────────────────────────────────────────────────────────────
+// ── Sandbox holes ──
 
 #[test]
 fn sandbox_removes_dangerous_globals() {
@@ -77,39 +77,24 @@ fn sandbox_removes_dangerous_globals() {
         )
         .unwrap();
     assert!(all_nil);
-    // `debugstack` survives the sandbox — and returns a REAL traceback, not the `""` this used to
-    // assert. The stub was fine for addons that only DISPLAY it and wrong for the ones that PARSE
-    // it: `FuBarPlugin-2.0.lua:752` finds each plugin's own folder in `debugstack(6, 1, 0)`, and
-    // against `""` that returned nil and killed 20 corpus addons.
+    // `debugstack` survives the sandbox and returns a real traceback, which addons parse.
     let trace = s.eval::<String>("return debugstack()").unwrap();
     assert!(
         !trace.is_empty(),
         "debugstack must return a real traceback: {trace:?}"
     );
-    // **Frames only — no `stack traceback:` header** (decision 2121). Line 1 IS a frame, which is
-    // what `AceLibrary.lua:70` reads (`string.gsub(stack, "\n.*", "")` then
-    // `".*\\(.*).lua:%d+: .*"`), and what `AceDB-2.0.lua:742` counts on when it skips exactly one
-    // line to reach its caller's.
+    // Frames only, no `stack traceback:` header: `AceLibrary.lua:70` reads line 1 as a frame and
+    // `AceDB-2.0.lua:742` skips exactly one line to reach its caller.
     assert!(
         !trace.starts_with("stack traceback"),
         "the reference has no header line: {trace:?}"
     );
-    // A level far past the top of the stack is an empty string, never a raise — a caller that
-    // guesses too deep still gets something it can `string.find` against.
+    // A level past the top of the stack is an empty string, never a raise.
     assert_eq!(s.eval::<String>("return debugstack(99)").unwrap(), "");
 }
 
-/// **AceDB-2.0's own capture, run for real across two chunks** (decision 2121).
-///
-/// `RegisterDB` reads the calling addon's folder out of `debugstack()` by skipping exactly one
-/// line — its own frame — and taking the `\AddOns\<folder>\` out of the next. That only works if
-/// line 1 is a frame; with mlua's `stack traceback:` header in front, the capture returned the
-/// folder of whichever addon shipped the winning copy of the library, `RegisterDB` took its
-/// already-loaded branch, and `db.raw` was bound to a fresh table at the addon's file scope —
-/// before the SavedVariables chunk ran. Bartender2 then printed `Creating new DB` at every login.
-///
-/// The two chunks here are the real configuration: the library lives in one addon's folder, the
-/// caller in another's.
+/// AceDB-2.0's `RegisterDB` skips one line of `debugstack()`, its own frame, and takes the caller's
+/// `\AddOns\<folder>\` from the next; here the library and its caller load from different addons.
 #[test]
 fn acedbs_capture_names_the_calling_addon_not_the_librarys_owner() {
     let s = script();
@@ -132,7 +117,7 @@ fn acedbs_capture_names_the_calling_addon_not_the_librarys_owner() {
     );
 }
 
-/// `AceLibrary.lua:70`'s reader: the first line, whole, is a frame it can pull a file name out of.
+/// `AceLibrary.lua:70` pulls a file name out of the first line, a whole frame.
 #[test]
 fn the_first_debugstack_line_is_a_frame() {
     let s = script();
@@ -151,9 +136,8 @@ fn the_first_debugstack_line_is_a_frame() {
     );
 }
 
-/// `AceLibrary.lua:139`'s `argCheck` names the offending function with `"([`<].-['>])"` — a
-/// BACKTICK opening it. Lua 5.4 writes `in function 'name'`, which that pattern cannot match; the
-/// reference's 5.0 wording is `` in function `name' ``.
+/// The reference's Lua 5.0 writes a named frame as `` in function `name' ``, opening with a
+/// backtick, which `AceLibrary.lua:139`'s `argCheck` pattern `` "([`<].-['>])" `` needs.
 #[test]
 fn a_named_frame_uses_the_5_0_backtick_quoting() {
     let s = script();
@@ -165,18 +149,10 @@ fn a_named_frame_uses_the_5_0_backtick_quoting() {
     assert_eq!(found, "`BenillaProbeNamed'");
 }
 
-/// **Every frame carries its own trailing `\n`, and `count1` bounds nothing on its own**
-/// (decision 2121, wow-re `debugstack-return-shape.md` §3.1).
-///
-/// Stock Lua 5.0 pushes `"\n\t"` *before* each frame plus a header once; the reference pushes a
-/// single `"\n"` after each frame and no header (`0x703971`). And the walk formats while the level
-/// is `<= start + count1` — `0x703857` is `jbe`, unsigned ≤ — then probes
-/// `getstack(level + count2)`: a probe that FAILS steps back and prints that level as an ordinary
-/// frame. So with `count1 = 1, count2 = 0` a two-deep stack returns TWO frames and no marker, and a
-/// three-deep one returns one frame plus `"...\n"` and nothing after. A client that clamped to
-/// `count1` would diverge at exactly `depth == count1 + 1` — and that is
-/// `FuBarPlugin-2.0.lua:752`'s `debugstack(6, 1, 0)`, whose capture is a GREEDY
-/// `"\\AddOns\\(.*)\\"` reading the LAST path in the string.
+/// The reference ends each frame with `"\n"` and writes no header (`0x703971`). It formats while
+/// the level is `<= start + count1` (`0x703857`, `jbe`), then probes `getstack(level + count2)`; a
+/// failed probe prints that level as an ordinary frame. So with `count1 = 1, count2 = 0` a
+/// two-deep stack gives two frames and no marker, and a three-deep one a frame then `"...\n"`.
 #[test]
 fn debugstack_frames_end_in_newline_and_count1_does_not_clamp() {
     let s = script();
@@ -185,8 +161,6 @@ fn debugstack_frames_end_in_newline_and_count1_does_not_clamp() {
         trace.ends_with('\n'),
         "the newline is pushed AFTER each frame: {trace:?}"
     );
-    // Two levels at or above `start`, `count1 = 1`: the elision probe fails, so the second frame
-    // prints in full and no marker appears.
     let two: String = s
         .eval(
             "function BenillaProbeDepth2() local r = debugstack(1, 1, 0) return r end \
@@ -196,7 +170,6 @@ fn debugstack_frames_end_in_newline_and_count1_does_not_clamp() {
     let lines: Vec<&str> = two.trim_end().split('\n').collect();
     assert_eq!(lines.len(), 2, "two frames, no marker: {two:?}");
     assert!(!two.contains("..."), "no elision at depth 2: {two:?}");
-    // Deeper: one frame, then the marker on its own line, and nothing after it (count2 = 0).
     let deep: String = s
         .eval(
             "function BenillaProbeC() local r = debugstack(1, 1, 0) return r end \
@@ -210,20 +183,15 @@ fn debugstack_frames_end_in_newline_and_count1_does_not_clamp() {
     assert_eq!(lines[1], "...", "the marker is its own complete line");
 }
 
-/// **An addon's chunk is named the way the CLIENT names it**, because addons parse that name.
-///
-/// `FuBarPlugin-2.0.lua:752` is `string.find(debugstack(6, 1, 0), "\\AddOns\\(.*)\\")`, and it
-/// feeds the capture into `format("Interface\\AddOns\\%s\\icon", folderName)`. Without a name
-/// mlua defaults the chunk to the RUST caller location, that pattern misses, and every FuBar plugin
-/// dies formatting a nil three frames from the cause.
-///
-/// The greedy `(.*)` is why the file has to be in the name too: it captures to the LAST backslash.
+/// An addon chunk is named as the reference names it, `@Interface\AddOns\<folder>\<file>`:
+/// `FuBarPlugin-2.0.lua:752` finds its folder with a greedy `"\\AddOns\\(.*)\\"`, which captures
+/// up to the last backslash, so the file must be in the name.
 #[test]
 fn an_addon_chunk_is_named_the_way_the_client_names_it() {
     let name = crate::script::addon_chunk_name("FuBar_BagFu", "FuBar_BagFu.lua");
     assert_eq!(name, "@Interface\\AddOns\\FuBar_BagFu\\FuBar_BagFu.lua");
 
-    // FuBar's own pattern, run for real against a traceback from a chunk loaded under that name.
+    // FuBar's own pattern, against a traceback from a chunk loaded under that name.
     let s = script();
     s.run_chunk_named(
         b"function BenillaProbeFolder() return debugstack(1, 1, 0) end",
@@ -267,7 +235,7 @@ fn loadstring_is_text_only_bytecode_rejected() {
     assert!(ok, "loadstring must reject bytecode");
 }
 
-// ── GetTime: the session clock (decision 0137 — the reference cast bar anchors on it) ───────────
+// ── GetTime: the session clock ──
 
 #[test]
 fn gettime_starts_at_zero_and_tracks_tick() {
@@ -279,15 +247,7 @@ fn gettime_starts_at_zero_and_tracks_tick() {
     assert!((t - 0.5).abs() < 1e-6, "two 0.25s ticks = 0.5 (got {t})");
 }
 
-/// The rest of the bare globals Blizzard's own restricted scope enumerates (decision 1187).
-///
-/// The list is not from memory: `Blizzard_RestrictedAddOnEnvironment/RestrictedEnvironment.lua`
-/// copies exactly these out of the engine, which is what distinguishes them from the table helpers
-/// (`tContains`, `tInvert`, …) that FrameXML defines in Lua and we must therefore NOT supply.
-///
-/// The measured cost of their absence: Bagnon + BagBrother produced 94 load failures, 81 of them
-/// `Cannot find a library instance of "…"`, because `strmatch` was nil so every LibStub-registering
-/// library aborted before it could register.
+/// The rest of the engine's bare string and math globals, and the later-client names it lacks.
 #[test]
 fn the_rest_of_the_bare_globals() {
     let s = script();
@@ -318,20 +278,8 @@ fn the_rest_of_the_bare_globals() {
     .unwrap();
 }
 
-/// **The Lua 5.0 dialect a vanilla addon is written in runs on our 5.1 VM** — measured, because
-/// this question has been answered three different ways from memory.
-///
-/// 1.12 runs Lua 5.0 (byte-confirmed in wow-5875-re: `0x811b30 = "Lua: Lua 5.0 Copyright..."`);
-/// we run 5.1 via mlua's `lua51`. Decision 1188 called that "the deepest divergence and it is
-/// unresolved" and told the next session to test it; 1189 replied that 0068 had already closed it.
-/// Meanwhile five of our own transcribed FrameXML files carried the opposite claim in a comment —
-/// *"`LUA_COMPAT_VARARG` isn't shipped"* — each citing the others as precedent, so a false fact
-/// propagated by citation without anyone re-running it.
-///
-/// It is shipped. This asserts the five idioms vanilla addon code actually uses, so the next
-/// session reads a result instead of a recollection. **The implicit `arg` table is the one that
-/// matters**: it is the difference between a vanilla addon's vararg functions working and every
-/// one of them erroring at runtime, which is 1188's stated redirect-the-arc risk.
+/// 1.12 runs Lua 5.0 (`0x811b30`, "Lua: Lua 5.0 Copyright..."); this VM is mlua's `lua51`, and the
+/// 5.0 idioms vanilla addons use run on it, above all the implicit vararg `arg` table.
 #[test]
 fn the_lua_5_0_dialect_vanilla_addons_are_written_in_runs_here() {
     let s = script();
@@ -364,22 +312,13 @@ fn the_lua_5_0_dialect_vanilla_addons_are_written_in_runs_here() {
     .unwrap();
 }
 
-/// **`time()` is real epoch seconds and `date()` formats them** — engine globals in the 1.12
-/// client's own `_G` (slots 34/33 of its base registry) that we lacked entirely, because the
-/// sandbox strips `os`.
-///
-/// `time` was the top name in the session-start `attempt to call global` row. Every corpus site
-/// persists it into SavedVariables and compares across sessions
-/// (`FTC_Save[k].LastCheck = time()`), so a session-relative clock like `GetTime` would be wrong in
-/// a way that only shows up on the SECOND login.
-///
-/// The formats asserted are the ones read off real call sites, against a FIXED epoch so the
-/// conversion is checked rather than the machine's clock: 2001-09-09 01:46:40 UTC, a Sunday.
+/// `time()` is wall-clock epoch seconds and `date()` formats them, both engine globals in the 1.12
+/// `_G` (slots 34 and 33 of its base registry); addons save `time()` and compare across logins.
 #[test]
 fn time_is_epoch_seconds_and_date_formats_them() {
     let s = script();
 
-    // A plausible wall clock: after 2020, before 2100. Pins that this is not GetTime's 0-based one.
+    // A plausible wall clock, between 2020 and 2100, not GetTime's 0-based one.
     let now: i64 = s.eval("return time()").unwrap();
     assert!(
         (1_577_836_800..4_102_444_800).contains(&now),
@@ -409,31 +348,26 @@ fn time_is_epoch_seconds_and_date_formats_them() {
         assert_eq!(got, want, "date({fmt:?})");
     }
 
-    // Bare `date()` is `%c` (Recap.lua:2690 calls it with no arguments) and must not raise.
+    // Bare `date()` is `%c` and must not raise; `Recap.lua:2690` calls it with no arguments.
     let bare: String = s.eval("return date()").unwrap();
     assert!(
         bare.len() > 10,
         "bare date() must format something: {bare:?}"
     );
 
-    // A leap day, because the civil conversion is where a date implementation goes wrong.
+    // A leap day, the civil conversion's edge case.
     let leap: String = s.eval(r#"return date("%Y-%m-%d %A", 951782400)"#).unwrap();
     assert_eq!(leap, "2000-02-29 Tuesday");
 }
 
-// ── RunScript, at the image's own contract (2136's "left open", closed) ──────────────────────────
+// ── RunScript ──
 
-/// `RunScript`'s chunk name is the SOURCE, not a label of ours.
-///
-/// `0x48b9c7 mov edx,eax` / `0x48b9c9 mov ecx,eax` hand `lua_tostring`'s one return to
-/// `FrameScript_Execute 0x704cd0` as both the code and the name, so the name reaches
-/// `luaL_loadbuffer` unprefixed and `luaO_chunkid 0x6f5c40` wraps it — `[string "…"]`. We used to
-/// write `=[RunScript]`, whose leading `=` is chunkid's *print this verbatim* marker.
+/// `RunScript` hands its string to `FrameScript_Execute` (`0x704cd0`) as both code and chunk name
+/// (`0x48b9c7`, `0x48b9c9`), so `luaO_chunkid` (`0x6f5c40`) reports it as `[string "…"]`.
 #[test]
 fn a_runscript_chunk_is_named_by_its_own_source() {
     let mut s = script();
-    // The error is consumed by RunScript (fact 3), so read it off the recorded channel rather
-    // than off a raise.
+    // RunScript consumes the error, so read it off the recorded channel.
     s.run("RunScript(\"error('boom')\")").unwrap();
     let errs = s.take_errors();
     assert!(
@@ -443,15 +377,12 @@ fn a_runscript_chunk_is_named_by_its_own_source() {
     );
 }
 
-/// The three silent legs, and the raise that must NOT happen.
-///
-/// `lua_isstring 0x6f3510` is tag-based, so a number passes and runs as its own text; every other
-/// type takes `0x48b98f je 0x48b9f3` to `xor eax,eax; ret`. An empty string takes the same exit at
-/// `0x48b9a1`. There is no `luaL_error 0x6f4940` in the function at all.
+/// A non-string argument returns silently (`0x48b98f` jumps to `0x48b9f3`), as does an empty
+/// string (`0x48b9a1`); a number passes `lua_isstring` (`0x6f3510`) and runs as text. The function
+/// never calls `luaL_error` (`0x6f4940`).
 #[test]
 fn runscript_swallows_a_bad_argument_instead_of_raising() {
     let mut s = script();
-    // Each of these must return normally AND leave the next statement running.
     s.run(
         "BenillaRan = 0
          RunScript(nil)
@@ -466,7 +397,7 @@ fn runscript_swallows_a_bad_argument_instead_of_raising() {
         s.take_errors().is_empty(),
         "a silent no-op records nothing either"
     );
-    // A number IS a string to `lua_isstring`, so it compiles — and `42` is not a statement.
+    // A number is a string to `lua_isstring`, so it compiles, and `42` is not a statement.
     s.run("RunScript(42)").unwrap();
     assert!(
         s.take_errors()
@@ -476,11 +407,9 @@ fn runscript_swallows_a_bad_argument_instead_of_raising() {
     );
 }
 
-/// A raise inside the snippet does not escape it: `0x704ae0` runs the chunk under
-/// `lua_pcall(L, 0, 0, -2)` (`0x704b68`) with the registry's error handler pushed at `0x704afe`,
-/// and pcalls that same handler for a *compile* failure (`0x704b42`). Both legs return 0 values.
-///
-/// This is the one with teeth: raising here let one bad macro abort whatever ran it.
+/// A raise inside the snippet stays there: `0x704ae0` runs it under `lua_pcall` (`0x704b68`) with
+/// the registry's error handler (`0x704afe`), and calls that handler for a compile failure too
+/// (`0x704b42`).
 #[test]
 fn a_runscript_error_reaches_the_handler_and_not_the_caller() {
     let mut s = script();
@@ -503,7 +432,7 @@ fn a_runscript_error_reaches_the_handler_and_not_the_caller() {
         "both errors are recorded, not dropped: {errs:?}"
     );
     assert!(errs[0].contains("inner"), "{errs:?}");
-    // mlua's `Display` category word ("syntax error: ") is not something the image ever writes.
+    // mlua's `Display` prefix ("syntax error: ") is not something the reference writes.
     assert!(
         errs[1].starts_with("[string \"this is not lua\"]:1:"),
         "a compile failure is reported under the same name, undecorated: {errs:?}"
diff --git a/crates/benilla-ui/src/script/tests/structure_queries.rs b/crates/benilla-ui/src/script/tests/structure_queries.rs
index 03fde377..46132d88 100644
--- a/crates/benilla-ui/src/script/tests/structure_queries.rs
+++ b/crates/benilla-ui/src/script/tests/structure_queries.rs
@@ -1,30 +1,9 @@
-//! **`GetChildren` / `GetNumChildren` / `GetRegions` / `GetNumRegions`** — the four structure
-//! queries, and the properties an addon walking a frame it did not build depends on.
-//!
-//! The consumer that motivated them is `pfUI.api.StripTextures`, embedded in four separate top-20
-//! addons (pfUI, pfQuest, pfQuest-turtle, ShaguDPS):
-//!
-//! ```lua
-//! for _, v in ipairs({ frame:GetRegions() }) do
-//!   if v.SetTexture then ... end
-//! end
-//! ```
-//!
-//! so the shape under test is the one that idiom needs: **multiple return values**, in the
-//! structure's own order, each a usable widget object.
-//!
-//! Every claim here is VERIFIED against the reference by a wow-re §5 quartet
-//! (`ui/scratch/widget-list-bindings.md`): the lists are `[frame+0x300]` and `[frame+0x1b8]`, both
-//! linkers APPEND AT THE TAIL so the values come back oldest-first with no reversal, hidden nodes
-//! are returned and counted, a detached region and the title region are both absent, a Button's
-//! label and state textures are present, and an empty frame returns zero values while `GetNum*`
-//! returns the number `0`.
+//! The structure queries `GetChildren`, `GetNumChildren`, `GetRegions` and `GetNumRegions`
+//! (`0x773f60`/`0x774180`): they walk `[frame+0x300]` and `[frame+0x1b8]`, whose linkers append at
+//! the tail, so values come back oldest first as multiple returns, hidden ones included.
 
 use super::common::script;
 
-/// The whole contract in one document: both lists, their order, the counts agreeing with them, the
-/// empty case, and — the one that is a behaviour rather than a plumbing detail — that a region
-/// detached by `SetParent(nil)` leaves both region verbs.
 #[test]
 fn the_structure_queries_report_the_structure() {
     let mut s = script();
@@ -48,8 +27,7 @@ fn the_structure_queries_report_the_structure() {
     )
     .unwrap();
 
-    // ── The lists, by name and IN ORDER. Named rather than counted, so a walk that returned the
-    //    right number of the wrong things (or the right things reversed) cannot pass.
+    // ── The lists, by name and in order.
     assert_eq!(
         s.eval::<String>(
             "local n = '' for _, v in ipairs({ SQHost:GetChildren() }) do \
@@ -69,9 +47,7 @@ fn the_structure_queries_report_the_structure() {
         "regions come back in CREATION order, not draw order — the OVERLAY fontstring stays second"
     );
 
-    // ── The counts are the same walk. A count that disagrees with the list is an off-by-one deep
-    //    inside a loop the addon did not write, so the two verbs share one function by construction
-    //    and this pins it.
+    // ── The counts are the same walk.
     assert_eq!(
         s.eval::<(usize, usize)>(
             "return SQHost:GetNumChildren(), table.getn({ SQHost:GetChildren() })"
@@ -87,8 +63,7 @@ fn the_structure_queries_report_the_structure() {
         (3, 3)
     );
 
-    // ── The objects are USABLE, not opaque handles: `StripTextures` feature-tests `v.SetTexture`
-    //    to tell a texture from a fontstring, then calls it. Both halves have to hold.
+    // ── Usable objects: pfUI's `StripTextures` tests `v.SetTexture`, then calls it.
     assert_eq!(
         s.eval::<String>(
             "local out = '' for _, v in ipairs({ SQHost:GetRegions() }) do \
@@ -100,8 +75,7 @@ fn the_structure_queries_report_the_structure() {
         "a texture answers SetTexture and a fontstring does not — the StripTextures branch"
     );
 
-    // ── A childless, regionless frame yields NOTHING, and counts zero. `ipairs` over it must run
-    //    zero times rather than once over a nil.
+    // ── An empty frame returns no values and counts zero.
     assert_eq!(
         s.eval::<(usize, usize, usize)>(
             "local e = CreateFrame(\"Frame\", \"SQEmpty\", UIParent) \
@@ -111,11 +85,8 @@ fn the_structure_queries_report_the_structure() {
         (0, 0, 0)
     );
 
-    // ── DETACHED REGIONS LEAVE BOTH VERBS. `Region:SetParent(nil)` unlinks from the parent's draw
-    //    layer AND its region list in the client (`0x77fd10`, wow-re `widget-api-batch-benilla.md`
-    //    Q7). We keep the entry so the arena can still free the slot — a representation choice that
-    //    must not be observable here, or a StripTextures-shaped walk would "strip" a region that is
-    //    already off the screen.
+    // ── A detached region leaves both verbs: `Region:SetParent(nil)` unlinks it from the draw
+    //    layer and the region list (`0x77fd10`); our arena keeps the entry, unseen here.
     s.run("SQFontB:SetParent(nil)").unwrap();
     assert_eq!(
         s.eval::<String>(
@@ -132,13 +103,8 @@ fn the_structure_queries_report_the_structure() {
         "...and from the count, which is the same walk"
     );
 
-    // ── THE TITLE REGION IS NOT IN THE LIST, and this is the assertion that corrected us. Its two
-    //    creation paths in the client dispatch a vtable slot that is a bare `[this+0x9c] = parent`
-    //    and never reach the region linker, so it was never in the list `GetRegions` walks —
-    //    corroborated by `Hide`/`Show` carrying an explicit extra `[frame+0xa8]` case *because* the
-    //    walk misses it (wow-re `ui/scratch/widget-list-bindings.md`, §5 quartet). Ours lives in
-    //    `Frame::regions` so the arena can still free it, which makes that a representation detail
-    //    this walk must not leak.
+    // ── The title region is not in the list: its creation sets `[this+0x9c] = parent` without
+    //    the region linker, and `Hide`/`Show` handle `[frame+0xa8]` separately (`0x768060`).
     s.run("SQHost:CreateTitleRegion()").unwrap();
     assert_eq!(
         s.eval::<usize>("return SQHost:GetNumRegions()").unwrap(),
@@ -155,8 +121,7 @@ fn the_structure_queries_report_the_structure() {
         "...and does not appear in it"
     );
 
-    // ── A child reparented away leaves its old parent's child list too (the frame twin of the
-    //    above, and the case an addon hits when it re-hosts a default-UI frame).
+    // ── A reparented child leaves its old parent's list.
     s.run("SQChildB:SetParent(UIParent)").unwrap();
     assert_eq!(
         s.eval::<String>(
diff --git a/crates/benilla-ui/src/script/tests/talent.rs b/crates/benilla-ui/src/script/tests/talent.rs
index 1f9fcc32..ab4c63fc 100644
--- a/crates/benilla-ui/src/script/tests/talent.rs
+++ b/crates/benilla-ui/src/script/tests/talent.rs
@@ -1,6 +1,5 @@
-//! The talent engine seam (decision 0304): the Era binding tuples over a pushed snapshot, the
-//! learn-click queue, and the `SetTalent` tooltip — the spell builder with the talent
-//! interleave (rank line white, req lines red, next-rank block, learn hint green).
+//! The talent bindings over a pushed snapshot, the learn queue, and `SetTalent`: the spell tooltip
+//! with the talent lines interleaved.
 
 use super::common::script;
 use crate::script::*;
@@ -62,8 +61,6 @@ fn one_tab_state() -> TalentUiState {
     }
 }
 
-/// The Era tuples read back exactly what the app pushed — including the 1-based grid seats,
-/// the flat prereq triplets, and the points pair.
 #[test]
 fn bindings_read_the_pushed_snapshot() {
     let mut s = script();
@@ -95,7 +92,6 @@ fn bindings_read_the_pushed_snapshot() {
     assert!(s.take_errors().is_empty());
 }
 
-/// LearnTalent queues (tab, index) verbatim for the app's wire drain.
 #[test]
 fn learn_talent_queues_for_the_app_drain() {
     let mut s = script();
@@ -106,9 +102,8 @@ fn learn_talent_queues_for_the_app_drain() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A stand-in string table for the talent tail's three keys — **deliberately not the shipped
-/// wording**, because what is under test is which key each line reaches and what fills it, never
-/// what the sentence says (decision 2045).
+/// Stand-in values for the three talent keys, not the shipped wording: the tests check which key
+/// each line reaches.
 fn seed_talent_strings(s: &mut UiScript) {
     s.run(
         r#"
@@ -120,9 +115,8 @@ fn seed_talent_strings(s: &mut UiScript) {
     .unwrap();
 }
 
-/// SetTalent = the spell builder + the talent interleave: name, TOOLTIP_TALENT_RANK white, cost
-/// line, gold description, TOOLTIP_TALENT_NEXT_RANK + the next rank's gold description, green
-/// TOOLTIP_TALENT_LEARN.
+/// `SetTalent`'s lines: name, `TOOLTIP_TALENT_RANK` (white), cost, gold description,
+/// `TOOLTIP_TALENT_NEXT_RANK` and the next rank's gold description, green `TOOLTIP_TALENT_LEARN`.
 #[test]
 fn set_talent_renders_the_interleaved_tooltip() {
     let mut s = script();
@@ -162,7 +156,6 @@ fn set_talent_renders_the_interleaved_tooltip() {
     "#,
     )
     .unwrap();
-    // The learn hint wears the tooltip green; the requirement red is exercised below.
     s.resolve();
     let quads = s.extract();
     let green = quads.iter().any(|q| {
@@ -173,14 +166,13 @@ fn set_talent_renders_the_interleaved_tooltip() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A locked talent shows its red requirement line; a missing spell view falls back to the rank
-/// line alone and records the ask for the app resolver (the shared ask-once channel).
+/// A missing spell view renders the rank line alone and asks for the view once.
 #[test]
 fn set_talent_locked_reqs_and_the_ask_once_miss() {
     let mut s = script();
     seed_talent_strings(&mut s);
     s.set_talents(one_tab_state());
-    // No spell view pushed for Ignite (11119): the render falls back, the ask is recorded.
+    // No spell view pushed for Ignite (11119).
     s.run(
         r#"
         local a = CreateFrame("Button", "TB2"); a:SetPoint("CENTER", 0, 0); a:SetWidth(10); a:SetHeight(10)
@@ -198,7 +190,6 @@ fn set_talent_locked_reqs_and_the_ask_once_miss() {
         "the display spell was asked: {asks:?}"
     );
 
-    // With the view landed, the full render carries the red requirement line.
     s.set_spell_tooltip(
         11119,
         SpellTooltipView {
diff --git a/crates/benilla-ui/src/script/tests/taxi.rs b/crates/benilla-ui/src/script/tests/taxi.rs
index 534b9244..91338c00 100644
--- a/crates/benilla-ui/src/script/tests/taxi.rs
+++ b/crates/benilla-ui/src/script/tests/taxi.rs
@@ -1,12 +1,9 @@
-//! The taxi seam (decision 0484): the app-pushed snapshot surfaces through the Era bindings the
-//! reference `TaxiFrame.lua` reads, and the click/close intents drain back out.
+//! The taxi bindings stock `TaxiFrame.lua` reads over a pushed snapshot, and the node and close
+//! intents.
 
 use super::common::script;
 use crate::script::*;
 
-/// The full round trip: push a two-node snapshot, read it back exactly as the reference Lua does
-/// (count, type, position, name, cost, route segments), click a node + close, drain both intents,
-/// and `SetTaxiMap` paints the pushed art onto the target texture region.
 #[test]
 fn taxi_snapshot_surfaces_and_intents_drain() {
     let mut s = script();
@@ -62,7 +59,6 @@ fn taxi_snapshot_surfaces_and_intents_drain() {
     assert!(s.take_taxi_close());
     assert!(!s.take_taxi_close(), "the close flag drains");
 
-    // SetTaxiMap assigned the pushed art onto the texture region.
     s.resolve();
     assert!(
         s.extract().iter().any(|q| matches!(
@@ -72,7 +68,6 @@ fn taxi_snapshot_surfaces_and_intents_drain() {
         "the continent art draws on the SetTaxiMap target"
     );
 
-    // The ride flag reaches UnitOnTaxi.
     s.set_on_taxi(true);
     s.run(r#"assert(UnitOnTaxi("player") == 1)"#).unwrap();
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
diff --git a/crates/benilla-ui/src/script/tests/texcoord_font.rs b/crates/benilla-ui/src/script/tests/texcoord_font.rs
index 60b897b9..db4e3308 100644
--- a/crates/benilla-ui/src/script/tests/texcoord_font.rs
+++ b/crates/benilla-ui/src/script/tests/texcoord_font.rs
@@ -1,11 +1,8 @@
-//! TexCoords + Font objects (decision 0084).
+//! `SetTexCoord` and font objects.
 
 use super::common::script;
 use crate::script::*;
 
-/// `SetTexCoord(l, r, t, b)` writes the region's UV sub-rect; it surfaces on the extracted quad,
-/// `GetTexCoord` reads it back; the 8-arg affine form carries per-corner UVs (the route-line
-/// draw's rotated quads).
 #[test]
 fn set_tex_coord_changes_extracted_uv() {
     let mut s = script();
@@ -32,14 +29,12 @@ fn set_tex_coord_changes_extracted_uv() {
         tex.content
     );
 
-    // EIGHT values, per corner, in `SetTexCoord`'s own usage order — `ULx, ULy, LLx, LLy, URx,
-    // URy, LRx, LRy` (decision 1840). A Rect stored as `[l, r, t, b]` comes back out as its four
-    // corners, which is the only shape the reference has: there is no 4-value getter.
+    // `GetTexCoord` returns eight values in `SetTexCoord`'s corner order, `ULx, ULy, LLx, LLy,
+    // URx, URy, LRx, LRy`: the reference has no 4-value getter.
     let got: (f32, f32, f32, f32, f32, f32, f32, f32) = s.eval("return t:GetTexCoord()").unwrap();
     assert_eq!(got, (0.1, 0.2, 0.1, 0.8, 0.6, 0.2, 0.6, 0.8));
 
-    // The 8-arg affine form (arg order UL, LL, UR, LR) lands as per-corner UVs in screen order
-    // [TL, TR, BR, BL] — here a 90° rotation of the full texture.
+    // The 8-argument form (UL, LL, UR, LR) lands in screen order [TL, TR, BR, BL]; a 90° turn here.
     s.run("t:SetTexCoord(0,1, 1,1, 0,0, 1,0)").unwrap();
     s.resolve();
     let tex = s
@@ -73,9 +68,6 @@ fn set_tex_coord_changes_extracted_uv() {
     ));
 }
 
-/// `SetFontObject("Name")` copies a registered [`FontObject`]'s face/height/color onto the
-/// FontString; `GetFontObject` hands back the OBJECT (whose `GetName` round-trips); a later call
-/// re-points it (the resolved paint on the extracted quad follows). An unknown name errors.
 #[test]
 fn set_font_object_repoints_fontstring() {
     let mut s = script();
@@ -144,7 +136,6 @@ fn set_font_object_repoints_fontstring() {
         )
     );
 
-    // Re-point.
     s.run("fs:SetFontObject('Small')").unwrap();
     s.resolve();
     assert_eq!(
@@ -156,13 +147,10 @@ fn set_font_object_repoints_fontstring() {
         )
     );
 
-    // An unknown font object errors (never a silent no-op).
     assert!(s.run("fs:SetFontObject('Nope')").is_err());
 }
 
-/// `justifyV`: MIDDLE is the default (the client's own FontString default — what seats the money
-/// numbers on their coins' centerline), `SetJustifyV` overrides it, and a font object carrying one
-/// applies it on `SetFontObject`.
+/// A FontString's `justifyV` defaults to MIDDLE, the client's default.
 #[test]
 fn justify_v_defaults_middle_and_overrides() {
     let mut s = script();
@@ -192,16 +180,9 @@ fn justify_v_defaults_middle_and_overrides() {
     s.resolve();
     assert_eq!(justify_v(&s), JustifyV::Bottom);
 
-    // A font object carrying justify_v applies it — but ONLY on the axis this string has not
-    // already claimed for itself. `SetJustifyV` above severed the V axis, and §5-verified that
-    // severance is permanent: the reference clears the axis's inheritMask bit (`+0x124`, the
-    // per-axis justify mask — wow-re `system/ui/scratch/font-object-lua-surface.md`) and never
-    // restores it, so a later `SetFontObject` cannot take the axis back.
-    //
-    // This assertion used to read `Top`. That was our copy-everything model, not the client's; the
-    // shipped XML path is unaffected either way, because the loader applies `inherits=` BEFORE the
-    // element's own `justifyV=` (`Loader::apply_fontstring_font`), so the explicit attribute still
-    // wins.
+    // A font object's justification applies only on an axis the string has not set itself: a
+    // local setter clears that axis's inherit bit (`+0x124`) for good. XML is unaffected, as the
+    // loader applies `inherits=` before the element's own `justifyV=`.
     s.register_font_object(
         "TopFont",
         FontObject {
@@ -218,7 +199,7 @@ fn justify_v_defaults_middle_and_overrides() {
     s.resolve();
     assert_eq!(justify_v(&s), JustifyV::Bottom, "severance is permanent");
 
-    // A string that never claimed the axis DOES take the object's justification.
+    // A string that never set the axis takes the object's justification.
     s.run(
         r#"
         fresh = f:CreateFontString(nil, "ARTWORK")
diff --git a/crates/benilla-ui/src/script/tests/tooltip.rs b/crates/benilla-ui/src/script/tests/tooltip.rs
index 5fe9616a..dcb24950 100644
--- a/crates/benilla-ui/src/script/tests/tooltip.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip.rs
@@ -1,7 +1,5 @@
-//! The GameTooltip widget's engine mechanics (decision 0274): the line stack + named line
-//! regions, auto-size from the measure round-trip, the right-flush, SetOwner's anchor law +
-//! IsOwned, SetText's implicit show, both AddLine shapes, ClearLines/Hide firing
-//! `OnTooltipCleared`, SetMinimumWidth's floor, and FadeOut's ramp-then-hide.
+//! The GameTooltip widget's engine mechanics: the line stack and its auto-size, `SetOwner`'s
+//! anchor modes, the implicit and gated shows, and the fade.
 
 use super::common::script;
 use crate::script::*;
@@ -22,8 +20,6 @@ fn measure_all(s: &mut UiScript, sizes: &[(&str, f32, f32)]) {
     s.resolve();
 }
 
-/// The full stack: three lines (one double), measured, auto-sized, right-flushed, and the named
-/// line globals published.
 #[test]
 fn line_stack_autosize_and_right_flush() {
     let mut s = script();
@@ -84,16 +80,8 @@ fn line_stack_autosize_and_right_flush() {
     assert_eq!(l2.top, 536.0);
 }
 
-/// An EMPTY line mid-stack (the corpus' `AddLine("")`; the live shape was an empty-string
-/// subtitle from the wire): a ONE-UNIT row that also charges its 2px slot gap. Two fallbacks died
-/// to get here. First the owner-edge one: an empty FontString never measures, so its unpinned
-/// bottom edge fell back to the OWNER frame's bottom (0068's v1 region rule), the line stretched
-/// to the plate's bottom and the anchor chain marched every later line OUT of the plate (the live
-/// NPC-tooltip spill — name inside, "Level 20"/"PvP" below the frame under the health bar). Then
-/// the zero-span collapse that replaced it, which the reference does not have either: its size
-/// getters floor at one FrameXML unit, so `0.0` is not a span a FontString can have (decision
-/// 1664). The row and the plate read that floor off ONE constant, which is what keeps them from
-/// drifting apart the way B309's did.
+/// An empty line is a one-unit row plus its 2 px gap, as the reference's size getters floor a
+/// FontString at one FrameXML unit; the row and the plate read that floor from one constant.
 #[test]
 fn empty_line_is_a_one_unit_row_and_the_chain_stays_inside_the_plate() {
     let mut s = script();
@@ -123,10 +111,7 @@ fn empty_line_is_a_one_unit_row_and_the_chain_stays_inside_the_plate() {
         ],
     );
     // Rows 14 + 1 + 12 + 12 with 3 slot gaps ⇒ totalh 45, height 65; maxw 90 ⇒ width 110.
-    // The blank row is ONE unit, not zero: a FontString's span floors at one FrameXML unit on
-    // both the plate's metric and the line's own rect, from one constant (decision 1664).
-    // (That this row exists at all is a separate open question — on the reference `AddLine("")`
-    // returns without incrementing the line count, wow-re `tooltip-blank-line-height.md` §3.)
+    // The reference's `AddLine("")` returns without adding a line (`0x530270`); ours adds this row.
     s.run(
         r#"
         assert(TTE:GetWidth() == 110, "auto width, got " .. tostring(TTE:GetWidth()))
@@ -145,8 +130,6 @@ fn empty_line_is_a_one_unit_row_and_the_chain_stays_inside_the_plate() {
     assert!(s.take_errors().is_empty());
 }
 
-/// SetOwner clears previous content (firing OnTooltipCleared), owns the frame for IsOwned, and
-/// Hide drops the owner + content and fires OnTooltipCleared again.
 #[test]
 fn owner_clear_and_hide_lifecycle() {
     let mut s = script();
@@ -179,11 +162,9 @@ fn owner_clear_and_hide_lifecycle() {
     assert!(s.take_errors().is_empty());
 }
 
-/// SetText shows the tooltip implicitly (the PaperDoll empty-slot flow calls no Show); AddLine
-/// does not (the corpus' `AddLine … Show()`). The colour law: positional `r, g, b` apply only
-/// when the r-slot is a number — the corpus' archaic `(text, "", r, g, b)` shape has a string
-/// there, so the real 1.12 binding drops the whole colour tail and renders the DEFAULT GOLD
-/// (the reference's zone tooltip, director-matched; the trailing numbers never shift into place).
+/// `SetText` shows the tooltip and `AddLine` does not. `r, g, b` apply only when the r slot is a
+/// number, so `AddLine(text, "", r, g, b)` draws in the default gold, as the reference's zone
+/// tooltip does.
 #[test]
 fn settext_shows_and_both_addline_shapes() {
     let mut s = script();
@@ -228,20 +209,17 @@ fn settext_shows_and_both_addline_shapes() {
             })
             .unwrap_or_else(|| panic!("no quad for {needle}"))
     };
-    // The engine default gold 0xffffd200 (both no-colour shapes land on it).
+    // The default gold `0xffffd200`, where both no-colour shapes land.
     let gold = [1.0, 210.0 / 255.0, 0.0, 1.0];
     assert_eq!(color_of("Zone Name"), gold);
     assert_eq!(color_of("plain gold"), gold);
     assert_eq!(color_of("wrapped tail"), [0.2, 0.4, 0.6, 1.0]);
-    // The partial tail: r gates the block on, missing g/b read as 0.0 (byte-pinned).
+    // A numeric r gates the block on, and a missing g or b reads as 0.
     assert_eq!(color_of("red only"), [1.0, 0.0, 0.0, 1.0]);
     assert!(s.take_errors().is_empty());
 }
 
-/// A tooltip whose lines haven't been measured yet holds its declared size — the gaps alone must
-/// never resolve it to a gaps-only rect (the first cut summed LINE_GAP/DOUBLE_GAP for unmeasured
-/// rows and collapsed a fresh 4-line tooltip to 60×26; caught during the 0274 call-site
-/// migration).
+/// Until its lines are measured, a tooltip keeps its declared size rather than a gaps-only one.
 #[test]
 fn unmeasured_lines_hold_declared_size() {
     let mut s = script();
@@ -260,7 +238,7 @@ fn unmeasured_lines_hold_declared_size() {
     "#,
     )
     .unwrap();
-    // Resolve WITHOUT answering the measure round-trip: the declared 120×32 must hold.
+    // Resolve without answering the measure: the declared 120×32 holds.
     s.resolve();
     s.run(
         r#"
@@ -284,7 +262,6 @@ fn unmeasured_lines_hold_declared_size() {
         .unwrap();
 }
 
-/// SetMinimumWidth floors the auto width (the money row's law), and clears with the content.
 #[test]
 fn minimum_width_floors_autosize() {
     let mut s = script();
@@ -307,8 +284,7 @@ fn minimum_width_floors_autosize() {
         .unwrap();
 }
 
-/// FadeOut ramps the frame alpha down and hides at the end of the ramp (owner + lines dropped,
-/// OnTooltipCleared fired); fresh content mid-fade cancels the ramp at full alpha.
+/// Fresh content mid-fade cancels the ramp at full alpha.
 #[test]
 fn fadeout_ramps_then_hides() {
     let mut s = script();
@@ -342,7 +318,6 @@ fn fadeout_ramps_then_hides() {
         mid_alpha > 0.2 && mid_alpha < 0.8,
         "mid-fade alpha ~0.5, got {mid_alpha}"
     );
-    // Re-content cancels the fade at full alpha.
     s.run(
         r#"
         TT5:SetText("Fresh Hover")
@@ -360,7 +335,7 @@ fn fadeout_ramps_then_hides() {
         })
         .expect("fresh line draws");
     assert_eq!(fresh_alpha, 1.0, "fresh content restored full alpha");
-    // Run a full ramp to the end: hidden + cleared.
+    // A full ramp ends hidden and cleared.
     s.run("TT5:FadeOut()").unwrap();
     s.tick(0.6);
     s.run(
@@ -374,12 +349,8 @@ fn fadeout_ramps_then_hides() {
     assert!(s.take_errors().is_empty());
 }
 
-/// SetOwner's anchor law at the screen edge CLAMPS — the client's geometry-flags-bit4 clamp
-/// (`assemble 0x767a20`, wow-re layout.md), carried by every GameTooltip frame **by
-/// construction** (decision 0352: no tooltip ever leaves the window). The reproduction is the
-/// minimap zone-text hover (MinimapCluster.xml: `ANCHOR_LEFT` on a button at the very top of
-/// the screen — plate bottom-right at the owner's top-left seats it wholly ABOVE the window):
-/// the reference plate hangs DOWN from the screen top instead, size preserved, X untouched.
+/// Every GameTooltip clamps to the screen (the geometry-flags bit 4 clamp, `assemble 0x767a20`), so
+/// the zone text's `ANCHOR_LEFT` (`Minimap.lua:39`) hangs down from the screen top, not above it.
 #[test]
 fn owner_anchored_tooltip_clamps_to_screen() {
     let mut s = script();
@@ -407,8 +378,7 @@ fn owner_anchored_tooltip_clamps_to_screen() {
         ],
     );
     // Auto-size: maxw 120 ⇒ width 140; totalh 14+2+12 ⇒ height 48. Unclamped, the plate's
-    // BOTTOMRIGHT sits at the owner's TOPLEFT (610, 600) — top 648, wholly above the window.
-    // The clamp shifts it back down: top at the screen top, size preserved, X untouched.
+    // BOTTOMRIGHT at the owner's TOPLEFT (610, 600) puts its top at 648.
     s.run(
         r#"
         assert(TTC:GetTop() == 600, "top clamped to the screen top, got " .. TTC:GetTop())
@@ -419,7 +389,7 @@ fn owner_anchored_tooltip_clamps_to_screen() {
     )
     .unwrap();
     s.resolve();
-    // The flag routes: unclamped, the plate returns to the raw anchor law above the window.
+    // Unclamped, the plate goes back above the window.
     s.run(
         r#"
         assert(not TTC:IsClampedToScreen(), "flag readable")
@@ -431,14 +401,11 @@ fn owner_anchored_tooltip_clamps_to_screen() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `0x52fa50`'s ladder as pure logic (law §3-BUFF-TIME-FORMAT) — the arm thresholds, the
-/// ceil/truncate asymmetry, and the `_P1` pick — over SYNTHETIC templates, so this asserts the
-/// mechanism and carries none of the reference's own eight strings. The real ones are read off the
-/// player's install and exercised in `benilla::ui_script::buff_tests`.
+/// `0x52fa50`'s duration ladder over stand-in templates: the arm edges, the ceiling on every arm
+/// but seconds, and the `_P1` plural pick.
 #[test]
 fn the_duration_ladder_ceils_every_arm_but_seconds() {
-    // Deliberately not the shipped wording: what is under test is which key is reached and what
-    // number fills it, never what the string says.
+    // Not the shipped wording: the test is which key is reached and what number fills it.
     let table = |key: &str| -> Option<String> {
         Some(
             match key {
@@ -457,8 +424,7 @@ fn the_duration_ladder_ceils_every_arm_but_seconds() {
     };
     let d = |ms: u32| crate::script::tooltip::duration_text(ms, "T", true, &table);
 
-    // The three arm boundaries, from the compare instructions — each is exact, and the arm below
-    // it counts in its own unit right up to the edge.
+    // The three arm edges are exact, and the arm below counts in its own unit up to the edge.
     assert_eq!(d(86_400_000).as_deref(), Some("<1 day>"), "the day edge");
     assert_eq!(
         d(86_399_999).as_deref(),
@@ -469,17 +435,16 @@ fn the_duration_ladder_ceils_every_arm_but_seconds() {
     assert_eq!(
         d(3_599_999).as_deref(),
         Some("<60 mins>"),
-        "the carve's own example: no '1 hour' until the hour is whole"
+        "the worked example: no '1 hour' until the hour is whole"
     );
     assert_eq!(d(60_000).as_deref(), Some("<1 min>"), "the minute edge");
     assert_eq!(
         d(61_000).as_deref(),
         Some("<2 mins>"),
-        "the carve's own example: 61 s ceils to 2, it does not truncate to 1"
+        "the worked example: 61 s ceils to 2, it does not truncate to 1"
     );
 
-    // The asymmetry that makes this one function rather than four format calls: roundUp reaches
-    // the top three arms only.
+    // roundUp reaches the top three arms only.
     assert_eq!(
         d(59_999).as_deref(),
         Some("<59 secs>"),
@@ -498,18 +463,18 @@ fn the_duration_ladder_ceils_every_arm_but_seconds() {
         "exactly one is singular"
     );
 
-    // roundUp = 0 truncates the top arms too (the parameter is real, not a constant we folded).
+    // roundUp = 0 truncates the top arms too.
     assert_eq!(
         crate::script::tooltip::duration_text(61_000, "T", false, &table).as_deref(),
         Some("<1 min>"),
     );
 
-    // A key the string table does not carry yields NO LINE rather than an invented one.
+    // A key the string table lacks yields no line.
     assert_eq!(
         crate::script::tooltip::duration_text(1_000, "NOPE", true, &table),
         None
     );
-    // …and a family shipping only the singular falls back to it rather than vanishing.
+    // A family with only the singular falls back to it.
     let singular_only = |key: &str| (key == "S_SEC").then(|| "<%d s>".to_string());
     assert_eq!(
         crate::script::tooltip::duration_text(5_000, "S", true, &singular_only).as_deref(),
@@ -517,20 +482,9 @@ fn the_duration_ladder_ceils_every_arm_but_seconds() {
     );
 }
 
-/// **B309 — a POOLED line cell that goes empty must not keep the box it measured last hover.**
-///
-/// `measured` is a cache the solver honours without a key check on purpose: it is the last-known
-/// box, held so a line whose text just changed does not collapse for the frame its re-measure is
-/// in flight. Empty text is the one case where that measure never comes — both measure asks
-/// filter empty strings out — so before the fix an emptied cell held its dead box FOREVER, and
-/// only the DRAWN geometry was wrong: the plate's own sum calls empty text zero
-/// (`tooltip::cell`) and the Lua getters key-check (`region::measured_wh`), so both said 0 while
-/// the solver stood a full row there.
-///
-/// Live, that is the item tooltip's SET block: `ClearLines` keeps the cache (the hover re-enter
-/// loop depends on it), so the two blank gold spacers land on cells that carried real text on an
-/// earlier hover. Each drew an uncounted row and the set bonuses hung below the backdrop —
-/// Frostshake's Field Marshal's Raiment shot, two blanks, two rows.
+/// The solver keeps a line's last measured box, unkeyed, while a re-measure is in flight, and an
+/// empty line is never measured, so a pooled cell that goes empty must drop its old box: the item
+/// tooltip's set block puts blank spacers on cells that held text.
 #[test]
 fn an_emptied_pooled_line_drops_its_stale_box_and_the_plate_still_contains_the_chain() {
     let mut s = script();
@@ -556,13 +510,12 @@ fn an_emptied_pooled_line_drops_its_stale_box_and_the_plate_still_contains_the_c
         ("PvP", 24.0, 12.0),
     ];
     measure_all(&mut s, sizes);
-    // Hover two, SAME pooled cells: line 2 is now the blank spacer. Nothing new to measure —
-    // lines 1 and 3 re-validate against their own keys, and an empty string is never asked for.
+    // Hover two, same pooled cells: line 2 is now the blank spacer, which is never measured.
     s.run(
         r#"
         TTR:ClearLines()
         TTR:AddLine("Marshal McBride")
-        -- WRAPPED, as the §22 spacer is (`render.rs`'s `addw`): the wrap pin writes a non-zero
+        -- WRAPPED, as the set spacer is (`render.rs`'s `addw`): the wrap pin writes a non-zero
         -- width into `size`, so only the HEIGHT falls through to the measure cache.
         TTR:AddLine("", 1, 0.82, 0, true)
         TTR:AddLine("PvP")
@@ -590,22 +543,11 @@ fn an_emptied_pooled_line_drops_its_stale_box_and_the_plate_still_contains_the_c
     assert!(s.take_errors().is_empty());
 }
 
-/// **`SetOwner`'s omitted `anchorType` is mode 0 = ANCHOR_LEFT**, and the clear-vs-keep split runs
-/// between NONE and PRESERVE, not between "points" and "doesn't".
-///
-/// 2142's open thread 1 predicted the opposite on both counts — a mode-7 default, and a NONE arm
-/// that must stop dropping anchors — and the wow-re §5 dispatched for the CURSOR mechanism refuted
-/// both at the bytes (`system/ui/scratch/tooltip-cursor-anchor-law.md` §0.2/§0.3/§2; decision
-/// 2176). What is actually there:
-///
-/// * `0x53120d` zeroes the binding's local mode before any compare, and `0x531214`'s
-///   `lua_isstring` gate jumps the whole `SStrCmpI` chain when arg 3 is absent, nil, a boolean or
-///   a table — so the answer is **0 = ANCHOR_LEFT**, silently, with no `luaL_error` anywhere in
-///   `[0x531221, 0x53133a)`. The core's `mov [+0x318],7` at `0x530012` is an unconditional
-///   pre-store `0x530031` overwrites; it survives only when the owner is NULL.
-/// * `0x52fe90` returns for mode **8** at `0x52fead`, *before* `0x52fec2 call 0x767ed0`, and the
-///   mode-7 skip beside that clear is gated on an arg1 `SetOwner`'s core always passes as 1. So
-///   every mode 0..7 clears, and only PRESERVE keeps the placement.
+/// An omitted `anchorType` is mode 0, ANCHOR_LEFT: `0x53120d` zeroes the local, the `lua_isstring`
+/// gate at `0x531214` skips the compare chain, and nothing in `[0x531221, 0x53133a)` raises. The
+/// core's pre-store of mode 7 (`0x530012`) survives only a NULL owner (`0x530031`). `0x52fe90`
+/// returns for mode 8 (`0x52fead`) before its clear (`0x52fec2 call 0x767ed0`), and `SetOwner`
+/// always passes the arg that gates mode 7's skip as 1, so only ANCHOR_PRESERVE keeps the points.
 #[test]
 fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
     let mut s = script();
@@ -624,7 +566,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
     s.resolve();
     assert_eq!(s.eval::<f32>("return Plate:GetLeft()").unwrap(), 100.0);
 
-    // ANCHOR_PRESERVE (mode 8) is the ONE mode that leaves the plate alone.
+    // ANCHOR_PRESERVE (mode 8) is the one mode that leaves the plate alone.
     s.run(r#"Plate:SetOwner(Owner, "ANCHOR_PRESERVE")"#)
         .unwrap();
     s.resolve();
@@ -635,7 +577,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
     );
     assert_eq!(s.eval::<i64>("return Plate:GetNumPoints()").unwrap(), 1);
 
-    // ANCHOR_NONE (mode 7) clears — which is what makes `GameTooltip_SetDefaultAnchor` safe.
+    // ANCHOR_NONE (mode 7) clears, which `GameTooltip.lua:73`'s default anchor relies on.
     s.run(r#"Plate:SetOwner(Owner, "ANCHOR_NONE")"#).unwrap();
     assert_eq!(
         s.eval::<i64>("return Plate:GetNumPoints()").unwrap(),
@@ -643,8 +585,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
         "mode 7 reaches the clear: arg1 is always 1 from SetOwner's core"
     );
 
-    // `SetOwner(f)` — no anchor string at all. Mode 0, and mode 0 PLACES: ANCHOR_LEFT pins the
-    // plate's BOTTOMRIGHT to the owner's TOPLEFT, so its right edge sits at the owner's left.
+    // No anchor string: mode 0 places the plate's BOTTOMRIGHT at the owner's TOPLEFT.
     s.run(r#"Plate:SetPoint("BOTTOMLEFT", nil, "BOTTOMLEFT", 100, 100)"#)
         .unwrap();
     s.run("Plate:SetOwner(Owner)").unwrap();
@@ -660,8 +601,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
         "the owner's left edge (300) less the plate's own 50 wide"
     );
 
-    // An UNRECOGNISED string is the same silent mode 0 — the compare chain falls through with the
-    // local untouched, and raises nothing.
+    // An unrecognised string falls through the compare chain: the same silent mode 0.
     s.run(r#"Plate:SetOwner(Owner, "ANCHOR_SIDEWAYS")"#)
         .unwrap();
     assert_eq!(
@@ -670,11 +610,7 @@ fn set_owner_defaults_to_anchor_left_and_only_preserve_keeps_the_placement() {
     );
 }
 
-/// **`SetAlpha(255)` on SetOwner is UNCONDITIONAL** — `0x52fff4`, the first thing the SetOwner
-/// core `0x52ffe0` does, before its five stores (wow-re `system/ui/ledger.tsv` row `0x52ffe0`,
-/// verified). Ours only ever restored the alpha one of OUR OWN fades had taken away, so a plate
-/// left dim by any other path — an addon's `SetAlpha`, an inherited parent alpha — stayed dim
-/// through every subsequent hover, where the reference stamps it back to full on each SetOwner.
+/// The `SetOwner` core `0x52ffe0` first sets alpha 255 (`0x52fff4`), whatever dimmed the plate.
 #[test]
 fn set_owner_stamps_full_alpha_even_with_no_fade_running() {
     let s = script();
@@ -695,20 +631,9 @@ fn set_owner_stamps_full_alpha_even_with_no_fade_running() {
     .unwrap();
 }
 
-/// **`Show` is an EXISTENCE GATE, not a plain show** — `0x530a80`, the CGameTooltip override of
-/// `vtbl+0x88` (the slot a Lua `:Show()` lands in). It shows only when BOTH the owner `+0x314`
-/// and the line count `+0x31c` are non-zero, and otherwise calls its own `vtbl+0x84`
-/// effective-hide `0x530a60` — the SetOwner core with a NULL owner, so the plate is hidden AND
-/// un-owned (wow-re `system/ui/ledger.tsv` row `0x530a80`, verified;
-/// `scratch/hover-hide-and-tooltip-owner-law.md` §4).
-///
-/// The symptom that found it: `Questie`'s tracker draws an EMPTY plate on hover — correctly
-/// sized and bordered, with no text. `QuestieTracker.lua`'s quest-button OnEnter has a dead zone
-/// between its two arms (an in-progress quest that has objectives AND whose objective text is in
-/// the Questie database matches neither), so it adds no line and then calls `Tooltip:Show()`
-/// unconditionally. The reference swallows that; we drew it — and, because `layout_tooltips`
-/// skips a zero-line plate instead of collapsing it, we drew it at the LAST hover's size, which
-/// is why it looked like a real tooltip with the text missing rather than a stub.
+/// `Show` (`0x530a80`, the `vtbl+0x88` override) shows only with an owner (`+0x314`) and a line
+/// (`+0x31c`); otherwise it calls `0x530a60` (`vtbl+0x84`), the `SetOwner` core with a NULL owner,
+/// which hides and un-owns. `QuestieTracker.lua`'s OnEnter can call `Show` with no line.
 #[test]
 fn show_with_no_lines_self_hides_and_un_owns() {
     let mut s = script();
@@ -728,8 +653,7 @@ fn show_with_no_lines_self_hides_and_un_owns() {
     )
     .unwrap();
 
-    // Questie's exact shape: the re-hover's SetOwner clears the content, the handler's dead zone
-    // adds nothing, and Show() runs anyway.
+    // Questie's shape: a re-hover's `SetOwner` clears the lines, nothing is added, `Show` runs.
     s.run(
         r#"
         Tip:SetOwner(Owner, "ANCHOR_RIGHT")
@@ -741,7 +665,7 @@ fn show_with_no_lines_self_hides_and_un_owns() {
     )
     .unwrap();
 
-    // The other half of the gate, on its own: a line but no owner is equally not shown.
+    // A line but no owner is the other half of the gate.
     s.run(
         r#"
         Tip:AddLine("Orphan", 1, 1, 1)
@@ -752,21 +676,9 @@ fn show_with_no_lines_self_hides_and_un_owns() {
     .unwrap();
 }
 
-/// **A NON-STRING anchor argument must not raise** — and for a year it did, because the binding
-/// took arg 3 as `Option<String>` and let mlua's converter be the gate.
-///
-/// The reference's gate is `lua_isstring 0x6f3510`, whose entire body is `lua_type` then
-/// `cmp eax,4 / cmp eax,3`: LUA_TSTRING or LUA_TNUMBER pass and are read by coercion, and every
-/// other tag takes `0x53121b je 0x53133a` over the whole compare chain to the join, leaving the
-/// zeroed local — mode 0, `ANCHOR_LEFT`, silently, with no `luaL_error` anywhere in
-/// `[0x531221, 0x53133a)` (wow-re `system/ui/scratch/tooltip-cursor-anchor-law.md` §0.2, the same
-/// section decision 2176 already quotes in this file's doc comments). So a boolean, a table, a
-/// function and absent are *indistinguishable* at this position.
-///
-/// The symptom that found it: `Questie` hovers a world-map note with
-/// `Tooltip:SetOwner(this, this)` (`QuestieNotes.lua` `Questie_Tooltip_OnEnter`) — a frame where
-/// the anchor goes — and got `bad argument #3: error converting Lua table to String` where the
-/// reference draws the tooltip.
+/// `lua_isstring 0x6f3510` passes only a string or a number; any other tag jumps the compare chain
+/// (`0x53121b je 0x53133a`) to mode 0 and raises nothing. `QuestieNotes.lua` passes a frame here
+/// (`SetOwner(this, this)`).
 #[test]
 fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
     let s = script();
@@ -778,7 +690,7 @@ fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
     )
     .unwrap();
 
-    // A TABLE — Questie's own call shape, a frame passed where the anchor string goes.
+    // A table, as Questie passes.
     s.run("Plate:SetOwner(Owner, Owner)")
         .expect("a table anchor takes the isstring gate's jump, it does not raise");
     assert_eq!(
@@ -786,7 +698,7 @@ fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
         "ANCHOR_LEFT"
     );
 
-    // A BOOLEAN and an explicit nil are the same jump.
+    // A boolean and an explicit nil take the same jump.
     for arg in ["true", "false", "nil"] {
         s.run(&format!(
             r#"Plate:SetOwner(Owner, "ANCHOR_RIGHT") Plate:SetOwner(Owner, {arg})"#
@@ -799,8 +711,7 @@ fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
         );
     }
 
-    // A NUMBER is the one non-string tag the gate DOES admit: it is stringified and run through
-    // the chain, which no number can match — the same mode 0, by the other route.
+    // A number passes the gate as a string that matches no mode: mode 0 again.
     s.run(r#"Plate:SetOwner(Owner, "ANCHOR_RIGHT") Plate:SetOwner(Owner, 5)"#)
         .unwrap();
     assert_eq!(
@@ -809,11 +720,8 @@ fn a_non_string_anchor_is_silently_mode_zero_and_never_raises() {
     );
 }
 
-/// **`ANCHOR_CURSOR` is a real ninth mode**, not a string to warn about (2142's open thread 2, and
-/// nine corpus files ask for it): mode 6 clears at `SetOwner` time like mode 7, and then the
-/// per-frame update `0x530b20` pins the plate's **BOTTOM** to the screen's **BOTTOMLEFT** at the
-/// cursor's absolute position, divided by the plate's own effective scale. See
-/// `script::tooltip::cursor_anchor`.
+/// `ANCHOR_CURSOR`, mode 6, clears at `SetOwner` like mode 7; the per-frame update `0x530b20` then
+/// pins the plate's BOTTOM to the screen's BOTTOMLEFT at the cursor, over its effective scale.
 #[test]
 fn anchor_cursor_follows_the_cursor_every_frame() {
     let mut s = script();
@@ -854,7 +762,7 @@ fn anchor_cursor_follows_the_cursor_every_frame() {
         "centred horizontally on the cursor: {left}..{right}"
     );
 
-    // It follows. The whole point of mode 6 is that no second SetOwner is needed.
+    // It follows the cursor with no second `SetOwner`.
     s.mouse_move(120.0, 480.0);
     s.resolve();
     let (left, right, bottom): (f32, f32, f32) = s
@@ -867,14 +775,8 @@ fn anchor_cursor_follows_the_cursor_every_frame() {
     );
 }
 
-/// `GameTooltip:GetAnchorType()` — ONE string, the reference's own spelling, round-tripping
-/// whatever `SetOwner` was given (`0x5313e0`, table `0x854198`, argc 1, arity 1, kinds `(string)`,
-/// reading `[+0x318]` back through the name table `0x531530`).
-///
-/// The round trip is the whole point rather than a nicety: `_Nameplates/_Nameplates.lua:479` is
-/// `if GameTooltip:GetAnchorType() ~= Anchor then GameTooltip:SetOwner(Column, Anchor) end`, so an
-/// answer that never equals what the setter was handed would re-own the plate every OnUpdate; and
-/// `pfUI/modules/tooltip.lua:97` compares against the literal `"ANCHOR_NONE"`.
+/// `GetAnchorType` (`0x5313e0`, table `0x854198`) answers one string, `[+0x318]` through the name
+/// table `0x531530`; `_Nameplates.lua:479` compares it with what it passed to `SetOwner`.
 #[test]
 fn tooltip_anchor_type_round_trips_every_reachable_mode() {
     let s = script();
@@ -886,8 +788,7 @@ fn tooltip_anchor_type_round_trips_every_reachable_mode() {
     )
     .unwrap();
 
-    // Arity 1, kind string, and NO nil leg — the shapes row is `(string)` with no alternative, so
-    // a plate nobody has owned still answers a string.
+    // Never nil: a plate nobody has owned answers a string too.
     assert_eq!(s.arity("AnchorTip:GetAnchorType()").unwrap(), 1, "arity 1");
     assert_eq!(
         s.eval::<String>("return type(AnchorTip:GetAnchorType())")
@@ -902,8 +803,7 @@ fn tooltip_anchor_type_round_trips_every_reachable_mode() {
         "a plate nothing has owned is anchored to nothing"
     );
 
-    // All NINE modes SetOwner accepts, each answered back verbatim — ANCHOR_PRESERVE included,
-    // which the reference stores like any other rather than resolving back to what it preserved.
+    // All nine modes round-trip, ANCHOR_PRESERVE included: the reference stores it like any other.
     for mode in [
         "ANCHOR_RIGHT",
         "ANCHOR_LEFT",
@@ -925,7 +825,7 @@ fn tooltip_anchor_type_round_trips_every_reachable_mode() {
         );
     }
 
-    // Lower case in, the reference's canonical spelling out — SetOwner already folds the token.
+    // Lower case in, the canonical spelling out.
     s.run(r#"AnchorTip:SetOwner(AnchorOwner, "anchor_left")"#)
         .unwrap();
     assert_eq!(
@@ -934,9 +834,8 @@ fn tooltip_anchor_type_round_trips_every_reachable_mode() {
         "ANCHOR_LEFT"
     );
 
-    // An anchor SetOwner does not recognise is the binding's zero-initialised local, mode 0 —
-    // silently, with no raise (`0x53120d`, and no `luaL_error` in the compare chain). Ours adds a
-    // warning the reference does not have, which is a diagnostic and not API surface.
+    // An unrecognised anchor is mode 0, with no raise (`0x53120d`). Deviation: we also log a
+    // warning so the unknown token shows up in diagnostics; no addon can see it.
     s.run(r#"AnchorTip:SetOwner(AnchorOwner, "ANCHOR_SIDEWAYS")"#)
         .unwrap();
     assert_eq!(
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/bindings.rs b/crates/benilla-ui/src/script/tests/tooltip_item/bindings.rs
index c73eb0b8..eb305d82 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/bindings.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/bindings.rs
@@ -1,22 +1,16 @@
-//! The Set* entry points: the vendor compare's CURRENTLY_EQUIPPED shape,
-//! SetInventoryItem outside compare, and SetHyperlink's item-link filter.
+//! The `Set*` entry points: the vendor compare, `SetInventoryItem` outside it, `SetHyperlink`'s
+//! item filter, and the tradeskill and merchant-compare row indexing.
 
 use std::collections::HashMap;
 
 use super::script;
 use crate::script::*;
 
-/// The compare SHAPE, driven the only way 1.12.1 drives it: the vendor row's
-/// `SetMerchantCompareItem` (`MerchantFrame.xml:63-80`). The armed render is the equipped item's
-/// ORDINARY tooltip plus ONE line, first — the gray CURRENTLY_EQUIPPED header (p5). Both compare
-/// call sites pass p4 (compact) ZERO, so the two things that are easy to get wrong here are
-/// pinned as negatives: the name keeps its QUALITY color (this worn ring is epic, so the assert
-/// bites), and nothing is cut at `0x52e14c` — the description still prints (2216).
-///
-/// **And the negative control that keeps this engine out of it** (2210): a bag hover seats
-/// nothing, with shift or without, because the reference has no hover compare at all —
-/// `SHOW_COMPARE_TOOLTIP` has zero fire sites in 5875, so nothing may reach a listener for it
-/// either. The plates belong to whatever FrameXML raises them, and this engine raises none.
+/// The compare as 1.12.1 drives it, from the vendor row's `SetMerchantCompareItem`
+/// (`MerchantFrame.xml:63-80`): the worn item's ordinary tooltip under a gray
+/// `CURRENTLY_EQUIPPED` header (p5). Both callers pass p4 zero, so the name keeps its quality
+/// colour and nothing is cut at `0x52e14c`. A bag hover seats no plate, shift or not:
+/// `SHOW_COMPARE_TOOLTIP` has no fire site in the reference.
 #[test]
 fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
     let mut s = script();
@@ -26,8 +20,7 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
         durability: None,
         item_id: 7000,
         name: Some("Old Loop".into()),
-        // EPIC — a white name and a quality name are the same pixel at quality 1, which is how
-        // the conflated flag survived a green test for as long as it did.
+        // Epic: at quality 1 a white name and a quality name are the same pixel.
         quality: 4,
         ..Default::default()
     });
@@ -98,8 +91,7 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
             slots,
         }),
     );
-    // The plates are ordinary GameTooltip frames the FrameXML owns — the engine knows nothing
-    // about them (`ShoppingTooltip` does not occur in the image at all).
+    // The plates are ordinary GameTooltips the FrameXML owns; the reference never names them.
     s.run(
         r#"
         local a = CreateFrame("Button", "Slot"); a:SetPoint("LEFT", 0, 0); a:SetWidth(10); a:SetHeight(10)
@@ -108,7 +100,7 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
         CreateFrame("GameTooltip", "ShoppingTooltip1"):Hide()
         CreateFrame("GameTooltip", "ShoppingTooltip2"):Hide()
         -- A ref-shaped SHOW_COMPARE_TOOLTIP listener, kept as the NEGATIVE control: 5875 never
-        -- signals event 377 (zero fire sites, wow-re merchant-compare-item-law.md §8), so nothing
+        -- signals event 377 (zero fire sites in the whole image), so nothing
         -- benilla does may reach this handler.
         compare_calls = {}
         local watcher = CreateFrame("Frame", "CompareWatcher")
@@ -175,7 +167,6 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
     "#,
     )
     .unwrap();
-    // The compare colors: gray header, and the name in its own QUALITY color — the byte law.
     s.resolve();
     let quads = s.extract();
     let color_of = |txt: &str| {
@@ -206,16 +197,11 @@ fn merchant_compare_renders_the_compare_shape_and_no_hover_seats_a_plate() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **`nameOnly`** — `SetInventoryItem`'s optional third argument, p4 of the builder, and the ONLY
-/// door onto the compact render in 1.12.1 (wow-re `ui/scratch/tooltip-nameonly-p4-census.md`: 27
-/// of 31 call sites pass a provable zero, one forwards, and the three that carry a flag are all
-/// this binding's). No stock FrameXML caller passes it — all 8 stock call sites are
-/// two-argument — so this is addon surface, and it is live code, not a dead arm.
-///
-/// The mode is **trimmed, not bare**, and that is the half a plausible implementation gets wrong:
-/// two non-contiguous cuts plus an early return. Gone: the bind/lock region, the whole stat body,
-/// and everything past the cooldown line. Kept: the name (white), the slot/type cell, durability,
-/// every requirement line and the spell triggers.
+/// `SetInventoryItem`'s third argument, `nameOnly`, is the builder's p4 and the one way to the
+/// compact render: of `0x52b650`'s 31 call sites, 27 pass zero, one forwards and three are this
+/// binding's, and no stock caller passes it. The render is trimmed, not bare: the bind and lock
+/// lines, the stat body and everything past the cooldown line go; the white name, the slot and
+/// type cell, durability, the requirements and the spell triggers stay.
 #[test]
 fn set_inventory_item_name_only_is_the_trimmed_build() {
     let mut s = script();
@@ -237,9 +223,7 @@ fn set_inventory_item_name_only_is_the_trimmed_build() {
             class: 2,
             subclass: 7,
             inventory_type: 13,
-            // One line from each of the three regions p4 treats differently: CONJURED / the bind
-            // line / UNIQUE / LOCKED are CUT, ARMOR is CUT, and the type cell, durability, the
-            // level requirement and the trigger all SURVIVE.
+            // A line from each region p4 treats differently.
             flags: 0x2,
             bonding: 1,
             max_count: 1,
@@ -312,8 +296,7 @@ fn set_inventory_item_name_only_is_the_trimmed_build() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `SetInventoryItem` outside a compare: the FULL line law (quality name, description — no cut),
-/// return 1 on an occupied slot, nil on empty/foreign units.
+/// Outside a compare: the full render, 1 for an occupied slot, nil for an empty or foreign one.
 #[test]
 fn set_inventory_item_renders_full_outside_compare() {
     let mut s = script();
@@ -377,8 +360,6 @@ fn set_inventory_item_renders_full_outside_compare() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `SetHyperlink`: the full escaped chat link and the bare `item:` form both render through the
-/// shared law; non-item links no-op without touching the current content.
 #[test]
 fn set_hyperlink_renders_items_and_ignores_other_links() {
     let mut s = script();
@@ -410,8 +391,7 @@ fn set_hyperlink_renders_items_and_ignores_other_links() {
     assert!(s.take_errors().is_empty());
 }
 
-/// One tradeskill recipe fixture — the product id is `spell_id + 10_000`, so the tooltip's own
-/// name names which recipe the channel actually landed on.
+/// A recipe whose product id is `spell_id + 10_000`, so the tooltip's name shows which row it hit.
 fn ts_recipe(spell_id: u32, name: &str, group: (u32, u32, &str)) -> TradeSkillRecipe {
     TradeSkillRecipe {
         group: Some((group.0, group.1, group.2.to_string())),
@@ -437,13 +417,8 @@ fn ts_recipe(spell_id: u32, name: &str, group: (u32, u32, &str)) -> TradeSkillRe
     }
 }
 
-/// `SetTradeSkillItem`'s index is a **VISIBLE** row index, not a position in `recipes` — headers
-/// interleave with rows, so the two differ the moment any group precedes the recipe. This is the
-/// exact mis-index the tradeskill module doc once carried as a known gap: with one header above it,
-/// visible row 4 is the SECOND group's recipe, and a raw `recipes[4-1]` lookup would land on the
-/// first group's second recipe instead. Both the product channel and the reagent channel are
-/// pinned, since the detail-icon and reagent-slot hovers are the two callers that pass a genuine
-/// visible index straight through. A HEADER row is a no-op, not a shifted hit.
+/// `SetTradeSkillItem` takes a visible row index, headers included, not a position in `recipes`;
+/// the product and reagent hovers both pass one, and a header row is a no-op.
 #[test]
 fn set_trade_skill_item_indexes_visible_rows_not_raw_recipes() {
     let mut s = script();
@@ -468,11 +443,7 @@ fn set_trade_skill_item_indexes_visible_rows_not_raw_recipes() {
     }));
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 6);
 
-    // Visible row 5 is "Alpha Cloak" (spell 4) — its product is 10_004. A raw recipes[5-1] lookup
-    // would land on recipe index 4 (out of range, a silent no-op); recipes[4-1] on "Beta Cloak".
-    // `TTTextLeft1` need not exist when a call renders nothing (what an out-of-range RAW index
-    // does), so read it defensively — that case must surface as an assert_eq naming the row, not
-    // as a Lua nil-index panic three lines away from the claim.
+    // `TTTextLeft1` may not exist when nothing renders, so it is read defensively.
     let name_at = |s: &mut UiScript, row: i64, reagent: &str| -> String {
         s.run(&format!("TT:SetTradeSkillItem({row}{reagent})"))
             .unwrap();
@@ -483,26 +454,20 @@ fn set_trade_skill_item_indexes_visible_rows_not_raw_recipes() {
     assert_eq!(name_at(&mut s, 6, ""), "Beta Cloak");
     assert_eq!(name_at(&mut s, 2, ""), "Alpha Bolt");
 
-    // The reagent channel takes the same mapping.
     assert_eq!(name_at(&mut s, 5, ", 1"), "Alpha Cloak Reagent");
 
-    // A header row resolves to nothing — the hover is a no-op, so the previous render stands
-    // rather than a neighbouring recipe's tooltip appearing under the cursor.
+    // A header row is a no-op: the previous render stands.
     assert_eq!(name_at(&mut s, 4, ""), "Alpha Cloak Reagent");
 }
 
-/// `SetMerchantCompareItem(index [, offset])` — the shopping tooltip the stock vendor row raises.
-///
-/// The contract that decides ghost tooltips versus none is the RETURN, so that is what this pins:
-/// the **number** 1 on success, `nil` on every failure, one value always. Stock's
-/// `if ( ShoppingTooltip1:SetMerchantCompareItem(id, 1) ) then … end` reads it directly, so a
-/// boolean `false` where nil belongs shows an empty tooltip and a truthy nil-case shows two.
+/// `SetMerchantCompareItem(index [, offset])` returns the number 1 or nil, one value, and the stock
+/// vendor row shows each plate on it (`MerchantFrame.xml:67`).
 #[test]
 fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
 
-    // Both finger slots worn, both class 4 (ARMOR) like the ring on the shelf.
+    // Both finger slots worn, class 4 (armor) like the ring on the shelf.
     let mut inv: InventorySlots = Default::default();
     for (slot, id, name) in [(11usize, 7000u32, "Old Loop"), (12, 7001, "Older Loop")] {
         inv[slot] = Some(InvSlotView {
@@ -522,7 +487,7 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             },
         );
     }
-    // …and a shield, class 4, in the off hand — the case that makes offset 2 nil for a WEAPON.
+    // A shield, class 4, in the off hand makes offset 2 nil for a weapon.
     inv[17] = Some(InvSlotView {
         item_id: 7100,
         name: Some("Battered Buckler".into()),
@@ -571,7 +536,7 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             },
             MerchantItem {
                 name: Some("Unseen Thing".into()),
-                item_id: 8999, // no template — the uncached leg
+                item_id: 8999, // no template: the uncached leg
                 ..Default::default()
             },
         ],
@@ -583,7 +548,7 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             name: "Shiny Loop".into(),
             quality: 3,
             class: 4,
-            inventory_type: 11, // finger — two candidate slots
+            inventory_type: 11, // finger: two candidate slots
             ..Default::default()
         },
     );
@@ -593,13 +558,11 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             name: "Sharp Sword".into(),
             quality: 3,
             class: 2,
-            inventory_type: 13, // one-hand — main hand then off hand
+            inventory_type: 13, // one-hand: main hand, then off hand
             ..Default::default()
         },
     );
 
-    // The two shopping tooltips are ordinary GameTooltip frames — the engine knows nothing about
-    // them (the substring `ShoppingTooltip` does not occur in the image at all).
     s.run(
         r#"
         CreateFrame("GameTooltip", "ShoppingTooltip1"):Hide()
@@ -611,7 +574,6 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
     let call =
         |s: &mut UiScript, expr: &str| s.eval::<String>(&format!("return type({expr})")).unwrap();
 
-    // A ring against two worn rings: both offsets answer, and the answer is the NUMBER 1.
     assert_eq!(
         s.eval::<String>(r#"return tostring(ShoppingTooltip1:SetMerchantCompareItem(1, 1))"#)
             .unwrap(),
@@ -622,7 +584,6 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
         call(&mut s, "ShoppingTooltip2:SetMerchantCompareItem(1, 2)"),
         "number"
     );
-    // …and it filled with the WORN item, headed by the gray compare line.
     assert!(
         s.eval::<bool>(
             r#"local n = ShoppingTooltip1:NumLines()
@@ -637,9 +598,7 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
         "the fill is the equipped item's own tooltip with the CURRENTLY_EQUIPPED header"
     );
 
-    // A one-hand weapon: main hand matches (class 2), the off-hand SHIELD does not (class 4), so
-    // offset 2 is nil. This is the reference's class test doing the work, and it is the case a
-    // slot-only reading would get wrong.
+    // A one-hand weapon: the main hand (class 2) matches, the off-hand shield (class 4) does not.
     assert_eq!(
         call(&mut s, "ShoppingTooltip1:SetMerchantCompareItem(2, 1)"),
         "number"
@@ -650,12 +609,12 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
         "a shield is not a candidate for a weapon — class, not slot"
     );
 
-    // Offset defaults to 1 when absent, and does NOT raise.
+    // An absent offset is 1, not a raise.
     assert_eq!(
         call(&mut s, "ShoppingTooltip1:SetMerchantCompareItem(1)"),
         "number"
     );
-    // An explicit 0 or a negative is nil — the counter starts below zero and only decrements.
+    // An offset of 0 or less is nil: the counter starts below zero and only decrements.
     for bad in ["0", "-1"] {
         assert_eq!(
             call(
@@ -666,7 +625,6 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
             "offset {bad}"
         );
     }
-    // Out of range, and the uncached template, are both nil — never an error.
     for expr in [
         "ShoppingTooltip1:SetMerchantCompareItem(0, 1)",
         "ShoppingTooltip1:SetMerchantCompareItem(99, 1)",
@@ -674,20 +632,18 @@ fn set_merchant_compare_item_answers_one_or_nil_per_candidate_slot() {
     ] {
         assert_eq!(call(&mut s, expr), "nil", "{expr}");
     }
-    // 2.7 re-bases in f64 and THEN truncates: 2.7 - 1 = 1.7 -> row 1, the sword. Doing it the
-    // other way round would land on row 2.
+    // 2.7 re-bases in f64, then truncates: 1.7 is row 1, the sword.
     assert_eq!(
         call(&mut s, "ShoppingTooltip1:SetMerchantCompareItem(2.7, 1)"),
         "number"
     );
 
-    // A non-number index RAISES, with the client's own usage text.
     let e = s
         .run(r#"ShoppingTooltip1:SetMerchantCompareItem({}, 1)"#)
         .unwrap_err()
         .to_string();
     assert!(e.contains("Usage: SetMerchantCompareItem"), "{e}");
-    // …but a numeric STRING is a number to `lua_isnumber`.
+    // A numeric string passes `lua_isnumber`.
     assert_eq!(
         call(&mut s, r#"ShoppingTooltip1:SetMerchantCompareItem("1", 1)"#),
         "number"
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/law.rs b/crates/benilla-ui/src/script/tests/tooltip_item/law.rs
index 9fb0ede7..cc0ca698 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/law.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/law.rs
@@ -1,14 +1,11 @@
-//! The emission-order law and the red requirement checks: the verified line families, the
-//! player-state-tracked reds (level/class/rep), and the slot|type cells' independent
-//! proficiency reds (hard miss on TYPE; alternate/dual-wield on SLOT).
+//! Line order and the red requirement checks: level, class and reputation against player state,
+//! and the slot and type cells' separate proficiency reds.
 
 use std::collections::HashMap;
 
 use super::{axe, lines_of, right_color, script};
 use crate::script::*;
 
-/// The full line law over a rich weapon + the red checks: a level-25 warrior fails the level
-/// requirement (red) but passes the class list (white).
 #[test]
 fn item_line_law_and_red_requirements() {
     let mut s = script();
@@ -16,7 +13,7 @@ fn item_line_law_and_red_requirements() {
     s.set_item_template(871, axe());
     s.set_player_req_state(PlayerReqState {
         level: 25,
-        class_id: 1, // Warrior — allowed
+        class_id: 1, // Warrior: allowed
         race_id: 1,
         skills: HashMap::new(),
         ..Default::default()
@@ -39,14 +36,12 @@ fn item_line_law_and_red_requirements() {
             "Ravager",
             "[ITEM_BIND_ON_EQUIP]",
             "[INVTYPE_2HWEAPON]",
-            // School 0 is physical: the reference names no school word for it either.
-            // The first emitted slot takes the plain key, a later one the `PLUS_` twin, and a
-            // school'd slot the `_WITH_SCHOOL` arm — the word sits INSIDE the template.
+            // School 0 has no school word. The first damage line takes the plain key, later ones
+            // `PLUS_`, and a slot with a school the `_WITH_SCHOOL` arm, the word inside it.
             "[DMG 68 - 103]",
             "[+DMGS 2 - 4 [SCHOOL5]]",
             "[DPS 25.3]",
-            // Display order, NOT wire order: the fixture feeds (Stamina, Strength) but the
-            // 0x808e88 table prints Strength first (STR,AGI,STA,INT,SPI,HP,MANA).
+            // Display order, not field order: `0x808e88` prints STR, AGI, STA, INT, SPI, HP, MANA.
             "[MOD_STRENGTH +9]",
             "[MOD_STAMINA +12]",
             "[RESIST_SINGLE +10 [SCHOOL5]]",
@@ -58,7 +53,6 @@ fn item_line_law_and_red_requirements() {
         ],
         "the verified line order (0276)"
     );
-    // The name wears the Rare blue; the failed level line is red; the passed class line white.
     assert_eq!(lines[0].1, [0.0, 0.439, 0.867, 1.0], "rare-blue name");
     let class_line = &lines[10];
     assert_eq!(
@@ -72,17 +66,13 @@ fn item_line_law_and_red_requirements() {
         [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0],
         "level 25 < 37 → red"
     );
-    // The right column of the slot|type pair carries the subclass.
     let ty: String = s.eval("return TTTextRight3:GetText()").unwrap();
     assert_eq!(ty, "Axe");
-    // The speed column of the damage pair.
     let speed: String = s.eval("return TTTextRight4:GetText()").unwrap();
     assert_eq!(speed, "Speed 3.50");
     assert!(s.take_errors().is_empty());
 }
 
-/// The red law flips with player state: leveling past the requirement turns the line white; a
-/// class outside the list turns the class line red.
 #[test]
 fn red_lines_track_player_state() {
     let mut s = script();
@@ -90,7 +80,7 @@ fn red_lines_track_player_state() {
     s.set_item_template(871, axe());
     s.set_player_req_state(PlayerReqState {
         level: 60,
-        class_id: 8, // Mage — not in {Warrior, Rogue}
+        class_id: 8, // Mage: not in {Warrior, Rogue}
         race_id: 1,
         skills: HashMap::new(),
         ..Default::default()
@@ -121,12 +111,10 @@ fn red_lines_track_player_state() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The §5-verified families folded back 2026-07-10 (tooltip-content-law.md): SIGNABLE green,
-/// UNIQUE before STARTS_QUEST, LOCKED red, six-equal resistances collapse to the ALL line (and
-/// Holy never prints singly), a known taught spell reds "Already known", the description gold —
-/// and NO openable line: `BenillaSetItemById` is a template source, and the whole openable/readable/
-/// creator tail rides the ref's item-OBJECT gate (`0x52e1c7`/`0x52e2e0` — byte-read 2026-07-20;
-/// the instance-tail law itself is in [`instance_tail_creator_and_readable`]).
+/// The gated families (`0x52b650`): SIGNABLE green, UNIQUE before STARTS_QUEST, LOCKED red, six
+/// equal resistances as one ALL line (Holy never prints alone), a known taught spell's red
+/// "Already known", the gold description, and no openable line: the openable, readable and creator
+/// tail needs an item object (`0x52e1c7`, `0x52e2e0`), and a template has none.
 #[test]
 fn verified_families_signable_locked_resists_known() {
     let mut s = script();
@@ -146,7 +134,6 @@ fn verified_families_signable_locked_resists_known() {
             ..Default::default()
         },
     );
-    // The player already knows the taught spell 2020.
     s.set_spellbook(SpellBookState {
         tabs: Vec::new(),
         slots: vec![SpellSlotView {
@@ -197,7 +184,6 @@ fn verified_families_signable_locked_resists_known() {
         [1.0, 210.0 / 255.0, 0.0, 1.0],
         "the description is the byte-verified gold"
     );
-    // Holy exclusion: a lone Holy resist prints nothing.
     s.set_item_template(
         5519,
         ItemTemplateView {
@@ -215,10 +201,8 @@ fn verified_families_signable_locked_resists_known() {
     "#,
     )
     .unwrap();
-    // …and the five that DO print come out in the builder's own order, which is not the field
-    // order: `0x52c8ad` runs `edi` 1..5 reading school `(edi == 1) ? 6 : edi`, so **Arcane leads**
-    // and Holy is displaced rather than skipped (decision 2080 named this; we printed plain field
-    // order, Fire first and Arcane last).
+    // The five that print follow the builder, not the fields: `0x52c8ad` runs `edi` 1..5 reading
+    // school `(edi == 1) ? 6 : edi`, so Arcane leads.
     s.set_item_template(
         5520,
         ItemTemplateView {
@@ -246,12 +230,10 @@ fn verified_families_signable_locked_resists_known() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The slot|type line's independent cell reds (byte-read at the builder's coloring legs
-/// against the verified AddLine-CORE signature — NB law §10's prose swaps the cells): a hard
-/// proficiency miss (`0xc4d4a0[class]` bit `1 << subclass`) reds the TYPE cell; the SLOT cell
-/// reds when the weapon is usable only via its alternate subclass (ItemSubClass
-/// prereq/postreq) or is an off-hand weapon without Dual Wield (`0x5eab70`). Plus the
-/// reputation-requirement red (§1-RED's standing leg) and the hidden-type suppression.
+/// The slot and type cells red separately: a hard proficiency miss (`0xc4d4a0[class]` bit
+/// `1 << subclass`) reds the type; usable only through the alternate subclass, or an off-hand
+/// weapon without Dual Wield (`0x5eab70`), reds the slot. The reputation line takes the red
+/// (`0xc0d390`) below the required rank, and a hidden subclass prints no type cell.
 #[test]
 fn proficiency_and_reputation_reds() {
     let mut s = script();
@@ -305,8 +287,7 @@ fn proficiency_and_reputation_reds() {
         white,
         "met reputation is white"
     );
-    // 1H-axes-only mask, no alternate on the view: the hard miss reds the TYPE cell and the
-    // slot stays white. Friendly standing reds the rep line.
+    // A 1H-axes mask, no alternate: the type cell reds, not the slot; Friendly reds the rep line.
     let mut req2 = req;
     req2.proficiency.insert(2, 1 << 0);
     req2.rep_ranks.insert(72, 4);
@@ -325,8 +306,7 @@ fn proficiency_and_reputation_reds() {
         red,
         "unmet reputation is red"
     );
-    // The same mask with the view's alternate resolved to 1H axes (the real (2,1) row's
-    // prerequisite): usable-via-alternate reds the SLOT cell instead; the type goes white.
+    // With the alternate set to 1H axes, as the real (2, 1) row has it, the slot reds instead.
     let mut alt = item;
     alt.proficiency_alt = Some(0);
     s.set_item_template(871, alt);
@@ -343,8 +323,7 @@ fn proficiency_and_reputation_reds() {
         white,
         "the alternate covers the type"
     );
-    // An off-hand weapon with its dagger bit set still reds the SLOT cell without Dual
-    // Wield; learning it (an effect-40 spell) clears the red.
+    // An off-hand dagger reds the slot until Dual Wield (an effect-40 spell) is known.
     s.set_item_template(
         872,
         ItemTemplateView {
@@ -362,8 +341,7 @@ fn proficiency_and_reputation_reds() {
     s.run(r#"TT:SetOwner(Slot9, "ANCHOR_RIGHT"); TT:BenillaSetItemById(872)"#)
         .unwrap();
     let lines = lines_of(&mut s);
-    // `INVTYPE_WEAPONOFFHAND`, NOT `INVTYPE_SHIELD` — one enUS sentence, two keys, and only the
-    // weapon one belongs on an InventoryType 22.
+    // Type 22 takes `INVTYPE_WEAPONOFFHAND`, not `INVTYPE_SHIELD`, though both read "Off Hand".
     assert_eq!(
         color(&lines, "[INVTYPE_WEAPONOFFHAND]"),
         red,
@@ -384,13 +362,12 @@ fn proficiency_and_reputation_reds() {
         white,
         "Dual Wield clears it"
     );
-    // An item class with NO proficiency entry never reds (the map only ever holds classes
-    // the server sent masks for).
+    // A class with no proficiency entry never reds: the map holds only what the server sent.
     s.set_item_template(
         118,
         ItemTemplateView {
             name: "Tattered Cloth Vest".into(),
-            class: 4,    // armor — but req2 carries no class-4 entry
+            class: 4,    // armor, with no class-4 entry in req2
             subclass: 1, // cloth
             inventory_type: 5,
             ..Default::default()
@@ -404,7 +381,7 @@ fn proficiency_and_reputation_reds() {
         white,
         "a class with no mask entry stays white"
     );
-    // A hidden subclass (displayFlags bit 0 — the Miscellaneous family) prints no type cell.
+    // A hidden subclass (displayFlags bit 0, the Miscellaneous family) prints no type cell.
     s.set_item_template(
         889,
         ItemTemplateView {
@@ -428,9 +405,8 @@ fn proficiency_and_reputation_reds() {
     assert!(s.take_errors().is_empty());
 }
 
-/// ITEM_MIN_LEVEL's `> 1` gate (byte-VERIFIED `0x52d2cf`: `cmp esi,0x1 / jle skip`): a level-1
-/// requirement — every starter consumable's shape (bread/water carry `RequiredLevel 1`) —
-/// prints NO line, exactly like no requirement at all; level 2 is the first that prints.
+/// `ITEM_MIN_LEVEL` prints only above 1 (`0x52d2cf`): a level-1 requirement, as starter food and
+/// water carry, prints nothing.
 #[test]
 fn required_level_one_is_hidden() {
     let mut s = script();
@@ -462,28 +438,9 @@ fn required_level_one_is_hidden() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The instance tail (byte-read 2026-07-20; wow-re §1-CREATOR/-OPENABLE cross-checked, their
-/// 0f4824e2): a REAL-instance hover (`SetBagItem`) appends the creator line — "Written by %s"
-/// (white) when the instance carries letter text, the green-escaped "<Made by %s>" otherwise —
-/// then READABLE off the instance text id (its template's PageText is 0 — the
-/// director-reported gap). An unresolved creator (name query in flight) emits no line. LOCKED
-/// yields to the instance UNLOCKED bit — which is also what un-gates ITEM_OPENABLE: a bag hover
-/// on an openable instance shows the green `<Right Click to Open>` (director-observed on a clam;
-/// wow-re `right-click-open.md` §1 re-derived the `p6` leg selector that had it suppressed).
-/// A **running cooldown** takes SetBagItem's other leg and suppresses the line — the two are
-/// structurally exclusive on this binding (decision 0896).
-/// **Line 3 — the charter's guild name and master**, between the NAME and the green
-/// `ITEM_SIGNABLE` (wow-re `tooltip-content-law.md`'s emission order: 2 NAME, 3 the petition
-/// triple, 4 SIGNABLE).
-///
-/// The director's report was that our charter tooltip showed the name and the green line with
-/// nothing between them, where the real client prints "Guild Name: BTC" / "Guild Master:
-/// Twowarrior". The ORDER is the half a text-only assertion would miss: these lines sit above the
-/// green one, not below it.
-///
-/// Also pinned: the two key families (a plain petition reads "Petition:" / "Created by"), and that
-/// an unresolved owner withholds only its own line — the creator line's rule, and the reason a
-/// first hover of an unopened charter is not blank but partial.
+/// A charter's guild name and master sit between the item name and the green `ITEM_SIGNABLE`
+/// (`0x52b650` emits the name, the petition lines, then SIGNABLE). A plain petition takes the
+/// "Petition:" and "Created by" keys, and an owner still in flight withholds only its own line.
 #[test]
 fn charter_lines_sit_between_the_name_and_the_signable_line() {
     let mut s = script();
@@ -493,7 +450,7 @@ fn charter_lines_sit_between_the_name_and_the_signable_line() {
         ItemTemplateView {
             name: "Guild Charter".into(),
             quality: 1,
-            flags: 0x2000, // ITEM_FLAG_CHARTER — the green line's own gate
+            flags: 0x2000, // ITEM_FLAG_CHARTER, the green line's own gate
             max_count: 1,
             bonding: 1,
             ..Default::default()
@@ -516,7 +473,6 @@ fn charter_lines_sit_between_the_name_and_the_signable_line() {
             owner: Some("Twowarrior".into()),
         })),
     );
-    // The owner's name still in flight — the title line stands, its own does not.
     slots.insert(
         2,
         charter(Some(PetitionSlotView {
@@ -525,9 +481,7 @@ fn charter_lines_sit_between_the_name_and_the_signable_line() {
             owner: None,
         })),
     );
-    // No record yet at all: the plate is the name and the green line, as it was before this.
     slots.insert(3, charter(None));
-    // A non-charter petition takes the OTHER key family.
     slots.insert(
         4,
         charter(Some(PetitionSlotView {
@@ -662,9 +616,6 @@ fn instance_tail_creator_and_readable() {
     slots.insert(3, slot(2589, false, Some("Geoffrey"), 0)); // crafted, still locked
     slots.insert(4, slot(2589, false, None, 0x4)); // unlocked → LOCKED gone, open line on
     slots.insert(5, slot(7973, false, None, 0)); // the clam: lockless, openable outright
-                                                 // The same clam with a RUNNING cooldown — `SetBagItem`'s p6=1 leg, which skips the openable
-                                                 // tree entirely (the ITEM_COOLDOWN_TIME line takes its place in the reference; that line has
-                                                 // no feed here yet, so this slot renders bare).
     slots.insert(
         6,
         ContainerSlot {
@@ -697,12 +648,12 @@ fn instance_tail_creator_and_readable() {
     );
     assert_eq!(lines[1].1, [1.0, 1.0, 1.0, 1.0], "WRITTEN_BY is white");
     assert_eq!(lines[2].1, [0.0, 1.0, 0.0, 1.0], "READABLE is green");
-    // Creator unresolved → no writer line, READABLE stays (the re-push repaints later).
+    // The instance tail (`0x52e1b1`-`0x52e358`): a creator still in flight prints no writer line,
+    // and READABLE stays.
     s.run(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); TT:SetBagItem(0, 2)"#)
         .unwrap();
     let texts: Vec<String> = lines_of(&mut s).into_iter().map(|(t, _)| t).collect();
     assert_eq!(texts, vec!["Plain Letter", "[ITEM_READABLE]"]);
-    // Crafted + locked: the green-escaped Made-by; no open line while LockID gates it.
     s.run(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); TT:SetBagItem(0, 3)"#)
         .unwrap();
     let texts: Vec<String> = lines_of(&mut s).into_iter().map(|(t, _)| t).collect();
@@ -715,22 +666,19 @@ fn instance_tail_creator_and_readable() {
         ],
         "CREATED_BY carries the string's own green escape; locked chest hides OPENABLE"
     );
-    // The instance UNLOCKED bit retires the LOCKED line AND satisfies the openable lock sub-gate.
+    // The instance's UNLOCKED bit drops the LOCKED line and satisfies the openable lock gate.
     s.run(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); TT:SetBagItem(0, 4)"#)
         .unwrap();
     let lines = lines_of(&mut s);
     let texts: Vec<&str> = lines.iter().map(|(t, _)| t.as_str()).collect();
     assert_eq!(texts, vec!["Heavy Chest", "[ITEM_OPENABLE]"]);
     assert_eq!(lines[1].1, [0.0, 1.0, 0.0, 1.0], "OPENABLE is green");
-    // The director's case: a lockless LOOTABLE template (a clam) is openable outright — name +
-    // the green line, nothing between them.
     s.run(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); TT:SetBagItem(0, 5)"#)
         .unwrap();
     let texts: Vec<String> = lines_of(&mut s).into_iter().map(|(t, _)| t).collect();
     assert_eq!(texts, vec!["Small Barnacled Clam", "[ITEM_OPENABLE]"]);
-    // The same clam mid-cooldown takes SetBagItem's OTHER leg (p6=1) — the openable tree is
-    // skipped wholesale, so the green line is gone (the reference prints ITEM_COOLDOWN_TIME in
-    // its place; unfed here). `hasCooldown`, the binding's own return, is the same boolean.
+    // Mid-cooldown the clam takes `SetBagItem`'s other leg (p6 = 1, picked at `0x6e2ed0`), which
+    // skips the openable tree; the reference prints `ITEM_COOLDOWN_TIME` there, unfed here.
     let has_cd: bool = s
         .eval(r#"TT:SetOwner(getglobal("SlotL"), "ANCHOR_RIGHT"); return TT:SetBagItem(0, 6)"#)
         .unwrap();
@@ -744,25 +692,15 @@ fn instance_tail_creator_and_readable() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **§6's Soulbound override** — the bind line reads the INSTANCE, not only the template
-/// (B310, Frostshake: an equipped Maiden's Circle still said *Binds when equipped*, and B309's
-/// own shot showed *Binds when picked up* on the equipped pants).
-///
-/// The law (wow-re `tooltip-content-law.md` §6, byte-verified): Bonding `[record+0x194]` ∈ {1..5}
-/// decides whether a line prints at all; a **runtime-bound instance** (`0x5da2c0` — soulbound
-/// flag, or a live enchant slot that binds) overrides it to `ITEM_SOULBOUND`, and to
-/// `ITEM_BIND_QUEST` for the quest kinds; only then does the jump table `0x52e4fc` pick
-/// 1→picked up · 2→equipped · 3→used · 4/5→Quest Item.
-///
-/// Four claims, three of them controls: the override fires on a bound instance, an UNbound
-/// instance of the same item still reads *Binds when equipped*, a template hover (no instance at
-/// all) still reads *Binds when equipped*, and a bound QUEST item stays *Quest Item* — the
-/// override's other arm is the same text 4|5 print anyway.
+/// Bonding `[record+0x194]` in 1..5 decides whether a bind line prints; a runtime-bound instance
+/// (`0x5da2c0`: the soulbound flag, or a live enchant slot that binds) prints `ITEM_SOULBOUND`,
+/// or `ITEM_BIND_QUEST` for the quest kinds; else the jump table `0x52e4fc` picks 1 picked up,
+/// 2 equipped, 3 used, 4 and 5 Quest Item.
 #[test]
 fn a_runtime_bound_instance_overrides_the_bind_line_to_soulbound() {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
-    s.set_item_template(871, axe()); // bonding 2 — Binds when equipped
+    s.set_item_template(871, axe()); // bonding 2: Binds when equipped
     let ring = ItemTemplateView {
         name: "Maiden's Circle".into(),
         quality: 2,
@@ -788,9 +726,9 @@ fn a_runtime_bound_instance_overrides_the_bind_line_to_soulbound() {
         ..Default::default()
     };
     let mut slots = HashMap::new();
-    slots.insert(1, slot(942, true)); // bound: the reported case
+    slots.insert(1, slot(942, true)); // bound
     slots.insert(2, slot(942, false)); // the same ring, not yet bound
-    slots.insert(3, slot(4913, true)); // a bound QUEST item
+    slots.insert(3, slot(4913, true)); // a bound quest item
     s.set_container(
         0,
         Some(ContainerState {
@@ -826,30 +764,26 @@ fn a_runtime_bound_instance_overrides_the_bind_line_to_soulbound() {
     let (text, color) = bind_line(&mut s);
     assert_eq!(
         text, "[ITEM_SOULBOUND]",
-        "a runtime-bound instance overrides §6"
+        "a runtime-bound instance overrides the template's Bonding"
     );
-    assert_eq!(color, [1.0, 1.0, 1.0, 1.0], "§6 is white");
+    assert_eq!(color, [1.0, 1.0, 1.0, 1.0], "the bind line is white");
 
-    // Control 1: the SAME item, instance not bound — the template's bonding stands.
+    // Controls: the same ring unbound, and a template hover, which has no instance.
     s.run(r#"TT:SetBagItem(0, 2)"#).unwrap();
     assert_eq!(bind_line(&mut s).0, "[ITEM_BIND_ON_EQUIP]");
 
-    // Control 2: a TEMPLATE hover carries no instance at all, so nothing can override.
     s.run(r#"TT:BenillaSetItemById(871)"#).unwrap();
     assert_eq!(bind_line(&mut s).0, "[ITEM_BIND_ON_EQUIP]");
 
-    // Control 3: the override's other arm is ITEM_BIND_QUEST — the same text 4|5 already print.
+    // A bound quest item stays `ITEM_BIND_QUEST`, the text 4 and 5 print anyway.
     s.run(r#"TT:SetBagItem(0, 3)"#).unwrap();
     assert_eq!(bind_line(&mut s).0, "[ITEM_BIND_QUEST]");
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// **The damage block's five-arm template matrix** (wow-re
-/// `tooltip-damage-matrix-and-container-slots.md` §D1, VERIFIED; decision 2080 named this cell and
-/// 2158 converted it). Each arm here names the leg it takes: the school predicate is the slot's
-/// school NUMBER, the ammo predicate is `ItemClass == 6` alone, the single predicate compares the
-/// two ROUNDED bounds, and the first/`PLUS_` flag is per-item — a skipped slot does not consume it.
-/// The rounding is `floor(min)` / `ceil(max)`, not a round-half pair.
+/// The damage templates (`0x52c22b`): the school arm goes by the slot's school number, the ammo
+/// arm by `ItemClass == 6` alone, the single arm by equal rounded bounds, and the first/`PLUS_`
+/// flag is per item, kept past a skipped slot. Bounds round as `floor(min)`, `ceil(max)`.
 #[test]
 fn damage_matrix_arms_and_the_first_flag() {
     let mut s = script();
@@ -875,9 +809,7 @@ fn damage_matrix_arms_and_the_first_flag() {
         ..Default::default()
     };
 
-    // The plain two-number arm, the SKIP, and the PLUS_ twin — the skipped middle slot does not
-    // consume the first flag, so slot 2 still prints as a later line, and only the FIRST emitted
-    // line carries the Speed cell.
+    // A zero middle slot is skipped; only the first line carries the Speed cell.
     let lines = show(
         &mut s,
         900,
@@ -898,29 +830,24 @@ fn damage_matrix_arms_and_the_first_flag() {
         .expect("right cell 4");
     assert_eq!(later, "", "a later damage line renders left-only");
 
-    // floor(min) / ceil(max) on fractional bounds — Fang of the Mystics' real numbers. A
-    // round-half pair would say "39 - 86"; the biased pair says 38.
+    // Fang of the Mystics' real bounds: `floor`/`ceil` give 38 - 86, where rounding gives 39.
     let lines = show(&mut s, 901, weapon(vec![(38.7, 85.7, 0)]));
     assert_eq!(lines[2], "[DMG 38 - 86]", "{lines:?}");
 
-    // The SINGLE arm — the two ROUNDED bounds equal. It is a no-school, non-ammo leaf only.
+    // The single arm: equal rounded bounds, no school, not ammo.
     let lines = show(&mut s, 902, weapon(vec![(7.0, 7.0, 0)]));
     assert_eq!(lines[2], "[DMG1 7]", "{lines:?}");
-    // …and a school'd slot with equal bounds still takes the WITH_SCHOOL arm, two identical
-    // numbers and all: there is no SINGLE_…_WITH_SCHOOL template.
+    // A slot with a school and equal bounds takes `WITH_SCHOOL`: no single school template exists.
     let lines = show(&mut s, 903, weapon(vec![(7.0, 7.0, 4)]));
     assert_eq!(lines[2], "[DMGS 7 - 7 [SCHOOL4]]", "{lines:?}");
 
-    // AMMO is `ItemClass == 6` alone. The `%g` value is the two rounded bounds averaged and is
-    // NOT divided by anything — Rough Arrow's 1–2 reads 1.5 — and ammo gets neither a Speed
-    // cell nor a DPS line, because both gate on class 2.
+    // Ammo's `%g` is the rounded bounds' average, undivided (Rough Arrow's 1-2 reads 1.5), with
+    // no Speed cell or DPS line, both gated on class 2.
     let arrow = ItemTemplateView {
         name: "Rough Arrow".into(),
         class: 6,
         subclass: 2,
         sub_class_display: Some("Arrow".into()),
-        // `ItemClass.dbc` row 6's own name — the LEFT cell for a class-6 item, which never
-        // consults the InventoryType key table.
         item_type: Some("Projectile".into()),
         inventory_type: 24,
         damages: vec![(1.0, 2.0, 0)],
@@ -928,9 +855,8 @@ fn damage_matrix_arms_and_the_first_flag() {
         ..Default::default()
     };
     let lines = show(&mut s, 904, arrow.clone());
-    // The slot|type line above it reads "Projectile | Arrow": a class-6 item takes
-    // `ItemClass.dbc`'s own row-6 name on the LEFT (`0x52c0bc`, read verbatim — never a
-    // GlobalString), not the empty `INVTYPE_AMMO` key.
+    // The type line reads "Projectile | Arrow": the left cell is the DBC name (`0x52c0bc`),
+    // never a GlobalString such as the absent `INVTYPE_AMMO`.
     assert_eq!(lines[1], "Projectile", "{lines:?}");
     let ty: String = s
         .eval("return TTTextRight2:GetText() or ''")
@@ -984,9 +910,8 @@ fn damage_matrix_arms_and_the_first_flag() {
     );
 }
 
-/// **The bag line** (wow-re §D2, VERIFIED): its gate is `InventoryType == 0x12` alone — never the
-/// slot count — and its second hole is the same `ItemSubClass` DisplayName the type cell reads, so
-/// the noun is per-subclass. A container whose row names nothing prints no slot line at all.
+/// The bag line (`0x52b754`) gates on `InventoryType == 0x12` alone, and its noun is the
+/// subclass's DisplayName; a row with no name prints no line.
 #[test]
 fn container_slots_line_names_its_subclass() {
     let mut s = script();
@@ -1020,17 +945,15 @@ fn container_slots_line_names_its_subclass() {
         "[SLOTS 24 Soul Bag]",
         "the noun is the subclass's, not a constant"
     );
-    // A quiver is InventoryType 18 like every other container — INVTYPE_QUIVER is a dead slot
-    // name in 1.12 — so it reaches this line and names itself.
+    // A quiver is InventoryType 18 like any container, so it names itself here.
     let mut quiver = bag(2, Some("Quiver"), 8);
     quiver.class = 11;
     assert_eq!(show(&mut s, 912, quiver)[1], "[SLOTS 8 Quiver]");
-    // The gate never tests the slot count.
     assert_eq!(
         show(&mut s, 913, bag(0, Some("Bag"), 0))[1],
         "[SLOTS 0 Bag]"
     );
-    // No row name: NEITHER this line nor the ordinary slot|type one.
+    // No row name: neither this line nor the slot and type line.
     let lines = show(&mut s, 914, bag(0, None, 16));
     assert_eq!(lines.len(), 1, "name line only: {lines:?}");
 }
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/mechanics.rs b/crates/benilla-ui/src/script/tests/tooltip_item/mechanics.rs
index 9da0fca9..e07b04ef 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/mechanics.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/mechanics.rs
@@ -1,15 +1,13 @@
-//! Render mechanics around the line law: the sell-price money protocol (OnTooltipAddMoney +
-//! ITEM_UNSELLABLE), wrapped-line measurement through the re-enter loop, and the unit health
-//! bar hiding on an item render.
+//! Render mechanics around the line order: sell price, wrapped lines, the unit health bar,
+//! durability, enchant lines and random-property rolls.
 
 use std::collections::HashMap;
 
 use super::script;
 use crate::script::*;
 
-/// The sell-price money protocol: SetBagItem at an open merchant fires OnTooltipAddMoney with
-/// SellPrice × stack; price 0 prints the ITEM_UNSELLABLE line; no merchant → neither; the
-/// in-flight template renders the link-name fallback and records the ask.
+/// `SetBagItem` at an open merchant fires `OnTooltipAddMoney` with SellPrice × stack, and price 0
+/// prints `ITEM_UNSELLABLE`; with no merchant, neither. A template in flight renders the link name.
 #[test]
 fn bag_item_money_law_and_fallback() {
     let mut s = script();
@@ -80,7 +78,6 @@ fn bag_item_money_law_and_fallback() {
     )
     .unwrap();
     assert_eq!(s.take_item_stat_asks(), vec![9999], "the miss asked");
-    // Zero sell price at a merchant: the ITEM_UNSELLABLE line, no money.
     s.set_item_template(
         9999,
         ItemTemplateView {
@@ -104,13 +101,8 @@ fn bag_item_money_law_and_fallback() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A wrap-flagged line carries its wrap column on the VERY FIRST measure ask (append_line pins
-/// the region width at write time), so ONE round-trip answers the wrapped extent — and the
-/// plate height/width converge even when the hover's re-enter loop clears + rebuilds the
-/// content every frame. The old two-step (layout re-pinning after an overflowing unwrapped
-/// measure) never converged under that loop: the wrapped re-measure was wiped before it could
-/// land, wrap lines contributed no height, and everything after them spilled below the plate
-/// (the live bread/hearthstone bug).
+/// A wrap line's first measure asks with the wrap column, so one pass answers the wrapped size,
+/// and the size holds while the hover clears and rebuilds the content every frame.
 #[test]
 fn wrap_lines_measure_wrapped_in_one_pass_and_survive_the_reenter_loop() {
     let mut s = script();
@@ -137,8 +129,7 @@ fn wrap_lines_measure_wrapped_in_one_pass_and_survive_the_reenter_loop() {
     )
     .unwrap();
     s.resolve();
-    // ONE measure pass, the frame loop's shape: the wrap-flagged description asks WITH the
-    // wrap column; plain lines ask unconstrained.
+    // One measure pass: the wrap-flagged description asks with the wrap column, others without.
     let answer = |s: &mut UiScript| {
         let reqs = s.fontstrings_needing_measure();
         let answers: Vec<(u32, f32, f32, u64)> = reqs
@@ -168,8 +159,7 @@ fn wrap_lines_measure_wrapped_in_one_pass_and_survive_the_reenter_loop() {
     "#,
     )
     .unwrap();
-    // The re-enter loop: clear + rebuild + one measure pass per frame, three frames — the size
-    // must HOLD (the oscillation regression).
+    // Clear, rebuild and measure once per frame for three frames: the size holds.
     for _ in 0..3 {
         s.run(
             r#"
@@ -191,8 +181,7 @@ fn wrap_lines_measure_wrapped_in_one_pass_and_survive_the_reenter_loop() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The mouseover health bar is UNIT content: an item render on the same tooltip HIDES it (the
-/// live bug: the bar from the last mob hover rode under every item tooltip).
+/// The mouseover health bar is unit content: an item render on the same tooltip hides it.
 #[test]
 fn item_render_hides_the_unit_health_bar() {
     let mut s = script();
@@ -241,9 +230,8 @@ fn item_render_hides_the_unit_health_bar() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A REAL-INSTANCE hover renders the instance's LIVE durability pair, not the template's full
-/// max/max — the wire updates `ITEM_FIELD_DURABILITY` on damage (death 10%, spirit healer 25%;
-/// director-reported: the 25% loss showed nowhere). A plain template/link hover keeps max/max.
+/// A bag hover shows the instance's live `ITEM_FIELD_DURABILITY` (a death costs 10%, the spirit
+/// healer 25%); a template or link hover shows max/max.
 #[test]
 fn real_instance_hover_renders_live_durability() {
     let mut s = script();
@@ -302,10 +290,8 @@ fn real_instance_hover_renders_live_durability() {
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// FULLY BROKEN gear renders its true `0 / max` pair (director-caught: gear ground to durability
-/// 0 by repeated spirit rezzes read as 100% — the create block omits the zero `DURABILITY` field,
-/// and the sparse `None` fell back to the template's max/max; `ObjectFields`' created semantics
-/// now feed the explicit 0 through).
+/// Broken gear shows its true `0 / max`: a create block omits a zero `DURABILITY`, which must not
+/// read as the template's max.
 #[test]
 fn broken_instance_hover_renders_zero_durability() {
     let mut s = script();
@@ -353,8 +339,7 @@ fn broken_instance_hover_renders_zero_durability() {
     )
     .unwrap();
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
-    // Red iff broken — the byte law ("durability (red iff broken==0)", wow-re ui.md): the 0/40
-    // line paints the requirement red, never white.
+    // Red only when broken (`0x854bc4`, colour `0xc0d390`).
     let lines = super::lines_of(&mut s);
     let dur = lines
         .iter()
@@ -367,12 +352,8 @@ fn broken_instance_hover_renders_zero_durability() {
     );
 }
 
-/// The **enchant lines** (law line 17, decision 0915) — the director's report: an axe carrying
-/// Enchant Weapon - Agility showed its green glow in the world and said nothing in the tooltip.
-///
-/// Three claims at once: the line renders from the instance's resolved enchant text, it sits
-/// **between the resistances and the durability line** (the law's 16 → 17 → 18), and it is green.
-/// The control is the template/link hover of the same item — no instance, no enchant, no line.
+/// An instance's enchant prints from its resolved text, in green, between the resistances and
+/// durability; a template hover of the same item has no instance and so no enchant line.
 #[test]
 fn an_enchanted_instance_renders_its_enchant_line_before_durability() {
     let mut s = script();
@@ -384,8 +365,7 @@ fn an_enchanted_instance_renders_its_enchant_line_before_durability() {
             quality: Some(4),
             item_id: 22816,
             durability: Some((105, 105)),
-            // What the app resolved from `ITEM_FIELD_ENCHANTMENT` slot 0 → enchant 2564 →
-            // `SpellItemEnchantment`'s own name string. Slot 0 = permanent, positive id.
+            // `ITEM_FIELD_ENCHANTMENT` slot 0 (permanent) → enchant 2564 → its name string.
             enchants: vec![EnchantView {
                 slot: 0,
                 name: "Agility +15".into(),
@@ -441,7 +421,6 @@ fn an_enchanted_instance_renders_its_enchant_line_before_durability() {
         "the enchant line is green"
     );
 
-    // The control: the same item as a TEMPLATE hover has no instance, so no enchant line.
     s.run(r#"TT:BenillaSetItemById(22816)"#).unwrap();
     let lines = super::lines_of(&mut s);
     assert!(
@@ -451,12 +430,8 @@ fn an_enchanted_instance_renders_its_enchant_line_before_durability() {
     assert!(s.errors().is_empty(), "script errors: {:?}", s.errors());
 }
 
-/// The **enchant colour bands** — the correction the byte-carve landed (wow-re §1-ENCHANT §E3,
-/// decision 0920). The colour is per SLOT, not per family: only slots 0 (permanent) and 1
-/// (temporary) are ever coloured — green for a positive id, the tooltip's OTHER red
-/// (`0xc0d398 = ffff0000`, distinct from the requirement lines' `ffff2020`) for a negative one —
-/// and the random-property slots 2..6 are always white whatever the sign. Our first cut painted
-/// every slot green.
+/// Enchant colour goes by slot (`0x52ca29`): slots 0 and 1 are green for a positive id and pure
+/// red (`0xc0d398`, `ffff0000`, not the requirement `ffff2020`) for a negative one; 2..6 are white.
 #[test]
 fn enchant_line_colour_is_per_slot_and_sign() {
     let mut s = script();
@@ -484,7 +459,6 @@ fn enchant_line_colour_is_per_slot_and_sign() {
                     name: "Stamina +7".into(),
                     ..Default::default()
                 },
-                // A suffix slot with a NEGATIVE id is still white — the band, not the sign, rules.
                 EnchantView {
                     slot: 4,
                     name: "Spirit +3".into(),
@@ -547,10 +521,8 @@ fn enchant_line_colour_is_per_slot_and_sign() {
     );
 }
 
-/// The temporary enchant's countdown REPLACES the name in the same line (never a second one), and
-/// the charges suffix rides after it — §E3's `0x52fa50` bucket ladder and the `" (%s)"` join. The
-/// countdown's source is `SMSG_ITEM_ENCHANT_TIME_UPDATE`, so a slot with no packet shows the bare
-/// name: that is the control here.
+/// A temporary enchant prints one line, its countdown template (`0x52fa50`) around the name, then
+/// the charges joined by `" (%s)"`; with no `SMSG_ITEM_ENCHANT_TIME_UPDATE` it is the bare name.
 #[test]
 fn temporary_enchant_line_carries_its_countdown_and_charges() {
     let mut s = script();
@@ -616,15 +588,11 @@ fn temporary_enchant_line_carries_its_countdown_and_charges() {
     );
 }
 
-/// **The loot hover shows the ROLL, never the placeholder** (decision 1547; wow-re §E6-LOOT).
-/// `SetLootItem 0x533470` writes an instance block (p6=1) whose `+0x424` is the wire's
-/// randomPropertyId and whose seven enchant slots are zeroed, and passes an all-zero item GUID —
-/// so there is never an object, the builder takes §E5's suffix-row copy into slots 2..6, and the
-/// `ITEM_RANDOM_ENCHANT` arm is unreachable (§E1's fork). The row's name is the suffix-joined one
-/// (`0x5d8b00`, the same string `GetLootSlotInfo` returns), so the plate reads "… of the Monkey".
-///
-/// This is the reported bug's exact shape: through the template path (`BenillaSetItemById`) the same
-/// hover printed the ITEM_RANDOM_ENCHANT placeholder until the item reached a bag.
+/// A loot hover shows the roll, never the placeholder: `SetLootItem` (`0x533470`) builds an
+/// instance block (p6 = 1) with the roll at `+0x424`, zeroed enchant slots and no object, so the
+/// builder copies the suffix row into slots 2..6 (`0x52b7e0`) and never reaches
+/// `ITEM_RANDOM_ENCHANT` (`0x52c991`). The name is the suffixed one `GetLootSlotInfo` returns
+/// (`0x5d8b00`).
 #[test]
 fn a_looted_roll_shows_its_lines_and_never_the_placeholder() {
     let mut s = script();
@@ -634,8 +602,7 @@ fn a_looted_roll_shows_its_lines_and_never_the_placeholder() {
             name: "Bloodrazor".into(),
             quality: 2,
             class: 2,
-            // The template CAN roll — the placeholder's own gate, so its absence below is the law
-            // and not an accident of the fixture.
+            // The template can roll, so the placeholder's absence below is the rule at work.
             random_property: 42,
             ..Default::default()
         },
@@ -650,8 +617,7 @@ fn a_looted_roll_shows_its_lines_and_never_the_placeholder() {
             is_coin: false,
             item_id: 8888,
             link: Some("|cff1eff00|Hitem:8888:0:584:0|h[Bloodrazor of the Monkey]|h|r".into()),
-            // The row carries the ROLL, not resolved lines — the engine resolves it, like the
-            // reference reading its own DBC store off the block's `+0x424`.
+            // The row carries the roll id; the engine resolves it, as the reference reads `+0x424`.
             random_property_id: 584,
         })],
         fishing: false,
@@ -703,15 +669,12 @@ fn a_looted_roll_shows_its_lines_and_never_the_placeholder() {
             .iter()
             .find(|(t, _)| t == line)
             .unwrap_or_else(|| panic!("the roll's slot line {line} — got {texts:?}"));
-        // Slots 2..6 are always WHITE, whatever the sign (§E3).
         assert_eq!(l.1, [1.0, 1.0, 1.0, 1.0], "{line} is white");
     }
 }
 
-/// The other half of the same law: a loot row with **no** roll shows no enchant line AND no
-/// placeholder, even though the template can roll. The fork tests the block's presence, not its
-/// contents (§E1) — which is why this cannot be expressed as "print the placeholder when the
-/// slots are empty".
+/// A loot row with no roll shows neither enchant lines nor the placeholder, though the template can
+/// roll: the fork tests the block's presence, not its contents (`0x52c9a3`).
 #[test]
 fn a_looted_item_with_no_roll_shows_neither_line_nor_placeholder() {
     let mut s = script();
@@ -755,11 +718,8 @@ fn a_looted_item_with_no_roll_shows_neither_line_nor_placeholder() {
     );
 }
 
-/// A **chat link** is a block source too (`SetHyperlink 0x532181`, p6=1): its `|Hitem:` token 2 is
-/// the roll, which §E5 expands into slots 2..6, and the placeholder arm is unreachable. Decision
-/// 0920's prose said a hyperlink hover shows the placeholder; §E1's fork says otherwise, and this
-/// is the case that proves it — the same drop, linked in chat instead of hovered in the loot
-/// window, must read identically.
+/// A chat link is a block source too (`SetHyperlink` `0x532181`, p6 = 1): its `|Hitem:` token 2 is
+/// the roll, `0x52b7e0` expands it into slots 2..6, and `0x52c9a3` never reaches the placeholder.
 #[test]
 fn a_linked_roll_shows_its_lines_and_never_the_placeholder() {
     let mut s = script();
@@ -816,10 +776,8 @@ fn a_linked_roll_shows_its_lines_and_never_the_placeholder() {
     );
 }
 
-/// `ITEM_RANDOM_ENCHANT` (§E5) — the template-only placeholder: a random-property item with NO
-/// instance to read a roll from prints it, green, and the per-slot lines and this one are mutually
-/// exclusive by construction. The control is the same template hovered as a real enchanted
-/// instance: the roll is known, so the placeholder gives way to the slot lines.
+/// `ITEM_RANDOM_ENCHANT` (`0x52cc33`) prints, green, only for a random-property item with no
+/// instance to read a roll from; an instance's known roll prints its slot lines instead.
 #[test]
 fn random_property_template_hover_shows_the_placeholder() {
     let mut s = script();
@@ -849,7 +807,6 @@ fn random_property_template_hover_shows_the_placeholder() {
         .expect("the template hover shows the placeholder");
     assert_eq!(placeholder.1, [0.0, 1.0, 0.0, 1.0], "green");
 
-    // With a real instance (the roll is known) the placeholder is gone and the slots print.
     let mut slots = HashMap::new();
     slots.insert(
         1,
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/mod.rs b/crates/benilla-ui/src/script/tests/tooltip_item/mod.rs
index 531bd138..9c4107a6 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/mod.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/mod.rs
@@ -1,22 +1,13 @@
-//! The engine item-tooltip renderer (decision 0274 P1, law per 0276): the verified line law
-//! end-to-end, the red failed-requirement law against live player state, the sell-price money
-//! protocol (engine fires `OnTooltipAddMoney` — merchant open + real instance + repair off),
-//! and the in-flight-template fallback.
+//! The engine item-tooltip renderer: line order, requirement reds against live player state, the
+//! sell price (`OnTooltipAddMoney` at an open merchant, for a real instance, out of repair mode)
+//! and the fallback for a template still in flight.
 
 use super::common::script as bare_script;
 use crate::script::*;
 
-/// A stand-in `GlobalStrings.lua` for the item builder — **deliberately not the shipped wording**.
-///
-/// Every sentence the builder draws is a key resolved off the VM's own globals (decision 2045),
-/// and what these tests establish is *which key* each line reaches and what fills it, never what
-/// the sentence says. Naming each value after its own key is the point: `INVTYPE_SHIELD`,
-/// `INVTYPE_WEAPONOFFHAND` and `SECONDARYHANDSLOT` all read "Off Hand" in enUS, `ITEM_REQ_SKILL`
-/// shares "Requires %s" with the three `LOCKED_WITH_*` keys, and an assertion on the English
-/// would pass on every one of them. Read an expected line here as "this key, filled with these".
-///
-/// The values keep each shipped template's *hole shape* — that is what proves the fill — and
-/// nothing else about it.
+/// Stand-in `GlobalStrings.lua` values, each named after its key with the shipped hole shape:
+/// several keys share one enUS sentence ("Off Hand", "Requires %s"), so the tests assert which key
+/// each line reaches and what fills it.
 fn seed_item_strings(s: &mut UiScript) {
     s.run(
         r#"
@@ -121,8 +112,7 @@ fn seed_item_strings(s: &mut UiScript) {
     .unwrap();
 }
 
-/// The shared fixture VM, with [`seed_item_strings`] already run — every test in this tree needs
-/// it, because a builder that resolves nothing draws nothing.
+/// The fixture VM, with [`seed_item_strings`] run.
 fn script() -> UiScript {
     let mut s = bare_script();
     seed_item_strings(&mut s);
@@ -136,8 +126,7 @@ fn axe() -> ItemTemplateView {
         quality: 3,
         class: 2,
         subclass: 1,
-        // ItemSubClass.dbc's DisplayName for (2, 1) — the app-resolved word the type cell
-        // prints; the two axe subclasses share it.
+        // `ItemSubClass.dbc`'s DisplayName for (2, 1), which both axe subclasses share.
         sub_class_display: Some("Axe".into()),
         inventory_type: 17,
         bonding: 2,
@@ -155,8 +144,7 @@ fn axe() -> ItemTemplateView {
     }
 }
 
-/// The tooltip's left-column lines in order, each with its draw color (read from the extract —
-/// the color a renderer would actually paint).
+/// The tooltip's left-column lines in order, each with the colour the extract paints it.
 fn lines_of(s: &mut UiScript) -> Vec<(String, [f32; 4])> {
     s.resolve();
     let quads = s.extract();
diff --git a/crates/benilla-ui/src/script/tests/tooltip_item/set.rs b/crates/benilla-ui/src/script/tests/tooltip_item/set.rs
index a5bfd48b..ae351242 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_item/set.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_item/set.rs
@@ -1,19 +1,12 @@
-//! The §22 item-SET block: order (blank, gold header, skill line, member ladder, blank,
-//! bonuses), the threshold-ascending sort, the skill gate, member cream/gray, and the
-//! ask-once for unseen set ids.
+//! The item-set block (`ITEM_SET_NAME` `0x854b1c`): a blank, the gold header, the skill line, the
+//! member ladder, a blank, then the bonuses by ascending threshold; and the quest reward hovers.
 
 use super::{lines_of, script};
 use crate::script::*;
 
-/// The §22 SET block, byte-read: a blank gold line, the gold `ITEM_SET_NAME` header, the skill
-/// line (white/red) between header and the member ladder (cream when equipped / gray; in-flight
-/// names wait), a second blank, then the threshold bonuses SORTED ascending — green only when the
-/// skill requirement is met AND owned ≥ threshold — plus the ask-once for an unseen set id.
-///
-/// **The two bonus arms are two different keys** (`0x52e056..0x52e0d6`): an ACTIVE bonus formats
-/// `ITEM_SET_BONUS` = "Set: %s" with no count at all, and only an inactive one formats
-/// `ITEM_SET_BONUS_GRAY` = "(%d) Set: %s". Watching the (2) bonus move between them as the skill
-/// gate opens and closes is what these assertions are for.
+/// Members are cream when equipped and gray otherwise; a bonus is green only with the skill met
+/// and enough owned. The bonus arms are two keys (`0x52e056..0x52e0d6`): an active bonus formats
+/// `ITEM_SET_BONUS` ("Set: %s", no count), an inactive one `ITEM_SET_BONUS_GRAY` ("(%d) Set: %s").
 #[test]
 fn item_set_block_counts_and_colors() {
     let mut s = script();
@@ -29,7 +22,7 @@ fn item_set_block_counts_and_colors() {
     };
     vest.stats.clear();
     s.set_item_template(6303, vest);
-    // Two members equipped (the chest itself + the belt).
+    // Two members equipped: the chest itself and the belt.
     let mut slots: InventorySlots = Default::default();
     slots[4] = Some(InvSlotView {
         item_id: 6303,
@@ -46,11 +39,10 @@ fn item_set_block_counts_and_colors() {
             (6303, Some("Defias Mark".into())),
             (6304, Some("Defias Belt".into())),
             (6305, Some("Defias Gloves".into())),
-            (6306, None), // template still in flight — no line yet
+            (6306, None), // template still in flight: no line yet
             (6307, Some("Defias Boots".into())),
         ],
-        // Stored high-first (the catalog keeps DBC slot order — The Gladiator ships
-        // 3,2,5,4): the renderer must sort ascending at print time.
+        // Stored high-first in DBC slot order (The Gladiator ships 3,2,5,4); the renderer sorts.
         bonuses: vec![
             (4, "+10 Attack Power.".into()),
             (2, "Increases movement speed slightly.".into()),
@@ -120,8 +112,7 @@ fn item_set_block_counts_and_colors() {
         gray,
         "inactive bonus is gray"
     );
-    // The skill gate (`0x5eaae0`): an unmet set-level skill reds its line — seated between
-    // the header and the first member — and grays every bonus, met thresholds included.
+    // The skill gate (`0x5eaae0`): an unmet skill reds its line and grays every bonus.
     let mut gated = set_view;
     gated.required_skill = 165;
     gated.required_skill_rank = 250;
@@ -138,7 +129,7 @@ fn item_set_block_counts_and_colors() {
     .unwrap();
     let lines = lines_of(&mut s);
     assert_eq!(color(&lines, "[MIN_SKILL Leatherworking 250]"), red);
-    // The gate also moves it onto the OTHER key: an inactive bonus is the counted spelling.
+    // Grayed, the (2) bonus takes the counted key.
     assert_eq!(
         color(
             &lines,
@@ -162,7 +153,6 @@ fn item_set_block_counts_and_colors() {
         green,
         "meeting the skill restores the green — and the countless key with it"
     );
-    // An unseen set id records the ask-once.
     s.set_item_template(
         9999,
         ItemTemplateView {
@@ -177,10 +167,8 @@ fn item_set_block_counts_and_colors() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `GameTooltip:SetQuestItem(type, index)` and `SetQuestLogItem(type, index)` — the quest-giver
-/// panels' and the quest log's reward hovers (stock QuestFrameTemplates.xml:148,
-/// QuestLogFrame.xml:113): the row's item by id through the shared renderer; a row that is not
-/// there leaves the tooltip empty (1944).
+/// `SetQuestItem` and `SetQuestLogItem`, the reward hovers (`QuestFrameTemplates.xml:148`,
+/// `QuestLogFrame.xml:113`), render the row's item by id; a missing row leaves the tooltip empty.
 #[test]
 fn quest_item_hovers_render_the_rows_item_by_id() {
     let mut s = script();
@@ -236,7 +224,7 @@ fn quest_item_hovers_render_the_rows_item_by_id() {
         }],
         ..Default::default()
     });
-    // The detail hangs on the row now, so the tooltip reads it through the selection (2247).
+    // The detail hangs on the selected row, so select it first.
     s.run("SelectQuestLogEntry(1)").unwrap();
     s.run(r#"TT:SetOwner(Q1, "ANCHOR_RIGHT"); TT:SetQuestLogItem("reward", 1)"#)
         .unwrap();
diff --git a/crates/benilla-ui/src/script/tests/tooltip_spell.rs b/crates/benilla-ui/src/script/tests/tooltip_spell.rs
index d14a109a..4a83a075 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_spell.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_spell.rs
@@ -1,8 +1,6 @@
-//! The engine spell/aura tooltip channel (decision 0274 P2, law per 0276): the verified line
-//! shapes — name|rank, ONE cost|range line, ONE casttime|cooldown line, the passive omission,
-//! the aura variant (white description + the SetPlayerBuff-only remaining line, itself gold —
-//! B62), and SetAction's
-//! pure delegation.
+//! The engine spell and aura tooltips: name|rank, one cost|range line, one casttime|cooldown line,
+//! the passive omission, the aura variant (white description, and the gold remaining line on
+//! `SetPlayerBuff` only), and the selectors that delegate to them.
 
 use super::common::script;
 use crate::script::*;
@@ -20,7 +18,7 @@ fn fireball() -> SpellTooltipView {
     }
 }
 
-/// The spellbook hover: name|rank gray, cost|range one line, casttime line, gold description.
+/// The spellbook hover: no rank column, cost|range on one line, cast time, gold description.
 #[test]
 fn spellbook_hover_renders_the_verified_shape() {
     let mut s = script();
@@ -53,7 +51,6 @@ fn spellbook_hover_renders_the_verified_shape() {
     "#,
     )
     .unwrap();
-    // The description wears the byte-verified gold.
     s.resolve();
     let quads = s.extract();
     let gold = quads.iter().any(|q| {
@@ -64,13 +61,8 @@ fn spellbook_hover_renders_the_verified_shape() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **`bookType` decides which book the hover reads** — the fork `SetSpell 0x532d10` makes at
-/// `0x532e1c`/`0x532e2a` (`[4*i + 0xb6f098]` for the pet, `[4*i + 0xb700f0]` otherwise).
-///
-/// The defect (1050): the binding took the argument and dropped it, so a pet-book hover indexed the
-/// PLAYER's slot list — the imp's first spell showed the player's first spell, "Attack" and its
-/// crit line, on the director's screen. Both books are populated here with a *different* spell at
-/// the same slot id, which is the only arrangement that can tell the two apart.
+/// `SetSpell`'s `bookType` picks the book (`0x532d10` forks at `0x532e1c`, `0x532e2a`: the pet's
+/// slots at `0xb6f098`, the player's at `0xb700f0`); both books hold a different spell at slot 1.
 #[test]
 fn a_pet_book_hover_reads_the_pets_book_not_the_players() {
     let mut s = script();
@@ -126,9 +118,8 @@ fn a_pet_book_hover_reads_the_pets_book_not_the_players() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The tracking icon's hover (SetTrackingSpell): a GOLD name over the white (aura-variant)
-/// description — the shape the director's reference A/B pinned (2026-07-20), distinct from
-/// SetPlayerBuff's white name. No cost/casttime lines, no duration-remaining line.
+/// `SetTrackingSpell`, as the reference draws it: a gold name over the white aura description,
+/// with no cost, cast time or remaining line.
 #[test]
 fn tracking_hover_renders_gold_name_over_white_description() {
     let mut s = script();
@@ -178,7 +169,7 @@ fn tracking_hover_renders_gold_name_over_white_description() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A passive spell omits the casttime|cooldown line whole — never a "Passive" text line.
+/// A passive spell omits the casttime|cooldown line whole, with no "Passive" text line.
 #[test]
 fn passive_omits_the_casttime_line() {
     let mut s = script();
@@ -220,8 +211,8 @@ fn passive_omits_the_casttime_line() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The buff hover: the aura variant — WHITE description + the duration-remaining line (only
-/// this entry point), computed off the aura's GetTime expiry.
+/// The buff hover is the aura variant: a white description and, on this entry point only, the
+/// remaining-time line computed off the aura's `GetTime` expiry.
 #[test]
 fn player_buff_hover_is_the_aura_variant() {
     let mut s = script();
@@ -272,7 +263,6 @@ fn player_buff_hover_is_the_aura_variant() {
     "#,
     )
     .unwrap();
-    // The aura description is WHITE (the byte-verified aura/spell difference).
     s.resolve();
     let quads = s.extract();
     let white = quads.iter().any(|q| {
@@ -280,19 +270,14 @@ fn player_buff_hover_is_the_aura_variant() {
             if t.starts_with("Intellect increased") && *c == [1.0, 1.0, 1.0, 1.0])
     });
     assert!(white, "aura description is white, not gold");
-    // …and the NAME is GOLD: the aura builder `0x52f880` writes it through the gold wrapper
-    // `0x530380`, where the spell builder uses the plain `0x530270`. Pinned against the
-    // reference's own buff hover (2026-07-25 report B53), which the white name did not match.
+    // The name is gold: the aura builder `0x52f880` writes it through the gold wrapper
+    // `0x530380`, where the spell builder uses the plain `0x530270`.
     let gold_name = quads.iter().any(|q| {
         matches!(&q.content, QuadContent::Text { text: Some(t), color: Some(c), .. }
             if t == "Arcane Intellect" && (c[1] - 210.0 / 255.0).abs() < 1e-6)
     });
     assert!(gold_name, "aura name is gold, not white");
-    // …and so is the DURATION-REMAINING line — the same `0xffffd200`, not the description's
-    // white. Report B62: measured on the reporter's own 1.12.1 reference shot
-    // (`media/1530672450247856148`), the "29 minutes remaining" glyphs are exactly
-    // `(255, 210, 0)`, the same pixels as that shot's title row, while its description rows are
-    // `(255, 255, 255)`. Ours drew the line white, which is the whole report.
+    // So is the remaining line, the same `0xffffd200`, as in the reference's buff hover.
     let gold_remaining = quads.iter().any(|q| {
         matches!(&q.content, QuadContent::Text { text: Some(t), color: Some(c), .. }
             if t == "<2 mm>" && *c == [1.0, 210.0 / 255.0, 0.0, 1.0])
@@ -301,9 +286,8 @@ fn player_buff_hover_is_the_aura_variant() {
     assert!(s.take_errors().is_empty());
 }
 
-/// Law §3-BUFF's right column: the buff hover names the DISPEL CLASS where the spell hover would
-/// put a gray "Rank N" — "Magic" on Ice Armor, the half of B53 the gold name didn't cover — and it
-/// is gold, sharing the aura name's wrapper. A `rank` on the same view must NOT displace it.
+/// The buff builder's (`0x52f880`) right column is the dispel class, gold through the aura name's
+/// wrapper, where the spell hover puts a gray rank; a `rank` on the view must not displace it.
 #[test]
 fn player_buff_hover_names_the_dispel_class_in_gold() {
     let mut s = script();
@@ -312,7 +296,7 @@ fn player_buff_hover_names_the_dispel_class_in_gold() {
         168,
         SpellTooltipView {
             name: "Ice Armor".into(),
-            rank: Some("Rank 1".into()), // the spell variant's column — never the aura's
+            rank: Some("Rank 1".into()), // the spell variant's column, never the aura's
             dispel_type: Some("Magic".into()),
             aura_description: "Encases the caster in a layer of ice.".into(),
             ..Default::default()
@@ -350,9 +334,8 @@ fn player_buff_hover_names_the_dispel_class_in_gold() {
     assert!(s.take_errors().is_empty());
 }
 
-/// Law §3.6's equipped-item line and §3.8's reagents line — the two lines the 2026-07-25 reports
-/// found missing (B54, B56). Order: cast|cooldown → requires-item → requires-form → reagents →
-/// description, each requirement red while unmet.
+/// `0x52e610`'s line order: cast|cooldown, requires-item, requires-form, reagents, description,
+/// each requirement red while unmet.
 #[test]
 fn requirement_and_reagent_lines_render_in_law_order() {
     let mut s = script();
@@ -388,8 +371,8 @@ fn requirement_and_reagent_lines_render_in_law_order() {
         assert(TTTextLeft1:GetText() == "Shoot")
         assert(TTTextLeft2:GetText() == "30 yd range", "cost absent: range moves left")
         assert(TTTextLeft3:GetText() == "Instant")
-        assert(TTTextLeft4:GetText() == "Requires Wands", "law §3.6 sits above the reagents")
-        assert(string.find(TTTextLeft5:GetText(), "Light Feather") ~= nil, "law §3.8")
+        assert(TTTextLeft4:GetText() == "Requires Wands", "the requirement sits above the reagents")
+        assert(string.find(TTTextLeft5:GetText(), "Light Feather") ~= nil, "the reagents line")
         assert(TTTextLeft6:GetText() == "Attack with an equipped wand.", "description last")
     "#,
     )
@@ -401,10 +384,8 @@ fn requirement_and_reagent_lines_render_in_law_order() {
             if t == "Requires Wands" && *c == [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0])
     });
     assert!(red, "an unmet equipped-item requirement is red");
-    // The reagent's inline `|cffff2020` escape reaches the region VERBATIM: the engine paints
-    // the line's BASE colour white and the app's text layer resolves the escape into colour runs
-    // (`benilla::ui_text::markup`, covered by its own `color_runs_survive_the_wrap`). So what this
-    // layer owns is that the escape is neither stripped nor pre-flattened.
+    // The reagent's `|cffff2020` escape reaches the region verbatim over a white base colour; the
+    // app's text layer (`ui_text::markup`) turns it into colour runs.
     let verbatim = quads.iter().any(|q| {
         matches!(&q.content, QuadContent::Text { text: Some(t), color: Some(c), .. }
             if t == "Reagents: |cffff2020Light Feather|r" && *c == [1.0, 1.0, 1.0, 1.0])
@@ -416,9 +397,9 @@ fn requirement_and_reagent_lines_render_in_law_order() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The target-frame aura hover: SetUnitBuff/SetUnitDebuff render the aura variant for the token's
-/// sign-filtered list — WITHOUT the duration-remaining line (byte-verified: only SetPlayerBuff
-/// appends it, and no other unit carries a duration on the 1.12 wire anyway).
+/// `SetUnitBuff`/`SetUnitDebuff` render the aura variant from the unit's sign-filtered list, with
+/// no remaining line: only `SetPlayerBuff` appends it, and the 1.12 wire carries no other unit's
+/// durations.
 #[test]
 fn unit_buff_and_debuff_hover_render_the_aura_variant_without_remaining() {
     let mut s = script();
@@ -477,20 +458,9 @@ fn unit_buff_and_debuff_hover_render_the_aura_variant_without_remaining() {
     assert!(s.take_errors().is_empty());
 }
 
-/// **`SetPlayerBuff` reads a 1.12 cache position, not an Era ordinal** — the index space the whole
-/// `GetPlayerBuff*` family shares (`script::aura`'s header; pinned by `ref-BuffFrame.lua:105`,
-/// which passes `GetPlayerBuff`'s return straight in).
-///
-/// Every assertion here is a case the previous 1-based, sign-filtered reading got wrong, and got
-/// wrong *silently* — the plate still rendered, just for the wrong aura:
-///
-/// - position 1 is the SECOND aura, not the first again;
-/// - a debuff is reachable at all (the old sign filter defaulted to helpful, so no position ever
-///   resolved to one);
-/// - `-1` clears instead of showing the first buff. `BigWigs/Raids/Naxxramas/Loatheb.lua:260-271`
-///   feeds an unchecked `GetPlayerBuff(i, "HARMFUL")` in and breaks its scan when line 1 goes nil,
-///   so "shows something" there is an addon that never stops scanning;
-/// - a surplus filter argument is ignored (`CT_BuffMod/CT_BuffFrame.lua:151` passes one).
+/// `SetPlayerBuff` takes a 1.12 cache position, the `GetPlayerBuff` family's index space:
+/// `BuffFrame.lua:105` passes that return straight in. A miss, `-1` included, clears the plate,
+/// and a surplus filter argument is ignored.
 #[test]
 fn player_buff_hover_indexes_the_cache_position_not_a_filtered_ordinal() {
     let mut s = script();
@@ -509,7 +479,7 @@ fn player_buff_hover_indexes_the_cache_position_not_a_filtered_ordinal() {
             },
         );
     }
-    // The player's cache: two buffs then a debuff, ONE list, insertion-ordered (decision 0257).
+    // The player's cache: two buffs then a debuff, in one insertion-ordered list.
     s.set_auras(
         "player",
         Some(vec![
@@ -562,8 +532,8 @@ fn player_buff_hover_indexes_the_cache_position_not_a_filtered_ordinal() {
     assert!(s.take_errors().is_empty(), "{:?}", s.take_errors());
 }
 
-/// SetAction delegates by payload kind: a SPELL slot renders the spell view; an empty slot shows
-/// nothing; a miss records the ask.
+/// `SetAction` delegates by payload kind: a spell slot renders the spell view, and a spell the
+/// store lacks shows no plate and records the ask.
 #[test]
 fn action_hover_delegates_by_kind() {
     let mut s = script();
@@ -581,7 +551,7 @@ fn action_hover_delegates_by_kind() {
         25,
         Some(ActionSlot {
             kind: 0x00,
-            action: 5143, // not in the store — the ask channel fires
+            action: 5143, // not in the store: the ask channel fires
             ..Default::default()
         }),
     );
@@ -603,10 +573,8 @@ fn action_hover_delegates_by_kind() {
     assert!(s.take_errors().is_empty());
 }
 
-/// A MACRO slot's hover is the reference's `0x52b040`: ONE white line, the macro's name (the
-/// "normal" colour `0xc0cf60` = 0xffffffff, wow-re `tooltip-content-law.md`), and a slot whose
-/// macro no longer exists shows no plate at all. The director's report after 1636 landed: a macro
-/// on the bar had no tooltip — the arm was a pre-0983 `_ => Ok(())`.
+/// A macro slot's hover is the reference's `0x52b040`: one line, the macro's name in the normal
+/// colour (`0xc0cf60` holds `0xffffffff`, white); a slot whose macro is gone shows no plate.
 #[test]
 fn action_hover_on_a_macro_slot_shows_its_name_in_white() {
     let mut s = script();
@@ -684,12 +652,8 @@ fn trainer_service(spell_id: u32, name: &str, tooltip: TrainerTooltip) -> Traine
     }
 }
 
-/// `SetTrainerService` is a SELECTOR: it renders no line of its own and routes to whichever shared
-/// builder the app-side law picked. All three arms are pinned here — the item arm, the spell arm
-/// (with `altCaster` suppressing the reagents block), and a header row, which is a no-op.
-///
-/// The index is a VISIBLE row index, so row 1 is the "Arms" header and the services start at 2 —
-/// the same interleave `SetTradeSkillItem` has, and the same way to get it wrong.
+/// `SetTrainerService` renders no line of its own: it routes to the item or spell builder the app
+/// picked (`altCaster` drops the reagents), and its index is a visible row, so row 1 is a header.
 #[test]
 fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
     let mut s = script();
@@ -701,8 +665,8 @@ fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
             quality: 1,
             class: 2,
             subclass: 7,
-            // The type cell's word is app-resolved off ItemSubClass.dbc, never composed in the
-            // renderer — a view that carries none prints no type cell.
+            // The app resolves the type cell's word from ItemSubClass.dbc; a view without one
+            // prints no type cell.
             sub_class_display: Some("Sword".into()),
             ..Default::default()
         },
@@ -759,7 +723,7 @@ fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
     )
     .unwrap();
 
-    // Row 3: the class-trainer service -> the SPELL builder on the TAUGHT spell, reagents shown.
+    // Row 3: the class-trainer service goes to the spell builder on the taught spell.
     s.run(
         r#"
         TT:SetOwner(AB1, "ANCHOR_RIGHT")
@@ -781,7 +745,7 @@ fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
         "the gold description is part of the shared builder's law: {texts:?}"
     );
 
-    // Row 4: the same view, altCaster set -> the reagents block is gone, everything else stays.
+    // Row 4: the same view with altCaster set loses only the reagents block.
     s.run(
         r#"
         TT:SetOwner(AB1, "ANCHOR_RIGHT")
@@ -801,11 +765,8 @@ fn set_trainer_service_selects_the_builder_and_never_renders_its_own_line() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `SetCraftSpell` is `SetTrainerService`'s structural twin: a selector, not the two-line
-/// name/description stub it used to be. Both arms are pinned, and the assertion that matters most
-/// is the negative one — a rod recipe's hover shows the ROD's item tooltip while the same row's
-/// ICON is the spell's (Law D, decision 1107). Icon and tooltip disagreeing on one row is the
-/// verified shape, not a bug to reconcile.
+/// `SetCraftSpell` is a selector like `SetTrainerService`: a rod recipe hovers the rod's item
+/// tooltip while its row's icon is the spell's, which is the reference's shape, not a bug.
 #[test]
 fn set_craft_spell_selects_the_builder_like_the_trainer_hover_does() {
     let mut s = script();
@@ -893,10 +854,8 @@ fn set_craft_spell_selects_the_builder_like_the_trainer_hover_does() {
     assert!(s.take_errors().is_empty());
 }
 
-/// Law §3-BUFF-DURATION's **gate**: `0x532b00` skips the duration block on `untilCancelled`
-/// (`532bda: 8b 46 0c` / `532bdf: 75 2d`) — never on "has this aura a duration yet". The three
-/// cases below are the ones that separate the two questions, and the middle two are what the old
-/// `duration > 0 && left > 0` gate got wrong.
+/// `0x532b00` skips the remaining line on `untilCancelled` (`0x532bda`, `0x532bdf`), never on
+/// whether the aura has a duration yet.
 #[test]
 fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
     let mut s = script();
@@ -943,8 +902,7 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
         ..Default::default()
     };
 
-    // 1 · Permanent — and carrying a duration anyway, so only the FLAG can be doing the work.
-    // Title + description, nothing else.
+    // 1 · Permanent, with a duration anyway, so only the flag can suppress the line.
     assert_eq!(
         show(AuraState {
             duration: 1800.0,
@@ -956,8 +914,7 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
         "untilCancelled suppresses the line even with a live duration on the record"
     );
 
-    // 2 · Timed, but no duration packet has landed yet — the frame an aura appears. The old gate
-    // blanked this; the reference shows the line, counting from zero.
+    // 2 · Timed, before any duration packet: the reference shows the line, counting from zero.
     assert_eq!(
         show(AuraState {
             duration: 0.0,
@@ -969,8 +926,7 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
         "a timed aura's first frames still carry the line"
     );
 
-    // 3 · Lapsed — the reading the reference's own truncating seconds arm produces, which the old
-    // gate hid entirely.
+    // 3 · Lapsed: the reference's truncating seconds arm reads 0.
     assert_eq!(
         show(AuraState {
             duration: 30.0,
@@ -982,8 +938,7 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
         "a lapsed aura reads 0, it does not lose the line"
     );
 
-    // Control: an ordinary live aura still counts, so none of the above is the line going missing
-    // for an unrelated reason.
+    // Control: an ordinary live aura still counts down.
     assert_eq!(
         show(AuraState {
             duration: 1800.0,
@@ -996,9 +951,9 @@ fn the_remaining_line_is_gated_on_until_cancelled_not_on_the_duration() {
     assert!(s.take_errors().is_empty());
 }
 
-/// `GetRewardSpell()` / `GetQuestLogRewardSpell()` answer `texture, name, isTradeskillSpell` —
-/// three nils when the quest teaches nothing (the reference's own `(nil,nil,nil)` kind) — and
-/// `GameTooltip:SetQuestRewardSpell()` / `SetQuestLogRewardSpell()` render that spell (1944).
+/// `GetRewardSpell()` and `GetQuestLogRewardSpell()` answer `texture, name, isTradeskillSpell`,
+/// three nils when the quest teaches nothing, and `SetQuestRewardSpell()` and
+/// `SetQuestLogRewardSpell()` render that spell.
 #[test]
 fn quest_reward_spell_getters_and_hovers() {
     let mut s = script();
@@ -1066,7 +1021,7 @@ fn quest_reward_spell_getters_and_hovers() {
         }],
         ..Default::default()
     });
-    // The detail hangs on the row now, so both readers go through the selection (2247).
+    // The detail hangs on the row, so both readers go through the selection.
     s.run("SelectQuestLogEntry(1)").unwrap();
     assert_eq!(
         s.eval::<(String, String, Option<i64>)>("return GetQuestLogRewardSpell()")
diff --git a/crates/benilla-ui/src/script/tests/tooltip_unit.rs b/crates/benilla-ui/src/script/tests/tooltip_unit.rs
index 5869e6dc..f15b9997 100644
--- a/crates/benilla-ui/src/script/tests/tooltip_unit.rs
+++ b/crates/benilla-ui/src/script/tests/tooltip_unit.rs
@@ -1,20 +1,11 @@
-//! The engine unit tooltip builder (decision 0274 P3, law per 0276): the level-line composition
-//! (four `TOOLTIP_UNIT_LEVEL*` keys, the `ELITE`/`BOSS` rank table, "??", `CORPSE`, "Race Class"
-//! over `PLAYER` — all seeded here as marked stand-ins, see [`seed_level_strings`]), the flag lines
-//! (PvP white / Skinnable red / Civilian green), the world-mouseover drive (default anchor +
-//! `UPDATE_MOUSEOVER_UNIT` recolor + the fade arm on loss), and the health-bar watcher.
+//! The engine unit tooltip builder: the level line, the flag lines, the world-mouseover drive and
+//! the health-bar watcher.
 
 use super::common::script;
 use crate::script::*;
 
-/// A stand-in string table for the level line — the four `TOOLTIP_UNIT_LEVEL*` templates and the
-/// three word slots that fill them, **deliberately not the shipped wording**. What these tests
-/// establish is *which key* each slot combination reaches and what fills it, never what the
-/// sentence says (decision 2045, "assert the identifier, not the sentence"), and here that is not
-/// a formality: `TOOLTIP_UNIT_LEVEL_CLASS`'s enUS "Level %s %s" is word-for-word
-/// `FRIENDS_LEVEL_TEMPLATE`, `UNIT_TYPE_LEVEL_TEMPLATE` and `CHARACTER_SELECT_INFO`, and the bare
-/// template's "Level %s" is also `ITEM_LEVEL`, `LEVEL_GAINED` and `UNIT_LEVEL_TEMPLATE`. An
-/// assertion on the English would pass on all seven.
+/// Stand-in level-line strings, deliberately not the shipped wording: the enUS templates repeat
+/// other globals word for word, so only a marked stand-in shows which key was reached.
 fn seed_level_strings(s: &mut UiScript) {
     s.run(
         r#"
@@ -46,7 +37,7 @@ fn wolf() -> UnitState {
     }
 }
 
-/// The creature law: gold name, subtitle, the CLASS_TYPE level line, red Skinnable.
+/// A creature: gold name, subtitle, the CLASS_TYPE level line, red Skinnable.
 #[test]
 fn creature_line_law() {
     let mut s = script();
@@ -72,7 +63,7 @@ fn creature_line_law() {
         -- A RECOGNISED token naming nothing answers nil...
         assert(tt:SetUnit("party4") == nil, "a recognised but absent unit answers nil")
         -- ...while an UNRECOGNISED one raises, because SetUnit resolves through the client's one
-        -- token resolver like every Unit* verb (wow-re raid-roster-bindings.md §1: a token matching
+        -- token resolver like every Unit* verb (`0x515970`: a token matching
         -- none of the nine prefixes reaches `luaL_error("Unknown unit name: %s")` and longjmps).
         -- This used to read `SetUnit("nosuch") == nil`, which was the refuted claim.
         assert(pcall(tt.SetUnit, tt, "nosuch") == false, "an unrecognised token raises")
@@ -82,10 +73,8 @@ fn creature_line_law() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The snapshot the app pushes for a creature the client has only just seen: the DESCRIPTOR's
-/// fields are in (level, reaction, the skinnable flag) and everything the creature record carries
-/// — name, subtitle, type word, rank, civilian/leader — is still absent, because they all arrive
-/// together in the one `SMSG_CREATURE_QUERY_RESPONSE` that fills `CGUnit+0xb30`.
+/// A creature just seen: its descriptor fields are in, but the record fields (name, subtitle, type,
+/// rank, civilian) wait for the `SMSG_CREATURE_QUERY_RESPONSE` that fills `CGUnit+0xb30`.
 fn unqueried_wolf() -> UnitState {
     UnitState {
         exists: true,
@@ -101,22 +90,9 @@ fn unqueried_wolf() -> UnitState {
     }
 }
 
-/// **A name still in flight titles the plate `UNKNOWNOBJECT` — never an empty line** (decision
-/// 2040, closing 2002's residue).
-///
-/// The builder's name read is `CGUnit_C::GetUnitName 0x609210` (`0x52a187`), the same resolver
-/// `UnitName 0x517020` delegates to, and every one of its misses — a null `CGUnit+0xb30`
-/// (`0x609353 je 0x609324`) among them — ends at the same `FrameScript_GetText("UNKNOWNOBJECT")`
-/// tail. So the verb and the plate answer the same string for the same instant, and because the
-/// string is read out of the VM's `_G` it translates with `GlobalStrings.lua`.
-///
-/// The builder has NO counterpart to `UnitName`'s two nils: the `"player"` fast path is the
-/// *binding's* (`0x517083`, before any resolve), so a player whose name has not arrived titles
-/// `UNKNOWNOBJECT` too; and a token resolving to nothing never reaches a builder at all — the
-/// entry gate hands back no object, `SetUnit` answers nil and no plate is drawn.
-///
-/// Failure looks like the empty first line the residue named: `TextLeft1` reads `""`, the plate
-/// measures to a blank row, and the level line reads as the tooltip's title.
+/// `CGUnit_C::GetUnitName 0x609210` (`0x52a187`) reads the name, as for `UnitName 0x517020`, and
+/// every miss, a null `CGUnit+0xb30` among them (`0x609353 je 0x609324`), ends at
+/// `FrameScript_GetText("UNKNOWNOBJECT")`. The `"player"` fast path is the binding's (`0x517083`).
 #[test]
 fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     let mut s = script();
@@ -145,9 +121,7 @@ fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     )
     .unwrap();
 
-    // The query answers: the very next render replaces the placeholder with the real name and
-    // fills the record's lines. (Live, the hover feed re-drives this without the mouse moving —
-    // its rebuild key is the whole line-affecting snapshot, `ui_tooltip::lines_view`.)
+    // The query answers: the next render replaces the placeholder and fills the record's lines.
     let mut answered = unqueried_wolf();
     answered.name = Some("Timber Wolf".into());
     answered.subtitle = Some("Alpha".into());
@@ -165,8 +139,7 @@ fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     )
     .unwrap();
 
-    // An EMPTY (or absent) global is the same miss as no global — `0x609324`'s own check, which
-    // falls to the binary's literal `0x860fa4`.
+    // An empty or absent global falls to the binary's own literal `0x860fa4` (`0x609324`).
     s.set_unit("target", Some(unqueried_wolf()));
     s.run(
         r#"
@@ -177,8 +150,7 @@ fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     )
     .unwrap();
 
-    // The `"player"` fast path is the BINDING's, not the builder's: a player whose name-cache row
-    // has not answered titles the same placeholder, where `UnitName("player")` would push nil.
+    // A player whose name has not arrived titles the placeholder; `UnitName("player")` pushes nil.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -203,18 +175,15 @@ fn a_pending_name_titles_unknownobject_and_the_answer_replaces_it() {
     )
     .unwrap();
 
-    // The GUID-0 counterpart: a recognised token naming nothing resolves to no object, so no
-    // builder runs — nil, and no plate. (There is no third answer; the builder never sees it.)
+    // A recognised token naming nothing resolves to no object, so no builder runs.
     s.run(r#"assert(TT:SetUnit("party4") == nil, "an absent unit draws no plate at all")"#)
         .unwrap();
     assert!(s.take_errors().is_empty());
 }
 
-/// The faction-name line sits between the level line and "PvP" (the builder-tail block the §2
-/// order omitted — the director's Marshal McBride reference: Level, Stormwind, PvP); the
-/// CIVILIAN line is the dishonorable-kill warning, whole gate (`0x612550`): PvP bit + civilian
-/// flag + HOSTILE + GREY/trivial — a friendly (or non-grey) civilian never shows it; LEADER
-/// (white) needs only the PvP bit + the flag (`0x6125c0`).
+/// The faction line sits between the level line and "PvP" (`0x529fe0`). Civilian needs the PvP
+/// bit, the flag, hostility and a grey level (`0x612550`); Leader only the PvP bit and the flag
+/// (`0x6125c0`).
 #[test]
 fn faction_line_and_civilian_gate() {
     let mut s = script();
@@ -224,7 +193,7 @@ fn faction_line_and_civilian_gate() {
         level: 30,
         ..Default::default()
     });
-    // The reference shot's shape: a FRIENDLY civilian guard — faction line, PvP, NO Civilian.
+    // A friendly civilian guard: faction line and PvP, no Civilian.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -252,7 +221,7 @@ fn faction_line_and_civilian_gate() {
     "#,
     )
     .unwrap();
-    // The warning case: HOSTILE + grey (level 20 vs player 30 → gap 10 > band 8) + PvP-flagged.
+    // Hostile, PvP-flagged and grey (a gap of 10 is past the band of 8): the warning shows.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -278,7 +247,7 @@ fn faction_line_and_civilian_gate() {
     "#,
     )
     .unwrap();
-    // Same unit but NOT grey (level 25, gap 5 ≤ band 8): the warning drops.
+    // Not grey (a gap of 5 is inside the band of 8): no warning.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -380,7 +349,7 @@ fn level_line_variants() {
     "#,
     )
     .unwrap();
-    // The "??" gate, byte-pinned: HOSTILE (reaction ≤ 2) + 10 levels up reads "??"…
+    // A hostile unit (reaction 2 or less) 10 levels up reads "??".
     let ten_up = |reaction: u8, is_player: bool| UnitState {
         exists: true,
         name: Some("Elder".into()),
@@ -400,7 +369,7 @@ fn level_line_variants() {
     "#,
     )
     .unwrap();
-    // …but UNFRIENDLY (reaction 3) does not — the internal bound is hated/hostile only…
+    // An unfriendly one (reaction 3) does not.
     s.set_unit("target", Some(ten_up(3, false)));
     s.run(
         r#"
@@ -409,7 +378,7 @@ fn level_line_variants() {
     "#,
     )
     .unwrap();
-    // …and PLAYERS never read "??" regardless of reaction/delta.
+    // Players never read "??".
     s.set_unit("target", Some(ten_up(2, true)));
     s.run(
         r#"
@@ -421,9 +390,7 @@ fn level_line_variants() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The world-mouseover drive: `world_tooltip_unit` fires the default-anchor script, renders,
-/// fires `UPDATE_MOUSEOVER_UNIT` (the Lua recolor), and the health bar tracks later pushes;
-/// hover loss arms the fade (alpha ramps, then hides).
+/// `world_tooltip_unit` fires the default anchor, renders, then fires `UPDATE_MOUSEOVER_UNIT`.
 #[test]
 fn world_hover_drive_and_health_watcher() {
     let mut s = script();
@@ -466,8 +433,7 @@ fn world_hover_drive_and_health_watcher() {
     "#,
     )
     .unwrap();
-    // The handler's seating resolved: bottom-right of the 800×600 screen, −13 in, 70 up.
-    // (Answer the line measures first — the auto-size needs them before the plate has a rect.)
+    // The auto-size needs the line measures before the plate has a rect.
     let answers: Vec<(u32, f32, f32, u64)> = s
         .fontstrings_needing_measure()
         .iter()
@@ -480,7 +446,7 @@ fn world_hover_drive_and_health_watcher() {
                   "plate at the default corner, got " .. tostring(GameTooltip:GetRight()) .. "," .. tostring(GameTooltip:GetBottom()))"#,
     )
     .unwrap();
-    // A health push for the LIVE token re-drives the bar without a rebuild.
+    // A health push for the live token re-drives the bar without a rebuild.
     let mut hurt = wolf();
     hurt.health = 12;
     s.set_unit("mouseover", Some(hurt));
@@ -488,7 +454,6 @@ fn world_hover_drive_and_health_watcher() {
         r#"assert(GameTooltipStatusBar:GetValue() == 12, "the health watcher tracked the push")"#,
     )
     .unwrap();
-    // Hover loss: the fade arms; past the ramp the tooltip hides.
     s.world_tooltip_fade();
     s.tick(0.6);
     s.run(r#"assert(not GameTooltip:IsShown(), "faded out after the ramp")"#)
@@ -496,9 +461,8 @@ fn world_hover_drive_and_health_watcher() {
     assert!(s.take_errors().is_empty());
 }
 
-/// The minimap BLIP tooltip (`minimap_tooltip`): refuses without a Minimap widget; with one, one
-/// white line seated against the widget (the INTERIM ANCHOR_LEFT law), world-owned so the shared
-/// fade arm hides it on hover loss.
+/// The minimap blip tooltip (`minimap_tooltip`): refused without `UIParent`, otherwise one line
+/// seated above the cursor, world-owned so the shared fade hides it on hover loss.
 #[test]
 fn minimap_blip_tooltip_shows_and_fades() {
     let mut s = script();
@@ -524,8 +488,7 @@ fn minimap_blip_tooltip_shows_and_fades() {
     "#,
     )
     .unwrap();
-    // Seated 5 px from the 800-wide screen's right edge: the clamp (the client's G bit4)
-    // slides the plate back inside instead of letting it clip (director-caught).
+    // Seated 5 px from the right edge, the clamp (the client's G bit4) slides the plate inside.
     let answers: Vec<(u32, f32, f32, u64)> = s
         .fontstrings_needing_measure()
         .iter()
@@ -537,11 +500,10 @@ fn minimap_blip_tooltip_shows_and_fades() {
         r#"assert(GameTooltip:GetRight() <= 800, "clamped inside the screen, got " .. tostring(GameTooltip:GetRight()))"#,
     )
     .unwrap();
-    // Follow: a move re-seats without rebuilding the line.
     s.world_tooltip_move(400.0, 300.0);
     s.run(r#"assert(GameTooltipTextLeft1:GetText() == "Stormwind", "content survives a move")"#)
         .unwrap();
-    // Hover loss rides the shared world fade: armed, then hidden past the ramp.
+    // Hover loss rides the shared world fade.
     s.world_tooltip_fade();
     s.tick(0.6);
     s.run(r#"assert(not GameTooltip:IsShown(), "faded out after the ramp")"#)
diff --git a/crates/benilla-ui/src/script/tests/toplevel.rs b/crates/benilla-ui/src/script/tests/toplevel.rs
index 5176fd1a..958ad2b6 100644
--- a/crates/benilla-ui/src/script/tests/toplevel.rs
+++ b/crates/benilla-ui/src/script/tests/toplevel.rs
@@ -1,16 +1,10 @@
-//! The `toplevel` flag and the raise law — `SetToplevel`/`IsToplevel`, `Raise`/`Lower`, and the
-//! raise itself with its real trigger (Show) and its real gate (occlusion). The mechanism, the byte
-//! addresses and the clause-by-clause mapping onto our order model are in `script::object::toplevel`.
-//!
-//! Every test drives the PRODUCTION path — the Lua bindings, the loader, and the real
-//! `mouse_button`/`mouse_move` entry points — and asserts on the two things that are actually
-//! observable: `GetFrameLevel()` (the arithmetic) and the extracted painter order (the pixels).
+//! The `toplevel` flag and the raise: `SetToplevel`/`IsToplevel`, `Raise`/`Lower`, and the raise
+//! on show, press and drag, gated on occlusion. Tests assert `GetFrameLevel()` and the paint order.
 
 use super::common::script;
 use crate::script::{QuadContent, UiScript};
 
-/// The order textures actually paint in, by their texture path — the render list `extract` returns
-/// IS the draw order (`order::traversal`'s ZKey sort).
+/// Texture paths in paint order: the list `extract` returns is the draw order.
 fn painted(s: &mut UiScript) -> Vec<String> {
     s.resolve();
     s.extract()
@@ -27,14 +21,8 @@ fn level(s: &mut UiScript, frame: &str) -> i64 {
         .unwrap()
 }
 
-/// Two overlapping MEDIUM frames: `Board` — already on screen and sitting at frame level **5** —
-/// and `Dialog`, born at level 0 and hidden.
-///
-/// The level split is the point. A frame's link stamp already lifts it within its bucket when it is
-/// shown (`resequence_to_tail`, decision 0557), so a same-level sibling would prove nothing about
-/// the raise; **level outranks the link stamp** in the draw key, so nothing but a real level bump
-/// can get `Dialog` over `Board`. This is the shape of the complaint the law answers: a dialog
-/// opening behind a window that happens to sit higher in its stratum.
+/// Two overlapping MEDIUM frames: `Board`, shown at level 5, and `Dialog`, hidden at level 0. The
+/// level outranks the link stamp in the draw key, so only a real level bump puts `Dialog` on top.
 fn board_and_dialog() -> UiScript {
     let mut s = script();
     s.set_screen_size(800.0, 600.0);
@@ -58,11 +46,9 @@ fn board_and_dialog() -> UiScript {
     s
 }
 
-// ── The flag ────────────────────────────────────────────────────────────────────────────────────
+// ── The flag ──
 
-/// `SetToplevel`/`IsToplevel` round-trip, including the reference's **default-true** optional
-/// argument (`0x775440` marshals an optional boolean defaulting to true, unlike `SetMovable`).
-/// Nothing is born toplevel.
+/// `SetToplevel`'s optional argument defaults to true (`0x775440`), unlike `SetMovable`'s.
 #[test]
 fn the_flag_round_trips_and_defaults_off() {
     let s = script();
@@ -75,27 +61,19 @@ fn the_flag_round_trips_and_defaults_off() {
     assert!(s.eval::<bool>("return F:IsToplevel()").unwrap());
     s.run("F:SetToplevel(false)").unwrap();
     assert!(!s.eval::<bool>("return F:IsToplevel()").unwrap());
-    // The omitted argument is TRUE, not false — the reference's `SetToplevel()` turns the bit ON.
     s.run("F:SetToplevel()").unwrap();
     assert!(
         s.eval::<bool>("return F:IsToplevel()").unwrap(),
         "SetToplevel() with no argument sets the bit"
     );
-    // Lua truthiness, like every other flag setter here: the corpus writes SetToplevel(1).
+    // Lua truthiness: addons write `SetToplevel(1)`.
     s.run("F:SetToplevel(nil); F:SetToplevel(1)").unwrap();
     assert!(s.eval::<bool>("return F:IsToplevel()").unwrap());
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `toplevel="true"` in XML lands on the real method — it was a warn-once gap in the loader until
-/// this law existed, which left every window authored toplevel (thirteen of our own frames, 82
-/// corpus addons) unable to come to the front while `SetToplevel` did not exist at all.
-///
-/// `enableKeyboard` used to be warned here on the same principle — implementing one clause is not
-/// a licence to go quiet about the other. It now lands on a real `EnableKeyboard`, so the warning
-/// is gone and this asserts the flag instead. Key *delivery* reads the same flag
-/// (`script::keyboard`'s walk, 1319); the flag and a handler stay separable in the reference too
-/// (`frame-key-script-delivery.md` §3.2), which is why this asserts the flag alone.
+/// The XML `toplevel` and `enableKeyboard` attributes set the flags their methods read; in the
+/// reference the keyboard flag is separate from any handler (`0x76af00`).
 #[test]
 fn the_xml_toplevel_and_enable_keyboard_attributes_both_reach_their_methods() {
     let s = script();
@@ -126,8 +104,7 @@ fn the_xml_toplevel_and_enable_keyboard_attributes_both_reach_their_methods() {
         s.eval::<bool>("return XmlTop:IsKeyboardEnabled()").unwrap(),
         "the XML attribute must reach the flag"
     );
-    // Default false, and the setter round-trips both ways — a frame that never asked is not in the
-    // bucket (`0x76af00` is reached from the attribute or an explicit call, never a ctor).
+    // Off by default: `0x76af00` runs from the attribute or a call, never a constructor.
     s.run("Plain = CreateFrame('Frame', 'PlainKbd')").unwrap();
     assert!(!s.eval::<bool>("return Plain:IsKeyboardEnabled()").unwrap());
     s.run("Plain:EnableKeyboard(true)").unwrap();
@@ -136,10 +113,9 @@ fn the_xml_toplevel_and_enable_keyboard_attributes_both_reach_their_methods() {
     assert!(!s.eval::<bool>("return Plain:IsKeyboardEnabled()").unwrap());
 }
 
-// ── The raise on Show ───────────────────────────────────────────────────────────────────────────
+// ── The raise on Show ──
 
-/// The control, and the behaviour before this landed: a **non-toplevel** frame is shown and moves
-/// nowhere. `Dialog` paints under `Board` because its level is lower, exactly as the draw key says.
+/// The control: a frame that is not toplevel keeps its level when shown, and paints under `Board`.
 #[test]
 fn a_non_toplevel_frame_does_not_move_when_shown() {
     let mut s = board_and_dialog();
@@ -153,14 +129,8 @@ fn a_non_toplevel_frame_does_not_move_when_shown() {
     );
 }
 
-/// The headline: the same frame, marked `toplevel`, comes to the front on **Show** — the trigger
-/// the law names (`effective_visible_show 0x76ae10` @`0x76aee0`), not on a click.
-///
-/// The arithmetic is pinned here because it is the whole mapping onto our order model. Visible
-/// MEDIUM levels are `{0 (Dialog), 5 (Board)}`; `level_compact 0x764eb0` renumbers those occupied
-/// levels contiguously into `[0, 2)` — Board 5 → 1 — and the raise then writes
-/// `level := bucket->count` = **2**. Not a live max-scan (`5 + 1`), not a re-stamp: one above the
-/// top *occupied* level, counted after the compaction.
+/// A toplevel frame raises on show (`0x76ae10` at `0x76aee0`): compaction (`0x764eb0`) renumbers
+/// the occupied levels `{0, 5}` to `[0, 2)`, then the raise writes `level := bucket->count`, 2.
 #[test]
 fn a_raise_is_top_occupied_level_plus_one_after_compaction() {
     let mut s = board_and_dialog();
@@ -184,15 +154,9 @@ fn a_raise_is_top_occupied_level_plus_one_after_compaction() {
     );
 }
 
-/// The trigger is the **`effectiveVisible` false→true transition**, not the `Show()` call: a frame
-/// whose own `shown` bit is already set raises when an ancestor's Show finally makes it visible, and
-/// a `Show()` that changes no effective visibility raises nothing.
-///
-/// The setup order is load-bearing and is worth reading as the law's own proof. `Holder` is hidden
-/// *before* `Dialog:Show()`, so that Show is not a transition — leave it visible and `Dialog` raises
-/// there instead, ends up above everything, and the transition under test then correctly declines
-/// because nothing is left to raise over. (That mis-ordering is what the first draft of this test
-/// did; the gate was right and the fixture was wrong.)
+/// The trigger is the effective-visibility transition, not the `Show` call. `Holder` is hidden
+/// before `Dialog:Show()` so that call is no transition; otherwise `Dialog` raises there and has
+/// nothing left to raise over.
 #[test]
 fn the_trigger_is_the_effective_visibility_transition_not_the_show_call() {
     let mut s = board_and_dialog();
@@ -217,8 +181,8 @@ fn the_trigger_is_the_effective_visibility_transition_not_the_show_call() {
     assert_eq!(level(&mut s, "Board"), 5, "and compacts nothing");
 
     s.run("Holder:Show()").unwrap();
-    // Occupied visible MEDIUM levels at the raise: Holder 0, Dialog 1, Board 5 → compaction
-    // renumbers to {0, 1, 2} (Board → 2), count 3, and the raise writes Dialog := 3.
+    // Levels at the raise are Holder 0, Dialog 1, Board 5; compaction makes Board 2, count 3, and
+    // the raise writes Dialog := 3.
     assert_eq!(
         level(&mut s, "Dialog"),
         3,
@@ -227,11 +191,9 @@ fn the_trigger_is_the_effective_visibility_transition_not_the_show_call() {
     assert_eq!(level(&mut s, "Board"), 2, "the compaction ran with it");
 }
 
-// ── The gate ────────────────────────────────────────────────────────────────────────────────────
+// ── The gate ──
 
-/// **Occlusion-gated**: a toplevel frame that overlaps nothing changes nothing at all. The gate sits
-/// *before* the compaction in `0x7650f0`, so a declined raise leaves the whole stratum's levels
-/// untouched too — `Board` keeps its authored 5.
+/// The occlusion gate runs before the compaction in `0x7650f0`, so a declined raise moves no level.
 #[test]
 fn a_raise_on_a_frame_that_overlaps_nothing_is_a_total_no_op() {
     let mut s = board_and_dialog();
@@ -253,9 +215,7 @@ fn a_raise_on_a_frame_that_overlaps_nothing_is_a_total_no_op() {
     );
 }
 
-/// The scan runs from the frame's **own level upward** (`for lvl = T->+0xc4; lvl < bucket->count`).
-/// A toplevel frame whose only overlap is with something *below* it is already in front of it, so
-/// there is nothing to raise over.
+/// The occlusion scan starts at the frame's own level (`for lvl = T->+0xc4; lvl < bucket->count`).
 #[test]
 fn the_scan_ignores_frames_below_the_raised_frames_own_level() {
     let mut s = board_and_dialog();
@@ -276,9 +236,7 @@ fn the_scan_ignores_frames_below_the_raised_frames_own_level() {
     assert_eq!(level(&mut s, "Board"), 3);
 }
 
-/// A window overlaps its own children by construction, so the scan excludes the raised frame's
-/// subtree (`is_descendant 0x767010`). Without that clause every toplevel frame with content in it
-/// would raise on every trigger.
+/// The scan excludes the raised frame's own subtree (`0x767010`).
 #[test]
 fn the_scan_excludes_the_raised_frames_own_subtree() {
     let mut s = board_and_dialog();
@@ -299,10 +257,7 @@ fn the_scan_excludes_the_raised_frames_own_subtree() {
     );
 }
 
-/// A raise **never changes the stratum** — `0x7650f0` never writes `+0xc0`. A LOW toplevel frame
-/// raises over its LOW neighbours and stays under every MEDIUM frame, however many times it is
-/// raised. (This is the mechanism that could not have fixed the party-frame-through-loot-window
-/// bug: wow-re's CLAIM 2, refuted.)
+/// `0x7650f0` never writes the stratum (`+0xc0`), so a LOW toplevel frame raises within LOW only.
 #[test]
 fn a_raise_can_never_lift_a_frame_out_of_its_stratum() {
     let mut s = script();
@@ -354,16 +309,11 @@ fn a_raise_can_never_lift_a_frame_out_of_its_stratum() {
     );
 }
 
-// ── Propagation and compaction ──────────────────────────────────────────────────────────────────
+// ── Propagation and compaction ──
 
-/// `propagate = 1` shifts **same-strata** children by the same delta (`0x76a4f0` @`0x76a58a`), so
-/// the raised subtree keeps its internal order; cross-strata children are untouched
-/// (`0x76a582: cmp …; jne`).
-///
-/// The arithmetic in full. Visible MEDIUM levels before the raise are `{0 Dialog, 1 Kid, 2 Grandkid,
-/// 5 Board}`; compaction maps them to `{0, 1, 2, 3}` (Board 5 → 3) and reports `count = 4`. The
-/// raise writes `Dialog := 4`, i.e. `delta = +4`, and pushes that same +4 into Kid (1 → 5) and
-/// Grandkid (2 → 6) — gaps and order preserved. `Cross`, moved to the DIALOG stratum, keeps its 1.
+/// The raise's `propagate = 1` shifts same-strata children by its delta (`0x76a4f0` at
+/// `0x76a58a`) and skips the others (`0x76a582`). Levels `{0, 1, 2, 5}` compact to `{0, 1, 2, 3}`,
+/// so Dialog goes to 4 and Kid and Grandkid move by the same +4.
 #[test]
 fn the_raised_subtree_shifts_by_one_delta_and_keeps_its_internal_order() {
     let mut s = board_and_dialog();
@@ -394,12 +344,8 @@ fn the_raised_subtree_shifts_by_one_delta_and_keeps_its_internal_order() {
     );
 }
 
-/// Compaction is what keeps `level := top + 1` from ratcheting. Two overlapping toplevel windows
-/// traded back and forth twenty times settle inside a two-level band instead of climbing one step
-/// per show — and the frame shown last is on top every single time.
-///
-/// Without `level_compact 0x764eb0` this test ends at level 20, and a long session ends at
-/// `u16::MAX`.
+/// Compaction (`0x764eb0`) keeps `level := top + 1` from climbing: twenty alternating raises stay
+/// within a two-level band.
 #[test]
 fn compaction_bounds_the_raise_across_repeated_shows() {
     let mut s = script();
@@ -436,11 +382,10 @@ fn compaction_bounds_the_raise_across_repeated_shows() {
     );
 }
 
-// ── The Lua verbs ───────────────────────────────────────────────────────────────────────────────
+// ── The Lua verbs ──
 
-/// `Frame:Raise()` — the explicit script call (`0x775a50` → `0x76a5b0` → `0x7650f0(force = 1)`).
-/// Called on a **non-toplevel** frame it acts on the nearest toplevel ancestor, and on nothing at
-/// all when there is none: the gate lives in the worker, so no call site has to check.
+/// `Raise` (`0x775a50`, then `0x76a5b0`, then `0x7650f0` with force 1) acts on the nearest toplevel
+/// self or ancestor, and on nothing when there is none.
 #[test]
 fn lua_raise_acts_on_the_nearest_toplevel_ancestor_and_is_silent_without_one() {
     let mut s = board_and_dialog();
@@ -465,7 +410,7 @@ fn lua_raise_acts_on_the_nearest_toplevel_ancestor_and_is_silent_without_one() {
         "raising a child raised the toplevel window it lives in"
     );
 
-    // A frame with no toplevel in its chain: a total no-op, and not an error.
+    // No toplevel in the chain: a no-op, not an error.
     let board_before = level(&mut s, "Board");
     let loose_before = level(&mut s, "Loose");
     s.run("Loose:Raise()").unwrap();
@@ -474,9 +419,7 @@ fn lua_raise_acts_on_the_nearest_toplevel_ancestor_and_is_silent_without_one() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// `Frame:Lower()` is a **verified no-op stub** in build 5875 (`0x7652a0` = `xor eax,eax; ret 4`,
-/// its frame argument never read). It exists so a caller gets the reference's silence rather than a
-/// nil-call error — and it must not become "the opposite of Raise".
+/// The reference's `Lower` does nothing (`0x7652a0`: `xor eax,eax; ret 4`), and neither does ours.
 #[test]
 fn lua_lower_exists_and_does_nothing() {
     let mut s = board_and_dialog();
@@ -487,9 +430,7 @@ fn lua_lower_exists_and_does_nothing() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The drag-start trigger (`0x7652b0` @`0x7652d7`): grabbing a movable toplevel window brings it
-/// forward before the drag begins. This was the deferral `object::movable`'s doc carried ("benilla
-/// has no raise law yet") and it is closed.
+/// `StartMoving` raises a toplevel window before the drag begins (`0x7652b0` at `0x7652d7`).
 #[test]
 fn starting_a_move_raises_the_dragged_window() {
     let mut s = board_and_dialog();
@@ -516,7 +457,7 @@ fn starting_a_move_raises_the_dragged_window() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-// ── The mouse-DOWN trigger ──────────────────────────────────────────────────────────────────────
+// ── The mouse-down trigger ──
 
 /// The centre of `name`'s resolved rect, in the coordinate space [`UiScript::mouse_button`] takes.
 fn centre(s: &UiScript, name: &str) -> (f32, f32) {
@@ -529,11 +470,7 @@ fn centre(s: &UiScript, name: &str) -> (f32, f32) {
     (x as f32, y as f32)
 }
 
-/// **A press brings the window forward** — the trigger at `0x766392` in the mouse-down handler
-/// `0x7662c0`, the last of the six census sites to be wired (wow-re ledger `0x7662c0`).
-///
-/// Without it `toplevel` gives only half the behaviour a player reads as "windows": a window you
-/// *open* comes to the front, and a window you *click* stays buried under whatever is on top of it.
+/// A press raises the window: the trigger at `0x766392` in the mouse-down handler `0x7662c0`.
 #[test]
 fn pressing_a_toplevel_window_brings_it_to_the_front() {
     let mut s = board_and_dialog();
@@ -550,7 +487,7 @@ fn pressing_a_toplevel_window_brings_it_to_the_front() {
     s.resolve();
     assert!(level(&mut s, "Dialog") < level(&mut s, "Board"));
 
-    // A point inside Dialog and clear of Board, so the hit is unambiguous.
+    // Board overlaps Dialog's centre but takes no mouse, so the hit is Dialog.
     let (x, y) = centre(&s, "Dialog");
     assert_eq!(s.hit_test_name(x, y).as_deref(), Some("Dialog"));
     s.mouse_button(x, y, "LeftButton", true);
@@ -562,10 +499,7 @@ fn pressing_a_toplevel_window_brings_it_to_the_front() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// The trigger is **UNGUARDED** — there is no toplevel test at the call site. The worker resolves
-/// the nearest toplevel *self-or-ancestor*, so pressing a plain child raises the window that owns
-/// it. This is the clause that makes clicking a window's button, tab or background art work at all;
-/// with a guard out here, only a press landing on the window frame itself would raise.
+/// The press trigger has no toplevel test; the worker raises the nearest toplevel self or ancestor.
 #[test]
 fn pressing_a_child_of_a_toplevel_window_raises_the_window() {
     let mut s = board_and_dialog();
@@ -596,9 +530,7 @@ fn pressing_a_child_of_a_toplevel_window_raises_the_window() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **The RELEASE never raises.** The sibling category-`0xe` handler `0x766420` has no `Raise` call
-/// anywhere in it; only the down edge does. A raise on the release would be invisible in the
-/// ordinary case and wrong in the one that matters — a press that started a drag elsewhere.
+/// The mouse-up handler (`0x766420`, category `0xe`) has no raise; only the down edge raises.
 #[test]
 fn releasing_over_a_toplevel_window_does_not_raise_it() {
     let mut s = board_and_dialog();
@@ -615,7 +547,7 @@ fn releasing_over_a_toplevel_window_does_not_raise_it() {
     s.resolve();
     let (x, y) = centre(&s, "Dialog");
     let before = level(&mut s, "Dialog");
-    // A release with no press before it: the down edge never ran, so nothing may move.
+    // A release with no press before it.
     s.mouse_button(x, y, "LeftButton", false);
     assert_eq!(
         level(&mut s, "Dialog"),
@@ -625,11 +557,8 @@ fn releasing_over_a_toplevel_window_does_not_raise_it() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **Capture else hover.** The handler resolves `root+0x80` (the existing capture) *before* falling
-/// back to `root+0x7c` (the frame under the cursor), so a second button pressed while the first is
-/// still held raises the frame being HELD, not whatever the pointer has wandered onto. The capture
-/// clears only when the last button comes up (`0x7664bb`, gated on the post-event mask), so the
-/// next press after that resolves to the hover again.
+/// The press raises the capture (`root+0x80`) before the hover (`root+0x7c`), so a second button
+/// raises the held frame; the capture clears when the last button comes up (`0x7664bb`).
 #[test]
 fn a_chorded_press_raises_the_held_frame_not_the_one_under_the_cursor() {
     let mut s = board_and_dialog();
@@ -659,14 +588,13 @@ fn a_chorded_press_raises_the_held_frame_not_the_one_under_the_cursor() {
     .unwrap();
     s.resolve();
 
-    // Hold the left button on Dialog…
+    // Hold the left button on Dialog.
     let (dx, dy) = centre(&s, "Dialog");
     s.mouse_button(dx, dy, "LeftButton", true);
     let dialog_held = level(&mut s, "Dialog");
     let other_before = level(&mut s, "Other");
 
-    // …then press the right button away over Other. The capture is still Dialog's, so Other is not
-    // the raise target even though it is what the cursor is on.
+    // Then press the right button over Other: the capture is still Dialog's.
     let (ox, oy) = centre(&s, "Other");
     assert_eq!(s.hit_test_name(ox, oy).as_deref(), Some("Other"));
     s.mouse_button(ox, oy, "RightButton", true);
@@ -677,7 +605,7 @@ fn a_chorded_press_raises_the_held_frame_not_the_one_under_the_cursor() {
     );
     assert_eq!(level(&mut s, "Dialog"), dialog_held);
 
-    // Both buttons up — only now does the capture clear.
+    // Both buttons up: only now does the capture clear.
     s.mouse_button(ox, oy, "LeftButton", false);
     s.mouse_button(ox, oy, "RightButton", false);
     let other_now = level(&mut s, "Other");
@@ -690,30 +618,9 @@ fn a_chorded_press_raises_the_held_frame_not_the_one_under_the_cursor() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A window raised while part of it is hidden must keep its own children level with each other**
-/// — the compaction may not split a sibling pair (director's report 2026-09-08, decision 2104).
-///
-/// This is Gatherer 1.0.0's Report window, built the way its XML builds it and reduced to the four
-/// frames that matter:
-///
-/// - `Win` — `toplevel`, `frameStrata="DIALOG"`, born hidden, at level 1 (what `SetParent` gives a
-///   child of a level-0 `UIParent`).
-/// - `Close` — a Button declared inside `Win`'s `<Frames>`, so level 2, and visible with `Win`.
-/// - `Body` — a `<Frame parent="Win" hidden="true" enableMouse="true">` covering the whole window
-///   (`GathererInfo_ReportFrame`, 640×370 centred on a 640×390 dialog), also level 2, but HIDDEN
-///   when `Win` is shown. The addon shows it one line later.
-/// - `Other` — the already-open Options window it overlaps, which is what arms the occlusion gate.
-///
-/// The sequence is the addon's: `Win:Show()` (whose raise runs while `Body` is still hidden), then
-/// `Body:Show()`. `Close` and `Body` are siblings under one parent, so their levels are equal by
-/// construction and **must stay equal** — the reference's hit sweep then gives the tie to the
-/// earlier-linked frame, which is `Close`, and the Close button works.
-///
-/// What went wrong: the compaction renumbered `Close` (visible, in the bucket) and not `Body`
-/// (hidden, in no bucket), then the raise's propagate pushed the same delta into both — so the one
-/// level the compaction squeezed out of `Close` and not out of `Body` became a permanent inversion.
-/// `Body` is mouse-enabled and covers the window, so it swallowed every click and hover the Close
-/// button should have had: the button showed no highlight and could not be pressed.
+/// Gatherer's Report window: `Win` raises while its full-cover `Body` is still hidden, then `Body`
+/// shows. Siblings `Close` and `Body` must stay level through the compaction, so the reference's
+/// hit sweep gives the tie to the earlier-linked `Close`.
 #[test]
 fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
     let mut s = script();
@@ -757,8 +664,7 @@ fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
     .unwrap();
     s.resolve();
 
-    // The addon's own two lines: show the window (the raise fires here, with `Body` still hidden),
-    // then show the sub-frame for the selected tab.
+    // The addon's two lines: the raise fires on the first, with `Body` still hidden.
     s.run("Win:Show()").unwrap();
     s.run("Body:Show()").unwrap();
     s.resolve();
@@ -770,9 +676,7 @@ fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
         level(&mut s, "Other")
     );
 
-    // THE SYMPTOM FIRST, through the engine's own pointer path: the Close button takes its own
-    // click and its own hover. Asserted before the arithmetic below so a regression reports what
-    // the director would see, not the number behind it.
+    // The Close button takes its own click and hover, asserted before the levels behind them.
     let (cx, cy) = centre(&s, "Close");
     assert_eq!(
         s.hit_test_name(cx, cy).as_deref(),
@@ -792,7 +696,6 @@ fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
         "Close"
     );
 
-    // …and the number behind it.
     assert_eq!(
         level(&mut s, "Close"),
         level(&mut s, "Body"),
@@ -802,11 +705,8 @@ fn a_raise_with_a_hidden_child_keeps_the_windows_own_siblings_level() {
     assert!(s.errors().is_empty(), "{:?}", s.errors());
 }
 
-/// **A script level change carries no children** (decision 2189): the Lua binding `0x774560`
-/// calls `set_frame_level 0x76a4f0` with `propagate=0` — only the raise shifts a subtree. Stock
-/// FrameXML is written against it (`BonusActionButtonTemplate` raises the button and then its
-/// cooldown by hand), and carrying the children put the bonus bar's sweep over an addon's
-/// cooldown count.
+/// `SetFrameLevel` (`0x774560`) calls `0x76a4f0` with `propagate=0`, so the children stay put;
+/// stock `BonusActionBarFrame.xml:13-15` raises a button and then its cooldown by hand.
 #[test]
 fn a_script_level_change_leaves_the_children_where_they_were() {
     let mut s = script();
diff --git a/crates/benilla-ui/src/script/tests/visibility.rs b/crates/benilla-ui/src/script/tests/visibility.rs
index 3805b3d8..fcb21929 100644
--- a/crates/benilla-ui/src/script/tests/visibility.rs
+++ b/crates/benilla-ui/src/script/tests/visibility.rs
@@ -1,4 +1,4 @@
-//! Show/Hide fire OnShow/OnHide exactly on effective transitions; OnUpdate ticks gate on visibility.
+//! Show and Hide fire OnShow/OnHide only on effective transitions; OnUpdate runs only when visible.
 
 use super::common::script;
 
diff --git a/crates/benilla-ui/src/script/tests/widget_surface.rs b/crates/benilla-ui/src/script/tests/widget_surface.rs
index 83daa23f..b5a02e0c 100644
--- a/crates/benilla-ui/src/script/tests/widget_surface.rs
+++ b/crates/benilla-ui/src/script/tests/widget_surface.rs
@@ -1,44 +1,13 @@
-//! **The widget-method surface gate** — the sibling of [`super::reference_surface`], for the API
-//! an addon reaches through a *widget* rather than through `_G` (decision 2142).
-//!
-//! `our_globals_stay_inside_the_1_12_surface` has guarded the global namespace since 1189, and the
-//! shape gate (1842/1843/2118) guards the arity and return kinds of the methods we *have*. Between
-//! them sat the question neither asks: **is the set of method NAMES on each widget class the set
-//! 1.12 registers?** A method the reference has and we do not is invisible to the shape gate,
-//! which skips what does not exist; a method we have and the reference does not is invisible to
-//! everything, and is the superset `api-coverage.sh`'s header calls "not free" — an addon that
-//! feature-detects (`if region.GetBlendMode then`) takes a path we cannot honour, and the failure
-//! surfaces far from the cause.
-//!
-//! A corpus census over 110 top-20 and 219 vanilla addons found both directions live at once
-//! (2142): `ShaguTweaks` probes `GetBlendMode`, which we were missing, and silently recolours
-//! textures the reference leaves alone; `pfUI` and `_Nameplates` call `GameTooltip:GetAnchorType`
-//! bare and raise. The demand is in the corpus, which is not in this repo — so this gate does not
-//! measure demand. It measures the SURFACE, and every entry in the two declared lists below is
-//! where the reading of the demand got written down.
-//!
-//! When re-reading that demand: those corpora hold addons that *run on* 1.12, not addons written
-//! only for it — most of the big ones are multi-client and pick a code path at load, and they come
-//! in several versions of themselves. `scripts/api-coverage.sh`'s header has the detail; decision
-//! 2146 is the case that made it matter.
-//!
-//! ## The reference side is a CHAIN, not 23 flat surfaces
-//!
-//! The reference's 23 widget registrar tables are mutually **disjoint** — a class's real surface is
-//! its own table plus the tables it misses into. Comparing a live `Frame` against `0x878ec0` alone
-//! reports 87 of its 88 methods as beyond-1.12, which is how you get a gate nobody believes.
-//! [`WIDGET_CHAINS`] is that inheritance, and its two non-obvious rows are byte-settled, not
-//! guessed: `0x87c9b8` is the base `Region` map (its 19 names are exactly [`super::super`]'s
-//! `REGION_MAP_METHODS`), and `0x847ce4` is `LootButton`, whose whole surface of its own is
-//! `SetSlot` (decision 1799, read off the registrar's own `mov edx,1`).
+//! The widget-method surface gate, the widget sibling of [`super::reference_surface`]. The
+//! reference's 23 widget registrar tables are disjoint, so a class's surface is its own table plus
+//! those it inherits ([`WIDGET_CHAINS`]): `0x87c9b8` is the base `Region` map (the 19
+//! `REGION_MAP_METHODS`), and `LootButton`'s own `0x847ce4` holds only `SetSlot`.
 use std::collections::{BTreeMap, BTreeSet};
 
 use crate::script::{widget_method_census, UiScript};
 
-/// `(class, its own registrar table, the tables it inherits)`.
-///
-/// `WorldFrame` is a `Frame` to Lua (1983/1984) and `TitleRegion` a bare `Region`, so neither has a
-/// table of its own among the 23. `TaxiRouteFrame` is absent for the same reason (1828).
+/// `(class, its own registrar table, the tables it inherits)`. `WorldFrame` is a `Frame` to Lua
+/// and `TitleRegion` a bare `Region`; like `TaxiRouteFrame`, neither has a table of its own.
 const WIDGET_CHAINS: &[(&str, &str, &[&str])] = &[
     ("Frame", FRAME, &[REGION]),
     ("WorldFrame", FRAME, &[REGION]),
@@ -70,8 +39,7 @@ const WIDGET_CHAINS: &[(&str, &str, &[&str])] = &[
     ("Minimap", "0x84c538", FRAME_CHAIN),
     ("Texture", "0x87c128", &[REGION]),
     ("FontString", "0x87c1d8", &[REGION]),
-    // The font OBJECT (`CreateFont`) carries its own `GetName`/`GetObjectType`/`IsObjectType` and
-    // inherits nothing.
+    // The font object (`CreateFont`) inherits nothing.
     ("Font", "0x87c7c8", &[]),
     ("TitleRegion", REGION, &[]),
 ];
@@ -82,17 +50,11 @@ const MODEL: &str = "0x878948";
 const PLAYER_MODEL: &str = "0x84f1fc";
 const FRAME_CHAIN: &[&str] = &[FRAME, REGION];
 
-/// Methods the reference registers that this client does not answer — **a list that may only
-/// shrink**, one row per name, naming every class it is missing on and why it has not been built.
-///
-/// The corpus demand behind each is 2142's census. A name with real, live callers does not belong
-/// here: it belongs implemented.
+/// Reference methods this client does not answer yet: one row per name, its classes and why. The
+/// list only shrinks; a name with live callers belongs implemented.
 const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
-    // ── The MovieFrame trio: zero addon demand, and the stock GLUE screen calls all three ──────
-    // `_extracted_gluexml/MovieFrame.lua:23/30/35/47/71`. The glue screens stay ours permanently
-    // (0068 §8), so the intro-movie screen is owed these however little the ecosystem wants them —
-    // which makes this the one group here that is a real backlog item rather than a name nobody
-    // has ever typed. benilla has no movie playback at all, so it is a feature, not a verb.
+    // ── The MovieFrame trio ──
+    // The stock glue `MovieFrame.lua` calls all three; benilla plays no movie yet.
     (
         "StartMovie",
         "MovieFrame",
@@ -104,10 +66,8 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
         "MovieFrame",
         "the same — `MovieFrame.lua:35` passes `GetMovieSubtitles()`",
     ),
-    // ── The Minimap's four content setters ────────────────────────────────────────────────────
-    // benilla draws the minimap's blips, arrow and mask from the app side (`minimap/blips`), never
-    // through Lua; the stock UI does not call these either. Wiring them means routing the art
-    // choice back through the VM, which nothing has asked for.
+    // ── The Minimap's four content setters ──
+    // The app draws the minimap's blips and arrow itself, never through Lua.
     (
         "SetArrowModel",
         "Minimap",
@@ -116,10 +76,8 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
     ("SetBlipTexture", "Minimap", "the same"),
     ("SetIconTexture", "Minimap", "the same"),
     ("SetPlayerModel", "Minimap", "the same"),
-    // ── The Button font-object and text-colour family ─────────────────────────────────────────
-    // Seven getters and one setter over a button's disabled/highlight/pushed font state. benilla
-    // keeps that state (`button.rs`'s `Slot` triple) but publishes none of it back. **Zero call
-    // sites in 329 addon folders and zero in the stock UI** — the whole family is completeness.
+    // ── The Button font-object and text-colour family ──
+    // `button.rs` keeps this font state but publishes none of it; nothing calls these.
     (
         "GetDisabledFontObject",
         "Button CheckButton LootButton",
@@ -155,9 +113,7 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
         "Button CheckButton LootButton",
         "the same family",
     ),
-    // ── Line spacing, on the five classes that carry text ─────────────────────────────────────
-    // A real layout property benilla's text layout does not model — a setter here is not a store,
-    // it is a change to how `ui_text` lays out wrapped lines. No caller anywhere measured.
+    // ── Line spacing, on the five classes that carry text ──
     (
         "GetSpacing",
         "EditBox Font FontString MessageFrame ScrollingMessageFrame",
@@ -168,9 +124,7 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
         "EditBox Font FontString MessageFrame ScrollingMessageFrame",
         "the same — the setter is a layout change, not a stored value",
     ),
-    // ── EditBox mode read-backs ───────────────────────────────────────────────────────────────
-    // The four modes are all SET here (`editbox`'s `SetAutoFocus`/`SetMultiLine`/`SetNumeric`/
-    // `SetPassword`) and none is readable. Cheap, and nothing has ever asked.
+    // ── EditBox mode read-backs ──
     (
         "IsAutoFocus",
         "EditBox",
@@ -179,10 +133,7 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
     ("IsMultiLine", "EditBox", "the same"),
     ("IsNumeric", "EditBox", "the same"),
     ("IsPassword", "EditBox", "the same"),
-    // ── ScrollingMessageFrame's line-position surface ─────────────────────────────────────────
-    // The scroll POSITION verbs (`ScrollUp`/`ScrollDown`/`ScrollToTop`…) are all here; these four
-    // report or set where that position sits, which our message buffer tracks internally and does
-    // not publish. No caller anywhere measured.
+    // ── ScrollingMessageFrame's line-position surface ──
     (
         "GetCurrentLine",
         "ScrollingMessageFrame",
@@ -191,16 +142,14 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
     ("GetCurrentScroll", "ScrollingMessageFrame", "the same"),
     ("GetNumLinesDisplayed", "ScrollingMessageFrame", "the same"),
     ("SetScrollFromBottom", "ScrollingMessageFrame", "the same"),
-    // ── The colour picker's HSV pair ──────────────────────────────────────────────────────────
-    // `ColorSelect` publishes the RGB pair; the HSV twin would need the conversion the reference
-    // does in C. The stock `ColorPickerFrame` uses RGB only, and so does every corpus caller.
+    // ── The colour picker's HSV pair ──
     (
         "GetColorHSV",
         "ColorSelect",
         "the RGB pair is published; nothing measured asks for HSV",
     ),
     ("SetColorHSV", "ColorSelect", "the same"),
-    // ── One texture read-back ─────────────────────────────────────────────────────────────────
+    // ── One texture read-back ──
     (
         "IsDesaturated",
         "Texture",
@@ -208,9 +157,7 @@ const NOT_YET_ANSWERED: &[(&str, &str, &str)] = &[
     ),
 ];
 
-/// Methods this client answers that 1.12 does not register on that class — **each a deliberate,
-/// reasoned exception, never a quiet superset**. Same contract as
-/// [`super::reference_surface::allowed_beyond_1_12`]: a name here must say why it stays.
+/// Methods answered here that 1.12 does not register on that class, each with why it stays.
 const ALLOWED_BEYOND: &[(&str, &str, &str)] = &[];
 
 /// The reference's widget rows, `table_va -> {name}`.
@@ -236,7 +183,7 @@ fn reference_tables() -> BTreeMap<String, BTreeSet<String>> {
     out
 }
 
-/// `class -> the effective reference surface` (own table + everything it inherits).
+/// `class -> the effective reference surface` (its own table and everything it inherits).
 fn reference_surface_by_class() -> BTreeMap<&'static str, BTreeSet<String>> {
     let tables = reference_tables();
     assert!(
@@ -284,8 +231,7 @@ fn declared(list: &[(&str, &str, &str)]) -> BTreeMap<String, BTreeSet<String>> {
         .collect()
 }
 
-/// Render a `class -> names` map as the declared-list rows it would need, so a failure hands you
-/// the entry to paste rather than a set difference to transcribe.
+/// Render a `class -> names` map as declared-list rows, ready to paste in.
 fn as_rows(diff: &BTreeMap<String, BTreeSet<String>>) -> String {
     let mut by_name: BTreeMap<&String, Vec<&String>> = BTreeMap::new();
     for (class, names) in diff {
@@ -343,7 +289,7 @@ fn every_1_12_widget_method_is_answered() {
         as_rows(&missing)
     );
 
-    // A listed name that came back fails, so the list cannot outlive its fix.
+    // A listed name that is answered now fails, so the list cannot outlive its fix.
     let mut healed: Vec<String> = Vec::new();
     for (name, classes, _) in NOT_YET_ANSWERED {
         for class in classes.split_whitespace() {
@@ -374,8 +320,7 @@ fn our_widget_methods_stay_inside_the_1_12_surface() {
         let extra: BTreeSet<String> = have
             .iter()
             .filter(|n| !want.contains(*n))
-            // Our host bridge and the VM's own internals declare themselves ours by prefix, the
-            // same discipline `reference_surface` uses for globals.
+            // Our host bridge and VM internals are marked by prefix, as `reference_surface` does.
             .filter(|n| !n.starts_with("Benilla") && !n.starts_with("__benilla_"))
             .filter(|n| !listed.get(*n).is_some_and(|c| c.contains(class)))
             .cloned()
diff --git a/crates/benilla-ui/src/script/tests/worldframe.rs b/crates/benilla-ui/src/script/tests/worldframe.rs
index 3e552175..52825b82 100644
--- a/crates/benilla-ui/src/script/tests/worldframe.rs
+++ b/crates/benilla-ui/src/script/tests/worldframe.rs
@@ -1,6 +1,5 @@
-//! The `WorldFrame` kind (decisions 1983/1984; wow-re `worldframe-widget.md`): a `Frame` to Lua,
-//! a one-shot type, born in stratum `WORLD` with mouse and wheel enabled, and a hit the app's
-//! arbiter must be able to tell apart.
+//! The `WorldFrame` kind (vtable `0x8043e8`): a `Frame` to Lua, creatable once, born in stratum
+//! `WORLD` with mouse and wheel on, and a hit the app can tell apart.
 
 use crate::script::UiScript;
 
@@ -13,9 +12,8 @@ fn vm() -> UiScript {
     s
 }
 
-/// `GetObjectType()` answers `"Frame"` and `IsObjectType("WorldFrame")` is nil: the class
-/// inherits the base table's type slots (the TaxiRouteFrame precedent), so the registered name
-/// never becomes an identity.
+/// `GetObjectType()` answers `"Frame"`: the class keeps the base table's type slots, as
+/// `TaxiRouteFrame` does.
 #[test]
 fn the_world_frame_is_a_frame_to_lua() {
     let s = vm();
@@ -72,8 +70,6 @@ fn the_world_frame_is_born_in_stratum_world_with_the_mouse_and_wheel() {
     );
 }
 
-/// The hit test answers the world frame where nothing else is under the cursor — the addon-facing
-/// scripts on it fire — and the app can tell that hit apart from a UI hit.
 #[test]
 fn a_hit_on_the_world_frame_is_told_apart_from_a_ui_hit() {
     let mut s = vm();
diff --git a/crates/benilla-ui/src/script/tests/worldmap.rs b/crates/benilla-ui/src/script/tests/worldmap.rs
index cb5bb869..c3b307fb 100644
--- a/crates/benilla-ui/src/script/tests/worldmap.rs
+++ b/crates/benilla-ui/src/script/tests/worldmap.rs
@@ -1,21 +1,19 @@
-//! The world-map bindings (decision 0203 phase 2): catalog/feed pushes, the engine-owned
-//! selection, and the deferred WORLD_MAP_UPDATE queue.
+//! The world-map bindings: catalog and feed pushes, the engine-owned selection, and the deferred
+//! `WORLD_MAP_UPDATE` queue.
 
 use super::common::script;
 use crate::script::*;
 
-/// A two-continent catalog shaped like the real 5875 one (Kalimdor first — the app's push order
-/// defines every Lua-visible index; the sheet rects are the real disjoint kernel outputs). The
-/// EK zone grid is sparse: exactly the real Goldshire cell (12735, verified against the shipped
-/// Azeroth.zmp) marked as zone 1.
+/// A two-continent catalog shaped like the real one: Kalimdor first, since the push order defines
+/// every Lua-visible index, with the real disjoint sheet rects. The sparse EK grid marks the real
+/// Goldshire cell (12735 in `Azeroth.zmp`) as zone 1.
 fn push_catalog(s: &mut UiScript) {
     let mut ek_grid = vec![0u16; 128 * 128];
     ek_grid[12735] = 1;
-    // Cell 8801 = the child (0.5, 0.5) resolves to through Elwynn's OWN loc rect — a "Stormwind
-    // City" peer child. Clicking it from the Elwynn zone map drills into the city (the §3 path).
+    // Cell 8801 is where (0.5, 0.5) lands through Elwynn's own loc rect: the Stormwind City peer,
+    // which a click on the Elwynn map drills into (`0x4a67a0`).
     ek_grid[8801] = 2;
-    // Cell 9060 = the child (0.82, 0.82) resolves to through Elwynn's own rect — Elwynn itself,
-    // the case the zone-level hover must stay silent on (the displayed zone never names itself).
+    // Cell 9060, where (0.82, 0.82) lands: Elwynn itself, which the zone-level hover never names.
     ek_grid[9060] = 1;
     s.set_world_map_catalog(vec![
         WorldMapContinentView {
@@ -52,15 +50,11 @@ fn push_catalog(s: &mut UiScript) {
                     name: "Elwynn Forest".into(),
                     area_id: 12,
                     map_file: "Elwynn".into(),
-                    // A clean synthetic loc rect inside the EK continent rect: w=2000, h=1500 → the
-                    // continent-highlight formula lands on round-ish expected coords (asserted below).
+                    // Synthetic, inside EK's rect: w=2000, h=1500, for round highlight coords.
                     loc_rect: (-8000.0, -10000.0, -400.0, -1900.0),
-                    // Three overlays. Two are shaped like real Elwynn rows: Northshire reveals
-                    // on explore bit 125, Goldshire on bit 124 (the real AreaTable exploreFlags);
-                    // their hit rects (top, left, bottom, right; px of 1002×668) sit apart so a
-                    // point is in at most one. The first is a row whose first area slot resolves
-                    // to nothing (bit 126; its rect overlaps Northshire's) — the zone-level hover
-                    // must walk past it, not stop at it.
+                    // Northshire (bit 125) and Goldshire (124) carry the real exploreFlags; hit
+                    // rects are (top, left, bottom, right) in px of 1002×668. The first row's area
+                    // is unresolvable (bit 126) and overlaps Northshire: the hover walks past it.
                     overlays: vec![
                         WorldMapOverlayView {
                             texture: "Interface\\WorldMap\\Elwynn\\STONECAIRNLAKE".into(),
@@ -94,8 +88,7 @@ fn push_catalog(s: &mut UiScript) {
                         },
                     ],
                 },
-                // A city peer of Elwynn — a WorldMapArea child of the continent with its own art
-                // folder, indistinguishable from a zone in code (wow-re 15b2a8ea Part 2a).
+                // A city peer of Elwynn, which the reference treats as a zone (`0x4a67a0`).
                 WorldMapZoneView {
                     name: "Stormwind City".into(),
                     area_id: 1519,
@@ -108,19 +101,16 @@ fn push_catalog(s: &mut UiScript) {
     ]);
 }
 
-/// The **orphan list** — `0x4a5d00`'s third array, and in 5875 its entire population: the three
-/// battlegrounds, with the real row ids, map ids, area ids and art folders, in `WorldMapArea.dbc`
-/// **file order** (the fill pass appends with no sort). Alterac Valley carries one of its three
-/// real `WorldMapOverlay` rows over its real AreaBit 954 — the only battleground art the
-/// explored-bit gate has anything to say about (WSG and AB key zero overlay rows).
+/// The orphan list, `0x4a5d00`'s third array: in 1.12 exactly the three battlegrounds, with their
+/// real row, map and area ids and art folders, in `WorldMapArea.dbc` file order (no sort). Alterac
+/// Valley carries one of its real `WorldMapOverlay` rows (AreaBit 954); WSG and AB have none.
 fn push_direct_areas(s: &mut UiScript) {
     let row = |name: &str, area_id: u32, folder: &str, overlays: Vec<WorldMapOverlayView>| {
         WorldMapZoneView {
             name: name.into(),
             area_id,
             map_file: folder.into(),
-            // A synthetic rect: nothing engine-side projects through it (the app owns every
-            // projection), it is carried because the row is the row.
+            // A synthetic rect: the app owns every projection, so nothing here reads it.
             loc_rect: (1500.0, 500.0, 1600.0, 600.0),
             overlays,
         }
@@ -149,20 +139,17 @@ fn push_direct_areas(s: &mut UiScript) {
     ]);
 }
 
-/// **The direct-area selection** — the third state, and the whole of what a battleground map is
-/// (wow-re `system/ui/scratch/worldmap-direct-area-selection.md`). Inside Warsong Gulch the
-/// reference selects `(continent = -2, direct = WorldMapArea 443)`, and `GetMapInfo()` answers the
-/// art folder that `Blizzard_BattlefieldMinimap.lua:83-86` needs before it will draw anything at
-/// all; a client that models the selection as `(continent, zone)` answers nil there and draws an
-/// empty battle map.
+/// The direct-area selection (`[0x845074]`) is a third state: inside Warsong Gulch the reference
+/// selects `(continent = -2, direct = WorldMapArea 443)`, and `GetMapInfo()` answers the art
+/// folder `Blizzard_BattlefieldMinimap.lua:83` needs before it draws.
 #[test]
 fn a_direct_area_is_the_third_selection_state() {
     let mut s = script();
     push_catalog(&mut s);
     push_direct_areas(&mut s);
 
-    // The player is in Warsong Gulch: `0x4a6650`'s continent loop misses (map 489 is no
-    // continent's) and only then does the orphan loop match, selecting the row's own id.
+    // In Warsong Gulch `0x4a6650`'s continent loop misses (map 489 is no continent's) and the
+    // orphan loop selects the row's own id.
     s.set_world_map_feed(None, Some((0.5, 0.5)), 0.0, None, Vec::new(), Vec::new());
     s.set_world_map_player_direct_area(Some(443));
     s.run("SetMapToCurrentZone()").unwrap();
@@ -188,9 +175,8 @@ fn a_direct_area_is_the_third_selection_state() {
          row id has no entries to fire from"
     );
 
-    // Hover and click are refused. Both matter: there is no `.zmp` bitmap for a battleground
-    // (`0x4a6ec0`/`0x4a7620`/`0x4a7540` each test `-2` explicitly), and the world sheet's
-    // continent walk must not run just because the direct state shares its `continent == 0` cell.
+    // Hover and click are refused: a battleground has no `.zmp` bitmap (`0x4a6ec0`, `0x4a7620`,
+    // `0x4a7540` each test `-2`), and the world sheet's walk must not run on `continent == 0`.
     assert!(s
         .eval::<Option<String>>("return UpdateMapHighlight(0.5, 0.5)")
         .unwrap()
@@ -203,10 +189,9 @@ fn a_direct_area_is_the_third_selection_state() {
         "a click cannot drill off an instance map"
     );
 
-    // ── THE REFRESH TRAP. All five of the reference's in-place refresh sites re-pass
-    // `direct != -1 ? direct : zone` (`0x48f9f6`, `0x4a6460`, `0x6d93d8`, `0x6d9a17`, `0x6dac72`);
-    // one that re-passed the zone alone would drop the instance map back to the world view on the
-    // next world-state push or exploration update — silently, and only inside a battleground.
+    // All five of the reference's refresh sites re-pass `direct != -1 ? direct : zone`
+    // (`0x48f9f6`, `0x4a6460`, `0x6d93d8`, `0x6d9a17`, `0x6dac72`); passing the zone alone would
+    // drop an instance map to the world view on the next refresh.
     s.set_world_map_explored(vec![u32::MAX; 64]);
     s.set_world_map_landmarks(Vec::new());
     s.run("SetMapToCurrentZone()").unwrap();
@@ -218,8 +203,8 @@ fn a_direct_area_is_the_third_selection_state() {
         "a refresh re-selects the DIRECT cell, never the (0, 0) pair beside it"
     );
 
-    // Selecting a continent or a zone CLEARS the direct cell: `0x4a67a0`'s other legs all fall
-    // into `0x4a67ea mov [0x845074],-1`, and only `ecx == -2` jumps past it.
+    // Selecting a continent or zone clears the direct cell: `0x4a67a0`'s other legs all reach
+    // `0x4a67ea`, which writes -1 to `[0x845074]`; only `ecx == -2` jumps past it.
     s.run("SetMapZoom(2, 1)").unwrap();
     assert_eq!(
         s.eval::<(String, i64, i64)>(
@@ -230,8 +215,8 @@ fn a_direct_area_is_the_third_selection_state() {
         "the instance map does not shadow later navigation"
     );
 
-    // And the stock zoom-out button's own path off a battleground map: its `else` arm fires
-    // because `GetCurrentMapZone()` is 0 there, and `SetMapZoom(0)` is the world view.
+    // The stock zoom-out button off a battleground map: `GetCurrentMapZone()` is 0 there, so its
+    // `else` arm runs `SetMapZoom(0)`, the world view (`WorldMapFrame.lua:257`).
     s.run("SetMapToCurrentZone()").unwrap();
     s.run("SetMapZoom(0)").unwrap();
     assert_eq!(
@@ -242,10 +227,8 @@ fn a_direct_area_is_the_third_selection_state() {
     );
 }
 
-/// An instance map's overlays are **admitted**, keyed by the direct area, under exactly the zone's
-/// explored-bit gate (`0x4a67a0`'s overlay half, `0x4a6b10 jl 0x4a6b3d`; wow-re
-/// `worldmap-overlay-reveal-gate.md` §2) — no free reveal for a battleground. On 5875 data that
-/// means Alterac Valley's three rows and nothing at all for the other two.
+/// An instance map's overlays, keyed by the direct area, pass the zone's explored-bit gate
+/// (`0x4a67a0`'s overlay half, `0x4a6b10` to `0x4a6b3d`), with no free reveal for a battleground.
 #[test]
 fn an_instance_map_reveals_its_overlays_under_the_zone_gate() {
     let mut s = script();
@@ -270,18 +253,15 @@ fn an_instance_map_reveals_its_overlays_under_the_zone_gate() {
         "Interface\\WorldMap\\AlteracValley\\DUNBALDAR"
     );
 
-    // Warsong Gulch keys zero `WorldMapOverlay` rows — a fully explored character still sees bare
-    // detail tiles there.
+    // Warsong Gulch keys no `WorldMapOverlay` rows, so even fully explored it shows none.
     s.set_world_map_player_direct_area(Some(443));
     s.run("SetMapToCurrentZone()").unwrap();
     s.set_world_map_explored(vec![u32::MAX; 64]);
     assert_eq!(s.eval::<i64>("return GetNumMapOverlays()").unwrap(), 0);
 }
 
-/// The navigation surface: lists come from the catalog, SetMapZoom's selection reads back
-/// synchronously in the same Lua breath (the reference's dropdown-click contract), zone/continent
-/// arguments clamp, and GetMapInfo names the displayed art folder (nil at the world level — the
-/// reference Lua's own "World" fallback).
+/// Lists come from the catalog, `SetMapZoom` reads back in the same call stack as the reference's
+/// dropdown expects, arguments clamp, and `GetMapInfo` names the art folder (nil at world level).
 #[test]
 fn worldmap_navigation_and_map_info() {
     let mut s = script();
@@ -306,7 +286,6 @@ fn worldmap_navigation_and_map_info() {
         ("Durotar".into(), "The Barrens".into())
     );
 
-    // World level by default: continent 0, nil map info.
     assert_eq!(
         s.eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
             .unwrap(),
@@ -314,7 +293,6 @@ fn worldmap_navigation_and_map_info() {
     );
     assert!(s.eval::<bool>("return GetMapInfo() == nil").unwrap());
 
-    // The synchronous read-back the reference relies on, and the art-folder name per level.
     s.run("SetMapZoom(2)").unwrap();
     assert_eq!(
         s.eval::<(i64, i64, String)>(
@@ -330,7 +308,6 @@ fn worldmap_navigation_and_map_info() {
         "a zone selection names the ZONE's art folder"
     );
 
-    // Out-of-range arguments clamp (never a Lua error — addons pass garbage).
     s.run("SetMapZoom(9, 9)").unwrap();
     assert_eq!(
         s.eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
@@ -340,9 +317,9 @@ fn worldmap_navigation_and_map_info() {
     );
 }
 
-/// SetMapToCurrentZone lands on the app-fed player zone; the feed's projection + facing surface
-/// through GetPlayerMapPosition/GetPlayerFacing — for `"player"` and, since report B320, for the
-/// `party1..4` slots too. A `raid` token still answers the off-map sentinel.
+/// `SetMapToCurrentZone` lands on the app-fed player zone, and the feed surfaces through
+/// `GetPlayerFacing` and `GetPlayerMapPosition` for the player and `party1..4`. A `raid` token
+/// answers the off-map sentinel; the reference reads raid positions (`WorldMapFrame.lua:379`).
 #[test]
 fn worldmap_current_zone_and_player_feed() {
     let mut s = script();
@@ -389,21 +366,14 @@ fn worldmap_current_zone_and_player_feed() {
     assert_eq!(s.eval::<i64>("return GetCurrentMapContinent()").unwrap(), 0);
 }
 
-/// The **engine** moves the selection too, with no Lua in the loop — the reference's second
-/// writer of `[0x84506c]`/`[0x845070]`: `0x494780`'s `old == 0` side call to the resolver
-/// `0x4a6650`, which every exit of ends in the `SetMap` setter `0x4a67a0` (wow-re
-/// `system/ui/scratch/worldmap-selection-autosync.md`).
-///
-/// We only ever had the Lua writers, so until something opened the map we sat at the world
-/// level — and there `GetPlayerMapPosition` answers a world-SHEET uv, which every addon built on
-/// Astrolabe rescales as a zone uv. This pins that a fresh session can be on the player's own
-/// zone before a single line of FrameXML or addon Lua has asked for it.
+/// The engine moves the selection with no Lua in the loop: the reference's second writer of
+/// `[0x84506c]`/`[0x845070]` is `0x494780`'s `old == 0` call to the resolver `0x4a6650`, whose
+/// every exit ends in the `SetMap` setter `0x4a67a0`.
 #[test]
 fn the_engine_can_select_a_zone_with_no_lua_call() {
     let mut s = script();
     push_catalog(&mut s);
 
-    // A fresh VM is the world sheet, and nothing Lua-side has run.
     assert_eq!(
         s.eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
             .unwrap(),
@@ -418,8 +388,7 @@ fn the_engine_can_select_a_zone_with_no_lua_call() {
         (1, 2),
         "the engine's own SetMap is what Lua reads back"
     );
-    // The WHOLE selection moved, not just the pair of globals: GetMapInfo names the zone sheet,
-    // which is what `WorldMapFrame_Update` loads art from and what Astrolabe keys its scale on.
+    // The whole selection moved: `GetMapInfo` names the zone sheet `WorldMapFrame_Update` loads.
     assert!(
         s.eval::<Option<String>>("return GetMapInfo()")
             .unwrap()
@@ -427,8 +396,7 @@ fn the_engine_can_select_a_zone_with_no_lua_call() {
         "a selected zone names its map file; the world level is the nil that mis-scales"
     );
 
-    // It clamps through the same tail as the Lua verbs — an out-of-range pair cannot corrupt
-    // the selection (`0x4a67a0` range-checks the zone against the continent's child count).
+    // It clamps through the same tail as the Lua verbs (`0x4a67a0` range-checks the zone).
     s.sync_world_map_to_player_zone(99, 99, None);
     let (c, _) = s
         .eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
@@ -436,9 +404,9 @@ fn the_engine_can_select_a_zone_with_no_lua_call() {
     assert!(c > 0, "clamped into the catalog, never past it");
 }
 
-/// World-level ProcessMapClick picks the continent whose sheet-rect contains the click (the
-/// 0x4a7100 AABB walk — the real kernel rects are disjoint); continent-level clicks resolve
-/// through the 0x4a6ec0 zone grid; hover names ride the same cell law.
+/// A world-level `ProcessMapClick` picks the continent whose sheet rect contains it (`0x4a7100`,
+/// the real rects being disjoint); continent-level clicks and hovers resolve through the zone grid
+/// (`0x4a6ec0`).
 #[test]
 fn worldmap_click_containment_and_zone_grid() {
     let mut s = script();
@@ -461,10 +429,9 @@ fn worldmap_click_containment_and_zone_grid() {
     s.run("ProcessMapClick(0.72, 0.63)").unwrap();
     assert_eq!(s.eval::<i64>("return GetCurrentMapContinent()").unwrap(), 2);
 
-    // Continent level: Goldshire's UV inside the EK rect lands on grid cell 12735 (the real
-    // Azeroth.zmp index for that world position) → zone 1. The zone lights up: name + fileName +
-    // the six geometry values (wow-re 15b2a8ea continent branch), all against the zone's loc rect
-    // within the continent. cont_w=35199.9, cont_h=23466.6; w=2000, h=1500.
+    // Continent level: Goldshire's uv lands on cell 12735, zone 1, which lights up with its name,
+    // file name and six geometry values (`0x4a8494`) against its loc rect in the continent:
+    // cont_w=35199.9, cont_h=23466.6; w=2000, h=1500.
     let (name, file, tpx, tpy, tx, ty, sx, sy) = s
         .eval::<(String, String, f64, f64, f64, f64, f64, f64)>(
             "return UpdateMapHighlight(0.452843, 0.720880)",
@@ -512,10 +479,8 @@ fn worldmap_click_containment_and_zone_grid() {
         "the grid click drills into the zone"
     );
 
-    // Now at the ZONE level (Elwynn): a click re-expressed through ELWYNN's own rect lands on
-    // cell 8801 = the Stormwind City peer child → drills into the city map. This is the path that
-    // was a no-op before (wow-re 15b2a8ea Part 2: continent- and zone-level clicks run identical
-    // code, only the windowing rect differs).
+    // At zone level a click through Elwynn's own rect lands on cell 8801, the Stormwind City peer,
+    // and drills in: `0x4a75c9` runs continent- and zone-level clicks alike, windowed differently.
     s.run("ProcessMapClick(0.5, 0.5)").unwrap();
     assert_eq!(
         s.eval::<(i64, i64)>("return GetCurrentMapContinent(), GetCurrentMapZone()")
@@ -530,12 +495,10 @@ fn worldmap_click_containment_and_zone_grid() {
     assert_eq!(s.eval::<i64>("return GetCurrentMapContinent()").unwrap(), 0);
 }
 
-/// At ZONE level `UpdateMapHighlight` answers a NAME only (report B360; wow-re 15b2a8ea §1a/1b/1d):
-/// a revealed overlay's sub-area when the cursor is inside its hit rect, else the neighbouring
-/// zone or city whose grid cell the cursor is in through the DISPLAYED zone's rect window — never
-/// the displayed zone itself — and always a nil fileName + six zeros, so the stock frame hides the
-/// highlight quad. Fogged sub-areas have no name; an overlay with no resolvable first area is
-/// walked past. The reference's own Duskwood shot: "Deadwind Pass" in the label, no highlight.
+/// At zone level `UpdateMapHighlight` answers a name only (`0x4a812e`): a revealed overlay's
+/// sub-area under the cursor, else the neighbouring zone or city whose cell the cursor is in
+/// through the displayed zone's rect, never that zone itself. The file name is nil and the
+/// geometry zeros, so the stock frame hides the quad.
 #[test]
 fn worldmap_zone_level_hover_names_without_highlight() {
     let mut s = script();
@@ -551,20 +514,18 @@ fn worldmap_zone_level_hover_names_without_highlight() {
         |name: &str| -> Answer { (Some(name.into()), None, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0) };
     let miss: Answer = (None, None, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
 
-    // Nothing explored. (0.5, 0.5) through Elwynn's rect is cell 8801 = the Stormwind City peer:
-    // the neighbouring child is NAMED, and nothing else — the B360 answer, Deadwind Pass from
-    // Duskwood in the report.
+    // Nothing explored: (0.5, 0.5) is cell 8801, the Stormwind City peer, named and nothing else.
     assert_eq!(hover(&mut s, 0.5, 0.5), name_only("Stormwind City"));
     // Cell 9060 = Elwynn itself: the displayed zone never names itself.
     assert_eq!(hover(&mut s, 0.82, 0.82), miss);
     // An empty cell, no overlay: the tail.
     assert_eq!(hover(&mut s, 0.2, 0.2), miss);
-    // Inside Goldshire's hit rect but fogged (bit 124 clear): no name — the pre-search walks the
-    // REVEALED list, and cell 8929 under it is empty.
+    // Inside Goldshire's hit rect, fogged (bit 124 clear): the pre-search walks only revealed
+    // overlays, and cell 8929 under it is empty.
     assert_eq!(hover(&mut s, 0.42, 0.7), miss);
 
-    // Reveal Northshire (bit 125 = word 3, bit 29). Its rect contains (0.5, 0.5): the overlay
-    // pre-search runs BEFORE the grid, so the sub-area wins over the city under the same point.
+    // Reveal Northshire (bit 125 = word 3, bit 29): the overlay pre-search runs before the grid,
+    // so its sub-area wins over the city under (0.5, 0.5).
     let mut explored = vec![0u32; 64];
     explored[3] = 1 << 29;
     s.set_world_map_explored(explored.clone());
@@ -586,8 +547,7 @@ fn worldmap_zone_level_hover_names_without_highlight() {
     s.set_world_map_explored(explored);
     assert_eq!(hover(&mut s, 0.5, 0.5), name_only("Northshire Valley"));
 
-    // Control: back at the continent level the hovered zone still lights up — fileName is the art
-    // folder and the quad geometry is non-zero.
+    // Control: at continent level the hovered zone still lights up, with its art folder.
     s.run("SetMapZoom(2)").unwrap();
     let (name, file, tpx, _, tx, ty, _, _) = hover(&mut s, 0.452843, 0.720880);
     assert_eq!(
@@ -597,8 +557,8 @@ fn worldmap_zone_level_hover_names_without_highlight() {
     assert!(tx > 0.0 && ty > 0.0);
 }
 
-/// SetMapZoom queues WORLD_MAP_UPDATE through the pending-event queue: nothing fires inside the
-/// call (a binding can't re-enter dispatch), the registered frame hears it on the next tick.
+/// `SetMapZoom` queues `WORLD_MAP_UPDATE` rather than firing it, since a binding cannot re-enter
+/// dispatch; the registered frame hears it on the next tick.
 #[test]
 fn worldmap_update_event_fires_on_next_tick() {
     let mut s = script();
@@ -630,16 +590,14 @@ fn worldmap_update_event_fires_on_next_tick() {
     );
 }
 
-/// The exploration fog: overlays reveal per the pushed bitset — none before any push, the
-/// matching subset after (bit 125 = Northshire in the fixture), the full info tuple comes back,
-/// and re-pushing the same bitset queues no extra repaint.
+/// Overlays reveal per the pushed explored bitset: none before a push, the matching subset after,
+/// each with its full info tuple.
 #[test]
 fn worldmap_overlays_reveal_by_explored_bits() {
     let mut s = script();
     push_catalog(&mut s);
-    s.run("SetMapZoom(2, 1)").unwrap(); // the Elwynn zone map (EK's only fixture zone)
+    s.run("SetMapZoom(2, 1)").unwrap(); // the Elwynn zone map
 
-    // Nothing explored: the zone shows no overlays (all parchment).
     assert_eq!(s.eval::<i64>("return GetNumMapOverlays()").unwrap(), 0);
 
     // Bit 125 set (word 3, bit 29): Northshire reveals, Goldshire stays fogged.
@@ -662,7 +620,7 @@ fn worldmap_overlays_reveal_by_explored_bits() {
         .eval::<bool>("return GetMapOverlayInfo(3) == nil")
         .unwrap());
 
-    // At the continent level the overlay family reads empty (fog is a zone-map thing).
+    // At continent level the overlay family reads empty: fog is a zone-map thing.
     s.run("SetMapZoom(2)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumMapOverlays()").unwrap(), 0);
 }
diff --git a/crates/benilla-ui/src/script/tick.rs b/crates/benilla-ui/src/script/tick.rs
index 634637f9..cffc511a 100644
--- a/crates/benilla-ui/src/script/tick.rs
+++ b/crates/benilla-ui/src/script/tick.rs
@@ -1,7 +1,5 @@
-//! The host runtime loop — an `impl UiScript` block beside its concern (the `layout.rs` pattern):
-//! the event fan-out to registered frames ([`UiScript::fire_event`]), the per-frame advance
-//! ([`UiScript::tick`]: OnUpdate + the engine-side fades and the model panes' clocks), and the FrameXML session clock
-//! ([`UiScript::now`]). The low-level handler-firing these drive lives in [`super::event`].
+//! The host runtime loop: event fan-out ([`UiScript::fire_event`]), the per-frame advance
+//! ([`UiScript::tick`]) and the `GetTime()` clock ([`UiScript::now`]).
 
 use mlua::Lua;
 
@@ -10,59 +8,32 @@ use crate::widget::FrameHandle;
 use super::{editbox, event, tooltip, Model, ScriptValue, UiScript};
 
 impl UiScript {
-    /// Queue an event to fire at the **start of the next tick**, into the same
-    /// [`super::Model::pending_events`] list the engine's own bindings use — so it lands *after*
-    /// everything queued earlier in the frame and before that tick's `OnUpdate` pass.
-    ///
-    /// **Ordering, not laziness, is the whole reason this is public** (decision 1750). A benilla
-    /// drain runs a step behind the input pass that fed it, so an event it fires *immediately*
-    /// arrives BEFORE events the same input already queued — the reverse of the reference, where
-    /// the deferral happens inside the very call that queued them. That inversion is not
-    /// hypothetical: the soulbind confirm raised by placing an item into a worn slot was cancelled
-    /// one tick later by that same place's own `CURSOR_UPDATE`, whose `StaticPopup_Hide` is
-    /// `UIParent.lua:356-360` transcribed correctly. Queueing restores the reference's relative
-    /// order — cursor-change first, question second — while a *later* cursor change still retires
-    /// the question, which is exactly what that arm is for.
-    ///
-    /// Use [`Self::fire_event`] for anything whose ordering against in-flight queued events does
-    /// not matter, which is nearly everything.
+    /// Queue an event for the start of the next tick, behind everything queued earlier and before
+    /// that tick's `OnUpdate` pass. A drain runs a step behind its input, so firing at once would
+    /// overtake events that input already queued: the soulbind confirm for an item placed into a
+    /// worn slot must follow that placement's `CURSOR_UPDATE`, whose handler hides it
+    /// (`UIParent.lua:357-361`).
     pub fn queue_event(&mut self, event: &str, args: Vec<ScriptValue>) {
         self.model_mut()
             .pending_events
             .push((event.to_string(), args));
     }
 
-    /// Fire an event to every frame registered for it, invoking their `OnEvent` handlers (RF-0025):
-    /// both the legacy `this`/`event`/`arg1..argN` globals *and* the modern `(self, event, ...)`
-    /// arguments. Events reach registered frames regardless of visibility, **in registration
-    /// order** — the client's `SignalEvent 0x703e50` walks the per-event listener list head-first
-    /// (tail-append insert `0x7052d0`, wow-re `event-dispatch-order.md`: FIFO, first-registered
-    /// fires first). Cross-frame order is a LAW consumers depend on: both ZoneText frames write
-    /// `PVPInfoTextString` on one event — the last writer decides. Handler errors are collected
-    /// into [`UiScript::errors`], never panicking.
+    /// Fire an event to every frame registered for it, shown or not, setting both the
+    /// `this`/`event`/`arg1..argN` globals and the `(self, event, ...)` arguments (`0x704d50`,
+    /// `0x704f10`); handler errors go to [`UiScript::errors`]. Frames fire in registration order,
+    /// as `SignalEvent` (`0x703e50`) walks its tail-appended list (`0x7052d0`), and consumers rely
+    /// on it: both ZoneText frames write `PVPInfoTextString` on one event, and the last one wins.
     ///
-    /// **The walk steps by a next-listener SAVED BEFORE the handler runs** (`0x703ee8: mov
-    /// edi,[eax+0x4]` — "save the next node before firing"; decision 1324), never by list index.
-    /// That is what makes a handler that UNREGISTERS ITSELF mid-dispatch unable to rob its
-    /// successor — and it is load-bearing in the wild: AceEvent-2.0 treats `PLAYER_LOGIN` /
-    /// `VARIABLES_LOADED` as fire-once events and unregisters its frame *inside* the handler, so
-    /// an index walk skipped whichever addon registered right after AceEvent (Bagnon_Forever's
-    /// saved-bag DB never initialized — the director's `SaveBagData:76` error dialogs). A frame
-    /// registered mid-dispatch tail-appends and is still visited; a handler that unregisters the
-    /// walk's SAVED next stops the dispatch there (the reference frees the node and walks into
-    /// its zeroed links — memory-accident territory we render as a deterministic stop, a knowing
-    /// divergence from an accident, not from a mechanism).
+    /// The walk steps by the next listener saved before each handler runs (`0x703ee8`), so a
+    /// handler that unregisters itself does not skip its successor. Deviation: a handler that
+    /// unregisters the saved next ends the dispatch, because the reference then reads a freed node.
     pub fn fire_event(&mut self, event: &str, args: Vec<ScriptValue>) {
         fire_event_into(&self.lua, event, args);
     }
 }
 
-/// [`UiScript::fire_event`] against the VM directly, for a caller that holds `&Lua` rather than
-/// `&UiScript` — which is every Lua binding, and therefore `UpdateSpells` (decision 1924).
-///
-/// Identical behaviour; `fire_event` is the same call with the script's own VM. The `&mut self` on
-/// the method was never load-bearing — the body reaches everything through `lua.app_data_mut()` —
-/// and this is the shape [`crate::loader::load_into`] already uses for the same reason (1188 §2).
+/// [`UiScript::fire_event`] for a caller holding `&Lua`, such as a Lua binding.
 pub(crate) fn fire_event_into(lua: &Lua, event: &str, args: Vec<ScriptValue>) {
     let model_mut = || lua.app_data_mut::<Model>().expect("model app_data set");
     {
@@ -75,8 +46,7 @@ pub(crate) fn fire_event_into(lua: &Lua, event: &str, args: Vec<ScriptValue>) {
         };
         while let Some(h) = at {
             let mut model = model_mut();
-            // The saved handle must still be registered — its removal (by the previous handler)
-            // ends the walk, per the doc above.
+            // A saved next that the previous handler unregistered ends the walk.
             let Some(pos) = model
                 .event_to_frames
                 .get(event)
@@ -100,38 +70,26 @@ pub(crate) fn fire_event_into(lua: &Lua, event: &str, args: Vec<ScriptValue>) {
 }
 
 impl super::UiScript {
-    /// Advance time: run `OnUpdate(self, elapsed)` on every *effectively-visible* frame that has one
-    /// (RF-0025: OnUpdate → `this` + `arg1 = elapsed`). Errors collected, never panicking.
-    /// Also advances the `GetTime()` clock — the FrameXML session clock (seconds, monotonic,
-    /// arbitrary epoch like the real client's), kept as the `__benilla_now` global so the stdlib
-    /// binding reads it without a host round-trip. Reference FrameXML (CastingBarFrame & co.)
-    /// anchors durations on GetTime; the clock advancing in the same call that fires OnUpdate
-    /// keeps the two views of time consistent within a frame.
-    /// The current `GetTime()` value (`__benilla_now`, seconds) — the FrameXML clock. The app
-    /// reads it to stamp an absolute expiry into the clock a Lua countdown reads (the aura feed's
-    /// `expirationTime`, decision 0257); it is the same value `GetTime()` returns inside the VM.
+    /// The current `GetTime()` value in seconds; the app stamps absolute expiries with it, such as
+    /// an aura's `expirationTime`.
     pub fn now(&self) -> f64 {
         self.lua.globals().get("__benilla_now").unwrap_or(0.0)
     }
 
-    /// Start this VM's `GetTime()` clock at `secs` rather than at zero — how a host hands a
-    /// **freshly built** VM the clock its process is already on (decision 2116).
-    ///
-    /// The reference's `GetTime` (`0x515ea0`) is `KERNEL32!GetTickCount` scaled by 0.001 (through
-    /// the thunk `0x42c010` → `0x42b790`; wow-re `system/core/ledger.tsv` boundary row and
-    /// `system/ui/ledger.tsv:3265`) — an **OS** clock that knows nothing about the Lua VM and never
-    /// restarts, which is exactly what lets stock `Cooldown.lua` gate on `start > 0`. Ours lives
-    /// inside the VM, so without this a rebuilt VM — every logout/login, every `ReloadUI` — would
-    /// restart it at zero and every host value already converted onto it would land in the past.
-    ///
-    /// Set once, at construction: from then on only [`Self::tick`] moves the clock, so the
-    /// `(Instant, GetTime)` pair a host keeps beside it stays atomic by construction.
+    /// Start this VM's `GetTime()` clock at `secs`, so a rebuilt VM (a relog, a `ReloadUI`) keeps
+    /// the process's clock. The reference's `GetTime` (`0x515ea0`, through `0x42c010` and
+    /// `0x42b790`) is `GetTickCount` scaled by 0.001, an OS clock that never restarts, which stock
+    /// `Cooldown.lua` relies on (`start > 0`). Set once, at construction; after that only
+    /// [`Self::tick`] moves it.
     pub fn set_now(&mut self, secs: f64) {
         if let Err(e) = self.lua.globals().set("__benilla_now", secs) {
             self.push_error(e);
         }
     }
 
+    /// Advance a frame: the `GetTime()` clock, the edit boxes and queued events, then
+    /// `OnUpdate(self, elapsed)` on every visible frame that has one (`0x704f10`), then the
+    /// engine's own fades, model panes and hover.
     pub fn tick(&mut self, elapsed: f32) {
         let clock = {
             let g = self.lua.globals();
@@ -141,32 +99,22 @@ impl super::UiScript {
         if let Err(e) = clock {
             self.push_error(e);
         }
-        // The focused edit box's caret blink (`0x77a790` runs on the client's frame tick).
+        // The focused edit box's caret blink (`0x77a790`, on the client's frame tick).
         editbox::tick_blink(&self.lua, elapsed);
-        // …and, from inside that same `0x77a790` (`0x77a7a1`), the dirty-word drain that fires the
-        // `OnTextChanged`s an edit only marked (decision 1831). It runs BEFORE this tick's
-        // OnUpdate sweep, matching the reference's order: the box's own OnUpdate override drains
-        // before the FrameXML handlers that read the box get their turn.
+        // Then `0x77a790`'s drain of the `OnTextChanged`s an edit only marked (`0x77a7a1`), before
+        // the OnUpdate sweep, as in the reference.
         editbox::drain_text_changed(&self.lua);
-        // …and the caret flush's own fire, the second half of `0x77a790`'s update walk
-        // (`0x77d3e0` → `0x77da80`): `OnCursorChanged` when the caret has moved. It is what
-        // `ScrollingEdit_OnCursorChanged` records and `ScrollingEdit_OnUpdate` then scrolls by,
-        // so this is the mail body and the GM ticket box following the caret as you type.
+        // Then the caret flush (`0x77d3e0` → `0x77da80`): `OnCursorChanged` when the caret moved,
+        // which `ScrollingEdit_OnUpdate` scrolls by.
         editbox::drain_cursor_changed(&self.lua);
-        // Events queued by Lua bindings last tick (`Model::pending_events` — e.g. `SetMapZoom` →
-        // `WORLD_MAP_UPDATE`; the cursor arc's `CURSOR_UPDATE`/`ITEM_LOCK_CHANGED`/
-        // `DELETE_ITEM_CONFIRM`, decision 0216) fire first, so handlers see them before this
-        // frame's OnUpdate runs.
+        // Events queued since the last tick fire before this tick's OnUpdate.
         let pending = std::mem::take(&mut self.model_mut().pending_events);
         for (event, args) in pending {
             self.fire_event(&event, args);
         }
         let ids: Vec<u32> = {
             let mut model = self.model_mut();
-            // The OnUpdate population is its own list (decision 1446) — maintained by
-            // `SetScript`, `scripts`' one writer — so this reads a few hundred handles instead
-            // of re-filtering the whole scripts map. A destroyed frame's handle stays until its
-            // liveness check fails once, then compacts here.
+            // `SetScript` keeps the OnUpdate list; a destroyed frame's handle compacts out here.
             let frames: Vec<FrameHandle> = model
                 .on_update_frames
                 .iter()
@@ -188,18 +136,9 @@ impl super::UiScript {
                 model.on_update_frames = live;
             }
             let mut ids: Vec<u32> = frames.into_iter().map(|h| model.frame_id(h)).collect();
-            // **Deterministic order, by frame id — i.e. creation order.**
-            //
-            // `model.scripts` is a hash map, so this sweep used to fire OnUpdate in an order that
-            // varied per process. That was invisible for as long as every geometry getter answered
-            // from the PREVIOUS frame's resolve: each handler saw the same stale world regardless
-            // of when it ran. The moment the getters began settling on demand (so a handler can
-            // observe work an earlier handler did this same sweep), the order became load-bearing
-            // and the macro window's tab width started flipping 164/167 run to run.
-            //
-            // Random order was always wrong — the reference sweeps a defined order — the staleness
-            // was merely hiding it. Creation order is stable, matches FrameXML declaration order,
-            // and is what a handler reading a sibling's geometry should see.
+            // Creation order, by frame id: getters settle on demand, so a handler sees what an
+            // earlier one did this sweep, and the order must be stable. The reference walks each
+            // strata level's list of shown frames (`0x765650`).
             ids.sort_unstable();
             ids
         };
@@ -209,16 +148,10 @@ impl super::UiScript {
             }
         }
         self.tick_model_panes(elapsed);
-        // Advance every ScrollingMessageFrame's per-line fade (the client's OnUpdate `0x788460`).
-        // Independent of the frame's own OnUpdate script — the fade is C++ behavior, not Lua. The
-        // AtBottom freeze gate lives inside `ScrollingMessageState::tick`.
+        // The engine's line fades, apart from any OnUpdate script: ScrollingMessageFrame's
+        // (`0x788460`) and MessageFrame's (`0x786200`), which also keeps only the lines that fit
+        // its height, so its rows are read from the resolved rect before the mutable walk.
         let mut model = self.model_mut();
-        // The sibling class's OnUpdate (`0x786200`): the same two-phase fade with no scroll gate,
-        // plus the capacity law that is this class's stand-in for `maxLines` — the cap is what fits
-        // vertically, so it needs the frame's resolved rect and is collected first (the arena walk
-        // below holds a mutable borrow that cannot also read `model.resolved`).
-        // Both per-kind walks below ride the arena's ticked-kind registry (decision 1446):
-        // dozens of handles instead of two full-arena sweeps per tick.
         let ticked: Vec<FrameHandle> = model.arena.ticked_kinds().to_vec();
         let message_frames: Vec<(FrameHandle, usize)> = ticked
             .iter()
@@ -248,16 +181,11 @@ impl super::UiScript {
             }
         }
         drop(model);
-        // Advance fading tooltips (FadeOut's ramp + end-of-ramp hide) — engine behavior like the
-        // message fade above, decision 0274.
+        // Tooltip fades: `FadeOut`'s ramp and the hide at its end.
         tooltip::tick_fades(&self.lua);
-        // The hover RE-PICK ([`Model::hover_repick`]): the world under a stationary cursor
-        // changed this tick (the hovered frame hid, or a frame was shown over the cursor), so
-        // re-run the hover walk at the SAVED cursor position — the reference's own pump tail
-        // (`0x765650` → `0x7660d0` with the saved event, didn't-move coalesce bypassed).
-        // `mouse_move` at the unchanged point is exactly that walk: the hidden frame's OnLeave
-        // already fired at hide time and `mouseover` is clear, so only the new winner's
-        // boundary fires — no second OnLeave, `OnEnter` with no physical mouse move.
+        // A frame hid or showed under a still cursor: re-run the hover walk at the saved position,
+        // as the reference's pump tail does (`0x765650` → `0x7660d0`). The hidden frame's OnLeave
+        // already fired, so only the new winner's `OnEnter` fires.
         let repick = {
             let mut model = self.model_mut();
             let due = model.hover_repick;
@@ -267,29 +195,18 @@ impl super::UiScript {
         if let Some((x, y)) = repick {
             self.mouse_move(x, y);
         }
-        // `WOW_UI_HANDLERS=<secs>` — who spent the frame (decision 1395). Last, so a report covers
-        // everything this tick fired; a no-op unless the instrument is armed.
+        // `WOW_UI_HANDLERS=<secs>`: last, so its report covers everything this tick fired.
         self.report_handler_profile(elapsed);
     }
 }
 
 impl UiScript {
-    /// The model panes' per-frame pass (decision 2007; wow-re `modelframe-render-law.md` §4).
-    ///
-    /// Three things the reference does each frame for a **visible** model pane, in this order:
-    /// the widget's own `OnUpdate` (`0x76d7f0`, walked by the UI pump with the Lua OnUpdates the
-    /// caller just fired) advances its private scene clock by `trunc(elapsed · 1000)` ms — a
-    /// truncation, no `+0.5` (`76d854 __ftol`); the paint (`vt+0x98`, `0x76d1a0`) fires
-    /// `OnUpdateModel` before it builds the scene; and the scene's animate runs the completion
-    /// callback (`0x76cdc0`) when the armed sequence has run its length — `OnAnimFinished`, on
-    /// natural completion only (mode 0), once per arm, for a looping sequence's first pass as
-    /// much as for a clamped one's end (the flag test sits after the enqueue — wow-re
-    /// `modelframe-texanim-and-sequence-law.md`, Q4). A hidden pane gets none of the three: its
-    /// clock stands still and it completes nothing, which is what makes the minimap ping "resume
-    /// where the last one stopped".
-    ///
-    /// The completion is read AFTER `OnUpdateModel` because the handler may re-arm (the cooldown
-    /// flips to its flash there), and a fresh arm has nothing to complete.
+    /// The model panes' per-frame pass, for visible panes, in the reference's order: the pane's
+    /// `OnUpdate` (`0x76d7f0`) advances its clock by `trunc(elapsed · 1000)` ms, the paint
+    /// (`0x76d1a0`) fires `OnUpdateModel`, and the animate fires `OnAnimFinished` (`0x76cdc0`) once
+    /// per arm when the armed sequence completes naturally, a loop's first pass included
+    /// (`0x719370`). A hidden pane's clock stands still. Completion is read after `OnUpdateModel`,
+    /// whose handler may re-arm.
     fn tick_model_panes(&mut self, elapsed: f32) {
         let dt_ms = (elapsed * 1000.0).trunc().max(0.0) as u64;
         let update_ids: Vec<u32> = {
@@ -306,8 +223,7 @@ impl UiScript {
                     m.clock_ms += dt_ms;
                 }
             }
-            // The handler population, maintained by `SetScript` like `on_update_frames`; a
-            // destroyed frame's handle compacts out on its first miss.
+            // Kept by `SetScript`; a destroyed frame's handle compacts out on its first miss.
             if model
                 .on_update_model_frames
                 .iter()
@@ -322,12 +238,9 @@ impl UiScript {
                     .collect();
                 model.on_update_model_frames = live;
             }
-            // Visible MODEL panes WITH A MODEL INSTALLED: the handler is `CSimpleModel::LoadXML`'s
-            // (`+0x3cc`) and the paint that fires it (`76d1bc`) is reached only past the
-            // `[widget+0x318] ≠ 0` gate at `76d24c` — a file set, resident or still streaming;
-            // a pane with no file paints nothing and fires nothing (wow-re
-            // `modelframe-texanim-and-sequence-law.md`, Q4). A script of that name on any
-            // other kind is inert, as it is in the reference.
+            // Only visible Model panes with a file set, resident or streaming: the paint that fires
+            // the handler (`0x76d1bc`) is gated on `[widget+0x318] ≠ 0` (`0x76d24c`). On any other
+            // kind the script is inert.
             let frames: Vec<FrameHandle> = model
                 .on_update_model_frames
                 .iter()
@@ -340,7 +253,7 @@ impl UiScript {
                 })
                 .collect();
             let mut ids: Vec<u32> = frames.into_iter().map(|h| model.frame_id(h)).collect();
-            ids.sort_unstable(); // creation order — the OnUpdate sweep's own law
+            ids.sort_unstable(); // creation order, as in the OnUpdate sweep
             ids
         };
         for id in update_ids {
diff --git a/crates/benilla-ui/src/script/tooltip/mod.rs b/crates/benilla-ui/src/script/tooltip/mod.rs
index a36de89c..56f421d0 100644
--- a/crates/benilla-ui/src/script/tooltip/mod.rs
+++ b/crates/benilla-ui/src/script/tooltip/mod.rs
@@ -1,28 +1,14 @@
-//! The `GameTooltip` method surface + engine behavior (decision 0274): the line stack, the
-//! owner/anchor law, auto-size, and the fade — the modeled behavior of the client's game-layer
-//! tooltip class over `CSimpleFrame` (wow-re `ui/scratch/bindings.md` pins the full 38-binding
-//! Lua surface; `tooltip-money.md` the money/cooldown internals; the *content* builders land per
-//! 0274's phases on top of these mechanics).
+//! The `GameTooltip` method surface and engine behaviour: the line stack, owner and anchor,
+//! auto-size and the fade.
 //!
-//! **Lines are real named FontString regions**, engine-created on demand and published as Lua
-//! globals (`<name>TextLeft1` …) — reference Lua addresses them by name
-//! (`GameTooltipTextLeft1:SetTextColor`, UnitFrame.lua), so they cannot be private state. The
-//! real template pre-declares 30 pairs and the class grows past them with `AddFontStrings`;
-//! benilla uses the one growth mechanism for all of them.
+//! Lines are named FontString regions published as Lua globals (`<name>TextLeft1` …), since
+//! FrameXML addresses them by name (`GameTooltipTextLeft1:SetTextColor`, `UnitFrame.lua:76`). The
+//! template declares 30 pairs, which are adopted; the reference grows past them through
+//! `AddFontStrings`, and this also creates pairs on demand.
 //!
-//! **Layout is a `resolve` pre-pass** ([`layout_tooltips`]): frame size = max measured line width
-//! (+ the double-line gap) + 2·pad × summed line heights + gaps, with `SetMinimumWidth` as a
-//! floor, and each double line's right column re-pointed flush to the text inset — the job the
-//! real client's C++ line layout does over the template's static anchors. It reads the measure
-//! round-trip's cached extents, so a fresh tooltip converges in ~2 frames (same as the retired
-//! Lua `OnUpdate` measure loop it replaces).
-//!
-//! `AddLine` accepts both shipped-FrameXML shapes — `(text, r, g, b[, wrap])` and the archaic
-//! `(text, "", r, g, b)` (both appear across the real 1.12 corpus; the non-number second slot is
-//! skipped). A wrap-flagged line has [`crate::widget::TOOLTIP_WRAP_WIDTH`] pinned onto its
-//! region at APPEND time, so its very first measure comes back wrapped — one round-trip, stable
-//! under the hover re-enter loop's per-frame content clears (the item description /
-//! trigger-effect lines).
+//! Layout is a pre-pass of every `resolve` ([`layout_tooltips`]): the width is the widest line (a
+//! double line adds the column gap) plus padding, floored by `SetMinimumWidth`; the height is the
+//! summed line heights and gaps; each right column sits flush with the text inset.
 
 use mlua::{Lua, Table, Value};
 
@@ -37,11 +23,10 @@ use crate::widget::{
     TOOLTIP_FADE_SECS, TOOLTIP_LINE_GAP, TOOLTIP_PAD,
 };
 
-/// Registry key of the GameTooltip method table (the MAXCSTACK discipline: named registry root).
+/// Registry key of the GameTooltip method table, a named registry root (the MAXCSTACK discipline).
 pub(super) const REG_TOOLTIP_METHODS: &str = "__benilla_tooltip_methods";
 
-/// Run `f` over a frame's tooltip state under one short write borrow. Errors if `this` is not a
-/// live GameTooltip (unreachable through the kind dispatcher, but the table is a plain Lua value).
+/// Runs `f` over a GameTooltip's state under one short write borrow.
 fn with_tip<T>(lua: &Lua, this: &Table, f: impl FnOnce(&mut TooltipState) -> T) -> mlua::Result<T> {
     let h = frame_handle_of(lua, this)?;
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -55,17 +40,12 @@ pub(super) fn tip_mut(model: &mut Model, h: FrameHandle) -> mlua::Result<&mut To
     }
 }
 
-/// Copy a named font object's resolved paint onto a line region (the `SetFontObject` copy,
-/// minus the error on a missing name: engine tests load file subsets where Fonts.xml may be
-/// absent — an unregistered name leaves the renderer's default face rather than failing the
-/// hover).
+/// `SetFontObject` onto a line cell, except that a missing font object keeps the default face
+/// rather than raising (a VM loaded without Fonts.xml).
 fn apply_font(d: &mut RegionData, name: &str, fo: Option<&FontObject>) {
     d.font_object = Some(name.to_string());
-    // The severance mask is left standing — a re-point does NOT restore inheritance in the
-    // reference (see `super::font`'s module doc on the `+0x2c` inheritMask). A freshly created
-    // line has a clean mask anyway; an adopted XML-declared line keeps whatever its own attributes
-    // severed. Either way the line inherits the object LIVE from here: a later
-    // `GameTooltipText:SetFont(…)` re-paints every tooltip line through `font::propagate`.
+    // The inherit mask (`+0x2c`) stays: a re-point does not restore inheritance in the reference.
+    // From here the line follows the font object live, through `font::propagate`.
     if let Some(f) = fo {
         d.font_path = f.font.clone();
         d.font_height = f.height;
@@ -77,14 +57,9 @@ fn apply_font(d: &mut RegionData, name: &str, fo: Option<&FontObject>) {
     }
 }
 
-/// Ensure the line-pair pool holds at least `n` pairs — ADOPTING XML-declared pairs
-/// (`<name>TextLeft<i>`/`TextRight<i>`, the ref template's pre-declared ladder: their faces
-/// ride, the engine owns justify/visibility/anchors) and creating the rest (faces cloned from
-/// the previous pair when a ladder exists, else the header/text defaults).
-/// Pair `i` (1-based): left at TOPLEFT (pad,−pad) of the frame (i = 1) or the previous left's
-/// BOTTOMLEFT (0,−gap); right at RIGHT→left RIGHT (its x offset is [`layout_tooltips`]'s to
-/// recompute). Line 1 wears `GameTooltipHeaderText`, the rest `GameTooltipText` — the real
-/// template's fonts.
+/// Grows the line-pair pool to `n` pairs: XML-declared pairs (`<name>TextLeft<i>`) are adopted
+/// with their fonts, and created pairs clone the previous pair's fonts past a declared ladder, or
+/// else wear the template's `GameTooltipHeaderText` (line 1) and `GameTooltipText`.
 fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
     let h = frame_handle_of(lua, this)?;
     // (id, global name) pairs to publish once the model borrow is dropped.
@@ -113,10 +88,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
             }
             let i = have + 1;
 
-            // An XML-declared pair for this index? The ref template mechanism: FrameXML declares
-            // the leading pairs (ShoppingTooltipTemplate's small-font ladder, TextLeft1..N), the
-            // class ADOPTS them and, past the ladder, grows lines that clone the previous pair's
-            // faces. GameTooltip declares none, so the header/text defaults hold there.
+            // The template's declared pair for this index (ShoppingTooltipTemplate's ladder).
             let declared = |model: &Model, cell: &str| -> Option<crate::widget::RegionHandle> {
                 if frame_name.is_empty() {
                     return None;
@@ -128,8 +100,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
                 let rh = model.id_to_region.get(&id).copied()?;
                 (model.arena.region(rh)?.owner == h).then_some(rh)
             };
-            // Font source for a CREATED cell: the previous line's declared/cloned faces when the
-            // frame carries an XML ladder, else the engine defaults.
+            // A created cell's fonts: the previous line's under an XML ladder, else the defaults.
             let seed_font =
                 |model: &mut Model,
                  d: &mut RegionData,
@@ -179,9 +150,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
                     d
                 };
                 d.hidden = true;
-                // Left-justified like the template's line stack — invisible while the rect hugs
-                // the measured text, load-bearing once the wrap consumer pins a region to the
-                // wrap column.
+                // Left-justified as in the template; it shows once a wrap line pins its width.
                 d.justify.set_h(super::JustifyH::Left);
                 d.anchors = vec![match prev_left {
                     None => Anchor::new(
@@ -204,7 +173,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
                 }];
                 model.region_data.insert(left, d);
                 model.touch_measure(left); // an adopted cell can arrive text-in-hand
-                model.touch_layout(); // a line row entered the layout graph (decision 0740)
+                model.touch_layout(); // a line row entered the layout graph
             }
             let left_id = model.region_id(left);
 
@@ -232,12 +201,12 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
                 d.anchors = vec![Anchor::new(Point::Right, left_id, Point::Right, 0.0, 0.0)];
                 model.region_data.insert(right, d);
                 model.touch_measure(right); // an adopted cell can arrive text-in-hand
-                model.touch_layout(); // a line row entered the layout graph (decision 0740)
+                model.touch_layout(); // a line row entered the layout graph
             }
             let right_id = model.region_id(right);
 
             if !frame_name.is_empty() {
-                // Adopted pairs are already named + published by the loader.
+                // Adopted pairs are already named and published by the loader.
                 if adopted_left.is_none() {
                     let ln = format!("{frame_name}TextLeft{i}");
                     model.region_names.entry(ln.clone()).or_insert(left_id);
@@ -265,7 +234,7 @@ fn ensure_lines(lua: &Lua, this: &Table, n: usize) -> mlua::Result<()> {
     Ok(())
 }
 
-/// One text cell's write: text + color + shown. `color` alpha defaults opaque.
+/// Writes a line cell's text and colour and shows it.
 pub(super) fn write_cell(
     model: &mut Model,
     rh: crate::widget::RegionHandle,
@@ -275,18 +244,15 @@ pub(super) fn write_cell(
     let d = model.region_data.entry(rh).or_default();
     d.text = Some(text.to_string());
     d.vertex_color = Some(color);
-    // `AddLine("…", r, g, b)`'s colour is this line's OWN colour, exactly as if Lua had called
-    // `SetTextColor` on the cell — so it must survive a later mutation of the font object the
-    // line inherits ([`super::types::FontExplicit`]). Without the mark, one
-    // `GameTooltipText:SetTextColor(…)` would repaint every red/green line in the tooltip.
+    // The line's own colour, as if set by `SetTextColor`: a later
+    // `GameTooltipText:SetTextColor` must not repaint it.
     d.font_explicit.color = true;
     d.hidden = false;
     model.touch_measure(rh);
 }
 
-/// Hide + blank every line cell and zero the counters. The caller fires `OnTooltipCleared`
-/// (outside the model borrow) — the engine-fired widget script the reference wires to its
-/// money-row clear.
+/// Hides and blanks every line cell and resets the counters; the caller fires `OnTooltipCleared`
+/// outside the model borrow.
 pub(super) fn clear_content(model: &mut Model, h: FrameHandle) {
     let (lefts, rights) = match model.arena.frame(h).map(|f| &f.kind_state) {
         Some(KindState::Tooltip(t)) => (t.left_lines.clone(), t.right_lines.clone()),
@@ -296,30 +262,10 @@ pub(super) fn clear_content(model: &mut Model, h: FrameHandle) {
         if let Some(d) = model.region_data.get_mut(&rh) {
             d.text = None;
             d.hidden = true;
-            // `measured` is deliberately KEPT. It is a cache whose validity gate is its own
-            // content hash ([`RegionData::measure_key`] over text/font/wrap/outline), so wiping
-            // it here invalidates nothing the key would not — while destroying the one thing that
-            // makes the hover re-enter loop affordable. That loop
-            // (`ContainerFrameItemButton_OnUpdate`, unthrottled in 1.12 and shipped verbatim as
-            // the reference's `ContainerFrameItemButton_OnUpdate`) clears and rebuilds the SAME content
-            // every frame: keeping the cache lets each rebuilt line re-validate against its own
-            // key, so nothing re-shapes, the measure list stays empty, its forced second resolve
-            // never happens, and the layout gate's fingerprint — which exists precisely to
-            // "absorb idempotent writes for free" (layout.rs) — closes over the whole loop.
-            // Wiping it cost +10 CPU ms/frame on a live bag hover (measured 13.2 → 23.9 cpu_ms,
-            // `WOW_CAPTURE=ui-bag` vs `ui-tooltip`); the gate is
-            // `layout_gate::the_hover_re_enter_loop_neither_re_measures_nor_re_solves`.
-            //
-            // The wrap pin (`size`) is likewise KEPT, and for the stronger reason: wiping it here
-            // was the last write that made the hover re-enter loop differ from itself. The wipe
-            // and `append_line`'s re-pin are a round trip inside ONE frame — same cell, same
-            // width, no observable state between them — but each half bumped the layout epoch, so
-            // tier 1 went dirty every hover frame and tier 2 hashed the whole UI to conclude
-            // nothing had moved (~0.65 ms/frame, `WOW_UI_COST=1` on `WOW_CAPTURE=ui-tooltip`, at
-            // solves=0). The pin is now written from the line's own wrap flag at append time —
-            // set for a wrap line, cleared for a plain one — which covers the case this wipe
-            // existed for (a cell whose new content doesn't wrap) without a write per frame.
-            // A hidden, textless cell contributes nothing to layout in between either way.
+            // `measured` and the wrap pin (`size`) stay: the measure cache is keyed by content
+            // ([`RegionData::measure_key`]) and `append_line` rewrites the pin, so the hover
+            // loop's per-frame clear and rebuild (`ContainerFrameItemButton_OnUpdate`) re-measures
+            // and re-lays out nothing.
         }
     }
     if let Ok(t) = tip_mut(model, h) {
@@ -328,9 +274,8 @@ pub(super) fn clear_content(model: &mut Model, h: FrameHandle) {
         t.unit_token = None;
         t.world_owned = false;
     }
-    // The mouseover health bar is UNIT content: it hides with the lines (the ref bar exists
-    // only while a unit shows; the byte law's watcher re-shows it on the next unit render).
-    // Without this, the bar from the last mob hover rode under every ITEM tooltip.
+    // The `<name>StatusBar` health bar is unit content: it hides with the lines, and the next
+    // unit render re-shows it.
     let bar = model
         .arena
         .frame(h)
@@ -341,7 +286,7 @@ pub(super) fn clear_content(model: &mut Model, h: FrameHandle) {
     }
 }
 
-/// Fire `OnTooltipCleared` on the tooltip frame (errors → [`Model::errors`], never propagated).
+/// Fires `OnTooltipCleared`; a script error is recorded, never propagated.
 pub(super) fn fire_cleared(lua: &Lua, h: FrameHandle) {
     let id = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -350,16 +295,13 @@ pub(super) fn fire_cleared(lua: &Lua, h: FrameHandle) {
     if let Err(e) = event::fire_widget_handler(lua, id, "OnTooltipCleared", Vec::new()) {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
 }
 
-/// A content `Set*`'s tail: show when it rendered lines, hide when it rendered none. The real
-/// client's uncached path leaves a CLEARED tooltip whose size collapses to nothing — with our
-/// declared-size plate the visible equivalent is a hide; the hover's re-enter repaints the
-/// moment the app answers the ask. Hiding through the arena directly (not [`hide_tooltip`])
-/// keeps the owner: IsOwned must stay true for the re-enter loop.
+/// A content `Set*`'s tail: shown with lines, hidden without. The reference leaves an uncached
+/// tooltip cleared and collapsed to nothing; this plate keeps its declared size, so it hides. It
+/// hides without [`hide_tooltip`] to keep the owner, which the hover loop's `IsOwned` needs.
 pub(super) fn show_or_hide_empty(lua: &Lua, h: FrameHandle) {
     let lines = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -371,10 +313,8 @@ pub(super) fn show_or_hide_empty(lua: &Lua, h: FrameHandle) {
     set_shown(lua, h, lines > 0);
 }
 
-/// Cancel a running fade and restore full alpha (fresh CONTENT does this — re-hovering during
-/// the fade-out resurrects the tooltip at full strength). Conditional on a fade actually running,
-/// because an addon that lowered the plate's alpha itself and then added a line keeps its alpha:
-/// only the three sites in [`full_alpha`] are documented to stamp it back.
+/// New content cancels a running fade at full alpha; with no fade running, an alpha the addon set
+/// stays, since only the paths in [`full_alpha`] reset it.
 fn cancel_fade(model: &mut Model, h: FrameHandle) {
     if let Ok(t) = tip_mut(model, h) {
         if t.fade_start.take().is_some() {
@@ -383,15 +323,8 @@ fn cancel_fade(model: &mut Model, h: FrameHandle) {
     }
 }
 
-/// `SetAlpha(255)` — **UNCONDITIONAL**, and the FIRST thing the SetOwner core `0x52ffe0` does
-/// (`0x52fff4`), before the five stores; `0x530a80`'s show arm does it too, and its self-hide arm
-/// reaches it through `0x530a60` → `0x52ffe0(0, 0, 0, 0)`. So all three of SetOwner, Show and the
-/// effective-hide leave the plate at full strength whether or not one of OUR fades was running
-/// (wow-re `system/ui/ledger.tsv` rows `0x52ffe0` / `0x530a80`, both verified, and
-/// `scratch/hover-hide-and-tooltip-owner-law.md` §4).
-///
-/// [`cancel_fade`] is not this: it only restores the alpha a fade of ours took away, so a plate
-/// left dim by any other path never recovered where the reference recovers on the next SetOwner.
+/// `SetAlpha(255)`, unconditional: the SetOwner core `0x52ffe0` does it first (`0x52fff4`), and
+/// Show (`0x530a80`) and its self-hide (`0x530a60`, the core with no owner) reach it too.
 fn full_alpha(model: &mut Model, h: FrameHandle) {
     if let Ok(t) = tip_mut(model, h) {
         t.fade_start = None;
@@ -399,12 +332,12 @@ fn full_alpha(model: &mut Model, h: FrameHandle) {
     model.arena.set_alpha(h, 1.0);
 }
 
-/// The engine's `GetTime` clock (the `__benilla_now` global [`super::UiScript::tick`] advances).
+/// The engine's `GetTime` clock, which [`super::UiScript::tick`] advances.
 fn now(lua: &Lua) -> f64 {
     lua.globals().get("__benilla_now").unwrap_or(0.0)
 }
 
-/// Show/hide through the arena with the visibility events fired (the shared Show/Hide's path).
+/// Shows or hides through the arena and fires the visibility events.
 pub(super) fn set_shown(lua: &Lua, h: FrameHandle, shown: bool) {
     let changed = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -413,38 +346,15 @@ pub(super) fn set_shown(lua: &Lua, h: FrameHandle, shown: bool) {
     event::fire_visibility_changes(lua, changed);
 }
 
-/// The engine tooltip's default text colour — the byte constant `0xc0d3e8` = `0xffffd200` gold
-/// every no-colour `AddLine`/`SetText` renders with. This is why the reference's zone tooltip is
-/// GOLD despite Minimap.lua's `AddLine(text, "", 1.0, 1.0, 1.0)`: 1.12's binding reads the colour
-/// at its fixed positions, the `""` in the r-slot is not a number, and the whole colour tail is
-/// dropped in favour of this default — the trailing 1.0s never shift into place (the last one is
-/// consumed as the truthy wrap flag). Byte-pinned: the static-init writer `0x528e50` stores
-/// `0xffffd200` at `0xc0d3e8` (§0-BINDINGS verdict, 2026-07-14).
+/// The default line colour, gold `0xffffd200` (stored at `0xc0d3e8` by `0x528e50`). The zone
+/// tooltip's `AddLine(text, "", 1.0, 1.0, 1.0)` (`Minimap.lua:40`) renders in it: the `""` r-slot
+/// drops the whole colour, and the last `1.0` lands in the wrap slot.
 pub(in crate::script) const DEFAULT_TEXT_GOLD: [f32; 4] = [1.0, 210.0 / 255.0, 0.0, 1.0];
 
-/// The client's duration-string formatter, `0x52fa50` — the one that turns a millisecond count
-/// into "2 hours remaining" / "45 seconds remaining" (wow-re `ui/scratch/tooltip-content-law.md`
-/// §3-BUFF-TIME-FORMAT, the 2026-08-14 carve). Its parameter vector is the binary's:
-/// `(V_ms, keyPrefix, roundUp)`, minus the `extraArg` slot only the enchant line fills.
-///
-/// **The ladder, with the thresholds decoded from the compare instructions** (`52fa76`, `52fab4`,
-/// `52fb03`, falling through to `0x52fb4f`): `≥ 86_400_000` → `_DAYS` · `≥ 3_600_000` → `_HOURS` ·
-/// `≥ 60_000` → `_MIN` · else `_SEC`. Each arm divides by its own threshold, so the number shown is
-/// always in the unit the arm names.
-///
-/// **`roundUp` ceils — but only in the top three arms; `_SEC` always truncates.** That asymmetry is
-/// the whole reason this is a shared function and not four `format!`s, and it is what produces the
-/// reference's three surprising readings: 61 s is "2 minutes remaining" (ceil, not "1"), 3 599 999 ms
-/// is "60 minutes remaining" (the hour arm needs the full hour, so there is no "1 hour" until
-/// exactly 3 600 000), and the final second before an aura lapses reads "**0** seconds remaining"
-/// (truncation, not "1").
-///
-/// **The text is the player's own `GlobalStrings.lua`, never ours.** `get` is the VM-global lookup
-/// (`load_global_strings` runs the shipped file into this VM at boot, off the patch chain); the
-/// template arrives as `"%d minutes remaining"` and the count fills its one `%d`. A key the string
-/// table doesn't carry yields **no line at all** rather than an invented one — the same disposition
-/// 0620 §5 took for a reagent whose template hasn't streamed. That is also why this house ships no
-/// copy of the eight strings: on an install they are read, and off one there is nothing to render.
+/// The client's duration formatter (`0x52fa50`): days, hours, minutes or seconds by threshold,
+/// each dividing by its own unit. `round_up` ceils every arm but seconds, which truncates, so 61 s
+/// reads "2 minutes" and 3 599 999 ms "60 minutes". The text is the player's own
+/// `GlobalStrings.lua` through `get`; a missing key renders no line.
 pub(in crate::script) fn duration_text(
     ms: u32,
     key_prefix: &str,
@@ -465,8 +375,6 @@ pub(in crate::script) fn duration_text(
     } else {
         ("SEC", SEC_MS)
     };
-    // `roundUp` reaches the day/hour/minute arms only — the seconds arm has no rounding branch at
-    // all, so it truncates whatever `roundUp` says.
     let n = if round_up && divisor != SEC_MS {
         ms.div_ceil(divisor)
     } else {
@@ -476,19 +384,9 @@ pub(in crate::script) fn duration_text(
     Some(template.replacen("%d", &n.to_string(), 1))
 }
 
-/// [`crate::strings::plural`] for this module's callers — the `_P1` pick behind
-/// `GetText(token, gender, n)`, whose byte law (and the refuted `> 1` reading: `703c89` is a
-/// *signed* test, so a zero ordinal takes the plural arm and a lapsing aura reads "0 seconds
-/// remaining") now lives with the primitive rather than in a fourth private copy of it. Four
-/// copies of one rule is the shape decision 2045 wrote about; `fill` had eight.
-///
-/// **Gender is not modelled, and that is faithful, not a gap:** `0x52fa50` pushes a literal `0`
-/// on both arms (`52fb8d: 6a 00`, `52fbaa: 6a 00`), which `0x703bf0` turns into nil, and enUS
-/// folds nil to no suffix.
-///
-/// (When BOTH the twin and the bare token are absent the reference renders an EMPTY line, off its
-/// pre-seeded `0x882748`; we render no line at all. Unreachable with shipped data — all eight of
-/// the aura family's keys ship — and off an install there is no string table to be faithful to.)
+/// [`crate::strings::plural`], the `_P1` pick of `GetText(token, gender, n)`. There is no gender:
+/// the formatter passes a literal 0 (`0x52fa50`), which `0x703bf0` reads as nil. With neither key
+/// present the lookup yields "" (`0x882748`), which the line core drops, so no line either way.
 pub(in crate::script) fn plural_template(
     token: &str,
     n: u32,
@@ -497,8 +395,7 @@ pub(in crate::script) fn plural_template(
     crate::strings::plural(token, Some(n), get)
 }
 
-/// A colour-component argument — `lua_tonumber`'s coercion (a numeric string counts, `""` and
-/// other strings don't).
+/// A colour component by `lua_tonumber`'s coercion: a numeric string counts, other strings do not.
 fn color_num(v: Option<&Value>) -> Option<f32> {
     match v {
         Some(Value::Number(n)) => Some(*n as f32),
@@ -508,9 +405,9 @@ fn color_num(v: Option<&Value>) -> Option<f32> {
     }
 }
 
-/// The bindings' boolean-argument read (`GetBoolOrDefault`, byte-pinned in the §0-BINDINGS
-/// verdict): nil/absent, false, numeric 0, and the strings `"0"`/`"off"`/`"disabled"` are
-/// false; everything else is true.
+/// A wrap flag: nil, false, 0 and the strings "0", "off" and "disabled" are false, anything else
+/// true. The reference reads it with `GetBoolOrDefault` (`0x6f1c10`,
+/// `binding_abi::bool_or_default`), where "false", "no" and 0.5 are false too.
 fn bool_arg(v: Option<&Value>) -> bool {
     match v {
         None | Some(Value::Nil) | Some(Value::Boolean(false)) => false,
@@ -523,12 +420,8 @@ fn bool_arg(v: Option<&Value>) -> bool {
     }
 }
 
-/// The colour block of an `AddLine`-family tail (the values at the r/g/b positions): applied
-/// only when the r-slot is a number (`lua_isnumber` — the sole gate, §0-BINDINGS verdict);
-/// anything else drops the WHOLE block to the default gold [`DEFAULT_TEXT_GOLD`] — the ref's
-/// gold zone tooltip, whose `(text, "", 1.0, 1.0, 1.0)` shape has `""` at the r-slot. When the
-/// gate passes, g/b are UNGATED `lua_tonumber` reads: a missing/non-number component is **0.0**
-/// (byte-pinned). Alpha is forced opaque (the bindings pack `0xFF`).
+/// An `AddLine`-family colour, gated on the r-slot alone (`lua_isnumber`, `0x6f34d0`), else
+/// [`DEFAULT_TEXT_GOLD`]; past the gate a non-number g or b reads 0, and alpha is always opaque.
 fn parse_line_color(r: Option<&Value>, g: Option<&Value>, b: Option<&Value>) -> [f32; 4] {
     match color_num(r) {
         Some(r) => [
@@ -541,9 +434,8 @@ fn parse_line_color(r: Option<&Value>, g: Option<&Value>, b: Option<&Value>) ->
     }
 }
 
-/// Parse an `AddLine` tail (the args after `text`): positional `r, g, b, wrapText` — the
-/// byte-pinned `0x531630` signature. The wrap flag is read at its position REGARDLESS of the
-/// colour gate (the ref's zone-tooltip shape wraps: its trailing `1.0` lands in the wrap slot).
+/// An `AddLine` tail, positional `r, g, b, wrap` (`0x531630`); the wrap flag is read whatever the
+/// colour gate decides.
 fn parse_line_tail(args: &[Value]) -> ([f32; 4], bool) {
     (
         parse_line_color(args.first(), args.get(1), args.get(2)),
@@ -551,8 +443,7 @@ fn parse_line_tail(args: &[Value]) -> ([f32; 4], bool) {
     )
 }
 
-/// A Lua text argument → the line's string: strings pass through, numbers stringify (Lua
-/// coercion), nil/absent is an empty line (`GameTooltip:AddLine()` ships in the corpus).
+/// A text argument as a line's string: numbers stringify as Lua does, and nil is empty.
 fn text_of(v: Option<&Value>) -> String {
     match v {
         Some(Value::String(s)) => s.to_str().map(|s| s.to_string()).unwrap_or_default(),
@@ -569,10 +460,9 @@ fn text_of(v: Option<&Value>) -> String {
     }
 }
 
-/// Append one line (both columns; `right = None` leaves the right cell hidden). Grows the pool,
-/// writes the cells, bumps `num_lines` (+ the line's wrap flag), cancels any fade. Does NOT show
-/// the tooltip — `AddLine` leaves showing to the caller (the corpus' `AddLine … Show()`),
-/// `SetText`/the content builders show themselves.
+/// Appends one line and cancels any fade, without showing the tooltip: `AddLine` callers call
+/// `Show`. The reference's line core drops a line whose sides are both empty (`0x530270`); this
+/// appends it.
 pub(super) fn append_line(
     lua: &Lua,
     this: &Table,
@@ -589,30 +479,14 @@ pub(super) fn append_line(
         _ => return Err(mlua::Error::runtime("not a GameTooltip")),
     };
     write_cell(&mut model, lh, &left.0, left.1);
-    // A wrap-flagged line PINS its wrap column at write time, so its very first measure ask
-    // carries the width and comes back WRAPPED (multi-row height) in the same frame. The old
-    // shape — layout re-pinning after an overflowing single-line measure — needed a second
-    // round-trip that the bag re-enter loop's per-frame content clear kept wiping out: wrapped
-    // lines never converged live (the plate under-counted their rows forever — the bread/
-    // hearthstone spill). One step, no oscillation.
-    // The wrap pin is written from the LINE's own flag every append — set for a wrap line,
-    // cleared for a plain one — so a cell that changes role can never keep a stale pin, and
-    // `clear_content` needs no wipe of its own (which is what used to make this write differ
-    // every frame). The epoch bump is gated on a REAL change: in the hover re-enter loop the
-    // rebuilt line pins the same width it already carried, so tier 1 stays clean and the
-    // whole-UI fingerprint (tier 2) never runs — see `clear_content`'s note.
+    // The wrap width is pinned at append, so the first measure already comes back wrapped. It is
+    // written from this line's own flag every time, and layout is touched only on a change.
     let pin = wrap.then_some((crate::widget::TOOLTIP_WRAP_WIDTH, 0.0));
     if let Some(d) = model.region_data.get_mut(&lh) {
         if d.size != pin {
             d.size = pin;
-            // NAMED, not conservative (decision 1388). This writes one region's EXPLICIT SIZE and
-            // nothing else — no anchor target, no roster membership — which is the exact shape
-            // 1388 migrated every size setter to. It was missed because it is an internal write
-            // rather than a `SetWidth` binding, and the miss is expensive in the one place it can
-            // least afford to be: the pin flips whenever a line changes ROLE between wrapped and
-            // plain, which is what every hover from one item or spell to a differently-shaped one
-            // does. A conservative touch there re-derives the whole layout graph — every live
-            // frame's scale re-synced, every anchored region re-hashed — on each hover.
+            // A size-only write takes the named touch: a conservative one would re-derive the
+            // whole layout graph on every hover that turns a line between wrapped and plain.
             model.touch_layout_region(lh);
             // The wrap pin is the measure key's wrap-width input.
             model.touch_measure(lh);
@@ -631,8 +505,7 @@ pub(super) fn append_line(
 mod verbs;
 pub(super) use verbs::install;
 
-/// The full hide: drop the owner, cancel the fade, clear the content, hide the frame, fire
-/// `OnTooltipCleared`. Shared by the `Hide` method and the fade's end-of-ramp.
+/// The full hide shared by `Hide`, a `Show` with no owner or no lines, and the end of a fade.
 pub(super) fn hide_tooltip(lua: &Lua, h: FrameHandle) {
     {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -646,14 +519,8 @@ pub(super) fn hide_tooltip(lua: &Lua, h: FrameHandle) {
     fire_cleared(lua, h);
 }
 
-/// One line cell's layout input: `Some((w, h))` once the cell is shown with text AND the measure
-/// round-trip has answered; one floored unit each way for a shown but EMPTY cell (the reference's
-/// `AddLine("")` adds no line at all, and its virtual `GetHeight` never reads back `0.0`); `None`
-/// for hidden/cleared cells and for PENDING measures. A pending cell contributes nothing — no
-/// width, no height, and (in the caller) no gaps — so a fresh tooltip holds its declared default
-/// size until real extents land, instead of collapsing to a gaps-only rect (the guard the first
-/// cut got wrong: it summed LINE_GAP/DOUBLE_GAP for unmeasured rows, caught by the migration
-/// pass).
+/// A line cell's measured extent; `None` for a hidden or unmeasured cell, which adds no size and
+/// no gap, so a fresh tooltip keeps its declared size until its lines are measured.
 type Cell = Option<(f32, f32)>;
 
 fn cell(model: &Model, rh: crate::widget::RegionHandle) -> Cell {
@@ -663,13 +530,8 @@ fn cell(model: &Model, rh: crate::widget::RegionHandle) -> Cell {
         return None;
     }
     if text.is_empty() {
-        // The same floor the sweep applies to the line's own rect
-        // (`layout::FONTSTRING_MIN_SPAN`): the reference's `GetHeight` is virtual and ends in a
-        // one-unit clamp, so `0.0` is not a height any caller — plate arithmetic included — can
-        // read back off a FontString (wow-re `region-size-fallback.md` §3,
-        // `tooltip-blank-line-height.md` §3). Reporting zero here while the chain below the row
-        // resolved one unit is the B309 shape at 1/14th the size, and the point of one constant
-        // is that the two cannot drift apart.
+        // One unit each way, the floor of the line's own rect: the reference's `GetHeight`
+        // (`0x772a60`) clamps to one unit, so no FontString reads back 0.
         return Some((
             super::layout::FONTSTRING_MIN_SPAN,
             super::layout::FONTSTRING_MIN_SPAN,
@@ -678,54 +540,13 @@ fn cell(model: &Model, rh: crate::widget::RegionHandle) -> Cell {
     d.measured.map(|m| (m.w, m.h))
 }
 
-/// The auto-size + right-flush pre-pass, run at the top of every layout resolve (decision 0274):
-/// for each live GameTooltip, frame size = max measured line width (a double line is
-/// left + gap + right) + 2·pad, floored by `SetMinimumWidth`, × summed line heights + gaps; each
-/// visible right column's anchor re-points so its right edge sits at the text inset. Skips
-/// frames whose lines haven't been measured yet — the XML default size holds until the extents
-/// land. With a [`TextMeasure`](super::TextMeasure) installed that is the SAME `resolve`
-/// (`resolve` solves, fills the pending measures inline, and solves again, so this pre-pass runs
-/// a second time with real extents); without one it is the host's batch round-trip, one frame
-/// later, which is the engine-less path every measurer-free VM still takes.
-/// **ANCHOR_CURSOR — mode 6, re-anchored to the live cursor every frame** (`0x530b20`, the
-/// `CGameTooltip` override of `vtable+0x38` on `0x808f60`; wow-re
-/// `system/ui/scratch/tooltip-cursor-anchor-law.md` §1, three independent derivations agreeing
-/// instruction-for-instruction). Nine corpus files ask for it — `pfUI`'s tooltip, xpbar and chat
-/// modules, `pfQuest/browser.lua`, `TipBuddy` — and until decision 2176 benilla warned and placed
-/// them by some other mode.
-///
-/// The whole of the re-anchor is one `SetPoint`:
-///
-/// ```text
-/// 530b32  cmp [this+0x318],6 ; jne                    -- every other mode skips
-/// 530b3b  eax = [this+0xa0]                           -- the CSimpleTop root == [0xcf0bd8]
-/// 530b4f  ecx = [eax+0x111c] ; edx = [eax+0x1118]     -- the SAVED cursor, normalised [0,1]
-/// 530b63  call 0x41ad80                               -- x *= G44 (screen w), y *= G48 (screen h)
-/// 530b68  fld [this+0x7c] ; fdivr 1.0f                -- 1 / the tooltip's own effective scale
-/// 530b97  call 0x767c70(BOTTOM=7, [0xcf0bd8], BOTTOMLEFT=6, x/scale, y/scale, doResolve=1)
-/// ```
-///
-/// So **the plate's BOTTOM-centre is pinned to the screen's BOTTOMLEFT plus the cursor's absolute
-/// position** — centred horizontally on the cursor and sitting directly above it. Four details are
-/// worth keeping because none is guessable from the name:
-///
-/// * The `relativeTo` is the screen root passed **raw**, not `+0x24` like every other anchor — the
-///   `CSimpleTop`'s `CLayoutFrame` base sits at offset 0. Ours is [`SCREEN`](super::SCREEN), which
-///   is the same object.
-/// * The **divide by the tooltip's own effective scale** is the "cursor box recip": an anchor
-///   offset is stored raw and multiplied by the child's scale at resolve time, so dividing here is
-///   what makes the result land at the cursor's *absolute* position. Ours does the same divide,
-///   against the same scale [`GetWidth`](super::object::eff_scale) reads.
-/// * **The `SetOwner`-time offsets `+0x3c4/+0x3c8` do not participate** — 12 reads of them, every
-///   one on a modes-0..5 arm of `0x52fe90`.
-/// * There is **no `ClearAllPoints` here** (earned zero over the function's complete call set): one
-///   anchor slot is overwritten, and `0x767c70`'s own no-op gate — same target, same
-///   `relativePoint`, both offsets within 2⁻²² — is what keeps a still cursor free.
-///
-/// It runs from the per-frame update pump, which a hidden tooltip is not in (`0x76ad9d`
-/// deregisters on hide), and in the **same frame** as the placement it produces: the layout drain
-/// `0x768ed0` runs at `0x765799`, right after the `+0x38` loop and before the draw. Hence its home
-/// here, at the top of the resolve, beside the auto-size pass.
+/// `ANCHOR_CURSOR` (mode 6), re-anchored every frame by the update override `0x530b20`: one
+/// `SetPoint` (`0x767c70`) pins the plate's BOTTOM to the screen root's BOTTOMLEFT (`0xcf0bd8`)
+/// at the cursor position divided by the tooltip's own effective scale, so it sits centred above
+/// the cursor. There is no `ClearAllPoints`, and `SetPoint`'s no-op gate keeps a still cursor
+/// free. The `SetOwner` offsets play no part (only `0x52fe90` reads them). Only a shown tooltip is
+/// in the update pump (`0x76ad9d`), and the placement lands the same frame, before the layout
+/// drain (`0x768ed0`).
 fn cursor_anchor(model: &mut Model, h: FrameHandle) {
     let scale = crate::script::object::eff_scale(model, h);
     let (cx, cy) = model.cursor_pos;
@@ -737,7 +558,7 @@ fn cursor_anchor(model: &mut Model, h: FrameHandle) {
         cy / scale,
     );
     let input = model.layout_inputs.entry(h).or_default();
-    // `0x767c70`'s change-detect, in our own terms: one slot, replaced only on a real change.
+    // `0x767c70`'s change detect: the one slot is replaced only on a real change.
     let same =
         input.anchors.len() == 1 && crate::script::object::anchor_bits_eq(&input.anchors[0], &new);
     if same {
@@ -749,10 +570,8 @@ fn cursor_anchor(model: &mut Model, h: FrameHandle) {
 }
 
 pub(super) fn layout_tooltips(model: &mut Model) {
-    // The arena's tooltip registry, not the resolve's whole frame roster: this pre-pass runs at
-    // the top of EVERY resolve, and finding two or three tooltips by scanning ~4000 ids was most
-    // of what it cost (decision 1634). `frame_to_id` still gates each one — a tooltip outside the
-    // resolve's roster would mint an id here and take the ledger's conservative branch with it.
+    // Only tooltips in the resolve's roster: one outside it would mint an id here and take the
+    // layout ledger's conservative branch.
     let tips: Vec<FrameHandle> = model
         .arena
         .tooltip_kinds()
@@ -761,9 +580,7 @@ pub(super) fn layout_tooltips(model: &mut Model) {
         .filter(|h| model.frame_to_id.contains_key(h))
         .collect();
     for h in tips {
-        // Mode 6 first, and **before the line gate below**: the reference's per-frame update is
-        // not gated on content at all, only on the plate being in the pump's list — which is the
-        // shown list. See [`cursor_anchor`].
+        // Mode 6 runs before the line gate: the reference re-anchors any shown plate, lines or not.
         let cursor_mode = match model.arena.frame(h).map(|f| (&f.kind_state, f.shown)) {
             Some((KindState::Tooltip(t), shown)) => shown && t.anchor == TooltipAnchor::Cursor,
             _ => false,
@@ -784,13 +601,6 @@ pub(super) fn layout_tooltips(model: &mut Model) {
         if num == 0 {
             continue;
         }
-        // (Wrap columns are pinned at append time — append_line — so every measure here is
-        // already the wrapped one; no second round-trip.)
-        // Per-line metrics next (one read pass), then the size + right-flush writes. Only
-        // measured cells contribute — a row with no measured cell adds no height and no gap, and
-        // a tooltip with nothing measured yet is skipped whole (its declared size holds until the
-        // extents land — this resolve's own `fill_measures` with a measurer installed, the host's
-        // batch round-trip a frame later without one).
         let n = num.min(lefts.len()).min(rights.len());
         let rows: Vec<(Cell, Cell)> = (0..n)
             .map(|i| (cell(model, lefts[i]), cell(model, rights[i])))
@@ -812,22 +622,20 @@ pub(super) fn layout_tooltips(model: &mut Model) {
             maxw = maxw.max(lw + rw);
         }
         if counted == 0 {
-            continue; // nothing measured yet — hold the declared size
+            continue; // nothing measured yet: the declared size holds
         }
         maxw = maxw.max(min_w);
         if maxw <= 0.0 || totalh <= 0.0 {
             continue;
         }
         let input = model.layout_inputs.entry(h).or_default();
-        // `pad_w` = SetPadding's extra width (ref ItemRefTooltip: room for the close button).
+        // `pad_w` is `SetPadding`'s extra width (ItemRefTooltip's room for its close button).
         input.width = maxw + 2.0 * TOOLTIP_PAD + pad_w;
         input.height = totalh + 2.0 * TOOLTIP_PAD;
-        // This pre-pass runs INSIDE the resolve, so it must not open tier 1 (see the note method's
-        // own doc) — but the per-node ledger decision 1388's incremental pass seeds from still has
-        // to hear that these two inputs were written by something other than a Lua setter.
+        // Inside the resolve, so a note and not a touch; the incremental pass still has to hear
+        // that these inputs changed.
         model.note_layout_frame_write(h);
-        // Right-flush each double line: right edge = left.right + (maxw − left.width)
-        // = frame.left + pad + maxw = the text inset's right.
+        // Right-flush each double line: left.right + (maxw - left.width) is the text inset.
         for (i, (l, r)) in rows.iter().enumerate() {
             if r.is_none() {
                 continue;
@@ -847,19 +655,15 @@ pub(super) fn layout_tooltips(model: &mut Model) {
     }
 }
 
-/// Advance every fading tooltip (called from [`super::UiScript::tick`], the ScrollingMessage/
-/// Cooldown pattern): alpha ramps 1→0 over [`TOOLTIP_FADE_SECS`]; at the end the tooltip hides
-/// for real (owner dropped, content cleared, `OnTooltipCleared` fired).
+/// Advances every fading tooltip: alpha ramps from 1 to 0 over [`TOOLTIP_FADE_SECS`], then the
+/// full hide.
 pub(super) fn tick_fades(lua: &Lua) {
     let t = now(lua);
     let mut ramping: Vec<(FrameHandle, f32)> = Vec::new();
     let mut finished: Vec<FrameHandle> = Vec::new();
     {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
-        // The arena's tooltip registry (1634) — this runs every tick, and the roster it used to
-        // walk is ~4000 entries at a corpus UI. The `frame_to_id` gate is kept: `hide_tooltip`
-        // below writes layout, and a frame outside the resolve's roster takes the ledger's
-        // conservative branch.
+        // Roster-gated as in `layout_tooltips`, since `hide_tooltip` below writes layout.
         for &h in model.arena.tooltip_kinds() {
             if !model.frame_to_id.contains_key(&h) {
                 continue;
@@ -874,7 +678,7 @@ pub(super) fn tick_fades(lua: &Lua) {
                 continue;
             };
             if !frame.shown {
-                finished.push(h); // hidden mid-fade by other means — just tidy the state
+                finished.push(h); // hidden mid-fade by other means: just tidy the state
                 continue;
             }
             let a = 1.0 - ((t - start) / TOOLTIP_FADE_SECS) as f32;
diff --git a/crates/benilla-ui/src/script/tooltip/verbs.rs b/crates/benilla-ui/src/script/tooltip/verbs.rs
index 1768def6..b83607ea 100644
--- a/crates/benilla-ui/src/script/tooltip/verbs.rs
+++ b/crates/benilla-ui/src/script/tooltip/verbs.rs
@@ -1,7 +1,4 @@
-//! The GameTooltip Lua verb table — [`install`] registers the widget methods (SetOwner /
-//! AddLine / AddDoubleLine / SetText / ClearLines / SetMinimumWidth / SetPadding / FadeOut /
-//! IsOwned / NumLines / the anchor law) over the parent module's line-pool mechanics, then
-//! chains the item/unit content builders' method sets.
+//! The GameTooltip Lua methods over the parent module's line pool, plus the content builders'.
 
 use mlua::{Lua, Table, Value, Variadic};
 
@@ -21,50 +18,25 @@ use super::{
 pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     let m = lua.create_table()?;
 
-    // SetOwner(owner, anchorType [, x, y]) — the binding `0x5310d0` and the core it calls,
-    // `0x52ffe0(owner_region, mode, dx, dy)`: SetAlpha(255) (`0x52fff4`), fade-disarm
-    // (`0x530002`), `+0x314 = owner` (`0x53000c`), the mode (`0x530031`), the offsets, then the
-    // anchor-apply `0x52fe90`. We clear the content too, because the engine fires
-    // OnTooltipCleared: a fresh owner never inherits the last hover's lines or money.
+    // SetOwner(owner, anchorType [, x, y]): the binding `0x5310d0` calls the core `0x52ffe0`,
+    // which sets full alpha (`0x52fff4`), disarms the fade, stores the owner (`0x53000c`), mode
+    // and offsets, then applies the anchor (`0x52fe90`). The content clears and OnTooltipCleared
+    // fires, so a new owner never inherits the last hover's lines or money.
     //
-    // **The omitted / unreadable / unrecognised anchorType is mode 0 = ANCHOR_LEFT, silently.**
-    // `0x53120d` writes 0 into the binding's local mode *before any compare runs*; `0x531214`'s
-    // `lua_isstring` gate jumps the whole `SStrCmpI` chain when arg 3 is absent, nil, boolean or a
-    // table; the chain's last `jne` reaches the same join untouched; and `[0x531221, 0x53133a)`
-    // contains no `luaL_error` (earned zero, positive-controlled against the five this function
-    // *does* have in its owner-validation prologue). `0x5313c0` then hands that local to the core.
+    // A missing, non-string or unknown anchorType is mode 0, ANCHOR_LEFT, with no error: the
+    // binding's local starts at 0 (`0x53120d`). The core's pre-store of 7 (`0x530012`) survives
+    // only a NULL owner, the un-own path (`0x530a60`) of every hide.
     //
-    // The core's own `mov [+0x318],7` at `0x530012` is **not** that default: it is an
-    // unconditional pre-store that `0x530031` overwrites with the argument, and it survives only
-    // when the owner pointer is NULL — the un-own path `0x530a60` takes on every hide.
-    //
-    // **The anchor-apply clears, and only ANCHOR_PRESERVE escapes it** (`0x52fe90` read
-    // contiguously): a NULL owner returns at `0x52fe9e`; **mode 8 returns at `0x52fead`, before
-    // the clear**; then `0x52feb8` tests the caller's arg1, which `0x530037` always passes as
-    // **1** (`0x53002d push 0x1`), so the mode-7 skip at `0x52feba` is dead on this path and
-    // `0x52fec2 call 0x767ed0` (ClearAllPoints) runs for **every mode 0..7**; and only then does
-    // `0x52fed0 ja` send 6 and 7 home while 0..5 take the SetPoint jump table `0x52ffbc`.
-    //
-    // So the three arms below are: 0..5 clear-and-point, **6 and 7 clear**, 8 nothing. Decision
-    // 2176 replaces 2142's open thread 1, which had it backwards on both counts — it read the
-    // core's pre-store as the Lua default and read "no SetPoint" as "no clear", and a wow-re §5
-    // dispatched for the CURSOR mechanism refuted both at the bytes (`system/ui/scratch/`
-    // `tooltip-cursor-anchor-law.md` §0.2/§0.3/§2).
+    // The anchor apply returns first for ANCHOR_PRESERVE (8, `0x52fead`), then clears all points
+    // (`0x767ed0` at `0x52fec2`) for modes 0..7; modes 0..5 then set a point (`0x52ffbc`).
     m.set(
         "SetOwner",
         lua.create_function(
             |lua, (this, owner, anchor, x, y): (Table, Table, Value, Option<f32>, Option<f32>)| {
                 let h = frame_handle_of(lua, &this)?;
                 let owner_h = frame_handle_of(lua, &owner)?;
-                // The gate is `lua_isstring 0x6f3510`, whose whole body is `lua_type` then
-                // `cmp eax,4 / cmp eax,3` — LUA_TSTRING or LUA_TNUMBER and nothing else — so the
-                // anchor argument is read the reference's way, by COERCION, and a boolean, table,
-                // function or userdata is indistinguishable from absent. Taking it as
-                // `Option<String>` made mlua's converter the gate instead, and mlua raises on a
-                // table: `Questie`'s `Tooltip:SetOwner(this, this)` (QuestieNotes.lua, the map-note
-                // hover) died with "bad argument #3: error converting Lua table to String" on a
-                // call the reference completes silently at mode 0. This function's doc comment has
-                // stated the law since 2176 — only the signature disagreed.
+                // The gate is `lua_isstring` (`0x6f3510`): a string or number is read, and any
+                // other type counts as absent rather than raising.
                 let anchor = optional_string(lua, &anchor);
                 {
                     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -72,17 +44,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                     full_alpha(&mut model, h);
                     tip_mut(&mut model, h)?.owner = Some(owner_h);
                     let owner_id = model.frame_id(owner_h);
-                    // The anchor mode is resolved ONCE, into the reference's own enum, and both
-                    // the placement below and `GetAnchorType`'s answer are taken from that one
-                    // value — so the plate and the getter can never tell different stories.
-                    //
-                    // Absent, unreadable and unrecognised all land on **ANCHOR_LEFT**, which is
-                    // the binding's zero-initialised local (`0x53120d`) surviving the
-                    // `lua_isstring` gate or the compare chain, with no raise. The warning on the
-                    // unrecognised leg is ours and stays: the reference is silent, but nothing
-                    // observable to Lua changes, and this exact warning is what made
-                    // `ANCHOR_CURSOR` visible as a real ninth mode nine corpus files ask for
-                    // rather than a typo (2142's open thread 2).
+                    // Resolved once: the placement and `GetAnchorType` both read this value. The
+                    // warning on an unknown name is ours; the reference is silent, and Lua sees no
+                    // difference.
                     let anchor = match anchor
                         .as_deref()
                         .map(str::to_ascii_uppercase)
@@ -118,23 +82,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                             None
                         }
                     };
-                    // **Modes 6 and 7 CLEAR and stop; mode 8 does neither.** `0x52fe90` reaches
-                    // `0x52fec2 call 0x767ed0` for every mode 0..7 — the mode-7 skip beside it is
-                    // gated on an arg1 that `SetOwner`'s core always passes as 1 — and mode 8
-                    // returned two compares earlier, at `0x52fead`, without touching anything.
-                    //
-                    // For ANCHOR_NONE that clear is what makes `GameTooltip_SetDefaultAnchor`
-                    // (`SetOwner(owner, "ANCHOR_NONE")` → `ClearAllPoints()` → `SetPoint(...)`,
-                    // the path of every action-bar hover) safe: a stale owner anchor cannot win
-                    // the frame the caller forgets to re-point. For ANCHOR_CURSOR it is the
-                    // opening move of a placement the per-frame update finishes
-                    // (`script::tooltip::cursor_anchor`).
-                    //
-                    // Dropping every anchor is a retarget to the EMPTY target set, and it names
-                    // its node like any other (decision 1625). It matters here more than
-                    // anywhere: left on the conservative touch, this line was a whole-graph
-                    // derivation on every action button the cursor crossed and on nothing else —
-                    // exactly the shape the director's recorder reported (decision 1630).
+                    // Modes 6 and 7 clear all points and stop. The clear lets
+                    // `GameTooltip_SetDefaultAnchor` (GameTooltip.lua:76-77) set one point with no
+                    // stale owner anchor; mode 6 is then placed per frame by `cursor_anchor`. The
+                    // drop is a named retarget to no targets, not a conservative touch.
                     if matches!(anchor, TooltipAnchor::Cursor | TooltipAnchor::None) {
                         let dropped = match model.layout_inputs.get_mut(&h) {
                             Some(input) if !input.anchors.is_empty() => {
@@ -151,18 +102,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                         let new =
                             Anchor::new(own, owner_id, rel, x.unwrap_or(0.0), y.unwrap_or(0.0));
                         let input = model.layout_inputs.entry(h).or_default();
-                        // The no-op compare keeps the per-frame SetOwner idiom (the bag
-                        // hover's OnUpdate re-enter) from dirtying tier 1 by itself; the
-                        // content clear above already reports its own writes.
+                        // No-op when unchanged, so the bag hover's per-frame SetOwner does not
+                        // dirty the layout.
                         let same = input.anchors.len() == 1
                             && crate::script::object::anchor_bits_eq(&input.anchors[0], &new);
                         if !same {
-                            // The plate re-points at the button under the cursor, which moves
-                            // an EDGE — structural under 1388, and therefore a whole-graph
-                            // derivation on every bag slot and every spellbook button a hover
-                            // sweep crossed. It names its node now (decision 1625): the old
-                            // and new target lists are both right here, so the cached graph's
-                            // edges are re-pointed instead of thrown away.
+                            // A named retarget: the cached layout graph re-points this edge
+                            // instead of being rebuilt.
                             let old_targets: Vec<u32> =
                                 input.anchors.iter().map(|a| a.relative_to).collect();
                             input.anchors = vec![new];
@@ -175,14 +121,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // GameTooltip:BenillaGetTooltipOwner() — **ours, and the prefix is what makes it honest.**
-    // 1.12 registers `IsOwned` (ask about ONE frame) and no getter at all, so there is no
-    // reference spelling for "which frame owns this plate" to be faithful to; a `GetOwner` here
-    // would be an unexplained superset an addon can feature-detect (1188, and the census that
-    // moved it, 2142). Under the `Benilla` prefix it is unreachable by accident from an addon
-    // that means to call a WoW function. Its one caller is the dev-only hover recorder
-    // (`benilla-app/src/hover_log.rs`), which needs the owner's NAME per frame so a trace reads
-    // the same names the director sees.
+    // GameTooltip:BenillaGetTooltipOwner(): not a 1.12 method (1.12 has only `IsOwned`); the dev
+    // hover recorder (`benilla-app/src/hover_log.rs`) reads the owner's name through it.
     m.set(
         "BenillaGetTooltipOwner",
         lua.create_function(|lua, this: Table| {
@@ -199,21 +139,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // GetAnchorType() — ONE string, the mode the last SetOwner placed this plate by
-    // (`0x5313e0`, table `0x854198`, argc 1, arity 1, kinds `(string)`; it reads `[+0x318]` back
-    // through the 9-entry name table `0x531530`). The kinds column has no nil alternative and this
-    // does not answer one: a tooltip nothing has owned yet answers `"ANCHOR_NONE"`, which is
-    // [`TooltipAnchor`]'s default and the same mode the reference's own SetOwner core falls back to.
-    //
-    // Two corpus callers, both unguarded, both raising against this VM until now, and they are the
-    // two shapes the verb has: `pfUI/modules/tooltip.lua:97` compares against ONE mode
-    // (`if GameTooltip:GetAnchorType() == "ANCHOR_NONE" then` — its OnShow reposition, so an equality
-    // on the exact reference spelling), and `_Nameplates/_Nameplates.lua:479` compares against a
-    // mode it computed (`if GameTooltip:GetAnchorType() ~= Anchor then GameTooltip:SetOwner(Column,
-    // Anchor) end` — a re-SetOwner suppressor, so an answer that never equals what SetOwner was
-    // given would re-own the plate on every OnUpdate). Both need the string to round-trip through
-    // the setter verbatim, which is why the mode is resolved once up there and read straight back
-    // here rather than re-derived from the plate's anchors.
+    // GetAnchorType(): the last SetOwner's mode by name (`0x5313e0`, name table `0x531530`), never
+    // nil; a never-owned tooltip answers "ANCHOR_NONE". The reference also answers it after any
+    // hide, whose un-own leaves mode 7; this keeps the last mode. Addons compare it with what they
+    // passed to SetOwner, so the name must round-trip.
     m.set(
         "GetAnchorType",
         lua.create_function(|lua, this: Table| {
@@ -221,9 +150,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(anchor.name())
         })?,
     )?;
-    // IsOwned(frame) — the hover re-enter loop's gate (ref ContainerFrame.lua OnUpdate): true
-    // only while `frame` is the live owner; the owner drops on hide, so a hidden tooltip never
-    // resurrects from a stale OnUpdate.
+    // IsOwned(frame): the hover loop's OnUpdate gate (`ContainerFrame.lua:657`); the owner drops
+    // on hide, so a stale OnUpdate never brings a hidden tooltip back.
     m.set(
         "IsOwned",
         lua.create_function(|lua, (this, frame): (Table, Table)| {
@@ -233,13 +161,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetText(text, r, g, b, alpha, textWrap) — the byte-pinned `0x531b90` signature (alpha is
-    // a REAL parsed argument here, its own isnumber gate, default 1.0 — unlike AddLine's forced
-    // opaque; GameTooltip_AddNewbieTip passes `(text, r, g, b, 1, 1)`). `text` is REQUIRED — a
-    // non-string raises the binding's own 'Usage: SetText("text" [, color])' FrameScript error
-    // and adds no line. No colour args → the engine default GOLD. Clears, writes line 1,
-    // SHOWS — the corpus never calls Show after SetText (PaperDoll's empty-slot text relies
-    // on it).
+    // SetText(text, r, g, b, alpha, wrap) (`0x531b90`): alpha has its own number gate, default 1,
+    // and a text that is neither string nor number raises the binding's usage error. It clears,
+    // writes line 1 and shows: the empty-slot hover calls no Show after it
+    // (PaperDollFrame.lua:747).
     m.set(
         "SetText",
         lua.create_function(|lua, (this, args): (Table, Variadic<Value>)| {
@@ -270,27 +195,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // AppendText(text) — `0x531e30`. The reference's bag/bar tooltips build a title with SetText
-    // and then hang the keybinding on the end of that same line rather than adding a second one:
-    //
-    //     GameTooltip:SetText(TEXT(BACKPACK_TOOLTIP), 1.0, 1.0, 1.0);
-    //     if ( GetBindingKey("TOGGLEBACKPACK") ) then
-    //         GameTooltip:AppendText(" "..NORMAL_FONT_COLOR_CODE.."("..key..")"..FONT_COLOR_CODE_CLOSE)
-    //     end
-    //
-    // — ContainerFrame.xml l.188-206 (the bag window's portrait button, one arm per bag id) and
-    // MainMenuBarBagButtons.xml l.96 / .lua l.91 (the bar's). Both files run off the player's own
-    // chain (1751), so those are live call sites in this VM, not transcriptions we could adjust.
-    //
-    // LINE 1's left cell, appended in place, keeping its colour: the escape codes in the argument
-    // are what colour the suffix, which only works if it lands INSIDE an existing line. A tooltip
-    // with no lines yet is a no-op rather than a raise — the reference's own callers always
-    // SetText first, and nothing is carved about the empty case.
-    //
-    // INFERRED, pending the byte carve of `0x531e30`: that it is line 1 rather than the last line
-    // added. Every attested call site sets exactly one line before appending, so the two readings
-    // are indistinguishable from the corpus alone; line 1 is chosen because the reference's own
-    // name for the target is `GameTooltipTextLeft1`. Re-measure is unconditional either way.
+    // AppendText(text) (`0x531e30`): appends to line 1's left cell in place, keeping its colour,
+    // and does nothing with no lines, as the reference's body does (`0x5305b0`, line 1 at
+    // `0x5305cc`). The bag tooltips hang a keybinding on their SetText title with it
+    // (ContainerFrame.xml:198, MainMenuBarBagButtons.lua:91).
     m.set(
         "AppendText",
         lua.create_function(|lua, (this, text): (Table, Value)| {
@@ -313,10 +221,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // AddLine(text [, r, g, b [, wrap]]) — positional; the corpus' archaic `(text, "", r, g, b)`
-    // shape has a non-number in the r-slot, so the real binding drops the colour tail and the
-    // line renders the default GOLD (the ref's zone/taxi/repair tooltips — director-matched).
-    // Appends without showing.
+    // AddLine(text [, r, g, b [, wrap]]): positional, and appends without showing; the
+    // `(text, "", r, g, b)` shape has a non-number r-slot, so it renders default gold.
     m.set(
         "AddLine",
         lua.create_function(|lua, (this, args): (Table, Variadic<Value>)| {
@@ -325,11 +231,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             append_line(lua, &this, (text, color), None, wrap)
         })?,
     )?;
-    // AddDoubleLine(textL, textR, rL, gL, bL, rR, gR, bR [, wrap]) — the two-column line
-    // (slot|type, damage|speed), byte-pinned `0x531840`: each side's colour gates on ITS OWN
-    // r-slot isnumber (default gold, g/b ungated → 0.0, alpha forced opaque), and the wrap arg
-    // is dead weight — the core forces wrap=0 whenever the right text is non-empty. The right
-    // column right-flushes in the layout pass.
+    // AddDoubleLine(textL, textR, rL, gL, bL, rR, gR, bR [, wrap]) (`0x531840`): each side's
+    // colour gates on its own r-slot. The core forces wrap off when the right text is non-empty;
+    // this never wraps.
     m.set(
         "AddDoubleLine",
         lua.create_function(
@@ -362,19 +266,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         "NumLines",
         lua.create_function(|lua, this: Table| with_tip(lua, &this, |t| t.num_lines as i64))?,
     )?;
-    // AddFontStrings(left, right) — adopt two caller-made FontStrings as the next line pair
-    // (`0x530c40`, wow-re `system/ui/scratch/bindings.md`; the parent module's doc already names it
-    // as how the real class grows past its template's 30 declared pairs).
-    //
-    // The scan-tooltip idiom, and the reason this landed with the font-object work rather than
-    // separately: `Gratuity-2.0.lua:56-59` builds its whole 30-line hidden tooltip out of
-    // `tt:CreateFontString()` + `:SetFontObject(GameFontNormal)` + `tt:AddFontStrings(l, r)`, so
-    // publishing the font globals only moved that library's death one line down. Five corpus addons
-    // sit behind those four lines.
-    //
-    // The pair is placed exactly as an engine-grown one (hidden, left/right justified, hung off the
-    // previous line) — the layout pass owns line geometry either way — but the regions' FONTS are
-    // left alone, since choosing them is the entire point of the caller doing this by hand.
+    // AddFontStrings(left, right) (`0x530c40`): adopts two caller-made FontStrings as the next
+    // line pair, placed like an engine-grown pair but keeping the caller's fonts.
     m.set(
         "AddFontStrings",
         lua.create_function(|lua, (this, left, right): (Table, Table, Table)| {
@@ -419,31 +312,31 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 d.justify.set_h(crate::script::JustifyH::Right);
                 d.anchors = vec![Anchor::new(Point::Right, left_id, Point::Right, 0.0, 0.0)];
             }
-            model.touch_layout(); // two line rows entered the layout graph (decision 0740)
+            model.touch_layout(); // two line rows entered the layout graph
             let t = tip_mut(&mut model, h)?;
             t.left_lines.push(lh);
             t.right_lines.push(rh);
             Ok(())
         })?,
     )?;
-    // SetMinimumWidth(w) — a floor on the auto-sized width (the ref's SetTooltipMoney calls it
-    // with the money row's width so coins never overhang the plate).
+    // SetMinimumWidth(w): a floor on the auto-sized width (`SetTooltipMoney` passes the money
+    // row's, GameTooltip.lua:91).
     m.set(
         "SetMinimumWidth",
         lua.create_function(|lua, (this, w): (Table, f32)| {
             with_tip(lua, &this, |t| t.min_width = w.max(0.0))
         })?,
     )?;
-    // SetPadding(w) — extra auto-size width (ref ItemRefTooltip OnLoad: SetPadding(16) keeps the
-    // corner close button off the text). A frame property — persists across content clears.
+    // SetPadding(w): extra auto-size width that survives a content clear (ItemRefTooltip's 16
+    // keeps its close button off the text, ItemRef.xml:40).
     m.set(
         "SetPadding",
         lua.create_function(|lua, (this, w): (Table, f32)| {
             with_tip(lua, &this, |t| t.padding = w.max(0.0))
         })?,
     )?;
-    // FadeOut() — the world-mouseover loss ramp (alpha 1→0 over TOOLTIP_FADE_SECS, INTERIM
-    // constant, then a real hide). Fresh content or Show cancels it.
+    // FadeOut(): alpha ramps to 0 over `TOOLTIP_FADE_SECS`, then the full hide; new content or
+    // Show cancels it.
     m.set(
         "FadeOut",
         lua.create_function(|lua, this: Table| {
@@ -455,29 +348,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // Show/Hide — shadow the shared pair (kind tables resolve first) to keep the tooltip's
-    // state honest: Show cancels a fade at full alpha; Hide drops the owner + content and fires
-    // OnTooltipCleared (the ref clears its money row through exactly that script).
-    // Show is an EXISTENCE GATE, not a plain show. `0x530a80` — the CGameTooltip override of
-    // `vtbl+0x88`, which is the slot a Lua `:Show()` lands in (the generic widget Show path
-    // `0x7a3350` sets `[+0xd0]=1` then calls slot `+0x88`) — shows only when BOTH `+0x314` (the
-    // owner) and `+0x31c` (the line count) are non-zero; otherwise it calls its own `vtbl+0x84`
-    // effective-hide `0x530a60`, which is the SetOwner core with a NULL owner, so the plate is
-    // hidden AND un-owned and OnTooltipCleared fires. Evaluated at Show time only — it is never a
-    // visibility poll. (wow-re `system/ui/ledger.tsv` row `0x530a80`, verified, and
-    // `scratch/hover-hide-and-tooltip-owner-law.md` §4.)
-    //
-    // Without the gate an addon that reaches `Show()` having added no lines leaves a VISIBLE
-    // empty plate — and, because `layout_tooltips` skips a zero-line plate rather than collapsing
-    // it, one still wearing the last hover's width and height. That is what `Questie`'s tracker
-    // does: `QuestieTracker.lua`'s quest-button OnEnter has a dead zone between its two arms (an
-    // in-progress quest whose objective text IS in its database adds nothing) and then calls
-    // `Tooltip:Show()` unconditionally. On the reference `0x530a80` swallows it; we drew the
-    // empty plate.
-    //
-    // `show_or_hide_empty` is the same law for the app-answered content asks, and deliberately
-    // does NOT un-own (its re-enter repaint needs the owner). This path is the reference's own,
-    // so it takes the reference's full effective-hide.
+    // Show and Hide shadow the shared pair. Show (`0x530a80`, the override the generic Show at
+    // `0x7a3350` calls) shows only a plate with an owner and at least one line, checked at Show
+    // time only; otherwise it takes the full hide (`0x530a60`): un-owned, cleared,
+    // OnTooltipCleared fired. Hide is the full hide.
     m.set(
         "Show",
         lua.create_function(|lua, this: Table| {
@@ -505,17 +379,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The item content channels (BenillaSetItemById/SetBagItem/SetMerchantItem/SetBuybackItem) live in
-    // their own module — the one shared renderer + the red usable law (decision 0274 P1).
+    // The content methods: items, spells and auras, talents, units.
     crate::script::tooltip_item::install_methods(lua, &m)?;
-    // The spell/aura/action content channels (SetSpell/SetShapeshift/SetPlayerBuff/SetAction) —
-    // the verified spell-builder law (decision 0274 P2, grounded by 0276).
     crate::script::tooltip_spell::install_methods(lua, &m)?;
-    // The talent channel (SetTalent) — the spell builder with the talent interleave
-    // (decision 0304).
     crate::script::talent::install_tooltip_method(lua, &m)?;
-    // The unit content channel (SetUnit + the world-mouseover drivers) — the verified unit law
-    // (decision 0274 P3, grounded by 0276).
     crate::script::tooltip_unit::install_methods(lua, &m)?;
 
     lua.set_named_registry_value(REG_TOOLTIP_METHODS, m)?;
diff --git a/crates/benilla-ui/src/script/tooltip_item/mod.rs b/crates/benilla-ui/src/script/tooltip_item/mod.rs
index d1896bd3..02dc756e 100644
--- a/crates/benilla-ui/src/script/tooltip_item/mod.rs
+++ b/crates/benilla-ui/src/script/tooltip_item/mod.rs
@@ -1,56 +1,14 @@
-//! The engine **item-tooltip renderer** (decision 0274 P1) — the one line law every item hover
-//! renders through, mirroring the real client's single shared C++ renderer (`0x52b650`, behind
-//! 8 of the 9 `Set*Item` bindings — wow-re `ui/scratch/tooltip-money.md`). The entry methods
-//! (`SetBagItem`, `SetMerchantItem`, `SetBuybackItem`, and the prefixed `BenillaSetItemById` —
-//! ours, because 1.12 has no id-keyed door onto the shared renderer) register into the
-//! GameTooltip kind table beside the widget verbs ([`super::tooltip`]).
+//! The engine item-tooltip renderer: every item hover renders through one line law, as 8 of the
+//! reference's 9 `Set*Item` bindings share the builder `0x52b650`. The methods register into the
+//! GameTooltip kind table beside the widget verbs ([`super::tooltip`]). Every family's order,
+//! gate and colour is the reference's, and every sentence is a key resolved off the player's own
+//! `GlobalStrings.lua` at render time. Red (`0xc0d390`, `0xffff2020`) marks unmet requirements,
+//! LOCKED, broken durability and "Already known"; the name never recolors.
 //!
-//! **The line law is BYTE-VERIFIED** — the 0274 §5 verdict on `0x52b650`'s emission order
-//! (wow-re `ui/scratch/tooltip-content-law.md`, §5-cross-checked; folded back 2026-07-10):
-//! every family's order, gate, and color pointer is the binary's, and every sentence is a KEY
-//! resolved off the player's own `GlobalStrings.lua` at render time (decision 2045). Not yet
-//! built (feeds pending, laws recorded): the instance families (soulbound override, enchants,
-//! made-by, live durability, cooldown-remaining).
-//! Residual INTERIMs cited inline: the dual-wield/off-hand proficiency exception
-//! (`0x5eab70`), the type cell's override red, the set-owned count source.
-//!
-//! **Compare mode** (0274 P4, re-based by 2202, scoped back to the reference by 2210, and
-//! corrected to the census by 2216): `SetInventoryItem` on an ARMED shopping tooltip renders the
-//! equipped item's ORDINARY tooltip plus ONE extra line, first — the gray "Currently Equipped"
-//! (`[arg+0x18]≠0`). That is the entire difference. The builder's other flag, p4 `[arg+0x14]`,
-//! *is* a compact mode (white name, stat body jumped, early-return at `0x52e14c`) — but the two
-//! compare call sites pass it **zero**, so a shopping plate shows a quality-colored name and the
-//! full body, and a client that abbreviates here is wrong (wow-re `merchant-compare-item-law.md`
-//! §6). **Nothing in this engine seats a shopping plate**: the two callers that arm this mode
-//! are [`compare_against_worn`]'s own bindings — `SetMerchantCompareItem` and
-//! `SetAuctionCompareItem` — and the FrameXML that calls them (`MerchantFrame.xml:63-80`,
-//! `AuctionFrame`) owns the plates' geometry and lifetime, exactly as in 1.12.1. There is no
-//! hover compare in the reference at all: `SHOW_COMPARE_TOOLTIP` has zero fire sites in the whole
-//! image, so `PaperDollFrame.lua`'s slot listener is dead code there (wow-re
-//! `merchant-compare-item-law.md` §8).
-//!
-//! **`nameOnly`** (p4 `[arg+0x14]`, the flag 2216 had tangled with the header; built by 2224):
-//! the builder's
-//! compact mode, and the census that settled it found exactly one door onto it — this module's
-//! `SetInventoryItem`, third argument, a number `> 0`. It is what the image's own usage string
-//! `0x8552dc` calls it. No stock FrameXML caller passes it (all 8 sites are two-argument), so it
-//! is addon surface; it is nonetheless live code, and the mode is **trimmed, not bare** — the
-//! bind/lock region and the stat body are jumped and the tail is cut, but the slot/type cell,
-//! durability, every requirement line and the spell triggers all still print. Both flags ride in
-//! [`render::BuilderFlags`], a struct precisely so they cannot be collapsed again.
-//!
-//! **The red "you can't use this" law** (the director's explicit ask) — byte-verified §1-RED:
-//! red is the AddLine color `0xffff2020`, applied to requirement lines the ACTIVE player fails
-//! (level, class/race lists, skill rank, required spell), to LOCKED, to broken durability, and
-//! unconditionally to "Already known"; the NAME never recolors. Compared against
-//! [`super::PlayerReqState`] + the spellbook.
-//!
-//! The sell-price money row is the byte-verified law: only a REAL-INSTANCE source (`SetBagItem`)
-//! while the merchant window is open and repair mode is off — the engine computes
-//! `SellPrice × stack` and fires the `OnTooltipAddMoney` script; FrameXML renders the coins
-//! (`SetTooltipMoney`). A zero sell price in that context prints `ITEM_UNSELLABLE`
-//! (`0x854a74`, pushed at `0x52e4a3`). Template sources (`SetMerchantItem`/`BenillaSetItemById`/quest
-//! rows) never show money, per the same law.
+//! Stock FrameXML seats the shopping plates (`MerchantFrame.xml:63-80`,
+//! `Blizzard_AuctionUI.lua:1078`). There is no hover compare: `SHOW_COMPARE_TOOLTIP` has no fire
+//! site (`0x49211a` and `0x49630d` never produce event 377), so `PaperDollFrame.lua`'s listener
+//! for it is dead code.
 
 use mlua::{Lua, MultiValue, Table, Value};
 
@@ -64,17 +22,11 @@ mod render;
 use names::{quality_color, GRAY, WHITE};
 use render::{render_view, BuilderFlags};
 
-/// The compare tooltips' shared body — what `SetMerchantCompareItem 0x536080` and
-/// `SetAuctionCompareItem 0x535d70` both run once their wrapper has an offered template and a
-/// re-based `offset` (wow-re `merchant-compare-item-law.md`): walk the offered type's candidate
-/// slots (`0x809200[InventoryType]`), skipping EMPTY slots without decrementing and slots whose
-/// worn item's CLASS differs, until `offset` occupied matches have been passed; then fill the
-/// ordinary EQUIPPED-item tooltip with the compare header on — the FULL body (`p4 = 0`) plus one
-/// gray `CURRENTLY_EQUIPPED` line (`p5 = 1`), by arming the `equipped_header_armed` latch and running
-/// `SetInventoryItem`, which is what the reference does too:
-/// `0x536080` calls the ordinary item builder `0x52b650` with the header flag set. The NUMBER 1 on
-/// success; nil on a miss, which does NOT clear the tooltip (the reference's nil exit touches
-/// nothing else).
+/// The body both compare bindings run (`0x536080`, `0x535d70`): walk `0x809200[InventoryType]`'s
+/// slots, skipping empty ones uncounted and ones whose worn item's class differs (`0x5d9f30`),
+/// until `left` matches have passed; then run `SetInventoryItem` there with the header latch armed,
+/// as `0x536080` calls `0x52b650` with p4 = 0, p5 = 1. The number 1, or nil on a miss, which leaves
+/// the tooltip untouched.
 fn compare_against_worn(
     lua: &Lua,
     this: &Table,
@@ -90,7 +42,7 @@ fn compare_against_worn(
                 .inv_slot("player", slot as usize)
                 .filter(|s| s.item_id != 0)
             else {
-                continue; // empty: skipped WITHOUT decrementing
+                continue; // an empty slot is not counted
             };
             let same_class = model
                 .item_templates
@@ -121,8 +73,7 @@ fn compare_against_worn(
     Ok(Value::Integer(1))
 }
 
-/// Look up the store; a miss records the ask (the app sends `CMSG_ITEM_QUERY` and pushes back —
-/// the hover's re-enter loop repaints on arrival).
+/// The cached template; a miss records the ask, and the hover's re-enter loop repaints on arrival.
 fn view_of(lua: &Lua, item_id: u32) -> Option<ItemTemplateView> {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let v = model.item_templates.get(&item_id).cloned();
@@ -132,10 +83,8 @@ fn view_of(lua: &Lua, item_id: u32) -> Option<ItemTemplateView> {
     v
 }
 
-/// The enchant lines a **random-suffix roll** contributes, out of the pushed roll table — the
-/// reference's §E5 copy of the suffix row's five ids into enchant slots 2..6, which every
-/// block-supplying source with no item object relies on (loot, links, auction rows, the roll
-/// window). `0`, or an id the table doesn't name, contributes nothing.
+/// A random-suffix roll's enchant lines: the reference copies the suffix row's five ids into
+/// enchant slots 2..6 (`0x52b7bf`) for a block source with no item object.
 fn roll_enchants(lua: &Lua, random_property_id: u32) -> Vec<crate::script::EnchantView> {
     let model = lua.app_data_ref::<Model>().expect("model app_data");
     model
@@ -145,16 +94,13 @@ fn roll_enchants(lua: &Lua, random_property_id: u32) -> Vec<crate::script::Encha
         .unwrap_or_default()
 }
 
-/// The bracketed name out of an `|Hitem:…|h[Name]|h` link (the container slot's own display
-/// name — the miss-path fallback line's source).
 fn link_name(link: &str) -> Option<&str> {
     let start = link.find('[')? + 1;
     let end = link[start..].find(']')? + start;
     Some(&link[start..end])
 }
 
-/// Fire the engine→Lua money hand-off (`OnTooltipAddMoney(copper)` — the byte-verified protocol:
-/// the engine computes, FrameXML's `SetTooltipMoney` renders).
+/// Fire `OnTooltipAddMoney(copper)`: the engine computes, FrameXML's `SetTooltipMoney` draws.
 fn fire_add_money(lua: &Lua, h: crate::widget::FrameHandle, copper: u64) {
     let id = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -168,20 +114,10 @@ fn fire_add_money(lua: &Lua, h: crate::widget::FrameHandle, copper: u64) {
     ) {
         lua.app_data_mut::<Model>()
             .expect("model app_data")
-            .errors
-            .push(e.to_string());
+            .record_script_error(e.to_string());
     }
 }
 
-/// The `|Hitem:` payload's numeric fields — the full escaped shape
-/// (`|cff…|Hitem:2947:0:584:0|h[Name]|h|r`) or a bare `item:2947`.
-///
-/// The four are `(item id, enchant id, randomPropertyId, uniqueId)` — the reference's own link
-/// format `"%s|Hitem:%d:%d:%d:%d|h[%s]|h%s"` (`0x8549c8`), and `SetHyperlink 0x532181` parses them
-/// straight into the tooltip's instance block: token 1 → enchant slot 0 (`+0x3d0`), **token 2 →
-/// `+0x424`, the roll** (which §E5 then expands into slots 2..6), token 3 → `+0x420`, which
-/// nothing reads. Missing fields read `0`, like the bare `item:id` shape an addon may pass.
-/// The `enchant:<spellId>` of an enchant hyperlink, or `None` for any other link.
 fn hyperlink_enchant_spell(link: &str) -> Option<u32> {
     let at = link.find("enchant:")? + 8;
     let tail = &link[at..];
@@ -204,8 +140,7 @@ fn hyperlink_item_fields(link: &str) -> Option<(u32, u32, u32)> {
     (item_id != 0).then_some((item_id, enchant_id, random_property_id))
 }
 
-/// The shared id-keyed render (`BenillaSetItemById`/`SetHyperlink`): template hit → the full line law
-/// (+ the compare arm when this is the main GameTooltip); miss → the ask + a name-only line.
+/// The id-keyed render; on a miss, the ask and a name-only line, as `SetBagItem`'s miss path.
 fn render_by_id(
     lua: &Lua,
     this: &Table,
@@ -239,7 +174,6 @@ fn render_by_id(
     Ok(())
 }
 
-/// The quest-item hover: the row's item by id, or an empty tooltip when the row is not there.
 fn set_quest_item_view(
     lua: &Lua,
     this: &Table,
@@ -259,11 +193,8 @@ fn set_quest_item_view(
     }
 }
 
-/// The paperdoll slots an item of this InventoryType equips into (the 1.12
-/// `GetInventorySlotInfo` slot ids) — the compare drive's candidate slots. Two-slot families
-/// (rings, trinkets, one-hand weapons, and a two-hander displacing both hands) can fill both
-/// shopping plates. Twin of the app-side `ui_items::find_equip_slot` (the equip-click fit rule) —
-/// one law, two consumers.
+/// An InventoryType's compare candidate slots, as `GetInventorySlotInfo` ids: the reference's
+/// mask table `0x809200[InventoryType]`.
 fn equip_slots_for(inventory_type: u32) -> &'static [u32] {
     match inventory_type {
         1 => &[1],             // head
@@ -283,12 +214,8 @@ fn equip_slots_for(inventory_type: u32) -> &'static [u32] {
         13 => &[16, 17],       // one-hand
         21 => &[16],           // main hand
         14 | 22 | 23 => &[17], // shield / off-hand weapon / held
-        // Two-hand: **main hand ONLY**, which is not the obvious answer. A 2H displaces both
-        // hands when equipped, and this table was written `[16, 17]` on that reasoning. The
-        // reference's own mask disagrees: `0x809200[17]` is `0x8000`, bit 15, main hand alone
-        // (wow-re `merchant-compare-item-law.md` §3). It is a COMPARE-CANDIDATE table, not an
-        // occupancy one — the question it answers is "which worn item is this offering to
-        // replace", and for a two-hander that is the weapon in your main hand.
+        // Two-hand: main hand only, though a two-hander displaces both: `0x809200[17]` is
+        // `0x8000`, bit 15.
         17 => &[16],
         15 | 25 | 26 | 28 => &[18], // bow / thrown / wand-gun / relic
         _ => &[],
@@ -297,20 +224,10 @@ fn equip_slots_for(inventory_type: u32) -> &'static [u32] {
 
 /// Register the item content channels into the GameTooltip kind method table.
 pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // GameTooltip:BenillaSetItemById(itemId [, fallbackName, fallbackQuality]) — the id-keyed
-    // hover (quest reward rows, loot rows).
-    //
-    // **Ours, and the `Benilla` prefix is what keeps it honest.** 1.12's nine `Set*Item` bindings
-    // all name a CONTAINER — a bag slot, a merchant row, a loot slot — because the reference's
-    // callers always have one; nothing there takes a bare item id. Ours do: the channels in this
-    // module reach [`render_by_id`] as a Rust call, but the ones that live in a sibling module
-    // (`tooltip_spell`'s action-bar item arm, `SetTrainerService`, `SetCraftSpell`) reach it
-    // through the wrapper table, and that needs a NAME. Spelling that name like a WoW function
-    // would be an unexplained superset an addon can feature-detect (1188; the census that moved
-    // it, 2142); under the prefix it is unreachable by accident from an addon that means to call
-    // a WoW function, and no addon has reason to call it at all.
-    //
-    // Template source: no money row, per the byte-verified sell-price law.
+    // GameTooltip:BenillaSetItemById(itemId [, fallbackName, fallbackQuality]). Not a 1.12 verb,
+    // whose `Set*Item` bindings all name a container: sibling modules' item hovers (the action
+    // bar's, `SetTrainerService`, `SetCraftSpell`) reach `render_by_id` by this name through the
+    // wrapper table, and the prefix keeps it off the 1.12 surface.
     m.set(
         "BenillaSetItemById",
         lua.create_function(
@@ -320,13 +237,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetQuestItem(type, index) / SetQuestLogItem(type, index) — the quest-giver
-    // panels' and the quest log's reward/choice/required hovers (stock QuestFrameTemplates.xml:148,
-    // QuestLogFrame.xml:113; bindings 0x533610 / 0x533760, 3 args with self, 0 returns). `type` is
-    // the same "choice" | "reward" | "required" key `GetQuestItemInfo` takes, `index` the 1-based
-    // slot; the item is rendered by id through the shared renderer, with the row's own name and
-    // quality as the fallbacks a template that has not arrived yet paints from. An unknown type or
-    // an out-of-range index shows nothing — the reference's tooltip stays empty too.
+    // GameTooltip:SetQuestItem(type, index) / SetQuestLogItem(type, index) (`0x533610`,
+    // `0x533760`; `QuestFrameTemplates.xml:148`, `QuestLogFrame.xml:113`), no returns. `type` is
+    // `GetQuestItemInfo`'s; an unknown type or index leaves the tooltip empty, as in the reference.
     m.set(
         "SetQuestItem",
         lua.create_function(|lua, (this, kind, index): (Table, String, usize)| {
@@ -360,16 +273,14 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetHyperlink(link) — the chat-link tooltip (ref ItemRef.lua's SetItemRef →
-    // ItemRefTooltip:SetHyperlink). Accepts the full escaped link or a bare "item:<id>";
-    // non-item links (player/spell/quest) have no tooltip surface yet and no-op.
+    // GameTooltip:SetHyperlink(link): the chat-link tooltip (`ItemRef.lua:60`). Takes an item
+    // link, escaped or a bare "item:<id>", or an enchant link; any other link does nothing.
     m.set(
         "SetHyperlink",
         lua.create_function(|lua, (this, link): (Table, String)| {
-            // The client's only other link kind: `|Henchant:<spellId>|h[name]|h`, the craft
-            // window's enchant link (`GetCraftItemLink`, 1973), which `SetHyperlink` consumes
-            // behind the same castUI gate its producer stands behind (`0x532243`) — the spell's
-            // own tooltip, by id.
+            // The only other link it takes, the craft window's `|Henchant:<spellId>|h[name]|h`
+            // (`GetCraftItemLink`): the spell's own tooltip, behind its producer's castUI gate
+            // (`0x532243`).
             if let Some(spell) = hyperlink_enchant_spell(&link) {
                 return super::tooltip_spell::set_spell_by_id(
                     lua,
@@ -389,16 +300,13 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 clear_content(&mut model, h);
             }
             fire_cleared(lua, h);
-            // A link is a **block source** (`SetHyperlink 0x532181` passes p6=1), so it never
-            // reaches the `<Random enchantment>` arm and it does show the roll's own lines — the
-            // half of §E5 decision 0920's prose had backwards. The NAME comes off the link's own
-            // brackets: the sender's client built that text with the suffix already joined
-            // (`0x5d8b00` feeds the link builder), so re-deriving it would only invite the two to
-            // disagree.
-            //
-            // The link's ENCHANT field (slot 0, a permanent enchant like "Crusader") is parsed but
-            // not yet rendered: naming it needs the `SpellItemEnchantment` row, and no benilla
-            // surface writes that field into a link it composes today. A stated gap, not drift.
+            // The reference's format is `"%s|Hitem:%d:%d:%d:%d|h[%s]|h%s"` (`0x8549c8`), and
+            // `SetHyperlink` (`0x532181`) parses it into a block (p6=1): the enchant id to slot 0
+            // (`+0x3d0`), the roll to `+0x424` (expanded into slots 2..6 by `0x52b7bf`), the
+            // unique id to `+0x420`, unread; a missing field is 0. So a link shows its roll's
+            // lines, never the placeholder (`0x52cc33`). The name is the link's own, built with
+            // the suffix joined (`0x5d8b00`). The enchant id is parsed, not rendered: naming it
+            // needs its `SpellItemEnchantment` row, and no link benilla composes carries one.
             let inst = render::ItemInstance {
                 name: link_name(&link).map(str::to_string),
                 enchants: roll_enchants(lua, roll),
@@ -407,7 +315,6 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             match view_of(lua, id) {
                 Some(v) => {
                     render_view(lua, &this, &v, BuilderFlags::default(), Some(&inst))?;
-                    // Unchanged from the `render_by_id` this leg used to share: a link dropped on
                 }
                 None => {
                     if let Some(name) = link_name(&link) {
@@ -426,46 +333,20 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetInventoryItem(unit, slot) → hasItem, hasCooldown, repairCost — the equipped-slot hover
-    // (paperdoll slots, buff-frame weapon enchants) and the shopping-compare listener's render
-    // (ref PaperDollFrame.lua:626). **Unit-keyed** through `Model::inv_slot`, the same router the
-    // `GetInventoryItem*` getters use: `"player"` from the self feed, the inspected token from the
-    // PUBLIC visible-item view (decision 0631 — the ref's inspect slot OnEnter calls exactly this,
-    // `InspectPaperDollFrame.xml:20`). An inspected item carries no durability/creator, so those
-    // lines simply don't render — the reference's own inspect tooltip shape. On an ARMED shopping
-    // tooltip this renders the byte law's compare shape; the arm is consumed either way.
-    // hasCooldown is nil INTERIM (no equipped-cooldown feed yet — its truthiness gates the ref's
-    // re-poll only).
-    //
-    // **THREE returns, not two.** The reference's own `PaperDollFrame.lua:741` reads
-    // `local hasItem, hasCooldown, repairCost = GameTooltip:SetInventoryItem("player", this:GetID())`
-    // — Blizzard's file, out of the shipped `patch.MPQ`, and its very next use is
-    // `if ( InRepairMode() and repairCost and (repairCost > 0) ) then ... SetTooltipMoney(...)`.
-    // (l.632 in the same file reads only two, which is a caller not needing the third, not a
-    // different contract.) We pushed two, so pfUI's durability scan died on
-    // `panel.lua:499: attempt to perform arithmetic on local 'repCost' (a nil value)`.
-    //
-    // `repairCost` is **0 INTERIM**, the same posture and the same reason as `SetBagItem`'s below:
-    // the per-item repair feed is the paper-doll arc's and does not exist yet. Zero rather than nil
-    // because the reference **always pushes a number** there — wow-re `tooltip-money.md` §return-2
-    // reads `fild [ebp-0x30]; call 0x6f3810` on `SetBagItem`'s unconditional leg — and an
-    // undamaged item's cost genuinely is 0, so the interim value is a *real* value of the domain
-    // rather than a stand-in. Every reference consumer guards on `> 0`.
-    //
-    // Arity provenance, stated because it differs from the rest of this module: the *three* is the
-    // reference's own consumer, not a byte-read `mov eax, 3`. `SetBagItem`'s two IS byte-verified
-    // (`mov eax,2` @0x534985). A carve of `0x532ee0`'s tail would upgrade this line.
+    // GameTooltip:SetInventoryItem(unit, slot [, nameOnly]) -> hasItem, hasCooldown, repairCost
+    // (`0x532ee0`), three as `PaperDollFrame.lua:741` reads them; the arity is that consumer's,
+    // not byte-read as `SetBagItem`'s two is (`0x534985`). Unit-keyed through `Model::inv_slot`:
+    // an inspected item (`InspectPaperDollFrame.xml:20`) has no durability or creator, so those
+    // lines do not show, as in the reference. An armed shopping tooltip renders the compare
+    // shape; the arm is consumed either way. repairCost is 0, as `SetBagItem`'s is.
     m.set(
         "SetInventoryItem",
         lua.create_function(
             |lua, (this, unit, slot, name_only): (Table, String, usize, Value)| {
                 let h = frame_handle_of(lua, &this)?;
-                // **The third argument the binary names itself**: `0x8552dc` carries
-                // `"Usage: SetInventoryItem(unit, slot [, nameOnly])"`, and `0x533027`–`0x53304c` is
-                // its gate — the flag seeds 0 and becomes 1 only on `lua_isnumber(L,4)` AND
-                // `lua_tonumber(L,4) > 0.0` STRICTLY. A miss does not raise; it leaves the zero and
-                // builds the ordinary tooltip. Three of this binding's four builder legs pass it
-                // through (wow-re `ui/scratch/tooltip-nameonly-p4-census.md` §3).
+                // `nameOnly` (usage string `0x8552dc`) is set only by a number above 0
+                // (`0x533027..0x53304c`); anything else builds the ordinary tooltip, without an
+                // error. Three of the binding's four builder legs pass it on, not `0x533106`.
                 let name_only = super::binding_abi::positive_number_flag(lua, name_only)?;
                 let (item_id, name, quality, inst, currently_equipped) = {
                     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -482,25 +363,19 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                                 s.name.clone(),
                                 s.quality,
                                 render::ItemInstance {
-                                    // The slot's own name — app-composed, so it carries the
-                                    // random-suffix roll off `ITEM_FIELD_RANDOM_PROPERTIES_ID`.
+                                    // App-composed, with the suffix off
+                                    // `ITEM_FIELD_RANDOM_PROPERTIES_ID`.
                                     name: s.name.clone(),
                                     durability: s.durability,
                                     creator: s.creator.clone(),
                                     has_text: false,
                                     flags: s.flags,
                                     already_bound: s.already_bound,
-                                    // No petition line on the doll: a charter has `InventoryType = 0`
-                                    // and cannot be equipped, so this hover can never be over one.
+                                    // A charter has `InventoryType` 0 and is never equipped.
                                     petition: None,
                                     enchants: s.enchants.clone(),
-                                    // `SetInventoryItem 0x532ee0` also has p6=0 legs (`0x533106`,
-                                    // `0x5332ad`) — the "this binding can never emit OPENABLE" claim
-                                    // is dead here too (wow-re `right-click-open.md` §1.2). Which leg
-                                    // each takes is not pinned, and the case is unobservable anyway:
-                                    // nothing openable is equippable, so the doll hover has no clam to
-                                    // show. Left `false` deliberately — inventing a selector we have
-                                    // not read would be the §4 trade, and there is nothing to gain.
+                                    // `0x532ee0` has p6=0 legs too (`0x533106`, `0x5332ad`), but
+                                    // nothing openable is equippable.
                                     openable_source: false,
                                     duration_ms: s.duration_ms,
                                 },
@@ -508,12 +383,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                         });
                     match view {
                         Some((id, name, q, inst)) => (id, name, q, inst, armed),
-                        // An EMPTY slot answers `nil` for hasItem — and still pushes the other two,
-                        // because the reference's own caller destructures all three unconditionally
-                        // and only then tests `hasItem`. Answering one value here would hand
-                        // `PaperDollItemSlotButton_OnEnter` a nil `repairCost` on every empty slot,
-                        // which its `repairCost and (repairCost > 0)` guard survives but pfUI's bare
-                        // `totalRep + repCost` does not.
+                        // An empty slot answers nil and still pushes the other two: callers
+                        // destructure all three first, and an addon may add up repairCost.
                         None => {
                             return Ok(MultiValue::from_vec(vec![
                                 Value::Nil,
@@ -523,7 +394,6 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                         }
                     }
                 };
-                // p5 and p4, carried as one value but never as one flag (2216).
                 let flags = BuilderFlags {
                     currently_equipped,
                     name_only,
@@ -536,10 +406,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 match view_of(lua, item_id) {
                     Some(v) => render_view(lua, &this, &v, flags, Some(&inst))?,
                     None => {
-                        // Template in flight — the slot view's own name holds the plate (the same
-                        // 0138 posture as SetBagItem's miss path).
-                        // The compare header is a key like every other sentence (2045); this
-                        // fallback path shows it for exactly the reason the full render does.
+                        // Template in flight: the header and the slot's own name, as
+                        // `SetBagItem`'s miss path.
                         if flags.currently_equipped {
                             if let Some(t) = crate::strings::global(lua, "CURRENTLY_EQUIPPED") {
                                 append_line(lua, &this, (t, GRAY), None, false)?;
@@ -558,13 +426,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 show_or_hide_empty(lua, h);
                 Ok(MultiValue::from_vec(vec![
                     Value::Integer(1),
-                    // `hasCooldown` — **broader than its name**, and this is the one arm of it we can
-                    // answer. The builder's Lua return is `[ebp-0x38]`, set by FOUR sites, only one of
-                    // which is the cooldown line: LOCKED_WITH_ITEM, the temporary-enchant countdown,
-                    // **the item's own duration line** (`0x52ce0d`), and ITEM_COOLDOWN_TIME. So a
-                    // duration-bearing item answers truthy here with no cooldown of any kind, and an
-                    // addon can see it (decision 1933's fold-back). The equipped-cooldown feed is
-                    // still the INTERIM above; this is the half that now exists.
+                    // hasCooldown is the builder's `[ebp-0x38]`, set by four lines:
+                    // LOCKED_WITH_ITEM, the temporary-enchant countdown, the item's duration
+                    // (`0x52ce0d`) and ITEM_COOLDOWN_TIME. Only the duration is answered here.
                     if inst.duration_ms.is_some() {
                         Value::Boolean(true)
                     } else {
@@ -576,11 +440,11 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetBagItem(bag, slot) → hasCooldown, repairCost — the real-instance hover.
-    // The one money-eligible source built so far: merchant open + repair off ⇒ the engine fires
-    // OnTooltipAddMoney(SellPrice × stack), or prints ITEM_UNSELLABLE at price 0 (wow-re
-    // tooltip-money.md's gate, engine-side at last). repairCost is 0 INTERIM (the per-item
-    // durability/repair feed is the paper-doll arc's).
+    // GameTooltip:SetBagItem(bag, slot) -> hasCooldown, repairCost: the real-instance hover and
+    // the one money source: with the merchant open and repair off (`0x52e376`), the engine fires
+    // `OnTooltipAddMoney(SellPrice × stack)`, or prints ITEM_UNSELLABLE at price 0 (`0x854a74`,
+    // pushed at `0x52e4a3`). repairCost is 0: the per-item repair cost is not fed. The reference
+    // always pushes a number there (`0x534975`), and stock guards on `> 0`.
     m.set(
         "SetBagItem",
         lua.create_function(|lua, (this, bag, slot): (Table, i64, u32)| {
@@ -593,11 +457,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     .and_then(|c| c.slots.get(&slot))
                     .filter(|s| s.item_id != 0)
                 {
-                    // The reference's own leg selector, byte-read: `SetBagItem 0x534620` asks the
-                    // item-cooldown query `0x6e2ed0` and takes the p6=1 (instance-block) leg iff
-                    // **all three** of enable/start/duration are non-zero — a genuinely running
-                    // cooldown. That one boolean is both the Lua `hasCooldown` return and the
-                    // openable gate's inverse, so they are computed once, here (decision 0896).
+                    // `0x534620` takes the p6=1 leg iff the cooldown query `0x6e2ed0` reports
+                    // enable, start and duration all non-zero; that one boolean is both the
+                    // `hasCooldown` return and the inverse of the openable gate.
                     Some(s) => {
                         let has_cd = s
                             .cooldown
@@ -609,24 +471,17 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                             s.link.clone(),
                             s.quality.unwrap_or(1),
                             render::ItemInstance {
-                                // The bag slot's display name rides its LINK (the reference
-                                // builds that link out of `0x5d8b00`'s output, so the two are the
-                                // same string by construction — the roll's suffix included).
+                                // The link's name: the reference builds both from `0x5d8b00`.
                                 name: s.link.as_deref().and_then(link_name).map(str::to_string),
                                 durability: s.durability,
                                 creator: s.creator.clone(),
                                 has_text: s.readable,
                                 flags: s.flags,
                                 already_bound: s.already_bound,
-                                // Line 3 — the charter's guild name and master. Only the BAG hover
-                                // carries it: a charter has `InventoryType = 0` and cannot be worn,
-                                // so the doll site above has no petition to show and does not ask
-                                // its slot view for one.
                                 petition: s.petition.clone(),
                                 enchants: s.enchants.clone(),
-                                // p6 == 0 ⇔ no running cooldown. A clam shows the green line; the
-                                // same clam mid-cooldown would show ITEM_COOLDOWN_TIME instead
-                                // (that line has no feed here yet — a separate, pre-existing gap).
+                                // p6 = 0 iff no cooldown runs; mid-cooldown the reference shows
+                                // ITEM_COOLDOWN_TIME instead, which is not built.
                                 openable_source: !has_cd,
                                 duration_ms: s.duration_ms,
                             },
@@ -656,11 +511,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     }
                 }
                 None => {
-                    // Template in flight. The real client early-outs to an EMPTY tooltip here
-                    // (tooltip-money.md's uncached path); benilla keeps a name-only line instead
-                    // (decision 0138 — the name is already on the slot's link, and a blank plate
-                    // under an on-screen name reads broken). The re-enter loop repaints the
-                    // moment the push lands.
+                    // Deviation: while the template is in flight the reference leaves the tooltip
+                    // empty (`0x52b6a3`); this shows the slot's name, because a blank plate under
+                    // an on-screen name reads as broken. The re-enter loop repaints on arrival.
                     if let Some(name) = link.as_deref().and_then(link_name) {
                         append_line(
                             lua,
@@ -674,32 +527,17 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             }
             show_or_hide_empty(lua, h);
             Ok(MultiValue::from_vec(vec![
-                // Not just the cooldown: the builder's return is set by four line sites, and the
-                // item's own duration line is one of them (see `SetInventoryItem`'s note above,
-                // decision 1933's fold-back).
+                // The builder's `[ebp-0x38]`: a running cooldown or the item's duration line.
                 Value::Boolean(has_cd || inst.duration_ms.is_some()),
                 Value::Integer(0),
             ]))
         })?,
     )?;
 
-    // GameTooltip:SetLootItem(slot) — the loot-row hover (the reference's own binding,
-    // `0x533470`, which its `LootButtonTemplate` <OnEnter> runs behind `LootSlotIsItem`).
-    // **A block source, not a template one** (§1-SESSION's writer table: the leg at `0x533564`
-    // supplies the instance block, p6=1), and that is the whole point of it existing here: a loot
-    // slot is no item object, so its rolled random-suffix enchants reach the builder through the
-    // block — never through `ITEM_FIELD_ENCHANTMENT`, which the wire does not carry for loot.
-    // Hovering a "… of the Monkey" drop through the template path `BenillaSetItemById` instead printed
-    // the `<Random enchantment>` placeholder until the item was in the bag (decision 1547).
-    //
-    // `slot` is the 1-based display row, like every other loot getter; the coin pile and a
-    // cleared row have no tooltip.
-    // GameTooltip:SetTradePlayerItem(id) / SetTradeTargetItem(id) — `0x5341e0` / `0x534410`, two
-    // arguments exact (self, slot), no returns: the trade slot's item, rendered off its template
-    // the way the loot slot is (decision 1966; the stock TradeFrame.xml's slot OnEnter). The
-    // target side reads the partner's slot guids (`[0xb715a0 + slot*4]`, wow-re
-    // `loot-slot-record.md`); an empty or out-of-range slot leaves the tooltip untouched. The
-    // slot's enchant line waits on the trade snapshot carrying the wire's enchant id (0592 P3).
+    // GameTooltip:SetTradePlayerItem(slot) / SetTradeTargetItem(slot) (`0x5341e0`, `0x534410`;
+    // `TradeFrame.xml:150`, `TradeFrame.xml:106`), no returns: the slot's item, the target side
+    // off the partner's slot guids (`[0xb715a0 + slot*4]`). An empty or out-of-range slot leaves
+    // the tooltip untouched. The enchant line is not rendered: the trade view has no enchant id.
     for (name, player_side) in [("SetTradePlayerItem", true), ("SetTradeTargetItem", false)] {
         m.set(
             name,
@@ -746,6 +584,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?;
     }
 
+    // GameTooltip:SetLootItem(slot): the loot-row hover (`0x533470`, `LootFrame.xml:42`, behind
+    // `LootSlotIsItem`). A block source (`0x533564`, p6=1): a loot slot is no item object, so a
+    // rolled suffix's enchants reach the builder through the block, never through
+    // `ITEM_FIELD_ENCHANTMENT`. `slot` is the 1-based row; coin and cleared rows have no tooltip.
     m.set(
         "SetLootItem",
         lua.create_function(|lua, (this, slot): (Table, usize)| {
@@ -767,10 +609,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 clear_content(&mut model, h);
             }
             fire_cleared(lua, h);
-            // The row's own name is the app-composed one — the roll's suffix already joined, so
-            // the plate reads "Chipped Claw of the Bear" like the reference's `0x5d8b00` output.
-            // The lines come from the roll id through the pushed table, which is where the
-            // reference reads them too (its `+0x424` against the DBC store, §E5).
+            // The row's app-composed name has the suffix joined, as `0x5d8b00` does; the lines
+            // come from the roll id, the reference's `+0x424` (`0x52b7bf`).
             let inst = render::ItemInstance {
                 name: row.name.clone(),
                 enchants: roll_enchants(lua, row.random_property_id),
@@ -778,8 +618,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             };
             match view_of(lua, row.item_id) {
                 Some(v) => render_view(lua, &this, &v, BuilderFlags::default(), Some(&inst))?,
-                // Template in flight — the row's name holds the plate (SetBagItem's 0138 posture;
-                // the re-enter loop repaints when the push lands).
+                // Template in flight: the row's name, as `SetBagItem`'s miss path.
                 None => {
                     if let Some(name) = row.name.clone() {
                         append_line(
@@ -797,11 +636,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetLootRollItem(rollId) — the group-loot roll window's hover (the reference's
-    // own `0x5364a0`). The same shape as SetLootItem beside it, byte-verified on the same
-    // dispatch: p6=1 with `+0x424 ← [roll+0x20]` (the roll's randomPropertyId), all 7 enchant
-    // slots zero, and BOTH guid args `&{0,0}` — no item object, so §E5's suffix-row copy is the
-    // only enchant source and the placeholder arm is unreachable.
+    // GameTooltip:SetLootRollItem(rollId): the roll window's hover (`0x5364a0`,
+    // `LootFrame.xml:343`). Like `SetLootItem`: p6=1 with `+0x424` = `[roll+0x20]`, the roll's
+    // randomPropertyId, every enchant slot zero and no item object, so the suffix-row copy
+    // (`0x52b7bf`) is the only enchant source.
     m.set(
         "SetLootRollItem",
         lua.create_function(|lua, (this, roll_id): (Table, u32)| {
@@ -848,35 +686,13 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetMerchantCompareItem(index [, offset]) — `0x536080`, GameTooltip method-table
-    // entry 43 (wow-re `system/ui/scratch/merchant-compare-item-law.md`). The shopping tooltip the
-    // stock vendor row raises beside the main one: "here is what you are wearing that this would
-    // replace".
-    //
-    // **`offset` is not a slot.** It is the 1-based ordinal among CANDIDATE slots, and a slot is a
-    // candidate only when all three of these hold — the reference's own conjunction:
-    //
-    //   1. its bit is set in `0x809200[InventoryType]` (our [`equip_slots_for`]),
-    //   2. the slot is OCCUPIED,
-    //   3. the equipped item's **class** equals the vendor item's class. Class only — subclass is
-    //      never read.
-    //
-    // Empty slots are skipped **without** decrementing, so offset 1 finds the first occupied
-    // matching slot wherever it sits. The consequences are the reference's and they are not
-    // obvious: a shield in the off hand makes offset 2 nil for a one-hand weapon (ARMOR ≠ WEAPON),
-    // and an equipped wand DOES compare against a bow on the shelf (both class 2, both bit 17).
-    // Any type with one candidate slot answers nil for offset 2, which is what makes stock's
-    // second `if` cheap.
-    //
-    // **The return contract decides ghost tooltips versus none**, so it is transcribed exactly:
-    // ONE Lua value on every non-raising path — the NUMBER 1 on success (`lua_pushnumber`, not a
-    // boolean), `nil` on every failure. A bad `this` or a non-number index RAISES; a missing
-    // `offset` does not, and defaults to 1. An explicit `offset` of 0 or less is nil, because the
-    // counter starts below zero and only ever decrements.
-    //
-    // An uncached vendor template answers nil AND fires the query ([`view_of`] does both), so the
-    // first hover of an unseen vendor item shows no shopping tooltip and a later one does. That is
-    // the reference's behaviour, not a race we lost.
+    // GameTooltip:SetMerchantCompareItem(index [, offset]) (`0x536080`, method-table entry 43):
+    // the shopping tooltip beside a vendor row. `offset` counts candidate slots, 1-based: set in
+    // `0x809200[InventoryType]`, occupied, and holding an item of the offered class (never
+    // subclass), so a worn shield makes offset 2 nil for a one-hand weapon and a worn wand compares
+    // against a bow. One value on every non-raising path: the number 1 (`lua_pushnumber`) or nil.
+    // A bad `this` or a non-number index raises; a missing `offset` is 1, one of 0 or less is nil.
+    // An uncached template answers nil and fires the query, as in the reference.
     m.set(
         "SetMerchantCompareItem",
         lua.create_function(
@@ -891,20 +707,18 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                         _ => None,
                     }
                 };
-                // The one argument whose absence is an ERROR, with the client's own usage text.
+                // The one argument whose absence raises, with the reference's usage text.
                 let Some(idx) = as_number(&index) else {
                     return Err(mlua::Error::runtime(
                         "Usage: SetMerchantCompareItem(\"slot\" [, offset])",
                     ));
                 };
-                // The reference re-bases the index in f64 and THEN truncates toward zero, so 2.7
-                // is row 1 (1.7 → 1) rather than row 2. Doing it the other way round differs by
-                // one for every fractional index.
+                // Re-based in f64, then truncated toward zero, as the reference does: 0.5 is row 1.
                 let row = (idx - 1.0).trunc();
                 if row.is_nan() || row < 0.0 || row > f64::from(u32::MAX) {
                     return Ok(Value::Nil);
                 }
-                // `offset` re-bases as an INTEGER, and its absence means 1.
+                // `offset` is truncated before it is re-based; absent, it is 1.
                 let left = match offset.as_ref().and_then(as_number) {
                     Some(n) if n.is_nan() => return Ok(Value::Nil),
                     Some(n) => n.trunc() - 1.0,
@@ -926,8 +740,6 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 }) else {
                     return Ok(Value::Nil);
                 };
-                // The vendor item's own template — the class this compares by, and the miss that
-                // fires the query.
                 let Some(offered) = view_of(lua, item_id) else {
                     return Ok(Value::Nil);
                 };
@@ -937,15 +749,11 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetAuctionCompareItem("type", index [, offset]) — `0x535d70`, the auction row's
-    // twin of the vendor compare: the same body (`0x53603e` and `0x5362d4` both reach the shared
-    // compare with `p4 = 0, p5 = 1`, wow-re `tooltip-content-law.md`; `merchant-compare-item-law.md`
-    // §7 for the wrapper), fed by one of the three auction lists instead of the vendor's shelf.
-    // The type argument is `lua_isstring`-gated (`0x535e28`) and matched against the list names;
-    // a non-string type or non-number index raises the reference's own Usage; a bad list name,
-    // an out-of-range row or an uncached template is nil. Return contract as the merchant's: the
-    // NUMBER 1 on success, nil otherwise — the stock `AuctionFrameItem_OnEnter` gates each
-    // shopping tooltip on it (1971).
+    // GameTooltip:SetAuctionCompareItem("type", index [, offset]) (`0x535d70`): the vendor
+    // compare's body (`0x53603e` and `0x5362d4` both pass p4 = 0, p5 = 1) over an auction list.
+    // `type` is `lua_isstring`-gated (`0x535e28`); a non-string type or non-number index raises
+    // the reference's usage, and a bad list, row or uncached template is nil. The number 1 on
+    // success, which `Blizzard_AuctionUI.lua:1081` gates each shopping tooltip on.
     m.set(
         "SetAuctionCompareItem",
         lua.create_function(
@@ -1008,10 +816,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetMerchantItem(index) / SetBuybackItem(index) — template-id sources through
-    // the same store (the real SetMerchantItem is the template path — tooltip-money.md); the
-    // merchant feed's own stat head is the fallback while the template answer is in flight, so
-    // the vendor hover always shows at least the head it showed pre-0274.
+    // GameTooltip:SetMerchantItem(index) / SetBuybackItem(index): template sources, as the
+    // reference's `SetMerchantItem` (`0x534080`) is.
     for (method, buyback) in [("SetMerchantItem", false), ("SetBuybackItem", true)] {
         m.set(
             method,
@@ -1038,17 +844,13 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 match view_of(lua, row.item_id) {
                     Some(v) => {
                         render_view(lua, &this, &v, BuilderFlags::default(), None)?;
-                        // **The vendor tab arms nothing** — `MerchantFrame.xml:67-80` seats
-                        // `ShoppingTooltip1/2` itself on every hover of it, unconditionally, and
-                        // that is the reference's own live compare. Arming here would put the
-                        // shift drive on the same two plates the stock row already owns, and its
-                        // release edge would then hide a compare the player never asked it to.
-                        // The BUYBACK tab is the other branch of the same button and seats
-                        // nothing, so it arms like any other hover.
+                        // Nothing to arm: the vendor tab's row seats `ShoppingTooltip1/2` itself
+                        // (`MerchantFrame.xml:67-80`), and the buyback tab seats none.
                         if buyback {}
                     }
                     None => {
-                        // Template in flight: the row's own stat head as a minimal view.
+                        // Template in flight: the row's own stat head as a minimal view, the
+                        // same deviation as `SetBagItem`'s miss path.
                         let head = row.stats.unwrap_or_default();
                         let v = ItemTemplateView {
                             name: row.name.clone().unwrap_or_default(),
@@ -1075,9 +877,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?;
     }
 
-    // GameTooltip:SetInboxItem(index) — the mail window's enclosed-item hover (decision 0544): the
-    // inbox row's item entry through the same id-keyed store (MailFrame.lua l.218/470). A row with no
-    // enclosed item (item_id 0) is a no-op, like the reference (which only calls this when hasItem).
+    // GameTooltip:SetInboxItem(index): the mail item hover (`MailFrame.lua:218`,
+    // `MailFrame.lua:470`). A row with no item does nothing; stock calls it only when there is one.
     m.set(
         "SetInboxItem",
         lua.create_function(|lua, (this, index): (Table, usize)| {
@@ -1100,9 +901,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 clear_content(&mut model, h);
             }
             fire_cleared(lua, h);
-            // A block source (`SetInboxItem 0x5355fa`, p6=1) carrying the attachment's roll — so
-            // an "… of the Monkey" in the mail reads like the same drop in the loot window, and
-            // the placeholder arm is unreachable here too (decision 1547).
+            // A block source (`0x5355fa`, p6=1) carrying the attachment's roll: no placeholder.
             let inst = render::ItemInstance {
                 name,
                 enchants: roll_enchants(lua, roll),
@@ -1116,14 +915,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetAuctionItem(type, index) — an auction ROW's hover (decision 1511). The row's
-    // item entry through the same id-keyed store, keyed by list type ("list"/"bidder"/"owner").
-    //
-    // An auction row's tooltip deliberately emits **no** "Made by", "Gift from" or openable lines,
-    // and the reason is structural rather than a rule anyone applies: the reference's binding
-    // zeroes the GUID arguments before it resolves anything, so the gate those lines hang off
-    // fails outright (wow-re §5, claim 6). Our id-keyed store has no instance to report either,
-    // so we land on the same output by the same shape of reasoning.
+    // GameTooltip:SetAuctionItem(type, index): an auction row's hover, `type` "list", "bidder" or
+    // "owner". No creator, gift or open line: the reference zeroes the guid arguments
+    // (`0x535a6d`, `0x535a73`), so the item-object gate those lines hang off fails.
     m.set(
         "SetAuctionItem",
         lua.create_function(|lua, (this, kind, index): (Table, String, usize)| {
@@ -1149,9 +943,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 clear_content(&mut model, h);
             }
             fire_cleared(lua, h);
-            // A block source (`SetAuctionItem 0x5359d9`, p6=1) carrying the listing's roll: a
-            // rolled auction shows its real lines, never the placeholder (decision 1547). The
-            // zeroed GUIDs the note above describes are unaffected — a roll is not an instance.
+            // A block source (`0x5359d9`, p6=1) carrying the listing's roll: no placeholder.
             let inst = render::ItemInstance {
                 name,
                 enchants: roll_enchants(lua, roll),
@@ -1165,14 +957,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetAuctionSellItem() — the create-auction slot's hover (decision 1511). The item
-    // staged in the sell slot, through the same id-keyed store. A no-op when the slot is empty
-    // (the reference gates the call on GetAuctionSellItemInfo()).
-    //
-    // Unlike an auction ROW, this one names a real item the player owns — the reference passes the
-    // live sell-slot GUID here and resolves an actual object, so its creator line is structurally
-    // reachable (wow-re §5, claim 6, REFINED). Ours is still the id-keyed template view, so we do
-    // not print one; that is a known narrowing, not a claim about the reference.
+    // GameTooltip:SetAuctionSellItem(): the sell slot's hover (`Blizzard_AuctionUI.xml:1791`); an
+    // empty slot does nothing. The reference resolves the live sell-slot object (`[0xb72608]`,
+    // `[0xb7260c]`, `0x5357b4`), so its creator line can show; this renders the template alone.
     m.set(
         "SetAuctionSellItem",
         lua.create_function(|lua, this: Table| {
@@ -1201,9 +988,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetSendMailItem() — the mail Send tab's attached-item hover (decision 0544): the
-    // cursor item attached to the send slot, through the same id-keyed store (MailFrame.lua l.952).
-    // A no-op when nothing is attached (the reference gates the call on GetSendMailItem()).
+    // GameTooltip:SetSendMailItem(): the attached item's hover (`MailFrame.xml:952`); an empty
+    // slot does nothing.
     m.set(
         "SetSendMailItem",
         lua.create_function(|lua, this: Table| {
@@ -1232,21 +1018,16 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetTradeSkillItem(skillIndex [, reagentIndex]) — the tradeskill window's item
-    // hover (decision 0437 phase 2): with reagentIndex, that recipe's reagent's item; without, the
-    // recipe's PRODUCT item. Routes through the same id-keyed renderer BenillaSetItemById uses. A product
-    // id of 0 (a pure-effect recipe) or an in-flight ask-once answer both fall to render_by_id's own
-    // name-only fallback line (the recipe's name for the product channel, the reagent's own —
-    // possibly still-nil — name for the reagent channel) rather than a no-op: that fallback already
-    // exists and reads better than a blank hover. An out-of-range skill/reagent index is a no-op.
+    // GameTooltip:SetTradeSkillItem(skillIndex [, reagentIndex]): the reagent's item, or without
+    // `reagentIndex` the recipe's product. A product id of 0 or an uncached template shows the
+    // recipe's or the reagent's name alone (`render_by_id`); a bad index does nothing.
     m.set(
         "SetTradeSkillItem",
         lua.create_function(
             |lua, (this, skill_index, reagent_index): (Table, usize, Option<usize>)| {
                 let found = {
                     let model = lua.app_data_ref::<Model>().expect("model app_data");
-                    // The VISIBLE-row mapping (headers interleave since the TU-B grouping
-                    // landed) — never a raw recipes[] index; a header index resolves to None.
+                    // A visible-row index, headers included (`0x4fca20`); a header is None.
                     let Some(recipe) = super::tradeskill::recipe_at(&model, skill_index) else {
                         return Ok(());
                     };
@@ -1266,13 +1047,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         )?,
     )?;
 
-    // GameTooltip:SetCraftItem(craftIndex, reagentIndex) — the craft window's reagent hover
-    // (decision 0437 phase 3, ref `CraftItemTemplate`'s OnEnter, `Blizzard_CraftUI.xml:33`):
-    // ALWAYS the REAGENT's item — unlike SetTradeSkillItem, Craft has no product-item concept to
-    // fall back to when reagentIndex is omitted (craft.rs's own module doc, "no product-item
-    // concept"), so this signature has no optional arm; the ref itself never calls it with one
-    // argument either. Routes through the same id-keyed renderer. An out-of-range craft/reagent
-    // index is a no-op.
+    // GameTooltip:SetCraftItem(craftIndex, reagentIndex): the reagent's item
+    // (`Blizzard_CraftUI.xml:33`); a craft has no product item, so both arguments are required. A
+    // bad index does nothing.
     m.set(
         "SetCraftItem",
         lua.create_function(
diff --git a/crates/benilla-ui/src/script/tooltip_item/names.rs b/crates/benilla-ui/src/script/tooltip_item/names.rs
index dbc54c17..847cc3d2 100644
--- a/crates/benilla-ui/src/script/tooltip_item/names.rs
+++ b/crates/benilla-ui/src/script/tooltip_item/names.rs
@@ -1,24 +1,10 @@
-//! The item tooltip's display vocabulary — the builder's own **key** tables (`INVTYPE_*`,
-//! `ITEM_MOD_*`, `SPELL_SCHOOL%d_CAP`), the DBC-sourced subclass/class/race names, and the
-//! byte-verified color constants the render law paints with. Pure data; the law itself is
-//! [`super::render`], which resolves every key here against the player's own `GlobalStrings.lua`
-//! (decision 2045).
-//!
-//! **Keys, not sentences, and the difference is not cosmetic.** `INVTYPE_SHIELD` and
-//! `INVTYPE_WEAPONOFFHAND` both read "Off Hand" in enUS and are separately localizable
-//! everywhere else; a table that stored the English could not tell them apart, and this one had
-//! them collapsed into a single arm until 2045's sweep.
-//!
-//! **What stays a Rust literal here, and why it is not the same thing**: [`CLASS_NAMES`] and
-//! [`RACE_NAMES`] name rows the reference reads out of DBC records (ChrClasses, ChrRaces), never
-//! out of `GlobalStrings.lua`. Those belong to the DBC-feed question, not to this one — and the
-//! subclass names that used to sit beside them have gone the whole way there: the type cell and
-//! the bag line both read `ItemSubClass.dbc`'s own DisplayName off the app-resolved view now,
-//! rather than a hand-typed copy of it.
+//! The item tooltip's vocabulary: the builder's key tables (`INVTYPE_*`, `ITEM_MOD_*`,
+//! `SPELL_SCHOOL%d_CAP`), which [`super::render`] resolves against the player's own
+//! `GlobalStrings.lua`, and its colours. Keys, not English: `INVTYPE_SHIELD` and
+//! `INVTYPE_WEAPONOFFHAND` both read "Off Hand" in enUS and differ elsewhere. [`CLASS_NAMES`] and
+//! [`RACE_NAMES`] are English literals; the reference reads `ChrClasses.dbc` and `ChrRaces.dbc`.
 
-/// The client's 7-entry quality→color table (wow-re RF-0055, VERIFIED at `0xc0d3c8` behind
-/// `GetItemQualityColor 0x48dfb0`): Poor gray, Common white, Uncommon green, Rare blue, Epic
-/// purple, Legendary orange, Artifact gold.
+/// The reference's quality colour table, `0xc0d3c8`, read by `GetItemQualityColor` (`0x48dfb0`).
 pub(super) const QUALITY_RGB: [[f32; 3]; 7] = [
     [0.616, 0.616, 0.616], // 0 Poor      9d9d9d
     [1.0, 1.0, 1.0],       // 1 Common    ffffff
@@ -29,42 +15,23 @@ pub(super) const QUALITY_RGB: [[f32; 3]; 7] = [
     [0.902, 0.8, 0.502],   // 6 Artifact  e6cc80
 ];
 
-// The tooltip color constants — BYTE-VERIFIED (wow-re `ui/scratch/tooltip-content-law.md` §1's
-// pointer table): white `0xc0cf60=ffffffff`, red `0xc0d390=ffff2020` (255,32,32), green
-// `0xc0d3ac=ff00ff00`, gold `0xc0d3e8=ffffd200` (255,210,0), gray `0xc0d3c4=ff808080`.
+// The tooltip colours: white `0xc0cf60` ffffffff, red `0xc0d390` ffff2020, green `0xc0d3ac`
+// ff00ff00, gold `0xc0d3e8` ffffd200, gray `0xc0d3c4` ff808080.
 pub(super) const WHITE: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
 pub(super) const GREEN: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
 pub(super) const RED: [f32; 4] = [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0];
-/// The tooltip's OTHER red — `0xc0d398 = ffff0000`, a pure red distinct from the (255,32,32) the
-/// requirement lines wear. Two lines use it, both in the enchant family: a **negative** enchant id
-/// in slot 0/1, and ITEM_ENCHANT_DISCLAIMER (wow-re §1-ENCHANT §E3/§E4).
+/// The pure red `0xc0d398` (ffff0000), used by two enchant lines (`0x52ca29`, `0x52cc13`): a
+/// negative enchant id in slot 0 or 1, and ITEM_ENCHANT_DISCLAIMER.
 pub(super) const ENCHANT_RED: [f32; 4] = [1.0, 0.0, 0.0, 1.0];
 pub(super) const GOLD: [f32; 4] = [1.0, 210.0 / 255.0, 0.0, 1.0];
 pub(super) const GRAY: [f32; 4] = [128.0 / 255.0, 128.0 / 255.0, 128.0 / 255.0, 1.0];
-/// The owned set member's pale cream — byte-read `0xc0d368 = ffffff97` (writer `0x529050`).
+/// An equipped set member's cream, `0xc0d368` (ffffff97, written at `0x529050`).
 pub(super) const CREAM: [f32; 4] = [1.0, 1.0, 151.0 / 255.0, 1.0];
 
-/// InventoryType → the slot line's GlobalString **key** — the builder's own 30-entry pointer
-/// table at `0x83ddb0`, indexed by `[record+0x2c]` directly (`0x52c103: mov ecx,[ecx*4+0x83ddb0]`,
-/// the read the law's §10 names), dumped entry by entry rather than matched by English.
-///
-/// **Index 0 and index 29 are the pre-seeded empty string `0x882748`** — a non-equip item and an
-/// out-of-range type name nothing, which is the `None` here. 18 (bag) and 27 (quiver) *do* have
-/// entries (`INVTYPE_BAG`/`INVTYPE_QUIVER`) but are unreachable: both are containers, and a
-/// container takes the CONTAINER_SLOTS line above this call instead.
-///
-/// **Four of these keys ship no value, and that is the reference's behaviour, not a gap.**
-/// `INVTYPE_AMMO` (24), `INVTYPE_THROWN` (25), `INVTYPE_RANGEDRIGHT` (26) and `INVTYPE_QUIVER`
-/// (27) are in the exe's table but absent from `GlobalStrings.lua`, so `FrameScript_GetText`
-/// hands the builder an empty left cell. We had written "Projectile", "Thrown" and "Ranged" into
-/// those arms — the invention class decision 2045 says a text-matching tripwire cannot catch.
-///
-/// **But an arrow's cell is not empty, and this table is not why.** A class-6 item never reaches
-/// here at all: the builder forks to `ItemClass.dbc`'s own name for it one instruction earlier
-/// (`0x52c0bc`), so ammunition reads "Projectile | Arrow" — the word 2080 deleted, restored by
-/// the mechanism that actually produces it rather than by the key that does not. `INVTYPE_RANGED`
-/// (15) likewise **does** ship, so a bow reads "Ranged | Bow"; it is 25 and 26 — thrown weapons
-/// and guns/crossbows/wands, all ItemClass 2 — that genuinely draw the type word alone.
+/// InventoryType to the slot line's key: the builder's 30-entry table `0x83ddb0`, indexed by
+/// `[record+0x2c]` (`0x52c103`); entries 0 and 29 are the empty string `0x882748`, here `None`. A
+/// bag (18) takes CONTAINER_SLOTS instead, and class 6 its class name (`0x52c0bc`); 24-27 ship no
+/// `GlobalStrings.lua` value, so a thrown weapon (25) or a gun (26) has an empty slot cell.
 pub(super) fn invtype_key(t: u32) -> Option<&'static str> {
     Some(match t {
         1 => "INVTYPE_HEAD",
@@ -97,40 +64,30 @@ pub(super) fn invtype_key(t: u32) -> Option<&'static str> {
     })
 }
 
-/// The damage block's bias constant — `[0x808120]`, byte-exact `0.9999899864196777`
-/// (`0x3f7fff58`). Neither `0.5` nor `1.0`: the epsilon is what stops an exactly-integral max
-/// from being bumped by one, and a true `ceil()` differs from this expression for any value
-/// within ~1e-5 above an integer.
+/// The damage bias `[0x808120]`, 0.9999899864196777: an integral max is not bumped, and unlike a
+/// true `ceil()` a value within ~1e-5 above an integer is not rounded up.
 const DAMAGE_BIAS: f32 = f32::from_bits(0x3f7f_ff58);
 
-/// `floor(DamageMin)` as the builder computes it — `fsub [0x808120]` iff the value is **not**
-/// greater than 0, then `__ftol`'s truncate-toward-zero (`0x52c253`–`0x52c276`).
+/// The builder's `floor(DamageMin)`: subtract the bias unless positive, then truncate toward zero
+/// (`0x52c253..0x52c276`).
 pub(super) fn floor_min(m: f32) -> i32 {
     (if m > 0.0 { m } else { m - DAMAGE_BIAS }) as i32
 }
 
-/// `ceil(DamageMax)` — the mirror: `fadd [0x808120]` iff the value **is** greater than 0, then
-/// the same truncating conversion (`0x52c26e`–`0x52c28c`).
+/// The builder's `ceil(DamageMax)`: add the bias if positive, then truncate (`0x52c26e..0x52c28c`).
 pub(super) fn ceil_max(m: f32) -> i32 {
     (if m > 0.0 { m + DAMAGE_BIAS } else { m }) as i32
 }
 
-/// A damage/resistance school's name key — `SPELL_SCHOOL%d_CAP`, the one string the builder
-/// composes at runtime rather than naming outright (`0x84e4cc`, pushed at `0x52c2a8` for the
-/// damage line and `0x52c8d1` for the resistance line; law §11/§16).
-///
-/// The index is the school itself: `SPELL_SCHOOL0_CAP` is "Physical" and 1..6 are
-/// Holy/Fire/Nature/Frost/Shadow/Arcane. **School 0 answers `None`** because the reference
-/// doesn't name it either — a physical weapon takes the school-less `DAMAGE_TEMPLATE` arm rather
-/// than printing the word.
+/// A school's name key, `SPELL_SCHOOL%d_CAP`, the one key the builder composes (`0x84e4cc`,
+/// pushed at `0x52c2a8` and `0x52c8d1`). School 0 has none: a physical weapon takes the
+/// school-less `DAMAGE_TEMPLATE` arm.
 pub(super) fn school_key(s: u32) -> Option<String> {
     (1..=6).contains(&s).then(|| format!("SPELL_SCHOOL{s}_CAP"))
 }
 
-/// Stat-mod type → its `ITEM_MOD_*` key. Not a *name*: the key resolves to the whole line
-/// template, sign hole and all (`ITEM_MOD_AGILITY = "%c%d Agility"`), which is why 2 has no arm —
-/// the builder's 8-way jump table `0x52e510` skips it (law §15, keys byte-read at
-/// `0x52c6eb..0x52c777`).
+/// Stat type to its `ITEM_MOD_*` line template (`"%c%d Agility"`); the builder's 8-way jump table
+/// `0x52e510` skips 2 (keys at `0x52c6eb..0x52c777`).
 pub(super) fn stat_key(t: u32) -> Option<&'static str> {
     Some(match t {
         0 => "ITEM_MOD_MANA",
@@ -144,7 +101,7 @@ pub(super) fn stat_key(t: u32) -> Option<&'static str> {
     })
 }
 
-/// Class id → display name (vanilla playable ids; the `ITEM_CLASSES_ALLOWED` list).
+/// The playable class ids and names the `ITEM_CLASSES_ALLOWED` list prints.
 pub(super) const CLASS_NAMES: [(u32, &str); 9] = [
     (1, "Warrior"),
     (2, "Paladin"),
@@ -157,7 +114,7 @@ pub(super) const CLASS_NAMES: [(u32, &str); 9] = [
     (11, "Druid"),
 ];
 
-/// Race id → display name (vanilla playable ids; the `ITEM_RACES_ALLOWED` list).
+/// The playable race ids and names the `ITEM_RACES_ALLOWED` list prints.
 pub(super) const RACE_NAMES: [(u32, &str); 8] = [
     (1, "Human"),
     (2, "Orc"),
@@ -169,7 +126,7 @@ pub(super) const RACE_NAMES: [(u32, &str); 8] = [
     (8, "Troll"),
 ];
 
-/// A playable-ids mask covering every listed id — a mask covering all of them shows no line.
+/// The mask of every listed id; an item allowing all of them shows no line.
 pub(super) fn full_mask(ids: &[(u32, &str)]) -> i32 {
     ids.iter().fold(0i32, |m, &(id, _)| m | (1 << (id - 1)))
 }
diff --git a/crates/benilla-ui/src/script/tooltip_item/render.rs b/crates/benilla-ui/src/script/tooltip_item/render.rs
index d22b6e86..3802541f 100644
--- a/crates/benilla-ui/src/script/tooltip_item/render.rs
+++ b/crates/benilla-ui/src/script/tooltip_item/render.rs
@@ -1,18 +1,9 @@
-//! The item tooltip's line law — [`render_view`], the byte-verified emission order of the
-//! client's shared renderer `0x52b650` (see the parent module doc for the law's provenance and
-//! the compare/red/SET summaries).
-//!
-//! **Every sentence here is a key, never a Rust string** (decision 2045). The builder names its
-//! keys outright — the census of the string pointers reachable from `[0x52b650, 0x52e600)` is
-//! where each one below came from, so a line's key is the *reference's* choice and not a match on
-//! English. That distinction is load-bearing: `ITEM_REQ_SKILL`, `LOCKED_WITH_ITEM`,
-//! `LOCKED_WITH_SPELL` and `LOCKED_WITH_SPELL_KNOWN` are all "Requires %s" in enUS and four
-//! different strings anywhere else.
-//!
-//! A key the player's `GlobalStrings.lua` does not carry emits **no line at all** — never an
-//! invented one. That is `duration_text`'s disposition and the reference's own: its
-//! `FrameScript_GetText` hands back the pre-seeded empty string and `AddLine` drops an empty row
-//! before it ever counts it.
+//! The item tooltip's line law, [`render_view`]: the emission order of the reference's builder
+//! `0x52b650`. Every sentence is a key the builder itself names (the string pointers reachable
+//! from `[0x52b650, 0x52e600)`), never a match on English: `ITEM_REQ_SKILL` and the three
+//! `LOCKED_WITH_*` keys all read "Requires %s" in enUS and differ elsewhere. A key the player's
+//! `GlobalStrings.lua` lacks emits no line, as in the reference, whose `FrameScript_GetText`
+//! returns the empty string and whose `AddLine` drops an empty row uncounted.
 
 use mlua::{Lua, Table};
 
@@ -22,149 +13,80 @@ use crate::strings::{fill, Arg};
 
 use super::names::*;
 
-/// The REAL instance's contribution to the line law — the fields only a streamed item OBJECT
-/// carries. A template/link hover passes `None` at the call site: the ref gates the whole
-/// creator + openable/readable tail on the item-object pointer (`0x52e1c7`/`0x52e2e0` — no
-/// object, no lines), and keeps the authored full max/max durability.
+/// What a source knows beyond the template: an item object's fields, or a block source's name and
+/// roll. A template source passes `None`.
 #[derive(Default)]
 pub(super) struct ItemInstance {
-    /// The source's own display NAME, when it knows one the template cannot compose — today that
-    /// is exactly the **random-suffix roll**: "Chipped Claw" + `ItemRandomProperties[id].suffix`
-    /// = "Chipped Claw of the Bear". The reference composes it inside the builder (`0x52b7bf`
-    /// keeps the suffix row for the name, and `0x5d8b00` joins it through `ITEM_SUFFIX_TEMPLATE`);
-    /// here the app owns every DBC join, so it arrives already joined — the same division the
-    /// enchant lines below already use. `None` = the template's own name (`ItemTemplateView::name`).
+    /// The name with its random suffix joined, which the reference composes in the builder
+    /// (`0x52b7bf`, `0x5d8b00` through `ITEM_SUFFIX_TEMPLATE`); `None` takes the template's.
     pub name: Option<String>,
-    /// Live `(current, max)` durability (director-reported: the spirit healer's 25% loss
-    /// showed nowhere); `None` = indestructible (max 0) or the create not yet landed.
+    /// Live `(current, max)`; `None` for an indestructible item or one not yet streamed.
     pub durability: Option<(u32, u32)>,
-    /// The RESOLVED `ITEM_FIELD_CREATOR` name (the app's ask-once name cache — the ref's
-    /// `0x55f080` probe). `None` = authorless OR the name query is still in flight: the ref
-    /// emits no line either way (`0x52e209`; its resolve callback repaints the tooltip, ours
-    /// is the container re-enter loop).
+    /// The resolved `ITEM_FIELD_CREATOR` name (the reference's `0x55f080`); `None` while it is
+    /// unresolved, which prints no line either (`0x52e209`).
     pub creator: Option<String>,
-    /// Instance `ITEM_FIELD_ITEM_TEXT_ID` ≠ 0 (a mail permanent copy): flips the creator line
-    /// to WRITTEN_BY (`0x52e223`) and satisfies the READABLE gate (`0x52e348`).
+    /// `ITEM_FIELD_ITEM_TEXT_ID` ≠ 0, a letter's copy: the creator line reads WRITTEN_BY
+    /// (`0x52e223`) and READABLE shows (`0x52e348`).
     pub has_text: bool,
-    /// Instance `ITEM_FIELD_FLAGS` — the openable lock sub-gate reads UNLOCKED `0x4`
-    /// (`0x52e30c`) and the wrapped-gift arm WRAPPED `0x8` (`0x52e31d`).
+    /// `ITEM_FIELD_FLAGS`: UNLOCKED `0x4` (read at `0x52e30c`), WRAPPED `0x8` (`0x52e31d`).
     pub flags: u32,
-    /// `0x5da2c0` — **this instance is runtime-bound**: `ITEM_FIELD_FLAGS & 1`, or a live
-    /// enchant slot naming a `SpellItemEnchantment` row that binds. The binding half needs a DBC
-    /// join, so the whole predicate arrives app-resolved
-    /// ([`crate::script::ContainerSlot::already_bound`]) rather than being re-derived here off
-    /// [`Self::enchants`] — that list is a *display* view and drops rows the line law hides.
-    /// Drives §6's Soulbound override; `false` on every template/link source.
+    /// Runtime-bound (`0x5da2c0`): `ITEM_FIELD_FLAGS & 1`, or an enchant that binds. App-resolved,
+    /// since [`Self::enchants`] drops rows the line law hides.
     pub already_bound: bool,
-    /// The petition this charter names — **line 3**, between the NAME and `ITEM_SIGNABLE`. See
-    /// [`crate::script::PetitionSlotView`], which carries the reason its third line is unbuilt.
+    /// The petition a charter names, printed between the name and `ITEM_SIGNABLE`.
     pub petition: Option<crate::script::PetitionSlotView>,
-    /// The instance's enchant slots, app-resolved and in slot order (law line 17 / §1-ENCHANT,
-    /// decisions 0915/0920) — see [`crate::script::EnchantView`]. Empty on an unenchanted item and
-    /// on every template/link source (no instance, nothing enchanted).
+    /// The enchant slots, app-resolved, in slot order (`0x52c991`).
     pub enchants: Vec<crate::script::EnchantView>,
-    /// May this source emit the ITEM_OPENABLE line? = the reference's `p6 == 0` — "this tooltip
-    /// carries **no** caller-supplied instance block" (`[this+0x440]`, tested at `0x52e2e8`: when
-    /// it is set, the builder evaluates only READABLE and skips the openable tree entirely).
-    ///
-    /// **This is not a per-binding constant.** wow-re's earlier §1-OPENABLE said `SetBagItem`
-    /// passes `p6=1` and so could *never* show the line — which is why our bag hover had no green
-    /// line at all, and which the director's screenshot of a clam falsified. The re-derivation
-    /// (wow-re `right-click-open.md` §1, §5 pair 2026-08-02) found the cause: the old p6 table was
-    /// enumerated per *binding* from the instance-block **writers**, so it only ever saw the p6=1
-    /// leg. A per-**call-site** census of all 31 `0x52b650` sites finds five callers with two or
-    /// more legs, and `SetBagItem 0x534620` is one: `0x534900` p6=1 and `0x53493e` p6=0.
-    ///
-    /// What selects the leg is the item-cooldown query `0x6e2ed0` at `0x53483a` — p6=1 iff
-    /// **enable, start and duration are all non-zero**, i.e. iff the item has a *running
-    /// cooldown*. That same block writes `this+0x408 = start + duration − now`, whose sole
-    /// consumer is the ITEM_COOLDOWN_TIME line and the builder's `hasCooldown` return. So on the
-    /// bag binding the two lines are structurally exclusive: **an item on cooldown shows
-    /// "Cooldown remaining", the same item off cooldown shows `<Right Click to Open>`.**
-    /// Decision 0896.
+    /// The reference's p6 = 0, no caller-supplied instance block (`[this+0x440]`, tested at
+    /// `0x52e2e8`; when set, only READABLE is evaluated). It is per call site, not per binding:
+    /// `SetBagItem` (`0x534620`) takes p6=1 (`0x534900`) iff the cooldown query `0x6e2ed0` at
+    /// `0x53483a` finds one running, else p6=0 (`0x53493e`), so the open line and the cooldown
+    /// line never show together there.
     pub openable_source: bool,
-    /// **The instance's remaining LIFETIME in milliseconds** — a duration-limited item (a
-    /// conjured stone, a holiday gift, a timed quest item) counting down to its own destruction.
-    /// `None` = no timer, which is every ordinary item and every template/link source.
-    ///
-    /// App-resolved from the client-local deadline `SMSG_ITEM_TIME_UPDATE` parks
-    /// ([`crate::script::ContainerSlot::duration_ms`]), not from the instance's
-    /// `ITEM_FIELD_DURATION` field: vmangos's own writer says the field is not what the client
-    /// displays from — *"Though the client has the information in the item's data field, we have
-    /// to send SMSG_ITEM_TIME_UPDATE to display the remaining time"* (`Item::SendTimeUpdate`,
-    /// `Objects/Item.cpp:1094`) — which is the same split the temporary-enchant countdown one
-    /// field up already takes (decisions 0920/1933).
+    /// A timed item's remaining lifetime in ms, from `SMSG_ITEM_TIME_UPDATE`, not
+    /// `ITEM_FIELD_DURATION`: the client displays from the packet (`Objects/Item.cpp:1093`).
     pub duration_ms: Option<u64>,
 }
 
-/// The SET block's blank gold spacer — the reference's own literal `0x854b2c`, and it is **not**
-/// the empty string. It is a SPACE followed by a newline, and the difference is a whole row.
-///
-/// Both halves are byte-verified (wow-re, `tooltip-content-law.md` §22 + this arc's re-derivation):
-/// `AddLine`'s core `0x530270` takes an empty left text with no right text and **bails before it
-/// ever increments the line count** (`5302a9: test ebx,ebx; 5302ab: je 0x530378`, the shared exit,
-/// which never reaches the `inc [esi+0x31c]` at `0x530372`) — an empty string here is silently
-/// dropped, not even a zero-height slot. So the reference cannot spell this line `""`, and it
-/// doesn't: `" \n"` is one real line carrying one space. It measures as ONE row, not two, because
-/// the width-based stepper `0x5c7470` consumes the trailing break inside the same call that
-/// scanned the space (`5c7659: add esi,ecx`) and the kernel's next top-of-loop read hits the NUL.
-///
-/// benilla lands on the same row count from the same law: the app's `fontstring_lines`
-/// trailing-break rule (decision 1343) drops the empty segment a plain split would leave, so
-/// `" \n"` is one line here too. We wrote `String::new()`, which our own engine calls zero lines
-/// of zero height — so the set block's two spacers were invisible where the reference shows two
-/// blank rows.
+/// The set block's blank gold line, the reference's literal `0x854b2c`: a space and a newline. An
+/// empty string would be no row, as `AddLine` (`0x530270`) drops an empty left text uncounted
+/// (`0x5302a9`). `" \n"` is one row: the stepper `0x5c7470` consumes the break with the space
+/// (`0x5c7659`), as the app's `fontstring_lines` trailing-break rule does.
 const SET_SPACER: &str = " \n";
 
-/// The builder's two independent render flags, p4 and p5 of `0x52b650` — a struct rather than two
-/// adjacent `bool`s because collapsing them into one was decision 2216's bug, and two positional
-/// bools at a call site is the same mistake with an extra step.
+/// The builder's two independent render flags, p4 and p5 of `0x52b650`.
 #[derive(Clone, Copy, Default)]
 pub(super) struct BuilderFlags {
-    /// **p5 `[arg+0x18]`** — prepend the gray `CURRENTLY_EQUIPPED` line. Set by the two shopping
-    /// plates (`SetMerchantCompareItem`, `SetAuctionCompareItem`) and by nothing else in the
-    /// image; those two sites pass [`name_only`](Self::name_only) ZERO.
+    /// p5 `[arg+0x18]`: prepend the gray `CURRENTLY_EQUIPPED` line. Only the two compare bindings
+    /// set it, and both pass [`name_only`](Self::name_only) zero.
     pub currently_equipped: bool,
-    /// **p4 `[arg+0x14]`** — the compact mode the binary itself calls `nameOnly`
-    /// (`0x8552dc`: `"Usage: SetInventoryItem(unit, slot [, nameOnly])"`). Reachable from exactly
-    /// one binding — `SetInventoryItem`'s optional third argument, a number `> 0` — and from no
-    /// stock FrameXML caller at all, but it is live code an addon can ask for (wow-re
-    /// `ui/scratch/tooltip-nameonly-p4-census.md`, §5 trio + orchestrator, 2026-09-13; benilla
-    /// decision 2224).
-    ///
-    /// It is *trimmed*, not bare, and the trim is two non-contiguous jumps plus an early return:
-    /// the name goes white, the bind/lock region and the whole stat body are cut, and everything
-    /// after the cooldown line is skipped. What survives is the name, the slot/type cell,
-    /// durability, duration, every requirement line, the spell triggers and the set block.
+    /// p4 `[arg+0x14]`, the compact mode the reference calls `nameOnly` (`0x8552dc`), reachable
+    /// only through `SetInventoryItem`'s third argument. The name goes white, the bind/lock region
+    /// and the stat body are cut, and all after the cooldown line is skipped; the slot/type cell,
+    /// durability, duration, requirements, spell triggers and set block still print.
     pub name_only: bool,
 }
 
-/// Render one item template into the tooltip — the BYTE-VERIFIED emission law of the shared
-/// renderer `0x52b650` (wow-re `ui/scratch/tooltip-content-law.md`, §5-cross-checked 2026-07-10;
-/// the proficiency-cell and SET legs byte-read directly 2026-07-11; the creator/readable
-/// instance tail byte-read 2026-07-20; the enchant lines of line 17 fed 2026-08-03, decision
-/// 0915), minus the instance-only families still unfed (soulbound override, cooldown-remaining,
-/// the gift-wrap family).
+/// Render one item into the tooltip in `0x52b650`'s order. Not built: ITEM_COOLDOWN_TIME,
+/// ITEM_WRAPPED_BY and the `LOCKED_WITH_*` line under LOCKED.
 pub(super) fn render_view(
     lua: &Lua,
     this: &Table,
     v: &ItemTemplateView,
     flags: BuilderFlags,
-    // `None` = a template/link source (the ref's no-object path).
+    // `None`: a template source, with no item object and no instance block.
     inst: Option<&ItemInstance>,
 ) -> mlua::Result<()> {
     let (req, known_spell, taught_known, set_view, equipped) = {
         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
         let knows = |id: u32| model.spellbook.slots.iter().any(|s| s.spell_id == id);
         let known = v.required_spell != 0 && knows(v.required_spell);
-        // A taught spell (trigger 6, SPELL_EFFECT_LEARN) the player already knows — the
-        // unconditional-red ITEM_SPELL_KNOWN "Already known" line (recipes).
+        // A taught spell (trigger 6, learn) the player knows: the always-red ITEM_SPELL_KNOWN.
         let taught = v
             .spell_triggers
             .iter()
             .any(|&(t, id, _)| t == 6 && id != 0 && knows(id));
-        // The SET block's inputs: the app-resolved set view (a miss records the ask-once) and
-        // the player's equipped item ids — the (owned/total) count + per-member highlight.
+        // The set view (a miss records the ask) and the equipped ids the set block counts.
         let set_view = (v.item_set != 0)
             .then(|| {
                 let view = model.item_sets.get(&v.item_set).cloned();
@@ -186,12 +108,7 @@ pub(super) fn render_view(
     let addw = |l: (String, [f32; 4])| append_line(lua, this, l, None, true);
     let add2 =
         |l: (String, [f32; 4]), r: (String, [f32; 4])| append_line(lua, this, l, Some(r), false);
-    // The VM's own `GlobalStrings.lua`, off the player's patch chain — the one source of every
-    // sentence below.
     let get = |key: &str| crate::strings::global(lua, key);
-    // One line, named by KEY and filled from the template the install carries. A key the table
-    // does not hold emits nothing: the reference's empty `FrameScript_GetText` return reaches
-    // `AddLine`'s `0x530270`, which bails before it increments the line count.
     let keyed = |key: &str, args: &[Arg<'_>], color: [f32; 4], wrap: bool| -> mlua::Result<()> {
         match get(key) {
             Some(t) => append_line(lua, this, (fill(&t, args), color), None, wrap),
@@ -199,40 +116,25 @@ pub(super) fn render_view(
         }
     };
 
-    // The gray CURRENTLY_EQUIPPED header (`[arg+0x18]≠0`, color ptr `0xc0d3c4`) — and it is the
-    // ONLY thing a shopping-tooltip fill adds. **Against a plain `SetInventoryItem` of the same
-    // equipped item, one extra line, first, is the whole difference**: the two callers that set
-    // the header (`SetMerchantCompareItem`'s arg vector at `0x5362d4`, `SetAuctionCompareItem`'s
-    // at `0x53603e`) pass **p4 = 0**, so compact/compare mode is OFF — the NAME keeps its quality
-    // color, the stat body is not jumped, and nothing is cut at `0x52e14c`. wow-re
-    // `merchant-compare-item-law.md` §6 says it in as many words ("a downstream client that
-    // renders a 'compare mode' abbreviated tooltip here is wrong"), and `tooltip-content-law.md`
-    // §1's per-call-site census over all 31 sites of `0x52b650` is what settles it: those two are
-    // the only sites in the image passing a literal non-zero p5, and both pass p4 zero.
+    // The gray header (`[arg+0x18]`, colour `0xc0d3c4`) is all a compare adds: the only two of
+    // `0x52b650`'s 31 call sites passing p5 (`0x5362d4`, `0x53603e`) pass p4 = 0, so none is cut.
     if flags.currently_equipped {
         keyed("CURRENTLY_EQUIPPED", &[], GRAY, false)?;
     }
     let name = inst
         .and_then(|i| i.name.clone())
         .unwrap_or_else(|| v.name.clone());
-    // The NAME's one recolor: `nameOnly` paints it white (`0x52b8b3`, the `je 0x52b8ca` target
-    // being the quality arm `lea ecx,[eax*4+0xc0d3c8]`). Nothing else ever recolors it — an
-    // unusable item's name stays quality-colored.
+    // `nameOnly` paints the name white (`0x52b8b3`), else the quality arm colours it (`0x52b8ca`);
+    // nothing else recolors it, not even for an unusable item.
     let name_color = if flags.name_only {
         WHITE
     } else {
         quality_color(v.quality)
     };
     add((name, name_color))?;
-    // Line 3 — the petition block, ABOVE the green line and below the name: "Guild Name: X" then
-    // "Guild Master: Y" for a charter, "Petition: X" / "Created by Y" for a plain petition. The
-    // keys are picked by the record's own charter bit, the same bit `GetPetitionInfo`'s first
-    // return reads.
-    //
-    // Each line is withheld while its source is unresolved rather than printed with a hole: an
-    // uncached owner name shows the title alone, and the repaint fills it in — the creator line's
-    // rule, and the reference's own (its resolve callback repaints the tooltip; ours is the
-    // container re-enter loop).
+    // The petition lines, below the name: a charter's `GUILD_CHARTER_*` pair or a petition's
+    // `PETITION_*`, by the record's charter bit (`GetPetitionInfo`'s first return). A line whose
+    // source is unresolved waits for the repaint, as the creator line does.
     if let Some(p) = inst.and_then(|i| i.petition.as_ref()) {
         let (title_key, creator_key) = if p.is_charter {
             ("GUILD_CHARTER_TITLE", "GUILD_CHARTER_CREATOR")
@@ -246,27 +148,19 @@ pub(super) fn render_view(
             keyed(creator_key, &[Arg::S(owner)], WHITE, false)?;
         }
     }
-    // ITEM_SIGNABLE (green) — Flags bit 0x2000 (petitions).
+    // ITEM_SIGNABLE: template flag `0x2000`, a petition.
     if v.flags & 0x2000 != 0 {
         keyed("ITEM_SIGNABLE", &[], GREEN, false)?;
     }
-    // **p4's FIRST cut** (`0x52babe`; `0x52bac3 jne 0x52bfad` skips `[0x52bac9, 0x52bfad)`) — the
-    // whole bind/lock region. `ITEM_SIGNABLE` just above is NOT in the jumped range and survives.
+    // p4's first cut (`0x52babe`, skipping `[0x52bac9, 0x52bfad)` at `0x52bac3`): the bind/lock
+    // region. ITEM_SIGNABLE above survives it.
     if !flags.name_only {
-        // ITEM_CONJURED (Flags bit 0x2).
         if v.flags & 0x2 != 0 {
             keyed("ITEM_CONJURED", &[], WHITE, false)?;
         }
-        // The bind line (§6, white, one line). Bonding `[record+0x194]` ∈ {1..5} is what decides
-        // whether a line prints at ALL — a Bonding-0 item says nothing here however it is held.
-        // Within that, a **runtime-bound instance** (`0x5da2c0` — [`ItemInstance::already_bound`])
-        // overrides the whole line to ITEM_SOULBOUND, and to ITEM_BIND_QUEST for the two quest
-        // kinds, which is the same text 4|5 print anyway; only then does the jump table `0x52e4fc`
-        // pick 1→picked up · 2→equipped · 3→used · 4/5→Quest Item.
-        //
-        // Before this arm an equipped Binds-when-equipped piece kept saying *Binds when equipped*
-        // forever (B310, Frostshake): the template's `bonding` never changes when the item binds —
-        // the instance's flag is the only thing that does.
+        // Bonding (`[record+0x194]`) 1..5 decides whether a bind line prints. A runtime-bound
+        // instance (`0x5da2c0`) prints ITEM_SOULBOUND, or ITEM_BIND_QUEST for the quest kinds;
+        // otherwise the jump table `0x52e4fc` picks 1 pickup, 2 equip, 3 use, 4 and 5 quest.
         match v.bonding {
             4 | 5 => keyed("ITEM_BIND_QUEST", &[], WHITE, false)?,
             1..=3 if inst.is_some_and(|i| i.already_bound) => {
@@ -285,37 +179,22 @@ pub(super) fn render_view(
         if v.start_quest != 0 {
             keyed("ITEM_STARTS_QUEST", &[], WHITE, false)?;
         }
-        // LOCKED (red) — suppressed once the INSTANCE carries UNLOCKED `0x4` (the law's "and the
-        // item is not already unlocked"; the same bit the openable sub-gate reads). The key-item
-        // "Requires %s" sub-line joins with the Lock.dbc resolve (the GO-locks follow-up).
+        // LOCKED, red, until the instance carries UNLOCKED `0x4`.
         if v.lock_id != 0 && inst.is_none_or(|i| i.flags & 0x4 == 0) {
             keyed("LOCKED", &[], RED, false)?;
         }
     }
-    // Slot | type — or, for a bag, the single CONTAINER_SLOTS line in the same seat. The type
-    // cell is suppressed for cloaks (InventoryType 16) and displayFlags-hidden subclasses
-    // (rings/trinkets/shirts — the "Miscellaneous" family), both builder gates. The two cells
-    // recolor independently (byte-read at the builder's `0x52c143..0x52c1f9` legs against the
-    // verified `0x530270(this, left, right, leftColor, rightColor, wrap)` signature — NB the
-    // law §10 prose has the cells swapped): a proficiency-mask miss (`0xc4d4a0[class]` bit
-    // `1 << subclass`; our SMSG_SET_PROFICIENCY-fed map; no mask entry never reds) reds the
-    // TYPE cell — unless a weapon's alternate subclass (ItemSubClass prereq/postreq) is
-    // proficient, which reds the SLOT cell instead. Independently, an off-hand weapon
-    // (InventoryType 22) reds the SLOT cell without Dual Wield (`0x5eab70` = the learned
-    // effect-40 spell), even when the type itself is proficient.
-    // The bag line's gate is `InventoryType == 0x12` **alone** (`0x52b754 sete`, read at
-    // `0x52bffe`) — never the slot count, which the gate does not test at all: a 0-slot bag
-    // prints "0 Slot Bag". Every shipped container carries 18, quivers and ammo pouches
-    // included, which is why `INVTYPE_QUIVER` is a dead slot name in 1.12 (wow-re §D2.4:
-    // InventoryType 27 occurs in none of the 848 records of the reference install's own
-    // `itemcache.wdb`, and `0x809200[27]` maps to no equipment slot at all).
+    // The slot | type line, or for a bag the CONTAINER_SLOTS line in its seat. The type cell is
+    // hidden for cloaks (16) and display-hidden subclasses. The cells recolor independently
+    // (`0x52c143..0x52c1f9`): a proficiency miss (`0xc4d4a0[class]` bit `1 << subclass`; a class
+    // with no mask never reds) reds the type, or the slot when a weapon's alternate subclass is
+    // proficient; an off-hand weapon (22) without Dual Wield (`0x5eab70`) reds the slot.
+    // The bag gate is `InventoryType == 18` alone (`0x52b754`, read at `0x52bffe`), never the slot
+    // count. Quivers and ammo pouches are 18 too, so 27 is dead (`0x809200[27]` maps to no slot).
     if v.inventory_type == 18 {
-        // `%d` is `ContainerSlots`; `%s` is the SAME `ItemSubClass` DisplayName the type cell
-        // reads — so the noun is per-subclass ("24 Slot Soul Bag", "8 Slot Quiver", "6 Slot
-        // Ammo Pouch"), never the constant "Bag" this line used to print for every container.
-        // A container whose row has no display name emits NEITHER this line nor the ordinary
-        // slot|type one (`0x52c006`/`0x52c018`/`0x52c021` all jump past the whole region), and
-        // displayFlags bit 0 is not consulted on this path.
+        // `%s` is the subclass DisplayName the type cell reads ("8 Slot Quiver"); a subclass
+        // without one prints no line at all (`0x52c006`, `0x52c018`, `0x52c021`), and
+        // displayFlags bit 0 is not read here.
         if let Some(name) = v.sub_class_display.as_deref() {
             keyed(
                 "CONTAINER_SLOTS",
@@ -325,27 +204,16 @@ pub(super) fn render_view(
             )?;
         }
     } else {
-        // The slot cell. For **`ItemClass == 6` the InventoryType key table is not consulted at
-        // all** (`0x52c0bc cmp dword [esi],6`): the reference reads `ItemClass.dbc` row 6's own
-        // localized name — "Projectile" — verbatim out of the store at `[0xc0dc24]`, never
-        // through `FrameScript_GetText`. That is the same `[classRow + 4·locale + 0xc]` column
-        // `GetItemInfo`'s `itemType` answers with, which the view already carries.
-        //
-        // Every other class takes the `0x83ddb0` key table for its InventoryType, so the types
-        // whose keys `GlobalStrings.lua` does not carry (24 ammo, 25 thrown, 26 ranged-right,
-        // 27 quiver) draw no slot cell — but 15 `INVTYPE_RANGED` *does* ship, so a bow reads
-        // "Ranged | Bow" while a gun reads "Gun" alone. Decision 2080 removed three invented
-        // words here and was right about the KEYS; an arrow's cell is nonetheless not empty,
-        // because ammunition never reaches them (wow-re §D2.5j, VERIFIED).
+        // The slot cell: for `ItemClass == 6`, `ItemClass.dbc`'s own name ("Projectile", read
+        // from `[0xc0dc24]` at `0x52c0bc`), the column `GetItemInfo`'s itemType reads; else the
+        // `0x83ddb0` key, so a bow reads "Ranged | Bow" and a gun, whose key ships no string,
+        // "Gun" alone.
         let slot = if v.class == 6 {
             v.item_type.clone()
         } else {
             invtype_key(v.inventory_type).and_then(&get)
         };
-        // The type cell is `ItemSubClass.dbc`'s DisplayName for the pair, app-resolved (the
-        // builder's `0xc0db90` row cache read) — never a table in here: 2080 found the same
-        // shape one file over, where a hand-typed "Lockpicking" shadowed `LockType.dbc`'s own
-        // "Pick Lock".
+        // The type cell: `ItemSubClass.dbc`'s DisplayName, app-resolved (the builder's `0xc0db90`).
         let ty = if v.inventory_type == 16 || v.hide_subclass {
             None
         } else {
@@ -373,48 +241,30 @@ pub(super) fn render_view(
                 (t.to_string(), req_color(!right_red)),
             )?,
             (Some(s), None) => add((s, req_color(!left_red)))?,
-            // No slot name: the type stands alone and takes the hard-miss color (the
-            // builder's single-cell fallback keeps flag-1).
+            // No slot name: the type stands alone, keeping its own colour.
             (None, Some(t)) => add((t.to_string(), req_color(!right_red)))?,
             _ => {}
         }
     }
-    // **p4's SECOND cut** (`0x52c220`; `0x52c225 jne 0x52cc5b` skips `[0x52c22b, 0x52cc5b)`) —
-    // damage/speed/DPS, armor, block, the stat mods, the resistances and the whole enchant family.
-    // The two cuts are not contiguous: the slot/type cell between them is emitted either way.
+    // p4's second cut (`0x52c220`, skipping `[0x52c22b, 0x52cc5b)` at `0x52c225`): damage through
+    // the enchant family. The slot/type cell between the two cuts always prints.
     if !flags.name_only {
-        // **The damage block** — five slots, a five-arm template matrix and a first/PLUS_ flag
-        // (wow-re `tooltip-damage-matrix-and-container-slots.md` §D1, VERIFIED at
-        // `[0x52c22b, 0x52c5a1)`; §5 trio). Every arm is a key, and every hole's shape is the
-        // binary's own push list — this block composed its English in Rust until it was converted.
-        //
-        // The three predicates and the flag: **hasSchool** is the slot's school field being nonzero
-        // (school 0 takes the no-school subtree — `SPELL_SCHOOL0_CAP` is never looked up);
-        // **isAmmo** is `ItemClass == 6` and *only* that (not InventoryType, not a flag);
-        // **isSingle** is `floor(min) == ceil(max)` on the ROUNDED integers, tested only on the
-        // no-school non-ammo leaf (there is no `SINGLE_…_WITH_SCHOOL`); and **isFirst** is per-ITEM,
-        // cleared on the first EMITTED slot, so a skipped slot does not consume it.
+        // The damage block, `[0x52c22b, 0x52c5a1)`: per slot, a key picked by school (non-zero),
+        // ammo (`ItemClass == 6` alone) and, on the no-school non-ammo leaf only, single
+        // (`floor(min) == ceil(max)`); every emitted slot after the first takes `PLUS_`.
         let mut first = true;
         let mut dps_acc = 0.0f32;
         for &(min, max, school) in v.damages.iter().take(5) {
-            // `floor(min)` / `ceil(max)` — NOT a round-half pair, which is what this block used to
-            // do on both bounds. The reference biases by `0x808120` (0.9999899864196777, neither 0.5
-            // nor 1.0 — the epsilon is what stops an exactly-integral max being bumped) and converts
-            // with `__ftol`'s truncate-toward-zero. Fang of the Mystics' 38.7–85.7 reads "38 - 86";
-            // rounding to nearest would say "39 - 86" (43 shipped items carry fractional damage).
+            // The biased floor and ceil (`0x808120`), not rounding: 38.7-85.7 reads "38 - 86".
             let (lo, hi) = (floor_min(min), ceil_max(max));
             // A slot is emitted iff either rounded bound is nonzero (`0x52c292`).
             if lo == 0 && hi == 0 {
                 continue;
             }
-            // The school WORD is the resolved key; the school NUMBER is what picks the arm. A chain
-            // that carries no `SPELL_SCHOOL%d_CAP` still takes the with-school template and fills
-            // the hole with the empty string, exactly as `FrameScript_GetText` does.
+            // The school number picks the arm; a missing `SPELL_SCHOOL%d_CAP` fills its hole empty.
             let school_name = school_key(school).and_then(|k| get(&k)).unwrap_or_default();
-            // `avg` is the two ROUNDED bounds averaged, round-tripped through f32 — and it is NOT
-            // divided by anything: `AMMO_DAMAGE_TEMPLATE`'s shipped "Adds %g damage per second" is
-            // FrameXML's phrasing over a number the binary never makes per-second (Rough Arrow's
-            // 1–2 reads "Adds 1.5 damage per second").
+            // The rounded bounds' mean, not per second whatever `AMMO_DAMAGE_TEMPLATE` says: an
+            // arrow of 1-2 reads "Adds 1.5 damage per second".
             let avg = f64::from((lo + hi) as f32 * 0.5);
             let plus = |k: &str| {
                 if first {
@@ -445,17 +295,14 @@ pub(super) fn render_view(
                     vec![Arg::D(lo.into()), Arg::D(hi.into())],
                 )
             };
-            // The RIGHT cell is the FIRST emitted line's alone, and weapons' alone (`0x52c494`/
-            // `0x52c49c` — the only two conjuncts): every later damage line, and every line of a
-            // non-weapon, renders left-text-only. `"%s %.2f"` is an `.rdata` LITERAL, not a key —
-            // only the word "Speed" is looked up — over `Delay × 0.001`.
+            // Speed rides a weapon's first emitted line only (`0x52c494`, `0x52c49c`): the literal
+            // `"%s %.2f"` over `Delay × 0.001`, with only the word a key.
             let speed = (first && v.class == 2).then(|| {
                 let word = get("SPEED").unwrap_or_default();
                 let secs = f64::from(v.delay_ms) * f64::from(0.001_f32);
                 format!("{word} {secs:.2}")
             });
-            // The damage line is white in BOTH cells unconditionally — it never reddens for an item
-            // the player cannot use (`0x52c4fa`–`0x52c516`).
+            // White in both cells, even for an unusable item (`0x52c4fa..0x52c516`).
             if let Some(t) = get(&key) {
                 let line = (fill(&t, &args), WHITE);
                 match speed {
@@ -463,17 +310,14 @@ pub(super) fn render_view(
                     None => add(line)?,
                 }
             }
-            // The DPS accumulator runs on the emit path, and it uses the RAW floats — so the
-            // printed range and the printed DPS are computed from different numbers by design.
+            // DPS sums the raw floats of the emitted slots, not the printed bounds.
             dps_acc += (max + min) * 0.5;
             first = false;
         }
-        // DPS — two conjuncts: a line was emitted AND `ItemClass == 2`. Ammo can satisfy neither
-        // (its arms require class 6), so an arrow gets no DPS line and no Speed cell.
+        // DPS needs an emitted line and `ItemClass == 2`, so ammunition has none.
         if !first && v.class == 2 {
-            // The precision is DPS_TEMPLATE's own `%.1f`, not ours — a locale that respells it gets
-            // its own number of decimals with no code change (law §12: "the print precision is
-            // FRAMEXML-DATA"). There is no divide-by-zero guard in the reference either.
+            // The precision is `DPS_TEMPLATE`'s own (`0x854c4c`); the reference has no
+            // divide-by-zero guard either.
             let secs = f64::from(v.delay_ms) * f64::from(0.001_f32);
             keyed(
                 "DPS_TEMPLATE",
@@ -493,30 +337,23 @@ pub(super) fn render_view(
                 false,
             )?;
         }
-        // Stat mods (+N Stamina …) in the client's DISPLAY order — the `0x808e88` table (byte-read:
-        // 4,3,7,5,6,1,0 then 8,9,2,10 + zero padding; the builder's outer loop walks the table,
-        // the inner loop scans the item's raw slots — `0x52c6b0..0x52c801`). So Strength, Agility,
-        // Stamina, Intellect, Spirit, Health, Mana — never the wire order. (The table's trailing
-        // ZERO entries would re-match a mana slot once per pass — a dormant client quirk nothing
-        // shipped can reach: the only mana-stat item in the whole 1.12 DB is the internal "Test MP
-        // Ring" 6674. Not emulated.)
+        // Stats in the display order of `0x808e88` (4,3,7,5,6,1,0, then 8,9,2,10 and zero padding;
+        // `0x52c6b0..0x52c801`), not wire order. Deviation: the reference's padding repeats a mana
+        // stat once per zero entry; not emulated, since only the internal test ring 6674 has one.
         const STAT_DISPLAY_ORDER: [u32; 7] = [4, 3, 7, 5, 6, 1, 0];
         for &want in &STAT_DISPLAY_ORDER {
             for &(t, val) in &v.stats {
                 if t != want || val == 0 {
                     continue;
                 }
-                // The `ITEM_MOD_*` template is the whole line, sign hole included
-                // (`"%c%d Agility"`) — the sign is an argument, not a prefix we glue on.
+                // The sign fills the template's `%c` (`"%c%d Agility"`).
                 let Some(key) = stat_key(t) else { continue };
                 let sign = if val > 0 { "+" } else { "-" };
                 keyed(key, &[Arg::S(sign), Arg::D(val.abs().into())], WHITE, false)?;
             }
         }
-        // Resistances: six equal nonzero values collapse to the ALL line; otherwise one line per
-        // nonzero school with HOLY excluded from the singles loop (both byte-verified). The six
-        // fields are schools 1..6, so slot `i` names `SPELL_SCHOOL{i+1}_CAP` — the same `%d`-composed
-        // key the damage line uses one block up.
+        // Six equal non-zero resistances print the ALL line; otherwise one line per non-zero
+        // school, Holy excluded. Field `i` is school `i + 1`.
         let first_res = v.resistances[0];
         if first_res != 0 && v.resistances.iter().all(|&r| r == first_res) {
             let sign = if first_res > 0 { "+" } else { "-" };
@@ -527,12 +364,8 @@ pub(super) fn render_view(
                 false,
             )?;
         } else {
-            // **The singles come out in the BUILDER's order, not the field order.** `0x52c8ad–
-            // 0x52c93e` runs `edi` 1..5 and reads school `esi = (edi == 1) ? 6 : edi`, so the lines
-            // are Arcane, Fire, Nature, Frost, Shadow — and that 1→6 remap is *how* Holy is excluded:
-            // it is displaced by Arcane rather than skipped by a test. Read while converting the
-            // block's keys and named in decision 2080; we emitted plain field order (Fire first,
-            // Arcane last) until it was converted.
+            // The builder's order, not field order: `0x52c8ad..0x52c93e` walks 1..5 reading school
+            // 6 for 1, so Arcane comes first and Holy is displaced rather than tested.
             const RESIST_EMIT_ORDER: [u32; 5] = [6, 2, 3, 4, 5];
             for school in RESIST_EMIT_ORDER {
                 let r = v.resistances[school as usize - 1];
@@ -549,41 +382,18 @@ pub(super) fn render_view(
                 )?;
             }
         }
-        // **Line 17 — the enchant family** (wow-re `tooltip-content-law.md` §1-ENCHANT, byte-carved
-        // 2026-08-03 on this lane's dispatch; decisions 0915/0920). One contiguous block
-        // `[0x52c991, 0x52cc69)` between the resistances and the durability precompute, and three arms
-        // that are mutually exclusive by construction — the per-slot loop falls through to the
-        // proposed-enchant pair and jumps the block's end, so RANDOM_ENCHANT is reachable only when
-        // there was no id source at all (§E1).
-        //
-        // The **colour is per slot**, and this is the correction the carve landed (§E3): the value is a
-        // computed local, defaulting to WHITE, overwritten **only for slots 0 and 1** — green
-        // `0xc0d3ac` for a positive id, pure-red `0xc0d398` for a negative one. Slots 2..6 — the
-        // random-property suffix enchants — are **always white**, whatever the sign. (Our first cut
-        // painted every slot green.) The sign never picks a different DBC row; the app already
-        // resolved that off `abs(id)`.
-        //
-        // Two gates sit above the loop. **ITEM_SIGNABLE** (template Flags bit `0x2000`, a petition or
-        // guild charter) forces every id to 0 with no fallback (`0x52c9e0: test ah,0x20`) — such an
-        // item shows no enchant line even if its instance carries ids. And with **no id source at all**
-        // the block instead prints the template-only `ITEM_RANDOM_ENCHANT` placeholder (§E5).
+        // The enchant family, `[0x52c991, 0x52cc69)`: the slot loop, or with no id source at all
+        // the `ITEM_RANDOM_ENCHANT` placeholder (`0x52cc33`). Slots 0 and 1 are green `0xc0d3ac`
+        // for a positive id and red `0xc0d398` for a negative one; the suffix slots 2..6 are always
+        // white. A signable item (`0x2000`) zeroes every id (`0x52c9e0`) and shows no enchant line.
         let signable = v.flags & 0x2000 != 0;
         let enchant_slots = match signable {
             true => &[][..],
             false => inst.map(|i| i.enchants.as_slice()).unwrap_or_default(),
         };
-        // "No id source" is the reference's own three-way fork (§E1): a wrapped gift, or no item
-        // object AND no caller-supplied instance block (`+0x440 == 0`). Ours reads the same: a hover
-        // that passes NO [`ItemInstance`] is a p6=0 leg — the template sources (merchant, quest,
-        // craft, buyback, send-mail, the compare legs, `BenillaSetItemById`) — plus the wrapped-gift bit.
-        //
-        // **A block-supplying source never prints the placeholder, even carrying no ids at all.** The
-        // fork tests the block's presence, not its contents, so `SetLootItem`/`SetHyperlink`/
-        // `SetInboxItem`/`SetAuctionItem`/`SetLootRollItem`/the trade legs fall into the slot loop and
-        // print whatever their slots hold — nothing, when the roll is absent. Decision 0920's prose
-        // put a hyperlink hover on the placeholder arm; §E1's `0x52c9a3` fork says otherwise, and
-        // that is the drift 1547 corrects (a linked or looted "of the Monkey" showed the placeholder
-        // where the reference shows the rolled lines).
+        // No id source (`0x52c991`): a wrapped gift, or no item object and no instance block
+        // (`+0x440 == 0`), here a hover passing no [`ItemInstance`]. The fork tests the block's
+        // presence, not its contents (`0x52c9a3`), so a block source never shows the placeholder.
         let no_id_source = inst.is_none_or(|i| i.flags & 0x8 != 0);
         if no_id_source && !signable && v.random_property != 0 {
             keyed("ITEM_RANDOM_ENCHANT", &[], GREEN, false)?;
@@ -594,26 +404,19 @@ pub(super) fn render_view(
                 (true, true) => ENCHANT_RED,
                 (false, _) => WHITE,
             };
-            // A TEMPORARY enchant's countdown REPLACES the plain name in the same line and keeps that
-            // colour — it is never a second line (§E3). The bucket ladder (day/hour/min/sec) and its
-            // ceil-vs-truncate split are [`enchant_time_left`]'s; its source is
-            // `SMSG_ITEM_ENCHANT_TIME_UPDATE`, never the item's own duration field.
+            // A temporary enchant's countdown replaces its name, in the same line and colour
+            // (`0x52ca49`); the time is `SMSG_ITEM_ENCHANT_TIME_UPDATE`'s.
             let mut text = match e.remaining_ms {
-                // The countdown IS the line — `ITEM_ENCHANT_TIME_LEFT_MIN = "%s (%d min)"` carries
-                // the enchant's own name in its first hole. Without that template there is no line
-                // to compose: the reference printf's an empty format into a zeroed buffer and
-                // `AddLine` drops the empty row, so a missing key skips the slot rather than falling
-                // back to the bare name.
+                // A missing template skips the slot, not falling back to the bare name: the
+                // reference formats an empty string, which `AddLine` drops.
                 Some(ms) => match enchant_time_left(&e.name, ms, &get) {
                     Some(t) => t,
                     None => continue,
                 },
                 None => e.name.clone(),
             };
-            // " (N Charges)" — the slot's own charges dword through ITEM_SPELL_CHARGES, then the
-            // literal `" (%s)" 0x854820` (`0x52caa6–0x52cb38`), which is the engine's own format and
-            // not a string table entry. Only an owned item object carries charges; the session/inspect
-            // legs ship ids alone, so this is naturally absent there.
+            // The slot's charges: ITEM_SPELL_CHARGES inside the literal `" (%s)"` (`0x854820`,
+            // `0x52caa6..0x52cb38`).
             if let Some(charges) = charges_phrase(e.charges, &get) {
                 text.push_str(&format!(" ({charges})"));
             }
@@ -621,9 +424,7 @@ pub(super) fn render_view(
         }
     }
     if let Some((cur, max)) = inst.and_then(|i| i.durability).filter(|&(_, max)| max > 0) {
-        // Red iff BROKEN (durability 0) — the byte law (wow-re ui.md tooltip content law:
-        // "durability (red iff broken==0)", the AddLine colour pointer `0xc0d390`, the same
-        // red as the unmet-requirement lines).
+        // Red (`0xc0d390`) only when broken.
         let color = if cur == 0 { RED } else { WHITE };
         keyed(
             "DURABILITY_TEMPLATE",
@@ -640,29 +441,17 @@ pub(super) fn render_view(
             false,
         )?;
     }
-    // **ITEM_DURATION `0x854bb4` — the item's own expiry countdown** (`0x52ce0d`, one of the four
-    // sites that set the builder's `[ebp-0x38]` return, wow-re `tooltip-content-law.md` §E3's
-    // census). It sits here by that address: after the durability precompute the note pins at
-    // `0x52cd0e–0x52cd22` (law line 18) and well before `ITEM_COOLDOWN_TIME` at `0x52e140` (line
-    // 23) — the numbered law list omits the line entirely, which is the gap decision 1933 names.
-    // Formatted through the same `0x52fa50` ladder as the enchant countdown, with key prefix
-    // `ITEM_DURATION`; unlike its siblings that prefix ships **no `_P1` plural twin**, so every
-    // count reads "days"/"hrs" (`GlobalStrings.lua:2401-2404`) — which `plural_template`'s
-    // fall-back-to-the-bare-token arm produces without a special case.
-    //
-    // **This is `tooltip::duration_text` itself**, not a second copy of the ladder: the two had
-    // drifted into separate implementations of the same four arms, and the local one always
-    // emitted a line (an invented sentence off an install) where the shared one returns `None`.
-    // The one seam is the width — the deadline is parked as `u64` milliseconds and the reference's
-    // formatter takes a dword, so a timer past 49.7 days saturates rather than wrapping. No 1.12
-    // item carries one; the longest shipped duration is a fortnight.
+    // ITEM_DURATION (`0x854bb4`, `0x52ce0d`), the item's own expiry: after durability
+    // (`0x52cd0e..0x52cd22`), before ITEM_COOLDOWN_TIME (`0x52e140`), through the `0x52fa50`
+    // ladder. Its prefix ships no `_P1` twin, so every count reads "days" or "hrs"
+    // (`GlobalStrings.lua:2401-2404`). The reference's formatter takes a dword, so a timer past
+    // 49.7 days saturates here; no 1.12 item lasts past a fortnight.
     if let Some(ms) = inst.and_then(|i| i.duration_ms) {
         let ms = u32::try_from(ms).unwrap_or(u32::MAX);
         if let Some(line) = duration_text(ms, "ITEM_DURATION", true, &get) {
             add((line, WHITE))?;
         }
     }
-    // Class/race lists — red when the player's own bit is absent (the usable ask).
     if v.allowable_class > 0
         && (v.allowable_class & full_mask(&CLASS_NAMES)) != full_mask(&CLASS_NAMES)
     {
@@ -698,9 +487,7 @@ pub(super) fn render_view(
             )?;
         }
     }
-    // ITEM_MIN_LEVEL prints only for RequiredLevel > 1 (byte-VERIFIED `0x52d2cf`: `cmp esi,0x1 /
-    // jle skip`) — a level-1 requirement gates nothing a logged-in player could fail, so the
-    // real client hides it on all the level-1 consumables that carry one.
+    // Only a required level above 1 prints (`0x52d2cf`).
     if v.required_level > 1 {
         keyed(
             "ITEM_MIN_LEVEL",
@@ -709,11 +496,8 @@ pub(super) fn render_view(
             false,
         )?;
     }
-    // The skill requirement is TWO keys, picked by whether a rank is asked for — `ITEM_MIN_SKILL`
-    // = "Requires %s (%d)" and `ITEM_REQ_SKILL` = "Requires %s" (the builder's own pair at
-    // `0x52d34e`/`0x52d355`). `ITEM_REQ_SKILL` is also what the required-SPELL line below takes
-    // (`0x52d650`): three other 1.12 keys read "Requires %s" in enUS — the `LOCKED_WITH_*` trio —
-    // and none of them is this line.
+    // ITEM_MIN_SKILL with a rank, ITEM_REQ_SKILL without (`0x52d34e`, `0x52d355`); the required
+    // spell takes ITEM_REQ_SKILL too (`0x52d650`).
     if let Some(skill) = &v.required_skill_name {
         let have = req.skills.get(&v.required_skill).copied().unwrap_or(0);
         let color = req_color(have >= v.required_skill_rank.max(1));
@@ -735,9 +519,7 @@ pub(super) fn render_view(
         }
     }
     if let Some(rep) = &v.required_rep_line {
-        // Red when the player's rank with the faction is below the requirement (the §1-RED rep
-        // leg: standing `< [+0x58]`); an unfed faction reads as unmet, like the real client's
-        // empty store at login (INITIALIZE_FACTIONS lands before the world does).
+        // Red (`0xc0d390`) below the required rank (`[+0x58]`); an unfed faction reads as unmet.
         let rank = req
             .rep_ranks
             .get(&v.required_rep_faction)
@@ -748,14 +530,11 @@ pub(super) fn render_view(
             req_color(u32::from(rank) >= v.required_rep_rank),
         ))?;
     }
-    // ITEM_SPELL_KNOWN — a taught spell the player already knows, UNCONDITIONALLY red.
     if taught_known {
         keyed("ITEM_SPELL_KNOWN", &[], RED, false)?;
     }
-    // Green trigger lines, wrapped — the text is app-resolved (the spell's name in P1; its
-    // $-substituted description via the token engine in P2). The prefix is a key, joined to the
-    // text by the engine's own `"%s %s"` literal `0x82ef08` (`0x52da7e`) — which is why the
-    // shipped values ("Use:", "Equip:", "Chance on hit:") carry no trailing space of their own.
+    // Green, wrapped trigger lines: the prefix key and the app-resolved text joined by the
+    // literal `"%s %s"` (`0x82ef08`, `0x52da7e`).
     for &(trigger, _, ref text) in &v.spell_triggers {
         let key = match trigger {
             0 | 5 => "ITEM_SPELL_TRIGGER_ONUSE",
@@ -769,21 +548,12 @@ pub(super) fn render_view(
     if let Some(charges) = charges_phrase(v.charges.max(0) as u32, &get) {
         add((charges, WHITE))?;
     }
-    // The item-SET block (§22, above the binary's p4 cut at `0x52e14c`), byte-read at the builder's
-    // `0x52d8a0..0x52e0f5`: a blank gold line ([`SET_SPACER`]), the gold "name (owned/total)"
-    // header, the set-level skill line (white, red when short), the member ladder ("  name" —
-    // pale-cream `0xc0d368` when equipped, gray otherwise; a member whose template is still in
-    // flight waits — the app re-pushes the view as names land), a second blank, then the threshold
-    // bonuses sorted THRESHOLD-ASCENDING (the builder qsorts the slot indices via `0x52e5c0` —
-    // never the DBC's stored order), green only when the skill requirement is met (`0x5eaae0`)
-    // AND owned ≥ threshold. "Owned" counts EQUIPPED members on both builder paths (the
-    // owner-unit 19-slot scan / the hyperlink walk with section mask 0x1).
-    //
-    // **The two bonus arms are two different KEYS, and this is where reading the byte law paid**
-    // (`0x52e056..0x52e0d6`): the met arm formats `ITEM_SET_BONUS` = "Set: %s" with the text
-    // alone, and only the unmet arm formats `ITEM_SET_BONUS_GRAY` = "(%d) Set: %s" with the
-    // count. We had printed the counted form in both colours, so an ACTIVE set bonus read
-    // "(3) Set: …" where 1.12 reads "Set: …".
+    // The set block (`0x52d8a0..0x52e0f5`), above p4's cut at `0x52e14c`: a blank gold line, the
+    // gold "name (owned/total)" header, the set's skill line, the members (cream `0xc0d368` when
+    // equipped, else gray; one still in flight waits), a second blank, then the bonuses sorted by
+    // threshold (`0x52e5c0`), green when the skill is met (`0x5eaae0`) and enough are owned.
+    // "Owned" counts equipped members on both builder paths. A met bonus is ITEM_SET_BONUS, the
+    // text alone; only an unmet one is ITEM_SET_BONUS_GRAY, with its count (`0x52e056..0x52e0d6`).
     if let Some(set) = &set_view {
         let owned = set
             .members
@@ -814,8 +584,7 @@ pub(super) fn render_view(
                 keyed("ITEM_REQ_SKILL", &[Arg::S(skill)], color, false)?;
             }
         }
-        // The member ladder's two-space indent is the engine's own `"  %s"` literal `0x854b14`,
-        // not a string-table entry.
+        // The two-space indent is the literal `"  %s"` (`0x854b14`), not a key.
         for (id, name) in &set.members {
             let Some(name) = name else { continue };
             let color = if equipped.contains(id) { CREAM } else { GRAY };
@@ -833,30 +602,22 @@ pub(super) fn render_view(
             }
         }
     }
-    // **p4's early return** — `0x52e147` reads the flag and `0x52e14c je 0x52e170` takes the
-    // NON-compact leg, so compact is the fall-through `0x52e14e`: it stamps `[esi+0xd0]=1`, lays
-    // out, and returns `[ebp-0x38]` (the `hasCooldown` answer is produced on this path too).
-    // Everything from here down — flavor text, creator/gift, OPENABLE/READABLE, money — is below
-    // `0x52e170` and never runs.
+    // p4's early return (`0x52e147..0x52e14c`): compact falls through to `0x52e14e`, lays out and
+    // returns, so nothing from `0x52e170` on runs: flavor text, creator, open or read line, money.
     if flags.name_only {
         return Ok(());
     }
-    // The quoted flavor text — gold, wrapped, literal quotes (all three byte-verified).
     if !v.description.is_empty() {
         addw((format!("\"{}\"", v.description), GOLD))?;
     }
-    // Everything below rides the REAL-INSTANCE gate (`0x52e1c7`/`0x52e2e0`): a template/link
-    // hover emits no creator line and no openable/readable line — you can't right-click a
-    // hyperlink open.
+    // The reference gates the rest on an item object (`0x52e1c7`, `0x52e2e0`). Here only a template
+    // source (`None`) stops, so a link, loot, mail or auction hover, which has an instance but no
+    // object, still reaches READABLE.
     let Some(inst) = inst else { return Ok(()) };
-    // The creator line (`0x52e1b1..0x52e2db`, wow-re §1-CREATOR CONFIRMED): the resolved
-    // `ITEM_FIELD_CREATOR` name — a letter (instance text id) is ITEM_WRITTEN_BY, anything
-    // else ITEM_CREATED_BY, both the literal 1.12 GlobalStrings (the Made-by green is the
-    // string's OWN `|cff00ff00` escape; the AddLine color pointer is white `0xc0cf60`, wrap 0).
-    // A WRAPPED instance (`ITEM_FIELD_FLAGS` bit `0x8` — the arm gate `0x52b7b0`, instance bit
-    // only) switches the whole line to ITEM_WRAPPED_BY off `ITEM_FIELD_GIFTCREATOR`; that
-    // field has no feed yet, so a wrapped instance emits NOTHING here rather than a wrong
-    // "Made by" (gifts join with the wrap/unwrap arc).
+    // The creator line (`0x52e1b1..0x52e2db`), white `0xc0cf60`: ITEM_WRITTEN_BY for a letter, else
+    // ITEM_CREATED_BY, green by its own `|cff00ff00`. A wrapped instance (`0x8`, gate `0x52b7b0`)
+    // takes ITEM_WRAPPED_BY off `ITEM_FIELD_GIFTCREATOR` in the reference; that is not built, so a
+    // wrapped instance prints no creator line.
     if inst.flags & 0x8 == 0 {
         if let Some(name) = &inst.creator {
             let key = if inst.has_text {
@@ -867,18 +628,10 @@ pub(super) fn render_view(
             keyed(key, &[Arg::S(name)], WHITE, false)?;
         }
     }
-    // ITEM_OPENABLE / ITEM_READABLE — ONE line, openable wins outright (the `jmp 0x52e35d` past
-    // the READABLE test; `0x52e2f2..0x52e35d`, wow-re `right-click-open.md` §1.4, re-verified
-    // unchanged by the 2026-08-02 §5 pair): openable = a p6=0 source ([`ItemInstance::
-    // openable_source`]) AND the template loot flag `0x4` behind its lock sub-gate (LockID set →
-    // only once the instance carries UNLOCKED `0x4`), or a wrapped gift (template WRAPPER `0x200`
-    // + instance WRAPPED `0x8`); readable = template PageText (the CGItem vtable `+0x74` getter
-    // `0x5d9e10`) OR the instance letter text. Both green.
-    //
-    // Note the lock sub-gate is the LINE's, not the CLICK's: the send arm tests the bare template
-    // bit, so a locked junkbox stays silent here while its right-click still goes out and draws
-    // the server's "Item is locked" (decision 0896, `ItemInfo::opens_loot`). The click order is
-    // also the inverse of this one — READABLE wins there.
+    // One green line, OPENABLE winning (`0x52e2f2..0x52e35d`). Openable: a p6=0 source and either
+    // the loot flag `0x4` behind its lock gate (a lock needs UNLOCKED) or a wrapped gift (`0x200`
+    // and WRAPPED `0x8`). Readable: PageText (`0x5d9e10`) or the letter text. The lock gate is the
+    // line's only: the click tests the bare flag (`ItemInfo::opens_loot`), and READABLE wins there.
     let openable = inst.openable_source
         && ((v.flags & 0x4 != 0 && (v.lock_id == 0 || inst.flags & 0x4 != 0))
             || (v.flags & 0x200 != 0 && inst.flags & 0x8 != 0));
@@ -890,33 +643,17 @@ pub(super) fn render_view(
     Ok(())
 }
 
-/// A temporary enchant's line text — the name with its countdown, the reference's own bucket
-/// ladder (wow-re `tooltip-content-law.md` §E3 → `0x52fa50`, byte-verified): a runtime key
-/// `ITEM_ENCHANT_TIME_LEFT_<DAYS|HOURS|MIN|SEC>` chosen by the largest unit that fits, with the
-/// count taken as **ceil** in the day/hour/minute arms and **truncated** in the seconds arm, and
-/// the `_P1` plural twin picked by [`plural_template`]'s byte-pinned rule. The day and hour keys
-/// ship a twin; minutes and seconds do not, so those read "(1 min)" at one minute exactly as they
-/// read "(9 min)".
-///
-/// **Two holes, which is why this cannot be `duration_text`**: the templates are
-/// `"%s (%d min)"` — the enchant's own name fills the first, the count the second. That name is
-/// the `SpellItemEnchantment` row's, DBC data rather than a string-table sentence, so it arrives
-/// as an argument. `None` = the family is absent from the install's string table, and the caller
-/// draws no line at all.
+/// A temporary enchant's name with its countdown (`0x52fa50`): `ITEM_ENCHANT_TIME_LEFT_<unit>`, its
+/// `_P1` twin picked by [`plural_template`]. Two holes, the name then the count, so not
+/// `duration_text`; `None` when the install lacks the family, and the caller draws no line.
 fn enchant_time_left(name: &str, ms: u64, get: &dyn Fn(&str) -> Option<String>) -> Option<String> {
     let (suffix, n) = time_bucket(ms);
     let template = plural_template(&format!("ITEM_ENCHANT_TIME_LEFT_{suffix}"), n, get)?;
     Some(fill(&template, &[Arg::S(name), Arg::D(i64::from(n))]))
 }
 
-/// `0x52fa50`'s bucket + count for the ENCHANT countdown — the key suffix and the number that
-/// fills it. The largest unit that fits wins (`>= 1 day` · `>= 1 h` · `>= 1 min` · else seconds);
-/// the count is **ceil** in the day/hour/minute arms (the `roundUp` argument, which all seven of
-/// the function's callers pass as 1) and plain **truncation** in the seconds arm.
-///
-/// The same ladder [`crate::script::tooltip::duration_text`] walks — it stays separate only
-/// because that one fills a single-hole template and this family has two holes; every other
-/// countdown in the tooltips goes through `duration_text`.
+/// `0x52fa50`'s unit and count: the largest unit that fits, the count ceiled for days, hours and
+/// minutes (all seven callers pass `roundUp` 1) and truncated for seconds.
 fn time_bucket(ms: u64) -> (&'static str, u32) {
     const SEC: u64 = 1_000;
     const MIN: u64 = 60 * SEC;
@@ -932,12 +669,8 @@ fn time_bucket(ms: u64) -> (&'static str, u32) {
     (suffix, u32::try_from(n).unwrap_or(u32::MAX))
 }
 
-/// `ITEM_SPELL_CHARGES` and its `_P1` plural twin (`0x84e3b4`, pushed at `0x52cae8` for the
-/// enchant suffix and `0x52db61` for the standalone line). One rule for both consumers: the
-/// charges line (law line 21) and the enchant line's ` (…)` suffix (§E3).
-///
-/// Zero answers `None` — the reference never reaches this with a zero count, and neither
-/// consumer here has a line to draw without one.
+/// `ITEM_SPELL_CHARGES` or its `_P1` twin (`0x84e3b4`), pushed at `0x52cae8` for the enchant
+/// suffix and `0x52db61` for the charges line; zero charges have no phrase.
 fn charges_phrase(n: u32, get: &dyn Fn(&str) -> Option<String>) -> Option<String> {
     if n == 0 {
         return None;
@@ -950,10 +683,8 @@ fn charges_phrase(n: u32, get: &dyn Fn(&str) -> Option<String>) -> Option<String
 mod tests {
     use super::*;
 
-    /// A stand-in string table, **deliberately not the shipped wording** — what is under test is
-    /// which key is reached and what fills it, never what the sentence says (decision 2045,
-    /// "assert the identifier, not the sentence"). Every value carries angle brackets so a
-    /// resolved line cannot be mistaken for a composed one.
+    /// A stand-in string table, not the shipped wording: the tests check which key is reached and
+    /// what fills it.
     fn table(key: &str) -> Option<String> {
         Some(
             match key {
@@ -971,10 +702,7 @@ mod tests {
         )
     }
 
-    /// The countdown's bucket ladder (wow-re §1-ENCHANT §E3 → `0x52fa50`): the largest unit that
-    /// fits wins, the count is **ceil** in the day/hour/minute arms and **truncated** in seconds,
-    /// and the day/hour arms have `_P1` twins while minutes and seconds do not — so those two
-    /// suffixes reach the same key at every count.
+    /// The `0x52fa50` ladder: minutes and seconds have no `_P1` twin, so each reaches one key.
     #[test]
     fn enchant_countdown_buckets_and_rounding() {
         let t = |ms| enchant_time_left("Rockbiter", ms, &table);
@@ -990,21 +718,17 @@ mod tests {
         // Days ceil.
         assert_eq!(t(86_400_000).as_deref(), Some("<Rockbiter :: 1 D>"));
         assert_eq!(t(86_400_001).as_deref(), Some("<Rockbiter :: 2 DD>"));
-        // Zero never reaches here (the app drops an expired timer), but it must not panic — and
-        // zero takes the PLURAL arm, which is `GetPluralIndex`'s rule, not a rounding accident.
+        // The app drops an expired timer, but zero must not panic; it takes the plural arm,
+        // `GetPluralIndex`'s rule.
         assert_eq!(t(0).as_deref(), Some("<Rockbiter :: 0 S>"));
     }
 
-    /// A string table that does not carry the family draws **no line**, never an invented one —
-    /// the whole point of resolving by key rather than composing (2045).
     #[test]
     fn a_missing_countdown_family_draws_nothing() {
         assert_eq!(enchant_time_left("Rockbiter", 60_000, &|_| None), None);
         assert_eq!(charges_phrase(3, &|_| None), None);
     }
 
-    /// `ITEM_SPELL_CHARGES` and its `_P1` plural twin — one rule, both consumers (the charges
-    /// line and the enchant line's suffix). A zero count has no line either way.
     #[test]
     fn charges_phrase_picks_the_plural() {
         assert_eq!(charges_phrase(1, &table).as_deref(), Some("<1 chg>"));
diff --git a/crates/benilla-ui/src/script/tooltip_spell.rs b/crates/benilla-ui/src/script/tooltip_spell.rs
index 3a0278e5..e4757cd6 100644
--- a/crates/benilla-ui/src/script/tooltip_spell.rs
+++ b/crates/benilla-ui/src/script/tooltip_spell.rs
@@ -1,26 +1,12 @@
-//! The engine **spell/aura tooltip channel** (decision 0274 P2) — the verified line law of the
-//! spell builder `0x52e610` and the aura builder `0x52f880` (wow-re
-//! `ui/scratch/tooltip-content-law.md`, the 0276 fold-back):
+//! The spell and aura tooltip content, in the line order of the spell builder `0x52e610` and the
+//! aura builder `0x52f880`: name and rank; cost and range; cast time and cooldown (omitted for a
+//! passive spell, with no "Passive" line); the required item class, then form, white when met and
+//! red when not; reagents, a missing one inline red; the description, gold (white on an aura).
+//! Only `SetPlayerBuff` adds the gold time-remaining line.
 //!
-//! - name | rank (gray) — one double line. The name's colour is the BUILDER's: **white** from
-//!   the spell builder (`0x530270`), **gold** from the aura builder (`0x530380`, the gold
-//!   wrapper) — the same split `SetTrackingSpell` shows;
-//! - **Cost | Range** — ONE double line (either side may be absent);
-//! - **CastTime | Cooldown** — ONE double line; a passive spell simply omits it (there is NO
-//!   "Passive" text in the 1.12 builder);
-//! - required tool / form — the equipped-item-class line then the stance line, each white when
-//!   met and red when not;
-//! - reagents — inline red per missing item (the one builder that uses the `|cffff2020` escape;
-//!   joins when a reagent feed exists);
-//! - description — gold, wrapped. An AURA's description is **white** (byte-verified difference),
-//!   and only `SetPlayerBuff` appends the duration-remaining line, which is **gold** again
-//!   (`0xffffd200`, the title's gold — B62; see [`render_spell`]'s tail).
-//!
-//! The engine renders VIEWS ([`SpellTooltipView`]) the app resolves at push time — the $-token
-//! substitution (values off Spell.dbc + the player's level), cast-time/duration/range text —
-//! because the catalogs and the token engine live app-side; the engine holds no DBC knowledge.
-//! Views are keyed by spell id in an ask-once store (the item-template store's pattern): a
-//! renderer miss records the id, the app resolves and pushes, the hover's re-enter repaints.
+//! The app resolves each spell into a [`SpellTooltipView`] (`$`-tokens, cast, range and duration
+//! text), kept in an ask-once store by spell id: a miss records the id, the app pushes the view and
+//! the next hover repaints.
 
 use mlua::{Lua, Table, Value};
 
@@ -29,81 +15,67 @@ use super::tooltip::{append_line, clear_content, fire_cleared};
 use super::{CraftTooltip, Model, TrainerTooltip};
 
 const WHITE: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
-/// The rank column's gray — byte-verified `0xff808080` (0276).
+/// The rank column's gray, `0xff808080`.
 const GRAY: [f32; 4] = [128.0 / 255.0, 128.0 / 255.0, 128.0 / 255.0, 1.0];
-/// The description gold — byte-verified `0xffffd200` (0276).
+/// The description gold, `0xffffd200`.
 const GOLD: [f32; 4] = [1.0, 210.0 / 255.0, 0.0, 1.0];
 
-/// One spell's tooltip view — every string app-resolved (the $-engine's output for the
-/// description; the cost/range/cast/cooldown texts off the DBC catalogs).
+/// One spell's tooltip, every string resolved by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct SpellTooltipView {
     pub name: String,
-    /// "Rank N" — the gray right column of the name line, on the SPELL variant only.
+    /// "Rank N", the name line's gray right column on the spell variant.
     pub rank: Option<String>,
-    /// "Magic" / "Curse" / "Disease" / "Poison" — the AURA variant's right column (law §3-BUFF),
-    /// the `SpellDispelType.dbc` name of the spell's dispel class gated by that table's `[+0x28]`
-    /// flag, so an undispellable aura (Stealth) carries `None`. Rendered GOLD, like the aura name
-    /// it shares its line with — not the spell variant's gray.
+    /// The aura variant's gold right column (`0x52f8e5`): the `SpellDispelType.dbc` name, such as
+    /// "Magic", when that row's `[+0x28]` flag is set, so Stealth has none.
     pub dispel_type: Option<String>,
-    /// "35 Mana" / "20 Rage" / "20 Health" / "11 Health, plus 5 per sec" — the cost cell: the
-    /// RESOLVED cost through the power-type key array with the health fallback (1074).
+    /// The cost cell, such as "35 Mana" or "11 Health, plus 5 per sec": the resolved cost through
+    /// the power-type keys, falling back to health.
     pub cost: Option<String>,
-    /// "30 yd range" — the range cell.
     pub range: Option<String>,
-    /// "1.5 sec cast" / "Instant cast" / "Instant" / "Next melee" / "Attack speed" /
-    /// "Channeled" — `None` = a passive spell: the whole casttime|cooldown line is omitted
-    /// (the verified law; never a "Passive" text line).
+    /// The cast cell ("1.5 sec cast", "Instant", "Next melee", "Channeled"); `None` is a passive
+    /// spell, whose cast and cooldown line is omitted.
     pub cast_time: Option<String>,
-    /// "15 sec cooldown" — the cooldown cell: `max(RecoveryTime, CategoryRecoveryTime)` (the
-    /// 0276 line law §3.4 — Charge's 15 s lives in the CATEGORY column).
+    /// The cooldown cell (`SPELL_RECAST_TIME_SEC 0x854ed4`): `max(RecoveryTime,
+    /// CategoryRecoveryTime)`, as Charge's 15 s is in the category column.
     pub cooldown: Option<String>,
-    /// "Requires Wands" — the equipped-item-class half of law §3.6, over
-    /// `EquippedItemClass`/`EquippedItemSubClassMask`: white when [`Self::item_met`], red when
-    /// not. Sits ABOVE [`Self::requires_form`] (the law's tool-then-form order).
+    /// "Requires Wands" (`SPELL_EQUIPPED_ITEM 0x854e94`), from `EquippedItemClass` and
+    /// `EquippedItemSubClassMask`.
     pub requires_item: Option<String>,
-    /// Whether some WORN item satisfies the class + subclass mask (the app re-pushes views when
-    /// the equipped set changes, so the color tracks live swaps).
+    /// A worn item matches the class and subclass mask; re-pushed on an equipment change.
     pub item_met: bool,
-    /// "Requires Battle Stance" — the required-form line (law §3.6, `SPELL_REQUIRED_FORM` over
-    /// the `Stances` mask): white when [`Self::form_met`], red when not.
+    /// "Requires Battle Stance" (`SPELL_REQUIRED_FORM 0x854e64`), from the `Stances` mask.
     pub requires_form: Option<String>,
-    /// Whether the player's CURRENT shapeshift form satisfies the mask (the app re-pushes views
-    /// on a form change, so the color tracks live stance switches).
+    /// The current shapeshift form matches the mask; the app re-pushes on a form change.
     pub form_met: bool,
-    /// "Reagents: Light Feather" — law §3.8, `SPELL_REAGENTS` ("Reagents: ", no format slot) +
-    /// the 8 reagent slots. Rendered WHITE and wrapped; a reagent the player is short of carries
-    /// the builder's own **inline** `|cffff2020` escape (the spell builder is the one builder
-    /// that colors mid-line), so the composed string arrives paint-ready from the app.
+    /// "Reagents: Light Feather" (`SPELL_REAGENTS 0x854e54` and the eight reagent slots); the app
+    /// writes a missing reagent's inline `|cffff2020` escape.
     pub reagents: Option<String>,
-    /// "2.62% chance to dodge" — the law's line 10 (§3-CHANCE), selected by the spell's `Effect[0]`
-    /// and rendered white and unwrapped, BELOW the reagents and ABOVE the description. The
-    /// percentage is the player's own live avoidance/crit field, so the app re-pushes as it moves.
+    /// "2.62% chance to dodge" (`CHANCE_TO_DODGE 0x854e44` and its siblings, by `Effect[0]`),
+    /// from the player's live stat, which the app re-pushes as it moves.
     pub chance: Option<String>,
-    /// The $-substituted description — gold + wrapped for spells.
+    /// The `$`-substituted description.
     pub description: String,
-    /// The $-substituted AURA description (`Spell.dbc AuraDescription`) — the buff hover's
-    /// white text (byte-verified: the aura builder reads the aura column). Falls back to
-    /// `description` when empty.
+    /// The `$`-substituted `AuraDescription`, which the aura builder reads; `description` stands in
+    /// when it is empty.
     pub aura_description: String,
 }
 
 impl super::UiScript {
-    /// Store (or replace) a spell's tooltip view — the app's push half of the ask-once flow.
+    /// Store or replace a spell's view, answering its ask.
     pub fn set_spell_tooltip(&mut self, spell_id: u32, view: SpellTooltipView) {
         let mut model = self.model_mut();
         model.spell_tooltip_asks.remove(&spell_id);
         model.spell_tooltips.insert(spell_id, view);
     }
 
-    /// Drain the spell ids the renderers asked for that the store didn't have.
+    /// Drain the spell ids the renderers asked for and the store lacked.
     pub fn take_spell_tooltip_asks(&mut self) -> Vec<u32> {
         self.model_mut().spell_tooltip_asks.drain().collect()
     }
 }
 
-/// Look up the store; a miss records the ask. `pub(super)` for the talent tooltip's shared use
-/// (its display + next-rank spells ride this same ask-once channel — decision 0304).
+/// Look up a spell's view; a miss records the ask.
 pub(super) fn spell_view_of(lua: &Lua, spell_id: u32) -> Option<SpellTooltipView> {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     let v = model.spell_tooltips.get(&spell_id).cloned();
@@ -113,49 +85,35 @@ pub(super) fn spell_view_of(lua: &Lua, spell_id: u32) -> Option<SpellTooltipView
     v
 }
 
-/// The talent interleave for [`render_spell`] (decision 0304; the builder's own talent params —
-/// wow-re tooltip-content-law §3 lines 2/13): the white "Rank r/m" after the name, the red
-/// requirement lines while locked (position CONFIRMED — decision 0305's residue: matches the
-/// builder law, after the rank line), the "Next rank:" block, and the green learn hint.
+/// The talent lines [`render_spell`] interleaves (`TOOLTIP_TALENT_RANK 0x854a2c`,
+/// `TOOLTIP_TALENT_LEARN 0x8549f8`): the white "Rank r/m" after the name, the red requirements
+/// while locked, the next-rank block and the green learn hint.
 #[derive(Clone, Debug, Default)]
 pub(super) struct TalentLines {
-    /// `TOOLTIP_TALENT_RANK` = "Rank %d/%d", already filled by the caller off the player's own
-    /// string table. `None` = the table does not carry the key, and the plate shows no rank row
-    /// (decision 2045 — never an invented one).
+    /// `TOOLTIP_TALENT_RANK` ("Rank %d/%d") filled from the player's strings; `None` when they
+    /// lack the key, and no rank row shows.
     pub rank_line: Option<String>,
     pub reqs: Vec<String>,
-    /// The next rank's spell id (0 = none) — asked from the spell store when its description
-    /// hasn't landed yet, so the hover's re-enter completes the block.
+    /// The next rank's spell id, 0 for none, asked from the store while `next_desc` is missing.
     pub next_spell: u32,
     pub next_desc: Option<String>,
     pub learn: bool,
 }
 
-/// `TOOLTIP_TALENT_LEARN`'s green — the shared talent-learn green of the tooltip color table
-/// (byte-verified `0xff00ff00`, wow-re tooltip-content-law).
+/// The talent learn hint's green, `0xff00ff00`.
 const GREEN: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
-/// The unmet-requirement red — `0xc0d390 = ffff2020` (the item builder's own RED value).
+/// The unmet-requirement red, `0xffff2020` (`0xc0d390`, the item builder's red).
 const RED: [f32; 4] = [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0];
 
-/// Render one spell view — the verified law (module doc). `aura` renders the aura variant:
-/// white description, plus the caller-supplied duration-remaining line (`SetPlayerBuff` only).
-/// `talent` interleaves the talent lines ([`TalentLines`] doc).
-/// The builder's parameter vector, named as the byte law names it (`0x52e610`'s param3..param8 —
-/// wow-re `ui/scratch/tooltip-content-law.md` §3). These were three positional `bool`s at a
-/// 7-argument call site, which is exactly the shape that gets silently transposed; `Default` is the
-/// plain spell hover every caller but two wants.
+/// The spell builder's options (`0x52e610`'s parameters); `Default` is the plain spell hover.
 #[derive(Clone, Copy, Default)]
 pub(super) struct SpellRenderOpts {
-    /// Render through the AURA builder (`0x52f880`) rather than the spell builder: gold name, white
-    /// description, the dispel-class right column.
+    /// The aura builder (`0x52f880`): gold name, white description, the dispel class at right.
     pub(super) aura: bool,
-    /// `param6` showRank — the gray "Rank N" right column. `SetSpell` passes 0 (the spellbook hover
-    /// never shows it), `SetAction` passes 1.
+    /// `param6` showRank, the gray "Rank N" column: `SetSpell` passes 0, `SetAction` 1.
     pub(super) show_rank: bool,
-    /// `param5` altCaster — **one** gate suppressing **both** the totems and the reagents lines
-    /// (byte-verified at the two branch sites `0x52ed43` and `0x52f393`). Set only by
-    /// `SetTrainerService`, and only when the matched learn-wrapper slot was `LEARN_PET_SPELL`: a
-    /// pet-training service shows neither block.
+    /// `param5` altCaster, which drops the totem and reagent lines (`0x52ed43`, `0x52f393`); only
+    /// `SetTrainerService` sets it, for a `LEARN_PET_SPELL` service.
     pub(super) alt_caster: bool,
 }
 
@@ -172,23 +130,15 @@ fn render_spell(
         show_rank,
         alt_caster,
     } = opts;
-    // The name colour splits by BUILDER, byte-verified: the spell builder `0x52e610` writes its
-    // name line through `0x530270` (white), the aura builder `0x52f880` through `0x530380` — the
-    // GOLD wrapper (wow-re tooltip-content-law §3 line 1 vs §3-BUFF). SetTrackingSpell's gold,
-    // already pinned by the director's own A/B, is the same wrapper.
+    // The spell builder writes the name white (`0x530270`), the aura builder gold (`0x530380`).
     let name_color = if aura { GOLD } else { WHITE };
-    // The name line's RIGHT column splits by builder too. The spell builder's is the gray "Rank N",
-    // and it shows only when the CALLER asks (byte-verified: SetSpell passes param6=0 — the
-    // spellbook hover never shows "Rank N"; SetAction passes 1). The aura builder's is the dispel
-    // class ("Magic" on Ice Armor — §3-BUFF), and it is GOLD, not gray: a buff never shows a rank.
     let right = if aura {
         v.dispel_type.clone().map(|t| (t, GOLD))
     } else {
         v.rank.clone().filter(|_| show_rank).map(|t| (t, GRAY))
     };
     append_line(lua, this, (v.name.clone(), name_color), right, false)?;
-    // The talent head: "Rank r/m" (builder line 2, TOOLTIP_TALENT_RANK white) + the red
-    // requirement lines while locked (position CONFIRMED, decision 0305 — TalentLines doc).
+    // The talent head: the white rank line, then the red requirements while locked.
     if let Some(t) = talent {
         if let Some(rank) = &t.rank_line {
             append_line(lua, this, (rank.clone(), WHITE), None, false)?;
@@ -198,7 +148,6 @@ fn render_spell(
         }
     }
     if !aura {
-        // Cost | Range — one line, either side optional.
         match (&v.cost, &v.range) {
             (Some(c), Some(r)) => append_line(
                 lua,
@@ -211,7 +160,6 @@ fn render_spell(
             (None, Some(r)) => append_line(lua, this, (r.clone(), WHITE), None, false)?,
             (None, None) => {}
         }
-        // CastTime | Cooldown — one line; a passive spell (cast_time None) omits it whole.
         if let Some(ct) = &v.cast_time {
             match &v.cooldown {
                 Some(cd) => append_line(
@@ -224,8 +172,6 @@ fn render_spell(
                 None => append_line(lua, this, (ct.clone(), WHITE), None, false)?,
             }
         }
-        // Required tool / form (law §3.6): the equipped-item-class line first, then the stance
-        // line. Each white when met, red when not.
         if let Some(req) = &v.requires_item {
             let color = if v.item_met { WHITE } else { RED };
             append_line(lua, this, (req.clone(), color), None, false)?;
@@ -234,14 +180,12 @@ fn render_spell(
             let color = if v.form_met { WHITE } else { RED };
             append_line(lua, this, (req.clone(), color), None, false)?;
         }
-        // Reagents (law §3.8): white + wrapped, the missing entries inline-red inside the text.
-        // Suppressed wholesale by altCaster — the same gate that hides the totems block, which we
-        // have no feed for yet, so this is the only half of it that is observable here.
+        // Reagents, white and wrapped, unless altCaster drops them; the totem line it also drops
+        // is not built.
         if let Some(reagents) = v.reagents.as_ref().filter(|_| !alt_caster) {
             append_line(lua, this, (reagents.clone(), WHITE), None, true)?;
         }
-        // Chance to dodge/parry/block/crit (law line 10, §3-CHANCE) — white, NOT wrapped, and it
-        // sits here: below the reagents, above the description.
+        // The chance line, white and unwrapped, between the reagents and the description.
         if let Some(chance) = &v.chance {
             append_line(lua, this, (chance.clone(), WHITE), None, false)?;
         }
@@ -255,11 +199,9 @@ fn render_spell(
         let color = if aura { WHITE } else { GOLD };
         append_line(lua, this, (desc.clone(), color), None, true)?;
     }
-    // The talent tail: the TOOLTIP_TALENT_NEXT_RANK header (white, `0x854a10` pushed at
-    // `0x52b2cd`) over the next rank's gold description, and the green learn hint (builder
-    // line 13, TOOLTIP_TALENT_LEARN `0x8549f8` at `0x52b362`). Both are keys into the player's
-    // own string table (decision 2045); an install without them shows the description alone
-    // rather than a sentence of ours.
+    // The talent tail: the white `TOOLTIP_TALENT_NEXT_RANK` header (`0x854a10`, pushed at
+    // `0x52b2cd`) over the next rank's gold description, then the green `TOOLTIP_TALENT_LEARN`
+    // hint (`0x52b362`). Both are the player's own strings; without them the line is skipped.
     if let Some(t) = talent {
         if let Some(next) = &t.next_desc {
             if let Some(header) = crate::strings::global(lua, "TOOLTIP_TALENT_NEXT_RANK") {
@@ -273,21 +215,16 @@ fn render_spell(
             }
         }
     }
-    // The duration-remaining line (`SetPlayerBuff` only) is GOLD `0xffffd200` — the same gold as
-    // the aura title it sits under, NOT the description's white. Measured off the reporter's own
-    // 1.12.1 reference shot for B62 (`media/1530672450247856148`, Ice Armor in Wetlands): the
-    // "29 minutes remaining" glyphs read exactly `(255, 210, 0)`, pixel-identical to that shot's
-    // "Ice Armor" / "Magic" title row, while its description rows read `(255, 255, 255)`. Ours
-    // rendered it white (`media/1530672304877469696`, `(255, 255, 255)`) — that white *is* B62.
+    // The time-remaining line (`SetPlayerBuff` only) is the title's gold `0xffffd200`, not the
+    // description's white: a 1.12.1 screenshot reads (255, 210, 0) on it.
     if let Some(rem) = remaining {
         append_line(lua, this, (rem, GOLD), None, false)?;
     }
     Ok(())
 }
 
-/// The talent tooltip's entry (decision 0304 — `GameTooltip:SetTalent`'s render half): the
-/// display spell through the shared store + the talent interleave. A missing next-rank view is
-/// re-asked so the hover's re-enter completes the block.
+/// `GameTooltip:SetTalent`'s render: the talent's spell plus its talent lines; a missing next-rank
+/// view is asked for.
 pub(super) fn set_spell_with_talent(
     lua: &Lua,
     this: &Table,
@@ -313,8 +250,7 @@ pub(super) fn set_spell_with_talent(
             Some(&talent),
         )?,
         None => {
-            // The view hasn't landed: show the talent head alone (the ask is recorded; the
-            // hover's re-enter repaints complete) — the spell channel's own fallback shape.
+            // No view yet: the rank line alone until the next hover.
             if let Some(rank) = &talent.rank_line {
                 append_line(lua, this, (rank.clone(), WHITE), None, false)?;
             }
@@ -324,10 +260,7 @@ pub(super) fn set_spell_with_talent(
     Ok(())
 }
 
-/// Shared entry: clear, render (or record the ask and show nothing but the name if the caller
-/// knows one), show.
-/// The reward-spell hover: the spell by id with the quest's own name as the fallback, or an
-/// empty tooltip.
+/// The reward-spell hover: the spell, its name as the fallback, or an empty tooltip.
 fn set_reward_spell(
     lua: &Lua,
     this: &Table,
@@ -373,27 +306,16 @@ pub(super) fn set_spell_by_id(
     Ok(())
 }
 
-/// Register the spell/aura content channels into the GameTooltip kind method table.
+/// Register the spell and aura content methods on the GameTooltip method table.
 pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // GameTooltip:SetSpell(bookId, bookType) — the spellbook hover: the 1-based book slot resolves
-    // through the named book's state to a spell id.
-    //
-    // **`bookType` decides which book**, exactly like every `bookType`-taking global
-    // (`super::spellbook::book_slot`). Byte-verified in `SetSpell 0x532d10`, which is its own
-    // implementation of the same fork rather than a caller of the shared parser: arg2 → number,
-    // `- 1`, bounded `[0, 0x400)` (`0x532dd4`-`0x532df4`); arg3 → string, compared against the
-    // literal `"pet"` at `0x846960` (`0x532e13`); match takes `[4*i + 0xb6f098]` — the PET book —
-    // and sets `isPet = 1` (`0x532e1c`), everything else takes `[4*i + 0xb700f0]` (`0x532e2a`).
-    // That `isPet` then rides into `0x6e2ea0` as the cooldown BANK (`0x532e50`), the same bank
-    // split 1031 built.
-    //
-    // Before the fork, a pet-book hover indexed the PLAYER's slot list, so hovering the imp's first
-    // spell showed the player's first spell — "Attack", crit line and all (decision 1050).
+    // GameTooltip:SetSpell(bookId, bookType): the spellbook hover. `SetSpell 0x532d10` bounds the
+    // 1-based slot to `[0, 0x400)` (`0x532dd4`) and reads the pet book (`0xb6f098`) when `bookType`
+    // is "pet" (`0x532e13`), else the player's (`0xb700f0`); the pet flag also picks the cooldown
+    // bank it passes to `0x6e2ea0` (`0x532e50`).
     m.set(
         "SetSpell",
         lua.create_function(|lua, (this, book_id, book_type): (Table, u32, Value)| {
-            // The reference requires a STRING third argument and bails otherwise (`0x532dc0`'s
-            // `lua_isstring(3)` → `je` out); a non-string is therefore not "the player's book".
+            // A non-string `bookType` bails (`0x532dc0`) rather than meaning the player's book.
             let Some(book_type) = book_type.as_string().and_then(|s| s.to_str().ok()) else {
                 return Ok(());
             };
@@ -407,7 +329,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             set_spell_by_id(lua, &this, spell_id, name, SpellRenderOpts::default(), None)
         })?,
     )?;
-    // GameTooltip:SetShapeshift(index) — the stance-bar hover (the form's own spell tooltip).
+    // GameTooltip:SetShapeshift(index): the stance-bar hover, the form's spell tooltip.
     m.set(
         "SetShapeshift",
         lua.create_function(|lua, (this, index): (Table, usize)| {
@@ -421,11 +343,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             set_spell_by_id(lua, &this, spell_id, name, SpellRenderOpts::default(), None)
         })?,
     )?;
-    // GameTooltip:SetPetAction(index) — the pet-bar hover (decision 0982). Only ever reached for a
-    // SPELL slot: the reference's `PetActionButton_OnEnter` builds a token slot's tooltip inline
-    // from `tooltipName`/`tooltipSubtext` and never calls this. A slot with no spell (a token, an
-    // empty slot, an out-of-range index) is a no-op, leaving whatever was shown — the same shape
-    // as SetSpell's out-of-range.
+    // GameTooltip:SetPetAction(index): the pet-bar hover for a spell slot; the stock
+    // `PetActionButton_OnEnter` builds a token's tooltip itself (`PetActionBarFrame.lua:290`). A
+    // slot with no spell is a no-op.
     m.set(
         "SetPetAction",
         lua.create_function(|lua, (this, index): (Table, usize)| {
@@ -447,29 +367,11 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             set_spell_by_id(lua, &this, spell_id, name, SpellRenderOpts::default(), None)
         })?,
     )?;
-    // GameTooltip:SetPlayerBuff(buffIndex) — the buff-bar hover: the aura variant (white
-    // AuraDescription) + the duration-remaining line only this entry point appends (byte-verified;
-    // remaining computed live off the aura's GetTime expiry). The line's TEXT is no longer interim:
-    // §3-BUFF-TIME-FORMAT pinned `0x52fa50`'s four-arm ladder and its rounding, and
-    // `tooltip::duration_text` is it.
-    //
-    // **The argument is a 1.12 CACHE POSITION, not a filtered ordinal** — the same 0-based handle
-    // `GetPlayerBuff` returns and every `GetPlayerBuff*` sibling consumes (see
-    // `super::aura`'s header). `ref-BuffFrame.lua:105` is the pin: `GameTooltip:SetPlayerBuff(buffIndex)`
-    // where `buffIndex` came straight out of `GetPlayerBuff`, never from the button's own id.
-    //
-    // This corrects a real defect: the binding previously read a 1-based index within the
-    // sign-filtered list, so of the corpus's 21 call sites — all of which pass a cache position —
-    // every position >= 1 resolved one aura too early, no debuff was ever reachable (the sign
-    // defaulted to helpful), and `SetPlayerBuff(-1)` showed the FIRST buff instead of nothing.
-    // That last one is load-bearing: `BigWigs/Raids/Naxxramas/Loatheb.lua:260-271` feeds an
-    // unchecked `GetPlayerBuff(i, "HARMFUL")` straight in and terminates its scan on the tooltip's
-    // first line going nil.
-    //
-    // A miss (out of range, negative, empty cache) routes through the shared entry with spell id 0,
-    // exactly like SetUnitBuff's: content clears and the plate hides, never a stale tooltip left
-    // showing. Any surplus argument is ignored — `CT_BuffMod/CT_BuffFrame.lua:151` passes a filter
-    // string the reference's own binding never reads.
+    // GameTooltip:SetPlayerBuff(buffIndex): the aura variant plus the time-remaining line only
+    // this entry appends, its text `0x52fa50`'s (`tooltip::duration_text`). The argument is the
+    // 0-based cache position `GetPlayerBuff` returns (`BuffFrame.lua:105`), not a filtered
+    // ordinal. A miss, negative included, clears and hides the plate as `SetUnitBuff`'s does; a
+    // surplus argument is ignored, as in the reference.
     m.set(
         "SetPlayerBuff",
         lua.create_function(|lua, (this, index): (Table, i64)| {
@@ -484,33 +386,25 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     .and_then(|pos| model.auras.get("player").and_then(|a| a.get(pos)));
                 match hit {
                     Some(a) => {
-                        // The gate is `untilCancelled`, NOT "does this aura have a duration yet".
-                        // §3-BUFF-DURATION: `0x532b00` skips the whole duration block when the
-                        // cache record's `+0xc` is set (`532bda: 8b 46 0c` / `532bdf: 75 2d`), so
-                        // a permanent aura shows title + description and nothing more. That flag
-                        // is DBC-derived, so it is already right on the frame an aura appears —
-                        // before any `SMSG_UPDATE_AURA_DURATION` lands — which is exactly why
-                        // `AuraState::until_cancelled`'s own doc calls it a different question
-                        // from `expiration_time == 0.0`. Gating on the duration (what this did)
-                        // blanked the line for a timed aura's first frames, and hid the
-                        // reference's own "0 seconds remaining" once one lapsed.
+                        // The gate is `untilCancelled`, not a known duration: `0x532b00` skips
+                        // the line when the record's `+0xc` is set (`0x532bdf`), a DBC flag that
+                        // holds before any `SMSG_UPDATE_AURA_DURATION` lands; a lapsed aura shows
+                        // "0 seconds remaining".
                         let ms = (!a.until_cancelled).then(|| {
-                            // The reference counts integer milliseconds off GetTickCount; ours is
-                            // a float second clock, so this is the nearest millisecond to it.
+                            // The reference counts integer milliseconds off `GetTickCount`;
+                            // this rounds the float clock to the nearest one.
                             ((a.expiration_time - now) * 1000.0)
                                 .round()
                                 .clamp(0.0, f64::from(u32::MAX)) as u32
                         });
                         (a.spell_id, a.name.clone(), ms)
                     }
-                    // The miss clears rather than leaving the previous plate up — the same shape
-                    // SetUnitBuff uses, and the one Loatheb's scan depends on: it breaks its loop
-                    // when TextLeft1 reads nil, so a stale line would never let it terminate.
+                    // A miss clears: an addon scan that stops when `TextLeft1` reads nil would
+                    // otherwise never end.
                     None => (0, None, None),
                 }
             };
-            // The text is `0x52fa50`'s, over the player's own GlobalStrings — never a string of
-            // ours. Off an install the table is absent and the line simply does not render.
+            // `0x52fa50`'s text from the player's own strings; without them the line is skipped.
             let remaining = remaining_ms.and_then(|ms| {
                 let g = lua.globals();
                 super::tooltip::duration_text(ms, "SPELL_TIME_REMAINING", true, &|key| {
@@ -530,22 +424,13 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             )
         })?,
     )?;
-    // GameTooltip:SetUnitBuff(unit, index) / SetUnitDebuff(unit, index) — the target frame's aura
-    // hover: the same aura variant (white AuraDescription), WITHOUT the duration-remaining line —
-    // byte-verified, only SetPlayerBuff appends it (and no other unit has a duration on the 1.12
-    // wire anyway). The index counts within the sign-filtered list, the UnitBuff/UnitDebuff
-    // convention.
+    // GameTooltip:SetUnitBuff/SetUnitDebuff(unit, index): the aura variant with no time line; the
+    // 1-based index counts within the helpful or harmful list, as `UnitBuff` does.
     for (verb, helpful) in [("SetUnitBuff", true), ("SetUnitDebuff", false)] {
         m.set(
             verb,
-            // `index` is `Value`, not `i64`, and that is a fidelity fix rather than laxity — the
-            // same correction `SetTexture` already carries. A C binding reads what it wants off
-            // the Lua stack: `lua_tonumber` on nil yields 0, which finds no aura and shows
-            // nothing. Typing it `i64` made us RAISE on a call the real client accepts silently.
-            //
-            // Found by the use-probe: `CT_AssistFrameDebuff1:OnEnter` calls
-            // `SetUnitDebuff(unit, this:GetID())` and the id is nil on a frame CT_UnitFrames
-            // created without one. It only fires on hover, so nothing before the probe saw it.
+            // `index` is a `Value`: the reference's `lua_tonumber` reads nil as 0, which finds no
+            // aura, where an `i64` would raise.
             lua.create_function(move |lua, (this, token, index): (Table, String, Value)| {
                 let index = match &index {
                     Value::Integer(i) => *i,
@@ -566,9 +451,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                         .and_then(|a| a.iter().filter(|a| a.helpful == helpful).nth(idx))
                         .map(|a| (a.spell_id, a.name.clone()))
                 };
-                // A miss (index past the list, unknown token) still routes through the shared
-                // entry with spell id 0: content clears and the empty plate hides — never a
-                // stale previous tooltip left showing. Id 0 records no ask.
+                // A miss goes through with spell id 0, which clears and hides the plate and
+                // records no ask.
                 let (spell_id, name) = hit.unwrap_or((0, None));
                 set_spell_by_id(
                     lua,
@@ -584,13 +468,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             })?,
         )?;
     }
-    // GameTooltip:SetTrackingSpell() — the minimap tracking icon's hover: NAME gold over a white
-    // (aura-)description, pinned by the director's reference A/B (2026-07-20: "Find Minerals"
-    // gold over white "Finding Minerals."). That is just the AURA builder's shape — its name line
-    // rides the gold wrapper `0x530380` too — so this is no longer a one-off; `0x532c50`'s body
-    // still isn't carved, so carve it in wow-re before extending BEYOND that shape. No
-    // duration-remaining line (only SetPlayerBuff appends one), and no tracking active clears +
-    // hides, like the SetUnitBuff miss path.
+    // GameTooltip:SetTrackingSpell(): the tracking icon's hover, the name gold over the white
+    // aura description, as the reference shows "Find Minerals" and as the aura builder's gold
+    // wrapper `0x530380` writes it; `0x532c50` itself is untraced. No tracking clears and hides.
     m.set(
         "SetTrackingSpell",
         lua.create_function(|lua, this: Table| {
@@ -621,8 +501,7 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     }
                 }
                 None => {
-                    // The view hasn't landed (ask recorded; the re-enter repaints): the name
-                    // alone, in the same gold.
+                    // No view yet: the name alone, gold.
                     if let Some(name) = fallback_name {
                         append_line(lua, &this, (name, GOLD), None, false)?;
                     }
@@ -632,21 +511,9 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // GameTooltip:SetAction(slot) — the action-bar hover: pure delegation by payload kind
-    // (`0x5322a0`, byte-verified: SPELL 0x00 → the spell builder `0x52e610`, ITEM 0x80 → the item
-    // builder `0x52b650`, MACRO 0x40 → `0x52b040`; wow-re `ui.md`'s SetAction dispatch).
-    //
-    // The MACRO arm is the reference's whole `0x52b040`: fetch the record (`0x4f0f40`), and either
-    // hide (no record) or render ONE line — the macro's NAME (`rec+0x24`) — through the
-    // single-coloured-line wrapper `0x5303b0` in the "normal" colour `0xc0cf60`, which is WHITE
-    // (`0xffffffff`, VERIFIED never rewritten — wow-re `tooltip-content-law.md` §1's colour
-    // table). Not the spell title's gold, and nothing about the bound spell: 1.12 has no
-    // `#showtooltip`. This arm was a `_ => Ok(())` left from before 0983 shipped macros, which is
-    // why a macro on the bar hovered to nothing (the director, 2026-08-27, after 1636).
-    // GameTooltip:SetQuestRewardSpell() / SetQuestLogRewardSpell() — the hover of the reward
-    // slot stock marks `rewardType = "spell"` (QuestFrameTemplates.xml:150, QuestLogFrame.xml:115;
-    // bindings 0x535bb0 / 0x535c60, self only, 0 returns): the quest's reward spell by id through
-    // the spell renderer, an empty tooltip when the quest rewards none.
+    // GameTooltip:SetQuestRewardSpell() / SetQuestLogRewardSpell() (`0x535bb0`, `0x535c60`): the
+    // hover of a reward slot whose `rewardType` is "spell" (`QuestFrameTemplates.xml:150`,
+    // `QuestLogFrame.xml:115`), the quest's reward spell or an empty tooltip.
     m.set(
         "SetQuestRewardSpell",
         lua.create_function(|lua, this: Table| {
@@ -674,6 +541,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             set_reward_spell(lua, &this, id)
         })?,
     )?;
+    // GameTooltip:SetAction(slot): the action-bar hover by payload kind (`0x5322a0`): a spell
+    // (0x00) to the spell builder `0x52e610`, an item (0x80) to the item builder `0x52b650`, a
+    // macro (0x40) to `0x52b040`, which fetches it (`0x4f0f40`) and renders only its name, white
+    // (`0x5303b0` in colour `0xc0cf60`), or hides with none; 1.12 has no `#showtooltip`.
     m.set(
         "SetAction",
         lua.create_function(|lua, (this, slot): (Table, u32)| {
@@ -695,7 +566,6 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     None,
                 ),
                 0x80 => {
-                    // Route through the shared item renderer (the id-keyed entry).
                     let f: mlua::Function = this.get("BenillaSetItemById")?;
                     f.call::<()>((this.clone(), a.action))
                 }
@@ -704,8 +574,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                     let name = {
                         let mut model = lua.app_data_mut::<Model>().expect("model app_data");
                         clear_content(&mut model, h);
-                        // The same 1..36 index lookup `GetActionText` and the bar's icon arm
-                        // make, so the three can never disagree about which macro a slot holds.
+                        // The same 1..36 lookup as `GetActionText` and the bar icon, so the
+                        // three agree on a slot's macro.
                         model.macros.get(a.action as usize).map(|m| m.name.clone())
                     };
                     fire_cleared(lua, h);
@@ -720,19 +590,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GameTooltip:SetTrainerService(index) — the trainer detail-icon hover (ref
-    // `Blizzard_TrainerUI.xml:452`, whose OnEnter is SetOwner(this,"ANCHOR_RIGHT") +
-    // SetTrainerService(ClassTrainerFrame.selectedService) + Show(); the LIST ROWS carry no tooltip
-    // at all). Byte-verified whole in wow-re `ui/scratch/trainer-service-tooltip-law.md`.
-    //
-    // The binding is a **selector, not a renderer**: `0x5338b0` emits no line of its own (verified
-    // negative — none of the four AddLine helpers appears in its extent) and hands one of the two
-    // shared builders a subject. The subject is decided app-side, because the law reads `Spell.dbc`
-    // fields the engine cannot see, and arrives pre-resolved as `TrainerService::tooltip`. All this
-    // does is pick the renderer — which is exactly what the reference binding does.
-    //
-    // `index` is a **VISIBLE** row index (headers interleave), resolved through the same mapping
-    // every other trainer getter uses; a header row is a no-op.
+    // GameTooltip:SetTrainerService(index): the trainer detail icon's hover
+    // (`Blizzard_TrainerUI.xml:452`); list rows have no tooltip. `0x5338b0` writes no line itself
+    // and hands a shared builder the subject the app resolved (`TrainerService::tooltip`). `index`
+    // is a visible row, headers included; a header is a no-op.
     m.set(
         "SetTrainerService",
         lua.create_function(|lua, (this, index): (Table, usize)| {
@@ -744,9 +605,8 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
                 }
             };
             match subject {
-                // Route through the shared item renderer, the way the reference routes into
-                // `0x52b650`. No fallback name: an item id of 0 or a template still in flight
-                // renders an EMPTY tooltip, which is the builder's own early-out.
+                // The item builder (`0x52b650`), with no fallback name: id 0 or a template in
+                // flight renders empty, the builder's own early-out.
                 TrainerTooltip::Item(item_id) => {
                     let f: mlua::Function = this.get("BenillaSetItemById")?;
                     f.call::<()>((this.clone(), item_id))
@@ -768,17 +628,10 @@ pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // GameTooltip:SetCraftSpell(craftIndex) — the Craft window's detail-icon hover (ref
-    // `CraftIcon`'s OnEnter, `Blizzard_CraftUI.xml:566`). `SetTrainerService`'s structural twin and
-    // its law's opposite (wow-re `ui/scratch/trainer-service-tooltip-law.md` §4.1): a selector into
-    // the same two shared builders, deciding on the RECIPE's own effect columns rather than a
-    // taught spell's attributes. The subject arrives pre-resolved as `CraftRecipe::tooltip`.
-    //
-    // This replaced a v1 two-line "name white, description gold" render. That was wrong in both
-    // halves: `0x533e90` funnels into `0x52e610`/`0x52b650` like every other content binding, so
-    // two lines were eight-plus short, and on a `LEARN_SPELL` or `CREATE_ITEM` recipe it was
-    // describing the wrong subject entirely. `craft_index` is a raw recipe position — the Craft
-    // window is FLAT, with no headers to interleave (unlike the tradeskill list).
+    // GameTooltip:SetCraftSpell(craftIndex): the craft detail icon's hover
+    // (`Blizzard_CraftUI.xml:566`). `SetCraftSpell 0x533e90` hands a shared builder the subject the
+    // app resolved from the recipe's own effects (`CraftRecipe::tooltip`). `craftIndex` is a plain
+    // recipe position: the craft list has no headers.
     m.set(
         "SetCraftSpell",
         lua.create_function(|lua, (this, craft_index): (Table, usize)| {
diff --git a/crates/benilla-ui/src/script/tooltip_unit.rs b/crates/benilla-ui/src/script/tooltip_unit.rs
index 4b39b485..d22b8a78 100644
--- a/crates/benilla-ui/src/script/tooltip_unit.rs
+++ b/crates/benilla-ui/src/script/tooltip_unit.rs
@@ -1,40 +1,12 @@
-//! The engine **unit tooltip builder** (decision 0274 P3) — the byte-verified line law of
-//! `0x529fe0` (wow-re `ui/scratch/tooltip-content-law.md`, the 0276 fold-back):
-//!
-//! - NAME (gold — FrameXML recolors `TextLeft1` by reaction on `UPDATE_MOUSEOVER_UNIT`, exactly
-//!   like the reference's `GameTooltip_UnitColor`; the guild line is likewise FrameXML's and
-//!   joins when guild data streams). A name still in flight reads `UNKNOWNOBJECT`, never an
-//!   empty line — the builder's name read is `0x609210`, the same resolver `UnitName` uses, and
-//!   its miss tail is the same string (decisions 2002/2040);
-//! - the creature SUBTITLE ("Stable Master") — white;
-//! - the LEVEL line, filled from three slots into one of the four `TOOLTIP_UNIT_LEVEL*` templates
-//!   the player's own `GlobalStrings.lua` carries (decision 2045 — the keys are the builder's,
-//!   read off `0x52a622`/`0x52a64d`/`0x52a682`/`0x52a6ac`, never matched on their English):
-//!   level text (`"??"` for a world boss, a much-higher hostile, or level ≤ 0 — the hostile
-//!   delta is INTERIM at +10 pending a byte pin of the comparison), the class slot (the creature
-//!   TYPE word for hostile/neutral creatures, `"Race Class"` for players, `CORPSE` when dead),
-//!   and the type slot (the rank key table `{"", ELITE, ELITE, BOSS, ""}`; `PLAYER` for players);
-//! - the FACTION NAME ("Stormwind", white) — the builder-tail block `0x52a7a0..` the law's §2
-//!   order originally omitted: the app resolves it (`faction_name`), every gate applied;
-//! - "PvP" (white) · "Skinnable" (**red**) · "Civilian" (green, `0x612550`: PvP-flagged +
-//!   query-civilian + HOSTILE + GREY/trivial — the dishonorable-kill warning) · "Leader"
-//!   (white, `0x6125c0`: PvP-flagged + query racial_leader);
-//! - health on the attached status bar (`<name>StatusBar`, the template child below the plate),
-//!   refreshed by every `set_unit` push for the live token — the byte law's HEALTH watcher.
-//!
-//! The world mouseover drives this through [`super::UiScript::world_tooltip_unit`] (the engine
-//! shows the tooltip at the default anchor by firing `OnTooltipSetDefaultAnchor`, renders, and
-//! fires `UPDATE_MOUSEOVER_UNIT` for the Lua recolor) and [`super::UiScript::world_tooltip_fade`]
-//! (the byte law ARMS a fade on hover loss, not an instant hide). Unit-frame hovers call the
-//! same `SetUnit` from Lua.
+//! The engine unit tooltip, in `0x529fe0`'s line order: the name (gold; FrameXML recolours it by
+//! reaction), the creature subtitle, the level line, the faction name, then "PvP", "Skinnable",
+//! "Civilian" and "Leader", with health on the `<name>StatusBar` child. The world mouseover drives
+//! it through [`super::UiScript::world_tooltip_unit`]; unit-frame hovers call `SetUnit` from Lua.
 
 use mlua::{Lua, Table};
 
 use super::object::frame_handle_of;
 use super::tooltip::{append_line, clear_content, fire_cleared, show_or_hide_empty, tip_mut};
-// The grey band + trivial/GREY check (`0x5f0700`, the CIVILIAN line's last gate: a green-or-
-// better con never warns of a dishonorable kill) and the "??" gate live in one shared home
-// (`unit.rs`), alongside `UnitLevel`'s −1 return and the `GetQuestGreenRange` binding.
 use super::unit::{is_civilian_kill, level_reads_unknown, unknownobject};
 use super::{KindState, Model, UnitState};
 use crate::layout::{Anchor, Point};
@@ -44,35 +16,29 @@ use crate::widget::FrameHandle;
 const WHITE: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
 const GREEN: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
 const RED: [f32; 4] = [1.0, 32.0 / 255.0, 32.0 / 255.0, 1.0];
-/// `0xc0d420` = `0xff40c040` — the satisfiable-lock green (see [`TooltipTint::LockOpen`]).
+/// `0xc0d420` = `0xff40c040`, the satisfiable-lock green.
 const LOCK_OPEN: [f32; 4] = [64.0 / 255.0, 192.0 / 255.0, 64.0 / 255.0, 1.0];
-/// Unit names render gold (byte-verified `0xffffd200`); FrameXML recolors line 1 by reaction.
+/// `0xffffd200`, the unit name's colour until FrameXML recolours it by reaction.
 const GOLD: [f32; 4] = [1.0, 210.0 / 255.0, 0.0, 1.0];
 
-/// A GameObject tooltip line's colour, as the builder `0x52aa20` picks it (decision 0756). The
-/// app half decides *which* line gets which tint from the lock law; this enum is only the
-/// crate-boundary spelling, so the colour constants stay private to the UI engine.
+/// A GameObject tooltip line's colour, as the builder `0x52aa20` picks it; the app picks the tint
+/// for each line.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TooltipTint {
-    /// `0xc0cf60` — the requirement line's normal colour (the key-item "Requires %s").
+    /// `0xc0cf60`: a requirement line's normal colour (the key item's "Requires %s").
     White,
-    /// The "Locked" line's UNMET colour `0xc0d3a8` = `0xffff2020`, and the unknown-skill
-    /// "Requires %s" (whose own red is `0xffff0000` — a difference of 32/255 in G and B that no
-    /// eye resolves, so one slot serves both).
+    /// `0xc0d3a8` = `0xffff2020`, the unmet "Locked" line. Deviation: the unknown-skill
+    /// "Requires %s" shares it, though its reference red is `0xffff0000`, because a 32/255
+    /// difference in G and B does not show.
     Red,
-    /// The "Locked" line when the lock **is** satisfiable — `0xc0d420` = `0xff40c040`
-    /// (64,192,64). Deliberately NOT the tooltip's ordinary green `0xc0d3ac` = `0xff00ff00`: this
-    /// is the second rung of the skill-difficulty ramp `0x529fa0` (grey/green/yellow/orange/red,
-    /// static-init writers at `0x5290d0` &c.), which the lock line borrows wholesale, and it is a
-    /// visibly softer green than the one every other tooltip line uses.
+    /// The satisfiable "Locked" line: `0xc0d420` = `0xff40c040`, the green rung of the
+    /// skill-difficulty ramp `0x529fa0`, not the ordinary green `0xc0d3ac` = `0xff00ff00`.
     LockOpen,
 }
 
-/// The rank word's GlobalString **key** — byte-verified `0x854158[]`, the pointer table the
-/// builder indexes by rank at `0x52a5bd`/`0x52a5d4`. Its entries are key names, not words: index 0
-/// and 4 are the pre-seeded empty string `0x882748`, 1 and 2 are both `ELITE` (rare-elite prints
-/// ELITE, rare prints nothing — there is no distinct "Rare Elite" word in 1.12's builder), 3 is
-/// `BOSS`.
+/// The rank word's GlobalString key, from the builder's table `0x854158` (indexed at `0x52a5bd`
+/// and `0x52a5d4`): ranks 1 and 2 (elite, rare elite) are `ELITE`, 3 is `BOSS`, and 0 and 4 (rare)
+/// are the empty string `0x882748`.
 fn rank_key(rank: u32) -> Option<&'static str> {
     match rank {
         1 | 2 => Some("ELITE"),
@@ -81,31 +47,19 @@ fn rank_key(rank: u32) -> Option<&'static str> {
     }
 }
 
-/// The level line — three slots over the four `TOOLTIP_UNIT_LEVEL*` templates, each resolved off
-/// the player's own `GlobalStrings.lua` (decision 2045). The keys are the builder's own, pushed at
-/// `0x52a622` (`_CLASS_TYPE`), `0x52a64d` (`_CLASS`), `0x52a682` (`_TYPE`) and `0x52a6ac` (the
-/// bare one) — which matters, because `TOOLTIP_UNIT_LEVEL_CLASS`'s enUS "Level %s %s" is also the
-/// wording of `FRIENDS_LEVEL_TEMPLATE`, `UNIT_TYPE_LEVEL_TEMPLATE` and `CHARACTER_SELECT_INFO`,
-/// and the bare one collides with `ITEM_LEVEL`, `LEVEL_GAINED` and `UNIT_LEVEL_TEMPLATE`. Seven
-/// wrong keys are reachable by matching the English here; none by reading the builder.
-///
-/// `None` = the install's string table carries no template for the slot combination in hand, and
-/// the plate shows no level row rather than a composed one.
+/// The level line: level, class and type slots in one of the four `TOOLTIP_UNIT_LEVEL*`
+/// GlobalStrings, keyed as the builder keys them (`0x52a622` `_CLASS_TYPE`, `0x52a64d` `_CLASS`,
+/// `0x52a682` `_TYPE`, `0x52a6ac` bare), never by their English, which other keys share. `None`
+/// when the install has no template for the combination, and then no row shows.
 fn level_line(lua: &Lua, u: &UnitState, player_level: u32) -> Option<String> {
     let get = |key: &str| crate::strings::global(lua, key);
-    // The "??" gate, byte-pinned (0x529fe0 §2-LEVEL): much-higher HOSTILE — internal reaction
-    // ≤ 1 = hated/hostile = UnitReaction ≤ 2 on our 1..8 API scale (the UnitIsEnemy mapping) —
-    // with playerLevel ≤ targetLevel−10; OR WorldBoss; OR level ≤ 0. Players NEVER read "??".
-    // Shared with `UnitLevel`'s −1 return, so the tooltip and the target frame can never
-    // disagree on who reads "??" ([`level_reads_unknown`]).
+    // "??" by the gate `UnitLevel`'s -1 shares (`0x529fe0`), so tooltip and target frame agree.
     let level_text = if level_reads_unknown(u, player_level) {
         "??".to_string()
     } else {
         u.level.to_string()
     };
-    // The class slot: "Race Class" for players; the creature TYPE word for hostile/neutral
-    // creatures (a friendly creature shows none — the byte law's hostile/neutral-only gate);
-    // "Corpse" when dead.
+    // `CORPSE` when dead, "Race Class" for a player, the creature type only if hostile or neutral.
     let class_slot = if u.dead {
         get("CORPSE")
     } else if u.is_player {
@@ -120,7 +74,6 @@ fn level_line(lua: &Lua, u: &UnitState, player_level: u32) -> Option<String> {
     } else {
         None
     };
-    // The type slot: the rank word, or PLAYER for players.
     let type_slot = if u.is_player {
         get("PLAYER")
     } else {
@@ -160,23 +113,13 @@ fn render_unit(lua: &Lua, this: &Table, token: &str) -> mlua::Result<bool> {
     }
     fire_cleared(lua, h);
     let Some(u) = unit else {
-        // No unit: drop the live token and leave the tooltip hidden-empty.
         set_live_token(lua, h, None);
         show_or_hide_empty(lua, h);
         return Ok(false);
     };
-    // The NAME line. A unit whose name query has not answered yet does NOT title an empty plate:
-    // the builder resolves the name through `CGUnit_C::GetUnitName 0x609210` (`0x52a187`), and
-    // every one of that function's misses — a creature whose `creaturecache.wdb` record
-    // (`CGUnit+0xb30`) is still null, a pet whose `petnamecache.wdb` row is absent or stale, a
-    // player row `namecache.wdb` has not answered — falls to the SAME
-    // `FrameScript_GetText("UNKNOWNOBJECT")` tail `UnitName` falls to. One seam, one resolver
-    // ([`unknownobject`], decisions 2002/2040), so the verb and the plate can never disagree.
-    //
-    // The builder has no counterpart to `UnitName`'s two nils: the `"player"` fast path is the
-    // *binding's* (`0x517083`, before any resolve), and a token resolving to GUID 0 never reaches
-    // a builder at all — the entry gate `0x468460(typemask 8)` hands back no object, `SetUnit`
-    // answers nil and no plate is drawn (the `unit` early-return above).
+    // The name: `CGUnit_C::GetUnitName` `0x609210` (`0x52a187`), whose every miss falls to
+    // `UNKNOWNOBJECT`, as `UnitName`'s does. A token with no object never reaches the builder
+    // (`0x468460`): no plate, and `SetUnit` answers nil.
     let title = match &u.name {
         Some(n) => n.clone(),
         None => unknownobject(lua)?.to_str()?.to_string(),
@@ -188,8 +131,7 @@ fn render_unit(lua: &Lua, this: &Table, token: &str) -> mlua::Result<bool> {
     if let Some(level) = level_line(lua, &u, player_level) {
         append_line(lua, this, (level, WHITE), None, false)?;
     }
-    // The faction-name line ("Stormwind", white) sits between the level line and "PvP" — the
-    // builder-tail block at `0x52a7a0`. The app resolved every gate into `faction_name`.
+    // The faction name, between the level line and "PvP" (`0x52a7a0`); the app applied its gates.
     if let Some(faction) = &u.faction_name {
         append_line(lua, this, (faction.clone(), WHITE), None, false)?;
     }
@@ -199,15 +141,11 @@ fn render_unit(lua: &Lua, this: &Table, token: &str) -> mlua::Result<bool> {
     if u.skinnable {
         append_line(lua, this, ("Skinnable".into(), RED), None, false)?;
     }
-    // CIVILIAN (green) — `0x612550`, whole: the unit's PvP bit + the query civilian flag + the
-    // unit is HOSTILE to the player (UnitReaction ≤ 2 — internal reaction < 2) + the kill would
-    // be GREY/trivial. PVP_RANK_CIVILIAN = "Civilian" (extracted GlobalStrings). The predicate
-    // itself lives in `unit` because `UnitPVPName` gates its own civilian arm on the same call.
+    // "Civilian" (`0x612550`): PvP-flagged, a civilian, hostile, and grey to kill (`0x5f0700`).
     if is_civilian_kill(&u, player_level) {
         append_line(lua, this, ("Civilian".into(), GREEN), None, false)?;
     }
-    // LEADER (white) — `0x6125c0`: the PvP bit + the query racial_leader flag, no other gate.
-    // PVP_RANK_LEADER = "Leader" (extracted GlobalStrings).
+    // "Leader" (`0x6125c0`): PvP-flagged and a racial leader, no other gate.
     if u.racial_leader && u.pvp {
         append_line(lua, this, ("Leader".into(), WHITE), None, false)?;
     }
@@ -227,7 +165,7 @@ fn set_world_owned(lua: &Lua, h: FrameHandle) {
     }
 }
 
-/// Remember (or drop) the tooltip's live unit token — the health watcher's key.
+/// Remember (or drop) the tooltip's live unit token, the health watcher's key.
 fn set_live_token(lua: &Lua, h: FrameHandle, token: Option<String>) {
     let mut model = lua.app_data_mut::<Model>().expect("model app_data");
     if let Some(f) = model.arena.frame_mut(h) {
@@ -237,8 +175,8 @@ fn set_live_token(lua: &Lua, h: FrameHandle, token: Option<String>) {
     }
 }
 
-/// Drive the `<name>StatusBar` child from a unit snapshot (`None` hides it) — the engine pushes
-/// health, FrameXML's `HealthBar_OnValueChanged` colors the fill.
+/// Drive the `<name>StatusBar` child from a unit snapshot (`None` hides it); FrameXML's
+/// `HealthBar_OnValueChanged` colours the fill.
 fn update_bar(lua: &Lua, h: FrameHandle, unit: Option<&UnitState>) {
     let bar = {
         let model = lua.app_data_mut::<Model>().expect("model app_data");
@@ -284,19 +222,17 @@ fn update_bar(lua: &Lua, h: FrameHandle, unit: Option<&UnitState>) {
         ) {
             lua.app_data_mut::<Model>()
                 .expect("model app_data")
-                .errors
-                .push(e.to_string());
+                .record_script_error(e.to_string());
         }
     }
 }
 
-/// The `set_unit` push hook: a fresh snapshot for the tooltip's LIVE token re-drives the health
-/// bar (the byte law's HEALTH UpdateField watcher — the bar tracks without a line rebuild).
+/// A `set_unit` push for a tooltip's live token updates its health bar without rebuilding the
+/// lines, as the reference's HEALTH field watcher does.
 pub(super) fn on_unit_push(lua: &Lua, token: &str) {
     let hits: Vec<FrameHandle> = {
         let model = lua.app_data_mut::<Model>().expect("model app_data");
-        // The arena's tooltip registry (1634), gated by the resolve's roster exactly as the walk
-        // it replaces was — `update_bar` writes layout.
+        // Registered frames only, as `update_bar` writes layout.
         model
             .arena
             .tooltip_kinds()
@@ -321,11 +257,9 @@ pub(super) fn on_unit_push(lua: &Lua, token: &str) {
 }
 
 impl super::UiScript {
-    /// Show the world-mouseover unit tooltip (the engine-driven flow the byte law describes):
-    /// fire `OnTooltipSetDefaultAnchor` (FrameXML seats the plate at the default corner), render
-    /// `token`'s snapshot, fire `UPDATE_MOUSEOVER_UNIT` (FrameXML recolors the name line by
-    /// reaction). Call on hover-target CHANGE — the health bar tracks pushes in between; a
-    /// re-show mid-fade resurrects at full alpha. `false` = no tooltip frame / no such unit.
+    /// Show the world-mouseover unit tooltip: fire `OnTooltipSetDefaultAnchor`, render `token`,
+    /// fire `UPDATE_MOUSEOVER_UNIT`. Call on a hover-target change; a re-show mid-fade returns to
+    /// full alpha. `false` when there is no tooltip frame or no such unit.
     pub fn world_tooltip_unit(&mut self, token: &str) -> bool {
         let h = {
             let mut model = self.model_mut();
@@ -357,7 +291,6 @@ impl super::UiScript {
         };
         if shown {
             set_world_owned(&self.lua, h);
-            // Cancel any running fade at full alpha (a re-hover resurrects).
             let mut model = self.model_mut();
             if let Some(f) = model.arena.frame_mut(h) {
                 if let KindState::Tooltip(t) = &mut f.kind_state {
@@ -372,25 +305,12 @@ impl super::UiScript {
         shown
     }
 
-    /// Show the world-mouseover GAMEOBJECT tooltip — the byte-verified GO builder `0x52aa20`
-    /// (decisions 0276 / **0756**): the NAME (gold) followed by the lock lines the caller
-    /// resolved, each with its own tint.
-    ///
-    /// **The anchor FORKS per object — it is not uniform** (decision 0766, correcting 0756). The
-    /// publisher's GameObject leg calls the picked object's `[obj->vtbl+0x5c]` and branches:
-    ///
-    /// - **true** (`0x492a01`) → `0x52ffe0(owner, 6, 0, 0)` — anchor-state **6**, the *cursor*
-    ///   anchor. Corroborated by the loss path: `0x530ae0` hides an anchor-state-6 tooltip
-    ///   **immediately** instead of arming the fade, which is how a pointer-following label behaves.
-    /// - **false** (`0x492a42`) → no `SetOwner` at all; the plate keeps its default corner seat.
-    ///
-    /// The **unit** leg (`0x492983`) never consults `+0x5c` — units are always corner-seated, which
-    /// is why the fork went unnoticed when 0756 made every GameObject corner-seated too. `cursor`
-    /// carries the caller's verdict: `Some(ui_xy)` = the cursor arm (and then
-    /// [`Self::world_tooltip_move`] follows the pointer), `None` = the corner.
-    ///
-    /// Same fade lifecycle as the unit flow (no `UPDATE_MOUSEOVER_UNIT` — that recolor is the
-    /// unit line's).
+    /// Show the world-mouseover GameObject tooltip (builder `0x52aa20`): the name in gold, then
+    /// the caller's lock lines. The anchor forks on the object's `[vtbl+0x5c]`: true (`0x492a01`)
+    /// seats it at the cursor, anchor state 6 (`0x52ffe0(owner, 6, 0, 0)`); false (`0x492a42`)
+    /// keeps the default corner, as units (`0x492983`) always do. `cursor` is that verdict, and
+    /// [`Self::world_tooltip_move`] follows a cursor-seated plate. Hover loss arms the unit flow's
+    /// fade, where the reference's loss path (`0x530ae0`) hides an anchor-state-6 plate at once.
     pub fn world_tooltip_gameobject(
         &mut self,
         name: &str,
@@ -409,31 +329,15 @@ impl super::UiScript {
             (h, id, root, root_id)
         };
         match cursor {
-            // The cursor arm: seated centred above the pointer, clamped by the tooltip frame's own
-            // flag. Compare-then-touch so a still pointer never re-layouts.
+            // The cursor arm: centred above the pointer; compare-then-touch, so a still pointer
+            // never re-layouts.
             Some((ui_x, ui_y)) => {
                 let mut model = self.model_mut();
-                // **The OWNER, which this arm used to skip** (decision 2255). The
-                // reference's cursor arm is `0x492a01 → 0x52ffe0(owner, 6, 0, 0)` — the SetOwner
-                // CORE, not a bare re-anchor — and the core's `0x53000c` stores that owner into
-                // `+0x314`. Every OTHER world plate we build reaches an owner by accident: the
-                // corner arm below and the unit flow both fire `OnTooltipSetDefaultAnchor`, whose
-                // FrameXML handler calls `GameTooltip:SetOwner(UIParent, …)` in Lua. This arm
-                // fires nothing, so `+0x314` stayed NULL on exactly the cursor-seated objects —
-                // a signpost, a mailbox, every GENERIC(5).
-                //
-                // A null owner is not cosmetic, because **`:Show()` is an existence gate**:
-                // `0x530a80` shows only when `+0x314` AND `+0x31c` are both non-zero, and
-                // otherwise takes the effective-hide `0x530a60` — which we implement faithfully
-                // (see the `Show` verb). So any Lua that reached `GameTooltip:Show()` while one of
-                // these plates was up HID IT, and hid it through our own correct code.
-                //
-                // That is not hypothetical: `!Questie` hooks GameTooltip's `OnShow` at
-                // PLAYER_LOGIN (`Questie:hookTooltip`, installed because stock GameTooltip has no
-                // OnShow of its own) and its handler ends in `GameTooltip:Show()`. So the plate's
-                // own show event hid the plate, ~26 ms after the engine built it, on every
-                // signpost, for the whole session — the director's report. The reference cannot
-                // reach that state: `0x492a01` writes the owner before the plate is ever shown.
+                // The owner: this arm is the SetOwner core (`0x52ffe0`), which stores it at
+                // `+0x314` (`0x53000c`); the other arms get theirs from FrameXML's
+                // `OnTooltipSetDefaultAnchor`. Without one, any Lua `GameTooltip:Show()` hides the
+                // plate: `0x530a80` shows only when `+0x314` and `+0x31c` are both set, else it
+                // takes `0x530a60`.
                 if let Ok(t) = tip_mut(&mut model, h) {
                     t.owner = Some(root);
                 }
@@ -446,7 +350,7 @@ impl super::UiScript {
                     model.touch_layout();
                 }
             }
-            // The corner arm: the same default-anchor handler the unit flow fires.
+            // The corner arm: the default-anchor handler the unit flow fires too.
             None => {
                 if let Err(e) = super::event::fire_widget_handler(
                     &self.lua,
@@ -501,13 +405,10 @@ impl super::UiScript {
         true
     }
 
-    /// Show the minimap BLIP tooltip — a landmark's `AreaPOI` name or a quest-dot NPC's name,
-    /// one GOLD line (the reference's engine SetText gold; a cross-interior dot renders FAINT
-    /// gold — the byte law's `|cffb0b0b0` wrap modulating the gold base, director-matched),
-    /// seated centred ABOVE the cursor: the tooltip's BOTTOM at the given UI-space point. The
-    /// plate FOLLOWS the pointer — `Self::minimap_tooltip_move` re-seats it as the cursor
-    /// drifts within one blip. Same world-owned fade lifecycle as the mouseover tooltip:
-    /// hover loss arms [`Self::world_tooltip_fade`].
+    /// Show the minimap blip tooltip (an `AreaPOI` or quest-dot name): one gold line, faint gold
+    /// for a cross-interior dot, its bottom at the given UI point above the cursor.
+    /// [`Self::world_tooltip_move`] follows the pointer, and hover loss arms
+    /// [`Self::world_tooltip_fade`].
     pub fn minimap_tooltip(&mut self, text: &str, ui_x: f32, ui_y: f32, grey: bool) -> bool {
         let (h, id, root_id) = {
             let mut model = self.model_mut();
@@ -531,13 +432,10 @@ impl super::UiScript {
             let mut model = self.model_mut();
             clear_content(&mut model, h);
             let input = model.layout_inputs.entry(h).or_default();
-            // Anchor only — the screen clamp (G flags bit4: a cursor-seated plate near the window
-            // edge slides back in instead of clipping, director's report at the screen-right
-            // minimap) is the tooltip FRAME's own flag (`Frame::clamped_to_screen`), synced with
-            // live extents at every resolve.
+            // Anchor only: the frame's own clamp flag (`Frame::clamped_to_screen`, G flags bit 4)
+            // slides a plate near the window edge back on screen.
             let new = Anchor::new(Point::Bottom, root_id, Point::BottomLeft, ui_x, ui_y);
-            // Compare-then-touch: a still cursor re-seats the plate at the same point every
-            // frame — tier 1 of the layout gate stays quiet unless the pointer actually moved.
+            // Compare-then-touch, so a still cursor does not dirty the layout.
             let same =
                 input.anchors.len() == 1 && super::object::anchor_bits_eq(&input.anchors[0], &new);
             if !same {
@@ -546,10 +444,7 @@ impl super::UiScript {
             }
         }
         fire_cleared(&self.lua, h);
-        // The blip name renders GOLD like the reference (the engine tooltip's SetText line —
-        // the same 0xffffd200 the unit-name line uses); a cross-interior entry renders the
-        // byte law's `|cffb0b0b0` wrap MODULATING that gold — faint gold, not flat grey
-        // (director-matched against the reference, 2026-07-13).
+        // A cross-interior entry's `|cffb0b0b0` wrap modulates the gold: faint gold, not grey.
         let dim = 0xb0 as f32 / 255.0;
         let color = if grey {
             [GOLD[0] * dim, GOLD[1] * dim, GOLD[2] * dim, 1.0]
@@ -575,9 +470,7 @@ impl super::UiScript {
         true
     }
 
-    /// Re-seat the showing cursor-anchored tooltip at a new pointer point (the follow half of
-    /// [`Self::minimap_tooltip`] and [`Self::world_tooltip_gameobject`]): anchor-only — no
-    /// content rebuild, no fade churn. No-op when the tooltip isn't the world-owned shown plate.
+    /// Re-seat the shown world-owned tooltip at a new pointer point, anchor only; else a no-op.
     pub fn world_tooltip_move(&mut self, ui_x: f32, ui_y: f32) {
         let mut model = self.model_mut();
         let Some(h) = model.arena.lookup("GameTooltip") else {
@@ -596,11 +489,8 @@ impl super::UiScript {
         }
         let root_id = model.frame_id(root);
         let input = model.layout_inputs.entry(h).or_default();
-        // Anchor only — the frame's own clamp flag keeps the plate on screen (see
-        // `Frame::clamped_to_screen`).
         let new = Anchor::new(Point::Bottom, root_id, Point::BottomLeft, ui_x, ui_y);
-        // Compare-then-touch, as in the seat/blip paths above: the follow fires per pointer
-        // event, and a still cursor must not dirty the layout gate's tier 1.
+        // Compare-then-touch: this runs on every pointer event.
         let same =
             input.anchors.len() == 1 && super::object::anchor_bits_eq(&input.anchors[0], &new);
         if !same {
@@ -609,12 +499,8 @@ impl super::UiScript {
         }
     }
 
-    /// **Is `GameTooltip` still the plate a world hover put up?** — world-owned (no Lua
-    /// `SetOwner`, no content `Set*` and no `Hide` has taken it since) and still shown.
-    ///
-    /// The world-hover driver keeps a host-side memo of which plate it put up so it does not
-    /// rebuild one per frame; that memo is about the HOVER, and this is the other half of the
-    /// question — whether the plate that memo describes is still on the screen.
+    /// Whether `GameTooltip` is still the shown plate a world hover put up, with no Lua
+    /// `SetOwner`, content `Set*` or `Hide` since.
     pub fn world_tooltip_up(&mut self) -> bool {
         let model = self.model_mut();
         let Some(h) = model.arena.lookup("GameTooltip") else {
@@ -627,8 +513,8 @@ impl super::UiScript {
             .unwrap_or(false)
     }
 
-    /// Arm the mouseover tooltip's fade-out (hover loss — the byte law arms a timestamped fade,
-    /// never an instant hide). No-op when the tooltip isn't showing a world unit.
+    /// On hover loss, arm the world tooltip's timed fade (the reference's unit plate fades rather
+    /// than hiding); a no-op unless a world-owned plate is shown.
     pub fn world_tooltip_fade(&mut self) {
         let now = self.now();
         let mut model = self.model_mut();
@@ -647,15 +533,12 @@ impl super::UiScript {
 
 /// Register the unit content channel into the GameTooltip kind method table.
 pub(super) fn install_methods(lua: &Lua, m: &Table) -> mlua::Result<()> {
-    // GameTooltip:SetUnit(token) → 1/nil — the unit-frame hover (ref UnitFrame_OnEnter reads
-    // the return to arm its re-poll).
+    // GameTooltip:SetUnit(token) → 1 or nil, which `UnitFrame_OnEnter` reads to arm its re-poll.
     m.set(
         "SetUnit",
         lua.create_function(|lua, (this, token): (Table, String)| {
-            // Same gate as every `Unit*` verb: `SetUnit` resolves its argument through the client's
-            // one token resolver, so an unrecognised name raises here too rather than drawing an
-            // empty tooltip. NOT inside `render_unit` — the app's own push calls that with a
-            // canonical token and must never be gated against itself.
+            // The token gate every `Unit*` verb uses: an unknown token raises. Not in
+            // `render_unit`, which the app calls with canonical tokens.
             crate::script::unit::check_unit_token(&Some(token.clone()))?;
             let ok = render_unit(lua, &this, &token)?;
             Ok(if ok {
diff --git a/crates/benilla-ui/src/script/trade.rs b/crates/benilla-ui/src/script/trade.rs
index adb82768..fc9f68c2 100644
--- a/crates/benilla-ui/src/script/trade.rs
+++ b/crates/benilla-ui/src/script/trade.rs
@@ -1,29 +1,7 @@
-//! The player-to-player trade bindings (decision 0592 P1) — the two-sided trade-window surface, the
-//! same push/intent seam as [`super::mail`]/[`super::merchant`]: the app pushes a **trade snapshot**
-//! ([`UiScript::set_trade`] — both sides' slots already resolved from the wire to name/icon/quality
-//! by the app's item-template + display caches, and the partner's name from the name cache) and the
-//! Lua `InitiateTrade`/`AcceptTrade`/`CloseTrade`/… calls queue outbound **intents** the app drains.
-//! The engine holds no trade knowledge — a slot is a resolved item view, a side is seven slots + a
-//! gold amount, and the accept-glow is a fired event, never read state.
-//!
-//! ## The 5875 API shape (VERIFIED against the extracted `TradeFrame.lua`)
-//!
-//! `id` is **1-based** everywhere (slots 1..=7; slot 7 is the non-traded / enchant slot); an
-//! out-of-range or empty slot answers `nil`. The read getters:
-//! `GetTradePlayerItemInfo(id)` → `name, texture, numItems, isUsable, enchantment` (our own offer),
-//! `GetTradeTargetItemInfo(id)` → `name, texture, numItems, quality, isUsable, enchantment` (the
-//! partner's offer — the extra `quality` drives its slot's colour + the red not-usable tint),
-//! `GetPlayerTradeMoney()`/`GetTargetTradeMoney()` → the two gold amounts in copper, and
-//! `GetTradePartnerName()` → the partner's name (benilla's getter for the window header, in place of
-//! the reference's `UnitName("NPC")`; the partner's *portrait* rides the `"npc"` token the app points
-//! at the partner entity — decision 0592, [`crate::script`] has no engine-side unit for it).
-//! `enchantment` is `nil` in P1 (the enchant-slot spell name is decision 0592 P3).
-//!
-//! The intents: `InitiateTrade(unit)` queues the right-click menu's trade offer (the app resolves the
-//! unit token → guid → `CMSG_INITIATE_TRADE`); `AcceptTrade()`/`CancelTradeAccept()`/`CloseTrade()`
-//! flag the accept / un-accept / cancel verbs the app maps to `CMSG_ACCEPT_TRADE` /
-//! `CMSG_UNACCEPT_TRADE` / `CMSG_CANCEL_TRADE`. Setting items/gold onto the window (the drag-drop
-//! slots + the money widget) is decision 0592 P2.
+//! The trade bindings: the app pushes both sides of the open trade ([`UiScript::set_trade`]), and
+//! the trade verbs queue intents it drains. Slots are 1-based, 1..=7, the seventh the non-traded
+//! enchant slot; an empty or out-of-range slot answers nil. The partner rides the `"npc"` unit,
+//! which the app points at them.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -31,63 +9,48 @@ use super::binding_abi::flag;
 use super::cursor::{self, CursorPayload};
 use super::Model;
 
-/// The seven trade slots per side (`TRADE_SLOT_COUNT`, vmangos `TradeData.h`) — six tradeable
-/// (1..=6) plus the seventh non-traded / enchant slot. Mirrors the wire's fixed count without a
-/// `benilla-protocol` dependency (this crate is engine-only).
+/// Slots per side, six traded and the non-traded enchant slot: vmangos `TRADE_SLOT_COUNT`
+/// (`TradeData.h`), kept equal to the protocol crate's, which this crate does not depend on.
 pub const TRADE_SLOTS: usize = 7;
 
-/// One resolved trade slot, as the app pushes it (decision 0592) — the wire `TradeItem`'s
-/// entry/display resolved through the shared item-template + display caches. Plain data; an empty
-/// slot is `None` in [`TradeSideState::slots`], never a zeroed `Some`.
+/// One filled trade slot, resolved by the app; an empty slot is `None`, never a zeroed `Some`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TradeSlotItem {
-    /// The item template entry (`0` never stored — an empty slot is `None`) — the `isUsable` gate's
-    /// key over the shared item-template store, and the slot tooltip's identity (decision 0592 P2).
+    /// The item entry, the key for `isUsable` and the tooltip.
     pub item_id: u32,
-    /// The item name (from the template); `None` while the ask-once template answer is in flight.
+    /// `None` while the item template is in flight.
     pub name: Option<String>,
-    /// The item icon (from the wire `display_id` via `ItemDisplayInfo.dbc`); `None` while in flight.
     pub texture: Option<String>,
-    /// The stack count in this slot (`>= 1` for a filled slot).
     pub count: u32,
-    /// The item quality (0..=6); `None` while the template is in flight. Read only for the target
-    /// side (the recipient slot's quality colour + red not-usable tint — `TradeFrame.lua` l.84).
+    /// `None` while the template is in flight; only the target side's info returns it
+    /// (`TradeFrame.lua:84`).
     pub quality: Option<u32>,
-    /// The enchant-slot spell name (slot 7 only) — `None` in P1 (the applied-spell path is
-    /// decision 0592 P3).
+    /// The name of the enchant being applied to slot 7, which stock shows in green
+    /// (`TradeFrame.lua:62`); the app always sends `None`.
     pub enchantment: Option<String>,
-    /// The slot's full escaped `|cff…|Hitem:…|h[Name]|h|r` link — `GetTradePlayerItemLink` /
-    /// `GetTradeTargetItemLink`'s answer, and `None` while the ask-once template answer is in
-    /// flight (the link embeds the name and the quality colour).
-    ///
-    /// The same shape as [`super::merchant::MerchantItem::link`] and for the same reason: 1.12's
-    /// own `TradeFrame.lua` hands it straight to `DressUpItemLink` on a ctrl-click and to
-    /// `ChatFrameEditBox:Insert` on a shift-click, so it is a string the app already knows rather
-    /// than anything the engine composes.
+    /// The escaped item link the link verbs answer; `None` while the template is in flight, since
+    /// it embeds the name and the quality.
     pub link: Option<String>,
 }
 
-/// One side of the trade window — the seven slots (1-based in the API) plus the gold offered on
-/// this side, in copper. `player` is our own offer, `target` the partner's ([`TradeState`]).
+/// One side's offer.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TradeSideState {
-    /// The seven slots (index 0 = trade slot 1 … index 6 = the enchant slot); `None` = empty.
+    /// Index 0 is trade slot 1, index 6 the enchant slot.
     pub slots: [Option<TradeSlotItem>; TRADE_SLOTS],
-    /// Gold offered on this side, in copper.
+    /// In copper.
     pub gold: u32,
 }
 
-/// The open trade window's snapshot. Pushed whole by the app; `None` = no trade open (the window is
-/// closed). The accept-glow state is **not** here — it rides the fired `TRADE_ACCEPT_UPDATE` event,
-/// never a getter (the reference `TradeFrame_SetAcceptState`, `TradeFrame.lua` l.116).
+/// The open trade, pushed whole by the app. The accept highlight is not here: it rides the
+/// `TRADE_ACCEPT_UPDATE` event (`TradeFrame.lua:35`).
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TradeState {
-    /// Our own offer (the wire's `their_window == false` snapshot).
+    /// Our offer.
     pub player: TradeSideState,
-    /// The partner's offer (the wire's `their_window == true` snapshot).
+    /// The partner's offer, the wire's `their_window` snapshot.
     pub target: TradeSideState,
-    /// The partner's name, resolved by the app through the name cache; `None` while in flight. The
-    /// window header reads this (benilla's `GetTradePartnerName()` in place of `UnitName("NPC")`).
+    /// The partner's name for `GetTradePartnerName()`, `None` while in flight.
     pub partner_name: Option<String>,
 }
 
@@ -97,65 +60,55 @@ impl super::UiScript {
         self.model_mut().trade = state;
     }
 
-    /// Drain the unit tokens `InitiateTrade` queued since the last drain — the app resolves each
-    /// token → player guid and sends `CMSG_INITIATE_TRADE`.
+    /// Drain the tokens `InitiateTrade` queued; the app sends `CMSG_INITIATE_TRADE` for each.
     pub fn take_trade_initiates(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().trade_initiates)
     }
 
-    /// Whether `AcceptTrade` was called since the last drain (and clear the flag) — the app maps it
-    /// to `CMSG_ACCEPT_TRADE`.
+    /// Whether `AcceptTrade` was called since the last drain: `CMSG_ACCEPT_TRADE`.
     pub fn take_trade_accept(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_accept)
     }
 
-    /// Whether `CancelTradeAccept` was called since the last drain — the app maps it to
-    /// `CMSG_UNACCEPT_TRADE` (drop your accept, stay in the trade).
+    /// Whether `CancelTradeAccept` was called since the last drain: `CMSG_UNACCEPT_TRADE`.
     pub fn take_trade_unaccept(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_unaccept)
     }
 
-    /// Whether `CloseTrade` was called since the last drain — the app maps it to `CMSG_CANCEL_TRADE`
-    /// and clears its local trade session (the window's OnHide close verb).
+    /// Whether `CloseTrade`, the window's OnHide verb, was called since the last drain; the app
+    /// sends `CMSG_CANCEL_TRADE` and ends its session.
     pub fn take_trade_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_close)
     }
 
-    /// Whether `BeginTrade()` was called since the last drain — `CMSG_BEGIN_TRADE`, empty
-    /// (decision 1963; the TRADE dialog that calls it can never show in 1.12.1, so this is an
-    /// addon's reach).
+    /// Whether `BeginTrade()` was called since the last drain: an empty `CMSG_BEGIN_TRADE`.
     pub fn take_trade_begin(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_begin)
     }
 
-    /// Whether `CancelTrade()` was called since the last drain — the BARE `CMSG_CANCEL_TRADE`,
-    /// where `CloseTrade` wraps the same opcode in the window's teardown (decision 1963).
+    /// Whether `CancelTrade()` was called since the last drain: the bare `CMSG_CANCEL_TRADE`.
     pub fn take_trade_cancel(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_cancel)
     }
 
-    /// The copper amount `SetTradeMoney` last offered since the last drain (and clear it) — the app
-    /// maps it to `CMSG_SET_TRADE_GOLD` (decision 0592 P2).
+    /// The copper `SetTradeMoney` last offered since the last drain: `CMSG_SET_TRADE_GOLD`.
     pub fn take_trade_money(&mut self) -> Option<u32> {
         std::mem::take(&mut self.model_mut().trade_set_money)
     }
 
-    /// The `(trade_id, bag, slot)` placements `ClickTradeButton` queued since the last drain — the app
-    /// maps each `(bag, slot)` through its wire-position map to `CMSG_SET_TRADE_ITEM` (decision 0592 P2).
-    /// `trade_id` is 1-based (1..=7); `bag`/`slot` are the engine's cursor space (0 backpack …).
+    /// The `(trade_id, bag, slot)` placements `ClickTradeButton` queued, for `CMSG_SET_TRADE_ITEM`:
+    /// `trade_id` 1..=7, `bag` and `slot` in the cursor's space.
     pub fn take_trade_set_items(&mut self) -> Vec<(u32, i64, u32)> {
         std::mem::take(&mut self.model_mut().trade_set_items)
     }
 
-    /// The 1-based trade slot ids `ClickTradeButton` queued to clear (empty-cursor click on a filled
-    /// slot) — the app maps each to `CMSG_CLEAR_TRADE_ITEM` (decision 0592 P2).
+    /// The 1-based slots `ClickTradeButton` queued to clear, for `CMSG_CLEAR_TRADE_ITEM`.
     pub fn take_trade_clear_items(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().trade_clear_items)
     }
 }
 
-/// Fetch a cloned slot for a 1-based index off one side, or `None` (out of range / empty / no trade
-/// open). `pick` selects the side from the pushed [`TradeState`].
+/// The slot at a 1-based index on the side `pick` selects.
 fn slot_at(
     model: &Model,
     index: usize,
@@ -170,20 +123,16 @@ fn slot_at(
         .flatten()
 }
 
-/// The gold on one side (copper), or `0` if no trade is open.
 fn gold(model: &Model, pick: impl Fn(&TradeState) -> &TradeSideState) -> u32 {
     model.trade.as_ref().map(pick).map_or(0, |side| side.gold)
 }
 
-/// A click on OUR trade slot `id` (1-based) as a cursor drop target (decision 0592 P2, ref
-/// `ClickTradeButton`, TradeFrame.xml l.135): a held bag item drops in — queue a `(id, bag, slot)`
-/// placement the app maps to `CMSG_SET_TRADE_ITEM` — and the cursor is **cleared** (the 0218
-/// plain-clear: no local held copy, the filled slot reads back from `SMSG_TRADE_STATUS_EXTENDED`). An
-/// empty cursor on a filled slot queues a clear (`CMSG_CLEAR_TRADE_ITEM`; the item never left the bag,
-/// the server just un-references it). A spell/action payload is refused, put back untouched.
+/// `ClickTradeButton(id)` on our slot (`TradeFrame.xml:135`): a held bag item is queued for
+/// `CMSG_SET_TRADE_ITEM` and the cursor cleared, the app filling our column itself since vmangos
+/// echoes a placement only to the partner (`TradeData.cpp:81`); an empty cursor on a filled slot
+/// queues a clear. Any other payload stays on the cursor.
 fn click_trade_button(model: &mut Model, id: u32) {
-    // The money arm runs first and never reads the index (`0x4bfe34`, decision 1965): coins on
-    // the cursor go into the offer as `AddTradeMoney` puts them, and that is the whole click.
+    // Coins on the cursor go into the offer, the index unread (`0x4bfe34`).
     if matches!(model.cursor, Some(CursorPayload::Money(_))) {
         cursor::money::add_trade_money(model);
         return;
@@ -217,8 +166,7 @@ fn click_trade_button(model: &mut Model, id: u32) {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetTradePlayerItemInfo(id) → name, texture, numItems, isUsable, enchantment (our own offer;
-    // TradeFrame.lua l.55). An empty/out-of-range slot answers nil.
+    // GetTradePlayerItemInfo(id): the five values `TradeFrame.lua:55` reads.
     g.set(
         "GetTradePlayerItemInfo",
         lua.create_function(|lua, id: usize| {
@@ -249,13 +197,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradePlayerItemLink(id) / GetTradeTargetItemLink(id) → the slot's escaped item link, or
-    // nil for an empty slot / one whose template answer is still in flight.
-    //
-    // 1.12's `TradeFrame.lua` reaches for these on a modified click of a trade slot — ctrl hands
-    // the link to `DressUpItemLink`, shift inserts it into the chat box — the same pair of arms
-    // the merchant rows have, which is why this mirrors `GetMerchantItemLink` exactly rather than
-    // composing anything here.
+    // The link verbs, for a slot's ctrl and shift clicks (`TradeFrame.xml:129`, `:95`).
     for (name, side) in [
         ("GetTradePlayerItemLink", true),
         ("GetTradeTargetItemLink", false),
@@ -280,8 +222,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // GetTradeTargetItemInfo(id) → name, texture, numItems, quality, isUsable, enchantment (the
-    // partner's offer; TradeFrame.lua l.84 — the extra `quality` is the recipient-only colour).
+    // GetTradeTargetItemInfo(id): the six values `TradeFrame.lua:84` reads.
     g.set(
         "GetTradeTargetItemInfo",
         lua.create_function(|lua, id: usize| {
@@ -317,8 +258,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerTradeMoney() / GetTargetTradeMoney() → the two gold amounts, copper (TradeFrame.lua
-    // l.165/l.585). 0 when no trade is open.
     g.set(
         "GetPlayerTradeMoney",
         lua.create_function(|lua, ()| {
@@ -334,8 +273,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradePartnerName() → the partner's name (benilla's header getter, in place of the
-    // reference's UnitName("NPC") — see the module doc). nil while in flight / no trade open.
+    // `GetTradePartnerName()` is not a 1.12 global; the stock header reads `UnitName("NPC")`
+    // (`TradeFrame.lua:43`).
     g.set(
         "GetTradePartnerName",
         lua.create_function(|lua, ()| {
@@ -349,8 +288,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // InitiateTrade(unit) — queue the right-click menu's trade offer against a unit token; the app
-    // resolves it → player guid → CMSG_INITIATE_TRADE (the UnitPopup TRADE row, decision 0592 P1).
+    // InitiateTrade(unit): the unit menu's TRADE row.
     g.set(
         "InitiateTrade",
         lua.create_function(|lua, unit: String| {
@@ -362,8 +300,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AcceptTrade() / CancelTradeAccept() / CloseTrade() — the Trade / un-accept / cancel verbs the
-    // app maps to CMSG_ACCEPT_TRADE / CMSG_UNACCEPT_TRADE / CMSG_CANCEL_TRADE (decision 0592 P1).
     g.set(
         "AcceptTrade",
         lua.create_function(|lua, ()| {
@@ -391,10 +327,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(())
         })?,
     )?;
-    // BeginTrade() / CancelTrade() — the TRADE dialog's pair (wow-re `staticpopup-dialog-bindings.md`
-    // §2: 0 args, 0 returns, no gate; `0x117` and `0x11C`, both empty). The dialog itself can never
-    // show in 1.12.1 (TRADE_REQUEST is signalled by nothing), so both are an addon's reach;
-    // CancelTrade is the bare packet, CloseTrade above the same opcode wrapped in the teardown.
+    // BeginTrade() and CancelTrade() (`0x48aa60`, `0x48aa70`): no arguments, no returns, no gate,
+    // and an empty `0x117` or `0x11C`. They are the `TRADE` popup's Yes and No
+    // (`StaticPopup.lua:517-522`), which never shows in 1.12 as nothing signals `TRADE_REQUEST`.
     g.set(
         "BeginTrade",
         lua.create_function(|lua, ()| {
@@ -414,14 +349,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetTradeMoney(copper) — offer this many copper on our side (the money input's value-changed
-    // callback); the app maps it to CMSG_SET_TRADE_GOLD (decision 0592 P2). `i64` in, clamped, so a
-    // fractional/negative Lua number can never panic the coercion.
+    // SetTradeMoney(copper): the money input's callback (`TradeFrame.lua:173`).
     g.set(
         "SetTradeMoney",
         lua.create_function(|lua, copper: Value| {
-            // `0x4c0820` (decision 1965): a non-number RAISES; the low dword goes on the wire as an
-            // absolute offer, gated on the purse covering it — a refusal is silent at every level.
+            // `0x4c0820`: a non-number raises; the low dword is the whole offer, sent only when the
+            // purse covers it, and a refusal is silent.
             let n = crate::script::binding_abi::number_arg(
                 lua,
                 copper,
@@ -436,8 +369,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClickTradeButton(id) — drop a held bag item into / clear our trade slot `id` (1..=7); the app
-    // maps it to CMSG_SET_TRADE_ITEM / CMSG_CLEAR_TRADE_ITEM (decision 0592 P2).
     g.set(
         "ClickTradeButton",
         lua.create_function(|lua, id: u32| {
@@ -447,14 +378,11 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ClickTargetTradeButton(id) — the partner's column is read-only (their offer is server-driven);
-    // inert in P2 (the shift-click item link is decision 0592 P3). Registered so the shared slot
-    // handler can call it for the recipient side without erroring.
+    // ClickTargetTradeButton(id) (`TradeFrame.xml:101`): the partner's column takes nothing.
     g.set(
         "ClickTargetTradeButton",
         lua.create_function(|lua, _id: u32| {
-            // The same money arm as `ClickTradeButton` (`0x4c00a3`, decision 1965): coins on the
-            // cursor go into OUR offer whichever side's slot was clicked, the index unread.
+            // Coins on the cursor still go into our offer, the index unread (`0x4c00a3`).
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             cursor::money::add_trade_money(&mut model);
             Ok(())
@@ -502,12 +430,6 @@ mod tests {
         }
     }
 
-    /// **The two link verbs**, and the two absences they share with every other item-link reader
-    /// here: an empty slot, and a slot whose ask-once template answer has not landed.
-    ///
-    /// 1.12's `TradeFrame.lua` reaches for these on a modified click of a trade slot — ctrl hands
-    /// the link to `DressUpItemLink`, shift inserts it into the chat box. They were two of the four
-    /// engine verbs the readiness probe reports against stock `TradeFrame.xml`.
     #[test]
     fn the_trade_slots_answer_their_item_links() {
         let mut s = UiScript::new().unwrap();
@@ -520,7 +442,7 @@ mod tests {
             .unwrap());
 
         let mut st = state();
-        // A slot whose template is still in flight carries no link — the string embeds the name.
+        // A slot whose template is in flight has no link.
         st.target.slots[1] = Some(TradeSlotItem {
             item_id: 4306,
             name: None,
@@ -542,7 +464,7 @@ mod tests {
                 .unwrap(),
             "|cffffffff|Hitem:4306:0:0:0|h[Linen Cloth]|h|r"
         );
-        // …the in-flight slot, and an empty one, and one past the seven.
+        // The in-flight slot, an empty one, and one past the seven.
         assert!(s
             .eval::<bool>("return GetTradeTargetItemLink(2) == nil")
             .unwrap());
@@ -565,7 +487,6 @@ mod tests {
 
         s.set_trade(Some(state()));
 
-        // Player slot 1: name, texture, count 5, isUsable 1, enchantment nil.
         let (name, tex, count, usable): (String, String, i64, i64) = s
             .eval(
                 "local n,t,c,u,e = GetTradePlayerItemInfo(1)\n\
@@ -577,12 +498,11 @@ mod tests {
         assert!(s
             .eval::<bool>("local n,t,c,u,e = GetTradePlayerItemInfo(1)\nreturn e == nil")
             .unwrap());
-        // An empty player slot → nil.
         assert!(s
             .eval::<bool>("return GetTradePlayerItemInfo(2) == nil")
             .unwrap());
 
-        // Target slot 1 carries the extra quality (index 4 of the 6-tuple).
+        // The target side adds quality as the fourth return.
         let (name, _tex, count, quality, usable): (String, String, i64, i64, i64) =
             s.eval("return GetTradeTargetItemInfo(1)").unwrap();
         assert_eq!(
@@ -643,13 +563,12 @@ mod tests {
         assert!(s.take_trade_close());
         assert!(!s.take_trade_close(), "drained");
 
-        // SetTradeMoney folds gold/silver/copper into a copper total the app ships as SET_TRADE_GOLD,
-        // gated on the purse covering it (1965).
+        // An offer is sent only when the purse covers it.
         s.set_money(20_000);
         s.run("SetTradeMoney(1 * 10000 + 23 * 100 + 45)").unwrap();
         assert_eq!(s.take_trade_money(), Some(12_345));
         assert_eq!(s.take_trade_money(), None, "drained");
-        // The low dword of -5 is an unsigned 0xFFFFFFFB, past any purse: refused silently (1965).
+        // The low dword of -5 is 0xFFFFFFFB, past any purse: refused silently.
         s.run("SetTradeMoney(-5)").unwrap();
         assert_eq!(s.take_trade_money(), None);
         s.run("SetTradeMoney(30000)").unwrap();
@@ -682,8 +601,7 @@ mod tests {
         assert!(s.take_trade_set_items().is_empty());
         assert!(s.take_trade_clear_items().is_empty());
 
-        // A held backpack item (bag 0, slot 3) dropped on our slot 2 → a (2, 0, 3) placement, and the
-        // cursor is cleared (0218 plain-clear — no local held copy).
+        // A held backpack item dropped on our slot 2 queues (2, 0, 3) and clears the cursor.
         s.model_mut().cursor = Some(item(0, 3));
         s.run("ClickTradeButton(2)").unwrap();
         assert_eq!(s.take_trade_set_items(), vec![(2, 0, 3)]);
@@ -692,7 +610,7 @@ mod tests {
             "the drop clears the cursor"
         );
 
-        // Empty cursor on a FILLED player slot → clear it; on an empty slot → nothing.
+        // An empty cursor clears a filled slot and does nothing on an empty one.
         let mut st = TradeState::default();
         st.player.slots[0] = Some(TradeSlotItem {
             item_id: 2589,
@@ -708,7 +626,7 @@ mod tests {
             "an empty slot clears nothing"
         );
 
-        // The partner column is read-only — ClickTargetTradeButton never queues and never eats the cursor.
+        // The partner's column queues nothing and leaves the cursor alone.
         s.model_mut().cursor = Some(item(0, 3));
         s.run("ClickTargetTradeButton(1)").unwrap();
         assert!(s.take_trade_set_items().is_empty());
@@ -717,7 +635,7 @@ mod tests {
             "a partner-side click leaves the cursor untouched"
         );
 
-        // A spell payload is refused — put back untouched, nothing queued.
+        // A spell payload is refused and stays on the cursor.
         s.model_mut().cursor = Some(CursorPayload::Spell(crate::script::cursor::CursorSpell {
             passive: false,
             book_slot: 1,
diff --git a/crates/benilla-ui/src/script/tradeskill/api.rs b/crates/benilla-ui/src/script/tradeskill/api.rs
index a416073a..03eb2134 100644
--- a/crates/benilla-ui/src/script/tradeskill/api.rs
+++ b/crates/benilla-ui/src/script/tradeskill/api.rs
@@ -1,5 +1,4 @@
-//! The Lua globals (`GetTradeSkillInfo`, `DoTradeSkill`, the filter family, …) — [`install`] wires
-//! the Era `TradeSkillFrame.lua` API surface onto [`super::view`]'s display-tree/filter machinery.
+//! The tradeskill Lua globals over [`super::view`]'s visible rows and filters.
 
 use mlua::{Lua, MultiValue, Value};
 
@@ -20,7 +19,7 @@ fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     })
 }
 
-/// A `bool` as the Era `1`/`nil` shape.
+/// A `bool` as the 1.12 API's `1` or `nil`.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -33,8 +32,7 @@ fn era_bool(b: bool) -> Value {
 pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetTradeSkillLine() → lineName, rank, maxRank; ("UNKNOWN", 0, 0) with no window open (the
-    // ref's own no-tradeskill shape).
+    // GetTradeSkillLine(): ("UNKNOWN", 0, 0) with no window open, as the reference answers.
     g.set(
         "GetTradeSkillLine",
         lua.create_function(|lua, ()| {
@@ -51,8 +49,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // → the number of VISIBLE rows the open window offers — headers + the recipes of uncollapsed
-    // groups (0 when closed).
+    // GetNumTradeSkills(): the visible rows, headers included.
     g.set(
         "GetNumTradeSkills",
         lua.create_function(|lua, ()| {
@@ -61,12 +58,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The two link verbs (wow-re `tradeskill/scratch/tradeskill-craft-item-links.md`, 1973).
-    //
-    // GetTradeSkillItemLink(index) — `0x4ff410`: the number gate raises its Usage; then ZERO
-    // values on every miss — an index off the list, a header row, a recipe with no product, an
-    // uncached product template (no query is ever sent; the app pre-asks when the list lands) —
-    // and otherwise ONE string, the product's `|Hitem:` link in its quality colour.
+    // GetTradeSkillItemLink(index) (`0x4ff410`): zero values on any miss (a header, no product, an
+    // uncached template, which is never queried here), else the product's item link.
     g.set(
         "GetTradeSkillItemLink",
         lua.create_function(|lua, index: Value| {
@@ -94,10 +87,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillReagentItemLink(index, reagentIndex) — `0x4ff800`: both arguments through the
-    // number gate, raising `Usage: GetTradeReagentSkillItemLink(…)` — Blizzard's own typo, kept.
-    // `reagentIndex` is 1-based over the NON-EMPTY reagent slots and never range-checked in the
-    // client; ALWAYS exactly one value: the reagent's link, or nil on any miss.
+    // GetTradeSkillReagentItemLink(index, reagentIndex) (`0x4ff800`): always one value, the link
+    // or nil; `reagentIndex` counts the non-empty reagent slots, and the usage error's
+    // `GetTradeReagentSkillItemLink` is the reference's own typo.
     g.set(
         "GetTradeSkillReagentItemLink",
         lua.create_function(|lua, (index, reagent): (Value, Value)| {
@@ -128,10 +120,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillInfo(index) → name, type, numAvailable, isExpanded. `index` 1-based into the
-    // VISIBLE row list (the module doc's grouped-list law, wow-re `tradeskill` TU-B). A header row:
-    // (groupName, "header", 0, isExpanded 1/nil). A recipe row: (name, difficulty color key,
-    // numAvailable, nil). Out of range → a single nil.
+    // GetTradeSkillInfo(index): (name, "header", 0, isExpanded) for a header, (name, difficulty,
+    // numAvailable, nil) for a recipe, one nil out of range.
     g.set(
         "GetTradeSkillInfo",
         lua.create_function(|lua, index: usize| {
@@ -169,7 +159,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetFirstTradeSkill() → the first NON-header visible index (0 when none).
     g.set(
         "GetFirstTradeSkill",
         lua.create_function(|lua, ()| {
@@ -178,9 +167,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillSubClasses() → the current group names, in group order (VERIFIED, wow-re
-    // `tradeskill` TU-B: the filter-dropdown vocabulary IS the header list) — though v1 ships no
-    // filter dropdown to consume it yet (the SubClass/InvSlot filter family below stays inert).
+    // GetTradeSkillSubClasses(): the group names in order, unfiltered (`0x4ffb60`).
     g.set(
         "GetTradeSkillSubClasses",
         lua.create_function(|lua, ()| {
@@ -195,8 +182,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ExpandTradeSkillSubClass(i) / CollapseTradeSkillSubClass(i) — fold a group by its header's
-    // VISIBLE index (i == 0 = ALL groups, the CollapseAll semantics — see [`set_collapsed`]).
+    // Expand/CollapseTradeSkillSubClass(i): the group whose header is visible row i; 0 is all.
     g.set(
         "ExpandTradeSkillSubClass",
         lua.create_function(|lua, id: usize| {
@@ -216,7 +202,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillIcon(index) → icon texture path (nil while in flight / OOB / a header row).
     g.set(
         "GetTradeSkillIcon",
         lua.create_function(|lua, index: usize| {
@@ -225,7 +210,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillNumMade(index) → minMade, maxMade (0, 0 when OOB / no window / a header row).
     g.set(
         "GetTradeSkillNumMade",
         lua.create_function(|lua, index: usize| {
@@ -239,8 +223,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillCooldown(index) → remaining cooldown seconds, or nil when ready / OOB / a header
-    // row (the ref Lua tests this return for truthiness).
+    // GetTradeSkillCooldown(index): nil when ready, which the stock Lua tests for truthiness
+    // (Blizzard_TradeSkillUI.lua:215).
     g.set(
         "GetTradeSkillCooldown",
         lua.create_function(|lua, index: usize| {
@@ -254,8 +238,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillNumReagents(index) → this recipe's reagent count (0 when OOB / no window / a
-    // header row).
     g.set(
         "GetTradeSkillNumReagents",
         lua.create_function(|lua, index: usize| {
@@ -264,10 +246,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillReagentInfo(index, reagentIndex) → name, icon, need, have (a single nil when the
-    // recipe/reagent index is OOB or `index` is a header row). name/icon are themselves nil while
-    // the ask-once template answer is in flight — the ref grays/counts the row off exactly these
-    // four.
+    // GetTradeSkillReagentInfo(index, reagentIndex): one nil on a miss; name and icon are nil
+    // until the item template arrives.
     g.set(
         "GetTradeSkillReagentInfo",
         lua.create_function(|lua, (index, reagent_index): (usize, usize)| {
@@ -286,9 +266,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeSkillTools(index) → an alternating (name, has) multivalue, one pair per Requirements
-    // tool (e.g. "Anvil", 1, "Mining Pick", nil) — the ref feeds this straight into
-    // BuildColoredListString. Empty when the recipe has no tools / index is OOB / a header row.
+    // GetTradeSkillTools(index): alternating (name, has) pairs, which the stock Lua feeds to
+    // `BuildColoredListString` (Blizzard_TradeSkillUI.lua:274).
     g.set(
         "GetTradeSkillTools",
         lua.create_function(|lua, index: usize| {
@@ -304,8 +283,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTradeskillRepeatCount() → the remaining Create All repeats (note the lowercase "s" in
-    // "Tradeskill" — that IS the real 1.12 API name). 0 with no window open.
+    // GetTradeskillRepeatCount(): the lowercase "s" is the 1.12 name.
     g.set(
         "GetTradeskillRepeatCount",
         lua.create_function(|lua, ()| {
@@ -316,9 +294,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SelectTradeSkill(index) / GetTradeSkillSelectionIndex() — the engine-held selection, VISIBLE
-    // index in ([`select`]: a header index is IGNORED, not cleared), VISIBLE index out
-    // ([`selected_visible_index`]), held internally as a stable flat-recipe position (module doc).
+    // SelectTradeSkill and GetTradeSkillSelectionIndex take and answer visible indices.
     g.set(
         "SelectTradeSkill",
         lua.create_function(|lua, index: u32| {
@@ -335,9 +311,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // DoTradeSkill(index, count) — queue the recipe's SPELL ID for `count` crafts (default 1, never
-    // less than 1) — the app's repeat machine turns this into that many CMSG_CAST_SPELL sends. Out
-    // of range / a header index → ignored.
+    // DoTradeSkill(index, count): queues the recipe's spell for `count` crafts, which the app sends
+    // as one `CMSG_CAST_SPELL` each.
     g.set(
         "DoTradeSkill",
         lua.create_function(|lua, (index, count): (usize, Option<i64>)| {
@@ -345,8 +320,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             if let Some((spell_id, avail)) =
                 recipe_at(&model, index).map(|r| (r.spell_id, r.num_available))
             {
-                // The client clamps the repeat to numAvailable at the latch (byte-VERIFIED —
-                // wow-re `tradeskill` TU-D, `DoTradeSkill 0x500280`).
+                // The client clamps the repeat to numAvailable, at least 1 (`0x500280`).
                 let n = (count.unwrap_or(1).max(1) as u32).min(avail.max(1));
                 model.trade_skill_dos.push((spell_id, n));
             }
@@ -354,8 +328,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseTradeSkill() — client-side close (no packet, vanilla): flag it so the app clears its
-    // local state.
+    // CloseTradeSkill(): client-side only, no packet; the app clears its state.
     g.set(
         "CloseTradeSkill",
         lua.create_function(|lua, ()| {
@@ -365,16 +338,12 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The sub-class/inv-slot FILTER family — real now (the dropdowns ship, ref
-    // Blizzard_TradeSkillUI.lua l.314-414). Indexing follows the C originals: the SubClass index
-    // is 1-based into the CURRENT GetTradeSkillSubClasses order (`0x4ffc70` bounds-checks against
-    // the live header count), the InvSlot index 1-based into the GetTradeSkillInvSlots order;
-    // index 0 is the "All" pseudo-entry on both. `Set*(0, 1, …)` = everything back on (the ref's
-    // "All Subclasses"/"All Slots" menu row); `Set*(i, 1, 1)` = EXCLUSIVE — only entry i shown
-    // (every ref menu click passes exactly this shape); `Set*(i, 1)` un-hides i; `Set*(i, 0)`
-    // hides it. Each set re-lists + fires TRADE_SKILL_UPDATE via the touched flag (the `0x4fd710`
-    // re-sort + event 0x139 shape). `Get*(0)` answers "is everything shown" — the ref's
-    // all-checked probe.
+    // The subclass and inv-slot filters (Blizzard_TradeSkillUI.lua:314-414): index i is 1-based
+    // into `GetTradeSkillSubClasses` (`0x4ffc70` bounds-checks it) or `GetTradeSkillInvSlots`, and
+    // 0 is all. `Set*(i, 1, 1)` shows only i, as every menu click does; `Set*(i, 1)` shows i and
+    // `Set*(i, 0)` hides it. Each set fires TRADE_SKILL_UPDATE through the touched flag
+    // (`0x4fd710`), and `Get*(0)` asks whether everything is shown. The reference's per-header
+    // subclass flag (`+0xc`, mask `0x84dd60`) is kept here as hidden group keys.
     g.set(
         "GetTradeSkillSubClassFilter",
         lua.create_function(|lua, index: usize| {
@@ -432,17 +401,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             },
         )?,
     )?;
-    // GetTradeSkillInvSlots() → the distinct slot words of the open window's products, ascending
-    // slot-bit order (the `0xbde058` bit walk — [`present_inv_slots`]).
+    // GetTradeSkillInvSlots(): the products' slot names in ascending bit order (`0xbde058`).
     g.set(
         "GetTradeSkillInvSlots",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let mut out = Vec::new();
-            // Each word is its `0x84dd70` token resolved off the player's own string table
-            // (decision 2045). A token the table does not carry answers the empty string rather
-            // than being dropped: the list is POSITIONAL — `GetTradeSkillInvSlotFilter(index)`
-            // indexes the same order — so a hole would shift every filter after it.
+            // A token (`0x84dd70`) missing from the string table answers "" rather than being
+            // dropped: the filter verbs index this list by position.
             for bit in present_inv_slots(&model) {
                 let word = inv_slot_token(bit)
                     .and_then(|k| crate::strings::global(lua, k))
@@ -452,9 +418,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(MultiValue::from_vec(out))
         })?,
     )?;
-    // The InvSlot pair reads/writes the shown-mask (`0x84dd64`) with the index resolving to the
-    // (index-1)-th SET bit of the accumulated present-slots mask — present slots only, ascending
-    // (TU-G §4's enumeration; `GetTradeSkillInvSlots` returns exactly that order).
+    // The inv-slot pair works on the shown mask (`0x84dd64`); index i is the i-th present slot bit
+    // (`0x4ffe60`).
     g.set(
         "GetTradeSkillInvSlotFilter",
         lua.create_function(|lua, index: usize| {
@@ -464,7 +429,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             }
             let bits = present_inv_slots(&model);
             Ok(match index.checked_sub(1) {
-                // The "all shown?" probe: (present & mask) == present (TU-G §4, `0x4fffd0`).
+                // Everything shown: (present & mask) == present (`0x4fffd0`).
                 None => era_bool(
                     bits.iter()
                         .all(|&b| model.trade_skill_invslot_mask & (1 << b) != 0),
@@ -487,8 +452,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 let bits = present_inv_slots(&model);
                 let on = on.unwrap_or(1) != 0;
                 let exclusive = exclusive.unwrap_or(0) != 0;
-                // The exact mask math per path (TU-G §4, the recovered `0x4fd730` args): all →
-                // 0xffffffff · off → old & ~(1<<b) · exclusive → 1<<b · add → old | (1<<b).
+                // The mask each path writes, as `0x4fd730` is called.
                 match index.checked_sub(1) {
                     None => model.trade_skill_invslot_mask = u32::MAX,
                     Some(n) => {
diff --git a/crates/benilla-ui/src/script/tradeskill/mod.rs b/crates/benilla-ui/src/script/tradeskill/mod.rs
index 9b7aa68e..81f04d9a 100644
--- a/crates/benilla-ui/src/script/tradeskill/mod.rs
+++ b/crates/benilla-ui/src/script/tradeskill/mod.rs
@@ -1,89 +1,8 @@
-//! The tradeskill bindings (decision 0437 phase 2) — the Era-shaped crafting-window surface driving a
-//! faithful port of the real 1.12 `TradeSkillFrame` (extracted from `interface.MPQ`:
-//! `Interface\FrameXML\Blizzard_TradeSkillUI\TradeSkillFrame.{xml,lua}`). Same two-way seam as
-//! [`super::trainer`]: the app pushes a **tradeskill snapshot** ([`UiScript::set_trade_skill`] — the
-//! recipes already resolved to name/icon/reagents/tools/color by the app from `Spell.dbc`/
-//! `SkillLineAbility.dbc`/bag counts), and the Lua `DoTradeSkill`/`CloseTradeSkill` calls queue
-//! outbound **intents** the app drains ([`UiScript::take_trade_skill_dos`] returns
-//! `(spell id, count)` pairs / [`UiScript::take_trade_skill_close`]). The engine holds no recipe
-//! knowledge — a recipe is name/icon/difficulty/reagents/tools/cooldown, all app-resolved (0437 §"The
-//! decision" item 1).
-//!
-//! ## The Era API shape (matched to the real `TradeSkillFrame.lua`)
-//!
-//! `GetTradeSkillInfo(index) → name, type, numAvailable, isExpanded`: `type` is either the recipe's
-//! difficulty color key (`"optimal"|"medium"|"easy"|"trivial"`, [`TradeSkillDifficulty::as_str`]) or
-//! `"header"` for a group row (see below); `isExpanded` is `nil` for a recipe row, `1`/`nil` for a
-//! header. `GetTradeSkillReagentInfo`/`GetTradeSkillTools`/`GetTradeSkillCooldown`/
-//! `GetTradeSkillNumMade`/`GetTradeskillRepeatCount` (note the lowercase "s" in "Tradeskill" — that
-//! IS the real 1.12 spelling) round out the detail pane; `DoTradeSkill` queues the craft,
-//! `CloseTradeSkill` is the client-side close (vanilla sends no packet here either, matching
-//! [`super::trainer`]'s `CloseTrainer` precedent).
-//!
-//! ## The grouped list — wow-re `tradeskill` TU-B, VERIFIED
-//!
-//! Unlike v1's flat render, the engine now owns the WHOLE display tree, built fresh from
-//! [`TradeSkillState::recipes`] on every query ([`build_groups`]) — [`TradeSkillState::recipes`] is
-//! just the app's flat, unordered input; its push order carries no meaning. Every recipe belongs to
-//! a group keyed by the CREATED item's `(ItemClass, ItemSubClass)`, named from `ItemSubClass.dbc`
-//! (resolved app-side — [`TradeSkillRecipe::group`]); a recipe whose product template is still in
-//! flight has no group yet (the client's own one-frame header deferral) and buckets trailing under
-//! a synthesized group keyed `(u32::MAX, u32::MAX)` with an empty name — no real `ItemClass` reaches
-//! `u32::MAX`, so it sorts last with no special-casing. Groups order by `ItemClass` id ascending,
-//! ties broken alphabetically by group name (case-insensitive, never by subclass id); within a
-//! group, recipes order by difficulty tier ascending (Optimal < Medium < Easy < Trivial — the byte
-//! tiers 0..3, [`TradeSkillDifficulty::tier`]), ties broken alphabetically by recipe name. The
-//! client's own middle tiebreak (an item-template field) is SKIPPED — the one INFERRED remainder of
-//! TU-B, named and pinned like [`TradeSkillDifficulty`]'s own INTERIM color law once was.
-//!
-//! Visible rows are each group's header (always shown) plus — for an uncollapsed group — its
-//! recipes; every index the Era API takes/returns is 1-based into THAT list (mirrors
-//! [`super::skills`]'s tree exactly: groups + collapse + visible-index remapping). `GetTradeSkillInfo`
-//! on a header row returns `(groupName, "header", 0, isExpanded)`; `GetNumTradeSkills()` counts
-//! visible rows; `GetFirstTradeSkill()` is the first NON-header visible index (`0` when none).
-//! `Expand/CollapseTradeSkillSubClass(i)` fold a group by its header's VISIBLE index (`i == 0` =
-//! ALL groups — the CollapseAll button's own call shape); the collapse set is keyed by group key
-//! ([`Model::trade_skill_collapsed`]) and survives a `set_trade_skill` content re-push (pruned to
-//! still-live groups). `GetTradeSkillSubClasses()` returns the current group names in group
-//! order — the VERIFIED filter-dropdown vocabulary IS the header list, and it never shrinks
-//! under a filter — and the `SubClassFilter`/`InvSlot` filter family is byte-VERIFIED (wow-re
-//! `tradeskill` TU-G): the subclass filter is hidden group keys (the client's per-header
-//! `+0xc` flag, position mask `0x84dd60` derived), the inv-slot filter is a shown-bit mask
-//! (`0x84dd64`) over the accumulated slot vocabulary, [`rows`] drops filtered recipes and any
-//! group left empty (a merely-collapsed group keeps its header), and every engine-side mutator
-//! (a filter set, an expand/collapse) raises the `trade_skill_touched` flag the app answers with
-//! `TRADE_SKILL_UPDATE` — the real client's in-call recompute+resort + event 0x13a (the
-//! `0x4fd710`/`0x4fd730`/`0x4fd750` writer trio). Persistence is the client's `0xbde064`-keyed
-//! story: filters, collapse, and the spell-id selection all survive a same-profession
-//! close→reopen and reset on a profession switch ([`UiScript::set_trade_skill`]). The InvSlot
-//! vocabulary folds each product's `InventoryType` through the dumped `DAT_00809200` table
-//! ([`inv_slot_mask`] — WEAPON contributes both hand bits) and names bits via the `0x84dd70`
-//! token table ([`inv_slot_name`]).
-//!
-//! Every per-recipe getter — `DoTradeSkill`, `GetTradeSkillIcon`/`NumMade`/`Cooldown`/`NumReagents`/
-//! `ReagentInfo`/`Tools` — resolves its `index` through this same visible mapping via [`recipe_at`]
-//! and no-ops/nil-shapes on a header row. **`SelectTradeSkill(i)` on a header index is IGNORED, not
-//! cleared** — the ref's own `SetSelection` toggles the fold instead of selecting (ref l.184-192,
-//! transcribed in the XML); the engine simply leaves the prior selection untouched. The selection
-//! itself is held internally as a position into the OPEN WINDOW's FLAT `recipes` list — stable
-//! across a collapse/expand (which never reorders `recipes`, only what's visible) and remapped by
-//! spell id only across a `set_trade_skill` re-push ([`selected_visible_index`] derives the current
-//! VISIBLE index from that flat position on every read, [`super::skills`]'s own by-identity
-//! persistence pattern adapted to a field this module can't change the type of).
-//!
-//! ## The tooltip channel
-//!
-//! `GameTooltip:SetTradeSkillItem(skillIndex [, reagentIndex])` is registered in
-//! [`super::tooltip_item`], beside `SetMerchantItem`, through the same id-keyed item renderer: with
-//! `reagentIndex` it resolves that recipe's reagent's item, without it the recipe's PRODUCT item. A
-//! product id of `0` (a pure-effect recipe) or an in-flight ask-once template answer both fall back to
-//! the renderer's own name-only line — the recipe's name for the product channel — rather than a
-//! no-op, since that fallback already exists and reads better than a blank hover.
-//!
-//! `skillIndex` is a **VISIBLE** index and is resolved through [`recipe_at`] (`pub(crate)` for
-//! exactly this), never a raw [`TradeSkillState::recipes`] position — headers interleave with rows
-//! since the TU-B grouping landed, so a raw index would show the wrong item the moment any group
-//! precedes the selected recipe's own. A header index resolves to `None` and the hover is a no-op.
+//! The tradeskill bindings behind the stock `Blizzard_TradeSkillUI`: the app pushes a snapshot
+//! ([`UiScript::set_trade_skill`]) with recipes resolved from `Spell.dbc`, `SkillLineAbility.dbc`
+//! and bag counts, and drains the intents `DoTradeSkill` and `CloseTradeSkill` queue. The engine
+//! owns the grouped, filtered list (`0x4fca20`); every Lua index, `SetTradeSkillItem`'s included,
+//! is 1-based into its visible rows ([`recipe_at`]).
 
 use std::collections::HashSet;
 
@@ -98,27 +17,23 @@ use view::build_groups;
 pub(super) use api::install;
 pub(crate) use view::recipe_at;
 
-/// The recipe difficulty band (the color law, computed app-side): the Lua color-table key
-/// `GetTradeSkillInfo` returns as its `type`. These four names ARE the real client's own
-/// `TradeSkillTypeColor` keys (`TradeSkillFrame.lua`); WHICH recipes land in which band (the
-/// trivial-rank cut points) is CONFIRMED at the bytes (decision 0446, wow-re `tradeskill` TU-C:
-/// gray ≥ trivialHigh, green ≥ the low/high midpoint, yellow ≥ trivialLow, orange below) — this
-/// enum is the verified Era vocabulary the app's law picks from.
+/// A recipe's difficulty band, computed app-side: gray at or above trivialHigh, green from the
+/// low/high midpoint, yellow from trivialLow, orange below (`0x4fca20`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum TradeSkillDifficulty {
-    /// Orange — a near-certain skill-up (the hardest recipes relative to current rank).
+    /// Orange: a near-certain skill-up.
     Optimal,
-    /// Yellow — a good skill-up chance.
+    /// Yellow: a good skill-up chance.
     Medium,
-    /// Green — a fading skill-up chance.
+    /// Green: a fading skill-up chance.
     Easy,
-    /// Gray — no more skill-up; still craftable for its own sake.
+    /// Gray: no skill-up.
     Trivial,
 }
 
 impl TradeSkillDifficulty {
-    /// The Era `type` string `GetTradeSkillInfo` returns for a RECIPE row (a header row returns
-    /// `"header"` instead — the module doc's grouped list).
+    /// A recipe row's `type` in `GetTradeSkillInfo`, a `TradeSkillTypeColor` key
+    /// (`Blizzard_TradeSkillUI.lua:7-10`).
     pub fn as_str(self) -> &'static str {
         match self {
             TradeSkillDifficulty::Optimal => "optimal",
@@ -128,12 +43,8 @@ impl TradeSkillDifficulty {
         }
     }
 
-    /// The byte tier a group sorts recipes by, ascending (wow-re `tradeskill` TU-B, VERIFIED):
-    /// Optimal < Medium < Easy < Trivial, 0..3. The **Craft** window's row comparators key on the
-    /// same tier byte first (`row[+0xc]`, decision 1124), which is why this is `pub(crate)` and not
-    /// private to this module: the client's two code tables are one vocabulary shifted by one
-    /// (Craft's `0` is a `"none"` tier benilla cannot produce), so the *relative* order is identical
-    /// and the shift is invisible to a comparator.
+    /// The tier byte recipes sort by, ascending (`0x4fd380`). The Craft window's comparators key on
+    /// the same order (`row[+0xc]`, shifted by one for a "none" tier), so it shares this.
     pub(crate) fn tier(self) -> u8 {
         match self {
             TradeSkillDifficulty::Optimal => 0,
@@ -144,114 +55,74 @@ impl TradeSkillDifficulty {
     }
 }
 
-/// One reagent a recipe consumes (`GetTradeSkillReagentInfo`): the bag-counted need/have plus the
-/// resolved name/icon — both `None` until the app's ask-once item-template answer lands (the same
-/// miss path as [`super::ItemTemplateView`]'s own asks), at which point the ref Lua sees the slot as
-/// blank (a `nil` name/texture hides the row's icon+text, not an error state).
+/// One reagent of a recipe, as `GetTradeSkillReagentInfo` reports it.
 #[derive(Clone, Debug, PartialEq)]
 pub struct TradeSkillReagent {
-    /// The reagent's item entry — the tooltip channel key (`GameTooltip:SetTradeSkillItem(i, j)`
-    /// resolves through this, never through `name`/`icon`).
+    /// The item entry `SetTradeSkillItem(i, j)` resolves through.
     pub item: u32,
-    /// The resolved display name, or `None` while the ask-once template answer is still in flight.
+    /// `None` until the item template arrives.
     pub name: Option<String>,
-    /// The resolved icon texture path, or `None` while still in flight.
+    /// `None` until the item template arrives.
     pub icon: Option<String>,
     /// How many this recipe consumes.
     pub need: u32,
-    /// How many the player's bags currently hold (`count_of`, decision 0269) — the row's own
-    /// have-vs-need gate, which the ref Lua grays/counts off directly.
+    /// How many the player's bags hold.
     pub have: u32,
 }
 
-/// One recipe row (`GetTradeSkillInfo` + its detail-pane getters): a known spell carrying attr
-/// `SPELL_ATTR_IS_TRADESKILL` (0437 §"What scoping verified"), resolved by the app from
-/// `Spell.dbc`/`SkillLineAbility.dbc`/bag counts into everything the window shows.
+/// One recipe: a known spell with `SPELL_ATTR_IS_TRADESKILL`, resolved app-side from `Spell.dbc`,
+/// `SkillLineAbility.dbc` and bag counts.
 #[derive(Clone, Debug, PartialEq)]
 pub struct TradeSkillRecipe {
-    /// The VERIFIED header key (wow-re `tradeskill` TU-B): the created item's `(ItemClass,
-    /// ItemSubClass)` + the resolved `ItemSubClass.dbc` display name; `None` while the product's
-    /// template is still in flight (the client's own one-frame header deferral) — [`build_groups`]
-    /// buckets those trailing under a synthesized empty-named group.
+    /// The product's `(ItemClass, ItemSubClass)` and `ItemSubClass.dbc` name, the header key
+    /// (`0x55ba30`); `None` until the product's template arrives.
     pub group: Option<(u32, u32, String)>,
-    /// The recipe spell id — what `DoTradeSkill` queues as the `CMSG_CAST_SPELL` target (one send
-    /// per item crafted, decision 0437 — there is no wire count field).
+    /// What `DoTradeSkill` casts, one `CMSG_CAST_SPELL` per item: the packet has no count.
     pub spell_id: u32,
     pub name: String,
-    /// The color band `GetTradeSkillInfo`'s `type` reports ([`TradeSkillDifficulty`]).
     pub difficulty: TradeSkillDifficulty,
-    /// `min` over reagents of `floor(have/need)` — `0` when any reagent is short (uncraftable); the
-    /// count `GetTradeSkillInfo` reports as `numAvailable`.
+    /// The least `have / need` over the reagents, reported as `numAvailable`.
     pub num_available: u32,
-    /// The product item's icon if it resolved, else the spell's own icon (an app-resolved fallback);
-    /// `None` only while both are still in flight.
+    /// The product's icon, else the spell's; `None` while neither has arrived.
     pub icon: Option<String>,
     pub min_made: u32,
     pub max_made: u32,
-    /// Remaining tradeskill cooldown in seconds (the Mooncloth-style per-recipe cooldown); `None` =
-    /// ready now (`GetTradeSkillCooldown` returns `nil`, which the ref Lua tests for truthiness).
+    /// Remaining cooldown in seconds; `None` when ready.
     pub cooldown_secs: Option<u64>,
-    /// The item entry this recipe creates — the tooltip channel key for the no-`reagentIndex` call to
-    /// `SetTradeSkillItem`; `0` = no product item (a pure-effect recipe has nothing to show there).
+    /// The created item, 0 for a pure-effect recipe.
     pub product_item: u32,
-    /// The product's `InventoryType` (item template) — the InvSlot filter's raw input, folded to
-    /// its slot-bit contribution by [`inv_slot_mask`] (the real client's
-    /// `DAT_00809200[InventoryType]` OR-accumulate + overrides, wow-re `tradeskill` TU-G §1).
-    /// `0` (non-equip, or the template still in flight) folds to the `0x800000` catch-all bit.
+    /// The product's `InventoryType`, which the inv-slot filter folds to slot bits through
+    /// `DAT_00809200` (`0x4fcee6`); 0 takes the catch-all bit.
     pub product_inv_type: u32,
-    /// The product's `ItemLevel` (item template `+0x38`) — the sort's SECONDARY key, ascending,
-    /// between the difficulty tier and the name (wow-re `tradeskill` sort law, the `record+0x14`
-    /// field identity pinned by the 2026-07-17 dispatch: the dbcache `ItemStats_C::Read 0x7c9640`
-    /// write order). `0` while the template is in flight — moot, since a template-less recipe has
-    /// no group yet and buckets trailing anyway.
+    /// The product's `ItemLevel`, the sort key between tier and name (`record+0x14`, `0x7c9640`).
     pub product_item_level: u32,
-    /// Consumed reagents, in display order (`GetTradeSkillNumReagents`/`GetTradeSkillReagentInfo`).
+    /// In display order.
     pub reagents: Vec<TradeSkillReagent>,
-    /// The Requirements line's tool list — `(tool name, have)` pairs (e.g. `("Anvil", true)`); exposed
-    /// to Lua as `GetTradeSkillTools`'s alternating multivalue, which the ref feeds into
-    /// `BuildColoredListString`.
+    /// The Requirements line's `(tool name, have)` pairs.
     pub tools: Vec<(String, bool)>,
 }
 
-/// One open tradeskill window: the skill line's name/rank and its recipe list. Pushed whole by the
-/// app ([`UiScript::set_trade_skill`]); `None` means the window is closed.
+/// One open tradeskill window, pushed whole by the app.
 #[derive(Clone, Debug, PartialEq)]
 pub struct TradeSkillState {
-    /// The skill line id (`SkillLine.dbc`) — the persistence cache key (`0xbde064`, wow-re
-    /// `tradeskill` TU-G §6): a push for a different line than the last resets the filters, the
-    /// collapse set, and the selection; the same line keeps them, across close/reopen too.
+    /// The `SkillLine.dbc` id, the persistence key (`0xbde064`).
     pub line: u32,
-    /// The skill line's display name (`SkillLine.dbc`) — e.g. `"Tailoring"`.
     pub line_name: String,
     pub rank: u32,
     pub max_rank: u32,
-    /// The window's recipe rows — the app's FLAT, UNORDERED input; the engine owns ALL ordering
-    /// (group + tier + name, the module doc's grouped-list law, wow-re `tradeskill` TU-B) and
-    /// builds the display tree fresh from this on every query ([`build_groups`]), so push order
-    /// carries no meaning. The Era API's `index` is 1-based into the synthesized VISIBLE list, never
-    /// straight into this slice — see [`recipe_at`].
+    /// Unordered: the engine sorts them (`0x4fca20`), and Lua indexes the visible rows, not this.
     pub recipes: Vec<TradeSkillRecipe>,
-    /// Remaining Create All repeats (`GetTradeskillRepeatCount`) — the client-side repeat machine's
-    /// own counter (TU-D, byte-confirmed — decision 0446), not engine-driven: the app decrements
-    /// and re-pushes as each repeat's cast resolves.
+    /// Remaining Create All repeats (`0x500230`), decremented by the app as each cast resolves.
     pub repeat_count: u32,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open tradeskill window's recipe snapshot. Snapshots re-push
-    /// every time a resolved field changes (reagent counts, ask-once answers landing, …) — no
-    /// diffing happens here.
+    /// Pushes the open window's snapshot, or `None` on close; the app re-pushes on any change.
     ///
-    /// Persistence is the real client's, byte-VERIFIED (wow-re `tradeskill` TU-G §6, keyed by the
-    /// `0xbde064` last-built-line cache): a push for a **different skill line** resets the two
-    /// filters, the collapse set, and the selection; the **same line** keeps all of them — and
-    /// because a close (`None`) touches none of that state either, they survive a close→reopen
-    /// round trip exactly like the client's statics do. The selection rides its **spell id**
-    /// (`0xbde044`'s own storage) — on every push it remaps to the id's new flat position, or
-    /// clears if the recipe vanished. The collapse/subclass-hidden key sets are pruned to the
-    /// groups the fresh recipes still produce (the client's save→restore-by-key round trip loses
-    /// exactly the keys that stopped existing); the inv-slot mask is deliberately NOT pruned —
-    /// the build never touches `0x84dd64`.
+    /// Persistence follows the reference (`0x4fc910`, keyed by `0xbde064`): a different skill line
+    /// resets filters, folds and selection, and the same line keeps them across a close. The
+    /// selection rides its spell id (`0xbde044`); fold and subclass keys are pruned to live groups,
+    /// while the inv-slot mask (`0x84dd64`) is never pruned.
     pub fn set_trade_skill(&mut self, state: Option<TradeSkillState>) {
         let mut model = self.model_mut();
         match state {
@@ -288,28 +159,21 @@ impl super::UiScript {
         }
     }
 
-    /// Drain the **(spell id, count)** intents `DoTradeSkill` queued since the last call — the engine
-    /// resolves each clicked recipe's INDEX to its spell id, so the app sends `CMSG_CAST_SPELL`
-    /// without needing the index mapping; `count` is the total the app's own client-side repeat loop
-    /// (decision 0437 §5, TU-D) turns into that many sequential sends, one per item — "Create" queues
-    /// `1`, "Create All" queues [`TradeSkillState::repeat_count`].
+    /// Drains the `(spell id, count)` crafts `DoTradeSkill` queued; the app's repeat loop
+    /// (`0x4fd7b0`) sends one cast per item.
     pub fn take_trade_skill_dos(&mut self) -> Vec<(u32, u32)> {
         std::mem::take(&mut self.model_mut().trade_skill_dos)
     }
 
-    /// Whether `CloseTradeSkill` was called since the last drain (and clear the flag). Like
-    /// [`super::trainer`]'s `CloseTrainer`, the client-side close sends no packet — the app just
-    /// clears its local tradeskill state.
+    /// Whether `CloseTradeSkill` ran since the last drain; the close sends no packet.
     pub fn take_trade_skill_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_skill_close)
     }
 
-    /// Whether an engine-side list mutator ran since the last drain (a filter set, an
-    /// expand/collapse) — the real client answers those from inside the C call with a
-    /// recompute+resort + `TRADE_SKILL_UPDATE` (the `0x4fd710`/`0x4fd730`/`0x4fd750` writer trio
-    /// → event 0x13a, wow-re `tradeskill` TU-G §3); the app drains this and fires the event the
-    /// same frame (the ref's `CollapseAllButton_OnClick` and the filter-menu clicks repaint ONLY
-    /// off that event — no direct `TradeSkillFrame_Update()` call).
+    /// Whether a filter or fold changed since the last drain. The reference re-sorts and fires
+    /// `TRADE_SKILL_UPDATE` (event `0x13a`) inside the call (`0x4fd710`, `0x4fd730`, `0x4fd750`);
+    /// the app fires it the same frame, and the stock filter and collapse-all clicks repaint only
+    /// off that event.
     pub fn take_trade_skill_touched(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trade_skill_touched)
     }
diff --git a/crates/benilla-ui/src/script/tradeskill/tests.rs b/crates/benilla-ui/src/script/tradeskill/tests.rs
index a8def0fa..0a9ab929 100644
--- a/crates/benilla-ui/src/script/tradeskill/tests.rs
+++ b/crates/benilla-ui/src/script/tradeskill/tests.rs
@@ -1,7 +1,7 @@
 use super::*;
 use crate::script::UiScript;
 
-/// One recipe fixture — a single-reagent, single-tool row, distinct spell/product ids per name.
+/// A single-reagent, single-tool recipe fixture.
 fn recipe(
     spell_id: u32,
     name: &str,
@@ -20,9 +20,8 @@ fn recipe(
         max_made: 1,
         cooldown_secs: None,
         product_item: spell_id + 10_000,
-        product_inv_type: 20, // Robe — folds to the Chest slot bit (4)
-        // Neutral by default (0 everywhere = the tie falls through to the name, the pre-verdict
-        // order every other test pins); the ItemLevel tie-break test overrides it explicitly.
+        product_inv_type: 20, // Robe: folds to the Chest slot bit (4)
+        // 0 everywhere, so ties fall through to the name; the ItemLevel test sets it.
         product_item_level: 0,
         reagents: vec![TradeSkillReagent {
             item: 2589,
@@ -35,9 +34,7 @@ fn recipe(
     }
 }
 
-/// A two-recipe, SINGLE-group Tailoring window (the original v1 fixture, now grouped under one
-/// "Cloth" header): row 1 is the header, rows 2-3 are the recipes, tier-sorted — Simple Robe
-/// (Optimal, tier 0) before Bolt of Linen Cloth (Trivial, tier 3).
+/// One "Cloth" group: row 1 the header, then Simple Robe (tier 0) and Bolt of Linen Cloth (tier 3).
 fn two_recipe_state() -> TradeSkillState {
     TradeSkillState {
         line: 197,
@@ -64,11 +61,8 @@ fn two_recipe_state() -> TradeSkillState {
     }
 }
 
-/// Four groups (wow-re `tradeskill` TU-B): class 1 "Bolts" (two Optimal-tier recipes — a NAME
-/// tie within a tier), class 2 "Armor Kit"/"Zephyr Cloak" (a CLASS tie broken by group NAME, not
-/// subclass id — "Zephyr Cloak"'s subclass id 1 is LOWER than "Armor Kit"'s 5, yet "Armor Kit"
-/// sorts first), and one recipe whose product template hasn't resolved yet (`group: None`),
-/// bucketed trailing under an empty header.
+/// Four groups: "Bolts" (class 1, a name tie within a tier); "Armor Kit" and "Zephyr Cloak"
+/// (class 2, ordered by name against their subclass ids 5 and 1); a recipe with no group yet.
 fn state() -> TradeSkillState {
     TradeSkillState {
         line: 197,
@@ -137,7 +131,7 @@ fn grouped_visible_rows_ordered_by_class_then_name_tie_then_tier_then_name() {
         ("Bolts", "header"),
         ("Alpha Bolt", "optimal"), // tier tie -> name
         ("Beta Bolt", "optimal"),
-        ("Armor Kit", "header"), // class tie -> NAME, not subclass id (5 > 1)
+        ("Armor Kit", "header"), // class tie -> name, not subclass id (5 > 1)
         ("Alpha Plate", "optimal"), // tier 0 before...
         ("Zinc Chain", "trivial"), // ...tier 3
         ("Zephyr Cloak", "header"),
@@ -160,8 +154,7 @@ fn collapse_hides_a_groups_entries_and_remaps_indices_incl_collapse_all() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
 
-    // Collapse "Armor Kit" (header at visible index 4): its two recipes vanish, 10 -> 8, and it
-    // now reports isExpanded=nil.
+    // "Armor Kit" is header 4: its two recipes go, 10 -> 8, and it reports isExpanded nil.
     s.run("CollapseTradeSkillSubClass(4)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 8);
     let (name, _, _, expanded) = s
@@ -170,20 +163,18 @@ fn collapse_hides_a_groups_entries_and_remaps_indices_incl_collapse_all() {
         )
         .unwrap();
     assert_eq!((name.as_str(), expanded), ("Armor Kit", None));
-    // "Zephyr Cloak" is now row 5 (was row 7) — the two hidden entries shift everything after.
+    // "Zephyr Cloak" moves up from row 7 to row 5.
     assert_eq!(
         row_kind(&mut s, 5),
         ("Zephyr Cloak".into(), "header".into())
     );
 
-    // Expand it back.
     s.run("ExpandTradeSkillSubClass(4)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 10);
 
-    // Collapse-all (id 0): only the 4 headers remain.
+    // Id 0 folds every group: the 4 headers remain.
     s.run("CollapseTradeSkillSubClass(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 4);
-    // Expand-all (id 0).
     s.run("ExpandTradeSkillSubClass(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 10);
 }
@@ -193,8 +184,7 @@ fn pending_recipes_bucket_trailing_under_an_empty_header() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
 
-    // The pending header (row 9): empty name, "header", numAvailable 0, expanded by default —
-    // a real group like any other (nothing has collapsed it).
+    // Row 9 is the pending group's header.
     let (name, kind, avail, expanded) = s
         .eval::<(String, String, i64, Option<i64>)>(
             "local n,t,a,e = GetTradeSkillInfo(9) return n,t,a,e",
@@ -204,10 +194,8 @@ fn pending_recipes_bucket_trailing_under_an_empty_header() {
         (name.as_str(), kind.as_str(), avail, expanded),
         ("", "header", 0, Some(1))
     );
-    // Its one recipe (row 10) reads normally.
     assert_eq!(row_kind(&mut s, 10), ("Mystery Item".into(), "easy".into()));
 
-    // It folds/unfolds exactly like a named group.
     s.run("CollapseTradeSkillSubClass(9)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 9);
 }
@@ -217,7 +205,6 @@ fn header_and_entry_tuple_shapes() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
 
-    // Header row 1 ("Bolts"): (name, "header", 0, expanded=1).
     let (name, kind, avail, expanded) = s
         .eval::<(String, String, i64, Option<i64>)>(
             "local n,t,a,e = GetTradeSkillInfo(1) return n,t,a,e",
@@ -228,7 +215,6 @@ fn header_and_entry_tuple_shapes() {
         ("Bolts", "header", 0, Some(1))
     );
 
-    // Recipe row 2 ("Alpha Bolt", optimal, numAvailable 5): (name, "optimal", 5, nil).
     let (name, kind, avail, expanded) = s
         .eval::<(String, String, i64, Option<i64>)>(
             "local n,t,a,e = GetTradeSkillInfo(2) return n,t,a,e",
@@ -245,8 +231,7 @@ fn do_trade_skill_and_getters_no_op_on_a_header_index() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
 
-    // Header row 1 ("Bolts"): every per-recipe getter reads nil/zero/empty rather than
-    // misreading through to whatever recipe happens to sit at that raw position.
+    // Row 1 is a header: every per-recipe getter reads nil, zero or empty.
     assert!(s
         .eval::<bool>("return GetTradeSkillIcon(1) == nil")
         .unwrap());
@@ -273,7 +258,7 @@ fn do_trade_skill_and_getters_no_op_on_a_header_index() {
         "a header index queues no craft"
     );
 
-    // SelectTradeSkill on a header index is IGNORED — the prior selection is untouched.
+    // A header index leaves the selection as it was.
     s.run("SelectTradeSkill(2)").unwrap(); // "Alpha Bolt", row 2
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
@@ -324,8 +309,7 @@ fn selection_persists_across_collapse_and_a_regroup() {
         8
     );
 
-    // Collapsing an EARLIER group ("Bolts", header 1) shifts every later row up two — the
-    // selection follows Wind Cloak to its new visible position, not the stale numeric index.
+    // Folding "Bolts" above it moves Wind Cloak up two rows, and the selection follows.
     s.run("CollapseTradeSkillSubClass(1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 8);
     assert_eq!(
@@ -335,15 +319,14 @@ fn selection_persists_across_collapse_and_a_regroup() {
     );
     s.run("ExpandTradeSkillSubClass(1)").unwrap();
 
-    // Collapsing Wind Cloak's OWN group ("Zephyr Cloak", back at row 7) hides the selected row:
-    // the index reads 0 without discarding the underlying selection...
+    // Folding its own group (row 7) hides it: the index reads 0, but the selection stays...
     s.run("CollapseTradeSkillSubClass(7)").unwrap();
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
             .unwrap(),
         0
     );
-    // ...expanding it again brings the SAME recipe right back into view at row 8.
+    // ...and comes back at row 8.
     s.run("ExpandTradeSkillSubClass(7)").unwrap();
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
@@ -361,8 +344,7 @@ fn selection_persists_across_collapse_and_a_regroup() {
         8
     );
 
-    // A re-push that drops the selected recipe entirely (its whole group along with it) clears
-    // the selection.
+    // A re-push without the recipe clears the selection.
     let mut without_wind_cloak = state();
     without_wind_cloak.recipes.remove(4);
     s.set_trade_skill(Some(without_wind_cloak));
@@ -383,8 +365,7 @@ fn snapshot_feeds_the_api_tuples_through_the_visible_mapping() {
             .unwrap(),
         ("Tailoring".into(), 57, 75)
     );
-    // 1 header + 2 recipes = 3 visible rows; the first NON-header row is 2 (Simple Robe, the
-    // group's tier-0 recipe).
+    // 1 header + 2 recipes; the first recipe row is 2 (Simple Robe, tier 0).
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 3);
     assert_eq!(s.eval::<i64>("return GetFirstTradeSkill()").unwrap(), 2);
 
@@ -437,7 +418,7 @@ fn selection_persists_across_a_repush_by_spell_id() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(two_recipe_state()));
 
-    // Select "Bolt of Linen Cloth" (spell 2963), the group's tier-3 row (row 3).
+    // Bolt of Linen Cloth (spell 2963) is row 3.
     s.run("SelectTradeSkill(3)").unwrap();
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
@@ -445,9 +426,7 @@ fn selection_persists_across_a_repush_by_spell_id() {
         3
     );
 
-    // Re-push with the flat array reordered (a reagent-count re-list from the app) — the
-    // ENGINE re-sorts regardless of push order, so Bolt of Linen Cloth stays visible row 3; the
-    // selection follows it there by SPELL ID, not by its (now different) flat array position.
+    // A reordered re-push: the engine re-sorts, and the selection follows the spell id to row 3.
     let mut reordered = two_recipe_state();
     reordered.recipes.swap(0, 1);
     s.set_trade_skill(Some(reordered));
@@ -457,7 +436,7 @@ fn selection_persists_across_a_repush_by_spell_id() {
         3
     );
 
-    // A re-push that drops the selected recipe entirely clears the selection.
+    // A re-push without the recipe clears the selection.
     let mut without_2963 = two_recipe_state();
     without_2963.recipes.remove(0);
     s.set_trade_skill(Some(without_2963));
@@ -478,17 +457,14 @@ fn do_trade_skill_drains_spell_id_and_count() {
     assert_eq!(s.take_trade_skill_dos(), vec![(2963, 5)]);
     assert!(s.take_trade_skill_dos().is_empty(), "drained");
 
-    // Row 2 = Simple Robe (spell 3919, numAvailable 0). No count arg defaults to 1; a
-    // non-positive count clamps up to 1 (the byte-VERIFIED latch floor, wow-re `tradeskill`
-    // TU-D — `max(avail, 1)`).
+    // Row 2 = Simple Robe (spell 3919, numAvailable 0): a missing or zero count is 1 (`0x500280`).
     s.run("DoTradeSkill(2) DoTradeSkill(2, 0)").unwrap();
     assert_eq!(s.take_trade_skill_dos(), vec![(3919, 1), (3919, 1)]);
 
-    // An out-of-range index is ignored.
     s.run("DoTradeSkill(99)").unwrap();
     assert!(s.take_trade_skill_dos().is_empty());
 
-    // A HEADER index (row 1, "Cloth") queues nothing either.
+    // Row 1 is the "Cloth" header.
     s.run("DoTradeSkill(1, 5)").unwrap();
     assert!(s.take_trade_skill_dos().is_empty());
 }
@@ -533,7 +509,6 @@ fn no_snapshot_shapes_unknown_line_and_nil_info() {
     s.run("DoTradeSkill(1, 1)").unwrap();
     assert!(s.take_trade_skill_dos().is_empty(), "no window, no intent");
 
-    // Collapse/expand/select on an empty pane are harmless no-ops.
     s.run("CollapseTradeSkillSubClass(0) ExpandTradeSkillSubClass(1) SelectTradeSkill(1)")
         .unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 0);
@@ -557,24 +532,22 @@ fn get_trade_skill_tools_multivalue_shape() {
         ("Anvil", Some(1), "Mining Pick", None)
     );
 
-    // A recipe with no tools returns an empty multivalue (arity 0, not one nil).
+    // No tools: zero values, not one nil.
     let mut t2 = two_recipe_state();
     t2.recipes[0].tools.clear();
     s.set_trade_skill(Some(t2));
     assert_eq!(s.arity("GetTradeSkillTools(3)").unwrap(), 0);
 
-    // A HEADER index (row 1) also returns an empty multivalue.
+    // A header row: zero values too.
     assert_eq!(s.arity("GetTradeSkillTools(1)").unwrap(), 0);
 }
 
-/// The verified persistence story (wow-re `tradeskill` TU-G §6, the `0xbde064` cache key):
-/// collapse/filter/selection state SURVIVES a same-profession close→reopen and resets only
-/// when a DIFFERENT skill line opens.
+/// Persistence keyed by skill line (`0x4fc910`, `0xbde064`).
 #[test]
 fn close_reopen_keeps_state_for_the_same_line_and_resets_on_a_switch() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(two_recipe_state()));
-    s.run("SelectTradeSkill(2)").unwrap(); // Simple Robe (the tier-0 row under the header)
+    s.run("SelectTradeSkill(2)").unwrap(); // Simple Robe, the tier-0 row
     s.run("CollapseTradeSkillSubClass(1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 1);
 
@@ -591,10 +564,10 @@ fn close_reopen_keeps_state_for_the_same_line_and_resets_on_a_switch() {
         0
     );
 
-    // Reopen the SAME line: the fold survives the round trip (header only, still collapsed)…
+    // The same line: the fold survives...
     s.set_trade_skill(Some(two_recipe_state()));
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 1);
-    // …and so does the selection, by spell id: expand and it's visible index 2 again.
+    // ...and so does the selection, by spell id.
     s.run("ExpandTradeSkillSubClass(1)").unwrap();
     assert_eq!(
         s.eval::<i64>("return GetTradeSkillSelectionIndex()")
@@ -602,7 +575,7 @@ fn close_reopen_keeps_state_for_the_same_line_and_resets_on_a_switch() {
         2
     );
 
-    // A DIFFERENT line resets everything: fully expanded, nothing selected.
+    // A different line resets everything.
     s.run("CollapseTradeSkillSubClass(1)").unwrap();
     let mut other = two_recipe_state();
     other.line = 164; // Blacksmithing
@@ -615,9 +588,7 @@ fn close_reopen_keeps_state_for_the_same_line_and_resets_on_a_switch() {
     );
 }
 
-/// The SubClass filter (ref Blizzard_TradeSkillUI.lua l.406-408): an exclusive set shows only
-/// that group; the vocabulary (`GetTradeSkillSubClasses`) never shrinks; `Get(0)` answers the
-/// all-shown probe; `Set(0, 1, 1)` (the "All Subclasses" row) restores everything.
+/// The subclass filter as the stock menu drives it (`Blizzard_TradeSkillUI.lua:406-409`).
 #[test]
 fn subclass_filter_exclusive_narrows_list_but_not_vocabulary() {
     let mut s = UiScript::new().unwrap();
@@ -652,7 +623,7 @@ fn subclass_filter_exclusive_narrows_list_but_not_vocabulary() {
         1
     );
 
-    // The "All Subclasses" row's own call shape restores everything.
+    // The "All Subclasses" row's call restores everything.
     s.run("SetTradeSkillSubClassFilter(0, 1, 1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 10);
     assert_eq!(
@@ -662,12 +633,9 @@ fn subclass_filter_exclusive_narrows_list_but_not_vocabulary() {
     );
 }
 
-/// A stand-in string table for the `0x84dd70` token family — **deliberately not the shipped
-/// wording**, because what these tests establish is *which token* each slot bit reaches, never
-/// what the word says (decision 2045, "assert the identifier, not the sentence"). Naming each
-/// value after its own key is the point: `SECONDARYHANDSLOT`, `INVTYPE_SHIELD` and
-/// `INVTYPE_WEAPONOFFHAND` all read "Off Hand" in enUS, so an assertion on the English could not
-/// tell a correct table from one wired to the item tooltip's family.
+/// Stand-in slot strings named after their tokens (`0x84dd70`): `SECONDARYHANDSLOT`,
+/// `INVTYPE_SHIELD` and `INVTYPE_WEAPONOFFHAND` all read "Off Hand" in enUS, so only the token
+/// shows which one a bit reaches.
 fn seed_slot_tokens(s: &mut UiScript) {
     s.run(
         r#"
@@ -687,9 +655,6 @@ fn seed_slot_tokens(s: &mut UiScript) {
     .unwrap();
 }
 
-/// The InvSlot filter: the vocabulary is the distinct slot words ascending by slot bit; an
-/// exclusive set drops every recipe on other slots AND any group that empties — header
-/// included.
 #[test]
 fn invslot_filter_drops_recipes_and_emptied_groups() {
     let mut s = UiScript::new().unwrap();
@@ -728,9 +693,7 @@ fn invslot_filter_drops_recipes_and_emptied_groups() {
     assert_eq!(s.eval::<i64>("return GetNumTradeSkills()").unwrap(), 10);
 }
 
-/// WEAPON (InventoryType 13) is the one multi-bit contribution (`0x18000`, TU-G §1): a
-/// one-hand weapon lists BOTH hand slots in the vocabulary and stays visible under either
-/// hand's exclusive filter.
+/// A one-hand weapon (InventoryType 13, `0x18000`) lists both hand slots and passes either.
 #[test]
 fn one_hand_weapon_spans_both_hand_slots() {
     let mut s = UiScript::new().unwrap();
@@ -758,8 +721,8 @@ fn one_hand_weapon_spans_both_hand_slots() {
     );
 }
 
-/// Every engine-side list mutator raises the touched flag exactly once per drain — the app's
-/// cue to fire TRADE_SKILL_UPDATE (the `0x4fd710`/`0x4fd750` in-call event, module doc).
+/// Each filter or fold raises the flag the app answers with TRADE_SKILL_UPDATE (`0x4fd710`,
+/// `0x4fd750`).
 #[test]
 fn filter_and_fold_mutators_raise_the_touched_flag() {
     let mut s = UiScript::new().unwrap();
@@ -779,10 +742,7 @@ fn filter_and_fold_mutators_raise_the_touched_flag() {
     assert!(s.take_trade_skill_touched());
 }
 
-/// The sort's SECONDARY key is the product's ItemLevel, ascending — between the difficulty tier
-/// and the name (the `record+0x14` = item template ItemLevel identity, pinned 2026-07-17). Two
-/// same-tier recipes whose ALPHABETICAL order contradicts their item levels must order by level;
-/// equal levels fall through to the name.
+/// ItemLevel (`record+0x14`) sorts between tier and name.
 #[test]
 fn same_tier_recipes_order_by_product_item_level_before_name() {
     let mut s = UiScript::new().unwrap();
@@ -828,17 +788,12 @@ fn same_tier_recipes_order_by_product_item_level_before_name() {
     assert_eq!(names, ["Cloth", "Mmm Robe", "Zzz Robe", "Aaa Robe"]);
 }
 
-/// The link pair (wow-re `tradeskill-craft-item-links.md`, 1973): the product's link in its
-/// quality colour with zero tokens; ZERO values for a header, a missing product or an uncached
-/// template; the reagent link nil on the same misses and always exactly one value; the typo'd
-/// reagent Usage; the number gate.
+/// The two link verbs' shapes (`0x4ff410`, `0x4ff800`).
 #[test]
 fn the_link_verbs_answer_the_clients_shapes() {
     let mut s = UiScript::new().unwrap();
     s.set_trade_skill(Some(state()));
-    // Row 1 is a header; row 2 the first VISIBLE recipe — found by the name the API answers for
-    // it, since the visible order is the grouped one, not the pushed one. Seed its product's and
-    // one reagent's templates.
+    // Row 2 is the first recipe, found by name since the visible order is the sorted one.
     let st = state();
     let row2 = s.eval::<String>("return (GetTradeSkillInfo(2))").unwrap();
     let r = st
diff --git a/crates/benilla-ui/src/script/tradeskill/view.rs b/crates/benilla-ui/src/script/tradeskill/view.rs
index 7fec6269..798e4082 100644
--- a/crates/benilla-ui/src/script/tradeskill/view.rs
+++ b/crates/benilla-ui/src/script/tradeskill/view.rs
@@ -1,6 +1,5 @@
-//! The display-tree + filter machinery: grouping/sorting the flat `TradeSkillRecipe` list into the
-//! visible-row tree the Era API indexes (see the parent module doc — the grouped-list law and the
-//! byte-VERIFIED `SubClassFilter`/`InvSlot` filter family, wow-re `tradeskill` TU-B/TU-G).
+//! The visible rows the tradeskill API indexes: grouping, sorting and filtering the flat recipes
+//! (`0x4fca20`, `0x4fd180`).
 
 use std::collections::HashMap;
 
@@ -8,13 +7,9 @@ use crate::script::Model;
 
 use super::TradeSkillRecipe;
 
-/// Fold a product's `InventoryType` to its InvSlot-filter contribution (`record+0x10`) — the
-/// real client's 29-entry `DAT_00809200` table with its build-time overrides, dumped in full and
-/// byte-VERIFIED (wow-re `tradeskill` TU-G §1): FINGER/TRINKET/BAG collapse to their first slot's
-/// single bit (`0xb → 0x400`, `0xc → 0x1000`, `0x12 → 0x80000` — the raw table's multi-slot
-/// entries are dead, overwritten before use), zero contributions (NON_EQUIP/AMMO/QUIVER) take the
-/// `0x800000` catch-all (bit 23), and **WEAPON (13) is the one multi-bit survivor** — `0x18000`,
-/// a one-hand weapon shows under both hand slots.
+/// A product's `InventoryType` as inv-slot filter bits (`record+0x10`): the client's 29-entry
+/// table at `0x809200` after its overrides, so finger, trinket and bag take one bit each, a
+/// one-hand weapon sets both hand bits, and non-equipment takes the catch-all bit 23.
 fn inv_slot_mask(inv_type: u32) -> u32 {
     match inv_type {
         1 => 1 << 0,                  // HEAD
@@ -27,34 +22,22 @@ fn inv_slot_mask(inv_type: u32) -> u32 {
         8 => 1 << 7,                  // FEET
         9 => 1 << 8,                  // WRIST
         10 => 1 << 9,                 // HANDS
-        11 => 1 << 10,                // FINGER (override — single bit)
-        12 => 1 << 12,                // TRINKET (override — single bit)
-        13 => (1 << 15) | (1 << 16),  // WEAPON — both hands (0x18000)
+        11 => 1 << 10,                // FINGER (override: single bit)
+        12 => 1 << 12,                // TRINKET (override: single bit)
+        13 => (1 << 15) | (1 << 16),  // WEAPON: both hands (0x18000)
         14 | 22 | 23 => 1 << 16,      // SHIELD / WEAPONOFFHAND / HOLDABLE
         15 | 25 | 26 | 28 => 1 << 17, // RANGED / THROWN / RANGEDRIGHT / RELIC
         16 => 1 << 14,                // CLOAK (back)
         17 | 21 => 1 << 15,           // 2HWEAPON / WEAPONMAINHAND
-        18 => 1 << 19,                // BAG (override — single bit)
+        18 => 1 << 19,                // BAG (override: single bit)
         19 => 1 << 18,                // TABARD
-        _ => 1 << 23,                 // NON_EQUIP / AMMO / QUIVER / unknown — the catch-all
+        _ => 1 << 23,                 // NON_EQUIP / AMMO / QUIVER / unknown: the catch-all
     }
 }
 
-/// The InvSlot dropdown's per-bit GlobalString **token** — the real client's 24-entry table
-/// (`0x84dd70`, byte-VERIFIED — wow-re `tradeskill` TU-G §2), dumped entry by entry. The caller
-/// resolves it against the player's own `GlobalStrings.lua` (decision 2045); these are the
-/// paper-doll `*SLOT` family, **not** the `INVTYPE_*` family the item tooltip's slot line uses,
-/// and that distinction is exactly why the word cannot be stored here: `SECONDARYHANDSLOT`,
-/// `INVTYPE_SHIELD` and `INVTYPE_WEAPONOFFHAND` are three separately-localizable strings that all
-/// read "Off Hand" in enUS.
-///
-/// Bits 11/13/20-22 (`FINGER1SLOT`/`TRINKET1SLOT`/the extra `BAGSLOT`s) are present in the table
-/// but unreachable through [`inv_slot_mask`] — kept for the full 24-entry fidelity.
-///
-/// **`None` is the out-of-range arm and is unreachable by construction**: the only caller walks
-/// [`present_inv_slots`], which enumerates bits 0..23, and the reference's table has an entry for
-/// every one of them. It resolves to the empty string at the call site, which is what
-/// `FrameScript_GetText` hands back for a token the table has no row for.
+/// The inv-slot dropdown's `GlobalStrings.lua` token per bit, the client's 24-entry table at
+/// `0x84dd70`: the paper-doll `*SLOT` names, not the tooltip's `INVTYPE_*` ones. Bits 11, 13 and
+/// 20-22 are in the table, but no `InventoryType` reaches them.
 pub(super) fn inv_slot_token(bit: u32) -> Option<&'static str> {
     Some(match bit {
         0 => "HEADSLOT",
@@ -82,10 +65,8 @@ pub(super) fn inv_slot_token(bit: u32) -> Option<&'static str> {
     })
 }
 
-/// The InvSlot filter vocabulary: the set bits of the accumulated slot mask, ascending — the real
-/// client's bits-0..23 walk over `0xbde058` (`GetTradeSkillInvSlots 0x4ffc20`, TU-G §2).
-/// Accumulated over ALL recipes, unfiltered — the mask ORs up at list build, before any filter
-/// applies.
+/// The inv-slot vocabulary: the set bits, ascending, of the slot mask over all recipes, unfiltered
+/// (`0xbde058`, walked by `GetTradeSkillInvSlots`, `0x4ffc20`).
 pub(super) fn present_inv_slots(model: &Model) -> Vec<u32> {
     let Some(t) = model.trade_skill.as_ref() else {
         return Vec::new();
@@ -97,9 +78,8 @@ pub(super) fn present_inv_slots(model: &Model) -> Vec<u32> {
     (0..24).filter(|b| accum & (1 << b) != 0).collect()
 }
 
-/// Whether a recipe passes the current filters (the recompute's own row test, TU-G §5): its slot
-/// contribution overlaps the shown-mask (`record+0x10 & 0x84dd64 != 0`) and its group isn't
-/// subclass-hidden.
+/// The recompute's row test (`0x4fd180`): the slot bits meet the shown mask (`0x84dd64`) and the
+/// group is not hidden.
 fn passes_filters(model: &Model, r: &TradeSkillRecipe) -> bool {
     let key = r
         .group
@@ -109,40 +89,27 @@ fn passes_filters(model: &Model, r: &TradeSkillRecipe) -> bool {
         && inv_slot_mask(r.product_inv_type) & model.trade_skill_invslot_mask != 0
 }
 
-/// One recipe group in the synthesized display tree (wow-re `tradeskill` TU-B): the created item's
-/// `(ItemClass, ItemSubClass)` key (the collapse key) + resolved display name, and the positions
-/// (into [`TradeSkillState::recipes`]) of the group's recipes, pre-sorted by tier, product
-/// ItemLevel, then name.
-/// Engine-internal — rebuilt fresh from the flat recipes on every query ([`build_groups`]) rather
-/// than cached on [`Model`] (unlike [`super::skills::SkillGroup`]): `TradeSkillState` has no
-/// engine-owned tree field of its own, so [`Row::Header`] just carries the group's key/name
-/// directly instead of an index into a cached `Vec`.
+/// One recipe group (`0x4fca20`), keyed by the product's `(ItemClass, ItemSubClass)` and rebuilt
+/// on every query.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(super) struct TradeSkillGroup {
     pub(super) key: (u32, u32),
     pub(super) name: String,
-    /// Positions into [`TradeSkillState::recipes`], sorted by tier, product ItemLevel, then
-    /// [`collate`]d name.
+    /// Positions into `TradeSkillState::recipes`, in display order.
     entries: Vec<usize>,
 }
 
-/// The WoW enUS collator, approximated ([`super::skills`]/[`super::trainer`]'s own helper,
-/// duplicated here rather than shared — each seam module keeps its own copy, the established local
-/// convention): case-insensitive alphabetical, raw bytes as a stable tie-break.
+/// An approximation of the reference's name compare, the case-insensitive `0x64a4c0`:
+/// case-insensitive, then raw bytes.
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
         .then_with(|| a.cmp(b))
 }
 
-/// Build the display tree from the flat recipes (the module doc's grouped-list law, wow-re
-/// `tradeskill` TU-B): group by the created item's `(ItemClass, ItemSubClass)` — a recipe with no
-/// group yet (`group: None`, its product template still in flight) buckets into the trailing
-/// `(u32::MAX, u32::MAX)`/`""` group; sort each group's recipes by tier, then the product's
-/// **ItemLevel ascending** (the `record+0x14` secondary key — field identity pinned 2026-07-17,
-/// [`TradeSkillRecipe::product_item_level`]), then [`collate`]d name; sort the groups by
-/// `ItemClass` id ascending, ties broken by [`collate`]d name (never by subclass id — the pending
-/// group's `u32::MAX` class id sorts it last with no special-casing needed).
+/// The groups in display order (`0x4fca20`): by `ItemClass`, then name, never subclass id; each
+/// group's recipes by tier, product ItemLevel (`record+0x14`), then name. A recipe with no group
+/// yet goes into an empty-named group keyed `u32::MAX`, which sorts last.
 pub(super) fn build_groups(recipes: &[TradeSkillRecipe]) -> Vec<TradeSkillGroup> {
     let mut map: HashMap<(u32, u32), TradeSkillGroup> = HashMap::new();
     for (i, r) in recipes.iter().enumerate() {
@@ -183,22 +150,16 @@ pub(super) fn build_groups(recipes: &[TradeSkillRecipe]) -> Vec<TradeSkillGroup>
     groups
 }
 
-/// One visible row of the display tree: a group **header** (carrying its key/name — see
-/// [`TradeSkillGroup`]'s own doc for why this isn't an index) or a **recipe** (carrying its
-/// position into [`TradeSkillState::recipes`]).
+/// One visible row: a group header, or a recipe's position in `TradeSkillState::recipes`.
 #[derive(Clone)]
 pub(super) enum Row {
     Header { key: (u32, u32), name: String },
     Entry(usize),
 }
 
-/// The visible rows in display order: each group's header, then — when the group isn't
-/// collapsed — its recipes that pass the filters ([`passes_filters`]). A subclass-hidden group,
-/// or one whose every recipe the InvSlot filter drops, contributes NO rows at all — header
-/// included (the real window never shows an empty header under a filter — the visibility law
-/// decision 0452 landed byte-exact, wow-re `tradeskill` TU-G: filtered recipes and emptied/
-/// filtered headers drop out of the numbered list; a merely-collapsed header stays). The Lua's
-/// 1-based `index` is a position in *this* list. Empty when no window is open.
+/// The visible rows every Lua index is 1-based into: each group's header, then its recipes that
+/// pass the filters unless it is folded. A group the filters empty loses its header too; a merely
+/// folded one keeps it (`0x4fd180`).
 pub(super) fn rows(model: &Model) -> Vec<Row> {
     let Some(t) = model.trade_skill.as_ref() else {
         return Vec::new();
@@ -230,19 +191,12 @@ pub(super) fn rows(model: &Model) -> Vec<Row> {
     out
 }
 
-/// The count of visible rows (headers + the recipes of uncollapsed groups).
 pub(super) fn num_rows(model: &Model) -> usize {
     rows(model).len()
 }
 
-/// The recipe at a 1-based VISIBLE index, or `None` when that row is a header (or OOB) — so every
-/// per-recipe getter/`DoTradeSkill` safely no-ops on a header row (wow-re `tradeskill` TU-B).
-///
-/// `pub(crate)`: the tooltip channel (`super::tooltip_item`'s `SetTradeSkillItem`) SHOULD route
-/// through this too — a header index, or the header rows preceding a real recipe, would otherwise
-/// misalign a raw `TradeSkillState::recipes` index against the visible list the XML actually clicks
-/// through. See the module doc's "KNOWN GAP" note: that follow-up isn't done here (out of this
-/// change's file scope), but the seam is exposed for it.
+/// The recipe at a 1-based visible index; `None` on a header, so the per-recipe verbs and
+/// `SetTradeSkillItem` no-op there.
 pub(crate) fn recipe_at(model: &Model, index: usize) -> Option<&TradeSkillRecipe> {
     let n = index.checked_sub(1)?;
     match rows(model).get(n)? {
@@ -251,7 +205,7 @@ pub(crate) fn recipe_at(model: &Model, index: usize) -> Option<&TradeSkillRecipe
     }
 }
 
-/// The first NON-header visible index (`GetFirstTradeSkill`'s law), `0` when none.
+/// `GetFirstTradeSkill`: the first recipe row's visible index, 0 when none.
 pub(super) fn first_recipe_index(model: &Model) -> u32 {
     rows(model)
         .iter()
@@ -259,13 +213,8 @@ pub(super) fn first_recipe_index(model: &Model) -> u32 {
         .map_or(0, |p| (p + 1) as u32)
 }
 
-/// `GetTradeSkillSelectionIndex()` — the CURRENT visible index of the engine-held selection (`0`
-/// when nothing is selected, or the selected recipe isn't visible right now, e.g. its group just got
-/// collapsed). [`Model::trade_skill_selection`] holds a stable position into the open window's FLAT
-/// `recipes` list (module doc) — collapse/expand never touches it, only what [`rows`] shows, so this
-/// derives the visible position fresh on every read rather than needing an eager remap on every
-/// collapse toggle ([`super::skills`]'s own by-identity pattern, adapted to a field this module can't
-/// change the type of).
+/// `GetTradeSkillSelectionIndex`: the selection's visible index, 0 when none or hidden. The
+/// selection is held as a flat recipe position, so a fold never moves it.
 pub(super) fn selected_visible_index(model: &Model) -> u32 {
     let Some(pos) = model.trade_skill_selection.checked_sub(1) else {
         return 0;
@@ -276,19 +225,15 @@ pub(super) fn selected_visible_index(model: &Model) -> u32 {
         .map_or(0, |p| (p + 1) as u32)
 }
 
-/// `SelectTradeSkill(index)` — resolve the 1-based VISIBLE index to a position in the open window's
-/// flat recipe list and hold THAT ([`selected_visible_index`]'s own doc). A HEADER row is IGNORED —
-/// the prior selection is left exactly as it was (the module doc: the ref's own `SetSelection`
-/// toggles the fold instead of selecting, so a header index never reaches here through the XML in
-/// practice, but the engine contract holds regardless). An out-of-range index clears the selection
-/// (the pre-existing convention, unchanged).
+/// `SelectTradeSkill`: holds the recipe at a visible index. A header index leaves the selection
+/// as it was, and an out-of-range one clears it; the stock Lua folds a header instead of selecting
+/// it (`Blizzard_TradeSkillUI.lua:184-192`).
 pub(super) fn select(model: &mut Model, index: u32) {
     let visible = rows(model);
     match index.checked_sub(1).and_then(|n| visible.get(n as usize)) {
         Some(Row::Entry(ei)) => {
             model.trade_skill_selection = (*ei + 1) as u32;
-            // The spell-id shadow (`0xbde044`'s own storage) — what survives a close→reopen and
-            // remaps across a re-push ([`super::UiScript::set_trade_skill`]).
+            // The spell id (`0xbde044`) is what survives a close and remaps across a re-push.
             model.trade_skill_selected_spell = model
                 .trade_skill
                 .as_ref()
@@ -303,11 +248,8 @@ pub(super) fn select(model: &mut Model, index: u32) {
     }
 }
 
-/// Collapse (`collapse = true`) or expand a group by the **display index of its header row**
-/// ([`super::skills`]'s own `Collapse/ExpandSkillHeader` shape). `id == 0` targets ALL groups (the
-/// CollapseAll semantics — no such button ships this slice, the XML's own deviation note); `id > 0`
-/// resolves the header at that visible index to its group key. A non-header (or OOB) index is a
-/// no-op.
+/// Folds or unfolds the group whose header is visible row `id`; 0 is every group, as the stock
+/// collapse-all button passes, and any other row is a no-op.
 pub(super) fn set_collapsed(model: &mut Model, id: usize, collapse: bool) {
     if id == 0 && !collapse {
         model.trade_skill_collapsed.clear();
diff --git a/crates/benilla-ui/src/script/trainer/mod.rs b/crates/benilla-ui/src/script/trainer/mod.rs
index abc3f3cc..070b1f75 100644
--- a/crates/benilla-ui/src/script/trainer/mod.rs
+++ b/crates/benilla-ui/src/script/trainer/mod.rs
@@ -1,97 +1,24 @@
-//! The trainer bindings (decision 0237) — the Era-shaped class/profession trainer surface driving a
-//! faithful port of the real 1.12 `ClassTrainerFrame` (extracted from `interface.MPQ`:
-//! `Interface\FrameXML\ClassTrainerFrame.{xml,lua}`). Same two-way seam as [`super::merchant`]: the
-//! app pushes a **trainer snapshot** ([`UiScript::set_trainer`] — the wire services already resolved
-//! to name/icon/cost/state/requirements by the app), and the Lua `BuyTrainerService`/`CloseTrainer`
-//! calls queue outbound **intents** the app drains ([`UiScript::take_trainer_buys`] returns the
-//! chosen services' **spell ids** / [`UiScript::take_trainer_close`]). The engine holds no trainer
-//! knowledge — a service is name/subtext/icon/cost/state/gates/description, all app-resolved.
-//!
-//! ## The Era API shape (matched to the real `ClassTrainerFrame.lua`)
-//!
-//! The reference window's `.lua` is transcribed onto these bindings, so the return *shapes* match it
-//! verbatim: `GetTrainerServiceInfo → name, subText, serviceType, isExpanded`;
-//! `GetTrainerServiceCost → money, talentPointCost, professionPointCost`;
-//! `GetTrainerServiceSkillReq → skill, rank, hasReq`; `GetTrainerServiceAbilityReq → name, hasReq`;
-//! `IsTrainerServiceLearnSpell → isLearnSpell, isPetLearnSpell`. `serviceType` is either the string
-//! `"header"` (a skill-line group header, with `isExpanded` set) or the service's colour state
-//! `"available"`/`"unavailable"`/`"used"` (green/red/gray, `isExpanded` nil).
-//!
-//! ## The tree (decisions 0247 + 1124 — the byte-verified grouping/sort model, **per trainer type**)
-//!
-//! The 1.12 wire (`SMSG_TRAINER_LIST`) is a **flat** service list; the client builds a **collapsible
-//! tree** on top of it, and `index` is **1-based into that visible tree**, not the wire order.
-//! [`UiScript::set_trainer`] takes the flat services (each already carrying its app-resolved
-//! [`TrainerService::group_key`]/[`TrainerService::group_name`]) and synthesizes the tree: one
-//! **header row per distinct group key**, then that group's services in the group's own order. State
-//! is a per-row **colour**, never the grouping key.
-//!
-//! **The `trainerType` selects everything** — the list finalizer `0x4d8410` picks the row comparator
-//! by `ds:0xb73a08` (`dec eax; je` chain @ `0x4d8561`) and the builder `0x4d7560` picks both the
-//! group key and the header comparator by the same dword (`0x4d7786`, `0x4d79eb`). Neither the group
-//! key nor the sort is one law with a "later refinement" — they are four laws, and 1124 is where
-//! benilla stopped applying the class one to all of them:
-//!
-//! | type | rows | headers | group key |
-//! |---|---|---|---|
-//! | 0 class, 3 pet | `0x4d85c0` — level → skill value → name → rank | `0x4d7b90`, by name | taught spell's `SkillLine` |
-//! | 1 mount ("talent") | `0x4d8850` — **state byte → name** | `0x4d7b90`, `-1` first then by name | `-1` when the service is `used`, else the `SkillLine` |
-//! | 2 tradeskill | `0x4d8760` — **skill value → name**, no level key, no rank key | `0x4d7c30`, by **raw key asc** | **1 or 2**, see below |
-//!
-//! At type 2 the group key is **not a skill line and never resolves one**: the builder defaults it
-//! to 2 and sets it to 1 iff the **wire** spell's own `Spell.dbc Effect[0..2]` contains `44`
-//! `SKILL_STEP` (`0x4d77b6`), which makes exactly two groups — `TRADESKILL_SERVICE_STEP` ("Development
-//! Skills", the profession-learn services) and `TRADESKILL_SERVICE_LEARN` ("Recipes") — and means
-//! **no row is ever dropped at a tradeskill trainer**. That partition, not a level key, is what puts
-//! "Apprentice Blacksmith" at the top of a blacksmithing trainer: `reqLevel` is inert at type 2.
-//! At the other types a service whose group key is `0` (unresolved skill line) is still dropped,
-//! matching the client.
-//!
-//! A service hides when its state fails the dropdown filter ([`Model::trainer_filter`]) or its group
-//! is collapsed ([`Model::trainer_collapsed`]) — but **hiding is not removing**: the client parks a
-//! hidden record in a tail behind the visible ones and keeps its index, so `GetNumTrainerServices`
-//! answers with the *visible* count while every getter's index space is the *whole* array ([`rows`]).
-//! An index past the count is a legal hidden row, and the stock window is handed exactly one after a
-//! purchase ([`selected_row`]). `Collapse/ExpandTrainerSkillLine(id)` take the **display index of a
-//! header row** (`id == 0` = all groups — the collapse-all button); they toggle that group's
-//! visibility, never reorder.
-//!
-//! The **selection** is likewise the selected service's **spell id** (`ds:0xb73a0c`), re-resolved to
-//! a position on every `GetTrainerSelectionIndex` — never a stored row number ([`selected_row`]).
-//!
-//! ## Faithful stubs (no wire data yet — kept so the ported XML runs)
-//!
-//! `GetTrainerServiceStepReq` returns nil (no tradeskill-step data on the wire), and per-requirement
-//! `hasReq`/`met` flags are derived from the service's overall `category` (an unavailable service has
-//! an unmet gate) rather than a per-gate wire bit, which 5875 does not send.
-//!
-//! One thing the client does that this engine does not, named rather than left to be discovered: a
-//! group whose row counters go to zero **vanishes entirely, header included** (`0x4d8460`,
-//! `0x4d8528`–`0x4d8549`) — which is how a type-1 trainer whose every service is `used` shows one
-//! "My Talents" header and no skill-line headers at all. benilla always keeps a header. The case
-//! that is *reachable* here (does the state-filter dropdown emptying a group also take its header?)
-//! is an open question with wow-re; the build-time case above cannot arise, because benilla builds
-//! a group only from services that exist.
+//! The trainer bindings the stock `Blizzard_TrainerUI` window calls, over the snapshot the app
+//! pushes ([`UiScript::set_trainer`]). `SMSG_TRAINER_LIST` is flat; the client builds a collapsible
+//! tree of header and service rows over it, every Lua index is 1-based into that tree, and the
+//! trainer type (`ds:0xb73a08`) picks the row comparator (`0x4d8561`), the group key and the
+//! header comparator (`0x4d7786`, `0x4d79eb`).
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// The green/red/gray state of a service (the wire's `TrainerSpellState`, decision 0237), surfaced to
-/// Lua as the Era `category` string `GetTrainerServiceInfo` returns.
+/// A service's state (the wire's `TrainerSpellState`): green learnable, red gated, gray known.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum TrainerServiceCategory {
-    /// Green — learnable now.
     #[default]
     Available,
-    /// Red — a requirement (level / skill / prerequisite) is unmet.
     Unavailable,
-    /// Gray — already known.
     Used,
 }
 
 impl TrainerServiceCategory {
-    /// The Era `category` string (`ClassTrainerFrame`'s colour switch reads exactly these).
+    /// `GetTrainerServiceInfo`'s type string, which the stock window colours each row by.
     fn era_str(self) -> &'static str {
         match self {
             TrainerServiceCategory::Available => "available",
@@ -109,10 +36,8 @@ impl TrainerServiceCategory {
         }
     }
 
-    /// The row's **state byte** `[+0x30]` — the value `0x4d8ba0` maps to the colour string (`0` →
-    /// available, `2` → used, anything else → unavailable). It is a colour on every trainer type but
-    /// one: at type 1 it is also the third sort key ([`talent_order`]), which is why this exists
-    /// separately from the filter slot it numerically coincides with.
+    /// The record's state byte `[+0x30]`, which `0x4d8ba0` maps to the type string; at type 1 it is
+    /// also a sort key ([`talent_order`]), so it stays apart from the equal filter slot.
     fn state_key(self) -> u8 {
         match self {
             TrainerServiceCategory::Available => 0,
@@ -121,7 +46,6 @@ impl TrainerServiceCategory {
         }
     }
 
-    /// Parse the Era filter-type string the sort checkboxes pass.
     fn from_filter_str(s: &str) -> Option<Self> {
         match s {
             "available" => Some(TrainerServiceCategory::Available),
@@ -132,8 +56,8 @@ impl TrainerServiceCategory {
     }
 }
 
-/// A skill-line requirement on a service (`GetTrainerServiceSkillReq`): the skill's display name, the
-/// rank required, and whether the player meets it (`hasReq`, derived from the service `category`).
+/// A service's skill requirement (`GetTrainerServiceSkillReq`). The wire has no per-gate bit, so
+/// `met` comes from the service's `category`.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct TrainerSkillReq {
     pub name: String,
@@ -141,38 +65,27 @@ pub struct TrainerSkillReq {
     pub met: bool,
 }
 
-/// A prerequisite-ability requirement (`GetTrainerServiceAbilityReq`): the ability's display name and
-/// whether the player has it (`hasReq`).
+/// A prerequisite ability (`GetTrainerServiceAbilityReq`); `met` is whether the player knows it.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct TrainerAbilityReq {
     pub name: String,
     pub met: bool,
 }
 
-/// What `GameTooltip:SetTrainerService` describes for one row — the pre-resolved output of the
-/// **app-side** tooltip law (`ui_trainer::service_tooltip`, transcribing `SetTrainerService
-/// 0x5338b0`). The engine holds no DBC, so the app decides the subject and the engine only picks a
-/// renderer; the binding in the real client does exactly that too — it emits no line of its own and
-/// is a three-way selector into the shared spell builder `0x52e610` or item builder `0x52b650`.
-///
-/// This is deliberately **not** derivable from [`TrainerService::texture`]: the tooltip and the icon
-/// disagree, by design and in both directions (wow-re `ui/scratch/trainer-service-tooltip-law.md`
-/// §6 — the icon needs a trainer-type gate the tooltip does not have, and the icon pins the *wire*
-/// wrapper where the tooltip hops to the *taught* spell). On ~806 of the shipped corpus's trainer
-/// services the reference client visibly shows one spell's icon above another spell's tooltip.
+/// What `GameTooltip:SetTrainerService` (`0x5338b0`) describes for a row, resolved by the app; the
+/// reference only picks the spell builder `0x52e610` or the item builder `0x52b650`. Not derivable
+/// from [`TrainerService::texture`]: the icon (`0x4d8f50`) gates on the trainer type and shows the
+/// wire spell, while the tooltip describes the taught one.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum TrainerTooltip {
-    /// The ITEM builder, on this item id — the taught spell carries `SPELL_ATTR_IS_TRADESKILL`.
-    /// `0` (or a template still in flight) renders an EMPTY tooltip, which is the client's own
-    /// behaviour: the builder early-outs on a cache miss and the query is enqueued.
+    /// The item builder on this item id, for a taught spell with `SPELL_ATTR_IS_TRADESKILL`; 0 or
+    /// an uncached template renders empty, as the reference's builder does on a cache miss.
     Item(u32),
-    /// The SPELL builder, on the taught spell — or on the wire spell itself when no learn-wrapper
-    /// slot resolved, the only path that describes the wrapper.
+    /// The spell builder on the taught spell, or on the wire spell when no learn slot resolved.
     Spell {
         spell_id: u32,
-        /// `param5` altCaster — ONE gate suppressing BOTH the totems and the reagents lines
-        /// (byte-verified at `0x52ed43` and `0x52f393`). Set exactly when the matched wrapper slot
-        /// was `SPELL_EFFECT_LEARN_PET_SPELL`.
+        /// The builder's altCaster argument, which drops the totem and reagent lines (`0x52ed43`,
+        /// `0x52f393`); set when the matched slot is `SPELL_EFFECT_LEARN_PET_SPELL`.
         alt_caster: bool,
     },
 }
@@ -186,88 +99,63 @@ impl Default for TrainerTooltip {
     }
 }
 
-/// One trainer service row, resolved by the app from the wire `TrainerSpell` (decision 0237). Plain
-/// data — position in [`TrainerState::services`] is the *unsorted* wire order; the 1-based index the
-/// Lua uses is a position in the visible display tree ([`rows`], built from [`TrainerState::groups`]).
+/// One service, resolved by the app from the wire `TrainerSpell`; its place in
+/// [`TrainerState::services`] is wire order, not display order.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TrainerService {
-    /// The service spell id — what the app sends for `CMSG_TRAINER_BUY_SPELL` when this row is bought.
+    /// The wire spell id, which `CMSG_TRAINER_BUY_SPELL` names.
     pub spell_id: u32,
-    /// The spell name (`GetTrainerServiceInfo`'s first return); `None` while `Spell.dbc` is still
-    /// loading (the API reports `nil`, the XML shows `UNKNOWN`).
+    /// The wire spell's name; `None` (before `Spell.dbc` loads) answers nil, shown as `UNKNOWN`.
     pub name: Option<String>,
-    /// The rank/subtext line (`Spell.dbc` NameSubtext — "Rank N"); `None`/empty shows no second line.
+    /// The wire spell's rank text, such as "Rank 2".
     pub subtext: Option<String>,
-    /// Icon texture path (`Interface\Icons\…`); `None` while the catalog answer is in flight.
     pub texture: Option<String>,
-    /// The spell description shown in the detail pane (`GetTrainerServiceDescription`); `""` when the
-    /// app has no description source yet.
     pub description: String,
-    /// Money cost in copper (already reputation-discounted server-side).
+    /// In copper, already reputation-discounted by the server.
     pub cost: u32,
-    /// A primary-profession first rank — the real window's `cpCost2 > 0` (the profession-point cost
-    /// that raises the "you can only have two professions" confirm dialog).
+    /// A primary profession's first rank: the stock window's `cpCost2 > 0`, which asks to confirm.
     pub prof_first_rank: bool,
-    /// The green/red/gray colour ([`TrainerServiceCategory`]).
     pub category: TrainerServiceCategory,
-    /// Character level required (0 = none).
     pub level_req: u32,
-    /// The skill-line requirement, or `None` when the service has no skill gate.
     pub skill_req: Option<TrainerSkillReq>,
-    /// Prerequisite-ability requirements (resolved from the wire's req-spell ids); empty when none.
     pub ability_reqs: Vec<TrainerAbilityReq>,
-    /// A tradeskill step (`IsTrainerServiceTradeSkill`) vs. a plain learn-spell.
     pub is_trade_skill: bool,
-    /// The tree's grouping key, resolved app-side by the **trainer type's own** builder law
-    /// (module doc, decision 1124): the taught spell's `SkillLine` at types 0/1/3, or the
-    /// `SKILL_STEP` partition's `1`/`2` at type 2. `0` = unresolved: the service is **dropped** from
-    /// the tree (the client's `skillLine == 0 → drop`) — reachable only at types 0/1/3.
+    /// The tree group: the taught spell's `SkillLine` at types 0, 1 and 3, where 0 (unresolved)
+    /// drops the service and a known service at type 1 takes `TRAINER_GROUP_KNOWN`; at type 2, 1
+    /// when the wire spell has a `SKILL_STEP` (44) effect, else 2 (`0x4d77b6`), so a tradeskill
+    /// trainer drops nothing.
     pub group_key: u32,
-    /// The group's localized display name — the header row's text. `SkillLine.dbc`'s name at types
-    /// 0/1/3; the `TRADESKILL_SERVICE_STEP`/`_LEARN` global strings at type 2.
+    /// The header text: the skill line's name, `KNOWN_TALENTS_HEADER` for the known group, or at
+    /// type 2 `TRADESKILL_SERVICE_STEP`/`_LEARN`.
     pub group_name: String,
-    /// What the detail-icon hover describes ([`TrainerTooltip`]) — resolved app-side, because the
-    /// law reads `Spell.dbc` fields the engine cannot see. Independent of [`Self::texture`].
     pub tooltip: TrainerTooltip,
 }
 
-/// One group in the display tree (decisions 0247/1124): the header's key + name and the positions
-/// (into [`TrainerState::services`]) of the group's services, pre-sorted by the trainer type's
-/// within-group comparator. Synthesized by [`UiScript::set_trainer`] — the app pushes only the flat
-/// services.
+/// One header and its services, built by [`UiScript::set_trainer`].
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TrainerGroup {
-    /// The group key (also the collapse key).
+    /// Also the collapse key.
     pub key: u32,
-    /// The header's display name.
     pub name: String,
-    /// The group's services, as positions into [`TrainerState::services`], in display order.
+    /// Positions into [`TrainerState::services`], in display order.
     pub services: Vec<usize>,
 }
 
-/// One open trainer window: the services, the greeting line, and the wire trainer type. Pushed whole
-/// by the app; `None` means no trainer is open (the window is closed).
+/// The open trainer, pushed whole by the app.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TrainerState {
     pub services: Vec<TrainerService>,
-    /// The trainer's greeting/title line (`SMSG_TRAINER_LIST`'s trailing string).
+    /// `SMSG_TRAINER_LIST`'s trailing string.
     pub greeting: String,
-    /// `SMSG_TRAINER_LIST`'s `trainerType` (`ds:0xb73a08`), verbatim — **the** switch: it selects the
-    /// row comparator, the header comparator and the group-key law (module doc), and it is what the
-    /// two whole-trainer predicates test (`IsTradeskillTrainer 0x4d8ea0`: `== 2`; `IsTalentTrainer
-    /// 0x4d8ed0`: `== 1`). 0 class · 1 mount · 2 tradeskill · 3 pet.
+    /// `SMSG_TRAINER_LIST`'s trainer type (`ds:0xb73a08`): 0 class, 1 mount, 2 tradeskill, 3 pet.
     pub trainer_type: u32,
-    /// The sorted skill-line groups over `services` — **built by [`UiScript::set_trainer`]**, not
-    /// pushed by the app (default-empty on a bare `TrainerState`). The display tree walks these.
+    /// Built by [`UiScript::set_trainer`], not pushed by the app.
     pub groups: Vec<TrainerGroup>,
 }
 
 impl super::UiScript {
-    /// Push (or clear, with `None`) the open trainer's service snapshot. On a push, the engine
-    /// **builds the skill-line tree** ([`build_groups`]) from the flat services and prunes the
-    /// collapse set to the lines that still exist (so a collapse survives a content update — a buy
-    /// re-lists — but a switch to a different trainer starts expanded). Clearing resets the selection
-    /// and the collapse set (a closed window holds nothing).
+    /// Push the open trainer, or clear it with `None`. A push builds the tree ([`build_groups`])
+    /// and keeps only the collapsed groups that still exist, so a fold survives a content update.
     pub fn set_trainer(&mut self, state: Option<TrainerState>) {
         let mut model = self.model_mut();
         match state {
@@ -285,37 +173,15 @@ impl super::UiScript {
         }
     }
 
-    /// **Reset what one `SMSG_TRAINER_LIST` arriving resets — the state filter, the collapse set,
-    /// and the selection.**
+    /// Reset what each `SMSG_TRAINER_LIST` resets in the reference (`0x4d7560`): the filter to mask
+    /// 3, or 5 at a mount trainer (`0x4d75d9`), the collapse set and the selection. Call it per
+    /// packet, never per snapshot: the repaint path `0x4d7d40` touches none of the three.
     ///
-    /// Byte-verified (wow-re `system/ui/scratch/trainer-service-suppression.md`, decision 1128): the
-    /// list builder writes the filter mask itself on every packet — `0x4d75d9 mov ds:0xb73a1c,3`
-    /// (available|unavailable, "already known" OFF), or `5` (available|used) when `trainerType == 1`
-    /// — alongside `ds:0xb73a20 = ds:0xb73a24 = 0xffffffff`, which is "no group collapsed". So the
-    /// player's filter choice does NOT live in the engine across trainer visits in the reference: it
-    /// lives in the saved variable `TRAINER_FILTER_*`, and the window's show handler pushes it back
-    /// over this reset (decision 1128; `TrainerFrame.xml`'s `BenillaTrainerFrame_ApplyFilter`).
-    ///
-    /// **The selection is the same edge and the same law.** `0x4d7560`'s tail selects record 0 —
-    /// `0x4d7b40 xor ecx,ecx` → `0x4d7b42 call 0x4d74f0`, after the sort — and since row 0 is always
-    /// a group header, whose record carries the id `0xffffffff` (`0x4d7b05`), the getter's scan
-    /// finds the first header and answers **1**. Clearing is the same thing to every caller: the
-    /// stock window only ever asks `GetTrainerSelectionIndex() > 1`, which 0 and 1 both fail, so
-    /// both send it down `ClassTrainer_SelectFirstLearnableSkill`. Without this a re-opened trainer
-    /// could inherit a selection from the last visit — the same spell id, still in the list, still
-    /// resolving — which the reference cannot do.
-    ///
-    /// The repaint path `0x4d7d40` touches **none** of the three (a `ds:0xb73a0c` census over the
-    /// whole image returns four references, all in the setter/getter/teardown), which is why a
-    /// purchase leaves the selection sitting on the service it just greyed out.
-    ///
-    /// This is the **packet** edge, not the content edge — [`Self::set_trainer`] runs on every
-    /// snapshot change (an item template landing, a name resolving), and the reference's repaint path
-    /// `0x4d7d40` does not touch either mask. Reset there and a filter would evaporate mid-window.
+    /// Deviation: the selection clears to 0, because the header the reference re-selects
+    /// (`0x4d7b42`, reading 1) has no spell id; the stock window's `> 1` test treats 0 and 1 alike.
     pub fn reset_trainer_list_state(&mut self, trainer_type: u32) {
         let mut model = self.model_mut();
-        // Mask 5 at a mount/"talent" trainer: available + already-known, which is what makes a
-        // known mount visible under its "My Talents" header at all (decision 1124's group -1).
+        // Mask 5 at a mount trainer shows available and known services, so the known group shows.
         model.trainer_filter = if trainer_type == TRAINER_TYPE_MOUNT {
             [true, false, true]
         } else {
@@ -325,59 +191,47 @@ impl super::UiScript {
         model.trainer_selection = None;
     }
 
-    /// Drain the **spell ids** `BuyTrainerService` queued since the last call (the engine resolves each
-    /// clicked filtered row to its service's spell id, so the app sends `CMSG_TRAINER_BUY_SPELL`
-    /// without needing to know the filter/index mapping).
+    /// Drain the spell ids `BuyTrainerService` queued, each already resolved from its row.
     pub fn take_trainer_buys(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().trainer_buys)
     }
 
-    /// Whether `CloseTrainer` was called since the last drain (and clear the flag). vanilla's
-    /// client-side close sends no packet — the app just clears its local trainer state.
+    /// Whether `CloseTrainer` was called since the last drain; the close sends no packet.
     pub fn take_trainer_close(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().trainer_close)
     }
 }
 
-/// One visible row of the display tree: a skill-line **header** (carrying its group index) or a
-/// **service** (carrying its position into [`TrainerState::services`]).
+/// One row: a header by group index, or a service by its position in [`TrainerState::services`].
 #[derive(Clone, Copy)]
 enum Row {
     Header(usize),
     Service(usize),
 }
 
-/// The WoW enUS collator (`0x64a480`), approximated: case-insensitive alphabetical, with the raw
-/// bytes as a stable tie-break so equal-when-folded names keep a deterministic order.
+/// Folds case, raw bytes breaking ties. The reference's row comparators call the case-sensitive
+/// `0x64a480`, its header comparator the case-insensitive `0x64a4c0` (`0x4d7c12`).
 fn collate(a: &str, b: &str) -> std::cmp::Ordering {
     a.to_lowercase()
         .cmp(&b.to_lowercase())
         .then_with(|| a.cmp(b))
 }
 
-/// `SMSG_TRAINER_LIST`'s tradeskill `trainerType` (module doc's table).
 const TRAINER_TYPE_TRADESKILL: u32 = 2;
-/// `SMSG_TRAINER_LIST`'s mount `trainerType` — the one the client's own vocabulary calls "talent"
-/// (`IsTalentTrainer 0x4d8ed0` tests it).
+/// The mount trainer type, which the client calls "talent".
 const TRAINER_TYPE_MOUNT: u32 = 1;
 
-/// The already-known group a **type 1** trainer buckets its `used` services into — the client's
-/// signed `-1` group key (`0x4d77e8`), whose header takes the `KNOWN_TALENTS_HEADER` global string
-/// ("My Talents", 1.12.1 enUS). Modelled as `u32::MAX` because the key is otherwise a skill-line id;
-/// the header comparator `0x4d7b90` tests for it explicitly and sorts it **first**, ahead of the
-/// name ordering that ranks every other header.
+/// The group a type 1 trainer files its `used` services under: the client's signed -1 key
+/// (`0x4d77e8`), headed `KNOWN_TALENTS_HEADER` and sorted before every other header by `0x4d7b90`.
 pub const TRAINER_GROUP_KNOWN: u32 = u32::MAX;
 
-/// A service's required-skill value (`[+0x1c]`, the wire's `reqSkillValue`) — `0` when the service
-/// carries no skill gate.
+/// The record's required-skill value `[+0x1c]`, 0 with no skill gate.
 fn skill_value(s: &TrainerService) -> u32 {
     s.skill_req.as_ref().map_or(0, |r| r.rank)
 }
 
-/// The within-group comparator for a **class** (type 0) or **pet** (type 3) trainer — keys ④–⑦ of
-/// the verified `0x4d85c0`: required level (`[+0x14]` byte) → required-skill value (`[+0x1c]` u32) →
-/// localized name → localized rank/subtext, all ascending. Pet is not special-cased anywhere in the
-/// selection chain at `0x4d8561`; it lands here with class.
+/// Rows at a class or pet trainer (`0x4d85c0`; `0x4d8561` sends pet here too): required level,
+/// skill value, name, then rank, all ascending.
 fn class_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
     let name = |s: &TrainerService| s.name.clone().unwrap_or_default();
     let rank = |s: &TrainerService| s.subtext.clone().unwrap_or_default();
@@ -388,13 +242,8 @@ fn class_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
         .then_with(|| collate(&rank(a), &rank(b)))
 }
 
-/// The within-group comparator for a **tradeskill** trainer (type 2) — the whole of `0x4d8760`'s
-/// row half: required-skill value **ascending** (`0x4d87d9`/`0x4d8801`), then the localized name.
-///
-/// The two keys it pointedly does *not* have are the interesting ones, and both were in benilla's
-/// output until 1124: there is **no `[+0x14]` required-level key** (which is what used to sink the
-/// profession-learn row — the only row with a level — to the bottom of every profession trainer),
-/// and **no `[+0x204]` rank tie-break**.
+/// Rows at a tradeskill trainer (`0x4d8760`): required skill value ascending (`0x4d87d9`), then
+/// name. It has no level key and no rank key.
 fn tradeskill_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
     let name = |s: &TrainerService| s.name.clone().unwrap_or_default();
     skill_value(a)
@@ -402,11 +251,8 @@ fn tradeskill_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Orderin
         .then_with(|| collate(&name(a), &name(b)))
 }
 
-/// The within-group comparator for a **mount** trainer (type 1, the client's "talent") — the whole
-/// of `0x4d8850`'s row half: the **state byte** `[+0x30]` ascending (`0x4d88f1`, so available →
-/// unavailable → used), then the localized name. The one comparator on which the green/red/gray is a
-/// sort key rather than only a colour; like the tradeskill one it has no level, skill-value or rank
-/// key.
+/// Rows at a mount trainer (`0x4d8850`): the state byte ascending (`0x4d88f1`: available,
+/// unavailable, used), then name.
 fn talent_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
     let name = |s: &TrainerService| s.name.clone().unwrap_or_default();
     a.category
@@ -415,17 +261,9 @@ fn talent_order(a: &TrainerService, b: &TrainerService) -> std::cmp::Ordering {
         .then_with(|| collate(&name(a), &name(b)))
 }
 
-/// Build the display tree from the flat services (decisions 0247/1124), by the trainer type's own
-/// three laws:
-///
-/// * **group** on the app-resolved [`TrainerService::group_key`], dropping the unresolved `0` (which
-///   a type-2 list never produces — its partition is total);
-/// * **order each group's services** with that type's row comparator;
-/// * **order the headers** by raw key ascending at type 2 (`0x4d7c30`: one key, no name, no
-///   tie-break), else by localized name with the key breaking a name tie (`0x4d7b90`).
-///
-/// The service positions index back into the unchanged `services` slice, so every getter still
-/// resolves a row to its full service data.
+/// Group the services by [`TrainerService::group_key`], dropping key 0, and sort each group's rows
+/// by the type's comparator; headers sort by raw key at type 2 (`0x4d7c30`), else by name
+/// (`0x4d7b90`).
 fn build_groups(services: &[TrainerService], trainer_type: u32) -> Vec<TrainerGroup> {
     let mut map: std::collections::HashMap<u32, TrainerGroup> = std::collections::HashMap::new();
     for (i, s) in services.iter().enumerate() {
@@ -454,9 +292,8 @@ fn build_groups(services: &[TrainerService], trainer_type: u32) -> Vec<TrainerGr
     if trainer_type == TRAINER_TYPE_TRADESKILL {
         groups.sort_by_key(|g| g.key);
     } else {
-        // `0x4d7b90`: the `-1` (already-known) group first, then localized name. Its second key —
-        // `hdr[+0x24] == 0` first, between those two — is uncarved and unreachable here: benilla's
-        // headers are one per distinct skill line, so nothing ties on the name that it would break.
+        // `0x4d7b90`: the known group first, then name. Its middle key, `hdr[+0x24] == 0` first, is
+        // untraced and not built.
         groups.sort_by(|a, b| {
             (a.key != TRAINER_GROUP_KNOWN)
                 .cmp(&(b.key != TRAINER_GROUP_KNOWN))
@@ -467,42 +304,12 @@ fn build_groups(services: &[TrainerService], trainer_type: u32) -> Vec<TrainerGr
     groups
 }
 
-/// The client's whole row array, and how much of its front is **on screen** — the visible rows in
-/// display order (decisions 0247/1124), then every hidden one in a **tail** behind them.
-///
-/// **Hiding a row is not removing it**, and that is the shape of the real array rather than a
-/// convenience here. The finalizer `0x4d8410` writes only a per-record visible flag — `[+0x34] = 1`
-/// at `0x4d84c6`, `= 0` at `0x4d8546` — decrements the *visible* count `ds:0xb73a18` (`0x4d8549`),
-/// and then `qsort`s **all `ds:0xb73a10`** records (`0x4d857e`) with that flag as the comparator's
-/// PRIMARY key (`0x4d85ce` … `0x4d8744 setne al` / `0x4d874e lea eax,[eax+eax-1]` → ±1). A hidden
-/// row therefore keeps a record, a position and an index — it is simply parked behind the visible
-/// ones. `GetNumTrainerServices` (`0x4d8d90`) answers with the visible count `ds:0xb73a18`, while
-/// the index space every getter is bounds-checked against is the **total** `ds:0xb73a10`: the
-/// thirteen service getters all route through one shared accessor gate, `0x4d89b0`'s
-/// `cmp ecx, dword ptr [0xb73a10]`, and `GetTrainerServiceInfo` (`0x4d8dc0`) reaches the same gate
-/// through its four siblings (`0x4d8aa2`, `0x4d8b52`, `0x4d8ba2`, `0x4d8c32`). The visible count has
-/// **five references image-wide** — the finalizer seeding and decrementing it, the buy-ALL loop, and
-/// `GetNumTrainerServices` — and **no getter is among them**. So an index past
-/// `GetNumTrainerServices()` is a legal, resolvable, *hidden* row — which is exactly the index the
-/// stock window is handed after a purchase, and reading it as out-of-range is what used to strand
-/// the detail pane ([`selected_row`]). An all-boxes-off window is empty because the Lua stops
-/// iterating, not because the rows stopped existing.
-///
-/// The tail's own ORDER is the comparator's remaining keys in the client and tree order here. It is
-/// unobservable through the stock window — nothing iterates past `GetNumTrainerServices()`, and the
-/// single index that ever reaches in is the selection's, resolved by identity — so the difference
-/// costs nothing until something walks the tail.
-///
-/// **The filter and the collapse are deliberately asymmetric**, and that asymmetry is structural in
-/// the client rather than incidental. The finalizer builds a per-group flag `hdr[+0x1c]` by walking
-/// the group's per-state member counts through the **live** state mask `ds:0xb73a1c` (`0x4d8431`,
-/// `0x4d8447`), and the hide it drives at `0x4d8535` has **no header-row exemption** — so a group
-/// every one of whose rows the dropdown hides disappears entirely, header included, and unchecking
-/// every box empties the window (`GetNumTrainerServices() == 0`). The collapse test three
-/// instructions later (`0x4d8541`) *does* exempt headers (`0x4d853d`) and reads a different field
-/// (`hdr[+0x20]`), so a collapsed group keeps its header — which is what makes it re-expandable.
-/// benilla had both cases keeping the header, with a test asserting it; 1124 inverted the filter
-/// half.
+/// The client's whole row array and its visible count: visible rows in display order, then every
+/// hidden row in a tail. The finalizer `0x4d8410` only clears a hidden record's visible flag
+/// (`0x4d8546`) and sorts it behind (`0x4d857e`), and the getters bound on the total
+/// (`0x4d89b0`, `ds:0xb73a10`), so a hidden row keeps its index. A group the filter empties hides
+/// its header too (`0x4d8535`); a collapsed one keeps it (`0x4d853d`). The tail's order here is
+/// tree order, not the client's; the stock window reaches the tail only by the selection's index.
 fn rows(model: &Model) -> (Vec<Row>, usize) {
     let Some(t) = model.trainer.as_ref() else {
         return (Vec::new(), 0);
@@ -516,7 +323,7 @@ fn rows(model: &Model) -> (Vec<Row>, usize) {
             .copied()
             .partition(|&si| model.trainer_filter[t.services[si].category.filter_slot()]);
         if passes.is_empty() {
-            // The whole group is filtered away — header with it (1124's inverted half).
+            // The filter hid every service, so the header goes too.
             tail.push(Row::Header(gi));
         } else {
             shown.push(Row::Header(gi));
@@ -535,10 +342,8 @@ fn rows(model: &Model) -> (Vec<Row>, usize) {
     (shown, visible)
 }
 
-/// The service at a 1-based visible index, or `None` when that row is a **header** (or OOB / no
-/// trainer) — so the getters/buy that read a service safely no-op on a header row. `pub(super)`:
-/// `GameTooltip:SetTrainerService` lives in the tooltip channel and must resolve its index through
-/// the same VISIBLE mapping, never a raw `services[]` position.
+/// The service at a 1-based row index; `None` for a header. `GameTooltip:SetTrainerService`
+/// resolves its index through this too, never through a raw `services` position.
 pub(super) fn service(model: &Model, index: usize) -> Option<&TrainerService> {
     let n = index.checked_sub(1)?;
     match rows(model).0.get(n)? {
@@ -547,43 +352,16 @@ pub(super) fn service(model: &Model, index: usize) -> Option<&TrainerService> {
     }
 }
 
-/// `GetNumTrainerServices`' answer — the count of rows **on screen** (headers + unfiltered,
-/// uncollapsed services), which is the client's `ds:0xb73a18` and not the length of the row array
-/// the indices run over ([`rows`]).
+/// `GetNumTrainerServices` (`0x4d8d90`): the visible count `ds:0xb73a18`, not the array's length.
 fn num_services(model: &Model) -> usize {
     rows(model).1
 }
 
-/// The selected service's 1-based position in the row array ([`rows`]) — which is **past
-/// `GetNumTrainerServices()` when that service is hidden**, and `None` only when nothing is selected
-/// or the service has left the trainer's list altogether.
-///
-/// **The selection is the service, not the row it happens to sit on.** `SelectTrainerService`
-/// (`0x4d8e60` → `0x4d74f0`) stores the record's **spell id** at `ds:0xb73a0c` — 0 when the index is
-/// out of range, never a clamp — and this getter (`0x4d8f10` → `0x4d7520`) finds it again by linear
-/// scan over the whole array, `cmp dword ptr [edi], esi` at `0x4d7543`, answering `-1` → Lua `0`
-/// only when the scan runs out. Three separate things renumber the rows under a stored number — the
-/// state filter, a collapse, a re-list — so an index stored on Monday is a different service on
-/// Tuesday, and one merely *clamped* to the row count is the worst answer available: plausible, in
-/// range, and wrong. benilla stored the number.
-///
-/// It is load-bearing far beyond bookkeeping, because the stock `Blizzard_TrainerUI.lua` repaints
-/// its detail pane through exactly **one** door. `ClassTrainerTrainButton_OnClick` clears
-/// `ClassTrainerFrame.showSkillDetails`, and `ClassTrainer_SetSelection` early-returns while that is
-/// nil — so on `TRAINER_UPDATE` only the `GetTrainerSelectionIndex() > 1` **else** branch,
-/// `ClassTrainer_SelectFirstLearnableSkill`, puts the flag back and rewrites the name, icon,
-/// `Requires:` line and cost. Answering with a *live, visible* row number for a service that has
-/// left the screen therefore takes the silent branch and leaves the pane describing the spell the
-/// player just learned, under a highlight sitting on the row that slid up into its place — the
-/// director's report.
-///
-/// The reference's own answer there is the hidden row's index, and its consequence is worth stating
-/// because it is what a player sees: `> 1` is true, so the window resets the scroll, calls
-/// `ClassTrainer_SetSelection` on a row nothing displays, and the update loop — which asks only
-/// whether the selection is *on screen* — finds it is not and hides the detail pane. **After you
-/// train a spell the reference blanks the pane and highlights nothing**; it does not advance to the
-/// next spell. Answering `0` instead would select the first learnable and repaint, which is the
-/// fresh-window behaviour, not the post-purchase one.
+/// `GetTrainerSelectionIndex`: the selected service's 1-based row, past the visible count while it
+/// is hidden; `None` when nothing is selected or it left the list. The selection is the record's
+/// spell id (`0x4d8e60` stores it at `ds:0xb73a0c`, `0x4d8f10` scans for it at `0x4d7543`), so no
+/// filter, collapse or update moves it to another service. After a purchase hides the service,
+/// the stock window blanks its detail pane and highlights nothing, as the reference does.
 fn selected_row(model: &Model) -> Option<usize> {
     let want = model.trainer_selection?;
     let t = model.trainer.as_ref()?;
@@ -597,33 +375,10 @@ fn selected_row(model: &Model) -> Option<usize> {
         .checked_add(1)
 }
 
-/// Collapse (`collapse = true`) or expand a skill line by the **display index of its header row**
-/// (decision 0247's `Collapse/ExpandTrainerSkillLine`). `id == 0` targets **all** groups (the
-/// collapse-all button); `id > 0` resolves the header at that index to its skill line. A non-header
-/// (or out-of-range) index is a no-op.
-///
-/// Like every other index in this surface it runs over the whole row array, so a header sitting in
-/// the hidden tail resolves too ([`rows`]). That is the shape of the accessor gate the service
-/// getters were carved to share (`0x4d89b0`, bounded by the total); these two bindings' own gate was
-/// **not** carved, and the difference is unobservable through the stock window, which only ever
-/// passes a visible header's index or `0`.
-/// Queue `TRAINER_UPDATE` — **the repaint the reference fires from the mask-commit thunk itself**,
-/// not from Lua (decision 2244).
-///
-/// `SetTrainerServiceTypeFilter`'s four legs all commit through `0x4d8c90`, whose whole body is
-/// `mov ds:0xb73a1c,ecx; call 0x4d8410; mov ecx,0x136; jmp 0x703e50` — write the mask, re-run the
-/// finalizer, **fire event `0x136` = `TRAINER_UPDATE`** (wow-re `system/ui/ledger.tsv`'s `0x4d8c90`
-/// row; the id is `ui.md`'s own event table). Its siblings `0x4d8cb0` (the skill-line mask) and
-/// `0x4d8cd0` (the expand mask, which is what Collapse/ExpandTrainerSkillLine commit) are recorded
-/// there as the same shape.
-///
-/// That matters because **nothing in the stock window repaints after a filter click**:
-/// `ClassTrainerFrameFilterDropDown_OnClick` sets the saved global, calls the filter verb, and then
-/// only does `ClassTrainerListScrollFrameScrollBar:SetValue(0)` — a no-op when the bar is already at
-/// zero. The list is repainted by `ClassTrainerFrame_OnEvent`'s `TRAINER_UPDATE` arm, and by nothing
-/// else. While our own `TrainerFrame.xml` ran (before 1957) its click handler repainted explicitly,
-/// which is why this only became visible when the window went stock: the checkboxes moved and the
-/// list underneath did not.
+/// Queue `TRAINER_UPDATE`, which the reference fires from its mask commits, not from Lua:
+/// `0x4d8c90` writes the filter mask, re-runs the finalizer and fires event `0x136`, and the
+/// skill-line and expand-mask commits (`0x4d8cb0`, `0x4d8cd0`, the collapse verbs') do the same.
+/// The stock window's filter click (`Blizzard_TrainerUI.lua:524`) does not repaint.
 fn queue_trainer_update(model: &mut Model) {
     model
         .pending_events
@@ -662,7 +417,6 @@ fn set_collapsed(model: &mut Model, id: usize, collapse: bool) {
     }
 }
 
-/// An optional string as a Lua value (`nil` when absent).
 fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     Ok(match s {
         Some(s) => Value::String(lua.create_string(s)?),
@@ -670,7 +424,7 @@ fn opt_str(lua: &Lua, s: Option<&String>) -> mlua::Result<Value> {
     })
 }
 
-/// A `bool` as the Era `1`/`nil` shape.
+/// A `bool` as the reference's `1` or nil.
 fn era_bool(b: bool) -> Value {
     if b {
         Value::Integer(1)
@@ -683,7 +437,6 @@ fn era_bool(b: bool) -> Value {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // → the number of services the open trainer offers under the current filter (0 when closed).
     g.set(
         "GetNumTrainerServices",
         lua.create_function(|lua, ()| {
@@ -692,9 +445,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceInfo(index) → name, subText, serviceType, isExpanded. `index` 1-based into the
-    // visible tree; out of range → a single nil. A HEADER row returns (skillLineName, nil, "header",
-    // isExpanded); a SERVICE row returns (name, subText, stateString, nil) (decision 0247).
+    // GetTrainerServiceInfo(index) → name, subText, serviceType, isExpanded; one nil past the end.
     g.set(
         "GetTrainerServiceInfo",
         lua.create_function(|lua, index: usize| {
@@ -733,13 +484,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceSkillLine(index) → the skill line the service teaches into, by name — the
-    // group the tree files it under (`TrainerService::group_name`: `SkillLine.dbc`'s name at
-    // trainer types 0/1/3, 1124's builder law). The stock window's one caller is the
-    // CONFIRM_PROFESSION dialog, which formats "learn <profession>?" with it
-    // (Blizzard_TrainerUI.lua l.19-24). A header row or an out-of-range index answers nil. The
-    // binding is registered (`0x4d9160`, 399 bytes) but its return law is not carved beyond
-    // "delegates"; this is the call site's reading (1957).
+    // GetTrainerServiceSkillLine(index): the group name, nil for a header. The reference's return
+    // (`0x4d9160`) is untraced; the stock `CONFIRM_PROFESSION` dialog shows it as the profession.
     g.set(
         "GetTrainerServiceSkillLine",
         lua.create_function(|lua, index: usize| {
@@ -760,7 +506,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceIcon(index) → texture path (nil while in flight / OOB).
     g.set(
         "GetTrainerServiceIcon",
         lua.create_function(|lua, index: usize| {
@@ -769,7 +514,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceDescription(index) → the spell description ("" when the app has none / OOB).
     g.set(
         "GetTrainerServiceDescription",
         lua.create_function(|lua, index: usize| {
@@ -781,8 +525,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceCost(index) → money, talentPointCost, professionPointCost. Talent cost is
-    // always 0 (no talent trainer); profession cost is 1 for a primary-profession first rank.
+    // GetTrainerServiceCost(index) → money, talentPointCost, professionPointCost; the talent cost
+    // is always 0, the profession cost 1 for a primary profession's first rank.
     g.set(
         "GetTrainerServiceCost",
         lua.create_function(|lua, index: usize| {
@@ -798,7 +542,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceLevelReq(index) → required character level (0 = none).
     g.set(
         "GetTrainerServiceLevelReq",
         lua.create_function(|lua, index: usize| {
@@ -807,7 +550,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceSkillReq(index) → skillName, skillRank, hasReq (nil when no skill gate / OOB).
     g.set(
         "GetTrainerServiceSkillReq",
         lua.create_function(|lua, index: usize| {
@@ -823,7 +565,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceNumAbilityReq(index) → how many prerequisite abilities the service lists.
     g.set(
         "GetTrainerServiceNumAbilityReq",
         lua.create_function(|lua, index: usize| {
@@ -832,7 +573,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceAbilityReq(index, i) → abilityName, hasReq (nil OOB).
     g.set(
         "GetTrainerServiceAbilityReq",
         lua.create_function(|lua, (index, i): (usize, usize)| {
@@ -849,13 +589,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceStepReq(index) → step, met — always nil (no tradeskill-step data on the wire).
+    // GetTrainerServiceStepReq(index) → step, met: always nil, as the wire carries no step data.
     g.set(
         "GetTrainerServiceStepReq",
         lua.create_function(|_, _index: usize| Ok(Value::Nil))?,
     )?;
 
-    // IsTrainerServiceTradeSkill(index) → 1/nil (a tradeskill step vs. a learn-spell).
     g.set(
         "IsTrainerServiceTradeSkill",
         lua.create_function(|lua, index: usize| {
@@ -866,8 +605,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsTrainerServiceLearnSpell(index) → isLearnSpell, isPetLearnSpell. Pet-learn is always nil
-    // (benilla drives no pet trainer); a non-tradeskill service is a learn-spell.
+    // IsTrainerServiceLearnSpell(index) → isLearnSpell, isPetLearnSpell: any service that is not a
+    // tradeskill is a learn spell; isPetLearnSpell is not built and always answers nil.
     g.set(
         "IsTrainerServiceLearnSpell",
         lua.create_function(|lua, index: usize| {
@@ -877,8 +616,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsTradeskillTrainer() → 1/nil for the whole trainer (drives the tradeskill-vs-class layout):
-    // `0x4d8ea0` tests trainerType == 2.
+    // IsTradeskillTrainer(): trainer type 2 (`0x4d8ea0`).
     g.set(
         "IsTradeskillTrainer",
         lua.create_function(|lua, ()| {
@@ -889,9 +627,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // IsTalentTrainer() → 1/nil: `0x4d8ed0` tests trainerType == 1 — vmangos's MOUNT trainers, which
-    // the client's own vocabulary calls "talent" (decision 1124). It used to return a hardcoded nil
-    // on the belief that benilla drives no such trainer; the shipped world has 23 of them.
+    // IsTalentTrainer(): trainer type 1 (`0x4d8ed0`), which vmangos gives its mount trainers.
     g.set(
         "IsTalentTrainer",
         lua.create_function(|lua, ()| {
@@ -902,7 +638,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerGreetingText() → the trainer's greeting line ("" when no trainer is open).
     g.set(
         "GetTrainerGreetingText",
         lua.create_function(|lua, ()| {
@@ -916,8 +651,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerServiceTypeFilter(type) → 1/nil (whether that category is shown). SetTrainerService-
-    // TypeFilter(type, on) toggles it — the sort checkboxes' real client-side filtering.
     g.set(
         "GetTrainerServiceTypeFilter",
         lua.create_function(|lua, kind: String| {
@@ -933,19 +666,18 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, (kind, on): (String, Value)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
             if let Some(c) = TrainerServiceCategory::from_filter_str(&kind) {
-                // Era passes 1 / 0 (or true/nil); anything truthy-but-not-0 enables.
+                // The stock window passes 1 or 0; nil, false and 0 disable.
                 let enable = !matches!(on, Value::Nil | Value::Integer(0) | Value::Boolean(false));
                 model.trainer_filter[c.filter_slot()] = enable;
-                // …and the repaint, from here rather than from Lua ([`queue_trainer_update`]).
-                // Unconditional, like the thunk: it fires whether or not the bit moved.
+                // Fires even when the bit did not move, as the reference's thunk does.
                 queue_trainer_update(&mut model);
             }
             Ok(())
         })?,
     )?;
 
-    // Collapse/ExpandTrainerSkillLine(id) — fold a skill line by the display index of its header row
-    // (id 0 = all groups, the collapse-all button); a non-header index no-ops (decision 0247).
+    // Collapse/ExpandTrainerSkillLine(id): fold the group headed by row `id`, or all at 0. `id`
+    // spans the whole row array like the getters' gate (`0x4d89b0`); their own bound is untraced.
     g.set(
         "CollapseTrainerSkillLine",
         lua.create_function(|lua, id: usize| {
@@ -965,14 +697,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SelectTrainerService(index) — select the SERVICE at that row, by its spell id. An index out
-    // of range clears the selection (`0x4d74f0`'s `cmp ecx, ds:0xb73a10` / `mov [0xb73a0c], 0` —
-    // cleared, never clamped); [`selected_row`] is why the id and not the row number.
-    //
-    // A HEADER row clears here too, where the reference would store the header record's own id,
-    // `0xffffffff` (`0x4d7b05`), and find the FIRST header again on the way back out — answering 1
-    // rather than 0. The two are the same answer to the only question the stock window asks of this
-    // number (`GetTrainerSelectionIndex() > 1`), and nothing else reads it.
+    // SelectTrainerService(index): select the row's service by spell id; past the end clears it
+    // (`0x4d74f0` stores 0, never a clamp). Deviation: a header clears it too, because it has no
+    // spell id; the reference stores its `0xffffffff` (`0x4d7b05`) and reads back 1, which the
+    // stock window's `> 1` test treats the same as 0.
     g.set(
         "SelectTrainerService",
         lua.create_function(|lua, index: usize| {
@@ -982,9 +710,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetTrainerSelectionIndex() → the selected service's current 1-based row — **past
-    // `GetNumTrainerServices()` while that service is hidden**, and 0 only when nothing is selected
-    // or the service has left the list entirely ([`selected_row`] has the law and what rides on it).
     g.set(
         "GetTrainerSelectionIndex",
         lua.create_function(|lua, ()| {
@@ -993,19 +718,10 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // BuyTrainerService(index) — queue that row's SPELL ID for purchase (the app sends
-    // CMSG_TRAINER_BUY_SPELL). A header row, an out-of-range index, or an ALREADY-KNOWN row is
-    // silently ignored: the single-row path `0x4d89d0` resolves through the same total-bounded
-    // accessor gate as every getter, then refuses on the state byte — `0x4d89e1 cmp esi,ebx; je`
-    // (no record) and `0x4d89e5 cmp byte ptr [esi+0x30], bl; jne` (state != 0, i.e. anything but
-    // `available`), both jumping to the same do-nothing exit.
-    //
-    // Deliberately NOT built: the reference's buy-ALL convenience `0x4d8a70`, the one
-    // visible-count-bounded loop in the whole surface (`0x4d8a71`/`0x4d8a88` read `ds:0xb73a18`).
-    // The split `0x4da244 dec eax; 0x4da245 jns` is SIGNED, so it is every Lua index **<= 0** that
-    // lands there — `BuyTrainerService(0)` buys the player's entire visible list in one call. Here
-    // index 0 is a no-op instead. Nothing in the stock window passes a non-positive index, and a
-    // verb that spends the whole purse on a typo is not one to reproduce on the strength of that.
+    // BuyTrainerService(index): queue the row's spell id. `0x4d89d0` bounds through the getters'
+    // gate and refuses any state byte but 0 (`0x4d89e5`), so only an available service queues.
+    // Deviation: index 0 is a no-op, because one stray call would spend the purse; the reference
+    // buys every visible service for any index at or below 0 (`0x4da244`, `0x4d8a70`).
     g.set(
         "BuyTrainerService",
         lua.create_function(|lua, index: usize| {
@@ -1020,7 +736,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // CloseTrainer() — client-side close (no packet, vanilla): flag it so the app clears its state.
+    // CloseTrainer(): sends no packet; the app clears its state on the flag.
     g.set(
         "CloseTrainer",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/trainer/tests.rs b/crates/benilla-ui/src/script/trainer/tests.rs
index 7e8170a1..def3be58 100644
--- a/crates/benilla-ui/src/script/trainer/tests.rs
+++ b/crates/benilla-ui/src/script/trainer/tests.rs
@@ -1,6 +1,4 @@
-//! The trainer tree's tests — the per-`trainerType` ordering laws (decisions 0247/1124) pinned
-//! against wow-re's own emulated runs of the real finalizer, plus the filter/collapse/intent
-//! surface. Split out of `mod.rs` when the four comparators pushed it past the file budget.
+//! Tests for the trainer tree: the per-type row orders, the filter, the collapse and the intents.
 
 use super::*;
 use crate::script::UiScript;
@@ -14,8 +12,6 @@ fn svc(
 ) -> TrainerService {
     TrainerService {
         spell_id,
-        // The fixture's default subject: the wire spell, no hop (the "no learn wrapper"
-        // fallback); the tooltip tests set the arm they mean explicitly.
         tooltip: TrainerTooltip::Spell {
             spell_id,
             alt_caster: false,
@@ -36,10 +32,8 @@ fn svc(
     }
 }
 
-/// A two-line warrior trainer (type 0). Groups sort by name (Arms < Fury); within Arms, the level
-/// keys order Heroic Strike (level 1) before Cleave (level 20). The default-expanded tree is thus:
-/// `[H:Arms, Heroic Strike(avail), Cleave(used), H:Fury, Bloodrage(unavail)]` — a 5-row list whose
-/// service rows sit at indices 2, 3, 5.
+/// A class trainer whose tree is `[H:Arms, Heroic Strike, Cleave, H:Fury, Bloodrage]`, the three
+/// services available, used and unavailable.
 fn trainer() -> TrainerState {
     let mut hs = svc(
         78,
@@ -66,7 +60,7 @@ fn trainer() -> TrainerState {
     }
 }
 
-/// Every visible row as `(name, serviceType)` — the shape the ported XML actually renders.
+/// Every visible row as `(name, serviceType)`.
 fn visible(s: &mut UiScript) -> Vec<(String, String)> {
     let n = s.eval::<i64>("return GetNumTrainerServices()").unwrap();
     (1..=n)
@@ -88,10 +82,8 @@ fn tree_interleaves_headers_and_ordered_services() {
         .unwrap());
 
     s.set_trainer(Some(trainer()));
-    // 2 headers + 3 services = 5 visible rows.
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 
-    // Row 1 is the "Arms" header: name, nil subtext, "header", isExpanded=1.
     let (hn, hsub, ht, hexp) = s
         .eval::<(String, Option<String>, String, Option<i64>)>(
             "local n,s,t,e = GetTrainerServiceInfo(1) return n,s,t,e",
@@ -100,7 +92,6 @@ fn tree_interleaves_headers_and_ordered_services() {
     assert_eq!((hn.as_str(), ht.as_str()), ("Arms", "header"));
     assert_eq!((hsub, hexp), (None, Some(1)));
 
-    // Rows 2..5: services (name/state) then the Fury header then its service — the sorted tree.
     let info = |s: &mut UiScript, i: i64| {
         s.eval::<(String, String)>(&format!(
             "local n,_,t = GetTrainerServiceInfo({i}) return n,t"
@@ -120,7 +111,7 @@ fn tree_interleaves_headers_and_ordered_services() {
 fn service_getters_read_the_row_at_a_visible_index() {
     let mut s = UiScript::new().unwrap();
     let mut t = trainer();
-    // Heroic Strike (services[0], the row at index 2) carries a full gate set.
+    // Heroic Strike, row 2, gets a full gate set.
     t.services[0].skill_req = Some(TrainerSkillReq {
         name: "Blacksmithing".into(),
         rank: 100,
@@ -132,7 +123,6 @@ fn service_getters_read_the_row_at_a_visible_index() {
     }];
     s.set_trainer(Some(t));
 
-    // Cost/level/desc/reqs all resolve at the SERVICE index 2 (not the header at 1).
     assert_eq!(
         s.eval::<(i64, i64, i64)>("return GetTrainerServiceCost(2)")
             .unwrap(),
@@ -161,7 +151,7 @@ fn service_getters_read_the_row_at_a_visible_index() {
         .eval::<bool>("local l,p = IsTrainerServiceLearnSpell(2) return l==1 and p==nil")
         .unwrap());
 
-    // A HEADER row (index 1) has no service data — the getters no-op to defaults.
+    // Row 1 is a header, so the getters answer their defaults.
     assert_eq!(
         s.eval::<i64>("return GetTrainerServiceLevelReq(1)")
             .unwrap(),
@@ -175,17 +165,13 @@ fn service_getters_read_the_row_at_a_visible_index() {
         .unwrap());
 }
 
-/// The state filter takes a group's **header with it** once it hides the group's last service — the
-/// finalizer's `[+0x1c]` hide has no header-row exemption (`0x4d8528`/`0x4d8535`, decision 1124).
-/// This asserted the opposite until 1124: benilla rendered bare headers over empty groups, and an
-/// all-boxes-off filter left a window full of headings and nothing else.
+/// The reference's filter hide exempts no header (`0x4d8528`, `0x4d8535`).
 #[test]
 fn state_filter_takes_a_groups_header_with_its_last_service() {
     let mut s = UiScript::new().unwrap();
     s.set_trainer(Some(trainer()));
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 
-    // Hide "used": Cleave drops (5 → 4), and BOTH headers stay — Arms still has Heroic Strike.
     s.run("SetTrainerServiceTypeFilter('used', 0)").unwrap();
     assert_eq!(
         visible(&mut s)
@@ -195,8 +181,6 @@ fn state_filter_takes_a_groups_header_with_its_last_service() {
         ["header", "available", "header", "unavailable"]
     );
 
-    // Now hide "available" too: Arms loses its last row, so the ARMS HEADER GOES WITH IT — only
-    // Fury's header and its unavailable service remain.
     s.run("SetTrainerServiceTypeFilter('available', 0)")
         .unwrap();
     assert_eq!(
@@ -207,17 +191,12 @@ fn state_filter_takes_a_groups_header_with_its_last_service() {
         ]
     );
 
-    // Every box off renders NOTHING — not a list of bare headings.
     s.run("SetTrainerServiceTypeFilter('unavailable', 0)")
         .unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 0);
 
-    // …but the *rows* are still there behind it, and the getters still serve them (2231). This line
-    // asserted `GetTrainerServiceInfo(1) == nil` until the accessor gate was carved: the single one
-    // every service getter shares, `0x4d89b0`, bounds against the TOTAL `ds:0xb73a10`, and the
-    // visible count `ds:0xb73a18` has exactly five references image-wide — the finalizer seeding and
-    // decrementing it, the buy-ALL loop, and `GetNumTrainerServices`. No getter reads it. An empty
-    // window is empty because the Lua stops iterating, not because the rows stopped existing.
+    // The rows remain: the getters bound on the total `ds:0xb73a10` (`0x4d89b0`), not the visible
+    // count `ds:0xb73a18`.
     assert_eq!(
         s.eval::<String>("return (GetTrainerServiceInfo(1))")
             .unwrap(),
@@ -231,15 +210,12 @@ fn state_filter_takes_a_groups_header_with_its_last_service() {
     );
 }
 
-/// Collapse is the *asymmetric* case, and deliberately so: it hides a group's services but keeps the
-/// header — a different field (`hdr[+0x20]`) tested three instructions after the filter's, with a
-/// header-row exemption the filter's lacks (`0x4d853d`). Without it a collapsed group could never be
-/// re-expanded, having no header left to click.
+/// The reference's collapse test exempts headers (`0x4d853d`), where the filter's does not.
 #[test]
 fn collapse_keeps_the_header_the_filter_would_remove() {
     let mut s = UiScript::new().unwrap();
     s.set_trainer(Some(trainer()));
-    s.run("CollapseTrainerSkillLine(1)").unwrap(); // fold Arms — both its services hide
+    s.run("CollapseTrainerSkillLine(1)").unwrap(); // fold Arms
     assert_eq!(
         visible(&mut s),
         [
@@ -248,7 +224,6 @@ fn collapse_keeps_the_header_the_filter_would_remove() {
             ("Bloodrage".to_string(), "unavailable".to_string()),
         ]
     );
-    // Collapse-all keeps every header; the filter's empty case keeps none.
     s.run("CollapseTrainerSkillLine(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 2);
 }
@@ -258,8 +233,6 @@ fn collapse_by_header_index_and_collapse_all() {
     let mut s = UiScript::new().unwrap();
     s.set_trainer(Some(trainer()));
 
-    // Collapse the Arms group by its header's display index (1): its two services vanish, the
-    // header stays and now reports isExpanded=nil. 5 → 3 (H:Arms, H:Fury, Bloodrage).
     s.run("CollapseTrainerSkillLine(1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 3);
     assert!(s
@@ -272,14 +245,11 @@ fn collapse_by_header_index_and_collapse_all() {
         "Arms' services are folded; Fury's header is now row 2"
     );
 
-    // Expand it back by the same header index.
     s.run("ExpandTrainerSkillLine(1)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 
-    // Collapse-all (id 0): both groups fold → just the two headers.
     s.run("CollapseTrainerSkillLine(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 2);
-    // Expand-all (id 0): back to the full tree.
     s.run("ExpandTrainerSkillLine(0)").unwrap();
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 }
@@ -291,7 +261,7 @@ fn collapse_survives_a_content_update_and_resets_on_close() {
     s.run("CollapseTrainerSkillLine(1)").unwrap(); // fold Arms
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 3);
 
-    // A re-list (same skill lines) keeps the fold — a buy re-lists and the tree shouldn't jump open.
+    // A content update over the same groups keeps the fold.
     s.set_trainer(Some(trainer()));
     assert_eq!(
         s.eval::<i64>("return GetNumTrainerServices()").unwrap(),
@@ -299,31 +269,23 @@ fn collapse_survives_a_content_update_and_resets_on_close() {
         "Arms stays collapsed across a content update"
     );
 
-    // Close → the collapse set resets; a re-open is fully expanded.
     s.set_trainer(None);
     s.set_trainer(Some(trainer()));
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 }
 
-/// A buy queues the row's **spell id**, and only a green row can be bought — the single-row path
-/// `0x4d89d0` resolves the index through the shared total-bounded gate and then refuses on the state
-/// byte (`0x4d89e5 cmp byte ptr [esi+0x30], bl; jne`), so red and gray rows are silently dropped on
-/// the floor rather than sent to the server (2231). This used to queue whatever the index resolved
-/// to, which is how a `used` row could still put a `CMSG_TRAINER_BUY_SPELL` on the wire.
+/// The reference's buy refuses any state byte but 0 (`0x4d89d0`, `0x4d89e5`).
 #[test]
 fn buy_queues_an_available_services_spell_id_and_refuses_every_other_row() {
     let mut s = UiScript::new().unwrap();
     s.set_trainer(Some(trainer()));
-    // Row 2 is Heroic Strike (spell 78, available). Buying it queues its spell id, not its index.
     s.run("BuyTrainerService(2)").unwrap();
     assert_eq!(s.take_trainer_buys(), vec![78]);
     assert!(s.take_trainer_buys().is_empty(), "drained");
 
-    // Buying a HEADER row (index 1) queues nothing.
     s.run("BuyTrainerService(1)").unwrap();
     assert!(s.take_trainer_buys().is_empty(), "a header is not buyable");
 
-    // Nor does a gray row (Cleave, already known) or a red one (Bloodrage, gated).
     s.run("BuyTrainerService(3)").unwrap();
     s.run("BuyTrainerService(5)").unwrap();
     assert!(
@@ -345,7 +307,7 @@ fn selection_and_close_intents() {
         s.eval::<i64>("return GetTrainerSelectionIndex()").unwrap(),
         2
     );
-    s.run("SelectTrainerService(9)").unwrap(); // OOB (past the 5 rows) clears
+    s.run("SelectTrainerService(9)").unwrap(); // past the 5 rows: clears
     assert_eq!(
         s.eval::<i64>("return GetTrainerSelectionIndex()").unwrap(),
         0
@@ -357,9 +319,7 @@ fn selection_and_close_intents() {
     assert!(!s.take_trainer_close(), "drained");
 }
 
-/// The two whole-trainer predicates fork on the wire `trainer_type` — `IsTradeskillTrainer` on
-/// `== 2` (`0x4d8ea0`), `IsTalentTrainer` on `== 1` (`0x4d8ed0`) — so at most one is ever true, and
-/// at a class trainer neither is.
+/// `IsTradeskillTrainer` tests type 2 (`0x4d8ea0`), `IsTalentTrainer` type 1 (`0x4d8ed0`).
 #[test]
 fn tradeskill_and_talent_flags() {
     let mut s = UiScript::new().unwrap();
@@ -367,13 +327,12 @@ fn tradeskill_and_talent_flags() {
         .eval::<bool>("return IsTradeskillTrainer() == nil")
         .unwrap());
 
-    // A class trainer: neither predicate.
     s.set_trainer(Some(trainer()));
     assert!(s
         .eval::<bool>("return IsTradeskillTrainer() == nil and IsTalentTrainer() == nil")
         .unwrap());
 
-    // A tradeskill trainer — one "Recipes" group, so its one service is the row at index 2.
+    // One "Recipes" group, so its service is row 2.
     let mut recipe = svc(
         2743,
         "Copper Chain Pants",
@@ -395,7 +354,6 @@ fn tradeskill_and_talent_flags() {
         .eval::<bool>("return IsTrainerServiceTradeSkill(2) == 1")
         .unwrap());
 
-    // A mount trainer — the "talent" predicate, which used to be a hardcoded nil.
     s.set_trainer(Some(TrainerState {
         greeting: String::new(),
         trainer_type: 1,
@@ -417,7 +375,6 @@ fn tradeskill_and_talent_flags() {
 fn unresolved_skill_line_is_dropped() {
     let mut s = UiScript::new().unwrap();
     let mut t = trainer();
-    // A service whose skill line didn't resolve (0) is dropped from the tree entirely.
     t.services.push(svc(
         999,
         "Orphan Spell",
@@ -426,19 +383,11 @@ fn unresolved_skill_line_is_dropped() {
         "",
     ));
     s.set_trainer(Some(t));
-    // Still 5 rows — the orphan contributes neither a header nor a service row.
     assert_eq!(s.eval::<i64>("return GetNumTrainerServices()").unwrap(), 5);
 }
 
-/// **The selection is the service, never the row it sits on** — and a hidden service keeps a row.
-///
-/// `SelectTrainerService` stores the record's spell id (`ds:0xb73a0c`, `0x4d74f0`) and
-/// `GetTrainerSelectionIndex` finds it again by scanning the **whole** array (`0x4d7520`, bounded by
-/// the total `ds:0xb73a10`, not the visible `ds:0xb73a18`). Filtering and collapsing only clear a
-/// record's visible flag `[+0x34]` and sort it into a tail, so the answer for an off-screen
-/// selection is an index *past* `GetNumTrainerServices()` — never a clamp, and never a live row
-/// number belonging to some other service. benilla stored the row number and clamped it, which is
-/// the director's "the info and img below don't update" report: see [`super::selected_row`].
+/// The reference stores the selection as a spell id (`0x4d74f0`) and scans the whole array for it
+/// (`0x4d7520`), so a hidden selection reads past the visible count.
 #[test]
 fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
     let mut s = UiScript::new().unwrap();
@@ -450,13 +399,11 @@ fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
             .unwrap()
     };
 
-    // Bloodrage sits at row 5 of `[H:Arms, Heroic Strike, Cleave, H:Fury, Bloodrage]`.
     s.run("SelectTrainerService(5)").unwrap();
     assert_eq!(sel(&mut s), 5);
     assert_eq!(at(&mut s, 5), "Bloodrage");
 
-    // Hide the already-known state: Cleave leaves and everything under it slides up one. The row
-    // number 5 now names nothing on screen; the selection is still Bloodrage, at row 4.
+    // Hiding Cleave moves Bloodrage up to row 4.
     s.run("SetTrainerServiceTypeFilter('used', 0)").unwrap();
     assert_eq!(at(&mut s, 4), "Bloodrage");
     assert_eq!(
@@ -465,9 +412,7 @@ fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
         "it followed its service, it did not stay put"
     );
 
-    // Fold Bloodrage's group away. It is off screen but not gone: its record goes to the tail, so
-    // the answer is an index past the visible count — which is what sends the stock window down its
-    // "the selection is not on screen" path instead of silently repainting someone else's row.
+    // Row 3 is now the Fury header.
     s.run("CollapseTrainerSkillLine(3)").unwrap();
     let folded = sel(&mut s);
     assert!(
@@ -478,8 +423,7 @@ fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
     s.run("ExpandTrainerSkillLine(3)").unwrap();
     assert_eq!(sel(&mut s), 4, "and back on screen when the group unfolds");
 
-    // He learns it. The re-list brings it back gray and the filter hides it — the tail again, never
-    // the row number of whatever moved up into its place.
+    // Learned, it comes back gray and the filter hides it.
     let mut learned = trainer();
     learned.services[2].category = TrainerServiceCategory::Used;
     s.set_trainer(Some(learned));
@@ -488,23 +432,18 @@ fn the_selection_follows_its_service_and_lands_in_the_tail_when_it_is_hidden() {
         "the learned spell is off screen, not at some live row"
     );
 
-    // A service that has left the trainer's list altogether is the one case that reads 0.
     let mut shorter = trainer();
     shorter.services.remove(2);
     s.set_trainer(Some(shorter));
     assert_eq!(sel(&mut s), 0);
 
-    // A header row is not a selection, and neither is a row past the end.
     s.set_trainer(Some(trainer()));
     s.run("SelectTrainerService(1)").unwrap();
     assert_eq!(sel(&mut s), 0, "row 1 is the Arms header");
 }
 
-/// A new `SMSG_TRAINER_LIST` resets the selection with the rest of the builder's state — `0x4d7560`
-/// selects record 0 after the sort (`0x4d7b40 xor ecx,ecx` → `0x4d7b42 call 0x4d74f0`), which is
-/// always a group header and so reads back as 1. Clearing is the same answer to the only question
-/// the stock window asks (`GetTrainerSelectionIndex() > 1`, which 0 and 1 both fail); what matters
-/// is that a re-opened trainer cannot inherit the last visit's selection.
+/// The reference's list builder re-selects a header (`0x4d7560`, `0x4d7b42`), so a re-opened
+/// trainer never keeps the last visit's selection.
 #[test]
 fn a_new_list_packet_clears_the_selection() {
     let mut s = UiScript::new().unwrap();
@@ -536,23 +475,12 @@ fn clearing_empties_and_resets_selection() {
     );
 }
 
-/// **The tradeskill order, pinned against wow-re's emulated run of the real finalizer** (decision
-/// 1124). The fixture is creature 957 "Dane Lindgren" — the blacksmithing trainer in the director's
-/// report — with his 19 real `npc_trainer` rows: 18 recipes on skill line 164 with ascending
-/// `reqSkillValue`, plus the profession-learn service 2020 ("Apprentice Blacksmith", `reqLevel 5`,
-/// no skill gate). wow-re fed exactly this set through the builder `0x4d7560` + finalizer `0x4d8410`
-/// with `0xb73a08 = 2` and the real `qsort`/collator, and got the 21 rows asserted below.
-///
-/// Two things this pins that benilla had wrong, and one it never had:
-/// - the learn row is **first among services**, under its own `Development Skills` header — placed
-///   by the `SKILL_STEP` group partition, *not* by any level key;
-/// - `reqLevel` is **inert** at type 2 (the class comparator's first key, which used to sink 2020 to
-///   the bottom of the list);
-/// - recipes ascend by `reqSkillValue`, ties broken by name.
+/// Creature 957's 19 vmangos `npc_trainer` rows, in the order the reference's builder `0x4d7560`
+/// and finalizer `0x4d8410` give them at type 2: the `SKILL_STEP` learn row first under its own
+/// header, `reqLevel` inert, the recipes by `reqSkillValue` then name.
 #[test]
 fn tradeskill_trainer_matches_the_emulated_reference_order() {
-    // (wire spell, name, reqSkillValue) — the recipes, in wire order (ascending here, but the
-    // fixture is shuffled below to prove the order is the comparator's and not the input's).
+    // (wire spell, name, reqSkillValue), reversed below so the order must come from the sort.
     let recipes: &[(u32, &str, u32)] = &[
         (2743, "Copper Chain Pants", 1),
         (2754, "Copper Mace", 15),
@@ -576,7 +504,7 @@ fn tradeskill_trainer_matches_the_emulated_reference_order() {
     let mut services: Vec<TrainerService> = recipes
         .iter()
         .map(|&(id, name, req)| {
-            // Group key 2 = TRADESKILL_SERVICE_LEARN: no SKILL_STEP effect on the wire spell.
+            // Group key 2, `TRADESKILL_SERVICE_LEARN`: the wire spell has no `SKILL_STEP` effect.
             let mut s = svc(id, name, TrainerServiceCategory::Unavailable, 2, "Recipes");
             s.subtext = None;
             s.level_req = 0;
@@ -588,8 +516,8 @@ fn tradeskill_trainer_matches_the_emulated_reference_order() {
             s
         })
         .collect();
-    services.reverse(); // wire order is not display order — and must not be
-                        // Group key 1 = TRADESKILL_SERVICE_STEP: spell 2020 carries Effect 44 SKILL_STEP.
+    services.reverse();
+    // Group key 1, `TRADESKILL_SERVICE_STEP`: spell 2020 has effect 44, `SKILL_STEP`.
     let mut learn = svc(
         2020,
         "Apprentice Blacksmith",
@@ -598,7 +526,7 @@ fn tradeskill_trainer_matches_the_emulated_reference_order() {
         "Development Skills",
     );
     learn.subtext = None;
-    learn.level_req = 5; // the key that used to decide everything, and decides nothing here
+    learn.level_req = 5; // inert at type 2
     learn.prof_first_rank = true;
     services.insert(services.len() / 2, learn);
 
@@ -638,10 +566,7 @@ fn tradeskill_trainer_matches_the_emulated_reference_order() {
     assert_eq!(got, expected);
 }
 
-/// **The mount (type 1, the client's "talent") order, pinned against wow-re's emulated run**
-/// (decision 1124): the already-known services fold into the `-1` "My Talents" group, which the
-/// header comparator puts **first**, ahead of the name-ordered skill-line headers; within a group
-/// the state byte sorts available → unavailable → used, then the name.
+/// At a mount trainer the known group's header sorts first (`0x4d7b90`), the rest by name.
 #[test]
 fn mount_trainer_folds_known_services_into_my_talents() {
     let known = |id: u32, name: &str| {
@@ -700,16 +625,13 @@ fn mount_trainer_folds_known_services_into_my_talents() {
         ],
         "the -1 group leads; every other header is name-ordered"
     );
-    // And the type predicates fork on the same dword the sort does.
     assert!(s.eval::<bool>("return IsTalentTrainer() == 1").unwrap());
     assert!(s
         .eval::<bool>("return IsTradeskillTrainer() == nil")
         .unwrap());
 }
 
-/// The **state byte is a sort key at type 1 and only there** — the same three services, ordered by
-/// state (available → unavailable → used) inside one group, where the class cascade would order
-/// them by level and the tradeskill one by skill value.
+/// Only at type 1 is the state byte a sort key (`0x4d8850`).
 #[test]
 fn talent_order_sorts_on_state_within_a_group() {
     let one = |id: u32, name: &str, cat: TrainerServiceCategory| svc(id, name, cat, 762, "Riding");
@@ -728,8 +650,7 @@ fn talent_order_sorts_on_state_within_a_group() {
     let got: Vec<String> = visible(&mut s).into_iter().map(|(n, _)| n).collect();
     assert_eq!(got, ["Riding", "Cee", "Bee", "Aye"]);
 
-    // The same three at a CLASS trainer sort by name instead (equal levels, no skill gates) — the
-    // proof that the comparator really is selected by the type and not shared.
+    // At a class trainer the same three sort by name: equal levels, no skill gates.
     s.set_trainer(Some(TrainerState {
         greeting: String::new(),
         trainer_type: 0,
diff --git a/crates/benilla-ui/src/script/tutorial.rs b/crates/benilla-ui/src/script/tutorial.rs
index 82220a5b..d9fb026f 100644
--- a/crates/benilla-ui/src/script/tutorial.rs
+++ b/crates/benilla-ui/src/script/tutorial.rs
@@ -1,34 +1,23 @@
-//! The tutorial system's four Lua verbs (decision 1976; wow-re
-//! `system/ui/scratch/tutorial-flags.md` §6): the registrar table at `.data 0x846b04` —
-//! `TutorialsEnabled`, `FlagTutorial`, `ClearTutorials`, `ResetTutorials`.
-//!
-//! The banks are the app's (they are wire state, and the fire-once trigger law lives beside the
-//! sites that trigger): the app pushes the **acknowledged** bank's bytes here when they change,
-//! which is all `TutorialsEnabled` reads, and drains the three writes.
-//!
-//! | verb | shape |
-//! |---|---|
-//! | `TutorialsEnabled()` | one value on both legs: the number `1` if ANY byte of the acknowledged bank is not `0xFF`, else `nil` — over the whole bank, not the 50 real ids; `nil` with no bank |
-//! | `FlagTutorial(n)` | `n` must pass `lua_isnumber` else `Usage: FlagTutorial("tutorial")` (the quoted usage is the reference's own, and misleading — a number is required); truncated, `n − 1` must lie in `0..50` else a SILENT no-op; zero values |
-//! | `ClearTutorials()` | zero values; every bit set in both banks and `CMSG_TUTORIAL_CLEAR` |
-//! | `ResetTutorials()` | zero values; every bit cleared in both banks and `CMSG_TUTORIAL_RESET` |
+//! The four tutorial verbs, registered at `0x846b04`. The banks are the app's: it pushes the
+//! acknowledged bank for `TutorialsEnabled` and drains the writes. `ClearTutorials()` sets every
+//! bit of both banks and sends `CMSG_TUTORIAL_CLEAR`; `ResetTutorials()` clears them and sends
+//! `CMSG_TUTORIAL_RESET`. None of the three writers returns a value.
 
 use mlua::{Lua, Value};
 
 use super::binding_abi::{flag, number_arg};
 use super::Model;
 
-/// `FlagTutorial`'s clamp: `0 ≤ n − 1 < 0x32` — the fifty ids `GlobalStrings.lua` names.
+/// `FlagTutorial`'s bound, `0 ≤ n − 1 < 0x32`: the fifty tutorials `GlobalStrings.lua` names.
 const TUTORIAL_IDS: i32 = 0x32;
 
 impl super::UiScript {
-    /// The acknowledged bank's bytes (`None` before `SMSG_TUTORIAL_FLAGS` lands) — what
-    /// `TutorialsEnabled()` scans.
+    /// The acknowledged bank's bytes, `None` before `SMSG_TUTORIAL_FLAGS`.
     pub fn set_tutorial_bank(&mut self, bank: Option<Vec<u8>>) {
         self.model_mut().tutorial_bank = bank;
     }
 
-    /// `FlagTutorial(n)` calls since the last drain: the **0-based** ids (`n − 1`), in range.
+    /// `FlagTutorial(n)` calls since the last drain, as 0-based ids (`n − 1`).
     pub fn take_tutorial_flag_requests(&mut self) -> Vec<u32> {
         std::mem::take(&mut self.model_mut().tutorial_flag_requests)
     }
@@ -47,8 +36,8 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // `TutorialsEnabled()` (`0x4b5960`): scans `[0xb711ec] * 4` bytes of bank B for one ≠ 0xFF;
-    // `1.0` or nil, one value; an unallocated bank skips the loop and answers nil.
+    // `TutorialsEnabled()` (`0x4b5960`): 1 if any of the bank's `[0xb711ec] * 4` bytes is not
+    // 0xFF, the whole bank and not just the fifty ids; else nil, as with no bank.
     g.set(
         "TutorialsEnabled",
         lua.create_function(|lua, ()| {
@@ -61,8 +50,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `FlagTutorial(n)` (`0x4b59b0`): `lua_isnumber` else the Usage raise; `__ftol`; `dec`; `js`
-    // and `cmp 0x32 / jge` bail silently; else the acknowledge-and-send setter with the 0-based id.
+    // `FlagTutorial(n)` (`0x4b59b0`): a non-number raises the reference's usage text, which asks
+    // for a string; truncated, an `n − 1` outside `0..0x32` is a silent no-op.
     g.set(
         "FlagTutorial",
         lua.create_function(|lua, n: Value| {
@@ -102,7 +91,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::UiScript;
 
-    /// `1` or nil, one value, over the WHOLE bank — and nil with none.
     #[test]
     fn tutorials_enabled_scans_the_whole_acknowledged_bank() {
         let mut s = UiScript::new().unwrap();
@@ -128,7 +116,6 @@ mod tests {
         assert_eq!(s.eval::<i64>("return TutorialsEnabled()").unwrap(), 1);
     }
 
-    /// `FlagTutorial`: the number gate's raise, `n − 1`, the silent out-of-range legs, truncation.
     #[test]
     fn flag_tutorial_takes_a_one_based_number_and_bails_silently_off_the_fifty() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/types.rs b/crates/benilla-ui/src/script/types.rs
index 3f33ba67..8f38b434 100644
--- a/crates/benilla-ui/src/script/types.rs
+++ b/crates/benilla-ui/src/script/types.rs
@@ -3,18 +3,11 @@ use mlua::{Lua, Value};
 use crate::layout::{Anchor, Rect};
 use crate::order::ZTarget;
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Public value + extract types (engine-free seams)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-
-/// A simple, engine-free value the host can inject into Lua — the seam the app's net/state→event
-/// bridge (decision 0068 §3) uses to hand `fire_event` its `arg1..argN`. Deliberately not
-/// `mlua::Value` so callers never touch mlua handles (the MAXCSTACK discipline reaches the API too).
+/// A value the host passes into Lua, such as a `fire_event` argument, without an mlua handle.
 #[derive(Clone, Debug, PartialEq)]
 pub enum ScriptValue {
     Nil,
     Bool(bool),
-    /// An integer argument (GUIDs-as-strings aside, most event args are ints/strings).
     Int(i64),
     Number(f64),
     Str(String),
@@ -32,27 +25,20 @@ impl ScriptValue {
     }
 }
 
-/// A texture region's UV mapping — the two live `SetTexCoord` forms.
+/// A texture region's UV mapping, one of the two `SetTexCoord` forms.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum TexCoords {
-    /// The 4-edge crop `[left, right, top, bottom]` (`SetTexCoord(l,r,t,b)` / XML `<TexCoords>`):
-    /// an axis-aligned UV sub-rect in 0..1 texture space, top-left origin. A mirrored
-    /// (`left > right`) or flipped tuple keeps its orientation.
+    /// `SetTexCoord(l,r,t,b)` or XML `<TexCoords>`, 0..1 from the top left; a mirrored or
+    /// flipped tuple keeps its orientation.
     Rect([f32; 4]),
-    /// The 8-arg affine form (`SetTexCoord(ULx,ULy, LLx,LLy, URx,URy, LRx,LRy)`) — an arbitrary
-    /// UV quad (rotation/shear; the reference's `DrawRouteLine` taxi route lines are the first
-    /// consumer). Stored per corner in **screen order `[TL, TR, BR, BL]`** (the renderer's
-    /// `push_quad` winding — the Lua arg order is converted at the binding).
+    /// `SetTexCoord(ULx,ULy, LLx,LLy, URx,URy, LRx,LRy)`, an arbitrary UV quad, stored in screen
+    /// order `[TL, TR, BR, BL]`: the binding reorders the Lua arguments.
     Corners([[f32; 2]; 4]),
 }
 
 impl TexCoords {
-    /// The tightest axis-aligned `[left, right, top, bottom]` containing the mapping (exact for
-    /// `Rect`, the bounding box for `Corners`).
-    ///
-    /// **Not what `GetTexCoord()` reports** — that answers eight per-corner values, and the 4-value
-    /// rect it used to return is a shape the reference has nowhere (decision 1840). This is the
-    /// renderer's and the app's convenience view, and it keeps its callers.
+    /// The mapping's axis-aligned `[left, right, top, bottom]` bounds; not what `GetTexCoord()`
+    /// answers, which is the eight corner values.
     pub fn edges(&self) -> [f32; 4] {
         match *self {
             TexCoords::Rect(e) => e,
@@ -69,210 +55,118 @@ impl TexCoords {
 /// What an [`ExtractedQuad`] carries to a renderer, beyond its rect.
 #[derive(Clone, Debug, PartialEq)]
 pub enum QuadContent {
-    /// The frame's own draw slot (backdrop/scissor seat) — no region visual of its own in v1.
+    /// The frame's own draw slot, which draws nothing itself.
     Frame,
-    /// A `Minimap` widget's own draw slot: the circular HUD map's content hole. The engine core
-    /// carries the resolved rect + the zoom index; the app renderer draws the world into it —
-    /// the streamed tile window, the mask, and the player arrow (decision 0203). Emitted *at the
-    /// frame's own z*, so the widget's children (border art, buttons) paint above the map exactly
-    /// as the reference layers them.
+    /// A `Minimap` widget's content hole, which the app fills with the map; emitted at the
+    /// frame's own z, so the widget's children (border art, buttons) paint above it.
     Minimap {
-        /// The **outdoor** zoom index, `0..MINIMAP_ZOOM_LEVELS` (0 = widest) — see
-        /// [`crate::widget::MinimapState`].
+        /// The outdoor zoom index, `0..MINIMAP_ZOOM_LEVELS`, 0 the widest.
         zoom: u8,
-        /// The **indoor** zoom index (persisted separately; the client's `0x86f69c`). Both travel
-        /// so the app renderer picks by its own WMO-containment test rather than racing the
-        /// `inside` flag it pushed down.
+        /// The indoor zoom index (`0x86f69c`), sent too so the renderer picks by its own test.
         inside_zoom: u8,
     },
-    /// A `Model` / `PlayerModel` widget's own draw slot: the 3D pane's content hole. The engine
-    /// core carries the resolved rect and the pane's identity; the app renderer puts pixels in it
-    /// — the same division of labour [`QuadContent::Minimap`] uses, and for the same reason (the
-    /// scene state is [`crate::widget::ModelState`]; the render is not this crate's).
-    ///
-    /// **The clock is deliberately NOT here.** A pane's play head moves every tick, and the
-    /// host memoizes its whole quad conversion on the extracted list being unchanged — a
-    /// cursor in this variant would re-convert the entire interface every frame a cooldown or a
-    /// ping is showing. The host reads the play heads straight off the engine instead
-    /// (`UiScript::visible_model_panes`, decision 2008); this variant carries only what the
-    /// layout and the Lua setters decide.
-    ///
-    /// **Why the NAME travels rather than the scene.** benilla draws a body pane by sampling an
-    /// off-screen bake the app already keeps per *window* (the paper doll's, the inspect window's,
-    /// the pet page's), and which bake a pane samples is a fact about that window, not about the
-    /// widget. So the seam carries what the app needs to make the join — the pane's global frame
-    /// name, which since decision 1751 is the reference's own — and nothing it would have to
-    /// invent a meaning for. A pane with no name, or one no window has claimed, draws nothing;
-    /// that is also what a `SetModel` pane does today, and it is honest rather than a white slab.
+    /// A `Model` or `PlayerModel` widget's 3D pane: a `model` file draws as a tile, a unit pane
+    /// samples the bake of the window its name belongs to, or nothing. The host memoizes on this
+    /// list, so it reads the moving play head from `UiScript::visible_model_panes` instead.
     ModelPane {
-        /// The pane's frame handle — the renderer's key for the tile it keeps per pane (a name
-        /// is optional and shared by nothing; the handle is neither). Decision 2007.
+        /// The renderer's key for the tile it keeps per pane.
         handle: crate::widget::FrameHandle,
-        /// The pane's global frame name (`$parent`-expanded), or `None` for an anonymous
-        /// `CreateFrame("Model")` — pfUI's autocast shine is the corpus example of the latter.
+        /// The global frame name; `None` for an anonymous `CreateFrame("Model")`.
         name: Option<String>,
-        /// The `SetModel` path the pane holds (`None` for a unit pane or an empty one) — what the
-        /// host's tile renderer draws (decision 2013), the map arrow's `crate::script::ARROW_MODEL`
-        /// among them since 2015.
+        /// The `SetModel` file; `None` for a unit pane or an empty one.
         model: Option<String>,
         /// `SetFacing`'s radians (0 default).
         facing: f32,
         /// `SetModelScale`'s factor (1 default).
         model_scale: f32,
-        /// `SetPosition`'s offset, in the ortho leg's layout units (render law §2: the root is
+        /// `SetPosition`'s offset, in the ortho leg's layout units (`0x76d1a0`: the root is
         /// `T(pos · layoutScale) · R(facing) · S(…)`).
         position: (f32, f32, f32),
-        /// The frame's **own** alpha — what the model instance draws at. The reference re-pushes
-        /// `[widget+0xc8]/255` into the instance on every `Frame:SetAlpha` (`0x76d120`), and
-        /// nothing folds the parent chain in: a pane under a faded parent draws at its own
-        /// alpha (render law §4.4). [`ExtractedQuad::alpha`] carries the effective one.
+        /// The frame's own alpha, which the model draws at: `Frame:SetAlpha` pushes it into the
+        /// instance without the parent chain (`0x76d120`).
         own_alpha: f32,
-        /// `ReplaceIconTexture`'s path — the type-14 texture override, or `None` for the file's
-        /// own textures.
+        /// `ReplaceIconTexture`'s path, the type-14 texture override.
         icon: Option<String>,
-        /// The installed camera as a RAW index into the file's camera table, or `None` for the
-        /// NULL camera. **This is the render leg** (decision 2027): `None` is the orthographic
-        /// one — the model laid flat over the pane's rect — and `Some(n)` the perspective one,
-        /// framed by the file's own record `n`.
+        /// The camera, a raw index into the file's camera table: `None` renders orthographic, the
+        /// model laid flat over the rect, and `Some(n)` in perspective through camera `n`.
         camera: Option<u32>,
-        /// The pane's embedded `CGLight`. Disabled on every shipped pane, which is why an
-        /// unlit-on-every-material UI M2 never notices; a LIT batch under a disabled light draws
-        /// black, and that is the reference's answer, not a gap.
+        /// The embedded `CGLight`, off on every shipped pane; a lit batch under it draws black, as
+        /// in the reference.
         light: crate::widget::ModelLight,
-        /// The pane's fog, only when armed — colour, near and far as the fill callback stages
-        /// them. Per-batch from there: a material with the UNFOGGED bit ignores it.
+        /// The fog, when armed; a material with the UNFOGGED bit ignores it.
         fog: Option<crate::widget::ModelFog>,
     },
-    /// A `Texture` region: a BLP path *or* a solid/vertex color (or both — a tinted texture).
+    /// A `Texture` region: a BLP path, a solid or vertex colour, or both (a tinted texture).
     Texture {
         path: Option<String>,
         color: Option<[f32; 4]>,
-        /// WoW `ADD` blend (highlights/glows) instead of straight alpha.
+        /// The `ADD` blend instead of straight alpha.
         additive: bool,
-        /// The `<TexCoords>`/`SetTexCoord` UV mapping the region samples — the 4-edge crop or the
-        /// 8-arg affine quad ([`TexCoords`]). `None` = the full texture (0,1,0,1). The renderer
-        /// crops (or reprojects) the quad's UVs to this.
+        /// `None` is the full texture.
         tex_coords: Option<TexCoords>,
-        /// Draw masked to the inscribed circle — a **portrait** (`SetPortraitToTexture`, and
-        /// `SetPortraitTexture`'s round unit-portrait binding). The renderer bakes the circular
-        /// alpha so the square icon/model doesn't poke past the frame ring. A `portrait_unit`
-        /// binding with this **false** is the square booth pane (`BenillaSetBoothTexture` —
-        /// the paper doll's model view, decision 0208 §5).
+        /// A portrait, masked to the inscribed circle; false with a `portrait_unit` is the square
+        /// booth pane (`BenillaSetBoothTexture`).
         circular: bool,
-        /// A **live unit portrait** (`SetPortraitTexture(region, unit)` round;
-        /// `BenillaSetBoothTexture(region, token)` square — `circular` above distinguishes): the
-        /// unit token whose model this region renders. When `Some`, the renderer ignores
-        /// `path`/`color` and samples the app-side portrait render-target for this token (the
-        /// off-screen model bake). `None` = an ordinary texture/color region. The engine-free core
-        /// only carries the token; resolving it to a rendered image is the app's job (the modern
-        /// 2D portrait is a high-res model bake).
+        /// A live unit portrait's unit: the renderer samples the app's bake of it instead of
+        /// `path` and `color`.
         portrait_unit: Option<String>,
-        /// On-screen rotation about the quad center, radians, **counterclockwise-positive**.
-        ///
-        /// **Always `0.0` now — nothing writes it any more.** It carried a later-era
-        /// `Texture:SetRotation` benilla shipped early so the world-map player arrow could spin,
-        /// standing in for the reference's engine arrow model (0203 flags the stand-in). That arrow
-        /// became a real Model frame driven by `ModelState::facing` (`script::worldmap_arrow`), and
-        /// the verb has since come off the Texture map — 1.12 registers `SetRotation` on PlayerModel
-        /// alone (`0x84f1fc`). The plumbing is left standing rather than pruned in the same change,
-        /// because it runs into the app's quad emit; see [`RegionData::rotation`].
+        /// Rotation about the centre, radians counterclockwise; always 0, since 1.12 registers
+        /// `SetRotation` on PlayerModel alone (`0x84f1fc`).
         rotation: f32,
-        /// `Texture:SetDesaturated(1)` — draw the sampled texel as its **luminance** instead of
-        /// its colour (decision 1327). The renderer greys the texel and *then* modulates by
-        /// `color`, because the reference's own consumers pass a dim tint alongside the flag
-        /// (`SetItemButtonDesaturated(button, 1, 0.65, 0.65, 0.65)`) and expect both to land.
+        /// `SetDesaturated`: the texel draws as its luminance, then is tinted by `color`, since
+        /// `SetItemButtonDesaturated` passes a dim tint with the flag.
         desaturated: bool,
     },
-    /// A `ColorSelect`'s **hue disc** — its `<ColorWheelTexture>` region. That element carries no
-    /// `file=` in the reference either: the wheel is generated by the client, not loaded, and there
-    /// is no BLP anywhere in the MPQ chain that is a colour wheel. So the engine core hands the
-    /// renderer the rect and the widget's HSV and the app makes the pixels — the same division the
-    /// [`QuadContent::Minimap`] slot uses, for the same reason.
-    ///
-    /// The disc it must draw is fixed by the *pick* law it has to invert (wow-re
-    /// `colorselect-color-law.md` §5): at normalised offset `(nx, ny)` from the rect's centre the
-    /// pixel is `HSV(atan2(ny, nx)·180/π + 180, min(|n|, 1), …)`, so clicking a pixel selects the
-    /// colour that pixel shows.
-    ///
-    /// **It carries no colour**, and that is the byte law rather than an omission: the fill loop
-    /// draws every texel at a literal `V = 1.0` (`0x78b68b`) and never reads the widget's own
-    /// value, so the disc is the same image at every colour. Handing the renderer an HSV it must
-    /// ignore would also churn this quad on every step of a drag, for no pixel.
+    /// A `ColorSelect`'s `<ColorWheelTexture>` disc, generated: the pixel at normalised offset
+    /// `(nx, ny)` from the centre is `HSV(atan2(ny, nx)·180/π + 180, min(|n|, 1), 1)`, inverting
+    /// the pick law (`0x78bd80`); the fill draws every texel at `V = 1` (`0x78b68b`), so no colour
+    /// travels.
     ColorWheel,
-    /// A `ColorSelect`'s **brightness strip** — its `<ColorValueTexture>` region, the wheel's
-    /// file-less twin. A vertical ramp of the currently selected hue and saturation, black at the
-    /// bottom, which is the inverse of the strip's own pick law
-    /// (`V = clamp((y − bottom)/(top − bottom), 0, 1)`).
+    /// A `ColorSelect`'s `<ColorValueTexture>` strip: the hue and saturation, black at the
+    /// bottom, the inverse of its pick law `V = clamp((y − bottom)/(top − bottom), 0, 1)`.
     ColorValue {
-        /// The widget's hue, degrees.
+        /// Degrees.
         hue: f32,
-        /// The widget's saturation, `0..=1`. Together these are the whole strip: its top is
-        /// `HSV(hue, sat, 1)` and its bottom is black, so the widget's **value** moves no pixel of
-        /// it (only its marker).
+        /// `0..=1`; the widget's value moves only its marker, never the strip.
         sat: f32,
     },
-    /// One frame `Backdrop` piece (the tiled bg, or one of the 8 border pieces) — emitted at the
-    /// owning frame's own draw slot, behind its regions ([`UiScript::extract`](super::UiScript::extract)). A textured quad
-    /// whose UVs are four explicit per-corner pairs (`[TL, TR, BR, BL]`, screen order) because the
-    /// TOP/BOTTOM edges are rotated 90°, and whose texture needs REPEAT addressing (edges tile).
-    /// The [`ExtractedQuad::rect`] is the piece's screen bounding box.
+    /// One `Backdrop` piece, the tiled background or one of the 8 border pieces, drawn in the
+    /// frame's slot behind its regions; per-corner UVs, since the top and bottom edges turn 90°.
     Backdrop {
-        /// The bg or edge texture path.
         path: String,
-        /// The bg (`SetBackdropColor`) or border (`SetBackdropBorderColor`) vertex tint, pre-alpha.
+        /// The `SetBackdropColor` or `SetBackdropBorderColor` tint, pre-alpha.
         color: [f32; 4],
-        /// Four per-corner UVs, `[TL, TR, BR, BL]` (screen order).
+        /// `[TL, TR, BR, BL]`, screen order.
         uvs: [[f32; 2]; 4],
-        /// Sample the texture with REPEAT (wrap) addressing.
+        /// Sample with repeat (wrap) addressing.
         tile: bool,
     },
-    /// A `FontString` region: its text, color, horizontal justification, and the resolved font
-    /// (path + height + shadow) from its font object / `SetFont` — rendering/metrics are the Bevy
-    /// side's job (it honors [`QuadContent::Text::justify_h`], picks the face by `font`, bakes at
-    /// `height`, and draws [`QuadContent::Text::shadow`] as an offset dark pass behind the glyphs).
+    /// A `FontString` region with its resolved font; the app measures and draws it.
     Text {
         text: Option<String>,
         color: Option<[f32; 4]>,
         justify_h: JustifyH,
         justify_v: JustifyV,
-        /// The resolved font face path (`SetFontObject`/`SetFont`/XML `inherits=`), e.g.
-        /// `"Fonts\\FRIZQT__.TTF"`. `None` ⇒ the renderer's default face (Friz Quadrata).
+        /// The face path, e.g. `"Fonts\\FRIZQT__.TTF"`; `None` is Friz Quadrata.
         font: Option<String>,
-        /// The resolved font height in logical px. `None` ⇒ the renderer's default size.
+        /// Logical px; `None` is the renderer's default size.
         font_height: Option<f32>,
-        /// The `SetTextHeight` override (see [`RegionData::text_height`]): `Some` = the
-        /// scaled-string regime — draw at THIS height, uncapped (the one-to-one 32-px raster cap
-        /// applies only when this is `None`).
+        /// The `SetTextHeight` override, drawn uncapped; `None` keeps the 32 px raster cap.
         text_height: Option<f32>,
-        /// The resolved drop shadow (font object `<Shadow>` — offset + color). The real 1.12
-        /// `MasterFont` root carries `(1,-1)` black, so nearly every stock font is shadowed; the
-        /// crispness of client text against parchment/world IS this shadow.
+        /// 1.12's `MasterFont` sets `(1,-1)` black, so nearly every stock font has one.
         shadow: Option<FontShadow>,
-        /// The resolved glyph outline (`outline="NORMAL"/"THICK"`). The Number* fonts (action-bar
-        /// hotkeys/counts) carry it; the renderer draws it as a black offset halo under the fill —
-        /// `cosmic-text` has no native outline. `None` for the common un-outlined case.
         outline: Outline,
-        /// The write-on reveal (`SetAlphaGradient` — see [`RegionData::alpha_gradient`]): the
-        /// renderer multiplies each glyph's alpha by the ramp at its character position (before
-        /// `start` opaque, the next `length` chars 1→0, beyond invisible). `None` = draw whole.
+        /// `SetAlphaGradient`: before `start` opaque, the next `length` characters fading from 1
+        /// to 0, the rest invisible.
         alpha_gradient: Option<(f32, f32)>,
-        /// **Seat this block exactly where `rect` puts it**, skipping the UI grid's vertical
-        /// block-top snap — true for a FontString owned by a V-plate, false for every other one
-        /// (`super::nameplate::is_world_seated`, decision 2172).
-        ///
-        /// Not a client concept: in the reference the whole interface *is* the pixel grid, so the
-        /// snap and the rect agree by construction. benilla has one family of frames that lives
-        /// outside it — the WorldFrame overlays that slide continuously over the 3-D scene, whose
-        /// seat law is a DEVICE-pixel snap (`vplates::device_snap`, 0188/1398) rather than the
-        /// UI's logical-pixel one. Snapping their text on the coarser UI grid makes it *beat*
-        /// against the art it is supposed to be rigid to: two quantizers on one sliding object.
+        /// Seat the text at `rect` without the UI grid's block-top snap: true on a nameplate
+        /// (`super::nameplate::is_world_seated`), which slides on a device-pixel snap, so a second
+        /// snap would jitter its text. Not a reference field.
         world_seat: bool,
     },
 }
 
-/// A `FontString`'s horizontal text justification within its resolved rect — the XML `justifyH`
-/// attr (`SetJustifyH`). The FrameXML default is **CENTER** (the client's `JustifyH` field default);
-/// the app's text renderer positions each line's run against the rect per this.
+/// A `FontString`'s horizontal justification (`justifyH`, `SetJustifyH`); CENTER by default.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum JustifyH {
     Left,
@@ -281,12 +175,8 @@ pub enum JustifyH {
     Right,
 }
 
-/// A `FontString`'s vertical text justification within its resolved rect — the XML `justifyV`
-/// attr (`SetJustifyV`). The FrameXML default is **MIDDLE** (the client's `JustifyV` field
-/// default) — a sized FontString centers its line block vertically, which is why the real
-/// client's 13px money numbers sit on their coin icons' centerline. The app's text renderer
-/// offsets the line block against the rect per this (no-op for a rect sized to its text, i.e.
-/// every host-measured height-less FontString).
+/// A `FontString`'s vertical justification (`justifyV`, `SetJustifyV`); MIDDLE by default, so a
+/// sized FontString centres its lines.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum JustifyV {
     Top,
@@ -295,44 +185,26 @@ pub enum JustifyV {
     Bottom,
 }
 
-/// A Texture's blend mode — the client's shared `alphaMode` enum, the `{value, name}` table at
-/// `0x811aa8`: `DISABLE=0 · ALPHAKEY=1 · BLEND=2 · ADD=3 · MOD=4` (wow-re
-/// `system/ui/ui.md:1383`, `scratch/rf28-typed-widget-loadxml.md:22`). It is one enum reached two
-/// ways — the XML `alphaMode=` attribute and `Texture:SetBlendMode` — and read back by
-/// `Texture:GetBlendMode`.
-///
-/// **`Blend` is the default because the CSimpleTexture ctor writes it**: `0x76fc64 mov
-/// [esi+0xd0],2`, which `ActionButtonTemplate.xml`'s `<NormalTexture>` keeps by declaring no
-/// `alphaMode` (wow-re `scratch/button-state-texture-path-setter.md`, where the value is
-/// load-bearing for a different question and therefore evidence rather than assertion — mode 1
-/// would alpha-test a half-alpha vertex colour away entirely, mode 2 ghosts it). It is the answer
-/// every ordinary texture gives `ShaguTweaks/mods/dark-ui-elements.lua:169`'s
-/// `region:GetBlendMode() == "ADD"` guard, so getting it wrong is the same recolouring bug one
-/// branch over.
-///
-/// **Only ADD changes what this engine draws.** The renderer takes the ADD/not-ADD bit
-/// ([`QuadContent::Texture::additive`]); `DISABLE`, `ALPHAKEY` and `MOD` are carried faithfully
-/// through the setter and the getter and drawn as straight alpha — the stated v1 gap, unchanged by
-/// storing the whole mode instead of a bool.
+/// A Texture's blend mode, the client's `alphaMode` enum (`0x811aa8`), set by XML `alphaMode=`
+/// or `SetBlendMode`; BLEND is the constructor's (`0x76fc64 mov [esi+0xd0],2`). The renderer
+/// acts only on ADD: the others draw as straight alpha, their reference blending not built.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum BlendMode {
-    /// `DISABLE` = 0 — `GL_ONE, GL_ZERO`, alpha reference 0. Drawn as straight alpha here.
+    /// `DISABLE` (0): `GL_ONE, GL_ZERO`, alpha reference 0.
     Disable,
-    /// `ALPHAKEY` = 1 — `GL_ONE, GL_ZERO` with alpha reference 224/255. Drawn as straight alpha here.
+    /// `ALPHAKEY` (1): `GL_ONE, GL_ZERO`, alpha reference 224/255.
     AlphaKey,
-    /// `BLEND` = 2 — `GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA`. The ctor's value, hence the default.
+    /// `BLEND` (2): `GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA`.
     #[default]
     Blend,
-    /// `ADD` = 3 — `GL_SRC_ALPHA, GL_ONE`. The one mode the renderer acts on.
+    /// `ADD` (3): `GL_SRC_ALPHA, GL_ONE`.
     Add,
-    /// `MOD` = 4 — `GL_DST_COLOR, GL_ZERO`. Drawn as straight alpha here.
+    /// `MOD` (4): `GL_DST_COLOR, GL_ZERO`.
     Mod,
 }
 
 impl BlendMode {
-    /// Parse the enum's own spelling, as `SetBlendMode` and the XML `alphaMode=` attribute take it.
-    /// Case-insensitive (the Lua binding coerces through the shared string-arg law); `None` for a
-    /// name outside the table's five.
+    /// Parse the name, case-insensitively, as `SetBlendMode` and XML `alphaMode=` take it.
     pub fn parse(s: &str) -> Option<BlendMode> {
         match s.to_ascii_uppercase().as_str() {
             "DISABLE" => Some(BlendMode::Disable),
@@ -344,7 +216,7 @@ impl BlendMode {
         }
     }
 
-    /// The reference's own spelling, as `GetBlendMode()` answers it (the name column of `0x811aa8`).
+    /// The name `GetBlendMode()` answers (the name column of `0x811aa8`).
     pub const fn name(self) -> &'static str {
         match self {
             BlendMode::Disable => "DISABLE",
@@ -356,10 +228,7 @@ impl BlendMode {
     }
 }
 
-/// A `FontString`'s glyph outline (the XML `outline`/`<Font outline=>` attr, OUTLINETYPE): `NONE`
-/// (the common case), `NORMAL`, or `THICK`. Resolved through the font registry and readable via
-/// `GetFont`; the v1 text renderer does **not** yet rasterize outlines (a documented gap — the atlas
-/// bakes plain coverage), so this is carried for fidelity/round-tripping, not drawn.
+/// A `FontString`'s glyph outline (XML `outline=`, OUTLINETYPE), answered by `GetFont`.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum Outline {
     #[default]
@@ -369,8 +238,8 @@ pub enum Outline {
 }
 
 impl Outline {
-    /// Parse the **XML** OUTLINETYPE attribute (`outline="NONE"/"NORMAL"/"THICK"`,
-    /// case-insensitive); unknown ⇒ `None`. This is *not* the Lua spelling — see [`Outline::flags`].
+    /// Parse the XML `outline=` attribute, case-insensitively; not the Lua spelling, which is
+    /// [`Outline::flags`].
     pub fn parse(s: &str) -> Outline {
         match s.to_ascii_uppercase().as_str() {
             "NORMAL" => Outline::Normal,
@@ -379,22 +248,9 @@ impl Outline {
         }
     }
 
-    /// Parse a **Lua `SetFont` flags string** — a different vocabulary from the XML attribute
-    /// above, and mixing the two is a silent no-op: `SetFont(path, h, "OUTLINE")` through
-    /// [`Outline::parse`] matches nothing and lands on `NONE`.
-    ///
-    /// The reference reads the argument as a *set* of substrings against
-    /// `{0x1 OUTLINE, 0x4 THICKOUTLINE, 0x2 MONOCHROME}` (`0x811b10`, wow-re
-    /// `system/ui/scratch/widget-api-batch-benilla.md` Q8), which is why this is `contains` and not
-    /// equality — `"OUTLINE, MONOCHROME"` is a real thing addons write. MONOCHROME has no field
-    /// here (we model no glyph AA mode) and is ignored; `THICK` is checked first because
-    /// `"THICKOUTLINE"` contains `"OUTLINE"`.
-    ///
-    /// One function, three callers: `Button:SetFont`, `FontString:SetFont` and `Font:SetFont` all
-    /// delegate to the *same* impl in the reference (`0x79f210`), so they cannot be allowed to
-    /// disagree here. They did: the Font-object binding parsed its Lua flags with the XML reader,
-    /// so `GameFontNormal:SetFont(f, h, "OUTLINE")` silently cleared the outline instead of setting
-    /// it, while the FontString binding carried its own inline copy of this match.
+    /// Parse a Lua `SetFont` flags string, shared by every `SetFont` (`0x79f210`) and matched by
+    /// substring against `{0x1 OUTLINE, 0x4 THICKOUTLINE, 0x2 MONOCHROME}` (`0x811b10`): THICK
+    /// first, since `THICKOUTLINE` contains `OUTLINE`. MONOCHROME is ignored, its mode not built.
     pub fn flags(s: &str) -> Outline {
         let s = s.to_ascii_uppercase();
         if s.contains("THICK") {
@@ -406,7 +262,7 @@ impl Outline {
         }
     }
 
-    /// The OUTLINETYPE token (for `GetFont`'s flags return).
+    /// The flags token `GetFont` answers.
     pub fn as_str(self) -> &'static str {
         match self {
             Outline::None => "",
@@ -416,89 +272,63 @@ impl Outline {
     }
 }
 
-/// A font object's drop shadow (`<Shadow><Offset/><Color/></Shadow>`): pixel offset in WoW y-up
-/// XML convention (`y="-1"` = 1px down) + color. Inherited down `<Font>` chains like every other
-/// paint field (the 1.12 `MasterFont` root sets `(1,-1)` black — ref-Fonts.xml l.55-62).
+/// A font object's `<Shadow>`, inherited down `<Font>` chains; 1.12's `MasterFont` sets `(1,-1)`
+/// black (`Fonts.xml:55`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct FontShadow {
-    /// XML `<Offset><AbsDimension x= y=/>` — WoW y-up (negative y = down-screen).
+    /// Pixels, y up: `y="-1"` is 1 px down.
     pub offset: [f32; 2],
-    /// `<Color r= g= b= a=/>`; alpha defaults 1.
+    /// Alpha defaults to 1.
     pub color: [f32; 4],
 }
 
-/// A named virtual **Font object** (`<Font name=… font=… inherits=…>`): the resolved paint a
-/// `FontString` picks up by `inherits=`/`SetFontObject`. Values are already flattened through the
-/// `<Font>` inherits chain (rooted at a real TTF path); any field the chain never set is `None`
-/// (the renderer falls back). This is the registry entry [`Model::font_objects`](super::Model::font_objects) keys by name.
+/// A named `<Font>` object's paint, flattened through its `inherits=` chain; a field the chain
+/// never sets is `None`.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct FontObject {
-    /// The TTF path (`font="Fonts\\FRIZQT__.TTF"`), inherited down the chain.
+    /// The TTF path (`font=`).
     pub font: Option<String>,
-    /// The font height in logical px (`<FontHeight><AbsValue val=/>`).
+    /// Logical px (`<FontHeight>`).
     pub height: Option<f32>,
-    /// The drop shadow (`<Shadow>`), inherited down the chain like the rest of the paint.
     pub shadow: Option<FontShadow>,
-    /// The text color (`<Color r= g= b= a=/>`).
     pub color: Option<[f32; 4]>,
-    /// The glyph outline (`outline=` attr).
     pub outline: Outline,
-    /// The default horizontal justification (`justifyH=` attr), if the object sets one.
     pub justify_h: Option<JustifyH>,
-    /// The default vertical justification (`justifyV=` attr), if the object sets one.
     pub justify_v: Option<JustifyV>,
 }
 
-/// One entry of the render list [`UiScript::extract`](super::UiScript::extract) produces: a draw target in the client's exact
-/// painter order (the [`crate::order::traversal`] `ZKey` order), its resolved screen rect (if the
-/// layout pass resolved it), the effective alpha to draw at, and its content. This is the seam the
-/// Bevy extractor consumes; it names only this crate's own types (handles, [`Rect`]) — no engine.
+/// One entry of [`UiScript::extract`](super::UiScript::extract)'s render list, in the client's
+/// painter order ([`crate::order::traversal`]).
 #[derive(Clone, Debug, PartialEq)]
 pub struct ExtractedQuad {
-    /// The draw target (a frame's own slot, or one of its regions).
+    /// A frame's own slot, or one of its regions.
     pub target: ZTarget,
-    /// The packed draw-order key (`ZKey::raw`); entries are already sorted ascending by it.
+    /// The packed draw-order key (`ZKey::raw`); entries are sorted ascending by it.
     pub z: u64,
-    /// The resolved rect (`[bottom, left, top, right]`, screen px, y-up). `None` if the owning frame
-    /// is under-constrained (no resolvable anchors) — a renderer skips it. A region's rect is its
-    /// own owner-relative resolution when it carries anchors, else centered-on / filling its owner
-    /// (see [`UiScript::extract`](super::UiScript::extract)).
+    /// `None` when the owning frame's anchors do not resolve; a renderer skips it.
     pub rect: Option<Rect>,
-    /// The effective alpha to draw at: for a frame slot its own `effective_alpha`; for a region the
-    /// verified single-hop product `region.alpha × ownerFrame.effective_alpha` (see
-    /// [`RegionData::alpha`]).
+    /// A frame's `effective_alpha`, or a region's alpha times its owner's, one hop only.
     pub alpha: f32,
-    /// The renderable content.
     pub content: QuadContent,
-    /// The ScrollFrame clip this quad draws within (decision 0112): `Some(rect)` when the owning
-    /// frame is a ScrollFrame's scroll child, or any descendant of one — nested ScrollFrames
-    /// intersect (see [`UiScript::extract`](super::UiScript::extract)'s `effective_clip`). `None` = unclipped, the common case.
+    /// The ScrollFrame clip of a scroll child and its descendants, nested ones intersecting.
     pub clip: Option<Rect>,
-    /// The owning frame's `effective_scale` (`propagation.md`: `parentScale · ownScale`). The
-    /// `rect` above already carries it — the layout solver multiplies every placement by the
-    /// owner's scale — but glyph METRICS don't live in the rect: the renderer must rasterize a
-    /// `Text` quad's font at `font_height × scale` (and scale the shadow offset with it) or a
-    /// `SetScale`'d window draws scaled boxes full of unscaled text, the exact divergence
-    /// decision 0219 §2 recorded. 1.0 for the unscaled common case.
+    /// The owner's `effective_scale` (`0x76ac90`), already in `rect`; a `Text` quad's font and
+    /// shadow offset must be scaled by it too.
     pub scale: f32,
 }
 
-/// The visual state of a region leaf (`Texture`/`FontString`), stored beside the arena because
-/// [`crate::widget::Region`] models only structure (kind/owner/layer), not paint. See [`object`]'s
-/// `SetTexture`/`SetVertexColor`/`SetText`.
 /// A two-stop linear gradient (`SetGradientAlpha`/`SetGradient`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Gradient {
-    /// `true` for `"VERTICAL"`, `false` for `"HORIZONTAL"` — the client matches the token
-    /// case-insensitively and treats anything else as horizontal.
+    /// `"VERTICAL"`, matched case-insensitively; anything else is horizontal, as in the client.
     pub vertical: bool,
-    /// The gradient's two stops, RGBA. `SetGradient` (no alpha) sets both alphas to 1.
+    /// RGBA; `SetGradient`, which takes no alpha, sets both alphas to 1.
     pub start: [f32; 4],
     pub end: [f32; 4],
 }
 
 impl Gradient {
-    /// The single colour a one-tint quad can show for this gradient — the midpoint.
+    /// The midpoint, the one colour a one-tint quad can show.
     pub fn midpoint(&self) -> [f32; 4] {
         let mut out = [0.0; 4];
         for (i, chan) in out.iter_mut().enumerate() {
@@ -510,195 +340,91 @@ impl Gradient {
 
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct RegionData {
-    /// Region-level visibility (`Show`/`Hide` on a Texture/FontString, XML `hidden=` — the real
-    /// VisibleRegion bit): a hidden region emits no quad regardless of its owner frame's state.
-    /// The ref's own kit relies on it (PanelTemplates_SelectTab hides tab slice textures;
-    /// ContainerFrame_Update hides cooldown textures).
+    /// `Show`/`Hide` and XML `hidden=`: a hidden region emits no quad, whatever its owner's state.
     pub(crate) hidden: bool,
-    /// The region's own alpha (`SetAlpha`/`GetAlpha`, XML `alpha=`); `None` = never set = 1.0.
+    /// `SetAlpha`, XML `alpha=`; `None` is 1. Drawn times the owner frame's alpha, one hop only:
+    /// frame `SetAlpha` (`0x76a690`) cascades to child frames and only invalidates regions.
     ///
-    /// A region draws at `ownAlpha × ownerFrame.alpha` — a **single hop** to its immediate owner,
-    /// never a product up the tree (wow-re `propagation.md`, VERIFIED: frame `SetAlpha 0x76a690`
-    /// overwrite-cascades onto child *frames* and only *invalidates* child regions, which re-read
-    /// the owner's `+0xc8` at draw). [`UiScript::extract`](super::UiScript::extract) folds this into
-    /// [`ExtractedQuad::alpha`] alongside that owner alpha.
-    ///
-    /// **Settled for a Texture, kept distinct anyway:** `Texture:SetAlpha 0x79b580` is
-    /// `SetVertexColor(r, g, b, a)` on the *same* `+0xa8`/`+0xb8` slot as [`Self::vertex_color`], so
-    /// in the real client the two clobber each other. We keep them separate fields because the draw
-    /// result is identical either way — both readings end in one product,
-    /// `texel × ownColorAlpha × frameAlpha` — and no reference call site sets both on one region;
-    /// separate storage additionally keeps `SetAlpha` on a FontString from wiping its font object's
-    /// colour, which the CSimpleFontString half of that binding was never pinned for. The
-    /// divergence is now *known* rather than open: a call site that sets both is where it bites.
+    /// Deviation: kept apart from [`Self::vertex_color`], which the reference's `Texture:SetAlpha`
+    /// (`0x79b580`) rewrites, because the drawn product differs only on a region that sets both,
+    /// which no stock code does, and a FontString's `SetAlpha` then keeps its font colour.
     pub(crate) alpha: Option<f32>,
     /// A texture path (`SetTexture("Interface\\...")`).
     pub(crate) texture: Option<String>,
-    /// The **solid-colour texture** (`SetTexture(r, g, b, a)`, and XML `<Texture><Color/></Texture>`
-    /// with no `file=`) — the `+0xcc` slot [`Self::texture`] also occupies, so the two are mutually
-    /// exclusive by construction: every writer of one clears the other. Not a tint. The real client
-    /// really does *generate an 8×8 texture* here (`CSimpleTexture::SetTexture(const CImVector*)`
-    /// `0x770360` → `0x44a9c0` → the `rep stos` generator `0x5c5350` fills 64 texels with the packed
-    /// ARGB), which is why the XML alpha rides in the **texel** and multiplies with
-    /// [`Self::vertex_color`] rather than being replaced by it.
+    /// `SetTexture(r, g, b, a)` or an XML `<Color>` with no `file=`, sharing `+0xcc` with
+    /// [`Self::texture`]: setting one clears the other. The reference makes an 8×8 texture of it
+    /// (`0x770360` → `0x44a9c0` → `0x5c5350`), so its alpha multiplies with the vertex colour's.
     pub(crate) fill: Option<[f32; 4]>,
-    /// `SetGradientAlpha(orientation, r1,g1,b1,a1, r2,g2,b2,a2)` / `SetGradient(...)` — the two-stop
-    /// linear gradient the client generates into the same texture slot the colour form fills.
-    ///
-    /// **Stored in full, painted as its midpoint, and that gap is stated rather than implied.** The
-    /// UI renderer has one tint per quad (a colour region is the shared 1x1 white image tinted), so
-    /// there is nowhere yet to put a second stop; folding to the average is a *visible*
-    /// approximation and belongs to the director to judge (method §7). It is kept whole HERE so the
-    /// renderer can honour it later without another API change — the data is already right, only
-    /// the paint is coarse.
-    ///
-    /// Measured cost of the approximation on the corpus's biggest consumer: `FuBar_Panel.lua:144`
-    /// is `SetGradientAlpha("VERTICAL", 1,1,1,0, 1,1,1,0.5*t)` — **white at both stops, alpha
-    /// only**, i.e. a soft fade, and both textures are `Hide()`n on the next two lines. A uniform
-    /// half-alpha band instead of a fade is the whole difference there.
+    /// `SetGradientAlpha`/`SetGradient`, stored whole and drawn as its midpoint: the renderer has
+    /// one tint per quad, so the reference's gradient is not built.
     pub(crate) gradient: Option<Gradient>,
-    /// The **vertex colour** (`SetVertexColor 0x79abd0` → `0x77f750`, writing `+0xb8`; a StatusBar's
-    /// `SetStatusBarColor`; a FontString's `SetTextColor` and its font object's colour) — storage
-    /// distinct from [`Self::fill`]/[`Self::texture`]'s `+0xcc`.
-    ///
-    /// **Draw law** (wow-re `system/ui/scratch/texture-color-composition.md`, VERIFIED):
-    /// `drawn = texel × vertexColour`, per channel, **alpha included**. `None` = never set = the
-    /// untinted white every region draws at by default. This is why the reference `SkillFrame`'s
-    /// row trough — declared `<Color 1,1,1,0.2>`, then `SetVertexColor(0, 0, 0.75, 0.5)`'d — draws
-    /// at alpha `0.2 × 0.5 = 0.1`, not `0.5`. [`super::extract`] does that multiply.
+    /// `SetVertexColor` (`0x79abd0` → `0x77f750`, `+0xb8`), `SetStatusBarColor` or a text colour,
+    /// drawn as `texel × colour` per channel, alpha included: a `<Color 1,1,1,0.2>` tinted
+    /// `(0, 0, 0.75, 0.5)` draws at alpha 0.1, as `SkillFrame`'s row trough does.
     pub(crate) vertex_color: Option<[f32; 4]>,
-    /// This region is a **portrait**: draw its texture masked to the inscribed circle (set by
-    /// `SetPortraitToTexture`, and by `SetPortraitTexture`'s round unit binding). WoW portraits
-    /// are circular — the frame ring is a thin band whose transparent corners would otherwise
-    /// expose the square icon/model. The app bakes the circular alpha mask; the flag rides
-    /// through [`QuadContent::Texture::circular`]. False with a live `portrait_unit` = the square
-    /// booth pane (`BenillaSetBoothTexture`, decision 0208 §5).
+    /// A portrait (`SetPortraitToTexture`, `SetPortraitTexture`), masked to the inscribed circle;
+    /// false with a `portrait_unit` is the square booth pane (`BenillaSetBoothTexture`).
     pub(crate) circular: bool,
-    /// A **live unit portrait** (`SetPortraitTexture(region, unit)` round;
-    /// `BenillaSetBoothTexture(region, token)` square): the unit token whose model this region
-    /// renders. `Some` ⇒ the region samples the app's off-screen portrait bake for this token
-    /// (ignoring `texture`/`color`); rides through [`QuadContent::Texture::portrait_unit`]. Cleared by
-    /// `SetTexture`/`SetPortraitToTexture` (the region becomes an ordinary texture again).
+    /// A live unit portrait's unit, drawn from the app's bake instead of the texture or colour;
+    /// cleared by `SetTexture` and `SetPortraitToTexture`.
     pub(crate) portrait_unit: Option<String>,
     /// FontString text (`SetText`).
     pub(crate) text: Option<String>,
-    /// The write-on reveal (`SetAlphaGradient(start, length)` — CSimpleFontString's per-character
-    /// alpha gradient, the quest-description "writing" machinery): characters before `start` draw
-    /// opaque, the next `length` ramp 1→0, the rest invisible. `None` = no gradient (every
-    /// FontString but an armed quest description). Cleared by `SetText` — fresh text draws whole.
+    /// `SetAlphaGradient(start, length)`, the quest text's write-on reveal; cleared by `SetText`.
     pub(crate) alpha_gradient: Option<(f32, f32)>,
-    /// The region's blend mode (`SetBlendMode` / XML `alphaMode` — the reference's `[texture+0xd0]`,
-    /// the shared enum `0x811aa8`). Highlight state textures are created at
-    /// [`BlendMode::Add`] (the client's `SetHighlightTexture` contract); everything else starts at
-    /// the ctor's [`BlendMode::Blend`].
-    ///
-    /// **The whole mode is kept, not just "is it ADD"**, because `GetBlendMode` answers it back as
-    /// a string and a getter that could only ever say `"BLEND"` or `"ADD"` would answer `"BLEND"`
-    /// to a texture the caller set to `"MOD"`. The renderer still reads only the ADD/not-ADD
-    /// distinction ([`QuadContent::Texture::additive`]) — that is unchanged, and the three modes it
-    /// flattens are the stated gap they always were.
+    /// `SetBlendMode`, XML `alphaMode` (the reference's `+0xd0`), starting at [`BlendMode::Add`]
+    /// for a highlight texture, as `SetHighlightTexture` makes it, else at the constructor's BLEND.
     pub(crate) blend: BlendMode,
-    /// Explicit region size (`SetWidth`/`SetHeight`/XML `<Size>`); `None` = derive. Size fills the
-    /// axis the anchors don't pin (the client's "0 = derive") — so under a texture's implicit
-    /// SetAllPoints (two corners pin everything) an authored size is structurally unread, which is
-    /// how the reference stack-split plate authors 256×32 and renders 172×96 (decision 1310, B180).
+    /// `SetWidth`/`SetHeight`, XML `<Size>`; `None` derives it. It fills only an axis the anchors
+    /// leave free, so under an implicit `SetAllPoints` the stack-split plate's 256×32 is unread.
     pub(crate) size: Option<(f32, f32)>,
-    /// Region anchors (`SetPoint`/XML `<Anchors>` on a Texture/FontString). An anchor's
-    /// `relative_to` defaults to the owner frame and may name a frame or a **sibling region**
-    /// (resolved via [`Model::region_names`]; the fixpoint in [`UiScript::resolve`] orders the
-    /// sibling chain). Every drawable region carries at least one — authored, or the
-    /// creation-path implicit anchor ([`super::region::implicit_creation_anchor`], decision
-    /// 1310); empty means a templateless Lua region nobody anchored, which never resolves and
-    /// never draws. Non-empty ⇒ resolved in [`UiScript::resolve`], any edge the anchors leave
-    /// unset inherited from the owner frame's rect.
+    /// `SetPoint`, XML `<Anchors>`, relative to the owner frame unless naming a frame or sibling
+    /// region. An edge they leave unset comes from the region's own size, measured text or texel
+    /// extent, never the owner's rect; one still unset leaves the region unresolved (`0x767a20`).
+    /// Empty is a Lua region nobody anchored, which never draws: every other has an authored or
+    /// creation-time anchor ([`super::region::implicit_creation_anchor`]).
     pub(crate) anchors: Vec<Anchor>,
-    /// `Texture:SetDesaturated(flag)` — the shader desaturation state (`0x79c1e0`, verified in
-    /// wow-re's ledger). Rides the extract as [`QuadContent::Texture::desaturated`] and the
-    /// renderer greys the texel by it (decision 1327), so the binding answers "shader supported"
-    /// — see `region/paint.rs`'s `SetDesaturated`.
+    /// `SetDesaturated` (`0x79c1e0`): the renderer greys the texel, so the binding reports support.
     pub(crate) desaturated: bool,
-    /// `SetNonSpaceWrap` / `CanNonSpaceWrap` — FontString only (`0x79e9f0`/`0x79ead0`, wow-re's
-    /// widget-method batch). **State only here.** The real client's gx flag `0x40` feeds a
-    /// mid-word wrap carry and the fit-count terminator whose one consumer is the ellipsis
-    /// truncate at `0x771ec0`; our text layout has no ellipsis path, so honouring the value in
-    /// layout would mean inventing one. Stored and answered faithfully, unread by the renderer —
-    /// which is the honest position and is stated rather than left to be discovered.
-    ///
-    /// Default is ON (a no-arg `SetNonSpaceWrap()` also enables), so `None` reads as enabled.
+    /// `SetNonSpaceWrap`/`CanNonSpaceWrap` (`0x79e9f0`/`0x79ead0`), `None` on. Stored, not applied:
+    /// the reference's flag `0x40` drives a mid-word wrap and the ellipsis fit count (`0x771ec0`).
     pub(crate) non_space_wrap: Option<bool>,
-    /// FontString justification, as the client's own **dword** rather than a pair of resolved
-    /// enums — `CSimpleFontString+0x120`, bits 0–2 horizontal and 3–5 vertical, defaulting to the
-    /// ctor's `0x212` (CENTER|MIDDLE). See [`crate::justify::Justify`]: an axis can be *cleared*,
-    /// which no resolved enum can hold, and the Lua getter and the draw path then answer that
-    /// state differently (`"UNKNOWN"` vs centred) — both faithfully.
+    /// The client's dword at `CSimpleFontString+0x120`: bits 0-2 horizontal, 3-5 vertical, `0x212`
+    /// from the constructor. A cleared axis answers `"UNKNOWN"` to the getter and draws centred.
     pub(crate) justify: crate::justify::Justify,
-    /// The `<TexCoords>`/`SetTexCoord` UV mapping ([`TexCoords`]: the 4-edge crop, or the 8-arg
-    /// affine quad). `None` = the full texture. Slices the quadrant/atlas art (decision 0084).
+    /// The `<TexCoords>`/`SetTexCoord` mapping; `None` is the full texture.
     pub(crate) tex_coords: Option<TexCoords>,
-    /// `Texture:SetTexCoordModifiesRect(flag)` / `GetTexCoordModifiesRect()` — the reference's
-    /// `[texture+0x124]`, whose sole writer is `SetTexCoordModifiesRect 0x79c080`
-    /// (`0x79c113 mov [edi+0x124],eax`) and which is BSS-zero otherwise (wow-re
-    /// `scratch/taxiroute-widget-type.md`, `ui.md:5594`).
-    ///
-    /// **State only, and the geometry half is NOT wired.** In the reference the flag gates a
-    /// rect-recompute leg (`ui.md:4619`, `0x770462`): with it set, a `SetTexCoord` re-derives the
-    /// region's own rect from the UV quad rather than leaving the rect alone and merely resampling
-    /// inside it. Honouring that here means `region::layout`'s resolve reading this flag and
-    /// deriving the region's rect from [`Self::tex_coords`] instead of from its anchors and size —
-    /// a resolve-order change, not a paint one, and nothing in either addon corpus or the stock UI
-    /// calls the SETTER, so there is no measured case to build it against. Stored and answered
-    /// truthfully, unread by layout; stated here rather than left to be discovered.
+    /// `SetTexCoordModifiesRect`, the reference's `+0x124` (written only at `0x79c113`, in
+    /// `0x79c080`). Stored, not applied: there a set flag makes `SetTexCoord` re-derive the rect
+    /// from the UV quad (`0x770462`); no stock or corpus code sets it.
     pub(crate) tex_coord_modifies_rect: bool,
-    /// On-screen rotation about the region center, radians, counterclockwise-positive.
-    /// **Unwritable: the `Texture:SetRotation` that was its only setter is gone** (1.12 registers
-    /// the name on PlayerModel alone) — see [`QuadContent::Texture::rotation`] for why it is still
-    /// here.
+    /// Rotation about the centre, radians counterclockwise; always 0: 1.12 has no Texture setter.
     pub(crate) rotation: f32,
-    /// The named font object this FontString last resolved (`inherits=`/`SetFontObject`) — our
-    /// `FONTINSTANCE+0x028 parentFontObject`, and a **live** link: mutating that object
-    /// (`GameFontNormal:SetFont(…)`) re-paints this region through
-    /// [`script::font::propagate`](super::font::propagate). `GetFontObject` returns its handle.
-    /// The object's paint is eagerly copied into the fields below so every reader stays a plain
-    /// field read.
+    /// The font object this FontString inherits (`FONTINSTANCE+0x028`, a FontString's `+0xd0`), a
+    /// live link: its paint is copied below, and
+    /// [`script::font::propagate`](super::font::propagate) repaints on a change.
     pub(crate) font_object: Option<String>,
-    /// Which of the font properties below this region set **for itself** since its last
-    /// `SetFontObject` — our `FONTINSTANCE+0x038 explicitlySetMask`. See [`FontExplicit`].
+    /// What this region set for itself, which its font object no longer overwrites.
     pub(crate) font_explicit: FontExplicit,
-    /// Resolved font face path (`SetFont`/`SetFontObject`). `None` = the renderer's default face.
+    /// Resolved font face path (`SetFont`/`SetFontObject`); `None` is the renderer's default.
     pub(crate) font_path: Option<String>,
-    /// Resolved font height in logical px (`SetFont`/`SetFontObject`/`<FontHeight>`). `None` = default.
+    /// Resolved font height in logical px; `None` is the renderer's default.
     pub(crate) font_height: Option<f32>,
-    /// A `SetTextHeight` scale override — the client's two text-size regimes (§5-verified,
-    /// wow-re `fontstring-overflow.md`): a FontString defaults to **one-to-one** (bit `0x200`,
-    /// drawn at the raster px, subject to the 32-px raster cap); `SetTextHeight 0x771600` is the
-    /// ONLY clearer — the literal size then flows through UNCAPPED, magnified from the raster.
-    /// `Some` = that regime; the renderer draws at this height and skips the one-to-one cap.
+    /// A `SetTextHeight` override: a FontString is one-to-one by default (bit `0x200`, capped at
+    /// 32 px), and only `SetTextHeight 0x771600` clears that, drawing the size uncapped.
     pub(crate) text_height: Option<f32>,
-    /// Resolved glyph outline (`SetFont` flags / font object). Carried, not yet drawn (see [`Outline`]).
+    /// Resolved glyph outline (`SetFont` flags or the font object).
     pub(crate) outline: Outline,
-    /// Resolved drop shadow (font object `<Shadow>`), drawn by the renderer behind the glyphs.
+    /// Resolved drop shadow (font object `<Shadow>`), drawn behind the glyphs.
     pub(crate) font_shadow: Option<FontShadow>,
-    /// The host-measured wrapped text size for a FontString with no explicit height — the engine's
-    /// side of the measure round-trip ([`UiScript::fontstrings_needing_measure`] →
-    /// [`UiScript::set_measured_text`]): the real client's layout asks its font engine for string
-    /// metrics exactly like this (`fontstring.md`). `key` invalidates on text/font/wrap changes.
+    /// The host-measured size of a FontString with no explicit height.
     pub(crate) measured: Option<MeasuredText>,
 }
 
-/// The per-property "this region set it itself, so it does not inherit" record — the real client's
-/// `FONTINSTANCE+0x038 explicitlySetMask` (wow-re `system/ui/scratch/fontstring.md`).
-///
-/// It exists for exactly one job: when a **font object is mutated**
-/// (`GameFontNormal:SetTextColor(…)`), every region inheriting it re-reads the object, and a
-/// property the region had overridden must survive that re-read. A dropdown row that does
-/// `SetFontObject(GameFontNormalSmall)` and then `SetTextColor(1, 0, 0)` keeps its red.
-///
-/// A fresh `SetFontObject` **clears the whole mask** — re-pointing at an object is a deliberate
-/// "take this object's paint", and `Dewdrop-2.0` re-runs exactly that pair on every row refresh
-/// (`SetFontObject` at l.2160-2166, then `SetTextColor` at l.2180), which only stays correct if the
-/// re-point wins. (Whether the real client's mask outlives a re-point is the one part of this the
-/// bytes have not yet been asked; the choice above is the one that leaves current behaviour
-/// untouched, and it is the *propagation* half — new behaviour either way — that the mask governs.)
+/// The font properties a region set for itself, which changes to its font object no longer
+/// reach: the reference's inherit mask (`FONTINSTANCE+0x2c`, a FontString's `+0xd4`; justify
+/// per axis at `+0x124`), whose bit each local setter clears. Nothing restores one, a later
+/// `SetFontObject` included, so a row that calls `SetTextColor(1, 0, 0)` stays red.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub(crate) struct FontExplicit {
     /// `SetFont`'s path argument, or XML `font=`.
@@ -709,7 +435,7 @@ pub(crate) struct FontExplicit {
     pub(crate) outline: bool,
     /// `SetTextColor`/`SetVertexColor`, or a `<FontString><Color>`.
     pub(crate) color: bool,
-    /// Reserved for a region-level shadow setter; XML `<Shadow>` on the FontString itself.
+    /// `SetShadowColor`/`SetShadowOffset`, or XML `<Shadow>` on the FontString itself.
     pub(crate) shadow: bool,
     /// `SetJustifyH`, or XML `justifyH=`.
     pub(crate) justify_h: bool,
@@ -717,49 +443,23 @@ pub(crate) struct FontExplicit {
     pub(crate) justify_v: bool,
 }
 
-/// A cached host measurement of a FontString's laid-out text (see [`RegionData::measured`]).
+/// A cached host measurement of a FontString's laid-out text.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) struct MeasuredText {
-    /// The extent of the text **as laid out** — wrapped inside the region's declared width, if it
-    /// has one. The auto-size input, and what `GetWidth`/`GetHeight` echo.
+    /// The laid-out extent, wrapped in any declared width, which auto-size and `GetWidth` read.
     pub(crate) w: f32,
     pub(crate) h: f32,
-    /// The extent the text would take with **no wrap constraint** — what `GetStringWidth` reports,
-    /// and a different number from [`Self::w`] for exactly those regions that carry a declared width.
-    ///
-    /// The reference keeps only this one (`GetStringWidth 0x79e510` → `0x772890`, cached at
-    /// `+0xfc`): it measures the raw text with **no wrap constraint**, so "Lua sees the natural,
-    /// unwrapped, un-truncated width at the DRAWN size" (wow-re `fontstring-overflow.md`, "The
-    /// measurement echo", VERIFIED). benilla needs both, because its auto-size path reads the
-    /// laid-out extent off this same cache.
-    ///
-    /// Serving the laid-out width to `GetStringWidth` instead is a **feedback loop**, not a rounding
-    /// difference: any kit that sizes a box from `GetStringWidth` and then sets a width on the string
-    /// — which is what the reference's own `PanelTemplates_TabResize` does — reads its own output
-    /// back as its next input. The macro window's character tab changed width every single frame for
-    /// exactly this reason (decision 0997).
+    /// The unwrapped width `GetStringWidth` answers, the only one the reference keeps
+    /// (`0x79e510` → `0x772890`, cached at `+0xfc`); answering `w` would feed back through
+    /// `PanelTemplates_TabResize`, which sets the string's width from it.
     pub(crate) natural_w: f32,
-    /// Hash of (text, font path, font height bits, wrap-width bits) — mismatch ⇒ re-measure.
+    /// The [`RegionData::measure_key`] it was measured under; a mismatch re-measures.
     pub(crate) key: u64,
 }
 
 impl MeasuredText {
-    /// Did the part of this measurement the **layout** reads move? (decision 1385)
-    ///
-    /// Only `w`/`h` are layout inputs — they are the auto-size axes, and the only fields
-    /// `InputFingerprint` feeds (`script::layout`'s region walk hashes `m.w`/`m.h`, nothing else).
-    /// `key` is the measure CACHE's business and `natural_w` is `GetStringWidth`'s; neither can
-    /// move a rect.
-    ///
-    /// The distinction is load-bearing, not tidiness. A measure request is only ever *issued* when
-    /// the stored key mismatches, and `MeasuredText`'s derived `PartialEq` includes `key` — so
-    /// `d.measured != Some(new)` is **structurally always true** at both write sites, and touching
-    /// the epoch on it meant every answered measure opened tier 1. A FontString whose text changes
-    /// to something the same size does that on a cadence: a buff countdown ticking `"58s" → "57s"`,
-    /// a colour-code swap, any same-width digit. Tier 1 then went dirty and tier 2 hashed all
-    /// ~10k anchored regions to conclude nothing had moved — ~1 ms, `solves=0`, per tick, times
-    /// the number of unsynchronised timers on screen. The same shape 0740's own doc records the
-    /// bag-hover loop paying, and a sibling of the castbar's (1385).
+    /// Whether `w` or `h`, the layout's only inputs, moved: a fresh measure always differs in
+    /// `key`, so a whole-value compare would dirty the layout on every same-size text change.
     pub(crate) fn layout_moved(before: Option<Self>, after: Self) -> bool {
         before.is_none_or(|b| {
             b.w.to_bits() != after.w.to_bits() || b.h.to_bits() != after.h.to_bits()
@@ -768,162 +468,119 @@ impl MeasuredText {
 }
 
 impl RegionData {
-    /// The measure-cache key for the region's CURRENT text/font/wrap/outline — the one recipe both
-    /// sides of the measure round-trip share. [`super::UiScript::fontstrings_needing_measure`]
-    /// stamps it into each request (and skips regions whose stored [`MeasuredText::key`] still
-    /// matches); the Lua-visible metric reads (`GetStringWidth`/`GetWidth`, region.rs) treat a
-    /// stored measure whose key mismatches as ABSENT — a measure of text this region no longer
-    /// holds is not a metric (the whisper-header cursor bug: `SetText("Tell …: ")` then a
-    /// same-frame `GetWidth()` served the OLD header's width, and the edit box latched its text
-    /// insets on it). The layout solver's own read (layout.rs) deliberately does NOT key-check:
-    /// it keeps the last-known box until the fresh measure lands, so lines never collapse for the
-    /// round-trip frame. **With one carve-out, and it is the carve-out this cache needs**: EMPTY
-    /// text is never measured at all (both measure asks filter it out), so "until the fresh
-    /// measure lands" is a promise that can never be kept for a cell that goes from text to `""`
-    /// — the solver drops the stored measure there rather than hold a dead box forever (B309: the
-    /// item tooltip's blank SET spacers drew rows the plate counted as zero).
-    /// `scale` is the owner frame's `effective_scale`: it's in the key because the host measures
-    /// at the drawn raster size ([`MeasureRequest::scale`]), so a `SetScale` under a cached
-    /// measure must invalidate it exactly like a font-size change.
+    /// The measure-cache key of the text, font, wrap width, outline and owner scale. A Lua metric
+    /// read treats a measure under another key as absent; the layout keeps the old box until the
+    /// new one lands, except for empty text, which is never measured.
     pub(crate) fn measure_key(&self, scale: f32) -> u64 {
         use std::hash::{Hash, Hasher};
         let mut hasher = std::collections::hash_map::DefaultHasher::new();
-        // By reference: `String` hashes exactly as `str` does, and this runs for every
-        // FontString on every frame's staleness sweep — a clone here was ~1.5k heap allocs a
-        // frame at a city pin, all discarded at the key compare.
+        // By reference: `String` hashes as `str` does, and this runs for every FontString every
+        // frame, so a clone would allocate for nothing.
         self.text.as_deref().unwrap_or("").hash(&mut hasher);
         self.font_path.hash(&mut hasher);
         self.font_height.map(f32::to_bits).hash(&mut hasher);
         self.text_height.map(f32::to_bits).hash(&mut hasher);
         let wrap_width = self.size.map(|s| s.0).filter(|w| *w > 0.0);
         wrap_width.map(f32::to_bits).hash(&mut hasher);
-        // Outline is in the key because it changes measured WIDTH under the client's step law
-        // (an outlined font steps +1px more per glyph — GlyphStepBase 0x5ca2b0).
+        // The outline changes the measure: a THICK one steps each glyph 1 px further
+        // (`GlyphStepBase 0x5ca2b0`).
         (self.outline as u8).hash(&mut hasher);
         scale.to_bits().hash(&mut hasher);
         hasher.finish()
     }
 }
 
-/// The focused EditBox's advance-table request — returned by
-/// [`UiScript::editbox_advances_request`](super::UiScript::editbox_advances_request), answered
-/// via [`UiScript::set_editbox_advances`](super::UiScript::set_editbox_advances) with the
-/// per-byte cumulative laid-out widths of `text` (len+1 entries, `[0] = 0`, a continuation byte
-/// repeating its lead's value). The metrics seam that makes click→char-index, drag-select, and
-/// the caret scroll window engine-local (RF-0082's mouse/caret leaves).
+/// The focused EditBox's advance-table request, answered via
+/// [`UiScript::set_editbox_advances`](super::UiScript::set_editbox_advances) with the width at
+/// each byte of `text` (len+1 entries, `[0] = 0`, a continuation byte repeating its lead's), for
+/// the engine's click-to-caret and selection (the reference's click handler is `0x77b800`).
 #[derive(Clone, Debug, PartialEq)]
 pub struct EditBoxAdvanceRequest {
-    /// Opaque frame id of the box — pass back verbatim.
+    /// Opaque frame id; pass it back verbatim.
     pub id: u32,
     pub font: Option<String>,
     pub height: Option<f32>,
-    /// The resolved glyph outline — the per-glyph step bias (+1px, GlyphStepBase 0x5ca2b0)
-    /// changes every advance.
+    /// A THICK outline adds 1 px to every glyph step (`GlyphStepBase 0x5ca2b0`).
     pub outline: Outline,
-    /// The box frame's `effective_scale`. The host measures at the drawn raster size
-    /// (`height × scale × seam`) but divides the answer by the SEAM ALONE, so the advances come
-    /// back in screen UI units — the space the engine's ÷seam mouse feed and the box's resolved
-    /// (scale-multiplied) rect both live in. Contrast [`MeasureRequest::scale`], whose answer is
-    /// frame-local.
+    /// The box's `effective_scale`. The host measures at `height × scale × seam` but divides by
+    /// the seam alone, so advances come back in screen UI units, like the mouse feed and the
+    /// box's rect; a [`MeasureRequest`] answer is frame-local instead.
     pub scale: f32,
-    /// The DISPLAY string (mask-aware) the table indexes.
+    /// The displayed string (mask-aware) the table indexes.
     pub text: String,
-    /// `Some(width)` for a multiline box: also answer the wrapped-row starts + row pitch at this
-    /// wrap width (the text region's resolved width — the same width the draw wraps at), via
-    /// [`UiScript::set_editbox_advances`](super::UiScript::set_editbox_advances)'s `rows`/`cell_h`.
-    /// `None` = single-line (answer `rows = [0]`).
+    /// For a multiline box, the width the draw wraps at: the answer then also carries the row
+    /// starts and pitch (`rows`, `cell_h`); `None` is single-line, answered `rows = [0]`.
     pub wrap_width: Option<f32>,
-    /// Cache key — pass back verbatim.
+    /// Cache key; pass it back verbatim.
     pub key: u64,
 }
 
-// `EditAction`/`EditUnit` are the *editing law's* vocabulary, so they live beside the state that
-// law mutates ([`crate::widget::EditBoxState`]) rather than here — `script` depends on `widget`,
-// never the other way round, and the glue screens drive the law with no Lua VM in sight
-// (decision 0704). Re-exported here because this is the path the host has always used.
+// Re-exported from `widget`, which `script` depends on and never the reverse.
 pub use crate::widget::{EditAction, EditOutcome, EditUnit};
 
-/// The focused EditBox's per-frame text-UI geometry — returned by
-/// [`UiScript::focused_editbox_text_ui`](super::UiScript::focused_editbox_text_ui): everything
-/// the host needs to draw the box's window substring, selection highlight, and caret.
+/// The focused EditBox's per-frame text geometry: its text window, selection and caret.
 #[derive(Clone, Debug, PartialEq)]
 pub struct EditBoxTextUi {
-    /// The text region's draw target — match the extracted Text quad by it.
+    /// The text region's draw target, to find its extracted Text quad by.
     pub target: crate::order::ZTarget,
-    /// Draw `display[display_from..]` (the scroll window's start, a DISPLAY byte offset).
-    /// Always 0 for a multiline box (it wraps in place instead of windowing).
+    /// The scroll window's start, a display byte offset; always 0 for a multiline box.
     pub display_from: usize,
-    /// The box is multiline: the host draws the full wrapped block (no window, no unbounded
-    /// rect) and seats the caret/selection by `(row, x)` at the answered row pitch.
+    /// Multiline: the whole wrapped block draws, caret and selection seated by `(row, x)`.
     pub multi_line: bool,
     /// Caret x in px from the drawn window's text origin (multiline: from the row's origin).
     pub caret_x: f32,
-    /// Caret wrapped-row index (always 0 single-line) — the vertical half of the 2-D seat.
+    /// Always 0 single-line.
     pub caret_row: usize,
-    /// The answered row pitch in px (0 until the advance answer lands); the host may prefer its
-    /// own draw-side line cell — the two are the same law (the snapped font em).
+    /// The answered row pitch in px, 0 until the advances arrive.
     pub cell_h: f32,
-    /// The blink phase — draw the caret this frame (hosts may pin it on for captures).
+    /// The blink phase: draw the caret this frame.
     pub caret_on: bool,
-    /// The selection as per-row `(row, x0, x1)` px spans from each row's origin, when non-empty
-    /// (single-line: at most one span, row 0 — the old scalar span).
+    /// Per-row `(row, x0, x1)` px spans from each row's origin; single-line has at most one.
     pub selection: Vec<(usize, f32, f32)>,
-    /// The selection highlight tint (`SetHighlightColor`; ctor default opaque `0x606060` gray).
+    /// `SetHighlightColor`; the constructor's default is opaque `0x606060` grey.
     pub highlight_color: [f32; 4],
 }
 
-/// One FontString the layout needs host-measured this frame (no explicit height; text present).
-/// Returned by [`UiScript::fontstrings_needing_measure`](super::UiScript::fontstrings_needing_measure); answer via [`UiScript::set_measured_text`](super::UiScript::set_measured_text).
+/// One FontString the layout needs host-measured this frame (text, no explicit height), answered
+/// via [`UiScript::set_measured_text`](super::UiScript::set_measured_text).
 #[derive(Clone, Debug, PartialEq)]
 pub struct MeasureRequest {
-    /// Opaque region id — pass back verbatim.
+    /// Opaque region id; pass it back verbatim.
     pub id: u32,
     pub font: Option<String>,
     pub height: Option<f32>,
-    /// The `SetTextHeight` override (see [`RegionData::text_height`]): measured at this height,
-    /// uncapped, when present — the drawn size is the measured size (`0x772890`).
+    /// The `SetTextHeight` override, measured uncapped at the drawn size (`0x772890`).
     pub text_height: Option<f32>,
-    /// Wrap width when the region's width is pinned (explicit `<Size x>`), else single-line.
+    /// Set when the region's width is pinned (explicit `<Size x>`), else single-line.
     pub wrap_width: Option<f32>,
-    /// The resolved glyph outline — it biases the client's per-glyph step (+1px, GlyphStepBase
-    /// 0x5ca2b0), so the measured width depends on it.
+    /// A THICK outline adds 1 px to every glyph step (`GlyphStepBase 0x5ca2b0`).
     pub outline: Outline,
-    /// The owner frame's `effective_scale`. The host must measure at the DRAWN raster size —
-    /// `font_height × scale × its own screen seam` — and divide the px answer back by the full
-    /// product: glyph advances step to whole pixels (the step law), so a measure taken at the
-    /// unscaled size is not `scale ×` the drawn one, and an auto-sized FontString in a scaled
-    /// frame would mis-fit its own text (spurious wrap → spurious "..." ellipsis).
+    /// The owner's `effective_scale`. The host measures at `font_height × scale × seam` and
+    /// divides by that whole product: advances step to whole pixels, so a measure at the
+    /// unscaled size is not proportional to the drawn one.
     pub scale: f32,
     pub text: String,
-    /// Cache key — pass back verbatim.
+    /// Cache key; pass it back verbatim.
     pub key: u64,
 }
 
-/// One ScrollingMessageFrame ring line whose wrapped **row count** needs a host measurement (its
-/// cache key went stale — new line, width change, font change). The message-frame half of the
-/// measure round-trip: returned by
-/// [`UiScript::message_lines_needing_measure`](super::UiScript::message_lines_needing_measure),
-/// answered via [`UiScript::set_message_line_rows`](super::UiScript::set_message_line_rows) with
-/// `(frame, index, rows, key)` — same-frame, before extract, no re-resolve needed (rows shift only
-/// the emitted bands, never the anchor graph).
+/// One ScrollingMessageFrame line whose wrapped row count needs measuring, answered via
+/// [`UiScript::set_message_line_rows`](super::UiScript::set_message_line_rows) in the same frame,
+/// before extract: rows move only the drawn bands, never the anchors.
 #[derive(Clone, Debug, PartialEq)]
 pub struct LineMeasureRequest {
-    /// Opaque frame id — pass back verbatim.
+    /// Opaque frame id; pass it back verbatim.
     pub frame: u32,
-    /// The line's ring index at collect time — pass back verbatim (the ring cannot shift between
-    /// collect and answer within one host drive; the key still guards a stale store).
+    /// The line's ring index at collect time; pass it back verbatim.
     pub index: u32,
     pub font: Option<String>,
     pub height: Option<f32>,
-    /// The frame's resolved inner width — the wrap constraint. Already scale-multiplied (it is
-    /// the resolved rect's width), unlike `height`, which is the font's local size.
+    /// The frame's inner width: already scale-multiplied, unlike `height`, the font's own size.
     pub wrap_width: f32,
-    /// The resolved glyph outline (step-law width bias, as on [`MeasureRequest`]).
     pub outline: Outline,
-    /// The frame's `effective_scale` — the host wraps at the drawn raster size
-    /// (`height × scale × seam`), as on [`MeasureRequest::scale`].
+    /// As for [`MeasureRequest::scale`].
     pub scale: f32,
     pub text: String,
-    /// Cache key — pass back verbatim.
+    /// Cache key; pass it back verbatim.
     pub key: u64,
 }
diff --git a/crates/benilla-ui/src/script/ui_errors.rs b/crates/benilla-ui/src/script/ui_errors.rs
index d8ac6453..f7b8639a 100644
--- a/crates/benilla-ui/src/script/ui_errors.rs
+++ b/crates/benilla-ui/src/script/ui_errors.rs
@@ -1,25 +1,16 @@
-//! **The Lua-callable half of the client-local error-display family** — FrameXML-facing globals
-//! whose whole body, in the reference binary, is "push one catalog id at
-//! `CGGameUI::DisplayError`'s dispatcher". The engine-side half (a Rust system raising a key
-//! directly, e.g. the passive-on-bar refusal) pushes onto the same [`Model::ui_errors`] queue;
-//! the app drains it, resolves each key against the VM's own GlobalStrings and fires
-//! `UI_ERROR_MESSAGE` (`ui_action/feed.rs`) — which is byte-for-byte the reference route: catalog
-//! row → GlobalStrings text → FrameScript event `0xe0`, rendered by UIErrorsFrame.
+//! Lua globals whose whole body pushes one catalog id at `CGGameUI::DisplayError`'s dispatcher.
+//! Engine-side refusals share the [`Model::ui_errors`] queue, which the app resolves against
+//! GlobalStrings and fires as `UI_ERROR_MESSAGE` (event `0xe0`), the reference's route.
 //!
-//! First tenant: `NotWhileDeadError` (decision 1507's open item, closed by the wow-re §5
-//! cross-check of 2026-08-21, recorded in wow-re `system/ui`): registration pair `0x83e398`,
-//! C body `0x48d340` = `push 0x7e; call 0x496720; xor eax,eax; ret` — no argument read, no
-//! dead-check of its own, 0 return values, and its catalog row (`0xb4be70`, key
-//! `ERR_PLAYER_DEAD`) names sound `"NONE"`, so the toast is silent. FrameXML decides *when* to
-//! call it (ShowUIPanel's `whileDead` refusal, UIParent.lua l.663-666; ContainerFrame.lua l.147
-//! and l.190); the binding only displays.
+//! `NotWhileDeadError` (`0x48d340`, registered at `0x83e398`) is `push 0x7e; call 0x496720`: no
+//! argument, no dead check, no return, and a silent catalog row (`0xb4be70`). FrameXML decides
+//! when to call it (`UIParent.lua:663-666`, `ContainerFrame.lua:147` and `:190`).
 
 use mlua::Lua;
 
 use super::model::Model;
 
-/// The GlobalStrings key of catalog id `0x7e` — the row `NotWhileDeadError`'s pushed id resolves
-/// to ("You can't do that when you're dead.").
+/// Catalog id `0x7e`'s GlobalStrings key ("You can't do that when you're dead.").
 const NOT_WHILE_DEAD_KEY: &str = "ERR_PLAYER_DEAD";
 
 /// Register the error-display globals.
diff --git a/crates/benilla-ui/src/script/unit/bindings.rs b/crates/benilla-ui/src/script/unit/bindings.rs
index a8795fd7..8b6b51d8 100644
--- a/crates/benilla-ui/src/script/unit/bindings.rs
+++ b/crates/benilla-ui/src/script/unit/bindings.rs
@@ -1,19 +1,7 @@
-//! The `Unit*` global registrations (see the parent module's doc for the seam and the return
-//! shapes): every binding reads the per-token [`UnitState`](super::UnitState) snapshot store
-//! through the parent's `with_unit`/`pick_unit_token` helpers.
-//!
-//! **Every predicate here returns through one function** — [`super::unit_predicate`] when it reads
-//! a snapshot field, [`flag`](super::super::binding_abi::flag) when it computes its own bool.
-//! Neither ever hands mlua a Rust `bool`: all 29 of the reference's unit predicates push the
-//! constant double `1.0` (`lua_pushnumber 0x6f3810`) or `nil` (`lua_pushnil 0x6f37f0`), one value
-//! at every live `ret`, and **no binding in the 83-entry table at `0x850438` calls
-//! `lua_pushboolean 0x6f39f0` at all** (decisions 1830, 2043, 2048). A new predicate that open-codes
-//! `Value::Integer(1)`/`Value::Nil`, or returns a `bool`, is the drift those records exist to stop.
-//!
-//! **The scope of that claim is the unit table, not "the binding surface"** — 2043 said the wider
-//! thing and 2048 corrected it. `lua_pushboolean` exists at `0x6f39f0` with seven call sites, and
-//! one of them *is* a registered FrameScript binding: `IsPetAttackActive 0x4be0e0` answers a real
-//! Lua `true`/`false`, never nil (ours already does — `super::super::pet`).
+//! The `Unit*` global registrations, over the per-token [`UnitState`](super::UnitState) snapshots.
+//! Every predicate answers the number 1 or nil through [`super::unit_predicate`] or
+//! [`flag`](super::super::binding_abi::flag): no binding in the reference's unit table (`0x850438`)
+//! calls `lua_pushboolean` (`0x6f39f0`), though `IsPetAttackActive` (`0x4be0e0`) outside it does.
 
 use mlua::{Lua, Value};
 
@@ -24,18 +12,9 @@ use super::{
     unit_predicate, unknownobject, with_unit, PlayerRecord, SelectionRequest,
 };
 
-/// **The `"player"` fast path, shared by the four verbs that take it** (decision 2263).
-///
-/// `Some(x)` = this token is `"player"` and `x` is the record's answer; `None` = it is any other
-/// token and the caller falls through to the unit resolver. That is the reference's own shape —
-/// a full-string, case-insensitive compare of the token against `0x847894` (`b"player\0"`) whose
-/// **match is the fall-through** — and it is one function rather than four copies for the reason
-/// [`super::super::names::gated_rank`](crate)'s sibling comment gives about rank: four readers of
-/// one record, each testing the token itself, is how they drift apart. `UnitName`, `UnitRace`,
-/// `UnitClass` and `UnitSex` are the whole set; `UnitLevel` is **not** one of them.
-///
-/// The compare is a full string, not a prefix: `"playerfoo"` is a recognised-but-unresolvable
-/// token ([`super::token_recognised`]) and goes to the resolver, not here.
+/// The `"player"` fast path of `UnitName`, `UnitRace`, `UnitClass` and `UnitSex`, never
+/// `UnitLevel`: the record's answer when the token equals `"player"` (`0x847894`) whole and
+/// case-insensitively; any other token, `"playerfoo"` included, goes to the resolver.
 fn player_record_arm<T>(
     lua: &Lua,
     token: &Option<String>,
@@ -51,18 +30,12 @@ fn player_record_arm<T>(
     Some(f(&model.player_record))
 }
 
-/// The two class ids `GetComboPoints 0x51a190` accepts — the literals `4` and `0xb` it compares
-/// the class byte `[[player+0x110]+0x79]` against. That byte is `UNIT_FIELD_BYTES_0` byte 1, the
-/// same value [`PlayerReqState::class_id`](super::super::PlayerReqState) carries; `UnitClass`'s own
-/// binding (`0x518350`) reads it through the identical `[obj+0x110]+0x79` chain, which is what
-/// identifies it. The *names* are the conventional vanilla ids — the client's class table is
-/// heap-built, so nothing in the file maps 4→Rogue by itself (decision 0875).
+/// The class ids `GetComboPoints` (`0x51a190`) accepts: it compares the class, `UNIT_FIELD_BYTES_0`
+/// byte 1, with 4 and 0xb.
 const CLASS_ROGUE: u32 = 4;
 const CLASS_DRUID: u32 = 11;
 
-/// Register the `Unit*` globals reading the per-token snapshot store (the same style/place the
-/// object model and stdlib register their globals — bare globals on `_G`, matching the live API
-/// surface).
+/// Register the `Unit*` globals.
 pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -73,20 +46,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `UnitIsVisible(unit)` — `0x516030`, and it is **object presence, nothing else**:
-    // `ClntObjMgrObjectPtr(resolve(token), TYPEMASK_UNIT) != NULL`. 57 bytes, one branch, no field
-    // read and no comparison beyond `test eax,eax`.
-    //
-    // **Not a synonym for `UnitExists`, and neither implies the other.** An out-of-range party
-    // member has a roster entry and no object: `UnitExists` = 1 through its GUID fallback,
-    // `UnitIsVisible` = nil. That pair is the branch pfUI takes seven times — most visibly
-    // `if not UnitIsVisible(unitstr) or not UnitIsConnected(unitstr)`, which chooses between a 3D
-    // portrait and a flat one.
-    //
-    // **The return is the NUMBER 1, never a boolean** — `0x6f3810` writes tag 3 with the operands
-    // of `1.0` on the true leg, `lua_pushnil` on the false one. `UnitExists` above answers a Rust
-    // `bool` and so hands Lua `true`/`false`; that is its own pre-existing question, and matching
-    // it here would have been the wrong kind of consistency.
+    // `UnitIsVisible(unit)` (`0x516030`): whether the client holds the unit's object, nothing else.
+    // Not `UnitExists`: an out-of-range party member exists through its roster entry, unseen.
     g.set(
         "UnitIsVisible",
         lua.create_function(|lua, token: Option<String>| {
@@ -94,26 +55,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // `UnitIsTapped(unit)` / `UnitIsTappedByPlayer(unit)` — `0x519c90` / `0x519d00`, a masked-byte
-    // pair (108 bytes each; only the mask and the `Usage:` string differ). Each is
-    // `object present && (UNIT_DYNAMIC_FLAGS & mask)` and nothing else: no ownership, no GUID
-    // compare, no party/raid or health conjunct anywhere in either body.
-    //
-    // **Shape A, unlike `UnitIsVisible` directly above** — these two carry an `lua_isstring` gate
-    // and a `Usage:` `luaL_error`, where their neighbour has none. Two adjacent verbs in one
-    // family with opposite argument shapes is exactly why 1717's taxonomy is settled per binding;
-    // inheriting the sibling's shape here would have been wrong in the quiet direction.
-    //
-    // The reference raises TWO different messages — `Usage:` for a non-string/non-number, and the
-    // resolver's `"Unknown unit name: %s"` for a bad token (and for any NUMBER, since the
-    // `lua_isstring` gate admits tag 3 and hands the resolver `"5"`). `check_unit_token` inside
-    // `with_unit` is the second of those; the first is the `?` on the argument type below.
-    // The gate is the BINDING's, not `with_unit`'s: `check_unit_token` lets a nil through by
-    // design, because that is right for `UnitExists`, `UnitIsVisible` and eleven others. **"and
-    // most of this family" is what this comment used to say, and it was the wrong way round** —
-    // wow-re has since censused all 83 entries of the table at `0x850438` and 53 of them gate and
-    // raise, with only 13 unit-token bindings quiet (decision 1834). These two were never the
-    // exception; they were an early instance of the rule.
+    // `UnitIsTapped`/`UnitIsTappedByPlayer` (`0x519c90`/`0x519d00`): the object is present and its
+    // `UNIT_DYNAMIC_FLAGS` has the mask bit, nothing more. Unlike `UnitIsVisible` they gate with
+    // `lua_isstring`: another type raises `Usage:`, and a number raises `Unknown unit name`.
     for (name, usage, by_player) in [
         ("UnitIsTapped", r#"Usage: UnitIsTapped("unit")"#, false),
         (
@@ -125,10 +69,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         g.set(
             name,
             lua.create_function(move |lua, token: Value| {
-                // Shape A: a string OR a number passes (`lua_isstring` admits tag 3, and the
-                // client hands the resolver `"5"` — which then raises `Unknown unit name: 5`,
-                // the family's SECOND message). Everything else — nil, absent, boolean, table,
-                // function — is the `Usage:` raise.
                 let token = Some(crate::script::binding_abi::string_arg(lua, token, usage)?);
                 let hit = with_unit(lua, &token, false, |u| {
                     if by_player {
@@ -137,35 +77,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                         u.tapped
                     }
                 })?;
-                // One value, and it is the NUMBER 1 or nil — never a boolean, the same shape the
-                // rest of this family answers in.
                 Ok(flag(hit))
             })?,
         )?;
     }
 
-    // `UnitIsPartyLeader(unit)` — `0x516210`. **Two legs, ORed, covering disjoint failures:**
-    //
-    //     o = ObjPtr(resolve(token), TYPEMASK_PLAYER)          -- 0x10, not this family's 8
-    //     (o != NULL && (o.PLAYER_FLAGS & 0x1)) || resolve(token) == g_groupLeaderGuid
-    //
-    // The descriptor leg answers for any held player — including a stranger who leads their OWN
-    // party, which a comparison against our group's leader can never express. The GUID leg answers
-    // for a group member whose object the client does not hold (an out-of-range `party3`, any
-    // `raidN`), where there is no descriptor to read. Neither is sufficient alone, which is why
-    // this is not derivable from `IsPartyLeader()` + `GetPartyLeaderIndex()` however it is
-    // arranged (wow-re `ui/scratch/party-leader-and-nameplate-verbs.md`, G1 REFUTED).
-    //
-    // **No zero guard, and that is deliberate.** `IsPartyLeader 0x4e9130` short-circuits on a
-    // `0:0` cached leader; this one does not. An unresolvable-but-non-raising token resolves to
-    // `0:0`, which equals the zeroed leader while ungrouped — so `UnitIsPartyLeader(nil)` answers
-    // **1 solo**. It reads like a bug and it is the behaviour; answering nil there would be the
-    // divergence.
-    //
-    // Shape C with a shape-A tail: no `lua_isstring` gate and no `Usage:` of its own, but a bad
-    // token — and any Lua NUMBER, which the resolver stringifies first — raises
-    // `"Unknown unit name: %s"` from `check_unit_token`. One value on both legs, the number 1 or
-    // nil, never a boolean.
+    // `UnitIsPartyLeader(unit)` (`0x516210`): a held player's `PLAYER_FLAGS` bit 0x1, for a
+    // stranger leading their own party, or a GUID equal to the group leader's, for a member not
+    // held. No zero guard (unlike `IsPartyLeader`, `0x4e9130`): GUID 0 matches the zeroed leader,
+    // so `UnitIsPartyLeader(nil)` answers 1 while ungrouped. No `Usage:` gate; a bad token or a
+    // number raises `Unknown unit name`.
     g.set(
         "UnitIsPartyLeader",
         lua.create_function(|lua, token: Option<String>| {
@@ -175,8 +96,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 .as_ref()
                 .and_then(|t| model.unit(t))
                 .is_some_and(|u| u.group_leader);
-            // The GUID leg. A token with no snapshot resolves to GUID 0 — the reference's `0:0` —
-            // and 0 == the zeroed leader is exactly the solo case above.
+            // A token with no snapshot is GUID 0, the reference's `0:0`.
             let guid = token
                 .as_ref()
                 .and_then(|t| model.unit(t))
@@ -193,50 +113,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitName("unit")"#,
             )?);
-            // TWO values on every live path (`eax = 2` at `0x5170ae` and `0x517289`): the name and
-            // the **realm**. Slot 2 is nil for a same-realm player, and *structurally* nil for a
-            // pet, creature, game object or item — `0x609210` writes the out-parameter only on its
-            // PLAYER branch. benilla is single-realm, so the second is always nil here; the day a
-            // cross-realm name arrives it is `UnitState`'s to carry, and `UnitPopup.lua:106`'s
-            // `name.."-"..server` join is what will read it. Decision 1840.
-            //
-            // Not to be confused with `showServerName`: that is the parameter of FrameXML's own
-            // `GetUnitName(unit, showServerName)` wrapper, which calls this binding with ONE
-            // argument. The engine's real second argument is a strict `LUA_TBOOLEAN` and is not
-            // modelled — no consumer passes it.
-            //
-            // Value 1 — and the ONLY two nils a recognised token can produce (`0x517020`, wow-re
-            // `ui/scratch/binding-shape-arity-law.md` §2.1): the `"player"` fast path reads the
-            // local name buffer and pushes nil when it is empty (`0x51708c` → `0x5abdc0`; the
-            // `0x517083` this used to cite is the token's string *compare*, `call 0x64a4c0` —
-            // corrected 2261), and a token that resolves to GUID 0 pushes nil (`0x5170c0`).
-            // The empty-buffer nil is not an explicit push either: `0x517095` is
-            // `lua_pushstring`, which falls through on NULL at `0x6f3895` into `lua_pushnil`. EVERY other path ends in a
-            // string — the cached name, or `FrameScript_GetText("UNKNOWNOBJECT")`: `0x517220` for
-            // a GUID with no object and no cache row, `0x609324` inside `CGUnit_C::GetUnitName`
-            // for a unit whose name cache has not answered or is stale (a pet's is
-            // `petnamecache.wdb`, keyed by `UNIT_FIELD_PETNUMBER`, `pet-action-bar-api.md`
-            // §11c.6). A freshly called pet is that case by construction: `UNIT_PET` fires off the
-            // descriptor and the name lands a `CMSG_PET_NAME_QUERY` round-trip later, and stock
-            // `PetStable.lua:129` concatenates the answer in between.
-            //
-            // "Resolved to a GUID" is a SEATED SNAPSHOT — not `exists`. The reference's
-            // `UnitExists` is a conjunction with `IsSelectable` (the `UnitState::exists` doc's
-            // named gap), so a not-selectable unit reads its name there with `UnitExists` nil; the
-            // name resolver's own nil is GUID 0 and nothing else, and a feed that seats a token
-            // has resolved it. Decision 2002.
-            //
-            // **The `"player"` arm is the BUFFER, not the snapshot** (decision 2261). `0x51708c`
-            // reads `0x5abdc0` — the local name buffer at `0xc27d88` — and returns; it never
-            // reaches the resolver, so no object, no descriptor and no name-query answer is
-            // involved on this path at all. Modelling it off the snapshot (as this did until
-            // 2261) put the one name the client always knows behind the one cache that can miss:
-            // decision 2260's realm-cache load dropped our own guid, the feed pushed a nameless
-            // player over the roster seat, and `UnitName("player")` read nil in the world.
-            //
-            // The buffer's emptiness is still the reference's own nil — it just means something
-            // a snapshot cannot say, and something a client that is in the world never is:
-            // "no Enter World has been committed in this process".
+            // Two values (`0x5170ae`, `0x517289`): the name, and the realm, nil for a same-realm
+            // player or a non-player (`0x609210`), so always nil in single-realm benilla. A second
+            // argument (stock `UnitPopup.lua:106` passes `true`) is not read. The name is nil only
+            // for an empty `"player"` buffer (`0x51708c`, `0x6f3895`) or GUID 0 (`0x5170c0`);
+            // otherwise a string, `UNKNOWNOBJECT` until the name cache answers (`0x517220`,
+            // `0x609324`), as for a new pet. A seated snapshot answers even where `exists` is
+            // false; the `"player"` arm reads the local name buffer (`0xc27d88`), never the unit.
             if let Some(seeded) = player_record_arm(lua, &token, |r| r.name.clone()) {
                 let name = if seeded.is_empty() {
                     Value::Nil
@@ -279,13 +162,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitLevel (`0x517fc0`, §5-VERIFIED 2026-07-17): the raw UNIT_FIELD_LEVEL — a raw ≤ 0
-    // VERBATIM (never −1) — or **−1** iff world-boss rank 3 (unconditional) / hostile
-    // (reaction ≤ 1 internal) AND ≥ 10 levels above the player (inclusive). The FrameXML
-    // target frame branches its skull on `<= 0` (`TargetFrame_CheckLevel`), so a level-0
-    // (unstreamed) unit skulls through the verbatim 0, exactly as the reference does. Not
-    // carried: the dormant attackable-decay override (`max(1, raw − round(min(b,100)·0.05))`,
-    // `b` INFERRED and 0 in normal play — it can never drive the value ≤ 0 anyway).
+    // UnitLevel (`0x517fc0`): the raw level (a raw 0 stays 0), or -1 for a world boss or a hostile
+    // unit 10 or more levels above the player. The reference's attackable-decay override
+    // (`max(1, raw - round(min(b, 100) * 0.05))`, `b` an untraced byte not seen set) is not built.
     g.set(
         "UnitLevel",
         lua.create_function(|lua, token: Value| {
@@ -309,12 +188,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitIsCorpse (`0x5161c0`, §5-VERIFIED 2026-07-17) → 1/nil: a pure OBJECT-TYPE check —
-    // the token resolves to a live TYPEID_CORPSE world object (a released player's remains).
-    // NO health test: a dead mob or dead player is NOT a corpse (the ref target frame shows a
-    // dead mob's level number, not the skull). Reads [`UnitState::corpse_object`], which no
-    // feed sets yet — corpse objects aren't selectable in benilla — so this returns nil today,
-    // faithfully.
+    // UnitIsCorpse (`0x5161c0`): the token names a corpse object, a released player's remains; a
+    // dead unit is not one. No feed sets `corpse_object`, so this answers nil.
     g.set(
         "UnitIsCorpse",
         lua.create_function(|lua, token: Option<String>| {
@@ -322,16 +197,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCanAttack (`0x516c50`, §5-VERIFIED 2026-07-17) → 1/nil: pure delegation to the
-    // `CanAttack 0x606980` predicate (decision 0172), read from the non-player token's app-fed
-    // snapshot ([`UnitState::can_attack`]). Directional in the live API; our snapshot carries
-    // the player→unit direction, the only order the shipped FrameXML calls
-    // (`UnitCanAttack("player", "target")`).
+    // UnitCanAttack (`0x516c50`) delegates to `CanAttack` (`0x606980`). The snapshot holds only
+    // whether the player can attack the unit, fed for `target`, `targettarget` and `npc`, and that
+    // answers both argument orders; the reverse direction stock FrameXML also asks
+    // (`TargetFrame.lua:147`) is not built.
     g.set(
         "UnitCanAttack",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -347,10 +220,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetQuestGreenRange (`0x4e17d0`, §5-VERIFIED 2026-07-17) — the green→grey boundary the
-    // FrameXML `GetDifficultyColor` buckets by (ref QuestLogFrame.lua l.593):
-    // `GRAYBAND[min(playerLevel/5, 19)]` off the binary's `0x8076c0` table, byte-identical to
-    // the `0x81dda8`/`0x80ae98` twins [`grey_band`] transcribes. No args; 0 with no player.
+    // GetQuestGreenRange (`0x4e17d0`): the green-to-grey boundary `QuestLogFrame.lua:593` buckets
+    // by, from the table at `0x8076c0`. The reference answers 0 with no player object (`0x4e17f8`);
+    // here a level of 0 reads the table's first entry, 4.
     g.set(
         "GetQuestGreenRange",
         lua.create_function(|lua, ()| {
@@ -371,8 +243,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The other two of the client's death trio (decision 0308 §1): a released ghost has health 1,
-    // so IsDead is false for it and the popup flow branches on all three.
+    // A released ghost has health 1, so `UnitIsDead` is false for it.
     g.set(
         "UnitIsGhost",
         lua.create_function(|lua, token: Value| {
@@ -396,26 +267,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitReaction(unit, other) → the reaction scale, or nil. The live API is directional (unit's
-    // reaction toward `other`); our feed only resolves it for the "target" token toward the player,
-    // which is the sole caller (`TargetFrame_CheckFaction`), so the `other` arg is accepted and
-    // unused.
-    //
-    // **NOT a 1/nil predicate, and its nil does not mean "reaction 0"** (decision 2048, correcting
-    // 2043's aside). `0x5167e0` pushes `0x6061e0(u1, u2)` **plus one** (`0x51683e inc eax`,
-    // `0x516842 fild`) — a self-compare answers **5** — so the value is 1-based and **0 is
-    // unreachable**. Its nil leg (`0x51685f`) means only that a token failed to resolve to a live
-    // UNIT.
-    //
-    // Ours maps our own `reaction == 0` to nil because that is our sentinel for "not yet fed", and
-    // the observable is the same nil an unresolved token gives. The gap is the feed's, not the
-    // shape's: a resolved unit whose reaction has not streamed answers nil here where the reference
-    // answers a number. The target frame paints its name plate blue on that nil.
+    // UnitReaction(unit, other) (`0x5167e0`): `0x6061e0(unit, other)` plus one (`0x51683e`), so
+    // 1-based, 5 for a unit toward itself, never 0; nil (`0x51685f`) only when a token names no
+    // unit. Our reaction 0 means "not fed" and also answers nil, where the reference answers a
+    // number. The snapshot holds the reaction toward the player, so `other` is checked, not read.
     g.set(
         "UnitReaction",
         lua.create_function(|lua, (token, _other): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let token = Some(crate::script::binding_abi::string_arg(
                 lua,
                 token,
@@ -435,19 +294,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitIsEnemy / UnitIsFriend — the reaction-thresholded pair (the ref target-select sound
-    // branch, TargetFrame_OnShow). v1 derives both from the same snapshot as `UnitReaction`:
-    // enemy = reaction ≤ 2 (hated/hostile), friend = reaction ≥ 5 (friendly+); the live API's
-    // extra PvP inputs (duels, flagged players, sanctuaries) are deferred with the rest of the
-    // PvP wire. The pair is directional in the live API but our snapshot only carries the
-    // target↔player reaction, so the binding reads whichever arg isn't "player" (the ref calls
-    // both orders: UnitIsEnemy("target","player"), UnitIsFriend("player","target")). Unknown
-    // reaction (0) → nil for both, the API's "can't tell". `1`/nil returns, era-style.
+    // UnitIsEnemy/UnitIsFriend (`0x516890`/`0x516930`) threshold the reaction `UnitReaction`
+    // reads: enemy at 1 or 2, friend at 5 and up, and an unfed 0 is neither. The snapshot holds the
+    // reaction toward the player, so the non-player argument names the unit.
     g.set(
         "UnitIsEnemy",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -466,8 +319,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
     g.set(
         "UnitIsFriend",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -484,22 +336,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitIsPlayer(unit) → 1 if the unit is a player character, else nil. Reads the snapshot's
-    // guid-family flag (the same one the unit tooltip's "(Player)" line keys on). The target frame's
-    // faction tint branches on it (`TargetFrame_CheckFaction`): a player-controlled unit takes the
-    // red/blue player legs, an NPC the reaction swatch. (The live gate is `UnitPlayerControlled`,
-    // which also covers pets/charmed creatures; we resolve only the player half of it — the extra
-    // reach needs a player-controlled flag we don't carry, and a player's own alt is the case here.)
-    // UnitIsCivilian(unit) → 1 if killing this unit would be a DISHONORABLE kill, else nil. This is
-    // `0x612550` itself handed to Lua — the same four-term predicate (`pvp` bit AND creature-query
-    // civilian flag AND hostile AND the kill would be grey) that the unit tooltip's green CIVILIAN
-    // line and `UnitPVPName`'s civilian arm already run through `is_civilian_kill`. That function's
-    // doc called itself "ONE home, two callers"; the stock target frame is the third, and it is the
-    // one that names the predicate — `TargetFrame_CheckDishonorableKill` (TargetFrame.lua:230) is
-    // its only FrameXML caller and the comment inside it reads "Is a dishonorable kill".
-    //
-    // Sharing the function is the point: a second copy would let the tooltip, the name and the
-    // target plate disagree about the same mob.
+    // UnitIsCivilian(unit): killing the unit would be dishonorable, the predicate `0x612550`. It
+    // shares `is_civilian_kill` with the tooltip's civilian line and `UnitPVPName`, so all agree.
     g.set(
         "UnitIsCivilian",
         lua.create_function(|lua, unit: Value| {
@@ -516,11 +354,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             ))
         })?,
     )?;
-    // UnitPlayerControlled(unit) → 1 if a PLAYER is driving this unit, else nil. `UNIT_FIELD_FLAGS`
-    // bit 3 (`UNIT_FLAG_PVP_ATTACKABLE 0x8`), which is wider than `UnitIsPlayer` below: a player's
-    // pet and a charmed creature answer 1 here and nil there. Stock `UnitFrame_OnEnter`
-    // (UnitFrame.lua:58) is the caller that made this a blocker rather than a nicety — it gates the
-    // player-options newbie tip on it, so a missing binding raised on the first unit-frame hover.
+    // UnitPlayerControlled(unit) (`0x516410`): `UNIT_FIELD_FLAGS` bit 0x8, vmangos
+    // `UNIT_FLAG_PLAYER_CONTROLLED`, so a player's pet or a charmed creature answers 1 where
+    // `UnitIsPlayer` answers nil. An unrecognised token answers nil here; the reference raises.
     g.set(
         "UnitPlayerControlled",
         lua.create_function(|lua, unit: Option<String>| {
@@ -537,44 +373,23 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             unit_predicate(lua, &token, |u| u.is_player)
         })?,
     )?;
-    // UnitIsPlusMob(unit) → 1 if this unit is a "plus" mob, else nil (`0x516d40`, extent
-    // `[0x516d40,0x516d8f)`). One bit of the SAME `UNIT_FIELD_FLAGS` word `UnitPlayerControlled`
-    // reads: `shr ecx,6; test cl,1` — bit 6, `UNIT_FLAG_PLUS_MOB 0x40`.
-    //
-    // **It is not a rank read**, which is the trap the name sets. `UnitClassification` is its
-    // table neighbour and answers off the gated creature rank (decision 0782), so the obvious
-    // implementation is `rank > 0` — but `0x516d40` never calls the rank getter `0x605620` (whose
-    // six callers are enumerated) and never touches the creature cache. The two agree in practice
-    // because the SERVER derives the bit from the rank — vmangos `Creature::UpdateEntry` sets it
-    // on `!IsPet() && rank > 0` (`Creature.cpp:634`, INFERRED from source) — so **rare** answers 1
-    // here alongside elite, rare-elite and world boss, while a player, a pet and a normal mob
-    // answer nil. Where they part is the unstreamed unit: a creature whose cache record has not
-    // arrived still carries its own flags, so this answers truthfully where a rank read would say
-    // "normal". No client code writes the bit (zero bitwise RMWs at `+0xa0` image-wide), so it is
-    // the server's word verbatim.
-    //
-    // No stock FrameXML file calls it, which is why nothing shipped ever raised on its absence;
-    // addons do (`FuBar_DakSmak` colours its tooltip with it), and calling the nil global is what
-    // B385 reported. Last of the three verbs decision 1834 left loudly absent.
-    // Decision 2209 (wow-re `9f84e7e4`,
-    // `system/ui/scratch/unit-verbs-controlled-charmed-creaturetype.md` §4.2).
+    // UnitIsPlusMob(unit) (`0x516d40`): `UNIT_FIELD_FLAGS` bit 0x40, never the creature rank
+    // (`0x605620`). The server sets it for a non-pet above normal rank (`Creature.cpp:634`), so a
+    // rare answers 1, and an uncached creature still answers from its flags.
     g.set(
         "UnitIsPlusMob",
         lua.create_function(|lua, token: Option<String>| {
-            // One of 1834's quiet thirteen: no `lua_isstring` gate and no `Usage:` arm, so a nil
-            // or absent token is a quiet nil. An UNRECOGNISED one still raises — the body reaches
-            // the shared resolver through `0x515940`, and that is `unit_predicate`'s own gate.
+            // No `lua_isstring` gate, so nil answers nil; an unrecognised token still raises in
+            // the resolver (`0x515940`).
             unit_predicate(lua, &token, |u| u.flags & 0x40 != 0)
         })?,
     )?;
 
-    // The identity predicates (decision 0434 §5 — the unit popup's menu pick + gating). Same-token
-    // is trivially the same unit; otherwise both snapshots must carry a real (nonzero) guid.
+    // UnitIsUnit(a, b): both units exist and are the same token or share a nonzero GUID.
     g.set(
         "UnitIsUnit",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -585,7 +400,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 b,
                 r#"Usage: UnitIsUnit("unit", "otherUnit")"#,
             )?);
-            // BOTH arguments go through the resolver, so either being unrecognised raises.
+            // Both go through the resolver, so either one unrecognised raises.
             check_unit_token(&a)?;
             check_unit_token(&b)?;
             let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -602,17 +417,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitAffectingCombat(unit) → the number 1 in combat, else nil (`0x517e10`).
-    //
-    // The unusual half is the miss shape: **false and "no such unit" are the SAME arm**
-    // (`0x517e48 je 0x517e73` joins `0x517e5c je 0x517e73`), so an unresolvable token is
-    // indistinguishable from a peaceful one. Reproduced deliberately — an addon cannot use this
-    // binding to probe whether a unit exists, and ours must not let it either.
-    //
-    // A **bad or missing argument raises**, unlike its `UnitInRaid` neighbour: the guard here is
-    // `0x6f3510` (number-or-string, and NULL for an absent argument) with the usage literal at
-    // `0x851070` behind `0x6f4940`, which does not return. A *number* is accepted and stringified
-    // — `UnitAffectingCombat(5)` resolves the token `"5"`, finds nothing, and answers nil.
+    // UnitAffectingCombat(unit) (`0x517e10`): 1 in combat, else nil. No such unit takes the same
+    // arm as a unit out of combat (`0x517e48`, `0x517e5c`), so it cannot probe existence. A missing
+    // argument, or one neither string nor number, raises `Usage:` (`0x6f3510`, `0x6f4940`), unlike
+    // `UnitInRaid`; a number reaches the resolver, which raises `Unknown unit name` (`0x515c14`).
     g.set(
         "UnitAffectingCombat",
         lua.create_function(|lua, token: Value| {
@@ -626,27 +434,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitInRaid(unit) → **the constant number 1** on a hit, nil on a miss. NOT an index, and
-    // never a raise (`0x516350`, wow-re `raid-roster-bindings.md` §1, §5-cross-checked).
-    //
-    // Three things about this binding are the opposite of the obvious guess, and all three are
-    // read off its 83 bytes:
-    //
-    //  * **The hit value is a hard-coded `1.0`** — `0x51637e push 0x3ff00000; push 0` into the
-    //    push-number helper. The membership helper underneath (`0x4baee0`) only ever returns
-    //    `mov eax,1` / `xor eax,eax`; it never exposes its loop counter, so there is no index to
-    //    be 0- or 1-based about. An addon doing `local i = UnitInRaid(u)` and then
-    //    `GetRaidRosterInfo(i)` reads member 1 on the real client too.
-    //  * **It never raises.** `0x6f3690` hands back NULL for a missing or uncoercible argument
-    //    instead of erroring, `0x515970` maps NULL/empty to GUID `0:0`, and `0x4baee0`
-    //    short-circuits `0:0` to false at its entry (`or eax,esi; je`). So a missing, wrong-typed
-    //    or unresolvable unit answers `nil`, not an error — hence `Option<String>` and no usage
-    //    string, unlike its `GetRaidRosterInfo` sibling.
-    //  * **The player is in the roster array**, so no `t == "player"` special case is needed here
-    //    — unlike `UnitInParty` below, whose roster excludes the recipient.
-    // HasFullControl() → 1 | nil: the reference's `[0xb4b3e4]` read at `0x51a158` (wow-re
-    // `control-loss-and-restore.md`) — the control flag `SMSG_CLIENT_CONTROL_UPDATE` writes for
-    // the local player, which the stock unit menu greys its follow/trade rows on (1958).
+    // HasFullControl(): the flag `SMSG_CLIENT_CONTROL_UPDATE` writes for the local player
+    // (`0xb4b3e4`, read at `0x51a158`), which the stock unit menu greys its follow and trade on.
     g.set(
         "HasFullControl",
         lua.create_function(|lua, ()| {
@@ -655,11 +444,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitPlayerOrPetInParty(unit) / UnitPlayerOrPetInRaid(unit) → 1 | nil: the unit is a
-    // member of the group, or a member's pet — its owner (`UNIT_FIELD_SUMMONEDBY`, else the
-    // charmer, else the creator: `UnitState::owner`) is. The bindings are registered
-    // (`0x5162f0` / `0x5163b0`) and delegate to a C++ predicate wow-re has not carved; the
-    // owner reading is this file's, flagged in 1958.
+    // UnitPlayerOrPetInParty/InRaid(unit): the unit or its owner (`UnitState::owner`) is in the
+    // group. The reference's predicate behind `0x5162f0`/`0x5163b0` is untraced; the owner reading
+    // is benilla's.
     for (name, raid) in [
         ("UnitPlayerOrPetInParty", false),
         ("UnitPlayerOrPetInRaid", true),
@@ -695,6 +482,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
+    // UnitInRaid(unit) (`0x516350`): the constant 1 on a hit (`0x51637e`), never an index. The
+    // reference never raises `Usage:`: a missing or uncoercible argument is GUID 0 (`0x6f3690`,
+    // `0x515970`), a miss (`0x4baee0`). The roster holds the player, unlike `UnitInParty`'s.
     g.set(
         "UnitInRaid",
         lua.create_function(|lua, token: Option<String>| {
@@ -715,8 +505,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitInParty(unit) → 1 when the unit is the player-in-a-group or one of the party1..4
-    // members (a party token directly, or any token whose guid matches the roster's).
+    // UnitInParty(unit): the grouped player or a party member, by token or by roster GUID.
     g.set(
         "UnitInParty",
         lua.create_function(|lua, token: Option<String>| {
@@ -745,15 +534,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCanCooperate(a, b) → 1 for a friendly PLAYER unit. DEVIATION, stated: the client
-    // resolves faction-template cooperation masks; this reads the snapshot's is_player +
-    // UnitIsFriend's reaction>=5 — the same verdict for every case the popup gates on (invite/
-    // whisper a same-faction player), without the faction machinery the engine doesn't carry.
+    // Deviation: UnitCanCooperate answers 1 for a friendly (5 and up) player, because the engine
+    // carries no faction templates; the reference resolves their cooperation masks. The verdict
+    // matches for the unit popup's invite and whisper gates.
     g.set(
         "UnitCanCooperate",
         lua.create_function(|lua, (a, b): (Value, Value)| {
-            // BOTH positions carry an `lua_isstring` gate — two sites in the body —
-            // so either argument being nil raises (decision 1836).
+            // Both arguments are `lua_isstring`-gated, so either one nil raises.
             let a = Some(crate::script::binding_abi::string_arg(
                 lua,
                 a,
@@ -772,13 +559,11 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetRaidTargetIndex(unit) → the mark slot 1..8, or nil unmarked (decision 0434 §6's board,
-    // fed per token).
+    // GetRaidTargetIndex(unit): the mark, 1 to 8, or nil.
     g.set(
         "GetRaidTargetIndex",
         lua.create_function(|lua, token: Value| {
-            // Gated (`0x4bb4be` → `0x4bb4cd`), and the usage string names the
-            // argument unquoted — the reference's own spelling. Decision 1836.
+            // Gated (`0x4bb4be`, `0x4bb4cd`); the unquoted `unit` is the reference's spelling.
             let token = Some(crate::script::binding_abi::string_arg(
                 lua,
                 token,
@@ -793,17 +578,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The party-frame status predicates (decision 0434 §2/§3): connection, AFK/DND, and the two PvP
-    // flags. All 1/nil, through the family's one push site (2043).
-    //
-    // **`UnitIsAFK`/`UnitIsDND` are OURS, not the reference's** — this comment used to claim they
-    // "follow the era shape from the start", which named the wrong authority. wow-re's raw byte
-    // census over the whole image finds ZERO occurrences of `UnitIsAFK`, `UnitIsDND`, `IsAFK` or
-    // `IsDND`, as bindings or as strings (positive control: `UnitIsPVP\0` and `UnitIsGhost\0`
-    // each return exactly 1) — `ui/scratch/nil-unit-token-arg-law.md` §11. 1.12 surfaces a
-    // member's AFK/DND state through `GetGuildRosterInfo` and the `CHAT_FLAG_AFK`/`CHAT_FLAG_DND`
-    // GlobalStrings; there is no unit predicate for it. They wear the family's shape because that
-    // is the right shape for an invention of ours to wear, not because a binding was read.
+    // The party frame's status predicates. `UnitIsAFK` and `UnitIsDND` do not exist in the 1.12
+    // client, which has no unit AFK or DND predicate; benilla adds them beyond the 1.12 surface.
     g.set(
         "UnitIsConnected",
         lua.create_function(|lua, token: Value| {
@@ -827,8 +603,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             unit_predicate(lua, &token, |u| u.is_dnd)
         })?,
     )?;
-    // UnitIsPVP reads the same `pvp` field the unit tooltip's "PvP" line already does (one flag,
-    // two callers) — see the field doc.
     g.set(
         "UnitIsPVP",
         lua.create_function(|lua, token: Value| {
@@ -851,20 +625,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             unit_predicate(lua, &token, |u| u.is_pvp_ffa)
         })?,
     )?;
-    // UnitFactionGroup(unit) → (englishGroup, localizedName), the pair the PvP icon law reads:
-    // the first names the `UI-PVP-<group>` texture, the second titles the player frame's hit-area
-    // tooltip. nil, nil for a unit with no side (Monster/neutral templates) or no snapshot — the
-    // ref's icon branches gate on exactly that (decision 0646 §1/§3).
-    //
-    // **The two are genuinely different strings and this used to push one twice.** They are
-    // FactionGroup.dbc's `InternalName` (field 2) and `Name0` (field 3), and only on enUS are they
-    // the same word — which is why the duplication survived, and why the old doc on
-    // `UnitState::faction_group` said so as if it settled the matter. Every stock consumer of the
-    // FIRST return concatenates it into a path: `"…\UI-PVP-"..factionGroup` at `PlayerFrame.lua:68`,
-    // `TargetFrame.lua:198` and `PartyMemberFrame.lua:125`, `"…\Battleground-"..` at
-    // `BattlefieldFrame.lua:195`, and `HonorFrame.lua:68` compares it to the literal "Alliance".
-    // On any localized client the old shape named a texture that does not exist. All five of those
-    // files are on our chain.
+    // UnitFactionGroup(unit) → FactionGroup.dbc's `InternalName` (field 2), which stock FrameXML
+    // builds texture paths from (`PlayerFrame.lua:68`), and its localized `Name0` (field 3); nil,
+    // nil for a unit with no side or no snapshot.
     g.set(
         "UnitFactionGroup",
         lua.create_function(|lua, token: Value| {
@@ -879,9 +642,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             match pair {
                 (Some(english), localized) => {
                     let a = Value::String(lua.create_string(&english)?);
-                    // The localized half falls back to the English one rather than to nil: a unit
-                    // with a side always has an `InternalName`, and `Name0` is empty for the
-                    // Player/Monster rows, so nil here would blank a tooltip the reference fills.
                     let b = match localized {
                         Some(l) if !l.is_empty() => Value::String(lua.create_string(&l)?),
                         _ => a.clone(),
@@ -893,10 +653,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitRace(unit) → (localized, raceFile) or nil, nil; UnitClass(unit) → (localized,
-    // classFileName) — the paper doll's "Level %d %s %s" line + the CLASSFILENAME-keyed
-    // stat-tooltip lookups (decision 0208 §3). Unknown (feed not landed / a raceless creature)
-    // reports nil, nil — the live API's shape for an absent unit.
+    // UnitRace(unit) → localized, raceFile; UnitClass(unit) → localized, classFileName; nil, nil
+    // for a unit without one.
     g.set(
         "UnitRace",
         lua.create_function(|lua, token: Value| {
@@ -905,9 +663,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitRace("unit")"#,
             )?);
-            // The `"player"` arm is the RECORD, not the snapshot (decision 2263): `0x518269`
-            // reads `0x5abdd0` — `0xc27e80`, the char-enum row's race byte — and resolves it
-            // through `ChrRaces`, never reaching the unit resolver. See [`PlayerRecord`].
+            // The `"player"` arm reads the character-select record's race byte (`0x518269`,
+            // `0xc27e80`), never the unit resolver.
             if let Some(pair) = player_record_arm(lua, &token, |r| r.race.clone()) {
                 return match pair {
                     Some((loc, file)) => Ok((
@@ -937,8 +694,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitClass("unit")"#,
             )?);
-            // The `"player"` arm is the RECORD (decision 2263): `0x5183b9` → `0x5abde0`,
-            // `0xc27e81` through `ChrClasses`. Second return is the UPPERCASE token.
+            // The `"player"` arm reads the record's class byte (`0x5183b9`, `0xc27e81`); the second
+            // return is the uppercase token.
             if let Some(pair) = player_record_arm(lua, &token, |r| r.class.clone()) {
                 return match pair {
                     Some((loc, file)) => Ok((
@@ -960,28 +717,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             }
         })?,
     )?;
-    // UnitHasRelicSlot(unit) → **the number 1, or nil** (`0x519e50`). Whether this unit's
-    // INVSLOT 17 holds a Libram/Totem/Idol instead of a bow.
-    //
-    // The whole body is: typemask bit 4 (PLAYER) → `UNIT_FIELD_BYTES_0` byte 1 (the class) →
-    // bounds against `ds:0xc0def8` → `ds:0xc0def4`[class] → `[row+0x40]`, `ChrClasses.dbc` field
-    // 16. There is **no `cmp` against a class id anywhere in the function** — 1.12 is entirely
-    // data-driven here, and `benilla_formats::ChrClasses` is that data. The app resolves it and
-    // hands us the bit, exactly as it does for `class_file`.
-    //
-    // **This shipped absent for a long time, on a claim that was simply false** — that the relic
-    // slot post-dates 1.12 and `UnitHasRelicSlot` is a later-era verb. The base `dbc.MPQ` copy of
-    // `ChrClasses.dbc` really does have no field 16; the `patch.MPQ` copy the client actually
-    // reads has it, set for Paladin, Shaman and Druid. Decision 1796. Stock `PaperDollFrame.lua`
-    // calls this **unconditionally** at l.429 and l.580 — so while it was missing, the character
-    // sheet raised `attempt to call global 'UnitHasRelicSlot' (a nil value)` for *every* class,
-    // not just the three.
-    //
-    // No `"player"` fast path (unlike `UnitClass 0x5183b0`, which has one), so this answers for
-    // any token — `UnitHasRelicSlot("target")` on an enemy druid is 1, and the stock inspect path
-    // at `PaperDollFrame.lua:429` depends on exactly that.
-    //
-    // The truthy leg is the NUMBER 1, never a boolean; the false leg is nil, never `false`.
+    // UnitHasRelicSlot(unit) (`0x519e50`): a player unit's class has a relic slot, `ChrClasses.dbc`
+    // field 16 (`ds:0xc0def4`), which the app resolves; no class id is compared in code. Field 16
+    // is in the `patch.MPQ` copy only, set for Paladin, Shaman and Druid. No `"player"` fast path,
+    // so any token answers, as stock `InspectPaperDollFrame.lua:123` needs.
     g.set(
         "UnitHasRelicSlot",
         lua.create_function(|lua, token: Value| {
@@ -995,14 +734,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitSex(unit) → 2 male, 3 female (1 = neuter — no 1.12 unit feed produces it).
-    //
-    // **The absent/unstreamed leg is the NUMBER 2, not nil** — `UnitSex 0x517f9f` pushes the
-    // constant double 2.0 (`push 0x40000000; push 0`), which wow-re's
-    // `unit-predicate-return-shape.md` §4 carves as the numeric-getter contrast to the predicate
-    // family's `1.0`/nil: the numeric getters in this same table answer a number on the
-    // unresolved leg, never nil. The shapes table agrees — this row is `(number)`, with no nil
-    // alternative anywhere (decision 2118).
+    // UnitSex(unit): 2 male, 3 female, or 1 neuter, which no feed sends. A unit that does not
+    // resolve answers 2, never nil (`0x517f9f`).
     g.set(
         "UnitSex",
         lua.create_function(|lua, token: Value| {
@@ -1011,10 +744,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitSex("unit")"#,
             )?);
-            // The `"player"` arm is the RECORD (decision 2263): `0x517ef9` → `0x5abdf0`,
-            // `0xc27e82`. **No bounds check anywhere on that path** — the byte indexes
-            // `fild [4*eax+0x808be4]` over `{2,3,1,6}` directly — so an unset record answers `2`
-            // ("male") in the reference too, which is what our `0` maps to below.
+            // The `"player"` arm reads the record's byte (`0x517ef9`, `0xc27e82`) into
+            // `{2, 3, 1, 6}` unchecked (`0x808be4`), so an unset record answers 2 there too.
             let sex = match player_record_arm(lua, &token, |r| r.sex) {
                 Some(sex) => sex,
                 None => with_unit(lua, &token, 0u8, |u| u.sex)?,
@@ -1023,56 +754,27 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitCreatureType(unit) → **1 string, or nil** (`0x51a280`), the sibling of
-    // `UnitCreatureFamily 0x51a310`. Adjacent addresses and the same shape — but a DIFFERENT
-    // column: this reads `CreatureType.dbc` col `1 + locale`, the family reads col `8 + locale`.
-    // "Adjacent so probably identical" was right about the shape and wrong about the map.
-    //
-    // **A three-stage resolver** (`0x605570`), with no class or typemask gate anywhere — its only
-    // three tests are bounds checks:
-    //   1. **shapeshift override** — `SpellShapeshiftForm.dbc` col 12, keyed by field 138
-    //      `UNIT_FIELD_BYTES_1` byte 2, taken only if signed `> 0` (`0x60559a jg`), so `0` **and
-    //      the `-1` sentinel** fall through;
-    //   2. **the cached creature record** `[unit+0xb30]+0x18`, returned **unvalidated** — this is
-    //      what [`UnitState::creature_type_name`] carries;
-    //   3. **race fallback** — `ChrRaces.dbc` col 9, keyed by field 36 `UNIT_FIELD_BYTES_0` byte 0.
-    //
-    // Stage 3 is why **a PLAYER answers `"Humanoid"`, not nil**: `ChrRaces` col 9 is **7 for all
-    // nine shipped race rows** and `CreatureType[7]` is `"Humanoid"`, while `[player+0xb30]` is
-    // never populated (§5-verified by a 4-hit writer census — the ctor zeroes it, two writers
-    // early-out on `key==0`, and the third is hard-gated on `OBJECT_FIELD_TYPE == 0x9`, an
-    // equality a player's `0x19` fails structurally). A creature-record-only reading answers nil
-    // there, which would have been wrong for every `UnitCreatureType("player")` and every
-    // `("target")` aimed at a player.
-    //
-    // **Stage 1 is NOT modelled, and it is the one divergence to know about.** A druid in Cat,
-    // Bear, Dire Bear, Travel or Aquatic form — and a shaman in Ghost Wolf — answers `"Beast"` on
-    // the reference and `"Humanoid"` here. Tree Form, Moonkin, Battle Stance, Shadowform and
-    // Spirit of Redemption carry col 12 = `-1` and fall through to race anyway, so those already
-    // agree. We hold the active form's spell id and name ([`super::super::ShapeshiftFormView`])
-    // but **not the form INDEX the DBC is keyed by**, and matching on a localised form name would
-    // be inventing a mechanism the client does not use.
-    //
-    // The argument gate is real, and differs from the two boolean siblings: arg1 goes through
-    // `lua_isstring` (`0x6f3510`) and a miss calls `luaL_error 0x6f4940`, which **longjmps** — so a
-    // non-string, including a MISSING argument, abandons the caller's statement. An unresolved
-    // *token* is a different thing entirely and answers nil (`0x51a2b8`).
-    //
-    // Demand: 6 distinct corpus addons over 11 files.
+    // UnitCreatureType(unit) (`0x51a280`): one string, nil for a token naming no unit (`0x51a2b8`).
+    // Its resolver `0x605570` tries the shapeshift form's type (`SpellShapeshiftForm.dbc` column
+    // 12, only above 0, `0x60559a`), the cached creature record, then the race's (`ChrRaces.dbc`
+    // column 9, "Humanoid" for every race). The form stage is not built (no form index here), so an
+    // animal-form druid or a Ghost Wolf shaman answers "Humanoid" where the reference says "Beast".
+    // A missing argument, or one neither string nor number, raises `Usage:` (`0x6f3510`,
+    // `0x6f4940`).
     g.set(
         "UnitCreatureType",
         lua.create_function(|lua, token: Value| {
             let token = match &token {
                 Value::String(s) => Some(s.to_str()?.to_string()),
-                // `lua_isstring` coerces a number, so a numeric token is accepted and simply
-                // resolves to nothing.
+                // A number passes `lua_isstring`; here it answers nil, where the reference's
+                // resolver raises `Unknown unit name` for it.
                 Value::Number(_) | Value::Integer(_) => Some(String::new()),
                 _ => return Err(mlua::Error::runtime("Usage: UnitCreatureType(\"unit\")")),
             };
             let word = with_unit(lua, &token, None, |u| {
                 u.creature_type_name
                     .clone()
-                    // Stage 3, collapsed: every player race maps to CreatureType 7.
+                    // The race stage, collapsed: every player race maps to type 7.
                     .or_else(|| u.is_player.then(|| "Humanoid".to_string()))
             })?;
             match word {
@@ -1082,11 +784,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitClassification(unit) → "normal" | "elite" | "rareelite" | "worldboss" | "rare" (decision
-    // 0782, byte-verified `0x516d90`): a plain table index by the gated rank, and it answers a
-    // STRING for every input — never nil. An absent snapshot deliberately reports "normal" rather
-    // than nil because the binary does: its unresolved-token path loads table index 0 and pushes
-    // that, so a frame reading it gets the plain border art instead of a nil comparison.
+    // UnitClassification(unit) (`0x516d90`): the rank's word, and "normal" for a token that
+    // resolves to no unit, never nil.
     g.set(
         "UnitClassification",
         lua.create_function(|lua, token: Option<String>| {
@@ -1095,8 +794,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitPowerType(unit) → (index, token): (0, "MANA"), (1, "RAGE"), … (the live API also returns
-    // alt-power color components; addons that read those handle nil).
+    // UnitPowerType(unit) (`0x517940`): one number, the power index (0 mana, 1 rage, ...), with no
+    // token string. A unit that does not resolve answers 0, never nil: `UnitFrame.lua:122` indexes
+    // `ManaBarColor` with it.
     g.set(
         "UnitPowerType",
         lua.create_function(|lua, token: Value| {
@@ -1105,29 +805,13 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
                 token,
                 r#"Usage: UnitPowerType("unit")"#,
             )?);
-            // ONE value, not the Era pair. `0x517940` has four live `ret`s and `eax = 1` at every
-            // one, four `lua_pushnumber` sites and zero `lua_pushstring` — the `(type, "MANA")`
-            // tuple does not exist in 5875 (decision 1840). `power_token` stays: 1819's per-resource
-            // event names are its real caller.
-            //
-            // The miss default is the NUMBER 0, the same value as Mana and never nil, which is
-            // load-bearing rather than tidy: `UnitFrame.lua:122` indexes `ManaBarColor[...]` with it.
             let ty = with_unit(lua, &token, 0u8, |u| u.power_type)?;
             Ok(i64::from(ty))
         })?,
     )?;
 
-    // **`UnitMana`/`UnitManaMax(unit)`, not `UnitPower`** (1188 phase 5, decision 1190's list).
-    // These carried Era's names — `UnitPower`/`UnitPowerMax` do not exist in 1.12 at all, which
-    // `reference/1.12-globals.tsv` says outright — and an addon feature-detecting `if UnitPower`
-    // would have taken a path this client cannot honour.
-    //
-    // The rename is exact, not approximate: 1.12's verbs take **one argument** and return the
-    // current/max of whatever power the unit actually uses (`UnitFrame.lua`: `local currValue =
-    // UnitMana(unit)`), which is precisely what the Era pair did when called without a type — and
-    // every one of our own call sites called it that way. The type-filtering second argument goes
-    // with the name: 1.12 has no such parameter, and asking "how much *mana* does a rage user
-    // have" is spelled `UnitPowerType(unit)` first, which we already provide and which IS 1.12.
+    // UnitMana/UnitManaMax(unit): the current and maximum of whatever power the unit uses; 1.12
+    // has no `UnitPower` and no power-type argument.
     g.set(
         "UnitMana",
         lua.create_function(|lua, token: Value| {
@@ -1151,10 +835,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitXP/UnitXPMax(unit) → the player's XP within the level / the level's requirement. Player-
-    // level values (PLAYER_XP is PRIVATE, only our own avatar's), but the live API is unit-tokened:
-    // it returns the values only for the "player" token and 0 for any other unit — faithfully, no
-    // creature/other player exposes XP. `0` until the app's feed lands (SetMinMaxValues clamps).
+    // UnitXP/UnitXPMax(unit): `PLAYER_XP` is a private field, so only `"player"` has a value and
+    // any other token answers 0.
     let is_player = |token: &Option<String>| token.as_deref() == Some("player");
     g.set(
         "UnitXP",
@@ -1189,19 +871,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // UnitIsCharmed(unit) → 1 while somebody is charming this unit, else nil (`0x516cf0`).
-    //
-    // Three details, all byte-verified, none of them what a reimplementation reaches for:
-    //  · the predicate is `UNIT_FIELD_CHARMEDBY != 0` — a plain 64-bit non-zero test on fields
-    //    10/11 — **not** a `UNIT_FIELD_FLAGS` bit, which is the obvious guess for a boolean-shaped
-    //    unit question;
-    //  · a hit is the NUMBER 1 (`lua_pushnumber`, tag 3) and a miss is `nil` (tag 0) — never
-    //    `true`/`false`, and never `0`. Exactly one value on both arms;
-    //  · it is ASYMMETRIC. The field is "who charms me", so the CHARMER reads nil and the charmed
-    //    unit reads 1. `UnitIsPossessed` does not exist in 5875 at all — this is the only
-    //    charm verb in the API.
-    //
-    // KLHThreatMeter is the corpus addon blocked on it (`KTM_My.lua:533`); seven others name it.
+    // UnitIsCharmed(unit) (`0x516cf0`): `UNIT_FIELD_CHARMEDBY` is nonzero, not a flags bit, so the
+    // charmed unit answers 1 and its charmer nil. 1.12 has no `UnitIsPossessed`.
     g.set(
         "UnitIsCharmed",
         lua.create_function(|lua, token: Option<String>| {
@@ -1209,8 +880,6 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMoney() → the player's purse in copper (a player-level global, not a unit token). The coin
-    // display + the merchant window's money line read it; `0` until the app's coinage feed lands.
     g.set(
         "GetMoney",
         lua.create_function(|lua, ()| {
@@ -1219,29 +888,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetComboPoints() → the player's banked combo points, 0..5 (a player-level global, not a unit
-    // token — the 1.12 binding takes no arguments). `ComboFrame` shows/hides on it, and the
-    // combat-text COMBO_POINTS arm reads it.
-    //
-    // TWO gates before the byte, transcribed from `0x51a190` (§5 byte-read, decision 0875) — the
-    // reference `ComboFrame.lua` carries no class check at all, so BOTH of them live here or
-    // nowhere:
-    //
-    //   51a1c3  mov eax,[esi+0x110]; mov al,[eax+0x79]   ; the class byte
-    //   51a1cc  cmp al,4 / cmp al,0xb → jne push 0.0     ; ROGUE or DRUID, nothing else
-    //   51a1f3  edx=[esi+0xe68]; eax=[edx+0x838] …0x83c  ; PLAYER_FIELD_COMBO_TARGET
-    //   51a205  cmp against [0xb4e2d8]/[0xb4e2dc]        ; == the CURRENT target, or push 0.0
-    //   51a234  mov al,[ecx+0x1029]                      ; only now, PLAYER_FIELD_BYTES byte 1
-    //
-    // The class gate is why a *warrior* never sees a dot even though the server really does bank a
-    // point for them on a victim's dodge: that byte reaches the usable walk's leg 5 (which has no
-    // class test, and is what greys Overpower — 0869) but stops here, before any UI can see it.
-    // The target gate is why combo points read as "per target": re-targeting empties the dots
-    // without the count moving, and selecting the banked unit again refills them.
-    //
-    // Both comparisons are the binary's own plain equality — no null special case. With nothing
-    // banked and no target both GUIDs are 0, which passes the target gate and reads a byte that is
-    // 0 anyway; the server writes and clears the pair together.
+    // GetComboPoints() (`0x51a190`): `PLAYER_FIELD_BYTES` byte 1, behind two gates stock
+    // `ComboFrame.lua` does not repeat: the class is rogue or druid (`0x51a1cc`), so a warrior's
+    // dodge point never shows, and `PLAYER_FIELD_COMBO_TARGET` equals the current target
+    // (`0x51a205`), so the points read per target. Both are plain equality, GUID 0 included.
     g.set(
         "GetComboPoints",
         lua.create_function(|lua, ()| {
@@ -1258,19 +908,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // The rest-state trio (decisions 1082/1087) — player-level globals over the app's rest feed
-    // ([`UiScript::set_rest_state`]), the MainMenuBar exhaustion tick's and the player frame's
-    // whole wire. Byte-VERIFIED, wow-re `system/ui/scratch/rested-xp-bindings.md` (a §5 pair +
-    // orchestrator arbitration): the surface is Exhaustion.dbc DATA, not client constants — the
-    // rows live in the model ([`UiScript::set_exhaustion_rows`]; shipped-table fallback).
-    //
-    // GetRestState() → (stateID, stateName, multiplier) — `0x48d350`: the raw `PLAYER_BYTES_2`
-    // byte 3 indexes Exhaustion.dbc DIRECTLY (the `[0xc0dd78]` ID→row array) and the triple is
-    // `(row.ID, row.name[locale], row.factor)`: 1 → (1, "Rested", 2.0), 2 → (2, "Normal", 1.0),
-    // and FrameXML's dead 3..5 branches map to the real beta rows (XXXTired 1.0/0.5,
-    // XXXExhausted 0.25). Every failure — byte 0 (pre-feed), byte past the table, no row —
-    // returns (nil, nil, nil), the binary's own fail path. The multiplier is what
-    // `EXHAUST_TOOLTIP1` renders ×100 ("200% of normal experience").
+    // GetRestState() (`0x48d350`) → the Exhaustion.dbc row's ID, name and factor, indexed directly
+    // by `PLAYER_BYTES_2` byte 3 (`0xc0dd78`); nil, nil, nil when there is no such row.
     g.set(
         "GetRestState",
         lua.create_function(|lua, ()| {
@@ -1285,15 +924,9 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // GetXPExhaustion() → the rested span in BAR-XP units — `0x48d3f0`: the u32 pool × the f32
-    // factor of **Exhaustion.dbc row ID 1, hard-coded** (`[[0xc0dd78]+4]`, whatever the current
-    // state) — 2.0 in the shipped data, which is the whole "rested XP is double" law: the server
-    // drains the pool 1:1 against BASE kill XP while granting +100% (vmangos `GetXPRestBonus`),
-    // and the client scales by exactly this row's factor. **nil is decided by the rest-state
-    // byte, never by the pool** (`0x48d43b dec/jne`): byte ≠ 1 → nil whatever the pool holds
-    // (vmangos's 0 < bonus ≤ 10 hysteresis window sends byte 2 with a nonzero pool — nil there),
-    // and a rested byte with pool 0 → the NUMBER 0. The tick parks at `currXP + this`
-    // (`ExhaustionTick_Update`).
+    // GetXPExhaustion() (`0x48d3f0`): the rested pool times the factor of Exhaustion.dbc row 1
+    // whatever the state (2.0 shipped). Nil unless the rest byte is 1 (`0x48d43b`), whatever the
+    // pool holds, so a rested byte with an empty pool answers 0.
     g.set(
         "GetXPExhaustion",
         lua.create_function(|lua, ()| {
@@ -1306,9 +939,7 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             })
         })?,
     )?;
-    // IsResting() → 1/nil: inside a rest area (inn/city) right now — `0x516ea0`, byte-VERIFIED:
-    // PLAYER_FLAGS `shr 5; test 1` = bit 0x20, pushed as the NUMBER 1.0 or nil (the Lua-vanilla
-    // predicate shape, not a boolean). The player frame's flashing zzz reads exactly this.
+    // IsResting() (`0x516ea0`): `PLAYER_FLAGS` bit 0x20, in a rest area.
     g.set(
         "IsResting",
         lua.create_function(|lua, ()| {
@@ -1316,12 +947,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(flag(model.resting))
         })?,
     )?;
-    // PartialPlayTime() / NoPlayTime() → 1/nil: the two anti-addiction play-time regimes, read
-    // straight off `PLAYER_FLAGS` — `0x48eb70` is `shr eax,0xc; and al,1` (bit 12) and `0x48ebe0`
-    // its bit-13 neighbour (decision 1746, which carved both while establishing that bit 0x1000 is
-    // PARTIAL_PLAY_TIME on 5875 rather than the pre-1.6.1 CAN_SELF_RESURRECT). Same Lua-vanilla
-    // predicate shape as `IsResting` above: the NUMBER 1 or nil, never a boolean. Stock
-    // `PlayerFrame_UpdatePlaytime` (PlayerFrame.lua:244) is the only FrameXML caller of either.
+    // PartialPlayTime()/NoPlayTime(): the play-time limit flags, `PLAYER_FLAGS` bits 0x1000
+    // (`0x48eb70`) and 0x2000 (`0x48ebe0`).
     g.set(
         "PartialPlayTime",
         lua.create_function(|lua, ()| {
@@ -1336,19 +963,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(flag(model.no_play_time))
         })?,
     )?;
-    // GetBillingTimeRested() → the account's rested billing MINUTES, as one number, always
-    // (decision 1820; binding `0x48ec50`, byte-VERIFIED). The body has no `jcc` at all and ends in
-    // an unconditional `mov eax,1`, and both callees are branchless and call-free — so it can never
-    // return nil and never return zero values, which is why this is not the `Value::Nil` shape its
-    // neighbours use. The engine applies NO conversion: `0x48ec5e` is a bare unsigned u32→double
-    // push, so "minutes" is the server's convention, corroborated by stock `PlayerFrame.lua:246`
-    // dividing by 60 against `REQUIRED_REST_HOURS = 5`.
-    //
-    // Against vmangos this reads 0, because the server hardcodes `uint32(0)` for the field
-    // (`World.cpp:331`). It is fed from the wire rather than pinned to a constant so a server that
-    // populates it is reported honestly. Note the reference only ever reaches this call from
-    // INSIDE `if PartialPlayTime() ... elseif NoPlayTime()`, so with those bits clear stock
-    // FrameXML never calls it — it has to exist for the file to load, and is off the live path.
+    // GetBillingTimeRested() (`0x48ec50`): always one number, unconverted (`0x48ec5e`); stock
+    // `PlayerFrame.lua:246` reads it as minutes. vmangos always sends 0 (`World.cpp:331`).
     g.set(
         "GetBillingTimeRested",
         lua.create_function(|lua, ()| {
@@ -1356,18 +972,14 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
             Ok(Value::Number(f64::from(model.billing_time_rested)))
         })?,
     )?;
-    // GetTimeToWellRested() → nil, always — `0x48d4b0`, byte-VERIFIED: the whole binding is 11
-    // bytes, `pushnil; return 1`. FrameXML's EXHAUST_TOOLTIP4 countdown branch is dead in 5875.
+    // GetTimeToWellRested(): always nil; the reference's binding (`0x48d4b0`) only pushes nil.
     g.set(
         "GetTimeToWellRested",
         lua.create_function(|_, ()| Ok(Value::Nil))?,
     )?;
 
-    // TargetUnit(unit) — select a unit by token (the reference's `TargetUnit` Lua shim → SetSelection;
-    // the caller here is `PlayerFrame_OnClick`'s left-click branch → `TargetUnit("player")`, and the
-    // TARGETSELF binding). Queues the raw token; the app resolves it to a streamed entity and commits
-    // the selection. A nil/absent unit is ignored, as is any token the app can't resolve — the real
-    // client no-ops `TargetUnit` on a unit that doesn't exist.
+    // TargetUnit(unit): queue the token for the app to resolve and select; a token naming no unit
+    // is a no-op, as in the reference.
     g.set(
         "TargetUnit",
         lua.create_function(|lua, token: Option<String>| {
@@ -1379,31 +991,11 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // AssistUnit(unit) — select the *token's own* target (`0x489b80`; wow-re
-    // `object-layer/scratch/targeting-by-name.md` PART C, §5-cross-checked). The ASSISTTARGET
-    // binding's body is `AssistUnit("target")`, and `/assist`'s bare form is the same call.
-    //
-    // The shared assist tail (`0x489bb2`–`0x489c07`, byte-identical to `AssistByName`'s) is three
-    // steps and no more: read `UNIT_FIELD_TARGET` off the basis (`[[obj+0x110]+0x28]`), bail
-    // **silently** if it is zero, then hand the guid to the select-if-resolves helper `0x489a40`.
-    // Four things it deliberately is not:
-    //
-    //  * **not gated by `CanAssist`** — a whole-binary census of the 25 `call 0x6066f0` sites puts
-    //    none of them on this path (VERIFIED negative), so `AssistUnit("target")` on a hostile
-    //    creature assists it, and that is the common case in play.
-    //  * **not players-only** — unlike `AssistByName`'s typemask `0x10`, the token resolver takes
-    //    whatever the token names.
-    //  * **not a deselect on failure** — an unresolvable token, a basis with no target, and a
-    //    target that is not streamed all leave the current selection exactly where it was
-    //    (`0x489a40`'s arm 3 is a bare `ret`).
-    //  * **not an attack** — the tail's swing leg is gated on the `assistAttack` CVar, whose
-    //    registered default is `"0"` (VERIFIED at the registration bytes `0x48fc50`). Stock assist
-    //    selects and does not swing; the leg becomes reachable only if benilla grows the CVar.
-    //
-    // A nil/absent unit is ignored here rather than queued, like `TargetUnit`'s: the reference
-    // emits game-message `0xb8` for the token it cannot parse, and that id→string table is
-    // runtime-populated BSS wow-re could not statically recover — the same known deviation
-    // `TargetByName` already carries, and silence is better than an invented line.
+    // AssistUnit(unit) (`0x489b80`): select the unit's `UNIT_FIELD_TARGET`. The shared tail
+    // (`0x489bb2`-`0x489c07`) returns silently on 0 and selects through `0x489a40`, which leaves
+    // the selection alone when nothing resolves; no `CanAssist` gate (`0x6066f0`), any unit, and a
+    // swing only with `assistAttack` set (default "0", `0x48fc50`). Deviation: a nil token is
+    // silent, because the reference's game message `0xb8` for it has no recoverable text.
     g.set(
         "AssistUnit",
         lua.create_function(|lua, token: Option<String>| {
@@ -1417,14 +1009,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // TargetLastEnemy() — re-select the last **attackable** unit that was targeted (`0x489b45`
-    // reads the pair `[0xb4e2e8]/[0xb4e2ec]`, which `SetSelection 0x493540` stamps at `0x49377d`
-    // alongside the plain last-target pair `TargetLastTarget` reads). The TARGETLASTHOSTILE
-    // binding (default `G`) is its only shipped caller.
-    //
-    // Takes no argument and routes through the same select-if-resolves helper, so a remembered
-    // guid whose unit has since streamed out is a silent no-op rather than a deselect. The app
-    // owns the memory itself (`crate::target::scan`'s `LastEnemy`) — the VM holds no guids.
+    // TargetLastEnemy(): re-select the last attackable target (`0x489b45` reads `0xb4e2e8`, which
+    // `SetSelection` stamps at `0x49377d`), a no-op once it has streamed out. The app remembers it.
     g.set(
         "TargetLastEnemy",
         lua.create_function(|lua, ()| {
@@ -1434,18 +1020,10 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // TargetNearestFriend([reverse]) — the friendly half of the TAB scan. `0x489aa0` is
-    // byte-for-byte `TargetNearestEnemy`'s shim with one changed immediate: both fetch the
-    // optional Lua arg #1 as the reverse flag (`0x6f1c10`, default 0) and call the one cycler
-    // `0x493f60(ecx = reverse, edx = mode)` — `edx = 1` for enemy, **`2` for friend** (3 and 4 are
-    // the party and raid siblings). Everything downstream is the same code; only the
-    // per-candidate filter `0x493e40` forks on the mode, and mode 2's arm (`0x493eca`) is
-    // `CanAssist(player, cand)` then `UNIT_FIELD_HEALTH > 0`.
-    //
-    // TARGETNEARESTFRIEND (`CTRL-TAB`) calls it bare; TARGETPREVIOUSFRIEND (`CTRL-SHIFT-TAB`)
-    // calls `TargetNearestFriend(1)` — 1.12's own `Bindings.xml` comments the argument
-    // `-- 1 (or "true") means reverse!`, so the truthiness test below takes a number OR a boolean.
-    // A numeric 0 is forward, matching `0x6f1c10`'s "absent == 0" reading.
+    // TargetNearestFriend([reverse]) (`0x489aa0`): the Tab cycler `0x493f60` in mode 2 (enemy is
+    // 1), whose filter (`0x493eca`) wants `CanAssist` and health above 0. Argument 1 reverses
+    // (`0x6f1c10`, absent is 0); stock `Bindings.xml` says "1 (or "true")", so a number or a
+    // boolean reverses.
     g.set(
         "TargetNearestFriend",
         lua.create_function(|lua, reverse: Option<Value>| {
@@ -1461,41 +1039,20 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // TargetByName(name [, exactMatch]) — select by NAME through the shared resolver `0x493aa0`
-    // (`0x489d60`; wow-re `object-layer/scratch/targeting-by-name.md`, a §5 trio + two pairs).
-    // The app already owns that resolver for `/target` (decision 0886, `crate::target::by_name`);
-    // this is the binding half, which 11 corpus addons call and the slash command bypassed.
-    //
-    // The four things this signature is not:
-    //
-    //  * **not exact by default** — tier 1 is a whole-string case-insensitive compare, tier 2 is
-    //    the longest common PREFIX (anchored at 0, never a substring), and tier 2 is live
-    //    whenever Lua arg #2 is absent or 0. `TargetByName("Rag")` selects Ragnaros.
-    //  * **not nearest** — a tier-1 hit returns 0 from the walk callback and *terminates the
-    //    enumeration*, so among whole-string matches the winner is the first in enumeration
-    //    order, not the closest. Our resolver ranks exact-then-longest-prefix-then-nearest
-    //    instead; the deviation and its cost are argued at length in `by_name`'s module header,
-    //    which is the one place to change if that judgement is ever reversed.
-    //  * **not players-only** — typemask 8 is UNIT, i.e. creatures *and* players (contrast
-    //    `AssistByName`/`FollowByName`, which pass `0x10`). And with filter mode 0 there is no
-    //    dead, reaction, attackability, range, cone or scene-attach gate, and **no
-    //    self-exclusion**: `TargetByName(UnitName("player"))` self-targets.
-    //  * **not silent on a miss** — the reference emits game-message `0x127` (named, nothing
-    //    matched) or `0xb8` (null/empty name) and leaves the current target untouched. We keep
-    //    the target untouched and say nothing: the id→string table is runtime-populated BSS that
-    //    wow-re could not statically recover, and inventing a line is worse than omitting one.
-    //    Same known deviation the slash path already carries.
-    //
-    // A missing or wrong-typed first argument RAISES (`0x489d69 call 0x6f3510` → `0x489de1` →
-    // `0x6f4940`, usage literal `0x842698`); a number is accepted and stringified.
+    // TargetByName(name [, exactMatch]) (`0x489d60`, resolver `0x493aa0`, shared with `/target`): a
+    // case-insensitive whole-name match wins, else without `exactMatch` the longest common prefix,
+    // so "Rag" selects Ragnaros. Any unit (typemask 8), no dead, reaction, range or self gate. A
+    // missing name, or one neither string nor number, raises `Usage:` (`0x489d69`, `0x6f4940`); a
+    // number is taken as its string. Deviation: among whole-name matches ours picks the nearest,
+    // because the reference's first-walked pick is order-dependent and reads as a bug. Deviation: a
+    // miss is silent, because the reference's game messages `0x127` and `0xb8` have no statically
+    // recoverable text.
     g.set(
         "TargetByName",
         lua.create_function(|lua, (name, exact): (Value, Option<Value>)| {
             let name =
                 super::super::binding_abi::string_arg(lua, name, "Usage: TargetByName(\"name\")")?;
-            // Arg #2 is fetched with `0x6f1c10(idx=2, default 0)` — it never raises, and a
-            // numeric 0 is the same as absent. Matches `FollowByName`'s reading of its own
-            // arg #2, which reaches the identical `ctx+0x0c` slot.
+            // Argument 2 comes from `0x6f1c10` with default 0: it never raises, and 0 is absent.
             let exact = match exact {
                 None | Some(Value::Nil) | Some(Value::Boolean(false)) => false,
                 Some(Value::Integer(n)) => n != 0,
@@ -1508,16 +1065,8 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // DropItemOnUnit(unit) — drop the cursor's held item onto a unit (`0x48d960`). Two legs in the
-    // reference: the PET leg feeds the pet, the PLAYER leg opens a trade. Queues the raw token and
-    // nothing else — every gate reads state this VM does not hold, so the app owns all of them
-    // (`ui_action::targeting::drop_item_on_unit`).
-    //
-    // This binding **existed in our shipped `PetFrame_OnClick` before it existed here**: the
-    // handler transcribed the reference's three legs faithfully, and the middle one called a nil
-    // global, so the whole handler errored out the moment you clicked your pet holding anything.
-    // That is B208's "dropping food onto the pet doesn't feed" — the reported bug was a missing
-    // registration, not a missing mechanism.
+    // DropItemOnUnit(unit) (`0x48d960`): drop the cursor's item on a unit, feeding a pet or
+    // opening a trade with a player. Only the token is queued; the app runs every gate.
     g.set(
         "DropItemOnUnit",
         lua.create_function(|lua, token: Option<String>| {
@@ -1529,28 +1078,16 @@ pub(in crate::script) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SpellTargetUnit(unit) — bind a unit to the spell awaiting its click. The other leg of
-    // `PetFrame_OnClick`, tested BEFORE `CursorHasItem()` (ref `PetFrame.lua:114-129`), and dead
-    // in our VM for the same reason `DropItemOnUnit` was.
-    //
-    // It is registered as an accepted **no-op**, deliberately, and that is faithful for every word
-    // benilla can currently arm: the targeting cursor models the location / item / gameobject
-    // seams (0792/0923/0939), and a *unit* cannot satisfy any of them — the reference's
-    // `BindTarget 0x6e5b40` would reject it at the same three mask tests our seams ask. The word
-    // that would make this do something is the residual unit-word machine that `cast_target`'s
-    // header names as still deferred (a unit-target spell never enters targeting mode here at all;
-    // it resolves to `CastWireTarget::Unit` or refuses). So: present, silent, and honest — what it
-    // must NOT be is absent, which is what took the handler down with it.
+    // SpellTargetUnit(unit): a no-op. A unit-target spell never enters targeting mode here, and for
+    // the location, item and gameobject modes this client arms, the reference's `BindTarget`
+    // (`0x6e5b40`) rejects a unit too. Stock `PetFrame_OnClick` calls it, so it must exist.
     g.set(
         "SpellTargetUnit",
         lua.create_function(|_, _token: Option<String>| Ok(()))?,
     )?;
 
-    // ClearTarget() — drop the current selection (the reference API returns 1 when it cleared,
-    // nil when there was nothing to clear; `ToggleGameMenu`'s ESC chain depends on the nil to
-    // fall through to opening the menu). Reads the same per-token store `UnitExists("target")`
-    // answers from; the app commits the actual deselect (SetSelection guid 0 + the engaged
-    // attack-stop) from the drained trigger.
+    // ClearTarget(): 1 when it cleared a target, nil when there was none, which `ToggleGameMenu`'s
+    // Escape chain needs to fall through to the menu. The app commits the deselect.
     g.set(
         "ClearTarget",
         lua.create_function(|lua, ()| {
diff --git a/crates/benilla-ui/src/script/unit/mod.rs b/crates/benilla-ui/src/script/unit/mod.rs
index 322ee4fd..212898d1 100644
--- a/crates/benilla-ui/src/script/unit/mod.rs
+++ b/crates/benilla-ui/src/script/unit/mod.rs
@@ -1,179 +1,75 @@
-//! The game-state `Unit*` bindings (decision 0068 §3) — the first slice of the addon-facing API that
-//! reads *live game state*, and the seam that keeps this crate engine-free while doing so.
-//!
-//! The engine must not touch the ECS/net (decisions 0006/0061: the codec is stateless, the ECS owns
-//! state). So instead of reaching outward, the app pushes a per-frame **unit snapshot** into the VM
-//! via [`UiScript::set_unit`], and the `Unit*` globals here read that plain data. A frame's
-//! `UnitHealth("player")` therefore resolves against a [`UnitState`] the Bevy side deposited that
-//! frame — the same shape a real addon sees, with none of the coupling.
-//!
-//! Return shapes follow the reference: `UnitName` returns the name *or nil*;
-//! `UnitHealth`/`UnitHealthMax`/`UnitLevel` return numbers (`UnitLevel` returns **−1** for a
-//! unit whose level "can't be told" — [`level_reads_unknown`], the target frame's skull gate);
-//! a unit that doesn't exist reports `UnitExists` nil and the numbers `0` (nil for the name),
-//! exactly as the client does for an absent unit token. Tokens (`"player"`, `"target"`, …) are opaque strings the host never
-//! interprets — the app decides what each maps to.
-//!
-//! **Every predicate in this family answers the number `1` or `nil`, never a Lua boolean**, and it
-//! answers it through the one helper — [`unit_predicate`], over
-//! [`super::binding_abi::flag`]. Decision 2043; the law is 1830's, which settled the same
-//! question for the widget predicates a family earlier.
-//!
-//! v1 gaps, stated not hidden: the snapshot carries only the *active* power slot (see the
-//! `UnitMana` note below); `UnitIsConnected`'s backing
-//! field defaults `false`, and no app-side feed sets it `true` for live units yet (decision 0434
-//! §2's party-frame predicates land the binding first, the feed follows — see the field doc).
+//! The `Unit*` bindings. The app pushes each token's [`UnitState`] every frame through
+//! [`UiScript::set_unit`], and the globals read that plain data, which keeps this crate free of
+//! the ECS. Every predicate answers the number `1` or nil, never a Lua boolean.
 
 use mlua::Lua;
 
 use super::Model;
 
-/// One queued **selection ask** from Lua, in call order — the app resolves it to a guid and
-/// commits it through the one SetSelection tail.
-///
-/// The three verbs share one queue because the reference shares one *function*: `TargetUnit`
-/// (`0x4899d0`), `AssistUnit` (`0x489b80`), `TargetLastEnemy` and `TargetLastTarget` all reach
-/// selection through the "select if it resolves" helper `0x489a40`, whose three arms are the same
-/// for every caller — resolve the guid and commit, else fall back to the group roster, else a
-/// **silent return** (wow-re `object-layer/scratch/selection-attack-seam.md` §1). Splitting them
-/// into a queue each would also lose their relative order, which a macro can observe
-/// (`TargetUnit("party1"); AssistUnit("target")` is not the same as the reverse).
+/// A selection ask from Lua, queued in call order for the app to resolve and commit. The reference
+/// routes `TargetUnit`, `AssistUnit` and `TargetLastEnemy` through one helper (`0x489a40`: commit,
+/// else the group roster, else a silent return), and a macro can observe their order.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum SelectionRequest {
-    /// `TargetUnit(unit)` — select the unit the token names.
+    /// `TargetUnit(unit)` (`0x4899d0`): the unit the token names.
     Unit(String),
-    /// `AssistUnit(unit)` — select the token's own `UNIT_FIELD_TARGET`; a basis with no target is
-    /// a silent no-op (the reference's shared assist tail bails before any send).
+    /// `AssistUnit(unit)` (`0x489b80`): the token's own `UNIT_FIELD_TARGET`; a token with no
+    /// target is a silent no-op that sends nothing.
     Assist(String),
-    /// `AssistByName(name)` (`0x489c40`) — the `/assist Bob` handler's verb: select what the
-    /// *named player* is targeting. A name, not a unit token, so it is the app's name→unit
-    /// resolution (`AssistRequest`) rather than `Assist`'s token walk.
+    /// `AssistByName(name)` (`0x489c40`), the `/assist <name>` verb: what the named player
+    /// targets, resolved by name rather than by token.
     AssistByName(String),
-    /// `TargetLastEnemy()` — select the last *attackable* unit that was committed.
+    /// `TargetLastEnemy()`: the last attackable unit committed.
     LastEnemy,
 }
 
-/// **The local player record — `0xc27d80`, ours** (decision 2263).
-///
-/// A copy of ONE `SMSG_CHAR_ENUM` `CHARACTER_INFO` row, and the source the reference answers four
-/// `"player"` verbs from. Each opens with the identical full-string, case-insensitive compare of
-/// the token against `0x847894` (`b"player\0"`) whose **match is the fall-through**, and each is
-/// unconditional — there is no arm that re-routes `"player"` to the unit resolver, so the
-/// descriptor never supersedes this record even once the object exists:
-///
-/// | verb | fast path | accessor | byte |
-/// |---|---|---|---|
-/// | `UnitName` `0x517020` | `0x51708c` | `0x5abdc0` | `+0x08` name |
-/// | `UnitRace` `0x518200` | `0x518269` | `0x5abdd0` | `+0x100` → `ChrRaces` |
-/// | `UnitClass` `0x518350` | `0x5183b9` | `0x5abde0` | `+0x101` → `ChrClasses` |
-/// | `UnitSex` `0x517e90` | `0x517ef9` | `0x5abdf0` | `+0x102` gender |
-///
-/// One writer image-wide — `0x5abd9e` (`rep movsd`, 0x44 dwords) inside `CGlueMgr::EnterWorld`,
-/// at the character-select commit — and **no instruction anywhere clears it**. It is filled before
-/// FrameXML loads and before `CMSG_PLAYER_LOGIN` is sent, which is why the reference can run addon
-/// `OnUpdate` for many frames with no local player object and still answer all four (wow-re
-/// `ui/scratch/unitname-player-seed-window.md` §6).
-///
-/// **`UnitLevel` is deliberately NOT here.** The record carries the level at `+0x108` and the
-/// client ships an accessor for it, `0x5abe00`, that **nothing calls** — so `UnitLevel("player")`
-/// reads the descriptor and answers `0` in exactly the window the four answer in.
-///
-/// **Resolved strings, not the raw bytes**, because this crate has no DBC: the reference resolves
-/// `+0x100`/`+0x101` through `ChrRaces`/`ChrClasses` at call time, and the app does that same
-/// resolution once when it seeds the record (it is the identical lookup
-/// `ui_unit::race_names`/`class_names` already does for the unit snapshot, so the two cannot
-/// disagree about what a race byte means).
+/// The reference's local player record (`0xc27d80`): a copy of the chosen `SMSG_CHAR_ENUM` row,
+/// written once at the Enter World commit (`0x5abd9e`) before FrameXML loads, and never cleared.
+/// `UnitName` (`0x517020`), `UnitRace` (`0x518200`), `UnitClass` (`0x518350`) and `UnitSex`
+/// (`0x517e90`) answer `"player"`, matched whole in any case, from it and never from the
+/// descriptor, so they answer before the player object exists. `UnitLevel` reads the descriptor:
+/// the record's level accessor (`0x5abe00`) has no caller. Race and class are held resolved, as
+/// this crate has no DBC.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct PlayerRecord {
-    /// `+0x08` — the NUL-terminated name buffer at `0xc27d88`. Empty is the record's only unset
-    /// state, and the reference's only `UnitName("player")` nil: `lua_pushstring(NULL)` at
-    /// `0x517095` tail-jumps into `lua_pushnil`. Unreachable from Lua in the real client, because
-    /// the verb is not registered until `UI_Init` and only an Enter World commit gets there.
+    /// `+0x08`, the name; empty is the unset record, whose `UnitName("player")` is nil
+    /// (`0x517095`).
     pub name: String,
-    /// `+0x100` resolved — `UnitRace`'s `(localized, file token)` pair, e.g.
-    /// `("Night Elf", "NightElf")`. `None` is the all-zero record: race 0 has no `ChrRaces` row,
-    /// and the reference's bound/NULL-row arms push `nil, nil` rather than reaching the resolver.
+    /// `+0x100` as `UnitRace`'s (localized, file token) pair; `None` is race 0, which has no
+    /// `ChrRaces` row and answers `nil, nil`.
     pub race: Option<(String, String)>,
-    /// `+0x101` resolved — `UnitClass`'s `(localized, UPPERCASE token)` pair, e.g.
-    /// `("Warrior", "WARRIOR")`. `None` for the all-zero record, same shape as [`Self::race`].
+    /// `+0x101` as `UnitClass`'s (localized, uppercase token) pair; `None` answers `nil, nil`.
     pub class: Option<(String, String)>,
-    /// `+0x102` on `UnitSex`'s scale (2 male, 3 female) — **not** the wire's 0/1.
-    ///
-    /// `0` is our unset marker and reads as `2`, which is not a fudge: `0x517ef9`'s accessor feeds
-    /// `fild [4*eax+0x808be4]` over `{2,3,1,6}` with **no bounds check at all**, so an all-zero
-    /// record answers `2` ("male") in the reference too. It is the one of the four with no
-    /// validity guard.
+    /// `+0x102` on `UnitSex`'s scale (2 male, 3 female), not the wire's 0/1. The unset 0 answers
+    /// 2, as the reference's all-zero record does: `0x517ef9` indexes `{2,3,1,6}` (`0x808be4`)
+    /// with no bounds check.
     pub sex: u8,
 }
 
-/// One unit-token's game-state snapshot, pushed by the app each frame and read by the `Unit*`
-/// bindings. Plain data (no mlua handles, no ECS types) — the engine-free seam decision 0068 §3
-/// draws between the app's net/ECS feed and the Lua API.
+/// One unit token's snapshot, pushed by the app each frame and read by the `Unit*` bindings;
+/// plain data, with no mlua handles or ECS types.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct UnitState {
-    /// Whether the unit exists (`UnitExists`). A token with no snapshot is treated as `false` too.
-    ///
-    /// **Stays TRUE for an out-of-range party member** — that is the whole point of the roster
-    /// fallback, and it is what separates this field from [`Self::has_object`].
-    ///
-    /// *Named gap, second order:* 1.12's `UnitExists 0x515fb0` is a **conjunction** — the object
-    /// lookup AND a virtual `[edx+0x58]` that resolves to `IsSelectable 0x60be60`
-    /// (`!(UNIT_FIELD_FLAGS & 0x02000000) || UNIT_FIELD_CREATEDBY == you`) — falling back to the
-    /// GUID-only roster test on a miss. We model the fallback and not the conjunct, so a
-    /// not-selectable unit created by someone else reads `exists` here and `nil` there. No corpus
-    /// caller reaches it; recorded rather than folded in (wow-re
-    /// `ui/scratch/unitisvisible-object-presence.md`).
+    /// `UnitExists`, true for an out-of-range party member through the roster fallback. The
+    /// reference (`0x515fb0`) also requires a held object to be selectable before that fallback
+    /// (`0x60be60`: `UNIT_FIELD_FLAGS & 0x02000000` clear, or created by us); that is not built.
     pub exists: bool,
-    /// **`UnitIsVisible` — the client holds a live object for this token, and nothing else.**
-    ///
-    /// The reference is 57 bytes with one branch (`0x516030`):
-    /// `ClntObjMgrObjectPtr(resolve(token), TYPEMASK_UNIT) != NULL`. Its body reads **zero** object
-    /// fields, makes **zero** comparisons beyond `test eax,eax`, and contains **zero** float
-    /// opcodes — so there is no distance term, no radius, no alpha/fade/interpolation flag and no
-    /// "known to the client" bit in it. Addons read it as a range gate because **the range test is
-    /// the server's**: `SMSG_DESTROY_OBJECT` and the OUT_OF_RANGE demotion unlink the object from
-    /// the manager index this query searches, so the client answers with the presence of the
-    /// object the server chose to send.
-    ///
-    /// Distinct from [`Self::exists`], and neither implies the other. The one that matters here:
-    /// an out-of-range party member is `exists == true`, `has_object == false` — which is exactly
-    /// pfUI's `if not UnitIsVisible(unitstr) or not UnitIsConnected(unitstr)` portrait branch.
-    ///
-    /// The app already computed this and did not publish it: `ui_party::feed`'s
-    /// `member_unit_state` takes `store: Option<&ObjectStore>` and its own comment calls that
-    /// argument "the reference's `0x468460`". Every snapshot built from a live store sets it
-    /// (`ui_unit::snapshot`); the roster-record leg and a token with no snapshot leave it `false`.
-    ///
-    /// **One presence field serves three verbs** — `UnitIsVisible`, and the object-presence
-    /// conjunct of both tapped predicates below.
+    /// `UnitIsVisible` (`0x516030`): the client holds an object for this token, and nothing more;
+    /// the range test is the server's, which drops out-of-range objects. Not [`Self::exists`]: an
+    /// out-of-range party member exists without an object.
     pub has_object: bool,
-    /// `UnitIsTapped` — `UNIT_DYNAMIC_FLAGS` (UpdateField **143**) bit `0x4`: this unit is
-    /// someone's kill credit. `0x519c90` is `test BYTE PTR [eax+0x224],0x4` behind the same
-    /// object-presence check [`Self::has_object`] carries, and **nothing else** — no ownership, no
-    /// GUID compare, no party/raid or health conjunct anywhere in the body (wow-re
-    /// `ui/scratch/tapped-bits-and-unit-faction.md`).
-    ///
-    /// Set only on the live-descriptor leg, so an out-of-range unit reads `false` — which is the
-    /// object-presence conjunct, for free, by the same route `has_object` gets it.
+    /// `UnitIsTapped` (`0x519c90`): `UNIT_DYNAMIC_FLAGS` (field 143) bit `0x4`, someone holds the
+    /// kill credit. Set only from a live descriptor, which supplies the reference's
+    /// object-presence check.
     pub tapped: bool,
-    /// **`UnitIsPartyLeader`'s FIRST leg** — the server's `PLAYER_FLAGS & 0x1` on this unit's own
-    /// descriptor, restricted to players (`TYPEMASK_PLAYER`, `0x10` — **not** this family's usual
-    /// `8`, which is the one difference the predicate makes to the object lookup).
-    ///
-    /// Not derived client-side, and not the same question as "leads MY group": it is true for a
-    /// stranger who leads their own party, which no comparison against our group's leader GUID can
-    /// express. The second leg is that comparison, in `script::party` — the two cover disjoint
-    /// failures and the reference ORs them (wow-re
-    /// `ui/scratch/party-leader-and-nameplate-verbs.md`).
+    /// `UnitIsPartyLeader`'s first leg: `PLAYER_FLAGS & 0x1` on a player's own descriptor, true
+    /// for a stranger leading their own party. The reference (`0x516210`) ORs it with a compare
+    /// against our group leader's guid.
     pub group_leader: bool,
-    /// `UnitIsTappedByPlayer` — the same field's bit `0x8` (`0x519d00`, a masked-byte clone of its
-    /// sibling: 108 bytes each, differing only in the mask and the `Usage:` string).
-    ///
-    /// Read as a **pair**: `tapped && !tapped_by_player` is "someone else's kill", which is the
-    /// grey-bar condition unit-frame addons draw (pfUI `api/unitframes.lua:2012`).
+    /// `UnitIsTappedByPlayer` (`0x519d00`): the same field's bit `0x8`. Tapped without it is
+    /// someone else's kill, the grey unit frame.
     pub tapped_by_player: bool,
-    /// The unit's name (`UnitName` → the string, or nil). `None` while the app's name-query cache
-    /// hasn't answered (or the server doesn't know the unit).
+    /// `UnitName`'s name; `None` until the name query answers, which reads as [`unknownobject`].
     pub name: Option<String>,
     /// Current health (`UnitHealth`).
     pub health: u32,
@@ -181,304 +77,131 @@ pub struct UnitState {
     pub max_health: u32,
     /// Level (`UnitLevel`).
     pub level: u32,
-    /// The active power type (`UnitPowerType`): `0` mana, `1` rage, `2` focus, `3` energy,
-    /// `4` happiness — the descriptor's `UNIT_FIELD_BYTES_0` byte 3.
+    /// The active power type (`UnitPowerType`), `UNIT_FIELD_BYTES_0` byte 3: 0 mana, 1 rage,
+    /// 2 focus, 3 energy, 4 happiness.
     pub power_type: u8,
     /// Current power of the active type (`UnitMana`).
     pub power: u32,
     /// Maximum power of the active type (`UnitManaMax`).
     pub max_power: u32,
-    /// Whether the unit is dead (`UnitIsDead`). NB a released ghost is NOT dead by this
-    /// predicate — its wire health is 1 (decision 0308 §1); the trio is dead / [`Self::ghost`] /
-    /// dead-or-ghost, the real client's three tests.
+    /// `UnitIsDead`; a released ghost is not dead by it, as its health is 1.
     pub dead: bool,
-    /// Whether somebody is charming this unit (`UnitIsCharmed`).
-    ///
-    /// **`UNIT_FIELD_CHARMEDBY != 0`, and the asymmetry is the fact worth keeping.** The binding
-    /// `0x516cf0` reads fields 10/11 as one 64-bit value and tests it non-zero — not a
-    /// `UNIT_FIELD_FLAGS` bit, and not a comparison against the player (its body contains no `cmp`
-    /// at all). The field means *"who charms me"*; its mirror `UNIT_FIELD_CHARM` (*"whom I charm"*)
-    /// is never read here. So a **charmer** answers nil, a **charmed** pet answers 1, and an
-    /// ordinary **summoned** pet answers nil — `"pet"` is itself charm-else-summon in the resolver.
-    /// (wow-re `system/ui/scratch/unit-verbs-controlled-charmed-creaturetype.md`.)
+    /// `UnitIsCharmed` (`0x516cf0`): `UNIT_FIELD_CHARMEDBY` (fields 10-11) is non-zero.
+    /// `UNIT_FIELD_CHARM` is never read, so a charmer answers nil, as does a summoned pet.
     pub charmed: bool,
-    /// Whether the unit is a released ghost (`UnitIsGhost` — `PLAYER_FLAGS` bit 0x10, decision
-    /// 0308 §1). Only meaningful for player tokens; creatures stay `false`.
+    /// `UnitIsGhost`: `PLAYER_FLAGS` bit `0x10`, so players only.
     pub ghost: bool,
-    /// The unit's reaction toward the player on the `UnitReaction` scale (`1` hated … `4` neutral …
-    /// `8` exalted; `0` = unknown → `UnitReaction` returns nil). The app resolves it from the
-    /// faction-template / reputation decode (the same one the selection ring uses) for the `"target"`
-    /// token; other tokens leave it `0`. Read by `UnitReaction`, which the target frame tints its
-    /// name plate by (`TargetFrame_CheckFaction`).
+    /// The reaction toward the player on `UnitReaction`'s scale, 1 hated to 8 exalted, 0 unknown
+    /// (nil). Fed for the tokens naming another unit; `"player"` and `"pet"` stay 0.
     pub reaction: u8,
-    /// The unit's localized race display name (`UnitRace`'s first return, e.g. "Night Elf").
-    /// `None` = unknown (the race byte hasn't streamed, or a raceless creature) → `UnitRace`
-    /// returns nil, nil. The app resolves it from `UNIT_FIELD_BYTES_0` byte 0 (decision 0208 §3).
+    /// `UnitRace`'s localized first return, from `UNIT_FIELD_BYTES_0` byte 0; `None` answers
+    /// `nil, nil`.
     pub race: Option<String>,
-    /// The race's file/token name (`UnitRace`'s second return, e.g. "NightElf" — 1.12's 8 races),
-    /// the shape texture-path splices key on.
+    /// `UnitRace`'s second return, the file token (`"NightElf"`) texture paths are built from.
     pub race_file: Option<String>,
-    /// The unit's localized class display name (`UnitClass`'s first return, e.g. "Warrior").
+    /// `UnitClass`'s localized first return.
     pub class: Option<String>,
-    /// The class's file name (`UnitClass`'s second return): the **uppercase** token ("WARRIOR")
-    /// the ref's stat-tooltip lookups key on (`getglobal(strupper(class).."_STAT_TOOLTIP")` —
-    /// the ref uppercases it again defensively; we store it already uppercase).
+    /// `UnitClass`'s second return, the uppercase token (`"WARRIOR"`).
     pub class_file: Option<String>,
-    /// This unit's INVSLOT 17 is a **relic** slot rather than a ranged-weapon slot —
-    /// `UnitHasRelicSlot`'s whole answer (`0x519e50`).
-    ///
-    /// Resolved app-side off `ChrClasses.dbc` field 16, for the same reason [`Self::class_file`]
-    /// is resolved app-side: it is a static per-class column of a table this crate cannot read.
-    /// The reference gates on TYPEMASK_PLAYER before it looks at the class byte, so the feed sets
-    /// this only for a player — a creature, a pet and an unstreamed unit all leave it `false`,
-    /// which is the nil leg.
-    ///
-    /// True for exactly Paladin, Shaman and Druid in 1.12 (Libram, Totem, Idol). It was believed
-    /// here for a long time that no 1.12 class had one; see decision 1796 for how that survived.
+    /// `UnitHasRelicSlot` (`0x519e50`): INVSLOT 17 is a relic slot, from `ChrClasses.dbc` field
+    /// 16. Players only, true for Paladin, Shaman and Druid.
     pub has_relic_slot: bool,
-    /// The unit's sex on the `UnitSex` scale: `2` male, `3` female (`1` = neuter/unknown). `0`
-    /// (the unfilled default) reports as nil — the API's "can't tell", like [`Self::reaction`].
-    /// The app maps `UNIT_FIELD_BYTES_0` byte 2 (0 male / 1 female) onto this shape.
+    /// `UnitSex`'s scale, 2 male and 3 female, from `UNIT_FIELD_BYTES_0` byte 2 (0 male, 1
+    /// female). The unfilled 0 answers 2, the reference's unresolved answer (`0x517f9f`).
     pub sex: u8,
-    /// This token is a PLAYER character (guid family) — the unit tooltip's level line renders
-    /// "Race Class (Player)" instead of the creature type (decision 0276's verified law).
+    /// `UnitIsPlayer`: a player character by guid, whose tooltip level line shows race and class.
     pub is_player: bool,
-    /// This token is **player-CONTROLLED** — `UNIT_FIELD_FLAGS` bit 3
-    /// (`UNIT_FLAG_PVP_ATTACKABLE 0x8`, behaviourally "player-controlled"; the same bit
-    /// `target::relations::ring_reaction`'s duel leg selects on). Wider than
-    /// [`Self::is_player`]: a player's pet and a charmed creature are player-controlled without
-    /// being players, which is exactly the distinction stock `UnitFrame_OnEnter`
-    /// (UnitFrame.lua:58) needs when it decides whether the hovered plate gets the
-    /// player-options newbie tip. `UnitIsPlayer`'s note used to call this reach a gap we did not
-    /// carry; the unit-frame migration is what closed it.
+    /// `UnitPlayerControlled` (`0x516410`): `UNIT_FIELD_FLAGS` bit `0x8`, which a player's pet
+    /// and a charmed creature carry as well as a player.
     pub player_controlled: bool,
-    /// `UNIT_FIELD_FLAGS`, raw — what `UNIT_FLAGS` fires on (the app's `fire_transitions`); the
-    /// three readings above are bits of it.
+    /// `UNIT_FIELD_FLAGS`, raw: `UnitIsPlusMob` reads bit `0x40`, and `UNIT_FLAGS` fires when it
+    /// moves.
     pub flags: u32,
-    /// `PLAYER_FLAGS` (descriptor index 190), raw — what **`PLAYER_FLAGS_CHANGED`** fires on, the
-    /// [`Self::flags`] pattern one field over. `0` on a creature, which has no PLAYER block.
-    ///
-    /// The reference watches this dword type-wide over TYPEID_PLAYER (`0x468070(ecx=4, edx=8,
-    /// width 4)` registered at `0x5e25d7`), and its handler `0x5ee990` fires the event from
-    /// `0x5eea35`-`0x5eea3d` — **unguarded by any bit test, and above the local-player GUID gate
-    /// at `0x5eea93`** — so *any* bit moving on *any* player announces itself, remote players
-    /// included. Decision 2078.
-    ///
-    /// Raw, not a decoded subset, and that is the point: [`Self::group_leader`] (`0x1`) and
-    /// [`Self::ghost`] (`0x10`) are the only bits this struct decodes, while `0x2`/`0x4` (the
-    /// chat AFK/DND flags), `0x8` (GM), `0x200` (PvP-desired), `0x400`/`0x800` (hide helm/cloak)
-    /// and `0x1000`/`0x2000` (the play-time regimes) all move without touching either. Firing off
-    /// the decoded pair would silently under-announce every one of them.
+    /// `PLAYER_FLAGS` (field 190), raw, 0 on a creature. `PLAYER_FLAGS_CHANGED` fires when any
+    /// bit moves on any player, remote ones included: the reference's handler (`0x5ee990`) fires
+    /// before any bit test or local-player check. Raw, as most of its bits are not decoded here.
     pub player_flags: u32,
-    /// `UNIT_DYNAMIC_FLAGS` (descriptor index 143), raw — what **`UNIT_DYNAMIC_FLAGS`** the
-    /// *event* fires on, the [`Self::flags`] pattern a hundred fields over.
-    ///
-    /// The event is id **137**, and the id is not arbitrary: the reference's generic bridge
-    /// `0x51bbb0` registers one watch per unit-window field whose name-table slot is non-NULL, and
-    /// the id it dispatches is that field's own window index — `137 + 6 = 143`, this field.
-    /// Byte-verified here rather than taken from the note: `0xbe1198 + 137*4 = 0xbe13bc` has
-    /// exactly one writer image-wide (`0x51ad8b`), and the pointer it stores resolves to
-    /// `"UNIT_DYNAMIC_FLAGS"`. The watch **length** is 4 — selector byte `[0x51bc98 + 137] = 4`,
-    /// jump-table entry `0x51bbf9 mov eax,4` — so the gate is a `repe cmpsb` over exactly this one
-    /// dword against the object's shadow copy (`0x4655bb`), and **any** bit moving fires it.
-    ///
-    /// Raw for the same reason [`Self::player_flags`] is, and the cost of getting it wrong is
-    /// larger here: this struct decodes four of its bits ([`Self::tapped`],
-    /// [`Self::tapped_by_player`], and — through the store — lootable `0x1` and dead-looking
-    /// `0x20`), while `0x2` (tracked, Hunter's Mark) and `0x10` moves without touching any of
-    /// them. Firing off the decoded subset would silently under-announce those.
+    /// `UNIT_DYNAMIC_FLAGS` (field 143), raw. The event of the same name fires when any bit
+    /// moves: the reference's field watch (`0x51bbb0`) compares the whole dword, and bits such as
+    /// `0x2` (tracked) are not decoded here.
     pub dynamic_flags: u32,
-    /// The unit's owner — `UNIT_FIELD_SUMMONEDBY`, else its charmer, else its creator; `0` for
-    /// nobody's. What `UnitPlayerOrPetInParty`/`InRaid` read for the "or pet" half (1958).
+    /// The owner: `UNIT_FIELD_SUMMONEDBY`, else the charmer, else the creator, else 0; the
+    /// "or pet" half of `UnitPlayerOrPetInParty` and `UnitPlayerOrPetInRaid`.
     pub owner: u64,
-    /// The unit's guild membership (`GetGuildInfo(unit)`, decision 1257). `None` = guildless, or
-    /// a creature, or a player whose `PLAYER_GUILDID` has not streamed yet. Filled from the
-    /// PUBLIC descriptor fields 191/192 joined against the app's guild-identity cache — see
-    /// [`super::guild::UnitGuild`].
+    /// `GetGuildInfo(unit)`, from descriptor fields 191-192 and the guild-name cache; `None`
+    /// when guildless or not yet streamed.
     pub guild: Option<super::guild::UnitGuild>,
-    /// The NPC subtitle line ("Stable Master") — the creature template's subname; the unit
-    /// tooltip's second line. `None` for players/untitled creatures.
+    /// The creature template's subname ("Stable Master"), the tooltip's second line.
     pub subtitle: Option<String>,
-    /// The creature TYPE display word ("Beast", "Humanoid", …) — app-resolved from
-    /// `CreatureType.dbc`; the level line's class slot for hostile/neutral creatures.
+    /// The creature type word ("Beast") from `CreatureType.dbc`, the level line's class slot.
     pub creature_type_name: Option<String>,
-    /// Elite rank 0..4 — the creature classification every rank reader in the client shares, via
-    /// the one getter `0x605620`: the level line's rank word `{"", Elite, Elite, Boss, ""}` (0276),
-    /// `UnitLevel`'s world-boss −1 ([`level_reads_unknown`]), and `UnitClassification`
-    /// ([`classification_word`], decision 0782). **Already gated** by the app when it fills this:
-    /// the getter answers `0` unless the unit has a cached creature template *and* a zero
-    /// `UNIT_FIELD_PETNUMBER`, so a player, an un-queried creature and an enslaved elite all read
-    /// `0` here — the gate belongs at the one write, not in each of the three readers.
+    /// Creature rank 0..=4 as the reference's getter (`0x605620`) answers it, so already gated:
+    /// 0 without a cached creature template or with a pet number. The tooltip's rank word,
+    /// `UnitLevel`'s boss -1 and `UnitClassification` all read it.
     pub rank: u32,
-    /// The creature civilian flag — feeds the tooltip's green CIVILIAN line (shown only for a
-    /// PvP-flagged HOSTILE unit that is also GREY/trivial to the player — the dishonorable-kill
-    /// warning, the client's `0x612550` gate; a friendly civilian never shows it).
+    /// The creature civilian flag, one term of [`is_civilian_kill`].
     pub civilian: bool,
-    /// The creature racial-leader flag — the tooltip's white LEADER line (`0x6125c0`, gated on
-    /// the same PvP bit as CIVILIAN).
+    /// The creature racial-leader flag, the tooltip's LEADER line when PvP-flagged (`0x6125c0`).
     pub racial_leader: bool,
-    /// PvP-flagged (`UNIT_FIELD_FLAGS` PvP bit) — the tooltip's "PvP" line, and also `UnitIsPVP`
-    /// (decision 0434 §2: the party-frame PVP icon reads the same flag the tooltip line does, so
-    /// there's one field, not two).
+    /// `UNIT_FIELD_FLAGS`' PvP bit: `UnitIsPVP` and the tooltip's PvP line.
     pub pvp: bool,
-    /// Skinnable (`UNIT_FIELD_FLAGS` skinnable bit) — the tooltip's RED "Skinnable" line.
+    /// `UNIT_FIELD_FLAGS`' skinnable bit, the tooltip's red Skinnable line.
     pub skinnable: bool,
-    /// The unit's faction display name ("Stormwind") — the tooltip's white line between the
-    /// level line and "PvP". App-resolved (Faction.dbc through the unit's faction template,
-    /// every gate applied: reputation faction, race/class slot, hidden flag, the creature
-    /// HIDE_FACTION_TOOLTIP type flag); `None` = no line.
+    /// The faction name ("Stormwind"), the tooltip line after the level line, from `Faction.dbc`
+    /// through the faction template with its hiding gates applied; `None` shows no line.
     pub faction_name: Option<String>,
-    /// Connection to the server is live (`UnitIsConnected`) — an offline party member's portrait
-    /// desaturates (decision 0434 §2/§3: the `GROUP_LIST` status byte's `0x01` online bit).
-    /// **The zero value is `false`**, so a snapshot built via `..Default::default()` reports a unit
-    /// DISCONNECTED — which matters more than it reads: stock `UnitFrameManaBar_Update`
-    /// (UnitFrame.lua:213) greys a disconnected unit's bar and never reaches the power colour at
-    /// all. A synthetic unit that means to be live must say so.
-    ///
-    /// The app's own feed does (`ui_unit::snapshot`, "the stated `is_connected` gap, closed"), and
-    /// the party feed reads the roster status byte's `0x01` for its tokens. This doc used to call
-    /// that "a pending app-side change, not yet wired"; it has been wired since, and the note
-    /// outlived it. A token absent from the store (`UnitExists` false) still reports nil
-    /// regardless, via the same "no snapshot" path every other predicate here uses.
+    /// `UnitIsConnected`; party tokens take the roster status byte's `0x01`. The default `false`
+    /// reads disconnected, which greys a stock mana bar (`UnitFrame.lua:214`), so a synthetic
+    /// live unit must set it.
     pub is_connected: bool,
-    /// Away-from-keyboard (`UnitIsAFK` — decision 0434 §2's status-byte `0x40` bit). The party
-    /// frame's name line and chat both key off it. App-resolved; `false` until the feed lands.
+    /// `UnitIsAFK`, the roster status byte's `0x40`, fed for party tokens.
     pub is_afk: bool,
-    /// Do-not-disturb (`UnitIsDND` — decision 0434 §2's status-byte `0x80` bit), the AFK flag's
-    /// sibling.
+    /// `UnitIsDND`, the roster status byte's `0x80`, fed for party tokens.
     pub is_dnd: bool,
-    /// Free-for-all PvP-flagged (`UnitIsPVPFreeForAll` — decision 0434 §2's status-byte `0x10`
-    /// bit) — distinct from [`Self::pvp`]'s ordinary faction PvP flag; a unit can carry either, both,
-    /// or neither independently (an FFA zone flags this without the ordinary flag ever setting).
+    /// `UnitIsPVPFreeForAll`: `PLAYER_FLAGS` bit `0x80`, or the roster status byte's `0x10`;
+    /// independent of [`Self::pvp`].
     pub is_pvp_ffa: bool,
-    /// The unit's **current** PvP rank on the internal `0..=18` scale, `0` = no rank
-    /// (`UnitPVPRank`; decision 1512). `PLAYER_BYTES_3` **byte 3** — a **PUBLIC** descriptor field,
-    /// which is the whole reason a foreign player's rank is knowable and why the reference's
-    /// inspect pane can call `UnitPVPRank("target")`. Not to be confused with the HIGHEST LIFETIME
-    /// rank (`PLAYER_FIELD_BYTES` byte 3), which is private, rides
-    /// [`HonorState`](super::HonorState) instead, and is what `GetPVPLifetimeStats` reports.
-    ///
-    /// Internal, not visual: the badge texture and `GetPVPRankInfo`'s second return are the
-    /// `-4..=14` visual scale, converted in [`super::pvp`] and nowhere else.
+    /// `UnitPVPRank`: the current rank on the internal `0..=18` scale (0 none), from the public
+    /// `PLAYER_BYTES_3` byte 3. The private lifetime highest rides
+    /// [`HonorState`](super::HonorState); [`super::pvp`] converts to the `-4..=14` visual scale.
     pub pvp_rank: u8,
-    /// The unit's **city-protector title** index — `PLAYER_BYTES_3` **byte 2**, the byte next door
-    /// to [`Self::pvp_rank`] (vmangos `PLAYER_BYTES_3_OFFSET_CITY_PROTECTOR_TITLE`), PUBLIC like
-    /// it. `0` = none. Read by exactly one thing: `UnitPVPName`'s medal line, which appends
-    /// `"\n"` + the `PVP_MEDAL<n>` GlobalString when it is non-zero (`0x6093ef`).
-    ///
-    /// **v1 feed gap, stated not hidden:** no app-side feed fills this yet — it rides the same
-    /// dword the rank byte is decoded from, so wiring it is one line there, and until that line
-    /// exists every unit reads `0` and `UnitPVPName` renders no medal. The binding leg is built
-    /// against the field rather than left out, so the seam is a feed line rather than a missing
-    /// arm (same shape as [`Self::is_connected`]'s stated gap).
+    /// The city-protector title, `PLAYER_BYTES_3` byte 2 (0 none): `UnitPVPName` appends the
+    /// `PVP_MEDAL<n>` line for a non-zero one (`0x6093ef`).
     pub pvp_medal: u8,
-    /// The unit's PvP faction group — `"Alliance"` or `"Horde"`, else `None` (`UnitFactionGroup`;
-    /// decision 0646 §1). App-resolved from `UNIT_FIELD_FACTIONTEMPLATE` → `FactionTemplate.dbc`'s
-    /// group mask, with the Player bit skipped: every playable race's template carries
-    /// Player|<side> (mask 3 or 5), and so do the PvP-flagged city guards, so the side bit is the
-    /// only one that can name a shipped `UI-PVP-<group>` texture. `None` for Monster/neutral
-    /// templates is a state the icon callers explicitly handle (`if ( factionGroup and … )`).
-    ///
-    /// This is the **English** half — FactionGroup.dbc's `InternalName` — because that is what
-    /// `UnitFactionGroup`'s first return must carry: every stock consumer concatenates it into a
-    /// texture path (`"…\UI-PVP-"..factionGroup` at `PlayerFrame.lua:68`, `TargetFrame.lua:198`,
-    /// `PartyMemberFrame.lua:125`; `"…\Battleground-"..` at `BattlefieldFrame.lua:195`), and
-    /// `HonorFrame.lua:68` compares it against the literal `"Alliance"`.
-    ///
-    /// This field's doc used to say the binding "returns it twice … enUS ships the same word for
-    /// both". That is true of enUS and of nothing else: `Name0` is localized, so on any other
-    /// client the texture path would name a file that does not exist. The localized half lives in
-    /// [`Self::faction_group_localized`] now.
+    /// `UnitFactionGroup`'s first return, `"Alliance"` or `"Horde"`: `FactionGroup.dbc`'s English
+    /// `InternalName` for the side bit of the faction template's group mask, which stock builds
+    /// texture paths from (`PlayerFrame.lua:68`). `None` for a template with no side.
     pub faction_group: Option<String>,
-    /// The **localized** group name — FactionGroup.dbc's `Name0`, and `UnitFactionGroup`'s SECOND
-    /// return, which stock uses as display text (`PlayerFrame.lua`'s PvP hit-area tooltip title).
-    /// Never interchangeable with the English half above.
+    /// `UnitFactionGroup`'s second return, `FactionGroup.dbc`'s localized `Name0`: display text.
     pub faction_group_localized: Option<String>,
-    /// The unit's **PvP team digit** — `0x5efe00`'s tri-state: `0` Horde, `1` Alliance, `-1` a
-    /// unit with no side. The second `%d` of `PVP_RANK_<rank>_<team>`, and **not**
-    /// [`Self::faction_group`] restated.
-    ///
-    /// The two answer different questions and the difference is a shipped bug's whole cause
-    /// (report B378, decision 2227): `UnitFactionGroup` reads the unit's LIVE
-    /// `UNIT_FIELD_FACTIONTEMPLATE` (`0x5166b8`/`0x5166be`), while every rank-title surface reads
-    /// the unit's **RACE** and walks `ChrRaces` → `FactionTemplate` → factionGroupMask
-    /// (`0x5efe00`, `[obj+0x110]+0x78`). A vmangos GM is forced to template 35 and so genuinely
-    /// loses the PvP flag icon — and keeps his rank title, because his race did not move. Wiring
-    /// this to the faction group instead read `NONE` at every rank for a Grand Marshal.
-    ///
-    /// **`Default` is `0`, and that is the reference's answer too, not a placeholder.** A literal
-    /// snapshot is one the object manager could not resolve (the out-of-range roster leg), and
-    /// `GetPVPRankInfo`'s team register is left at its initial `0` on exactly that edge
-    /// (`0x51a9af`'s lookup failing) — so a roster-only unit is named off the Horde list on both
-    /// clients. Every snapshot built from a live descriptor fills it (`ui_unit::snapshot`).
+    /// The team digit of `PVP_RANK_<rank>_<team>` (`0x5efe00`): 0 Horde, 1 Alliance, -1 no side.
+    /// It follows the race through `ChrRaces` and `FactionTemplate`, never the live template
+    /// `UnitFactionGroup` reads (`0x5166b8`), so a GM on template 35 keeps the rank title. The
+    /// default 0 is the reference's answer for a unit it cannot resolve (`0x51a9af`).
     pub pvp_team: i8,
-    /// The unit's GUID (`OBJECT_FIELD_GUID`) — the identity the cross-token predicates compare
-    /// (`UnitIsUnit`, `UnitInParty`; decision 0434 §5's popup gating). `0` = the app's feed didn't
-    /// resolve one; two zero guids never compare equal.
+    /// `OBJECT_FIELD_GUID`, which `UnitIsUnit` and `UnitInParty` compare; 0 is unresolved, and
+    /// two zeros never match.
     pub guid: u64,
-    /// The raid-target mark on this unit (`GetRaidTargetIndex`): `0` none, `1..=8` the slot.
-    /// App-fed from the `GroupState` raid-target board (decision 0434 §6's verified 8-slot table
-    /// law) — the phase-5 submenu reads it; the phase-6 world renders draw from the same board.
+    /// `GetRaidTargetIndex`: 0 none, else the mark 1..=8, from the group's raid-target board.
     pub raid_target: u8,
-    /// The player can attack this unit (`UnitCanAttack("player", unit)`) — app-fed from the
-    /// byte-confirmed `CanAttack 0x606980` predicate (decision 0172; the flag disqualifiers +
-    /// reaction ≤ neutral legs TAB and the combat flash share; the Lua binding `0x516c50` is
-    /// pure delegation to it, §5-VERIFIED). Like [`Self::reaction`], the feed resolves it for
-    /// the `"target"` token; other tokens leave the default `false` (→ nil), which is right for
-    /// every current caller (`TargetFrame_CheckLevel`'s difficulty-color gate).
+    /// Whether the player can attack the unit, `UnitCanAttack("player", unit)`, which the binding
+    /// (`0x516c50`, delegating to `CanAttack` `0x606980`) answers for both argument orders. Fed for
+    /// `target`, `targettarget` and `npc`; other tokens read false.
     pub can_attack: bool,
-    /// This token resolves to a **TYPEID_CORPSE world object** — `UnitIsCorpse`'s whole
-    /// predicate (`0x5161c0`, §5-VERIFIED: a pure object-type check, no health test; a dead
-    /// mob/player is NOT a corpse). No feed sets it yet — corpse objects (a released player's
-    /// remains) aren't selectable in benilla — a stated gap, not an oversight.
+    /// `UnitIsCorpse` (`0x5161c0`): the token names a `TYPEID_CORPSE` object, which a dead unit
+    /// is not. No feed sets it.
     pub corpse_object: bool,
-    /// In combat (`UnitAffectingCombat`) — `UNIT_FIELD_FLAGS` (descriptor index 46) **bit 19**,
-    /// mask `0x00080000` (`0x517e10`, wow-re `bag-language-combat-action-bindings.md` §3,
-    /// §5-cross-checked: `mov ecx,[eax+0xa0]; shr ecx,0x13; test cl,1`).
-    ///
-    /// **There is no player-specific combat latch**, stated as the explicit negative because it
-    /// is precisely what a client is tempted to invent: a whole-image census of the
-    /// `shr reg,0x13` + `test rl,1` idiom returns 7 hits, six of them this same field+bit — and
-    /// two of those six are hardcoded *local-player* readers taking no token at all. `"player"`
-    /// takes a fast path to the cached local-player GUID inside `0x515970` and then reads the
-    /// identical bit. One wire flag answers this for every token, which is what this one field
-    /// is; `benilla::ui_action::usable` already reads the same bit off the same descriptor.
+    /// `UnitAffectingCombat` (`0x517e10`): `UNIT_FIELD_FLAGS` bit `0x00080000`, for every token
+    /// including `"player"`; the reference has no separate player combat flag.
     pub in_combat: bool,
 }
 
-/// `FrameScript_GetText("UNKNOWNOBJECT")` as the client's name resolvers call it — the VM's own
-/// GlobalString, read out of `_G` exactly as `0x703bf0` reads it (so a translated
-/// `GlobalStrings.lua` translates this too; enUS `"Unknown"`, `GlobalStrings.lua:4444`), falling
-/// back to the binary's own literal `"Unknown Being"` (`0x860fa4`) when the global is missing or
-/// empty. Always a string — this is the "name not yet known" state, never a nil.
-///
-/// **ONE home, two callers**, the same reason [`is_civilian_kill`] is a function. `UnitName`
-/// `0x517020` reaches it at `0x517220`, and `CGUnit_C::GetUnitName 0x609210` — which the UNIT
-/// TOOLTIP builder `0x529fe0` calls for its title line (`0x52a187`) — reaches the *same* tail at
-/// `0x609324`, from every one of its misses:
-///
-/// ```text
-/// 609353  je 0x609324        ; creature: [CGUnit+0xb30] (creaturecache.wdb) still null
-/// 6092ce  je 0x609324        ; pet: petnamecache.wdb row absent, or its stamp stale
-/// 609265  je 0x609324        ; player: namecache.wdb has not answered
-/// 609324  push 0x0 / or edx,-1 / mov ecx,0x850ed0 ("UNKNOWNOBJECT") / call 0x703bf0
-/// 60933c  mov eax,0x860fa4   ; the global missing or empty -> "Unknown Being"
-/// ```
-///
-/// One resolver, so the verb and the plate can never disagree about what a unit whose name is
-/// still in flight is called (decisions 2002, 2040).
-///
-/// **Both halves of that tail are here, and both are load-bearing.** The lookup is the rule
-/// (decision 2045: the sentence is the install's, not ours); the literal beside it is the
-/// reference's own `0x860fa4`, which is what "a literal is legitimate only as a fallback beside a
-/// lookup" means. Spelled `globals().get::<String>` — the shape `benilla-app`'s
-/// `reference_strings` tripwire recognises as a resolver — so the fallback reads as the fallback
-/// it is rather than as undeclared drift. It answers the same three cases the `mlua::Value` read
-/// it replaces did: a non-empty string is returned, and both a missing global and a present-but-
-/// EMPTY one take `0x860fa4` (the binary tests the pointer and then its first byte).
+/// The name of a unit whose name is not yet known, as the reference's `UnitName` (`0x517220`) and
+/// unit tooltip title (`0x609324`) both answer it: the `UNKNOWNOBJECT` GlobalString (enUS
+/// "Unknown"), else the literal "Unknown Being" (`0x860fa4`) when the global is missing or empty.
 pub fn unknownobject(lua: &Lua) -> mlua::Result<mlua::String> {
-    // One expression, deliberately: `globals().get::<String>` is what the tripwire matches on,
-    // and a line break inside it would hide this resolver from the walk again.
+    // One expression: `benilla-app`'s `reference_strings` check matches
+    // `globals().get::<String>`, and a line break inside it would hide this lookup.
     let global = lua.globals().get::<String>("UNKNOWNOBJECT").ok();
     lua.create_string(match global.as_deref() {
         Some(s) if !s.is_empty() => s,
@@ -486,18 +209,13 @@ pub fn unknownobject(lua: &Lua) -> mlua::Result<mlua::String> {
     })
 }
 
-/// The grey-band table `0x80ae98` (a byte-identical twin at `0x81dda8` drives the nameplate's
-/// grey level colour), indexed by `playerLevel / 5` and clamped to 12 past the table. ONE home
-/// for its three consumers: [`unit_is_grey`] (tooltip CIVILIAN gate + the plate's skull/grey
-/// legs), the `GetQuestGreenRange` binding (the FrameXML `GetDifficultyColor` green→grey
-/// boundary), and — through both — every level con the UI shows.
+/// The reference's grey-level band (`0x80ae98`; twins at `0x81dda8` and `0x8076c0`), indexed by
+/// player level / 5.
 const GREY_BAND: [u32; 20] = [
     4, 4, 5, 5, 6, 6, 7, 7, 8, 9, 10, 11, 12, 12, 12, 12, 12, 12, 12, 12,
 ];
 
-/// The band value for a player level — `GREY_BAND[min(playerLevel/5, 19)]` (the
-/// `GetQuestGreenRange` return, §5-VERIFIED 2026-07-17: the binding `0x4e17d0` reads the
-/// byte-identical `0x8076c0` twin with exactly this index clamp).
+/// `GetQuestGreenRange`'s answer (`0x4e17d0`): the band for a player level, 12 past the table.
 pub fn grey_band(player_level: u32) -> u32 {
     GREY_BAND
         .get((player_level / 5) as usize)
@@ -505,58 +223,32 @@ pub fn grey_band(player_level: u32) -> u32 {
         .unwrap_or(12)
 }
 
-/// The trivial/GREY check (`0x5f0700`, §5-VERIFIED 2026-07-17 — was INFERRED): a unit enough
-/// levels *below* the player that it cons grey — `playerLevel − unitLevel >
-/// GREY_BAND[playerLevel/5]`, **strict >** (diff == band is still green). The binary's full
-/// predicate also requires not-player-controlled; every consumer here applies this to creatures.
+/// 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.
 pub fn unit_is_grey(player_level: u32, unit_level: u32) -> bool {
     player_level > unit_level && player_level - unit_level > grey_band(player_level)
 }
 
-/// The **CIVILIAN predicate `0x612550`** — "killing this would be a dishonorable kill": the unit's
-/// PvP bit **and** the creature-query civilian flag **and** the unit is HOSTILE to the player
-/// (`UnitReaction` ≤ 2) **and** the kill would be GREY/trivial ([`unit_is_grey`]). A friendly
-/// civilian, or one that still cons, is not one.
-///
-/// **ONE home, two callers**, which is the whole reason it is a function: the unit tooltip's green
-/// CIVILIAN line ([`super::tooltip_unit`], decision 0276) and `UnitPVPName`'s civilian arm
-/// ([`super::pvp`] — `0x609370` leg B, which prefixes `PVP_RANK_CIVILIAN` onto a non-player's
-/// name). The engine gates both on the same call; a second copy here would let the tooltip and the
-/// name disagree about whether the same mob is a civilian.
-///
-/// **Scope of the verification.** wow-re's honor carve leaves `0x612550` itself uncarved (its §12,
-/// "named by its use here"); the four terms are decision 0276's tooltip-line law, which is where
-/// this composition was verified. So this is the tooltip's gate reused at the second call site the
-/// carve proves shares it — not an independently byte-checked predicate.
+/// The civilian gate (`0x612550`), a dishonorable kill: PvP-flagged, a civilian creature, hostile
+/// (`UnitReaction` <= 2) and grey. The tooltip's CIVILIAN line and `UnitPVPName`'s civilian prefix
+/// (`0x609370`) both read it. The terms are the tooltip line's; `0x612550`'s body is not traced.
 pub fn is_civilian_kill(u: &UnitState, player_level: u32) -> bool {
     u.civilian && u.pvp && u.reaction != 0 && u.reaction <= 2 && unit_is_grey(player_level, u.level)
 }
 
-/// The "level reads ??" gate — the engine tooltip's byte-pinned leg set (`0x529fe0` §2-LEVEL):
-/// never players; level 0 (unstreamed), world-boss rank 3, or a much-higher hostile (reaction
-/// ≤ 2 on the 1..8 API scale, unit ≥ player + 10 — **inclusive**, byte-confirmed). The Lua
-/// `UnitLevel`'s −1 law was §5-VERIFIED against this (wow-re `ui/scratch/
-/// level-assess-bindings.md`, 2026-07-17): its two −1 legs are exactly the boss + hostile-≥10
-/// legs here (no trivial-gray term exists in `0x517fc0`, and none is possible at ≥ +10), with
-/// ONE divergence the binding handles itself — a raw level ≤ 0 returns VERBATIM, not −1
-/// (same skull outcome in FrameXML; the tooltip's "??" keeps the level-0 leg per its own law).
+/// The tooltip's "??" level gate (`0x529fe0`): never a player; level 0, world-boss rank 3, or a
+/// hostile (reaction <= 2) at least 10 levels above the player. `UnitLevel` (`0x517fc0`) answers
+/// the boss and hostile legs with -1, but returns a level of 0 as is.
 pub fn level_reads_unknown(u: &UnitState, player_level: u32) -> bool {
     let much_higher_hostile =
         u.reaction != 0 && u.reaction <= 2 && u.level >= player_level.saturating_add(10);
     !u.is_player && (u.level == 0 || u.rank == 3 || much_higher_hostile)
 }
 
-/// `UnitClassification`'s return — the classification-word table, **byte-verified** at `0x850424`
-/// (decision 0782): the binding `0x516d90` is nothing but `TABLE[rank(unit)]`, indexed by the same
-/// gated rank [`UnitState::rank`] carries. The table is exactly five entries long (the sixth dword
-/// at `0x850438` is an unrelated `"UnitExists"` literal), and rank comes pre-clamped to 0..4 by
-/// `CreatureInfo+0x20`, so an out-of-range value can only be our own bug — it reads `"normal"`,
-/// which is also what the binding's unresolved-token path pushes (`0x516dc4` loads index 0).
-///
-/// Note `"rareelite"` is a real return here even though 1.12 has no rare-elite *art* and no
-/// rare-elite tooltip *word* — the reference's `TargetFrame_CheckClassification` sends it to the
-/// same Elite border as `"elite"`, and the tooltip's `{"", Elite, Elite, Boss, ""}` prints ELITE for
-/// it. The distinction exists in the API and nowhere in the pixels.
+/// `UnitClassification` (`0x516d90`): the word table at `0x850424` indexed by the gated
+/// [`UnitState::rank`]; an unresolved token reads index 0, "normal" (`0x516dc4`). "rareelite" is
+/// a real answer, though stock draws it with the elite art (`TargetFrame.lua:209`).
 pub fn classification_word(rank: u32) -> &'static str {
     match rank {
         1 => "elite",
@@ -567,8 +259,8 @@ pub fn classification_word(rank: u32) -> &'static str {
     }
 }
 
-/// The Era power-token string for a power-type index (`UnitPowerType`'s second return,
-/// `UNIT_POWER_UPDATE`'s arg2). Unknown indices report as mana, the descriptor default.
+/// The resource name for a power type, the suffix of 1.12's per-resource events (`UNIT_RAGE`,
+/// `UNIT_MAXRAGE`); an unknown index reads as mana, the descriptor default.
 pub fn power_token(ty: u8) -> &'static str {
     match ty {
         1 => "RAGE",
@@ -580,28 +272,17 @@ pub fn power_token(ty: u8) -> &'static str {
 }
 
 impl super::UiScript {
-    /// Push (or clear) a unit token's snapshot. `Some(state)` stores it under `token`; `None` removes
-    /// it (so `UnitExists(token)` reports false and the numeric getters return `0`). The app's
-    /// per-frame feed (decision 0068 §3) calls this for `"player"`/`"target"`/… before the VM's
-    /// event dispatch, so a frame's `OnEvent` sees the current values.
+    /// Push, or clear with `None`, a token's snapshot; the app's feed calls it each frame before
+    /// event dispatch, so a frame's `OnEvent` sees current values.
     pub fn set_unit(&mut self, token: &str, state: Option<UnitState>) {
         {
             let mut model = self.model_mut();
             match state {
-                // Folded on the way IN as well as on the way out — the map's key type is the
-                // canonical lowercase token, so a feed that ever pushed `"Target"` could not create
-                // a second, shadowing entry.
+                // Keys fold to lowercase on the way in too, so a `"Target"` push cannot shadow
+                // `"target"`.
                 Some(s) => {
-                    // **A `"player"` push keeps the record in step, field by field** (2261,
-                    // widened by 2263). The reference writes `0xc27d80` once per Enter World
-                    // commit and never clears it; our VM is rebuilt per login, so the entry load
-                    // seeds it — and this keeps it true for any later push that KNOWS a field,
-                    // without ever letting one that doesn't blank it.
-                    //
-                    // That asymmetry is the whole mechanism: 2260's nameless player snapshot is
-                    // exactly the push that must not be able to reach these four verbs. It is also
-                    // what keeps every fixture in the workspace correct without touching them — a
-                    // test that seats a full player is, by this rule, also seating the record.
+                    // A `"player"` push updates each record field it carries and never blanks
+                    // one, so a nameless snapshot cannot reach the four record verbs.
                     if token.eq_ignore_ascii_case("player") {
                         let rec = &mut model.player_record;
                         if let Some(name) = s.name.as_deref().filter(|n| !n.is_empty()) {
@@ -626,34 +307,26 @@ impl super::UiScript {
                 }
             }
         }
-        // A push for a tooltip's LIVE unit token re-drives its health bar (the byte law's
-        // HEALTH watcher — decision 0276; no line rebuild).
+        // A push for a tooltip's live unit token re-drives its health bar, without a line rebuild.
         super::tooltip_unit::on_unit_push(&self.lua, token);
     }
 
-    /// Push the player's purse in copper (`PLAYER_FIELD_COINAGE`), read by the `GetMoney` global. A
-    /// player-level snapshot (like the unit tokens) — the app calls this each frame the coinage
-    /// field changes (decision 0081 phase 4).
+    /// Push the player's copper (`PLAYER_FIELD_COINAGE`), read by `GetMoney`.
     pub fn set_money(&mut self, copper: u64) {
         self.model_mut().money = copper;
     }
 
-    /// Push the player's experience within the level (`PLAYER_XP`) and the level's requirement
-    /// (`PLAYER_NEXT_LEVEL_XP`), read by the `UnitXP`/`UnitXPMax` globals. A player-level pair (like
-    /// [`Self::set_money`]) — the app calls this each frame the XP fields change (the MainMenuBar XP
-    /// bar feed). Both PRIVATE descriptor fields, so this only ever carries our own avatar's values.
+    /// Push `PLAYER_XP` and `PLAYER_NEXT_LEVEL_XP`, private fields that `UnitXP` and `UnitXPMax`
+    /// answer for `"player"` alone.
     pub fn set_player_xp(&mut self, xp: u32, next_level_xp: u32) {
         let mut model = self.model_mut();
         model.player_xp = xp;
         model.player_next_level_xp = next_level_xp;
     }
 
-    /// Push the player's rest snapshot — the `PLAYER_BYTES_2` byte 3 rest state, the
-    /// `PLAYER_REST_STATE_EXPERIENCE` pool (raw wire value, base kill-XP units) and the
-    /// `PLAYER_FLAGS_RESTING` bit — taken together so the `GetRestState`/`GetXPExhaustion`/
-    /// `IsResting` trio can never read a half-updated rest picture. Player-level fields, same
-    /// shape as [`Self::set_money`]; the app calls this each frame any of the three moves
-    /// (decision 1082).
+    /// Push the rest state (`PLAYER_BYTES_2` byte 3), the rested pool
+    /// (`PLAYER_REST_STATE_EXPERIENCE`, raw) and `PLAYER_FLAGS_RESTING` together, so
+    /// `GetRestState`, `GetXPExhaustion` and `IsResting` never read a half update.
     pub fn set_rest_state(&mut self, state: u8, pool: u32, resting: bool) {
         let mut model = self.model_mut();
         model.rest_state = state;
@@ -661,48 +334,40 @@ impl super::UiScript {
         model.resting = resting;
     }
 
-    /// Push the two **play-time** bits of `PLAYER_FLAGS` — 12 (`PartialPlayTime`) and 13
-    /// (`NoPlayTime`), decision 1746. Taken together for the same reason the rest trio is:
-    /// stock `PlayerFrame_UpdatePlaytime` (PlayerFrame.lua:244) tests them as an if/elseif pair
-    /// and a half-updated pair would paint the wrong one of the two icons.
+    /// Push `PLAYER_FLAGS` bits 12 (`PartialPlayTime`) and 13 (`NoPlayTime`) together, as
+    /// `PlayerFrame.lua:244` tests them in one if/elseif.
     pub fn set_play_time(&mut self, partial: bool, none: bool) {
         let mut model = self.model_mut();
         model.partial_play_time = partial;
         model.no_play_time = none;
     }
 
-    /// Push the account's **rested billing minutes**, from the `SMSG_AUTH_RESPONSE` that admitted
-    /// the session — what `GetBillingTimeRested()` returns (decision 1820). Set once at login: the
-    /// client parks it in a process-lifetime global and nothing else on the wire ever writes it.
+    /// Push `GetBillingTimeRested()`'s minutes, from the `SMSG_AUTH_RESPONSE` that admitted the
+    /// session; nothing else on the wire writes it.
     pub fn set_billing_time_rested(&mut self, minutes: u32) {
         self.model_mut().billing_time_rested = minutes;
     }
 
-    /// Enter the **UI-load sound-suppression scope** — the reference's `0x458f50`, an `inc` on the
-    /// counted depth every name-keyed `PlaySound` reads. Counted, not a flag, exactly as the
-    /// client has it: nesting is legal and only the outermost exit re-enables sound.
+    /// Enter the UI-load sound-suppression scope (`0x458f50`): a depth every name-keyed
+    /// `PlaySound` reads, so scopes nest and only the outermost exit re-enables sound.
     pub fn push_sound_suppression(&self) {
         let mut model = self.model_mut();
         model.sound_suppression = model.sound_suppression.saturating_add(1);
     }
 
-    /// Leave it — `0x458f60`'s `dec`. Saturating on the way down too: an unbalanced pop is a bug
-    /// in the caller, and silently wrapping to a permanently-muted UI would be the worse failure.
+    /// Leave it (`0x458f60`), saturating so an unbalanced pop cannot wrap to a muted UI.
     pub fn pop_sound_suppression(&self) {
         let mut model = self.model_mut();
         model.sound_suppression = model.sound_suppression.saturating_sub(1);
     }
 
-    /// Push whether a cinematic is playing — what `InCinematic()` answers.
+    /// Push whether a cinematic is playing, `InCinematic()`'s answer.
     pub fn set_in_cinematic(&mut self, playing: bool) {
         self.model_mut().in_cinematic = playing;
     }
 
-    /// Push Exhaustion.dbc — `(rest-state byte, localized name, factor)` rows for the
-    /// `GetRestState`/`GetXPExhaustion` bindings (they read the table exactly as `0x48d350` /
-    /// `0x48d3f0` read the client's own copy; decision 1087). Called once at startup off the
-    /// patch chain; an empty push is ignored so a failed DBC read keeps the shipped-table
-    /// fallback the model seeds.
+    /// Push `Exhaustion.dbc`'s (rest state, localized name, factor) rows, read as `0x48d350` and
+    /// `0x48d3f0` read them; an empty push keeps the fallback table the model seeds.
     pub fn set_exhaustion_rows(&mut self, rows: Vec<(u8, String, f64)>) {
         if rows.is_empty() {
             return;
@@ -711,64 +376,45 @@ impl super::UiScript {
         model.exhaustion = rows.into_iter().map(|(id, n, f)| (id, (n, f))).collect();
     }
 
-    /// Push the player's banked combo points (`PLAYER_FIELD_BYTES` byte 1) and the unit they sit
-    /// on (`PLAYER_FIELD_COMBO_TARGET`) — the pair `Player::SetComboPoints` writes together, taken
-    /// together so they can never be read half-updated. Player-level PRIVATE fields, same shape as
-    /// [`Self::set_money`]; the app calls this each frame either moves, including the drop back to
-    /// zero (decisions 0869, 0875).
-    ///
-    /// **Raw wire values** — `GetComboPoints`'s class and current-target gates live in the binding,
-    /// where the binary puts them.
+    /// Push the combo points (`PLAYER_FIELD_BYTES` byte 1) and their target
+    /// (`PLAYER_FIELD_COMBO_TARGET`) together, as `Player::SetComboPoints` writes them. Raw:
+    /// `GetComboPoints`' class and target gates are the binding's.
     pub fn set_combo_points(&mut self, points: u8, target: u64) {
         let mut model = self.model_mut();
         model.combo_points = points;
         model.combo_target = target;
     }
 
-    /// Drain the selection asks queued since the last call — the app resolves each to a guid and
-    /// commits it through the one SetSelection tail. See [`SelectionRequest`] for why the three
-    /// verbs share one ordered queue.
+    /// Drain the queued [`SelectionRequest`]s, in call order.
     pub fn take_selection_requests(&mut self) -> Vec<SelectionRequest> {
         std::mem::take(&mut self.model_mut().selection_requests)
     }
 
-    /// Drain the `TargetNearestFriend([reverse])` presses queued since the last call — one `bool`
-    /// per call, the cycle direction (`false` forward, `true` backward). Its own queue rather than
-    /// a [`SelectionRequest`] variant because it names no unit: the reference runs it through the
-    /// TAB cycler `0x493f60(reverse, mode 2)` and straight into `SetSelection`, never through the
-    /// select-if-resolves helper the other three share.
+    /// Drain the `TargetNearestFriend([reverse])` calls, `true` for reverse. It names no unit: the
+    /// reference runs the TAB cycler (`0x493f60`, mode 2) straight into `SetSelection`.
     pub fn take_target_nearest_friend_requests(&mut self) -> Vec<bool> {
         std::mem::take(&mut self.model_mut().target_nearest_friend_requests)
     }
 
-    /// Drain the `(name, exactMatch)` pairs `TargetByName` queued since the last call — the app
-    /// runs the shared by-name resolver (decision 0886) and commits the selection.
+    /// Drain the `TargetByName(name, exactMatch)` calls for the app's by-name resolver.
     pub fn take_target_by_name_requests(&mut self) -> Vec<(String, bool)> {
         std::mem::take(&mut self.model_mut().target_by_name_requests)
     }
 
-    /// Drain the `ClearTarget()` trigger: `true` if it fired with a live target since the last
-    /// call — the ESC chain's last leg; the app commits the deselect (SetSelection guid 0).
+    /// Drain `ClearTarget()`: true if it fired with a live target; the app deselects (guid 0).
     pub fn take_target_clear(&mut self) -> bool {
         std::mem::take(&mut self.model_mut().target_clear)
     }
 
-    /// Drain the unit tokens `DropItemOnUnit` queued since the last call — the app runs every gate
-    /// and, on the pet leg, casts the learned Feed Pet spell at the held item (`0x48d960`).
+    /// Drain `DropItemOnUnit`'s tokens; on the pet the app casts the learned Feed Pet spell at
+    /// the held item (`0x48d960`).
     pub fn take_drop_item_on_unit(&mut self) -> Vec<String> {
         std::mem::take(&mut self.model_mut().drop_item_on_unit)
     }
 }
 
-/// Pick the interesting token from a directional two-unit call (`UnitIsEnemy(a, b)`): whichever
-/// arg isn't `"player"` — our snapshot stores the relationship on the non-player unit (target),
-/// and the ref calls both argument orders.
-///
-/// **The `"player"` test folds case**, like every other token comparison here and like the client's
-/// own resolver. It is the kind of site the map's fold does not cover on its own: an addon passing
-/// `UnitIsEnemy("Player", "target")` would otherwise be read as naming a non-player first arg, and
-/// this would answer about the wrong unit — a wrong ANSWER rather than a missing one, which is the
-/// worse failure of the two.
+/// The non-`"player"` token of a two-unit call such as `UnitIsEnemy(a, b)`, which the snapshot
+/// holds the relationship on; the test folds case, as the resolver does.
 fn pick_unit_token(a: &Option<String>, b: &Option<String>) -> Option<String> {
     match (a, b) {
         (Some(x), _) if !x.eq_ignore_ascii_case("player") => Some(x.clone()),
@@ -777,16 +423,9 @@ fn pick_unit_token(a: &Option<String>, b: &Option<String>) -> Option<String> {
     }
 }
 
-/// The token prefixes 1.12's resolver `0x515970` recognises, in its own order.
-///
-/// The order is the binary's and is preserved even though our recogniser is order-insensitive:
-/// `partypet` must be tested before `party` and `raidpet` before `raid` for a *resolver* to pick the
-/// right unit, and the day this grows from a boolean into a resolver, the list is already right.
-///
-/// **These are PREFIX tests.** The compare length is the literal's, and `_strnicmp` stops at either
-/// string's NUL, so `"playerfoo"` matches `player` — which is why it is a quiet nil rather than a
-/// raise. `npc` is the sole FULL-STRING compare in the resolver, so `"npctarget"` matches nothing
-/// and raises; it is deliberately absent from this list and handled separately below.
+/// The token prefixes the resolver (`0x515970`) tests, in its order (`partypet` before `party`).
+/// Each is a prefix test, so `"playerfoo"` is recognised; `npc`, its one full-string compare, is
+/// tested apart.
 const UNIT_TOKEN_PREFIXES: [&str; 8] = [
     "player",
     "pet",
@@ -798,47 +437,24 @@ const UNIT_TOKEN_PREFIXES: [&str; 8] = [
     "mouseover",
 ];
 
-/// Does 1.12's resolver RECOGNISE this token — whether or not it names a live unit?
-///
-/// This is the whole raise/nil distinction, so it is worth being exact about what it is not: it does
-/// not ask whether a unit exists. `"party5"` on a solo character, `"pet"` with no pet, and
-/// `"playerfoo"` are all *recognised* and answer nil; only a token the resolver's nine compares
-/// never match raises `Unknown unit name`.
+/// Whether the resolver recognises the token, not whether it names a unit: `"party5"` solo is
+/// recognised and answers nil, and only a token none of its nine compares match raises.
 pub(crate) fn token_recognised(token: &str) -> bool {
-    // `npc` full-string, everything else a prefix — and folded, like every compare in the resolver
-    // (`SStrCmpI` -> `_strnicmp`, ASCII only; 1247).
+    // `npc` full-string, the rest prefixes, all folded as `_strnicmp` folds: ASCII only.
     token.eq_ignore_ascii_case("npc")
         || UNIT_TOKEN_PREFIXES
             .iter()
-            // BYTES, not a string slice. `token[..p.len()]` panics when the token is multibyte
-            // UTF-8 and the prefix length lands mid-character ("byte index N is not a char
-            // boundary") — an addon passing a non-ASCII token would take the client down. The
-            // client's own compare is `_strnicmp` over bytes with an ASCII-only fold, so byte
-            // comparison is both the safe form and the faithful one.
+            // Bytes, not a `str` slice, which panics mid-character on a multibyte token.
             .any(|p| {
                 token.len() >= p.len()
                     && token.as_bytes()[..p.len()].eq_ignore_ascii_case(p.as_bytes())
             })
 }
 
-/// The gate every `Unit*` binding puts an addon-supplied token through.
-///
-/// **An unrecognised token RAISES and does not return** — `0x515970` falls off the end of its nine
-/// compares into `luaL_error(L, "Unknown unit name: %s")`, which longjmps (wow-re
-/// `system/ui/scratch/unit-token-grammar.md`). Ours answered nil for everything unknown, which is
-/// 1203's shape pointed the other way: a failure the client reports, silently swallowed.
-///
-/// The split is THREE-way, not two, and the two quiet legs are as carved:
-///   * **absent argument** — quiet nil *here*, because this helper is only the resolver's half.
-///     Whether a nil ever reaches it is the BINDING's question, and it is settled per binding:
-///     wow-re's census of all 83 entries at `0x850438` found 53 that gate the token position with
-///     `lua_isstring` and raise `Usage:`, against 13 unit-token bindings with no gate at all
-///     (decision 1834). The gated ones call `binding_abi::string_arg` before they get here, so a
-///     nil never arrives; the quiet 13 pass it straight through. This comment used to say the
-///     gates were "NOT uniform … only those two poles are verified" and decline to guess, which
-///     was the right call at the time — the table now exists, so it is applied rather than feared;
-///   * **`""`** — quiet nil;
-///   * a **recognised** token naming nothing (`"party5"` solo, `"playerfoo"`) — quiet nil.
+/// The resolver's token check: an unrecognised token raises `Unknown unit name`, as `0x515970`
+/// ends in `luaL_error`; `""`, an absent token and a recognised one naming nothing pass. Whether
+/// nil arrives is per binding: of the 83 in the table at `0x850438`, 53 raise `Usage:` first and
+/// 13 unit-token bindings take nil with no gate.
 pub(crate) fn check_unit_token(token: &Option<String>) -> mlua::Result<()> {
     match token {
         Some(t) if !t.is_empty() && !token_recognised(t) => {
@@ -848,10 +464,8 @@ pub(crate) fn check_unit_token(token: &Option<String>) -> mlua::Result<()> {
     }
 }
 
-/// Read a unit token's snapshot under a short model borrow, mapping it through `f`; `default` when the
-/// token is absent (the "unit doesn't exist" path).
-///
-/// Raises for an unrecognised token ([`check_unit_token`]) before it looks anything up.
+/// Map a token's snapshot through `f` under a short model borrow, or answer `default` for an
+/// absent unit, after the token check.
 fn with_unit<T>(
     lua: &Lua,
     token: &Option<String>,
@@ -866,21 +480,10 @@ fn with_unit<T>(
     })
 }
 
-/// A unit **predicate** binding's whole body: resolve the token, map its snapshot to a bool, and
-/// push the family's one return shape — the number `1` or `nil`, never a Lua boolean.
-///
-/// [`with_unit`] answers whatever `f` answers, so a predicate written on it *directly* hands mlua a
-/// Rust `bool`, and mlua pushes tag 1. That is the one shape 1.12 cannot produce: `UnitExists`
-/// (`0x515fb0`) pushes `lua_pushnumber` (`0x6f3810`, tag 3, the double `1.0`) or `lua_pushnil`
-/// (`0x6f37f0`, tag 0) and nothing else, and so does every other predicate in the family. So the
-/// whole family goes through [`super::binding_abi::flag`] — 1830's widget law, which is the
-/// *same* law, finally applied to the unit surface (decision 2043). A predicate that hand-computes
-/// its own bool calls that helper directly; one that reads a snapshot field calls this. Both end at
-/// the one push site, which is what stops the family drifting apart again.
-///
-/// **Not every unit binding is a predicate.** `UnitReaction` answers the reaction *number*,
-/// `UnitLevel` a level (with `-1` for "can't be told"), `UnitPowerType` a power index whose miss is
-/// the number `0` and never nil. Those keep their own shapes and must not be routed here.
+/// A unit predicate's body: the number 1 or nil through [`super::binding_abi::flag`], never a Lua
+/// boolean, as the reference pushes only `lua_pushnumber` (`0x6f3810`) or `lua_pushnil`
+/// (`0x6f37f0`). `UnitReaction`, `UnitLevel` and `UnitPowerType` are getters with their own
+/// shapes and do not route here.
 fn unit_predicate(
     lua: &Lua,
     token: &Option<String>,
@@ -889,8 +492,7 @@ fn unit_predicate(
     Ok(super::binding_abi::flag(with_unit(lua, token, false, f)?))
 }
 
-/// The `Unit*`/`GetQuestGreenRange` Lua binding registrations — split from this module's
-/// state+laws half purely for size (same seam as the other script modules' install fns).
+/// The `Unit*` and `GetQuestGreenRange` registrations.
 mod bindings;
 #[cfg(test)]
 mod tests;
diff --git a/crates/benilla-ui/src/script/unit/tests.rs b/crates/benilla-ui/src/script/unit/tests.rs
index 740d4803..014ecc9c 100644
--- a/crates/benilla-ui/src/script/unit/tests.rs
+++ b/crates/benilla-ui/src/script/unit/tests.rs
@@ -1,4 +1,4 @@
-//! The `Unit*` binding tests (the parent module is the unit under test).
+//! The `Unit*` binding tests.
 
 use crate::script::{PartyState, PlayerRecord, UiScript, UnitState};
 
@@ -26,7 +26,7 @@ fn player() -> UnitState {
 #[test]
 fn unit_reaction_reports_the_scale_value_or_nil() {
     let mut s = UiScript::new().unwrap();
-    // Neutral target (UnitReaction 4) → the integer; the name-plate palette indexes it.
+    // 4 is neutral.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -40,7 +40,7 @@ fn unit_reaction_reports_the_scale_value_or_nil() {
             .unwrap(),
         4
     );
-    // reaction 0 (unresolved) reports as nil — the API's "can't tell".
+    // 0 is unresolved, which answers nil.
     s.set_unit(
         "player",
         Some(UnitState {
@@ -54,15 +54,11 @@ fn unit_reaction_reports_the_scale_value_or_nil() {
         .unwrap());
 }
 
-/// The target plate's faction decision (TargetFrame_CheckFaction, as `UnitFrame_Update`
-/// composes it): a player-controlled target picks red (mutually hostile) or blue (else) and
-/// NEVER the reaction green; only an NPC reads the reaction swatch. This pins the predicate
-/// composition the plate branch depends on — a friendly *player* must resolve to blue, which is
-/// exactly the green-vs-blue bug the branch fixes.
+/// A player target branches on `UnitIsEnemy` and an NPC on `UnitReaction` (2 hostile, 5
+/// friendly), so a friendly player is blue, never the reaction colour.
 #[test]
 fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch() {
     let mut s = UiScript::new().unwrap();
-    // The plate's decision, verbatim from the XML Update (a chunk whose if-branches each return).
     let plate = r#"
             local u = "target"
             if UnitIsPlayer(u) then
@@ -73,7 +69,6 @@ fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch(
         "#;
     let decide = |s: &mut UiScript| s.eval::<String>(plate).unwrap();
 
-    // A friendly PLAYER (reaction 5) → blue, not the reaction green.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -84,7 +79,6 @@ fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch(
         }),
     );
     assert_eq!(decide(&mut s), "blue");
-    // A hostile PLAYER (reaction 2) → red.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -95,7 +89,6 @@ fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch(
         }),
     );
     assert_eq!(decide(&mut s), "red");
-    // A friendly NPC (same reaction 5, not a player) → the reaction swatch (green), unchanged.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -106,7 +99,6 @@ fn the_name_plate_faction_branch_picks_player_red_blue_over_the_reaction_swatch(
         }),
     );
     assert_eq!(decide(&mut s), "reaction");
-    // UnitIsPlayer itself: 1 for a player, nil otherwise.
     assert!(s
         .eval::<bool>(r#"return UnitIsPlayer("target") == nil"#)
         .unwrap());
@@ -132,8 +124,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         level: 3,
         ..Default::default()
     });
-    // A hostile 10+ levels up (reaction 2, level 13 vs player 3) → −1: the target frame's
-    // skull branch (TargetFrame_CheckLevel's `level <= 0`).
+    // Hostile (2) and 10 levels above the player: -1, the target frame's skull.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -144,7 +135,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), -1);
-    // One level short of the band (12 vs 3) → the raw number.
+    // 9 above: the level.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -155,7 +146,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), 12);
-    // The same 10-up gap on a NEUTRAL (reaction 4) tells its level — the gate is hostile-only.
+    // Neutral (4) at 10 above: the level, as the gate is hostile-only.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -166,7 +157,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), 13);
-    // A world boss (creature rank 3) hides its level regardless of the gap.
+    // A world boss (rank 3) at any gap: -1.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -178,7 +169,6 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), -1);
-    // A PLAYER never reads −1 (rank/reaction notwithstanding).
     s.set_unit(
         "target",
         Some(UnitState {
@@ -190,8 +180,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
         }),
     );
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("target")"#).unwrap(), 60);
-    // A raw level 0 (unstreamed) returns VERBATIM — never −1 (§5: `0x517fc0` pushes the
-    // raw field; only the boss/hostile legs substitute). Same skull outcome via `<= 0`.
+    // An unstreamed level 0 answers 0, not -1: `0x517fc0` pushes the raw field.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -208,7 +197,7 @@ fn unit_level_reads_minus_one_when_the_level_cant_be_told() {
 fn corpse_can_attack_and_green_range_bindings() {
     use crate::script::PlayerReqState;
     let mut s = UiScript::new().unwrap();
-    // UnitIsCorpse: a pure TYPEID_CORPSE object check (§5) — a DEAD unit is NOT a corpse…
+    // `UnitIsCorpse` is an object-type check (`0x5161c0`): a dead unit is not a corpse.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -220,7 +209,6 @@ fn corpse_can_attack_and_green_range_bindings() {
     assert!(s
         .eval::<bool>(r#"return UnitIsCorpse("target") == nil"#)
         .unwrap());
-    // …only a resolved corpse world object is.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -233,8 +221,7 @@ fn corpse_can_attack_and_green_range_bindings() {
         s.eval::<i64>(r#"return UnitIsCorpse("target")"#).unwrap(),
         1
     );
-    // UnitCanAttack reads the app-fed 0x606980 verdict off the non-player token, both
-    // argument orders; false → nil.
+    // `UnitCanAttack` reads the non-player token's verdict in either argument order.
     assert!(s
         .eval::<bool>(r#"return UnitCanAttack("player", "target") == nil"#)
         .unwrap());
@@ -259,8 +246,7 @@ fn corpse_can_attack_and_green_range_bindings() {
     assert!(s
         .eval::<bool>(r#"return UnitIsCorpse("target") == nil"#)
         .unwrap());
-    // GetQuestGreenRange: the grey band for the player's level — 4 at level 3, 9 at 46,
-    // 12 clamped past the table (the byte-verified GREY_BAND).
+    // `GetQuestGreenRange`: the grey band for the player's level, 12 past the table.
     for (pl, want) in [(3u32, 4i64), (46, 9), (120, 12)] {
         s.set_player_req_state(PlayerReqState {
             level: pl,
@@ -278,9 +264,8 @@ fn corpse_can_attack_and_green_range_bindings() {
 fn target_unit_queues_the_token_for_the_app_to_resolve() {
     use crate::script::SelectionRequest;
     let mut s = UiScript::new().unwrap();
-    // Nothing queued until a call lands.
     assert!(s.take_selection_requests().is_empty());
-    // Each call queues its raw token, in order; a nil token is ignored.
+    // A nil token is not queued.
     s.eval::<()>(r#"TargetUnit("player")"#).unwrap();
     s.eval::<()>(r#"TargetUnit("target")"#).unwrap();
     s.eval::<()>(r#"TargetUnit(nil)"#).unwrap();
@@ -291,14 +276,10 @@ fn target_unit_queues_the_token_for_the_app_to_resolve() {
             SelectionRequest::Unit("target".into()),
         ]
     );
-    // The drain is a take — a second read is empty.
     assert!(s.take_selection_requests().is_empty());
 }
 
-/// The three verbs share ONE queue, and the queue keeps their call order — which is the whole
-/// reason it is one queue (`0x489a40` is one function for all of them, and a macro can observe
-/// the order). A nil `AssistUnit` argument is dropped like `TargetUnit`'s, and
-/// `TargetLastEnemy()` names no unit at all.
+/// A nil `AssistUnit` argument is dropped like `TargetUnit`'s.
 #[test]
 fn the_selection_queue_carries_all_three_verbs_in_call_order() {
     use crate::script::SelectionRequest;
@@ -318,9 +299,8 @@ fn the_selection_queue_carries_all_three_verbs_in_call_order() {
     assert!(s.take_selection_requests().is_empty());
 }
 
-/// `TargetNearestFriend`'s reverse flag, read exactly as `0x6f1c10(idx 1, default 0)` does:
-/// absent or nil is forward, and 1.12's own `Bindings.xml` note — *"1 (or \"true\") means
-/// reverse!"* — is why a boolean and a number both count. A numeric `0` is forward.
+/// The reverse flag as `0x6f1c10` reads it: absent, nil and 0 are forward, 1 and `true` reverse
+/// (`Bindings.xml:458`).
 #[test]
 fn target_nearest_friend_queues_its_reverse_flag() {
     let mut s = UiScript::new().unwrap();
@@ -361,8 +341,6 @@ fn set_unit_is_read_by_the_bindings() {
 #[test]
 fn absent_token_reports_not_existing_with_zero_numbers() {
     let s = UiScript::new().unwrap();
-    // **nil, not `false`** — the family's false leg (decision 2043). `== nil` is the comparison a
-    // boolean would invert, so it is the one worth asserting.
     assert!(s
         .eval::<bool>(r#"return UnitExists("target") == nil"#)
         .unwrap());
@@ -398,21 +376,17 @@ fn a_dead_unit_reports_dead_and_zero_health() {
     assert_eq!(s.eval::<i64>(r#"return UnitExists("target")"#).unwrap(), 1);
     assert_eq!(s.eval::<i64>(r#"return UnitIsDead("target")"#).unwrap(), 1);
     assert_eq!(s.eval::<i64>(r#"return UnitHealth("target")"#).unwrap(), 0);
-    // Name unknown (no name-query yet) → `UNKNOWNOBJECT`, never nil: the unit RESOLVED, and the
-    // reference pushes nil for a zero GUID only (decision 2002; the shape is pinned below). A bare
-    // VM carries no GlobalStrings, so this is the binary's own literal.
+    // A resolved unit with no name yet reads `UNKNOWNOBJECT`, never nil; a bare VM has no
+    // GlobalStrings, so this is the literal fallback.
     assert_eq!(
         s.eval::<String>(r#"return UnitName("target")"#).unwrap(),
         "Unknown Being"
     );
 }
 
-/// `UnitName`'s value 1 is nil in exactly two cases — a zero GUID, and the `"player"` fast path
-/// over an empty local-name buffer — and a STRING everywhere else: the cached name, or
-/// `FrameScript_GetText("UNKNOWNOBJECT")` for a unit that resolved but whose name the cache has not
-/// answered (`0x517020` §2.1; `0x609324`). The stock stable window concatenates the answer on
-/// `UNIT_PET` (`PetStable.lua:129`), the instant a called pet's name is still in flight — the
-/// director's `attempt to concatenate a nil value` dialog (decision 2002).
+/// `UnitName` (`0x517020`) is nil only for a zero guid or an empty `"player"` record, else a
+/// string: the name, or `UNKNOWNOBJECT` while it is in flight (`0x609324`). `PetStable.lua:129`
+/// concatenates it on `UNIT_PET`, before a called pet's name arrives.
 #[test]
 fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
     let mut s = UiScript::new().unwrap();
@@ -426,24 +400,23 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
     };
     s.set_unit("pet", Some(pending.clone()));
 
-    // No GlobalStrings loaded: the literal the binary falls back to (`0x860fa4`).
+    // No GlobalStrings: the literal fallback (`0x860fa4`).
     assert_eq!(
         s.eval::<String>(r#"return UnitName("pet")"#).unwrap(),
         "Unknown Being"
     );
-    // With the stock global seated, its (localizable) value — read out of the VM, not baked in.
     s.run(r#"UNKNOWNOBJECT = "Unknown""#).unwrap();
     assert_eq!(
         s.eval::<String>(r#"return UnitName("pet")"#).unwrap(),
         "Unknown"
     );
-    // An EMPTY global is the same miss as an absent one (`0x609324`'s empty check).
+    // An empty global is the same miss as an absent one.
     s.run(r#"UNKNOWNOBJECT = """#).unwrap();
     assert_eq!(
         s.eval::<String>(r#"return UnitName("pet")"#).unwrap(),
         "Unknown Being"
     );
-    // Still two returns, the second nil (1840).
+    // Two returns, the realm nil.
     assert_eq!(
         s.eval::<i64>(r#"local t = {UnitName("pet")}; return table.getn(t)"#)
             .unwrap(),
@@ -454,7 +427,6 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
         .eval::<bool>(r#"local _, realm = UnitName("pet"); return realm == nil"#)
         .unwrap());
 
-    // The name lands: the string, and nothing else changes.
     let mut named = pending.clone();
     named.name = Some("Snarl".into());
     s.set_unit("pet", Some(named));
@@ -463,7 +435,7 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
         "Snarl"
     );
 
-    // The `"player"` fast path never reaches the resolver: an empty local-name buffer is nil.
+    // `"player"` reads the record, never the snapshot: an empty record is nil.
     s.set_unit("player", Some(pending));
     assert!(s
         .eval::<bool>(r#"return UnitName("player") == nil"#)
@@ -472,7 +444,7 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
         .eval::<bool>(r#"return UnitName("PLAYER") == nil"#)
         .unwrap());
 
-    // A token nothing resolves is GUID 0 → nil (the shape `absent_token_…` pins too).
+    // A token that resolves nothing is guid 0: nil.
     assert!(s
         .eval::<bool>(r#"return UnitName("target") == nil"#)
         .unwrap());
@@ -482,8 +454,7 @@ fn unitname_reads_unknownobject_for_a_resolved_unit_whose_name_is_in_flight() {
 fn power_bindings_read_the_active_type() {
     let mut s = UiScript::new().unwrap();
     s.set_unit("player", Some(player())); // rage 35/100
-                                          // ONE value. The Era `(type, "RAGE")` pair does not exist in 5875 — `0x517940` pushes a
-                                          // number at every one of its four live `ret`s and never a string (decision 1840).
+                                          // One value: `0x517940` pushes a number, never a string.
     assert_eq!(
         s.eval::<i64>(r#"return UnitPowerType("player")"#).unwrap(),
         1
@@ -493,19 +464,14 @@ fn power_bindings_read_the_active_type() {
         s.eval::<i64>(r#"return UnitManaMax("player")"#).unwrap(),
         100
     );
-    // **The 1.12 verbs take one argument and report the ACTIVE power**, whatever it is — this
-    // unit is a rage user and `UnitMana` reads 35 rage, which looks wrong and is exactly right
-    // (`UnitFrame.lua`: `local currValue = UnitMana(unit)` for every power type). Asking about a
-    // specific type is `UnitPowerType(unit)` first; there is no second argument to pass, and the
-    // Era pair that had one is gone (decision 1190's beyond-1.12 list, 1188 phase 5).
+    // `UnitMana` reports the active power, here rage, as `UnitFrame.lua:218` reads it for every
+    // type; `UnitPower` and `UnitPowerMax` are not 1.12 verbs.
     assert!(
         s.eval::<bool>("return UnitPower == nil and UnitPowerMax == nil")
             .unwrap(),
         "the Era spellings must not linger beside the 1.12 ones"
     );
-    // An absent unit: the NUMBER 0 — the same value Mana has, and never nil. Load-bearing rather
-    // than tidy: stock `UnitFrame.lua:122` writes `ManaBarColor[UnitPowerType(unitFrame.unit)]`,
-    // and a nil there indexes nothing.
+    // An absent unit is the number 0, never nil: `UnitFrame.lua:122` indexes `ManaBarColor` by it.
     assert_eq!(
         s.eval::<i64>(r#"return UnitPowerType("target")"#).unwrap(),
         0
@@ -515,7 +481,6 @@ fn power_bindings_read_the_active_type() {
 #[test]
 fn get_money_reads_the_pushed_purse() {
     let mut s = UiScript::new().unwrap();
-    // No feed yet: 0 copper.
     assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 0);
     s.set_money(123_456);
     assert_eq!(s.eval::<i64>("return GetMoney()").unwrap(), 123_456);
@@ -524,7 +489,6 @@ fn get_money_reads_the_pushed_purse() {
 #[test]
 fn unit_xp_reads_the_player_globals_only_for_the_player_token() {
     let mut s = UiScript::new().unwrap();
-    // No feed yet: 0/0.
     assert_eq!(s.eval::<i64>(r#"return UnitXP("player")"#).unwrap(), 0);
     assert_eq!(s.eval::<i64>(r#"return UnitXPMax("player")"#).unwrap(), 0);
     s.set_player_xp(4200, 6000);
@@ -533,7 +497,6 @@ fn unit_xp_reads_the_player_globals_only_for_the_player_token() {
         s.eval::<i64>(r#"return UnitXPMax("player")"#).unwrap(),
         6000
     );
-    // Any non-player token reports 0 (no creature/other unit exposes XP — the live shape).
     assert_eq!(s.eval::<i64>(r#"return UnitXP("target")"#).unwrap(), 0);
     assert_eq!(s.eval::<i64>(r#"return UnitXPMax("target")"#).unwrap(), 0);
 }
@@ -579,7 +542,6 @@ fn party_frame_predicates_report_1_or_nil() {
         .eval::<bool>(r#"return UnitIsPVPFreeForAll("party1") == nil"#)
         .unwrap());
 
-    // Flip every flag: the false/true cases aren't just "always true".
     s.set_unit(
         "party1",
         Some(UnitState {
@@ -608,7 +570,6 @@ fn party_frame_predicates_report_1_or_nil() {
         1
     );
 
-    // An absent token reports nil regardless of any flag's zero value.
     assert!(s
         .eval::<bool>(r#"return UnitIsConnected("party2") == nil"#)
         .unwrap());
@@ -629,11 +590,7 @@ fn unit_race_class_sex_report_the_snapshot_or_the_absent_shape() {
         ("Warrior".into(), "WARRIOR".into())
     );
     assert_eq!(s.eval::<i64>(r#"return UnitSex("player")"#).unwrap(), 3);
-    // An absent token: the two string pairs go nil, nil — but **`UnitSex` answers the number 2**,
-    // not nil. It is a numeric getter, and `0x517f9f` pushes the constant double 2.0 on the
-    // unresolved leg exactly as `UnitLevel`/`UnitMana`/`GetMoney` push 0.0 on theirs (wow-re
-    // `unit-predicate-return-shape.md` §4; decision 2118). The shapes table has no nil alternative
-    // for this row at all.
+    // An absent token: `nil, nil` for the pairs, but `UnitSex` answers the number 2 (`0x517f9f`).
     assert!(s
         .eval::<bool>(r#"local a, b = UnitRace("target") return a == nil and b == nil"#)
         .unwrap());
@@ -641,7 +598,6 @@ fn unit_race_class_sex_report_the_snapshot_or_the_absent_shape() {
         .eval::<bool>(r#"local a, b = UnitClass("target") return a == nil and b == nil"#)
         .unwrap());
     assert_eq!(s.eval::<i64>(r#"return UnitSex("target")"#).unwrap(), 2);
-    // A snapshot whose race/class haven't resolved yet (feed pending): same nils.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -652,13 +608,11 @@ fn unit_race_class_sex_report_the_snapshot_or_the_absent_shape() {
     assert!(s
         .eval::<bool>(r#"local a, b = UnitRace("target") return a == nil and b == nil"#)
         .unwrap());
-    // Same for a seated body whose sex byte has not streamed: the number 2, never nil.
+    // An unstreamed sex byte reads 2 too.
     assert_eq!(s.eval::<i64>(r#"return UnitSex("target")"#).unwrap(), 2);
 }
 
-/// `UnitFactionGroup` returns the (english, localized) pair the PvP-icon law reads, and `nil, nil`
-/// for a unit with no side — the state the reference's `if ( factionGroup and … )` gate exists
-/// for (decision 0646 §1). `TogglePVP` queues one toggle per call.
+/// `UnitFactionGroup` answers (English, localized), or `nil, nil` for a unit with no side.
 #[test]
 fn faction_group_pair_and_the_pvp_toggle() {
     let mut s = UiScript::new().unwrap();
@@ -673,17 +627,11 @@ fn faction_group_pair_and_the_pvp_toggle() {
     let (english, localized) = s
         .eval::<(String, String)>(r#"return UnitFactionGroup("target")"#)
         .unwrap();
-    // With no localized name fed, the second return falls back to the English one rather than nil:
-    // FactionGroup.dbc leaves `Name0` empty for some rows, and nil here would blank a tooltip the
-    // reference fills.
+    // With no localized name fed, the second return falls back to the English one, not nil.
     assert_eq!((english.as_str(), localized.as_str()), ("Horde", "Horde"));
 
-    // **The two halves are DIFFERENT fields and this is the assertion that says so.** They are
-    // FactionGroup.dbc's `InternalName` and `Name0`; only on enUS do they hold the same word, which
-    // is why returning one twice went unnoticed. The first is concatenated into a texture path by
-    // every stock consumer (`"…\UI-PVP-"..factionGroup` — PlayerFrame.lua:68, TargetFrame.lua:198,
-    // PartyMemberFrame.lua:125; `"…\Battleground-"..` — BattlefieldFrame.lua:195), so a localized
-    // string there names a file that does not exist. This fixture is a deDE-shaped client.
+    // A deDE-shaped client: the halves are `InternalName` and `Name0`, and stock builds texture
+    // paths from the English first (`TargetFrame.lua:198`, `BattlefieldFrame.lua:195`).
     s.set_unit(
         "target",
         Some(UnitState {
@@ -702,7 +650,6 @@ fn faction_group_pair_and_the_pvp_toggle() {
         "the FIRST return is the English InternalName — a texture path is built from it"
     );
 
-    // No side (a Monster/neutral template, or a unit whose template hasn't streamed).
     s.set_unit(
         "target",
         Some(UnitState {
@@ -714,9 +661,7 @@ fn faction_group_pair_and_the_pvp_toggle() {
     assert!(s
         .eval::<bool>(r#"local a, b = UnitFactionGroup("target") return a == nil and b == nil"#)
         .unwrap());
-    // An absent unit answers the same way. (This read `"focus"` until the unrecognised-token raise
-    // landed — a token 1.12 does not have at all, so it now raises rather than being "absent". The
-    // question the line means to ask needs a RECOGNISED token that names nothing.)
+    // An absent unit, a recognised token naming nothing, answers the same.
     assert!(s
         .eval::<bool>(r#"local a = UnitFactionGroup("party4") return a == nil"#)
         .unwrap());
@@ -731,9 +676,8 @@ fn faction_group_pair_and_the_pvp_toggle() {
     assert_eq!(s.take_pvp_toggles(), 0, "the drain empties the queue");
 }
 
-/// `UnitClassification` (decision 0782, byte-verified table `0x850424`): five words indexed by the
-/// gated rank, a STRING for every input — including an absent token, which the binary answers
-/// `"normal"` for (its unresolved path loads index 0), never nil.
+/// The word table at `0x850424` by gated rank answers a string for every input: an absent token
+/// reads index 0, "normal", never nil.
 #[test]
 fn unit_classification_reads_the_five_word_table() {
     let mut s = UiScript::new().unwrap();
@@ -761,9 +705,6 @@ fn unit_classification_reads_the_five_word_table() {
         );
     }
 
-    // No snapshot at all, and a missing argument: still "normal", never nil. The target frame's
-    // border branch compares this against string literals, so a nil here would be a Lua error the
-    // reference cannot produce.
     s.set_unit("target", None);
     assert_eq!(
         s.eval::<String>(r#"return UnitClassification("target")"#)
@@ -780,9 +721,8 @@ fn unit_classification_reads_the_five_word_table() {
 
 // ── `UnitAffectingCombat` and `TargetByName` ────────────────────────────────────────────────────
 
-/// `UnitAffectingCombat` → the number 1 / nil, and **one arm serves both "not in combat" and "no
-/// such unit"** (`0x517e48` and `0x517e5c` jump to the same `0x517e73`). That indistinguishability
-/// is the behaviour, not a shortcut: an addon must not be able to probe existence with this verb.
+/// Not in combat and no such unit share one nil arm: `0x517e48` and `0x517e5c` both jump to
+/// `0x517e73`.
 #[test]
 fn unit_affecting_combat_is_one_or_nil_and_hides_the_missing_unit() {
     let mut s = UiScript::new().unwrap();
@@ -805,20 +745,14 @@ fn unit_affecting_combat_is_one_or_nil_and_hides_the_missing_unit() {
             .unwrap(),
         "an unresolvable token is the SAME nil a peaceful unit gives"
     );
-    // **A number is accepted and stringified — and that is exactly why it RAISES.** The gate
-    // `0x6f3510` is number-OR-string, so `5` is coerced via `%.14g` to the token `"5"`; `"5"` then
-    // matches none of the resolver's nine prefixes and falls into
-    // `luaL_error("Unknown unit name: %s")`. This assertion read `== nil` and "it does not raise"
-    // until wow-re's own §5 cross-check refuted the no-error-path claim it rested on
-    // (`raid-roster-bindings.md` §1) — the acceptance was right, the conclusion was not.
+    // A number passes the gate (`0x6f3510`) as the token "5", which matches no prefix and raises.
     assert!(
         s.run("UnitAffectingCombat(5)").is_err(),
         "a number is coerced to a token that matches nothing, so it raises"
     );
 }
 
-/// A missing or wrong-typed argument **raises** — `0x6f4940` is `luaL_error` and does not return,
-/// so the caller's statement is abandoned rather than continuing with a nil.
+/// The usage raise is `luaL_error` (`0x6f4940`), which does not return.
 #[test]
 fn unit_affecting_combat_raises_on_a_bad_argument() {
     let s = UiScript::new().unwrap();
@@ -833,8 +767,8 @@ fn unit_affecting_combat_raises_on_a_bad_argument() {
     }
 }
 
-/// `TargetByName(name [, exactMatch])` queues the name **and the second argument** — the flag the
-/// slash command has no way to supply, which turns the resolver's longest-common-prefix tier off.
+/// `exactMatch`, which the slash command cannot pass, turns off the resolver's
+/// longest-common-prefix tier.
 #[test]
 fn target_by_name_queues_the_name_and_the_exact_flag() {
     let mut s = UiScript::new().unwrap();
@@ -857,7 +791,7 @@ fn target_by_name_queues_the_name_and_the_exact_flag() {
     );
     assert!(s.take_target_by_name_requests().is_empty());
 
-    // A missing/wrong-typed name raises (`0x489d69 call 0x6f3510` → `0x489de1`).
+    // A missing name raises: the gate call at `0x489d69` fails to `0x489de1`.
     let err = s.eval::<mlua::Value>("return TargetByName()").unwrap_err();
     assert!(
         format!("{err}").contains(r#"Usage: TargetByName("name")"#),
@@ -865,12 +799,7 @@ fn target_by_name_queues_the_name_and_the_exact_flag() {
     );
 }
 
-/// **`UnitIsCharmed` — the number `1`, the nil, and the asymmetry.**
-///
-/// `KLHThreatMeter\Code\KTM_My.lua:533` is the corpus line blocked on it; seven other addons name
-/// it. The binding (`0x516cf0`) reads `UNIT_FIELD_CHARMEDBY != 0` — a 64-bit non-zero test on
-/// fields 10/11, **not** a `UNIT_FIELD_FLAGS` bit, which is what a boolean-shaped unit question
-/// invites you to assume.
+/// `0x516cf0` tests `UNIT_FIELD_CHARMEDBY` (fields 10-11) non-zero, not a `UNIT_FIELD_FLAGS` bit.
 #[test]
 fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
     let mut s = UiScript::new().unwrap();
@@ -879,8 +808,6 @@ fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
     mc.charmed = true;
     s.set_unit("target", Some(mc));
 
-    // A hit is the NUMBER 1 — `lua_pushnumber` writes tag 3; tag 1 (boolean) is never written on
-    // either arm, so `== true` in an addon must NOT match.
     assert_eq!(
         s.eval::<i64>(r#"return UnitIsCharmed("target")"#).unwrap(),
         1
@@ -897,7 +824,6 @@ fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
         "exactly one value on the hit path"
     );
 
-    // An uncharmed unit and an absent one both answer nil — and nil, not `false` and not `0`.
     for token in ["player", "party1"] {
         assert!(
             s.eval::<Option<i64>>(&format!(r#"return UnitIsCharmed("{token}")"#))
@@ -913,8 +839,6 @@ fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
         );
     }
 
-    // **The asymmetry.** The field is "who charms me", never "whom I charm", so the charmer reads
-    // nil while its victim reads 1 — here the player is doing the charming and is not charmed.
     assert!(
         s.eval::<Option<i64>>(r#"return UnitIsCharmed("player")"#)
             .unwrap()
@@ -923,20 +847,8 @@ fn unit_is_charmed_answers_one_or_nil_and_only_for_the_charmed_side() {
     );
 }
 
-/// **`UnitIsPlusMob` reads a FLAG BIT, not the creature rank** (B385; `0x516d40`).
-///
-/// Decision 2209. The name says "elite" and its table neighbour `UnitClassification` answers off
-/// the gated rank, so the natural implementation is `rank > 0`. The binary's is not: it takes
-/// `UNIT_FIELD_FLAGS` and tests bit 6 (`UNIT_FLAG_PLUS_MOB 0x40`), never calling the rank getter
-/// `0x605620` (wow-re `9f84e7e4`,
-/// `system/ui/scratch/unit-verbs-controlled-charmed-creaturetype.md` §4.2). The two normally
-/// agree because the server derives the bit from the rank — so **rare** answers 1 here, not just
-/// elite — and they part on the unit whose creature-cache record has not arrived, which still
-/// carries its own flags while its rank reads 0.
-///
-/// That divergence is the whole reason this is a test and not a reading: a `rank > 0`
-/// implementation passes every ordinary case and is wrong exactly where the flag is the only
-/// thing the client has.
+/// `0x516d40` tests `UNIT_FLAG_PLUS_MOB` (`0x40`) and never the rank getter (`0x605620`). The
+/// server sets the bit from the rank, so the two part only while the creature record is missing.
 #[test]
 fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
     let with = |flags: u32, rank: u32| UnitState {
@@ -949,8 +861,7 @@ fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
     let mut s = UiScript::new().unwrap();
     s.set_unit("player", Some(player()));
 
-    // The ordinary agreeing cases: the server sets the bit on `!IsPet() && rank > 0`, so elite,
-    // rare-elite, world boss AND rare all carry it, and a normal mob does not.
+    // The server sets the bit on `!IsPet() && rank > 0` (`Creature.h:185`), so rare carries it.
     for (rank, word) in [
         (1u32, "elite"),
         (2, "rareelite"),
@@ -972,16 +883,14 @@ fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
         "a normal mob answers nil"
     );
 
-    // ── The two legs a rank read gets wrong ──
-    // The flag WITHOUT a rank: an unstreamed creature, whose cache record has not arrived, still
-    // has its own descriptor. `rank > 0` would call it normal; the client says 1.
+    // The flag without a rank: a creature whose cache record has not arrived.
     s.set_unit("target", Some(with(0x40, 0)));
     assert_eq!(
         s.eval::<i64>(r#"return UnitIsPlusMob("target")"#).unwrap(),
         1,
         "the bit alone decides — no creature-cache rank is consulted"
     );
-    // A rank WITHOUT the flag — a player's pet, which the server excludes (`!IsPet()`).
+    // A rank without the flag: a pet, which the server excludes.
     s.set_unit("target", Some(with(0x8, 2)));
     assert!(
         s.eval::<Option<i64>>(r#"return UnitIsPlusMob("target")"#)
@@ -990,9 +899,8 @@ fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
         "no bit, no plus mob — a neighbouring flag (player-controlled) must not read as one"
     );
 
-    // The token grammar: quiet on nil/absent (one of 1834's thirteen with no `lua_isstring`
-    // gate), quiet on a recognised token naming nothing, and a raise on an unrecognised one —
-    // the body reaches the shared resolver through `0x515940`.
+    // One of the 13 with no `lua_isstring` gate: nil is quiet, and an unrecognised token raises
+    // through the resolver (`0x515940`).
     assert!(s.run("UnitIsPlusMob()").is_ok(), "nil token stays quiet");
     assert!(
         s.run("UnitIsPlusMob(nil)").is_ok(),
@@ -1011,17 +919,7 @@ fn unit_is_plus_mob_reads_the_flag_bit_and_not_the_rank() {
     );
 }
 
-/// **Unit tokens fold case, because the client's resolver does.**
-///
-/// `0x515970` compares every one of its literals with `SStrCmpI` → `_strnicmp`, whose fold is
-/// `'A'..'Z' += 0x20`; not one of its ten compares reaches the case-sensitive sibling (wow-re
-/// `system/ui/scratch/unit-token-grammar.md`, §5 trio). So this is a NARROWING fix — the real
-/// client resolves these and we did not — rather than the superset 1189 had to take back out.
-///
-/// `Accountant.lua:107` is the corpus line that paid for it: `UnitFactionGroup("Player")`, capital
-/// P, whose nil made `Accountant_SaveData[realm][faction]` a nil table index at l.192 and ended the
-/// addon's session. Roughly ten addons pass `Player`, `PLAYER`, `Target`, `Pet`, `PARTY`, `NPC`,
-/// `Mouseover` or `"Raid"..i`.
+/// The resolver (`0x515970`) compares every literal with `_strnicmp`, folding ASCII case.
 #[test]
 fn a_unit_token_resolves_whatever_its_case() {
     let mut s = UiScript::new().unwrap();
@@ -1030,7 +928,6 @@ fn a_unit_token_resolves_whatever_its_case() {
     tgt.name = Some("Hogger".into());
     s.set_unit("target", Some(tgt));
 
-    // Every spelling names the same unit — the getter, the number and the predicate alike.
     for spelling in ["player", "Player", "PLAYER", "PlAyEr"] {
         assert_eq!(
             s.eval::<String>(&format!(r#"return UnitName("{spelling}")"#))
@@ -1057,10 +954,8 @@ fn a_unit_token_resolves_whatever_its_case() {
         );
     }
 
-    // **The two-unit call, which the map's fold does not cover on its own.**
-    // `pick_unit_token` chooses "whichever arg is not the player"; with a case-sensitive test,
-    // `("Player", "target")` reads as a non-player FIRST arg and the call answers about the wrong
-    // unit — a wrong answer rather than a missing one.
+    // `pick_unit_token`'s own `"player"` test folds too, or `"Player"` would read as the other
+    // unit.
     assert!(
         s.eval::<bool>(
             r#"return UnitIsEnemy("Player", "target") == UnitIsEnemy("player", "target")"#
@@ -1069,9 +964,6 @@ fn a_unit_token_resolves_whatever_its_case() {
         "the directional pick folds case too"
     );
 
-    // An unseated but RECOGNISED token is still absent whatever its case — folding must not invent
-    // units. (`bogus` moved out of this list when the unrecognised-token raise landed: it is not
-    // "absent", it is not a unit token at all, and the client says so.)
     for spelling in ["Party1", "PARTY1", "raid9", "MouseOver"] {
         assert!(
             !s.eval::<bool>(&format!(r#"return UnitExists("{spelling}")"#))
@@ -1081,8 +973,7 @@ fn a_unit_token_resolves_whatever_its_case() {
     }
 }
 
-/// The fold is on the way **IN** as well as out: a feed that pushes `"Target"` must not create a
-/// second entry shadowing `"target"`, which is what a lookup-only fold would allow.
+/// A `"Target"` push must not create an entry shadowing `"target"`.
 #[test]
 fn seating_a_token_folds_its_key_too() {
     let mut s = UiScript::new().unwrap();
@@ -1095,7 +986,6 @@ fn seating_a_token_folds_its_key_too() {
         "a token seated as \"Target\" is readable as \"target\""
     );
 
-    // …and clearing it through the other spelling really clears it, rather than leaving a shadow.
     s.set_unit("TARGET", None);
     assert!(
         s.eval::<bool>(r#"return UnitExists("target") == nil"#)
@@ -1104,21 +994,12 @@ fn seating_a_token_folds_its_key_too() {
     );
 }
 
-/// **An unrecognised token RAISES; a recognised one that names nothing is a quiet nil.**
-///
-/// `0x515970` falls off the end of its nine compares into `luaL_error(L, "Unknown unit name: %s")`,
-/// which longjmps and never returns (wow-re `system/ui/scratch/unit-token-grammar.md`). Ours
-/// answered nil for everything unknown — 1203's shape pointed the other way, a failure the client
-/// reports and we swallowed.
-///
-/// The split is THREE-way, and the two quiet legs are the ones a "raise on nil" implementation gets
-/// wrong.
+/// `0x515970` ends its nine compares in `luaL_error(L, "Unknown unit name: %s")`.
 #[test]
 fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
     let mut s = UiScript::new().unwrap();
     s.set_unit("player", Some(player()));
 
-    // RAISE: nothing the resolver's compares match.
     for bogus in ["bogus", "focus", "boss1", "arena1"] {
         let err = s
             .run(&format!(r#"UnitName("{bogus}")"#))
@@ -1129,12 +1010,10 @@ fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
             "the raise carries the client's own text and the offending token: {err}"
         );
     }
-    // `npc` is the SOLE full-string compare, so a suffix on it matches nothing at all.
+    // `npc` is the one full-string compare, so a suffix on it matches nothing.
     assert!(s.run(r#"UnitName("npctarget")"#).is_err());
-    // …while `npc` itself is recognised, folded like everything else.
     assert!(s.run(r#"UnitName("NPC")"#).is_ok());
 
-    // QUIET NIL, leg 1: a recognised token naming nothing here.
     for absent in [
         "party5",
         "raid17",
@@ -1150,8 +1029,7 @@ fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
             "{absent} is recognised and absent — nil, not a raise"
         );
     }
-    // QUIET NIL, leg 2: a recognised PREFIX with a junk suffix. The compares are prefix tests that
-    // stop at either NUL, so `playerfoo` matches `player` and never reaches the raise.
+    // A recognised prefix with a suffix is quiet too: the compares stop at either NUL.
     for junk in ["playerfoo", "raidx", "petx", "targetish"] {
         assert!(
             s.eval::<Option<String>>(&format!(r#"return UnitName("{junk}")"#))
@@ -1161,26 +1039,21 @@ fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
              implementation that raises on \"did not resolve\" gets wrong."
         );
     }
-    // QUIET NIL, leg 3: the empty string — which passes the `lua_isstring` gate (it IS a string)
-    // and dies quietly in the resolver's own NULL/empty guard.
+    // Quiet nil: the empty string passes the `lua_isstring` gate and stops at the resolver's
+    // empty guard.
     assert!(s.run(r#"UnitName("")"#).is_ok());
 
-    // …but an ABSENT or nil argument is NOT leg 3, and this line used to assert that it was.
-    // `UnitName 0x517020` gates its token position at `0x517048` and raises
-    // `Usage: UnitName("unit")` (`0x850ee0`); `luaL_error` does not return. The comment this
-    // replaces said the per-binding gates were "not uniform … only two poles verified", which was
-    // true when it was written — wow-re has since censused all 83 entries of the table at
-    // `0x850438`: 53 gate and raise, and only 13 unit-token bindings are quiet. Decision 1834.
+    // An absent or nil argument raises `Usage: UnitName("unit")` (`0x850ee0`) from `UnitName`'s
+    // own gate (`0x517048`).
     assert!(s.run("UnitName()").is_err(), "absent argument raises");
     assert!(s.run("UnitName(nil)").is_err(), "nil argument raises");
-    // A NUMBER passes the gate — `lua_isstring` admits tag 3 — and is handed to the resolver as
-    // "5", which then raises the family's OTHER message rather than the `Usage:` one.
+    // A number passes the gate as "5" and raises the resolver's message instead.
     assert!(
         s.run("UnitName(5)").is_err(),
         "a number reaches the resolver"
     );
 
-    // The thirteen that stay quiet, three of them here: no gate at all, so nil is fine.
+    // Three of the 13 with no gate, where nil is quiet.
     for quiet in ["UnitExists", "UnitIsVisible", "UnitClassification"] {
         assert!(
             s.run(&format!("{quiet}()")).is_ok(),
@@ -1188,30 +1061,20 @@ fn an_unrecognised_unit_token_raises_and_a_recognised_empty_one_does_not() {
         );
     }
 
-    // A two-unit call gates BOTH arguments.
+    // A two-unit call checks both tokens.
     assert!(s.run(r#"UnitIsUnit("player", "bogus")"#).is_err());
     assert!(s.run(r#"UnitIsUnit("bogus", "player")"#).is_err());
     assert!(s.run(r#"UnitIsUnit("player", "party3")"#).is_ok());
 }
 
-/// **A multibyte unit token must not take the client down.**
-///
-/// The prefix test used to slice the token as a `&str` — `token[..p.len()]` — which PANICS when the
-/// token is multibyte UTF-8 and the prefix length lands mid-character ("byte index N is not a char
-/// boundary"). Any addon passing a non-ASCII token would have crashed the process rather than
-/// getting the `Unknown unit name` raise the client gives.
-///
-/// The client compares with `_strnicmp` over BYTES and folds ASCII only, so byte comparison is both
-/// the safe form and the faithful one — a token whose bytes differ above 0x7F is simply not one of
-/// the nine prefixes.
+/// The resolver compares bytes with an ASCII fold, so a non-ASCII token matches no prefix and
+/// raises, where slicing it as a `str` would panic mid-character.
 #[test]
 fn a_multibyte_unit_token_raises_rather_than_panicking() {
     let mut s = UiScript::new().unwrap();
     s.set_unit("player", Some(player()));
 
-    // Each of these has a multibyte character positioned so that a byte-index slice at one of the
-    // prefix lengths (3 for `pet`, 4 for `raid`, 5 for `party`, 6 for `player`/`target`) would land
-    // inside it.
+    // Each puts a multibyte character across a prefix length: 3, 4, 5 or 6 bytes.
     for token in ["pé", "раid", "playér", "targét", "мышь", "日本語のトークン"] {
         let err = s
             .run(&format!(r#"UnitName("{token}")"#))
@@ -1222,7 +1085,6 @@ fn a_multibyte_unit_token_raises_rather_than_panicking() {
             "it must RAISE, not panic and not answer: {err}"
         );
     }
-    // …and an ASCII token that merely shares a prefix's leading bytes still behaves.
     assert!(s
         .eval::<Option<String>>(r#"return UnitName("playerfoo")"#)
         .unwrap()
@@ -1233,25 +1095,12 @@ fn a_multibyte_unit_token_raises_rather_than_panicking() {
     );
 }
 
-/// **`UnitIsVisible` is object presence, and it is NOT `UnitExists`** — the pair an out-of-range
-/// party member separates, and the branch pfUI takes seven times.
-///
-/// `0x516030` is 57 bytes with one branch:
-/// `ClntObjMgrObjectPtr(resolve(token), TYPEMASK_UNIT) != NULL`. No field read, no comparison
-/// beyond `test eax,eax`, no float opcode — so no distance, no radius, no visibility flag. The
-/// range test is the *server's*: the out-of-range demotion unlinks the object from the very
-/// manager index this query searches (wow-re `ui/scratch/unitisvisible-object-presence.md`).
-///
-/// The state that backs it is [`UnitState::has_object`], which `ui_party::feed`'s
-/// `member_unit_state` has always branched on — its `store: Option<&ObjectStore>` argument, whose
-/// own comment names `0x468460`. This test is what stops the two fields being conflated back
-/// together, because in every *in-range* case they agree and only the out-of-range one tells them
-/// apart.
+/// `0x516030` tests only that the client holds the object, so an out-of-range party member exists
+/// but is not visible.
 #[test]
 fn unit_is_visible_is_object_presence_not_existence() {
     let mut s = UiScript::new().unwrap();
 
-    // In range: the object is held, both answer yes.
     s.set_unit(
         "party1",
         Some(UnitState {
@@ -1266,9 +1115,7 @@ fn unit_is_visible_is_object_presence_not_existence() {
         "a held object is visible — and the return is the NUMBER 1, never a boolean"
     );
 
-    // **Out of range: the roster still has them, the object manager does not.** This is the row
-    // that matters; `exists` MUST stay true here, because that is what UnitExists's own GUID
-    // fallback answers, and folding the two fields into one would silently break it.
+    // Out of range: the roster has the member, the object manager does not.
     s.set_unit(
         "party1",
         Some(UnitState {
@@ -1289,7 +1136,7 @@ fn unit_is_visible_is_object_presence_not_existence() {
         "...and UnitExists must NOT have moved with it — the roster fallback is the difference"
     );
 
-    // pfUI's actual line (`unitframes.lua:1873`), which chooses a flat portrait over a 3D one.
+    // pfUI's portrait test (`api/unitframes.lua:1873`).
     assert!(
         s.eval::<bool>(
             r#"return (not UnitIsVisible("party1") or not UnitIsConnected("party1")) and true or false"#
@@ -1298,7 +1145,6 @@ fn unit_is_visible_is_object_presence_not_existence() {
         "the portrait branch fires for an out-of-range member"
     );
 
-    // A token with no snapshot at all: nil, via the same "no snapshot" path every predicate uses.
     assert_eq!(
         s.eval::<Option<i64>>(r#"return UnitIsVisible("party4")"#)
             .unwrap(),
@@ -1306,20 +1152,8 @@ fn unit_is_visible_is_object_presence_not_existence() {
     );
 }
 
-/// **The tapped pair, and the two ways it goes wrong.**
-///
-/// `UnitIsTapped 0x519c90` / `UnitIsTappedByPlayer 0x519d00` are a masked-byte pair — 108 bytes
-/// each, differing only in the `UNIT_DYNAMIC_FLAGS` mask (`0x4`/`0x8`, UpdateField 143) and the
-/// `Usage:` string. Each is `object present && (flags & mask)` and nothing else: no ownership, no
-/// GUID compare, no party/raid or health conjunct (wow-re
-/// `ui/scratch/tapped-bits-and-unit-faction.md`).
-///
-/// Asserted here because both are easy to get wrong in a way that still looks right:
-///
-/// - **Shape A, not shape C.** `UnitIsVisible` beside them has *no* `Usage:` raise; these two do.
-///   Inheriting the neighbour's shape would fail quietly, in the permissive direction.
-/// - **The pair is read as a conjunction.** `tapped && not tappedByPlayer` — someone *else's* kill
-///   — is the condition addons actually draw, and either bit alone says nothing useful.
+/// `0x519c90` and `0x519d00` test `UNIT_DYNAMIC_FLAGS` bits `0x4` and `0x8` behind object
+/// presence, and unlike `UnitIsVisible` both raise `Usage:` on a bad argument.
 #[test]
 fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
     let mut s = UiScript::new().unwrap();
@@ -1336,7 +1170,6 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
         );
     };
 
-    // Untapped: both nil.
     set(&mut s, false, false);
     assert_eq!(
         s.eval::<Option<i64>>(r#"return UnitIsTapped("target")"#)
@@ -1344,7 +1177,7 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
         None
     );
 
-    // Tapped by someone ELSE — the grey-bar case, pfUI `api/unitframes.lua:2012`.
+    // Tapped by someone else: the grey bar (pfUI `api/unitframes.lua:2012`).
     set(&mut s, true, false);
     assert_eq!(
         s.eval::<i64>(r#"return UnitIsTapped("target")"#).unwrap(),
@@ -1364,7 +1197,6 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
         "someone else's kill — the conjunction addons actually draw"
     );
 
-    // Tapped by ME: both set, so the grey-bar branch must NOT fire.
     set(&mut s, true, true);
     assert!(
         !s.eval::<bool>(
@@ -1374,8 +1206,8 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
         "my own tap is not greyed"
     );
 
-    // Object presence is a conjunct of BOTH: an out-of-range unit is neither, whatever the bits
-    // say — and the bits cannot even be read, because there is no descriptor to read them from.
+    // No object with the bit set, which the feed never builds: it sets `tapped` only from a live
+    // descriptor, so the binding reads the field as given.
     s.set_unit(
         "target",
         Some(UnitState {
@@ -1386,9 +1218,6 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
             ..Default::default()
         }),
     );
-    // (The feed can never build that combination — `ui_unit::snapshot` sets all three together —
-    // but the binding is asserted against it anyway, because a future feed that forgot would
-    // otherwise report a tapped unit the object manager does not hold.)
     assert_eq!(
         s.eval::<i64>(r#"return UnitIsTapped("target")"#).unwrap(),
         1,
@@ -1396,11 +1225,7 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
          assertion records which of the two owns it"
     );
 
-    // SHAPE A. `UnitIsVisible` next door has no `Usage:` raise; these do — and **nil is in the
-    // list**, which is the half that does not come free: the shared `check_unit_token` lets a nil
-    // through by design (right for `UnitExists` and `UnitIsVisible`, wrong for these two), so the
-    // gate has to live in the binding. This assertion is what found that; the original spelling
-    // used `print`, which is not defined in our VM and so was quietly testing nil all along.
+    // Shape A, nil included: `check_unit_token` lets nil through, so the gate is the binding's.
     for bad in ["{}", "true", "nil", "", "function() end"] {
         assert!(
             s.run(&format!("UnitIsTapped({bad})")).is_err(),
@@ -1413,28 +1238,15 @@ fn the_tapped_pair_is_two_masks_of_one_field_and_raises_on_a_bad_argument() {
     }
 }
 
-/// **`UnitIsPartyLeader` is two legs ORed, and the solo case answers 1.**
-///
-/// `0x516210` is
-///
-/// ```text
-/// o = ObjPtr(resolve(t), TYPEMASK_PLAYER)
-/// (o != NULL && (o.PLAYER_FLAGS & 0x1)) || resolve(t) == g_groupLeaderGuid
-/// ```
-///
-/// and it is **not** derivable from `IsPartyLeader()` + `GetPartyLeaderIndex()` however arranged —
-/// the two legs cover disjoint failures (wow-re
-/// `ui/scratch/party-leader-and-nameplate-verbs.md`, G1 REFUTED). Each leg is asserted with the
-/// other one dead, because either alone looks sufficient until the case it cannot reach.
+/// `0x516210`: the player object's `PLAYER_FLAGS & 0x1`, or the resolved guid is the group
+/// leader's; each leg is asserted with the other dead.
 #[test]
 fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
     let mut s = UiScript::new().unwrap();
     const ME: u64 = 0x1111;
     const THEM: u64 = 0x2222;
 
-    // ── LEG 1 alone: the descriptor flag, with the leader GUID matching nobody.
-    //    This is the leg that answers for a STRANGER who leads their own party — something no
-    //    comparison against our group's leader could ever express.
+    // Leg 1 alone: the flag, as on a stranger who leads their own party.
     s.set_party(PartyState {
         leader_guid: 0x9999,
         own_guid: 0,
@@ -1457,8 +1269,7 @@ fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
         "the server's PLAYER_FLAGS bit answers on its own"
     );
 
-    // ── LEG 2 alone: no descriptor flag, but the resolved GUID IS our leader. This is the
-    //    out-of-range member — the client holds no object, so leg 1 has nothing to read.
+    // Leg 2 alone: an out-of-range member, with no object to read, whose guid is our leader.
     s.set_party(PartyState {
         leader_guid: THEM,
         own_guid: 0,
@@ -1481,7 +1292,6 @@ fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
         "the GUID compare answers where there is no descriptor to read a flag from"
     );
 
-    // ── Neither leg: a grouped member who does not lead.
     s.set_unit(
         "party2",
         Some(UnitState {
@@ -1498,10 +1308,8 @@ fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
         None
     );
 
-    // ── **NO ZERO GUARD.** Ungrouped, the cached leader is 0 and an unresolvable-but-non-raising
-    //    token resolves to 0 — so they match and the answer is 1. `IsPartyLeader 0x4e9130`
-    //    short-circuits on a `0:0` leader and `0x516210` does not; that asymmetry is the finding,
-    //    and answering nil here would be the divergence, however much it reads like a bug.
+    // No zero guard: solo, the cached leader is 0 and an unresolved token is 0, so the answer is
+    // 1; `IsPartyLeader` (`0x4e9130`) guards a zero leader, `0x516210` does not.
     s.set_party(PartyState::default());
     assert_eq!(
         s.eval::<i64>("return UnitIsPartyLeader(nil)").unwrap(),
@@ -1515,16 +1323,11 @@ fn unit_is_party_leader_ors_two_legs_and_answers_one_when_solo() {
         "...and so does a token with no snapshot, by the same route"
     );
 
-    // A bad token still raises through the shared resolver — shape C with a shape-A tail.
     assert!(s.run(r#"UnitIsPartyLeader("notatoken")"#).is_err());
 }
 
-/// `UnitHasRelicSlot` — the number 1 or nil, per token, never a boolean.
-///
-/// This shipped **absent** for months on the belief that the relic slot post-dates 1.12, which is
-/// false (decision 1796). Stock `PaperDollFrame.lua` calls it unconditionally at l.429 and l.580,
-/// so while it was missing the character sheet raised `attempt to call global` for every class —
-/// which is why the nil-global case is asserted here too, not just the answer.
+/// Stock calls it unconditionally (`PaperDollFrame.lua:429`, `PaperDollFrame.lua:580`), so the
+/// global must exist for every class.
 #[test]
 fn unit_has_relic_slot_answers_one_or_nil() {
     let mut s = UiScript::new().unwrap();
@@ -1539,8 +1342,7 @@ fn unit_has_relic_slot_answers_one_or_nil() {
     warrior.has_relic_slot = false;
     s.set_unit("target", Some(warrior));
 
-    // The truthy leg is the NUMBER 1 (`lua_pushnumber`, `0x519ec8`) — a caller comparing it to 1
-    // is stock idiom, and a boolean would silently fail that.
+    // The true leg is the number 1 (`0x519ec8`).
     assert_eq!(
         s.eval::<String>(r#"return tostring(UnitHasRelicSlot("player"))"#)
             .unwrap(),
@@ -1551,34 +1353,26 @@ fn unit_has_relic_slot_answers_one_or_nil() {
             .unwrap(),
         "number"
     );
-    // The false leg is nil, never `false` (`lua_pushnil`, `0x519edb`).
+    // The false leg is nil, never false (`0x519edb`).
     assert_eq!(
         s.eval::<String>(r#"return type(UnitHasRelicSlot("target"))"#)
             .unwrap(),
         "nil"
     );
-    // No `"player"` fast path in the reference, so every token is answered the same way — the
-    // stock inspect path at `PaperDollFrame.lua:429` passes the inspected unit, not "player".
+    // No `"player"` fast path: `InspectPaperDollFrame.lua:123` passes the inspected unit.
     assert_eq!(
         s.eval::<String>(r#"return type(UnitHasRelicSlot("party1"))"#)
             .unwrap(),
         "nil"
     );
-    // And it EXISTS — the regression that actually bit. A nil global here takes the whole
-    // character sheet down for every class, not just the three that answer 1.
     assert_eq!(
         s.eval::<String>("return type(UnitHasRelicSlot)").unwrap(),
         "function"
     );
 }
 
-/// **The two-token predicates gate BOTH positions** — decision 1836, closing the half 1834 left
-/// open on purpose.
-///
-/// 1834 applied the `lua_isstring` gate only where wow-re's partial list named a single-token
-/// binding, because a census that finds "a gate somewhere in this body" cannot say *which*
-/// argument carries it. The complete 83-row table (`nil-unit-token-arg-law.md` §10) resolves it:
-/// these seven each carry **two** `lua_isstring` sites, so either argument being nil raises.
+/// Each of these carries two `lua_isstring` gates in the table at `0x850438`, so either argument
+/// nil raises.
 #[test]
 fn a_two_token_predicate_raises_on_either_nil_argument() {
     let mut s = UiScript::new().unwrap();
@@ -1608,14 +1402,12 @@ fn a_two_token_predicate_raises_on_either_nil_argument() {
         assert!(s.run(&format!("{verb}()")).is_err(), "{verb} with neither");
     }
 
-    // `GetRaidTargetIndex` is the one of six previously-unclassified names that takes a token, and
-    // it is gated. Its usage string names the argument UNQUOTED — the reference's own spelling.
+    // `GetRaidTargetIndex` takes a token and is gated.
     assert!(s.run(r#"GetRaidTargetIndex("player")"#).is_ok());
     assert!(s.run("GetRaidTargetIndex()").is_err());
 
-    // …while the other five take no argument at all and have no gate. `GetTimeToWellRested` is a
-    // three-instruction stub in the reference that always pushes nil; computing a value there
-    // would be divergence, not a feature.
+    // These take no argument and have no gate; `GetTimeToWellRested` is a stub in the reference
+    // that always pushes nil.
     for none in [
         "GetQuestGreenRange",
         "GetRestState",
@@ -1627,32 +1419,14 @@ fn a_two_token_predicate_raises_on_either_nil_argument() {
     }
 }
 
-// ── The family's return SHAPE, pinned per binding ───────────────────────────────────────────────
+// ── The predicates' return shape ────────────────────────────────────────────────────────────────
 
-/// **Every `Unit*` predicate answers the number `1` or `nil` — never a Lua boolean** (decision
-/// 2043; the law is 1830's, made for the widget predicates a family earlier).
-///
-/// The reference cannot produce a boolean here. Its pushes are `lua_pushnumber 0x6f3810` (tag 3,
-/// the double `1.0`) and `lua_pushnil 0x6f37f0` (tag 0); `lua_pushboolean 0x6f39f0` has seven call
-/// sites image-wide and not one is a registered binding body, so **tag 1 is never written**
-/// (wow-re `ui/scratch/binding-shape-arity-law.md`, `ui/scratch/button-enabled-state.md`, restated
-/// `ui.md` l.4700 and l.7348; the per-binding carves for `UnitExists 0x515fb0`,
-/// `UnitIsVisible 0x516030`, `UnitIsTapped 0x519c90`, `UnitAffectingCombat 0x517e10`,
-/// `UnitPlayerControlled 0x516410`, `UnitInRaid 0x516350`, `UnitIsCharmed 0x516cf0` and
-/// `UnitHasRelicSlot 0x519e50` each state it outright).
-///
-/// **Truthiness is exactly why this needs a test rather than a reading.** `if UnitIsDead(u)` and
-/// `if not UnitIsDead(u)` are identical under either shape, and mlua's `bool` conversion maps
-/// `Integer(1)` to `true` as happily as it maps `Boolean(true)` — so a test that reads the value
-/// as a Rust `bool` passes under the bug. Only `type(...)`, `== 1` and `== nil` separate them, and
-/// `== nil` is the one that *inverts*: a boolean `false` is not `nil`, so a caller comparing
-/// against `nil` concludes the opposite of the truth.
-///
-/// The table is the whole registered family, so a new predicate added outside the seam fails here
-/// rather than shipping its own shape.
+/// The reference pushes the number 1 (`lua_pushnumber`, `0x6f3810`) or nil (`0x6f37f0`), and no
+/// unit binding calls `lua_pushboolean` (`0x6f39f0`). mlua reads 1 as `true`, so only `type`,
+/// `== 1` and `== nil` tell the shapes apart.
 #[test]
 fn every_unit_predicate_is_one_or_nil_and_never_a_boolean() {
-    // (binding, the call as an addon writes it, a UnitState that makes it TRUE)
+    // (binding, the call, a UnitState that makes it true)
     let table: Vec<(&str, &str, UnitState)> = vec![
         (
             "UnitExists",
@@ -1873,7 +1647,6 @@ fn every_unit_predicate_is_one_or_nil_and_never_a_boolean() {
     ];
 
     for (name, call, live) in table {
-        // ---- the TRUE leg: the number 1, one value, and NOT a boolean ----
         let mut s = UiScript::new().unwrap();
         s.set_unit("player", Some(player()));
         s.set_unit("target", Some(live));
@@ -1902,9 +1675,7 @@ fn every_unit_predicate_is_one_or_nil_and_never_a_boolean() {
             "{name} returns exactly one value on the true leg"
         );
 
-        // ---- the FALSE leg: nil, one value, and NOT `false` ----
-        // The token is cleared rather than re-flagged, so this also covers the "no such unit" arm
-        // the reference shares with a false predicate.
+        // The false leg: nil, one value. Clearing the token also covers the absent-unit arm.
         let mut s = UiScript::new().unwrap();
         s.set_unit("player", Some(player()));
         s.set_unit("target", None);
@@ -1926,11 +1697,7 @@ fn every_unit_predicate_is_one_or_nil_and_never_a_boolean() {
     }
 }
 
-/// The corpus idiom, spelled the way an addon spells it, on a live token and a dead one.
-///
-/// This is the shape a `bool` breaks and truthiness hides: `if UnitExists("target") == 1` is
-/// simply never true under a boolean, and `if UnitExists("target") == nil` is never true either —
-/// the branch silently picks the wrong arm in both directions at once.
+/// The addon idiom: under a boolean, neither `== 1` nor `== nil` would ever be true.
 #[test]
 fn the_equals_one_idiom_branches_correctly_on_a_live_and_a_dead_token() {
     let mut s = UiScript::new().unwrap();
@@ -1963,9 +1730,8 @@ fn the_equals_one_idiom_branches_correctly_on_a_live_and_a_dead_token() {
     );
 }
 
-/// `UnitOnTaxi` (`0x517a40`) is the family's one predicate registered outside `unit/`, over the
-/// taxi module's own ride flag — which is how it stayed a `bool` when its 22 siblings were fixed.
-/// Same shape, and the same `Usage:` raise its gate at `0x517a48` carries.
+/// `UnitOnTaxi` (`0x517a40`), registered with the taxi module's ride flag, has the family's shape
+/// and raises `Usage:` from its gate (`0x517a48`).
 #[test]
 fn unit_on_taxi_is_one_or_nil_and_raises_the_reference_usage() {
     let mut s = UiScript::new().unwrap();
@@ -1984,7 +1750,7 @@ fn unit_on_taxi_is_one_or_nil_and_raises_the_reference_usage() {
     assert!(!s
         .eval::<bool>(r#"return UnitOnTaxi("player") == true"#)
         .unwrap());
-    // Any other token is nil, not false — only our own player is tracked.
+    // Only the player's ride is tracked: any other token is nil.
     assert!(s
         .eval::<bool>(r#"return UnitOnTaxi("target") == nil"#)
         .unwrap());
@@ -1996,24 +1762,18 @@ fn unit_on_taxi_is_one_or_nil_and_raises_the_reference_usage() {
     );
 }
 
-/// **The four `"player"` verbs read the seeded record, and nothing can blank it** (2261/2263).
-///
-/// The reference's `"player"` arm never reaches the resolver: `0x51708c` reads `0xc27d88`, a copy
-/// of the char-enum row written once at the Enter World commit and never cleared anywhere in the
-/// image. So the name survives everything that can happen to the *snapshot* — which is the whole
-/// of decision 2260's bug: a name-cache miss for our own guid produced a nameless player push, it
-/// replaced the roster seat, and the verb went nil in the world. That push is modelled here
-/// exactly, and it must now be invisible to this verb.
+/// The reference's `"player"` arm reads the record (`0x51708c` reads `0xc27d88`), never the
+/// snapshot, so a nameless player push cannot blank the name.
 #[test]
 fn the_player_record_outlives_every_snapshot() {
     let mut s = UiScript::new().unwrap();
 
-    // Before any Enter World commit — the buffer's one empty state, and the reference's nil.
+    // Before Enter World the record is empty: nil.
     assert!(s
         .eval::<bool>(r#"return UnitName("player") == nil"#)
         .unwrap());
 
-    // The world-entry load seeds it from the roster row, before a single addon file runs.
+    // Enter World seeds it from the character row, before any addon file runs.
     s.set_player_record(PlayerRecord {
         name: "Nelprifour".into(),
         race: Some(("Night Elf".into(), "NightElf".into())),
@@ -2027,7 +1787,7 @@ fn the_player_record_outlives_every_snapshot() {
          for many frames with no local player object and this verb still answers"
     );
 
-    // 2260's push, verbatim: the descriptor landed, the name cache missed for our own guid.
+    // The descriptor has landed, but the name cache missed our own guid.
     let nameless = UnitState {
         exists: true,
         has_object: true,
@@ -2053,12 +1813,10 @@ fn the_player_record_outlives_every_snapshot() {
         "UnitClass's second return is the UPPERCASE token"
     );
     assert_eq!(s.eval::<i64>(r#"return UnitSex("player")"#).unwrap(), 2);
-    // …and the snapshot is still the snapshot for everything else. `UnitLevel` is the boundary:
-    // the record carries a level byte and the client's accessor for it (`0x5abe00`) is DEAD, so
-    // this one reads the descriptor even for `"player"`.
+    // `UnitLevel` reads the snapshot: the record's level accessor (`0x5abe00`) has no caller.
     assert_eq!(s.eval::<i64>(r#"return UnitLevel("player")"#).unwrap(), 5);
 
-    // The token going away entirely (the logout despawn frames) does not empty the buffer either.
+    // Removing the token, as at logout, keeps the record.
     s.set_unit("player", None);
     assert_eq!(
         s.eval::<String>(r#"return UnitName("player")"#).unwrap(),
@@ -2070,7 +1828,7 @@ fn the_player_record_outlives_every_snapshot() {
         "the name and the unit are different questions — which is exactly what the buffer buys"
     );
 
-    // An empty seed is refused, not stored: nothing in the reference ever empties this record.
+    // An empty seed is refused: nothing empties the reference's record.
     s.set_player_record(PlayerRecord::default());
     assert_eq!(
         s.eval::<String>(r#"return UnitName("player")"#).unwrap(),
@@ -2081,8 +1839,7 @@ fn the_player_record_outlives_every_snapshot() {
         "Night Elf"
     );
 
-    // A NAMED push does keep it in step — a second login as somebody else (1290's per-login VM
-    // is the usual route, but a push must never leave the two disagreeing).
+    // A named push updates the record, so a push never leaves the two disagreeing.
     let mut other = player();
     other.name = Some("Onewarrior".into());
     s.set_unit("player", Some(other));
@@ -2102,32 +1859,22 @@ fn the_player_record_outlives_every_snapshot() {
         "player() is female — the record follows the push"
     );
 
-    // Still the family's two returns, the second nil (1840).
+    // Two returns, the realm nil.
     assert_eq!(
         s.eval::<i64>(r#"local t = {UnitName("player")}; return table.getn(t)"#)
             .unwrap(),
         1
     );
-    // …and the case fold on the token holds on the fast path too.
+    // The record path folds case too.
     assert_eq!(
         s.eval::<String>(r#"return UnitName("PLAYER")"#).unwrap(),
         "Onewarrior"
     );
 }
 
-/// **The unset record's four answers, which are not uniform** (decision 2263).
-///
-/// The state is "no Enter World has been committed in this process" — unreachable from Lua in the
-/// reference, because the four verbs only exist inside `UI_Init`'s table and only an Enter World
-/// commit gets there. It is reachable *here* (a bare VM, a capture, a test world with no pick), so
-/// it is pinned to what the bytes do rather than left to whatever falls out:
-///
-/// - `UnitName` → nil, via `lua_pushstring(NULL)` at `0x517095` tail-jumping into `lua_pushnil`;
-/// - `UnitRace`/`UnitClass` → `nil, nil`, via the DBC bound and NULL-row arms — race 0 and class 0
-///   have no row, and those arms reach `pushnil` **without** falling back to the unit resolver;
-/// - `UnitSex` → the number **2**, because `0x517ef9`'s accessor feeds `fild [4*eax+0x808be4]`
-///   over `{2,3,1,6}` with **no bounds check at all**. It is the one of the four with no validity
-///   guard, and "male" is what an all-zero record means to it.
+/// An all-zero record, which a bare VM here can reach: `UnitName` nil (`0x517095`), `UnitRace` and
+/// `UnitClass` `nil, nil` as race and class 0 have no row, and `UnitSex` 2, as `0x517ef9` indexes
+/// its table (`0x808be4`) unchecked.
 #[test]
 fn an_unseeded_player_record_answers_the_references_four_ways() {
     let s = UiScript::new().unwrap();
@@ -2151,8 +1898,7 @@ fn an_unseeded_player_record_answers_the_references_four_ways() {
         2,
         "the one of the four with no bounds check — an all-zero record reads male, not nil"
     );
-    // And the fast path is the TOKEN, not a prefix: `"playerfoo"` is recognised but resolves to
-    // nothing, so it goes to the resolver and answers the resolver's nil.
+    // The record arm needs the whole token: `"playerfoo"` goes to the resolver.
     assert!(s
         .eval::<bool>(r#"return UnitName("playerfoo") == nil"#)
         .unwrap());
diff --git a/crates/benilla-ui/src/script/weapon_enchant.rs b/crates/benilla-ui/src/script/weapon_enchant.rs
index 96e14620..81a41ffb 100644
--- a/crates/benilla-ui/src/script/weapon_enchant.rs
+++ b/crates/benilla-ui/src/script/weapon_enchant.rs
@@ -1,99 +1,42 @@
-//! `GetWeaponEnchantInfo` — the two **temporary weapon enchantment** slots, as virtual buff slots.
+//! `GetWeaponEnchantInfo` (`0x4c9790`): the two temporary weapon enchantments, which
+//! `BuffFrame_Enchant_OnUpdate` (`BuffFrame.lua:162-233`) polls every frame.
 //!
-//! This is the whole data path behind the reference's `TemporaryEnchantFrame`
-//! (`BuffFrame.lua:162-233`): the row polls this verb every frame, shows an icon per enchanted
-//! weapon, and counts its expiry down. Eight corpus addons call it as well.
+//! No arguments; six values on every path (`0x4c993a`, `0x4c995b`, `0x4c998f`), main hand
+//! (equipment slot 15, `0x4c97c3`) then off hand (slot 16, `0x4c988b`):
 //!
-//! # The byte-verified signature (`0x4c9790`, `system/ui/ledger.tsv:1972`)
-//!
-//! Zero arguments — the function never touches the Lua stack for input; `edi` is the state. **Six**
-//! return values on **every** path (`mov eax,0x6` at `0x4c993a`, `0x4c995b` and `0x4c998f`, the
-//! three exits), in the order FrameXML destructures them:
-//!
-//! ```text
-//! hasMainHandEnchant, mainHandExpiration, mainHandCharges,
-//! hasOffHandEnchant,  offHandExpiration,  offHandCharges
-//! ```
-//!
-//! | value | shape | absent |
+//! | value | present | absent |
 //! |---|---|---|
-//! | `has*Enchant` | the **number 1** (`push 0x3ff00000; push 0x0` — the double 1.0 — through the number-push at `0x6f3810`, `0x4c97fc`/`0x4c98c3`) | **nil** (`0x6f37f0`, the nil-push, three of them at `0x4c9873` / `0x4c9944`) |
-//! | `*Expiration` | a number of **MILLISECONDS remaining** (`0x5d9d00(item, 1)` → `fild` → number-push, `0x4c9828`-`0x4c983f`) | **nil** |
-//! | `*Charges` | a number (the enchantment triple's third dword) | the number **0**, never nil (`mov DWORD PTR [ebp-0x4],0x0; fild`, `0x4c985a`) |
+//! | `has*Enchant` | the number 1 (`0x6f3810`) | nil (`0x6f37f0`) |
+//! | `*Expiration` | milliseconds remaining (`0x5d9d00`) | nil |
+//! | `*Charges` | the charges | 0, never nil (`0x4c985a`) |
 //!
-//! Milliseconds, not seconds: `ref-BuffFrame.lua:189`/`:212` divide by 1000 before displaying, and
-//! `0x5d9d00` is the same live remaining-time reader `benilla::items::Items::enchant_remaining_ms`
-//! mirrors (decision 0920). It is *remaining* time, recomputed per call against a deadline — never
-//! an absolute stamp.
+//! Each weapon's `ITEM_FIELD_ENCHANTMENT` slot 1 triple is read raw (`0x83a3c8`): a nonzero id is
+//! the whole gate (`0x4c97f8`), with no DBC lookup, so the totem imbues, which the tooltip's
+//! enchant list drops, still show. The duration dword only gates the expiration (`0x4c981b`); the
+//! value is `max(0, deadline - now)` on a deadline `0x5d9cc0` parks from the seconds in
+//! `SMSG_ITEM_ENCHANT_TIME_UPDATE`, so the host subtracts on read and an elapsed timer is 0.
 //!
-//! # Which slots, and which enchantment
-//!
-//! Main hand is fetched first, from **equipment slot 15** (`push 0xf`, `0x4c97c3`), off hand from
-//! **16** (`push 0x10`, `0x4c988b`) — the client's 0-based `EQUIPMENT_SLOT_*` numbering, so the
-//! live-API `GetInventorySlotInfo` ids one higher (16 `MainHandSlot`, 17 `SecondaryHandSlot`) are
-//! what the frame passes to `GetInventoryItemTexture`.
-//!
-//! Per weapon the binary reads three consecutive dwords off the item's descriptor —
-//! `[D+0x4c]` the enchant **id** (`test eax,eax; je` = the entire has-an-enchant gate, `0x4c97f8`),
-//! `[D+0x50]` the **duration**, `[D+0x54]` the **charges** — and the `push 0x1` handed to
-//! `0x5d9d00` names the enchantment slot: **1 = TEMP**. The identity is read off the client's own
-//! field-metadata table, not inferred: `0x83a3c8` = `"ITEM_FIELD_ENCHANTMENT"`, index `0x10`, size
-//! `0x15`, with `0x83a2d4`/`0x83a2e8` fixing `D = O + 0x18` — so the triple is fields 25/26/27,
-//! slot 1.
-//!
-//! **The gate is the raw id and nothing else** — no DBC lookup, no display filter. That is why the
-//! app feeds this from [`benilla_protocol`]'s `item_enchant(1)` rather than from the tooltip-shaped
-//! [`super::EnchantView`] list, which drops an id the `SpellItemEnchantment` catalog cannot name
-//! *and* the whole `Flags & 0x2` print-no-line family (decision 0928) — the totem weapon imbues,
-//! i.e. precisely the enchants this row exists to show.
-//!
-//! # The expiration is NOT the wire field
-//!
-//! The trap, and the reason this went through wow-re rather than being read off the update fields:
-//! `[D+0x50]`, the item's own enchantment **duration** dword, is read *only* as a non-zero presence
-//! gate (`0x4c981b test ecx,ecx`) — **its value is never returned**. The number comes from a
-//! client-local **absolute deadline** at `item+0x324[slot]`, written only by `0x5d9cc0` out of
-//! `SMSG_ITEM_ENCHANT_TIME_UPDATE` as `now_ms + seconds*1000`, and read back as
-//! `max(0, deadline − now)` (`0x5d9d00`: `0x5d9d15` clock, `0x5d9d2a sub`). **The wire carries
-//! seconds; this API returns milliseconds.** So a host stores a deadline and subtracts on read — it
-//! never ticks a countdown. `benilla::items::Items` does exactly that, and
-//! `Items::enchant_deadline_ms` is the read that keeps an *elapsed* timer as the number `0` rather
-//! than collapsing it to "no timer", which is the distinction `BuffFrame_Enchant_OnUpdate` draws
-//! "0 s" from.
-//!
-//! **Our one named gap.** The reference's nil-expiration branch is `[D+0x50] == 0`; ours is "no
-//! deadline was ever parked for this slot". They differ for exactly one state — an enchant whose
-//! duration field is set but whose `SMSG_ITEM_ENCHANT_TIME_UPDATE` has not arrived yet, where the
-//! reference answers the number `0` and we answer nil. Closing it needs an
-//! `item_enchant_duration(slot)` accessor beside `item_enchant`/`item_enchant_charges` in
-//! `benilla_protocol` (the triple's middle field, deliberately unexposed there because the tooltip
-//! never reads it — decision 0920). The server sends the packet in the same breath as the field, so
-//! the window is a frame or two.
+//! The reference's expiration is nil only when the duration dword is 0; ours is nil until the
+//! first `SMSG_ITEM_ENCHANT_TIME_UPDATE`, which follows the field within a frame or two.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One weapon's **temporary** enchantment (`ITEM_FIELD_ENCHANTMENT` slot 1), as the app reads it
-/// off the equipped item object. Its mere existence is `has*Enchant`: the app only builds one when
-/// the enchant id is nonzero, which is the binary's own gate.
+/// One weapon's temporary enchantment (`ITEM_FIELD_ENCHANTMENT` slot 1); the app builds one only
+/// for a nonzero enchant id, the reference's gate.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct WeaponEnchant {
-    /// Milliseconds left on the enchant — `max(0, deadline − now)` off the parked
-    /// `SMSG_ITEM_ENCHANT_TIME_UPDATE` deadline, so **`Some(0)` for an elapsed timer** (the
-    /// reference returns the number 0 there, and the row draws "0 s" and pulses). `None` is the
-    /// reference's nil expiration: no timer on this enchant at all.
+    /// Milliseconds left, `max(0, deadline - now)`: `Some(0)` once elapsed, where the reference
+    /// returns 0 and the row draws "0 s"; `None` is no timer at all.
     pub remaining_ms: Option<u64>,
-    /// The triple's charges dword — `0` for an enchant that carries none, never absent.
+    /// The charges dword, 0 for none.
     pub charges: u32,
 }
 
 impl super::UiScript {
-    /// Push the two weapons' temporary enchantments (`None` = no item, or no enchant on it).
-    ///
-    /// **Pushed every frame, not on change**: `remaining_ms` is a live countdown, so folding it
-    /// into a change-gated snapshot would either fire that snapshot's event every frame or freeze
-    /// the timer. The reference recomputes it per call for the same reason.
+    /// Push the two weapons' temporary enchantments, `None` for no item or no enchant. Pushed every
+    /// frame: `remaining_ms` is live, and the reference recomputes it per call.
     pub fn set_weapon_enchants(
         &mut self,
         main_hand: Option<WeaponEnchant>,
@@ -111,8 +54,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let mut out = Vec::with_capacity(6);
-            // Main hand then off hand, three values each — the arity is fixed at six whatever is
-            // equipped, so a caller's `local a, b, c, d, e, f = …` never shifts.
+            // Main hand then off hand, three values each: always six.
             for hand in model.weapon_enchants {
                 match hand {
                     Some(e) => {
@@ -135,16 +77,12 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
 mod tests {
     use crate::script::{UiScript, WeaponEnchant};
 
-    /// **The arity, and the shapes that carry it.** Six values on every path — the reference's
-    /// `mov eax,0x6` — with `nil` for an unenchanted weapon and the *number* 1 for an enchanted
-    /// one. An implementation that returned `false`/`0`, or that returned early with three values
-    /// when the off hand is empty, breaks `BuffFrame_Enchant_OnUpdate`'s single destructuring
-    /// assignment and every corpus caller with it.
+    /// `BuffFrame.lua:163` destructures all six at once.
     #[test]
     fn get_weapon_enchant_info_returns_six_values_on_every_path() {
         let mut s = UiScript::new().unwrap();
 
-        // Nothing equipped or nothing enchanted: six nils, not zero values.
+        // Nothing enchanted: six nils, not zero values.
         assert_eq!(s.arity("GetWeaponEnchantInfo()").unwrap(), 6);
         assert!(s
             .eval::<bool>(
@@ -152,7 +90,6 @@ mod tests {
                  return a == nil and b == nil and c == nil and d == nil and e == nil and f == nil"
             )
             .unwrap());
-        // The reference's own early-out branch, run for real.
         assert!(s
             .eval::<bool>("local m, _, _, o = GetWeaponEnchantInfo() return (not m) and (not o)")
             .unwrap());
@@ -178,11 +115,10 @@ mod tests {
             (1.0, 480_000.0, 0.0),
             "the number 1, MILLISECONDS, and a zero charge count"
         );
-        // `has` is the number 1, not a boolean: `true ~= 1` would invert any `== 1` test.
+        // The number 1, not a boolean: `true ~= 1`.
         assert!(s
             .eval::<bool>("local a = GetWeaponEnchantInfo() return a == 1")
             .unwrap());
-        // The off hand is still all nil.
         assert!(s
             .eval::<bool>(
                 "local _, _, _, d, e, f = GetWeaponEnchantInfo() \
@@ -211,10 +147,7 @@ mod tests {
             "no parked deadline is a nil expiration, never a fabricated 0"
         );
 
-        // ...and the state that is NOT nil: an elapsed timer. The reference returns the number 0
-        // there (`max(0, deadline - now)` on a deadline in the past), and the enchant row's
-        // `if ( expiration )` is TRUE for 0 in Lua — so it draws "0 s" and pulses the icon. A host
-        // that collapsed "expired" into "no timer" would blank the last second of every enchant.
+        // An elapsed timer is the number 0, which the row's `if ( expiration )` takes as true.
         s.set_weapon_enchants(
             Some(WeaponEnchant {
                 remaining_ms: Some(0),
@@ -233,20 +166,14 @@ mod tests {
             "and 0 is truthy in Lua, which is what makes the row draw it"
         );
 
-        // Zero arguments — and a surplus one is IGNORED, not an error. The reference reads nothing
-        // off the stack and has no usage string at all (contrast its neighbour
-        // `GetInventoryAlertStatus`, which has both), so an addon that guesses at a slot argument
-        // still gets an answer rather than a raised error.
+        // The reference reads no arguments and has no usage string, so a surplus one is ignored.
         assert_eq!(
             s.arity("GetWeaponEnchantInfo(16, \"nonsense\")").unwrap(),
             6
         );
     }
 
-    /// The reference's own consumer arithmetic, run over the binding: `expiration/1000` is the
-    /// number of seconds the row prints, and the `< BUFF_WARNING_TIME` flash test rides on it.
-    /// Milliseconds is the whole point — a seconds return would make a 480 s enchant read as
-    /// 0.48 s and flash from the moment it was applied.
+    /// `BuffFrame.lua:212` divides by 1000 before its `BUFF_WARNING_TIME` test.
     #[test]
     fn the_expiration_is_milliseconds_the_way_the_reference_divides_it() {
         let mut s = UiScript::new().unwrap();
diff --git a/crates/benilla-ui/src/script/who_sort.rs b/crates/benilla-ui/src/script/who_sort.rs
index 39ca8dc1..7ba19abf 100644
--- a/crates/benilla-ui/src/script/who_sort.rs
+++ b/crates/benilla-ui/src/script/who_sort.rs
@@ -1,58 +1,34 @@
-//! The `/who` list's sort — the reference's seven-slot key chain, its promote-and-flip rule, and
-//! the comparator that walks it (`SortWho 0x5ad890`, comparator `0x5ada00`; wow-re
-//! `system/net/scratch/who-list-sort-law.md`, §5-crossed 2026-09-05, benilla decision 2030).
-//!
-//! **A `/who` sort is not "order by the clicked column".** The reference keeps a *chain* of seven
-//! `{key, dir}` slots at `0xc2817c`/`0xc28180`, seeded once per process to `key[i] = i`
-//! (`0x5add04`), i.e. **zone → level → class → group → name → race → guild**, every direction
-//! ascending. Each click *promotes* its key to the front of that chain; the keys it displaces
-//! stay behind it, so the chain reads most-recently-used first and the comparator walks it as a
-//! **tie-breaker list**, not as a single key. Two players on the same level keep whatever order
-//! the previously clicked key gave them.
-//!
-//! Two consequences that are the whole of bug B365:
-//!
-//! - **A repeated click reverses.** The promote flips the direction **only when the key was
-//!   already at the front** (`0x5ad99e`–`0x5ad9a7`, the `sete` on `i == 0`); promoting a key from
-//!   anywhere else carries its *remembered* direction over unchanged. So Name, Name reverses; but
-//!   Name, Level, Name does **not** — the second Name click restores the direction the first one
-//!   left there.
-//! - **Nothing here is a request to the server.** The chain and the comparator are engine state;
-//!   `SortWho` sorts the array it already holds and fires `WHO_LIST_UPDATE` synchronously, inside
-//!   the binding ([`super::social`]'s `SortWho`).
-//!
-//! The chain is **per-process** in the reference — its initialiser `0x5adc50` runs once from the
-//! process-start run at `0x401666` — so it survives a logout and the next login inherits it.
-//! `SocialState::clear_session` on the app side keeps it for that reason.
+//! The `/who` sort (`SortWho` `0x5ad890`, comparator `0x5ada00`): a chain of seven `{key, dir}`
+//! slots (`0xc2817c`/`0xc28180`), seeded zone, level, class, group, name, race, guild, all
+//! ascending (`0x5add04`). A click promotes its key to the front and the comparator walks the chain
+//! as tie-breakers, so earlier clicks still order ties. The direction flips only when the key was
+//! already in front (`0x5ad99e`–`0x5ad9a7`); promoted from behind, it keeps its old direction.
+//! Sorting is local, never a server request, and the chain lives for the process (`0x5adc50`, run
+//! from `0x401666`), so it survives a logout.
 
 use std::cmp::Ordering;
 
 use super::social::WhoInfo;
 
-/// The seven keys `SortWho` maps its argument to. **The declaration order is the reference's key
-/// numbering** (`edi` in `0x5ad8bb`–`0x5ad979`) *and* the chain's seeded order, because the
-/// initialiser writes `key[i] = i`.
+/// The seven keys `SortWho` maps its argument to, declared in the reference's numbering
+/// (`0x5ad8bb`–`0x5ad979`), which is also the chain's seeded order.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
 pub enum WhoSortKey {
-    /// `0` — `"zone"`, the frame's own resting column.
+    /// `0`, `"zone"`, the frame's resting column.
     Zone,
-    /// `1` — `"level"`, the one numeric arm: at `dir = 0` the **lower** level comes first.
+    /// `1`, `"level"`, the one numeric arm: ascending puts the lower level first.
     Level,
-    /// `2` — `"class"`.
+    /// `2`, `"class"`.
     Class,
-    /// `3` — `"group"`. A real chain key whose comparator arm (`0x5adbb2`) *is* the continue
-    /// label: it orders nothing, ever. Unreachable from the shipped UI as well — the header that
-    /// carries `sortType = "group"` sits inside `FriendsFrame.xml`'s commented span 1413–1429 —
-    /// but it is modelled because it occupies a slot, and promoting it still displaces whatever
-    /// key was at the front.
+    /// `3`, `"group"`: its arm (`0x5adbb2`) orders nothing, but promoting it still displaces the
+    /// front key. The stock header for it is commented out (`FriendsFrame.xml:1413-1429`).
     Group,
-    /// `4` — `"name"`, and the answer for **any** string the seven compares miss: `edi` is
-    /// preloaded with 4 at `0x5ad8bb` and never reassigned on the no-match path.
+    /// `4`, `"name"`, and the answer for any other string (preloaded at `0x5ad8bb`).
     #[default]
     Name,
-    /// `5` — `"race"`.
+    /// `5`, `"race"`.
     Race,
-    /// `6` — `"guild"`.
+    /// `6`, `"guild"`.
     Guild,
 }
 
@@ -68,9 +44,8 @@ impl WhoSortKey {
         Self::Guild,
     ];
 
-    /// `SortWho`'s argument → key: seven `0x64a4c0` compares (`0x5ad8c0`–`0x5ad979`), which are
-    /// **case-insensitive** (`0x414310` folds `A`–`Z` on both operands), with [`Self::Name`] as
-    /// the no-match answer.
+    /// `SortWho`'s argument to its key: seven ASCII case-insensitive compares (`0x64a4c0`,
+    /// `0x5ad8c0`–`0x5ad979`), [`Self::Name`] when none match.
     pub fn from_sort_type(sort_type: &str) -> Self {
         match () {
             _ if sort_type.eq_ignore_ascii_case("name") => Self::Name,
@@ -84,33 +59,28 @@ impl WhoSortKey {
         }
     }
 
-    /// This key's own ordering of two rows at `dir = 0` — the comparator's seven jump-table arms
-    /// (`0x5adbd8`), each returning `0x64a4c0`'s `−1/0/+1` or the level arm's `setge` sign.
+    /// This key's ascending order of two rows: the comparator's jump-table arms (`0x5adbd8`).
     fn order(self, a: &WhoInfo, b: &WhoInfo) -> Ordering {
         match self {
-            // `a+0` / `a+0x30`: wire strings, compared case-insensitively. An empty guild is a
-            // real value here (`""` sorts before any name), not a missing row.
+            // `a+0`/`a+0x30`, wire strings; an empty guild is a real value and sorts first.
             Self::Name => ascii_ci_cmp(&a.name, &b.name),
             Self::Guild => ascii_ci_cmp(&a.guild, &b.guild),
-            // `a+0x90`, i32: `cmp; je tie; setge dl; lea edx,[edx*2-1]` — lower level first.
+            // `a+0x90`, an i32, lower level first.
             Self::Level => a.level.cmp(&b.level),
-            // The three DBC arms: the *localized name* out of `ChrClasses`/`ChrRaces`/`AreaTable`
-            // is what gets compared, which is exactly what the app already resolved into the row.
+            // The localized `ChrClasses`/`ChrRaces`/`AreaTable` name the app resolved into the row.
             Self::Class => dbc_name_cmp(&a.class, &b.class),
             Self::Race => dbc_name_cmp(&a.race, &b.race),
             Self::Zone => dbc_name_cmp(&a.zone, &b.zone),
-            // `0x5adbb2` is the continue label itself.
+            // `0x5adbb2` is the chain loop's continue label.
             Self::Group => Ordering::Equal,
         }
     }
 }
 
-/// The seven-slot `{key, dir}` chain at `0xc2817c`/`0xc28180`: the sort keys most-recently-used
-/// first, each with the direction it was last left in. See the module doc.
+/// The seven-slot chain: keys most recently used first, each with the direction it was left in.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct WhoSortChain {
-    /// `(key, reversed)`, slot 0 first. Every key appears exactly once — a promote permutes, it
-    /// never inserts or drops.
+    /// `(key, reversed)`, slot 0 first; always a permutation of all seven keys.
     slots: [(WhoSortKey, bool); 7],
 }
 
@@ -124,14 +94,12 @@ impl Default for WhoSortChain {
 }
 
 impl WhoSortChain {
-    /// `SortWho`'s promote (`0x5ad980`–`0x5ad9c9`): move `sort_type`'s key to the front, flipping
-    /// its direction **only if it was already there**, and shift the keys it passed down one slot
-    /// each. Keys behind it keep their own remembered directions.
+    /// `SortWho`'s promote (`0x5ad980`–`0x5ad9c9`): move the key to the front, flipping its
+    /// direction only if it was already there; the keys it passes shift down one slot.
     pub fn promote(&mut self, sort_type: &str) {
         let key = WhoSortKey::from_sort_type(sort_type);
         let Some(at) = self.slots.iter().position(|(k, _)| *k == key) else {
-            // Unreachable: the chain is a permutation of all seven keys. The reference's own
-            // not-found edge (`0x5ad991 jmp 0x5ad9cf`) skips the promote and sorts anyway.
+            // Unreachable; the reference's not-found edge skips the promote and sorts (`0x5ad991`).
             return;
         };
         let dir = if at == 0 {
@@ -143,8 +111,8 @@ impl WhoSortChain {
         self.slots[0] = (key, dir);
     }
 
-    /// The comparator `0x5ada00`: walk the chain, return the first key that does not tie —
-    /// negated when that slot's direction is set — and `Equal` when all seven tie.
+    /// The comparator (`0x5ada00`): the first key that does not tie, negated when its slot is
+    /// reversed, else `Equal`.
     pub fn compare(&self, a: &WhoInfo, b: &WhoInfo) -> Ordering {
         for (key, reversed) in self.slots {
             let order = key.order(a, b);
@@ -155,29 +123,21 @@ impl WhoSortChain {
         Ordering::Equal
     }
 
-    /// Order `rows` by the chain — the `qsort` at `0x5ad9cf` (a click) and `0x5ae0e2` (a fresh
-    /// `SMSG_WHO` answer, which is why results arrive already in the current order).
-    ///
-    /// The reference's `qsort` is unstable and this is not; the difference is unobservable,
-    /// because the name key never leaves the chain and no two rows of one realm's `/who` answer
-    /// share a name, so [`Self::compare`] is a total order over the rows that can actually occur.
+    /// Order `rows` by the chain, as the reference's `qsort` does on a click (`0x5ad9cf`) and on
+    /// each `SMSG_WHO` answer (`0x5ae0e2`). This sort is stable where `qsort` is not, which no two
+    /// rows can show: names are unique and the name key never leaves the chain.
     pub fn sort(&self, rows: &mut [WhoInfo]) {
         rows.sort_by(|a, b| self.compare(a, b));
     }
 
-    /// The chain's keys, front (most recently clicked) first — for tests and diagnostics.
     #[cfg(test)]
     fn keys(&self) -> [(WhoSortKey, bool); 7] {
         self.slots
     }
 }
 
-/// `0x64a4c0` → `0x414310`: a **case-insensitive ASCII** compare, folding only `A`–`Z` by `+0x20`
-/// on both operands (`0x41434a`–`0x41435c`) and answering `−1/0/+1`.
-///
-/// Deliberately not `to_lowercase()`: that is a Unicode fold, and it would order the accented
-/// names the localized clients allow differently from the reference, which only ever touches the
-/// 26 ASCII letters.
+/// The reference's string compare (`0x64a4c0`, `0x414310`): it folds `A`–`Z` only
+/// (`0x41434a`–`0x41435c`), so accented names order as they do there, not by a Unicode fold.
 fn ascii_ci_cmp(a: &str, b: &str) -> Ordering {
     let (a, b) = (a.as_bytes(), b.as_bytes());
     for (x, y) in a.iter().zip(b) {
@@ -190,22 +150,10 @@ fn ascii_ci_cmp(a: &str, b: &str) -> Ordering {
     a.len().cmp(&b.len())
 }
 
-/// The three DBC-backed arms' compare. **A row the id could not resolve TIES** — verified on all
-/// three arms (class `0x5ada7b`, race `0x5adadf`, zone `0x5adb40`), which are one idiom
-/// byte-for-byte: three miss conditions (a negative id, an id past the *inclusive* bound, a NULL
-/// row at an in-range id) zero the row register, and either side being zero jumps to `0x5adbb2`,
-/// which **is** the chain loop's `inc esi`. So it is not a returned `0` compared against
-/// something — the key contributes nothing and the next slot decides. `dir` cannot reach it
-/// either (the `neg` is gated behind the compare the tie branch skips).
-///
-/// The tie matters more than it looks: an unresolved id would otherwise sort as `""`, parking
-/// every unknown zone at the top of the list ahead of Ahn'Qiraj.
-///
-/// **The empty string is this side's marker for "no row", and the two sides of the reference
-/// disagree on purpose.** `GetWhoInfo 0x5ad6e0` substitutes the localized `"UNKNOWN"` on the same
-/// three legs, so a row can read UNKNOWN in the cell while sorting as though that column did not
-/// exist. Anything that starts showing UNKNOWN here has to carry the miss to this comparator by
-/// some route other than the string (wow-re `who-list-sort-law.md` §11.1–§11.2).
+/// The class, race and zone arms (`0x5ada7b`, `0x5adadf`, `0x5adb40`): an id with no DBC row, an
+/// empty name here, ties and passes to the next key (`0x5adbb2`) rather than sorting as `""`. The
+/// empty name is the miss marker: the reference's `GetWhoInfo` (`0x5ad6e0`) shows `UNKNOWN` for
+/// it, benilla's an empty cell, and a row that carried `UNKNOWN` would sort on that word.
 fn dbc_name_cmp(a: &str, b: &str) -> Ordering {
     if a.is_empty() || b.is_empty() {
         return Ordering::Equal;
@@ -232,8 +180,6 @@ mod tests {
         rows.iter().map(|r| r.name.as_str()).collect()
     }
 
-    /// The seeded chain is the reference's `key[i] = i`, all ascending — so a list nobody has
-    /// clicked is ordered zone, then level, then class, then name.
     #[test]
     fn the_chain_is_seeded_in_key_order() {
         assert_eq!(
@@ -250,8 +196,6 @@ mod tests {
         );
     }
 
-    /// The key mapping, including the case-insensitive compares and the name fallback that
-    /// swallows every unrecognised string.
     #[test]
     fn the_sort_type_maps_case_insensitively_and_falls_back_to_name() {
         for (arg, key) in [
@@ -276,7 +220,6 @@ mod tests {
         }
     }
 
-    /// **B365's headline.** A first click sorts ascending; the *same* key clicked again reverses.
     #[test]
     fn a_repeated_click_reverses() {
         let mut rows = vec![
@@ -298,10 +241,6 @@ mod tests {
         assert_eq!(names(&rows), ["Erdrin", "Galas"], "and back again");
     }
 
-    /// The flip is `i == 0` ONLY. Clicking a different key in between promotes name from slot 1
-    /// with its remembered direction *carried*, so the third click below does not re-reverse —
-    /// it restores what the second one left, which is the half a naive "toggle on every click"
-    /// implementation gets wrong.
     #[test]
     fn promoting_from_behind_carries_the_direction_it_left() {
         let mut chain = WhoSortChain::default();
@@ -310,7 +249,7 @@ mod tests {
         chain.promote("level"); // name drops to slot 1, still descending
         assert_eq!(chain.keys()[1], (WhoSortKey::Name, true));
 
-        chain.promote("name"); // back to the front — NOT a flip
+        chain.promote("name"); // back to the front, not a flip
         assert_eq!(chain.keys()[0], (WhoSortKey::Name, true));
 
         let mut rows = vec![
@@ -321,9 +260,6 @@ mod tests {
         assert_eq!(names(&rows), ["Bbb", "Aaa"], "still descending");
     }
 
-    /// The displaced keys stay behind the clicked one, most-recently-used first — so a click is a
-    /// tie-breaker chain, not a fresh single-key sort. Level, then class: rows equal on class
-    /// keep the *level* order the earlier click established.
     #[test]
     fn earlier_clicks_survive_as_tie_breakers() {
         let mut chain = WhoSortChain::default();
@@ -347,7 +283,6 @@ mod tests {
         );
     }
 
-    /// The level arm is the numeric one, and ascending means the LOWER level first.
     #[test]
     fn level_ascends_before_it_reverses() {
         let mut rows = vec![row("High", 60, "Mage", "Z"), row("Low", 12, "Mage", "Z")];
@@ -360,8 +295,6 @@ mod tests {
         assert_eq!(names(&rows), ["High", "Low"]);
     }
 
-    /// Names fold case the way `0x414310` does — `apple` and `Apple` compare equal, and `Zed`
-    /// sorts after `apple` rather than before it as a byte compare would have it.
     #[test]
     fn the_string_arms_fold_ascii_case() {
         assert_eq!(ascii_ci_cmp("Apple", "apple"), Ordering::Equal);
@@ -370,16 +303,12 @@ mod tests {
         assert_eq!(ascii_ci_cmp("Ann", "Anne"), Ordering::Less, "prefix first");
     }
 
-    /// An unresolved DBC name ties rather than sorting as `""` — otherwise every row whose zone
-    /// id has no `AreaTable` row would pile up at the top of a zone sort.
     #[test]
     fn an_unresolved_dbc_name_ties() {
         let mut chain = WhoSortChain::default();
         chain.promote("zone");
         let known = row("Bbb", 10, "Mage", "Westfall");
         let unknown = row("Aaa", 10, "Mage", "");
-        // Not `Less`: a `""` zone does not sort first, it does not sort at all — the zone key
-        // ties and the chain falls through to the name, where Aaa beats Bbb.
         assert_eq!(
             chain.compare(&known, &unknown),
             Ordering::Greater,
@@ -387,12 +316,10 @@ mod tests {
         );
         assert_eq!(chain.compare(&unknown, &known), Ordering::Less);
 
-        // A *guild* is not a DBC lookup: an empty guild is a real value and sorts first.
+        // A guild is not a DBC lookup: an empty guild is a real value and sorts first.
         assert_eq!(ascii_ci_cmp("", "Legacy"), Ordering::Less);
     }
 
-    /// `"group"` is a live chain key with a dead arm: it displaces whatever was at the front, and
-    /// orders nothing itself, so the list falls straight through to the rest of the chain.
     #[test]
     fn the_group_key_displaces_but_orders_nothing() {
         let mut chain = WhoSortChain::default();
@@ -411,8 +338,6 @@ mod tests {
         );
     }
 
-    /// Every key ties ⇒ `Equal`, the comparator's `xor eax,eax` tail. Only reachable for two rows
-    /// that agree on all six live keys.
     #[test]
     fn identical_rows_tie_on_every_key() {
         let chain = WhoSortChain::default();
diff --git a/crates/benilla-ui/src/script/worldmap.rs b/crates/benilla-ui/src/script/worldmap.rs
index 36a0542a..1e5a10d2 100644
--- a/crates/benilla-ui/src/script/worldmap.rs
+++ b/crates/benilla-ui/src/script/worldmap.rs
@@ -1,155 +1,86 @@
-//! The world-map bindings (decision 0203 phase 2) — the Era-shaped map-navigation surface the
-//! reference `WorldMapFrame.lua` reads, over the questgiver/quest-log seam shape: the app pushes
-//! a static **catalog** once (continents → zones, from `WorldMapArea`/`AreaTable`/
-//! `WorldMapContinent`) and a small per-frame **feed** (the player's resolved zone, projected map
-//! position, and facing — all projection math stays app-side in `map_proj`); the engine owns the
-//! **selection** (which map is displayed) so `SetMapZoom` → `GetCurrentMapContinent` reads back
-//! synchronously in the same click, exactly like the quest-log selection precedent.
+//! The world-map bindings `WorldMapFrame.lua` reads, over a catalog and a per-frame feed the app
+//! pushes (projection stays in `map_proj`); the engine owns the selection, so `SetMapZoom` reads
+//! back in the same click.
 //!
-//! `SetMapZoom`/`SetMapToCurrentZone`/`ProcessMapClick` queue `WORLD_MAP_UPDATE` through the
-//! model's pending-event queue (fired at the next tick — the reference's synchronous fire is a
-//! repaint trigger, and one tick is invisible at frame rate).
+//! The Lua selection is the client's indices plus one (`0x4a7ed0`, `0x4a7f00`): continent 0 is the
+//! world sheet, zone 0 the whole continent; continents in `WorldMapArea` file order (`0x4a5d00`),
+//! zones by case-insensitive name (`0x4a6390`). An instance map is a third state (`0x4a67a0`).
 //!
-//! Selection encoding (the Lua-visible one, wow-re-confirmed — the client's internal indices
-//! `+1`): continent `0` = the world sheet, `1..` = the catalog's continents; zone `0` = the
-//! whole continent, `1..` = that continent's zone list. The catalog's *order* defines those
-//! indices everywhere (dropdowns, `SetMapZoom`, the feed) — the app builds it under the
-//! verified rules (WorldMapArea file order for continents, case-insensitive display-name sort
-//! for zones; wow-re Q1(d)/Q3(b) verdicts, 2026-07-07).
-//!
-//! …and a **third** selection state beside that pair: the **direct area**, the map of an
-//! instance — a battleground, a dungeon — which is no continent's child and so falls out of both
-//! lists (wow-re `system/ui/scratch/worldmap-direct-area-selection.md`). The reference does not
-//! encode it inside `(continent, zone)`: it carries THREE `.data` cells, and `continent == -2`
-//! with a `WorldMapArea` row **ID** in the third one IS that state ([`WorldMapState::direct_area`]).
-//! Inside Warsong Gulch a client without it answers `GetMapInfo() == nil`, and the stock
-//! `Blizzard_BattlefieldMinimap.lua:83-86` returns on the fourth line of its update — an empty
-//! battle map and an empty world map, which is the bug this models away.
-//!
-//! Continent-level hover/click resolve through the pushed **zone grid** — the 128×128 area
-//! bitmap (`Interface\WorldMap\<Continent>.zmp`, remapped app-side to 1-based zone indices; the
-//! source + cell law are wow-re-verified, `0x4a6ec0` / the Q1 §5 verdict 2026-07-07). The cell
-//! law itself is transcribed here ([`area_grid_cell`]) rather than in the app's `map_proj`
-//! because its only callers are these bindings. `UpdateMapHighlight` answers per level exactly
-//! as `0x4a7fa0` does (wow-re 15b2a8ea): at continent level the hovered zone's name **and** its
-//! highlight quad; at zone level a **name only** — a revealed overlay's sub-area when the cursor
-//! is inside its `WorldMapOverlay` hit rect, else the neighbouring zone or city whose grid cell
-//! the cursor is in through the displayed zone's rect window, never the displayed zone itself —
-//! with a nil fileName, so the frame hides the quad (report B360). The world sheet's continent
-//! highlight is not built: hovering a continent there answers the nil/zero tail.
-//!
-//! Zone maps carry **exploration fog**: the base tiles are the unexplored parchment, and each
-//! discovered sub-area's overlay art (`GetNumMapOverlays`/`GetMapOverlayInfo`, filtered by the
-//! pushed `PLAYER_EXPLORED_ZONES` bitset) fills it in — the reference's own overlay pool draws
-//! the returned pieces. The landmark family (`GetNumMapLandmarks`/`GetMapLandmarkInfo`) answers
-//! with the `AreaPOI.dbc` rows the displayed level admits, then the guard-directions marker
-//! (decisions 1586, 1514).
+//! Deviation: `WORLD_MAP_UPDATE` fires at the next tick, where the reference fires it
+//! synchronously, because it only triggers a repaint and one tick is invisible.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One zone row in a continent's list. Its 1-based position IS the zone index Lua sees.
+/// One zone of a continent; its 1-based position is the Lua zone index.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapZoneView {
-    /// The display name (AreaTable's localized string — "Elwynn Forest").
+    /// `AreaTable.dbc`'s localized name, "Elwynn Forest".
     pub name: String,
-    /// The AreaTable id (the feed's player-zone resolution joins on this; phase 3 overlays too).
+    /// The `AreaTable.dbc` id the feed's player-zone resolution joins on.
     pub area_id: u32,
-    /// The `Interface\WorldMap\<file>\` art folder (WorldMapArea's internal name — "Elwynn").
+    /// The `Interface\WorldMap\<file>\` art folder, `WorldMapArea`'s internal name ("Elwynn").
     pub map_file: String,
-    /// This zone's WorldMapArea loc rect `(left, right, top, bottom)` — the window the continent
-    /// highlight sizes/seats against, and the rect the zone-level `ProcessMapClick` un-lerps
-    /// through (wow-re 15b2a8ea: the zone is a rect window onto the one per-continent bitmap).
+    /// The `WorldMapArea` loc rect `(left, right, top, bottom)`; at zone level, the grid's window.
     pub loc_rect: (f32, f32, f32, f32),
-    /// The zone's discovery overlays (WorldMapOverlay rows) — the art that fills the parchment
-    /// as sub-areas are explored (`GetNumMapOverlays`/`GetMapOverlayInfo`).
     pub overlays: Vec<WorldMapOverlayView>,
 }
 
-/// One **map landmark** — a POI icon on the displayed map (`GetNumMapLandmarks` /
-/// `GetMapLandmarkInfo`). The app projects it, so what arrives here is already map UV.
-///
-/// Two sources feed it, in the reference's own order (its builder `0x4a67a0`, VERIFIED in wow-re
-/// `system/ui/scratch/gossip-poi-marker.md` §8):
-///
-/// - the **`AreaPOI.dbc` rows** that survive the builder's level-flag, exploration and
-///   world-state gates — the town and capital icons, the capitals' "Under Attack" markers, and the
-///   Eastern Plaguelands towers (decision 1586);
-/// - then the **guard-directions marker** (`SMSG_GOSSIP_POI` — the flag a guard drops when you ask
-///   where the warrior trainer is), appended last as the one element with `+0x10 == 1` and exempt
-///   from every gate above.
+/// A POI icon on the displayed map, projected to map UV. The reference's builder (`0x4a67a0`)
+/// lists the `AreaPOI.dbc` rows past its level, exploration and world-state gates, then the
+/// guard-directions marker (`SMSG_GOSSIP_POI`, `+0x10 == 1`), ungated.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapLandmarkView {
-    /// The label its tooltip shows ("Stormwind Warrior Trainer").
     pub name: String,
-    /// The second tooltip line — a live status string on the AreaPOI rows that carry one (a
-    /// battleground node's "In Conflict"); empty for the guard marker.
+    /// The second tooltip line, a live status such as "In Conflict"; empty for the guard marker.
     pub description: String,
-    /// The `Interface\Minimap\POIIcons` cell, 8×8 grid (the guard marker's is `6` — the red flag).
+    /// The `Interface\Minimap\POIIcons` cell in its 8×8 grid.
     pub texture_index: u32,
-    /// Position on the DISPLAYED map, `[0,1]` UV from its top-left.
+    /// Position on the displayed map, UV from its top-left.
     pub uv: (f32, f32),
 }
 
-/// One discovery overlay: a sub-area's map art, drawn over the base tiles once any of its
-/// explore bits is set (decision 0203 phase 3).
+/// A sub-area's map art, drawn over the base tiles once any of its explore bits is set.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapOverlayView {
-    /// The full texture path prefix (`Interface\WorldMap\<Zone>\<TexName>`) — the reference Lua
-    /// appends the piece number (`..1`, `..2`, …) exactly as the client's C return does.
+    /// The path prefix `Interface\WorldMap\<Zone>\<TexName>`; the Lua appends the piece number.
     pub texture: String,
-    /// The overlay's art size in map px (the Lua slices it into 256-tiles with POT file sizes).
     pub width: u32,
     pub height: u32,
-    /// Placement within the 1002×668 detail frame, px from its TOPLEFT.
+    /// Placement in the 1002×668 detail frame, pixels from its top-left.
     pub offset_x: u32,
     pub offset_y: u32,
-    /// The AreaTable `exploreFlag` bit indices that reveal this overlay (any set bit shows it;
-    /// empty = never shown — an overlay whose areas are unknown).
+    /// The `AreaTable.dbc` exploreFlag bits that reveal it, any one sufficing; empty never shows.
     pub explore_bits: Vec<u32>,
-    /// The hover hit rect `(top, left, bottom, right)`, px of the 1002×668 detail frame — the
-    /// DBC's own `HitRect*` fields. The zone-level `UpdateMapHighlight` scales it by 1/1002 and
-    /// 1/668 and tests the normalized cursor against it, both edges inclusive (wow-re 15b2a8ea
-    /// §1d, `0x4a7ffc..0x4a80ea`).
+    /// The DBC's `HitRect*` `(top, left, bottom, right)` in detail-frame pixels, which the
+    /// zone-level hover tests with both edges inclusive (`0x4a7ffc..0x4a80ea`).
     pub hit_rect: (u32, u32, u32, u32),
-    /// The name that hover shows inside the rect: the localized AreaTable name of the overlay's
-    /// FIRST area slot (`0x4a7fa0` reads `+0x8` only). `None` when that slot resolves to no row —
-    /// the client then walks past the overlay exactly as if the cursor were outside it.
+    /// The hover name: the `AreaTable.dbc` name of the first area slot only (`0x4a7fa0` reads
+    /// `+0x8`); `None` walks past the overlay as if the cursor were outside.
     pub area_name: Option<String>,
 }
 
-/// One continent. Its 1-based position IS the continent index Lua sees.
+/// One continent; its 1-based position is the Lua continent index.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapContinentView {
-    /// The display name — Map.dbc's localized MapName ("Eastern Kingdoms", "Kalimdor"), the
-    /// client's own dropdown-label source (`0x4a65a0`; wow-re Q3(a) verdict), never the art
-    /// folder string.
+    /// `Map.dbc`'s localized MapName, the dropdown label (`0x4a65a0`), not the art folder.
     pub name: String,
-    /// The `Interface\WorldMap\<file>\` art folder.
     pub map_file: String,
-    /// This continent's rect on the world sheet, normalized UV `(u0, v0, u1, v1)` — world-level
-    /// `ProcessMapClick` picks the first continent (catalog order) containing the click, exactly
-    /// the client's AABB walk (`0x4a7100`'s world branch over the record trailer floats). The
-    /// app computes it with the verified `0x4a5d00` kernel (`map_proj::continent_sheet_rect`,
-    /// from the WorldMapContinent tile bounds); the 5875 rects are disjoint.
+    /// The rect on the world sheet in UV `(u0, v0, u1, v1)`, from the `WorldMapContinent` tile
+    /// bounds (`0x4a5d00`); a world-level click takes the first that holds it (`0x4a7100`).
     pub world_rect: (f32, f32, f32, f32),
-    /// The continent's WorldMapArea world rect (loc left/right/top/bottom) — the rect the
-    /// `0x4a6ec0` cell law un-lerps hover/click UVs through ([`area_grid_cell`]).
+    /// The `WorldMapArea` loc rect the cell law un-lerps a hover or click through.
     pub loc_rect: (f32, f32, f32, f32),
-    /// The 128×128 area bitmap, remapped app-side to **1-based zone indices** into
-    /// [`Self::zones`] (0 = no zone; empty = no bitmap shipped — hover/click inert). Row-major,
-    /// indexed by [`area_grid_cell`].
+    /// The 128×128 area bitmap (`<Continent>.zmp`, read at `0x4a5feb`) as 1-based indices into
+    /// [`Self::zones`], 0 for none; empty when no bitmap ships, leaving hover and click inert.
     pub zone_grid: Vec<u16>,
-    /// The continent's zones, in Lua index order.
     pub zones: Vec<WorldMapZoneView>,
 }
 
-/// The `0x4a6ec0` cell law, verbatim: clamp the UV, un-lerp through the continent's WorldMapArea
-/// rect back to world coords, quantize on the half-ADT world grid (2.9296876e-5 = 1/(64·533.33),
-/// the binary's 0x806544), range-check, index `col − row·128` (row is truncated from the negated
-/// axis, so it's ≤ 0). Verified against the shipped Azeroth.zmp: Goldshire's world position
-/// lands on cell 12735 = Elwynn Forest.
+/// The `0x4a6ec0` cell law: clamp the UV, un-lerp through the loc rect to world coordinates,
+/// scale by `0x806544` (1/(64·533.33)), range-check, and index `col - row·128`, `row` being
+/// truncated from the negated axis and so `<= 0`.
 fn area_grid_cell(loc: (f32, f32, f32, f32), u: f32, v: f32) -> Option<usize> {
     const K: f32 = 2.929_687_6e-5;
     let (left, right, top, bottom) = loc;
@@ -180,18 +111,11 @@ fn area_grid_cell(loc: (f32, f32, f32, f32), u: f32, v: f32) -> Option<usize> {
         .filter(|&i| i < 128 * 128)
 }
 
-/// The hovered/clicked child (zone OR city) at the current CONTINENT or ZONE selection: the grid
-/// cell's 1-based index into the continent's `zones`, or `None` off-land / off-grid / at world
-/// level. The rect that windows the one per-continent 128×128 bitmap is the continent's own loc
-/// rect at continent level, the CURRENT zone's loc rect at zone level — there is no per-zone
-/// bitmap, a zone/city is just a different rect window (wow-re 15b2a8ea, FUN_004a6ec0 §1c). This
-/// is what lets a click on a city's footprint from its neighbouring zone map drill into the city.
+/// The 1-based zone or city under a hover or click: the continent's one grid, windowed by its own
+/// loc rect at continent level and by the displayed zone's at zone level (`0x4a6ec0`).
 fn grid_area(state: &WorldMapState, u: f32, v: f32) -> Option<u16> {
-    // The direct-area state has no bitmap and is refused before the cell law runs: `0x4a6ec0`
-    // opens `cmp esi,-2; je 0x4a70ed` (wow-re `worldmap-direct-area-selection.md` §6) — the chain
-    // ships exactly three `.zmp` files and none of them is a battleground's. Explicit rather than
-    // left to `c == 0` below, because "the world sheet" and "an instance map" are different
-    // states that happen to share that cell.
+    // An instance map has no grid (`0x4a6ec0` opens `cmp esi,-2; je 0x4a70ed`); tested apart from
+    // `c == 0`, which the world sheet shares.
     if state.direct_area.is_some() {
         return None;
     }
@@ -215,8 +139,7 @@ fn grid_area(state: &WorldMapState, u: f32, v: f32) -> Option<u16> {
     }
 }
 
-/// Power-of-two round-up (≥ n, ≥ 1) — the client's `worldmap_pot_dim` round-up, used for the
-/// continent highlight's vertical texcoord crop (`texPercentageY = dim / potdim`).
+/// The client's power-of-two round-up (`0x4a833c`).
 fn next_pow2(n: i64) -> i64 {
     let mut p = 1i64;
     while p < n {
@@ -225,97 +148,58 @@ fn next_pow2(n: i64) -> i64 {
     p
 }
 
-/// The engine-side world-map state: the pushed catalog + feed, and the engine-owned selection.
+/// The engine-side world-map state: the pushed catalog and feed, and the selection.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldMapState {
-    /// The static catalog (pushed once at startup; empty until then — every binding degrades to
-    /// the world level, where `GetMapInfo` returns nil and the reference Lua falls back to
-    /// `"World"`).
+    /// The catalog, pushed once at startup; until then every binding answers as at world level.
     pub continents: Vec<WorldMapContinentView>,
-    /// The **orphan list** — the third array the reference's catalog builder fills (`0x4a5d00`'s
-    /// count/fill passes `0x4a6130`/`0x4a61c9`): every `WorldMapArea` row with `areaID != 0`
-    /// whose mapID matches **no** continent record, as `(row ID, the row)`, in DBC **file order,
-    /// unsorted** — the three battlegrounds in 5875. Keyed by id, never indexed: nothing outside
-    /// [`direct_row`]'s lookup reads a position here, because the selection stores the row's own
-    /// ID rather than a place in this list.
+    /// The orphan list the reference's catalog builder also fills (`0x4a6130`, `0x4a61c9`): each
+    /// `WorldMapArea` row with `areaID != 0` on no continent's map, the three battlegrounds.
     pub direct_areas: Vec<(u32, WorldMapZoneView)>,
-    /// The displayed map: `(continent, zone)`, `(0, 0)` = the world sheet. **Not the whole
-    /// selection on its own** — [`Self::direct_area`] overrides it.
+    /// The displayed `(continent, zone)`, `(0, 0)` the world sheet, unless [`Self::direct_area`].
     pub selection: (u32, u32),
-    /// The **direct-area selection**: the `WorldMapArea` row **ID** of an instance map, or `None`
-    /// at every continent/zone/world selection.
-    ///
-    /// The reference's selection is THREE `.data` cells, not two (wow-re
-    /// `worldmap-direct-area-selection.md` §1): `[0x84506c]` continent, `[0x845070]` zone,
-    /// `[0x845074]` direct. `continent == -2` IS this state, and the third cell then holds the
-    /// row's own id — **not** an index into [`Self::direct_areas`], which is only ever a lookup
-    /// table. The setter `0x4a67a0` keeps the two exclusive (`0x4a67c1` stores the id only on the
-    /// `ecx == -2` leg and jumps past `0x4a67ea`'s `= -1`; every other leg reaches it), so
-    /// `direct_area.is_some()` ⇒ `selection == (0, 0)` — enforced in [`store_selection`], the one
-    /// writer.
+    /// An instance map's `WorldMapArea` row id: the reference's third selection cell `[0x845074]`
+    /// beside continent `[0x84506c]` (then -2) and zone `[0x845070]`. The setter `0x4a67a0` keeps
+    /// it exclusive with the pair (`0x4a67c1`, `0x4a67ea`); [`store_selection`] is the one writer.
     pub direct_area: Option<u32>,
-    /// Where `SetMapToCurrentZone` lands — the player's current `(continent, zone)` resolved by
-    /// the app (AreaTable parent walk × the catalog). `None` = no continent matched → either the
-    /// orphan leg below, or the world sheet.
+    /// The player's `(continent, zone)`, where `SetMapToCurrentZone` lands.
     pub player_zone: Option<(u32, u32)>,
-    /// The orphan half of that same answer: the `WorldMapArea` row ID whose mapID is the player's
-    /// own map, or `None`. `0x4a6650` runs its continent loop FIRST and reaches the orphan loop
-    /// only on a miss (`0x4a66c3`), so at most one of the two is ever set — and inside a
-    /// battleground it is this one.
+    /// The resolver's orphan leg, the `WorldMapArea` row id on the player's map. `0x4a6650`
+    /// reaches it only when its continent loop misses (`0x4a66c3`), so at most one is set.
     pub player_direct_area: Option<u32>,
-    /// `GetPlayerMapPosition("player")` for the CURRENT selection — projected app-side each frame
-    /// (`map_proj`), `None`/(0,0) = off this map (the reference hides the blip).
+    /// `GetPlayerMapPosition("player")` on the displayed map; `None` is off it.
     pub player_uv: Option<(f32, f32)>,
-    /// The world map's arrow frame and the battlefield minimap's — the two per-session
-    /// singletons `CreateWorldMapArrowFrame`/`CreateMiniWorldMapArrowFrame` build, by wrapper id
-    /// (`worldmap_arrow`, 1980). `None` until the first create.
+    /// The arrow frames' wrapper ids, built once per session; `None` until created.
     pub arrow_world: Option<u32>,
     pub arrow_mini: Option<u32>,
-    /// `GetPlayerMapPosition("party1".."party4")` for the CURRENT selection, in `party_slots`
-    /// order — projected app-side through the same law as [`Self::player_uv`] (report B320).
-    /// A slot is `None` when there is no member there, when we hold no position for them, or when
-    /// that position is off the displayed map; all three read as the reference's `(0,0)` hide
-    /// sentinel at the binding, which is the only answer its FrameXML consumer knows.
-    ///
-    /// Shorter than 4 whenever the party is: a missing index is a `None`.
+    /// `party1`..`party4` in `party_slots` order; `None` or missing answers `(0, 0)`.
     pub party_uv: Vec<Option<(f32, f32)>>,
-    /// `raid1..raid40` in roster order — the stock map's raid arm (1980), fed like `party_uv`.
+    /// `raid1`..`raid40` in roster order, fed like [`Self::party_uv`].
     pub raid_uv: Vec<Option<(f32, f32)>>,
-    /// `GetPlayerFacing()` — wow orientation radians (0 = north, counterclockwise-positive). Our
-    /// transcribed frame spins its arrow texture with it (`SetRotation`); the reference rotates
-    /// an engine-rendered arrow model instead (0203 flags the stand-in).
+    /// Radians, 0 north, counterclockwise-positive; `UpdateWorldMapArrowFrames` turns the arrows.
     pub player_facing: f32,
-    /// `GetCorpseMapPosition()` for the CURRENT selection — the corpse-run marker (decision 0308
-    /// §5), projected app-side like [`Self::player_uv`]; `None`/(0,0) = no corpse or off this map
-    /// (the reference's WorldMapFrame.lua:443-452 hide law).
+    /// `GetCorpseMapPosition()` on the displayed map; `None` is no corpse or off the map.
     pub corpse_uv: Option<(f32, f32)>,
-    /// The discovery bitset (`PLAYER_EXPLORED_ZONES_1` — 64 u32 = 2048 bits, bit n = AreaTable
-    /// exploreFlag n), pushed by the app when the descriptor changes. Empty = nothing explored.
+    /// `PLAYER_EXPLORED_ZONES_1`, 64 words, bit n being `AreaTable.dbc` exploreFlag n.
     pub explored: Vec<u32>,
-    /// The POI icons on the displayed map (`GetNumMapLandmarks`/`GetMapLandmarkInfo`), already
-    /// projected into its UV — pushed by the app on change, which repaints an open map.
     pub landmarks: Vec<WorldMapLandmarkView>,
 }
 
-/// Is explore-bit `n` set in the pushed bitset?
 fn explored_bit(explored: &[u32], n: u32) -> bool {
     explored
         .get((n / 32) as usize)
         .is_some_and(|w| w & (1 << (n % 32)) != 0)
 }
 
-/// The reciprocals `0x4a7fa0` scales a `WorldMapOverlay` hit rect by: the rect is authored in
-/// pixels of the 1002×668 detail frame, the cursor arrives normalized, and the client brings the
-/// rect to the cursor (`fild` → `fmul` a f32 constant → `fstp dword`), so the edges are f32.
+/// The f32 reciprocals `0x4a7fa0` scales a hit rect's detail-frame pixels by (`fild`, `fmul`,
+/// `fstp dword`) to meet the normalized cursor, so the edges are f32.
 const OVERLAY_RECIP_X: f32 = 1.0 / 1002.0;
 const OVERLAY_RECIP_Y: f32 = 1.0 / 668.0;
 
-/// The zone-level **overlay pre-search** (`0x4a7ffc..0x4a80ea`, wow-re 15b2a8ea §1d): the first
-/// REVEALED overlay whose hit rect contains the cursor names its first area. Both edges are
-/// inclusive; a rect with a zero-width edge never hits; a NaN cursor never hits; an overlay whose
-/// first area resolves to no AreaTable row is walked past, not stopped at. The list is the one
-/// `GetNumMapOverlays` counts — the exploration-gated one (`[0xb6e630]`, built by `0x4a6ad9`
-/// under the explored-byte read at `0x4a6bfa`), so a fogged sub-area has no name.
+/// The zone-level overlay pre-search (`0x4a7ffc..0x4a80ea`): the first revealed overlay whose hit
+/// rect holds the cursor, edges inclusive, names its first area; a zero-width rect or a NaN cursor
+/// never hits, and a nameless overlay is walked past. The list is the revealed one (`[0xb6e630]`,
+/// built by `0x4a6ad9`, gated at `0x4a6bfa`), so a fogged sub-area has no name.
 fn overlay_hover(state: &WorldMapState, x: f32, y: f32) -> Option<String> {
     revealed_overlays(state).into_iter().find_map(|o| {
         let (top, left, bottom, right) = o.hit_rect;
@@ -341,8 +225,6 @@ fn overlay_hover(state: &WorldMapState, x: f32, y: f32) -> Option<String> {
 
 /// What `UpdateMapHighlight` answers for a cursor at map UV `(x, y)` under the current selection.
 enum Hover {
-    /// Continent level, over a zone: its name and the highlight quad — fileName, texPercentageY,
-    /// textureX/Y, scrollChildX/Y (texPercentageX is that branch's constant 1.0).
     Highlight {
         name: String,
         file: String,
@@ -350,16 +232,13 @@ enum Hover {
         texture: (f64, f64),
         scroll: (f64, f64),
     },
-    /// Zone level: a name only — fileName nil, six zeros, the frame hides the quad.
     Name(String),
-    /// Off every area: the nil/zero tail.
     Miss,
 }
 
-/// The continent-level answer for the hovered zone (the `0x4a81de → 0x4a822a` highlight-compute
-/// path, zone-search branch): fileName = its art folder (the frame draws `<file>\<file>Highlight`),
-/// the six coords seat/size/crop that texture over the zone's rect within the continent, keeping
-/// the client's f32/f64 asymmetric narrowing.
+/// The continent-level highlight (`0x4a81de` → `0x4a822a`): the zone's art folder, drawn as
+/// `<file>\<file>Highlight`, and the coords seating it over the zone's rect in the client's mixed
+/// f32 and f64.
 fn continent_hover(cont: &WorldMapContinentView, zone: &WorldMapZoneView) -> Option<Hover> {
     let (cl, cr, ct, cb) = cont.loc_rect;
     let (zl, zr, zt, zb) = zone.loc_rect;
@@ -374,7 +253,7 @@ fn continent_hover(cont: &WorldMapContinentView, zone: &WorldMapZoneView) -> Opt
     let texture_y = (1.0f64 / f64::from(cont_h)) * f64::from(h);
     let scroll_x = f64::from(recip_x * (cl - zl));
     let scroll_y = f64::from(recip_y_f32 * (ct - zt));
-    // texPctY = dim/potdim, dim = __ftol((h·128)/w) (rect-form K = 128).
+    // texPctY = dim / potdim, dim = __ftol(h·128 / w).
     let dim = ((h * 128.0) / w) as i64;
     let potdim = next_pow2(dim);
     let tex_pct_y = if potdim > 0 {
@@ -391,14 +270,12 @@ fn continent_hover(cont: &WorldMapContinentView, zone: &WorldMapZoneView) -> Opt
     })
 }
 
-/// `0x4a7fa0`'s level dispatch (wow-re 15b2a8ea §1a). Continent level: the grid cell's zone lights
-/// up. Zone level: the overlay pre-search first, then the same grid re-windowed by the displayed
-/// zone's own rect (`0x4a7620`), which returns nothing for the displayed zone itself — and only the
-/// name-only tail is reachable from there (`0x4a812e`). World level: the continent highlight is
-/// not built, so the tail.
+/// `0x4a7fa0`'s level dispatch. Continent level: the grid's zone highlights. Zone level: the
+/// overlay pre-search, then the grid through the displayed zone's rect (`0x4a7620`), naming a
+/// neighbour but never the displayed zone, name only (`0x4a812e`). World level: the tail, as the
+/// continent highlight the reference draws there is not built here.
 fn hover(wm: &WorldMapState, x: f32, y: f32) -> Hover {
-    // An instance map resolves no area under the cursor: the lookup INSIDE `UpdateMapHighlight`
-    // (`0x4a7620`) opens `cmp esi,-2; je 0x4a76d7` → `xor eax,eax`, so no highlight and no name.
+    // An instance map resolves no area (`0x4a7620` opens `cmp esi,-2; je 0x4a76d7`).
     if wm.direct_area.is_some() {
         return Hover::Miss;
     }
@@ -424,10 +301,8 @@ fn hover(wm: &WorldMapState, x: f32, y: f32) -> Hover {
         .unwrap_or(Hover::Miss)
 }
 
-/// The selected direct area's row, resolved by **id** through the orphan list — the reference's
-/// `[0xc0d5bc]` id-index lookup (`0x4a6cf0`'s `0x4a6d24` leg), which bound-checks on every read
-/// rather than trusting the stored cell. An id no row carries reads back as `None`, which is the
-/// binary's own NULL → `lua_pushnil`.
+/// The direct area's row by id, bound-checked as the reference's `[0xc0d5bc]` lookup is
+/// (`0x4a6d24`); an id no row carries is `None`, its NULL.
 fn direct_row(state: &WorldMapState) -> Option<&WorldMapZoneView> {
     let id = state.direct_area?;
     state
@@ -437,11 +312,8 @@ fn direct_row(state: &WorldMapState) -> Option<&WorldMapZoneView> {
         .map(|(_, row)| row)
 }
 
-/// The displayed map's `WorldMapArea` row, if one is displayed: the selected zone, or — in the
-/// direct-area state — the instance map's own row. `0x4a6cf0` resolves both through the same id
-/// lookup, and `0x4a67a0`'s overlay half admits the `-2` state with the displayed key
-/// `= [0x845074]` (wow-re `worldmap-overlay-reveal-gate.md` §2), so a battleground's overlays
-/// reveal under the explored-bit gate exactly as a zone's do — no free reveal.
+/// The displayed zone's or instance map's row; `0x4a67a0` keys the -2 state's overlays by
+/// `[0x845074]`, so an instance map's pass the same explored-bit gate.
 fn current_zone(state: &WorldMapState) -> Option<&WorldMapZoneView> {
     if state.direct_area.is_some() {
         return direct_row(state);
@@ -457,7 +329,7 @@ fn current_zone(state: &WorldMapState) -> Option<&WorldMapZoneView> {
         .get(z as usize - 1)
 }
 
-/// The displayed zone's REVEALED overlays, in catalog order (the i-th is `GetMapOverlayInfo(i)`).
+/// The displayed zone's revealed overlays in catalog order, the i-th `GetMapOverlayInfo(i)`.
 fn revealed_overlays(state: &WorldMapState) -> Vec<&WorldMapOverlayView> {
     current_zone(state)
         .map(|zone| {
@@ -474,8 +346,7 @@ fn revealed_overlays(state: &WorldMapState) -> Vec<&WorldMapOverlayView> {
 }
 
 impl super::UiScript {
-    /// Push the static catalog (startup, once the DBCs are read). Queues `WORLD_MAP_UPDATE` so an
-    /// already-open frame repaints (startup normally precedes any frame, harmlessly).
+    /// Pushes the catalog at startup, queueing `WORLD_MAP_UPDATE` so an open map repaints.
     pub fn set_world_map_catalog(&mut self, continents: Vec<WorldMapContinentView>) {
         let mut model = self.model_mut();
         model.worldmap.continents = continents;
@@ -484,9 +355,7 @@ impl super::UiScript {
             .push(("WORLD_MAP_UPDATE".to_string(), Vec::new()));
     }
 
-    /// Push the **orphan list** — the instance maps, keyed by `WorldMapArea` row id (see
-    /// [`WorldMapState::direct_areas`]). Pushed beside the continent catalog at the same edge and
-    /// for the same reason; the reference fills both containers in one walk (`0x4a5d00`).
+    /// Pushes the orphan list beside the catalog, both filled in one walk (`0x4a5d00`).
     pub fn set_world_map_direct_areas(&mut self, direct_areas: Vec<(u32, WorldMapZoneView)>) {
         let mut model = self.model_mut();
         model.worldmap.direct_areas = direct_areas;
@@ -495,17 +364,12 @@ impl super::UiScript {
             .push(("WORLD_MAP_UPDATE".to_string(), Vec::new()));
     }
 
-    /// Push the resolver's **orphan leg** for the player — the `WorldMapArea` row id whose map is
-    /// the player's own, or `None` (see [`WorldMapState::player_direct_area`]). The continent/zone
-    /// leg rides [`Self::set_world_map_feed`]'s `player_zone`; `0x4a6650` computes both in one
-    /// pass and reaches this one only when that one missed.
+    /// Pushes the resolver's orphan leg; the continent leg rides [`Self::set_world_map_feed`].
     pub fn set_world_map_player_direct_area(&mut self, direct_area: Option<u32>) {
         self.model_mut().worldmap.player_direct_area = direct_area;
     }
 
-    /// Push the discovery bitset (the app calls this when `PLAYER_EXPLORED_ZONES` changes —
-    /// including the first stream-in). Queues `WORLD_MAP_UPDATE` so an open zone map fills in
-    /// newly explored art immediately.
+    /// Pushes the discovery bitset; a change queues `WORLD_MAP_UPDATE` so an open map fills in.
     pub fn set_world_map_explored(&mut self, explored: Vec<u32>) {
         let mut model = self.model_mut();
         if model.worldmap.explored != explored {
@@ -516,9 +380,7 @@ impl super::UiScript {
         }
     }
 
-    /// Push the displayed map's landmarks (the app projects them; see [`WorldMapLandmarkView`]).
-    /// On change, queues `WORLD_MAP_UPDATE` — the repaint that re-seats the POI icons, exactly
-    /// the event the overlay push above uses for the same reason.
+    /// Pushes the displayed map's landmarks; a change queues `WORLD_MAP_UPDATE` to re-seat them.
     pub fn set_world_map_landmarks(&mut self, landmarks: Vec<WorldMapLandmarkView>) {
         let mut model = self.model_mut();
         if model.worldmap.landmarks != landmarks {
@@ -529,8 +391,7 @@ impl super::UiScript {
         }
     }
 
-    /// Push the per-frame feed (player zone/projection/facing, the corpse marker, and the party
-    /// slots' projections — see [`WorldMapState`]).
+    /// Pushes the per-frame feed: the player's zone, the projected positions and the facing.
     pub fn set_world_map_feed(
         &mut self,
         player_zone: Option<(u32, u32)>,
@@ -549,32 +410,18 @@ impl super::UiScript {
         model.worldmap.raid_uv = raid_uv;
     }
 
-    /// The engine-owned selection — the app reads it each frame to project the feed for the
-    /// displayed map. **All three of the reference's cells**, in its own order: the continent and
-    /// zone pair (`0` = whole), then the direct-area row id
-    /// ([`WorldMapState::direct_area`]) which overrides both when it is `Some`. A consumer that
-    /// reads only the pair sees an instance map as the world sheet — which is precisely the bug
-    /// that left the battle map empty — so the third cell travels with them.
+    /// The selection's three cells, which the app reads each frame to project the feed: continent,
+    /// zone, and the direct-area id that overrides them when `Some`. The pair alone reads an
+    /// instance map as the world sheet.
     pub fn world_map_selection(&self) -> (u32, u32, Option<u32>) {
         let wm = &self.model_ref().worldmap;
         (wm.selection.0, wm.selection.1, wm.direct_area)
     }
 
-    /// Move the selection **from the engine**, with no Lua in the loop — the reference's
-    /// `SetMap` setter `0x4a67a0` reached from the zone updater `0x494780` rather than from a
-    /// binding, which is how a freshly-logged-in client already shows the player's own zone.
-    ///
-    /// The reference has TWO writers of `[0x84506c]`/`[0x845070]`: the Lua verbs
-    /// (`SetMapZoom`/`SetMapToCurrentZone`/`ProcessMapClick`), and this one. We only ever had the
-    /// first, so until some addon opened the map we sat at the world level — and at the world
-    /// level `GetPlayerMapPosition` answers a world-SHEET uv (`0x4a7360` step 2), which every
-    /// addon that assumes a zone uv silently mis-scales. See [`crate::script::worldmap`]'s caller
-    /// in `ui_world_map::feed_world_map` for the gate.
-    ///
-    /// It takes the resolver's whole answer — including the orphan leg — because `0x4947ac` calls
-    /// `0x4a6650`, the same resolver `SetMapToCurrentZone` does: a player logging straight into a
-    /// battleground is on the battleground's own map before any Lua runs, exactly as one logging
-    /// into Elwynn is on Elwynn's.
+    /// Moves the selection from the engine, as the zone updater `0x494780` calls the setter
+    /// `0x4a67a0`: a fresh login shows the player's map before any Lua runs, not the world sheet,
+    /// whose `GetPlayerMapPosition` is sheet UV (`0x4a7360`). It takes the resolver's whole
+    /// answer, orphan leg included, as `0x4947ac` calls `0x4a6650`.
     pub fn sync_world_map_to_player_zone(
         &mut self,
         continent: u32,
@@ -585,27 +432,15 @@ impl super::UiScript {
         select_resolved(&mut model, continent, zone, direct_area);
     }
 
-    /// The **normalized position within the map art** at UI-space `(x, y)`, or `None` when the
-    /// point isn't over it. Reproduces the reference's own click normalization verbatim —
-    /// `WorldMapFrame.xml`'s `WorldMapButton_OnClick`: `u = (x − left)/width`,
-    /// `v = (top − y)/height` over `WorldMapButton`'s rect — so the UV handed back is the same one
-    /// [`ProcessMapClick`](install) reads and the same one the blips are placed in. The Lua's
-    /// effective-scale division cancels here: point and rect are both already in screen units.
-    ///
-    /// A pure query (fires nothing, mutates nothing). Its consumer is the app-side dev map-jump,
-    /// which needs a click's UV *without* going through the faithful click path — that path drills
-    /// into a zone, and the reference's law for it must not grow a second meaning.
+    /// The map UV at UI point `(x, y)`, or `None` off the art, normalized over `WorldMapButton`
+    /// as `WorldMapButton_OnClick` does (WorldMapFrame.lua:287-291). A pure query for the app's
+    /// dev map-jump, which must not drill in as the click path does.
     pub fn world_map_uv_at(&self, x: f32, y: f32) -> Option<(f32, f32)> {
         let id = self.hit_test(x, y)?;
         let model = self.model_ref();
         let hit = model.id_to_frame.get(&id).copied()?;
-        // The map button, or **anything sitting on it**: the stock file makes every POI icon a
-        // child of `WorldMapButton` (`WorldMapFrame.lua:178`), and so are the player arrow's clear
-        // button and the party/raid blips, so the topmost frame over a town or a teammate is one
-        // of those and not the button. Requiring the button itself made the click deaf exactly
-        // where the map has something to show — the director's report on the stock map. Walking
-        // up rather than widening the name test keeps everything else out: a click on the
-        // continent dropdown or the close button is over neither the button nor its subtree.
+        // The button or anything on it: POI icons (WorldMapFrame.lua:178), the player arrow's
+        // button and the blips are its children and sit on top.
         let mut fh = hit;
         while model.arena.frame(fh)?.name.as_deref() != Some("WorldMapButton") {
             fh = model.arena.frame(fh)?.parent?;
@@ -616,11 +451,8 @@ impl super::UiScript {
     }
 }
 
-/// **The one writer of the three selection cells** — `0x4a67a0`, whose whole job is that the
-/// continent/zone pair and the direct-area id can never both be live: the setter's valid-continent
-/// leg and its `-1` leg both fall into `0x4a67ea mov [0x845074],eax` (`= -1`), and only `ecx == -2`
-/// jumps past it after storing the id (`0x4a67c1`), having already forced the zone cell to `-1`.
-/// Every selection verb in this module goes through here, so neither half can be moved alone.
+/// The one writer of the three selection cells, as the setter `0x4a67a0` is: every leg but
+/// `ecx == -2` clears the direct cell (`0x4a67ea`), and that one stores the id (`0x4a67c1`).
 fn store_selection(model: &mut Model, selection: (u32, u32), direct_area: Option<u32>) {
     model.worldmap.selection = selection;
     model.worldmap.direct_area = direct_area;
@@ -629,9 +461,8 @@ fn store_selection(model: &mut Model, selection: (u32, u32), direct_area: Option
         .push(("WORLD_MAP_UPDATE".to_string(), Vec::new()));
 }
 
-/// Clamp + store a continent/zone selection and queue the repaint event. The shared tail of
-/// `SetMapZoom`/`SetMapToCurrentZone`/`ProcessMapClick` — and it **clears the direct area**, which
-/// is the setter invariant above.
+/// Clamps and stores a continent and zone, clearing the direct area: the tail of `SetMapZoom`,
+/// `SetMapToCurrentZone` and `ProcessMapClick`.
 fn select(model: &mut Model, continent: i64, zone: i64) {
     let c = continent.clamp(0, model.worldmap.continents.len() as i64) as u32;
     let z = if c == 0 {
@@ -643,22 +474,14 @@ fn select(model: &mut Model, continent: i64, zone: i64) {
     store_selection(model, (c, z), None);
 }
 
-/// Select an instance map directly — `0x4a67a0` reached with `ecx == -2`: the zone cell goes to
-/// `-1` (our `0`) and the raw `WorldMapArea` row id lands in `[0x845074]` **verbatim and
-/// unchecked**. We keep it unchecked for the same reason the reference can: every consumer
-/// bound-checks on read ([`direct_row`]), so an id no row carries degrades to the nil map name
-/// instead of corrupting the selection.
+/// Selects an instance map, `0x4a67a0` with `ecx == -2`: the zone cell goes to -1 (our 0) and the
+/// row id is stored unchecked, as every reader bound-checks it ([`direct_row`]).
 fn select_direct(model: &mut Model, wma_id: u32) {
     store_selection(model, (0, 0), Some(wma_id));
 }
 
-/// Apply the resolver `0x4a6650`'s answer — the shared tail of `SetMapToCurrentZone` (`0x4a7e20`
-/// is literally `call 0x4a6650`) and of the engine's own first-world-enter sync (`0x4947ac`, the
-/// same function: there is no second resolver).
-///
-/// The orphan leg wins when it is set, and it is set only when no continent matched — the
-/// reference reaches `0x4a66c3` exclusively through the continent loop's miss, so the two answers
-/// are mutually exclusive by construction upstream and the order here is belt-and-braces.
+/// Applies the resolver `0x4a6650`'s answer, the tail of `SetMapToCurrentZone` and of the login
+/// sync (`0x4947ac`).
 fn select_resolved(model: &mut Model, continent: u32, zone: u32, direct_area: Option<u32>) {
     match direct_area {
         Some(id) => select_direct(model, id),
@@ -670,7 +493,7 @@ fn select_resolved(model: &mut Model, continent: u32, zone: u32, direct_area: Op
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetMapContinents() → name1, name2, … (the dropdown list; index = continent number).
+    // GetMapContinents() → the continent names, in index order.
     g.set(
         "GetMapContinents",
         lua.create_function(|lua, ()| {
@@ -685,12 +508,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMapZones(continent) → name1, name2, … (that continent's zone list; index = zone number).
-    // A NEGATIVE continent answers empty — `0x4a7d10`'s `dec edi; cmp edi,[0xb6e664]; jae` is an
-    // unsigned bound, so `GetCurrentMapContinent()`'s `-1` on an instance map takes the empty
-    // exit. That emptiness is load-bearing: it is what leaves `WorldMapZoneButton_OnClick` with
-    // no button to fire, and so what stops a `SetMapZoom(-1, id)` from writing a bogus row id
-    // into the direct cell (wow-re §5.4).
+    // GetMapZones(continent) → the zone names. A negative continent answers none, as `0x4a7d10`'s
+    // bound is unsigned (`dec edi; cmp edi,[0xb6e664]; jae`): an instance map's empty zone list is
+    // what keeps `WorldMapZoneButton_OnClick` from calling `SetMapZoom(-1, id)`.
     g.set(
         "GetMapZones",
         lua.create_function(|lua, c: i64| {
@@ -709,13 +529,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCurrentMapContinent() / GetCurrentMapZone() — the selection halves (0 = world / whole
-    // continent). The reference reads them right after SetMapZoom in the same click. Each is its
-    // cell `+ 1` and nothing else (`0x4a7ed0`, `0x4a7f00`: a straight-line fild/pushnumber), so
-    // the direct-area state answers **-1** (from the `-2` sentinel) and **0** (the zone cell it
-    // forces to `-1`). The `-1` is a value no stock path tests for, and benignly: it leaves
-    // `WorldMapFrame.lua:59`'s zoom-out button enabled, and the zone dropdown it would feed is
-    // empty because `GetMapZones(-1)` takes the unsigned-bound exit below.
+    // GetCurrentMapContinent() / GetCurrentMapZone(): each cell plus one (`0x4a7ed0`, `0x4a7f00`),
+    // so an instance map answers -1 and 0.
     g.set(
         "GetCurrentMapContinent",
         lua.create_function(|lua, ()| {
@@ -734,7 +549,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetMapZoom(continent[, zone]) — the dropdowns' and zoom-out button's navigation verb.
     g.set(
         "SetMapZoom",
         lua.create_function(|lua, (c, z): (i64, Option<i64>)| {
@@ -744,10 +558,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // SetMapToCurrentZone() — the OnShow verb: jump to the player's own map (app-resolved feed).
-    // `0x4a7e20` is `call 0x4a6650; xor eax,eax; ret`, so this is the resolver's whole answer,
-    // orphan leg included — which is what puts a player standing in Warsong Gulch on the Warsong
-    // Gulch map. The stock battlefield minimap calls it itself on PLAYER_ENTERING_WORLD.
+    // SetMapToCurrentZone(): the resolver's whole answer, orphan leg included (`0x4a7e20` is
+    // `call 0x4a6650; xor eax,eax; ret`).
     g.set(
         "SetMapToCurrentZone",
         lua.create_function(|lua, ()| {
@@ -759,23 +571,16 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMapInfo() → mapFileName (the Interface\WorldMap\<name>\ folder). World level → nil —
-    // the reference Lua's own `"World"` fallback exists because the client returned nil there
-    // (wow-re `worldmap-direct-area-selection.md` §5.1/§5.3).
-    //
-    // The name is `WorldMapArea` field[3], the **art-folder identifier** — "WarsongGulch", never
-    // the localized "Warsong Gulch": `0x4a6cf0` reads `[row+0xc]` with no locale multiplier, in
-    // deliberate contrast to `0x4a8740`'s `[rec + 4*[0xc0e080] + 0x2c]` AreaTable read. That is
-    // why FrameXML interpolates it straight into `Interface\WorldMap\<name>\<name>1..12`.
+    // GetMapInfo() → mapFileName and two texture dimensions (`0x4a7e30`, `mov eax,3`): nil, 0, 0
+    // at world level. The name is the unlocalized art folder (`0x4a6cf0` reads `[row+0xc]`).
     g.set(
         "GetMapInfo",
         lua.create_function(|lua, ()| {
             let model = lua.app_data_ref::<Model>().expect("model app_data");
             let wm = &model.worldmap;
             let file = match (wm.direct_area, wm.selection) {
-                // The direct-area state — an instance map, resolved by id through the orphan
-                // list. `0x4a6cf0`'s `jl 0x4a6d24` sends BOTH negative continents here and the
-                // `-1` world level answers nil only because its third cell is `-1` too.
+                // An instance map, by id through the orphan list: `0x4a6cf0`'s `jl 0x4a6d24`
+                // sends both negative continents there, and world level's third cell is -1.
                 (Some(_), _) => direct_row(wm).map(|row| row.map_file.clone()),
                 (None, (0, _)) => None,
                 (None, (c, z)) => wm.continents.get(c as usize - 1).map(|cont| match z {
@@ -787,18 +592,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
                         .unwrap_or_else(|| cont.map_file.clone()),
                 }),
             };
-            // THREE values, always: `0x4a7e30` pushes all three unconditionally and returns
-            // `mov eax,3` from its single `ret`, so the world-level answer is `nil, 0, 0` rather
-            // than one nil. (Its four conditional jumps all sit inside slot 3's power-of-two
-            // round and none gates a push — wow-re §10 corrects the "no conditional jump at all"
-            // absolute this comment used to carry, without touching the conclusion.
-            // `arity_conf = exact`; decision 1845.)
-            //
-            // The two zeros are the map art's texture dimensions, which no caller reads: both
-            // consumers bind slot 2 to a `textureHeight` local they never read again. They are
-            // **0 on every instance map** in the reference too — `0x4a6d50` scans
-            // `WorldMapContinent.dbc` for the row's mapID and that table ships only mapIDs
-            // {0, 1}, so the scan exhausts (§5.2).
+            // No caller reads the dimensions, 0 here on every map; the reference computes them
+            // from `WorldMapContinent.dbc` (`0x4a6d50`), which lacks an instance map's mapID.
             let file = match file {
                 Some(f) => Value::String(lua.create_string(&f)?),
                 None => Value::Nil,
@@ -807,8 +602,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetCorpseMapPosition() → x, y in [0,1] map UV; (0,0) = no corpse / not on this map — the
-    // reference's hide sentinel (WorldMapFrame.lua:445), same shape as the player position below.
+    // GetCorpseMapPosition() → map UV, or (0, 0), which WorldMapFrame.lua:445 hides.
     g.set(
         "GetCorpseMapPosition",
         lua.create_function(|lua, ()| {
@@ -818,9 +612,8 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerMapPosition(unit) → x, y in [0,1] map UV; (0,0) = not on this map (hide the
-    // blip). `"player"`, `"party1".."party4"` (report B320) and `"raid1".."raid40"` (1980, the
-    // stock map's raid arm over its `WorldMapRaid1..40` pool) resolve; anything else is (0,0).
+    // GetPlayerMapPosition(unit) → map UV, or (0, 0) off the map; `player`, `party1`..`party4`
+    // and `raid1`..`raid40` resolve, anything else is (0, 0).
     g.set(
         "GetPlayerMapPosition",
         lua.create_function(|lua, unit: String| {
@@ -842,9 +635,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetPlayerFacing() → wow orientation radians (counterclockwise-positive, 0 = north). Feeds
-    // the transcribed frame's arrow SetRotation (the reference's engine arrow reads facing
-    // natively; a Lua-visible getter is our seam for the texture stand-in).
+    // GetPlayerFacing() → the facing in radians. Not a 1.12 global.
     g.set(
         "GetPlayerFacing",
         lua.create_function(|lua, ()| {
@@ -853,21 +644,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // ProcessMapClick(x, y) — normalized click within WorldMapButton (wow-re 15b2a8ea, Part 2).
-    // World level: pick the first continent whose sheet-rect contains the click (the 0x4a7100
-    // AABB walk; the 5875 rects are disjoint). Continent OR zone level: identical instructions —
-    // the 0x4a6ec0 grid cell through the CURRENT selection's rect (the continent's, or the current
-    // zone's) → a continent child index → drill. Because a city is just another child, a click on
-    // its footprint — from the continent map, or from a neighbouring zone map when the footprint
-    // falls in that zone's window — drills into the city's own map.
+    // ProcessMapClick(x, y) (`0x4a7f30`): at world level the first continent whose sheet rect
+    // holds the click (`0x4a7100`); otherwise the zone or city under it through the displayed
+    // rect (`0x4a6ec0`), which it drills into.
     g.set(
         "ProcessMapClick",
         lua.create_function(|lua, (x, y): (f32, f32)| {
             let mut model = lua.app_data_mut::<Model>().expect("model app_data");
-            // An instance map swallows the click: the drill INSIDE `ProcessMapClick`
-            // (`0x4a7540`) opens `cmp esi,-2; je 0x4a760d`, a bare epilogue. Ahead of the world
-            // arm below, because the direct state shares its `continent == 0` cell and must not
-            // fall into the world sheet's continent walk.
+            // An instance map swallows the click (`0x4a7540` opens `cmp esi,-2; je 0x4a760d`),
+            // tested first as it shares the world sheet's `continent == 0`.
             if model.worldmap.direct_area.is_some() {
                 return Ok(());
             }
@@ -888,9 +673,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // UpdateMapHighlight(x, y) → name, fileName, texPctX, texPctY, textureX, textureY,
-    // scrollChildX, scrollChildY (wow-re 15b2a8ea, 0x4a7fa0) — the per-level law is [`hover`].
-    // Eight values always: the frame reads `fileName` to decide whether a quad is drawn at all,
-    // so a name-only answer carries a nil there and six zeros behind it.
+    // scrollChildX, scrollChildY (`0x4a7fa0`): eight values always, a nil fileName hiding the quad.
     g.set(
         "UpdateMapHighlight",
         lua.create_function(|lua, (x, y): (f32, f32)| {
@@ -922,8 +705,6 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumMapLandmarks() — how many POI icons the displayed map carries: the `AreaPOI.dbc` rows
-    // that pass the builder's gates, then the guard-directions marker.
     g.set(
         "GetNumMapLandmarks",
         lua.create_function(|lua, ()| {
@@ -932,15 +713,9 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetMapLandmarkInfo(i) → name, description, textureIndex, x, y — the i-th (1-based) landmark
-    // (return shape VERIFIED at `0x4a8740`, wow-re `system/ui/scratch/gossip-poi-marker.md`).
-    // `textureIndex` indexes `Interface\Minimap\POIIcons`' 8×8 grid, already resolved app-side
-    // through the reference's own leg (`0x4a8848`): a row's `Icon`, or the constant 15 at zone
-    // level unless it carries `Flags & 0x80`; the guard's marker is its packet `Icon` verbatim.
-    // x/y are `[0,1]` UV on the displayed map, the same space `GetPlayerMapPosition` answers in. A
-    // landmark with no description answers **nil** there, as the reference does (`0x6f3890` pushes
-    // nil on a NULL string) — the guard's marker never carries one, and neither do the ~2/3 of
-    // AreaPOI rows with no live status text.
+    // GetMapLandmarkInfo(i) → name, description, textureIndex, x, y (`0x4a8740`). textureIndex is
+    // a row's Icon, or 15 at zone level without `Flags & 0x80` (`0x4a8848`), and the guard
+    // marker's packet Icon; an empty description is nil, as `0x6f3890` pushes for a NULL string.
     g.set(
         "GetMapLandmarkInfo",
         lua.create_function(|lua, i: i64| {
@@ -968,11 +743,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetNumMapOverlays() — how many of the displayed map's overlays are REVEALED by the
-    // explored bitset (the client's C side filters the same way; the reference Lua draws every
-    // returned overlay). 0 at world/continent level; an instance map is admitted under the same
-    // gate as a zone (see [`current_zone`]) — which on 5875 data means Alterac Valley's three
-    // rows and nothing for the other two battlegrounds.
+    // GetNumMapOverlays(): the displayed map's revealed overlays; 0 at world and continent level.
     g.set(
         "GetNumMapOverlays",
         lua.create_function(|lua, ()| {
@@ -982,8 +753,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     )?;
 
     // GetMapOverlayInfo(i) → textureName, textureWidth, textureHeight, offsetX, offsetY,
-    // mapPointX, mapPointY — the i-th (1-based) revealed overlay. The texture is the full path
-    // prefix (the Lua appends the piece number); mapPointX/Y are 0 on every 5875 row.
+    // mapPointX, mapPointY; mapPointX and mapPointY are 0 on every 5875 row.
     g.set(
         "GetMapOverlayInfo",
         lua.create_function(|lua, i: i64| {
diff --git a/crates/benilla-ui/src/script/worldmap_arrow.rs b/crates/benilla-ui/src/script/worldmap_arrow.rs
index c9d27731..9141c321 100644
--- a/crates/benilla-ui/src/script/worldmap_arrow.rs
+++ b/crates/benilla-ui/src/script/worldmap_arrow.rs
@@ -1,22 +1,7 @@
-//! The world map's **arrow frames** (decision 1980; wow-re
-//! `system/ui/scratch/worldmap-arrow-and-positions.md` §2): the seven bindings the stock
-//! `WorldMapFrame.lua` and `Blizzard_BattlefieldMinimap.lua` call to put the player's arrow on
-//! the map.
-//!
-//! The reference keeps **two singletons per UI session** — the world map's and the battlefield
-//! minimap's — each a stock `Model` widget (the same class `CreateFrame("Model")` makes) born as a
-//! child of the frame the first `Create…` was given, loaded with `Interface\Minimap\MinimapArrow.mdx`,
-//! shown, and never freed: every later `Create…` is a no-op even with a different parent. Its
-//! rect is the model's bounding box (no authored size), its model is re-centred on that rect by
-//! every `Update…`, and its facing is the camera-tracked object's — the player's. `Position…` is
-//! literally `arrow:SetPoint(...)` with the generic binder's three error strings and two silent
-//! legs; `Show…` is `arrow:Show()`/`Hide()` under the never-raising boolean coercion.
-//!
-//! Here the singleton is an anonymous `Model` frame this module creates through the same factory
-//! `CreateFrame` uses, sized to the arrow's byte-measured footprint, and the app draws it: a
-//! `Model` frame whose file is the minimap arrow extracts as [`QuadContent::ModelPane`] with the
-//! path and the facing, and the app's model-pane arm paints the arrow sprite there
-//! (`ui_script/extract`).
+//! The world map's arrow frames (`0x4a8bb0`), the seven bindings `WorldMapFrame.lua` and
+//! `Blizzard_BattlefieldMinimap.lua` call. The reference keeps two singletons per UI session, the
+//! world map's and the battlefield minimap's: stock `Model` frames made by the first `Create`,
+//! never freed, their rect the arrow file's bounding box and their facing the player's.
 
 use mlua::{Lua, MultiValue, ObjectLike, Table, Value};
 
@@ -24,15 +9,11 @@ use super::binding_abi::bool_or_default;
 use super::object::{create_frame, decode_id, frame_handle_of, frame_wrapper, point_from_str};
 use super::Model;
 
-/// The arrow's model — `0x8453c0`, and NOT `Rotating-MinimapArrow`.
+/// The arrow's model (`0x8453c0`), not `Rotating-MinimapArrow`.
 pub const ARROW_MODEL: &str = "Interface\\Minimap\\MinimapArrow.mdx";
 
-/// The arrow's rect is the file's own bounding box — the implicit rect of a size-less pane
-/// (decision 2015; `MinimapArrow.mdx`'s `0.0262 × 0.0263` model units read as layout units,
-/// `1280·extent = 33.5 × 33.7` FrameXML units at 4:3). The world-map arrow's model scale is
-/// `G48 · 5/3` (`= 1.0` at 4:3, `G48 = 1/√(aspect² + 1)`) and the mini's `G48 · 10/9`, so the
-/// quad holds a constant apparent size as the window's shape changes while its rect grows with
-/// `√(a²+1)` (render law §2, the worked arrow).
+/// Half the file's bounding box, which is the size-less pane's rect in layout units (33.5 x 33.7
+/// FrameXML units at 4:3); `0x4a7b20` centres the model there.
 fn centre_of(facts: Option<&crate::widget::ModelFileFacts>) -> (f32, f32, f32) {
     facts.map_or((0.0, 0.0, 0.0), |f| {
         let (x, y) = f.extent();
@@ -60,7 +41,8 @@ impl Arrow {
             Arrow::Mini => model.worldmap.arrow_mini = Some(id),
         }
     }
-    /// The model-scale numerator: `5/3` for the world map's arrow, `10/9` for the mini's.
+    /// The model scale over `G48`: `5/3` for the world map, `10/9` for the mini, so the arrow keeps
+    /// its apparent size as the window's shape changes (`0x4a7ad8`).
     fn scale_over_g48(self) -> f32 {
         match self {
             Arrow::World => 5.0 / 3.0,
@@ -97,15 +79,15 @@ impl Arrow {
     }
 }
 
-/// `[0x832a48]` — the Y half-extent of the reference's layout space, `1/√(A² + 1)` for the
-/// screen's aspect `A`; `0.6` at 4:3.
+/// `G48` (`0x832a48`), the Y half-extent of the reference's layout space: `1/√(A² + 1)` for the
+/// screen's aspect `A`, 0.6 at 4:3.
 fn g48(model: &Model) -> f32 {
     let (w, h) = (model.screen.width(), model.screen.height());
     let a = if h > 0.0 { w / h } else { 4.0 / 3.0 };
     1.0 / (a * a + 1.0).sqrt()
 }
 
-/// The arrow's model scale for this screen, and the footprint that scale gives it.
+/// The arrow's model scale for this screen.
 fn arrow_scale(model: &Model, which: Arrow) -> f32 {
     g48(model) * which.scale_over_g48()
 }
@@ -142,7 +124,7 @@ fn create(lua: &Lua, which: Arrow, parent: Value) -> mlua::Result<()> {
     {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         if which.slot(&model).is_some() {
-            return Ok(()); // the singleton exists: the parent is not even read (§2.1)
+            return Ok(()); // the singleton exists: the parent is not even read (`0x4a7a80`)
         }
     }
     let wrapper = create_frame(
@@ -154,13 +136,8 @@ fn create(lua: &Lua, which: Arrow, parent: Value) -> mlua::Result<()> {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
         arrow_scale(&model, which)
     };
-    // `SetModel("Interface\Minimap\MinimapArrow.mdx")` in C++ (`0x4a7a80` → `0x76c8e0`): the
-    // same file set every pane takes, seeded with the file's facts when the host has them
-    // (decision 2007 — the arrow's Stand loops its 3.333 s with no bone keyed, so nothing
-    // moves; the arm is the reference's, not a look). No authored size: the widget's rect is
-    // the file's bounding box (§2.2, decision 2015), and `0x4a7b20`'s `SetPosition(½·GetWidth,
-    // ½·GetHeight, 0)` — the geometry override's bbox extent, in layout units — centres the
-    // model on it.
+    // The reference's `SetModel` (`0x4a7a80` calls `0x76c8e0`) with no authored size: the rect is
+    // the file's bounding box, and `0x4a7b20` centres the model on it.
     let facts = lua
         .app_data_mut::<Model>()
         .expect("model app_data")
@@ -177,7 +154,6 @@ fn create(lua: &Lua, which: Arrow, parent: Value) -> mlua::Result<()> {
     Ok(())
 }
 
-/// The singleton's wrapper, or `None` while it does not exist.
 fn arrow_wrapper(lua: &Lua, which: Arrow) -> mlua::Result<Option<Table>> {
     let id = {
         let model = lua.app_data_ref::<Model>().expect("model app_data");
@@ -186,9 +162,8 @@ fn arrow_wrapper(lua: &Lua, which: Arrow) -> mlua::Result<Option<Table>> {
     id.map(|id| frame_wrapper(lua, id)).transpose()
 }
 
-/// `UpdateWorldMapArrowFrames()` (§2.3): for each existing arrow, re-centre the model on its
-/// rect and copy the camera-tracked object's facing — the player's, which the app pushes with
-/// the world-map feed — into its rotation about +Z. No player → neither facing moves.
+/// `UpdateWorldMapArrowFrames()` (`0x4a8d10`, `0x4a7c20`): re-centre each arrow and copy the
+/// camera-tracked object's facing, the player's; with no player the facing stays.
 fn update(lua: &Lua) -> mlua::Result<()> {
     for which in [Arrow::World, Arrow::Mini] {
         let Some(wrapper) = arrow_wrapper(lua, which)? else {
@@ -212,12 +187,9 @@ fn update(lua: &Lua) -> mlua::Result<()> {
     Ok(())
 }
 
-/// `Position…("point", "frame" [, relativePoint] [, offsetX, offsetY])` (§2.4): silent with no
-/// arrow; args 1 and 2 must be strings (a number is one) else the usage raise; the point through
-/// the same table `SetPoint` reads, else `Unknown frame point`; the frame by name — `$parent`
-/// expanded against the arrow's parent, then `_G` — else `Couldn't find frame named '%s'`, and
-/// the arrow itself `Error: %s is anchored to itself`; a non-string third argument means
-/// `relativePoint = point` and zero offsets with no error; offsets only when both are numbers.
+/// `Position...("point", "frame" [, relativePoint] [, offsetX, offsetY])` (`0x4a8d20`,
+/// `0x4a8f20`): `SetPoint` on the arrow, silent with no arrow. A non-string third argument means
+/// the same point and zero offsets, with no error; offsets apply only when both are numbers.
 fn position(lua: &Lua, which: Arrow, args: [Value; 5]) -> mlua::Result<()> {
     let Some(arrow) = arrow_wrapper(lua, which)? else {
         return Ok(());
@@ -232,7 +204,9 @@ fn position(lua: &Lua, which: Arrow, args: [Value; 5]) -> mlua::Result<()> {
     }
     let frame_name = as_string(&frame)?;
     let resolved = if let Some(rest) = frame_name.strip_prefix("$parent") {
-        // The first NAMED ancestor of the arrow — its parent frame, or that frame's own parent.
+        // The reference (`0x76c5b0`) matches `$parent` in any case and takes the first named
+        // ancestor's name, else "Top"; here the prefix matches as spelled and only the direct
+        // parent's name is tried.
         let parent_name: Option<String> = arrow
             .call_method::<Option<Table>>("GetParent", ())?
             .and_then(|p| {
@@ -278,15 +252,14 @@ fn position(lua: &Lua, which: Arrow, args: [Value; 5]) -> mlua::Result<()> {
     )
 }
 
-/// `Show…([shown])` (§2.5): silent with no arrow; the never-raising boolean coercion with a
-/// default of true (absent → show, `nil` → hide).
+/// `Show...([shown])` (`0x4a9120`, `0x4a9170`): silent with no arrow; the never-raising boolean
+/// coercion, true by default.
 fn show(lua: &Lua, which: Arrow, args: MultiValue) -> mlua::Result<()> {
     let Some(arrow) = arrow_wrapper(lua, which)? else {
         return Ok(());
     };
-    // An ABSENT argument is not nil at the C API (`LUA_TNONE`, which the binding's nil test does
-    // not match), so the bare call shows; an explicit nil hides; anything else is the boolean
-    // coercion with its true default.
+    // An absent argument is `LUA_TNONE`, which the binding's nil test does not match, so a bare
+    // call shows and an explicit nil hides.
     let on = match args.front() {
         None => true,
         Some(Value::Nil) => false,
@@ -340,8 +313,8 @@ mod tests {
     use super::*;
     use crate::script::UiScript;
 
-    /// The arrow file's facts, as the host hands them over (2007/2015): the header box the
-    /// implicit rect and the re-centring read.
+    /// The arrow file's facts as the host hands them over: the header box the rect and the
+    /// centring read.
     fn arrow_facts(s: &mut UiScript) {
         s.set_model_facts(
             ARROW_MODEL,
@@ -369,8 +342,6 @@ mod tests {
         s
     }
 
-    /// The three raise strings, then the singleton: an anonymous Model child of the parent,
-    /// loaded with the arrow, born shown, sized to its footprint; a second create a no-op.
     #[test]
     fn create_validates_its_parent_and_makes_one_arrow_per_session() {
         let mut s = vm();
@@ -412,11 +383,9 @@ mod tests {
         assert_eq!(kind, "Model");
         assert!(shown, "born shown");
         assert_eq!(w, 0.0, "no authored size, no facts yet: no rect");
-        // The file lands: the rect is its box in layout units — 0.0262 × 1280 at 4:3 — and the
-        // model is centred on it (`0x4a7b20`, half the box, in layout units).
+        // The rect is the box in layout units, 0.0262 x 1280 at 4:3, with the model centred on it.
         arrow_facts(&mut s);
-        // The C++ re-centres on create and on every `UpdateWorldMapArrowFrames` (`0x4a7b20`);
-        // a file that lands after the create is picked up by the next update.
+        // Facts that land after the create are picked up by the next update, which re-centres.
         s.run("UpdateWorldMapArrowFrames()").unwrap();
         s.resolve();
         let w: f32 = s.eval("return ({WM:GetChildren()})[2]:GetWidth()").unwrap();
@@ -441,8 +410,6 @@ mod tests {
         );
     }
 
-    /// `Position…` anchors the arrow like SetPoint, with the reference's three strings and its
-    /// two silent legs; `Show…` follows the boolean coercion; `Update…` copies the facing.
     #[test]
     fn position_show_and_update_drive_the_arrow() {
         let mut s = vm();
@@ -487,7 +454,7 @@ mod tests {
             (cx - (dl + 100.0)).abs() < 0.01 && (cy - (dt - 50.0)).abs() < 0.01,
             "{cx} {cy}"
         );
-        // A non-string third argument: relativePoint = point, offsets ignored, no error.
+        // A non-string third argument: the same point, offsets ignored, no error.
         s.run("PositionWorldMapArrowFrame('TOPLEFT', 'WorldMapDetailFrame', nil, 100, -50)")
             .unwrap();
         s.resolve();
diff --git a/crates/benilla-ui/src/script/worldstate.rs b/crates/benilla-ui/src/script/worldstate.rs
index 62bca9af..7c06445d 100644
--- a/crates/benilla-ui/src/script/worldstate.rs
+++ b/crates/benilla-ui/src/script/worldstate.rs
@@ -1,44 +1,27 @@
-//! The world-state UI seam — `GetNumWorldStateUI` / `GetWorldStateUIInfo`, the two bindings behind
-//! the always-up PvP readout (`WorldStateFrame`; decision 1586).
-//!
-//! The list is built app-side ([`crate::world_state_ui`](benilla_app)) because every one of its
-//! gates reads app state — the last init's `(map, area)` scope, the joined chat channels, the live
-//! world-state table — and pushed here as already-resolved rows. That is the same split every
-//! other feed uses; what the reference keeps in a process global (`0xb71e7c`, an array of DBC row
-//! ids re-walked on demand) we keep as the resolved answer.
-//!
-//! **Return shape VERIFIED** at `0x4c5a70` (wow-re `system/ui/scratch/worldstate-ui-law.md`).
-//! Worth stating what it is *not*: this is a **ten**-value return, and it carries **no `uiType` and
-//! no `hidden`** — those are a later expansion of the API, and a client that answered twelve values
-//! here would hand `WorldStateFrame` its icon path where it expects a number.
+//! `GetNumWorldStateUI` and `GetWorldStateUIInfo`, behind the always-up PvP readout, over rows the
+//! app resolves; the reference re-walks an array of DBC row ids (`0xb71e7c`) on demand. The info
+//! is ten values (`0x4c5a70`), with no `uiType` or `hidden`, which came later.
 
 use mlua::{Lua, MultiValue, Value};
 
 use super::Model;
 
-/// One row of the always-up world-state readout — the ten values `GetWorldStateUIInfo` returns,
-/// in its order.
+/// One row of the readout: the ten values `GetWorldStateUIInfo` returns, in order.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WorldStateUiView {
-    /// `uiState` — the row's `StateVariable` world state resolved through the table, or **`1`**
-    /// when it carries none (`0x4c5ad8`: the miss is a literal `1.0`, not `0`, so a row without a
-    /// state reads as "on" rather than "off").
+    /// `uiState`: the row's `StateVariable` world state, or 1 (on) when it has none (`0x4c5ad8`).
     pub ui_state: i32,
-    /// The label, already macro-expanded (`"Towers Controlled: 3"`). The **only** expanded string
-    /// of the ten.
+    /// The label, macro-expanded, the only expanded string of the ten.
     pub text: String,
     /// The static icon's texture path, or `""`.
     pub icon: String,
-    /// The icon that replaces it while the row's state is live (Warsong Gulch's enemy flag), or
-    /// `""`.
+    /// The icon that replaces it while the state is live (Warsong Gulch's enemy flag), or `""`.
     pub dynamic_icon: String,
     pub tooltip: String,
     pub dynamic_tooltip: String,
-    /// A token naming an extra widget the row drives — `"CAPTUREPOINT"` on the one row that has
-    /// one — or `""`.
+    /// The extra widget the row drives, `"CAPTUREPOINT"` on the one row that has one, or `""`.
     pub extended_ui: String,
-    /// That widget's three world states, **resolved to values** (the DBC holds ids; the binding
-    /// answers what they read).
+    /// That widget's three world states, resolved to values; the DBC holds ids.
     pub extended_ui_state: [i32; 3],
 }
 
@@ -48,19 +31,10 @@ pub(crate) struct WorldStateUiState {
 }
 
 impl super::UiScript {
-    /// Push the always-up world-state readout's rows (see
-    /// [`WorldStateUiView`](WorldStateUiView)). On change, queues
-    /// **`UPDATE_WORLD_STATES`** — event `0x20e`, the reference's own name for it.
-    ///
-    /// **Named divergence, in the *trigger*, not the shape.** The reference fires that event from
-    /// exactly two sites (`0x48fa12`, after an init rebuilds the list; `0x49bdd6`, when the
-    /// zone-defense channel membership flips) and, verified by a whole-`.text` scan for the id,
-    /// nowhere else — so a plain `SMSG_UPDATE_WORLD_STATE` changing a tower count fires nothing.
-    /// It can afford that because its Lua re-reads live values off the table at whatever moment it
-    /// repaints; we push resolved values, so a silent value change would simply never reach the
-    /// frame. We therefore fire on any change to what the readout would *display*, which is the
-    /// reference's two triggers plus the value updates its own frame must already be reacting to
-    /// by some means the binary does not show.
+    /// Push the readout's rows, queuing `UPDATE_WORLD_STATES` (event `0x20e`) on any change.
+    /// Deviation: the reference fires it only after an init rebuild (`0x48fa12`) or a zone-defense
+    /// channel flip (`0x49bdd6`); we fire on a value change too, because our rows are resolved
+    /// values its Lua would re-read live.
     pub fn set_world_state_ui(&mut self, rows: Vec<WorldStateUiView>) {
         let mut model = self.model_mut();
         if model.worldstate.rows != rows {
@@ -75,8 +49,7 @@ impl super::UiScript {
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
-    // GetNumWorldStateUI() — how many always-up rows the current scope admits (`0x4c5a40`: pushes
-    // the count, no validation, always one return).
+    // `0x4c5a40`: the count, no validation, always one return.
     g.set(
         "GetNumWorldStateUI",
         lua.create_function(|lua, ()| {
@@ -85,28 +58,15 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         })?,
     )?;
 
-    // GetWorldStateUIInfo(index) — the i-th (1-based) row, ten values (`0x4c5a70`).
-    //
-    // Two legs of the reference's behaviour are easy to get wrong and are reproduced here:
-    //
-    // - a **non-number** argument RAISES `"Usage: GetWorldStateUIInfo(index)"`. The binding's
-    //   `luaL_error` leg looks like it returns — its callee has a `ret` — but that `ret` is an
-    //   MSVC epilogue, and closing the range two levels down (`luaG_errormsg`, then `luaD_throw`,
-    //   neither of which contains a single `ret`) proves the longjmp. So this is an error, not a
-    //   quiet nil.
-    // - an **out-of-range** index returns exactly ONE value, the number `0` — not nil, and not a
-    //   run of ten nils (`0x4c5be5`). The index falls through a row-id substitution of `0`, whose
-    //   id-index slot is NULL, and lands on that shared bail.
-    //
-    // No string return is ever nil: an empty DBC column resolves to the string block's leading
-    // NUL, so Lua gets `""`. The `__ftol` on the index truncates toward zero.
+    // A non-number raises (the `luaL_error` longjmps), an out-of-range index answers the single
+    // number 0 (`0x4c5be5`), and no string is ever nil: an empty DBC column reads `""`.
     g.set(
         "GetWorldStateUIInfo",
         lua.create_function(|lua, index: Value| {
             let index = match index {
                 Value::Integer(i) => i as f64,
                 Value::Number(n) => n,
-                // The reference accepts a numeric STRING too — `lua_isnumber` coerces.
+                // A numeric string too, as `lua_isnumber` coerces.
                 Value::String(ref s) => match s.to_str().ok().and_then(|s| s.trim().parse().ok()) {
                     Some(n) => n,
                     None => return Err(mlua::Error::runtime("Usage: GetWorldStateUIInfo(index)")),
@@ -115,7 +75,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
             };
             let row = {
                 let model = lua.app_data_ref::<Model>().expect("model app_data");
-                // Truncate toward zero, then 1-based.
+                // Truncated toward zero by `__ftol`, then 1-based.
                 usize::try_from(index.trunc() as i64)
                     .ok()
                     .and_then(|i| i.checked_sub(1))
diff --git a/crates/benilla-ui/src/script/worn_display.rs b/crates/benilla-ui/src/script/worn_display.rs
index 6565d124..071a0af8 100644
--- a/crates/benilla-ui/src/script/worn_display.rs
+++ b/crates/benilla-ui/src/script/worn_display.rs
@@ -1,81 +1,52 @@
-//! The **equipment-display** API surface — `ShowHelm`/`ShowingHelm`, `ShowCloak`/`ShowingCloak`
-//! (decision 1472): the player's two "don't draw this piece of my gear" preferences.
-//!
-//! Two bits, and they are not the UI's to keep. The preference lives server-side in the character's
-//! own `PLAYER_FLAGS` (`HIDE_HELM 0x400` / `HIDE_CLOAK 0x800`), which is a **public** descriptor
-//! field — so it dresses our body on every client that can see us, and every other player's on
-//! ours. That is why there is no CVar and no saved variable behind this row: the wire flag is the
-//! single source of truth, it is per-character rather than per-install, and it is already persisted
-//! by whoever we are logged into.
-//!
-//! **The setter is a set; the wire verb is a flip.** `CMSG_TOGGLE_HELM`/`CMSG_TOGGLE_CLOAK` carry no
-//! body and have no target-state form at all (vmangos `HandleShowingHelmOpcode` is a bare
-//! `ToggleFlag`), so `ShowHelm(v)` compares `v` against what we currently believe and queues a flip
-//! only on a difference. The belief is updated **optimistically at the call** and overwritten only
-//! when the *wire* bit actually moves ([`super::UiScript::set_worn_display`], pushed on the
-//! descriptor edge and not per frame) — without that, the value would snap back to the stale
-//! descriptor for the length of the round trip and a second click inside that window would compute
-//! the wrong flip.
-//!
-//! The 1.12 panel calls the setter with the **strings** `"1"` / `"0"` (`UIOptionsFrame_Save`
-//! l.286-297, `value.setFunc(value.value)`), so the argument is read *numerically* — plain Lua
-//! truthiness would make `"0"` mean "show" and the reference's own Options panel could never turn
-//! a helm off. See [`shown_arg`].
+//! `ShowHelm`/`ShowingHelm` and `ShowCloak`/`ShowingCloak`, over the `PLAYER_FLAGS` bits
+//! `HIDE_HELM` (`0x400`) and `HIDE_CLOAK` (`0x800`), which the server keeps per character, so no
+//! CVar backs them. The wire verbs are bodiless flips (vmangos `HandleShowingHelmOpcode` is a bare
+//! `ToggleFlag`), so a set queues a flip only when it differs from a belief that moves at the call
+//! and is overwritten when the wire bit moves.
 
 use mlua::{Lua, Value};
 
 use super::Model;
 
-/// Which of the two worn-display preferences a queued flip is for. One entry per
-/// `CMSG_TOGGLE_HELM`/`CMSG_TOGGLE_CLOAK` the app should send.
+/// A queued flip: one `CMSG_TOGGLE_HELM` or `CMSG_TOGGLE_CLOAK` for the app to send.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum WornDisplay {
-    /// The head slot — `PLAYER_FLAGS_HIDE_HELM`.
+    /// The head slot, `PLAYER_FLAGS_HIDE_HELM`.
     Helm,
-    /// The back slot — `PLAYER_FLAGS_HIDE_CLOAK`.
+    /// The back slot, `PLAYER_FLAGS_HIDE_CLOAK`.
     Cloak,
 }
 
 impl super::UiScript {
-    /// Drain the worn-display flips queued since the last call — one `CMSG_TOGGLE_HELM` /
-    /// `CMSG_TOGGLE_CLOAK` each. A list rather than a count because the two slots are distinct
-    /// packets; within one slot, two flips in a frame are two sends, exactly like the PvP toggle.
+    /// Drain the queued flips, one packet each; two flips of one slot in a frame are two sends.
     pub fn take_worn_display_toggles(&mut self) -> Vec<WornDisplay> {
         std::mem::take(&mut self.model_mut().worn_display_toggles)
     }
 
-    /// Push the wire truth for both preferences — the app calls this **on a `PLAYER_FLAGS` edge**,
-    /// never per frame, so an optimistic flip made by [`install`]'s setters survives until the
-    /// server's answer actually arrives (see the module doc).
+    /// Push the wire truth, only on a `PLAYER_FLAGS` edge: pushed per frame, it would undo an
+    /// optimistic flip before the server answers, and a second click would flip the wrong way.
     pub fn set_worn_display(&mut self, helm_shown: bool, cloak_shown: bool) {
         let mut model = self.model_mut();
         model.helm_shown = helm_shown;
         model.cloak_shown = cloak_shown;
     }
 
-    /// What the VM currently believes — the app's own read, for the drain's compare and for tests.
+    /// What the VM currently believes, `(helm_shown, cloak_shown)`.
     pub fn worn_display(&self) -> (bool, bool) {
         let model = self.model_ref();
         (model.helm_shown, model.cloak_shown)
     }
 }
 
-/// The setter's argument convention: **numeric**, not Lua-truthy. `nil`/`false`/`0`/`"0"` read as
-/// "hide"; `true`, any non-zero number and any non-numeric string read as "show".
-///
-/// The distinction is load-bearing rather than pedantic. 1.12's own Interface panel hands this
-/// binding the *string* `"0"` to mean off (`UIOptionsFrame_Save`), and in Lua 5.0 `"0"` is truthy —
-/// so a plain `lua_toboolean` reading would make the reference's own Show Helm checkbox a one-way
-/// switch. Numeric-string coercion is what makes it work, and it is the same shape
-/// [`super::action::truthy_nonzero`] already carries for `UseAction`'s `checkCursor`.
+/// Numeric, not Lua-truthy: the stock panel passes the string `"0"` for off
+/// (`UIOptionsFrame_Save`), which Lua 5.0 holds truthy. Nil, false, 0 and `"0"` hide.
 fn shown_arg(v: &Value) -> bool {
     match v {
         Value::Nil => false,
         Value::Boolean(b) => *b,
         Value::Integer(i) => *i != 0,
         Value::Number(n) => *n != 0.0,
-        // A numeric string coerces like Lua's own arithmetic does; a non-numeric one is not a
-        // value this API is ever handed, and reads as "show" rather than silently hiding gear.
+        // A non-numeric string is never handed to this API; it shows rather than hiding gear.
         Value::String(s) => s
             .to_str()
             .ok()
@@ -94,11 +65,10 @@ fn want(model: &mut Model, which: WornDisplay, show: bool) {
     if *held == show {
         return;
     }
-    *held = show; // optimistic — the wire edge overwrites it when the server answers
+    *held = show; // optimistic: the wire edge overwrites it when the server answers
     model.worn_display_toggles.push(which);
 }
 
-/// Register the equipment-display globals.
 pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
     let g = lua.globals();
 
@@ -116,8 +86,7 @@ pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
         )?;
     }
 
-    // The getters the Options row reads its checked state from — `1`/`nil`, the 1.12 boolean
-    // return the panel feeds straight into `SetChecked`.
+    // `1` or nil, which the Options row feeds straight into `SetChecked`.
     for (name, which) in [
         ("ShowingHelm", WornDisplay::Helm),
         ("ShowingCloak", WornDisplay::Cloak),
@@ -142,10 +111,6 @@ mod tests {
     use super::WornDisplay;
     use crate::script::UiScript;
 
-    /// The argument convention, and the one that would silently break the feature: 1.12's own
-    /// Options panel calls the setter with the **string** `"0"` to mean "hide", and in Lua 5.0 that
-    /// string is truthy. A plain truthiness reading would make Show Helm a one-way switch — on
-    /// forever, off never — with no error anywhere to say so.
     #[test]
     fn the_setter_reads_its_argument_numerically_so_the_string_zero_hides() {
         let mut s = UiScript::new().unwrap();
@@ -175,9 +140,8 @@ mod tests {
         );
     }
 
-    /// The wire verb is a blind flip, so **asking for the state we are already in must send
-    /// nothing** — otherwise the Options window's Defaults button, which writes every row on the
-    /// page unconditionally, would invert whichever preference was already at its default.
+    /// The Options window's Defaults button writes every row, so a flip on no difference would
+    /// invert a preference already at its default.
     #[test]
     fn asking_for_the_state_we_are_already_in_sends_nothing() {
         let mut s = UiScript::new().unwrap();
@@ -196,8 +160,6 @@ mod tests {
         );
     }
 
-    /// The descriptor is the truth: a wire push overrides whatever the VM believed. This is the
-    /// edge the app feeds — it is why the app pushes on a `PLAYER_FLAGS` CHANGE and not per frame.
     #[test]
     fn the_wire_push_overrides_the_optimistic_belief() {
         let mut s = UiScript::new().unwrap();
@@ -205,8 +167,7 @@ mod tests {
         let _ = s.take_worn_display_toggles();
         assert_eq!(s.worn_display(), (false, true));
 
-        // The server answers something else entirely (another client toggled it, or our flip
-        // crossed a login) — the descriptor wins, and the next ask is computed from it.
+        // The server answers otherwise; the descriptor wins and the next ask is computed from it.
         s.set_worn_display(true, false);
         assert_eq!(s.worn_display(), (true, false));
         s.run("ShowHelm(0)").unwrap();
diff --git a/crates/benilla-ui/src/source.rs b/crates/benilla-ui/src/source.rs
index e15f6b3b..2c0b5f51 100644
--- a/crates/benilla-ui/src/source.rs
+++ b/crates/benilla-ui/src/source.rs
@@ -1,87 +1,29 @@
-//! **UI source bytes** — what a `.lua`, `.xml` or `.toc` file *is*, before any parser sees it.
-//!
-//! One rule, and it is the reference's: **a UI source file is bytes, not text.** wow-5875-re has
-//! the whole path byte-verified (`system/ui/scratch/lua-chunk-load-encoding.md`, a §5 trio run for
-//! this decision): `0x704bc0` slurps the file (`0x648620`) with `pad = 0`, so there is not even a
-//! trailing NUL, the handle is opened **binary** on every leg of `0x647db0`, and `0x704ae0` hands
-//! the pointer and length straight to `luaL_loadbuffer 0x6f5690`. No transcoding, no codepage
-//! conversion; the only `WideCharToMultiByte` on the path converts the *path*. Lua 5.0 strings
-//! *are* byte strings, so a cp1252 German locale file loads there and its literals carry the raw
-//! bytes.
-//!
-//! Two things the compiler's front door does do, and we do them too because they are the
-//! reference's own code rather than Lua's: it **strips a UTF-8 BOM** ([`strip_bom`] — ten
-//! instructions Blizzard patched into `luaL_loadbuffer`) and it **eats a leading `#`-line**
-//! ([`strip_hashbang`] — Lua 5.0 puts that in `luaX_setinput`, where every chunk passes; 5.1 moved
-//! it somewhere mlua never calls).
-//!
-//! benilla read every one of these files with `read_to_string` until decision 1193, which meant a
-//! file that was not valid UTF-8 did not merely lose a glyph — it **did not exist**: the read
-//! returned `None` and the loader reported "not found". Measured over a real 218-addon vanilla
-//! corpus, that is **80 addons of 218** (37 %): 76 non-UTF-8 `.lua` files, 5 non-UTF-8 `.toc`
-//! files (which made those addons invisible to discovery entirely), and 160 files carrying a UTF-8
-//! BOM. `AceAddon-2.0.lua` is one of them, and it is embedded in ~30 addons — one library file
-//! taking out the whole Ace/FuBar half of the ecosystem.
-//!
-//! ## Two verbs, because there are two kinds of consumer
-//!
-//! - [`strip_bom`] + raw bytes → **Lua chunks**. Byte-transparent, exactly as the reference.
-//!   `string.len()` on a literal returns what it returns there, and byte-indexing agrees.
-//! - [`decode`] → **our own parsers** (FrameXML XML, `.toc`), which need `&str` because Rust
-//!   parsers do. This is the only place a guess is made, and it is made where it is cheapest.
-//!
-//! **Why not transcode the Lua too, so everything downstream is UTF-8?** Because that would
-//! silently change `string.len`, `string.sub` and `string.byte` on every non-ASCII literal — a
-//! divergence from the verified mechanism, bought for a rendering convenience. The right place to
-//! turn bytes into text is the boundary that actually requires text, which is a Rust binding
-//! signature, not the file loader. A stray byte should cost one glyph, not the file.
+//! UI source files are bytes, not text. The reference reads a Lua file whole and binary
+//! (`0x704bc0` via `0x648620`, no trailing NUL; binary on every leg of `0x647db0`), and
+//! `0x704ae0` hands it untranscoded to `luaL_loadbuffer 0x6f5690`, so a cp1252 file's literals
+//! keep their raw bytes. [`chunk`] prepares a Lua chunk byte for byte; [`decode`] gives our own
+//! `.xml` and `.toc` parsers the `&str` they need. Transcoding Lua instead would change
+//! `string.len`, `string.sub` and `string.byte` on every non-ASCII literal.
 
 use std::borrow::Cow;
 
-/// The UTF-8 byte-order mark. Not an encoding — a three-byte signature some Windows editors write
-/// in front of a UTF-8 file.
 const BOM: &[u8] = &[0xEF, 0xBB, 0xBF];
 
-/// `bytes` without a leading UTF-8 BOM.
-///
-/// **This is fidelity, not a modernisation** — and that is a correction to this module's first
-/// draft, which reasoned that stock Lua 5.0's lexer meets `0xEF` and stops, so a BOM'd file must
-/// have failed on the real client too, so stripping it was us being kinder than the original. An
-/// RE dispatch into wow-5875-re read the bytes instead of the manual: **Blizzard patched the strip
-/// into `luaL_loadbuffer 0x6f5690` themselves.** Ten instructions stock Lua does not have
-/// (`0x6f5699`–`0x6f56b4`): a `size >= 3` guard, three byte compares against `EF BB BF`, then
-/// `add edx,3` / `sub eax,3` — all before the `LoadS` fill and `lua_load 0x6f4320`. That is the
-/// only live door into the compiler, so addon files, FrameXML, XML script bodies and `loadstring`
-/// all get it. The `.toc` reader has its own separate skip at `0x6edc71`.
-///
-/// The lexer reasoning was right and the conclusion drawn from it was wrong: `luaX_lex 0x6ff610`
-/// *would* reject `0xEF`, which is precisely why the patch has to exist. A verified mechanism
-/// beats a correct-sounding derivation, every time.
-///
-/// The edge semantics are the reference's, byte for byte: **at most one** mark, **only** at offset
-/// 0, and a file shorter than three bytes is untouched (a BOM-only file compiles as an empty
-/// chunk). A UTF-16 BOM (`FF FE` / `FE FF`) is left alone — the reference does not handle one
-/// either, that file is not a Lua chunk in any encoding it could run, and transcoding it would be
-/// inventing content rather than reading it. None exists in the corpus.
+/// `bytes` without a leading UTF-8 BOM, a strip the reference added to its
+/// `luaL_loadbuffer 0x6f5690` (`0x6f5699`–`0x6f56b4`), so every chunk gets it, `loadstring`
+/// included; the `.toc` reader has its own at `0x6edc71`. At most one mark, only at offset 0; a
+/// UTF-16 mark is left alone, as the reference leaves it.
 pub fn strip_bom(bytes: &[u8]) -> &[u8] {
     bytes.strip_prefix(BOM).unwrap_or(bytes)
 }
 
-/// `bytes` with a leading `#`-line removed — the **hash-bang skip**, which is a dialect difference
-/// and not a convenience.
-///
-/// Lua 5.0 puts this skip in `luaX_setinput` (`0x6ff5cd`–`0x6ff600`), which every chunk goes
-/// through: a source file whose first character is `#` loses its whole first line, including one
-/// handed to `loadstring`. **Lua 5.1 moved it out** into `luaL_loadfile`, which mlua's
-/// `Lua::load` does not call — so a 5.1-family VM silently keeps the line and then fails to
-/// compile it. Verified in the binary by the same RE dispatch that corrected [`strip_bom`].
-///
-/// Applied after the BOM strip, because that is the order the reference applies them in: the mark
-/// is removed inside `luaL_loadbuffer`, and the lexer sees the shortened buffer.
+/// `bytes` without a leading `#` line: Lua 5.0 skips it for every chunk in `luaX_setinput`
+/// (`0x6ff5cd`–`0x6ff600`), while 5.1 moved the skip to `luaL_loadfile`, which mlua's
+/// `Lua::load` never calls. Runs after the BOM strip, the reference's order.
 pub fn strip_hashbang(bytes: &[u8]) -> &[u8] {
     match bytes.first() {
         Some(b'#') => match bytes.iter().position(|&b| b == b'\n') {
-            // Lua 5.0 leaves the newline for the line counter; so do we.
+            // Lua 5.0 keeps the newline for the line counter.
             Some(nl) => &bytes[nl..],
             None => &bytes[bytes.len()..],
         },
@@ -94,19 +36,9 @@ pub fn chunk(bytes: &[u8]) -> &[u8] {
     strip_hashbang(strip_bom(bytes))
 }
 
-/// Interpret UI source bytes as text, for the parsers that cannot take bytes.
-///
-/// Valid UTF-8 passes through **borrowed and unchanged** — which is every file we ship and the
-/// overwhelming majority of every corpus, so the guess below is never reached for them.
-///
-/// Otherwise the bytes are decoded as **cp1252** (Windows-1252). That is a guess, and it is the
-/// right one to make: the vanilla-era addons that are not UTF-8 are Western-European locale files
-/// written on a Windows box — German and French `## Notes:` lines and `<Include>`d localisation
-/// documents. cp1252 maps every byte (the five undefined slots become U+FFFD), so the decode
-/// cannot fail and the addon cannot vanish. A GBK or EUC-KR file decodes to mojibake instead of
-/// disappearing, which is a strictly better failure and one that is visible rather than silent.
-///
-/// The BOM is stripped first, so a BOM'd UTF-8 file is borrowed too.
+/// UI source bytes as text for our parsers: after the BOM, valid UTF-8 is borrowed unchanged and
+/// anything else is read as cp1252, which the non-UTF-8 vanilla addons (Western-European locale
+/// files) are written in; every byte maps, so no file fails to decode.
 pub fn decode(bytes: &[u8]) -> Cow<'_, str> {
     let bytes = strip_bom(bytes);
     match std::str::from_utf8(bytes) {
@@ -115,13 +47,8 @@ pub fn decode(bytes: &[u8]) -> Cow<'_, str> {
     }
 }
 
-/// One cp1252 byte as a `char`.
-///
-/// cp1252 is Latin-1 (where a byte *is* its code point) except for `0x80..=0x9F`, which Latin-1
-/// leaves as C1 control codes and Windows fills with the punctuation people actually type — the
-/// curly quotes, the em dash, the euro sign. Getting that window wrong is what turns a French
-/// addon's `l'objet` into a control character, so the window is spelled out rather than
-/// approximated by a Latin-1 cast.
+/// One cp1252 byte as a `char`: Latin-1, except `0x80..=0x9F`, where Latin-1 has C1 controls and
+/// cp1252 has punctuation (the five undefined slots become U+FFFD).
 fn cp1252(b: u8) -> char {
     const C1: [char; 32] = [
         '\u{20AC}', '\u{FFFD}', '\u{201A}', '\u{0192}', '\u{201E}', '\u{2026}', '\u{2020}',
@@ -140,20 +67,18 @@ fn cp1252(b: u8) -> char {
 mod tests {
     use super::*;
 
-    /// A BOM'd file loses exactly three bytes, and a file without one is untouched.
     #[test]
     fn the_utf8_bom_is_removed_and_nothing_else_is() {
         assert_eq!(strip_bom(b"\xEF\xBB\xBFlocal x = 1"), b"local x = 1");
         assert_eq!(strip_bom(b"local x = 1"), b"local x = 1");
-        // A lone 0xEF is not a BOM, and a truncated one is not either — neither may be eaten.
+        // A truncated mark is not a BOM.
         assert_eq!(strip_bom(b"\xEF\xBB"), b"\xEF\xBB");
         assert_eq!(strip_bom(b"\xEF"), b"\xEF");
         assert_eq!(strip_bom(b""), b"");
-        // A UTF-16 mark is left alone: that file is not a chunk we can honestly run.
+        // A UTF-16 mark is left alone.
         assert_eq!(strip_bom(b"\xFF\xFEl\0"), b"\xFF\xFEl\0");
     }
 
-    /// Valid UTF-8 is borrowed, not rebuilt — the common path allocates nothing.
     #[test]
     fn valid_utf8_is_borrowed_unchanged() {
         let text = "## Title: Sch\u{e4}tze";
@@ -163,44 +88,33 @@ mod tests {
         assert_eq!(decode(&bom), text);
     }
 
-    /// A cp1252 `.toc` line decodes to the glyphs its author typed, rather than to nothing.
-    ///
-    /// `0xE4` is `a`-umlaut in both Latin-1 and cp1252; `0x92` is the right single quote in cp1252
-    /// and a C1 control in Latin-1, which is the difference this table exists for.
+    /// `0xE4` is `ä` in Latin-1 and cp1252 alike; `0x92` is cp1252's right single quote but a C1
+    /// control in Latin-1.
     #[test]
     fn cp1252_is_decoded_where_utf8_fails() {
         assert_eq!(decode(b"## Notes: Sch\xE4tze"), "## Notes: Sch\u{e4}tze");
         assert_eq!(decode(b"l\x92objet"), "l\u{2019}objet");
         assert_eq!(decode(b"\x80"), "\u{20AC}");
-        // Undefined cp1252 slots survive as the replacement char — never as a decode failure.
+        // An undefined cp1252 slot becomes the replacement char.
         assert_eq!(decode(b"\x81"), "\u{FFFD}");
     }
 
-    /// The `#`-line skip is Lua 5.0's, and it is a *dialect* fact rather than a nicety.
-    ///
-    /// `luaX_setinput 0x6ff5cd` eats it for every chunk the reference compiles, including one
-    /// handed to `loadstring`. mlua's 5.1 does not, because 5.1 moved the skip into
-    /// `luaL_loadfile` and `Lua::load` never calls that.
     #[test]
     fn a_leading_hash_line_is_eaten_the_way_lua_5_0_eats_it() {
-        // The newline survives — 5.0 leaves it so the line counter stays honest.
+        // The newline stays, for the line counter.
         assert_eq!(strip_hashbang(b"#!/usr/bin/lua\nreturn 1"), b"\nreturn 1");
-        // A `#` with no newline at all leaves nothing behind.
         assert_eq!(strip_hashbang(b"# only a comment"), b"");
-        // Anything else is untouched — `#t` mid-expression is a length operator, not a shebang.
         assert_eq!(strip_hashbang(b"local n = #t"), b"local n = #t");
         assert_eq!(strip_hashbang(b""), b"");
-        // ...and the two run in the reference's order: mark first, then the line.
+        // The mark goes first, then the line: the reference's order.
         assert_eq!(chunk(b"\xEF\xBB\xBF#line\nreturn 1"), b"\nreturn 1");
     }
 
-    /// The whole point, stated as a property: **no byte sequence makes a source file vanish**.
     #[test]
     fn every_byte_sequence_decodes_to_something() {
         let all: Vec<u8> = (0u8..=255).collect();
         let text = decode(&all);
         assert!(!text.is_empty());
-        // ASCII survives verbatim, which is what a parser actually keys on.
         assert!(text.starts_with('\0'));
         assert!(text.contains("ABC"));
     }
diff --git a/crates/benilla-ui/src/strings.rs b/crates/benilla-ui/src/strings.rs
index c21df352..212f9267 100644
--- a/crates/benilla-ui/src/strings.rs
+++ b/crates/benilla-ui/src/strings.rs
@@ -1,64 +1,19 @@
-//! **One faithful substitution for reference string templates** — the client's `SStrPrintf` face.
-//!
-//! Every user-visible sentence benilla shows comes from `GlobalStrings.lua` or `GlueStrings.lua`
-//! (decision 2045), and most of those carry `%s`/`%d` holes the caller fills. Doing that filling
-//! correctly is not `format!`'s job and never was: the template is *data read at runtime from the
-//! player's install*, so the holes have to be walked, not compiled.
-//!
-//! **Why this module exists.** Before it, the substitution had been reinvented at least eight
-//! times across the workspace, with semantics that did not agree:
-//!
-//! - `ui_instance::fill_template` — ordered, `%%`-aware, starvation-safe, and tested. The best of
-//!   them, and the one this is derived from.
-//! - `ui_duel::winner_line` — a hand-rolled `%1$s`/`%2$s` positional pass, because the duel's
-//!   retreat wording swaps its two names and no ordered filler can express that.
-//! - `ui_action::errors::ui_error_text` — `str::replace`, which fills **every** `%s` with the
-//!   *same* argument. Latent rather than live (no message it currently carries has two), but it
-//!   was a real trap waiting for the first two-argument template to reach that queue.
-//! - `ui_guild::fill`, `ui_petition::fill`, and one-off `replacen` calls in `ui_binder`,
-//!   `ui_trade`, `ui_items::feed` and `equip_error`.
-//!
-//! Eight copies of one primitive is how the `ui_error_text` bug survived: there was no single
-//! place where "how do we fill a reference template" could be got right once.
-//!
-//! **The semantics, and why each is what it is.**
-//!
-//! - `%s` and `%d` consume the next argument, **left to right**. This is `SStrPrintf`'s own order.
-//! - `%N$s` / `%N$d` take argument `N` (1-based) and do **not** move the sequential cursor. 1.12
-//!   uses these exactly where a translation needs to reorder the holes —
-//!   `DUEL_WINNER_RETREAT = "%2$s has fled from %1$s in a duel"` is the canonical case, and it is
-//!   also why hardcoding an English sentence is a localization bug and not merely untidy.
-//! - `%%` collapses to one `%`.
-//! - **A specifier whose argument is missing is copied through literally.** A template we
-//!   mis-modelled should look wrong, not look plausible — `ui_instance` established this and it is
-//!   the right call: a visibly broken line gets reported, a quietly wrong one does not.
-//! - Any other specifier is copied through untouched.
-//!
-//! **`%c` and `%f`/`%g` are here because 1.12's own tables use them**, not for completeness. The
-//! item tooltip's stat and resistance families are spelled with a *character* hole for the sign —
-//! `ITEM_MOD_AGILITY = "%c%d Agility"`, `ITEM_RESIST_SINGLE = "%c%d %s Resistance"` — and its
-//! rate lines with a float one: `DPS_TEMPLATE = "(%.1f damage per second)"`,
-//! `AMMO_DAMAGE_TEMPLATE = "Adds %g damage per second"`. A filler that only knew `%s`/`%d` would
-//! copy those holes through visibly, which is the same as not being able to show the line.
-//!
-//! **The precision is the template's, never the caller's** — `%.1f` is one decimal because
-//! `DPS_TEMPLATE` says so, and a locale that respells it to `%.2f` gets two without a code change.
-//! That is the whole point of reading the template at runtime.
+//! Fills the `%` holes of a `GlobalStrings.lua` or `GlueStrings.lua` template read at runtime, as
+//! the client's `SStrPrintf` does: `%s`, `%d`, `%c`, `%f` and `%g` take the next argument left to
+//! right, `%N$s` takes argument N without moving that cursor (`DUEL_WINNER_RETREAT` reorders its
+//! two names), `%%` is `%`, and the precision is the template's. A hole with no argument, or one
+//! this does not know, is copied through literally so a mis-modelled template shows.
 
 use std::fmt::Write as _;
 
-/// One argument to [`fill`]. Every hole renders every variant — `%s` as text, `%d` as an integer,
-/// `%f`/`%g` as a real — so a caller that groups its arguments differently from the template still
-/// fills in the order the template asks for.
+/// One argument to [`fill`]; any variant renders in any hole, so the template's order decides.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum Arg<'a> {
-    /// A string argument — a player name, an item link, a zone. Also what a `%c` hole takes: the
-    /// only `%c` 1.12 spells is the `+`/`-` sign char of the `ITEM_MOD_*`/`ITEM_RESIST_*` family,
-    /// and a one-character string is how a caller says that.
+    /// Text; also what `%c` takes, whose one 1.12 use is the `+`/`-` sign of `ITEM_MOD_*` and
+    /// `ITEM_RESIST_*`.
     S(&'a str),
-    /// A numeric argument.
     D(i64),
-    /// A real argument — the rate lines (`DPS_TEMPLATE`, the `AMMO_*` damage templates).
+    /// A real, for the rate lines (`DPS_TEMPLATE`, the `AMMO_*` damage templates).
     F(f64),
 }
 
@@ -98,7 +53,7 @@ impl From<f64> for Arg<'_> {
 }
 
 impl Arg<'_> {
-    /// `%s` — and `%c`, whose only 1.12 use is a one-character sign string.
+    /// `%s` and `%c`.
     fn as_s(&self, out: &mut String) {
         match self {
             Arg::S(s) => out.push_str(s),
@@ -116,9 +71,7 @@ impl Arg<'_> {
             Arg::D(n) => {
                 let _ = write!(out, "{n}");
             }
-            // A `%d` handed a string is a caller bug, not a display decision; showing the string
-            // is strictly more useful than showing nothing and matches what varargs would do with
-            // a pointer-sized value far better than a zero would.
+            // A string in a `%d` hole is a caller bug; showing it beats showing nothing.
             Arg::S(s) => out.push_str(s),
             // C truncates toward zero here; so does `as`.
             Arg::F(x) => {
@@ -127,7 +80,7 @@ impl Arg<'_> {
         }
     }
 
-    /// `%f` / `%.Nf` — the precision is the template's, defaulting to C's 6.
+    /// `%f`/`%.Nf`, the precision defaulting to C's 6.
     fn as_f(&self, prec: Option<usize>, out: &mut String) {
         let p = prec.unwrap_or(6);
         match self {
@@ -141,21 +94,10 @@ impl Arg<'_> {
         }
     }
 
-    /// `%g` / `%.Ng` — C's rule, **including the precision**, which is significant digits here
-    /// rather than decimal places.
-    ///
-    /// The precision is not decoration on this one. Five 1.12 templates are spelled `%.3g` —
-    /// `SPELL_CAST_TIME_SEC`, `SPELL_CAST_TIME_MIN`, `SPELL_RECAST_TIME_SEC`,
-    /// `SPELL_RECAST_TIME_MIN`, `SPELL_CAST_TIME_RANGED` — and the numbers reaching them are
-    /// divisions: a 100-second cooldown is 1.666… minutes. Under C that is "1.67 min cooldown".
-    /// Under Rust's shortest round-trip `{}` it is "1.6666666666666667 min cooldown", which is
-    /// why `{}` cannot stand in for `%g` in general even though it agrees with it on the one- and
-    /// two-decimal values the ammo templates carry.
-    ///
-    /// C's rule, from the standard: let X be the exponent of the value written in `%e` style at
-    /// precision P−1; use `%f` with precision P−1−X when P > X ≥ −4, and `%e` otherwise; then
-    /// drop trailing zeros from the fraction, and the point with them if nothing is left. Taking
-    /// X *after* the rounding is what makes 9.999 at P=3 read "10" rather than "10.0".
+    /// `%g`/`%.Ng` by C's rule, the precision P counting significant digits: with X the exponent
+    /// of the value in `%e` at precision P−1, use `%f` at P−1−X when P > X ≥ −4, else `%e`, then
+    /// drop trailing zeros. 1.12's five `%.3g` cast and cooldown templates need it: a 100-second
+    /// cooldown is "1.67 min", where Rust's shortest round-trip `{}` prints 17 digits.
     fn as_g(&self, prec: Option<usize>, out: &mut String) {
         let Arg::F(x) = self else {
             return self.as_s(out);
@@ -165,7 +107,7 @@ impl Arg<'_> {
             out.push('0');
             return;
         }
-        // Round first, then read the exponent off the result — the standard's own order.
+        // Round first, then read the exponent, so 9.999 at P=3 is "10", not "10.0".
         let sci = format!("{:.*e}", p - 1, x);
         let (mantissa, exp) = sci.split_once('e').unwrap_or((sci.as_str(), "0"));
         let exp: i32 = exp.parse().unwrap_or(0);
@@ -180,8 +122,7 @@ impl Arg<'_> {
     }
 }
 
-/// Drop a fraction's trailing zeros, and the point with them if nothing survives — `%g`'s last
-/// step, and the reason "1.50" prints as "1.5" and "2.00" as "2".
+/// `%g`'s last step: drop a fraction's trailing zeros, and the point if nothing is left.
 fn trim_zeros(s: &str) -> &str {
     match s.contains('.') {
         true => s.trim_end_matches('0').trim_end_matches('.'),
@@ -189,21 +130,19 @@ fn trim_zeros(s: &str) -> &str {
     }
 }
 
-/// One parsed `%…` specifier: where it ends, which argument it names, how precise, and what
-/// conversion. Split out because the scan now has four optional parts before the conversion
-/// letter and inlining it made the fill loop unreadable.
+/// One parsed `%…` specifier.
 struct Spec {
-    /// 1-based `%N$` argument, when the specifier is positional.
+    /// The 1-based `N` of `%N$`.
     positional: Option<usize>,
-    /// `.N`, when the specifier carries one.
+    /// `.N`.
     precision: Option<usize>,
     conv: char,
     /// Index just past the conversion letter.
     end: usize,
 }
 
-/// Scan `[N$][flags][width][.prec]conv` starting just after a `%`. `None` = not a conversion this
-/// module knows, which the caller copies through untouched.
+/// Scan `[N$][flags][width][.prec]conv` just after a `%`; `None` for a conversion this does not
+/// know.
 fn parse_spec(chars: &[char], after_percent: usize) -> Option<Spec> {
     let mut i = after_percent;
     let digits = |i: &mut usize| {
@@ -213,8 +152,7 @@ fn parse_spec(chars: &[char], after_percent: usize) -> Option<Spec> {
         }
         chars[start..*i].iter().collect::<String>()
     };
-    // `%N$…` — positional. Bare digits without the `$` are a width, so this only commits when the
-    // `$` is actually there.
+    // Digits are a position only when a `$` follows; otherwise they are a width.
     let mut positional = None;
     let mut probe = i;
     let n = digits(&mut probe);
@@ -239,53 +177,26 @@ fn parse_spec(chars: &[char], after_percent: usize) -> Option<Spec> {
     })
 }
 
-/// **The other half of decision 2045**: a reference string off the VM's own globals, `None` when
-/// the key is absent **or empty**. `load_global_strings` runs the player's own
-/// `GlobalStrings.lua` — and the `Localize()` patch over it — into this VM at boot, so this is
-/// the whole of "read the sentence from the install".
-///
-/// **Empty counts as missing, and that is the reference's own test, not a convenience.**
-/// `FrameScript_GetText` hands back a pre-seeded empty string (`0x882748`) for a key the table
-/// does not carry, and the callers that care test both — `GetPVPRankInfo` checks the pointer at
-/// `0x51aa1c` and then its first byte at `0x51aa20`. A caller here gets `None` for both, and the
-/// house rule is that **`None` emits no line at all rather than an invented one** (the
-/// disposition [`crate::script`]'s `duration_text` took, and 0620 §5 before it).
-///
-/// Spelled `globals().get::<String>` deliberately: that is the shape
-/// `benilla-app/tests/reference_strings.rs` recognises as a key lookup, so a function that
-/// resolves through this is visible to the tripwire as resolving.
+/// A string from the VM's globals, where the install's `GlobalStrings.lua` is loaded at boot;
+/// `None`, and so no line, when absent or empty. `FrameScript_GetText` returns an empty string
+/// (`0x882748`) for a missing key, and callers test both (`GetPVPRankInfo`, `0x51aa1c`/`0x51aa20`).
 pub fn global(lua: &mlua::Lua, key: &str) -> Option<String> {
-    // Bound before the filter so the lookup stays one unbroken `globals().get::<String>` — a
-    // rustfmt-split chain is a resolver the tripwire's substring match cannot see.
+    // Bound before the filter so `globals().get::<String>` stays one unbroken substring, which is
+    // what `benilla-app/tests/reference_strings.rs` matches as a key lookup.
     let value = lua.globals().get::<String>(key).ok();
     value.filter(|s| !s.is_empty())
 }
 
-/// **`GetText(token, nil, ordinal)`'s plural pick**, resolved: the bare token for exactly one, the
-/// `_P1` twin for anything else — **zero included** — and `GetText`'s own fall-back to the bare
-/// token when the twin is absent.
-///
-/// **Byte-pinned, and the `> 1` reading is refuted.** `0x52fa50` snprintf's the bare key, then
-/// `0x703bf0` looks up the Lua global `GetText` and pcalls it with `(key, ordinal, gender)`; the
-/// predicate is `LocaleProperties.lua`'s `GetPluralIndex`, singular iff `not ordinal or
-/// ordinal == 1`, and `703c89: 7d 07` is a **signed** test — a zero ordinal is pushed as the
-/// number `0`, which Lua reads as truthy, so it takes the plural arm. Only a negative becomes
-/// nil. Had zero mapped to nil, a lapsing aura would read "0 second remaining".
-///
-/// Lives here, beside [`fill`], because it is the second half of the same job and it had grown
-/// **four** private copies that had to agree and could not be made to: the aura ladder's, the
-/// instance lockouts', the talent pane's, and one inlined in the death screen's sickness timer.
-/// That is the shape decision 2045 wrote about — the first `fill` had eight.
-///
-/// `None` = neither the twin nor the bare token resolves, which is the reference's
-/// data-suppression face and means **no line at all** rather than an invented one.
+/// `GetText(token, nil, ordinal)`'s plural pick: `0x52fa50` formats the key and `0x703bf0`
+/// pcalls the Lua `GetText`, where `GetPluralIndex` (`LocaleProperties.lua:56`) is singular for
+/// `not ordinal or ordinal == 1`. So one or no ordinal takes the bare token, anything else the
+/// `_P1` twin, falling back to the bare token. Zero is plural: the test at `0x703c89` is signed,
+/// only a negative becomes nil, and the number `0` is truthy in Lua.
 pub fn plural(
     token: &str,
     ordinal: Option<u32>,
     get: &dyn Fn(&str) -> Option<String>,
 ) -> Option<String> {
-    // `not ordinal or ordinal == 1` is the SINGULAR arm, so an absent ordinal takes the bare
-    // token — the same `GetText(token)` short arm a nil `genderTag` sends the reference down.
     if ordinal.is_some_and(|n| n != 1) {
         if let Some(twin) = get(&format!("{token}_P1")).filter(|s| !s.is_empty()) {
             return Some(twin);
@@ -294,7 +205,7 @@ pub fn plural(
     get(token).filter(|s| !s.is_empty())
 }
 
-/// Fill a reference template. See the module doc for the rules.
+/// Fill a reference template, by the rules in the module doc.
 pub fn fill(template: &str, args: &[Arg<'_>]) -> String {
     let mut out = String::with_capacity(template.len() + 16);
     let chars: Vec<char> = template.chars().collect();
@@ -306,20 +217,18 @@ pub fn fill(template: &str, args: &[Arg<'_>]) -> String {
             i += 1;
             continue;
         }
-        // `%%`
         if chars.get(i + 1) == Some(&'%') {
             out.push('%');
             i += 2;
             continue;
         }
         let Some(spec) = parse_spec(&chars, i + 1) else {
-            // Not a conversion we know — copy the `%` and rescan from the next char, so `50% off`
-            // survives intact.
+            // Unknown: copy the `%` and rescan from the next char, so `50% off` survives.
             out.push('%');
             i += 1;
             continue;
         };
-        // A positional names its argument outright and does NOT move the sequential cursor.
+        // A positional does not move the sequential cursor.
         let idx = match spec.positional {
             Some(n) => n.checked_sub(1),
             None => Some(next),
@@ -336,7 +245,7 @@ pub fn fill(template: &str, args: &[Arg<'_>]) -> String {
                     next += 1;
                 }
             }
-            // starved — copy the whole specifier through so a mis-modelled template looks wrong
+            // Starved: copy the specifier through so a mis-modelled template shows.
             None => out.extend(&chars[i..spec.end]),
         }
         i = spec.end;
@@ -348,8 +257,6 @@ pub fn fill(template: &str, args: &[Arg<'_>]) -> String {
 mod tests {
     use super::*;
 
-    /// `ui_instance::fill_template`'s own contract, which this subsumes — ordered, starvation-safe,
-    /// `%%`-aware. These are its test's cases verbatim, so the migration cannot change behaviour.
     #[test]
     fn ordered_fills_stop_at_the_arguments_they_have() {
         assert_eq!(
@@ -361,19 +268,13 @@ mod tests {
         assert_eq!(fill("no fills", &[Arg::D(7)]), "no fills");
     }
 
-    /// **`%.3g` is significant digits, and the precision is load-bearing.** Five 1.12 templates
-    /// carry it, all of them fed by a division: `SPELL_RECAST_TIME_MIN = "%.3g min cooldown"`
-    /// against a 100-second cooldown is 1.666… minutes. Rust's shortest round-trip `{}` — the
-    /// obvious stand-in for `%g`, and what this filler shipped with for a day — writes all
-    /// seventeen digits of that. C writes three significant ones.
     #[test]
     fn g_is_significant_digits_and_drops_trailing_zeros() {
         let g = |t: &str, v: f64| fill(t, &[Arg::F(v)]);
         assert_eq!(g("%.3g min cooldown", 100.0 / 60.0), "1.67 min cooldown");
         assert_eq!(g("%.3g sec cast", 1.5), "1.5 sec cast");
-        // Trailing zeros go, and the point with them — 2.00 is "2", not "2.00".
         assert_eq!(g("%.3g sec cast", 2.0), "2 sec cast");
-        // The exponent is taken AFTER the rounding, which is what makes this "10" and not "10.0".
+        // The exponent is read after rounding.
         assert_eq!(g("%.3g", 9.999), "10");
         // A bare `%g` is C's default precision of six.
         assert_eq!(g("%g", 1.0 / 3.0), "0.333333");
@@ -382,8 +283,6 @@ mod tests {
         assert_eq!(g("%.3g", 123_456.0), "1.23e+05");
     }
 
-    /// `%f` takes the template's precision, not the caller's — `DPS_TEMPLATE` is one decimal
-    /// because the shipped string says `%.1f`, and a locale that respells it gets two for free.
     #[test]
     fn f_takes_the_templates_precision() {
         assert_eq!(
@@ -393,14 +292,9 @@ mod tests {
         assert_eq!(fill("%.2f", &[Arg::F(41.25)]), "41.25");
     }
 
-    /// **The plural pick's zero, which is the half people get wrong.** `GetText`'s predicate is
-    /// `not ordinal or ordinal == 1` — so an ABSENT ordinal is singular, and a zero one is
-    /// **plural**, because `703c89` is a signed test and Lua reads the number `0` as truthy. The
-    /// tempting `> 1` reading makes a lapsing aura read "0 second remaining".
     #[test]
     fn plural_takes_the_twin_for_zero_and_the_bare_token_for_none() {
         let table = |key: &str| -> Option<String> {
-            // Deliberately not the shipped wording: which key is reached is the whole question.
             match key {
                 "T" => Some("<one>".into()),
                 "T_P1" => Some("<many>".into()),
@@ -420,15 +314,11 @@ mod tests {
             Some("<one>"),
             "no ordinal at all takes GetText's short arm"
         );
-        // A token with no `_P1` twin falls back to itself, at any count.
         assert_eq!(plural("ONLY", Some(7), &table).as_deref(), Some("<only>"));
-        // Neither resolving is no line at all, never an invented one.
         assert_eq!(plural("ABSENT", Some(2), &table), None);
     }
 
-    /// **The case an ordered filler cannot express**, and the reason positional specifiers exist:
-    /// 1.12's duel pair reorders the same two names, so filling them left-to-right names the wrong
-    /// winner. Both templates are quoted from GlobalStrings (958/959).
+    /// The duel pair, `GlobalStrings.lua:958-959`.
     #[test]
     fn positional_specifiers_reorder_rather_than_consume() {
         let (a, b) = (Arg::S("Alice"), Arg::S("Bob"));
@@ -440,12 +330,9 @@ mod tests {
             fill("%2$s has fled from %1$s in a duel", &[a, b]),
             "Bob has fled from Alice in a duel"
         );
-        // A positional may repeat an argument, which no cursor-based fill can do.
         assert_eq!(fill("%1$s vs %1$s", &[a]), "Alice vs Alice");
     }
 
-    /// The bug that eight copies of this hid: `str::replace` fills every `%s` with the *same*
-    /// argument. Two holes must take two arguments.
     #[test]
     fn each_hole_takes_its_own_argument() {
         assert_eq!(
@@ -457,7 +344,6 @@ mod tests {
         );
     }
 
-    /// A starved positional is copied through too, and an unknown specifier is left alone.
     #[test]
     fn starved_and_unknown_specifiers_survive_visibly() {
         assert_eq!(fill("%1$s and %2$s", &[Arg::S("only")]), "only and %2$s");
@@ -465,17 +351,14 @@ mod tests {
         assert_eq!(fill("%q", &[Arg::S("x")]), "%q");
     }
 
-    /// Numbers reach `%s` as digits and strings reach `%d` as themselves — a caller whose argument
-    /// grouping differs from the template's still fills in the template's order.
     #[test]
     fn arguments_render_for_whichever_hole_they_meet() {
         assert_eq!(fill("%s/%d", &[Arg::D(3), Arg::D(5)]), "3/5");
         assert_eq!(fill("%d", &[Arg::S("many")]), "many");
     }
 
-    /// The item tooltip's own two exotic holes, quoted from GlobalStrings (2416, 2441, 942): a
-    /// `%c` sign character and a `%.1f` rate. Both consume an argument like any other hole — the
-    /// bug they replace is a filler that copied them through and showed the player `"%c+5"`.
+    /// `ITEM_MOD_AGILITY`, `ITEM_RESIST_SINGLE` and `DPS_TEMPLATE`, `GlobalStrings.lua:2416`,
+    /// `:2441` and `:942`.
     #[test]
     fn the_sign_and_rate_holes_the_item_builder_uses() {
         assert_eq!(
@@ -493,21 +376,17 @@ mod tests {
             fill("(%.1f damage per second)", &[Arg::F(24.428_571)]),
             "(24.4 damage per second)"
         );
-        // The PRECISION is the template's: respelling it changes the line with no code change.
         assert_eq!(fill("%.3f", &[Arg::F(1.5)]), "1.500");
         assert_eq!(fill("%f", &[Arg::F(1.5)]), "1.500000", "C's default is 6");
-        // `%g` drops the trailing zeros the ammo templates would otherwise show.
         assert_eq!(fill("Adds %g damage", &[Arg::F(7.0)]), "Adds 7 damage");
         assert_eq!(fill("Adds %g damage", &[Arg::F(7.5)]), "Adds 7.5 damage");
     }
 
-    /// A width or flag between the `%` and the letter is skipped rather than breaking the scan,
-    /// and a starved `%.1f` still copies through whole.
     #[test]
     fn widths_and_flags_do_not_derail_the_scan() {
         assert_eq!(fill("%5d|%-3s", &[Arg::D(7), Arg::S("x")]), "7|x");
         assert_eq!(fill("%.1f and %.1f", &[Arg::F(1.0)]), "1.0 and %.1f");
-        // A bare `%` before a digit that never reaches a conversion letter is still just a `%`.
+        // `%1 ` never reaches a conversion letter, so the `%` stays literal.
         assert_eq!(fill("100%1 of it", &[Arg::D(3)]), "100%1 of it");
     }
 }
diff --git a/crates/benilla-ui/src/toc.rs b/crates/benilla-ui/src/toc.rs
index 95c8adb2..3c66828b 100644
--- a/crates/benilla-ui/src/toc.rs
+++ b/crates/benilla-ui/src/toc.rs
@@ -1,37 +1,24 @@
-//! The `.toc` manifest parser — the load list + metadata of every addon, including Blizzard's own
-//! (`FrameXML.toc` and the `Blizzard_*` AddOns are ordinary manifests; third-party addons are the
-//! identical mechanism — decision 0068).
-//!
-//! Grammar, shared by 1.12 and Era manifests (Era only adds directive *keys*, not syntax):
-//! - `## Key: Value` — a directive. Keys compare case-insensitively; localized variants carry a
-//!   locale suffix (`## Title-deDE: …`). Era manifests list several client builds in one
-//!   `## Interface: 11507, 11508`.
-//! - `#` (not followed by another `#`) — a comment.
-//! - anything else non-blank — a file to load, in order (`.lua`/`.xml`, `\` or `/` separators).
-//!
-//! The parser is lossless about order (directives keep file order for duplicate keys; files keep
-//! load order) and byte-tolerant: UTF-8 BOM, `\r\n`, and stray whitespace are the norm in shipped
-//! manifests, not the exception.
+//! The `.toc` manifest parser, for FrameXML, the `Blizzard_*` addons and third-party ones alike:
+//! `## Key: Value` is a directive, any other `#` line a comment, and any other non-blank line a
+//! file to load, in order. A BOM, `\r\n` and stray whitespace are tolerated.
 
-/// A parsed `.toc` manifest: ordered directives + the ordered file load list.
+/// A parsed `.toc` manifest.
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct Toc {
-    /// `## Key: Value` directives in file order, keys as written (compare via [`Toc::directive`]).
+    /// `## Key: Value` pairs in file order, keys as written.
     pub directives: Vec<(String, String)>,
-    /// Files to load, in order, exactly as written (path separators are normalized at *load* time,
-    /// not here — the manifest is quoted verbatim in errors and tooling).
+    /// Files to load, in order, as written; separators are normalized at load time.
     pub files: Vec<String>,
 }
 
-/// Case-insensitive ASCII prefix test — the reference's `SStrCmpI(line, key, SStrLen(key))`.
+/// Case-insensitive ASCII prefix test, the reference's `SStrCmpI(line, key, SStrLen(key))`.
 fn starts_with_ci(s: &str, prefix: &str) -> bool {
     let (s, p) = (s.as_bytes(), prefix.as_bytes());
     s.len() >= p.len() && s[..p.len()].eq_ignore_ascii_case(p)
 }
 
 impl Toc {
-    /// Parse manifest text. Never fails: unrecognizable lines are file entries by definition of
-    /// the grammar, and an empty input is an empty manifest.
+    /// Parse manifest text; never fails, since any unrecognized line is a file entry.
     pub fn parse(text: &str) -> Self {
         let text = text.strip_prefix('\u{feff}').unwrap_or(text);
         let mut toc = Toc::default();
@@ -41,8 +28,7 @@ impl Toc {
                 continue;
             }
             if let Some(directive) = line.strip_prefix("##") {
-                // `##` alone (or without a colon) is treated as a comment, matching the client's
-                // tolerance for malformed directives.
+                // `##` with no colon is a comment, as the client tolerates it.
                 if let Some((key, value)) = directive.split_once(':') {
                     let key = key.trim();
                     if !key.is_empty() {
@@ -57,17 +43,8 @@ impl Toc {
         toc
     }
 
-    /// The directive whose key matches `key` case-insensitively — **the LAST one, when a manifest
-    /// writes the key twice**.
-    ///
-    /// This read the first for as long as the doc here said "shipped manifests don't duplicate
-    /// keys", which two of them do: `MoveAnything.toc` has `## Notes` on lines 3 and 5, and
-    /// `AtlasLoot.toc` has `## Author` on lines 6 and 9. The reference hashes each directive into
-    /// the metadata map at `[rec+0x98]` (`0x51d580`) and, on an existing entry, **frees the old
-    /// value and stores the new** (`0x51d77b`) — a hash insert, so the last line written wins.
-    ///
-    /// Note the asymmetry with [`Self::list`] one function down, and that both halves were wrong
-    /// here in the same direction: a **scalar** replaces, a **list** appends.
+    /// The directive matching `key` case-insensitively, the last one when a key repeats: the
+    /// reference's hash insert into `[rec+0x98]` (`0x51d580`) replaces the old value (`0x51d77b`).
     pub fn directive(&self, key: &str) -> Option<&str> {
         self.directives
             .iter()
@@ -76,21 +53,15 @@ impl Toc {
             .map(|(_, v)| v.as_str())
     }
 
-    /// `## Interface:` as client build numbers. Era manifests list several (`11507, 11508`);
-    /// 1.12's lists one (`11200`). Unparseable entries are skipped, not errors.
+    /// `## Interface:` as build numbers, for display; Era manifests list several (`11507, 11508`).
     pub fn interface_versions(&self) -> Vec<u32> {
         self.directive("Interface")
             .map(|v| v.split(',').filter_map(|n| n.trim().parse().ok()).collect())
             .unwrap_or_default()
     }
 
-    /// `## Interface:` **as the 1.12 client reads it** (decision 1292): the leading integer of
-    /// the value, and a manifest with no `## Interface` line (or a non-numeric one) is `0`.
-    /// Byte-verified (wow-re `addon-version-gate.md` §2.2): `Toc_Parse 0x51c9b0` stores
-    /// `SStrToInt` of the value at `[rec+0x1c]`, the record ctor leaves it `0`, and the version
-    /// gate compares that single dword — so an Era manifest's `11507, 11508` reads as `11507`,
-    /// exactly as the reference would read it. [`Toc::interface_versions`] stays for display;
-    /// the GATE runs on this.
+    /// `## Interface:` as the version gate reads it: `Toc_Parse 0x51c9b0` stores `SStrToInt` of
+    /// the value at `[rec+0x1c]` (else the ctor's `0`), so `11507, 11508` reads `11507`.
     pub fn interface_version(&self) -> u32 {
         self.directive("Interface")
             .map(|v| {
@@ -100,29 +71,14 @@ impl Toc {
             .unwrap_or(0)
     }
 
-    /// A list directive (`SavedVariables`, `OptionalDeps`, `Dependencies`, …), tokenized the way
-    /// the reference tokenizes it. Missing directive = empty list.
-    ///
-    /// **Two departures from the obvious read, both byte-derived, both of which were losing real
-    /// data** (decision 2126):
-    ///
-    /// * **A repeated directive APPENDS.** The reference `strdup`s each item into a `0x40`-granular
-    ///   array at `[rec+0x80]` with a running count at `[rec+0x7c]` (wow-re
-    ///   `savedvariables-protocol.md` §4), so a second `## SavedVariables:` line continues the
-    ///   first rather than being ignored. Reading only the first line cost `CT_RaidAssist` 18 of
-    ///   its 25 saved globals — it declares them across four lines and got seven, so raid
-    ///   positions, menu state, boss timers, debuff templates, the loot method and the squelch
-    ///   list were never written and never restored.
-    /// * **A space separates as surely as a comma.** The tokenizer is `SStrTokenize 0x64ae50` over
-    ///   the delimiter SET `" ,"` at `0x8537c4` — readable in the image's own `.rdata`, sitting
-    ///   between the `RequiredDep` and `OptionalDep` literals. `SpecialTalentUI` writes
-    ///   `## SavedVariables: SpecialTalentPlannedSaved SpecialTalentFrameSaved` and we registered
-    ///   one "global" whose name contained a space.
+    /// A list directive (`SavedVariables`, `OptionalDeps`, …) as the reference tokenizes it: a
+    /// repeated line appends (`0x64a620` into the array at `[rec+0x80]`, count at `[rec+0x7c]`),
+    /// and a space separates like a comma (`SStrTokenize 0x64ae50`, delimiters `" ,"` at
+    /// `0x8537c4`).
     pub fn list(&self, key: &str) -> Vec<&str> {
         self.list_where(|k| k.eq_ignore_ascii_case(key))
     }
 
-    /// [`Self::list`] over every directive whose key satisfies `pick`, in file order.
     fn list_where(&self, mut pick: impl FnMut(&str) -> bool) -> Vec<&str> {
         self.directives
             .iter()
@@ -132,45 +88,34 @@ impl Toc {
             .collect()
     }
 
-    /// Hard dependencies — **every directive whose key STARTS WITH `Dep` or `RequiredDep`**.
-    ///
-    /// The three dependency keys are the only ones in the reference's directive table that carry
-    /// **no colon**: the `.rdata` cluster reads
-    /// `SavedVariablesPerCharacter:\0 SavedVariables:\0 LoadWith:\0 \0\0 Dep\0 RequiredDep\0 " ,"\0\0 OptionalDep\0 Revision:\0`,
-    /// and a whole-key compare against `"Dep"` could never match a line reading `Dependencies:`.
-    /// So the compare is a PREFIX compare — `SStrCmpI(line, key, SStrLen(key))` at
-    /// `0x51cd4e`-`0x51cd5f` — and `## Dependencies`, `## RequiredDependencies` and
-    /// `## Dependency` all land here (decision 2126).
-    ///
-    /// Both keys feed the SAME array in the reference (`[rec+0x50]`), so a manifest writing both
-    /// gets their union rather than whichever this function happened to test first.
+    /// Hard dependencies: every directive whose key starts with `Dep` or `RequiredDep`. The
+    /// reference stores these keys without a colon and prefix-compares them
+    /// (`0x51cd4e`-`0x51cd5f`), so `## Dependencies` and `## RequiredDependencies` both land in
+    /// its one array at `[rec+0x50]`.
     pub fn dependencies(&self) -> Vec<&str> {
         self.list_where(|k| starts_with_ci(k, "RequiredDep") || starts_with_ci(k, "Dep"))
     }
 
-    /// Soft dependencies — every directive whose key starts with `OptionalDep`, on the same
-    /// prefix rule as [`Self::dependencies`].
-    ///
-    /// **They load FIRST and their failures are ignored** — `AddOn_Load 0x51f240`'s own order,
-    /// quoted in 1191 §2 — which is what lets `## OptionalDeps: FuBar, Ace2` mean "if Ace2 is
-    /// installed, its libraries are already global by the time my files run". **130 corpus addons
-    /// declare them**, and the whole FuBar family leans on exactly that: `FuBar_BagFu`'s `.toc`
-    /// lists `FuBarPlugin-2.0.lua` BEFORE `AceLibrary.lua`, which only works because the `Ace2`
-    /// addon went first.
-    ///
-    /// The long form `## OptionalDependencies:` — which 4 corpus addons write — used to be
-    /// refused here, on the reasoning that it was "verified for the required half and merely
-    /// plausible for this one, queued as an RE question". The premise was wrong: the reference
-    /// matches all three dependency keys by the same colon-less prefix, so the long form was never
-    /// a separate question.
+    /// Soft dependencies: every directive whose key starts with `OptionalDep`, the long form
+    /// included. `AddOn_Load 0x51f240` loads them first and ignores their failures.
     pub fn optional_dependencies(&self) -> Vec<&str> {
         self.list_where(|k| starts_with_ci(k, "OptionalDep"))
     }
 
-    /// `## LoadOnDemand: 1` (Era loader; absent in 1.12 manifests).
+    /// `## LoadOnDemand: 1`, which stock 1.12 addons such as `Blizzard_TalentUI` carry.
     pub fn load_on_demand(&self) -> bool {
         self.directive("LoadOnDemand").map(str::trim) == Some("1")
     }
+
+    /// `## DefaultState:`, the byte at `[rec+0x2b]` the enable query `0x51e470` falls back to when
+    /// characters disagree or none has chosen. `Toc_Parse` stores `"enabled"` (`0x853764`) as 1 and
+    /// `"disabled"` (`0x853758`) as 0 at `0x51d204` and any other value not at all (`0x51d21a`);
+    /// the ctor `0x520550` seeds 1 (`0x5205b9`), so only `disabled` disables.
+    pub fn default_state(&self) -> bool {
+        !self
+            .directive("DefaultState")
+            .is_some_and(|v| v.trim().eq_ignore_ascii_case("disabled"))
+    }
 }
 
 #[cfg(test)]
@@ -205,6 +150,29 @@ mod tests {
         assert_eq!(toc.directives.len(), 4);
     }
 
+    #[test]
+    fn default_state_is_enabled_unless_the_manifest_says_disabled() {
+        let d = |body: &str| Toc::parse(body).default_state();
+        assert!(d("## Interface: 11200\n"), "absent: the ctor's own 1");
+        assert!(d("## DefaultState: enabled\n"));
+        assert!(!d("## DefaultState: disabled\n"));
+        assert!(
+            !d("## DefaultState:    DISABLED   \n"),
+            "trimmed, case-folded"
+        );
+        assert!(
+            d("## DefaultState: maybe\n"),
+            "neither literal: no store, the 1 stands"
+        );
+        assert!(
+            d("## DefaultState:\n"),
+            "empty value is not `disabled` either"
+        );
+        // Last-wins, the reference's hash insert.
+        assert!(!d("## DefaultState: enabled\n## DefaultState: disabled\n"));
+        assert!(d("## DefaultState: disabled\n## DefaultState: enabled\n"));
+    }
+
     #[test]
     fn vanilla_1_12_shape() {
         let toc = Toc::parse(
@@ -220,10 +188,6 @@ mod tests {
         assert_eq!(toc.files.len(), 2);
     }
 
-    /// **A scalar directive REPLACES on a repeat; a list directive APPENDS** — the reference's two
-    /// stores, and this file had both backwards (decision 2126). `MoveAnything.toc` writes
-    /// `## Notes` twice and `AtlasLoot.toc` writes `## Author` twice, so the scalar half is not
-    /// hypothetical either.
     #[test]
     fn a_scalar_directive_replaces_and_a_list_directive_appends() {
         let toc = Toc::parse(
@@ -237,13 +201,6 @@ mod tests {
         assert!(toc.load_on_demand());
     }
 
-    /// **`CT_RaidAssist`'s own manifest, in shape** — 25 saved globals across four lines, of which
-    /// we registered the first seven. The rest (raid positions, menu state, boss timers, debuff
-    /// templates, the loot method, the squelch list) were never written and never restored.
-    ///
-    /// Plus `SpecialTalentUI`'s: two names separated by a SPACE, which we read as one global whose
-    /// name contained a space. The tokenizer is `SStrTokenize 0x64ae50` over the delimiter set
-    /// `" ,"` at `0x8537c4`.
     #[test]
     fn a_repeated_list_directive_accumulates_across_lines_and_splits_on_space() {
         let toc = Toc::parse(
@@ -255,15 +212,6 @@ mod tests {
         assert_eq!(toc.list("SavedVariablesPerCharacter"), vec!["E", "F"]);
     }
 
-    /// **The three dependency keys are matched by PREFIX**, because they are the only directives in
-    /// the reference's table with no colon: the `.rdata` cluster is
-    /// `… LoadWith:\0 \0\0 Dep\0 RequiredDep\0 " ,"\0\0 OptionalDep\0 Revision:\0 …`, and a
-    /// whole-key compare against `"Dep"` could never match a line reading `Dependencies:`.
-    ///
-    /// Four corpus addons write the long optional form (`FuBar_CRDelayFu`, `FuBar_PetInFu`,
-    /// `FuBar_ToFu`, `FuBar_WeaponRebuffFu`), which this file used to refuse on the reasoning that
-    /// the long form was "merely plausible" for the optional half. It was never a separate
-    /// question.
     #[test]
     fn the_dependency_keys_match_by_prefix_and_both_required_spellings_union() {
         let toc = Toc::parse(
@@ -278,8 +226,7 @@ mod tests {
             vec!["LibC", "LibD", "LibE"],
             "the long and short optional spellings are the same key"
         );
-        // And the prefixes do not bleed into each other: `OptionalDependencies` does not start
-        // with `Dep`, so it never lands in the required list.
+        // `OptionalDependencies` does not start with `Dep`.
         assert!(!toc.dependencies().contains(&"LibC"));
     }
 
@@ -289,21 +236,4 @@ mod tests {
         let toc = Toc::parse("# only a comment\n\n");
         assert!(toc.directives.is_empty() && toc.files.is_empty());
     }
-
-    /// Parses a REAL shipped manifest when `BENILLA_TOC` points at one (never committed — extract
-    /// e.g. `Interface\FrameXML\FrameXML.toc` with benilla-extract and export the path). Skips
-    /// silently otherwise, so CI/gates don't depend on client data.
-    #[test]
-    fn real_manifest_when_available() {
-        let Ok(path) = std::env::var("BENILLA_TOC") else {
-            return;
-        };
-        let text = std::fs::read_to_string(&path).expect("reading BENILLA_TOC");
-        let toc = Toc::parse(&text);
-        assert!(!toc.files.is_empty(), "a real manifest lists files");
-        assert!(
-            !toc.interface_versions().is_empty(),
-            "a real manifest declares ## Interface"
-        );
-    }
 }
diff --git a/crates/benilla-ui/src/widget/kinds/editbox.rs b/crates/benilla-ui/src/widget/kinds/editbox.rs
index ca6f8e8a..4028ba68 100644
--- a/crates/benilla-ui/src/widget/kinds/editbox.rs
+++ b/crates/benilla-ui/src/widget/kinds/editbox.rs
@@ -3,287 +3,136 @@ use super::RegionHandle;
 /// The text span a cursor motion or deletion operates over.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum EditUnit {
-    /// One character (the plain arrow / Backspace / Delete granularity).
+    /// One character, a whole link counting as one: plain arrow, Backspace, Delete.
     Char,
-    /// One word run ([`EditBoxState::word_boundary`] — the Ctrl/Option-arrow granularity).
+    /// One word run ([`EditBoxState::word_boundary`]): Ctrl/Option+arrow.
     Word,
-    /// The line edge: text start going back, text end going forward (Home/End, Cmd+arrow).
+    /// Text start going back, text end going forward: Home/End, Cmd+arrow.
     Edge,
 }
 
-/// One semantic text-editing operation on an edit box — fed to [`EditBoxState::apply`]. The host's
-/// per-OS keymap (which physical chord means which action: Ctrl+Left on Windows, Option+Left on
-/// macOS, …) translates key events into these; the *effect* of each action is the byte-verified box
-/// law (RF-0082: selection anchoring, selection-first deletes, word classes). Clipboard operations
-/// are deliberately absent: they need the OS pasteboard, so they stay host-side.
+/// One semantic editing operation for [`EditBoxState::apply`]: the host's per-OS keymap picks the
+/// action, the reference's edit-box law decides its effect. Clipboard operations stay host-side.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum EditAction {
-    /// Move the caret one `unit` back/forward; `extend` drags the selection from its fixed
-    /// anchor (the Shift family). (The alt-arrow gate is upstream, on the key — the
-    /// ref guard `0x77b18e`; arrows are the only chord source of `Char` moves).
+    /// Move the caret one `unit`; `extend` (Shift) drags the selection from its fixed anchor. The
+    /// alt-arrow gate (`0x77b18e`) acts upstream, on the key.
     Move {
         unit: EditUnit,
         back: bool,
         extend: bool,
     },
-    /// Delete one `unit` back/forward from the caret — the selection first when one exists
-    /// (every deletion gesture collapses to "delete the selection"). `Edge` going back is the
-    /// macOS Cmd+Backspace "clear to start".
+    /// Delete one `unit` from the caret, or the selection if any; `Edge` back is Cmd+Backspace.
     Delete { unit: EditUnit, back: bool },
-    /// Select the whole text, caret to the end (the ref's Ctrl+A, `HighlightText(0, -1)`).
+    /// Ctrl+A: select all, caret to the end (`HighlightText(0, -1)`).
     SelectAll,
-    /// Recall the previous (older) submitted line into the box (`historyLines`).
+    /// Recall the next older submitted line (`historyLines`).
     HistoryPrev,
     /// Step back toward the newest line; past it, restore the stashed draft.
     HistoryNext,
 }
 
-/// A `CSimpleEditBox`'s runtime state — the byte-verified text/cursor/selection/flags model of
-/// RF-0082 (`rf82-editbox-runtime.md`). Offsets below are the client's **E-base** (the CScriptObject
-/// `this`), the base the runtime input/text handlers address the object through.
-///
-/// The client stores text as a NUL-terminated `char*` with a parallel per-byte class array; benilla
-/// holds it as a Rust `String` and keeps every byte offset ([`cursor`](Self::cursor)/
-/// [`sel_start`](Self::sel_start)/[`sel_end`](Self::sel_end)) snapped to a UTF-8 char boundary — the
-/// same invariant the client's boundary-snap (`0x77bd30`) maintains.
+/// A `CSimpleEditBox`'s runtime state; `E+` offsets are from its `CScriptObject` `this`. Byte
+/// offsets stay on char boundaries, as the client's boundary snap (`0x77bd30`) keeps them.
 #[derive(Clone, Debug, PartialEq)]
 pub struct EditBoxState {
-    /// The real text buffer (`E+0x32c`, `char*`). `GetText`/`GetNumber` read this; `password` masks
-    /// only the *display*, never this buffer (RF-0082 §3).
+    /// The real text (`E+0x32c`); `password` masks only the display (`E+0x334`, `0x77d4d0`).
     pub text: String,
-    /// The insertion caret as a byte offset into [`text`](Self::text) (`E+0x36c`; sole setter
-    /// clamps to `[0, len]`). Always on a char boundary.
+    /// The caret, a byte offset into the text (`E+0x36c`, clamped to `[0, len]`).
     pub cursor: usize,
-    /// Selection anchor (`E+0x35c`) — equal to [`sel_end`](Self::sel_end) (and the cursor) when no
-    /// text is selected. Byte offset, char-boundary-snapped.
+    /// Selection start (`E+0x35c`); equal to `sel_end` and the cursor when nothing is selected.
     pub sel_start: usize,
-    /// Selection end (`E+0x360`). A non-empty selection is `sel_start != sel_end`; every insert
-    /// replaces it first (RF-0082 §3).
+    /// Selection end (`E+0x360`); an insert replaces a non-empty selection first (`0x77cd70`).
     pub sel_end: usize,
-    /// `autoFocus` (`flags@E+0x318` bit0). Two acquisition paths, and both are built:
-    ///
-    /// 1. **On SHOW** — the box self-focuses when it becomes visible, gated on nothing else holding
-    ///    focus. The EditBox's own OnShow vtable override (`0x81c910` slot +0x30, `0x77a750`) fires
-    ///    the Lua handler and then tail-jumps `SetFocus`:
-    ///    `if ([0xcf4dc8] == 0 && (flags & 1)) jmp 0x77e3d0` @`0x77a76d`. The mirror slot +0x34
-    ///    (`0x77a780`) tail-jumps `ClearFocus`, so **hiding an edit box releases the keyboard**.
-    ///    Ours is [`crate::script::editbox`]'s `visibility_focus`.
-    /// 2. **On the first key/char event** while nothing is focused — the self-acquire guard; the box
-    ///    grabs focus and processes that same event.
-    ///
-    /// **Both corrections landed together, decision 1686 (2026-08-29).** wow-re's own
-    /// `ui.md`/RF-0082 had published "autoFocus does NOT focus on show, verified by absence" off a
-    /// census written over `call` alone, which cannot see a tail-`jmp`; a `(call|jmp)` census finds
-    /// the eleventh site (`editbox-selection-focus-law.md` §6). The construction default came with
-    /// it and is byte-read, not chosen — see [`Default`]'s `flags = 1` note below. Every
-    /// `autoFocus` in the shipped 1.12.1 chain is `="false"`, ten opt-outs and no opt-ins, which is
-    /// the authoring signature of exactly that default.
+    /// `autoFocus` (`E+0x318` bit 0): take the focus when shown if nothing holds it (the OnShow
+    /// override `0x77a750`, `0x77a76d`) and on a key or char event while nothing is focused.
     pub auto_focus: bool,
-    /// `multiLine` (bit1): Enter inserts a newline (rather than firing `OnEnterPressed`) and `\n` is
-    /// accepted into the buffer.
+    /// `multiLine` (bit 1): Enter inserts a newline instead of firing `OnEnterPressed`.
     pub multi_line: bool,
-    /// `numeric` (bit2): an insert containing ANY char outside `'0'..='9'` is aborted wholesale
-    /// (not per-char filtered) — RF-0082 §3.
+    /// `numeric` (bit 2): an insert with any non-digit is refused whole, not filtered (`0x77bf41`).
     pub numeric: bool,
-    /// `password` (bit3): the display string is one `'*'` per *character* (the mask, `E+0x334`); the
-    /// real text is untouched.
+    /// `password` (bit 3): the display is one `*` per character (`E+0x334`); the text is untouched.
     pub password: bool,
-    /// **Alt-arrow mode** (bit4) — the XML attribute spells it `ignoreArrows`, the Lua surface
-    /// spells it `SetAltArrowKeyMode`/`GetAltArrowKeyMode` (`0x7996e0`/`0x799790`), and there is
-    /// exactly one flag behind both names. `SetIgnoreArrows` does **not** exist in 5875: the
-    /// 48-entry EditBox method table `[0x87bb68, 0x87bce8)` carries the Alt pair at 46/47 and no
-    /// entry whose name contains "Ignore" (wow-re `ignorearrows-alt-arrow-gate.md`, §5 VERIFIED).
-    ///
-    /// **What it does, and it is not what "ignore" suggests.** With the flag set, the four arrow
-    /// keys (`0x204` LEFT / `0x205` UP / `0x206` RIGHT / `0x207` DOWN) are **not consumed by the
-    /// box at all** unless ALT is held — the guard `0x77b18e` returns 0, the strata walk carries
-    /// on down to `CGWorldFrame`, and the key reaches its binding (`TURNLEFT`, `MOVEFORWARD`).
-    /// That is the whole point: it is what lets you turn while the chat box has focus. With Alt
-    /// held the guard falls through to ordinary handling and the caret moves.
-    ///
-    /// A focused box otherwise consumes **everything** (the handler's shared tail `0x77b35e`
-    /// returns 1), so these four keys are the only ones it ever lets past.
-    ///
-    /// benilla read this as "consumed but inert, unless Ctrl" for two rounds — the modifier was
-    /// wrong (a wow-re note said `0x41f8f0(2)` was Ctrl; it is ALT, and five other notes already
-    /// said so) and so was the consumption. Both corrected by the §5.
+    /// Alt-arrow mode (bit 4; XML `ignoreArrows`, Lua `SetAltArrowKeyMode`): a focused box lets the
+    /// four arrows through to their bindings unless Alt (`0x41f8f0(2)`) is held (`0x77b18e`), so
+    /// you can turn while typing. It consumes every other key (`0x77b35e`).
     pub alt_arrow_key_mode: bool,
-    /// `maxLetters` (`E+0x340`, 0 = unlimited): after each insert, trim from the end while the
-    /// *letter* (char) count exceeds this (RF-0082 §3).
+    /// `maxLetters` (`E+0x340`), 0 for unlimited.
     pub max_letters: usize,
-    /// `maxBytes` (`E+0x33c`; the client's `-1` sentinel = unlimited → `None` here): trim from the
-    /// end while the byte length exceeds this, applied before `maxLetters`.
+    /// `maxBytes` (`E+0x33c`); the client's `-1`, unlimited, is `None`.
     pub max_bytes: Option<usize>,
-    /// The implicit FontString the text renders through (`E+0x328`, the EditBox's analogue of
-    /// ButtonText). **Built by the ctor**, not lazily: `0x779bee` constructs it from allocator
-    /// `0xcf4d10` with tag `0x846544` = `".?AVCSimpleFontString@@"` via `0x770d30(E, 2, 1)`, and
-    /// that is the FIRST of the five regions a `CSimpleEditBox` is born with (wow-re
-    /// `system/ui/scratch/rf85-editbox-caret.md` §1). Creation order is what `GetRegions` hands
-    /// Lua — one flat creation-ordered list off `[frame+0x1b8]`, oldest first, no filter
-    /// (`scratch/widget-list-bindings.md`) — so these five precede every `<Layers>` region.
-    ///
-    /// **DEFERRED, and named rather than silently taken:** the ctor's draw layer is 2 sub 1
-    /// (ARTWORK), while this region is still created at OVERLAY sub 0 — what ships today and what
-    /// the director has looked at. Moving it is a draw-order change to every EditBox in the client
-    /// with nothing asking for it, so it is a separate change, not a rider on this one.
+    /// The implicit FontString the text renders through (`E+0x328`, ctor `0x779bee`).
     pub text_region: Option<RegionHandle>,
-    /// The **three selection-highlight quads** (`E+0x350`/`0x354`/`0x358`), built by the ctor loop
-    /// `0x779c41–0x779c72` as `CSimpleTexture`s via `0x76fc40(E, 2, 0)` — allocator `0xcf4ce0`, tag
-    /// `0x846588` = `".?AVCSimpleTexture@@"`, class-identical to the caret (RF-0085 §1). They are
-    /// members of the frame's region list like any other region (`0x76fc40`→`0x77f640`→`0x77fd10`,
-    /// the single linker into `[frame+0x1b8]`), which is why they are built here.
-    ///
-    /// **They carry no art of their own and paint nothing.** benilla draws the selection highlight
-    /// host-side, from [`sel_start`](Self::sel_start)/[`sel_end`](Self::sel_end) through the seam —
-    /// so these are the real regions the client has, not yet the regions the highlight rides.
-    /// Routing the paint through them is a separate, larger change (the host would have to read a
-    /// region rect instead of a seam field); this is stated, not stubbed.
+    /// The three selection-highlight textures (`E+0x350`/`0x354`/`0x358`, ctor `0x779c41`). They
+    /// paint nothing: the host draws the highlight from `sel_start`/`sel_end`.
     pub selection_regions: [Option<RegionHandle>; 3],
-    /// The **caret** (`E+0x368`), the ctor's fifth and last region: a `CSimpleTexture` built at
-    /// `0x779c86–0x779cac` via `0x76fc40(E, 3, 1)` — a solid vertex-coloured quad, never a glyph
-    /// (no texture path is ever assigned to `E+0x368`, band-wide census; RF-0085 §1). Layer 3 over
-    /// the text's 2 is why the caret draws above the text and the selection quads below it.
-    ///
-    /// Same standing as [`selection_regions`](Self::selection_regions): the region is real and in
-    /// the list, the *painting* is still host-side off [`caret_shown`](Self::caret_shown).
+    /// The caret texture (`E+0x368`, ctor `0x779c86`), a solid quad above the text. It paints
+    /// nothing: the host draws the caret from `caret_shown`.
     pub caret_region: Option<RegionHandle>,
-    /// The submitted-line history (`AddHistoryLine`; the XML `historyLines` cap) — oldest first,
-    /// newest last; UP recalls older from the end, DOWN newer. The exact recall keys + draft
-    /// model are INFERRED (wow-re's rf82 flags the 1.12 history controller as an untraced
-    /// observer, `0x77b730`) — plain UP/DOWN with the in-progress line restored past the newest
-    /// entry; on the chat-arc wow-re dispatch list (decision 0288).
+    /// The submitted lines, oldest first. UP/DOWN recall and the restored draft are inferred: the
+    /// reference's history controller (`0x77b730`) is untraced.
     pub history: Vec<String>,
-    /// `historyLines` — max entries kept (drop-oldest on add). `0` = history off (the widget
-    /// default; ChatFrame's edit box declares 32).
+    /// `historyLines`, the most lines kept; 0 (the default) is no history.
     pub history_max: usize,
-    /// The active recall position while browsing (an index into [`Self::history`]); `None` = live
-    /// editing. Typed edits, [`Self::add_history_line`], and focus gain end browsing —
-    /// programmatic `SetText` deliberately does NOT (the chat live parse rewrites the box on
-    /// every recalled slash line; ending the browse there pinned every UP to the newest entry).
+    /// The recall position, `None` while editing. `SetText` must not end the browse: the chat
+    /// parser rewrites a recalled slash line through it.
     pub history_pos: Option<usize>,
     /// The live line stashed when browsing starts, restored when DOWN walks past the newest entry.
     pub history_draft: Option<String>,
-    /// `SetTextInsets(l, r, t, b)` / XML `<TextInsets>` — the text region's rect shrink inside the
-    /// box (the chat edit box drives its left inset past the "Say:" header every header change).
-    /// Applied as the text region's two corner anchors (`script::editbox::set_text_insets`).
+    /// `SetTextInsets(l, r, t, b)`, applied as the text region's two corner anchors.
     pub text_insets: [f32; 4],
-    /// The focused box's per-byte cumulative advance table — the host's answer to the advance
-    /// measure request: `advances[i]` = laid-out width of `display[..i]` (len+1 entries; a
-    /// continuation byte repeats its lead's value). This is the metrics seam that makes
-    /// click→index (`0x77d0d0`), drag-select, and the scroll window engine-local — the real
-    /// client reads the same geometry off its embedded render object. Empty until answered.
+    /// The host-measured width of `display[..i]` per byte `i`, a continuation byte repeating its
+    /// lead's; hit-testing (`0x77d0d0`) and the scroll window read it. Empty until answered.
     pub advances: Vec<f32>,
-    /// Cache key of [`Self::advances`] (display text + font identity hash) — the same staleness
-    /// discipline as the FontString measure round-trip.
+    /// Hash of the display text and font [`Self::advances`] was measured for.
     pub advances_key: u64,
-    /// The wrapped-row starts of the DISPLAY string — answered with [`Self::advances`] by the
-    /// host, which runs the same wrap pass the draw uses. `rows[i]` is the byte where row `i`
-    /// begins; row `i` covers `rows[i]..rows[i+1]` (last row to end of display). Always at least
-    /// `[0]`; a single-line box stays exactly `[0]`. The 2-D caret/click law
-    /// ([`Self::caret_row_x`]/[`Self::index_at_pos`]) reads it; bytes swallowed at a break (the
-    /// dropped trailing separator, the `\n` itself) belong to the row they end.
+    /// The display byte each wrapped row starts at, measured by the host with the draw's wrap pass;
+    /// at least `[0]`. Bytes swallowed at a break (the space, the `\n`) belong to the row they end.
     pub rows: Vec<usize>,
-    /// The row pitch in px (the snapped font em — the same `N·S` block law the host's measure
-    /// uses), answered with [`Self::advances`]. `0.0` until answered.
+    /// The row pitch in pixels (the snapped font em), answered with the advances; 0 until then.
     pub cell_h: f32,
-    /// The `(row, x)` the last `OnCursorChanged` was fired with — the caret-flush edge's memory
-    /// (`0x77da80`, whose one caller `0x77d475` is gated on dirty bit 2, so the fire is per
-    /// *change*, not per frame). `None` = never fired, which is what makes the first flush after
-    /// a focus fire even though the caret is at the home position.
+    /// The `(row, x)` of the last `OnCursorChanged`, fired per change (`0x77da80`, dirty bit 2 at
+    /// `0x77d475`); `None` lets the first flush after focus fire with the caret at home.
     pub cursor_fired: Option<(usize, f32)>,
-    /// First visible byte of the display window (`E+0x348` display/scroll start index) — the
-    /// char-granular h-scroll. Clamped each read so the cursor stays inside the window
-    /// (`0x77da80`'s early-out hides the caret outside `[start, start+visible]`).
+    /// The first visible display byte of a single-line box (`E+0x348`), scrolled by whole chars
+    /// to keep the caret in view; `0x77da80` hides a caret outside the window.
     pub scroll_start: usize,
-    /// A LeftButton press landed inside the box and hasn't released (`E+0x364`
-    /// mouse-drag-active): every mouse move maps to a char index and extends the selection there,
-    /// cursor following (`0x77a860`).
+    /// A left-button press in the box is held (`E+0x364`); moves extend the selection (`0x77a860`).
     pub drag_active: bool,
-    /// Caret blink half-period in seconds (`E+0x370`; ctor default **0.5**, the XML `blinkSpeed`
-    /// attr overrides).
+    /// Caret blink half-period in seconds (`E+0x370`; ctor 0.5, XML `blinkSpeed`).
     pub blink_period: f32,
-    /// Blink accumulator (`E+0x374`): += dt while focused; crossing the period toggles
-    /// [`Self::caret_shown`] and resets.
+    /// Blink accumulator (`E+0x374`): grows while focused; crossing the period toggles the caret.
     pub blink_accum: f32,
-    /// The blink phase — caret visible this half-period. Every cursor/text/selection change
-    /// resets it to `true` with a fresh accumulator (the client's click path calls the dirty
-    /// flush's blink reset before placing the cursor).
+    /// The caret shows this half-period; every cursor, text or selection change turns it on.
     pub caret_shown: bool,
-    /// The selection highlight tint (`SetHighlightColor`, the `E+0x350` texture trio's color;
-    /// ctor default **0xFF606060** — opaque medium gray). RGBA 0..1.
+    /// The selection tint (`SetHighlightColor`), RGBA 0..1; the ctor default is `0xFF606060`.
     pub highlight_color: [f32; 4],
-    /// The justification bit word behind `Set/GetJustifyH` and `Set/GetJustifyV` — entries #12–#15
-    /// of the EditBox method table (`0x797990`/`0x797a50`/`0x797b10`/`0x797bd0`, tail-calling the
-    /// shared `0x79fc20`/`0x79fcb0`/`0x79fce0`/`0x79fd70`).
-    ///
-    /// **One dword, two axes** (`CSimpleFont+0x54` / `CSimpleFontString+0x120`), from the 6-entry
-    /// enum at `.rdata 0x811ad0`: bits 0–2 horizontal (`LEFT` 0x01, `CENTER` 0x02, `RIGHT` 0x04),
-    /// bits 3–5 vertical (`TOP` 0x08, `MIDDLE` 0x10, `BOTTOM` 0x20).
-    ///
-    /// **An EditBox's default is `0x211` — LEFT, not the generic CENTER.** The `CSimpleFont` ctor
-    /// default really is `0x212` (`CENTER | MIDDLE | 0x200`), but the EditBox constructor
-    /// *overrides* the horizontal axis immediately after linking its font instance —
-    /// `0x779bcd mov ecx,[edi+0x54]; and eax,~6; or eax,1; 0x779be4 mov [edi+0x54],eax` — so
-    /// `GetJustifyH()` on a fresh box answers **`"LEFT"`**. Bit `0x200` falls outside both axis
-    /// masks and neither accessor reads it, so only `0x11` is modelled. (wow-re
-    /// `system/ui/scratch/editbox-font-surface.md` §6.2; this **corrected** our first cut, which
-    /// took the generic `0x212` and answered `"CENTER"`.)
-    ///
-    /// **Kept on the box, not on its text region.** Each font binding's shim hands the shared
-    /// implementation `[this+0x324]` — the box's implicit FontString, i.e. [`Self::text_region`] —
-    /// so on the reference these do write that string's justify field. But our EditBox draw law
-    /// seats that region's vertical justification by `multiLine` (TOP / MIDDLE) and its horizontal
-    /// one LEFT, and writing the region here would fight that law *and* be clobbered by the next
-    /// `SetMultiLine`.
-    ///
-    /// **The vertical half of that is now VERIFIED to be exactly right, and for a reason worth
-    /// keeping** (§6 of the note above). `CSimpleFontString+0x124` is a per-bit *inherit* mask over
-    /// `+0x120`, and `SetMultiLine 0x77a4a0` clears the whole vertical group `0x38` from it on
-    /// **both** legs while writing the V bits locally (multi-line → TOP, single-line → MIDDLE) —
-    /// and the EditBox ctor calls `SetMultiLine` unconditionally at birth (`0x779c2f`, with the
-    /// ctor's zero register). A census of all 256 `+0x124` operands image-wide found every
-    /// `CSimpleFontString` writer to be an AND: **nothing ever ORs an inherit bit back.** So
-    /// `SetJustifyV` writes the instance and is masked out at `0x77086e`, never reaching the
-    /// rendered text, while `GetJustifyV` reads the instance (`0x79fd73`) and echoes it back:
-    /// **the getter and the pixels disagree permanently, by construction, on the real client too.**
-    /// Our rendered V justify is decided solely by `multiLine`, which is the same rule.
-    ///
-    /// **The horizontal half stays open, and is deliberately not guessed.** `SetMultiLine` never
-    /// clears the `0x7` bits, so `SetJustifyH`'s value *does* reach the FontString's `+0x120` —
-    /// but whether the editbox's own draw `0x77da80` reads it for placement, rather than
-    /// left-anchoring at the insets rect the way rf82's windowed draw describes, is untraced.
-    /// Verifying that the value propagates is not verifying that the draw honours it, so the
-    /// reading that changes no pixels is the one taken and the question is named. It is the whole
-    /// visible difference for `AceGUIWidget-Slider.lua:210`'s `editbox:SetJustifyH("CENTER")`
-    /// (3 corpus addons), whose call now round-trips either way.
+    /// The bits of `Set/GetJustifyH` and `Set/GetJustifyV` (`0x797990`-`0x797bd0`), kept on the
+    /// box and not drawn. For V that is the reference: `SetMultiLine` (`0x77a4a0`) makes the
+    /// text's V bits local, so a `SetJustifyV` is masked out (`0x77086e`) and only the getter sees
+    /// it. Whether the draw (`0x77da80`) reads H is untraced.
     pub justify: u32,
 }
 
 impl EditBoxState {
-    /// The horizontal axis mask (bits 0–2) — `SetJustifyH`'s `(cur & ~7) | (parsed & 7)`.
+    /// The horizontal justify bits (0-2).
     pub const JUSTIFY_H_MASK: u32 = crate::justify::H_MASK;
-    /// The vertical axis mask (bits 3–5) — `SetJustifyV`'s.
+    /// The vertical justify bits (3-5).
     pub const JUSTIFY_V_MASK: u32 = crate::justify::V_MASK;
 
-    /// Parse a justify token to its bit — [`crate::justify::parse_bits`]. `None` = no match, which
-    /// is what makes the caller raise `Usage: %s:SetJustifyH("justify")`; the reference checks this
-    /// one, unlike `SetTextColor`.
+    /// A justify token's bit; `None` makes the caller raise the reference's
+    /// `Usage: %s:SetJustifyH("justify")`.
     pub fn justify_bit(token: &str) -> Option<u32> {
         crate::justify::parse_bits(token)
     }
 
-    /// Replace one axis's bits with `parsed`'s — [`crate::justify::set_axis`].
-    ///
-    /// **The verified trap this reproduces:** `SetJustifyH("TOP")` *parses* (0x08) but
-    /// `0x08 & 0x07 == 0`, so it **clears** justifyH and a later `GetJustifyH()` answers
-    /// `"UNKNOWN"` — no error is raised. A plausible implementation that maps unknown-to-CENTER
-    /// silently answers something the client never would; the FontString and `<Font>` tables both
-    /// did exactly that until this law was lifted out of here and shared with them.
+    /// Replace one axis's bits with `parsed`'s. `SetJustifyH("TOP")` parses but clears the H bits,
+    /// so `GetJustifyH()` then answers `"UNKNOWN"`, with no error.
     pub fn set_justify_axis(&mut self, mask: u32, parsed: u32) {
         self.justify = crate::justify::set_axis(self.justify, mask, parsed);
     }
 
-    /// The token for one axis — [`crate::justify::name_of`].
+    /// The token for one axis.
     pub fn justify_token(&self, mask: u32) -> &'static str {
         crate::justify::name_of(self.justify, mask)
     }
@@ -296,8 +145,8 @@ impl Default for EditBoxState {
             cursor: 0,
             sel_start: 0,
             sel_end: 0,
-            // `flags = 1` at construction (`0x779a29`/`0x779a2e`): bit0 (autoFocus) SET, every
-            // other flag clear. A box that says nothing self-focuses when shown.
+            // The ctor sets the flags to 1 (`0x779a29`/`0x779a2e`), autoFocus alone, so a box
+            // that says nothing self-focuses when shown.
             auto_focus: true,
             multi_line: false,
             numeric: false,
@@ -321,21 +170,19 @@ impl Default for EditBoxState {
             blink_period: 0.5,
             blink_accum: 0.0,
             caret_shown: true,
-            // Filled by `Arena::create`'s ctor pass — `Default` cannot reach the arena, and a
-            // handle-less default is what a not-yet-created box has.
+            // Filled by `WidgetArena::create`'s ctor pass, which `Default` cannot reach.
             selection_regions: [None; 3],
             caret_region: None,
             highlight_color: [96.0 / 255.0, 96.0 / 255.0, 96.0 / 255.0, 1.0],
-            // The EditBox ctor's `0x211` minus the unread bit 0x200 — `LEFT | MIDDLE`. LEFT, not
-            // the generic font default CENTER: `0x779be4` overrides the H axis at construction.
+            // The ctor's `0x211` less the unread bit 0x200: LEFT | MIDDLE, since the ctor
+            // overrides the font default's CENTER (`0x779be4`).
             justify: 0x01 | 0x10,
         }
     }
 }
 
 impl EditBoxState {
-    /// `AddHistoryLine`: append (drop-oldest past [`Self::history_max`]) and end any browse in
-    /// progress. Empty lines and a zero cap are no-ops.
+    /// `AddHistoryLine`: append the line, dropping the oldest past the cap, and end any browse.
     pub fn add_history_line(&mut self, line: &str) {
         if self.history_max == 0 || line.is_empty() {
             return;
@@ -349,10 +196,8 @@ impl EditBoxState {
         self.history_draft = None;
     }
 
-    /// One UP (`older = true`) or DOWN step through the history. Returns the text the box should
-    /// now show: entering browse mode stashes the live draft; stepping past the newest entry
-    /// leaves browse mode and returns the draft. `None` = nothing to do (no history / already at
-    /// the oldest / not browsing on DOWN).
+    /// One UP (`older`) or DOWN step, returning the text to show: the first UP stashes the draft,
+    /// and DOWN past the newest entry restores it.
     pub fn history_step(&mut self, older: bool) -> Option<String> {
         if self.history.is_empty() {
             return None;
@@ -363,11 +208,11 @@ impl EditBoxState {
                 self.history_pos = Some(self.history.len() - 1);
             }
             (None, false) => return None,
-            (Some(0), true) => return None, // already at the oldest — hold
+            (Some(0), true) => return None, // at the oldest: hold
             (Some(p), true) => self.history_pos = Some(p - 1),
             (Some(p), false) if p + 1 < self.history.len() => self.history_pos = Some(p + 1),
             (Some(_), false) => {
-                // Past the newest — back to the stashed live line.
+                // Past the newest: back to the stashed draft.
                 self.history_pos = None;
                 return Some(self.history_draft.take().unwrap_or_default());
             }
@@ -375,19 +220,16 @@ impl EditBoxState {
         self.history_pos.map(|p| self.history[p].clone())
     }
 
-    /// End any history browse (the recalled line becomes an ordinary draft; the stash is
-    /// dropped). Called on typed edits, [`Self::add_history_line`], and focus gain — never on
-    /// programmatic `SetText` (see [`Self::history_pos`]).
+    /// End any history browse; `SetText` must not call this (see [`Self::history_pos`]).
     pub fn end_history_browse(&mut self) {
         self.history_pos = None;
         self.history_draft = None;
     }
 
-    // ── selection / geometry law (RF-0082 §4 + the diffed mouse/caret leaves) ────────────────
+    // ── selection / geometry law ─────────────────────────────────────────────────────────────
 
-    /// The DISPLAY string — what the box draws, what the advance table indexes, and what
-    /// hit-tests run against: the text itself, or one `'*'` per character under `password`
-    /// (the `E+0x334` mask; both draw `0x77da80` and hit-test `0x77d0d0` branch on the flag).
+    /// What the box draws and hit-tests: the text, or one `*` per character under `password`
+    /// (`E+0x334`; the draw `0x77da80` and the hit-test `0x77d0d0` both branch on the flag).
     pub fn display(&self) -> String {
         if self.password {
             "*".repeat(self.text.chars().count())
@@ -396,8 +238,7 @@ impl EditBoxState {
         }
     }
 
-    /// TEXT byte offset → DISPLAY byte offset (identity unless `password`, where each char is
-    /// one `'*'` byte).
+    /// A text byte offset as a display byte offset.
     pub fn text_to_display(&self, byte: usize) -> usize {
         if self.password {
             self.text[..byte.min(self.text.len())].chars().count()
@@ -406,7 +247,7 @@ impl EditBoxState {
         }
     }
 
-    /// DISPLAY byte offset → TEXT byte offset (inverse of [`Self::text_to_display`]).
+    /// A display byte offset as a text byte offset.
     pub fn display_to_text(&self, dbyte: usize) -> usize {
         if self.password {
             self.text
@@ -418,24 +259,16 @@ impl EditBoxState {
         }
     }
 
-    /// The char-boundary DISPLAY index nearest pixel `x` (x measured from the text origin, i.e.
-    /// the advance table's zero — the caller adds the scroll window's offset first). Walks the
-    /// cumulative table over char boundaries; nearest-boundary rounding (INFERRED — `0x77d0d0`'s
-    /// exact rounding is undiffed; nearest is the Windows-edit convention). Empty table (host
-    /// hasn't answered yet) → end of text.
+    /// The display index nearest pixel `x` from the text origin, the caller adding the scroll
+    /// offset. It rounds to the nearest stop; `0x77d0d0`'s rounding is untraced.
     pub fn index_at_x(&self, x: f32) -> usize {
         let display = self.display();
         self.index_at_x_in(x, 0, display.len(), &display)
     }
 
-    /// [`Self::index_at_x`] restricted to the boundary range `[start, end]` of `display` —
-    /// the per-row walk of the 2-D law ([`Self::index_at_pos`]). `x` is measured from
-    /// `advances[start]`.
-    ///
-    /// The candidates are the **reachable cursor stops**, not every char boundary: the client's
-    /// hit-test converts its glyph index through the same token walk everything else uses, with
-    /// `atomicLinks = 0` (`0x77d0d0`, `6a 00` @`0x77d2f6`), so a click stops on each visible
-    /// character of a link's text but can never land inside an escape (decision 1077).
+    /// [`Self::index_at_x`] within `[start, end]`, `x` measured from `advances[start]`. It lands
+    /// only on cursor stops: the hit-test walks tokens with `atomicLinks = 0` (`0x77d0d0`, at
+    /// `0x77d2f6`), so a click reaches each visible character of a link but never an escape.
     fn index_at_x_in(&self, x: f32, start: usize, end: usize, display: &str) -> usize {
         if self.advances.len() != display.len() + 1 {
             return end;
@@ -444,7 +277,7 @@ impl EditBoxState {
         let mut prev = start;
         for b in self.stops_in(start, end, display) {
             if self.advances[b] - origin >= x {
-                // x lies between boundaries `prev` and `b` — pick the nearer.
+                // x lies between stops `prev` and `b`: pick the nearer.
                 return if x - (self.advances[prev] - origin) <= (self.advances[b] - origin) - x {
                     prev
                 } else {
@@ -456,8 +289,8 @@ impl EditBoxState {
         end
     }
 
-    /// The cursor stops strictly inside `(start, end]` of `display`, in order — the mouse-path walk
-    /// of [`crate::markup::ClassMap::advance`] (`atomic_links = false`). Always ends at `end`.
+    /// The cursor stops in `(start, end]`, in order, walked with links not atomic (the mouse walk);
+    /// always ends at `end`.
     fn stops_in(&self, start: usize, end: usize, display: &str) -> Vec<usize> {
         let map = crate::markup::ClassMap::new(display);
         let mut stops = Vec::new();
@@ -476,9 +309,7 @@ impl EditBoxState {
         stops
     }
 
-    /// The wrapped row index containing DISPLAY byte `b` — the last row whose start is ≤ `b`
-    /// (a byte exactly on a wrap boundary belongs to the row it *starts*, so the caret lands at
-    /// the head of the new row, where typing continues).
+    /// The wrapped row holding display byte `b`; a byte on a wrap boundary heads the new row.
     pub fn row_of(&self, b: usize) -> usize {
         match self.rows.binary_search(&b) {
             Ok(i) => i,
@@ -486,17 +317,14 @@ impl EditBoxState {
         }
     }
 
-    /// Row `i`'s DISPLAY byte range `[start, end)` — `end` is the next row's start (the swallowed
-    /// break bytes live at the tail of this range), or the display length for the last row.
+    /// Row `i`'s display byte range, with the break bytes it swallowed at its tail.
     pub fn row_range(&self, i: usize, display_len: usize) -> (usize, usize) {
         let start = self.rows.get(i).copied().unwrap_or(0);
         let end = self.rows.get(i + 1).copied().unwrap_or(display_len);
         (start, end.max(start))
     }
 
-    /// The caret's wrapped position: `(row, x)` with `x` the advance from the row's start —
-    /// the 2-D twin of the single-line `advances[cursor]` read. Row 0 / x 0 until the host has
-    /// answered the advance table.
+    /// The caret's wrapped `(row, x)`, `x` measured from the row's start.
     pub fn caret_row_x(&self, cursor_d: usize) -> (usize, f32) {
         let display = self.display();
         if self.advances.len() != display.len() + 1 {
@@ -508,12 +336,8 @@ impl EditBoxState {
         (row, self.advances[cursor_d] - self.advances[start])
     }
 
-    /// The char-boundary DISPLAY index nearest point `(x, y)` — the multiline click law
-    /// (`0x77d0d0`'s 2-D half): `y` (px down from the text region's top) picks the row by the
-    /// answered pitch, `x` walks that row's advances. Degrades to the 1-D walk while the rows/
-    /// pitch are unanswered (single-line boxes stay exactly the old behavior). The row's END
-    /// boundary excludes trailing break bytes only in x (clicking past a wrapped row's ink lands
-    /// at the wrap point).
+    /// The display index nearest `(x, y)` (`0x77d0d0`): `y`, down from the text top, picks the row
+    /// by the pitch and `x` walks that row. Without rows it is [`Self::index_at_x`].
     pub fn index_at_pos(&self, x: f32, y: f32) -> usize {
         let display = self.display();
         if self.rows.len() <= 1 || self.cell_h <= 0.0 {
@@ -530,9 +354,8 @@ impl EditBoxState {
         )
     }
 
-    /// The word-jump target from the cursor (Ctrl+arrow — the client walks its per-byte class
-    /// array `E+0x330`; benilla approximates the classes with alphanumeric runs, INFERRED):
-    /// forward = end of the current/next alnum run; back = start of the current/previous one.
+    /// The Ctrl+arrow target. A word here is a run of ASCII alphanumerics or non-ASCII bytes; the
+    /// reference walks its per-byte class array (`E+0x330`).
     pub fn word_boundary(&self, forward: bool) -> usize {
         let bytes = self.text.as_bytes();
         let is_word = |b: u8| b.is_ascii_alphanumeric() || b >= 0x80;
@@ -557,21 +380,16 @@ impl EditBoxState {
         }
     }
 
-    /// Show the caret and restart its blink cycle — the client's dirty flush resets the blink on
-    /// every cursor/text/selection change (and the click path calls it before placing the cursor).
+    /// Show the caret and restart its blink, as the client's dirty flush does on every change.
     pub fn reset_blink(&mut self) {
         self.caret_shown = true;
         self.blink_accum = 0.0;
     }
 
-    /// Clamp the scroll window (`E+0x348`, a DISPLAY-byte start index) so the caret stays inside
-    /// `avail` pixels: window start ≤ cursor, and the cursor's advance fits within the window's
-    /// width. Whole-char steps (the client scrolls its display window by characters, never
-    /// sub-pixel). No-op until the host has answered the advance table.
+    /// Scroll the single-line window (`E+0x348`) by whole chars to keep the caret in `avail` px.
     pub fn clamp_scroll(&mut self, avail: f32) {
         if self.multi_line {
-            // A multiline box wraps instead of windowing (the client's h-scroll `E+0x348` is the
-            // single-line mechanism; multiline scrolls via its parent ScrollFrame).
+            // A multiline box wraps; its parent ScrollFrame scrolls it.
             self.scroll_start = 0;
             return;
         }
@@ -580,7 +398,7 @@ impl EditBoxState {
             return;
         }
         let cursor_d = self.text_to_display(self.cursor);
-        // Snap a stale start (text shrank / mid-char) back onto a boundary.
+        // Snap a stale start back onto a char boundary.
         self.scroll_start = self.scroll_start.min(display.len());
         while self.scroll_start > 0 && !display.is_char_boundary(self.scroll_start) {
             self.scroll_start -= 1;
@@ -604,30 +422,23 @@ impl EditBoxState {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────
-// The editing law (RF-0082 §3/§4) — pure over the state, no Lua, no widget tree
+// The editing law: pure over the state, no Lua, no widget tree
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 //
-// These used to live in `script::editbox` welded to the Lua layer, which meant the *only* way to
-// get the byte-verified box law was to be a FrameXML EditBox. The glue screens (login, character
-// create, the delete dialog) therefore each grew their own three-case imitation of it — append a
-// char, Backspace, Tab — with no caret movement, no selection, and no clipboard (decision 0704).
-// The law lives here now, and `script::editbox` is a thin wrapper that calls these and fires the
-// Lua events an [`EditOutcome`] tells it to. Anything with a `&mut EditBoxState` gets the real
-// law, whether or not there is a Lua VM anywhere near it.
+// `script::editbox` wraps these and fires the Lua events an `EditOutcome` names; the glue
+// screens use them with no Lua at all.
 
-/// What a pure edit changed, so a caller with events to fire knows which to fire. The FrameXML
-/// wrapper turns this into `OnTextChanged`/`OnSpacePressed`; the glue screens ignore it.
+/// What an edit changed, for the FrameXML wrapper's `OnTextChanged` and `OnSpacePressed` fires.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct EditOutcome {
-    /// The text buffer changed — the `OnTextChanged` trigger.
+    /// The text changed: `OnTextChanged`.
     pub text_changed: bool,
-    /// Spaces this edit inserted — the `OnSpacePressed` fire count. Only an insert of typed text
-    /// reports these; a paste deliberately does not (a paste is not a typed space).
+    /// Typed spaces inserted, one `OnSpacePressed` each; a paste reports none.
     pub spaces: usize,
 }
 
 impl EditOutcome {
-    /// A change that fires `OnTextChanged` and nothing else.
+    /// An outcome with no typed spaces.
     fn changed(text_changed: bool) -> Self {
         EditOutcome {
             text_changed,
@@ -637,17 +448,13 @@ impl EditOutcome {
 }
 
 impl EditBoxState {
-    /// Apply one semantic [`EditAction`] — the single entry point the host's per-OS chord table
-    /// feeds (decision 0301: the host owns *which chord*, this owns *what it does*).
+    /// Apply one [`EditAction`] from the host's per-OS chord table.
     pub fn apply(&mut self, action: EditAction) -> EditOutcome {
         match action {
             EditAction::Move { unit, back, extend } => {
                 match unit {
-                    // No flag test here any more. The alt-arrow gate is on the KEY, not on the
-                    // action — with the flag set the box never sees the arrow at all, because the
-                    // host declines it before the chord is dispatched (`UiScript::
-                    // editbox_alt_arrow_fallthrough`). Anything that reaches this far was either
-                    // Alt-held or not an arrow, and both move the caret normally.
+                    // The alt-arrow gate is on the key: the host declines a gated arrow before
+                    // it becomes an action (`UiScript::editbox_alt_arrow_mode`).
                     EditUnit::Char => self.move_by_char(!back, extend),
                     EditUnit::Word => self.move_by_word(!back, extend),
                     EditUnit::Edge => self.move_to_edge(!back, extend),
@@ -669,27 +476,23 @@ impl EditBoxState {
                 self.highlight_text(0, -1);
                 EditOutcome::default()
             }
-            // History recall is the caller's: it routes through the SetText path so the FrameXML
-            // box also fires `OnTextSet`. `history_step` is the state half.
+            // The caller recalls history through `SetText`, so `OnTextSet` fires.
             EditAction::HistoryPrev | EditAction::HistoryNext => EditOutcome::default(),
         }
     }
 
-    /// Insert `ins` at the cursor (`0x77bee0`): replace any selection first; `numeric` aborts the
-    /// insert **wholesale** on any non-digit (not per-char filtering — RF-0082 §3); splice, advance
-    /// the caret, enforce the caps.
+    /// Insert at the cursor (`0x77bee0`), replacing any selection; `numeric` refuses the whole
+    /// insert on any non-digit (`0x77bf41`).
     pub fn insert(&mut self, ins: &str) -> EditOutcome {
         if self.numeric && !ins.chars().all(|c| c.is_ascii_digit()) {
             return EditOutcome::default();
         }
-        // Refused outright with the caret strictly inside a hyperlink — the opening guard of
-        // `0x77bee0` (decision 1077). Only the mouse can put the caret there (the keyboard treats a
-        // link as one unit), and the client then silently swallows the typing rather than letting
-        // it split `|Hitem:…|h[Name]|h` into something unclickable.
+        // Typing with the caret inside a hyperlink, where only the mouse can put it, is
+        // swallowed: the opening guard of `0x77bee0`.
         if !crate::markup::ClassMap::new(&self.text).insert_allowed(self.cursor) {
             return EditOutcome::default();
         }
-        self.end_history_browse(); // a typed edit turns a recalled line into an ordinary draft
+        self.end_history_browse();
         self.delete_selection();
         self.text.insert_str(self.cursor, ins);
         self.cursor += ins.len();
@@ -702,9 +505,8 @@ impl EditBoxState {
         }
     }
 
-    /// Insert OS-clipboard text: [`insert`](Self::insert) with the paste sanitation — every control
-    /// character is dropped, except `\n` into a multiline box. Reports no spaces: a paste is not a
-    /// typed space, so it fires no `OnSpacePressed`.
+    /// Insert clipboard text with its control characters dropped, bar `\n` in a multiline box; a
+    /// paste fires no `OnSpacePressed`.
     pub fn paste(&mut self, text: &str) -> EditOutcome {
         let cleaned: String = text
             .chars()
@@ -716,27 +518,16 @@ impl EditBoxState {
         EditOutcome::changed(self.insert(&cleaned).text_changed)
     }
 
-    /// `SetText` (`0x77be00`) is a clear-all followed by `Insert`, not a plain assignment, and the
-    /// order of its three parts is load-bearing (decision 1831):
-    ///
-    /// 1. the selection collapses **unconditionally**, before anything is compared — an identical
-    ///    `SetText` still drops a highlight;
-    /// 2. a case-sensitive equality test then short-circuits (`SStrCmp` at `0x77be4b`), skipping the
-    ///    clear-all, the insert and both fires — so the caller fires nothing;
-    /// 3. the changing leg is `0x77c500` (delete the whole buffer) then `0x77bee0` (`Insert`), which
-    ///    means `SetText` **inherits `Insert`'s gates**. The one that shows is `numeric`: the gate
-    ///    abandons the insert wholesale on any non-digit, and the clear-all has already run, so the
-    ///    box is left **empty** rather than unchanged. `SetNumber(-5)` and `SetNumber(0.8)` both
-    ///    empty a `numeric` box, because `-` and `.` are not digits.
-    ///
-    /// The clear-all raises the `textChanged` dirty bit on every path it reaches, so the aborted
-    /// insert still reports a change and still fires — reporting `""`.
+    /// `SetText` (`0x77be00`), in order: collapse the selection even when the text is equal; stop
+    /// if equal (`SStrCmp`, case-sensitive, `0x77be4b`), firing nothing; else clear all
+    /// (`0x77c500`), then `Insert` (`0x77bee0`) with its gates. So a `numeric` box given a
+    /// non-digit, as by `SetNumber(-5)`, ends empty and still reports a change.
     pub fn set_text(&mut self, s: &str) -> bool {
-        self.collapse(); // (1) unconditional, ahead of the comparison
+        self.collapse(); // even when the text is equal
         if self.text == s {
-            return false; // (2)
+            return false;
         }
-        // (3) the clear-all, then Insert — whose `numeric` gate refuses the whole string.
+        // Clear all, then Insert, whose `numeric` gate refuses the whole string.
         self.text = if self.numeric && !s.chars().all(|c| c.is_ascii_digit()) {
             String::new()
         } else {
@@ -749,8 +540,7 @@ impl EditBoxState {
         true
     }
 
-    /// The selected substring, or `None` with no selection (Ctrl+C, `0x77e1d0`). A password box
-    /// yields its **mask run**, never the real text — the client copies a placeholder.
+    /// The selection for Ctrl+C (`0x77e1d0`); a password box yields its mask, never the text.
     pub fn selected_text(&self) -> Option<String> {
         if self.sel_start == self.sel_end {
             return None;
@@ -775,9 +565,7 @@ impl EditBoxState {
         Some(taken)
     }
 
-    /// `HighlightText` (`0x77cca0`), the client's exact clamp: `start = clamp(start, 0..=len)`;
-    /// `end = (end < 0 || end > len) ? len : end`; then `if end < start { end = len }` — so
-    /// `(0, -1)` selects all. Byte offsets, snapped to char boundaries.
+    /// `HighlightText` (`0x77cca0`) with the client's clamp, so `(0, -1)` selects all.
     pub fn highlight_text(&mut self, start: i64, end: i64) {
         let len = self.text.len() as i64;
         let s = start.clamp(0, len);
@@ -791,8 +579,7 @@ impl EditBoxState {
         self.reset_blink();
     }
 
-    /// BACKSPACE / DELETE: the selection when there is one, else the char before (`forward=false`)
-    /// or after the caret. `true` when anything was removed.
+    /// Backspace (`forward = false`) or Delete: the selection if any, else one step.
     pub fn delete_dir(&mut self, forward: bool) -> bool {
         self.end_history_browse();
         let did = 'del: {
@@ -800,9 +587,8 @@ impl EditBoxState {
                 self.delete_selection();
                 break 'del true;
             }
-            // One ATOMIC token step, then the endpoint snap — `0x77c280(±1)` passes
-            // `atomicLinks = 1` (`6a 01` @`0x77c2a3`) and hands the span to `0x77c510`, so one
-            // BACKSPACE takes a whole item link, escapes and trailing `|r` included (1077).
+            // One atomic token step (`0x77c280`, `atomicLinks = 1` at `0x77c2a3`), then the span
+            // snap (`0x77c510`): one Backspace takes a whole item link, escapes and `|r` included.
             let target = crate::markup::ClassMap::new(&self.text).advance(
                 self.cursor,
                 if forward { 1 } else { -1 },
@@ -820,8 +606,7 @@ impl EditBoxState {
         did
     }
 
-    /// Word/edge delete: the selection first when one exists, else the span between the caret and
-    /// `target`. `true` when anything was removed.
+    /// Word or edge delete: the selection if any, else the span from the caret to `target`.
     pub fn delete_to(&mut self, target: usize) -> bool {
         self.end_history_browse();
         let did = if self.sel_start != self.sel_end {
@@ -842,13 +627,11 @@ impl EditBoxState {
         did
     }
 
-    /// LEFT/RIGHT one char: `extend` drags the selection from its fixed anchor; otherwise the caret
-    /// collapses onto the selection edge (when there is one) or steps one char.
+    /// Left or Right one step, `extend` dragging the selection; without it, a selection collapses
+    /// to its edge instead.
     pub fn move_by_char(&mut self, right: bool, extend: bool) {
-        // One TOKEN step, links atomic — `0x77bb30(±1, atomicLinks = 1)`, which every arrow path
-        // reaches (`6a 01` @`0x77c6d2`). So one press crosses a whole `|cff…|Hitem:…|h[Name]|h|r`
-        // rather than stepping into the middle of an escape, and Shift+arrow selects all of it
-        // (decision 1077). Not a char step: an escape byte is not a cursor position.
+        // One token step, links atomic (`0x77bb30`, `atomicLinks = 1` at `0x77c6d2`): a press
+        // crosses a whole link, never into an escape, and Shift+arrow selects all of it.
         let step = |s: &str, i: usize| {
             crate::markup::ClassMap::new(s).advance(i, if right { 1 } else { -1 }, true)
         };
@@ -866,10 +649,8 @@ impl EditBoxState {
         self.reset_blink();
     }
 
-    /// Ctrl/Option+arrow: the caret to the next [`word_boundary`](Self::word_boundary) — reached as
-    /// a **loop of single atomic steps** (`0x77c8c0`/`0x77c7a0` loop `0x77c6b0`), so the landing
-    /// place is always a reachable stop even when the word target falls inside an escape or
-    /// part-way through a link (decision 1077).
+    /// Ctrl/Option+arrow: the caret to the [`word_boundary`](Self::word_boundary) by single atomic
+    /// steps (`0x77c8c0`/`0x77c7a0` loop `0x77c6b0`), so it always lands on a reachable stop.
     pub fn move_by_word(&mut self, right: bool, extend: bool) {
         let word = self.word_boundary(right);
         let mut target = self.cursor;
@@ -896,8 +677,7 @@ impl EditBoxState {
         self.move_caret_to(target, extend);
     }
 
-    /// Place the caret at `target`, extending the selection from its fixed anchor when `extend`.
-    /// The shared tail of every non-char move (and of a mouse click/drag).
+    /// Place the caret at `target`, extending the selection from its anchor when `extend`.
     pub fn move_caret_to(&mut self, target: usize, extend: bool) {
         let target = snap_down(&self.text, target.min(self.text.len()));
         if extend {
@@ -911,7 +691,6 @@ impl EditBoxState {
         self.reset_blink();
     }
 
-    /// Delete the current selection: remove `[min, max)` and collapse the caret to its left edge.
     fn delete_selection(&mut self) {
         if self.sel_start == self.sel_end {
             return;
@@ -923,10 +702,8 @@ impl EditBoxState {
         self.delete_span(a..b);
     }
 
-    /// Remove a byte span, first widening it out of any hyperlink it cuts — `0x77c510` (decision
-    /// 1077), the second guarantee under the atomic walk: a mouse-drag selection that clips half an
-    /// item link still deletes the whole `|c…|H…|h[text]|h|r` unit rather than leaving orphaned
-    /// escape bytes. The caret collapses to the widened span's left edge.
+    /// Remove a byte span widened to whole hyperlinks (`0x77c510`), so a drag selection that clips
+    /// a link deletes all of it; the caret lands at the span's start.
     fn delete_span(&mut self, span: std::ops::Range<usize>) {
         let span = crate::markup::ClassMap::new(&self.text).snap_delete_range(span);
         self.cursor = span.start;
@@ -934,15 +711,14 @@ impl EditBoxState {
         self.collapse();
     }
 
-    /// Collapse the selection onto the caret — the client's own `0x77ccf0` (RF-0082 §4), which
-    /// every delete path runs and which a screen losing the keyboard runs on the box it is leaving.
+    /// Collapse the selection onto the caret (`0x77ccf0`), as every delete does and as a screen
+    /// losing the keyboard does to the box it leaves.
     pub fn collapse(&mut self) {
         self.sel_start = self.cursor;
         self.sel_end = self.cursor;
     }
 
-    /// The fixed end of the selection while extending — the endpoint that is *not* the caret (the
-    /// caret itself when nothing is selected).
+    /// The selection end that is not the caret.
     fn selection_anchor(&self) -> usize {
         if self.sel_start == self.cursor {
             self.sel_end
@@ -951,14 +727,12 @@ impl EditBoxState {
         }
     }
 
-    /// Set the selection to `[min(a,b), max(a,b)]`.
     fn set_span(&mut self, a: usize, b: usize) {
         self.sel_start = a.min(b);
         self.sel_end = a.max(b);
     }
 
-    /// Enforce the length caps after an edit (`0x77c02d`): trim whole chars from the end while over
-    /// `maxBytes`, then while over `maxLetters`; clamp caret/selection back into the buffer.
+    /// After an edit, trim from the end to `maxBytes`, then `maxLetters` (`0x77c02d`).
     fn enforce_caps(&mut self) {
         if let Some(mb) = self.max_bytes {
             while self.text.len() > mb {
@@ -966,15 +740,9 @@ impl EditBoxState {
             }
         }
         if self.max_letters > 0 {
-            // LETTERS, not chars: `0x77bc80` counts classes 2, 3 and 6 only, so a 48-byte item link
-            // costs 14 against `maxLetters` — its visible `[Chipped Claw]` and nothing more
-            // (decision 1077). Counting raw chars made a 255-letter chat line fill up three times
-            // too fast once it held links.
-            //
-            // The trim pops through `0x77c280(-1)` — the BACKSPACE primitive, `atomicLinks = 1` —
-            // re-counting the whole buffer after every pop (`0x77c0e4`). So an over-long buffer
-            // sheds a whole hyperlink in one bite, exactly as a keypress would, and can never shear
-            // an escape in half.
+            // Letters, not chars: `0x77bc80` counts classes 2, 3 and 6, so an item link costs only
+            // its visible name. The trim is the Backspace step (`0x77c280(-1)`, links atomic),
+            // re-counting after each pop (`0x77c0e4`), so it sheds a whole link at once.
             loop {
                 let map = crate::markup::ClassMap::new(&self.text);
                 if map.num_letters() <= self.max_letters {
@@ -994,7 +762,7 @@ impl EditBoxState {
     }
 }
 
-/// The byte offset of the char boundary at or below `i` (identity if `i` is already on one).
+/// The char boundary at or below `i`.
 fn snap_down(s: &str, i: usize) -> usize {
     let mut i = i.min(s.len());
     while i > 0 && !s.is_char_boundary(i) {
@@ -1024,7 +792,7 @@ mod row_law_tests {
     fn the_caret_seats_by_row_and_row_local_x() {
         let eb = two_row_box();
         assert_eq!(eb.caret_row_x(5), (0, 35.0));
-        // A cursor exactly on the wrap boundary heads the NEW row (typing continues there).
+        // A cursor on the wrap boundary heads the new row.
         assert_eq!(eb.caret_row_x(10), (1, 0.0));
         assert_eq!(eb.caret_row_x(15), (1, 35.0));
     }
@@ -1032,7 +800,7 @@ mod row_law_tests {
     #[test]
     fn a_click_picks_its_row_then_walks_it() {
         let eb = two_row_box();
-        // Row 1 (y past one pitch), x 21 → boundary 3 within the row → byte 13.
+        // Row 1 (y past one pitch), x 21: the row's third stop, byte 13.
         assert_eq!(eb.index_at_pos(21.0, 20.0), 13);
         // Above the block clamps to row 0; below clamps to the last row.
         assert_eq!(eb.index_at_pos(0.0, -5.0), 0);
diff --git a/crates/benilla-ui/src/widget/kinds/messageframe.rs b/crates/benilla-ui/src/widget/kinds/messageframe.rs
index cddaccf7..48a767c9 100644
--- a/crates/benilla-ui/src/widget/kinds/messageframe.rs
+++ b/crates/benilla-ui/src/widget/kinds/messageframe.rs
@@ -1,105 +1,60 @@
 use std::collections::VecDeque;
 
-/// One line held in a [`ScrollingMessageState`] ring — its text, its already-quantized color, its
-/// live fade state (a per-line snapshot of the frame's `timeVisible`/`fadeDuration` at insert,
-/// msgframe-runtime.md: MessageData `+0xc`/`+0x10`), and its host-measured wrapped row count (the
-/// message-line half of the measure round-trip — a long chat line occupies as many display rows as
-/// it wraps into, so the bands above it shift up by real content height).
+/// One message line: its text, quantized color, own fade countdowns (the record's `+0xc`/`+0x10`
+/// snapshots of `timeVisible`/`fadeDuration`) and host-measured row count.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MessageLine {
-    /// The line text (already formatted app-side: `[Name]: text`, `Name yells: text`, …).
+    /// The line as printed, already formatted by the caller.
     pub text: String,
-    /// The RGB the line draws at, **byte-quantized** at insert (`AddMessage` `trunc(x*255+0.5)`,
-    /// round-half-up; alpha is never stored — it is forced opaque and then driven by the fade).
+    /// The line's RGB, byte-quantized at insert ([`quantize_u8`]).
     pub color: [u8; 3],
-    /// `AddMessage`'s fifth argument — the chat-type index the line was printed under
-    /// (`GetChatTypeIndex`), so `UpdateColorByID` can find every line of a type when
-    /// `UPDATE_CHAT_COLOR` lands. 0 for a line printed without one.
+    /// `AddMessage`'s fifth argument, the chat-type id `UpdateColorByID` matches; 0 when absent.
     pub id: u32,
-    /// Remaining phase-1 countdown (the `timeVisible` snapshot ticking down); while `> 0` the line
-    /// holds full alpha.
+    /// Seconds left before the fade starts, from the `timeVisible` snapshot.
     pub time_left: f32,
-    /// Remaining phase-2 countdown (the `fadeDuration` snapshot). Once `time_left` hits `0` this
-    /// counts down and drives [`Self::alpha`].
+    /// Seconds of fade left, from the `fadeDuration` snapshot; counts once `time_left` is spent.
     pub fade_left: f32,
-    /// The current display alpha in `[0, 1]`. Phase 1 leaves it at whatever `AddMessage` set —
-    /// forced opaque on a ScrollingMessageFrame (`792add: or edi,0xffffff00`), the caller's real
-    /// alpha arg on a MessageFrame (`795752`, default 1.0) — and phase 2 **overwrites** it with the
-    /// byte-quantized ramp `trunc(remaining/fadeDuration*255)`, the client's own store into the
-    /// line's alpha byte (`0x788547` / `786364`→`[edi+0xb]`). `0` once fully faded — in a
-    /// ScrollingMessageFrame the line stays in the ring (a slot is freed only by drop-oldest /
-    /// `SetMaxLines`) and merely draws nothing, its rows still holding their place; a MessageFrame
-    /// has no ring, so its retire helper (`0x786570`) frees the line outright and the rest re-pack.
+    /// The display alpha: `AddMessage`'s (opaque on a ScrollingMessageFrame, `0x792add`; the alpha
+    /// argument on a MessageFrame, `0x795752`) until the fade overwrites it with the byte ramp
+    /// `trunc(remaining / fadeDuration * 255)` (`0x788547`, `0x786364`). At 0 a scrolling line
+    /// keeps its ring slot and rows; a MessageFrame frees it (`0x786570`).
     pub alpha: f32,
-    /// How many display rows the line wraps into at the frame's current width/font — host-measured
-    /// through the message-line measure round-trip
-    /// ([`crate::script::UiScript::message_lines_needing_measure`]). `1` until measured.
+    /// The rows the line wraps into at the frame's width and font, host-measured; 1 until then.
     pub rows: u16,
-    /// Cache key of the [`Self::rows`] measurement — hash of (text, font, height, wrap width),
-    /// computed engine-side. `0` = unmeasured (drawn as one row until the same-frame answer lands);
-    /// a width/font change mismatches the key and re-requests.
+    /// Hash of the text, font, height and wrap width `rows` was measured at; 0 is unmeasured.
     pub rows_key: u64,
 }
 
-/// A `CSimpleMessageScrollFrame`'s runtime state (msgframe-runtime.md, byte-verified §5 pair): a true
-/// ring of `max_lines` (drop-oldest, independent of how many display), each line carrying its own
-/// fade snapshot; a scrollback cursor counted **up from the bottom** (`0` = newest = AtBottom); and
-/// the frame-level fade config the per-line snapshots copy at insert.
+/// A `CSimpleMessageScrollFrame`'s runtime state (ctor `0x787670`): a drop-oldest ring of lines,
+/// a scrollback cursor counted up from the newest line, and the fade config new lines copy.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ScrollingMessageState {
-    /// The frame's OWN justification, set by `SetJustifyH`/`SetJustifyV` — `None` until one of
-    /// them is called.
-    ///
-    /// VERIFIED present on both classes: the ScrollingMessageFrame method table `0x87b5c0`
-    /// (the one whose `AddMessage` is `0x792900`, msgframe-runtime.md's scrolling family) carries
-    /// `SetJustifyH 0x792600`/`GetJustifyH`/`SetJustifyV`/`GetJustifyV`, and the MessageFrame table
-    /// `0x87b960` (`AddMessage 0x795590`, the `SetInsertMode` sibling) carries the same four. Read
-    /// off the `{const char*, void*}` pair bytes; the same walk reproduces the Button table at
-    /// `0x879d00` exactly as wow-re records it, and confirms Button has no `SetJustifyH` — which is
-    /// why the family cannot be inferred and had to be read.
-    ///
-    /// **`Option`, and the reason is ours not the client's.** The real object keeps ONE justify
-    /// dword: its font instance's. Ours reads a message frame's font instance off its first
-    /// `<FontString>` region (`message_frame_font`), which is where XML's
-    /// `<FontString … justifyH="LEFT"/>` lands — but a frame built by `CreateFrame` has no such
-    /// child and would have nowhere to store. So `None` means "never told, defer to the font
-    /// object" and keeps the shipped chat rendering byte-for-byte what it was; `Some` is an
-    /// explicit call and wins. The divergence that buys: on a frame that HAS a FontString, setting
-    /// the frame's justify does not change what that FontString's own `GetJustifyH` reports, where
-    /// the client would have them be one field.
+    /// The frame's own `SetJustifyH`/`SetJustifyV` (method table `0x87b5c0`), `None` until called
+    /// and then winning over the font's. Deviation: the reference has one field, the font's, but
+    /// our font is read off the first `<FontString>` region (`message_frame_font`), which a
+    /// `CreateFrame` frame lacks; so that FontString's own `GetJustifyH` does not see this.
     pub justify: Option<crate::justify::Justify>,
 
-    /// The line ring, newest at the back. Capacity is enforced by drop-oldest in [`Self::add`].
+    /// The line ring, newest at the back.
     pub lines: VecDeque<MessageLine>,
-    /// The ring capacity (`maxLines`; ctor default 8, ChatFrame.xml sets 128). `SetMaxLines` is
-    /// **destructive** (msgframe-runtime.md).
+    /// `maxLines`, the ring capacity (ctor 8); `SetMaxLines` clears the ring (`0x787dd0`).
     pub max_lines: usize,
-    /// `timeVisible`/`displayDuration` — phase-1 duration a new line holds full alpha (ctor 10.0s;
-    /// ChatFrame 120.0s).
+    /// `timeVisible`/`displayDuration`: seconds a new line holds full alpha (ctor 10).
     pub time_visible: f32,
-    /// `fadeDuration` — phase-2 fade ramp length (ctor 3.0s). `0` ⇒ the line vanishes instantly at
-    /// phase-1 expiry (no ramp).
+    /// `fadeDuration`: the fade's length in seconds (ctor 3); 0 hides the line at once.
     pub fade_duration: f32,
-    /// Bumped by every path that can change a line's TEXT set (add, clear, SetMaxLines, and the
-    /// generic mut door `KindState::message_lines_mut`) — the measure sweep's skip token
-    /// (`message_lines_needing_measure`): a frame whose generation and measure environment both
-    /// match its last clean sweep hashes no lines. Fade ticking deliberately does NOT bump (it
-    /// moves alpha/time, never text), or a fading chat line would keep the sweep hot for its
-    /// whole 2-minute ride.
+    /// Bumped by every change to the lines' text or colour, `KindState::message_lines_mut` too,
+    /// so the measure sweep skips an unchanged frame; the fade tick must not bump it.
     pub lines_gen: u64,
-    /// `fadingEnabled` (ctor 1). While false, lines never fade.
+    /// `fadingEnabled` (ctor 1).
     pub fading_enabled: bool,
-    /// The scrollback offset, counted up from the newest line: `0` = pinned to the bottom (AtBottom,
-    /// the only state in which fades tick — though every scroll entry re-arms the displayed lines
-    /// regardless, [`Self::reset_all_fade_times`]); `n` = the view is `n` lines older. Clamped in
-    /// [`Self::scroll_up`].
+    /// Lines scrolled back from the newest; 0 is AtBottom, the only state in which fades tick.
     pub scroll_offset: usize,
 }
 
 impl Default for ScrollingMessageState {
     fn default() -> ScrollingMessageState {
-        // The shared CSimpleMessageScrollFrame ctor defaults (msgframe-runtime.md §"Shared ctor
-        // defaults": fadingEnabled=1, timeVisible=10.0, fadeDuration=3.0; SMF maxLines=8).
+        // The ctor's defaults (`0x787670`).
         ScrollingMessageState {
             justify: None,
             lines: VecDeque::new(),
@@ -113,34 +68,15 @@ impl Default for ScrollingMessageState {
     }
 }
 
-/// Byte-quantize a `0..1` color/alpha component the way `AddMessage` does (`clamp[0,1]`, `*255`,
-/// `+0.5`, truncate — round-half-up; msgframe-runtime.md AddMessage `0x788150`).
+/// A `0..1` colour component as a byte, rounded half up as `AddMessage` does (`0x788150`).
 pub fn quantize_u8(x: f32) -> u8 {
     (x.clamp(0.0, 1.0) * 255.0 + 0.5).trunc() as u8
 }
 
 impl ScrollingMessageState {
-    /// `AddMessage(text, r, g, b)` (`0x788150`): quantize the color, snapshot the current
-    /// `timeVisible`/`fadeDuration` onto the new line, and push it at the ring's newest slot,
-    /// dropping the oldest when over `max_lines`. A view scrolled up stays anchored on the same
-    /// content (the ring cursor is a slot, not an offset — msgframe-runtime.md).
-    /// `ScrollingMessageFrame:UpdateColorByID(id, r, g, b)` (`0x7932b0` → `0x788250`) — every line
-    /// tagged `id` takes the new colour, quantised the way `AddMessage` quantised the old one.
-    /// Returns how many lines moved; a recolour bumps the generation so a settled frame redraws.
-    ///
-    /// **`id == 0` matches nothing, and that is a guard the reference opens with, not a
-    /// consequence** (decision 2125; wow-re `system/ui/scratch/login-chat-colour-pipeline.md`).
-    /// `0x788250` is `mov edi,[ebp+8]; test edi,edi; je 0x7882a4` → `ret 8`: zero never reaches a
-    /// comparison and the record walk is not entered at all.
-    ///
-    /// Without it this was a live repaint of every line ever printed with no explicit colour,
-    /// because `AddMessage`'s absent-id case stores an explicit literal `0` (`0x7929b7 xor edi,edi`
-    /// → `0x78821d mov [edi+0x14],ecx`) and `ChatTypeInfo["REPLY"].id` is 0 too — FrameXML declares
-    /// REPLY and the engine's 94-row registry does not carry it. So `ChatFrame_OnEvent`'s
-    /// `UPDATE_CHAT_COLOR` arm mirroring WHISPER into REPLY (`ChatFrame.lua` l.1357-1365) called
-    /// `UpdateColorByID(0, 1.0, 0.5, 1.0)` and turned every `AceConsole:Print` in the window
-    /// whisper-pink. Measured `(255,128,255)` on Bartender2's login line where the reference reads
-    /// `(255,255,255)`.
+    /// `UpdateColorByID(id, r, g, b)` (`0x7932b0`): recolour every line tagged `id`, returning how
+    /// many changed. `id == 0` matches nothing (the guard at `0x788250`): a line printed without
+    /// an id stores 0 (`0x7929b7`), and `ChatFrame.lua:1357` recolours REPLY, whose id is 0.
     pub fn update_color_by_id(&mut self, id: u32, r: f32, g: f32, b: f32) -> usize {
         if id == 0 {
             return 0;
@@ -163,8 +99,8 @@ impl ScrollingMessageState {
         self.add_with_id(text, r, g, b, 0);
     }
 
-    /// `AddMessage(text, r, g, b, id)` — the line, tagged with the chat-type index it was
-    /// printed under so a later `UpdateColorByID(id, …)` can recolour it.
+    /// `AddMessage(text, r, g, b, id)` (`0x792900`, `0x788150`): push the line and drop the oldest
+    /// past `max_lines`; a scrolled-up view stays on the same lines.
     pub fn add_with_id(&mut self, text: String, r: f32, g: f32, b: f32, id: u32) {
         self.lines_gen = self.lines_gen.wrapping_add(1);
         let line = MessageLine {
@@ -184,14 +120,13 @@ impl ScrollingMessageState {
         }
         while self.lines.len() > self.max_lines {
             self.lines.pop_front();
-            // The dropped line was above the view — walk the anchor back down with it.
+            // The dropped line was above the view: walk the anchor back down with it.
             self.scroll_offset = self.scroll_offset.saturating_sub(1);
         }
         self.clamp_scroll();
     }
 
-    /// `SetMaxLines(n)` — **destructive** (`0x787dd0`): frees every line + resets the cursor, then
-    /// sets the new capacity. Not a preserving resize.
+    /// `SetMaxLines(n)` (`0x787dd0`): free every line and reset the scroll, then set the capacity.
     pub fn set_max_lines(&mut self, n: usize) {
         self.lines_gen = self.lines_gen.wrapping_add(1);
         self.lines.clear();
@@ -206,8 +141,7 @@ impl ScrollingMessageState {
         self.scroll_offset = 0;
     }
 
-    /// Whether the view is pinned to the newest line (`AtBottom` — the only state in which fades
-    /// tick).
+    /// Whether the view is pinned to the newest line (`AtBottom`).
     pub fn at_bottom(&self) -> bool {
         self.scroll_offset == 0
     }
@@ -226,24 +160,9 @@ impl ScrollingMessageState {
         self.scroll_offset = self.scroll_offset.min(self.max_scroll());
     }
 
-    /// **Re-arm the displayed lines' fade** — the engine's `0x788b80`, which every scroll entry
-    /// reaches (see the scroll methods below). Per displayed line it writes the quartet
-    /// `alpha = 0xFF` (`0x788baf`), the in-use flag (`0x788bb3`), and the frame's *current*
-    /// `timeVisible`/`fadeDuration` **defaults** back onto the record's `+0xc`/`+0x10` snapshots
-    /// (`0x788bc0`/`0x788bc9`) — full values, never partial, and the frame default rather than
-    /// whatever the line was inserted with.
-    ///
-    /// Two properties that are easy to get wrong and are both byte-verified:
-    ///
-    /// - **The displayed set only, never the whole ring.** `0x788b80` walks `[+0x34c]` entries of
-    ///   the display vector `[+0x3a4]`, reaching each record through `node.+0xc`. A line scrolled
-    ///   out of view keeps whatever fade state it had.
-    /// - **A fully-faded line is recoverable.** Expiry (`0x788525`–`0x788538`) only clears the
-    ///   in-use flag, blanks the display object and hides it; `0x788460` contains no allocator call
-    ///   at all, so the record, its text and its wrapped height all survive and come straight back.
-    ///
-    /// Not a Lua binding: it is in no vtable and no data dword, and 1.12's FrameXML has no
-    /// `ResetAllFadeTimes` caller. It is engine behavior, reached only through the scroll entries.
+    /// Re-arm the fade of the displayed lines only (`0x788b80`): full alpha and the frame's
+    /// current `timeVisible`/`fadeDuration`, so even a fully faded line comes back (expiry frees
+    /// nothing, `0x788525`). Engine-only, not a 1.12 Lua verb; every scroll entry reaches it.
     pub fn reset_all_fade_times(&mut self, viewport_rows: usize) {
         let (time_visible, fade_duration) = (self.time_visible, self.fade_duration);
         for line in self.lines.range_mut(self.displayed_range(viewport_rows)) {
@@ -253,10 +172,7 @@ impl ScrollingMessageState {
         }
     }
 
-    /// The ring indices the view currently shows, oldest-first — the set
-    /// [`Self::reset_all_fade_times`] walks. The newest displayed line sits at the top end (it is
-    /// the bottom row on screen); the walk runs older from there for [`Self::displayed_count`]
-    /// messages.
+    /// The ring indices the view shows, oldest first.
     pub fn displayed_range(&self, viewport_rows: usize) -> std::ops::Range<usize> {
         let count = self.displayed_count(viewport_rows);
         if count == 0 {
@@ -268,54 +184,37 @@ impl ScrollingMessageState {
 
     // ── The scroll entries ──────────────────────────────────────────────────────────────────
     //
-    // **Every one of them re-arms the displayed lines' fade**, by one of two engine routes that
-    // between them leave no gap (wow-re `msgframe-fade-rearm-law.md`):
-    //
-    // - the cursor does NOT move (a scroll that is already at the boundary, or a no-op jump) — the
-    //   binding calls `0x788b80` directly: `ScrollUp` at AtTop (`0x788626`), `ScrollDown` at
-    //   AtBottom (`0x788666`), `ScrollToBottom` at AtBottom (`0x7886e5`);
-    // - the cursor DOES move — the relayout `0x788750` runs and its per-line helper `0x788af0`
-    //   (sole caller `0x7888be`) writes the same quartet under `arg3 != 0 || AtBottom == 0`, where
-    //   `arg3` is the relayout's own 0→1 AtBottom edge flag (`0x7887a3`). Land off the bottom and
-    //   the second term fires; land back ON the bottom and the edge flag does.
-    //
-    // So the re-arm is unconditional at this level and the two routes collapse into one call after
-    // the cursor has moved — which is also the right order, since the displayed set the engine
-    // walks is the one the new cursor selects. **Correction (2026-08-29):** benilla previously had
-    // scrolling merely *freeze* the countdown, on the strength of msgframe-runtime.md's "nothing
-    // un-fades" — that note described the tick's gate, not the scroll bindings, which had not been
-    // walked. Faded chat could never be brought back; the director reported it.
+    // Each re-arms the displayed lines' fade after moving the cursor. A scroll that cannot move
+    // calls `0x788b80` directly (`0x788626`, `0x788666`, `0x7886e5`); one that moves relayouts
+    // (`0x788750`), whose helper `0x788af0` re-arms on landing off the bottom or back onto it.
 
-    /// `ScrollUp` (`0x788610`) — one line older (no cursor move at the top), then re-arm.
+    /// `ScrollUp` (`0x788610`): one line older, then re-arm.
     pub fn scroll_up(&mut self, viewport_rows: usize) {
         self.scroll_offset = (self.scroll_offset + 1).min(self.max_scroll());
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// `ScrollDown` (`0x788650`) — one line newer (no cursor move at the bottom), then re-arm.
+    /// `ScrollDown` (`0x788650`): one line newer, then re-arm.
     pub fn scroll_down(&mut self, viewport_rows: usize) {
         self.scroll_offset = self.scroll_offset.saturating_sub(1);
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// `ScrollToBottom` (`0x7886d0`) — jump to the newest line, then re-arm.
+    /// `ScrollToBottom` (`0x7886d0`): to the newest line, then re-arm.
     pub fn scroll_to_bottom(&mut self, viewport_rows: usize) {
         self.scroll_offset = 0;
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// `ScrollToTop` (`0x788690`) — jump to the oldest line, then re-arm. This one never reaches
-    /// `0x788b80`; it re-arms because it always relayouts with AtBottom = 0.
+    /// `ScrollToTop` (`0x788690`): to the oldest line, then re-arm, as its relayout always lands
+    /// off the bottom.
     pub fn scroll_to_top(&mut self, viewport_rows: usize) {
         self.scroll_offset = self.max_scroll();
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// How many messages the view shows from the current anchor, given the viewport's row budget
-    /// (`floor(frame height / pitch)`): walk older from the anchor summing each message's wrapped
-    /// [`MessageLine::rows`] until the budget is spent. A partially-fitting message counts (it draws,
-    /// clipped), matching [`emit`](crate::script::UiScript::extract)'s band walk. At least 1 when
-    /// any line exists.
+    /// How many messages fit `viewport_rows` from the anchor, each costing its wrapped rows; a
+    /// partly fitting one counts, as in the draw's band walk (`emit_message_lines`).
     pub fn displayed_count(&self, viewport_rows: usize) -> usize {
         if self.lines.is_empty() || viewport_rows == 0 {
             return 0;
@@ -333,36 +232,24 @@ impl ScrollingMessageState {
         count.max(1)
     }
 
-    /// `PageUp` — the client pages by `numLinesDisplayed` scroll steps then one back
-    /// (msgframe-runtime.md: net page = displayed − 1, one line of overlap).
+    /// `PageUp` (`0x7885b0`): back by the displayed count less one, then re-arm.
     pub fn page_up(&mut self, viewport_rows: usize) {
         let page = self.displayed_count(viewport_rows).saturating_sub(1).max(1);
         self.scroll_offset = (self.scroll_offset + page).min(self.max_scroll());
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// `PageDown` — the same page size toward the newest line. Pages inherit both re-arm routes
-    /// from the `ScrollUp`/`ScrollDown` steps they are built out of.
+    /// `PageDown`: the same page toward the newest line, then re-arm.
     pub fn page_down(&mut self, viewport_rows: usize) {
         let page = self.displayed_count(viewport_rows).saturating_sub(1).max(1);
         self.scroll_offset = self.scroll_offset.saturating_sub(page);
         self.reset_all_fade_times(viewport_rows);
     }
 
-    /// Advance the fade by `dt` (the OnUpdate tick, `0x788460`). The entry gate is **AtBottom** and
-    /// `fading_enabled` — scrolled up, every line holds its current alpha and *this* function never
-    /// un-fades one. Un-fading is the scroll entries' job, through
-    /// [`Self::reset_all_fade_times`] — do not read the freeze below as "nothing ever comes back",
-    /// which is the reading that cost us the bug. Each
-    /// line runs phase 1 (`time_left` countdown at full alpha), then phase 2 (`fade_left` countdown,
-    /// alpha = `trunc(fade_left/fade_duration*255)`); `fade_duration == 0` snaps straight to 0.
-    ///
-    /// **Both countdowns are `fst`-without-pop** (`0x7884d7` phase 1, `0x788544` phase 2): memory
-    /// takes the `f32` rounding of `remaining − dt` while the x87 stack keeps the un-rounded value,
-    /// and it is the *un-rounded* one that the `fdiv`/`fmul 255.0`/`__ftol` ramp then consumes. So
-    /// the arithmetic runs wide and only the stored countdown narrows to `f32`. Phase 1's negative
-    /// overshoot is discarded — it stores exactly `0`, and phase 2 starts on the next tick with the
-    /// full fade rather than the remainder.
+    /// Advance the fade by `dt` (OnUpdate, `0x788460`), only at the bottom with fading on; the
+    /// scroll entries, not this, bring faded lines back. Both countdowns store `f32` while the
+    /// ramp reads the unrounded x87 value (`fst` without pop, `0x7884d7`, `0x788544`), and phase
+    /// 1's overshoot is dropped, so the fade starts whole on the next tick.
     pub fn tick(&mut self, dt: f32) {
         if !self.fading_enabled || !self.at_bottom() {
             return;
@@ -374,7 +261,7 @@ impl ScrollingMessageState {
                 continue;
             }
             if self.fade_duration <= 0.0 {
-                // No ramp — the line vanishes the instant phase 1 expires.
+                // No ramp: the line vanishes when phase 1 ends.
                 line.alpha = 0.0;
                 continue;
             }
@@ -384,9 +271,8 @@ impl ScrollingMessageState {
                 line.fade_left = 0.0;
                 line.alpha = 0.0;
             } else {
-                // Divisor is the LIVE frame fadeDuration (a mid-fade SetFadeDuration rescales the
-                // ramp), byte-quantized like the client — off the wide `remaining`, not the stored
-                // f32, per the `fst`-no-pop shape above.
+                // Over the live fadeDuration (a mid-fade change rescales the ramp), from the
+                // unrounded `remaining`, not the stored f32.
                 let byte = quantize_fade_wide(remaining / f64::from(self.fade_duration));
                 line.alpha = f32::from(byte) / 255.0;
             }
@@ -394,103 +280,57 @@ impl ScrollingMessageState {
     }
 }
 
-/// Phase-2 alpha quantization: `trunc(x*255)` (no `+0.5` — the fade tick truncates, `0x788547`).
+/// The fade's alpha byte, truncated with no `+0.5` (`0x788547`).
 fn quantize_fade(x: f32) -> u8 {
     (x.clamp(0.0, 1.0) * 255.0).trunc() as u8
 }
 
-/// [`quantize_fade`] off the x87 stack's un-rounded ratio — see [`ScrollingMessageState::tick`] on
-/// the `fst`-without-pop shape that makes the ramp wider than the countdown it stores.
+/// [`quantize_fade`] of the unrounded ratio (see [`ScrollingMessageState::tick`]).
 fn quantize_fade_wide(x: f64) -> u8 {
     (x.clamp(0.0, 1.0) * 255.0).trunc() as u8
 }
 
-/// Where a [`MessageFrameState`]'s newest message enters the display stack — the `insertMode` XML
-/// attribute (`0x87a618`) and the `SetInsertMode`/`GetInsertMode` pair (`0x794ed0`/`0x794ff0`).
-///
-/// **MessageFrame only**, which is why it lives here and not on [`ScrollingMessageState`]: the
-/// scrolling class has neither binding and no such XML attribute (msgframe-runtime.md's
-/// binding-family table; wow-re `widget-api-batch-benilla.md` Q4, byte-verified).
+/// Where a MessageFrame's newest message enters: XML `insertMode` (`0x87a618`) and
+/// `SetInsertMode`/`GetInsertMode` (`0x794ed0`/`0x794ff0`); the scrolling class has neither.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum InsertMode {
-    /// `"TOP"` (the client's `0`): the newest message takes the frame's **top** line and older ones
-    /// step down. The reference's own `UIErrorsFrame.xml:4` asks for this, and so does every corpus
-    /// caller of `SetInsertMode` (`BigWigs/Plugins/Messages.lua:209`).
+    /// `"TOP"` (0): newest on the top line, older stepping down, as `UIErrorsFrame.xml:4` asks.
     Top,
-    /// `"BOTTOM"` (the client's `1`, and the **ctor default**): newest at the bottom, older stepping
-    /// up — the chat shape.
+    /// `"BOTTOM"` (1, the ctor default): newest on the bottom line, older stepping up.
     #[default]
     Bottom,
 }
 
-/// A `CSimpleMessageFrame`'s runtime state (ctor `0x785640`; msgframe-runtime.md, byte-verified §5
-/// pair) — the class `UIErrorsFrame` is, and [`ScrollingMessageState`]'s **sibling, never its
-/// base**. The two come from different ctors and their `AddMessage` bindings are different
-/// functions with different tails, so nothing is shared here beyond the line record itself:
+/// A `CSimpleMessageFrame`'s runtime state (ctor `0x785640`), the class of `UIErrorsFrame` and a
+/// sibling of [`ScrollingMessageState`]: no ring, no `maxLines` (the cap is what fits), no
+/// scrollback, an `AddMessage` alpha in place of the id, and a faded line freed (`0x786570`).
 ///
-/// | | MessageFrame (this) | ScrollingMessageFrame |
-/// |---|---|---|
-/// | store | display lines only — no ring, **no `maxLines`**; the cap is what fits vertically | a true ring of `maxLines`, drop-oldest |
-/// | `AddMessage` tail | a real **alpha**, default 1.0 (`0x795590`) | an **id**; alpha forced `0xFF` (`0x792900`) |
-/// | scrollback | none at all | cursor + scroll/page set |
-/// | `SetInsertMode` | yes ([`InsertMode`]) | no binding, no attribute |
-/// | a fully-faded line | retired and the rest re-pack (`0x786570`) | keeps its ring slot and its rows |
-///
-/// The one recorded shape this does **not** model is the pending queue: the real class only
-/// *enqueues* in `AddMessage` and drains at OnUpdate, dropping the message outright if
-/// `numLinesDisplayed` is 0 at drain time (`786265`). Here a message lands in [`Self::lines`]
-/// immediately and [`Self::trim_to_viewport`] applies the vertical cap at the next tick — the same
-/// observable result one tick earlier, without a second buffer whose only visible consequence is
-/// that a message added to a zero-height frame vanishes.
+/// The reference queues `AddMessage` and drains it at OnUpdate, dropping a message while
+/// `numLinesDisplayed` is 0 (`0x786265`); here a line lands at once and
+/// [`Self::trim_to_viewport`] applies the cap.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MessageFrameState {
-    /// The frame's OWN justification, set by `SetJustifyH`/`SetJustifyV` — `None` until one of
-    /// them is called.
-    ///
-    /// VERIFIED present on both classes: the ScrollingMessageFrame method table `0x87b5c0`
-    /// (the one whose `AddMessage` is `0x792900`, msgframe-runtime.md's scrolling family) carries
-    /// `SetJustifyH 0x792600`/`GetJustifyH`/`SetJustifyV`/`GetJustifyV`, and the MessageFrame table
-    /// `0x87b960` (`AddMessage 0x795590`, the `SetInsertMode` sibling) carries the same four. Read
-    /// off the `{const char*, void*}` pair bytes; the same walk reproduces the Button table at
-    /// `0x879d00` exactly as wow-re records it, and confirms Button has no `SetJustifyH` — which is
-    /// why the family cannot be inferred and had to be read.
-    ///
-    /// **`Option`, and the reason is ours not the client's.** The real object keeps ONE justify
-    /// dword: its font instance's. Ours reads a message frame's font instance off its first
-    /// `<FontString>` region (`message_frame_font`), which is where XML's
-    /// `<FontString … justifyH="LEFT"/>` lands — but a frame built by `CreateFrame` has no such
-    /// child and would have nowhere to store. So `None` means "never told, defer to the font
-    /// object" and keeps the shipped chat rendering byte-for-byte what it was; `Some` is an
-    /// explicit call and wins. The divergence that buys: on a frame that HAS a FontString, setting
-    /// the frame's justify does not change what that FontString's own `GetJustifyH` reports, where
-    /// the client would have them be one field.
+    /// The frame's own `SetJustifyH`/`SetJustifyV` (method table `0x87b960`), `None` until called.
+    /// Deviation: kept apart from the font's, as [`ScrollingMessageState::justify`] is.
     pub justify: Option<crate::justify::Justify>,
 
-    /// See [`ScrollingMessageState::lines_gen`] — the same sweep-skip token.
+    /// The measure sweep's skip token, as [`ScrollingMessageState::lines_gen`].
     pub lines_gen: u64,
-    /// The display lines, **newest at the back always** — [`InsertMode`] is a *display direction*
-    /// resolved at emit, not a storage order, so "evict the oldest" is one `pop_front` in both
-    /// modes.
+    /// The lines, newest at the back in both insert modes: [`InsertMode`] only orders the draw.
     pub lines: VecDeque<MessageLine>,
-    /// `insertMode` — which end of the frame new messages enter from (ctor default BOTTOM).
+    /// `insertMode` (ctor BOTTOM).
     pub insert_mode: InsertMode,
-    /// `timeVisible`/`displayDuration` — phase-1 duration a new line holds its insert alpha (ctor
-    /// 10.0s; `UIErrorsFrame.xml` sets 5).
+    /// `timeVisible`/`displayDuration`: seconds a new line holds its insert alpha (ctor 10).
     pub time_visible: f32,
-    /// `fadeDuration` — phase-2 ramp length (ctor 3.0s). `0` ⇒ the line vanishes at phase-1 expiry
-    /// with no ramp.
+    /// `fadeDuration`: the fade's length in seconds (ctor 3); 0 hides the line at once.
     pub fade_duration: f32,
-    /// `fadingEnabled` (ctor 1). While false nothing fades — and, because retirement is what bounds
-    /// this list, nothing retires either; the vertical cap is then the only bound (which is exactly
-    /// the client's own arrangement).
+    /// `fadingEnabled` (ctor 1); while false only the vertical cap bounds the lines.
     pub fading_enabled: bool,
 }
 
 impl Default for MessageFrameState {
     fn default() -> MessageFrameState {
-        // The CSimpleMessageFrame ctor defaults (msgframe-runtime.md §"Shared ctor defaults":
-        // fadingEnabled=1, timeVisible=10.0, fadeDuration=3.0; insertMode 1 = BOTTOM). Note the
-        // fade pair is shared with the scrolling class but `maxLines` has no counterpart here.
+        // The ctor's defaults (`0x785640`).
         MessageFrameState {
             justify: None,
             lines: VecDeque::new(),
@@ -504,10 +344,8 @@ impl Default for MessageFrameState {
 }
 
 impl MessageFrameState {
-    /// `AddMessage(text, r, g, b, a)` (`0x795590` → `0x785d00`): quantize the colour the same
-    /// round-half-up way the scrolling class does, take the **alpha argument** as the line's
-    /// starting alpha (this class's fourth numeric really is alpha — the scrolling one's is an id
-    /// and forces `0xFF`), snapshot the frame's fade config, and append.
+    /// `AddMessage(text, r, g, b, a)` (`0x795590`, `0x785d00`): the fourth number is the line's
+    /// starting alpha, where the scrolling class takes an id and forces opaque.
     pub fn add(&mut self, text: String, r: f32, g: f32, b: f32, a: f32) {
         self.lines_gen = self.lines_gen.wrapping_add(1);
         self.lines.push_back(MessageLine {
@@ -516,35 +354,23 @@ impl MessageFrameState {
             color: [quantize_u8(r), quantize_u8(g), quantize_u8(b)],
             time_left: self.time_visible,
             fade_left: self.fade_duration,
-            // Quantized like the colour: the client packs all four channels into one 0xAARRGGBB
-            // dword through the same `ftol(v*255 + 0.5)`.
+            // Quantized like the colour: all four channels pack into one ARGB dword.
             alpha: f32::from(quantize_u8(a)) / 255.0,
             rows: 1,
             rows_key: 0,
         });
     }
 
-    /// `Clear` — retire every line immediately, no fade. (`_LazyPig` calls `UIErrorsFrame:Clear()`
-    /// eleven times; it is the one non-`AddMessage` verb the corpus actually uses on this class.)
+    /// `Clear`: drop every line at once, no fade.
     pub fn clear(&mut self) {
         self.lines_gen = self.lines_gen.wrapping_add(1);
         self.lines.clear();
     }
 
-    /// Advance the fade by `dt` — the OnUpdate virtual `0x786200`, whose gate is
-    /// `activeCount != 0 && fadingEnabled != 0 && numLinesDisplayed > 0`. **No scroll gate**: this
-    /// class has no scrollback, so unlike [`ScrollingMessageState::tick`] nothing can freeze it.
-    ///
-    /// Two phases per line, identical formula to the scrolling class: `time_left` counts down at the
-    /// insert alpha, then `fade_left` counts down and *overwrites* the alpha with
-    /// `trunc(fade_left/fade_duration*255)` against the **live** frame `fade_duration`. A finished
-    /// line is then **freed** rather than left in place — this class has no ring to hold a slot, so
-    /// the survivors re-pack (`0x786570`, the retire helper that decrements the active count).
-    ///
-    /// Deliberately still narrow arithmetic: the `fst`-without-pop shape is byte-cited for the
-    /// *scrolling* class's tick (`0x7884d7`/`0x788544`), and `0x786200` has not been walked for it.
-    /// Copying the wide form across on the strength of "same formula" would be the scope error
-    /// decision 1692 is about, one class over.
+    /// Advance the fade by `dt` (OnUpdate, `0x786200`) in the scrolling class's two phases, with no
+    /// scroll gate, freeing a finished line (`0x786570`). The reference also gates on
+    /// `numLinesDisplayed > 0`, which this does not check. The arithmetic is `f32`: whether
+    /// `0x786200` keeps the unrounded x87 value like the scrolling tick is untraced.
     pub fn tick(&mut self, dt: f32) {
         if !self.fading_enabled {
             return;
@@ -566,19 +392,13 @@ impl MessageFrameState {
                 line.alpha = f32::from(quantize_fade(line.fade_left / self.fade_duration)) / 255.0;
             }
         }
-        // Retired lines are gone, not blank: `alpha == 0` past phase 1 is the finished state.
+        // A line past phase 1 at alpha 0 is finished, and freed.
         self.lines.retain(|l| l.time_left > 0.0 || l.alpha > 0.0);
     }
 
-    /// Evict the oldest lines until only what fits in `viewport_rows` display rows remains — this
-    /// class's whole capacity law ("no `maxLines` anywhere on this class — the cap is what fits
-    /// vertically"), with each line costing its host-measured wrapped [`MessageLine::rows`].
-    ///
-    /// `viewport_rows == 0` means the frame has no resolved rect yet (or a degenerate one) and is
-    /// left alone rather than emptied: dropping there would lose a message posted from an `OnLoad`
-    /// before the first solve, which is a v1 ordering artefact and not the client's zero-height
-    /// case. The fade is what bounds the list in that window — and with `fading_enabled` false it
-    /// is unbounded until the frame resolves, which is stated rather than papered over.
+    /// Evict the oldest lines until the rest fit `viewport_rows`, each costing its wrapped rows.
+    /// Zero rows means no rect yet and evicts nothing, so a message posted from `OnLoad` before
+    /// the first layout survives; until then only the fade bounds the list.
     pub fn trim_to_viewport(&mut self, viewport_rows: usize) {
         if viewport_rows == 0 {
             return;
diff --git a/crates/benilla-ui/src/widget/kinds/mod.rs b/crates/benilla-ui/src/widget/kinds/mod.rs
index 823e3837..f94deefd 100644
--- a/crates/benilla-ui/src/widget/kinds/mod.rs
+++ b/crates/benilla-ui/src/widget/kinds/mod.rs
@@ -1,7 +1,4 @@
-//! The widget-kind vocabulary + per-kind state (the "later layer" over the frame arena): the
-//! 13 client widget classes ([`FrameKind`]), the two region leaves ([`RegionKind`]), and the
-//! modeled per-kind behavior ([`KindState`]) that a `CSimple*` subtype adds over `CSimpleFrame`
-//! (RF-28 tables; decision 0068). Split from the arena so each grows independently.
+//! Widget kinds: [`FrameKind`], [`RegionKind`] and the per-kind state, [`KindState`].
 
 use std::collections::{HashSet, VecDeque};
 
@@ -12,55 +9,17 @@ mod messageframe;
 pub use editbox::*;
 pub use messageframe::*;
 
-/// The widget subtype of a [`Frame`]. Each corresponds to a client `CSimple*` class
-/// (`frame-model.md`, the 13 widget factories, decision 0068). Kinds with modeled behavior carry it
-/// in [`Frame::kind_state`] (StatusBar today); the rest are tags whose per-kind behavior (button
-/// states, editbox text, …) is a later layer over this arena.
+/// A [`Frame`]'s widget class; one with modeled behavior carries it in [`Frame::kind_state`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum FrameKind {
-    /// Plain `CSimpleFrame` — the base container.
+    /// Plain `CSimpleFrame`, the base container.
     Frame,
-    /// The reference's `CGWorldFrame` (decisions 1983/1984; wow-re `worldframe-widget.md`): the
-    /// singleton the 3D world renders behind. Registered as its own frame type (`"WorldFrame"`
-    /// @`0x843450`, factory `0x4959d0`) whose registry record is **destroyed on the first
-    /// instantiation** — a second `<WorldFrame>` or `CreateFrame("WorldFrame")` is an unknown type;
-    /// **a `Frame` to Lua** (`GetObjectType()` answers `"Frame"`, `IsObjectType("WorldFrame")` is
-    /// nil — its vtable inherits the base's type slots, the TaxiRouteFrame precedent); born with
-    /// key, mouse and wheel enabled (`0xE`) in **stratum 0, `WORLD`, below `BACKGROUND`**, which
-    /// no XML or Lua can name. benilla draws the world through Bevy, so the kind is a full-screen
-    /// frame whose hits are the WORLD's: the app's pointer arbiter treats a hovered WorldFrame as
-    /// not-over-UI while its own scripts still fire, as the reference's do before the click's
-    /// binding runs.
+    /// `CGWorldFrame` (factory `0x4959d0`), the singleton the world renders behind: a `Frame` to
+    /// Lua, in stratum `WORLD` below `BACKGROUND`; hovered, it is not over the UI but runs scripts.
     WorldFrame,
     Button,
-    /// `CLootButton` (`Ui\\LootFrame.h:21`, factory `0x495a30`, size `0x4e0`) — a
-    /// **registered `CreateFrame` type**, one of the eight the client registers through
-    /// `0x495940` (pair `("LootButton" @0x843414, 0x495a30)` at site `0x4959a6`), and the reason
-    /// the stock `LootFrame.xml` cannot load against a plain `<Button>`.
-    ///
-    /// It is a `CSimpleButton` **plus one dword and one overridden virtual**, and that is the
-    /// whole class. The dword at `+0x4dc` is the 0-based loot slot; the virtual is primary slot 37
-    /// `OnClick 0x4c1820`. Everything else it overrides (slots 0, 2, 4, 6, 7 and the secondary
-    /// adjustor thunk) is compiler-mandated identity and lifetime plumbing. A binary-wide census
-    /// of `+0x4dc` finds exactly three sites in its code: the ctor's zero, `SetSlot`'s write, and
-    /// `OnClick`'s read.
-    ///
-    /// **What it does NOT have**, each proven by the vtable dwords being *identical* to
-    /// `CSimpleButton`'s: no C-side `OnEnter`/`OnLeave` (slots 19/20), so the hover tooltip is
-    /// purely the FrameXML `<OnEnter>`; no drag (29/30/31); no `OnLoad`/`OnShow`/`OnHide`/
-    /// `OnUpdate` (9/12/13/14). And no button-code test anywhere in its 79-byte click body — it
-    /// reads `[ebp+8]` once and immediately forwards it — so **right-click loots exactly like
-    /// left-click**, and with no `<OnDoubleClick>` a fast double-click takes two slots.
-    ///
-    /// The click, in order (`0x4c1820`): a scripted click returns immediately and does **nothing,
-    /// not even run the Lua `<OnClick>`** (`0x4c182b`); otherwise the base fires the Lua handler
-    /// unconditionally, and then — only with **no shift, ctrl or alt** held — the take runs. That
-    /// gate is what keeps the C take and `LootFrameItem_OnClick`'s ctrl/shift arms from firing
-    /// together, and it is why the shipped Lua handler deliberately never calls a take itself.
-    ///
-    /// Its whole Lua surface of its own is **one method, `SetSlot(index)`** (table `0x847ce4`,
-    /// count 1 read off the registrar's own `mov edx,1`) — 1-based in, 0-based stored, no returns.
-    /// `LootFrame.lua:94` is its only caller. Decision 1799; wow-re `e5338caf`.
+    /// `CLootButton` (factory `0x495a30`): a `CSimpleButton` plus a loot slot and an `OnClick`
+    /// (`0x4c1820`) that takes it; a registered `CreateFrame` type the stock `LootFrame.xml` needs.
     LootButton,
     CheckButton,
     EditBox,
@@ -68,161 +27,73 @@ pub enum FrameKind {
     Slider,
     ScrollFrame,
     Model,
-    /// `CGCharacterModelBase` (`0x505680`, size `0x3f8`) — the **unit-showing** model pane, and a
-    /// registered `CreateFrame` type in its own right: pair `("PlayerModel" @0x84343c, factory
-    /// 0x495bd0)` at registration site `0x49597f`, one of the eight the game client registers
-    /// through `0x495940` (wow-re `ui/scratch/model-pane-method-tables.md` §1).
-    ///
-    /// **It extends [`FrameKind::Model`] and adds exactly three verbs** — `SetUnit`, `RefreshUnit`,
-    /// `SetRotation` (table `0x84f1fc`, 3 entries). Its Lua surface is those three *plus* all 23 of
-    /// `Model`'s, and it gets them by **chaining, not repetition**: `CGCharacterModelBase`'s method
-    /// lookup `0x506260` probes its own 3-entry map and, on a miss, tail-calls `0x506290 call
-    /// 0x76f870` — `CSimpleModel`'s. Our `__index` already walks a *slice* of registry keys, so the
-    /// chain is `&[PLAYERMODEL, MODEL]` and nothing is duplicated.
-    ///
-    /// **The direction is derived → base only.** A plain `<Model>` does *not* acquire `SetUnit`/
-    /// `RefreshUnit`/`SetRotation`: nothing chains from `0x76f870` down into `0x506260`. benilla
-    /// published all three on `Model` until 2026-08-30 — a `strings WoW.exe` hit read as ownership,
-    /// which it cannot be (`SetUnit`'s pooled string `0x84f22c` is referenced by **two** table
-    /// entries, `PlayerModel 0x84f1fc` and `GameTooltip 0x854290`, and by no `Model` entry).
-    ///
-    /// Same posture as its base: the engine core holds the scene the Lua API reads and writes
-    /// ([`KindState::Model`], shared with [`FrameKind::Model`]); the pixels are the app renderer's.
-    /// `CGCharacterModelBase` adds `0x1c` bytes of members over `CSimpleModel` — the turn-animation
-    /// flag/expiry at `+0x3e8`/`+0x3ec` that `SetRotation` arms — and those are **not modeled**:
-    /// no getter reads them, and the app's `<Model>` renderer draws no shuffle animation.
-    /// `script::modelframe`'s `SetRotation` carries the addresses.
+    /// `CGCharacterModelBase` (`0x505680`, factory `0x495bd0`): `Model` plus `SetUnit`,
+    /// `RefreshUnit` and `SetRotation` (table `0x84f1fc`), which a plain `<Model>` lacks.
     PlayerModel,
-    /// `DressUpModel` — `CGDressUpModelFrame` (`Ui\DressUpModelFrame.cpp`, factory `0x495c00`,
-    /// ctor `0x5041d0` chaining `CGCharacterModelBase`'s `0x505680`): the dressing room's pane.
-    /// It EXTENDS [`FrameKind::PlayerModel`] — the same members, two behavioural vtable overrides
-    /// (idx36 `0x504350`: clone the unit's CharacterComponents and seed the two hand lanes; idx38
-    /// `0x504470`) — and adds exactly three verbs of its own, table `0x84f190`: `Undress 0x504c00`,
-    /// `Dress 0x504cd0`, `TryOn 0x504d90`. Everything else it answers is `PlayerModel`'s and then
-    /// `Model`'s, by the same chaining. Its state is [`KindState::Model`] like both of them; what a
-    /// try-on DOES lives app-side as an ordered intent queue (`script::dressup`), because the
-    /// substitution set is a look composed against the player's live equipment, which the VM
-    /// never holds (decisions 1060, 1969; wow-re `ui/scratch/dressup-model-equipment.md` §0).
+    /// `CGDressUpModelFrame` (factory `0x495c00`): `PlayerModel` plus `Undress`, `Dress` and
+    /// `TryOn` (table `0x84f190`); a try-on is composed app-side against live equipment.
     DressUpModel,
-    /// `TabardModel` (`0x503bd0`) — the guild tabard designer's pane: `CGCharacterModelBase`'s
-    /// other subclass (the dress-up model's sibling), with ten verbs of its own in table
-    /// `0x84ee40` — the emblem/colour cycling, the two emblem-texture setters, the save gate and
-    /// the save. Its state is [`KindState::Model`] like its siblings; the design it carries lives
-    /// app-side (`script::tabard`, decision 1977).
+    /// `TabardModel` (`0x503bd0`): `CGCharacterModelBase` plus ten verbs (table `0x84ee40`).
     TabardModel,
-    /// `CSimpleMessageFrame` — the non-scrolling message frame (`UIErrorsFrame`'s class, and the
-    /// one `CreateFrame("MessageFrame")` makes). Its behaviour (the display lines, the per-line
-    /// fade, `insertMode`) is modeled in [`KindState::Message`]. Sibling of
-    /// [`FrameKind::ScrollingMessageFrame`], not a base or a subset of it.
+    /// `CSimpleMessageFrame`, `UIErrorsFrame`'s class: a sibling of the scrolling one.
     MessageFrame,
-    /// `CSimpleMessageScrollFrame` — the scrolling, ring-buffered message frame (the chat window's
-    /// class). Its behavior (the line ring, per-line fade, wheel scrollback) is modeled in
-    /// [`KindState::ScrollingMessage`]. Sibling of [`FrameKind::MessageFrame`] (different C++ ctor),
-    /// not a subclass — offsets/semantics do not transfer (msgframe-runtime.md).
+    /// `CSimpleMessageScrollFrame`, the chat window's ring-buffered class; a sibling of
+    /// [`FrameKind::MessageFrame`] whose offsets do not transfer (bases `0x7a3540`/`0x769090`).
     ScrollingMessageFrame,
     ColorSelect,
     SimpleHtml,
     MovieFrame,
-    /// The `GameTooltip` widget family (decision 0274). Like [`FrameKind::Minimap`], a
-    /// *game-layer* factory over `CSimpleFrame`; its modeled behavior —
-    /// the line stack, owner/anchor law, auto-size, fade — lives in [`KindState::Tooltip`] and
-    /// `script::tooltip`. The real class's Lua surface is the 38-binding family wow-re pinned
-    /// (`ui/scratch/bindings.md` 0x530c40–0x5364a0); the line/color primitives are byte-diffed
-    /// (`luabind_530`), the content builders land per 0274's phases.
+    /// The `GameTooltip` family, a game-layer factory; its 38 bindings are `0x530c40`..`0x5364a0`.
     GameTooltip,
-    /// The `<Minimap>` widget (Minimap.xml's circular HUD map). Like [`FrameKind::GameTooltip`], a
-    /// *game-layer* factory, not one of the 13 base FrameXML types (`RegisterFrameFactories`
-    /// `0x495940` registers the game UI's own widget set at `CGGameUI::Initialize`; ui node). The
-    /// widget is a sized hole the game engine draws into — tiles, blips, and the player arrow are
-    /// the app renderer's job (decision 0203); the engine core carries only the rect and the zoom
-    /// state ([`KindState::Minimap`]).
+    /// The `<Minimap>` widget, a game-layer factory (`0x495940`) the app draws the map into.
     Minimap,
 }
 
-/// Whether a [`Region`] leaf is a texture or a text string. These are the client's two non-frame
-/// region types (`CScriptRegion`-derived leaves, `frame-model.md`).
+/// The kind of a [`Region`] leaf, the client's `CScriptRegion`-derived non-frame objects.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum RegionKind {
     /// A `Texture` (BLP quad).
     Texture,
     /// A `FontString` (text run).
     FontString,
-    /// A frame's **title region** — the drag handle `Frame:CreateTitleRegion()` makes.
-    ///
-    /// A third leaf rather than a texture that happens to draw nothing, because the difference is
-    /// OBSERVABLE: wow-re carves the object as a plain Region (`widget-api-batch-benilla.md` Q6,
-    /// `0x773910`) whose `GetObjectType()` answers `"Region"` and which exposes exactly the 19
-    /// Region methods — **no Show/Hide, no scripts, no textures**. A `Texture` in disguise would
-    /// answer `"Texture"` to any addon that asked, and would emit a quad.
+    /// A frame's title region, the drag handle `Frame:CreateTitleRegion()` makes: a plain Region
+    /// (`0x773910`) that answers `"Region"` and has only the 19 Region methods.
     Title,
 }
 
-/// Per-kind widget state — the "later layer" over the kind tag, for the kinds whose behavior is
-/// modeled. Lives on the [`Frame`] node (the client's `CSimpleStatusBar` etc. extend `CSimpleFrame`
-/// with exactly such members).
+/// The state a modeled kind adds over `CSimpleFrame`, carried on the [`Frame`] node.
 #[derive(Clone, Debug, PartialEq)]
 pub enum KindState {
-    /// No modeled per-kind behavior (a plain frame, or a kind whose behavior is a later layer).
+    /// No modeled per-kind state.
     None,
-    /// `CSimpleStatusBar` (factory `0x6eef20`; LoadXML table RF-28): a value in `[min, max]` filling
-    /// a bar texture along the orientation axis.
+    /// `CSimpleStatusBar` (factory `0x6eef20`, LoadXML `0x782ef0`): a value filling a bar texture.
     StatusBar(StatusBarState),
-    /// `CSimpleButton`/`CSimpleCheckbox` (factories `0x6eeab0`/`0x6eeb30`; LoadXML tables RF-28) —
-    /// the state-texture array + ButtonText. [`FrameKind::CheckButton`] shares this state (the
-    /// client's checkbox extends the button class), using the two `checked` members.
+    /// `CSimpleButton`/`CSimpleCheckbox` (factories `0x6eeab0`/`0x6eeb30`, LoadXML
+    /// `0x7788c0`/`0x785170`); the checkbox extends the button and uses the `checked` members.
     Button(ButtonState),
-    /// `CSimpleEditBox` (factory `0x6eec70`; runtime model RF-0082): the text buffer, cursor,
-    /// selection, config flags, and the FontString the text renders through.
+    /// `CSimpleEditBox` (factory `0x6eec70`): text, cursor, selection, flags and its FontString.
     EditBox(EditBoxState),
-    /// `CSimpleMessageScrollFrame` (ctor `0x787670`; runtime model msgframe-runtime.md): the line
-    /// ring, the per-line fade snapshots + phases, and the scrollback cursor.
+    /// `CSimpleMessageScrollFrame` (ctor `0x787670`): the line ring, fades and scrollback.
     ScrollingMessage(ScrollingMessageState),
-    /// `CSimpleMessageFrame` (ctor `0x785640`; same runtime model) — the `UIErrorsFrame` class:
-    /// display lines with no ring and no scrollback, plus `insertMode`. A **sibling** of
-    /// [`KindState::ScrollingMessage`], not a subset of it ([`MessageFrameState`]'s doc has the
-    /// contract table).
+    /// `CSimpleMessageFrame` (ctor `0x785640`): lines and `insertMode`, no ring or scrollback.
     Message(MessageFrameState),
-    /// `CSimpleScrollFrame` (decision 0112 — the ScrollFrame mechanism, the engine's last structural
-    /// gap: the quest log's detail pane, chat history, and every long-content window need it): the
-    /// scroll child + the vertical scroll offset. The offset setter and the range are byte-pinned
-    /// (2017: `0x786db0` stores the offset as given, no clamp; 1338: `0x786e30` measures the
-    /// child's subtree); the rest is spec-faithful to the documented contract, same posture as
-    /// StatusBar's fill. Horizontal scroll is out of scope (no 1.12 template drives it).
+    /// `CSimpleScrollFrame`: the scroll child and offsets. `0x786db0` stores an offset unclamped;
+    /// `0x786e30` measures the range from the child's subtree.
     Scroll(ScrollFrameState),
-    /// `CSimpleSlider` (factory `0x6eee40`; LoadXML table `0x789580`, RF-28): a value in `[min, max]`
-    /// with a step and orientation, positioning a thumb texture along the track. The mechanism is
-    /// spec-faithful to the documented Slider widget contract (same posture as StatusBar's fill /
-    /// ScrollFrame's scroll), not byte-pinned. Every scrollbar is one (decision 0250).
+    /// `CSimpleSlider` (factory `0x6eee40`, LoadXML `0x789580`), every scrollbar included.
     Slider(SliderState),
-    /// `CSimpleColorSelect` (ctor `0x78b220`, factory `0x6eef90`; LoadXML `0x78b3f0`, script-map
-    /// `0x78b4f0`, RF-28): the colour the picker window holds, as the client holds it — **HSV
-    /// floats**, not RGB ([`ColorSelectState`], whose docs carry the byte-verified law). The colour
-    /// *wheel* and *value strip* the real widget draws are engine art with no BLP behind them (their
-    /// `<ColorWheelTexture>`/`<ColorValueTexture>` elements carry no `file=`), so this state is the
-    /// widget's whole modeled behavior here; see [`crate::script::colorselect`].
+    /// `CSimpleColorSelect` (ctor `0x78b220`, factory `0x6eef90`, LoadXML `0x78b3f0`).
     ColorSelect(ColorSelectState),
-    /// The `Model` widget's scene state — the 3D pane an addon or a FrameXML frame parks a model
-    /// in. **The same split as [`KindState::Minimap`]**: the engine core carries exactly what
-    /// the Lua API reads and writes, and the pixels are the app renderer's job. See
-    /// [`ModelState`].
+    /// The scene state of every model kind; the pixels are the app's.
     Model(ModelState),
-    /// The `<Minimap>` widget's zoom state (decision 0203). The engine core carries only what the
-    /// Lua API reads/writes (`GetZoom`/`SetZoom`/`GetZoomLevels`); the tile/blip render is app-side.
+    /// The `<Minimap>` widget's zoom, mask and player arrow; the tiles and blips are the app's.
     Minimap(MinimapState),
-    /// The GameTooltip widget's line stack + owner/fade state ([`TooltipState`], decision 0274).
+    /// The `GameTooltip` line stack, owner and fade.
     Tooltip(TooltipState),
 }
 
 impl KindState {
-    /// The display lines of **either** message-frame class, or `None` for every other kind.
-    ///
-    /// The two classes are siblings with different stores, different `AddMessage` tails and
-    /// different scrollback (see [`MessageFrameState`]), but the *line record* they display is the
-    /// same [`MessageLine`] — text, quantized colour, fade phases, wrapped row count. This pair of
-    /// accessors is the only place that likeness is spent: the wrapped-row measure round-trip and
-    /// the band emit are one code path for both, while every behaviour that actually differs stays
-    /// on its own state. Matching on the two variants at those sites instead would have been two
-    /// near-copies of the round-trip, which is how the second one silently rots.
+    /// The display lines of either message-frame class, which share the [`MessageLine`] record.
     pub fn message_lines(&self) -> Option<&VecDeque<MessageLine>> {
         match self {
             KindState::ScrollingMessage(smf) => Some(&smf.lines),
@@ -231,8 +102,7 @@ impl KindState {
         }
     }
 
-    /// The message kinds' sweep-skip generation ([`ScrollingMessageState::lines_gen`]);
-    /// `None` for every other kind.
+    /// The message kinds' sweep-skip generation ([`ScrollingMessageState::lines_gen`]).
     pub fn lines_gen(&self) -> Option<u64> {
         match self {
             KindState::ScrollingMessage(smf) => Some(smf.lines_gen),
@@ -241,11 +111,10 @@ impl KindState {
         }
     }
 
-    /// [`Self::message_lines`], mutably — the measure round-trip's write-back half.
+    /// [`Self::message_lines`], mutably, for the measure's write-back.
     pub fn message_lines_mut(&mut self) -> Option<&mut VecDeque<MessageLine>> {
         match self {
-            // Any mut borrow through this door counts as a text change for the measure sweep's
-            // skip token — conservative, and the door every write-back path uses.
+            // Any mutable borrow counts as a text change for the measure sweep's skip token.
             KindState::ScrollingMessage(smf) => {
                 smf.lines_gen = smf.lines_gen.wrapping_add(1);
                 Some(&mut smf.lines)
@@ -259,70 +128,34 @@ impl KindState {
     }
 }
 
-/// A tooltip's anchor mode — the reference's `+0x318`, which `SetOwner 0x5310d0` writes and
-/// `GetAnchorType 0x5313e0` reads back through the 9-entry jump table `.rdata 0x531530`.
-///
-/// **The id order below is the jump table's, and it is NOT the setter's compare order** — a
-/// distinction that cost wow-re a contradiction between two of its own notes (`bag-portrait-and-
-/// appendtext.md` §5 had ids 2/3 and 4/5 swapped, because the setter compares `ANCHOR_BOTTOMRIGHT`
-/// third and stores it as id 3 while comparing `ANCHOR_BOTTOMLEFT` fourth and storing it as id 2;
-/// the getter's arm *bodies* sit in `.text` in that same compare order, so it reads as
-/// corroboration). Settled from three independent ends and fixed in place there:
-/// `system/ui/scratch/tooltip-cursor-anchor-law.md` §0/§0.1 (decision 2176).
-///
-/// **All nine modes are reachable.** `SetOwner`'s absent / non-string / unrecognised argument is
-/// mode **0** = [`TooltipAnchor::Left`], silently — the binding zero-initialises its local at
-/// `0x53120d` and neither the `lua_isstring` gate nor the compare chain's fall-through raises.
-///
-/// **What each mode does to the placement** (`0x52fe90`, read contiguously): a NULL owner returns
-/// at once; mode **8** returns at `0x52fead`, *before* the clear; every other mode reaches
-/// `0x52fec2 call 0x767ed0` (ClearAllPoints) — the mode-7 skip beside it is gated on an arg1
-/// `SetOwner`'s core always passes as 1 — and then modes **0..5** take the SetPoint jump table
-/// `0x52ffbc` while **6** and **7** stop there. So: 0..5 clear and point, 6 and 7 clear, 8 does
-/// neither.
+/// A tooltip's anchor mode (`+0x318`), set by `SetOwner` (`0x5310d0`), which reads a missing or
+/// unknown mode as [`TooltipAnchor::Left`] (`0x53120d`). The ids follow `GetAnchorType`'s table
+/// (`0x5313e0`, `0x531530`), not the setter's compare order. Placement (`0x52fe90`): modes 0..5
+/// clear the anchors and point, 6 and 7 only clear, 8 does neither.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum TooltipAnchor {
-    /// `ANCHOR_LEFT` — the plate's right edge on the owner's left.
+    /// `ANCHOR_LEFT`: the plate's right edge on the owner's left.
     Left,
-    /// `ANCHOR_RIGHT` — the plate's left edge on the owner's right; the stock UI's overwhelming
-    /// default (87 of the 123 `ANCHOR_*` mentions in 1.12's FrameXML).
+    /// `ANCHOR_RIGHT`: the plate's left edge on the owner's right.
     Right,
-    /// `ANCHOR_BOTTOMLEFT`.
     BottomLeft,
-    /// `ANCHOR_BOTTOMRIGHT`.
     BottomRight,
-    /// `ANCHOR_TOPLEFT`.
     TopLeft,
-    /// `ANCHOR_TOPRIGHT`.
     TopRight,
-    /// `ANCHOR_CURSOR` — mode 6: the anchors are cleared, and then the plate is re-anchored to the
-    /// live cursor **every frame** by the class's own update override `0x530b20`
-    /// (`script::tooltip::cursor_anchor` carries the law). Nine corpus files ask for it — `pfUI`'s
-    /// tooltip, xpbar and chat modules, `pfQuest/browser.lua`, `TipBuddy`.
+    /// `ANCHOR_CURSOR`: re-anchored to the live cursor every frame by the update `0x530b20`.
     Cursor,
-    /// `ANCHOR_NONE` — mode 7: the anchors are cleared and no `SetPoint` follows, leaving the
-    /// caller to point the plate (`GameTooltip_SetDefaultAnchor` does exactly that on the next
-    /// line, and that clear is what keeps a stale owner anchor from winning the frame a caller
-    /// forgets to re-point).
-    ///
-    /// **The default here**, which is a benilla choice rather than a read byte: the ctor
-    /// `0x529240` does not write `+0x318` at all, so what a never-owned plate holds depends on the
-    /// allocator, and `GetAnchorType` answers `"ANCHOR_NONE"` for anything out of range
-    /// (`0x53146f ja` shares the id-7 arm). ANCHOR_NONE is therefore the answer that is right
-    /// under the widest reading, and it is the one `pfUI/modules/tooltip.lua:97` compares against.
-    /// It is **not** `SetOwner`'s omitted-argument default, which is mode 0 — see the type doc.
+    /// `ANCHOR_NONE`: cleared, and the caller points the plate. The default here: the ctor
+    /// `0x529240` never writes `+0x318`, leaving the reference's start value to its allocator,
+    /// and the getter answers this for any out-of-range id (`0x53146f`).
     #[default]
     None,
-    /// `ANCHOR_PRESERVE` — mode 8: the owner is recorded and the previous placement is kept
-    /// *including its anchors* — `0x52fe90` returns at `0x52fead`, before the ClearAllPoints that
-    /// every other mode reaches. That clear-vs-keep split is the entire difference between this
-    /// and [`TooltipAnchor::None`]. Stored like any other mode, so `GetAnchorType` answers
-    /// `"ANCHOR_PRESERVE"` after one — the reference does not resolve it back to what it preserved.
+    /// `ANCHOR_PRESERVE`: the previous placement and its anchors are kept (`0x52fe90` returns at
+    /// `0x52fead`, before the clear); `GetAnchorType` still answers `"ANCHOR_PRESERVE"`.
     Preserve,
 }
 
 impl TooltipAnchor {
-    /// The reference's own spelling, as `GetAnchorType()` answers it (table `0x531530`).
+    /// The name `GetAnchorType()` answers (table `0x531530`).
     pub const fn name(self) -> &'static str {
         match self {
             TooltipAnchor::Left => "ANCHOR_LEFT",
@@ -338,259 +171,126 @@ impl TooltipAnchor {
     }
 }
 
-/// A `GameTooltip`'s runtime state (decision 0274). The line *text/color/wrap* is not duplicated
-/// here — each line pair is a real named FontString region (`<name>TextLeftN`/`TextRightN`,
-/// engine-created on demand, published as Lua globals exactly like the real template's 30
-/// pre-declared pairs, which reference Lua addresses by name: `GameTooltipTextLeft1:SetTextColor`).
-/// The state carries what the C++ class carries beside its strings: the live line count, the
-/// owner + the region pool, the minimum width, and the fade clock.
-///
-/// Layout is engine-side (`script::tooltip::layout_tooltips`, a `resolve` pre-pass): frame size =
-/// max measured line width + 2·[`TOOLTIP_PAD`] × summed line heights + gaps, right columns
-/// re-pointed flush to the text inset — the job the real client's C++ line layout does over the
-/// template's static anchors (today's Lua `OnUpdate` measure loop, retired).
+/// A `GameTooltip`'s state. Its lines are FontString regions named `<name>TextLeftN`/`TextRightN`,
+/// made on demand and published as Lua globals, as the stock template's 30 pairs are.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TooltipState {
     /// Lines currently filled (`NumLines`). Regions past this index exist but are hidden.
     pub num_lines: usize,
-    /// The left-column FontString pool, index i = line i+1. Grown on demand — no line cap (the
-    /// real template ships 30 pairs and the class grows via `AddFontStrings`; one mechanism here).
+    /// The left-column FontString pool, index i = line i+1, grown on demand with no line cap.
     pub left_lines: Vec<RegionHandle>,
     /// The right-column pool (the `AddDoubleLine`/`TextRightN` half), parallel to `left_lines`.
     pub right_lines: Vec<RegionHandle>,
-    /// `SetOwner`'s frame — dropped on hide (`IsOwned` is the hover re-enter loop's gate,
-    /// ref `ContainerFrame.lua` OnUpdate).
+    /// `SetOwner`'s frame, dropped on hide.
     pub owner: Option<FrameHandle>,
-    /// The anchor mode the last `SetOwner` placed this plate by, read back by `GetAnchorType()` —
-    /// the reference's `+0x318` (wow-re `bag-portrait-and-appendtext.md` §5,
-    /// `hover-hide-and-tooltip-owner-law.md` §4).
+    /// The last `SetOwner`'s mode, read back by `GetAnchorType()`.
     pub anchor: TooltipAnchor,
-    /// `SetMinimumWidth(w)` — a floor on the auto-sized width (the ref's money-row floor).
-    /// Cleared (0.0) by `ClearLines`/hide, like the content.
+    /// `SetMinimumWidth`: a floor on the auto-sized width, cleared with the content.
     pub min_width: f32,
-    /// `FadeOut()`'s start on the `GetTime` clock; `None` = not fading. Any fresh content
-    /// (SetOwner/SetText/AddLine/Show) cancels the fade and restores full alpha.
+    /// `FadeOut()`'s start on the `GetTime` clock; any fresh content or `Show` cancels the fade.
     pub fade_start: Option<f64>,
-    /// The unit token this tooltip currently shows (`SetUnit`/the world mouseover) — the health
-    /// watcher's key: a `set_unit` push for this token re-drives the status bar (decision 0276's
-    /// verified refresh law). Dropped with the content.
+    /// The unit this tooltip shows; a `set_unit` push for it re-drives the health bar.
     pub unit_token: Option<String>,
-    /// This tooltip currently shows WORLD-hover content (a mouseover unit, GameObject, or
-    /// corpse) — the fade-on-loss gate (`world_tooltip_fade`); a window hover never fades.
-    /// Dropped with the content.
+    /// Shows world-hover content, which fades when the hover is lost; a window hover never fades.
     pub world_owned: bool,
-    /// ARMED for a shopping-compare render: the next `SetInventoryItem` on this frame prepends the
-    /// gray "Currently Equipped" line — the builder's p5 `[arg+0x18]≠0` and NOTHING else. It is
-    /// deliberately not the neighbouring p4 `[arg+0x14]` (compact: white name, stat body jumped,
-    /// cut at `0x52e14c`), which both compare call sites pass as zero; conflating the two is what
-    /// made our shopping plates paint an epic's name white and drop its description (2216). Set by
-    /// the engine right before it fills a shopping plate, and consumed by that render. Survives
-    /// `SetOwner`'s content clear, because the reference's own compare caller
-    /// (`MerchantFrame.xml:67-72`) SetOwners *between* the arm and the render; how the real engine
-    /// plumbs the flag to `0x52b650` is unrecorded, so this seam is the INTERIM model of it.
+    /// Armed for a compare render: the next `SetInventoryItem` prepends "Currently Equipped"
+    /// (`[arg+0x18]`, not the compact `[arg+0x14]`), surviving the stock caller's `SetOwner` in
+    /// between (`MerchantFrame.xml:67-72`); the reference's route to `0x52b650` is untraced.
     pub equipped_header_armed: bool,
-    /// `SetPadding(w)` — extra width beyond the measured content (ref ItemRefTooltip's
-    /// OnLoad `SetPadding(16)`: room for the corner close button). 0 for ordinary tooltips.
+    /// `SetPadding`: extra width past the content (`ItemRef.xml:40` sets 16 for the close button).
     pub padding: f32,
-    /// Line 1 was ADOPTED from XML-declared regions (`<name>TextLeft1` in the instance/template
-    /// — ShoppingTooltipTemplate's small-font ladder): lines the engine creates past the
-    /// declared set clone the previous line's faces instead of the header/text defaults, the
-    /// real class's grow-past-the-template behavior.
+    /// Line 1 came from XML (`ShoppingTooltipTemplate`), so later lines clone the previous fonts.
     pub xml_declared_lines: bool,
 }
 
-/// The tooltip plate's text inset — the real template seats `TextLeft1` at TOPLEFT (10,−10).
+/// The plate's text inset: the stock template seats `TextLeft1` at TOPLEFT (10, −10).
 pub const TOOLTIP_PAD: f32 = 10.0;
-/// Inter-line gap — each `TextLeftN` hangs at the previous line's BOTTOMLEFT (0,−2).
+/// The line gap: each `TextLeftN` hangs at the previous line's BOTTOMLEFT (0, −2).
 pub const TOOLTIP_LINE_GAP: f32 = 2.0;
-/// The minimum gap between a double line's columns. INFERRED from the ref template's static
-/// `TextRightN` offset (+40 off its partner); the C++ layout that owns the real gap isn't RE'd —
-/// this is the eyeball knob if a double line reads too wide/tight (carried over from the
-/// pre-0274 Lua tooltip).
+/// The least double-line column gap, the stock `TextRightN` offset; the reference's is untraced.
 pub const TOOLTIP_DOUBLE_GAP: f32 = 40.0;
-/// `FadeOut`'s ramp length, seconds. INTERIM pending the 0274 §5 lifecycle verdict (the world-
-/// mouseover tooltip's fade constant lives in the untraced SetUnit/mouseover path).
+/// `FadeOut`'s ramp length in seconds; the reference's constant is untraced.
 pub const TOOLTIP_FADE_SECS: f64 = 0.5;
-/// The width a wrap-flagged line wraps at, logical px — pinned onto the line region at APPEND
-/// time (`append_line`), so its first measure comes back wrapped. INTERIM pending the 0274 §5
-/// (the real wrap column lives in the untraced C++ line layout); sized against the reference's
-/// description/trigger-line wrap by eye.
+/// A wrap-flagged line's width, pinned when it is appended; the reference's column is untraced.
 pub const TOOLTIP_WRAP_WIDTH: f32 = 260.0;
 
-/// The model-pane scene state — **shared by [`FrameKind::Model`] and [`FrameKind::PlayerModel`]**,
-/// because the client's `CGCharacterModelBase` (`0x505680`) *extends* `CSimpleModel` (`0x76c8e0`)
-/// rather than replacing it: every field below is a `CSimpleModel` member both classes carry.
-///
-/// **What this is and is not.** The 1.12 `Model` widget is a viewport that draws one M2 in a
-/// little scene of its own — the character pane, the tabard designer, the minimap ping, the pet
-/// bar's autocast shine, and every addon that wants a 3D thing in a frame. The engine core holds
-/// exactly the scene an addon can read back or write; **the render is the app's**, the same
-/// contract [`MinimapState`] already runs under, and the reason both exist as state-only kinds
-/// here.
-///
-/// **Every field is a 1.12 binding's storage, and which binding is read off the registrar, not off
-/// a string scan.** wow-re enumerated the whole family at the pair bytes on 2026-08-30
-/// (`ui/scratch/model-pane-method-tables.md`): `Model`'s table is `0x878948` with **23** entries,
-/// `PlayerModel`'s is `0x84f1fc` with **3**, and the derived table never repeats its base's. The
-/// earlier justification for these fields — "the names are in the binary as isolated strings" — is
-/// the mistake that round corrected: a `strings` hit answers *whether a name exists*, never *which
-/// table owns it*, and `SetUnit`'s single pooled string `0x84f22c` is referenced by two entries in
-/// two different tables. Ownership now comes from a dword-reference count over the name's VA.
-///
-/// **All 23 of `Model`'s are published** (decision 2027 carved the last seven — `AdvanceTime`,
-/// `ReplaceIconTexture` and the fog near/far/clear set). `script::tests::modelframe`'s `UNBUILT`
-/// array is the live count and is empty; the wall around it is what notices a name arriving or
-/// leaving (1134 §4's naming rule, with nothing left to name).
+/// A model pane's scene: the `CSimpleModel` (`0x76c8e0`) members every model kind carries, read
+/// and written by `Model`'s 23 methods (table `0x878948`); the render is the app's.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ModelState {
-    /// The M2/MDX path last given to `SetModel`, or `None` after `ClearModel` / before any set.
-    /// Stored **as written** — the client's own path space is `Interface\...\Foo.mdx`, and the
-    /// app's loader is what maps `.mdx` to the `.m2` that actually ships.
+    /// `SetModel`'s path as written (`.mdx`); the app's loader maps it to the shipped `.m2`.
     pub path: Option<String>,
-    /// `PlayerModel:SetUnit(unit)` — the *other* way a pane gets its content, used by the dress-up
-    /// and paper-doll frames. Mutually exclusive with [`Self::path`] in practice: whichever was set
-    /// last is what the pane shows, so each setter clears the other.
-    ///
-    /// The field lives on every pane because it is a `CSimpleModel` member; the **setter** does
-    /// not — `SetUnit` is [`FrameKind::PlayerModel`]'s (`0x84f1fc[0]` → `0x505d70`), and a plain
-    /// `<Model>` has no way to reach it.
+    /// `PlayerModel:SetUnit`'s unit (`0x505d70`); it and [`Self::path`] each clear the other.
     pub unit: Option<String>,
-    /// `SetSequence(n)` — the last animation id asked for (the raw id lands in
-    /// `[bone0 block + 0xf8]`, which `PlayerModel`'s per-paint stomp reads). What actually
-    /// PLAYS is [`Self::armed`].
+    /// The last `SetSequence` id (`[bone0 block + 0xf8]`); what plays is [`Self::armed`].
     pub sequence: i32,
-    /// **The widget's private scene clock**, milliseconds — `[scene+0xc]` of the `CM2Scene` the
-    /// widget owns (`0x76cfc0`, cached at `+0x314`; never the world's `[0xc7b298]`). Advanced by
-    /// the widget's own `OnUpdate` (`0x76d7f0`: `trunc(elapsed · 1000)`, no `+0.5`), which the UI
-    /// pump walks for **visible** frames only — so a hidden pane's clock stands still and a
-    /// re-shown one resumes where it stopped (the minimap ping's "ping N resumes where ping N−1
-    /// left off"). Nothing else advances it: `AdvanceTime` is inert. The scene outlives the
-    /// model, so `SetModel` does not reset it. Decision 2007.
+    /// The pane's own scene clock in ms (`0x76cfc0`): its `OnUpdate` (`0x76d7f0`) adds
+    /// `trunc(elapsed · 1000)` only while shown; `AdvanceTime` is inert, `SetModel` keeps it.
     pub clock_ms: u64,
-    /// What is armed on bone slot 0 — the sequence the pane plays and the anchor its cursor is
-    /// read against. `None` while nothing plays: before any file, after `ClearModel`, or after
-    /// a `SetSequence` naming an id the file does not own (which stops what was playing and
-    /// arms nothing — `0x7121a0`'s interrupt runs before its bounds check).
+    /// The sequence on bone slot 0. A `SetSequence` id the file does not own stops what played
+    /// and arms nothing (`0x7121a0` interrupts before its bounds check).
     pub armed: Option<ArmedSequence>,
-    /// `SetModel` ran but the loader's own arm has not — the file's facts ([`ModelFileFacts`])
-    /// were not known at the call. The reference links the instance as a waiter for the
-    /// streaming drain and runs the completion (`0x70ebd0`: arm Stand, variation 0) when the
-    /// asset lands; [`ModelState::seed_from_facts`] is that completion, run when the host hands
-    /// the facts over.
+    /// `SetModel` ran and the loader's completion ([`ModelState::seed_from_facts`]) awaits facts.
     pub pending_seed: bool,
-    /// `ReplaceIconTexture(path)` — the type-14 texture override (`0x76cfe0(0xe, path)` →
-    /// `0x710ec0`), which lives on the model instance and dies with it: `SetModel` and
-    /// `ClearModel` clear it. `None` = the file's own textures.
+    /// `ReplaceIconTexture`'s override (`0x76cfe0`); `SetModel` and `ClearModel` drop it.
     pub icon: Option<String>,
-    /// The frame's size is the **implicit rect** — the file's bounding-box extent in layout units
-    /// (`bboxExtent · 768·√(a²+1)` FrameXML units; render law §3, `implicit-size-law.md` §1),
-    /// written by the engine because the pane authored no size (decision 2015). The geometry
-    /// getters `0x76d080`/`0x76d0d0` answer it whenever no size is authored; here it is written
-    /// into the layout input when the file's facts land and re-derived when the screen's aspect
-    /// moves, and an authored `SetWidth`/`SetHeight` clears it for good.
+    /// No size authored: the pane takes the file's box extent, `bboxExtent · 768·√(a²+1)` units
+    /// (`0x6f1eb0`, `0x76d080`), re-derived on aspect change; an authored size clears it for good.
     pub implicit_size: bool,
-    /// The pane's yaw in radians — `CSimpleModel+0x39c`. **One slot, written by two verbs on two
-    /// different classes**: `Model:SetFacing` (`0x76dce0`) and `PlayerModel:SetRotation`
-    /// (`0x505f00` → `0x505bb0`, whose last act is `0x505c44 mov [esi+0x39c], eax` — literally the
-    /// same field). That is why the reference's rotate buttons can drive a paper-doll pane through
-    /// `SetRotation` and `GetFacing` reads it back.
+    /// Yaw in radians (`+0x39c`), one slot written by both `Model:SetFacing` (`0x76dce0`) and
+    /// `PlayerModel:SetRotation` (`0x505f00`), so `GetFacing` reads either back.
     pub facing: f32,
-    /// `SetModelScale` — the model's own scale within the pane, default 1.
+    /// `SetModelScale`: the model's scale within the pane, default 1.
     pub scale: f32,
-    /// The **pending** camera index (`CSimpleModel+0x320`) — `Some(n)` while the camera question
-    /// is open, `None` once it is settled. The ctor writes `Some(0)`, a standing request for raw
-    /// camera 0, which the model-ready hook applies ([`ModelState::seed_from_facts`]); `SetCamera`
-    /// with no facts yet defers into it (`0x76cec0`'s two early legs). **While it is `Some`, the
-    /// pane draws nothing at all** — the reference's draw gate is
-    /// `76d5f0 cmp [this+0x320],-1 ; jne <skip everything>` (decision 2027).
+    /// The camera index still to install (`+0x320`): the ctor's `Some(0)`, or a `SetCamera` made
+    /// before the facts (`0x76cec0`). While it is `Some` the pane draws nothing (`0x76d5f0`).
     pub camera_pending: Option<i32>,
-    /// The **installed** camera (`+0x31c`) as a RAW index into the file's camera table, or `None`
-    /// for the NULL camera — which is what an index past the table's count installs (`76cf08`)
-    /// and what a file with no cameras always gets. `None` is the **orthographic** render leg;
-    /// `Some(n)` is the perspective one, framed by the file's own record `n`.
-    ///
-    /// Raw is the whole point: `0x76cec0` reads the count off `MD20+0x124` and the record at
-    /// `[model+0x3c4] + idx·0x84 + 0x80`, and **never consults `cameraLookup`** — that array is
-    /// the portrait bake's path (wow-re `modelframe-camera-law.md` §2.1).
+    /// The installed camera (`+0x31c`): a raw camera-table index, never via `cameraLookup`, drawn
+    /// in perspective; `None`, the NULL camera an out-of-range index installs, draws orthographic.
     pub camera: Option<u32>,
-    /// `SetPosition(x, y, z)` — the model's offset within the pane's scene.
+    /// `SetPosition`: the model's offset within the pane's scene.
     pub position: (f32, f32, f32),
-    /// The pane's embedded `CGLight` (`CSimpleModel+0x324`) — see [`ModelLight`]. Typed since
-    /// decision 2027: the render law (§5.1–§5.3) carves every field, its consumer and both of
-    /// `SetLight`'s traps, so the tuple no longer has to be stored opaquely.
     pub light: ModelLight,
-    /// `SetFogColor(r, g, b, a)` as the reference stores it: **one packed `0xAARRGGBB` dword**,
-    /// which is why its getter is four values wide and why a Set→Get round trip is **lossy** —
-    /// eight bits per channel (decision 1845).
-    ///
-    /// `0xffff_ffff` is the ctor's own terminal write, so the never-set answer is `1, 1, 1, 1` and
-    /// not four zeros. It used to be `Option<(f32, f32, f32)>` here: three components, no alpha,
-    /// and `None` for unset — every one of those three wrong.
-    ///
-    /// All seven fog verbs are built as of decision 2027 — this pair plus
-    /// `SetFogNear`/`GetFogNear`/`SetFogFar`/`GetFogFar`/`ClearFog` — because the render law
-    /// (§5.4) carves every one of their bodies.
+    /// `SetFogColor` as the reference stores it, one packed `0xAARRGGBB` dword, so a round trip
+    /// keeps 8 bits a channel; the ctor's `0xffff_ffff` reads back as `1, 1, 1, 1`.
     pub fog_color: u32,
-    /// `+0x3a4` **bit 0** — fog armed. Set by `SetFogColor` (`76f059 or [edi+0x3a4],1`) and by the
-    /// XML `<FogColor>` child; cleared by `ClearFog` (`76f5c5 and [edi+0x3a4],-2` — **bit 0 only**,
-    /// so the colour, near and far all survive a clear and come back on the next `SetFogColor`).
-    /// The ctor leaves it off.
+    /// Fog armed (`+0x3a4` bit 0): set by `SetFogColor` and `<FogColor>`, cleared by `ClearFog`,
+    /// which leaves colour, near and far for the next `SetFogColor`.
     pub fog: bool,
-    /// `+0x3ac` — fog near, raw and unclamped from `SetFogNear` (`76f282 fstp`), clamped at `≥ 0`
-    /// only on the XML `fogNear` attribute path (`76cbbb`). Ctor `0.0`.
+    /// Fog near (`+0x3ac`): unclamped from `SetFogNear`, clamped `≥ 0` only from XML `fogNear`.
     pub fog_near: f32,
-    /// `+0x3b0` — fog far, same shape as [`Self::fog_near`] (`76f432`, XML `fogFar` at `76cbf3`).
-    /// **Ctor `1.0`**, not `0.0`: the fill callback stages `1/(far − near)` and the batch fogs
-    /// only when that is `> 0`, so the ctor's pair is already a valid (if tiny) ramp.
+    /// Fog far (`+0x3b0`), shaped like [`Self::fog_near`]; the ctor's is `1.0`.
     pub fog_far: f32,
 }
 
-/// A model pane's **armed** fog — [`ModelState::armed_fog`]'s answer, and the whole of what the
-/// renderer needs: the disarmed values are engine state that nothing draws.
+/// A model pane's armed fog, all the renderer needs ([`ModelState::armed_fog`]).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ModelFog {
-    /// The packed `0xAARRGGBB` colour (`+0x3a8`). The alpha byte exists and is **never read** by
-    /// the fill callback (`0x76d680` takes bytes 2,1,0 only).
+    /// The packed `0xAARRGGBB` colour (`+0x3a8`); the fill callback `0x76d680` never reads alpha.
     pub color: u32,
-    /// `+0x3ac` / `+0x3b0`, raw. The fill stages `1/(far − near)` and a batch fogs only when that
-    /// is `> 0`, so a `far <= near` pair arms the flag and still draws unfogged.
+    /// Raw near and far (`+0x3ac`/`+0x3b0`); a batch fogs only when `1/(far − near) > 0`, so
+    /// `far <= near` draws unfogged.
     pub near: f32,
     pub far: f32,
 }
 
 impl ModelFog {
-    /// The colour as linear `[r, g, b]` in `0..=1` — the fill callback's own unpack
-    /// (`0x7bbf20` -> bytes 2,1,0 × 1/255).
+    /// The colour as `[r, g, b]` in `0..=1`, the fill callback's unpack (`0x7bbf20`).
     pub fn rgb(&self) -> [f32; 3] {
         [16, 8, 0].map(|shift| ((self.color >> shift) & 0xff) as f32 / 255.0)
     }
 }
 
-/// A model pane's embedded **`CGLight`** — the 0x6c-byte object at `CSimpleModel+0x324` that the
-/// per-paint fill callback `0x76d680` adds to the model's light collector, and the only light a
-/// `<Model>` widget has (wow-re `modelframe-render-law.md` §5.1/§5.2).
-///
-/// **A plain `<Model>`'s is DISABLED and stays that way unless Lua enables it.** The ctor
-/// `0x76c8e0` leaves `+0x60 = 0`, so `0x71bf90` returns before adding anything and the collector
-/// finalizes with zero ambient and zero diffuse — under which a LIT batch draws **black**. That
-/// is harmless by asset design (every in-game UI M2 is UNLIT on every material, §5.7) and it is
-/// the faithful answer for an addon's lit one. `<PlayerModel>`'s ctor `0x505680` enables its own
-/// instead, which is why the paper doll is lit; those panes are the portrait booth's, not this
-/// widget's.
-///
-/// Each colour is stored **already multiplied by its intensity** — `SetLight` folds
-/// `rgb/255 × intensity` before the copy — which is why there is no separate intensity field.
+/// A model pane's embedded `CGLight` (`+0x324`), its only light (`0x76d680`): off on a plain
+/// `<Model>` until Lua enables it, so a lit batch draws black (`0x71bf90`), and on for a
+/// `PlayerModel` (ctor `0x505680`). Colours are stored times their intensity.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ModelLight {
-    /// `CGLight+0x60` — enabled. `SetLight`'s first argument writes it, and **only when nonzero**:
-    /// `SetLight(0, …)` returns at `76e2cb` without touching the widget at all, so it is not a
-    /// way to turn a light off (§5.3 trap 1).
+    /// `+0x60`: set by a nonzero `SetLight` (`0x76e1e0`) first argument; `SetLight(0, …)` is inert.
     pub enabled: bool,
-    /// `+0x08` — type. `true` = point/omni (`1`, what both ctors write), `false` = directional.
-    /// Chooses which of the two vector setters `SetLight`'s `(x, y, z)` reaches.
+    /// `+0x08`: point (`1`, both ctors) or directional; picks where `SetLight`'s `(x, y, z)` goes.
     pub omni: bool,
-    /// `+0x0c` position (when [`Self::omni`]) or `+0x24` direction (when not) — the direction is
-    /// **normalised on write** by `0x71b6a0`, and is a *from-light* vector.
+    /// Position (`+0x0c`), or a directional light's from-light direction (`+0x24`), normalised.
     pub vector: [f32; 3],
     /// `+0x30` ambient, intensity already folded in.
     pub ambient: [f32; 3],
@@ -598,9 +298,7 @@ pub struct ModelLight {
     pub diffuse: [f32; 3],
 }
 
-/// The `<Model>` ctor's light (`0x76c8e0`): `0x71b4a0` (type 1, everything else zero), then
-/// enabled `0` at `76c99c`, type `1` at `76c9a5`, ambient `(1,1,1)` at `76c9b4`–`76c9d3` and
-/// diffuse `(1,1,1)` at `76c9d6`–`76c9ff`. White, and switched off.
+/// The `<Model>` ctor's light (`0x76c8e0`, `0x71b4a0`): white, and switched off.
 impl Default for ModelLight {
     fn default() -> Self {
         Self {
@@ -613,11 +311,7 @@ impl Default for ModelLight {
     }
 }
 
-/// A fresh `Model` pane: no content, sequence 0, unrotated, unit scale, camera 0, at the origin.
-///
-/// `scale` is the one field whose zero value would be wrong — a model at scale 0 is invisible, and
-/// the widget's documented default is 1 — so [`ModelState`] cannot use a derived `Default` for it
-/// and this impl exists to say why.
+/// A fresh pane as the `CSimpleModel` ctor leaves it.
 impl Default for ModelState {
     fn default() -> Self {
         Self {
@@ -643,105 +337,75 @@ impl Default for ModelState {
     }
 }
 
-/// What a pane's bone slot 0 is playing — the reference's `0x7121a0` arm (`SetSequence`
-/// `0x76dec0` → `0x76cf50`, `SetSequenceTime` `0x76dfc0` → `0x76cf80`, and the loader's own
-/// seed `0x70ebd0`): the id, and the **anchor** the cursor is read against. The reference
-/// bakes `cursor_lo = sceneClock − trunc(ms)` once and its sampler re-reads that anchor every
-/// frame; there is no counter that advances on its own, which is what lets the cooldown scrub
-/// the pane every paint without the clock fighting it. Decision 2007.
+/// What bone slot 0 plays, as the `0x7121a0` arm leaves it: the id and the anchor the cursor
+/// counts from, with no counter of its own, so a caller can scrub the pane every paint.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ArmedSequence {
-    /// The `AnimationData.dbc` id — `SetSequence`'s argument, or the loader's Stand seed.
+    /// The `AnimationData.dbc` id: `SetSequence`'s argument, or the loader's Stand seed.
     pub anim_id: i32,
-    /// The scene-clock value the cursor counts from: `cursor = clock_ms − anchor_ms`, so a
-    /// `SetSequenceTime(id, ms)` at clock `c` stores `c − ms`.
+    /// The clock value the cursor counts from: `SetSequenceTime(id, ms)` at `c` stores `c − ms`.
     pub anchor_ms: i64,
-    /// The scene clock when the arm was made — so a queued arm (made before the file's facts
-    /// were known) can replay at residency with its original offset: `armed_at − anchor` is the
-    /// `ms` the call asked for.
+    /// The clock at the arm, so an arm queued behind the load replays with its offset.
     pub armed_at_ms: u64,
-    /// The completion callback has fired for this arm — the sequence ran its length (a clamp's
-    /// end, or a loop's first pass) and the widget's `OnAnimFinished` ran. Once per arm: a
-    /// re-arm starts a fresh one.
+    /// `OnAnimFinished` has fired for this arm; it fires once per arm.
     pub finished: bool,
 }
 
-/// The playing sequence's cursor, as the renderer samples it — [`ModelState::play_head`]'s
-/// answer under the file's facts.
+/// The playing sequence's cursor, as the renderer samples it ([`ModelState::play_head`]).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ModelPlayHead {
-    /// The `AnimationData.dbc` id of the armed sequence (the file owns it — see
-    /// [`ModelFileFacts::owns`]).
+    /// The armed sequence's `AnimationData.dbc` id, one the file owns.
     pub anim_id: u16,
-    /// Milliseconds into the sequence: wrapped for a looping one, held at the last frame for a
-    /// clamped one that has completed.
+    /// Milliseconds in: wrapped when looping, held at the end when clamped.
     pub cursor_ms: u32,
 }
 
-/// One sequence of a model file, as the clock needs it — see [`ModelFileFacts`].
+/// One sequence of a model file, as the pane clock needs it.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct SequenceFacts {
     /// The `AnimationData.dbc` id (`M2Sequence+0x00`).
     pub anim_id: u16,
     /// The sequence's length, `end − start` on the file's timeline (`+0x08 − +0x04`).
     pub duration_ms: u32,
-    /// The sequence loops (the flag the formats crate decodes as `looping`); a clamped one
-    /// holds its last frame and fires the completion callback once.
+    /// Loops; a clamped sequence holds its last frame.
     pub looping: bool,
 }
 
-/// What the engine needs to know about a model **file** to run a pane's clock — the reference
-/// reads these off the resident `MD20` (`animationLookup` at `md20+0x24`, the sequence table,
-/// the header bounds); here the host's M2 loader has them and hands them over through
-/// `UiScript::set_model_facts` once the asset lands. Keyed by the `SetModel` path
-/// ([`model_key`]), shared by every pane holding that file. Decision 2007.
+/// What a pane needs from its model file, which the reference reads off the resident `MD20`; the
+/// host hands it over (`UiScript::set_model_facts`), keyed by [`model_key`].
 #[derive(Clone, Debug, PartialEq)]
 pub struct ModelFileFacts {
-    /// The sequences the file owns, **in file order** — the first is `animations[0]`, the
-    /// loader's fallback seed when the file does not own id 0.
+    /// The file's sequences in file order; the first is the seed when id 0 is missing.
     pub sequences: Vec<SequenceFacts>,
-    /// The header bounding box, raw WoW model space (`min`, `max`) — the implicit rect of a
-    /// size-less `<Model>` (render law §3) and the arrow's re-centring.
+    /// The header bounding box `(min, max)` in model space.
     pub bbox: ([f32; 3], [f32; 3]),
-    /// How many records the file's **camera table** holds (`MD20+0x124`) — the bound
-    /// `Model:SetCamera(n)` is checked against (`0x76cec0`: `76ceeb if idx >= count -> install
-    /// NULL`). `0` for the overwhelming majority of models, which is why a plain `<Model>` almost
-    /// always ends on the orthographic leg. Decision 2027.
+    /// The camera table's size (`MD20+0x124`), `SetCamera`'s bound (`0x76cec0`); 0 for most models.
     pub cameras: u32,
 }
 
 impl ModelFileFacts {
-    /// Does the file own `anim_id` — the reference's `0x711960` ("does `animationLookup` map
-    /// it"): a model owns an id iff some sequence carries it.
+    /// Whether the file owns `anim_id`: `0x711960`'s `animationLookup` test.
     pub fn owns(&self, anim_id: u16) -> bool {
         self.sequences.iter().any(|s| s.anim_id == anim_id)
     }
 
-    /// The sequence `SetSequence(anim_id)` plays: the id's **first** file slot — variation 0,
-    /// which is what both the loader's seed and the widget's arm pass (`0x7121a0`'s third
-    /// argument is `0`, never `-1`, on this path).
+    /// The sequence `SetSequence(anim_id)` plays: the id's first slot, variation 0 (`0x7121a0`).
     pub fn sequence(&self, anim_id: u16) -> Option<&SequenceFacts> {
         self.sequences.iter().find(|s| s.anim_id == anim_id)
     }
 
-    /// The header bounding box's `(x, y)` extent in model units — the implicit rect of a
-    /// size-less pane (render law §3) and the arrow's re-centring (`0x4a7b20`: `½·GetWidth`,
-    /// `½·GetHeight`, both the geometry override's bbox extent).
+    /// The box's `(x, y)` extent, a size-less pane's implicit rect (`0x76d080`/`0x76d0d0`).
     pub fn extent(&self) -> (f32, f32) {
         let (min, max) = self.bbox;
         ((max[0] - min[0]).max(0.0), (max[1] - min[1]).max(0.0))
     }
 
-    /// Which camera raw index `idx` installs: `Some(idx)` when the table has it, `None` — the
-    /// **NULL** camera, i.e. the orthographic leg — when it does not. Negative indices land in the
-    /// same place the reference's unsigned `jae` puts them.
+    /// The camera raw index `idx` installs; `None`, the NULL camera, out of range or negative.
     pub fn camera_at(&self, idx: i32) -> Option<u32> {
         u32::try_from(idx).ok().filter(|&i| i < self.cameras)
     }
 
-    /// The loader's idle seed (`0x70ebd0`'s tail, `0x710153`–`0x71019b`): **id 0 (`Stand`) if
-    /// the file owns it, else `animations[0]`'s own id**; `None` only for a file with no
-    /// sequences at all.
+    /// The loader's idle seed (`0x70ebd0`): Stand (id 0) if owned, else the first sequence's id.
     pub fn stand_id(&self) -> Option<u16> {
         if self.owns(0) {
             Some(0)
@@ -751,9 +415,7 @@ impl ModelFileFacts {
     }
 }
 
-/// The key a model path is filed under: case-folded, forward slashes, no extension — so
-/// `Interface\Cooldown\UI-Cooldown-Indicator.mdx` and its shipped `.m2` twin are one file, as
-/// they are for the loader.
+/// A model path's key: case-folded, forward slashes, no extension, so `.mdx` and `.m2` match.
 pub fn model_key(path: &str) -> String {
     let p = path.to_ascii_lowercase().replace('\\', "/");
     let stem = p
@@ -765,11 +427,8 @@ pub fn model_key(path: &str) -> String {
 }
 
 impl ModelState {
-    /// `SetModel(path)` — `vt+0x94` (`0x76cce0`): a **fresh instance** of the file (`CreateModel`
-    /// with flags 5), which displaces a unit, drops the previous instance's icon override and
-    /// its arm, and runs the loader's completion (`0x70ebd0`) synchronously when the file is
-    /// resident — [`Self::seed_from_facts`] — else waits for it ([`Self::pending_seed`]). The
-    /// scene clock is the WIDGET's, not the instance's, and keeps running.
+    /// `SetModel` (`0x76cce0`): a fresh instance, dropping unit, icon override and arm, seeded now
+    /// if the file is resident, else when it lands (`0x70ebd0`); the scene clock runs on.
     pub fn set_file(&mut self, path: String, facts: Option<&ModelFileFacts>) {
         self.path = Some(path);
         self.unit = None;
@@ -781,7 +440,7 @@ impl ModelState {
         }
     }
 
-    /// `ClearModel` — releases the instance: no file, no unit, no override, nothing armed.
+    /// `ClearModel`: releases the instance.
     pub fn clear_file(&mut self) {
         self.path = None;
         self.unit = None;
@@ -790,13 +449,8 @@ impl ModelState {
         self.pending_seed = false;
     }
 
-    /// `SetSequence` / `SetSequenceTime` — the `0x7121a0` arm. It **interrupts** whatever plays
-    /// first (the completion callback fires with a non-zero mode there, which the widget's
-    /// `OnAnimFinished` gate ignores — §4.5: natural completion only), then arms `id` at `ms`
-    /// into it — or arms nothing when the file does not own the id (the bounds check at
-    /// `71247c` returns having armed nothing). With the facts not known yet the arm is kept and
-    /// re-checked when they land ([`Self::seed_from_facts`]) — the reference's queued replay for
-    /// a file still streaming.
+    /// `SetSequence`/`SetSequenceTime` (`0x7121a0`): interrupts what plays, with no
+    /// `OnAnimFinished` (`0x76cdc6`), then arms `id` at `ms` unless the known file lacks it.
     pub fn arm(&mut self, id: i32, ms: i64, facts: Option<&ModelFileFacts>) {
         self.sequence = id;
         let owned = u16::try_from(id)
@@ -810,12 +464,8 @@ impl ModelState {
         });
     }
 
-    /// The loader's completion for a file that just became resident (`0x70ebd0`), then the
-    /// replay of what was queued behind the load: the seed arms Stand (variation 0); an explicit
-    /// `SetSequence`/`SetSequenceTime` made while the file streamed replays AFTER it — at its
-    /// original offset — and decides the final state, which for an id the file does not own is
-    /// **nothing armed** (the interrupt ran, the bounds check armed nothing). Idempotent once
-    /// the seed has run: a second hand-over of the same facts only re-checks ownership.
+    /// The loader's completion (`0x70ebd0`): arms Stand, then replays an arm queued during the
+    /// load at its offset, which decides the result. A later call only re-checks ownership.
     pub fn seed_from_facts(&mut self, facts: &ModelFileFacts) {
         let queued = self.armed.filter(|_| self.pending_seed);
         if self.pending_seed {
@@ -835,18 +485,13 @@ impl ModelState {
                 self.armed = None;
             }
         }
-        // The model-ready hook's other half (`0x76ce00` `76ce3e`): apply the pending camera index
-        // if the question is still open. The ctor's standing `Some(0)` is what gives a plain
-        // `<Model>` its default camera 0, and it is applied here, once, exactly as the reference
-        // applies it on the asset-ready edge.
+        // The model-ready hook's other half (`0x76ce00`): the pending camera, 0 from the ctor.
         if let Some(idx) = self.camera_pending {
             self.install_camera(idx, Some(facts));
         }
     }
 
-    /// The pane's fog, **only when it is armed** (`+0x3a4` bit 0) — the fill callback's own gate
-    /// (`76d68a test byte [esi+0x3a4],1 ; je`). A disarmed pane stages nothing, and its collector
-    /// keeps the zeroed `1/(far − near)` that the per-batch fog test refuses.
+    /// The pane's fog when armed (`+0x3a4` bit 0), the fill callback's own gate.
     pub fn armed_fog(&self) -> Option<ModelFog> {
         self.fog.then_some(ModelFog {
             color: self.fog_color,
@@ -855,13 +500,8 @@ impl ModelState {
         })
     }
 
-    /// `0x76cec0` — select a camera by RAW table index. With no facts yet (the reference's "no
-    /// model" / "not ready" legs at `76cece`/`76cedb`) the index is **deferred** into
-    /// [`Self::camera_pending`] and nothing draws until it resolves; with facts, the index is
-    /// bounds-checked against the table's count and either installed or answered with the NULL
-    /// camera, and **either way the pending index is cleared** (`0x76ce80`'s
-    /// `76cead mov [esi+0x320],-1` — installing *any* camera, NULL included, settles the
-    /// question).
+    /// `SetCamera` by raw index (`0x76cec0`): deferred until the facts are known, then installed
+    /// or answered with the NULL camera, either clearing the pending index (`0x76ce80`).
     pub fn install_camera(&mut self, idx: i32, facts: Option<&ModelFileFacts>) {
         match facts {
             Some(f) => {
@@ -872,9 +512,7 @@ impl ModelState {
         }
     }
 
-    /// Where the armed sequence stands on the scene clock, under `facts`: wrapped for a looping
-    /// sequence, held at the end for a clamped one. `None` when nothing is armed or the arm names
-    /// a sequence the facts do not carry.
+    /// Where the armed sequence stands on the scene clock under `facts`.
     pub fn play_head(&self, facts: &ModelFileFacts) -> Option<ModelPlayHead> {
         let armed = self.armed?;
         let anim_id = u16::try_from(armed.anim_id).ok()?;
@@ -894,12 +532,8 @@ impl ModelState {
         })
     }
 
-    /// Has the armed sequence run its length without its completion having fired — the edge the
-    /// tick turns into `OnAnimFinished` (the completion callback `0x76cdc0`, `mode == 0`). Once
-    /// per arm, and **for a looping sequence too**: `0x719370` enqueues the completion when the
-    /// widget clock reaches `lo + duration · replays` and tests the loop flag only after it, so a
-    /// loop's first pass completes exactly like a clamp's end (wow-re
-    /// `modelframe-texanim-and-sequence-law.md`, Q4; corrects 2007's "clamped only").
+    /// The armed sequence ran its length and `OnAnimFinished` (`0x76cdc0`) is owed, once per arm
+    /// and for a loop too: `0x719370` enqueues it before testing the loop flag.
     pub fn completion_due(&self, facts: &ModelFileFacts) -> bool {
         let Some(armed) = self.armed else {
             return false;
@@ -917,51 +551,24 @@ impl ModelState {
     }
 }
 
-/// The Minimap widget's modeled state — the client keeps **two independent zoom indices**, chosen by
-/// whether the player is inside a WMO (wow-re minimap node, `wmo-interior-minimap.md` finding 2 Q7
-/// CORRECTION): the inside flag `0xceaa60` routes the outdoor index `0x86f698` (CVar `minimapZoom`,
-/// chunk table `0x8116d0`) or the indoor index `0x86f69c` (CVar `minimapInsideZoom`, radius table
-/// `0x8116e8` = `{150,120,90,60,40,25}` yd). `GetZoom`/`SetZoom` read/write whichever is active, and
-/// each persists across transitions — so zooming in indoors does not disturb the outdoor zoom, and
-/// vice versa. (An earlier reading held the second index to be a rotate-minimap CVar and the interior
-/// scale to be a constant; both were wrong — superseded in wow-re. Stronger since the ping RE
-/// (`minimap-ping-law.md`): there is **no rotate-minimap CVar in 5875 at all** — a 214-site
-/// `CVar::Register` census plus a whole-image string scan found no such knob, so nothing on this
-/// path ever needs a rotation term.) `set_zoom` clamps to 5.
+/// The Minimap widget's state. The client keeps two zoom indices, outdoor (`0x86f698`, CVar
+/// `minimapZoom`) and indoor (`0x86f69c`, CVar `minimapInsideZoom`, radii `{150,120,90,60,40,25}`
+/// yd); the WMO-interior flag `0xceaa60` picks which one `GetZoom`/`SetZoom` use.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MinimapState {
-    /// The **outdoor** zoom index, `0..MINIMAP_ZOOM_LEVELS` (0 = widest, 5 = tightest). `SetZoom`
-    /// clamps like the client's `0x6daa10` (clamp at 5, mark dirty).
+    /// The outdoor zoom index, 0 widest to 5 tightest; `SetZoom` clamps at 5 (`0x6daa10`).
     pub zoom: u8,
-    /// The **indoor** zoom index (same range), persisted separately — the client's `0x86f69c`.
     pub inside_zoom: u8,
-    /// Is the player inside a WMO interior (the client's `0xceaa60`)? Selects which index the Lua
-    /// zoom API reads and writes. Pushed down by the app, which owns the WMO containment test.
+    /// Inside a WMO interior, which picks the index; pushed by the app, which owns that test.
     pub inside: bool,
-    /// The mask art the disc is cut to — `Minimap:SetMaskTexture(path)`, a real 1.12 method (the
-    /// name is in the 5875 image; there is no `GetMaskTexture` beside it, so this is write-only
-    /// from Lua). `None` = the engine default, [`MINIMAP_DEFAULT_MASK`].
-    ///
-    /// State-only here, pixels app-side, like the zoom index (0203): the app already masks the
-    /// disc through its own `UiQuadMask`, and this only decides which texture it loads. It is what
-    /// makes a **square minimap** possible, which is the single most recognisable thing pfUI does
-    /// to the default UI (`modules/minimap.lua:27`).
+    /// `Minimap:SetMaskTexture`'s mask, write-only from Lua; `None` is [`MINIMAP_DEFAULT_MASK`].
     pub mask_texture: Option<String>,
-    /// The **player-arrow** `Model` — the client's `[Minimap+0x338]`, ninth and last of the nine
-    /// engine children the ctor builds ([`MINIMAP_ENGINE_CHILDREN`]). An explicit slot because that
-    /// is the shape the client keeps: `CMinimap::SetPlayerFacing 0x4eb8e0` reaches the arrow through
-    /// this field, never by counting children; "it is also `GetChildren()[9]`" is a *consequence* of
-    /// the ctor's order, not the definition.
+    /// The player-arrow `Model` (`[Minimap+0x338]`), reached by `SetPlayerFacing` (`0x4eb8e0`).
     pub player_arrow: Option<FrameHandle>,
 }
 
-/// Both minimap zoom CVars register with the default `"3"` — **not** 0 (wow-re, VERIFIED at the
-/// `RegisterCVar 0x63db90` argument slot: `minimapZoom` @`0x48fc5a` and `minimapInsideZoom`
-/// @`0x48fc76` each push the string `"3"` at `0x82e960`). The minimap reset path copies the
-/// persisted CVar int into the live index rather than zeroing it, so 3 is what a fresh client runs.
-/// **Higher index = more zoomed in**: index 3 ⇒ a 60 yd indoor radius (of the `{150…25}` table) and a
-/// 133.3 yd outdoor half-extent (of the `{14…4}` chunk table). Seeding 0 here made both maps far too
-/// wide — the director's "way too zoomed out" (2026-07-09).
+/// Both zoom CVars register with `"3"` (`0x48fc5a`/`0x48fc76`) and the reset copies the CVar in;
+/// a higher index zooms in, 3 being a 60 yd indoor radius and a 133.3 yd outdoor half-extent.
 pub const MINIMAP_DEFAULT_ZOOM: u8 = 3;
 
 impl Default for MinimapState {
@@ -971,15 +578,14 @@ impl Default for MinimapState {
             inside_zoom: MINIMAP_DEFAULT_ZOOM,
             inside: false,
             mask_texture: None,
-            // Filled by the arena the moment the widget is inserted — the nine are ctor-time, so a
-            // Minimap is never observably without them (`WidgetArena::create`).
+            // Set by `WidgetArena::create` on insert, as the ctor builds its children.
             player_arrow: None,
         }
     }
 }
 
 impl MinimapState {
-    /// The zoom index the client's `get_zoom_index`/`set_zoom` operate on right now.
+    /// The index `GetZoom`/`SetZoom` act on now.
     pub fn active_zoom(&self) -> u8 {
         if self.inside {
             self.inside_zoom
@@ -988,7 +594,7 @@ impl MinimapState {
         }
     }
 
-    /// Write the active index (the `set_zoom` half of the same routing).
+    /// Writes the index the inside flag selects.
     pub fn set_active_zoom(&mut self, zoom: u8) {
         if self.inside {
             self.inside_zoom = zoom;
@@ -998,116 +604,53 @@ impl MinimapState {
     }
 }
 
-/// The client's minimap zoom-level count (`get_zoom_levels` `0x6da9a0` returns the constant 6).
+/// The zoom-level count (`GetZoomLevels`, `0x6da9a0`).
 pub const MINIMAP_ZOOM_LEVELS: u8 = 6;
 
-/// The engine's own minimap mask — the circle `Minimap:SetMaskTexture` replaces. benilla's
-/// renderer has loaded this path since the minimap existed; naming it here is what lets the Lua
-/// setter override it.
+/// The engine's circular minimap mask, which `Minimap:SetMaskTexture` replaces.
 pub const MINIMAP_DEFAULT_MASK: &str = "Textures\\MinimapMask";
 
-/// **Nine `Model` children, built by the `CMinimap` ctor before anything else sees the widget** —
-/// wow-re `ui/scratch/widget-list-bindings.md` §5 / `ui/ui.md`, VERIFIED. The ctor `0x4edbc0`
-/// (TU `Ui\MinimapFrame.cpp`) allocates `CSimpleModel` (`0x76c8e0`) nine times with the Minimap as
-/// parent, in three source-ordered groups whose `__LINE__` arguments give the order directly:
-///
-/// | # | stored at | `__LINE__` | what it is |
-/// |---|---|---|---|
-/// | 1–5 | `[Minimap+0x320 + 4k]` | 1424 | the rim/party arrows (`minimapArrowModel`) |
-/// | 6–8 | `[Minimap+0x314 + 4k]` | 1438 | the three POI direction arrows (`minimapArrowModel`) |
-/// | 9 | `[Minimap+0x338]` | 1450 | **the player arrow** (`minimapPlayerModel`) |
-///
-/// **Why the engine core carries them at all**, when the app draws every one of these arrows itself
-/// from its own art (`benilla-app`'s `minimap::blips`): because they are *structure the Lua API can
-/// see*, and two of the most-installed 1.12 addons read it. `Questie`'s `QuestieArrow.lua`
-/// `GetPlayerFacing()` is `({Minimap:GetChildren()})[9]:GetFacing()`, and pfQuest's
-/// `compat/client.lua` does the same — the ctor runs before the XML `<Frames>` descent
-/// (`0x6ee408` before `0x6ee4ea`) and both linkers append at the tail, so on a stock client the
-/// tuple is these nine then `Minimap.xml`'s six, and index 9 is the arrow. Without them that read
-/// is `nil` and the addon dies calling a method on it.
-///
-/// The count is fixed and unconditional: an unloadable model file only skips the *file* assignment
-/// (`0x4ee286` returns early), never the child.
+/// The `Model` children the `CMinimap` ctor (`0x4edbc0`) makes before its XML ones, even for an
+/// unloadable file (`0x4ee286`): five rim and party arrows, three POI arrows, the player arrow;
+/// addons (Questie, pfQuest) read `({Minimap:GetChildren()})[9]` as the player arrow.
 pub const MINIMAP_ENGINE_CHILDREN: usize = 9;
 
-/// The engine default for `<Minimap minimapArrowModel=…>` — the string at `0x84c768`, applied by
-/// `0x4ee170` to engine children 1–8. (`Minimap.xml:97` sets the attribute explicitly, in the `.mdl`
-/// spelling; the loader rewrites the extension either way.)
+/// The default `minimapArrowModel` (`0x84c768`), applied to engine children 1 to 8 (`0x4ee170`).
 pub const MINIMAP_DEFAULT_ARROW_MODEL: &str = "Interface\\Minimap\\Rotating-MinimapArrow.mdx";
 
-/// The engine default for `<Minimap minimapPlayerModel=…>` — the string at `0x8453c0`, applied by
-/// `0x4ee260` to engine child 9 **alone**.
+/// The default `minimapPlayerModel` (`0x8453c0`), applied to engine child 9 alone (`0x4ee260`).
 pub const MINIMAP_DEFAULT_PLAYER_MODEL: &str = "Interface\\Minimap\\MinimapArrow.mdx";
 
-/// A `CSimpleScrollFrame`'s runtime state: the frame whose anchors are overridden to track the
-/// scroll offset ([`crate::script::UiScript::resolve`]'s scroll-child override), and the current
-/// scroll position on each axis. `SetVerticalScroll` stores the offset VERBATIM — the reference's
-/// `0x786db0` never reads the range (decision 2017) — and the ranges are always computed live from
-/// the resolved rects (never cached here), so this struct carries only the three members the
-/// client's `SetScrollChild`/`SetHorizontalScroll`/`SetVerticalScroll` actually set (`[+0x318]`,
-/// `[+0x324]`, `[+0x328]`).
+/// A `CSimpleScrollFrame`'s members (`+0x318`/`+0x324`/`+0x328`); the ranges are measured live.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ScrollFrameState {
-    /// The scroll child (`SetScrollChild`) — the one frame whose content pans within this frame's
-    /// rect. `None` = no child (nothing to clip or offset).
+    /// `SetScrollChild`'s frame, which pans within this frame's rect.
     pub child: Option<FrameHandle>,
-    /// The horizontal scroll offset in px (`SetHorizontalScroll`), unclamped — the reference's
-    /// `[+0x324]`, whose setter `0x786d30` is the byte-clone of the vertical one's `0x786db0`.
-    ///
-    /// **The sign is the mirror of the vertical one below, and that is the reference's, not a
-    /// slip.** `0x787100` re-anchors the child as
-    /// `SetPoint(TOPLEFT, self, TOPLEFT, +[+0x324], +[+0x328])` — both offsets handed over raw,
-    /// neither negated (wow-re `scrollframe-offset-and-range-law.md` §2.3/§6.2). x grows right, so
-    /// a POSITIVE horizontal offset pushes the child right and reveals nothing new; scrolling
-    /// right takes a NEGATIVE one, where scrolling down takes a positive vertical.
-    /// `aux-addon/tabs/search/filter.lua:315-322` corroborates it from the caller's side: it
-    /// bounds x into `[min(0, frameWidth - contentWidth - 10), 0]` and y into
-    /// `[0, contentHeight - frameHeight]`.
+    /// `SetHorizontalScroll`'s offset in px, unclamped; `0x787100` anchors the child at
+    /// `(+horizontal, +vertical)`, so scrolling right takes a negative offset, down a positive.
     pub horizontal: f32,
-    /// The vertical scroll offset in px (`SetVerticalScroll`), unclamped — the reference's
-    /// `[+0x328]`. XML y-positive-up: a positive offset lifts the child
-    /// (`child.top = scrollframe.top + vertical`), bringing content below the fold into view. The
-    /// scroll bar's `[min, max]` is what keeps it inside the range — in FrameXML, never here.
+    /// `SetVerticalScroll`'s offset in px (`0x786db0`), unclamped: a positive one lifts the child
+    /// to show what is below; the FrameXML scroll bar's range keeps it in bounds.
     pub vertical: f32,
 }
 
-/// The face/size/flags one `Button:SetFont(file, height [, flags])` call writes.
-///
-/// **One record, not three, and that is the faithful shape here rather than a shortcut.** The
-/// client's Button embeds three `CSimpleFont` sub-objects — normal `+0x33c`, disabled `+0x434`,
-/// highlight `+0x3b8` — and `SetFont` (`0x780880`) retunes **all three with the same values**
-/// (`GetFont` reads only the normal one). Nothing in the 1.12 Lua surface can set them apart: a
-/// Button has `SetFont` and the `*FontObject` triple, and the latter changes which object each
-/// state *inherits*, never its local face. So three identical copies could only ever diverge by
-/// our own bug (wow-re `system/ui/scratch/widget-api-batch-benilla.md` Q8).
+/// `Button:SetFont`'s record, one for the client's three embedded fonts (`+0x33c`, `+0x434`,
+/// `+0x3b8`), since `SetFont` (`0x780880`) sets all three alike and no Lua call parts them.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ButtonFont {
-    /// The TTF path (`"Fonts\\FRIZQT__.TTF"`).
     pub path: String,
     /// The font height in logical px.
     pub height: f32,
-    /// The **normalized** OUTLINETYPE token — `""`, `"OUTLINE"` or `"THICKOUTLINE"` — so
-    /// `GetFont`'s third return reads like the FontString/Font-object one rather than echoing
-    /// whatever the addon spelled. Kept as a string, not `script::Outline`, because this module is
-    /// the arena's vocabulary and deliberately names no script type.
-    ///
-    /// **An omitted `flags` argument clears the outline** (this is `""`), which is the reading the
-    /// batch does not pin: it records arg4 as parsed against `{OUTLINE, THICKOUTLINE, MONOCHROME}`
-    /// and says nothing about its absence. A `lua_tostring` on a missing argument yields no flags,
-    /// so "absent means none" is what the shared impl most plausibly does, and it is the reading
-    /// an addon setting a plain face expects.
+    /// The normalized outline, `""`, `"OUTLINE"` or `"THICKOUTLINE"`, as `GetFont` answers it; an
+    /// omitted `flags` clears it, where the reference's handling is untraced.
     pub flags: String,
 }
 
-/// The client's button STATE INDEX — `[CSimpleButton+0x328]`, the one variable `SetState
-/// 0x779790` writes and `IsEnabled 0x7800b0` / `GetButtonState 0x780180` read back.
-///
-/// The client numbers them 0 DISABLED / 1 NORMAL / 2 PUSHED, which is also the index into its
-/// state-texture array (`[this + state*4 + 0x4b8]`); we name the variants instead, because
-/// nothing here indexes.
+/// A button's state, `[CSimpleButton+0x328]`: 0 DISABLED, 1 NORMAL, 2 PUSHED, also the index into
+/// its texture array `+0x4b8`. Past the ctor, `SetState` (`0x779790`) is its only writer.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum ButtonVisualState {
-    /// `Disable()` — the button fires no clicks and draws from the Disabled slot.
+    /// `Disable()`: the button fires no clicks and draws from the Disabled slot.
     Disabled,
     /// The resting state a button is born in.
     #[default]
@@ -1116,139 +659,63 @@ pub enum ButtonVisualState {
     Pushed,
 }
 
-/// A Button's state model: which of the state textures draws is a **latched** consequence of the
-/// interaction state, not a pure function of it — the client's texture array `+0x4b8` plus its
-/// currently-shown pointer `+0x4c4`, which moves only on a transition into a state that *has* a
-/// texture ([`Self::settle`]). The regions all exist in the arena; [`Self::region_visible`] reads
-/// the pointer at extract time.
+/// A button's state. The drawn state texture is latched, not derived: the shown pointer
+/// (`+0x4c4`) moves only on a transition into a state that has a texture ([`Self::set_state`]).
 #[derive(Clone, Debug, PartialEq)]
 pub struct ButtonState {
-    /// **`[CSimpleButton+0x32c]` — the LOCK**, written unconditionally by every
-    /// `SetButtonState(state, locked) 0x779790` and read by exactly four guards, all of them the
-    /// engine's own edges. While it is set the button **ignores the mouse press/release
-    /// transitions entirely**; while it is clear, any engine edge that fires re-writes it to
-    /// `false`, because every engine call site passes `locked = 0` (wow-re
-    /// `system/ui/scratch/button-state-edge-set.md`, VERIFIED — including `Enable`/`Disable`,
-    /// which therefore CLEAR a lock a script set).
-    ///
-    /// `MainMenuBarMicroButtons.lua` is the reference's own customer: `SetButtonState("PUSHED", 1)`
-    /// when a panel opens, `SetButtonState("NORMAL")` — the flag defaulting to 0 — when it closes.
-    /// The ordinary action bars pass no flag at all, and Tablet-2.0 pushes its clicked rows
-    /// unlocked and never un-pushes them, which is the whole reason this field exists (2134).
+    /// The lock (`+0x32c`) of `SetButtonState(state, locked)`: while set, the hide, press, release
+    /// and drag edges skip the button, and an `Enable`/`Disable` that runs (`0x779160`) clears it.
     pub locked: bool,
-    /// [`FrameKind::LootButton`]'s own field — `CLootButton +0x4dc`, the **0-based** loot slot
-    /// this row takes when clicked. `None` until `SetSlot` writes it (the ctor's zero is a slot
-    /// id in the reference; ours is `None`, so a row that was never given one takes nothing
-    /// rather than silently taking slot 0). Unused on every other button kind, the same way
-    /// [`Self::checked`] below is unused on a plain Button — the client's subclasses add their one
-    /// field the same way, and our flat state mirrors that rather than growing a variant.
+    /// [`FrameKind::LootButton`]'s 0-based slot (`+0x4dc`) from `SetSlot`. Deviation: `None`
+    /// until then, not the ctor's 0, so that an unset row takes nothing rather than slot 0.
     pub loot_slot: Option<u32>,
-    /// CheckButton's checked flag (`+0x4dc`; XML `checked`). Unused on a plain Button.
+    /// A CheckButton's checked flag (`+0x4dc`, XML `checked`).
     pub checked: bool,
     /// `<NormalTexture>`/`SetNormalTexture` (`+0x4bc`).
     pub normal: Option<RegionHandle>,
-    /// `<PushedTexture>` (`+0x4c0`) — taken on the press transition. A button with none keeps
-    /// whatever it was showing ([`Self::set_state`]), which is not a fallback but the absence of
-    /// one.
+    /// `<PushedTexture>` (`+0x4c0`); a button with none keeps what it showed ([`Self::set_state`]).
     pub pushed: Option<RegionHandle>,
     /// `<DisabledTexture>` (`+0x4b8`).
     pub disabled: Option<RegionHandle>,
-    /// `<HighlightTexture>` (`+0x4c8`) — additive over the current state texture while hovered
-    /// (it lives in the HIGHLIGHT draw layer, above the others, not instead of them).
+    /// `<HighlightTexture>` (`+0x4c8`), drawn over the state texture while hovered.
     pub highlight: Option<RegionHandle>,
-    /// CheckButton `<CheckedTexture>` (`+0x4e0`) — additive while checked. A SEPARATE array from
-    /// the state textures, with its own rule (`0x7854c0`): hide both, then show
-    /// [`Self::disabled_checked`] if checked ∧ it exists ∧ the state is DISABLED, else this one if
-    /// it exists, else nothing. **The fallback is one-way** — a disabled checked button with no
-    /// DisabledChecked art falls back to this; a checked one never falls the other way.
+    /// `<CheckedTexture>` (`+0x4e0`), drawn while checked; `0x7854c0` shows
+    /// [`Self::disabled_checked`] instead when disabled and it exists.
     pub checked_tex: Option<RegionHandle>,
-    /// CheckButton `<DisabledCheckedTexture>` (`+0x4e4`) — replaces CheckedTexture when disabled.
-    /// The greyed tick a peace-forced faction's At War box wears (B369).
+    /// `<DisabledCheckedTexture>` (`+0x4e4`), which replaces the checked texture when disabled.
     pub disabled_checked: Option<RegionHandle>,
-    /// The `<ButtonText>` fontstring (`+0x338`; `SetText`). Always drawn.
+    /// The `<ButtonText>` fontstring (`+0x338`, `SetText`), always drawn.
     pub text: Option<RegionHandle>,
-    /// `RegisterForClicks`' set (the exact 1.12 API strings, e.g. `"LeftButtonUp"`,
-    /// `"RightButtonDown"`) — which press/release transitions reach `OnClick`. Plain strings, not
-    /// an enum: the API is an open list of `"<Button>Button<Up|Down>"` names and the input path
-    /// only ever needs membership, never to enumerate it. Defaults to the client's own default
-    /// (`{"LeftButtonUp"}` — a left click, on release).
+    /// `RegisterForClicks`' names, the transitions that reach `OnClick`; default `"LeftButtonUp"`.
     pub registered_clicks: HashSet<String>,
-    /// Per-state label font-object NAMES (`<NormalFont inherits=>`/`SetTextFontObject` and the
-    /// Highlight/Disabled pair): at extract, the ButtonText re-points to the current state's font
-    /// object — the client's per-state CFontString font swap (UIPanelButtonTemplate's gold
-    /// normal / white highlight / gray disabled label). `None` = keep the label's own paint.
+    /// The normal state's label font object (`<NormalFont>`); `None` keeps the label's own paint.
     pub normal_font: Option<String>,
-    /// See [`ButtonState::normal_font`] — the highlighted state (hovered **or**
-    /// [`locked_highlight`](ButtonState::locked_highlight)). `None` means the button has no
-    /// highlight instance at all and the label stays on the normal one, colour included.
+    /// [`ButtonState::normal_font`] when highlighted; `None` keeps the normal one, colour and all.
     pub highlight_font: Option<String>,
-    /// See [`ButtonState::normal_font`] — the disabled state.
+    /// [`ButtonState::normal_font`] for the disabled state.
     pub disabled_font: Option<String>,
-    /// The NORMAL embedded font's own justify — `<NormalFont justifyH=>` (or the `<NormalText>`
-    /// alias), a **local** write on the instance at `+0x33c` (`CSimpleButton::LoadXML 0x7788c0`
-    /// → the `<Font>` loader `0x783c30`), severed from whatever object the instance inherits and
-    /// surviving a later `SetTextFontObject`. `None` = the instance shows its object's justify.
-    ///
-    /// Two readers, and the first is the one that made this a field of the *button*: the label
-    /// adopter `CSimpleButton::SetFontString 0x778d20` — the tail `SetText`'s lazy creation and
-    /// the Lua adopter share — anchors an unanchored label to the button by exactly this word
-    /// (`[button+0x390]`: LEFT→LEFT, RIGHT→RIGHT, else CENTER), which is how a row of the
-    /// reference's `UIMenuButtonTemplate` (no `<ButtonText>`, `SetText` from Lua) hugs its left
-    /// edge. The second is the label's paint and query surface, reached through the live link
-    /// (`script::button::apply_normal_font`, `script::extract`). Decision 1996.
+    /// `<NormalFont justifyH=>`, local to the normal font (`+0x33c`) and kept over
+    /// `SetTextFontObject`; `SetFontString` (`0x778d20`) anchors an unanchored label by it.
     pub normal_justify_h: Option<crate::script::JustifyH>,
-    /// See [`ButtonState::normal_justify_h`] — `<HighlightFont justifyH=>`, the highlight instance
-    /// (`+0x3b8`). Paint only: the adopter reads the normal instance alone.
+    /// `<HighlightFont justifyH=>` (`+0x3b8`); paint only, the label anchor reads the normal one.
     pub highlight_justify_h: Option<crate::script::JustifyH>,
-    /// See [`ButtonState::normal_justify_h`] — `<DisabledFont justifyH=>`, the disabled instance
-    /// (`+0x434`). Paint only.
+    /// `<DisabledFont justifyH=>` (`+0x434`); paint only.
     pub disabled_justify_h: Option<crate::script::JustifyH>,
-    /// `Button:SetFont(file, height [, flags])` — the button's own face/size/flags, set on the
-    /// embedded font objects themselves rather than on any font object they inherit. See
-    /// [`ButtonFont`] for why one record covers the client's three.
-    ///
-    /// It lives here, not on the ButtonText's [`crate::script::RegionData`], because the reference
-    /// **never dereferences the label pointer** (`+0x338`) in `SetFont`/`GetFont`: styling a
-    /// `CreateFrame("Button")` with no `<ButtonText>` is a silent no-op there, and writing to a
-    /// label would have meant lazily creating one — observable through `GetFontString()`, which
-    /// must stay nil. `extract` applies it to the label whenever there is one, which also makes a
-    /// later `SetText` (which *does* create the FontString) pick the style up for free.
+    /// `Button:SetFont`'s face, kept on the button since `SetFont` never touches the label
+    /// (`+0x338`) and so creates none; extract applies it to whatever label there is.
     pub font: Option<ButtonFont>,
-    /// Per-state label COLOR overrides (`Button:SetTextColor` and the Highlight/Disabled pair):
-    /// when the matching state is current, extract repaints the ButtonText with this color over
-    /// the state font object's own paint — the dropdown kit's rows lean on all three
-    /// (`info.textR/G/B`, isTitle's NORMAL-yellow and notClickable's HIGHLIGHT-white recolors of
-    /// a disabled row). `None` = the state font's paint.
+    /// `SetTextColor`'s label colour for the normal state, painted over the state font's own.
     pub normal_color: Option<[f32; 4]>,
-    /// See [`ButtonState::normal_color`] — the highlighted state. It does **not** fall back to
-    /// `normal_color`: each state is its own font instance, so a `SetTextColor` cannot reach the
-    /// highlighted label (which is why `UIDropDownMenu.lua` always pairs the two setters).
+    /// [`ButtonState::normal_color`] for the highlighted state, which never falls back to it.
     pub highlight_color: Option<[f32; 4]>,
-    /// See [`ButtonState::normal_color`] — the disabled state.
+    /// [`ButtonState::normal_color`] for the disabled state.
     pub disabled_color: Option<[f32; 4]>,
-    /// `LockHighlight()` — the button reads as highlighted regardless of hover until
-    /// `UnlockHighlight()` (ref `CButton::LockHighlight`; the dropdown kit keeps a checked row's
-    /// highlight lit). That covers BOTH halves of the highlighted look: the HighlightTexture
-    /// ([`Self::region_visible`]) and the label's font instance (`script::extract`). The list
-    /// windows lean on the second alone — a tradeskill/craft/trainer recipe row blanks its
-    /// highlight texture to `""` and locks the selected row anyway, purely for the white label.
+    /// `LockHighlight()`: highlighted regardless of hover, both the texture and the label font.
     pub locked_highlight: bool,
-    /// The client's **currently-shown state texture** — the pointer at `+0x4c4`. Private, and the
-    /// only thing [`Self::region_visible`] consults for the three state textures: it is written by
-    /// [`Self::set_state`] and [`Self::set_state_slot`] alone, which is what makes the transition
-    /// rule un-bypassable.
+    /// The shown state texture (`+0x4c4`), written only by `set_state` and `set_state_slot`.
     shown: Option<RegionHandle>,
-    /// **`[CSimpleButton+0x328]` — THE state**, and the client really does have only this one
-    /// variable: `SetButtonState 0x779790` is its only writer past the ctor, and `IsEnabled
-    /// 0x7800b0`, `GetButtonState 0x780180` and every texture decision read it back.
-    ///
-    /// Private, because it is a **latch driven by edges**, not a value derived from inputs. That
-    /// distinction is the whole of decision 2134: benilla used to carry `enabled` and
-    /// `pushed_state` beside it and re-derive `state` from them plus the live mouse
-    /// (`(held && hovered) || pushed_state`), and the reference's press state **has no hover term
-    /// at all** — the enter and leave notifies (`0x779490`/`0x7794e0`) read `[+0x328]` only as a
-    /// DISABLED guard and never write it. A derived model un-presses when the cursor leaves a held
-    /// button and re-presses when it comes back; the reference does neither.
+    /// The state (`+0x328`), a latch moved only by edges: the enter and leave notifies
+    /// (`0x779490`/`0x7794e0`) never write it, so leaving a held button does not un-press it.
     state: ButtonVisualState,
 }
 
@@ -1284,7 +751,7 @@ impl Default for ButtonState {
 }
 
 impl ButtonState {
-    /// The slot a state draws from — the client's `[this + state*4 + 0x4b8]`.
+    /// The slot a state draws from, the client's `[this + state*4 + 0x4b8]`.
     fn state_slot(&self, state: ButtonVisualState) -> Option<RegionHandle> {
         match state {
             ButtonVisualState::Disabled => self.disabled,
@@ -1293,40 +760,9 @@ impl ButtonState {
         }
     }
 
-    /// **`CSimpleButton::SetState 0x779790`** — the transition, and the whole of why the shown
-    /// texture is state rather than a lookup.
-    ///
-    /// Both halves of the swap test the SAME dword — the new state's own slot: `0x7797b5` loads
-    /// `[esi + 4*edi + 0x4b8]` and `0x7797be` skips the hide when it is null; `0x7797d9`/`0x7797e2`
-    /// skips the show on the same value. The state itself is written regardless (`0x779801`). So a
-    /// transition into a state with no texture of its own **changes nothing** — the
-    /// previously-shown texture stays up, and there is no fallback path to Normal anywhere in the
-    /// function. The equality early-out sits at `0x7797a3`/`0x7797a9`, *after* the unconditional
-    /// `[+0x32c] = locked` store and *before* every texture step. wow-re
-    /// `system/ui/scratch/button-disabled-state-texture-law.md`, VERIFIED.
-    ///
-    /// **A button is NORMAL before its art is loaded, which is what makes the rule bite.** The
-    /// `CSimpleButton` ctor `0x7786a0` writes `[+0x328] = 0` and `[+0x4c4] = 0`, then ends
-    /// `push 1; call 0x779160` → `[vtbl+0x9c]` = this function with NORMAL. Only then does
-    /// `LoadXML` install the art, each child through the `0x778fd0` setter family
-    /// ([`Self::set_state_slot`]) — `<NormalTexture>` at `0x77890e` with idx 1, which matches, so
-    /// it is shown on the spot. Every button in the family therefore reaches its first `Disable()`
-    /// already wearing its normal art.
-    ///
-    /// Three things the reference draws out of that one rule, which a pure `state → slot`
-    /// resolution cannot:
-    ///
-    /// - **A press with no PushedTexture keeps its normal art.** (Our old resolution special-cased
-    ///   this as `pushed.or(normal)` — the fallback was never a rule, it was this mechanism seen
-    ///   from one side.)
-    /// - **`Disable()` on a button with no DisabledTexture keeps its normal art.** This is B369:
-    ///   `ReputationDetailAtWarCheckBox` has a `<NormalTexture>` and no `<DisabledTexture>`, and
-    ///   `ReputationFrame_Update` `Disable()`s it for a faction whose war flag cannot be toggled —
-    ///   in the reference the box stays on screen (greyed label, still a box); resolving the shown
-    ///   texture as a pure function of the state made it vanish, leaving a bare label.
-    ///   `Disable 0x77ffd0` reaches here through `0x78009a call [vtbl+0x90](0)` → `0x779160`.
-    /// - **So does an empty spellbook slot's `UI-Quickslot2` ring**, which is the same shape and
-    ///   was the case decision 0227 got backwards — see 2011.
+    /// `SetState` (`0x779790`): entering a state with no texture keeps the shown one
+    /// (`0x7797be`/`0x7797e2`). A button is NORMAL before `LoadXML` adds its art (ctor
+    /// `0x7786a0`), so a press or `Disable()` without its own texture keeps the normal art.
     fn set_state(&mut self, new: ButtonVisualState) {
         if new == self.state {
             return;
@@ -1337,48 +773,28 @@ impl ButtonState {
         }
     }
 
-    /// **`CSimpleButton::SetButtonState(state, locked) 0x779790` — the ONE writer**, and the door
-    /// every edge below goes through.
-    ///
-    /// `0x77979d mov [this+0x32c], locked` is **unconditional**, before and independent of the
-    /// state's own equality early-out at `0x7797a3` — so a `SetButtonState("NORMAL", 1)` on a
-    /// button that is already NORMAL still arms the lock, and every engine edge (all of which pass
-    /// `locked = 0`) disarms it even when the state does not move.
+    /// `SetButtonState(state, locked)` (`0x779790`), the one writer: the lock is stored before the
+    /// equal-state early-out (`0x77979d`), so it is set or cleared even when the state holds.
     pub fn set_button_state(&mut self, new: ButtonVisualState, locked: bool) {
         self.locked = locked;
         self.set_state(new);
     }
 
-    /// `IsEnabled 0x7800b0` — which reads `[+0x328]` and nothing else, because there is no
-    /// separate enabled flag in the class.
+    /// `IsEnabled` (`0x7800b0`): the state alone; the class has no enabled flag.
     pub fn enabled(&self) -> bool {
         self.state != ButtonVisualState::Disabled
     }
 
-    /// `GetButtonState 0x780180` — the same one variable, un-derived. A button held down by the
-    /// mouse answers `"PUSHED"` because the press *wrote* it, not because a getter re-checks the
-    /// cursor (which is what ours used to do, and why it could disagree with the art).
+    /// `GetButtonState` (`0x780180`): the latched state, never re-derived from the cursor.
     pub fn button_state(&self) -> ButtonVisualState {
         self.state
     }
 
-    // ── The engine's edges (wow-re `scratch/button-state-edge-set.md`, VERIFIED) ─────────────
-    //
-    // Seven call sites of `0x779790` exist image-wide; six are below and the seventh is the Lua
-    // binding ([`Self::set_button_state`]). Every one of the six passes `locked = 0`. There is
-    // **no enter edge and no leave edge** — `0x779490`/`0x7794e0` re-apply the label style and
-    // never touch `[+0x328]` — which is the correction 2134 is built on.
+    // ── The engine's edges ──
+    // Six of `0x779790`'s seven call sites, all passing `locked = 0`; the seventh is Lua's.
 
-    /// **`SetEnabled(bool) 0x779160`** (vtable `+0x90`) — `Enable 0x77fef0` / `Disable 0x77ffd0`.
-    ///
-    /// Two asymmetries the byte read settles, both early-outs on the state it already has:
-    /// `Enable()` on a button that is not DISABLED does **nothing at all** (`0x779175`) — so it
-    /// does not un-push a PUSHED button and does not clear a lock; `Disable()` on an
-    /// already-DISABLED one likewise (`0x77919c`). When it does run it passes `locked = 0`
-    /// (`0x779179`/`0x7791c2`), so enabling or disabling a script-locked button **unlocks** it.
-    ///
-    /// Returns whether the transition ran — the caller owes the HIGHLIGHT draw-layer half only
-    /// then (`script::button::set_enabled`).
+    /// `SetEnabled` (`0x779160`): a no-op if nothing changes (`0x779175`/`0x77919c`), so enabling a
+    /// pushed button neither un-pushes nor unlocks it; returns whether it ran.
     pub fn set_enabled(&mut self, on: bool) -> bool {
         if on == self.enabled() {
             return false;
@@ -1394,72 +810,40 @@ impl ButtonState {
         true
     }
 
-    /// **The hide edge** — `CSimpleButton`'s `+0x34` override `0x7791e0`, which un-presses and then
-    /// tail-jumps the base notify so the frame's `<OnHide>` still fires. Guard at `0x7791ed`:
-    /// `state != DISABLED && locked == 0`.
+    /// The hide edge (`0x7791e0`): an unlocked, enabled button goes NORMAL; `<OnHide>` still fires.
     pub fn on_hide(&mut self) {
         if self.state != ButtonVisualState::Disabled && !self.locked {
             self.set_button_state(ButtonVisualState::Normal, false);
         }
     }
 
-    /// **The press edge** — the mouse-down dispatcher `0x779210`'s `0x7792b1`
-    /// `SetButtonState(PUSHED, 0)`, guarded at `0x779295` on `locked == 0 && state != DISABLED`.
-    /// Unconditional past the registration and hit gates above it, which is why a right-click on a
-    /// slot that registered `RightButtonUp` lights up even when the click does nothing.
+    /// The press edge (`0x779210`), past the registration and hit gates, so a registered click
+    /// pushes the button even when the click itself does nothing.
     pub fn on_mouse_down(&mut self) {
         if !self.locked && self.state != ButtonVisualState::Disabled {
             self.set_button_state(ButtonVisualState::Pushed, false);
         }
     }
 
-    /// **The release edge** — the mouse-up dispatcher `0x7792d0`'s `0x7793de`
-    /// `SetButtonState(NORMAL, 0)`, guarded at `0x7793c2` on `locked == 0` and at `0x779307` on the
-    /// state actually being PUSHED.
-    ///
-    /// **It does not ask where the cursor is.** A press held over a button and released anywhere
-    /// on screen un-presses it; the release is the edge, the hover is not. (The caller skips this
-    /// when the base finalized a drag — `0x7792df`'s `0x76c040` test — which is our
-    /// `cursor::take_drag(..).started`.)
-    ///
-    /// This is the edge that fixes Tablet-2.0: its rows call `SetButtonState("PUSHED")` with no
-    /// lock argument and never call `SetButtonState("NORMAL")` at all, because in the reference
-    /// this release does it for them.
+    /// The release edge (`0x7792d0`): a pushed, unlocked button goes NORMAL wherever the cursor
+    /// is, even one Lua pushed. The caller skips it when the release ends a drag (`0x7792df`).
     pub fn on_mouse_up(&mut self) {
         if !self.locked && self.state == ButtonVisualState::Pushed {
             self.set_button_state(ButtonVisualState::Normal, false);
         }
     }
 
-    /// **The drag-start edge** — `+0x74`'s override `0x7793f0`, `0x779410`
-    /// `SetButtonState(NORMAL, 0)` under the same `0x779400` guard, before forwarding to the base
-    /// `0x76c1e0` that fires `<OnDragStart>`.
-    ///
-    /// It fires on the drag THRESHOLD crossing (a link-time `0.01` frame units, `0x81c468`), not on
-    /// the rect edge, and only for a frame that called `RegisterForDrag` — so a button you drag off
-    /// un-presses well before the cursor leaves it, and one you merely slide off does not.
+    /// The drag-start edge (`0x7793f0`), before `<OnDragStart>`: it fires at the drag threshold
+    /// (0.01 frame units, `0x81c468`) on a `RegisterForDrag` frame, not at the rect edge.
     pub fn on_drag_start(&mut self) {
         if !self.locked && self.state != ButtonVisualState::Disabled {
             self.set_button_state(ButtonVisualState::Normal, false);
         }
     }
 
-    /// **`SetNormalTexture`/`SetPushedTexture`/`SetDisabledTexture 0x778fd0`** — the slot store,
-    /// plus the conditional push to the shown pointer: `[this+idx*4+0x4b8] = tex`, and `+0x4c4`
-    /// takes it **only when `idx == [this+0x328]`** (the gate at `0x779027`). Setting a state's
-    /// texture while the button is in a *different* state does not display it: a fresh region is
-    /// born hidden (`0x77f695` writes `+0xc4 = 0`), so a non-current slot is installed dark.
-    ///
-    /// This is also how a button's art first reaches the screen at all — see [`Self::set_state`]
-    /// for why LoadXML always finds the button in NORMAL.
-    ///
-    /// **One stated divergence.** When the write DISPLACES an occupant, the reference *destroys*
-    /// it (`0x77900a` calls the old object's `vtbl[0](1)`) and clears `+0x4c4` if that occupant
-    /// was the shown one. Ours never gets there: `script::button::ensure_slot` creates a slot's
-    /// region once and later `SetNormalTexture` calls repaint that same region, so the handle is
-    /// stable and an addon holding `GetNormalTexture()` keeps a live object where the reference
-    /// would have handed it a dead one. Nothing in the corpus reads a state texture across a
-    /// replacement; the object-identity half is not modeled.
+    /// `SetNormalTexture` and kin (`0x778fd0`): stores the slot, shown only if it is the current
+    /// state's (`0x779027`). The reference destroys a displaced texture (`0x77900a`); here the
+    /// region is made once and repainted, so a held `GetNormalTexture()` stays live.
     pub fn set_state_slot(&mut self, state: ButtonVisualState, rh: Option<RegionHandle>) {
         match state {
             ButtonVisualState::Disabled => self.disabled = rh,
@@ -1471,21 +855,15 @@ impl ButtonState {
         }
     }
 
-    /// Whether a region of this button draws. The three state textures answer from the shown
-    /// pointer alone ([`Self::set_state`]) — which is why the press is no longer an argument here:
-    /// it is an *input to the transition*, consumed at [`Self::settle`], not something a paint
-    /// re-derives. `hovered` stays because the Highlight is not a state texture and really does
-    /// track the cursor with no latch of its own. Checked draws additively per its own condition,
-    /// and any region that is not one of these (ButtonText, user regions) always draws.
+    /// Whether a region of this button draws: a state texture only when shown, the highlight
+    /// while hovered or locked, the checked pair by their rule, anything else always.
     pub fn region_visible(&self, rh: RegionHandle, hovered: bool) -> bool {
         let some = Some(rh);
         if some == self.normal || some == self.pushed || some == self.disabled {
             return some == self.shown;
         }
         if some == self.highlight {
-            // No `enabled` term: a disabled button loses its highlight because `Disable()` turns
-            // the whole HIGHLIGHT draw layer off (`script::button::set_enabled`), which extract
-            // applies before it ever reaches here.
+            // No `enabled` term: `Disable()` turns the whole HIGHLIGHT layer off before this.
             return hovered || self.locked_highlight;
         }
         if some == self.checked_tex {
@@ -1498,27 +876,23 @@ impl ButtonState {
     }
 }
 
-/// A StatusBar's value model + its bar-fill region. Zero-initialized like the client's members —
-/// a degenerate range (`max <= min`) draws an empty bar until the data configures it.
+/// A StatusBar's value and fill texture, zero-initialized like the client's members.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct StatusBarState {
-    /// `SetMinMaxValues` low bound (XML `minValue`; the 1.12 loader swaps a reversed pair, RF-28).
+    /// `SetMinMaxValues` low bound (XML `minValue`); the loader swaps a reversed pair (`0x782ef0`).
     pub min: f32,
     /// `SetMinMaxValues` high bound (XML `maxValue`).
     pub max: f32,
     /// The current value (`SetValue`/XML `defaultValue`), clamped into `[min, max]`.
     pub value: f32,
-    /// `true` = VERTICAL (fills bottom-up); `false` = HORIZONTAL (fills left-to-right), the default
-    /// (shared enum table `0x811b00`: HORIZONTAL=0/VERTICAL=1).
+    /// VERTICAL fills bottom-up; HORIZONTAL, the default, left to right (enum `0x811b00`).
     pub vertical: bool,
-    /// The bar-fill texture region (`SetStatusBarTexture`/`<BarTexture>`), created on first set. A
-    /// renderer scales this region's rect by [`Self::fraction`] along the orientation axis.
+    /// The fill texture (`<BarTexture>`), cropped to [`Self::fraction`] along the orientation axis.
     pub bar: Option<RegionHandle>,
 }
 
 impl StatusBarState {
-    /// The fill fraction `(value − min) / (max − min)`, clamped to `[0, 1]`; a degenerate range
-    /// (`max <= min`) is `0.0` (an unconfigured bar draws empty, matching zero-init members).
+    /// The fill fraction `(value − min) / (max − min)` in `[0, 1]`; `0.0` when `max <= min`.
     pub fn fraction(&self) -> f32 {
         if self.max > self.min {
             ((self.value - self.min) / (self.max - self.min)).clamp(0.0, 1.0)
@@ -1528,54 +902,27 @@ impl StatusBarState {
     }
 }
 
-/// A `CSimpleSlider`'s runtime state (RF-28 LoadXML `0x789580`): the value in `[min, max]`, the
-/// value step, orientation, an enabled flag, and the thumb texture the engine positions by the value
-/// fraction along the track. Only the members the documented `SetMinMaxValues`/`SetValue`/
-/// `SetValueStep`/`SetOrientation`/`SetThumbTexture` contract sets — the thumb's *position* is
-/// derived live from the fraction (never cached here), like StatusBar's fill.
-///
-/// **Default orientation is VERTICAL** — the opposite of [`StatusBarState`]'s HORIZONTAL default,
-/// and verified against the real templates, not assumed: `UIPanelScrollBarTemplate` (every
-/// scrollbar) declares no `orientation` and is vertical, while a horizontal slider
-/// (`OptionsSliderTemplate`) must declare `orientation="HORIZONTAL"` (decision 0250). Sliders in the
-/// UI are overwhelmingly scrollbars, so VERTICAL is the ctor default.
+/// A `CSimpleSlider`'s state. The default orientation is VERTICAL, unlike a StatusBar's: the
+/// stock `UIPanelScrollBarTemplate` declares none and is vertical.
 #[derive(Clone, Debug, PartialEq)]
 pub struct SliderState {
-    /// `SetMinMaxValues` low bound (XML `minValue`). Unlike StatusBar, a reversed pair is **not**
-    /// swapped (the Slider LoadXML stores `min` + `max−min` as a range and does no swap, RF-28); the
-    /// value clamp guards a degenerate range instead ([`Self::clamp`]).
+    /// `SetMinMaxValues` low bound (XML `minValue`); a reversed pair is not swapped (`0x789580`).
     pub min: f32,
     /// `SetMinMaxValues` high bound (XML `maxValue`).
     pub max: f32,
-    /// The current value (`SetValue`/XML `defaultValue`), clamped into `[min, max]`. Zero-initialised
-    /// like the client's `+0x320`, and readable through `GetValue` before anything set it.
+    /// The stored value (`+0x320`), zero-initialised and readable before any `SetValue`.
     pub value: f32,
-    /// **Has a range** — the client's `+0x314` bit1, set by `SetMinMaxValues` and never cleared
-    /// (wow-re `slider-mouse-law.md` §3/§6). Until it is set, `SetValue` is a complete no-op: no
-    /// store, no `OnValueChanged`.
+    /// `+0x314` bit 1, set by `SetMinMaxValues` (`0x7898f0`); until then `SetValue` is a no-op.
     pub range_valid: bool,
-    /// **Has a value** — the client's `+0x314` bit2, set by the first successful `SetValue` and
-    /// never cleared. Two things hang off it, both byte-verified in wow-re (`0x789930`,
-    /// `0x7898f0`): the first-ever `SetValue` **always** fires `OnValueChanged`, even when the new
-    /// value equals the zero-init one; and `SetMinMaxValues` re-clamps the held value through
-    /// `SetValue` **only** once a value exists. Before this flag, `SetMinMaxValues` on a fresh
-    /// slider clamped the zero-init value into the new range and fired the handler — which is how
-    /// Atlas's option sliders raised `attempt to index global 'AtlasOptions'` from their own
-    /// `<OnLoad>`, a handler the reference never runs at that point.
+    /// `+0x314` bit 2, set by the first `SetValue`, which always fires `OnValueChanged`;
+    /// `SetMinMaxValues` re-clamps the value only once this is set.
     pub has_value: bool,
-    /// `SetValueStep` (XML `valueStep`) — the client's `[+0x324]`, and **the quantiser every
-    /// stored value passes through**, not merely the arrow keys' stride: `SetValue 0x789930`
-    /// rounds the clamped value onto the `min + n·step` lattice before the change compare, so
-    /// `GetValue` on a stepped slider can only ever answer a lattice point ([`slider_set_value`],
-    /// which is the whole kernel transcribed). A `step` of exactly `0.0` — the ctor default, and
-    /// what every scrollbar template leaves it at — skips the quantiser outright, which is the
-    /// gate that keeps `UIPanelScrollBarTemplate` continuous.
+    /// `SetValueStep` (`+0x324`): every stored value is quantised onto `min + n·step`
+    /// ([`slider_set_value`]); 0, the default the scrollbars keep, skips the quantiser.
     pub step: f32,
-    /// `true` = VERTICAL (the ctor default; value maps along the track's height, min at the top),
-    /// `false` = HORIZONTAL (`orientation`; shared enum `0x811b00` HORIZONTAL=0/VERTICAL=1).
+    /// VERTICAL, the default, puts `min` at the top of the track (enum `0x811b00`).
     pub vertical: bool,
-    /// The thumb texture region (`SetThumbTexture`/`<ThumbTexture>`), created on first set. A
-    /// renderer positions this region's rect at [`Self::fraction`] along the orientation axis.
+    /// The thumb texture (`<ThumbTexture>`), placed at [`Self::fraction`] along the track.
     pub thumb: Option<RegionHandle>,
 }
 
@@ -1594,39 +941,11 @@ impl Default for SliderState {
     }
 }
 
-/// **The slider drag law — the one owner, for every lane.**
-///
-/// Two pure functions, stated on a single axis in *distance from the track's leading edge* (the
-/// end the thumb sits at when the value is `min`). That framing is what makes them lane-neutral:
-/// the Lua widget arena measures y **up** and the Bevy-UI glue screens measure y **down**, and
-/// both reduce to "how far along the track is this", so neither has to restate the arithmetic.
-///
-/// Restating it is exactly what went wrong. The AddOns glue scrollbar shipped with a *decorative*
-/// knob and no drag at all (1297 named the gap; B273's reporter hit it), the char-create glue
-/// scrollbar grew its own accumulated-delta drag that drifts off the cursor, and the engine slider
-/// held the real formula — three surfaces, one widget, no shared line of code. These two functions
-/// are that shared line.
-///
-/// **The law is benilla's, and it diverges from 1.12 deliberately in one place.** wow-re's
-/// `system/ui/scratch/slider-mouse-law.md` (a §5 1v1, VERIFIED off the bytes of `0x789ba0` /
-/// `0x789ca0`) settled `CSimpleSlider`: there is **no thumb hit-test in the class at all** — every
-/// press, track or thumb, warps the value to seat the thumb's CENTER under the cursor and begins
-/// one continuous drag capture, button-agnostic, clamped by SetValue. We take all of that except
-/// the thumb press: ours grabs **offset-preserving**, so the point you grabbed stays under the
-/// finger instead of jumping to the thumb's middle (decision 0992 §6 — kept as the less surprising
-/// feel, and invisible on a reference-sized thumb either way). If that ever flips to byte-faithful,
-/// it flips here, once, for every surface at the same time.
-///
-/// [`slider_grab`] runs on the press, [`slider_fraction`] on the press and on every move after it.
-///
-/// Where a press grabs the thumb: the offset from the thumb's leading edge that stays under the
-/// cursor for the rest of the drag.
-///
-/// `cursor` and `thumb_lead` are distances from the track's leading edge; `thumb_extent` is the
-/// thumb's length along the axis. A press **on** the thumb keeps its grabbed point (0992 §6); a
-/// press **off** it — anywhere on the track — grabs the thumb by its center, which is what makes
-/// the value warp under the cursor and the drag continue as one gesture (1.12's whole law, and
-/// 0989's directed requirement, which converged with it).
+/// Where a press grabs the thumb: the offset from its leading edge that stays under the cursor,
+/// with distances from the track's leading edge so every UI surface shares it. Off the thumb it
+/// is the center, warping the value under the cursor. Deviation: on the thumb it is the grabbed
+/// point, where `CSimpleSlider` (`0x789ba0`/`0x789ca0`) always centers it, because that feels
+/// less surprising and a stock-sized thumb hides the difference.
 pub fn slider_grab(cursor: f32, thumb_lead: f32, thumb_extent: f32) -> f32 {
     if cursor >= thumb_lead && cursor <= thumb_lead + thumb_extent {
         cursor - thumb_lead
@@ -1635,13 +954,8 @@ pub fn slider_grab(cursor: f32, thumb_lead: f32, thumb_extent: f32) -> f32 {
     }
 }
 
-/// Cursor → fraction of travel, absolute and drift-free: the thumb's leading edge goes to
-/// `cursor − grab`, and that lands at `fraction × (track_extent − thumb_extent)`.
-///
-/// `None` when the travel is zero or negative — a thumb as long as its track has nowhere to go, so
-/// there is no value to compute and the caller must leave the slider alone rather than divide by
-/// zero. Otherwise clamped to `[0, 1]`: dragging past either end pins there, exactly as the
-/// client's own out-of-span presses pin through SetValue's clamp.
+/// The fraction of travel that puts the thumb's leading edge at `cursor − grab`, clamped to
+/// `[0, 1]` as `SetValue` clamps; `None` when the thumb fills the track.
 pub fn slider_fraction(
     cursor: f32,
     grab: f32,
@@ -1652,47 +966,16 @@ pub fn slider_fraction(
     (travel > 0.0).then(|| ((cursor - grab) / travel).clamp(0.0, 1.0))
 }
 
-/// **`CSimpleSlider::SetValue`'s arithmetic kernel — `0x789930`, clamp then quantise.**
-///
-/// The value a `SetValue(v)` actually stores, given the widget's range fields as the client holds
-/// them: `min` = `[+0x318]`, `span` = `[+0x31c]` (the client keeps the *span*, not the max — the
-/// range setter `0x7898f0` stores `end − start` and `0x789a60` re-derives `max = span + min`), and
-/// `step` = `[+0x324]`.
-///
-/// Transcribed op-for-op from wow-re's bit-exact primitive `glue_789930_set_value`
-/// (`crates/ui/src/glue_geom_789.rs`, difftest `glue_geom_789.rs::glue_789930_set_value`,
-/// ledger `PRIMITIVE:glue_789930_set_value`, VERIFIED), whose own doc reads the emitted jccs:
-///
-/// 1. **clamp-low** (`0x789947`..`0x78995f`) — `fld min; fcomp v; test ah,0x41; jne`: `max(min, v)`,
-///    with an unordered compare (NaN) taking the `v` arm.
-/// 2. **`bound = span + min`** (`0x789962`/`0x789968`), spilled to the f32 slot `[ebp-4]`.
-/// 3. **clamp-high** (`0x78996e`..`0x78999c`) — `hi = bound` *reloaded as f32* iff `bound < lo`
-///    ordered-strict; otherwise `hi` is the clamp-low again. Net: `clamp(v, min, bound)`, except
-///    that a **degenerate range pins to `bound`, not to `min`** — which is the one place this
-///    replaced an assumption, our old `v.clamp(min, max.max(min))` having pinned the other way.
-/// 4. **quantise** (`0x78999c`..`0x789a06`), skipped entirely when `step == 0.0`:
-///    `diff = hi − min`, `halfstep = step · 0.5`, then **round-half-away-from-zero** —
-///    `(diff + halfstep) / step` when `diff > 0` ordered, `(diff − halfstep) / step` otherwise
-///    (`≤ 0` and NaN both take the round-down arm) — truncated toward zero by `__ftol`, and
-///    `hi = n · step + min`.
-///
-/// Two consequences worth stating because they look like bugs and are not:
-///
-/// * **The quantised value is NOT re-clamped.** With a range that is not a whole number of steps,
-///   the top of the travel rounds *past* `max` by up to half a step. Every stepped slider the
-///   reference ships is an exact multiple (`FauxScrollFrame_Update` builds its range as
-///   `(numItems − numToDisplay) · valueStep`; the option sliders are all 10/20/100 steps), so the
-///   overshoot is unreachable there — but an addon's odd range really does produce it.
-/// * **The lattice is anchored at `min`, not at zero**, so a slider over `[0.25, 1.0]` stepping by
-///   `0.1` settles on `0.25, 0.35, …`, never on `0.3`.
-///
-/// The f64 intermediates are the x87 register stack at PC_53, and the two `as f32` narrowings are
-/// its two `fst`/`fstp` spills — not an approximation of them.
+/// `CSimpleSlider::SetValue`'s arithmetic (`0x789930`), op for op. The client holds the range as
+/// `min` and `span` (`0x7898f0` stores `end − start`). Clamp into `[min, span + min]`, a
+/// degenerate range pinning to `span + min`; then, unless `step` is 0, round half away from zero
+/// onto the `min + n·step` lattice. The result is not re-clamped, so an uneven range can overshoot
+/// `max` by up to half a step. The f64 intermediates are the x87 registers, each `as f32` a spill.
 pub fn slider_set_value(v: f32, min: f32, span: f32, step: f32) -> f32 {
     let minv = f64::from(min);
     let vv = f64::from(v);
 
-    // clamp-low: `fcomp(min, v)` falls through to `min` only on `min > v` ordered-strict.
+    // Clamp low: `fcomp(min, v)` takes `min` only on `min > v` ordered, so a NaN `v` passes.
     let clamp_low = |v: f64| {
         if matches!(minv.partial_cmp(&v), Some(core::cmp::Ordering::Greater)) {
             minv
@@ -1702,10 +985,10 @@ pub fn slider_set_value(v: f32, min: f32, span: f32, step: f32) -> f32 {
     };
     let lo = clamp_low(vv);
 
-    // `bound = span + min`, live, and spilled to f32 at `[ebp-4]`.
+    // `bound = span + min`, spilled to f32 at `[ebp-4]`.
     let bound = f64::from(span) + minv;
     let mut hi = if matches!(bound.partial_cmp(&lo), Some(core::cmp::Ordering::Less)) {
-        f64::from(bound as f32) // `fld [ebp-4]` — the f32 reload, not the live value
+        f64::from(bound as f32) // `fld [ebp-4]`: the f32 reload, not the live value
     } else {
         clamp_low(vv)
     };
@@ -1727,8 +1010,7 @@ pub fn slider_set_value(v: f32, min: f32, span: f32, step: f32) -> f32 {
 }
 
 impl SliderState {
-    /// The value fraction `(value − min) / (max − min)`, clamped to `[0, 1]`; a degenerate range
-    /// (`max <= min`, an unscrollable slider) is `0.0` — the thumb sits at the track's start.
+    /// The value fraction in `[0, 1]`; `0.0` when `max <= min`, the thumb at the track's start.
     pub fn fraction(&self) -> f32 {
         if self.max > self.min {
             ((self.value - self.min) / (self.max - self.min)).clamp(0.0, 1.0)
@@ -1737,25 +1019,9 @@ impl SliderState {
         }
     }
 
-    /// `SetValue` (`0x789930`): clamp **and quantise** `v` ([`slider_set_value`]) and store it;
-    /// returns `Some(value)` when the caller must fire `OnValueChanged`. The fire law is the
-    /// client's, emitted-jcc read in wow-re `slider-mouse-law.md` §6: **no range yet → a complete
-    /// no-op**; **first-ever value → always store and fire**; after that, **fire iff the
-    /// clamped/step-quantised value differs** from the stored one. The change-gate is load-bearing,
-    /// not an optimisation: the reference scrollbar wires `OnValueChanged → SetVerticalScroll →
-    /// scrollbar:SetValue` back on itself, and the gate is what stops that after one hop.
-    ///
-    /// **The quantiser is inside the gate, not after it**, and that is what makes a stepped
-    /// slider's drag cheap as well as faithful: a thumb moved a pixel within one step's band
-    /// resolves to the same lattice point and fires nothing at all, exactly as the reference's
-    /// `fcom` against `[+0x320]` decides.
-    ///
-    /// The client holds the range as `min` + `span`; we hold `min` + `max`, so the span is derived
-    /// here the way `0x7898f0` computes it (`end − start`, at f64 and narrowed). That keeps
-    /// `GetMinMaxValues` answering the exact pair that was set — the reference's own `max` is
-    /// re-derived as `span + min` and can differ from it in the last ulp — at the cost of the
-    /// clamp bound being that same re-derivation. A degenerate range (`max < min`) pins to the
-    /// bound, which is the client's arm, not to `min`.
+    /// `SetValue` (`0x789930`): stores the settled value, returning it when `OnValueChanged` fires:
+    /// never without a range, always the first time, else only on a change, which is what ends the
+    /// scrollbar's `SetVerticalScroll` loop. The span is derived as `0x7898f0` computes it.
     pub fn store_value(&mut self, v: f32) -> Option<f32> {
         if !self.range_valid {
             return None;
@@ -1770,28 +1036,9 @@ impl SliderState {
         })
     }
 
-    /// **`SetValueStep` (`0x789a60`) — which is not a field write** (decision 2143).
-    ///
-    /// The byte read, VERIFIED (wow-re `slider-mouse-law.md` §10, a scoped round dispatched from
-    /// this repo, cross-derived twice and pinned by an executed probe on the binary's own bytes):
-    ///
-    /// 1. `0x789a66` stores the step — **unconditional**.
-    /// 2. `0x789a6c test byte [+0x314],2` — **no range yet ⇒ return, and nothing else happens.**
-    /// 3. Otherwise `0x789a91 call 0x7898f0(min, f32(span + min))` — [`Self::set_min_max`] with the
-    ///    max **re-derived**, which re-clamps the held value through `SetValue` when one exists,
-    ///    re-quantising it onto the NEW lattice and firing `OnValueChanged` if it moved.
-    ///
-    /// So a step handed to a slider that already holds a value can move that value and fire — and,
-    /// because `span′ = f32(f32(span + min) − min)` is **not the identity**, it can also change the
-    /// range (`min = 1.0`, `span = 1e-8` collapses it to zero). Ours stored the step and stopped,
-    /// which diverged on all three counts and on the next `GetMinMaxValues` besides.
-    ///
-    /// Inert for every caller the reference ships, and **not for the reason decision 2133 gave**
-    /// (that they set the range and the step before any value exists — true only of each site's
-    /// first run; `FauxScrollFrame_Update` re-runs on a live bar from fourteen update functions and
-    /// never calls `SetValue` at all). It is inert because the only writer of the value is
-    /// `SetValue`, which quantises on the way in, so the value is always already on the lattice
-    /// being re-imposed.
+    /// `SetValueStep` (`0x789a60`): stores the step, then with a range re-runs `SetMinMaxValues`
+    /// with the max re-derived as `f32(span + min)` (`0x789a91`), which can re-quantise the value,
+    /// fire `OnValueChanged` and even change the range, since that sum rounds.
     pub fn set_value_step(&mut self, step: f32) -> Option<f32> {
         self.step = step;
         if !self.range_valid {
@@ -1802,9 +1049,7 @@ impl SliderState {
         self.set_min_max(self.min, max)
     }
 
-    /// `SetMinMaxValues` (`0x7898f0`): set the range, mark it valid, and re-clamp the held value
-    /// **only if one exists** (bit2) — a fresh slider's zero-init value is not a value, so a range
-    /// that excludes zero fires nothing. Returns what [`Self::store_value`] would for the re-clamp.
+    /// `SetMinMaxValues` (`0x7898f0`): sets the range; re-settles the value only once one exists.
     pub fn set_min_max(&mut self, min: f32, max: f32) -> Option<f32> {
         (self.min, self.max) = (min, max);
         self.range_valid = true;
@@ -1816,68 +1061,27 @@ impl SliderState {
     }
 }
 
-/// A `ColorSelect`'s colour (`CSimpleColorSelect`, ctor `0x78b220`) — **three HSV `f32`s**, hue in
-/// **degrees**, and `-1` for the hue of anything grey.
-///
-/// **This is the corrected model, and the correction is the point.** The obvious store is three RGB
-/// bytes, and it is wrong: wow-re's §5 trio (`system/ui/scratch/colorselect-color-law.md`,
-/// 2026-08-11, dispatched from this repo for exactly this question) reads the members off the ctor —
-/// `+0x328` hue-degrees, `+0x32c` saturation, `+0x330` value, all `f32`, initialised `(0, 0, 1)` =
-/// white — with the packed dword at `+0x334` a *derived cache* for the value-strip gradient, not the
-/// state. Two consequences a byte store cannot express: hue survives a drag that takes saturation to
-/// zero, and `GetColorHSV` really does answer `-1` for a grey (`0x7bbc80` writes the sentinel at
-/// `0x7bbccd`).
-///
-/// **The round trip is not the identity, and that is the client's arithmetic, not ours.** There are
-/// two quantizers and they disagree:
-///
-/// * **A, inbound, round-half-up** — `SetColorRGB` only: `trunc(v·255 + 0.5)` via the CRT `__ftol`
-///   (`0x78ec7d`/`0x78ec91`/`0x78eca9`).
-/// * **B, outbound, floor** — every read path: `(bits_f32(v·255 + 512.0) >> 14) & 0xff`
-///   (`0x7bbec0`), a one-sided `2^-15` window.
-///
-/// Composed over the lossy `f32`-degrees hue trip, wow-re measured **exhaustively over all 256³
-/// reachable triples: 1,636,226 (9.7527 %) come back with exactly one channel exactly `-1`** — never
-/// `+1`, never `±2`, never the minimum channel, greys never. And because `quantize_a(b/255) == b` for
-/// every byte, it **ratchets**: the FrameXML idiom `r,g,b = f:GetColorRGB() … f:SetColorRGB(r,g,b)`
-/// re-applies the same lossy map instead of settling — `(0, 8, 132)` walks to `(0, 0, 132)` in eight
-/// cycles. Every Ace2/Dewdrop colour option is that idiom, once per open-and-accept.
-///
-/// It is transcribed rather than smoothed **because it is what the client computes** and the addons
-/// were written against it (wow-re's own §7: *"not a fidelity defect to correct"*). If it ever has to
-/// go, the surgical change is one line — using quantizer A on the read-back too drives the mismatch
-/// count to exactly 0, measured — and it would be a deliberate, recorded deviation, not a bug fix.
-///
-/// No alpha: `SetColorRGB` reads an optional 5th argument, quantizes it, and *discards* it
-/// (`0x7bbf20` reads three bytes; `0x7bbec0` hard-writes `0xff`). The reference's opacity is a
-/// separate `Slider`. `SetColorHSV`/`GetColorHSV` (`0x78e920`/`0x78ea00`) have zero callers across
-/// the 218-addon corpus, so they wait for a customer (decision 1195) — but the state they would read
-/// and write is now the right shape for them.
+/// A `ColorSelect`'s colour (ctor `0x78b220`): HSV `f32`s, hue in degrees, `-1` for a grey
+/// (`0x7bbccd`). RGB enters rounded half up (quantizer A) and leaves floored (B), so a
+/// `GetColorRGB`/`SetColorRGB` round trip drops a channel by 1 for about 9.75 % of colours, and
+/// repeating it ratchets; that drift is the reference's. `SetColorRGB` discards a fifth argument.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct ColorSelectState {
-    /// `[hue-degrees, saturation, value]` — the widget's `+0x328`/`+0x32c`/`+0x330`. Hue is `-1.0`
-    /// whenever saturation is 0 (the grey sentinel).
+    /// `[hue°, saturation, value]` (`+0x328`/`+0x32c`/`+0x330`); an RGB grey has hue `-1.0`.
     pub hsv: [f32; 3],
-    /// `<ColorWheelTexture>` / `SetColorWheelTexture` (`0x78de90`), the widget's `+0x318` — the hue
-    /// disc. The **rect of this region is the wheel's hit box**: the press handler tests the cursor
-    /// against `[+0x318]+0x24`, not against the frame. Created on first set, like a Slider's thumb.
+    /// The hue disc (`<ColorWheelTexture>`, `0x78de90`, `+0x318`), its rect the wheel's hit box.
     pub wheel: Option<RegionHandle>,
-    /// `<ColorWheelThumbTexture>` / `SetColorWheelThumbTexture` (`0x78e160`) — the little marker
-    /// that rides the disc. Its rect is *derived* from `hsv` at extract, and an anchor authored on
-    /// it in XML is **discarded**: `0x78b850` calls `ClearAllPoints 0x767ed0` and re-`SetPoint`s
-    /// from C++ on every colour change. The two thumbs are the only elements here with a `file=`
-    /// and the only ones the reference gives no `<Anchors>` — those two facts are the same fact.
+    /// The disc's marker (`<ColorWheelThumbTexture>`, `0x78e160`), placed from `hsv` at extract;
+    /// an XML anchor on it is discarded (`0x78b850` re-points it on every colour change).
     pub wheel_thumb: Option<RegionHandle>,
-    /// `<ColorValueTexture>` / `SetColorValueTexture` (`0x78e450`), the widget's `+0x320` — the
-    /// brightness strip, and the second hit box (`[+0x320]+0x24`).
+    /// The brightness strip (`<ColorValueTexture>`, `0x78e450`, `+0x320`), the second hit box.
     pub value_strip: Option<RegionHandle>,
-    /// `<ColorValueThumbTexture>` / `SetColorValueThumbTexture` (`0x78e720`) — the strip's marker,
-    /// rect derived from `hsv[2]`.
+    /// The strip's marker (`<ColorValueThumbTexture>`, `0x78e720`), placed from `hsv[2]`.
     pub value_thumb: Option<RegionHandle>,
 }
 
 impl Default for ColorSelectState {
-    /// The ctor's own initial state: H=0, S=0, V=1 — white (`0x78b27e`/`0x78b298`/`0x78b28e`).
+    /// The ctor's white: H=0, S=0, V=1 (`0x78b27e`/`0x78b298`/`0x78b28e`).
     fn default() -> ColorSelectState {
         ColorSelectState {
             hsv: [0.0, 0.0, 1.0],
@@ -1890,43 +1094,33 @@ impl Default for ColorSelectState {
 }
 
 impl ColorSelectState {
-    /// **Quantizer A** — `SetColorRGB`'s inbound leg only (`0x78ec7d`/`0x78ec91`/`0x78eca9`): clamp
-    /// to `[0, 1]`, `·255.0 + 0.5`, then the CRT `__ftol` (`0x40a2b0`) which forces round-to-chop.
-    /// Round-**half-up**. The `255.0`/`0.5` operands are `f32` in `.rdata` and widen exactly, so the
-    /// chain runs in `f64` as the x87 PC_53 registers do.
+    /// Quantizer A, `SetColorRGB`'s inbound leg (`0x78ec7d`): clamp to `[0, 1]`, `·255 + 0.5`,
+    /// truncate (`__ftol`, `0x40a2b0`), so round half up, in `f64` as the x87 registers run it.
     pub fn quantize_a(v: f64) -> u8 {
         let clamped = if v.is_nan() { 0.0 } else { v.clamp(0.0, 1.0) };
         // In-range the product is `[0.5, 255.5]`, so the truncation is always a valid byte.
         (clamped * 255.0 + 0.5) as u8
     }
 
-    /// **Quantizer B** — `0x7bbec0`'s magic-512 pack, on *every* outbound path (the `OnColorSelect`
-    /// payload `0x78bb42`, `GetColorRGB` `0x78ede6`, the strip tint `0x78bbf6`). `v·255 + 512.0`
-    /// lands in the `[512, 1024)` binade where the `f32` ulp is exactly `2^-14`, so the mantissa
-    /// holds `RN(v·255·2^14)` and `>>14` reads its **floor**. No clamp — out-of-range wraps mod 256,
-    /// which is reachable through `SetColorHSV` (unclamped) but not through `SetColorRGB`.
+    /// Quantizer B, every outbound path (`0x7bbec0`): `v·255 + 512` as `f32` has a `2^-14` ulp, so
+    /// `>> 14` reads the floor of `v·255`. Unclamped: out of range wraps mod 256.
     pub fn quantize_b(v: f32) -> u8 {
         let c = (f64::from(v) * 255.0 + 512.0) as f32;
         ((c.to_bits() >> 14) & 0xff) as u8
     }
 
-    /// `0x7bbf20`'s unpack — a colour byte back to `f32`, scaling by the **`f32`** `0x3b808081`
-    /// (≈1/255, rounded *up*: this is why the only round-trip failure mode is a shortfall that
-    /// floors down). Distinct from the `f64` `1/255` the Lua push uses; both appear in one call.
+    /// `0x7bbf20`'s unpack: the byte times the `f32` `0x3b808081`, 1/255 rounded up.
     fn unpack_byte(b: u8) -> f32 {
         let k = f32::from_bits(0x3b80_8081);
         (f64::from(i32::from(b)) * f64::from(k)) as f32
     }
 
-    /// The Lua-facing normalize (`0x78bb47..0x78bb85` and `0x78edfa`/`0x78ee17`/`0x78ee34`): the
-    /// channel byte times the **`f64`** `1/255` at `0x804578` — a multiply by the reciprocal, never a
-    /// divide (they are not the same double).
+    /// The Lua-facing normalize: the byte times the `f64` `1/255` at `0x804578`, never a divide.
     pub fn normalize(byte: u8) -> f64 {
         f64::from(byte) * (1.0_f64 / 255.0)
     }
 
-    /// `0x7bf680` — the index of the largest `|component|`. Compares are strict `>` (`fcom`; equal
-    /// takes the not-greater branch), so a tie resolves to the **later** index.
+    /// `0x7bf680`: the index of the largest `|component|`, a tie going to the later index.
     fn dominant_axis(v: &[f32; 3]) -> usize {
         let (a0, a1, a2) = (v[0].abs(), v[1].abs(), v[2].abs());
         if a0 > a1 {
@@ -1942,7 +1136,7 @@ impl ColorSelectState {
         }
     }
 
-    /// `0x7bf700` — the index of the smallest `|component|`, traced from the same flag pattern.
+    /// `0x7bf700`: the index of the smallest `|component|`.
     fn minor_axis(v: &[f32; 3]) -> usize {
         let (a0, a1, a2) = (v[0].abs(), v[1].abs(), v[2].abs());
         if a0 >= a1 {
@@ -1958,10 +1152,7 @@ impl ColorSelectState {
         }
     }
 
-    /// `0x7bbc80` — RGB→HSV. `value` is the dominant channel; `saturation = (value − minor)/value`
-    /// (0 when `value == 0`); `hue` is the `-1` sentinel when saturation is 0, else the 60°-sector
-    /// formula on the chroma, wrapped `+360` if negative. Each store rounds to `f32`; the chroma
-    /// divide runs on the un-rounded `f64` register.
+    /// `0x7bbc80`, RGB to HSV: each store rounds to `f32`; the chroma divide runs in `f64`.
     fn rgb_to_hsv(rgb: &[f32; 3]) -> [f32; 3] {
         let f = f64::from;
         let dom = Self::dominant_axis(rgb);
@@ -1991,10 +1182,8 @@ impl ColorSelectState {
         [hue, sat, value]
     }
 
-    /// `0x7bbd60` — HSV→RGB. `s == 0` short-circuits to `(v, v, v)` *without reading hue*, which is
-    /// what makes the `-1` sentinel inert on the way out. Otherwise the 6-sector decode, with the
-    /// sector floored by the same magic-512 trick as quantizer B and clamped to `≤ 5`. The
-    /// `f32(1/60) = 0x3c888889` on the way back is the lossy step the whole `-1` drift comes from.
+    /// `0x7bbd60`, HSV to RGB: a grey never reads hue; the sector is floored by quantizer B's
+    /// trick, and the `f32` 1/60 (`0x3c888889`) is where the round trip's drift comes from.
     pub fn hsv_to_rgb(hsv: &[f32; 3]) -> [f32; 3] {
         let f = f64::from;
         let (h, s, v) = (hsv[0], hsv[1], hsv[2]);
@@ -2021,24 +1210,13 @@ impl ColorSelectState {
         }
     }
 
-    /// Store HSV **raw** — no clamp, no quantize, no round trip through RGB. This is what the
-    /// widget's own drag handler does (`0x78bd80`: `fstp [esi+0x328]` / `[+0x32c]` / `[+0x330]`
-    /// straight off the geometry) and what `SetColorHSV 0x78e920` does (wow-re
-    /// `colorselect-color-law.md` §4/§5). The reachable state set is therefore *strictly finer*
-    /// than [`Self::set_rgb`]'s, which can only ever land on the HSV image of the 8-bit lattice —
-    /// the picker's wheel resolves colours the Lua boundary cannot name. What Lua *reads back* is
-    /// quantized identically either way, because the quantize lives on the outbound leg.
+    /// Stores HSV raw, as the drag handler (`0x78bd80`) and `SetColorHSV` (`0x78e920`) do.
     pub fn set_hsv(&mut self, h: f32, s: f32, v: f32) {
         self.hsv = [h, s, v];
     }
 
-    /// `SetColorRGB`'s whole store, in the binary's order (`0x78eb7e`…`0x78ecfa`): clamp each
-    /// argument to `[0, 1]` as `f32` → quantizer A → back to `f32` through `0x7bbf20`'s `1/255` →
-    /// `0x7bbc80` RGB→HSV → store. Always stores — there is deliberately **no change-gate**, unlike
-    /// [`SliderState::store_value`]: the only conditional between `SetColorRGB`'s entry and its
-    /// handler invoke is `0x78bafd`, which tests whether a handler is *bound*, and none of the three
-    /// writers reads the old HSV before overwriting it. Two sibling widgets in the same band,
-    /// opposite gating.
+    /// `SetColorRGB`'s store (`0x78eb7e`): quantizer A, the `0x7bbf20` unpack, RGB to HSV. It
+    /// always stores, with no change gate: `0x78bafd` only tests whether a handler is bound.
     pub fn set_rgb(&mut self, r: f64, g: f64, b: f64) {
         let bytes = [
             Self::quantize_a(r),
@@ -2053,10 +1231,8 @@ impl ColorSelectState {
         self.hsv = Self::rgb_to_hsv(&rgb);
     }
 
-    /// The read-back both `GetColorRGB` and the `OnColorSelect` payload run — literally the same two
-    /// calls in the same order (`0x78edda`/`0x78ede6` vs `0x78bb36`/`0x78bb42`), which is *why* a
-    /// handler's `arg1..arg3` are bit-identical to a `GetColorRGB()` on the next line: HSV→RGB, then
-    /// quantizer B, then the `f64` `1/255`.
+    /// The read-back `GetColorRGB` (`0x78edda`) and the `OnColorSelect` payload (`0x78bb36`) both
+    /// run, so they match bit for bit: HSV to RGB, quantizer B, then the `f64` `1/255`.
     pub fn rgb_f64(&self) -> (f64, f64, f64) {
         let rgb = Self::hsv_to_rgb(&self.hsv);
         (
diff --git a/crates/benilla-ui/src/widget/mod.rs b/crates/benilla-ui/src/widget/mod.rs
index 033f28c2..3784f93a 100644
--- a/crates/benilla-ui/src/widget/mod.rs
+++ b/crates/benilla-ui/src/widget/mod.rs
@@ -1,64 +1,18 @@
-//! The widget object model — the frame arena and the show/hide/strata/level/scale/alpha
-//! mutations, transcribed from wow-5875-re's binary-verified propagation cluster (decision 0068).
-//!
-//! This crate owns the *model*, not the runtime: the arena stores frames and their region leaves and
-//! implements the propagation math, but it does **not** run Lua or fire `OnShow`/`OnHide` — the
-//! mutations that cause visibility transitions *return the set of frames that changed* so the
-//! Lua-embedding layer (the app) can fire the handlers in order.
-//!
-//! ## Ground truth (wow-5875-re `system/ui/scratch/`, binary-verified against `WoW.exe`)
-//!
-//! - **Effective visibility** (`effective_visible_show 0x76ae10` / `_hide 0x76ad50`,
-//!   `propagation.md`): `effectiveVisible = shown AND (parent == null OR parent.effectiveVisible)`.
-//!   A transition recurses into child frames — **a hidden mid-tree frame blocks its whole subtree** —
-//!   and fires `OnShow`/`OnHide`. The recursion is *transition-gated*: a node whose effective
-//!   visibility does not change stops the walk (its subtree cannot have changed).
-//! - **Strata** (`set_frame_strata 0x76a470`): the **whole subtree is forced to one stratum** — the
-//!   frame's strata is set, then every child frame is recursively set to the same value.
-//! - **Level** (`set_frame_level 0x76a4f0`): clamp `>= 0`; `delta = new - old`; **same-strata**
-//!   children shift by the same `delta` (relative offsets preserved); cross-strata children are
-//!   untouched.
-//! - **Effective scale** (`effective_scale 0x76ac90`): `effectiveScale = parentScale * ownScale`,
-//!   written to `layoutScale`, **ε-gated** (skip the write + recursion if `|new - cur| < 2.384e-7`,
-//!   the `_DAT_008029d4` constant — [`SCALE_EPS`]); recurse to child frames.
-//! - **Alpha** (`SetAlpha 0x76a690`, byte-verified — wow-re `propagation.md`, CORRECTED section):
-//!   an eager set-time **overwrite-cascade** — SetAlpha writes the raw value to the frame and
-//!   recurses over its child frames pushing the SAME value (a flatten, like the strata subtree-
-//!   force; never a draw-time ancestor product). At draw a region multiplies its own alpha by its
-//!   OWNER frame's alpha only (one hop, `0x772180`/`0x77fac0`) — which is what `effective_alpha`
-//!   feeds, so effective always equals own.
-//! - **Named auto-publish**: a frame with a name is published to the global name table; a duplicate
-//!   name does **not** overwrite the first (see [`WidgetArena::lookup`]).
-//!
-//! ## Alpha: the settled model (the old 1.12-vs-Era tension is resolved)
-//!
-//! An earlier INFERRED reading ("1.12 alpha is not tree-propagated") kept a dormant Era-style
-//! propagation flag here as a hedge. The §5 cross-check on `SetAlpha 0x76a690` settled it: 1.12
-//! DOES reach the subtree, but by set-time overwrite (the same raw byte pushed to every
-//! descendant frame's `+0xc8`), not by a live parent×child product — Era's `ignoreParentAlpha`
-//! belongs to the later multiplicative model and has no 1.12 counterpart (there is no
-//! `GetEffectiveAlpha` in 5875). The hedge machinery is gone; [`WidgetArena::set_alpha`] IS the
-//! client's mechanism. Consequences worth knowing: a child's later own-SetAlpha diverges from its
-//! parent until the parent is set again (last write wins), and a frame created under a dimmed
-//! parent starts at 1.0 (creation does not re-push the parent's alpha). Scale keeps its own
-//! (verified multiplicative) propagation and Era `ignore_parent_scale` opt-out, inert in 1.12.
+//! The widget object model: the frame arena, its regions, and the reference's propagation of
+//! show, strata, level, scale and alpha down the frame tree. It runs no Lua: a mutation that
+//! moves visibility returns the frames that changed, for the caller to fire `OnShow`/`OnHide`.
 
 use std::collections::HashMap;
 
 use crate::order::{DrawLayer, Strata};
 
-/// The scale-propagation ε — `_DAT_008029d4` = `0x34800000` ≈ 2.384e-7 (`propagation.md`,
-/// `effective_scale 0x76ac90`): a recomputed effective scale within ε of the current one is skipped
-/// (no write, no recursion). This is the *same* binary constant the layout resolver uses for its
-/// `OnSizeChanged` gate, so we reuse it rather than restate the value.
+/// The effective-scale epsilon of `0x76ac90`: the client's constant `0x8029d4` (`0x34800000`,
+/// about 2.384e-7), the same one the layout's `OnSizeChanged` gate uses.
 pub const SCALE_EPS: f64 = crate::layout::SIZE_EPS;
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Handles — generational, so a destroyed-then-reused slot never aliases a stale handle
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Handles ──────────────────────────────────────────────────────────────────────────────────
 
-/// A generational handle to a [`Frame`] in a [`WidgetArena`]. Copyable and comparable; a handle to a
-/// destroyed frame is detected (the slot's generation moved on) and reads return `None`.
+/// A generational handle to a [`Frame`]: it stops resolving once the frame is destroyed.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub struct FrameHandle {
     index: u32,
@@ -73,26 +27,21 @@ pub struct RegionHandle {
 }
 
 impl RegionHandle {
-    /// The handle's identity as one integer — index and generation packed — for the layout change
-    /// gate's fingerprint (`script::layout::InputFingerprint`), which must notice a region being
-    /// swapped for a different one at the same map size.
+    /// Index and generation in one integer: the layout gate's fingerprint must see a region swap.
     #[inline]
     pub(crate) fn fingerprint_bits(self) -> u64 {
         (u64::from(self.generation) << 32) | u64::from(self.index)
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// A hand-rolled generational arena (no external deps — a slotmap in miniature)
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The generational arena ───────────────────────────────────────────────────────────────────
 
 struct Slot<T> {
     generation: u32,
     value: Option<T>,
 }
 
-/// Minimal generational arena: `insert` reuses freed slots, `remove` bumps the slot's generation so
-/// old handles stop resolving. Indices/generations are `u32` — plenty for a UI.
+/// `remove` bumps the slot's generation, so an old handle stops resolving.
 struct Arena<T> {
     slots: Vec<Slot<T>>,
     free: Vec<u32>,
@@ -150,7 +99,6 @@ impl<T> Arena<T> {
         slot.value.as_mut()
     }
 
-    /// Iterate live entries as `(index, generation, &value)`.
     fn iter(&self) -> impl Iterator<Item = (u32, u32, &T)> + '_ {
         self.slots
             .iter()
@@ -158,7 +106,6 @@ impl<T> Arena<T> {
             .filter_map(|(i, s)| s.value.as_ref().map(|v| (i as u32, s.generation, v)))
     }
 
-    /// Iterate live entries as `(index, generation, &mut value)`.
     fn iter_mut(&mut self) -> impl Iterator<Item = (u32, u32, &mut T)> + '_ {
         self.slots
             .iter_mut()
@@ -167,9 +114,7 @@ impl<T> Arena<T> {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Widget kinds
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Widget kinds ─────────────────────────────────────────────────────────────────────────────
 
 mod kinds;
 pub use kinds::{
@@ -183,53 +128,26 @@ pub use kinds::{
     TOOLTIP_FADE_SECS, TOOLTIP_LINE_GAP, TOOLTIP_PAD, TOOLTIP_WRAP_WIDTH,
 };
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// Frame + Region nodes
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── Frame and Region nodes ───────────────────────────────────────────────────────────────────
 
-/// A frame node in the arena — the modeled subset of `CSimpleFrame` (`frame-model.md`).
-///
-/// The invariant-bearing fields (`effective_visible`, `effective_scale`, `effective_alpha`) and the
-/// structural fields (`parent`, `children`, `regions`) are maintained by the [`WidgetArena`]
-/// mutators; treat them as **read-only** and change state through
-/// [`WidgetArena::set_shown`]/[`set_frame_strata`](WidgetArena::set_frame_strata)/etc. so propagation
-/// stays correct. (Not to be confused with [`crate::layout::LayoutInput`], which is the *layout resolver's*
-/// per-frame anchor/size input — a separate concern.)
+/// A frame node, the modelled subset of `CSimpleFrame`. The `effective_*` fields and the tree
+/// links belong to the [`WidgetArena`] mutators: change state through them so it propagates.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Frame {
-    /// The widget subtype.
     pub kind: FrameKind,
-    /// Draw layers switched OFF on this frame — bit `n` = [`DrawLayer::index`] `n`.
-    ///
-    /// `Frame:EnableDrawLayer(layer)` / `DisableDrawLayer(layer)`, VERIFIED present on the Frame
-    /// method table `0x878ec0` at `0x7755b0` / `0x775680`, sitting between `IsToplevel` and `Show`.
-    /// (Read off the `{const char*, void*}` pair bytes; the same walk reproduces wow-re's recorded
-    /// Button table at `0x879d00` exactly.)
-    ///
-    /// A disabled layer hides every region the frame owns in it, and the region's own `Show`/`Hide`
-    /// is untouched underneath — re-enabling the layer brings back exactly what was showing before,
-    /// which is why this is a frame-level mask rather than a sweep over the regions. Both corpus
-    /// consumers (pfUI, MoveAnything) use it to strip Blizzard artwork off a frame they are
-    /// reskinning without disturbing what the owner does to its own regions.
+    /// Layers switched off by `DisableDrawLayer` (`0x775680`) and back on by `EnableDrawLayer`
+    /// (`0x7755b0`), bit `n` for [`DrawLayer::index`] `n`: a frame-level mask, so each region
+    /// keeps its own shown state underneath.
     pub disabled_layers: u8,
-    /// The frame's name (its global identifier), if any. See [`WidgetArena::lookup`] for the
-    /// non-overwriting publish rule.
+    /// The global name, which a later duplicate carries without owning ([`WidgetArena::lookup`]).
     pub name: Option<String>,
-    /// The parent frame, or `None` for a top-level frame (attached to the screen root / `UIParent`).
     pub parent: Option<FrameHandle>,
-    /// Child frames in **insertion order** (the client's `+0x300` child list order) — this order is
-    /// the draw-order tiebreak within a `(strata, level)` bucket for equal-insertion children.
+    /// Child frames in link order, oldest first (the client's child list at `+0x300`).
     pub children: Vec<FrameHandle>,
-    /// Owned region leaves (textures/fontstrings), in creation order. A region detached by
-    /// `SetParent(nil)` stays in this list so [`WidgetArena::destroy`] still frees it — see
-    /// [`Region::detached`], which is what actually takes it out of the draw.
+    /// Owned regions in link order, a detached one included so `destroy` frees it.
     pub regions: Vec<RegionHandle>,
-    /// This frame's **title region** — the drag handle at `CSimpleFrame+0xA8`, or `None`.
-    ///
-    /// **One per frame**, which is what makes `CreateTitleRegion` idempotent: a second call returns
-    /// the SAME object after clearing its anchors, so calling it on an XML-declared title region
-    /// silently wipes them (wow-re `widget-api-batch-benilla.md` Q6). It is also in
-    /// [`Frame::regions`], so the arena still frees it.
+    /// The title region (`CSimpleFrame+0xA8`), also in `regions`. One per frame: a second
+    /// `CreateTitleRegion` returns it with its anchors cleared (`0x767ed0` → `0x767620`).
     pub title_region: Option<RegionHandle>,
     /// The draw stratum (`frameStrata +0xc0`, default MEDIUM).
     pub strata: Strata,
@@ -237,189 +155,83 @@ pub struct Frame {
     pub level: u16,
     /// This frame's own alpha, 0.0..=1.0 (`alpha +0xc8`, default 1.0).
     pub alpha: f32,
-    /// The alpha a renderer should apply — always == [`Frame::alpha`] (see the module's alpha
-    /// section: 1.12 cascades at set time, so there is no separate draw-time product). Kept as its
-    /// propagated product (see the module tension note).
+    /// Always equal to [`Frame::alpha`]: alpha cascades at set time, and at draw a region
+    /// multiplies only its owner frame's alpha (`0x772180`/`0x77fac0`).
     pub effective_alpha: f32,
-    /// `shown` bit (`shown +0xd0`, default true) — the frame's own Show/Hide state.
+    /// The frame's own Show/Hide bit (`+0xd0`, default true).
     pub shown: bool,
-    /// `effectiveVisible +0xd4` — `shown AND parent-chain visible`. Maintained by propagation.
+    /// `shown` and every ancestor effectively visible (`+0xd4`).
     pub effective_visible: bool,
-    /// Whether the frame accepts the mouse (`EnableMouse`). Default **false** — WoW's `enableMouse`
-    /// default; only mouse-enabled *and* effective-visible frames capture the cursor in
-    /// [`crate::order::hit_test`]. (Keyboard focus / `EnableKeyboard` is a separate flag, out of
-    /// scope in this crate for now.)
+    /// `EnableMouse`: the mouse bit (bit 2) of the input mask `[frame+0xcc]`.
     pub mouse_enabled: bool,
-    /// Whether the frame accepts the **wheel** (`EnableMouseWheel` / XML `enableMouseWheel`) — a
-    /// flag of its own in the reference, and separate from [`Self::mouse_enabled`] there and here
-    /// (decision 1198).
-    ///
-    /// Default **false**, WoW's own default. The wheel dispatch bubbles to the nearest *enabled*
-    /// ancestor carrying an `OnMouseWheel`, which is how a scroll region hands the wheel to the
-    /// window behind it while keeping its handler installed — a frame with a handler it has not
-    /// enabled is deliberately transparent to the wheel.
+    /// `EnableMouseWheel`, or an `<OnMouseWheel>` script at XML load: the mask's wheel bit (3).
+    /// A frame with the script but not the bit is transparent to the wheel.
     pub mouse_wheel_enabled: bool,
-    /// Whether the frame is **keyboard-enabled** (`EnableKeyboard` `0x776f90` / XML
-    /// `enableKeyboard`) — the kind-0/kind-1 bucket membership `0x76af00` writes as
-    /// `[frame+0xcc] |= 1<<kind`.
-    ///
-    /// Default **false**, the client's own default. **This is the field key delivery gates on**:
-    /// [`crate::script::keyboard`]'s walk builds its candidate set from
-    /// `effective_visible && keyboard_enabled`, then orders it strata 8→0 / level high→low /
-    /// oldest-registration-first (built 2026-08-14, decision 1319). wow-re's
-    /// `scratch/frame-key-script-delivery.md` §3.2 is explicit that the flag and a handler are
-    /// separable: `EnableKeyboard(true)` on a script-less frame "puts it in the walk where it is
-    /// called and declines — transparent to everything downstream", so **being enabled is not
-    /// being a handler**.
+    /// `EnableKeyboard` (`0x776ec0`), XML `enableKeyboard` or a key script at XML load: the
+    /// mask's char and key bits (`0x76af00`), which key delivery walks
+    /// ([`crate::script::keyboard`]); a script-less frame there declines.
     pub keyboard_enabled: bool,
-    /// Clamp-to-screen (`SetClampedToScreen` / XML `clampedToScreen` — the client's geometry
-    /// flags **bit4**, applied inside rect assembly `0x767a20`, wow-re `layout.md`): the layout
-    /// resolve shifts this frame's assembled rect back inside the screen, size preserved.
-    /// Default **true for GameTooltip frames**, false otherwise: the reference tooltip observably
-    /// clamps (the minimap zone-text hover's ANCHOR_LEFT plate hangs down from the screen top
-    /// instead of leaving the window) though its XML never sets the attribute — the class supplies
-    /// the flag — and the rule here is absolute: no tooltip ever leaves the window (decision 0352).
+    /// `SetClampedToScreen`, geometry flags bit 4: `0x767a20` shifts the rect back on screen.
+    /// Every GameTooltip is born with it here; the stock tooltips get it from their template,
+    /// `GameTooltipTemplate.xml:3`.
     pub clamped_to_screen: bool,
-    /// `SetHitRectInsets` / XML `<HitRectInsets>` — how far the frame's **mouse** rect is inset
-    /// from its resolved rect, as `[left, right, top, bottom]` (default all 0, i.e. the hit rect
-    /// IS the frame rect). Only [`crate::order::hit_test`] reads it: drawing, anchoring, and
-    /// `GetLeft`/`GetWidth` all stay on the un-inset rect. The reference uses it wherever a
-    /// button's art fills less than its frame — the micro buttons are 29×58 frames whose art
-    /// occupies only the lower ~40 px, and a `top="18"` inset is what stops that empty header
-    /// from swallowing hover and clicks aimed past the bar.
+    /// `SetHitRectInsets` or `<HitRectInsets>`: the mouse rect's `[left, right, top, bottom]`
+    /// inset. Only the hit test reads it; drawing, anchoring and `GetLeft`/`GetWidth` do not.
     pub hit_rect_insets: [f32; 4],
-    /// `SetMovable` / XML `movable` — whether `StartMoving()` may drag this frame. Default
-    /// **false**, and the flag is a *guard*, not a behaviour: nothing moves until a script calls
-    /// `StartMoving`, and `StartMoving` without this bit set raises instead of moving
-    /// ([`crate::script`]'s `object::movable` cluster).
+    /// `SetMovable`: only a guard, as `StartMoving` errors without it.
     pub movable: bool,
-    /// `SetResizable` / XML `resizable` — the sizing twin of [`Frame::movable`], guarding the
-    /// `StartSizing` half of the same family. Default false. benilla stores and reports the flag;
-    /// no resize *drag* is built (`StopMovingOrSizing` already covers the stop side of both).
+    /// `SetResizable`: the guard `StartSizing` checks.
     pub resizable: bool,
-    /// `SetMinResize` / `SetMaxResize` — the interactive-resize bounds as `(width, height)`
-    /// (`0x776020` / `0x7762a0`, with `GetMinResize 0x775f20` / `GetMaxResize 0x7761a0`; all four
-    /// on the Frame method table `0x878ec0`, stored in the client at `CLayoutFrame+0x5c..+0x68`
-    /// as a `CRect`-shaped `{minY, minX, maxY, maxX}`).
-    ///
-    /// **`0.0` is the client's own "unbounded" sentinel, on each field independently** (1505) — not a
-    /// flag, not a negative, not a `None`: the `CLayoutFrame` ctor `0x767680` zeroes all four, the
-    /// getters hand back two plain numbers (`0, 0` on a frame nobody bounded, never `nil`), and
-    /// the clamp's first test on every axis is `bound == 0.0 → skip`. A **negative** bound is
-    /// therefore live and clamps normally. Byte-verified: wow-re
-    /// `system/ui/scratch/resize-bounds-and-button-fontstring.md` §1–2.
-    ///
-    /// The values are lengths in the same space as the explicit width/height, so they compare
-    /// directly against [`crate::layout::LayoutInput`]'s — the binding runs the byte-identical
-    /// logical→internal transform `SetWidth`'s does.
-    ///
-    /// A window kit's opening lines are `SetResizable(true)` + these two; Quiver's
-    /// `SideEffectMakeMoveable` calls `SetMinResize` on every module frame it builds and died on
-    /// the nil method (part of B267).
-    ///
-    /// **Only the interactive drag reads them** — VERIFIED, not an omission: the setters store raw
-    /// and do not even mark the layout dirty, `CLayoutFrame::SetWidth`/`SetHeight` never consult
-    /// them, and no layout-resolve path does either. A frame sized 100 wide with
-    /// `SetMinResize(400, 400)` stays 100 wide until the first drag tick snaps it into range.
+    /// `SetMinResize` (`0x776020`; `GetMinResize` `0x775f20`): the resize drag's floor, `(width,
+    /// height)` in `SetWidth` units. `0.0` is unbounded per axis (ctor `0x767680`); a negative
+    /// bound clamps (`0x768710`). Only the drag reads it, never `SetWidth` or the layout.
     pub min_resize: (f32, f32),
-    /// The upper twin of [`Frame::min_resize`] — see its doc, including the `0.0` sentinel.
+    /// `SetMaxResize` (`0x7762a0`; `GetMaxResize` `0x7761a0`): the ceiling, same rules.
     pub max_resize: (f32, f32),
-    /// `SetUserPlaced` — the client's "the user placed this frame; persist its position across
-    /// sessions" bit. Default false, readable through `IsUserPlaced`, and consumed by the layout
-    /// cache ([`crate::script::layout_cache`]) — which is where persisting a frame's position
-    /// belongs, rather than with the drag that moved it.
-    ///
-    /// **Necessary, not sufficient.** Every drag entry stamps this bit unconditionally
-    /// (`0x7652b0` @`0x7652e5`), so an addon that drags a stock frame once stamps it too; the
-    /// cache's own filter is this bit AND [`Frame::movable`]`|`[`Frame::resizable`], at both the
-    /// write and the apply, which is what lets the stamp fall off again (decision 2193).
+    /// `SetUserPlaced`: the layout cache keeps this frame's position. Every drag (`0x7652b0`)
+    /// stamps it (`0x7652e5`), so the cache also requires `movable` or `resizable`, at write and
+    /// at apply.
     pub user_placed: bool,
-    /// `SetToplevel` / XML `toplevel` — flag word `[frame+0xb4]` **bit `0x1`**, the same word as
-    /// [`Frame::movable`] (`0x100`) and [`Frame::resizable`] (`0x200`), written by the same pure
-    /// bit-setter `0x76a3c0` (wow-re `ui/scratch/toplevel-raise.md`). Default false.
-    ///
-    /// The flag only **marks**: setting it performs no raise (`SetToplevel 0x775440` is
-    /// arg-marshal + `0x76a3c0` and returns). What reads it is the raise worker
-    /// `CSimpleTop::Raise 0x7650f0`, which resolves the nearest toplevel *self-or-ancestor* and
-    /// raises **that** — so a frame with this bit clear is never the subject of a raise, and a
-    /// frame with it set is what a click/show anywhere in its subtree lifts. The law, the gate and
-    /// the arithmetic live in [`crate::script::object::toplevel`].
+    /// `SetToplevel` (`0x775440`): bit `0x1` of the flag word `[frame+0xb4]` (`movable` `0x100`,
+    /// `resizable` `0x200`, all set by `0x76a3c0`). It raises nothing; `CSimpleTop::Raise`
+    /// (`0x7650f0`) raises the nearest toplevel self-or-ancestor of a clicked or shown frame.
     pub toplevel: bool,
     /// This frame's own scale (`ownScale +0xb8`, default 1.0).
     pub scale: f32,
-    /// `layoutScale` = `parentEffective * ownScale`, ε-gated (`effective_scale 0x76ac90`).
+    /// `layoutScale` = `parentEffective * ownScale`, ε-gated (`0x76ac90`).
     pub effective_scale: f32,
-    /// Era `ignoreParentScale` opt-out — inert in 1.12 (no frame sets it; extension point).
+    /// A later client's `ignoreParentScale`, not 1.12: nothing sets it.
     pub ignore_parent_scale: bool,
-    /// The Lua-visible numeric id (`GetID`/`SetID`, XML `id=` — the client's `+0xb4`): an
-    /// app-meaning-free label frames carry for their handlers (a dropdown row's list position, a
-    /// tab index). Default 0. Distinct from the layout/wrapper id ([`Model`](crate::script::Model)'s
-    /// bijection) — this one is data, not identity.
+    /// `GetID`/`SetID` and XML `id`, at `+0xb0` (`0x77531f`, `0x7753e7`): data for handlers, such
+    /// as a tab index, not the script model's frame id. Default 0.
     pub wow_id: i64,
-    /// The frame's **live link position** in its `(strata, level)` bucket — the client's intrusive
-    /// list order, not a creation index. Seeded at creation and re-stamped to the bucket's tail by
-    /// [`WidgetArena::resequence_to_tail`] on every relink the reference performs: becoming
-    /// effectively visible, and a *changing* strata or level on an already-visible frame.
-    ///
-    /// It orders **two** sweeps that disagree about which end wins. Drawing takes the LATER-linked
-    /// frame on top; the HIT sweep probes the EARLIER-linked frame first and stops there
-    /// (decision 1816). See [`crate::order::hit_test`], and the note on [`WidgetArena`].
+    /// The link position in the `(strata, level)` bucket, re-stamped at the tail on each relink.
+    /// Drawing puts the later-linked frame on top; the hit test probes the earlier-linked first.
     pub insertion_seq: u32,
-    /// Per-kind behavior state (StatusBar value model, …); [`KindState::None`] for plain kinds.
     pub kind_state: KindState,
-    /// Next declaration index handed to a new region of this frame (region draw-order tiebreak).
     next_decl: u32,
 }
 
-/// A region leaf — a texture or fontstring belonging to one frame (`frame-model.md`).
+/// A region leaf: a texture or font string owned by one frame.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Region {
-    /// Texture or fontstring.
     pub kind: RegionKind,
-    /// The frame this region belongs to.
     pub owner: FrameHandle,
-    /// The draw layer within the owner (BACKGROUND..HIGHLIGHT).
     pub draw_layer: DrawLayer,
-    /// `textureSubLevel` — ordering within the draw layer (extension point beyond 1.12; see
-    /// [`crate::order`]).
+    /// A later client's `textureSubLevel`; 1.12 has no sub-level (`0x76a860`).
     pub sub_level: i8,
-    /// Declaration index within the owner frame — the final within-layer draw tiebreak.
+    /// The index within the owner frame, the last within-layer draw tiebreak.
     pub decl_seq: u32,
-    /// `Region:SetParent(nil)` — the region is **orphaned and unrendered, not destroyed** (wow-re
-    /// `widget-api-batch-benilla.md` Q7: the re-link virtual `0x77fd10` with a null parent unlinks
-    /// from the old parent's draw layer and region list and stores nothing in their place).
-    ///
-    /// Modelled as a flag rather than as an owner-less region: [`Frame::regions`] keeps the entry
-    /// so [`WidgetArena::destroy`] still frees the slab slot, and
-    /// [`crate::order::traversal`] skips it, so it emits no quad. A later
-    /// `SetParent(frame)` clears it and re-links for real
-    /// ([`WidgetArena::set_region_owner`]).
+    /// `Region:SetParent(nil)`: unlinked and not drawn, but not destroyed (`0x77fd10` with a null
+    /// parent). The owner's `regions` keeps it so `destroy` frees it; `SetParent(frame)` relinks.
     pub detached: bool,
 }
 
-// ─────────────────────────────────────────────────────────────────────────────────────────────
-// The arena
-// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ── The arena ────────────────────────────────────────────────────────────────────────────────
 
-/// The frame arena: the store of all frames and regions, the name registry, and the propagation
-/// mutators.
-///
-/// The **screen root** (`CSimpleTop` / `UIParent`) is *not* a node here — a frame with
-/// `parent == None` is a top-level frame anchored to the always-visible, unit-scale screen root.
-///
-/// **Link-stamp / draw order.** Each frame gets a monotonic `insertion_seq` at creation, used as the
-/// draw-order tiebreak **below the draw layer** within a `(strata, level)` bucket (decision 0884 —
-/// the layer outranks the frame; see [`crate::order`]). Like the client, a frame is re-stamped to
-/// its bucket's **tail** whenever it *becomes visible* (`effective_visible_show 0x76ae10` re-ADDS to
-/// the intrusive level list) or a visible frame changes strata/level (both setters remove-then-add;
-/// `propagation.md`). Show order IS draw order within a bucket — how the reference's late-shown
-/// `MiniMapTrackingFrame` draws over the earlier-declared `MinimapBackdrop` ring despite the XML
-/// declaring it first (decision 0557; the mutators live in [`propagation`]).
-///
-/// The client's own list is a *head* insert walked tail→head, i.e. FIFO by link time with the
-/// newest-linked frame emitted last — order-equivalent to this ascending counter, which is why the
-/// counter stays (0884's §5 refuted the intuition that a head insert draws *first*). A same-value
-/// `SetFrameLevel` early-outs before re-stamping, matching `0x76a4f0`'s `je` at `0x76a509`.
+/// The frame arena: frames, regions, the name registry and the propagation mutators. The screen
+/// root is not a node: a frame with no parent hangs off it. Within a bucket the client's list is a
+/// head insert walked tail to head, the same order as the ascending [`Frame::insertion_seq`].
 pub struct WidgetArena {
     frames: Arena<Frame>,
     regions: Arena<Region>,
@@ -427,30 +239,14 @@ pub struct WidgetArena {
     next_insertion: u32,
     /// The draw list's fingerprint cache ([`crate::order::traversal`]).
     pub(crate) order_cache: crate::order::OrderCache,
-    /// Monotonic count of Minimap-kind frames ever created — an O(1) "a new Minimap widget
-    /// exists" signal, so the per-frame state feed (`set_minimap_inside`'s caller) re-pushes
-    /// exactly when one appears instead of walking every frame to find out.
+    /// Minimap frames ever created, so the state feed notices a new one without a walk.
     minimap_created: u64,
-    /// Frames whose kind carries **engine-side per-tick behavior** — ScrollingMessageFrame /
-    /// MessageFrame (the line fades) and Cooldown (the flash-finished hide). The tick's registry
-    /// (decision 1446, the `minimap_created` disposition at list size): the per-frame advance
-    /// walks these few dozen instead of the whole arena, which it used to do TWICE per tick — a
-    /// corpus UI is thousands of frames. Appended at creation (kinds never change after);
-    /// `destroy` removes its own handle, so the list never carries dead entries.
+    /// The live frames the host ticks (message fades, model scene clocks), so the tick skips the
+    /// rest of the arena. Added at creation, as kinds never change; `destroy` removes its own.
     ticked_kinds: Vec<FrameHandle>,
-    /// Every live **GameTooltip**, same registry shape as [`Self::ticked_kinds`] and for the same
-    /// reason one layer over: three hot paths (the auto-size pre-pass at the top of every layout
-    /// resolve, the per-tick fade advance, and the unit-push hook) all begin "find the tooltips",
-    /// and all three did it by walking the resolve's whole frame roster — ~4000 entries at a
-    /// corpus UI, to reach the two or three that exist. Appended at creation (kinds never change);
-    /// `destroy` removes its own handle, so the list never carries dead entries.
+    /// The live GameTooltips, kept the same way, for the layout pre-pass, fade tick and unit push.
     tooltip_kinds: Vec<FrameHandle>,
-    /// Every live **Minimap**, same registry shape as [`Self::ticked_kinds`] and for the same
-    /// reason: three state feeds (containment, the two zoom indices, and the player-arrow facing)
-    /// all begin "find the Minimaps", and the facing is *per frame*. The ping's own lesson
-    /// (decision 1596) was that a per-widget push must not walk the ~3–4k-frame arena every frame
-    /// to reach the one widget that exists. Appended at creation (kinds never change); `destroy`
-    /// removes its own handle.
+    /// The live Minimaps, kept the same way, for the containment, zoom and arrow-facing feeds.
     minimap_kinds: Vec<FrameHandle>,
 }
 
@@ -460,52 +256,29 @@ impl Default for WidgetArena {
     }
 }
 
-/// Whether a widget of this kind is **mouse-enabled by its constructor**, needing neither an
-/// `enableMouse` attribute nor an auto-enabling `<Scripts>` handler to be clickable.
-///
-/// One list, because there are two readers: this arena, and `benilla-app`'s `frame_flag_gate`
-/// sweep, which compares our frames against a model of the reference's XML. That sweep used to
-/// carry its own copy with a comment claiming it was "deliberately the SAME list" — it was not,
-/// and it drifted silently the first time this one was edited. A wrong entry should be wrong in
-/// one place.
-///
-/// **Read off the client's ctors** (wow-re `ui/scratch/mouse-enable-law.md` `774f7eb6`, and the
-/// follow-up `68987021`). `[frame+0xcc]` is a four-bit input mask — char, keyboard, MOUSE, wheel —
-/// zeroed by the base `CSimpleFrame` ctor `0x769090` and set by exactly five subclass ctors:
-/// Button `0x778771`, CheckButton (through Button), Slider `0x789467`, ColorSelect `0x78b2b5`,
-/// and EditBox `0x779ced`, which takes char+keyboard+mouse together because it must take a click
-/// to focus. `Minimap` is an engine frame born `0x4` (`0x4edc38`), and ours is a `FrameKind`.
-///
-/// **`ScrollFrame` and `ScrollingMessageFrame` are NOT here, and that was the hard one.** They
-/// were, on the reasoning that a scroll frame "takes the wheel in its ctor" — the wheel is a
-/// different bit, and no ctor writes it at all. Against that stood a recorded observation:
-/// `ChatFrame1` is a `ScrollingMessageFrame`, and something has to make a 1.12 chat link
-/// clickable. The follow-up round settled it: nothing about the frame does. The engine synthesises
-/// one mouse-enabled `CSimpleHyperlinkButton` child PER LINK SPAN (`0x7a3240`, born through the
-/// `CSimpleButton` ctor) and routes the hyperlink scripts back to the parent. We hold spans as
-/// rects rather than child frames, so `script::pointer`'s hit test carries the same law as a
-/// disjunct: the chat window is a candidate over a link and inert everywhere else.
+/// Whether this kind's constructor enables the mouse, so it takes clicks with no `enableMouse`
+/// and no mouse script: the base ctor `0x769090` zeroes the input mask `[frame+0xcc]`, and Button
+/// (`0x778771`, CheckButton through it), Slider (`0x789467`), ColorSelect (`0x78b2b5`), EditBox
+/// (`0x779ced`..`0x779d03`, with char and key) and Minimap (`0x4edc38`) set its mouse bit. The
+/// ScrollFrame and ScrollingMessageFrame ctors set none; a chat link takes clicks through a
+/// mouse-enabled child per span (`0x7a3240`), which `script::pointer` models as rects.
 pub fn mouse_enabled_by_ctor(kind: FrameKind) -> bool {
     matches!(
         kind,
         FrameKind::Button
             | FrameKind::CheckButton
             | FrameKind::EditBox
-            // `CGWorldFrame`'s ctor enables key + mouse + wheel (`0x481b09`/`0x481b14`/`0x481b1f`,
-            // wow-re `mouse-enable-law.md`); the hit is the world's, not the UI's (decision 1983).
+            // `CGWorldFrame`'s ctor enables key, mouse, wheel (`0x481b09`/`0x481b14`/`0x481b1f`).
             | FrameKind::WorldFrame
-            // A Slider's thumb must be draggable: every scrollbar is a UIPanelScrollBarTemplate
-            // Slider that declares no `enableMouse` yet is draggable in-game (decision 0250).
             | FrameKind::Slider
             | FrameKind::ColorSelect
             | FrameKind::Minimap
-            // `LootButton` extends `CSimpleButton` and inherits its ctor's bit (decision 1799).
+            // `LootButton` extends `CSimpleButton` and inherits its ctor's bit.
             | FrameKind::LootButton
     )
 }
 
 impl WidgetArena {
-    /// A new, empty arena in **1.12 mode** (alpha does not propagate).
     pub fn new() -> WidgetArena {
         WidgetArena {
             frames: Arena::new(),
@@ -520,75 +293,63 @@ impl WidgetArena {
         }
     }
 
-    /// Monotonic count of Minimap widgets ever created (see the field note).
+    /// Minimap frames ever created, a cheap signal that a new one exists.
     pub fn minimap_created(&self) -> u64 {
         self.minimap_created
     }
 
-    /// The frames whose kind the host must advance each tick (see the field note).
+    /// The frames the host advances each tick.
     pub fn ticked_kinds(&self) -> &[FrameHandle] {
         &self.ticked_kinds
     }
 
-    /// The live GameTooltip frames (see the field note).
     pub fn tooltip_kinds(&self) -> &[FrameHandle] {
         &self.tooltip_kinds
     }
 
-    /// The live Minimap frames (see the field note).
     pub fn minimap_kinds(&self) -> &[FrameHandle] {
         &self.minimap_kinds
     }
 
     // ── Read access ────────────────────────────────────────────────────────────────────────────
 
-    /// Borrow a frame, or `None` if the handle is stale/unknown.
     pub fn frame(&self, h: FrameHandle) -> Option<&Frame> {
         self.frames.get(h.index, h.generation)
     }
 
-    /// Mutably borrow a frame. Prefer the dedicated mutators for state that propagates
-    /// (shown/strata/level/scale/alpha/parent) — direct edits bypass propagation.
+    /// Direct edits skip propagation: shown, strata, level, scale, alpha and parent go through
+    /// the mutators.
     pub fn frame_mut(&mut self, h: FrameHandle) -> Option<&mut Frame> {
         self.frames.get_mut(h.index, h.generation)
     }
 
-    /// Borrow a region, or `None` if the handle is stale/unknown.
     pub fn region(&self, h: RegionHandle) -> Option<&Region> {
         self.regions.get(h.index, h.generation)
     }
 
-    /// Mutably borrow a region.
     pub fn region_mut(&mut self, h: RegionHandle) -> Option<&mut Region> {
         self.regions.get_mut(h.index, h.generation)
     }
 
-    /// Iterate every live frame as `(handle, &Frame)` (arena order — [`crate::order::traversal`]
-    /// sorts into draw order).
+    /// Every live frame, in arena order, not draw order.
     pub fn iter_frames(&self) -> impl Iterator<Item = (FrameHandle, &Frame)> + '_ {
         self.frames
             .iter()
             .map(|(index, generation, f)| (FrameHandle { index, generation }, f))
     }
 
-    /// Iterate every live frame as `(handle, &mut Frame)` — for per-kind state the host advances each
-    /// tick (the ScrollingMessageFrame fade). Structural fields stay the arena's to mutate through its
-    /// propagation setters; this is for [`Frame::kind_state`] only.
+    /// Every live frame, mutably, for [`Frame::kind_state`].
     pub fn iter_frames_mut(&mut self) -> impl Iterator<Item = (FrameHandle, &mut Frame)> + '_ {
         self.frames
             .iter_mut()
             .map(|(index, generation, f)| (FrameHandle { index, generation }, f))
     }
 
-    /// Move `h` to the **tail** of its `(strata, level)` draw bucket — the client's own live-list
-    /// maintenance (`propagation.md`): `effective_visible_show 0x76ae10` re-ADDS a frame to its
-    /// level's intrusive list on the hidden→visible transition, and `set_frame_strata 0x76a470` /
-    /// `set_frame_level 0x76a4f0` remove-then-add a visible frame — an intrusive-list add appends.
-    /// Called by the [`propagation`] mutators on exactly those transitions (module doc).
+    /// Move `h` to its bucket's tail, as the client's level-list add does: show `0x76ae10` on
+    /// becoming visible, and strata `0x76a470` or level `0x76a4f0` on a visible frame.
     pub(crate) fn resequence_to_tail(&mut self, h: FrameHandle) {
-        // The seq lives in an 18-bit field of the packed `ZKey`; unbounded show-bumping could
-        // exhaust it over a marathon session, so at the cap renumber every frame in its current
-        // order (order-preserving, so no visible change) instead of tripping ZKey's assert.
+        // The stamp is `INSERTION_BITS` wide in the packed `ZKey`: at the cap, renumber every
+        // frame in its current order, which changes no draw order.
         if self.next_insertion >= (1 << crate::order::INSERTION_BITS) {
             let mut order: Vec<FrameHandle> =
                 self.iter_frames().map(|(handle, _)| handle).collect();
@@ -607,31 +368,21 @@ impl WidgetArena {
         }
     }
 
-    /// Resolve a name to the frame that published it, or `None`. Publishing is **non-overwriting**:
-    /// the first frame created with a given name owns it; a later duplicate keeps its own `name`
-    /// field but does not become the lookup target (matching the client's auto-publish rule,
-    /// `propagation.md`/decision 0068).
+    /// The first frame created with `name`; a later duplicate never takes it over (`0x701bd0`).
     pub fn lookup(&self, name: &str) -> Option<FrameHandle> {
         self.names.get(name).copied()
     }
 
     // ── Create / destroy ────────────────────────────────────────────────────────────────────────
 
-    /// Create a frame of `kind`, with an optional `name` and `parent`. A `parent` handle that is not
-    /// live is treated as `None` (top-level). The new frame starts `shown`, strata MEDIUM, level 0,
-    /// scale 1.0, alpha 1.0; its `effective_visible`/`effective_scale`/`effective_alpha` are computed
-    /// from the parent immediately. If `name` is given and not already published, it is published.
-    ///
-    /// (Strata/level inheritance from the parent at create time is a *loader/CreateFrame* concern,
-    /// not the ctor's — the client's ctor writes MEDIUM/0 unconditionally, `frame-model.md`; we match
-    /// that and leave inheritance to the layer above.)
+    /// Create a frame as the client's ctor `0x769090` does, whatever the parent: shown, MEDIUM,
+    /// level 0, scale and alpha 1.0. A dead `parent` makes a top-level frame.
     pub fn create(
         &mut self,
         kind: FrameKind,
         name: Option<String>,
         parent: Option<FrameHandle>,
     ) -> FrameHandle {
-        // Only keep a parent that is actually live.
         let parent = parent.filter(|&p| self.frame(p).is_some());
         let parent_visible = parent.is_none_or(|p| self.frame(p).unwrap().effective_visible);
         let parent_scale = parent.map_or(1.0, |p| self.frame(p).unwrap().effective_scale);
@@ -641,8 +392,7 @@ impl WidgetArena {
 
         let shown = true;
         let scale = 1.0f32;
-        // Alpha starts at 1.0 regardless of the parent's — creation does not re-push a dimmed
-        // parent's value (only SetAlpha cascades; module alpha section).
+        // 1.0 whatever the parent's: only `SetAlpha` pushes alpha down the tree.
         let alpha = 1.0f32;
         let effective_alpha = alpha;
 
@@ -654,8 +404,7 @@ impl WidgetArena {
             children: Vec::new(),
             regions: Vec::new(),
             title_region: None,
-            // The WorldFrame's constructor is the one writer of stratum 0 (`WORLD`, below
-            // `BACKGROUND`); every other kind starts at the base ctor's MEDIUM (1984).
+            // The WorldFrame ctor alone writes stratum 0, WORLD; the rest start MEDIUM.
             strata: if kind == FrameKind::WorldFrame {
                 Strata::World
             } else {
@@ -667,32 +416,19 @@ impl WidgetArena {
             shown,
             effective_visible: shown && parent_visible,
             mouse_enabled: mouse_enabled_by_ctor(kind),
-            // The two kinds whose ctor takes the WHEEL rather than the mouse generally — the same
-            // by-construction argument as above, narrowed to the flag it is actually about
-            // (decision 1198): a ScrollingMessageFrame and a ScrollFrame are wheel-interactive
-            // with no attribute, and nothing else is.
+            // The WorldFrame ctor takes the wheel (`0x481b1f`); the reference's ScrollFrame and
+            // ScrollingMessageFrame ctors do not, and a stock one takes it from `<OnMouseWheel>`.
             mouse_wheel_enabled: matches!(
                 kind,
                 FrameKind::ScrollingMessageFrame | FrameKind::ScrollFrame | FrameKind::WorldFrame
             ),
-            // Nothing is keyboard-enabled by construction: `0x76af00` is only ever reached from the
-            // XML attribute or an explicit call, never a ctor (`scripts-auto-enable.md` §1-2).
+            // No kind is keyboard-enabled at creation here; the reference's EditBox
+            // (`0x779ced`/`0x779cf8`) and WorldFrame (`0x481b09`) ctors enable key input.
             keyboard_enabled: false,
-            // A tooltip clamps to the screen by construction (its XML never sets the attribute,
-            // yet the reference plate observably never leaves the window — the class supplies
-            // geometry flags bit4; decision 0352's law: no tooltip off-screen, ever).
             clamped_to_screen: matches!(kind, FrameKind::GameTooltip),
-            // No frame is born with an inset hit rect — `<HitRectInsets>`/SetHitRectInsets is the
-            // only source (the client's ctor zeroes the four floats too).
             hit_rect_insets: [0.0; 4],
-            // No kind is born movable/resizable/user-placed/toplevel: every one of the four is
-            // opt-in from XML or a script, and a frame nobody opted in stays where its anchors put
-            // it, at the level it was created with.
             movable: false,
             resizable: false,
-            // All four zeroed, which IS the client's unbounded state — `CLayoutFrame`'s ctor
-            // `0x767680` does exactly this (`xor esi,esi` into `+0x5c..+0x68`), and `0.0` is the
-            // sentinel the clamp tests rather than a separate flag.
             min_resize: (0.0, 0.0),
             max_resize: (0.0, 0.0),
             user_placed: false,
@@ -704,8 +440,8 @@ impl WidgetArena {
             insertion_seq,
             kind_state: match kind {
                 FrameKind::StatusBar => KindState::StatusBar(StatusBarState::default()),
-                // `CLootButton` and `CSimpleCheckbox` both extend `CSimpleButton` and both add
-                // exactly one field, which `ButtonState` carries for them (`loot_slot`/`checked`).
+                // `CLootButton` and `CSimpleCheckbox` extend `CSimpleButton` by one field each,
+                // which `ButtonState` carries (`loot_slot`, `checked`).
                 FrameKind::Button | FrameKind::CheckButton | FrameKind::LootButton => {
                     KindState::Button(ButtonState::default())
                 }
@@ -719,9 +455,8 @@ impl WidgetArena {
                 FrameKind::ColorSelect => {
                     KindState::ColorSelect(kinds::ColorSelectState::default())
                 }
-                // Both model panes share one state: `CGCharacterModelBase` EXTENDS `CSimpleModel`,
-                // so a `<PlayerModel>` carries every `CSimpleModel` member and adds only the
-                // turn-animation pair we do not model (`ModelState`'s doc).
+                // `CGCharacterModelBase` extends `CSimpleModel`, adding only a turn-animation pair,
+                // which is not modelled.
                 FrameKind::Model
                 | FrameKind::PlayerModel
                 | FrameKind::DressUpModel
@@ -736,8 +471,6 @@ impl WidgetArena {
         if matches!(kind, FrameKind::Minimap) {
             self.minimap_created += 1;
         }
-        // The model panes ride the same registry: their scene clock advances per tick and their
-        // completion edge is read there (decision 2007).
         let ticked = matches!(
             kind,
             FrameKind::ScrollingMessageFrame
@@ -762,7 +495,6 @@ impl WidgetArena {
                 .push(handle);
         }
         if let Some(n) = name {
-            // Non-overwriting: first writer wins.
             self.names.entry(n).or_insert(handle);
         }
         if matches!(kind, FrameKind::EditBox) {
@@ -770,46 +502,21 @@ impl WidgetArena {
         }
         if matches!(kind, FrameKind::Minimap) {
             self.minimap_kinds.push(handle);
-            // The `CMinimap` ctor's own last act, so no observer ever sees a Minimap without its
-            // nine (see [`MINIMAP_ENGINE_CHILDREN`]). It sits here rather than in the loader
-            // because the client builds them in the *element factory* — `CreateFrame("Minimap")`
-            // from Lua gets them too, and gets them before its OnLoad runs.
+            // The `CMinimap` ctor's last act, so a `CreateFrame("Minimap")` has its nine children
+            // before its `OnLoad` too.
             self.build_minimap_engine_children(handle);
         }
         handle
     }
 
-    /// Build the **five engine-owned regions of a fresh EditBox**, in the ctor's own order — the
-    /// same posture as [`Self::build_minimap_engine_children`] below, and for the same reason: the
-    /// client builds them in `CSimpleEditBox`'s ctor, so a `CreateFrame("EditBox")` with no XML
-    /// behind it has them too, before its OnLoad runs.
-    ///
-    /// wow-re `system/ui/scratch/rf85-editbox-caret.md` §1, all VERIFIED off bytes:
-    ///
-    /// | # | region | ctor site | built by |
-    /// |---|---|---|---|
-    /// | 1 | text FontString `E+0x328` | `0x779bee` | `0x770d30(E, 2, 1)` |
-    /// | 2-4 | selection-highlight quads `E+0x350/0x354/0x358` | `0x779c41`–`0x779c72` | `0x76fc40(E, 2, 0)` |
-    /// | 5 | caret `E+0x368` | `0x779c86`–`0x779cac` | `0x76fc40(E, 3, 1)` |
-    ///
-    /// **Why the ORDER is the whole point.** `GetRegions 0x773f60` walks `[frame+0x1b8]` — one flat
-    /// creation-ordered list, oldest first, with **no filter** (hidden regions are returned and
-    /// counted), and insertion is at the TAIL (`scratch/widget-list-bindings.md`). All five reach
-    /// that list through `0x77fd10`, the single linker. So on a real client the authored `<Layers>`
-    /// regions start at index **6**, and an addon may index them there.
-    ///
-    /// pfUI's `skins/blizzard/friends.lua` l.379 is the report:
-    /// `local _,_,_,_,_,left,right = GuildControlPopupFrameEditBox:GetRegions()` — it skips five and
-    /// takes the box's two `UI-ChatInputBorder` textures. Before this, benilla returned only the
-    /// authored regions, so `left` was nil and the whole guild-control skin died on it.
-    ///
-    /// The four quads are created blank — no texture, no fill — so they emit nothing; benilla's
-    /// caret and selection highlight are still painted host-side. That gap is named on the
-    /// [`EditBoxState`](kinds::EditBoxState) fields rather than papered over.
+    /// Build the five regions the `CSimpleEditBox` ctor gives every EditBox, in its order: the
+    /// text FontString `E+0x328` (`0x779bee`, `0x770d30(E, 2, 1)`), three selection quads
+    /// `E+0x350/0x354/0x358` (`0x779c41`..`0x779c72`, `0x76fc40(E, 2, 0)`) and the caret
+    /// `E+0x368` (`0x779c86`..`0x779cac`, `0x76fc40(E, 3, 1)`). `GetRegions` (`0x773f60`) lists
+    /// them first, hidden or not, so authored `<Layers>` regions start at index 6. The quads carry
+    /// no texture: caret and selection paint host-side.
     fn build_editbox_engine_regions(&mut self, eb: FrameHandle) {
-        // The text region keeps the OVERLAY/0 layer it has always shipped with; the ctor's own
-        // 2/1 is recorded on the field and deferred there (a draw-order change to every EditBox
-        // is not a rider on a region-list fix).
+        // OVERLAY here; the reference ctor puts the text in layer 2, ARTWORK (`0x770d30(E, 2, 1)`).
         let text = self.create_region(eb, RegionKind::FontString, DrawLayer::Overlay, 0);
         let mut selection = [None; 3];
         for slot in &mut selection {
@@ -823,11 +530,8 @@ impl WidgetArena {
         }
     }
 
-    /// Build the nine engine-owned `Model` children of a fresh Minimap and remember the ninth as
-    /// its player arrow. They are created **anonymous and file-less**: the ctor only constructs
-    /// them, and the model paths are `CMinimap::LoadXML 0x4ee2b0`'s to assign from the two
-    /// attributes (the loader's minimap pass) — which is why a `CreateFrame("Minimap")` with no XML
-    /// behind it has nine blank Models here, exactly as the reference does.
+    /// Build a Minimap's nine engine `Model` children, the ninth its player arrow. They are born
+    /// anonymous and without a model file; `CMinimap::LoadXML` (`0x4ee2b0`) assigns the paths.
     fn build_minimap_engine_children(&mut self, minimap: FrameHandle) {
         let mut ninth = None;
         for _ in 0..kinds::MINIMAP_ENGINE_CHILDREN {
@@ -838,8 +542,7 @@ impl WidgetArena {
         }
     }
 
-    /// Destroy a frame and its whole subtree (child frames and all regions), unpublishing any names
-    /// it owns and detaching it from its parent's child list. Stale handles are ignored.
+    /// Destroy a frame and its subtree, with their regions and the names they own.
     pub fn destroy(&mut self, h: FrameHandle) {
         let Some(frame) = self.frame(h) else {
             return;
@@ -848,7 +551,7 @@ impl WidgetArena {
         let regions = frame.regions.clone();
         let parent = frame.parent;
         let name = frame.name.clone();
-        // Each (recursive) destroy removes its own handle — the tick registry stays dead-free.
+        // Each recursive call removes its own handle, so the registries hold no dead frame.
         self.ticked_kinds.retain(|&t| t != h);
         self.tooltip_kinds.retain(|&t| t != h);
         self.minimap_kinds.retain(|&t| t != h);
@@ -872,7 +575,6 @@ impl WidgetArena {
         self.frames.remove(h.index, h.generation);
     }
 
-    /// Create a region leaf owned by `owner`. Returns `None` if `owner` is stale.
     pub fn create_region(
         &mut self,
         owner: FrameHandle,
@@ -902,23 +604,9 @@ impl WidgetArena {
         Some(handle)
     }
 
-    /// **Free one region leaf** — unlink it from its owner's region list and release the slab slot,
-    /// so the handle stops resolving and the region stops drawing. Returns whether it was live.
-    ///
-    /// There is no `Region:Destroy` in the widget API and none is wanted: this exists for the one
-    /// engine-owned lifetime in the client, `CSimpleHTML::SetText`, which pool-frees the blocks of
-    /// the previous parse before building the new ones (`simplehtml-markup-engine.md` §10 step 1 —
-    /// the pool allocate at `0x78adc6` has a matching free, and the CONTENTNODE list at `+0x340` is
-    /// what names the objects to free). Without it a second `SetText` leaves the first parse's
-    /// FontStrings on screen, stacked behind the new ones.
-    ///
-    /// **The caller owns the rest of the region's identity.** The arena holds only structure;
-    /// paint (`RegionData`), the stable id maps, the resolved-rect cache and any name publish live
-    /// on the script model, and a caller that frees a region without dropping those leaves a
-    /// resolvable id pointing at a dead handle. [`crate::script`]'s SimpleHTML block teardown is
-    /// the one caller and does the whole set. For the same reason this must never be pointed at a
-    /// region some *state* still holds by handle (a button's texture slot, a tooltip line, an
-    /// EditBox's text region): freeing those would leave that state dangling.
+    /// Free one region, as only `CSimpleHTML::SetText` does in the client, pool-freeing the last
+    /// parse's blocks (`0x78adc6`). The caller drops the region's script-model state too, and never
+    /// frees a region some state holds by handle.
     pub fn destroy_region(&mut self, h: RegionHandle) -> bool {
         let Some(region) = self.region(h) else {
             return false;
@@ -934,8 +622,6 @@ impl WidgetArena {
     }
 }
 
-// The propagation mutators (visibility/strata/level/scale/alpha/reparenting) — split out for size;
-// see `propagation`'s module doc.
 mod propagation;
 
 #[cfg(test)]
diff --git a/crates/benilla-ui/src/widget/propagation.rs b/crates/benilla-ui/src/widget/propagation.rs
index 1ac190b5..9ac43f9a 100644
--- a/crates/benilla-ui/src/widget/propagation.rs
+++ b/crates/benilla-ui/src/widget/propagation.rs
@@ -1,23 +1,17 @@
-//! [`WidgetArena`]'s propagation mutators — the binary-verified subtree math that keeps
-//! `effective_visible`/`strata`/`level`/`effective_scale`/`effective_alpha` (and reparenting, which
-//! touches several of those at once) consistent whenever a frame's own state changes. Split out of
-//! [`super`] because this is the module's dense, ground-truth-heavy core (see the module doc's
-//! "Ground truth" section); the arena's storage/create/destroy/read-access lives with the struct
-//! definition in [`super`].
+//! [`WidgetArena`]'s mutators: propagation down the subtree, reparenting and the frame flags.
 
 use crate::order::Strata;
 
 use super::{FrameHandle, RegionHandle, WidgetArena, SCALE_EPS};
 
 impl WidgetArena {
-    // ── Visibility (effective_visible_show/_hide) ────────────────────────────────────────────────
+    // ── Visibility ───────────────────────────────────────────────────────────────────────────────
 
-    /// Set a frame's own `shown` bit and propagate effective visibility through its subtree, per
-    /// `effective_visible_show 0x76ae10` / `_hide 0x76ad50` (`propagation.md`). Returns, in
-    /// pre-order (a node before its descendants), **every frame whose `effective_visible` actually
-    /// changed** — the caller fires `OnShow`/`OnHide` for those, in order. A no-op `shown` write, or
-    /// a change that does not move any effective visibility (e.g. hiding an already-invisible frame),
-    /// returns empty.
+    /// Set `shown` and propagate effective visibility down the subtree (show `0x76ae10`, hide
+    /// `0x76ad50`), returning the frames that changed, a node before its descendants, for the
+    /// caller to fire `OnShow`/`OnHide`. The reference notifies post-order (`0x76aef5`) and
+    /// re-reads live links, so a frame a handler hides mid-cascade fails its gate (`0x76ae1d`) and
+    /// is never notified; this list is a snapshot that still holds it.
     pub fn set_shown(&mut self, h: FrameHandle, shown: bool) -> Vec<FrameHandle> {
         let mut changed = Vec::new();
         match self.frame_mut(h) {
@@ -41,17 +35,12 @@ impl WidgetArena {
         };
         let new_ev = shown && parent_visible;
         if new_ev == old_ev {
-            // Transition-gated: no change here ⇒ no change below (children's parent-visibility and
-            // own shown are unchanged). Prune, exactly like the client's recursion.
+            // No change here means none below: prune, as the client's recursion does.
             return;
         }
         self.frame_mut(h).unwrap().effective_visible = new_ev;
         if new_ev {
-            // The client re-ADDS the frame to its (strata, level) bucket on this transition —
-            // an intrusive-list append, so a newly shown frame draws over everything already in
-            // its bucket ([`WidgetArena::resequence_to_tail`]). Pre-order recursion gives the
-            // descendants later seqs than the node, exactly like the client's recursion re-adding
-            // each as its own effectiveVisible flips.
+            // Re-added at its bucket's tail, as the client does, and each descendant after it.
             self.resequence_to_tail(h);
         }
         changed.push(h);
@@ -60,14 +49,10 @@ impl WidgetArena {
         }
     }
 
-    // ── Strata (set_frame_strata) ────────────────────────────────────────────────────────────────
+    // ── Strata ───────────────────────────────────────────────────────────────────────────────────
 
-    /// Force `h` and its **whole subtree** to `strata`, per `set_frame_strata 0x76a470`
-    /// (`propagation.md`): set the frame's strata, then recursively set every child frame to the
-    /// same value. The client's visible-gated bucket remove/add (its live draw-list maintenance)
-    /// is mirrored by re-sequencing a visible frame to its new bucket's tail
-    /// ([`WidgetArena::resequence_to_tail`]); [`crate::order::traversal`] recomputes the buckets
-    /// from the fields.
+    /// Force `h` and its whole subtree to `strata` (`0x76a470`), moving each visible frame to the
+    /// tail of its new bucket.
     pub fn set_frame_strata(&mut self, h: FrameHandle, strata: Strata) {
         let (visible, children) = match self.frame_mut(h) {
             Some(f) => {
@@ -87,13 +72,10 @@ impl WidgetArena {
         }
     }
 
-    // ── Level (set_frame_level) ──────────────────────────────────────────────────────────────────
+    // ── Level ────────────────────────────────────────────────────────────────────────────────────
 
-    /// Set `h`'s level. When `propagate`, **same-strata** child frames shift by the same delta
-    /// (relative offsets preserved); cross-strata children are untouched — per `set_frame_level
-    /// 0x76a4f0` (`propagation.md`). Level is unsigned here, so the client's `if (level < 0) level =
-    /// 0` clamp is subsumed by the type (a Lua binding saturates on conversion); a propagated shift
-    /// that would go negative saturates to 0, and an overflow saturates to `u16::MAX`.
+    /// Set `h`'s level (`0x76a4f0`); with `propagate`, same-strata children shift by the same
+    /// delta. A same-value call returns before relinking (`0x76a509`).
     pub fn set_frame_level(&mut self, h: FrameHandle, level: u16, propagate: bool) {
         let (delta, strata, children) = match self.frame_mut(h) {
             Some(f) => {
@@ -106,8 +88,7 @@ impl WidgetArena {
             }
             None => return,
         };
-        // The client's visible-gated remove/add: a visible frame lands at its NEW bucket's tail
-        // (a hidden one is in no bucket — it appends on its next show anyway).
+        // Only a visible frame relinks (`0x76a541`); a hidden one is in no bucket.
         if self.frame(h).is_some_and(|f| f.effective_visible) {
             self.resequence_to_tail(h);
         }
@@ -119,63 +100,21 @@ impl WidgetArena {
                 Some(cf) if cf.strata == strata => {
                     (i32::from(cf.level) + delta).clamp(0, i32::from(u16::MAX)) as u16
                 }
-                _ => continue, // cross-strata (or stale) child: untouched
+                _ => continue, // cross-strata or stale: untouched
             };
             self.set_frame_level(c, child_new, true);
         }
     }
 
-    /// Squeeze the free levels out of `strata` and return the level counter — `level_compact
-    /// 0x764eb0`, the step `CSimpleTop::Raise 0x7650f0` runs immediately before it sets the raised
-    /// frame's level to `bucket->count(+0x8)` (wow-re `ui/scratch/level-compact-law.md`, a §5 trio
-    /// dispatched from here; `ui/scratch/toplevel-raise.md` for the raise it serves).
+    /// Level compaction (`0x764eb0`), run by `CSimpleTop::Raise` (`0x7650f0`) before it sets the
+    /// raised frame's level to the returned count: renumber the occupied levels of `strata` in
+    /// order, hidden frames included (the scan tests only strata and level, `0x764f18`/`0x764f20`),
+    /// without propagating (`0x764faf`). `level` is written directly, so `insertion_seq` survives
+    /// where the reference re-levels through `0x76a4f0` (`0x764fb6`) and relinks visible frames.
     ///
-    /// **EVERY frame of the stratum is renumbered — hidden ones included, and that is the byte
-    /// law, not a benilla choice** (decision 2104). `0x764eb0`'s occupancy test is a two-part OR: a
-    /// level node's own list, else a scan of the client's **master frame list** (`[root+0xcc4]`,
-    /// link offset `0x304` — every live frame, joined in the `CSimpleFrame` ctor and counted by
-    /// `GetNumFrames`), and that scan filters on exactly two fields — `+0xc0` strata (`0x764f18`)
-    /// and `+0xc4` level (`0x764f20`). The renumber pass `0x764f80..0x764fc9` walks the same list.
-    /// A census of `+0xd4` (effectiveVisible) over the whole body `[0x764eb0, 0x76500e)` finds
-    /// **zero** hits; in `set_frame_level 0x76a4f0` the `+0xc4` write is unconditional
-    /// (`0x76a53b`) and `+0xd4` gates only the bucket relink below it (`0x76a541`).
-    ///
-    /// Gating the renumber on visibility — which benilla did, reasoning from the level lists rather
-    /// than from the bytes — is not a relabelling at all: it changes the relative order of the part
-    /// it touches against the part it does not, and that difference then rides out on the raise's
-    /// `propagate` delta, which is computed in the *new* numbering and applied to levels still
-    /// carrying the *old* one. One level of squeeze taken out of a visible child and not out of its
-    /// hidden sibling becomes a permanent inversion between two frames that are level by
-    /// construction — `parent.level + 1` for both. Gatherer's Report window is the shape that found
-    /// it: the window's visible Close button and its hidden, mouse-enabled, full-cover body are both
-    /// direct children, the body was hidden for the Show raise, and it came out one level above the
-    /// button and ate every click and hover the button should have had. The reference lands that
-    /// pair equal, and the hit sweep's tie then goes to the earlier-linked frame, the button (1816).
-    ///
-    /// So the visible gate stays where it belongs — on the *link list* (`resequence_to_tail`, draw
-    /// participation) — and off the *numbering*, which is a property of the frame.
-    ///
-    /// **The renumber is strictly order-preserving, so by itself it changes no draw order**: distinct
-    /// levels map to distinct indices monotonically and equal levels stay equal. Its whole job is to
-    /// keep the raise target *bounded* — without it, `level := max + 1` would ratchet upward one step
-    /// per raise for as long as the session lasts.
-    ///
-    /// **Ours packs tighter than the binary's, deliberately.** `bucket+0x8` is a high-water *bound*,
-    /// not a count of occupied levels, and `0x764eb0`'s cursor resumes at its saved pre-gap index
-    /// while that bound shrinks under it (`0x764fd3`/`0x764fd8`), so a wide gap carries an interior
-    /// hole past it: occupied `{0, 4, 6}` at count 7 comes out `{0, 1, 3}` at count 4, not
-    /// `{0, 1, 2}` at 3. That artifact is invisible to draw and hit order — both maps are monotone
-    /// and injective on levels, and both keep the invariant the raise needs (`count` above every
-    /// occupied level) — so we take the contiguous one rather than model a cursor bug.
-    ///
-    /// Two things it deliberately is **not**: it does not propagate (`0x764faf` passes
-    /// `propagate = 0`, so a parent/child level *offset* is not preserved across a hole either —
-    /// parent 5 / child 7 comes out adjacent), and **it does not relink**, which is a known
-    /// divergence: the binary re-levels each moved frame through `0x76a4f0` at `0x764fb6`, so every
-    /// moved *visible* frame is unlinked and re-inserted and its within-level link order is
-    /// rewritten (a hidden frame takes no list churn). We write `level` directly instead, so our
-    /// `insertion_seq` survives a compaction untouched. Nothing observed yet turns on it; it is
-    /// named in 2104 rather than changed under a bug fix.
+    /// Deviation: levels pack contiguously, because the reference's resuming cursor
+    /// (`0x764fd3`/`0x764fd8`) leaves a hole past a wide gap ({0, 4, 6} at count 7 gives {0, 1, 3}
+    /// at count 4) that no draw or hit order can see.
     pub fn compact_levels(&mut self, strata: Strata) -> u16 {
         let mut occupied: Vec<u16> = self
             .iter_frames()
@@ -200,28 +139,23 @@ impl WidgetArena {
         occupied.len() as u16
     }
 
-    // ── The toplevel flag (flag word bit 0x1) ────────────────────────────────────────────────────
+    // ── Toplevel ─────────────────────────────────────────────────────────────────────────────────
 
-    /// Set a frame's `toplevel` bit — `SetToplevel 0x775440` / XML `toplevel`, both through the pure
-    /// bit-setter `0x76a3c0` (see [`Frame::toplevel`]). A pure flag write: **it raises nothing**.
-    /// A stale handle is a no-op.
+    /// `SetToplevel` (`0x775440`) via the bit-setter `0x76a3c0`: a flag write that raises nothing.
     pub fn set_toplevel(&mut self, h: FrameHandle, toplevel: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.toplevel = toplevel;
         }
     }
 
-    /// Whether the frame carries the `toplevel` bit (`IsToplevel`). A stale handle reads as `false`.
     pub fn is_toplevel(&self, h: FrameHandle) -> bool {
         self.frame(h).is_some_and(|f| f.toplevel)
     }
 
-    // ── Scale (effective_scale) ──────────────────────────────────────────────────────────────────
+    // ── Scale ────────────────────────────────────────────────────────────────────────────────────
 
-    /// Set `h`'s own scale and recompute effective scale down the subtree, ε-gated, per
-    /// `effective_scale 0x76ac90` (`propagation.md`): `effectiveScale = parentScale * ownScale`; a
-    /// node whose new effective scale is within [`SCALE_EPS`] of its current one is skipped along
-    /// with its subtree (its children's parent-scale did not move).
+    /// Set `h`'s own scale and recompute `effective_scale = parent's * own` down the subtree
+    /// (`0x76ac90`), stopping at a frame whose value moves less than [`SCALE_EPS`].
     pub fn set_scale(&mut self, h: FrameHandle, scale: f32) {
         if let Some(f) = self.frame_mut(h) {
             f.scale = scale;
@@ -254,12 +188,8 @@ impl WidgetArena {
 
     // ── Alpha ────────────────────────────────────────────────────────────────────────────────────
 
-    /// Set `h`'s alpha and **overwrite every descendant frame's** with the same raw value — the
-    /// byte-verified 1.12 mechanism (`SetAlpha 0x76a690` writes `[this+0xc8]` then recurses the
-    /// child-frame list pushing the SAME value; wow-re `propagation.md`, CORRECTED section). An
-    /// eager set-time flatten, structurally the strata subtree-force — never a draw-time ancestor
-    /// product, so `effective_alpha` (what a renderer's one-hop region composition reads) always
-    /// equals `alpha`.
+    /// `SetAlpha` (`0x76a690`): write the raw value to `h` and every descendant frame (`+0xc8`),
+    /// with no draw-time product, so a child's own later `SetAlpha` holds until an ancestor's next.
     pub fn set_alpha(&mut self, h: FrameHandle, alpha: f32) {
         let Some(f) = self.frame_mut(h) else { return };
         f.alpha = alpha;
@@ -270,32 +200,21 @@ impl WidgetArena {
         }
     }
 
-    // ── Reparenting (reparent_begin / reparent_finish) ───────────────────────────────────────────
+    // ── Reparenting ──────────────────────────────────────────────────────────────────────────────
 
-    /// The runtime reparent, phase 1 of 2 — the guards and the **hide half** of
-    /// `CSimpleFrame::SetParent 0x76ab10`'s byte-verified sequence (wow-re
-    /// `ui/scratch/setparent-runtime-strata-level.md` §2; decision 1323, which corrects this
-    /// module's previous "strata/level are NOT changed by reparenting" — refuted at `0x76ab65`).
+    /// Phase 1 of `SetParent` (`0x76ab10`): the guards and the hide half. `None` when the parent
+    /// is unchanged (`0x76ab20` skips everything), the frame is dead, or the move would cycle (the
+    /// Lua binding raises first, `0x7a177f`); otherwise the frames that lost effective visibility,
+    /// in pre-order, whose `OnHide` runs under the old parent (`0x76ab41`).
     ///
-    /// Returns `None` for the byte-verified TOTAL no-op — `newParent == currentParent` (`0x76ab20`
-    /// skips *everything*) — and for a dead handle or a cycle (the Lua binding raises on a cycle
-    /// *before* calling here, per the binding's own inline `+0x9c` walk at `0x7a177f`; a direct
-    /// caller gets the silent reject as a backstop). Otherwise `Some(hidden)`: every frame whose
-    /// effective visibility just dropped, in pre-order — empty when the frame was not effectively
-    /// visible ("a reparent of a hidden frame fires neither" event). The caller fires `OnHide` for
-    /// those and then calls [`Self::reparent_finish`]; the hide runs while the frame still hangs
-    /// under its OLD parent, as the reference's `0x76ab41` does before the `+0x9c` store, so an
-    /// `OnHide` handler observes the old parent. (One knowing divergence: the reference unlinks
-    /// from the old parent's child list *before* the hide, so an `OnHide` calling
-    /// `oldParent:GetChildren()` no longer sees the frame there; ours still does — the relink is
-    /// phase 2's, so a handler that itself reparents can't leave the lists half-spliced.)
+    /// Deviation: the frame is still in the old parent's child list during `OnHide`, unlike the
+    /// reference, because a handler that itself reparents must not find the lists half-spliced.
     pub fn reparent_begin(
         &mut self,
         h: FrameHandle,
         new_parent: Option<FrameHandle>,
     ) -> Option<Vec<FrameHandle>> {
         self.frame(h)?;
-        // Keep only a live new parent; reject a cycle (new_parent == h or below h).
         let new_parent = new_parent.filter(|&p| self.frame(p).is_some());
         if let Some(np) = new_parent {
             if np == h || self.is_ancestor(h, np) {
@@ -312,32 +231,13 @@ impl WidgetArena {
         Some(hidden)
     }
 
-    /// Phase 2 — the relink and the rest of `0x76ab10`'s verified sequence: **strata := parent's**
-    /// (`0x76ab5a` → the value-gated subtree force of [`Self::set_frame_strata`]; MEDIUM for nil),
-    /// **level := parent.level + 1 with `propagate = 0`** (`0x76ab65`; 0 for nil), scale
-    /// re-inherit, then the **show half**. Returns the frames whose effective visibility came back
-    /// (fire `OnShow` for those, in order).
-    ///
-    /// Load-bearing consequences, each verified in the note:
-    ///
-    /// - **Existing children keep their absolute levels** (`propagate = 0`; `level_compact
-    ///   0x764eb0`'s one caller is the toplevel Raise, unreachable from here). A child created when
-    ///   the parent sat lower can land BELOW its own parent — the client ships that and nothing
-    ///   repairs it but the child's own `SetFrameLevel` (which is exactly what AtlasLoot's
-    ///   button templates do in `OnShow`, and why its browse panel works on the reference).
-    /// - **The show half is gated on `was_visible`** (`0x76abfd`: `ebx && (parent==0 ||
-    ///   parent->+0xd4)`) — the `+0xd4` cascade only runs inside `0x76ae10`, so a reparent of a
-    ///   hidden (or hidden-chained) frame does NOT recompute effective visibility: moved under a
-    ///   visible parent it stays effectively invisible until something shows it. That staleness is
-    ///   the shipped behaviour, not an oversight to "fix" here.
-    /// - The `OnShow` refire down the re-shown subtree is what lets an addon hand-repair the
-    ///   propagate-0 level law (`this:SetFrameLevel(GetParent():GetFrameLevel()+1)` in `OnShow` —
-    ///   the reference fires it via the `+0x84`/`+0x88` hide→show round-trip on any visible
-    ///   reparent).
-    ///
-    /// `was_visible` is phase 1's `!hidden.is_empty()` — the reference's `ebx`, captured at
-    /// `0x76ab2b` before anything runs. Alpha stays untouched throughout: the client only pushes
-    /// alpha at `SetAlpha` time (module alpha section).
+    /// Phase 2 of `SetParent` (`0x76ab10`): relink, strata := the parent's (`0x76ab5a`, MEDIUM for
+    /// none), level := the parent's + 1 without propagating (`0x76ab65`, 0 for none), scale
+    /// re-inherited, then the show half, returning the frames that became visible; alpha is
+    /// untouched. `h`'s own children keep their levels, so one can end up below `h`.
+    /// `was_visible` is whether phase 1 hid anything (the reference's `ebx` at `0x76ab2b`); the
+    /// show half runs only then (`0x76abfd`), so a hidden frame moved under a visible parent keeps
+    /// a stale effective visibility until something shows it.
     pub fn reparent_finish(
         &mut self,
         h: FrameHandle,
@@ -346,11 +246,11 @@ impl WidgetArena {
     ) -> Vec<FrameHandle> {
         let mut shown = Vec::new();
         if self.frame(h).is_none() {
-            return shown; // died inside an OnHide — nothing left to move
+            return shown; // died inside an OnHide: nothing to move
         }
         let new_parent = new_parent.filter(|&p| self.frame(p).is_some());
-        // Relink from the CURRENT parent (an OnHide handler may itself have reparented; the
-        // reference's unconditional `+0x9c` store at `0x76ab49` means the outer call wins).
+        // Relink from the current parent: an `OnHide` may have reparented it, and the reference's
+        // unconditional `+0x9c` store (`0x76ab49`) lets the outer call win.
         let old_parent = self.frame(h).unwrap().parent;
         if let Some(op) = old_parent {
             if let Some(of) = self.frame_mut(op) {
@@ -367,8 +267,7 @@ impl WidgetArena {
                 let pf = self.frame(np).expect("live new parent");
                 (pf.strata, pf.level.saturating_add(1))
             }
-            // SetParent(nil) is a RESET — strata 3 (MEDIUM), level 0 (`0x76aba3`/`0x76abac`) —
-            // not "keep current".
+            // `SetParent(nil)` resets to MEDIUM and level 0 (`0x76aba3`/`0x76abac`).
             None => (Strata::default(), 0),
         };
         self.set_frame_strata(h, pstrata);
@@ -382,10 +281,7 @@ impl WidgetArena {
         shown
     }
 
-    /// [`Self::reparent_begin`] + [`Self::reparent_finish`] in one call, for callers with no Lua
-    /// to fire between the halves (tests, direct arena use). Returns both phases' visibility
-    /// changes concatenated — hide half first. The Lua binding does NOT use this: it must fire
-    /// `OnHide` between the phases (the events' direction is read from live state at fire time).
+    /// Both reparent phases in one call, hide changes first, for a caller with no `OnHide` to fire.
     pub fn set_parent(
         &mut self,
         h: FrameHandle,
@@ -399,41 +295,18 @@ impl WidgetArena {
         [hidden, shown].concat()
     }
 
-    /// Re-link a **region leaf** (Texture/FontString) to a new owner frame — the arena half of
-    /// `Region:SetParent`. `None` detaches ([`super::Region::detached`]). Returns whether anything
-    /// moved (a same-owner call and a stale handle both report `false`).
-    ///
-    /// **This is a different mechanism from the frame reparent above, and the difference is
-    /// verified.** `SetParent` is one Region-table binding (`0x7a1550`) dispatching a per-class
-    /// virtual: a plain Region gets `0x76c430`, which writes the geometry parent and nothing else,
-    /// but a Texture or FontString gets `0x7733d0` → `0x77fd10`, a **full re-link** — remove from
-    /// the old parent's draw layer (`0x77fc60`) and region list (`vtbl+0x2c`), store the new
-    /// parent, insert into its region list (`0x76a750`) and re-register in its draw layer
-    /// (`0x77fcb0`), **preserving layer and sub-level** (wow-re `widget-api-batch-benilla.md` Q7).
-    /// So the layer/sub-level fields are deliberately untouched here and only the membership moves;
-    /// the fresh `decl_seq` is the "insert into the new parent's region list" half, which lands the
-    /// region at the tail of that frame's list exactly as the client's insert does.
-    ///
-    /// Nothing propagates, unlike the frame reparent: a region has no effective-visible/scale/alpha
-    /// of its own here — every reader (`IsVisible`, the measure key, `extract`'s alpha product)
-    /// resolves the owner frame's live values through [`super::Region::owner`], so re-pointing that
-    /// field *is* the propagation the client does eagerly (`0x77fd10` pushes the new parent's shown
-    /// bit into the region).
-    ///
-    /// **A same-owner call is a no-op, and that is the conservative reading, not a verified one.**
-    /// `0x77fd10` is unconditional, so the reference may re-tail a region within its own layer when
-    /// an addon re-parents it to the frame it already belongs to. Not reproducing that can only
-    /// ever *preserve* declared draw order, never invent one; and the corpus's only region
-    /// `SetParent` caller — `FuBar_FuXPFu.lua:210-211`, which re-parents two `XPBar:CreateTexture`
-    /// sparks to `XPBar` — moves both in declaration order, so the two readings agree there.
+    /// `Region:SetParent` for a texture or font string; `None` detaches. The client re-links in
+    /// full (`0x7733d0` → `0x77fd10`): out of the old parent's layer (`0x77fc60`) and list, into
+    /// the new parent's list (`0x76a750`) and layer (`0x77fcb0`), its layer kept, so the region
+    /// takes the tail `decl_seq`. Readers resolve through `owner`, so nothing propagates. A
+    /// same-owner call is a no-op, as in the reference (`0x77fd33`).
     pub fn set_region_owner(&mut self, rh: RegionHandle, new_owner: Option<FrameHandle>) -> bool {
         let Some(region) = self.region(rh) else {
             return false;
         };
         let (old_owner, was_detached) = (region.owner, region.detached);
-        // Keep only a live new owner. No cycle check: the client's (`0x7a177f`) walks the new
-        // parent's frame chain looking for the receiver, and a Texture/FontString is never a frame,
-        // so for a region it can never fire.
+        // No cycle check: the client's (`0x7a177f`) looks for the receiver in the new parent's
+        // frame chain, and a region is never a frame.
         let new_owner = new_owner.filter(|&f| self.frame(f).is_some());
         match new_owner {
             Some(f) if f == old_owner && !was_detached => return false,
@@ -441,8 +314,6 @@ impl WidgetArena {
             _ => {}
         }
         let Some(new_owner) = new_owner else {
-            // Detached: the entry stays in its last owner's list (so `destroy` still frees it) and
-            // the flag alone takes it out of the draw.
             if let Some(r) = self.region_mut(rh) {
                 r.detached = true;
             }
@@ -469,89 +340,69 @@ impl WidgetArena {
         true
     }
 
-    // ── Mouse interaction (the hit-test flag) ────────────────────────────────────────────────────
+    // ── Frame flags ──────────────────────────────────────────────────────────────────────────────
 
-    /// Set a frame's `mouse_enabled` flag (`EnableMouse`). Only mouse-enabled *and* effective-visible
-    /// frames capture the cursor in [`crate::order::hit_test`]; the default is **false** (WoW's
-    /// `enableMouse` default). A stale handle is a no-op. (Keyboard focus is a separate concern, not
-    /// modeled here yet.)
+    /// `EnableMouse`.
     pub fn set_mouse_enabled(&mut self, h: FrameHandle, enabled: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.mouse_enabled = enabled;
         }
     }
 
-    /// `EnableKeyboard` (`0x776f90`) — kind-0/kind-1 bucket membership. Stored and answered, and
-    /// it is what [`crate::script::keyboard`]'s delivery walk filters on (1319).
+    /// `EnableKeyboard` (`0x776ec0`): the char and key bits the key walk filters on.
     pub fn set_keyboard_enabled(&mut self, h: FrameHandle, enabled: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.keyboard_enabled = enabled;
         }
     }
 
-    /// Whether the frame is keyboard-enabled. A stale handle reads as `false`.
+    /// `IsKeyboardEnabled` (`0x776f90`).
     pub fn is_keyboard_enabled(&self, h: FrameHandle) -> bool {
         self.frame(h).is_some_and(|f| f.keyboard_enabled)
     }
 
-    /// `EnableMouseWheel` — the wheel's own gate, separate from the mouse's (decision 1198).
+    /// `EnableMouseWheel`, the wheel's own bit, separate from the mouse's.
     pub fn set_mouse_wheel_enabled(&mut self, h: FrameHandle, enabled: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.mouse_wheel_enabled = enabled;
         }
     }
 
-    /// Whether the frame currently accepts the wheel. A stale handle reads as `false`.
     pub fn is_mouse_wheel_enabled(&self, h: FrameHandle) -> bool {
         self.frame(h).is_some_and(|f| f.mouse_wheel_enabled)
     }
 
-    /// Whether the frame currently accepts the mouse (see [`WidgetArena::set_mouse_enabled`]). A
-    /// stale handle reads as `false`.
     pub fn is_mouse_enabled(&self, h: FrameHandle) -> bool {
         self.frame(h).map(|f| f.mouse_enabled).unwrap_or(false)
     }
 
-    // ── Clamp-to-screen (geometry flags bit4) ────────────────────────────────────────────────────
-
-    /// Set a frame's clamp-to-screen flag (`SetClampedToScreen` `0x776c00` — geometry flags bit4;
-    /// see [`Frame::clamped_to_screen`] for the tooltip-kind default). A stale handle is a no-op.
+    /// `SetClampedToScreen` (`0x776c00`).
     pub fn set_clamped_to_screen(&mut self, h: FrameHandle, clamp: bool) {
         if let Some(f) = self.frame_mut(h) {
             f.clamped_to_screen = clamp;
         }
     }
 
-    /// Whether the frame clamps to the screen (`IsClampedToScreen` `0x776cb0`). A stale handle
-    /// reads as `false`.
+    /// `IsClampedToScreen` (`0x776cb0`).
     pub fn is_clamped_to_screen(&self, h: FrameHandle) -> bool {
         self.frame(h).map(|f| f.clamped_to_screen).unwrap_or(false)
     }
 
-    // ── Hit-rect insets (the mouse rect, not the draw rect) ──────────────────────────────────────
-
-    /// Set a frame's hit-rect insets, `[left, right, top, bottom]` (`SetHitRectInsets`; see
-    /// [`Frame::hit_rect_insets`]). A stale handle is a no-op.
+    /// `SetHitRectInsets`, `[left, right, top, bottom]`.
     pub fn set_hit_rect_insets(&mut self, h: FrameHandle, insets: [f32; 4]) {
         if let Some(f) = self.frame_mut(h) {
             f.hit_rect_insets = insets;
         }
     }
 
-    /// A frame's hit-rect insets, `[left, right, top, bottom]` (`GetHitRectInsets`). A stale handle
-    /// reads as all-zero — the same "no inset" answer an untouched frame gives.
+    /// `GetHitRectInsets`, `[left, right, top, bottom]`.
     pub fn hit_rect_insets(&self, h: FrameHandle) -> [f32; 4] {
         self.frame(h).map(|f| f.hit_rect_insets).unwrap_or([0.0; 4])
     }
 
     // ── Small helpers ────────────────────────────────────────────────────────────────────────────
 
-    /// Is `maybe_ancestor` on the parent chain of `node` (walking up, loop-guarded)? — the client's
-    /// `is_descendant 0x767010`, read the other way round.
-    ///
-    /// Two callers, and they are the two the binary has: [`WidgetArena::set_parent`]'s cycle guard,
-    /// and the raise's overlap scan, which excludes the raised frame's own subtree from the frames
-    /// it may be considered to overlap ([`crate::script::object::toplevel`]).
+    /// Whether `maybe_ancestor` is on `node`'s parent chain (`0x767010`, read the other way round).
     pub fn is_ancestor(&self, maybe_ancestor: FrameHandle, node: FrameHandle) -> bool {
         let mut cur = self.frame(node).and_then(|f| f.parent);
         let mut guard = 0usize;
@@ -562,7 +413,7 @@ impl WidgetArena {
             cur = self.frame(c).and_then(|f| f.parent);
             guard += 1;
             if guard > self.frames.slots.len() {
-                break; // defensive; a well-formed tree never loops
+                break; // a well-formed tree never loops
             }
         }
         false
diff --git a/crates/benilla-ui/src/widget/tests.rs b/crates/benilla-ui/src/widget/tests.rs
index eb2c857c..3dcbfdc0 100644
--- a/crates/benilla-ui/src/widget/tests.rs
+++ b/crates/benilla-ui/src/widget/tests.rs
@@ -1,8 +1,4 @@
-//! Rust-driven tests of [`super::WidgetArena`]'s propagation mutators: effective visibility,
-//! strata subtree-force, level delta-shift, scale propagation, reparenting, the named registry, and
-//! the byte-verified alpha overwrite-cascade. Split out alongside the propagation mutators purely
-//! for size — the tests exercise both `super` (create/destroy) and `super::propagation` (the
-//! mutators) through the one public `WidgetArena` surface.
+//! Tests of [`super::WidgetArena`]'s mutators and registries.
 
 use super::*;
 
@@ -22,7 +18,6 @@ fn hide_show_toggles_effective_visibility_and_reports_changes() {
     assert_eq!(changed, vec![root]);
     assert!(!a.frame(root).unwrap().effective_visible);
 
-    // Hiding again is a no-op (already hidden).
     assert!(a.set_shown(root, false).is_empty());
 
     let changed = a.set_shown(root, true);
@@ -38,7 +33,6 @@ fn mid_tree_hide_blocks_a_shown_grandchild() {
     let grand = a.create(FrameKind::Frame, None, Some(child));
     assert!(a.frame(grand).unwrap().effective_visible);
 
-    // Hide the middle frame: child + grand lose effective visibility, though both are `shown`.
     let changed = a.set_shown(child, false);
     assert_eq!(changed, vec![child, grand]); // pre-order
     assert!(a.frame(root).unwrap().effective_visible);
@@ -49,7 +43,6 @@ fn mid_tree_hide_blocks_a_shown_grandchild() {
         "grandchild's own shown bit is untouched"
     );
 
-    // Re-show the middle: both come back.
     let changed = a.set_shown(child, true);
     assert_eq!(changed, vec![child, grand]);
     assert!(a.frame(grand).unwrap().effective_visible);
@@ -62,13 +55,12 @@ fn hidden_grandchild_stays_hidden_when_ancestor_reshows() {
     let child = a.create(FrameKind::Frame, None, Some(root));
     let grand = a.create(FrameKind::Frame, None, Some(child));
 
-    a.set_shown(grand, false); // grand's own shown = false
-    let changed = a.set_shown(root, false); // hide the top
-                                            // grand was already effectively invisible, so it does NOT re-report on the hide.
+    a.set_shown(grand, false);
+    let changed = a.set_shown(root, false);
+    // grand is already invisible, so the hide does not report it.
     assert_eq!(changed, vec![root, child]);
 
-    let changed = a.set_shown(root, true); // re-show top
-                                           // child comes back; grand stays hidden (its own shown is false).
+    let changed = a.set_shown(root, true);
     assert_eq!(changed, vec![root, child]);
     assert!(a.frame(child).unwrap().effective_visible);
     assert!(!a.frame(grand).unwrap().effective_visible);
@@ -97,13 +89,11 @@ fn set_level_delta_shifts_same_strata_children_only() {
     let root = a.create(FrameKind::Frame, None, None);
     let same = a.create(FrameKind::Frame, None, Some(root));
     let cross = a.create(FrameKind::Frame, None, Some(root));
-    // root level 0; give the children distinct levels to prove the *delta* (relative offset) is
-    // preserved, not the absolute value.
+    // Distinct child levels show the delta is kept, not the absolute level.
     a.set_frame_level(same, 5, true);
     a.set_frame_level(cross, 2, true);
-    a.set_frame_strata(cross, Strata::High); // move `cross` to another strata
+    a.set_frame_strata(cross, Strata::High);
 
-    // Raise root by +10 with propagation.
     a.set_frame_level(root, 10, true);
     assert_eq!(a.frame(root).unwrap().level, 10);
     assert_eq!(
@@ -124,8 +114,8 @@ fn level_shift_saturates_at_zero() {
     let root = a.create(FrameKind::Frame, None, None);
     let child = a.create(FrameKind::Frame, None, Some(root));
     a.set_frame_level(root, 10, true);
-    a.set_frame_level(child, 12, true); // child two above root
-                                        // Drop root to 0 (delta -10): child would be 2.
+    a.set_frame_level(child, 12, true);
+    // Root drops by 10, taking the child from 12 to 2.
     a.set_frame_level(root, 0, true);
     assert_eq!(a.frame(child).unwrap().level, 2);
 }
@@ -154,12 +144,10 @@ fn scale_epsilon_gate_skips_subthreshold_change() {
     let mut a = arena();
     let root = a.create(FrameKind::Frame, None, None);
     let child = a.create(FrameKind::Frame, None, Some(root));
-    // Set a marker on the child's effective scale we can detect being (not) overwritten.
     a.set_scale(child, 4.0);
     assert_eq!(a.frame(child).unwrap().effective_scale, 4.0);
 
-    // Nudge root by less than ε: effective scale of root barely moves, so the recursion into the
-    // child is pruned and the child keeps its exact prior value.
+    // A sub-ε change to the root prunes the recursion, so the child keeps its exact value.
     let tiny = 1.0 + (SCALE_EPS as f32) / 4.0;
     a.set_scale(root, tiny);
     assert_eq!(
@@ -184,7 +172,6 @@ fn reparent_reinherits_visibility_and_scale() {
     assert!(a.frame(child).unwrap().effective_visible);
     assert_eq!(a.frame(child).unwrap().effective_scale, 3.0);
 
-    // Move under the hidden parent: child loses visibility and re-inherits scale 2.0.
     let changed = a.set_parent(child, Some(hidden));
     assert_eq!(changed, vec![child]);
     assert!(!a.frame(child).unwrap().effective_visible);
@@ -201,7 +188,6 @@ fn reparent_cycle_is_rejected() {
     let mut a = arena();
     let root = a.create(FrameKind::Frame, None, None);
     let child = a.create(FrameKind::Frame, None, Some(root));
-    // Making root a child of its own child would cycle — rejected, no-op.
     let changed = a.set_parent(root, Some(child));
     assert!(changed.is_empty());
     assert_eq!(a.frame(root).unwrap().parent, None);
@@ -216,7 +202,6 @@ fn named_registry_is_non_overwriting() {
     let first = a.create(FrameKind::Frame, Some("MyFrame".into()), None);
     let second = a.create(FrameKind::Frame, Some("MyFrame".into()), None);
     assert_ne!(first, second);
-    // The first writer owns the name; the duplicate still carries its own `name` field.
     assert_eq!(a.lookup("MyFrame"), Some(first));
     assert_eq!(a.frame(second).unwrap().name.as_deref(), Some("MyFrame"));
 }
@@ -243,13 +228,12 @@ fn generational_handle_detects_reuse() {
     let mut a = arena();
     let h = a.create(FrameKind::Frame, None, None);
     a.destroy(h);
-    // A new frame may reuse the slot; the old handle must not resolve to it.
     let h2 = a.create(FrameKind::Frame, None, None);
     assert!(a.frame(h).is_none());
     assert!(a.frame(h2).is_some());
 }
 
-// ── Alpha (the byte-verified overwrite-cascade, SetAlpha 0x76a690) ───────────────────────────
+// ── Alpha ────────────────────────────────────────────────────────────────────────────────────
 
 #[test]
 fn set_alpha_overwrites_the_subtree() {
@@ -258,27 +242,23 @@ fn set_alpha_overwrites_the_subtree() {
     let child = a.create(FrameKind::Frame, None, Some(root));
     let grandchild = a.create(FrameKind::Frame, None, Some(child));
     a.set_alpha(root, 0.5);
-    // The same raw value lands on every descendant frame (a flatten, not a product).
     for h in [root, child, grandchild] {
         assert_eq!(a.frame(h).unwrap().alpha, 0.5);
         assert_eq!(a.frame(h).unwrap().effective_alpha, 0.5);
     }
-    // Last write wins: a child's own later SetAlpha diverges until the parent sets again…
+    // Last write wins: the child's own SetAlpha holds until the parent sets again.
     a.set_alpha(child, 1.0);
     assert_eq!(a.frame(root).unwrap().effective_alpha, 0.5);
     assert_eq!(a.frame(child).unwrap().effective_alpha, 1.0);
     assert_eq!(a.frame(grandchild).unwrap().effective_alpha, 1.0);
-    // …and a frame created under a dimmed parent starts at 1.0 (creation doesn't re-push).
+    // A frame created under a dimmed parent starts at 1.0.
     let late = a.create(FrameKind::Frame, None, Some(root));
     assert_eq!(a.frame(late).unwrap().effective_alpha, 1.0);
 }
 
 // ── The per-kind registries ──────────────────────────────────────────────────────────────────
 
-/// The tooltip registry is exactly the live GameTooltips — including when one dies as somebody
-/// else's child, which is the case a registry maintained only at the explicit `destroy` call site
-/// would miss. Three hot paths read it instead of scanning the resolve's roster (decision 1634), so
-/// a stale entry is a dangling handle in the layout pre-pass, not a cosmetic drift.
+/// Includes a tooltip destroyed as another frame's child.
 #[test]
 fn the_tooltip_registry_tracks_live_gametooltips() {
     let mut a = arena();
@@ -287,11 +267,9 @@ fn the_tooltip_registry_tracks_live_gametooltips() {
     let holder = a.create(FrameKind::Frame, None, None);
     let loose = a.create(FrameKind::GameTooltip, None, None);
     let child = a.create(FrameKind::GameTooltip, None, Some(holder));
-    // A non-tooltip kind never enters the list.
     let _plain = a.create(FrameKind::Button, None, None);
     assert_eq!(a.tooltip_kinds(), &[loose, child]);
 
-    // Destroying the PARENT takes its tooltip child with it.
     a.destroy(holder);
     assert_eq!(a.tooltip_kinds(), &[loose]);
 
diff --git a/crates/benilla-visual/Cargo.toml b/crates/benilla-visual/Cargo.toml
index 266d5ea7..72fe52a4 100644
--- a/crates/benilla-visual/Cargo.toml
+++ b/crates/benilla-visual/Cargo.toml
@@ -3,13 +3,12 @@ name = "benilla-visual"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "Perceptual image diff for the Phase-5 visual A/B render harness (decision 0008)"
+description = "Perceptual image diff for the visual A/B render harness"
 
 [lints]
 workspace = true
 
 [dependencies]
 anyhow.workspace = true
-# PNG-only image IO + the RgbImage buffer the metrics run over. No Bevy — this is the pure-math half of
-# the harness, so it compiles fast and runs under `cargo test --workspace`.
+# PNG IO and the `RgbImage` buffer the metrics run over; no Bevy, so the crate stays fast to test.
 image = { version = "0.25", default-features = false, features = ["png"] }
diff --git a/crates/benilla-visual/src/lib.rs b/crates/benilla-visual/src/lib.rs
index fc8c6da4..d50cb0c3 100644
--- a/crates/benilla-visual/src/lib.rs
+++ b/crates/benilla-visual/src/lib.rs
@@ -1,45 +1,31 @@
-//! Perceptual image-diff metrics for the Phase-5 visual A/B render harness (decision 0008).
-//!
-//! The harness captures deterministic screenshots of benilla (`$WOW_CAPTURE`, see the `capture` module
-//! in the `benilla` crate) and diffs them. This crate is the pure-math half: given two equally-sized
-//! images it reports how far they diverge ([`Metrics`]) and renders a heatmap of *where* ([`diff_image`]).
-//!
-//! Three uses, one tool: (1) **self-regression** — capture baselines on the current pipeline, then diff
-//! every linear-HDR rework step against them so a machine catches a regression before the director's
-//! eye; (2) **determinism check** — diffing two captures of the same scenario must come out ≈0, which is
-//! what makes (1) trustworthy; (3) **flicker** ([`envelope`]) — the same arithmetic over *time* instead
-//! of over versions: a burst of adjacent frames from a parked camera (`WOW_LIVE_SHOT_COUNT`), collapsed
-//! to where the picture would not hold still.
+//! Image-diff metrics for the capture harness (`WOW_CAPTURE`, the `capture` module in
+//! `benilla-app`): how far two equal-size images diverge ([`Metrics`]) and where ([`diff_image`]),
+//! and over a burst of frames, which pixels would not hold still ([`envelope`], [`toggles`]).
 
 pub mod relight;
 
 use image::RgbImage;
 
-/// A pixel counts as "changed" for [`Metrics::pct_over`] if any channel differs by more than this many
-/// byte units. 8/255 ≈ 3% — above dithering/rounding noise, below a real visual shift.
+/// A pixel counts toward [`Metrics::pct_over`] when a channel differs by more than this (8/255,
+/// about 3%): above dithering noise, below a real visual shift.
 pub const OVER_THRESHOLD: u8 = 8;
 
-/// Per-image difference metrics. Channel deltas are in 0..255 byte units; `pct_over` is a fraction 0..1.
+/// Per-image difference metrics: channel deltas in 0..255 byte units, fractions in 0..1.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Metrics {
-    /// Mean absolute per-channel difference (0..255). The headline "how different" number.
+    /// Mean absolute per-channel difference (0..255).
     pub mae: f64,
-    /// Root-mean-square per-channel difference (0..255) — weights large local deltas more than `mae`.
+    /// Root-mean-square per-channel difference (0..255), weighting large local deltas.
     pub rmse: f64,
     /// Largest single-channel difference anywhere (0..255).
     pub max_delta: u8,
     /// Fraction of pixels (0..1) whose largest channel delta exceeds [`OVER_THRESHOLD`].
     pub pct_over: f64,
-    /// How many pixels differ **at all** (any channel, by any amount).
-    ///
-    /// The number that separates "a render changed" from "a silhouette pixel landed on the other
-    /// side of an MSAA tie": both read as a scary `max_delta` and an `mae` of 0.000, and only the
-    /// count tells them apart. A handful of pixels in a 5.76 M-pixel frame is a tie flipping with
-    /// the binary; a region is a regression. Answering that used to take a hand-rolled PNG
-    /// decoder in a scratchpad, every time.
+    /// Pixels that differ at all: a handful is an MSAA tie flipping, a region a regression, though
+    /// both show a large `max_delta` and an `mae` of 0.000.
     pub changed: u64,
-    /// Where the largest delta is, `(x, y)` — `(0, 0)` when nothing differs. A tie flip recurs at
-    /// the *same* coordinate build after build, which is most of the evidence that it is one.
+    /// Where the largest delta is, `(0, 0)` when nothing differs; a tie flip recurs at the same
+    /// spot build after build.
     pub worst_at: (u32, u32),
 }
 
@@ -90,9 +76,7 @@ pub fn compare(a: &RgbImage, b: &RgbImage) -> anyhow::Result<Metrics> {
     })
 }
 
-/// Render an amplified per-channel abs-difference image: each output channel is `|a-b| * amplify`,
-/// clamped to 255. This colourises both *where* and *in which channel* the images diverge (a red shift
-/// shows red), so the diff is readable at a glance. Errors on a size mismatch.
+/// The per-channel difference `|a - b| * amplify`, clamped to 255, so a red shift shows red.
 pub fn diff_image(a: &RgbImage, b: &RgbImage, amplify: u32) -> anyhow::Result<RgbImage> {
     if a.dimensions() != b.dimensions() {
         anyhow::bail!(
@@ -114,12 +98,12 @@ pub fn diff_image(a: &RgbImage, b: &RgbImage, amplify: u32) -> anyhow::Result<Rg
     Ok(out)
 }
 
-/// How far a burst of frames moved, and where — the output of [`envelope`].
+/// How far a burst of frames moved, and where: [`envelope`]'s output.
 #[derive(Debug, Clone)]
 pub struct Envelope {
-    /// Per-channel `(max − min)` across the stack, amplified — the picture of *where* it flickers.
+    /// Per-channel `max - min` across the stack, amplified.
     pub image: RgbImage,
-    /// Largest single-channel swing anywhere (0..255). The headline "does it flicker at all".
+    /// Largest single-channel swing anywhere (0..255).
     pub max_swing: u8,
     /// Mean per-channel swing (0..255) over the whole frame.
     pub mean_swing: f64,
@@ -127,14 +111,9 @@ pub struct Envelope {
     pub pct_unstable: f64,
 }
 
-/// Collapse a burst of equally-sized frames to their per-pixel **envelope** — `max − min` per channel
-/// across the whole stack. This is the flicker instrument: a still image cannot show a temporal
-/// artefact, but the envelope of adjacent frames from a *parked* camera can, and it localises the
-/// unstable pixels in one picture instead of `n−1` pairwise diffs.
-///
-/// A pixel that holds still contributes 0 whatever its colour, so a scene that is merely *wrong* comes
-/// out black — only what refuses to settle lights up. Errors on fewer than two frames or a size
-/// mismatch.
+/// A burst's per-pixel envelope, `max - min` per channel across the whole stack: from a parked
+/// camera only what refuses to settle lights up, however wrong a still pixel is. Errors on fewer
+/// than two frames or a size mismatch.
 pub fn envelope(frames: &[RgbImage], amplify: u32) -> anyhow::Result<Envelope> {
     let (w, h) = burst_dimensions(frames, 2)?;
     let mut image = RgbImage::new(w, h);
@@ -169,38 +148,26 @@ pub fn envelope(frames: &[RgbImage], amplify: u32) -> anyhow::Result<Envelope> {
     })
 }
 
-/// How often a burst *reversed direction*, and where — the output of [`toggles`].
+/// How often a burst reversed direction, and where: [`toggles`]'s output.
 #[derive(Debug, Clone)]
 pub struct Toggles {
-    /// Per-channel reversal count across the stack, amplified — the picture of *where* it toggles.
+    /// Per-channel reversal count across the stack, amplified.
     pub image: RgbImage,
-    /// Most reversals any one channel made (0..frames−2).
+    /// Most reversals any one channel made (0..frames-2).
     pub max_reversals: u32,
     /// Fraction of pixels (0..1) that reversed at least [`TOGGLE_MIN_REVERSALS`] times.
     pub pct_toggling: f64,
-    /// Row-major `width × height` flags: did this pixel toggle? Carried out of the scan because
-    /// *where* the toggling pixels sit relative to each other is a separate reading ([`shape`]) and
-    /// re-thresholding the amplified image would only recover it approximately.
+    /// Row-major per-pixel toggle flags for [`shape`], exact where re-thresholding `image` is not.
     pub mask: Vec<bool>,
 }
 
-/// A pixel counts as "toggling" for [`Toggles::pct_toggling`] at this many direction reversals. Two
-/// is the smallest count that cannot be a single overshoot, and it already needs a four-frame
-/// up-down-up run — which smooth motion across an edge does not produce.
+/// Direction reversals that make a pixel toggle: two cannot be a single overshoot, and smooth
+/// motion across an edge never makes the up-down-up run they need.
 pub const TOGGLE_MIN_REVERSALS: u32 = 2;
 
-/// Count, per pixel and channel, how many times the value **reversed direction** across the burst,
-/// ignoring steps smaller than `min_delta`.
-///
-/// This is [`envelope`]'s companion for the case the envelope cannot serve: **a moving camera**.
-/// When the view is panning, every edge in the frame sweeps across pixels and `max − min` lights up
-/// the whole picture, so it says nothing. But smooth motion is *monotone* — a pixel being crossed by
-/// an edge goes one way and stays going that way — while z-fighting and an unstable draw order
-/// **alternate**, A/B/A/B, however the camera moves. Counting reversals separates the two.
-///
-/// The director's report is what forced this: the Far Watch Post tower "mostly only flickers while
-/// moving the cam, not while still" — the one condition under which a parked burst is blind by
-/// construction (decision 0653's blind spot, named in 0656).
+/// Count, per pixel and channel, the direction reversals across the burst, ignoring steps under
+/// `min_delta`: the flicker reading for a moving camera. Smooth motion is monotone; z-fighting and
+/// an unstable draw order alternate however the camera moves.
 pub fn toggles(frames: &[RgbImage], min_delta: u8, amplify: u32) -> anyhow::Result<Toggles> {
     let (w, h) = burst_dimensions(frames, 3)?;
     let mut image = RgbImage::new(w, h);
@@ -210,8 +177,7 @@ pub fn toggles(frames: &[RgbImage], min_delta: u8, amplify: u32) -> anyhow::Resu
     for (x, y, out) in image.enumerate_pixels_mut() {
         let mut pixel_max = 0u32;
         for c in 0..3 {
-            // `dir` is the sign of the last step big enough to count; a run of sub-threshold steps
-            // neither reverses nor resets it, so dithering noise cannot manufacture a toggle.
+            // `dir` is the last counted step's sign; smaller steps neither reverse nor reset it.
             let (mut dir, mut reversals) = (0i8, 0u32);
             for pair in frames.windows(2) {
                 let (a, b) = (
@@ -246,7 +212,7 @@ pub fn toggles(frames: &[RgbImage], min_delta: u8, amplify: u32) -> anyhow::Resu
     })
 }
 
-/// A rectangle of the frame, in pixels — `x1`/`y1` exclusive.
+/// A rectangle of the frame in pixels, `x1` and `y1` exclusive.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Rect {
     pub x0: u32,
@@ -279,10 +245,7 @@ pub struct Region {
     pub bounds: Rect,
     /// Toggling pixels in the run (≤ the bounds' area).
     pub pixels: u64,
-    /// Up to [`REGION_SAMPLES`] pixels spread evenly through the run, in scan order — coordinates
-    /// Every pixel in the run, in scan order. Kept whole because the run's *own* time series
-    /// ([`Region::steps`]) is the reading that follows, and it has to be over the run, not over a
-    /// bounding box that also contains whatever else was passing through.
+    /// Every pixel in the run, in scan order; [`Region::steps`] reads these, not the bounding box.
     pub members: Vec<(u32, u32)>,
 }
 
@@ -292,33 +255,25 @@ pub const REGION_SAMPLES: usize = 8;
 /// One frame-to-frame step of a run, from [`Region::steps`].
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Step {
-    /// The run's mean luma (0..255) in the earlier frame. The *level*, not just the change: a
-    /// two-state flip's ratio is what identifies the multiplier behind it, and a delta alone hides it.
+    /// The run's mean luma (0..255) in the earlier frame.
     pub mean_from: f64,
-    /// The run's mean R/G/B (0..255) in the earlier frame. Whether a two-state flip preserves the
-    /// channel ratios says what kind of flip it is: a pure **intensity** scale (one light term
-    /// switching on or off) keeps the hue, while swapping to a differently-coloured lighting lane
-    /// does not — and luma alone cannot tell those apart.
+    /// The run's mean R, G and B (0..255) in the earlier frame.
     pub mean_rgb_from: [f64; 3],
     /// Change in the run's mean luma (0..255 units) from this frame to the next.
     pub mean_delta: f64,
-    /// Fraction of the run's pixels (0..1) that moved the **same way** as the mean did. Near 1 = the
-    /// whole surface changed together; near 0.5 = as many pixels went up as down.
+    /// Fraction of the run's pixels (0..1) that moved the same way as the mean: near 1 the surface
+    /// changed together, near 0.5 as many went up as down.
     pub agreement: f64,
 }
 
 impl Region {
-    /// How much of its own bounding box the run actually fills, 0..1. A solid surface approaches 1;
-    /// a scattering of speckles inside a wide box is near 0.
+    /// How much of its bounding box the run fills, 0..1: a solid surface nears 1, speckle 0.
     pub fn fill(&self) -> f64 {
         let area = u64::from(self.bounds.width()) * u64::from(self.bounds.height());
         self.pixels as f64 / area.max(1) as f64
     }
 
-    /// Up to [`REGION_SAMPLES`] pixels spread evenly through the run — coordinates that are
-    /// *provably* in it, to hand to the in-game ray pick (`WOW_PICK`). Reading them off a heatmap by
-    /// eye lands next to the run as often as in it, and then the pick names the wrong surface with
-    /// total confidence.
+    /// Up to [`REGION_SAMPLES`] pixels spread through the run, for the ray pick (`WOW_PICK`).
     pub fn samples(&self) -> Vec<(u32, u32)> {
         let step = (self.members.len() / REGION_SAMPLES).max(1);
         self.members
@@ -329,14 +284,9 @@ impl Region {
             .collect()
     }
 
-    /// The run's own frame-to-frame time series — the reading that separates a surface being
-    /// **re-shaded** from one whose **edges are moving**.
-    ///
-    /// [`shape`] says the toggling pixels form one coherent surface; it cannot say what the surface
-    /// is doing. If the whole run brightens and dims together (`agreement` near 1, `mean_delta`
-    /// swinging), it is being lit differently frame to frame — a shading defect. If half its pixels
-    /// go up while the other half go down (`agreement` near 0.5, `mean_delta` near 0), nothing is
-    /// being re-lit: a boundary is sweeping across it, and the run is an edge, not a surface.
+    /// The run's frame-to-frame series: the whole run brightening and dimming together (`agreement`
+    /// near 1) is a surface re-shaded; half up and half down (`agreement` near 0.5, `mean_delta`
+    /// near 0) is an edge sweeping across it.
     pub fn steps(&self, frames: &[RgbImage]) -> Vec<Step> {
         frames
             .windows(2)
@@ -358,8 +308,7 @@ impl Region {
                     .collect();
                 let n = deltas.len().max(1) as f64;
                 let mean_delta = deltas.iter().sum::<f64>() / n;
-                // A pixel that did not move is counted as disagreeing: it is evidence against "the
-                // whole surface moved together", which is exactly the claim under test.
+                // A pixel that did not move counts against the surface moving together.
                 let same = deltas
                     .iter()
                     .filter(|d| **d != 0.0 && d.is_sign_positive() == mean_delta.is_sign_positive())
@@ -375,33 +324,26 @@ impl Region {
     }
 }
 
-/// Rec. 601 luma — one number per pixel for "how bright", so a colour shift and a brightness shift
-/// are not confused with each other.
+/// Rec. 601 luma.
 fn luma(p: &image::Rgb<u8>) -> f64 {
     0.299 * f64::from(p[0]) + 0.587 * f64::from(p[1]) + 0.114 * f64::from(p[2])
 }
 
-/// The **spatial** structure of a toggle map — the reading that separates two defects the toggle
-/// percentage alone cannot tell apart.
-///
-/// Both z-fighting and a visibility flip make pixels alternate, so both score the same on
-/// [`Toggles::pct_toggling`]. They differ in *shape*: z-fighting resolves per fragment, so it lands
-/// as moiré banding or speckle — many small runs, low neighbour agreement. A whole surface blinking
-/// in and out (a culling, portal-visibility or draw-submission flip) lands as **one large solid run**
-/// with the surface's own silhouette — few runs, high fill, high coherence. That distinction decides
-/// which subsystem is at fault, so it is measured rather than eyeballed off a heatmap.
+/// The spatial structure of a toggle map. Z-fighting resolves per fragment, landing as many small
+/// runs of low coherence; a whole surface blinking (a culling, portal-visibility or draw-submission
+/// flip) lands as one large solid run. Both score the same on [`Toggles::pct_toggling`].
 #[derive(Debug, Clone, PartialEq)]
 pub struct Shape {
     /// Connected runs of at least [`MIN_REGION_PIXELS`], largest first.
     pub regions: Vec<Region>,
     /// Toggling pixels that fell in runs too small to list.
     pub scattered: u64,
-    /// Mean fraction of the 4-neighbours of a toggling pixel that also toggle, 0..1. Near 1 = solid
-    /// areas; near 0 = isolated pixels. A one-pixel-wide moiré band sits near 0.5.
+    /// Mean fraction of a toggling pixel's 4-neighbours that also toggle, 0..1: solid areas near 1,
+    /// isolated pixels near 0, a one-pixel moiré band near 0.5.
     pub coherence: f64,
 }
 
-/// A connected run smaller than this is noise, not a surface — counted in [`Shape::scattered`].
+/// A run smaller than this is noise, counted in [`Shape::scattered`].
 pub const MIN_REGION_PIXELS: u64 = 16;
 
 /// Group a toggle mask into connected runs (4-connectivity) and measure their coherence.
@@ -418,8 +360,7 @@ pub fn shape(t: &Toggles) -> Shape {
                 continue;
             }
             toggling += 1;
-            // Off-frame neighbours count as non-toggling: an edge pixel is genuinely less enclosed,
-            // and pretending otherwise would inflate the coherence of anything touching the border.
+            // Off-frame neighbours count as non-toggling, so a run on the border is not inflated.
             let n = u64::from(x > 0 && t.mask[idx(x - 1, y)])
                 + u64::from(x + 1 < wu && t.mask[idx(x + 1, y)])
                 + u64::from(y > 0 && t.mask[idx(x, y - 1)])
@@ -428,7 +369,7 @@ pub fn shape(t: &Toggles) -> Shape {
         }
     }
 
-    // Iterative flood fill — a recursive one blows the stack on a full-screen region.
+    // Iterative: a recursive flood fill overflows the stack on a full-screen region.
     let mut seen = vec![false; wu * hu];
     let mut regions: Vec<Region> = Vec::new();
     let mut scattered = 0u64;
@@ -477,8 +418,7 @@ pub fn shape(t: &Toggles) -> Shape {
                 }
             }
             if pixels >= MIN_REGION_PIXELS {
-                // The flood fill visits in stack order, so sort to scan order — otherwise
-                // `Region::samples` spreads its picks through the traversal, not through the run.
+                // Scan order, so `Region::samples` spreads through the run, not the traversal.
                 members.sort_unstable_by_key(|&(x, y)| (y, x));
                 regions.push(Region {
                     bounds: b,
@@ -510,11 +450,8 @@ pub fn crop(img: &RgbImage, rect: Rect) -> RgbImage {
     })
 }
 
-/// Magnify by an integer factor, nearest-neighbour — every output pixel is a source pixel verbatim.
-/// This is the only scaling the `crop` subcommand offers on purpose: a resampler blends neighbours,
-/// and a blended edge has already minted a false finding once (a `sips` downscale's "magenta
-/// fringe" read as a render defect). Zoom may enlarge, never shrink: measurements happen at source
-/// resolution or not at all.
+/// Magnify by an integer factor, nearest-neighbour, so every output pixel is a source pixel: a
+/// resampler's blended edge reads as a render defect. It never shrinks.
 pub fn zoom(img: &RgbImage, factor: u32) -> RgbImage {
     let s = factor.max(1);
     RgbImage::from_fn(img.width() * s, img.height() * s, |x, y| {
@@ -522,8 +459,7 @@ pub fn zoom(img: &RgbImage, factor: u32) -> RgbImage {
     })
 }
 
-/// Lay tiles out left-to-right, top-to-bottom in a `cols`-wide grid on a mid-grey mat, so a burst's
-/// crops read as one contact sheet. Tiles of different sizes are placed at their own size.
+/// Lay tiles out in a `cols`-wide grid on a dark grey mat, one contact sheet; each keeps its size.
 pub fn contact_strip(tiles: &[RgbImage], cols: u32, gap: u32) -> RgbImage {
     let cols = cols.max(1);
     let (tw, th) = tiles
@@ -545,7 +481,6 @@ pub fn contact_strip(tiles: &[RgbImage], cols: u32, gap: u32) -> RgbImage {
     out
 }
 
-/// The common size of a burst, erroring unless it has at least `min` equally-sized frames.
 fn burst_dimensions(frames: &[RgbImage], min: usize) -> anyhow::Result<(u32, u32)> {
     if frames.len() < min {
         anyhow::bail!("needs at least {min} frames, got {}", frames.len());
@@ -563,9 +498,7 @@ fn burst_dimensions(frames: &[RgbImage], min: usize) -> anyhow::Result<(u32, u32
     Ok((w, h))
 }
 
-/// Stitch two images side by side (`left | right`) with a `gap`-px dark separator, for at-a-glance A/B
-/// comparison (e.g. the faithful vs modern render). Heights may differ; the output is the max height
-/// with each image top-aligned.
+/// Stitch two images side by side with a `gap`-px dark separator, top-aligned at the taller height.
 pub fn compose_side_by_side(left: &RgbImage, right: &RgbImage, gap: u32) -> RgbImage {
     let h = left.height().max(right.height());
     let w = left.width() + gap + right.width();
@@ -596,9 +529,6 @@ mod tests {
         assert_eq!(m.worst_at, (0, 0));
     }
 
-    /// The single-pixel case this exists for: one silhouette pixel on the wrong side of an MSAA
-    /// tie. `mae` rounds to 0.000 and `pct_over` to 0.00% in a frame this size, so the *only*
-    /// signals that separate it from a real render change are the count and the coordinate.
     #[test]
     fn one_flipped_pixel_is_counted_and_located() {
         let a = solid(100, 80, [40, 40, 40]);
@@ -613,8 +543,7 @@ mod tests {
 
     #[test]
     fn constant_offset_matches_offset() {
-        // Every channel of `b` is 10 below `a`, so mae == rmse == max_delta == 10, and (10 > 8) so
-        // every pixel is "over" → pct_over == 1.
+        // `b` is 10 below `a`: mae == rmse == max_delta == 10, and 10 > 8 puts every pixel over.
         let a = solid(8, 5, [100, 100, 100]);
         let b = solid(8, 5, [90, 90, 90]);
         let m = compare(&a, &b).unwrap();
@@ -626,7 +555,6 @@ mod tests {
 
     #[test]
     fn small_offset_is_under_threshold() {
-        // A 5-byte shift is below OVER_THRESHOLD (8), so no pixel counts as changed even though mae>0.
         let a = solid(8, 5, [100, 100, 100]);
         let b = solid(8, 5, [95, 95, 95]);
         let m = compare(&a, &b).unwrap();
@@ -650,8 +578,6 @@ mod tests {
 
     #[test]
     fn zoom_is_pixel_verbatim() {
-        // A 2x1 two-colour image zoomed ×3: every output pixel must be one of the two source
-        // values, block-aligned — any third colour would mean a resampler blended an edge.
         let mut img = solid(2, 1, [10, 20, 30]);
         img.put_pixel(1, 0, Rgb([200, 100, 50]));
         let z = zoom(&img, 3);
@@ -687,8 +613,6 @@ mod tests {
 
     #[test]
     fn a_still_burst_has_no_envelope() {
-        // The point of max−min: a scene that never moves comes out black however bright it is, so a
-        // merely *wrong* render cannot masquerade as a flickering one.
         let img = solid(4, 4, [200, 30, 90]);
         let e = envelope(&[img.clone(), img.clone(), img], 8).unwrap();
         assert_eq!(e.max_swing, 0);
@@ -699,9 +623,7 @@ mod tests {
 
     #[test]
     fn envelope_spans_the_whole_stack_not_just_neighbours() {
-        // 10 → 60 → 10: consecutive pairs each swing 50, and so does the envelope. But a value that
-        // drifts monotonically (10 → 35 → 60) swings only 25 per pair while the envelope still says
-        // 50 — which is the reason this is a stack operation and not a chain of pairwise diffs.
+        // 10, 60, 10 swings 50 per pair; 10, 35, 60 only 25 per pair, yet both envelopes are 50.
         let base = solid(2, 1, [10, 10, 10]);
         let alternating = {
             let mut m = base.clone();
@@ -760,9 +682,6 @@ mod tests {
 
     #[test]
     fn a_monotone_sweep_never_toggles_however_far_it_moves() {
-        // The whole point: this is what a moving camera does to a pixel an edge sweeps across —
-        // a huge envelope (0 → 240) and zero reversals. `envelope` calls it maximally unstable;
-        // `toggles` correctly says it is not flickering.
         let sweep = ramp(&[0, 60, 120, 180, 240]);
         assert_eq!(envelope(&sweep, 1).unwrap().max_swing, 240);
         let t = toggles(&sweep, 4, 60).unwrap();
@@ -772,7 +691,7 @@ mod tests {
 
     #[test]
     fn an_alternating_pixel_toggles_every_step() {
-        // A/B/A/B/A — z-fighting's signature. Four steps, three of them reversals.
+        // A/B/A/B/A, z-fighting's signature: four steps, three of them reversals.
         let t = toggles(&ramp(&[10, 90, 10, 90, 10]), 4, 60).unwrap();
         assert_eq!(t.max_reversals, 3);
         assert_eq!(t.pct_toggling, 1.0);
@@ -781,19 +700,16 @@ mod tests {
 
     #[test]
     fn sub_threshold_noise_neither_toggles_nor_forgets_the_direction() {
-        // ±1 dither must not manufacture reversals …
+        // ±1 dither makes no reversals,
         let t = toggles(&ramp(&[50, 51, 50, 51, 50, 51]), 4, 60).unwrap();
         assert_eq!(t.max_reversals, 0);
-        // … and a run of it in the middle of a real climb must not reset the direction either,
-        // or every noisy edge would read as one reversal per crossing.
+        // nor does it reset the direction in the middle of a real climb.
         let t = toggles(&ramp(&[0, 40, 41, 40, 41, 80]), 4, 60).unwrap();
         assert_eq!(t.max_reversals, 0);
     }
 
     #[test]
     fn a_single_overshoot_is_one_reversal_and_below_the_toggle_bar() {
-        // Down-then-up once: real, but not a flicker — `TOGGLE_MIN_REVERSALS` is what draws that
-        // line, so a lone direction change must not be counted as a toggling pixel.
         let t = toggles(&ramp(&[10, 90, 40]), 4, 60).unwrap();
         assert_eq!(t.max_reversals, 1);
         assert_eq!(t.pct_toggling, 0.0);
@@ -818,8 +734,7 @@ mod tests {
         assert_eq!(out.get_pixel(4, 0), &Rgb([40, 50, 60])); // right image
     }
 
-    /// A burst in which exactly the pixels selected by `flips` alternate 0/200 and everything else
-    /// holds still — the shape tests differ only in *which* pixels those are.
+    /// A burst where the pixels `flips` selects alternate 0/200 and the rest hold still.
     fn alternating(
         w: u32,
         h: u32,
@@ -838,7 +753,6 @@ mod tests {
 
     #[test]
     fn one_solid_block_reads_as_a_single_filled_run() {
-        // A whole surface blinking: one run, filling its own box, every interior pixel enclosed.
         let frames = alternating(20, 20, 6, |x, y| {
             (4..12).contains(&x) && (4..12).contains(&y)
         });
@@ -866,8 +780,6 @@ mod tests {
 
     #[test]
     fn a_checkerboard_covers_the_same_area_with_none_of_the_shape() {
-        // Z-fighting resolving per fragment. Same region of the frame, ~half the pixels toggling,
-        // but no pixel touches another — the reading that separates it from the block above.
         let frames = alternating(20, 20, 6, |x, y| {
             (4..12).contains(&x) && (4..12).contains(&y) && (x + y) % 2 == 0
         });
@@ -879,11 +791,10 @@ mod tests {
 
     #[test]
     fn runs_come_back_largest_first_and_short_ones_are_scattered() {
-        // Two blocks plus a speck: the big one leads, the speck falls below MIN_REGION_PIXELS.
         let frames = alternating(40, 20, 6, |x, y| {
             let big = (2..12).contains(&x) && (2..12).contains(&y); // 100 px
             let small = (20..25).contains(&x) && (2..7).contains(&y); // 25 px
-            let speck = (30..33).contains(&x) && y == 10; // 3 px — noise
+            let speck = (30..33).contains(&x) && y == 10; // 3 px, noise
             big || small || speck
         });
         let s = shape(&toggles(&frames, 4, 60).unwrap());
@@ -900,7 +811,7 @@ mod tests {
         let s = shape(&toggles(&frames, 4, 60).unwrap());
         assert!(s.regions.is_empty());
         assert_eq!(s.scattered, 0);
-        assert_eq!(s.coherence, 0.0); // no toggling pixels — not a divide-by-zero
+        assert_eq!(s.coherence, 0.0); // no toggling pixels, and no divide-by-zero
     }
 
     #[test]
diff --git a/crates/benilla-visual/src/main.rs b/crates/benilla-visual/src/main.rs
index cdd60d01..8530c10d 100644
--- a/crates/benilla-visual/src/main.rs
+++ b/crates/benilla-visual/src/main.rs
@@ -1,19 +1,6 @@
-//! `benilla-visual` — diff captures from the Phase-5 visual A/B harness (decision 0008).
-//!
-//! Usage:
-//!   benilla-visual diff     <a.png> <b.png>   [--out <diff.png>] [--fail <mae>] [--amplify <n>]
-//!   benilla-visual diff-dir <dir_a> <dir_b>   [--out <diff_dir>] [--fail <mae>] [--amplify <n>]
-//!   benilla-visual flicker  <burst_dir>       [--out <envelope.png>] [--fail <mae>] [--amplify <n>]
-//!   benilla-visual stat     <img.png>         [--rect <x>,<y>,<w>,<h>]
-//!
-//! `diff` compares two images; `diff-dir` compares every `*.png` present in *both* directories by name.
-//! Prints the metrics; writes amplified heatmap(s) when `--out` is given; exits non-zero if any image's
-//! MAE exceeds `--fail` (when given). Typical loop: capture baselines, change the renderer, re-capture,
-//! `diff-dir baseline candidate --out diff --fail 1.5`.
-//!
-//! `flicker` is the same arithmetic over *time*: point it at a `WOW_LIVE_SHOT_COUNT` burst (adjacent
-//! frames, parked camera) and it prints the frame-to-frame table and the whole-stack envelope, and
-//! writes the envelope heatmap — the picture of which pixels would not hold still.
+//! `benilla-visual`: diff captures, and read flicker and motion out of a burst of frames; `--help`
+//! lists the subcommands. The regression loop: capture baselines, change the renderer, re-capture,
+//! then `diff-dir baseline candidate --out diff --fail 1.5`.
 
 use std::collections::BTreeSet;
 use std::path::{Path, PathBuf};
@@ -24,32 +11,24 @@ use benilla_visual::{
     Metrics, Rect, OVER_THRESHOLD,
 };
 
-/// A frame-to-frame step must move a channel by this much to count as a direction change (override
-/// with `--toggle-delta`). Above PNG/dither noise, below any real surface swap.
-///
-/// **The pan rate matters more than this number.** A moving camera sweeps texture detail across
-/// every pixel, and detail is not monotone — at 8°/s (≈15 px/frame at 3200 px) the map saturates at
-/// 93% and says nothing. Keep the sweep **sub-pixel per frame** (≈0.2°/s) so ordinary surfaces
-/// barely move while a depth-comparison flip still swaps whole surfaces at full amplitude.
+/// The smallest step that counts as a direction change (`--toggle-delta`): above PNG and dither
+/// noise, below a surface swap. The pan rate matters more: keep a sweep sub-pixel per frame (about
+/// 0.2°/s), since at 8°/s texture detail saturates the map.
 const TOGGLE_MIN_DELTA: u8 = 4;
 
-/// Reversal counts are small integers, so the toggle map needs its own (much larger) gain than the
-/// 0..255 swings the envelope amplifies: at 60, three reversals saturate.
+/// The toggle map's gain: reversal counts are small, and at 60 three of them saturate.
 const TOGGLE_AMPLIFY: u32 = 60;
 
 /// Gap (px) between the two halves of a side-by-side compose.
 const COMPOSE_GAP: u32 = 6;
 
-/// Tiles per row on a `hotspot` contact sheet — wide enough that a 24-frame burst reads as a few
-/// rows of adjacent frames rather than one unscannable ribbon.
+/// Tiles per row on a `hotspot` contact sheet.
 const STRIP_COLS: u32 = 6;
 
-/// Pixels of context kept around a hotspot crop (override with `--pad`). Enough to see what the
-/// toggling region borders — which is usually the whole point.
+/// Pixels of context around a hotspot crop (`--pad`), enough to see what the run borders.
 const DEFAULT_PAD: u32 = 24;
 
-/// How many runs `hotspot` reports a time series for. Enough to see whether the top runs flip on the
-/// same frames (one cause) or independently (several), narrow enough to stay one screen.
+/// Runs `hotspot` prints a series for: enough to see whether the top runs flip together.
 const SERIES_RUNS: usize = 4;
 
 /// Default amplification for the heatmap output (per-channel abs-diff ×N, clamped).
@@ -147,8 +126,7 @@ fn main() -> Result<()> {
                 opts.out.as_deref(),
                 opts.amplify,
             )?;
-            // Under `--fail` this is a gate, and a shot that never landed must sink it — see the
-            // note in `diff_dir` (decision 0743).
+            // Under `--fail` this is a gate, and a missing shot fails it.
             if opts.fail.is_some() && !unpaired.is_empty() {
                 bail!(
                     "{} unpaired image(s) — a shot is missing from one side, so this comparison is \
@@ -240,17 +218,8 @@ fn main() -> Result<()> {
     Ok(())
 }
 
-/// What one named pixel *did*, frame by frame — the colour counterpart to the client's `WOW_DEPTH`.
-///
-/// The aggregate readings (`flicker`, `hotspot`) answer "which pixels would not hold still" over a
-/// whole region, which is the right question when you are looking for a defect and the wrong one once
-/// you have found it. Correlating a renderer-side probe against the pixels needs the opposite: *this*
-/// pixel, *these* frames, no averaging. Run `WOW_DEPTH` and `--at` on the same coordinates and the two
-/// logs line up frame for frame — "the colour changed here but the depth did not" is a fact you cannot
-/// get from a region mean, because a run mean over 19 000 pixels hides which of them moved.
-///
-/// It also guards the trap this exists inside: a burst that happens to contain **no** flip reads as a
-/// clean negative. The per-frame Δ makes an absent phenomenon obvious instead of invisible.
+/// One named pixel's colour frame by frame, to line up against the client's `WOW_DEPTH` log at the
+/// same coordinates; the per-frame delta shows a burst that caught no flip at all.
 fn series(dir: &Path, at: &str) -> Result<()> {
     let pixels = parse_at(at)?;
     let names = pngs(dir)?;
@@ -284,17 +253,8 @@ fn series(dir: &Path, at: &str) -> Result<()> {
     Ok(())
 }
 
-/// Cut a window out of a capture, magnify it, and report what was actually cut — the vetted
-/// replacement for the ad-hoc `sips`/`ffmpeg` crop pipelines that kept minting false findings
-/// (`sips --cropOffset` takes (y, x) and silently ignores what it can't parse; a guessed ffmpeg
-/// window read "no eyes" off a frame the model had left). Three honesty rules: a rect that misses
-/// the frame entirely is an ERROR, never an edge-clamped guess; a rect that only partially fits is
-/// clamped *out loud*; and every pixel sample prints in SOURCE coordinates at source resolution, so
-/// nothing downstream does coordinate math on a zoomed image.
-/// Per-channel min / mean / max over a rect (or the whole frame) — the "is this region flat?"
-/// instrument. A frame edge that shows the render target's clear colour instead of art reads as
-/// `min == max` on every channel (decision 1619, the glue framing's void check); a region of art
-/// never does. Printed, not judged: the caller compares two rects or two captures.
+/// Per-channel min, mean and max over a rect or the whole frame: an edge showing the clear colour
+/// instead of art reads `min == max` on every channel, which a region of art never does.
 fn stat_cmd(path: &Path, rect: Option<&str>) -> Result<()> {
     let img = load(path)?;
     let (w, h) = img.dimensions();
@@ -389,7 +349,7 @@ fn crop_cmd(path: &Path, rect: &str, at: Option<&str>, scale: u32, out: &Path) -
         zoomed.width(),
         zoomed.height(),
     );
-    // Samples: the rect's centre always, plus any --at points — all in source coordinates.
+    // Samples: the rect's centre and any `--at` points, in source coordinates.
     let mut samples = vec![((r.x0 + r.x1) / 2, (r.y0 + r.y1) / 2)];
     if let Some(at) = at {
         samples.extend(parse_at(at)?);
@@ -414,8 +374,7 @@ fn crop_cmd(path: &Path, rect: &str, at: Option<&str>, scale: u32, out: &Path) -
     Ok(())
 }
 
-/// `"x,y,w,h"` → the rect it names. Strict for the same reason as [`parse_at`]: a half-parsed
-/// window silently crops the wrong place, and a wrong crop reads as a finding.
+/// `"x,y,w,h"` → the rect it names; strict, since a half-parsed window crops the wrong place.
 fn parse_rect(spec: &str) -> Result<Rect> {
     let parts: Vec<&str> = spec.split(',').map(str::trim).collect();
     let [x, y, w, h] = parts.as_slice() else {
@@ -437,7 +396,7 @@ fn parse_rect(spec: &str) -> Result<Rect> {
     })
 }
 
-/// `"x,y;x,y"` → pixels. Strict: a typo here would silently report the wrong pixel's history.
+/// `"x,y;x,y"` → pixels; strict, since a typo would report the wrong pixel's history.
 fn parse_at(spec: &str) -> Result<Vec<(u32, u32)>> {
     spec.split(';')
         .filter(|s| !s.trim().is_empty())
@@ -455,27 +414,11 @@ fn parse_at(spec: &str) -> Result<Vec<(u32, u32)>> {
         .collect()
 }
 
-/// Stitch every `*.png` present in both dirs into `left | right` side-by-side images under `out`.
-/// **The sub-pixel motion ruler** (`flow <burst_dir> [--rect "<x>,<y>,<w>,<h>"]`).
-///
-/// `flicker` and `series` answer *how much* a pixel changed. Neither can answer the question a
-/// "the animation ticks" report actually asks — is the thing in front of the pixel advancing
-/// **evenly**? — and the obvious way to ask it is a trap: recover one silhouette edge's sub-pixel
-/// position frame by frame, and the ruler is built out of 8-bit pixels, so it carries its own
-/// 1/255 quantisation and a 0.2 px step cannot be separated from the tool's noise floor. That
-/// ambiguity is exactly what left the first staircase reading unattributed.
-///
-/// So estimate the whole window's displacement at once, by least squares over every pixel in it
-/// (Lucas–Kanade, the standard first-order flow solve): thousands of gradients vote on one
-/// `(dx, dy)`, the 8-bit floor averages down by `√N`, and the estimate lands two orders of
-/// magnitude under a pixel. A breathing body is not a rigid translation and does not need to be —
-/// what is read off the series is whether the aggregate advances smoothly, and a staircase in the
-/// RENDER shows up as a staircase here whatever the body underneath is doing.
-///
-/// Columns are the per-frame displacement, its magnitude, and the **second difference** — the
-/// curvature-per-frame discriminator the world-space jitter meter uses, on this side of the glass.
-/// The summary counts **stalled** frames (under a fifth of the median step): a smooth pan has
-/// none, a staircase is mostly them.
+/// The sub-pixel motion ruler: one least-squares (Lucas-Kanade) displacement per frame pair over
+/// the whole window, so thousands of gradients average the 8-bit floor away and a render that
+/// advances in steps reads as steps. Columns are the displacement, its magnitude and the second
+/// difference; a stalled frame moves under a fifth of the median step. It assumes constant
+/// brightness: for a shaded, deforming body use `edge`.
 fn flow(dir: &Path, rect: Option<&str>) -> Result<()> {
     let names = pngs(dir)?;
     if names.len() < 3 {
@@ -487,8 +430,7 @@ fn flow(dir: &Path, rect: Option<&str>) -> Result<()> {
     }
     let first = load(&dir.join(names.iter().next().expect("non-empty")))?;
     let (w, h) = first.dimensions();
-    // The default window is the whole frame minus the one-pixel border the central differences
-    // need. A named rect is clamped out loud, never silently (the `crop` honesty rule).
+    // A named rect is clamped out loud, never silently; the solve skips the one-pixel border.
     let win = match rect {
         Some(spec) => {
             let want = parse_rect(spec)?;
@@ -581,8 +523,7 @@ fn flow(dir: &Path, rect: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-/// One frame's luma over `win`, row-major — the flow solve's input (f32 is exact for 8-bit sums
-/// and halves the working set against a 3200x1800 f64 buffer).
+/// One frame's luma over `win`, row-major; `f32` halves the working set of a 3200x1800 frame.
 fn luma_window(img: &image::RgbImage, win: &Rect) -> Vec<f32> {
     let mut out = Vec::with_capacity(((win.x1 - win.x0) * (win.y1 - win.y0)) as usize);
     for y in win.y0..win.y1 {
@@ -596,10 +537,8 @@ fn luma_window(img: &image::RgbImage, win: &Rect) -> Vec<f32> {
     out
 }
 
-/// Least-squares first-order optical flow between two luma windows: the `(dx, dy)` that best
-/// explains `b` as `a` shifted, solved once over every interior pixel. `None` when the window
-/// carries no usable gradient structure (a flat sky — the normal matrix is singular and any
-/// answer would be invented).
+/// The `(dx, dy)` that best explains `b` as `a` shifted, over every interior pixel; `None` when
+/// the normal matrix is singular, as over a flat sky.
 fn lucas_kanade(a: &[f32], b: &[f32], w: usize, h: usize) -> Option<(f64, f64)> {
     let (mut sxx, mut sxy, mut syy, mut sxt, mut syt) = (0.0f64, 0.0, 0.0, 0.0, 0.0);
     for y in 1..h - 1 {
@@ -616,8 +555,7 @@ fn lucas_kanade(a: &[f32], b: &[f32], w: usize, h: usize) -> Option<(f64, f64)>
         }
     }
     let det = sxx * syy - sxy * sxy;
-    // Scale-relative: the normal matrix grows with the window, so an absolute epsilon would call
-    // a big flat window solvable and a small textured one singular.
+    // Relative, since the normal matrix grows with the window.
     if det <= 1e-12 * (sxx * syy).max(f64::MIN_POSITIVE) {
         return None;
     }
@@ -646,11 +584,10 @@ fn compose_dir(da: &Path, db: &Path, out: &Path) -> Result<()> {
     Ok(())
 }
 
-/// Report how far a burst of adjacent frames moved: the frame-to-frame table, then the whole-stack
-/// envelope. Returns the worst consecutive-pair metrics (the `--fail` subject) — the envelope is a
-/// *stack* number and can exceed any single pair, so failing on the pair is the conservative gate.
+/// Print a burst's frame-to-frame table, envelope and toggles; the worst pair's metrics are the
+/// `--fail` subject, since the envelope can exceed any single pair.
 fn flicker(dir: &Path, out: Option<&Path>, amplify: u32, toggle_delta: u8) -> Result<Metrics> {
-    let names: Vec<String> = pngs(dir)?.into_iter().collect(); // BTreeSet — already shot order
+    let names: Vec<String> = pngs(dir)?.into_iter().collect(); // a BTreeSet: already shot order
     if names.len() < 2 {
         bail!(
             "{} holds {} *.png — a flicker burst needs at least 2 (WOW_LIVE_SHOT_COUNT=<n>)",
@@ -691,8 +628,7 @@ fn flicker(dir: &Path, out: Option<&Path>, amplify: u32, toggle_delta: u8) -> Re
         e.mean_swing,
         e.pct_unstable * 100.0
     );
-    // The moving-camera reading. Printed always, because which of the two numbers is meaningful
-    // depends on whether the camera was parked — and a burst does not carry that fact.
+    // Printed always: a burst does not record whether the camera was parked.
     let t = toggles(&frames, toggle_delta, TOGGLE_AMPLIFY)?;
     println!(
         "toggles  of {} frames (delta {toggle_delta}): max reversals {:>3}  toggling pixels {:>6.2}%  \
@@ -718,12 +654,8 @@ fn flicker(dir: &Path, out: Option<&Path>, amplify: u32, toggle_delta: u8) -> Re
     Ok(worst)
 }
 
-/// Follow the toggle map to the thing it found: measure the toggling pixels' **shape**, then crop
-/// the largest run out of every frame into one contact sheet.
-///
-/// The map says *where*; this says *what kind*, and shows the frames that prove it. A run that fills
-/// its box and holds together is one surface blinking (visibility/culling); many thin runs are
-/// z-fighting resolving per fragment. Both read identically on the toggle percentage.
+/// Measure the toggling pixels' shape, print the top runs' series and relight fits, and crop the
+/// largest run out of every frame into one contact sheet.
 fn hotspot(dir: &Path, out: &Path, toggle_delta: u8, pad: u32) -> Result<()> {
     let names: Vec<String> = pngs(dir)?.into_iter().collect();
     let frames: Vec<image::RgbImage> = names
@@ -751,8 +683,7 @@ fn hotspot(dir: &Path, out: &Path, toggle_delta: u8, pad: u32) -> Result<()> {
             r.bounds.x0,
             r.bounds.y0,
         );
-        // Pasteable straight into the in-game ray pick, which is the next question every time:
-        // WOW_PICK="<this>" names the surfaces at these exact pixels, front to back.
+        // For the ray pick: `WOW_PICK` names the surfaces at these pixels, front to back.
         let pick = r
             .samples()
             .iter()
@@ -767,9 +698,7 @@ fn hotspot(dir: &Path, out: &Path, toggle_delta: u8, pad: u32) -> Result<()> {
             benilla_visual::MIN_REGION_PIXELS
         );
     };
-    // What the top runs are actually *doing*, frame by frame: re-shaded together, or edges moving.
-    // Side by side, because whether they flip on the SAME steps is the difference between one global
-    // cause and several local ones — and that is invisible in any single run's series.
+    // The top runs side by side: flipping on the same steps means one cause, not several.
     let series: Vec<Vec<benilla_visual::Step>> = s
         .regions
         .iter()
@@ -789,11 +718,8 @@ fn hotspot(dir: &Path, out: &Path, toggle_delta: u8, pad: u32) -> Result<()> {
             .collect();
         println!("    {:>2} -> {:<2}  {}", i, i + 1, cols.join("  "));
     }
-    // The two extremes of run #0, per channel — the *levels*, which is all this line is. Read the
-    // ratios as description, never as a diagnosis: equal ratios rule out a scalar multiply and
-    // nothing else, since an ADDED light moves the three channels by different factors too. The
-    // reading that actually separates "one surface, re-lit" from "two surfaces" is the per-pixel
-    // affine fit printed below it (`benilla_visual::relight`).
+    // Run #0's extremes per channel, a description only: equal ratios rule out a scalar multiply
+    // and nothing else. The relight fit below is the diagnosis.
     let s0 = &series[0];
     let lo = s0
         .iter()
@@ -812,10 +738,7 @@ fn hotspot(dir: &Path, out: &Path, toggle_delta: u8, pad: u32) -> Result<()> {
         hi.mean_rgb_from[0], hi.mean_rgb_from[1], hi.mean_rgb_from[2],
         ratio.join(" / "),
     );
-    // Same surface re-lit, or a different surface? Fit each run's pixels across its own biggest
-    // frame-to-frame step. High R² = the pattern survived the flip and only its gain/offset moved,
-    // so it is one surface being shaded differently; low R² = the two frames show different
-    // surfaces, whatever the means do.
+    // Each run fitted across its biggest step: high R² is one surface re-lit, low R² two surfaces.
     println!(
         "  across each run's biggest step — is it one surface re-lit? (R² near 1 = yes), \
          against its quietest step as the control:"
@@ -837,8 +760,7 @@ fn hotspot(dir: &Path, out: &Path, toggle_delta: u8, pad: u32) -> Result<()> {
                 )
             })
             .collect();
-        // The control is what licenses the verdict: a low R² on the flip only means "different
-        // surfaces" if the same pixels under the same pan fit tightly when they did NOT flip.
+        // A low R² on the flip means two surfaces only if the quiet step fits tightly.
         let verdict = if ctl.worst_r2() < 0.9 {
             "no control — the pan alone decorrelates these pixels; fit says nothing"
         } else if fit.worst_r2() > 0.9 {
@@ -860,8 +782,7 @@ fn hotspot(dir: &Path, out: &Path, toggle_delta: u8, pad: u32) -> Result<()> {
         );
     }
     let rect = biggest.bounds.padded(pad, w, h);
-    // The toggle map goes in as the first tile, so the sheet carries its own legend: this is the
-    // region, and here is what the frames did inside it.
+    // The toggle map is the first tile, the sheet's own legend.
     let mut tiles = vec![crop(&t.image, rect)];
     tiles.extend(frames.iter().map(|f| crop(f, rect)));
     if let Some(parent) = out.parent().filter(|p| !p.as_os_str().is_empty()) {
@@ -882,9 +803,7 @@ fn hotspot(dir: &Path, out: &Path, toggle_delta: u8, pad: u32) -> Result<()> {
     Ok(())
 }
 
-/// `foo.png` + `-toggle` → `foo-toggle.png`. The two maps answer the same question under opposite
-/// camera conditions, so they are written as a pair rather than behind a second flag nobody would
-/// remember to pass.
+/// `foo.png` + `-toggle` → `foo-toggle.png`.
 fn sibling(out: &Path, suffix: &str) -> PathBuf {
     let ext = out.extension().and_then(|e| e.to_str()).unwrap_or("png");
     let stem = out.file_stem().and_then(|s| s.to_str()).unwrap_or("out");
@@ -915,15 +834,9 @@ fn over_fail(m: &Metrics, fail: Option<f64>) -> bool {
     fail.is_some_and(|t| m.mae > t)
 }
 
-/// Load an image as RGB (dropping any alpha — capture windows are opaque).
-/// One silhouette's sub-pixel position along a scanline, per frame — the shading-independent
-/// answer to "did the rendered geometry MOVE smoothly?".
-///
-/// Per frame and per scanline: take the row's own darkest and brightest samples, put the
-/// threshold halfway between them, and linearly interpolate the crossing. Renormalising to the
-/// row's own ends every frame is the whole point — a uniform brightness change (the body turning
-/// into the light) moves `lo` and `hi` together and leaves the crossing where it was, while a
-/// geometric shift moves it. That is the property [`flow`] lacks.
+/// One silhouette's sub-pixel position along a scanline, per frame: where the row crosses the
+/// midpoint of its own darkest and brightest samples, so a uniform brightness change leaves it in
+/// place and only a geometric shift moves it.
 fn edge(dir: &Path, at: &str) -> Result<()> {
     let names = pngs(dir)?;
     if names.len() < 3 {
@@ -972,7 +885,7 @@ fn edge(dir: &Path, at: &str) -> Result<()> {
                 .collect();
             let lo = row.iter().copied().fold(f64::INFINITY, f64::min);
             let hi = row.iter().copied().fold(f64::NEG_INFINITY, f64::max);
-            // Too little contrast to call an edge — report it rather than invent a position.
+            // Too little contrast to call an edge: report it, never invent a position.
             if hi - lo < 12.0 {
                 pos.push(f64::NAN);
                 continue;
@@ -1051,11 +964,10 @@ fn diff_one(a: &Path, b: &Path, out: Option<&Path>, amplify: u32) -> Result<Metr
     Ok(m)
 }
 
-/// Compare every `*.png` present in both dirs (by file name). Returns the worst (highest-MAE) result.
-/// What one `diff-dir` run found: the worst pair by MAE, and every image present on only ONE side.
+/// What one `diff-dir` run found: the worst pair by MAE, and every image on only one side.
 struct DirDiff {
     worst: Option<(String, Metrics)>,
-    /// Files with no counterpart, so not diffed at all — see the note in [`diff_dir`].
+    /// Files with no counterpart, so not diffed.
     unpaired: Vec<String>,
 }
 
@@ -1069,11 +981,8 @@ fn diff_dir(da: &Path, db: &Path, out: Option<&Path>, amplify: u32) -> Result<Di
             db.display()
         );
     }
-    // UNPAIRED shots are ANNOUNCED, never skipped in silence. Pairing on the intersection alone is
-    // how a sweep reports all-green with a shot missing: on 2026-07-28 one `water-night` capture
-    // exited 0 without writing its PNG, and `selfcheck` diffed the other eight and passed clean. A
-    // gate that quietly narrows its own scope is worse than no gate. Reported always; fatal to the
-    // CALLER when `--fail` is in force, i.e. whenever this is being used as a gate (decision 0743).
+    // Unpaired shots are announced, never skipped in silence, so a capture that wrote no PNG
+    // cannot let the rest pass clean; the caller fails on them under `--fail`.
     let unpaired: Vec<String> = a
         .difference(&b)
         .map(|n| format!("{}/{n}", da.display()))
@@ -1117,9 +1026,8 @@ fn pngs(dir: &Path) -> Result<BTreeSet<String>> {
 }
 
 fn fmt_metrics(m: &Metrics) -> String {
-    // `px` and the worst pixel's coordinate are what tell a render change from an MSAA tie: both
-    // show `MAE 0.000` with an alarming `max`, and only the count and the location separate them
-    // (a handful of pixels, at the same coordinate every build, is a tie).
+    // `px` and the worst pixel's coordinate tell an MSAA tie from a render change: a handful of
+    // pixels at the same spot every build is a tie.
     let where_ = if m.changed == 0 {
         String::new()
     } else {
@@ -1187,7 +1095,6 @@ mod tests {
 
     #[test]
     fn rect_spec_is_strict() {
-        // "x,y,w,h" and nothing else — a half-parsed window crops the wrong place silently.
         let r = parse_rect("10, 20, 30, 40").unwrap();
         assert_eq!((r.x0, r.y0, r.x1, r.y1), (10, 20, 40, 60));
         assert!(parse_rect("10,20,30").is_err());
diff --git a/crates/benilla-visual/src/relight.rs b/crates/benilla-visual/src/relight.rs
index ab8d2236..54da3fce 100644
--- a/crates/benilla-visual/src/relight.rs
+++ b/crates/benilla-visual/src/relight.rs
@@ -1,26 +1,11 @@
-//! **Is it the same surface lit differently, or a different surface?** — the reading that separates
-//! the two explanations a two-state flip always admits.
+//! Tells one surface lit differently from two different surfaces. Equal channel ratios rule out
+//! only a scalar multiply, since an added coloured light changes the ratios too; the spatial
+//! pattern tells them apart. Re-lighting is an affine map per pixel, `bright ≈ gain·dim + offset`,
+//! so the fit is tight, while two surfaces fit loosely however well their means line up. This fits
+//! one frame's pixels onto the other's per channel and reports R².
 //!
-//! [`Region::steps`] measures that a run alternates between two levels and that its pixels move
-//! together. That is where the evidence used to stop, and the gap mattered: B38's tent was read off
-//! the per-channel *ratios* as "two materials trading places", on the argument that one light term
-//! switching would scale all three channels equally. **That argument is wrong.** Equal ratios rule
-//! out a scalar multiply and nothing else — an *additive* term (a coloured light arriving or
-//! leaving) changes the ratios freely. Measured there: dim `(77, 42, 32)` → bright `(192, 79, 35)`
-//! is "×2.50 / ×1.89 / ×1.12", which reads as two materials, and is *also* exactly the dim state
-//! plus a warm `(115, 37, 3)`. The ratios cannot tell those apart, so they were never evidence.
-//!
-//! What does tell them apart is the **spatial pattern**, which the means throw away. Re-lighting a
-//! surface is an affine map on its pixels — every pixel keeps its place in the pattern, so
-//! `bright ≈ gain·dim + offset` holds *per pixel* and the fit is tight. Two different surfaces have
-//! unrelated patterns (canvas weave vs plank grain), and no affine map relates them: the fit is
-//! loose however well the means happen to line up. So: least-squares fit one frame's pixels onto the
-//! other's, per channel, and report R². That is a number, not an inference from a number.
-//!
-//! Fit across the run's **largest single frame-to-frame step**, never across the whole burst: the
-//! camera pans during a capture, and a pixel only names the same bit of world for as long as the
-//! image holds still under it. Adjacent frames at the sub-pixel-per-frame pan the toggle map needs
-//! (decision 0656) are the same view; frames twenty apart are not.
+//! The fit spans the run's largest single frame-to-frame step, never the whole burst: the camera
+//! pans, and a pixel names the same bit of world only while the image holds still under it.
 
 use image::RgbImage;
 
@@ -29,26 +14,20 @@ use crate::Region;
 /// A per-channel affine fit of one frame's pixels onto another's, over a [`Region`]'s own pixels.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Relight {
-    /// Per channel, the `a` in `to ≈ a·from + b`. Near 1 with a non-zero [`Relight::offset`] is a
-    /// light being *added*; well above 1 with an offset near 0 is one being *scaled*.
+    /// Per channel, the `a` in `to ≈ a·from + b`: near 1 with an offset is a light added, well
+    /// above 1 with none a light scaled.
     pub gain: [f64; 3],
     /// Per channel, the `b` in `to ≈ a·from + b`, in 0..255 units.
     pub offset: [f64; 3],
-    /// Per channel coefficient of determination, 0..1 — how much of the target frame's variation
-    /// across the run the fit explains. **This is the reading.** Near 1: one surface, re-lit (the
-    /// pattern survived, only its scale and offset moved). Low: the two frames show *different*
-    /// surfaces, and no amount of re-lighting maps one to the other.
+    /// Per channel R², 0..1: near 1 is one surface re-lit, low is two different surfaces.
     pub r2: [f64; 3],
-    /// Did this channel vary across the run at all? A flat channel (uniform, or clipped to 0/255)
-    /// has nothing for a fit to explain, so its R² is 0 for a reason that is **not** evidence of
-    /// different surfaces — and without this flag that 0 would outvote the channels that do carry
-    /// evidence, turning a plain re-light into a false "different surfaces".
+    /// Whether the channel varied across the run: a flat or clipped channel's R² of 0 is no
+    /// evidence, and must not outvote the others.
     pub determinate: [bool; 3],
 }
 
 impl Relight {
-    /// The weakest **determinate** channel's R² — the honest summary, since "one surface, re-lit"
-    /// has to hold in every channel that carries evidence. 0 when no channel does.
+    /// The weakest determinate channel's R², or 0 when no channel is determinate.
     pub fn worst_r2(&self) -> f64 {
         (0..3)
             .filter(|&c| self.determinate[c])
@@ -58,11 +37,8 @@ impl Relight {
     }
 }
 
-/// Least-squares fit of `to`'s pixels onto `from`'s, per channel, over `region`'s own pixels.
-///
-/// A channel with no variation across the run (a flat, saturated, or clipped channel) has nothing
-/// for a fit to explain; its R² is reported as 0 rather than dividing by zero, which reads as
-/// "this channel is not evidence" — the conservative direction.
+/// Least-squares fit of `to`'s pixels onto `from`'s per channel, over `region`'s own pixels; a flat
+/// channel reports R² 0 and is not determinate.
 pub fn relight(region: &Region, from: &RgbImage, to: &RgbImage) -> Relight {
     let mut out = Relight {
         gain: [0.0; 3],
@@ -106,20 +82,13 @@ pub fn relight(region: &Region, from: &RgbImage, to: &RgbImage) -> Relight {
     out
 }
 
-/// The index of the frame-to-frame step where the run's mean luma moved most — the flip itself,
-/// and the pair [`relight`] should be fitted across. `None` for a burst with fewer than two frames.
+/// The step where the run's mean luma moved most: the flip, and the pair [`relight`] fits across.
 pub fn biggest_step(region: &Region, frames: &[RgbImage]) -> Option<usize> {
     extreme_step(region, frames, true)
 }
 
-/// The step where the run's mean luma moved **least** — the **control**, and the reason a low R² on
-/// the biggest step can be believed at all.
-///
-/// The capture pans, so consecutive frames are never quite the same image, and a textured surface
-/// sliding a fraction of a pixel decorrelates on its own. That means a low R² is only evidence of
-/// *different surfaces* if a step where the run did **not** flip scores high across the same pixels
-/// under the same motion. Quiet step near 1 and flip step near 0 is a real reading; both low means
-/// the fit is measuring the pan and nothing else.
+/// The step where the run's mean luma moved least: the control. The pan alone decorrelates a
+/// textured surface, so a low R² on the flip means two surfaces only if this step fits tightly.
 pub fn quietest_step(region: &Region, frames: &[RgbImage]) -> Option<usize> {
     extreme_step(region, frames, false)
 }
@@ -161,7 +130,7 @@ mod tests {
         }
     }
 
-    /// A textured surface: a pattern with real variation for a fit to have to explain.
+    /// A patterned surface, with variation for a fit to explain.
     fn textured(w: u32, h: u32, f: impl Fn(u32, u32) -> [u8; 3]) -> RgbImage {
         RgbImage::from_fn(w, h, |x, y| Rgb(f(x, y)))
     }
@@ -169,7 +138,7 @@ mod tests {
     #[test]
     fn the_same_surface_plus_a_warm_light_fits_as_gain_one_and_an_offset() {
         let dim = textured(16, 16, |x, y| [(x * 8) as u8, (y * 6) as u8, (x + y) as u8]);
-        // Exactly the B38 shape: add a warm constant, leave the pattern alone.
+        // A warm constant added, the pattern untouched.
         let bright = textured(16, 16, |x, y| {
             [(x * 8 + 115) as u8, (y * 6 + 37) as u8, (x + y + 3) as u8]
         });
@@ -200,8 +169,6 @@ mod tests {
         assert!(r.offset[0].abs() < 1e-6, "{r:?}");
     }
 
-    /// The discrimination the module exists for: two surfaces whose *means* differ exactly as a
-    /// re-light would, but whose patterns are unrelated. The means cannot tell them apart; R² can.
     #[test]
     fn two_different_surfaces_do_not_fit_however_well_their_means_line_up() {
         // Vertical stripes vs horizontal stripes: same mean, same spread, no affine relation.
@@ -221,9 +188,6 @@ mod tests {
         assert!((r.offset[0] - 90.0).abs() < 1e-9, "{r:?}");
     }
 
-    /// The flat-channel rule has to be a *skip*, not a zero vote: a surface whose blue is clipped
-    /// flat but whose red and green track perfectly is one surface being re-lit, and reporting the
-    /// dead channel's 0 as the verdict would call it two.
     #[test]
     fn a_flat_channel_does_not_outvote_the_ones_carrying_evidence() {
         let dim = textured(16, 16, |x, y| [(x * 8) as u8, (y * 6) as u8, 255]);
diff --git a/crates/benilla-wdt/Cargo.toml b/crates/benilla-wdt/Cargo.toml
index e69add2d..16e3190d 100644
--- a/crates/benilla-wdt/Cargo.toml
+++ b/crates/benilla-wdt/Cargo.toml
@@ -3,7 +3,7 @@ name = "benilla-wdt"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "WDT map tile-table reader + tile/world coords for WoW 1.12.1 (build 5875) — in-repo, decision 0021"
+description = "WDT map tile-table reader and tile/world coordinates for WoW 1.12.1 (build 5875)"
 
 [lints]
 workspace = true
diff --git a/crates/benilla-wdt/src/lib.rs b/crates/benilla-wdt/src/lib.rs
index 4af13b4f..dc928351 100644
--- a/crates/benilla-wdt/src/lib.rs
+++ b/crates/benilla-wdt/src/lib.rs
@@ -1,44 +1,29 @@
-//! WDT (map tile table) reader + tile↔world coords for **WoW 1.12.1 (build 5875)** — in-repo,
-//! replacing `wow-wdt` (decision 0021).
+//! The 1.12.1 WDT (map tile table) reader, and the tile and world coordinate helpers.
 //!
-//! A vanilla `.wdt` is a tiny chunked file (`MVER`, `MPHD`, `MAIN`, and — on a **WMO-only map** —
-//! `MWMO` + one `MODF`). Two things in it matter to the streamer:
-//!
-//! - **`MAIN`** — a 64×64 table of 8-byte entries whose flag bit 0 (`0x1`) marks "this tile has an
-//!   `.adt`".
-//! - **The global WMO** — `MPHD` dword0 bit 0 marks a map with **no terrain at all**, whose whole
-//!   world is one building placed by the single `MODF` entry after `MWMO`. 20 of the 43 shipped
-//!   maps are built this way (every WMO dungeon: the Blackrock pair, Gnomeregan, Dire Maul, the
-//!   Stockade…); on those maps `MAIN` is entirely empty and this placement *is* the map
-//!   (decision 0688).
-//!
-//! The coord helpers map a world `(x, y)` to its `(tile_x, tile_y)` and back, on the 64-tile,
-//! 533⅓-yd grid.
-//!
-//! Proven against `wow-wdt` over a real map's WDT during the decision-0021 migration (oracle test in
-//! git history); the `benilla-formats` terrain tests pin tile selection + world coords end-to-end.
+//! A `.wdt` holds `MVER`, `MPHD`, `MAIN` and, on a WMO-only map, `MWMO` and one `MODF`. `MAIN` is a
+//! 64×64 table of 8-byte entries whose flag bit 0 marks a tile with an `.adt`. `MPHD` dword 0 bit 0
+//! marks a map with no terrain, whose whole world is the one building the `MODF` places: 20 of the
+//! 43 shipped maps, every WMO dungeon, each with an empty `MAIN`.
 
 use std::io::{Read, Seek, SeekFrom};
 
-/// WoW client generation. We only target Classic (1.12.1); kept as an enum so the reader signature
-/// matches the call sites.
+/// The client generation; 1.12.1 is the only one.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum WowVersion {
     Classic,
 }
 
-/// Re-export so `benilla_wdt::version::WowVersion` resolves (mirrors the original crate's module path).
+/// Re-export, so `benilla_wdt::version::WowVersion` resolves.
 pub mod version {
     pub use super::WowVersion;
 }
 
-/// Tiles per map edge (64×64).
+/// Tiles per map edge.
 const MAP_SIZE: usize = 64;
-/// Yards per ADT tile (1/64 of the map edge).
 const TILE_YARDS: f32 = 533.333_3;
 
-/// World `(x, y)` → ADT tile `(tile_x, tile_y)`. WoW's axes are swapped vs the tile grid: `tile_x`
-/// comes from world **y**, `tile_y` from world **x**. Clamped to `0..=63`.
+/// World `(x, y)` → ADT tile `(tile_x, tile_y)`, clamped to `0..=63`. The axes swap: `tile_x`
+/// comes from world y, `tile_y` from world x.
 pub fn world_to_tile(world_x: f32, world_y: f32) -> (u32, u32) {
     let offset = 32.0 * TILE_YARDS;
     let tile_x = ((offset - world_y) / TILE_YARDS) as u32;
@@ -46,17 +31,13 @@ pub fn world_to_tile(world_x: f32, world_y: f32) -> (u32, u32) {
     (tile_x.min(63), tile_y.min(63))
 }
 
-/// Chunks per tile edge (16×16 per ADT) and per map edge (1024).
 const CHUNKS_PER_TILE: u32 = 16;
-/// Yards per terrain chunk (1/16 of a tile, 33⅓ yd).
 const CHUNK_YARDS: f32 = TILE_YARDS / CHUNKS_PER_TILE as f32;
 
-/// World `(x, y)` → the **chunk** index `(chunk_x, chunk_y)` on the 1024×1024 chunk grid — the same
-/// axis swap as [`world_to_tile`], and `chunk >> 4` is exactly that tile. Clamped to `0..=1023`.
-///
-/// This is the reference's own streaming coordinate: `0x672730` computes
-/// `fistp((17066.666 − pos) × 0.03 − 0.5)` per axis — the containing chunk — and sizes its
-/// residency windows in these units (wow-re `terrain.md`, "Streaming residency").
+/// World `(x, y)` → chunk `(chunk_x, chunk_y)` on the 1024×1024 grid, clamped to `0..=1023`, with
+/// [`world_to_tile`]'s axis swap and `chunk >> 4` its tile. It is the reference's streaming
+/// coordinate: `0x672730` computes `fistp((17066.666 - pos) * 0.03 - 0.5)` per axis and sizes its
+/// residency windows in chunks.
 pub fn world_to_chunk(world_x: f32, world_y: f32) -> (u32, u32) {
     let offset = 32.0 * TILE_YARDS;
     let max = MAP_SIZE as u32 * CHUNKS_PER_TILE - 1;
@@ -65,8 +46,7 @@ pub fn world_to_chunk(world_x: f32, world_y: f32) -> (u32, u32) {
     (chunk_x.min(max), chunk_y.min(max))
 }
 
-/// ADT tile `(tile_x, tile_y)` → the world `(x, y)` of its max-corner origin (inverse of
-/// [`world_to_tile`]).
+/// ADT tile → the world `(x, y)` of its max corner, the inverse of [`world_to_tile`].
 pub fn tile_to_world(tile_x: u32, tile_y: u32) -> (f32, f32) {
     let offset = 32.0 * TILE_YARDS;
     (
@@ -75,7 +55,7 @@ pub fn tile_to_world(tile_x: u32, tile_y: u32) -> (f32, f32) {
     )
 }
 
-/// Info about one map tile (the subset the streamer reads).
+/// One map tile, as the streamer reads it.
 #[derive(Debug, Clone, Copy)]
 pub struct TileInfo {
     pub x: usize,
@@ -84,27 +64,21 @@ pub struct TileInfo {
     pub has_adt: bool,
 }
 
-/// The single building that **is** a WMO-only map — the `MWMO` path plus the one `MODF` entry that
-/// follows it (decision 0688). Position/rotation are already in the same convention as an ADT's own
-/// MODF placements (`benilla_formats::WmoInstance`), so the streamer places it through the exact
-/// path it places any other building with.
+/// The one building that is a WMO-only map: the `MWMO` path and its `MODF` entry, already in
+/// `benilla_formats::WmoInstance`'s convention.
 #[derive(Debug, Clone)]
 pub struct GlobalWmo {
     /// `MWMO` root path (e.g. `world\wmo\dungeon\az_stormwindprisons\stormwindjail.wmo`).
     pub model: String,
-    /// Position in WoW world coords (X north, Y west, Z up).
-    ///
-    /// Taken **raw** from the MODF, without the `32·533⅓ − v` corner-origin remap an ADT's
-    /// placements get: this entry is authored in world coords already. Every shipped WMO-only map
-    /// stores `(0, 0, 0)` here, and the remap would put the whole dungeon 24 km from its own
-    /// entrance — falsified against all 26 of the server's real entry points (decision 0688).
+    /// Position in world coords (X north, Y west, Z up), taken raw: the `32·533⅓ - v` remap an
+    /// ADT's placements get would put every shipped WMO-only map, which stores `(0, 0, 0)`, 24 km
+    /// from its entrance.
     pub position: [f32; 3],
-    /// Euler rotation in **degrees** (X, Y, Z); Y is the heading about the up axis. Live data, not
-    /// always identity: Dire Maul is authored at `ry = 180°` while the other 19 maps sit at 0.
+    /// Euler rotation in degrees (X, Y, Z), Y the heading; Dire Maul's `ry` is 180°, the rest 0.
     pub rotation: [f32; 3],
-    /// MODF doodad-set index — which *additional* prop set to show beyond the always-on set 0.
+    /// MODF doodad-set index: the prop set shown beside the always-on set 0.
     pub doodad_set: u16,
-    /// MODF name-set index — the placement's `WMOAreaTable.NameSetID` naming/audio variant.
+    /// MODF name-set index, the placement's `WMOAreaTable.NameSetID` variant.
     pub name_set: u16,
 }
 
@@ -113,12 +87,10 @@ pub struct GlobalWmo {
 pub struct WdtFile {
     /// `has_adt` per tile, indexed `y * 64 + x` (the on-disk MAIN order).
     has_adt: Vec<bool>,
-    /// The whole map, on a map with no terrain; `None` on an ADT map.
     global_wmo: Option<GlobalWmo>,
 }
 
 impl WdtFile {
-    /// Tile info at `(x, y)`, or `None` out of range.
     pub fn get_tile(&self, x: usize, y: usize) -> Option<TileInfo> {
         if x >= MAP_SIZE || y >= MAP_SIZE {
             return None;
@@ -130,8 +102,7 @@ impl WdtFile {
         })
     }
 
-    /// The map's single global building, if this is a WMO-only map (`MPHD` bit 0) — the entire
-    /// world on such a map. `None` on an ADT map, where the ground comes from the tiles instead.
+    /// The map's one building, on a WMO-only map (`MPHD` bit 0).
     pub fn global_wmo(&self) -> Option<&GlobalWmo> {
         self.global_wmo.as_ref()
     }
@@ -151,9 +122,25 @@ impl<R: Read + Seek> WdtReader<R> {
         }
     }
 
-    /// Parse the WDT, returning the tile grid and (on a WMO-only map) the global WMO placement.
-    /// Walks chunks until EOF; everything but `MPHD`/`MAIN`/`MWMO`/`MODF` is skipped.
+    /// One chunk's payload, refused before the buffer is sized if the stream cannot hold it.
+    fn read_payload(&mut self, size: u64, stream_end: u64) -> std::io::Result<Vec<u8>> {
+        let remaining = stream_end.saturating_sub(self.reader.stream_position()?);
+        if size > remaining {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::UnexpectedEof,
+                "WDT chunk runs past the end of the stream",
+            ));
+        }
+        let mut buf = vec![0u8; size as usize];
+        self.reader.read_exact(&mut buf)?;
+        Ok(buf)
+    }
+
+    /// Parse the WDT, walking chunks to EOF and skipping all but `MPHD`, `MAIN`, `MWMO` and `MODF`.
     pub fn read(&mut self) -> std::io::Result<WdtFile> {
+        let start = self.reader.stream_position()?;
+        let stream_end = self.reader.seek(SeekFrom::End(0))?;
+        self.reader.seek(SeekFrom::Start(start))?;
         let mut has_adt: Option<Vec<bool>> = None;
         let mut wmo_only = false;
         let mut wmo_path: Option<String> = None;
@@ -163,14 +150,12 @@ impl<R: Read + Seek> WdtReader<R> {
             if !read_full(&mut self.reader, &mut hdr)? {
                 break; // clean EOF
             }
-            // Chunk magics are stored reversed on disk; MAIN ⇒ "NIAM".
+            // Chunk magics are stored reversed on disk: MAIN is "NIAM".
             let size = u32::from_le_bytes([hdr[4], hdr[5], hdr[6], hdr[7]]) as u64;
             match &hdr[0..4] {
-                // MPHD — only dword0 bit 0 is ever read: "this map has no terrain, its world is
-                // the global WMO below" (the reference reads exactly this one bit, @0x694810).
+                // MPHD: the reference reads only dword 0 bit 0, the no-terrain flag (`0x694810`).
                 b"DHPM" if size >= 4 => {
-                    let mut buf = vec![0u8; size as usize];
-                    self.reader.read_exact(&mut buf)?;
+                    let buf = self.read_payload(size, stream_end)?;
                     wmo_only = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]) & 0x1 != 0;
                 }
                 b"NIAM" => {
@@ -191,22 +176,19 @@ impl<R: Read + Seek> WdtReader<R> {
                         .collect();
                     has_adt = Some(grid);
                 }
-                // MWMO — one NUL-terminated path on a WMO-only map, and a zero-length stub on an
-                // ADT map (which is why the `wmo_only` flag, not this chunk, is the gate).
+                // MWMO: a NUL-terminated path on a WMO-only map, a zero-length stub on an ADT map,
+                // so the `wmo_only` flag, not this chunk, is the gate.
                 b"OMWM" if size > 0 => {
-                    let mut buf = vec![0u8; size as usize];
-                    self.reader.read_exact(&mut buf)?;
+                    let buf = self.read_payload(size, stream_end)?;
                     let end = buf.iter().position(|&b| b == 0).unwrap_or(buf.len());
                     let path = String::from_utf8_lossy(&buf[..end]).into_owned();
                     if !path.is_empty() {
                         wmo_path = Some(path);
                     }
                 }
-                // MODF — exactly one 64-byte placement here (the ADT variant carries many).
+                // MODF: exactly one 64-byte placement here.
                 b"FDOM" if size >= 64 => {
-                    let mut buf = vec![0u8; size as usize];
-                    self.reader.read_exact(&mut buf)?;
-                    modf = Some(buf);
+                    modf = Some(self.read_payload(size, stream_end)?);
                 }
                 _ => {
                     self.reader.seek(SeekFrom::Current(size as i64))?;
@@ -216,15 +198,14 @@ impl<R: Read + Seek> WdtReader<R> {
         let has_adt = has_adt.ok_or_else(|| {
             std::io::Error::new(std::io::ErrorKind::InvalidData, "WDT missing MAIN chunk")
         })?;
-        // A WMO-only map with no placement to show would be an empty void, so demand both parts
-        // before claiming one — a malformed header bit alone must not suppress the tile grid.
+        // The flag and a placement, or no global WMO: a stray header bit must not hide the grid.
         let global_wmo = match (wmo_only, wmo_path, modf) {
             (true, Some(model), Some(e)) => Some(GlobalWmo {
                 model,
                 position: [f32_at(&e, 8), f32_at(&e, 12), f32_at(&e, 16)],
                 rotation: [f32_at(&e, 20), f32_at(&e, 24), f32_at(&e, 28)],
-                // 0x20..0x38 is the bounding box; the placement words follow it. (`uniqueId` at
-                // +4 is dead here — the reference overwrites it from its own counter @0xc9a320.)
+                // 0x20..0x38 is the bounding box. `uniqueId` at +4 is unread: the reference
+                // overwrites it from its own counter (`0xc9a320`).
                 doodad_set: u16_at(&e, 58),
                 name_set: u16_at(&e, 60),
             }),
@@ -237,21 +218,19 @@ impl<R: Read + Seek> WdtReader<R> {
     }
 }
 
-/// Little-endian `f32` at `off` (0.0 past the end — callers have already length-checked the entry).
 fn f32_at(b: &[u8], off: usize) -> f32 {
     b.get(off..off + 4)
         .and_then(|s| s.try_into().ok())
         .map_or(0.0, f32::from_le_bytes)
 }
 
-/// Little-endian `u16` at `off` (0 past the end).
 fn u16_at(b: &[u8], off: usize) -> u16 {
     b.get(off..off + 2)
         .and_then(|s| s.try_into().ok())
         .map_or(0, u16::from_le_bytes)
 }
 
-/// Read exactly `buf.len()` bytes; `Ok(false)` on a clean EOF before any byte, `Ok(true)` on success.
+/// Read exactly `buf.len()` bytes; `Ok(false)` on a clean EOF before any byte.
 fn read_full<R: Read>(reader: &mut R, buf: &mut [u8]) -> std::io::Result<bool> {
     let mut filled = 0;
     while filled < buf.len() {
@@ -279,14 +258,12 @@ mod tests {
     use super::*;
     use std::io::Cursor;
 
-    // Mirror of the crate-private grid constants, so the tests read the geometry independently of
-    // the values the code under test happens to use.
+    // The grid constants restated, so the tests do not read the code's own.
     const T: f32 = 533.333_3;
     const OFFSET: f32 = 32.0 * T;
 
-    /// Build a minimal on-disk WDT: an ignored `MVER`, an ignored `MPHD`, then a `MAIN` whose flag
-    /// bit 0 is set exactly for the `set_tiles` `(x, y)` list. A trailing unknown chunk exercises
-    /// the seek-past-unknown path *after* `MAIN` too.
+    /// A minimal WDT: `MVER`, a zero `MPHD`, a `MAIN` flagging exactly `set_tiles`, and an unknown
+    /// chunk after it if `trailing`.
     fn synth_wdt(set_tiles: &[(usize, usize)], trailing: bool) -> Vec<u8> {
         let mut out = Vec::new();
         let chunk = |magic: &[u8; 4], payload: &[u8], out: &mut Vec<u8>| {
@@ -294,11 +271,8 @@ mod tests {
             out.extend_from_slice(&(payload.len() as u32).to_le_bytes());
             out.extend_from_slice(payload);
         };
-        // MVER (magic reversed on disk) — version 18, ignored by the reader.
         chunk(b"REVM", &18u32.to_le_bytes(), &mut out);
-        // MPHD — 32 bytes of header we don't read.
         chunk(b"DHPM", &[0u8; 32], &mut out);
-        // MAIN — 64×64 × 8 bytes; set bit 0 of `flags` for the requested tiles.
         let count = MAP_SIZE * MAP_SIZE;
         let mut main = vec![0u8; count * 8];
         for &(x, y) in set_tiles {
@@ -316,8 +290,8 @@ mod tests {
         WdtReader::new(Cursor::new(bytes), WowVersion::Classic).read()
     }
 
-    /// A WMO-only map's on-disk shape: `MPHD` bit 0, an all-empty `MAIN`, then `MWMO` + one 64-byte
-    /// `MODF`. Field values are distinct primes-ish so a column slip can't pass.
+    /// A WMO-only map: `MPHD` bit 0, an empty `MAIN`, `MWMO` and one 64-byte `MODF` of distinct
+    /// values, so a column slip fails.
     fn synth_wmo_only_wdt(mphd_bit0: bool, with_modf: bool) -> Vec<u8> {
         let mut out = Vec::new();
         let chunk = |magic: &[u8; 4], payload: &[u8], out: &mut Vec<u8>| {
@@ -334,15 +308,15 @@ mod tests {
         if with_modf {
             let mut e = [0u8; 64];
             e[0..4].copy_from_slice(&0u32.to_le_bytes()); // nameId
-            e[4..8].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes()); // uniqueId (dead)
+            e[4..8].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes()); // uniqueId, unread
             for (i, v) in [11.0f32, 22.0, 33.0].iter().enumerate() {
                 e[8 + i * 4..12 + i * 4].copy_from_slice(&v.to_le_bytes()); // position
             }
             for (i, v) in [1.0f32, 180.0, 2.0].iter().enumerate() {
                 e[20 + i * 4..24 + i * 4].copy_from_slice(&v.to_le_bytes()); // rotation
             }
-            // 0x20..0x38 bounding box left zero — we don't read it.
-            e[56..58].copy_from_slice(&7u16.to_le_bytes()); // flags (dead)
+            // 0x20..0x38, the bounding box, left zero: unread.
+            e[56..58].copy_from_slice(&7u16.to_le_bytes()); // flags, unread
             e[58..60].copy_from_slice(&3u16.to_le_bytes()); // doodadSet
             e[60..62].copy_from_slice(&5u16.to_le_bytes()); // nameSet
             chunk(b"FDOM", &e, &mut out);
@@ -350,8 +324,6 @@ mod tests {
         out
     }
 
-    /// The WMO-only branch end to end: the `MPHD` gate, the `MWMO` path, and every `MODF` column
-    /// the streamer places the building with. Position is read **raw** — no corner-origin remap.
     #[test]
     fn reads_the_global_wmo_of_a_wmo_only_map() {
         let wdt = parse(synth_wmo_only_wdt(true, true)).expect("parses");
@@ -360,27 +332,21 @@ mod tests {
         assert_eq!(g.position, [11.0, 22.0, 33.0]);
         assert_eq!(g.rotation, [1.0, 180.0, 2.0]);
         assert_eq!((g.doodad_set, g.name_set), (3, 5));
-        // Such a map authors no tiles — the grid still parses, it's just empty.
         assert!(!wdt.get_tile(32, 32).expect("in range").has_adt);
     }
 
-    /// An ADT map carries a zero-length `MWMO` stub and no `MODF`; it must not claim a global WMO
-    /// (which would spawn a phantom building over real terrain).
     #[test]
     fn an_adt_map_has_no_global_wmo() {
         let wdt = parse(synth_wdt(&[(30, 30)], false)).expect("parses");
         assert!(wdt.global_wmo().is_none());
-        // …and neither does a malformed file that sets the bit but ships no placement: a stray
-        // header bit must degrade to "no global WMO", never to a half-built one.
+        // Nor a file with the bit but no placement,
         let half = parse(synth_wmo_only_wdt(true, false)).expect("parses");
         assert!(half.global_wmo().is_none());
-        // …nor one that ships the placement without the flag.
+        // nor one with the placement but no bit.
         let unflagged = parse(synth_wmo_only_wdt(false, true)).expect("parses");
         assert!(unflagged.global_wmo().is_none());
     }
 
-    /// The chunk grid nests in the tile grid: `chunk >> 4` is the tile `world_to_tile` names, at
-    /// every chunk centre of a whole tile and at the map's far clamp.
     #[test]
     fn the_chunk_index_nests_in_the_tile_index() {
         let (ox, oy) = tile_to_world(32, 44);
@@ -400,14 +366,12 @@ mod tests {
 
     #[test]
     fn world_origin_is_map_center_tile() {
-        // World (0, 0) sits at the 32,32 tile boundary — the documented map center.
         assert_eq!(world_to_tile(0.0, 0.0), (32, 32));
     }
 
     #[test]
     fn tile_center_round_trips_exactly() {
-        // Sample the *center* of each tile (corner minus half a tile on both axes); a half-tile
-        // margin absorbs f32 rounding so truncation can't spill into a neighbour.
+        // Tile centres: the half-tile margin absorbs f32 rounding.
         for &(tx, ty) in &[(0, 0), (1, 10), (20, 31), (33, 33), (50, 62), (63, 63)] {
             let (cx, cy) = tile_to_world(tx, ty);
             let center = (cx - 0.5 * T, cy - 0.5 * T);
@@ -430,7 +394,6 @@ mod tests {
 
     #[test]
     fn world_to_tile_clamps_both_extremes() {
-        // Far past the max corner saturates low; far past the min corner clamps to the last tile.
         assert_eq!(world_to_tile(1.0e9, 1.0e9), (0, 0));
         assert_eq!(world_to_tile(-1.0e9, -1.0e9), (63, 63));
     }
@@ -441,7 +404,6 @@ mod tests {
         assert!(wdt.get_tile(3, 5).unwrap().has_adt);
         assert!(wdt.get_tile(63, 0).unwrap().has_adt);
         assert!(wdt.get_tile(0, 63).unwrap().has_adt);
-        // An untouched tile reads empty, and the returned coords echo the query.
         let empty = wdt.get_tile(10, 10).unwrap();
         assert!(!empty.has_adt);
         assert_eq!((empty.x, empty.y), (10, 10));
@@ -449,7 +411,6 @@ mod tests {
 
     #[test]
     fn skips_unknown_chunks_before_and_after_main() {
-        // MVER/MPHD precede MAIN and a bogus chunk follows it; all must be seek-skipped cleanly.
         let wdt = parse(synth_wdt(&[(1, 1)], true)).unwrap();
         assert!(wdt.get_tile(1, 1).unwrap().has_adt);
     }
@@ -464,7 +425,6 @@ mod tests {
 
     #[test]
     fn missing_main_chunk_is_an_error() {
-        // Only MVER present — no MAIN ⇒ InvalidData.
         let mut only_mver = Vec::new();
         only_mver.extend_from_slice(b"REVM");
         only_mver.extend_from_slice(&4u32.to_le_bytes());
@@ -475,7 +435,7 @@ mod tests {
 
     #[test]
     fn empty_stream_has_no_main() {
-        // A clean EOF at the very first header is not a truncation error, but still no MAIN.
+        // A clean EOF, not a truncation, but still no MAIN.
         let err = parse(Vec::new()).unwrap_err();
         assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
     }
@@ -486,4 +446,18 @@ mod tests {
         let err = parse(vec![b'N', b'I', b'A']).unwrap_err();
         assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
     }
+
+    /// The message pins that the guard refuses, not the read after it.
+    #[test]
+    fn a_chunk_size_past_the_end_of_stream_is_refused_before_allocating() {
+        for magic in [b"DHPM", b"OMWM", b"FDOM"] {
+            let mut bytes = Vec::new();
+            bytes.extend_from_slice(magic);
+            bytes.extend_from_slice(&u32::MAX.to_le_bytes());
+            bytes.extend_from_slice(&[0u8; 64]); // some payload, nowhere near the claim
+            let err = parse(bytes).unwrap_err();
+            assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
+            assert_eq!(err.to_string(), "WDT chunk runs past the end of the stream");
+        }
+    }
 }
diff --git a/crates/benilla-wmo/Cargo.toml b/crates/benilla-wmo/Cargo.toml
index b043efd7..96fc4ee2 100644
--- a/crates/benilla-wmo/Cargo.toml
+++ b/crates/benilla-wmo/Cargo.toml
@@ -3,7 +3,7 @@ name = "benilla-wmo"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "WMO (root + group) reader for WoW 1.12.1 (build 5875) — in-repo, decision 0021"
+description = "WMO (root and group) reader for WoW 1.12.1 (build 5875)"
 
 [lints]
 workspace = true
diff --git a/crates/benilla-wmo/src/lib.rs b/crates/benilla-wmo/src/lib.rs
index 9fd1e09e..53217776 100644
--- a/crates/benilla-wmo/src/lib.rs
+++ b/crates/benilla-wmo/src/lib.rs
@@ -1,24 +1,13 @@
-//! A WMO (World Map Object) reader for **WoW 1.12.1 (build 5875)** — in-repo, replacing `wow-wmo`
-//! (decision 0021), scoped to what the renderer consumes.
-//!
-//! A WMO is split across a **root** file (`MOHD` header, `MOTX` texture blob, `MOMT` materials, group
-//! info, doodads, lights) and one **group** file per group (`MOGP` super-chunk wrapping `MOVT`/`MONR`/
-//! `MOTV`/`MOVI`/`MOBA`/`MOCV`). [`parse_wmo`] returns whichever the bytes are. Chunks are IFF-style:
-//! a 4-char magic stored **reversed** on disk, a `u32` size, then payload.
-//!
-//! Byte access goes through `benilla-bytes` (decision 0064): every read is bounds-checked and a
-//! truncated chunk is a typed [`Error::Truncated`], never a panic or a silently-empty struct.
-//!
-//! Only the render path lives here; benilla-formats hand-parses MOLT/MOGI/MODS/MOPY itself. Proven
-//! against `wow-wmo` over real WMOs during the decision-0021 migration (oracle test in git history);
-//! the WMO mesh/collision golden tests in benilla-formats pin it end-to-end on every run.
+//! A 1.12.1 WMO (World Map Object) reader, scoped to what the renderer consumes. A root file holds
+//! `MOHD`, `MOTX` and `MOMT` among its tables; each group file holds a `MOGP` super-chunk wrapping
+//! the geometry sub-chunks. A chunk is a 4-char magic stored reversed, a `u32` size, the payload.
 
 use std::collections::HashMap;
 use std::io::Cursor;
 
 use benilla_bytes::{chunks, ByteExt};
 
-/// A parsed WMO file — either the root or one group.
+/// A parsed WMO file: the root or one group.
 pub enum ParsedWmo {
     Root(WmoRoot),
     Group(WmoGroup),
@@ -27,8 +16,8 @@ pub enum ParsedWmo {
 /// The WMO root: textures, materials, and the group count.
 pub struct WmoRoot {
     pub textures: Vec<String>,
-    /// MOTX byte-offset → index into [`textures`](Self::textures) (materials reference textures by the
-    /// byte offset of their name in the MOTX blob).
+    /// MOTX byte offset → index into [`textures`](Self::textures): a material names its texture by
+    /// the offset of the name in the blob.
     pub texture_offset_index_map: HashMap<u32, u32>,
     pub materials: Vec<Material>,
     /// Group count (`MOHD.nGroups`).
@@ -41,33 +30,20 @@ pub struct Material {
     pub blend_mode: u32,
     /// Byte offset of texture 1's name in the MOTX blob.
     pub texture_1: u32,
-    /// The authored **SIDN** self-illum colour (MOMT+0x10, stored BGRA on disk — here RGB). The real
-    /// client's per-frame updater scales it by the night fraction and adds it as the material
-    /// EMISSION on lit batches (`flags & 0x10` — the windows-glow-at-night mechanism). Meaningless
-    /// (usually zero) when the SIDN flag is clear.
+    /// The SIDN self-illumination colour (MOMT+0x10, BGRA on disk, RGB here): the client scales it
+    /// by the night fraction and adds it as emission on batches with `flags & 0x10`, the windows'
+    /// glow at night.
     pub sidn_rgb: [u8; 3],
-    /// **MOMT+0x1C — `diffColor`**, the material's authored diffuse colour (BGRA on disk, RGB here).
-    ///
-    /// Read for exactly one consumer: it is the **body colour of an interior WMO liquid pool**. The
-    /// reference's interior water kernel `0x6b6420` runs with lighting forced off and no pixel
-    /// shader, and its whole RGB is this dword taken raw — `Cf = MOMT[MLIQ.materialId].diffColor`,
-    /// combined with the animated sheet as `clamp(Cf + Ct)`. The pool's material's own alpha at
-    /// `+0x1f` is discarded; opacity comes from the per-vertex LUT instead.
-    ///
-    /// The offset is anchored on both sides by fields this repo verified independently of water:
-    /// `+0x18` texture 2 and `+0x20` [`Self::ground_type`]. Stride 0x40, base `[CMapObj+0x1d8]`
-    /// (`0x6c3ace` + `0x6c3ad7 shr edx,6`). VERIFIED wow-re `terrain/scratch/water-shading-law.md`.
+    /// MOMT+0x1C `diffColor` (BGRA on disk, RGB here), read only as an interior liquid's body
+    /// colour: the reference's interior water kernel `0x6b6420` runs unlit with no pixel shader,
+    /// its RGB this dword raw, `Cf = MOMT[MLIQ.materialId].diffColor`, combined with the animated
+    /// sheet as `clamp(Cf + Ct)`. Its alpha at `+0x1f` is discarded; opacity comes per vertex.
+    /// Stride 0x40, base `[CMapObj+0x1d8]` (`0x6c3ace`, `0x6c3ad7 shr edx,6`).
     pub diff_color: [u8; 3],
-    /// **MOMT+0x20 — the surface's `TerrainType.dbc` id**, i.e. what walking on this material
-    /// sounds like. The footstep chain's WMO leg: the client's down-ray arbitrates a terrain probe
-    /// against a WMO probe and the nearer surface supplies the terrain type, so a building's own
-    /// floor — not the ADT beneath it — decides the step indoors.
-    ///
-    /// Verified from the shipped 5875 data, not from a format doc: across all **815 root WMOs /
-    /// 10 299 materials** this dword only ever holds `{0,1,2,3,4,5,7,8,10}` — exactly the
-    /// `TerrainType.dbc` id domain (ids 0–10) — and **10 = "None" on 10 075 of them**, the
-    /// unauthored default, which resolves through `SoundID 0` to the generic `*Dirt` kit rather
-    /// than to silence. Only ~224 materials name a surface explicitly.
+    /// MOMT+0x20: the surface's `TerrainType.dbc` id, what a footstep on it sounds like. The
+    /// client's down-ray takes the nearer of the terrain and WMO probes, so a building's floor
+    /// decides the step indoors. The 5875 data holds only `{0,1,2,3,4,5,7,8,10}`; 10 ("None", on
+    /// 10 075 of 10 299 materials) resolves through `SoundID 0` to the generic `*Dirt` kit.
     pub ground_type: u32,
 }
 
@@ -110,63 +86,40 @@ pub struct Batch {
     pub material_id: u8,
 }
 
-/// A MOPY per-face material/flags entry (2 bytes), one per triangle — drives collision filtering.
+/// A MOPY entry, one triangle's flags and material (2 bytes); it drives collision filtering.
 pub struct MopyEntry {
     pub flags: u8,
     pub material_id: u8,
 }
 
-/// One WMO group's MLIQ liquid grid (the water/lava/slime surface embedded in the group — canals,
-/// fountains, dungeon pools). A flat `xverts × yverts` height grid over `xtiles × ytiles` cells, in
-/// **WMO model space** (WoW axes, yards); the placement transform lifts it into the world. Cell
-/// membership + type come from the per-tile flag low nibble (`& 0xf`): `0xf` = hole (no liquid), else
-/// the nibble is the liquid type indexing the reference's texture table (VERIFIED wow-re
-/// `rf-water-liquid-type-texture-material.md`; render dispatch `0x6b62e0`, water kernels
-/// `0x6b6420`/`0x6b6630`, magma/slime `0x6b68f0` — `rf-mliq-liquid-uv-texgen.md`).
+/// A WMO group's MLIQ liquid grid: `xverts × yverts` heights over `xtiles × ytiles` cells in WMO
+/// model space (WoW axes, yards). A tile flag's low nibble is `0xf` for a hole, else the liquid
+/// type indexing the reference's texture table (dispatch `0x6b62e0`, water `0x6b6420` and
+/// `0x6b6630`, magma and slime `0x6b68f0`).
 pub struct WmoLiquid {
-    /// Vertex-grid dimensions (`xtiles = xverts − 1`, `ytiles = yverts − 1`).
+    /// Vertex-grid dimensions (`xtiles = xverts - 1`, `ytiles = yverts - 1`).
     pub xverts: u32,
     pub yverts: u32,
     pub xtiles: u32,
     pub ytiles: u32,
-    /// The `(0,0)` grid corner in WMO model space (WoW `[x, y, z]`, yards). Grid vertex `(i, j)` sits
-    /// at `(base.x + i·MLIQ_CELL_STEP, base.y + j·MLIQ_CELL_STEP, heights[j·xverts + i])`.
+    /// The `(0,0)` grid corner in WMO model space (WoW `[x, y, z]`, yards). Grid vertex `(i, j)`
+    /// sits at `(base.x + i·MLIQ_CELL_STEP, base.y + j·MLIQ_CELL_STEP, heights[j·xverts + i])`.
     pub base: [f32; 3],
-    /// MLIQ `materialId` (index into the root MOMT — unused by the animated-water render path, which
-    /// selects its texture from the tile-flag type; kept for completeness).
+    /// MLIQ `materialId`, an index into the root MOMT, whose `diffColor` colours an interior pool.
     pub material_id: u16,
-    /// Per-vertex absolute liquid height (WMO-local Z), row-major `j·xverts + i`, `xverts·yverts` long.
-    /// The MLIQ vertex is 8 bytes and the height is its trailing `f32`; what the leading 4 bytes mean
-    /// is per liquid type — see [`Self::opacity`] for the water reading.
+    /// Per-vertex liquid height (WMO-local Z), row-major `j·xverts + i`: the trailing `f32` of each
+    /// 8-byte MLIQ vertex, whose leading 4 bytes depend on the liquid type.
     pub heights: Vec<f32>,
-    /// Per-vertex **opacity index** — the water vertex's byte 0, row-major beside [`Self::heights`].
-    ///
-    /// WMO liquid carries no bathymetry, so nothing here can be ramped by depth the way ADT MCLQ's
-    /// water is; this byte **is** the authored opacity. The reference indexes a 256-entry alpha ramp
-    /// (`[0xca7f10]`, rebuilt per frame from the zone's river shallow/deep alpha pair) with it and
-    /// uses the result as the vertex alpha — the water arms bind no depth-ramp texture at all
-    /// (VERIFIED wow-re `terrain/scratch/water-shading-law.md`; zero references to the ADT ramp
-    /// globals `0xc7fbc0`/`0xc81768`/`0xc7fcd8` anywhere in `[0x6b0000, 0x6c4000)`).
-    ///
-    /// It was parsed as nothing for a long time — the field it replaced was documented as "flow
-    /// data" — which is why every WMO pool in benilla rendered at one pinned opacity.
-    ///
-    /// On the **magma/slime** arm the same four bytes are an authored `int16` `(s, t)` UV pair
-    /// instead, so byte 0 there is half a texture coordinate and means nothing as an opacity. The
-    /// consumer picks by liquid type; this parser just carries the byte.
-    ///
-    /// That split is also what corroborates the reading against the shipped data, independently of
-    /// the disassembly. Censused over every drawn liquid vertex in the corpus: on the **water** arms
-    /// the byte is structured — Stormwind's canals are **91.2% a single value (86)** across 3492
-    /// vertices with only 41 distinct values, exactly the shape of an authored per-surface opacity —
-    /// while on **magma/slime** it is near-uniform noise over all 256 values (each ≈0.7–1.4%), which
-    /// is what half of a texture coordinate should look like. A byte that is a constant on one arm
-    /// and white noise on the other is not being read at the wrong offset.
+    /// Per-vertex opacity index, a water vertex's byte 0, row-major beside [`Self::heights`]. WMO
+    /// liquid has no depth, so this byte is the authored opacity: the reference indexes a 256-entry
+    /// alpha ramp with it (`[0xca7f10]`, rebuilt per frame from the zone's river shallow and deep
+    /// alphas) and binds no depth-ramp texture (no reference to the ADT ramp globals `0xc7fbc0`,
+    /// `0xc81768`, `0xc7fcd8` in `[0x6b0000, 0x6c4000)`). On magma and slime the four bytes are an
+    /// `int16` `(s, t)` UV pair instead; the consumer picks by liquid type.
     pub opacity: Vec<u8>,
-    /// Per-tile flag bytes, row-major `j·xtiles + i`, `xtiles·ytiles` long. Low nibble = liquid type;
-    /// `0xf` = hole (skip the tile); `0x80` shared (the strip-builder gate). `0x40` ("fishable") is
-    /// carried but deliberately unread: the reference's WMO-side reader `0x6b9e50` is only reached
-    /// from the zero-caller `0x69b5d0` island — fishability is the server's verdict. Decision 1825.
+    /// Per-tile flags, row-major `j·xtiles + i`: the low nibble the liquid type (`0xf` a hole),
+    /// `0x80` shared (the strip-builder gate). `0x40` (fishable) is unread: the reference's reader
+    /// `0x6b9e50` is reachable only from the uncalled `0x69b5d0`, and the server decides fishing.
     pub tile_flags: Vec<u8>,
 }
 
@@ -174,9 +127,8 @@ pub struct WmoLiquid {
 pub struct WmoGroup {
     /// MOGP group flags (bit test `& 0x48` selects exterior vs interior).
     pub flags: u32,
-    /// MOGP `groupLiquid` @ header `0x34` — the liquid **type override**: when `!= 0xf` it names the
-    /// whole group's liquid type directly (wow-re `wmoliquid` `type_override`); `0xf` (the common
-    /// case) defers to the per-tile MLIQ nibble. `0xf` when the header is too short to carry it.
+    /// MOGP `groupLiquid` at header `0x34`: other than `0xf` it overrides every tile's liquid type
+    /// (`0x6b9f10`); `0xf`, also the value for a header too short to carry it, defers to the tiles.
     pub group_liquid: u32,
     pub vertex_positions: Vec<Vec3>,
     pub vertex_normals: Vec<Vec3>,
@@ -184,9 +136,7 @@ pub struct WmoGroup {
     pub vertex_colors: Vec<Color>,
     pub vertex_indices: Vec<u16>,
     pub render_batches: Vec<Batch>,
-    /// MOPY per-face material/flags (one per triangle).
     pub material_info: Vec<MopyEntry>,
-    /// The group's MLIQ liquid grid, if it carries one (`QILM` sub-chunk present).
     pub liquid: Option<WmoLiquid>,
 }
 
@@ -241,10 +191,10 @@ fn parse_root(b: &[u8]) -> Result<WmoRoot> {
                 root.textures = t;
                 root.texture_offset_index_map = m;
             }
-            // MOMT entry is 64 bytes: flags@0, shader@4, blend_mode@8, texture_1@12, sidnColor@16, …
+            // A 64-byte MOMT entry: flags@0, shader@4, blend_mode@8, texture_1@12, sidnColor@16.
             b"TMOM" => {
                 for m in p.as_chunks::<64>().0 {
-                    // CImVector — BGRA bytes on disk, so the LE u32 reads B | G<<8 | R<<16 | A<<24.
+                    // CImVector: BGRA on disk, so the LE u32 reads B | G<<8 | R<<16 | A<<24.
                     let sidn = m.u32_at(0x10).ok_or(Error::Truncated("MOMT"))?;
                     let diff = m.u32_at(0x1c).ok_or(Error::Truncated("MOMT"))?;
                     root.materials.push(Material {
@@ -263,8 +213,7 @@ fn parse_root(b: &[u8]) -> Result<WmoRoot> {
     Ok(root)
 }
 
-/// MOTX is a NUL-separated string blob; materials reference each name by its byte offset. Build the
-/// texture list + an offset→index map (matching wow-wmo: record the offset at each string's first byte).
+/// MOTX, a NUL-separated name blob: the texture list, and each name's first-byte offset → index.
 fn parse_motx(blob: &[u8]) -> (Vec<String>, HashMap<u32, u32>) {
     let mut textures = Vec::new();
     let mut map = HashMap::new();
@@ -284,12 +233,10 @@ fn parse_motx(blob: &[u8]) -> (Vec<String>, HashMap<u32, u32>) {
     (textures, map)
 }
 
-/// Parse a MOGP super-chunk payload: a 68-byte group header (flags @8) then the geometry sub-chunks.
-/// A payload shorter than the header parses to an empty group (a real-data tolerance, kept from the
-/// pre-0064 reader) — but a *sub-chunk* shorter than its record size is a hard [`Error::Truncated`].
+/// Parse a MOGP payload: a 68-byte header (flags at 8), then the geometry sub-chunks. A payload
+/// shorter than the header is an empty group.
 fn parse_group(mogp: &[u8]) -> Result<WmoGroup> {
     let flags = mogp.u32_at(8).unwrap_or(0);
-    // groupLiquid @ 0x34 (the type override; 0xf = "use the per-tile MLIQ nibble"). Absent header ⇒ 0xf.
     let group_liquid = mogp.u32_at(0x34).unwrap_or(0xf);
     let mut g = WmoGroup {
         flags,
@@ -306,8 +253,8 @@ fn parse_group(mogp: &[u8]) -> Result<WmoGroup> {
     if mogp.len() < 68 {
         return Ok(g);
     }
-    // `extend` (not assign): a sub-chunk that appears more than once concatenates, matching wow-adt's
-    // push-loop (some WMOs carry a second MOTV, e.g. KL_PvPBarracks).
+    // Push, never assign: a repeated sub-chunk concatenates (some WMOs carry a second MOTV, e.g.
+    // KL_PvPBarracks).
     for (magic, s) in chunks(&mogp[68..]) {
         match &magic {
             b"TVOM" => {
@@ -342,7 +289,8 @@ fn parse_group(mogp: &[u8]) -> Result<WmoGroup> {
                         .push(c.u16_at(0).ok_or(Error::Truncated("MOVI"))?);
                 }
             }
-            // MOBA: bbox_min[i16;3] bbox_max[i16;3] start_index(u32@12) count(u16@16) min/max(u16) flags(u8@22) material_id(u8@23)
+            // MOBA: bbox_min[i16;3] bbox_max[i16;3] start_index(u32@12) count(u16@16)
+            // min/max(u16) flags(u8@22) material_id(u8@23)
             b"ABOM" => {
                 for c in s.as_chunks::<24>().0 {
                     g.render_batches.push(Batch {
@@ -362,7 +310,6 @@ fn parse_group(mogp: &[u8]) -> Result<WmoGroup> {
                     });
                 }
             }
-            // MOPY: 2 bytes/face — flags + material id, one per triangle (collision filtering).
             b"YPOM" => {
                 for c in s.as_chunks::<2>().0 {
                     g.material_info.push(MopyEntry {
@@ -371,8 +318,6 @@ fn parse_group(mogp: &[u8]) -> Result<WmoGroup> {
                     });
                 }
             }
-            // MLIQ: the group's liquid grid — a 30-byte SMOLiquidHeader, then `xverts·yverts`
-            // 8-byte vertices (height at +4), then `xtiles·ytiles` 1-byte tile flags.
             b"QILM" => g.liquid = parse_mliq(s)?,
             _ => {}
         }
@@ -380,11 +325,11 @@ fn parse_group(mogp: &[u8]) -> Result<WmoGroup> {
     Ok(g)
 }
 
-/// Parse an `MLIQ` sub-chunk payload into a [`WmoLiquid`]. Returns `Ok(None)` when the payload is
-/// too short for the header or its declared grid (a truncated/garbage chunk yields no liquid rather
-/// than a hard error — the group still renders its geometry).
+/// Parse an `MLIQ` payload into a [`WmoLiquid`]; no liquid when the grid is empty, oversized or
+/// longer than the payload, so the group still renders.
 fn parse_mliq(s: &[u8]) -> Result<Option<WmoLiquid>> {
-    // SMOLiquidHeader: xverts@0 yverts@4 xtiles@8 ytiles@12 base[f32;3]@16 materialId(u16)@28 (30 B).
+    // SMOLiquidHeader, 30 B: xverts@0 yverts@4 xtiles@8 ytiles@12 base[f32;3]@16
+    // materialId(u16)@28; then 8-byte vertices (height at +4), then 1-byte tile flags.
     let (Some(xverts), Some(yverts), Some(xtiles), Some(ytiles)) =
         (s.u32_at(0), s.u32_at(4), s.u32_at(8), s.u32_at(12))
     else {
@@ -392,7 +337,7 @@ fn parse_mliq(s: &[u8]) -> Result<Option<WmoLiquid>> {
     };
     let nverts = (xverts as usize).saturating_mul(yverts as usize);
     let ntiles = (xtiles as usize).saturating_mul(ytiles as usize);
-    // Sanity-cap the grid so a corrupt header can't ask us to allocate gigabytes (real grids are ≤~32²).
+    // A corrupt header must not size gigabytes; real grids are about 32² at most.
     if nverts == 0 || ntiles == 0 || nverts > 1 << 20 || ntiles > 1 << 20 {
         return Ok(None);
     }
@@ -405,13 +350,12 @@ fn parse_mliq(s: &[u8]) -> Result<Option<WmoLiquid>> {
     let vbase = 30usize;
     let tbase = vbase + nverts * 8;
     if s.len() < tbase + ntiles {
-        return Ok(None); // declared grid runs past the payload — treat as no liquid
+        return Ok(None); // the declared grid runs past the payload: no liquid
     }
     let heights: Vec<f32> = (0..nverts)
         .map(|k| s.f32_at(vbase + k * 8 + 4).unwrap_or(0.0))
         .collect();
-    // Byte 0 of the same 8-byte vertex — the water opacity index (see `WmoLiquid::opacity`). The
-    // bounds are already guaranteed by the `tbase` check above.
+    // Byte 0 of each vertex, in bounds by the `tbase` check above.
     let opacity: Vec<u8> = (0..nverts).map(|k| s[vbase + k * 8]).collect();
     let tile_flags = s[tbase..tbase + ntiles].to_vec();
     Ok(Some(WmoLiquid {
@@ -489,7 +433,7 @@ mod tests {
 
     #[test]
     fn group_parses_mliq_liquid_grid() {
-        // A 2×2-vertex (1×1-tile) MLIQ: header + 4 verts (8 B each, height at +4) + 1 tile byte.
+        // A 2×2-vertex (1×1-tile) MLIQ: header, 4 verts (8 B each, height at +4), 1 tile byte.
         let mut mliq = Vec::new();
         mliq.extend(2u32.to_le_bytes()); // xverts
         mliq.extend(2u32.to_le_bytes()); // yverts
@@ -498,10 +442,10 @@ mod tests {
         mliq.extend([10.0f32, 20.0, -5.0].map(f32::to_le_bytes).concat()); // base xyz
         mliq.extend(115u16.to_le_bytes()); // materialId
         for h in [-5.0f32, -5.0, -5.0, -5.0] {
-            mliq.extend([0u8, 0, 0, 0]); // flow bytes
+            mliq.extend([0u8, 0, 0, 0]); // leading bytes, opacity first
             mliq.extend(h.to_le_bytes()); // height
         }
-        mliq.push(0x44); // tile flag: nibble 4 (lake_a), fishable (0x40) — a wet tile
+        mliq.push(0x44); // tile flag: type 4 (lake_a), fishable (0x40)
 
         let mut mogp = vec![0u8; 68];
         mogp[8..12].copy_from_slice(&0x2000u32.to_le_bytes()); // flags
@@ -523,7 +467,7 @@ mod tests {
 
     #[test]
     fn truncated_mliq_yields_no_liquid_not_a_panic() {
-        // A header that declares a grid larger than the payload → None (the group still parses).
+        // A header declaring a grid larger than the payload: no liquid, and the group still parses.
         let mut mliq = Vec::new();
         mliq.extend(9u32.to_le_bytes()); // xverts
         mliq.extend(9u32.to_le_bytes()); // yverts
@@ -531,7 +475,7 @@ mod tests {
         mliq.extend(8u32.to_le_bytes()); // ytiles
         mliq.extend([0.0f32, 0.0, 0.0].map(f32::to_le_bytes).concat());
         mliq.extend(0u16.to_le_bytes());
-        // …but no vertex/tile bytes follow.
+        // and no vertex or tile bytes follow.
         let mut mogp = vec![0u8; 68];
         mogp.extend(chunk(b"QILM", &mliq));
         let b = chunk(b"PGOM", &mogp);
@@ -543,7 +487,7 @@ mod tests {
 
     #[test]
     fn truncated_mohd_is_an_error_not_a_panic() {
-        // MOHD payload of 3 bytes: the pre-0064 reader panicked on rd_u32(p, 4).
+        // A 3-byte MOHD payload cannot hold nGroups at 4.
         let b = chunk(b"DHOM", &[0u8; 3]);
         assert!(matches!(parse(&b), Err(Error::Truncated("MOHD"))));
     }
@@ -552,11 +496,11 @@ mod tests {
     fn hostile_shapes_do_not_panic() {
         assert!(matches!(parse(&[]), Err(Error::NotWmo)));
         assert!(matches!(parse(&[0u8; 7]), Err(Error::NotWmo)));
-        // Over-declared chunk size clamps (lenient) — parses to an empty-ish root.
+        // An over-declared chunk size clamps, leniently.
         let mut b = chunk(b"DHOM", &[0u8; 64]);
         b[4..8].copy_from_slice(&u32::MAX.to_le_bytes());
         assert!(matches!(parse(&b), Err(Error::Truncated("MOHD")) | Ok(_)));
-        // A short MOGP (below the 68-byte header) is an empty group, kept from the old reader.
+        // A MOGP shorter than its 68-byte header is an empty group.
         let b = chunk(b"PGOM", &[0u8; 10]);
         let Ok(ParsedWmo::Group(g)) = parse(&b) else {
             panic!("short MOGP should parse to an empty group");
diff --git a/crates/benilla-world/Cargo.toml b/crates/benilla-world/Cargo.toml
index eadf82f7..2c5bec0c 100644
--- a/crates/benilla-world/Cargo.toml
+++ b/crates/benilla-world/Cargo.toml
@@ -3,49 +3,37 @@ name = "benilla-world"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "The world renderer: terrain, water, sky, weather, models, lighting, collision and the frame ladder — everything needed to put something in a world and ask the world about itself, with no game attached (decision 1160)"
+description = "The world renderer: terrain, water, sky, weather, models, lighting, collision and the frame ladder; everything needed to put something in a world and ask the world about itself, with no game attached"
 
 [lints]
 workspace = true
 
 [features]
-# Forwarded dev/player seam (0026 · 1173/1174 · 1175). Default-on. `benilla-formats` must be taken
-# with `default-features = false` and its `dev` re-exported here: it is default-on there too, so
-# without this a `--no-default-features` player build gets the feature back through unification and
-# the binary carries the build machine's source-tree path after all.
+# The dev/player seam, on by default. `benilla-assets` and `-formats` come in without default
+# features and their `dev` is forwarded here, or unification would put it back in a player build.
 default = ["dev"]
-#
-# `bevy/debug` rides with it (decision 1451): without it every ECS diagnostic — a panicking system,
-# a parameter that will not validate, the enforcer's whole fault list — reads `<Enable the debug
-# feature to see the name>`, which is what the frame-one crash it fixes was reported as. It stores
-# `&'static str` names on systems and params; it is diagnostics, not an instrument, so nothing
-# depends on it and the player build simply says less. Enabled here rather than in `benilla-app`
-# so `benilla-worldview` — the enforcer, whose entire output is these names — carries it too.
+# `bevy/debug` names systems and parameters in ECS diagnostics (else "Enable the debug feature to
+# see the name"); set here so `benilla-worldview`, which reports those names, gets it too.
 dev = ["benilla-formats/dev", "benilla-assets/dev", "bevy/debug"]
 
 [dependencies]
 avian3d = "0.6"
 benilla-assets = { path = "../benilla-assets", default-features = false }
 benilla-formats = { path = "../benilla-formats", default-features = false }
-# The wire crate (`benilla_protocol`) is deliberately NOT here. The engine renders a world; it
-# does not speak a protocol. Decision 1177 took the last crossing out — `WorldUnit.kind:
-# EntityKind` became `WorldUnit.wades: bool` — and the absence of that dependency line IS the
-# record's gate: the crate graph enforces it, so no test has to.
-# The WMO group parser — the portal audit re-parses a group to pin its own decode against the file.
+# No `benilla-protocol`: the engine renders a world and does not speak the protocol.
+# For the portal audit, which re-parses a WMO group to check its decode against the file.
 benilla-wmo = { path = "../benilla-wmo" }
 bevy.workspace = true
 bytemuck = { version = "1", features = ["derive"] }
 image = { version = "0.25", default-features = false, features = ["png"] }
-libc = "0.2"
 
-# macOS: `bgwin` demotes the app to Accessory for a background run and orders the window out of
-# the way. Same pins as `benilla-app`'s — one objc2 in the graph.
+# macOS AppKit calls, at `benilla-app`'s pins so the graph has one objc2.
 [target.'cfg(target_os = "macos")'.dependencies]
 objc2-app-kit = { version = "0.2", features = [
     # `bgwin`'s Accessory demotion and window ordering, and `modkeys`' modifier read.
     "NSApplication",
     "NSEvent",
-    # `mac_quit` walks the default menu bar to re-point the Quit item (decision 1528).
+    # `mac_quit` walks the default menu bar to re-point the Quit item.
     "NSMenu",
     "NSMenuItem",
     "NSResponder",
@@ -54,6 +42,5 @@ objc2-app-kit = { version = "0.2", features = [
 ] }
 # `MainThreadMarker`, for the AppKit calls above.
 objc2-foundation = "0.2"
-# `sel!`, for the two selectors `mac_quit` swaps. The pin objc2-app-kit 0.2 itself builds against,
-# so this adds a name to the manifest and nothing to the graph.
+# `sel!`, for the two selectors `mac_quit` swaps; the objc2 that objc2-app-kit 0.2 builds against.
 objc2 = "0.5"
diff --git a/crates/benilla-world/src/art_scope.rs b/crates/benilla-world/src/art_scope.rs
index 19c8de6b..101f22f1 100644
--- a/crates/benilla-world/src/art_scope.rs
+++ b/crates/benilla-world/src/art_scope.rs
@@ -1,43 +1,9 @@
-//! **Within-map art residency** — the distance half of decision 0729's map-scope teardown.
+//! Within-map art residency: the world-art dedup caches drop what was last wanted more than a
+//! radius from the view focus; a cross-map transition still clears them outright.
 //!
-//! 0729 gave the world-art dedup caches a *reset point*: a cross-map transition clears them, and the
-//! loading screen pays for the rebuild. B131 is the case that argument does not reach — a long flight
-//! **inside** one map never fires that transition, so nothing ever evicts and `mats`/`images` ratchet
-//! for as long as you stay on a continent (decision 0785's open half: 26.8 k materials / 2.8 k images
-//! after ten minutes here; 3.2 → 4.9 GiB of VRAM on the reporter's tour).
-//!
-//! This module turns clear-on-*transition* into clear-on-*distance*: every cache entry remembers the
-//! view focus it was last used from, and a sweep drops what was last wanted more than
-//! [`DEFAULT_RADIUS_YD`] away. So residency is bounded by *where you are*, not by how long the process
-//! has run, and the map-change clear stays exactly as it was — the hard reset on top of the soft one.
-//!
-//! **Distance decides what expires; a dwell floor decides how soon.** [`MIN_DWELL_SECS`] exists
-//! because the radius alone is sized for gameplay speed — the detached free-fly camera crosses it in
-//! five seconds and would lose a city's dedup only to rebuild it on the way back (found on the
-//! director's first real run; see the constant).
-//!
-//! **Distance, not a TTL**, and the difference is safety rather than taste: a time-expired entry can
-//! be one the streamer is about to ask for again from ten yards away, and dropping it costs a
-//! duplicate; a distance-expired entry is one whose tiles unloaded long ago. The radius is therefore
-//! floored at the streamer's own reach ([`radius_floor`]) so eviction can never outrun the thing that
-//! placed the art.
-//!
-//! **Two properties worth knowing before reading the code**, both of which buy the design its
-//! smallness:
-//!
-//! 1. **Stamping needs no plumbing.** A *use* (a [`SpatialCache::fetch`] hit or an insert) clears the
-//!    stamp to `None` — "used since the last sweep" — and the *sweep* is what writes today's focus
-//!    onto every `None`. So no call site has to know where the camera is, and a cache nothing sweeps
-//!    (the `Local<MaterialCache>`s in the glue booth and the portrait bake) simply never expires.
-//! 2. **Nothing needs ordering.** The stamp is at worst one sweep interval stale (≈25 yd at flight
-//!    speed, against a 2.6 km radius) and `due` being read a frame before it is set only moves the
-//!    sweep one frame. There are no `.before`/`.after` constraints anywhere in this module.
-//!
-//! The failure mode if the radius were ever too small: evicting the dedup for art that is still
-//! drawn. That is not a visual bug and not a leak — the drawn entity holds its own handles, and the
-//! next spawn of that art re-creates one duplicate material which becomes the new cache entry. It
-//! costs a lost batch, and it self-heals. That asymmetry (too-eager = mild and transient, too-lazy =
-//! the bug we are fixing) is why the floor is a clamp and not a warning.
+//! A use (a [`SpatialCache::fetch`] hit or an insert) clears an entry's stamp to `None` and each
+//! sweep stamps every `None` with the current focus, so no call site needs the camera and a cache
+//! nothing sweeps never expires. Eviction only drops the dedup: a drawn entity keeps its handles.
 
 use std::hash::Hash;
 
@@ -48,36 +14,20 @@ use bevy::time::Real;
 use benilla_assets::SpatialCache;
 use benilla_formats::TILE_SIZE;
 
-/// Wall seconds between sweeps ([`Real`], not the virtual clock — this is a housekeeping cadence,
-/// and decision 0789's reading applies: "what time is it" is not "how much world time to advance").
-/// One `retain` over ~30 k entries a second is not measurable; the interval exists so it is not run
-/// per frame, and it doubles as the stamp's resolution.
+/// Real-clock seconds between sweeps (housekeeping, not world time); also the stamp's resolution.
 const SWEEP_SECS: f32 = 1.0;
 
-/// Default eviction radius in yards — five ADT tiles (2667 yd). Chosen as the smallest round
-/// multiple of the tile grid comfortably clear of [`radius_floor`] (2560 yd): far enough that art
-/// still on screen is never evicted, close enough that leaving one city for another recovers it
-/// (Stormwind → Booty Bay is ~5500 yd, Ironforge → Stormwind ~4250).
+/// Five ADT tiles (2667 yd), the smallest round tile multiple clear of [`radius_floor`].
 const DEFAULT_RADIUS_YD: f32 = 5.0 * TILE_SIZE;
 
-/// The smallest radius that cannot evict art the streamer is still holding: the far **corner** of
-/// the widest tile block the residency window can keep, plus a tile of margin.
-///
-/// A stamp records where *the viewer* was when the art was last wanted, not where the art is — so an
-/// entry can be up to a streaming reach "behind" the art it belongs to. Flooring the radius at the
-/// block's circumscribed radius means you have to leave the art's neighbourhood entirely before its
-/// dedup expires. The window follows the live `farclip` (1513), so the floor is taken at the clamp's
-/// **max** — the widest the window can ever be — rather than tracking the slider: a floor that
-/// shrank with the view distance would buy nothing (the default clears it either way) and would
-/// have to re-resolve on every drag.
+/// The far corner of the widest tile block the residency window keeps (at the `farclip` clamp's
+/// maximum), plus a tile: a stamp is where the viewer stood, so no smaller radius is safe.
 fn radius_floor() -> f32 {
     crate::terrain_stream::window::max_resident_reach_yd(*crate::view::FARCLIP_RANGE.end())
 }
 
-/// Resolve `$WOW_ART_RADIUS` (yards; `0` or negative ⇒ eviction off, the A/B leg that reproduces the
-/// unbounded behaviour on a fixed build) against the streamer's reach. An explicitly-requested radius
-/// below [`radius_floor`] is raised **and** warned about, rather than silently obeyed: a knob that
-/// quietly means something else than it says is how decision 0789 happened.
+/// `$WOW_ART_RADIUS` in yards (`0` or less turns eviction off); a value under [`radius_floor`] is
+/// raised to it with a warning.
 fn radius_from_env() -> f32 {
     let floor = radius_floor();
     match std::env::var("WOW_ART_RADIUS")
@@ -97,27 +47,25 @@ fn radius_from_env() -> f32 {
     }
 }
 
-/// Which cache a census row is about. Fixed set, in journal-column order — the CSV's columns only
-/// ever grow at the end, so this enum's order is part of the file format.
+/// Which cache a census row is about, in journal-column order: the CSV only grows columns at the
+/// end, so this order is part of the file format.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum ArtSlot {
-    /// `Placements::materials` — streamed doodad/WMO submesh materials.
+    /// `Placements::materials`: streamed doodad and WMO submesh materials.
     PlaceMats,
-    /// `ModelMaterials` — every authored-batch material: creatures, players, GameObjects, the
-    /// character composites, the booth scenes.
+    /// `ModelMaterials`: every authored-batch material, units, GameObjects and booth scenes alike.
     ModelMats,
-    /// `SkinComposites` — composited character body atlases (decision 0044).
+    /// `SkinComposites`: composited character body atlases.
     Skins,
-    /// `WorldAssets::model_materials` — the ground-clutter material dedup.
+    /// `WorldAssets::model_materials`: the ground-clutter material dedup.
     ClutterMats,
-    /// `WorldAssets::textures` — decoded world BLPs by (path, wrap).
+    /// `WorldAssets::textures`: decoded world BLPs by (path, wrap).
     Textures,
-    /// `ClutterGeometry` — CPU submesh copies of every detail M2 decoded.
+    /// `ClutterGeometry`: CPU submesh copies of every decoded detail M2.
     ClutterGeo,
 }
 
 impl ArtSlot {
-    /// Every slot, in journal-column order.
     pub const ALL: [ArtSlot; 6] = [
         ArtSlot::PlaceMats,
         ArtSlot::ModelMats,
@@ -127,7 +75,6 @@ impl ArtSlot {
         ArtSlot::ClutterGeo,
     ];
 
-    /// The journal's column name for this slot.
     pub(crate) fn column(self) -> &'static str {
         match self {
             ArtSlot::PlaceMats => "pmat",
@@ -151,9 +98,8 @@ impl ArtSlot {
     }
 }
 
-/// Per-cache residency, refreshed by every [`ArtScope::apply`] call — the instrument that localizes
-/// a residency ratchet to **one cache** in a single journal row, instead of the run-length probe that
-/// found B131. `Assets<T>::len()` says "materials are growing"; this says which map is holding them.
+/// Per-cache live and dropped counts, refreshed by every [`ArtScope::apply`], so one journal row
+/// shows which cache is growing.
 #[derive(Resource, Default)]
 pub struct ArtCensus {
     live: [usize; ArtSlot::ALL.len()],
@@ -161,7 +107,7 @@ pub struct ArtCensus {
 }
 
 impl ArtCensus {
-    /// Live entries in one cache as of its last sweep.
+    /// Live entries in one cache as of its last [`ArtScope::apply`].
     pub fn live(&self, slot: ArtSlot) -> usize {
         self.live[slot.idx()]
     }
@@ -175,25 +121,20 @@ impl ArtCensus {
 /// The sweep's shared state: the radius, this tick's focus, and whether this frame is a sweep frame.
 #[derive(Resource, Default)]
 pub struct ArtScopeState {
-    /// Eviction radius in yards; `0` ⇒ never evict. Zero until [`configure_art_scope`] runs, so
-    /// nothing can be dropped before the streamer's reach is known.
+    /// Eviction radius in yards, `0` for none; zero until [`configure_art_scope`] runs.
     radius: f32,
-    /// The view focus, wow coords (`crate::terrain_stream::view_focus` — the same ladder the
-    /// streamer and the WDL ring use). `None` when there is no focus at all (no avatar, no camera),
-    /// which suspends both stamping and sweeping.
+    /// The view focus in WoW coords; `None` (no avatar, no camera) suspends stamping and sweeping.
     focus: Option<[f32; 3]>,
     /// Set on the one frame per [`SWEEP_SECS`] that sweeps.
     due: bool,
     last_sweep: f32,
-    /// Wall seconds since app start, this frame — the clock the dwell floor is measured on.
+    /// Real seconds since app start this frame; the cache's dwell floor is measured on it.
     now: f32,
 }
 
 impl ArtScopeState {
-    /// The view focus this frame, wow coords — what the sweep measures from. Exposed for the FPS
-    /// journal: its `x,y,z` are the *avatar*, which stands still through a whole detached free-fly, so
-    /// on that leg the position columns say nothing about where the art was being asked for. This is
-    /// the column that does.
+    /// This frame's view focus in WoW coords, which the sweep measures from. The FPS journal logs
+    /// it because its avatar columns stand still through a detached free-fly.
     pub fn focus(&self) -> Option<[f32; 3]> {
         self.focus
     }
@@ -207,8 +148,7 @@ pub struct ArtScope<'w> {
 }
 
 impl ArtScope<'_> {
-    /// Sweep one cache (on sweep frames) and record its residency. Safe to call for a cache that is
-    /// empty, unconfigured, or in a run with eviction switched off — it degrades to a census read.
+    /// Sweeps one cache on sweep frames and records its residency.
     pub fn apply<K: Eq + Hash, V>(&mut self, cache: &mut SpatialCache<K, V>, slot: ArtSlot) {
         let dropped = match self.state.focus {
             Some(focus) if self.state.due && self.state.radius > 0.0 => {
@@ -230,7 +170,6 @@ impl ArtScope<'_> {
     }
 }
 
-/// Resolve the radius once at startup (the floor is a constant of the view-distance clamp).
 fn configure_art_scope(mut state: ResMut<ArtScopeState>) {
     state.radius = radius_from_env();
     if state.radius > 0.0 {
@@ -243,8 +182,8 @@ fn configure_art_scope(mut state: ResMut<ArtScopeState>) {
     }
 }
 
-/// Publish this frame's focus and decide whether it is a sweep frame. Deliberately unordered against
-/// every consumer — see the module docs.
+/// Publish this frame's focus and whether it sweeps. Unordered against every consumer: a stamp is
+/// at most one sweep stale, and reading `due` a frame early only moves the sweep a frame.
 fn track_art_scope(
     mut state: ResMut<ArtScopeState>,
     time: Res<Time<Real>>,
@@ -261,8 +200,7 @@ fn track_art_scope(
     }
 }
 
-/// Owns the sweep policy + the census. The caches themselves stay private to their modules; each
-/// registers its own three-line system that hands its caches to [`ArtScope::apply`].
+/// Owns the sweep policy and the census; each cache's owner calls [`ArtScope::apply`].
 pub(crate) struct ArtScopePlugin;
 
 impl Plugin for ArtScopePlugin {
@@ -278,12 +216,6 @@ impl Plugin for ArtScopePlugin {
 mod tests {
     use super::*;
 
-    // The cache's own behaviour (stamping, the dwell floor, altitude, handle drop) is tested where
-    // the cache now lives — `benilla_assets::spatial_cache`. What is left here is the half that
-    // stayed: how wide the sweep reaches, and that an unconfigured run still bounds itself.
-
-    /// Eviction must never outrun the streamer: the default radius clears the far corner of the
-    /// widest block the window keeps at the clamp's max view distance.
     #[test]
     fn the_radius_clears_the_streamers_own_reach() {
         assert!(
@@ -291,12 +223,11 @@ mod tests {
             "default {DEFAULT_RADIUS_YD} must clear the floor {}",
             radius_floor()
         );
-        // (26 + 1 + 16) chunks per axis at 777, the corner of that, plus a tile: ~2560 yd.
+        // (26 + 1 + 16) chunks each way at farclip 777, to the corner, plus a tile: ~2560 yd.
         assert!((radius_floor() - 2560.0).abs() < 1.0, "{}", radius_floor());
     }
 
-    /// With `$WOW_ART_RADIUS` unset (every ordinary run, and the test binary) the radius is the
-    /// default, floored — never zero, so a shipped build always bounds itself.
+    /// `$WOW_ART_RADIUS` is unset in the test binary, as in every ordinary run.
     #[test]
     fn an_unconfigured_run_still_bounds_itself() {
         assert_eq!(radius_from_env(), DEFAULT_RADIUS_YD.max(radius_floor()));
diff --git a/crates/benilla-world/src/assets/mod.rs b/crates/benilla-world/src/assets/mod.rs
index 7be9de02..f7bff6d5 100644
--- a/crates/benilla-world/src/assets/mod.rs
+++ b/crates/benilla-world/src/assets/mod.rs
@@ -1,10 +1,5 @@
-//! The asset foundation's **plugin shell** — the three systems that drive
-//! [`benilla_assets::WorldAssets`] from inside the client.
-//!
-//! The store itself went down to `benilla-assets` (decision 1164); what could not follow it is
-//! exactly this: opening the chain needs the shared light buffer (`lighting`), evicting the world
-//! art needs the cross-map message (`world_map`), and the residency sweep needs the art-scope
-//! instrument. Three upward reaches, all of them here, none of them in the data core.
+//! Drives [`benilla_assets::WorldAssets`] from the client: each system needs a client piece (the
+//! light buffer, `MapChange`, the art scope), so it lives here rather than in `benilla-assets`.
 
 use bevy::prelude::*;
 use bevy::render::renderer::RenderDevice;
@@ -13,8 +8,7 @@ use crate::art_scope::{ArtScope, ArtSlot};
 use benilla_assets::{AssetSet, RenderConfig, WorldAssets};
 use benilla_formats::open_chain;
 
-/// The asset foundation plugin: opens the **one** patch chain at startup and inserts the shared
-/// [`WorldAssets`] + [`RenderConfig`] that the other subsystems build on.
+/// Opens the patch chain at startup and inserts the shared [`WorldAssets`] and [`RenderConfig`].
 pub(crate) struct AssetPlugin;
 
 impl Plugin for AssetPlugin {
@@ -28,11 +22,8 @@ impl Plugin for AssetPlugin {
     }
 }
 
-/// Drop the world-art dedup on a cross-map transition (`world_map::MapChange` — see its doc for
-/// why a clear is always safe): `textures` + `model_materials` pin every map's world art forever
-/// otherwise (the #bugs teleport leak). The UI sprite caches (`sprites`/`tiled_sprites`/
-/// `portraits`/`masks`) stay — they are game-global UI scope, and their negative entries exist
-/// precisely to stop per-frame re-walks of the chain.
+/// Clears `textures` and `model_materials` on a map change, or they pin every map's art forever.
+/// The UI sprite caches stay: they are global, and their negative entries stop per-frame re-walks.
 fn evict_world_art(
     mut changes: MessageReader<crate::world_map::MapChange>,
     assets: Option<ResMut<WorldAssets>>,
@@ -47,11 +38,8 @@ fn evict_world_art(
     }
 }
 
-/// Expire the world-art dedup by **distance** (decision 0793) — the within-map half of the eviction
-/// above. `textures` is the one that matters for VRAM: a decoded BLP is pinned by the material that
-/// samples it, and a material by this cache, so nothing here dropping is why `images` never fell on a
-/// same-map traverse. The UI sprite caches stay unswept for the same reason they survive a map change
-/// (game-global scope, and their negative entries exist to stop per-frame chain re-walks).
+/// Expires the world-art caches by distance within a map: a cached material pins the decoded BLP it
+/// samples, so `textures` is what frees VRAM. The UI sprite caches stay, as on a map change.
 fn scope_world_art(mut scope: ArtScope, assets: Option<ResMut<WorldAssets>>) {
     if let Some(mut a) = assets {
         scope.apply(&mut a.model_materials, ArtSlot::ClutterMats);
@@ -97,24 +85,12 @@ fn open_world_assets(
         );
         return;
     };
-    // How much terrain is resident is NOT a knob here: the streamer derives its window from the
-    // live `farclip` (`view::ViewDistance`, the player's Terrain Distance setting) the way the
-    // reference does — `terrain_stream::window`, decision 1513. `$WOW_TILE_RADIUS` is retired.
-    // Ground-texture repeats per chunk; tunable live in the panel afterward.
-    let tex_tiles = std::env::var("WOW_TEX_TILES")
-        .ok()
-        .and_then(|s| s.parse::<f32>().ok())
-        .unwrap_or(8.0);
-    // See the field doc: the tile-unload budget (B181). Default 1 — even the fastest focus
-    // (boosted free-fly, ~1 stale row/s) produces stale tiles far slower than 60/s drains them.
+    // Stale tiles released per frame: 1 outpaces even boosted free-fly's stale row a second.
     let unload_budget = std::env::var("WOW_TILE_UNLOAD")
         .ok()
         .and_then(|s| s.parse().ok())
         .unwrap_or(1);
-    commands.insert_resource(RenderConfig {
-        tex_tiles,
-        unload_budget,
-    });
+    commands.insert_resource(RenderConfig { unload_budget });
 
     match open_chain(&data) {
         Ok(chain) => commands.insert_resource(WorldAssets::open(chain, light_buf, torch)),
diff --git a/crates/benilla-world/src/bgwin.rs b/crates/benilla-world/src/bgwin.rs
index 572c1e2b..809dd892 100644
--- a/crates/benilla-world/src/bgwin.rs
+++ b/crates/benilla-world/src/bgwin.rs
@@ -1,49 +1,15 @@
-//! Background instrumented runs: probe/capture/regression windows that open *behind* the
-//! director's work — and stay reachable once they're there.
+//! Background instrumented runs: a probe or capture window opens behind the user's work without
+//! taking focus, then becomes an ordinary window.
 //!
-//! Agent-driven runs (captures, live probes, the rig, FPS journals) open a real window for
-//! seconds to minutes on the same desktop the director is working on. Left alone, each launch
-//! stole their focus twice over:
-//!
-//! - **Window-side** — the primary window opened focused (`makeKeyAndOrderFront`), swallowing
-//!   whatever they were typing (on 2026-07-19 a login-shot run typed their keystrokes into the
-//!   account box). `Window::focused = false` fixed that for capture/login-shot runs only; every
-//!   live probe still opened key.
-//! - **App-side (macOS)** — winit's AppKit backend unconditionally calls
-//!   `activateIgnoringOtherApps` at `applicationDidFinishLaunching` and sets the Regular
-//!   activation policy, so even an unfocused run activated the app: the menu bar switched and
-//!   the window ordered in **front** of every other app's. bevy_winit 0.18 exposes no
-//!   `EventLoopBuilderExtMacOS` hook to turn either off, so it can't be prevented — only undone,
-//!   immediately after launch (decision 0703).
-//!
-//! Stealing the screen is a **launch-time event**, and only an event's worth of correction is
-//! owed. 0703 paid for it with two *permanent* states, and the bill came due: with
-//! `WindowLevel::AlwaysOnBottom` (`kCGNormalWindowLevel - 1`) the window could never be raised
-//! above a normal one however hard you clicked it, and the Accessory activation policy struck it
-//! from Cmd-Tab and the Dock. Every instrumented window was unreachable for its whole life, not
-//! just polite at birth. Decision 0709 keeps both mechanisms — they are the right ones, and
-//! Accessory in particular is doing more work than it looks (see [`macos::hand_back_activation`])
-//! — but scopes them to the launch instead of the run:
-//!
-//! [`background_run`] detects an instrumented run from the env that drives it (no recipe or
-//! script changes anywhere). `main` opens the window unfocused and below the normal level, so it
-//! cannot flash over the director's work on the way up. [`BgWinPlugin`] then holds the launch:
-//! Accessory policy, activation handed straight back to whatever they were using, and our window
-//! ordered to the **back of the stack** — on screen, so surface rendering, readback and
-//! screenshots are untouched, but behind their work. Once the launch goes quiet (half a second
-//! with no activation landing on us; hard-capped at three seconds) it lets go in sequence —
-//! window level back to Normal, policy back to Regular, one last order-to-back — and latches
-//! shut. What's left is an ordinary window that Cmd-Tabs, clicks and raises like any other, for
-//! as long as the run lasts.
+//! winit's AppKit backend activates the app at launch and bevy_winit 0.18 has no hook to stop it,
+//! so `main` opens the window unfocused below the normal level and [`BgWinPlugin`] undoes the
+//! launch, then restores the Normal level and Regular policy: left on, `AlwaysOnBottom` keeps the
+//! window under every other and Accessory hides it from Cmd-Tab and the Dock.
 
 use bevy::prelude::*;
 
-/// Env prefixes that mark a run as agent-driven — the capture harness, shots/smokes, and the
-/// live-probe fleet. Deliberately only *run-driving* switches: a plain modifier the director
-/// might set on an attended run (`WOW_GM`, `WOW_FARCLIP`, traces…) must NOT push their own
-/// window to the bottom of the stack. A new probe env usually starts with `WOW_PROBE`/
-/// `WOW_CAPTURE` and is covered for free; one that doesn't shows up as "the new probe window
-/// opened focused" and gets its prefix added here.
+/// Env prefixes that mark an instrumented run: only run-driving switches, never a modifier someone
+/// sets on an attended run (`WOW_GM`, `WOW_FARCLIP`). A probe env none covers opens focused.
 const BG_ENV_PREFIXES: &[&str] = &[
     "WOW_AUDIT_",
     "WOW_CAPTURE",
@@ -69,20 +35,13 @@ const BG_ENV_PREFIXES: &[&str] = &[
     "WOW_PROBE",
     "WOW_RIG",
     "WOW_SCHED_CENSUS",
-    // The one that names the condition directly: `WOW_UNATTENDED` *is* "the chair is empty"
-    // (1769), and method.md tells every ad-hoc probe to set it. It was missing here for as long
-    // as this list has existed, so a probe launched exactly the way the method prescribes — but
-    // under none of the named prefixes — opened focused and borderless-fullscreen over the
-    // director's work. Reported 2026-09-01 while probing B346. This is the case the list's own
-    // doc predicts ("one that doesn't shows up as the new probe window opened focused"); it is
-    // also the strongest signal available, since nothing else asserts nobody is there.
+    // Set by every unattended run (docs/METHOD.md): the one env that says nobody is at the desk.
     "WOW_UNATTENDED",
     "WOW_WORLDVIEW_",
 ];
 
-/// Is this an instrumented background run? `WOW_BG=1` forces yes on any run, `WOW_BG=0` forces
-/// no (the escape hatch when the director wants to *watch* a probe live); otherwise, auto-detect
-/// from the run-driving env ([`BG_ENV_PREFIXES`]).
+/// Whether this is an instrumented background run: `WOW_BG=0` forces no (to watch a probe live),
+/// any other `WOW_BG` forces yes, and otherwise any [`BG_ENV_PREFIXES`] env counts.
 pub fn background_run() -> bool {
     match std::env::var("WOW_BG").as_deref() {
         Ok("0") => return false,
@@ -95,23 +54,12 @@ pub fn background_run() -> bool {
     })
 }
 
-/// Background-run envs whose run produces **no image** — nothing reads the framebuffer, so the
-/// window is pure plumbing. Prefix-matched, and the rule in [`no_pixel_run`] is **all-of**: a run
-/// counts as no-pixel only when *every* background env it sets is in this list, so a
-/// `WOW_PROBE_CHAT=… WOW_LIVE_SHOT=…` pairing (drive there, then shoot) keeps its full-size window.
-///
-/// Erring here is cheap in one direction only: a missing entry just means a big window, which is
-/// the old behaviour. A *wrong* entry shrinks a window someone is photographing — so a new
-/// `WOW_PROBE…`-named env that captures pixels has to be excluded by name here, since the bare
-/// `WOW_PROBE` prefix would otherwise sweep it in.
+/// Background envs whose run reads no pixels, so its window may be small; [`no_pixel_run`] needs
+/// every background env a run sets to be here. A wrong entry shrinks a window being photographed,
+/// and the bare `WOW_PROBE` prefix also matches any new `WOW_PROBE…` env that reads pixels.
 const NO_PIXEL_ENV_PREFIXES: &[&str] = &[
-    // Paired with its entry above, and it has to be BOTH or neither: `leg.sh`, `cine.sh` and
-    // `summon-live.sh` all set `WOW_UNATTENDED` beside a `WOW_PROBE*`/`WOW_RIG` that IS no-pixel,
-    // so listing it only as a background env would make it the one non-no-pixel member of every
-    // such run and the all-of rule would grow all three back to the full 1600x900 that decision
-    // 1148 shrank. A run whose ONLY background env is this one reads no pixels by construction —
-    // anything that photographs the frame names itself (`WOW_CAPTURE`, `WOW_LIVE_SHOT`,
-    // `WOW_*_SHOT`), and none of those are here, so every such pairing keeps its full size.
+    // In both lists: unattended runs pair it with a no-pixel `WOW_PROBE*` or `WOW_RIG`, which the
+    // all-of rule would otherwise grow back to full size. A run that photographs names itself.
     "WOW_UNATTENDED",
     "WOW_FEED_GATE_CHECK",
     "WOW_FEED_GATE_TRACE",
@@ -121,27 +69,13 @@ const NO_PIXEL_ENV_PREFIXES: &[&str] = &[
     "WOW_PROBE",
     "WOW_RIG",
     "WOW_SCHED_CENSUS",
-    // The engine boot check reads no pixels — it reads the ERROR LOG. Its sibling
-    // `WOW_WORLDVIEW_SHOT` is deliberately absent: that one photographs the frame, and the
-    // all-of rule below keeps a CHECK+SHOT pairing at full size.
+    // The engine boot check reads its log; `WOW_WORLDVIEW_SHOT` photographs and stays off.
     "WOW_WORLDVIEW_CHECK",
 ];
 
-/// Does this run read no pixels — i.e. may its window be small and parked out of the way?
-///
-/// The point is the director's screen. A probe window is asserted `AlwaysOnTop` for its whole life
-/// ([`crate::capture::ProbeFocusPlugin`], decision 0906 — an occluded macOS window throttles to
-/// ~1 fps and a wall-clock probe schedule then fires the wrong steps), which silently defeats
-/// everything this module does to keep instrumented runs behind the director's work: the level is
-/// re-asserted every frame, over the `AlwaysOnBottom` birth cage AND over the `Normal` this module
-/// hands back at release. That assertion is correct and stays. What was wrong is pairing it with
-/// the **full 1600×900 default**, so every agent probe planted a screen-filling window over
-/// whatever they were doing — six of them in one session, which is how it got reported
-/// (decision 1148). Un-occludable and unobtrusive were never in conflict: a small window in a
-/// corner is both.
-///
-/// `WOW_BG=1` (forced background, no run-driving env) is deliberately NOT no-pixel — that is the
-/// hand-driven case, and shrinking a window the director asked for is the opposite of the point.
+/// Whether this run reads no pixels, so its window may be small and parked. The app pins a probe
+/// window `AlwaysOnTop` (an occluded macOS window throttles to about 1 fps), overriding this
+/// module's ordering. `WOW_BG=1` with no run-driving env is not a no-pixel run.
 pub fn no_pixel_run() -> bool {
     if !background_run() {
         return false;
@@ -160,9 +94,7 @@ pub fn no_pixel_run() -> bool {
     saw_one
 }
 
-/// On a [`background_run`], undo winit's launch-time app activation and window ordering (macOS;
-/// no-op elsewhere) for the length of the launch window, then get out of the way. The
-/// `focused: false` half lives where the window is built, in `main`.
+/// On a [`background_run`], undoes winit's launch-time activation and raise (macOS only).
 pub struct BgWinPlugin;
 
 impl Plugin for BgWinPlugin {
@@ -192,48 +124,34 @@ mod macos {
     use objc2_app_kit::{NSApplication, NSApplicationActivationPolicy};
     use objc2_foundation::MainThreadMarker;
 
-    /// How quiet the launch has to go before [`hold_background`] calls it settled and lets go:
-    /// this long with the app continuously inactive. winit's `activateIgnoringOtherApps` is a
-    /// WindowServer round-trip that can be *granted* well after `PreStartup`'s
-    /// [`hand_back_activation`] already ran — and a granted activation re-raises our window — so
-    /// the hold can't be a fixed count; every activation it sees restarts the clock.
+    /// How long the app must stay inactive before [`hold_background`] lets go; winit's activation
+    /// is a WindowServer round-trip that can land late, so each one seen restarts this clock.
     const SETTLE: Duration = Duration::from_millis(500);
 
-    /// Hard ceiling on the hold, however unsettled things look. Past this the window is the
-    /// director's, and an unrecognised activation source is a bug to find, not to fight forever.
+    /// Hard ceiling on the hold, however unsettled the launch looks.
     const CEILING: Duration = Duration::from_secs(3);
 
-    /// How long to keep watching after the promotion to Regular. Raising the activation policy
-    /// is the one step that could itself pull the app forward, so the release is not trusted
-    /// blind — it is checked for a moment, then latched shut.
+    /// How long to watch after the promotion to Regular, which can itself activate the app.
     const TAIL: Duration = Duration::from_millis(300);
 
-    /// Where the launch correction has got to. The whole plugin is this one-way sequence.
+    /// Where the launch correction has got to, a one-way sequence.
     #[derive(Default)]
     pub(super) enum Phase {
         /// Undoing winit's activation and raise until the launch goes quiet.
         #[default]
         Holding,
-        /// Quiet reached: the window level has been retargeted at Normal and bevy applies the
-        /// `setLevel` this frame — which re-orders us to the front of the level we just joined.
+        /// Quiet: the level is retargeted at Normal, and bevy's `setLevel` this frame puts the
+        /// window at the front of that level.
         Promoting,
-        /// Regular policy restored (Dock icon, Cmd-Tab entry). Watching for a moment in case that
-        /// promotion pulled the app forward with it.
+        /// Regular policy restored (Dock icon, Cmd-Tab); watching in case that activated the app.
         Tail(Duration),
         /// Hands off, permanently.
         Done,
     }
 
-    /// Give activation back to the app the director was using. The `NonSendMarker` param pins
-    /// the system to the main thread (AppKit's requirement).
-    ///
-    /// Demoting to the Accessory policy for the launch is load-bearing, and not merely to hide
-    /// the Dock icon: `deactivate()` on its own does **not** hold a Regular-policy app in the
-    /// background on macOS 26 — measured, the app took frontmost within 160 ms of launch and kept
-    /// it for the whole run, which is the 2026-07-19 keystroke-stealing bug exactly. Accessory is
-    /// what actually keeps us out of the foreground. Its cost — no Cmd-Tab entry — is why it is
-    /// wrong to *leave* on (that is what stranded the window), so it is scoped to the launch and
-    /// promoted back to Regular the moment things settle (decision 0709).
+    /// Demotes the app to the Accessory policy and hands activation back, on the main thread
+    /// (`NonSendMarker`, AppKit's requirement). Accessory is what holds the app back: on macOS 26
+    /// `deactivate()` alone lets a Regular app take frontmost within 160 ms and keep it.
     pub(super) fn hand_back_activation(_main_thread: NonSendMarker) {
         let Some(mtm) = MainThreadMarker::new() else {
             return;
@@ -243,18 +161,9 @@ mod macos {
         let _ = hand_back(&app);
     }
 
-    /// The launch window: keep handing activation back and keep our window at the back of the
-    /// stack until the launch settles, then let go for good. A no-op thereafter — from that point
-    /// the window is ordinary, and raising it is between the director and the WindowServer.
-    ///
-    /// Deliberately *not* keyed on window focus, which reads like the obvious "the director
-    /// reached for it" signal and isn't: winit's `window_activation_hack`
-    /// (`app_state.rs`, `applicationDidFinishLaunching`) calls `makeKeyAndOrderFront` on every
-    /// visible window regardless of the `focused: false` we asked for, so the launch itself
-    /// delivers a focus gain on ~frame 2 — and an activation granted later delivers another, as
-    /// the key window resigns and re-takes key across the app deactivate/activate. Focus cannot
-    /// tell us apart from the WindowServer, so the hold is timed against quiet instead, and kept
-    /// short enough that it can't meaningfully fight a director who clicks during it.
+    /// Hands activation back and orders the window back until the launch settles, then lets go.
+    /// Timed against quiet, not window focus: winit's `window_activation_hack` makes every visible
+    /// window key at launch whatever `focused` says, so focus gains come from the WindowServer too.
     pub(super) fn hold_background(
         _main_thread: NonSendMarker,
         time: Res<Time<Real>>,
@@ -278,17 +187,14 @@ mod macos {
                     && now.saturating_sub(*started) < CEILING
                 {
                     if hand_back(&app) {
-                        // An activation landed (winit's, granted late). Restart the settle clock:
-                        // whatever raised us once can raise us again while the round-trip is
-                        // still in flight.
+                        // A late-granted activation landed: restart the settle clock.
                         *last_active = now;
                         debug!("bgwin: took activation back {now:?} in");
                     }
                     order_back(&app);
                     return;
                 }
-                // Quiet. Start letting go — the window level first, retargeted through the
-                // component so bevy's own cache stays honest about where the window is.
+                // Quiet: release the level through the component, so bevy's cache stays true.
                 let Ok(mut window) = windows.single_mut() else {
                     return;
                 };
@@ -296,17 +202,14 @@ mod macos {
                 *phase = Phase::Promoting;
             }
             Phase::Promoting => {
-                // bevy applied the `setLevel` at the end of last frame, which put us at the front
-                // of the normal level; drop straight back to the bottom of it before anything is
-                // presented on top of the director's work. Then hand the Dock icon and the
-                // Cmd-Tab entry back.
+                // bevy's `setLevel` last frame put us at the front of the normal level: order
+                // back before restoring the Dock icon and Cmd-Tab entry.
                 order_back(&app);
                 app.setActivationPolicy(NSApplicationActivationPolicy::Regular);
                 *phase = Phase::Tail(now);
             }
             Phase::Tail(since) => {
                 if hand_back(&app) {
-                    // The promotion pulled us forward after all — put it back.
                     debug!("bgwin: policy promotion activated the app; handed it back");
                 }
                 order_back(&app);
@@ -321,10 +224,9 @@ mod macos {
         }
     }
 
-    /// Give activation back to whoever had it before we launched. Reports whether there was any
-    /// to give back — i.e. whether an activation had landed on us since the last look.
+    /// Deactivates the app if it is active; `true` when an activation had landed on us.
     fn hand_back(app: &NSApplication) -> bool {
-        // SAFETY: main thread — every caller takes `NonSendMarker` and checks `MainThreadMarker`.
+        // SAFETY: main thread; every caller takes `NonSendMarker` and checks `MainThreadMarker`.
         unsafe {
             if !app.isActive() {
                 return false;
@@ -334,20 +236,11 @@ mod macos {
         }
     }
 
-    /// Order our windows to the back of the normal window level: on screen (surface rendering,
-    /// readback and screenshots untouched) but behind the director's work.
-    ///
-    /// Plain stacking, not a window level — that is the whole point. `AlwaysOnBottom` pins a
-    /// window below every normal one *forever*; a window ordered to the back is merely last in
-    /// line, and comes forward the instant anything raises it.
-    ///
-    /// Unconditional for the length of the hold, and deliberately not gated on "the app is
-    /// active": winit raises the window when it creates it and again in its
-    /// `window_activation_hack`, both of which can land while we are already inactive, so a gate
-    /// on activation would leave that raise standing and the window parked on top for the whole
-    /// run. Repeating it while already at the back is an idempotent no-op.
+    /// Orders our windows to the back of the normal level, still on screen, where anything can
+    /// raise them. Not gated on the app being active: winit raises the window at creation and in
+    /// its activation hack, and either can land while we are inactive.
     fn order_back(app: &NSApplication) {
-        // SAFETY: main thread — every caller takes `NonSendMarker` and checks `MainThreadMarker`.
+        // SAFETY: main thread; every caller takes `NonSendMarker` and checks `MainThreadMarker`.
         unsafe {
             for window in app.windows().iter() {
                 window.orderBack(None);
diff --git a/crates/benilla-world/src/billboard.rs b/crates/benilla-world/src/billboard.rs
index c76e55fc..24ab1341 100644
--- a/crates/benilla-world/src/billboard.rs
+++ b/crates/benilla-world/src/billboard.rs
@@ -1,25 +1,14 @@
-//! M2 billboard cards — submeshes that ride a billboard bone (glow cards, chains, the questgiver
-//! markers). The real 1.12 client re-orients the bone to the camera every frame; benilla otherwise
-//! renders M2 geometry in its static bind pose, single-sided.
+//! M2 billboard cards: submeshes riding a billboard bone (glow cards, chains, the quest markers),
+//! turned to the camera every frame as the 1.12 client does.
 //!
-//! **The re-orientation law is byte-pinned** (wow-re `animation/scratch/billboard-bone-law.md`,
-//! §5): the M2 bone palette is computed in **VIEW space**, and a billboard bone's matrix rows are
-//! REPLACED with the camera basis — spherical (`0x08`) takes the whole fixed basis (bone X toward
-//! the viewer, Y screen-right, Z screen-up: the identity rows `{(0,0,−1),(1,0,0),(0,1,0)}` at
-//! `0x714463`); the lock arms (`0x10`/`0x20`/`0x40` = keep X/Y/Z) keep their authored axis and
-//! rebuild the other two from the camera (`0x40` lock-Z — the `?` marker's `0x240` — keeps model
-//! up, rebuild the in-plane pair). Crucially this is the **view-matrix basis, one shared
-//! orientation for every billboard** — NOT a per-pivot aim, and NOT the geometry's facet normal
-//! (the old card aimed its first-triangle normal at the camera: arbitrary for 3-D geometry like
-//! the 353-vert `?`, which is exactly why its proportions read wrong). The lock-Z in-plane sign
-//! is `Y = Fwd × Z` — the 0168 handedness residual, settled by the director's A/B (the recorded
-//! `Z × Fwd` order turned the model 180°: a mirrored `?`); it makes lock-Z agree with the
-//! spherical arm's toward-the-viewer X at a level camera.
+//! The reference computes the bone palette in view space and replaces a billboard bone's rows with
+//! the camera basis. Spherical (`0x08`) takes the whole basis, bone X toward the viewer, Y
+//! screen-right, Z screen-up (the rows `{(0,0,−1),(1,0,0),(0,1,0)}` at `0x714463`); lock-X/Y/Z
+//! (`0x10`/`0x20`/`0x40`) keeps its authored axis and rebuilds the other two from the camera. It
+//! is one shared orientation for every billboard, never a per-pivot aim or a facet normal.
 //!
-//! The submesh mesh is built **centred at its bone pivot** (`benilla_assets::build_submesh_mesh`)
-//! in the model-local Bevy frame — where the WoW bone axes land as X→−Z, Y→−X, Z→+Y (coords.rs) —
-//! so we place the entity at the pivot's world position and write the rebuilt basis as its
-//! rotation each frame; the geometry itself is never touched.
+//! A card's mesh is centred at its bone pivot in model-local Bevy axes (WoW X→−Z, Y→−X, Z→+Y), so
+//! the entity sits at the pivot with the rebuilt basis as its rotation.
 
 use benilla_assets::BillboardInfo;
 use benilla_formats::{BillboardKind, BoneScaleAnim};
@@ -29,73 +18,41 @@ use bevy::prelude::*;
 
 use crate::view::WorldCamera;
 
-/// A spawned billboard card: where its pivot sits in the world, its per-axis scale, how
-/// it tracks the camera (the bone-flag arm), and its optional global-sequence scale pulse. The
-/// per-frame system rewrites the entity transform from these — including `Visibility` (the
-/// hidden-owner mirror), so a card requires it rather than trusting every spawn site's `Mesh3d`
-/// to bring it along.
-///
-/// It requires a [`MeshTag`] for the same reason: a card is a world ROOT, so every per-model alpha
-/// that reaches an ordinary submesh by descending the model's tree has to reach a card through its
-/// own tag instead (`player::apply_self_model_fade` — the zoom-to-first-person feather). Only the
-/// alpha-animated spawn sites used to bring one, which left the channel *incidentally* present;
-/// the default `MeshTag(0)` is the shader's untagged-⇒-opaque sentinel, so requiring it changes
-/// nothing about how a card draws.
+/// A spawned billboard card: world pivot, per-axis scale, bone-flag arm and scale pulse. It needs
+/// a [`MeshTag`] as a world root: a per-model alpha (the self-model fade) reaches it through its
+/// own tag, and the default `MeshTag(0)` is the shader's untagged, opaque sentinel.
 #[derive(Component)]
 #[require(Transform, Visibility, MeshTag)]
 pub struct BillboardCard {
     world_pivot: Vec3,
-    /// The card's scale in its OWN (pre-billboard) frame — the joint's/placement's per-axis scale,
-    /// applied before the camera basis, exactly as [`billboard_joint_palette`] applies it to a
-    /// billboard JOINT (`Transform { rotation: camera_basis, scale, .. }` = `T·R_cam·S`). It is a
-    /// `Vec3` and not a scalar because real content animates a billboard bone **non-uniformly**:
-    /// the Lightwell's shaft (`World\Goober\G_HolyLightWell.m2`, bone 0, lock-Z) holds
-    /// `(8.808, 8.808, 37.560)` through its whole Stand loop, a 0.12 yd card stretched into a
-    /// 4.5 yd column of light. Collapsing that to `scale.x` and splatting it — which every lane
-    /// did until 2026-08-25 — rendered the shaft 1.06 yd tall instead: a squat, blown-out card
-    /// sitting on the well's own bowl and drowning it (bug B169, "Lightwell renders very buggy").
+    /// Per-axis scale in the card's own frame, applied before the camera basis (`T·R_cam·S`) as
+    /// the joint palette applies it. Not a scalar: the Lightwell's shaft
+    /// (`World\Goober\G_HolyLightWell.m2` bone 0) holds `(8.808, 8.808, 37.560)`.
     scale: Vec3,
     kind: BillboardKind,
-    /// The billboard bone's looping scale animation (the lamppost glow "breathe"), sampled each frame
-    /// and multiplied into [`Self::scale`]. `None` for a static card (no global-sequence scale track).
+    /// The bone's global-sequence scale loop (a lamppost glow's breathe), times [`Self::scale`].
     scale_anim: Option<BoneScaleAnim>,
-    /// The armed-sequence cursor offset (ms, negated so a wrapping ADD subtracts): sampling the
-    /// [`Self::seq_translation`] loop runs on `elapsed − arm_ms` — the reference's per-play
-    /// phase for SEQUENCE tracks (`cursor = clock − startOffset`, re-baked at every arm). `0`
-    /// until [`Self::arm_seq_translation`] arms a loop.
+    /// The arm time, negated so a wrapping add subtracts: [`Self::seq_translation`] samples at
+    /// `elapsed − arm_ms`, re-armed per play like the reference's sequence tracks.
     arm_neg_ms: u32,
-    /// The gseq [`Self::scale_anim`]'s ATTACH anchor (ms): `None` until the first placement pass
-    /// stamps it — the reference snapshots the scene clock once per model instance at attach
-    /// (`CM2Model+0x68`, wow-re `gseq-anchor.md`; decision 0856), so a row of lampposts streamed
-    /// in on different frames breathes at per-instance phases, while same-frame spawns share
-    /// one. Distinct from [`Self::arm_neg_ms`]: the gseq anchor is stamped once per instance,
-    /// the sequence cursor re-arms per play. (An earlier position-hash de-sync here emulated
-    /// the per-instance spread with an invented mechanism; 0855 briefly removed phase entirely —
-    /// both superseded by the byte law.)
+    /// The global-sequence clock's attach anchor (ms), stamped on the first placement pass and
+    /// never re-armed: the reference snapshots the scene clock once per instance (`CM2Model+0x68`)
+    /// and samples at `sceneNow − attach`, so cards attached on different frames breathe apart.
     gseq_attach_ms: Option<u32>,
-    /// The bone's armed first-sequence **translation** loop (the questgiver `?` marker's bob, keys in
-    /// Bevy axes) — sampled each frame on the same clock/phase and added at the pivot, rotated by
-    /// [`Self::placement_rot`]. `None` (every doodad card today) = the static pivot; only the marker
-    /// spawn site arms it via [`Self::with_seq_translation`] — the doodad half of that ride belongs
-    /// to the 0130 phase-4 bone-follow work.
+    /// The bone's armed first-sequence translation loop (a quest marker's bob, Bevy axes), added
+    /// at the pivot and turned by [`Self::placement_rot`]. Only the marker spawn site arms one.
     seq_translation: Option<BoneScaleAnim>,
     /// The placement's rotation, so the bob offset (model-local) points where the instance points.
     placement_rot: Quat,
-    /// The entity this card FOLLOWS (a unit/GameObject anchor or held-item root): the facing system
-    /// re-seats the card from its live `GlobalTransform` every frame and despawns the card when it
-    /// goes — the ONE mechanism for every non-doodad spawn path (braziers, held torches, missiles),
-    /// so a glow card can never again render at the model origin because a spawn site forgot the
-    /// pivot (the recurring "glow on the ground" family — decision 0153). `None` = fixed placement
-    /// (terrain doodads, whose transform never moves).
+    /// The entity this card follows, re-seated from it every frame and despawned with it (a unit
+    /// or GameObject anchor, a held-item root); `None` for a fixed placement.
     follow: Option<Entity>,
     /// The pivot in the model's local Bevy frame (re-applied each frame when `follow` is set).
     local_pivot: Vec3,
 }
 
 impl BillboardCard {
-    /// Build a card from a submesh's [`BillboardInfo`] and its instance `placement`. The pivot is placed
-    /// in the world; the card's orientation ignores the placement rotation (a billboard faces the camera
-    /// regardless of how the prop is turned).
+    /// A card for a submesh's [`BillboardInfo`] at a fixed instance `placement`.
     pub fn new(info: &BillboardInfo, placement: Transform) -> Self {
         let world_pivot = placement.transform_point(info.pivot);
         Self {
@@ -112,27 +69,16 @@ impl BillboardCard {
         }
     }
 
-    /// Build a card that FOLLOWS `owner` — the entity-path form (creatures, GameObjects, held
-    /// items, missiles, spell effects): world pivot/scale/rotation are re-derived from the owner's
-    /// live `GlobalTransform` every frame, and the card despawns when the owner goes.
+    /// A card following `owner` (a creature, GameObject, held item, missile or spell effect).
     pub fn following(info: &BillboardInfo, owner: Entity) -> Self {
         let mut card = Self::new(info, Transform::IDENTITY);
         card.follow = Some(owner);
         card
     }
 
-    /// Build a card riding a live JOINT — an animated host's billboard bone (the swinging lamp,
-    /// the mount's lights). The joint's frame already bakes the bone pivot (the 0130 rig identity
-    /// `joint = root · M_bone · T(pivot)`), so the card's local pivot is the joint origin.
-    ///
-    /// The joint also already carries the bone's global-sequence scale — every joint/anchor lane
-    /// runs a [`crate::rig_anim::GlobalSeqDrive`] over the same bone list, and `re_place`
-    /// reads the composed result back as [`Self::scale`] — so the card must NOT sample its own
-    /// copy of the track. Keeping it multiplied the twinkle in twice, at two different clocks
-    /// (the drive's spawn clock × the card's position-hash phase): squared peaks at random
-    /// alignment — Arcane Intellect's sometimes-2.5-yd lens flare (decision 0851). The sampler
-    /// stays on the rigless lanes ([`Self::new`]/[`Self::following`]), where the card is the only
-    /// thing animating.
+    /// A card on an animated host's billboard joint (a swinging lamp, a mount's lights). The joint
+    /// already bakes the pivot and the bone's global-sequence scale
+    /// ([`crate::rig_anim::GlobalSeqDrive`]), so the card samples none: that would twinkle twice.
     pub fn following_joint(info: &BillboardInfo, joint: Entity) -> Self {
         let mut card = Self::following(info, joint);
         card.local_pivot = Vec3::ZERO;
@@ -140,19 +86,9 @@ impl BillboardCard {
         card
     }
 
-    /// A card with **no geometry** — a pure billboard *frame*: an entity whose live transform is a
-    /// billboard bone's replaced palette matrix (pivot in the world, camera basis as the rotation),
-    /// for the other consumers of that matrix to ride. Today's one caller is the equipped-item
-    /// emitter lane (`entities::equipment::spawn`): an item model spawns no rig, so nothing else
-    /// would apply the replacement to a particle emitter hanging under a billboard bone — and the
-    /// reference folds the emitter's record position through exactly this matrix
-    /// (wow-re `part-anchoring-live-bone.md` §1 row 3).
-    ///
-    /// It is the same mechanism as a card and deliberately not a second one (decision 0153's rule):
-    /// same basis, same pivot law, same follow/despawn contract, one system. A card without a
-    /// `Mesh3d` simply draws nothing while its transform is maintained.
-    ///
-    /// `pivot` is model-local **Bevy** axes (the frame `owner`'s children live in).
+    /// A card with no mesh: a billboard bone's replaced palette matrix as a live transform, for an
+    /// item's particle emitter to ride (an item spawns no rig); the reference folds the emitter's
+    /// position through this matrix (`0x7190a9`-`0x71910c`). `pivot` is model-local Bevy axes.
     pub fn frame_following(kind: BillboardKind, pivot: Vec3, owner: Entity) -> Self {
         Self {
             world_pivot: Vec3::ZERO, // re-seated from the owner before the first facing write
@@ -168,17 +104,15 @@ impl BillboardCard {
         }
     }
 
-    /// Arm the card's first-sequence translation loop (the questgiver `?` bob) with the client's
-    /// arm-time cursor: sampling runs on `elapsed − arm_ms` (the loop starts at its first key the
-    /// moment the marker attaches, like the real arm at status receive).
+    /// Arms the first-sequence translation loop (a quest marker's bob) at `arm_ms`, so it opens on
+    /// its first key, as the reference arms it when the quest status arrives.
     pub fn with_seq_translation(mut self, anim: Option<BoneScaleAnim>, arm_ms: u32) -> Self {
         self.arm_seq_translation(anim, arm_ms);
         self
     }
 
-    /// Re-arm the translation loop on a LIVE card — the marker swapping between its low (anim 0)
-    /// and raised (anim 190) bob when the unit's overhead name toggles: fresh cursor, same law as
-    /// [`Self::with_seq_translation`].
+    /// Re-arms the loop on a live card: the marker swaps between its low (anim 0) and raised
+    /// (anim 190) bob when the unit's overhead name toggles.
     pub fn arm_seq_translation(&mut self, anim: Option<BoneScaleAnim>, arm_ms: u32) {
         if anim.is_some() {
             self.arm_neg_ms = arm_ms.wrapping_neg();
@@ -186,23 +120,14 @@ impl BillboardCard {
         self.seq_translation = anim;
     }
 
-    /// The entity this card follows, if any — the anchor/joint that decides both where it sits and
-    /// which model it BELONGS to. A card is a world root, so a system that walks a model's tree
-    /// (the self-avatar fade; the light node's shade push in `entity_shade`) can only recognise the
-    /// model's own cards by testing this against the entities it walked. `None` = a fixed terrain
-    /// doodad's card, whose shade rides its material selector instead.
-    ///
-    /// It is also the entity whose `InheritedVisibility` decides whether an entity-lane card draws
-    /// at all — a world root inherits nothing, so its model's hide has to be *read*, by the one
-    /// `Visibility` authority (`model_render::visibility`, decision 1409).
+    /// The entity this card follows. A card is a world root, so a walk over its model's tree (the
+    /// self fade, the shade push) recognises it through this, and the visibility authority
+    /// (`model_render::visibility`) draws it only while this entity is visible.
     pub fn follows(&self) -> Option<Entity> {
         self.follow
     }
 
-    /// Re-seat a card that FOLLOWS something (the questgiver `!`/`?` markers over a unit that can
-    /// move) — recompute the world pivot/scale/rotation from a fresh `placement`, keeping the card's
-    /// orientation kind, rest normal, and animation phase. Doodad cards never need this (their
-    /// placement is fixed at spawn).
+    /// Re-seats the card from a fresh `placement` (a quest marker over a moving unit).
     pub fn re_place(&mut self, placement: Transform, local_pivot: Vec3) {
         self.world_pivot = placement.transform_point(local_pivot);
         self.scale = placement.scale;
@@ -210,25 +135,12 @@ impl BillboardCard {
     }
 }
 
-/// A bone's rewritten **effective parent matrix** — the `flags & 0x7` arm the reference takes at
-/// `m2_animate` `0x71496d`–`0x714d0c`, before the billboard selector and before the bone's own TRS
-/// composes onto it (wow-re `billboard-bone-law.md` §9.1/§9.5, byte-verified). This is not an
-/// escape hatch from the billboard: it changes the input the billboard law is applied to, and the
-/// `&0x78` switch runs afterwards exactly as before.
-///
-/// - `parent` — the bone's ANIMATED parent world matrix (`palette[parent_bone]` before the rewrite).
-/// - `root` — the model's own root frame, `world_from_model` (`[model+0xfc]`): for a rigged host
-///   that is its `joints_root`, and for a mounted rider that is its seat anchor, which is exactly
-///   what the reference composes at `0x714389`.
-/// - `pivot` — the bone's BIND local translation (`pivot_i − pivot_parent`). Our joint chain is
-///   pivot-relative, so this plays the role of the byte law's model-space `piv` in the
-///   pivot-preserving tail `T' = pivotWorld − piv·newBasis`: the bone keeps the POSITION its
-///   animated parent carried it to and loses only the orientation. That is the whole reason a
-///   galloping mount still carries its rider up and down while never rocking them.
-///
-/// The reference is row-major with row vectors, so its "row K" is our column K — both name the
-/// image of model basis vector K, and the WoW→Bevy bake is a signed permutation of those axes, so
-/// the per-axis legs below pair the same axes the bytes do.
+/// A bone's rewritten parent matrix, the `flags & 0x7` arm (`0x71496d`-`0x714d0c`), taken before
+/// its own TRS and the `& 0x78` billboard switch, which still runs. `root` is the model's frame
+/// `[model+0xfc]` (composed at `0x714389`; a rider's seat anchor), `pivot` the bone's bind local
+/// translation. The tail `T' = pivotWorld − piv·newBasis` keeps where the animated parent carried
+/// the bone and drops only its orientation, so a mount carries its rider without rocking them.
+/// The reference's row K is our column K, both the image of basis vector K.
 pub(crate) fn parent_arm_matrix(
     arm: benilla_formats::ParentArm,
     parent: Affine3A,
@@ -236,15 +148,15 @@ pub(crate) fn parent_arm_matrix(
     pivot: Vec3,
 ) -> Affine3A {
     use benilla_formats::ParentBasis;
-    // `0x714bdb`'s unit guard: a degenerate axis is left alone rather than exploding.
+    // `0x714bdb`'s unit guard: a degenerate axis is left as it is.
     const UNIT_EPS: f32 = 1.0 / (1 << 22) as f32;
-    // `0x80c5c8`, the ratio leg's own constant — deliberately NOT the unit eps above.
+    // `0x80c5c8`, the ratio leg's own constant, not the unit eps above.
     const RATIO_EPS: f32 = 1e-5;
     let (p, r) = (parent.matrix3, root.matrix3);
     let per_axis = |f: &dyn Fn(usize) -> Vec3A| Mat3A::from_cols(f(0), f(1), f(2));
     let matrix3 = match arm.basis {
         ParentBasis::Keep => p,
-        // `flags & 6 == 2` — ignore parent scale: unit-length axes, directions kept.
+        // `flags & 6 == 2`, ignore parent scale: unit-length axes, directions kept.
         ParentBasis::UnitNormalize => per_axis(&|k| {
             let len = p.col(k).length();
             if len > UNIT_EPS {
@@ -253,8 +165,7 @@ pub(crate) fn parent_arm_matrix(
                 p.col(k)
             }
         }),
-        // `flags & 6 == 4` — ignore parent rotation: the ROOT's direction at the PARENT's
-        // magnitude, per axis.
+        // `flags & 6 == 4`, ignore parent rotation: the root's direction at the parent's length.
         ParentBasis::RootDirection => per_axis(&|k| {
             let rl2 = r.col(k).length_squared();
             let ratio = if rl2 <= RATIO_EPS {
@@ -264,7 +175,7 @@ pub(crate) fn parent_arm_matrix(
             };
             r.col(k) * ratio
         }),
-        // `flags & 6 == 6` — ignore parent rotation AND scale: the root basis outright.
+        // `flags & 6 == 6`, ignore parent rotation and scale: the root basis outright.
         ParentBasis::RootBasis => r,
     };
     Affine3A {
@@ -279,12 +190,9 @@ pub(crate) fn parent_arm_matrix(
     }
 }
 
-/// The rebuilt orientation for a billboard of `kind` — the byte law (module doc), one function
-/// for both consumers: the CARD path (`kept_rot` = the placement/owner rotation) and the JOINT
-/// palette pass below (`kept_rot` = the joint's fully-composed pre-billboard world rotation, the
-/// law's `normalize(rK)`). `bx/by/bz` are the bone's WoW-frame X/Y/Z axes as world directions
-/// after the replacement; the returned quat maps the mesh's model-local Bevy frame onto them
-/// (WoW axes sit in that frame as X→−Z, Y→−X, Z→+Y — coords.rs — so local X→−by, Y→bz, Z→−bx).
+/// The rebuilt orientation for a billboard of `kind`, for cards and joints alike; `kept_rot` is
+/// the pre-billboard rotation a lock arm keeps its axis from. `bx/by/bz` are the bone's WoW axes
+/// after the replacement, and Bevy local X/Y/Z maps onto `−by`/`bz`/`−bx`.
 pub fn billboard_basis(
     kind: BillboardKind,
     kept_rot: Quat,
@@ -293,27 +201,20 @@ pub fn billboard_basis(
     up: Vec3,
 ) -> Quat {
     let (bx, by, bz) = match kind {
-        // Spherical (`0x08`): the whole fixed basis — X toward the viewer, Y screen-right,
-        // Z screen-up (the view-space identity rows).
+        // Spherical (`0x08`): X toward the viewer, Y screen-right, Z screen-up.
         BillboardKind::Spherical => (-fwd, right, up),
-        // Lock-Z (`0x40` — the `?` marker, the frost-armor sheets): keep the authored bone Z
-        // (model up, pointed by `kept_rot`), rebuild the in-plane pair from the camera. The
-        // in-plane sign is `Y = Fwd × Z` — the 0168 residual, settled by the director's A/B
-        // (the other order showed the model's back: a mirrored `?`); this order also agrees
-        // with the spherical arm at a level camera (X toward the viewer, Y screen-right), the
-        // coherence the flipped version lacked. A camera looking straight along the kept axis
-        // degenerates the cross — hold screen-right then.
+        // Lock-Z (`0x40`, the `?` marker): keep the authored Z, rebuild the in-plane pair.
+        // `Y = Fwd × Z`, as the other order mirrors the model, and it agrees with the spherical
+        // arm at a level camera. Looking along Z degenerates the cross: Y holds screen-right.
         BillboardKind::LockZ => {
             let bz = (kept_rot * Vec3::Y).normalize_or(Vec3::Y);
             let by = fwd.cross(bz).try_normalize().unwrap_or(right);
             let bx = by.cross(bz);
             (bx, by, bz)
         }
-        // Lock-X/-Y: the same verified structure generalized per kept axis — the cyclically
-        // PREVIOUS axis takes `Fwd × kept` (that assignment is what reproduces the settled
-        // lock-Z arm), the third completes the right-handed WoW triple. No shipped content has
-        // A/B'd these two arms yet; if a chain/rope ever reads mirrored, the sign here is the
-        // one knob (0168's pattern).
+        // Lock-X/Y: lock-Z's structure per kept axis, the cyclically previous axis taking
+        // `Fwd × kept` and the third completing the right-handed WoW triple. Their in-plane sign
+        // follows lock-Z's by analogy, not from the reference.
         BillboardKind::LockX => {
             let bx = (kept_rot * -Vec3::Z).normalize_or(-fwd);
             let bz = fwd.cross(bx).try_normalize().unwrap_or(up);
@@ -330,42 +231,30 @@ pub fn billboard_basis(
     Quat::from_mat3(&Mat3::from_cols(-by, bz, -bx))
 }
 
-/// A rigged host whose skeleton authors billboard bones (component beside the rig's
-/// `AnimationPlayer`): the joint entities in bone order, each bone's parent, and which joints
-/// billboard. [`billboard_joint_palette`] rewrites those joints' propagated world rotations to
-/// the camera basis every frame — the byte law operates on the BONE PALETTE
-/// (`finalBoneWorld … children multiply onto this`, wow-re `billboard-bone-law.md`), so geometry
-/// skinned to a billboard bone's CHILDREN inherits the facing. The per-batch card split can
-/// never catch that case: the frost-armor sheets skin every vertex to the scale-in CHILD of the
-/// lock-Z bone, which is exactly why they rendered glued to the character.
+/// A rigged host's billboard and parent-arm bones, beside its `AnimationPlayer`. The reference
+/// billboards the bone palette, where children multiply onto the replaced matrix (`0x7151ba`), so
+/// geometry skinned to a billboard bone's child (the frost-armor sheets) inherits the facing.
 #[derive(Component)]
 pub struct BillboardJointRig {
-    /// The host root entity — the model's own root frame `[model+0xfc]`, which the `flags & 0x7`
-    /// arm rebuilds a bone's parent matrix out of.
+    /// The host root, the model's own frame `[model+0xfc]` that the `flags & 0x7` arm builds from.
     root: Entity,
     joints: Vec<Entity>,
     parents: Vec<i16>,
     kinds: Vec<Option<BillboardKind>>,
-    /// Bone flags `0x1/0x2/0x4` per joint ([`parent_arm_matrix`]) — the HandArrow/Bullet attach
-    /// helpers (the nocked arrow lies flat along the facing instead of twisting with the draw
-    /// hand, wow-re `nocked-ammo-cancel.md` §E4) and every vanilla mount's rider seat.
+    /// Bone flags `0x1/0x2/0x4` per joint: the HandArrow/Bullet helpers, every mount's rider seat.
     arms: Vec<Option<benilla_formats::ParentArm>>,
-    /// Each bone's BIND local translation — the pivot the arm preserves. `locals` carry the
-    /// ANIMATED translation, which the byte law rotates by the *new* basis, so the two are not
-    /// interchangeable here.
+    /// Each bone's bind local translation, the pivot the arm preserves; the animated local is not
+    /// interchangeable, as the reference rotates it by the new basis.
     binds: Vec<Vec3>,
 }
 
 impl BillboardJointRig {
-    /// The host root — the collapsed-rig world pass's do-not-enter set reads it (a nested rig
-    /// with its own billboard output owns its interior, whichever lane the outer rig is on).
+    /// The host root: the collapsed-rig world pass leaves a nested rig's interior to it.
     pub(crate) fn root(&self) -> Entity {
         self.root
     }
 
-    /// Build for a spawned rig — `None` when the skeleton authors neither a billboard bone nor a
-    /// `flags & 0x7` bone (the common case: ordinary rigs cost nothing). `root` is the host entity
-    /// the joints hang under (the model-space frame).
+    /// For a rig under host `root`; `None` when no bone billboards or has a `flags & 0x7` arm.
     pub fn new(
         skeleton: &benilla_assets::ModelSkeleton,
         joints: &[Entity],
@@ -393,35 +282,17 @@ impl BillboardJointRig {
     }
 }
 
-/// The palette half of the billboard law: for each rigged host, replace every billboard joint's
-/// world rotation with the camera basis (scale and pivot translation preserved — the law's
-/// `lenK`/`finalTranslation`, which in our rig identity is simply "keep the joint's global
-/// scale/translation"), then re-compose every descendant joint from its local TRS so skinned
-/// geometry — and emitters/ribbons riding those joints — inherit the facing. Runs after
-/// propagation and writes `GlobalTransform` directly (the same exactness argument as
-/// [`face_billboards`], which must run after this so following-joint cards read the replaced
-/// frames). **Every palette consumer must read AFTER this system, same frame**: avian's physics
-/// sync re-propagates the hierarchy from locals inside the fixed loop, so an Update-time read
-/// gets the UN-billboarded pose — the Demon Skin flames followed the character's yaw instead of
-/// the camera until the particle/ribbon sims moved behind this pass. Bone order is parent-sorted
-/// in every real M2 (the format guarantees parent < child); a malformed child whose parent
-/// follows it just keeps its propagated pose.
-///
-/// A rigged model can hang under ANOTHER rig's joint — a spell-effect instance on a unit's
-/// attach-helper bone, a rigged held item in a hand. One ownership law keeps the passes from
-/// fighting over those frames: the child-recompose walk **never enters a nested rig's subtree**
-/// — not even its root, whose propagated global (the live ANIMATED attach-bone frame) is what
-/// its emitters' attach frame must read. Without it, the boar's flag-0x04 attach helper
-/// re-composed the Eviscerate impact model's frames from raw locals, erasing its camera-born
-/// billboard basis or its animated attach rotation depending on per-launch query order — the
-/// burst rendered as a body-locked pillar on some launches and correctly on others. With no rig
-/// ever writing into another rig's subtree, the passes are order-independent again.
+/// The palette half of the billboard law: each billboard joint's world rotation becomes the camera
+/// basis, keeping scale and translation (the reference's tail `0x715868`), and its descendants
+/// re-compose on it, so skinned geometry and riding emitters inherit the facing. Every palette
+/// consumer must read after this pass: avian's physics sync re-propagates from locals in the
+/// fixed loop, so an Update read sees the un-billboarded pose. The walk never enters a nested rig,
+/// not even its root (a spell effect on an attach bone), so no rig overwrites another's frames.
+/// M2 bones are parent-sorted; a malformed child whose parent follows it keeps its propagated pose.
 pub fn billboard_joint_palette(
     cam: Query<&GlobalTransform, With<WorldCamera>>,
     hosts: Query<&BillboardJointRig>,
-    // A parked unit's pose is frozen off-frustum (decision 0448) — camera-facing its glow joints
-    // would re-dirty the subtree for a rig no one sees. A parked host still sits in the
-    // do-not-enter set (its propagated frames are real); it just isn't re-faced.
+    // A parked host (frozen off-frustum) is not re-faced but stays in the do-not-enter set.
     parked: Query<Has<crate::rig_anim::AnimParked>>,
     mut joints: Query<(&Transform, &mut GlobalTransform), Without<WorldCamera>>,
     children: Query<&Children>,
@@ -430,15 +301,14 @@ pub fn billboard_joint_palette(
         return;
     };
     let (fwd, right, up) = (*cam_tf.forward(), *cam_tf.right(), *cam_tf.up());
-    // Every rig root — the walk's do-not-enter set.
+    // Every rig root: the walk's do-not-enter set.
     let rig_roots: bevy::platform::collections::HashSet<Entity> =
         hosts.iter().map(|r| r.root).collect();
     for rig in hosts
         .iter()
         .filter(|r| !parked.get(r.root).unwrap_or(false))
     {
-        // The model's own root frame `[model+0xfc]` — what the `flags & 0x7` arm rebuilds a
-        // parent matrix out of. Read before the joint loop (the root is never a joint).
+        // The model's own frame `[model+0xfc]`, which the `flags & 0x7` arm builds from.
         let root_affine = joints
             .get(rig.root)
             .map(|(_, g)| g.affine())
@@ -450,10 +320,9 @@ pub fn billboard_joint_palette(
             let parent_new = pidx.and_then(|p| replaced[p]);
             let arm = rig.arms[i];
             if parent_new.is_none() && rig.kinds[i].is_none() && arm.is_none() {
-                continue; // untouched subtree — the propagated pose stands
+                continue; // untouched: the propagated pose stands
             }
-            // The arm needs the PARENT's matrix in hand; propagation only left us the child's, so
-            // an armed bone whose parent was untouched reads the parent's propagated frame here.
+            // An armed bone under an untouched parent reads the parent's propagated frame.
             let parent_world = if arm.is_some() {
                 parent_new.or_else(|| {
                     let e = pidx.map_or(rig.root, |p| rig.joints[p]);
@@ -466,8 +335,7 @@ pub fn billboard_joint_palette(
                 continue;
             };
             let mut g = match (arm, parent_world) {
-                // `flags & 0x7`: rewrite the parent matrix, then compose this bone's own TRS onto
-                // it — and fall through to the billboard switch, which still runs (§9.1).
+                // `flags & 0x7` rewrites the parent; the billboard switch below still runs.
                 (Some(a), Some(pw)) => GlobalTransform::from(parent_arm_matrix(
                     a,
                     pw.affine(),
@@ -489,10 +357,8 @@ pub fn billboard_joint_palette(
             replaced[i] = Some(g);
             *global = g;
         }
-        // Rigid children hanging under a rewritten joint (a held item, the nocked arrow) got
-        // their globals from ordinary propagation — BEFORE this rewrite. Re-compose those
-        // subtrees from the replaced frames; sibling JOINTS are excluded (the replaced-chain
-        // above owns them). Skinned geometry never needs this — it reads the joint frames.
+        // Rigid children under a rewritten joint (held items, the nocked arrow) were propagated
+        // before the rewrite: re-compose them, skipping joints, which the loop above owns.
         let joint_set: bevy::platform::collections::HashSet<Entity> =
             rig.joints.iter().copied().collect();
         let mut stack: Vec<(Entity, GlobalTransform)> = Vec::new();
@@ -523,27 +389,15 @@ pub fn billboard_joint_palette(
     }
 }
 
-/// The billboard placement pass (PostUpdate, after `TransformSystems::Propagate`, before
-/// visibility) — [`billboard_joint_palette`] then [`face_billboards`] run here, and upstream
-/// card re-seaters (the quest markers) order `.before` it. Placement reads the SAME-frame
-/// propagated pose: running in Update read last-frame joint/owner globals, so a card over a
-/// moving unit trailed a frame behind and snapped forward on stop (the nameplate lag's sibling).
+/// The billboard placement pass: PostUpdate, after transform propagation and before visibility,
+/// so placement reads this frame's pose. Card re-seaters (the quest markers) order before it.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub struct BillboardPlace;
 
-/// Per-frame: face each billboard card to the camera (around its pivot) and apply its scale pulse.
-/// A FOLLOWING card (entity-path) is first re-seated from its owner's live global transform — and
-/// despawned when the owner is gone (streamed out, unequipped, died). Runs in [`BillboardPlace`]
-/// (post-propagation), so it writes `GlobalTransform` directly alongside `Transform` — cards
-/// write ABSOLUTE world transforms and live at the root/identity, so the direct write is exact.
-///
-/// It does NOT own a card's `Visibility` — [`crate::model_render::visibility`] does, for every
-/// card as for every other `ModelPart` (decision 0025). This system used to mirror a hidden owner
-/// here as well, and that write was **dead**: [`BillboardPlace`] is only ordered
-/// `before(CheckVisibility)`, not before `VisibilityPropagate`, so the `Hidden` it wrote landed
-/// after the propagation that would have consumed it and was overwritten in the next frame's
-/// `Update` by the authority — for a year, a GameObject's glow card went on burning over its own
-/// culled model (decision 1409).
+/// Faces each card to the camera about its pivot and applies its scale pulse, first re-seating a
+/// following card from its owner, or despawning it with the owner. Cards are world roots, so the
+/// direct `GlobalTransform` write is exact. A `Visibility` write here would be lost: this set is
+/// not ordered before visibility propagation, and [`crate::model_render::visibility`] owns it.
 #[allow(clippy::type_complexity)] // the card tuple, commented inline
 pub(crate) fn face_billboards(
     mut commands: Commands,
@@ -565,22 +419,13 @@ pub(crate) fn face_billboards(
     let Ok((cam_tf, cam_local)) = cam.single() else {
         return;
     };
-    // The camera basis — the VIEW-MATRIX axes the byte law substitutes (one shared orientation
-    // for every billboard; never a per-pivot aim).
-    // The propagated frame OR the seat's own write: a teleport frame moves the local before
-    // propagation runs (see doodad_anim's gate), and the old read carried a pre-snap placement
-    // across the snap.
+    // A teleport frame moves the seat's local before propagation, so either change counts.
     let cam_moved = cam_tf.is_changed() || cam_local.as_ref().is_some_and(|l| l.is_changed());
     let (fwd, right, up) = (*cam_tf.forward(), *cam_tf.right(), *cam_tf.up());
     let elapsed_ms = time.elapsed().as_millis() as u32;
     for (entity, mut card, mut tf, mut global, tag) in &mut cards {
-        // A card with no track is a pure function of the camera basis and its owner's frame:
-        // when neither moved this frame, the placement below would come out bit-identical
-        // (the write guards at the end already knew that; the recompute did not — 1979's
-        // floor, every resident card re-placed on a still frame).
-        // …and a card that has never been placed (the first-pass stamp is what says so): it
-        // spawned unrotated at scale one, and a still frame must not leave it that way
-        // (review of 2026-09-04 — a tile bursting in under a parked camera).
+        // A track-less card is a pure function of the camera and its owner, so it is skipped
+        // when neither moved, unless it has never been placed (no attach stamp yet).
         let tracked = card.scale_anim.is_some()
             || card.seq_translation.is_some()
             || card.gseq_attach_ms.is_none();
@@ -592,16 +437,9 @@ pub(crate) fn face_billboards(
                     }
                     let pivot = card.local_pivot;
                     card.re_place(gt.compute_transform(), pivot);
-                    // The card-provenance trace (`WOW_MOVE_TRACE`, ~2 Hz): where each following
-                    // card sits, how big it renders, and at what alpha. An invisible spell-fx
-                    // card has exactly three possible causes — placement, scale, alpha — and a
-                    // screenshot cannot tell them apart; this line does (it split Arcane
-                    // Intellect's "missing" stars into scale ✓ / place ✓ / alpha ×0.3 — the
-                    // faithful stealth-aura compose, not a defect).
-                    // `enabled_for`, not `enabled`: this is by far the busiest tag in the file
-                    // (thousands of lines a second in a populated scene, each an unbuffered write
-                    // under the shared mutex), so it is the one most worth dropping cheaply when the
-                    // run is asking a movement question — `WOW_MOVE_TRACE_TAGS`, decision 0880.
+                    // The `card` trace (`WOW_MOVE_TRACE`, ~2 Hz): each following card's place,
+                    // scale and alpha, the three causes of an invisible card. `enabled_for`, so
+                    // `WOW_MOVE_TRACE_TAGS` drops this busiest tag cheaply.
                     if benilla_assets::trace::enabled_for("card") && elapsed_ms % 512 < 20 {
                         benilla_assets::trace::line(
                             "card",
@@ -622,21 +460,15 @@ pub(crate) fn face_billboards(
         } else if !tracked && !cam_moved {
             continue;
         }
-        // The gseq attach anchor: stamped on the card's first placement pass — the reference's
-        // once-per-instance scene-clock snapshot (decision 0856).
+        // The gseq attach anchor, stamped on the first placement pass (`CM2Model+0x68`).
         let attach_ms = *card.gseq_attach_ms.get_or_insert(elapsed_ms);
         let card = &*card;
         let rotation = billboard_basis(card.kind, card.placement_rot, fwd, right, up);
-        // The bone's global-sequence scale pulse (the lamppost glow "breathe"), on the instance's
-        // anchored cursor (`sceneNow − attach`): instances stamped on different frames pulse at
-        // per-instance phases, same-frame spawns in phase — the reference's anchor law.
-        // `Vec3::ONE` (no-op) when the card has no scale track.
+        // The global-sequence scale pulse on the instance's anchored cursor, `sceneNow − attach`.
         let pulse = card.scale_anim.as_ref().map_or(Vec3::ONE, |a| {
             Vec3::from_array(a.sample(elapsed_ms.wrapping_sub(attach_ms)))
         });
-        // The armed first-sequence translation loop (the questgiver `?` bob): a model-local offset
-        // at the pivot, pointed by the placement rotation and sized by its scale — on the ARM
-        // cursor (`elapsed − arm_ms`), the sequence-track half of the clock law.
+        // The armed bob on the arm cursor `elapsed − arm_ms`, turned and sized by the placement.
         let bob = card.seq_translation.as_ref().map_or(Vec3::ZERO, |a| {
             card.placement_rot
                 * (Vec3::from_array(a.sample(elapsed_ms.wrapping_add(card.arm_neg_ms)))
@@ -647,15 +479,11 @@ pub(crate) fn face_billboards(
             rotation,
             scale: card.scale * pulse,
         };
-        // A parked camera over a still, track-less card recomputes bit-identical values, so the
-        // write only lands on real movement: unconditional, it marked every card
-        // `Changed<Transform>`+`Changed<GlobalTransform>` every frame and the downstream
-        // change-detection consumers (`classify_water_side`'s moved sweep, the shade dirty walk)
-        // never went quiet.
+        // Only a real change is written, so change-detection consumers go quiet on a still frame.
         if *tf != placed {
             *tf = placed;
         }
-        // Propagation already ran this frame — the direct global write is what renders.
+        // Propagation already ran this frame: the direct global write is what renders.
         let placed_global = GlobalTransform::from(placed);
         if *global != placed_global {
             *global = placed_global;
@@ -663,14 +491,12 @@ pub(crate) fn face_billboards(
     }
 }
 
-/// Registers the billboard placement pass ([`BillboardPlace`], PostUpdate post-propagation).
-/// Cards are spawned by the model spawn sites (in Update — mesh churn stays there).
+/// Registers the [`BillboardPlace`] pass; the model spawn sites spawn cards, in Update.
 pub struct BillboardPlugin;
 
 impl Plugin for BillboardPlugin {
     fn build(&self, app: &mut App) {
-        // The set carries the schedule constraints so every member — including the
-        // particle/ribbon sims other plugins add — lands post-propagation, pre-visibility.
+        // The set holds the ordering, so the particle and ribbon sims other plugins add get it too.
         app.configure_sets(
             PostUpdate,
             BillboardPlace
@@ -681,9 +507,8 @@ impl Plugin for BillboardPlugin {
             PostUpdate,
             (
                 billboard_joint_palette,
-                // The collapsed-rig world pass (decision 0724): palette rows + replaced-subtree
-                // anchor re-seats, between the entity lane's joint rewrite and the card facing
-                // (cards following a unit's billboard-bone anchor read the replaced frame).
+                // The collapsed-rig world pass, between the joint rewrite and the card facing:
+                // cards on a unit's billboard-bone anchor read the replaced frame.
                 crate::rig_anim::finalize_rig_worlds,
                 face_billboards,
             )
@@ -698,24 +523,11 @@ mod tests {
     use super::*;
     use benilla_assets::BillboardInfo;
 
-    /// **Geometry lying along a bone's own axis does not sweep** — the fact decision 0847 got wrong
-    /// and 0853 restored, pinned here in our own basis rather than trusted to algebra.
-    ///
-    /// The R14 pauldron's spikes run along WoW **−Z** (`seamswing`: mean |z| 0.284/0.291 against
-    /// ≤0.06 on x and y, worst vertex 12° off axis), which is Bevy local **−Y**. A spherical
-    /// billboard maps WoW Z to the camera's up, so that direction must come out as **−up — screen
-    /// DOWN — from every camera orientation**, never tracing an arc. 0847 read the spikes' 0.29 yd
-    /// length as a 0.29 yd arc through the plate and withdrew a correct change on it; if that arc
-    /// were real, this test is where it would show up as a direction that moves with the camera.
-    ///
-    /// The `kept_rot` argument is swept too: the spherical arm discards the pre-billboard rotation
-    /// outright (wow-re `billboard-bone-law.md` §1), so the wearer's shoulder yaw must not reach
-    /// the result — which is *also* why the spike stops following the shoulder, the real visible
-    /// difference the arm makes (§6.3).
+    /// The R14 pauldron's spikes run along WoW −Z (`seamswing`), Bevy −Y: a spherical billboard
+    /// points them screen-down from every camera and discards the pre-billboard rotation
+    /// (`0x7152f8`), so the wearer's shoulder yaw never reaches them.
     #[test]
     fn a_spike_along_its_bone_axis_points_screen_down_from_every_angle() {
-        // Bevy local −Y is the pauldron spike's run axis (WoW −Z through coords.rs' X→−Z, Y→−X,
-        // Z→+Y).
         let spike_local = Vec3::NEG_Y;
         for (yaw, pitch) in [
             (0.0, 0.0),
@@ -748,10 +560,6 @@ mod tests {
         }
     }
 
-    /// A FOLLOWING card (decision 0153 — the entity-path glow cards) re-seats from its owner's
-    /// live global transform each frame and despawns with it: the brazier glow burns at the bowl
-    /// (owner translation + authored pivot), never the model origin — and dies when the owner
-    /// streams out / unequips.
     #[test]
     fn following_card_rides_its_owner_and_dies_with_it() {
         let mut app = App::new();
@@ -783,10 +591,6 @@ mod tests {
             Vec3::new(5.0, 1.7, 0.0),
             "owner translation + authored pivot — not the model origin"
         );
-        // The hidden-owner half of this test used to live here, asserting a `Visibility` write
-        // this system made and the real schedule then threw away — a green test pinning a dead
-        // write (decision 1409). The law is unchanged and now lives with the one authority that
-        // can enforce it: `model_render::visibility::a_card_follows_its_owners_verdict`.
         app.world_mut().entity_mut(owner).despawn();
         app.update();
         assert!(
@@ -795,12 +599,7 @@ mod tests {
         );
     }
 
-    /// A JOINT-lane card takes the global-sequence twinkle from the joint ALONE (decision 0851):
-    /// every joint/anchor lane runs a `GlobalSeqDrive` that writes the bone's scale track onto
-    /// the joint, and `re_place` reads the composed result back as the card's scale — a card that
-    /// also sampled its own copy multiplied the twinkle in twice, at two clocks offset by the
-    /// position-hash phase (Arcane Intellect's sometimes-2.5-yd lens flare). The rigless lanes
-    /// keep the sampler: there the card is the only thing animating.
+    /// The joint's `GlobalSeqDrive` carries the twinkle; only a rigless card samples its own.
     #[test]
     fn joint_lane_takes_the_twinkle_from_the_joint_alone() {
         let mut app = App::new();
@@ -810,7 +609,6 @@ mod tests {
             crate::view::WorldCamera,
             GlobalTransform::from_translation(Vec3::new(0.0, 0.0, 10.0)),
         ));
-        // The twinkle track, a flat ×2 — visible wherever it is applied.
         let info = BillboardInfo {
             bone: 0,
             pivot: Vec3::ZERO,
@@ -822,8 +620,8 @@ mod tests {
             }),
             seq_translations: vec![],
         };
-        // The joint arrives already composed by the rig: drive-written twinkle ×2 × parent
-        // flare ×3 = 6. Sampling the track again on top would render ×12.
+        // The joint as the rig composes it: twinkle ×2 × parent flare ×3 = 6; sampling the
+        // track again would render ×12.
         let joint = app
             .world_mut()
             .spawn(GlobalTransform::from(Transform::from_scale(Vec3::splat(
@@ -837,8 +635,6 @@ mod tests {
                 Transform::IDENTITY,
             ))
             .id();
-        // The rigless lane: a plain anchor at scale 1 — the card's own sampler is the only
-        // twinkle writer.
         let anchor = app.world_mut().spawn(GlobalTransform::IDENTITY).id();
         let rigless_card = app
             .world_mut()
@@ -858,25 +654,12 @@ mod tests {
         );
     }
 
-    /// **A card keeps its bone's NON-UNIFORM scale** — bug B169, the Lightwell (2026-08-25).
-    ///
-    /// `World\Goober\G_HolyLightWell.m2` bone 0 is a lock-Z billboard carrying the well's light
-    /// shaft (batch 0, `LIGHTWELLRAY.BLP`, 12 verts all weight-1 on that bone, so the 0028 split
-    /// makes it a card). Its scale is a **sequence** track, not a global-sequence one, so nothing
-    /// in `BillboardInfo::scale_anim` carries it: the value reaches the card only through the
-    /// joint, via `re_place`. Authored (WoW axes, `m2anim`): the Spawn clamp ramps
-    /// `(1,1,1) → (8.808, 8.808, 37.560)` in 0.5 s and the 23.3 s Stand loop holds it there,
-    /// pulsing Z between 35.170 and 37.560 — a 0.18 × 0.12 yd card stretched into a
-    /// **1.59 × 4.51 yd** column of light standing out of the bowl.
-    ///
-    /// `re_place` used to keep `placement.scale.x` and splat it, so the shaft rendered
-    /// 1.59 × **1.06** yd: a squat additive card sitting exactly on the 1.09 yd bowl at the same
-    /// height, blowing it out. Every test above this one used a uniform `Vec3::splat`, which is
-    /// why the collapse survived — the numbers here are the asset's own.
+    /// `World\Goober\G_HolyLightWell.m2` bone 0 is a lock-Z card whose sequence scale track
+    /// (`m2anim`, WoW axes) holds `(8.808, 8.808, 37.560)` through its Stand loop; it reaches the
+    /// card only through the joint, and stands the 0.12 yd card 4.51 yd tall.
     #[test]
     fn a_card_keeps_its_bones_non_uniform_scale() {
-        // The authored WoW-axis scale, permuted to Bevy axes exactly as the clip builder does
-        // (`benilla_assets`: `Vec3::new(s[1], s[2], s[0])` — Bevy Y is WoW Z, the shaft's long axis).
+        // WoW axes permuted to Bevy as the clip builder does: Bevy Y is WoW Z, the long axis.
         const WOW: [f32; 3] = [8.808, 8.808, 37.560];
         let bevy_scale = Vec3::new(WOW[1], WOW[2], WOW[0]);
         // The card's authored span (`m2batch`): 0.18 yd across, 0.12 yd tall, in the YZ plane.
@@ -893,11 +676,9 @@ mod tests {
             bone: 0,
             pivot: Vec3::ZERO,
             kind: BillboardKind::LockZ,
-            scale_anim: None, // a SEQUENCE track — the joint is the only carrier
+            scale_anim: None, // a sequence track: the joint is its only carrier
             seq_translations: vec![],
         };
-        // The joint as the rig composes it: the billboard palette preserves the full scale, so
-        // this is what `re_place` reads back.
         let joint = app
             .world_mut()
             .spawn(GlobalTransform::from(Transform::from_scale(bevy_scale)))
@@ -923,22 +704,6 @@ mod tests {
         );
     }
 
-    /// **The billboard FRAME an equipped item's emitter rides** (decision 0813), with the real
-    /// numbers of nazriel's B118 item (`LShoulder_Mail_PVPAlliance_C_01`: billboard bone 1 pivot
-    /// `(-0.012, 0.162, -0.060)`, sparkle emitter position `(-0.252, 0.178, -0.046)`, both raw WoW
-    /// model space — pinned in `benilla_formats`' `real_pvp_shoulder_emitters_ride_a_billboard_bone`).
-    ///
-    /// The law: the emitter's live origin is `pivot + camBasis·(position − pivot)`, so the sparkle
-    /// sits a **fixed 0.24 yd along the VIEW axis** from the pauldron's billboard pivot — behind it
-    /// (the chain offset's WoW +X is toward the viewer and this offset is negative), which is what
-    /// puts most of the 0.7 yd quad behind the pauldron's own depth. A rest-pose placement instead
-    /// nails it to a fixed model-space point, so what the pad occludes changes with every camera
-    /// move — the reported "way too strong and off position". Both halves are asserted: the offset's
-    /// magnitude/direction at one camera, and that it FOLLOWS the camera to the next.
-    /// A card that spawns under a parked camera must still be placed on its first pass: the
-    /// still-frame skip (1979) has no view of "never placed", and a tile bursting in under a
-    /// parked camera left every glow card unrotated at scale one until the mouse moved
-    /// (review 2026-09-04).
     #[test]
     fn a_card_born_on_a_still_frame_is_placed() {
         use benilla_assets::coords::wow_to_bevy;
@@ -973,6 +738,9 @@ mod tests {
         );
     }
 
+    /// The R14 PVP shoulder (`LShoulder_Mail_PVPAlliance_C_01`): billboard bone 1's pivot and its
+    /// sparkle emitter, raw WoW axes. The emitter rides `pivot + camBasis·(position − pivot)`, so
+    /// the sparkle sits 0.24 yd behind the pivot along the view axis from any camera.
     #[test]
     fn an_item_emitters_billboard_frame_puts_it_behind_the_pivot() {
         use benilla_assets::coords::wow_to_bevy;
@@ -992,7 +760,6 @@ mod tests {
             .world_mut()
             .spawn((crate::view::WorldCamera, GlobalTransform::IDENTITY))
             .id();
-        // The item root — the shoulder attach point, wherever the wearer stands.
         let root = app
             .world_mut()
             .spawn(GlobalTransform::from_translation(Vec3::new(3.0, 1.5, 0.0)))
@@ -1005,8 +772,7 @@ mod tests {
             ))
             .id();
 
-        // Camera 1: the Bevy default (at the origin, looking down −Z) — so "away from the viewer"
-        // is −Z.
+        // Camera 1: the Bevy default, looking down −Z, so away from the viewer is −Z.
         app.update();
         let tf = *app.world().entity(frame).get::<Transform>().unwrap();
         let pivot_world = Vec3::new(3.0, 1.5, 0.0) + wow_to_bevy(PIVOT);
@@ -1024,8 +790,7 @@ mod tests {
             "…and all but ~2 cm of the offset is in that one axis: {sparkle:?}"
         );
 
-        // Camera 2: a quarter turn — the offset must follow the camera, not the model. This is the
-        // whole difference from the rest pose, which would return the same vector both times.
+        // Camera 2: a quarter turn. The offset follows the camera; a rest pose would not move.
         app.world_mut()
             .entity_mut(cam)
             .insert(GlobalTransform::from(Transform::from_rotation(
@@ -1045,14 +810,7 @@ mod tests {
         );
     }
 
-    /// A card the **exterior-scene cull** owns must not have its `Visibility` written here
-    /// (decision 0784). One component, one authority (0025): a world-placement card is tagged
-    /// with the rest of its model, both systems run in the same unordered post-propagation
-    /// window, and this mirror silently undid the cull's `Hidden` — a lamp glow drawing through
-    /// a sealed room's wall while every other submesh of the same lamp was correctly gone.
-    ///
-    /// The card must still be *placed* (its transform is this system's job either way), and an
-    /// untagged card must still mirror — that half is the test above.
+    /// A card tagged `ExteriorScene` keeps the cull's `Hidden`, and is still placed.
     #[test]
     fn the_exterior_cull_owns_a_tagged_cards_visibility() {
         let mut app = App::new();
@@ -1062,7 +820,7 @@ mod tests {
             crate::view::WorldCamera,
             GlobalTransform::from_translation(Vec3::new(0.0, 0.0, 10.0)),
         ));
-        // A VISIBLE owner — the mirror's "show it" arm, which is the one that did the damage.
+        // A visible owner, whose verdict must not reach a card the cull has hidden.
         let owner = app
             .world_mut()
             .spawn((
@@ -1082,7 +840,7 @@ mod tests {
             .spawn((
                 BillboardCard::following(&info, owner),
                 Transform::IDENTITY,
-                // …and the cull has already hidden it: no window admits this model.
+                // The cull has already hidden it: no window admits this model.
                 Visibility::Hidden,
                 crate::exterior_cull::ExteriorScene,
             ))
@@ -1104,31 +862,24 @@ mod tests {
         );
     }
 
-    /// The palette pass: a lock-Z billboard JOINT gets its propagated world rotation replaced by
-    /// the camera basis (translation/scale kept — the pivot stays put, the grow-in scale
-    /// survives), and its CHILD joint is re-composed from the replaced parent — so geometry
-    /// skinned to the child inherits the facing (the frost-armor case). The host's own yaw must
-    /// not leak into the result: two hosts facing opposite ways produce the SAME billboarded
-    /// orientation for an upright lock-Z bone.
+    /// A lock-Z joint takes the camera basis, keeping its pivot and scale, and its child joint
+    /// re-composes on it; the host's yaw does not reach the result.
     #[test]
     fn palette_pass_faces_joints_and_recomposes_children() {
         let mut app = App::new();
         app.add_systems(Update, billboard_joint_palette);
         app.world_mut().spawn((
             crate::view::WorldCamera,
-            // Looking along −Z from +Z, world-up Y — the identity camera frame.
             GlobalTransform::from(Transform::from_translation(Vec3::new(0.0, 0.0, 10.0))),
         ));
         let mut spawn_host = |yaw: f32| {
             let host_rot = Quat::from_rotation_y(yaw);
-            // Joint 0: lock-Z billboard at the host's frame, world pivot (5, 1, 0), scale 2.
             let j0_global = GlobalTransform::from(Transform {
                 translation: Vec3::new(5.0, 1.0, 0.0),
                 rotation: host_rot,
                 scale: Vec3::splat(2.0),
             });
             let j0 = app.world_mut().spawn((Transform::IDENTITY, j0_global)).id();
-            // Joint 1: the scale-in child, one unit up its parent's Y, half scale.
             let j1_local = Transform::from_translation(Vec3::Y).with_scale(Vec3::splat(0.5));
             let j1 = app
                 .world_mut()
@@ -1168,11 +919,8 @@ mod tests {
         let (s0, r0, t0) = g0.to_scale_rotation_translation();
         assert_eq!(t0, Vec3::new(5.0, 1.0, 0.0), "the pivot stays put");
         assert!((s0 - Vec3::splat(2.0)).length() < 1e-5, "scale preserved");
-        // Lock-Z at this camera: kept axis = world up; the replaced frame is exactly the
-        // camera-agreeing basis — local +Y stays up, local −Z faces the viewer.
         assert!((r0 * Vec3::Y).dot(Vec3::Y) > 0.999, "kept axis upright");
         assert!((r0 * -Vec3::Z).dot(Vec3::Z) > 0.999, "faces the camera");
-        // The opposite-facing host lands on the SAME orientation — char yaw does not leak.
         let (_, rb, _) = app
             .world()
             .entity(b0)
@@ -1183,8 +931,8 @@ mod tests {
             rb.angle_between(r0) < 1e-4,
             "host yaw must not change the facing"
         );
-        // The child re-composed onto the replaced parent: parent's new Y is world Y, so the
-        // child sits one PARENT-scaled unit above the pivot, with composed scale 2·0.5 = 1.
+        // The child re-composed on the replaced parent: one parent-scaled unit above the pivot,
+        // composed scale 2·0.5 = 1.
         let (s1, _, t1) = app
             .world()
             .entity(a1)
@@ -1201,14 +949,9 @@ mod tests {
         );
     }
 
-    /// The four `flags & 0x6` legs of [`parent_arm_matrix`], each against its byte definition
-    /// (wow-re `billboard-bone-law.md` §9.5), plus the pivot-preserving tail that is the whole
-    /// reason a galloping mount carries its rider without rocking them.
-    ///
-    /// The parent here is rotated 90° about X and scaled non-uniformly; the root is a plain 90°
-    /// yaw at scale 3. Each leg is asserted on the quantity it is defined by — axis LENGTHS for
-    /// the scale legs, axis DIRECTIONS for the rotation legs — so a leg that accidentally did the
-    /// other one's job cannot pass.
+    /// Each `flags & 0x6` leg (`0x71496d`-`0x714d0c`) is asserted on what defines it, axis lengths
+    /// for scale and axis directions for rotation, so a leg doing another's job fails; then the
+    /// pivot-preserving tail.
     #[test]
     fn the_parent_arm_legs_match_their_byte_definitions() {
         use benilla_formats::{ParentArm, ParentBasis};
@@ -1230,11 +973,9 @@ mod tests {
         let axis_len = |m: Affine3A, k: usize| m.matrix3.col(k).length();
         let axis_dir = |m: Affine3A, k: usize| Vec3::from(m.matrix3.col(k).normalize());
 
-        // `flags & 6 == 0` — the basis is the parent's, untouched.
         let keep = parent_arm_matrix(arm(ParentBasis::Keep), parent, root, pivot);
         assert!(keep.matrix3.abs_diff_eq(parent.matrix3, 1e-5));
 
-        // `flags & 6 == 2` — unit axes, parent's directions.
         let unit = parent_arm_matrix(arm(ParentBasis::UnitNormalize), parent, root, pivot);
         for k in 0..3 {
             assert!((axis_len(unit, k) - 1.0).abs() < 1e-5, "axis {k} unit");
@@ -1244,7 +985,6 @@ mod tests {
             );
         }
 
-        // `flags & 6 == 4` — root's direction, parent's magnitude, per axis.
         let ratio = parent_arm_matrix(arm(ParentBasis::RootDirection), parent, root, pivot);
         for k in 0..3 {
             assert!(
@@ -1257,12 +997,10 @@ mod tests {
             );
         }
 
-        // `flags & 6 == 6` — the root basis outright, scale included.
         let full = parent_arm_matrix(arm(ParentBasis::RootBasis), parent, root, pivot);
         assert!(full.matrix3.abs_diff_eq(root.matrix3, 1e-5));
 
-        // The pivot-preserving tail: whichever leg ran, composing the bone's own bind translation
-        // onto the rewritten matrix lands it exactly where the ANIMATED parent carried it.
+        // The tail: every leg lands the bind translation where the animated parent carried it.
         let want = parent.transform_point3a(pivot.into());
         for m in [keep, unit, ratio, full] {
             let landed = m.transform_point3a(pivot.into());
@@ -1282,10 +1020,8 @@ mod tests {
         assert!((Vec3::from(moved.translation) - Vec3::new(0.0, 5.0, 0.0)).length() < 1e-5);
     }
 
-    /// The ignore-parent-rotation joint (bone flag 0x04 — the HandArrow/Bullet attach helpers,
-    /// wow-re `nocked-ammo-cancel.md` §E4): its pivot rides the parent's full matrix, its
-    /// ROTATION resets to the host root's frame — and a rigid child (the nocked arrow) hanging
-    /// under it re-composes onto the replaced frame instead of keeping the twisted propagated one.
+    /// Bone flag 0x04 (the HandArrow/Bullet helpers): the pivot rides the parent, the rotation
+    /// resets to the host root's, and a rigid child (the nocked arrow) re-composes onto it.
     #[test]
     fn ignore_parent_rotation_joint_keeps_the_model_frame() {
         let mut app = App::new();
@@ -1294,7 +1030,7 @@ mod tests {
             crate::view::WorldCamera,
             GlobalTransform::from(Transform::from_translation(Vec3::new(0.0, 0.0, 10.0))),
         ));
-        // The host root: yawed 90° — the model frame every flag-0x04 joint must land on.
+        // The host root, yawed 90°: the frame every flag-0x04 joint lands on.
         let host_rot = Quat::from_rotation_y(std::f32::consts::FRAC_PI_2);
         let host = app
             .world_mut()
@@ -1303,8 +1039,7 @@ mod tests {
                 GlobalTransform::from(Transform::from_rotation(host_rot)),
             ))
             .id();
-        // Joint 0: the animated hand — twisted a further 90° about X (the draw-hand roll the
-        // arrow must NOT inherit), pivot at (1, 2, 3).
+        // Joint 0: the animated hand, with a roll about X the arrow must not inherit.
         let hand_rot = host_rot * Quat::from_rotation_x(std::f32::consts::FRAC_PI_2);
         let j0_global = GlobalTransform::from(Transform {
             translation: Vec3::new(1.0, 2.0, 3.0),
@@ -1312,14 +1047,13 @@ mod tests {
             scale: Vec3::ONE,
         });
         let j0 = app.world_mut().spawn((Transform::IDENTITY, j0_global)).id();
-        // Joint 1: the flag-0x04 attach helper, one local unit up the HAND's frame.
+        // Joint 1: the flag-0x04 attach helper, one local unit up the hand's frame.
         let j1_local = Transform::from_translation(Vec3::Y);
         let j1 = app
             .world_mut()
             .spawn((j1_local, j0_global.mul_transform(j1_local)))
             .id();
-        // The rigid arrow child under the helper, at a local offset — propagated PRE-pass with
-        // the twisted frame (what the bug rendered).
+        // The rigid arrow under the helper, propagated before the pass with the twisted frame.
         let arrow_local = Transform::from_translation(Vec3::X);
         let arrow = app
             .world_mut()
@@ -1355,8 +1089,6 @@ mod tests {
         app.world_mut().spawn(rig);
         app.update();
 
-        // The helper joint: pivot carried by the HAND's frame (hand rot · Y above the hand),
-        // rotation snapped back to the HOST's.
         let (_, r1, t1) = app
             .world()
             .entity(j1)
@@ -1372,7 +1104,6 @@ mod tests {
             r1.angle_between(host_rot) < 1e-3,
             "the rotation resets to the model root's frame"
         );
-        // The arrow child re-composed onto the replaced frame: host-frame X off the pivot.
         let (_, ra, ta) = app
             .world()
             .entity(arrow)
@@ -1389,13 +1120,8 @@ mod tests {
         );
     }
 
-    /// A rigged model nested under another rig's rewritten joint (the Eviscerate impact instance
-    /// on the boar's flag-0x04 attach helper): the outer rig's child walk must not enter the
-    /// nested rig's subtree AT ALL — the root keeps its propagated global (the live animated
-    /// attach-bone frame its emitters' attach rotation reads), and the interior belongs to the
-    /// nested rig's own pass. Both spawn orders must land on the identical result; pre-fix,
-    /// whichever rig iterated last won, so the effect's camera-born billboard frame (and its
-    /// animated attach frame) survived or died per launch.
+    /// A rig nested under another's rewritten joint (a spell impact on an attach helper) keeps its
+    /// root's propagated frame and its own billboard, in either spawn order.
     #[test]
     fn nested_rig_interior_is_owned_by_its_own_pass() {
         for nested_first in [false, true] {
@@ -1405,8 +1131,8 @@ mod tests {
                 crate::view::WorldCamera,
                 GlobalTransform::from(Transform::from_translation(Vec3::new(0.0, 0.0, 10.0))),
             ));
-            // The outer host (a boar): yawed 90°, one flag-0x04 attach-helper joint whose
-            // propagated global carries an animated twist the reset must erase.
+            // The outer host: yawed 90°, one flag-0x04 attach helper whose propagated global
+            // carries an animated twist the reset erases.
             let host_rot = Quat::from_rotation_y(std::f32::consts::FRAC_PI_2);
             let host = app
                 .world_mut()
@@ -1434,9 +1160,8 @@ mod tests {
                 spine_bone: None,
                 head_bone: None,
             };
-            // The nested effect instance: its root hangs one local X under the helper, and its
-            // single joint is a lock-Z billboard whose propagated global still carries the
-            // (wrong) host twist — its own pass must replace it, and keep it replaced.
+            // The nested effect: its root one local X under the helper, its one joint a spherical
+            // billboard whose propagated global still carries the host twist.
             let fx_local = Transform::from_translation(Vec3::X);
             let fx_root = app
                 .world_mut()
@@ -1469,8 +1194,6 @@ mod tests {
             }
             app.update();
 
-            // The nested root keeps its PROPAGATED global — the animated attach-bone frame
-            // (with the hand twist): the walk never entered the nested subtree.
             let expected = j0_global.mul_transform(fx_local);
             let (_, rr, rt) = app
                 .world()
@@ -1487,18 +1210,14 @@ mod tests {
                 rr.angle_between(er) < 1e-3,
                 "nested root keeps the animated attach rotation (nested_first={nested_first})"
             );
-            // The nested rig's own billboard frame SURVIVES, in either spawn order: the outer
-            // walk stopped at the nested root instead of re-composing fj0 from its raw local.
             let (_, rj, _) = app
                 .world()
                 .entity(fj0)
                 .get::<GlobalTransform>()
                 .unwrap()
                 .to_scale_rotation_translation();
-            // The spherical basis at this camera, through the WoW→Bevy axis fold
-            // (`billboard_basis`'s `from_cols(-by, bz, -bx)`): Bevy-local −Z toward the viewer
-            // (WoW X), Bevy-local +Y screen-up (WoW Z) — the (π,0) ray ring's camera-born plane
-            // (wow-re part-billboard-ring-emulated.md).
+            // The spherical basis at this camera: Bevy-local −Z (WoW X) toward the viewer, +Y
+            // (WoW Z) screen-up, the camera-born plane at `0x71547c`.
             assert!(
                 (rj * -Vec3::Z).dot(Vec3::Z) > 0.999,
                 "the nested billboard faces the camera (nested_first={nested_first})"
@@ -1510,17 +1229,13 @@ mod tests {
         }
     }
 
-    /// An armed first-sequence translation loop (the questgiver `?` bob) moves the card off its
-    /// pivot by the sampled offset, on the arm-time cursor: armed at t=0, sampled at the loop's
-    /// midpoint, the card sits at the middle key's offset. No `Time` plugin — the clock is set by
-    /// hand so the sample point is exact.
+    /// Armed at t=0 and sampled at the loop's midpoint, the card sits at the middle key's offset.
     #[test]
     fn armed_seq_translation_bobs_the_card() {
         let mut app = App::new();
         app.init_resource::<Time>();
         app.add_systems(Update, face_billboards);
-        // A camera straight ahead of the card's rest normal: the facing rotation is identity, so
-        // the transform isolates the bob.
+        // A camera straight ahead: the facing rotation is identity, isolating the bob.
         app.world_mut().spawn((
             crate::view::WorldCamera,
             GlobalTransform::from_translation(Vec3::new(0.0, 0.0, 10.0)),
diff --git a/crates/benilla-world/src/boot.rs b/crates/benilla-world/src/boot.rs
index e7ee1843..b727ecb9 100644
--- a/crates/benilla-world/src/boot.rs
+++ b/crates/benilla-world/src/boot.rs
@@ -1,14 +1,5 @@
-//! The **tuned Bevy boot** — the `DefaultPlugins` set every benilla binary stands on.
-//!
-//! Extracted from `benilla_app::run` the moment there was a second binary to boot ([`crate::worldview`],
-//! decision 1160): the window differs per binary, but the *engine* tuning — the asset root, the log
-//! filter, the task-pool sizing and QoS, and the disabled audio plugin — must not. Each of those
-//! four is load-bearing and each was learned the hard way; a second boot that quietly re-derived
-//! them would be a second place for them to rot.
-//!
-//! The `Window` stays the caller's, because that is genuinely per-binary: the client's is shaped by
-//! the capture harness and the background-run rules (decisions 0703/0709/1148), the world viewer's
-//! is a plain window.
+//! The tuned Bevy boot: the `DefaultPlugins` set every benilla binary stands on. The engine tuning
+//! is shared; the `Window` is the caller's.
 
 use bevy::app::{PluginGroupBuilder, TaskPoolOptions, TaskPoolPlugin};
 use bevy::prelude::*;
@@ -22,36 +13,18 @@ pub fn tuned_default_plugins(primary_window: Window) -> PluginGroupBuilder {
             primary_window: Some(primary_window),
             ..default()
         })
-        // NOTE: there is deliberately no `AssetPlugin::file_path` here (decision 1175). This used
-        // to bake `concat!(env!("CARGO_MANIFEST_DIR"), "/assets")` — the *build* machine's source
-        // tree — because a shim package builds the binary and Bevy's runtime `CARGO_MANIFEST_DIR`
-        // fallback would otherwise resolve `assets/` in the shim's dir (0993). It worked on the
-        // machine that compiled it and nowhere else: on a player's machine every shader resolved
-        // to nothing and the world drew bare, the "silently-no-shaders trap" `capture/mod.rs`'s
-        // header names. Every WGSL file in the tree is now compiled into the binary
-        // (`crate::shaders`, `benilla_app::shaders`, `benilla_assets::materials`) and addressed
-        // `embedded://<crate>/shaders/…`, so nothing reaches for a file root at all and 1171's
-        // engine/game line survives as the crate each shader is embedded from.
-        // Quiet wgpu/naga; our own crates stay at info. The ring keeps the last lines of what
-        // stderr shows for the crash report (`log_ring`; decision 2266 §B2).
+        // Deliberately no `AssetPlugin::file_path`: a baked source path resolves only on the build
+        // machine. Every shader is embedded (`embedded://<crate>/shaders/…`), so no root is read.
+        // Quiet wgpu/naga; the ring keeps the last stderr lines for the crash report (`log_ring`).
         .set(bevy::log::LogPlugin {
             filter: "wgpu=error,naga=warn".into(),
             custom_layer: |_| Some(Box::new(crate::log_ring::LogRing)),
             ..default()
         })
-        // Asset streaming is this client's load bottleneck: every M2/WMO/BLP read decompresses from
-        // MPQ and parses **synchronously** on Bevy's IO task pool, and the AssetServer runs *all*
-        // loads there. Bevy's default caps that pool at 4 threads, so a teleport into a dense area —
-        // terrain + WMOs + their doodad props, all bursting at once — saturates it and the
-        // net-driven NPC/GameObject models queue behind the flood. Give IO more of the box (it sits
-        // idle when not streaming); the world-render path is GPU/IO-bound, not compute-bound, so
-        // trading some compute threads for streaming throughput is the right call.
-        // Thread QoS (decision 0609): Bevy's workers spawn at default QoS — the same Darwin
-        // scheduling class as rustc or an OBS encoder — so under a background build the frame's own
-        // threads queue behind the compiler for P-core time. Promote them at spawn: compute runs
-        // this frame's systems (user-interactive); IO/async-compute feed upcoming frames
-        // (user-initiated — above default, below the frame itself). The render thread has no spawn
-        // hook; `ThreadQosPlugin` promotes it from inside.
+        // Asset loads parse synchronously on the IO pool, and Bevy's default 4 threads saturate on
+        // a dense teleport. Workers spawn at default QoS, behind any background build:
+        // compute is user-interactive, IO and async compute user-initiated, and
+        // `ThreadQosPlugin` promotes the render thread from inside.
         .set(TaskPoolPlugin {
             task_pool_options: TaskPoolOptions {
                 io: bevy::app::TaskPoolThreadAssignmentPolicy {
@@ -73,12 +46,8 @@ pub fn tuned_default_plugins(primary_window: Window) -> PluginGroupBuilder {
                     on_thread_spawn: Some(std::sync::Arc::new(|| {
                         thread_qos::promote_current_thread(thread_qos::QosClass::UserInteractive)
                     })),
-                    // `WOW_THREADS=1` serialises the systems that run this frame. Not a performance
-                    // dial — a **diagnostic**: a defect that alternates frame to frame with no
-                    // camera, geometry or draw-order change behind it is what an unordered write
-                    // between two systems looks like, and that is separable from every other cause
-                    // only by taking the concurrency away. Anything that survives `WOW_THREADS=1`
-                    // is not a race.
+                    // `WOW_THREADS=1` serialises the frame's systems, a diagnostic: a defect that
+                    // survives it is not a race between two systems.
                     max_threads: match std::env::var("WOW_THREADS").ok().as_deref() {
                         Some("1") => 1,
                         _ => TaskPoolOptions::default().compute.max_threads,
@@ -88,31 +57,16 @@ pub fn tuned_default_plugins(primary_window: Window) -> PluginGroupBuilder {
                 ..default()
             },
         })
-        // Sound is kira behind our own mixer seam (decision 0070). Bevy's `AudioPlugin` used to be
-        // disabled here (0530) so it would not open a second, never-used OS output stream — but
-        // the crate behind it was still compiled and linked. Since 1932 `bevy_audio` is off at the
-        // feature level, so there is no plugin to disable and no rodio/cpal/vorbis stack in the
-        // binary; the feature list that keeps it out is in the workspace `Cargo.toml`.
-        // The dead registrations (decision 1438): DefaultPlugins members whose only runtime
-        // trace here was per-frame machinery for types nothing instantiates — every registered
-        // asset/material type costs an `Assets<T>` event system in PostUpdate plus
-        // extract/prepare/sweep families in the render app, priced by the 1437 census against
-        // the 1435 band map. Each cut was usage-grepped NEGATIVE and then proven by a clean
-        // boot, and the boot vetoed two of the five candidates the greps had passed (its
-        // missing-resource panic names the dependent): gizmos are the bowstring/fishing-line
-        // renderer (0938, warmed through a bare-`Gizmos` param no `Gizmos<` pattern sees), and
-        // the sprite pair carries our OWN FrameXML quad pass — `UiQuadMaterial` is a
-        // `Material2d` riding `Mesh2dPipeline`. What else stays, stays for a reason:
-        // bevy_picking drives the world-interact lane, TextPlugin draws the glue-screen text,
-        // PostProcessPlugin is the EffectGlow bloom, and two members are pinned by upstream
-        // exactly like 1437's Render-MT — ScenePlugin (avian's collider backend reads
-        // `SceneSpawner` even in a meshless world; our own harness tests document it) and
-        // PbrPlugin's ForwardDecal family (registered inside PbrPlugin::build).
+        // Sound is kira behind our own mixer; `bevy_audio` is off by feature (workspace
+        // `Cargo.toml`). Kept though they look idle: gizmos (bowstring, fishing line), sprites (the
+        // FrameXML quad pass), picking, TextPlugin (glue text), PostProcessPlugin (glow bloom) and
+        // ScenePlugin (avian's collider backend reads `SceneSpawner`); the ForwardDecal family is
+        // registered inside `PbrPlugin::build`, so it cannot be disabled on its own.
         //
-        // We load M2/WMO/ADT through our own mpq:// loaders — no glTF anywhere.
+        // M2/WMO/ADT load through our own `mpq://` loaders; there is no glTF.
         .disable::<bevy::gltf::GltfPlugin>()
         // No bevy AA: no Fxaa/TAA/SMAA/CAS component anywhere (MSAA is core render, unaffected).
         .disable::<bevy::anti_alias::AntiAliasPlugin>()
-        // No gamepad input; 1.12's bindings are keyboard/mouse (0997).
+        // No gamepad input; 1.12's bindings are keyboard/mouse.
         .disable::<bevy::gilrs::GilrsPlugin>()
 }
diff --git a/crates/benilla-world/src/build_id.rs b/crates/benilla-world/src/build_id.rs
index 28e4df01..1773634f 100644
--- a/crates/benilla-world/src/build_id.rs
+++ b/crates/benilla-world/src/build_id.rs
@@ -1,48 +1,25 @@
-//! **Which build is this?** — the commit the running binary was built from, stamped in at
-//! compile time by the `benilla` launcher shim's `build.rs` (which owns the *how*, including why
-//! the stamp can't go stale — and why it is stamped into the ~30-line shim rather than this
-//! crate: cargo re-dirties whatever package carries the stamp on every commit, decision 0993)
-//! and handed to [`crate::run`] as the [`BuildId`] resource.
-//!
-//! A report from someone else's machine — "the water reads wrong here", "it panicked on login" —
-//! is only actionable against known code, and nothing else in the binary identifies it: the crate
-//! version is a permanent `0.1.0`, and people build from a clone of the public snapshot repo whose
-//! HEAD moves with every sync. So the sha is the version.
-//!
-//! Two surfaces, deliberately:
-//!
-//! - **The startup log line** ([`banner`], run from [`crate::preflight`]'s banner family) — this is
-//!   the one that matters for someone else's run. They launch from a terminal, so the id is already
-//!   in the output they paste; nobody has to know a hotkey to answer "what are you on?".
-//! - **The debug panel's footer** (`` ` ``) — the same line where the reader already is when they
-//!   are looking at a readout, click-to-copy for the full sha.
-//!
-//! Mapping a reported sha back: a **public** snapshot sha is tagged `pub/<short-sha>` on the private
-//! commit it shipped, so `git show pub/<sha>` (or `git rev-parse pub/<sha>^{commit}`) names the code
-//! exactly; a **private** sha is just a commit here.
+//! Which build is running: the commit the binary was built from, stamped at compile time by the
+//! launcher shims' build script (`benilla-buildstamp`) and passed to `run` as the [`BuildId`]
+//! resource. It shows in the startup log line ([`banner`]) and in the debug panel's footer.
 
 use bevy::prelude::*;
 
-/// The launcher shim's compile-time git stamp, inserted as a resource by [`crate::run`]. The git
-/// fields are empty when the build had no checkout to read (a downloaded source zip, or no `git`
-/// on `PATH`), which [`BuildId::summary`] reports as an unknown build.
+/// The launcher shim's compile-time git stamp. The git fields are empty when the build had no
+/// checkout or no `git` on `PATH`, which [`BuildId::summary`] reports as an unknown build.
 #[derive(Resource, Clone, Copy)]
 pub struct BuildId {
-    /// The full 40-char sha of the commit this binary was built from (what the panel copies).
+    /// The full sha, which the debug panel copies.
     pub sha: &'static str,
-    /// Git's own abbreviation of [`sha`](Self::sha), from the same repo `pubsync` abbreviates in —
-    /// so a public build's string is literally the suffix of its `pub/<sha>` tag.
+    /// Git's own abbreviation of [`sha`](Self::sha).
     pub short: &'static str,
-    /// The commit date of [`sha`](Self::sha) (`YYYY-MM-DD`) — a property of the sha, so it can
-    /// never disagree with it.
+    /// The commit date of [`sha`](Self::sha) (`YYYY-MM-DD`), not the build date.
     pub date: &'static str,
-    /// The cargo profile directory this was built in: `debug`, `release`, or `ship` (0736). Half
-    /// of every "it runs badly" report is a debug build.
+    /// The cargo profile directory: `debug`, `release` or `ship`.
     pub profile: &'static str,
 }
 
 impl BuildId {
-    /// The one-line build id: `f5fd009 · 2026-07-30 · release`.
+    /// The one-line build id: short sha, commit date and profile.
     pub fn summary(&self) -> String {
         if self.short.is_empty() {
             format!("unknown (built without a git checkout) · {}", self.profile)
@@ -52,9 +29,7 @@ impl BuildId {
     }
 }
 
-/// Log the build id once at startup — the line that answers "what version are you on?" from a
-/// pasted terminal log. Not env-gated, for [`crate::preflight`]'s reason: an id nobody knows to
-/// switch on is not an id.
+/// Log the build id once at startup, not env-gated, so every pasted log carries it.
 pub fn banner(build: Res<BuildId>) {
     info!("benilla build {}", build.summary());
 }
diff --git a/crates/benilla-world/src/clouds/kernel.rs b/crates/benilla-world/src/clouds/kernel.rs
index 5dad7f8b..6bb8924d 100644
--- a/crates/benilla-world/src/clouds/kernel.rs
+++ b/crates/benilla-world/src/clouds/kernel.rs
@@ -1,52 +1,20 @@
-//! The cloud coverage kernel — a faithful port of the reference's procedural cloud field.
-//!
-//! The real client maintains a scrolling 128×128 byte tile of cloud coverage (the SkyManager
-//! working-set `0xce98e8`), regenerated in 32-row bands at ~10 Hz by `cloud_coverage_noise`
-//! (`WoW.exe 0x6cffc0`, transcribed bit-exact in wow-re `crates/lighting/src/clouds.rs`): 4-octave
-//! toroidal value noise (lacunarity 2, persistence 0.5) → `rawByte`, thresholded by the authored
-//! Light.dbc cloud density `C` (`T = trunc((1−C)·255)`, `0x6d0970`) and shaped through a fixed
-//! 256-byte tone curve (`0x6d0900`, gamma 0.96 — frozen here as [`CURVE`]). One field serves every
-//! consumer: the glare occlusion `occ1` samples the same tile the visible layer renders from
-//! (wow-re `scratch/cloud-coverage-pipeline.md`, §5-verified).
-//!
-//! The noise lattice is keyed by three axes: tile row (`row_key`, advancing `freq` per row), tile
-//! column (`col_key`, advancing `freq` per column), and time (the u16 `phase`, bumped once per full
-//! tile wrap ≈ 0.4 s — its high byte picks the permutation slice pair, its low byte the fade
-//! weight between them). High key bytes select lattice cells through the permutation table; low
-//! bytes index the raised-cosine [`fade`] table as interpolation weights. Band regeneration at an
-//! unchanged `phase`/`T` is idempotent (keys derive from absolute tile coordinates), so the field
-//! only *moves* when the phase advances or the authored density changes — exactly the reference's
-//! slow cloud drift.
-//!
-//! Each regen fire ends with the **color pass** (`0x6cfb00`, wow-re `dn_sky_vtx.rs` — diffed
-//! bit-exact): the coverage bytes become RGBA texels (gradient + sun-aligned glow, alpha = the
-//! coverage byte), and *that image* is what the dome uploads — the reference binds its color
-//! buffer zero-copy to the gx texture (Addendum A §3). The glow's per-cell surface normal comes
-//! from the octave-2 derivative leg (`[cfg+0x68]`, Addendum A §4).
-//!
-//! Deviations from the bytes, all in never-hit or non-visual domains (recorded in the decision
-//! record): the `acos` argument is clamped to ±1 (the reference NaNs above ~70° elevation, a
-//! domain its sun/moon never reach); LUT reads wrap toroidally instead of running off the flat
-//! heap at the measure-zero `u == 1.0` edge; the gradient table uses the reference's MSVC-LCG
-//! *formula* with a fixed seed (the reference seed is process-random and not visually
-//! load-bearing — any 256 uniform values in [−1, 1] are equivalent, wow-re pipeline note §1b);
-//! and the color buffer seeds alpha-0 instead of `0xFFFFFFFF` (no white flash before the first
-//! build).
+//! The reference's procedural cloud field (`0xce98e8`): a scrolling 128×128 byte tile of 4-octave
+//! toroidal value noise, thresholded by the Light.dbc cloud density, shaped by a fixed tone curve
+//! (`0x6d0900`) and colored into the texels the dome draws. The glare samples the same tile.
 
 use bevy::math::Vec3;
 
 use super::tables::{fade_table, gradient_table, CURVE, PERM};
 
-/// Tile side at `SkyCloudLOD 0` (`cols = 128 << LOD`; the CVar clamps to [0,1] and defaults to 0 —
-/// wow-re pipeline §3d). We implement LOD 0.
+/// Tile side at `SkyCloudLOD` 0, its default (`128 << LOD`, `0x6d1d60`); only LOD 0 is built.
 pub const COLS: usize = 128;
-/// `log2(COLS)` — the row-pitch shift the sampler uses (`[cfg+0x20]`).
+/// `log2(COLS)`, the sampler's row-pitch shift (`[cfg+0x20]`).
 pub const SHIFT: u32 = 7;
-/// Rows regenerated per fire (`[cfg+0x14]`, default 32).
+/// Rows regenerated per fire (`[cfg+0x14]`).
 pub const ROWS_PER_TICK: usize = 32;
-/// Octave count (`[cfg+0x28]`, constant 4).
+/// Octaves (`[cfg+0x28]`).
 pub const OCTAVES: usize = 4;
-/// Regen countdown reset (`0x8115b4` = 0.1 s) — the ~10 Hz cadence.
+/// Regen countdown reset in seconds (`0x8115b4`): a 10 Hz cadence.
 pub const REGEN_PERIOD: f32 = 0.1;
 /// Per-octave lattice frequencies, LOD 0 row of the base table `0x86f3dc` (`(16 >> LOD) << oct`).
 const BASE_FREQ: [u16; OCTAVES] = [16, 32, 64, 128];
@@ -56,26 +24,18 @@ fn perm(i: u32) -> u32 {
     u32::from(PERM[(i & 0xff) as usize])
 }
 
-/// Per-octave lattice walk state — the 0x54-byte stack record of `0x6cffc0`, kept as named fields.
+/// Per-octave lattice walk state: `0x6cffc0`'s 0x54-byte stack record as named fields.
 struct Octave {
-    /// Lattice frequency (`base_table[LOD·5 + oct]`; the record's `B+8`/`B+0xa` key delta).
     freq: u16,
-    /// Row axis key (`B+4`): starts at `scroll·freq`, advances `freq` per row. High byte = row
-    /// lattice cell, low byte = row fade index.
+    /// Row key (`B+4`), from `scroll·freq`, `+freq` per row: high byte the cell, low byte the fade.
     row_key: u16,
-    /// Column axis key (`B+2`): re-seeded to `phase` each row, advances `freq` per column. High
-    /// byte = column lattice cell (`uVar14`), low byte = column fade index.
     col_key: u16,
-    /// Octave amplitude `1 / 2^oct` (`B+0x1a`).
     amp: f32,
-    /// Per-row lattice corner seeds (`B+0x1e..0x2a`): row cell hashed through the phase-selected
-    /// permutation slices (`x*` = current time slice, `y*` = next).
+    /// Row corner seeds (`B+0x1e..0x2a`): `x*` through the current time slice, `y*` the next.
     x0: u32,
     x1: u32,
     y0: u32,
     y1: u32,
-    /// Cached corner gradients + deltas for the current column cell (`B+0x2e..0x4a`), rebuilt
-    /// lazily when the column cell changes (`B+0x4c` cache key).
     g00: f32,
     g00d: f32,
     g10: f32,
@@ -87,37 +47,27 @@ struct Octave {
     cached: u32,
 }
 
-/// The cloud coverage field: the byte tile, the colored texture, and the regen state.
+/// The cloud coverage field: the byte tile, its colored texels and the regen state.
 pub struct CloudKernel {
-    /// The coverage byte tile (`[cfg+0x44]`), `COLS²` row-major. `byte/255 = R ∈ [0,1]`.
+    /// Coverage bytes (`[cfg+0x44]`), `COLS²` row-major; `byte/255` is the coverage `R`.
     tile: Vec<u8>,
-    /// The float accumulation tile (`[cfg+0x50]`).
     accum: Vec<f32>,
-    /// The per-cell shape derivative pairs (`[cfg+0x68]`, 2 f32/cell) — written by the octave-2
-    /// leg, consumed by the color pass as the glow surface normal `S = (dx, dy, 1)`
-    /// (Addendum A §4).
+    /// Per-cell slopes from the octave-2 leg (`[cfg+0x68]`), the glow normal `(dx, dy, 1)`.
     deriv: Vec<[f32; 2]>,
-    /// The previous-row scratch (`[cfg+0x5c]`, `COLS` f32) feeding the row derivative.
     prevrow: Vec<f32>,
-    /// The colored RGBA texels (`[cfg+0x38]`, 4 B/cell: gradient+glow RGB, alpha = the coverage
-    /// byte) — **this is what the reference uploads** (`0x58ac70` binds `[cfg+0x38]` zero-copy;
-    /// Addendum A §3 — corrects the earlier "coverage bytes uploaded" reading).
+    /// Colored texels (`[cfg+0x38]`), the buffer the reference binds as its texture (`0x58ac70`).
     rgba: Vec<[u8; 4]>,
-    /// Scroll position — the tile row the next band starts at (`[cfg+0x18]`).
+    /// The tile row the next band starts at (`[cfg+0x18]`).
     scroll: usize,
-    /// Noise-space phase (`[cfg+0xa0]`, u16) — +1 per full tile wrap; the time axis.
+    /// The noise's time axis (`[cfg+0xa0]`), +1 per full tile wrap.
     phase: u16,
     /// Regen countdown (`[cfg+0xb0]`); starts expired so the first tick fires.
     countdown: f32,
-    /// The gradient table (`0xce92d8`) — 256 × f32 in [−1, 1], built once (see [`gradient_table`]).
     gradient: [f32; 256],
-    /// The fade table (`0xce8dd8`) — `0.5·(1 − cos(iπ/256))`, built once.
     fade: [f32; 256],
 }
 
-/// Per-fire inputs to the color pass — `0x6cfb00`'s per-frame setup, resolved by the caller from
-/// [`crate::lighting::WowLighting`]: the three Light.dbc cloud palette rows, the weather blend,
-/// and the glow body (sun by day / moon by night, with its 8-key day envelope).
+/// The color pass inputs (`0x6cfb00`'s per-frame setup), from [`crate::lighting::WowLighting`].
 #[derive(Clone, Copy, PartialEq)]
 pub struct CloudFrame {
     /// Sun-glow palette (IntBand sub-10), sRGB 0..1.
@@ -126,12 +76,11 @@ pub struct CloudFrame {
     pub(crate) slope: [f32; 3],
     /// Gradient base (IntBand sub-12).
     pub(crate) gbase: [f32; 3],
-    /// The weather storm blend `bcc` — feeds the glow z-bias (`bcc·192 + 64`) and the dim
-    /// (`1 − 0.75·bcc`).
+    /// The weather storm blend, which sets the glow's z-bias and dim.
     pub(crate) bcc: f32,
-    /// Camera→body direction of the glow body (Bevy frame).
+    /// Camera→glow body direction (Bevy frame): the sun by day, the moon by night.
     pub(crate) glow_dir: Vec3,
-    /// The glow day-envelope factor (`0xce9ab8` track — `daynight::cloud_glow_track`).
+    /// The glow's day envelope, the reference's static track at `0xce9ab8`.
     pub(crate) glow_track: f32,
 }
 
@@ -142,8 +91,8 @@ impl Default for CloudKernel {
             accum: vec![0.0; COLS * COLS],
             deriv: vec![[0.0; 2]; COLS * COLS],
             prevrow: vec![0.0; COLS],
-            // The reference inits the color buffer 0xFFFFFFFF; we keep alpha 0 until the first
-            // build so an unprimed dome can never flash white (cosmetic-only deviation).
+            // Deviation: the reference starts this buffer at 0xFFFFFFFF; alpha 0 keeps a dome
+            // drawn before the first build from flashing white.
             rgba: vec![[255, 255, 255, 0]; COLS * COLS],
             scroll: 0,
             phase: 0,
@@ -155,9 +104,7 @@ impl Default for CloudKernel {
 }
 
 impl CloudKernel {
-    /// Advance the countdown and regenerate one 32-row band when it expires (`0x6cffc0`'s
-    /// self-throttle: fire when the decremented countdown ≤ 0, reset to 0.1). Returns whether the
-    /// tile changed.
+    /// Regenerates one band when the countdown runs out (`0x6cffc0`); true if the tile changed.
     pub fn tick(&mut self, dt: f32, density: f32, frame: &CloudFrame) -> bool {
         self.countdown -= dt;
         if self.countdown > 0.0 {
@@ -168,33 +115,28 @@ impl CloudKernel {
         true
     }
 
-    /// Full-tile rebuild (`0x6cff90`): regenerate every row at once — the reference runs this on
-    /// discontinuities (init / zone / LOD change) by forcing the row count to `cols`.
+    /// Regenerates every row (`0x6cff90`), as the reference does on init, zone and LOD changes.
     pub fn rebuild(&mut self, density: f32, frame: &CloudFrame) {
         self.scroll = 0;
         self.regen(density, COLS, frame);
         self.countdown = REGEN_PERIOD;
     }
 
-    /// Re-run the color pass over the whole tile without touching the coverage — the frozen
-    /// capture clock's path when only the palette/sun/weather inputs moved.
+    /// Re-runs the color pass over the whole tile without touching coverage, for the frozen clock.
     pub fn recolor(&mut self, frame: &CloudFrame) {
         self.color_band(0, COLS, frame);
     }
 
-    /// One regeneration fire: `rows` tile rows starting at `self.scroll` (noise + quantize +
-    /// the color pass, the reference's `0x6cffc0` → `0x6cfb00` order), then the scroll/phase
-    /// advance. The body is the `0x6cffc0` transcription (wow-re `clouds.rs`) in named-field form.
+    /// One fire of `0x6cffc0`: noise, quantize and color `rows` rows from `scroll`, then advance.
     fn regen(&mut self, density: f32, rows: usize, frame: &CloudFrame) {
-        // Threshold refresh (`0x6d0970`, called at the top of every fire): T = trunc((1−C)·255).
-        // The reference does not clamp C; authored bands stay in [0,1] and we clamp for safety.
+        // Threshold (`0x6d0970`): the reference does not clamp; authored densities stay in [0, 1].
         let threshold = ((1.0 - density.clamp(0.0, 1.0)) * 255.0) as i32;
 
-        // Phase-selected permutation slice pair: the time axis. `seed` = phase HIGH byte.
+        // The time axis: the phase's high byte picks the permutation slice pair.
         let seed = u32::from(self.phase >> 8);
-        let slice_a = perm(seed); // local_18 — current time slice
-        let slice_b = perm(seed + 1); // local_1c — next time slice
-        let fade_t = f64::from(self.fade[(self.phase & 0xff) as usize]); // f_b — time fraction
+        let slice_a = perm(seed); // current time slice
+        let slice_b = perm(seed + 1); // next time slice
+        let fade_t = f64::from(self.fade[(self.phase & 0xff) as usize]); // time fraction
 
         let scroll = self.scroll;
         let mut oct: Vec<Octave> = (0..OCTAVES)
@@ -202,8 +144,7 @@ impl CloudKernel {
                 let freq = BASE_FREQ[c];
                 Octave {
                     freq,
-                    // B+4 init: `(u16)(tile_x · key)` — absolute-row keyed, which is what makes
-                    // band regeneration idempotent at a fixed phase.
+                    // Keyed by the absolute row, so a band regenerates identically at one phase.
                     row_key: (scroll as u32).wrapping_mul(u32::from(freq)) as u16,
                     col_key: 0,
                     amp: 1.0 / (1u32 << c) as f32,
@@ -224,15 +165,12 @@ impl CloudKernel {
             })
             .collect();
 
-        // Float-tile zero-clear over the band.
         for v in &mut self.accum[scroll * COLS..(scroll + rows).min(COLS) * COLS] {
             *v = 0.0;
         }
 
         for row in 0..rows {
             let base = (scroll + row) * COLS;
-            // Per-row lattice setup: hash the row cell (row_key high byte) through the two time
-            // slices; re-seed the column walk from the phase; invalidate the corner cache.
             for o in oct.iter_mut() {
                 let bv = u32::from(o.row_key >> 8);
                 o.x0 = perm(slice_a + bv);
@@ -242,14 +180,13 @@ impl CloudKernel {
                 o.col_key = self.phase;
                 o.cached = u32::MAX;
             }
-            // fVar4 — the previous column's third-octave partial sum (reset per row: the
-            // `fld 0.0` before the column loop).
+            // The previous column's three-octave partial sum, reset per row.
             let mut prev_accum = 0.0f32;
             for col in 0..COLS {
                 let cell = base + col;
                 for (oi, o) in oct.iter_mut().enumerate() {
-                    let fade_row = f64::from(self.fade[(o.row_key & 0xff) as usize]); // f_a
-                    let cz = u32::from(o.col_key >> 8); // uVar14 — column lattice cell
+                    let fade_row = f64::from(self.fade[(o.row_key & 0xff) as usize]);
+                    let cz = u32::from(o.col_key >> 8); // column lattice cell
                     if cz != o.cached {
                         o.cached = cz;
                         let g = |s: u32| self.gradient[perm(s) as usize];
@@ -263,8 +200,7 @@ impl CloudKernel {
                         o.g11 = g(s3);
                         o.g11d = g(s3 + 1) - o.g11;
                     }
-                    // The fade-interpolated bilinear + time lerp, mirroring the binary's f64
-                    // in-register chain with its one f32 round-trip (`v8`).
+                    // The reference's f64 chain, with its one f32 round trip (`v8`).
                     let fx = f64::from(self.fade[(o.col_key & 0xff) as usize]);
                     let v7 = fx * f64::from(o.g00d) + f64::from(o.g00);
                     let v8 = f64::from((fx * f64::from(o.g01d) + f64::from(o.g01)) as f32);
@@ -274,10 +210,7 @@ impl CloudKernel {
                     let acc = f64::from(self.accum[cell]);
                     let stored = (((v8b - v7b) * fade_t + v7b) * f64::from(o.amp) + acc) as f32;
                     self.accum[cell] = stored;
-                    // The octave-2 derivative leg (`0x6cffc0`, the `local_10 == 2` branch): the
-                    // column/row slopes of the three-octave partial sum, into the pair buffer the
-                    // color pass reads as the glow surface normal. `scale = 1 << (shift − 7)` — 1
-                    // at LOD 0.
+                    // Octave 2 stores the running sum's slopes: the color pass's glow normal.
                     if oi == 2 {
                         let scale = f64::from((1i32 << ((SHIFT - 7) & 0x1f)) as f32);
                         self.deriv[cell][0] =
@@ -289,24 +222,21 @@ impl CloudKernel {
                     }
                 }
             }
-            // Per-row key advance: walks the row axis one `freq` step.
             for o in oct.iter_mut() {
                 o.row_key = o.row_key.wrapping_add(o.freq);
             }
         }
 
-        // Palette-quantize the band into the byte tile: the binary's float-bits pack
-        // (`fmul 64; fadd 128; fadd 512; fstp` then bits `>> 14`), threshold, tone curve.
+        // Quantize by the reference's float-bits pack, then threshold and tone curve.
         for cell in scroll * COLS..(scroll + rows).min(COLS) * COLS {
             let q = ((f64::from(self.accum[cell]) * 64.0 + 128.0 + 512.0) as f32).to_bits();
             let idx = ((q >> 14) & 0xff) as i32 - threshold;
             self.tile[cell] = if idx >= 0 { CURVE[idx as usize] } else { 0 };
         }
 
-        // The color pass over the same band (`0x6cfb00`, called before the scroll advance).
+        // The color pass (`0x6cfb00`) runs before the scroll advance.
         self.color_band(scroll, rows, frame);
 
-        // Scroll advance with wrap: the wrap bumps the noise-space phase — the time axis moves.
         self.scroll += rows;
         if self.scroll >= COLS {
             self.phase = self.phase.wrapping_add(1);
@@ -314,20 +244,15 @@ impl CloudKernel {
         }
     }
 
-    /// The color pass — the exact `0x6cfb00` per-cell algorithm (wow-re `dn_sky_vtx.rs`, diffed
-    /// bit-exact; Addendum A §1): per cell `t` = the coverage byte — `t == 0` copies the previous
-    /// cell's RGB with alpha 0 (the filtering-friendly hole fill); else the gradient
-    /// `slope·p + gbase` with `p = (((255−t)>>1) + 64)/255`, plus the sun-aligned glow
-    /// `sun·(cosθ·intensity)` where `cosθ` aligns the cell→body vector (tile-cell units, z =
-    /// `bcc·192 + 64`) against the cell's shape normal `(dx, dy, 1)` through the binary's integer
-    /// fast-inverse-sqrt. Channels clamp at 1 and pack `floor(ch·255)`; alpha = `t`.
+    /// The color pass (`0x6cfb00`): a hole copies the previous cell's RGB at alpha 0; a covered
+    /// cell is a gradient in its coverage plus a glow by the angle to its slope normal.
     fn color_band(&mut self, start: usize, rows: usize, frame: &CloudFrame) {
         let f = f64::from;
         let z_bias = (f(frame.bcc) * 192.0 + 64.0) as f32;
         let intensity = (f(frame.glow_track) * (1.0 - f(frame.bcc) * 0.75)) as f32;
         let body = body_cells(frame.glow_dir);
         for row in start..(start + rows).min(COLS) {
-            let row_base = row as f32; // [ebp-0x84] = f18 + row — the absolute tile row
+            let row_base = row as f32; // the absolute tile row
             for col in 0..COLS {
                 let g = row * COLS + col;
                 let t = self.tile[g];
@@ -338,7 +263,7 @@ impl CloudKernel {
                     }
                     continue;
                 }
-                // The angle byte: n = (((255 − t) >> 1) + 0x40) & 0xff ∈ [64, 191].
+                // The angle byte, in [64, 191].
                 let n = u32::from((255u8.wrapping_sub(t) >> 1).wrapping_add(0x40));
                 let p = f(INV_255) * f64::from(n);
                 let mut ch = [
@@ -347,8 +272,7 @@ impl CloudKernel {
                     (f(frame.slope[2]) * p + f(frame.gbase[2])) as f32,
                 ];
                 if let Some((su, sv)) = body {
-                    // V = (Su − col, Sv − row, z_bias); S = (dx, dy, 1). Accumulation and
-                    // product order per the bytes (±1-ulp load-bearing in the diff).
+                    // The reference's sum and product order: a one-ulp change moves output bytes.
                     let vx = (f(su) - f64::from(col as u32)) as f32;
                     let vy = (f(sv) - f(row_base)) as f32;
                     let vz = z_bias;
@@ -374,26 +298,23 @@ impl CloudKernel {
         }
     }
 
-    /// Sample the coverage `R ∈ [0,1]` toward a camera-relative offset `d` (Bevy frame, +Y up) —
-    /// the reference's `FUN_006cfa90`: project onto the tile, read the byte. `d` is the
-    /// un-normalized body offset — the glare samples at its 12-unit sky point, so the zenith
-    /// shift contributes `cos45°/|d|`.
+    /// The coverage in [0, 1] toward camera-relative `d` (`0x6cfa90`). `d` is not normalized: the
+    /// glare samples at its 12-unit sky point, so the zenith shift weighs `cos45°/|d|`.
     pub fn coverage(&self, d: Vec3) -> f32 {
         let Some((u, v)) = project_cells(d) else {
             return f32::from(self.tile[(COLS / 2) * COLS + COLS / 2]) / 255.0;
         };
-        let (col, row) = (u as i32, v as i32); // _ftol
-                                               // Toroidal mask (the reference reads the flat heap unchecked; `u == 1.0` is measure-zero).
+        let (col, row) = (u as i32, v as i32);
+        // Deviation: the index wraps where the reference reads past the tile, only at `u == 1.0`.
         let cell = ((row as usize & (COLS - 1)) << SHIFT) + (col as usize & (COLS - 1));
         f32::from(self.tile[cell]) / 255.0
     }
 
-    /// The colored RGBA texels for the visible-layer texture upload (Addendum A §3).
+    /// The colored texels the visible layer uploads (`0x58ac70`).
     pub fn rgba(&self) -> &[[u8; 4]] {
         &self.rgba
     }
 
-    /// Raw coverage bytes (tests).
     #[cfg(test)]
     pub(crate) fn tile(&self) -> &[u8] {
         &self.tile
@@ -405,10 +326,8 @@ impl CloudKernel {
     }
 }
 
-/// The azimuthal tile projection (`FUN_006cf870`): camera-relative offset → fractional tile cell
-/// `(col, row)`. LUT centre = zenith, radius grows with the angle off a `+cos(π/4)`-shifted
-/// zenith axis, saturating at 45° (the rim; below-horizon directions clamp there). `None` for a
-/// degenerate zero offset.
+/// The azimuthal tile projection (`0x6cf870`): the zenith at the centre, the radius growing with
+/// the angle off a `+cos(π/4)`-shifted axis up to the 45° rim, where lower directions clamp.
 fn project_cells(d: Vec3) -> Option<(f32, f32)> {
     let len = f64::from(d.length());
     if len < 1e-6 {
@@ -416,8 +335,7 @@ fn project_cells(d: Vec3) -> Option<(f32, f32)> {
     }
     let quarter_pi = f64::from(std::f32::consts::FRAC_PI_4);
     let c = f64::from(d.y) + f64::from(std::f32::consts::FRAC_PI_4.cos());
-    // The reference feeds `c/len` to acos unclamped and NaNs above ~70° elevation — a domain
-    // its bodies never reach; we clamp (recorded deviation).
+    // Deviation: clamped; the reference NaNs above about 70° elevation, where its bodies never go.
     let theta = (c / len).clamp(-1.0, 1.0).acos();
     let phase = theta.min(quarter_pi) / quarter_pi * 0.5;
     let hyp = (f64::from(d.x) * f64::from(d.x) + f64::from(d.z) * f64::from(d.z)).sqrt();
@@ -436,17 +354,15 @@ fn project_cells(d: Vec3) -> Option<(f32, f32)> {
     ))
 }
 
-/// The glow body's tile cell (`0x6cfb00` setup, steps 1–2): intersect the camera→body ray with
-/// the unit sky dome (`sky_dome_ray_point 0x6cf9c0` — the `−cos(π/4)`-shifted sphere, larger
-/// quadratic root) and project the hit point onto the tile. `None` on the degenerate no-root /
-/// zero-direction case.
+/// The glow body's tile cell (`0x6cfb00` setup): the camera→body ray's far hit on the unit dome
+/// shifted by `−cos(π/4)` (`0x6cf9c0`), projected onto the tile.
 fn body_cells(dir: Vec3) -> Option<(f32, f32)> {
     let f = f64::from;
-    // k = −cos(0.25·π), the quarter-arc constant both functions open with.
+    // k = −cos(π/4), the dome's shift.
     let k = -(f(0.25f32) * f(std::f32::consts::PI)).cos();
     let a = (f(dir.x) * f(dir.x) + f(dir.y) * f(dir.y) + f(dir.z) * f(dir.z)) as f32;
     let b = {
-        // `fchs; fmul v.z; fadd st,st` — (−k·up) doubled (the reference's z-up ↔ our y-up).
+        // −k·up, doubled; the reference's up is z, ours is y.
         let nk = -k * f(dir.y);
         (nk + nk) as f32
     };
@@ -460,8 +376,7 @@ fn body_cells(dir: Vec3) -> Option<(f32, f32)> {
     project_cells(hit)
 }
 
-/// The cmath quadratic solver (`0x454f40`): larger root of `a·t² + b·t + c = 0`, Vieta-stable
-/// exactly as the binary rounds it; `None` on the no-root leg (`b² ≤ 4ac` or unordered).
+/// The larger root of `a·t² + b·t + c = 0`, rounded as the reference's solver does (`0x454f40`).
 fn quadratic_larger_root(a: f32, b: f32, c: f32) -> Option<f32> {
     let f = f64::from;
     let g = f(a) * f(c) * 4.0;
@@ -483,33 +398,26 @@ fn quadratic_larger_root(a: f32, b: f32, c: f32) -> Option<f32> {
     })
 }
 
-/// `1/255` as the binary stores it (`0x8026c8` = `0x3b808081`).
+/// `1/255` as the reference stores it (`0x8026c8`).
 const INV_255: f32 = f32::from_bits(0x3b80_8081);
 
-/// The binary's integer fast-inverse-sqrt leaf (`0x456330`): a one-shot seed, NO Newton step —
-/// deterministic bit-manipulation, so ported verbatim (the approximation error is part of the
-/// reference's glow shape).
+/// The reference's inverse-sqrt seed (`0x456330`), no Newton step: its error shapes the glow.
 fn fisr(x: f32) -> f32 {
     f32::from_bits(0x5f39_97bbu32.wrapping_sub((x.to_bits() >> 1) & 0x3fff_ffff))
 }
 
-/// Pack one color channel to a byte exactly as the binary does (`0x6cfef6..0x6cff44`): clamp
-/// `≤ 1.0` (no lower clamp), then the `bits(ch·255 + 512) >> 14` trick — `floor(ch·255)` after
-/// f32 rounding.
+/// Packs a channel as the reference does (`0x6cfef6..0x6cff44`): clamped above only, floored.
 fn pack_channel(ch: f64) -> u8 {
     let clamped = if ch < 1.0 { ch } else { 1.0 };
     (((clamped * 255.0 + 512.0) as f32).to_bits() >> 14) as u8
 }
 
-/// Sun glare cloud occlusion (`occ1_sun = 1 − R`, `0x6cf7b0`): a cloud over the sun dims the
-/// flare linearly with coverage.
+/// The sun glare's cloud occlusion (`0x6cf7b0`): the flare dims linearly with coverage.
 pub fn occ1_sun(r: f32) -> f32 {
     1.0 - r
 }
 
-/// Moon glare cloud occlusion — the tent `1 − |2(R − 0.5)|` (`0x6cf7d0`): zero at R=0 *and* R=1.
-/// The reference's moon halo is a thin-cloud effect — off in a perfectly clear patch of sky,
-/// blooming when a wisp crosses the moon.
+/// The moon glare's cloud occlusion (`0x6cf7d0`): a tent, so the halo blooms only in thin cloud.
 pub fn occ1_moon(r: f32) -> f32 {
     1.0 - (2.0 * (r - 0.5)).abs()
 }
@@ -518,8 +426,6 @@ pub fn occ1_moon(r: f32) -> f32 {
 mod tests {
     use super::*;
 
-    /// A daytime frame: mid-grey slope over a dark base, warm glow, clear weather, the sun high
-    /// in the +X sky at full envelope.
     fn frame() -> CloudFrame {
         CloudFrame {
             sun: [1.0, 0.78, 0.54],
@@ -531,9 +437,7 @@ mod tests {
         }
     }
 
-    /// Clear sky (C=0 ⇒ T=255): every cell quantizes below the threshold ⇒ R = 0 everywhere ⇒
-    /// occ1_sun = 1 (full flare), occ1_moon = 0 (no halo) — wow-re pipeline §1d. The colored
-    /// texels are all alpha 0 (the t==0 hole fill).
+    /// Density 0 puts the threshold at 255, so every cell quantizes to 0.
     #[test]
     fn clear_sky_is_empty_coverage() {
         let mut k = CloudKernel::default();
@@ -546,11 +450,7 @@ mod tests {
         assert_eq!(occ1_moon(0.0), 0.0);
     }
 
-    /// Full density (C=1 ⇒ T=0): every raw byte clears the threshold, so the whole sky reads as
-    /// heavy cover through the tone curve's high region — a storm's overcast field, not a
-    /// scattered one. Regeneration is deterministic. Intermediate density (C=0.6, the reference's
-    /// own init threshold) cuts the threshold through the noise distribution: a real mix of
-    /// clear (0) and covered cells — the scattered-cloud texture.
+    /// Density 1 is overcast; 0.6 gives the reference's init threshold, 101, and scattered cloud.
     #[test]
     fn density_shapes_the_field_and_regen_is_deterministic() {
         let mut a = CloudKernel::default();
@@ -559,8 +459,7 @@ mod tests {
         b.rebuild(1.0, &frame());
         assert_eq!(a.tile(), b.tile());
         assert_eq!(a.rgba(), b.rgba());
-        // Overcast: no cell clears (the noise's whole range sits above T=0), and the curve pushes
-        // the bulk high (measured mean ≈ 242, min 135 — the accumulator tail through the toe).
+        // Measured: mean about 242, minimum 135.
         assert!(
             a.tile().iter().all(|&v| v > 0),
             "overcast leaves no clear cell"
@@ -577,19 +476,14 @@ mod tests {
         );
     }
 
-    /// Band regeneration is keyed by absolute tile coordinates: four 32-row ticks at a fixed
-    /// phase reproduce exactly the tile a full rebuild computes at that phase. This pins the
-    /// toroidal walk (row_key seeding, per-row advance, quantize windows) against the reference
-    /// structure — a wrong scroll seed or window shears the field between bands. The colored
-    /// texels agree from row 1 (row 0's row-derivative reads the persistent prev-row scratch,
-    /// which legitimately differs between a fresh full pass and a scrolled one — the reference's
-    /// own post-rebuild wart, gone by the next wrap).
+    /// Row 0's texels differ: its row slope reads the previous-row scratch, which a fresh rebuild
+    /// and a scrolled band see differently, as in the reference.
     #[test]
     fn incremental_bands_tile_the_full_field() {
         let mut inc = CloudKernel::default();
-        inc.rebuild(0.6, &frame()); // ends with phase bumped to 1, scroll 0
+        inc.rebuild(0.6, &frame()); // leaves phase 1, scroll 0
         for _ in 0..4 {
-            inc.tick(1.0, 0.6, &frame()); // four band fires cover the whole tile at phase 1
+            inc.tick(1.0, 0.6, &frame());
         }
         let mut full = CloudKernel::default();
         full.set_phase(1);
@@ -598,10 +492,6 @@ mod tests {
         assert_eq!(inc.rgba()[COLS..], full.rgba()[COLS..]);
     }
 
-    /// The color pass (`0x6cfb00`): a covered cell away from the glow carries the pure gradient
-    /// bytes (`floor((slope·p + gbase)·255)`, `p = (((255−t)>>1)+64)/255`) with alpha = t; a
-    /// cell whose body-alignment is positive gains the sun term; a hole copies its left
-    /// neighbour's RGB at alpha 0.
     #[test]
     fn color_pass_matches_the_byte_math() {
         let mut k = CloudKernel::default();
@@ -620,7 +510,6 @@ mod tests {
             assert_eq!(px[1], want(f.slope[1], f.gbase[1]));
             assert_eq!(px[2], want(f.slope[2], f.gbase[2]));
         }
-        // Glow on: texels toward the sun brighten, none darken below the gradient base.
         let lit = frame();
         let mut kl = CloudKernel::default();
         kl.rebuild(1.0, &lit);
@@ -634,8 +523,6 @@ mod tests {
         assert!(kl.rgba().iter().zip(k.rgba()).all(|(a, b)| a[0] >= b[0]));
     }
 
-    /// The hole fill: force a hole next to a covered cell and recolor — the hole copies its left
-    /// neighbour's RGB with alpha 0 (the reference's filtering-friendly early-out).
     #[test]
     fn holes_copy_the_left_neighbour_rgb() {
         let mut k = CloudKernel::default();
@@ -650,32 +537,26 @@ mod tests {
         }
     }
 
-    /// The integer fast-inverse-sqrt seed (`0x456330`): the exact bit formula, ~3% accurate.
     #[test]
     fn fisr_is_the_binary_seed() {
         assert_eq!(fisr(1.0).to_bits(), 0x3f79_97bb);
         assert!((fisr(4.0) - 0.5).abs() < 0.02);
     }
 
-    /// The azimuthal projection: zenith reads the tile centre; a low direction lands on the rim
-    /// ring at its azimuth; below-horizon clamps to the same rim radius.
     #[test]
     fn sampler_projects_zenith_to_centre_and_horizon_to_rim() {
         let mut k = CloudKernel::default();
         k.tile.fill(0);
         let mid = COLS / 2;
         k.tile[mid * COLS + mid] = 255;
-        // Straight up: phase 0 ⇒ the centre cell.
         assert_eq!(k.coverage(Vec3::new(0.0, 12.0, 0.0)), 1.0);
-        // A horizontal +X direction: phase clamps to 0.5 ⇒ col = COLS (wraps to 0), row = mid.
+        // Horizontal +X clamps to the rim: col = COLS, which wraps to 0, row = mid.
         k.tile[mid * COLS] = 51;
         let r = k.coverage(Vec3::new(12.0, 0.0, 0.0));
         assert!((r - 0.2).abs() < 1e-3, "rim read {r}");
-        // Below the horizon: same clamp, same cell.
         assert_eq!(k.coverage(Vec3::new(12.0, -4.0, 0.0)), r);
     }
 
-    /// The moon tent peaks at half coverage and vanishes at both extremes (`0x6cf7d0`).
     #[test]
     fn moon_tent_shape() {
         assert_eq!(occ1_moon(0.5), 1.0);
diff --git a/crates/benilla-world/src/clouds/layer.rs b/crates/benilla-world/src/clouds/layer.rs
index 33ccd2f2..c1abfe8c 100644
--- a/crates/benilla-world/src/clouds/layer.rs
+++ b/crates/benilla-world/src/clouds/layer.rs
@@ -1,24 +1,7 @@
-//! The visible cloud layer — the reference's celestial-pass cloud dome (`0x6d0530` mesh,
-//! `0x6cfb00` coloring, `0x58ac70` per-regen texture upload; wow-re
-//! `scratch/cloud-coverage-pipeline.md` §3).
-//!
-//! The reference draws a 12-ring hemisphere strip (pole → the 45° rim, ring co-latitudes bunched
-//! toward the rim, per-ring vertex alpha fading the rim out) textured by an image generated from
-//! the coverage byte tile every regen, as the **last draw of its sky pass** — one squashed depth
-//! slice `[0.975, 0.98]` shared by stars/discs/gradient/clouds, depth-write off, painter's order
-//! (wow-re `celestial-frame-anatomy`; the earlier "discs at `[0.995, 1.0]`" note here
-//! misattributed the GLARE + occlusion-probe band to the discs) — so terrain occludes the clouds
-//! and the clouds blend over a setting sun. We reproduce the layering with real depth: every
-//! vertex is pushed to **uniform radius** along its recentred direction (the reference's squashed
-//! cap relies on the depth-range remap; at real depth its apex would sit at `0.29·r` — inside the
-//! scene, clouds drawing over cliffs) and the dome is camera-centred at `far·0.87` — inside the
-//! opaque sky dome (`far·0.9`), behind all terrain — with its slot in the reference's fixed order
-//! held by [`crate::sky_order::CLOUDS_BIAS`]: after the discs, before the rain, before the glare
-//! (the frame's last render, per the same pin).
-//!
-//! The strip topology is converted to a triangle list (11 bands × 32 triangles — the reference's
-//! 11 separate 34-index strips; same pixels, one mesh). The coverage image is R8; the color math
-//! runs per-fragment in `cloud.wgsl` from the same bytes the occlusion sampler reads.
+//! The visible cloud layer, the reference's cloud dome (`0x6d0530` mesh, `0x6cfb00` coloring,
+//! `0x58ac70` upload): a 12-ring cap from the pole to the 45° rim, faded at the rim, drawn last in
+//! the sky pass so clouds blend over a setting sun. [`crate::sky_order::CLOUDS_BIAS`] holds that
+//! place; the shared far-depth pin puts it behind all terrain.
 
 use bevy::asset::RenderAssetUsages;
 use bevy::camera::Projection;
@@ -40,25 +23,21 @@ use crate::view::WorldCamera;
 
 use super::kernel::COLS;
 
-/// The cloud dome material: unlit premultiplied-gamma blend over the sky, coverage from the R8
-/// tile texture, palette/glow uniforms packed like `SkyExt`.
+/// The cloud dome material: the kernel's colored texels, blended premultiplied in gamma.
 pub type CloudMaterial = ExtendedMaterial<StandardMaterial, CloudExt>;
 
-/// The colored cloud texture (see `cloud.wgsl`). All color math already happened CPU-side in the
-/// kernel's `0x6cfb00` port (gradient + glow + weather dim, in gamma bytes exactly like the
-/// reference) — the material only carries the resulting RGBA image, whose texels are **raw gamma
-/// values** (a non-sRGB texture, never linearised).
+/// The colored cloud texture. The color math is CPU-side as in the reference, so the texels are
+/// raw gamma bytes in a non-sRGB texture.
 #[derive(Asset, AsBindGroup, Clone, TypePath)]
 pub struct CloudExt {
-    /// The live colored tile (RGBA8, 128², alpha = coverage), re-uploaded on regen — the
-    /// reference's `0x58ac70` zero-copy bind of the `0x6cfb00` color buffer (Addendum A §3).
+    /// The colored tile, alpha the coverage, re-uploaded each regen (`0x58ac70`).
     #[texture(100)]
     #[sampler(101)]
     pub(crate) texels: Handle<Image>,
 }
 
 impl MaterialExtension for CloudExt {
-    /// The shared sky vertex stage — the far-depth pin ([`crate::sky_order`], "The depth law").
+    /// The shared sky vertex stage, which pins every sky vertex to the far depth.
     fn vertex_shader() -> ShaderRef {
         SKY_VERTEX_SHADER.into()
     }
@@ -78,22 +57,18 @@ impl MaterialExtension for CloudExt {
     }
 }
 
-/// Marker for the cloud dome entity.
 #[derive(Component)]
 pub(super) struct CloudDome;
 
-/// The tick system's upload target — the colored tile image the dome samples, plus the material
-/// to touch on every upload (a modified `Image` gets a fresh GPU texture, and the material's
-/// cached bind group must be rebuilt to see it — without the touch the dome keeps sampling the
-/// first upload forever).
+/// The tick's upload target: the image the dome samples, and the material to touch on each upload
+/// so its bind group picks up the new texture.
 #[derive(Resource)]
 pub(super) struct CloudLayer {
     pub(crate) image: Handle<Image>,
     pub(crate) material: Handle<CloudMaterial>,
 }
 
-/// Ring co-latitude fractions ×π (`0x811570` table, `0x6d0530`): pole → the 45° rim, bunched
-/// toward the rim.
+/// Ring co-latitudes in units of π (`0x811570`), from the pole to the 45° rim.
 const RING_COLAT: [f32; 12] = [
     0.0, 0.025, 0.05, 0.075, 0.10, 0.125, 0.15, 0.175, 0.205, 0.23, 0.245, 0.25,
 ];
@@ -102,13 +77,11 @@ const RING_COLAT: [f32; 12] = [
 const RING_ALPHA: [f32; 12] = [
     1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 128.0 / 255.0, 0.0, 0.0,
 ];
-/// Azimuth steps per ring (`0x6d0530`: 12 rings × 16 = 192 verts).
+/// Azimuth steps per ring (`0x6d0530`).
 const AZ_STEPS: usize = 16;
 
-/// The reference dome (`0x6d0530`, radius 1): positions recentred `−cos(π/4)` so the rim sits at
-/// eye level, the polar UV `(sin·V + 0.5, cos·V + 0.5)` with `V = ring/24` — the same square
-/// mapping the coverage sampler uses, so the drawn cloud and the glare occlusion co-locate.
-/// Normals = the unit sky direction (feeds the sun-glow alignment).
+/// The reference dome (`0x6d0530`): recentred by `−cos(π/4)` so the rim sits at eye level, with
+/// the coverage sampler's polar UV so the drawn cloud and the glare's occlusion line up.
 fn cloud_dome_mesh() -> Mesh {
     let shift = std::f32::consts::FRAC_PI_4.cos();
     let mut positions = Vec::with_capacity(12 * AZ_STEPS);
@@ -117,16 +90,15 @@ fn cloud_dome_mesh() -> Mesh {
     let mut colors = Vec::with_capacity(12 * AZ_STEPS);
     for (ring, (&colat, &alpha)) in RING_COLAT.iter().zip(RING_ALPHA.iter()).enumerate() {
         let phi = colat * std::f32::consts::PI;
-        let v_r = ring as f32 / 24.0; // ring·(1/12)·0.5 — the polar UV radius
+        let v_r = ring as f32 / 24.0; // the polar UV radius
         for j in 0..AZ_STEPS {
             let az = j as f32 / AZ_STEPS as f32 * std::f32::consts::TAU;
             let (sa, ca) = az.sin_cos();
-            // The recentred sky direction (`cos φ − cos45°` height: rim at eye level), pushed to
-            // unit radius so the whole cap sits at one distance (see the module docs).
+            // Recentred so the rim sits at eye level, then pushed to unit radius.
             let dir = Vec3::new(phi.sin() * sa, phi.cos() - shift, phi.sin() * ca).normalize();
             positions.push([dir.x, dir.y, dir.z]);
             normals.push([dir.x, dir.y, dir.z]);
-            // u tracks world x, v tracks world z — matching the sampler's (col ← x, row ← z).
+            // u follows world x and v world z, as the sampler's column and row do.
             uvs.push([sa * v_r + 0.5, ca * v_r + 0.5]);
             colors.push([1.0, 1.0, 1.0, alpha]);
         }
@@ -169,7 +141,7 @@ pub(super) fn setup_cloud_layer(
         },
         TextureDimension::D2,
         vec![0; COLS * COLS * 4], // fully transparent until the field primes
-        // NON-sRGB: the texels are the kernel's gamma bytes; sampling must return them raw.
+        // Not sRGB: the texels are gamma bytes and must sample raw.
         TextureFormat::Rgba8Unorm,
         RenderAssetUsages::default(),
     ));
@@ -178,8 +150,7 @@ pub(super) fn setup_cloud_layer(
             unlit: true,
             cull_mode: None, // viewed from inside
             alpha_mode: AlphaMode::Premultiplied,
-            // The sky pass's last draw — over the discs, under the rain and the glare (the
-            // reference's fixed order; see the ladder in `sky_order`).
+            // The sky pass's last draw: over the discs, under the rain and the glare.
             depth_bias: crate::sky_order::CLOUDS_BIAS,
             ..default()
         },
@@ -196,19 +167,9 @@ pub(super) fn setup_cloud_layer(
     commands.insert_resource(CloudLayer { image, material });
 }
 
-/// The sky-dome visibility toggle (the clouds hide with the rest of the sky). All color state
-/// lives in the texture — the kernel's `0x6cfb00` port owns it.
-///
-/// A WMO skybox ([`crate::skybox`]) hides the clouds too: `CSky::Render`'s one shared boolean skips
-/// **all six** sky elements together (`0x6d4a3b test edi,edi; je`), so the painted art is the whole
-/// sky rather than a backdrop the procedural clouds keep drawing over. The art carries its own cloud
-/// banks; layering ours on top lifted the painted zenith out of its near-black. The gate is the
-/// slot's **weight** past 0.99 ([`crate::skybox::SkyboxWeight`]): through the body of the 4-second
-/// crossfade the clouds keep drawing and the painted sky alpha-blends over them.
-///
-/// A **submerged eye** hides them the same way: the scene driver's `0x6812a4` submerged test skips
-/// the whole `CSky::Render` call (byte-VERIFIED, wow-re terrain "the liquid render state") — from
-/// under the surface there is no sky, only the murk.
+/// Hides the dome with the rest of the sky: under a WMO skybox past weight 0.99, as `CSky::Render`
+/// skips all six sky elements on one flag (`0x6d4a3b`), and while submerged, as the scene skips
+/// `CSky::Render` (`0x6812a4`).
 pub(super) fn apply_cloud_visibility(
     debug: Res<DebugState>,
     skybox: Res<crate::skybox::SkyboxWeight>,
@@ -226,11 +187,8 @@ pub(super) fn apply_cloud_visibility(
     }
 }
 
-/// Pin the dome to the camera at `far·0.87` — inside the opaque sky dome (`far·0.9`), sorted after
-/// the disc shells so the transparent pass draws the clouds over a setting sun, the reference's
-/// depth-band layering. The radius sets the dome's *screen* geometry only: occlusion against the
-/// world is the far depth `sky_vertex.wgsl` pins (`sky_order`, "The depth law"), not this shell —
-/// the WDL horizon reaches past it (0588).
+/// Centres the dome on the camera at `far·0.87`, inside the sky dome. The radius only sizes it on
+/// screen; occlusion comes from the far-depth pin in `sky_vertex.wgsl`.
 #[allow(clippy::type_complexity)]
 pub(super) fn follow_cloud_dome(
     cam: Query<(&GlobalTransform, &Projection), With<WorldCamera>>,
@@ -259,9 +217,6 @@ pub(super) fn follow_cloud_dome(
 mod tests {
     use super::*;
 
-    /// The dome is the reference's `0x6d0530` build: 192 verts (12 rings × 16), the 11 band
-    /// strips as 352 triangles, rim at eye level (y = 0 after the −cos45° recentre), UV radius
-    /// growing ring-linear to 11/24.
     #[test]
     fn dome_matches_the_reference_build() {
         let mesh = cloud_dome_mesh();
@@ -275,8 +230,7 @@ mod tests {
             .unwrap()
             .as_float3()
             .unwrap();
-        // Every vertex sits at unit radius (the uniform-distance push); the pole points straight
-        // up and the rim (colat 0.25π, recentred to eye level) stays at y = 0.
+        // Unit radius everywhere; the pole points straight up and the rim sits at y = 0.
         for p in pos {
             let r = (p[0] * p[0] + p[1] * p[1] + p[2] * p[2]).sqrt();
             assert!((r - 1.0).abs() < 1e-5, "radius {r}");
diff --git a/crates/benilla-world/src/clouds/mod.rs b/crates/benilla-world/src/clouds/mod.rs
index 3996dbc7..aca2e21e 100644
--- a/crates/benilla-world/src/clouds/mod.rs
+++ b/crates/benilla-world/src/clouds/mod.rs
@@ -1,20 +1,8 @@
-//! Clouds — the procedural sky cloud subsystem (wow-re `scratch/cloud-coverage-pipeline.md`).
+//! The procedural sky clouds: as in the reference, one coverage field feeds both the glare's cloud
+//! occlusion and the visible dome, so the cloud over the sun is the cloud that dims it.
 //!
-//! One coverage field serves every consumer, exactly like the reference: the [`kernel`] maintains
-//! the scrolling 128² byte tile (4-octave toroidal value noise, thresholded by the authored
-//! Light.dbc cloud density `C`, tone-curved), the flare gate samples it for the cloud occlusion
-//! `occ1` (sun `1−R`, moon the thin-cloud tent), and the visible [`layer`] renders the same bytes
-//! as a dome texture. A cloud drifting over the sun therefore dims the glare *and* is the cloud
-//! you see — they cannot desynchronize.
-//!
-//! `C` rides [`WowLighting::cloud_density`] (LightFloatBand sub-3, weather/underwater blends
-//! included), so storms with an authored overcast band raise the coverage — and with it the
-//! glare dimming — with no extra wiring.
-//!
-//! **Capture mode freezes the field's clock**: the tile becomes a pure function of `C` (a full
-//! rebuild whenever it changes, no phase drift), so capture fixtures stay bit-identical across
-//! runs — the settle-frame count varies with real frame timing, and a live phase would smear a
-//! few bytes per run. Live runs keep the reference's ~10 Hz scroll + slow morph.
+//! Capture mode freezes the field's clock and rebuilds only when the density changes, so captures
+//! stay byte-identical whatever the frame timing.
 
 use bevy::pbr::MaterialPlugin;
 use bevy::prelude::*;
@@ -30,19 +18,14 @@ mod tables;
 
 pub use kernel::{occ1_moon, occ1_sun};
 
-/// The live cloud coverage field. Read [`CloudCoverage::coverage`] with a camera-relative offset
-/// (e.g. the glare's 12-unit sky point) to get `R ∈ [0,1]` at that sky position.
+/// The live cloud coverage field.
 #[derive(Resource)]
 pub struct CloudCoverage {
     kernel: kernel::CloudKernel,
-    /// Whether the first full rebuild ran (the reference full-rebuilds on init, then scrolls
-    /// incrementally — `0x6cff90` vs `0x6cffc0`).
+    /// Whether the init rebuild ran (`0x6cff90`); the bands scroll after it (`0x6cffc0`).
     primed: bool,
-    /// Capture mode: freeze the phase clock; rebuild only when `C` changes (see module docs).
     frozen: bool,
-    /// The density the tile was last built with (the frozen-mode rebuild trigger).
     last_density: f32,
-    /// The color-pass inputs of the last build (the frozen-mode recolor trigger).
     last_frame: Option<kernel::CloudFrame>,
 }
 
@@ -59,7 +42,7 @@ impl Default for CloudCoverage {
 }
 
 impl CloudCoverage {
-    /// Coverage `R` toward camera-relative offset `d` (Bevy frame, +Y up).
+    /// Coverage in [0, 1] toward camera-relative `d` (Bevy frame, +Y up).
     pub fn coverage(&self, d: Vec3) -> f32 {
         self.kernel.coverage(d)
     }
@@ -75,25 +58,20 @@ impl Plugin for CloudsPlugin {
             .add_systems(
                 Update,
                 (
-                    // After the submersion verdict: the surfacing edge (wet→dry) must fire the
-                    // full rebuild the SAME frame the dome un-hides, or the first visible frame
-                    // still shows the submerged-era tile.
-                    // …and on the READ side of the lighting resolve: the surfacing rebuild
-                    // below takes its density and palette from `WowLighting`, so an unordered
-                    // tick rebuilds the field from the atmosphere we just LEFT — the underwater
-                    // one, whose cloud density is 0.0 in Stranglethorn (B354, decision 2032).
+                    // After the submersion verdict, so surfacing rebuilds the tile the frame the
+                    // dome reappears, and after the lighting resolve, so that rebuild takes the
+                    // air's density and palette rather than the water's.
                     tick_clouds
                         .after(crate::liquid::SubmersionVerdict)
                         .in_set(crate::lighting::LightingConsumeSet),
-                    // After the resolve: the dome and the painted skybox must agree WITHIN a frame,
-                    // or one frame draws both (the ordering `crate::sky`'s gate already takes) —
-                    // and after the submersion verdict, for the same one-frame-agreement reason.
+                    // After the skybox resolve and the submersion verdict, so the dome hides in
+                    // the same frame as the rest of the sky.
                     layer::apply_cloud_visibility
                         .after(crate::skybox::SkyboxResolve)
                         .after(crate::liquid::SubmersionVerdict),
                 ),
             )
-            // Camera-anchored placement post-propagation, like the sky dome (decision 0504).
+            // Camera-anchored after transform propagation, like the sky dome.
             .add_systems(
                 PostUpdate,
                 layer::follow_cloud_dome.in_set(crate::billboard::BillboardPlace),
@@ -101,10 +79,8 @@ impl Plugin for CloudsPlugin {
     }
 }
 
-/// Advance the coverage field — a full rebuild the first frame, then the reference's ~10 Hz
-/// incremental 32-row band scroll (or the frozen capture clock) — and re-upload the colored
-/// RGBA texels when they changed (the reference's per-regen `0x58ac70` upload of the `0x6cfb00`
-/// color buffer, Addendum A §3).
+/// Advances the coverage field (a full rebuild first, then the 10 Hz band scroll) and re-uploads
+/// its texels when they change, as the reference does per regen (`0x58ac70`).
 fn tick_clouds(
     mut cov: ResMut<CloudCoverage>,
     light: Res<WowLighting>,
@@ -115,18 +91,13 @@ fn tick_clouds(
     underwater: Res<crate::liquid::Underwater>,
     mut was_submerged: Local<bool>,
 ) {
-    // The surfacing edge — the reference's wet→dry detector `0x680ac3` fires `0x6d2210(1)`, the
-    // FULL-rebuild selector (`bl!=0` → `0x6cff90`), the frame the eye leaves the liquid
-    // (byte-VERIFIED, wow-re `water-frame-straddle.md` §4b + `cloud-coverage-pipeline.md` §0).
-    // Without it the incremental 32-row scroll restores the field band-by-band over ~0.4 s+ —
-    // the sky pass returns instantly (0902's gate) but the clouds creep back in behind it,
-    // the "delayed pop-in" the director sighted. Dry→wet takes no edge, exactly like the
-    // reference: the sky pass is skipped while submerged, so nobody sees the tile.
+    // Surfacing forces a full rebuild: the reference's wet→dry edge (`0x680ac3`) calls
+    // `0x6d2210(1)`, which selects `0x6cff90`; a band scroll would bring the clouds back over
+    // 0.4 s. Going under needs nothing, since the sky pass is skipped while submerged.
     let submerged = underwater.0.any();
     let surfaced = *was_submerged && !submerged;
     *was_submerged = submerged;
     let density = light.cloud_density;
-    // The color-pass inputs (`0x6cfb00`'s per-frame setup), from the resolved lighting.
     let frame = kernel::CloudFrame {
         sun: light.cloud_colors[0],
         slope: light.cloud_colors[1],
@@ -153,8 +124,7 @@ fn tick_clouds(
         cov.kernel.rebuild(density, &frame);
         true
     } else if cov.frozen {
-        // The frozen capture clock: the coverage stays put; recolor only when the palette /
-        // glow / weather inputs moved (deterministic — the scenario pins them).
+        // Frozen clock: coverage stays put; recolor only when the color inputs move.
         if cov.last_frame != Some(frame) {
             cov.last_frame = Some(frame);
             cov.kernel.recolor(&frame);
@@ -173,9 +143,8 @@ fn tick_clouds(
                     .as_mut()
                     .expect("cpu-side cloud image")
                     .copy_from_slice(cov.kernel.rgba().as_flattened());
-                // Touch the material so its bind group rebuilds against the re-uploaded
-                // texture (a modified Image gets a NEW GpuImage; a stale bind group keeps
-                // sampling the first upload forever).
+                // Touch the material: a modified Image gets a new GPU texture, and a stale bind
+                // group keeps sampling the first upload.
                 materials.get_mut(&layer.material);
             }
         }
diff --git a/crates/benilla-world/src/clouds/tables.rs b/crates/benilla-world/src/clouds/tables.rs
index a214fed2..7ca6b523 100644
--- a/crates/benilla-world/src/clouds/tables.rs
+++ b/crates/benilla-world/src/clouds/tables.rs
@@ -1,8 +1,6 @@
-//! The frozen cloud noise tables — dumped from the binary or rebuilt by its exact one-time
-//! builders (wow-re `scratch/cloud-coverage-pipeline.md` §1b/§1d).
+//! The cloud noise tables, dumped from the reference or rebuilt by its one-time builders.
 
-/// The static permutation table (`0x86f2d0`, `.rdata`) — 256 bytes, a permutation of 0..255,
-/// always indexed `& 0xff` (no doubled-512 layout). Dumped verbatim from the binary.
+/// The permutation table (`0x86f2d0`), dumped verbatim: 256 bytes, always indexed `& 0xff`.
 #[rustfmt::skip]
 pub(crate) const PERM: [u8; 256] = [
     225, 155, 210, 108, 175, 199, 221, 144, 203, 116,  70, 213,  69, 158,  33, 252,
@@ -23,10 +21,8 @@ pub(crate) const PERM: [u8; 256] = [
     137, 214, 145,  93,  92, 100, 245,   0, 216, 186,  60,  83, 105,  97, 204,  52,
 ];
 
-/// The tone curve (`0xce91d8`) — built once at init by `dn_tone_curve 0x6d0900` (gamma 0.96,
-/// init threshold 101: `curve[i] = ftol(255 − 255·0.96^(i·0.6015625))`) and fixed thereafter.
-/// Frozen to the reference's exact bytes rather than recomputed through libm `pow`
-/// (cross-platform determinism; wow-re pipeline §1d).
+/// The tone curve (`0xce91d8`), built once by `0x6d0900` as `ftol(255 − 255·0.96^(i·0.6015625))`
+/// for the init threshold 101; frozen to the reference's bytes, as libm `pow` varies by platform.
 #[rustfmt::skip]
 pub(crate) const CURVE: [u8; 256] = [
       0,   6,  12,  18,  23,  29,  34,  40,  45,  50,  55,  60,  65,  69,  74,  78,
@@ -47,10 +43,9 @@ pub(crate) const CURVE: [u8; 256] = [
     254, 254, 254, 254, 254, 254, 254, 254, 254, 254, 254, 254, 254, 254, 254, 254,
 ];
 
-/// The gradient table build (`0x6d0c90` loop 1): `gradient[i] = 1 − 2·rand()/32767` with MSVC's
-/// LCG (`seed = seed·214013 + 2531011; (seed >> 16) & 0x7fff`). The reference's seed is whatever
-/// the process `srand` state was — not visually load-bearing (any uniform table is equivalent);
-/// we fix seed = 1 (the CRT default) for run-to-run determinism.
+/// The gradient table (`0xce92d8`, built by `0x6d0c90` loop 1): `1 − 2·rand()/32767` on MSVC's
+/// `rand`. Deviation: seed 1, the CRT default, for determinism; the reference's is the process
+/// `srand` state, and any uniform table looks the same.
 pub(crate) fn gradient_table() -> [f32; 256] {
     let mut seed: u32 = 1;
     std::array::from_fn(|_| {
@@ -60,7 +55,7 @@ pub(crate) fn gradient_table() -> [f32; 256] {
     })
 }
 
-/// The fade table build (`0x6d0c90` loop 2): the raised-cosine ease `0.5·(1 − cos(iπ/256))`.
+/// The fade table (`0xce8dd8`, built by `0x6d0c90` loop 2): a raised cosine.
 pub(crate) fn fade_table() -> [f32; 256] {
     std::array::from_fn(|i| 0.5 * (1.0 - ((i as f32) * std::f32::consts::PI / 256.0).cos()))
 }
diff --git a/crates/benilla-world/src/clutter.rs b/crates/benilla-world/src/clutter.rs
index 922e0d4f..b9c584aa 100644
--- a/crates/benilla-world/src/clutter.rs
+++ b/crates/benilla-world/src/clutter.rs
@@ -1,11 +1,6 @@
-//! Ground clutter: grass/flowers/pebbles scattered per MCNK cell (authored `GroundEffect*.dbc`
-//! placement). At tile-load each chunk's tufts are **scattered** (MCSH/normal-baked) into a per-chunk
-//! [`ClutterChunk`]; [`stream_chunk_clutter`] then **builds** its merged meshes lazily only while the
-//! chunk is within the ~70 yd detail-doodad horizon and tears them down past it — the reference's
-//! per-chunk `CDetailDoodadInst` lifecycle (`ground-effects.md` §7), which bounds live grass to a bubble
-//! and spreads the build across frames. [`ClutterPlugin`] owns the catalog + the lazy build lifecycle
-//! independently of the terrain streamer; whichever streamer is active does the per-tile *scatter* (it
-//! has the tile's chunks) into the `ClutterChunk`s this builds — so the streamer can be swapped.
+//! Ground clutter (`GroundEffect*.dbc`): the terrain streamer scatters each chunk's tufts at tile
+//! load, and a chunk's meshes exist only inside the 70 yd detail-doodad horizon (`[0x867958]`),
+//! the reference's per-chunk `CDetailDoodadInst` build and unlink.
 
 use std::collections::HashMap;
 
@@ -24,17 +19,13 @@ use benilla_formats::{
     GroundDoodadPlacement, GroundEffectCatalog, ModelBlend, RenderSubmesh, SHADOW_MAP_SIZE,
 };
 
-/// Ground clutter as its own subsystem: loads the `GroundEffect*` catalog + config at startup, and runs
-/// the lazy per-chunk build/teardown every frame. The per-tile *scatter* is driven by whichever terrain
-/// streamer is active (it has the tile's chunks); this plugin owns the catalog and the build lifecycle
-/// so they don't depend on the terrain streamer's own setup (which lets the streamer be swapped).
+/// Loads the ground-effect catalog at startup and runs the per-chunk build and teardown.
 pub(crate) struct ClutterPlugin;
 
 impl Plugin for ClutterPlugin {
     fn build(&self, app: &mut App) {
-        // The config exists from plugin build, not `setup_clutter`: the CVar loader
-        // (`crate::cvars::load_config`, also Startup) applies a saved `WorldDetail` onto it, and
-        // an ordering flip must not silently drop the file's value (0992).
+        // Inserted at build, not in `setup_clutter`: `benilla-app`'s Startup CVar loader applies a
+        // saved `WorldDetail` onto it.
         app.init_resource::<ClutterConfig>()
             .add_systems(Startup, setup_clutter.after(AssetSet::Open))
             .add_systems(
@@ -50,17 +41,9 @@ impl Plugin for ClutterPlugin {
     }
 }
 
-/// Drop every built clutter mesh when the detail-doodad **cutout** moves, so the lazy builder
-/// re-meshes the bubble against the new reference — the alpha-test ref is baked into the material at
-/// build time (it is part of `model_material`'s dedup key), so nothing already on screen would
-/// otherwise notice. `detailDoodadAlpha` is a live console command in the reference
-/// (`0x6739a0`, registrar `0x63f9e0` — a command, not a CVar, so it never persists), where the
-/// global is read at draw time and needs no rebuild; ours costs a re-mesh of the ~30 chunks in the
-/// bubble, which the per-frame cap spreads over a few frames.
-///
-/// Watches the **value**, not `is_changed()`, because the predicate is "the cutout moved" and
-/// not "the resource moved": `ClutterConfig` also carries the density, whose own writer would
-/// otherwise cost a re-mesh of the bubble on every detail-slider notch. First sight only arms.
+/// Drop the built meshes when the cutout value moves (a density write must not re-mesh): the ref is
+/// baked into the material. The reference's `detailDoodadAlpha` is a console command (`0x6739a0`,
+/// registered at `0x63f9e0`), not a CVar, so it never persists.
 fn remesh_on_cutout_change(
     mut commands: Commands,
     cfg: Res<ClutterConfig>,
@@ -86,9 +69,7 @@ fn remesh_on_cutout_change(
     );
 }
 
-/// Drop the decoded clutter-geometry cache on a cross-map transition (`world_map::MapChange` —
-/// see its doc): it holds CPU submesh copies of every detail M2 ever decoded, and clutter models
-/// are map-flavored (a new map re-decodes its own handful on first build).
+/// Drop the decoded clutter geometry on a map change; the new map decodes its own models.
 fn evict_clutter_geometry(
     mut changes: MessageReader<crate::world_map::MapChange>,
     geometry: Option<ResMut<ClutterGeometry>>,
@@ -102,11 +83,7 @@ fn evict_clutter_geometry(
     }
 }
 
-/// Expire the decoded clutter geometry by **distance** (decision 0793) — the within-map half of
-/// [`evict_clutter_geometry`]. Clutter models are map-*flavoured*: the handful a zone uses is decoded
-/// on its first chunk build and then held for the process, so a continent tour accumulates every
-/// zone's set. Re-approaching re-decodes one M2 off the chain, inside the same lazy per-chunk build
-/// that would rebuild the meshes anyway.
+/// Expire the decoded clutter geometry by distance within a map.
 fn scope_clutter_geometry(
     mut scope: crate::art_scope::ArtScope,
     geometry: Option<ResMut<ClutterGeometry>>,
@@ -116,16 +93,14 @@ fn scope_clutter_geometry(
     }
 }
 
-/// Startup: load the ground-effect (clutter) catalog off the shared chain + insert the per-chunk
-/// geometry cache. (Moved out of the terrain streamer's `setup_terrain`.)
+/// Startup: load the ground-effect catalog and insert the geometry cache.
 fn setup_clutter(mut commands: Commands, world_assets: Option<ResMut<WorldAssets>>) {
     let Some(world_assets) = world_assets else {
         return;
     };
-    // Per-chunk clutter geometry cache, read by the lazy `stream_chunk_clutter` build.
     commands.insert_resource(ClutterGeometry::default());
     let mut chain = world_assets.chain.lock_recover();
-    // key_by_internal_id = true: the faithful GroundEffectDoodad keying (see load_ground_effect_catalog).
+    // `true`: a `doodadId` names a `GroundEffectDoodad.internalId`, as the reference keys it.
     match load_ground_effect_catalog(&mut chain, true) {
         Ok(catalog) => {
             info!("ground-effect catalog: {} effects", catalog.len());
@@ -135,68 +110,38 @@ fn setup_clutter(mut commands: Commands, world_assets: Option<ResMut<WorldAssets
     }
 }
 
-/// Ground-clutter rendering: the `effectId → (models, density)` catalog (GroundEffect* DBCs).
-/// Optional — if the DBCs fail to load, the ground simply has no detail doodads. Clutter is scattered
-/// per chunk into [`ClutterChunk`] units at tile-load (tracked with the tile so it streams out with the
-/// terrain) and built lazily by [`stream_chunk_clutter`]. The raw model geometry is cached in
-/// [`ClutterGeometry`].
+/// The `effectId → (models, density)` catalog; absent, and no clutter, when the DBCs fail to load.
 #[derive(Resource)]
 pub(crate) struct GroundClutter {
     pub(crate) catalog: GroundEffectCatalog,
 }
 
-/// The client's detail-doodad alpha-test reference: `detailDoodadAlpha`, default **128/255 ≈ 0.5**
-/// (RE'd in `WoW.exe`). Foliage is an alpha-tested cutout at
-/// this ref. We default clutter to it instead of the general (higher) vanilla model key, which was
-/// over-cutting the thin grass blades in the shared grass/flower atlas (they vanished while the solid
-/// flowers survived).
+/// The detail-doodad alpha-test ref, `detailDoodadAlpha` = 128/255, lower than the model key.
 pub(crate) const DETAIL_DOODAD_ALPHA_REF: f32 = 128.0 / 255.0;
 
-/// The client's detail-doodad draw distance — a **hardcoded 70 yd** (RE'd `_DAT_00867958`); clutter
-/// fades out over the last quarter (full to 52.5 yd = 0.75×, gone by 70 yd). This is why the real
-/// client's clutter "appears as you walk into it" rather than being drawn to the horizon.
+/// The reference's hardcoded detail-doodad draw distance, 70 yd (`[0x867958]`); clutter fades out
+/// over its last quarter.
 pub(crate) const DETAIL_DOODAD_FADE_FAR: f32 = 70.0;
 
-/// Ground-clutter tunables (read at tile scatter; a `density` change re-scatters LOADED tiles too —
-/// `terrain_stream::rescatter_clutter`, the 1.12 setter's own chunk-rebuild law, 0992):
-/// `density` multiplies the per-chunk cell-visit count (the client's `frillDensity`, faithful=16 at ×1)
-/// — player-settable through **either** registered CVar over this one field, [`ClutterConfig::frill_density`]
-/// being the conversion: `WorldDetail` (the panel's stop, 0/1/2 → ×1/×2/×3) or `frillDensity` (the
-/// reference's own cells-per-chunk, 1..256), both arms in `benilla-app`'s `cvars`;
-/// `scale` resizes each doodad model; `alpha_ref` is the alpha-test cutout threshold
-/// ([`DETAIL_DOODAD_ALPHA_REF`]); `fade_far` is the clutter draw-distance horizon (yd,
-/// [`DETAIL_DOODAD_FADE_FAR`]; fade starts at 0.75×). Initial values from `$WOW_CLUTTER_DENSITY` /
-/// `$WOW_CLUTTER_SCALE` / `$WOW_CLUTTER_ALPHA` / `$WOW_CLUTTER_FADE`; `density 0` disables clutter.
+/// Ground-clutter tunables. `density` scales the reference's 16 cells per chunk (`frillDensity`),
+/// and a change re-scatters loaded tiles, as the 1.12 setter rebuilds its chunks. Seeded from
+/// `$WOW_CLUTTER_DENSITY`, `$WOW_CLUTTER_ALPHA` and `$WOW_CLUTTER_FADE`; density 0 is no clutter.
 #[derive(Resource, Clone, Copy)]
 pub struct ClutterConfig {
     pub density: f32,
-    pub scale: f32,
     pub alpha_ref: f32,
     pub fade_far: f32,
 }
 
 impl ClutterConfig {
-    /// This session's ground cover in the **reference's own unit** — `frillDensity`, the number of
-    /// cells the scatter visits per chunk ([`benilla_formats::FRILL_DENSITY`] at ×1).
-    ///
-    /// The multiplier above is benilla's spelling of a knob 1.12 keeps in cells: its slider stops
-    /// are `SetWorldDetail 0x488dd0`'s 16/32/48, which are this constant times 1/2/3. So the two
-    /// registered CVars over this field — `WorldDetail` (the stop) and `frillDensity` (the cells) —
-    /// are one knob read two ways, and this pair is where that conversion lives so neither the CVar
-    /// host nor the scatter carries a bare 16.
+    /// The ground cover as the reference's `frillDensity`, cells visited per chunk; the
+    /// `WorldDetail` slider stops are 16/32/48 (`SetWorldDetail`, `0x488dd0`).
     pub fn frill_density(&self) -> f32 {
         self.density * benilla_formats::FRILL_DENSITY as f32
     }
 
-    /// Set the ground cover from a `frillDensity`, under the reference's own clamp.
-    ///
-    /// `[1, 256]` is what the real client's change callback `0x688de0` pins a written value to —
-    /// **not** `[16, 48]`: the slider's three stops are one writer of this CVar, and a console
-    /// `frillDensity 200` is another. It is also why the `WorldDetail` arm's clamp is the tighter
-    /// one: there the stop is the value, here the cells are.
-    ///
-    /// Zero is deliberately NOT reachable here, matching that callback — clutter-off stays the
-    /// `$WOW_CLUTTER_DENSITY=0` lever's, which is an instrument rather than a setting.
+    /// Set the ground cover from a `frillDensity`, clamped to `[1, 256]` as the reference's change
+    /// callback `0x688de0` does, so zero is unreachable here.
     pub fn set_frill_density(&mut self, frill: f32) {
         self.density = frill.clamp(1.0, benilla_formats::FRILL_DENSITY_MAX as f32)
             / benilla_formats::FRILL_DENSITY as f32;
@@ -207,16 +152,10 @@ impl Default for ClutterConfig {
     fn default() -> Self {
         let env = |k: &str| std::env::var(k).ok().and_then(|s| s.parse::<f32>().ok());
         Self {
-            // Default ×2 = frillDensity 32 = the panel's Medium (1649). It was ×3/High, matched to
-            // the director's OWN reference install, which runs High — a setting on their machine,
-            // not a default of the game's: `frillDensity` registers at 16, and a first launch has
-            // `hwDetect` overwrite it from `VideoHardware.dbc` to 24 on any D3D9-class part and 8
-            // on the weakest. Both are below Medium, and 24 is not on a panel stop at all, so every
-            // stop is a divergence; High was simply the dearest one, and this is alpha-tested
-            // overdraw on the ground — the thing a bandwidth-bound part has least of. Medium is the
-            // nearest stop no sparser than a fresh install, and the row is one drag from High.
+            // Deviation: ×2, `frillDensity` 32 (the panel's Medium), because a fresh install's
+            // `hwDetect` value (24 from `VideoHardware.dbc`, 8 on the weakest parts) is on no panel
+            // stop, and Medium is the nearest stop no sparser.
             density: env("WOW_CLUTTER_DENSITY").unwrap_or(2.0).max(0.0),
-            scale: env("WOW_CLUTTER_SCALE").unwrap_or(1.0).max(0.01),
             alpha_ref: env("WOW_CLUTTER_ALPHA")
                 .unwrap_or(DETAIL_DOODAD_ALPHA_REF)
                 .clamp(0.0, 1.0),
@@ -227,68 +166,43 @@ impl Default for ClutterConfig {
     }
 }
 
-/// Decoded clutter-model geometry cache (model path → submeshes), keyed by normalized path so each
-/// tiny detail M2 is loaded once and then *merged* per chunk. Lives as a resource (not on the streamer)
-/// so the lazy per-chunk build system can reach it independently of `WorldAssets`. Replaces the
-/// streamer's old per-tile `clutter_cache`.
+/// Decoded clutter-model submeshes by path: each detail M2 is decoded once, then merged per chunk.
 #[derive(Resource, Default)]
 pub(crate) struct ClutterGeometry(
     pub(crate) benilla_assets::SpatialCache<String, Vec<RenderSubmesh>>,
 );
 
-/// One MCNK chunk's ground clutter as a **lazily-built** unit — the faithful per-chunk `CDetailDoodadInst`
-/// lifecycle (`ground-effects.md` §7): scattered + MCSH/normal-baked at tile-load, but its meshes are
-/// built only while the chunk is within the detail-doodad horizon and torn down past it. This bounds live
-/// grass to a ~70 yd bubble (vs every loaded tile) and spreads the mesh-build over frames instead of one
-/// per-tile hitch. Owned by its tile (despawned on unload, which cascades to `built`).
+/// One MCNK chunk's scattered clutter, meshed only while inside the detail-doodad horizon.
 #[derive(Component)]
 pub(crate) struct ClutterChunk {
-    /// The chunk's clutter AABB in Bevy space (its terrain box, grown by a tuft's height).
-    /// Build/teardown gate on the camera's distance to the BOX — its nearest point — which is what
-    /// "any of this chunk is still within reach" actually means. A centre distance has to carry a
-    /// chunk-radius margin to approximate it, and that margin is a horizontal figure: on relief a
-    /// 33 yd chunk's vertical spread pushes its centre past the margin while its near corner is
-    /// still deep inside the visible band, and the whole chunk's grass pops in on approach (2004).
+    /// The chunk's terrain box grown by a tuft's height, in Bevy space. The gate measures to its
+    /// nearest point, not its centre, so a chunk on relief is not built late.
     bounds: (Vec3, Vec3),
-    /// Scattered placements grouped by model path; each becomes one merged mesh per submesh when built.
+    /// Placements by model path; each model merges into one mesh per submesh.
     models: Vec<(String, Vec<ShadedPlacement>)>,
-    /// The spawned merged meshes while built (children of this entity); empty ⇒ not currently built.
+    /// The built meshes, children of this entity; empty when not built.
     built: Vec<Entity>,
 }
 
-/// Slack (yd) past the reach computed below, so a chunk is built a moment before any of its grass
-/// could be visible and the per-frame build cap has room to spend. Past the reach the ramp is
-/// already alpha 0, so building/tearing down here is invisible — the same reason the reference ties
-/// its build distance to the fade end.
+/// Slack (yd) past the fade reach, so a chunk is built before any of its grass can show.
 const CLUTTER_BUILD_MARGIN: f32 = 8.0;
 
-/// Hysteresis (yd) between the build distance and the teardown distance, so a chunk hovering at the
-/// boundary doesn't thrash build↔despawn every frame.
+/// Hysteresis (yd) between build and teardown, so a chunk at the boundary does not thrash.
 const CLUTTER_TEARDOWN_HYSTERESIS: f32 = 6.0;
 
-/// How far above the terrain surface a tuft reaches (yd) — the chunk's clutter AABB is its terrain
-/// box grown by this, so the gate measures the geometry that actually draws.
+/// How far a tuft reaches above the terrain (yd); the chunk's box is grown by it.
 const CLUTTER_TUFT_HEIGHT: f32 = 3.0;
 
-/// Build at most this many chunks' clutter per frame, so entering a dense area (or a teleport) spreads
-/// the mesh-build + GPU upload over a few frames instead of one stutter.
+/// Most chunks built per frame, so an arrival in a dense area spreads over a few frames.
 const CLUTTER_BUILDS_PER_FRAME: usize = 8;
 
-/// **Step 8 — per-doodad MCSH shadow tint.** Vanilla draws detail doodads UNLIT with a hardcoded
-/// DIFFUSE constant: `0xFFFFFFFF ≈ 1.0` (lit) or `0xFFC0C0C0 ≈ 0.753` (MCSH-shadowed). Picked
-/// per-vertex from the chunk's static MCSH map at the doodad's placement coord. q12 RE:
-/// no day/night, no ambient, no N·L — the only shading
-/// input is this grey. Baked into vertex `ATTRIBUTE_COLOR` at scatter time so the model shader
-/// can `texture × vertex_color` in gamma space (the faithful MODULATE 1×).
+/// The reference's per-tuft detail-doodad diffuse, picked from the chunk's MCSH map at the
+/// placement: `0xFFFFFFFF` lit, `0xFFC0C0C0` shadowed. Baked into the vertex colour.
 const MCSH_LIT: f32 = 1.0;
 const MCSH_SHADOWED: f32 = 192.0 / 255.0; // 0xC0 / 0xFF
 
-/// Sample the chunk's MCSH map at a world-space placement coord. Returns the per-doodad shadow
-/// tint (1.0 lit, ≈0.753 shadowed). Falls back to lit when the chunk has no MCSH (most chunks
-/// don't) or when the position somehow lands outside the chunk's footprint. Coord math: the
-/// chunk's NW corner is `chunk.positions[0]`; +X is north (south distance = `nw_x − wx`), +Y is
-/// west (east distance = `nw_y − wy`); MCSH is row-major over the chunk's 0..1 UV with row=south,
-/// col=east, 64×64 texels.
+/// The MCSH tint at a world position; lit when the chunk has no MCSH or the point falls outside.
+/// MCSH is 64×64, row-major, rows running south and columns east from the chunk's NW corner.
 fn mcsh_tint_at(chunk: &ChunkMesh, world: [f32; 3]) -> f32 {
     let Some(shadow) = chunk.shadow.as_ref() else {
         return MCSH_LIT;
@@ -310,11 +224,8 @@ fn mcsh_tint_at(chunk: &ChunkMesh, world: [f32; 3]) -> f32 {
     }
 }
 
-/// Sample the chunk's MCNR terrain normal (WoW coords) nearest a world-space position — the **ground
-/// normal under the tuft**. Lighting clutter by this (instead of a uniform world-up) makes a tuft
-/// follow the terrain beneath it: darker on a slope facing away from the sun, like the dirt under it
-/// — the per-position sun/shade variation the reference shows. Nearest outer-grid vertex (≈2 yd
-/// spacing) is plenty; falls back to WoW-up (`+Z`) when the chunk has no MCNR.
+/// The MCNR normal (WoW space) at the outer-grid vertex nearest a position, the ground under a
+/// tuft; `+Z` when the chunk has no MCNR.
 fn terrain_normal_at(chunk: &ChunkMesh, world: [f32; 3]) -> [f32; 3] {
     if chunk.normals.len() < 145 || chunk.positions.is_empty() {
         return [0.0, 0.0, 1.0];
@@ -328,23 +239,18 @@ fn terrain_normal_at(chunk: &ChunkMesh, world: [f32; 3]) -> [f32; 3] {
     chunk.normals[row * 17 + col]
 }
 
-/// A scattered placement plus its baked MCSH tint and ground normal — what the merge iterates over.
+/// A scattered placement with its baked MCSH tint and ground normal.
 struct ShadedPlacement {
     placement: GroundDoodadPlacement,
     tint: f32,
-    /// Terrain (ground) normal under the tuft, **Bevy space** — baked onto every vertex so clutter is
-    /// lit by the ground it stands on (`wow_model.wgsl` ground-normal N·L). Same value for all of a
-    /// tuft's vertices ⇒ no per-face view-dependence. VERIFIED faithful: WoW writes the terrain
-    /// quadrant-plane normal onto the clutter vertex normal channel.
+    /// The ground normal under the tuft, in Bevy space, on every vertex: here the MCNR normal of
+    /// the nearest outer-grid vertex ([`terrain_normal_at`]). The reference uses the plane of the
+    /// cell's centre-fan triangle the tuft lands in (planes built at `0x6bfec1`–`0x6bfefe`, the
+    /// triangle picked at `0x6c0148`–`0x6c0193`, the normal stored at `0x6b2a87`–`0x6b2a9c`).
     ground_normal: [f32; 3],
 }
 
-/// **Scatter** a tile's ground clutter into per-chunk [`ClutterChunk`] units — WITHOUT building any
-/// meshes. Each chunk's placements are MCSH/normal-baked here (while the parent chunk is in scope; the
-/// static per-vertex shading matches the real client, baked at map-compile time) and stored on a
-/// `ClutterChunk` entity owned by the tile. [`stream_chunk_clutter`] builds the meshes lazily as chunks
-/// come within the detail-doodad horizon. Empty chunks are skipped (no entity). Replaces the old
-/// build-everything-at-tile-load path.
+/// Scatter a tile's clutter into [`ClutterChunk`]s, tint and normal baked, building no meshes.
 pub(crate) fn scatter_tile_clutter(
     commands: &mut Commands,
     chunks: &[ChunkMesh],
@@ -372,7 +278,6 @@ pub(crate) fn scatter_tile_clutter(
         if by_model.is_empty() {
             continue;
         }
-        // The chunk's terrain AABB in Bevy space — what the LOD system measures against.
         let mut lo = Vec3::splat(f32::MAX);
         let mut hi = Vec3::splat(f32::MIN);
         for p in &chunk.positions {
@@ -380,7 +285,6 @@ pub(crate) fn scatter_tile_clutter(
             lo = lo.min(v);
             hi = hi.max(v);
         }
-        // Tufts stand ON the surface, so the drawn geometry reaches a little above the terrain box.
         hi.y += CLUTTER_TUFT_HEIGHT;
         entities.push(
             commands
@@ -394,15 +298,11 @@ pub(crate) fn scatter_tile_clutter(
     }
 }
 
-/// **Lazily build** one chunk's clutter: merge every instance of each model (within this chunk) into one
-/// mesh per submesh — baking each tuft's yaw/pos/scale + MCSH tint + ground normal into the vertices —
-/// and spawn them as children of `chunk_entity` (so a tile unload cascades to them). Returns the spawned
-/// entities (tracked on the `ClutterChunk` for distance teardown). Same merge as the old per-tile path,
-/// now per-chunk so only the ~70 yd bubble is ever built/drawn.
+/// Build one chunk's clutter: each model's instances merged into one mesh per submesh, every tuft's
+/// transform, tint and ground normal baked in, spawned as children of `chunk_entity`.
 fn build_chunk_clutter(
     chunk_entity: Entity,
     models: &[(String, Vec<ShadedPlacement>)],
-    scale: f32,
     alpha_ref: f32,
     fade_far: f32,
     geometry: &mut ClutterGeometry,
@@ -420,15 +320,11 @@ fn build_chunk_clutter(
         if subs.is_empty() {
             continue;
         }
-        // One merged mesh per submesh (each submesh has its own texture/blend → material).
         for sub in subs.iter() {
             let vcount = sub.positions.len() * placements.len();
             let mut positions = Vec::with_capacity(vcount);
             let mut uvs = Vec::with_capacity(vcount);
-            // Clutter normals = the GROUND normal under each tuft (the terrain quadrant normal WoW
-            // bakes onto the clutter vertex channel — NOT the grass-blade M2 normal). Same value on
-            // every vertex of a tuft ⇒ no per-face view-dependence; the shader lights it like the
-            // terrain beneath.
+            // The ground normal under each tuft, never the blade's own M2 normal.
             let mut normals = Vec::with_capacity(vcount);
             let mut colors = Vec::with_capacity(vcount);
             let mut indices = Vec::with_capacity(sub.indices.len() * placements.len());
@@ -437,11 +333,12 @@ fn build_chunk_clutter(
                 let base = positions.len() as u32;
                 let origin = wow_to_bevy(d.position);
                 let rot = Quat::from_rotation_y(d.yaw);
-                // Per-instance scale (client's random [0.9,1.1]) × the debug-panel size multiplier.
-                let inst_scale = scale * d.scale;
-                // MCSH tint per placement — same value on every vertex of THIS instance, so all
-                // tris of one grass clump share the lit/shadowed colour. The shader multiplies
-                // `texture × vertex_color` in gamma space (the faithful MODULATE 1×).
+                // The reference's random per-tuft scale, in [0.9, 1.1].
+                let inst_scale = d.scale;
+                // One tint per tuft. The reference makes the grey the lit material (colour material
+                // on ambient and diffuse, `0x59cfec`), `clamp(grey × light) × texture`; the shader
+                // multiplies it outside the clamp, `texture × grey × clamp(light)`, so under light
+                // above 1.0 a shadowed tuft comes out darker than the reference's.
                 let tint = [sp.tint, sp.tint, sp.tint, 1.0];
                 for (i, p) in sub.positions.iter().enumerate() {
                     positions.push((rot * (wow_to_bevy(*p) * inst_scale) + origin).to_array());
@@ -458,28 +355,22 @@ fn build_chunk_clutter(
             mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, positions);
             mesh.insert_attribute(Mesh::ATTRIBUTE_UV_0, uvs);
             mesh.insert_attribute(Mesh::ATTRIBUTE_NORMAL, normals);
-            // Step 8: per-vertex MCSH tint (1.0 lit / ≈0.753 shadowed). Triggers Bevy's
-            // `VERTEX_COLORS` shader def → `pbr_input.material.base_color` becomes
-            // `vertex_color × texture`. Read by the clutter path in `wow_model.wgsl`.
+            // The MCSH tint, under the `VERTEX_COLORS` def the shader's clutter path reads.
             mesh.insert_attribute(Mesh::ATTRIBUTE_COLOR, colors);
             mesh.insert_indices(Indices::U32(indices));
             let mesh = meshes.add(mesh);
-            // **The detail-doodad pass owns its render state** — it is not the batch's (2004).
-            // The reference sets one state for every tuft in the frame (`0x6b2b80`: blend mode 2
-            // = SRC_ALPHA/INV_SRC_ALPHA, ALPHAREF = `detailDoodadAlpha` 128, cull OFF, depth-write
-            // ON) and its per-slot draw `0x6b2d60` binds nothing but the texture — the M2 batch's
-            // own blend/cull is never consulted for a detail doodad. Passing `sub.blend` through
-            // gave the two Opaque-authored detail models no cutout at all (their transparent
-            // margin drew as solid card) and left five single-sided ones showing only one face.
+            // The detail-doodad pass owns the render state, never the batch: the reference sets one
+            // for every tuft (`0x6b2b80`: alpha blend, ALPHAREF `detailDoodadAlpha`, cull off,
+            // depth write on), and its per-slot draw `0x6b2d60` binds only the texture.
             let material = assets.model_material(
                 sub.texture.as_deref(),
                 ModelBlend::AlphaTest, // the pass's cutout, not the batch's authored blend
                 true,                  // cull off for every tuft, like the reference's pass
-                Some(alpha_ref), // detail-doodad alpha-test ref (≈0.5), not the higher general key
-                Some(fade_far),  // detail-doodad distance fade (≈70 yd horizon — opacity, dc30e1f)
-                false,           // clutter is not WMO (keeps its ground-normal N·L path)
-                false, // not a doodad fade twin (clutter's own clutter_fade path handles it)
-                (sub.wrap_x, sub.wrap_y), // the M2 texture record's own address mode (0763)
+                Some(alpha_ref),       // the detail-doodad alpha-test ref, not the general key
+                Some(fade_far),        // the detail-doodad distance fade
+                false,                 // not WMO: keeps the ground-normal N·L path
+                false,                 // not a doodad fade twin: clutter fades on its own path
+                (sub.wrap_x, sub.wrap_y), // the M2 texture record's own address mode
                 images,
                 materials,
             );
@@ -491,12 +382,8 @@ fn build_chunk_clutter(
         }
     }
     if !out.is_empty() {
-        // Parent the freshly-built clutter to its chunk — but tolerate the chunk having been despawned
-        // before this command applies. A cross-map teleport (or any tile unload) despawns the tile,
-        // which cascades to its `ClutterChunk` children; a plain `commands.entity(..).add_children`
-        // then PANICS on the dead parent (the Ashenvale-teleport crash). Check at apply time, and if the
-        // parent is gone, despawn the orphan clutter we just spawned so it doesn't leak as parentless
-        // (world-baked) geometry.
+        // Parent at apply time: a tile unload in between despawns the chunk, and `add_children`
+        // on a dead parent panics, so the orphans are despawned instead.
         let children = out.clone();
         commands.queue(
             move |world: &mut World| match world.get_entity_mut(chunk_entity) {
@@ -516,36 +403,22 @@ fn build_chunk_clutter(
     out
 }
 
-/// Squared distance from a point to an axis-aligned box — zero inside it. The clutter LOD's measure:
-/// "is any of this chunk within reach", which a centre distance can only approximate.
+/// Squared distance from a point to an axis-aligned box, zero inside.
 fn box_distance_squared(p: Vec3, (lo, hi): (Vec3, Vec3)) -> f32 {
     (lo - p).max(p - hi).max(Vec3::ZERO).length_squared()
 }
 
-/// How far (as a multiple of the fade horizon) a chunk can sit from the eye and still have grass the
-/// shader will draw.
-///
-/// The fade is keyed on **view-space depth** (`wow_model.wgsl`, the reference's camera-space texgen),
-/// so the horizon is a plane across the view, not a sphere around the eye: a fragment out at the
-/// frustum's corner is `1/cos θ` further in straight-line distance than one dead ahead at the same
-/// depth. The LOD gate measures straight-line distance — it must not depend on where the camera
-/// happens to be pointing, or a turn would drop and rebuild chunks that are still being drawn — so it
-/// takes the worst case, the corner ray, and that is exactly this factor. Derived from the live
-/// projection rather than pinned, because it moves with the aspect ratio: ~1.31 at 16:9 and ~1.45 at
-/// 21:9, and a constant tuned on one monitor silently clips the screen edges on a wider one.
+/// The fade horizon's reach along the frustum's corner ray, as a multiple of it: the fade is on
+/// view depth (the reference's camera-space texgen), the gate on a distance that ignores heading.
 fn frustum_corner_reach(fov_y: f32, aspect: f32) -> f32 {
     let tan_v = (fov_y * 0.5).tan();
     let tan_h = tan_v * aspect;
     (1.0 + tan_v * tan_v + tan_h * tan_h).sqrt()
 }
 
-/// The per-chunk clutter LOD: build a chunk's clutter when its BOX comes within reach of the
-/// detail-doodad horizon and tear it down when it leaves — the reference's `CDetailDoodad` lifecycle
-/// (per-chunk build/unlink at the 70 yd `[0x867958]`, which it measures as the nearest view-space
-/// depth of the chunk's bounding sphere and then never frees). Bounds live grass to a bubble around
-/// the player instead of every loaded tile and, with the per-frame build cap, spreads the cost so a
-/// tile-load no longer builds 256 chunks at once. Build/teardown happen where the fade ramp is
-/// already alpha 0, so they are invisible.
+/// Build a chunk's clutter when its box comes within the fade reach, and tear it down past it,
+/// where the fade is already zero. The reference builds and unlinks per chunk at 70 yd
+/// (`[0x867958]`), by the nearest view depth of the chunk's bounding sphere.
 pub(crate) fn stream_chunk_clutter(
     mut commands: Commands,
     cam: Query<(&GlobalTransform, Option<&Projection>), With<WorldCamera>>,
@@ -557,10 +430,7 @@ pub(crate) fn stream_chunk_clutter(
     mut images: ResMut<Assets<Image>>,
     mut materials: ResMut<Assets<WowModelMaterial>>,
 ) {
-    // Both come from `setup_clutter`, which inserts neither when there is no client data — and a
-    // hard `ResMut` here is a *validation* failure, not a `None` the body can handle: the system
-    // never runs, Bevy's default error handler panics, and a client that found no install died on
-    // its first frame instead of sitting at the login screen (decision 1451).
+    // Both are absent without an install, and a hard `ResMut` would fail validation and panic.
     let (Some(mut geometry), Some(mut assets)) = (geometry, assets) else {
         return;
     };
@@ -568,9 +438,8 @@ pub(crate) fn stream_chunk_clutter(
         return;
     };
     let cam_pos = cam_tf.translation();
-    // The straight-line reach the view-depth fade implies at the frustum's corner (see the helper).
-    // A missing/non-perspective projection falls back to Bevy's own perspective default, the one
-    // `view.rs` leaves in place (≈ the reference's 44.1° vertical) at 16:9.
+    // Without a perspective projection, Bevy's default stands in: the one `view.rs` keeps, about
+    // the reference's 44.1° vertical, at 16:9.
     let reach = cfg.fade_far
         * match projection {
             Some(Projection::Perspective(p)) => frustum_corner_reach(p.fov, p.aspect_ratio),
@@ -581,22 +450,10 @@ pub(crate) fn stream_chunk_clutter(
         };
     let build_d2 = (reach + CLUTTER_BUILD_MARGIN).powi(2);
     let drop_d2 = (reach + CLUTTER_BUILD_MARGIN + CLUTTER_TEARDOWN_HYSTERESIS).powi(2);
-    // The LATE-BUILD tripwire (2012). A chunk built while its nearest corner is ALREADY inside the
-    // fade horizon had grass the player could see before the mesh existed — the "it popped in"
-    // class, and the thing to rule out first whenever clutter is reported appearing abruptly.
-    // Straight-line distance under the horizon implies view depth under it too, so this catches
-    // every genuinely-visible case (and some invisible ones, which is the safe direction). Two
-    // causes, and the line says which: the gate let it through late, or the per-frame cap deferred
-    // it — the second is expected in the burst right after a login or a teleport, when the whole
-    // bubble is built at once, and is why this reports the backlog rather than just the count.
+    // The late-build tripwire: a chunk built already inside the horizon pops in where it is seen.
     let visible_d2 = cfg.fade_far.powi(2);
 
-    // Pass 1: measure every chunk, tear down what has left, and collect what wants building.
-    // **Nearest first** (2012). The build budget is spent in whatever order the query hands the
-    // chunks over, which is archetype order — so a chunk 90 yd away, where the ramp is already
-    // alpha 0 and nobody can see it, would take a build slot ahead of one at 48 yd that is inside
-    // the visible band. On a cold fill that is a pop with a free fix: sort the candidates by
-    // distance and the cap always buys the most visible grass first.
+    // Pass 1: tear down what has left; collect the rest nearest first, for the per-frame cap.
     let mut wanted: Vec<(f32, Entity)> = Vec::new();
     for (ent, mut cc) in &mut chunks {
         let d2 = box_distance_squared(cam_pos, cc.bounds);
@@ -626,7 +483,6 @@ pub(crate) fn stream_chunk_clutter(
         let built = build_chunk_clutter(
             ent,
             &cc.models,
-            cfg.scale,
             cfg.alpha_ref,
             cfg.fade_far,
             &mut geometry,
@@ -638,13 +494,8 @@ pub(crate) fn stream_chunk_clutter(
         );
         cc.built = built;
     }
-    // Two cases, and only one is a defect — the message always said so, but BOTH were warnings, so
-    // the benign one cried wolf. A login/teleport burst has a BACKLOG: the per-frame cap is why the
-    // near chunks are late, and the whole burst runs behind the loading cover. The director's
-    // 2026-09-15 log has three of these at t+1.7 s under a cover that did not lift until t+4.3 s —
-    // including one announcing grass at 4.4 yd that nobody could possibly have seen. With NO
-    // backlog the cap is not the cause: the distance gate let a near chunk through late on an
-    // ordinary frame, the player can see that one, and that one still warns.
+    // With a backlog the cap made it late, the expected burst behind a login or teleport's loading
+    // cover; with none the distance gate let a visible chunk through late, a defect.
     if late > 0 {
         if backlog > 0 {
             debug!(
@@ -668,21 +519,16 @@ pub(crate) fn stream_chunk_clutter(
 mod tests {
     use super::*;
 
-    /// The ramp `wow_model.wgsl` evaluates, mirrored here so the reference's four landmarks are
-    /// **checkable** rather than a comment. Not a second implementation to keep in sync — a pin: if
-    /// anyone retunes `0.75`, the `254`/`256` texel-centre constants or the `252/255` cap without
-    /// re-deriving them, these numbers move and the test says so.
+    /// The fade ramp `wow_model.wgsl` evaluates, mirrored as a pin on its constants.
     fn ramp(z: f32, far: f32) -> f32 {
         let near = far * 0.75;
         let u = (z - near) / (far - near);
         ((254.0 - 256.0 * u) / 255.0).clamp(0.0, 252.0 / 255.0)
     }
 
-    /// wow-re `terrain/scratch/detail-doodad-distance-fade.md`: a 64-texel CLAMP/LINEAR ramp whose
-    /// texel centres give `alpha = (254 − 256u)/255`, capped at texel 0's `252/255`. So the plateau
-    /// runs to 52.63672 yd (not 52.5), the ramp hits zero at 69.86328 yd (not 70), the slope is
-    /// −0.0573670 per yard, and the 128/255 detail-doodad cutout erases a fully-opaque texel at
-    /// 61.11328 yd — the horizon grass actually vanishes at, well short of the 70 yd draw distance.
+    /// The reference's 64-texel clamp/linear ramp (`0x6b235b` fills it, `[0x867958]` = 70 anchors
+    /// it): `alpha = (254 − 256u)/255` capped at `252/255`, so the plateau ends at 52.63672 yd,
+    /// zero falls at 69.86328 yd, and the 128/255 cutout erases opaque grass at 61.11328 yd.
     #[test]
     fn the_ramp_hits_the_reference_landmarks() {
         assert!(
@@ -701,25 +547,20 @@ mod tests {
         assert_eq!(ramp(70.0, 70.0), 0.0);
         let slope = ramp(60.0, 70.0) - ramp(61.0, 70.0);
         assert!((slope - 0.0573670).abs() < 1e-6, "slope per yard");
-        // The cutout erases a fully-opaque texel where the ramp crosses the 128/255 reference.
         assert!(ramp(61.11328, 70.0) < DETAIL_DOODAD_ALPHA_REF + 1e-5);
         assert!(ramp(61.11, 70.0) > DETAIL_DOODAD_ALPHA_REF);
     }
 
-    /// The gate measures the chunk's box, not its centre: zero inside, and the nearest point outside.
     #[test]
     fn box_distance_measures_the_nearest_point() {
         let b = (Vec3::new(-1.0, -1.0, -1.0), Vec3::new(1.0, 1.0, 1.0));
         assert_eq!(box_distance_squared(Vec3::ZERO, b), 0.0);
         assert_eq!(box_distance_squared(Vec3::new(4.0, 0.0, 0.0), b), 9.0);
-        // A tall thin chunk: a point level with the top face is 3 yd away, though its CENTRE — the
-        // old measure — is 5 yd away. That gap is the relief case that popped whole chunks.
+        // A tall chunk: the point is 3 yd from its top face but 5 yd from its centre.
         let tall = (Vec3::new(-1.0, -4.0, -1.0), Vec3::new(1.0, 4.0, 1.0));
         assert_eq!(box_distance_squared(Vec3::new(4.0, 4.0, 0.0), tall), 9.0);
     }
 
-    /// The fade is keyed on view depth, so the LOD's straight-line reach is the corner ray's — and it
-    /// widens with the aspect ratio, which is why it is derived and not pinned to one monitor.
     #[test]
     fn the_corner_reach_widens_with_the_aspect() {
         let fov = PerspectiveProjection::default().fov;
diff --git a/crates/benilla-world/src/collision.rs b/crates/benilla-world/src/collision.rs
index 48e68a76..c95b56b0 100644
--- a/crates/benilla-world/src/collision.rs
+++ b/crates/benilla-world/src/collision.rs
@@ -1,14 +1,8 @@
-//! Physics **collision layers** — the two collision *audiences* the world geometry is queried by.
-//!
-//! The player body and the third-person camera collide against *different* sets of WMO faces (a
-//! binary-VERIFIED 1.12.1 fact; see `benilla_formats`'s MOPY mask doc and wow-5875-re
-//! `system/collision/collision.md`): the **walking** gather drops DETAIL faces (`0x04`), the
-//! **camera/LOS** gather instead drops NOCAMCOLLIDE faces (`0x02`) — so the camera collides with
-//! visible decals/overhangs (forge pipes, low beams) the player walks *under*, and passes through
-//! NOCAMCOLLIDE faces the player still stands on. avian can't filter a single trimesh per-face, so
-//! each WMO bakes two colliders, separated by these layers; the player and camera queries pick their
-//! audience by mask. Everything else — terrain, doodads, GameObjects — sits on the default layer and is
-//! collided by **both** (so it needs no explicit layer).
+//! World collision: the layers and traces the body and the camera query. The reference's walking
+//! box query (leaf `0x6bca50`) drops MOPY DETAIL faces (`0x04`) and its camera/LOS segment query
+//! (leaf `0x6bc700`) drops NOCAMCOLLIDE faces (`0x02`), so the camera hits a low beam the body
+//! walks under. avian cannot filter one trimesh per face, so each WMO bakes one collider per
+//! audience; terrain, doodads and GameObjects sit on the default layer, which both see.
 
 use avian3d::character_controller::move_and_slide::{
     MoveAndSlide, MoveAndSlideConfig, MoveAndSlideHitData, MoveAndSlideHitResponse,
@@ -23,111 +17,66 @@ use bevy::math::{Dir3, Quat, Vec3};
 
 mod one_sided;
 
-/// The collision audiences. avian reserves bit 0 for [`CollisionLayer::Default`], which every collider
-/// without an explicit `CollisionLayers` belongs to — so terrain/doodad/GameObject colliders are seen by
-/// both the player and camera queries automatically. Only the two per-WMO meshes carry an explicit layer.
+/// The collision audiences. avian puts every collider without explicit `CollisionLayers` on bit 0,
+/// [`CollisionLayer::Default`]; only WMO faces and liquid carry a layer.
 #[derive(PhysicsLayer, Default, Clone, Copy)]
 pub(crate) enum CollisionLayer {
-    /// Geometry both audiences collide with: terrain, doodads, GameObjects (the default layer).
+    /// Terrain, doodads and GameObjects, which both audiences collide with.
     #[default]
     Default,
-    /// WMO faces only the **player body** collides with — the walking gather (skip DETAIL `0x04`).
+    /// A WMO's walking collider, every face but DETAIL (`0x04`); only the body sees it.
     Walk,
-    /// WMO faces only the **camera** collides with — the camera/LOS gather (skip NOCAMCOLLIDE `0x02`).
+    /// A WMO's camera/LOS collider, every face but NOCAMCOLLIDE (`0x02`); only the camera sees it.
     Camera,
-    /// **Liquid surfaces** — the wet-cell lattice of every MCLQ layer and WMO pool, on a layer of
-    /// their own so that *no* query sees them unless it asks.
-    ///
-    /// This is `cameraWaterCollision`'s primary consumer and the shape the reference gives it: the
-    /// CVar does not re-lane any geometry, it adds `0xf0000` to the **trace mask** the solver hands
-    /// its three collision queries (`0x50e5ec`; the nibble is read at `0x69cc13` and gates a
-    /// per-layer intersection over the chunk's four MCLQ slots — `0x10000` river/lake, `0x20000`
-    /// ocean, `0x40000` magma, `0x80000` slime). A per-trace mask is exactly a `SpatialQueryFilter`,
-    /// which is why this is a layer and not a component the camera looks for.
-    ///
-    /// wow-re `ui/scratch/water-band-discontinuity.md`. It **refutes** that tree's own
-    /// `camera-arm-liquid-blind.md` §2, a VERIFIED NEGATIVE that stood from June: the census was
-    /// correct and controlled, but a capability requested through an argument flag is invisible to
-    /// any census of call sites. Decision 2149 rested benilla on that verdict and built the wrong
-    /// half of the feature; 2165 took it out.
+    /// Liquid surfaces, every MCLQ layer's and WMO pool's wet cells, hit only by a query that asks.
+    /// `cameraWaterCollision` ORs `0xf0000` into the trace mask the camera solver hands its three
+    /// collision queries (`0x50e5ec`), and `0x69cc13` reads that nibble to gate the chunk's four
+    /// MCLQ slots (`0x10000` river/lake, `0x20000` ocean, `0x40000` magma, `0x80000` slime).
     Liquid,
 }
 
-/// **The camera-collision probe radius (yd)** — the sphere [`WorldCollision::cast_camera`] sweeps
-/// along the boom against the SOLID world.
-///
-/// It is the margin kept between the camera and the surface it stops at, so the near plane does
-/// not poke through the wall; smaller than the player capsule, so the camera threads gaps the body
-/// cannot. **benilla's own construction** — the reference's camera trace is a bare ray
-/// (`0x672170`) with no radius anywhere on it.
-///
-/// It lives *here*, in the crate that owns the trace, rather than beside the camera that spawns
-/// the probe, because a fixture that sweeps a different radius than the client ships is an
-/// instrument reading itself: decision 2179's gate swept `0.15` against a client shipping `0.3`
-/// and certified a camera that was being slammed onto the character on every level surface swim
-/// (2185). Nothing may hardcode this number.
+/// The camera probe's radius (yd) against the solid world. Deviation: the reference's camera
+/// trace is a bare ray (`0x672170`); the sphere keeps the near plane out of a wall. Nothing may
+/// hardcode it: a fixture sweeping another radius tests another client.
 pub const CAMERA_PROBE_RADIUS: f32 = 0.3;
 
-/// `CollisionLayers` for a WMO's **walking** collider — member of [`CollisionLayer::Walk`] only, so the
-/// camera query (which omits `Walk`) never hits it.
+/// `CollisionLayers` for a WMO's walking collider, which the camera query never hits.
 pub(crate) fn walk_layers() -> CollisionLayers {
     CollisionLayers::new(CollisionLayer::Walk, LayerMask::ALL)
 }
 
-/// `CollisionLayers` for a WMO's **camera/LOS** collider — member of [`CollisionLayer::Camera`] only, so
-/// the player movement query (which omits `Camera`) never hits it.
+/// `CollisionLayers` for a WMO's camera/LOS collider, which the body query never hits.
 pub(crate) fn camera_layers() -> CollisionLayers {
     CollisionLayers::new(CollisionLayer::Camera, LayerMask::ALL)
 }
 
-/// `CollisionLayers` for a **liquid surface** — member of [`CollisionLayer::Liquid`] only.
-///
-/// Every existing filter omits that bit, so these colliders are inert to the body, the camera, the
-/// mouse pick and the particle snap alike until a query asks for them by name. A swimmer must not
-/// be stopped by the water they are in, and nothing but the camera sweep under
-/// `cameraWaterCollision` has any business hitting a waterline.
+/// `CollisionLayers` for a liquid surface, inert to every query that does not ask for it: a
+/// swimmer is never stopped by the water they are in.
 pub(crate) fn liquid_layers() -> CollisionLayers {
     CollisionLayers::new(CollisionLayer::Liquid, LayerMask::ALL)
 }
 
-/// **How many times the world's collider set has changed** — bumped when [`crate::terrain_stream`]
-/// attaches a batch of built colliders, and when any collider is removed (a tile or placement
-/// streaming out, an entity despawning).
-///
-/// It exists because a cached collision *answer* is only as good as the world it was computed
-/// against. The one consumer today is the creature ground clamp's cast gate (decision 1357), which
-/// holds a hit while the unit's own inputs are unchanged: the unit's position and the colliders
-/// under it. It could see the first half change and not the second, so a unit that took its answer
-/// from a half-arrived world — the terrain under a building, before the building's own floor
-/// collider had attached — held that answer forever and stood under the floor for the rest of the
-/// session. A stamp on the collider set closes that: an answer computed at one stamp is re-asked at
-/// the next.
-///
-/// A `u64` counter, not a dirty flag: the gate compares its own recorded stamp, so it never has to
-/// coordinate with other readers about who clears it.
+/// How many times the world's collider set has changed: bumped when [`crate::terrain_stream`]
+/// attaches a batch of colliders and when any collider is removed. A cached collision answer (the
+/// creature ground clamp's) holds only at the stamp it was computed at.
 #[derive(Resource, Default)]
 pub struct ColliderEpoch(u64);
 
 impl ColliderEpoch {
-    /// The current stamp — recorded alongside a cached collision answer, compared to decide whether
-    /// that answer still describes this world.
+    /// The current stamp, recorded beside a cached collision answer.
     pub fn get(&self) -> u64 {
         self.0
     }
 
-    /// **The collider set changed** — call this from any lane that inserts a collider outside the
-    /// streamer's own attach queue (the GameObject hull lane is the one such lane today, decision
-    /// 0761). A lane that forgets leaves a cached answer dated against a world that no longer
-    /// exists; the cost of an over-eager bump is one re-cast.
+    /// Records a change. Any lane that inserts a collider outside the streamer's attach queue (the
+    /// GameObject hull lane) must call it.
     pub fn bump(&mut self) {
         self.0 = self.0.wrapping_add(1);
     }
 }
 
-/// Bump [`ColliderEpoch`] for the *removal* half (the attach half is published by the streamer's
-/// own attach loop, which already counts what it did). Despawning an entity emits removal events
-/// for its components, so this covers tile/placement stream-out and object destroys alike; reading
-/// the queue is O(removals), which is zero on almost every frame.
+/// Bumps [`ColliderEpoch`] on any collider removal, despawns included; the streamer's attach loop
+/// bumps for its own attaches.
 pub(crate) fn track_collider_removals(
     mut removed: RemovedComponents<Collider>,
     mut epoch: ResMut<ColliderEpoch>,
@@ -137,62 +86,31 @@ pub(crate) fn track_collider_removals(
     }
 }
 
-/// Marks a static trimesh collider whose triangles **receive ground decals** (the selection ring).
-/// The reference's decal collector is byte-verified (wow-re selection-circle RE, §5-cross-checked):
-/// its box query gathers **terrain triangles + WMO group faces** — M2 doodads/GameObjects/units are
-/// *never* collected (no collector exists for them; the ring draws under barrels, not onto them) —
-/// with the decal draw sites passing flags `0x200122` (terrain on, WMO on, liquid off). The WMO side
-/// filters faces only by a MOPY **material-class mask `0x88`** (no walkability/up-facing test — which
-/// is why the reference ring drapes down vertical step faces). We mark the WMO **walk** collider as
-/// the interim WMO face set — all faces minus DETAIL (`0x04`) — which differs from the reference's
-/// minus-`0x88`-classes set only on those flagged faces (exact parity would need a third per-WMO face
-/// bake; deferred until the MOPY `0x88` class semantics are RE'd).
+/// Marks a static trimesh that receives ground decals (the selection ring). The reference collects
+/// only terrain and WMO group faces (`0x6ad2c0` calls only `0x6ad330`/`0x6ad4e0`; draw flags
+/// `0x200122`, liquid off), so the ring draws under a barrel, not onto it, and filters WMO faces
+/// by MOPY class mask `0x88` alone, so it drapes down step faces. The mark rides the WMO walk
+/// collider (every face but DETAIL `0x04`); a `0x88` face set of its own is not built.
 #[derive(Component)]
 pub struct GroundDecalSurface;
 
-/// Marks a static collider that **occludes the mouse pick** — the reference's scene trace also
-/// traces the world and discards the object hit iff the world hit is *strictly nearer* (wow-re
-/// selection-circle RE PART 3, §5-cross-checked 2026-07-20: `0x480df0` @ `0x480eb4`,
-/// `CWorld::Intersect 0x672170` mask `0x1000114`), so a unit/GameObject behind a wall is not
-/// hoverable. The byte-decoded occluder set, and what carries the mark: **terrain** tiles (DDA
-/// `0x69c920`), **WMO group faces** with MOPY reject-mask `0x84` — the **walk** bake (reject
-/// `0x04`) is the nearest existing face set, differing only on `0x80`-flagged faces (exact parity
-/// needs a third per-WMO bake, the same deferral as the decal path's `0x88`) — and **static
-/// default-set map doodad hulls** (`0x69cdb0`; map doodads + WMO props here). NOT marked, per the
-/// same decode: liquid (mask bits 16-19 are off on the pick path), server-spawned GameObject
-/// hulls and units (they are the *object* trace — a chest must not occlude itself), and transport
-/// hulls (the 0466 law: an NPC on deck stays hoverable through the railing).
+/// Marks a static collider that occludes the mouse pick: the reference traces the world too and
+/// drops the object hit when the world hit is strictly nearer (`0x480df0` at `0x480eb4`,
+/// `CWorld::Intersect` `0x672170`, mask `0x1000114`), so a unit behind a wall is not hoverable.
+/// Occluders are terrain (DDA `0x69c920`), WMO group faces outside MOPY reject mask `0x84` (here
+/// the walk collider, which rejects only `0x04`: a `0x84` face set is not built) and static
+/// default-set doodad hulls (`0x69cdb0`). Liquid (mask bits 16-19 off) is not, nor are unit and
+/// server-spawned GameObject hulls, transports included: those are the object trace.
 #[derive(Component)]
 pub struct PickOccluder;
 
-/// **Colliders this frame's local mover must not see** — the game's half of the reference's
-/// per-trace collision mask.
-///
-/// The engine cannot compute this: "a GameObject whose type is DOOR, while the player is a ghost"
-/// names two gameplay concepts, and the engine names nothing of the game (this crate's other API
-/// wall). So the game publishes the entity set and [`WorldCollision::cast_mover`] applies it.
-///
-/// Empty on every ordinary frame, which is what makes the living player's query provably the one it
-/// always was.
+/// Colliders the local mover's trace skips this frame (the game's half of the reference's
+/// per-trace mask), applied by [`WorldCollision::cast_mover`]; empty on an ordinary frame.
 #[derive(Resource, Default)]
 pub struct MoverTraceExclusions(pub bevy::ecs::entity::EntityHashSet);
 
-/// **Trace a body through the world** — the engine's movement-collision face.
-///
-/// Every one of the four one-sided casts took the same two leading arguments (avian's
-/// `MoveAndSlide`, and a `SpatialQueryFilter` the caller built on the line before), and every
-/// caller built the *same* filter. Both are the engine's business: which collision layers a body
-/// sees is a property of how the world was baked (the two per-WMO face sets, `CollisionLayer`),
-/// not a choice a mover gets to make.
-///
-/// **Deliberately not merged with `WorldPoint`** (1164 item 11): `ground_normal_under` here and
-/// `terrain_height_under` there answer "what is the ground" from two different worlds — a physics
-/// trimesh and an MCNK heightfield — and merging them would put avian's `MoveAndSlide` in the
-/// signature of every zone-text and footstep reader.
-///
-/// The **one-sidedness** is the whole reason these are not avian's own calls: the reference
-/// discards a face approached from its back before computing any distance, and that gate has to
-/// run where candidates are enumerated (see [`one_sided`]'s header, decisions 0967/0968).
+/// Traces a body through the world one-sided: the reference drops a face approached from its back
+/// before any distance test, so the gate runs where candidates are enumerated ([`one_sided`]).
 #[derive(bevy::ecs::system::SystemParam)]
 pub struct WorldCollision<'w, 's> {
     ms: MoveAndSlide<'w, 's>,
@@ -200,54 +118,29 @@ pub struct WorldCollision<'w, 's> {
 }
 
 impl WorldCollision<'_, '_> {
-    /// What a walking **body** collides with: the default layer (terrain, doodads, GameObjects)
-    /// plus the walk-only WMO faces — and never the camera-only ones.
-    ///
-    /// Exposed for the two lanes that hand a filter to something other than these casts (the mouse
-    /// pick's occlusion trace, the mount-tilt probe); everything else should use the methods
-    /// below, which apply it themselves.
+    /// What a walking body collides with: the default layer and the WMO walking colliders. Public
+    /// for the lanes that hand a filter elsewhere (the mouse pick's occlusion trace, the mount-tilt
+    /// probe); the casts below apply it themselves.
     pub fn body_filter() -> SpatialQueryFilter {
         SpatialQueryFilter::from_mask(LayerMask(
             CollisionLayer::Default.to_bits() | CollisionLayer::Walk.to_bits(),
         ))
     }
 
-    /// …and what the third-person **camera** collides with: the other way round on those two WMO
-    /// face layers (it takes NOCAMCOLLIDE faces the body walks through, and skips the DETAIL faces
-    /// the body walks on).
-    ///
-    /// **The waterline is deliberately not in here** — it rides its own ray
-    /// ([`waterline_ray`](Self::waterline_ray)), for the reason spelled out there. This mask is the
-    /// SOLID world only, and is byte-for-byte the filter it always was.
+    /// What the camera collides with: the default layer and the WMO camera/LOS colliders, so it
+    /// hits DETAIL faces the body passes and passes NOCAMCOLLIDE faces the body stands on. The
+    /// solid world only: the waterline rides [`waterline_ray`](Self::waterline_ray).
     pub(crate) fn camera_filter() -> SpatialQueryFilter {
         SpatialQueryFilter::from_mask(LayerMask(
             CollisionLayer::Default.to_bits() | CollisionLayer::Camera.to_bits(),
         ))
     }
 
-    /// **The waterline leg of the camera trace — a RAY, not the probe sphere** (decision 2185).
-    ///
-    /// `cameraWaterCollision` is a trace mask (`0x50e5ec` ORs `0xf0000` into the word the solver
-    /// hands its three collision queries), and the query that word rides is a **line segment**:
-    /// `0x672170` takes `(start, end, out, frac, flags)` and carries no radius at all, bottoming
-    /// out in the Möller–Trumbore ray/triangle test at `0x7c2c40` (wow-re
-    /// `camera-water-atomicity.md` §145, `camera-cvar-kernels.md` §276). The reference's whole
-    /// camera trace is that ray; benilla's is a [`CAMERA_PROBE_RADIUS`] sphere, which is **our own
-    /// construction** — the margin that keeps the near plane out of a wall — and it stays, because
-    /// walls are what it is for.
-    ///
-    /// It cannot stay for water, because the corridor's clearance is a reference constant sized
-    /// for a ray. Arm A lifts the sweep origin to `surface + 2/9 = 0.2222` yd, and the probe's
-    /// radius is `0.3`: centred on that floor the sphere hangs **78 mm through the water plane
-    /// before the sweep has moved at all**, so a level camera behind a surface swimmer was returned
-    /// a hit at distance zero — the camera slammed onto the character, every frame the boom ran
-    /// flat. Tip it a couple of degrees down and the sweep escapes the plane and the hit vanishes;
-    /// that flip, against a snap-in/ease-out arm, is the "snaps in for a second every couple of
-    /// seconds" a surface swim was reported with.
-    ///
-    /// Two-sided, like the shape sweep beside it and for the same reason: a camera crossing the
-    /// surface from underneath has no facing contract to honour, it just must not end up through
-    /// the plane.
+    /// The waterline leg of the camera trace, a ray: `cameraWaterCollision` ORs `0xf0000` into the
+    /// solver's trace mask (`0x50e5ec`), and that trace is a segment with no radius (`0x672170`,
+    /// Möller–Trumbore at `0x7c2c40`). The swim corridor's `surface + 2/9` yd clearance is sized
+    /// for that ray: a [`CAMERA_PROBE_RADIUS`] sphere on the corridor floor starts 78 mm through
+    /// the plane. Two-sided, like the solid sweep.
     fn waterline_ray(&self, from: Vec3, movement: Vec3) -> Option<f32> {
         let Ok(dir) = Dir3::new(movement) else {
             return None;
@@ -275,18 +168,8 @@ impl WorldCollision<'_, '_> {
         self.cast_body_with(shape, from, movement, skin_width, &Self::body_filter())
     }
 
-    /// [`cast_body`](Self::cast_body) against a **caller-supplied** filter.
-    ///
-    /// It exists for one caller and one reason: the reference's world trace carries a per-trace
-    /// mask, and a GHOST's mask drops DOOR GameObjects from the gather — a ghost walks through
-    /// closed doors (wow-re `collision/scratch/ghost-door-tracemask.md`). That is a property of
-    /// *this mover's trace*, not of the door, so it cannot be expressed by re-laning the collider:
-    /// [`body_filter`](Self::body_filter) is shared with the particle snap, the precipitation
-    /// probe, the mouse pick and the creature conform, none of which may lose a door because the
-    /// local player happens to be dead.
-    ///
-    /// The living case passes [`body_filter`](Self::body_filter) itself, so it is the same query it
-    /// always was — byte for byte, by construction rather than by inspection.
+    /// [`cast_body`](Self::cast_body) against a caller-supplied filter: the mover's own trace mask,
+    /// which the shared [`body_filter`](Self::body_filter) must not carry.
     fn cast_body_with(
         &self,
         shape: &Collider,
@@ -298,29 +181,10 @@ impl WorldCollision<'_, '_> {
         one_sided::cast_move(&self.ms, shape, from, movement, skin_width, filter)
     }
 
-    /// Sweep the **camera boom** against the camera's world — the distance along `movement` the
-    /// arm is free to reach, or `None` for an unobstructed boom.
-    ///
-    /// Deliberately avian's own two-sided cast rather than the one-sided law above: the facing
-    /// gate exists because a *body* must not stand on a face wound away from it, and a camera has
-    /// no such contract — it just must not end up inside geometry, from either side.
-    ///
-    /// **Two legs, two shapes, and that is the point** (decision 2185). The solid world is swept
-    /// with the caller's probe sphere, which is benilla's own margin against a wall's near plane;
-    /// the waterline is a bare ray, which is the reference's own geometry and the only shape that
-    /// fits through the clearance the corridor budgets for it — see
-    /// [`waterline_ray`](Self::waterline_ray). `liquid` is `cameraWaterCollision`, straight
-    /// through: with it clear the water leg does not run and this is the query it always was.
-    ///
-    /// The nearer of the two wins, which is what one trace carrying both classes would have done.
-    ///
-    /// **The probe is this function's, not the caller's.** It used to be threaded in from a
-    /// `CameraProbe` resource in `benilla-app`, along with a rotation that was always the identity
-    /// (a sphere has no orientation) and a skin width that was always zero — three arguments of
-    /// noise around one number that belongs to the trace. That number is [`CAMERA_PROBE_RADIUS`],
-    /// and the whole of decision 2185 is that it must be read in the same place the clearance it
-    /// has to fit through is (`crates/benilla-app/tests/world_api_wall.rs` is what made the point:
-    /// exporting the constant widened the doorway, and owning the probe closes it instead).
+    /// Sweeps the camera boom: how far along `movement` the arm may reach, `None` when clear.
+    /// Two-sided, since a camera has no facing contract. The solid world takes a
+    /// [`CAMERA_PROBE_RADIUS`] sphere; with `liquid` (`cameraWaterCollision`) set, the waterline
+    /// takes a ray ([`waterline_ray`](Self::waterline_ray)). The nearer hit wins.
     pub fn cast_camera(&self, from: Vec3, movement: Vec3, liquid: bool) -> Option<f32> {
         let solid = self
             .ms
@@ -366,8 +230,7 @@ impl WorldCollision<'_, '_> {
         )
     }
 
-    /// [`slide_body`](Self::slide_body) against a caller-supplied filter — the ghost's door
-    /// exclusion, for the reason spelled out on [`cast_body_with`](Self::cast_body_with).
+    /// [`slide_body`](Self::slide_body) against a caller-supplied filter.
     fn slide_body_with(
         &self,
         shape: &Collider,
@@ -390,24 +253,11 @@ impl WorldCollision<'_, '_> {
         )
     }
 
-    /// Sweep the **local mover's own body** — [`cast_body`](Self::cast_body) with this frame's
-    /// [`MoverTraceExclusions`] applied.
-    ///
-    /// The reference's world trace carries a per-trace mask, and the local mover's mask gains bit
-    /// `0x8000` when the body it is driving is a player **in ghost form** (`0x631658`); the
-    /// GameObject collision-candidacy virtual `0x5f85f0` reads that bit and drops every
-    /// `GAMEOBJECT_TYPE_ID == 0` (DOOR) object from the gather. So a ghost walks through closed
-    /// doors, and nothing else about its collision differs (wow-re
-    /// `collision/scratch/ghost-door-tracemask.md`).
-    ///
-    /// **Why the exclusion rides the trace and not the collider.** It is tempting to drop the
-    /// door's collider, or re-lane it — both are wrong, because the fact is about *whose trace this
-    /// is*. [`body_filter`](Self::body_filter) is shared with the particle snap, the precipitation
-    /// probe, the mouse pick, the taxi probe and the creature ground conform; a door that stopped
-    /// existing for all of them because the local player happened to be dead would be a much larger
-    /// claim than the binary makes. Only the mover's own sweeps take the exclusion.
-    ///
-    /// With the set empty — every living frame — this is [`cast_body`](Self::cast_body) exactly.
+    /// [`cast_body`](Self::cast_body) with this frame's [`MoverTraceExclusions`]. In the reference
+    /// the mover's trace mask gains `0x8000` when it drives a player in ghost form (`0x631658`),
+    /// and the GameObject candidacy virtual `0x5f85f0` then drops every DOOR (type 0) from the
+    /// gather: a ghost walks through closed doors. Only the mover's own sweeps take it; the
+    /// shared [`body_filter`](Self::body_filter) keeps its doors.
     pub fn cast_mover(
         &self,
         shape: &Collider,
@@ -418,7 +268,7 @@ impl WorldCollision<'_, '_> {
         self.cast_body_with(shape, from, movement, skin_width, &self.mover_filter())
     }
 
-    /// [`slide_body`](Self::slide_body) for the local mover — see [`cast_mover`](Self::cast_mover).
+    /// [`slide_body`](Self::slide_body) with this frame's [`MoverTraceExclusions`].
     pub fn slide_mover(
         &self,
         shape: &Collider,
@@ -439,24 +289,19 @@ impl WorldCollision<'_, '_> {
         )
     }
 
-    /// [`body_filter`](Self::body_filter), plus whatever this frame's mover must not see.
-    ///
-    /// Allocation-free while the set is empty (`EntityHashSet::default()` allocates nothing), which
-    /// is every frame the player is alive.
+    /// [`body_filter`](Self::body_filter) minus this frame's exclusions; no allocation when empty.
     fn mover_filter(&self) -> SpatialQueryFilter {
         Self::body_filter().with_excluded_entities(self.exclusions.0.iter().copied())
     }
 
-    /// Every front-facing triangle in a box around `at` — the step probe's face gather.
+    /// Every front-facing triangle in a box around `at`: the step probe's face gather.
     pub fn faces_near_body(&self, at: Vec3, half: Vec3, limit: usize) -> Vec<one_sided::FaceProbe> {
         one_sided::faces_near(&self.ms, at, half, &Self::body_filter(), limit)
     }
 }
 
-/// **`cameraWaterCollision` is a trace mask and nothing else.** The same waterline collider is a
-/// wall to the camera boom with the CVar on, thin air with it off, and thin air to the walking body
-/// either way — which is the whole of the reference's `0x50e5ec`, and the reason a swimmer is never
-/// stopped by the water they are in.
+/// `cameraWaterCollision` is a trace mask (`0x50e5ec`): the waterline stops the camera boom only
+/// with it set, and never the walking body.
 #[cfg(test)]
 mod liquid_trace_mask {
     use super::*;
@@ -504,7 +349,7 @@ mod liquid_trace_mask {
             .expect("system runs")
     }
 
-    /// …and the walking body, which must pass through either way.
+    /// The walking body on the same drop.
     fn descend_body(app: &mut App) -> Option<f32> {
         app.world_mut()
             .run_system_once(move |c: WorldCollision| {
@@ -519,14 +364,8 @@ mod liquid_trace_mask {
             .expect("system runs")
     }
 
-    /// A waterline at `y = 0`, tessellated at the **real** liquid cell size.
-    ///
-    /// Deliberately not one huge quad: an MCNK liquid layer is a 9×9 lattice over the chunk's
-    /// 33.333 yd, so its cells are 4.167 yd and its triangles are that big and no bigger. A sphere
-    /// swept at grazing incidence against a 120 yd triangle is numerically unstable in a way it is
-    /// not against a 4 yd one, and a test that models the water as one quad measures the solver's
-    /// conditioning rather than the client's behaviour — which is exactly the sort of
-    /// unrepresentative fixture that lets a defect through.
+    /// A waterline at `y = 0` in real MCLQ cells (a chunk's 33.333 yd over 8, 4.167 yd): a sphere
+    /// grazing one huge triangle is numerically unstable where one grazing a 4 yd cell is not.
     fn flooded_world() -> App {
         let mut app = App::new();
         app.add_plugins((
@@ -538,8 +377,6 @@ mod liquid_trace_mask {
         ));
         app.init_asset::<Mesh>();
         app.init_resource::<MoverTraceExclusions>();
-        // 32×32 cells of 4.1667 yd — 133 yd square, 2048 triangles, the shape a streamed
-        // MCLQ layer actually presents.
         const CELL: f32 = 33.333_332 / 8.0;
         const N: usize = 32;
         let half = CELL * N as f32 * 0.5;
@@ -579,12 +416,10 @@ mod liquid_trace_mask {
     const SURFACE_DEPTH: f32 = 0.75 * 2.031;
     const HEAD_OVER_FEET: f32 = 2.027_777_7 - 1.0 / 3.0;
     const ZOOM: f32 = 15.0;
-    /// What 2170 framed at — the bare swim preset `cam+0x124`, which puts the orbit centre 11 mm
-    /// UNDER the plane.
+    /// The bare swim preset `cam+0x124` as framing pivot: an orbit centre 11 mm under the plane.
     const UNCORRECTED_PIVOT: f32 = 1.512_012;
 
-    /// The arm length the solver settles on for a swimmer whose feet are at `feet_y`, framing at
-    /// `pivot_over_feet`, sweeping from `origin_over_feet`, looking at `pitch` radians (+up).
+    /// The settled arm length for a swimmer with feet at `feet_y`, framing `geo`, at `pitch` (+up).
     fn open_arm(app: &mut App, feet_y: f32, geo: (f32, f32), pitch: f32) -> f32 {
         let (head, boom, len) = boom_from(feet_y, geo, pitch);
         app.world_mut()
@@ -594,11 +429,7 @@ mod liquid_trace_mask {
             .expect("system runs")
     }
 
-    /// The same arm through the query benilla shipped **before** decision 2185: one sphere sweep
-    /// carrying the liquid layer on its own mask, exactly as `camera_filter(true)` built it.
-    ///
-    /// It stays as the positive control for both of the tests below, because it is the query in
-    /// which the defect lives — and a gate whose control cannot fail is not a gate.
+    /// The positive control: the same arm as one sphere sweep with the liquid layer on its mask.
     fn open_arm_swept(app: &mut App, feet_y: f32, geo: (f32, f32), pitch: f32) -> f32 {
         let (head, boom, len) = boom_from(feet_y, geo, pitch);
         app.world_mut()
@@ -630,22 +461,18 @@ mod liquid_trace_mask {
         (head, boom, boom.length())
     }
 
-    /// 2170's geometry at a given depth: the framing pivot is the bare swim preset, so it rides the
-    /// **body** — and the boom is rooted at the head, likewise.
+    /// The uncorrected geometry: pivot at the bare swim preset, boom at the head, both on the body.
     fn uncorrected(_feet_y: f32) -> (f32, f32) {
         (UNCORRECTED_PIVOT, HEAD_OVER_FEET)
     }
 
-    /// The corridor's geometry at a given depth: arm A pins the pivot to `d + 2/9` and its floor
-    /// lifts the sweep origin to the same place, so **both ride the water plane** rather than the
-    /// body.
+    /// The corridor's geometry: pivot and sweep origin both at `surface + 2/9`, on the water plane.
     fn corrected(feet_y: f32) -> (f32, f32) {
         let floor = (0.0 - feet_y) + 2.0 / 9.0;
         (floor, HEAD_OVER_FEET.max(floor))
     }
 
-    /// Worst single-step change in arm length as the swimmer's depth is walked over `span`, at the
-    /// given pitch.
+    /// The worst one-step change in arm length as the swimmer's depth walks over `span`.
     fn worst_over_depth(
         app: &mut App,
         arm: impl Fn(&mut App, f32, (f32, f32), f32) -> f32,
@@ -667,30 +494,13 @@ mod liquid_trace_mask {
         worst
     }
 
-    /// **The gate this feature ships behind, with a positive control that reproduces the bug.**
-    ///
-    /// The axis is **depth**, not pitch — which is the correction that made this test worth having.
-    /// A first attempt swept the camera *pitch* and found all three geometries merely steep, no
-    /// cliff anywhere; that was the wrong question, because the director's report was of a camera
-    /// snapping *while swimming at the surface*, with the mouse still. What varies then is the
-    /// swimmer's depth, by fractions of a millimetre, as the float resolver settles against its
-    /// rest cap.
-    ///
-    /// **2170's geometry turns half a millimetre of that into ten yards of camera.** Its framing
-    /// pivot is the bare swim preset, so the orbit centre rides the BODY — and sits 11 mm under the
-    /// water plane. The boom's far end therefore straddles the plane, and whether the sweep hits at
-    /// all flips with the settle. Snap in, ease out, snap in: exactly what was reported.
-    ///
-    /// **The corridor's geometry cannot do this, structurally.** Arm A pins the pivot to `d + 2/9`
-    /// and its floor lifts the sweep origin to the same place — both defined FROM THE SURFACE, so
-    /// the camera's clearance over the water is a constant 2/9 yd no matter what the body does
-    /// underneath it. Depth stops being an input. That is the property worth having, and it is why
-    /// this is a fix rather than a tuning: nothing here was made smaller, it was made independent.
+    /// A surface swimmer's depth settles by fractions of a millimetre with the mouse still. With
+    /// the pivot 11 mm under the plane the boom's far end straddles it and the arm swings by yards;
+    /// the corridor defines pivot and origin from the surface, so depth is no input at all.
     #[test]
     fn a_swimmers_settle_cannot_move_the_camera_once_the_corridor_holds_it() {
         let mut app = flooded_world();
-        // The control, at the pitch where the old geometry is worst: looking slightly down, which
-        // swings the seat up across the plane.
+        // The control at its worst pitch: slightly down, which swings the seat up across the plane.
         let control = worst_over_depth(
             &mut app,
             open_arm_swept,
@@ -704,7 +514,7 @@ mod liquid_trace_mask {
             "the positive control must reproduce the regression — half a millimetre of settle \
              should swing 2170's camera by yards, got {control}"
         );
-        // …and the corridor, across the whole range a swimmer looks through.
+        // The corridor, across a swimmer's whole pitch range.
         for pitch_deg in [-25.0f32, -10.0, -2.0, -0.5, 0.0, 0.5, 2.0, 10.0, 25.0] {
             let step = worst_over_depth(
                 &mut app,
@@ -722,31 +532,15 @@ mod liquid_trace_mask {
         }
     }
 
-    /// **The probe that did not fit through its own corridor** (decision 2185).
-    ///
-    /// The corridor lifts the camera's sweep origin to `surface + 2/9 = 0.2222` yd. That is a
-    /// **reference** constant, and the reference's trace is a bare ray: `0x672170` takes a start,
-    /// an end, an out-point and a `frac` and carries no radius anywhere, bottoming out in the
-    /// Möller–Trumbore ray/triangle test at `0x7c2c40`. benilla's camera probe is a
-    /// [`CAMERA_PROBE_RADIUS`] = `0.3` yd sphere — **our own** construction, the margin that keeps
-    /// the near plane out of a wall. `0.3 > 0.2222`, so centred on the corridor floor it hangs 78
-    /// mm through the water plane *before the sweep has moved at all*.
-    ///
-    /// A surface swimmer's boom runs from that origin to a seat at the same height — the corridor
-    /// pins both to `surface + 2/9` — so a **level** camera sweeps exactly parallel to the water,
-    /// and came back pinned at zero: the camera slammed onto the character. Tip it two degrees
-    /// down and the sphere escapes the plane and the hit vanishes. That flip, against an arm that
-    /// snaps in instantly and eases back out over about a second, is the "snaps in for a second
-    /// every couple of seconds" a surface swim was reported with — and it is the same mechanism
-    /// 2170 was reported for and 2179 could not reach, because the corridor it built is measured
-    /// in a clearance this probe was always too fat for.
+    /// A level boom behind a surface swimmer runs parallel to the water, 2/9 yd above it: a
+    /// `0.3` yd sphere there starts 78 mm through the plane and pins at zero, a ray stays open.
     #[test]
     fn a_level_boom_behind_a_surface_swimmer_is_not_pinned_to_the_water() {
         let mut app = flooded_world();
         let feet_y = -SURFACE_DEPTH;
         let geo = corrected(feet_y);
 
-        // The control, which must reproduce the defect: the pre-2185 query, level.
+        // The control, level: the sphere sweep must reproduce the pin.
         let control = open_arm_swept(&mut app, feet_y, geo, 0.0);
         assert!(
             control < 0.01,
@@ -754,7 +548,7 @@ mod liquid_trace_mask {
              starts inside the plane and comes back pinned at zero, got {control}"
         );
 
-        // …and the shipping query, across the band a surface swimmer actually looks through.
+        // The shipping query, across a surface swimmer's pitch band.
         for deg in [-25.0f32, -10.0, -2.0, -0.5, 0.0, 0.25, 0.5] {
             let open = open_arm(&mut app, feet_y, geo, deg.to_radians());
             assert!(
@@ -764,8 +558,7 @@ mod liquid_trace_mask {
             );
         }
 
-        // …and the option still does its job when the camera really is aimed under the water:
-        // 2/9 yd of clearance shed at sin(20 deg) crosses the plane 0.65 yd along the boom.
+        // A boom descending at 20 deg sheds the 2/9 yd clearance 0.65 yd along it (sin 20 deg).
         let aimed = open_arm(&mut app, feet_y, geo, 20.0f32.to_radians());
         assert!(
             (aimed - 0.65).abs() < 0.05,
@@ -799,20 +592,15 @@ mod liquid_trace_mask {
     }
 }
 
-/// The contact pipeline we deliberately do not run (decision 1232, disabled in `world_plugins`).
-///
-/// These two tests are a matched pair: the first shows the cost was real — a kinematic trimesh
-/// resting in the static world generates contact pairs, and avian then computes a trimesh-vs-trimesh
-/// manifold for each, every physics tick — and the second shows that dropping the broad phase
-/// removes them *without* costing the shape-casts the character controller actually rides.
+/// The contact pipeline `world_plugins` disables: the stock broad phase pairs a resting kinematic
+/// trimesh with the static world for a manifold every tick, and dropping it keeps the shape casts.
 #[cfg(test)]
 mod contact_pipeline {
     use super::*;
     use bevy::ecs::system::RunSystemOnce;
     use bevy::prelude::*;
 
-    /// A static 10×10 floor plus a kinematic 4×4 slab overlapping it — the transport-on-terrain
-    /// shape that was generating manifolds against 65k-triangle tiles in the real world.
+    /// A static 10×10 floor and a kinematic 4×4 slab on it: a transport resting on terrain.
     fn overlapping_world(broad_phase: bool) -> App {
         let mut app = App::new();
         let physics = PhysicsPlugins::new(bevy::app::PostUpdate);
@@ -849,17 +637,15 @@ mod contact_pipeline {
             Collider::trimesh(fv, ft),
             Transform::default(),
         ));
-        // Overlapping, not merely adjacent: same plane, so the AABBs intersect and the narrow
-        // phase has real triangle work to do.
+        // Coplanar and overlapping, so the AABBs intersect.
         let (sv, st) = quad(2.0, 0.0);
         app.world_mut().spawn((
             RigidBody::Kinematic,
             Collider::trimesh(sv, st),
             Transform::default(),
         ));
-        // Two frames, not one: the first seats `Position`/`Rotation` and the collider trees, and
-        // the physics schedule first steps on the second. A single-`update()` fixture (which is
-        // what `one_sided`'s is) never runs a physics step at all.
+        // Two updates: the first seats `Position`/`Rotation` and the collider trees, and physics
+        // first steps on the second.
         app.update();
         app.update();
         app
@@ -871,8 +657,7 @@ mod contact_pipeline {
 
     #[test]
     fn the_stock_plugin_set_generates_contact_pairs_we_never_read() {
-        // The bug's premise. If this ever reads 0, avian changed and 1232's reasoning needs a
-        // re-read before the disable below can still be justified as a saving.
+        // If this reads 0, avian changed and the broad-phase disable may no longer save anything.
         assert!(
             active_pairs(&overlapping_world(true)) > 0,
             "expected the stock broad phase to pair the kinematic slab with the static floor"
@@ -887,8 +672,7 @@ mod contact_pipeline {
             0,
             "no broad phase means no contact pairs, so nothing to build manifolds for"
         );
-        // The half that must NOT regress: the collider BVH is `ColliderTreePlugin`'s, not the
-        // broad phase's, so a downward cast still finds the floor the player walks on.
+        // The collider BVH is `ColliderTreePlugin`'s, not the broad phase's, so casts still work.
         let hit = app
             .world_mut()
             .run_system_once(|spatial: SpatialQuery| {
diff --git a/crates/benilla-world/src/collision/one_sided.rs b/crates/benilla-world/src/collision/one_sided.rs
index cad3913d..de4808c2 100644
--- a/crates/benilla-world/src/collision/one_sided.rs
+++ b/crates/benilla-world/src/collision/one_sided.rs
@@ -1,47 +1,22 @@
-//! **One-sided movement collision** — the reference's facing law, applied at the only seam where it
-//! can live: per candidate triangle, inside the sweep.
+//! One-sided movement collision. The reference gathers faces at their file winding (`0x671cc0`)
+//! and its resolver skips any with `n·dir > −1e-5` (`0x632700`) for every caller of `0x632ba0`:
+//! falling, walking, step-up, ground settle, transports and the water surface, so a floor is
+//! filtered exactly like a wall.
 //!
-//! The real client's movement collision is an orientation-blind gather followed by a strictly
-//! one-sided resolver: `0x671cc0` emits every candidate face's plane at the **unflipped file
-//! winding**, and `0x632700` opens each record with `dot = n·dir` against `[0x80c5c4]`
-//! (`0xb727c5ac` = −9.99999975e-6) — **a face is processed iff `n·dir ≤ −1e-5`**. A face approached
-//! from its back is discarded before any distance is computed, and this is not a wall-slide special
-//! case: the 16 callers of `0x632ba0 earliest_contact` span falling, walking, step-up, ground-settle,
-//! transports and the water-surface arm — "the surface you stand on is filtered exactly like the wall
-//! you slide along" (decision 0967, wow-re `collision/scratch/wmo-movement-group-gate.md`; confirmed
-//! at B86's exact pin in decision 0968). parry's trimesh is two-sided by construction, which is why
-//! benilla stood on CoT's inward-wound shell where 1.12.1 falls through it.
+//! parry's trimesh is two-sided, and a first-hit cast cannot yield the front face behind a
+//! backface, so this re-runs avian's `move_and_slide` over its public pieces and gates each
+//! triangle in its own BVH walk. The winding seen is the authored one: `Collider::trimesh` keeps
+//! it, and every transform is a rotation. Convex colliders stay whole-shape, and camera and
+//! line-of-sight casts stay two-sided, as the reference's segment kernel is (`0x7c29f0`).
 //!
-//! Why this is a mirrored loop and not a post-filter: a shape cast reports only the *first* hit. If
-//! that hit is a backface, the correct result is the next front-face hit *behind* it — information a
-//! finished cast no longer has. So the gate must run where candidates are enumerated, and avian's
-//! enumeration (`cast_shape_predicate`, `contact_manifolds`) carries no triangle identity out. This
-//! module therefore re-runs avian's own `move_and_slide` algorithm — same iteration structure, same
-//! skin-width pull-back, same depenetration solver (`depenetrate_intersections`), same velocity
-//! projection — over its public building blocks, walking each trimesh's BVH itself so every triangle
-//! is gated on its **authored winding** before it may block. `Collider::trimesh` stores vertices and
-//! indices exactly as passed (parry `TriMeshFlags::empty()`), and every transform between the file
-//! and the collider is a proper rotation (decision 0968), so `TriMesh::triangle(i)`'s winding *is*
-//! the authored winding.
+//! Deviation: the slide, step and snap are avian's kinematic controller, with parry's edge-hit
+//! normals, not the reference's resolver, because pieces of that resolver grafted onto the
+//! controller left the mover in states the reference never reaches; only its face filters, the
+//! facing law and the backface band, are ported.
 //!
-//! What is ported is the **law**, not the reference's resolver: the slide/step/snap machinery stays
-//! the standard kinematic controller (that direction was closed in 0207), contact normals for edge
-//! hits stay parry's, and convex (non-trimesh) colliders stay whole-shape — a convex volume has no
-//! reachable backface. The camera/LOS path is untouched *on purpose*: the reference's segment
-//! kernel `0x7c29f0` is two-sided (0967), so avian's ordinary cast is already faithful there.
-//!
-//! **There is no depenetration pass, and that is the law too** (decision 2018). avian's
-//! `move_and_slide` opens and closes with a Gauss–Seidel push-out of every face the shape overlaps;
-//! the reference's resolver has no such stage anywhere in `0x634040`'s closure. Its world query is a
-//! time-of-impact sweep and nothing else: a face the prism starts *behind* by more than 1/36 yd
-//! (`[0x7ff9c8]`, the backface band in `0x632830`'s clip) is not a hit at all, one it straddles is a
-//! hit at `t = 0` that the slide projects against, and neither ever *moves* a body that asked to go
-//! nowhere. The push-out was benilla's, and it is what shoved a seated body sideways off its stool:
-//! the server seats a player at a chair's origin, inside the chair's own collision box, and the
-//! minimum-translation vector for a tall capsule inside a small box is horizontal — out through the
-//! nearest side (B359, measured at 0.555 yd on the first frame, with no input). A body that starts
-//! inside geometry leaves it the way the reference does: by walking out through the faces wound
-//! away from it, which the sweep never counts.
+//! There is no depenetration: the reference's resolver (`0x634040`) is a sweep with no push-out, so
+//! a body inside geometry, such as a player the server seats inside a chair's box, walks out
+//! through the faces wound away from it instead of being shoved sideways.
 
 use avian3d::character_controller::move_and_slide::{
     MoveAndSlide, MoveAndSlideConfig, MoveAndSlideHitData, MoveAndSlideHitResponse,
@@ -57,34 +32,21 @@ use avian3d::prelude::*;
 use bevy::prelude::*;
 use core::time::Duration;
 
-/// The reference's facing gate: `[0x80c5c4] = 0xb727c5ac`. A face may block iff `n·dir ≤ EPS`,
-/// with `n` the authored winding normal and `dir` the unit direction of the motion being resolved.
+/// The facing gate (`[0x80c5c4]`, −1e-5): a face blocks only when `n·dir` is at most this, `n` its
+/// authored normal and `dir` the unit motion.
 const FACING_EPS: f32 = f32::from_bits(0xb727_c5ac);
 
-/// avian's own stabilizer for `pull_back` when `n·dir` is nearly zero (`move_and_slide.rs`).
+/// avian's `pull_back` floor for a near-zero `n·dir` (its `move_and_slide.rs`).
 const DOT_EPSILON: f32 = 0.005;
 
-/// The reference's **backface band**: `[0x7ff9c8]` = `1/36` yd. A candidate face the mover has
-/// already passed by more than this is not a hit — `0x632830`'s clip (wow-re
-/// `resolve_clip.rs::polygon_toi`) rejects a face **every vertex of which** sits further than the
-/// band behind the prism's leading plane along the motion, and keeps one with any vertex nearer
-/// than that as a hit at `t = 0`. It is what makes the resolver a *sweep* and not a solver: a body
-/// the server placed inside a hull (a seated player at a chair's origin, a caged creature) meets
-/// faces it already straddles, and the band says which of those still count — a seat top half a
-/// yard into the body, every vertex of it behind the body's leading edge, does not exist; a sloped
-/// terrain triangle a few centimetres into the feet, one vertex of which still lies below them,
-/// does (decision 2018). **Measured against the vertices, not the penetration depth**: the first
-/// port used parry's contact depth, and on a 19° slope under a stool that read the terrain as
-/// behind the feet — the body fell 26 yd through the world. Ported at this seam, like the facing
-/// law, because it can only be applied where the *overlapping* triangle is known: avian's own
-/// sweep skips every origin-penetrating hit (`ignore_origin_penetration`) and leaves the overlap to
-/// the depenetration pass this module no longer runs.
+/// The backface band (`[0x7ff9c8]`, 1/36 yd): `0x632830`'s clip drops a face whose every vertex
+/// lies more than this behind the mover's leading plane along the motion, and keeps one with any
+/// vertex nearer as a hit at `t = 0`. Measured on the vertices: a penetration depth would drop a
+/// sloped floor just above the feet, and the body would fall through the world.
 const BACKFACE_BAND: f32 = 1.0 / 36.0;
 
-/// One-sided drop-in for [`MoveAndSlide::cast_move`]: sweep `shape` (world-axis-aligned, as every
-/// mover capsule is) along `movement`, stopping `skin_width` short of the first face whose
-/// **authored winding opposes the motion**. Backfaces are not candidates at all — the sweep passes
-/// through them to whatever front-face lies beyond, which no post-filter on a first-hit cast can do.
+/// One-sided [`MoveAndSlide::cast_move`]: sweeps the axis-aligned `shape` along `movement` to
+/// `skin_width` short of the first face whose authored winding opposes the motion.
 pub(crate) fn cast_move(
     ms: &MoveAndSlide<'_, '_>,
     shape: &Collider,
@@ -96,7 +58,6 @@ pub(crate) fn cast_move(
     let (dir, len) = Dir3::new_and_length(movement).unwrap_or((Dir3::X, 0.0));
     let max_toi = len + skin_width;
 
-    // The swept broad-phase box: the shape's AABB at both ends of the motion, grown by the skin.
     let a0 = shape.aabb(from, Quat::IDENTITY);
     let a1 = shape.aabb(from + movement, Quat::IDENTITY);
     let swept = ColliderAabb {
@@ -115,8 +76,7 @@ pub(crate) fn cast_move(
         }
 
         if let Some(trimesh) = collider.shape_scaled().as_trimesh() {
-            // Work in the trimesh's local frame: the cast pose and direction come in, world hit
-            // data goes out. A proper rotation preserves the sign of every `n·dir`.
+            // In the trimesh's local frame; a rotation keeps the sign of every `n·dir`.
             let inv_rot = rot.0.inverse();
             let local_from = inv_rot * (from - pos.0);
             let local_dir = inv_rot * *dir;
@@ -127,10 +87,10 @@ pub(crate) fn cast_move(
             {
                 let tri = trimesh.triangle(tri_id);
                 let Some(n) = tri.normal() else {
-                    continue; // degenerate face: no winding, no plane, nothing to block with
+                    continue; // a degenerate face has no winding
                 };
                 if n.dot(local_dir) > FACING_EPS {
-                    continue; // the law: a face approached from its back is not a candidate
+                    continue; // approached from its back
                 }
                 let Ok(Some(hit)) = cast_shapes(
                     &Pose3::IDENTITY,
@@ -148,8 +108,7 @@ pub(crate) fn cast_move(
                 ) else {
                     continue;
                 };
-                // An overlap at `t = 0` is a hit only inside the band: a face the body has passed
-                // deeper than that is behind it, whatever its winding says about the motion.
+                // An overlap at `t = 0` is a hit only inside the band.
                 if hit.status == ShapeCastStatus::PenetratingOrWithinTargetDist
                     && behind_the_band(&tri, &local_pose, shape, local_dir)
                 {
@@ -169,7 +128,7 @@ pub(crate) fn cast_move(
                 }
             }
         } else {
-            // A convex collider has no reachable backface: whole-shape sweep, exactly avian's.
+            // A convex collider has no reachable backface: avian's whole-shape sweep.
             let Ok(Some(hit)) = cast_shapes(
                 &Pose3::from_parts(pos.0, rot.0),
                 Vec3::ZERO,
@@ -202,7 +161,7 @@ pub(crate) fn cast_move(
     }
 
     best.map(|mut hit| {
-        // avian's skin-width pull-back: stop short of the surface by `skin / |n·dir|`, never negative.
+        // avian's skin-width pull-back: `skin / |n·dir|` short of the surface, never negative.
         hit.distance = if max_toi == 0.0 {
             0.0
         } else {
@@ -213,10 +172,8 @@ pub(crate) fn cast_move(
     })
 }
 
-/// One-sided drop-in for [`SpatialQuery::cast_ray`], for the movement-law probes that are rays
-/// rather than shape sweeps (the creature ground clamp mirrors the WALK resolver's Z re-derivation,
-/// and that resolver filters its down-probe like every other arm — 0967's caller census). `dir`
-/// must be a unit direction; the gate and the semantics are [`cast_move`]'s, minus the skin.
+/// One-sided [`SpatialQuery::cast_ray`] for movement probes that are rays, such as the creature
+/// ground clamp: the reference's walk resolver gates its down-probe like every other caller.
 pub(crate) fn cast_ray(
     ms: &MoveAndSlide<'_, '_>,
     origin: Vec3,
@@ -285,13 +242,8 @@ pub(crate) fn cast_ray(
     best
 }
 
-/// One-sided drop-in for [`MoveAndSlide::move_and_slide`]: avian's algorithm — sweep, collect
-/// contact planes, project velocity, repeat — with every stage running over the gated candidate set
-/// instead of the two-sided trimesh, and **without** avian's opening and closing depenetration
-/// (see the module note: the reference's resolver has no push-out stage, and the one this carried
-/// is what displaced a seated body out of its chair). The `on_hit` callback contract is avian's
-/// ([`MoveAndSlideHitData`] / [`MoveAndSlideHitResponse`]), so the mover's ride/steep-wall handlers
-/// move over unchanged.
+/// One-sided [`MoveAndSlide::move_and_slide`]: avian's sweep, plane collection and velocity
+/// projection over the gated faces, without its depenetration; `on_hit` keeps avian's contract.
 pub(crate) fn move_and_slide(
     ms: &MoveAndSlide<'_, '_>,
     shape: &Collider,
@@ -341,10 +293,7 @@ pub(crate) fn move_and_slide(
             break;
         }
 
-        // Collect nearby contact planes for velocity clipping — avian's `intersections` pass, per
-        // gated triangle. The gate here is the same law with the *velocity* as the motion: a face
-        // may clip the slide iff its authored winding opposes where we are going AND we sit on its
-        // front side (behind a face, its plane does not exist for us — that is the fall-through).
+        // avian's contact-plane pass, gated with the velocity as the motion.
         let mut aborted = false;
         for_each_contact(
             ms,
@@ -403,15 +352,10 @@ pub(crate) fn move_and_slide(
     }
 }
 
-/// Visit every contact of `shape` (world-axis-aligned) against the filtered world within
-/// `prediction`, gated by the one-sided law with `motion` as the direction being resolved — the
-/// slide's plane collection: a triangle participates iff its authored normal opposes the velocity
-/// (`n·v̂ ≤ EPS`) *and* the mover sits on its front side (behind a face, its plane does not exist
-/// for movement).
-///
-/// The callback receives `(entity, world contact point, world contact normal toward the mover,
-/// contact distance — negative when penetrating)` and returns `false` to stop the visit. Convex
-/// colliders are visited ungated.
+/// Visits each contact of `shape` within `prediction` for the slide's planes: a triangle counts
+/// when its authored normal opposes `motion` and the mover is on its front side. The callback gets
+/// `(entity, point, normal toward the mover, distance, negative when penetrating)` and returns
+/// `false` to stop; convex colliders are ungated.
 fn for_each_contact(
     ms: &MoveAndSlide<'_, '_>,
     shape: &Collider,
@@ -461,15 +405,11 @@ fn for_each_contact(
                 ) else {
                     continue;
                 };
-                // Front-side gate: the contact must push the mover along the authored normal.
-                // Behind the face (`c.normal1 ≈ −n`) the plane does not exist for movement.
+                // Front side only: behind a face, its plane does not exist for movement.
                 if c.normal1.dot(n) <= 0.0 {
                     continue;
                 }
-                // The backface band (see [`BACKFACE_BAND`]): a face the body has already passed
-                // is not a plane to slide along — the sweep does not count it, and a slide plane
-                // the sweep never reported would clip the body against geometry it is meant to
-                // walk straight out of.
+                // A face passed beyond the band is no slide plane, as the sweep never reports it.
                 if c.dist < 0.0 && behind_the_band(&tri, &local_pose, shape, local_dir) {
                     continue;
                 }
@@ -494,11 +434,8 @@ fn for_each_contact(
     }
 }
 
-/// Has the mover already passed this triangle by more than the [`BACKFACE_BAND`]? The reference's
-/// own measure: every vertex of the face against the mover's **leading extent along the motion**
-/// (`0x632830`'s per-vertex `ray_plane_t` against the prism's leading plane). The leading extent is
-/// the shape's support point along `dir` — for the capsule, the far segment end plus the radius.
-/// A shape with no support map (none on the movement audience) is never behind: the hit stands.
+/// Whether every vertex lies more than [`BACKFACE_BAND`] behind the shape's support point along
+/// `dir`, `0x632830`'s per-vertex test.
 fn behind_the_band(tri: &Triangle, shape_pose: &Pose3, shape: &Collider, dir: Vec3) -> bool {
     let Some(support) = shape.shape_scaled().as_support_map() else {
         return false;
@@ -511,8 +448,7 @@ fn behind_the_band(tri: &Triangle, shape_pose: &Pose3, shape: &Collider, dir: Ve
     ahead < -BACKFACE_BAND
 }
 
-/// The conservative local-frame box of a world AABB under `world→local` = `inv_rot · (x − pos)`:
-/// transform the eight corners and take their extent.
+/// The local-frame box bounding a world AABB's eight corners.
 fn aabb_to_local(aabb: ColliderAabb, pos: Vec3, inv_rot: Quat) -> ParryAabb {
     let (mut mins, mut maxs) = (Vec3::INFINITY, Vec3::NEG_INFINITY);
     for i in 0..8 {
@@ -528,37 +464,29 @@ fn aabb_to_local(aabb: ColliderAabb, pos: Vec3, inv_rot: Quat) -> ParryAabb {
     ParryAabb::new(mins, maxs)
 }
 
-/// One collision triangle near a point, as the **movement law** sees it — the geometry readout
-/// behind the step-up probe ([`crate::player::step_probe`]).
+/// One collision triangle near a point, as the movement law sees it, for the step-up probe.
 pub struct FaceProbe {
-    /// The collider it belongs to (a WMO walk bake, a terrain tile, a doodad hull…).
     pub entity: Entity,
-    /// World-space normal at the **authored winding** — the vector [`cast_move`]'s gate tests.
+    /// World-space normal at the authored winding, the vector the gate tests.
     pub normal: Vec3,
     /// World-space vertices.
     pub(crate) verts: [Vec3; 3],
 }
 
 impl FaceProbe {
-    /// Whether this face may block a sweep heading `dir` — [`cast_move`]'s gate, exactly.
+    /// Whether this face may block a sweep heading `dir`: [`cast_move`]'s gate.
     pub fn blocks(&self, dir: Vec3) -> bool {
         self.normal.dot(dir) <= FACING_EPS
     }
 
-    /// World centroid — what "how far ahead is this face" is measured from.
+    /// World centroid, where a face's distance ahead is measured from.
     pub fn centroid(&self) -> Vec3 {
         (self.verts[0] + self.verts[1] + self.verts[2]) / 3.0
     }
 }
 
-/// Every trimesh face inside the box `at ± half` that `filter` can reach, nearest centroid first.
-///
-/// **Diagnostic only, and deliberately UNGATED**: it reports the faces the one-sided law *rejects*
-/// alongside the ones it keeps, which is the entire point of having it. "The kerb top is authored
-/// downward-facing, so our settle probe passes straight through it" and "the advance was too short
-/// to reach the tread" produce the same silent non-step from the outside, and opposite readings
-/// here. Convex (non-trimesh) colliders have no per-face winding to report and are skipped — the
-/// law leaves them whole-shape too.
+/// Every trimesh face in the box `at ± half` that `filter` reaches, nearest centroid first. A
+/// diagnostic, ungated on purpose: it shows the faces the law rejects beside those it keeps.
 pub(crate) fn faces_near(
     ms: &MoveAndSlide<'_, '_>,
     at: Vec3,
@@ -611,12 +539,10 @@ mod tests {
     use super::*;
     use bevy::ecs::system::RunSystemOnce;
 
-    /// A physics world holding one 10×10 quad at y = 0 with the given winding — `up: true` is a
-    /// floor (authored normal +Y), `up: false` is 0968's shell face (authored normal −Y).
+    /// One 10×10 quad at y = 0, wound as a floor (+Y) when `up`, else as a shell face (−Y).
     fn world_with_quad(up: bool) -> App {
         let mut app = App::new();
-        // avian's collider backend reads `Assets<Mesh>` and `SceneSpawner` even in a meshless
-        // world, so the headless asset/scene plugins ride along.
+        // avian's collider backend reads `Assets<Mesh>` and `SceneSpawner` even with no meshes.
         app.add_plugins((
             MinimalPlugins,
             bevy::transform::TransformPlugin,
@@ -650,7 +576,6 @@ mod tests {
         Collider::capsule(0.4, 1.0)
     }
 
-    /// A headless world holding one up-wound trimesh built from `(verts, tris)`.
     fn world_with_mesh(verts: Vec<Vec3>, tris: Vec<[u32; 3]>) -> App {
         let mut app = App::new();
         app.add_plugins((
@@ -672,7 +597,6 @@ mod tests {
         app
     }
 
-    /// Sweep the test capsule from `from` by `movement` and report the hit distance, `None` on a miss.
     fn sweep(app: &mut App, from: Vec3, movement: Vec3) -> Option<f32> {
         app.world_mut()
             .run_system_once(move |ms: MoveAndSlide| {
@@ -689,16 +613,7 @@ mod tests {
             .unwrap()
     }
 
-    /// **The backface band, both faces of it** (decision 2018). The capsule here is 1.8 tall
-    /// (radius 0.4, segment 1.0), its centre 0.9 above its feet.
-    ///
-    /// A small horizontal face the body straddles — a seat top 0.5 yd into it, every vertex behind
-    /// the body's leading edge along a horizontal walk — is not a hit: the body walks out of the
-    /// chair. A large **sloped** face the feet sit 5 cm under — the terrain under a stool — is
-    /// still a hit for a downward probe, because a vertex of it lies below the feet; the first port
-    /// measured parry's penetration depth instead and dropped the floor, and the body fell through
-    /// the world. And a **flat** face every vertex of which is more than the band above the feet
-    /// is gone, which is the reference's own answer for a body placed under flat ground.
+    /// The capsule is 1.8 tall (radius 0.4, segment 1.0), its centre 0.9 above its feet.
     #[test]
     fn the_band_keeps_a_straddled_slope_and_drops_a_passed_face() {
         // A 0.6 × 0.6 seat top at y = 0.5, up-wound; the body's feet at y = 0 on its centre.
@@ -719,8 +634,7 @@ mod tests {
             "a seat top the body straddles is behind its leading edge: the walk out is free"
         );
 
-        // A 10-yd terrain triangle rising 1 yd across its span (a ~6° slope), the feet 5 cm
-        // under its plane at the body's own x — but one vertex of it lies well below the feet.
+        // A 10-yd slope rising 1 yd (about 6°), the feet 5 cm under it, one vertex well below.
         let mut slope = world_with_mesh(
             vec![
                 Vec3::new(-5.0, -0.5, -5.0),
@@ -737,7 +651,6 @@ mod tests {
             "a sloped floor the feet sit 5 cm under still supports: a vertex of it is below them"
         );
 
-        // The same feet 5 cm under a FLAT floor: every vertex more than the band behind — gone.
         let mut flat = world_with_mesh(
             vec![
                 Vec3::new(-5.0, 0.0, -5.0),
@@ -752,7 +665,6 @@ mod tests {
             None,
             "a flat floor more than 1/36 yd above the feet has been passed"
         );
-        // …and 2 cm under it — inside the band — is still standing on it.
         let feet_just_under = Vec3::new(0.0, 0.9 - 0.02, 0.0);
         assert_eq!(
             sweep(&mut flat, feet_just_under, Vec3::NEG_Y * 0.2),
@@ -763,7 +675,6 @@ mod tests {
 
     #[test]
     fn a_floor_blocks_a_fall_and_a_backface_does_not() {
-        // The whole bug in one assertion pair: the same quad, same cast, opposite winding.
         for (up, expect_block) in [(true, true), (false, false)] {
             let hit = world_with_quad(up)
                 .world_mut()
@@ -789,8 +700,7 @@ mod tests {
                 }
             );
             if let Some(h) = hit {
-                // Capsule bottom = center − (0.5 + 0.4); surface at 0 ⇒ contact after ~2.1 yd,
-                // pulled back by the skin.
+                // The capsule's bottom is 0.9 below its centre: contact after 2.1 yd.
                 assert!((h.collision_distance - 2.1).abs() < 1e-3);
                 assert!(h.normal1.y > 0.99);
             }
@@ -799,8 +709,7 @@ mod tests {
 
     #[test]
     fn a_floor_is_no_ceiling_from_below() {
-        // Rising through an up-wound floor from beneath: its backface must not bump the head —
-        // and the down-wound quad, approached from below, is the face that must.
+        // From below, an up-wound floor is a backface and a down-wound quad blocks.
         for (up, expect_block) in [(true, false), (false, true)] {
             let hit = world_with_quad(up)
                 .world_mut()
@@ -821,8 +730,6 @@ mod tests {
 
     #[test]
     fn the_slide_falls_through_a_backface_and_rests_on_a_floor() {
-        // The full resolve, not just the cast: one second of straight fall through/onto the quad.
-        // Backface: every stage — sweep and contact planes — must let the body pass.
         for (up, expect_above) in [(true, true), (false, false)] {
             let end = world_with_quad(up)
                 .world_mut()
diff --git a/crates/benilla-world/src/decal.rs b/crates/benilla-world/src/decal.rs
index 9a842fe7..bb8a07cd 100644
--- a/crates/benilla-world/src/decal.rs
+++ b/crates/benilla-world/src/decal.rs
@@ -1,26 +1,10 @@
-//! The shared world-surface **decal projector** — the reference's own ground-decal mechanism
-//! (wow-re selection-circle RE §2 + unit-blob-shadow RE, the `0x6d7330` → `0x6d6fa0` matrices →
-//! `0x6d7480` emit chain): gather the triangles of every [`GroundDecalSurface`] collider (terrain
-//! tiles + WMO faces — **never** doodads/GameObjects) whose BVH overlaps a projection box, clip
-//! each to the box ([`clip_to_frame`]), and emit them with planar top-down UVs. Because the
-//! emitted triangles are exact sub-pieces of the drawn surfaces, a decal is pixel-coplanar with
-//! what's on screen — **provided it transforms through the same `clip_from_world` matrix as the
-//! world-mesh shaders** (the `DECAL_WORLD_CLIP` lane variant; the cam-relative route reaches
-//! the same plane through different arithmetic and misses by more than the bias at WoW-scale
-//! coordinates — decision 0781), the rasterizer `depth_bias` settling the depth test — and
-//! drapes down
-//! steps and ledge faces precisely like the reference (a vertical face gets the smeared texel
-//! column of its XZ spot: projective texturing, faithfully).
-//!
-//! Since 0733 the projector emits **effect-stream triangles** ([`EffectVertex`], world-space,
-//! fan-unrolled) instead of `Mesh` assets: its clients cache the projected slice and push it
-//! into the shared lane per frame — zero mesh churn, tint/fade applied at push time.
-//!
-//! Three clients — the same emit loop in the binary: the **selection ring**
-//! ([`crate::target`]`::ring`, collector flags `0x200122`), the **unit blob shadow**
-//! ([`crate::blob_shadow`], flags `0x2f0122` — the ring's + the liquid receivers, a gap here:
-//! liquid surfaces aren't in the [`GroundDecalSurface`] set yet), and the ground-fx spell
-//! decals ([`crate::ground_fx`]).
+//! The ground-decal projector, the reference's `0x6d7330` → `0x6d6fa0` → `0x6d7480` chain: the
+//! triangles of every [`GroundDecalSurface`] collider (terrain and WMO faces, never doodads or
+//! GameObjects) in a box, clipped to it and emitted as world-space [`EffectVertex`] triangles with
+//! planar top-down UVs, so a vertical face smears its texel column as in the reference. They are
+//! coplanar with the drawn surface only through the world shaders' `clip_from_world`
+//! (`DECAL_WORLD_CLIP`). Collector flags: the ring `0x200122`, the blob shadow `0x2f0122`, which
+//! adds liquid; liquid is not a receiver here yet.
 
 use avian3d::parry::bounding_volume::{Aabb as ParryAabb, BoundingVolume};
 use avian3d::prelude::Collider;
@@ -29,11 +13,8 @@ use bevy::prelude::*;
 use crate::collision::GroundDecalSurface;
 use crate::particles::buffer::EffectVertex;
 
-/// A decal's projection box: a yaw-rotated horizontal rectangle × a vertical slab, all relative
-/// to `center` (the owning object's feet). The horizontal bounds live in the **rotated frame**
-/// (`x' = dx·cos − dz·sin`, `z' = dz·cos + dx·sin`); UVs map `[min_x, max_x] × [min_z, max_z]`
-/// to `[0,1]²`, so the texture square IS this rectangle. An axis-aligned box passes
-/// `(sin, cos) = (0, 1)`.
+/// A decal's projection box around `center` (the owner's feet): a yaw-rotated rectangle, bounds in
+/// the rotated frame (`x' = dx·cos − dz·sin`, `z' = dz·cos + dx·sin`), times a vertical slab.
 pub struct DecalFrame {
     pub center: Vec3,
     pub sin: f32,
@@ -54,9 +35,7 @@ impl DecalFrame {
         (dx * self.cos - dz * self.sin, dz * self.cos + dx * self.sin)
     }
 
-    /// The default UV map — the texture square IS the frame rectangle:
-    /// `[min_x, max_x] × [min_z, max_z] → [0,1]²` (the ring's and blob shadow's mapping). The
-    /// ground-fx lane substitutes a bilinear map over the source quad's authored corner UVs.
+    /// The texture square as the frame rectangle, `[min_x, max_x] × [min_z, max_z] → [0,1]²`.
     pub fn rect_uv(&self, x: f32, z: f32) -> [f32; 2] {
         [
             (x - self.min_x) / (self.max_x - self.min_x),
@@ -94,15 +73,9 @@ impl DecalFrame {
     }
 }
 
-/// Project a surface decal into `out` as **world-space, fan-unrolled effect triangles**: the
-/// [`GroundDecalSurface`] triangles are gathered, clipped to `frame`'s box, and emitted with
-/// top-down UVs. `alpha` computes each vertex's colour alpha from its in-frame position
-/// `(x', y_rel, z')` (vertical fades, edge ramps); the colour is white × that alpha — the
-/// pushing client multiplies its tint/fade in. `uv` maps in-frame `(x', z')` to the emitted
-/// texture coordinate ([`DecalFrame::rect_uv`] for the plain texture-square decals; the
-/// ground-fx lane bilerps its quad's authored corner UVs). Returns `false` when nothing was
-/// gathered (no receiving surface in the box) — the caller hides the decal, the reference's
-/// own no-ground gate (`0x6d74b5`: the whole draw is skipped).
+/// Project a decal into `out` as world-space, fan-unrolled white triangles, alpha from
+/// `alpha(x', y_rel, z')` and UVs from `uv(x', z')`. `false` when no surface is in the box: the
+/// caller hides the decal, the reference's no-ground gate (`0x6d74b5` skips the whole draw).
 pub(crate) fn project_decal(
     out: &mut Vec<EffectVertex>,
     surfaces: &Query<&Collider, With<GroundDecalSurface>>,
@@ -116,8 +89,7 @@ pub(crate) fn project_decal(
     }
     let start = out.len();
     for collider in surfaces {
-        // The marked colliders are static trimeshes with world-space vertices (identity pose),
-        // so their local AABB/triangles are world AABB/triangles.
+        // Marked colliders are identity-pose trimeshes: local AABBs and triangles are world ones.
         let Some(trimesh) = collider.shape().as_trimesh() else {
             continue;
         };
@@ -139,8 +111,7 @@ pub(crate) fn project_decal(
                     color: [1.0, 1.0, 1.0, a],
                 }
             };
-            // Fan-triangulate the clipped convex polygon, unrolled (the stream's tri-list
-            // topology: identity indices, no shared vertices).
+            // Fan-unrolled: the stream is a triangle list with no shared vertices.
             for k in 1..n - 1 {
                 out.push(vert(poly[0]));
                 out.push(vert(poly[k]));
@@ -151,12 +122,8 @@ pub(crate) fn project_decal(
     out.len() > start
 }
 
-/// Sutherland–Hodgman clip of a triangle against the frame's projection box: the yaw-rotated
-/// horizontal rectangle (clipping in the rotated frame is exactly the texture frame, so UVs stay
-/// in `[0,1]` and the texture can never wrap ghost copies in at the corners) and the vertical
-/// slab. Interpolates full 3D positions along clipped edges, so the result stays on the source
-/// triangle's plane. Returns the polygon buffer and its vertex count — fewer than 3 when the
-/// triangle lies outside the box.
+/// Sutherland-Hodgman clip of a triangle to the frame's box, in the rotated frame so UVs stay in
+/// `[0,1]` and never wrap; edges interpolate in 3D, so the result stays on the triangle's plane.
 fn clip_to_frame(tri: [Vec3; 3], frame: &DecalFrame) -> ([Vec3; 9], usize) {
     let rx = |p: Vec3| frame.in_frame(p).0;
     let rz = |p: Vec3| frame.in_frame(p).1;
@@ -169,8 +136,7 @@ fn clip_to_frame(tri: [Vec3; 3], frame: &DecalFrame) -> ([Vec3; 9], usize) {
         &|p: Vec3| (frame.center.y + frame.max_y) - p.y,
         &|p: Vec3| p.y - (frame.center.y + frame.min_y),
     ];
-    // Stack ping-pong (this runs per gathered triangle per frame): a convex clip grows the
-    // polygon by at most one vertex per plane, so 3 + 6 = 9 bounds both buffers.
+    // A convex clip adds at most one vertex per plane, so 3 + 6 = 9 bounds both stack buffers.
     let mut poly = [Vec3::ZERO; 9];
     let mut next = [Vec3::ZERO; 9];
     poly[..3].copy_from_slice(&tri);
@@ -184,7 +150,7 @@ fn clip_to_frame(tri: [Vec3; 3], frame: &DecalFrame) -> ([Vec3; 9], usize) {
                 next[out] = a;
                 out += 1;
             }
-            // The edge crosses the plane → emit the intersection point.
+            // The edge crosses the plane: emit the intersection point.
             if (da >= 0.0) != (db >= 0.0) {
                 next[out] = a + (b - a) * (da / (da - db));
                 out += 1;
@@ -199,26 +165,15 @@ fn clip_to_frame(tri: [Vec3; 3], frame: &DecalFrame) -> ([Vec3; 9], usize) {
     (poly, len)
 }
 
-/// **Project a decal onto the world's receiving surfaces** — the face for every lane that draws
-/// something flat on the ground.
-///
-/// Four lanes (the blob shadow, footprints, the selection ring, the targeting reticle) each held
-/// `Query<&Collider, With<GroundDecalSurface>>` and passed it to [`project_decal`]. The receiver
-/// set is the world's business — which colliders take a decal is decided at bake time by the MOPY
-/// material class, not by the lane drawing on them — so the query goes here and the lanes ask a
-/// question instead of carrying an answer.
+/// Projects decals onto the world's receiving surfaces, for every lane that draws flat on the
+/// ground; which colliders receive is decided at bake time by the MOPY material class.
 #[derive(bevy::ecs::system::SystemParam)]
 pub struct WorldDecal<'w, 's> {
     surfaces: Query<'w, 's, &'static Collider, With<GroundDecalSurface>>,
 }
 
 impl WorldDecal<'_, '_> {
-    /// Clip every receiving triangle in `frame`'s box and emit it into `out` with top-down UVs.
-    ///
-    /// `alpha` computes each vertex's colour alpha from its in-frame position (vertical fades,
-    /// edge ramps); `uv` maps in-frame `(x', z')` to a texture coordinate. Returns `false` when
-    /// nothing was gathered — no receiving surface in the box — and the caller hides its decal,
-    /// which is the reference's own no-ground gate (`0x6d74b5`: the whole draw is skipped).
+    /// [`project_decal`] over the receiving surfaces; `false` means hide the decal (`0x6d74b5`).
     pub fn project(
         &self,
         out: &mut Vec<crate::particles::buffer::EffectVertex>,
@@ -229,17 +184,12 @@ impl WorldDecal<'_, '_> {
         project_decal(out, &self.surfaces, frame, alpha, uv)
     }
 
-    /// How many receiving surfaces are resident — the decal lanes' census line, which is how a
-    /// "my shadow vanished" report gets answered with "there was nothing under you".
+    /// How many receiving surfaces are resident; with none, a decal has nothing to land on.
     pub fn receiver_count(&self) -> usize {
         self.surfaces.iter().count()
     }
 
-    /// Does this collider **receive** ground decals?
-    ///
-    /// The mount-tilt probe asks it of whatever its down-ray hit, to decide whether the surface is
-    /// ground worth tilting to. That is a different question from projecting and deserves to read
-    /// like one — it had been spelling the marker into its own query filter.
+    /// Whether this collider receives ground decals, which the mount tilt asks of its down-ray hit.
     pub fn receives(&self, entity: Entity) -> bool {
         self.surfaces.contains(entity)
     }
@@ -249,8 +199,7 @@ impl WorldDecal<'_, '_> {
 mod tests {
     use super::*;
 
-    /// An axis-aligned 2×2×2 box around the origin (`(sin, cos) = (0, 1)`), so in-frame
-    /// coordinates ARE world `(x, z)` and the expected polygons can be written by hand.
+    /// An axis-aligned 2×2×2 box around the origin, so in-frame coordinates are world `(x, z)`.
     fn frame() -> DecalFrame {
         DecalFrame {
             center: Vec3::ZERO,
@@ -274,13 +223,13 @@ mod tests {
         ];
         let (poly, n) = clip_to_frame(tri, &frame());
         assert_eq!(n, 3);
-        // Same vertices, same order — the caller's fan (`poly[0], poly[k], poly[k+1]`) rides it.
+        // Same vertices, same order: the caller's fan rides it.
         assert_eq!(&poly[..3], &tri);
     }
 
     #[test]
     fn a_half_clipped_triangle_emits_the_hand_computed_polygon() {
-        // Crosses only the `max_x` plane; every value below is exact in f32, so `==` is honest.
+        // Crosses only the `max_x` plane; every value below is exact in f32.
         let tri = [
             Vec3::new(0.0, 0.0, 0.0),
             Vec3::new(2.0, 0.0, 0.0),
@@ -288,7 +237,7 @@ mod tests {
         ];
         let (poly, n) = clip_to_frame(tri, &frame());
         assert_eq!(n, 4);
-        // The emit order: each surviving vertex first, then its edge's crossing point.
+        // Each surviving vertex first, then its edge's crossing point.
         assert_eq!(
             &poly[..4],
             &[
diff --git a/crates/benilla-world/src/dev_state.rs b/crates/benilla-world/src/dev_state.rs
index 3c75b082..5630dd92 100644
--- a/crates/benilla-world/src/dev_state.rs
+++ b/crates/benilla-world/src/dev_state.rs
@@ -1,43 +1,17 @@
-//! The dev **state** — resource-only, no egui: the per-subsystem toggles the render and gameplay
-//! systems read, with **player-faithful defaults** (fog on, dome on, everything visible, follow
-//! the server clock, no weather override). Decision 0026's "config out of the editor": this file
-//! is the always-present layer; the debug panel is only the *editor* that writes it. When the
-//! compile-time `dev` seam lands (0026's deferred phase), this module stays in a player build —
-//! the defaults ARE the player behaviour — and only the egui surfaces gate out.
-//!
-//! It was `debug_panel::state` until decision 1164. Living inside the panel's module made the
-//! panel look like the owner of config eight other subsystems read, and it was the second reason
-//! `DebugPanelPlugin` had to be inside the engine's plugin group — the first being the model
-//! `Visibility` authority, now `model_render`'s. With both out, the panel is an instrument again
-//! and the engine boots without it, which is what `benilla-worldview` is for.
+//! The dev state: the per-subsystem toggles the render and gameplay systems read, at
+//! player-faithful defaults. The debug panel only edits it, so it stays in a player build.
 
 use bevy::prelude::*;
 
-/// **Is this a deterministic capture run?** (`$WOW_CAPTURE` set.)
-///
-/// Six engine lanes ask it, and every one of them asks the same question: *freeze what varies with
-/// wall time, so two runs of the same scene produce the same pixels.* Material animation stops
-/// sampling, liquid ticks pin, the doodad-anim tier collapses, the pipeline warmer changes its
-/// mind about what to warm. That is a property of **how the world is being run**, not of the
-/// screenshot harness that happens to switch it on — which is why it lives here, in the
-/// always-present config layer, beside the other environment-armed defaults, rather than in
-/// `capture`. The harness above still owns the *scenario*; it just no longer owns the fact that
-/// there is one.
-///
-/// Cheap by construction: an env read per call, the same shape the caller already paid for.
+/// Whether this is a deterministic capture run (`$WOW_CAPTURE`): wall-time variation freezes.
 pub fn deterministic_run() -> bool {
     std::env::var("WOW_CAPTURE").is_ok()
 }
 
-/// How many frames each still-frame input has read as changed since startup — `[camera
-/// transform, DebugState, ViewDistance, ExteriorWindows, CameraInteriorClaim, any
-/// WmoPortalInstance, any InheritedVisibility]`. The still-frame skips (decision 1979: the
-/// visibility walk, billboards, emitter gates, doodad hosts) engage only when all of these are
-/// still; an input rewritten every frame silently disarms every one of them, and `FPS_PROBE`'s
-/// `noisy=` prints these as per-window deltas so that input is named. The two population
-/// terms are the visibility walk's own last two (`new_portals`, `owner_flips`): they were
-/// added the day the walk's `portals` term read 300 of 300 on a parked city frame for a
-/// latch written through `Mut` — a gate the five resource counters could not see.
+/// Frames each still-frame input has read as changed since startup: `[camera transform,
+/// DebugState, ViewDistance, ExteriorWindows, CameraInteriorClaim, any WmoPortalInstance, any
+/// InheritedVisibility]`. The still-frame skips (visibility walk, billboards, emitter gates,
+/// doodad hosts) engage only while all are still; `FPS_PROBE`'s `noisy=` prints them per window.
 pub static STILL_INPUTS_CHANGED: [std::sync::atomic::AtomicU32; 7] = [
     std::sync::atomic::AtomicU32::new(0),
     std::sync::atomic::AtomicU32::new(0),
@@ -74,17 +48,11 @@ pub(crate) fn count_still_inputs(
     }
 }
 
-/// Root debug state. One resource, grouped into per-subsystem sections. Defaults: panel hidden
-/// (`open: false`), each section its own `Default` (so this derives cleanly).
+/// Root debug state, one section per subsystem.
 #[derive(Resource)]
 pub struct DebugState {
-    /// Panel visible? Hidden by default; toggled with the dev chord + `D` (decisions 1043, 1048).
-    ///
-    /// `$WOW_PANEL=1` starts it **open**, which is how a headless capture run gets the panel into
-    /// the frame. Without it a panel change (a new footer line, a section that grew past the
-    /// scroll reserve) could only be checked in the director's own window, and clipping is exactly
-    /// the failure a capture catches for free. Read here rather than by the panel's plugin,
-    /// alongside this file's other environment-armed defaults.
+    /// Panel visible; toggled with the dev chord + `D`. `$WOW_PANEL=1` starts it open, so a
+    /// headless capture can shoot it.
     pub open: bool,
     pub models: ModelDebug,
     pub lighting: LightingDebug,
@@ -104,14 +72,12 @@ impl Default for DebugState {
     }
 }
 
-/// Weather-instrument state: a panel-armed override that drives the same `WeatherState::apply`
-/// path as the wire (decision 0302), so any type/grade transition can be exercised without a GM
-/// `.wchange`. While `force` is on, wire weather is consumed and ignored.
+/// Weather override through the wire's own `WeatherState::apply` path.
 #[derive(Default)]
 pub struct WeatherDebug {
-    /// Override armed: the scrub below substitutes for the wire.
+    /// Override armed: the scrub below replaces the wire, whose weather is consumed and ignored.
     pub force: bool,
-    /// One-shot: the scrub changed — re-apply it (set by the panel, taken by `weather_tick`).
+    /// One-shot: set by the panel when the scrub changes, taken by `weather_tick`.
     pub dirty: bool,
     /// Wire weather type (0 fine / 1 rain / 2 snow / 3 sand).
     pub kind: u32,
@@ -121,30 +87,22 @@ pub struct WeatherDebug {
     pub instant: bool,
 }
 
-/// Sound-instrument state: the kit probe (the real play path — variation pick + per-shot
-/// variation + category mix), consumed by `sound::kit`. The *config* (enable, master volume)
-/// lives in [`crate::sound::SoundConfig`] — always-on player state per decision 0026; the panel
-/// only edits it. (The pre-kit raw-path probes retired once the kit player became the one real
-/// path — the kit probe exercises device + MPQ + decode end-to-end anyway.)
+/// The sound kit probe, played through the real kit path (`sound::kit`); the sound settings are
+/// `sound::SoundConfig`.
 pub struct SoundDebug {
     /// A `SoundEntries` kit id or name for the "Play kit" probe.
     pub kit_query: String,
     /// One-shot: play `kit_query` through the kit player.
     pub play_kit: bool,
-    /// How many copies of `kit_query` the probe fires **in one frame** (decision 1551).
-    ///
-    /// The reported defect is an overlap defect — "a lot of mobs attacking same time, or a priest
-    /// buffing a group with mass fort" — and it needs no game state to reproduce, only N
-    /// sample-aligned copies of one kit. Five copies of kit 3116 (`HolyProtection`) *is* mass
-    /// Fortitude on a full party, arithmetically: the health line reports the peak the mix asked
-    /// for, and `SoundOutputLimiter` A/Bs what it sounds like.
+    /// Copies of `kit_query` fired in one frame, the overlap case (many attackers, a group buff):
+    /// five of kit 3116 (`HolyProtection`) is a group Fortitude on a full party.
     pub play_copies: u32,
 }
 
 impl Default for SoundDebug {
     fn default() -> Self {
         Self {
-            // A UI kit with several variations — exercises the depleting weighted pick.
+            // A UI kit with several variations, to exercise the depleting weighted pick.
             kit_query: "igMiniMapZoomIn".into(),
             play_kit: false,
             play_copies: 1,
@@ -152,30 +110,21 @@ impl Default for SoundDebug {
     }
 }
 
-/// Scene lighting controls. Colors come from `Light.dbc` sampled at the current time of day (the
-/// **server** game-clock by default). The lighting section is
-/// mostly a readout — the resolved DBC values + sun direction at the current time — plus the time
-/// scrub and a fog-disable toggle. (The tone-gap discovery knobs were removed once that investigation
-/// closed; the faithful path is the only path now.)
+/// Scene lighting controls: `Light.dbc` is sampled at the server game clock unless scrubbed.
 pub struct LightingDebug {
-    /// Follow the live server game-clock (default). When `false`, scrub time with `manual_minute`.
+    /// Follow the live server game clock; when `false`, `manual_minute` sets the time.
     pub follow_server_time: bool,
-    /// Manually-set minute of the game day (`0..1440`), used when `follow_server_time` is off.
+    /// Minute of the game day (`0..1440`) while not following the server.
     pub manual_minute: u32,
-    /// Disable the `Light.dbc` distance fog on terrain + models (debug). The sky-dome horizon colour
-    /// is unaffected (it's the sky band, not the distance fog). Default `false` = faithful fog on.
+    /// Disable the `Light.dbc` distance fog; the sky dome's horizon band is not fog and stays.
     pub disable_fog: bool,
-    /// Hide the gradient sky dome (debug). Default `false` = dome shown (faithful). Useful for A/B and
-    /// for the FPS-debug Performance toggles.
+    /// Hide the gradient sky dome.
     pub disable_sky_dome: bool,
 }
 
 impl Default for LightingDebug {
     fn default() -> Self {
-        // `WOW_CLOCK=<minute 0..1439>` arms the manual scrub from the environment — the
-        // matched-hour capture instrument (a headless probe can't reach the panel slider, and a
-        // time-of-day A/B against a reference screenshot is meaningless at the wrong hour —
-        // bug B33's whole diagnosis hinged on one). Unset = follow the server clock, as before.
+        // `WOW_CLOCK=<minute 0..1439>` arms the manual scrub, to match a reference shot's hour.
         let clock = std::env::var("WOW_CLOCK")
             .ok()
             .and_then(|v| v.trim().parse::<u32>().ok())
@@ -189,17 +138,13 @@ impl Default for LightingDebug {
     }
 }
 
-/// Toggles for the world-model render: per-layer (blend) and per-type visibility (a scene
-/// inspector). Material values (alpha-key cutoff, two-sided culling, and the WoW lighting) are
-/// baked in `model_material` / driven from the Lighting section.
+/// World-model render toggles: visibility per model kind and per blend layer.
 pub struct ModelDebug {
     /// Visible flags indexed by [`crate::model_render::kind_index`].
     pub kind_visible: [bool; 4],
     /// Visible flags indexed by [`crate::model_render::blend_index`].
     pub blend_visible: [bool; 5],
-    /// WMO portal visibility culling on/off (decision 0031). On = the faithful per-group PVS; off =
-    /// every group of a building always drawn (the pre-portal behaviour). An A/B switch for the
-    /// director: flip it off in the Trade District and the cathedral above reappears.
+    /// WMO portal culling: on is the reference's per-group PVS, off draws every group.
     pub portal_cull: bool,
 }
 
@@ -208,8 +153,7 @@ impl Default for ModelDebug {
         Self {
             kind_visible: [true; 4],
             blend_visible: [true; 5],
-            // `WOW_NOPORTALCULL=1` presets the panel's A/B switch off, so a headless capture can
-            // shoot the same viewpoint with and without the cull (the B65 diff loop).
+            // `WOW_NOPORTALCULL=1` starts the cull off, for a headless A/B of one viewpoint.
             portal_cull: std::env::var("WOW_NOPORTALCULL").is_err(),
         }
     }
diff --git a/crates/benilla-world/src/doodad_anim/lazy.rs b/crates/benilla-world/src/doodad_anim/lazy.rs
index 58848afb..40f45fc6 100644
--- a/crates/benilla-world/src/doodad_anim/lazy.rs
+++ b/crates/benilla-world/src/doodad_anim/lazy.rs
@@ -1,31 +1,6 @@
-//! The lazy palette-rig lane (decision 0863): a placed doodad's slot in the 2048-entry skin
-//! palette is claimed at its **first draw-gate wake**, not at spawn — and given back under table
-//! pressure while the host is parked.
-//!
-//! Why: the slot table — not the 131 k-bone slab — is the palette's scarce axis, and the eager
-//! design spent it on the wrong population. The 0863 census across an Elwynn/Stormwind/Westfall
-//! hop leg: 1300–1750 of ~1900 live slots were **parked** doodad hosts (drawn by nobody, player
-//! stopped, slot held), the drawn-set peak was ~630, and the table hit its 2047 cap — at which
-//! point every creature streaming in at the visibility boundary was refused a rig and froze at
-//! bind pose *permanently* (the director's "statue mobs after flying around"). Slots that follow
-//! the drawn set leave the table sized 3× over the real demand.
-//!
-//! The lane's three laws:
-//! - **Promote at wake** ([`promote_lazy_rig`], called from the draw gate): allocate, write the
-//!   current pose's rows (so the swapped-in skinned mesh never renders zeroed — origin-collapsed
-//!   — rows), insert the [`RigSkin`], swap every [`SkinnedTwin`] part `static → skinned` and
-//!   write its tag's rig field. A denial (table momentarily full) is retried every frame the
-//!   host stays drawn — never permanent.
-//! - **Keep while parked** — parking alone frees nothing, so a camera pan is zero churn,
-//!   exactly the pre-0863 behaviour when the table has room.
-//! - **Reap under pressure** ([`reap_parked_rigs`]): when slot headroom drops under
-//!   [`REAP_LOW_WATER`], the longest-parked hosts demote (skinned → static, rig field cleared,
-//!   `RigSkin` removed — the component hook frees the slot). A parked host's meshes are all
-//!   `Visibility::Hidden`, so the demote is invisible by construction.
-//!
-//! An emitter-only host (a chimney's smoke plume: joints for the emitter to ride, no skinned
-//! parts) never gets a [`LazyRig`], so it never takes a slot at all — under the eager design it
-//! held one nobody could read.
+//! The lazy palette-rig lane: a placed doodad claims its skin-palette slot at its first draw-gate
+//! wake, not at spawn, keeps it while parked, and gives it back only under table pressure. An
+//! emitter-only host has no skinned parts, gets no [`LazyRig`] and never takes a slot.
 
 use bevy::mesh::skinning::SkinnedMeshInverseBindposes;
 use bevy::mesh::MeshTag;
@@ -35,43 +10,33 @@ use crate::rig_palette::{RigPalettes, RigSkin};
 
 use super::DoodadAnimHost;
 
-/// Start reclaiming parked rigs when the palette's slot headroom drops below this. Sized to keep
-/// real room for the eager lanes (units at ~120 peak, held items, spell fx) plus a stream-in
-/// burst, while never engaging at all in ordinary scenes.
+/// Reaping starts below this slot headroom: room for the eager lanes and a stream-in burst.
 pub(crate) const REAP_LOW_WATER: usize = 256;
 
-/// Demotions per frame while under pressure — enough to outpace any stream-in burst (a full
-/// tile's placements land over several frames) without a single-frame command spike.
+/// Demotions per frame under pressure: enough to outpace a stream-in without a one-frame spike.
 const REAP_PER_FRAME: usize = 64;
 
-/// A host must have been parked this long (secs) before the reaper may take its slot — a camera
-/// swing across the pack must not demote what the swing-back re-promotes.
+/// Seconds a host must be parked before it is reaped, so a camera swing and back does not churn.
 const REAP_MIN_PARKED_SECS: f32 = 2.0;
 
-/// On the anim-host root: what the wake-edge allocation needs, held until the host is first
-/// drawn. Present ⇔ the placement has skinned parts worth a slot.
+/// On the anim-host root of a placement with skinned parts: what a wake's allocation needs.
 #[derive(Component)]
 pub(crate) struct LazyRig {
-    /// The skeleton's bone count — the allocation size. No joint list since decision 1365: the
-    /// pose lives in the host's [`crate::rig_anim::RigPose`] buffer and the world pass writes
-    /// the rows.
+    /// The skeleton's bone count, the allocation size.
     pub(crate) bones: u32,
     pub(crate) ibp: Handle<SkinnedMeshInverseBindposes>,
-    /// The [`SkinnedTwin`]-carrying part entities the promote/demote swaps.
+    /// The [`SkinnedTwin`] part entities the promote and demote swap.
     pub(crate) parts: Vec<Entity>,
 }
 
-/// On a part spawned on its static form with a skinned twin waiting: the promote swaps
-/// `Mesh3d` to `skinned`, the demote back to `stat`. Both forms are app-built (decision 0834)
-/// and the handles held here keep them resident across the swaps.
+/// A part's static and skinned meshes, swapped by promote and demote and kept resident here.
 #[derive(Component)]
 pub(crate) struct SkinnedTwin {
     pub(crate) skinned: Handle<Mesh>,
     pub(crate) stat: Handle<Mesh>,
 }
 
-/// The part query both edges rewrite. A part that despawned mid-frame (tile streaming out under
-/// the gate) just skips — its host root is on the same placement list and follows it this frame.
+/// The part query both edges rewrite; a part despawned mid-frame is skipped, its host with it.
 pub(super) type TwinParts<'w, 's> = Query<
     'w,
     's,
@@ -82,12 +47,8 @@ pub(super) type TwinParts<'w, 's> = Query<
     ),
 >;
 
-/// The wake edge: allocate the slot, seed its rows from the pose buffer's CURRENT composed
-/// affines, and swap the parts. Returns whether the host now has a rig (so the gate can keep
-/// retrying a denial while the host stays drawn). Rows are seeded before the meshes swap: the
-/// first skinned frame shows the parked pose the static mesh was already showing, and the world
-/// pass takes over the same frame (the wake re-arms the player, whose evaluation re-raises
-/// `pose_dirty`).
+/// The wake edge: allocate the slot, seed its rows from the pose buffer, then swap the parts, so
+/// the first skinned frame shows the pose the static mesh did. Returns whether the host rigged.
 pub(super) fn promote_lazy_rig(
     commands: &mut Commands,
     palettes: &mut RigPalettes,
@@ -99,19 +60,16 @@ pub(super) fn promote_lazy_rig(
     parts: &mut TwinParts,
 ) -> bool {
     let Some(rig) = RigSkin::allocate_bones(palettes, lazy.bones, lazy.ibp.clone()) else {
-        return false; // table full — the warn fired; the gate retries while drawn
+        return false; // table full: the gate retries while drawn
     };
     let slot = rig.slot;
     if let (Some(ibp), Some(pose)) = (ibps.get(&lazy.ibp), pose) {
-        // Rig-relative like every other seed (decision 0974): the same compose the world pass
-        // runs, from the root's propagated world.
+        // Rig-relative, from the root's propagated world, as the world pass composes.
         let root_g = worlds.get(root).copied().unwrap_or_default();
         crate::rig_anim::seed_rig_rows(pose, root_g, &rig, ibp, palettes);
     }
-    // Queued, liveness-checked at APPLY time: the slot's only free path is the component's
-    // `on_replace` hook, so a plain `insert` racing this frame's tile-unload despawn would drop
-    // the `RigSkin` un-attached and leak the slot for the session. (`try_insert` has the same
-    // hole — a failed insert still never runs the hook.)
+    // Liveness-checked at apply: only `RigSkin`'s `on_replace` hook frees the slot, so an insert
+    // (or a failed `try_insert`) racing this frame's tile-unload despawn would leak it.
     commands.queue(
         move |world: &mut bevy::ecs::world::World| match world.get_entity_mut(root) {
             Ok(mut e) => {
@@ -133,8 +91,7 @@ pub(super) fn promote_lazy_rig(
     true
 }
 
-/// The demote — the promote's exact inverse. Removing the [`RigSkin`] is what frees the slot
-/// (its `on_replace` hook), so whoever demotes cannot leak.
+/// The promote's inverse; removing the [`RigSkin`] frees the slot through its hook.
 fn demote_lazy_rig(commands: &mut Commands, root: Entity, lazy: &LazyRig, parts: &mut TwinParts) {
     for &part in &lazy.parts {
         let Ok((mut mesh, mut tag, twin)) = parts.get_mut(part) else {
@@ -143,8 +100,7 @@ fn demote_lazy_rig(commands: &mut Commands, root: Entity, lazy: &LazyRig, parts:
         mesh.0 = twin.stat.clone();
         tag.0 = crate::mesh_tag::with_rig(tag.0, 0);
     }
-    // Liveness-checked like the promote's insert: a host despawned this frame already freed its
-    // slot through the hook, and a plain `entity(root)` would panic at apply.
+    // A host despawned this frame already freed its slot; `entity(root)` would panic.
     commands.queue(move |world: &mut bevy::ecs::world::World| {
         if let Ok(mut e) = world.get_entity_mut(root) {
             e.remove::<RigSkin>();
@@ -152,10 +108,8 @@ fn demote_lazy_rig(commands: &mut Commands, root: Entity, lazy: &LazyRig, parts:
     });
 }
 
-/// The pressure reaper: under [`REAP_LOW_WATER`] slot headroom, demote the longest-parked
-/// rigged hosts, oldest first, up to [`REAP_PER_FRAME`]. Zero work — one headroom read — when
-/// the table has room, which is the ordinary case; the eager lanes (units, quest markers, spell
-/// fx, booths) are never touched, only hosts this module promoted.
+/// Under [`REAP_LOW_WATER`] headroom, demote up to [`REAP_PER_FRAME`] parked hosts, oldest first;
+/// only hosts this lane promoted, never the eager lanes.
 pub(super) fn reap_parked_rigs(
     time: Res<Time>,
     palettes: Res<RigPalettes>,
@@ -178,8 +132,7 @@ pub(super) fn reap_parked_rigs(
             continue;
         };
         demote_lazy_rig(&mut commands, root, lazy, &mut parts);
-        // The RigSkin removal above is a command — the resource's headroom doesn't move until
-        // it applies, so the batch size is the cap here, not the headroom re-read.
+        // Headroom moves only when the queued removals apply, so the batch size is the cap.
     }
 }
 
@@ -190,13 +143,9 @@ mod tests {
     use bevy::animation::graph::AnimationNodeIndex;
     use bevy::mesh::skinning::SkinnedMeshInverseBindposes;
 
-    /// The gate + the reaper on the schedule shape they ship with (gate stamps `parked_at`, the
-    /// reaper reads it), plus every resource the gate's params need. The camera query is empty —
-    /// mesh-backed hosts take the `Visibility` branch.
     fn app() -> App {
         let mut app = App::new();
-        // TimePlugin disabled, `Time` manual — the reroll harness's rule: the real-clock driver
-        // would clobber the whole-window advances the reap-hysteresis assertions need.
+        // `Time` is manual: the real-clock driver would clobber the tests' own advances.
         app.add_plugins((
             bevy::MinimalPlugins
                 .build()
@@ -214,10 +163,7 @@ mod tests {
         app
     }
 
-    /// One host: a hidden-by-default part carrying a [`SkinnedTwin`] of two distinct weak mesh
-    /// handles, a one-bone [`LazyRig`] + [`crate::rig_anim::RigPose`] (the collapsed shape,
-    /// decision 1365), and the mesh-backed draw-gate shape. Returns `(host, part)` — the part IS
-    /// the visibility carrier, like assemble's.
+    /// A host with a one-bone [`LazyRig`] whose single [`SkinnedTwin`] part carries its visibility.
     fn lazy_host(app: &mut App, visible: bool) -> (Entity, Entity) {
         let stat = Handle::<Mesh>::default();
         let skinned = app
@@ -291,11 +237,6 @@ mod tests {
         )
     }
 
-    /// The lazy law end to end: born hidden, a host holds NO slot; a wake allocates on its
-    /// SECOND consecutive drawn frame (the first is the spawn-default-visibility lie — see the
-    /// gate's promote comment), swaps the part to the skinned twin, writes its tag's rig field,
-    /// and seeds the palette rows (the pose buffer's identity bind affine × identity bindpose =
-    /// a non-zero row — the swapped-in mesh never renders zeroed rows).
     #[test]
     fn a_host_rigs_at_first_wake_not_at_spawn() {
         let mut app = app();
@@ -337,13 +278,10 @@ mod tests {
         );
     }
 
-    /// The retry law: a wake into a FULL table is a delay, not a sentence — the host stays on
-    /// the static mesh, and the frame the table has room again (here: one slot freed) the
-    /// still-drawn host promotes. This is the exact failure that used to be permanent.
     #[test]
     fn a_denied_wake_retries_until_the_table_has_room() {
         let mut app = app();
-        // Fill every slot (2047 one-bone rigs), leaking them into a Vec so they stay live.
+        // Fill all 2047 slots with one-bone rigs, held so they stay live.
         let hoard: Vec<RigSkin> = {
             let mut palettes = app.world_mut().resource_mut::<RigPalettes>();
             std::iter::from_fn(|| RigSkin::allocate_bones(&mut palettes, 1, Handle::default()))
@@ -352,33 +290,29 @@ mod tests {
         assert_eq!(app.world().resource::<RigPalettes>().slot_headroom(), 0);
 
         let (host, _part) = lazy_host(&mut app, true);
-        app.update(); // frame 1: the spawn-race frame — never promotes
-        app.update(); // frame 2: a real drawn frame — denied against the full table
+        app.update(); // frame 1: the spawn-race frame never promotes
+        app.update(); // frame 2: drawn, denied by the full table
         assert_eq!(
             rig_slot(&app, host),
             None,
             "full table ⇒ denied, static mesh"
         );
 
-        // One slot frees; the host is still drawn — the very next frame promotes.
         let freed = hoard[0].slot;
         app.world_mut().resource_mut::<RigPalettes>().free(freed);
         app.update();
         assert!(rig_slot(&app, host).is_some(), "room ⇒ the retry lands");
     }
 
-    /// The reaper law: under low slot headroom, a host parked past the hysteresis window gives
-    /// its slot back — part demoted to the static form, tag cleared — and the next wake
-    /// re-promotes. With headroom, a parked host keeps its slot (a camera pan is zero churn).
     #[test]
     fn pressure_reaps_the_parked_and_the_next_wake_re_rigs() {
         let mut app = app();
         let (host, part) = lazy_host(&mut app, true);
         app.update();
-        app.update(); // second consecutive drawn frame — the promote's confirm
+        app.update(); // the second drawn frame promotes
         assert!(rig_slot(&app, host).is_some(), "drawn ⇒ rigged");
 
-        // Park, and age past the reap hysteresis: with plenty of headroom, the slot stays.
+        // Park and age past the hysteresis: with headroom, the slot stays.
         *app.world_mut()
             .entity_mut(part)
             .get_mut::<Visibility>()
@@ -395,7 +329,7 @@ mod tests {
             "parked with headroom ⇒ the slot is kept (zero churn)"
         );
 
-        // Choke the table below the low-water mark: the parked host is reaped.
+        // Choke the table below the low-water mark.
         let _hoard: Vec<RigSkin> = {
             let mut palettes = app.world_mut().resource_mut::<RigPalettes>();
             (0..(crate::mesh_tag::MAX_RIG_SLOTS - 1 - REAP_LOW_WATER))
@@ -403,7 +337,7 @@ mod tests {
                 .collect()
         };
         app.update();
-        app.update(); // command application frame — the RigSkin removal lands
+        app.update(); // the queued removal applies
         assert_eq!(
             rig_slot(&app, host),
             None,
@@ -422,8 +356,7 @@ mod tests {
         );
         assert_eq!(tag_rig, 0, "and its tag's rig field cleared");
 
-        // Re-wake: the still-pressured table has the reaped slot free again — re-promote (two
-        // drawn frames, the confirm).
+        // Re-wake: the reaped slot is free again, and two drawn frames re-promote.
         *app.world_mut()
             .entity_mut(part)
             .get_mut::<Visibility>()
@@ -433,9 +366,6 @@ mod tests {
         assert!(rig_slot(&app, host).is_some(), "the next wake re-rigs");
     }
 
-    /// The emitter-only shape: a host with no [`LazyRig`] (assemble inserts none when nothing
-    /// skins) wakes and parks without ever touching the table — under the eager design every
-    /// chimney's smoke host burned a slot nobody could read.
     #[test]
     fn a_host_without_skinned_parts_never_takes_a_slot() {
         let mut app = app();
@@ -447,24 +377,16 @@ mod tests {
     }
 }
 
-/// The Bevy contract this lane's `Aabb` depends on (decision 1261), pinned against the real
-/// `calculate_bounds` system rather than a reading of it.
-///
-/// `promote_lazy_rig`/`demote_lazy_rig` write `Mesh3d`. Bevy's `calculate_bounds` runs two
-/// queries — an inserting one filtered `Without<Aabb>`, and an **updating** one filtered
-/// `Or<(AssetChanged<Mesh3d>, Changed<Mesh3d>)>` that overwrites a bound the app authored. So the
-/// authored all-animation bound decision 1259 puts on an animated placement survives exactly as
-/// long as nothing swaps that placement's mesh — i.e. until its first draw-gate wake, at which
-/// point it was silently recomputed from the skinned twin's bind-pose geometry and the birds
-/// resumed blinking. `NoAutoAabb` (which both queries exclude) is the fix; this is the guard that
-/// a Bevy upgrade cannot quietly take it back.
+/// Bevy's `calculate_bounds` recomputes a bound whenever `Mesh3d` changes, so an animated
+/// placement's authored all-animation bound survives the lazy rig's twin swap only under
+/// `NoAutoAabb`; these tests pin that Bevy contract.
 #[cfg(test)]
 mod bound_survives_the_twin_swap {
     use super::*;
     use bevy::camera::primitives::Aabb;
     use bevy::camera::visibility::NoAutoAabb;
 
-    /// A 1 yd cube — what the skinned twin's bind-pose geometry computes to.
+    /// A 1 yd cube, the skinned twin's bind-pose bound.
     fn tiny_mesh() -> Mesh {
         Mesh::from(bevy::math::primitives::Cuboid::new(1.0, 1.0, 1.0))
     }
@@ -474,8 +396,7 @@ mod bound_survives_the_twin_swap {
         Aabb::from_min_max(Vec3::new(-4.2, 8.8, -30.5), Vec3::new(13.6, 16.0, 36.6))
     }
 
-    /// `(app, entity)` with Bevy's own bounds system on the schedule and the authored bound in
-    /// place, mid-swap: `Mesh3d` has just been rewritten the way `promote_lazy_rig` rewrites it.
+    /// Bevy's bounds system over the authored bound, right after a promote-style `Mesh3d` swap.
     fn swapped(guard: bool) -> (App, Entity) {
         let mut app = App::new();
         app.add_plugins((bevy::MinimalPlugins, AssetPlugin::default()));
@@ -494,7 +415,6 @@ mod bound_survives_the_twin_swap {
             app.world_mut().entity_mut(e).insert(NoAutoAabb);
         }
         app.update();
-        // The swap the lazy rig performs at the placement's first wake.
         app.world_mut().entity_mut(e).get_mut::<Mesh3d>().unwrap().0 = skinned;
         app.update();
         (app, e)
@@ -504,7 +424,6 @@ mod bound_survives_the_twin_swap {
         *app.world().entity(e).get::<Aabb>().expect("a bound")
     }
 
-    /// The bug: unguarded, the twin swap hands the authored bound back to `compute_aabb`.
     #[test]
     fn an_unguarded_bound_is_clobbered_by_the_mesh_swap() {
         let (app, e) = swapped(false);
@@ -517,7 +436,6 @@ mod bound_survives_the_twin_swap {
         );
     }
 
-    /// The fix: guarded, the authored bound is still the authored bound after the swap.
     #[test]
     fn a_guarded_bound_survives_the_mesh_swap() {
         let (app, e) = swapped(true);
diff --git a/crates/benilla-world/src/doodad_anim/mat_anim.rs b/crates/benilla-world/src/doodad_anim/mat_anim.rs
index 8049dec7..7d5f6eac 100644
--- a/crates/benilla-world/src/doodad_anim/mat_anim.rs
+++ b/crates/benilla-world/src/doodad_anim/mat_anim.rs
@@ -1,60 +1,39 @@
-//! Animated **materials** on placed models (decision 0130 phases 2/3): the per-batch baked
-//! colour-alpha/weight loops ([`MatAnim`] — composed into the render-alpha `MeshTag` by the
-//! visibility authority) and the shared-clock UV-scroll / tint registries
-//! ([`UvAnimMaterials`] / [`TintAnimMaterials`]) their samplers tick. Split from the host module
-//! ([`super`]) along the concern seam: this file is about *material* channels; the host file is
-//! about *bone* channels (the anim host, the variation windows, the draw gate).
+//! Animated materials: the per-batch colour-alpha and weight loops ([`MatAnim`]) and the
+//! texture-transform and tint registries ([`UvAnimMaterials`], [`TintAnimMaterials`]).
 
 use bevy::prelude::*;
 
 use benilla_assets::ModelAnimations;
 
-/// Per-submesh **animated material alpha** (decision 0130 phase 2): the batch's baked
-/// colour-alpha/weight loops + how this instance clocks them. [`sample_mat_anim`] keeps
-/// [`Self::current`] fresh; the model-`Visibility` authority multiplies it into the render-alpha
-/// `MeshTag` it already owns (a composed *input*, not an extra tag writer — the 0066 protocol) and
-/// hides the batch at combined 0 (the verified `A ≤ 0` cull, wow-re `m2-alpha-combine-cull`).
-///
-/// The loops are baked **per sequence** (`benilla_formats::AlphaAnim`), so an instance also has to
-/// say *which* sequence it is playing — see [`Self::host`].
+/// Per-submesh animated material alpha: the batch's per-sequence colour-alpha and weight loops,
+/// sampled into [`Self::current`]. The visibility authority multiplies that into the render-alpha
+/// `MeshTag` and hides the batch at 0, the reference's `A ≤ 0` cull (`0x707b3a`–`0x707b5c`).
 #[derive(Component)]
 pub struct MatAnim {
     anim: std::sync::Arc<benilla_formats::AlphaAnim>,
-    /// The entity whose `AnimationPlayer` decides which sequence's loops to read, re-resolved every
-    /// frame — the **unit lane**, where the played sequence changes constantly and the batch's
-    /// authored visibility changes with it (a voidwalker's upper armour is weight 0 in Stand and 1
-    /// only in Death). `None` for an instance pinned to one sequence for its life: a placed doodad
-    /// (armed once at load with `animations[0]`, wow-re `doodad-anim-host.md`) or a spell effect —
-    /// both then read [`Self::seq`] on the spawn clock, which is the pre-per-sequence behaviour.
+    /// The entity whose `AnimationPlayer` names the sequence to read, re-resolved every frame (the
+    /// unit lane: a voidwalker's upper armour is weight 0 in Stand, 1 in Death). `None` pins the
+    /// instance to [`Self::seq`] on its spawn clock: a spell effect, or a placed doodad, which
+    /// reads slot 0 where the reference reads the sequence each arm picks (op4 `0x7121a0`, called
+    /// from the load build `0x70ebd0` and again on every re-roll).
     host: Option<Entity>,
-    /// The sequence **file slot** to read: fixed at spawn for the pinned lanes, and the last one
-    /// resolved from [`Self::host`] for the unit lane. `None` ⇒ slot 0 (the bake's own degrade).
+    /// The file sequence slot to read: fixed when pinned, the last one resolved from
+    /// [`Self::host`] otherwise; `None` reads slot 0.
     seq: Option<usize>,
-    /// `Time::elapsed_secs` at spawn — the clock origin (arm-time phase, like the bone host). Only
-    /// the pinned lanes use it; a hosted instance reads the player's own seek time instead, so its
-    /// alpha stays in phase with the pose that drives it.
+    /// `Time::elapsed_secs` at spawn, the pinned lanes' clock origin; a hosted instance reads its
+    /// player's seek time, so its alpha stays in phase with its pose.
     spawned_at: f32,
-    /// Captures freeze the clock at 0 for deterministic frames (dimming constants still show).
+    /// Captures freeze the clock at 0 for deterministic frames.
     frozen: bool,
-    /// This instance's sampled value drives the render-alpha `MeshTag` field **by itself** (no
-    /// `DoodadFade` on the entity): the spell-effect parts (`entities::spell_fx`), whose alpha
-    /// channel has no other writer. `false` on the doodad lane — there the visibility authority
-    /// owns the tag and composes [`Self::current`] in (for a fade holder multiplied with the
-    /// distance fade; for a lit interior prop written alone into the probe payload's alpha field,
-    /// bits 0..=15 since the 0355 re-lane) — and on the unit lane, whose own compose is
-    /// [`crate::entities::apply_unit_mat_alpha`].
+    /// The sample drives the render-alpha `MeshTag` field by itself: the spell-effect parts, whose
+    /// alpha has no other writer. `false` on the doodad lane, where the visibility authority
+    /// composes [`Self::current`] in, and on the unit lane (`entities::apply_unit_mat_alpha`).
     pub(crate) drives_tag: bool,
-    /// This instance belongs to the **unit lane's** tag compose
-    /// ([`crate::entities::apply_unit_mat_alpha`]) even though it has no [`Self::host`] to read a
-    /// sequence from: the ATTACH-MODEL case (a held weapon, a helm, a pauldron). Such a model
-    /// spawns no rig — it rests in its file's first sequence, so its loops are pinned like a
-    /// placed doodad's — but it hangs off a unit, so the compose has to be the one ordered against
-    /// the wearer's appear-fade and interior classifier rather than the world-model visibility
-    /// authority's. See [`Self::resting`].
+    /// Composed by the unit lane without a [`Self::host`]: an attach model (a held weapon, a helm),
+    /// pinned like a doodad but ordered against the wearer's appear-fade. See [`Self::resting`].
     unit_lane: bool,
-    /// The gseq factors' ATTACH anchor (secs on the shared clock): `None` until the first
-    /// [`sample_mat_anim`] pass stamps it — the reference snapshots the scene clock once per
-    /// model instance at attach (`CM2Model+0x68`, wow-re `gseq-anchor.md`; decisions 0856/0858).
+    /// The gseq attach anchor (secs, shared clock), stamped by the first [`sample_mat_anim`] pass:
+    /// the reference snapshots the scene clock once per instance at attach (`CM2Model+0x68`).
     gseq_attach: Option<f64>,
     /// The last sampled combined factor (colour-alpha × weight), read by the visibility authority.
     pub current: f32,
@@ -66,8 +45,7 @@ impl MatAnim {
         now: f32,
         frozen: bool,
     ) -> Self {
-        // The seed sample: both clocks at 0 — nothing armed, and the attach anchor (stamped on
-        // the first live pass) makes the gseq cursor open at 0 too.
+        // Seed at both clocks' 0: nothing is armed, and the gseq cursor opens at its anchor.
         let current = anim.sample(None, 0.0, 0.0);
         Self {
             anim,
@@ -82,10 +60,8 @@ impl MatAnim {
         }
     }
 
-    /// The spell-effect-lane constructor: never frozen (the `fxview` instrument ages effects
-    /// through captures; golden scenarios spawn no effects), the sampled alpha drives the part's
-    /// render-alpha tag directly (see [`Self::drives_tag`]), and the instance is pinned to the one
-    /// sequence its rig plays (`seq` — the missile's InFlight, else the file-order-first clip).
+    /// The spell-effect lane: never frozen, driving the part's tag itself, and pinned to the
+    /// sequence its rig plays (`seq`: the missile's InFlight, else the file-order-first clip).
     pub fn driving_tag(
         anim: std::sync::Arc<benilla_formats::AlphaAnim>,
         now: f32,
@@ -98,24 +74,16 @@ impl MatAnim {
         m
     }
 
-    /// Read the sequence (and its clock) from `host`'s live `AnimationPlayer` each frame instead of
-    /// staying pinned to the slot this instance opened on — for a spell-effect instance that
-    /// **advances** through its authored lifecycle (`Stand` → `Hold` → `Decay`, wow-re
-    /// `ceffect-anim-lifecycle.md`), because each leg has its own authored alpha loops: Ice
-    /// Barrier's pulse is as much the `Hold` band's oscillating transparency weights as its bone
-    /// scale. `None` leaves the instance pinned (a lane with no rig has no player to ask).
-    ///
-    /// It keeps [`Self::drives_tag`], so this stays an effect part writing its own tag — it borrows
-    /// the unit lane's *sequence source*, not its tag-compose ownership.
+    /// Read the sequence and clock from `host`'s live `AnimationPlayer` each frame, for an effect
+    /// that advances Stand, Hold, Decay (`0x5ff170` arms Hold, `0x5ff270` the terminal Decay), each
+    /// leg with its own alpha loops. It keeps [`Self::drives_tag`]; `None` leaves it pinned.
     pub fn following_host(mut self, host: Option<Entity>) -> Self {
         self.host = host;
         self
     }
 
-    /// The **unit-lane** constructor: the sequence (and its clock) come from `host`'s live
-    /// `AnimationPlayer`, so a creature's batches appear and disappear with the animation exactly
-    /// as authored. The tag is composed by [`crate::entities::apply_unit_mat_alpha`], not driven
-    /// here — the interior classifier and the appear-fade already own that channel.
+    /// The unit lane: sequence and clock come from `host`'s live `AnimationPlayer`, and the tag is
+    /// composed by `entities::apply_unit_mat_alpha`, not driven here.
     pub fn following(anim: std::sync::Arc<benilla_formats::AlphaAnim>, host: Entity) -> Self {
         Self {
             host: Some(host),
@@ -123,14 +91,8 @@ impl MatAnim {
         }
     }
 
-    /// The **attach-model** constructor (a held weapon, a helm, a pauldron): the loops are pinned
-    /// to the file's first sequence — an item model spawns no rig and rests there, the same reason
-    /// its emitters and ribbons read Stand — while the tag compose stays the unit lane's, ordered
-    /// against the wearer's appear-fade and interior classifier.
-    ///
-    /// Its clock is irrelevant in practice (a rest-pose model's tracks are the constants the file
-    /// authors) so it takes no `now`; sampling still runs every frame like every other lane, so a
-    /// keyed track on a rest sequence animates rather than latching at its first key.
+    /// The attach-model lane (a held weapon, a helm): pinned to the file's first sequence, where a
+    /// rig-less item model rests, and composed by the unit lane.
     pub fn resting(anim: std::sync::Arc<benilla_formats::AlphaAnim>) -> Self {
         Self {
             unit_lane: true,
@@ -138,29 +100,18 @@ impl MatAnim {
         }
     }
 
-    /// Whether this instance's tag alpha is the unit lane's to compose (see
-    /// [`crate::entities::apply_unit_mat_alpha`]) — a hosted creature/player batch, or an
-    /// attach model's batch ([`Self::resting`]), and never a self-driving effect part.
+    /// Whether the unit lane composes this instance's tag: a hosted or attach-model batch, never an
+    /// effect part that drives its own.
     pub fn composes_unit_tag(&self) -> bool {
         (self.host.is_some() || self.unit_lane) && !self.drives_tag
     }
 }
 
-/// The sequence slot + clip-local time a host is playing, for [`sample_mat_anim`]: the **base**
-/// animation with the greatest blend weight. Masked overlays (a torso-only swing, an arm's draw
-/// ceremony, the finger grip) run on their own graph nodes and are deliberately skipped — they
-/// pose bones, they don't reselect the sequence the material tracks read. During a cross-fade two
-/// base clips are live and the heavier one wins; the reference instead blends the two sampled
-/// scalars by λ (wow-re `eval.md` FN 0x71af20's blend leg), a sub-blend-time difference on tracks
-/// the corpus authors as 0/1 steps — recorded, not modelled.
-///
-/// A player with **nothing armed** is not "no sequence" — the reference arms the loader-idle clip on
-/// every M2 instance at load, so the answer is that sequence at its opening frame
-/// ([`ModelAnimations::idle_seq`], decision 0936). benilla's rig tier skips the arm whenever looping
-/// the idle would render identically to the static mesh, and that skip used to leak out of the mesh
-/// question into this one: both callers read the returned `None` as "keep the pinned slot", which
-/// starts life at file slot 0. On a Spawn/Stand/Despawn GameObject slot 0 is the Spawn flourish, so
-/// the batch read a sequence the instance was never playing.
+/// The sequence slot and clip time a host plays: its base animation with the greatest weight, as
+/// masked overlays pose bones without reselecting the sequence. In a cross-fade the heavier clip
+/// wins, where the reference blends the two samples by λ (`0x71af20`). With nothing armed it is
+/// the loader-idle sequence at t = 0 ([`ModelAnimations::idle_seq`]): the reference arms that clip
+/// on every M2 at load, and slot 0 can be another sequence (a GameObject's Spawn).
 pub fn playing_seq(player: &AnimationPlayer, anims: &ModelAnimations) -> Option<(usize, f32)> {
     player
         .playing_animations()
@@ -173,33 +124,23 @@ pub fn playing_seq(player: &AnimationPlayer, anims: &ModelAnimations) -> Option<
         .or_else(|| anims.idle_seq().map(|seq| (seq, 0.0)))
 }
 
-/// Sample every instance's material-alpha loops: a hosted instance on its host's playing sequence
-/// and clip clock, a pinned one on its own spawn clock. Frozen (capture) instances keep their t=0
-/// sample. Hidden instances sample too — the visibility authority's alpha cull reads
-/// [`MatAnim::current`], so a batch BORN at weight 0 (`HolyLight_Low_Head`'s light column, keyed
-/// `0 → 1` at 300 ms) must keep its clock running or the alpha-hide latches forever (the old
-/// skip-while-Hidden held `current` at the 0 that caused the hide — the invisible pala-heal flash).
-/// Sampling is a pure function of the clock, so an instance hidden for any *other* reason (draw
-/// gate, far-clip) still lands right on re-appear, and the reference animation-evaluates the tracks
-/// every frame regardless of the cull (wow-re `m2-alpha-combine-cull`). Runs before the visibility
-/// authority so the tag it composes is this frame's value.
+/// Sample every instance: a hosted one on its host's sequence and clip clock, a pinned one on its
+/// spawn clock; frozen ones keep their t = 0 sample. Hidden instances sample too, as the reference
+/// evaluates the tracks every frame regardless of the cull (`0x707b3a`–`0x707b5c`), or a batch
+/// born at weight 0 would stay hidden. Runs before the visibility authority.
 pub fn sample_mat_anim(
     time: Res<Time>,
     hosts: Query<(&AnimationPlayer, &ModelAnimations)>,
     mut q: Query<&mut MatAnim>,
 ) {
     let now = time.elapsed_secs();
-    // The scene clock, full-precision (a long-uptime f32 elapsed drifts whole milliseconds,
-    // which a 433 ms twinkle shows): the base the per-instance gseq attach anchor subtracts
-    // from (0856).
+    // The scene clock in f64: a long-uptime f32 drifts whole milliseconds.
     let shared = time.elapsed_secs_f64();
     for mut m in &mut q {
         if m.frozen {
             continue;
         }
-        // A hosted instance whose host has no player yet (the frame before the rig arms, or a
-        // rest-pose GameObject) keeps its last resolved slot and reads it at t=0 — the sequence's
-        // opening pose, which is what a model sitting at bind pose shows.
+        // A host with no player yet keeps its last slot at t = 0, a bind-posed model's pose.
         let played = m
             .host
             .and_then(|h| hosts.get(h).ok())
@@ -212,135 +153,70 @@ pub fn sample_mat_anim(
             None if m.host.is_some() => (m.seq, 0.0),
             None => (m.seq, now - m.spawned_at),
         };
-        // The instance's gseq cursor: sceneNow − attach, the anchor stamped on this first pass
-        // (decisions 0856/0858 — every lane, spell effects included: fresh instance per play).
+        // The gseq cursor is sceneNow − attach, the anchor stamped on the first pass.
         let attach = *m.gseq_attach.get_or_insert(shared);
         m.current = m.anim.sample(seq, elapsed, shared - attach);
     }
 }
 
-/// The **UV-animated materials** registry (decision 0130 phase 3, wow-re `m2-texanim-uv`): each
-/// batch material carrying a texture-transform translation loop, keyed by material asset id.
-/// [`tick_anim_materials`] re-samples a *drawn* entry's offset into the material's `sun_scale.zw`
-/// each frame — one shared uniform per material, so every instance of a model batch scrolls in
-/// phase. A recorded, invisible divergence for BOTH clock laws (0856): the reference phases a
-/// seq-band loop per play (arm cursor) and a gseq loop per instance (attach anchor,
-/// `gseq-anchor.md`), but one uniform per material cannot phase per instance — meaningless for a
-/// seamless scroll either way. Entries drop when the material asset does.
-/// The scan marker (1375): a part whose material can ever be a [`UvAnimMaterials`]/
-/// [`TintAnimMaterials`] key — inserted at spawn, beside the registration itself, and only for a
-/// loop with a real period (a period-0 constant is fully served by its material seed). Without
-/// it, [`tick_anim_materials`]'s draw scan visited every `WowModelMaterial` row in the world
-/// (~48k at Stormwind) to find the placed instances of ~113 animated models.
+/// The scan marker: a part whose material can be a [`UvAnimMaterials`] or [`TintAnimMaterials`]
+/// key, inserted at spawn beside the registration, so the draw scan visits only animated parts.
 #[derive(bevy::prelude::Component)]
 pub struct AnimMatPart;
 
-/// **Which loop a registered material animates on** — and the whole of decision 1408.
-///
-/// A registry keyed by MATERIAL is shared by every instance of a batch, so it has no sequence to
-/// key on. That is exactly right while every sequence bakes the same loop, and structurally unable
-/// to be right when they don't: the BRM lava bubbles key their whole flipbook inside a 50 %-weighted
-/// variation, and their 15 placements re-roll independently every ~3.3 s (decision 0768), so at any
-/// instant some are on slot 0 and some on slot 1. One shared row cannot serve both.
-///
-/// So a batch whose slots disagree — 22 batch-channels across **6 models**, corpus-wide
-/// (`benilla-extract uvslotscan`) — takes a material of its own **per placement**, keyed by its
-/// anim host in [`crate::model_render::MatKey`], and this entry remembers that host so the sample
-/// rides the sequence the host is actually playing. Everything else keeps the shared material and
-/// the shared clock, untouched.
-///
-/// Per-placement materials rather than a per-instance row in the shared table: the row would have
-/// to be addressed from the shader, and every per-instance channel there is spoken for
-/// (`MeshTag`'s 32 bits are fully allocated; the instance slot is the lazily-allocated,
-/// pressure-reaped palette slot). Against a measured population of six models it buys a new GPU
-/// region and a shader branch to save a handful of draw calls on small atmospheric props, and the
-/// clones are bounded by the same distance evictor every other material has (`art_scope`,
-/// decision 0785). Revisit if the population ever grows.
+/// Which loop a registered UV material animates on. A material-keyed row serves every instance of
+/// the batch, so a batch whose sequence slots bake different loops takes a material per placement
+/// (keyed by its anim host in [`crate::model_render::MatKey`]) and follows that host's slot.
 pub enum UvLoop {
-    /// Every sequence bakes the same loop: the shared material, on the free-running shared clock.
+    /// Every slot bakes the same loop: the shared material on the free-running scene clock. `None`
+    /// for a rotate- or scale-only transform, whose translation row stays at zero.
     ///
-    /// `None` when the batch's transform carries **no translation at all** — a rotate-only or
-    /// scale-only transform, whose whole motion is the [`UvAnimEntry::affine`] row beside this
-    /// one. Two entity batches in the shipped corpus are exactly that
-    /// (`World\Goober\G_ScryingBowl`'s water and `G_ScourgeRuneCircleCrystal`'s rune ring, both
-    /// `chans —R—`), so a lane that made the translation mandatory would have to invent a
-    /// zero loop for them or drop them silently. The entry still holds its translation row; it
-    /// stays at zero, which is what that row means.
+    /// Deviation: every instance scrolls in one phase, where the reference phases a band loop per
+    /// arm and a gseq loop from each instance's attach (`CM2Model+0x68`), because one uniform
+    /// serves the material and a seamless scroll looks the same at any phase.
     Shared(Option<std::sync::Arc<benilla_formats::UvAnim>>),
-    /// The slots disagree: this material belongs to ONE placement, and the loop is whichever slot
-    /// `host` is playing right now.
+    /// The slots disagree: this material belongs to one placement, on whichever slot `host` plays.
     PerSeq {
         seqs: std::sync::Arc<benilla_formats::SeqLoops<[f32; 2]>>,
         host: Entity,
     },
-    /// The **spell-effect** lane (decision 2282): this material is one effect instance's own
-    /// clone, and the scroll rides that instance's clip — `host`'s live `AnimationPlayer`, the
-    /// same source [`MatAnim::following_host`] reads, so the two material channels of one cast
-    /// stay in step through `Stand` → `Hold` → `Decay`.
-    ///
-    /// **Per instance, not shared, because on an effect the scroll is not ambience — it IS the
-    /// animation.** A waterfall's loop is seamless, so one uniform for every placement on a
-    /// free-running clock is indistinguishable from the truth. The druid's claw trail is a
-    /// one-shot reveal: `Spells\SwipeCaster.m2` is two strips whose UVs are authored wholly
-    /// outside `0..1` against a CLAMP-addressed sheet, and the 1.5 s U-scroll is what drags the
-    /// claw along them. On a shared clock every bear in the raid would sweep in one phase none of
-    /// their casts chose; frozen at the track's first key — which is what the effect lane did
-    /// until 2282 — the strips sample only the sheet's transparent border and the trail does not
-    /// exist at all.
-    ///
-    /// `seqs` (1408's per-slot set) when the batch's slots disagree, `single` otherwise; a batch
-    /// whose slot 0 is dead beside a live later slot carries only the first, so both are optional
-    /// and at least one is always present.
+    /// The spell-effect lane: one effect instance's own clone, scrolling on that instance's clip
+    /// (`host`'s player, as [`MatAnim::following_host`] reads it), because an effect's scroll is
+    /// its animation: `SwipeCaster.m2`'s UVs lie outside a clamped sheet until the scroll drags
+    /// the claw in. `seqs` when the slots disagree, `single` otherwise; at least one is present.
     Instance {
         seqs: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 2]>>>,
         single: Option<std::sync::Arc<benilla_formats::UvAnim>>,
         host: Entity,
-        /// `Time::elapsed_secs` at attach — this instance's clock origin. It is the band clock
-        /// for an instance whose model arms no player, and the global-sequence anchor
-        /// (`sceneNow − attach`, decisions 0856/0858: one fresh instance per play) for every one.
+        /// `Time::elapsed_secs` at attach: the band clock when the model arms no player, and the
+        /// gseq anchor (`sceneNow − attach`, a fresh instance per play) always.
         attached_at: f32,
     },
 }
 
-/// One registered UV-scroll material: its sampler, its table slot, and the built seed the delta
-/// rows are measured from (the material's own `sun_scale.zw`, which is never mutated again —
-/// decision 1381).
+/// One registered UV material (the texture-transform translation `0x716216` gates): its loop, its
+/// table slot, and the built `sun_scale.zw` seed its delta rows are measured from, never mutated.
 pub struct UvAnimEntry {
     pub anim: UvLoop,
     pub slot: u16,
     pub seed: [f32; 2],
-    /// The effect lane's **affine half** ([`UvAffine`], decision 2282) — `None` on every other
-    /// lane, and on an effect batch whose transform only translates (the common case).
+    /// The rotation and scaling half ([`UvAffine`]), `None` when the transform only translates.
     affine: Option<UvAffine>,
 }
 
-/// A texture transform's ROTATION and SCALING, on the effect lane: the two channels the
-/// translation row cannot carry, and the second table row that does ([`affine_row`]'s encoding,
-/// decision 2019).
-///
-/// They ride the same instance clock as the translation beside them, and they exist here for the
-/// same reason that one does — `Spells\ShieldWall_Impact_Base.mdx`'s halo turns AND scales, and
-/// `Spells\GroundingTotem_Impact.mdx` is a **scale-only** transform, so a lane that ran only the
-/// scroll would still render both wrong. `benilla-extract fxuvscan` is where that population is
-/// read; it is three models today, which is exactly why nobody would have found them by eye.
+/// A texture transform's rotation and scaling, which the translation row cannot carry: a second
+/// table row (`crate::mat_anim_table::affine_row`'s encoding) on the translation's clocks.
 struct UvAffine {
     rot: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 4]>>>,
     scale: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 2]>>>,
-    /// The affine row's slot (`anim_slots.z`). Its encoding is a delta from the IDENTITY, not
-    /// from a material seed — row 0 is the identity, so there is nothing to measure from.
+    /// The affine row's slot (`anim_slots.z`); the row is a delta from the identity, not a seed.
     slot: u16,
 }
 
 impl UvAnimEntry {
-    /// The slot's delta row for `now`: the quantized sample minus the built seed — the shader
-    /// adds it back onto `sun_scale.zw` (decision 1381's encoding). Quantized exactly as the
-    /// old asset-mutating lane quantized its absolute writes, so the first live frame shows the
-    /// same number the old path would have written.
-    ///
-    /// `playing` is the per-placement lane's live `(sequence slot, clip time)`, resolved by the
-    /// caller from [`Self::host`]; a host that has gone (despawned mid-frame) or a sequence with no
-    /// loop samples the identity, i.e. the batch sits at its built seed — the same degrade a full
-    /// table gives.
+    /// The slot's delta row for `now`: the quantized sample minus the built seed, which the shader
+    /// adds back onto `sun_scale.zw`. `playing` is the host's `(slot, clip time)`; a gone host or a
+    /// slot with no loop samples a zero offset.
     pub(crate) fn delta(&self, now: f32, gseq_now: f64, playing: Option<(usize, f32)>) -> [f32; 4] {
         let uv = match &self.anim {
             UvLoop::Shared(anim) => anim.as_ref().map_or([0.0, 0.0], |a| a.sample(now)),
@@ -350,10 +226,8 @@ impl UvAnimEntry {
                         .map(|l| l.sample(l.clock(band_t, gseq_now)))
                 })
                 .unwrap_or([0.0, 0.0]),
-            // The effect lane's clocks are the INSTANCE's, never the scene's (2282): the band
-            // clock is the clip this instance is playing — the spawn age while its rig has no
-            // player yet, which is `MatAnim`'s own degrade — and the gseq cursor is measured from
-            // its attach rather than from process start.
+            // The effect lane's clocks are the instance's: the band clock is its clip time (its
+            // age while the rig has no player), and the gseq cursor runs from its attach.
             UvLoop::Instance {
                 seqs,
                 single,
@@ -376,11 +250,8 @@ impl UvAnimEntry {
         ]
     }
 
-    /// This entry's **affine** row and the slot it goes in, or `None` when the transform only
-    /// translates. Sampled on **the same clocks [`Self::delta`] uses for this entry's own lane**,
-    /// so the three channels of one transform are always read at one instant — a rotation read on
-    /// the scene clock beside a translation read on an instance's play head would be two different
-    /// moments of the same matrix.
+    /// This entry's affine slot and row, sampled on the clocks [`Self::delta`] uses so all three
+    /// channels of one transform read one instant; `None` when the transform only translates.
     pub(crate) fn affine(
         &self,
         now: f32,
@@ -388,9 +259,6 @@ impl UvAnimEntry {
         playing: Option<(usize, f32)>,
     ) -> Option<(u16, [f32; 4])> {
         let a = self.affine.as_ref()?;
-        // Per lane, exactly as `delta` does it: the shared lane reads the free-running scene clock
-        // on both, the per-placement lane its host's playing clip, and the effect lane its own
-        // age-anchored pair (decisions 0856/0858).
         let (band_t, gseq) = match &self.anim {
             UvLoop::Shared(_) => (now, gseq_now),
             UvLoop::PerSeq { .. } => (playing.map_or(now, |(_, t)| t), gseq_now),
@@ -415,7 +283,6 @@ impl UvAnimEntry {
 }
 
 impl UvAnimEntry {
-    /// The placement whose sequence this entry rides, or `None` on the shared lane.
     fn host(&self) -> Option<Entity> {
         match &self.anim {
             UvLoop::Shared(_) => None,
@@ -423,18 +290,12 @@ impl UvAnimEntry {
         }
     }
 
-    /// Is this the **spell-effect** lane ([`UvLoop::Instance`])? The one entry kind
-    /// [`tick_anim_materials`] keeps sampling inside a deterministic capture, on exactly
-    /// [`MatAnim`]'s and `spell_fx::FxTintAnims`' own argument: an effect's clock is its
-    /// instance's frame-stepped `AnimationPlayer`, not wall time, so `fxview` can age one without
-    /// any golden scenario — which spawns no effects at all — moving a pixel.
+    /// The spell-effect lane, sampled even in a capture: its clock is its instance's player.
     fn instance_lane(&self) -> bool {
         matches!(self.anim, UvLoop::Instance { .. })
     }
 
-    /// The loop this entry samples right now — the instrument's read
-    /// ([`crate::doodad_anim::matanim_probe`]), so the probe's period and phase sweep come from
-    /// the same resolution [`Self::delta`] makes rather than a hand-rolled twin of it.
+    /// The loop this entry samples now, resolved as [`Self::delta`] does, for [`matanim_probe`].
     fn resolved(&self, playing: Option<(usize, f32)>) -> Option<&benilla_formats::UvAnim> {
         match &self.anim {
             UvLoop::Shared(a) => a.as_deref(),
@@ -446,9 +307,7 @@ impl UvAnimEntry {
         }
     }
 
-    /// The `now` a phase-sweep sample passes for this entry. The effect lane measures its clocks
-    /// from ATTACH, so handing it a raw phase `t` would read as a negative age; every other lane
-    /// is already on the scene clock. (The sweep moves the play head too — see the caller.)
+    /// A phase sweep's `now`: the effect lane counts from attach, the others on the scene clock.
     fn phase_now(&self, t: f32) -> f32 {
         match &self.anim {
             UvLoop::Instance { attached_at, .. } => attached_at + t,
@@ -458,7 +317,6 @@ impl UvAnimEntry {
 }
 
 impl TintAnimEntry {
-    /// [`UvAnimEntry::host`]'s twin.
     fn host(&self) -> Option<Entity> {
         match &self.anim {
             TintLoop::Shared(_) => None,
@@ -467,12 +325,9 @@ impl TintAnimEntry {
     }
 }
 
-/// The anim hosts a per-placement entry reads its sequence from — [`playing_seq`] behind a query,
-/// so [`tick_anim_materials`] can resolve one per entry without borrowing the world twice.
+/// The anim hosts a per-placement entry reads its sequence from, for [`playing_seq`].
 pub type SeqHosts<'w, 's> = Query<'w, 's, (&'static AnimationPlayer, &'static ModelAnimations)>;
 
-/// The playing sequence slot + clip time of one anim host, or `None` if the entry is on the shared
-/// lane, the host is gone, or it has no sequence at all.
 fn host_seq(hosts: &SeqHosts, host: Option<Entity>) -> Option<(usize, f32)> {
     let (player, anims) = hosts.get(host?).ok()?;
     playing_seq(player, anims)
@@ -486,11 +341,9 @@ pub struct UvAnimMaterials(
     >,
 );
 
-/// Register material `id` for the per-frame UV scroll: allocate its table slot, remember the
-/// built seed, and bake the slot index into the material's `anim_slots.x` — the ONE material
-/// write this lane ever makes (spawn-frame, where the asset is Modified anyway). A full table
-/// (never seen below ~500 resident animated materials) skips registration: the batch stays
-/// frozen at its built seed — a degraded look, never a wrong pixel.
+/// Register material `id` for the UV scroll: allocate its table slot, record the built seed and
+/// write the slot into `anim_slots.x`, the one material write this lane makes. A full table skips
+/// registration, leaving the batch at its seed.
 pub(crate) fn register_uv(
     reg: &mut UvAnimMaterials,
     table: &mut crate::mat_anim_table::MatAnimTable,
@@ -505,18 +358,14 @@ pub(crate) fn register_uv(
         bevy::log::warn_once!("mat-anim table full — a UV-scroll batch stays at its seed");
         return;
     };
-    // **Through the parked half, not `Assets::get_mut`** (decision 2038). A material this
-    // spawner just built is not in the store yet — `model_render::lazy` reserves its handle and
-    // parks the value until something view-visible binds it — so the store-only read returned
-    // `None` for *every* registration, freed the slot again and left the registry empty: no UV
-    // scroll and no animated tint anywhere in the world, silently, from the day deferral landed.
+    // Through the parked half, not `Assets::get_mut`: `model_render::lazy` parks a just-built
+    // material outside the store until something visible binds it.
     let Some(seed) = crate::model_render::lazy::with_material_mut(materials, id, |mat| {
         let seed = [mat.extension.sun_scale.z, mat.extension.sun_scale.w];
         mat.extension.anim_slots.x = f32::from(slot);
         seed
     }) else {
-        // Neither half holds it: a dead or foreign handle, and nothing to animate. Loud, because
-        // the silent version of this branch is what cost three days of frozen water.
+        // Neither half holds it: a dead or foreign handle, warned so a dead lane is never silent.
         bevy::log::warn_once!(
             "mat-anim: no material behind {id} — a UV-scroll batch stays at its seed"
         );
@@ -524,10 +373,6 @@ pub(crate) fn register_uv(
         return;
     };
     match &anim {
-        // The breadcrumb for the lanes that have no other tell: a per-placement or per-instance
-        // material is invisible in every count (it is one more material, one more row), so "did
-        // the bubbles / the claw trail take the new lane at all" would otherwise be a question
-        // only the eye could answer. One line per registration, at debug (decisions 1408, 2282).
         UvLoop::PerSeq { host, .. } => {
             bevy::log::debug!("mat-anim: per-placement UV lane armed for host {host} (slot {slot})")
         }
@@ -549,14 +394,9 @@ pub(crate) fn register_uv(
     );
 }
 
-/// Attach the ROTATION/SCALING half to an entry [`register_uv`] has just made, if the batch has
-/// one — the second table row, `anim_slots.z`, and 2019's `[cos − 1, sin, sx − 1, sy − 1]`
-/// encoding whose zero row IS the identity.
-///
-/// The translation half decides whether there is an entry at all (a full table, a dead handle);
-/// the affine half attaches to it or not at all. A transform that ONLY rotates or scales still
-/// takes a translation row that stays at zero — one row, on a population of five models corpus-
-/// wide, for a registration path with one shape instead of two.
+/// Attach the rotation and scaling half, if any, to the entry [`register_uv`] just made: a second
+/// row, its slot in `anim_slots.z`, encoded `[cos − 1, sin, sx − 1, sy − 1]` so the zero row is
+/// the identity. A rotate- or scale-only transform still owns a translation row.
 fn attach_affine(
     reg: &mut UvAnimMaterials,
     table: &mut crate::mat_anim_table::MatAnimTable,
@@ -584,20 +424,9 @@ fn attach_affine(
     }
 }
 
-/// Put one **spell-effect material clone** on the per-instance UV lane (decision 2282): the
-/// engine's whole door for `entities::spell_fx`, which owns the clone and nothing else about how
-/// the scroll is delivered.
-///
-/// One door rather than the three pieces behind it ([`UvLoop`]'s effect variant, [`register_uv`],
-/// the table row), because they are one fact — *this clone scrolls, on that instance's clip* —
-/// and the class of bug this lane keeps producing is a caller that took some of the pieces and
-/// not the rest (decision 2038's registry of marked-but-unregistered parts is the same shape).
-///
-/// `seqs` / `single` are the batch's baked loops in 1408's two spellings, at least one present;
-/// `host` is the effect instance root whose `AnimationPlayer` names the playing clip, and
-/// `attached_at` its `Time::elapsed_secs` origin. The clone's `sun_scale.zw` is read as the seed
-/// the delta rows are measured from, exactly as on the shared lane, so a caller that seeds it at
-/// the loop's own `t = 0` gets a correct FIRST frame before this lane has written a row.
+/// Put one spell-effect material clone on the per-instance UV lane, whole: the [`UvLoop`] effect
+/// variant, [`register_uv`] and both table rows. `host` is the effect root whose player names the
+/// clip, `attached_at` its `Time::elapsed_secs` origin, and the clone's `sun_scale.zw` the seed.
 pub fn register_fx_uv(
     reg: &mut UvAnimMaterials,
     table: &mut crate::mat_anim_table::MatAnimTable,
@@ -631,11 +460,8 @@ pub fn register_fx_uv(
         return;
     };
     let _ = turns;
-    // **Both rows, written now.** `tick_anim_materials` runs once per frame in `Update` and this
-    // registration happens in the same schedule, so an instance that attaches after the tick would
-    // otherwise draw its first frame at row 0 — the identity, which on this population is the
-    // authored-UV frame the whole decision is about (a Swipe strip renders NOTHING there). One
-    // write at spawn costs nothing and removes the class.
+    // Both rows written now: an instance attached after this frame's tick would otherwise draw
+    // its first frame on zero rows, the identity.
     let (slot, row) = (entry.slot, entry.delta(attached_at, 0.0, None));
     let affine = entry.affine(attached_at, 0.0, None);
     table.set(slot, row);
@@ -644,28 +470,9 @@ pub fn register_fx_uv(
     }
 }
 
-/// Put one **unit / GameObject / held-item** batch material on the UV lane (decision 2295) — the
-/// engine's whole door for the entity lane, and the twin of [`register_fx_uv`] for a population
-/// that is resident rather than pooled.
-///
-/// It picks the lane from the authored record rather than making the caller reason about it,
-/// which is the same argument [`UvLoops`] itself rests on:
-///
-/// - **`host` is `Some` and the slots disagree** ⇒ [`UvLoop::PerSeq`]. This material belongs to
-///   that one instance (the caller owns the clone), and the loop is whichever file-sequence slot
-///   the instance is playing — 1408's lane, reached from the entity side for the first time.
-///   `World\Lordaeron\Plagueland\PassiveDoodads\BloodOfHeroes` is the class: slot 0 holds its
-///   bubble sheets still while slot 1 sweeps them, at freq 16384/16383, so its placements bubble
-///   independently and one shared row cannot serve two of them.
-/// - **otherwise** ⇒ [`UvLoop::Shared`], the free-running scene clock on the batch's shared,
-///   deduped material — 0136 choice 1. Exactly faithful for a global-sequence loop (the
-///   reference clocks those on one per-scene ms cursor), and 0136's recorded, still-invisible
-///   divergence for a seamless band loop.
-///
-/// A period-0 translation is not a loop — its seed IS its forever value, so registering it would
-/// buy a per-frame re-write of the same number (1375) — but a batch that only rotates or scales
-/// still registers, because its motion is the affine row and its translation row is the zero it
-/// is meant to be.
+/// Put one unit, GameObject or held-item batch material on the UV lane: [`UvLoop::PerSeq`] on the
+/// caller's own clone when there is a `host` and the slots disagree, else [`UvLoop::Shared`] on
+/// the deduped material. A period-0 translation registers only if the batch rotates or scales.
 pub fn register_entity_uv(
     reg: &mut UvAnimMaterials,
     table: &mut crate::mat_anim_table::MatAnimTable,
@@ -692,10 +499,8 @@ pub fn register_entity_uv(
     );
 }
 
-/// The four baked channels of one batch's texture transform, as [`register_fx_uv`] takes them —
-/// 1408's two translation spellings plus 2019's per-slot rotation and scaling sets. A struct
-/// because they are one authored record, and a caller passing four `Option`s positionally is a
-/// caller that will eventually swap two of them.
+/// The four baked channels of one batch's texture transform: the translation as a per-slot set or
+/// one loop, and the per-slot rotation and scaling sets.
 #[derive(Default)]
 pub struct UvLoops {
     pub seqs: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 2]>>>,
@@ -705,10 +510,8 @@ pub struct UvLoops {
 }
 
 impl UvLoops {
-    /// The record as one authored batch carries it — **the one place the four channels are read
-    /// off a submesh**, so a lane that registers and a spawner that marks can never disagree about
-    /// which batches animate (decision 2038's law, whose violation froze every waterfall in the
-    /// game for three days).
+    /// The one place the four channels are read off a submesh, so the registration and the spawn
+    /// marker cannot disagree about which batches animate.
     pub fn of(sub: &benilla_assets::ModelSubmesh) -> Self {
         Self {
             seqs: sub.uv_seq.clone(),
@@ -718,19 +521,14 @@ impl UvLoops {
         }
     }
 
-    /// Does this batch animate its texture transform at all? The test the effect attach makes
-    /// before cloning a material: any of the four channels, because a scale-only transform
-    /// (`Spells\GroundingTotem_Impact.mdx`) and a dead-slot-0 translation (1408) each answer
-    /// `None` to the obvious one.
+    /// Whether any channel is present, the effect attach's test before cloning a material: a
+    /// scale-only transform or a dead slot 0 leaves `single` empty.
     pub fn any(&self) -> bool {
         self.seqs.is_some() || self.single.is_some() || self.rot.is_some() || self.scale.is_some()
     }
 
-    /// Does it need a per-frame SAMPLE — i.e. does it move? [`Self::any`] minus the constants: a
-    /// translation keyed to one value for the whole clip is its material's seed and nothing more
-    /// (1375), while a rotate-only or scale-only batch answers `None` on the translation channel
-    /// and still moves. The **one predicate** the entity lane's registration and its
-    /// [`AnimMatPart`] marker both ask.
+    /// Whether the batch moves: [`Self::any`] minus a period-0 translation, which is its seed. The
+    /// one predicate the entity lane's registration and its [`AnimMatPart`] marker share.
     pub fn animates(&self) -> bool {
         self.seqs.is_some()
             || self.rot.is_some()
@@ -738,8 +536,7 @@ impl UvLoops {
             || self.single.as_ref().is_some_and(|l| l.period > 0.0)
     }
 
-    /// The offset the batch opens on — what a caller seeds the clone's `sun_scale.zw` with so its
-    /// first frame is the loop's own `t = 0` and not the authored, unscrolled UV.
+    /// The offset the batch opens on, to seed a clone's `sun_scale.zw` at the loop's `t = 0`.
     pub fn open_offset(&self) -> [f32; 2] {
         self.seqs
             .as_ref()
@@ -749,38 +546,10 @@ impl UvLoops {
     }
 }
 
-/// Re-sample the **drawn** animated materials on the shared clock — the UV scroll
-/// ([`UvAnimMaterials`]) and the RGB tint ([`TintAnimMaterials`]) together, because they share the
-/// draw scan below. Skipped in captures (materials keep their t = 0 seed — constants still show,
-/// frames stay deterministic), **except the spell-effect lane**
-/// ([`UvAnimEntry::instance_lane`]), whose clock is an effect instance's own frame-stepped
-/// player: `fxview` exists to age an effect inside a capture, and no golden scenario spawns one,
-/// so a scene with no effect in it takes the identical early return it always did.
-///
-/// **The draw gate, and why it is the fix for B131.** Mutating a material asset marks it Modified,
-/// which on the Metal non-bindless path re-creates its uniform buffers *and its bind group* that
-/// frame. 0130 sized this as "a few uniform writes per frame" on the premise that the resident
-/// population is tiny (113 texanim models exist game-wide, a handful in view) — true per view,
-/// **false per map session**: the dedup caches hold every material they ever built until a
-/// `MapChange` (decision 0729), and a registry entry only evicts when its material dies, so on a
-/// single-map traverse both registries grow monotonically and every entry is re-uploaded every
-/// frame for ever. Measured on a parked same-map leg by square-waving this system:
-/// **+9.85 ms of CPU per frame at 174 resident entries (~57 µs each)** — and residency 4 → 248
-/// entries inside ten minutes, recoverable only by a restart or a map change. That is B131.
-///
-/// Gating on the draw is not a workaround for that growth, it is this lane finally obeying the
-/// module's own law: [`gate_doodad_anim`] already gates the *pose* on "any submesh actually drawn",
-/// on exactly the byte ground that makes it free — sampling is clock-indexed, so a material that
-/// re-appears is written from `now` and shows the value the shared clock dictates, with nothing to
-/// catch up (the module docs' "pausing costs nothing and drifts nothing"). A material nothing draws
-/// is a per-frame GPU rebuild with no pixel to show for it.
-///
-/// `Visibility != Hidden` is the same spelling [`gate_doodad_anim`] uses — the authority's verdict
-/// (far clip + size-bucketed fade + portal cull), written in `Update` by
-/// `debug_panel::ModelVisSet`, which this system is ordered after so the verdict is *this* frame's.
-/// It over-includes (a part left `Inherited` under a hidden ancestor counts as drawn), which is the
-/// safe direction: an extra write costs a frame's uniform upload, a missed one would freeze a
-/// visible scroll.
+/// Re-sample the drawn animated materials into the shared table, UV scroll and tint together:
+/// sampling is clock-indexed, so a re-appearing one has nothing to catch up. Drawn is
+/// `Visibility != Hidden` after `model_render::ModelVisSet`. Captures skip this, except the
+/// spell-effect lane ([`UvAnimEntry::instance_lane`]).
 pub(super) fn tick_anim_materials(
     time: Res<Time>,
     real: Res<Time<bevy::time::Real>>,
@@ -796,21 +565,13 @@ pub(super) fn tick_anim_materials(
         With<AnimMatPart>,
     >,
     twins: Res<crate::model_render::FarSideTwins>,
-    // The per-placement lane's sequence source (decision 1408): an entry registered `PerSeq` asks
-    // its own anim host which slot it is playing, instead of reading the shared clock.
     hosts: SeqHosts,
     mut drawn: Local<
         bevy::platform::collections::HashSet<AssetId<benilla_assets::materials::WowModelMaterial>>,
     >,
 ) {
     if uv_reg.0.is_empty() && tint_reg.0.is_empty() {
-        // **The tripwire for decision 2038's whole class.** [`AnimMatPart`] and the registration
-        // next to it share ONE predicate at the spawn site, so a world holding marked parts with
-        // an empty registry is never "a scene with no animated content" — it is this lane dead,
-        // which is exactly how every waterfall, canal and lava sheet in the game froze silently
-        // for three days. Free: the marker is archetype-filtered, so this is one iterator probe
-        // on a frame that was about to return anyway, and it says nothing in the ordinary empty
-        // case.
+        // Marked parts beside an empty registry mean this lane is dead, not that nothing animates.
         if parts.iter().next().is_some() {
             bevy::log::warn_once!(
                 "mat-anim: parts are marked animated but NOTHING is registered — the UV/tint lane is dead"
@@ -821,44 +582,28 @@ pub(super) fn tick_anim_materials(
     if matanim_off(&real) {
         return;
     }
-    // A deterministic run freezes the SHARED-clock lanes at their seed (the whole reason a golden
-    // frame is reproducible) but keeps the effect lane running, because that lane's clock is one
-    // instance's frame-stepped `AnimationPlayer` — the `fxview` carve-out `MatAnim` and
-    // `spell_fx::FxTintAnims` already take (decision 2282). A capture with no effect in it — every
-    // golden scenario — holds no such entry, so it returns here exactly as it always has.
+    // A capture freezes the shared-clock lanes at their seed but keeps the effect lane running.
     let frozen = crate::dev_state::deterministic_run() && !matanim_live();
     if frozen && !uv_reg.0.values().any(UvAnimEntry::instance_lane) {
         return;
     }
     drawn.clear();
-    // Skipped when frozen: the only entries still sampling there are the effect lane's, and they
-    // are exempt from the draw gate below — so a capture pays nothing for a scan it cannot read.
+    // Frozen, only the effect lane samples, and it skips the draw gate: no scan is needed.
     for (mat, vis) in parts.iter().filter(|_| !frozen) {
         if *vis != Visibility::Hidden {
             let id = mat.id();
-            // A far-classified instance carries the far TWIN's id — never a registry key. Count
-            // it as its near identity, or a batch whose every instance sits beyond the water
-            // plane marks its near entry not-drawn and freezes both variants' scroll (1375; the
-            // twin itself keeps getting written by `classify_water_side`'s Modified mirror).
+            // A far-classified part carries its far twin's id, never a registry key: count it as
+            // the near one, or a batch drawn only beyond the water plane would freeze.
             drawn.insert(twins.near_of(id).unwrap_or(id));
         }
     }
     let now = time.elapsed_secs();
-    // The samples land in the shared table as DELTAS from each entry's built seed (decision
-    // 1381) — the material asset is never touched, so there is no per-frame `Modified`, no
-    // bind-group rebuild, no `AssetChanged` walk, and no far-twin re-insert (the twin's clone
-    // carries the same slot and seed, so it scrolls in phase off the same row). Quantized
-    // because the input drifts continuously: 1/4096 of a texture repeat (1/255 for tint) is
-    // below what any face can show — and `MatAnimTable::set` skips same-value writes, so a slow
-    // loop uploads nothing most frames. Eviction is unchanged: an entry dies with its material,
-    // and its slot zeroes back to identity ([`crate::mat_anim_table`]'s free law).
+    // Rows are deltas from each entry's seed, so no material changes per frame and its far twin
+    // shares the row; quantized (1/4096, 1/255 for tint) so an unchanged row is not re-uploaded.
     let gseq_now = f64::from(now);
     uv_reg.0.retain(|id, entry| {
-        // **Alive means either half holds it** (decision 2038): a material still parked by
-        // `model_render::lazy` — built, handle reserved, nothing view-visible bound to it yet —
-        // is not in the store, and `Assets::contains` alone reads that as death. Evicting there
-        // would drop the entry a spawn just made and never rebuild it, because registration
-        // happens once, at spawn.
+        // Alive means either half holds it: a material parked by `model_render::lazy` is not in
+        // the store, and registration happens once, at spawn.
         if !crate::model_render::lazy::holds(&materials, *id) {
             table.free(entry.slot);
             if let Some(a) = &entry.affine {
@@ -866,19 +611,12 @@ pub(super) fn tick_anim_materials(
             }
             return false;
         }
-        // **The effect lane skips the draw gate.** That gate's argument is a material nothing
-        // draws costing a per-frame rebuild for ever, on a population that grows monotonically
-        // across a map session (B131). An effect instance is one of a handful and lives about a
-        // second, so there is nothing to ratchet — while making it obey the gate would mean
-        // threading [`AnimMatPart`] onto every fx part, card and decal, and a part that missed the
-        // marker would silently freeze mid-scroll. It is also what keeps the lane running inside a
-        // deterministic capture (`fxview`).
+        // The effect lane skips the draw gate: its parts carry no `AnimMatPart`, and an effect
+        // lives about a second, so an undrawn one costs little.
         let fx = entry.instance_lane();
         if (fx || drawn.contains(id)) && (!frozen || fx) {
             let playing = host_seq(&hosts, entry.host());
             table.set(entry.slot, entry.delta(now, gseq_now, playing));
-            // …and the rotation/scale row beside it, for the effect models that turn or scale
-            // their UVs rather than only sliding them (2282).
             if let Some((slot, row)) = entry.affine(now, gseq_now, playing) {
                 table.set(slot, row);
             }
@@ -900,22 +638,9 @@ pub(super) fn tick_anim_materials(
     });
 }
 
-/// **The price-this-system knob** (`WOW_MATANIM_DUTY=<start_s>:<period_s>`, decision 0785): alternate
-/// [`tick_anim_materials`] off/on every `period` seconds from `start`. Park at one pin, square-wave
-/// it, and the difference between the ON and OFF buckets **is** this system's per-frame cost, with
-/// residency, scene, entity count and camera all held identical — a measurement, not an argument.
-/// It is how B131's ratchet was priced (+9.85 ms/frame over 174 resident entries) and how the draw
-/// gate above was then shown to remove it (+0.22 ms). Kept, not deleted: the ~10 ms-floor ledger
-/// (0729's residuals) has more per-frame systems queued for exactly this treatment.
-///
-/// A **square wave** rather than one flip, because this machine's frame cost drifts on its own —
-/// a single before/after pair cannot tell the drift from the signal, and both legs of the verifying
-/// run climbed ~10 ms while their ON/OFF difference stayed flat.
-///
-/// **`Time<Real>`, deliberately:** virtual time is clamped to `max_delta` (250 ms), so on a leg that
-/// hitches it lags real time badly. That is what smeared the first attempt at this measurement into
-/// nonsense — the probe-chat schedule reads virtual time, so once the leg hitched its hops drifted
-/// 40 s → 75 s apart and windows labelled "parked, ticks off" in fact held a teleport and live ticks.
+/// `WOW_MATANIM_DUTY=<start_s>:<period_s>` turns [`tick_anim_materials`] off and on every `period`
+/// seconds from `start`; the ON/OFF difference over the square wave is its per-frame cost. On
+/// `Time<Real>` because virtual time clamps to `max_delta` (250 ms) and lags on a hitching run.
 fn matanim_off(time: &Time<bevy::time::Real>) -> bool {
     static SPEC: std::sync::OnceLock<Option<(f32, f32)>> = std::sync::OnceLock::new();
     let spec = SPEC.get_or_init(|| {
@@ -929,34 +654,16 @@ fn matanim_off(time: &Time<bevy::time::Real>) -> bool {
     })
 }
 
-/// **`WOW_MATANIM_LIVE=1` — run the shared lanes inside a deterministic capture too.**
-///
-/// The freeze above is what makes a golden frame reproducible, and it is right for every scenario
-/// in the sweep. It also means `fxview` — the fixture whose whole job is to age a subject — cannot
-/// show a **unit's or GameObject's** texture transform at all, because those are shared-clock
-/// entries (decision 2295); the effect lane is exempt only because its clock is one instance's
-/// frame-stepped player. Without this knob the A/B for "does this creature's skin scroll" does not
-/// exist, and the answer would have to come from the director's screen, which is not what §7 means
-/// by leaving the look to them.
-///
-/// Off by default, read once, and no golden scenario sets it — so the sweep is untouched.
+/// `WOW_MATANIM_LIVE=1` runs the shared lanes inside a deterministic capture too, so `fxview` can
+/// show a unit's or GameObject's texture transform. Off by default; no golden scenario sets it.
 fn matanim_live() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_MATANIM_LIVE").is_ok_and(|v| v != "0"))
 }
 
-/// The **tint-animated materials** registry — the M2Color-RGB twin of [`UvAnimMaterials`]: each
-/// batch material whose colour track animates (the vertex bake is skipped for those —
-/// `benilla-formats` `m2_batches`), keyed by material asset id. [`tick_anim_materials`]
-/// re-samples the tint into the material's `tint` uniform on the same shared clock, for the drawn
-/// (the same recorded seq-band phase divergence as the UV scroll — invisible for a placed
-/// doodad's ambient loop). Spell-effect instances need real per-instance phase instead (one cast
-/// = one 0.9 s pulse), so the effect lane clones its materials and ticks them on the instance
-/// clock (`entities::spell_fx`), never through this registry.
-/// [`UvLoop`]'s RGB twin, on the same rule and for the same reason — `uvslotscan` finds the tint
-/// channel pinned to slot 0 by the same line, and `Spells\\Deterrence_State_Base.m2` tinting
-/// **red→blue in Stand and green→red in Hold**, where the pin renders a *wrong colour* rather than
-/// a frozen one.
+/// Which loop a registered tint material (an animated M2 colour track) animates on, [`UvLoop`]'s
+/// RGB twin: `Shared`, with the same phase deviation as [`UvLoop::Shared`], or `PerSeq` on one
+/// placement's slot. Spell-effect instances tick their own tint clones and never register here.
 pub enum TintLoop {
     Shared(std::sync::Arc<benilla_formats::RgbAnim>),
     PerSeq {
@@ -965,7 +672,7 @@ pub enum TintLoop {
     },
 }
 
-/// One registered tint material — [`UvAnimEntry`]'s RGB twin (seed = the built `tint.xyz`).
+/// One registered tint material, seeded from the built `tint.xyz`.
 pub struct TintAnimEntry {
     pub anim: TintLoop,
     pub slot: u16,
@@ -973,9 +680,8 @@ pub struct TintAnimEntry {
 }
 
 impl TintAnimEntry {
-    /// [`UvAnimEntry::delta`]'s RGB twin (1/255 quantization, the display's own step). The
-    /// per-placement lane's identity is WHITE — the tint is a multiplier, so an unresolvable host
-    /// must leave the batch at its built seed, not black it out.
+    /// The tint's delta row, quantized at the display's 1/255 step. An unresolved host reads white,
+    /// the multiplier's identity, so the batch is untinted rather than black.
     pub(crate) fn delta(&self, now: f32, gseq_now: f64, playing: Option<(usize, f32)>) -> [f32; 4] {
         let rgb = match &self.anim {
             TintLoop::Shared(anim) => anim.sample(now),
@@ -1004,7 +710,7 @@ pub struct TintAnimMaterials(
     >,
 );
 
-/// [`register_uv`]'s tint twin: slot into `anim_slots.y`, seed from the built `tint.xyz`.
+/// Register a tint material: its slot goes in `anim_slots.y`, its seed is the built `tint.xyz`.
 pub fn register_tint(
     reg: &mut TintAnimMaterials,
     table: &mut crate::mat_anim_table::MatAnimTable,
@@ -1019,7 +725,7 @@ pub fn register_tint(
         bevy::log::warn_once!("mat-anim table full — a tint batch stays at its seed");
         return;
     };
-    // The parked half, exactly as [`register_uv`] reaches it (decision 2038).
+    // Through the parked half, as in `register_uv`.
     let Some(seed) = crate::model_render::lazy::with_material_mut(materials, id, |mat| {
         let seed = [
             mat.extension.tint.x,
@@ -1036,35 +742,11 @@ pub fn register_tint(
     reg.0.insert(id, TintAnimEntry { anim, slot, seed });
 }
 
-/// **The animated-material probe** (`WOW_MATANIM_PROBE=<secs>`): once, `secs` after boot, print
-/// one line per live [`AnimMatPart`] — the parts whose material can be a [`UvAnimMaterials`] /
-/// [`TintAnimMaterials`] key — with everything that decides whether it actually moves on screen:
-///
-/// ```text
-/// matanim  <model>#<uid>  mat <asset id>[ FAR][ PARKED]  anim_slots (1, 0, 0)  vis Inherited drawn 1
-///   uv slot 1 seed (+0.0000,+0.0000) row (+0.0000,-0.2122) live (+0.0000,-0.2122)
-///   shared period 9.967s loop (+0.0000,+0.0000) (+0.0000,-0.2542) (+0.0000,-0.5083) (+0.0000,-0.7542)
-/// ```
-/// (one line per part; wrapped here)
-///
-/// Four questions, one line each, because a frozen scroll can fail at any of them and the pixels
-/// say the same thing every time: is the batch **registered** at all (a missing line is a batch
-/// whose loop never reached the registry — an exhausted table, a period-0 constant, a lane that
-/// forgot to register); does its **loop** actually move (the four quarter-phase samples — a
-/// flat row here is an asset that scrolls nowhere, not a renderer fault); is the **table row**
-/// live (the value the shader will read — flat while the loop moves means the tick's draw gate
-/// never picked this material up, which is 1375's failure mode); and is the part **drawn** (the
-/// gate's own input).
-///
-/// It samples the loop itself rather than watching the row over time, so it is a **one-shot that
-/// works in a deterministic capture** — where [`tick_anim_materials`]'s shared lanes are skipped
-/// and their rows stay zero by design (the effect lane keeps running there; decision 2282). In a
-/// live run the `row` column is the tick's real output and the two halves can be compared
-/// directly.
-///
-/// A trailing block of `(unmarked)` rows names every registry entry no [`AnimMatPart`] accounts
-/// for: the spell-effect lane, which is off the draw gate and therefore off the marker, plus any
-/// entry whose part has gone — the readout that says a registered clone exists at all.
+/// `WOW_MATANIM_PROBE=<secs>`: once, `secs` after boot, log one line per [`AnimMatPart`] with what
+/// decides whether it moves on screen: registered or not, its loop's four quarter-phase samples,
+/// its live table row, and its draw verdict. It samples the loop itself, so it works in a
+/// deterministic capture. A trailing `(unmarked)` block lists the registry entries no marked part
+/// accounts for: the spell-effect lane, and any leak.
 pub(super) fn matanim_probe(
     time: Res<Time>,
     uv_reg: Res<UvAnimMaterials>,
@@ -1077,9 +759,7 @@ pub(super) fn matanim_probe(
     mut fired: Local<bool>,
 ) {
     let Some(at) = probe_at() else { return };
-    // Not latched while the world is still empty: a capture holds the game clock at 0 while the
-    // scene builds, so "elapsed >= at" alone would fire the probe on frame one, before a single
-    // doodad had spawned, and report nothing.
+    // Not while the world is empty: a capture holds the clock at 0 while the scene builds.
     if *fired
         || time.elapsed_secs() < at
         || (parts.iter().next().is_none() && uv_reg.0.is_empty() && tint_reg.0.is_empty())
@@ -1090,23 +770,17 @@ pub(super) fn matanim_probe(
     let now = time.elapsed_secs();
     let gseq_now = f64::from(now);
     let mut rows: Vec<String> = Vec::new();
-    // One UV entry as a row — hoisted out of the part loop so the unvisited pass below prints
-    // exactly the same columns for an entry NO marked part accounts for.
     let uv_row = |e: &UvAnimEntry| {
         let playing = host_seq(&hosts, e.host());
-        // The per-placement lane has one loop per sequence, so its phase sweep is meaningless
-        // without a play head — it prints the head instead, and samples on the shared clock.
+        // A per-placement entry has a loop per slot, so it prints its play head, not a period.
         let (lane, period) = match &e.anim {
             UvLoop::Shared(a) => {
-                // `None` = a rotate-/scale-only transform: the translation row is real and stays
-                // at zero, and the period the sweep needs is the AFFINE channel's, not this one's.
+                // `None`: a rotate- or scale-only transform, whose translation row stays at zero.
                 let p = a.as_ref().map_or(0.0, |a| a.period);
                 (format!("shared period {p:.3}s"), p)
             }
             UvLoop::PerSeq { .. } => (format!("per-seq playing {playing:?}"), 0.0),
-            // The effect lane HAS a resolved loop (the clip it opened on), so unlike the
-            // per-placement lane its sweep is meaningful — read across the instance's own
-            // clip, from attach, beside the age that says where in it this frame sits.
+            // The effect lane has a resolved loop, so it sweeps its own clip from attach.
             UvLoop::Instance { attached_at, .. } => (
                 format!(
                     "per-instance age {:.3}s playing {playing:?}",
@@ -1115,11 +789,8 @@ pub(super) fn matanim_probe(
                 e.resolved(playing).map_or(0.0, |l| l.period),
             ),
         };
-        // Four quarter-phase samples of the loop itself: a flat set is an asset that scrolls
-        // nowhere, whatever the row says. The phase has to move the clock the entry actually
-        // reads — for the shared lane that is `now`, for a hosted one the PLAY HEAD, which is why
-        // the sweep substitutes the phase into `playing` rather than only into `now` (an entry
-        // whose host supplies a band clock ignores `now` entirely, and the sweep read flat).
+        // Four quarter-phase samples of the loop. The phase moves the clock the entry reads:
+        // `now` on the shared lane, the play head on a hosted one, which ignores `now`.
         let phases: Vec<String> = (0u8..4)
             .map(|i| {
                 let t = period * f32::from(i) / 4.0;
@@ -1129,8 +800,6 @@ pub(super) fn matanim_probe(
             })
             .collect();
         let live = e.delta(now, gseq_now, playing);
-        // The affine half, when the transform has one: `[cos − 1, sin, sx − 1, sy − 1]`, so all
-        // zeros IS the identity and a flat row there says the turn/scale never reached the shader.
         let affine = e.affine(now, gseq_now, playing).map_or(String::new(), |(slot, want)| {
             let row = table.row(slot);
             format!(
@@ -1154,14 +823,11 @@ pub(super) fn matanim_probe(
         AssetId<benilla_assets::materials::WowModelMaterial>,
     > = std::collections::HashSet::new();
     for (mat, vis, vv, obj) in &parts {
-        // A far-classified part carries the TWIN's id; the registry is always keyed by the near
-        // one — the same fold `tick_anim_materials`' draw scan makes (1375).
+        // A far part carries its twin's id; the registry is keyed by the near one.
         let far = twins.near_of(mat.id());
         let id = far.unwrap_or(mat.id());
         let label = obj.map_or_else(|| "-".to_string(), |o| format!("{}#{}", o.label, o.id));
-        // Through the parked half (`lazy::with_material`), or the readout would report every
-        // not-yet-drawn material's stamp as a zero it never had — the deferral confusion this
-        // probe exists to resolve (decision 2038). `parked` says which half answered.
+        // Through the parked half, or an undrawn material's slots read zero; `parked` says which.
         let parked = !materials.contains(id);
         let slots =
             crate::model_render::lazy::with_material(&materials, id, |m| m.extension.anim_slots)
@@ -1191,11 +857,7 @@ pub(super) fn matanim_probe(
             u8::from(vv.is_some_and(|v| v.get())),
         ));
     }
-    // **The entries no marked part accounts for.** The spell-effect lane is exactly this
-    // population by design — its parts carry no [`AnimMatPart`] because they skip the draw gate
-    // (`tick_anim_materials`) — and so is every genuine leak: a registered material whose part is
-    // gone, or whose marker was never inserted. Without this pass the probe could not see the
-    // claw trail at all, which is the one thing decision 2282 built it to read.
+    // Entries no marked part accounts for: the effect lane, which carries no marker, and any leak.
     for (id, e) in &uv_reg.0 {
         if visited.contains(id) {
             continue;
@@ -1214,10 +876,8 @@ pub(super) fn matanim_probe(
     }
 }
 
-/// One animated part as [`matanim_probe`] reads it: the material it is bound to (the far twin's
-/// id while it is far-classified), the two halves of the draw verdict the tick's gate turns on,
-/// and the placement that names it. A tuple alias because the inline form trips the workspace
-/// gate's `type_complexity`, the same shape `debug_panel::inspect`'s readouts take.
+/// One animated part as [`matanim_probe`] reads it: its material, both halves of its draw
+/// verdict, and the placement that names it.
 type ProbeReadout = (
     &'static MeshMaterial3d<benilla_assets::materials::WowModelMaterial>,
     &'static Visibility,
@@ -1225,8 +885,7 @@ type ProbeReadout = (
     Option<&'static crate::interact::WorldObject>,
 );
 
-/// `WOW_MATANIM_PROBE` — unset is off; bare (or unparseable) fires at 20 s. Read once
-/// ([`matanim_off`]'s pattern): the system runs every frame to check its own latch.
+/// `WOW_MATANIM_PROBE`, read once: unset is off, bare or unparseable fires at 20 s.
 fn probe_at() -> Option<f32> {
     static AT: std::sync::OnceLock<Option<f32>> = std::sync::OnceLock::new();
     *AT.get_or_init(|| {
@@ -1239,7 +898,6 @@ fn probe_at() -> Option<f32> {
 mod delta_tests {
     use super::*;
 
-    /// An effect-lane entry over one shared translation loop, attached at `attached_at`.
     fn fx_entry(attached_at: f32) -> UvAnimEntry {
         UvAnimEntry {
             anim: UvLoop::Instance {
@@ -1254,8 +912,7 @@ mod delta_tests {
         }
     }
 
-    /// A rotation-only loop, as `G_ScryingBowl`'s water and `G_ScourgeRuneCircleCrystal`'s rune
-    /// ring author one: a quarter turn about Z over two seconds, keyed in file slot 0 only.
+    /// A rotation-only loop: a quarter turn about Z over two seconds, in file slot 0 only.
     fn quarter_turn() -> std::sync::Arc<benilla_formats::SeqLoops<[f32; 4]>> {
         const Q: f32 = std::f32::consts::FRAC_1_SQRT_2;
         const QUARTER: [f32; 4] = [0.0, 0.0, Q, Q];
@@ -1272,10 +929,7 @@ mod delta_tests {
         )
     }
 
-    /// **`animates()` is the one predicate, and it is not `uv_anim.is_some()`** (decision 2295).
-    /// Two entity batches in the shipped corpus rotate and never translate, so the channel a
-    /// reader would check first answers `None` for them; and a translation keyed to one constant
-    /// value is the material's seed, not a loop to sample (1375).
+    /// `animates()` is not `uv_anim.is_some()`: a rotate-only batch moves, a constant does not.
     #[test]
     fn the_animates_predicate_sees_a_rotation_only_batch() {
         let rot_only = UvLoops {
@@ -1303,10 +957,6 @@ mod delta_tests {
         assert!(!UvLoops::default().animates());
     }
 
-    /// **The affine half runs on whichever clock its own lane runs on** (decision 2295 widening
-    /// 2282's). A shared entity entry has no host and no attach time, so its rotation reads the
-    /// free-running scene clock — which is what makes a rune ring on a shared, deduped material
-    /// turn at all.
     #[test]
     fn a_shared_entry_turns_on_the_scene_clock() {
         let e = UvAnimEntry {
@@ -1319,17 +969,12 @@ mod delta_tests {
                 slot: 5,
             }),
         };
-        // No translation channel at all: the row it still owns stays at the zero it means.
+        // No translation channel: its row stays at zero.
         assert_eq!(e.delta(1.0, 1.0, None), [0.0, 0.0, 0.0, 0.0]);
-        // Half-way through the turn, and the row is `[cos − 1, sin, sx − 1, sy − 1]` of the
-        // **raw, unnormalised** lerped quaternion — which is the reference's own arithmetic, not
-        // an oversight: `0x713ea0` lerps each component and `0x7bddb0` consumes the result as is,
-        // so between two keys `|q| < 1` and the 2×2 is a rotation with a slight shrink (wow-re
-        // `modelframe-texanim-and-sequence-law.md` §3.4: *"a re-implementation that slerps, or
-        // normalises before building the matrix, diverges from the reference between keys"*).
-        // Here `q = (0, 0, 0.35355, 0.85355)`, so `c = 1 − 2z² = 0.75` and `s = 2zw = 0.60355` —
-        // NOT the 0.7071/0.7071 a normalised 45° would give. Asserted exactly so a future
-        // "obvious fix" to normalise fails here.
+        // Half-way through the turn the row comes from the raw, unnormalised lerp, as in the
+        // reference (`0x713ea0` lerps each component, `0x7bddb0` uses the result as is):
+        // `q = (0, 0, 0.35355, 0.85355)`, so `c = 1 − 2z² = 0.75` and `s = 2zw = 0.60355`, not the
+        // 0.7071 of a normalised 45°. Normalising fails here.
         let (slot, row) = e.affine(1.0, 1.0, None).expect("the affine row");
         assert_eq!(slot, 5);
         assert!(
@@ -1340,7 +985,6 @@ mod delta_tests {
             row[2].abs() < 1e-6 && row[3].abs() < 1e-6,
             "no scaling authored, so the scale half is the identity: {row:?}"
         );
-        // …and the clock really is `now`: a different scene time gives a different angle.
         let later = e.affine(1.5, 1.5, None).expect("the affine row").1;
         assert!(
             (later[1] - row[1]).abs() > 1e-2,
@@ -1348,10 +992,6 @@ mod delta_tests {
         );
     }
 
-    /// **The effect lane reads its INSTANCE's play head, not the scene clock** (decision 2282).
-    /// The band clock is the clip time the host's `AnimationPlayer` reports, so two casts a minute
-    /// apart are at the same point of their own scroll — the property a shared-material lane
-    /// structurally cannot have, and the one Swipe's one-shot reveal rests on.
     #[test]
     fn the_effect_lane_reads_its_own_play_head() {
         let anim = uv_loop();
@@ -1366,9 +1006,6 @@ mod delta_tests {
         }
     }
 
-    /// With no player to ask — the frame before an effect's rig arms, or a model that never arms
-    /// one — the band clock degrades to the instance's own AGE, which is `MatAnim`'s degrade next
-    /// door and not the free-running scene clock a shared entry would read.
     #[test]
     fn a_player_less_effect_falls_back_to_its_age() {
         let anim = uv_loop();
@@ -1380,9 +1017,6 @@ mod delta_tests {
         );
     }
 
-    /// The **affine** half (2019's encoding, zero = identity): sampled on the same clocks as the
-    /// translation beside it, and absent — never a zeroed row — when the transform only slides.
-    /// `Spells\GroundingTotem_Impact.m2` is the scale-only case this stands for.
     #[test]
     fn the_effect_lane_samples_rotation_and_scale_on_the_same_clock() {
         let mut e = fx_entry(100.0);
@@ -1408,8 +1042,7 @@ mod delta_tests {
             .affine(100.0, 0.0, Some((0, 1.0)))
             .expect("the affine row");
         assert_eq!(slot, 12);
-        // Half-way: scale 0.625, encoded as `sx − 1`; rotation untouched, so `cos − 1` and `sin`
-        // are the identity's zeros.
+        // Half-way: scale 0.625, encoded `sx − 1`; no rotation, so `cos − 1` and `sin` are zero.
         assert!(
             row[0].abs() < 1e-6 && row[1].abs() < 1e-6,
             "no rotation authored: {row:?}"
@@ -1430,9 +1063,6 @@ mod delta_tests {
         })
     }
 
-    /// The delta law (decision 1381): a row is the quantized live sample minus the BUILT seed,
-    /// so the shader's `seed + row` shows exactly the number the old asset-mutating lane wrote.
-    /// At t = 0 that is the quantized seed — the same value the old tick's first frame produced.
     #[test]
     fn the_delta_reproduces_the_old_absolute_write() {
         let anim = uv_loop();
@@ -1465,13 +1095,7 @@ mod delta_tests {
         }
     }
 
-    /// **B98** (decision 1408): the per-placement lane samples the slot the placement's own host is
-    /// playing — not slot 0, and not a shared clock.
-    ///
-    /// The BRM lava bubble's shape, exactly: slot 0 bakes to nothing (a dead hold) and slot 1
-    /// carries the flipbook. Reading slot 0, as the shared registry must, is the frozen sprite the
-    /// report named; reading the host's live slot is the fix. The unresolved case — a host
-    /// despawned mid-frame — must land on the UV identity, i.e. the built seed, never a jump.
+    /// A lava bubble's shape: slot 0 bakes nothing and slot 1 the flipbook.
     #[test]
     fn the_per_placement_lane_reads_its_hosts_sequence() {
         let seqs = std::sync::Arc::new(
@@ -1502,13 +1126,12 @@ mod delta_tests {
             (d[1] - 0.605).abs() < 1e-3,
             "the flipbook's V offset: {d:?}"
         );
-        // On slot 0 there is no loop at all — the identity, i.e. the built seed.
+        // Slot 0 has no loop: the zero offset, here the built seed.
         assert_eq!(entry.delta(0.0, 0.0, Some((0, 3.0))), [0.0; 4]);
-        // …and an unresolvable host degrades to the same identity, never to a shared-clock sample.
+        // An unresolvable host degrades to the same identity, never a shared-clock sample.
         assert_eq!(entry.delta(99.0, 99.0, None), [0.0; 4]);
     }
 
-    /// The tint twin, same law at the display's 1/255 step.
     #[test]
     fn the_tint_delta_reproduces_the_old_absolute_write() {
         let anim = std::sync::Arc::new(benilla_formats::RgbAnim {
diff --git a/crates/benilla-world/src/doodad_anim/mod.rs b/crates/benilla-world/src/doodad_anim/mod.rs
index c4bb20d4..46167f48 100644
--- a/crates/benilla-world/src/doodad_anim/mod.rs
+++ b/crates/benilla-world/src/doodad_anim/mod.rs
@@ -1,30 +1,11 @@
-//! The doodad animation host (decision 0130, phase 1) — world-placed M2 doodads (ADT MDDF + WMO MODD
-//! props) animate: flags wave, windmills turn, flame bones jiggle.
+//! The doodad animation host: placed M2 doodads (ADT MDDF and WMO MODD props) animate.
 //!
-//! Byte ground (wow-5875-re `system/animation/scratch/doodad-anim-host.md`, VERIFIED): a doodad's M2
-//! instance is armed at load — bone 0, animation id 0, `linkFlag=1` — and then **re-arms itself every
-//! play-window, for ever**, rolling a fresh frequency-weighted variation each time (§5, decision
-//! 0768: the watchdog `0x719370` fires on `now ≥ windowHi`, enqueues the doodad-only completion
-//! callback `0x6951b0` that `0x695100` installed at `[model+0x70]`, and that callback re-runs op4
-//! with `variationIdx = -1`, which writes the next `windowHi` and clears the latch — self-sustaining).
-//! **Global sequences loop with zero arming**, clock-driven. The cycle is gated on **linkage** — the
-//! per-frame walk `0x7074b0` only advances models spliced into the scene list, which the doodad drain
-//! `0x683f80` does per **in-range** doodad — not on the draw, so a doodad behind the camera keeps
-//! cycling. Because sampling is clock-indexed (`cursor = clock − startOffset`), a re-appearing model
-//! shows the pose the shared clock dictates — pausing costs nothing and drifts nothing.
-//!
-//! benilla's translation: the spawn site ([`crate::terrain_stream`]) classifies each placed model by
-//! [`classify`] — the ~90% with no animated channel stay on today's static path (measured,
-//! `benilla-extract doodadscan`) — and an animated one spawns the skinned twin + a collapsed
-//! [`RigPose`] buffer (decision 1365 — no joint entities; consumers ride on-demand anchors) on an
-//! anim-root entity carrying [`DoodadAnimHost`]: an `AnimationPlayer` on the armed clip,
-//! re-rolled every window by [`reroll_doodad_variation`], and/or a [`GlobalSeqDrive`] for the
-//! free-running channels. [`gate_doodad_anim`] here is the draw-time tick made explicit: animation
-//! runs iff any of the doodad's submeshes is actually drawn (the `Visibility` verdict the debug-panel
-//! authority composes from far-clip + the size-bucketed distance fade + the WMO portal cull), and a
-//! resume seeks to `(now − armed_at) mod duration` — the ref's shared-clock phase, measured from the
-//! current arm. Note the two gates are deliberately different: the *draw* gates the pose, the
-//! *linkage* (here: residency) gates the variation cycle.
+//! The reference arms a doodad at load (bone 0, animation id 0, `linkFlag=1`) and re-arms it every
+//! play-window with a fresh weighted variation: the watchdog `0x719370` fires on `now ≥ windowHi`
+//! and runs the callback `0x6951b0` that `0x695100` installed at `[model+0x70]`, which re-arms
+//! with `variationIdx = -1`. Global sequences loop with no arming. The walk `0x7074b0` advances
+//! only the models the doodad drain `0x683f80` links each frame from the drawn and faded set, and
+//! sampling is clock-indexed (`cursor = clock − startOffset`), so pausing drifts nothing.
 
 use bevy::animation::graph::AnimationNodeIndex;
 use bevy::app::AnimationSystems;
@@ -46,46 +27,27 @@ pub use mat_anim::{
 };
 pub(crate) use mat_anim::{register_uv, UvLoop};
 
-/// What a placed doodad model animates — decision 0130's content gate, decided per model at spawn.
+/// What a placed doodad model animates, decided per model at spawn.
 pub enum DoodadAnimTier<'a> {
-    /// No animated bone channel: today's static path, untouched (no joints, no player — the ~90%
-    /// measured case: trees, fences, barrels, rocks).
+    /// No animated bone channel: the static path (most doodads: trees, fences, rocks).
     Static,
-    /// Only free-running global-sequence channels (candelabra glow pulses): joints +
-    /// [`GlobalSeqDrive`], **no** `AnimationPlayer` — the cheapest animated tier.
+    /// Only global-sequence channels (a candelabra's glow): a [`GlobalSeqDrive`], no player.
     GlobalSeqOnly,
-    /// The **loader-idle seed** moves bones (flags, windmills, torch flames): joints + an
-    /// `AnimationPlayer` looping this clip — the client's one-time load arm. That seed is animation
-    /// id 0 (Stand) resolved through the model's own `playableAnimationLookup`, NOT the file-order
-    /// first sequence (decision 0637; the variant name predates the correction and is kept because
-    /// it is the tier's identity, not a claim about which sequence). Global-sequence channels ride
-    /// along if the model also has them.
+    /// The loader-idle seed moves bones (flags, windmills, torch flames): an `AnimationPlayer`
+    /// looping this clip. The seed is animation id 0 resolved through the model's
+    /// `playableAnimationLookup`, not the file-order first sequence the name suggests.
     FirstSeq(&'a AnimClip),
 }
 
-/// The animation-event tags that make a placed doodad SOUND: `$DSL` (the looping emitter), `$DSO`
-/// (a positioned one-shot), `$DSE` (the stop token that releases a `$DSL` — `data` is 0 on all 16
-/// shipped models) and the generic `$SND`. Routed by `benilla_app::sound::anim_events`; listed here
-/// because their presence is what earns a bind-posed model a clock it would otherwise be denied
-/// (see [`arms_for_sound`]). Byte law: wow-re `sound/scratch/doodad-sound-emitters.md`.
+/// The animation-event tags that make a placed doodad sound: `$DSL` (a looping emitter), `$DSO` (a
+/// positioned one-shot), `$DSE` (the stop that releases a `$DSL`) and `$SND`, the markers the
+/// reference's doodad event callback `0x6951e0` routes on.
 pub(crate) const SOUND_EVENT_TAGS: [&[u8; 4]; 4] = [b"$DSL", b"$DSO", b"$DSE", b"$SND"];
 
-/// Does this model's **arm chain** — the loader-idle seed and its variations, the only sequences a
-/// placed doodad ever plays — carry a sound-event marker?
-///
-/// This is deliberately NOT part of [`classify`]: the tier answers "what does this model *render*",
-/// and 0130's whole point is that a bind-posed sequence renders as the static mesh. That stays true.
-/// What it never meant is that the sequence does not *run* — the reference arms every placed doodad
-/// it creates (`0x695100` → `0x7121a0`, module docs §1/§4a) and cycles it whenever the doodad is in
-/// the frame's animate set, and the event track rides that clock. A humming
-/// lamp is the proof: `KalidarStreetLamp01.m2` is one looping 3.333 s Stand that keys no bone at all
-/// and carries exactly one event, `$DSL` → `NightElfStreetLampLoop`. Gating its clock on the *rig*
-/// is what made every world doodad silent (bug B345), and the corpus says the class is not marginal
-/// — `benilla-extract soundeventscan`: 273 carrier models, 108 of which no rig gate would ever arm.
-///
-/// Same shape as [`ModelAnimations::idle_clip`]'s own note about emitters and material loops: arming
-/// the idle seed is what gives a consumer a running clock instead of a frozen slot-0 read. Sound is
-/// simply the third consumer.
+/// Whether the model's arm chain (the loader-idle seed and its variations, the only sequences a
+/// placed doodad plays) carries a sound-event marker. Kept out of [`classify`], which answers what
+/// the model renders: the reference arms every placed doodad (`0x695100` → `0x7121a0`), and its
+/// event track runs on that clock even when no bone moves (`KalidarStreetLamp01.m2`'s `$DSL`).
 pub(crate) fn arms_for_sound(anims: &ModelAnimations) -> bool {
     let Some(idle) = anims.idle_clip() else {
         return false;
@@ -101,8 +63,7 @@ pub(crate) fn arms_for_sound(anims: &ModelAnimations) -> bool {
         })
 }
 
-/// Classify a placed model for the spawn site. Boneless models are `Static` regardless of parsed
-/// tracks — their skinned twin carries joint attributes with no joints to index (the 0035 guard).
+/// Classify a placed model; a boneless one is `Static`, with no joints for a skin to index.
 pub fn classify<'a>(
     skeleton: &ModelSkeleton,
     animations: Option<&'a ModelAnimations>,
@@ -113,9 +74,8 @@ pub fn classify<'a>(
     if skeleton.joints.is_empty() {
         return DoodadAnimTier::Static;
     }
-    // `first_seq` — 0130's content gate, and only that (decision 0936's split; the loader arm's
-    // *identity* answer is `idle_seq`/`idle_clip`, which the entity lane arms from). It stays the
-    // rig question here: a seed that holds bind pose renders identically to the static mesh.
+    // `first_seq` is the content gate, not the arm's identity (`idle_seq`): a seed that holds bind
+    // pose renders identically to the static mesh.
     match anims.first_seq.and_then(|i| anims.clips.get(i)) {
         Some(clip) => DoodadAnimTier::FirstSeq(clip),
         None if !anims.global_bones.is_empty() => DoodadAnimTier::GlobalSeqOnly,
@@ -123,55 +83,36 @@ pub fn classify<'a>(
     }
 }
 
-/// What [`spawn_anim_host`] set up for one animated placement — the spawn site arms the
-/// [`DoodadAnimHost`] on `root` with the submesh list once it has spawned them.
-///
-/// Since decision 1365 there are NO joint entities: the pose lives in a [`RigPose`] buffer,
-/// carried here BY VALUE so the caller can mint consumer anchors ([`Self::anchor`]) for the bones
-/// something actually rides — billboard cards, emitters, ribbons — and then attach the buffer
-/// with [`Self::finish`]. Only consumed bones ever get an entity (the 1354 census: 96 % of the
-/// old eagerly-spawned population hosted nothing).
+/// What [`spawn_anim_host`] set up for one placement; the [`RigPose`] rides here by value until
+/// [`Self::finish`], so anchors ([`Self::anchor`]) are minted only for bones something rides.
 pub struct AnimHostSpawn {
     pub root: Entity,
-    /// The collapsed rig's pose buffer, not yet inserted — [`Self::finish`] attaches it to
-    /// `root` once every consumer anchor is minted.
+    /// The pose buffer, inserted on `root` by [`Self::finish`] once every anchor is minted.
     pose: RigPose,
     pub inverse_bindposes: Handle<SkinnedMeshInverseBindposes>,
-    /// The looping first-sequence node + duration, `None` on the gseq-only tier.
+    /// The armed clip's node and duration, `None` on the gseq-only tier.
     pub(crate) clip: Option<(AnimationNodeIndex, f32)>,
-    /// The **file sequence slot** the load arm seeded ([`AnimClip::seq_index`]) — the axis every
-    /// per-sequence bake is keyed on. `None` on the gseq-only tier (no arm).
-    ///
-    /// This is the *loader's* var-0 seed only. It is no longer what the placement ends up playing:
-    /// [`reroll_doodad_variation`] overrides it on the first frame with a real weighted roll and
-    /// keeps re-rolling every play-window (decision 0768), exactly as the reference's holder setup
-    /// `0x695100` lands its `variationIdx = -1` arm after the loader's var-0 one. Consumers that
-    /// must track the *current* slot therefore read the host's live player instead — the emitters
-    /// ride [`crate::particles::EmitClock::Host`].
+    /// The file sequence slot the load arm seeded ([`AnimClip::seq_index`]); the first re-roll
+    /// replaces it, as the holder's `0x695100` arm does, so the current slot is read off the host's
+    /// player ([`crate::particles::EmitClock::Host`]). `None` on the gseq-only tier.
     pub(crate) seq: Option<usize>,
-    /// The animation id the arm rolls its variation over (id 0 — the loader-idle seed's id, resolved
-    /// through the model's own `playableAnimationLookup`). `None` on the gseq-only tier: nothing was
-    /// armed, so there is no play-window and nothing to re-roll.
+    /// The animation id the arm rolls variations over; `None` on the gseq-only tier.
     pub(crate) anim_id: Option<u16>,
 }
 
 impl AnimHostSpawn {
-    /// The anchor entity standing in for `bone` — spawned on first demand, shared on repeat asks
-    /// ([`RigPose::anchor_for`]). `None` = the bone is outside this skeleton (the consumer
-    /// misses, exactly as `joints.get(bone)` used to).
+    /// The anchor entity for `bone`, spawned on first demand and shared after
+    /// ([`RigPose::anchor_for`]); `None` for a bone outside the skeleton.
     pub fn anchor(&mut self, commands: &mut Commands, bone: u16) -> Option<Entity> {
         self.pose.anchor_for(commands, self.root, bone)
     }
 
-    /// The skeleton's bone count — what a palette allocation sizes itself with now that there is
-    /// no joint list to measure.
+    /// The skeleton's bone count, the palette allocation size.
     pub fn bones(&self) -> u32 {
         self.pose.locals.len() as u32
     }
 
-    /// Attach the pose buffer to the host root. Called once, after the caller minted its
-    /// anchors; returns the `(bone, anchor)` registry for consumers that resolve after this
-    /// point (the placement's emitter/ribbon spawns).
+    /// Attach the pose buffer once the anchors are minted; returns the `(bone, anchor)` registry.
     pub fn finish(self, commands: &mut Commands) -> Vec<(u16, Entity)> {
         let anchors = self.pose.anchors.clone();
         commands.entity(self.root).insert(self.pose);
@@ -179,10 +120,8 @@ impl AnimHostSpawn {
     }
 }
 
-/// Whether [`spawn_anim_host`] would rig this model — the model-forms requester's twin of the
-/// spawn gate (decision 0834), so the skinned twins are built exactly for the placed models that
-/// will draw them. Mirrors both of the host's gates: the tier, and the capture freeze (captures
-/// keep every doodad static, so they need no twins either).
+/// Whether [`spawn_anim_host`] would rig this model, by the same tier and capture gates, so skinned
+/// twins are built only for placed models that draw them.
 pub fn wants_rig(m: &M2Model) -> bool {
     !crate::dev_state::deterministic_run()
         && !matches!(
@@ -191,34 +130,22 @@ pub fn wants_rig(m: &M2Model) -> bool {
         )
 }
 
-/// Spawn the animation host for one placed M2, if [`classify`] says it animates: an anim-root entity
-/// at the placement transform carrying the collapsed [`RigPose`] buffer (decision 1365 — no joint
-/// entities; consumer anchors are minted on demand and cascade with the root),
-/// and — per tier — an `AnimationPlayer` looping the **loader-idle seed's** clip (the client's
-/// one-time load arm at `0x70ebd0`: `0x7121a0(bone 0, animation id 0 resolved through the model's
-/// own `playableAnimationLookup`, linkFlag=1)` once — wow-re `gameobject-anim-arm.md` §1, which
-/// CORRECTED `doodad-anim-host.md` §1's prose reading of `animations[0].id`; decision 0637) and/or
-/// the free-running [`GlobalSeqDrive`] (bone-index targets, the collapsed lane). `None` ⇒ the
-/// model is static and the caller keeps today's path untouched.
+/// Spawn the animation host for one placed M2 that animates: a root at the placement transform
+/// with the collapsed [`RigPose`] and, per tier, an `AnimationPlayer` looping the loader-idle seed
+/// (the reference's load arm `0x70ebd0` → `0x7121a0(bone 0, animation id 0, linkFlag=1)`) and/or
+/// a [`GlobalSeqDrive`]. `None` keeps the static path.
 pub fn spawn_anim_host(
     commands: &mut Commands,
     m: &M2Model,
     transform: Transform,
 ) -> Option<AnimHostSpawn> {
-    // The visual A/B harness (decision 0010) needs deterministic frames; a live animation clock
-    // isn't. Captures keep every doodad on the static path — bind pose renders identically to the
-    // static mesh (decision 0035), so world baselines stay comparable across runs and branches.
+    // Captures keep every doodad static, so their frames are deterministic.
     if crate::dev_state::deterministic_run() {
         return None;
     }
     let tier = classify(&m.skeleton, m.animations.as_ref());
-    // The SOUND arm (bug B345), orthogonal to the tier: a model whose pose is bind renders as the
-    // static mesh — 0130's gate is right about pixels — but its event track still has to run, and
-    // the reference runs it for every placed doodad. So a `Static`/`GlobalSeqOnly` model that
-    // authors `$DSL`/`$DSO`/`$SND` on its arm chain still gets a HOST here: `ModelAnimations` and
-    // the arm bookkeeping (`clip`/`anim_id`, which is what [`reroll_doodad_variation`] maintains and
-    // the event scanner reads), and deliberately **no `AnimationPlayer`** — there is no pose to
-    // evaluate, and paying for a rig to run a clock is exactly what 0130 exists to avoid.
+    // The sound arm, orthogonal to the tier: a bind-posed model still runs its event track, as in
+    // the reference, so it gets a host with the arm bookkeeping but no `AnimationPlayer`.
     let sound_arm = m.animations.as_ref().is_some_and(arms_for_sound);
     if matches!(tier, DoodadAnimTier::Static) && !sound_arm {
         return None;
@@ -227,63 +154,39 @@ pub fn spawn_anim_host(
         .animations
         .as_ref()
         .expect("animated tier or sound arm ⇒ animations");
-    // Chain-only visibility (`crate::vis_chain`): the host root renders nothing — its parts
-    // draw as world roots — and ~1.4k hosts sat in the per-camera sweep at the Goldshire pin.
     let root = commands
         .spawn((transform, Visibility::default()))
         .vis_chain_only()
         .id();
-    // The collapsed pose buffer (decision 1365 — 0724 replayed for this lane): no joint
-    // entities, no `AnimatedBy` targets, no `BillboardJointRig`. The 0712 evaluator poses
-    // `locals` off the player, the model pass folds + seats the anchors, and the world pass
-    // handles the billboard/arm bones and the palette rows.
-    //
-    // NO palette rig here either (decision 0863). The host's slot allocation is the CALLER's
-    // policy: the terrain-stream lane goes lazy — parts spawn on the static form and the draw
-    // gate allocates at the first wake ([`LazyRig`]) — because the resident population is
-    // thousands of parked hosts while the 2048-slot table is the scarce axis (the 0863 census:
-    // 1300–1750 parked of ~1900 live slots, active peak ~630). A gate-less caller (quest
-    // markers) allocates eagerly itself, or its host would never skin.
+    // The caller allocates the palette slot: lazily on the terrain-stream lane (`LazyRig`), eagerly
+    // for a gate-less caller such as quest markers, whose host would otherwise never skin.
     let pose = RigPose::new(root, &m.skeleton);
     let mut clip_info = None;
     let mut armed_seq = None;
     let mut arm_id = None;
     if let DoodadAnimTier::FirstSeq(head) = tier {
-        // (the rigged arm — player + graph + variation chain)
-        // The **loader's** seed only — `0x70ebd0`'s var-0 arm on the head of the chain. The real
-        // pick is the holder setup's second op4 call (`0x695100`, `variationIdx = -1`), which lands
-        // *after* it and is the effective arm (wow-re §4a); here that second arm is
-        // [`reroll_doodad_variation`]'s first pass, which fires the same frame because the host is
-        // born with an already-expired window. Splitting it that way is not a convenience: it is
-        // the one code path the reference has, since every later re-arm is byte-identical to the
-        // holder's first one.
+        // The loader's var-0 seed only (`0x70ebd0`). The effective arm is the holder's
+        // `variationIdx = -1` op4 (`0x695100`), here `reroll_doodad_variation`'s first pass, the
+        // same frame, since the host is born with an expired window.
         let mut player = AnimationPlayer::default();
         player.play(head.node).repeat();
         commands.entity(root).insert((
             player,
             AnimationGraphHandle(anims.graph.clone()),
-            // The re-roll needs the variation chain, and — now that a placed doodad's played
-            // sequence CHANGES — so does every per-sequence consumer that resolves off this host
-            // (`playing_seq`): the emitters' rate/enable tracks, the material-alpha sampler.
+            // For the re-roll and the per-sequence consumers resolving off this host.
             anims.clone(),
         ));
         clip_info = Some((head.node, head.duration));
         armed_seq = Some(head.seq_index);
         arm_id = Some(head.anim_id);
     } else if sound_arm {
-        // The clock-only arm: same loader seed, same self-sustaining re-roll — `ModelAnimations` is
-        // what [`reroll_doodad_variation`] needs, and without it the host would never be matched by
-        // that query and its window would never advance. No player, no graph handle: nothing here
-        // poses anything, and `gate_doodad_anim` already treats both as optional.
+        // The clock-only arm: the re-roll's query needs `ModelAnimations`; nothing here poses.
         let head = anims.idle_clip().expect("sound arm ⇒ an idle clip");
         clip_info = Some((head.node, head.duration));
         arm_id = Some(head.anim_id);
         commands.entity(root).insert(anims.clone());
-        // `armed_seq` stays `None` ON PURPOSE. It is the *only* input to `PlacementHost::arm`,
-        // which is what puts this placement's emitters on `EmitClock::Host` — a clock that reads
-        // the host's `AnimationPlayer`. This host has none, so claiming the arm would move a
-        // previously-`Pinned` emitter onto a player that does not exist. The sound clock is read
-        // from `clip`/`armed_at` instead, which needs no player and no slot number.
+        // `armed_seq` stays `None`: it alone moves the placement's emitters onto `EmitClock::Host`,
+        // which reads a player this host lacks. The sound clock reads `clip` and `armed_at`.
     }
     if let Some(drive) = GlobalSeqDrive::new_rig(&anims.global_bones, m.skeleton.joints.len()) {
         commands.entity(root).insert(drive);
@@ -298,69 +201,36 @@ pub fn spawn_anim_host(
     })
 }
 
-/// The anim-root component of one animated doodad placement: the draw gate's state + what to re-arm
-/// on resume. The root entity carries the placement transform, the joint hierarchy as children, and
-/// (per tier) the `AnimationPlayer`/[`GlobalSeqDrive`]; it lives in the placement's entity list, so
-/// it despawns (joints cascading) when the tile streams out.
+/// The anim root of one animated placement: the draw gate's state and what to re-arm on resume.
+/// It despawns with its tile, its bone anchors with it.
 #[derive(Component)]
 pub struct DoodadAnimHost {
-    /// The placement's skinned submesh entities — animation runs iff ANY of them is drawn (their
-    /// `Visibility` is the composed far-clip + distance-fade + portal-cull verdict).
+    /// The placement's skinned submeshes; animation runs while any of them is drawn.
     pub(crate) meshes: Vec<Entity>,
-    /// The placement's **draw-set gate** — the draw-set answer for a MESHLESS host (a
-    /// particles-only model like the InstancePortal swirl or Stratholme's burning-building fire:
-    /// 0 render batches, so no submesh carries a `Visibility` verdict). Not a fade sphere any
-    /// more but the whole [`crate::particles::EmitterFade`], **the same value the placement's
-    /// emitters, ribbons and glow lights were built with** (`terrain_stream::spawn::emitter_fade`,
-    /// one expression at one call site), so every rider of a placement freezes and resumes
-    /// together.
-    ///
-    /// It used to be `(radius, world_center)`, and [`gate_doodad_anim`] rebuilt the rest as
-    /// `instance: None, room: None` on the reasoning that a particles-only model is not a
-    /// building's prop. Stratholme's fire is 88 particles-only props of `stratholme_b.wmo`, and
-    /// with no instance the exterior-window term asks `ExteriorGate::admits_sphere` — which,
-    /// standing in a sealed room, is `Windows([])` and admits **nothing**. Every meshless prop of
-    /// the building the camera stood in was parked (decision 2059).
+    /// The draw-set gate of a meshless (particles-only) host: the [`crate::particles::EmitterFade`]
+    /// its emitters, ribbons and lights were built with, so they freeze together. It carries the
+    /// prop's building (instance and room), without which a sealed room would park its own props.
     pub(crate) fade: crate::particles::EmitterFade,
-    /// The looping first-sequence graph node + its duration (secs); `None` on the gseq-only tier.
+    /// The armed clip's graph node and duration (secs); `None` on the gseq-only tier.
     pub(crate) clip: Option<(AnimationNodeIndex, f32)>,
-    /// `Time::elapsed_secs` at the current **arm** — the player's clock origin: the variation
-    /// re-arms every play-window, and a resume must seek to `(now − armed_at) mod duration` or it
-    /// lands at the phase of a clip this host stopped playing several windows ago. (The
-    /// [`GlobalSeqDrive`] needs no origin at all — global sequences sample the shared world clock
-    /// directly, decision 0855.)
+    /// `Time::elapsed_secs` at the current arm, the player's clock origin: a resume seeks to
+    /// `(now − armed_at) mod duration`. The [`GlobalSeqDrive`] keeps its own attach anchor instead.
     pub(crate) armed_at: f32,
-    /// When the armed play-window ends, on the shared clock — the reference's `windowHi`
-    /// (`[model+0xac]`), rewritten by every arm. `now ≥ window_hi` ⇒ re-roll. A host is born with
-    /// this at `NEG_INFINITY` so the first frame performs the holder's `variationIdx = -1` arm.
+    /// The end of the armed play-window on the shared clock, the reference's `windowHi`
+    /// (`[model+0xac]`); `now ≥ window_hi` re-rolls. Born at `NEG_INFINITY`, so frame one arms.
     pub(crate) window_hi: f32,
-    /// The animation id to re-roll over ([`AnimHostSpawn::anim_id`]); `None` on the gseq-only tier,
-    /// which has no arm and therefore no window.
+    /// The animation id to re-roll over; `None` on the gseq-only tier, which has no window.
     pub(crate) anim_id: Option<u16>,
     /// Whether the host was ticking last frame (edge-triggered pause/resume).
     pub active: bool,
-    /// `Time::elapsed_secs` when `active` last flipped false — the reaper's age key (decision
-    /// 0863): under table pressure the longest-parked rigged hosts demote first. Never read
-    /// while `active`.
+    /// `Time::elapsed_secs` when `active` last went false: the reaper demotes the longest-parked.
     pub(crate) parked_at: f32,
 }
 
 impl DoodadAnimHost {
-    /// Where the **armed clip's own clock** stands right now: `(node, seek)`, the seek being
-    /// `(now − armed_at) mod duration`. `None` when nothing is armed (the gseq-only tier without a
-    /// sound arm — free-running channels have no window at all).
-    ///
-    /// The **shared clock, never the `AnimationPlayer`**, because it is the one answer both arms
-    /// can give: a clock-only host has no player to read at all, and a rigged one's resume seeks
-    /// the player to exactly this value, so the two never disagree while the host is drawn.
-    ///
-    /// It is **not** a claim that the cycle runs while the host is parked. This doc used to say the
-    /// reference gates the cycle on "linkage — residency, not the draw", and that read
-    /// `doodad-anim-host.md` §5b's *linkage* as "loaded": the note means spliced into the per-frame
-    /// scene worklist `[CM2Scene+0x20]`, which **is** the drawn/faded set — "a doodad culled out of
-    /// the drain stops advancing and resumes on re-link". Consumers that must honour that read
-    /// [`DoodadAnimHost::active`] beside this clock; the placed-doodad sound scanner
-    /// (`benilla_app::doodad_events`) does, and decision 2059 is what it cost not to.
+    /// The armed clip's `(node, seek)` on the shared clock, `(now − armed_at) mod duration`. It
+    /// answers while parked, but the reference fires no events for a doodad culled out of its
+    /// scene list (`[CM2Scene+0x20]`), so a consumer reads [`DoodadAnimHost::active`] beside it.
     pub fn arm_clock(&self, now: f32) -> Option<(AnimationNodeIndex, f32)> {
         let (node, duration) = self.clip?;
         // A zero-length clip has no phase to compute; it sits at its own t = 0.
@@ -373,32 +243,15 @@ impl DoodadAnimHost {
     }
 }
 
-/// The doodad's self-sustaining re-arm (decision 0768, wow-re `doodad-anim-host.md` §5): when the
-/// armed play-window ends, roll a fresh frequency-weighted variation of the same animation id, snap
-/// to it, and write the next window. This is the whole of bug B63's residual — the Blasted Lands
-/// lightning keys its entire burst in a 5.0 %-weighted variation (`frequency` 1638 of 32767), so
-/// with a once-at-load pick ~1.5 of the Tainted Scar's 31 placements strobed from a *fixed* spot
-/// every 1.3 s for ever, while the reference re-rolls all 31 every window and the strike wanders.
+/// The doodad's self-sustaining re-arm: when the armed play-window ends, roll a fresh
+/// frequency-weighted variation of the same animation id, snap to it (`blendFlag = 0` at
+/// `0x6951c8`, no cross-fade) and write the next window. An undrawn host only updates
+/// [`DoodadAnimHost::clip`], for [`gate_doodad_anim`]'s resume to arm.
 ///
-/// Two details that are easy to get wrong, both byte-pinned:
-/// - **The re-arm is a snap, not a blend** (`blendFlag = 0` at `0x6951c8`) — hence `stop_all` before
-///   the play rather than a cross-fade.
-/// - **This system runs over ALL hosts and never consults [`DoodadAnimHost::active`] — a
-///   DELIBERATE divergence, not a reading of the bytes.** The reference's per-frame walk covers
-///   exactly the models spliced into `[CM2Scene+0x20]`, and the doodad drain splices only what
-///   survived frustum + occlusion + the radius-tiered fade cutoff — so in the real client a doodad
-///   behind you *stops* advancing and, on re-link, finds `now ≥ windowHi` and re-arms at once
-///   (wow-re `animation/scratch/doodad-anim-host.md` §5b,
-///   `terrain/scratch/doodad-emitter-drawset-gate.md` §1c/§2b). Gating this here would therefore be
-///   the faithful shape, and it is left ungated on purpose: it would freeze the whole field while
-///   you looked away and re-roll all 31 of the Tainted Scar's placements on the frame you turned
-///   back, and that burst is an approved *look* to weigh with the director rather than a silent
-///   change (decision 2059 names it as the open follow-up). The sound lane is gated; this one is
-///   not, and the difference is recorded rather than smoothed over.
-///
-/// A host that is not currently drawn still re-rolls; it just updates [`DoodadAnimHost::clip`] and
-/// leaves the (stopped) player alone, so [`gate_doodad_anim`]'s resume arms whatever the latest
-/// window rolled.
+/// Deviation: this runs for every resident host, where the reference stops a doodad culled out
+/// of its scene list (`[CM2Scene+0x20]`) and re-arms it at once on re-link (`0x7074b0`,
+/// `0x683f80`), because gating it so would re-roll the whole field on the frame the camera turns
+/// back.
 fn reroll_doodad_variation(
     time: Res<Time>,
     mut rng: ResMut<benilla_assets::AnimRng>,
@@ -411,21 +264,20 @@ fn reroll_doodad_variation(
     let now = time.elapsed_secs();
     for (mut host, anims, player) in &mut hosts {
         let Some(anim_id) = host.anim_id else {
-            continue; // gseq-only: free-clock loops, never armed (§1)
+            continue; // gseq-only: never armed
         };
         if now < host.window_hi {
             continue;
         }
         let Some(clip) = anims.pick_variation(anim_id, rng.draw()) else {
-            // No chain for this id (a model whose sequence set changed under us): stop asking.
+            // No chain for this id: stop asking.
             host.anim_id = None;
             continue;
         };
         let (node, duration) = (clip.node, clip.duration);
         let replay = rng.replay_count(clip.replay);
         host.armed_at = now;
-        // `span · R` — for `replay = (0, 0)` that is exactly one loop, so the roll repeats every
-        // pass. A zero-duration clip would make this a busy loop, so it costs one window minimum.
+        // `span · R`, one loop for `replay = (0, 0)`; a zero-duration clip gets a minimum window.
         host.window_hi = now + (duration * replay as f32).max(f32::EPSILON);
         host.clip = Some((node, duration));
         if host.active {
@@ -437,10 +289,9 @@ fn reroll_doodad_variation(
     }
 }
 
-/// The draw gate: pause a doodad's animation when none of its submeshes is drawn, resume — seeking
-/// both clocks to the shared-clock position — when one is again. Runs before [`AnimationSystems`] so
-/// a resume's seek lands the same frame. Steady state (nothing flipped) is one `Visibility` read per
-/// mesh, no writes.
+/// The draw gate: stop a doodad's animation while it is not drawn, and on resume seek the player
+/// to the arm's shared-clock phase. Runs before [`AnimationSystems`], so the seek lands the same
+/// frame.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 fn gate_doodad_anim(
     time: Res<Time>,
@@ -459,28 +310,18 @@ fn gate_doodad_anim(
             Ref<GlobalTransform>,
             &bevy::camera::primitives::Frustum,
             Ref<bevy::camera::Projection>,
-            // The seat's own write, visible THIS frame: `GlobalTransform` only changes after
-            // propagation, which runs after this system — so on a teleport frame the global
-            // reads still while the camera has already moved. Reading the local too is what
-            // keeps the verdict reuse below from carrying a pre-snap verdict across a snap
-            // (the over-bright lamppost glow after a .tele, 2026-09-04).
+            // The seat's own write: `GlobalTransform` propagates after this system, so on a
+            // teleport frame only the local shows the camera moved.
             Option<Ref<Transform>>,
         ),
         With<crate::view::WorldCamera>,
     >,
-    // A meshed host's verdict is its meshes' `Visibility`; when none moved this frame and the
-    // camera stood still, every host's verdict is last frame's (decision 1979's floor: ~1.5 k
-    // hosts × their submesh lookups on every still frame).
+    // With no part's `Visibility` changed and the camera still, every verdict is last frame's.
     changed_vis: Query<(), (Changed<Visibility>, With<crate::model_render::ModelPart>)>,
-    // The frame's draw-set inputs, as ONE bundle: the far-clip wall, the exterior-window gate
-    // (a meshless prop OUTSIDE, seen from a WMO interior, is not in the frame's worklist and must
-    // not tick its bones either — 0786), the room the camera stands in, and the portal instances
-    // a prop's own rooms resolve through (0689/1289). The same `SystemParam` the particle and
-    // ribbon sims read, so the three riders of one placement cannot answer the draw-set question
-    // differently (2059).
+    // The draw-set inputs (far clip, exterior-window gate, camera room, portal instances), the
+    // same `SystemParam` the particle and ribbon sims read, so a placement's riders agree.
     scene: crate::particles::sim::SceneGates,
-    // The lazy-rig lane's wake half (decision 0863, [`lazy`]): a drawn host without a slot
-    // promotes here — allocation, row seed, part swap.
+    // The lazy-rig lane's wake half: a drawn host without a slot promotes here.
     mut palettes: ResMut<crate::rig_palette::RigPalettes>,
     ibps: Res<Assets<SkinnedMeshInverseBindposes>>,
     worlds: Query<&GlobalTransform>,
@@ -488,8 +329,7 @@ fn gate_doodad_anim(
     mut commands: Commands,
     mut logged: Local<bool>,
 ) {
-    // One breadcrumb per session, the first frame any host exists — the machine-readable "doodads
-    // are animating" signal (the live count is in the debug panel).
+    // One log line per session, the first frame any host exists.
     if !*logged && !hosts.is_empty() {
         *logged = true;
         info!("doodad anim: first host armed (decision 0130 phase 1)");
@@ -503,21 +343,12 @@ fn gate_doodad_anim(
     }) && !scene.changed()
         && changed_vis.is_empty();
     for (entity, mut host, lazy, pose, has_rig, player, drive) in &mut hosts {
-        // A host born this frame has no verdict to reuse (`active` starts false): a meshless one
-        // spawned under a parked camera stayed parked until the camera moved (review
-        // 2026-09-04). Read off the host's own tick — a second query on the component would
-        // conflict with this one's `&mut`.
+        // A host born this frame has no verdict to reuse (`active` starts false).
         let drawn = if verdicts_still && !host.is_added() {
             host.active
         } else if host.meshes.is_empty() {
-            // Meshless (particles-only) host: the emitters' own draw-set law (see the `fade`
-            // field doc) — the reference ticks animation for any model in the draw set, and a
-            // 0-batch model is admitted on its fade sphere exactly like its emitters are.
-            // "Exactly like" is literal: this asks the placement's OWN `EmitterFade` — the very
-            // value its emitters and ribbons were handed — through `in_draw_set`, the single
-            // spelling of the rule. A second copy of it is how the far-clip term went missing
-            // here as well as in the emitters (0678/B39), and how a particles-only WMO prop lost
-            // its building identity and was culled from inside its own room (2059).
+            // Meshless: the reference ticks any model in the draw set, and a 0-batch model is
+            // admitted on its fade sphere like its emitters, through the same `in_draw_set`.
             let fade = &host.fade;
             world_cam.as_ref().is_some_and(|(cam_tf, frustum, _, _)| {
                 fade.in_draw_set(
@@ -540,20 +371,10 @@ fn gate_doodad_anim(
                 .iter()
                 .any(|&e| vis.get(e).is_ok_and(|v| *v != Visibility::Hidden))
         };
-        // The lazy-rig promote (decision 0863, [`lazy`]): a host DRAWN two frames running (`&&
-        // host.active` — last frame's verdict) holding a [`lazy::LazyRig`] and no slot yet — its
-        // first wake, or a denial being retried — claims its palette slot now. Checked every
-        // frame it stays drawn, not just on the flip edge, so a momentarily full table is a
-        // short delay at bind pose, never the permanent statue this lane was built to kill.
-        //
-        // Two frames, not one, because the first frame is a LIE: a spawned part's `Visibility`
-        // defaults to `Inherited` (a `Mesh3d` required component) and the fade/cull authorities
-        // ran before the spawner's commands applied — so on its first frame every far doodad in
-        // the streamed tile reads "drawn". Promoting on that frame re-created the eager design
-        // one frame late (measured on the 0863 verification leg: ~1500 parked hosts holding
-        // slots, the pre-fix census's own number). The second frame's verdict is the
-        // authorities' real one; a genuinely visible host promotes one frame late, at fade-in
-        // distance, invisibly.
+        // The lazy-rig promote, retried every frame the host stays drawn so a full table is only
+        // a delay. It needs a second drawn frame (`host.active`): on its first, a spawned part's
+        // `Visibility` is still the `Inherited` default the fade and cull authorities have not
+        // judged, so every far doodad of a new tile reads drawn.
         if drawn && host.active && !has_rig {
             if let Some(lazy) = lazy {
                 lazy::promote_lazy_rig(
@@ -572,15 +393,12 @@ fn gate_doodad_anim(
             continue;
         }
         host.active = drawn;
-        // The rig-machinery half of the park (decision 1365): the marker gates the 0712
-        // evaluator, the model compose, and the world finalize — so a hidden host's collapsed
-        // rig costs nothing at all, where the joint hierarchy kept paying propagation. The
-        // commands apply before `AnimationSystems` (the gate orders `.before` it), so a resume's
-        // re-arm below evaluates the same frame the marker drops — 0739's wake law.
+        // `AnimParked` holds the pose evaluation, compose and finalize; these commands apply
+        // before `AnimationSystems`, so a resume's re-arm evaluates the frame the marker drops.
         if drawn {
             commands.entity(entity).remove::<AnimParked>();
         } else {
-            host.parked_at = now; // the reaper's age key (decision 0863)
+            host.parked_at = now; // the reaper's age key
             commands.entity(entity).insert(AnimParked);
         }
         if let Some(mut p) = player {
@@ -589,22 +407,17 @@ fn gate_doodad_anim(
                     let anim = p.start(node);
                     anim.repeat();
                     if duration > 0.0 {
-                        // Phase from the current ARM, not from spawn: the variation re-arms every
-                        // play-window, so `spawned_at` names a clip this host may have stopped
-                        // playing many windows ago (decision 0768).
+                        // Phase from the current arm, not from spawn: the variation re-arms.
                         anim.seek_to((now - host.armed_at).rem_euclid(duration));
                     }
                 }
             } else {
-                // Stop (not pause): a paused active animation is still sampled and applied every
-                // frame by `animate_targets`; stopping empties the player so a hidden doodad costs
-                // nothing. The resume above re-arms + seeks, which is the faithful clock semantics.
+                // Stop, not pause: `animate_targets` still applies a paused animation each frame.
                 p.stop_all();
             }
         }
         if let Some(mut d) = drive {
-            // No re-seek on resume: the drive samples the shared world clock (decision 0855), so
-            // a re-appearing doodad lands on the phase the clock dictates by construction.
+            // No re-seek: the drive's cursor, sceneNow − attach, is a pure function of the clock.
             d.set_paused(!drawn);
         }
     }
@@ -616,39 +429,30 @@ impl Plugin for DoodadAnimPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<UvAnimMaterials>();
         app.init_resource::<TintAnimMaterials>();
-        // The client's ONE `rand()` stream (`benilla_assets::AnimRng`), seeded here because this
-        // is where the engine boots and where `deterministic_run` is knowable — the reference's
-        // own `srand(GetTickCount())` runs once per process from CRT static init, pre-`WinMain`
-        // (wow-re `net/scratch/crt-rand-stream-seeding.md`; decision 2301). A capture keeps the
-        // CRT's pre-`srand` value, so golden frames stay reproducible.
+        // The one `rand()` stream: the reference seeds it once per process before `WinMain`
+        // (`srand(GetTickCount())`, `0x5d1c70`); a capture leaves it unseeded.
         app.init_resource::<benilla_assets::AnimRng>();
         let deterministic = crate::dev_state::deterministic_run();
         app.world_mut()
             .resource_mut::<benilla_assets::AnimRng>()
             .seed_for_session(deterministic);
-        // The re-roll runs BEFORE the draw gate: a window that expires this frame must arm its new
-        // clip before the gate decides what to resume, or a host re-appearing on the same frame
-        // resumes the previous window's variation for one frame.
+        // The re-roll runs before the draw gate, or a host re-appearing as its window expires
+        // resumes the old variation for a frame.
         app.add_systems(
             PostUpdate,
             (reroll_doodad_variation, gate_doodad_anim)
                 .chain()
                 .before(AnimationSystems),
         );
-        // The lazy-rig pressure reaper (decision 0863): one headroom read per frame when the
-        // table has room; demotes longest-parked rigged hosts when it doesn't.
         app.add_systems(Update, lazy::reap_parked_rigs);
-        // `sample_mat_anim` runs before the visibility authority (`ModelVisSet`): it composes
-        // `MatAnim::current` into the render-alpha tag the same frame. The material tick runs
-        // *after* it, because its draw gate reads the verdict that authority writes — one frame
-        // later would freeze a scroll for a frame on every doodad that comes into view.
+        // `sample_mat_anim` runs before the visibility authority, which composes its value the
+        // same frame; the material tick runs after, since its draw gate reads that verdict.
         app.add_systems(
             Update,
             (
                 sample_mat_anim.before(crate::model_render::ModelVisSet),
                 tick_anim_materials.after(crate::model_render::ModelVisSet),
-                // The readout of everything that lane just decided (`WOW_MATANIM_PROBE`), after
-                // it, so the `row` column is this frame's write and not the previous one's.
+                // After the tick, so the probe's `row` column is this frame's write.
                 mat_anim::matanim_probe.after(tick_anim_materials),
             ),
         );
@@ -736,10 +540,6 @@ mod tests {
         }
     }
 
-    /// The unit lane's resolution: a part reads the sequence its HOST is playing, and follows it
-    /// when the host changes animation. This is the plumbing B16/B20 turn on — with the old
-    /// single-sequence bake there was nothing to follow, so a voidwalker's death-only armour drew
-    /// in every animation.
     #[test]
     fn hosted_mat_anim_follows_the_host_sequence() {
         let mut app = App::new();
@@ -763,7 +563,6 @@ mod tests {
             "playing sequence 0 ⇒ the batch is culled"
         );
 
-        // Switch the host to the other sequence: the same part must now draw.
         let world = app.world_mut();
         let mut entity = world.entity_mut(host);
         {
@@ -779,9 +578,7 @@ mod tests {
         );
     }
 
-    /// A hosted part whose host has no `AnimationPlayer` yet (the frame before the rig arms, a
-    /// rest-pose GameObject) still resolves — to slot 0 at t=0, the sequence's opening pose. It
-    /// must not read as fully visible by default, or the batch flashes for a frame at spawn.
+    /// With no player yet, slot 0 at t = 0, so the batch does not flash visible for a frame.
     #[test]
     fn hosted_mat_anim_without_a_player_reads_the_first_sequence() {
         let mut app = App::new();
@@ -799,8 +596,6 @@ mod tests {
         );
     }
 
-    /// The pinned lanes are unchanged: a doodad/effect instance reads the slot it was built with,
-    /// on its own spawn clock, and never consults a host.
     #[test]
     fn pinned_mat_anim_reads_its_own_slot() {
         let a = two_seq_alpha();
@@ -828,8 +623,6 @@ mod tests {
         }
     }
 
-    /// The content gate: no animations / no joints / a motionless first sequence ⇒ static (today's
-    /// path); gseq channels alone ⇒ the player-less tier; a moving first sequence ⇒ the looping arm.
     #[test]
     fn classify_picks_the_measured_tiers() {
         // No ModelAnimations at all (a barrel): static.
@@ -837,13 +630,13 @@ mod tests {
             classify(&skeleton(3), None),
             DoodadAnimTier::Static
         ));
-        // Boneless model: static even with parsed animations (the 0035 out-of-bounds guard).
+        // Boneless model: static even with parsed animations.
         let a = anims(vec![clip(0)], Some(0), true);
         assert!(matches!(
             classify(&skeleton(0), Some(&a)),
             DoodadAnimTier::Static
         ));
-        // A motionless first sequence, no gseq (a posed tree): static — no skin, no player.
+        // A motionless first sequence, no gseq (a posed tree): static.
         let a = anims(vec![clip(0)], None, false);
         assert!(matches!(
             classify(&skeleton(3), Some(&a)),
@@ -861,13 +654,8 @@ mod tests {
             classify(&skeleton(3), Some(&a)),
             DoodadAnimTier::FirstSeq(c) if c.anim_id == 0
         ));
-        // A CLOCK-ONLY model (decision 0941): every sequence now builds a clip, so a model whose
-        // bones never move — the Molten Core rune, the flame ring, 807 corpus models whose
-        // animation lives entirely in their emitter tracks — arrives here with clips and NO
-        // `first_seq` (the content gate declined it). It must still classify Static: its clock is
-        // armed by the entity lane off `idle_clip`, and rigging it could only reproduce the
-        // bind-pose mesh. This is the case that used to reach `first_seq: None` by never having
-        // built a clip at all.
+        // A clock-only model (clips but no `first_seq`: its animation lives in emitter tracks)
+        // stays Static; the entity lane arms its clock off `idle_clip`.
         let a = anims(vec![clip(0)], None, false);
         assert!(matches!(
             classify(&skeleton(3), Some(&a)),
@@ -881,10 +669,8 @@ mod tests {
         ));
     }
 
-    /// The lightning's own chain, read off the bytes (`benilla-extract m2seq` on
-    /// `World\Generic\PassiveDoodads\ParticleEmitters\BlastedLandsLightningbolt01.M2`): two
-    /// variations of animation id 0, weights 31129 / 1638 — so slot 1, which is where all four
-    /// emitters key their entire burst, carries exactly 5.0 %.
+    /// `BlastedLandsLightningbolt01.M2`'s chain: two variations of animation id 0, weights 31129
+    /// and 1638, so slot 1, where its emitters key the whole burst, carries 5.0 %.
     fn lightning_anims() -> ModelAnimations {
         let mut a = anims(vec![seq_clip(0, 0, 1), seq_clip(0, 1, 2)], Some(0), false);
         a.clips[0].frequency = 31129;
@@ -895,8 +681,7 @@ mod tests {
     }
 
     fn reroll_app() -> App {
-        // Deliberately NOT MinimalPlugins: `TimePlugin` drives `Time` off the real clock, which
-        // would clobber the manual advance these tests need to step whole play-windows.
+        // No `TimePlugin`: its real clock would clobber the manual advances that step windows.
         let mut app = App::new();
         app.init_resource::<Time>();
         app.init_resource::<benilla_assets::AnimRng>();
@@ -923,20 +708,12 @@ mod tests {
             .id()
     }
 
-    /// **Bug B63's residual, and the whole of decision 0768.** A placed doodad re-rolls its
-    /// frequency-weighted variation every play-window, for ever — it does NOT hold the one it
-    /// picked at load.
-    ///
-    /// Under the superseded contract the pick was once-at-load *and* seeded off the placement's
-    /// world position, so a Tainted Scar bolt that rolled slot 0 was silent for the life of the
-    /// session and one that rolled slot 1 strobed from that same fixed spot every 1.3 s for ever.
-    /// The reference re-rolls all 31 placements every window, which is why its strikes wander.
     #[test]
     fn a_placed_doodad_rerolls_its_variation_every_play_window() {
         let mut app = reroll_app();
         let host = lightning_host(&mut app);
 
-        // Frame 1: born with an expired window ⇒ the holder's `variationIdx = -1` arm lands at once.
+        // Frame 1: born with an expired window, the holder's `variationIdx = -1` arm lands at once.
         app.update();
         let armed = |app: &App| {
             app.world()
@@ -947,7 +724,6 @@ mod tests {
         };
         assert!(armed(&app).is_some(), "the first frame arms");
 
-        // Step whole windows and record which variation each one landed on.
         let mut seen = std::collections::HashMap::new();
         for _ in 0..400 {
             app.world_mut()
@@ -968,27 +744,20 @@ mod tests {
         let slot0 = seen.get(&AnimationNodeIndex::new(1)).copied().unwrap_or(0);
         let slot1 = seen.get(&AnimationNodeIndex::new(2)).copied().unwrap_or(0);
         assert_eq!(slot0 + slot1, 400, "every window arms one of the two");
-        // The bug was a placement stuck on ONE variation for ever. Both must occur.
         assert!(
             slot1 > 0,
             "the 5 % strike variation never came up in 400 windows — the bolt is stuck again"
         );
         assert!(slot0 > 0, "the 95 % silent variation never came up");
-        // A sanity band, not a distribution test — 400 windows off one fixed seed is far too few
-        // for that (it lands on 10, ~2.3σ under the mean, unremarkable). The weighting itself was
-        // measured separately over 200 000 draws: **4.9665 %** taken at the real
-        // two-draws-per-window stride, against the authored 1638/32768 = 4.9988 %. MSVC's LCG shows
-        // no stride bias here, which is worth having checked: the variation roll and the replay
-        // count come off the same stream, and a strided LCG is exactly where a rare variation could
-        // quietly under-fire and leave the field half as active as the reference's.
+        // A sanity band, not a distribution test: this seed lands on 10 (~2.3σ low). Over 200 000
+        // draws at two per window the rate is 4.9665 % against the authored 4.9988 %.
         assert!(
             (2..=60).contains(&slot1),
             "slot 1 came up {slot1}/400 — far enough off its authored 5 % to suspect the roll"
         );
     }
 
-    /// The gseq-only tier has no arm, so it has no play-window and nothing to re-roll: its channels
-    /// are free-clock loops the reference drives with zero arming (§1).
+    /// Global sequences loop with no arming, so the gseq-only tier opens no window.
     #[test]
     fn a_gseq_only_host_never_rerolls() {
         let mut app = reroll_app();
@@ -1020,11 +789,7 @@ mod tests {
         assert_eq!(h.window_hi, f32::NEG_INFINITY, "no window was ever opened");
     }
 
-    /// A host that is not currently drawn still advances its window — the reference gates the cycle
-    /// on **linkage** (the in-range doodad drain), not on the draw. Gating on the draw would freeze
-    /// the field while the camera looks away and then re-roll every placement on the one frame it
-    /// turns back: a burst of simultaneous strikes the reference cannot produce. The undrawn host
-    /// keeps its stopped player and just updates what a resume will arm.
+    /// The deviation on [`reroll_doodad_variation`]: an undrawn host cycles, its player untouched.
     #[test]
     fn an_undrawn_host_keeps_cycling() {
         let mut app = reroll_app();
@@ -1069,23 +834,14 @@ mod tests {
         );
     }
 
-    /// The draw gate stops the player + pauses the gseq drive when every submesh is hidden, and on
-    /// re-appearing re-arms at the shared-clock position (`(now − armed_at) mod duration`) — the
-    /// ref's clock-indexed pose, so pause history never desyncs phase.
     #[test]
     fn gate_pauses_hidden_and_resumes_on_the_shared_clock() {
         let mut app = App::new();
-        app.add_plugins((MinimalPlugins, AssetPlugin::default())); // Time + asset stores
-                                                                   // The gate reads the far-clip wall (0678) — this host is mesh-BACKED, so it takes the
-                                                                   // `Visibility` branch and never consults it, but the system still needs the resource.
+        app.add_plugins((MinimalPlugins, AssetPlugin::default()));
+        // The gate's params must resolve, though this meshed host never reads these.
         app.init_resource::<crate::view::ViewDistance>();
-        // …and the exterior-window gate's two terms (0786), for the same reason: this host is
-        // mesh-BACKED so it never consults them, but the system's params must resolve. Their
-        // defaults are the outdoor case (`Unrestricted`, no room claimed).
         app.init_resource::<crate::wmo_portal::ExteriorWindows>();
         app.init_resource::<crate::wmo_portal::CameraInteriorClaim>();
-        // The lazy-rig promote's params (decision 0863) — this host carries no `LazyRig`, so
-        // the wake edge never fires here, but the params must resolve.
         app.init_resource::<crate::rig_palette::RigPalettes>();
         app.init_asset::<SkinnedMeshInverseBindposes>();
         app.add_systems(Update, gate_doodad_anim);
@@ -1108,8 +864,7 @@ mod tests {
                     fade: crate::particles::EmitterFade::sphere(1.0, Vec3::ZERO),
                     clip: Some((node, 2.0)),
                     armed_at: 0.0,
-                    // Far future: this test exercises the DRAW gate, so no window may expire
-                    // under it and change the armed clip mid-assertion.
+                    // Far future: no window may expire and change the armed clip mid-test.
                     window_hi: f32::INFINITY,
                     anim_id: Some(0),
                     active: true,
@@ -1120,7 +875,6 @@ mod tests {
             ))
             .id();
 
-        // Visible: stays active, player untouched.
         app.update();
         let playing = |app: &mut App, e: Entity| {
             app.world_mut()
@@ -1132,7 +886,6 @@ mod tests {
         };
         assert_eq!(playing(&mut app, host), 1, "drawn ⇒ playing");
 
-        // Hide the one submesh: the player empties (stopped, zero per-frame cost).
         *app.world_mut()
             .entity_mut(mesh)
             .get_mut::<Visibility>()
@@ -1147,7 +900,6 @@ mod tests {
                 .active
         );
 
-        // Show it again: re-armed, looping, sought to the shared-clock position (< duration).
         *app.world_mut()
             .entity_mut(mesh)
             .get_mut::<Visibility>()
@@ -1164,23 +916,7 @@ mod tests {
         );
     }
 
-    /// [`DoodadAnimHost::arm_clock`] — the sound lane's phase, which must be the SHARED clock's,
-    /// never the (draw-gated) player's. Three claims: it wraps with the clip, it is unaffected by
-    /// the host being parked, and an unarmed host has no phase at all.
-    /// **A meshless prop of the building the camera stands in keeps animating** — decision 2059's
-    /// wiring, pinned where it broke.
-    ///
-    /// `EmitterFade`'s own tests already pin the LAW (`particles`:
-    /// `a_sealed_room_keeps_its_own_props_burning_and_stops_everything_else`). What was wrong here
-    /// was the wiring: this gate built its meshless host a fresh `EmitterFade` with
-    /// `instance: None, room: None`, so the exterior-window term fell through to
-    /// `ExteriorGate::admits_sphere` — and a sealed room is `Windows([])`, which "admits nothing".
-    /// Every particles-only WMO prop of the camera's OWN building was therefore parked, which is
-    /// Stratholme's 88 burning-building fires: 0 render batches each, so nothing but this branch
-    /// ever judged them, and their `$DSL` never fired.
-    ///
-    /// The control is the second host: same sphere, same place, no building — an ADT map doodad,
-    /// which a sealed room really must stop.
+    /// The control is a map doodad at the same spot with no building, which the sealed room stops.
     #[test]
     fn a_sealed_room_keeps_its_own_meshless_props_animating() {
         use crate::wmo_portal::{
@@ -1194,7 +930,7 @@ mod tests {
         app.init_asset::<SkinnedMeshInverseBindposes>();
         app.add_systems(Update, gate_doodad_anim);
 
-        // The camera stands inside a sealed room of `building` — no exterior window at all.
+        // The camera stands inside a sealed room of `building`, with no exterior window.
         let building = app
             .world_mut()
             .spawn(WmoPortalInstance {
@@ -1238,7 +974,7 @@ mod tests {
         let mut meshless = |fade: crate::particles::EmitterFade| {
             app.world_mut()
                 .spawn(DoodadAnimHost {
-                    meshes: Vec::new(), // 0 render batches — the whole point
+                    meshes: Vec::new(), // 0 render batches
                     fade,
                     clip: Some((node, 2.0)),
                     armed_at: 0.0,
@@ -1279,11 +1015,8 @@ mod tests {
         );
     }
 
-    /// The teleport frame (2026-09-04): this system runs before transform propagation, so the
-    /// camera's `GlobalTransform` still reads still on the frame its `Transform` was re-seated,
-    /// and the verdict reuse carried every host's pre-snap verdict across the snap — a lamppost
-    /// glow that should have parked kept its clock, a host that should have woken stayed parked.
-    /// The gate must read the seat's own write.
+    /// The gate runs before transform propagation, so on a teleport frame only the camera's local
+    /// has moved, and the verdict reuse must still re-judge every host.
     #[test]
     fn a_reseated_camera_is_not_a_still_scene() {
         let mut app = App::new();
@@ -1295,9 +1028,8 @@ mod tests {
         app.init_asset::<SkinnedMeshInverseBindposes>();
         app.add_systems(Update, gate_doodad_anim);
 
-        // A camera 1000 yd from the host, looking away: the host's frustum verdict is "not
-        // drawn". No propagation plugin, so `GlobalTransform` never follows `Transform` —
-        // exactly the ordering the gate sees on the real snap frame.
+        // A camera 1000 yd off, looking away: not drawn. With no propagation, `GlobalTransform`
+        // never follows `Transform`, as on the real snap frame.
         let far =
             Transform::from_xyz(1000.0, 0.0, 0.0).looking_at(Vec3::new(2000.0, 0.0, 0.0), Vec3::Y);
         let projection = bevy::camera::Projection::from(bevy::camera::PerspectiveProjection {
@@ -1356,9 +1088,7 @@ mod tests {
         app.update();
         assert!(!active(&app), "still ⇒ the verdict is reused, still parked");
 
-        // The snap: the seat writes the camera's local next to the host, facing it. The global
-        // (and the frustum built from it) stay stale this frame — and the host must still be
-        // re-judged rather than reused.
+        // The snap: the seat writes the local next to the host, facing it; the global stays stale.
         let near = Transform::from_xyz(0.0, 0.0, 10.0).looking_at(Vec3::ZERO, Vec3::Y);
         let near_frustum = bevy::camera::primitives::Frustum::from_clip_from_world(
             &(bevy::camera::Projection::from(bevy::camera::PerspectiveProjection {
@@ -1372,9 +1102,7 @@ mod tests {
             let mut e = app.world_mut().entity_mut(cam);
             *e.get_mut::<Transform>().unwrap() = near;
             *e.get_mut::<bevy::camera::primitives::Frustum>().unwrap() = near_frustum;
-            // The propagated frame, written WITHOUT a change tick: on the real snap frame it is
-            // last frame's value (propagation has not run), and this is the closest a test can
-            // stand to that — the only "moved" signal on this frame is the local.
+            // Written without a change tick, so the local is this frame's only moved signal.
             *e.get_mut::<GlobalTransform>()
                 .unwrap()
                 .bypass_change_detection() = GlobalTransform::from(near);
@@ -1392,9 +1120,7 @@ mod tests {
             armed_at: 10.0,
             window_hi: f32::NEG_INFINITY,
             anim_id: Some(0),
-            // PARKED — and the clock still answers, which is the point: `arm_clock` is a pure
-            // function of the shared clock, so the phase is defined whether or not the host is in
-            // the animate set. Honouring that membership is the CALLER's job (decision 2059).
+            // Parked, and the clock still answers: honouring the animate set is the caller's job.
             active: false,
             parked_at: 0.0,
         };
@@ -1405,11 +1131,9 @@ mod tests {
         let (_, seek) = host.arm_clock(12.0).expect("armed");
         assert!((seek - 2.0).abs() < 1e-4, "2 s in, {seek}");
 
-        // Past one full cycle it wraps rather than running off the end.
         let (_, seek) = host.arm_clock(14.0).expect("armed");
         assert!((seek - (4.0 - 3.333)).abs() < 1e-4, "wrapped to {seek}");
 
-        // A zero-length clip has no phase to compute and must not divide by it.
         host.clip = Some((AnimationNodeIndex::new(1), 0.0));
         let (_, seek) = host.arm_clock(99.0).expect("armed");
         assert!(
@@ -1417,7 +1141,6 @@ mod tests {
             "a zero-length clip sits at its own t = 0"
         );
 
-        // Nothing armed (the gseq-only tier without a sound arm) ⇒ no phase, so nothing fires.
         host.clip = None;
         assert!(host.arm_clock(12.0).is_none());
     }
diff --git a/crates/benilla-world/src/entity_shade.rs b/crates/benilla-world/src/entity_shade.rs
index 440993e8..cb6c28b1 100644
--- a/crates/benilla-world/src/entity_shade.rs
+++ b/crates/benilla-world/src/entity_shade.rs
@@ -1,55 +1,17 @@
-//! Entity ground-shade (decision 0173): units, players, and GameObjects sample the terrain MCSH under
-//! them **dynamically** and dim their sun term when standing in baked ground shadow — the fold-back of
-//! wow-re's byte-verified §8a/§9 verdict (`models/scratch/m2-interior-doodad-base-light`): a spawned
-//! unit/player/GameObject carries the SAME 2.5-lit / 0.5-MCSH-shadowed chain as an ADT doodad, driven by
-//! a per-frame MCSH sample at the object's node position and a linear intensity ramp (`0x69e770`, the
-//! step constant `[0x810808] = 3.3333`/s), not a static spawn-time bake.
+//! Entity ground shade: a unit, player or GameObject re-samples the terrain MCSH under it as it
+//! moves, rather than baking it at spawn, and ramps its light node's intensity between the
+//! reference's 2.5 lit and 0.5 shadowed (`0x69e770`, step `[0x810808]` = 3.3333/s).
 //!
-//! **The chain applies to units, and 0814 restored it after 0809 wrongly took it away.** The reference
-//! has TWO real delivery states for a unit's committed light, and which one a given unit is in is a
-//! *lifecycle* fact, not a category fact. Delivery splits at `0x672a20`: with `[model+0x3c0] != 0` the
-//! node applies (`0x6a7300` multiplies the diffuse by the ramped `[+0xa4]` — the 2.5/0.5 chain this
-//! file models); with `[model+0x3c0] == 0` the null fallback commits the raw day/night pair with no
-//! intensity multiply at all — a hardwired ×1.0, position-independent, never sampling MCSH.
-//! Registration fires on a model-set with the node present (`Node::SetModel 0x6716f0` ←
-//! `0x613cf0`/`0x613d80`: equip / display-id / shapeshift); node birth (`0x670db0` from Activate
-//! `0x613e10`) passes model arg 0, so its birth-time registration gate `670fca` is skipped and a unit
-//! is born UNREGISTERED.
+//! The reference lights a unit through the node only once registered (`0x672a20`, `[model+0x3c0]`;
+//! `0x6a7300` scales the diffuse by `[+0xa4]`), which a model-set does (`0x6716f0` from
+//! `0x613cf0`/`0x613d80`: equip, display id, shapeshift); a unit born unregistered (`0x670db0`,
+//! from `0x613e10`) commits the raw day/night pair at ×1.0. Every drawn unit has had its display
+//! model set, so only the registered state is modelled; which units stay unregistered is untraced
+//! (reference frames show a standing player at ×2.5 and a running one at ×1.0).
 //!
-//! **We model REGISTERED, because that is the steady state of anything we draw.** Every unit benilla
-//! renders has had its display model applied — which is exactly the node-present model-set that
-//! registers it — so unregistered is the pre-display transient, not the resting state. wow-re's own
-//! two frames bracket this and disagree with each other: a standing Stormwind player commits **×2.5**
-//! (registered, MCSH-lit) while a running Northshire player commits ×1.0
-//! (`unit-mcsh-shadow-target.md` §4). Their note marks the discriminant **Open** and hands it to us as
-//! a benilla-side observable — so a single hardwired value cannot be read off it in either direction,
-//! and 0809 read off the ×1.0 half. The director's eye settles the tie the way the ×2.5 frame does: a
-//! character standing in shade reads visibly dimmer than one in sun, and flattening that was wrong.
-//!
-//! The null fallback is therefore real, verified, and **deliberately not modelled** — see 0814. If we
-//! ever want it, it is a lifecycle flag flipped by the display-model apply, never a per-kind constant.
-//!
-//! Structure mirrors the reference's one-light-node-per-object: [`GroundShade`] lives on the **net
-//! entity root** (the `[obj+0xe0]` twin), sampled at the root's feet and ramped there; the resulting
-//! shade byte is written to every M2 part in the root's descendant tree — body submeshes, and held
-//! items/helm/shoulders hanging off joint entities — via the `MeshTag` shade field (`mesh_tag`), so a
-//! weapon dims with its wielder rather than sampling independently at the hand (the real client lights
-//! attachments from the owner's node; independent sampling would flicker at shadow edges mid-swing).
-//!
-//! Interplay: the interior classifier ([`crate::interior`]) owns a part's tag while it stands in a WMO
-//! room (an SH-probe slot — no sun indoors, so no shade either); this system skips those parts and
-//! runs after the classifier to re-assert the byte over its exterior reclaim. Fades own the alpha field
-//! only (they write through `with_alpha`), so shade rides through appear/despawn/zoom feathering.
-//!
-//! **The descendant tree is a TRANSFORM relation, not a light one, and the difference is a bug we
-//! shipped** (B373). A WMO-display GameObject's doodad props — a transport's cabin furniture — are
-//! parented under the net entity so they sail with the deck (decision 0474), but their light is
-//! their own baked MODD colour folded into an SH probe, the reference's `CMapDoodadDef` provider
-//! (`0x6a8050`) rather than the WENTITY node this file models. They were nonetheless in the walk,
-//! and since the shade byte overlaps the probe slot in bits 6..=13, every one of them was pushed
-//! onto a *different* probe: a neighbouring prop's light where the renamed index happened to be
-//! live, and an unallocated — zeroed — row where it was not, which draws solid black. Both write
-//! sites now ask [`probe_payload`], the payload question rather than the classifier question.
+//! [`GroundShade`] sits on the net entity root (the `[obj+0xe0]` node) and its byte goes to every
+//! M2 part below it, so a held weapon dims with its wielder: the reference lights attachments from
+//! the owner's node.
 
 use benilla_assets::AdtTile;
 use bevy::mesh::MeshTag;
@@ -59,99 +21,53 @@ use crate::interior::{classify_entity_interior, InteriorLit};
 use crate::mesh_tag::{exterior_payload, shade_of, with_shade, InteriorProbePayload};
 use crate::terrain_stream::{doodad_ground_shade, ShadeResolve, TerrainStreamer};
 
-// Decision 0354 generalized this file from "the MCSH ground-shade byte" to the entity light
-// node's CPU ramp pair: `t` (the intensity chase — the tag byte the exterior SH lane scales by)
-// and the ambient word chase the interior bake fold consumes. The MCSH sample now only picks the
-// OUTDOOR target; the classifier's interior verdict overrides it with the day/night point.
-
-/// How fast the shade mix `t` (0 = intensity 2.5, 1 = 0.5) moves toward its target: the binary's
-/// linear step `[0x810808] = 3.3333` **intensity-units/s**, expressed on `t` by dividing by the 2.0-wide
-/// span the mix covers. The rate is on the intensity axis and is unchanged by [`LIT_T`] — what 0821
-/// changed is the *distance travelled* (1.0 → 0.5 rather than 2.5 → 0.5), so a lit→shaded transition
-/// now takes 0.15 s of fully visible movement instead of 0.6 s that was 75 % invisible.
+/// The rate of `t` (0 = intensity 2.5, 1 = 0.5): the reference's linear step `[0x810808]` =
+/// 3.3333 intensity units/s over the mix's 2.0-wide span.
 const SHADE_RAMP_PER_SEC: f32 = 3.3333 / 2.0;
 
-/// Squared distance (yd²) the root must move before the MCSH bit is re-sampled — same gate as the
-/// interior classifier: a standing NPC costs a position compare and nothing else. (MCSH texels are
-/// ~0.5 yd, so half a yard of hysteresis is at the sample's own resolution.)
+/// Squared distance (yd²) a root moves before the MCSH bit is re-sampled, about one MCSH texel.
 const RESAMPLE_DIST_SQ: f32 = 0.25;
 
-/// The ambient word's ramp rate — the binary's `[0x810804] = 2.0` colour-units/s (`0x69e770`'s
-/// FIRST chase, `[+0x9c]` → `[+0xf4]`; wow-re `unit-light-combine-storm.md` c3 — the intensity
-/// chase runs at its own 3.3333).
+/// The ambient word's rate, `[0x810804]` = 2.0 colour units/s (`[+0x9c]` → `[+0xf4]`).
 const AMBIENT_RAMP_PER_SEC: f32 = 2.0;
 
-/// The shade mix `t` encoding the DAY/NIGHT intensity 1.0: `intensity = mix(2.5, 0.5, t)` ⇒
-/// `t = 0.75`. **Two distinct reference mechanisms land on this same value** and only ONE of them is
-/// modelled here, so keep them apart if either moves: the live one is an indoor entity's node target
-/// (the interior `[+0xf8] = 1.0`, written at `69e36b` behind the `[+0xc]&2` interior gate); the other
-/// is `0x672a20`'s null-node fallback for an unregistered unit (no intensity multiply at all), which
-/// 0814 records as real but deliberately unmodelled. A value shared by a live law and a shelved one is
-/// exactly how 0809 talked itself into pinning every unit here.
+/// `t` at the day/night intensity 1.0, an indoor node's target (`[+0xf8]` = 1.0 at `0x69e36b`,
+/// behind the `[+0xc] & 2` interior gate). The unregistered fallback's ×1.0 is another law.
 const DAYNIGHT_T: f32 = 0.75;
 
-/// The LIT outdoor target (decision 0821). The reference's lit target is intensity **2.5**, and this is
-/// **1.0** — not because the 2.5 is wrong, but because our shader cannot express it: `wow_model.wgsl`
-/// caps the gain with `min(intensity, 1.0)`, so every value from 2.5 down to 1.0 renders *identically*.
-///
-/// **Clamp the TARGET, not the gain.** With the cap on the gain, `t` ramped 0 → 1 over 0.6 s while the
-/// first 0.75 of that journey (0.45 s) was pinned at 1.0 and therefore **invisible** — the shade change
-/// read as a dead pause followed by a snap, which is what the director reported walking from sun into
-/// shade ("delayed by ~1 s"). Aiming the chase at the value the renderer can actually show removes the
-/// invisible stretch without touching a single rendered pixel of the settled states: lit still commits
-/// 1.0 (the cap was already delivering that) and shadowed still commits 0.5.
-///
-/// This is therefore a faithful ramp over an unfaithful *range*, and the range is the open item: **the
-/// day the `min(I, 1)` cap is lifted, this constant goes back to 0.0** and the full 2.5 → 0.5 sweep
-/// becomes visible on its own. The two must move together — see 0821, and 0803 §3 for why the cap is
-/// still there.
+/// Deviation: the lit outdoor target is intensity 1.0, not the reference's 2.5, because
+/// `wow_model.wgsl` caps the intensity at 1.0 (`min(I, 1)`) and a chase through the capped span
+/// would stall unseen. Back to 0.0 together with lifting that cap.
 const LIT_T: f32 = 0.75;
 
-/// Settled-ramp epsilon (on `t` and each ambient channel) — under half a tag/colour byte.
+/// The settled-ramp epsilon on `t` and each ambient channel, under half a byte.
 const RAMP_EPS: f32 = 1.0 / 640.0;
 
-/// The per-entity light-node state, on the net entity **root** (unit / player / GameObject) — the
-/// CPU twin of the reference's per-object light node (decision 0354): the intensity chase
-/// (`[+0xa4]`→`[+0xf8]`, held as the normalized mix `t` over the 2.5→0.5 span) and the ambient
-/// word chase (`[+0x9c]`→`[+0xf4]`) — the pair `0x69e770` steps every frame.
+/// An entity root's light node, the chase pair `0x69e770` steps each frame: intensity
+/// (`[+0xa4]` → `[+0xf8]`, held as `t`) and the ambient word (`[+0x9c]` → `[+0xf4]`).
 #[derive(Component)]
 pub struct GroundShade {
-    /// Current shade mix (1 = intensity 0.5; [`LIT_T`] = the lit 1.0 our shader can express, and also
-    /// [`DAYNIGHT_T`]'s day/night 1.0 — the two coincide while the gain cap stands) — what the
-    /// parts' tags show, and what the interior bake fold scales its diffuse word by.
+    /// The mix, 1 being intensity 0.5: the parts' tag byte and the bake fold's diffuse scale.
     t: f32,
-    /// Where `t` is ramping to ([`LIT_T`]/1 from the last MCSH sample outdoors; [`DAYNIGHT_T`] indoors).
+    /// The last MCSH sample's target, [`LIT_T`] or 1.
     target: f32,
     /// Root position at the last sample (the movement gate).
     last_pos: Vec3,
-    /// Whether the first sample landed (it snaps `t = target`; a spawn never plays a ramp-in).
+    /// Whether the first sample landed; it snaps `t`, so a spawn never ramps in.
     sampled: bool,
-    /// The interior verdict, published by the classifier (`crate::interior`) — indoors the MCSH
-    /// sample is overridden by the day/night target ([`DAYNIGHT_T`]).
+    /// The interior classifier's verdict; indoors [`DAYNIGHT_T`] overrides the MCSH sample.
     pub(crate) indoor: bool,
-    /// Standing on an outdoor-class WMO surface (street/deck/porch — `MOGI & 0x48`), published by
-    /// the classifier: the MCSH verdict of the terrain BENEATH the building is overridden by the
-    /// lit target ([`LIT_T`]; the reference's own value here is intensity 2.5) — byte-verified
-    /// (0477/0480, wow-re `unit-wmo-mcsh-gate.md`):
-    /// the down-ray attach's WMO branch sets the skip-shadow bit `[node+0xd]|=0x2` (`0x6a8bc7`,
-    /// every node subclass), the terrain branch clears it (`0x6a8bed`), and the exterior intensity
-    /// leg commits the constant 2.5 whenever it's set (`0x69e483`→`0x69e4ad` — the MCSH sample
-    /// runs only terrain-linked). `self.target` keeps the raw sample so stepping off onto real
-    /// terrain resumes from it.
+    /// On an outdoor-class WMO surface (`MOGI & 0x48`), the lit target overrides the MCSH: the
+    /// reference's WMO down-ray sets skip-shadow `[node+0xd] |= 0x2` (`0x6a8bc7`, cleared on
+    /// terrain at `0x6a8bed`), and the exterior leg then commits 2.5 (`0x69e483` → `0x69e4ad`).
     pub(crate) on_wmo: bool,
-    /// The ramped ambient word (0..1 per channel) — the bake fold's ambient input, chasing
-    /// [`Self::ambient_target`] at [`AMBIENT_RAMP_PER_SEC`]. Seeded by the classifier on bake
-    /// entry (from the scene ambient, so walking into a warm room ramps rather than pops).
+    /// The ramped ambient word (0..1 per channel), the bake fold's input; the classifier seeds it.
     pub(crate) ambient: Vec3,
     pub(crate) ambient_target: Vec3,
-    /// The last effective target the `WOW_INTERIOR_LOG` instrument printed (log-on-change; starts
-    /// off-scale so the first resolved target always prints).
+    /// The last target `WOW_INTERIOR_LOG` printed; starts off-scale so the first one prints.
     logged_target: f32,
-    /// The shade byte the descendant walk last pushed to this root's parts — the settled gate
-    /// (1490): while it matches this frame's byte and no other lane rewrote a part's tag (the
-    /// reclaim detector in [`update_ground_shade`]), the walk is skipped whole. `None` = the
-    /// parts are not known to carry any byte — fresh, or hidden by the election (a wake must
-    /// re-assert even at an unchanged byte).
+    /// The byte the walk last pushed to the parts; while it matches and no other lane rewrote a
+    /// tag, the walk is skipped. `None` when fresh or hidden, so a wake re-asserts.
     asserted: Option<u8>,
 }
 
@@ -173,18 +89,13 @@ impl Default for GroundShade {
 }
 
 impl GroundShade {
-    /// The node's current committed intensity (`[node+0xa4]`): 2.5 lit → 0.5 MCSH-shadowed, the
-    /// day/night 1.0 at [`DAYNIGHT_T`] — the bake fold multiplies its diffuse word by this.
+    /// The committed intensity (`[node+0xa4]`), which the bake fold multiplies its diffuse word by.
     pub(crate) fn intensity(&self) -> f32 {
         2.5 - 2.0 * self.t
     }
 
-    /// The intensity chase's EFFECTIVE target: indoors the day/night point overrides the MCSH
-    /// verdict; on an outdoor-class WMO surface the LIT point overrides (`self.target` keeps the raw
-    /// sample, so a root stepping back onto terrain resumes from it); otherwise the MCSH verdict
-    /// stands, for a unit exactly as for a GameObject — the target law is byte-shared and single-site
-    /// (`69e4ad`/`69e496`, wow-re `unit-mcsh-shadow-target.md` §1) and we model the registered
-    /// delivery that consumes it (0814).
+    /// The chase's target: day/night indoors, lit on a WMO surface, else the kept MCSH sample, for
+    /// a unit as for a GameObject (one law, `0x69e4ad`/`0x69e496`).
     fn effective_target(&self) -> f32 {
         if self.indoor {
             DAYNIGHT_T
@@ -195,64 +106,35 @@ impl GroundShade {
         }
     }
 
-    /// Whether both chases sit on their targets — the classifier's refold gate (a Bake anchor
-    /// keeps refolding its owned probe while either ramp moves). Compares against the EFFECTIVE
-    /// intensity target: an indoor unit over MCSH-shadowed terrain (any unit inside a building —
-    /// buildings bake their own footprint shadow) settles at the day/night point, and comparing
-    /// the raw MCSH sample here kept every settled indoor Bake unit refolding forever.
+    /// Whether both chases sit on their effective targets, the classifier's refold gate.
     pub(crate) fn ramps_settled(&self) -> bool {
         (self.t - self.effective_target()).abs() < RAMP_EPS
             && (self.ambient - self.ambient_target).abs().max_element() < RAMP_EPS
     }
 
-    /// Bake-entry seed (the classifier, on a lane change INTO the footprint bake): the ambient
-    /// chase starts from the scene ambient the entity was just lit by, targeting the floor's
-    /// cap-96 word — the reference's node carries its ramped `[+0x9c]` across the leg flip.
+    /// Seed the ambient chase on entering the footprint bake, from the scene ambient toward the
+    /// floor's cap-96 word, as the reference's node carries `[+0x9c]` across the leg flip.
     pub(crate) fn seed_ambient(&mut self, from: Vec3, target: Vec3) {
         self.ambient = from;
         self.ambient_target = target;
     }
 }
 
-/// **This part's light is its own `CMapDoodadDef`'s, not any ancestor entity's light node** — a
-/// WMO doodad prop spawned onto a streamed GameObject (a transport's deck cargo and its cabin
-/// furniture, `entities::wmo_props`). This file's walk must pass it by whichever payload it is on.
-///
-/// **The reference proves the node cannot reach it** (wow-re
-/// `models/scratch/transport-wmo-doodad-light.md`, 2026-09-06, VERIFIED at the bytes): a
-/// transport's WMO is linked into the SAME global `TSExplicitList<CMapObjDef>` (`0xca7d98`) the
-/// WMO scene walk iterates — there is no separate GameObject WMO band — so its MODD entries are
-/// ordinary doodad defs. And `[def+0xa4]`, the sun scale this file's byte models, has exactly
-/// FOUR writers image-wide: the ctor `0x6a7d73` (0.0), the WMO doodad-set commit `0x695bb3`
-/// (1.0), the ADT MDDF commit `0x6b01bb` (1.0), and the MCSH refresh `0x698cb4` (0.5). None of
-/// them is the light node: the 2.5-producer `0x69e280` is entered only from `0x671a73`/`0x69e913`
-/// and the ramp `0x69e770` only through the thunk `0x671a90`, whose callers all load `[obj+0xe0]`
-/// — a path a doodad def never takes. A transport has no M2 for a node to light at all
-/// (`0x5f80e0` returns 0 for the transport types).
-///
-/// So the faithful value is **1.0**, or 0.5 from a SINGLE MCSH sample at the doodad's own
-/// footprint — `0x698c50` is a one-shot queue drain that unlinks each entry, so the verdict
-/// freezes at the pose the prop became resident at, and never ramps. Pushing the host's ramped,
-/// re-sampled byte onto these parts was a divergence (decision 2047, the other half of 2031).
+/// A WMO doodad prop on a streamed GameObject (a transport's cargo), lit by its own `CMapDoodadDef`
+/// (`0x6a8050`), never the host's light node, so the walk passes it by. In the reference a
+/// transport's WMO is in the global map-object list (`0xca7d98`), and a def's `[def+0xa4]` has four
+/// writers, none the node: `0x6a7d73` (0.0), `0x695bb3` and `0x6b01bb` (1.0), and `0x698cb4`
+/// (0.5), an MCSH sample taken once at residency (`0x698c50`).
 #[derive(Component)]
 pub struct DoodadDefLit;
 
-/// Roots owed a shade re-assert this frame even at an unchanged byte: some OTHER lane rewrote a
-/// descendant part's `MeshTag` since [`detect_shade_reclaims`] last ran — the interior
-/// classifier's exterior reclaim (1358), a late-attached part (`Added` counts as changed).
-/// What lets [`update_ground_shade`]'s per-part walk skip the settled crowd (1490): steady
-/// frames have no foreign tag writes, so this is empty and every settled drawn body costs the
-/// ramp arithmetic and one map insert.
+/// Roots owed a re-assert at an unchanged byte: another lane (the classifier's exterior reclaim, a
+/// newly added part) rewrote a part's `MeshTag` since [`detect_shade_reclaims`] ran.
 #[derive(Resource, Default)]
 pub(crate) struct ShadeDirtyRoots(bevy::ecs::entity::EntityHashSet);
 
-/// The reclaim detector — its own system because `Changed<MeshTag>` is read access and the
-/// walk's query holds `&mut MeshTag` (B0001). Runs between the classifier and the walk, so a
-/// same-frame reclaim is caught the frame it happens; a writer scheduled after the walk
-/// (a PostUpdate fade) is caught on the next frame, exactly when the old unconditional walk
-/// would have repaired it too. The walk's own writes land after this system's baseline and so
-/// echo back as dirty for ONE extra frame — that echo walk compares every byte equal, writes
-/// nothing, and the chain goes quiet; it cannot oscillate.
+/// Flag the root above every part whose `MeshTag` changed; its own system, since the walk holds
+/// `&mut MeshTag`. The walk's own writes echo back for one frame, which then writes nothing.
 pub(crate) fn detect_shade_reclaims(
     changed_parts: Query<Entity, (Changed<MeshTag>, Without<crate::billboard::BillboardCard>)>,
     shade_roots: Query<(), With<GroundShade>>,
@@ -273,13 +155,8 @@ pub(crate) fn detect_shade_reclaims(
     }
 }
 
-/// `WOW_SHADE_CENSUS=<secs>` (any unparseable value = 5): a periodic one-line count of the two
-/// populations this pass has to keep apart — every part carrying the doodad-def marker, and the
-/// tagged parts *under* a shade root with the marked subset called out. B373 (2031/2041/2047) is
-/// what made the pair worth counting: a transport's cabin prop sits under the boat's shade root
-/// and must NOT take the boat's light, so "under a root" and "marked" diverging is the whole
-/// diagnosis, and the two numbers moving together again is how a regression shows up. Zero-cost
-/// when off: one env read, once.
+/// `WOW_SHADE_CENSUS=<secs>` (unparseable: 5): a periodic count of the [`DoodadDefLit`] parts and
+/// of the tagged parts under a shade root, the marked ones among them.
 fn shade_census_every() -> Option<f32> {
     static EVERY: std::sync::OnceLock<Option<f32>> = std::sync::OnceLock::new();
     *EVERY.get_or_init(|| {
@@ -289,7 +166,7 @@ fn shade_census_every() -> Option<f32> {
     })
 }
 
-/// The `shade-census` printer (`WOW_SHADE_CENSUS=<secs>`) — see [`shade_census_every`].
+/// The `WOW_SHADE_CENSUS` printer.
 fn census_shade_marks(
     marked: Query<(), With<DoodadDefLit>>,
     roots: Query<Entity, With<GroundShade>>,
@@ -328,9 +205,8 @@ pub(crate) struct EntityShadePlugin;
 
 impl Plugin for EntityShadePlugin {
     fn build(&self, app: &mut App) {
-        // After the interior classifier: its exterior reclaim writes a fresh tag (shade byte 0) the
-        // same frame this re-asserts the ramped byte, so the pair can't fight across frames. The
-        // detector sits between the two so the reclaim is observed the frame it happens.
+        // After the classifier, whose exterior reclaim writes shade byte 0 the same frame this
+        // re-asserts; the detector sits between them to see the reclaim that frame.
         app.init_resource::<ShadeDirtyRoots>().add_systems(
             Update,
             (
@@ -344,11 +220,8 @@ impl Plugin for EntityShadePlugin {
     }
 }
 
-/// Sample + ramp each shaded root, then push the byte to its parts' tags (change-gated per part).
+/// Sample and ramp each shaded root, then push its byte to its parts' tags.
 #[allow(clippy::type_complexity)]
-// A Bevy system's params are not an argument list to shorten — each is a distinct world access the
-// scheduler needs by name, and the card pass below deliberately takes its own disjoint `MeshTag`
-// query rather than smuggling one through a shared `ParamSet`.
 pub(crate) fn update_ground_shade(
     time: Res<Time>,
     streamer: Option<Res<TerrainStreamer>>,
@@ -358,14 +231,11 @@ pub(crate) fn update_ground_shade(
         &GlobalTransform,
         &mut GroundShade,
         Option<&crate::world_unit::ViewerUnit>,
-        // The election's verdict on this root (1270/1475) — `Option` because a fixed doodad's
-        // shade root carries no `Visibility` of its own and must keep walking.
+        // The election's verdict; `Option`, since a fixed doodad's shade root has no `Visibility`.
         Option<&Visibility>,
     )>,
     children: Query<&Children>,
-    // Parts are matched by carrying a `MeshTag`; a part whose payload is a PROBE SLOT is skipped,
-    // because the shade byte lives in the same bits (see [`probe_payload`]). Fading parts are NOT
-    // skipped — shade and fade own disjoint fields.
+    // A fading part is walked (shade and fade own disjoint fields); a probe-slot one is not.
     mut parts: Query<
         (
             &mut MeshTag,
@@ -375,10 +245,7 @@ pub(crate) fn update_ground_shade(
         ),
         Without<crate::billboard::BillboardCard>,
     >,
-    // A card is a world ROOT (the facing system owns its transform), so the descendant walk below
-    // cannot reach one — it carries its owner instead. Disjoint from `parts` by the filter above.
-    // It asks the same payload question: an interior prop's glow card carries its doodad's probe
-    // slot, and this pass reaches it by walking UP from the card's owner (B373).
+    // Cards are world roots the walk cannot reach; each resolves up from its owner instead.
     mut cards: Query<(
         &crate::billboard::BillboardCard,
         &mut MeshTag,
@@ -386,30 +253,20 @@ pub(crate) fn update_ground_shade(
         Has<InteriorProbePayload>,
         Has<DoodadDefLit>,
     )>,
-    // Reused across frames: each shaded ROOT → its shade byte this frame (a few hundred entries).
-    // The card pass walks `ChildOf` up to the nearest such root — this map used to record every
-    // descendant too (~10-20k inserts/frame) so that walk could be a single lookup.
+    // Each shaded root's byte, kept across frames (entity ids are generational).
     mut root_shade: Local<bevy::ecs::entity::EntityHashMap<u8>>,
-    // The card pass's up-walk: a card can follow a deep JOINT (`following_joint` — the swinging
-    // lamp's glow), and a joint is not a shade root.
+    // The card pass's up-walk: a card can follow a deep joint, which is not a shade root.
     child_of: Query<&ChildOf>,
-    // The reclaim detector's verdict ([`detect_shade_reclaims`], one stage earlier): roots owed
-    // a re-assert even at an unchanged byte.
     dirty_roots: Res<ShadeDirtyRoots>,
     mut self_log: Local<f32>,
 ) {
-    // The map persists across frames (decision 1979): a settled root's byte is already in it,
-    // and re-inserting ~1.3 k entries a frame was the walk's cost. A despawned root's entry is
-    // dead weight nothing reads — entity ids are generational, so a reuse never aliases it.
     let Some(streamer) = streamer else {
         return;
     };
     let step = SHADE_RAMP_PER_SEC * time.delta_secs();
     let ambient_step = AMBIENT_RAMP_PER_SEC * time.delta_secs();
     for (root, gt, shade, is_self, root_vis) in &mut roots {
-        // `WOW_INTERIOR_LOG=1`: a periodic SELF-node dump (every 3 s) — the probe run's definitive
-        // "what state is the parked character actually in" line, attributable unlike the
-        // change-triggered `[node]` lines below (wandering NPCs fire those constantly).
+        // `WOW_INTERIOR_LOG=1`: the viewer's own node state every 3 s.
         if is_self.is_some() && time.elapsed_secs() - *self_log > 3.0 && interior_log_enabled() {
             let p = gt.translation();
             eprintln!(
@@ -426,35 +283,24 @@ pub(crate) fn update_ground_shade(
             );
             *self_log = time.elapsed_secs();
         }
-        let shade = shade.into_inner(); // one deref; field writes below are unconditional-cheap
+        let shade = shade.into_inner();
         let pos = gt.translation();
-        // Re-sample the MCSH bit only on real movement (or the very first pass) — the global
-        // world→tile→chunk lookup is cheap, but a town of standing NPCs shouldn't run it per frame.
         if !shade.sampled || pos.distance_squared(shade.last_pos) >= RESAMPLE_DIST_SQ {
             match doodad_ground_shade(&streamer, &adt_tiles, pos) {
                 ShadeResolve::Ready(shadowed) => {
                     shade.target = if shadowed { 1.0 } else { LIT_T };
                     shade.last_pos = pos;
                     if !shade.sampled {
-                        // First landing: snap — an entity spawns already at its ground's shade
-                        // (the appear-fade covers the arrival; a ramp-in from lit would read as a
-                        // lighting pop right after materializing).
                         shade.t = shade.effective_target();
                         shade.sampled = true;
                     }
                 }
-                // The tile under the entity is requested but still decoding — keep the last state
-                // and retry next frame (mirrors the doodad spawn's deferral).
+                // The tile is still decoding: keep the last state and retry next frame.
                 ShadeResolve::Pending => {}
             }
         }
-        // Indoors the MCSH sample is moot: the day/night intensity target is 1.0 (the reference's
-        // interior `[+0xf8]`, decision 0354). The sample above still ran its movement gate, so
-        // stepping back outside resumes from a fresh MCSH verdict.
         let target = shade.effective_target();
-        // `WOW_INTERIOR_LOG=1`: one line whenever a node's intensity target moves — the live
-        // instrument for "which stage is this character actually in?" — MCSH-shadowed 0.5 ⇒ t 1;
-        // exterior lit and day/night both ⇒ t 0.75 / committed 1.0 while the gain cap stands (0821).
+        // `WOW_INTERIOR_LOG=1`: a line whenever a node's target moves.
         if (target - shade.logged_target).abs() > f32::EPSILON && interior_log_enabled() {
             eprintln!(
                 "[node] root {root:?} at ({:.1}, {:.1}, {:.1}) -> target t {target:.2} \
@@ -468,8 +314,7 @@ pub(crate) fn update_ground_shade(
             );
             shade.logged_target = target;
         }
-        // The reference ramps: linear toward the target, never past it — intensity (as the mix
-        // `t`) at 3.3333/s over its span, the ambient word at 2.0/s per channel (`0x69e770`).
+        // Linear toward the target, never past it (`0x69e770`).
         shade.t = if shade.t < target {
             (shade.t + step).min(target)
         } else {
@@ -483,45 +328,31 @@ pub(crate) fn update_ground_shade(
             ramp_toward(a.z, at.z, ambient_step),
         );
         let byte = (shade.t * 255.0).round().clamp(0.0, 255.0) as u8;
-        // Every root enters the card map, hidden or not — the insert is one hash write, and a
-        // hidden body's card used to walk its whole parent chain to a `None` precisely because
-        // its root was left out.
+        // Before the hidden skip: a hidden body's card must still find its root here.
         if root_shade.get(&root) != Some(&byte) {
             root_shade.insert(root, byte);
         }
-        // A root the election hid (1270/1475) draws nothing, so the re-assert walk below is
-        // skipped whole — 1473's audit found it running over every part of every off-view body.
-        // The ramps above kept stepping, so the byte is current the frame the body wakes; the
-        // cleared `asserted` is what makes the wake frame's walk unconditional, into parts
-        // whose tags retained their last byte.
+        // A hidden root skips the walk; its ramps kept stepping, and the cleared `asserted` makes
+        // the wake frame's walk unconditional.
         if root_vis.is_some_and(|v| *v == Visibility::Hidden) {
             shade.asserted = None;
             continue;
         }
-        // The settled gate (1490): every part below already carries this byte (we pushed it —
-        // `asserted`) and no other lane rewrote a tag since (`dirty_roots`). The walk used to be
-        // unconditional for a drawn root as the MeshTag re-assert over the classifier's
-        // exterior reclaim (1358); the reclaim detector above answers that by observation
-        // instead of by re-walking every body every frame.
+        // Settled: every part already carries this byte and no other lane rewrote a tag since.
         if shade.asserted == Some(byte) && !dirty_roots.0.contains(&root) {
             continue;
         }
         shade.asserted = Some(byte);
-        // Push to every part below the root (body submeshes are direct children; held items/helm ride
-        // joint entities deeper down — same full-tree walk as the self-fade). Change-gated per part on
-        // the byte, so a settled entity writes nothing and never re-triggers render extraction.
+        // Every part below the root, held items on deeper joints included, written on a change.
         for part in children.iter_descendants(root) {
             let Ok((mut tag, lit, own_probe, own_def)) = parts.get_mut(part) else {
                 continue;
             };
-            // Two reasons this walk passes a part by, and they are different questions.
-            // OWNERSHIP: a WMO doodad prop is lit by its own def, never by the node above it
-            // (`DoodadDefLit`) — it is only in this tree so it rides a moving transport.
+            // A WMO doodad prop, lit by its own def, is in this tree only to ride a transport.
             if own_def {
                 continue;
             }
-            // PAYLOAD: asked the only way the shade accessors can be reached
-            // (`mesh_tag::exterior_payload`); `None` = this part's bits 6..=18 are a probe slot.
+            // `None`: this part's bits 6..=18 hold a probe slot.
             let Some(ext) = exterior_payload(lit.is_some_and(InteriorLit::is_bake), own_probe)
             else {
                 continue;
@@ -531,18 +362,10 @@ pub(crate) fn update_ground_shade(
             }
         }
     }
-    // The cards (0788's loose end). A card belongs to the same light node as the body it hangs off —
-    // the reference shades every batch of an object through one node (0778) — but it is a world root,
-    // so the walk above skips it and it kept the lit rung while its owner dimmed. 0811 scoped this to
-    // GameObjects because 0809 had pinned units flat; 0814 put units back on the chase, so it is once
-    // again every carried card — a torch's flame card dims with the hand that holds it. The owner (an
-    // anchor or a deep joint) resolves to the NEAREST shaded root above it: with nested roots (a
-    // mounted unit — rider and mount each carry a node) that is the mount's, matching the
-    // one-node-per-object structure above; the old whole-tree map made this pick last-writer-wins.
+    // The cards: the reference shades every batch of an object through one node, so a card takes
+    // the nearest shaded root above its owner (on a mounted unit, the mount's).
     for (card, mut tag, lit, own_probe, own_def) in &mut cards {
-        // Both questions again, and a card needs them at least as much: it is a world ROOT, so
-        // this pass finds its owner by walking UP — which is how a deck lantern's glow card and a
-        // cabin prop's alike reached the host GameObject that does not light them (B373, 2047).
+        // As in the walk: walking up, a prop's card would reach a host that does not light it.
         if own_def {
             continue;
         }
@@ -550,7 +373,7 @@ pub(crate) fn update_ground_shade(
             continue;
         };
         let Some(byte) = card_root_shade(&root_shade, &child_of, card.follows()) else {
-            continue; // a fixed terrain doodad's card — its shade rides the material selector
+            continue; // a fixed terrain doodad's card: its shade rides the material selector
         };
         if shade_of(tag.0, ext) != byte {
             tag.0 = with_shade(tag.0, byte, ext);
@@ -558,9 +381,7 @@ pub(crate) fn update_ground_shade(
     }
 }
 
-/// The shade byte a card inherits: the NEAREST shaded root at or above `follows` (the owner itself
-/// first, then the `ChildOf` chain). `None` — no owner, or no shaded root over it — skips the card,
-/// exactly as the old whole-tree map's miss did.
+/// The byte of the nearest shaded root at or above `follows`, the owner itself first.
 fn card_root_shade(
     root_shade: &bevy::ecs::entity::EntityHashMap<u8>,
     child_of: &Query<&ChildOf>,
@@ -575,14 +396,13 @@ fn card_root_shade(
     }
 }
 
-/// `WOW_INTERIOR_LOG=1` — the interior/shade instrument lines. Resolved once: the raw env read ran
-/// per root per frame.
+/// `WOW_INTERIOR_LOG=1`: the interior and shade instrument lines, read once.
 fn interior_log_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_INTERIOR_LOG").is_some())
 }
 
-/// One linear ramp step toward a target, never past it (the binary's clamp-no-overshoot chase).
+/// One linear step toward a target, never past it, as the reference's chase.
 fn ramp_toward(v: f32, target: f32, step: f32) -> f32 {
     if v < target {
         (v + step).min(target)
@@ -603,10 +423,6 @@ mod tests {
         card_root_shade(map, &state.get(world), follows)
     }
 
-    /// The reclaim detector's tick contract (1490): a fresh part flags its root (Added counts
-    /// as changed); a quiet frame flags nothing; a foreign tag write flags the root again — and
-    /// only the root above the touched part, not every root in the world. This is what lets
-    /// the shade walk skip the settled crowd without ever missing 1358's exterior reclaim.
     #[test]
     fn a_foreign_tag_write_flags_exactly_its_root() {
         let mut app = App::new();
@@ -636,9 +452,6 @@ mod tests {
         );
     }
 
-    /// A card's owner can sit arbitrarily deep in its root's tree (a held torch's flame card
-    /// follows a hand JOINT under an item entity under the unit) — the up-walk finds the root's
-    /// byte; the root itself, as an owner, is the walk's zero-hop case.
     #[test]
     fn a_card_takes_its_roots_byte_from_any_depth() {
         let mut world = World::new();
@@ -656,8 +469,6 @@ mod tests {
         );
     }
 
-    /// No owner (a fixed terrain doodad's card), and an owner whose ancestor chain holds no shaded
-    /// root (a card of something this system doesn't shade) — both skip, like the old map miss.
     #[test]
     fn an_unshaded_card_is_skipped() {
         let mut world = World::new();
@@ -673,15 +484,8 @@ mod tests {
         );
     }
 
-    /// **The payload question, both populations** (B373). The guard used to ask "is this part on
-    /// the classifier's Bake law", which is only one of the two ways a `MeshTag` comes to hold a
-    /// probe slot; a WMO doodad prop holds one from spawn and carries no `InteriorLit` at all.
-    /// A transport's cabin furniture is where the second population lands inside an entity's
-    /// descendant walk, and every one of those props drew under a foreign probe.
-    ///
-    /// The question now lives in `mesh_tag` beside the bits it is about, and the shade accessors
-    /// take its answer as a witness — so this test is about the two populations, not about a
-    /// caller remembering to ask, which the type system now handles.
+    /// A tag holds a probe slot on the classifier's Bake law, or from spawn on a WMO doodad prop,
+    /// which carries no `InteriorLit`.
     #[test]
     fn either_probe_population_denies_the_shade_writer_its_witness() {
         assert!(
@@ -702,9 +506,7 @@ mod tests {
         );
     }
 
-    /// Nested shade roots — a mounted unit: rider root and mount root each carry a node, the mount
-    /// a descendant of the rider. A card under the MOUNT takes the mount's byte (the nearest root),
-    /// pinned here because the old whole-tree map answered this by insert order.
+    /// A mounted unit: the mount's shade root is a descendant of the rider's.
     #[test]
     fn a_nested_root_wins_by_nearness() {
         let mut world = World::new();
diff --git a/crates/benilla-world/src/exterior_cull.rs b/crates/benilla-world/src/exterior_cull.rs
index 5e09ba85..0d07d62b 100644
--- a/crates/benilla-world/src/exterior_cull.rs
+++ b/crates/benilla-world/src/exterior_cull.rs
@@ -1,123 +1,34 @@
-//! **The exterior scene draws only through doorways you can see.**
+//! The exterior scene draws only through the doorways the camera can see.
 //!
-//! Standing inside a WMO interior, the reference does not draw the outdoor world at large — it draws
-//! it once per *portal window* left over by the interior portal flood, with the view frustum narrowed
-//! to that window. We drew it unconditionally, which is why a hillside tree 200 yd outside Stratholme
-//! showed through the city's walls (the director's report; wow-re
-//! `system/terrain/scratch/interior-exterior-scene-cull.md`, decision 0774).
+//! The reference's scene driver `0x681070` branches at `0x681101` on the camera's map object
+//! `[0xc7b748]` (0 outdoors). Outdoors (`0x6811ca`) it runs the populate walk `0x682fa0` once, on
+//! the full-screen rect `{0, 0, 1, 1}` ([`ExteriorWindows::Unrestricted`]); inside (`0x681120`) it
+//! runs it once per window of the portal flood's worklist (`[0xcbe320]` of them, copied to
+//! `0xc7cb7c`), the frustum narrowed to each, and `0x681199` skips it at zero, so a sealed room
+//! draws no exterior. `0x682fa0` is the only producer of ADT terrain (`0x683bf0`), ADT doodads
+//! (`0x683700`), the second placement walk (`0x683340`), world WMOs (`0x6856c0`), liquid
+//! (`0x683ab0`) and the far band (`0x683040`).
 //!
-//! ## The carved law
+//! Bodies ride the same walk: `0x683dd0` elects every scene object each frame, and pass 2
+//! (`0x710c50`, `[model+0x50] = 0`) is neither drawn nor ticked. Outdoor objects reach pass 1 only
+//! through `0x683340` (inside `0x682fa0`), which frustum-tests each one, so a sealed room sends
+//! them all to pass 2 (`0x680390`). An object in a WMO group rides `0x6834e0`, which submits a
+//! group's members only while the group renders, frustum-testing each: an in-room body draws when
+//! its room, or one a portal hop away (our doorway-straddle guard), is in the PVS and its box is
+//! in view. `WOW_NO_DRAW_ELECTION=1` keeps only the window leg. The horizon-occlusion term
+//! (`0x686000`) is not built.
 //!
-//! The world-scene driver `0x681070` branches at `0x681101` on `[0xc7b748]`, the camera-containing map
-//! object (0 = outdoors):
+//! Per window the reference bilerps the camera's corner rays (`0xc7bcd8`) into 6 planes
+//! (`0x6865f0`→`0x686640`): a sub-frustum over the portal chain's screen-space AABB, tested per
+//! object on the whole AABB (`0x682f40`), with no scissor or clip plane. Here the rect is a scale
+//! and offset on clip space, and [`Frustum::from_clip_from_world`] extracts the same planes.
 //!
-//! - **Outside leg** (`0x6811ca`): one populate walk `0x682fa0` against the literal full-screen rect
-//!   `{0, 0, 1, 1}` — the ordinary frustum. [`ExteriorWindows::Unrestricted`].
-//! - **Inside leg** (`0x681120`): the flood leaves a deferred window worklist (count `[0xcbe320]`,
-//!   records `0xcbe324`, stride `0x14`), which the driver `rep movsd`s into `0xc7cb7c` (`0x68118b`)
-//!   and then walks **once per window** (`0x682fa0`), frustum narrowed to that window's rect.
-//!   **`0x681199 jbe 0x681204` skips the entire walk when the count is zero** — a sealed room draws no
-//!   exterior at all.
+//! Terrain is tagged per 33.333 yd MCNK cell: a 533 yd tile around the camera reaches every
+//! window's side of the view. The far band keeps its whole-tile box, the reference's far tier.
 //!
-//! `0x682fa0` is the *only* producer for every exterior bucket — ADT terrain (`0x683bf0`), ADT doodads
-//! (`0x683700`), the second placement walk (`0x683340`), world WMO placements (`0x6856c0`), all three
-//! liquid layers (`0x683ab0`) and the far band (`0x683040`) — and each drain unlinks what it walks. So
-//! "no window" really does mean "no exterior content", with no second path to leak through.
-//!
-//! ## Bodies ride the same walk — the correction 0774 needed (decision 1270)
-//!
-//! 0774 read this lane one stage too late and wrote the opposite: *"units are exempt and must stay
-//! exempt … the reference submits outdoor mobs from a sealed room and lets the building's own
-//! geometry z-reject them."* The **drain** fact it checked is true — `0x483460`/`0x48368a` walk the
-//! M2Scene worklist with zero references to `[0xc7b748]`/`[0xcbe320]` — but the decision is taken
-//! *before* the worklist, in the driver that does read them.
-//!
-//! Every frame `0x683dd0` (sole caller `0x6812c5`, inside `0x681070`) elects each scene object into
-//! one of two passes: `[record+0xb4]` is `0x481540` and nothing else (that dword occurs once
-//! image-wide, at `0x613ece`), and `CGObject::ShouldRender` is literally `0x6146c6: and eax,1`.
-//! Pass 2 takes `0x48161f je` → `0x48174e call 0x710c50`, which writes `[model+0x50] = 0`: the model
-//! never enters `[scene+0x24]`, the only list the draw loop `0x707680`/`0x707882` walks — and walk 2
-//! also skips `0x710b90`, so a pass-2 object is neither drawn nor ticked.
-//!
-//! **List A's only outdoor producer is `0x683340`, whose only caller is `0x682fe2` — inside
-//! `0x682fa0`**, the per-window exterior walk above. A sealed room never runs it, so `0x680390`
-//! sweeps every outdoor object in the world into pass 2. Nothing is submitted, so there is nothing
-//! for the building's geometry to z-reject: 0774's second claim fails in both halves. An object
-//! standing in a WMO group rides the sibling `0x6834e0` instead, which is why a creature in the
-//! camera's own room still draws.
-//!
-//! So a body is exterior scene exactly when it is not in a WMO room, and the windows gate it like
-//! the ground it stands on — [`WorldUnit::bound`].
-//!
-//! **The outdoor half of the same election (decision 1475).** The reference's OUTSIDE leg is not a
-//! stand-down — it is one full-screen window through the same walk (`0x6811ff`), whose producer
-//! `0x683340` frustum-tests every node; and the sibling in-room producer `0x6834e0` submits a
-//! group's members only when the group is rendered, frustum-testing each. So outdoors a body's
-//! bound is tested against the camera's own view volume, and an in-room body draws only when its
-//! room (one portal hop padded — the doorway-straddle guard) is in the PVS *and* its box is in
-//! view. 1270 §6 deferred this half; 1473's audit is why it landed. `WOW_NO_DRAW_ELECTION=1` is
-//! the lever back to the window leg alone. Knowingly absent: the horizon-occlusion term
-//! (`0x686000`) — its own machinery, its own record.
-//!
-//! ## The clip geometry
-//!
-//! Per window, the reference bilerps the camera's four global corner rays (`0xc7bcd8`) by the window's
-//! rect into 8 corners, and `0x6865f0`→`0x686640` builds **6 planes** from them. So the clip volume is
-//! a **sub-frustum whose cross-section is the portal's screen-space AABB** (accumulated along the
-//! portal chain), *not* its polygon — and the test is **per object, whole AABB** (`0x682f40`), never
-//! per primitive. There is no scissor rect and no user clip plane anywhere on the path: a doodad
-//! straddling the doorway edge is drawn **whole**, and the silhouette comes from the interior geometry
-//! in front of it.
-//!
-//! We build the same volume the cheap way: an NDC rect is a scale+offset on clip space, so
-//! `sub_clip_from_world = rect_to_ndc * clip_from_world` and Bevy's own
-//! [`Frustum::from_clip_from_world`] extracts the identical 6 planes. That keeps us on one
-//! plane-extraction implementation instead of a private corner-ray port.
-//!
-//! Windows narrower than [`MIN_WINDOW_NDC`] in either axis are dropped **on this walk** — the
-//! reference's reject is the first thing `0x682fa0` does, before it touches a bucket, and it is
-//! non-strict (`>= 0.01` of the 0..1 screen passes). It belongs to the walk, not to the volume:
-//! `0x682930`, the builder the containing building's own Pass 2 shares, contains no comparison at
-//! all, so a doorway too narrow to admit a hillside can still admit a wall. That asymmetry is the
-//! reference's, and reproducing it is [`scene_window_frustum`] vs [`window_frustum`] (decision
-//! 1853).
-//!
-//! ## What is gated so far, and what is knowingly not
-//!
-//! **Gated:** ADT terrain (`0x683bf0`), ADT doodad placements (`0x683700`), the WDL far band
-//! (`0x683040`), the net **bodies** on `0x683340` ([`WorldUnit::bound`]), and open-world **liquid**
-//! (`0x683ab0`) — the buckets whose entities have no other `Visibility` writer, so this is their
-//! sole authority (decision 0025). World **WMO placements** (`0x6856c0`), their props and their
-//! MLIQ pools are gated too, but by the *model-visibility* authority, which folds [`ExteriorGate`]
-//! into its own AND rather than being written here (decision 0784).
-//!
-//! **Liquid was the last of them** (decision 1652). 0774 deferred it and 0784 deferred it again,
-//! both on the same stated ground — that it "already has a visibility authority… its own lane". It
-//! did not. An ADT surface is spawned as a world root with `Mesh3d`, and nothing ever wrote its
-//! `Visibility`; the only writer in the whole subsystem was the `$WOW_NO_LIQUID` kill-switch,
-//! env-gated and `Added`-filtered. So the fix was not the "real design step" both records
-//! predicted — it was the tag, and this system was already the right owner. The lesson is 0784's
-//! own, one turn later: *"it already has an authority" needs a check, not a memory.* 0774 made that
-//! claim about two buckets at once; it was true of WMO placements and false of liquid, and because
-//! the two travelled in one sentence, nobody separated them. 0784 checked the half it was closing,
-//! found the claim inverted there, and copied the other half forward untested. What that cost is
-//! the director's report — from inside a cavern, the lake overhead drawing straight through the
-//! ceiling.
-//!
-//! **The unit is the drawn object, and for terrain that is the 33.333 yd MCNK cell, not the 533 yd
-//! tile** (decision 0780). This is a property of the *spawner*, not of anything here — but the cull is
-//! where it bites: a tile-sized box always contains the camera's own ground, so it intersects every
-//! window and is admitted whichever way the doorway faces. The cull was correct and looked broken.
-//! The far band keeps its whole-tile box, which is the reference's own far-tier granularity.
-//!
-//! **NOT gated, knowingly:** the horizon-occlusion term (`0x686000`) — its own machinery, its
-//! own record. Nothing in the exterior *buckets* is left ungated.
-//!
-//! **Deviation to be honest about:** the reference tests one AABB per *object*; a doodad placement has
-//! no root entity in our graph, so we tag and test each **submesh**. Their union is the object, so the
-//! only divergence is at a doorway's edge — a submesh entirely outside the window is dropped where the
-//! reference would draw the doodad whole. Visible only as a partially-clipped prop in a doorway.
-//! A body does not take that deviation: it has a root, so it is tested once, whole ([`ElectedBody`]).
+//! Deviation: the reference tests one AABB per object, but a doodad placement has no root entity
+//! here, so its submeshes are tested one by one, and a submesh outside a doorway's window drops
+//! where the reference draws the doodad whole. A body has a root and is tested once.
 
 use bevy::camera::primitives::{Aabb, Frustum};
 use bevy::camera::visibility::VisibilitySystems;
@@ -126,20 +37,15 @@ use bevy::prelude::*;
 use crate::view::WorldCamera;
 use crate::wmo_portal::{ExteriorWindows, Rect, WmoPvsSet};
 
-/// A window narrower than this fraction of the screen in either axis is dropped — the reference's
-/// `0x682fa0` test against `[0x8029d0]` (0.01 of a 0..1 screen; our rects are NDC, so twice that).
+/// The open-world walk drops a window narrower than this in either axis: `0x682fa0` tests against
+/// `[0x8029d0]`, 0.01 of a 0..1 screen, which is 0.02 in NDC.
 const MIN_WINDOW_NDC: f32 = 0.02;
 
-/// Tag for a piece of the **exterior scene** — the content the window worklist gates. Put this on ADT
-/// terrain **chunks**, ADT doodad placements, the WDL far band, world WMO placements and open-world
-/// liquid. Tag the object that is *drawn*: this is tested per entity, so tagging a container whose box
-/// spans far more than any one draw admits the lot (decision 0780).
-///
-/// **Never on anything parented to a WMO group** — those are already culled by the portal PVS
-/// ([`crate::wmo_portal::WmoGroupVis`]), and double-gating them would blank building interiors.
-/// **Never on a net body either**, but for the opposite reason to the one this line used to give:
-/// a body IS elected (see the module header), it is simply elected once at its **root** off
-/// [`WorldUnit::bound`], rather than per submesh.
+/// Tag for exterior scene content, gated by the window worklist: ADT terrain cells, ADT doodad
+/// placements, the WDL far band, world WMO placements and open-world liquid, each on the drawn
+/// object, as a container's box admits everything in it. Never on anything parented to a WMO
+/// group, which the portal PVS already culls (a second gate would blank its interior), nor on a net
+/// body, which is elected once at its root off `WorldUnit::bound`.
 #[derive(Component)]
 pub struct ExteriorScene;
 
@@ -147,37 +53,24 @@ pub struct ExteriorScene;
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct ExteriorCullSet;
 
-/// What the cull actually did on its last run — the instrument that makes a "why is that still
-/// drawn?" report answerable without guessing. `windows` is the worklist it read (`None` =
-/// [`ExteriorWindows::Unrestricted`], the stand-down leg), `frusta` how many survived
-/// [`MIN_WINDOW_NDC`], and `tested`/`hidden` how many tagged objects it reached and rejected.
-///
-/// Its whole point is that `tested` is the number no other instrument can see: an object drawn
-/// through a wall while `hidden == tested` is an object the cull **never reached**, which is a
-/// different defect from one it reached and admitted.
+/// What the cull did on its last run: `windows` is the worklist it read (`None` outdoors),
+/// `frusta` how many survived [`MIN_WINDOW_NDC`], `tested`/`hidden` how many tagged objects it
+/// reached and rejected. An object drawn through a wall while `hidden == tested` is one the cull
+/// never reached.
 #[derive(Resource, Default, Clone, Copy)]
 pub struct ExteriorCullVerdict {
     pub(crate) windows: Option<usize>,
     pub(crate) frusta: usize,
     pub(crate) tested: usize,
     pub(crate) hidden: usize,
-    /// Tagged objects with **no `Aabb`**, which the fail-open arm below admits unconditionally.
-    /// Non-zero is not automatically a defect (a tagged non-drawing entity has no bound and draws
-    /// nothing), but it is the one number that says how much of the scene the cull is not deciding.
+    /// Tagged objects with no `Aabb`, admitted: the share of the scene the cull is not deciding.
     pub(crate) unbounded: usize,
-    /// Net bodies the election reached ([`WorldUnit::bound`] set), and how many the windows
-    /// rejected — counted apart from
-    /// `tested`/`hidden` because they answer a different question. The world buckets are a
-    /// *residency* count in the tens of thousands; bodies are the server's visibility stream, a
-    /// couple of dozen. Summed together, a body leg that reaches nothing at all would be invisible.
+    /// Net bodies the election reached, and how many it hid; kept apart from `tested`/`hidden`,
+    /// whose tens of thousands would hide a body leg that reached nothing.
     pub(crate) bodies: usize,
     pub(crate) bodies_hidden: usize,
-    /// Open-world liquid surfaces the cull reached, and how many the windows rejected — a
-    /// **subset** of `tested`/`hidden` above, reported separately for the reason the body leg is
-    /// (decision 1652). A tile carries a handful of MCNK liquid layers against ~250 terrain cells,
-    /// so a liquid leg that reached *nothing* would move `tested` by less than its own noise. This
-    /// is the number that says "the lake is being decided", and before 1652 it was structurally
-    /// zero.
+    /// Open-world liquid surfaces reached and hid, a subset of `tested`/`hidden` kept apart as the
+    /// bodies are: a tile's few liquid layers vanish among its ~250 terrain cells.
     pub(crate) liquid: usize,
     pub(crate) liquid_hidden: usize,
 }
@@ -193,12 +86,8 @@ impl Plugin for ExteriorCullPlugin {
             PostUpdate,
             apply_exterior_cull
                 .in_set(ExteriorCullSet)
-                // The windows are written by the flood in `Update`; the cull reads them and must land
-                // before Bevy's own visibility pass consumes the result this same frame — and before
-                // the hierarchy propagation, so a root verdict reaches `InheritedVisibility` (which
-                // 1283's consumers and the billboard mirror read) the SAME frame. 1270 only ordered
-                // against `CheckVisibility`, leaving a benign race the window leg never noticed; the
-                // frustum leg follows the camera every frame, so the frame of lag is pinned away.
+                // The flood writes the windows in `Update`. Running before visibility propagation
+                // lets a root verdict reach `InheritedVisibility` the same frame.
                 .after(WmoPvsSet)
                 .after(bevy::transform::TransformSystems::Propagate)
                 .before(VisibilitySystems::VisibilityPropagate)
@@ -207,21 +96,11 @@ impl Plugin for ExteriorCullPlugin {
     }
 }
 
-/// The sub-frustum for one NDC window rect — the **construction alone**, no narrowness gate.
-///
-/// **Two callers, deliberately one construction** (decision 1826): this module gates the open world
-/// through these rects, and `crate::wmo_portal`'s Pass 2 gates the containing building's own
-/// exterior groups through the same ones. The reference likewise builds one volume per window and
-/// hands it to both (`0x682930` for `0x6b3b20`'s Pass 2, and the copy at `0xc7cb7c` for
-/// `0x682fa0`). What 1826 also copied across, and should not have, was the *reject*: it belongs to
-/// the open-world walk's entry, not to the volume — see [`scene_window_frustum`]. So a doorway too
-/// narrow to admit a hillside **can** still admit a wall, which is the reference's own asymmetry.
-///
-/// An NDC rect maps to the full screen by a scale+offset **on clip space** — `clip.x` scaled by
-/// `2/(x1-x0)` plus `clip.w` times `-(x0+x1)/(x1-x0)`, and likewise in y — so pre-multiplying
-/// `clip_from_world` by that matrix yields a projection whose 6 extracted planes bound exactly the
-/// window's sub-frustum. Depth rows are untouched: the window narrows the view laterally and inherits
-/// the camera's own near/far.
+/// The sub-frustum for one NDC window rect, with no width gate: the reference builds one volume
+/// per window for both the open-world walk (the copy at `0xc7cb7c`, for `0x682fa0`) and the
+/// building's own Pass 2 (`0x682930`, for `0x6b3b20`), and only the walk rejects a narrow window
+/// ([`scene_window_frustum`]). The rect is a scale and offset on clip space with depth untouched,
+/// so the extracted planes bound the window at the camera's own near and far.
 pub(crate) fn window_frustum(rect: Rect, clip_from_world: &Mat4) -> Frustum {
     let [x0, y0, x1, y1] = rect;
     let (w, h) = (x1 - x0, y1 - y0);
@@ -235,21 +114,11 @@ pub(crate) fn window_frustum(rect: Rect, clip_from_world: &Mat4) -> Frustum {
     Frustum::from_clip_from_world(&(rect_to_ndc * *clip_from_world))
 }
 
-/// [`window_frustum`] behind the **open-world walk's own entry gate** — and nothing else's.
-///
-/// `0x682fa0` opens with the gate, before it touches a bucket: `fld [edi+8]; fsub [edi]; fcomp
-/// [0x8029d0]; test ah,5; jnp -> ret` on x, then the same on y. `[0x8029d0]` is `0.01` and the rects
-/// are `[0,1]` screen fraction, so the walk runs iff **both extents are `>= 0.01`** — 0.02 in our NDC,
-/// non-strict, and a window under it draws no terrain, no ADT doodads, no world WMO placement, no
-/// liquid, no far band and no outdoor unit at all.
-///
-/// **The gate is the walk's, not the volume's** (RE 2026-09-02, `wow-5875-re`
-/// `models/scratch/wmo-pass2-window-reseed.md`): a compare-class census over the whole of
-/// `0x682930` — the builder both consumers share — returns **zero** compares, and Pass 2's own body
-/// `[0x6b3c73, 0x6b3d6f)` has seven, none of them on the rect. Decision 1826 read the reject as
-/// part of the shared construction and applied it to both, which silently culled the containing
-/// building's whole exterior shell for every window between the recursion's own collapse guard
-/// (`0.001` NDC, `0x6b44b1`) and this one. Decision 1853.
+/// [`window_frustum`] behind the open-world walk's entry gate: `0x682fa0` returns before touching a
+/// bucket unless both extents are `>= [0x8029d0]` (0.01 of the 0..1 screen, 0.02 NDC), so a
+/// narrower window draws no terrain, doodad, world WMO, liquid, far band or outdoor unit. The
+/// shared builder `0x682930` has no compares, and Pass 2's body `[0x6b3c73, 0x6b3d6f)` none on the
+/// rect, so a window too narrow for the open world still draws the building's own shell.
 pub(crate) fn scene_window_frustum(rect: Rect, clip_from_world: &Mat4) -> Option<Frustum> {
     let [x0, y0, x1, y1] = rect;
     if x1 - x0 < MIN_WINDOW_NDC || y1 - y0 < MIN_WINDOW_NDC {
@@ -258,24 +127,21 @@ pub(crate) fn scene_window_frustum(rect: Rect, clip_from_world: &Mat4) -> Option
     Some(window_frustum(rect, clip_from_world))
 }
 
-/// This frame's exterior gate — the window worklist turned into clip volumes, built once and asked
-/// per object. **Two systems ask it**, which is the whole point of it being a value rather than a
-/// loop: [`apply_exterior_cull`] owns the exterior objects nothing else writes (terrain cells, the
-/// far band), and [`crate::debug_panel`]'s model-visibility authority folds the same answer into its
-/// own AND for every model submesh, because those already have an owner (decision 0784).
+/// This frame's exterior gate: the window worklist as clip volumes, built once and asked per
+/// object by [`apply_exterior_cull`] and by the owners that fold it into their own verdict
+/// (`model_render::visibility`, the particle and static-geometry culls).
 pub enum ExteriorGate {
-    /// Outdoors — the driver's outside leg (`0x6811ca`): the ordinary frustum is the window, so the
-    /// gate admits everything and each object goes back to whatever else owns it.
+    /// Outdoors, the outside leg (`0x6811ca`): the ordinary frustum is the window, so the gate
+    /// admits everything and leaves each object to its other owners.
     Open,
-    /// Indoors: an object draws only where one of these sub-frusta admits it. **Empty admits
-    /// nothing** — the sealed-room case (`0x681199`'s skip), and the one branch that must not fail
-    /// open, because failing open here is the bug this whole module exists to fix.
+    /// Indoors: an object draws only where a sub-frustum admits it. Empty admits nothing, the
+    /// sealed room (`0x681199`'s skip), and must never fail open.
     Windows(Vec<Frustum>),
 }
 
 impl ExteriorGate {
-    /// Build from the worklist + the world camera. No camera yet ⇒ [`Self::Open`]: nothing is on
-    /// screen to leak, and a verdict taken without a view matrix would be arbitrary.
+    /// From the worklist and the world camera. No camera yet is [`Self::Open`]: nothing is on
+    /// screen, and a verdict without a view matrix would be arbitrary.
     pub(crate) fn build(
         windows: &ExteriorWindows,
         cam: Option<(&GlobalTransform, &Projection)>,
@@ -295,12 +161,9 @@ impl ExteriorGate {
         )
     }
 
-    /// Whole-AABB, per object — the reference's `0x682f40`. Not per primitive: a doodad straddling
-    /// the doorway edge draws whole, and the interior geometry cuts its silhouette.
-    ///
-    /// No `Aabb` (mesh still loading, or an entity that draws nothing) ⇒ admitted. A missing bound
-    /// is a *timing* gap, not a visibility verdict, and blanking on it would flicker the world as
-    /// tiles stream in.
+    /// Whole AABB, per object, as the reference's `0x682f40`: a doodad straddling the doorway edge
+    /// draws whole. No `Aabb` (a mesh still loading, or nothing drawn) is admitted: a missing bound
+    /// is a timing gap, and blanking on it would flicker the world as tiles stream in.
     pub(crate) fn admits(&self, gt: &GlobalTransform, aabb: Option<&Aabb>) -> bool {
         match (self, aabb) {
             (Self::Open, _) | (_, None) => true,
@@ -313,10 +176,9 @@ impl ExteriorGate {
         }
     }
 
-    /// The same test against a WORLD-space bounding **sphere** — the form the particle lane speaks
-    /// (`EmitterFade`'s `[rec+0x68]` fade sphere is the owner doodad's bound, and an emitter has no
-    /// mesh of its own to carry an `Aabb`). The sphere's axis-aligned box is what gets tested, which
-    /// is looser than the sphere and therefore never hides something a sphere test would admit.
+    /// The same test for a world-space bounding sphere, the particle lane's form (`EmitterFade`'s
+    /// `[rec+0x68]` fade sphere, the owner doodad's bound), through its box, which is looser and so
+    /// never hides what the sphere would admit.
     pub(crate) fn admits_sphere(&self, center: Vec3, radius: f32) -> bool {
         let aabb = Aabb::from_min_max(center - Vec3::splat(radius), center + Vec3::splat(radius));
         self.admits(&GlobalTransform::IDENTITY, Some(&aabb))
@@ -335,35 +197,25 @@ type UnownedScene = (
     &'static GlobalTransform,
     Option<&'static Aabb>,
     &'static mut Visibility,
-    // Instrument only — never a term in the verdict. Liquid takes exactly the same test as a
-    // terrain cell; this only lets the counters say so (see [`ExteriorCullVerdict::liquid`]).
+    // Instrument only: liquid takes the terrain cell's test, and this lets the counters say so.
     Has<crate::liquid::LiquidSurface>,
 );
 
-/// …and the objects it is allowed to write: exterior scene that nothing else owns. `ModelPart` and
-/// `WmoGroupVis` both mean "the model-visibility authority writes this one".
+/// The objects [`apply_exterior_cull`] may write: exterior scene no one else owns. A `ModelPart`
+/// or `WmoGroupVis` is the model-visibility authority's.
 type UnownedSceneFilter = (
     With<ExteriorScene>,
     Without<crate::model_render::ModelPart>,
     Without<crate::wmo_portal::WmoGroupVis>,
-    // …and disjoint from the body leg below, which also writes `Visibility`. The two audiences
-    // never overlap by construction (a body is elected at its root, which is not scene content),
-    // but Bevy needs that **proved**, not intended: without this the system panics B0001 at the
-    // first run. Stating it here rather than in the body query keeps the exclusion next to the
-    // `ModelPart`/`WmoGroupVis` ones, which are the same kind of claim.
+    // Disjoint from the body leg, which also writes `Visibility`: the two never overlap, but Bevy
+    // panics on the conflicting access unless the filter proves it.
     Without<crate::world_unit::WorldUnit>,
 );
 
-/// **`WOW_CULL_TRACE=1` — one line per body per frame, saying why it drew.**
-///
-/// `cull_bodies`/`cull_bodies_hidden` say *how many*; they cannot say *which*, and the difference
-/// cost three live runs of inference during decision 1270. A body escapes this cull in exactly three
-/// ways — it was never elected (no `WorldUnit::bound`), it claims a WMO room, or a window admitted
-/// its box — and from a screenshot, and from the aggregate counters, all three look identical.
-///
-/// Off (the var unset) this is one `Option` read per body. Deliberately not throttled like
-/// `WOW_VIS_TRACE`: the audience is the server's visibility stream (dozens), and the question it
-/// answers — "which body, on which frame" — is destroyed by sampling.
+/// `WOW_CULL_TRACE=1`: one line per body per frame saying why it drew. A body escapes the cull in
+/// three ways the counters cannot tell apart: never elected (no `WorldUnit::bound`), a WMO room
+/// claim, or a window admitting its box. Unthrottled: the audience is dozens, and sampling would
+/// lose which body on which frame.
 fn trace_body(
     trace: &Option<Res<CullTrace>>,
     e: Entity,
@@ -395,22 +247,14 @@ fn trace_body(
     );
 }
 
-/// `WOW_CULL_TRACE` — see [`trace_body`].
+/// Present when `WOW_CULL_TRACE` is set ([`trace_body`]).
 #[derive(Resource)]
 pub(crate) struct CullTrace;
 
-/// What the body leg reads per net body — one whole-object test on its root, which is the
-/// reference's own granularity (`0x682f40`), and which takes the whole visual with it: body
-/// geosets, worn gear under their joints, the mount and its rider (`mount::spawn_mount_child`
-/// parents the mount to its host), and the entity-lane billboard cards, which are world roots that
-/// mirror their owner's `InheritedVisibility` ([`crate::billboard::face_billboards`]). None of that
-/// composes from a per-submesh tag.
-///
-/// [`crate::wmo_portal::UnitWmoRoom`] is the reference's own fork between its two producers: a room
-/// claim means the object rides `0x6834e0` with its building, no claim means it rides `0x683340`
-/// inside the window walk. `Option` because a body that spawned this frame may not have been rayed
-/// yet, and an unknown room is a **timing gap, not a verdict** — the same law the missing-`Aabb`
-/// arm above takes, and for the same reason: deciding on absent information flickers the world.
+/// What the body leg reads per net body: one whole-object test on its root (`0x682f40`), which
+/// takes the whole visual with it (gear, mount, rider, billboard cards). A room claim
+/// ([`crate::wmo_portal::UnitWmoRoom`]) rides `0x6834e0` with its building, no claim rides
+/// `0x683340` in the window walk; a body not yet rayed has none and reads as outdoors.
 type ElectedBody = (
     Entity,
     &'static GlobalTransform,
@@ -419,16 +263,11 @@ type ElectedBody = (
     &'static mut Visibility,
 );
 
-/// Hide every [`ExteriorScene`] object that no window admits — **only those with no other
-/// `Visibility` owner**. A model submesh (`ModelPart`) and a WMO group piece (`WmoGroupVis`) are
-/// written by [`crate::debug_panel`]'s model-visibility authority, which composes the toggles, the
-/// far-clip wall, the distance fade and the portal PVS; a second writer here does not "also cull"
-/// them, it *overwrites* all of that every frame (decision 0784). So this system owns exactly what
-/// it is the sole authority for: terrain cells, the WDL far band, and — in the second query below,
-/// a different audience under the same law rather than a second system — the elected net bodies
-/// ([`ElectedBody`], decision 1270), whose roots nothing else writes.
-// A Bevy system's params are not an argument list to shorten — each is a distinct world access
-// the scheduler needs by name (the `update_ground_shade` precedent).
+/// Hides every [`ExteriorScene`] object no window admits, of those with no other `Visibility`
+/// owner (terrain cells, the far band, open-world liquid), and elects each net body
+/// ([`ElectedBody`]), whose root nothing else writes. A `ModelPart` or `WmoGroupVis` belongs to
+/// `model_render::visibility`, which folds [`ExteriorGate`] into its own verdict: a write here
+/// would overwrite it every frame.
 fn apply_exterior_cull(
     windows: Res<ExteriorWindows>,
     cam: Query<(&GlobalTransform, &Projection), With<WorldCamera>>,
@@ -440,9 +279,7 @@ fn apply_exterior_cull(
     trace: Option<Res<CullTrace>>,
     mut no_election: Local<Option<bool>>,
 ) {
-    // `WOW_NO_DRAW_ELECTION=1` — disable 1475's frustum + room legs only (the 1270 window leg
-    // stays: it fixes a *correctness* report, not a cost). The A/B lever that brackets the
-    // election's worth at any pin, and the escape hatch if an artifact is ever reported.
+    // `WOW_NO_DRAW_ELECTION=1` disables the frustum and room legs; the window leg stays.
     let no_election =
         *no_election.get_or_insert_with(|| std::env::var_os("WOW_NO_DRAW_ELECTION").is_some());
     let set = |vis: &mut Visibility, target: Visibility| {
@@ -451,13 +288,9 @@ fn apply_exterior_cull(
         }
     };
     let gate = ExteriorGate::build(&windows, cam.iter().next());
-    // The camera's own view volume, as the full-screen window: the reference's OUTSIDE leg is
-    // literally one `{0,0,1,1}` window through the same walk (`0x6811ff`), so outdoors is not a
-    // stand-down for bodies — an out-of-frustum body is elected pass 2, not drawn and not ticked
-    // (1473's correction of 0648; decision 1475). Built from this frame's own camera transform
-    // (we run after `Propagate`), never the `Frustum` component, which another PostUpdate set
-    // may not have refreshed yet. `None` (no camera) admits: a verdict without a view matrix
-    // would be arbitrary — `ExteriorGate::build`'s own law.
+    // The view volume as the outside leg's `{0,0,1,1}` window (`0x6811ff`): an out-of-frustum
+    // body is elected to pass 2. Built from this frame's camera transform, not the `Frustum`
+    // component, which may not be refreshed yet; no camera admits.
     let full_view = cam.iter().next().and_then(|(cam_t, proj)| {
         let clip_from_world = proj.get_clip_from_view() * cam_t.to_matrix().inverse();
         scene_window_frustum([-1.0, -1.0, 1.0, 1.0], &clip_from_world)
@@ -485,42 +318,29 @@ fn apply_exterior_cull(
             },
         );
     }
-    // The body leg: one whole-object test per net body (see [`ElectedBody`]), serial because the
-    // audience is the server's visibility stream — dozens, not the tens of thousands above.
+    // The body leg: one whole-object test per net body.
     let (mut body_n, mut body_hidden) = (0usize, 0usize);
     for (e, gt, body, room, mut vis) in &mut bodies {
         let Some(bound) = body.bound.as_ref() else {
-            // The game says this body is not ours to decide (`WorldUnit::bound`). Traced too: an
-            // un-elected body is invisible to every counter below, which is exactly how a whole
-            // class of creature sat outside this cull unnoticed (decision 1270 §5).
+            // No bound: not this cull's to decide. Traced, as no counter below sees it.
             trace_body(&trace, e, "unelected", gt, room, None, true);
             continue;
         };
         body_n += 1;
-        // In a WMO room ⇒ its building's own walk submits it, not the exterior one.
-        //
-        // **No claim yet reads as outdoors, not as exempt**, and that asymmetry is the whole of the
-        // director's second report. A claim is `try_insert`ed by `track_unit_interiors` a frame or
-        // two after a body spawns, so "undecided ⇒ admit" let every streaming mob draw through a
-        // sealed ceiling for exactly as long as the gap — which at a cavern's frame rate is most of
-        // a second, per mob, continuously. The two error directions are not symmetric: guessing
-        // *outdoors* makes a mob in your own room appear a frame late, guessing *in a room* makes a
-        // mob outside appear through solid rock. And `UnitWmoRoom::default()` is itself a
-        // no-room claim, so this simply decides the missing component the way the present one would.
+        // In a WMO room, its building's walk submits it. No claim yet reads as outdoors, as
+        // `UnitWmoRoom::default()` does: the claim lands a frame or two after spawn, and admitting
+        // in the gap would draw every streaming mob through a sealed ceiling.
         let in_room = room.is_some_and(|r| r.room().is_some());
         let admitted = if no_election {
-            // The lever: 1270's window leg alone — in-room exempt, outdoors a stand-down.
+            // The lever: the window leg alone, in-room bodies exempt.
             in_room || gate.admits(gt, Some(bound))
         } else if in_room {
-            // The sibling producer (`0x6834e0`): submitted with its building iff its room — or a
-            // one-hop neighbour, the doorway-straddle guard — is in this frame's portal PVS,
-            // AND its box passes the camera frustum like any other group member (the producer
-            // frustum-tests members; a body behind the camera in a visible room is pass 2).
-            // Fail-open at every resolve seam ([`crate::wmo_portal::room_pvs_visible`]).
+            // The sibling producer `0x6834e0`: drawn iff its room or a one-hop neighbour is in the
+            // PVS and its box is in view; `room_pvs_visible` fails open at every resolve seam.
             crate::wmo_portal::room_pvs_visible(room, &instances, &wmos) && in_view(gt, bound)
         } else {
-            // The exterior walk: outdoors, the one full-screen window; indoors, the portal
-            // windows — which are already sub-frusta of the view, so no second frustum term.
+            // The exterior walk: outdoors the full-screen window, indoors the portal windows,
+            // already sub-frusta of the view.
             match &gate {
                 ExteriorGate::Open => in_view(gt, bound),
                 ExteriorGate::Windows(_) => gate.admits(gt, Some(bound)),
@@ -584,9 +404,7 @@ mod tests {
         f.intersects_obb(&aabb, &Affine3A::IDENTITY, true, true)
     }
 
-    /// The full-screen window must behave exactly like the ordinary view frustum — this is the
-    /// outside leg's `{0,0,1,1}` rect, and if it ever narrowed, standing outdoors would start
-    /// clipping the world.
+    /// The outside leg's `{0,0,1,1}` rect is exactly the ordinary view frustum.
     #[test]
     fn the_full_screen_window_is_the_whole_frustum() {
         let f = window_frustum([-1.0, -1.0, 1.0, 1.0], &clip_from_world());
@@ -597,9 +415,6 @@ mod tests {
         assert!(!admits(&f, Vec3::new(0.0, 0.0, 10.0)), "behind the eye");
     }
 
-    /// The load-bearing property: a window covering only the RIGHT half of the screen must admit
-    /// what is on the right and reject what is on the left. This is the whole cull — a doorway on
-    /// one side of the view must not let the world in on the other.
     #[test]
     fn a_half_screen_window_rejects_the_other_half() {
         let f = window_frustum([0.1, -1.0, 1.0, 1.0], &clip_from_world());
@@ -610,16 +425,11 @@ mod tests {
         );
     }
 
-    /// **The granularity of the tagged object is half the cull** (decision 0780). This test is the
-    /// same patch of ground twice: once as the 33.333 yd MCNK cell it is drawn as now, once as the
-    /// 533.333 yd ADT tile it used to be merged into. The cell is rejected; the tile is admitted,
-    /// because a tile is drawn around the camera and so reaches the doorway's side of the view no
-    /// matter which side the ground is on. Nothing in `apply_exterior_cull` can fix that — it is
-    /// decided by what the spawner tags — which is why re-merging terrain into a per-tile mesh
-    /// would silently restore "I can see the hillside through the wall" with every test still green.
+    /// Why terrain is tagged per MCNK cell: a tile around the camera reaches the doorway's side of
+    /// the view whichever side its ground is on, so a per-tile mesh would draw through the walls.
     #[test]
     fn a_narrow_window_rejects_a_chunk_of_ground_but_never_a_whole_tile_of_it() {
-        // A doorway on the RIGHT of the view; the ground of interest is 200 yd to the LEFT.
+        // A doorway on the right of the view; the ground of interest is 200 yd to the left.
         let f = window_frustum([0.6, -1.0, 1.0, 1.0], &clip_from_world());
         let ground = Vec3::new(-200.0, -2.0, -200.0);
 
@@ -633,8 +443,7 @@ mod tests {
             "an MCNK cell to the left must not come in through a doorway on the right"
         );
 
-        // The ADT tile that CONTAINS that cell. The camera stands on it, so it spans both sides of
-        // the view — half a kilometre of ground admitted by a doorway that shows a hundredth of it.
+        // The ADT tile containing that cell: the camera stands on it, so it spans the view.
         const TILE: f32 = 533.333 / 2.0;
         let tile = Aabb::from_min_max(Vec3::new(-TILE, -2.5, -TILE), Vec3::new(TILE, -1.5, TILE));
         assert!(
@@ -644,15 +453,13 @@ mod tests {
         );
     }
 
-    /// The OPEN-WORLD walk rejects a window narrower than a hundredth of the screen
-    /// (`0x682fa0`'s entry compares against `[0x8029d0]`) — and it is non-strict, so a window
-    /// exactly at the threshold draws. The reject also keeps a collapsed rect from producing a
-    /// degenerate frustum whose planes are NaN (which `intersects_obb` would answer arbitrarily).
+    /// `0x682fa0`'s entry rejects a window under `[0x8029d0]`, non-strictly; the reject also keeps
+    /// a collapsed rect from building a frustum of NaN planes.
     #[test]
     fn the_scene_walk_drops_a_window_under_a_hundredth_of_the_screen() {
         assert!(scene_window_frustum([0.5, -1.0, 0.5, 1.0], &clip_from_world()).is_none());
         assert!(scene_window_frustum([-1.0, 0.2, 1.0, 0.2001], &clip_from_world()).is_none());
-        // `>= 0.01` of a 0..1 screen passes — the client's `jnp` is parity, not a strict `>`.
+        // `>= 0.01` of a 0..1 screen passes: the client's `jnp` is parity, not a strict `>`.
         assert!(
             scene_window_frustum([0.0, -1.0, -1.0 + MIN_WINDOW_NDC, 1.0], &clip_from_world())
                 .is_none(),
@@ -663,10 +470,8 @@ mod tests {
         );
     }
 
-    /// …and the volume builder itself has no such gate, because `0x682930` has no compares at all:
-    /// Pass 2 draws the containing building's own shell through a window the open world cannot use
-    /// (decision 1853). The band is `[0.001, 0.02)` NDC — above the recursion's collapse guard,
-    /// below the scene walk's entry.
+    /// `0x682930` has no compares, so Pass 2 draws the building's shell through a window the open
+    /// world rejects: `[0.001, 0.02)` NDC, above the recursion's collapse guard (`0x6b44b1`).
     #[test]
     fn pass_twos_builder_takes_a_window_the_scene_walk_rejects() {
         let narrow = [0.0, -1.0, 0.01, 1.0];
@@ -683,8 +488,7 @@ mod tests {
         );
     }
 
-    /// One `apply_exterior_cull` run over a scene built by the caller, returning each body's
-    /// verdict in spawn order plus the counters.
+    /// One `apply_exterior_cull` run: each body's verdict in spawn order, and the counters.
     fn run_bodies(
         windows: ExteriorWindows,
         bodies: &[(Vec3, Option<crate::wmo_portal::UnitWmoRoom>, Aabb)],
@@ -694,7 +498,6 @@ mod tests {
             .insert_resource(Assets::<benilla_assets::WmoModel>::default())
             .insert_resource(windows)
             .add_systems(Update, apply_exterior_cull);
-        // The same camera the pure-frustum tests use: origin, down −Z, 90° fov.
         app.world_mut().spawn((
             WorldCamera,
             GlobalTransform::IDENTITY,
@@ -733,13 +536,11 @@ mod tests {
         (vis, *app.world().resource::<ExteriorCullVerdict>())
     }
 
-    /// The three states a body's room claim can be in — kept distinct because the middle and the
-    /// last decide opposite ways and are one `Option` layer apart.
     fn outdoors() -> Option<crate::wmo_portal::UnitWmoRoom> {
         Some(crate::wmo_portal::UnitWmoRoom::default()) // rayed, hit nothing
     }
     fn in_a_room() -> Option<crate::wmo_portal::UnitWmoRoom> {
-        // The room's *identity* is nothing to this system — only whether there is one.
+        // Only whether there is a room matters here, not which.
         Some(crate::wmo_portal::UnitWmoRoom::claimed(
             crate::wmo_portal::WmoRoom {
                 instance: Entity::from_raw_u32(1).expect("a valid entity id"),
@@ -749,20 +550,17 @@ mod tests {
     }
     const NOT_RAYED_YET: Option<crate::wmo_portal::UnitWmoRoom> = None;
 
-    /// A yard-ish box on the body's own origin — a creature's authored idle CAaBox.
+    /// A yard box on the body's origin, a creature's authored idle `CAaBox`.
     fn creature_box() -> Aabb {
         Aabb::from_min_max(Vec3::splat(-0.5), Vec3::splat(0.5))
     }
-    /// …and what the game writes before a body's model has resolved: a point at its origin.
+    /// What the game writes before a body's model resolves: a point at its origin.
     fn unresolved() -> Aabb {
         Aabb::from_min_max(Vec3::ZERO, Vec3::ZERO)
     }
 
-    /// **The Caverns of Time report, as a test** (decision 1270). Sealed room ⇒ no windows ⇒ the
-    /// exterior walk never runs, so an outdoor body is not submitted at all — while a body standing
-    /// in a WMO room rides the sibling producer `0x6834e0` and still draws. Both bodies sit at the
-    /// same spot dead ahead of the camera: the *only* thing separating them is the room claim,
-    /// which is the reference's own fork between its two producers.
+    /// Two bodies dead ahead in a sealed room: only the room claim separates the one the exterior
+    /// walk never submits from the one `0x6834e0` submits with its building.
     #[test]
     fn a_sealed_room_hides_the_outdoor_body_and_keeps_the_one_in_a_room() {
         let ahead = Vec3::new(0.0, 0.0, -50.0);
@@ -781,16 +579,8 @@ mod tests {
         assert_eq!((verdict.bodies, verdict.bodies_hidden), (2, 1));
     }
 
-    /// **A body whose model has not resolved yet is elected all the same**, on the point at its own
-    /// origin — the director's second report, after the first cut had landed: creatures still
-    /// appearing overhead inside Caverns of Time.
-    ///
-    /// Every streamed mob drew for one whole frame, because the model's extent reaches
-    /// `publish_world_units` only *after* `attach_entity_visuals` has already spawned the visual,
-    /// and a bound-less body was admitted. That looked like a conservative default and was a defect:
-    /// at a cavern's frame rate one frame is most of a second, and mobs stream continuously, so a
-    /// per-body flash reads as "they are still there". The origin never needed waiting for — it is
-    /// the server's own position, exact from the body's first frame.
+    /// A body whose model has not resolved is tested on its origin, the server's exact position,
+    /// not drawn for the frame until its extent arrives.
     #[test]
     fn a_body_whose_model_has_not_resolved_is_elected_on_its_origin() {
         let (vis, verdict) = run_bodies(
@@ -805,20 +595,8 @@ mod tests {
         assert_eq!((verdict.bodies, verdict.bodies_hidden), (1, 1));
     }
 
-    /// A body whose room has not been rayed yet reads as **outdoors**, and is gated.
-    ///
-    /// This test asserted the opposite when the first cut landed — "an unknown room is a timing gap,
-    /// not a verdict", borrowed from the missing-`Aabb` arm beside it. The director refuted it from
-    /// the screen: creatures still overhead inside Caverns of Time. `track_unit_interiors`
-    /// `try_insert`s a claim a frame or two after a body spawns, so on a continuous stream of mobs
-    /// there is always a handful mid-gap, and admitting them drew each one through the ceiling for
-    /// most of a second.
-    ///
-    /// The lesson is that the two arms are not the same question. A missing bound leaves nothing to
-    /// test, so the cull genuinely cannot decide. A missing *claim* still has a default the
-    /// component itself states — `UnitWmoRoom::default()` is a no-room claim — and the error
-    /// directions are lopsided: a body wrongly called outdoors appears a frame late, a body wrongly
-    /// called indoors appears through solid rock.
+    /// A missing claim is not a missing bound: `UnitWmoRoom::default()` is a no-room claim, and a
+    /// body wrongly outdoors appears a frame late where one wrongly indoors shows through rock.
     #[test]
     fn an_unrayed_body_reads_as_outdoors() {
         let (vis, verdict) = run_bodies(
@@ -833,20 +611,15 @@ mod tests {
         assert_eq!((verdict.bodies, verdict.bodies_hidden), (1, 1));
     }
 
-    /// Outdoors the driver's `{0,0,1,1}` leg IS the ordinary frustum — the reference's outside
-    /// leg is one full-screen window through the same frustum-testing walk, so a body behind the
-    /// camera is elected pass 2: not drawn (decision 1475). This test asserted the opposite under
-    /// 1270 ("`Unrestricted` is a stand-down… the arm that must never narrow") — that law was
-    /// built before wow-re's election correction and is deliberately superseded here (1473).
+    /// Outdoors the `{0,0,1,1}` leg frustum-tests bodies: one behind the camera goes to pass 2.
     #[test]
     fn outdoors_the_full_screen_window_elects_the_bodies() {
         let (vis, verdict) = run_bodies(
             ExteriorWindows::Unrestricted,
             &[
                 (Vec3::new(0.0, 0.0, -50.0), outdoors(), creature_box()),
-                // Behind the camera: pass 2. Its parts carry `NoFrustumCulling` (0648's picker
-                // law), so this root verdict is the ONLY thing standing between an off-view
-                // crowd and the draw queue — the Goldshire premium of 1473.
+                // Behind the camera: pass 2. Its parts carry `NoFrustumCulling`, so this root
+                // verdict alone keeps an off-view crowd out of the draw queue.
                 (Vec3::new(0.0, 0.0, 50.0), outdoors(), creature_box()),
             ],
         );
@@ -858,11 +631,7 @@ mod tests {
         assert_eq!((verdict.bodies, verdict.bodies_hidden), (2, 1));
     }
 
-    /// The in-room fork of the same election: a body in a PVS-dark room is not drawn — the
-    /// sibling producer only submits members of rendered groups — and the moment the flood
-    /// reaches its room (or a one-hop neighbour), it draws again. The imp-upstairs-in-the-inn
-    /// case from 1473's audit: visible-room wiring, resolve chain and all, not just the truth
-    /// table (which lives with [`crate::wmo_portal::room_pvs_visible`]).
+    /// The in-room fork through the real resolve chain; the truth table is `room_pvs_visible`'s.
     #[test]
     fn a_body_in_a_pvs_dark_room_is_not_drawn_until_the_flood_reaches_it() {
         let mut app = App::new();
@@ -881,10 +650,8 @@ mod tests {
                 ..default()
             }),
         ));
-        // A two-group building whose groups share no portal: group 0's verdict is its own bit.
-        // The nav table must be REAL — an absent nav entry is a fail-open seam that reads
-        // visible ([`crate::wmo_portal::room_pvs_visible`]'s law), which is right for a
-        // still-loading model and wrong as a test of the dark-room verdict.
+        // Two groups sharing no portal, with a real nav table: an absent entry fails open as
+        // visible, which would void the dark-room verdict.
         let sealed = |_g: u16| benilla_assets::WmoGroupNav {
             flags: 0,
             bbox_min: [0.0; 3],
@@ -917,7 +684,7 @@ mod tests {
                 flooded: vec![None, None],
             })
             .id();
-        // Dead ahead of the camera — only the room term can hide it.
+        // Dead ahead of the camera: only the room term can hide it.
         let body = app
             .world_mut()
             .spawn((
@@ -941,7 +708,6 @@ mod tests {
             Visibility::Hidden,
             "a PVS-dark room's body is not submitted"
         );
-        // The flood reaches its room: drawn again the same frame.
         app.world_mut()
             .entity_mut(inst)
             .get_mut::<crate::wmo_portal::WmoPortalInstance>()
@@ -953,8 +719,7 @@ mod tests {
             Visibility::Inherited,
             "PVS reach ⇒ drawn"
         );
-        // And a lit room does not exempt a member from the view: the sibling producer
-        // frustum-tests members too. Move the body behind the camera — hidden again.
+        // A lit room does not exempt a member from the view: behind the camera, hidden again.
         *app.world_mut()
             .entity_mut(body)
             .get_mut::<GlobalTransform>()
@@ -967,8 +732,6 @@ mod tests {
         );
     }
 
-    /// A doorway on the right admits the body on the right and rejects the one on the left — the
-    /// same law as the terrain test above, now on a whole object rather than a chunk of ground.
     #[test]
     fn a_doorway_admits_only_its_own_side() {
         let (vis, verdict) = run_bodies(
@@ -986,9 +749,8 @@ mod tests {
         assert_eq!((verdict.bodies, verdict.bodies_hidden), (2, 1));
     }
 
-    /// One `apply_exterior_cull` run over a scene of **liquid surfaces** — the ADT spawn's own
-    /// shape: a world root at `IDENTITY` (MCLQ positions are absolute) carrying a world-space
-    /// `Aabb`, the `LiquidSurface` marker and the `ExteriorScene` tag.
+    /// One `apply_exterior_cull` run over liquid surfaces shaped as the ADT spawn makes them: world
+    /// roots at `IDENTITY` (MCLQ positions are absolute) with a world-space `Aabb`.
     fn run_liquid(
         windows: ExteriorWindows,
         surfaces: &[Aabb],
@@ -1031,10 +793,8 @@ mod tests {
         (vis, *app.world().resource::<ExteriorCullVerdict>())
     }
 
-    /// One MCNK liquid layer's world box, centred at `at` — a flat 33.333 yd sheet, which is the
-    /// granularity `spawn_liquids` actually produces (one entity per `LiquidMesh`, and an ADT chunk
-    /// carries its liquid per chunk). Flat on purpose: a lake is a sheet, and the whole question is
-    /// whether a sheet *overhead* reaches the doorway's part of the view.
+    /// One MCNK liquid layer's world box at `at`: a flat 33.333 yd sheet, the granularity
+    /// `spawn_liquids` produces (one entity per `LiquidMesh`).
     fn lake(at: Vec3) -> Aabb {
         const CELL: f32 = 33.333 / 2.0;
         Aabb::from_min_max(
@@ -1043,15 +803,8 @@ mod tests {
         )
     }
 
-    /// **The director's report, as a test** (decision 1652): from inside a cavern you could see the
-    /// lake above through the ceiling. Sealed room ⇒ no windows ⇒ the reference's per-window
-    /// exterior populate never runs, and its ADT liquid producer `0x683ab0` is reachable from
-    /// nowhere else — so the lake is not submitted at all.
-    ///
-    /// Before 1652 this asserted nothing, because an ADT surface carried no `ExteriorScene` and the
-    /// cull never reached it. That is what `liquid`/`liquid_hidden` exist to make visible: the
-    /// counters are the difference between "the cull admitted the lake" and "the cull never saw
-    /// it", which from a screenshot are the same picture.
+    /// A sealed room never runs the exterior walk, the only path to the ADT liquid producer
+    /// `0x683ab0`, so the lake overhead is not drawn; the counters prove the cull reached it.
     #[test]
     fn a_sealed_room_hides_the_lake_overhead() {
         let overhead = Vec3::new(0.0, 30.0, -60.0);
@@ -1069,11 +822,7 @@ mod tests {
         );
     }
 
-    /// The control that must not change: **outdoors nothing about liquid moves.** The driver's
-    /// outside leg is one full-screen window (`0x6811ca`), so the gate is `Open` and every surface
-    /// goes back to whatever else owns it — which, for liquid, is nothing. If this ever fails, the
-    /// lake has started disappearing in the open world, which is a far worse bug than the one 1652
-    /// fixed.
+    /// Outdoors the gate is `Open` (`0x6811ca`) and liquid has no other owner, so no lake hides.
     #[test]
     fn outdoors_every_lake_is_admitted() {
         let (vis, verdict) = run_liquid(
@@ -1087,9 +836,6 @@ mod tests {
         assert_eq!((verdict.liquid, verdict.liquid_hidden), (2, 0));
     }
 
-    /// A doorway shows the water on its own side of the view and no other — the same law the
-    /// terrain and body legs take, on the bucket that was missing it. Both sheets sit at the same
-    /// height and depth; the only difference is which way the doorway faces.
     #[test]
     fn a_doorway_admits_only_the_water_on_its_own_side() {
         let (vis, verdict) = run_liquid(
@@ -1107,21 +853,14 @@ mod tests {
         assert_eq!((verdict.liquid, verdict.liquid_hidden), (2, 1));
     }
 
-    /// **The failure mode this change could have had, pinned:** the cavern's OWN pool must not be
-    /// blanked by the sealed room it sits in. A WMO pool carries `WmoGroupVis` (0689), so it is
-    /// owned by the model-visibility authority — which exempts the camera's own placement and folds
-    /// the window term in itself (0784) — and this system's `Without<WmoGroupVis>` filter must keep
-    /// its hands off it entirely, tag or no tag.
-    ///
-    /// Asserting on `liquid` is the point: the counter proves the surface was not merely *admitted*
-    /// but never walked, which is the difference between the two authorities agreeing and one of
-    /// them silently overwriting the other.
+    /// A WMO pool (`WmoGroupVis`) belongs to the model-visibility authority, which exempts the
+    /// camera's own building: this walk must skip it, tag or not, even in a sealed room.
     #[test]
     fn a_wmo_pool_is_never_written_by_this_system() {
         let mut app = App::new();
         app.init_resource::<ExteriorCullVerdict>()
             .insert_resource(Assets::<benilla_assets::WmoModel>::default())
-            // The sealed room — the one case that would blank it.
+            // The sealed room: the one case that would blank it.
             .insert_resource(ExteriorWindows::Windows(Vec::new()))
             .add_systems(Update, apply_exterior_cull);
         let instance = app.world_mut().spawn(()).id();
diff --git a/crates/benilla-world/src/ffx_glow.rs b/crates/benilla-world/src/ffx_glow.rs
index d0f37e99..36e2b30e 100644
--- a/crates/benilla-world/src/ffx_glow.rs
+++ b/crates/benilla-world/src/ffx_glow.rs
@@ -1,29 +1,9 @@
-//! The faithful **FFXGlow** post pass (decision 0158) — the reference's full-screen glow
-//! (`FFXEffects.cpp` / `FFXGlow.bls`), replacing the Bevy-`Bloom` approximation and its two
-//! eye-tuned constants.
-//!
-//! Pipeline (all byte-grounded — the shipped ARB programs + wow-re's `ffxeffects` T3 node):
-//! scene → ½ → ¼ downsample (dims floored at 8, `ffx_compute_rt_dims`) → separable Gauss4
-//! (weights ⅛ ⅜ ⅜ ⅛, shipped constants) → `out = screen + w·blur²` in gamma bytes, `w` = the
-//! per-zone `LightParams.glow` weight (authored data; the ONLY input, no knobs). The gamma-space
-//! byte math and the square-law are in `shaders/ffx_glow.wgsl`.
-//!
-//! This is the frame's sole glow pass — it won the A/B against Bevy's `Bloom`, and that fallback
-//! (plus its debug toggle) is gone. Applied to both the world camera and the portrait-booth bake
-//! cameras (`portrait::mod`): the booth rides the same final node so its bake reads at exact world
-//! parity, the FFXGlow combine owning the frame's ONE gamma decode.
-//!
-//! **What a bake does NOT inherit.** The node's two other lanes are keyed on the *viewer's own
-//! state*, not on the scene — the drunk/underwater haze and the ghost's FFXDeath combine — and the
-//! reference runs its FFX pass inside the WorldFrame's paint, with every UI frame compositing
-//! afterwards. [`FfxGlow::state_scale`] is that whole class in one field, `0` on every bake
-//! (decision 1481).
-//!
-//! **Two nodes since decision 2234.** The world view's node runs the three filter passes and,
-//! for a view nobody claims, the combine where [`crate::final_pass`] says. The player-UI camera
-//! claims the world view ([`FfxBackdrop`]) and draws the combine itself, first in its own main
-//! pass, straight into its byte target: the world enters the interface's buffer with no picture
-//! in between — no full-window float image written by one camera and read back by the next.
+//! The reference's full-screen glow (`FFXGlow.bls`): the scene is box-downsampled to ¼ in one
+//! pass (dims floored at 8, `0x6cdb40`), blurred by Gauss4 H then V (weights ⅛ ⅜ ⅜ ⅛), and
+//! combined as `lerp(screen, blur, z) + w·blur²` in gamma bytes (`shaders/ffx_glow.wgsl`), `w` the
+//! zone glow and `z` the haze. The combine also owns the frame's one gamma decode. A world view
+//! the player-UI camera claims ([`FfxBackdrop`]) runs only the filter passes, and the UI camera
+//! draws its combine.
 
 use bevy::core_pipeline::core_2d::graph::{Core2d, Node2d};
 use bevy::core_pipeline::core_2d::Transparent2d;
@@ -50,105 +30,54 @@ use bevy::render::{Render, RenderApp, RenderStartup, RenderSystems};
 use crate::final_pass::FinalPassTarget;
 use crate::view::WorldCamera;
 
-/// Marks a camera rendering with the faithful FFXGlow pass (extracted to the render world).
-///
-/// The pass is TWO things in one: the frame's single gamma→linear decode (mandatory on every view
-/// that draws our gamma-byte materials — decision 0161) and the glow add on top. `gain_scale`
-/// separates them: it multiplies the zone's [`FfxGlowGain`] for this view, so `0.0` keeps the
-/// decode and drops the glow.
+/// A camera running the FFXGlow pass: the frame's one gamma→linear decode, plus the glow add.
 #[derive(Component, Clone, Copy, ExtractComponent)]
 pub struct FfxGlow {
-    /// Per-view multiplier on the zone glow weight. See [`Self::WORLD`] / [`Self::UI_PANE`].
+    /// The per-view multiplier on the zone glow weight; `0.0` keeps the decode, drops the glow.
     pub(crate) gain_scale: f32,
-    /// **Which FFX pass pair this view runs**, and therefore what drives the combine's `y` (the
-    /// FFXDeath gate) and `z` (the haze mix) — see [`FfxState`].
-    ///
-    /// **The law, and why it is ONE field.** The reference runs its FFX pass inside the
-    /// WorldFrame's own paint — a BEGIN/END pair, `0x6cd890`/`0x6cda70`, bracketed at
-    /// `0x48350e`/`0x48379d` inside the one paint method `0x483460` (wow-re `death-pass.md` §5,
-    /// VERIFIED). It **cannot reach a bake**, for reasons that need no frame ordering: the pass's
-    /// render targets come from three module globals (`0xce8b5c` full, `0xce8ae8` quarter,
-    /// `0xce8b98` backbuffer) and it never observes the ambient binding — while the reference's
-    /// own portrait bake `0x524f60` binds no target at all and *copies* the framebuffer corner
-    /// out (`0x58acd0`/`0x449bf0`), so the pixels it keeps are pre-pass in every ordering.
-    ///
-    /// The binary does not separate the two lanes: the haze is `primary.z` of the glow combine
-    /// `0x6cb020`, which shares the single active-pass slot `0xce8bb4` with the death pass and
-    /// runs through the same bracket into the same three targets. So they are **one class**, and
-    /// this is one field. The zone glow is not in it (authored scene data, and a bake wants world
-    /// parity for it — decision 0638), which is why [`Self::gain_scale`] stays separate.
-    ///
-    /// The haze had its own `haze_scale` and the death gate had none, so a released ghost's
-    /// portraits baked through the FFXDeath combine and came back steel-blue luma (report B49,
-    /// decision 1481). Naming the *class* rather than the member was the fix; naming the **pass
-    /// pair** (decision 1731) is the same fix one step further, and it is the reference's own
-    /// shape — see [`FfxState`].
+    /// Which FFX pass pair this view runs, and so what drives the combine's death gate `y` and
+    /// haze `z`. The zone glow is scene data, outside it, so a bake keeps it.
     pub(crate) state: FfxState,
 }
 
-/// **Which of the reference's FFX pass pairs a view runs.** The binary builds *two*, and the
-/// active-pass slot `[0xce8bb4]` holds whichever the screen that is painting installed:
-///
-/// - the **WorldFrame** pair — `0x6cc130` CFFXGlow → `[0xb4b350]`, `0x6cc690` CFFXDeath →
-///   `[0xb4b39c]`, built at `0x481c46`; selected by `0x5de9c0` off `PLAYER_FLAGS_GHOST`;
-/// - the **glue** pair — `[0xb414c4]` glow / `[0xb41468]` death, built at CGlueMgr init
-///   `0x46a723`/`0x46a752`; selected by the select build's tail `0x472fd9 test dh,0x20` off the
-///   selected roster record's `CHARSELECT+0xfc & 0x2000` (wow-re `death-pass.md` §4(c) +
-///   `glue-select-model.md` §A2, both VERIFIED).
-///
-/// benilla's views coexist where the reference's screens take turns, so what the reference
-/// expresses as one global slot written by whoever paints, we express as a property of the view.
-/// That is *why* this is an enum and not a scale: a bake's [`Self::None`] cannot inherit a
-/// player-state lane by arithmetic accident, which is the invariant decision 1481 legislated after
-/// report B49, now structural.
+/// Which of the reference's two FFX pass pairs a view runs. The reference keeps the painting
+/// screen's pair in one active-pass slot `[0xce8bb4]`; our views coexist, so it is per view.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum FfxState {
-    /// The **WorldFrame** pair — the live player's own state: the ghost death combine
-    /// ([`FfxDeathFade`], off `PLAYER_FLAGS_GHOST`) and the drunk/underwater haze
-    /// ([`FfxHazeMix`]). The true world view only.
+    /// The WorldFrame pair (`0x6cc130` CFFXGlow → `[0xb4b350]`, `0x6cc690` CFFXDeath →
+    /// `[0xb4b39c]`, built at `0x481c46`): the ghost death combine ([`FfxDeathFade`]) and the
+    /// drunk/underwater haze ([`FfxHazeMix`]) of the live player. The world view only.
     Player,
-    /// The **glue** pair — the death combine iff the SELECTED ROSTER ROW is a ghost
-    /// ([`GlueFfx::death`]), and no haze: a glue screen has no drunk player and no camera in a
-    /// liquid, and the reference's glue pass pair carries no haze lane to read.
+    /// The glue pair (`[0xb414c4]` glow, `[0xb41468]` death, built at `0x46a723`/`0x46a752`): the
+    /// death combine when the selected roster row is a ghost ([`GlueFfx::death`]), and no haze.
     Glue,
-    /// Neither — a bake standing in for a 1.12 UI model widget, which the reference composites
-    /// *after* the WorldFrame's own FFX bracket and which therefore sees no pass state at all.
+    /// Neither: a bake standing in for a UI model widget. The reference's pass runs inside the
+    /// WorldFrame paint (`0x6cd890`/`0x6cda70`, at `0x48350e`/`0x48379d` in `0x483460`) on its own
+    /// targets (`0xce8b5c`, `0xce8ae8`, `0xce8b98`), and its portrait bake `0x524f60` copies its
+    /// pixels out of the framebuffer (`0x58acd0`/`0x449bf0`), so a bake never carries the pass.
     None,
 }
 
 impl FfxGlow {
-    /// The reference's own full-screen glow, at the zone's authored weight — the world camera:
-    /// zone glow AND the player-state passes (drunk / camera-eye-submerged blur, ghost death
-    /// combine). The only view that carries the latter.
+    /// The world camera: the zone glow and the live player's pass pair.
     pub const WORLD: Self = Self {
         gain_scale: 1.0,
         state: FfxState::Player,
     };
-    /// The **glue screens' own** fullscreen render (login / create / character select) — the
-    /// reference's glue pass pair, installed by CGlueMgr and applied around the glue scene's paint
-    /// (`0x46fad3 call 0x6cd890` … `0x46fae0 jmp 0x6cda70`). It is not a bake standing in for a UI
-    /// widget: it is the screen, so it runs the zone glow AND, for a ghost selection, the death
-    /// combine — while the GlueXML frames over it composite afterwards, untinted, exactly as the
-    /// reference's character list and buttons do.
+    /// The glue screens' scene: the zone glow and the glue pair, around the glue paint (`0x46fad3`
+    /// calls `0x6cd890`, `0x46fae0` jumps to `0x6cda70`); GlueXML composites after, untinted.
     pub const GLUE_SCENE: Self = Self {
         gain_scale: 1.0,
         state: FfxState::Glue,
     };
-    /// A portrait/booth bake at world parity for *lighting and glow* (decision 0638) — but never
-    /// a player-state pass: a bake stands in for a UI model widget, which the reference
-    /// composites after the WorldFrame's FFX pass. So a drunk player's unit frame stays sharp
-    /// while the world swims, and a **ghost's portrait keeps its living face** while the world
-    /// goes steel-blue (decision 1481, report B49).
+    /// A portrait bake: the zone glow at world parity and no player-state pass, so a ghost's
+    /// portrait keeps its living face and a drunk player's unit frame stays sharp.
     pub const BOOTH: Self = Self {
         gain_scale: 1.0,
         state: FfxState::None,
     };
-    /// **Decode only, no glow** — for a bake that stands in for a 1.12 *UI model widget*. The
-    /// reference applies its FFX pass inside the WorldFrame's own paint (the `0x6cd890`/`0x6cda70`
-    /// BEGIN/END bracket at `0x48350e`/`0x48379d`, wow-re `death-pass.md` §5); every UI frame
-    /// paints afterwards, at its own strata, so a `<PlayerModel>` pane is composited over an
-    /// already-glowed world and never glows itself. (The give-away in-game: the reference's chat
-    /// text and buttons don't bloom.)
+    /// Decode only, no glow: a bake standing in for a UI model widget (a `<PlayerModel>` pane),
+    /// which the reference paints after the WorldFrame's FFX pass, so it never glows.
     pub const UI_PANE: Self = Self {
         gain_scale: 0.0,
         state: FfxState::None,
@@ -161,95 +90,47 @@ impl Default for FfxGlow {
     }
 }
 
-/// **A 2D camera whose ground is the world's FFX combine** (decision 2234) — the player-UI
-/// camera.
-///
-/// The world reaches the interface's byte buffer as the FIRST DRAW of this camera's main pass:
-/// the combine of the view `source` names, rendered straight into this view's main texture in
-/// the UI lane's terms — the gamma byte, no decode ([`FfxCombineKey::gamma_out`]) — before
-/// anything the camera draws itself, inside the same pass ([`FfxTransparent2dNode`]). What that replaces is a picture: the combine used to write a full-window float
-/// image that the UI pass then drew as its first quad, one write and one read of every pixel at
-/// eight bytes each, for a value the quad re-encoded straight back to the byte the combine had
-/// computed.
-///
-/// `source` is the world camera drawing this frame — its main-world entity — or `None` when
-/// none is (the glue screens, the loading screen, a gated camera): the pass then does nothing
-/// and the camera's own clear is the ground, exactly as the quad's absence was. The render world
-/// resolves it to the view that actually rendered this frame ([`prepare_backdrops`]): a camera
-/// that is active but was not extracted — its target's image not prepared yet, a spawn frame —
-/// is not a source, so the pass never samples a main texture older than the frame. The component
-/// itself stays on the camera so its pair of combine pipelines is specialised on the camera's
-/// first frame, before any world exists to hitch on their compile.
-///
-/// The world view it names keeps its three filter passes — the ¼-res blur this combine samples
-/// — and runs no combine of its own: nothing writes its camera's target, which is a size-carrier
-/// only (`benilla_app::world_backdrop`). Its main texture is read unflipped, so a claimed camera
-/// runs `CameraOutputMode::Skip`.
+/// The player-UI camera's ground: the combine of the world view `source` names, drawn first in
+/// its main pass as the gamma byte ([`FfxTransparent2dNode`]). That world view runs no combine of
+/// its own, and runs `CameraOutputMode::Skip`, since its main texture is read unflipped.
 #[derive(Component, Clone, Copy, Default, ExtractComponent)]
 pub struct FfxBackdrop {
-    /// The world camera whose combine this camera runs — a main-world entity — or `None` while
-    /// no world is drawing.
+    /// The world camera drawing this frame (main-world entity). While `None` the camera's own
+    /// clear is the ground; the component stays so its pipelines compile before any world exists.
     pub source: Option<Entity>,
 }
 
-/// The per-zone glow weight `w` (`LightParams.glow` — authored data, synced from
-/// [`crate::lighting::WowLighting`] every frame).
+/// The glow weight `w`: the live `LightParams.glow`, synced every frame by [`sync_gain`].
 #[derive(Resource, Clone, ExtractResource)]
 pub struct FfxGlowGain(pub f32);
 
-/// The FFXDeath gate (decision 0308 §7, byte-VERIFIED wow-re death-pass.md): `1.0` while the
-/// player is a released ghost — the combine swaps to the FFXDeath program whole — else `0.0`.
-/// INSTANT on both edges (the client has no time ramp; the ghost tint is a shader constant).
-/// Driven by `benilla-app`'s death arc off `PLAYER_FLAGS_GHOST`; uploaded as the combine
-/// uniform's `y`, scaled per view by [`FfxGlow::state_scale`] — it is a **player-state** pass and
-/// reaches the world view only (decision 1481).
+/// The FFXDeath gate, the combine's `y`: `1.0` while the player is a released ghost (`0x5de9c0`,
+/// off `PLAYER_FLAGS_GHOST`), else `0.0`, with no ramp on either edge.
 #[derive(Resource, Clone, Default, ExtractResource)]
 pub struct FfxDeathFade(pub f32);
 
-/// **The glue screens' FFX state** — the two things the select build's tail writes, and nothing
-/// else (`0x472fba`–`0x473007`, byte-read from wow-re's own disassembly; the fork is
-/// `472fd9 test dh,0x20` on the selected record's `CHARSELECT+0xfc`):
-///
-/// ```text
-/// 472fde  mov ecx,ds:0xb41468 ; call 0x6cde60   ; ghost  → install the glue DEATH pass
-/// 472fe9  mov edx,ds:0x838570 ; mov [esi+0x110],edx      ; …and pin LightParams.glow
-/// 472ff7  mov ecx,ds:0xb414c4 ; call 0x6cde60   ; living → install the glue GLOW pass
-/// 473002  mov eax,ds:0x838574 ; mov [esi+0x110],eax      ; …and pin LightParams.glow
-/// ```
-///
-/// `[esi+0x110]` is the DN/lighting singleton's `LightParams.glow` (`esi` = `0x6d48b0()` =
-/// `&0xce9b60`) — the same scalar `0x6cb930` reads for the death combine's **alpha byte**
-/// (`glow × 255`, `death-pass.md` §3) and the glow combine reads for its blur² weight. So on a glue
-/// screen the glow weight is not a zone value at all: it is one of two constants, chosen by the
-/// same bit that chooses the pass.
-///
-/// Written by the game's char-select feed; read by [`sync_gain`]'s off-world arm and by
-/// [`FfxState::Glue`]'s combine.
+/// The glue screens' FFX state. The select build's tail (`0x472fba`–`0x473007`) forks on the
+/// selected record's `CHARSELECT+0xfc & 0x2000` (`0x472fd9`), installs (`0x6cde60`) the glue
+/// death or glow pass and pins `LightParams.glow` (`[0x6d48b0()+0x110]`) to a constant: both
+/// combines' blur² weight, which the death combine packs as its alpha byte (`0x6cb930`).
 #[derive(Resource, Clone, Copy, Default, PartialEq, Eq, Debug, ExtractResource)]
 pub enum GlueFfx {
-    /// **A glue ModelFFX widget is up and nothing has re-pinned it** — the login screen, the create
-    /// screen, and a character-select screen with an empty account (where no select build runs).
-    /// `CSimpleModelFFX`'s own **OnShow** override `0x46fa60` pins `[+0x110] = *0x8380b4 = 0.30f`
-    /// and installs the glue GLOW pass (`0x46fa74`). OnShow, not per-frame: it tail-jumps to
-    /// `0x76b260`, which runs the widget's `[frame+0x130]` handler (`0x76a0d0` maps `"OnShow"` to
-    /// that slot), which is why the select build's own pin below is not overwritten every frame.
+    /// A glue model widget is shown and nothing has re-pinned it: login, create, and a character
+    /// select with no characters. The widget's OnShow (`0x46fa60`) installs the glue glow pass and
+    /// pins `*0x8380b4` = 0.30, once on show, so the select build's pins hold.
     #[default]
     Shown,
-    /// **The character-select screen, LIVING selection.** The select build's tail installs the glue
-    /// GLOW pass and pins `*0x838574 = 0.40f` (`0x472ff7`/`0x473002`). Note what this is *not*: a
-    /// living selection is not "no post-process" — it is the glow pass at a pinned weight.
+    /// Character select, a living selection: the glue glow pass, pinned at `*0x838574` = 0.40
+    /// (`0x472ff7`/`0x473002`).
     SelectLiving,
-    /// **The character-select screen, GHOST selection.** The glue DEATH pass, and `*0x838570 = 0.15f`
+    /// Character select, a ghost selection: the glue death pass, pinned at `*0x838570` = 0.15
     /// (`0x472fde`/`0x472fe9`).
     SelectGhost,
 }
 
 impl GlueFfx {
-    /// The glue pair's death gate — `1.0` only for [`Self::SelectGhost`]. Instant on both edges,
-    /// like the world's: the reference's swap is a slot write with no time anchor in it, so
-    /// clicking from a ghost row to a living one un-washes the scene on the same frame. And it runs
-    /// on **every** selection, not only the first: `0x472a6d jne 0x472fba` sends an already-built
-    /// record straight into the swap block.
+    /// The glue pair's death gate, with no ramp. The swap re-runs on every selection, an
+    /// already-built record included (`0x472a6d`), so the scene changes on the click's frame.
     fn death(self) -> f32 {
         match self {
             Self::SelectGhost => 1.0,
@@ -257,22 +138,10 @@ impl GlueFfx {
         }
     }
 
-    /// `LightParams.glow` while a glue screen is up — the DN/lighting singleton's `0xce9c70`
-    /// (`0x6d48b0` is `mov eax,0xce9b60; ret`, so `[eax+0x110]` is that field).
-    ///
-    /// **All three values are byte-VERIFIED**, and an accessor-call-site census over all 41
-    /// `call 0x6d48b0` sites found exactly these three writers and three readers (the ffx packs
-    /// `0x6cb0e2`/`0x6cb557`/`0x6cb9e1`). Each constant has exactly one reference image-wide — the
-    /// read itself — so they are literals, not `.data` defaults that something else moves.
-    ///
-    /// This is the scalar the death combine turns into its **primary alpha byte** (`0x6cb9ec`:
-    /// `×255.0`, `+512.0`, `fstp`, `shr eax,0xe`) — 0.15 → 38, 0.40 → 102 — and which both combines
-    /// use as the blur² weight. So a ghost's select screen glows at **less than half** a living
-    /// one's, which is the opposite of what "the ghost look is the loud one" would suggest.
-    ///
-    /// (benilla keeps the float rather than the quantized byte: 38/255 = 0.14902 against 0.15 is
-    /// under a thousandth, and the same scalar feeds the in-world glow lane where the reference
-    /// carries a float too.)
+    /// `LightParams.glow` (`0xce9c70`) on a glue screen; the death combine packs it into its alpha
+    /// byte (`0x6cb9ec`: 0.15 → 38, 0.40 → 102). Deviation: kept a float where every reference
+    /// pack (`0x6cb0e2`/`0x6cb557`/`0x6cb9e1`) quantizes it to a byte, because the two differ by
+    /// under a thousandth (38/255 against 0.15).
     fn glow(self) -> f32 {
         match self {
             // `*0x8380b4`, the widget's OnShow pin.
@@ -285,24 +154,17 @@ impl GlueFfx {
     }
 }
 
-/// The haze mix `z` — the combine's screen-toward-blur cross-fade
-/// (`out = lerp(screen, blur, z) + w·blur²`, the shipped FFXGlow.bls). The reference's glow
-/// render packs it per frame from the **active player's** state (`0x6cb134`/`0x6cb599`, wow-re
-/// `ffxeffects/scratch/drunk-blur-z.md`, decision 1009 §A):
-/// `z = max(min(drunkByte,100)/100, submerged ? 84/255 : 0)` — fully blurred at 100 inebriation,
-/// and a fixed ≈0.329 floor whenever the **camera eye** is in any liquid (the vanilla underwater
-/// blur; `0x672470`'s eye-liquid probe, `0xf` = dry). Synced by [`sync_haze`]; uploaded as the
-/// combine uniform's `z`, scaled per view by [`FfxGlow::state_scale`].
+/// The haze mix `z`, the combine's cross-fade toward the blur, packed per frame from the player
+/// (`0x6cb134`/`0x6cb599`): `max(min(drunkByte, 100)/100, submerged ? 84/255 : 0)`, submerged
+/// being the camera eye in any liquid (`0x672470` not `0xf`).
 #[derive(Resource, Clone, Default, ExtractResource)]
 pub struct FfxHazeMix(pub f32);
 
-/// The underwater haze floor: 84/255 (the reference's byte 84 in the COLOR z lane whenever the
-/// eye-liquid probe reads non-dry — applied regardless of sobriety).
+/// The reference's byte 84 in the colour `z` lane while the eye is submerged, drunk or sober.
 const HAZE_SUBMERGED_FLOOR: f32 = 84.0 / 255.0;
 
-/// Sync [`FfxHazeMix`] from the two player-state inputs the reference's glow render reads each
-/// frame: our own drunk byte (`PLAYER_BYTES_3` byte 1 → `min(b,100)/100`) and the camera-eye
-/// submersion claim. Off-world both read empty → 0 (the glue screens never haze).
+/// [`FfxHazeMix`] from the drunk byte (`PLAYER_BYTES_3` byte 1) and the eye's submersion; both
+/// are empty off-world, so a glue screen never hazes.
 fn sync_haze(
     viewer: Res<crate::view::Viewer>,
     underwater: Option<Res<crate::liquid::Underwater>>,
@@ -320,53 +182,29 @@ fn sync_haze(
     }
 }
 
-/// **The GlowWave lane** — the underwater screen warp's two inputs (wow-re
-/// `ffxeffects/scratch/glow-wave-underwater.md`, §5 cross-checked; decision 1824).
-///
-/// Underwater the reference swaps its whole post-process pass list: `CFFXGlow::Render 0x6cc630`
-/// walks a second list whose third pass is **FFXGlowWave** (`0x6cb1f0`, render `0x6cb310`) rather
-/// than FFXGlow, and that pass displaces the combine's two samples through a sine bump map. wow-re's
-/// note had carried the swap as an undecided "GlowWave, *or* a duplicate Glow" for months; the round
-/// that answered it found the arms mutually exclusive and the plain-Glow arm unreachable on both
-/// backends, so a submerged frame is ALWAYS the wave.
-///
-/// **No liquid-type discrimination.** `[0xc7f288] ∈ {0xf dry, 0 water, 1 ocean, 2 magma, 3 slime}`
-/// and `0x6cc644` compares against `0xf` alone — the warp runs in lava and slime exactly as in
-/// water. (That is not the drift cloud's rule, which *does* fork per kind and gives slime no motes
-/// at all; two neighbouring underwater systems reading the same byte with different questions.)
+/// The underwater screen warp's inputs. With the camera eye in liquid, `CFFXGlow::Render`
+/// (`0x6cc630`) walks a second pass list ending in FFXGlowWave (`0x6cb1f0`, render `0x6cb310`),
+/// which displaces the combine's two samples through a sine bump map. The guard compares the
+/// eye-liquid byte `[0xc7f288]` with `0xf` (dry) alone (`0x6cc644`): lava and slime warp too.
 #[derive(Resource, Clone, Copy, Default, ExtractResource)]
 pub struct FfxWave {
-    /// `(t mod 3174)/3174` — the u-axis phase, 3.174 s.
+    /// `(t mod 3174)/3174`, the u-axis phase.
     phase1: f32,
-    /// `(t mod 2805)/2805` — the v-axis phase, 2.805 s. Independent of [`Self::phase1`]: the two
-    /// rejoin only every ~49 minutes, which is what keeps the warp from reading as a loop.
+    /// `(t mod 2805)/2805`, the v-axis phase; the two rejoin only every ~49 minutes.
     phase2: f32,
-    /// Whether the pass-list swap itself is tripped: in-world (`0x467d00`) **and** the camera-eye
-    /// liquid probe non-dry (`0x672470 != 0xf`). Not a strength — the swap is a hard fork, and the
-    /// warp has no ramp in or out.
+    /// The swap: in-world (`0x467d00`) and the eye in liquid (`0x672470` not `0xf`), with no ramp.
     active: bool,
 }
 
-/// The two GlowWave phase periods in milliseconds — `[0xce89c4]` and `[0xce89c8]`, divided into an
-/// integer millisecond clock exactly as the reference's `fild`/`fidiv` pair does.
+/// The phase periods (`[0xce89c4]`, `[0xce89c8]`), moduli of an integer millisecond clock.
 const WAVE_PERIOD_MS: [u64; 2] = [3174, 2805];
 
-/// The wave LUT's edge — 128×128 texels (`[0xce89a0]`'s 7-field descriptor: 128/128/128/128 and
-/// the two 1/128 reciprocals).
+/// The wave LUT is 128×128 texels (`[0xce89a0]`'s descriptor).
 const WAVE_LUT_EDGE: u32 = 128;
 
-/// The reference's glow-wave LUT (`ffx_glow_wave_lut` `0x6cbea0`, a diffed PRIMITIVE), as the
-/// texels our combine samples.
-///
-/// Two channels, one sine each and each depending on ONE axis — `du = sin(2πx/128)` across,
-/// `dv = sin(2πy/128)` down — which is what makes the sampled value a *displacement* rather than an
-/// intensity: the shipped format is the signed two-channel bump format on both backends
-/// (`D3DFMT_V8U8` / `GL_DSDT8_NV`), and the pass is a dependent texture read.
-///
-/// We store the reference's **unsigned** pack (`(s·0.5 + 0.5)·255`, its path B) and bias it back in
-/// the shader, because that is the permutation the live client actually runs: `gxApi` defaults to
-/// direct3d, the shipped `WTF/` overrides nothing, and the caps tier that selects picks the biased
-/// `ps_2_0` blob against an unsigned texture. `as u8` truncates toward zero, which is `__ftol`.
+/// The reference's glow-wave LUT (`0x6cbea0`), a displacement map: `du = sin(2πx/128)`,
+/// `dv = sin(2πy/128)`, stored as the unsigned pack `(s·0.5 + 0.5)·255` that the default Direct3D
+/// path's `ps_2_0` permutation biases back; `as u8` truncates toward zero, as `__ftol` does.
 fn wave_lut_texels() -> Vec<u8> {
     let pack = |s: f32| ((s * 0.5 + 0.5) * 255.0).clamp(0.0, 255.0) as u8;
     let sine = |i: u32| (std::f32::consts::TAU * i as f32 / WAVE_LUT_EDGE as f32).sin();
@@ -381,12 +219,9 @@ fn wave_lut_texels() -> Vec<u8> {
     texels
 }
 
-/// Sync [`FfxWave`] from the same two inputs the reference's swap guard reads, plus the clock its
-/// render method phases on (`OsGetAsyncTimeMs`, `0x6cb43a`).
-///
-/// The phases advance whether or not the wave is armed — they are a free-running wall clock in the
-/// reference too, not a timer the swap starts — so surfacing and diving again does not restart the
-/// pattern, and nothing has to be reset on the transition.
+/// [`FfxWave`] from the swap guard's inputs and the render's clock (`OsGetAsyncTimeMs`,
+/// `0x6cb43a`); the phases run free, armed or not, as the reference's do, so a dive never restarts
+/// them.
 fn sync_wave(
     time: Res<Time>,
     live: Res<crate::schedule::WorldLive>,
@@ -400,11 +235,7 @@ fn sync_wave(
     let verdict = underwater.map(|u| u.0);
     wave.active = live.0 && verdict.is_some_and(|v| v.any());
 
-    // `WOW_WAVE_DUMP` — 1 Hz, and it reports on EVERY frame including the ones that do not warp,
-    // naming why. An instrument that only speaks while the effect is running cannot tell "not
-    // armed" from "armed and broken", which is exactly the hour the drift cloud's first probe cost
-    // (decision 1814 §6b): the effect was off, the screen was silent, and the silence was
-    // indistinguishable from a compile failure.
+    // `WOW_WAVE_DUMP`: a 1 Hz line, warping or not, naming why not.
     if std::env::var_os("WOW_WAVE_DUMP").is_some() {
         let sec = time.elapsed_secs() as u32;
         if last_dump.replace(sec) != Some(sec) {
@@ -422,24 +253,15 @@ fn sync_wave(
     }
 }
 
-/// Whether a view draws the warped combine — the pass-list swap, as a pure function.
-///
-/// Three conditions, each a fact about the reference rather than a taste call:
-/// - the view runs the **WorldFrame** pass pair. The swap lives in `CFFXGlow::Render`, which the
-///   glue screens' own pair also reaches — but its guard's first half is `0x467d00`, the in-world
-///   objmgr gate, so a glue screen can never trip it. A bake runs no pair at all.
-/// - the camera eye is in liquid and we are in-world ([`FfxWave::active`]).
-/// - the player is **not a ghost**. `CFFXDeath` REPLACES `CFFXGlow` outright in the single active
-///   pass slot `[0xce8bb4]`, and `CFFXDeath::Render 0x6cdf20` owns one list and no guard — so a
-///   ghost underwater gets no warp, the same way it already gets no haze.
+/// Whether a view draws the warped combine: the WorldFrame pair (the glue pair reaches the same
+/// render, but the guard's in-world half `0x467d00` never trips there), [`FfxWave::active`], and
+/// no ghost, whose `CFFXDeath::Render` (`0x6cdf20`) has one list and no guard.
 fn wave_armed(state: FfxState, wave: FfxWave, death: f32) -> bool {
     matches!(state, FfxState::Player) && wave.active && death == 0.0
 }
 
-/// Sync the gain from the live zone lighting (the same source `sync_bloom` used). Off-world there
-/// is no `Light.dbc` zone — the reference runs its `LightParams` **default 0.5** (wow-re
-/// death-pass.md: "the zone/time-of-day ambient glow scalar, default 0.5"): the glue screens'
-/// soft glow. (Before this, the glue rendered with the derive-default 0.0 — no glow at all.)
+/// [`FfxGlowGain`]: the zone's `LightParams.glow` in world (its default 0.5 while no lighting
+/// exists), and the glue screen's pin off world ([`GlueFfx::glow`]).
 fn sync_gain(
     lighting: Option<Res<crate::lighting::WowLighting>>,
     live: Res<crate::schedule::WorldLive>,
@@ -449,10 +271,7 @@ fn sync_gain(
     let target = if live.0 {
         lighting.map_or(0.5, |l| l.glow)
     } else {
-        // Off-world the glue screen pins it outright — the widget's OnShow, or the select build's
-        // own fork ([`GlueFfx::glow`], all three byte-verified). It is never `LightParams`' default
-        // here: this arm used to read a flat 0.5 on the reasoning that an off-world client falls
-        // back to the table default, and the bytes say the glue screens pin it instead.
+        // A glue screen always pins the weight; it never falls back to the 0.5 default.
         glue.glow()
     };
     if gain.0 != target {
@@ -460,20 +279,15 @@ fn sync_gain(
     }
 }
 
-/// The FFXGlow pass is MANDATORY on the world camera in the gamma lane (decision 0161): its
-/// combine owns the frame's single gamma→linear decode — without it the whole frame presents
-/// over-bright. Insert on any world camera that lacks it (idempotent; spawn sites also add it).
+/// Adds [`FfxGlow`] to any world camera without it: its combine is the frame's one gamma decode,
+/// without which the frame presents over-bright.
 fn ensure_ffx_glow(
     mut commands: Commands,
     cam: Query<Entity, (With<WorldCamera>, Without<FfxGlow>)>,
     mut with: Query<&mut FfxGlow>,
 ) {
-    // Perf-bisect kill-switch: $WOW_NO_FFX strips the GLOW from every camera — the three filter
-    // passes and the blur term, [`FfxGlow::UI_PANE`]'s shape — and keeps the combine, because in
-    // the gamma lane the combine is not an effect: it is the frame's one decode on a `Write`
-    // view and the UI camera's ground pass on a claimed one (decision 2234), and a frame
-    // without it has no world in it. The frame shows the world un-glowed at its right
-    // brightness; what the lever prices is the blur chain and the glow add.
+    // `WOW_NO_FFX`, a perf lever: every camera drops to `UI_PANE`, no blur and no glow add, but
+    // keeps the combine, which is the frame's decode and the UI camera's ground.
     static NO_FFX: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     if *NO_FFX.get_or_init(|| std::env::var_os("WOW_NO_FFX").is_some()) {
         for mut glow in &mut with {
@@ -496,21 +310,15 @@ fn ensure_ffx_glow(
 #[derive(Debug, Hash, PartialEq, Eq, Clone, RenderLabel)]
 struct FfxGlowLabel;
 
-/// Layouts, sampler, and the four cached pipelines (downsample ×2 share one).
+/// The layouts, samplers, wave LUT and pipelines, built once at startup.
 #[derive(Resource)]
 struct FfxGlowPipelines {
     layout_filter: BindGroupLayoutDescriptor,
     layout_combine: BindGroupLayoutDescriptor,
     sampler: Sampler,
-    /// The 128×128 sine bump map and its own REPEAT sampler — built once here, not per view: the
-    /// LUT is 32 KB of resolution-independent constant, and the reference generates it once too
-    /// (the registration callback `0x6cbcf0`).
-    ///
-    /// REPEAT is load-bearing, not a default. The wave texcoord's scale runs to `W/128` — ten full
-    /// cycles across a 1280-wide screen — so under CLAMP every cycle but the first would pin to the
-    /// edge texel and the warp would vanish over ~90% of the frame. It is byte-closed to
-    /// `D3DTADDRESS_WRAP` (`0x5a2646`/`0x5a266a` through the table `0x80a254 = {CLAMP, WRAP}`), and
-    /// misreading it was the costliest near-miss of the round that derived this.
+    /// The 128×128 sine bump map, built once as the reference builds it (`0x6cbcf0`), and its
+    /// sampler, which must repeat (`D3DTADDRESS_WRAP`, `0x5a2646`/`0x5a266a`): the texcoord spans
+    /// `W/128` cycles, and a clamp would pin all but the first.
     wave_view: TextureView,
     wave_sampler: Sampler,
     downsample: CachedRenderPipelineId,
@@ -519,12 +327,8 @@ struct FfxGlowPipelines {
     combine: FfxCombinePipeline,
 }
 
-/// The combine — specialised on the **format it renders in** (decision 2206, [`crate::final_pass`]):
-/// a view whose camera runs `CameraOutputMode::Skip` gets it rendered straight into the output
-/// texture (a bake's image), a `Write` view into the HDR main texture for bevy's blit to copy
-/// out, as before — and the world view's combine is the UI camera's own pass, keyed on the UI
-/// target (decision 2234, [`FfxBackdrop`]). The three filter passes never leave the ¼-res chain
-/// and stay unspecialised.
+/// The combine, specialised on the format it renders in: a `Skip` camera's output texture, a
+/// `Write` view's HDR main texture ([`crate::final_pass`]), or a backdrop camera's UI target.
 struct FfxCombinePipeline {
     layout: BindGroupLayoutDescriptor,
     shader: Handle<Shader>,
@@ -534,20 +338,13 @@ struct FfxCombinePipeline {
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 struct FfxCombineKey {
     format: TextureFormat,
-    /// The combine as a **gamma-lane** pass (decision 2234): it stores the gamma byte it computed
-    /// and leaves the frame's one decode to the lane that owns it — the UI camera's, at its end,
-    /// for a view this combine grounds ([`FfxBackdrop`]). `false` is the world lane's own exit,
-    /// the decode here (0161).
+    /// Store the gamma byte and leave the decode to the UI camera's lane ([`FfxBackdrop`]);
+    /// `false` decodes here.
     gamma_out: bool,
-    /// The combine drawn INSIDE a 2D main pass — the first draw of a backdrop camera's
-    /// transparent pass — which carries the `Core2d` depth attachment and the view's sample
-    /// count, and a pipeline in that pass must say so (wgpu validates the pair). `None` is the
-    /// combine's own pass: colour only, one sample.
+    /// The sample count of the 2D main pass the combine draws inside, whose depth attachment the
+    /// pipeline must declare (wgpu validates both); `None` is its own colour-only pass.
     inside_2d: Option<u32>,
-    /// The underwater combine (`fs_combine_wave`). A SEPARATE pipeline rather than a branch inside
-    /// `fs_combine`: a dry frame then binds byte-for-byte the pipeline it bound before the warp
-    /// existed and pays nothing at all for it — no extra pass, no extra target, not even a uniform
-    /// branch.
+    /// The underwater entry (`fs_combine_wave`), its own pipeline so a dry frame pays nothing.
     wave: bool,
 }
 
@@ -578,9 +375,7 @@ impl SpecializedRenderPipeline for FfxCombinePipeline {
                     write_mask: ColorWrites::ALL,
                 })],
             }),
-            // Inside a 2D main pass the depth attachment is bound but never consulted: the
-            // ground writes every pixel under everything, and the phase's own items decide
-            // their order among themselves as they always did.
+            // The 2D pass's depth attachment, never tested or written: the ground is under all.
             depth_stencil: key.inside_2d.map(|_| DepthStencilState {
                 format: bevy::core_pipeline::core_2d::CORE_2D_DEPTH_FORMAT,
                 depth_write_enabled: false,
@@ -607,7 +402,7 @@ fn init_pipelines(
 ) {
     let shader: Handle<Shader> =
         asset_server.load("embedded://benilla_world/shaders/ffx_glow.wgsl");
-    // Filter passes bind (tex, sampler); the combine additionally binds (blur tex, gain uniform).
+    // Filter passes bind (tex, sampler); the combine adds the blur, the uniform and the wave LUT.
     let layout_filter = BindGroupLayoutDescriptor::new(
         "ffx_glow_filter_layout",
         &BindGroupLayoutEntries::sequential(
@@ -627,9 +422,7 @@ fn init_pipelines(
                 sampler(SamplerBindingType::Filtering),
                 texture_2d(TextureSampleType::Float { filterable: true }),
                 uniform_buffer_sized(false, Some(std::num::NonZero::new(32).unwrap())),
-                // The wave LUT + its REPEAT sampler ride EVERY combine's layout, dry included, so
-                // the two entry points stay interchangeable behind one bind group. Binding a
-                // texture the dry shader never samples costs the frame nothing.
+                // In every combine's layout, dry included, so both entries share one bind group.
                 texture_2d(TextureSampleType::Float { filterable: true }),
                 sampler(SamplerBindingType::Filtering),
             ),
@@ -642,9 +435,7 @@ fn init_pipelines(
         address_mode_v: AddressMode::ClampToEdge,
         ..Default::default()
     });
-    // LINEAR + REPEAT, both byte-closed: the reference's 128-texel sine is *sampled*, so linear
-    // filtering is what makes it a smooth wave rather than 128 steps, and the wrap is what lets the
-    // texcoord run past 1.0 into its tenth cycle.
+    // Linear, so the reference's 128-texel sine samples as a smooth wave; repeat, past 1.0.
     let wave_sampler = render_device.create_sampler(&SamplerDescriptor {
         min_filter: FilterMode::Linear,
         mag_filter: FilterMode::Linear,
@@ -665,8 +456,7 @@ fn init_pipelines(
                 mip_level_count: 1,
                 sample_count: 1,
                 dimension: TextureDimension::D2,
-                // Two unsigned channels, biased back to signed in the shader — the shipped
-                // permutation's own encoding (see [`wave_lut_texels`]).
+                // Unsigned, biased back to signed in the shader, as the shipped permutation does.
                 format: TextureFormat::Rg8Unorm,
                 usage: TextureUsages::TEXTURE_BINDING | TextureUsages::COPY_DST,
                 view_formats: &[],
@@ -723,39 +513,31 @@ fn init_pipelines(
     });
 }
 
-/// The two ¼-res ping-pong targets (the reference downsamples full→¼ in ONE Box4 pass —
-/// wow-re blur-geometry.md; a ½ intermediate would be one downsample too many), plus the
-/// GPU objects derived from them, so the node does not recreate them per frame.
+/// One view's ¼-res ping-pong pair (the reference downsamples full to ¼ in one Box4 pass,
+/// `0x6ca9d0`) and the GPU objects built from it, kept across frames.
 #[derive(Component)]
 struct FfxGlowTextures {
     quarter_a: CachedTexture,
     quarter_b: CachedTexture,
-    /// The combine's 32-byte uniform — `(gain, death, haze, dither)` then the GlowWave phases.
-    /// Persistent, rewritten each frame with a queue write (queue writes land before the graph's
-    /// submit executes).
+    /// The combine's 32-byte uniform, `(gain, death, haze, dither)` then the wave phases,
+    /// rewritten each frame by a queue write, which lands before the graph's submit.
     gain_buf: Buffer,
-    /// The two Gauss bind groups bind only the ¼-res ping-pong views + sampler — all stable
-    /// while the textures hold. The downsample and combine bind groups bind the view's finished
-    /// main texture, which `ViewTarget::post_process_write` flips per call on a `Write` view, so
-    /// those two are not cached (they would sample last frame's texture) and stay per-frame in
-    /// `run`.
+    /// Cached: the Gauss passes bind only the ¼-res pair. The downsample and combine bind the main
+    /// texture, which `post_process_write` flips per call on a `Write` view, so bind per frame.
     gauss_h_bind: BindGroup,
     gauss_v_bind: BindGroup,
-    /// The combine pipelines for this view, specialised on the format the combine renders in
-    /// for THIS camera's output mode (`FinalPassTarget::format`) — or `None` for a view some
-    /// [`FfxBackdrop`] claims, whose combine is that camera's own pass and not this node's.
+    /// This view's combine pair, keyed on its camera's output (`FinalPassTarget::format`), or
+    /// `None` while an [`FfxBackdrop`] claims the view.
     combine: Option<FfxCombinePair>,
 }
 
-/// One view's combine pipelines — dry and underwater (`fs_combine_wave`) — and the format they
-/// were keyed on: the freshness gate beside the two textures'.
+/// One view's dry and underwater combine pipelines, and the key they were specialised on.
 #[derive(Clone, Copy)]
 struct FfxCombinePair {
     dry: CachedRenderPipelineId,
     wave: CachedRenderPipelineId,
     format: TextureFormat,
-    /// The sample count the pair was keyed on — 1 for a combine's own pass, the view's for a
-    /// backdrop draw inside a 2D main pass.
+    /// 1 for the combine's own pass, the view's count for a backdrop draw inside a 2D main pass.
     samples: u32,
 }
 
@@ -770,8 +552,7 @@ impl FfxCombinePair {
     }
 }
 
-/// What specialising a combine pair takes — the one hand the two prepare systems reach for it
-/// with, so neither carries the three resources separately.
+/// What specialising a combine pair takes, shared by the two prepare systems.
 #[derive(bevy::ecs::system::SystemParam)]
 struct CombineSpecializer<'w> {
     pipeline_cache: Res<'w, PipelineCache>,
@@ -785,8 +566,7 @@ impl CombineSpecializer<'_> {
         self.pair_for(format, false, None)
     }
 
-    /// The backdrop draw inside a 2D main pass of `samples` samples: the gamma-lane exit, the
-    /// pass's depth attachment declared.
+    /// The backdrop draw inside a 2D main pass: the gamma-lane exit, the depth attachment declared.
     fn backdrop_pair(&mut self, format: TextureFormat, samples: u32) -> FfxCombinePair {
         self.pair_for(format, true, Some(samples))
     }
@@ -838,23 +618,12 @@ fn prepare_textures(
         let Some(vp) = camera.physical_viewport_size else {
             continue;
         };
-        // The view's OWN combine pair, specialised **whether or not this view is claimed**
-        // (decision 2262). A claimed view (some [`FfxBackdrop`] names it) has no combine of its
-        // own — the UI camera's ground pass is it, keyed on THAT camera's target — so it carries
-        // none rather than a pair keyed on a target nothing writes. But the claim is not a
-        // property of the world, it is a property of *this frame*: it drops the moment the UI
-        // camera loses its `ViewTarget`, which is what `prepare_view_targets` does as soon as the
-        // window's surface goes away. At app exit that is harmless (bevy runs one to three more
-        // updates after the last presented frame — see `benilla_app::shutdown`) and it is exactly
-        // what the director's 2026-09-15 log caught: two `pipeline compiled LIVE` lines in the
-        // same millisecond as "No windows are open, exiting". A minimize to zero size or a surface
-        // reconfigure reaches the same branch **while the player is looking at the frame**, and
-        // there the pair would be two synchronous Metal compiles on the render thread. Specialising
-        // is a cached lookup on a four-field key, so holding the pair warm from the first covered
-        // frame costs that lookup and nothing else.
+        // Specialised even while claimed: a claim is per frame and drops whenever the UI camera
+        // loses its `ViewTarget` (a minimize, a surface reconfigure), when a cold pair would
+        // compile synchronously on the render thread. Keeping it warm is a cached lookup.
         let own = specializer.pair(FinalPassTarget::format(&camera.output_mode, target));
         let combine = (!claims.0.contains(&entity)).then_some(own);
-        // The reference's RT-dim chain: ½ and ¼, floored (clamp ≥8 — `ffx_compute_rt_dims`).
+        // ¼ of the viewport, each side at least 8, as the reference sizes its targets (`0x6cdb40`).
         let mut tex = |label: &'static str, w: u32, h: u32| {
             texture_cache.get(
                 &render_device,
@@ -876,9 +645,7 @@ fn prepare_textures(
         };
         let quarter_a = tex("ffx_glow_quarter_a", vp.x / 4, vp.y / 4);
         let quarter_b = tex("ffx_glow_quarter_b", vp.x / 4, vp.y / 4);
-        // `TextureCache::get` hands the same textures back while the viewport holds, and the
-        // derived objects only depend on them — rebuilding the component anyway would be right
-        // back to per-frame bind-group creation.
+        // The cache returns the same textures while the viewport holds: rebuild only on a change.
         if existing.is_some_and(|t| {
             t.quarter_a.texture.id() == quarter_a.texture.id()
                 && t.quarter_b.texture.id() == quarter_b.texture.id()
@@ -917,20 +684,9 @@ fn prepare_textures(
     }
 }
 
-/// `WOW_DITHER=1` — arm the combine's deband dither (the shader's `glow.w`).
-///
-/// The frame's ONE quantization to 8 bits is the surface's sRGB present-encode of the combine's
-/// gamma-space output, so a smooth surface steps in 1/255. Measured on a lit bare arm the shading
-/// gradient is ~1.3 levels/px; a breathing idle drifts the body ~0.11 px/frame; so a pixel needs
-/// ~7 FRAMES to cross one step and the shading updates at ~8 Hz under a 60 Hz frame rate. Motion
-/// large enough to clear a level every frame hides it entirely — the reported
-/// small-moves-tick / big-moves-smooth split.
-///
-/// **Off by default because it is a divergence.** The reference's framebuffer was 8-bit and
-/// undithered; this lane is byte-exact against it (0161) and dithering trades that for a smoother
-/// gradient. Bevy would normally apply its own in the tonemapping pass, but `Tonemapping::None`
-/// makes that node return immediately, so the `DebandDither::Enabled` our camera inherits from
-/// `Camera3d` never runs — this is the only place it can live.
+/// `WOW_DITHER=1` arms the combine's deband dither (`ffx.lane.w`). Deviation, opt-in, off by
+/// default: the reference's 8-bit framebuffer is undithered, but a smooth gradient under slow
+/// motion steps visibly at 1/255. Bevy's own dither never runs under `Tonemapping::None`.
 fn dither_armed() -> f32 {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     match *ON.get_or_init(|| std::env::var_os("WOW_DITHER").is_some()) {
@@ -939,20 +695,8 @@ fn dither_armed() -> f32 {
     }
 }
 
-/// The combine's `(x, y, z, w)` uniform for one view — the whole per-view scaling law in one
-/// pure function, so it can be tested without a render world.
-///
-/// - **x** — the zone glow weight, scaled by [`FfxGlow::gain_scale`]: authored *scene* data, so a
-///   portrait bake carries it at world parity (decision 0638) and only a UI model pane drops it,
-///   keeping the combine for its gamma decode alone.
-/// - **y/z** — the FFXDeath gate and the haze mix, both selected by [`FfxGlow::state`]: which pass
-///   pair this view runs decides what drives them, and a bake runs neither pair (decision 1481,
-///   report B49 — now structural rather than arithmetic, decision 1731).
-/// - **w** — the deband-dither arm ([`dither_armed`]), 0 or 1.
-///
-/// The second row is the GlowWave lane: the two phases, written on every frame and read only by
-/// the warped entry point. They are unconditional because they are a free-running clock — gating
-/// the *write* on the arm would make the pattern restart on every dive.
+/// One view's combine uniform: the zone glow × [`FfxGlow::gain_scale`], the death gate and haze of
+/// its pass pair, the dither arm, then the wave phases, written every frame so the clock runs free.
 fn combine_uniform(
     zone_gain: f32,
     world: FfxPassState,
@@ -977,9 +721,7 @@ fn combine_uniform(
     ]
 }
 
-/// One pass pair's live state, as [`combine_uniform`] consumes it: the death gate and the haze mix
-/// that pair carries. The glue pair has no haze lane at all, which is a fact about the reference
-/// and not a value we happen to leave at zero.
+/// One pass pair's live death gate and haze mix.
 #[derive(Clone, Copy)]
 struct FfxPassState {
     death: f32,
@@ -987,22 +729,17 @@ struct FfxPassState {
 }
 
 impl FfxPassState {
-    /// The **WorldFrame** pair's live state: the ghost gate off `PLAYER_FLAGS_GHOST` and the
-    /// drunk/underwater haze, both of the live player.
     fn world(death: f32, haze: f32) -> Self {
         Self { death, haze }
     }
 
-    /// The **glue** pair's live state. Death only, and the constructor is where that is enforced:
-    /// the reference's haze is `primary.z` of the *WorldFrame* glow combine `0x6cb020`, packed from
-    /// the active player's inebriation and the camera-eye liquid probe (`drunk-blur-z.md`) — a glue
-    /// screen has neither, and CGlueMgr's pair has no lane to read them into. Passing a haze here
-    /// should be impossible rather than merely wrong.
+    /// Death only: the reference packs the haze into `primary.z` of the glow combine (`0x6cb020`)
+    /// from the in-world player's state, which a glue screen does not have.
     fn glue(death: f32) -> Self {
         Self { death, haze: 0.0 }
     }
 
-    /// What a view running neither pair reads — a bake.
+    /// What a view running neither pair reads: a bake.
     const INERT: Self = Self {
         death: 0.0,
         haze: 0.0,
@@ -1035,20 +772,14 @@ impl ViewNode for FfxGlowNode {
             pipeline_cache.get_render_pipeline(pipelines.gauss_h),
             pipeline_cache.get_render_pipeline(pipelines.gauss_v),
         ) else {
-            return Ok(()); // pipelines still compiling — draw the frame un-glowed
+            return Ok(()); // pipelines still compiling: the frame draws un-glowed
         };
-        // Where this view's combine lands (2206, `final_pass`): a `Skip` camera's output texture
-        // itself, a `Write` camera's ping-pong for bevy's blit to copy out. A CLAIMED view
-        // (decision 2234, [`FfxBackdrop`]) has no combine here at all: the UI camera's ground
-        // pass is its combine, and samples this view's finished main texture — unflipped, which
-        // is why a claimed camera runs `Skip` — once the filter passes below have built the
-        // blur it reads beside it.
+        // A `Skip` camera's combine lands in its output texture, a `Write` camera's in the
+        // ping-pong bevy's blit copies out ([`crate::final_pass`]); a claimed view has none here.
         let out = match textures.combine.as_ref() {
             None => None,
             Some(pair) => {
-                // THE PASS-LIST SWAP (`0x6cc630`). The reference forks the whole list here; we
-                // fork one pipeline, which is the same fork — the first two passes are identical
-                // in both lists.
+                // The pass-list swap (`0x6cc630`): the two lists differ only in the combine.
                 let Some(combine) = pipeline_cache.get_render_pipeline(pair.armed(wave)) else {
                     return Ok(());
                 };
@@ -1061,31 +792,20 @@ impl ViewNode for FfxGlowNode {
         let render_device = render_context.render_device().clone();
         let diagnostics = render_context.diagnostic_recorder();
 
-        // The combine reads the blur through exactly two terms — `w·blur²` (`lane.x`) and the
-        // haze cross-fade (`lane.z`; the ghost combine has no haze and reads the blur through
-        // the same `x`). With both exactly zero the three filter passes would compute a texture
-        // the combine multiplies by nothing, so they are skipped and the combine samples what
-        // the ¼-res target holds — finite bytes from an earlier frame, or wgpu's zero-init — × 0.
-        // Every UI-pane view (`gain_scale` 0, no haze lane) skips on every frame; the world view
-        // skips in a zone whose `LightParams.glow` is 0 while the eye is dry and sober. The same
-        // shader then runs with the same uniform: look-neutral by construction, and the
-        // journal's `gpu_glow` column reads 0 for a view that skipped (2008).
+        // The combines read the blur only through `w` (`x`) and the haze (`z`); with both zero the
+        // filter passes are skipped, and the stale, finite ¼-res target is multiplied by zero.
         let blur_read = uniform[0] != 0.0 || uniform[2] != 0.0;
         if blur_read {
             let layout_filter = pipeline_cache.get_bind_group_layout(&pipelines.layout_filter);
-            // The downsample binds the finished main texture, which a `Write` view's
-            // `post_process_write` flips per call — this bind group is not cached (it would
-            // sample last frame's texture); the two Gauss ones bind only the stable ¼-res
-            // ping-pong and ride prepared on [`FfxGlowTextures`].
+            // Per frame: a `Write` view flips its main texture per call ([`FfxGlowTextures`]).
             let down_bind = render_device.create_bind_group(
                 "ffx_glow_down_quarter",
                 &layout_filter,
                 &BindGroupEntries::sequential((source, &pipelines.sampler)),
             );
 
-            // The filter passes (byte-pinned chain): source→¼ (one Box4), ¼a→¼b (H), ¼b→¼a (V).
-            // Each pass opens its own diagnostic span (`render/ffx_glow_*/elapsed_gpu` on a
-            // device that times passes): the journal's `gpu_glow` column is their sum (2008).
+            // source → ¼a (one Box4), ¼a → ¼b (Gauss H), ¼b → ¼a (Gauss V), each in its own
+            // diagnostic span; the journal's `gpu_glow` column is their sum.
             let filter_passes: [(&'static str, &RenderPipeline, &BindGroup, &TextureView); 3] = [
                 (
                     "ffx_glow_down_quarter",
@@ -1133,15 +853,13 @@ impl ViewNode for FfxGlowNode {
         let Some((combine, out)) = out else {
             return Ok(()); // claimed: the combine is the UI camera's pass
         };
-        // The uniform is the combine's alone (the filter shaders never bind it), written by
-        // whichever node runs the combine — this one here, the backdrop node for a claimed view.
+        // Written by whichever node runs the combine: this one, or the backdrop node when claimed.
         world.resource::<RenderQueue>().write_buffer(
             &textures.gain_buf,
             0,
             bytemuck::cast_slice(&uniform),
         );
-        // Combine: screen + w·blur² (gamma-space byte math in the shader) → the view's output.
-        // Also binds the flipping `out.source` — per-frame for the downsample's reason.
+        // The combine into the view's output, bound per frame as the downsample is.
         let layout_combine = pipeline_cache.get_bind_group_layout(&pipelines.layout_combine);
         let bind = render_device.create_bind_group(
             "ffx_glow_combine",
@@ -1177,8 +895,7 @@ impl ViewNode for FfxGlowNode {
     }
 }
 
-/// The live inputs of one view's combine, read off the render world: its uniform, and whether
-/// the underwater entry is armed. One reading for the two nodes that can run a combine.
+/// One view's combine uniform and whether its underwater entry is armed, for both combine nodes.
 fn live_combine(world: &World, glow: &FfxGlow) -> ([f32; 8], bool) {
     let death = world.resource::<FfxDeathFade>().0;
     let wave = *world.resource::<FfxWave>();
@@ -1192,41 +909,25 @@ fn live_combine(world: &World, glow: &FfxGlow) -> ([f32; 8], bool) {
     (uniform, wave_armed(glow.state, wave, death))
 }
 
-/// Every view an [`FfxBackdrop`] names this frame: the render-world entities whose combine is
-/// somebody else's pass. Rebuilt in prepare, read by [`prepare_textures`] (no combine pair for a
-/// claimed view) and by the world node (no combine pass).
+/// The render-world views an [`FfxBackdrop`] claims this frame; a claimed view has no combine.
 #[derive(Resource, Default)]
 struct FfxBackdropClaims(Vec<Entity>);
 
-/// A backdrop camera's view, as the render world resolved it this frame: its own combine pair —
-/// specialised on ITS main texture's format with the gamma-lane exit
-/// ([`FfxCombineKey::gamma_out`]), where a world view's pair is keyed on the world's target and
-/// decodes — and the world view it grounds on, a render-world entity whose `ViewTarget` was
-/// prepared THIS frame, or `None`.
+/// A backdrop camera's combine pair (its own target's format, the gamma-lane exit) and the world
+/// view it grounds on, if that view rendered this frame.
 #[derive(Component)]
 struct FfxBackdropView {
     pair: FfxCombinePair,
     source: Option<Entity>,
 }
 
-/// The world views bevy prepared a `ViewTarget` for this frame — the ones that rendered — by
-/// their main-world entity.
+/// The world views bevy prepared a `ViewTarget` for this frame, by main-world entity.
 type RenderedWorldViews<'w, 's> =
     Query<'w, 's, (Entity, &'static MainEntity), (With<FfxGlow>, Changed<ViewTarget>)>;
 
-/// Resolve every [`FfxBackdrop`]: the claims, and each claiming view's pair and source.
-///
-/// The source is looked up among the views whose `ViewTarget` bevy prepared this frame
-/// (`Changed<ViewTarget>`: `prepare_view_targets` re-inserts it for every view it extracted),
-/// by the main-world entity the camera named. A world camera that is active in the main world
-/// but was not rendered this frame — its target's image not yet prepared, the frame it spawned
-/// — resolves to nothing, so the backdrop pass never samples a main texture older than the
-/// frame; and a world view is claimed from its very first rendered frame, so it never builds a
-/// combine pair it would drop a frame later.
-///
-/// The pair is keyed on the view's main texture, which exists from the view's first frame — so
-/// a player-UI camera spawned before the world has its pipelines compiling before there is a
-/// world to hitch on them (`pipe_warm`'s pre-world cover), whether or not it has a source yet.
+/// Resolves every [`FfxBackdrop`]: the claims, and each claiming view's pair and source. A source
+/// must have rendered this frame (`Changed<ViewTarget>`, re-inserted by `prepare_view_targets` for
+/// every extracted view), so the ground never samples a main texture older than the frame.
 fn prepare_backdrops(
     mut commands: Commands,
     mut claims: ResMut<FfxBackdropClaims>,
@@ -1265,24 +966,9 @@ fn prepare_backdrops(
     }
 }
 
-/// **The 2D main pass with the world as its first draw** (decision 2234) — bevy's
-/// `MainTransparentPass2dNode` with one addition, registered under bevy's own label
-/// (`RenderGraph::add_node` is a map insert; the graph's edges, keyed by label, carry over — the
-/// same replacement `benilla_app::opaque2d` makes of the opaque node).
-///
-/// On a view carrying an [`FfxBackdrop`] whose source rendered this frame
-/// ([`FfxBackdropView`]), the pass opens on the view's main texture — taking its first-call clear
-/// — and the world view's combine is drawn before any item of the transparent phase: the
-/// finished world main texture and the blur the world's own node just built, through the
-/// gamma-lane exit, into every pixel. Then the interface, over it, exactly as before.
-///
-/// **Inside the pass, not a pass of its own**, and that is the point on a tile GPU: a render
-/// pass boundary on a full-window target is a store of every tile to memory and a load of every
-/// tile back, so a separate ground pass before this one cost the Air 0.9 ms a frame it did not
-/// cost the RTX (2234's measurement). A draw inside the pass costs the tile nothing but the
-/// fragment work. On any other view — no source, a world that has not drawn yet, a camera that
-/// is not a backdrop camera at all — this is bevy's node to the letter, and the camera's own
-/// clear is the ground, as the backdrop quad's absence was.
+/// Bevy's `MainTransparentPass2dNode` plus one draw: with a backdrop source ([`FfxBackdropView`]),
+/// the world's combine is drawn first, under every transparent item, inside the pass, because on a
+/// tile GPU a pass boundary stores and reloads every tile.
 #[derive(Default)]
 struct FfxTransparent2dNode;
 
@@ -1312,8 +998,7 @@ impl ViewNode for FfxTransparent2dNode {
             return Ok(());
         };
 
-        // The ground: resolved and bound here, drawn inside the pass below. Everything it needs
-        // is read before the pass so the task closure owns only handles.
+        // The ground is resolved and bound before the pass, so the task closure owns only handles.
         let ground = backdrop
             .and_then(|view| view.source.map(|source| (view, source)))
             .and_then(|(view, source)| {
@@ -1327,7 +1012,7 @@ impl ViewNode for FfxTransparent2dNode {
                 let pipelines = world.resource::<FfxGlowPipelines>();
                 let pipeline_cache = world.resource::<PipelineCache>();
                 let (uniform, wave) = live_combine(world, glow);
-                // Still compiling: the frame has no world in it for a frame.
+                // Still compiling: this frame has no world in it.
                 let combine = pipeline_cache.get_render_pipeline(view.pair.armed(wave))?;
                 world.resource::<RenderQueue>().write_buffer(
                     &textures.gain_buf,
@@ -1335,9 +1020,7 @@ impl ViewNode for FfxTransparent2dNode {
                     bytemuck::cast_slice(&uniform),
                 );
                 let layout = pipeline_cache.get_bind_group_layout(&pipelines.layout_combine);
-                // The world view's finished main texture — the very texture its own node would
-                // have combined from — and the ¼-res blur its filter passes built this frame.
-                // Per-frame, as the world node's own combine bind group is.
+                // The world view's finished main texture and this frame's ¼-res blur, per frame.
                 let bind = render_context.render_device().create_bind_group(
                     "ffx_glow_combine",
                     &layout,
@@ -1376,13 +1059,8 @@ impl ViewNode for FfxTransparent2dNode {
                     render_pass.set_camera_viewport(viewport);
                 }
                 if let Some((combine, bind)) = ground.as_ref() {
-                    // No span of its own. A `pass_span` is a pipeline-statistics query as well
-                    // as a timestamp pair, and wgpu allows ONE such query active at a time: a
-                    // second one opened inside the pass's own was the validation error that
-                    // aborted every Vulkan build of the 09-15 sync on its first world frame
-                    // (B390, 2258) — and only Vulkan exposes the feature, so Metal and DX12
-                    // never nested anything and no gate saw it. The transparent pass's number
-                    // carries the combine; the journal never read a nested span.
+                    // No span of its own: a `pass_span` is also a pipeline-statistics query, wgpu
+                    // allows one active at a time, and Vulkan validation fails a nested one.
                     render_pass.set_render_pipeline(combine);
                     render_pass.set_bind_group(0, bind, &[]);
                     render_pass.draw(0..3, 0..1);
@@ -1424,11 +1102,8 @@ impl Plugin for FfxGlowPlugin {
             .add_systems(
                 Update,
                 (
-                    // The gain is the zone's `LightParams.glow`, so the sync is on the resolve's
-                    // read side; the haze floor and the wave's arm are the camera-eye submersion
-                    // verdict, so they are after the slot that writes it. Unordered, both flipped
-                    // a frame late — the underwater blur and warp outlived the surfacing frame
-                    // they belong to, exactly like the sky dome's stops (decision 2032).
+                    // The gain reads the resolved lighting; the haze and the wave read the
+                    // submersion verdict, and would flip a frame late unordered.
                     sync_gain.in_set(crate::lighting::LightingConsumeSet),
                     (sync_haze, sync_wave).after(crate::liquid::SubmersionVerdict),
                     ensure_ffx_glow,
@@ -1457,10 +1132,8 @@ impl Plugin for FfxGlowPlugin {
                     Node3d::Bloom,
                 ),
             )
-            // The 2D main pass with the world as its first draw, replacing bevy's transparent
-            // node under bevy's own label (the edges survive; `benilla_app::opaque2d` does the
-            // same to the opaque node, which is skipped when empty so this pass takes the
-            // target's first-call clear under the ground draw).
+            // Bevy's transparent 2D node, replaced under its own label so the edges survive; the
+            // opaque node (`benilla_app::opaque2d`) skips when empty, leaving this pass the clear.
             .add_render_graph_node::<ViewNodeRunner<FfxTransparent2dNode>>(
                 Core2d,
                 Node2d::MainTransparentPass,
@@ -1476,15 +1149,11 @@ mod tests {
     fn ghost_world() -> FfxPassState {
         FfxPassState::world(1.0, 0.0)
     }
-    /// The glue pair with a living selection — the common case.
     fn living_glue() -> FfxPassState {
         FfxPassState::glue(0.0)
     }
 
-    /// The zone glow is scene data — a portrait bake wants it at world parity (decision 0638) —
-    /// while the death and haze lanes belong to a *pass pair*, and a bake runs neither
-    /// (decision 1481, now structural: 1731). One preset table, checked as a whole so a new preset
-    /// can't quietly join the wrong side.
+    /// Checked as one table, so a new preset cannot quietly join the wrong side.
     #[test]
     fn only_the_two_screen_views_run_a_pass_pair() {
         for (name, view) in [("BOOTH", FfxGlow::BOOTH), ("UI_PANE", FfxGlow::UI_PANE)] {
@@ -1496,14 +1165,13 @@ mod tests {
         }
         assert_eq!(FfxGlow::WORLD.state, FfxState::Player);
         assert_eq!(FfxGlow::GLUE_SCENE.state, FfxState::Glue);
-        // The glow half is unchanged by that law: a bake still glows like the world.
+        // A bake still glows like the world.
         assert_eq!(FfxGlow::BOOTH.gain_scale, 1.0);
         assert_eq!(FfxGlow::GLUE_SCENE.gain_scale, 1.0);
         assert_eq!(FfxGlow::UI_PANE.gain_scale, 0.0);
     }
 
-    /// B49: a released ghost's portrait baked through the FFXDeath combine and came back steel-blue
-    /// luma. The gate reaches the world view and nothing else — while the zone glow still does.
+    /// Death-combined, a ghost's portrait would bake steel-blue; the zone glow still reaches it.
     #[test]
     fn a_ghosts_bake_is_not_death_combined() {
         let zone = 0.5;
@@ -1540,8 +1208,6 @@ mod tests {
         );
     }
 
-    /// The control this refactor must not disturb: the drunk/underwater haze was already
-    /// world-only, and still is.
     #[test]
     fn a_drunk_players_bake_stays_sharp() {
         let (zone, drunk) = (0.5, FfxPassState::world(0.0, 1.0));
@@ -1567,10 +1233,6 @@ mod tests {
         );
     }
 
-    /// **The two pairs are independent, which is the whole point of naming them** (decision 1731).
-    /// The reference has one active-pass slot because its screens take turns; ours coexist, so the
-    /// invariant has to be stated: a ghost on the CHARACTER-SELECT list death-combines the glue
-    /// scene and nothing else, and a released ghost in the WORLD never reaches the glue view.
     #[test]
     fn each_pass_pair_reaches_only_its_own_view() {
         let zone = 0.5;
@@ -1611,11 +1273,7 @@ mod tests {
         );
     }
 
-    /// The glue pair carries **no haze lane** — a fact about the reference (its pair is built by
-    /// CGlueMgr; the haze is `primary.z` of the *WorldFrame* glow combine), enforced by
-    /// [`FfxPassState::glue`] having no way to say otherwise. Pinned so the day someone widens that
-    /// constructor, a test argues back — and pinned against a fully hazed WORLD, which is the state
-    /// that would leak if the two pairs were ever refolded into one.
+    /// Against a fully hazed world, the state that would leak if the two pairs were ever merged.
     #[test]
     fn the_glue_pair_never_hazes() {
         let drunk_world = FfxPassState::world(0.0, 1.0);
@@ -1632,11 +1290,8 @@ mod tests {
         );
     }
 
-    /// **The pass-list swap** (`0x6cc630`) — the three conditions, each independently load-bearing.
-    ///
-    /// The guard is `0x467d00() != 0 && 0x672470() != 0xf`, and the death pass REPLACES the glow
-    /// pass outright rather than composing with it, so a ghost has no wave for the same structural
-    /// reason it has no haze.
+    /// The swap's guard is `0x467d00() != 0 && 0x672470() != 0xf` (`0x6cc630`), and a ghost runs
+    /// the death pass in place of the glow pass.
     #[test]
     fn the_warp_arms_only_for_a_living_submerged_world_view() {
         let wet = FfxWave {
@@ -1667,14 +1322,7 @@ mod tests {
         );
     }
 
-    /// **A dry frame is untouched by this feature** — the perf claim, made structurally rather than
-    /// with a frame counter (the machine that would measure it is busy, and a stopwatch could not
-    /// prove this anyway).
-    ///
-    /// Dry, the uniform's first row is bit-identical to what it was before the warp existed and the
-    /// phase row is inert; the node then selects `combine` — the same pipeline object, compiled at
-    /// the same startup, bound through the same layout. The warp costs a dry frame nothing because
-    /// there is nothing of it in a dry frame, not because its cost is small.
+    /// Dry, the uniform's first row is the plain combine's and the node binds the dry pipeline.
     #[test]
     fn a_dry_frame_pays_nothing_for_the_warp() {
         let live = FfxWave {
@@ -1700,10 +1348,6 @@ mod tests {
         );
     }
 
-    /// The phases are a FREE-RUNNING clock, not a timer the dive starts: they advance whether or not
-    /// the wave is armed, so surfacing and diving again does not restart the pattern. Their periods
-    /// are the reference's own two integer millisecond moduli, and being coprime-ish is what stops
-    /// the warp reading as a loop — they rejoin only every ~49 minutes.
     #[test]
     fn the_two_phases_run_independently_off_one_clock() {
         let phase = |ms: u64, i: usize| (ms % WAVE_PERIOD_MS[i]) as f32 / WAVE_PERIOD_MS[i] as f32;
@@ -1711,7 +1355,7 @@ mod tests {
         // Each wraps on its own period and nowhere else.
         assert!(phase(3173, 0) > 0.999 && phase(3174, 0) == 0.0);
         assert!(phase(2804, 1) > 0.999 && phase(2805, 1) == 0.0);
-        // At its own wrap the OTHER phase is mid-stride — the whole point of two moduli.
+        // At one phase's wrap the other is mid-stride.
         assert!(phase(3174, 1) > 0.13 && phase(3174, 1) < 0.14);
         // The joint period: lcm(3174, 2805) ms ≈ 49 min 28 s.
         let gcd = |mut a: u64, mut b: u64| {
@@ -1725,10 +1369,6 @@ mod tests {
         assert_eq!(joint, 2_967_690);
     }
 
-    /// **The LUT is a displacement map, and each channel bends ONE axis.** That is the fact that
-    /// makes the effect a geometric warp rather than a brightness shimmer, and it is visible in the
-    /// texels: `du` depends only on x, `dv` only on y (the shipped format is the signed two-channel
-    /// bump format on both backends — `D3DFMT_V8U8` / `GL_DSDT8_NV`).
     #[test]
     fn the_wave_lut_is_one_sine_per_axis() {
         let lut = wave_lut_texels();
@@ -1744,8 +1384,8 @@ mod tests {
                 assert_eq!(at(x, y).1, at(0, y).1, "dv must not vary across it");
             }
         }
-        // Biased back the way the shipped ps_2_0 permutation does, every texel is its axis's sine
-        // to within one 8-bit step — the quantization the reference itself ships.
+        // Biased back as the shipped `ps_2_0` permutation does, each texel is its sine within one
+        // 8-bit step, the reference's own quantization.
         for i in 0..edge {
             let want = (std::f32::consts::TAU * i as f32 / edge as f32).sin();
             let got = (at(i, i).0 as f32 / 255.0 - 0.5) * 2.0;
@@ -1756,10 +1396,8 @@ mod tests {
         }
     }
 
-    /// GOLDEN — the reference's own pack, down to the truncation. `ffx_glow_wave_lut`'s path B is
-    /// `(s·0.5 + 0.5)·255` → clamp → `__ftol`, and `__ftol` truncates toward zero rather than
-    /// rounding: `sin = 0` packs to **127**, not 128, so the map carries a half-step DC bias the
-    /// reference carries too. Rounding here would be a "cleaner" number and the wrong one.
+    /// The reference packs `(s·0.5 + 0.5)·255`, clamps, and truncates by `__ftol`: `sin = 0` packs
+    /// to 127, not 128, a half-step bias the reference ships too.
     #[test]
     fn the_wave_pack_truncates_like_ftol() {
         let lut = wave_lut_texels();
@@ -1771,12 +1409,7 @@ mod tests {
         assert_eq!(lut[96 * 2], 0, "sin(3π/2) = −1 → 0");
     }
 
-    /// GOLDEN — the three writers of the glue screens' `LightParams.glow`, and the alpha byte the
-    /// death combine quantizes the ghost one into. Every number byte-VERIFIED (wow-re
-    /// `glue-select-ghost-treatment.md`); each constant has exactly one reference image-wide.
-    ///
-    /// The default is a shown-but-unselected glue screen — login, create, and an empty account —
-    /// which is the state the login screen renders in and which is NOT either select arm.
+    /// The default is the shown, unselected glue screen (login, create, an empty account).
     #[test]
     fn the_glue_screens_pin_three_verified_glow_weights() {
         assert_eq!(GlueFfx::default(), GlueFfx::Shown);
@@ -1787,12 +1420,12 @@ mod tests {
         );
         assert_eq!(GlueFfx::SelectLiving.glow(), 0.40, "*0x838574");
         assert_eq!(GlueFfx::SelectGhost.glow(), 0.15, "*0x838570");
-        // Only the ghost arm installs the death pass, and it is the only arm that does.
+        // Only the ghost arm installs the death pass.
         assert_eq!(GlueFfx::SelectGhost.death(), 1.0);
         assert_eq!(GlueFfx::Shown.death(), 0.0);
         assert_eq!(GlueFfx::SelectLiving.death(), 0.0);
-        // The combine's primary alpha byte (`0x6cb9ec`: ×255, +512, fstp, shr 14) — 38 ghosted,
-        // 102 living. A ghost's screen glows at less than half a living one's.
+        // The packed byte (`0x6cb9ec`: ×255, +512, `fstp`, `shr 14`): 38, the ghost's death
+        // combine alpha, and 102, the living glow pass's `w`.
         let alpha_byte = |glow: f32| ((glow * 255.0 + 512.0).to_bits() >> 14) & 0xff;
         assert_eq!(alpha_byte(GlueFfx::SelectGhost.glow()), 38);
         assert_eq!(alpha_byte(GlueFfx::SelectLiving.glow()), 102);
diff --git a/crates/benilla-world/src/final_pass.rs b/crates/benilla-world/src/final_pass.rs
index a3564464..e16f856a 100644
--- a/crates/benilla-world/src/final_pass.rs
+++ b/crates/benilla-world/src/final_pass.rs
@@ -1,30 +1,11 @@
-//! **Where a colour lane's final pass lands** (decision 2206) — the one rule the FFXGlow combine
-//! ([`crate::ffx_glow`]) and the UI gamma decode (`benilla_app::ui_gamma`) share.
-//!
-//! Each of benilla's two colour lanes ends in a full-screen pass that owns the frame's one gamma
-//! decode (0161 for the world, 0254 for the UI). Bevy's default for a camera is
-//! [`CameraOutputMode::Write`]: that pass writes the view's main texture, and bevy's `upscaling`
-//! node then **blits** the result into the camera's target — a pure copy of every pixel, once per
-//! camera. On the Windows lab's RTX that copy was the costliest pass of the frame (2205: `upscaling`
-//! 1.1–1.4 ms of a 4.3 ms GPU frame, both cameras' blits summed), and on a tile GPU it is one more
-//! full-screen pass on the render thread 1975 called the floor.
-//!
-//! With the camera set to [`CameraOutputMode::Skip`] the blit is off, and the lane's final pass
-//! renders **straight into the target** — a `Skip` bake's combine into its image, the UI camera's
-//! decode into the swapchain. Same shader, same values, one full-screen pass fewer per camera;
-//! the pipeline is specialised on the target's format because that is now the format it writes.
-//! (The world camera's combine no longer lands anywhere of its own: since decision 2234 it is
-//! the first draw of the UI camera's main pass, `ffx_glow::FfxBackdrop`, and the world's target is a size-carrier
-//! nothing writes — so a claimed world view never resolves a destination at all.) The first use of the output in a frame is a clear rather than a load: a fast clear on an
-//! immediate-mode GPU, and on a tile GPU the difference between not reading the old contents and
-//! reading them — the fullscreen triangle covers every pixel of the viewport either way.
-//!
-//! A `Write` camera keeps the ping-pong ([`ViewTarget::post_process_write`]) and the blit, exactly
-//! as before: a bake's own `clear_color` and viewport (the glue booth's pillarbox, 1619) are the
-//! blit's to honour, and `benilla-worldview` has no reason to change. So the choice is the camera's
-//! — made where the camera is spawned — and a node only reads it. **The one hazard is the
-//! half-way state:** a `Skip` camera whose final pass never ran presents a target nothing wrote.
-//! That is why `$WOW_NO_FFX` (`ffx_glow::ensure_ffx_glow`) strips the glow and keeps the combine.
+//! Where a colour lane's final pass lands, for the FFXGlow combine ([`crate::ffx_glow`]) and the UI
+//! gamma decode (`benilla_app::ui_gamma`). A [`CameraOutputMode::Write`] camera keeps bevy's
+//! ping-pong and `upscaling` blit, which honours a bake's clear colour and viewport; a
+//! [`CameraOutputMode::Skip`] camera's final pass renders straight into the target, in its format,
+//! clearing it rather than loading it, since the fullscreen triangle covers the viewport either
+//! way. A world view the UI camera claims (`ffx_glow::FfxBackdrop`) resolves none: its combine is
+//! the first draw of that camera's main pass. A `Skip` camera whose final pass never ran presents
+//! a target nothing wrote, which is why `$WOW_NO_FFX` keeps the combine.
 
 use bevy::camera::{CameraOutputMode, Viewport};
 use bevy::color::LinearRgba;
@@ -34,24 +15,19 @@ use bevy::render::render_resource::{
 };
 use bevy::render::view::ViewTarget;
 
-/// One final pass's source and destination for one view — the seam's one noun. Its two
-/// associated functions are the two halves of the rule: [`Self::format`] for the pipeline (at
-/// prepare), [`Self::resolve`] for the pass (in the node).
+/// One final pass's source and destination for one view: [`Self::format`] at prepare for the
+/// pipeline, [`Self::resolve`] in the node for the pass.
 pub struct FinalPassTarget<'a> {
     /// The finished main texture the pass reads.
     pub source: &'a TextureView,
-    /// The attachment it renders into: the output texture (`Skip`) or the other main texture
-    /// (`Write`).
+    /// The output texture (`Skip`) or the other main texture (`Write`).
     pub destination: RenderPassColorAttachment<'a>,
-    /// A `Skip` camera's viewport, to be applied as the pass's scissor — what bevy's blit does for
-    /// the same camera. `None` covers the whole target.
+    /// A `Skip` camera's viewport, as the pass's scissor; `None` covers the whole target.
     pub scissor: Option<&'a Viewport>,
 }
 
 impl<'a> FinalPassTarget<'a> {
-    /// The format a lane's final pass renders in, for a view whose camera runs `output_mode`:
-    /// the output texture's own for a `Skip` camera, the main texture's for a `Write` one. What
-    /// the pass's pipeline is specialised on.
+    /// The format the final pass renders in, which its pipeline is specialised on.
     pub fn format(output_mode: &CameraOutputMode, target: &ViewTarget) -> TextureFormat {
         match output_mode {
             CameraOutputMode::Skip => target.out_texture_view_format(),
@@ -59,9 +35,8 @@ impl<'a> FinalPassTarget<'a> {
         }
     }
 
-    /// Resolve a view's final pass target from its camera's output mode. Call **once** per view
-    /// per frame: the `Write` arm takes the view's post-process write, which flips the main
-    /// texture.
+    /// Resolve a view's final pass target. Call once per view per frame: the `Write` arm takes the
+    /// view's post-process write, which flips the main texture.
     pub fn resolve(camera: &'a ExtractedCamera, target: &'a ViewTarget) -> Self {
         match camera.output_mode {
             CameraOutputMode::Skip => Self {
@@ -85,8 +60,7 @@ impl<'a> FinalPassTarget<'a> {
         }
     }
 
-    /// The scissor rect the pass sets on its render pass — `(x, y, width, height)` in physical
-    /// pixels — when [`Self::scissor`] names one.
+    /// The pass's scissor rect, `(x, y, width, height)` in physical pixels.
     pub fn scissor_rect(&self) -> Option<(u32, u32, u32, u32)> {
         self.scissor.map(|viewport| {
             (
diff --git a/crates/benilla-world/src/frame_pace.rs b/crates/benilla-world/src/frame_pace.rs
index 3c9d2623..2d8d3344 100644
--- a/crates/benilla-world/src/frame_pace.rs
+++ b/crates/benilla-world/src/frame_pace.rs
@@ -1,48 +1,12 @@
-//! **Frame pacing** — the clock we animate on follows the *presentation* cadence, not the CPU loop.
+//! Frame pacing: `Time<Virtual>` advances on the presentation cadence, not the CPU loop. Under
+//! `PresentMode::Fifo` frames are shown on refresh boundaries, but `Time<Real>` is stamped where
+//! the main thread waits on the render thread, so two frames shown 16.67 ms apart can measure
+//! 26.4 and 8.0 ms, and every bone of a standing model jitters at once. When recent deltas look
+//! vsync'd, each is snapped to a whole number of refresh periods and the remainder carried, so
+//! elapsed time still matches the wall clock; otherwise (uncapped, a real stall) it passes through.
 //!
-//! Under `PresentMode::Fifo` (our default — `video::present_mode`) a frame is displayed only on a
-//! refresh boundary, so the interval the eye receives is always an exact multiple of the monitor's
-//! period. The interval we *measure* is not: Bevy stamps `Time<Real>` once per main-schedule pass,
-//! and with pipelined rendering the main thread's wait for the render thread is where vsync
-//! back-pressure lands. That wait moves around, so two frames shown 16.67 ms apart can be measured
-//! as 26.4 ms and 8.0 ms. Their sum is right; the split is not.
-//!
-//! Advancing an animation by that split samples the pose at instants the display never shows: the
-//! model lurches ahead by the long delta, then barely moves on the short one. It is a rigid,
-//! whole-skeleton motion — every bone at once — which is exactly how it was reported ("a lot of
-//! jitter on the whole model", standing still, hands off the mouse), and why it is invisible until
-//! you are zoomed close enough for a fraction of a millimetre to be a pixel.
-//!
-//! **Measured at the Elwynn guard pin** (`.go xyz -9481.53 76.10 56.57 0`, 3200×1800, camera
-//! parked, no input), 1805 frames of steady state:
-//!
-//! - 77 frames (4.3%) had a delta more than 3 ms off the 16.663 ms median.
-//! - **27 of them were long/short PAIRS summing to an exact multiple of the refresh** — (26.4, 8.0),
-//!   (25.3, 8.0), (20.2, 13.2), (25.9, 7.1) — i.e. both frames were presented on cadence and only
-//!   the timestamps were split wrong. Just 3 were genuine dropped frames.
-//! - 91% of 10-frame windows summed to within 2 ms of 166.7 ms: presentation stayed locked.
-//! - The median bone's Δ tracked `dt` proportionally (`Δ/dt` constant to three digits), so the pose
-//!   is *correct for the time it is handed*. The time is what is wrong.
-//! - Whole-skeleton events (up to 91 of 117 bones past a quarter-pixel in one frame) landed on
-//!   those frames **95%** of the time: `P(twitch | bad delta) = 0.26` against `0.0006` otherwise.
-//!
-//! **What this does.** When the recent deltas look like a vsync cadence, the raw delta is snapped to
-//! the nearest whole multiple of the estimated refresh period and the remainder is carried into the
-//! next frame, so the long-run elapsed time still matches the wall clock exactly — no time is
-//! invented and none is lost. When the cadence does not look like vsync (uncapped, a genuine hitch,
-//! a load spike) the raw delta passes through untouched: pacing must never paper over a real stall,
-//! only correct a mis-split one.
-//!
-//! **Why `Time<Virtual>` and not `Time<Real>`.** `Real` is the wall clock, and the probe harness is
-//! required to read it (`capture::probes::ProbeClock`, decision 0789) precisely so a hitching run
-//! cannot silently under-run a knob. Pacing it would hide the defect from the instrument that found
-//! it. `Virtual` is Bevy's own *adjustable* game clock and is what `advance_animations`, the
-//! particle/ribbon sims and `Time<Fixed>` all derive from — one correction there reaches every
-//! animating consumer, which is the point: this is not a rig defect, it is a clock defect.
-//!
-//! `WOW_NO_FRAME_PACE=1` turns it off — the A/B lever, same shape as `WOW_NO_RIG_REBASE`. A
-//! hand-driven clock (`TimeUpdateStrategy::Manual*` — the capture harness, the deterministic
-//! tests) is never paced: those runs exist to reproduce frame-for-frame.
+//! `Time<Real>` stays unpaced because probes read it and a stall must stay visible there.
+//! `WOW_NO_FRAME_PACE=1` turns pacing off, and a manual `TimeUpdateStrategy` is never paced.
 
 use std::collections::VecDeque;
 use std::time::Duration;
@@ -50,29 +14,26 @@ use std::time::Duration;
 use bevy::prelude::*;
 use bevy::time::{Real, TimeSystems, TimeUpdateStrategy, Virtual};
 
-/// How many recent raw deltas the refresh estimate is taken over — about a third of a second at
-/// 60 Hz, long enough for a median to be stable and short enough to follow a refresh-rate change.
+/// Recent raw deltas the refresh-period median is taken over, about a third of a second at 60 Hz.
 const WINDOW: usize = 20;
 /// A sample counts as "on cadence" when it is within this fraction of the median.
 const TIGHT: f64 = 0.15;
-/// Engage only when at least this fraction of the window is on cadence — below it we are not
-/// looking at a vsync'd stream and snapping would be a lie.
+/// Pacing engages only when at least this share of the window is on cadence.
 const TIGHT_SHARE: f64 = 0.6;
-/// How far the unspent remainder may run before we stop trying to account for the frame in whole
-/// refreshes and report it as it happened. This is what keeps a genuine stall visible.
+/// The largest remainder, in periods, still worked off in whole refreshes; beyond it the frame is
+/// a stall and passes through raw.
 const CARRY_MAX: f64 = 1.5;
-/// The largest multiple worth snapping to: past four dropped frames it is a stall, not a mis-split.
+/// The largest multiple snapped to; a longer frame is a stall, not a mis-split.
 const MAX_MULT: f64 = 4.0;
 
-/// The pacer's running state: the cadence estimate, the unspent remainder, and the paced total.
 #[derive(Resource)]
 pub(crate) struct FramePacer {
     /// Recent raw deltas (seconds), for the refresh-period median.
     hist: VecDeque<f64>,
-    /// Time measured but not yet handed out, so the long-run sum is exact. Bounded by one period.
+    /// Time measured but not yet handed out, within [`CARRY_MAX`] periods.
     carry: f64,
-    /// The paced elapsed total — what `Time<Virtual>::elapsed` is rewritten to. `None` until the
-    /// first paced frame adopts whatever Bevy had, so the clock never jumps at start-up.
+    /// What `Time<Virtual>::elapsed` is rewritten to; `None` until the first paced frame adopts
+    /// Bevy's own, so the clock never jumps.
     total: Option<Duration>,
     /// `WOW_NO_FRAME_PACE=1`.
     off: bool,
@@ -108,21 +69,10 @@ impl FramePacer {
         (tight as f64 >= TIGHT_SHARE * v.len() as f64).then_some(period)
     }
 
-    /// Snap `raw` to the presentation cadence, carrying the remainder. Returns `raw` unchanged
-    /// whenever snapping would not be honest.
-    ///
-    /// **One call to this is one presented frame, so the answer is one refresh period** unless
-    /// frames were genuinely dropped — and that asymmetry is the whole rule. Rounding `want/period`
-    /// to nearest instead gets the case this exists for exactly backwards: the measured long half
-    /// of a mis-split pair reads 26.4 ms = 1.58 periods, rounds *up* to 2, and the frame that was
-    /// really shown for one refresh is paced as two. So the multiple is taken as a FLOOR, and only
-    /// once `want` has actually reached 1.5 periods — meaning the remainder says we are a whole
-    /// frame behind — is anything above 1 considered.
-    ///
-    /// The remainder is carried, not discarded, so this only ever re-distributes time: over any
-    /// run the paced total tracks the wall clock to within one period. When the remainder cannot be
-    /// worked off in whole refreshes ([`CARRY_MAX`]) the frame is not a mis-split at all — it is a
-    /// stall — and the raw delta passes through so the hitch stays visible.
+    /// Snaps `raw` to the presentation cadence, carrying the remainder, or returns it unchanged
+    /// for a stream that is not vsync'd and for a stall. One call is one presented frame, so the
+    /// multiple is 1 until `raw` plus the carry reaches 1.5 periods, then a floor: rounding would
+    /// pace the 26.4 ms long half of a mis-split pair (1.58 periods) as two frames.
     fn pace(&mut self, raw: f64) -> f64 {
         if self.hist.len() == WINDOW {
             self.hist.pop_front();
@@ -132,10 +82,9 @@ impl FramePacer {
             self.carry = 0.0;
             return raw;
         };
-        // Spend what the wall clock gave us plus whatever the last frame did not use.
         let want = raw + self.carry;
         if want < 0.0 {
-            // We are ahead of the wall clock by more than this frame is worth: stop inventing.
+            // Ahead of the wall clock by more than this frame is worth: stop inventing time.
             self.carry = 0.0;
             return raw;
         }
@@ -147,7 +96,7 @@ impl FramePacer {
         let snapped = mult * period;
         let carry = want - snapped;
         if carry.abs() > CARRY_MAX * period {
-            // Not a mis-split — a real stall. Report it as it happened.
+            // A real stall, not a mis-split: report it as it happened.
             self.carry = 0.0;
             return raw;
         }
@@ -156,16 +105,10 @@ impl FramePacer {
     }
 }
 
-/// Rewrite `Time<Virtual>` (and the generic `Time` derived from it) so this frame's delta is the
-/// paced one. Runs straight after Bevy's own clock tick, before anything reads a delta.
-///
-/// Bevy exposes no delta setter, so the clock is rebuilt: its context and wrap period are carried
-/// over, then two `advance_by` calls place `elapsed` at the paced total with `delta` as the paced
-/// step. Both are O(1) — `advance_by` is plain field arithmetic.
-///
-/// **Paused or time-scaled virtual time passes straight through**, untouched. `Virtual`'s cached
-/// `effective_speed` is private, so a rebuilt clock cannot honour a scale correctly, and pacing a
-/// clock that is deliberately not tracking wall time is meaningless anyway.
+/// Rewrites `Time<Virtual>` and the generic `Time` so this frame's delta is the paced one; runs
+/// right after Bevy's clock tick. Bevy has no delta setter, so the clock is rebuilt with its
+/// context and wrap period, and two `advance_by` calls place `elapsed` and `delta`. Paused or
+/// scaled virtual time passes through, since `Virtual`'s `effective_speed` is private.
 pub(crate) fn pace_virtual_time(
     real: Res<Time<Real>>,
     mut virt: ResMut<Time<Virtual>>,
@@ -173,12 +116,7 @@ pub(crate) fn pace_virtual_time(
     mut pacer: ResMut<FramePacer>,
     strategy: Option<Res<TimeUpdateStrategy>>,
 ) {
-    // A hand-driven clock is never a presentation cadence. The capture harness and the
-    // deterministic tests set `ManualInstant`/`ManualDuration` precisely so a run reproduces
-    // frame-for-frame; snapping their steps to a median would make the output depend on the
-    // machine, which is the one thing those captures exist to rule out. (With a *constant* manual
-    // delta the snap happens to be identity anyway — this guard is so that stays true by
-    // construction rather than by luck.)
+    // A manual clock (the capture harness, deterministic tests) must reproduce frame for frame.
     let manual = matches!(
         strategy.as_deref(),
         Some(TimeUpdateStrategy::ManualInstant(_) | TimeUpdateStrategy::ManualDuration(_))
@@ -190,7 +128,6 @@ pub(crate) fn pace_virtual_time(
     }
     let paced =
         Duration::from_secs_f64(pacer.pace(real.delta().as_secs_f64())).min(virt.max_delta());
-    // First paced frame adopts Bevy's own elapsed, so nothing jumps when this engages.
     let total = pacer.total.unwrap_or(virt.elapsed()) + paced;
     pacer.total = Some(total);
 
@@ -205,7 +142,7 @@ pub(crate) fn pace_virtual_time(
     *generic = virt.as_generic();
 }
 
-/// `WOW_FIXED_DT`'s pending arm — see [`plugin`].
+/// `WOW_FIXED_DT`'s pending arm (see [`plugin`]).
 #[derive(Resource)]
 struct FixedDt {
     dt: Duration,
@@ -213,8 +150,7 @@ struct FixedDt {
     armed: bool,
 }
 
-/// Install the manual strategy once the wall clock passes the arm time, and say so in the log —
-/// a run whose clock silently failed to pin would read exactly like a run that measured something.
+/// Installs the manual strategy once the wall clock passes the arm time, and logs it.
 fn arm_fixed_dt(mut cfg: ResMut<FixedDt>, mut commands: Commands) {
     if cfg.armed || std::time::Instant::now() < cfg.at {
         return;
@@ -228,25 +164,11 @@ fn arm_fixed_dt(mut cfg: ResMut<FixedDt>, mut commands: Commands) {
 }
 
 pub fn plugin(app: &mut App) {
-    // **`WOW_FIXED_DT=<ms>` — the deterministic clock**, and it exists for one question that no
-    // other instrument here can answer: *is the RENDERED motion even?*
-    //
-    // A per-frame screenshot burst is the only way to measure what the eye actually receives, and
-    // saving a 3200x1800 PNG stalls the frame to tens of milliseconds — so the burst perturbs the
-    // very timing it is trying to measure, and its frames sample the animation on a grid as ragged
-    // as the capture. Pinning the advance makes the geometry side perfectly even BY CONSTRUCTION,
-    // so any unevenness left in the captured pixels belongs to the render, not the clock. That is
-    // the whole discrimination: a body whose bones all move sub-pixel per frame can be flawless in
-    // world space and still step on screen, and only this pairing separates the two.
-    //
-    // It composes with the pacer rather than fighting it: `Time<Real>` drives `Time<Virtual>`, and
-    // [`pace_virtual_time`] stands down the moment a manual strategy is set.
-    // Spelled `<ms>[,<arm_after_wall_seconds>]`, default 40 s. **The delay is not a convenience,
-    // it is required**: a manual strategy overrides `Time<Real>`, which is the clock every probe
-    // trigger reads, and during load the app is not vsync-limited — it ran ~385 updates/second, so
-    // a pinned 16.6667 ms clock reached "90 seconds" in 14 s of wall time and the run exited before
-    // the character had finished streaming in. Arming on a real wall-clock `Instant` keeps the
-    // pinning for the part of the run that is being measured and leaves login/teleport on real time.
+    // `WOW_FIXED_DT=<ms>[,<arm_after_wall_seconds>]` (default 40 s) pins the animation step, so a
+    // per-frame screenshot burst, whose PNG saves stall every frame, measures the render's
+    // evenness and not the clock's; [`pace_virtual_time`] stands down under it. The arm delay is
+    // required: a manual strategy also drives `Time<Real>`, which probe triggers read, and during
+    // an unthrottled load it would race far ahead of the wall before the character streams in.
     if let Some((ms, after)) = std::env::var("WOW_FIXED_DT").ok().and_then(|v| {
         let (ms, after) = match v.split_once(',') {
             Some((a, b)) => (a, b.trim().parse::<f64>().ok()?),
@@ -276,8 +198,6 @@ mod tests {
         }
     }
 
-    /// The whole point: a long/short PAIR that sums to two refresh periods comes back out as two
-    /// equal periods — which is what the display actually showed — and nothing is invented.
     #[test]
     fn a_mis_split_pair_is_restored_to_the_cadence_the_display_showed() {
         let mut p = pacer();
@@ -285,7 +205,7 @@ mod tests {
         for _ in 0..WINDOW {
             p.pace(period);
         }
-        // The measured split of two on-cadence frames: 26.4 ms then 8.0 ms (the real reading).
+        // A measured split of two on-cadence frames.
         let a = p.pace(0.0264);
         let b = p.pace(0.0080);
         assert!(
@@ -296,22 +216,19 @@ mod tests {
             (b - period).abs() < 1.0e-6,
             "short half snapped to one period: {b}"
         );
-        // And the pair still spends exactly what the wall clock measured, to within the carry.
         assert!(
             ((a + b) - (0.0264 + 0.0080)).abs() <= period,
             "no time invented or lost beyond one period of carry"
         );
     }
 
-    /// Long-run elapsed must track the wall clock exactly — the carry exists so that snapping is a
-    /// re-distribution, never a drift. A thousand jittered frames may not gain or lose a frame.
     #[test]
     fn snapping_redistributes_time_it_never_creates_or_destroys_it() {
         let mut p = pacer();
         let period = 1.0 / 60.0;
         let mut raw_total = 0.0;
         let mut paced_total = 0.0;
-        // A deterministic long/short jitter around the cadence, the shape the measurement showed.
+        // Long/short jitter around the cadence, the measured shape.
         for i in 0..1000 {
             let raw = match i % 4 {
                 0 => period * 1.55,
@@ -329,8 +246,6 @@ mod tests {
         );
     }
 
-    /// A genuinely dropped frame IS two periods — pacing must not flatten a real 30 Hz stretch
-    /// into 60 Hz, or the clock would run slow for as long as the drop lasts.
     #[test]
     fn a_dropped_frame_is_paced_as_two_periods_not_one() {
         let mut p = pacer();
@@ -345,7 +260,6 @@ mod tests {
         );
     }
 
-    /// A real stall is NOT smoothed away: pacing corrects a mis-split, it does not hide a hitch.
     #[test]
     fn a_genuine_stall_passes_through_unpaced() {
         let mut p = pacer();
@@ -353,15 +267,14 @@ mod tests {
         for _ in 0..WINDOW {
             p.pace(period);
         }
-        let stall = 1.82; // the 1820 ms streaming stall the same run caught
+        let stall = 1.82; // a measured streaming stall
         assert_eq!(p.pace(stall), stall, "a stall is reported as it happened");
     }
 
-    /// An uncapped (non-vsync) stream never engages: with no cadence there is nothing to snap to.
     #[test]
     fn an_uncapped_stream_is_left_alone() {
         let mut p = pacer();
-        // Wildly varying frame times — a `PresentMode::AutoNoVsync` run.
+        // Frame times of a `PresentMode::AutoNoVsync` run.
         let raws = [0.004, 0.011, 0.0031, 0.019, 0.0072, 0.0155, 0.0028, 0.0093];
         for i in 0..WINDOW * 2 {
             let raw = raws[i % raws.len()];
diff --git a/crates/benilla-world/src/ground_fx.rs b/crates/benilla-world/src/ground_fx.rs
index ae9d9ee0..c694b018 100644
--- a/crates/benilla-world/src/ground_fx.rs
+++ b/crates/benilla-world/src/ground_fx.rs
@@ -1,31 +1,9 @@
-//! Ground-level spell-effect quads as **projected surface decals** — the third client of the
-//! shared decal projector (`decal.rs`), after the selection ring and the unit blob shadow.
+//! Ground-level spell-effect quads ([`benilla_formats::GroundQuad`]: Battle Shout's crescents, the
+//! paladin auras' rings, Consecration's burn disc) drawn as decals through the shared projector.
 //!
-//! A base-anchored effect model's flat ground-plane quads (Battle Shout's six crescents, the
-//! paladin auras' rings, Consecration's and Flamestrike's hovering burn discs —
-//! [`benilla_formats::GroundQuad`], the `groundscan` z=0 + hover populations) author every
-//! vertex on one ground-level plane (z = 0, or hovering fractions of a yard above it) with depth-test ON: drawn as
-//! free geometry they are buried per-pixel by the first up-slope and float over the first
-//! down-slope. The real 1.12 client draws them exactly that way (standard M2 batch pipeline —
-//! no ground conform exists in the spell-visual chain); this lane is a deliberate modern
-//! improvement, director-directed: anything that *needs ground level* renders like the ring does.
-//!
-//! Mechanism: the game's fx attach (`benilla::entities`) spawns one [`GroundFxDecal`] entity per ground quad
-//! of a base-anchored instance instead of a mesh child. Each frame ([`update_ground_fx_decals`],
-//! in [`crate::billboard::BillboardPlace`] — post-propagation, like the cards), the quad's four
-//! authored corners are posed through its live joint × the bone's inverse bindpose (exactly the
-//! skinned-vertex path, so the authored slide/spin/scale animation is preserved); when the posed
-//! corners moved (0733 §5 — the ShadowKey treatment; a static pose costs a compare), a
-//! projection frame is fitted to the posed rectangle and the ground triangles inside it are
-//! re-emitted with the quad's own UVs bilerped across the frame — the crescent drapes the
-//! terrain it crosses. The cached triangles are pushed onto the shared effect stream every
-//! frame with the part's authored identity riding the draw record: its blend
-//! ([`crate::particles::buffer::EffectBlend::from_model`]), its `0x70baf0` fog policy, its
-//! M2Color RGB loop and `MatAnim` alpha loop sampled into the vertex tint at push time (the old
-//! path's per-instance material clones and their per-frame mutations are gone). A decal
-//! despawns when its joint does (the effect instance's reap/self-termination), the billboard
-//! cards' orphan rule; it pushes nothing when no receiving surface is in the box (mid-air), the
-//! ring's no-ground gate.
+//! Deviation: the 1.12 client draws these flat quads as ordinary depth-tested M2 batches, so an
+//! up-slope buries them and a down-slope leaves them floating; here they drape the terrain like
+//! the selection ring, because an effect meant for ground level should sit on it.
 
 use avian3d::prelude::Collider;
 use benilla_assets::coords::wow_to_bevy;
@@ -38,56 +16,40 @@ use crate::decal::{project_decal, DecalFrame};
 use crate::particles::buffer::{EffectBlend, EffectDrawSpec, EffectFog, EffectQuads, EffectVertex};
 use crate::view::WorldCamera;
 
-/// One ground-quad decal: the live effect-rig joint it rides, the authored quad it projects,
-/// the part's draw identity, and the cached projection.
+/// One ground-quad decal: the joint it rides, the authored quad, its draw identity and its cache.
 #[derive(Component)]
 pub(crate) struct GroundFxDecal {
-    /// The joint entity whose pose animates the quad (the effect model's own rig; the instance
-    /// root for a boneless model). Its despawn — the instance's reap — despawns the decal.
+    /// The joint whose pose animates the quad; its despawn despawns the decal.
     joint: Entity,
-    /// The bone's inverse bindpose (identity for a boneless model): a corner's world position is
-    /// `joint_global × ibp × corner`, exactly what the skinned mesh would compute.
+    /// The bone's inverse bindpose: a corner lands at `joint_global × ibp × corner`, as a skinned
+    /// vertex does, so the authored slide, spin and scale survive.
     ibp: Mat4,
-    /// The quad corners in Bevy model space (y = 0), normalized at spawn so the fitted frame's
-    /// `+z'` axis matches the UV `t` axis (see [`spawn_ground_fx_decal`]).
+    /// Bevy model-space corners (y = 0), ordered at spawn so the frame's `+z'` is the UV `t` axis.
     corners: [Vec3; 4],
-    /// The authored UV at each corner, parallel to `corners`.
     uvs: [[f32; 2]; 4],
-    /// The part's texture (the shared material's, resolved at spawn).
     texture: Handle<Image>,
-    /// The part's authored blend, mapped onto the lane (`model_render.rs`'s law).
     blend: EffectBlend,
     /// The part's `0x70baf0` fog policy (from the shared material's baked marker bits).
     fog: EffectFog,
-    /// The part's M2Color RGB loop on this instance's clock (loop, attach-time origin) —
-    /// sampled into the vertex tint at push time (was: a per-instance material clone mutated
-    /// per frame through `FxTintAnims`).
+    /// The part's M2Color RGB loop and its attach-time origin, sampled into the tint at push time.
     rgb_anim: Option<(std::sync::Arc<benilla_formats::RgbAnim>, f32)>,
-    /// The part's **static** M2Color tint ([`GroundQuad::tint`]) — the constant colour the mesh
-    /// path draws through its vertex-colour bake, which this lane has no vertex buffer to carry.
-    /// White for a batch that authors none, and white whenever [`Self::rgb_anim`] is `Some` (the
-    /// bake clears one when it emits the other), so the two multiply without ever double-applying.
+    /// The static M2Color tint ([`GroundQuad::tint`]) the mesh path bakes into vertex colours;
+    /// white whenever [`Self::rgb_anim`] is `Some`, so the two never double-apply.
     tint: [f32; 3],
     /// The cached projection (world-space effect triangles, white × the vertical-fade alpha).
     cache: Vec<EffectVertex>,
-    /// The posed corners the cache was projected from (NaN-seeded: the first pass always
-    /// projects) + the receiving-surface count that re-arms a static pose when a tile streams.
+    /// The posed corners (NaN-seeded, so the first pass projects) and the receiving-surface count
+    /// the cache was built from; a streamed tile changes the count and re-projects a static pose.
     cached_corners: [Vec3; 4],
     cached_surfaces: usize,
-    /// The cached frame's center — the draw's sort anchor.
     center: Vec3,
 }
 
-/// Spawn one ground-quad decal entity (a world-root record — no render components; the
-/// projection rides the effect stream). The caller resolves the part's texture/blend/fog/tint
-/// identity from its shared material; the caller also inserts the part's `MatAnim` rider (its
-/// `current` is the push-time alpha).
+/// Spawns one ground-quad decal; the caller inserts the part's `MatAnim`, its push-time alpha.
 pub fn spawn_ground_fx_decal(
     commands: &mut Commands,
     texture: Handle<Image>,
-    // The authored batch's blend and its material's packed fog byte, *not* the lane enums they
-    // map to: a caller that translates those has to know the mapping, and the mapping is this
-    // lane's (`EffectBlend::from_model`, `EffectFog::from_model_policy`).
+    // The authored blend and packed fog bits, not the lane enums: the mapping is this lane's.
     blend: benilla_formats::ModelBlend,
     additive: bool,
     fog_policy_bits: u32,
@@ -100,10 +62,8 @@ pub fn spawn_ground_fx_decal(
     let fog = EffectFog::from_model_policy(fog_policy_bits);
     let mut corners = quad.corners.map(wow_to_bevy);
     let mut uvs = quad.uvs;
-    // Normalize corner handedness once, at rest: the WoW→Bevy rotation may map the authored
-    // (+x, +y) rect axes to a pair whose second axis lands on the fitted frame's −z'. Runtime
-    // joint transforms are proper rotations × positive scales, so this relative handedness is
-    // invariant — one row swap here keeps the bilerp `t` axis aligned with `+z'` forever.
+    // Fix handedness at rest: the WoW→Bevy rotation can put the second rect axis on `−z'`, and a
+    // joint pose (rotation × positive scale) keeps handedness, so one swap holds for good.
     let ex = corners[1] - corners[0] + corners[3] - corners[2];
     let ez = corners[2] - corners[0] + corners[3] - corners[1];
     if ez.z * ex.x - ez.x * ex.z < 0.0 {
@@ -131,10 +91,8 @@ pub fn spawn_ground_fx_decal(
         .id()
 }
 
-/// Fit a projection frame to the posed quad: center at the corner mean, the frame's `x'` axis
-/// along the (horizontally projected) `c0→c1` edge, half-extents from the averaged edge lengths,
-/// the ring's vertical slab (±2 × the larger half-extent, so a ledge catches a fading smear).
-/// `None` for a degenerate pose — the scale-0 first animation frame, or an edge-on tilt.
+/// Fits a frame to the posed quad: centered on the corner mean, `x'` along the horizontal `c0→c1`
+/// edge, a slab of ±2 × the larger half-extent; `None` for a scale-0 or edge-on pose.
 fn fit_frame(corners: &[Vec3; 4]) -> Option<DecalFrame> {
     let center = (corners[0] + corners[1] + corners[2] + corners[3]) * 0.25;
     let ex = (corners[1] - corners[0] + corners[3] - corners[2]) * 0.5;
@@ -148,8 +106,7 @@ fn fit_frame(corners: &[Vec3; 4]) -> Option<DecalFrame> {
     let vert = 2.0 * half_x.max(half_z);
     Some(DecalFrame {
         center,
-        // `in_frame` computes `x' = dx·cos − dz·sin`: cos = d.x, sin = −d.y sends the posed
-        // `c0→c1` edge direction onto the frame's +x' axis.
+        // `in_frame` takes `x' = dx·cos − dz·sin`, so these put the posed `c0→c1` edge on `+x'`.
         sin: -d.y,
         cos: d.x,
         min_x: -half_x,
@@ -161,19 +118,14 @@ fn fit_frame(corners: &[Vec3; 4]) -> Option<DecalFrame> {
     })
 }
 
-/// Bilinear UV over the quad's authored corner UVs at normalized frame coordinates `(s, t)`.
 fn bilerp_uv(uvs: &[[f32; 2]; 4], s: f32, t: f32) -> [f32; 2] {
     let lerp2 =
         |a: [f32; 2], b: [f32; 2], k: f32| [a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k];
     lerp2(lerp2(uvs[0], uvs[1], s), lerp2(uvs[2], uvs[3], s), t)
 }
 
-/// Per-frame placement + push (in [`crate::billboard::BillboardPlace`] — post-propagation, so
-/// the joint pose is THIS frame's; after `begin_effect_frame` — the push lands in this frame's
-/// stream): pose each decal's corners through its joint; re-project only when they (or the
-/// receiving surfaces) moved; push the cached triangles tinted with this frame's RGB/alpha loop
-/// samples. Orphaned decals (joint despawned with its effect instance) despawn; a frame with no
-/// receiving ground pushes nothing (the ring's no-ground gate).
+/// Re-projects a decal when its posed corners or the receiving surfaces change and pushes the
+/// cached triangles with this frame's tint; a decal whose joint is gone despawns.
 pub(crate) fn update_ground_fx_decals(
     mut commands: Commands,
     time: Res<Time>,
@@ -200,9 +152,7 @@ pub(crate) fn update_ground_fx_decals(
         }
         let pose = joint.affine() * Affine3A::from_mat4(decal.ibp);
         let corners = decal.corners.map(|c| pose.transform_point3(c));
-        // The rebuild gate (0733 §5): the posed corners capture the whole pose effect, so a
-        // static aura under a static rig costs this compare. (NaN-seeded corners make the
-        // first pass always project.)
+        // The posed corners capture the whole pose, so a static aura costs only this compare.
         if corners != decal.cached_corners || surface_count != decal.cached_surfaces {
             let decal = &mut *decal;
             decal.cached_corners = corners;
@@ -215,8 +165,8 @@ pub(crate) fn update_ground_fx_decals(
                     &mut decal.cache,
                     &surfaces,
                     &frame,
-                    // The ring's vertical trapezoid: full within half the slab, fading to 0 at
-                    // its edge — a wall/ledge smear dims with height instead of a hard clip.
+                    // Full alpha for `|y|` up to a quarter of the slab's half-height, fading to 0
+                    // at its edge, so a ledge smear dims with height instead of clipping.
                     |p| ((vert - p.y.abs()) / (0.75 * vert)).clamp(0.0, 1.0),
                     |x, z| {
                         let s = (x - frame.min_x) / (frame.max_x - frame.min_x);
@@ -229,11 +179,7 @@ pub(crate) fn update_ground_fx_decals(
         if decal.cache.is_empty() {
             continue;
         }
-        // This frame's tint: the part's M2Color colour — its STATIC constant (the vertex-colour
-        // bake this lane has no vertex buffer to carry) × its RGB loop where it varies (instance
-        // clock) — and the MatAnim alpha loop. Exactly what the vertex colours + material clone +
-        // MeshTag carried on the mesh path. Only one of the two colour terms is ever non-white
-        // (the bake emits one or the other), so the product is the authored colour, not a square.
+        // The static tint times the RGB loop (only one is ever non-white), and the `MatAnim` alpha.
         let loop_tint = decal
             .rgb_anim
             .as_ref()
@@ -253,15 +199,11 @@ pub(crate) fn update_ground_fx_decals(
                 texture: decal.texture.id(),
                 blend: decal.blend,
                 fog: decal.fog,
-                // Spell ground-fx art is authored to burn at its own colour (the lane law in
-                // `EffectBlend::from_model`); no lit ground quad observed in the corpus.
+                // Unlit: spell ground-fx art burns at its own colour; the corpus has no lit one.
                 lighting: super::particles::buffer::EffectLighting::None,
                 anchor: decal.center,
                 bias: crate::sky_order::Rung::GROUND_FX,
-                // The projector's shared coplanarity margin — NOT `GROUND_FX as i32`, which is a
-                // *sort* rung borrowed for a rasterizer field because the two numbers happened to
-                // coincide. That is the conflation 1806 is about, and it left this lane at +8192,
-                // which the projector's own bake residual exceeds by 1.30× (1817).
+                // The projector's coplanarity margin, not the `GROUND_FX` sort rung.
                 raster_bias: crate::sky_order::Rung::DECAL_RASTER,
                 raster_slope: 0.0,
                 cam_relative: false,
@@ -274,12 +216,8 @@ pub(crate) fn update_ground_fx_decals(
     }
 }
 
-/// Wire the ground-fx decal lane in.
-///
-/// The placement pass rides `BillboardPlace` — post-propagation, so the effect rig's joints carry
-/// THIS frame's pose — and after the stream clear, since it pushes its cached projection into this
-/// frame's stream. Registered here rather than by the game: the ordering is a property of the
-/// lane, and a caller that has to know it is a caller that can get it wrong.
+/// Runs the placement pass in `BillboardPlace`, after transform propagation so joints carry this
+/// frame's pose, and after `begin_effect_frame` clears the stream it pushes into.
 pub fn plugin(app: &mut App) {
     app.add_systems(
         bevy::app::PostUpdate,
@@ -293,8 +231,6 @@ pub fn plugin(app: &mut App) {
 mod tests {
     use super::*;
 
-    /// A yawed, scaled rect must fit a frame that reproduces its extents and maps corners to the
-    /// bilerp's (s, t) corners.
     #[test]
     fn fitted_frame_matches_posed_rect() {
         // A 2×1 rect (half-extents 1.0 / 0.5) yawed 30° about Y, raised to y = 3.
@@ -326,14 +262,12 @@ mod tests {
         assert!((frame.max_y - 2.0).abs() < 1e-5 && (frame.min_y + 2.0).abs() < 1e-5);
     }
 
-    /// A zero-scale pose (the first frame of an outward-scaling ring) fits no frame.
     #[test]
     fn degenerate_pose_fits_nothing() {
         let p = Vec3::new(1.0, 2.0, 3.0);
         assert!(fit_frame(&[p, p, p, p]).is_none());
     }
 
-    /// Corner UVs bilerp exactly at the corners and average at the middle.
     #[test]
     fn bilerp_hits_corners() {
         let uvs = [[0.0, 0.0], [0.25, 0.0], [0.0, 1.0], [0.25, 1.0]];
diff --git a/crates/benilla-world/src/instance_tint.rs b/crates/benilla-world/src/instance_tint.rs
index f753919d..32356a54 100644
--- a/crates/benilla-world/src/instance_tint.rs
+++ b/crates/benilla-world/src/instance_tint.rs
@@ -1,53 +1,20 @@
-//! The per-instance body **TINT** — a unit's whole model multiplied by one colour (decision 0812):
-//! the render channel for the aura state kit's CharProc 1 ([`crate::aura_visual`]), which had the
-//! nodes modelled and nowhere to put them.
+//! The per-instance body tint: a unit's whole model multiplied by one colour, the render channel
+//! for the aura kits' CharProc 1 (`benilla-app`'s `aura_visual`).
 //!
-//! **What it is in the reference.** A CM2 model instance carries two per-instance colour slots
-//! beside its fade alpha (`model+0x180`): a **modulate** tint at `model+0x184/188/18c` (setter
-//! `0x710cf0`, default `1,1,1`) and an **additive** highlight emissive at `+0x190/194/198`
-//! (`0x710d40`, default `0,0,0`). benilla already carries the additive one — that is
-//! [`crate::mesh_tag::HIGHLIGHT_BIT`], the hover/target brighten — because its colour is a single
-//! config constant and fits in a flag bit. This module is its modulate sibling, which needs a real
-//! per-instance RGB.
+//! The reference's CM2 instance carries a modulate tint at `model+0x184..0x18c` (setter
+//! `0x710cf0`, default white) beside the additive highlight (`0x710d40`), which is
+//! [`crate::mesh_tag::HIGHLIGHT_BIT`] here. The animate kernel `0x714260` multiplies it by
+//! `inputColorA`, and the batcher clamps it to [0,1] and sets it as the GL ambient and diffuse
+//! material colour (`0x70c3a9`–`0x70c4d3`, `0x70c8ad`): it scales the light sum inside the clamp,
+//! not emission, where `wow_model.wgsl` applies a WMO batch's MOCV. An unlit batch adds the tinted
+//! M2Color and the highlight inside one clamp.
 //!
-//! **Where it lands in the draw (VERIFIED, wow-re `models/models.md`).** The animate kernel
-//! `0x714260` derives `[ebx+0x1a0..0x1a8] = tint × inputColorA` per frame (per-channel `fmul` at
-//! `0x7142cc`/`0x7142de`/`0x7142ed`); the batcher `0x70c3a9`–`0x70c4d3` clamps it to [0,1],
-//! byte-packs `0xAARRGGBB` and issues gx **SetState(1, modulatedColor)** at `0x70c8ad`, which drives
-//! the device-init `GL_COLOR_MATERIAL` / `GL_AMBIENT_AND_DIFFUSE` current-colour path. So the tint
-//! is the **material ambient+diffuse colour**: it multiplies the light sum *inside* the [0,1] clamp
-//! and NOT the emission terms — structurally identical to what a WMO batch's MOCV already does in
-//! `wow_model.wgsl`, which is where the shader multiplies it. With lighting off (an UNLIT batch) the
-//! same state is a plain `glColor` modulate on the texture, so the fullbright path takes it too —
-//! unlike the highlight, whose GL_EMISSION is dead there.
-//!
-//! (wow-re's `ghost-death-visuals.md` §4 still flags this combine as its one INFERRED hop and asks
-//! for a models-node follow-up; `models.md` is that follow-up, and it is VERIFIED — two independent
-//! traces plus gx's applicator-arm enumeration. We build on the verified note.)
-//!
-//! **The channel: no new `MeshTag` bits.** `MeshTag` bits 19..=29 already carry the instance's rig
-//! slot ([`crate::rig_palette`]) — allocated per unit, written into every skinned part's tag at
-//! spawn, and preserved by every runtime tag writer by construction. The vertex stage reads it to
-//! index the palette region; the fragment stage now reads the *same* slot to index this table. That
-//! is what makes the tint free of the bit budget the alpha and probe payloads fight over (5 spare
-//! bits outdoors, **zero** indoors): it needs none.
-//!
-//! The rig field is safe to read on an unskinned instance because `WOW_RIG_SKIN` is keyed on the
-//! mesh's vertex layout (`WowModelExt::specialize` tests `ATTRIBUTE_WOW_JOINT_INDEX`), never on the
-//! tag — so a static mesh carrying a nonzero slot is not skinned by it, and the field is a plain
-//! per-instance index. Slot **0** is the world's no-rig sentinel (terrain, WMO, doodads, clutter,
-//! every unskinned part), so it is never written and always reads identity.
-//!
-//! **`0` means identity, and that is the client's own packing.** `0x60d840` builds the node value as
-//! `round(param) | 0xff000000` (`0x60d8cc`) — an authored colour always carries a full alpha byte,
-//! so a `0` word cannot be a real tint. A zeroed region is therefore a no-op by construction: the
-//! portrait booths' studio buffers, slot 0, and every frame before anything is tinted all cost
-//! nothing and change no pixel. The one shipped kit that authors a **black** body tint (spell 27200
-//! Defile, kit 6531, `param0 = 0`) survives it, because we store `0xFF000000` for it, not `0`.
-//!
-//! **Not eased.** The reference applies the tint head node on *change* (`unit+0xd04`
-//! change-detection → `×1/255` → `0x710cf0`), with none of the 1000 ms cubic ramp its sibling alpha
-//! gets (`0x614f80`). A tint appears and disappears instantly, and that is faithful.
+//! The table is indexed by the `MeshTag` rig slot ([`crate::rig_palette`]), so it takes no tag
+//! bits; an unskinned mesh reads its slot safely, as skinning keys on the vertex layout, not the
+//! tag. Slot 0, the no-rig sentinel, is never written. A `0` word is identity: the reference packs
+//! an authored colour as `round(param) | 0xff000000` (`0x60d840`), so black (spell 27200, Defile)
+//! is `0xff000000`. The tint applies on change with no easing (`unit+0xd04` into `0x710cf0`),
+//! unlike the alpha's 1000 ms ramp (`0x614f80`).
 
 use std::sync::Arc;
 
@@ -61,12 +28,11 @@ use crate::mesh_tag::MAX_RIG_SLOTS;
 /// Bytes per slot in the tint region: one packed `0xFFRRGGBB` word.
 const SLOT_BYTES: u64 = 4;
 
-/// The "no tint" word — see the module doc. Zero is identity, so a zeroed buffer is inert.
+/// The no-tint word: zero, so a zeroed buffer is inert.
 pub const IDENTITY: u32 = 0;
 
-/// Byte offset of the instance-tint region inside a `wow_light`-layout buffer: between the rig slot
-/// table and the palette rows, mirroring `wow_model.wgsl`'s struct order (the palette array is
-/// runtime-sized, so it has to stay last).
+/// Byte offset of the tint region in a `wow_light`-layout buffer, after the rig slot table and
+/// before the runtime-sized palette rows; it must match `wow_model.wgsl`'s struct order.
 pub(crate) fn region_offset() -> u64 {
     crate::rig_palette::rig_table_region_offset() + MAX_RIG_SLOTS as u64 * SLOT_BYTES
 }
@@ -76,39 +42,25 @@ pub(crate) fn region_bytes() -> u64 {
     MAX_RIG_SLOTS as u64 * SLOT_BYTES
 }
 
-/// Pack an RGB triple the way the reference does (`0x60d840`: `param | 0xff000000`) — so the word is
-/// never [`IDENTITY`], even for an authored black.
+/// Packs RGB as the reference does (`0x60d840`: `param | 0xff000000`), so even black is never
+/// [`IDENTITY`].
 pub fn pack(rgb: [u8; 3]) -> u32 {
     0xff00_0000 | (u32::from(rgb[0]) << 16) | (u32::from(rgb[1]) << 8) | u32::from(rgb[2])
 }
 
-/// Off-world `wow_light`-layout buffers that also carry the tint region — registered by key, the
-/// same shape as [`crate::rig_palette::RigPaletteMirrors`] and deliberately NOT the same list.
-///
-/// **Why this is opt-in, and why the portrait booths are not on it.** The reference's per-instance
-/// tint lives on ONE CM2 instance (`[inst+0x184..0x18c]`, setter `0x710cf0`). A unit-frame portrait
-/// does not render that instance: the bake `0x524f60` builds a **fresh** CM2 from it whose ctor sets
-/// colour `(1,1,1)` and alpha `1.0` (`0x70ea60`-`0x70ea89`/`0x70eaca`), and `0x525261 call 0x47a230`
-/// then sets those very two fields *again* — so a ghost's portrait shows the pre-death, untinted,
-/// fully-opaque face, and "a client that tints the portrait when the ghost flags are set diverges
-/// from 1.12.1" (wow-re `ghost-death-visuals.md` §6, VERIFIED; benilla report B49, decision 1481).
-/// Our round portraits mirror the world entity's own children, so they carry the WORLD unit's rig
-/// slot — pushing this region into their buffer would tint them with it. Their buffer keeps the
-/// zero-initialised (identity) region instead, which is the reference's fresh-instance behaviour
-/// reproduced by construction.
-///
-/// The **glue scene** is the opposite case and is why the list exists: it is not a bake standing in
-/// for a UI model widget, it is the screen itself, and its character component is exactly the
-/// instance the reference writes (`0x472939 -> 0x710cf0`, the char-select ghost proc). It carries its
-/// OWN rig slot, allocated by the booth spawn, so nothing a world unit does can reach it.
+/// Off-world `wow_light`-layout buffers that also carry the tint region, by key; deliberately not
+/// [`crate::rig_palette::RigPaletteMirrors`]' list. Portraits stay off it: the reference bakes one
+/// from a fresh CM2 with colour (1,1,1) and alpha 1 (`0x524f60`, ctor `0x70ea60`, set again at
+/// `0x525261` via `0x47a230`), so a ghost's portrait is untinted, and ours carry the world unit's
+/// rig slot. The glue scene is on it: its character is the instance the reference tints
+/// (`0x472939` into `0x710cf0`, the char-select ghost) and has a slot of its own.
 #[derive(Resource, Clone, Default, ExtractResource)]
 pub struct InstanceTintMirrors(
     pub std::collections::HashMap<&'static str, bevy::render::render_resource::Buffer>,
 );
 
-/// The live per-slot tint table, indexed by the instance's `MeshTag` rig slot. `Arc`-shared so the
-/// render-world extract is a pointer bump, and generation-stamped so a world with nothing tinted
-/// uploads nothing at all.
+/// The per-slot tint table, indexed by the `MeshTag` rig slot; `Arc`-shared for a cheap extract
+/// and generation-stamped so an untinted world uploads nothing.
 #[derive(Resource, Clone, ExtractResource)]
 pub struct InstanceTints {
     slots: Arc<Vec<u32>>,
@@ -125,9 +77,8 @@ impl Default for InstanceTints {
 }
 
 impl InstanceTints {
-    /// Set slot `slot`'s tint word (already packed — [`pack`], or [`IDENTITY`] to clear). Slot 0 is
-    /// the world's no-rig sentinel and is never written: everything unskinned shares it, so a write
-    /// there would tint terrain, doodads and WMO surfaces at once.
+    /// Sets a slot's packed word ([`pack`], or [`IDENTITY`] to clear). Slot 0, shared by everything
+    /// unskinned, is never written.
     pub fn set(&mut self, slot: u16, word: u32) {
         let i = slot as usize;
         if i == 0 || i >= MAX_RIG_SLOTS || self.slots[i] == word {
@@ -137,27 +88,20 @@ impl InstanceTints {
         self.generation += 1;
     }
 
-    /// Clear a slot back to identity — called on the aura's reap edge AND from `RigSkin`'s free
-    /// hook, so a slot can never carry a dead unit's tint into the next unit that allocates it.
+    /// Clears a slot; `RigSkin`'s free hook calls it too, so a reused slot never inherits a dead
+    /// unit's tint.
     pub(crate) fn clear(&mut self, slot: u16) {
         self.set(slot, IDENTITY);
     }
 
-    /// This slot's current word (`IDENTITY` when untinted, or for an out-of-range slot).
-    ///
-    /// Test support: the render path reads the uploaded region, never this. Not `#[cfg(test)]`
-    /// because the aura tests that assert on it live in `benilla-app`, and a dependent crate does
-    /// not compile this one's test cfg.
+    /// This slot's word, for tests (the render path reads the uploaded region); not
+    /// `#[cfg(test)]` because `benilla-app`'s aura tests use it.
     pub fn get(&self, slot: u16) -> u32 {
         self.slots.get(slot as usize).copied().unwrap_or(IDENTITY)
     }
 }
 
-/// Render world (`PrepareResources`): write the whole 8 KB region when anything changed. Gated on
-/// the generation, so a world with no tinted unit — the overwhelmingly common case — never touches
-/// the queue. Whole-region writes rather than per-slot ranges: the table is smaller than one
-/// palette rig's rows, and aura edges are rare (a hundredth the traffic of the pose upload beside
-/// it, which is the one that needed range coalescing).
+/// Render world (`PrepareResources`): writes the whole 8 KB region when the generation changed.
 fn upload_instance_tints(
     queue: Res<RenderQueue>,
     shared: Option<Res<crate::lighting::SharedLightBuffer>>,
@@ -166,9 +110,7 @@ fn upload_instance_tints(
     mut last: Local<Option<u64>>,
 ) {
     let Some(tints) = tints else { return };
-    // The generation gate covers the mirror list too: a mirror registered after the last write
-    // would otherwise never be filled. Mirrors are registered once per booth/scene buffer, so
-    // folding their count into the gate costs one comparison and closes that hole.
+    // The mirror count is in the gate, so a mirror registered after the last write still fills.
     let mirrors = mirrors
         .map(|m| m.0.values().cloned().collect::<Vec<_>>())
         .unwrap_or_default();
@@ -200,19 +142,15 @@ pub fn plugin(app: &mut App) {
 mod tests {
     use super::*;
 
-    /// The reference's own packing: the full alpha byte rides every authored colour, which is what
-    /// keeps `0` free as the identity sentinel — including for the one kit that authors black.
     #[test]
     fn packing_matches_the_reference_and_never_collides_with_identity() {
-        // The ghost aura's node value, byte-for-byte (wow-re: `round(9222653) | 0xff000000`).
+        // The ghost aura's node value (`round(9222653) | 0xff000000`).
         assert_eq!(pack([0x8c, 0xb9, 0xfd]), 0xff8c_b9fd);
-        // Spell 27200 Defile authors param0 = 0 — a real black body tint, not an absent one.
+        // Spell 27200 (Defile) authors param0 = 0: a real black tint.
         assert_eq!(pack([0, 0, 0]), 0xff00_0000);
         assert_ne!(pack([0, 0, 0]), IDENTITY);
     }
 
-    /// Slot 0 is shared by every unskinned instance in the world (terrain, WMO, doodads, clutter):
-    /// writing a tint there would colour the whole scene, so the setter refuses it.
     #[test]
     fn slot_zero_is_never_written() {
         let mut t = InstanceTints::default();
@@ -221,8 +159,6 @@ mod tests {
         assert_eq!(t.generation, 0, "and it costs no upload");
     }
 
-    /// A world with nothing tinted never bumps the generation, so it never uploads; a real change
-    /// bumps once, and a redundant re-write of the same colour does not.
     #[test]
     fn the_generation_tracks_real_changes_only() {
         let mut t = InstanceTints::default();
@@ -238,8 +174,6 @@ mod tests {
         assert_eq!(t.generation, 2, "already clear");
     }
 
-    /// An out-of-range slot is dropped rather than panicking — the 11-bit tag field cannot express
-    /// one, but the setter takes a `u16` and must not trust it.
     #[test]
     fn an_out_of_range_slot_is_dropped() {
         let mut t = InstanceTints::default();
diff --git a/crates/benilla-world/src/interact/mod.rs b/crates/benilla-world/src/interact/mod.rs
index 9673d9b7..dd1b48fa 100644
--- a/crates/benilla-world/src/interact/mod.rs
+++ b/crates/benilla-world/src/interact/mod.rs
@@ -1,38 +1,10 @@
-//! World interaction foundation — *what is the player pointing at?*
+//! What the player is pointing at: the identity of every pickable world thing ([`WorldObject`]),
+//! the world click gestures, and the ray caster ([`pick`]), which casts against resident geometry
+//! so colliderless props that a physics ray misses still pick.
 //!
-//! This is the shared base for every "point at the world" feature: the debug **object inspector**,
-//! hover tooltips, the contextual cursor (gear over objects, sword over attackable units),
-//! mouseover-targeting, and right-click-to-interact. Built once so we don't build picking +
-//! identity twice.
-//!
-//! The pieces:
-//! - [`WorldObject`] — an **identity** component on every pickable world entity (a doodad/WMO model, a
-//!   creature, a GameObject): its kind, a human label (model path or unit name), an id, and an optional
-//!   detail line. Attached at the spawn sites.
-//! - the **ray caster** ([`pick`]) — the pick-geometry declarations ([`PickMesh`] / [`PickBox`]) and
-//!   the shared triangle-accurate cast against the **actual resident mesh geometry** (so it works on
-//!   colliderless props — most doodads, including the campfire — which a physics raycast misses),
-//!   plus the generous inflated pass the mouse pick retries with (decision 1071).
-//! - [`MouseoverTarget`] — the resource [`update_mouseover`] fills each frame with the nearest
-//!   `WorldObject` under the cursor, for the inspector.
-//!
-//! The **instruments** built on this base — the dev-chord `I` inspector surface, the cast journal,
-//! and the mouseover pick that only ever ran while the inspector was armed — live in
-//! `debug_panel::{inspect, journal}` (decision 1160's stage zero). They were here first, and they
-//! were what made this module read as the most entangled thing on the engine/game line: between
-//! them they named the whole `target::cursor_mode` GO-reaction vocabulary, the spell catalog, the
-//! GameObject templates, the name cache and the net writer. What remains here — identity, the
-//! ray-caster and the three click gestures — reaches for none of it.
-//!
-//! The player-facing consumers (`crate::target`) run their picks through [`pick`] unconditionally.
-//!
-//! **Not every drawn thing has an entity** (decision 1534). The consolidating render lanes — the
-//! static merge's blobs and the retained static pass — draw many placements as one thing, and the
-//! per-placement entity that used to carry the declaration is gone. So the declaration has two more
-//! shapes: [`PickBlob`] (members on the blob entity, for a lane that still draws from one) and
-//! [`PickSource`] (the lane answers the ray itself, for one that draws from retained buffers).
-//! [`WorldPick`] is the bundle that hands a consumer all three at once — reach for it, not for
-//! [`PickParts`] alone, or the answer goes quiet over most of the static world.
+//! The consolidated render lanes draw many placements with no entity per placement, so a pick
+//! declaration takes three shapes: [`PickMesh`] or [`PickBox`] on an entity, [`PickBlob`] members
+//! on a blob entity, and a [`PickSource`] lane that answers the ray itself.
 
 use bevy::platform::collections::HashSet;
 use bevy::prelude::*;
@@ -48,86 +20,56 @@ pub use pick::{
 
 pub use pick::{ray_member, ray_mesh_bounds, ray_posed_mesh, RayHit};
 
-/// The identity of a pickable world thing, read by the inspector now and by tooltips/cursor/targeting
-/// later. Attached to a thing's renderable mesh entities at spawn.
+/// The identity of a pickable world thing, attached to its renderable mesh entities at spawn.
 #[derive(Component, Clone, Debug)]
 pub struct WorldObject {
     pub kind: ModelKind,
-    /// Primary label — a model path (doodads/WMOs/GameObjects) or a unit name. Shown to the player/dev.
+    /// A model path (doodads, WMOs, GameObjects) or a unit name.
     pub label: String,
-    /// Identifier — placement uniqueId, server guid, or display id (`0` if none).
+    /// Placement `uniqueId`, server guid or display id; `0` if none.
     pub id: u32,
-    /// Optional second line of kind-specific detail (e.g. `"emitters: 2"`); shown when non-empty.
+    /// An optional kind-specific second line, shown when non-empty.
     pub detail: String,
 }
 
-/// Marker on every pickable **GameObject** part — the GO mouseover pick's population
-/// (`target/hover.rs`). Inserted beside the part's `WorldObject { kind: GameObject }` at the
-/// attach spawn sites, so building the pick set is an archetype-filtered query over the handful
-/// of GO parts on screen instead of a kind-compare over every streamed `WorldObject` row (the
-/// doodad/WMO population dwarfs it).
+/// Marks every pickable GameObject part, so the GameObject hover's pick set is an archetype query
+/// rather than a scan of every `WorldObject`.
 #[derive(Component, Clone, Copy)]
 pub struct GoPickPart;
 
-/// The creature twin of [`GoPickPart`]: every pickable unit/player part — the model-less fallback
-/// cube included — the unit pick's skinless-fallback population. Doodad/WMO parts carry neither
-/// marker.
+/// Marks every pickable unit or player part, the model-less fallback cube included: the unit
+/// pick's skinless-fallback set. Doodad and WMO parts carry neither marker.
 #[derive(Component, Clone, Copy)]
 pub struct CreaturePickPart;
 
-/// A left *select* gesture in the world. Emitted by [`crate::player::control`] on the button's
-/// **release**, when the press satisfied the reference's click predicate — under 200 ms whatever the
-/// mouse did, or under 800 ms having turned the camera less than 2.25° of yaw / 2.0° of pitch
-/// ([`crate::player::camera::PressGesture`], decision 1122).
-///
-/// **A drag emits this too.** Orbit and select are independent in the reference: the press engages
-/// the camera look immediately and arms this test alongside it, so a fast flick-and-click orbits the
-/// camera *and* selects. This doc comment used to assert the opposite as design — *"a left drag
-/// engages the orbit and emits nothing"* — and a reporter quoted it back at us with an A/B against
-/// the real client proving it wrong (ledger B226).
-///
-/// It carries no position because the *pick* is latched separately, at the press
-/// ([`crate::target::PressPick`]) — never the live hover, which is blank by the time a dragged
-/// click lands.
+/// A left select gesture, sent on release when the press met the reference's click predicate:
+/// under 200 ms, or under 800 ms having turned the camera less than 2.25° of yaw and 2.0° of
+/// pitch. A drag that meets it selects too, as the reference arms the click beside the camera look.
+/// It carries no position: the pick is latched at the press (`target::PressPick`).
 #[derive(Message, Clone, Copy)]
 pub struct WorldClick;
 
-/// The right button's context gesture — same arbiter and same predicate as [`WorldClick`], for the
-/// button whose drag is the character turn. Vanilla's context action: attack a hostile under the
-/// cursor (later: interact/gossip on a friendly).
+/// The right button's context gesture, on the same predicate as [`WorldClick`].
 #[derive(Message, Clone, Copy)]
 pub struct WorldRightClick;
 
-/// The right button's **DOWN edge** in the world — emitted at the press, before the click-vs-drag
-/// test even starts, whenever the press belongs to the world (in the viewport off the UI, or any
-/// press while a look session already owns the hidden cursor). The reference's
-/// `CGWorldFrame::OnMouseDown 0x483c40` analogue: ground-targeting's right-click cancel hangs off
-/// this edge (`0x492c20`, wow-re `world-click-targeting.md` Q3), which fires whether the press
-/// becomes a click OR a turn-drag, and consumes nothing (the ref handler returns 0, so the
-/// BUTTON2 turn and the release's context click still run).
+/// The right button's press in the world (off the UI, or any press while a look holds the hidden
+/// cursor), sent before the click test starts, as the reference's `CGWorldFrame::OnMouseDown`
+/// (`0x483c40`), where ground targeting's right-click cancel hangs (`0x492c20`). It consumes
+/// nothing, so the turn and the release's context click still run.
 #[derive(Message, Clone, Copy)]
 pub struct WorldRightPress;
 
-/// **The world's pick sources, as one `SystemParam`** — the ECS pick geometry ([`PickParts`]) plus
-/// every lane that draws without entities ([`PickSource`]).
-///
-/// Bundled deliberately. A consumer that reaches for the entity half alone still compiles, still
-/// casts, and still returns hits — it just stops seeing most of the static world, silently. That is
-/// precisely how the inspector, the hover and `WOW_PICK` went quiet when the consolidating lanes
-/// shipped (decision 1534): nothing failed, the answers just went blank over trees and buildings.
-/// So the roster of lanes lives HERE, once, and a new consumer gets it by construction.
-///
-/// The caster itself stays lane-agnostic — it only knows the trait. This is the one place that
-/// knows which lanes exist.
+/// The world's pick sources as one `SystemParam`: the entity pick geometry ([`PickParts`]) and
+/// every lane that draws without entities ([`PickSource`]). Use this, not [`PickParts`] alone,
+/// which still returns hits but misses most of the static world.
 #[derive(bevy::ecs::system::SystemParam)]
 pub struct WorldPick<'w, 's> {
     parts: PickParts<'w, 's>,
-    /// The identity every hit resolves through — including the doodad/WMO parts the entity path
-    /// still spawns.
+    /// The identity every entity hit resolves through.
     objects: Query<'w, 's, &'static WorldObject>,
-    /// The retained static pass — `None` when `WOW_STATIC_GX=0` leaves every placement on the
-    /// entity path. (The static merge needs no entry: its blobs ARE entities, and answer through
-    /// [`PickBlob`].)
+    /// The retained static pass; `None` when `WOW_STATIC_GX=0` keeps every placement on the entity
+    /// path. The static merge's blobs are entities and answer through [`PickBlob`].
     gx: Option<Res<'w, crate::static_gx::StaticGx>>,
 }
 
@@ -141,7 +83,7 @@ impl WorldPick<'_, '_> {
             .collect()
     }
 
-    /// The identified cast against everything drawn — see [`cast_object_ray`].
+    /// The identified cast against everything drawn ([`cast_object_ray`]).
     pub fn cast(&self, ray: Ray3d, pickable: &HashSet<Entity>, all_hits: bool) -> Vec<ObjectHit> {
         cast_object_ray(
             ray,
@@ -153,7 +95,7 @@ impl WorldPick<'_, '_> {
         )
     }
 
-    /// The identified cast through a screen pixel — the mouseover's whole job.
+    /// The identified cast through a screen pixel.
     pub fn at_cursor(
         &self,
         cursor: Vec2,
@@ -173,10 +115,7 @@ impl WorldPick<'_, '_> {
     }
 }
 
-/// Registers the world-interaction **foundation**: the identity component's three click messages
-/// and the shared ray-caster's parameters. The inspector surface and the cast journal that used to
-/// be registered here are instruments, and moved to `debug_panel` in decision 1160's stage zero —
-/// along with the mouseover pick, which only ever ran while the inspector was armed.
+/// Registers the three world click messages.
 pub struct InteractPlugin;
 
 impl Plugin for InteractPlugin {
diff --git a/crates/benilla-world/src/interact/pick.rs b/crates/benilla-world/src/interact/pick.rs
index 554e389a..22f03bf1 100644
--- a/crates/benilla-world/src/interact/pick.rs
+++ b/crates/benilla-world/src/interact/pick.rs
@@ -1,8 +1,6 @@
-//! The shared **ray caster** — the pick-geometry declarations and the triangle-accurate cast every
-//! "what is under the cursor" consumer runs through: the inspector's mouseover, the target module's
-//! GameObject hover, the `WOW_PICK` probe. Casts against **resident geometry** ([`PickMesh`] —
-//! decision 0857), because the render meshes are `RENDER_WORLD`-only (0834) and a physics ray
-//! misses colliderless props. Pick geometry is **declared, never inferred** (decision 0929).
+//! The shared ray caster: the pick-geometry declarations and the triangle-accurate cast. It casts
+//! against resident geometry ([`PickMesh`]) because the render meshes are `RENDER_WORLD`-only, and
+//! pick geometry is declared, never inferred from a bound.
 
 use std::sync::Arc;
 
@@ -15,111 +13,58 @@ use bevy::prelude::*;
 
 use super::WorldObject;
 
-/// The resident **pick geometry** of one drawn batch: the model's decoded `RenderSubmesh`, `Arc`-shared
-/// with the model asset itself (decision 0857). The render forms are `RENDER_WORLD`-only since 0834 —
-/// their main-world vertex data is gone after extract, which is why Bevy's `MeshRayCast` silently
-/// stopped hitting every static model (the GO hover, the inspector, `WOW_PICK`). So the pickers read
-/// triangles from THIS instead, through the same WoW→Bevy bake the render form was built with
-/// (`submesh_to_static_mesh`: `wow_to_bevy` per vertex, billboard cards centred at their pivot).
-/// Attached beside `Mesh3d` at every spawn site that also attaches a pick key
-/// ([`super::WorldObject`] / `ModelPart`). A keyed entity carrying neither this nor [`PickBox`] is
-/// **not pickable** — pick geometry is declared, never inferred from a bound (decision 0929).
+/// The resident pick geometry of one drawn batch, shared with the model asset; the render mesh is
+/// `RENDER_WORLD`-only. A keyed entity with neither this nor [`PickBox`] is not pickable.
 #[derive(Component, Clone)]
 pub struct PickMesh(pub Arc<RenderSubmesh>);
 
-/// "My `Aabb` **is** my pick geometry" — the model-less cube fallback ([`crate::entities::attach`]),
-/// whose cuboid is exactly its bound, so a slab test is the exact answer and 12 triangles would only
-/// be a slower way to say it.
-///
-/// It exists as a **positive declaration** because the alternative — inferring it from the *absence*
-/// of a [`PickMesh`] — silently promoted every other keyed-but-mesh-less drawn entity into a solid
-/// invisible box. That is what broke the inspector inside a city WMO (decision 0929): a WMO group's
-/// MLIQ pool is a drawn `Mesh3d` with no resident geometry, it inherits the building's
-/// [`super::WorldObject`] from the placement's blanket tag, and its render mesh keeps the **whole**
-/// MLIQ vertex grid — dry cells included, sitting at height 0 while the drawn lava is 86–127 yd
-/// below. Ironforge's thirteen pools therefore hung ~100-yard invisible boxes over the entire city,
-/// and the box-entry hit won every pick: every hover, on anything, answered "Wmo · ironforge.wmo".
+/// Declares that the entity's `Aabb` is its pick geometry: the model-less fallback cube, whose
+/// cuboid is its bound. Declared, not inferred from a missing [`PickMesh`], because a WMO's MLIQ
+/// pool is a drawn, identified mesh with no resident geometry whose bound spans its whole grid.
 #[derive(Component, Clone, Copy)]
 pub struct PickBox;
 
-/// One placement's batch inside a **consolidated draw** — its identity, its resident geometry and
-/// the world pose that geometry draws at.
-///
-/// The consolidating render lanes (the static merge's blobs, 1417/1418; the retained static pass's
-/// cell/region bakes, 1429–1434) draw many placements as one thing. They win their draw calls by
-/// *removing* the per-placement entity — and the pick declaration ([`PickMesh`] + [`super::WorldObject`])
-/// used to ride that entity, so consolidating a placement silently un-named it: the inspector, the GO
-/// hover and `WOW_PICK` all went quiet over most of the static world, and 0929's "declared, never
-/// inferred" rule made the loss indistinguishable from correct transparency (decision 1534).
-///
-/// This is the declaration that survives the consolidation: identity + geometry + pose, per member,
-/// held by whoever owns the consolidated draw. The pick walks members exactly as it walks parts, so
-/// a blob or a retained cell answers with the *placement* under the cursor, never with the draw that
-/// happens to contain it.
+/// One placement's batch inside a consolidated draw: its identity, resident geometry and world
+/// pose, so the pick names the placement under the cursor rather than the draw.
 #[derive(Clone)]
 pub struct PickMember {
-    /// Shared per placement — one allocation per placement, not per batch.
+    /// One allocation per placement, shared by its batches.
     pub object: Arc<WorldObject>,
     pub geometry: Arc<RenderSubmesh>,
-    /// The member's own WORLD pose (the placement transform its geometry was baked with), not a
-    /// pose relative to the consolidated draw's entity.
+    /// The member's world pose (its placement transform), not relative to the draw's entity.
     pub transform: Transform,
 }
 
-/// The members of a **blob** — a consolidated draw that is still one entity (the static merge's
-/// lane, `terrain_stream::merge`). The entity keeps the broad phase and the drawn test it always
-/// had (its union `Aabb`, its own `ViewVisibility`); this component is the narrow phase, and the
-/// identity that comes back.
-///
-/// A blob carries no [`PickMesh`]: its baked mesh is the union of its members and would answer with
-/// the blob, not with what the cursor is on.
+/// The members of a blob, a consolidated draw that is still one entity (the static merge). The
+/// entity keeps the broad phase (its union `Aabb`, its `ViewVisibility`); the members are the
+/// narrow phase and the identity. A blob carries no [`PickMesh`], whose hit would name the blob.
 #[derive(Component, Clone)]
 pub struct PickBlob(pub Arc<[PickMember]>);
 
-/// One hit from the **identified** cast ([`cast_object_ray`]): what was hit, and where.
-///
-/// The identity is *resolved here*, not left as an entity for the caller to look up, because most
-/// of the static world has no entity to look anything up on — it draws from a consolidated lane
-/// (decision 1534). `entity` is `Some` only when one owns the geometry, which is exactly when the
-/// per-entity readouts (a unit's descriptor store, a GameObject's collision, a part's material)
-/// exist to be read.
+/// One hit from the identified cast, its identity resolved here since most of the static world has
+/// no entity; `entity` is `Some` only when an entity owns the geometry.
 pub struct ObjectHit {
-    /// What was hit. `None` only for an entity a caller made pickable WITHOUT a world identity —
-    /// an equipped item's part or its billboard card, which `WOW_PICK` admits on `ModelPart` so a
-    /// "my pauldron looks wrong" report has something to name (decision 0836). Consolidated
-    /// content is always identified: identity is what its lane carries it by.
+    /// `None` only for an entity picked without a world identity (an equipped item's part).
     pub object: Option<WorldObject>,
     pub entity: Option<Entity>,
     pub hit: RayHit,
 }
 
-/// Geometry that draws with **no entity to hang a [`PickMesh`] on** — today the retained static
-/// pass ([`crate::static_gx`]), whose cell and region bakes replaced their placements' entities
-/// outright.
-///
-/// A source answers the ray itself rather than publishing a side table, because **only the lane
-/// knows what it actually drew this frame**: its selection is a CPU scene walk at cell/group/set
-/// granularity, not a `ViewVisibility` bit an outside walker could read. Implementors must report
-/// only selected content — that is the entity path's own rule (`ViewVisibility`), kept.
+/// Geometry drawn with no entity to hang a [`PickMesh`] on ([`crate::static_gx`]). The lane answers
+/// the ray itself, since only it knows what it drew, and reports only content it selected.
 pub trait PickSource {
-    /// Append every hit along `ray`, nearest triangle per member. `all_hits` asks for the whole
-    /// ray (the `WOW_PICK` reading) rather than just this source's nearest.
+    /// Append the nearest hit per member along `ray`; `all_hits` asks for the whole ray.
     fn cast_objects(&self, ray: Ray3d, all_hits: bool, out: &mut Vec<(Arc<WorldObject>, RayHit)>);
 }
 
-/// One triangle-accurate hit from [`cast_pick_ray`]: the world-space point, the hit triangle's
-/// geometric normal (two-sided — the orientation is the authored winding's), and the distance along
-/// the ray.
+/// One triangle-accurate hit; the normal follows the authored winding, not the ray.
 pub struct RayHit {
     pub point: Vec3,
     pub normal: Vec3,
     pub distance: f32,
 }
 
-/// The one query every mesh picker casts against: a part's resident geometry, its world pose, the
-/// render world's own visibility verdict (the cast honours it, as `RayCastVisibility::VisibleInView`
-/// did), its bound for the broad phase, whether that bound is itself the pick shape ([`PickBox`]),
-/// and — for a consolidated blob — the members its baked mesh stands in for ([`PickBlob`]).
+/// The query every mesh picker casts against.
 pub type PickParts<'w, 's> = Query<
     'w,
     's,
@@ -133,12 +78,8 @@ pub type PickParts<'w, 's> = Query<
     ),
 >;
 
-/// Cast a ray from the logical `cursor` position into the world and return the nearest hit among
-/// `pickable`: `(entity, world point, distance)`. The `pickable` set restricts the cast (terrain,
-/// particle billboards, and other un-identified meshes stay transparent), so callers choose *what* is
-/// pickable while sharing *how* — the inspector's per-frame mouseover passes every
-/// [`super::WorldObject`], the target picker passes only unit meshes (so a doodad in front doesn't
-/// block a click on a mob).
+/// The nearest hit among `pickable` under the logical `cursor`: `(entity, world point, distance)`.
+/// Only `pickable` can be hit, so a caller that passes only unit meshes clicks through a doodad.
 pub fn pick_at_cursor(
     cursor: Vec2,
     camera: &Camera,
@@ -153,12 +94,8 @@ pub fn pick_at_cursor(
         .map(|(e, hit)| (e, hit.point, hit.distance))
 }
 
-/// The **identified** cast: the ECS pick set (parts, boxes and blob members) *plus* every
-/// entity-less [`PickSource`], nearest-first — what a "name what I am pointing at" instrument
-/// wants, where the plain entity cast answers "which entity".
-///
-/// The two populations are cast independently and merged by distance, because they are culled by
-/// different machinery: an entity by its `ViewVisibility`, a source by its lane's own scene walk.
+/// The identified cast: the entity pick set (parts, boxes, blob members) and every entity-less
+/// [`PickSource`], each culled by its own machinery, cast apart and merged nearest-first.
 pub fn cast_object_ray(
     ray: Ray3d,
     pickable: &HashSet<Entity>,
@@ -170,8 +107,7 @@ pub fn cast_object_ray(
     let mut out: Vec<ObjectHit> = cast_pick_ray_impl(ray, pickable, parts, all_hits, false)
         .into_iter()
         .map(|(entity, member, hit)| match member {
-            // A consolidated member's identity travels with the hit; the entity is the DRAW's
-            // (a blob), which is never what the cursor is on.
+            // A blob member: its identity travels with the hit, and the blob entity is dropped.
             Some(object) => ObjectHit {
                 object: Some((*object).clone()),
                 entity: None,
@@ -200,7 +136,7 @@ pub fn cast_object_ray(
     out
 }
 
-/// [`cast_object_ray`] through a screen pixel — the mouseover's whole job.
+/// [`cast_object_ray`] through a screen pixel.
 pub fn pick_object_at_cursor(
     cursor: Vec2,
     camera: &Camera,
@@ -216,23 +152,9 @@ pub fn pick_object_at_cursor(
         .next()
 }
 
-/// Cast `ray` against `pickable`'s **resident geometry** ([`PickMesh`] — decision 0857: the render
-/// meshes are `RENDER_WORLD`-only, so there is no main-world mesh data to cast against) and return
-/// the hits nearest-first: one per entity (its nearest triangle), the whole list with `all_hits`
-/// (the `WOW_PICK` probe's everything-along-the-ray reading) or just the front entity without.
-///
-/// Broad phase: a world-space slab test on each candidate's `Aabb` (entry distance), nearest entry
-/// first, so the narrow walk stops as soon as a confirmed hit is closer than every remaining box. A
-/// part with no bound (a `NoFrustumCulling` fx part) is narrow-tested unconditionally; a
-/// [`PickBox`] entity takes its box entry as the hit, its cuboid being exactly its bound.
-/// Triangles test **two-sided**, like the unit picker's narrow phase — a generous pick beats a
-/// strict one at silhouette edges.
-///
-/// **Pick geometry is required, never inferred** (decision 0929): an entity that is neither a
-/// [`PickMesh`] nor a [`PickBox`] is not pickable, however identified or bounded it is. The box hit
-/// used to be the fallback for *any* keyed entity with an `Aabb` and no mesh, which quietly turned
-/// a WMO's MLIQ pool — a drawn mesh with no resident geometry, wearing its building's identity —
-/// into a city-sized invisible occluder. See [`PickBox`].
+/// Cast `ray` against `pickable`'s resident geometry, nearest-first: one hit per entity (its
+/// nearest triangle), all of them with `all_hits`, else only the front one. Triangles test
+/// two-sided, and an entity with neither [`PickMesh`] nor [`PickBox`] is never hit.
 pub fn cast_pick_ray(
     ray: Ray3d,
     pickable: &HashSet<Entity>,
@@ -245,16 +167,12 @@ pub fn cast_pick_ray(
         .collect()
 }
 
-/// [`cast_pick_ray`]'s **generous second pass** (decision 1071 — wow-re object-layer mouse-pick,
-/// resolve `0x7089c0` pass 2, mouse-pick only): every vertex displaced by its **authored normal,
-/// added raw** — 1 model-unit (× the part's world scale) outward, the same halo the unit picker
-/// builds from skinned normals. A part without authored normals cannot build the halo and stays
-/// exact-only, like the unit path. A [`PickBox`] inflates its cuboid by the same 1 model-unit —
-/// the cube fallback stands in for a model, so the halo applies to it too. Returns **all** hits
-/// (the caller ranks them by the reference's pass-2 priority ladder, not pure distance). The
-/// reference clips its halo to the sequence bounds *sphere*; our broad bound is the tight mesh
-/// `Aabb` inflated by the same 1 model-unit — strictly more permissive, never less (the target
-/// module's standing direction of error).
+/// [`cast_pick_ray`]'s generous second pass, mouse pick only (the reference's resolve `0x7089c0`,
+/// pass 2): every vertex moves out along its authored normal, raw, a halo of 1 model-unit times
+/// the part's scale; a part without normals stays exact-only, and a [`PickBox`] grows by the same
+/// unit. Returns every hit, for the caller to rank by the reference's pass-2 priority, not
+/// distance. Deviation: the broad bound is the mesh `Aabb` grown by 1 unit, not the reference's
+/// sequence-bounds sphere, because it can only err permissive.
 pub fn cast_pick_ray_inflated(
     ray: Ray3d,
     pickable: &HashSet<Entity>,
@@ -266,9 +184,7 @@ pub fn cast_pick_ray_inflated(
         .collect()
 }
 
-/// The entity walk, with each hit's optional **member identity** (a blob hit names the placement
-/// under the cursor, not the blob — [`PickBlob`]). [`cast_pick_ray`] drops that half; the identified
-/// cast ([`cast_object_ray`]) is the reason it exists.
+/// The entity walk; a blob hit carries its member's identity ([`PickBlob`]).
 fn cast_pick_ray_impl(
     ray: Ray3d,
     pickable: &HashSet<Entity>,
@@ -283,11 +199,10 @@ fn cast_pick_ray_impl(
             continue;
         };
         if !vis.get() {
-            continue; // not drawn in any view this frame — the old cast's VisibleInView rule
+            continue; // not drawn in any view this frame
         }
-        // A blob's bound is the union of its members and is authored (`NoAutoAabb`), so it is
-        // both the broad phase and the only thing the ray can be rejected on before the members
-        // are walked. A blob with no bound is narrow-tested unconditionally, like a bound-less part.
+        // A blob's authored bound (`NoAutoAabb`) is its members' union; a blob with no bound is
+        // narrow-tested unconditionally, like a bound-less part.
         let entry = match (aabb, mesh, is_box, blob) {
             (Some(aabb), _, _, Some(_)) => {
                 let bound = if inflate {
@@ -306,8 +221,8 @@ fn cast_pick_ray_impl(
             }
             (None, _, _, Some(_)) => 0.0,
             (Some(aabb), Some(_), _, None) | (Some(aabb), None, true, None) => {
-                // Inflated cast: the halo displaces at most 1 model-unit (local space), so the
-                // local bound grown by exactly that can never clip it.
+                // The halo moves a vertex at most 1 model-unit in local space, so the bound grown
+                // by that never clips it.
                 let bound = if inflate {
                     Aabb {
                         center: aabb.center,
@@ -323,8 +238,7 @@ fn cast_pick_ray_impl(
                 }
             }
             (None, Some(_), _, None) => 0.0,
-            // No pick geometry — a drawn mesh nobody armed for the ray (a liquid surface), or a
-            // `PickBox` with no bound to be. Not pickable, rather than pickable as its bound.
+            // No pick geometry (a liquid surface), or a `PickBox` with no bound: not pickable.
             (_, None, _, None) => continue,
         };
         candidates.push((entry, entity));
@@ -340,9 +254,7 @@ fn cast_pick_ray_impl(
             continue;
         };
         if let Some(blob) = blob {
-            // A blob stands in for many placements: the hit is the MEMBER under the cursor, cast
-            // at the member's own world pose (its geometry is baked into the blob's mesh, but the
-            // resident submesh + placement transform is what it draws).
+            // The hit is the member under the cursor, cast at the member's own world pose.
             for m in blob.0.iter() {
                 let gt = GlobalTransform::from(m.transform);
                 if let Some(h) = ray_submesh(&m.geometry, &gt, origin, dir, inflate) {
@@ -354,8 +266,7 @@ fn cast_pick_ray_impl(
         }
         let hit = match mesh {
             Some(m) => ray_submesh(&m.0, gt, origin, dir, inflate),
-            // A `PickBox` (the broad phase admitted no other mesh-less candidate): its box entry is
-            // exactly its surface, the cuboid BEING its Aabb (grown by the halo when inflated).
+            // A `PickBox`: its box entry is its surface (grown by the halo when inflated).
             None => Some(RayHit {
                 point: origin + dir * entry,
                 normal: -dir,
@@ -369,25 +280,17 @@ fn cast_pick_ray_impl(
     }
     hits.sort_unstable_by(|a, b| a.2.distance.total_cmp(&b.2.distance));
     if !all_hits {
-        // One hit for the whole cast — but a blob contributes one per member, so the truncation
-        // has to come after the sort (it does) and cannot be a per-entity dedup.
+        // A blob contributes one hit per member, so truncate after the sort, not per entity.
         hits.truncate(1);
     }
     hits
 }
 
-/// The narrow phase for one part: ray-test every triangle of its resident geometry, in **model-local
-/// space** — the world ray mapped through the part's inverse affine, under which the ray parameter is
-/// unchanged, so a local `t` (against the world-normalized direction's image) *is* the world distance.
-/// Vertices go through the render form's own bake (`build_submesh_mesh`): `wow_to_bevy` per vertex,
-/// a billboard card centred at its pivot — so the pick tests exactly the surface the part draws
-/// (a card's live camera-facing rotation rides its `GlobalTransform`, shared here too). With
-/// `inflate` (the generous pass 2, decision 1071), each vertex is additionally displaced by its
-/// authored normal, raw — 1 model-unit in local space, which the world transform then scales,
-/// exactly the reference's `skinned_pos + rot·normal` with no extra constant. `wow_to_bevy` is a
-/// pure axis permutation with sign flips (orthonormal), so applying it to the normal is exact. A
-/// submesh authored without normals can't build the halo and reports a miss (the exact pass
-/// already had its say).
+/// The narrow phase for one part, in model-local space: the ray mapped through the inverse affine
+/// keeps its parameter, so a local `t` is the world distance. Vertices take the render form's own
+/// bake (`wow_to_bevy`, a billboard card centred at its pivot). With `inflate`, each vertex also
+/// moves by its authored normal, raw (the reference's `skinned_pos + rot·normal`); a submesh
+/// without normals then reports a miss.
 fn ray_submesh(
     geo: &RenderSubmesh,
     gt: &GlobalTransform,
@@ -396,7 +299,7 @@ fn ray_submesh(
     inflate: bool,
 ) -> Option<RayHit> {
     if inflate && geo.normals.len() != geo.positions.len() {
-        return None; // no authored normals — no halo to build
+        return None; // no authored normals, no halo
     }
     let inv = gt.affine().inverse();
     let local_origin = inv.transform_point3(origin);
@@ -416,7 +319,7 @@ fn ray_submesh(
     let mut nearest: Option<(f32, [Vec3; 3])> = None;
     for t in geo.indices.as_chunks::<3>().0 {
         let (Some(a), Some(b), Some(c)) = (pos(t[0]), pos(t[1]), pos(t[2])) else {
-            continue; // an out-of-range index — corrupt authoring; skip the triangle, not the model
+            continue; // an out-of-range index: skip the triangle, not the model
         };
         let tri = [a, b, c];
         if let Some(d) = ray_triangle(local_origin, local_dir, &tri) {
@@ -437,19 +340,10 @@ fn ray_submesh(
     })
 }
 
-/// The narrow phase for one **skinned** part: skin its vertices through `palette` (world-from-bind-pose joint
-/// matrices — the same transform GPU skinning applies) and ray-test every triangle. With `inflate`
-/// (the reference's pass 2), each vertex is additionally displaced by its **skinned normal, un-
-/// normalized** — the M2 normal is unit-length and the palette carries the world scale, so the
-/// halo is 1 model-unit × scale outward, exactly the binary's `skinned_pos + rot(palette)·normal`
-/// with no extra constant. Returns the nearest world-space hit distance, or `None`. Cost is
-/// bounded by the broad phase: only units near the cursor get here.
-///
-/// This lives here, beside the cast it belongs to, because it composes a **skinning palette** —
-/// the 0720 convention that retired Bevy's skin lane and put the joint data on the WOW attributes.
-/// A caller that re-derives that composition goes wrong silently the day the convention moves
-/// (it does not fail to compile; it stops hitting units), which is the same failure the light
-/// packer's doc records one module over.
+/// The narrow phase for one skinned part: skin its vertices through `palette` (world-from-bind-pose
+/// joint matrices, as GPU skinning applies them) and return the nearest triangle hit's distance.
+/// With `inflate`, each vertex also moves by its skinned normal, un-normalized: a halo of 1
+/// model-unit times the palette's scale (the reference's `skinned_pos + rot(palette)·normal`).
 pub fn ray_posed_mesh(
     mesh_assets: &Assets<Mesh>,
     mesh_id: AssetId<Mesh>,
@@ -463,11 +357,9 @@ pub fn ray_posed_mesh(
     else {
         return None;
     };
-    // The joint data rides the WOW attributes (decision 0720 retired Bevy's skin lane, and
-    // Bevy's `ATTRIBUTE_JOINT_INDEX` left our meshes with it). Every mesh that reaches this
-    // function is a skinned twin by construction (`RigPart` parts only), so a missing
-    // attribute is a broken authoring contract — not an unloaded asset — and it silently
-    // un-picks the whole unit: say so, once, loudly.
+    // The joints ride the WOW attributes, not Bevy's skin attributes. Every mesh here is a skinned
+    // twin (`RigPart` parts only), so a missing attribute is a broken authoring contract that
+    // un-picks the whole unit: warn once.
     let (
         Some(VertexAttributeValues::Uint16x4(joints)),
         Some(VertexAttributeValues::Float32x4(weights)),
@@ -486,8 +378,7 @@ pub fn ray_posed_mesh(
         _ if inflate => return None, // can't build the halo without normals
         _ => None,
     };
-    // Skin every vertex to world space once (blended matrix, as GPU skinning sums it), then walk
-    // the index triangles. Pass 2 adds the rotated normal, translation-free, to the position.
+    // Skin each vertex once by its blended matrix; pass 2 adds the rotated normal.
     let world: Vec<Vec3> = positions
         .iter()
         .enumerate()
@@ -529,9 +420,8 @@ pub fn ray_posed_mesh(
     hits
 }
 
-/// Ray–triangle intersection (Möller–Trumbore), **two-sided**, returning `t ≥ 0` along `dir`
-/// (unnormalized is fine — `t` is in `dir` lengths) or `None` on miss/parallel. Two-sided because a
-/// posed mesh can present back faces at silhouette edges and a generous pick beats a strict one.
+/// Ray-triangle intersection (Möller-Trumbore): `t ≥ 0` in `dir` lengths, `dir` need not be unit.
+/// Two-sided, since a posed mesh shows back faces at its silhouette edges.
 pub(crate) fn ray_triangle(origin: Vec3, dir: Vec3, tri: &[Vec3; 3]) -> Option<f32> {
     let (e1, e2) = (tri[1] - tri[0], tri[2] - tri[0]);
     let p = dir.cross(e2);
@@ -554,9 +444,7 @@ pub(crate) fn ray_triangle(origin: Vec3, dir: Vec3, tri: &[Vec3; 3]) -> Option<f
     (t >= 0.0).then_some(t)
 }
 
-/// A mesh's model-local [`Aabb`] transformed into a world-space axis-aligned box `(min, max)` — its 8
-/// corners run through the entity's world transform, then min/max'd. (An AABB of the rotated box: a hair
-/// larger than the true oriented box, which only makes the hover more forgiving.)
+/// A model-local [`Aabb`] as the world-space box `(min, max)` of its 8 transformed corners.
 pub(crate) fn world_aabb(aabb: &Aabb, gt: &GlobalTransform) -> (Vec3, Vec3) {
     let center = Vec3::from(aabb.center);
     let he = Vec3::from(aabb.half_extents);
@@ -574,8 +462,7 @@ pub(crate) fn world_aabb(aabb: &Aabb, gt: &GlobalTransform) -> (Vec3, Vec3) {
     (min, max)
 }
 
-/// Ray vs axis-aligned box (the slab test): the entry distance along `dir` if the ray hits, else `None`.
-/// `dir` need not be normalized; a zero component is handled by the infinities `recip` produces.
+/// The slab test's entry distance along `dir`; a zero component works through `recip`'s infinities.
 pub(crate) fn ray_aabb(origin: Vec3, dir: Vec3, min: Vec3, max: Vec3) -> Option<f32> {
     let inv = dir.recip();
     let t1 = (min - origin) * inv;
@@ -585,10 +472,8 @@ pub(crate) fn ray_aabb(origin: Vec3, dir: Vec3, min: Vec3, max: Vec3) -> Option<
     (tmax >= tmin.max(0.0)).then_some(tmin.max(0.0))
 }
 
-/// The narrow phase one [`PickSource`] member needs: a resident submesh at a world pose, cast
-/// exactly the way a drawn part's own geometry is ([`ray_submesh`] — the render form's `wow_to_bevy`
-/// bake, billboard cards centred at their pivot). Exposed so a lane answering the ray never
-/// re-derives that bake and drifts from what it draws.
+/// A [`PickSource`] member's narrow phase: a resident submesh at a world pose, cast through the
+/// same bake as a drawn part ([`ray_submesh`]) so no lane re-derives it.
 pub fn ray_member(geometry: &RenderSubmesh, transform: Transform, ray: Ray3d) -> Option<RayHit> {
     ray_submesh(
         geometry,
@@ -599,10 +484,8 @@ pub fn ray_member(geometry: &RenderSubmesh, transform: Transform, ray: Ray3d) ->
     )
 }
 
-/// Ray against a drawn entity's **world-space bound** — its `Aabb` taken through its
-/// `GlobalTransform`, corner by corner, so a rotated model's box is the box of its rotated
-/// corners and not its rotated box. The broad phase, and the whole test for a part whose exact
-/// geometry is not resident.
+/// Ray against an entity's `Aabb` taken to world space corner by corner: the broad phase, and the
+/// whole test for a part with no resident geometry.
 pub fn ray_mesh_bounds(origin: Vec3, dir: Vec3, aabb: &Aabb, gt: &GlobalTransform) -> Option<f32> {
     let (min, max) = world_aabb(aabb, gt);
     ray_aabb(origin, dir, min, max)
@@ -618,10 +501,8 @@ mod tests {
         Vec3::new(0.0, 0.0, 1.0),
     ];
 
-    /// The picker ↔ mesh-builder attribute contract: [`ray_posed_mesh`] must read the WOW joint
-    /// attributes the skinned twin is authored with ([`benilla_assets::ATTRIBUTE_WOW_JOINT_INDEX`],
-    /// decision 0720) — reading Bevy's standard skin attributes made every unit silently
-    /// unpickable, because a `None` here also blocks the AABB fallback (the `faithful` set).
+    /// The skinned twin carries its joints in the WOW attributes
+    /// ([`benilla_assets::ATTRIBUTE_WOW_JOINT_INDEX`]), not Bevy's.
     #[test]
     fn posed_pick_reads_the_wow_skin_attributes() {
         use bevy::asset::RenderAssetUsages;
@@ -644,9 +525,8 @@ mod tests {
         let mut assets = Assets::<Mesh>::default();
         let handle = assets.add(mesh);
 
-        // Bone 1 lifts the triangle +2 on Y; bone 0 is a zero row (a hit through it would land
-        // at the origin) — so a 3.0-distance hit proves the indices routed through the WOW
-        // attribute into the right palette row.
+        // Bone 1 lifts the triangle 2 on Y and bone 0 is a zero row, so a hit at 3.0 proves the
+        // WOW joint index picked row 1.
         let palette = [Mat4::ZERO, Mat4::from_translation(Vec3::Y * 2.0)];
         let t = ray_posed_mesh(
             &assets,
@@ -675,23 +555,18 @@ mod tests {
 
     #[test]
     fn ray_triangle_is_two_sided() {
-        // Same triangle hit from below (reversed winding relative to the ray) still connects.
         assert!(ray_triangle(Vec3::new(0.0, -5.0, 0.0), Vec3::Y, &TRI).is_some());
     }
 
     #[test]
     fn ray_triangle_misses_outside_and_behind() {
-        // Outside the triangle's extent.
         assert!(ray_triangle(Vec3::new(3.0, 5.0, 0.0), Vec3::NEG_Y, &TRI).is_none());
-        // Triangle behind the ray origin (t < 0).
         assert!(ray_triangle(Vec3::new(0.0, 5.0, 0.0), Vec3::Y, &TRI).is_none());
-        // Parallel to the plane.
         assert!(ray_triangle(Vec3::new(0.0, 5.0, 0.0), Vec3::X, &TRI).is_none());
     }
 
-    /// [`TRI`]'s pre-image under `wow_to_bevy` (`bevy = (−y, z, −x)` ⇒ `wow = (−bz, −bx, by)`):
-    /// a submesh authored with THESE WoW-space positions must be picked exactly where the render
-    /// form draws it, i.e. at [`TRI`] in model-local Bevy space.
+    /// [`TRI`]'s pre-image under `wow_to_bevy` (`bevy = (−y, z, −x)`), so it draws at [`TRI`] in
+    /// model-local Bevy space.
     fn wow_tri() -> RenderSubmesh {
         RenderSubmesh {
             positions: vec![[1.0, 1.0, 0.0], [1.0, -1.0, 0.0], [-1.0, 0.0, 0.0]],
@@ -700,10 +575,6 @@ mod tests {
         }
     }
 
-    /// The picker ↔ render-form bake contract (decision 0857): [`ray_submesh`] must test the
-    /// resident WoW-axes geometry through the SAME `wow_to_bevy` bake `submesh_to_static_mesh`
-    /// builds the drawn mesh with, under the part's world transform — the render mesh itself is
-    /// `RENDER_WORLD`-only (0834), so this path is the only thing keeping static models pickable.
     #[test]
     fn resident_geometry_picks_where_the_render_form_draws() {
         let mesh = PickMesh(std::sync::Arc::new(wow_tri()));
@@ -715,12 +586,11 @@ mod tests {
         assert!((hit.distance - 5.0).abs() < 1e-4);
         assert!(hit.point.abs_diff_eq(Vec3::new(10.0, 1.0, 0.0), 1e-4));
         assert!(hit.normal.abs_diff_eq(Vec3::Y, 1e-4) || hit.normal.abs_diff_eq(-Vec3::Y, 1e-4));
-        // …and a miss stays a miss.
         assert!(ray_submesh(&mesh.0, &gt, Vec3::new(20.0, 6.0, 0.0), Vec3::NEG_Y, false).is_none());
     }
 
-    /// [`wow_tri`] with every vertex normal authored as model-local Bevy `+X` (WoW pre-image
-    /// `(0, −1, 0)`): the inflated pass displaces the whole triangle +1 model-unit in x.
+    /// [`wow_tri`] with every normal model-local Bevy `+X` (WoW `(0, −1, 0)`): the inflated pass
+    /// moves the whole triangle 1 model-unit in x.
     fn wow_tri_with_x_normals() -> RenderSubmesh {
         RenderSubmesh {
             normals: vec![[0.0, -1.0, 0.0]; 3],
@@ -728,11 +598,6 @@ mod tests {
         }
     }
 
-    /// **Decision 1071 — the generous pass.** The inflated narrow phase displaces each vertex by
-    /// its authored normal, raw: 1 model-unit in local space, scaled by the part's world transform
-    /// (the reference's `skinned_pos + rot·normal`, no extra constant). A ray 1 world-unit beyond
-    /// the drawn silhouette misses the exact pass and hits the halo; the halo is 2 world-units wide
-    /// here because the part's scale is 2.
     #[test]
     fn inflated_pick_hits_the_one_model_unit_halo() {
         let mesh = PickMesh(std::sync::Arc::new(wow_tri_with_x_normals()));
@@ -744,12 +609,10 @@ mod tests {
         let hit = ray_submesh(&mesh.0, &gt, Vec3::new(13.0, 6.0, 0.0), Vec3::NEG_Y, true)
             .expect("the halo must catch a ray 1 world-unit past the silhouette");
         assert!((hit.distance - 5.0).abs() < 1e-4);
-        // …and the halo has its own edge: 2 world-units past the ×2 halo is still a miss.
+        // The halo has its own edge: x=16 is 2 world-units past it.
         assert!(ray_submesh(&mesh.0, &gt, Vec3::new(16.0, 6.0, 0.0), Vec3::NEG_Y, true).is_none());
     }
 
-    /// A submesh authored without normals cannot build the halo: the inflated pass reports a miss
-    /// (never a panic, never a silently un-displaced hit) — the exact pass already had its say.
     #[test]
     fn no_authored_normals_means_no_halo() {
         let mesh = PickMesh(std::sync::Arc::new(wow_tri()));
@@ -757,9 +620,8 @@ mod tests {
         assert!(ray_submesh(&mesh.0, &gt, Vec3::new(10.0, 6.0, 0.0), Vec3::NEG_Y, true).is_none());
     }
 
-    /// Cast a ray at a hand-built world and report `(entity, distance)` for every hit, nearest
-    /// first — the whole ray, so a candidate that was silently dropped is distinguishable from one
-    /// that merely lost. `inflate` runs the generous pass instead of the exact one.
+    /// Every hit along the ray at a hand-built world, nearest first, as `(entity, distance)`: the
+    /// whole ray, so a dropped candidate differs from one that lost.
     fn cast_in(world: &mut World, origin: Vec3, dir: Vec3, inflate: bool) -> Vec<(Entity, f32)> {
         use bevy::ecs::system::RunSystemOnce;
         fn cast(
@@ -779,8 +641,7 @@ mod tests {
             .expect("cast")
     }
 
-    /// Everything a drawn, bounded, visible part needs to be a pick candidate — minus the geometry,
-    /// which each test supplies (or deliberately withholds).
+    /// A drawn, bounded, visible part with no pick geometry; each test supplies its own.
     fn drawn(world: &mut World, at: Vec3, half: Vec3) -> EntityWorldMut<'_> {
         use bevy::camera::visibility::SetViewVisibility;
         let mut e = world.spawn((
@@ -794,15 +655,11 @@ mod tests {
         e
     }
 
-    /// **Decision 0929.** A drawn, identified, bounded entity with NO pick geometry — a WMO group's
-    /// MLIQ pool, whose render mesh keeps the whole (mostly dry) vertex grid and so bounds a box
-    /// ~100 yd tall over a city — must be transparent to the ray. It used to be picked at its box
-    /// entry, which put an invisible occluder in front of everything: inside Ironforge every hover,
-    /// on any NPC or GameObject, answered "Wmo · ironforge.wmo".
+    /// A WMO group's MLIQ pool: drawn, identified and bounded, with no pick geometry.
     #[test]
     fn a_bounded_mesh_less_entity_is_not_a_pick_occluder() {
         let mut world = World::new();
-        // The pool's box straddles the camera (entry 0.0 — it wins any distance sort it enters).
+        // The pool's box straddles the camera: entry 0.0 wins any distance sort it enters.
         let pool = drawn(&mut world, Vec3::ZERO, Vec3::new(60.0, 60.0, 60.0)).id();
         // The NPC behind it: real geometry at 10 yd (`wow_tri` spans x,z ∈ [-1,1] at y = 0).
         let npc = drawn(&mut world, Vec3::new(0.0, -10.0, 0.0), Vec3::splat(1.0))
@@ -816,8 +673,6 @@ mod tests {
         assert_eq!(hits.first().map(|(e, _)| *e), Some(npc));
     }
 
-    /// The other half of the same law: an entity that DECLARES its box is its shape ([`PickBox`] —
-    /// the model-less cube fallback) is still picked, at the box entry.
     #[test]
     fn a_declared_pick_box_is_picked_at_its_box_entry() {
         let mut world = World::new();
@@ -830,10 +685,6 @@ mod tests {
         assert!((hits[0].1 - 8.0).abs() < 1e-4, "{hits:?}"); // the box's near face
     }
 
-    /// **Decision 1071, the broad phase.** The inflated cast must grow the candidate's bound by the
-    /// same 1 model-unit as the halo, or the slab test rejects the entity before its halo is ever
-    /// narrow-tested — a mesh whose bound the ray misses by half a unit must still halo-hit. And a
-    /// [`PickBox`] inflates its declared cuboid the same way (its box IS its geometry).
     #[test]
     fn inflated_cast_grows_the_broad_bound_with_the_halo() {
         let mut world = World::new();
@@ -841,14 +692,14 @@ mod tests {
         let herb = drawn(&mut world, Vec3::new(0.0, -10.0, 0.0), Vec3::splat(1.0))
             .insert(PickMesh(std::sync::Arc::new(wow_tri_with_x_normals())))
             .id();
-        // x=1.5: outside the exact bound (the uninflated cast drops the candidate entirely)…
+        // x=1.5: outside the exact bound, so the uninflated cast drops the candidate,
         assert!(cast_in(&mut world, Vec3::new(1.5, 0.0, 0.0), Vec3::NEG_Y, false).is_empty());
-        // …inside the halo (and the inflated bound that must admit it).
+        // and inside the halo and the inflated bound.
         let hits = cast_in(&mut world, Vec3::new(1.5, 0.0, 0.0), Vec3::NEG_Y, true);
         assert_eq!(hits.first().map(|(e, _)| *e), Some(herb));
 
         // The cube fallback: box spans x∈[-2,2] at y∈[-12,-8]; a ray at x=2.5 misses the exact
-        // cuboid, hits the 1-unit-inflated one — at its grown near face (y=-7 → entry 7).
+        // cuboid and hits the inflated one at its grown near face (y=-7, entry 7).
         let mut world = World::new();
         let cube = drawn(&mut world, Vec3::new(0.0, -10.0, 0.0), Vec3::splat(2.0))
             .insert(PickBox)
@@ -893,11 +744,6 @@ mod tests {
             .expect("cast")
     }
 
-    /// **Decision 1534.** A consolidated blob draws many placements as one entity, and its baked
-    /// mesh is their union — so casting against the blob could only ever answer with the blob
-    /// ("static-merge", which is what its own `WorldObject` says). A [`PickBlob`] declares the
-    /// members instead: the cast names the PLACEMENT under the cursor, at that placement's own
-    /// pose, and the members are depth-ordered among themselves like separate parts would be.
     #[test]
     fn a_blob_names_the_member_under_the_cursor() {
         let mut world = World::new();
@@ -939,9 +785,6 @@ mod tests {
         );
     }
 
-    /// The blob's drawn test is still the ENTITY's: a blob the render world culled must be as
-    /// transparent to the ray as any other undrawn part (the `ViewVisibility` rule the entity
-    /// path has always had).
     #[test]
     fn an_undrawn_blob_is_transparent() {
         let mut world = World::new();
@@ -958,8 +801,7 @@ mod tests {
         assert!(names_in(&mut world, Vec3::new(0.0, 10.0, 0.0), Vec3::NEG_Y).is_empty());
     }
 
-    /// A billboard card's render form is centred at its pivot (`build_submesh_mesh`); the pick must
-    /// subtract the same pivot or it tests the card a whole pivot-offset away from where it draws.
+    /// The render form centres a billboard card at its pivot, so the pick subtracts the same pivot.
     #[test]
     fn billboard_card_picks_pivot_centred() {
         let mut sub = wow_tri();
@@ -972,10 +814,8 @@ mod tests {
             seq_translations: Vec::new(),
         });
         let mesh = PickMesh(std::sync::Arc::new(sub));
-        // The card entity sits AT the pivot's world spot (the spawn sites bake
-        // `transform_point(pivot)` into its translation), so the authored triangle — 3 below the
-        // pivot in model-local Bevy y — draws at world y = 0: a straight-down ray from y = 8 hits
-        // at distance 8. Without the pivot subtraction it would (wrongly) hit at y = 3.
+        // The card entity sits at the pivot's world spot, so the triangle 3 below it draws at world
+        // y = 0 and a ray down from y = 8 hits at 8; without the pivot subtraction, at y = 3.
         let gt = GlobalTransform::from(Transform::from_xyz(0.0, 3.0, 0.0));
         let hit = ray_submesh(&mesh.0, &gt, Vec3::new(0.0, 8.0, 0.0), Vec3::NEG_Y, false)
             .expect("the pivot-centred card must be hit where it draws");
diff --git a/crates/benilla-world/src/interior.rs b/crates/benilla-world/src/interior.rs
index f4aba86f..5c7cab3b 100644
--- a/crates/benilla-world/src/interior.rs
+++ b/crates/benilla-world/src/interior.rs
@@ -1,44 +1,11 @@
-//! Interior lighting classification for ENTITIES: which unit/GameObject M2s stand inside a WMO room.
+//! Interior lighting for entity M2s (units, players, GameObjects, held items): which stand in a
+//! WMO room, and the light law they take there.
 //!
-//! ONE law lights every indoor entity M2 (wow-re `unit-m2-shader-light.md`, the Goldshire-inn
-//! capture's byte-arbitrated trio — superseding `wmo-lit-selector.md` §3.3's class split):
-//!
-//! - **Every entity M2** — unit, player, GameObject, held item — is registered with the same
-//!   entity-node fill (`Node::SetModel 0x6716f0` ← the model setters, dispatched `0x672a20`): its
-//!   env-update attach down-rays the WMO render mesh under the entity and bakes the hit's
-//!   barycentric MOCV — **floor-168/cap-96** — as a directional on the fixed interior axis, plus
-//!   the hit group's MOLR point lobes. Decoded live at machine zero off the abbey INNBENCH draws
-//!   (GameObject) and bit-exact off an inn character draw (unit). Indoors we fold that into an SH
-//!   probe ([`InteriorKind::Bake`]) — the same probe table the MODD props ride.
-//! - The raw **day/night pair at gain 1.0** is the *null-node fallback* (`0x672a2f`: a model whose
-//!   node isn't registered — and our lane when the footprint ray misses or hits a MOPY&1 face).
-//!   The abbey capture's flat-lit characters were this state, not a character-path law; the pair
-//!   itself is NEVER indoor-modified. [`InteriorKind::Matte`] keeps it for bake-less parts.
-//!
-//! One SHADING law, **two ATTACHES.** The law above is type-blind; how a node *finds* its group is
-//! not. `0x6a86d0` forks on `[node+0x90]` bit 13 (`6a8714 test ah,0x20`), written at node creation
-//! from the descriptor TYPEMASK — units/players/doodads take the down-ray attach `0x6a8a20` from
-//! the node POSITION, **GameObjects take the containment attach `0x6a8c10` from the node's world
-//! bounding-box CENTRE** (`[node+0x5c]`), whose face query retries UPWARD on a miss. There is no
-//! subclass test anywhere in the dispatch: the mode bit is the whole fork. We carry it as
-//! [`ContainmentAttach`] on the anchor and as [`crate::wmo_portal::LightAttach`] through the
-//! verdict. Decision 0776 — a GameObject's origin routinely sits at or below its own floor, and
-//! sharing the unit down-ray put those objects outdoors in the middle of a building.
-//!
-//! Entities move and stream independently of their building, so [`classify_entity_interior`]
-//! re-tests them against the placed WMOs. The indoor test is the client's own: a faces-only
-//! ray from the attach's anchor onto the placed groups' geometry
-//! ([`crate::wmo_portal::indoor_verdict_at`] — the LIGHTING-class fork `[node+0xc]`, outdoor iff
-//! the hit group's `MOGI & 0x48` — NOT the zone-text `[node+0x90]` bit-0 predicate, which keys on
-//! `0x8` alone and so calls the `0x40`-only city street groups "indoors"; decision 0475 — and an
-//! outdoor-class WMO surface forces the LIT target, no MCSH beneath the building: the WMO-linked
-//! skip-shadow bit, byte-verified; decisions 0477/0480). One verdict per UNIT, sampled at its
-//! [`InteriorLit::anchor`] — a body's parts must never split across light laws (group bounding
-//! boxes did exactly that at floor level; director-caught, 2026-07-12), and a held/equipped item
-//! M2 anchors at its WEARER's root, never its own carried position: the reference aliases the
-//! wearer's light collector into each item by pointer (`[item+0x3b8]=[wearer+0x3b8]`, `0x718960` —
-//! `unit-light-combine-storm.md`; a hand-anchored shield split from its body, director-caught,
-//! 2026-07-13).
+//! One law lights every entity M2 (`Node::SetModel` `0x6716f0`, dispatched `0x672a20`): indoors,
+//! the node's attach rays onto the WMO render mesh and bakes the hit's barycentric MOCV
+//! (floor-168 / cap-96) on the fixed interior axis, plus the hit group's MOLR lobes, folded here
+//! into an SH probe. Indoors is the lighting class (`[node+0xc]`: outdoor iff `MOGI & 0x48`), not
+//! the zone-text bit, which calls `0x40`-only streets indoors. One verdict per unit, at its anchor.
 
 use std::collections::HashSet;
 
@@ -58,12 +25,8 @@ use crate::terrain_stream::{
 use crate::wmo_portal::{indoor_verdict_at, IndoorVerdict, WmoPortalInstance};
 use benilla_assets::materials::WowModelMaterial;
 
-/// Squared distance (yd²) an entity must move before it's re-tested: an epsilon — the reference
-/// runs the classify + footprint chain EVERY frame for units (the node is unlinked, so the
-/// WorldFrame ramp tail reaches `0x69e280` per tick; wow-re `unit-light-combine-storm.md` c1), so
-/// a moving entity re-samples per frame and the continuous MOCV field never quantizes into steps
-/// (the 0.5-yd gate here was the forge's per-step light flash). A standing entity still costs one
-/// position compare and nothing else.
+/// Squared distance (yd²) before a re-test: an epsilon, since the reference re-runs a unit's
+/// classify and footprint chain every tick (`0x69e280`), so the MOCV light must never step.
 const RESAMPLE_DIST_SQ: f32 = 1e-4;
 
 /// MONKEY (portal lane fade): how fast an anchor's crossfade weight travels between the exterior
@@ -99,9 +62,7 @@ impl WmoResidency {
         self.generation
     }
 
-    /// Replace the resident set, bumping the generation only when it actually changed
-    /// (order-independent, by asset id) — so the per-frame rebuild doesn't defeat the classifier's
-    /// movement gate.
+    /// Bumps the generation only on a real change, so the per-frame rebuild keeps anchors settled.
     pub(crate) fn update(&mut self, next: impl IntoIterator<Item = AssetId<WmoModel>>) {
         let next_ids: HashSet<AssetId<WmoModel>> = next.into_iter().collect();
         if next_ids != self.resident {
@@ -111,40 +72,26 @@ impl WmoResidency {
     }
 }
 
-/// The indoor light LAW an entity's model takes — decided at build time by whether the part built
-/// a bake variant (every M2 does; module docs).
+/// The indoor law a part takes, fixed at build time by whether it built a bake variant.
 #[derive(Clone)]
 pub(crate) enum InteriorKind {
-    /// The plain day/night matte at sun ×1.0 indoors — the reference's null-node fallback. Only
-    /// for parts with no bake variant; the Bake law also lands here on a footprint miss.
+    /// A part with no bake variant: indoors it keeps the day/night matte at gain 1.0.
     Matte,
-    /// Every entity M2 (unit/player/GameObject/held): the footprint-MOCV bake indoors — `material`
-    /// is the interior PROP-lane variant (the shader evaluates the model's SH probe by the
-    /// `MeshTag` slot), `center` the M2 vertex-box centre in Bevy model-local (the fold's MOLR
-    /// reference point, the byte-cited anchor family).
+    /// The footprint-MOCV bake: `material` is the prop-lane variant, which evaluates the SH probe
+    /// the `MeshTag` slot names, and `center` the M2 vertex-box centre (model-local), the fold's
+    /// MOLR reference point.
     Bake {
         material: Handle<WowModelMaterial>,
         center: Vec3,
     },
 }
 
-/// The interior-light membership of ONE M2 batch — the single place a spawn site decides whether
-/// a batch joins its model's law, and under which [`InteriorKind`]. `None` classifies the batch
-/// out entirely (a WMO-display part, which has no interior variant to swap to).
-///
-/// **Every batch of a model goes through this, cards included.** The reference has one light node
-/// per object and every batch shades through the same node fill (wow-re `unit-m2-shader-light.md`);
-/// a billboard BONE re-orients geometry, it does not re-route light. Our billboard batches spawn as
-/// world ROOTS so the facing system can own their transform (0153) — an implementation detail that
-/// must not reach the light, and which did while this policy was written out longhand at each spawn
-/// site and one of them omitted it: a Stratholme hanging sign baked from the room it hangs in while
-/// its own chain cards stayed on the exterior material and lit from the sky (decision 0778).
-///
-/// `anchor` is the model's NET ENTITY root for every caller — body mesh, held item, and card alike
-/// — so a model can never split across the two light laws ([`BodyBakeCenter`] for why an item
-/// aliases its wearer rather than folding from its own position). Each site still writes its own
-/// [`MeshTag`](bevy::mesh::MeshTag): the rig slot and the fade alpha are that site's to seed, and
-/// the classifier composes into them.
+/// One M2 batch's interior-light membership. Every batch of a model takes it, billboard cards
+/// included: the reference shades every batch through the object's one node (`0x7192b0`), and a
+/// billboard bone turns geometry, not light. `anchor` is the model's net entity root, so a model
+/// never splits across laws; `None` is a WMO-display part, with no interior variant. The caller
+/// seeds the part's [`MeshTag`](bevy::mesh::MeshTag) (rig slot, fade alpha); the classifier
+/// composes into it.
 pub fn part_interior_lit(
     exterior: &Handle<WowModelMaterial>,
     interior: Option<&Handle<WowModelMaterial>>,
@@ -166,125 +113,79 @@ pub fn part_interior_lit(
     ))
 }
 
-/// The law a part currently renders under (`None` until first classified).
+/// The law a part renders under.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum AppliedLaw {
     Exterior,
-    /// Indoors on the plain matte (a footprint ray that missed or hit a MOPY&1 face, or a
-    /// bake-less part — the day/night null-node lane).
+    /// Indoors on the day/night pair, unmodified, at gain 1.0: the reference's null-node fallback
+    /// (`0x672a2f`), for a footprint ray that missed or hit a MOPY&1 face, or a bake-less part.
     Matte,
     /// Indoors on the footprint bake, evaluated from this probe-table slot.
     Bake(u16),
 }
 
-/// The unit's own body-model bake centre (M2 vertex-box centre, model-local) on the net entity
-/// ROOT — the interior fold's MOLR reference point for EVERY part that shares the root's verdict,
-/// held items included. The reference has exactly one light node per unit; an equipped item M2
-/// aliases the wearer's collector by pointer (`[item+0x3b8]=[wearer+0x3b8]`, `0x718960` — wow-re
-/// `unit-light-combine-storm.md`), so an item never folds from its own carried position.
-///
-/// For a [`ContainmentAttach`] anchor it is also the **attach anchor** — the reference's
-/// `[node+0x5c]`, the same world point (decision 0776).
+/// The body model's vertex-box centre (model-local) on the net entity root: the MOLR reference
+/// point for every part under the root, held items included, since an item aliases its wearer's
+/// light collector (`[item+0x3b8]=[wearer+0x3b8]`, `0x718960`). For a [`ContainmentAttach`]
+/// anchor it is also the attach point, the reference's `[node+0x5c]`.
 #[derive(Component, Clone, Copy)]
 pub struct BodyBakeCenter(pub Vec3);
 
-/// This anchor's light node runs the **containment attach** (`0x6a8c10`), not the down-ray one —
-/// the reference's `[node+0x90]` bit 13, set at node creation from the descriptor TYPEMASK
-/// (`0x613e10`/`0x670db0`) and dispatched at `0x6a86d0`. In 1.12 exactly one object class carries
-/// it: **GameObjects**. See [`crate::wmo_portal::LightAttach`] for the two lanes at the bytes, and
-/// decision 0776 for what it corrects — a GameObject's origin is frequently at or below its own
-/// floor (a Stratholme portcullis spawns 15 cm under the corridor slab), so the down-ray this lane
-/// used to share left it outside the building on the outdoor light while its identical neighbour
-/// two doors down baked from the same floor.
+/// This anchor's node takes the containment attach from its bounding-box centre (`0x6a8c10`), not
+/// the down-ray from its position (`0x6a8a20`): `[node+0x90]` bit 13, set from the TYPEMASK at node
+/// creation (`0x613e10`/`0x670db0`) for GameObjects alone, forked at `0x6a86d0`. A GameObject's
+/// origin often sits at or under its own floor.
 #[derive(Component)]
 pub struct ContainmentAttach;
 
-/// The part → anchor edge of the classifier's registry (0734): every [`InteriorLit`] part names
-/// its NET ENTITY root here — body parts and held/equipped items alike (module docs — the
-/// reference has one light node per unit and items alias it). Bevy's relationship hooks maintain
-/// the anchor-side [`LitParts`] list through spawn, gear-swap despawn, and teardown, so a law
-/// change can write exactly its own parts and a settled anchor touches none.
+/// A part's net entity root, its anchor; bevy keeps the anchor's [`LitParts`] in step.
 #[derive(Component)]
 #[relationship(relationship_target = LitParts)]
 pub struct ClassifiedBy(pub Entity);
 
-/// The anchor-side part list [`ClassifiedBy`] maintains — the classifier's write fan-out. Never
-/// mutated by hand; bevy removes it when the last part leaves.
+/// An anchor's parts, maintained by [`ClassifiedBy`]; never edited by hand.
 #[derive(Component)]
 #[relationship_target(relationship = ClassifiedBy)]
 pub struct LitParts(Vec<Entity>);
 
-/// The emitter → anchor edge of the same registry: a **LIT** particle emitter names the net-entity
-/// root whose light node it draws under, exactly as a lit mesh batch names it through
-/// [`ClassifiedBy`].
-///
-/// It exists because a light node has **two** consumer classes and only one of them is a mesh. The
-/// reference creates the node from the object's TYPEID — `0x613e10` → `0x670db0` → `0x7134b0` for
-/// every UNIT/PLAYER/GAMEOBJECT/DYNAMICOBJECT/CORPSE — never from what its batches happen to do,
-/// and a particle draw commits that node's light through the same per-batch state producer a
-/// submesh does (the reference has no particle material: it synthesizes an `M2Material` from the
-/// emitter's file record every draw). wow-re `part-lit-normal-space.md` §6.2/§6.7.
-///
-/// Onyxia's lava trap is the case that proves the split: all five of `ONYZIASLAIRLAVATRAP.M2`'s
-/// mesh batches are UNLIT (`m2batch`: flags 0x13) while emitters #0/#1/#2 are lit, so the object
-/// registered no [`LitParts`] at all and the classifier never visited it — 104 of them stood in a
-/// WMO interior taking the day/night sun.
+/// A lit particle emitter's anchor, the net entity root whose light node it draws under. The
+/// reference builds the node from the object's type (`0x613e10` → `0x670db0` → `0x7134b0`) and
+/// commits its light to a particle draw as to a submesh (`0x70baf0`, the material synthesized per
+/// draw at `0x70d8b0`), so an object with only unlit mesh batches is classified for its emitters.
 #[derive(Component)]
 #[relationship(relationship_target = LitEmitters)]
 pub struct EmitterLitBy(pub Entity);
 
-/// The anchor-side emitter list [`EmitterLitBy`] maintains — the second reason an anchor is
-/// classified at all. Never mutated by hand; bevy removes it when the last emitter leaves, which
-/// is what releases an emitter-only anchor's probe slot when its cloud streams out.
+/// An anchor's lit emitters, maintained by [`EmitterLitBy`]; never edited by hand.
 #[derive(Component)]
 #[relationship_target(relationship = EmitterLitBy)]
 pub struct LitEmitters(Vec<Entity>);
 
-/// The constant RGB a LIT particle of this anchor's model is multiplied by — the anchor's own
-/// committed light evaluated along the **world up axis**, which is the only normal a particle quad
-/// ever carries (one constant per draw, wow-re `part-lit-normal-space.md` §2/§3; decision 1696).
-///
-/// Present only while the anchor is on the [`AppliedLaw::Bake`] law. Its ABSENCE is the exterior
-/// lane and means "take the scene's light", which the effect shader applies by itself — so an
-/// outdoor emitter costs nothing here and reads exactly as it did before this component existed.
+/// The constant a lit particle of this anchor multiplies by: the anchor's whole committed term
+/// (`ambient + 0.9·diffuse + Σ lamps`) along world up, a particle quad's only normal (one constant
+/// per draw, `0x7b3fd0`, `0x58b0b0`). Present only on the Bake law; absent, the scene's light.
 #[derive(Component, Clone, Copy, PartialEq, Debug)]
 pub struct ParticleLight(pub [f32; 3]);
 
-/// The **ambient half alone** of this anchor's committed words — `[`GroundShade::ambient`], the
-/// ramped chase toward `cap96(MOCV)`, with no diffuse lobe and no MOLT points.
-///
-/// [`ParticleLight`] is the whole fixed-function term (`ambient + 0.9·diffuse + Σ lamps`) because
-/// that is what a lit particle quad receives. One consumer needs strictly less: a **vertex format
-/// with no normal** disables the normal array outright, so its draw evaluates only the ambient
-/// product — `out = (Σ enabled lights' Ambient) × authoredColour` (wow-re
-/// `gx/scratch/format7-lighting-term.md`). The weapon swing trail is that draw, and it inherits
-/// the *wearer's* committed light, four-way byte-derived through
-/// `0x70d982 → 0x70ca50 → 0x70baf0` plus the held-weapon `[+0x3b8]` alias.
-///
-/// Same lifetime as [`ParticleLight`], for the same reason: present only on [`AppliedLaw::Bake`],
-/// and its ABSENCE is the exterior lane — outdoors a unit's ambient **is** the day/night ambient
-/// (`0x69e4ad`'s exterior intensity leg), so a consumer falls back to the scene's own.
+/// The ambient word alone (`GroundShade::ambient`, ramping toward `cap96(MOCV)`), for a draw whose
+/// vertex format has no normal and so evaluates only `Σ ambient × colour` (`0x592a60`): the weapon
+/// trail, lit by its wearer's node (`0x70d982` → `0x70ca50` → `0x70baf0`). Present only on the Bake
+/// law; outdoors the day/night ambient applies (`0x69e4ad`).
 #[derive(Component, Clone, Copy, PartialEq, Debug)]
 pub struct NodeAmbient(pub [f32; 3]);
 
-/// The anchor's classification record (0734) — the law its parts render under, plus the
-/// movement/residency gate that used to live per part. Inserted by the classifier on the first
-/// resolve; a settled anchor is one distance compare per frame, whatever its part count.
+/// An anchor's classification: its parts' law and room, and the movement/residency re-test gate.
 #[derive(Component)]
 pub struct InteriorAnchor {
     law: AppliedLaw,
-    /// The room the law's own attach ray claimed — `None` on the exterior law. It is the key the
-    /// per-frame interior-FOG gate is asked at, which is why a settled anchor keeps it: the gate's
-    /// answer moves with the CAMERA, so an anchor that never rays again still needs its room.
+    /// The attach's room, `None` outside; kept while settled, as its fog gate tracks the camera.
     room: Option<crate::wmo_portal::WmoRoom>,
-    /// The standing fog verdict for that room, re-read every frame (see [`anchor_room_fogged`]).
+    /// That room's fog verdict, re-read every frame ([`anchor_room_fogged`]).
     fog: bool,
-    /// Anchor position at the last down-ray + the residency generation then — the re-test gate.
+    /// The position and residency generation at the last ray: the re-test gate.
     last_pos: Vec3,
     generation: u32,
-    /// Whether the law was resolved from a bake-capable part's kind — a bake-capable part
-    /// joining a matte-resolved anchor must force a re-resolve (the reauthor drain checks this),
-    /// or it would ride the matte fallback until the anchor next moves.
+    /// Resolved from a bake-capable part; a bake part joining a matte-resolved anchor re-resolves.
     kind_bake: bool,
     /// MONKEY (portal lane fade): the crossfade weight this anchor's parts currently render at —
     /// `0` fully on the exterior result, `1` fully on the room result, chasing
@@ -394,26 +295,17 @@ fn lane_bits(lane: f32) -> u8 {
 #[derive(Resource, Default)]
 pub struct InteriorReauthor(pub Vec<Entity>);
 
-/// The interior/exterior material variants for one entity submesh part, so [`classify_entity_interior`]
-/// can swap by the model's current location without rebuilding. Attached only to M2 entity parts (WMO
-/// group geometry carries per-submesh interior in its own material + baked MOCV); its anchor edge
-/// is the sibling [`ClassifiedBy`]. The `on_add` hook enqueues the part for authoring, so a
-/// gear-swap part joining an already-settled anchor still gets the standing law.
+/// One M2 entity part's material variants, which [`classify_entity_interior`] swaps; adding it
+/// queues the part, so a part joining a settled anchor still takes the standing law.
 #[derive(Component)]
 #[component(on_add = enqueue_new_part)]
 pub struct InteriorLit {
-    /// The model's indoor law ([`InteriorKind`]) — uniform across an anchor's parts.
     kind: InteriorKind,
-    /// The exterior/day-night material (the global-SH lane): since 0354 the Matte law rides it
-    /// too — day/night is the intensity byte at the 1.0 point, not a separate material.
+    /// The exterior material, which the Matte law shares: day/night is the intensity byte at 1.0.
     exterior: Handle<WowModelMaterial>,
-    /// Last applied law — the part's last-written record (the anchor's [`InteriorAnchor`] is the
-    /// authority): the write gate, and [`Self::is_bake`]'s source. `None` until first written.
+    /// The law last written, the write gate; the anchor's [`InteriorAnchor`] is the authority.
     applied: Option<AppliedLaw>,
-    /// The [`crate::mesh_tag::INTERIOR_FOG_BIT`] as last written, beside the law rather than inside
-    /// it: the two are decided by different questions (the law by where this part STANDS, the fog
-    /// by whether that room is on the camera's chain this frame — decision 1792 §4), so a part can
-    /// need a rewrite for one with the other unchanged. Meaningless while `applied` is `None`.
+    /// The [`crate::mesh_tag::INTERIOR_FOG_BIT`] last written; it follows the camera, not the law.
     fogged: bool,
     /// MONKEY (portal lane fade): the tag's lane field as last written, the third component of the
     /// write gate. It has to be recorded separately from `applied` because two writes can name the
@@ -424,22 +316,14 @@ pub struct InteriorLit {
 }
 
 impl InteriorLit {
-    /// Whether this part currently rides the footprint-BAKE lane — the intensity-byte writer's
-    /// skip test: a bake part's tag payload is its probe SLOT, so [`crate::entity_shade`] must not
-    /// write the shade byte over it (every other law carries the byte — since 0354 the day/night
-    /// state is the byte at the intensity-1.0 point, not a material swap).
+    /// On the Bake law: the tag carries the probe slot, so [`crate::entity_shade`] must not write
+    /// the shade byte over it.
     pub(crate) fn is_bake(&self) -> bool {
         matches!(self.applied, Some(AppliedLaw::Bake(_)))
     }
 
-    /// The steady (non-feathering) material for the part's CURRENT law — the classifier's own
-    /// choice, exposed so the fade writers settle a part onto exactly what the classifier would
-    /// have written rather than onto a `cutout` latched before the law was known (decision 0755).
-    ///
-    /// The exterior and day/night (Matte) states share the exterior material: since 0354 the
-    /// difference between them is the node's intensity target (the tag byte `entity_shade` ramps),
-    /// not a separate material. Only the footprint bake swaps the variant — and a matte-KIND part
-    /// under a bake-law anchor has no bake variant to swap to, so it keeps the exterior one.
+    /// The steady material for the current law, which the fade writers settle onto: the bake
+    /// variant on the Bake law, else the exterior one (a matte-kind part has no bake variant).
     pub(crate) fn steady_material(&self) -> &Handle<WowModelMaterial> {
         match (self.applied, &self.kind) {
             (Some(AppliedLaw::Bake(_)), InteriorKind::Bake { material, .. }) => material,
@@ -447,16 +331,8 @@ impl InteriorLit {
         }
     }
 
-    /// Re-point a standing part's law variants at a freshly-built material set, and answer what it
-    /// should now draw — the character **re-dress** (`entities::attach::redress`): a gear change
-    /// re-composites the body atlas and re-resolves the cape texture, so every variant's handle
-    /// changes while the part, the room and therefore the *law* stay exactly as they were.
-    ///
-    /// The applied law is deliberately KEPT, which is what makes this a re-point rather than a
-    /// re-classification: nothing moved, so re-running the down-ray would answer the same thing at
-    /// the cost of a frame on the wrong material. A part's `kind` cannot change under it either —
-    /// bake-capability is a property of the batch's build, and a re-dress never changes which batch
-    /// a part is.
+    /// Re-points the variants at a re-dressed material set (`entities::attach::redress`) and
+    /// returns what to draw; the applied law stays, since a re-dress moves nothing.
     pub fn repoint(
         &mut self,
         exterior: &Handle<WowModelMaterial>,
@@ -479,10 +355,7 @@ impl InteriorLit {
         }
     }
 
-    /// Test-only: a part already recorded as riding the Bake law, so
-    /// [`crate::model_fade::FadeMaterials::material_for`] can be exercised over every law without
-    /// driving a full classifier run from another module ([`AppliedLaw`] is this module's business
-    /// and stays private).
+    /// Test-only: a part already on the Bake law, for tests outside this module.
     #[cfg(test)]
     pub(crate) fn applied_bake_for_test(
         kind: InteriorKind,
@@ -498,23 +371,15 @@ impl InteriorLit {
     }
 }
 
-/// `on_add` hook: a freshly spawned part asks for its anchor's standing law (drained by
-/// [`classify_entity_interior`] — a first-resolving anchor covers its parts anyway, but a part
-/// joining a SETTLED anchor gets no law-change write without this).
+/// Queues a new part: one joining a settled anchor would get no law-change write otherwise.
 fn enqueue_new_part(mut world: DeferredWorld, ctx: HookContext) {
     if let Some(mut queue) = world.get_resource_mut::<InteriorReauthor>() {
         queue.0.push(ctx.entity);
     }
 }
 
-/// Fade latch: re-author the part from its anchor's law the moment `RenderFade` leaves.
-///
-/// Since 0755 this is a **backstop**, not the convergence path it once was — the classifier now
-/// tracks a part's law right through its ramp, and `apply_render_fade` settles the material onto
-/// that law itself at the latch, so the forced re-author is normally a no-op. It stays because its
-/// failure mode is the "unit stays black indoors" bug (a probe slot freed while its part sat
-/// unauthored), which has cost us twice, and one forced write per part at the end of a ramp is
-/// nothing. Removal on despawn also lands here; the drain drops dead entries.
+/// Queues a part whose `RenderFade` leaves. The re-author is normally a no-op, kept as the
+/// backstop against a part left on a freed probe slot, which renders black.
 fn enqueue_on_fade_latch(
     fade_end: On<Remove, RenderFade>,
     parts: Query<(), With<InteriorLit>>,
@@ -525,38 +390,31 @@ fn enqueue_on_fade_latch(
     }
 }
 
-/// Registers the residency registry, the reauthor queue + its fade-latch observer, and the
-/// per-frame entity classifier (the streamer fills the registry).
+/// The residency registry, the reauthor queue with its fade-latch observer, and the classifier.
 pub(crate) struct InteriorPlugin;
 
 impl Plugin for InteriorPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<WmoResidency>()
             .init_resource::<InteriorReauthor>()
-            // **After the flood**, like every other reader of the per-group gate
-            // (`model_render::ModelVisSet`): since the interior-FOG half of a part's channel is
-            // `[0xca7f00]` (decision 1792 §4), classifying before the flood would answer a
-            // camera-move with last frame's rooms. The ray half wants the same order anyway — the
-            // placements it rays are the ones this frame's residency published.
+            // After the room flood: the fog half of a part's channel is the flood's `[0xca7f00]`
+            // chain, and before it a camera move would read last frame's rooms.
             .add_systems(
                 Update,
                 classify_entity_interior
                     .after(crate::wmo_portal::WmoPvsSet)
-                    // The fold reads the resolved `WowLighting`, so it belongs on the resolve's
-                    // read side (`lighting::LightingConsumeSet`, decision 2032).
+                    // The fold reads the resolved `WowLighting`.
                     .in_set(crate::lighting::LightingConsumeSet),
             )
             .add_observer(enqueue_on_fade_latch);
     }
 }
 
-/// The bake fold's cached ray products, on the ANCHOR (net entity root): while the node's ramps
-/// move without the entity moving (it stopped just inside the forge's warm zone), the per-frame
-/// refold re-uses these instead of re-running the down-ray. Written on every ray that lands a
-/// Baked verdict; removed with the law.
+/// The bake fold's ray products on the anchor, refolded without a new ray while the node's ramps
+/// still move and the entity does not.
 #[derive(Component)]
 pub struct BakeState {
-    /// floor-168 of the footprint MOCV word (0..1) — the fold's diffuse, × the node intensity.
+    /// floor-168 of the footprint MOCV (0..1): the fold's diffuse, before the node intensity.
     word: Vec3,
     /// The hit group's windowed MOLR lobes (world space, pre-gained).
     lobes: Vec<PropLobeLight>,
@@ -564,17 +422,10 @@ pub struct BakeState {
     ref_point: Vec3,
 }
 
-/// Light each entity part by where its model stands. Outside ⇒ the exterior lane (the global SH ×
-/// the ramped intensity byte). Inside a WMO room ⇒ the footprint-MOCV bake folded into the
-/// anchor's OWNED SH probe (refolded per frame while the node moves or its ramps chase — the
-/// reference's per-tick env update, decision 0354), or the day/night state = the same exterior
-/// material at the intensity-1.0 byte point. One law for every entity M2, unit and GameObject
-/// alike (module docs). The verdict is the client's faces-only down-ray at the model's anchor —
-/// one ray per UNIT per re-test, re-run only when the anchor moves or a building streams in/out.
-///
-/// The walk is over ANCHORS, not parts (0734): a settled anchor is one distance compare, whatever
-/// its part count, and parts are written only when their anchor's law changes (or through the
-/// [`InteriorReauthor`] drain — a fresh part, a fade latch, the zoom feather's release).
+/// Lights each entity part by where its anchor stands: outside, the global SH × the ramped
+/// intensity byte; in a room, the footprint bake folded into the anchor's own SH probe, or the
+/// day/night matte. An anchor rays again only when it moves or a building streams; its parts are
+/// written only when its law changes, or through [`InteriorReauthor`].
 #[allow(clippy::type_complexity)]
 pub fn classify_entity_interior(
     mut commands: Commands,
@@ -586,11 +437,8 @@ pub fn classify_entity_interior(
     adt_tiles: Res<Assets<AdtTile>>,
     lighting: Res<crate::lighting::WowLighting>,
     mut probes: ResMut<PropProbes>,
-    // The walk is over LIGHT NODES: an anchor is visited when it has a lit mesh part **or** a lit
-    // particle emitter, because those are the node's two consumer classes ([`EmitterLitBy`]). The
-    // filter is what keeps it a light-node walk and not a walk over every entity in the world —
-    // a node with no consumer would still ray, and would still take a probe slot from a table
-    // that has a floor.
+    // Light nodes with a consumer, a lit mesh part or a lit emitter ([`EmitterLitBy`]): any other
+    // node would still ray and take a slot from a bounded probe table.
     mut anchors: Query<
         (
             Entity,
@@ -610,19 +458,14 @@ pub fn classify_entity_interior(
     seats: Query<&PropProbeSlot>,
     mut queue: ResMut<InteriorReauthor>,
     part_anchors: Query<&ClassifiedBy>,
-    // Fading parts are **included** (decision 0755). The light law and the fade alpha are
-    // orthogonal, and they are deconflicted by field, not by lockout: the classifier's payload
-    // writes carry the tag's alpha field through (`mesh_tag::with_interior_probe` /
-    // `with_exterior_reset`), and a fading part takes the BLEND twin of its law from the very
-    // rule the ramp itself applies (`FadeMaterials::material_for`) — same handle, either order,
-    // no fight. Excluding them is what left a streamed indoor entity with no law at all for the
-    // whole 2 s ramp, so it appeared under exterior light and swapped to its room's in one frame
-    // at the latch.
+    // Fading parts included, or an entity streaming in indoors fades in under exterior light. The
+    // writes keep the tag's alpha, and take the law's blend twin by the ramp's own rule
+    // (`FadeMaterials::material_for`), so the two writers never fight.
     mut parts: PartWrite,
 ) {
     let _t0 = std::time::Instant::now();
     let (mut n_anchors, mut n_resolved, mut n_written) = (0usize, 0usize, 0usize);
-    // Anchors that wanted a resolve but had every part fade-excluded — the appear-fade lockout.
+    // Anchors with no part to ask, the tripwire for a fade lockout creeping back.
     let mut n_fade_blocked = 0usize;
     let mut resolve_us = 0.0f32;
     for (
@@ -640,11 +483,8 @@ pub fn classify_entity_interior(
         n_anchors += 1;
         let pos = anchor_t.translation();
         let had_state = state.is_some();
-        // Skip the down-ray entirely for a settled anchor (no movement, no building streamed) —
-        // this is what keeps a town full of standing NPCs/props at one compare per frame. A
-        // Bake-law anchor whose node ramps still chase keeps refolding (from the cached ray
-        // products — no new ray), so a unit that stops just inside a warm zone finishes its
-        // transition instead of freezing mid-ramp.
+        // A settled anchor skips the ray. On the Bake law it refolds from the cached products while
+        // its ramps chase, so a unit that stops in a warm room does not freeze mid-ramp.
         if let Some(state) = state.as_deref_mut() {
             let settled = state.generation == residency.generation
                 && pos.distance_squared(state.last_pos) < RESAMPLE_DIST_SQ;
@@ -660,8 +500,7 @@ pub fn classify_entity_interior(
                                 slot,
                                 fold_interior_probe(words.0, words.1, bake.ref_point, &bake.lobes),
                             );
-                            // The mesh's probe and the emitters' constant off the SAME committed
-                            // words, through the two lanes' different curves (1709).
+                            // The emitters' constant, from the same words through its own curve.
                             if let Some(mut light) = particle_light {
                                 light.set_if_neq(ParticleLight(interior_light_up(
                                     words.0,
@@ -670,19 +509,15 @@ pub fn classify_entity_interior(
                                     &bake.lobes,
                                 )));
                             }
-                            // …and the ambient word on its own, for the normal-less draws whose
-                            // term is that product and nothing else ([`NodeAmbient`]).
+                            // The ambient word alone, for normal-less draws ([`NodeAmbient`]).
                             if let Some(mut amb) = node_ambient {
                                 amb.set_if_neq(NodeAmbient(words.0));
                             }
                         }
                     }
                 }
-                // The law is settled; the FOG is not. Its gate is the camera's chain, not this
-                // anchor's position (decision 1792 §4) — a unit standing perfectly still leaves
-                // and rejoins its building's MFOG as the camera walks between rooms — so the one
-                // thing a settled anchor still re-reads is this bit. A compare per anchor, and a
-                // part write only on the frames the verdict actually moves.
+                // The fog is not settled: its gate is the camera's chain, so a still unit leaves
+                // and rejoins its building's MFOG as the camera walks between rooms.
                 let fog = anchor_room_fogged(state.room, &instances);
                 // MONKEY (portal lane fade): the settled gate above is MOVEMENT, and the blend is
                 // TIME — a unit that steps through a doorway and stops dead in it (or is stopped
@@ -703,14 +538,8 @@ pub fn classify_entity_interior(
                 continue;
             }
         }
-        // Re-resolving. The law is anchor-level and reduces to ONE input — the footprint fold's
-        // reference point, or `None` for the day/night matte — so this asks the anchor's first
-        // classifiable part for it. Since 0755 a fading part is classifiable, so the part arm only
-        // comes up empty on an anchor whose parts have all been despawned (a teardown mid-frame).
-        //
-        // An anchor with NO mesh part at all is the emitter-only node: nothing to ask, and every
-        // entity M2 bakes (see [`InteriorKind`]), so it takes the footprint law from its own bake
-        // centre. `fade_blocked` stays as the tripwire that the 0755 lockout has not crept back in.
+        // Re-resolving. The law's one input is the fold's reference point (`None` for the matte),
+        // asked of the first part; an emitter-only anchor bakes from its own centre.
         let part_bake = lit_parts
             .into_iter()
             .flat_map(LitParts::iter)
@@ -794,38 +623,16 @@ pub fn classify_entity_interior(
         if !law_changed && !lane_moved {
             continue;
         }
-        // `WOW_INTERIOR_LOG=1`: print interior classifications — the live-probe instrument for
-        // "did this entity actually classify indoors, and under which law?". Scoped to interior
-        // verdicts (plus interior→exterior flips) so the world's exterior masses stay silent. The
-        // ATTACH and the point it probed are printed too (0776): a line that says only "exterior"
-        // can't be read without knowing which lane produced it, and the two lanes now probe
-        // different points.
-        // Scoped to interior verdicts (plus interior→exterior flips) so the world's exterior
-        // masses stay silent — but `WOW_INTERIOR_LOG=all` prints the first-resolve exteriors too,
-        // which is the ONLY reading that answers "this thing is standing in a room and isn't
-        // lighting like it": a node that resolves exterior and stays there is otherwise invisible
-        // to this instrument, and looks identical to a node the walk never visited.
+        // `WOW_INTERIOR_LOG=1` prints interior verdicts and flips out of them, with the attach and
+        // the point it probed; `=all` adds the first-resolve exteriors.
         let log = std::env::var("WOW_INTERIOR_LOG").ok();
         // `law_changed` and not the write condition: the blend's frames are not classifications.
         if log.is_some()
             && law_changed
             && (law != AppliedLaw::Exterior || had_state || log.as_deref() == Some("all"))
         {
-            // The PART COUNT is load-bearing, not decoration: a lane readout says which law the
-            // model took, never which of its batches actually joined. A billboard card that
-            // silently classified out is invisible to every other reading of this line — the
-            // Stratholme sign baked correctly *and* its chains lit from the sky, and the anchor
-            // log said only "INTERIOR bake" for weeks (decision 0778). Compare it against the
-            // model's batch count (`benilla-extract m2batch <model>`).
-            //
-            // The EMITTER count is the same reading for the node's other consumer class: a model
-            // whose batches are all unlit registers zero parts and is here entirely on its lit
-            // emitters, and "0 parts / 0 emitters" is impossible — so the pair says which
-            // consumer put this node in front of the classifier, which is otherwise invisible.
-            // The ROOM and its fog gate ride the same line as the law, because since 1792 §5 they
-            // are the other half of what a part's channel says: "INTERIOR matte" alone cannot
-            // distinguish a unit wearing its building's MFOG from one on the scene fog two rooms
-            // out, and that difference is the whole of B335's colour.
+            // The part and emitter counts show what joined: compare the model's batch count
+            // (`benilla-extract m2batch <model>`).
             let room = match room {
                 Some(r) => format!(
                     " room g{} of {:?} · fog {}",
@@ -860,9 +667,8 @@ pub fn classify_entity_interior(
         }
         n_written += write_anchor_parts(law, fog, lane, lit_parts, &mut parts);
     }
-    // Drain the convergence queue: each entry re-authors from its anchor's standing law. Forced
-    // through the part's change gate — the enqueuing edges (fade latch, zoom release) mean a
-    // transient author overwrote the material/tag while `applied` stayed current.
+    // Drain the queue past each part's change gate: a transient writer (a fade, the zoom
+    // feather) may have overwritten its material or tag while `applied` stayed current.
     for part in std::mem::take(&mut queue.0) {
         let Ok(edge) = part_anchors.get(part) else {
             continue; // despawned since enqueue
@@ -871,16 +677,14 @@ pub fn classify_entity_interior(
             continue;
         };
         let Some(state) = state.as_deref_mut() else {
-            continue; // law not resolved yet — the anchor's first resolve writes every part
+            continue; // unresolved: the anchor's first resolve writes every part
         };
         let Ok((mut lit, mut material, mut tag, fm, ramping, pending)) = parts.get_mut(part) else {
             continue; // despawned between the enqueue and the drain
         };
         let fade = fm.filter(|_| ramping || pending);
-        // The mixed-kind hole: a bake-capable part joining an anchor whose law was resolved from
-        // a matte-kind part must force a re-resolve (drop the record; next frame re-rays) — the
-        // standing law can't say Bake. Written with the standing law this frame regardless, so
-        // the part isn't naked for the gap.
+        // A bake part on a matte-resolved anchor drops the record, so the next run re-rays; it
+        // still takes the standing law this frame.
         if matches!(lit.kind, InteriorKind::Bake { .. }) && !state.kind_bake {
             commands.entity(edge.0).try_remove::<InteriorAnchor>();
         }
@@ -898,18 +702,11 @@ pub fn classify_entity_interior(
             fade,
         ));
     }
-    // `WOW_INTERIOR_COST=1`: this lane's per-frame cost, in the terms that diagnose it — how many
-    // anchors the walk visits vs how many actually re-resolve vs how many PARTS got written, and
-    // what the resolves cost. The split is the whole diagnosis (it sent the 2026-07-27 hunt into
-    // the WMO column rays, decision 0711, and priced 0732's slice C — the 13.7k-part walk this
-    // anchor walk replaced). Cheap enough to leave in: three counters and one `Instant` per frame.
+    // `WOW_INTERIOR_COST=1`: anchors visited and resolved, parts written, and the cost per frame.
     static COST: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     if *COST.get_or_init(|| std::env::var_os("WOW_INTERIOR_COST").is_some()) {
-        // `WOW_COLUMN_COST=1` adds the column-query split to the same line: this lane IS the
-        // grid's caller, so its per-frame traffic belongs beside its per-frame cost. `spanning` was
-        // 0711's residual — the oversized floor slabs tested on every query, 99.26 % of everything
-        // tested when 1351 finally measured it. It is now the coarse level's residue and should
-        // read near zero; `spanning_pct` climbing is the regression watch.
+        // `WOW_COLUMN_COST=1` adds this lane's column-grid queries; `spanning` (oversized floor
+        // slabs tested on every query) should read near zero.
         let column = if benilla_assets::column_grid::column_cost_enabled() {
             let (queries, binned, coarse, spanning) =
                 benilla_assets::column_grid::take_column_query_stats();
@@ -933,9 +730,8 @@ pub fn classify_entity_interior(
     }
 }
 
-/// The classifier's part-write query: a part's law record, the material and tag the law authors,
-/// and the fade state that picks the material's blend twin. Named because both the system and its
-/// shared write loop ([`write_anchor_parts`]) take it.
+/// The classifier's part-write query: the law record, the material and tag the law writes, and the
+/// fade state that picks the blend twin.
 type PartWrite<'w, 's> = Query<
     'w,
     's,
@@ -949,9 +745,8 @@ type PartWrite<'w, 's> = Query<
     ),
 >;
 
-/// Author every part of one anchor from its standing `(law, fog)` — the classifier's ONE part-write
-/// loop, shared by the law resolve and by the per-frame fog gate, so the two can never write the
-/// channel differently. Returns how many parts actually took a write.
+/// Writes every part of one anchor from `(law, fog)`: the one loop the resolve and the fog gate
+/// share, so they never write the channel differently.
 fn write_anchor_parts(
     law: AppliedLaw,
     fog: bool,
@@ -1104,10 +899,8 @@ fn anchor_room_fogged(
     inst.fogs_group(room.group)
 }
 
-/// The attach and its anchor point — one choice, because `0x6a86d0`'s mode fork picks both the
-/// routine and the field it reads: a GameObject attaches by CONTAINMENT from its world
-/// bounding-box centre (`[node+0x5c]`), everything else DOWN-RAYS from its position
-/// (`[node+0xa8]`). Decision 0776.
+/// The attach and its point, one fork at `0x6a86d0`: containment from the world bounding-box
+/// centre (`[node+0x5c]`) for a GameObject, else the down-ray from the position (`[node+0xa8]`).
 fn attach_anchor(
     containment: bool,
     bake_center: Option<&BodyBakeCenter>,
@@ -1118,22 +911,16 @@ fn attach_anchor(
         (true, Some(BodyBakeCenter(center))) => {
             (LightAttach::Containment, anchor_t.transform_point(*center))
         }
-        // A containment anchor whose body model carries no bounds yet degrades to its origin — the
-        // same point the down-ray lane uses, never a wrong one.
+        // No bounds yet: the origin, the down-ray's own point.
         (true, None) => (LightAttach::Containment, anchor_t.translation()),
         (false, _) => (LightAttach::DownRay, anchor_t.translation()),
     }
 }
 
-/// Resolve one anchor's indoor law: the down-ray verdict, the node's target/seed updates, and for
-/// the Bake law the footprint fold into the anchor's OWNED probe slot. (The settled ramp-only
-/// refold from the cached ray products lives in the caller's walk — this always rays.) `seated` —
-/// the anchor's live [`PropProbeSlot`] — is the ONLY authority on that slot: Bake stays on it,
-/// entry/exit is judged by it, and a part-cached `Bake(slot)` is never believed (a fresh part
-/// once re-allocated here and freed the seated slot under the anchor's other parts — the
-/// stuck-black-unit bug; the fade-latch reauthor is the other half). The slot component lives on
-/// the ANCHOR — its on-remove hook frees the slot on despawn; law transitions remove/insert it
-/// here.
+/// Rays one anchor and resolves its law, updating its node and, on the Bake law, folding into the
+/// anchor's own probe slot. `seated`, the anchor's live [`PropProbeSlot`], is the only authority
+/// on that slot: a part's cached `Bake(slot)` is never believed, or a fresh part could free the
+/// slot under its siblings and leave them black.
 fn resolve_anchor_law(
     commands: &mut Commands,
     probes: &mut PropProbes,
@@ -1158,9 +945,8 @@ fn resolve_anchor_law(
         attach_at,
         attach,
     );
-    // Publish the outdoor GROUND kind to the node before the law resolves: standing on an
-    // outdoor-class WMO surface (street/deck/porch) forces the lit 2.5 target — the WMO-linked
-    // skip-shadow bit, byte-verified (0477/0480; `entity_shade` reads it).
+    // An outdoor-class WMO surface (street, deck, porch) sets the node's skip-shadow bit: the lit
+    // 2.5 target with no MCSH beneath, which `entity_shade` reads.
     let on_wmo = matches!(verdict, IndoorVerdict::OutdoorsOnWmo);
     if let Ok(mut node) = nodes.get_mut(anchor) {
         if node.on_wmo != on_wmo {
@@ -1177,23 +963,16 @@ fn resolve_anchor_law(
                 IndoorVerdict::Outdoors | IndoorVerdict::OutdoorsOnWmo => AppliedLaw::Exterior,
                 IndoorVerdict::DayNight => AppliedLaw::Matte,
                 IndoorVerdict::Baked { mocv, lobes } => {
-                    // The committed words: ambient chases cap96(MOCV) through the node's 2.0/s
-                    // ramp (seeded from the scene ambient on lane entry, so walking into a warm
-                    // room ramps rather than pops — the reference's `[+0x9c]` carries across the
-                    // leg flip); diffuse = floor-168(MOCV) × the node's ramped intensity (1.0
-                    // settled indoors; >1 transient while descending from an exterior 2.5 — the
-                    // trace's "instance E") on the fixed axis + the hit group's windowed MOLR
-                    // lobes from the model's bbox-centre reference point. Refolded per frame
-                    // while the entity moves or the chases run (the reference re-runs its attach
-                    // per env update — for a settled entity every input is time-independent).
+                    // The ambient chases cap96(MOCV) at the node's 2.0/s ramp, seeded from the
+                    // scene ambient on entry (the reference's `[+0x9c]` carries across the leg
+                    // flip); the diffuse is floor-168(MOCV) × the ramped intensity, plus MOLR.
                     let ref_point = anchor_t.transform_point(center);
                     let word = Vec3::from_array(floor168(mocv));
                     let (ambient, intensity) = match nodes.get_mut(anchor) {
                         Ok(mut node) => {
                             let target = Vec3::from_array(cap96(mocv));
-                            // Lane ENTRY is "the anchor holds no slot" — a fresh part joining an
-                            // already-seated anchor (a gear swap indoors) must neither reseed the
-                            // ambient ramp nor re-allocate; the anchor is mid-lane.
+                            // Entry is "no seated slot": a part joining a seated anchor (a gear
+                            // swap indoors) must not reseed the ramp.
                             if seated.is_none() {
                                 node.seed_ambient(Vec3::from_array(lighting.ambient), target);
                             } else {
@@ -1201,16 +980,14 @@ fn resolve_anchor_law(
                             }
                             (node.ambient, node.intensity())
                         }
-                        // A bake-capable anchor without a node (no GroundShade yet): the settled
-                        // committed words, directly.
+                        // No `GroundShade` yet: the settled words.
                         Err(_) => (Vec3::from_array(cap96(mocv)), 1.0),
                     };
                     let words = (ambient.to_array(), (word * intensity).to_array());
                     let coeffs = fold_interior_probe(words.0, words.1, ref_point, &lobes);
                     let emitter_light = interior_light_up(words.0, words.1, ref_point, &lobes);
                     let slot = match seated {
-                        // Staying in Bake: the anchor keeps its owned slot, rewritten in place —
-                        // no component churn, no extraction churn.
+                        // Staying in Bake: the owned slot is rewritten in place.
                         Some(slot) => {
                             probes.update_owned(slot, coeffs);
                             Some(slot)
@@ -1219,21 +996,15 @@ fn resolve_anchor_law(
                     };
                     match slot {
                         Some(slot) => {
-                            // `try_insert`: the anchor may have a same-frame despawn already
-                            // queued (the net teardown on a stream drop) — despawn discards
-                            // this pure cache, and the insert must not panic at apply time.
+                            // `try_insert`: a same-frame despawn may already be queued.
                             commands.entity(anchor).try_insert((
                                 BakeState {
                                     word,
                                     lobes,
                                     ref_point,
                                 },
-                                // The emitters' half of the same committed words — a different
-                                // curve, because a particle draw takes the fixed-function lane
-                                // where a mesh batch takes the SH one ([`interior_light_up`]).
+                                // A particle draw takes the fixed-function curve, not the SH one.
                                 ParticleLight(emitter_light),
-                                // …and the ambient half alone, which is the whole term for a
-                                // draw whose vertex format carries no normal ([`NodeAmbient`]).
                                 NodeAmbient(words.0),
                             ));
                             AppliedLaw::Bake(slot)
@@ -1251,24 +1022,20 @@ fn resolve_anchor_law(
             }
         }
     };
-    // Publish the indoor verdict to the node — `entity_shade` picks the intensity target from it
-    // (2.5/0.5 by MCSH outdoors; the day/night 1.0 indoors, Matte and Bake alike).
+    // `entity_shade` picks the intensity target from this: 2.5/0.5 by MCSH outdoors, 1.0 indoors.
     if let Ok(mut node) = nodes.get_mut(anchor) {
         let indoor = law != AppliedLaw::Exterior;
         if node.indoor != indoor {
             node.indoor = indoor;
         }
     }
-    // Slot lifecycle on the anchor, judged by the SEATED state (never a part's memory): entering
-    // Bake inserts the owned slot's component (its on-remove hook frees the slot); leaving
-    // removes it (and the fold cache). Staying rewrites the same slot in place above — no
-    // component cycling.
+    // The slot's lifecycle, judged by the seated state: entering Bake seats it, leaving removes it
+    // with the fold cache, and its component's hook frees the slot.
     match (seated, law) {
         (Some(old), AppliedLaw::Bake(new)) if old == new => {}
         (_, AppliedLaw::Bake(new)) => seat_probe_slot(commands, anchor, new),
         (Some(_), _) => {
-            // Leaving Bake: on a despawned anchor the despawn itself already ran the slot
-            // hook — the removes just must not panic.
+            // On a despawned anchor the hook already ran; the removes just must not panic.
             commands
                 .entity(anchor)
                 .try_remove::<PropProbeSlot>()
@@ -1278,10 +1045,7 @@ fn resolve_anchor_law(
         }
         _ => {}
     }
-    // The room rides back with the law, but only for the indoor laws: the exterior law is the
-    // "no record" arm, and holding a room there would let the fog gate fire on a unit standing on
-    // a porch. (`claimed` is already `None` on both outdoor verdicts; the probe-table-full fallback
-    // to Matte is the one arm that keeps a room the verdict resolved.)
+    // Only an indoor law keeps its room, so the fog gate never fires on a unit on a porch.
     let room = claimed
         .filter(|_| law != AppliedLaw::Exterior)
         .map(|(instance, group)| crate::wmo_portal::WmoRoom {
@@ -1291,17 +1055,14 @@ fn resolve_anchor_law(
     (law, room)
 }
 
-/// Queue the Bake slot swap on `anchor`, tolerant at APPLY time: the anchor may carry a
-/// same-frame despawn queued earlier by the net teardown (a world-stream drop mid-transition),
-/// which applies before this command and used to panic the classifier. Alive → the normal
-/// remove/insert swap (the remove's hook frees the old slot); dead → the fresh slot's component
-/// never lands, so its on-remove hook (the pool's only freer) never runs — release the orphan
-/// directly instead of leaking it in a pool that never resets.
+/// Seats a Bake slot on `anchor` at apply time. A same-frame despawn may have applied first; the
+/// slot's component then never lands and its hook never frees it, so it is released here, since
+/// the pool never resets.
 fn seat_probe_slot(commands: &mut Commands, anchor: Entity, new: u16) {
     commands.queue(
         move |world: &mut World| match world.get_entity_mut(anchor) {
             Ok(mut e) => {
-                // One insert: the slot's `on_replace` hook frees the outgoing slot (2005).
+                // One insert: the slot's `on_replace` hook frees the outgoing slot.
                 e.insert(PropProbeSlot(new));
             }
             Err(_) => world.resource_mut::<PropProbes>().release(new),
@@ -1326,15 +1087,8 @@ mod tests {
         world
     }
 
-    /// The stuck-black repair, on 0734's queue: a part whose last-written record names a slot the
-    /// anchor no longer owns (it sat outside the classifier's write query — a fade window — across
-    /// a slot change) converges to the anchor's standing law even while everything stands
-    /// perfectly still, because re-entering the world enqueues it (here via the `on_add` hook; at
-    /// runtime the fade-latch observer is the same edge). Pre-0734's ancestor bug: the resolver
-    /// trusted the stale part's slot, `update_owned` on the freed slot silently no-opped, and the
-    /// unit rendered the freed slot's zeroed rows — a black silhouette that survived any in-room
-    /// movement until the law itself changed (director-caught: charge across the doorway
-    /// un-blacked it).
+    /// A part recorded on a freed slot would draw its zeroed rows, a black unit; queued, it takes
+    /// the anchor's live slot while nothing moves.
     #[test]
     fn a_stale_part_converges_to_the_anchors_standing_law() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1342,7 +1096,7 @@ mod tests {
         let mut world = classifier_world();
         let coeffs = [Vec4::ZERO; 7];
 
-        // The anchor's live owned slot — and a defunct one its part still remembers.
+        // The anchor's live slot, and a freed one its part still remembers.
         let live = world
             .resource_mut::<PropProbes>()
             .alloc_owned(coeffs)
@@ -1354,8 +1108,7 @@ mod tests {
         world.resource_mut::<PropProbes>().release(stale);
 
         let generation = world.resource::<WmoResidency>().generation;
-        // In a room whose gate is on, so the reauthored tag is the whole Bake payload — slot and
-        // fog flag together, which is what `probe_bits` names.
+        // A room whose gate is on, so the tag is the whole Bake payload `probe_bits` names.
         let instance = placement_with_gate(&mut world, true);
         let anchor = world
             .spawn((
@@ -1365,7 +1118,7 @@ mod tests {
                     law: AppliedLaw::Bake(live),
                     room: Some(crate::wmo_portal::WmoRoom { instance, group: 0 }),
                     fog: true,
-                    last_pos: Vec3::ZERO, // matches the transform: the settled gate sees NO movement
+                    last_pos: Vec3::ZERO, // matches the transform: settled, no movement
                     generation,
                     kind_bake: true,
                     // MONKEY (portal lane fade): a SETTLED anchor — the blend already sits on its
@@ -1411,17 +1164,8 @@ mod tests {
         );
     }
 
-    /// **The light node is the object's, not its mesh's.** An object whose every mesh batch is
-    /// UNLIT registers no [`LitParts`] at all — and before this, the classifier's walk was over
-    /// part lists, so it never visited one. Onyxia's 104 lava traps are exactly that shape
-    /// (`m2batch`: all five batches flags 0x13) with three LIT emitters each, and they stood in a
-    /// WMO interior taking the day/night sun. The reference builds the node from the object's
-    /// TYPEID and fills it every frame regardless of what its batches do (wow-re
-    /// `part-lit-normal-space.md` §6.2), so a lit EMITTER is a consumer of it exactly as a lit
-    /// batch is.
-    ///
-    /// The control is the second anchor: an object with emitters but none of them lit registers
-    /// no edge, is not visited, and costs the walk nothing.
+    /// Onyxia's lava traps have this shape: all five mesh batches unlit (flags 0x13), three lit
+    /// emitters.
     #[test]
     fn an_object_whose_only_lit_consumer_is_an_emitter_is_still_classified() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1454,8 +1198,7 @@ mod tests {
         );
     }
 
-    /// A one-group placement whose interior-fog gate is `on`/`off` this frame — the `[0xca7f00]`
-    /// half of a unit's fog lane, as something the classifier tests can actually set.
+    /// A one-group placement whose interior-fog gate (the `[0xca7f00]` chain) is `gate`.
     fn placement_with_gate(world: &mut World, gate: bool) -> Entity {
         world
             .spawn(WmoPortalInstance {
@@ -1470,9 +1213,7 @@ mod tests {
             .id()
     }
 
-    /// A part spawned onto a SETTLED anchor (the gear-swap-indoors case) takes the standing law
-    /// through the `on_add` hook + drain — no law change, no anchor movement, and still the fresh
-    /// part's material/tag land on the anchor's law the very next classifier run.
+    /// A gear swap indoors: no law change and no movement.
     #[test]
     fn a_fresh_part_on_a_settled_anchor_takes_the_standing_law() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1514,12 +1255,8 @@ mod tests {
         );
     }
 
-    /// **The `[P+0x98]` conjunct** (decision 1792 §4): standing indoors is not enough. A settled
-    /// anchor whose room drops off the camera's interior-fog chain must return to the SCENE fog
-    /// without moving an inch and without changing its light law — the camera walked, not the
-    /// unit. This is B335's own artifact seen from one room further in: at Shadowfang the walls of
-    /// a room across the courtyard already read the scene fog (1787), and before this the mob
-    /// standing in it did not.
+    /// The `[P+0x98]` conjunct: when the camera, not the unit, takes the room off the chain, the
+    /// unit returns to the scene fog with its light law unchanged.
     #[test]
     fn a_settled_anchor_follows_its_rooms_fog_gate_without_moving() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1568,7 +1305,7 @@ mod tests {
             "and the LIGHT law is untouched — the unit is still standing in the same room"
         );
 
-        // …and back, so the gate is a live read rather than a one-way latch.
+        // And back: the gate is a live read, not a latch.
         world
             .get_mut::<WmoPortalInstance>(instance)
             .unwrap()
@@ -1577,15 +1314,8 @@ mod tests {
         assert!(fog_of(&world, part), "the camera comes back into the chain");
     }
 
-    /// Decision 0778: a model's BILLBOARD batch takes the same law as its mesh batches. The card
-    /// spawns as a world ROOT (the facing system owns its transform, 0153) rather than as a child
-    /// of the model, and that is the whole difference — it goes through the same
-    /// [`part_interior_lit`] and names the same anchor, so both converge on the same law. The bug
-    /// this pins: a Stratholme hanging sign baked from its room while its own chain cards, never
-    /// classified at all, stayed on the exterior material and lit from the sky.
-    ///
-    /// Also pins the classify-OUT arm — a WMO-display part builds no interior variant and must not
-    /// join at all, or it would be relit off a material it doesn't have.
+    /// The card is a world root, not the model's child, yet names the same anchor; also the
+    /// classify-out arm, a WMO-display part with no interior variant.
     #[test]
     fn a_models_billboard_card_takes_the_same_law_as_its_mesh_parts() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1659,9 +1389,7 @@ mod tests {
         );
     }
 
-    /// The mixed-kind hole (0734 §3): a bake-capable part joining an anchor whose law was
-    /// resolved from a matte-kind part drops the anchor's record — the next run re-rays with the
-    /// bake kind in reach instead of riding the matte fallback until the anchor happens to move.
+    /// Otherwise the part would ride the matte fallback until the anchor next moved.
     #[test]
     fn a_bake_part_joining_a_matte_resolved_anchor_forces_a_re_resolve() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1703,12 +1431,8 @@ mod tests {
         );
     }
 
-    /// The 0755 regression, at the anchor walk: an anchor whose parts are ALL mid-appear-fade
-    /// still resolves its law. Pre-0755 the classifier's write query excluded fading parts, so
-    /// such an anchor was skipped outright — a freshly-streamed indoor entity had no light law for
-    /// the whole 2 s ramp, appeared under the exterior lane, and swapped laws in a single frame the
-    /// instant the ramp latched (director-reported: "it swaps lighting in an instant once it's
-    /// fully faded in", measured at 2.02 s after the fade armed).
+    /// Otherwise an entity streaming in indoors fades in under exterior light and swaps laws when
+    /// its 2 s ramp latches.
     #[test]
     fn an_anchor_whose_parts_are_all_fading_still_resolves() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1743,11 +1467,6 @@ mod tests {
         );
     }
 
-    /// The other half of 0755: writing a law onto a part whose ramp is live must carry the ramp's
-    /// alpha through the payload rewrite (the classifier used to hardcode opaque, which is exactly
-    /// why it had to be locked out), and must land the part on that law's BLEND twin — so the
-    /// material mode and the tag payload mode name the same law at every instant, mid-ramp
-    /// included.
     #[test]
     fn a_law_written_mid_ramp_keeps_the_alpha_and_takes_the_laws_blend_twin() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1766,7 +1485,7 @@ mod tests {
                     law: AppliedLaw::Bake(slot),
                     room: None,
                     fog: false,
-                    last_pos: Vec3::ZERO, // settled: the walk skips the ray, the drain does the work
+                    last_pos: Vec3::ZERO, // settled: no ray, the drain does the work
                     generation,
                     kind_bake: true,
                     lane: 1.0,
@@ -1792,7 +1511,7 @@ mod tests {
                     Handle::default(),
                 ),
                 ClassifiedBy(anchor),
-                // Spawned on the EXTERIOR blend twin, as a streamed part is before it classifies.
+                // Spawned on the exterior blend twin, as a streamed part is before it classifies.
                 MeshMaterial3d::<WowModelMaterial>(exterior_blend.clone()),
                 MeshTag(mid_ramp),
                 crate::model_fade::FadeMaterials {
@@ -1843,9 +1562,6 @@ mod tests {
         assert_ne!(material, bake);
     }
 
-    /// The fade-latch edge: removing a part's `RenderFade` re-enqueues it for authoring — the
-    /// event that closes every fade-exclusion window (0734 §3; the old settled-path sweep is
-    /// gone, so this observer IS the convergence path).
     #[test]
     fn a_fade_latch_enqueues_the_part_for_reauthoring() {
         let mut world = classifier_world();
@@ -1873,12 +1589,8 @@ mod tests {
         );
     }
 
-    /// **The 0776 fork.** A GameObject anchor probes at its world bounding-box CENTRE, a unit at
-    /// its position — and the centre is where the difference bites: the Stratholme portcullis whose
-    /// spawn z sits 15 cm *under* the corridor slab rays into open air from its origin and into the
-    /// room from its centre (measured: `exterior` at z 125.354, `BAKE g02` at 125.40 and above).
-    /// The scale leg matters too — the centre is model-local, so a scaled placement must carry it
-    /// through the transform rather than adding a raw offset.
+    /// A Stratholme portcullis spawns 15 cm under its corridor slab, so only its centre rays into
+    /// the room. The centre is model-local, so a scaled placement carries it through the transform.
     #[test]
     fn a_gameobject_anchors_at_its_box_centre_and_a_unit_at_its_position() {
         use crate::wmo_portal::LightAttach;
@@ -1904,16 +1616,12 @@ mod tests {
             "a unit still rays from its position, box centre or not"
         );
 
-        // No bounds yet (the model is still streaming): degrade to the origin, never to a wrong
-        // point — the containment lane's other legs still apply.
+        // No bounds yet (the model is still streaming): the origin.
         let (attach, anchor) = attach_anchor(true, None, &at);
         assert_eq!(attach, LightAttach::Containment);
         assert_eq!(anchor, at.translation());
     }
 
-    /// The teardown race, both arms: a slot seated on a live anchor swaps normally; one seated
-    /// on an anchor whose despawn applied first neither panics (the old crash) nor leaks the
-    /// freshly allocated slot (the pool never resets — an orphan would be held forever).
     #[test]
     fn slot_seat_survives_a_despawned_anchor_and_releases_the_orphan() {
         let mut world = World::new();
diff --git a/crates/benilla-world/src/lib.rs b/crates/benilla-world/src/lib.rs
index c3cdc684..02aef8e8 100644
--- a/crates/benilla-world/src/lib.rs
+++ b/crates/benilla-world/src/lib.rs
@@ -1,42 +1,21 @@
-//! **benilla-world** — the world renderer, with no game attached.
-//!
-//! Decision 1160's crate. The line it draws: *this crate can put something into a world and answer
-//! questions about that world; it knows nothing about a session, a wire, an avatar or a UI.* What
-//! enforces the line is not this doc — it is the dependency edge. `benilla-world` does not depend
-//! on `benilla-app`, so a name that crosses back is a compile error rather than a lint, and
-//! `benilla-worldview` links only this crate, so an engine that quietly needs the game stops
-//! booting rather than quietly working.
-//!
-//! Above it: `benilla-app` (the game — session, wire, units, UI) and the two binaries.
-//! Below it: `benilla-assets` (the asset foundation both sides share) and `benilla-formats`.
-//!
-//! **One instrument travels with the engine and three do not**, and the rule that sorts them is
-//! whether `WorldPlugins` registers it. `art_scope` does — within-map art residency is engine
-//! behaviour, not a readout — so it is here. The debug panel, the perf journal and the pipeline
-//! warmer are registered by the game, and every one of them reads the game (units, targets, names,
-//! the UI): they are instruments *above* the stack, and the compiler said so the moment the move
-//! was attempted with them inside. That is the whole value of the crate edge over a naming
-//! convention — the earlier module-name-based wall had them excluded by an assumption, and the
-//! assumption was wrong.
+//! benilla-world: the world renderer, with no game attached. It puts things into a world and
+//! answers questions about it, and knows nothing of a session, the wire, an avatar or a UI. The
+//! dependency edge holds that line: this crate does not depend on `benilla-app`, and
+//! `benilla-worldview` links only this crate. Above it are `benilla-app` and the two binaries;
+//! below it, `benilla-assets` and `benilla-formats`.
 
-/// Re-exported so a shim binary needs no `bevy` dependency of its own — the same courtesy
-/// `benilla-app` extends to the `benilla` launcher.
+/// Re-exported so a shim binary needs no `bevy` dependency of its own.
 pub use bevy::app::AppExit;
 
-/// **Fixtures for dependents' tests.**
-///
-/// `#[cfg(test)]` code is not compiled for a downstream crate, so a fixture the game's tests share
-/// with the engine's has to be ordinary public code. Three of `benilla-app`'s tests build a
-/// particle emitter def — thirty fields of authored defaults — and duplicating that literal three
-/// times is how two of the copies quietly drift from the type.
+/// Test fixtures shared with dependent crates: ordinary public code, since `#[cfg(test)]` code is
+/// not compiled for a downstream crate.
 pub mod testing {
     use benilla_formats::{
         CellRamp, EmitParams, EmitTiming, OverLife, ParamsNow, ParticleBlend, ParticleEmitterDef,
         ParticleShape,
     };
 
-    /// The sampled-parameter side of [`particle_def`], constant-baked so a sim test is
-    /// deterministic.
+    /// The sampled parameters of [`particle_def`], constant so a sim test is deterministic.
     pub fn particle_params_now() -> ParamsNow {
         ParamsNow {
             emission_speed: 1.0,
@@ -51,7 +30,7 @@ pub mod testing {
         }
     }
 
-    /// A minimal emitter def for kernel tests — only the fields the emit kernel reads matter.
+    /// A minimal emitter def for kernel tests; only the fields the emit kernel reads matter.
     pub fn particle_def(shape: ParticleShape) -> ParticleEmitterDef {
         ParticleEmitterDef {
             flags: 0,
@@ -99,10 +78,8 @@ pub mod testing {
         particle_def(ParticleShape::Plane)
     }
 
-    /// A bind-pose [`crate::rig_anim::RigPose`] for tests that resolve consumer anchors
-    /// (decision 1355: anchors spawn on first demand through `RigPose::anchor_for`, so a test
-    /// wearer/mount/caster needs a pose, not a hand-built joint map): one root-parented joint per
-    /// entry, seated at its local translation.
+    /// A bind-pose [`crate::rig_anim::RigPose`] with one root-parented joint per entry, for tests
+    /// that resolve anchors (they spawn on demand through `RigPose::anchor_for`).
     pub fn test_rig_pose(
         root: bevy::ecs::entity::Entity,
         joints: &[bevy::math::Vec3],
@@ -149,8 +126,7 @@ pub mod lighting;
 pub mod liquid;
 pub mod log_ring;
 
-/// macOS `Cmd+Q`, re-pointed at the window close so the gesture goes through an exit the client
-/// can actually observe (decision 1528).
+/// macOS `Cmd+Q`, re-pointed at the window close so the shutdown systems run.
 pub mod mac_quit;
 pub mod map_proj;
 pub mod mat_anim_table;
diff --git a/crates/benilla-world/src/lighting/blob.rs b/crates/benilla-world/src/lighting/blob.rs
index 90458ec2..2cb7bdd9 100644
--- a/crates/benilla-world/src/lighting/blob.rs
+++ b/crates/benilla-world/src/lighting/blob.rs
@@ -1,19 +1,6 @@
-//! Building an **off-world light blob** — the portrait booths' frozen studio light, the body
-//! panes' reference light, the glue scene's authored-rig light.
-//!
-//! The shared world light is built by [`super::global_light`] on the frame path. These three are
-//! not on that path: they are written once (or once per scene swap) into a buffer of their own,
-//! and they all bind against the *same* std430 struct the model shaders declare. That struct's
-//! layout is the thing they must not know.
-//!
-//! [`super::global_light::pack_model_core_rows`] already made half this argument and says so in
-//! its own doc — *"a producer that copies the layout goes stale the day the layout moves — so
-//! producers don't copy it, they call this"* — after the booth rendered black portraits the day
-//! 0354 moved the lit lanes onto rows it never wrote. But it packs only the lit lanes. Every
-//! producer still hand-wrote the spec row, the two fog rows, the intensity dial, the point-table
-//! count, the point rows' interleave, and the byte offset of the probe region. Six pieces of the
-//! same layout, copied three times, one 0354 away from the same failure. This is the rest of that
-//! argument: the producers state values, and nothing outside this module states a row index.
+//! Off-world light blobs: the portrait booths' studio light, the body panes' light and the glue
+//! scene's rig light, each written into a buffer of its own against the model shaders' std430
+//! struct. Producers state values and never a row index, so a layout change cannot strand them.
 
 use bevy::prelude::*;
 use bevy::render::render_resource::{Buffer, BufferDescriptor, BufferUsages};
@@ -25,17 +12,13 @@ use super::global_light::{
 use super::prop_probes::prop_probe_region_offset;
 use super::sh::prop_probe_coeffs;
 
-/// Row 3 `.w` — the terrain shininess convention. Models never read it; every producer writes it
-/// so a terrain lane that ever binds an off-world blob degrades sanely.
+/// Row 3 with the terrain shininess (20) in `.w`; models never read it.
 const SPEC_ROW: [f32; 4] = [0.0, 0.0, 0.0, 20.0];
-/// Fog rows with fog OFF: colour black, `.w = 0` (disabled), and a farclip wall far enough away
-/// to be inert. The off-world default — a booth has no distance to fog.
+/// Fog rows with the fog off and an inert farclip wall.
 const NO_FOG: ([f32; 4], [f32; 4]) = ([0.0; 4], [0.0, 10_000.0, 0.0, 10_000.0]);
 
-/// An off-world light blob under construction: the header rows, an optional point table and an
-/// optional interior-probe fold, sized and written as one.
-///
-/// Start at [`LightBlob::model`] and state only what differs from a plain lit scene.
+/// An off-world light blob: the header rows, an optional point table and an optional interior
+/// probe. Start at [`LightBlob::model`] and state only what differs from a plain lit scene.
 pub struct LightBlob {
     rows: [[f32; 4]; LIGHT_HEADER_ROWS],
     points: Vec<[f32; 4]>,
@@ -43,11 +26,8 @@ pub struct LightBlob {
 }
 
 impl LightBlob {
-    /// A model-lit blob: the core lit lanes folded from `(ambient, diffuse, sun_dir)`, spec at the
-    /// terrain convention, fog off, no point lights, no probe.
-    ///
-    /// `sun_dir` is the light's **propagation** direction (the packer negates it back into a
-    /// to-light vector for the SH fold).
+    /// A plain model-lit blob: fog off, no point lights, no probe. `sun_dir` is the direction the
+    /// light travels.
     pub fn model(ambient: [f32; 3], diffuse: [f32; 3], sun_dir: Vec3) -> Self {
         let mut rows = [[0.0f32; 4]; LIGHT_HEADER_ROWS];
         pack_model_core_rows(&mut rows, ambient, diffuse, sun_dir);
@@ -60,32 +40,23 @@ impl LightBlob {
         }
     }
 
-    /// Fog: colour, far distance, and whether the shader applies it. Near is always 0 and the
-    /// farclip wall stays inert — the reference's off-world fog rows (`CharModelFogInfo` and
-    /// `AccountLogin.xml`) carry a far and nothing else.
+    /// Fog with near 0: the reference's off-world fog (`CharModelFogInfo`, `AccountLogin.xml`)
+    /// states a colour and a far and nothing else.
     pub fn fog(self, rgb: [f32; 3], far: f32, on: bool) -> Self {
         self.fog_span(rgb, 0.0, far, on)
     }
 
-    /// Fog with an explicit **near**, the ramp's low end (`fog_params.x`): the factor is
-    /// `(far − eye_z)/(far − near)` clamped, so near is where the fog first bites and not a
-    /// cosmetic. The one producer that can state one is the `<Model>` widget's `SetFogNear`
-    /// (decision 2027) — every other off-world blob leaves it at 0, which is what
-    /// [`Self::fog`] passes and what `CharModelFogInfo`'s own `SetFogNear(0)` says.
-    /// The farclip wall (`.w`) stays inert at `10_000`: it is a per-pixel *discard*, not a fade,
-    /// and an off-world scene has no clip distance to enforce.
+    /// Fog with an explicit near, where the clamped ramp `(far − eye_z)/(far − near)` starts; only
+    /// the `<Model>` widget's `SetFogNear` states one. The farclip wall stays inert: it discards,
+    /// and an off-world scene has nothing to clip.
     pub fn fog_span(mut self, rgb: [f32; 3], near: f32, far: f32, on: bool) -> Self {
         self.rows[4] = [rgb[0], rgb[1], rgb[2], if on { 1.0 } else { 0.0 }];
         self.rows[5] = [near, far, 0.0, 10_000.0];
         self
     }
 
-    /// The exterior-intensity dial (row 19 `.w`).
-    ///
-    /// **Currently inert: no shader reads it.** It survives because the three producers disagree
-    /// about its value (0.4 in the booths, 1.0 on the glue rig) and that disagreement is recorded
-    /// history, not noise — see the callers' comments. Stating it keeps their bytes identical;
-    /// when a portrait-light pass settles the question, it dies here, once.
+    /// The exterior-intensity dial, row 19 `.w`, which no shader reads; the booths state 0.4 and
+    /// the glue rig 1.0.
     pub fn dial(mut self, v: f32) -> Self {
         self.rows[19] = [0.0, 0.0, 0.0, v];
         self
@@ -111,22 +82,20 @@ impl LightBlob {
         self
     }
 
-    /// Fold an interior SH probe into slot 0 — the rig lane's read side (booth instances carry
-    /// `MeshTag` 0). `lobes` are toward-light unit vectors with their committed colours.
+    /// Folds an interior SH probe into slot 0, which the rig lane reads (booth instances carry
+    /// `MeshTag` 0); `lobes` are toward-light unit vectors with their committed colours.
     pub fn probe(mut self, ambient: [f32; 3], lobes: &[(Vec3, [f32; 3])]) -> Self {
         self.probe = Some(prop_probe_coeffs(ambient, lobes));
         self
     }
 
-    /// The probe's DC term per channel — for logging what was folded, not for the shader.
+    /// The probe's DC term per channel, for logging what was folded.
     pub fn probe_dc(&self) -> [f32; 3] {
         let p = self.probe.unwrap_or_default();
         [p[0].w, p[1].w, p[2].w]
     }
 
-    /// The packed header rows — for tests pinning a producer's values, and for diagnostics. The
-    /// row *indices* are this module's business; a caller that indexes one is asserting about a
-    /// lane, not building a blob.
+    /// The packed header rows, for tests and diagnostics; building a blob never needs an index.
     pub fn header_rows(&self) -> &[[f32; 4]] {
         &self.rows
     }
@@ -136,11 +105,8 @@ impl LightBlob {
         self.points.len() / 2
     }
 
-    /// Create a buffer this blob fits in.
-    ///
-    /// Sized to the **full** layout, never to what was written: `wow_model.wgsl` declares the
-    /// whole struct and wgpu validates the bound size against it at every draw. wgpu zeroes the
-    /// rest, so an unwritten table reads as empty.
+    /// A buffer of the full layout's size, never just what was written: wgpu validates the bound
+    /// size against `wow_model.wgsl`'s whole struct at every draw, and zeroes the unwritten rest.
     pub fn create(&self, device: &RenderDevice, label: &'static str) -> Buffer {
         device.create_buffer(&BufferDescriptor {
             label: Some(label),
@@ -150,8 +116,8 @@ impl LightBlob {
         })
     }
 
-    /// Write the blob into `buffer`. Header rows and the point table are contiguous, so they go in
-    /// one write; the probe region sits past the per-frame prefix and gets its own.
+    /// Writes the header rows and the point table in one write and the probe region, past the
+    /// per-frame prefix, in another.
     pub fn write(&self, queue: &RenderQueue, buffer: &Buffer) {
         let mut head = self.rows.to_vec();
         head.extend_from_slice(&self.points);
@@ -174,8 +140,6 @@ mod tests {
     // LIVE one.
     use super::super::global_light::MAX_POINT_LIGHTS;
 
-    /// The off-world defaults every producer used to hand-write: spec at the terrain convention,
-    /// fog off with an inert farclip wall, an empty point table.
     #[test]
     fn a_plain_model_blob_carries_the_off_world_defaults() {
         let b = LightBlob::model([0.5; 3], [0.8; 3], Vec3::NEG_Y);
@@ -184,15 +148,13 @@ mod tests {
         assert_eq!(b.rows[20][0], 0.0, "no point lights stated");
         assert_eq!(b.point_count(), 0);
         assert!(b.probe.is_none());
-        // The lit lanes are the packer's, not ours — pinned here only so a producer that stops
-        // getting them is loud (0354 rendered black portraits exactly this way).
+        // The lit lanes come from the shared packer; a blob without them renders black portraits.
         assert_eq!(b.rows[0][..3], [0.5; 3], "ambient");
         assert_eq!(b.rows[1][..3], [0.8; 3], "diffuse");
     }
 
-    /// A point light lands as the table's two interleaved rows, colour committed RAW —
-    /// over-gamut preserved (wow-re `trace-forensics-overgamut-point-commit-d3d`) — and the
-    /// header's count follows it. Negative channels are the one thing the commit floors.
+    /// A point light lands as two interleaved rows with its colour raw, over-gamut kept
+    /// (`0x71ca80` → `0x593040`) and only negatives floored, and the header counts it.
     #[test]
     fn a_point_light_commits_raw_and_counts_itself() {
         let b = LightBlob::model([0.0; 3], [0.0; 3], Vec3::NEG_Y).point(
@@ -230,8 +192,7 @@ mod tests {
         assert!(MAX_LIVE_POINT_LIGHTS <= 255, "EXT_SEL_EMPTY is index 255");
     }
 
-    /// Fog states colour and far independently of whether the shader applies it — the glue
-    /// scene's `fog` toggle flips the enable and leaves the race's authored rows standing.
+    /// The glue scene's fog toggle flips only the enable and leaves the race's fog rows standing.
     #[test]
     fn fog_states_its_rows_whether_or_not_it_is_enabled() {
         let on =
@@ -244,8 +205,7 @@ mod tests {
         assert_eq!(off.rows[5], on.rows[5]);
     }
 
-    /// The probe's DC is the fold's, reported for the log — and a blob without one reads zero
-    /// rather than panicking.
+    /// A blob without a probe reports a zero DC rather than panicking.
     #[test]
     fn the_probe_dc_reports_the_fold() {
         let b = LightBlob::model([0.0; 3], [0.0; 3], Vec3::NEG_Y).probe([0.2, 0.3, 0.4], &[]);
diff --git a/crates/benilla-world/src/lighting/daynight.rs b/crates/benilla-world/src/lighting/daynight.rs
index 3fc73314..81d03417 100644
--- a/crates/benilla-world/src/lighting/daynight.rs
+++ b/crates/benilla-world/src/lighting/daynight.rs
@@ -1,22 +1,15 @@
-//! Day/night cycle math — pure functions, no Bevy systems. Owns the **two sun directions** (the
-//! near-fixed lighting/shadow sun and the visible celestial sun that rises/sets), the wrap-around
-//! `DayNight::InterpTable` interpolator, and the dawn/dusk sky-warp strength curve. All ported from
-//! `WoW.exe` (`DayNight::SetDirection`, the sky-bodies builder `FUN_006d3b80`, the warp curve
-//! `0xce9b2c`) and pinned by golden tests. The parent [`super`] consumes these per frame.
+//! Day/night math ported from the 1.12 client's `DayNight` tables: the lighting sun, the visible
+//! sun and moons (the sky-bodies builder `0x6d3b80`), the celestial curves and their interpolator.
 
 use bevy::math::Vec3;
 
 use benilla_assets::coords::wow_to_bevy;
 
-/// Vanilla day/night sun light direction, ported from `DayNight::SetDirection`
-/// (wowdev.wiki Rendering/DayNight). The azimuth (`theta`) is **fixed** at 225° all day and the
-/// elevation (`phi`) only wobbles between ~110° and ~127°, so `dir.z = cos(phi)` stays negative —
-/// the sun is **always above the horizon**. Night is handled by the colors going dark, not by the
-/// sun setting. Returns the **Bevy-space** light *travel* direction (the shader's `-light_sun` is the
-/// to-light vector). `minute` is the game minute-of-day (`0..1440`).
+/// The lighting sun, `DayNight::SetDirection` (wowdev.wiki Rendering/DayNight): azimuth fixed at
+/// 225° and polar angle wobbling between ~110° and ~127°, so the sun never sets and night comes
+/// from the colours. Returns the Bevy-space travel direction; `minute` is the game minute of day.
 pub(super) fn sun_direction(minute: f32) -> Vec3 {
-    // (dayProgression, value) tables straight from the client. theta's table is constant, so we use
-    // the value directly. dayProgression = minute / 1440 (the client uses half-min/2880, identical).
+    // `(dayProgression, φ)`; the client's half-minute / 2880 equals minute / 1440.
     const PHI_TABLE: [(f32, f32); 4] = [
         (0.0, 2.2165682),
         (0.25, 1.9198623),
@@ -27,83 +20,59 @@ pub(super) fn sun_direction(minute: f32) -> Vec3 {
     let dp = minute / 1440.0;
     let phi = interp_daynight(&PHI_TABLE, dp);
     let (sp, cp) = (phi.sin(), phi.cos());
-    // Spherical → cartesian in WoW world coords (Z up), then into Bevy (pure rotation).
     let wow_dir = [sp * THETA.cos(), sp * THETA.sin(), cp];
     wow_to_bevy(wow_dir).normalize()
 }
 
-/// Vanilla **visible celestial sun** direction — the sky disc/glare the player sees — ported from the
-/// sky-bodies builder `FUN_006d3b80` (body 0). This is a **separate system** from the lighting sun
-/// ([`sun_direction`]): the engine computes two suns. The lighting sun barely moves (elevation only
-/// +20°..+37°, so MCSH shadows can be baked static), but the **visible** sun genuinely RISES AND SETS
-/// in elevation along the same fixed compass bearing — its polar angle `φ` sweeps 5° (near-zenith at
-/// solar noon) ↔ 100° (−10°, below the horizon at night), azimuth fixed at 45° to-sun (matching the
-/// lighting sun's bearing, so the bright disc sits in the lit direction). Below the horizon (night)
-/// the disc is parked at −10° and the dark sky takes over. Returns the **Bevy-space to-sun** direction
-/// (camera→sun); `minute` = game minute-of-day (`0..1440`).
-///
-/// (VERIFIED off the binary; the disc/lighting suns measure 25–32° apart in the WoW.8 apitrace. The
-/// once-flagged "builder-local→world rotation toward ~61°" is REFUTED — `0x6d3b80` adds the
-/// spherical offset to the camera directly in world space, no rotation; decision 0485.)
+/// The visible sun, body 0 of `0x6d3b80`: on the lighting sun's 45° bearing it rises and sets,
+/// polar angle 5° at solar noon to 100° (10° below the horizon) at night, offset from the camera in
+/// world space with no rotation. Returns the Bevy-space to-sun direction.
 pub(super) fn celestial_sun_direction(minute: f32) -> Vec3 {
-    // Body-0 elevation LUT (dayProgression, polar φ in rad) — `FUN_006d3b80` table @0xce8d64, count 5
-    // (decoded from the PE immediates: π·0.5555556 = 100°, π·0.0277778 = 5°). 100° = −10° (below the
-    // horizon, night); 5° = +85° (near zenith, solar noon). The azimuth LUT @0xce8d4c is a constant
-    // π·0.25 = 45°. The tightly-spaced keys around 0.5 hold the disc at the zenith across solar noon.
+    // Elevation table `0xce8d64` (dayProgression, polar φ): 100° is 10° below the horizon, 5° near
+    // the zenith, held across noon; the azimuth table `0xce8d4c` is a constant 45°.
     const ELEV_TABLE: [(f32, f32); 5] = [
-        (0.2291667, 1.7453293), // 100°  (near horizon — dawn / sunrise)
-        (0.4965278, 0.0872665), //   5°  (near zenith — rising into noon)
+        (0.2291667, 1.7453293), // 100°  (near the horizon, sunrise)
+        (0.4965278, 0.0872665), //   5°  (near the zenith, rising into noon)
         (0.5, 0.0872665),       //   5°  (solar noon)
-        (0.5034722, 0.0872665), //   5°  (near zenith — falling out of noon)
-        (0.8958333, 1.7453293), // 100°  (near horizon — dusk / sunset)
+        (0.5034722, 0.0872665), //   5°  (near the zenith, falling out of noon)
+        (0.8958333, 1.7453293), // 100°  (near the horizon, sunset)
     ];
-    const THETA: f32 = std::f32::consts::FRAC_PI_4; // 45°, constant — the to-sun azimuth (= the light's)
+    const THETA: f32 = std::f32::consts::FRAC_PI_4; // 45°, the lighting sun's bearing
     let dp = minute / 1440.0;
     let phi = interp_daynight(&ELEV_TABLE, dp);
     let (sp, cp) = (phi.sin(), phi.cos());
-    // to-sun = (cosθ·sinφ, sinθ·sinφ, cosφ) in WoW world (Z up) — used directly (not negated: the
-    // builder offsets the disc *toward* the sun), then into Bevy (pure rotation).
+    // to-sun = (cosθ·sinφ, sinθ·sinφ, cosφ) in WoW space, not negated: the builder offsets the
+    // disc toward the sun.
     let wow_to_sun = [sp * THETA.cos(), sp * THETA.sin(), cp];
     wow_to_bevy(wow_to_sun).normalize()
 }
 
-/// Visible **moon** direction (camera→moon, Bevy space) — the WHITE moon (`moon.blp`). Elevation
-/// table `0xce8d24`: polar φ **35° (overhead at midnight, elev +55°) ↔ 100° (below the horizon by day, elev
-/// −10°)** — up at night, parked below the horizon 04:00→22:00; azimuth a constant **45°** (the sun's
-/// bearing, table `0xce8d0c`). `minute` = game minute-of-day. (VERIFIED off `0x6d3b80`; decision 0485.)
-///
-/// The engine's second disc (`moon02.blp`, azimuth 135°→165°, table `0xce8ccc`) IS drawn every frame —
-/// the old "NULL-registered, never drawn" reading misattributed a glare-slot null in `0x6d4810` — but
-/// its colour field (`[0xce98a4]`) has NO writer in the binary, so it renders vertex-black on a
-/// phase-precessed schedule (`÷1.7` of the day counter) and never reads as a second moon (decision
-/// 0485). Its body lands with the follow-up-pinned tables.
+/// The white moon (`moon.blp`), camera to moon in Bevy space (`0x6d3b80`): elevation table
+/// `0xce8d24` puts it overhead at midnight (φ 35°, +55°) and parks it 10° below the horizon from
+/// 04:00 to 22:00; azimuth a constant 45°, the sun's bearing (table `0xce8d0c`).
 pub(super) fn moon_direction(minute: f32) -> Vec3 {
-    // Elevation LUT (dayProgression, polar φ rad): 35° = π·0.19444, 100° = π·0.55556.
+    // Elevation table (dayProgression, polar φ rad): 35° = π·0.19444, 100° = π·0.55556.
     const ELEV_TABLE: [(f32, f32); 5] = [
-        (0.000000, 0.6108652), // 35°  — midnight (overhead, +55°)
+        (0.000000, 0.6108652), // 35°, midnight (overhead, +55°)
         (0.003472, 0.6108652), // 35°
-        (0.166667, 1.7453293), // 100° — 04:00 (sets below the horizon, −10°)
-        (0.916667, 1.7453293), // 100° — 22:00 (still below the horizon)
-        (0.996528, 0.6108652), // 35°  — risen again before midnight
+        (0.166667, 1.7453293), // 100°, 04:00 (below the horizon, −10°)
+        (0.916667, 1.7453293), // 100°, 22:00 (still below the horizon)
+        (0.996528, 0.6108652), // 35°, risen again before midnight
     ];
     let dp = minute / 1440.0;
     let phi = interp_daynight(&ELEV_TABLE, dp);
-    let theta = std::f32::consts::FRAC_PI_4; // 45°, constant — the white moon shares the sun's bearing
+    let theta = std::f32::consts::FRAC_PI_4; // 45°, the sun's bearing
     let (sp, cp) = (phi.sin(), phi.cos());
-    // to-moon = (cosθ·sinφ, sinθ·sinφ, cosφ) in WoW world (Z up), then into Bevy (pure rotation).
     let wow_to_moon = [sp * theta.cos(), sp * theta.sin(), cp];
     wow_to_bevy(wow_to_moon).normalize()
 }
 
-/// Visible **moon02** direction + size scale (camera→body Bevy direction, size-curve multiplier) —
-/// the engine's third disc (`moon02.blp`), drawn every frame but **vertex-black** (its colour field
-/// `[0xce98a4]` has no writer in the binary), so it never reads as a second moon (decision 0485).
-/// Its tracks run on the **phase-precessed clock**: `phase = fmod(dayCounter + todPhase, 1.7)`
-/// (`0x6d41b9`, 65536 fixed-point; `day_continuous` = that sum, server-synced), which the track
-/// kernel `0x6cf6c0` **clamps to [0,1]** — so for the whole `r∈[1.0,1.7)` leg both tracks park on
-/// their wrap value (az 135°, φ 35° = elevation +55°, frozen high). Azimuth table `0xce8ccc`
-/// sweeps 135°→150°→165°; elevation table `0xce8ce4` is the white moon's curve shape (φ 35°↔100°);
-/// the size samples the shared `0xce8c8c` curve on the same phase, base ×1.0.
+/// `moon02` (`moon02.blp`), the third sky body: its Bevy direction and size multiplier. It is drawn
+/// every frame but vertex-black, since its colour field `[0xce98a4]` has no writer, so it never
+/// shows as a second moon. Its tracks run on `fmod(dayCounter + todPhase, 1.7)` (`0x6d41b9`;
+/// `day_continuous` is that sum), which the track kernel `0x6cf6c0` clamps to [0, 1], so the whole
+/// [1.0, 1.7) leg parks at azimuth 135°, elevation +55°. Azimuth `0xce8ccc` sweeps 135° to 165°,
+/// elevation `0xce8ce4` has the white moon's shape, and the size samples `0xce8c8c` at base ×1.0.
 pub(super) fn moon02_state(day_continuous: f64) -> (Vec3, f32) {
     // (dayFraction, azimuth rad): 135° = π·0.75 [0x8012cc], 150° = π·0.8333 [0x810018],
     // 165° = π·0.9167 [0x811644]; key times 04:00 / 22:00 like the elevation track.
@@ -112,15 +81,15 @@ pub(super) fn moon02_state(day_continuous: f64) -> (Vec3, f32) {
         (0.166667, 2.6179938), // 150°
         (0.916667, 2.8797932), // 165°
     ];
-    // (dayFraction, polar φ rad) — the white-moon curve shape on moon02's own clock.
+    // (dayFraction, polar φ rad): the white moon's shape on moon02's own clock.
     const ELEV_TABLE: [(f32, f32); 5] = [
-        (0.000000, 0.6108652), // 35°  — phase 0 (overhead, +55°)
+        (0.000000, 0.6108652), // 35°, phase 0 (overhead, +55°)
         (0.003472, 0.6108652), // 35°
-        (0.166667, 1.7453293), // 100° — below the horizon (clipped away)
+        (0.166667, 1.7453293), // 100°, below the horizon (clipped away)
         (0.916667, 1.7453293), // 100°
         (0.996528, 0.6108652), // 35°
     ];
-    // The kernel clamp: fmod into [0,1.7), then anything past 1.0 evaluates AT 1.0 (0x6cf6c0).
+    // The kernel clamp: past 1.0 the phase evaluates at 1.0 (`0x6cf6c0`).
     let phase = (day_continuous.rem_euclid(1.7) as f32).min(1.0);
     let theta = interp_daynight(&AZ_TABLE, phase);
     let phi = interp_daynight(&ELEV_TABLE, phase);
@@ -132,165 +101,129 @@ pub(super) fn moon02_state(day_continuous: f64) -> (Vec3, f32) {
     )
 }
 
-/// Dawn/dusk sky-dome warp strength curve `S(dayfrac)` — the day/night intensity that gates the
-/// azimuthal sky warp (`FUN_006d0f50`, table `0xce9b2c`, decoded off writer `FUN_006ce120`; VERIFIED).
-/// Two triangular spikes — sunrise (~06:29) and sunset (~21:29) — and **0 everywhere else** (all of
-/// midday AND deep night). Multiplied by the per-zone `highlightSky` flag to get `WowLighting.sky_warp`.
+/// The dawn/dusk sky-warp strength curve (table `0xce9b2c`, written by `0x6ce120`, gating the warp
+/// `0x6d0f50`): spikes at about 06:29 and 21:29, 0 everywhere else.
 const SKY_WARP_CURVE: [(f32, f32); 6] = [
     (0.1250, 0.0), // 03:00
-    (0.2708, 1.0), // 06:29 — dawn spike
+    (0.2708, 1.0), // 06:29, dawn spike
     (0.2917, 0.0), // 07:00
     (0.8542, 0.0), // 20:30
-    (0.8958, 1.0), // 21:29 — dusk spike
+    (0.8958, 1.0), // 21:29, dusk spike
     (0.9993, 0.0), // 23:59
 ];
 
-/// Dawn/dusk sky-dome warp strength `S` = `dawn_dusk_curve(dayfrac) × highlight_sky` (raw — the debug
-/// toggle gating lives in the caller). 0 across all of midday/night and in `highlightSky=0` zones, so
-/// the sky warp is identity except at ~06:30/21:30 in flagged zones. See [`SKY_WARP_CURVE`] + `sky.wgsl`.
+/// The sky warp strength `S = curve(dayfrac) × highlight_sky`.
 pub(super) fn sky_warp(minute: f32, highlight_sky: f32) -> f32 {
     interp_daynight(&SKY_WARP_CURVE, minute / 1440.0) * highlight_sky
 }
 
-/// Sun-disc **size-multiplier** curve — vanilla size table `0xce8cac` (VERIFIED off `WoW.exe`),
-/// sampled by the same wrap-around interpolator as the other DayNight tables.
-/// The disc grows to **2× at the dawn/dusk horizon** (06:00 / 21:00) and is **1× across midday** — the
-/// baked "huge sun at the horizon". The sun's per-body base multiplier is ×1.0, so this curve *is* its
-/// disc scale. (The night-side 2× plateau is never seen — the sun is parked −10° below the horizon then.)
+/// The sun disc's size multiplier, table `0xce8cac` at base ×1.0: 2× at the horizon (06:00, 21:00)
+/// and 1× across midday; its night-side 2× is never seen, the sun being below the horizon.
 const SUN_SIZE_CURVE: [(f32, f32); 4] = [
-    (0.25000, 2.0), // 06:00 — sunrise at the horizon (largest)
-    (0.28125, 1.0), // 06:45 — risen → the midday plateau
-    (0.84375, 1.0), // 20:15 — still small
-    (0.87500, 2.0), // 21:00 — sunset at the horizon (largest)
+    (0.25000, 2.0), // 06:00, sunrise (largest)
+    (0.28125, 1.0), // 06:45, the midday plateau
+    (0.84375, 1.0), // 20:15, still small
+    (0.87500, 2.0), // 21:00, sunset (largest)
 ];
 
-/// The sun disc's size multiplier at `minute` (game minute-of-day): `1.0` midday → `2.0` at the dawn/dusk
-/// horizon. `sun.rs` multiplies the disc's base angular size (`sun_size`) by this. See [`SUN_SIZE_CURVE`].
 pub(super) fn sun_disc_scale(minute: f32) -> f32 {
     interp_daynight(&SUN_SIZE_CURVE, minute / 1440.0)
 }
 
-/// Moon-disc **size-multiplier** curve — shared size table `0xce8c8c` for BOTH moon discs (VERIFIED,
-/// decision 0485). `1.5×` at moonrise/moonset (the horizon, ~22:00 / ~04:00) shrinking to `1.0×` overhead
-/// (~midnight) — the same horizon-enlargement as the sun. Multiply by the per-disc base (white ×1.75,
-/// moon02 ×1.0); moon02's phase precession shifts *when* it samples this, not the range.
+/// The moon discs' size multiplier, table `0xce8c8c`, shared by both: 1.5× at moonrise and moonset
+/// (about 22:00 and 04:00), 1× overhead, times the disc's base (white ×1.75, moon02 ×1.0).
 const MOON_SIZE_CURVE: [(f32, f32); 4] = [
-    (0.041667, 1.0), // 01:00 — overhead (smallest)
-    (0.166667, 1.5), // 04:00 — moonset horizon
-    (0.916667, 1.5), // 22:00 — moonrise horizon
-    (0.999306, 1.0), // 23:59 — wraps toward 01:00 (overhead)
+    (0.041667, 1.0), // 01:00, overhead (smallest)
+    (0.166667, 1.5), // 04:00, moonset
+    (0.916667, 1.5), // 22:00, moonrise
+    (0.999306, 1.0), // 23:59, wrapping toward 01:00
 ];
 
-/// The moon disc's size multiplier at `minute` — `1.0` overhead (~midnight) → `1.5` at moonrise/set. Both
-/// moon discs share the curve; multiply by the per-disc base (white ×1.75, moon02 ×1.0). See [`MOON_SIZE_CURVE`].
+/// The moon disc's size multiplier at `minute`, before the disc's base.
 pub(super) fn moon_disc_scale(minute: f32) -> f32 {
     interp_daynight(&MOON_SIZE_CURVE, minute / 1440.0)
 }
 
-/// Star-field **global-alpha** curve — vanilla star curve `0xce9a98` (VERIFIED off `WoW.exe`):
-/// the `Stars.m2` model-global alpha (`[ce96d8+0xb]/255`) the reference fades on
-/// this exact schedule. Keyframes (game-day fraction → 0..1): `00:00→1.0, 03:00→1.0, 04:30→0.0, 22:30→0.0`.
-/// The wrap-around interpolator gives the rest: stars **fade IN 22:30→00:00**, full all deep night, **fade
-/// OUT 03:00→04:30**, and **0 all day** (the reference skips the draw when the byte < 2). The day/night
-/// colours already darken the sky; this is the separate star layer on top.
+/// The star field's alpha curve `0xce9a98`, the `Stars.m2` model-global alpha
+/// (`[ce96d8+0xb]/255`): fades in from 22:30 to 00:00 and out from 03:00 to 04:30, 0 all day (the
+/// reference skips the draw below byte 2).
 const STAR_CURVE: [(f32, f32); 4] = [
-    (0.0, 1.0),    // 00:00 — full (deep night)
-    (0.125, 1.0),  // 03:00 — still full
-    (0.1875, 0.0), // 04:30 — fully out
-    (0.9375, 0.0), // 22:30 — start fading in (wrap → 00:00)
+    (0.0, 1.0),    // 00:00, full
+    (0.125, 1.0),  // 03:00, still full
+    (0.1875, 0.0), // 04:30, out
+    (0.9375, 0.0), // 22:30, fading in toward 00:00
 ];
 
-/// Star-field global alpha at `minute` (game minute-of-day): `1.0` deep night → `0.0` all day, fading in
-/// 22:30→00:00 and out 03:00→04:30. `sun.rs` multiplies the star dome's base-colour alpha by this (the
-/// model-global fade the reference applies). See [`STAR_CURVE`].
 pub(super) fn star_alpha(minute: f32) -> f32 {
     interp_daynight(&STAR_CURVE, minute / 1440.0)
 }
 
-/// Sun lens-flare **day/night envelope** curve — the per-body inline 4-key dnCurve table at
-/// `[glare+0x70]` (sun `0xce9818`, built by `0x6d1e30`; VERIFIED, wow-re celestial-bodies Addendum
-/// #5, decision 0508). A factor of the flare-intensity slew target in `sun::follow`: the sun's
-/// flare exists only by day — 0 until 06:30, full 07:30→19:30, gone by 21:00. Dusk (21:00→22:45)
-/// and dawn (03:15→06:30) are flare dead-bands for BOTH bodies.
+/// The sun lens-flare day envelope, the per-body dnCurve at `[glare+0x70]` (sun `0xce9818`, built
+/// by `0x6d1e30`): off until 06:30, full from 07:30 to 19:30, off by 21:00.
 const SUN_FLARE_DN_CURVE: [(f32, f32); 4] = [
-    (0.2708333, 0.0), // 06:30 — still off
-    (0.3125, 1.0),    // 07:30 — full day flare
-    (0.8125, 1.0),    // 19:30 — still full
-    (0.875, 0.0),     // 21:00 — off before the sun sets
+    (0.2708333, 0.0), // 06:30, still off
+    (0.3125, 1.0),    // 07:30, full
+    (0.8125, 1.0),    // 19:30, still full
+    (0.875, 0.0),     // 21:00, off before sunset
 ];
 
-/// The sun's flare dnCurve at `minute` (game minute-of-day). See [`SUN_FLARE_DN_CURVE`].
 pub(super) fn sun_flare_dn(minute: f32) -> f32 {
     interp_daynight(&SUN_FLARE_DN_CURVE, minute / 1440.0)
 }
 
-/// Moon lens-flare **night envelope** curve (moon dnCurve table `0xce9768`, built by `0x6d1f30`;
-/// VERIFIED, Addendum #5, decision 0508): flat **zero from 03:15 to 22:45** — the whole day *and*
-/// early evening — ramping in 22:45→24:00 (23:00 ≈ 0.20, 23:30 ≈ 0.61), full 00:00→02:00, out by
-/// 03:15. A 22:30 moonrise has NO halo in the reference; it first lights at 22:45 and peaks near
-/// midnight. This was the missing gate behind the director's "moon halo far too big" report.
+/// The moon lens-flare night envelope (`0xce9768`, built by `0x6d1f30`): zero from 03:15 to
+/// 22:45, ramping in to full at midnight and full to 02:00, so a 22:30 moonrise has no halo.
 const MOON_FLARE_DN_CURVE: [(f32, f32); 4] = [
-    (0.0833333, 1.0), // 02:00 — still full
-    (0.1354167, 0.0), // 03:15 — out
-    (0.9479167, 0.0), // 22:45 — first light
-    (0.999306, 1.0),  // ~23:59 — full (the wrap to 02:00 holds 1.0 across midnight)
+    (0.0833333, 1.0), // 02:00, still full
+    (0.1354167, 0.0), // 03:15, out
+    (0.9479167, 0.0), // 22:45, first light
+    (0.999306, 1.0),  // 23:59, full; the wrap to 02:00 holds it across midnight
 ];
 
-/// The moon's flare dnCurve at `minute` (game minute-of-day). See [`MOON_FLARE_DN_CURVE`].
 pub(super) fn moon_flare_dn(minute: f32) -> f32 {
     interp_daynight(&MOON_FLARE_DN_CURVE, minute / 1440.0)
 }
 
-/// The **SIDN night fraction** curve — the runtime-built 4-key track at `0xce9a34` (keys + the
-/// constants `0x811518`/`0x8115bc`, builder `0x6ce670`; VERIFIED, wow-re `wmo-interior-night-light`
-/// §3). Sampled per frame into `DNState+0x1ac`; the WMO material updater `0x6b4090` multiplies every
-/// SIDN material's authored emissive colour by it — windows glow **1.0 all night (21:30→06:00)**,
-/// ramp OFF over 06:00→07:00, stay **0 through the day**, and ramp ON over 20:30→21:30.
+/// The SIDN night fraction track `0xce9a34` (constants `0x811518`/`0x8115bc`, built by
+/// `0x6ce670`), sampled into `DNState+0x1ac`; the WMO material updater `0x6b4090` scales every
+/// SIDN material's emissive by it: 1 overnight, off from 06:00 to 07:00, on from 20:30 to 21:30.
 const SIDN_NIGHT_CURVE: [(f32, f32); 4] = [
-    (0.25, 1.0),      // 06:00 — still full night glow
-    (0.2916667, 0.0), // 07:00 — faded out for the day
-    (0.8541667, 0.0), // 20:30 — starts ramping in
-    (0.8958333, 1.0), // 21:30 — full glow (wrap → 06:00 holds 1.0)
+    (0.25, 1.0),      // 06:00, still full
+    (0.2916667, 0.0), // 07:00, off for the day
+    (0.8541667, 0.0), // 20:30, ramping in
+    (0.8958333, 1.0), // 21:30, full; the wrap to 06:00 holds it
 ];
 
-/// The SIDN self-illum night fraction at `minute` (game minute-of-day): `1.0` overnight, `0.0` all
-/// day, linear ramps 20:30→21:30 and 06:00→07:00. Multiplied into every WMO SIDN material's authored
-/// emissive colour (`wow_model.wgsl`, via the shared light buffer). See [`SIDN_NIGHT_CURVE`].
 pub(super) fn sidn_night_fraction(minute: f32) -> f32 {
     interp_daynight(&SIDN_NIGHT_CURVE, minute / 1440.0)
 }
 
-/// The **cloud sun-glow envelope** — the INTERNAL static 8-key track at `0xce9ab8` (built once by
-/// `0x6ce390` from constants; NOT a Light.dbc band), evaluated by the shared track kernel at the
-/// day fraction. ≈1.0 across the full day, notching to 0 at the twilight boundaries. The key
-/// array is stored NON-MONOTONIC (keys 6/7 sit before key 5 in time) — byte-verified as-is; the
-/// array-order scan makes them structurally unreachable and wraps `t > 0.9236` back to 1.0. We
-/// keep the keys in the stored order so [`interp_daynight`] (the same kernel) reproduces exactly
-/// that behavior (wow-re `cloud-coverage-pipeline.md` Addendum A §2 — the *intent* is flagged
-/// INFERRED there; the mechanism is verified).
+/// The cloud sun-glow envelope, the static 8-key track `0xce9ab8` (built by `0x6ce390`, not a
+/// `Light.dbc` band): about 1 all day with twilight notches. Its keys are stored non-monotonic
+/// (6 and 7 fall before 5 in time), and the kernel's array-order scan (`0x6cf6c0`) never reaches
+/// them and wraps `t > 0.9236` back to 1, so the stored order is kept for [`interp_daynight`].
 pub(super) fn cloud_glow_track(minute: f32) -> f32 {
     const CLOUD_GLOW_CURVE: [(f32, f32); 8] = [
-        (0.16667, 1.0), // 04:00 — full
-        (0.19444, 0.0), // 04:40 — dawn notch
+        (0.16667, 1.0), // 04:00, full
+        (0.19444, 0.0), // 04:40, dawn notch
         (0.20139, 0.0), // 04:50
-        (0.22917, 1.0), // 05:30 — full through the day
+        (0.22917, 1.0), // 05:30, full through the day
         (0.89583, 1.0), // 21:30
-        (0.92361, 0.0), // 22:10 — dusk notch
-        (0.88889, 0.0), // (structurally unreachable — stored order kept, see above)
-        (0.91667, 1.0), // (ditto; the seam wraps >22:10 back toward 1.0)
+        (0.92361, 0.0), // 22:10, dusk notch
+        (0.88889, 0.0), // unreachable, kept in the stored order
+        (0.91667, 1.0), // unreachable: past 22:10 the seam wraps back to 1
     ];
     interp_daynight(&CLOUD_GLOW_CURVE, minute / 1440.0)
 }
 
-/// The cloud glow's **body pick** (`0x6cfb00` setup): the SUN drives the glow while the day
-/// fraction sits in `[0.2013889, 0.9236111]` (≈ 04:50–22:10), the MOON otherwise.
+/// The cloud glow's body (`0x6cfb00`): the sun from about 04:50 to 22:10, else the moon.
 pub(super) fn cloud_glow_is_sun(minute: f32) -> bool {
     let dp = minute / 1440.0;
     (0.201_388_9..=0.923_611_1).contains(&dp)
 }
 
-/// Vanilla `DayNight::InterpTable`: wrap-around linear interpolation of a `(dayProgression, value)`
-/// table over `dp ∈ [0,1)`. (The client's two return branches both reduce to a plain lerp.)
+/// The reference's `DayNight::InterpTable`: wrap-around linear interpolation of a
+/// `(dayProgression, value)` table over `dp ∈ [0, 1)`; both of its return branches are this lerp.
 fn interp_daynight(table: &[(f32, f32)], dp: f32) -> f32 {
     let n = table.len();
     let mut a = 0;
@@ -318,28 +251,25 @@ fn interp_daynight(table: &[(f32, f32)], dp: f32) -> f32 {
 mod tests {
     use super::*;
 
-    /// The cloud glow envelope (Addendum A §2): full across the day, zero at the twilight
-    /// notches, and the verified seam wrap past 22:10 back to 1.0 (the non-monotonic stored
-    /// keys are unreachable under the array-order scan).
+    /// The cloud glow envelope under `0x6cf6c0`'s scan: full by day, zero at the twilight notches,
+    /// and back to 1 past 22:10.
     #[test]
     fn cloud_glow_track_matches_the_client_envelope() {
         assert_eq!(cloud_glow_track(720.0), 1.0); // noon
         assert_eq!(cloud_glow_track(0.20139 * 1440.0), 0.0); // the 04:50 notch
         let notch = cloud_glow_track(0.9236 * 1440.0); // approaching the 22:10 notch from below
         assert!(notch < 0.01, "dusk notch {notch}");
-        // The cliff: one step past the notch the array-order scan runs off the non-monotonic
-        // tail and the seam wrap snaps the envelope back to 1.0 (the verified mechanism).
+        // One step past the notch the scan runs off the non-monotonic tail and the seam wraps
+        // the envelope back to 1.
         assert_eq!(cloud_glow_track(0.9237 * 1440.0), 1.0);
         assert_eq!(cloud_glow_track(0.95 * 1440.0), 1.0); // deep night stays wrapped
         let mid_dusk = cloud_glow_track(0.9097 * 1440.0); // halfway 21:30→22:10
         assert!((mid_dusk - 0.5).abs() < 0.01, "mid-dusk {mid_dusk}");
-        // The body pick: sun by day, moon outside the window.
         assert!(cloud_glow_is_sun(720.0));
         assert!(!cloud_glow_is_sun(0.95 * 1440.0));
     }
 
-    // Vanilla DayNight phi keyframes (wowdev.wiki Rendering/DayNight) — pinned so a refactor can't
-    // silently change the sun's elevation curve.
+    // The `DayNight::SetDirection` φ keyframes.
     #[test]
     fn daynight_phi_matches_client_keyframes() {
         const PHI: [(f32, f32); 4] = [
@@ -351,13 +281,10 @@ mod tests {
         assert!((interp_daynight(&PHI, 0.0) - 2.2165682).abs() < 1e-5); // midnight
         assert!((interp_daynight(&PHI, 0.25) - 1.9198623).abs() < 1e-5); // 06:00
         assert!((interp_daynight(&PHI, 0.5) - 2.2165682).abs() < 1e-5); // noon
-                                                                        // Halfway between keyframes is the midpoint value.
-        assert!((interp_daynight(&PHI, 0.125) - 2.0682153).abs() < 1e-4);
+        assert!((interp_daynight(&PHI, 0.125) - 2.0682153).abs() < 1e-4); // halfway: the midpoint
     }
 
-    // The SIDN night-glow schedule (wow-re `wmo-interior-night-light` §3, track `0xce9a34`):
-    // 1.0 overnight, 0.0 all day, linear ramps 20:30→21:30 and 06:00→07:00 — pinned so a curve
-    // edit can't silently shift when windows light up.
+    // The SIDN track `0xce9a34`: 1 overnight, 0 by day, ramps 20:30 to 21:30 and 06:00 to 07:00.
     #[test]
     fn sidn_night_fraction_matches_the_client_track() {
         let f = |h: f32, m: f32| sidn_night_fraction(h * 60.0 + m);
@@ -374,8 +301,7 @@ mod tests {
 
     #[test]
     fn sun_is_always_above_the_horizon() {
-        // Bevy +Y is up; the sun's *travel* direction must point down (y < 0) at every time of day,
-        // i.e. the sun never sets (night comes from the colors, not the geometry).
+        // Bevy +Y is up, so the travel direction points down at every minute.
         for minute in (0..1440).step_by(30) {
             assert!(
                 sun_direction(minute as f32).y < 0.0,
@@ -386,7 +312,6 @@ mod tests {
 
     #[test]
     fn sun_azimuth_is_fixed_all_day() {
-        // theta is constant in vanilla, so the horizontal heading must not change over the day.
         let heading = |m: f32| {
             let d = sun_direction(m);
             d.x.atan2(d.z)
@@ -407,22 +332,18 @@ mod tests {
 
     #[test]
     fn celestial_sun_rises_and_sets_in_elevation() {
-        // Unlike the lighting sun, the VISIBLE sun sweeps a big elevation arc (`FUN_006d3b80`):
-        // below the horizon at night, near zenith at noon. Keyframes from agent A's binary tables.
         let noon = elev_deg(celestial_sun_direction(720.0)); // φ 5°  → +85°
         let dawn = elev_deg(celestial_sun_direction(0.0)); // φ 100° → −10°
         let morning = elev_deg(celestial_sun_direction(480.0)); // 08:00, φ 63° → +27°
         assert!((noon - 85.0).abs() < 1.0, "solar noon ~+85°, got {noon}");
         assert!((dawn + 10.0).abs() < 1.0, "midnight ~−10°, got {dawn}");
         assert!((morning - 27.0).abs() < 2.0, "08:00 ~+27°, got {morning}");
-        // It genuinely climbs from morning to noon (the lighting sun does NOT — it only bobs ±8°).
         assert!(noon > morning + 30.0, "should climb steeply toward noon");
         assert!(noon > dawn + 80.0, "midnight far below noon");
     }
 
     #[test]
     fn celestial_sun_dips_below_horizon_at_night() {
-        // Below the horizon (y < 0) before dawn and after dusk; above it through the day.
         assert!(
             celestial_sun_direction(0.0).y < 0.0,
             "midnight below horizon"
@@ -436,8 +357,6 @@ mod tests {
 
     #[test]
     fn celestial_sun_shares_the_lighting_bearing() {
-        // Both suns sit at to-sun azimuth 45° — the disc tracks the lit direction, differing only in
-        // elevation. Compare horizontal headings (atan2(x,z)) of celestial to-sun vs lighting to-sun.
         let heading = |d: Vec3| d.x.atan2(d.z);
         let light_to_sun = -sun_direction(600.0); // lighting to-sun
         let celes = celestial_sun_direction(600.0);
@@ -446,7 +365,7 @@ mod tests {
             dh < 1e-3,
             "celestial & lighting suns share a bearing, Δ={dh}"
         );
-        // And the celestial sun is HIGHER than the lighting sun at 10:00 (56° vs 31°).
+        // At 10:00 the visible sun rides higher, 56° against 31°.
         assert!(
             elev_deg(celes) > elev_deg(light_to_sun) + 15.0,
             "visible sun should ride higher than the lighting sun"
@@ -456,21 +375,18 @@ mod tests {
     #[test]
     fn sky_warp_curve_spikes_at_dawn_dusk_and_is_zero_midday() {
         let s = |min: u32| interp_daynight(&SKY_WARP_CURVE, min as f32 / 1440.0);
-        // 0 across all of midday AND deep night — the warp must not touch the daytime/night sky.
         assert_eq!(s(720), 0.0, "noon"); // 12:00
-        assert_eq!(s(0), 0.0, "midnight"); // 00:00 (wrap between two 0.0 keyframes)
+        assert_eq!(s(0), 0.0, "midnight"); // 00:00, wrapping between two 0 keys
         assert_eq!(s(1080), 0.0, "18:00");
-        // Triangular spikes to ~1.0 at sunrise (06:30) and sunset (21:30).
         assert!(s(390) > 0.99, "dawn spike ~1.0, got {}", s(390));
         assert!(s(1290) > 0.99, "dusk spike ~1.0, got {}", s(1290));
-        // Partway up the dawn ramp (06:00, between the 03:00=0 and 06:30=1 keyframes) is in (0,1).
         let mid = s(360);
         assert!(mid > 0.0 && mid < 1.0, "dawn ramp partial, got {mid}");
     }
 
     #[test]
     fn sun_disc_doubles_at_the_horizon_and_is_unit_at_midday() {
-        // VERIFIED size table 0xce8cac: 2× at sunrise (06:00) / sunset (21:00), 1× across midday.
+        // Size table `0xce8cac`.
         assert!(
             (sun_disc_scale((6 * 60) as f32) - 2.0).abs() < 1e-3,
             "06:00 sunrise = 2×"
@@ -487,14 +403,13 @@ mod tests {
             (sun_disc_scale((9 * 60) as f32) - 1.0).abs() < 1e-3,
             "09:00 plateau = 1×"
         );
-        // Mid-ramp just after sunrise (06:20, between 06:00→2.0 and 06:45→1.0) is in (1,2).
         let r = sun_disc_scale((6 * 60 + 20) as f32);
         assert!(r > 1.0 && r < 2.0, "post-sunrise shrink ramp, got {r}");
     }
 
     #[test]
     fn stars_fade_in_at_night_and_are_off_by_day() {
-        // VERIFIED star curve 0xce9a98: full deep night, off all day, fade in 22:30→00:00 / out 03:00→04:30.
+        // Star curve `0xce9a98`.
         assert!((star_alpha((0) as f32) - 1.0).abs() < 1e-3, "00:00 full"); // midnight
         assert!(
             (star_alpha((2 * 60) as f32) - 1.0).abs() < 1e-3,
@@ -502,19 +417,15 @@ mod tests {
         );
         assert_eq!(star_alpha((12 * 60) as f32), 0.0, "noon off"); // 12:00
         assert_eq!(star_alpha((18 * 60) as f32), 0.0, "18:00 off");
-        // Fading in across 22:30→00:00: 23:15 is partway up (0,1).
         let dusk = star_alpha((23 * 60 + 15) as f32);
         assert!(dusk > 0.0 && dusk < 1.0, "fading in at 23:15, got {dusk}");
-        // Fading out across 03:00→04:30: 03:45 is partway down (0,1).
         let dawn = star_alpha((3 * 60 + 45) as f32);
         assert!(dawn > 0.0 && dawn < 1.0, "fading out at 03:45, got {dawn}");
     }
 
     #[test]
     fn flare_dn_curves_gate_the_halos_by_time_of_day() {
-        // VERIFIED per-body dnCurve tables (sun 0xce9818 / moon 0xce9768, Addendum #5, 0508). The
-        // load-bearing value: a 22:30 moonrise has NO halo — the moon's curve is flat zero from
-        // 03:15 all the way to 22:45, then ramps in toward midnight (23:00 ≈ 0.20, 23:30 ≈ 0.61).
+        // The dnCurve tables, sun `0xce9818` and moon `0xce9768`: a 22:30 moonrise has no halo.
         assert_eq!(moon_flare_dn((22 * 60 + 30) as f32), 0.0, "22:30 no halo");
         assert_eq!(moon_flare_dn((12 * 60) as f32), 0.0, "noon no halo");
         let m2300 = moon_flare_dn((23 * 60) as f32);
@@ -526,7 +437,6 @@ mod tests {
             "01:00 full (the wrap across midnight holds 1.0)"
         );
         assert!(moon_flare_dn((3 * 60 + 15) as f32) < 1e-3, "03:15 out");
-        // The sun's is the day mirror: full across midday, gone by 21:00, off all night.
         assert!((sun_flare_dn((12 * 60) as f32) - 1.0).abs() < 1e-3, "noon");
         assert_eq!(sun_flare_dn((21 * 60) as f32), 0.0, "21:00 off");
         assert_eq!(sun_flare_dn((23 * 60) as f32), 0.0, "night off");
@@ -536,25 +446,23 @@ mod tests {
 
     #[test]
     fn moon_disc_enlarges_at_moonrise_and_set() {
-        // VERIFIED shared size table 0xce8c8c: 1.5× at the horizon (~22:00 rise / ~04:00 set), 1× overhead.
+        // The shared size table `0xce8c8c`.
         let m = |min: u32| interp_daynight(&MOON_SIZE_CURVE, min as f32 / 1440.0);
         assert!((m(22 * 60) - 1.5).abs() < 1e-3, "22:00 moonrise = 1.5×");
         assert!((m(4 * 60) - 1.5).abs() < 1e-3, "04:00 moonset = 1.5×");
         assert!((m(60) - 1.0).abs() < 1e-3, "01:00 overhead = 1×");
     }
 
-    // moon02's phase-precessed clock (0x6d41b9 fmod ÷1.7 + the 0x6cf6c0 kernel clamp; decision
-    // 0485): a normal-leg "day" behaves like the white moon on its own bearing, and the whole
-    // r∈[1.0,1.7) leg parks on the clamp value (az 135°, elevation +55°).
+    // moon02's precessed clock (`0x6d41b9`'s fmod by 1.7, then `0x6cf6c0`'s clamp): the normal
+    // leg follows the white moon's shape on its own bearing, and [1.0, 1.7) parks at the clamp.
     #[test]
     fn moon02_precesses_and_parks_on_the_clamp_leg() {
-        // Phase 0 (day 0 midnight): up (+55°), azimuth at the 135° key.
+        // Phase 0, day 0 midnight: up at +55°, azimuth on the 135° key.
         let (dir, scale) = moon02_state(0.0);
         assert!(dir.y > 0.5, "phase 0: up");
         assert!((scale - 1.0).abs() < 1e-3, "phase 0: overhead size 1×");
-        // Phase 0.5 (day 0 noon): below the horizon (clipped away by the shader).
         assert!(moon02_state(0.5).0.y < 0.0, "phase 0.5: below horizon");
-        // The clamp leg: any remainder in [1.0, 1.7) evaluates AT 1.0 — parked up, identical state.
+        // Any remainder in [1.0, 1.7) evaluates at 1.0: parked up, one state.
         let (park_a, sa) = moon02_state(1.05);
         let (park_b, sb) = moon02_state(1.65);
         assert!(park_a.y > 0.5, "clamp leg: parked above the horizon");
@@ -562,15 +470,14 @@ mod tests {
             (park_a - park_b).length() < 1e-6 && (sa - sb).abs() < 1e-6,
             "clamp leg: frozen"
         );
-        // Precession: the same time-of-day on consecutive days lands on different phases —
-        // day 10 midnight (phase fmod(10,1.7)≈1.5 → parked up) vs day 11 (fmod(11,1.7)≈0.8 → the
-        // below-horizon stretch of the normal leg).
+        // The same time on consecutive days lands on different phases: day 10 midnight is
+        // fmod(10, 1.7) ≈ 1.5 (parked up), day 11 is ≈ 0.8 (below the horizon).
         assert!(moon02_state(10.0).0.y > 0.5, "day 10 midnight: parked leg");
         assert!(
             moon02_state(11.0).0.y < 0.0,
             "day 11 midnight: below horizon"
         );
-        // And moon02's bearing is its own (az 135–165°), never the white moon's 45°.
+        // moon02's bearing is its own (135° to 165°), never the white moon's 45°.
         let heading = |d: Vec3| d.x.atan2(d.z).to_degrees();
         let h02 = heading(moon02_state(0.0).0);
         let hw = heading(moon_direction(0.0));
@@ -582,8 +489,7 @@ mod tests {
 
     #[test]
     fn moon_rises_at_night_sets_by_day() {
-        // The single (white) moon: overhead at midnight (elev +55° → Bevy y>0), below the horizon at noon
-        // (−10° → y<0).
+        // The white moon: +55° at midnight, −10° at noon.
         assert!(moon_direction(0.0).y > 0.5, "moon up at midnight");
         assert!(
             moon_direction((12 * 60) as f32).y < 0.0,
diff --git a/crates/benilla-world/src/lighting/global_light.rs b/crates/benilla-world/src/lighting/global_light.rs
index b477d078..b3373de0 100644
--- a/crates/benilla-world/src/lighting/global_light.rs
+++ b/crates/benilla-world/src/lighting/global_light.rs
@@ -1,18 +1,8 @@
-//! The **one shared global light** — the faithful replacement for the per-material light copy.
+//! The one shared global light, as the reference has a single scene light every draw reads.
 //!
-//! The real 1.12 client has a single scene light every draw reads; updating it is O(1). We used to
-//! store the resolved [`super::WowLighting`] *per material* and re-push it into every loaded terrain/
-//! model/liquid/wdl material each frame — Bevy then freed+recreated every material's bind group
-//! (`bevy_pbr` material.rs has an explicit "no fast path; we delete and recreate" TODO), a confirmed
-//! ~40fps tax.
-//!
-//! Instead: ONE persistent GPU storage buffer, created once from the main-world [`RenderDevice`]; every
-//! material references it via `#[storage(90, read_only, buffer)]` (a pre-made `Buffer`, baked into the
-//! bind group at prepare, zero per-frame upload — `#[uniform]` can't do this, it always re-allocates). The
-//! material assets are **never mutated after creation**, so no bind group is ever rebuilt. Each frame
-//! [`build_light_data`] (main world) packs the resolved light into a std430 blob and [`upload_light`]
-//! (render world, `PrepareResources`) writes it in place — all bind groups see the new data, zero
-//! rebuilds, regardless of how many tiles/models are loaded or how fast the clock moves.
+//! One persistent storage buffer, which every material binds at `storage(90)`: [`build_light_data`]
+//! packs the resolved light each frame and [`upload_light`] writes it in place. Material assets
+//! are never mutated after creation, since Bevy rebuilds the bind group of a mutated material.
 
 use benilla_formats::LiquidKind;
 use bevy::ecs::system::SystemParam;
@@ -30,11 +20,9 @@ use crate::dev_state::DebugState;
 use crate::view::ViewDistance;
 use crate::view::WorldCamera;
 
-/// The shared light, std430-packed as contiguous `vec4<f32>` rows. All-`vec4` so std430 == std140
-/// (each row 16-aligned, no stride surprises). The row order is the canonical layout every shader
-/// bound at `storage(90)` mirrors as a prefix — the WGSL structs in `wow_model.wgsl`/`terrain.wgsl`/
-/// `wow_effect.wgsl`. (`liquid.wgsl`/`wdl.wgsl` reuse the field NAMES but bind their own
-/// per-material uniforms fed by `apply_wow_lighting` — editing this layout does NOT reach them.)
+/// The shared light, std430-packed as `vec4<f32>` rows (all `vec4`, so std430 equals std140). Every
+/// shader that binds the buffer (`wow_model`, `terrain`, `liquid`, `wdl`, `wow_effect`,
+/// `static_gx`) mirrors this row order as a prefix; keep them in sync.
 ///   0 light_ambient (w=Mod2x 1.0) · 1 light_diffuse (w=clamp on) · 2 light_sun (w=dir/SH enable) ·
 ///   3 light_spec (w=terrain shininess 20) · 4 fog_color (w=enable) · 5 fog_params (x=start y=end
 ///      w=farclip; MONKEY (moon shadows) `.z` = the SIGNED directional-shadow weight — `+sun_w`
@@ -70,13 +58,9 @@ use crate::view::WorldCamera;
 ///      lighting the floor through a closed door. `[pos.xyz, range]`'s `range` is UNTOUCHED
 ///      (still the 48 yd candidacy constant), so the exterior lanes are byte-identical.
 ///
-/// The GPU buffer is LARGER than this per-frame blob: the interior-prop probe table
-/// (`lighting::prop_probes`, 7 rows per slot) lives at its tail — [`light_blob_bytes`] sizes the
-/// buffer for both, `upload_light` rewrites only this prefix each frame, and `upload_prop_probes`
-/// rewrites the tail only when a prop spawns/despawns. Only `wow_model.wgsl` declares the tail
-/// region — the other shaders mirror the PREFIX and bind the same (larger) buffer, which wgpu
-/// allows. Keeping the probes out of this struct keeps it stack-cheap: the ExtractResource clone
-/// runs every frame, and a ~900 KB by-value blob overflowed a render-thread stack (measured live).
+/// The GPU buffer is larger: the interior-prop probes and the skin-palette regions follow this
+/// prefix. They stay out of this struct because the extract clones it by value every frame, and
+/// ~900 KB overflowed a render thread's stack.
 #[repr(C)]
 #[derive(Clone, Copy, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
 struct LightStd430 {
@@ -84,39 +68,15 @@ struct LightStd430 {
     points: [[f32; 4]; 2 * MAX_POINT_LIGHTS],
 }
 
-/// Header row count of the canonical layout above (rows 0..=20). Every producer of a light blob
-/// sizes against this — the portrait booth included.
+/// Header row count of the layout above (rows 0..=20), which every light blob sizes against.
 pub const LIGHT_HEADER_ROWS: usize = 21;
 
-/// Pack the **model-lighting core** into `rows` — every row the model shaders' lit lanes derive
-/// from the (ambient, diffuse, sun_dir) triple: rows 0-2 (ambient/diffuse/sun, w = enables), the
-/// SH block (rows 6-11 + row 12 `.xyz`; DC = ambient in the `.w` lanes), and the sun's SH DC
-/// redistribution (row 17 `.yzw`, at intensity 1). Leaves every other row — and row 12 `.w`
-/// (free) / row 17 `.x` (SIDN) — untouched.
-///
-/// The sun's bands are the `Model2.bls` closed form — the SAME [`sh::prop_probe_coeffs`] fold the
-/// interior lane runs, per the disassembly of the shipped ARB program (wow-re
-/// `system/models/scratch/model2-bls-vertex-sh.md`): `E(n) = D·(3 + 16μ + 15μ²)/34`, μ = n·u
-/// toward-light, EVERY band linear in the committed colour `D` — there is no separate amplitude
-/// scalar, and the per-instance intensity lives entirely in that colour (a consumer multiplies
-/// ALL sun terms by I; packed here at I = 1). The peak (μ=1) equals the FFP walls' `D·(N·L)`
-/// peak by construction (the 16/17 accumulate scale exists for exactly that), and the closed form
-/// never goes meaningfully negative — the old trace-fit's ~¼-strength lobe with a negative back
-/// side (shadow-side characters turned blue as the warm channels floored at 0) is superseded.
-///
-/// **The SH block (rows 6-11, row 12 `.xyz`, row 17 `.yzw`) is the live exterior M2 response**
-/// (0803). It was dormant for months — 0410 took the lane off this curve onto a hard-cutoff FFP
-/// matte on the director's look call and nothing consumed the rows — until 0796 refuted the fidelity
-/// premise behind that retirement (the reference's M2 lane IS this SH shader) and 0799 put the two
-/// side by side for the call. Anything that stops writing these rows now renders every exterior
-/// doodad and creature black. The interior-prop and glue-rig lanes are unaffected — they fold their
-/// own probes through the per-instance `prop_probes` table, not these rows.
-///
-/// This is the ONE packer for the scene light ([`build_light_data`]) AND the portrait booth's
-/// studio light (`portrait::setup_booths`): the booth used to hand-copy the layout and rendered
-/// black portraits the day 0354 moved the lit lanes onto rows it never wrote. A producer that
-/// copies the layout goes stale the day the layout moves — so producers don't copy it, they call
-/// this.
+/// Packs the model-lighting core from `(ambient, diffuse, sun_dir)` and leaves every other lane
+/// alone: rows 0-2, the SH block (6-11 and 12 `.xyz`, ambient in the DC `.w` lanes) and the sun's
+/// SH DC on 17 `.yzw`, the exterior M2 lane's light. The sun's bands are `Model2.bls`'s
+/// `E(n) = D·(3 + 16μ + 15μ²)/34`, μ = n·u toward the light, the interior lane's
+/// [`sh::prop_probe_coeffs`] fold: all linear in `D`, so a consumer scales each by the intensity
+/// (packed at 1). Producers call this and never copy the layout.
 pub fn pack_model_core_rows(
     rows: &mut [[f32; 4]; LIGHT_HEADER_ROWS],
     ambient: [f32; 3],
@@ -126,10 +86,9 @@ pub fn pack_model_core_rows(
     rows[0] = [ambient[0], ambient[1], ambient[2], 1.0]; // 0 light_ambient (w=Mod2x 1.0)
     rows[1] = [diffuse[0], diffuse[1], diffuse[2], 1.0]; // 1 light_diffuse (w=clamp on)
     rows[2] = [sun_dir.x, sun_dir.y, sun_dir.z, 1.0]; // 2 light_sun (w=dir/SH enable 1.0)
-                                                      // The sun lobe folded at intensity 1 with NO ambient — ambient rides the DC lanes directly
-                                                      // (it never scales with the per-instance intensity), while the fold's own `.w` output is the
-                                                      // sun's DC redistribution, re-homed onto row 17 `.yzw` so the shader can scale it by I.
     let sun = sh::prop_probe_coeffs([0.0; 3], &[(-sun_dir, diffuse)]);
+    // The sun folds at intensity 1 without ambient: ambient takes the DC lanes unscaled, and the
+    // fold's own DC moves to row 17 `.yzw`, where the shader scales it by the intensity.
     for (i, row) in sun.iter().enumerate().take(6) {
         rows[6 + i] = row.to_array(); // 6-8 sh_c10_{r,g,b} · 9-11 sh_c13_{r,g,b}
     }
@@ -141,28 +100,17 @@ pub fn pack_model_core_rows(
                             // studio portrait takes neither — the frozen look is deliberate)
     rows[12][1] = sun[6].y;
     rows[12][2] = sun[6].z;
-    // 17 `.yzw` — the sun's SH DC redistribution at intensity 1 (`D·(4/17)(0.375+0.9375(uₓ²+u_y²))`
-    // per channel): an SH consumer adds it × the per-instance intensity (dormant since 0410 — see
-    // the doc above). `.x` (SIDN) is the scene's.
+    // 17 `.yzw`: the sun's SH DC at intensity 1; `.x` (SIDN) is the scene's.
     rows[17][1] = sun[0].w;
     rows[17][2] = sun[1].w;
     rows[17][3] = sun[2].w;
 }
 
-/// The reference's committed point-light diffuse is the **RAW** `colour × intensity × modelFade`
-/// — over-gamut values included (VERIFIED at the bytes + OBSERVED live, wow-re
-/// `models/scratch/trace-forensics-overgamut-point-commit-d3d.md`; compose arithmetic
-/// `m2-light-emitter-instances.md` §6b, animate leg `716a67`–`716aa6`).
-///
-/// `0x71ca80` — which two prior rounds read as a clamp01 and then as a peak-normalize — is
-/// actually a lossy **RGBE-style encoder**: it stores a peak-normalized byte colour at
-/// `CGxLight+0x14` *and* the raw peak float `m = max(1, r, g, b)` at `+0x20`, and the device copy
-/// `0x593040` **decodes them right back** (`byte · m/255 ≈ raw channel`) before the GL light is
-/// set. Net effect: identity up to 8-bit peak-relative quantization (≤ ~0.5 %, which we skip). A
-/// night terrain draw in the ring capture commits `(1.2, 1.035, 0.805)` verbatim — over-white
-/// preserved. So we pack the raw product; the saturation the eye sees comes from the *vertex*
-/// clamp of the summed lighting (GL T&L clamps `ambient + sun + Σ points` per vertex BEFORE
-/// interpolation — see `terrain.wgsl`), never from the commit.
+/// The reference commits a point light's diffuse raw, `colour × intensity × modelFade` (composed
+/// at `0x716a67`), over-gamut included: `0x71ca80` stores a peak-normalized byte colour and the
+/// peak `max(1, r, g, b)`, and `0x593040` decodes them back before the GL light is set. Saturation
+/// comes from the per-vertex clamp of the summed lighting, never from the commit. Deviation: the
+/// round trip's 8-bit quantization is skipped, because it moves a channel by under 0.5 %.
 pub fn commit_raw(rgb: [f32; 3]) -> [f32; 3] {
     rgb.map(|c| c.max(0.0))
 }
@@ -209,25 +157,12 @@ const INTERIOR_NEAR_ADMIT: f32 = 90.0;
 /// (0285: each unit picks its ≤3 nearest from this table) bounded.
 const POINT_PACK_RADIUS: f32 = 300.0;
 
-/// **The rooms a point light belongs to** — a WMO's own MOLT fixture (the groups whose MOLR names
-/// it) or one of its props' M2 lights (the groups whose MODR names the prop). Absent on an ADT map
-/// doodad's light, a creature's, a GameObject's: nothing claims those.
-///
-/// The fourth rider of decision 0689's law, after the prop's mesh, its particle clouds and its
-/// ribbon trails. The reference never needs it: a WMO's furniture is instantiated out of each
-/// **visible** group's MODR list, so a torch in a culled room does not exist and registers no
-/// light. Its light-register walk really does have no visibility term of its own — byte-verified,
-/// wow-re `m2-light-emitter-instances.md` §4: the gate for a model entering the register walk is
-/// the scene update-list activation flag `[model+0x10]`, "not visibility, not distance, not LOD",
-/// and the ≤4 cap is purely receiver-side. So the faithful fix is NOT a visibility test bolted onto
-/// the gather; it is that the SOURCE should not be there at all, which is what this component says.
-/// [`build_light_data`] drops the light while its rooms are culled, exactly as the model-visibility
-/// authority drops the prop's own submeshes.
-///
-/// A newtype rather than a bare [`crate::wmo_portal::WmoGroupVis`] on purpose: that component on a
-/// light entity would enlist it in `apply_model_visibility`'s `group_only` query — a `PointLight`
-/// carries `Visibility` and `GlobalTransform`, so it matches — making the model-visibility
-/// authority a second writer on an entity whose `Visibility` nothing reads (decision 0025).
+/// The rooms a point light belongs to: a WMO's MOLT fixture (the groups whose MOLR names it) or a
+/// prop's M2 light (the groups whose MODR names the prop). The reference admits a WMO's props only
+/// in frames the portal walk visits their group (`0x6838f0`, from `0x685d70`), so a culled room's
+/// torch registers no light; [`build_light_data`] drops the light while its rooms are culled. A
+/// newtype, since a bare [`crate::wmo_portal::WmoGroupVis`] would enlist the light in
+/// `apply_model_visibility`.
 #[derive(Component)]
 pub struct LightRooms(pub(crate) crate::wmo_portal::WmoGroupVis);
 
@@ -665,15 +600,13 @@ impl Default for ShadowFilterGaussian {
 pub struct WorldPointLight {
     /// Linear RGB, hue preserved.
     pub color: [f32; 3],
-    /// `4π × authored intensity` — the `PointLight` convention, so the packer's `/(4π)` reads
-    /// the authored product back.
+    /// `4π × authored intensity`, the `PointLight` convention, which the packer's `/(4π)` undoes.
     pub intensity: f32,
-    /// The ≤3-nearest selection-candidacy radius (yd) — see `terrain_stream::point_light`.
+    /// The ≤3-nearest selection radius (yd).
     pub range: f32,
 }
 
-/// Main-world resource holding the packed light for this frame; extracted into the render world where
-/// [`upload_light`] writes it. Rebuilt every frame by [`build_light_data`] (cheap — one std430 pack).
+/// The packed light for this frame, extracted for [`upload_light`].
 #[derive(Resource, Clone, Copy, ExtractResource)]
 struct WowLightData(LightStd430);
 
@@ -686,16 +619,12 @@ impl Default for WowLightData {
     }
 }
 
-/// The one persistent storage buffer all materials bind. Created once in [`create_shared_light_buffer`]
-/// (main world, so material construction can clone it into the `#[storage(90, …)]` field), then cloned
-/// into the render world via `ExtractResource` so [`upload_light`] can write it. `Buffer` clone shares
-/// the same GPU resource.
+/// The persistent storage buffer every material binds, created by [`new_shared_light_buffer`] and
+/// extracted to the render world; a `Buffer` clone shares the GPU resource.
 #[derive(Resource, Clone, ExtractResource)]
 pub struct SharedLightBuffer(pub Buffer);
 
-/// Wire the shared-light infra into the app. `build_light_data` is chained after the lighting resolve
-/// in [`super::LightingPlugin`]; this adds the resource, the extract plugins, the startup buffer
-/// creation, and the render-world upload.
+/// Registers the light pack, the probe publish, their extracts and the render-world uploads.
 pub(super) fn register(app: &mut App) {
     app.init_resource::<WowLightData>()
         // MONKEY (room gate): the per-fixture room claims, packed beside the point table.
@@ -719,12 +648,8 @@ pub(super) fn register(app: &mut App) {
         .add_plugins(ExtractResourcePlugin::<RoomClaimTable>::default())
         .add_plugins(ExtractResourcePlugin::<SharedLightBuffer>::default())
         .add_plugins(ExtractResourcePlugin::<super::prop_probes::PropProbeExtract>::default())
-        // PostUpdate, **after transform propagation**: the point table is packed from each light's
-        // `GlobalTransform`, and a CARRIED light (0587 — the torch in an NPC's hand) is a child of a
-        // moving joint, so its global is only correct once `Propagate` has run. Packed from `Update`
-        // it read the PREVIOUS frame's pose — the pool rubber-banded behind a walking bearer, and a
-        // freshly spawned light packed one frame at the world origin. A world-baked doodad light
-        // never moves, which is why this was invisible until entities started carrying lights.
+        // After transform propagation: a carried light (a torch in a hand) is a child of a moving
+        // joint, so its `GlobalTransform` is this frame's only once `Propagate` has run.
         .add_systems(
             PostUpdate,
             // MONKEY (light lane by position): the lane classifier is chained BEFORE the packer, so
@@ -738,8 +663,7 @@ pub(super) fn register(app: &mut App) {
         )
         // After the spawners (PostUpdate): publish the probe table for extraction on change.
         .add_systems(PostUpdate, super::prop_probes::publish_prop_probes);
-    // Guarded like every other render-side registration in the tree: a headless build (no GPU,
-    // `backends: None`) has no render app, and the schedule tests build the engine that way.
+    // A headless build (no GPU, `backends: None`), as the schedule tests use, has no render app.
     if let Some(render_app) = app.get_sub_app_mut(RenderApp) {
         render_app.add_systems(
             Render,
@@ -749,11 +673,8 @@ pub(super) fn register(app: &mut App) {
     }
 }
 
-/// Create the single persistent storage buffer. `RenderDevice` is a main-world resource (inserted in
-/// `RenderPlugin::finish`, available from `Startup` on), so the `assets` foundation builds it alongside
-/// `WorldAssets` (which stores a clone so `model_material` can hand it to every model) and inserts the
-/// returned resource (cloned into the render world for [`upload_light`]). `STORAGE | COPY_DST` (storage
-/// binding + per-frame `write_buffer`).
+/// Creates the shared light buffer, sized by [`light_blob_bytes`], from the main-world
+/// `RenderDevice`; the assets foundation builds it at startup.
 pub fn new_shared_light_buffer(device: &RenderDevice) -> SharedLightBuffer {
     SharedLightBuffer(device.create_buffer(&BufferDescriptor {
         label: Some("wow_shared_light"),
@@ -763,23 +684,17 @@ pub fn new_shared_light_buffer(device: &RenderDevice) -> SharedLightBuffer {
     }))
 }
 
-/// The full byte size of the shared light BUFFER: the per-frame blob ([`LightStd430`] — 19 header
-/// rows + the point-light table) PLUS the interior-prop probe region PLUS the skin-palette
-/// regions (rig slot table + tint table + rig-origin table + mat-anim table + straddle clip
-/// table + palette rows — decisions 0720/0812/0974/1381/2188) at the tail. **Every buffer bound as
-/// `wow_light` must be at least this big** — `wow_model.wgsl` declares the whole layout,
-/// and wgpu validates bound size against the shader's struct at draw time. The portrait booth's
-/// frozen studio-light buffer sizes itself with this (its table regions stay zeroed ⇒ no scene
-/// point lights and black probes on portraits — the studio look is deliberately static); a
-/// booth's PALETTE and ORIGIN regions are live, kept written by `rig_palette`'s mirror registry.
+/// The shared light buffer's full size: the per-frame blob ([`LIGHT_HEADER_ROWS`] rows and the
+/// point table), the interior-prop probe region and the skin-palette regions. Every buffer bound
+/// as `wow_light` must be this big: wgpu validates the bound size against `wow_model.wgsl`'s
+/// whole layout at each draw.
 pub fn light_blob_bytes() -> u64 {
     per_frame_blob_bytes()
         + (7 * MAX_PROP_PROBES * 16) as u64
         + crate::rig_palette::palette_regions_bytes()
 }
 
-/// Byte size of the per-frame prefix alone (= the probe region's offset — see
-/// `prop_probes::prop_probe_region_offset`).
+/// The per-frame prefix's size, which is also the probe region's offset.
 pub(super) fn per_frame_blob_bytes() -> u64 {
     std::mem::size_of::<LightStd430>() as u64
 }
@@ -1404,7 +1319,7 @@ fn build_light_data(
     let (rs, rd, rsa, rda) = l.water_colors(LiquidKind::Still);
     let (os, od, osa, oda) = l.water_colors(LiquidKind::Ocean);
     // Built in a scratch copy and written through `ResMut` only when a row moved: the extract
-    // clones this 8.5 KB blob every frame it reads as changed, and a parked frame changes nothing.
+    // clones this 8.5 KB blob every frame it reads as changed.
     let mut fresh = data.0;
     fresh.rows = [[0.0; 4]; LIGHT_HEADER_ROWS];
     let rows = &mut fresh.rows;
@@ -1421,13 +1336,9 @@ fn build_light_data(
     rows[14] = [rd[0], rd[1], rd[2], rda]; // 14 water river deep
     rows[15] = [os[0], os[1], os[2], osa]; // 15 water ocean shallow
     rows[16] = [od[0], od[1], od[2], oda]; // 16 water ocean deep
-                                           // 17 `.x` — the SIDN night fraction (the windows-glow-at-night ramp: `wow_model.wgsl`
-                                           // multiplies each WMO SIDN material's authored emissive colour by it on the lit lanes).
-                                           // `.yzw` is the core packer's below.
     rows[17][0] = l.sidn_night;
-    // 18/19 — the INTERIOR fog triple (see the layout doc above). 19.zw are free lanes: they
-    // carried retired dials (the 0273/0354-era A/Bs, the point gain, the 0750/0751 sun
-    // calibration). 12.w was free too until 0796 gave it the response A/B (below).
+    // Row 17 `.x` is the SIDN night fraction and `.yzw` the core packer's; 18/19 are the interior
+    // fog triple, and 19.zw and 12.w are free.
     rows[18] = [
         l.wmo_fog_color[0],
         l.wmo_fog_color[1],
@@ -1656,17 +1567,8 @@ fn build_light_data(
     for slot in claims.0[pts.len() * ROOM_CLAIM_STRIDE..].iter_mut() {
         *slot = 0;
     }
-    // `WOW_POINTS_DUMP=1`: print the committed point table once a second — the numeric probe for
-    // "what is actually lighting this ground". A pool that reads wrong is one of a small set of
-    // measurable causes (a duplicate light stacking, a light at the wrong height, an over-driven
-    // colour, a count that shouldn't be there), and every one of them is a number here. Throttled,
-    // and capped at the nearest 8 so a torch-lit town doesn't flood the log.
-    //
-    // `WOW_POINTS_DUMP=frame` drops the throttle. A once-a-second dump can only answer "is the pool
-    // right?", never "is it the *same* pool it was last frame?" — and B38's flicker turned out to
-    // alternate frame to frame, which a 1 Hz sample cannot see at all. Reading a per-second dump as
-    // evidence of per-frame stability is how that light was cleared once already (0665's parked
-    // culling test made the same mistake with a different instrument).
+    // `WOW_POINTS_DUMP=1` prints the nearest 8 packed lights once a second; `=frame` every frame,
+    // which a pool that changes frame to frame needs.
     static POINTS_DUMP: std::sync::OnceLock<Option<std::ffi::OsString>> =
         std::sync::OnceLock::new();
     if let Some(mode) = POINTS_DUMP.get_or_init(|| std::env::var_os("WOW_POINTS_DUMP")) {
@@ -1678,10 +1580,8 @@ fn build_light_data(
         let now = time.elapsed_secs_f64();
         if now - *last_dump >= every {
             *last_dump = now;
-            // How contested the three slots are for the chunk under the camera — the number that
-            // decides whether ground pops as emitters move. Candidacy is the faithful Chebyshev
-            // box (`terrain.wgsl`'s `TERRAIN_REACH`); the old 48-yd sphere is printed beside it so
-            // the over-gather stays visible rather than being taken on trust.
+            // Candidates for the camera chunk's three slots: the Chebyshev box of `terrain.wgsl`'s
+            // `TERRAIN_REACH` (keep in sync), with the 48 yd sphere's count beside it.
             let cell = 533.333_3 / 16.0;
             let half = 32.0 * 533.333_3;
             let snap = |v: f32| (((half + v) / cell).floor() + 0.5) * cell - half;
@@ -1762,14 +1662,8 @@ fn build_light_data(
             }
         }
     }
-    // `WOW_LIGHT_DUMP=frame` (or `=1` for 1 Hz): the WHOLE packed header, bit-exact, per frame.
-    //
-    // The point of dumping every row rather than the interesting ones is that B38 has now eliminated
-    // every *per-material* and *per-instance* shading input by measurement — they are bit-identical
-    // on bright and dim frames alike — which leaves this buffer and the view as the only things that
-    // can still be moving. A dump of selected rows would answer "did ambient move?"; only the full
-    // set answers "did ANY shading input move?", and that is the question worth a run. Rows are
-    // printed as raw f32 bits, so a change far below a printed decimal cannot hide.
+    // `WOW_LIGHT_DUMP=frame` (or `=1` for once a second) prints every packed header row as raw f32
+    // bits, so a change below a printed decimal still shows.
     static LIGHT_DUMP: std::sync::OnceLock<Option<std::ffi::OsString>> = std::sync::OnceLock::new();
     if let Some(mode) = LIGHT_DUMP.get_or_init(|| std::env::var_os("WOW_LIGHT_DUMP")) {
         let every = if mode.as_os_str() == "frame" {
@@ -2026,15 +1920,14 @@ mod tests {
     /// channel or row swap in the shader is caught by eye against this, not by this test.
     #[test]
     fn the_sh_response_lane_matches_the_closed_form_at_every_intensity() {
-        // Stormwind, minute ≈1185 — the bands wow-re independently recovered from the reference's
-        // own uploaded shader constants (0796 §1), so the test is anchored on a real committed pair.
+        // A committed Stormwind pair at minute ≈1185, from the reference's uploaded constants.
         let ambient = [102.0 / 255.0, 97.0 / 255.0, 123.0 / 255.0];
         let diffuse = [255.0 / 255.0, 112.0 / 255.0, 0.0];
         let sun_dir = Vec3::new(0.31, -0.82, 0.48).normalize(); // travel dir; to-light = −this
         let mut rows = [[0.0f32; 4]; LIGHT_HEADER_ROWS];
         pack_model_core_rows(&mut rows, ambient, diffuse, sun_dir);
 
-        /// The SH branch of `wow_model.wgsl`'s exterior doodad/entity lane, verbatim.
+        /// The SH branch of `wow_model.wgsl`'s exterior lane, verbatim.
         fn eval_sh_lane(rows: &[[f32; 4]; LIGHT_HEADER_ROWS], n: Vec3, intensity: f32) -> [f32; 3] {
             let quad = [n.x * n.y, n.y * n.z, n.z * n.z, n.x * n.z];
             let x2y2 = n.x * n.x - n.y * n.y;
@@ -2074,9 +1967,7 @@ mod tests {
                 }
             }
         }
-        // The peak is calibrated to the FFP peak by construction (the 16/17 accumulate scale) — so
-        // moving onto this curve changed NOTHING on a surface square to the sun, and the whole
-        // visible difference lives on the shadow side. That is why 0803 read subtle, not dramatic.
+        // At μ = 1 the lobe equals the FFP peak `A + D`, by the 16/17 accumulate scale.
         let peak = eval_sh_lane(&rows, u, 1.0);
         for ch in 0..3 {
             let ffp_peak = ambient[ch] + diffuse[ch]; // ambient + D·max(N·L,0) at N·L = 1
@@ -2087,8 +1978,8 @@ mod tests {
                 ffp_peak
             );
         }
-        // And the mid-back dip really is BELOW ambient — the low-order-SH ringing the reference
-        // authors. Clamping the sun term per-term instead of the sum would erase it.
+        // The mid-back dip goes below ambient, the reference's SH ringing; clamping per term
+        // instead of the sum would erase it.
         let dip = eval_sh_lane(&rows, mid_back, 1.0);
         assert!(
             dip[0] < ambient[0],
@@ -2098,13 +1989,8 @@ mod tests {
         );
     }
 
-    /// GOLDEN — the **commit clamp** (wow-re `m2-light-emitter-instances.md` §6a: `0x71ca80` with
-    /// `w = 1.0` degenerates to clamp01), driven end to end through the real packer so removing the
-    /// clamp from the pack expression fails here rather than in the director's eye.
-    ///
-    /// The held torch is the case that made it visible: authored `(0.467, 0.290, 0.133) × 3.0`, i.e.
-    /// a red channel 40% past white. Unclamped it saturated the MCVT grid far wider than the
-    /// reference and the ground pool read white instead of flame-orange.
+    /// A held torch, authored `(0.467, 0.290, 0.133) × 3.0`, commits its raw product through the
+    /// real packer, red 40% past white (`0x71ca80` encodes, `0x593040` decodes it back).
     #[test]
     fn the_torch_commits_the_raw_authored_product() {
         let mut app = packer_app();
@@ -2118,11 +2004,7 @@ mod tests {
         let rows = &app.world().resource::<WowLightData>().0;
         assert_eq!(rows.rows[20][0], 1.0, "the light packed");
         let rgb = rows.points[1];
-        // The raw authored product — over-white preserved. Two earlier rounds "fixed" this to a
-        // per-channel clamp and then a peak-normalize; the trace-confirmed mechanism is that the
-        // `0x71ca80` encode is decoded straight back by `0x593040`, so the GL light receives the
-        // raw `colour × intensity` (ring capture: a terrain draw commits (1.2, 1.035, 0.805)
-        // verbatim). Saturation belongs to the receiving vertex's lighting clamp, not the commit.
+        // Over-white is kept: saturation is the receiving vertex's clamp, not the commit's.
         assert!(
             (rgb[0] - 1.400_000_1).abs() < 1e-4,
             "red commits raw past white: {rgb:?}"
@@ -2703,9 +2585,8 @@ mod tests {
                 }
             }
         }
-        // The whole back hemisphere stays non-negative BEFORE ambient — the retired trace-fit's
-        // negative lobe (blue shadow-side characters) must never come back. Closed-form minimum is
-        // −0.0373·C at μ≈−0.53; with ambient ≥ 0.038·D the sum never floors a channel at 0.
+        // Over the back hemisphere the sun term never dips below the closed form's minimum,
+        // −0.0373·C·I at μ ≈ −0.53.
         let zero_amb = {
             let mut r = [[0.0f32; 4]; LIGHT_HEADER_ROWS];
             pack_model_core_rows(&mut r, [0.0; 3], diffuse, sun_dir);
@@ -2720,7 +2601,6 @@ mod tests {
                 + zero_amb[12][0] * (n.x * n.x - n.y * n.y);
             zero_amb[6][3] + zero_amb[17][1] * i + i * (lin + q)
         };
-        // Sweep μ over the back hemisphere: the dip never exceeds the documented −0.0373·C·I.
         for k in 0..=20 {
             let mu = -1.0 + k as f32 / 20.0;
             let n = (u * mu + side * (1.0 - mu * mu).sqrt()).normalize();
diff --git a/crates/benilla-world/src/lighting/mod.rs b/crates/benilla-world/src/lighting/mod.rs
index 9e70ecfd..027a4ce0 100644
--- a/crates/benilla-world/src/lighting/mod.rs
+++ b/crates/benilla-world/src/lighting/mod.rs
@@ -1,9 +1,5 @@
-//! Time-of-day lighting, driven by `Light.dbc` sampled against the server game-clock. **Lighting
-//! rebuild — Phase 0 (pitch black).** This module now only *resolves the faithful light values* —
-//! [`WowLighting`] (ambient/diffuse/specular colors + the vanilla `DayNight::SetDirection` sun
-//! direction) — and pushes them onto the terrain/model materials. It no longer spawns a PBR sun /
-//! ambient / distance fog / sky; the faithful lighting is rebuilt in-shader, one verified step at a
-//! time, on top of the Phase-0 black baseline.
+//! Time-of-day lighting: `Light.dbc` resolved against the game clock into [`WowLighting`] and the
+//! shared light buffer every world shader reads; the shaders do the lighting themselves.
 
 use bevy::prelude::*;
 
@@ -59,149 +55,87 @@ pub use global_light::{
     room_claim_bytes, CLAIM_EXT_OK, LIT_ROOM_EXT_DENY, ROOM_CLAIM_MAX, ROOM_CLAIM_STRIDE,
 };
 pub use prop_probes::{PropProbeSlot, PropProbes, MAX_PROP_PROBES};
-// The std430 layout itself — row indices, byte sizes, region offsets and the folds that fill them
-// — stays in the crate. Off-world producers state values through `LightBlob` and never a row index
-// (see `blob`); `global_light` builds the world's own blob on the frame path.
+// The std430 layout stays in the crate: off-world producers state values through `LightBlob`,
+// never a row index.
 pub(crate) use prop_probes::prop_probe_region_offset;
 pub use resolve::WmoCrossfade;
 use resolve::{apply_sky_backdrop, setup_lighting, update_time_lighting};
 pub(crate) use sh::prop_probe_coeffs;
 
-/// Scene lighting sampled from `Light.dbc` for the current time of day — fed into the terrain
-/// shader's WoW lighting. Colors are sRGB 0..1; `sun_dir` is the world-space (Bevy) direction the
-/// sun's light travels. Rewritten every frame by [`update_time_lighting`] as the clock advances.
+/// Scene lighting sampled from `Light.dbc` for the time of day. Colours are sRGB 0..1; `sun_dir` is
+/// the Bevy-space direction the sun's light travels.
 #[derive(Resource, Clone, Copy, Default, PartialEq)]
 pub struct WowLighting {
     pub ambient: [f32; 3],
     pub diffuse: [f32; 3],
-    /// Specular highlight color — the DBC sun-halo color (row 9, warm-white). Drives the terrain
-    /// sheen (Step 3b) and, later, model highlights (Step 7).
+    /// The specular colour, `Light.dbc` IntBand row 9: the terrain and water sun sheen.
     pub spec: [f32; 3],
     pub sun_dir: Vec3,
-    /// The **visible celestial sun** direction (camera→sun, Bevy space) — a *separate* body from the
-    /// lighting `sun_dir`. Drives the sun-disc/glow sprite (`sun.rs`). Unlike the near-fixed lighting
-    /// sun, this one genuinely rises and sets in elevation over the day (see [`daynight::celestial_sun_direction`]).
+    /// The visible sun, camera to sun in Bevy space; unlike the lighting sun it rises and sets.
     pub(crate) celestial_dir: Vec3,
-    /// **Step 5 fog** — gamma-space distance fog, per the q6 RE. Color = `Light.dbc` IntBand
-    /// **row 7** raw (no sky-blend, no sun-glow). `GL_LINEAR`, applied in-shader in gamma space
-    /// BEFORE the sRGB store cancel — NOT Bevy's `DistanceFog`, which blends in linear and breaks
-    /// the gamma invariant.
+    /// Distance fog colour, `Light.dbc` IntBand row 7 raw, applied `GL_LINEAR` in-shader in gamma
+    /// space; Bevy's `DistanceFog` blends in linear and would break the gamma invariant.
     pub fog_color: [f32; 3],
-    /// The **pushed** GL fog pair from [`resolve::scene_fog`] — `end = min(raw band end, farclip)`,
-    /// `start = frac × end` **unclamped**: negative under storm (Elwynn frac −0.5), which is the
-    /// reference's constant ~33% near veil in rain (wow-re `rf-weather-fog-veil.md`).
+    /// The pushed fog pair from [`resolve::scene_fog`]: `end = min(band end, farclip)` and
+    /// `start = frac × end` unclamped (`0x6cee61`), negative under storm: the near veil in rain.
     pub(crate) fog_start: f32,
     pub(crate) fog_end: f32,
-    /// The **interior** fog triple (DNState+0x80/84/88): `lerp(scene fog → the claimed WMO's MFOG
-    /// fog, t)` on the 4 s camera-in-WMO ramp ([`WmoCrossfade`]) — equal to the scene triple while
-    /// the camera is outside. Consumed ONLY by the interior lanes (round-6 Q-I consumer map): the
-    /// interior WMO-group surfaces and THAT group's doodads (`0x6b5190` / the group-doodad drawer
-    /// `0x6b62e0`) — `wow_model.wgsl` selects it by the material interior flag. Terrain, liquid,
-    /// sky, exterior groups, and world units keep the scene fog — the storm stays grey through the
-    /// inn's open door (director ref-shot, 2026-07-13).
+    /// The interior fog triple (`DNState+0x80/84/88`): the scene fog lerped toward the claimed
+    /// WMO's MFOG by the 4 s [`WmoCrossfade`]. Only content tagged as in a room on the camera's
+    /// portal chain reads it: the group's surfaces (`0x6b5190`) and liquid (`0x6b62e0`) and the M2s
+    /// in it (`0x71c110`); terrain, ADT liquid, the sky and exterior groups keep the scene fog.
     pub(crate) wmo_fog_color: [f32; 3],
     pub(crate) wmo_fog_start: f32,
     pub(crate) wmo_fog_end: f32,
-    /// The five sky-dome gradient stops, zenith→horizon (`Atmosphere.sky`, LightIntBand rows 2–6).
-    /// Fed to the `SkyPlugin` dome material; interpolated across the dome by elevation.
+    /// The five sky-dome stops, zenith to horizon (`Atmosphere.sky`, IntBand rows 2-6).
     pub(crate) sky: [[f32; 3]; 5],
-    /// **Per-kind water-surface tint** `[shallow, deep]` — `Atmosphere.water_river` (IntBand rows
-    /// 16/17) and `.water_ocean` (rows 14/15), RAW, resolved from the **area-light blend**, exactly
-    /// like every other band: the client's gather record carries all 18 colour rows and
-    /// `dn_record_overblend 0x6d30e0` merges all 18 per light (rows 14–17 are its `+0x34..+0x40`
-    /// step-9 loop) — there is no single-sphere pick in the water path (decision 1104, superseding
-    /// the `pick_light` split whose discontinuity snapped the tint at Tirisfal→Silverpine). The
-    /// from-above depth swatch is a 2-endpoint linear lerp of these by the per-vertex depth `V`
-    /// (river/lake `V = clamp(byte/42)`; VERIFIED `WoW.exe FUN_0068a830` + `c81768`). Pushed onto the
-    /// per-kind liquid materials by [`apply_wow_lighting`] via [`WowLighting::water_colors`].
+    /// Per-kind water tint `[shallow, deep]`: IntBand rows 16/17 (river, lake) and 14/15 (ocean),
+    /// raw and area-blended like every band (`0x6d30e0` merges all 18 colour rows per light).
     pub(crate) water_river: [[f32; 3]; 2],
     pub(crate) water_ocean: [[f32; 3]; 2],
-    /// **Per-kind water-blend alphas** `[shallow, deep]` — `LightParams.water/oceanShallow/DeepAlpha`,
-    /// blended across the same spheres as the tint. The swatch's depth-alpha ramp endpoints. Per-zone:
-    /// Elwynn/Loch Modan shallow ≈0.5, STV ≈0.85; deep ≈1.0. Replaces the hardcoded `*_SHALLOW_ALPHA`
-    /// constants for the live path (they remain as the `setup_liquid` frame-0 seed + DBC-absent default).
+    /// Per-kind water alphas `[shallow, deep]`, `LightParams` fields 5-8, blended like the tint.
     pub(crate) water_river_alpha: [f32; 2],
     pub(crate) water_ocean_alpha: [f32; 2],
-    /// **Per-zone FFXGlow/bloom composite weight** — `LightParams.glow`, quantised `floor(g·255)/255`
-    /// like the real client. Read by
-    /// `glow.rs`'s `sync_glow_weight` as the faithful default for `GlowSettings.weight` (the panel
-    /// slider is an override). Elwynn ≈ 0.647, Duskwood ≈ 0.498; fallback 0.5.
+    /// The FFXGlow composite weight, `LightParams.glow` quantised as the reference packs it.
     pub(crate) glow: f32,
-    /// **Dawn/dusk sky-dome warp strength** `S` — `dawn_dusk_curve(dayfrac) × highlightSky`, in
-    /// `[0,1]`. Drives the per-zone azimuthal warp in `sky.wgsl` (`FUN_006d0f50`): the sun-facing
-    /// quarter of the dome warms toward SkyColor0, the away side desaturates toward SkyColor1. The
-    /// curve is **0 across all of midday and deep night** (spikes to 1 only at ~06:30/21:30), so this
-    /// is 0 except at dawn/dusk — and 0 entirely in highlightSky=0 zones (Duskwood). At `S=0` the
-    /// warp is identity, so daytime sky stays byte-faithful. See [`daynight::sky_warp`].
+    /// The dawn/dusk sky warp strength `curve(dayfrac) × highlightSky` for `sky.wgsl`'s warp
+    /// (`0x6d0f50`): 0, the identity, except at dawn and dusk in flagged zones.
     pub(crate) sky_warp: f32,
-    /// **Sun disc size multiplier** — `sun_disc_scale(dayfrac)` (vanilla size table `0xce8cac`): `1.0`
-    /// across midday, up to `2.0` at the dawn/dusk horizon (the "huge sun at the horizon"). `sun.rs`
-    /// multiplies the disc's base angular size (`sun_size`) by this. See [`daynight::sun_disc_scale`].
+    /// The sun disc size multiplier (`0xce8cac`): 1 across midday, 2 at the dawn and dusk horizon.
     pub(crate) sun_disc_scale: f32,
-    /// **Sun lens-flare day/night envelope** — the per-body dnCurve table (`0xce9818`): `1.0` across
-    /// the day (07:30→19:30), `0.0` all night with dawn/dusk dead-bands (off by 21:00, back at
-    /// 06:30→07:30). A factor of the flare intensity's slew target in `sun::follow` (wow-re
-    /// celestial-bodies Addendum #5, decision 0508). See [`daynight::sun_flare_dn`].
+    /// The sun lens-flare day envelope (`0xce9818`): 1 from 07:30 to 19:30, 0 at night.
     pub(crate) sun_flare_dn: f32,
-    /// **Visible moon direction** (Bevy camera→moon) — the white moon at azimuth 45° (the sun's
-    /// bearing), up at night and below the horizon by day (`daynight::moon_direction`). The engine's
-    /// second disc (`moon02.blp`) IS drawn but vertex-black (its colour field has no writer in the
-    /// binary) at azimuth 135–165° on a phase-precessed schedule — never a visible second moon
-    /// (decision 0485). Consumed by the moon billboards in `sun`.
+    /// The white moon, camera to moon in Bevy space: up at night, below the horizon by day.
     pub(crate) moon_dir_white: Vec3,
-    /// **Moon disc size multiplier** — `1.0` overhead (~midnight) → `1.5` at moonrise/set (size table
-    /// `0xce8c8c`); `sun` multiplies by the white moon's base ×1.75.
+    /// The moon disc size multiplier (`0xce8c8c`): 1 overhead, 1.5 at moonrise and moonset.
     pub(crate) moon_disc_scale: f32,
-    /// **Moon lens-flare night envelope** — the moon's dnCurve table (`0xce9768`): flat `0.0` from
-    /// 03:15 all the way to 22:45 (the whole day + early evening), ramping in 22:45→24:00, full
-    /// 00:00→02:00. The moon's halo simply does not exist at a 22:30 moonrise (wow-re Addendum #5,
-    /// decision 0508). See [`daynight::moon_flare_dn`].
+    /// The moon lens-flare night envelope (`0xce9768`): 0 from 03:15 to 22:45, full after midnight.
     pub(crate) moon_flare_dn: f32,
-    /// **moon02 direction** (Bevy camera→body) — the engine's third disc, drawn vertex-BLACK on its
-    /// phase-precessed 1.7-day clock ([`daynight::moon02_state`]; decision 0485). Never a visible
-    /// second moon; faithfully occludes stars behind it.
+    /// `moon02`, camera to body in Bevy space: drawn vertex-black, it only occludes the stars.
     pub(crate) moon_dir_02: Vec3,
-    /// **moon02 size multiplier** — the shared `0xce8c8c` curve sampled on moon02's own phase
-    /// clock (base ×1.0).
+    /// `moon02`'s size multiplier, the `0xce8c8c` curve on its own phase clock (base ×1.0).
     pub(crate) moon02_disc_scale: f32,
-    /// **Star-field global alpha** — `star_alpha(dayfrac)` (vanilla star curve `0xce9a98`): `1.0` deep
-    /// night → `0.0` all day (fade in 22:30→00:00, out 03:00→04:30). `sun.rs` multiplies the star dome's
-    /// base-colour alpha by this (the reference's model-global star fade). See [`daynight::star_alpha`].
+    /// The star field's global alpha (`0xce9a98`): 1 in deep night, 0 all day.
     pub(crate) star_alpha: f32,
-    /// **SIDN night fraction** (`DNState+0x1ac`, track `0xce9a34`): `1.0` overnight → `0.0` all day
-    /// (ramps 20:30→21:30 / 06:00→07:00). `wow_model.wgsl` multiplies every WMO SIDN material's
-    /// authored emissive colour by it — the windows-glow-at-night ramp. See
-    /// [`daynight::sidn_night_fraction`].
+    /// The SIDN night fraction (`DNState+0x1ac`, `0xce9a34`) scaling the WMO windows' night glow.
     pub(crate) sidn_night: f32,
-    /// **Celestial diffuse tint** (sRGB) — the one DayNight colour the client broadcasts into the sun
-    /// disc, sun glare, white-moon disc, and moon glare every frame (`[0xce9c2c]`, broadcast by
-    /// `0x6d2260`; decision 0485). **LightIntBand sub-9** — byte-pinned: the band gather `0x6d64d0`
-    /// swaps positions 8/9 so table[8] = sub-9, whose alpha is forced 0xFF (`0x6d62e0`); the same
-    /// row [`Self::spec`] samples (warm cream at night — matching the reference trace's moon VBO
-    /// (254,240,228) — orange at dawn/dusk). The `sun` follow systems rewrite the disc/glare
-    /// material tints from it per frame; the moon's TEAL rim is NOT this tint but the dome's teal
-    /// night bands through the disc's feathered edge.
+    /// The celestial tint (sRGB) the reference broadcasts into the sun and white-moon discs and
+    /// glares each frame (`[0xce9c2c]`, `0x6d2260`): IntBand sub-9, the row [`Self::spec`] samples
+    /// (the gather `0x6d64d0` swaps slots 8/9; alpha forced 0xFF at `0x6d62e0`). The moon's teal
+    /// rim is the dome's night bands through the disc's feathered edge, not this tint.
     pub(crate) celestial_tint: [f32; 3],
-    /// **Authored cloud density `C`** — Light.dbc FloatBand sub-3, weather/area blends included.
-    /// Drives the coverage-field threshold (`clouds`): 0 = cloudless, 1 = full overcast potential
-    /// (wow-re `cloud-coverage-pipeline.md` §4).
+    /// Authored cloud density `C`, FloatBand sub-3 with the weather and area blends (`[0xce9c64]`):
+    /// the coverage threshold, 0 cloudless to 1 full overcast.
     pub(crate) cloud_density: f32,
-    /// **Cloud palette** `[sun-glow, slope, gbase]` — IntBand sub-10/11/12, the visible cloud
-    /// dome's colors (wow-re `cloud-coverage-pipeline.md` §3c).
+    /// The cloud palette `[sun-glow, slope, gbase]`, IntBand sub-10/11/12 (`0x6d64d0`).
     pub(crate) cloud_colors: [[f32; 3]; 3],
-    /// **Storm blend `bcc`** = `min(1, weather_density·4)` (`cloud_density_clamp 0x6d4500`) — the
-    /// weight already lerping the storm LightParams over the clear one, published for the
-    /// celestial-alpha seed (`floor(255·(1−bcc))` on the five body alphas, Addendum #6) and the
-    /// cloud sun-glow dimming (`1 − 0.75·bcc`). Purely weather-driven — authored `C` never feeds
-    /// it (wow-re `cloud-coverage-pipeline.md` §4).
+    /// The storm blend `bcc = min(1, density·4)` (`0x6d4500`) of the weather global `[0xce9ba0]`,
+    /// never `C`: the storm `LightParams` weight, the seed `floor(255·(1−bcc))` of the five body
+    /// alphas (`0x6d2c74`) and the cloud glow dim `1 − 0.75·bcc`.
     pub(crate) storm_bcc: f32,
-    /// **Cloud glow body direction** (Bevy, camera→body) — the sun while the day fraction sits in
-    /// ≈04:50–22:10, the moon otherwise (`0x6cfb00` setup; [`daynight::cloud_glow_is_sun`]). The
-    /// cloud color pass projects it onto the coverage tile as the glow centre.
+    /// The cloud glow's body (`0x6cfb00`): the sun from about 04:50 to 22:10, else the moon.
     pub(crate) cloud_glow_dir: Vec3,
-    /// **Cloud glow track factor** — the internal 8-key day envelope (`0xce9ab8`, ≈1.0 all day,
-    /// twilight notches; [`daynight::cloud_glow_track`]). Multiplied by the weather dim
-    /// `1 − 0.75·bcc` to form the glow intensity.
+    /// The cloud glow's day envelope (`0xce9ab8`), times `1 − 0.75·bcc` for the glow intensity.
     pub(crate) cloud_glow_track: f32,
 }
 
@@ -278,27 +212,24 @@ impl WowLighting {
     }
 }
 
-/// Water surface **specular shininess** — the water material's Phong power for the sun sheen
-/// (`ffp_material.shininess` at the traced water draw ≈ 6; terrain uses 20). Lower ⇒ a broader,
-/// softer glint that spreads at grazing (sunrise/sunset) sun.
+/// The water material's Phong power for the sun sheen: 6 at the reference's water draw, where
+/// terrain uses 20.
 pub(crate) const WATER_SHININESS: f32 = 6.0;
 
-/// Quantise a raw `LightParams.glow` (0..1) to the byte the reference packs into the composite-quad
-/// colour: `floor(g·255)/255`. (Elwynn 0.65 → 0.647.)
+/// `LightParams.glow` quantised to the byte the reference packs into the composite quad's colour,
+/// `floor(g·255)/255` (Elwynn 0.65 → 0.647).
 pub(crate) fn quantize_glow(glow: f32) -> f32 {
     (glow * 255.0).floor() / 255.0
 }
 
-/// The parsed `Light.dbc` family, kept resident so [`update_time_lighting`] can re-sample it each
-/// frame as the server clock advances. Absent if the DBCs failed to load (we fall back to a neutral
-/// day). Loaded once in `setup_lighting`.
+/// The parsed `Light.dbc` family, resident for the per-frame resample; absent without client data.
 #[derive(Resource)]
 pub(crate) struct LightSampler(pub(crate) LightCatalog);
 
-/// Where the time-of-day currently driving lighting comes from — a readout for the debug panel.
+/// Where the lighting's time of day comes from, for the debug panel.
 #[derive(Default, Clone, Copy, PartialEq, Debug)]
 pub enum ClockSource {
-    /// Pre-connect (or DBC-less): hardcoded noon.
+    /// Before connect, or without client data: noon.
     #[default]
     Fallback,
     /// Live server game-clock (`SMSG_LOGIN_SETTIMESPEED`, advanced by its timescale).
@@ -307,31 +238,22 @@ pub enum ClockSource {
     Manual,
 }
 
-/// **What time it is in the world** — the engine's clock *input*, written by whatever owns a
-/// session clock.
-///
-/// The lighting read `net::ServerTime` directly, which made the renderer depend on a wire type
-/// carrying an `Instant` and a packet timescale. 1160 put it plainly: the engine's clock is the
-/// server's clock — but the engine only ever needed three scalars off it, and a program with no
-/// server should get noon rather than a stub.
+/// The world's time of day, the engine's clock input, written by whatever owns a session clock; a
+/// program with no server gets noon.
 #[derive(Resource, Debug, Clone, Copy)]
 pub struct WorldTime {
-    /// Minute of the game day (`0..1440`) — what the `Light.dbc` colour sample, the clock display
-    /// and the log read.
+    /// Minute of the game day (`0..1440`), for the `Light.dbc` sample, the clock and the log.
     pub minute: u32,
-    /// The same, **fractional** — what the celestial body *positions* read, so the sun and moons
-    /// glide instead of stepping once per game-minute (a visible jump at a fast timescale).
+    /// The same, fractional, so the sun and moons glide rather than step each game minute.
     pub minute_f: f32,
-    /// The continuous day count for moon02's phase clock (days + day-fraction, unwrapped).
+    /// The continuous day count for moon02's phase clock (days plus day fraction, unwrapped).
     pub day: f64,
-    /// Has a real clock landed yet? `false` means the fields are the noon fallback, and the
-    /// lighting reports `ClockSource::Fallback` rather than `Server`.
+    /// Whether a real clock has landed; `false` means the noon fallback (`ClockSource::Fallback`).
     pub live: bool,
 }
 
 impl Default for WorldTime {
-    /// Noon, half a day in, not live — the fallback the lighting used to spell out itself when
-    /// `ServerTime` held `None`.
+    /// Noon, half a day in, not live.
     fn default() -> Self {
         Self {
             minute: 720,
@@ -342,8 +264,7 @@ impl Default for WorldTime {
     }
 }
 
-/// The effective game-clock driving lighting this frame — written by [`update_time_lighting`],
-/// read by the debug panel for its time readout. The *output* side of [`WorldTime`]'s input.
+/// The game clock the lighting used this frame, for the debug panel's readout.
 #[derive(Resource, Default, Clone, Copy)]
 pub struct GameClock {
     /// Minute of the game day (`0..1440`) being rendered.
@@ -351,55 +272,30 @@ pub struct GameClock {
     pub source: ClockSource,
 }
 
-/// Ordering handle: [`WowLighting`] and [`WmoCrossfade`] are resolved for the frame after this
-/// set. The skybox weight resolve hangs off it — the sky reading a stale crossfade is a frame
-/// where the painted sky and the fog disagree about how far into the building you are.
+/// [`WowLighting`] and [`WmoCrossfade`] are resolved for the frame after this set; the skybox
+/// weight reads the crossfade after it, or the painted sky and the fog disagree for a frame.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct LightingResolveSet;
 
-/// **The read side of [`LightingResolveSet`] — every `Update` system that reads the resolved
-/// [`WowLighting`] belongs in this set.** Configured once, here, as
-/// `LightingConsumeSet.after(LightingResolveSet)`; a consumer joins the contract with
-/// `.in_set(..)` instead of remembering a bespoke `.after(..)`, which is precisely what five of
-/// them did not remember (decision 2032).
-///
-/// **Why the contract needs a name of its own.** [`resolve::update_time_lighting`] is a *late*
-/// system by construction — it waits on the wire drain ([`crate::schedule::WorldStage::Net`]),
-/// the weather tick and the submersion verdict, each of which waits on something else. A consumer
-/// that declares no ordering waits on nothing, so Bevy's executor starts it at the top of
-/// `Update` and it reads the value the resolve wrote **last** frame. That is not a race: it is
-/// deterministic, it happens on every frame, and it is invisible for as long as the atmosphere
-/// only drifts with the clock.
-///
-/// It stops being invisible at a **submersion crossing**, where the atmosphere does not drift but
-/// jumps — the whole underwater `LightParams` swaps in or out in one frame, on the very frame
-/// [`crate::sky`]'s and [`crate::clouds`]'s own gates un-hide the domes. Report B354 is that
-/// frame photographed: coming up off the Savage Coast, the first dry frame painted the sky dome
-/// in Stranglethorn's UNDERWATER sky stops (`LightParams` 27) over an already-dry world, and
-/// [`crate::clouds`]'s surfacing full-rebuild — the fix for the 0.4 s cloud pop-in — rebuilt the
-/// coverage field at the *underwater* cloud density, which Stranglethorn authors as 0.0, so it
-/// rebuilt an empty sky and the clouds crept back band by band exactly as they had before that
-/// fix existed.
-///
-/// A consumer that runs in `PostUpdate` (the material/GPU pushes, the camera-anchored follows) is
-/// already after the resolve by schedule and needs nothing from this set.
+/// Every `Update` reader of the resolved [`WowLighting`] joins this set, ordered after
+/// [`LightingResolveSet`]. The resolve runs late (after the wire drain, the weather tick and the
+/// submersion verdict), so an unordered reader sees last frame's atmosphere, which shows when it
+/// swaps whole at a submersion crossing. A `PostUpdate` reader is already after the resolve.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct LightingConsumeSet;
 
-/// The one place [`LightingConsumeSet`] is tied to [`LightingResolveSet`] — a named function so
-/// the test below locks the SAME edge the plugin installs, rather than a copy of it.
+/// Orders [`LightingConsumeSet`] after [`LightingResolveSet`]; the test below calls this same
+/// function, so it checks the edge the plugin installs.
 pub(crate) fn configure_lighting_sets(app: &mut App) {
     app.configure_sets(Update, LightingConsumeSet.after(LightingResolveSet));
 }
 
-/// The lighting subsystem: registers the WoW-light resource + game-clock, a **black** background
-/// (Phase 0 — the DBC sky comes back in a later step), and the two per-frame systems that resolve the
-/// `Light.dbc` values for the time of day and push them onto the materials.
+/// The lighting subsystem: the light and clock resources and the per-frame resolve.
 pub(crate) struct LightingPlugin;
 
 impl Plugin for LightingPlugin {
     fn build(&self, app: &mut App) {
-        // The read side of the resolve, configured once (see [`LightingConsumeSet`]).
+        // Readers of the resolve run after it.
         configure_lighting_sets(app);
         app.init_resource::<WowLighting>()
             .init_resource::<PropProbes>()
@@ -413,19 +309,14 @@ impl Plugin for LightingPlugin {
                 (update_time_lighting, apply_sky_backdrop)
                     .chain()
                     .in_set(LightingResolveSet)
-                    // The storm blend reads this frame's weather densities (decision 0302).
+                    // The storm blend reads this frame's weather densities.
                     .after(crate::weather::WeatherTick)
-                    // …and this frame's game clock, which whatever owns the session publishes in
-                    // the wire-drain stage (`WorldTime`). Without this the two are unordered and
-                    // the sun's position can lag a frame at a fast timescale.
+                    // This frame's game clock, published in the wire-drain stage (`WorldTime`).
                     .after(crate::schedule::WorldStage::Net)
-                    // The submerged atmosphere reads THIS frame's submersion verdict — unordered,
-                    // the murk could arrive a frame after the eye went under (and out of step with
-                    // the sky-pass suppression, which reads the same verdict).
+                    // This frame's submersion verdict, which the sky-pass suppression also reads.
                     .after(crate::liquid::SubmersionVerdict),
             );
-        // The shared global-light buffer (build_light_data after the resolve above; the extract +
-        // render-world upload). Materials read this instead of carrying their own light copy.
+        // The shared light buffer, packed after the resolve and uploaded in the render world.
         global_light::register(app);
         // MONKEY (daylight fixtures): the per-frame re-aim, ordered before the packer's own set.
         daylight::register(app);
@@ -437,16 +328,9 @@ impl Plugin for LightingPlugin {
 mod ordering_tests {
     use super::*;
 
-    /// The edge itself, asserted the way the defect presented: **not** "did they happen to run in
-    /// this order" — B354's whole point is that an unordered pair *does* run in some order, one
-    /// the executor picks and that changes with the graph around it — but "is the order
-    /// DETERMINED". Two conflicting systems with no path between them are an *ambiguity*, which
-    /// Bevy will name when asked; deleting or inverting [`configure_lighting_sets`] puts the
-    /// ambiguity back and this fails.
-    ///
-    /// (An earlier cut of this test asserted the observed order and passed with the edge removed,
-    /// because the executor's arbitrary choice happened to be the right one. That is exactly the
-    /// reassurance the bug was hiding behind for months.)
+    /// The edge is asserted as an ambiguity, not an observed order: an unordered pair still runs
+    /// in some order, so only Bevy's ambiguity check fails when [`configure_lighting_sets`] is
+    /// removed or inverted.
     #[test]
     fn consumers_are_ordered_against_the_resolve() {
         use bevy::ecs::schedule::{LogLevel, ScheduleBuildSettings, ScheduleBuildWarning};
@@ -485,23 +369,12 @@ mod ordering_tests {
         );
     }
 
-    /// **Every `Update` reader of [`WowLighting`] in this crate joins the contract.** The defect
-    /// B354 photographed was not a subtle one in any single system — it was five systems that
-    /// each read the resolved atmosphere and none of which said when, so the executor started
-    /// them at the top of `Update` and they got last frame's. A named set only helps if joining
-    /// it is not something a sixth consumer can quietly forget, so this reads the crate's own
-    /// source and insists.
-    ///
-    /// The allowlist is the set of readers that are after the resolve **by schedule** rather than
-    /// by the set — every one of them runs in `PostUpdate` or is chained onto the resolve itself.
-    /// Adding a name here is a claim about WHEN it runs; make it only with the reason.
-    ///
-    /// Scoped to this crate's sources — `benilla-app`'s three readers are outside what a
-    /// `benilla-world` test can see (two are after the resolve by schedule; `minimap` is a
-    /// deliberate exception, decision 2032).
+    /// Every `Update` reader of [`WowLighting`] in this crate joins [`LightingConsumeSet`], checked
+    /// by reading the crate's source; `ALLOWED` lists the readers already after the resolve by
+    /// schedule, each with its reason. `benilla-app`'s readers are outside this check.
     #[test]
     fn every_update_reader_joins_the_consume_set() {
-        /// after-by-schedule, so the set would be redundant — file → why.
+        /// Readers already after the resolve by schedule: file, reason.
         const ALLOWED: &[(&str, &str)] = &[
             (
                 "lighting/resolve.rs",
@@ -547,9 +420,7 @@ mod ordering_tests {
                         && l.contains("Res<")
                         && l.contains("WowLighting>")
                 });
-                // Membership means a real `.in_set(..)` CALL, not a doc comment naming the set —
-                // an early cut of this check passed a file whose only mention was the comment
-                // explaining why it joined.
+                // Membership is a real `.in_set(..)` call, not a comment naming the set.
                 let joins = text.lines().any(|l| {
                     !l.trim_start().starts_with("//")
                         && l.contains("in_set(")
diff --git a/crates/benilla-world/src/lighting/prop_probes.rs b/crates/benilla-world/src/lighting/prop_probes.rs
index facbfba3..c6ddd114 100644
--- a/crates/benilla-world/src/lighting/prop_probes.rs
+++ b/crates/benilla-world/src/lighting/prop_probes.rs
@@ -1,9 +1,7 @@
-//! The per-instance **interior-prop light-probe table**: one 7-row SH probe per lit interior MODD
-//! prop, folded once at spawn ([`super::sh::prop_probe_coeffs`] over the MODD-colour base, the
-//! fixed-axis lobe, and the owning group's MOLR point lobes) and uploaded with the shared light
-//! blob. The prop's `MeshTag` payload carries its slot index; `wow_model.wgsl`'s interior-prop lane
-//! evaluates the probe per fragment. Slots free themselves when the prop despawns (streaming out)
-//! via the [`PropProbeSlot`] component hook — no per-frame bookkeeping.
+//! The interior-prop light-probe table: one 7-row SH probe per lit interior MODD prop, folded at
+//! spawn ([`super::sh::prop_probe_coeffs`] over the MODD colour, the fixed-axis lobe and the
+//! group's MOLR lights) and uploaded behind the shared light blob. The prop's `MeshTag` payload
+//! carries its slot, which the [`PropProbeSlot`] hook frees on despawn.
 
 use std::collections::HashMap;
 use std::sync::Arc;
@@ -14,16 +12,11 @@ use bevy::math::Vec4;
 use bevy::prelude::*;
 use bevy::render::extract_resource::ExtractResource;
 
-/// Capacity of the probe table (mirrored by `wow_model.wgsl`'s `prop_probes` array — keep in sync).
-/// Concurrently-resident lit interior props across every streamed placement: the abbey holds ~150
-/// interior MODDs, but a CITY-scale WMO streams thousands at once (the Northshire login radius
-/// reaches Stormwind's placement — >1024 interior props spawned in one frame, measured live).
-/// 8192 × 7 rows = 896 KB — a per-frame `write_buffer` of that size is noise on any target GPU.
+/// Capacity of the probe table, mirrored by `wow_model.wgsl`'s `prop_probes` array (keep in sync):
+/// a city WMO streams in thousands of lit interior props at once.
 pub const MAX_PROP_PROBES: usize = 8192;
 
-/// A probe's identity for content dedup: the 7 rows, compared/hashed BIT-EXACT (the fold is a pure
-/// function of its inputs, so identical props — the same MODD colour with the same lobe set — fold
-/// to identical bits; a fence WMO placed 200 times collapses to one slot).
+/// A probe's rows, bit for bit: identical props fold to identical bits and share a slot.
 #[derive(Clone, PartialEq, Eq, Hash)]
 struct ProbeKey([[u32; 4]; 7]);
 
@@ -33,33 +26,23 @@ impl ProbeKey {
     }
 }
 
-/// The main-world slot table. `rows` is allocated to capacity once; `free`/`high` implement a slab
-/// (freed slots recycle before the high-water mark advances), and identical probes SHARE a slot via
-/// [`ProbeKey`] refcounting — without it, a login scene's outdoor prop-WMO armies (every placement ×
-/// every MODD of a not-EXTERIOR-flagged group takes the MODD-colour law, faithfully) blew straight
-/// through an 8192 table (measured live at Northshire: peak 8192, still overflowing). The rows live
-/// behind an `Arc` so the render-world extract is a pointer bump, NOT a ~900 KB copy — probes change
-/// on spawn/despawn, not per frame, and [`upload_prop_probes`] writes the GPU region only when
-/// [`Self::generation`] moves (`Arc::make_mut` gives copy-on-write for the frame a change races the
-/// extract).
+/// The main-world slot table: a slab whose freed slots recycle first, with identical probes sharing
+/// a refcounted slot (without it a login scene's prop WMOs overflow the table). The rows sit behind
+/// an `Arc`: the render extract is a pointer bump, and `make_mut` copies when a change races it.
 #[derive(Resource)]
 pub struct PropProbes {
     rows: Arc<Vec<[[f32; 4]; 7]>>,
     free: Vec<u16>,
     high: usize,
-    /// Content dedup: probe bits → live slot. Entries live exactly as long as their refcount.
+    /// Probe bits to live slot, for as long as the slot's refcount lasts.
     by_key: HashMap<ProbeKey, u16>,
-    /// Per-slot (refcount, key) — the release path's reverse lookup. `None` = free slot; a live
-    /// slot with key `None` is OWNED (a dynamic entity's ramping probe — never deduped/shared).
+    /// Per slot `(refcount, key)`, `None` when free; a `None` key marks an owned, unshared slot.
     slots: Vec<Option<(u32, Option<ProbeKey>)>>,
-    /// Bumped on every write — the render-world upload's change detector.
+    /// Bumped on every write; the render-world upload watches it.
     generation: u64,
-    /// Peak concurrent DISTINCT occupancy (diagnostics: logged by the spawner on overflow; a peak
-    /// near capacity is the signal to grow the table).
+    /// Peak distinct occupancy, logged by the spawner on overflow.
     peak: usize,
-    /// Slots written since the last publish, as a `[lo, hi)` span — what the upload writes,
-    /// instead of every allocated row: a walk streams props in and out most frames and each
-    /// change re-sent the whole span (hundreds of KB) for one row.
+    /// Slots written since the last publish, `[lo, hi)`: the upload writes only this span.
     dirty: Option<(usize, usize)>,
 }
 
@@ -79,10 +62,8 @@ impl Default for PropProbes {
 }
 
 impl PropProbes {
-    /// Claim a slot for this probe — a live identical probe just gains a reference; a new one
-    /// takes a free slot and writes its rows. `None` when the table is full of DISTINCT probes
-    /// (the caller falls back to exterior lighting for that prop and warns — graceful, never
-    /// wrong-lit from a stale slot).
+    /// Claims a slot, sharing a live identical probe's; `None` when the table is full of distinct
+    /// probes, and the caller then lights the prop as exterior.
     pub fn alloc(&mut self, coeffs: [Vec4; 7]) -> Option<u16> {
         let key = ProbeKey::of(&coeffs);
         if let Some(&slot) = self.by_key.get(&key) {
@@ -100,10 +81,8 @@ impl PropProbes {
         Some(slot)
     }
 
-    /// Claim an OWNED slot for a dynamic entity's ramping probe (decision 0354): no content dedup —
-    /// two units walking the same room ramp independently, so sharing would couple their light —
-    /// and the holder updates it in place via [`Self::update_owned`] while its node ramps/moves.
-    /// Freed through the same [`PropProbeSlot`] hook as deduped slots.
+    /// Claims an owned slot for a moving entity's probe, never shared, since two units in one room
+    /// ramp independently; the holder rewrites it with [`Self::update_owned`].
     pub(crate) fn alloc_owned(&mut self, coeffs: [Vec4; 7]) -> Option<u16> {
         let slot = self.take_free_slot()?;
         Arc::make_mut(&mut self.rows)[slot as usize] = coeffs.map(|v| v.to_array());
@@ -113,10 +92,8 @@ impl PropProbes {
         Some(slot)
     }
 
-    /// Rewrite an OWNED slot's rows in place (the per-frame refold of a moving/ramping entity).
-    /// Refuses a deduped or free slot — an owned holder can never legitimately point at one, and
-    /// swallowing the write SILENTLY is how a stale holder stays black forever (the stuck
-    /// black-unit-indoors bug rode exactly this no-op), so the refusal warns.
+    /// Rewrites an owned slot in place. A shared or free slot is refused with a warning: a holder
+    /// pointing at one is stale, and a silent no-op would leave it black.
     pub(crate) fn update_owned(&mut self, slot: u16, coeffs: [Vec4; 7]) {
         if !matches!(self.slots.get(slot as usize), Some(Some((_, None)))) {
             warn_once!("update_owned({slot}) on a non-owned slot — the holder's slot is stale");
@@ -126,7 +103,6 @@ impl PropProbes {
         self.touch(slot);
     }
 
-    /// A row changed: widen the dirty span and bump the generation.
     fn touch(&mut self, slot: u16) {
         let s = slot as usize;
         self.dirty = Some(match self.dirty {
@@ -147,15 +123,13 @@ impl PropProbes {
         }
     }
 
-    /// Live and peak DISTINCT occupancy — the spawner's overflow diagnostic.
+    /// Live and peak distinct occupancy.
     pub fn occupancy(&self) -> (usize, usize) {
         (self.high - self.free.len(), self.peak)
     }
 
-    /// Drop one reference (frees at zero). Crate-visible for exactly one caller besides the
-    /// [`PropProbeSlot`] on-remove hook: the interior classifier's apply-time orphan path — a
-    /// slot allocated the same frame its anchor was despawned by the net teardown never gets
-    /// its component (whose hook would free it), so the queued command releases it directly.
+    /// Drops one reference, freeing at zero; besides the [`PropProbeSlot`] hook, the interior
+    /// classifier calls it for a slot whose anchor was despawned before its component landed.
     pub(crate) fn release(&mut self, slot: u16) {
         let Some(entry) = self.slots.get_mut(slot as usize) else {
             return;
@@ -173,24 +147,20 @@ impl PropProbes {
         if let Some(key) = key {
             self.by_key.remove(&key);
         }
-        // Zero the freed probe so a stale MeshTag (a frame of despawn skew) reads black, not the
-        // previous occupant's light.
+        // Zeroed, so a stale `MeshTag` in a frame of despawn skew reads black.
         Arc::make_mut(&mut self.rows)[slot as usize] = [[0.0; 4]; 7];
         self.touch(slot);
         self.free.push(slot);
     }
 }
 
-/// The render-world mirror of the probe table: an `Arc` bump per frame (never a data copy).
-/// [`upload_prop_probes`] writes the shared buffer's probe region — at [`prop_probe_region_offset`],
-/// past the per-frame light blob — only when the generation moves.
+/// The render-world mirror of the probe table, an `Arc` bump per frame.
 #[derive(Resource, Clone, ExtractResource)]
 pub(crate) struct PropProbeExtract {
     rows: Arc<Vec<[[f32; 4]; 7]>>,
     high: usize,
     generation: u64,
-    /// The rows this generation changed, `[lo, hi)`; `None` = everything up to `high` (the
-    /// first publish, and a render world that missed a generation).
+    /// The rows this generation changed, `[lo, hi)`; `None` means everything up to `high`.
     dirty: Option<(usize, usize)>,
 }
 
@@ -199,21 +169,20 @@ impl Default for PropProbeExtract {
         Self {
             rows: Arc::new(Vec::new()),
             high: 0,
-            // != PropProbes' initial 0, so the first refresh publishes even an empty table.
+            // Not `PropProbes`' initial 0, so the first publish sends even an empty table.
             generation: u64::MAX,
             dirty: None,
         }
     }
 }
 
-/// Main world, after the spawners: publish the table for extraction when it changed.
+/// Main world, after the spawners: publishes the table for extraction when it changed.
 pub(super) fn publish_prop_probes(
     mut probes: ResMut<PropProbes>,
     mut out: ResMut<PropProbeExtract>,
 ) {
     if out.generation != probes.generation {
-        // Consecutive generations carry their own span; a publish that skipped one (the
-        // change-gated system did not run in between) sends the whole allocated span once.
+        // After a skipped generation the whole allocated span goes, not just the last change.
         let consecutive = out.generation.wrapping_add(1) == probes.generation
             || out
                 .dirty
@@ -226,13 +195,13 @@ pub(super) fn publish_prop_probes(
     }
 }
 
-/// Byte offset of the probe region inside the shared light buffer (right after the per-frame blob).
+/// Byte offset of the probe region in the shared light buffer, right after the per-frame blob.
 pub fn prop_probe_region_offset() -> u64 {
     super::global_light::per_frame_blob_bytes()
 }
 
-/// Render world (`PrepareResources`): write the probe region in place when the table changed. The
-/// per-frame `upload_light` writes only the prefix, so the tail persists between changes.
+/// Render world, in `PrepareResources`: writes the probe region when the table changed; the
+/// per-frame upload writes only the prefix, so the region persists between changes.
 pub(super) fn upload_prop_probes(
     queue: Res<bevy::render::renderer::RenderQueue>,
     buffer: Option<Res<super::SharedLightBuffer>>,
@@ -245,9 +214,8 @@ pub(super) fn upload_prop_probes(
     if *last == Some(data.generation) {
         return;
     }
-    // The changed span when this render frame follows the last one it uploaded; the whole
-    // allocated span (freed slots inside it are zeroed rows) on the first upload and whenever a
-    // generation went by unseen, so the GPU never keeps a row the CPU has since rewritten.
+    // Only the changed span when this follows the last upload; the whole allocated span on the
+    // first upload and after an unseen generation, so the GPU never keeps a rewritten row.
     let high = data.high.min(data.rows.len());
     let (lo, hi) = match (data.dirty, *last) {
         (Some((lo, hi)), Some(seen)) if seen.wrapping_add(1) == data.generation => {
@@ -266,12 +234,9 @@ pub(super) fn upload_prop_probes(
     }
 }
 
-/// Attached to ONE entity of each lit interior prop instance (they despawn together with the
-/// placement); the hook returns the slot to the table whoever despawns it — and `on_replace`,
-/// not `on_remove` (the `RigSkin` shape, decision 2005): `on_remove` never fires on an
-/// insert-overwrite, so a re-seat that wrote a fresh slot over the old one leaked the old slot
-/// for the life of the session, and only a remove-then-insert discipline at the one re-seat
-/// site kept that from happening. `on_replace` fires once per transition on both edges.
+/// On one entity per lit interior prop; its hook returns the slot to the table. `on_replace`, not
+/// `on_remove`: an insert over a live slot must free the old one, and `on_remove` never fires on
+/// an overwrite.
 #[derive(Component)]
 #[component(on_replace = free_prop_probe_slot)]
 pub struct PropProbeSlot(pub u16);
@@ -294,22 +259,19 @@ mod tests {
         let c = [Vec4::splat(0.5); 7];
         let a = t.alloc(c).unwrap();
         let b = t.alloc(c).unwrap();
-        assert_eq!(a, b); // content dedup: a fence army costs ONE slot
+        assert_eq!(a, b); // identical content shares one slot
         let other = t.alloc([Vec4::splat(0.25); 7]).unwrap();
         assert_ne!(a, other);
-        // First release keeps the shared slot alive; the second frees it.
+        // The first release keeps the shared slot alive; the second frees it.
         t.release(a);
         assert_ne!(t.rows[a as usize], [[0.0; 4]; 7]);
         t.release(b);
-        assert_eq!(t.rows[a as usize], [[0.0; 4]; 7]); // freed ⇒ black, not stale light
-                                                       // The freed slot recycles, and the same content maps to it afresh.
-        let c2 = t.alloc(c).unwrap();
+        assert_eq!(t.rows[a as usize], [[0.0; 4]; 7]); // freed reads black, not stale light
+        let c2 = t.alloc(c).unwrap(); // the freed slot recycles
         assert_eq!(c2, a);
         assert_eq!(t.high, 2);
     }
 
-    /// The hook is `on_replace`, so an insert over a live slot frees the old one — the leak
-    /// `on_remove` would have let through (it never fires on an overwrite).
     #[test]
     fn overwriting_a_probe_slot_frees_the_old_one() {
         let mut w = World::new();
@@ -336,20 +298,19 @@ mod tests {
         let c = [Vec4::splat(0.5); 7];
         let a = t.alloc_owned(c).unwrap();
         let b = t.alloc_owned(c).unwrap();
-        assert_ne!(a, b); // identical content still gets its own slot — ramps stay independent
+        assert_ne!(a, b); // identical content still gets its own slot
         let g0 = t.generation;
         t.update_owned(a, [Vec4::splat(0.7); 7]);
         assert_eq!(t.rows[a as usize], [[0.7; 4]; 7]);
         assert!(t.generation > g0, "in-place update must republish");
-        // A deduped slot ignores update_owned (an owned holder can never point at one).
+        // A shared slot ignores `update_owned`.
         let d = t.alloc(c).unwrap();
         let before = t.rows[d as usize];
         t.update_owned(d, [Vec4::splat(0.9); 7]);
         assert_eq!(t.rows[d as usize], before);
-        // Owned slots free through the same release path (the component hook) and zero their rows.
+        // An owned slot frees through the same release, zeroes, and recycles.
         t.release(a);
         assert_eq!(t.rows[a as usize], [[0.0; 4]; 7]);
-        // …and the freed slot recycles for the next owned claim.
         assert_eq!(t.alloc_owned(c).unwrap(), a);
     }
 
@@ -361,11 +322,10 @@ mod tests {
             assert!(t.alloc(unique).is_some());
         }
         assert!(t.alloc([Vec4::splat(-1.0); 7]).is_none());
-        // …but a DUPLICATE of a live probe still succeeds at capacity (it costs no slot).
+        // A duplicate of a live probe still succeeds at capacity, costing no slot.
         assert!(t.alloc([Vec4::splat(1.0); 7]).is_some());
     }
 
-    /// A shared (extracted) Arc never sees an in-flight mutation: make_mut copies instead.
     #[test]
     fn extracted_rows_are_copy_on_write() {
         let mut t = PropProbes::default();
diff --git a/crates/benilla-world/src/lighting/resolve.rs b/crates/benilla-world/src/lighting/resolve.rs
index 7050f0bd..72e95217 100644
--- a/crates/benilla-world/src/lighting/resolve.rs
+++ b/crates/benilla-world/src/lighting/resolve.rs
@@ -1,8 +1,6 @@
-//! The per-frame time-of-day RESOLVE: samples `Light.dbc` against the effective game clock (server
-//! clock, manual debug-panel scrub, or the pre-connect noon fallback) into a fresh [`super::WowLighting`]
-//! — the scene-fog stage, the camera-in-WMO interior-fog crossfade ([`WmoCrossfade`]), and the startup
-//! seed ([`setup_lighting`]) all live here. Split from the resource type + plugin registration in
-//! `super`.
+//! The per-frame time-of-day resolve: `Light.dbc` sampled at the camera eye for the game clock
+//! (the server's, a debug scrub, or the noon fallback) into [`super::WowLighting`], with the scene
+//! fog, the camera-in-WMO interior-fog crossfade and the startup seed.
 
 use bevy::prelude::*;
 
@@ -16,34 +14,24 @@ use benilla_formats::{Atmosphere, LightCatalog};
 
 use super::{daynight, quantize_glow, ClockSource, GameClock, LightSampler, WowLighting};
 
-/// The scene-fog stage (`dn_scene_fog 0x6cee30`, wow-re `rf-weather-fog-veil.md`): resolve the
-/// **pushed** `(start, end)` fog pair from the blended bands. `end = min(zone_end, farclip)` — the
-/// zone ends in yards (Elwynn 500 clear / 278 storm, decision 0324) exceed only a lowered farclip,
-/// so the wall sits at the zone value and pulls in when the view-distance slider drops below it.
-/// `start = frac × end`, **unclamped** — the storm fraction is negative (Elwynn −0.5), flooring the
-/// whole near field at `1 − 1/(1−frac)` ≈ 33% fog *at the eye*: the constant storm veil.
+/// The scene-fog stage (`0x6cee30`): the pushed pair `end = min(zone end, farclip)` and
+/// `start = frac × end`, unclamped. The storm's negative fraction (Elwynn −0.5) floors the near
+/// field at `1 − 1/(1−frac)`, about 33% fog at the eye: the constant storm veil.
 fn scene_fog(fog_end_raw: f32, fog_start_frac: f32, farclip: f32) -> (f32, f32) {
     let end = fog_end_raw.min(farclip);
     (fog_start_frac * end, end)
 }
 
-/// The camera-in-WMO fog crossfade rate — `[0x8115b0] = 0.25`/s, a **4-second** fade both in and
-/// out (`0x6cefcb–0x6cf051`, wow-re `rf-weather-emission-timeline` ROUND 5).
+/// The camera-in-WMO fog crossfade rate, `[0x8115b0] = 0.25`/s: 4 s in and 4 s out
+/// (`0x6cefcb`–`0x6cf051`).
 const WMO_FOG_RAMP_PER_SEC: f32 = 0.25;
 
-/// The camera-in-WMO **interior crossfade** — the reference's `[0xce9bdc]` (+ the staging
-/// `0x6cef43–62`), ONE number with exactly two consumers: while the camera stands in a WMO
-/// interior, the scene fog — storm veil included — crossfades toward the building's own MFOG fog
-/// over 4 s and back out over 4 s on leaving, **and the same `t` is the WMO skybox's slot alpha**
-/// ("the skybox alpha and the interior fog blend are the same number" — wow-re `wmo-skybox.md` §3,
-/// VERIFIED; `crate::skybox` reads it through [`Self::t`], never a ramp of its own). This is why
-/// the reference's Goldshire inn keeps its warm authored haze while a storm rages outside (the
-/// storm's negative-start veil never reaches the room), and why Stratholme's painted sky fades in
-/// at exactly the rate its streets shed the scene fog. The staged triple LATCHES while the camera
-/// exits so the fade-out lerps from the room's fog instead of popping. A mid-interior fog-record
-/// switch (tavern → corridor) snaps the staged target — the client's source-identity guard
-/// (`0x6cef92–b5`) re-arms a lerp there whose exact semantics are un-carved (flagged in 0338); at
-/// room scales both records' fog is ≈0 so the step is invisible.
+/// The camera-in-WMO interior crossfade, the reference's `[0xce9bdc]`, its fog target staged at
+/// `0x6cef43`–`0x6cef62`: in a WMO interior the scene fog, storm veil included, fades toward the
+/// building's MFOG fog over 4 s, and the same `t` is the WMO skybox's slot alpha (`crate::skybox`
+/// reads [`Self::t`]). The staged fog latches while the camera leaves, so the fade-out starts from
+/// the room's fog. A fog-record switch inside a building snaps the staged target; the reference
+/// re-arms a lerp there (`0x6cef92`) whose semantics are untraced.
 #[derive(Resource, Default)]
 pub struct WmoCrossfade {
     t: f32,
@@ -51,14 +39,12 @@ pub struct WmoCrossfade {
 }
 
 impl WmoCrossfade {
-    /// The crossfade weight this frame, `[0, 1]` — advanced only by [`update_time_lighting`]'s
-    /// blend, read by the skybox weight resolve.
+    /// The crossfade weight this frame, `[0, 1]`.
     pub fn t(&self) -> f32 {
         self.t
     }
-    /// Advance the ramp by `dt` toward `target` and return the committed `(color, start, end)`.
-    /// The staging transform is the record's own law: `end = min(end, farclip)`,
-    /// `start = end × start_scalar` (`fmul 0x6cef56` — MFOG start IS a fraction of end in 1.12.1).
+    /// Advances the ramp by `dt` toward `target` and returns the committed `(color, start, end)`,
+    /// staged as `end = min(end, farclip)` and `start = end × start_scalar` (`0x6cef56`).
     fn blend(
         &mut self,
         target: Option<crate::wmo_portal::WmoFogTarget>,
@@ -95,11 +81,8 @@ impl WmoCrossfade {
     }
 }
 
-/// Startup: load `Light.dbc` and keep it resident as the [`LightSampler`], then seed [`WowLighting`]
-/// with the spawn-zone noon values (colors + the vanilla sun direction) so frame 0 has sane values;
-/// `update_time_lighting` takes over from frame 1. **Phase 0:** no PBR sun / shadows / fog are spawned
-/// — the faithful lighting is rebuilt in-shader. Absent client data ⇒ nothing seeded; `WowLighting`
-/// stays its default.
+/// Loads `Light.dbc` into the [`LightSampler`] and seeds [`WowLighting`] with spawn-zone noon for
+/// frame 0; without client data it stays default.
 pub(super) fn setup_lighting(
     mut commands: Commands,
     world_assets: Option<ResMut<WorldAssets>>,
@@ -109,8 +92,6 @@ pub(super) fn setup_lighting(
         return;
     };
     let mut chain = world_assets.chain.lock_recover();
-    // Keep the catalog resident: `update_time_lighting` re-samples it each frame against the server
-    // clock. The noon seed below only fills `WowLighting` until the first frame runs.
     let catalog = match LightCatalog::load(&mut chain) {
         Ok(cat) => Some(cat),
         Err(e) => {
@@ -118,10 +99,8 @@ pub(super) fn setup_lighting(
             None
         }
     };
-    // The faithful path is `sample_blended` (q2 RE: "rebuild must default to it, NOT `pick_light`").
-    // `sample_noon` falls through to `sample` which uses `pick_light` — single-sphere approximation.
-    // Replicate `sample_noon`'s "DAY/2, false" (noon, clear) but on the blended path. Moot at
-    // SPAWN_XY (no local sphere covers it, α=0 → blended ≡ global) but right anywhere spheres overlap.
+    // Noon (half-minute 1440), clear and dry, on the area-light blend, not the single-sphere
+    // `pick_light` of `sample_noon`.
     let atmo = catalog
         .as_ref()
         .map(|c| {
@@ -143,8 +122,6 @@ pub(super) fn setup_lighting(
         atmo.sun_diffuse, atmo.ambient
     );
     let (fog_start, fog_end) = scene_fog(atmo.fog_end, atmo.fog_start_frac, view.farclip);
-    // The shaders do the WoW lighting themselves, so they need the DBC colors + the sun's world-space
-    // travel direction (the faithful `DayNight::SetDirection` port; noon here, re-derived each frame).
     commands.insert_resource(WowLighting {
         ambient: atmo.ambient,
         diffuse: atmo.sun_diffuse,
@@ -154,7 +131,7 @@ pub(super) fn setup_lighting(
         fog_color: atmo.fog_color,
         fog_start,
         fog_end,
-        // Interior fog seeds equal to the scene (camera starts outdoors, ramp t = 0).
+        // The camera starts outdoors, so the interior fog equals the scene's.
         wmo_fog_color: atmo.fog_color,
         wmo_fog_start: fog_start,
         wmo_fog_end: fog_end,
@@ -164,49 +141,29 @@ pub(super) fn setup_lighting(
         water_river_alpha: atmo.water_river_alpha,
         water_ocean_alpha: atmo.water_ocean_alpha,
         glow: quantize_glow(atmo.glow),
-        // Noon → the dawn/dusk curve is 0, so no sky warp at startup regardless of zone.
         sky_warp: daynight::sky_warp(720.0, atmo.highlight_sky),
-        sun_disc_scale: daynight::sun_disc_scale(720.0), // noon → 1.0 (the sun grows toward the horizon)
-        sun_flare_dn: daynight::sun_flare_dn(720.0),     // noon → 1.0 (full day flare)
+        sun_disc_scale: daynight::sun_disc_scale(720.0),
+        sun_flare_dn: daynight::sun_flare_dn(720.0),
         moon_dir_white: daynight::moon_direction(720.0),
         moon_disc_scale: daynight::moon_disc_scale(720.0),
-        moon_flare_dn: daynight::moon_flare_dn(720.0), // noon → 0.0 (night-only halo)
-        moon_dir_02: daynight::moon02_state(0.5).0, // day 0 noon (below the horizon, like the white moon)
+        moon_flare_dn: daynight::moon_flare_dn(720.0),
+        moon_dir_02: daynight::moon02_state(0.5).0, // day 0, noon
         moon02_disc_scale: daynight::moon02_state(0.5).1,
-        star_alpha: daynight::star_alpha(720.0), // noon → 0 (stars off by day)
-        sidn_night: daynight::sidn_night_fraction(720.0), // noon → 0 (no window glow by day)
+        star_alpha: daynight::star_alpha(720.0),
+        sidn_night: daynight::sidn_night_fraction(720.0),
         celestial_tint: atmo.sun_color,
         cloud_density: atmo.cloud_density,
         cloud_colors: atmo.cloud_colors,
-        storm_bcc: 0.0, // no weather at startup
-        cloud_glow_dir: daynight::celestial_sun_direction(720.0), // noon → the sun
+        storm_bcc: 0.0,
+        cloud_glow_dir: daynight::celestial_sun_direction(720.0), // noon: the sun
         cloud_glow_track: daynight::cloud_glow_track(720.0),
     });
 }
 
-/// Drive **all** scene lighting from the time of day. The effective minute comes from the **server**
-/// game-clock (`SMSG_LOGIN_SETTIMESPEED`, advanced by its timescale) — or, via the debug panel, a
-/// manual scrub or the pre-connect noon fallback. We sample
-/// `Light.dbc` at that time for the ambient/diffuse/specular colors and set the sun *direction* from
-/// vanilla's `DayNight::SetDirection` (fixed azimuth, slight elevation wobble, **always above the
-/// horizon** — see [`daynight::sun_direction`]). Night is dark because the DBC colors go dark, NOT because the
-/// sun sets (that's how the real client does it). **Phase 0:** this only writes the resolved values
-/// into [`WowLighting`] (consumed by `apply_wow_lighting` → the materials). No PBR sun / ambient /
-/// fog / sky are touched — those are rebuilt in-shader step by step.
-/// The reference's `0x6d1620` — an HSV **VALUE-only** scale of a colour, as used by the ocean depth
-/// ramp: unpack to RGB floats, `RGB → HSV` (`0x7bbc80`), multiply the third member (V) alone,
-/// `HSV → RGB` (`0x7bbd60`), repack.
-///
-/// **It is a uniform RGB multiply, and that is a fact rather than an approximation.** HSV keeps
-/// `V = max(r,g,b)` and `S = (max − min)/max`; scaling V while H and S are untouched scales the max
-/// by `f`, and the min by `new_V·(1 − S) = f·min`, and the middle channel by the same ratio — so
-/// every channel comes back multiplied by `f`. The detour is an identity for a V-only scale, so we
-/// transcribe the identity. `the_hsv_detour_is_a_plain_multiply` checks that against an actual
-/// round trip rather than leaving it as an argument in a comment.
-///
-/// The one thing we do NOT carry over is the reference's byte repack (`×255 + 512 >> 14`): its
-/// light lane is 8-bit and ours is float end to end, and re-quantizing here would be inventing a
-/// step this pipeline does not otherwise have.
+/// The reference's HSV value-only scale (`0x6d1620`: RGB to HSV `0x7bbc80`, V × f, HSV to RGB
+/// `0x7bbd60`), used by the ocean depth ramp. With H and S fixed it scales every channel by `f`,
+/// so it is exactly a plain multiply. Deviation: no 8-bit repack (`×255 + 512 >> 14`), because
+/// this light lane is float end to end.
 fn hsv_value_scale(c: [f32; 3], f: f32) -> [f32; 3] {
     [c[0] * f, c[1] * f, c[2] * f]
 }
@@ -229,10 +186,8 @@ pub(super) fn update_time_lighting(
     mut last_dump: Local<Option<u32>>,
     mut last_fog_dump: Local<Option<u32>>,
 ) {
-    // Effective time-of-day and where it came from. `minute` (whole) drives the Light.dbc colour sample,
-    // the clock display, and the log; `minute_f` (FRACTIONAL) drives the celestial body *positions* +
-    // size/star curves so they move continuously — sampling at the truncated whole minute steps them once
-    // per game-minute, a visible jump at a fast timescale (the moon "jumping" on each update).
+    // `minute` drives the `Light.dbc` sample, the clock and the log; the fractional `minute_f`
+    // drives the celestial positions and curves, which would otherwise step once per game minute.
     let (minute, minute_f, source) = if debug.lighting.follow_server_time {
         if world_time.live {
             (world_time.minute, world_time.minute_f, ClockSource::Server)
@@ -247,7 +202,7 @@ pub(super) fn update_time_lighting(
         let m = debug.lighting.manual_minute.min(1439);
         (m, m as f32, ClockSource::Manual)
     };
-    // The continuous day count for moon02's phase clock (days + day-fraction, unwrapped).
+    // moon02's phase clock: the continuous day count, or under the manual scrub the day fraction.
     let day_f: f64 = match debug.lighting.follow_server_time {
         true => world_time.day,
         false => debug.lighting.manual_minute.min(1439) as f64 / 1440.0,
@@ -255,41 +210,24 @@ pub(super) fn update_time_lighting(
     clock.minute = minute;
     clock.source = source;
 
-    // Sample the area-light blend at the CAMERA EYE, resampled every frame — VERIFIED: the real
-    // client feeds the render camera's world eye into the `Light.dbc` sphere-containment blend
-    // (`dn_light_select 0x6d2d00` samples `DNState+0x18`, stamped each frame from the active
-    // `CCamera`'s eye in `WorldFrame::Render 0x482ea0`; wow-re `system/lighting` + benilla-pins B14).
-    // It is the camera, NOT the character: in third-person the eye is offset from the avatar by the
-    // orbit/zoom/pitch, and that offset is intended (sampling `player.pos`, as we used to, was wrong).
-    // No bucketing and no temporal lerp — smoothness is purely spatial (the `blendAlpha` falloff
-    // ramps); the per-material GPU push stays cheap because `apply_wow_lighting` only re-pushes when
-    // the resolved values change. The spawn swatch is the fallback only before the camera exists.
+    // The area-light blend samples the camera eye, not the character, every frame, as the
+    // reference does (`0x6d2d00` reads `DNState+0x18`, stamped from the camera eye at `0x482ea0`).
+    // No temporal smoothing, only the blend's spatial falloff; the spawn point stands in until the
+    // camera exists.
     let wow_pos = match cam.single() {
         Ok(t) => bevy_to_wow(t.translation()),
         Err(_) => [SPAWN_XY.0, SPAWN_XY.1, 83.5],
     };
-    // The faithful area-light blend: seed from the continent global light and α-lerp toward every
-    // overlapping local sphere (`calculateLightParamBlends`/`getLightResultsFromDB`, q2) — NOT the
-    // single-sphere `pick_light` approximation. Sampled at the true `wow_pos` every frame; neutral
-    // daytime fallback if the DBCs are missing. The map id MUST track the current continent — Light.dbc
-    // spheres are filtered by `continent`, so resolving on the wrong map drops every local sphere and
-    // falls back to the *other* continent's global default (e.g. Kalimdor → Eastern-Kingdoms warm fog).
+    // The map must be the current continent: `Light.dbc` spheres are filtered by continent, and
+    // the wrong map falls back to the other continent's global light.
     let map = current_map.as_ref().map_or(0, |m| m.0);
-    // When the camera is submerged, sample the UNDERWATER Light param (slot 1) instead — dense teal
-    // fog + cool light. Feeding it through the normal atmosphere → `WowLighting` path means every
-    // existing consumer (terrain/model/water/WDL fog + the clear colour) becomes underwater for free
-    // (VERIFIED apitrace WoW.18: the reference just switches the active param; no overlay quad).
+    // Submerged, the underwater `LightParams` (slot 1) replaces the atmosphere for every consumer;
+    // the reference switches the active param and draws no overlay.
     let submerged = eye_liquid.submersion();
-    // The ghost-world atmosphere (decision 0308 §7, byte-VERIFIED death-light.md): while
-    // PLAYER_FLAGS_GHOST is up the active LightParams slot is 4 — the death profile — applied
-    // instantly (the client rebuilds its color tables per frame off the single active slot).
+    // A ghost's atmosphere is `LightParams` slot 4, the death profile (`[0xce9bb0]`), at once.
     let ghost = viewer.ghost;
-    // The storm light-blend (the weather arc): weather's slow sky-density channel becomes
-    // `bcc = min(1, density·4)` (`cloud_density_clamp 0x6d4500`), and the STORM LightParams
-    // record is lerped over the clear one by that weight — every band at once (ambient, diffuse,
-    // sky stops, fog color *and distances*). That one blend is the reference's overcast
-    // darkening + fog draw-in. Zones without a storm param fall back to their clear param
-    // inside `sample_blended`, making the lerp an identity there.
+    // The storm blend: `bcc = min(1, density·4)` (`0x6d4500`) lerps the storm `LightParams` over
+    // the clear one, every band at once; a zone without one falls back to its clear param.
     let storm = weather
         .as_ref()
         .map_or(0.0, |w| crate::weather::storm_blend(w.sky_density));
@@ -307,28 +245,16 @@ pub(super) fn update_time_lighting(
             }
         })
         .unwrap_or(Atmosphere::DEFAULT);
-    // Sun direction from vanilla DayNight (fixed azimuth, slight elevation wobble, always up). Sampled
-    // continuously (`minute_f`) — the shared global-light buffer makes per-frame light changes O(1)
-    // (terrain + models read it directly; no per-material re-push), so the interim whole-minute quantize
-    // (the `apply_wow_lighting` FPS stopgap) is no longer needed.
     let sun_dir = daynight::sun_direction(minute_f);
-    // The *visible* celestial sun — a separate body that rises and sets in elevation (for the sprite).
     let celestial_dir = daynight::celestial_sun_direction(minute_f);
 
-    // Step 5 fog from the same DBC sample (q6), through the scene-fog stage: `min(zone end, farclip)`
-    // + `frac × end` unclamped (`dn_scene_fog 0x6cee30`, rf-weather-fog-veil + decision 0324). Elwynn
-    // commits 125/500 clear and −139/278 at full storm — the storm's −0.5 fraction yields the
-    // negative start = the near veil; the short storm end whites out the middle distance.
+    // Elwynn commits 125/500 clear and −139/278 at full storm (`0x6cee30`): the negative start is
+    // the near veil, and the short storm end whites out the middle distance.
     let (fog_start, fog_end) = scene_fog(atmo.fog_end, atmo.fog_start_frac, view.farclip);
-    // The camera-in-WMO interior-fog crossfade (see [`WmoCrossfade`]) — computed as its OWN triple;
-    // the scene fog above stays untouched (the round-5 global-overwrite washed the outside view
-    // golden through the door — director-caught, corrected per the round-6 Q-I lane map).
-    // Submerged, the submerged Light param owns everything — the MFOG record's own underwater
-    // block (`+0x24`, gated record flags 0x100/0x10) is a recorded, deferred lane. Bypassing the ramp
-    // rather than blending through it is also what the reference does for the fullbright liquids
-    // specifically: submerged in magma or slime *inside* an MFOG interior it **snaps** the fog block
-    // instantly (VERIFIED `0x6cef6f-85`) instead of taking the 4 s crossfade — which is the case that
-    // matters here, since Undercity's slime is WMO liquid.
+    // The interior crossfade is its own triple; the scene fog stays untouched. Submerged, the
+    // underwater param owns the fog and the ramp is bypassed, as the reference snaps it for magma
+    // and slime inside an MFOG interior (`0x6cef6f`); the reference's MFOG underwater block
+    // (`+0x24`, flags 0x100/0x10) is not applied.
     let (wmo_fog_color, wmo_fog_start, wmo_fog_end) = if submerged.any() {
         (atmo.fog_color, fog_start, fog_end)
     } else {
@@ -342,18 +268,16 @@ pub(super) fn update_time_lighting(
         )
     };
     let moon02 = daynight::moon02_state(day_f);
-    // **The ocean depth ramp** (decision 1829, wow-re `submerged-atmosphere.md` §3). Ocean alone
-    // runs it, and it darkens the two committed light triples — the first (`DNState+0x178`) by
-    // `fac1` down to 0.5, the second (`+0x174`) by `fac2` down to 0.75, over the first 30 yards.
-    // Every other submersion state, ocean's own fog colour included, is untouched: the fog-colour
-    // commit in the same block is dead code, overwritten from the bands immediately after.
+    // The ocean depth ramp, ocean only: ambient (`DNState+0x178`) × `fac1` down to 0.5 (`0x6d28e0`)
+    // and diffuse (`+0x174`) × `fac2` down to 0.75 (`0x6d28fe`) over the first 30 yd. The block's
+    // fog-colour commit is dead, overwritten from the bands.
     let (fac1, fac2) = submerged
         .ocean_depth_factors(eye_liquid.eye_z())
         .unwrap_or((1.0, 1.0));
     let resolved = WowLighting {
         ambient: hsv_value_scale(atmo.ambient, fac1),
         diffuse: hsv_value_scale(atmo.sun_diffuse, fac2),
-        spec: atmo.sun_color, // row 9 (warm-white) — WoW's specular color
+        spec: atmo.sun_color, // row 9, the specular colour
         sun_dir,
         celestial_dir,
         fog_color: atmo.fog_color,
@@ -363,47 +287,29 @@ pub(super) fn update_time_lighting(
         wmo_fog_start,
         wmo_fog_end,
         sky: atmo.sky,
-        // The water swatch rides the SAME area blend as every other band — byte-VERIFIED, decision
-        // 1104: the gather record's 18 colour slots (rows 14–17 at `+0x34..+0x40`) are all merged by
-        // `dn_record_overblend 0x6d30e0`, so there is no single-sphere pick anywhere in the client's
-        // water path. Resolving it off `pick_light` made the tint DISCONTINUOUS — it snapped whenever
-        // a tighter sphere's outer radius was crossed, i.e. at exactly the point where that sphere's
-        // own weight is zero (Tirisfal → Silverpine: green water to near-black brown in one step).
+        // Area-blended like every band (`0x6d30e0` merges all 18 colour rows): a single-sphere pick
+        // snaps the tint where a sphere's weight reaches zero.
         water_river: atmo.water_river,
         water_ocean: atmo.water_ocean,
         water_river_alpha: atmo.water_river_alpha,
         water_ocean_alpha: atmo.water_ocean_alpha,
-        glow: quantize_glow(atmo.glow), // per-zone bloom weight (LightParams.glow)
-        // Dawn/dusk sky-dome warp: `S = dawn_dusk_curve(dayfrac) × highlightSky`. 0 across midday and
-        // in highlightSky=0 zones, so it only warps the sky at ~06:30/21:30 in highlightSky=1 zones
-        // (Elwynn/Westfall, Thousand Needles, …). S-curve binary-VERIFIED faithful. (Open fidelity Q,
-        // not a panel knob: our shader may over-apply the warp to the
-        // apex/rim vs the binary's 4 mid rings, and the dusk visible result is unconfirmed.)
+        glow: quantize_glow(atmo.glow),
         sky_warp: daynight::sky_warp(minute_f, atmo.highlight_sky),
-        // Sun disc grows to 2× at the dawn/dusk horizon (size table 0xce8cac); 1× midday. Not gated by
-        // a toggle — it's a faithful, binary-verified curve (the trace cross-checks the 2× ratio).
         sun_disc_scale: daynight::sun_disc_scale(minute_f),
-        // The per-body lens-flare day/night envelopes (dnCurve tables, Addendum #5 / 0508): the
-        // sun's flare is a day thing, the moon's halo a deep-night thing; both are 0 at dusk/dawn.
         sun_flare_dn: daynight::sun_flare_dn(minute_f),
-        // The white moon (az 45°, the sun's bearing) + the shared moon size curve.
         moon_dir_white: daynight::moon_direction(minute_f),
         moon_disc_scale: daynight::moon_disc_scale(minute_f),
         moon_flare_dn: daynight::moon_flare_dn(minute_f),
-        // moon02 rides the server-synced continuous day clock (phase ÷1.7); under the manual
-        // scrub there is no day counter, so the scrubbed day-fraction alone feeds the phase.
         moon_dir_02: moon02.0,
         moon02_disc_scale: moon02.1,
         star_alpha: daynight::star_alpha(minute_f),
         sidn_night: daynight::sidn_night_fraction(minute_f),
-        // The celestial-body tint (discs + glares; decision 0485) — band sub-9, the same row as spec.
         celestial_tint: atmo.sun_color,
         cloud_density: atmo.cloud_density,
         cloud_colors: atmo.cloud_colors,
-        // The same weight that lerped the storm LightParams above — the reference computes bcc
-        // once (`0x6d4500`) and every consumer reads the one global.
+        // The one `bcc` that also weighted the storm blend above (`0x6d4500`).
         storm_bcc: storm,
-        // The cloud glow rides the sun by day, the white moon by night (`0x6cfb00` setup).
+        // The sun by day, the white moon by night (`0x6cfb00`).
         cloud_glow_dir: if daynight::cloud_glow_is_sun(minute_f) {
             celestial_dir
         } else {
@@ -411,21 +317,12 @@ pub(super) fn update_time_lighting(
         },
         cloud_glow_track: daynight::cloud_glow_track(minute_f),
     };
-    // Write only on a real change so downstream change-detection (sky/glow + the per-material push in
-    // `apply_wow_lighting`) still fires only on actual transitions, not every frame — even though we
-    // now resample continuously. `ResMut` marks the resource changed only on the DerefMut below.
+    // Assigned only on a change: the deref marks the resource changed, and readers gate on that.
     if *lighting != resolved {
         *lighting = resolved;
     }
-    // `WOW_FOG_DUMP=1`: the interior-fog crossfade live probe, 1 Hz — the committed pair + the
-    // ramp t (the 4 s in/out is too fast for the per-game-minute light dump to catch).
-    //
-    // `WOW_FOG_DUMP=frame` drops the throttle. 1 Hz is fast enough to watch a 4 s ramp travel and far
-    // too slow to see the **target** flip: `blend` switches hard between the scene triple and the
-    // staged interior one on `staged.is_some()`, so a target that alternates frame to frame alternates
-    // the committed fog frame to frame, and a once-a-second sample simply lands on whichever side it
-    // lands on. Rows 18/19 are read by WMO materials *alone*, which is exactly the footprint B38 shows
-    // (decision 0670: one WMO re-lit, terrain and sky untouched).
+    // `WOW_FOG_DUMP=1` prints the committed scene and interior fog and the ramp `t` once a second;
+    // `=frame` prints every frame, which a target flipping frame to frame needs.
     static FOG_DUMP: std::sync::OnceLock<Option<std::ffi::OsString>> = std::sync::OnceLock::new();
     if let Some(mode) = FOG_DUMP.get_or_init(|| std::env::var_os("WOW_FOG_DUMP")) {
         let sec = (mode.as_os_str() != "frame").then(|| time.elapsed_secs() as u32);
@@ -445,23 +342,9 @@ pub(super) fn update_time_lighting(
             );
         }
     }
-    // `WOW_LIGHT_DUMP=1`: print the committed global light once per game minute — the live-probe
-    // instrument for comparing our resolved pair against a reference-trace decode (which reports the
-    // committed GL pair in 0..255 bytes). Throttled on the whole minute so a 60 s probe logs a handful
-    // of lines, not one per frame (`sun_dir` wobbles continuously).
-    //
-    // It leads with the **`map` + eye position it sampled at**, because those are the two inputs that
-    // decide everything after them and neither is visible from the chair. Every colour below is
-    // `sample_blended(map, wow_pos, …)`, and `benilla-extract lightblend <map> <x> <y> <z> <minute>`
-    // recomputes the same call offline — so a line from a live run can be replayed against the DBC
-    // instead of argued about. Without the map printed, "is this the atmosphere the zone actually
-    // authored, or the one next door?" costs a session (Stratholme, 2026-07-29).
-    // `WOW_LIGHT_DUMP=frame` drops the minute throttle, exactly as `WOW_FOG_DUMP=frame` does. The
-    // minute gate is right for comparing colours against a DBC replay, and useless for anything
-    // POSITIONAL: game minutes advance slowly enough that a whole probe logs two lines, and both of
-    // them land in the first moments after world entry — before the submersion verdict has settled,
-    // so the line reports `Dry` at a position that is plainly underwater (1829, chasing exactly
-    // that contradiction).
+    // `WOW_LIGHT_DUMP=1` prints the resolved light once per game minute, led by the map and eye
+    // position it sampled, which `benilla-extract lightblend <map> <x> <y> <z> <minute>` replays
+    // offline; `=frame` prints every frame, for anything positional.
     static LIGHT_DUMP: std::sync::OnceLock<Option<std::ffi::OsString>> = std::sync::OnceLock::new();
     if let Some(mode) = LIGHT_DUMP.get_or_init(|| std::env::var_os("WOW_LIGHT_DUMP")) {
         let key = (mode.as_os_str() != "frame").then_some(minute);
@@ -471,11 +354,7 @@ pub(super) fn update_time_lighting(
         *last_dump = key;
         let b = |c: [f32; 3]| [c[0] * 255.0, c[1] * 255.0, c[2] * 255.0].map(|v| v.round() as i32);
         eprintln!(
-            // The submersion tail (1829) reports the RAMP ITSELF, not just its result. Comparing
-            // two dives at different depths cannot prove the ramp fired — the light row moves with
-            // the clock between runs, and the dump only fires on a game-minute change, so the two
-            // samples are never the same row. Printing the factors and their input settles it in
-            // one line instead.
+            // The tail prints the ocean ramp's factors and the eye depth they came from.
             "[light] map {map} at ({:.1}, {:.1}, {:.1}) minute {minute} ({source:?}) ambient {:?} diffuse {:?} spec {:?} sun_dir {:.3} fog {:?} start/end {:.0}/{:.0} submersion {submerged:?} eye_z {:.1} ocean_fac {:.4}/{:.4}",
             wow_pos[0],
             wow_pos[1],
@@ -494,18 +373,8 @@ pub(super) fn update_time_lighting(
     }
 }
 
-/// **Step 6** — drive the camera's `ClearColor` from the same Light.dbc row-7 fog colour the
-/// terrain and model shaders blend in (Step 5). Sky / skybox proper is deferred; for now the
-/// backdrop is just the fog colour, so a fully-fogged texel at the far plane lands on the same
-/// gamma byte as the void behind it (no horizon seam). q6 RE: the reference client's sky pass
-/// actually sets its own tiny 70→75 fog and draws in the fog colour, so the horizon converges on
-/// row 7 the same way; we approximate that with `glClearColor` until the sky dome is built
-/// (out-of-scope per the plan).
-///
-/// `Color::srgb` takes gamma-space 0..1 — that's exactly the form `WowLighting.fog_color` carries
-/// (the DBC byte triple divided by 255). Bevy's clear pass writes the bytes to the sRGB surface
-/// target directly, so the on-screen byte equals the DBC byte (same invariant as the shader output
-/// decode). Only writes when the colour actually changes, so frame-to-frame churn stays at zero.
+/// The clear colour is the row-7 fog colour, so a fully fogged texel at the far plane meets the
+/// void behind it without a seam.
 pub(super) fn apply_sky_backdrop(
     lighting: Option<Res<WowLighting>>,
     mut clear: ResMut<ClearColor>,
@@ -518,8 +387,8 @@ pub(super) fn apply_sky_backdrop(
         return;
     }
     *last = Some(l.fog_color);
-    // GAMMA LANE (0161): the buffer holds gamma bytes — the clear writes the authored DBC
-    // value RAW (`linear_rgb` = no conversion); the frame's one decode is the FFXGlow combine.
+    // The buffer holds gamma bytes, so the clear writes the DBC value raw (`linear_rgb` converts
+    // nothing); the frame's one decode is the FFXGlow combine.
     clear.0 = Color::linear_rgb(l.fog_color[0], l.fog_color[1], l.fog_color[2]);
 }
 
@@ -527,9 +396,7 @@ pub(super) fn apply_sky_backdrop(
 mod ocean_ramp_tests {
     use super::hsv_value_scale;
 
-    /// A textbook `RGB → HSV → RGB` round trip, written out here so the identity claim in
-    /// [`hsv_value_scale`]'s doc is *checked* rather than argued. If it were ever false, our one
-    /// multiply would be silently wrong in colour rather than obviously wrong in code.
+    /// A textbook `RGB → HSV → RGB` round trip, the reference's detour written out.
     fn round_trip_v_scale(c: [f32; 3], f: f32) -> [f32; 3] {
         let (r, g, b) = (c[0], c[1], c[2]);
         let max = r.max(g).max(b);
@@ -545,7 +412,7 @@ mod ocean_ramp_tests {
         } else {
             60.0 * ((r - g) / (max - min) + 4.0)
         };
-        // V *= f, H and S untouched — the reference's `0x6d1620`.
+        // V *= f, H and S untouched, as `0x6d1620` does.
         let v = v * f;
         // HSV -> RGB
         let cc = v * sat;
@@ -562,9 +429,7 @@ mod ocean_ramp_tests {
         [r1 + m, g1 + m, b1 + m]
     }
 
-    /// The reference scales HSV **V** alone; we transcribe that as a plain RGB multiply. This is an
-    /// identity, not an approximation — and the round trip above says so for real colours,
-    /// including the degenerate greys and blacks where the hue is undefined.
+    /// The value-only scale equals a plain multiply, greys and black (hue undefined) included.
     #[test]
     fn the_hsv_detour_is_a_plain_multiply() {
         let colours = [
@@ -595,9 +460,7 @@ mod tests {
     use super::*;
     use crate::wmo_portal::WmoFogTarget;
 
-    /// The 4 s in/out crossfade (`0.25/s` — `[0x8115b0]`): entering ramps to full in 4 s, the
-    /// staged fog LATCHES on exit so the fade-out lerps from the room's fog, and the ramp
-    /// releases the latch at zero.
+    /// The 4 s crossfade (`[0x8115b0]` = 0.25/s): the staged fog latches on exit and releases at 0.
     #[test]
     fn wmo_fog_ramp_fades_in_and_out_over_four_seconds() {
         let mut ramp = WmoCrossfade::default();
@@ -607,20 +470,20 @@ mod tests {
             start_scalar: 0.25,
         };
         let scene = ([0.2, 0.2, 0.2], -139.0, 278.0);
-        // 2 s in → half-way: end midway between the storm's 278 and the room's 194.4.
+        // 2 s in: the end is midway between the storm's 278 and the room's 194.4.
         let (_, _, end) = ramp.blend(Some(target), scene.0, scene.1, scene.2, 1100.0, 2.0);
         assert!((ramp.t - 0.5).abs() < 1e-6);
         assert!((end - (278.0 + (194.4 - 278.0) * 0.5)).abs() < 1e-3);
-        // 2 s more → fully the room's fog: start = end × scalar, storm veil gone.
+        // 4 s in: the room's fog alone, start = end × scalar.
         let (color, start, end) = ramp.blend(Some(target), scene.0, scene.1, scene.2, 1100.0, 2.0);
         assert!((end - 194.4).abs() < 1e-3);
         assert!((start - 194.4 * 0.25).abs() < 1e-3);
         assert!((color[0] - 1.0).abs() < 1e-6);
-        // Leave: 2 s out with NO target — the latched room fog still blends at half weight.
+        // 2 s out with no target: the latched room fog still blends at half weight.
         let (_, _, end) = ramp.blend(None, scene.0, scene.1, scene.2, 1100.0, 2.0);
         assert!((ramp.t - 0.5).abs() < 1e-6);
         assert!((end - (278.0 + (194.4 - 278.0) * 0.5)).abs() < 1e-3);
-        // 2 s more → scene fog verbatim and the latch releases.
+        // 4 s out: the scene fog verbatim.
         let (color, start, end) = ramp.blend(None, scene.0, scene.1, scene.2, 1100.0, 2.0);
         assert_eq!((color, start, end), scene);
         let (c2, s2, e2) = ramp.blend(None, scene.0, scene.1, scene.2, 1100.0, 2.0);
@@ -628,8 +491,8 @@ mod tests {
         assert!(ramp.staged.is_none(), "latch releases at t = 0");
     }
 
-    /// The staging clamp: a record end beyond the farclip commits the farclip (`0x6cef43` clamps
-    /// vs `[0xce9b94]`), and start scales off the CLAMPED end.
+    /// A record end past the farclip commits the farclip (`0x6cef43` against `[0xce9b94]`), and
+    /// the start scales off the clamped end.
     #[test]
     fn wmo_fog_staging_clamps_end_to_farclip() {
         let mut ramp = WmoCrossfade::default();
diff --git a/crates/benilla-world/src/lighting/sh.rs b/crates/benilla-world/src/lighting/sh.rs
index dcf3f8b5..d69fc015 100644
--- a/crates/benilla-world/src/lighting/sh.rs
+++ b/crates/benilla-world/src/lighting/sh.rs
@@ -1,21 +1,14 @@
-//! Model SH light-probe coefficient math — pure functions, no Bevy systems. Owns the order-2
-//! spherical-harmonic fold the reference runs in `Model2.bls` ([`prop_probe_coeffs`] — ONE closed
-//! form for the interior-prop probes AND the exterior scene-sun rows, per the disassembly of the
-//! shipped ARB program: wow-re `system/models/scratch/model2-bls-vertex-sh.md`), evaluated
-//! per-fragment in `wow_model.wgsl`. The old trace-fit builder (`model_sh_coeffs`, the 0.722
-//! amplitude factorization + `SUN_DC`) is retired: the disassembly showed its directional response
-//! was ~¼ of the real curve with a negative back lobe (the blue shadow-side characters), and that
-//! no separate amplitude scalar exists — intensity lives entirely in the committed colour.
+//! The order-2 SH light fold of the reference's `Model2.bls`: one closed form for the interior-prop
+//! probes and the exterior sun rows, evaluated per fragment in `wow_model.wgsl`. There is no
+//! separate amplitude scalar; intensity lives entirely in the committed colour.
 
 use bevy::math::{Vec3, Vec4};
 
-/// Fold one interior M2 prop's committed light into the 7-row order-2 SH probe — the EXACT closed
-/// form of the reference's CPU accumulators (wow-re `trace-forensics-abbey-interior-d3d` §1: the
-/// byte-verified ambient ×2√π into L00 and directional ×16π/17 on the 9-term basis reduce, with band
-/// factors (1, 2/3, 1/4), to `E += C·(4/17)·(0.375 + 2μ + 1.875μ²)` per directional lobe, μ = n·u —
-/// decoded off the live abbey stand draws to float precision, residuals ~1e-7). Expanding μ² over
-/// the shader basis `(n, 1, n.xy, n.yz, n.z², n.xz, n.x²−n.y²)` gives, per lobe (colour C,
-/// toward-light unit u):
+/// Folds committed lights into the 7-row order-2 SH probe, the closed form of the reference's
+/// accumulators: ambient ×2√π into L00 (`0x71bc70`) and each directional lobe ×16π/17 on the
+/// 9-term basis (`0x71bce0`), with band factors 1, 2/3 and 1/4, reduce to
+/// `E += C·(4/17)·(0.375 + 2μ + 1.875μ²)`, μ = n·u. On the shader basis
+/// `(n, 1, n.xy, n.yz, n.z², n.xz, n.x²−n.y²)`, per lobe of colour C and toward-light unit u:
 ///
 ///   DC     += C·(4/17)·(0.375 + 0.9375·(uₓ² + u_y²))
 ///   linear += C·(8/17)·u
@@ -23,18 +16,9 @@ use bevy::math::{Vec3, Vec4};
 ///   n.z²   += C·(7.5/17)·(u_z² − ½(uₓ² + u_y²))
 ///   x²−y²  += C·(7.5/34)·(uₓ² − u_y²)
 ///
-/// Ambient adds to DC ×1. The expansion identity is frame-generic (the curve depends only on
-/// μ = n·u), so folding and evaluating in Bevy world space is exact. `lobes` = `(toward-light unit
-/// dir, colour)` — for an interior prop the fixed interior axis + the group-MOLR point lobes, all
-/// pre-gained; for the exterior scene rows the sun (to-light, storm-blended diffuse), packed at
-/// intensity 1 by `global_light::pack_model_core_rows`. This is the SAME curve the shipped
-/// `Model2.bls` vertex program evaluates for BOTH lanes (wow-re `model2-bls-vertex-sh.md`: all 450
-/// lit permutations carry the identical lighting block; every constant is byte-anchored —
-/// `16π/17` accumulate scale on the standard real-SH basis, band ratios exactly 1 : 2/3 : 1/4,
-/// linear coefficient exactly 8/17; the SH peak at μ=1 equals the FFP `D·(N·L)` peak by
-/// construction). Evaluated per fragment in `wow_model.wgsl`; note the SH lobe is SOFTER than a
-/// hard `max(N·L, 0)` (E(μ=0) = 0.088·C, E(μ=−1) = 0.059·C — the reference's authored
-/// wrap-around, not a bug).
+/// Ambient adds to DC ×1. The curve depends only on μ, so folding in Bevy space is exact. `lobes`
+/// are `(toward-light unit, colour)`, pre-gained. E(μ=1) = C, the FFP peak, but the lobe is softer
+/// than `max(N·L, 0)`: E(μ=0) = 0.088·C and E(μ=−1) = 0.059·C, the reference's authored wrap.
 pub fn prop_probe_coeffs(ambient: [f32; 3], lobes: &[(Vec3, [f32; 3])]) -> [Vec4; 7] {
     const K: f32 = 4.0 / 17.0;
     let mut c = [Vec4::ZERO; 7];
@@ -77,13 +61,10 @@ mod tests {
         [0usize, 1, 2].map(|ch| c[ch].dot(n1) + c[3 + ch].dot(quad) + c[6][ch] * x2y2)
     }
 
-    /// GOLDEN — this lane's half of the two-curve split (decision 1709). An interior fold puts its
-    /// diffuse word on the fixed axis `(−0.30822, −0.30822, −0.9)` in WoW space, whose Bevy image
-    /// is unit and 0.9 up, so a world-up normal reads μ = 0.9 at every camera angle. A MESH batch
-    /// takes the SH lane and therefore `ambient + (4/17)·(0.375 + 2·0.9 + 1.875·0.81)·diffuse`
-    /// = `ambient + 0.869118·diffuse`; its own PARTICLES take the fixed-function lane and read
-    /// `ambient + 0.9·diffuse` off the same words
-    /// ([`crate::terrain_stream::interior_light_up`]). The two are meant to differ.
+    /// The fixed interior axis travels `(−0.30822, −0.30822, −0.9)` in WoW space, so a world-up
+    /// normal reads μ = 0.9 and a mesh gets `ambient + 0.869118·diffuse`, while the prop's
+    /// particles take the fixed-function `ambient + 0.9·diffuse`
+    /// ([`crate::terrain_stream::interior_light_up`]); the two lanes are meant to differ.
     #[test]
     fn a_world_up_normal_reads_the_fixed_interior_axis_at_a_constant() {
         let u = Vec3::new(-0.30822, 0.9, -0.30822);
@@ -100,10 +81,9 @@ mod tests {
         }
     }
 
-    /// GOLDEN — the reference's closed form at the three anchor normals: facing the lobe the full
-    /// colour arrives (`E(μ=1) = ambient + C` exactly — (4/17)·(0.375+2+1.875) = 1); side-on the
-    /// authored wrap leaves (4/17)·0.375 = 0.0882·C; opposite, (4/17)·0.25 = 0.0588·C. The director's
-    /// stand (MODD[24]): ambient (61,59,96)/255, diffuse (90,86,141)/255, fixed axis, NO point lobes.
+    /// The closed form at μ = 1, 0 and −1: `ambient + C`, `+ 0.0882·C` and `+ 0.0588·C`. The
+    /// inputs are an abbey stand's (MODD[24]): ambient (61,59,96)/255, diffuse (90,86,141)/255,
+    /// the fixed axis and no point lobes.
     #[test]
     fn prop_probe_matches_the_closed_form_at_the_anchor_normals() {
         let ambient = [61.0 / 255.0, 59.0 / 255.0, 96.0 / 255.0];
@@ -122,7 +102,7 @@ mod tests {
                 );
             }
         };
-        // μ = +1 (a cup-top facing the light): ambient + diffuse, exactly.
+        // μ = +1: ambient + diffuse, exactly.
         close(
             eval_probe(&c, u),
             [
@@ -143,7 +123,7 @@ mod tests {
             ],
             "away",
         );
-        // μ = 0 (a pole side-on): ambient + 0.0882·diffuse.
+        // μ = 0: ambient + 0.0882·diffuse.
         let side = u.cross(Vec3::Y).normalize_or_zero();
         let side = if side.length_squared() < 0.5 {
             Vec3::X
@@ -160,7 +140,7 @@ mod tests {
             ],
             "side-on",
         );
-        // No lobes at all → the flat ambient probe (a no-MOLR group's stand under ambient only).
+        // No lobes: the flat ambient probe.
         let flat = prop_probe_coeffs(ambient, &[]);
         close(eval_probe(&flat, Vec3::Y), ambient, "ambient-only");
         // Lobes are additive: a second lobe adds its own closed form independently.
diff --git a/crates/benilla-world/src/liquid/drift.rs b/crates/benilla-world/src/liquid/drift.rs
index 1b2ddbcb..794b93f9 100644
--- a/crates/benilla-world/src/liquid/drift.rs
+++ b/crates/benilla-world/src/liquid/drift.rs
@@ -1,52 +1,16 @@
-//! The underwater **drift cloud** — the 4000-mote field the reference draws while the camera eye
-//! is inside a liquid (decision 1814).
+//! The underwater drift cloud: 4000 world-fixed motes the reference draws while the camera eye is
+//! inside a liquid. The object is `World.cpp`'s own (`0xfa40` bytes from `0x66f971`, ctor
+//! `0x68e5a0`, held at `[0xc63180]`), sharing nothing with the weather manager `[0xc6326c]`. The
+//! advect (`0x66fee0`) and the draw (`0x6701e0`) both need the render-flag bit
+//! `[0xc7b2a4] & 0x2000000` and a camera-eye liquid type `[0xc7f288] != 0xf` ([`Underwater`]). The
+//! draw (`0x483731`) is the frame's last world content, after the water surface and both M2
+//! transparent passes ([`Rung::DRIFT_CLOUD`](crate::sky_order::Rung::DRIFT_CLOUD)), and no
+//! `LightParams` value reaches a mote.
 //!
-//! Ground truth: wow-re `system/lighting/scratch/drift-cloud-emission-law.md`, a §5 six-worker
-//! round commissioned for this build, plus the difftested kernel transcription in wow-re
-//! `crates/lighting/src/drift.rs`. The object is `World.cpp`'s own — `0xfa40` bytes from
-//! `0x66f971`, ctor `0x68e5a0`, held by the pointer `[0xc63180]` — and it is **not** part of the
-//! weather manager `[0xc6326c]`: the two share no state and no code (verified by complete
-//! enumeration; 12 references to the cloud, none in the CMapWeather band).
-//!
-//! ## The shape
-//!
-//! 4000 records of 16 bytes — `xyz` **camera-relative**, plus a per-particle billboard edge. They
-//! sit in a 30 yd cube centred on the eye and are advected by `p += (last_cam − cam) + gust`, each
-//! axis wrapped back into `±15`: the cloud is therefore **world-fixed** apart from the gust, and
-//! the wrap recycles a mote the moment it leaves the box. Nothing is spawned or killed — there is
-//! no lifetime, no emitter, and no per-particle recycle; the whole field is re-scattered only on a
-//! liquid-type change or a teleport.
-//!
-//! Both drive sites — the advect `0x66fee0` and the draw `0x6701e0` — carry the same two
-//! conjuncts: the render-flag bit `[0xc7b2a4] & 0x2000000` and `[0xc7f288] != 0xf`, the
-//! **camera-eye** liquid type. That second one is [`Underwater`], which benilla's murk already
-//! gates on, so the motes appear exactly when the murk does.
-//!
-//! ## Where it draws
-//!
-//! `0x483731`, between the ground-target reticle's liquid pass and the glare dispatch — after the
-//! water surface **and** both M2 transparent passes, i.e. the last world content in the frame.
-//! [`Rung::DRIFT_CLOUD`](crate::sky_order::Rung::DRIFT_CLOUD) is that slot on our ladder.
-//!
-//! Render state is unusually plain: alpha blend, depth test on, **depth write off**, lighting off,
-//! immediate `0xFFFFFFFF` white, and fog **off** for water/ocean (on only for magma). No
-//! LightParams value reaches a mote — the draw contains zero indirect calls and the colour is a
-//! compile-time immediate — so the motes are full-brightness texels over the fogged scene and take
-//! **no** underwater tint. That is worth stating because it is the opposite of the obvious guess.
-//!
-//! ## Where we knowingly differ from the bytes
-//!
-//! Four places, each a deliberate call rather than a gap — the reasoning is in decision 1814:
-//!
-//! 1. **[`GUST_REF_HZ`]** — the reference's water gust is a per-*frame* displacement with no `dt`
-//!    term, so its drift speed scales with frame rate. We normalise it to 60 fps.
-//! 2. **Atlas cell 12 is completed.** The reference's UV initialiser stops two floats early and
-//!    one magma mote in four draws a sprite smeared across the atlas diagonal — a shipped defect
-//!    ([`ATLAS`]).
-//! 3. **The cell walk has no off-by-one.** The reference reads its cell index at the *bottom* of
-//!    the draw loop, so the value lands on the next mote and slot 0 takes a hardcoded cell 8.
-//! 4. **The cull cone is floored at the frustum** ([`cull_limits`]) — its hardcoded 90° contains
-//!    the view at every aspect the reference shipped for, and stops doing so around 21:9.
+//! Deviation: mote `i` draws cell `i & 7` of its set, because the reference reads its cell index
+//! at the bottom of the draw loop, an off-by-one that gives each mote the previous one's cell and
+//! slot 0 a hardcoded cell 8. The other deviations are [`GUST_REF_HZ`], [`ATLAS`] and
+//! [`cull_limits`].
 
 use bevy::prelude::*;
 
@@ -62,82 +26,49 @@ use crate::view::WorldCamera;
 
 use super::Underwater;
 
-/// Pool size — `count = __ftol(1.0 * [0x81038c])`, `[0x81038c] = 4000.0f`, and `0x68e650` has
-/// exactly **one** caller (the ctor, with that literal). No CVar, console command or quality tier
-/// scales it: 4000 is not a capacity, it is the population.
+/// The population, `[0x81038c] = 4000.0f` through `0x68e650`'s one caller; nothing scales it.
 const COUNT: usize = 4000;
 
-/// The wrap box's edge (`+0xfa1c`, ctor literal `30.0f`; `0x68e680` has one caller). The motes
-/// live in `[−15, +15)` per axis, camera-relative.
+/// The wrap box's edge (`+0xfa1c`, ctor `30.0f` via `0x68e680`): motes live in `[−15, +15)`.
 const BOX_EDGE: f32 = 30.0;
 const BOX_HALF: f32 = BOX_EDGE * 0.5;
 
-/// A camera jump this big in ONE frame re-scatters the field (`0x68e99a` loads the *extent*, not
-/// the half — and `last_cam` is rewritten every frame, so this is a per-frame delta). It is a
-/// teleport detector, not a box re-centre: the box re-centres for free via the `+= delta` term.
+/// A one-frame camera jump this long re-scatters the field (`0x68e99a` loads the edge, not half).
 const TELEPORT: f32 = BOX_EDGE;
 
-/// The per-particle scale base (`+0xfa18`), re-set per liquid class by `0x68e670`: `1/36` for
-/// water and ocean (`0x680b1d`), `1/9` for magma (`0x680b5c`). A mote's edge is drawn uniformly
-/// from `[base·0.5, base·1.5)`, so water motes are **1.4–4.2 cm** across and magma's 5.6–16.7 cm.
+/// The mote edge base (`+0xfa18`, set by `0x68e670`): `1/36` for water and ocean (`0x680b1d`),
+/// `1/9` for magma (`0x680b5c`). An edge is uniform in `[base·0.5, base·1.5)`.
 const SCALE_WATER: f32 = 1.0 / 36.0;
 const SCALE_MAGMA: f32 = 1.0 / 9.0;
 
-/// Gust frequency (`[0x807a4c]`) and amplitude (`[0x807a3c]`) unit scales; each is drawn as
-/// `m · scale` with `m ∈ [1,2)`, giving freq `[0.0125, 0.025)` and amp `[0.005, 0.01)`.
+/// Gust frequency (`[0x807a4c]`) and amplitude (`[0x807a3c]`) units: each roll is `m·unit`,
+/// `m ∈ [1, 2)`.
 const GUST_FREQ_UNIT: f32 = 0.0125;
 const GUST_AMP_UNIT: f32 = 0.005;
 
-/// The vertical squash on a freshly rolled gust direction (`[0x8029b0]`), applied **before**
-/// normalising.
-///
-/// It is a bias, **not a bound** — a correction to the RE note's first reading, checked at the
-/// difftested transcription and by Monte Carlo. `|z|/|xy| = 0.25·|cot a|` with `a` uniform on
-/// `[−π, π)`, so `atan(0.25) = 14.04°` is the **median** elevation (quartiles 5.9°/31.1°): about
-/// 15.6% of rolls are steeper than 45° and the limit as `a → 0` is straight up. The one hard
-/// constraint is the `fchs` at `0x68e27d`, which forces `z ≥ 0` — the gust never blows downward.
+/// The vertical squash on a rolled gust (`[0x8029b0]`), before normalising: a bias, not a bound
+/// (`atan(0.25)` is the median elevation). The `fchs` at `0x68e27d` keeps `z ≥ 0`.
 const GUST_RISE: f32 = 0.25;
 
-/// Magma's motion is not a gust at all: a true velocity of `0.02` yd/s **downward**
-/// (`[0x86a098]`), and the one mode that is `dt`-scaled in the reference.
+/// Magma sinks at `0.02` yd/s (`[0x86a098]`), the one mode the reference scales by `dt`.
 const MAGMA_SINK: f32 = -0.02;
 
-/// The frame rate the water gust is denominated in — **our deviation, and the whole of it.**
-///
-/// `0x68e4f0`'s `mode <= 1` leg writes `out = sin(term·2π)·amp·dir` and the advect adds it to the
-/// position **with no `dt` factor** (the RE round flagged this as load-bearing; only magma's leg
-/// multiplies by `dt`). So the reference's mote drift is frame-rate dependent: at **peak** of the
-/// half-sine, ~0.3 yd/s at 30 fps, ~0.6 at 60, and ~1.2 on the 120 Hz panel this is being built on
-/// — a gust's *mean* is `2/π` of that, so ~0.19–0.38 yd/s at 60. (Peak and mean are labelled here
-/// because the RE's own table shipped one as the other for a day; the ratio, which is what this
-/// constant is about, is the same either way.) There is no single faithful speed to port — the
-/// binary's own answer spans 2× across the era's hardware — so reproducing the literal per-frame
-/// step would not be "the reference's speed", it would be *this machine's*.
-///
-/// We take the top of the era's range, 60 Hz, and scale by `dt·60`. This is the same move as the
-/// snow flake's [`SNOW_PX_REF_HEIGHT`](crate::weather::precip): denominate the reference's
-/// frame-quantised number in the era's own units so the *behaviour* carries over to hardware it
-/// never ran on, rather than the literal number carrying over and the behaviour changing.
+/// Deviation: the water gust moves `speed·dt·60` a frame where the reference (`0x68e4f0`,
+/// `mode <= 1`) moves `speed` with no `dt`, because the reference's drift doubles from 30 to
+/// 60 fps; 60 Hz holds the top of the era's range at any frame rate.
 const GUST_REF_HZ: f32 = 60.0;
 
-/// The draw's own cap: `0x68f2cd` stops the fill at `0xa68` bytes = 2664 verts = **666 quads**.
-/// It is not arbitrary — a uniform 4000-particle cube contributes ~1/6 of itself to a 90° cone, so
-/// the cap is sized to the expected survivor count and almost never actually bites.
+/// The draw's cap: `0x68f2cd` stops the fill at `0xa68` = 2664 vertices, 666 quads, about the
+/// share of the cube inside the 90° cone, so it rarely bites.
 const SUBMIT_CAP: usize = 666;
 
 /// The atlas cell pitch, `[0x810334] = 51/256`.
 const CELL: f32 = 51.0 / 256.0;
 
-/// The `Textures\WaterPoop02.blp` atlas as `(column, row)` cells — the lattice the CRT initialiser
-/// `[0x68ebf0, 0x68efae)` fills, recovered by emulating it. Four columns per row, plus cell 8
-/// alone out at column 4 of row 0.
-///
-/// **Cell 12 is completed here and is not in the binary.** The initialiser's last store is
-/// `0x68efa5` and its `ret` is `0x68efae`, so cell 12 gets 6 of its 8 floats and its bottom-right
-/// corner keeps BSS zero — sampling UV `(0,0)` and smearing the sprite across the atlas diagonal.
-/// The magma row uses cell 12 for one mote in four, so a faithful port would ship a visible defect
-/// on a quarter of the motes in every lava pool. Writing it as the lattice plainly intends is the
-/// §3 call (implement the mechanism, not the quirk); 1814 records it.
+/// The `Textures\WaterPoop02.blp` atlas as `(column, row)` cells, as the CRT initialiser
+/// `[0x68ebf0, 0x68efae)` fills it: four columns per row, plus cell 8 alone at column 4 of row 0.
+/// Deviation: cell 12 is completed, because the initialiser's last store (`0x68efa5`) leaves its
+/// bottom-right corner at zero and one magma mote in four would smear across the atlas diagonal.
 const ATLAS: [(f32, f32); 13] = [
     (0.0, 0.0),
     (1.0, 0.0),
@@ -154,46 +85,31 @@ const ATLAS: [(f32, f32); 13] = [
     (3.0, 2.0),
 ];
 
-/// Which atlas cells a mode draws from (`[0x86a0a0]`): water and ocean cycle cells 0–7, magma
-/// cycles 9–12.
+/// The atlas cells a mode draws from (`[0x86a0a0]`): water and ocean cycle 0–7, magma 9–12.
 const CELLS_WATER: [usize; 8] = [0, 1, 2, 3, 4, 5, 6, 7];
 const CELLS_MAGMA: [usize; 8] = [9, 10, 11, 12, 9, 10, 11, 12];
 
-/// The cull's per-axis tangent limits — the reference's cone, floored at the frustum.
-///
-/// `0x68f1c9` culls to `vz > 0 && |vx| < vz && |vy| < vz`: a fixed **90° cone** about the view
-/// axis, not the real frustum, and it is what sizes [`SUBMIT_CAP`]. At every aspect the reference
-/// shipped for, that cone comfortably contains the view — 4:3 with its ~44.1° vertical fov puts
-/// the horizontal half-angle at 28.4°, a 16.6° margin — so the two never disagreed.
-///
-/// They do on a modern window. The horizontal half-fov reaches the cone's 45° at about **21:9**
-/// and passes it beyond: taken literally, a 32:9 monitor would show motes winking out in two
-/// vertical bands down the left and right edges of the screen. That is not a defect the reference
-/// has and it is not one worth importing, so the limit is the **wider** of the two. On 4:3 and
-/// 16:9 this is exactly the reference's cone and nothing changes; only an aspect the reference
-/// never ran at sees a difference, which is the same shape of call as [`GUST_REF_HZ`].
-///
-/// Vertically the cone always wins (`tan 22.5° = 0.414`), so the `max` there is a statement of
-/// that fact rather than a live term.
+/// The cull's per-axis tangent limits: the reference's fixed 90° cone about the view axis
+/// (`0x68f1c9`: `vz > 0 && |vx| < vz && |vy| < vz`), which sizes [`SUBMIT_CAP`]. Deviation: floored
+/// at the frustum, because the cone stops containing the view at about 21:9, and a wider window
+/// would lose motes in bands down its sides.
 fn cull_limits(fov_y: f32, aspect: f32) -> (f32, f32) {
     let ty = (fov_y * 0.5).tan();
     ((ty * aspect).max(1.0), ty.max(1.0))
 }
 
-/// One mote — the reference's 16-byte record exactly: a camera-relative position and the
-/// billboard's world edge length.
+/// One mote, the reference's 16-byte record: a camera-relative position and the billboard edge.
 #[derive(Clone, Copy, Default)]
 struct Mote {
     pos: Vec3,
     edge: f32,
 }
 
-/// Which liquid class the field is configured for. Slime is absent on purpose: its arm of the
-/// dispatch (`0x680b6f`) clears the enable byte and does **not** re-scatter — there are no motes
-/// in slime.
+/// The liquid class the field is configured for. Slime has no motes: its dispatch arm
+/// (`0x680b6f`) clears the enable byte without a re-scatter.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum DriftMode {
-    /// Liquid types 0 and 1 — water and ocean.
+    /// Liquid types 0 and 1, water and ocean.
     Water,
     /// Liquid type 2.
     Magma,
@@ -214,8 +130,7 @@ impl DriftMode {
         }
     }
 
-    /// Fog is enabled for magma alone (`0x68f36e` sets gx id `0x0f` to `mode == 2`). Water motes
-    /// burn at full brightness over the murk.
+    /// Fog is on for magma alone (`0x68f36e` sets gx id `0x0f` to `mode == 2`).
     fn fog(self) -> EffectFog {
         match self {
             DriftMode::Water => EffectFog::Off,
@@ -224,28 +139,24 @@ impl DriftMode {
     }
 }
 
-/// The mote field. One resource, allocated once (64 KB) and never resized — the reference builds
-/// its object at process init and tears it down at exit.
+/// The mote field, allocated once, as the reference's object lives from process init to exit.
 #[derive(Resource)]
 pub(super) struct DriftCloud {
     motes: Vec<Mote>,
     /// The camera position at the previous advect (`+0xfa04`).
     last_cam: Vec3,
-    /// `None` = the enable byte is clear: never configured, or slime.
+    /// `None`: the enable byte is clear (never configured, or slime).
     mode: Option<DriftMode>,
-    /// What [`Underwater`] said last frame — the reference compares the new liquid type against
-    /// `[0xc7f288]` and skips the whole reconfiguration when it is unchanged.
+    /// Last frame's [`Underwater`]; an unchanged liquid type skips reconfiguring (`[0xc7f288]`).
     was: Submersion,
     gust_dir: Vec3,
     gust_freq: f32,
     gust_phase: f32,
     gust_amp: f32,
     rng: u32,
-    /// `$WOW_NO_PARTICLES` — the family's perf-bisect kill switch (`particles.rs`,
-    /// `ribbons.rs`): one switch, whole family, and a mote field is squarely in it. Cached at
-    /// construction rather than read per frame.
+    /// `WOW_NO_PARTICLES`, the particle family's kill switch, read once.
     off: bool,
-    /// Instrument state — see [`dump`].
+    /// State for the [`dump`] instrument.
     dump: bool,
     dump_at: f64,
     submitted: usize,
@@ -263,9 +174,7 @@ impl Default for DriftCloud {
             gust_freq: GUST_FREQ_UNIT,
             gust_phase: 0.0,
             gust_amp: GUST_AMP_UNIT,
-            // Any odd seed: the reference's lagged-table generator is byte-known, but nothing here
-            // needs its exact stream — only uniformity (the `particles::emit` idiom, and the same
-            // ruling `weather::precip::rand01` carries).
+            // Any odd seed: only uniformity matters, not the reference generator's exact stream.
             rng: 0x9e37_79b9,
             off: std::env::var_os("WOW_NO_PARTICLES").is_some(),
             dump: std::env::var_os("WOW_DRIFT_DUMP").is_some(),
@@ -277,8 +186,7 @@ impl Default for DriftCloud {
 }
 
 impl DriftCloud {
-    /// Scatter every mote uniformly through the box and redraw its edge — `0x68e720`. Called on a
-    /// liquid-type change and on a teleport, never per frame and never per mote at the wrap.
+    /// Scatter the field and redraw each edge (`0x68e720`): on a liquid-type change or a teleport.
     fn scatter(&mut self, mode: DriftMode) {
         let base = mode.scale_base();
         let lo = base * 0.5;
@@ -297,9 +205,7 @@ impl DriftCloud {
         self.mode = Some(mode);
     }
 
-    /// Roll a fresh gust — `0x68e1c0`. Two uniform angles on `[−π, π)`; the vertical term is
-    /// squashed by [`GUST_RISE`] and forced non-negative before the direction is normalised, then
-    /// a fresh period and amplitude.
+    /// Roll a fresh gust direction, period and amplitude (`0x68e1c0`).
     fn roll_gust(&mut self) {
         let mut rng = self.rng;
         let angle = |r: &mut u32| (rand01(r) * 2.0 - 1.0) * std::f32::consts::PI;
@@ -314,30 +220,28 @@ impl DriftCloud {
         self.rng = rng;
     }
 
-    /// This frame's whole-field displacement — `0x68e4f0`.
+    /// This frame's whole-field displacement (`0x68e4f0`).
     fn gust(&mut self, mode: DriftMode, dt: f32) -> Vec3 {
         match mode {
             DriftMode::Magma => Vec3::new(0.0, MAGMA_SINK * dt, 0.0),
             DriftMode::Water => {
                 self.gust_phase += dt;
                 let mut term = self.gust_phase * self.gust_freq;
-                // Strictly greater (`0x68e542 test ah,0x41; jne`): the period runs 20 s at the
-                // fastest frequency to 40 s at the slowest, and `sin(term·2π)` over `[0, 0.5]` is a
-                // non-negative half-sine — the gust swells from nothing to a peak and back, then
-                // takes a new direction.
+                // Strictly greater (`0x68e542`): each gust is one non-negative half-sine over 20
+                // to 40 s, then a new roll.
                 if term > 0.5 {
                     self.roll_gust();
                     term = 0.0;
                 }
                 let speed = (term * std::f32::consts::TAU).sin() * self.gust_amp;
-                // The one deviation: `· dt · 60` where the reference has no `dt` at all.
+                // The `GUST_REF_HZ` deviation: the reference has no `dt` here.
                 self.gust_dir * (speed * dt * GUST_REF_HZ)
             }
         }
     }
 
-    /// Advance the field — `0x68e930`. Because the records are camera-relative and `delta` is the
-    /// camera's *backwards* step, the cloud stands still in the world; only the gust moves it.
+    /// Advance the field (`0x68e930`): `delta` is the camera's backward step, so the
+    /// camera-relative cloud stands still in the world and only the gust moves it.
     fn advect(&mut self, mode: DriftMode, eye: Vec3, dt: f32) {
         let mut delta = self.last_cam - eye;
         self.last_cam = eye;
@@ -367,7 +271,7 @@ impl DriftCloud {
     }
 }
 
-/// The mote texture. One BLP, loaded once with the world's first camera.
+/// The mote texture, loaded with the world's first camera.
 #[derive(Resource)]
 struct DriftAssets {
     motes: Handle<Image>,
@@ -382,12 +286,8 @@ fn setup_drift(
     if existing.is_some() || cam.single().is_err() {
         return;
     }
-    // `PointSprite` — clamp, the gamma lane, and the BLP's **authored mip pyramid**. A mote is
-    // 1.4–4.2 cm wide and lives out to 26 yd, which on this projection is ~87 px at arm's length
-    // down to ~3 px at the box corner: a 17× minification of a 51 px atlas cell. Mip-0-only there
-    // is the snow flake's flickering speckle (`BlpVariant::Effect`'s docs), not crispness. The
-    // cost is that the deep mips blend neighbouring cells — which the reference pays too, having
-    // shipped the same atlas with the same 8 mips and bound it with the same filtering.
+    // `PointSprite`: clamp, the gamma lane and the BLP's authored mips, bound as the reference
+    // binds this atlas; mip 0 alone would flicker at the motes' up-to-17× minification.
     let point_sprite = |s: &mut benilla_assets::BlpLoaderSettings| {
         s.variant = benilla_assets::BlpVariant::PointSprite;
     };
@@ -396,8 +296,8 @@ fn setup_drift(
     });
 }
 
-/// Reconfigure on a liquid-class change, then advect — the reference's update-pass leg
-/// (`0x66fee0` → `0x68e930`), with `0x6809c0`'s type dispatch folded in ahead of it.
+/// Reconfigure on a liquid-class change, then advect: the reference's update leg (`0x66fee0` →
+/// `0x68e930`), with `0x6809c0`'s type dispatch folded in ahead of it.
 fn simulate_drift(
     mut cloud: ResMut<DriftCloud>,
     underwater: Res<Underwater>,
@@ -412,14 +312,12 @@ fn simulate_drift(
     if now != cloud.was {
         cloud.was = now;
         match now {
-            // Going dry does NOT clear the enable byte — `0x680abe` intercepts `0xf` before the
-            // type dispatch, so the field keeps its configuration and is suppressed by the frame
-            // gate alone. Diving back into the same liquid therefore finds it exactly as it was.
+            // Going dry keeps the configuration: `0x680abe` intercepts `0xf` before the type
+            // dispatch, and the frame gate alone hides the field.
             Submersion::Dry => {}
             // Slime disables outright, with no re-scatter (`0x680b6f`).
             Submersion::Slime => cloud.mode = None,
-            // Water and ocean share the drift cloud's whole configuration — the mote cell set is
-            // keyed on liquid types 0 AND 1 (`[0x86a0a0]`), so the sea drifts exactly like a lake.
+            // One configuration: the cell set is keyed on liquid types 0 and 1 (`[0x86a0a0]`).
             Submersion::Water | Submersion::Ocean => {
                 cloud.scatter(DriftMode::Water);
                 cloud.last_cam = eye;
@@ -430,11 +328,8 @@ fn simulate_drift(
             }
         }
     }
-    // The frame gate's second conjunct. (The first, the render-flag bit `0x2000000`, is the
-    // `waterParticulates` console command's latch — default ON, a plain on/off that scales
-    // nothing, and not a CVar at all: it is registered through the developer-console table
-    // `0x63f9e0`, has no `CVar::Register` site and no `Config.wtf` persistence. Nothing here
-    // wires it, exactly as nothing wires `showfootprints`.)
+    // The frame gate's second conjunct; the first, render-flag `0x2000000`, is the unwired
+    // `waterParticulates` console latch (default on, console table `0x63f9e0`, not a CVar).
     if !now.any() || cloud.off {
         return;
     }
@@ -444,8 +339,7 @@ fn simulate_drift(
     cloud.advect(mode, eye, time.delta_secs());
 }
 
-/// Emit the surviving motes into the shared effect stream — the reference's render-pass leg
-/// (`0x6701e0` → `0x68efe0`).
+/// Emit the surviving motes into the effect stream: the render leg (`0x6701e0` → `0x68efe0`).
 fn push_drift(
     mut cloud: ResMut<DriftCloud>,
     underwater: Res<Underwater>,
@@ -455,12 +349,9 @@ fn push_drift(
     time: Res<Time>,
 ) {
     cloud.submitted = 0;
-    // Every exit yields a REASON rather than returning, so the instrument can say why nothing drew.
-    // A census that goes silent when the thing is off cannot tell "off" from "broken" — which is
-    // exactly the hole the first live probe of this module fell into.
+    // Every exit yields a reason, so the instrument tells "off" from "broken".
     let status: &'static str = 'draw: {
-        // The same two conjuncts as the advect — the draw is independently gated, not a consequence of
-        // the sim having run.
+        // The advect's two conjuncts again: the draw is gated on its own, not on the sim.
         if !underwater.0.any() {
             break 'draw "dry (the eye is not in a liquid)";
         }
@@ -478,7 +369,7 @@ fn push_drift(
         };
         let (tan_x, tan_y) = match proj {
             Projection::Perspective(p) => cull_limits(p.fov, p.aspect_ratio),
-            // No perspective divide, so the cone means nothing; the reference has no such mode.
+            // No perspective, so no cone; the reference has no such mode.
             _ => (1.0, 1.0),
         };
         let eye = cam_tf.translation();
@@ -493,7 +384,6 @@ fn push_drift(
             if submitted == SUBMIT_CAP {
                 break;
             }
-            // The reference's cone, floored at the frustum — see [`cull_limits`].
             let rel = m.pos;
             let vz = rel.dot(fwd);
             if vz <= 0.0 {
@@ -507,9 +397,7 @@ fn push_drift(
             let half = m.edge * 0.5;
             let r = right * half;
             let u = up * half;
-            // Perimeter order (bl, br, tr, tl) — the stream's quad-index pattern closes it. The
-            // vertices are camera-RELATIVE (`cam_relative` below), which is what the record already
-            // holds; the reference does the same thing by handing the device only the projection.
+            // Perimeter order (bl, br, tr, tl), camera-relative as the records are.
             for (pos, uv) in [
                 (rel - r - u, [u0, v0 + CELL]),
                 (rel + r - u, [u0 + CELL, v0 + CELL]),
@@ -519,8 +407,7 @@ fn push_drift(
                 quads.verts.push(EffectVertex {
                     pos: pos.to_array(),
                     uv,
-                    // The colour is an immediate `0xFFFFFFFF` in the binary (`0x68f27b`): not
-                    // per-particle, not a global, and with no distance or depth fade.
+                    // An immediate `0xFFFFFFFF` (`0x68f27b`): no per-mote colour, no fade.
                     color: [1.0, 1.0, 1.0, 1.0],
                 });
             }
@@ -531,9 +418,8 @@ fn push_drift(
             EffectDrawSpec {
                 cam: cam_entity,
                 texture: assets.motes.id(),
-                // `SRC_ALPHA / ONE_MINUS_SRC_ALPHA` (gx id 7 = 2). The cascading alpha test at
-                // `GEQUAL 1/255` needs no lane of its own — under this blend a zero-alpha fragment
-                // already contributes nothing.
+                // `SRC_ALPHA / ONE_MINUS_SRC_ALPHA` (gx id 7 = 2), depth write off (id 0x12 = 0),
+                // as this lane draws; the `GEQUAL 1/255` alpha test adds nothing under this blend.
                 blend: EffectBlend::Alpha,
                 fog: mode.fog(),
                 lighting: EffectLighting::None,
@@ -557,14 +443,8 @@ fn push_drift(
     dump(&mut cloud, status, &time);
 }
 
-/// `$WOW_DRIFT_DUMP` — a 1 Hz line, because every question this field raises is numeric and none
-/// of them is answerable from a screenshot. `submitted` against [`SUBMIT_CAP`] says whether the cap
-/// is biting; `wrapped` is the recycle rate, which is the drift speed made visible; the gust block
-/// is the only state with a 20–40 s clock on it, so a stuck gust shows here and nowhere else.
-///
-/// **It reports when nothing draws, too, and that is the point.** The first live probe of this
-/// module printed no lines at all, which was indistinguishable between "the eye never went under"
-/// and "the draw is broken" — so `status` names the gate that stopped it.
+/// `WOW_DRIFT_DUMP`: a 1 Hz line with the draw's status (the gate that stopped it, if any), the
+/// submitted count against [`SUBMIT_CAP`], the wrap count and the gust state.
 fn dump(cloud: &mut DriftCloud, status: &'static str, time: &Time) {
     if !cloud.dump {
         return;
@@ -601,11 +481,8 @@ pub(super) fn register(app: &mut App) {
             Update,
             (
                 setup_drift,
-                // `CameraPoseSet` as well as the verdict: the advect's whole input is
-                // `last_cam − cam`, and for the length of `Update` a camera's `GlobalTransform` is
-                // last frame's pose unless you order after the set that refreshes it (1503). Read
-                // stale, a teleport's jump would land in `delta` a frame late — as a 30 yd shove
-                // through the field instead of the re-scatter it is.
+                // After `CameraPoseSet` too: until it runs, a camera's `GlobalTransform` is last
+                // frame's, and a stale pose turns a teleport's re-scatter into a shove.
                 simulate_drift
                     .after(super::SubmersionVerdict)
                     .after(crate::view::CameraPoseSet)
@@ -649,8 +526,7 @@ mod tests {
                     base * 1.5
                 );
             }
-            // A scatter that filled the box would still be wrong if it filled it in a corner: the
-            // mean of a uniform cube is the centre, and 4000 samples put it well inside 1 yd.
+            // Centred too: 4000 uniform samples put the mean well inside 1 yd of the centre.
             let mean: Vec3 = c.motes.iter().map(|m| m.pos).sum::<Vec3>() / COUNT as f32;
             assert!(mean.length() < 1.0, "scatter is not centred: mean {mean:?}");
         }
@@ -660,8 +536,6 @@ mod tests {
     fn the_wrap_keeps_every_mote_inside_the_box() {
         let mut c = cloud(DriftMode::Water);
         let mut eye = Vec3::ZERO;
-        // Walk the camera a long way in small steps — every step pushes motes out of the far face,
-        // and the wrap is the only thing bringing them back.
         for _ in 0..500 {
             eye += Vec3::new(0.4, 0.05, -0.3);
             c.advect(DriftMode::Water, eye, 1.0 / 60.0);
@@ -679,8 +553,7 @@ mod tests {
         let world_before: Vec<Vec3> = c.motes.iter().map(|m| m.pos).collect();
         let eye = Vec3::new(3.0, -1.0, 2.0);
         c.advect(DriftMode::Water, eye, 1.0 / 60.0);
-        // `pos` is camera-relative, so a mote that stood still in the world must now read
-        // `old − eye` — unless it wrapped, which is a teleport in world space by design.
+        // A mote still in the world now reads `old − eye`, unless it wrapped.
         let mut checked = 0;
         for (m, was) in c.motes.iter().zip(&world_before) {
             let expect = *was - eye;
@@ -702,7 +575,6 @@ mod tests {
         let mut c = cloud(DriftMode::Water);
         c.gust_amp = 0.0;
         let before: Vec<Vec3> = c.motes.iter().map(|m| m.pos).collect();
-        // One frame, further than the box is wide.
         c.advect(
             DriftMode::Water,
             Vec3::new(0.0, 0.0, TELEPORT + 1.0),
@@ -715,8 +587,6 @@ mod tests {
             .zip(&before)
             .filter(|(m, b)| (m.pos - **b).length() > 1e-3)
             .count();
-        // A wrap would have translated the field rigidly; a re-scatter moves essentially all of it
-        // to independent places.
         assert!(
             moved > COUNT * 9 / 10,
             "only {moved} motes were re-scattered"
@@ -734,17 +604,13 @@ mod tests {
                 (d.length() - 1.0).abs() < 1e-4,
                 "gust dir is not a unit vector"
             );
-            // The `fchs` at `0x68e27d` — the one hard constraint on the direction.
             assert!(d.y >= 0.0, "the gust blew downward: {d:?}");
             elev.push(d.y.clamp(-1.0, 1.0).asin().to_degrees());
         }
         elev.sort_by(|a, b| a.partial_cmp(b).unwrap());
         let median = elev[elev.len() / 2];
         let steep = elev.iter().filter(|e| **e > 45.0).count() as f32 / elev.len() as f32;
-        // `atan(0.25)` is the MEDIAN elevation, not a bound — the RE note's first reading said
-        // "always within 14.04° of horizontal", which the formula does not support and this test
-        // exists to keep anyone from re-introducing as a clamp. Closed forms: median
-        // `atan(0.25) = 14.036°`, and `P(elev > 45°) = (2/π)·atan(0.25) = 0.156`.
+        // Closed forms: median `atan(0.25) = 14.036°`, `P(elev > 45°) = (2/π)·atan(0.25) = 0.156`.
         assert!(
             (median - 0.25f32.atan().to_degrees()).abs() < 1.0,
             "median elevation {median} is not atan(0.25)"
@@ -775,9 +641,6 @@ mod tests {
 
     #[test]
     fn the_water_gust_is_frame_rate_independent() {
-        // The deviation `GUST_REF_HZ` buys exactly this: the same wall-clock second of drift,
-        // whatever the frame rate. (The reference's own answer differs by 2× between 30 and 60 fps
-        // — see the constant's docs.)
         let travel = |steps: u32, dt: f32| {
             let mut c = DriftCloud::default();
             c.roll_gust();
@@ -791,16 +654,12 @@ mod tests {
         };
         let at30 = travel(30, 1.0 / 30.0);
         let at120 = travel(120, 1.0 / 120.0);
-        // 5%, not 0: the gust's half-sine envelope is being sampled, and a 30-step Riemann sum of
-        // a rising function differs from a 120-step one by O(dt). That residual is the envelope's
-        // shape, not the frame rate leaking into the speed.
+        // 5%, not 0: 30- and 120-step sums over the rising half-sine differ by O(dt).
         assert!(
             (at30 - at120).abs() / at30.abs().max(1e-6) < 0.05,
             "one second of drift: {at30} at 30 fps vs {at120} at 120 fps"
         );
-        // And this is what the normalisation is FOR: strip the `dt·60` back out — which is the
-        // reference's literal per-frame law — and the same second of wall clock moves the field
-        // four times further at 120 fps than at 30.
+        // Without the `dt·60`, the reference's per-frame law moves the field 4× further at 120 fps.
         let literal = |steps: u32, dt: f32| travel(steps, dt) / (dt * GUST_REF_HZ);
         let ratio = literal(120, 1.0 / 120.0) / literal(30, 1.0 / 30.0);
         assert!(
@@ -820,7 +679,6 @@ mod tests {
 
     #[test]
     fn the_atlas_is_a_complete_lattice_including_the_reference_s_truncated_cell() {
-        // Every cell is a distinct 51/256 tile, and no two cells overlap.
         let mut seen = std::collections::HashSet::new();
         for (col, row) in ATLAS {
             assert!(col >= 0.0 && row >= 0.0);
@@ -831,18 +689,13 @@ mod tests {
                 "duplicate atlas cell"
             );
         }
-        // Cell 12 is the one the reference leaves half-written (its bottom-right corner stays BSS
-        // zero and samples UV (0,0)). Ours is a real tile at column 3, row 2 — if this ever reads
-        // (0,0) again we have re-imported a shipped defect.
+        // Cell 12, half-written in the reference, is a real tile at column 3, row 2.
         assert_eq!(ATLAS[12], (3.0, 2.0));
-        // And it is reachable: magma draws it for one mote in four.
         assert!(CELLS_MAGMA.contains(&12));
     }
 
     #[test]
     fn the_cull_never_clips_a_mote_that_is_on_screen() {
-        // The invariant, at every aspect a window can have: the cull limit is at least the
-        // frustum's, so nothing visible is dropped.
         for aspect in [4.0 / 3.0, 16.0 / 10.0, 16.0 / 9.0, 21.0 / 9.0, 32.0 / 9.0] {
             let (tx, ty) = cull_limits(crate::view::CAM_FOVY, aspect);
             let frustum_x = (crate::view::CAM_FOVY * 0.5).tan() * aspect;
@@ -856,19 +709,13 @@ mod tests {
                 "aspect {aspect}: cull {ty} < frustum {frustum_y}"
             );
         }
-        // ...and on the aspects the reference actually ran at, the limit IS its 90° cone — the
-        // widening is inert there, so `SUBMIT_CAP`'s sizing still holds where it was derived.
+        // At the aspects the reference ran at, the limit is its 90° cone exactly.
         assert_eq!(cull_limits(crate::view::CAM_FOVY, 4.0 / 3.0), (1.0, 1.0));
         assert_eq!(cull_limits(crate::view::CAM_FOVY, 16.0 / 9.0), (1.0, 1.0));
-        // Ultrawide is where it bites, and it bites horizontally only.
         let (tx, ty) = cull_limits(crate::view::CAM_FOVY, 32.0 / 9.0);
         assert!(tx > 1.0 && ty == 1.0);
     }
 
-    /// The perf gate, and it is structural rather than measured: a dry frame must commit **no
-    /// draw and no vertex**. The effect lane charges per submitted vertex, so "costs nothing when
-    /// you are not underwater" is a property of this assertion, not of a frame-rate reading on
-    /// whatever the machine was doing that afternoon (the 0353 law).
     #[test]
     fn a_dry_frame_commits_nothing() {
         use bevy::ecs::system::RunSystemOnce;
@@ -888,8 +735,7 @@ mod tests {
             Projection::default(),
         ));
 
-        // Dry: the field is configured and the texture is present, so the ONLY thing stopping the
-        // draw is the gate.
+        // Configured and textured, so only the gate stops the draw.
         world.insert_resource(Underwater(Submersion::Dry));
         world.run_system_once(push_drift).unwrap();
         {
@@ -898,8 +744,7 @@ mod tests {
             assert!(q.verts.is_empty(), "a dry frame pushed vertices");
         }
 
-        // Submerged: the same world, one resource different, and now it draws — so the assertion
-        // above is about the gate and not about a fixture that could never draw at all.
+        // The control: submerged, the same world draws.
         world.insert_resource(Underwater(Submersion::Water));
         world.run_system_once(push_drift).unwrap();
         {
@@ -923,8 +768,7 @@ mod tests {
         // Slime's arm clears the enable byte outright.
         c.mode = None;
         assert!(c.mode.is_none());
-        // ...while going dry leaves it alone: the reference intercepts `0xf` ahead of the type
-        // dispatch, so surfacing and diving again finds the same field.
+        // Going dry leaves the field as it was.
         let mut c = cloud(DriftMode::Water);
         let before: Vec<Vec3> = c.motes.iter().map(|m| m.pos).collect();
         c.was = Submersion::Dry;
diff --git a/crates/benilla-world/src/liquid/mod.rs b/crates/benilla-world/src/liquid/mod.rs
index 17a6dd76..fec0aec9 100644
--- a/crates/benilla-world/src/liquid/mod.rs
+++ b/crates/benilla-world/src/liquid/mod.rs
@@ -1,98 +1,28 @@
-//! Liquid (water) rendering: the animated lake/river/ocean surfaces the reference draws over MCLQ
-//! geometry. The parse + flat mesh live in `benilla_formats::liquid` (built into each `ChunkMesh.liquid`
-//! by the terrain loader); this is the Bevy render glue — one shared [`LiquidMaterial`] per
-//! [`LiquidKind`], a `texture_2d_array` of its animated frames, and a 24 fps frame-index cycler.
+//! Liquid: the animated surfaces (`surface`), where the liquid is and whether a subject or the
+//! camera eye is in it (`query`, indexed by `spatial`), and the underwater drift cloud (`drift`).
+//! The MCLQ parse and flat mesh are `benilla_formats::liquid`; the shading is `liquid.wgsl`.
 //!
-//! **This is the ADT path, and we render WMO liquid through it too — which is wrong.** The reference
-//! has three liquid renderers, not one: ADT MCLQ (below), WMO MLIQ water (`0x6b62e0` category 0,
-//! split again into exterior `0x6b6630` / interior `0x6b6420` on the group's `MOGP.flags & 0x48` —
-//! one texture stage, no depth ramp, alpha from a per-vertex authored byte), and magma/slime. The
-//! `wmo_liquid_arms` census sizes them: 30 exterior water groups (Stormwind's canals) against 134
-//! interior (every dungeon pool, Blackfathom's included). Neither is what this file implements.
-//! Recorded in wow-re `terrain/scratch/water-shading-law.md`.
+//! The reference has three liquid renderers, each with its own arm in the shader: ADT MCLQ, WMO
+//! MLIQ water (`0x6b62e0` category 0, exterior `0x6b6630` or interior `0x6b6420` by the group's
+//! `MOGP.flags & 0x48`: one texture stage, no depth ramp, alpha from a per-vertex authored byte)
+//! and magma/slime.
 //!
-//! Faithful ADT model — the combiner is an **asset**, extracted from `patch.MPQ` and read, not
-//! inferred: `Shaders\Pixel\ocean0_s.bls` is `rgb = primary·colorTex.rgb + detailTex.rgb +
-//! (secondary+0.25)·detailTex.a`, `alpha = colorTex.a`, with `0.25` its own scalar `PARAM`. The
-//! formula this module has always carried is right verbatim; its **provenance was not** — the
-//! citation here used to name an "apitrace WoW.17 program 159" and a `docs/knowledge/terrain.md`,
-//! neither of which exists, and wow-re had the program attributed to a character draw. The body
-//! colour is **`primary · waterTint`**, where:
-//! - **`waterTint`** is a **64-row byte-space ramp** between the zone's dedicated `Light.dbc` water
-//!   rows, RAW (no ×0.711): IntBand rows 16/17 (river/lake) or 14/15 (ocean), shallow→deep, by the
-//!   per-vertex depth `V` (river/lake `V = clamp(byte/42)`, VERIFIED `c81768`/`FUN_0068d790`; saturates
-//!   ~5 yd so the channel middle reaches the deep/teal row). `FUN_0068a830` builds it as an exact
-//!   integer accumulator — `row(i) = c0 + floor(i·(c1−c0)/64)`, `i = 0..63` — so it **never reaches
-//!   the deep endpoint**, and it is sampled LINEAR/CLAMP at texel `V·64 − 0.5`. **The ocean's last
-//!   row alone is then darkened** `floor(0.9·byte)` per channel (an HSV `V ×= 0.9` that reduces to
-//!   exactly that) with its alpha forced opaque — and ~80 % of the world's ocean vertices sample
-//!   that one row, so it is the open sea's actual colour (decision 2074). The swatch is rebuilt **per world frame**,
-//!   not baked once at bootstrap: the dirty flags `[0xc8117c]`/`[0xc81b70]` clear at
-//!   `0x680b90`/`0x680b97` and refill via `0x58acd0`, so colour and opacity track the zone and the
-//!   clock. (The earlier "reflected sky × 0.711 via `FUN_0068c250`" model fingered the WRONG builder —
-//!   a separate grey edge texture never bound on the water unit; and `byte/255` was the wrong LUT →
-//!   river never went teal. The `FUN_0068a830` attribution this line used to carry was also wrong:
-//!   wow-re reads `0x68a830` as a sky-band row fill.)
-//! - **`primary`** is the lit vertex colour `clamp(ambient + N·L·sun)`.
-//! - the animated `lake_a`/`ocean_h` frame is the **`detailTex`** (near-black RGB + ripple alpha): a
-//!   faint flat lift + an achromatic shimmer on crests — NOT the body colour. Mipped + 16× aniso so the
-//!   ripple averages out at distance (near-field samples mip 0, so near sparkle is the term itself).
-//! - **opacity** = the SAME `V` indexes both colour and alpha (one swatch row → RGB + A): the same
-//!   64-row ramp between
-//!   the LightParams shallow/deep alphas — river 0.5→1.0, ocean 0.75→1.0. The river channel reaches
-//!   α=1.0 (opaque, deep teal) by byte 42 ≈ 5 yd; the shore stays see-through (the pale edge band —
-//!   the bottom shows). The linear ramp is right, and `0xc7fbc0`'s `1.6·(i/63)^8` — which this line
-//!   used to flag as a competing reading — is **not on this path at all**: its only consumer is
-//!   `0x68c250` (via `0x68c4a0`) building the separate texture `[0xc7fbb8]`, bound at `0x685257`
-//!   inside a branch proven **dead** (`[0xc800ec]` is BSS whose only writer stores 0 and which is
-//!   never a `0x58b2b0` out-param target, so both arms are controlled). It is the sky/overlay glare
-//!   falloff, not a liquid opacity curve. The swatch's alpha column is the same endpoint lerp its RGB
-//!   is (`0x68a830`). VERIFIED, wow-re's §5 ocean round — `terrain/scratch/ocean-depth-ramp-law.md`.
+//! The ADT combiner is the asset `Shaders\Pixel\ocean0_s.bls` in `patch.MPQ`:
+//! `rgb = primary·colorTex.rgb + detailTex.rgb + (secondary + 0.25)·detailTex.a`,
+//! `alpha = colorTex.a`. `primary` is the lit vertex colour `clamp(ambient + N·L·sun)`;
+//! `detailTex` is the animated `lake_a`/`ocean_h` frame, near-black RGB and a ripple alpha.
+//! `colorTex` is a 64-row swatch, RGB between the zone's raw `Light.dbc` water rows (IntBand 16/17
+//! river/lake, 14/15 ocean) and alpha between its `LightParams` shallow and deep alphas, filled by
+//! `0x68a830` as `row(i) = c0 + floor(i·(c1−c0)/64)`, so it never reaches the deep endpoint. The
+//! ocean's last row alone is darkened by an HSV `V ×= 0.9` and forced opaque; about 80% of ocean
+//! vertices sample it. The dirty flags `[0xc8117c]`/`[0xc81b70]` clear every world frame
+//! (`0x680b90`/`0x680b97`, refill `0x58acd0`), so colour and opacity track the zone and the clock.
 //!
-//! **Each kind reads its own depth LUT, and both are verified** — `FUN_0068c4c0` builds them side by
-//! side and the two vert-fills read them the same way, `tc0 = (0.5, ramp[depthByte])`: river/lake
-//! `c81768 = min(d/42, 1)` (`FUN_0068d790`, `fld` @`0x68d818`), ocean `c7fcd8 = min(d/255, 1)`
-//! (`FUN_0068d690`, `fld` @`0x68d718`). Putting the river's `/42` on a river was the 2026-05-31 fix;
-//! the ocean's `/255` was never the same mistake, and calling it a placeholder was ours, not the
-//! binary's — `0x68d890`, the address that claim rested on, is the **magma** vert-fill (authored
-//! per-vertex texcoords × 3/256), as `benilla_adt::LiquidVertex::texcoords` has always said.
-//! The two divisors differ because the two authored depth bytes do: measured over every MCLQ block in
-//! Azeroth + Kalimdor, the sea's byte ramps **1.72 byte/yd** against a river's **8.96**, so `/255`
-//! saturates at ~148 yd of depth and `/42` at ~4.7 yd — within ~15 % of each other in yards per unit
-//! of V — and 83.4 % of ocean vertices are pinned at byte 255 outright, so the open sea is authored
-//! fully deep and the ramp is a shore band. Decision 2069;
-//! `benilla-formats::examples::liquid_depth_census` is the instrument, `WOW_OCEAN_DEPTH_DIV` the A/B.
-//! (Earlier cuts: ripple-as-colour → black; `×8` → "deep too early"; FLAT colour → "completely gone";
-//! sky × 0.711 → wrong builder; `byte/255` on the RIVER → wrong LUT, no teal centre. Faithful =
-//! rows 14–17 raw lerp + the /42 V on rivers, the /255 V on the sea.)
-//!
-//! Two-sided, alpha-blended, depth-write off (Bevy's transparent pass = the verified MCLQ water render
-//! state).
-//!
-//! The frame-flip is the client's first render animation — a deliberate **one-off** (a frame-index
-//! uniform off Bevy real `Time`), NOT a general animation system. Two clocks: animation =
-//! wall-clock; day/night = server game-time.
-
-//! ## Layout
-//!
-//! Three concerns, so three files behind this face:
-//!
-//! * [`query`] — **where the liquid is, and whether you are in it.** The world-space grid every
-//!   surface publishes ([`WaterChunkInfo`]), the position queries the swim/sound/foam/lighting
-//!   systems ask it ([`liquid_at`], [`water_surface_at`]), and the per-frame camera submersion
-//!   verdict ([`Underwater`]). Nothing here renders.
-//! * [`spatial`] — **which surfaces are near an XY**, without walking them all: the grid-hash
-//!   [`WaterIndex`] the per-draw consumers (the water-plane interleave's three lanes) pre-filter
-//!   through. The once-a-frame askers keep the plain walk.
-//! * [`surface`] — **the Bevy render glue.** The per-kind animated materials, the two spawn paths
-//!   (MCLQ and WMO MLIQ), the flat mesh build, and the 24 fps frame cycler.
-//! * [`drift`] — **the underwater drift cloud**: the 4000-mote field the reference draws while the
-//!   camera eye is inside a liquid (decision 1814). It is here rather than under `weather` because
-//!   the reference keeps it that way too — the pool is CWorld's, not the weather manager's, and
-//!   the two share no state and no code — and because [`Underwater`] is its whole trigger.
-//!
-//! The one cross-feed runs query → lighting: `detect_submersion` publishes WHICH liquid the eye is
-//! in, and `lighting::update_time_lighting` selects the whole submerged atmosphere from it.
+//! One per-vertex depth `V` indexes colour and alpha alike: `min(byte/42, 1)` on river/lake
+//! (`0xc81768`, read at `0x68d818` by `0x68d790`), `min(byte/255, 1)` on ocean (`0xc7fcd8`, read
+//! at `0x68d718` by `0x68d690`), both tables built by `0x68c4c0`. `0xc7fbc0`'s `1.6·(i/63)^8` is no
+//! water alpha: it fills the sky glare texture `[0xc7fbb8]` (`0x68c250` via `0x68c4a0`), whose one
+//! liquid binding, `0x685257`, sits in a branch that never runs (`[0xc800ec]` is only ever 0).
 
 use bevy::pbr::MaterialPlugin;
 use bevy::prelude::*;
@@ -110,14 +40,7 @@ mod spatial;
 mod surface; // the against-real-client-files tests — they span both halves
 pub mod waves;
 
-// The submodules are private, so this list IS the subsystem's face: everything the rest of the
-// client may name. Most of this list is now reached through `crate::world_point::WorldPoint`
-// rather than directly (decision 1164).
-//
-// `LiquidSurface` used to be deliberately absent — "spawned, never named from outside; add it here
-// the day something needs it". Decision 1652 is that day: the exterior-window cull counts liquid
-// apart from the rest of the scene, because a few dozen surfaces summed into tens of thousands of
-// terrain cells is a leg that could reach nothing at all and never show it.
+// The submodules are private: this list is everything the rest of the client may name.
 pub use query::{
     camera_claim, describe_at, liquid_at, player_claim, surfaces_at, unit_claim, water_surface_at,
     EyeLiquid, FoamPatch, LiquidClaim, LiquidHit, LiquidSource, RoomPlacements, SubmergedEye,
@@ -128,17 +51,8 @@ pub(crate) use surface::{
     spawn_liquids, spawn_wmo_liquids, LiquidAssets, LiquidSoundSource, LiquidSurface,
 };
 
-/// `WOW_FORCE_SUB=<frames>` — **hold the camera-eye verdict submerged for the first `<frames>`
-/// frames, then release it.** The surfacing crossing on demand, with no server, no swim and no
-/// water under the camera: everything that forks on the verdict (the atmosphere, the sky and
-/// cloud domes' gates, the drift cloud, the FFX haze and warp) takes the wet→dry edge on a frame
-/// this names, so a transition artefact can be photographed or logged deterministically inside
-/// the capture harness (`WOW_CAPTURE=<scenario>`).
-///
-/// Built for B354 (decision 2032), where the whole defect lived in the ONE frame after the edge
-/// and the reported spot was a dusk swim off the Savage Coast — a place a screenshot harness
-/// cannot get to and a bug a still frame cannot catch. It reproduced in `water-noon` in one
-/// command.
+/// `WOW_FORCE_SUB=<frames>`: hold the camera-eye verdict submerged for the first `<frames>` frames,
+/// then release it, so the wet-to-dry crossing lands on a known frame with no water or server.
 fn forced_submersion_frames() -> u32 {
     std::env::var("WOW_FORCE_SUB")
         .ok()
@@ -146,9 +60,8 @@ fn forced_submersion_frames() -> u32 {
         .unwrap_or(0)
 }
 
-/// The [`forced_submersion_frames`] override, applied after the real probe so it overwrites a
-/// genuine verdict rather than racing it. Prints the release frame, which is the frame every
-/// crossing artefact is read against. Registered only when the env names a hold.
+/// The [`forced_submersion_frames`] override, run after the real probe so it overwrites the
+/// verdict rather than racing it; logs the release frame.
 fn force_submersion(mut underwater: ResMut<Underwater>, mut frame: Local<u32>) {
     let hold = forced_submersion_frames();
     *frame += 1;
@@ -162,18 +75,13 @@ fn force_submersion(mut underwater: ResMut<Underwater>, mut frame: Local<u32>) {
     }
 }
 
-/// The frame slot where [`Underwater`] is written — the label every consumer of the submersion
-/// verdict orders itself `.after(..)`. The submerged view is a whole-screen swap (atmosphere, clear
-/// colour, and the sky-pass suppression all flip on it), so a consumer reading a frame-old verdict
-/// shows one mixed frame on every surface crossing — the murk with the sun still up, or clear water
-/// with the sky already gone. One label, so the "same frame" contract is written once instead of
-/// re-derived per consumer.
+/// The set that writes [`Underwater`]; every consumer of the verdict runs after it, since a
+/// frame-old verdict shows one mixed frame (murk with the sky still up) on every surface crossing.
 #[derive(bevy::ecs::schedule::SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub(crate) struct SubmersionVerdict;
 
-/// The water subsystem: load the per-kind frame arrays + shared materials at startup, then cycle the
-/// animation frame each update. Spawning the per-chunk surfaces happens in the terrain streamer (via
-/// [`spawn_liquids`], water lives *with* its tile), reading [`LiquidAssets`].
+/// The liquid subsystem: the shared materials at startup, the submersion verdict and the drift
+/// cloud each frame. The terrain streamer spawns the surfaces with their tile ([`spawn_liquids`]).
 pub(crate) struct LiquidPlugin;
 
 impl Plugin for LiquidPlugin {
@@ -185,34 +93,21 @@ impl Plugin for LiquidPlugin {
             .init_resource::<Underwater>()
             .init_resource::<SubmergedEye>()
             .init_resource::<WaterIndex>()
-            // PreUpdate: surfaces stream in/out via Update-side commands, so the edge is visible
-            // here the frame after — before any of that frame's consumers ask. A despawn's stale
-            // entry in between self-filters at the consumer (`Query::get` misses).
+            // PreUpdate: a surface streamed by last frame's commands is indexed before anyone asks.
             .add_systems(PreUpdate, maintain_water_index)
             .add_systems(Startup, surface::setup_liquid.after(AssetSet::Open))
             .add_systems(
                 Update,
                 (
-                    // AFTER the portal pass, which publishes the camera eye's room this frame
-                    // (`CameraInteriorClaim`): the submersion verdict is the eye's room applied to
-                    // the eye's position, and a frame-old room would flash the wrong atmosphere for
-                    // one frame on every doorway crossing — which, for a whole-screen filter, is
-                    // exactly the artefact that reads worst.
+                    // After the portal pass publishes this frame's `CameraInteriorClaim`: a
+                    // frame-old room flashes the wrong atmosphere on every doorway crossing.
                     query::detect_submersion
                         .after(crate::wmo_portal::WmoPvsSet)
                         .in_set(SubmersionVerdict),
                 ),
             )
-            // The surface-render kill-switch (see [`hide_liquid_surfaces`]) — inert without the env
-            // var, so it costs nothing when it isn't being used.
-            //
-            // `PostUpdate`, after the two systems that now own a liquid surface's `Visibility`
-            // every frame — the exterior-window cull (ADT surfaces, decision 1652) and the
-            // model-visibility authority (WMO pools, 0689/0784) — and before Bevy consumes the
-            // result. An *override* that runs last, deliberately, rather than a second writer
-            // trying to compose with them (decision 0025's law, and 0784's reasoning for why
-            // ordering is the wrong tool for two real terms but the right one for a kill-switch:
-            // there is nothing to AND here, the switch simply wins).
+            // The `WOW_NO_LIQUID` override: after both per-frame `Visibility` owners of a surface
+            // (the exterior cull, the model-visibility authority) and before Bevy reads it.
             .add_systems(
                 PostUpdate,
                 surface::hide_liquid_surfaces
@@ -220,9 +115,7 @@ impl Plugin for LiquidPlugin {
                     .before(bevy::camera::visibility::VisibilitySystems::VisibilityPropagate)
                     .run_if(|| std::env::var_os("WOW_NO_LIQUID").is_some()),
             );
-        // The scripted surfacing crossing (see [`force_submersion`]) — the node is only added
-        // when the env asks for it, so an ordinary run carries neither the system nor a per-frame
-        // run condition that would re-read the environment to say "no" 60 times a second.
+        // Added only when `WOW_FORCE_SUB` names a hold: an ordinary run carries no system for it.
         if forced_submersion_frames() > 0 {
             app.add_systems(
                 Update,
@@ -231,8 +124,6 @@ impl Plugin for LiquidPlugin {
                     .in_set(SubmersionVerdict),
             );
         }
-        // The underwater drift cloud — the one thing in this subsystem that RENDERS because the
-        // eye is submerged, rather than answering where the liquid is (see the layout note above).
         drift::register(app);
     }
 }
diff --git a/crates/benilla-world/src/liquid/query.rs b/crates/benilla-world/src/liquid/query.rs
index 2d7467ca..6e56bfaf 100644
--- a/crates/benilla-world/src/liquid/query.rs
+++ b/crates/benilla-world/src/liquid/query.rs
@@ -1,13 +1,6 @@
-//! **Where the liquid is, and whether you are in it** — the geometry side of the liquid subsystem,
-//! with no render glue at all.
-//!
-//! Every spawned surface publishes its grid in world WoW space ([`WaterChunkInfo`], built by
-//! `super::surface::wet_footprint`); everything that asks a *position* question — swimming, the
-//! wade splash and footstep depth, the foam lattice, the ambient loops, and the submerged
-//! atmosphere — reads it through [`liquid_at`] and its filtered siblings. [`detect_submersion`] is
-//! the one cross-feed out of the subsystem: it publishes WHICH liquid the camera eye stands in
-//! ([`Underwater`]), and `lighting::update_time_lighting` selects the whole submerged atmosphere
-//! from that.
+//! Where the liquid is and whether a subject is in it: every spawned surface publishes its grid in
+//! world WoW space ([`WaterChunkInfo`]), and swimming, wading, foam, the ambient loops and the
+//! camera's submersion verdict ask it through [`liquid_at`] and its siblings.
 
 use bevy::prelude::*;
 
@@ -18,16 +11,11 @@ use crate::wmo_portal::{
 use benilla_assets::coords::{bevy_to_wow, wow_to_bevy};
 use benilla_formats::{LiquidKind, LiquidMesh};
 
-/// The placements a claim resolves its room's [`flood`](LiquidClaim::Inside) against — the
-/// per-group override baked onto [`WmoPortalInstance`] at spawn.
-///
-/// Threaded to every claim builder rather than read once into a resource so the answer cannot
-/// outlive the placement: a building streams out and its rooms leave with it, which a keyed side
-/// table would have to be told about.
+/// The placements a claim reads its room's whole-group override from, baked onto
+/// [`WmoPortalInstance`] at spawn, so the answer leaves with the placement.
 pub type RoomPlacements<'w, 's> = Query<'w, 's, &'static WmoPortalInstance>;
 
-/// One room's whole-group submersion override, or `None` when the group carries none (5219 of the
-/// archive's 5220 groups' worth of the time) or its placement has already streamed out.
+/// A room's whole-group submersion override, if its group carries one and its placement is loaded.
 fn flood_of(room: WmoRoom, placements: &RoomPlacements) -> Option<LiquidKind> {
     placements
         .get(room.instance)
@@ -35,8 +23,8 @@ fn flood_of(room: WmoRoom, placements: &RoomPlacements) -> Option<LiquidKind> {
         .and_then(|i| i.flooded.get(room.group as usize).copied().flatten())
 }
 
-/// The **camera eye's** liquid claim — the reference's `[0xc7b748]` branch in the environment probe
-/// `0x6809c0`: a containing map-object selects its MLIQ, otherwise the ADT liquid answers.
+/// The camera eye's claim: the environment probe `0x6809c0` samples the containing map-object's
+/// MLIQ when `[0xc7b748]` names one, else the ADT liquid.
 pub fn camera_claim(claim: &CameraInteriorClaim, placements: &RoomPlacements) -> LiquidClaim {
     match claim.0 {
         Some(c) => LiquidClaim::Inside {
@@ -47,7 +35,7 @@ pub fn camera_claim(claim: &CameraInteriorClaim, placements: &RoomPlacements) ->
     }
 }
 
-/// The **player's** liquid claim, from the interior down-ray `wmo_portal` already runs each frame.
+/// The player's claim, from `wmo_portal`'s per-frame interior down-ray.
 pub fn player_claim(room: &PlayerWmoRoom, placements: &RoomPlacements) -> LiquidClaim {
     match room.0 {
         Some(room) => LiquidClaim::Inside {
@@ -58,9 +46,8 @@ pub fn player_claim(room: &PlayerWmoRoom, placements: &RoomPlacements) -> Liquid
     }
 }
 
-/// A **remote unit's** liquid claim, from its own per-unit room. The component is absent only on a
-/// unit's first frame, before `wmo_portal::track_unit_interiors` has reached it — that, and only
-/// that, is [`LiquidClaim::Unknown`].
+/// A remote unit's claim, from its own room; [`LiquidClaim::Unknown`] only on its first frame,
+/// before `wmo_portal::track_unit_interiors` reaches it.
 pub fn unit_claim(room: Option<&UnitWmoRoom>, placements: &RoomPlacements) -> LiquidClaim {
     match room.map(UnitWmoRoom::room) {
         Some(Some(room)) => LiquidClaim::Inside {
@@ -72,87 +59,43 @@ pub fn unit_claim(room: Option<&UnitWmoRoom>, placements: &RoomPlacements) -> Li
     }
 }
 
-/// What the camera eye is currently submerged in — **which liquid, not merely whether**. Set by
-/// [`detect_submersion`]; read by `lighting::update_time_lighting`, which selects the atmosphere from
-/// it so the whole scene (fog colour + distances, ambient, diffuse, clear colour) becomes the
-/// submerged one (VERIFIED apitrace WoW.18 — the murk is fog + light-tint, no overlay quad). Two
-/// clocks aside, this is the one cross-feed from the liquid subsystem into lighting.
-///
-/// **The kind is load-bearing, not decoration.** Water and ocean read the *zone's* underwater
-/// `LightParams` slot; magma and slime read fixed global rows instead, zone-independent
-/// (byte-VERIFIED `0x6d2371` — see `benilla_formats::Submersion`). Carrying a bare `bool` here is
-/// what left lava and slime with no submerged view at all: they were excluded from the flag outright,
-/// because one bool could only mean "the water murk", and turning the Great Forge teal was worse than
-/// showing nothing.
+/// Which liquid the camera eye is in, set by [`detect_submersion`]. Lighting selects the whole
+/// submerged atmosphere from it, with no overlay quad: water and ocean take the zone's underwater
+/// `LightParams` slot, magma and slime fixed global rows (`0x6d2371`).
 #[derive(Resource, Default)]
 pub struct Underwater(pub(crate) benilla_formats::Submersion);
 
-/// Where a liquid surface came from, and — for WMO liquid — **whose room it is**: the
-/// **delegation + scope key** for [`liquid_at`].
-///
-/// The reference's liquid query is context-aware: terrain's `0x69b6d0` **delegates the WMO case out**
-/// via `0x69b520` (wow-re `terrain/scratch/class-batch3.md`), which transforms the query point into
-/// each placed map-object's own space before any MLIQ is sampled; and the per-frame camera
-/// environment probe `0x6809c0` samples the **current WMO group's** MLIQ (`0x6b9f10`) when
-/// `[0xc7b748]` names a containing map-object, else the ADT query `0x6723d0 → 0x69b6d0`
-/// (wow-re `terrain/scratch/fog-env-state.md` §1, `models/scratch/wmo-lit-selector.md` §3.4).
-///
-/// Without the source split, a tunnel bored under a lake inherits the lake: an ADT footprint is a
-/// flat XY rectangle with no floor, so every position beneath it reads as submerged — the "swim in
-/// air" family (decision 0634). Without the **owner**, the same holds one level up: a WMO pool
-/// claims every position under its XY in *every other building on the map*, at any depth. That is
-/// decision 0696 — the Uldaman entrance read as submerged under a mushroom cave's pool 186 yd
-/// overhead, in a building the player was 191 yd below and had never entered.
+/// Where a surface came from and, for WMO liquid, whose room it is: the scope key for
+/// [`liquid_at`]. The reference's terrain query `0x69b6d0` tries the map-object leg `0x69b520`
+/// first, which moves the point into each map-object's own space before sampling MLIQ, then the
+/// ADT; the camera probe `0x6809c0` samples the current group's MLIQ (`0x6b9f10`) when
+/// `[0xc7b748]` names a containing map-object, else the ADT query (`0x6723d0` → `0x69b6d0`).
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub enum LiquidSource {
-    /// An ADT map-chunk surface (MCLQ) — the outdoor world's lakes, rivers, coast.
+    /// An ADT map-chunk surface (MCLQ).
     AdtChunk,
-    /// A WMO group's embedded surface (MLIQ) — canals, fountains, the Great Forge lava,
-    /// Undercity's slime — tagged with the room that owns it and that room's own floor.
+    /// A WMO group's surface (MLIQ), with the room that owns it and that room's floor.
     WmoGroup(WmoPool),
 }
 
-/// A WMO pool's **scope**: whose room it is, and how far down that room reaches.
-///
-/// Both fields exist to bound a footprint that has none of its own. `owner` bounds it sideways, to
-/// one placement (0696). `floor` bounds it *downwards*, to one storey — the piece 0696 named as
-/// still open and deferred to wow-re, now measured against the shipped files: Undercity's upper
-/// slime channels (groups 7 and 10, world z ≈ 52) were submerging the Rogues'-Quarter-level rooms
-/// **115 yd below them**, in the same placement, so owner scoping alone could not reject them.
+/// A WMO pool's scope: `owner` bounds its footprint to one placement, `floor` to one storey.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct WmoPool {
-    /// The room this pool belongs to.
-    ///
-    /// `None` only for a placement that spawned no [`WmoPortalInstance`](crate::wmo_portal::WmoPortalInstance)
-    /// — a portal-less building with no `WMOAreaTable` identity. Nothing can claim to be *inside*
-    /// such a placement (the interior trackers skip it), so its pool answers no one. That is the
-    /// pre-existing behaviour made explicit rather than a new gap: an unowned pool was already
-    /// unreachable, it just used to be unreachable by accident.
+    /// The room this pool belongs to; `None` for a placement that spawned no `WmoPortalInstance`
+    /// (no portals, no `WMOAreaTable` identity), which no interior claim can then reach.
     pub(crate) owner: Option<WmoRoom>,
-    /// World WoW Z of the **owning group's own bounding box floor** — a pool never claims a subject
-    /// below the room it sits in.
-    ///
-    /// The reference's WMO leg picks its group by testing the query point against each group's MOGI
-    /// bounding box (`0x6a4e00`, per-group strict AABB) before sampling any MLIQ, so a pool three
-    /// storeys up is never even a candidate. We take the box's **Z floor only**, not the whole AABB:
-    /// measured over every WMO placed in the shipped world, a pool's wet cells reach up to 25 yd
-    /// *outside* their own group's box in XY (Ahn'Qiraj, Stratholme), so testing XY against the box
-    /// too would newly reject pools that work today — while the Z floor cannot, because anything
-    /// genuinely swimming in a pool is above the floor of the room holding it.
-    ///
-    /// `NEG_INFINITY` when the group's bounds are unknown: no floor, i.e. exactly the pre-0701
-    /// behaviour, so a missing box can only ever fail open.
+    /// World WoW Z of the owning group's bounding-box floor: the pool claims no subject below it.
+    /// The reference's per-group box test (`0x6a4e00`) never picks an interior group: it skips
+    /// every group whose flags match its mask, and its one caller passes `0x2000`, the interior
+    /// flag (`0x69b570` → `0x69b575`). This floor bounds interior and exterior pools alike, in Z
+    /// only, since wet cells reach up to 25 yd outside their group's box in XY (Ahn'Qiraj,
+    /// Stratholme). `NEG_INFINITY` for unknown bounds, so a missing box fails open.
     pub(crate) floor: f32,
 }
 
 impl WmoPool {
-    /// The scope of the pool in `bounds`'s group, under a placement `transform`: the owning room,
-    /// and that group's bounding-box floor carried into world WoW Z.
-    ///
-    /// The floor is taken over all **eight** corners rather than off `bbox_min` alone, because a
-    /// placement may be rotated and the lowest corner of a tilted box is not the box's own minimum.
-    /// Absent bounds ⇒ [`NEG_INFINITY`](f32::NEG_INFINITY): a missing box must fail *open* (a pool
-    /// that claims too much — the pre-0701 behaviour) rather than closed (a lake nobody can swim in).
+    /// The pool's scope under a placement `transform`: the floor is the lowest of the box's eight
+    /// transformed corners, since a rotated box's lowest corner is not its `bbox_min`.
     pub(crate) fn new(
         owner: Option<WmoRoom>,
         transform: &Transform,
@@ -168,7 +111,7 @@ impl WmoPool {
         for x in [g.bbox_min[0], g.bbox_max[0]] {
             for y in [g.bbox_min[1], g.bbox_max[1]] {
                 for z in [g.bbox_min[2], g.bbox_max[2]] {
-                    // Bevy's +Y is WoW's +Z, so a transformed corner's `y` IS its world height.
+                    // Bevy's +Y is WoW's +Z, so a transformed corner's `y` is its height.
                     floor = floor.min(transform.transform_point(wow_to_bevy([x, y, z])).y);
                 }
             }
@@ -177,50 +120,28 @@ impl WmoPool {
     }
 }
 
-/// Whose liquid answers for one subject at one position — the query's context, and the whole of the
-/// "swim in air" family's fix.
-///
-/// Every subject that asks the liquid a question carries one: the player (from
-/// [`PlayerWmoRoom`](crate::wmo_portal::PlayerWmoRoom)), the camera eye (from
-/// [`CameraInteriorClaim`](crate::wmo_portal::CameraInteriorClaim) — the reference's `[0xc7b748]`),
-/// and every remote unit (its own per-unit claim). Before 0696 the parameter was a bare
-/// `Option<bool>`, which could say *that* a subject was indoors but never *where* — so "indoors"
-/// admitted every MLIQ surface in the world.
+/// Whose liquid answers for a subject: the player's room ([`PlayerWmoRoom`]), the camera eye's
+/// ([`CameraInteriorClaim`], the reference's `[0xc7b748]`) or a remote unit's own.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum LiquidClaim {
-    /// The subject stands in the open world: the ADT's MCLQ answers, nothing else.
+    /// In the open world: only the ADT's MCLQ answers.
     Outdoors,
-    /// The subject stands in this placed building: **that placement's** MLIQ answers, nothing else.
+    /// Inside this placed building: only that placement's MLIQ answers.
     Inside {
         room: WmoRoom,
-        /// The room's **whole-group submersion override** — its MOGP `groupLiquid`, when that word
-        /// is not the `0xf` no-liquid sentinel.
-        ///
-        /// Not a surface and not a depth. The client's group probe `0x6b9f10` reads this word
-        /// *first* and, when it is set, returns a hit unconditionally: the raw value as the kind,
-        /// `FLT_MAX` as the height, **no Z compare and no MLIQ test at all**. So it rides on the
-        /// claim rather than on a [`WaterChunkInfo`] — because there is no chunk. All 13 groups in
-        /// the archive that set it carry no `MLIQ` whatsoever, which is the entire point of the
-        /// mechanism (wow-re `models/scratch/wmo-liquid-scoping.md` §5; census reproduced with our
-        /// own reader).
-        ///
-        /// This is what makes an underwater cave or a flooded tunnel wet. Five are placed and can
-        /// be stood in: the Deeprun Tram's two submerged sections, the Prison Oubliette, the MD
-        /// crypt and the MD mountain cave — all of which read bone dry before decision 1000,
-        /// because the ADT leg is suppressed indoors and the room offered nothing in its place.
+        /// The room's whole-group submersion override: its MOGP `groupLiquid` when not the `0xf`
+        /// sentinel. The group probe `0x6b9f10` reads it first and, when set, hits unconditionally:
+        /// the raw value as the kind, `FLT_MAX` as the height, no Z compare and no MLIQ test. None
+        /// of the 13 groups that set it has an MLIQ; it floods the Deeprun Tram's submerged
+        /// sections, the Prison Oubliette and two MD caves.
         flooded: Option<LiquidKind>,
     },
-    /// No interior claim has been computed for this subject yet — its first frame, before the
-    /// tracker has run. Both sources answer (the pre-0634 behaviour), which is the wrong answer for
-    /// exactly one frame rather than a silent guess at the right one.
+    /// No claim yet (a subject's first frame, before its tracker runs): both sources answer.
     Unknown,
 }
 
 impl LiquidClaim {
-    /// A claim on a room that carries **no** whole-group override — the shape 5207 of the archive's
-    /// 5220 groups have, and what every offline scene and test fixture builds. The live claim
-    /// builders resolve the flood from the placement instead; this is for the callers that have a
-    /// room and no world to look it up in.
+    /// A claim on a room with no whole-group override, for callers with no placement to read.
     #[cfg(test)]
     pub(crate) fn inside(room: WmoRoom) -> Self {
         Self::Inside {
@@ -230,23 +151,9 @@ impl LiquidClaim {
     }
 }
 
-/// One liquid surface as the submersion/swim/foam/sound queries see it: its **grid**, in world WoW
-/// space with the placement transform already baked in, plus the XY bounds, which file it came
-/// from, and which liquid it is. Attached to each [`LiquidSurface`]; despawns with its tile, so no
-/// manual lifecycle.
-///
-/// Named `Water*` from when only water carried one. It now rides **every** kind — magma and slime
-/// included, which is what makes Blackrock's lava and Undercity's slime swimmable at all (decision
-/// 0634). Consumers that are specifically about *water* (the surface swatch, foam, the wade splash and
-/// footstep depth) filter on [`Self::kind`]; the swim mode does not, because you swim in lava too —
-/// and neither does the **submerged atmosphere**, which is per-kind rather than water-only
-/// ([`Underwater`]).
-///
-/// **A liquid is a grid — not a plane, not a triangle soup.** Both of its questions, *is this XY
-/// wet* and *how high is the surface here*, are answered by locating the containing cell
-/// ([`LiquidGrid::wet_cell_at`]) and reading it: the cell's own flag for the first, a bilinear over
-/// its four corner heights for the second — both O(1). The bounding box is only a cheap reject, and
-/// the triangles are only what the renderer draws.
+/// One liquid surface of any kind as the queries see it: its grid in world WoW space, placement
+/// baked in, with its XY bounds, source and kind. Wet-or-dry and the surface height both come from
+/// the cell containing the XY; the box is only a cheap reject.
 #[derive(Component)]
 pub struct WaterChunkInfo {
     min_x: f32,
@@ -258,15 +165,9 @@ pub struct WaterChunkInfo {
     grid: LiquidGrid,
 }
 
-/// A liquid surface's vertex grid in world WoW space: `cols × rows` positions row-major
-/// (`j·cols + i`), one wet flag per `(cols−1) × (rows−1)` cell, and the lattice's affine basis.
-///
-/// The grid stays a regular lattice under any placement — a WMO's MODF transform is affine, so the
-/// world positions are exactly `origin + i·u + j·v` in XY. That is *measured*, not assumed:
-/// Blackrock's 55×82 magma grid (a ~7° yaw placement, `u = (−4.136, −0.508)`) and Felwood's
-/// axis-aligned 9×9 MCLQ both reproduce from the span-derived basis to **0.0005 yd** — one f32 ulp
-/// at world magnitude. So a world XY inverts to grid coordinates with one 2×2 solve, and neither
-/// the rotated case nor the axis-aligned one needs a search.
+/// A surface's vertex grid in world WoW space and its lattice basis. A MODF placement is affine, so
+/// the XY positions stay `origin + i·u + j·v` (to 0.0005 yd on Blackrock's rotated 55×82 grid) and
+/// a world XY inverts to a cell with one 2×2 solve.
 struct LiquidGrid {
     cols: usize,
     rows: usize,
@@ -276,37 +177,23 @@ struct LiquidGrid {
     wet: Vec<bool>,
     /// Grid vertex `(0, 0)`, XY.
     origin: [f32; 2],
-    /// World XY step per `+1` in `i` / in `j` — derived over the **full span** (`(last − first)/n`)
-    /// rather than from one adjacent pair. At world magnitude a single f32 difference of two ~7600
-    /// yd coordinates carries ~1e-4 relative error, which over Blackrock's 54 cells drifts 0.02 yd;
-    /// dividing the same error by the span lands it at one ulp instead (both measured).
+    /// World XY step per `+1` in `i` / in `j`, over the full span (`(last − first)/n`): one
+    /// adjacent pair's f32 error at world magnitude drifts 0.02 yd across Blackrock's 54 cells.
     u: [f32; 2],
     v: [f32; 2],
-    /// `1/det` of the `[u v]` basis — `None` when the lattice is degenerate in XY (a placement that
-    /// stood the liquid plane on edge, or a malformed grid). Degenerate ⇒ queries fall back to the
-    /// bounds.
+    /// `1/det` of the `[u v]` basis; `None` when degenerate in XY, where queries use the bounds.
     inv_det: Option<f32>,
-    /// The highest wet vertex — the **degenerate fallback only**. Never the answer for a grid we can
-    /// sample: taking the chunk maximum as "the surface" is precisely the bug this type was rebuilt
-    /// to kill (decision 0642).
+    /// The highest wet vertex: the degenerate fallback only, never the surface of a sampled grid.
     fallback_z: f32,
 }
 
-/// How far outside the grid, in cells, a query may land and still be snapped back in. The lattice
-/// reproduces to ~1e-4 cells, so this is pure edge hygiene (≈4 mm): a player standing exactly on
-/// the outer rim of a lake must not fall through it on an f32 tie.
+/// How far outside the grid, in cells, a query still snaps in, so a lake's rim is wet on a tie.
 const GRID_EDGE_TOLERANCE: f32 = 1e-3;
 
 impl LiquidGrid {
-    /// The cell containing this world XY plus the in-cell fractions — `(i, j, fx, fy)` with
-    /// `0 ≤ fx, fy ≤ 1` — or `None` if the XY is off the grid, over a dry cell, or the grid is
-    /// unusable.
-    ///
-    /// The dry-cell rejection is the whole of decision 0635: a liquid grid is sparse (MLIQ per-tile
-    /// nibble `0xf` = hole, MCLQ likewise), so its bounding box routinely spans ground the liquid
-    /// never covers — canal banks, the tunnel under a canal, the dirt beside a river. One MLIQ
-    /// grid's box in Stormwind is **95 × 80 yards** and covers the canal *and* the dry mage-district
-    /// tunnel beside it; `[min,max]` alone can never tell them apart.
+    /// The wet cell containing this world XY and the in-cell fractions `(i, j, fx, fy)`. A grid is
+    /// sparse (MLIQ tile nibble `0xf` is a hole, MCLQ likewise), so its box spans dry ground: one
+    /// Stormwind MLIQ box, 95 × 80 yd, covers a canal and the dry tunnel beside it.
     fn wet_cell_at(&self, x: f32, y: f32) -> Option<(usize, usize, f32, f32)> {
         let (cells_x, cells_y) = (self.cols.checked_sub(1)?, self.rows.checked_sub(1)?);
         let inv_det = self.inv_det?;
@@ -327,13 +214,8 @@ impl LiquidGrid {
         self.wet.get(j * cells_x + i)?.then_some((i, j, fx, fy))
     }
 
-    /// The liquid surface height (WoW Z) at an in-cell position — the **bilinear** over the cell's
-    /// four corner heights.
-    ///
-    /// This is the reference's own rule: `0x6b7500` `liquid_height_sample` locates the cell, then
-    /// lerps along one axis and then the other over exactly these four heights (wow-re
-    /// `system/terrain/terrain.md` — transcribed there and difftested bit-exact against `WoW.exe`).
-    /// Same shape here, over the same corners.
+    /// The surface height (WoW Z) in a cell: the bilinear over its four corners, as `0x6b7500`
+    /// lerps along one axis and then the other.
     fn height_in_cell(&self, i: usize, j: usize, fx: f32, fy: f32) -> f32 {
         let z = |i: usize, j: usize| self.positions[j * self.cols + i][2];
         let t1 = z(i, j) + (z(i + 1, j) - z(i, j)) * fx;
@@ -341,8 +223,7 @@ impl LiquidGrid {
         t1 + (t2 - t1) * fy
     }
 
-    /// The `(lowest, highest)` wet vertex — how much relief this one surface carries. Walks the wet
-    /// cells; for the `/liquid` instrument only, which runs once per invocation.
+    /// The `(lowest, highest)` wet vertex, for the `/liquid` instrument.
     fn wet_z_range(&self) -> (f32, f32) {
         let Some(cells_x) = self.cols.checked_sub(1) else {
             return (self.fallback_z, self.fallback_z);
@@ -359,20 +240,14 @@ impl LiquidGrid {
 }
 
 impl WaterChunkInfo {
-    /// The **chunk-maximum** height — the single highest wet vertex of the whole grid.
-    ///
-    /// This is the rule the per-cell sample REPLACED (decision 0634): it answered "swimming" from
-    /// anywhere under a surface's XY box, which is how Blackrock's staircase read as submerged with
-    /// its lava metres below. Nothing live reads it; `super::real_data` does, to assert the number
-    /// the fix moved away from — a regression test whose baseline would otherwise be a comment.
+    /// The grid's highest wet vertex, which `super::real_data` shows is not the surface.
     #[cfg(test)]
     pub(super) fn chunk_max_z(&self) -> f32 {
         self.grid.fallback_z
     }
 
-    /// Build a footprint from a **world-space** liquid grid: `cols × rows` positions row-major and
-    /// one wet flag per cell. Bounds and the degenerate fallback height come from the wet cells'
-    /// own corners, so a sparse grid's box stays as tight as its liquid.
+    /// A footprint from a world-space grid of `cols × rows` positions and one wet flag per cell;
+    /// bounds and fallback height come from the wet cells' corners only.
     pub fn new(
         source: LiquidSource,
         kind: LiquidKind,
@@ -380,10 +255,7 @@ impl WaterChunkInfo {
         positions: Vec<[f32; 3]>,
         wet: Vec<bool>,
     ) -> Self {
-        // A grid whose dimensions don't match its arrays is normalized away to an EMPTY one here,
-        // in the one place that can judge it — so every method below indexes a grid it has already
-        // been told is self-consistent, instead of each re-deriving that judgement (and one of them
-        // getting it wrong). An empty grid has no bounds, so it simply claims nothing.
+        // Mismatched dimensions make an empty grid that claims nothing and walks nothing.
         let [cols, rows] = grid;
         let sane = cols >= 2
             && rows >= 2
@@ -424,9 +296,7 @@ impl WaterChunkInfo {
                 fallback_z = fallback_z.max(p[2]);
             }
         }
-        // Span-derived basis (see `LiquidGrid::u`) and its 2×2 determinant. A plane stood on edge
-        // projects to a line in XY: no cell lookup is possible there, so leave `inv_det` `None` and
-        // let the query fall back to the bounds rather than answer a wrong cell.
+        // The span-derived basis; a plane on edge has no XY area and leaves `inv_det` `None`.
         let origin = [positions[0][0], positions[0][1]];
         let step = |far: [f32; 3], n: usize| {
             [
@@ -458,26 +328,16 @@ impl WaterChunkInfo {
         }
     }
 
-    /// The liquid surface height (WoW Z) at this WoW-space XY, or `None` where this surface isn't
-    /// there — the **one** question the swim, submersion, wade and foam queries ask. A `None` is
-    /// exactly "dry here"; there is deliberately no second predicate that answers wet/dry on its
-    /// own, because two spellings of one question are how the box test and the cell test were able
-    /// to disagree for as long as they did.
-    ///
-    /// The answer is the bilinear sample of the containing cell — **not the chunk's highest
-    /// vertex**. A liquid grid is a heightfield, not a plane: Blackrock's magma runs 167.29 → 175.00
-    /// across one group, and Felwood's river drops ~2 yd across a single MCNK. The maximum is the
-    /// *whole surface's* ceiling, which near the low end sits metres above the liquid actually under
-    /// your feet — and that read as "swim in air" over both (decision 0642).
+    /// The surface height (WoW Z) at a WoW-space XY, `None` where dry: the one wet-or-dry question,
+    /// answered by the containing cell's bilinear, never by the grid's highest vertex.
     pub(crate) fn surface_z_at(&self, x: f32, y: f32) -> Option<f32> {
         if !self.contains(x, y) {
             return None; // the bounding box is the cheap reject
         }
         match self.grid.wet_cell_at(x, y) {
             Some((i, j, fx, fy)) => Some(self.grid.height_in_cell(i, j, fx, fy)),
-            // A grid we can't invert must not silently swallow its whole box — fall back to the
-            // bounds and the highest wet vertex rather than report a surface we failed to lay out
-            // as dry. A wrong "dry" is a player falling through a lake; a wrong "wet" is milder.
+            // A grid that cannot be inverted answers its whole box at the highest wet vertex: a
+            // wrong "dry" drops a player through a lake.
             None if self.grid.inv_det.is_none() => Some(self.grid.fallback_z),
             None => None,
         }
@@ -505,23 +365,15 @@ impl WaterChunkInfo {
         x >= self.min_x && x <= self.max_x && y >= self.min_y && y <= self.max_y
     }
 
-    /// The wet footprint's XY box as `[[min_x, min_y], [max_x, max_y]]`, or `None` for an empty
-    /// grid (which claims no area at all) — what [`super::spatial::WaterIndex`] buckets by.
+    /// The wet footprint's XY box, `None` for an empty grid: what [`super::spatial::WaterIndex`]
+    /// buckets by.
     pub(super) fn xy_bounds(&self) -> Option<[[f32; 2]; 2]> {
         (self.min_x <= self.max_x && self.min_y <= self.max_y)
             .then_some([[self.min_x, self.min_y], [self.max_x, self.max_y]])
     }
 
-    /// Does this surface answer for a subject holding `claim`? — the delegation, in one place.
-    ///
-    /// An [`Inside`](LiquidClaim::Inside) subject reads its **own placement's** MLIQ and nothing
-    /// else: not the ADT liquid overhead (the 0634 delegation), and not another building's pool
-    /// (the 0696 owner scoping). An [`Outdoors`](LiquidClaim::Outdoors) subject reads only the ADT.
-    /// [`Unknown`](LiquidClaim::Unknown) is the un-classified first frame and admits both.
-    ///
-    /// `z` is the subject's own WoW height, and it is what bounds a WMO pool **downwards** to its
-    /// own storey ([`WmoPool::floor`], decision 0701) — a test on the pool rather than on the
-    /// delegation, so it holds under every claim including `Unknown`.
+    /// Does this surface answer for a subject holding `claim` at WoW height `z`? The pool floor
+    /// ([`WmoPool::floor`]) holds under every claim, `Unknown` included.
     fn answers(&self, claim: LiquidClaim, z: f32) -> bool {
         match (claim, self.source) {
             (_, LiquidSource::WmoGroup(pool)) if z < pool.floor => false,
@@ -535,9 +387,7 @@ impl WaterChunkInfo {
         }
     }
 
-    /// The room this surface belongs to (`None` for ADT liquid and for an unowned WMO placement) —
-    /// the `/liquid` instrument's attribution column, which is what turns "some pool is claiming
-    /// me" into "*that* building's pool is claiming me".
+    /// The room this surface belongs to, for the instruments; `None` for ADT and unowned liquid.
     fn owner(&self) -> Option<WmoRoom> {
         match self.source {
             LiquidSource::AdtChunk => None,
@@ -545,13 +395,12 @@ impl WaterChunkInfo {
         }
     }
 
-    /// Does this WoW-space XY box overlap the chunk's wet footprint?
+    /// Does this WoW-space XY box overlap the wet footprint's box?
     pub(crate) fn overlaps(&self, lo_x: f32, hi_x: f32, lo_y: f32, hi_y: f32) -> bool {
         hi_x >= self.min_x && lo_x <= self.max_x && hi_y >= self.min_y && lo_y <= self.max_y
     }
 
-    /// Call `f` with every wet cell's four world-WoW corners, `[tl, tr, bl, br]` — the foam
-    /// builder's view of the surface, which clips each decal to the wet cells overlapping its box.
+    /// Call `f` with every wet cell's four world WoW corners `[tl, tr, bl, br]`, for the foam clip.
     pub(crate) fn for_each_wet_cell(&self, mut f: impl FnMut([[f32; 3]; 4])) {
         let g = &self.grid;
         let Some(cells_x) = g.cols.checked_sub(1) else {
@@ -564,10 +413,9 @@ impl WaterChunkInfo {
         }
     }
 
-    /// The wet footprint's nearest point to a WoW-space XY, ON the surface — the liquid ambient
-    /// loop's emitter slew target (the ref positions the channel at the nearest liquid cell; the
-    /// AABB clamp is our cell-level approximation, noted in 0506). Its height is the surface's at
-    /// that clamped XY, falling back to the highest wet vertex when the clamp lands over a hole.
+    /// The ambient loop's emitter target: the XY clamped into the footprint's box, at the surface's
+    /// height there, or the highest wet vertex over a hole. The reference uses the nearest liquid
+    /// cell; this clamp approximates it.
     pub(crate) fn nearest_point_wow(&self, x: f32, y: f32) -> [f32; 3] {
         let cx = x.clamp(self.min_x, self.max_x);
         let cy = y.clamp(self.min_y, self.max_y);
@@ -579,23 +427,14 @@ impl WaterChunkInfo {
     }
 }
 
-/// A liquid surface's [`WaterChunkInfo`] — its grid lifted into **world** WoW space, with
-/// `transform` mapping the mesh's local space into the world.
-///
-/// For MCLQ water `lq.positions` are already absolute WoW and `transform` is `IDENTITY` —
-/// `bevy_to_wow(wow_to_bevy(p))` is an exact round-trip (a pure axis permutation with sign flips),
-/// so the grid comes through bit-for-bit. For WMO liquid the positions are model-local and
-/// `transform` is the building's MODF placement, so each vertex is carried local-WoW → local-Bevy →
-/// world-Bevy → world-WoW. That transform is affine, so the grid is still a regular lattice on the
-/// far side — which is what lets [`WaterChunkInfo`] invert a world XY straight to a cell.
+/// A surface's [`WaterChunkInfo`], its grid carried into world WoW space by `transform`:
+/// `IDENTITY` for MCLQ, whose positions are already absolute (the axis round trip is exact), the
+/// MODF placement for model-local WMO liquid.
 pub(super) fn wet_footprint(
     lq: &LiquidMesh,
     transform: &Transform,
     source: LiquidSource,
 ) -> WaterChunkInfo {
-    // The grid is carried in WORLD WoW space (placement baked in) so every consumer — the swim
-    // query's cell lookup, the height sample, the foam clip, the ambient loop — reads one set of
-    // vertices in one frame of reference.
     let positions: Vec<[f32; 3]> = lq
         .positions
         .iter()
@@ -610,62 +449,34 @@ pub(super) fn wet_footprint(
     )
 }
 
-/// A liquid vertex's world-space WoW position: **local-WoW → local-Bevy → world-Bevy → world-WoW**.
-/// The one place the placement transform is baked into raw liquid coords. For MCLQ water the
-/// transform is `IDENTITY`, so this is `bevy_to_wow(wow_to_bevy(p))` = `p` exactly.
 fn world_wow(transform: &Transform, local: [f32; 3]) -> [f32; 3] {
     bevy_to_wow(transform.transform_point(wow_to_bevy(local)))
 }
 
-/// Marks a liquid surface that grows **foam** — water kinds only, never magma or slime.
-///
-/// A marker, not data: the wet cells foam clips against live on [`WaterChunkInfo`]
-/// ([`WaterChunkInfo::for_each_wet_cell`]), because the swim query needs the very same cells to
-/// answer "is this XY actually wet". They used to be duplicated here, which is how the two could
-/// disagree — foam clipped to the wet cells while swimming only ever tested the bounding box.
+/// Marks a water surface that grows foam; the cells it clips against are on [`WaterChunkInfo`].
 #[derive(Component)]
 pub struct FoamPatch;
 
-/// One liquid the query landed in: its surface height (WoW Z) and which liquid it is.
+/// The liquid a query landed in: its surface height (WoW Z) and kind.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct LiquidHit {
     pub surface_z: f32,
     pub kind: LiquidKind,
 }
 
-/// The liquid over a **WoW-space** position — the shared query under swim mode, submersion, wading
-/// and the enter-water sounds.
-///
-/// **`claim` is the whole delegation** ([`LiquidClaim`], [`LiquidSource`]):
-/// [`Inside`](LiquidClaim::Inside) answers from **that placement's own** MLIQ surfaces only,
-/// [`Outdoors`](LiquidClaim::Outdoors) from the ADT's MCLQ ones only. This mirrors the reference,
-/// whose terrain query delegates the WMO case out rather than unioning the two — and whose WMO leg
-/// transforms the point into each map-object's own space before sampling anything, so a building the
-/// subject is not in cannot answer for it.
-///
-/// It is the fix for "swim in air" at both levels. A footprint is a flat XY rectangle with **no
-/// floor**: before the source split the Stormwind canal claimed the mage-district tunnel beneath it
-/// (0634); before the *owner* scoping a mushroom cave's pool claimed the Uldaman entrance 186 yd
-/// below it, in a building the player had never entered (0696).
-///
-/// Each candidate answers with its height **at this XY** ([`WaterChunkInfo::surface_z_at`]), and
-/// among them the **lowest wins**. Overlapping footprints used to resolve by iteration order
-/// (`.next()`) — an arbitrary pick that made the answer depend on spawn order. The lowest is the one
-/// whose volume you are actually in when standing between two stacked surfaces.
-///
-/// And a WMO pool is bounded **below** by its own room's floor ([`WmoPool::floor`], decision 0701):
-/// owner scoping bounded a pool to its building but not to its *storey*, which left Undercity's
-/// upper slime channels submerging the rooms 115 yd beneath them — the same defect a third time,
-/// one level further in.
+/// The liquid over a WoW-space position under `claim`: the shared query of swimming, submersion,
+/// wading and the enter-water sounds. `Inside` reads only that placement's MLIQ and `Outdoors`
+/// only MCLQ. The reference's terrain query `0x69b6d0` reads the map-object leg first (`0x69b6ec`
+/// → `0x69b520` → `0x6a4e00`, exterior groups only), then the ADT, so an outdoor subject in an
+/// exterior group's pool reads that pool, which `Outdoors` here never does. Where surfaces stack,
+/// the lowest at this XY wins, the one a subject between them is in.
 pub fn liquid_at<'a>(
     liquids: impl Iterator<Item = &'a WaterChunkInfo>,
     wow: [f32; 3],
     claim: LiquidClaim,
 ) -> Option<LiquidHit> {
-    // The whole-group override answers FIRST and alone, exactly where `0x6b9f10` reads it: before
-    // any grid, with no Z compare, at `FLT_MAX`. Not folded in as one more candidate below, because
-    // `min_by` would then hand the room to any sibling pool that happens to sit lower — and the
-    // reference never gets that far. A flooded room's answer is the room.
+    // The whole-group override answers first and alone, as `0x6b9f10` reads it before any grid;
+    // as one more candidate, `min_by` would hand the room to any lower sibling pool.
     if let LiquidClaim::Inside {
         flooded: Some(kind),
         ..
@@ -687,33 +498,15 @@ pub fn liquid_at<'a>(
         .min_by(|a, b| a.surface_z.total_cmp(&b.surface_z))
 }
 
-/// Every loaded liquid footprint containing this WoW XY, one human-readable line each — the body of
-/// the `/liquid` chat instrument.
-///
-/// Built because the "swim in air" family cannot be reasoned about from the outside: the answer
-/// depends on which surfaces cover a spot, which FILE each came from, and the player's live interior
-/// claim — three things no offline dump can see together. Prints every candidate, not just the
-/// winner, so a surface that should not be claiming is visible next to the one that should.
-///
-/// Each line also carries the **cell** the height came from and the surface's full Z range, because
-/// the two failures this instrument exists to separate look identical without them: claiming a spot
-/// it shouldn't (wrong cell) versus claiming the right spot at the wrong height (wrong height rule).
-/// 0635 read a footprint's *size* off this instrument to find the first; a `grid z` span far from
-/// the sampled height is the second (decision 0642).
-///
-/// And each line names its **owner** — which placement + group a WMO pool belongs to, and whether
-/// the subject's own claim matches it (`◀ YOURS` / `other room`). Without that column the Uldaman
-/// report ("VERDICT Still, +185.91 over feet, WmoGroup WET-CELL") was indistinguishable from a
-/// legitimate pool sampled at the wrong height: nothing on the line said the surface belonged to a
-/// *different building* — which was the entire bug (0696).
+/// Every loaded footprint containing this WoW XY, one line each: the `/liquid` chat instrument.
+/// Each line names the surface's owner and floor, whether the claim admits it, the cell and height
+/// sampled and the surface's Z range, so a wrong claim and a wrong height read apart.
 pub fn describe_at<'a>(
     liquids: impl Iterator<Item = &'a WaterChunkInfo>,
     wow: [f32; 3],
     claim: LiquidClaim,
 ) -> Vec<String> {
-    // A flooded room has NOTHING in the surface list — that is the mechanism, not a failure — so an
-    // instrument that only walked footprints would print "no liquid here" beside a verdict that
-    // says submerged. Naming the override is the whole difference between the two readings.
+    // A flooded room has no footprint to list, so the override gets a line of its own.
     let mut lines = Vec::new();
     if let LiquidClaim::Inside {
         room,
@@ -742,8 +535,7 @@ pub fn describe_at<'a>(
                 ),
                 (None, _) => "box-only (dry here)".to_string(),
             };
-            // The owner column names the pool's room AND its floor: a candidate rejected for being
-            // a storey up looks identical to one rejected for being another building's without it.
+            // The floor too, or a pool rejected for its storey reads like another building's.
             let owner = match w.source {
                 LiquidSource::AdtChunk => "AdtChunk".to_string(),
                 LiquidSource::WmoGroup(pool) => match pool.owner {
@@ -777,12 +569,8 @@ pub fn describe_at<'a>(
     lines
 }
 
-/// Every **admitted** liquid surface height over `wow`'s XY under the given claim — the same
-/// delegation [`submersion_at`] applies (the 0634/0696 scoping: a pool in another building or
-/// storey never answers), with no over/under verdict attached: the consumer that needs the
-/// surfaces a subject is merely *near* — above or below — is the effect lane's water-side
-/// classification (`particles::sim::far_side_of_water_at`, decisions 0911/0921). Kept here so
-/// the delegation rule has one owner; `answers` stays private.
+/// Every surface height over `wow`'s XY that the claim admits, above or below the subject, for the
+/// effect lane's water-side test (`particles::sim::far_side_of_water_at`).
 pub fn surfaces_at<'a>(
     liquids: impl Iterator<Item = &'a WaterChunkInfo> + 'a,
     wow: [f32; 3],
@@ -793,14 +581,8 @@ pub fn surfaces_at<'a>(
         .filter_map(move |w| w.surface_z_at(wow[0], wow[1]))
 }
 
-/// [`liquid_at`] restricted to **water** kinds — the query for the consumers that are about water
-/// specifically (the wade splash, footstep depth, the remote-motion spline's depth), which must not
-/// fire in the Great Forge's lava or Undercity's slime. Swim mode deliberately does NOT use this one.
-///
-/// The **submerged atmosphere no longer routes through here either**: it is per-kind (magma and slime
-/// have their own fixed `LightParams` rows), so it reads [`Underwater`] instead. This wrapper's docs
-/// used to name "the teal murk" as its headline consumer, and that was exactly the assumption that
-/// left lava and slime with no submerged view at all.
+/// [`liquid_at`] over the water kinds only, for the wade splash, footstep depth and spline depth;
+/// swimming and the submerged atmosphere take every kind.
 pub fn water_surface_at<'a>(
     water: impl Iterator<Item = &'a WaterChunkInfo>,
     wow: [f32; 3],
@@ -809,74 +591,25 @@ pub fn water_surface_at<'a>(
     liquid_at(water.filter(|w| !w.kind.is_fullbright()), wow, claim).map(|h| h.surface_z)
 }
 
-// The **wade ceiling** used to live here, as `WADE_MAX = 2.0` — a flat proxy for a boundary B7
-// (decision 0226) had already shown to be `0.75·collisionHeight`, kept because the per-unit height
-// it needed was 0464's un-plumbed `CreatureModelData.collisionHeight`. Decision 0645 plumbed it, so
-// the proxy is gone and there is no wade constant to re-import: wading is *the complement of
-// swimming*, one number, and its one spelling is `player::swim_enter_depth(h)`. A human's line
-// moved 2.0 → 1.52 yd, a murloc's far shallower.
+// No wade constant: wading is the complement of swimming (`player::swim_enter_depth`).
 
-/// Eye-submersion accept margin for the **water** kinds (VERIFIED `FUN_0069b6d0`: `eye.z < surface +
-/// 0.01`, the f32 `0x3c23d70a` at `0x8029d0`, strict `<`). The WMO magma/slime compare carries no
-/// epsilon at all, so [`detect_submersion`] applies this per kind.
+/// The eye's accept margin on the water kinds, `z < surface + 0.01` strict (`0x69b6d0`, compared
+/// at `0x69ba23` against the f32 `0x3c23d70a` at `0x8029d0`); the WMO magma/slime compare has none.
 const SUBMERSION_EPS: f32 = 0.01;
 
-/// Which submerged atmosphere a liquid kind selects. Water/ocean/rapids take the zone's own
-/// underwater `LightParams` slot; magma and slime take fixed global rows instead, zone-independent
-/// (see [`benilla_formats::Submersion`]).
+/// The submerged atmosphere a liquid kind selects.
 fn submersion_of(kind: LiquidKind) -> benilla_formats::Submersion {
     use benilla_formats::Submersion;
     match kind {
         LiquidKind::Still | LiquidKind::Rapids => Submersion::Water,
-        // Ocean is its own verdict — it alone runs the depth ramp (decision 1829). It can only come
-        // from ADT MCLQ (`(b & 0x0f) & 3 == 1`); a WMO cannot author it, which is why no interior
-        // pool ever reaches this arm.
+        // Ocean alone runs the depth ramp; only ADT MCLQ authors it (`(b & 0x0f) & 3 == 1`).
         LiquidKind::Ocean => Submersion::Ocean,
         LiquidKind::Magma => Submersion::Magma,
         LiquidKind::Slime => Submersion::Slime,
     }
 }
 
-/// Set [`Underwater`] from the camera vs the liquid surfaces: the eye is submerged if it's over a wet
-/// cell and below that cell's surface (`FUN_0069b6d0` — its 9×9 bilinear sample is now what
-/// [`WaterChunkInfo::surface_z_at`] does, so this is the binary's own rule and no longer a per-chunk
-/// flat approximation of it). One pass over the loaded surfaces (a few hundred, cheap).
-///
-/// **The candidate set is the camera's own room, not the world.** The reference's per-frame
-/// environment probe `0x6809c0` reads the render eye `[0xc7cf20/24/28]` and then queries **one**
-/// source: the current WMO group's MLIQ (`0x6b9f10`) when `[0xc7b748]` names a containing
-/// map-object, otherwise the ADT liquid (`0x6723d0 → 0x69b6d0`) — VERIFIED, wow-re
-/// `terrain/scratch/fog-env-state.md` §1 (the two `[0xc7f288]` writers) and
-/// `ui/scratch/camera-arm-liquid-blind.md` §2's band census, which names both call sites inside
-/// `[0x6809c0, 0x680b90)`. We take the eye's claim from [`CameraInteriorClaim`], which
-/// `wmo_portal::compute_wmo_pvs` publishes off the very down-ray that writes `[0xc7b748]`.
-///
-/// This probe used to consult **every** loaded surface with no delegation at all, while the player's
-/// query had delegated since 0634 — so the two disagreed by construction, and the screen took the
-/// underwater filter in rooms the player was demonstrably dry in. Standing in Undercity's Rogues'
-/// Quarter at `(1414.08, 53.00, -62.26)`, 95 yd of rock below Tirisfal's ADT water at z 32.93, the
-/// player read "not in liquid" and the whole scene still rendered green (decision 0696).
-///
-/// **Every** liquid counts, including magma and slime — they are not the water murk, they are their
-/// own atmospheres (see [`Underwater`]). The eye's own **`+0.01` accept margin is water's alone**:
-/// byte-VERIFIED (`0x8029d0` = `0x3c23d70a` = 0.01, strict `<`, at `0x69ba23`) that the WMO
-/// magma/slime compare is a bare `z < h` with **no epsilon**, so the margin is applied per kind
-/// rather than uniformly.
-///
-/// Where surfaces stack, the **deepest submerging** one wins: standing in the Great Forge's lava
-/// under an unrelated water footprint should read as lava, and a `.any()` over an unordered query
-/// would otherwise answer with whichever entity the ECS happened to yield first.
-/// Which submerged atmosphere a position is in — the verdict [`detect_submersion`] publishes, as a
-/// plain function of a candidate set so it can be asked of the shipped files in a test.
-///
-/// It lived inline in the system until decision 0701, where the Undercity storey bug turned on it:
-/// the defect was never visible to [`liquid_at`] (which answers "the liquid over this XY", lowest
-/// wins, whether or not you are under it) but only to *this* rule — "every admitted surface the eye
-/// is beneath". A rule no test can call is a rule that drifts from the one being reasoned about.
-/// The verdict alone, for the tests that assert on it — a thin delegation to
-/// [`submersion_claim_at`], never a second copy of the rule. It restated the filter for about an
-/// hour of this change, and that was already one copy too many: the reason the surface height is
-/// threaded out of a *single* pass is precisely that two passes can disagree (decision 0701).
+/// The verdict alone, for tests: [`submersion_claim_at`] without the height.
 #[cfg(test)]
 pub(super) fn submersion_at<'a>(
     liquids: impl Iterator<Item = &'a WaterChunkInfo>,
@@ -886,13 +619,10 @@ pub(super) fn submersion_at<'a>(
     submersion_claim_at(liquids, wow, claim).map_or_else(Default::default, |(s, _)| s)
 }
 
-/// [`submersion_at`]'s verdict **and the surface it came from** — the same rule, one value wider.
-///
-/// The surface height is what the reference's own probe keeps beside the verdict (`0x680a87` /
-/// `0x680ab0` write the pair), and two consumers need it: the glare's depth fade wants
-/// `surface − probe` and the ocean ramp wants to know it is standing on a sea. Deriving it a second
-/// time from a second pass over the surfaces would be a rule that could drift from this one — the
-/// mistake decision 0701 already paid for once.
+/// The liquid a WoW position is submerged in and that surface's height, one pass for both, as the
+/// reference's probe writes the pair (`0x680a87`/`0x680ab0`). Every admitted kind counts; the
+/// position must be under a wet cell's bilinear surface, as `0x69b6d0` samples its 9×9 grid, and
+/// where surfaces stack the lowest one over the position wins.
 pub(super) fn submersion_claim_at<'a>(
     liquids: impl Iterator<Item = &'a WaterChunkInfo>,
     wow: [f32; 3],
@@ -913,13 +643,8 @@ pub(super) fn submersion_claim_at<'a>(
         .map(|(z, s)| (s, z))
 }
 
-/// The camera-eye liquid state as ONE system parameter — the verdict and the two scalars together.
-///
-/// They are read as a unit because they are written as a unit, by one probe in one frame slot
-/// ([`super::SubmersionVerdict`]); binding them separately invites a consumer that takes the depth
-/// from this frame and the verdict from the last. It also keeps a caller under Bevy's 16-parameter
-/// ceiling, which is what forced the bundle — [`crate::lighting::resolve::update_time_lighting`]
-/// reads sixteen other things.
+/// The camera eye's liquid state as one system parameter: the verdict and its two scalars, written
+/// together in [`super::SubmersionVerdict`] and so read together.
 #[derive(bevy::ecs::system::SystemParam)]
 pub struct EyeLiquid<'w> {
     verdict: Option<Res<'w, Underwater>>,
@@ -927,12 +652,12 @@ pub struct EyeLiquid<'w> {
 }
 
 impl EyeLiquid<'_> {
-    /// What the eye is in — [`benilla_formats::Submersion::Dry`] before the probe has ever run.
+    /// What the eye is in; `Dry` before the probe first runs.
     pub fn submersion(&self) -> benilla_formats::Submersion {
         self.verdict.as_ref().map_or_else(Default::default, |v| v.0)
     }
 
-    /// The eye's absolute world Z — the ocean ramp's raw input.
+    /// The eye's absolute world Z, the ocean ramp's input.
     pub fn eye_z(&self) -> f32 {
         self.eye.as_ref().map_or(0.0, |e| e.eye_z)
     }
@@ -943,31 +668,20 @@ impl EyeLiquid<'_> {
     }
 }
 
-/// The submerged camera's two scalars, published beside [`Underwater`] for the consumers that need
-/// a *distance* rather than a verdict (decision 1829).
+/// The submerged camera's two scalars, published beside [`Underwater`].
 #[derive(bevy::prelude::Resource, Default, Clone, Copy)]
 pub struct SubmergedEye {
-    /// `liquidSurfaceHeight − probeZ` in world-Z yards, **positive when submerged** and `0.0` when
-    /// dry — the quantity the reference writes at `0x680a87`/`0x680ab0`. Drives the glare's 10-yard
-    /// fade. Not a ray distance and not an occluder term.
+    /// `liquidSurfaceHeight − probeZ` in yards, positive when submerged and `0.0` when dry, as the
+    /// reference writes it at `0x680a87`/`0x680ab0`; drives the glare's 10 yd fade.
     pub depth: f32,
-    /// The camera eye's own absolute world Z. The ocean depth ramp clamps this raw
-    /// (`t = clamp(eye.z, −30, 0)`) rather than working from [`Self::depth`], because ocean
-    /// surfaces are pinned to z = 0 by a code branch (`0x69ba85`) rather than by data — so for the
-    /// one state that runs the ramp the two agree, and the absolute form is what the binary reads.
+    /// The eye's absolute world Z. The ocean ramp clamps it raw, `clamp(eye.z, −30, 0)`, since
+    /// ocean surfaces are pinned to z = 0 by a branch (`0x69ba85`), not by data.
     pub eye_z: f32,
 }
 
-/// How far the near rectangle's **lowest corner** sits below the eye (≤ 0, WoW-Z = Bevy-Y yards) —
-/// `min(0, corner heights − eye)`, so `eye_z + drop` is the reference's probe height
-/// `min(eye.z, corner[0..3].z)`. Zero when the camera pitches up enough that every corner clears
-/// the eye — the min with the eye itself is what keeps a skyward camera from probing above its
-/// own head. Pure (rotation + the projection's shape in, one height out) so the geometry is
-/// testable without ECS scaffolding, like [`submersion_at`].
-///
-/// The corners sit `near` ahead of the eye, `±tan(fov/2)·near` up/down and that times the aspect
-/// ratio sideways, in CAMERA space (Bevy: forward = −Z) — the same four points the reference
-/// builds from NDC z = −1 (`0x5c43b0`; wow-re `water-frame-straddle.md` §4c).
+/// How far the near rectangle's lowest corner sits below the eye, `≤ 0` yd: `eye_z + drop` is the
+/// reference's probe height `min(eye.z, corner[0..3].z)`, its corners built from NDC z = −1
+/// (`0x5c43b0`).
 pub(super) fn lowest_near_corner_drop(rotation: Quat, fov: f32, aspect: f32, near: f32) -> f32 {
     let half_h = (fov * 0.5).tan() * near;
     let half_w = half_h * aspect;
@@ -980,8 +694,10 @@ pub(super) fn lowest_near_corner_drop(rotation: Quat, fov: f32, aspect: f32, nea
     drop
 }
 
-// Eight parameters: the probe reads a camera, the loaded surfaces, two scoping resources and a
-// clock, then writes the verdict and its two scalars. They are the inputs the rule has.
+// The reference's camera probe spans `[0x6809c0, 0x680b90)`: it reads the render eye
+// `[0xc7cf20/24/28]`, samples one source, the current group's MLIQ (`0x6b9f10`) when `[0xc7b748]`
+// names a containing map-object, else the ADT liquid (`0x6723d0` → `0x69b6d0`), and writes
+// `[0xc7f288]`. `CameraInteriorClaim` comes off the down-ray that writes `[0xc7b748]`.
 pub(super) fn detect_submersion(
     mut underwater: ResMut<Underwater>,
     camera: Query<(&Transform, &Projection), With<WorldCamera>>,
@@ -996,15 +712,10 @@ pub(super) fn detect_submersion(
         return;
     };
     let claim = camera_claim(&eye_claim, &placements);
-    let eye = bevy_to_wow(cam.translation); // [x, y, z] WoW yards
-                                            // The probe HEIGHT is not the eye's — it is the lowest point of the NEAR RECTANGLE (or the
-                                            // eye itself if every corner sits above it): the reference's `0x6809c0` tests X,Y = the
-                                            // eye's, Z = `min(eye.z, corner[0..3].z)` over the frustum corners built at NDC z = −1 —
-                                            // VERIFIED, wow-re `water-frame-straddle.md` §4c. This is the whole no-straddle mechanism
-                                            // (§4d): the frame flips submerged the moment the visible rectangle's leading corner reaches
-                                            // the surface, before any under-surface viewpoint can render dry — so the crossing needs no
-                                            // camera constraint at all (the 0905 eye snap this replaces), and with the reference's 1/9
-                                            // near plane the band it owns is a few inches tall.
+    let eye = bevy_to_wow(cam.translation);
+    // `0x6809c0` tests the eye's XY at the near rectangle's lowest point, `min(eye.z,
+    // corner[0..3].z)`, so the frame turns submerged as the view's leading corner reaches the
+    // surface and no under-surface view renders dry, with no camera constraint needed.
     let probe_z = match proj {
         Projection::Perspective(p) => {
             eye[2] + lowest_near_corner_drop(cam.rotation, p.fov, p.aspect_ratio, p.near)
@@ -1013,30 +724,20 @@ pub(super) fn detect_submersion(
     };
     let verdict = submersion_claim_at(water.iter(), [eye[0], eye[1], probe_z], claim);
     underwater.0 = verdict.map(|(s, _)| s).unwrap_or_default();
-    // Depth is measured from the PROBE, not the eye — the probe is what decided we are submerged at
-    // all, so a fade driven off the eye would disagree with the verdict in the inches-tall band the
-    // near rectangle owns.
+    // Depth from the probe, not the eye, so the fade agrees with the verdict.
     submerged_eye.depth = verdict.map_or(0.0, |(_, z)| (z - probe_z).max(0.0));
     submerged_eye.eye_z = eye[2];
-    // `WOW_FOG_DUMP` also explains *this* decision (`frame` drops the 1 Hz throttle, as there). The
-    // committed fog is whichever submerged atmosphere the verdict names, so a fog line alone cannot
-    // say whether an atmosphere that reads wrong is the wrong record or the right record never
-    // selected. Reports the eye, the verdict, and every candidate surface over the eye's XY.
+    // `WOW_FOG_DUMP`: once a second, the eye, the verdict and every surface over the eye's XY.
     static FOG_DUMP: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     if *FOG_DUMP.get_or_init(|| std::env::var_os("WOW_FOG_DUMP").is_some()) {
         let sec = time.elapsed_secs() as u32;
         if last_dump.replace(sec) != Some(sec) {
-            // Every surface over the eye's XY, whether or not the eye's claim admits it — a
-            // candidate the delegation REJECTED is exactly what the Undercity green-screen report
-            // needed to see, and a list filtered to the winners can never show it.
+            // Rejected candidates too, marked, since a wrong verdict needs them seen.
             let mut cands: Vec<String> = water
                 .iter()
                 .filter_map(|w| {
                     w.surface_z_at(eye[0], eye[1]).map(|z| {
-                        // Name the owner's GROUP, not just whether the claim admits it: with
-                        // placement scoping a pool in another STOREY of the same building still
-                        // answers, and its group index is the only thing on this line that tells
-                        // it apart from the room's own pool.
+                        // The owner's group tells another storey's pool from the room's own.
                         format!(
                             "{:?} z {z:.2} {}{}",
                             w.kind,
@@ -1074,10 +775,8 @@ pub(super) fn detect_submersion(
 mod tests {
     use super::*;
 
-    /// The corner-min probe geometry (`min(eye.z, corner z's)` as an offset from the eye): level
-    /// pitch reaches half the near rectangle's height down, straight down reaches the full near
-    /// distance, straight up reaches nothing (the min with the eye itself), and yaw never enters
-    /// (no roll ⇒ the rectangle's width is world-horizontal at every heading).
+    /// Level reaches half the near rectangle's height down, straight down the full near distance,
+    /// straight up nothing, and yaw never enters.
     #[test]
     fn near_corner_drop_is_the_rectangles_lowest_point() {
         let (fov, aspect, near) = (std::f32::consts::FRAC_PI_4, 16.0 / 9.0, 1.0 / 9.0);
@@ -1096,7 +795,7 @@ mod tests {
         assert!((at(1.23, -0.4) - at(0.0, -0.4)).abs() < 1e-6);
     }
 
-    /// A flat 10×10 yd wet quad at WoW z = `z` — one cell, four corners.
+    /// A flat one-cell 10 yd wet quad at WoW z = `z`.
     fn flat_quad(z: f32) -> LiquidMesh {
         LiquidMesh {
             grid: [2, 2],
@@ -1117,8 +816,7 @@ mod tests {
         }
     }
 
-    /// One `cols × rows` grid of `step`-yard cells with its corner at the origin, heights from
-    /// `z(i, j)`, and the given per-cell wetness.
+    /// A `cols × rows` grid of `step`-yard cells from the origin, with heights `z(i, j)`.
     fn grid_info(
         source: LiquidSource,
         kind: LiquidKind,
@@ -1137,21 +835,16 @@ mod tests {
         WaterChunkInfo::new(source, kind, [cols, rows], positions, wet)
     }
 
-    /// A flat one-cell surface at `z`, 10 yd square — the fixture for the tests that are about the
-    /// delegation or the stacking rule, not about the height sample.
+    /// A flat one-cell surface at `z`, 10 yd square.
     fn flat_info(source: LiquidSource, kind: LiquidKind, z: f32) -> WaterChunkInfo {
         grid_info(source, kind, 2, 2, 10.0, vec![true], move |_, _| z)
     }
 
-    /// A stand-in placement identity — two distinct buildings, so "whose pool is this" is testable
-    /// without a `World`. `Entity::from_raw_u32` is the only way to mint one outside an ECS.
     fn placement(n: u32) -> Entity {
         Entity::from_raw_u32(n).expect("valid entity id")
     }
 
-    /// A WMO pool owned by placement `n`, group 0, whose room has no floor — the fixture for the
-    /// tests that are about the OWNER half of the scope. The floor half gets its own fixture
-    /// ([`wmo_pool`]) so neither can silently stand in for the other.
+    /// A WMO pool owned by placement `owner`, group 0, with no floor.
     fn wmo_info(owner: u32, kind: LiquidKind, z: f32) -> WaterChunkInfo {
         flat_info(
             LiquidSource::WmoGroup(wmo_pool(owner, f32::NEG_INFINITY)),
@@ -1160,7 +853,6 @@ mod tests {
         )
     }
 
-    /// The scope of a pool in placement `n`'s group 0, whose room's floor is at `floor`.
     fn wmo_pool(owner: u32, floor: f32) -> WmoPool {
         WmoPool {
             owner: Some(WmoRoom {
@@ -1171,7 +863,7 @@ mod tests {
         }
     }
 
-    /// An unowned, unfloored pool — the portal-less placement's case.
+    /// An unowned, unfloored pool: a portal-less placement's.
     fn orphan_pool() -> WmoPool {
         WmoPool {
             owner: None,
@@ -1179,7 +871,6 @@ mod tests {
         }
     }
 
-    /// The claim of a subject standing inside placement `n`.
     fn inside(owner: u32) -> LiquidClaim {
         LiquidClaim::inside(WmoRoom {
             instance: placement(owner),
@@ -1187,8 +878,7 @@ mod tests {
         })
     }
 
-    /// The claim of a subject standing inside placement `n`'s group 0, where that group carries the
-    /// whole-group submersion override.
+    /// The claim of a subject in placement `owner`'s group 0, flooded whole with `kind`.
     fn inside_flooded(owner: u32, kind: LiquidKind) -> LiquidClaim {
         LiquidClaim::Inside {
             room: WmoRoom {
@@ -1199,11 +889,7 @@ mod tests {
         }
     }
 
-    /// The Deeprun Tram's flooded sections, the Prison Oubliette and the two MD caves carry a MOGP
-    /// `groupLiquid` and **no MLIQ chunk at all**: there is no grid, no surface and no floor, and
-    /// the room is submerged everywhere inside it. So the query must answer with an empty world —
-    /// which is exactly what those rooms hand it — and must answer the same at any depth, because
-    /// `0x6b9f10`'s override leg runs before any Z compare exists.
+    /// A flooded room has no MLIQ at all, and `0x6b9f10`'s override leg runs before any Z compare.
     #[test]
     fn a_flooded_room_is_submerged_at_every_z_with_no_surface_in_the_world() {
         let claim = inside_flooded(1, LiquidKind::Still);
@@ -1223,12 +909,8 @@ mod tests {
         }
     }
 
-    /// The override is the room's WHOLE answer, not one more candidate in the `min_by`.
-    ///
-    /// This is the trap the reference's own ordering avoids: `0x6b9f10` reads `groupLiquid` before
-    /// it touches the grid, so a pool elsewhere in the same placement never gets a vote. Folded in
-    /// as a candidate instead, `FLT_MAX` loses every tie — and the flooded tunnel would report the
-    /// surface of a puddle two rooms away, at a height the subject is standing well above.
+    /// `0x6b9f10` reads `groupLiquid` before the grid, so a sibling pool never gets a vote, where
+    /// as a `min_by` candidate `FLT_MAX` would lose to it.
     #[test]
     fn the_override_outranks_a_sibling_pool_rather_than_losing_the_min() {
         let sibling = wet_footprint(
@@ -1238,11 +920,9 @@ mod tests {
         );
         let feet = [5.0, 5.0, -50.0];
 
-        // Without the override the sibling pool answers, at its own low surface.
         let plain = liquid_at(std::iter::once(&sibling), feet, inside(1)).expect("the pool");
         assert_eq!(plain.surface_z, -100.0);
 
-        // With it, the room does — and nothing about the pool changes the answer.
         let flooded = liquid_at(
             std::iter::once(&sibling),
             feet,
@@ -1252,17 +932,14 @@ mod tests {
         assert_eq!(flooded.surface_z, f32::MAX);
     }
 
-    /// The 5207 groups that carry the `0xf` sentinel must be untouched — the override only ever
-    /// *adds* water, and a claim without one is the pre-1000 query exactly (decision 1000).
+    /// A group carrying the `0xf` sentinel takes the plain query: the override only adds water.
     #[test]
     fn a_room_without_the_override_is_the_old_query_unchanged() {
         assert!(liquid_at(std::iter::empty(), [0.0, 0.0, 0.0], inside(1)).is_none());
         assert!(liquid_at(std::iter::empty(), [0.0, 0.0, 0.0], LiquidClaim::Outdoors).is_none());
     }
 
-    /// `/liquid` in a flooded room has no footprint to list, which is the mechanism working. The
-    /// instrument has to say so, or its silence reads as "the query is broken" next to a verdict
-    /// that says submerged.
+    /// `/liquid` in a flooded room names the override, which has no footprint to list.
     #[test]
     fn the_instrument_names_the_override_it_has_no_footprint_for() {
         let lines = describe_at(
@@ -1275,9 +952,7 @@ mod tests {
         assert!(describe_at(std::iter::empty(), [0.0, 0.0, 0.0], inside(1)).is_empty());
     }
 
-    /// MCLQ water passes `IDENTITY`: `bevy_to_wow(wow_to_bevy(p))` is a pure axis permutation with
-    /// sign flips, so the footprint must equal the raw wet-vertex bounds exactly (bit-for-bit — the
-    /// refactor that routed MCLQ through `wet_footprint` must not move a single lake edge).
+    /// Under `IDENTITY` the axis round trip is a pure permutation, so MCLQ bounds are bit-exact.
     #[test]
     fn identity_footprint_is_the_raw_bounds() {
         let info = wet_footprint(
@@ -1290,11 +965,8 @@ mod tests {
         assert_eq!(info.surface_z_at(5.0, 5.0), Some(5.0));
     }
 
-    /// A WMO canal under a yaw-only building placement (spin about vertical + a world lift): the
-    /// water plane stays LEVEL, so the sampled height must equal the local height plus the
-    /// placement's vertical lift, for EVERY yaw — and the cell lookup must still find the quad's
-    /// own centre after the spin, which is the property the world-space grid rests on. (Bevy +Y is
-    /// up; a WoW z-lift is a Bevy +Y translate.)
+    /// Under any yaw plus a lift the surface stays level at the local height plus the lift, and the
+    /// cell lookup still finds the spun quad's centre.
     #[test]
     fn yaw_placement_keeps_the_surface_level() {
         let lift = 3.0_f32;
@@ -1320,15 +992,10 @@ mod tests {
         }
     }
 
-    /// **The height rule** (director repro, Blackrock's lava and Felwood's river). A liquid grid is
-    /// a heightfield: the surface at an XY is the BILINEAR of its cell's four corners, never the
-    /// chunk's highest vertex. Over a cell rising 0 → 8 yd, the maximum is 8 everywhere while the
-    /// true surface runs the full ramp — which is exactly how a spot metres under the lava read as
-    /// metres over it.
+    /// The surface at an XY is the bilinear of its cell's corners, never the grid's highest vertex.
     #[test]
     fn the_surface_is_the_bilinear_of_its_cell_not_the_chunk_maximum() {
-        // One 10 yd cell; corner heights 0 / 4 (+x) / 2 (+y) / 8 (+x+y) — a genuine twist, so a
-        // plane fit through any three corners cannot reproduce the fourth.
+        // Corners 0 / 4 (+x) / 2 (+y) / 8 (+x+y): a twist no plane through three corners fits.
         let info = grid_info(
             LiquidSource::AdtChunk,
             LiquidKind::Still,
@@ -1361,13 +1028,12 @@ mod tests {
                 "bilinear at ({x}, {y}): got {got}, want {want}"
             );
         }
-        // The old rule — the chunk's highest wet vertex — would answer 8.0 at every one of those.
+        // The grid's highest wet vertex would answer 8.0 at every one.
         assert!(info.surface_z_at(0.0, 0.0).unwrap() < 8.0);
     }
 
-    /// The delegation, which is the whole "swim in air" fix: a tunnel bored under a lake sits inside
-    /// the lake's flat XY footprint (footprints have no floor), so before the source split it read as
-    /// submerged. Inside a WMO only WMO liquid answers; outdoors only ADT liquid does.
+    /// Inside a WMO only its liquid answers and outdoors only the ADT's, so a tunnel under a lake,
+    /// inside the lake's floorless footprint, is dry.
     #[test]
     fn indoors_and_outdoors_see_different_liquid() {
         let lake = flat_info(LiquidSource::AdtChunk, LiquidKind::Still, 50.0);
@@ -1375,27 +1041,17 @@ mod tests {
         let all = [&lake, &canal];
         let deep_under = [5.0, 5.0, 0.0];
 
-        // Standing in the tunnel: the lake 50 yd overhead must NOT answer.
+        // In the tunnel: the lake 50 yd overhead does not answer.
         let hit = liquid_at(all.into_iter(), deep_under, inside(1)).unwrap();
         assert_eq!(hit.surface_z, 8.0, "indoors must read the WMO's own liquid");
-        // Out on the surface: the ADT lake answers and the building's canal does not.
         let outside = liquid_at(all.into_iter(), deep_under, LiquidClaim::Outdoors).unwrap();
         assert_eq!(outside.surface_z, 50.0);
-        // Un-classified (a unit's first frame): both sources answer — the pre-0634 behaviour, and
-        // the ONLY arm that still has it.
+        // Unclassified (a unit's first frame): both sources answer.
         assert!(liquid_at(all.into_iter(), deep_under, LiquidClaim::Unknown).is_some());
-        // Outside the XY footprint nothing answers, either way.
         assert!(liquid_at(all.into_iter(), [99.0, 99.0, 0.0], LiquidClaim::Outdoors).is_none());
     }
 
-    /// **The Uldaman bug** (director repro at `-6152.73, -2969.59, 213.73`): the claiming surface
-    /// belonged to a DIFFERENT BUILDING. Offline against the real client files, the player stands in
-    /// `kz_uldaman_a.wmo` (id 1218) group 22 — which carries no liquid over that XY at all — while
-    /// the pool answering `+185.91` over their feet is group 1 of a `md_mushroomcave.wmo` placement
-    /// whose every group bbox EXCLUDES the player, 186 yd overhead.
-    ///
-    /// A footprint has no floor, so "indoors" as a bare bool admitted every MLIQ surface on the map.
-    /// Being inside building A must never read building B's water.
+    /// Inside one building, another building's pool never answers, at any height.
     #[test]
     fn another_buildings_pool_never_claims_you() {
         let mine = wmo_info(1, LiquidKind::Still, 8.0);
@@ -1410,31 +1066,22 @@ mod tests {
             8.0,
             "in building 1: only building 1's pool"
         );
-        // In building 2 the tall pool IS yours — the scoping is an attribution, not a height cap.
+        // In building 2 the tall pool is yours: scoping attributes a pool, it does not cap height.
         assert_eq!(
             liquid_at(all.into_iter(), feet, inside(2))
                 .unwrap()
                 .surface_z,
             190.0
         );
-        // The Uldaman shape exactly: standing in a building with no pool of its own, under someone
-        // else's. Pre-0696 the lowest of the two answered and the player swam in air.
+        // A building with no pool of its own, under another's (Uldaman under a cave's pool).
         assert!(
             liquid_at([&theirs].into_iter(), feet, inside(1)).is_none(),
             "building 1 has no liquid; building 2's must not stand in for it"
         );
     }
 
-    /// **The Undercity storey bug** (decision 0701): a pool in ANOTHER GROUP of the SAME placement,
-    /// far above, still claimed you — owner scoping bounds a pool sideways to one building but not
-    /// downwards to one room. Live repro at `.go xyz 1732.68 187.01 -65.70`: the eye's own room
-    /// (group 182) held slime at z −64.48, *below* the eye and so not submerging it, while groups 7
-    /// and 10 — the Ruins-of-Lordaeron-level channels at z 51.98, **115 yd overhead** — were what
-    /// turned the screen green.
-    ///
-    /// The floor is the fix, and the second half of this test is the reason it is a floor and not
-    /// the reference's whole per-group AABB: a subject genuinely in a pool is always above the
-    /// floor of the room holding it, so the bound cannot cost a swim.
+    /// A pool in another storey of the same placement never claims the room below, and the floor
+    /// never costs a room its own pool.
     #[test]
     fn a_pool_upstairs_does_not_claim_the_room_below() {
         // Undercity's shape, in miniature: one placement, two rooms stacked 115 yd apart.
@@ -1450,9 +1097,7 @@ mod tests {
         );
         let all = [&upstairs, &downstairs];
 
-        // The eye, standing in the lower room ABOVE its own slime. What turned the screen green was
-        // the SUBMERSION rule — "every surface over the eye that the eye is under" — so that is what
-        // this pins: the upstairs pool must not be a candidate for the eye at all.
+        // The eye in the lower room, above its own slime: the upstairs pool is no candidate at all.
         assert!(
             !upstairs.answers(inside(1), -63.59),
             "a pool 115 yd overhead, in another storey of the same building, must not submerge you"
@@ -1461,21 +1106,17 @@ mod tests {
             downstairs.answers(inside(1), -63.59),
             "…while the eye's OWN room's pool stays a candidate (it is simply below the eye)"
         );
-        // Step down into the lower room's OWN slime and it still answers — the floor bounds the
-        // pool to its room, it does not cap how deep the room's own liquid reaches.
+        // Down in the lower room's own slime, its pool still answers.
         assert_eq!(
             liquid_at(all.into_iter(), [5.0, 5.0, -66.0], inside(1))
                 .unwrap()
                 .surface_z,
             -64.48
         );
-        // …and upstairs, standing in the upper channels, they answer as they always did.
         assert!(upstairs.answers(inside(1), 50.0));
     }
 
-    /// The floor is a property of the POOL, not of the delegation, so it holds for a subject whose
-    /// claim has not been computed yet. An `Unknown` claim admits both sources — it must not also
-    /// re-admit the pool three storeys up that every other claim rejects.
+    /// The floor belongs to the pool, not the claim, so it holds for an `Unknown` claim too.
     #[test]
     fn the_floor_holds_even_for_an_unclassified_subject() {
         let upstairs = flat_info(
@@ -1497,9 +1138,7 @@ mod tests {
         .is_some());
     }
 
-    /// A group with no bounds has no floor — a missing box fails OPEN (claims as it used to), never
-    /// closed. Closing would turn "a pool claims too much" into "a lake nobody can swim in", which
-    /// is the worse failure and the harder one to notice.
+    /// A group with no bounds has no floor: a missing box fails open.
     #[test]
     fn a_pool_with_no_bounds_keeps_its_pre_floor_reach() {
         let unbounded = WmoPool::new(
@@ -1515,9 +1154,7 @@ mod tests {
         assert!(liquid_at([&pool].into_iter(), [5.0, 5.0, -9999.0], inside(1)).is_some());
     }
 
-    /// The floor comes off the group box carried through the PLACEMENT transform, over all eight
-    /// corners — a rotated placement's lowest corner is not the box's own `bbox_min`. Checked
-    /// against a roll that swaps which corner is lowest.
+    /// The floor is the lowest of the eight placed corners, under a lift and under a roll.
     #[test]
     fn the_floor_follows_the_placement_transform() {
         let bounds = benilla_formats::WmoGroupInfo {
@@ -1533,8 +1170,7 @@ mod tests {
             Some(&bounds),
         );
         assert!((lifted.floor - 100.0).abs() < 1e-3, "got {}", lifted.floor);
-        // Rolled 90° about the Bevy Z axis (a WoW-X roll): the box's ±10 half-width in one
-        // horizontal axis now reaches DOWN, so the floor is 10 below the placement, not 0.
+        // Rolled 90° about Bevy Z (a WoW-X roll): a ±10 horizontal half-width now reaches down.
         let rolled = WmoPool::new(
             None,
             &Transform {
@@ -1551,8 +1187,7 @@ mod tests {
         );
     }
 
-    /// A pool on a placement that spawned no instance entity is claimable by nobody — the honest
-    /// consequence of having no owner, rather than a silent fallback to "everybody".
+    /// A pool on a placement with no instance entity answers no claim but `Unknown`.
     #[test]
     fn an_unowned_pool_answers_no_one() {
         let orphan = flat_info(
@@ -1563,15 +1198,10 @@ mod tests {
         let feet = [5.0, 5.0, 0.0];
         assert!(liquid_at([&orphan].into_iter(), feet, inside(1)).is_none());
         assert!(liquid_at([&orphan].into_iter(), feet, LiquidClaim::Outdoors).is_none());
-        // …but an un-classified subject still sees it, like every other surface.
         assert!(liquid_at([&orphan].into_iter(), feet, LiquidClaim::Unknown).is_some());
     }
 
-    /// **The Undercity camera bug** (director repro at `1414.08, 53.00, -62.26`): the player's query
-    /// said "not in liquid" while the camera-eye probe still saw Tirisfal's ADT water at z 32.93,
-    /// 95 yd overhead, and the whole scene took the underwater filter. Both subjects now run the
-    /// same delegation, so an indoor claim excludes the ADT surface for the eye exactly as it does
-    /// for the feet.
+    /// An indoor claim excludes the ADT water overhead for the eye as for the feet.
     #[test]
     fn an_indoor_eye_does_not_see_the_adt_water_overhead() {
         let tirisfal = flat_info(LiquidSource::AdtChunk, LiquidKind::Still, 32.93);
@@ -1586,8 +1216,7 @@ mod tests {
         );
     }
 
-    /// Stacked surfaces resolve to the LOWEST, not to whichever the iterator yields first — the old
-    /// `.next()` made the answer depend on spawn order.
+    /// Stacked surfaces resolve to the lowest, in any iteration order.
     #[test]
     fn stacked_surfaces_take_the_lowest() {
         let upper = wmo_info(1, LiquidKind::Still, 40.0);
@@ -1598,10 +1227,7 @@ mod tests {
         }
     }
 
-    /// Lava and slime ARE swimmable (`liquid_at`) but must never drive the water-flavoured
-    /// consumers (`water_surface_at` → the wade splash, footstep depth, the spline depth). B24/B25 vs
-    /// the teal-lava regression the old fullbright exclusion was guarding against — both, at once.
-    /// The submerged atmosphere is deliberately NOT in that list any more: it is per-kind.
+    /// Lava and slime are swimmable but never water to the wade splash and depth consumers.
     #[test]
     fn fullbright_kinds_swim_but_are_not_water() {
         let lava = wmo_info(1, LiquidKind::Magma, 6.0);
@@ -1614,15 +1240,10 @@ mod tests {
         );
     }
 
-    /// **The canal-tunnel bug** (director repro at `-8889.49, 765.26, 93.38`, `/liquid` output:
-    /// one candidate, `xy [-8927..-8832, 688..768]`, surface +2.09 over the feet). A liquid grid is
-    /// sparse — its bounding box spans dry ground the wet cells never cover — so containment must
-    /// test the CELLS. Bounding-box containment is what kept the Stormwind canal claiming the dry
-    /// mage-district tunnel through the whole of 0634.
+    /// Containment tests the cells, not the box, which spans dry ground.
     #[test]
     fn a_dry_spot_inside_the_bounding_box_is_not_liquid() {
-        // Three cells in a row; the MIDDLE one is a hole, so the box spans dry ground between two
-        // wet halves — the canal-either-side-of-a-tunnel shape.
+        // Three cells in a row, the middle one a hole: a canal on either side of a tunnel.
         let info = grid_info(
             LiquidSource::WmoGroup(wmo_pool(1, f32::NEG_INFINITY)),
             LiquidKind::Still,
@@ -1641,14 +1262,12 @@ mod tests {
             info.surface_z_at(15.0, 5.0).is_none(),
             "inside the box but over the HOLE — must NOT be liquid (the canal tunnel)"
         );
-        // And the query agrees, which is what actually decides swimming.
         assert!(liquid_at([&info].into_iter(), [5.0, 5.0, 0.0], inside(1)).is_some());
         assert!(liquid_at([&info].into_iter(), [15.0, 5.0, 0.0], inside(1)).is_none());
     }
 
-    /// A grid we cannot invert (here a plane stood on edge, so it projects to a line in XY) falls
-    /// back to its bounds and its highest wet vertex, rather than reporting the whole box dry — a
-    /// wrong "no liquid" is a player falling through a lake, the strictly worse failure.
+    /// A grid that cannot be inverted (a plane on edge) falls back to its bounds and its highest
+    /// wet vertex rather than reading dry.
     #[test]
     fn a_degenerate_grid_falls_back_to_the_bounds() {
         let info = WaterChunkInfo::new(
@@ -1667,13 +1286,7 @@ mod tests {
         assert_eq!(info.surface_z_at(50.0, 5.0), None, "still bounded in XY");
     }
 
-    /// A malformed grid (dimensions that don't match the arrays) claims nothing at all — no bounds,
-    /// so no surface. Better a liquid that isn't there than one that swallows the map.
-    ///
-    /// It must also be *inert*, not merely unclaimed: every walker over the grid — the foam cell
-    /// walk, the `/liquid` range — indexes `positions` from the declared dimensions, so a grid that
-    /// kept 9×9 dimensions over a 4-vertex array would read off the end. The constructor normalizes
-    /// it to empty instead of leaving each walker to re-check.
+    /// A grid whose dimensions don't match its arrays claims nothing and walks nothing.
     #[test]
     fn a_malformed_grid_claims_nothing_and_walks_nothing() {
         let info = WaterChunkInfo::new(
diff --git a/crates/benilla-world/src/liquid/real_data.rs b/crates/benilla-world/src/liquid/real_data.rs
index 5d06874f..e9f0ea95 100644
--- a/crates/benilla-world/src/liquid/real_data.rs
+++ b/crates/benilla-world/src/liquid/real_data.rs
@@ -1,9 +1,5 @@
-//! The liquid subsystem against the **real 1.12.1 client files** — the tests that need actual ADT
-//! and WMO bytes rather than a synthetic quad, so they live apart from either half's unit tests and
-//! reach across both: they build surfaces the way `super::surface`'s spawn paths do and then ask
-//! `super::query` the same questions the running client asks.
-//!
-//! Every one skips when the client isn't present (the repo never carries Blizzard data).
+//! The liquid queries against the real client files: surfaces built as the spawn paths build them,
+//! asked what the running client asks. Each test skips without an install.
 
 use bevy::prelude::*;
 
@@ -14,18 +10,11 @@ use crate::wmo_portal::WmoRoom;
 use benilla_assets::coords::{bevy_to_wow, placement_rotation, wow_to_bevy};
 use benilla_formats::{parse_wmo_root, wmo_group_liquid_mesh, LiquidMesh, Submersion};
 
-/// Every loaded liquid surface covering a position's tile neighbourhood, world-placed and
-/// **owner-tagged** — the ADT's own MCLQ chunks and every WMO placement's MLIQ groups, i.e. the same
-/// candidate set the running client's `WaterChunkInfo` query sees, scoped the same way.
-///
-/// Each WMO placement gets a synthetic instance id (its index here) standing in for the
-/// `WmoPortalInstance` entity the app spawns; `containing_room` then answers the question the app's
-/// interior down-ray answers at runtime — *which* placement the subject is standing in — so a test
-/// can pose the real query with the real claim.
+/// The world-placed, owner-tagged liquid around a position: its tiles' MCLQ and every WMO
+/// placement's MLIQ, each placement under a synthetic instance id for the app's entity.
 struct LiquidScene {
     surfaces: Vec<WaterChunkInfo>,
-    /// Per placement: its synthetic instance id, model path, placement transform, and group
-    /// bounding boxes (WMO model space) — the containment test.
+    /// Each placement with its group boxes in model space, for the containment test.
     placements: Vec<Placement>,
 }
 
@@ -37,13 +26,8 @@ struct Placement {
 }
 
 impl LiquidScene {
-    /// The room a world position stands in: the first placement one of whose group bounding boxes
-    /// contains it, and that group.
-    ///
-    /// A coarser test than the app's down-ray (which races collision FACES and the terrain), and
-    /// deliberately so — a test that re-implemented the down-ray would be pinning the test's copy of
-    /// it. Group-box containment is enough to answer "which building is this position in", which is
-    /// the only thing these two sites turn on.
+    /// The room a world position stands in: the first placement and group whose box contains it,
+    /// coarser than the app's down-ray but enough to name the building.
     fn containing_room(&self, wow: [f32; 3]) -> Option<WmoRoom> {
         self.placements.iter().find_map(|p| {
             let local = bevy_to_wow(
@@ -63,8 +47,7 @@ impl LiquidScene {
         })
     }
 
-    /// Which model path a room's placement came from — so a test can state *which building* it
-    /// believes the player is in rather than trusting an index.
+    /// The model path of a room's placement.
     fn model_of(&self, room: WmoRoom) -> &str {
         self.placements
             .iter()
@@ -73,7 +56,7 @@ impl LiquidScene {
     }
 }
 
-/// Build the [`LiquidScene`] around a position. Empty (`None`) when the client isn't present.
+/// The [`LiquidScene`] around a position; `None` without an install.
 fn liquid_scene(map: &str, wow: [f32; 3]) -> Option<LiquidScene> {
     let data = benilla_formats::wow_data()?;
     let mut chain = benilla_formats::open_chain(&data).expect("open chain");
@@ -83,8 +66,7 @@ fn liquid_scene(map: &str, wow: [f32; 3]) -> Option<LiquidScene> {
         placements: Vec::new(),
     };
     let mut seen_placements: Vec<u32> = Vec::new();
-    // A building as big as Blackrock is placed in every tile it straddles, so its MODF may sit
-    // in a neighbour of the tile the position falls in.
+    // A building is placed in every tile it straddles, so its MODF may sit in a neighbour tile.
     for dx in -1i32..=1 {
         for dy in -1i32..=1 {
             let (tx, ty) = ((cx as i32 + dx) as u32, (cy as i32 + dy) as u32);
@@ -99,8 +81,7 @@ fn liquid_scene(map: &str, wow: [f32; 3]) -> Option<LiquidScene> {
                 ));
             }
             for w in &tile.wmos {
-                // A straddling building appears in each tile's MODF — spawn it once, as the
-                // streamer does (it dedups on the same `unique_id`).
+                // Once per `unique_id`, as the streamer dedups a straddling building.
                 if seen_placements.contains(&w.unique_id) {
                     continue;
                 }
@@ -138,8 +119,7 @@ fn liquid_scene(map: &str, wow: [f32; 3]) -> Option<LiquidScene> {
                         scene.surfaces.push(wet_footprint(
                             lq_ref(&lq),
                             &transform,
-                            // Built through the APP's own constructor, not a copy of the rule —
-                            // a test that re-derived the floor would pin its own version of 0701.
+                            // The app's own constructor, so the test pins the app's floor rule.
                             LiquidSource::WmoGroup(WmoPool::new(
                                 Some(WmoRoom {
                                     instance,
@@ -161,8 +141,7 @@ fn lq_ref(lq: &LiquidMesh) -> &LiquidMesh {
     lq
 }
 
-/// The verdict at a position, and the highest wet vertex among the surfaces that claim it —
-/// i.e. what the query answers now, beside what the chunk-maximum rule used to answer.
+/// The surface the query answers at a position, and the highest wet vertex of those over its XY.
 fn verdict(map: &str, wow: [f32; 3], claim: LiquidClaim) -> Option<(f32, f32)> {
     let all = liquid_scene(map, wow)?.surfaces;
     let hit = liquid_at(all.iter(), wow, claim)?;
@@ -174,14 +153,11 @@ fn verdict(map: &str, wow: [f32; 3], claim: LiquidClaim) -> Option<(f32, f32)> {
     Some((hit.surface_z, old))
 }
 
-/// **Blackrock Mountain's lava** at the director's `.go xyz -7531.21 -1123.64 172.58` (indoors,
-/// `blackrock.wmo` group 038 — a 55×82 magma grid running 167.29 → 175.00 under a ~7° yaw
-/// placement). The old chunk-maximum answered 175.00, i.e. 2.42 yd OVER the feet and well past
-/// the 1.52 yd swim line, on a staircase whose lava is metres below.
+/// Blackrock's lava stairs at `-7531.21 -1123.64 172.58`, in `blackrock.wmo` group 038: a 55×82
+/// grid running 167.29 to 175.00 under a ~7° yaw, whose maximum sits 2.42 yd over the feet.
 #[test]
 fn blackrock_lava_is_below_the_feet_not_above_it() {
     let feet = [-7531.21_f32, -1123.64, 172.58];
-    // Blackrock's own placement owns the magma, and the player is in it.
     let scene = liquid_scene("Azeroth", feet);
     let claim = scene
         .as_ref()
@@ -206,10 +182,8 @@ fn blackrock_lava_is_below_the_feet_not_above_it() {
     );
 }
 
-/// **Felfire Hill's river** at the director's `.go xyz 1983.97 -2875.84 98.00` (outdoors, one
-/// MCNK's 9×9 MCLQ falling 95.78 → 99.56 across the chunk). The old chunk-maximum answered
-/// 99.56 — 1.56 yd over the feet, just past the 1.52 yd swim line — while the player stands on
-/// the bank with the water at their soles.
+/// Felfire Hill's river bank at `1983.97 -2875.84 98.00`: one MCNK's MCLQ falls 95.78 to 99.56,
+/// and the water is at the player's soles.
 #[test]
 fn felfire_hill_river_does_not_swim_on_the_bank() {
     let feet = [1983.97_f32, -2875.84, 98.00];
@@ -232,17 +206,8 @@ fn felfire_hill_river_does_not_swim_on_the_bank() {
     );
 }
 
-/// **B85 — Uldaman reads as UNDERWATER** (director repro, `.go xyz -6152.73 -2969.59 213.73`; the
-/// `/liquid` line read `VERDICT Still surface z 399.64 (+185.91 over feet)`, `WmoGroup … WET-CELL`).
-///
-/// The claiming pool is **another building's**. At these feet the player stands in
-/// `kz_uldaman_a.wmo` (WMOAreaTable id 1218) group 22 — which carries no MLIQ over this XY at all —
-/// while the surface answering `+185.91` is group 1 of a nearby `md_mushroomcave.wmo` placement,
-/// whose every group box excludes the player: their feet sit at local z −191.15 under a pool that
-/// runs local z −5.65…0.00, i.e. 186 yd overhead in a cave they have never entered.
-///
-/// A footprint has no floor, so before 0696 "indoors" (a bare bool) admitted every MLIQ surface on
-/// the map and the lowest one won. The two arms below are the bug and the fix on the same bytes.
+/// Uldaman at `-6152.73 -2969.59 213.73`: the player is in `kz_uldaman_a.wmo` group 22, which has
+/// no MLIQ here, 186 yd under group 1 of a `md_mushroomcave.wmo` placement's pool.
 #[test]
 fn uldaman_is_not_submerged_in_a_mushroom_caves_pool() {
     let feet = [-6152.73_f32, -2969.59, 213.73];
@@ -250,9 +215,7 @@ fn uldaman_is_not_submerged_in_a_mushroom_caves_pool() {
         eprintln!("skipping: no WoW client data");
         return;
     };
-    // The bug, on the shipped files: the pool B85 reported really is over this XY and really is
-    // 185.91 yd up. Read off the surfaces with NO delegation at all — the reported number is a
-    // property of the files, so the control must not run through any rule this test also judges.
+    // The control, off the surfaces with no delegation: the cave's pool is over this XY.
     let reported = scene
         .surfaces
         .iter()
@@ -266,15 +229,12 @@ fn uldaman_is_not_submerged_in_a_mushroom_caves_pool() {
     );
     assert!(reported - feet[2] > 185.0, "…and 186 yd overhead");
 
-    // Since 0701 that pool is rejected TWICE over, and the second bound is independent of the
-    // first: even a subject with no interior claim at all is out of the cave's room, 186 yd under
-    // its floor. B85 would not have needed the owner half.
+    // The floor alone rejects it, even for an unclassified subject 186 yd under the cave's room.
     assert!(
         liquid_at(scene.surfaces.iter(), feet, LiquidClaim::Unknown).is_none(),
         "the cave's pool is below-the-floor rejected even for an unclassified subject"
     );
 
-    // The fix: the player's room is Uldaman's own placement, and Uldaman has no pool here.
     let room = scene
         .containing_room(feet)
         .expect("the player stands inside a placement");
@@ -289,21 +249,9 @@ fn uldaman_is_not_submerged_in_a_mushroom_caves_pool() {
     );
 }
 
-/// **The Undercity STOREY bug** (decision 0701) — the same wrong-underwater-filter as B60, one
-/// storey further in, and the half owner scoping could not reach. Live repro at
-/// `.go xyz 1732.68 187.01 -65.70`, where `WOW_FOG_DUMP` read:
-///
-/// ```text
-/// [submerged] Slime claim Inside(WmoRoom { instance: …, group: 182 }) eye [1731.9 187.0 -63.59]
-///             over-xy  Slime z -64.48 g182,  Slime z 51.98 g10,  Slime z 51.98 g7
-/// ```
-///
-/// The eye's own room (group 182) holds slime at −64.48, *below* the eye and so not submerging it.
-/// What turned the screen green were groups 7 and 10 — Undercity's upper channels at z 51.98,
-/// **115 yd overhead** — which owner scoping admits because they are the same placement.
-///
-/// The server agrees the eye is dry there: `.gps` reports `Liquid level: -64.478561`, i.e. 0.9 yd
-/// *under* the eye.
+/// Undercity at `1732.68 187.01 -63.59`: the eye's room (group 182) holds slime at −64.48, under
+/// the eye, while groups 7 and 10 of the same placement run 115 yd overhead. The server's `.gps`
+/// agrees the eye is dry: liquid level −64.478561.
 #[test]
 fn undercitys_upper_channels_do_not_submerge_the_rooms_below() {
     let eye = [1732.68_f32, 187.01, -63.59];
@@ -311,8 +259,7 @@ fn undercitys_upper_channels_do_not_submerge_the_rooms_below() {
         eprintln!("skipping: no WoW client data");
         return;
     };
-    // The control, straight off the files with no delegation: the pools that were claiming the eye
-    // really are up at 51.98, and really are over this XY.
+    // The control, with no delegation: the pools over this XY are up at 51.98.
     let overhead: Vec<f32> = scene
         .surfaces
         .iter()
@@ -324,8 +271,7 @@ fn undercitys_upper_channels_do_not_submerge_the_rooms_below() {
         "the surfaces over the eye are Undercity's upper channels at 51.98 (got {overhead:?})"
     );
 
-    // …and they belong to the eye's OWN placement, which is why 0696's owner scoping let them
-    // through: this is a storey bug, not a building bug.
+    // They belong to the eye's own placement, so only the floor can reject them.
     let room = scene
         .containing_room(eye)
         .expect("the eye stands inside a placement");
@@ -335,14 +281,11 @@ fn undercitys_upper_channels_do_not_submerge_the_rooms_below() {
         scene.model_of(room)
     );
 
-    // The fix, asked of the rule the SCREEN runs: a pool never claims below its own room's floor,
-    // so nothing over the eye submerges it and the filter stays off.
     assert_eq!(
         submersion_at(scene.surfaces.iter(), eye, LiquidClaim::inside(room)),
         Submersion::Dry,
         "a pool 115 yd overhead, in another storey of the same building, must not submerge the eye"
     );
-    // And the room's OWN slime is untouched — step down into it and the screen goes green properly.
     let inside_the_slime = [eye[0], eye[1], -66.0];
     assert_eq!(
         submersion_at(
@@ -366,15 +309,8 @@ fn undercitys_upper_channels_do_not_submerge_the_rooms_below() {
     );
 }
 
-/// **B60 — Undercity's Rogues' Quarter under Tirisfal's water** (director repro,
-/// `.go xyz 1414.08 53.00 -62.26`; the `/liquid` line read `AdtChunk Still WET-CELL surface z 32.93
-/// (+95.19 over feet)` while the player's own VERDICT was already `none`).
-///
-/// The ADT chunk's lake covers the XY 95 yd overhead and the rooms are cut into the rock beneath it.
-/// The player's query had delegated since 0634 and read dry; the **camera-eye** probe and the
-/// **per-unit** swim marker had not, so the screen took the underwater filter and the NPCs swam on
-/// dry stone. All three subjects run this one predicate now, so the assertion below is what each of
-/// them asks.
+/// Undercity's Rogues' Quarter at `1414.08 53.00 -62.26`, 95 yd under Tirisfal's lake: the player,
+/// the camera eye and a unit all ask this one predicate.
 #[test]
 fn the_rogues_quarter_is_not_under_tirisfals_lake() {
     let feet = [1414.08_f32, 53.00, -62.26];
@@ -382,8 +318,7 @@ fn the_rogues_quarter_is_not_under_tirisfals_lake() {
         eprintln!("skipping: no WoW client data");
         return;
     };
-    // The control: the ADT surface really is there, really covers this XY, and really is 95 yd up —
-    // an un-delegated subject (the pre-0696 camera and creature marker) is submerged in it.
+    // The control: an unscoped subject is submerged in the ADT lake 95 yd up.
     let unscoped = liquid_at(scene.surfaces.iter(), feet, LiquidClaim::Unknown)
         .expect("Tirisfal's water covers this XY");
     assert!(
@@ -392,8 +327,7 @@ fn the_rogues_quarter_is_not_under_tirisfals_lake() {
         "the surface B60 reported (got {})",
         unscoped.surface_z
     );
-    // The fix: a subject standing in Undercity reads Undercity's own liquid — and there is none
-    // over this XY, in any of its 38 liquid groups.
+    // Inside Undercity, none of its 38 liquid groups covers this XY.
     let room = scene
         .containing_room(feet)
         .expect("the player stands inside a placement");
@@ -408,11 +342,8 @@ fn the_rogues_quarter_is_not_under_tirisfals_lake() {
     );
 }
 
-/// **The gradient the swim law is sized against** (decision 0644): Felwood's Felfire Hill
-/// channel, along the run the live probe swam. A liquid surface is a heightfield, and *how far
-/// from flat* is exactly what decides whether the swim latch's 1/36-yd hysteresis band can
-/// absorb travelling along it — so the slope `player::swim`'s regression test drives is pinned
-/// here against the shipped ADT instead of living as a constant someone can only take on faith.
+/// The Felfire Hill channel's slope, the one `player::swim`'s regression test drives against the
+/// swim latch's 1/36 yd band.
 #[test]
 fn the_felfire_channel_falls_about_a_tenth_of_a_yard_per_yard() {
     let (downstream, upstream) = ([1953.97_f32, -2866.84, 0.0], [2013.97_f32, -2866.84, 0.0]);
diff --git a/crates/benilla-world/src/liquid/spatial.rs b/crates/benilla-world/src/liquid/spatial.rs
index d99cac85..be2edb9d 100644
--- a/crates/benilla-world/src/liquid/spatial.rs
+++ b/crates/benilla-world/src/liquid/spatial.rs
@@ -1,35 +1,17 @@
-//! The liquid **spatial index** — which surfaces are over an XY, without walking them all.
-//!
-//! [`super::surfaces_at`] answers "what liquid is at this XY" by testing every loaded
-//! [`WaterChunkInfo`] in turn. That is fine for the consumers that ask once or twice a frame
-//! (the camera waterline, the submersion verdict, a footstep) — and it detonates the moment a
-//! consumer asks per *draw*: the water-plane interleave's mesh lane (0919) classified ~13k
-//! transparent batches against ~2.2k loaded surfaces every frame — 29 M box tests, 54 ms, the
-//! 2026-08-03 "60 → 12 fps" regression, measured at the Stormwind pin by the live FPS probe.
-//!
-//! The index is a plain XY grid hash: one bucket per [`CELL`]-sized cell, each holding every
-//! surface whose wet-footprint box overlaps that cell. A point query is one hash lookup, and the
-//! hot path re-uses the exact same predicates ([`WaterChunkInfo::contains`] et al.) on the
-//! handful of candidates it returns — the verdict set is identical to the full walk by
-//! construction, because a surface is registered in every cell its box overlaps.
-//!
-//! Membership only changes when surfaces stream in or out with their tiles, so the rebuild is
-//! edge-triggered (`Added` / `RemovedComponents`) and costs nothing on a steady frame. A stale
-//! entry between despawn and rebuild self-filters at the consumer (`Query::get` on a dead entity
-//! misses), and a surface spawned this frame is indexed before the next frame's consumers run.
+//! The liquid spatial index for per-draw consumers: an XY grid hash, one bucket per [`CELL`]
+//! holding every surface whose wet-footprint box overlaps it, so a point query returns a superset
+//! the caller's own tests narrow to exactly the full walk's answer. Rebuilt only when surfaces
+//! stream in or out; a stale entry self-filters at the consumer's `Query::get`.
 
 use bevy::platform::collections::HashMap;
 use bevy::prelude::*;
 
 use super::query::WaterChunkInfo;
 
-/// Cell pitch, yards: one MCNK (100/3). An ADT surface's wet footprint fits one-to-few cells and
-/// a WMO pool's larger box lands in a handful (Stormwind's biggest MLIQ box, 95 × 80 yd, spans
-/// ~12) — buckets stay short, and a dry-land query misses the map entirely.
+/// Cell pitch in yards: one MCNK (100/3).
 const CELL: f32 = 100.0 / 3.0;
 
-/// The XY grid hash over every loaded liquid surface (module docs). Read via [`Self::over`];
-/// maintained by [`maintain_water_index`].
+/// The XY grid hash over every loaded liquid surface.
 #[derive(Resource, Default)]
 pub(crate) struct WaterIndex {
     cells: HashMap<[i32; 2], Vec<Entity>>,
@@ -41,20 +23,15 @@ impl WaterIndex {
         [(x / CELL).floor() as i32, (y / CELL).floor() as i32]
     }
 
-    /// Every surface whose wet-footprint box overlaps the cell containing this WoW-space XY — the
-    /// candidate set for [`super::surfaces_at`], a superset of the surfaces actually containing
-    /// the point (the caller's own `contains`/`answers` tests still decide).
+    /// The surfaces whose box overlaps this WoW XY's cell: a superset the caller's tests narrow.
     pub(crate) fn over(&self, x: f32, y: f32) -> &[Entity] {
         self.cells
             .get(&Self::cell_of(x, y))
             .map_or(&[], Vec::as_slice)
     }
 
-    /// Every surface registered in any cell the WoW-space box `[lo, hi]` touches, deduplicated —
-    /// the candidate set for a small box query (the foam patch builder), with [`Self::over`]'s
-    /// same superset guarantee: a surface overlapping the box overlaps one of its cells, and a
-    /// surface is registered in every cell its footprint overlaps. Boxes here are a few yards
-    /// (1–4 cells), buckets are short — the linear dedup is the cheap shape.
+    /// The surfaces in any cell the WoW box `[lo, hi]` touches, deduplicated: a superset, as
+    /// [`Self::over`].
     pub(crate) fn over_box(&self, lo: [f32; 2], hi: [f32; 2]) -> Vec<Entity> {
         let [x0, y0] = Self::cell_of(lo[0], lo[1]);
         let [x1, y1] = Self::cell_of(hi[0], hi[1]);
@@ -72,9 +49,7 @@ impl WaterIndex {
     }
 }
 
-/// Rebuild [`WaterIndex`] when the surface population changed — tile stream edges only. A full
-/// rebuild over ~2k surfaces is microseconds, so incremental bookkeeping would be complexity
-/// with nothing to buy.
+/// Rebuild [`WaterIndex`] in full when a surface streams in or out.
 pub(crate) fn maintain_water_index(
     mut index: ResMut<WaterIndex>,
     added: Query<(), Added<WaterChunkInfo>>,
@@ -106,8 +81,7 @@ mod tests {
     use crate::liquid::surfaces_at;
     use benilla_formats::LiquidKind;
 
-    /// A flat all-wet `cols × rows` grid at height `z` with vertex `(0,0)` at `(x0, y0)`,
-    /// 10 yd pitch.
+    /// A flat all-wet `cols × rows` grid at `z`, vertex `(0, 0)` at `(x0, y0)`, 10 yd pitch.
     fn chunk(x0: f32, y0: f32, z: f32, cols: usize, rows: usize) -> WaterChunkInfo {
         let positions = (0..rows)
             .flat_map(|j| (0..cols).map(move |i| [x0 + 10.0 * i as f32, y0 + 10.0 * j as f32, z]))
@@ -129,9 +103,7 @@ mod tests {
         app
     }
 
-    /// The index answers exactly like the full walk — same surfaces, same heights — from inside
-    /// a footprint, at its edge, and from dry land; and a surface spanning many cells is found
-    /// from every one of them.
+    /// The index answers as the full walk does: inside a footprint, at its edge, on dry land.
     #[test]
     fn indexed_candidates_match_the_full_walk() {
         let mut app = app();
@@ -161,7 +133,6 @@ mod tests {
         }
     }
 
-    /// Despawning the last surface empties the index on the next pass — the stream-out edge.
     #[test]
     fn a_despawned_surface_leaves_the_index() {
         let mut app = app();
diff --git a/crates/benilla-world/src/liquid/surface.rs b/crates/benilla-world/src/liquid/surface.rs
index 3cd26394..31a4f939 100644
--- a/crates/benilla-world/src/liquid/surface.rs
+++ b/crates/benilla-world/src/liquid/surface.rs
@@ -1,20 +1,8 @@
-//! **The Bevy render glue** — the animated liquid surfaces themselves.
-//!
-//! One shared material per (kind, [`LiquidPath`], scroll) over a `texture_2d_array` of the kind's
-//! frames, the two spawn paths (an ADT chunk's MCLQ and a WMO group's MLIQ), and the flat mesh build. The faithful
-//! shading model is `super`'s header and `liquid.wgsl`'s; the *position* side — the grid each
-//! spawned surface publishes and the queries against it — is [`super::query`].
-//!
-//! **The 24 fps frame-flip and the lava scroll are computed IN the shader off `globals.time`**
-//! (liquid.wgsl `anim_time`): both are pure functions of the wall clock and two per-material
-//! constants baked at build, so no CPU ever mutates a liquid material again. The 24 Hz
-//! `Assets::get_mut` cycler this replaced cost a measured 0.28 cpu_ms/frame at the SW pin (the
-//! WOW_NO_LIQUID_ANIM bracket, 2026-08-18, negative in all three rounds): its per-tick Modified
-//! chain re-uploaded ~14 material uniforms, rebuilt their Metal bind groups, and armed the
-//! whole-population `AssetChanged` walks 24 times a second. A deterministic run bakes the freeze
-//! at BUILD time (`anim.w = 0` → the shader clock reads 0 forever), so captures keep frame 0 /
-//! scroll 0 bit-exactly — the same pin the old tick enforced (0600). Two clocks, unchanged in
-//! spirit: animation = wall clock; day/night = server game-time.
+//! The animated liquid surfaces: one shared material per (kind, [`LiquidPath`], scroll) over a
+//! `texture_2d_array` of the kind's frames, the two spawn paths (an ADT chunk's MCLQ, a WMO
+//! group's MLIQ) and the flat mesh. The 24 fps frame flip and the lava scroll run in the shader
+//! off the wall clock, so no CPU mutates a material; a deterministic run bakes the clock off
+//! (frame 0, scroll 0). Day and night follow server time.
 
 use std::collections::HashMap;
 
@@ -33,50 +21,29 @@ use benilla_assets::LockRecover;
 use benilla_assets::{liquid_frame_array, RenderConfig, WorldAssets};
 use benilla_formats::{read_texture_mip_chain, BlpMipChain, LiquidKind, LiquidMesh};
 
-/// The shared liquid materials, keyed by [`LiquidKey`]. Read by the terrain streamer (via [`spawn_liquids`] /
-/// [`spawn_wmo_liquids`]) to material the per-chunk water meshes. Absent when the client has no data
-/// (no `WorldAssets`).
+/// The shared liquid materials by [`LiquidKey`]; absent without client data.
 #[derive(Resource, Default)]
 pub(crate) struct LiquidAssets {
     materials: HashMap<LiquidKey, LiquidEntry>,
 }
 
-/// **Which of the reference's liquid renderers a surface belongs to.**
-///
-/// The reference has three, and until now benilla had one. `0x6b62e0` sends the type nibble to a
-/// category, and category 0 (river/water — nibbles 0/4/8) splits again on the owning group's
-/// `MOGP.flags & 0x48`:
-///
-/// * [`Adt`](LiquidPath::Adt) — the MCLQ queues `0x6851b0` (river) / `0x685010` (ocean). **Two**
-///   texture stages: a static depth-ramp on stage 0 addressed by `tc0 = (0.5, LUT[depthByte])`, the
-///   animated sheet on stage 1 at `tc1 = (col·¼, row·¼)`, combined by `ocean0_s.bls`. The only path
-///   with a depth ramp, and its vertex carries no colour at all.
-/// * [`WmoExterior`](LiquidPath::WmoExterior) — `0x6b6630`. **One** stage (the sheet), a 9-float
-///   vertex carrying an up normal *and* a colour dword, and the pixel program `MapObjExtWater0.bls`
-///   bound at `0x6b6654`.
-/// * [`WmoInterior`](LiquidPath::WmoInterior) — `0x6b6420`. One stage, a 6-float vertex with **no
-///   normal**, lighting forced OFF, and no pixel program at all.
-///
-/// Magma and slime take none of these: they share `0x6b68f0` (WMO) / `0x68dca0` (ADT) whatever their
-/// group's flags say, so for the fullbright kinds this enum records only which *spawner* made the
-/// surface — which is still what picks the fog block below.
-///
-/// This also subsumes the old `interior: bool` lane, which existed for the **fog block**: the
-/// reference decides fog per *pass*, not per liquid type, and a WMO group's own pool is drawn by the
-/// WMO liquid pass, which re-submits the smoothed interior fog block (`0x6b6323`–`0x6b6342`) under
-/// the same `[0xca7f00]` gate as the WMO *geometry* pass — so a pool and the walls around it always
-/// fog alike, while ADT liquid submits no fog and draws under the once-a-frame scene block. (VERIFIED
-/// wow-re `fog-env-state` §5's 6-site submit census + `liquid-render-state-sided` §5; decision 0691.)
-/// `WmoInterior` is exactly the old `interior == true`, so [`Self::interior_fog`] is the whole of
-/// what that flag used to say — with the renderer identity now carried alongside it rather than
-/// inferred from it.
+/// Which of the reference's three liquid renderers draws a surface: `0x6b62e0` sends the type
+/// nibble to a category, and category 0 (nibbles 0/4/8) splits on the group's `MOGP.flags & 0x48`.
+/// Magma and slime share `0x6b68f0` (WMO) / `0x68dca0` (ADT) whatever the flags, so for them the
+/// path only picks the fog block. Fog is per pass: the WMO liquid pass re-submits the smoothed
+/// interior fog block (`0x6b6323`–`0x6b6342`) under the same `[0xca7f00]` gate as the WMO geometry,
+/// so a pool fogs like its walls, while ADT liquid submits none and draws under the scene block.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub(crate) enum LiquidPath {
-    /// An ADT chunk's MCLQ surface.
+    /// An ADT chunk's MCLQ (`0x6851b0` river, `0x685010` ocean): two stages, the depth swatch at
+    /// `tc0 = (0.5, LUT[depthByte])` and the sheet at `tc1 = (col·¼, row·¼)`; no vertex colour.
     Adt,
-    /// A WMO group's MLIQ surface, the group being exterior/exterior-lit (`MOGP.flags & 0x48 != 0`).
+    /// A WMO group's MLIQ, exterior or exterior-lit (`MOGP.flags & 0x48 != 0`), `0x6b6630`: one
+    /// stage, a 9-float vertex with an up normal and a colour dword, `MapObjExtWater0.bls` bound at
+    /// `0x6b6654`.
     WmoExterior,
-    /// A WMO group's MLIQ surface, the group being a true interior (`MOGP.flags & 0x48 == 0`).
+    /// A WMO group's MLIQ, a true interior (`MOGP.flags & 0x48 == 0`), `0x6b6420`: one stage, a
+    /// 6-float vertex with no normal, lighting off, no pixel program.
     WmoInterior,
 }
 
@@ -90,7 +57,6 @@ impl LiquidPath {
         }
     }
 
-    /// Does this surface fog with the **interior** block rather than the scene block?
     fn interior_fog(self) -> bool {
         matches!(self, Self::WmoInterior)
     }
@@ -104,23 +70,15 @@ impl LiquidPath {
         }
     }
 
-    /// Does a pool on this arm take its body colour from its **own MOMT `diffColor`**, baked into the
-    /// mesh's vertex colour? Only the interior arm: the exterior one is lit and reads a live
-    /// `Light.dbc` band instead, and ADT liquid has no MOMT to index at all.
+    /// Does this arm's pool take its body colour from its own MOMT `diffColor`? Only the interior
+    /// one: the exterior reads a live `Light.dbc` band, and ADT liquid has no MOMT.
     fn takes_material_body_color(self) -> bool {
         matches!(self, Self::WmoInterior)
     }
 }
 
-/// Which shared material a surface takes: its kind, its renderer ([`LiquidPath`]), and whether it
-/// takes the lava/slime UV scroll.
-///
-/// The scroll lane is a per-*nibble*, per-*path* property that [`LiquidKind`] deliberately collapses
-/// (2 and 6 are both `Magma`), so it cannot be derived from the kind and has to key the material —
-/// see [`scrolls`].
-///
-/// The variants share one decoded frame array — only the tiny uniform differs — so the extra
-/// materials cost a handful of bytes, not a second copy of 30 × 256² textures.
+/// Which shared material a surface takes. The scroll is per nibble and per path, which
+/// [`LiquidKind`] collapses (2 and 6 are both `Magma`), so it keys the material too.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 struct LiquidKey {
     kind: LiquidKind,
@@ -129,24 +87,13 @@ struct LiquidKey {
     scroll: bool,
 }
 
-/// Does this surface take the reference's animated stage-0 texture matrix — the lava/slime scroll?
-///
-/// **Only WMO MLIQ surfaces whose type nibble is 6 or 7** (VERIFIED wow-re `liquid-uv-scroll-law.md`:
-/// the WMO magma/slime kernel `0x6b68f0` gates on `and esi,0xc; cmp esi,4` over the `0x6ba970`
-/// nibble, and builds a matrix that is identity except element 13 = the v-translate). Three
-/// consequences that are easy to get wrong, all of them load-bearing:
-///
-/// * **Nibbles 2 and 3 do NOT scroll**, though they reach the same kernel and draw the same
-///   `lava.blp`/`slime.blp`. In the shipped data that is the difference between Blackrock's lava
-///   (nibble 6, scrolls) and the **Ironforge Great Forge's** (nibble 2, static) — the same texture,
-///   two behaviours, and the reason "lava scrolls" is not a statement you can make about lava.
-/// * **ADT liquid never scrolls, magma included** — the open-world Searing Gorge / Burning Steppes
-///   lava is nibble 6 too, but its queue is a *different* kernel (`0x68dca0`) which pushes a
-///   byte-exact identity with element 13 hard-zeroed at `0x68dda1`. So the gate is the nibble AND
-///   the path; a nibble-only test would slide every lava pool in the open world.
-/// * The phase is driven off the reference's uptime clock, so only its **rate and period** are
-///   reproducible — never its absolute value. We drive ours off the same wall clock the frame
-///   cycler uses.
+/// Does a WMO MLIQ surface of this type nibble take the reference's animated stage-0 texture
+/// matrix, the lava/slime scroll? Only 6 and 7: the WMO magma/slime kernel `0x6b68f0` gates on
+/// `and esi,0xc; cmp esi,4` over the `0x6ba970` nibble and builds an identity but for element 13,
+/// the v-translate. Nibbles 2 and 3 reach the same kernel and stay still (the Great Forge is 2,
+/// Blackrock 6). ADT liquid never scrolls, though open-world lava is nibble 6: its kernel
+/// `0x68dca0` zeroes element 13 at `0x68dda1`, so the caller gates the path. The phase runs off
+/// the reference's uptime clock; only its rate and period are reproducible.
 fn scrolls(nibble: u8) -> bool {
     matches!(nibble, 6 | 7)
 }
@@ -156,9 +103,7 @@ struct LiquidEntry {
 }
 
 impl LiquidAssets {
-    /// The shared material for a liquid kind on a given renderer, scrolling or not, if its frames
-    /// loaded. `scroll` is [`scrolls`]'s verdict; a `true` for a kind that has no scrolling variant
-    /// simply misses, which is the same "no material" path a failed frame load takes.
+    /// The shared material for a kind, renderer and scroll, if one was built and its frames loaded.
     pub(crate) fn material(
         &self,
         kind: LiquidKind,
@@ -171,38 +116,13 @@ impl LiquidAssets {
     }
 }
 
-/// Marks a spawned water surface (one per liquid MCNK chunk), so it can be queried/culled as a group.
+/// Marks a spawned liquid surface: one per MCNK liquid layer or WMO group pool.
 #[derive(Component)]
 pub(crate) struct LiquidSurface;
 
-/// Attribution kill-switch: `$WOW_NO_LIQUID=1` hides every liquid **surface**, and only the surface —
-/// the swim grid, the submersion verdict, the foam and the ambient loops all stay live, because those
-/// ride sibling components on the same entity ([`WaterChunkInfo`], [`FoamPatch`],
-/// [`LiquidSoundSource`]) rather than its `Visibility`.
-///
-/// It exists because "is that thing occluding the NPC a liquid surface?" was otherwise unanswerable
-/// from inside the game. A liquid surface is opaque where it is deep (`WATER_DEEP_ALPHA` = 1.0) and
-/// fully opaque for the fullbright kinds, and it carries no silhouette of its own that reads as
-/// *water* at a glancing angle — so a mis-placed one is indistinguishable by eye from a mis-placed
-/// wall, and both look like a hard straight seam across the scene. One A/B now separates them; the
-/// alternative was a screenshot argument. Same shape as `$WOW_NO_PARTICLES` / `$WOW_NO_FFX`.
-///
-/// **An ordered override, not a second authority** — the shape `apply_self_model_fade` already
-/// uses against the model-`Visibility` authority (`model_render::ModelVisSet`). Every liquid
-/// surface now has a real per-frame `Visibility` owner: an ADT surface is `ExteriorScene`, written
-/// by `exterior_cull::apply_exterior_cull`; a WMO pool carries `WmoGroupVis`, written by
-/// `model_render::visibility::apply_model_visibility`'s `group_only` query. So this runs in
-/// `PostUpdate` **after** both (decision 1652) and wins the frame.
-///
-/// It used to run in `Update` on `Added`, writing `Hidden` exactly once when a surface streamed in.
-/// That was already broken for WMO pools before this change — 0689 gave them `WmoGroupVis` in
-/// `Update`, so the authority re-wrote `Inherited` over the kill-switch on the very next frame and
-/// `$WOW_NO_LIQUID` silently stopped hiding Stormwind's canals and every dungeon pool. Nobody
-/// noticed because the switch's usual subject is a lake. Tagging ADT liquid would have taken the
-/// remaining half the same way; making it an override fixes both at once.
-///
-/// Change-gated, so the steady state is one compare per surface and no change-detection churn —
-/// and the system is `run_if`'d off the env var, so an ordinary run never schedules it at all.
+/// `WOW_NO_LIQUID`: hide every liquid surface and only the surface, since the swim grid, foam and
+/// sound ride sibling components. An override run after both per-frame `Visibility` owners (the
+/// exterior cull for ADT surfaces, `apply_model_visibility` for WMO pools), so it wins the frame.
 pub(super) fn hide_liquid_surfaces(mut surfaces: Query<&mut Visibility, With<LiquidSurface>>) {
     for mut vis in &mut surfaces {
         if *vis != Visibility::Hidden {
@@ -211,27 +131,15 @@ pub(super) fn hide_liquid_surfaces(mut surfaces: Query<&mut Visibility, With<Liq
     }
 }
 
-/// What the **above-water ambient-loop system** needs beyond the surface's geometry (wow-re
-/// `liquid-ambience-loop.md`, decision 0506): the sound-class nibble the driver resolves through
-/// `SoundWaterType.dbc`. Attached to **every** liquid surface, the fullbright kinds included (the
-/// Ironforge lava rumble, Undercity slime).
-///
-/// It used to carry its own copy of the footprint — bounds + a surface height — because when 0506
-/// wrote it, magma and slime carried no [`WaterChunkInfo`] to read them from. 0634 gave every kind
-/// one (that is what made lava swimmable), so the copy became a third set of numbers describing the
-/// same surface, and its height stayed the chunk maximum after the grid sample landed. The driver
-/// queries `(&LiquidSoundSource, &WaterChunkInfo)` instead — the pairing both spawn paths already
-/// guarantee — and reads the geometry from the one component that owns it.
+/// The ambient loop's sound-class nibble, resolved through `SoundWaterType.dbc` (`0x54e0a0`), on
+/// every liquid surface; the driver reads the geometry off the same entity's `WaterChunkInfo`.
 #[derive(Component)]
 pub(crate) struct LiquidSoundSource {
     /// The surface's sound-class nibble (`class = n & 3`, `FluidSpeed = n & 0xc`).
     pub(crate) nibble: u8,
 }
 
-/// Spawn a set of water surfaces — one flat mesh per [`LiquidMesh`], on its [`LiquidKind`]'s shared
-/// animated material. Used by the `AdtTile` pipeline (`terrain_stream`). No-op when the client has no
-/// data (`liquid_assets` absent) or a kind's frames didn't load. Spawned entities are pushed onto
-/// `entities` so they despawn with their tile.
+/// Spawn an ADT tile's liquid surfaces into `entities`, to despawn with the tile.
 pub(crate) fn spawn_liquids<'a>(
     commands: &mut Commands,
     liquids: impl Iterator<Item = &'a LiquidMesh>,
@@ -243,19 +151,11 @@ pub(crate) fn spawn_liquids<'a>(
         return;
     };
     for lq in liquids {
-        // ADT liquid always takes the SCENE fog: the ADT liquid passes submit no fog block of their
-        // own, so they draw under the once-a-frame scene submit (wow-re `fog-env-state` §5).
-        //
-        // And it NEVER scrolls — `scroll: false` here is not a default, it is the finding. Shipped
-        // ADT magma is nibble 6 throughout, the very nibble that scrolls on the WMO path, but the
-        // ADT queue is a different kernel that hard-zeroes the v-translate ([`scrolls`]). Deriving
-        // the flag from `lq.sound_nibble` here — the obvious-looking thing — would slide every
-        // Searing Gorge and Burning Steppes lava pool in the game.
+        // The scene fog (the ADT passes submit none and draw under the scene submit `0x66ff20`),
+        // and never a scroll, though ADT magma is nibble 6: its kernel zeroes the v-translate.
         let Some(material) = liquid.material(lq.kind, LiquidPath::Adt, false) else {
             continue; // this kind's frames failed to load (warned at setup)
         };
-        // The world-space liquid grid (MCLQ positions are already absolute WoW, so the IDENTITY
-        // transform is a no-op round-trip).
         let info = wet_footprint(lq, &Transform::IDENTITY, LiquidSource::AdtChunk);
         let foam = !lq.kind.is_fullbright(); // white surf is a water thing
         let mesh_handle = meshes.add(liquid_bevy_mesh(lq, None));
@@ -266,21 +166,10 @@ pub(crate) fn spawn_liquids<'a>(
                     MeshMaterial3d(material),
                     Transform::IDENTITY,
                     LiquidSurface,
-                    // **Open-world liquid is exterior scene** — the reference's ADT liquid
-                    // producer `0x683ab0` is called only from the per-window populate
-                    // `0x682fa0`, exactly like ADT terrain (`0x683bf0`) and doodads
-                    // (`0x683700`), so from inside a cavern the lake overhead draws only where a
-                    // doorway window admits it, and not at all from a sealed room (decision
-                    // 1652). This was 0774's last knowingly-ungated bucket, deferred again by
-                    // 0784 on the belief that liquid "has its own lane" — it does not: nothing
-                    // wrote an ADT surface's `Visibility` at all, so `apply_exterior_cull` is its
-                    // sole authority and the tag is the whole change.
-                    //
-                    // Granularity is already the reference's: one entity per MCNK liquid layer
-                    // (33.333 yd), never the 533 yd tile — the half of the cull that decision
-                    // 0780 is about. The `IDENTITY` transform is not incidental either: MCLQ
-                    // positions are absolute, so the mesh `Aabb` Bevy derives is already the
-                    // world-space box the window test wants.
+                    // Exterior scene: the ADT liquid producer `0x683ab0` is called only from the
+                    // per-window populate `0x682fa0`, like ADT terrain (`0x683bf0`) and doodads
+                    // (`0x683700`), one entity per MCNK layer. The exterior cull is its only
+                    // `Visibility` writer.
                     crate::exterior_cull::ExteriorScene,
                     info,
                     LiquidSoundSource {
@@ -289,14 +178,12 @@ pub(crate) fn spawn_liquids<'a>(
                 ))
                 .id(),
         );
-        // Foam is water-only; the cells it clips against ride `info`, not the marker.
         if foam {
             commands
                 .entity(*entities.last().expect("just pushed"))
                 .insert(FoamPatch);
         }
-        // **The waterline the camera sweep can hit** under `cameraWaterCollision` — inert to every
-        // other query, because nothing else asks for [`CollisionLayer::Liquid`].
+        // The waterline for the camera sweep under `cameraWaterCollision`; nothing else queries it.
         if let Some(collider) = liquid_collider(lq) {
             commands
                 .entity(*entities.last().expect("just pushed"))
@@ -305,18 +192,8 @@ pub(crate) fn spawn_liquids<'a>(
     }
 }
 
-/// The **collision** shape for one [`LiquidMesh`] — the same wet-cell triangles the render mesh
-/// draws, as a parry trimesh on [`CollisionLayer::Liquid`](crate::collision::CollisionLayer).
-///
-/// `lq.indices` is already the wet derivative (6 per wet cell), so this is the waterline exactly
-/// where there is water and nothing over the dry cells of a part-flooded chunk — which is the
-/// difference between a camera that stops at a lake's edge and one that stops in mid-air over the
-/// shore. Built inline rather than through [`crate::terrain_stream::PendingCollider`]'s async pool:
-/// an MCNK layer's 9×9 lattice is at most 64 cells, 128 triangles, next to the 256 a terrain chunk
-/// defers, and a WMO pool's MLIQ is the same order.
-///
-/// `None` for a degenerate layer with no triangles, which is a real case (an MCLQ layer whose cells
-/// are all dry) and not a failure.
+/// The collision trimesh for one [`LiquidMesh`]: the render mesh's own wet-cell triangles, `None`
+/// when every cell is dry. Built inline, as a layer is at most 128 triangles.
 fn liquid_collider(lq: &LiquidMesh) -> Option<Collider> {
     let tris: Vec<[u32; 3]> = lq
         .indices
@@ -332,11 +209,8 @@ fn liquid_collider(lq: &LiquidMesh) -> Option<Collider> {
     Some(Collider::trimesh(verts, tris))
 }
 
-/// Build the Bevy render mesh for one [`LiquidMesh`]: positions mapped WoW→Bevy (`lq.positions` are
-/// raw WoW coords — absolute for MCLQ, WMO-model-local for WMO liquid), a flat up normal, the tiling
-/// UVs, and the per-vertex swatch `V` packed into UV1.x for the shader's colour/opacity ramp. The
-/// caller decides the surface's world placement via the spawned entity's `Transform` (`IDENTITY` for
-/// absolute MCLQ water; the WMO placement transform for WMO liquid).
+/// The render mesh for one [`LiquidMesh`] in its own space (absolute for MCLQ, model-local for WMO
+/// liquid): a flat up normal, the tiling UVs, and the per-vertex depth `V` in UV1.x.
 fn liquid_bevy_mesh(lq: &LiquidMesh, body_color: Option<[f32; 3]>) -> Mesh {
     let positions: Vec<[f32; 3]> = lq
         .positions
@@ -349,19 +223,15 @@ fn liquid_bevy_mesh(lq: &LiquidMesh, body_color: Option<[f32; 3]>) -> Mesh {
         RenderAssetUsages::default(),
     );
     mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, positions);
-    // Flat surface: WoW up (0,0,1) → Bevy up (0,1,0). The shader lights against this (rotated into
-    // world by the entity transform) + the sun.
+    // WoW up (0, 0, 1) is Bevy up (0, 1, 0).
     mesh.insert_attribute(Mesh::ATTRIBUTE_NORMAL, vec![[0.0, 1.0, 0.0]; n]);
     mesh.insert_attribute(Mesh::ATTRIBUTE_UV_0, lq.uvs.clone());
     // UV1.x carries the per-vertex swatch depth (0..1) for the shader's opacity ramp; UV1.y is
     // unused.
     let uv1: Vec<[f32; 2]> = lq.depths.iter().map(|&d| [d, 0.0]).collect();
     mesh.insert_attribute(Mesh::ATTRIBUTE_UV_1, uv1);
-    // An INTERIOR WMO pool's body colour is its own `MOMT.diffColor`, and it rides the vertex colour
-    // because that is where the reference's interior water vertex carries it (a colour dword in its
-    // 6-float record). Baking it here keeps ONE shared material per lane: a per-surface uniform would
-    // have meant a material per pool. Absent on every other lane, which adds no attribute and takes
-    // the shader's `#else` white.
+    // An interior pool's `MOMT.diffColor` rides the vertex colour, where the reference's interior
+    // vertex carries it, keeping one material per lane; other lanes take the shader's white.
     if let Some([red, green, blue]) = body_color {
         mesh.insert_attribute(Mesh::ATTRIBUTE_COLOR, vec![[red, green, blue, 1.0]; n]);
     }
@@ -369,29 +239,9 @@ fn liquid_bevy_mesh(lq: &LiquidMesh, body_color: Option<[f32; 3]>) -> Mesh {
     mesh
 }
 
-/// Spawn a WMO group's embedded liquid surfaces (Stormwind's canals + fountains, the Ironforge lava,
-/// dungeon pools) at the building's placement `transform`, on the shared per-kind liquid material —
-/// the same animated water render as MCLQ, but its geometry is WMO-model-local (built by
-/// `benilla_formats::wmo_group_liquid_mesh`) so the placement transform lifts it into the world.
-///
-/// No-op when the client has no data (`liquid_assets` absent) or a kind's frames didn't load. Each
-/// WATER surface also carries a world-space [`WaterChunkInfo`] + [`FoamPatch`] (both built by baking the
-/// placement transform into the raw liquid coords, [`world_wow`]) so the whole water-interaction stack
-/// sees WMO liquid exactly like MCLQ: swimming ([`crate::player::swim`]), the underwater murk
-/// ([`detect_submersion`]), the wading splash/footstep sounds, AND the `CWater0Ripple` wade wake /
-/// standing ring ([`crate::water_fx`], which builds each foam decal from the wet-cell lattice). The
-/// foam's world-axis texgen + per-triangle overlap consume the transformed cells fine, so a rotated
-/// canal's ring is still correctly world-oriented. Spawned entities are pushed onto `entities` so they
-/// despawn with the placement.
-///
-/// `interior` is the owning group's `MOGI & 0x48 == 0` class, and it selects the **fog block** the
-/// surface draws under — the Great Forge's lava hazes with the forge's own fog, Stormwind's open
-/// canals with the sky's (see [`LiquidKey`]).
-///
-/// `pool` is the surface's **scope** (see [`WmoPool`]): the room it belongs to, and that room's own
-/// floor. A liquid footprint has no floor of its own, so an unscoped pool claims every position
-/// under its XY forever — the Uldaman entrance read as submerged under a mushroom cave's water
-/// 186 yd overhead (0696), and Undercity's upper slime submerged the rooms 115 yd below it (0701).
+/// Spawn a WMO group's liquid surfaces at the building's placement `transform`, pushed onto
+/// `entities` to despawn with the placement. `interior` is the group's `MOGI & 0x48 == 0` class,
+/// which picks the renderer and the fog block; `pool` scopes each surface to its room and floor.
 pub(crate) fn spawn_wmo_liquids<'a>(
     commands: &mut Commands,
     liquids: impl Iterator<Item = &'a LiquidMesh>,
@@ -400,9 +250,7 @@ pub(crate) fn spawn_wmo_liquids<'a>(
     transform: Transform,
     interior: bool,
     pool: WmoPool,
-    // The owning root's MOMT `diffColor` table (`WmoModel::material_diff_color`). An INTERIOR
-    // pool's whole body colour is its own entry; MOMT lives in the root, so the group file the
-    // `LiquidMesh` came from could not resolve it and the lookup happens here.
+    // The owning root's MOMT `diffColor` table: MOMT lives in the root, not the group file.
     material_diff_color: &[[f32; 3]],
     entities: &mut Vec<Entity>,
 ) {
@@ -411,16 +259,9 @@ pub(crate) fn spawn_wmo_liquids<'a>(
     };
     let path = LiquidPath::wmo(interior);
     for lq in liquids {
-        // `interior` picks the fog block, not the look: an interior group's pool is drawn by the WMO
-        // liquid pass, which re-submits the smoothed interior fog under the same `[0xca7f00]` gate as
-        // the WMO geometry pass — so the pool fogs exactly like the walls around it (see [`LiquidKey`]).
-        // This is the ONE path that can scroll, and the nibble — not the kind — is what decides it:
-        // Blackrock's lava (6) creeps, the Ironforge Great Forge's (2) does not, and both are
-        // `LiquidKind::Magma` drawing the same sheet ([`scrolls`]).
+        // The one path that can scroll, decided by the nibble, not the kind (`scrolls`).
         let scroll = scrolls(lq.sound_nibble);
-        // The interior arm's body colour, resolved through the pool's own MLIQ `materialId`. A
-        // fullbright pool takes none (its sheet IS the body), and a missing/out-of-range index
-        // simply yields no colour rather than a guessed one.
+        // The interior arm's body colour via the pool's MLIQ `materialId`; none when fullbright.
         let body_color = (path.takes_material_body_color() && !lq.kind.is_fullbright())
             .then(|| {
                 lq.material_id
@@ -432,8 +273,6 @@ pub(crate) fn spawn_wmo_liquids<'a>(
             continue; // this kind's frames failed to load (warned at setup)
         };
         if scroll {
-            // Rare (only nibble 6/7 pools reach it) and the only outside view of a decision that is
-            // otherwise invisible until you stand over the pool and watch it for ten seconds.
             debug!(
                 "liquid: {:?} nibble {} takes the scroll lane",
                 lq.kind, lq.sound_nibble
@@ -445,41 +284,25 @@ pub(crate) fn spawn_wmo_liquids<'a>(
                 MeshMaterial3d(material),
                 transform,
                 LiquidSurface,
-                // The per-frame interior-fog lane rides `MeshTag` bit 30, written by the one
-                // `Visibility` authority off this pool's own room (decision 1787; `liquid.wgsl`'s
-                // `room_fog`). Spawned clear: a pool wears the room's fog only once the flood has
-                // said the room is on the lane.
+                // Bit 30 is the interior-fog lane (`liquid.wgsl`'s `room_fog`), written each frame
+                // by the `Visibility` authority off the pool's room; spawned clear.
                 bevy::mesh::MeshTag(0),
-                // The ambient-loop source rides EVERY kind — the fullbright lava/slime hum too
-                // (0506). It reads its geometry off the `WaterChunkInfo` inserted below.
+                // Every kind, the lava and slime hum too.
                 LiquidSoundSource {
                     nibble: lq.sound_nibble,
                 },
             ))
             .id();
-        // The swim/submersion grid rides EVERY kind, magma and slime included — that is what
-        // makes Blackrock's lava and Undercity's slime swimmable instead of something you fall
-        // through (decision 0634, bugs B24/B25). It used to be gated on `!is_fullbright()` because
-        // `WaterChunkInfo` carried no kind, so tagging lava would have swum the player under a teal
-        // *water* murk with white foam. The component carries [`LiquidKind`] now and the
-        // water-flavoured consumers filter on it (`water_surface_at`, `detect_submersion`), so the
-        // exclusion is no longer what keeps lava from looking like a lake.
-        //
-        // Lava/slime **damage** is still not modelled — a named gap, not a reason to keep the
-        // geometry non-solid.
+        // Every kind carries the swim grid, so lava and slime swim; their damage is not modelled.
         commands.entity(surface).insert(wet_footprint(
             lq,
             &transform,
             LiquidSource::WmoGroup(pool),
         ));
-        // Foam stays water-only: it is white surf, and there is no such thing on magma.
         if !lq.kind.is_fullbright() {
             commands.entity(surface).insert(FoamPatch);
         }
-        // The camera's waterline, as on the ADT path. The shape is MODEL-LOCAL here and the
-        // entity carries the placement `transform`, so avian lifts it into the world the same way
-        // it lifts the render mesh — no second bake, and a rotated pool stays consistent with the
-        // surface the player sees.
+        // The camera's waterline, model-local under the entity's placement `transform`.
         if let Some(collider) = liquid_collider(lq) {
             commands
                 .entity(surface)
@@ -489,18 +312,13 @@ pub(crate) fn spawn_wmo_liquids<'a>(
     }
 }
 
-/// Each kind's animated frame set: `(kind, XTextures subdir, file stem, frame count on disk)`.
-/// Frames are `XTextures\<dir>\<stem>.<1..=count>.blp` (256² RGBA, RGB dark + alpha ripple).
+/// Each kind's frames, `XTextures\<dir>\<stem>.<1..=count>.blp`, as `(kind, dir, stem, count)`.
 const FRAME_SETS: &[(LiquidKind, &str, &str, u32)] = &[
     (LiquidKind::Still, "river", "lake_a", 30),
     (LiquidKind::Rapids, "river", "fast_a", 16),
     (LiquidKind::Ocean, "ocean", "ocean_h", 30),
-    // The fullbright kinds: opaque + unlit + fogged, the animated texture IS the body colour, there
-    // being no vertex colour or depth LUT to modulate it by (VERIFIED wow-re
-    // `liquid-render-state-sided` §5). **Magma reaches here from BOTH liquid systems** — the WMO
-    // MLIQ pools *and* the ADT MCLQ magma queue (B21: the 128 open-world lava chunks, Burning
-    // Steppes/Searing Gorge/Un'Goro); only slime is WMO-only, the reference having no ADT queue for
-    // it at all. See [`benilla_formats::LiquidKind`].
+    // Fullbright: the sheet is the opaque, unlit, fogged body (`0x6b68f0`). Magma comes from both
+    // the WMO pools and the ADT magma queue; the reference has no ADT queue for slime.
     (LiquidKind::Magma, "lava", "lava", 30),
     (LiquidKind::Slime, "slime", "slime", 30),
 ];
@@ -535,36 +353,19 @@ pub(super) fn setup_liquid(
             warn!("liquid: no frames for {stem} — {kind:?} water will not render");
             continue;
         };
-        // Blend state is per KIND, and this is where it is decided (VERIFIED wow-re
-        // `liquid-render-state-sided` — the device render-state *defaults* at `0x593bf0` are the baseline
-        // a liquid batch draws under, because every setter in the reference is Push/Pop-scoped):
-        //
-        //   * water / ocean — the reference sets EGxBlend 2 (SRC_ALPHA / INV_SRC_ALPHA) and depth-write
-        //     OFF, which is exactly Bevy's `AlphaMode::Blend` transparent pass. Unchanged. (Both are
-        //     gated on the fancy-water cvar `[0xc9a324]`, which we do not model — a separate lane.)
-        //   * magma / slime — blend state stays at the default **0**, i.e. `glDisable(GL_BLEND)`, with
-        //     the baseline depth test *and* depth write both ON (ids `0x10`/`0x12` = 1). The ADT lava
-        //     pass says so explicitly (`0x6855e2 (0x07, 0)`) and the WMO magma/slime arm never touches
-        //     blend at all. So they are genuinely opaque and belong in the OPAQUE pass: riding the
-        //     transparent pass with depth-write off is how a lava sheet fails to occlude what is behind
-        //     it. Foam already carries `depth_bias: 1.0` for the coplanar tie, so it still wins.
-        //
-        // Two-sided is universal — all four liquid passes force GL_CULL_FACE off at entry against a
-        // cull-ON baseline, and `glFrontFace` is never imported, so winding is moot (§6).
+        // Blend per kind, over the device defaults (`0x593bf0`) every reference setter pushes and
+        // pops against. Water and ocean: EGxBlend 2 (`SRC_ALPHA / INV_SRC_ALPHA`), depth write off
+        // (both under the fancy-water CVar `[0xc9a324]`, which is not modelled). Magma and slime:
+        // blend stays 0 (disabled) with depth test and write on (ids `0x10`/`0x12`), as the ADT
+        // lava pass sets (`0x6855e2`) and the WMO arm leaves it, so they are opaque. All four
+        // liquid passes turn culling off at entry (`0x59d7d8`); `glFrontFace` is never imported.
         let alpha_mode = if kind.is_fullbright() {
             AlphaMode::Opaque
         } else {
             AlphaMode::Blend
         };
-        // One material per (RENDERER × SCROLL) combination the kind can actually take (see
-        // [`LiquidKey`]), all sharing the one decoded frame array (`frames` is a handle; the clone is
-        // a refcount, not a second 30 × 256² decode). Every other input is identical, so this is the
-        // whole cost of giving each of the reference's three liquid renderers its own material — and
-        // of letting Blackrock's lava creep while Ironforge's sits still.
-        //
-        // The scroll variant exists only for the fullbright kinds: [`scrolls`] can only ever answer
-        // true for nibbles 6/7, which map to `Magma`/`Slime` and nothing else, so building one for
-        // water would be a material nothing can ever look up.
+        // One material per renderer and scroll the kind can take, all on one frame array; only
+        // magma and slime (nibbles 6 and 7) can scroll.
         let scroll_lanes: &[bool] = if kind.is_fullbright() {
             &[false, true]
         } else {
@@ -580,15 +381,13 @@ pub(super) fn setup_liquid(
         {
             let material = materials.add(ExtendedMaterial {
                 base: StandardMaterial {
-                    // We do our own (WoW) lighting in the shader.
+                    // The shader does the WoW lighting.
                     unlit: true,
                     alpha_mode,
                     cull_mode: None,
                     double_sided: true,
-                    // The transparent water kinds take the fixed water-pass slot: below every
-                    // unclassified world transparent, above the far-side effects (the reference's
-                    // 0x483460 interleave — `sky_order::WATER_BIAS`, where the byte story lives).
-                    // Opaque kinds (magma/slime) draw in the opaque pass and take no rung.
+                    // Water takes the water-pass slot of the reference's `0x483460` interleave
+                    // (`sky_order::WATER_BIAS`); the opaque kinds take no rung.
                     depth_bias: if kind.is_fullbright() {
                         0.0
                     } else {
@@ -599,10 +398,8 @@ pub(super) fn setup_liquid(
                 extension: LiquidExt {
                     scene_depth: water_depth.0.clone(),
                     frames: frames.clone(),
-                    // x = fullbright (magma/slime: the animated texture is the opaque body, skipping
-                    // the swatch and N·L — but NOT the fog, which every liquid kind takes); y = read
-                    // the ocean swatch rows rather than the river/lake ones; z = fog with the WMO
-                    // INTERIOR block; w = water's own sun-sheen exponent.
+                    // x = fullbright (the sheet as body, still fogged); y = the ocean swatch;
+                    // z = the interior fog block; w = water's sun-sheen exponent.
                     kind: Vec4::new(
                         if kind.is_fullbright() { 1.0 } else { 0.0 },
                         if kind == LiquidKind::Ocean { 1.0 } else { 0.0 },
@@ -611,11 +408,8 @@ pub(super) fn setup_liquid(
                     ),
                     // Which of the reference's three liquid renderers `liquid.wgsl` runs.
                     path: Vec4::new(path.shader_id(), 0.0, 0.0, 0.0),
-                    // x = reserved (frame 0; the shader derives the live index from its own
-                    // clock); y = frame count; z = the SCROLL FLAG (1 = this lane takes the
-                    // stage-0 v-scroll — [`scrolls`]' nibble-6/7 WMO lane); w = the clock
-                    // enable (0 on a deterministic run bakes the 0600 capture freeze — frame 0,
-                    // scroll 0 — with no tick left to skip).
+                    // x reserved; y = frame count; z = scroll; w = clock enable (0 on a
+                    // deterministic run: frame 0, scroll 0).
                     anim: Vec4::new(
                         0.0,
                         frame_count as f32,
@@ -652,7 +446,7 @@ pub(super) fn setup_liquid(
                 .insert(LiquidKey { kind, path, scroll }, LiquidEntry { material });
         }
     }
-    // Frame SETS, not materials — a set backs every renderer/scroll variant of its kind.
+    // Frame sets, not materials.
     info!(
         "liquid: loaded {} water frame set(s)",
         FRAME_SETS
@@ -663,11 +457,8 @@ pub(super) fn setup_liquid(
     commands.insert_resource(assets);
 }
 
-/// Decode frames `1..=count` for a kind — each with its BLP **authored mip chain** — into one
-/// repeating, mipmapped + anisotropic `texture_2d_array` (`assets::liquid_frame_array`; mips are what
-/// stop the ripple aliasing into sparkle at distance). Stops at the first missing/non-square/
-/// size-mismatched frame (the on-disk sets are contiguous 256² runs). Returns the image handle + the
-/// number of frames actually loaded, or `None` if none decoded.
+/// Decode frames `1..=count` with their authored mips into one repeating, anisotropic array,
+/// stopping at the first missing, non-square or mis-sized frame; returns it and the count loaded.
 fn load_frame_array(
     world_assets: &mut WorldAssets,
     images: &mut Assets<Image>,
@@ -698,10 +489,9 @@ fn load_frame_array(
         return None;
     }
     let loaded = frames.len() as u32;
-    // Flatten the per-frame DC for the WATER kinds only: mipping turns the shipped frames' drifting
-    // means into a whole-sheet brightness breath once per animation loop, which reads as a flicker on
-    // distant water. Magma/slime draw the sheet AS their body colour, where that swing is the intended
-    // pulse — so they keep theirs (`assets::flatten_frame_dc`).
+    // Deviation: water frames have their per-frame mean flattened (`flatten_frame_dc`), because
+    // mipping turns the shipped frames' drifting means into a flicker on distant water; magma and
+    // slime keep theirs, the body's intended pulse.
     let normalize_dc = !kind.is_fullbright();
     Some((images.add(liquid_frame_array(frames, normalize_dc)), loaded))
 }
@@ -710,23 +500,17 @@ fn load_frame_array(
 mod tests {
     use super::*;
 
-    /// The scroll gate, nibble by nibble — every trap in [`scrolls`] as an assertion.
-    ///
-    /// The failure this guards is not "lava doesn't move"; it is lava moving in the **wrong
-    /// places**, which is far harder to see and impossible to unsee once shipped.
     #[test]
     fn only_nibbles_six_and_seven_scroll() {
-        // The two that do: Blackrock's lava and Stratholme's slime.
+        // Blackrock's lava and Stratholme's slime.
         assert!(scrolls(6), "magma variant 6 takes the animated matrix");
         assert!(scrolls(7), "slime variant 7 takes the animated matrix");
 
-        // The two that reach the SAME kernel and draw the SAME sheet, and still do not scroll —
-        // the Ironforge Great Forge (2) and the Stratholme raid / Ahn'Qiraj slime (3).
+        // Same kernel, same sheet, still static: the Great Forge (2) and Undercity's slime (3).
         assert!(!scrolls(2), "the Great Forge's lava is static");
         assert!(!scrolls(3), "nibble-3 slime is static");
 
-        // The near-miss that a `nibble & 0xc == 4` test would wrongly admit: 4 satisfies it, but it
-        // is a *river* variant that never reaches the magma/slime kernel at all.
+        // 4 passes a bare `nibble & 0xc == 4` test but is a river variant, never the kernel's.
         assert!(!scrolls(4), "nibble 4 is lake_a, not a hazard liquid");
 
         // Everything else in the table, including the hole nibble.
@@ -735,8 +519,7 @@ mod tests {
         }
     }
 
-    /// A scrolling material exists for the fullbright kinds and **only** for them — a scroll lane
-    /// built for water would be a material no lookup can ever reach ([`setup_liquid`]).
+    /// Only the fullbright kinds have nibbles that scroll, so only they get a scroll lane.
     #[test]
     fn only_fullbright_kinds_can_take_a_scroll_lane() {
         for &(kind, ..) in FRAME_SETS {
@@ -751,7 +534,7 @@ mod tests {
         }
     }
 
-    /// One 2×2-vertex MCLQ sheet at `at` — the smallest thing `spawn_liquids` will actually build.
+    /// The smallest MCLQ sheet `spawn_liquids` builds: 2×2 vertices at `at`.
     fn one_sheet(at: [f32; 3]) -> LiquidMesh {
         let [x, y, z] = at;
         LiquidMesh {
@@ -773,9 +556,7 @@ mod tests {
         }
     }
 
-    /// A [`LiquidAssets`] whose only entry is the one the ADT arm asks for — `spawn_liquids`
-    /// `continue`s past a kind whose frames failed to load, so without this the spawn is a no-op
-    /// and the test below would pass on an empty world.
+    /// Only the ADT still-water material, without which `spawn_liquids` spawns nothing.
     fn adt_assets() -> LiquidAssets {
         LiquidAssets {
             materials: HashMap::from([(
@@ -791,16 +572,8 @@ mod tests {
         }
     }
 
-    /// **The spawner's half of the indoor water cull** (decision 1652) — and the half no test in
-    /// `exterior_cull` can cover, because that module's harness spawns its own entities and tags
-    /// them itself. `apply_exterior_cull` decides nothing about a surface it never queries, and
-    /// what puts a surface in its query is this tag, applied here. 0780 left exactly this note on
-    /// the terrain cull ("nothing in `apply_exterior_cull` can fix that — it is decided by what the
-    /// spawner tags") and terrain still has no test for it; liquid gets one.
-    ///
-    /// The three companion assertions are the filter `UnownedSceneFilter` actually applies: a
-    /// surface that picked up `ModelPart`, `WmoGroupVis` or `WorldUnit` would be silently dropped
-    /// from the walk and go back to drawing through the ceiling with this test still green.
+    /// An ADT surface carries `ExteriorScene` and none of the components `UnownedSceneFilter`
+    /// excludes, so the exterior cull reaches it.
     #[test]
     fn an_adt_liquid_surface_is_tagged_exterior_scene() {
         use bevy::ecs::system::RunSystemOnce;
@@ -838,38 +611,23 @@ mod tests {
             e.contains::<LiquidSurface>(),
             "…and is still a liquid surface"
         );
-        // The three exclusions in `UnownedSceneFilter`. An ADT surface must satisfy all of them or
-        // the tag buys nothing.
+        // The three exclusions in `UnownedSceneFilter`.
         assert!(!e.contains::<crate::model_render::ModelPart>());
         assert!(!e.contains::<crate::wmo_portal::WmoGroupVis>());
         assert!(!e.contains::<crate::world_unit::WorldUnit>());
     }
 }
 
-/// Which fog block a WMO pool takes, against the **real client data**. Skips when the 1.12.1 client
-/// isn't present (the repo never carries Blizzard data).
+/// The scroll and fog-block rules against the real client files.
 #[cfg(test)]
 mod real_data {
     use super::LiquidKind;
     use benilla_formats::{parse_wmo_root, wmo_group_liquid_mesh};
     use std::collections::HashMap;
 
-    /// **Which of the shipped hazard pools actually scroll** — [`super::scrolls`] against the real
-    /// data, so the gate is pinned to content rather than to a reading of the binary.
-    ///
-    /// The whole reason this needs a test: "does lava scroll?" has no answer, only a per-pool one.
-    /// The nibble is authored per WMO group, `LiquidKind` collapses it (2 and 6 are both `Magma`,
-    /// drawing the same `lava.blp`), and the two behaviours sit **inside one building** — so a gate
-    /// that quietly regressed to "all magma" or "no magma" would look plausible everywhere and be
-    /// wrong nearly everywhere. These counts are the shipped 1.12.1 numbers, measured:
-    ///
-    /// * **Ironforge is the two-sided case, and it is why the director's report needed a location.**
-    ///   Eleven magma groups: **9 at nibble 2 (static)** and **2 at nibble 6 (scrolling)**, plus 2
-    ///   still-water groups. Lava that moves and lava that does not, in the same forge.
-    /// * **Blackrock Mountain — the pin behind `blackrock_lava_is_below_the_feet_not_above_it`** —
-    ///   is nibble 6 throughout, in the outer mountain and both instance WMOs. All of it creeps.
-    /// * **Slime splits the same way**: Undercity's 38 canals are nibble 3 and stand still;
-    ///   Stratholme's are nibble 7 and flow.
+    /// The scroll gate over the shipped pools, where both behaviours share buildings: Ironforge has
+    /// 9 static nibble-2 and 2 scrolling nibble-6 magma groups, Blackrock is nibble 6 throughout,
+    /// Undercity's 38 slime canals are nibble 3 and still, and Stratholme's are nibble 7 and flow.
     #[test]
     fn only_the_nibble_six_and_seven_pools_scroll_in_the_shipped_data() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -926,7 +684,7 @@ mod real_data {
             "Stratholme's slime is nibble 7 throughout",
         );
 
-        // And the gate's verdict over all of it — the same sheet, two behaviours.
+        // The gate's verdict over all of it.
         assert_eq!(
             ironforge
                 .iter()
@@ -948,23 +706,8 @@ mod real_data {
         );
     }
 
-    /// **Which fog block each liquid-bearing WMO group takes**, against the real client files.
-    ///
-    /// This is decision 0691's follow-on lane. A WMO group's own pool is drawn by the pass that
-    /// re-submits the smoothed INTERIOR fog block (`0x6b6323`-`0x6b6342`), gated on the same
-    /// `[0xca7f00]` as the WMO *geometry* pass — so an indoor pool hazes with its room and an open-air
-    /// one must not. `spawn_wmo_liquids` decides that from the group's `MOGI & 0x48 == 0`, and an
-    /// inverted flag is invisible in any screenshot taken where the two blocks happen to agree (in dry
-    /// Undercity both clamp to 1 within ~58 yd). So pin it on the two buildings that straddle the line,
-    /// with the real numbers:
-    ///
-    /// * **Undercity** — 38 liquid groups, and all but ONE are interior. Its slime canals are the
-    ///   director's original report; the lone exterior one (group 7) is the granularity working, not
-    ///   noise, and is what makes this a real two-sided test rather than a constant.
-    /// * **Stormwind** — 22 liquid groups (canals + fountains), every one EXTERIOR. Reading these as
-    ///   interior would haze the open city's water with an indoor triple under an open sky.
-    ///
-    /// Skips when the 1.12.1 client isn't present (the repo never carries Blizzard data).
+    /// A WMO pool's fog block follows its group's `MOGI & 0x48 == 0` class: Undercity's 38 liquid
+    /// groups are interior but for group 7, and Stormwind's 22 are all exterior.
     #[test]
     fn a_wmo_pools_fog_block_follows_its_groups_interior_class() {
         let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-world/src/log_ring.rs b/crates/benilla-world/src/log_ring.rs
index 253337a0..253b35d0 100644
--- a/crates/benilla-world/src/log_ring.rs
+++ b/crates/benilla-world/src/log_ring.rs
@@ -1,19 +1,7 @@
-//! **The last few hundred log lines, kept in memory** — so a crash report can carry what the
-//! client was doing when it died (decision 2266 §B2).
-//!
-//! The only log sink is stderr, and a player's terminal (or a packaged Windows build with no
-//! console at all) is gone with the process. Of bug B390's four reporters one attached anything,
-//! and only because he had set `RUST_BACKTRACE=1` himself. A panic hook can write a file, but a
-//! payload and a backtrace without the minute of log before them is a symptom without a story:
-//! which zone, which opcode, which asset was loading. This ring is that story.
-//!
-//! Installed as [`bevy::log::LogPlugin::custom_layer`] by [`crate::boot::tuned_default_plugins`],
-//! so it sits under the same `EnvFilter` as the stderr formatter — the ring holds exactly the lines
-//! stderr showed, no more (a `wgpu=trace` firehose the filter drops never reaches it either).
-//! Bounded at [`CAPACITY`] lines; the cost is one string clone per emitted line, on the thread that
-//! logged it, behind a mutex that is never held across anything else.
-//!
-//! Read with [`recent`]. Nothing else in the engine reads it: it is an artefact feed, not a log.
+//! The last [`CAPACITY`] log lines, kept in memory so a crash report carries what the client was
+//! doing when it died. Installed as [`bevy::log::LogPlugin::custom_layer`] by
+//! [`crate::boot::tuned_default_plugins`], under the same `EnvFilter` as stderr, so it holds
+//! exactly the lines stderr showed. Read with [`recent`].
 
 use std::collections::VecDeque;
 use std::fmt::Write as _;
@@ -25,15 +13,14 @@ use bevy::log::tracing::{Event, Subscriber};
 use bevy::log::tracing_subscriber::layer::Context;
 use bevy::log::tracing_subscriber::Layer;
 
-/// How many lines the ring keeps. Two hundred is about a minute of an ordinary session's `info`
-/// stream and a few seconds of a bad one, which is the window a crash needs.
+/// How many lines the ring keeps: about a minute of an ordinary session's `info` stream.
 pub const CAPACITY: usize = 200;
 
 static RING: Mutex<VecDeque<String>> = Mutex::new(VecDeque::new());
 static START: OnceLock<Instant> = OnceLock::new();
 
-/// The layer. Zero-sized; the state is the module's static so the panic hook — which has no
-/// handle to the subscriber — can read it.
+/// The layer; its state is a static so the panic hook, which has no handle to the subscriber, can
+/// read it.
 pub struct LogRing;
 
 impl<S: Subscriber> Layer<S> for LogRing {
@@ -55,8 +42,8 @@ impl<S: Subscriber> Layer<S> for LogRing {
     }
 }
 
-/// Renders an event's fields the way the stderr formatter does: the `message` field bare, every
-/// other field as ` name=value` after it.
+/// Renders an event's fields as the stderr formatter does: `message` bare, the rest as
+/// ` name=value`.
 struct MessageVisitor<'a>(&'a mut String);
 
 impl Visit for MessageVisitor<'_> {
@@ -77,7 +64,7 @@ impl Visit for MessageVisitor<'_> {
     }
 }
 
-/// The ring's contents, oldest first. A snapshot: the ring keeps filling behind it.
+/// A snapshot of the ring, oldest first.
 pub fn recent() -> Vec<String> {
     RING.lock()
         .unwrap_or_else(|p| p.into_inner())
@@ -91,9 +78,7 @@ mod tests {
     use super::*;
     use bevy::log::tracing_subscriber::layer::SubscriberExt;
 
-    /// The ring is a process-wide static, so this test owns the whole contract in one go: lines
-    /// land in emission order, the message field renders bare and the others as `k=v`, and the
-    /// ring drops its oldest line rather than growing past [`CAPACITY`].
+    /// One test for the whole contract, since the ring is a process-wide static.
     #[test]
     fn the_ring_keeps_the_last_lines_in_order() {
         let subscriber = bevy::log::tracing_subscriber::registry().with(LogRing);
diff --git a/crates/benilla-world/src/mac_quit.rs b/crates/benilla-world/src/mac_quit.rs
index 4e944842..9c17107a 100644
--- a/crates/benilla-world/src/mac_quit.rs
+++ b/crates/benilla-world/src/mac_quit.rs
@@ -1,36 +1,13 @@
-//! **macOS `Cmd+Q`, turned into an exit the client can see** (decision 1528).
-//!
-//! On every other exit the client gets a frame to write the player's session down — the shutdown
-//! systems run in `Last`, after the `AppExit` (`benilla_app::shutdown`). `Cmd+Q` gets none.
-//!
-//! The gesture is winit's own default menu bar: `menu.rs` builds an app menu whose *Quit* item is
-//! wired straight to AppKit's `terminate:` (`applicationDidFinishLaunching`, and only when
-//! `default_menu` is on — bevy_winit 0.18 leaves it on and exposes no
-//! `EventLoopBuilderExtMacOS` hook to turn it off). `terminate:` runs
-//! `applicationWillTerminate:`, which closes every window and calls winit's `internal_exit()` →
-//! `LoopExiting` → `bevy_winit`'s `exiting()`, which clears the world. **No `app.update()` happens
-//! anywhere in that sequence**, so there is no schedule for a shutdown system to run in and no
-//! `AppExit` for one to read. Measured on the real client, in the world: `Cmd+Q` wrote nothing —
-//! not the flat saved variables, not one addon's `saved/*.lua`, not `AddOns.txt`, not the camera
-//! pose, not `config.toml`.
-//!
-//! The fix is the one winit itself points at: *"The menubar initialization should be before the
-//! `NewEvents` event, to allow overriding of the default menu even if it's created."* We re-point
-//! that one item at **`performClose:`**, so `Cmd+Q` becomes the window close — which Bevy already
-//! models end to end (`WindowCloseRequested` → `close_when_requested` → `exit_on_all_closed` →
-//! `AppExit` in `PostUpdate` → our `Last` shutdown tail → a clean exit). For a single-window game
-//! *quit* and *close the window* are the same act, so nothing is lost by making them the same
-//! code path; what is gained is that the gesture a macOS player reaches for first stops eating
-//! their settings.
-//!
-//! `setTarget(nil)` sends it down the responder chain, so the key window handles it — the same
-//! route the red close button takes. Everything here is a no-op off macOS.
+//! macOS `Cmd+Q`, re-pointed at the window close so quitting saves the session. winit's default
+//! menu wires Quit to AppKit's `terminate:`, which tears the app down with no `app.update()`, so no
+//! `AppExit` is read and the `Last` shutdown systems never run; bevy_winit 0.18 exposes no way to
+//! turn that menu off. Re-pointed at `performClose:`, Quit becomes the window close, which Bevy
+//! carries through `AppExit` to the shutdown systems. A no-op off macOS.
 
 use bevy::prelude::*;
 
-/// Re-points macOS's *Quit* menu item at the window close, at `Startup` — which runs inside the
-/// event loop, so winit's menu already exists (it is built in `applicationDidFinishLaunching`,
-/// before the first `NewEvents`).
+/// Re-points the Quit menu item at `Startup`, which runs inside the event loop, after winit built
+/// its menu in `applicationDidFinishLaunching`.
 pub struct MacQuitPlugin;
 
 impl Plugin for MacQuitPlugin {
@@ -42,8 +19,7 @@ impl Plugin for MacQuitPlugin {
 #[cfg(not(target_os = "macos"))]
 fn route_quit_through_window_close() {}
 
-/// The `NonSendMarker` pins the system to the main thread, which is AppKit's requirement (the
-/// same param `bgwin`'s AppKit systems carry).
+/// The `NonSendMarker` pins the system to the main thread, as AppKit requires.
 #[cfg(target_os = "macos")]
 fn route_quit_through_window_close(_main_thread: bevy::ecs::system::NonSendMarker) {
     use objc2::sel;
@@ -54,12 +30,11 @@ fn route_quit_through_window_close(_main_thread: bevy::ecs::system::NonSendMarke
         return;
     };
     let app = NSApplication::sharedApplication(mtm);
-    // SAFETY: main-thread AppKit reads of the app's own menu tree, and one property write on an
-    // item we found there. Every call is the documented signature.
+    // SAFETY: main-thread AppKit reads of the app's own menu tree and property writes on the items
+    // found there, each call with its documented signature.
     let rerouted = unsafe {
         let Some(main_menu) = app.mainMenu() else {
-            // No default menu (a bundled build that supplies its own, or `default_menu` off).
-            // Nothing to correct, and nothing bound to `terminate:` to lose settings through.
+            // No default menu (a bundled build's own, or `default_menu` off): nothing to re-point.
             return;
         };
         let mut rerouted = 0usize;
@@ -71,16 +46,15 @@ fn route_quit_through_window_close(_main_thread: bevy::ecs::system::NonSendMarke
                 if entry.action() != Some(sel!(terminate:)) {
                     continue;
                 }
-                entry.setTarget(None); // down the responder chain → the key window
+                entry.setTarget(None); // nil: down the responder chain to the key window
                 entry.setAction(Some(sel!(performClose:)));
                 rerouted += 1;
             }
         }
         rerouted
     };
-    // Loud when it finds nothing: a winit change that moves or renames the item would otherwise
-    // silently restore the settings-eating gesture, and that failure is invisible from inside the
-    // client (decision 1528).
+    // Warn when nothing was found: a winit change that moves the item would otherwise silently
+    // bring back the quit that skips the shutdown systems.
     if rerouted == 0 {
         warn!(
             "mac_quit: no Quit item bound to terminate: — Cmd+Q may bypass the shutdown tail \
diff --git a/crates/benilla-world/src/map_proj.rs b/crates/benilla-world/src/map_proj.rs
index 8e83f989..44e2a0a1 100644
--- a/crates/benilla-world/src/map_proj.rs
+++ b/crates/benilla-world/src/map_proj.rs
@@ -1,44 +1,25 @@
-//! The world-map projection laws (decision 0203 phase 2) — world position ↔ normalized map UV,
-//! transcribed from the byte-verified primitives in wow-re's `ui` node (`scratch/geometry.md` +
-//! `geo-decomp.c`; provenance there: two §5 pairs, op-order diffed bit-exact, for
-//! `0x4a7100` / `0x4a72b0` / `0x4a7360` / `0x4a6ec0`).
+//! The world-map projections between world position and normalized map UV (reference `0x4a7100`,
+//! `0x4a7360`). World is wow coordinates (wx north, wy west, yards); UV is [0,1]² over the map
+//! art, u east and v south, as `GetPlayerMapPosition` returns it and FrameXML multiplies it by the
+//! detail frame's size (`x·w`, `−y·h` from TOPLEFT).
 //!
-//! Frames: **world** is wow coords (wx +north, wy +west, yards); **UV** is [0,1]² over the map
-//! art, u rightward (east), v downward (south) — exactly what `GetPlayerMapPosition` returns and
-//! what the reference FrameXML multiplies by the detail-frame size (`x·w`, `−y·h` from TOPLEFT).
-//!
-//! The world map has three levels but only two laws:
-//! - **World level** (both continents on one 62.625×41.75-tile sheet): the WorldMapContinent.dbc
-//!   constants ([`WorldProj`]) drive `0x4a7360`'s world-mode branch ([`world_uv`]).
-//! - **Continent and zone levels**: a guarded lerp over the WorldMapArea.dbc world rect
-//!   ([`zone_uv`]) — a continent is just a big zone (its areaId=0 row carries a whole-continent
-//!   rect, aspect 1.5 like every other row in the 5875 data).
-//!
-//! `0x4a72b0` (the arrow-frame variant) is the same world-mode math with a final `1 − v` flip —
-//! it feeds the y-up arrow-frame anchor path (`0x4a8d20`), not the Lua position API, so it is not
-//! transcribed here; our player blip goes through [`world_uv`]/[`zone_uv`] + FrameXML `SetPoint`
-//! exactly like the reference's `GetPlayerMapPosition` consumers.
-//!
-//! NOT here: the 128×128 area-bitmap cell law (`0x4a6ec0`) — its consumers (`ProcessMapClick`/
-//! `UpdateMapHighlight`) execute inside the engine's Lua bindings, so the transcription lives
-//! with them in benilla-ui's `script/worldmap.rs` (the grid data is pushed in the catalog; the
-//! source file is `Interface\WorldMap\<Continent>.zmp` — wow-re Q1 verdict, 2026-07-07).
+//! The world level (both continents on one 62.625×41.75-tile sheet) projects by the
+//! WorldMapContinent.dbc constants ([`world_uv`]). A continent or zone is a guarded lerp over its
+//! WorldMapArea.dbc rect ([`zone_uv`]); a continent's rect is its areaId 0 row.
 
-/// Yards per ADT tile (the binary's 0x80654c).
+/// Yards per ADT tile (reference `0x80654c`).
 const TILE_YARDS: f32 = 533.333_3;
-/// The world sheet's span in tiles: u axis (0x806548) and v axis (0x806550). Ratio 1.5 — the
-/// 1002×668 map aspect.
+/// The world sheet's span in tiles, u (`0x806548`) and v (`0x806550`), the 1002×668 art's aspect.
 const WORLD_SPAN_U_TILES: f32 = 62.625;
 const WORLD_SPAN_V_TILES: f32 = 41.75;
-/// The binary's precomputed per-axis products (0x806554/0x806558): `1/(span · tile)` — world
-/// yards → sheet fraction.
+/// Yards to sheet fraction, `1/(span · tile)`, as the reference precomputes it (`0x806554`,
+/// `0x806558`).
 const K_U: f32 = 1.0 / (WORLD_SPAN_U_TILES * TILE_YARDS);
 const K_V: f32 = 1.0 / (WORLD_SPAN_V_TILES * TILE_YARDS);
 
-/// One continent's world-level projection constants — WorldMapContinent.dbc fields 6/7/8, which
-/// the binary reads at raw-record offsets +0x18/+0x1c/+0x20 (`0x4a72b0` / `0x4a7360` world-mode).
-/// f6/f7 place the continent on the world sheet (tile units, u/v axes); f8 scales world yards
-/// onto it. The 5875 rows: EK `{14.5, −7.0, 0.75}`, Kalimdor `{−19.0, −0.32249799, 0.75}`.
+/// A continent's world-level projection: WorldMapContinent.dbc fields 6 and 7 (its sheet offset
+/// in tiles, u and v) and 8 (the yard scale), read at record +0x18/+0x1c/+0x20 (`0x4a72b0`,
+/// `0x4a7360`).
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct WorldProj {
     pub offset_u: f32,
@@ -46,8 +27,8 @@ pub struct WorldProj {
     pub scale: f32,
 }
 
-/// A map sheet's world-coordinate rect — a WorldMapArea.dbc row's loc fields. `left` = max wy
-/// (west edge), `top` = max wx (north edge); left > right and top > bottom numerically.
+/// A WorldMapArea.dbc row's world rect: `left` is the west edge (max wy), `top` the north edge
+/// (max wx), so left > right and top > bottom.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct ZoneRect {
     pub left: f32,
@@ -56,38 +37,23 @@ pub struct ZoneRect {
     pub bottom: f32,
 }
 
-/// World → UV on the world sheet (`0x4a7360` world-mode, verbatim). The axis swap is the law:
-/// u from wy (east-west), v from wx (north-south). No range check — the caller decides what
-/// off-sheet means (the reference's own world-mode consumers don't clamp here either).
+/// World to UV on the world sheet (`0x4a7360` world mode): u from wy, v from wx, unclamped as in
+/// the reference. `0x4a72b0`, the arrow frame's variant, is the same with a final `1 − v`.
 pub fn world_uv(proj: WorldProj, wx: f32, wy: f32) -> (f32, f32) {
     let u = (proj.offset_u * (1.0 / WORLD_SPAN_U_TILES) + 0.5) - wy * K_U * proj.scale;
     let v = (proj.offset_v * (1.0 / WORLD_SPAN_V_TILES) + 0.5) - wx * K_V * proj.scale;
     (u, v)
 }
 
-/// World → UV inside a zone/continent rect (`0x4a7360` zone-mode, verbatim, quirks included).
-/// Each axis is `1 − (in − low)/span` with the binary's guard shape: *both* the span and the
-/// numerator short-circuit to 0 (an input exactly on the right/bottom edge yields 0, not 1).
-/// Then the combined range check zeroes both outputs if either leaves [0,1] — the `(0,0)` the
-/// reference FrameXML reads as "not on this map, hide the blip".
+/// World to UV inside a zone or continent rect (`0x4a7360` zone mode, quirks included). Each axis
+/// is `1 − (in − low)/span`, 0 when the span or the numerator is 0, so the east and south edges
+/// yield 0, not 1. If either leaves [0,1] both are zeroed, the `(0,0)` FrameXML reads as "not on
+/// this map" (`[0x4a74d6, 0x4a7533)`: inclusive compares against 0.0 at `0x7ffd74` and 1.0 at
+/// `0x7ff9d8`).
 ///
-/// **That range check was contested and is now settled** (2026-08-25): wow-re's
-/// `scratch/gossip-poi-marker.md` §8.3 had recorded that neither axis is clamped and that "a
-/// re-implementation that clamps diverges", against `geometry.md`'s diffed reading. The re-carve
-/// found §8.3's window stopped **two bytes short** of the clamp, which lives at
-/// `[0x4a74d6, 0x4a7533)` — four `fcomp`s against `0.0` (`0x7ffd74`) and `1.0` (`0x7ff9d8`), any
-/// failure zeroing *both* outputs. §8.3 is corrected; this function was already right, and it is
-/// what makes the world map's landmark pass show a zone only its own POIs rather than scattering
-/// the continent's off-art.
-///
-/// Two residual differences from the bytes, both named rather than chased:
-///
-/// - the compares are **inclusive** — exactly `0.0` and exactly `1.0` pass, which is what
-///   `(0.0..=1.0)` does — but an **unordered** (NaN) compare passes all four in the reference and
-///   is zeroed here. No DBC-sourced or wire-sourced position can produce one.
-/// - the reference compares its two axes at **different precisions**: the first against its `f32`
-///   store, the second as the live 80-bit `st0` the `fsubr` left. An `f32` reimplementation cannot
-///   have that asymmetry, and it can only matter within an ulp of an edge.
+/// Two residual differences from the reference: a NaN passes its compares and is zeroed here (no
+/// DBC or wire position makes one), and it compares its second axis at x87 precision, which `f32`
+/// cannot copy and which matters only within an ulp of an edge.
 pub fn zone_uv(rect: ZoneRect, wx: f32, wy: f32) -> (f32, f32) {
     fn axis(input: f32, low: f32, span: f32) -> f32 {
         if input - low != 0.0 && span != 0.0 {
@@ -105,27 +71,18 @@ pub fn zone_uv(rect: ZoneRect, wx: f32, wy: f32) -> (f32, f32) {
     }
 }
 
-/// UV → world on a zone/continent rect (`0x4a7100` zone-mode, verbatim — including the binary's
-/// quirk that BOTH axes lerp by the same `t` (its v input goes unused; the real callers consume
-/// one axis per call). Returns (wx, wy).
-///
-/// Its first consumer is the dev map-jump ([`crate::ui_world_map`]), which calls it exactly that
-/// way — once for `wy` with the click's `u`, once for `wx` with its `v`. Used per-axis, this IS
-/// the exact inverse of [`zone_uv`] (unlike the world-mode pair below).
+/// UV to world `(wx, wy)` on a zone or continent rect (`0x4a7100` zone mode): both axes lerp by
+/// the same `t`, as in the reference, whose callers take one axis per call; used so, it inverts
+/// [`zone_uv`].
 pub fn zone_world(rect: ZoneRect, t: f32) -> (f32, f32) {
     let wy = rect.left - (rect.left - rect.right) * t;
     let wx = rect.top - (rect.top - rect.bottom) * t;
     (wx, wy)
 }
 
-/// UV → world at the world level (`0x4a7100` world-mode, verbatim). Returns (wx, wy). This IS
-/// the client's world-level click→world law (wow-re Q2/Q3 verdict).
-///
-/// ANOMALY, CONFIRMED REAL (wow-re Q2 verdict, 2026-07-07): NOT the algebraic inverse of
-/// [`world_uv`] when scale ≠ 1 — the true inverse needs `offset·533.33/scale` but this uses the
-/// unscaled offset; with the 5875 scale of 0.75 that's a real ~1.33× offset discrepancy. The two
-/// functions genuinely disagree at the world level; each is reproduced as-is, and a round-trip
-/// does not close. Phase 2's click path only consumes the continent pick, not the world output.
+/// UV to world `(wx, wy)` at the world level (`0x4a7100` world mode), the reference's click law.
+/// Not the inverse of [`world_uv`] when the scale is not 1: like the reference, it uses the
+/// unscaled offset, so at the 0.75 scale a round trip misses.
 #[allow(dead_code)] // transcribed law, held for its first world-output consumer
 pub(crate) fn world_click_world(proj: WorldProj, u: f32, v: f32) -> (f32, f32) {
     let wx = (proj.offset_v - ((v - 0.5) / proj.scale) * WORLD_SPAN_V_TILES) * TILE_YARDS;
@@ -133,13 +90,9 @@ pub(crate) fn world_click_world(proj: WorldProj, u: f32, v: f32) -> (f32, f32) {
     (wx, wy)
 }
 
-/// The continent's rect on the world sheet, normalized UV — the `0x4a5d00` builder kernel,
-/// verbatim (wow-re Q2 verdict: X edges `(f2·f8 + xoff)/62.625` and `((f3+1)·f8 + xoff)/62.625`
-/// with `xoff = (31.3125 − f8·32) + f6`; Y likewise over 41.75 with `yoff = (20.875 − f8·32) +
-/// f7`), from the WorldMapContinent ADT tile bounds f2..f5. This rect is the world-level click's
-/// AABB test (`0x4a7100`'s containment walk). Returns (u0, v0, u1, v1). The 5875 rects are
-/// disjoint (Kalimdor u 0.089..0.400, EK u 0.624..0.923) — unlike the WorldMapArea art rects,
-/// which overlap mid-ocean.
+/// A continent's `(u0, v0, u1, v1)` on the world sheet from its WorldMapContinent tile bounds
+/// (fields 2 to 5), the `0x4a5d00` builder: the world-level click's hit test (`0x4a7100`). The two
+/// rects are disjoint, unlike the WorldMapArea art rects, which overlap mid-ocean.
 pub fn continent_sheet_rect(bounds: (u32, u32, u32, u32), proj: WorldProj) -> (f32, f32, f32, f32) {
     let (left, right, top, bottom) = bounds;
     let xoff = (31.3125 - proj.scale * 32.0) + proj.offset_u;
@@ -155,7 +108,7 @@ pub fn continent_sheet_rect(bounds: (u32, u32, u32, u32), proj: WorldProj) -> (f
 mod tests {
     use super::*;
 
-    /// The real 5875 WorldMapContinent rows (dumped from the chain's dbc this session).
+    /// The 5875 WorldMapContinent rows.
     const EK: WorldProj = WorldProj {
         offset_u: 14.5,
         offset_v: -7.0,
@@ -166,7 +119,7 @@ mod tests {
         offset_v: -0.322_498,
         scale: 0.75,
     };
-    /// The real 5875 Elwynn row (WorldMapArea id 30).
+    /// The 5875 Elwynn row (WorldMapArea id 30).
     const ELWYNN: ZoneRect = ZoneRect {
         left: 1535.4166,
         right: -1935.4166,
@@ -181,8 +134,7 @@ mod tests {
         );
     }
 
-    /// Stormwind on the world sheet: right-hand continent (EK), southern half — the values are
-    /// the formula evaluated at the real constants; the geography is the sanity.
+    /// Stormwind, in EK's southern half; the expected values are the formula at the real constants.
     #[test]
     fn world_uv_stormwind() {
         close(world_uv(EK, -8842.0, 626.0), (0.71748, 0.63016));
@@ -200,8 +152,7 @@ mod tests {
         close(zone_uv(ELWYNN, -9450.0, 60.0), (0.42509, 0.65256));
     }
 
-    /// The rect edges: west edge → u=0; the *east* edge hits the binary's numerator guard and
-    /// yields 0 too (not 1) — transcribed quirk.
+    /// The west edge gives u = 0, and so does the east, through the reference's numerator guard.
     #[test]
     fn zone_uv_edges() {
         let (u, _) = zone_uv(ELWYNN, -9450.0, ELWYNN.left);
@@ -211,25 +162,22 @@ mod tests {
         assert!(v > 0.0, "v stays a real projection: {v}");
     }
 
-    /// Off the rect on either axis → the (0,0) "hide the blip" sentinel.
+    /// Off the rect on either axis: the (0,0) "hide the blip" sentinel.
     #[test]
     fn zone_uv_off_map() {
         assert_eq!(zone_uv(ELWYNN, -9450.0, ELWYNN.left + 10.0), (0.0, 0.0));
         assert_eq!(zone_uv(ELWYNN, ELWYNN.top + 10.0, 60.0), (0.0, 0.0));
     }
 
-    /// Zone-mode UV→world: t=0 is the rect's top-left (north-west) corner, t=1 bottom-right —
-    /// and both axes ride the same t (the transcribed 0x4a7100 quirk).
+    /// t = 0 is the north-west corner, t = 1 the south-east; both axes ride one t (`0x4a7100`).
     #[test]
     fn zone_world_corners() {
         close(zone_world(ELWYNN, 0.0), (ELWYNN.top, ELWYNN.left));
         close(zone_world(ELWYNN, 1.0), (ELWYNN.bottom, ELWYNN.right));
     }
 
-    /// Used ONE AXIS PER CALL — the way the reference's callers consume it, and the way the dev
-    /// map-jump inverts a click — `zone_world` is the exact inverse of [`zone_uv`]. This is the
-    /// claim the jump's landing accuracy rests on, so it is pinned rather than reasoned about:
-    /// a world point projects to UV, and that UV comes back to the same point.
+    /// Used one axis per call, as the reference's callers and the dev map-jump use it,
+    /// `zone_world` inverts [`zone_uv`]; the jump's landing rests on it.
     #[test]
     fn zone_world_per_axis_inverts_zone_uv() {
         for (wx, wy) in [
@@ -243,11 +191,10 @@ mod tests {
         ] {
             let (u, v) = zone_uv(ELWYNN, wx, wy);
             assert!(u > 0.0 && v > 0.0, "fixture must be on the rect: {u} {v}");
-            // wy rides the u axis, wx the v axis — the axis swap zone_uv makes.
+            // wy rides the u axis, wx the v axis: `zone_uv`'s axis swap.
             let (_, back_wy) = zone_world(ELWYNN, u);
             let (back_wx, _) = zone_world(ELWYNN, v);
-            // Yards, not `close`'s 1e-4: these coordinates are ~10^4, so f32's ~7 digits leave
-            // millimetre-scale slop. A hundredth of a yard is inverse enough to teleport onto.
+            // Yards, not `close`'s 1e-4: at ~10^4, f32 leaves millimetre slop.
             assert!(
                 (back_wx - wx).abs() < 0.01 && (back_wy - wy).abs() < 0.01,
                 "({back_wx}, {back_wy}) vs ({wx}, {wy})"
@@ -255,8 +202,7 @@ mod tests {
         }
     }
 
-    /// With scale = 1 the world-level pair IS inverse (the anomaly is scale-dependent — see
-    /// `world_click_world`'s doc); pin the transcription shape through a roundtrip.
+    /// At scale 1 the world-level pair is inverse; the mismatch is the scale's.
     #[test]
     fn world_click_roundtrip_at_unit_scale() {
         let p = WorldProj {
@@ -272,9 +218,8 @@ mod tests {
         );
     }
 
-    /// The 0x4a5d00 rect kernel at the real 5875 rows: EK tiles (23,47,15,61), Kalimdor
-    /// (23,48,9,52) — expected values hand-evaluated from the recorded formula, and the two
-    /// rects are disjoint on the u axis (the world-level click's whole disambiguation).
+    /// `0x4a5d00` at the 5875 rows, EK tiles (23,47,15,61) and Kalimdor (23,48,9,52), evaluated by
+    /// hand; disjoint on u, which is how the world-level click tells them apart.
     #[test]
     fn continent_sheet_rects_disjoint() {
         let ek = continent_sheet_rect((23, 47, 15, 61), EK);
diff --git a/crates/benilla-world/src/mat_anim_table.rs b/crates/benilla-world/src/mat_anim_table.rs
index 087f93b7..c2df4664 100644
--- a/crates/benilla-world/src/mat_anim_table.rs
+++ b/crates/benilla-world/src/mat_anim_table.rs
@@ -1,27 +1,10 @@
-//! The shared **mat-anim table** (decision 1381) — the per-frame samples of every UV-scroll /
-//! tint-animated batch material, delivered through the `wow_light` buffer instead of by mutating
-//! the material asset.
+//! The mat-anim table: per-frame samples of every UV-scroll and tint-animated batch material,
+//! delivered through the `wow_light` buffer rather than by mutating the material asset.
 //!
-//! **Why.** `doodad_anim::tick_anim_materials` used to write each drawn animated material's
-//! sampled offset into the asset every frame (`sun_scale.zw` / `tint`). Every such write is an
-//! `AssetEvent::Modified`: a uniform re-upload plus, on the Metal non-bindless path, a bind-group
-//! rebuild (~57 µs per material — B131's measurement), plus the whole-population `AssetChanged`
-//! walks it arms (`mark_meshes_as_changed_if_their_materials_changed`, the per-material-type
-//! specialization checks), plus the far-twin mirror's whole-material re-insert
-//! (`model_render::classify_water_side`). 1375 bounded the *scan* and gated *unchanged* writes;
-//! this module removes the mutation itself — the remaining half of 1370's finding.
-//!
-//! **The encoding: rows are DELTAS from the built seed, and zero is identity.** A registered
-//! material keeps its build-time `sun_scale.zw = sample(0.0)` seed (and its `tint` first-key)
-//! untouched for ever; the shader adds `matanim[slot]` on top, with **row 0 pinned to zero** so
-//! `anim_slots = 0` — every static material — reads a no-op without a branch. Zero-as-identity is
-//! [`crate::instance_tint`]'s own argument, and it buys the same three properties here: the
-//! portrait booths' studio buffers (zeroed region ⇒ the seed pose, the static studio look),
-//! deterministic captures (the tick is skipped ⇒ zero deltas ⇒ bit-identical to the old seed
-//! frames), and slot exhaustion (no slot ⇒ frozen at seed, never garbage).
-//!
-//! Region layout: between the rig-origin table and the straddle clip table ([`crate::straddle`]);
-//! the palette rows stay last (the palette array is runtime-sized) — `wow_model.wgsl`'s struct
+//! Rows are deltas from the material's build-time seed (`sun_scale.zw = sample(0.0)`, the `tint`
+//! first key), and row 0 is pinned to zero, so a static material (`anim_slots = 0`), a zeroed
+//! studio buffer, a skipped tick and an exhausted table all read the seed. The region sits between
+//! the rig-origin table and the straddle clip table, the palette last; `wow_model.wgsl`'s struct
 //! mirrors this order.
 
 use std::sync::Arc;
@@ -31,23 +14,12 @@ use bevy::render::extract_resource::{ExtractResource, ExtractResourcePlugin};
 use bevy::render::renderer::RenderQueue;
 use bevy::render::{Render, RenderApp, RenderSystems};
 
-/// Slots in the table, row 0 included (row 0 is the pinned-zero identity every static material
-/// reads). B131 observed material-anim residency grow to ~250 entries on a long single-map
-/// session, which is what sized the original 512.
-///
-/// **Raised to 2048 by decision 1408**, and measured rather than guessed: the per-placement lane
-/// gives a batch whose UV/tint loop differs between sequences one row *per placement*, and a live
-/// probe into Upper Blackrock Spire armed **145 rows within half a second of world entry** — 22
-/// placements of one 5-batch prop, each batch taking a row for its cutout material and another for
-/// its blend twin. The old ceiling would have exhausted in one dungeon, and exhaustion is silent by
-/// design (the batch stays at its built seed), i.e. it would have re-frozen exactly the bubbles the
-/// decision unfroze. The row count is inherent to the fix, not to how it is addressed — a
-/// per-instance row in a shared material would need the same 220. 2048 costs 32 KB per
-/// `wow_light`-layout buffer.
+/// Slots in the table, row 0 included. A batch whose loop differs by sequence takes a row per
+/// placement (about 145 within half a second of entering Upper Blackrock Spire), and exhaustion
+/// is silent: the batch freezes at its seed. 2048 costs 32 KB per `wow_light`-layout buffer.
 pub(crate) const MAX_MAT_ANIM_SLOTS: usize = 2048;
 
-/// Byte offset of the mat-anim region inside a `wow_light`-layout buffer: after the rig-origin
-/// table, before the straddle clip table — mirroring `wow_model.wgsl`'s struct order.
+/// Byte offset of the region in a `wow_light`-layout buffer, in `wow_model.wgsl`'s struct order.
 pub(crate) fn region_offset() -> u64 {
     crate::rig_palette::rig_origin_region_offset() + crate::rig_palette::rig_origin_region_bytes()
 }
@@ -57,30 +29,21 @@ pub(crate) fn region_bytes() -> u64 {
     (MAX_MAT_ANIM_SLOTS * 16) as u64
 }
 
-/// Off-world `wow_light`-layout buffers that also carry the mat-anim region — registered by key,
-/// the shape of [`crate::instance_tint::InstanceTintMirrors`] and, like it, deliberately its own
-/// list.
-///
-/// A lane whose materials bind a light buffer of their own — the UI model tiles, whose twins
-/// carry the widget's black light — reads `matanim[slot]` out of THAT buffer, so rows it writes
-/// into the table reach it only if the table is uploaded there too (decision 2023: the cooldown
-/// sweep's rotation rows were written every frame into a region only the world's materials ever
-/// sampled, and the tile read the zero-initialised identity). The portrait booths are not on it:
-/// a bake stands in for a world instance whose animated materials keep the world's rows, and the
-/// studio buffers' zeroed region is the seed pose those bakes were built to show.
+/// Off-world `wow_light`-layout buffers that also carry the region, by key. A lane whose materials
+/// bind their own light buffer (the UI model tiles) reads `matanim[slot]` from it, so the table is
+/// uploaded there too. The portrait booths are not on it: their zeroed region is the seed pose.
 #[derive(Resource, Clone, Default, ExtractResource)]
 pub struct MatAnimMirrors(
     pub std::collections::HashMap<&'static str, bevy::render::render_resource::Buffer>,
 );
 
-/// The live delta table. `Arc`-shared so the render-world extract is a pointer bump, and
-/// generation-stamped so a scene with nothing animated in view uploads nothing at all
-/// ([`crate::instance_tint`]'s pattern, verbatim).
+/// The live delta table, `Arc`-shared for a cheap extract and generation-stamped so an unchanged
+/// table uploads nothing.
 #[derive(Resource, Clone, ExtractResource)]
 pub struct MatAnimTable {
     rows: Arc<Vec<[f32; 4]>>,
     generation: u64,
-    /// Slot allocator: the next never-used slot, and the freed ones. Slot 0 is never handed out.
+    /// The next never-used slot and the freed ones; slot 0 is never handed out.
     next: u16,
     free: Vec<u16>,
 }
@@ -97,9 +60,8 @@ impl Default for MatAnimTable {
 }
 
 impl MatAnimTable {
-    /// Allocate a slot (1-based; 0 is the identity row). `None` when the table is full — the
-    /// caller then simply doesn't register, and the batch stays frozen at its built seed: a
-    /// degraded look only a >2047-material session could see, never a wrong pixel.
+    /// Allocate a slot, never 0; on `None` the caller does not register and the batch stays at its
+    /// seed.
     pub fn alloc(&mut self) -> Option<u16> {
         if let Some(slot) = self.free.pop() {
             return Some(slot);
@@ -113,22 +75,19 @@ impl MatAnimTable {
         }
     }
 
-    /// Read slot `slot`'s row as last written (the identity row for an out-of-range slot) — the
-    /// tile probe's view of what a lane wrote.
+    /// Slot `slot`'s row as last written, identity when out of range.
     pub fn row(&self, slot: u16) -> [f32; 4] {
         self.rows.get(slot as usize).copied().unwrap_or([0.0; 4])
     }
 
-    /// Free a slot when its registry entry dies (the material was unloaded): the row zeroes —
-    /// back to identity — so the next allocation can never inherit a dead batch's delta.
+    /// Free a slot, zeroing its row so the next owner never inherits a dead batch's delta.
     pub fn free(&mut self, slot: u16) {
         self.set(slot, [0.0; 4]);
         self.free.push(slot);
     }
 
-    /// Write slot `slot`'s delta row; a same-value write costs nothing (the tick's quantized
-    /// samples make equality the common case on slow loops). Slot 0 — the shared identity — is
-    /// refused: writing it would scroll every static batch in the world at once.
+    /// Write slot `slot`'s delta row; a same-value write costs nothing, and slot 0, which every
+    /// static batch reads, is refused.
     pub fn set(&mut self, slot: u16, row: [f32; 4]) {
         let i = slot as usize;
         if i == 0 || i >= MAX_MAT_ANIM_SLOTS || self.rows[i] == row {
@@ -138,26 +97,22 @@ impl MatAnimTable {
         self.generation += 1;
     }
 
-    /// This slot's current row (test support — the render path reads the uploaded region).
+    /// This slot's current row, for tests.
     #[cfg(test)]
     pub(crate) fn get(&self, slot: u16) -> [f32; 4] {
         self.rows.get(slot as usize).copied().unwrap_or([0.0; 4])
     }
 }
 
-/// The **affine row** (decision 2019): a texture transform's rotation and scale as the deltas
-/// from the identity the shader adds back — `[cos − 1, sin, sx − 1, sy − 1]`, with `cos`/`sin`
-/// the raw quaternion's `1 − 2z²` / `2zw` ([`benilla_formats::rotation_2x2`]). The identity
-/// encodes as the zero row, which is what lets slot 0 serve every material with no transform.
+/// A texture transform's rotation and scale as deltas from identity, `[cos − 1, sin, sx − 1,
+/// sy − 1]`, with `cos` and `sin` the quaternion's `1 − 2z²` and `2zw`; identity is the zero row.
 pub fn affine_row(q: [f32; 4], scale: [f32; 2]) -> [f32; 4] {
     let (c, s) = benilla_formats::rotation_2x2(q);
     [c - 1.0, s, scale[0] - 1.0, scale[1] - 1.0]
 }
 
-/// Render world (`PrepareResources`): write the whole 8 KB region when anything changed, gated on
-/// the generation — a scene with no drawn animated material (most of the world) never touches the
-/// queue. Whole-region writes for the same reason `instance_tint` chose them: the table is small
-/// and the write is one queue call.
+/// Render world (`PrepareResources`): write the whole region to every carrying buffer when the
+/// generation moved.
 fn upload_mat_anim(
     queue: Res<RenderQueue>,
     shared: Option<Res<crate::lighting::SharedLightBuffer>>,
@@ -166,9 +121,7 @@ fn upload_mat_anim(
     mut last: Local<Option<u64>>,
 ) {
     let Some(table) = table else { return };
-    // The generation gate covers the mirror list too (the tint table's rule): a mirror
-    // registered after the last write would otherwise hold the zero region until the next
-    // animated frame. One comparison closes the hole by construction.
+    // The gate folds in the mirror count, so a mirror registered after the last write gets rows.
     let mirrors = mirrors
         .map(|m| m.0.values().cloned().collect::<Vec<_>>())
         .unwrap_or_default();
@@ -200,7 +153,6 @@ pub fn plugin(app: &mut App) {
 mod tests {
     use super::*;
 
-    /// The affine row's identity is the zero row — the whole reason the encoding is deltas.
     #[test]
     fn the_affine_identity_is_the_zero_row() {
         assert_eq!(affine_row([0.0, 0.0, 0.0, 1.0], [1.0, 1.0]), [0.0; 4]);
@@ -216,8 +168,6 @@ mod tests {
         );
     }
 
-    /// Slot 0 is the identity row every static material in the world reads — the setter refuses
-    /// it, and freeing can never zero it "again" into a generation bump.
     #[test]
     fn slot_zero_is_never_written() {
         let mut t = MatAnimTable::default();
@@ -226,8 +176,6 @@ mod tests {
         assert_eq!(t.generation, 0, "and it costs no upload");
     }
 
-    /// The allocator hands out 1.., recycles freed slots, and a freed slot's row is back to
-    /// identity before anyone can inherit it.
     #[test]
     fn alloc_free_recycles_and_zeroes() {
         let mut t = MatAnimTable::default();
@@ -240,7 +188,6 @@ mod tests {
         assert_eq!(t.alloc().unwrap(), a, "freed slot recycles first");
     }
 
-    /// Generation moves only on real content changes — the upload gate's whole premise.
     #[test]
     fn the_generation_tracks_real_changes_only() {
         let mut t = MatAnimTable::default();
@@ -252,8 +199,6 @@ mod tests {
         assert_eq!(t.generation, 1, "same row, no upload");
     }
 
-    /// Exhaustion answers `None` (the caller skips registration — frozen at seed), and freed
-    /// slots make it recoverable.
     #[test]
     fn exhaustion_is_none_and_recoverable() {
         let mut t = MatAnimTable::default();
diff --git a/crates/benilla-world/src/mesh_tag.rs b/crates/benilla-world/src/mesh_tag.rs
index 5a9ac3bd..d6ddc327 100644
--- a/crates/benilla-world/src/mesh_tag.rs
+++ b/crates/benilla-world/src/mesh_tag.rs
@@ -1,42 +1,28 @@
-//! The per-instance `MeshTag` channel: **one home for its bit conventions and ownership protocol**
-//! (decisions 0066, 0173 — the typed field layout; 0720 — the rig field + the 6-bit alpha).
+//! The per-instance `MeshTag` channel: the one home of its bit layout and its writer protocol.
 //!
-//! Every `WowModelMaterial` submesh carries a Bevy `MeshTag` (a raw `u32` the shader reads per
-//! instance). **Bits 31 and 30 are standalone flags; bits 0..=29 are the payload.** The **rig
-//! field** (bits 19..=29) and the **alpha field** (bits 0..=5) mean the same thing in every mode;
-//! the bits between them switch meaning on **material state** — so per entity each bit has exactly
-//! one meaning at a time:
+//! Every `WowModelMaterial` submesh carries a Bevy `MeshTag`, a `u32` the shader reads per
+//! instance. Bits 31 and 30 are flags ([`HIGHLIGHT_BIT`], [`INTERIOR_FOG_BIT`]), masked off before
+//! the payload decodes. In the payload the rig and alpha fields mean the same in every mode, and
+//! the bits between them switch meaning on material state:
 //!
-//! - **Highlight** ([`HIGHLIGHT_BIT`], bit 31): the hover/target model-brighten flag — the shader
-//!   adds the client's emissive lift to the lighting sum when set. Orthogonal by construction:
-//!   no payload mode ever sets bit 31, and the shader masks it off before reading the payload —
-//!   so the untagged-⇒-opaque `0` sentinel still works on the masked value.
-//! - **Interior fog** ([`INTERIOR_FOG_BIT`], bit 30): this instance draws with the INTERIOR fog
-//!   triple (shared-light rows 18-19) instead of the scene fog. **Two conjuncts, never one**: the
-//!   model must stand in a WMO interior (the reference's per-unit classification `0x71c110` →
-//!   collector `+0x184..`, lane by `[node+0xc]&2`) *and* the room it attached to must be on the
-//!   camera's `[0xca7f00]` chain this frame (`[P+0x98] != 0`, decision 1792 §4). Both writers
-//!   below decide it that way — the classifier for entity parts, `apply_model_visibility` for
-//!   room-bound WMO content — through [`with_interior_fog`]. Masked off with bit 31 before the
-//!   payload decode.
-//! - **Instance slot** (bits 19..=29, BOTH payload modes — decisions 0720, 0812, 0820): the
-//!   per-instance index into the shared buffer's slot-keyed regions. `0` is the world's shared
-//!   no-instance sentinel (terrain, WMO, doodads, clutter, and every part of a rig-less model). Two
-//!   consumers, reading it in different stages — which is why it is no longer called "the rig slot":
-//!     - the **vertex** stage indexes the skin-palette region with it ([`crate::rig_palette`], 0720)
-//!       — but only under `WOW_RIG_SKIN`, which `WowModelExt::specialize` compiles from the **mesh's
-//!       own joint attributes**, never from this field. A static mesh carrying a slot is not skinned.
-//!     - the **fragment** stage indexes the per-instance body-tint table with it
-//!       ([`crate::instance_tint`], 0812) — for every part, skinned or not.
+//! - Rig field (bits 19..=29): the instance slot into the shared buffer's slot-keyed regions, `0`
+//!   for none. The vertex stage reads the skin palette with it ([`crate::rig_palette`]) only under
+//!   `WOW_RIG_SKIN`, which comes from the mesh's own joints; the fragment stage reads the body tint
+//!   ([`crate::instance_tint`]) for every part. Every part carries its unit's slot, so a tinted
+//!   unit tints whole (an attached model inherits its parent CM2's colours, `0x714000`); worn gear
+//!   owns a rider slot and takes the tint and the straddle waterline through its `ParentModel`
+//!   chain. Written at spawn ([`rig_bits`]) and carried by every writer but [`with_rig`].
+//! - Alpha (bits 0..=5): the fade alpha, multiplying the cutout alpha. A whole payload of `0` is
+//!   the untagged, opaque sentinel.
+//! - Exterior payload (the default): bits 6..=13 are the ground-shade byte (`0` lit, `255` fully
+//!   MCSH-shadowed), mixing the batch's lit sun level toward the shaded one (`wow_model.wgsl`).
+//!   Entities ramp it ([`crate::entity_shade`]); statics leave it `0` and shade per material
+//!   (`sun_scale.x`). Bits 14..=18 are reserved.
+//! - Interior probe slot (an interior M2 prop or entity: interior material, `model_flags.z` set,
+//!   not a WMO): bits 6..=18 are the SH-probe table slot ([`crate::lighting::PropProbes`]).
+//!   [`probe_bits`] always carries a non-zero alpha, so slot 0 is valid.
 //!
-//!   That asymmetry is why the field is written from the **unit** and not from the part: a unit's
-//!   boneless geosets and its billboard cards carry their wearer's slot, so a tinted unit tints
-//!   *whole* — the reference's own rule (an attached/chained model inherits the parent CM2's
-//!   computed colours, `0x714000`). Before 0820 the field was skinning-only, and a dwarf's
-//!   Stoneform tint stopped at his pauldrons. **Worn gear is the exception:** since 1609 every
-//!   ordinary item owns a rider slot (0841's welded items a joint rig), so its per-slot state —
-//!   the tint (`aura_visual`'s chain walk) and the straddle waterline (`crate::straddle`, 2190) —
-//!   reaches it through the item's `ParentModel` chain, never through a shared slot.
+//! The writers, deconflicted by field and by order:
 //!
 //!   Written ONCE at part spawn ([`rig_bits`]); every runtime writer below preserves it by
 //!   construction (the `with_*` accessors carry bits the writer doesn't own). 11 bits ⇔
@@ -70,109 +56,30 @@
 //!   Slot 0 is a valid payload: [`probe_bits`] always carries a non-zero alpha field, so the
 //!   shader's untagged-⇒-opaque `0` sentinel never fires for these.
 //!
-//! **Who writes it** — five systems share the channel, deconflicted *by design*, not by luck:
-//!
-//! 1. `model_fade::apply_render_fade` (appear/despawn ramps) owns an entity's **alpha field**, and
-//!    its **material**, while a `RenderFade` lives on it; the other *alpha* writers filter those
-//!    entities out (`Without<RenderFade>`, `Without<PendingAppearFade>`). It writes through
-//!    [`with_alpha`], so the shade, probe-slot and rig fields survive a fade.
-//! 2. `interior::classify_entity_interior` is the owner of the **light law** for interior-capable
-//!    parts (`InteriorLit` holders) — the payload's non-alpha fields (probe slot on the Bake law,
-//!    plain payload otherwise, dropping the shade byte, which the shade writer below re-asserts
-//!    the same frame, ordered after) **and** [`INTERIOR_FOG_BIT`] on that same population. Its
-//!    whole-payload writes go through [`with_interior_probe`] / [`with_exterior_reset`], which
-//!    carry the rig **and alpha** fields, and it then sets the flag through [`with_interior_fog`].
-//!
-//!    The law and the flag are **two questions with two answers**: the law is where the part
-//!    stands (its own down-ray, re-asked only when it moves), the flag is whether that room is on
-//!    the camera's chain (re-read every frame, because the camera moves when the part does not).
-//!    An exterior-law part is never fogged; an indoor-law one is fogged only while its room's gate
-//!    is on.
-//!
-//!    It is **not** filtered by fade state (decision 0755): the light law and the fade alpha are
-//!    orthogonal, so 1 and 2 are deconflicted by *field*, not by lockout — the law follows a part
-//!    through its appear/despawn ramp, and only the *material* defers to 1 while a fade is live
-//!    (the fade picks the blend twin **of the law's family**, `FadeMaterials::material_for`). The
-//!    old lockout is what made a streamed indoor unit ramp in under exterior light and then swap
-//!    laws in a single frame the instant the ramp latched.
-//! 3. `debug_panel::apply_model_visibility` drives the small-prop distance fade (`DoodadFade`
-//!    holders) + glow-card dimming; `DoodadFade` is **never attached** to a lit interior prop
-//!    (spawn-time exclusion in `terrain_stream`), so 2 and 3 are disjoint. The same system also
-//!    owns [`INTERIOR_FOG_BIT`] on **room-bound WMO content** — anything carrying a
-//!    `WmoGroupVis`: a building's group geometry, its doodad props, and the merged blobs of
-//!    either. That is the client's per-group `[0xca7f00]` gate, whose population is disjoint from
-//!    2's by construction (a WMO part is never classified — it holds no `InteriorLit`) and which
-//!    writes through [`with_interior_fog`], so the probe slot a prop was spawned with survives
-//!    the room turning its fog on and off.
-//! 4. `player::apply_self_model_fade` (the zoom-to-first-person feather) runs **after** 1–3 and wins
-//!    on the self body submeshes' alpha while feathering; on the frame it ends it restores the
-//!    alpha field itself and hands the material back to the part's law (it cannot lean on 2 to
-//!    re-opaque it — since 0755 that writer carries alpha through rather than forcing it).
-//! 5. `entity_shade::update_ground_shade` owns the **shade field** on entity M2 parts (decision
-//!    0173): read-modify-write via [`with_shade`], never touching alpha — so it composes with 1–4
-//!    instead of racing them, and runs after 2 to re-assert the byte over 2's exterior reclaim.
-//!
-//!    **It must skip every part whose payload is a PROBE SLOT, and there are TWO such
-//!    populations, not one.** The shade byte and the probe slot overlap in bits 6..=13, so a
-//!    shade write into a probe payload silently renames the slot — `(slot & 0x1f00) | byte`,
-//!    a foreign probe or an unallocated (zeroed ⇒ **black**) row. The classifier's Bake parts
-//!    are one population and answer with `InteriorLit::is_bake`; a WMO doodad prop spawned with
-//!    its own folded probe is the other, and it holds no `InteriorLit` at all — it answers with
-//!    [`InteriorProbePayload`]. Asking only the first question is B373: a transport's cabin
-//!    furniture is parented under the GameObject for TRANSFORM reasons, so the entity light
-//!    node's descendant walk reached props it does not light, and every one of them went black.
-//!
-//!    **It is no longer possible to forget** (2041): [`with_shade`] and [`shade_of`] take an
-//!    [`ExteriorPayload`], which only [`exterior_payload`] mints and only when both populations
-//!    answer no. The overlap itself cannot be designed away — the four mode-independent fields
-//!    cost 19 bits, leaving 13 for a payload region the two modes want 21 of — so the guarantee
-//!    has to live in the type system instead of in a reader's memory.
-//!
-//! A further *payload* writer (stealth, ghost form, …) should claim reserved bits through a typed
-//! accessor here — never a new ad-hoc whole-payload convention (decision 0066's rule, upheld by
-//! 0173's layout).
-//!
-//! **Bit 31 has its own single writer**, deconflicted by *schedule*, not by slot:
-//! `target::highlight::apply_highlight` (PostUpdate) ORs/clears it on the hovered/targeted roots'
-//! parts every frame. The payload writers above all run in Update and re-derive the payload bits
-//! (dropping the flag); running after them re-asserts it the same frame, so they never need to know
-//! it exists.
+//! A new payload writer claims reserved bits through a typed accessor here, never a whole-payload
+//! convention of its own. Bit 31's one writer, `target::highlight::apply_highlight`, runs in
+//! `PostUpdate` after the `Update` payload writers, which drop the flag, and re-asserts it.
 
-/// **This instance's payload is the interior-probe mode** — bits 6..=18 are an SH-probe table
-/// slot ([`probe_bits`]), not a ground-shade byte. Spawned onto every batch of a lit interior
-/// MODD prop (`terrain_stream`'s placed-model assembler), cards included, and read by the
-/// exterior-payload writer as its "hands off" (`entity_shade`).
-///
-/// It exists because the *other* probe-slot population — the interior classifier's Bake-law
-/// entity parts — is recognised by a component the props do not carry (`InteriorLit`), and the
-/// shade writer's guard asked for that one instead of asking the payload question. Where the two
-/// populations meet is a WMO-display GameObject: its doodad props are parented under the net
-/// entity so they ride a moving transport, which puts them inside the entity light node's
-/// descendant walk while their light is their own baked MODD colour (the reference's
-/// `CMapDoodadDef` provider `0x6a8050`, never the WENTITY node). See decision 2031 / bug B373.
+/// Marks an instance whose bits 6..=18 are an interior probe slot ([`probe_bits`]): every batch of
+/// a lit interior MODD prop. The shade writer skips it even under a WMO-display GameObject, whose
+/// props ride the entity for transform only: their light is their own baked MODD colour (the
+/// reference's `CMapDoodadDef` provider `0x6a8050`).
 #[derive(bevy::prelude::Component)]
 pub struct InteriorProbePayload;
 
-/// Bit 31 of the `MeshTag`: the hover/target **model-brighten** flag (the real client's
-/// per-model highlight emissive — `SetHighlight 0x614550` writing the config RGB into the CM2;
-/// wow-re `object-layer/scratch/selection-circle.md` PART 2). The shader adds the emissive lift
-/// to the lighting sum when set and masks the bit off before decoding the payload.
+/// Bit 31: the hover/target model-brighten flag, the reference's per-model highlight emissive
+/// (`SetHighlight` `0x614550` writes the config RGB into the CM2), added to the lighting sum.
 pub const HIGHLIGHT_BIT: u32 = 0x8000_0000;
 
-/// Bit 30 of the `MeshTag`: the **interior-fog** flag — fog this instance with the interior
-/// triple (shared-light rows 18-19, the camera-crossfaded MFOG) instead of the scene fog. Two
-/// owners over disjoint populations, both applying the same two-conjunct law (see the module doc):
-/// `crate::interior` for entity parts, `apply_model_visibility` for room-bound WMO content.
-///
-/// At camera-out the interior triple EQUALS the scene triple (the reference's t=0 lerp), so the
-/// bit cannot diverge the fog unless the camera is inside a fogged WMO. That is why it took until
-/// B335 to matter — and why the chain conjunct is the rest of the story: with the camera inside a
-/// building, "inside the same building" is *not* the same room-complex, and a unit two courtyards
-/// away wore 95 %-saturated MFOG while the walls behind it wore none (wow-re
-/// `m2-unit-interior-fog.md`; decisions 1787, 1792).
+/// Bit 30: fog with the interior triple (shared-light rows 18-19, the camera-crossfaded MFOG)
+/// instead of the scene fog. Its owners set it when the model stands in a WMO interior (the
+/// reference's per-unit classification `0x71c110`, collector `+0x184`, lane by `[node+0xc]&2`) and
+/// its room is on the camera's `[0xca7f00]` chain this frame (`[P+0x98] != 0`). With the camera
+/// outside, the interior triple equals the scene's (the crossfade at `t = 0`). The unit's lane
+/// pick (`0x6c31e0`) has no room test of its own, unlike the wall drawer's per-group `0x6b5190`.
 pub(crate) const INTERIOR_FOG_BIT: u32 = 0x4000_0000;
 
-/// Bits 0..=5 of BOTH payload modes: the fade alpha as a 6-bit fraction (`63` = opaque).
+/// Bits 0..=5, both modes: the fade alpha as a 6-bit fraction (`63` = opaque).
 const ALPHA_MASK: u32 = 0x0000_003f;
 const ALPHA_MAX: f32 = 63.0;
 /// Bits 6..=13 of the exterior payload: the ground-shade byte.
@@ -199,37 +106,22 @@ pub(crate) const LANE_MAX: u8 = 15;
 /// Bits 6..=18 of the interior payload: the SH-probe table slot (13 bits ⇔ 8192 slots).
 const PROBE_MASK: u32 = 0x0007_ffc0;
 const PROBE_SHIFT: u32 = 6;
-/// Bits 19..=29 of BOTH payload modes: the skin-palette rig slot (decision 0720); `0` = no rig.
+/// Bits 19..=29, both modes: the rig slot, `0` for none.
 const RIG_MASK: u32 = 0x3ff8_0000;
 const RIG_SHIFT: u32 = 19;
-/// Rig slots addressable by the tag's 11-bit rig field (slot 0 = the "no rig" sentinel). The
-/// palette allocator (`crate::rig_palette`) sizes itself to this.
+/// The 11-bit rig field's slot count, slot 0 (none) included; `crate::rig_palette` sizes to it.
 pub const MAX_RIG_SLOTS: usize = 1 << 11;
 
-/// An interior-probe payload constructor for RIG-LESS spawns (the static-prop spawner): the slot
-/// in bits 6..=18 + an opaque alpha field + the [`INTERIOR_FOG_BIT`]. Rig-carrying writers (the
-/// entity classifier) go through [`with_interior_probe`] instead, which preserves the rig and
-/// alpha fields.
-///
-/// It sets the fog bit where `with_interior_probe` leaves it alone, and the difference is which
-/// population each serves. This is a **spawn** value for room-bound WMO content, whose bit
-/// `apply_model_visibility` then owns and rewrites every frame from the room's gate — except for
-/// an unnamed prop that no group's MODR references, which carries no `WmoGroupVis`, is never
-/// visited by that writer, and therefore keeps this value for its whole life (1787 §5). Set is
-/// what that population has always had.
+/// An interior-probe spawn tag for a rig-less part (the static-prop spawner): the slot, an opaque
+/// alpha and [`INTERIOR_FOG_BIT`] set. `apply_model_visibility` rewrites that bit every frame for
+/// room-bound WMO content; a prop no group's MODR references has no `WmoGroupVis` and keeps it
+/// set (the reference never instantiates such a prop).
 pub(crate) fn probe_bits(slot: u16) -> u32 {
     INTERIOR_FOG_BIT | (u32::from(slot) << PROBE_SHIFT) | alpha_bits(1.0)
 }
 
-/// The alpha field a whole-payload rewrite carries through, with the whole-payload-`0`
-/// *untagged ⇒ opaque* sentinel materialized as opaque (the field is never legitimately `0` —
-/// [`alpha_bits`] floors at `1`, so a `0` here can only be the sentinel).
-///
-/// This is what lets the interior classifier **re-lane a part while a fade owns its alpha**: the
-/// law rewrites the payload, the ramp's alpha rides through untouched (decision 0755). Before it,
-/// the classifier's payload writes hardcoded opaque, which is why it had to be locked out of
-/// fading parts entirely — and why a freshly-streamed indoor entity spent its whole 2 s appear
-/// ramp on the exterior lane and swapped light laws in one frame when the ramp latched.
+/// The alpha field a whole-payload rewrite carries, the untagged `0` (which [`alpha_bits`] never
+/// writes) made opaque: it lets the classifier re-lane a part mid-fade.
 fn carried_alpha(tag: u32) -> u32 {
     match tag & ALPHA_MASK {
         0 => ALPHA_MASK,
@@ -237,22 +129,15 @@ fn carried_alpha(tag: u32) -> u32 {
     }
 }
 
-/// Rewrite a tag as an interior-probe payload, preserving the rig and alpha fields (and nothing
-/// else — the classifier owns the rest of the payload when it fires): the entity classifier's
-/// Bake-law write for skinned unit parts, whose rig slot must ride through the indoor/outdoor
-/// transitions and whose fade alpha must ride through a mid-ramp re-lane.
-///
-/// **Payload only — it does not touch [`INTERIOR_FOG_BIT`]**, unlike its spawn-side sibling
-/// [`probe_bits`]. Standing indoors is necessary for a part's fog but not sufficient: the room must
-/// also be on the camera's `[0xca7f00]` chain this frame (decision 1792 §4), so the classifier
-/// composes this with [`with_interior_fog`] and the bit has exactly one decision point.
+/// Rewrites a tag as an interior-probe payload, keeping the rig and alpha fields: the classifier's
+/// Bake law. It leaves [`INTERIOR_FOG_BIT`] to [`with_interior_fog`]: standing indoors is not
+/// enough, the room must also be on the camera's `[0xca7f00]` chain.
 pub(crate) fn with_interior_probe(tag: u32, slot: u16) -> u32 {
     (tag & RIG_MASK) | (u32::from(slot) << PROBE_SHIFT) | carried_alpha(tag)
 }
 
-/// Rewrite a tag as a fresh exterior payload, preserving the rig and alpha fields: the
-/// classifier's outdoor reclaim (the shade writer re-asserts the shade byte the same frame,
-/// ordered after).
+/// Rewrites a tag as a fresh exterior payload, keeping the rig and alpha fields: the classifier's
+/// outdoor reclaim, whose shade byte the shade writer restores later the same frame.
 pub(crate) fn with_exterior_reset(tag: u32) -> u32 {
     (tag & RIG_MASK) | carried_alpha(tag)
 }
@@ -292,10 +177,7 @@ pub fn spawn_tag(rig_slot: u16, alpha: f32) -> u32 {
     rig_bits(rig_slot) | alpha_bits(alpha)
 }
 
-/// The rig field of a part's spawn tag (decision 0720): the skin-palette rig slot, written once
-/// when the skinned part spawns (composed with [`alpha_bits`]`(1.0)` or [`probe_bits`]). Every
-/// runtime writer preserves it. Slot 0 is the "no rig" value — [`crate::rig_palette`] never
-/// allocates it.
+/// A spawn tag's rig field; slot `0`, no rig, is never allocated by [`crate::rig_palette`].
 pub fn rig_bits(slot: u16) -> u32 {
     debug_assert!((slot as usize) < MAX_RIG_SLOTS);
     u32::from(slot) << RIG_SHIFT
@@ -306,19 +188,14 @@ pub fn rig_of(tag: u32) -> u16 {
     ((tag & RIG_MASK) >> RIG_SHIFT) as u16
 }
 
-/// Rewrite a tag's rig field in place, preserving every other field and both flag bits — the
-/// lazy-rig promote/demote writer (decision 0863): a doodad part's slot arrives at its first
-/// draw-wake and leaves under table pressure, and neither edge may touch the law payload, the
-/// fade alpha, or the shade/probe field. "Written once at spawn" (the module doc) remains the
-/// rule for every OTHER lane; this is the one sanctioned re-writer, and it owns only its field.
+/// Rewrites the rig field alone: the lazy-rig writer, the one exception to written-once, whose
+/// doodad slot arrives at its first draw-wake and leaves under table pressure.
 pub(crate) fn with_rig(tag: u32, slot: u16) -> u32 {
     (tag & !RIG_MASK) | rig_bits(slot)
 }
 
-/// A fade alpha as `MeshTag` bits: 6-bit fraction in the low field, everything else zero. Handles
-/// the shader's `0`-sentinel: `MeshTag == 0` means *untagged ⇒ opaque 1.0* in `wow_model.wgsl`,
-/// so a true zero (or negative) alpha returns `1` (≈1/63, near-invisible) instead of an
-/// accidentally-opaque `0`.
+/// A fade alpha as tag bits; a zero or negative alpha writes `1` (1/63), since a `0` tag is the
+/// shader's untagged, opaque sentinel (`wow_model.wgsl`).
 pub fn alpha_bits(alpha: f32) -> u32 {
     if alpha <= 0.0 {
         1u32
@@ -327,11 +204,8 @@ pub fn alpha_bits(alpha: f32) -> u32 {
     }
 }
 
-/// Set or clear [`INTERIOR_FOG_BIT`] alone, preserving the whole payload and the highlight bit —
-/// the room-bound writer's read-modify-write. The payload is untouched on purpose: a WMO interior
-/// prop's probe slot says how it is LIT, and the client's `[0xca7f00]` decides only which fog
-/// TRIPLE its batch is pushed with. The `0` sentinel survives too, because the shader masks bits
-/// 30/31 off before testing it.
+/// Sets or clears [`INTERIOR_FOG_BIT`] alone: the probe slot says how a prop is lit, the
+/// reference's `[0xca7f00]` only which fog triple its batch gets.
 pub(crate) fn with_interior_fog(tag: u32, on: bool) -> u32 {
     match on {
         true => tag | INTERIOR_FOG_BIT,
@@ -339,60 +213,31 @@ pub(crate) fn with_interior_fog(tag: u32, on: bool) -> u32 {
     }
 }
 
-/// Write the alpha field of a tag, preserving every other field (shade or probe slot, rig, both
-/// flag bits) — the fade writers' read-modify-write (an appear-fade on a unit standing in MCSH
-/// shadow must not flash it lit, and a feathering skinned part must keep its palette).
+/// Writes the alpha field alone: the fade writers' read-modify-write.
 pub fn with_alpha(tag: u32, alpha: f32) -> u32 {
     (tag & !ALPHA_MASK) | alpha_bits(alpha)
 }
 
-/// **Proof that an instance is on the EXTERIOR payload** — that bits 6..=13 are its ground-shade
-/// byte and not the low eight bits of somebody's probe slot. The shade accessors take one, so the
-/// question cannot be skipped: there is no way to reach [`with_shade`] or [`shade_of`] without
-/// having asked [`exterior_payload`] and been told yes.
-///
-/// **The overlap is forced, so the discipline has to be typed.** The four fields that mean the
-/// same thing in both modes cost 19 bits (alpha 6, rig 11, highlight 1, interior-fog 1), leaving
-/// 13 for the payload region — and the shade byte (8) plus the probe slot (13) want 21. There is
-/// no shrinking that fits: even a 4-bit shade beside an 11-bit probe needs 15. So the two fields
-/// will always share bits 6..=13, and the only question is whether a writer can reach the wrong
-/// one by forgetting to ask. Since B373 (2031, and 2041 for the witness) it cannot: it has to hold one of these.
+/// Proof that an instance is on the exterior payload, so bits 6..=13 are its shade byte and not a
+/// probe slot's low eight; [`with_shade`] and [`shade_of`] require it. The overlap is forced: the
+/// four shared fields take 19 bits, leaving 13 for payloads that want 21 (shade 8, probe 13).
 #[derive(Clone, Copy)]
 pub struct ExteriorPayload(());
 
-/// **Ask the payload question**, the one place it is stated. `None` means this instance's bits
-/// 6..=18 are an SH-probe slot and the shade writer must leave the whole region alone.
-///
-/// Two populations hold a probe slot, and knowing only one of them is what B373 was:
-/// - `on_bake_law` — the interior classifier's Bake law, an entity part standing in a WMO room
-///   whose slot the classifier re-seats as the body moves (`interior::InteriorLit::is_bake`). A
-///   runtime state, so it is passed in rather than read off a component here.
-/// - `own_probe` — a lit interior MODD prop, whose slot was folded once at spawn and never moves
-///   ([`InteriorProbePayload`], spawned by the placed-model assembler).
-///
-/// The second only meets an entity light node on a WMO-display GameObject, whose doodad props are
-/// parented under the net entity so they ride a moving transport — a *transform* relationship that
-/// the shade writer's descendant walk read as a *light* one, renaming every cabin prop's slot to
-/// `(slot & 0x1f00) | byte`.
+/// The payload question: `None` when bits 6..=18 hold a probe slot, as for an entity part on the
+/// classifier's Bake law (`on_bake_law`, `InteriorLit::is_bake`) or a lit interior MODD prop
+/// (`own_probe`, [`InteriorProbePayload`]).
 pub fn exterior_payload(on_bake_law: bool, own_probe: bool) -> Option<ExteriorPayload> {
     (!on_bake_law && !own_probe).then_some(ExteriorPayload(()))
 }
 
-/// Write the shade byte of an exterior-payload tag (`0` = lit … `255` = fully MCSH-shadowed),
-/// preserving the alpha and rig fields and the flag bits. If the alpha field reads `0`, the tag
-/// was the whole-payload-`0` *untagged ⇒ opaque* sentinel (the field is never legitimately `0` —
-/// [`alpha_bits`] floors at `1`), so materialize it as opaque — otherwise a non-zero shade byte
-/// would defeat the sentinel and the instance would decode alpha 0 (invisible).
-///
-/// Takes an [`ExteriorPayload`] because bits 6..=13 are shared with the probe slot: see that type
-/// for why they must be, and 2031 for what happened when a caller wrote them without asking.
+/// Writes the shade byte, turning an untagged `0` opaque first: a non-zero byte would otherwise
+/// defeat the sentinel and decode as alpha 0.
 pub(crate) fn with_shade(tag: u32, shade: u8, _: ExteriorPayload) -> u32 {
     (tag & !(ALPHA_MASK | SHADE_MASK)) | carried_alpha(tag) | (u32::from(shade) << SHADE_SHIFT)
 }
 
-/// Read back the alpha field of a tag as a fraction — the decoder twin of [`alpha_bits`], for a
-/// writer's change gate and for the tests that assert what actually reached an instance. A whole
-/// payload of `0` is the shader's *untagged ⇒ opaque* sentinel, so it reads `1.0`.
+/// Reads the alpha field as a fraction; the untagged `0` reads `1.0`.
 pub fn alpha_of(tag: u32) -> f32 {
     if tag == 0 {
         return 1.0;
@@ -400,36 +245,21 @@ pub fn alpha_of(tag: u32) -> f32 {
     (tag & ALPHA_MASK) as f32 / ALPHA_MAX
 }
 
-/// Read back the shade byte of an exterior-payload tag (the shade writer's change gate). Takes the
-/// same [`ExteriorPayload`] proof as [`with_shade`]: on a probe payload these bits are the slot's
-/// low eight, so the value would be meaningless — and a change gate that compares a meaningless
-/// value is how a wrong write gets *skipped* as well as how it gets made.
+/// Reads the shade byte of an exterior-payload tag (the shade writer's change gate).
 pub(crate) fn shade_of(tag: u32, _: ExteriorPayload) -> u8 {
     ((tag & SHADE_MASK) >> SHADE_SHIFT) as u8
 }
 
-/// Whether this tag's instance draws **translucent** (`0 < α < 1`) — the depth-prime twin's
-/// activation rule ([`crate::zfill`], decision 0831), decoding exactly as the shader does: the
-/// flag bits split off first, a whole payload of `0` is the *untagged ⇒ opaque* sentinel, and a
-/// full alpha field (63) is opaque. The field is never legitimately `0` ([`alpha_bits`] floors at
-/// `1`), so there is no "invisible" branch to exclude — bits `1..=62` are the whole translucent
-/// band, matching the reference's twin gate (any batch whose evaluated `A < 0.99999` routes to the
-/// transparent lists and clones a twin; only `A ≤ 0` culls the batch outright).
+/// Whether the instance draws translucent, decoded as the shader does: the trigger of the
+/// depth-prime twin ([`crate::zfill`]). The reference sends any batch with `A < 0.99999` to the
+/// transparent lists with a twin and culls only `A ≤ 0`, so alpha fields 1..=62 are the band.
 pub(crate) fn translucent(tag: u32) -> bool {
     let payload = tag & !(HIGHLIGHT_BIT | INTERIOR_FOG_BIT);
     payload != 0 && matches!(payload & ALPHA_MASK, 1..=62)
 }
 
-/// Human-readable decode of a `MeshTag`, for the probes (`WOW_PICK`'s per-frame shading dump).
-///
-/// It lives **here** because this module owns the bit conventions: a probe that re-derived the masks
-/// would silently drift the day a field moves — which is precisely how 0355 broke (the slot moved and
-/// one of its two writers kept the old bits). The masks stay private; this is the read-out.
-///
-/// The payload's meaning switches on **material state**, which a tag alone cannot know, so BOTH
-/// readings of bits 6..=18 are printed side by side: `shade` is the exterior law's byte, `slot` the
-/// interior law's probe index. A writer using the wrong law for its material is invisible in either
-/// reading alone and obvious in the pair — a shade byte of 255 sits inside a slot of 2047.
+/// A readable decode for the probes (`WOW_PICK`'s shading dump), here so no probe re-derives the
+/// masks. Bits 6..=18 print both ways, shade and slot, since only the material says which.
 pub fn describe(tag: u32) -> String {
     if tag == 0 {
         return "0 (untagged ⇒ opaque)".to_string();
@@ -460,43 +290,37 @@ pub fn describe(tag: u32) -> String {
 mod tests {
     use super::*;
 
-    /// The exterior-payload witness for a test that is about the BITS, not about which population
-    /// an instance belongs to — the population question has its own test above.
+    /// A witness for the tests about the bits rather than the population.
     fn ext() -> ExteriorPayload {
         exterior_payload(false, false).expect("neither probe population")
     }
 
     #[test]
     fn describe_prints_both_readings_of_the_shared_bits() {
-        // The 0-sentinel is called out by name rather than decoded as "α 0.000" (invisible), which
-        // is the one thing it never means.
+        // The 0 sentinel prints by name, never as the alpha 0 it does not mean.
         assert!(describe(0).contains("untagged"));
-        // Exterior law: the shade byte. Interior law: the same bits inside the slot. Both, always.
         let t = with_shade(alpha_bits(1.0), 255, ext());
         assert!(describe(t).contains("shade 255"), "{}", describe(t));
         assert!(describe(t).contains("slot 255"), "{}", describe(t));
-        // A probe payload reads back its slot, and carries the fog flag it bakes in.
+        // A probe payload: its slot and its baked-in fog flag.
         let t = probe_bits(6660);
         assert!(describe(t).contains("slot 6660"), "{}", describe(t));
         assert!(describe(t).contains("fog"), "{}", describe(t));
-        // The rig field is printed from its own bits.
         let t = rig_bits(1234) | alpha_bits(1.0);
         assert!(describe(t).contains("rig 1234"), "{}", describe(t));
-        // Both standalone flags are named, and neither is mistaken for payload.
         assert!(describe(HIGHLIGHT_BIT | alpha_bits(0.5)).contains("hi"));
         assert!(describe(HIGHLIGHT_BIT | INTERIOR_FOG_BIT | 1).contains("hi+fog"));
     }
 
     #[test]
     fn highlight_bit_is_orthogonal_to_both_payloads() {
-        // Neither payload mode can ever set bit 31, so OR-ing/masking the flag is lossless.
         for a in [0.0, f32::MIN_POSITIVE, 0.25, 0.5, 1.0] {
             assert_eq!(alpha_bits(a) & HIGHLIGHT_BIT, 0);
         }
         assert_eq!(with_shade(alpha_bits(1.0), 255, ext()) & HIGHLIGHT_BIT, 0);
         assert_eq!(probe_bits(8191) & HIGHLIGHT_BIT, 0);
         assert_eq!(rig_bits(2047) & HIGHLIGHT_BIT, 0);
-        // Both field writers preserve an already-set flag.
+        // Both field writers keep a set flag.
         assert_eq!(
             with_alpha(HIGHLIGHT_BIT | 0x3fff_ffff, 0.5) & HIGHLIGHT_BIT,
             HIGHLIGHT_BIT
@@ -513,13 +337,11 @@ mod tests {
         assert_eq!(alpha_bits(-0.5), 1);
         assert_ne!(alpha_bits(f32::MIN_POSITIVE), 0);
         assert_eq!(alpha_bits(1.0), ALPHA_MASK);
-        // Full alpha stays inside its field — disjoint from shade, probe, and rig.
         assert_eq!(alpha_bits(1.0) & (SHADE_MASK | PROBE_MASK | RIG_MASK), 0);
     }
 
     #[test]
     fn alpha_and_shade_fields_compose() {
-        // Round-trip: shade survives an alpha write, alpha survives a shade write.
         let t = with_shade(alpha_bits(1.0), 200, ext());
         assert_eq!(shade_of(t, ext()), 200);
         let t = with_alpha(t, 0.25);
@@ -532,23 +354,20 @@ mod tests {
 
     #[test]
     fn probe_bits_compose_with_the_alpha_field() {
-        // The slot rides bits 6..=18; a fade write must preserve it (the zoom-feather bug).
         let t = probe_bits(6660);
         assert_eq!((t & PROBE_MASK) >> PROBE_SHIFT, 6660);
-        assert_eq!(t & ALPHA_MASK, ALPHA_MASK); // opaque by default — the 0-sentinel can't fire
+        assert_eq!(t & ALPHA_MASK, ALPHA_MASK); // opaque, so the 0 sentinel cannot fire
         let t = with_alpha(t, 0.25);
-        assert_eq!((t & PROBE_MASK) >> PROBE_SHIFT, 6660); // slot survives the feather
+        assert_eq!((t & PROBE_MASK) >> PROBE_SHIFT, 6660); // the slot survives a fade
         assert_eq!(t & ALPHA_MASK, alpha_bits(0.25));
         assert_eq!(t & HIGHLIGHT_BIT, 0);
-        // The max slot (8191) stays inside bits 6..=18: the rig field stays clear, and the
-        // interior-fog flag is BAKED IN (a probe payload always fogs interior).
+        // The max slot leaves the rig field clear, and the fog flag is baked in.
         assert_eq!(probe_bits(8191) & RIG_MASK, 0);
         assert_eq!(probe_bits(8191) & INTERIOR_FOG_BIT, INTERIOR_FOG_BIT);
     }
 
     #[test]
     fn rig_field_survives_every_runtime_writer() {
-        // The rig slot is written once at spawn; every steady-state writer must carry it.
         let spawn = rig_bits(1000) | alpha_bits(1.0);
         assert_eq!(rig_of(spawn), 1000);
         assert_eq!(rig_of(with_alpha(spawn, 0.3)), 1000); // fades (writers 1, 3, 4)
@@ -565,7 +384,7 @@ mod tests {
         assert_eq!(rig_of(outdoor), 1000);
         assert_eq!(outdoor & (PROBE_MASK | INTERIOR_FOG_BIT), 0);
         assert_eq!(outdoor & ALPHA_MASK, ALPHA_MASK);
-        // Alpha and probe compose under the rig field exactly as they did without it.
+        // Alpha and probe compose under the rig field.
         let t = with_alpha(indoor, 0.5);
         assert_eq!(rig_of(t), 1000);
         assert_eq!((t & PROBE_MASK) >> PROBE_SHIFT, 4321);
@@ -573,19 +392,16 @@ mod tests {
 
     #[test]
     fn interior_fog_bit_survives_the_field_writers() {
-        // The bit is set by its owners through `with_interior_fog`; the alpha/shade
-        // read-modify-writes must carry it (a feathering or MCSH-ramping indoor unit keeps
-        // its room fog).
+        // A feathering or MCSH-ramping indoor unit keeps its room fog.
         let t = INTERIOR_FOG_BIT | alpha_bits(1.0);
         assert_eq!(with_alpha(t, 0.25) & INTERIOR_FOG_BIT, INTERIOR_FOG_BIT);
         assert_eq!(
             with_shade(t, 191, ext()) & INTERIOR_FOG_BIT,
             INTERIOR_FOG_BIT
         );
-        // And it never leaks into the payload fields it rides above.
+        // It never leaks into the payload fields.
         assert_eq!(shade_of(t, ext()), 0);
         assert_eq!(t & ALPHA_MASK, ALPHA_MASK);
-        // A probe payload keeps its slot decode with the flag set.
         assert_eq!((probe_bits(6660) & PROBE_MASK) >> PROBE_SHIFT, 6660);
     }
 
@@ -652,28 +468,23 @@ mod tests {
         assert_eq!(outdoor & ALPHA_MASK, mid_ramp, "and the reclaim too");
         assert_eq!(rig_of(outdoor), 7);
         assert_eq!(outdoor & (PROBE_MASK | INTERIOR_FOG_BIT), 0);
-        // A settled (opaque) part is unaffected — the steady state still reads exactly as before,
-        // barring the flag the two constructors deliberately differ on (see `probe_bits`).
+        // An opaque part's Bake payload is the spawn constructor's, less the fog flag.
         assert_eq!(
             with_interior_fog(with_interior_probe(alpha_bits(1.0), 1234), true),
             probe_bits(1234),
             "an opaque part's Bake payload is unchanged"
         );
         assert_eq!(with_exterior_reset(probe_bits(1234)), alpha_bits(1.0));
-        // The untagged-⇒-opaque sentinel is materialized, never propagated as alpha 0 (invisible).
+        // The untagged sentinel becomes opaque, never alpha 0.
         assert_eq!(with_interior_probe(0, 1234) & ALPHA_MASK, ALPHA_MASK);
         assert_eq!(with_exterior_reset(0) & ALPHA_MASK, ALPHA_MASK);
     }
 
-    /// **Why the shade writer must never touch a probe payload** (B373): the byte lives in bits
-    /// 6..=13 and the slot in 6..=18, so a shade write does not *corrupt* the slot in a way
-    /// anything downstream can notice — it RENAMES it, to `(slot & 0x1f00) | byte`, which is a
-    /// perfectly well-formed index into somebody else's probe (or into an unallocated, zeroed
-    /// row: solid black). Pinned here because the failure has no error path anywhere: the prop
-    /// simply draws under another prop's light.
+    /// A shade write into a probe payload leaves a valid, wrong slot, `(slot & 0x1f00) | byte`:
+    /// another prop's probe, or a zeroed row that draws black, with no error anywhere.
     #[test]
     fn a_shade_write_renames_a_probe_slot_instead_of_breaking_it() {
-        let slot = 440u16; // 0b1_1011_1000 — bits 14..=18 hold 1, bits 6..=13 hold 184
+        let slot = 440u16; // 0b1_1011_1000: bits 14..=18 hold 1, bits 6..=13 hold 184
         let tag = with_shade(probe_bits(slot), 191, ext());
         assert_eq!(
             (tag & PROBE_MASK) >> PROBE_SHIFT,
@@ -689,12 +500,10 @@ mod tests {
 
     #[test]
     fn with_shade_materializes_the_untagged_sentinel_as_opaque() {
-        // Shading an untagged (payload 0) instance must not defeat the "0 ⇒ opaque" rule by making
-        // the payload non-zero with a zero alpha field.
         let t = with_shade(0, 128, ext());
         assert_eq!(t & ALPHA_MASK, ALPHA_MASK);
         assert_eq!(shade_of(t, ext()), 128);
-        // Same through the highlight bit (payload still reads 0 under the mask).
+        // Likewise under the highlight bit, whose payload still reads 0.
         let t = with_shade(HIGHLIGHT_BIT, 128, ext());
         assert_eq!(t & ALPHA_MASK, ALPHA_MASK);
     }
diff --git a/crates/benilla-world/src/model_fade.rs b/crates/benilla-world/src/model_fade.rs
index f5231566..292c25c3 100644
--- a/crates/benilla-world/src/model_fade.rs
+++ b/crates/benilla-world/src/model_fade.rs
@@ -1,109 +1,59 @@
-//! Faithful 1.12 world-doodad distance fade — the size-bucketed per-object alpha fade the reference
-//! runs every frame in `FUN_00683f80` (the world-M2-doodad fade, called unconditionally from the world
-//! render `FUN_00681070`). VERIFIED from `WoW.exe` 2026-06-01 (capstone disasm + raw PE byte reads of
-//! the operands; the 9-agent reconcile workflow `wf_33fb17c5`).
-//!
-//! ## The mechanism (VERIFIED-bytefact)
-//! Per doodad the engine computes `d = horizontal_distance(center.xy, camera.xy) − boundingRadius`
-//! (center `rec+0x5c/0x60`, radius `rec+0x68`), then picks a fade band **purely by the doodad's
-//! bounding-sphere radius** (the size split the user observed — big things stay, small props fade near):
-//!
-//! | bounding radius | fade band (start→end yd) | examples (MEASURED, not guessed) |
-//! |---|---|---|
-//! | `> 7.0`         | never fades (`1.0`)      | trees, buildings — drawn until the frustum far-clip |
-//! | `≤ 0.5`         | `40 → 50`                | candles, a dandelion, a squash — table-top scale only |
-//! | `0.5 … 2.5`     | `100 → 125`              | most fences + posts, small haystacks, field pumpkins |
-//! | `2.5 … 7.0`     | `150 → 200`              | long fence spans, big haystacks (far end clamped by farclip) |
-//!
-//! **The band is chosen by SIZE, never by what the thing is** — and the intuitive example is
-//! usually the wrong one. This table's examples were measured with
-//! `cargo run -p benilla-formats --example fade_bucket -- <substring>`, after an earlier version of
-//! this comment listed "fences, haystacks, pumpkins" against `≤ 0.5` and a reader believed it. Not
-//! one of the 42 models whose path contains "fence" is in that band: they measure 0.75–4.97 yd, so
-//! a fence fades at `100→125` or `150→200` — roughly **twice** the ~70 yd clutter horizon, the
-//! ordering a player actually sees. Across all 9691 M2s the split is 2916 / 3042 / 1840 / 1893
-//! (smallest → never-fades). Re-measure before trusting an example here.
-//!
-//! `fade = 1 − (d − start) / range`, clamped to `[0, 1]`; monotonic in size (bigger ⇒ fades farther).
-//! `fade ≥ 1` ⇒ fully opaque (drawn); `fade ≤ 0` ⇒ culled (not added to the draw list). The scalar
-//! flows `CM2Model+0x180` → `inst+0x19c` → batch alpha → the per-vertex **diffuse.a** consumed by the
-//! cutout fragment shader, where the hard alpha test (`discard if tex0.a × diffuse.a < 224/255`) turns
-//! a dropping `fade` into per-pixel edge-first erosion, and the **blend pass while `0 < fade < 1`**
-//! makes the small-prop fade read as a soft gradient rather than the trees' hard cutout edge.
-//!
-//! Verified operand bytes (`WoW.exe`): radius cutoffs `0x810188=0.5`, `0x81018c=2.5`, `0x810190=7.0`;
-//! band starts `0x8101a0/a4/a8 = 50/125/200` (ends) with ranges `0x810194/98/9c = 10/25/50`; `1.0` at
-//! `0x7ff9d8`. This REFUTES an old static-RE claim of "no size/radius weighting" — a null byte-fact
-//! lost to the user's direct observation.
+//! The 1.12 world-doodad distance fade (`0x683f80`, run every frame from the world render
+//! `0x681070`). `d` is the horizontal camera distance to the bounding-sphere centre
+//! (`rec+0x5c/0x60`) minus the radius (`rec+0x68`), and the radius alone picks the band: a candle
+//! fades at 40 to 50 yd, a fence (0.75 to 4.97 yd) or haystack at 100 to 125 or 150 to 200, a tree
+//! never (`cargo run -p benilla-formats --example fade_bucket -- <name>` measures a model). The
+//! alpha reaches the fragment's `diffuse.a` (`CM2Model+0x180` → `+0x19c`), where the 224/255 alpha
+//! test erodes a cutout edge-first; a fading doodad draws blended. Constants: radius cutoffs
+//! `0x810188`/`0x81018c`/`0x810190`, band ends (start + range) `0x8101a0`/`a4`/`a8`, ranges
+//! `0x810194`/`98`/`9c`, `1.0` at `0x7ff9d8`.
 
 use benilla_assets::materials::WowModelMaterial;
 use bevy::mesh::MeshTag;
 use bevy::prelude::*;
 
-/// Per-instance data driving the world-doodad distance fade, attached to every doodad/WMO submesh
-/// entity at spawn. `apply_model_visibility` reads `radius` + the camera distance each frame, computes
-/// the fade via [`doodad_fade_alpha`], encodes it into the entity's `MeshTag` (raw f32 bits, consumed by
-/// `wow_model.wgsl`), and swaps `MeshMaterial3d` between `cutout` (steady, `fade==1`) and `blend`
-/// (feathering, `0<fade<1`) so the soft small-prop gradient reads correctly while trees stay hard-edged.
+/// A doodad submesh's distance-fade inputs. `apply_model_visibility` writes the fade into its
+/// `MeshTag` and draws `blend` while `0 < fade < 1`, `cutout` otherwise.
 #[derive(Component, Clone)]
 pub struct DoodadFade {
-    /// World bounding-sphere radius = M2 `bounding_sphere_radius` × placement scale (yd) — VERIFIED as
-    /// the reference's `rec+0x68` (`FUN_006952a0`: `radius × scale`). Selects the fade band.
+    /// The scaled bounding-sphere radius (yd), the reference's `rec+0x68` (`0x6952a0`).
     pub(crate) radius: f32,
-    /// The model's authored bounding-box **centre** in Bevy model-local space. At runtime the entity's
-    /// `GlobalTransform` maps it to the world sphere centre (the reference's `rec+0x5c/0x60`); the fade
-    /// distance is measured to THAT, not the placement origin — `FUN_006952a0` transforms `(min+max)/2`.
+    /// The model-local bounding-box centre the fade measures to (`0x6952a0`), not the origin.
     pub(crate) local_center: Vec3,
-    /// Steady-state material (the submesh's authored blend mode: opaque trunk / alpha-test canopy).
+    /// The steady material, in the submesh's authored blend mode.
     pub(crate) cutout: Handle<WowModelMaterial>,
-    /// `AlphaMode::Blend` variant of the same texture — used only while the object is feathering.
+    /// Its `AlphaMode::Blend` twin, drawn only while feathering.
     pub(crate) blend: Handle<WowModelMaterial>,
 }
 
-/// Radius above which a doodad **never** distance-fades (trees/buildings): drawn until the frustum
-/// far-clip drops the whole object. `> 7.0` yd bounding-sphere radius.
+/// Above this bounding radius (yd) a doodad never distance-fades; only the far clip drops it.
 pub const NEVER_FADE_RADIUS: f32 = 7.0;
 
-/// The three fading size buckets: `(max_radius, band_start_yd, band_range_yd)`. A doodad uses the first
-/// bucket whose `max_radius` it does not exceed; `fade = 1 − (d − start) / range`. Exact `FUN_00683f80`
-/// constants (see module docs). Buckets are ordered small→large; `NEVER_FADE_RADIUS` caps the table.
+/// `(max_radius, band_start, band_range)` in yd; a doodad takes the first row it does not exceed.
 const BUCKETS: [(f32, f32, f32); 3] = [
-    (0.5, 40.0, 10.0),  // ≤ 0.5 yd → 40→50  (candles/dandelions — NOT fences)
-    (2.5, 100.0, 25.0), // ≤ 2.5 yd → 100→125
-    (NEVER_FADE_RADIUS, 150.0, 50.0), // ≤ 7.0 yd → 150→200
+    (0.5, 40.0, 10.0),
+    (2.5, 100.0, 25.0),
+    (NEVER_FADE_RADIUS, 150.0, 50.0),
 ];
 
-/// The per-object distance-fade alpha for a doodad of bounding-sphere `radius` (yd, already scaled by
-/// the placement scale) whose center is `horiz_dist` yd from the camera **in the horizontal plane**
-/// (vertical offset ignored — the reference uses 2D distance). Returns the alpha multiplier in
-/// `[0.0, 1.0]`:
-/// - `1.0`  → fully opaque (draw normally; the cutout alpha test is unaffected).
-/// - `0.0`  → fully faded (the caller should cull the object — it contributes nothing).
-/// - `0<f<1`→ feathering; the object should draw **blended** so the fade reads as a soft gradient.
-///
-/// Doodads with `radius > NEVER_FADE_RADIUS` always return `1.0` (trees/buildings never fade here —
-/// they rely on the separate frustum far-clip cull).
+/// The distance-fade alpha of a doodad of `radius` yd (placement scale applied) whose centre is
+/// `horiz_dist` yd away in the horizontal plane (the reference ignores height). `0.0` means cull.
 pub fn doodad_fade_alpha(radius: f32, horiz_dist: f32) -> f32 {
     if radius > NEVER_FADE_RADIUS {
         return 1.0;
     }
-    // `d` is distance-to-surface (center distance minus the bounding radius), matching the reference's
-    // `dist − radius`; a bigger object therefore starts fading at a greater center distance.
     let d = horiz_dist - radius;
     let (_, start, range) = BUCKETS
         .iter()
         .copied()
         .find(|(max_r, _, _)| radius <= *max_r)
-        // radius ≤ NEVER_FADE_RADIUS here, so the last bucket (max_r == NEVER_FADE_RADIUS) always matches.
+        // Unreached: the last row's bound is `NEVER_FADE_RADIUS`.
         .unwrap_or((NEVER_FADE_RADIUS, 150.0, 50.0));
     (1.0 - (d - start) / range).clamp(0.0, 1.0)
 }
 
-/// The fade-band edges for a fader of bounding-sphere `radius`: `(near, far)` horizontal
-/// CENTRE distances — [`doodad_fade_alpha`] is `1.0` at `d ≤ near`, `0.0` at `d ≥ far`, and
-/// feathers between. `None` for a never-fader. The static-gx exile scan (B2, decision 1431)
-/// classifies placements on these edges, derived from the SAME bucket table the per-frame
-/// alpha evaluates — one source, so the two verdicts can never disagree.
+/// The `(near, far)` centre distances between which [`doodad_fade_alpha`] feathers, from the same
+/// `BUCKETS` rows, so the retained static pass that rings its cells on them cannot disagree.
 pub fn fade_band(radius: f32) -> Option<(f32, f32)> {
     if radius > NEVER_FADE_RADIUS {
         return None;
@@ -116,55 +66,29 @@ pub fn fade_band(radius: f32) -> Option<(f32, f32)> {
     Some((start + radius, start + radius + range))
 }
 
-/// The faithful per-object **appear / spawn fade** (`wow-5875-re` object-layer/`appear-fade`): a CGObject
-/// — every streamed unit, GameObject, and player — ramps its render alpha `α = t³` over **2 s wall-clock**
-/// when it first becomes visible, then latches opaque. This is the *temporal* sibling of [`DoodadFade`]'s
-/// *distance* fade: both drive the **same** per-instance render-alpha channel (the `MeshTag` the shader
-/// reads, with a cutout↔blend material swap while `α < 1`), matching the reference's single render-alpha
-/// slot (`CM2Model+0x19c`) written by separate sources for disjoint object categories (map doodads →
-/// distance fade; CGObjects → appear fade). [`apply_render_fade`] drives it.
-///
-/// It owns the part's **alpha** and its **material** while it lives; [`crate::interior`]'s
-/// classifier keeps owning the part's **light law** right through the ramp (decision 0755), and
-/// the fade reads that law each frame to pick the blend twin of the right family
-/// ([`FadeMaterials::material_for`]) — so an entity that streams in indoors ramps up already lit by
-/// its room instead of appearing under exterior light and snapping to the room's when it latches.
-///
-/// One channel, **two curves**, and that is the reference's shape rather than a generalisation of
-/// ours (decisions 2198/2203). Both ramps write this same per-instance alpha, but they are different
-/// functions armed by different subsystems: the appear ramp is `FadeTo 0x614f80` eased cubically by
-/// the object's own vtable slot 14, and the teardown ramp is the `SWModelFadeout` pump `0x672ef0`
-/// smoothstepping a *detached* model the object left behind. [`FadeCurve`] is which one; the
-/// teardown case is `{curve: Smoothstep, from: the live α, to: 0, duration: 2 s}` plus a
-/// despawn-on-complete system ([`DespawnFade`]), the appear case
-/// `{curve: Cubic, from: 0, to: 1, duration: 2 s}`. (Decision 0032; teardown fidelity corrected in
-/// 0067, its mechanism pinned in 2198 and its curve in 2203.)
+/// A render-alpha ramp on one part's `MeshTag`, drawn on the blend twin while `α < 1`
+/// ([`apply_render_fade`]). The appear ramp is `FadeTo` (`0x614f80`), cubic over 2 s from first
+/// visibility; the teardown is the `SWModelFadeout` pump (`0x672ef0`) on the model an object left
+/// behind ([`DespawnFade`]). The interior classifier keeps the light law through either.
 #[derive(Component, Clone)]
 pub struct RenderFade {
-    /// `Time::elapsed_secs` when the fade was armed (the entity's first-visible moment).
+    /// `Time::elapsed_secs` at arming.
     pub started: f32,
-    /// Fade length in seconds. Both ramps are [`APPEAR_FADE_SECS`] in 1.12 — the appear `FadeTo`'s
-    /// `0x7d0` argument and the teardown pump's `age > 0x7d0` unlink are the same 2000 ms.
+    /// Seconds; both reference ramps are 2000 ms (`FadeTo`'s `0x7d0`, the pump's `age > 0x7d0`).
     pub duration: f32,
-    /// Ramp endpoints. Appear `0 → 1`; teardown `live α → 0` (where `from` is the pump's
-    /// `startAlpha`, which scales the ramp rather than lerping from it — see
-    /// [`teardown_fade_alpha`]).
+    /// Appear `0 → 1`; teardown `live α → 0`, `from` being the pump's `startAlpha`.
     pub from: f32,
     pub to: f32,
     /// Which of the reference's two ramps this is.
     pub curve: FadeCurve,
 }
 
-/// Which of the reference's two render-alpha ramps a [`RenderFade`] runs. They are not
-/// parameterisations of one curve: the appear ease lives on the CGObject
-/// (`0x614a90`, `α = lerp(from, to, t³)`) and the teardown ease lives on the scene-node fadeout
-/// scheduler the object hands its model to on the way out (`0x672ef0`, `α = smoothstep(1 − t)`).
+/// The reference's two render-alpha ramps, two functions and not one curve: the CGObject's appear
+/// ease (`0x614a90`, `t³`) and the fadeout scheduler's teardown (`0x672ef0`, `smoothstep(1 − t)`).
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
 pub enum FadeCurve {
-    /// [`fade_alpha`] — the appear ramp.
     #[default]
     Cubic,
-    /// [`teardown_fade_alpha`] — the `SWModelFadeout` ramp.
     Smoothstep,
 }
 
@@ -178,8 +102,7 @@ impl RenderFade {
     }
 }
 
-/// The reference's appear-fade duration — `FadeTo(1.0, 2000 ms)` (`wow-5875-re` object-layer/`appear-fade`:
-/// byte `0x7d0`, wall-clock via `OsGetAsyncTimeMs`, framerate-independent).
+/// The appear fade's length, `FadeTo(1.0, 2000 ms)` on the wall clock (`OsGetAsyncTimeMs`).
 pub const APPEAR_FADE_SECS: f32 = 2.0;
 
 impl RenderFade {
@@ -195,106 +118,47 @@ impl RenderFade {
     }
 }
 
-/// The reference's cubic-ease render-alpha: `α = lerp(from, to, clamp(t, 0, 1)³)` (`0x614a90`: `fld t;
-/// fmul t; fmul t`). `t` is the fractional fade age. This is the **appear** ramp, and only the
-/// appear ramp: the teardown runs a different function entirely ([`teardown_fade_alpha`]).
+/// The appear ramp, `lerp(from, to, clamp(t, 0, 1)³)` at fractional age `t` (`0x614a90`).
 pub fn fade_alpha(from: f32, to: f32, t: f32) -> f32 {
     let t = t.clamp(0.0, 1.0);
     from + (to - from) * t * t * t
 }
 
-/// The reference's **teardown** render-alpha — the `SWModelFadeout` pump `0x672ef0`
-/// (`doodad_despawn_fade`, wow-re models PRIMITIVE, diffed bit-exact against the x87), which is
-/// what drives a model handed to the scheduler `0x672df0` by the base OnDeactivate `0x6145e0`
-/// (decision 2203):
-///
-/// ```text
-/// t = clamp((1 − age_ms · 0.0005 [0x80c698]) · startAlpha, 0, 1)
-/// α = (3 − 2t) · t²                                  ; smoothstep
-/// ```
-///
-/// `t_frac` is the fractional fade age (`age_ms · 0.0005` at the reference's fixed 2 s window), so
-/// the ramp inside the smoothstep *descends*. `start_alpha` is the object's live transition alpha
-/// at the hand-off (`obj+0xf4`) — **scaling the ramp, not the output**, which is why this is not
-/// expressible as a `lerp` and gets its own function rather than a flag on [`fade_alpha`].
-///
-/// Against the appear curve reversed — what benilla ran before the mechanism was pinned — this is a
-/// visibly different shape: at the half-way mark `1 − t³` is still at 0.875 where this is at 0.5.
+/// The teardown ramp, the `SWModelFadeout` pump (`0x672ef0`): `α = (3 − 2t) · t²` with
+/// `t = clamp((1 − t_frac) · startAlpha, 0, 1)`, `t_frac` being `age_ms · 0.0005` (`[0x80c698]`).
+/// `start_alpha`, the live alpha at the hand-off (`obj+0xf4`), scales the ramp, not the output.
 pub fn teardown_fade_alpha(start_alpha: f32, t_frac: f32) -> f32 {
     let t = ((1.0 - t_frac) * start_alpha).clamp(0.0, 1.0);
     (3.0 - 2.0 * t) * t * t
 }
 
-/// The scheduler's own **skip gate** (`0x672df0` @ `0x672e21`, the float compare against
-/// `[0x8029d0]`): a model handed over at less than this alpha is unlinked on the spot
-/// (`0x671ac0`) instead of being faded — it had nothing left to show. Below it, benilla pops.
+/// The scheduler's skip gate (`0x672df0` @ `0x672e21`, against `[0x8029d0]`): a model handed over
+/// below this alpha is unlinked at once (`0x671ac0`), not faded.
 pub const TEARDOWN_MIN_ALPHA: f32 = 0.01;
 
-/// One model instance's live **render alpha** — the reference's `CM2Model+0x19c`, and the single
-/// slot every fade in the client writes through (wow-re object-layer/`appear-fade` §"the alpha
-/// slot"): `+0x19c = argAlpha · +0x180`, with `+0x180 = obj+0x100 (master) · obj+0xf4 (the appear
-/// ramp)` for a CGObject and the distance fade for a map doodad.
-///
-/// benilla keeps that alpha on the MESH side in the per-part `MeshTag` (the appear/despawn ramp,
-/// the self-avatar feather, the doodad fade — three writers, one channel). This component is the
-/// same number published **per model instance**, for the consumers that are not meshes and cannot
-/// read a `MeshTag`: an emitter's particles and a ribbon's strip, whose alpha is per-vertex colour
-/// (decision 0827). Missing ⇒ `1.0`.
-///
-/// An **attached** model inherits its parent's, which is why an item's effects read their WEARER's
-/// (the `0x714000` recursion: a child model with `[model+0x1cc] ≠ 0` composes onto the parent's
-/// computed colours and alpha — wow-re `selection-circle.md` §scope, `0x714260`'s `[ebp+0x14]`).
-/// That inheritance is [`ParentModel`] + [`ModelAlphas`], never a spawn site pointing at the top
-/// of the chain by hand (decision 0833).
+/// A model instance's render alpha, the reference's `CM2Model+0x19c` (`argAlpha · +0x180`, where
+/// `+0x180` is `obj+0x100 · obj+0xf4` for a CGObject and the distance fade for a doodad), for the
+/// consumers that cannot read a `MeshTag`: particles and ribbons. Missing reads `1.0`.
 #[derive(Component, Clone, Copy, Debug, PartialEq)]
 pub struct ModelAlpha(pub f32);
 
-/// **A fade the game declares on an instance root** — a plain multiplier the engine folds into
-/// the composed model alpha beside its own appear and despawn ramps.
-///
-/// 1164's inversion, in one component. The alpha channel had six writers, three of them gameplay,
-/// each carrying a `Without<…>` lockout against the others; the reference has **one** slot
-/// (`CM2Model+0x19c`). The rule this establishes: the game says *how translucent this thing should
-/// be and why* (an aura's ramp, a stealth dip, a ghost form); the engine owns the write, the
-/// composition down the `ParentModel` chain, and the material swap that goes with it.
-///
-/// Absent reads `1.0`, so a root that has never declared one costs nothing.
+/// A fade the game declares on an instance root (an aura's ramp, stealth, a ghost form); the engine
+/// folds it into the composed alpha and owns the write. Absent reads `1.0`.
 #[derive(Component, Clone, Copy, Debug)]
 pub struct ModelFade(pub f32);
 
-/// The model instance this one is **chained to** — the reference's `[model+0x1cc]` parent link,
-/// set on a model that was attached to another model (`0x712f70 CM2Model::attachChild`). An item
-/// root's parent is its wearer; a weapon's enchant-glow instance's parent is that item root; a
-/// spell kit hung on a unit's is the unit.
-///
-/// It exists because composition is **recursive** in the reference (`0x714000` walks the chain and
-/// composes each child onto its parent's *computed* colour and alpha) and every spawn site knows
-/// exactly one thing for certain: who it just attached itself to. Asking a site for the far end of
-/// the chain instead is what left a weapon's glow — two links down — with no alpha source at all,
-/// blazing at full strength over a character that had not faded in yet (decision 0833).
+/// The model this one is attached to, the reference's `[model+0x1cc]` (`0x712f70`,
+/// `CM2Model::attachChild`). A spawn site names only its immediate parent.
 #[derive(Component, Clone, Copy, Debug, PartialEq)]
 pub struct ParentModel(pub Entity);
 
-/// How far a [`ParentModel`] walk goes before giving up — [`ModelAlphas`], and the tint's twin walk
-/// in [`crate::aura_visual`]. The real chains are 1–3 links (unit → item → glow); the bound is a
-/// cycle backstop, not a policy.
+/// The bound on a [`ParentModel`] walk, a cycle backstop: real chains are 1 to 3 links.
 pub const MAX_MODEL_CHAIN: usize = 8;
 
-/// The composed render alpha of a model instance — [`ModelAlpha`] multiplied along the
-/// [`ParentModel`] chain, i.e. the reference's `0x714000` recursion as a lookup. This is the number
-/// an effect multiplies into its vertex alpha; **an effect passes its OWN instance root** and the
-/// chain supplies everything above it.
-///
-/// Missing components read as opaque throughout: an entity with no alpha and no parent is `1.0`,
-/// which is why the steady-state world pays nothing for this.
-///
-/// **A link the engine does not compose reads its DECLARED fade.** [`ModelAlpha`] is published by
-/// [`publish_model_alpha`], which runs over streamed objects — a model tree the engine never
-/// composes (a booth bake, which has no appear ramp, no despawn ramp and no self feather, and whose
-/// value is final the moment it is built) therefore carries only the [`ModelFade`] its owner
-/// declared. Reading that when there is no published alpha is what lets one law cover both: the
-/// game still only ever declares (1164), and the walk is still the reference's `0x714000` recursion.
-/// A streamed unit carries both and the published one wins, because that one has the ramps folded in.
+/// A model instance's composed render alpha, the reference's recursion (`0x714000`, `0x714260`):
+/// `child+0x19c = parent+0x19c × child+0x180` up the [`ParentModel`] chain, so an effect passes
+/// its own instance root. A link with no published [`ModelAlpha`] (a booth bake) reads its
+/// [`ModelFade`]; the published one wins.
 #[derive(bevy::ecs::system::SystemParam)]
 pub struct ModelAlphas<'w, 's> {
     chain: Query<
@@ -309,8 +173,7 @@ pub struct ModelAlphas<'w, 's> {
 }
 
 impl ModelAlphas<'_, '_> {
-    /// `instance`'s composed alpha. A despawned link ends the walk (its effects are being freed
-    /// this frame anyway — [`crate::particles::OwnerLoss::Free`]).
+    /// `instance`'s composed alpha; a despawned link (its effects freed with it) ends the walk.
     pub fn get(&self, instance: Entity) -> f32 {
         let mut alpha = 1.0;
         let mut at = instance;
@@ -318,7 +181,7 @@ impl ModelAlphas<'_, '_> {
             let Ok((published, declared, parent)) = self.chain.get(at) else {
                 break;
             };
-            // Published wins: it is the declared fade with this frame's ramps already folded in.
+            // Published wins: it already folds the declared fade in.
             if let Some(a) = published.map(|a| a.0).or(declared.map(|d| d.0)) {
                 alpha *= a;
             }
@@ -331,21 +194,10 @@ impl ModelAlphas<'_, '_> {
     }
 }
 
-/// The render alpha of one streamed model instance this frame — pure, so the composition is pinned
-/// by tests without an ECS (the `model_fade` pattern):
-///
-/// - the **appear** ramp: none ⇒ opaque; pending ⇒ 0 (the entity is not being shown yet, so its
-///   effects must not be either — this is the login symptom); live ⇒ the cubic ramp,
-/// - × the **despawn** ramp (our stream-out look, 0032/0067) once armed,
-/// - × the **self-avatar** zoom feather, which applies to the player's own body alone,
-/// - × the **aura** alpha (`crate::aura_visual` — stealth's 0.3, invisibility's 0.5, …): the ramped
-///   CharProc-14 product. In the reference this is not a separate channel at all — the aura
-///   recompute drives the SAME `StartAlphaFade` slot the appear-fade uses (`0x60d180` →
-///   `0x614f80` → `obj+0xf4` → `+0x180` → `+0x19c` → `emitter+0x1a8`), which is exactly why a
-///   stealthed unit's weapon-glow particles and ribbons dim with it.
-///
-/// The product is the reference's own shape: it multiplies the transition alpha into the same
-/// `+0x180` slot rather than keeping a second channel.
+/// One streamed model's render alpha: the product of the appear ramp (0 while pending, hiding its
+/// effects too), the teardown, the self zoom feather and the declared fade, as the reference
+/// multiplies the transition alpha into `+0x180`; its aura recompute drives the appear fade's own
+/// `StartAlphaFade` (`0x60d180` → `0x614f80` → `obj+0xf4` → `+0x180` → `+0x19c` → `emitter+0x1a8`).
 pub fn model_render_alpha(
     now: f32,
     appear: Option<UnitAppearFade>,
@@ -360,32 +212,16 @@ pub fn model_render_alpha(
             fade_alpha(0.0, 1.0, (now - started) / APPEAR_FADE_SECS)
         }
     };
-    // The teardown's own curve (2203) — the same smoothstep the mesh channel runs, so an emitter's
-    // particles and a ribbon's strip thin out in step with the geometry they hang off rather than
-    // holding opaque while it feathers away.
+    // The mesh channel's teardown smoothstep, so effects thin out with their geometry.
     let despawn = despawn_started.map_or(1.0, |started| {
         teardown_fade_alpha(1.0, (now - started) / APPEAR_FADE_SECS)
     });
     (appear * despawn * self_fade * declared).clamp(0.0, 1.0)
 }
 
-/// **One streamed unit's live render alpha, asked of the unit** — the same product
-/// [`publish_model_alpha`] publishes as [`ModelAlpha`], answered on demand from the root's own
-/// presentation state.
-///
-/// [`ModelAlphas`] is the read side for a consumer that can wait for the publish: it looks up a
-/// number written in `PostUpdate` and composed down the [`ParentModel`] chain. This is the read
-/// side for a consumer that **cannot** — one that runs in `Update`, or on the very frame a unit's
-/// presentation begins, where the published component does not exist yet (`publish_model_alpha`
-/// inserts it through `Commands`). Both answer the same question from the same law
-/// ([`model_render_alpha`]); they differ only in where the inputs come from.
-///
-/// It exists because a consumer that reconstructs the answer for itself gets it wrong in the same
-/// way every time. The blob shadow gathered the live [`RenderFade`]s off a unit's *part* entities
-/// and read "no part is fading" as opaque — which is true of a settled unit and false of a
-/// **pending** one, whose parts are deliberately invisible and carry no `RenderFade` at all. The
-/// unit root is where the answer is unambiguous, because [`UnitAppearFade`] distinguishes the two
-/// states that a part-side walk cannot tell apart.
+/// A streamed unit's render alpha computed from its root, for a consumer that runs before
+/// [`publish_model_alpha`] (in `Update`, or on a unit's first frame). Ask the root: a pending
+/// unit's parts carry no [`RenderFade`], so a walk over them reads it as opaque.
 #[derive(bevy::ecs::system::SystemParam)]
 #[allow(clippy::type_complexity)] // one query, the four facets of a unit's presentation
 pub struct UnitRenderAlpha<'w, 's> {
@@ -404,11 +240,7 @@ pub struct UnitRenderAlpha<'w, 's> {
 }
 
 impl UnitRenderAlpha<'_, '_> {
-    /// `unit`'s render alpha this frame. A unit with nothing in flight — and an entity this query
-    /// cannot read at all — is `1.0`, so a settled world costs one lookup and no arithmetic.
-    ///
-    /// The viewer's own body carries the zoom feather here exactly as the publisher applies it,
-    /// so a caller never folds it in itself.
+    /// `unit`'s render alpha, zoom feather included; `1.0` for an entity it cannot read.
     pub fn get(&self, unit: Entity) -> f32 {
         let Ok((appear, despawn, declared, is_self)) = self.units.get(unit) else {
             return 1.0;
@@ -423,13 +255,11 @@ impl UnitRenderAlpha<'_, '_> {
     }
 }
 
-/// The door's own tests — the states a consumer that reconstructs this number gets wrong.
 #[cfg(test)]
 mod unit_render_alpha_tests {
     use super::*;
     use bevy::ecs::system::SystemState;
 
-    /// A world at `now`, holding one unit root built by `build`.
     fn unit_at(now: f32, build: impl FnOnce(&mut bevy::ecs::world::EntityWorldMut)) -> f32 {
         let mut world = World::new();
         let mut time = Time::<()>::default();
@@ -444,10 +274,6 @@ mod unit_render_alpha_tests {
         alpha
     }
 
-    /// **The blob shadow's bug, as the door now answers it.** A streamed unit waiting on the
-    /// world to be shown carries `UnitAppearFade::Pending` and no live `RenderFade` anywhere in
-    /// its tree; a consumer that asks "is any part of this unit fading" hears no and draws itself
-    /// opaque over an invisible creature. Asking the ROOT distinguishes the two.
     #[test]
     fn a_pending_unit_is_zero_and_a_settled_one_is_opaque() {
         assert_eq!(
@@ -471,9 +297,6 @@ mod unit_render_alpha_tests {
         );
     }
 
-    /// The unarmed `DespawnFade` sentinel is the component's business, not each caller's — the
-    /// negative `started` a stream-out stamps before it arms would otherwise read as a fade that
-    /// began long ago and finished, i.e. a unit that vanishes the moment it is marked.
     #[test]
     fn an_unarmed_despawn_stamp_is_not_a_fade() {
         assert_eq!(DespawnFade::default().armed(), None);
@@ -494,20 +317,13 @@ mod unit_render_alpha_tests {
         );
     }
 
-    /// **The two ramps are different functions** (decision 2203), and this is the test that would
-    /// have caught benilla running one of them backwards in place of the other. The appear ease is
-    /// the CGObject's own (`0x614a90`, `t³`); the teardown ease is the scene-node fadeout
-    /// scheduler's (`0x672ef0`, `smoothstep(1 − t)`), and they agree only at the endpoints.
     #[test]
     fn the_teardown_curve_is_not_the_appear_curve_reversed() {
-        // Endpoints — the only place they may agree.
         assert_eq!(teardown_fade_alpha(1.0, 0.0), 1.0, "opaque at the hand-off");
         assert_eq!(teardown_fade_alpha(1.0, 1.0), 0.0, "gone at the window end");
-        // The middle, where the old curve was visibly wrong: 1 − 0.5³ = 0.875 against 0.5.
+        // Mid-window: 0.5, against the reversed cubic's 1 − 0.5³ = 0.875.
         assert!((teardown_fade_alpha(1.0, 0.5) - 0.5).abs() < 1e-6);
         assert!((fade_alpha(1.0, 0.0, 0.5) - 0.875).abs() < 1e-6);
-        // Monotone down over the window, and clamped past it (the pump unlinks at `age > 2000`,
-        // so nothing ever samples beyond 1.0 — but a late frame must not read as re-appearing).
         let mut prev = f32::INFINITY;
         for i in 0..=20 {
             let a = teardown_fade_alpha(1.0, i as f32 / 20.0);
@@ -520,8 +336,6 @@ mod unit_render_alpha_tests {
             "clamped past the window"
         );
 
-        // `start_alpha` scales the RAMP, not the output — the reference multiplies it inside the
-        // clamp (`(1 − age·0.0005)·startAlpha`), which is why this is not a lerp from it.
         assert!(
             teardown_fade_alpha(0.25, 0.0) < 0.25,
             "smoothstep(0.25) < 0.25"
@@ -533,9 +347,6 @@ mod unit_render_alpha_tests {
         );
     }
 
-    /// An entity the query cannot read at all — a shadow whose owner was despawned this frame,
-    /// a booth part with no presentation — is opaque, never an accidental 0 that blinks the
-    /// thing out on its last frame.
     #[test]
     fn an_unreadable_owner_is_opaque() {
         let mut world = World::new();
@@ -548,12 +359,9 @@ mod unit_render_alpha_tests {
     }
 }
 
-/// Publish [`ModelAlpha`] on every streamed object each frame. Runs in `PostUpdate`, after every
-/// Update-side fade writer and the camera controller that computes the self feather, and before the
-/// effect sims that consume it ([`crate::particles`], [`crate::ribbons`]).
-///
-/// Opaque is the default and costs nothing: an entity that has never faded gets no component at all
-/// (a missing one reads `1.0`), so the steady-state world carries none of these.
+/// Publish [`ModelAlpha`] on every streamed object. `PostUpdate`: after every fade writer and the
+/// self feather, before the effect sims that read it ([`crate::particles`], [`crate::ribbons`]).
+/// An object that never faded gets none.
 #[allow(clippy::type_complexity)] // one query, five optional facets of the same entity
 pub(crate) fn publish_model_alpha(
     time: Res<Time>,
@@ -572,17 +380,14 @@ pub(crate) fn publish_model_alpha(
     >,
     // A declaration that went away is a change the `Ref` cannot see: those units are due.
     mut undeclared: RemovedComponents<ModelFade>,
-    // The appear ramp's RETIREMENT is a removal too — the frame it goes, the alpha must land
-    // on its final value, not hold the ramp's last sample (review 2026-09-04).
+    // So is the appear ramp's removal: the alpha must land on its final value.
     mut ramp_done: RemovedComponents<UnitAppearFade>,
 ) {
     let now = time.elapsed_secs();
     let mut undeclared: bevy::platform::collections::HashSet<Entity> = undeclared.read().collect();
     undeclared.extend(ramp_done.read());
     for (entity, appear, despawn, is_self, declared, current) in &mut units {
-        // With no ramp in flight and not the self body, the alpha is the declared fade alone —
-        // a published value that cannot have moved unless the declaration did. Every resident
-        // unit was recomputed and compared each frame (decision 1979's floor).
+        // No ramp and not the self body: only a changed declaration can move the alpha.
         if appear.is_none()
             && despawn.is_none()
             && !is_self
@@ -598,10 +403,8 @@ pub(crate) fn publish_model_alpha(
             appear.copied(),
             despawn.and_then(DespawnFade::armed),
             if is_self { viewer.self_fade } else { 1.0 },
-            // The game's declared fade — the aura ramp ticks it in Update (`apply_aura_alpha`)
-            // and this runs PostUpdate, so it is fresh. `self_fade` above is the bare zoom
-            // feather (the mesh-side writer folds the aura factor separately), so this is not a
-            // double application on the self body.
+            // Ticked in `Update` (`apply_aura_alpha`), so fresh here. `self_fade` is the bare zoom
+            // feather, so the self body does not take the aura twice.
             declared.map_or(1.0, |d| d.0),
         );
         match current {
@@ -618,26 +421,14 @@ pub(crate) fn publish_model_alpha(
     }
 }
 
-/// The camera-to-target span (yd) over which the **player's own** avatar fades from hidden (camera near)
-/// to opaque (camera out) as you zoom into first-person. VERIFIED from `WoW.exe` 5875 (`0x8089b0`; the
-/// self-model transparency setter `0x5b7bb0`, recorded in wow-re `system/ui/scratch/follow-camera.md`).
+/// The camera-to-target span (yd) over which the player's own body fades in (`0x8089b0`).
 pub const SELF_FADE_WINDOW: f32 = 1.8315;
-/// Distance-above-nearclip below which the avatar **hard-hides** (fully invisible — true first-person).
-/// VERIFIED `0x5b7bb0`: `D ≤ 0.00278` ⇒ α 0 + first-person, else the cosine ramp.
+/// The distance above the near clip at or below which the body hides: first person.
 pub const SELF_FADE_HIDE: f32 = 0.00278;
 
-/// The faithful **self-avatar transparency** as the camera nears its target — the fade that turns your
-/// own character translucent while zooming in, then fully invisible in first-person. VERIFIED from
-/// `WoW.exe` 5875 (`0x5b7bb0`, wow-re `follow-camera`): a cosine smoothstep on the camera-to-target
-/// distance, `α = (1 − cos(π·D/F))/2` over `D = dist − nearclip ∈ (SELF_FADE_HIDE, window]`. Below
-/// [`SELF_FADE_HIDE`] above the near clip the model hard-hides (`0.0`); at/after `window` it's opaque
-/// (`1.0`). `nearclip` is the camera's near-plane distance — the fade completes exactly as the near
-/// plane would begin to slice the model, which is why the two are coupled — the caller passes the
-/// LIVE `nearclip` ([`crate::view::ViewDistance::nearclip`]), not a constant, so a player who moves
-/// the near plane moves the fade with it (2163).
-///
-/// Unlike [`doodad_fade_alpha`] (horizontal *world* distance, size-bucketed) this is the *camera*
-/// distance to a single tracked object; both feed the same per-instance render-alpha channel.
+/// The player's own body alpha by camera distance (`0x5b7bb0`): `(1 − cos(π·D/window)) / 2` for
+/// `D = dist − nearclip`, 0 at or below [`SELF_FADE_HIDE`]. Pass the live `nearclip`
+/// ([`crate::view::ViewDistance::nearclip`]): the fade is measured from the near plane.
 pub fn self_model_fade_alpha(dist: f32, nearclip: f32, window: f32) -> f32 {
     let d = dist - nearclip;
     if d <= SELF_FADE_HIDE {
@@ -649,24 +440,15 @@ pub fn self_model_fade_alpha(dist: f32, nearclip: f32, window: f32) -> f32 {
     0.5 * (1.0 - (std::f32::consts::PI * d / window).cos())
 }
 
-/// Drive every live [`RenderFade`]: ramp the cubic alpha into the per-instance `MeshTag`, ride the
-/// blend twin of the part's **current light law** while feathering (the cutout ignores `α`), and
-/// drop the component once an appear fade latches opaque (handing the material back to
-/// [`crate::interior`] on the law's steady variant). Only freshly-streamed or streaming-out
-/// entities carry a `RenderFade` — it's removed after [`APPEAR_FADE_SECS`] — so the steady-state
-/// cost is nil.
-///
-/// The material is resolved from [`FadeMaterials`] + the live [`crate::interior::InteriorLit`]
-/// every frame rather than from a pair latched at arm time (decision 0755), so a part that
-/// classifies (or re-classifies) *during* its ramp follows its room's light immediately instead of
-/// finishing the ramp on whichever law happened to hold when the fade armed.
+/// Drive every live [`RenderFade`]: write its alpha into the `MeshTag`, draw the blend twin of the
+/// part's live light law ([`crate::interior::InteriorLit`]) while `α < 1`, resolved every frame so
+/// a part that classifies mid-ramp follows its room, and remove an appear fade once opaque.
 #[allow(clippy::type_complexity)]
 pub fn apply_render_fade(
     time: Res<Time>,
     mut commands: Commands,
-    // The water-plane axis (`model_render::classify_water_side`), composed into this writer's
-    // own pick via `far_resolved` — every owner of the handle channel derives the same composed
-    // handle from state, so the ramp and the classifier converge instead of re-swapping.
+    // The water-plane axis, composed into this writer's pick (`far_resolved`) so the ramp and the
+    // classifier derive the same handle instead of re-swapping.
     far_twins: Res<crate::model_render::FarSideTwins>,
     mut q: Query<(
         Entity,
@@ -686,24 +468,15 @@ pub fn apply_render_fade(
         } else {
             1.0
         };
-        // The fade owns the alpha field while it lives, so it is also where the batch's animated
-        // material factor multiplies in — the reference's combine is literally a product,
-        // `A = instanceAlpha × colourAlpha × weight` (wow-re `m2-alpha-combine-cull.md`), and the
-        // fade ramp IS this instance's alpha. Without this a unit appearing mid-Death would flash
-        // its death-only geometry opaque for the length of the ramp.
+        // The batch's animated factor multiplies in (`A = instanceAlpha × colourAlpha × weight`,
+        // `0x707b0b`, `0x707b33`), or death-only geometry shows through the ramp.
         let alpha = fade.alpha_at(t) * anim.map_or(1.0, |a| a.current);
-        // `with_alpha` handles the `MeshTag == 0` opaque-sentinel — else a just-spawned object at
-        // α 0 would flash fully opaque — and preserves the ground-shade byte, so a unit fading in
-        // under MCSH shadow doesn't flash lit (the conventions live in `crate::mesh_tag`).
+        // `with_alpha` keeps the ground shade and never writes the untagged, opaque `0`.
         let bits = crate::mesh_tag::with_alpha(tag.0, alpha);
         if tag.0 != bits {
             tag.0 = bits;
         }
-        // Feather on the blend twin while translucent; the cutout (opaque/alpha-test) ignores `α`.
-        // Both come from the part's CURRENT law — an indoor part feathers probe-lit and settles on
-        // the probe-lit steady material, with no law change at the latch. A part without
-        // `FadeMaterials` has no twin to swap to (it never fades in practice — every arming site
-        // pairs the two); its alpha still ramps, so it can never hang invisible.
+        // The cutout ignores `α`; a part without `FadeMaterials` still ramps, never hanging hidden.
         if let Some(fm) = fm {
             let want = crate::model_render::far_resolved(
                 fm.material_for(lit, alpha < 1.0),
@@ -714,73 +487,47 @@ pub fn apply_render_fade(
                 mat.0 = want.clone();
             }
         }
-        // Appear fade reached opaque: latch and release the channel back to the interior classifier.
-        // `try_remove`: wire-owned entity — see the lifetime contract in `arm_appear_fade`.
+        // An opaque appear fade hands the material back to the interior classifier.
         if t >= 1.0 && fade.to >= 1.0 {
             commands.entity(entity).try_remove::<RenderFade>();
         }
     }
 }
 
-/// A streamed entity that should appear-fade, **waiting to be armed**. The reference arms the fade when
-/// an object *becomes visible to the player* (visibility processor `0x4651a0`), NOT at stream-in — so the
-/// ramp plays while you can see it instead of completing **behind the loading screen** (login / `.tele`)
-/// or far off-screen. benilla attaches this at spawn (the entity rendered invisible meanwhile) and
-/// [`arm_appear_fade`] converts it into a live [`RenderFade`] once the world is actually being shown.
-/// (Decision 0032.)
+/// An appear fade waiting to arm, the entity hidden meanwhile. The reference arms it on the object
+/// becoming visible (`0x4651a0`), not at stream-in, so it never plays behind a loading screen.
 #[derive(Component, Clone)]
 pub struct PendingAppearFade {
-    /// `Time::elapsed_secs` at attach — the backstop-timeout origin.
+    /// `Time::elapsed_secs` at attach, the backstop timeout's origin.
     pub since: f32,
 }
 
-/// Backstop: arm a pending fade after this long even if the world never reports "shown" — bounds the
-/// worst case (a stuck load) so an entity can never hang invisible. Generous so it almost never fires
-/// before the real signal (the loading screen dropping) does.
+/// Arm a pending fade after this long anyway, so a stuck load cannot leave an entity invisible.
 const PENDING_TIMEOUT_SECS: f32 = 8.0;
 
-/// The appear-fade's clock, mirrored onto a streamed unit's **root** entity the moment its body first
-/// arms an appear-fade — decision 0032 read as a **per-unit** property (the reference fades a whole
-/// CGUnit — body plus every attached model — as one), not a per-mesh stamp taken only at the instant a
-/// given submesh happens to spawn. A held item / helm / shoulder resolves and spawns *later* than the
-/// body (an async template round trip, a model load — `entities::equipment::attach_held_items`); it
-/// reads this marker to **join** the unit's ramp instead of either spawning fully opaque (no marker
-/// consulted — the original bug: attachments popped in while the body eased) or restarting its own
-/// fade from zero (would desync the two visually). Mirrors [`PendingAppearFade`]/[`RenderFade`]'s two
-/// states one level up the hierarchy: [`arm_appear_fade`] advances both in lockstep (same trigger, same
-/// instant, so a late joiner reads "live" exactly when the rest of the unit does), and
-/// [`retire_unit_appear_fade`] drops it once the mirrored ramp completes — after that instant the unit
-/// has fully appeared, so anything spawning later (a gear swap, a delayed resolve) is a fresh
-/// presentation and correctly spawns steady, nil ongoing cost, same as the per-mesh channel.
-///
-/// See [`join_unit_appear_fade`] for the join decision a spawn site makes from this, kept as a pure
-/// function over plain data so it's unit-testable without the ECS.
+/// The appear fade's clock on a streamed unit's root. The reference fades a unit and its attached
+/// models as one, so a part that resolves later (a held item) joins this ramp; it is dropped when
+/// the ramp ends, after which a new part spawns steady.
 #[derive(Component, Clone, Copy, Debug, PartialEq)]
 pub enum UnitAppearFade {
-    /// Waiting for the world to be shown — mirrors [`PendingAppearFade::since`].
+    /// Waiting for the world to be shown.
     Pending { since: f32 },
-    /// The live ramp in progress — mirrors [`RenderFade::started`]. A joiner copies `started` verbatim
-    /// rather than sampling the current alpha: [`fade_alpha`] is a pure function of elapsed time, so an
-    /// identical `started` reproduces the identical curve for as long as both instances live — that
-    /// *is* what "joining the current position" means, no stored alpha required.
+    /// A joiner copies `started`, which reproduces the same curve.
     Live { started: f32 },
 }
 
-/// What a part spawning onto a unit should do about the unit's appear-fade, derived by
-/// [`join_unit_appear_fade`] from the unit root's [`UnitAppearFade`] (or its absence).
+/// What a part spawning onto a unit does about the unit's appear fade.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum JoinedFade {
-    /// No unit-level fade in flight (never armed, e.g. a WMO-display entity — or already latched):
-    /// spawn steady, exactly as a part attached long after the unit fully appeared does today.
+    /// No unit fade in flight: spawn steady.
     Steady,
-    /// Join the still-pending fade: arm together with the rest of the unit once the world is shown.
+    /// Arm with the unit once the world is shown.
     Pending { since: f32 },
-    /// Join the live ramp already in progress, at its current position (see [`UnitAppearFade::Live`]).
+    /// Join the running ramp at its current position.
     Live { started: f32 },
 }
 
-/// The join decision for a part spawning onto a unit whose root carries `unit` (or doesn't). Pure and
-/// total — extracted so the decision is testable without spinning up the ECS (see the tests below).
+/// The join decision for a part spawning onto a unit whose root carries `unit`.
 pub fn join_unit_appear_fade(unit: Option<UnitAppearFade>) -> JoinedFade {
     match unit {
         None => JoinedFade::Steady,
@@ -789,13 +536,8 @@ pub fn join_unit_appear_fade(unit: Option<UnitAppearFade>) -> JoinedFade {
     }
 }
 
-/// Arm each [`PendingAppearFade`] into a live [`RenderFade`] once the world is on-screen — the
-/// loading screen is not covering (it used to read the `focus_resident` proxy, which goes true
-/// well before the screen actually drops now that the clear waits for the whole scene — decision
-/// 0737) — or after [`PENDING_TIMEOUT_SECS`] as a backstop. This is the faithful trigger: the ramp
-/// starts when the player can actually see the entity. Also advances each unit-root
-/// [`UnitAppearFade`] clock in lockstep (same trigger, same instant) — a separate, smaller query
-/// since the root marker carries no material handles.
+/// Arm each [`PendingAppearFade`] once the loading screen stops covering the world, or after
+/// [`PENDING_TIMEOUT_SECS`], and advance each root's [`UnitAppearFade`] on the same instant.
 pub(crate) fn arm_appear_fade(
     time: Res<Time>,
     viewer: Res<crate::view::Viewer>,
@@ -810,20 +552,14 @@ pub(crate) fn arm_appear_fade(
     let now = time.elapsed_secs();
     let shown = !viewer.world_covered;
     let mut armed = 0usize;
-    // Of those, the world-ROOT billboard cards (decision 0836). Called out separately because a
-    // card reaches this system through nothing but its own spawn — no tree walk can find it — so
-    // "how many cards armed" is the one readout that separates "the cards fade" from "the cards
-    // are simply absent from the ramp", which is what they were.
+    // Counted apart: a world-root billboard card arms only through its own spawn.
     let mut armed_cards = 0usize;
     for (entity, pending, is_card) in &q {
         if shown || now - pending.since > PENDING_TIMEOUT_SECS {
             armed += 1;
             armed_cards += usize::from(is_card);
-            // `try_*`, like every fade command here: these entities are **wire-owned** — a net
-            // destroy can apply at any sync point between this system's query and its own
-            // commands, so fade bookkeeping on an already-dead entity is a no-op, never an error.
-            // (The observed crash: the login load ends, every pending fade arms in one frame,
-            // and a same-frame wire despawn beat this insert — decision 0200.)
+            // `try_*`, like every fade command here: the entities are wire-owned, and a net destroy
+            // can land between this query and its commands.
             commands
                 .entity(entity)
                 .try_insert(RenderFade::appear(now))
@@ -837,10 +573,7 @@ pub(crate) fn arm_appear_fade(
             }
         }
     }
-    // `WOW_INTERIOR_LOG=1`: the appear-fade's arming instant — the reference time the interior
-    // classifier's `[interior]` lines are read against. The seam between the two is where an
-    // indoor entity's light law used to land only AFTER the ramp latched (2 s of exterior light,
-    // then a pop); a run where the two instants coincide is the observable that closes it.
+    // `WOW_INTERIOR_LOG=1`: the arming instant the `[interior]` lines are read against.
     if armed > 0 && std::env::var_os("WOW_INTERIOR_LOG").is_some() {
         eprintln!(
             "[fade-arm] t {now:.2} armed {armed} parts ({armed_cards} billboard cards) \
@@ -849,10 +582,7 @@ pub(crate) fn arm_appear_fade(
     }
 }
 
-/// Drop a [`UnitAppearFade::Live`] once its mirrored ramp completes ([`APPEAR_FADE_SECS`] after
-/// `started`): past that instant the unit has fully appeared, so a part spawning later (a delayed
-/// template resolve, a gear change) is a fresh presentation rather than a continuation, and
-/// [`join_unit_appear_fade`] should treat it exactly like a unit that never had a marker at all.
+/// Drop a [`UnitAppearFade::Live`] once its ramp has run, so a later part spawns steady.
 pub(crate) fn retire_unit_appear_fade(
     time: Res<Time>,
     mut commands: Commands,
@@ -862,50 +592,30 @@ pub(crate) fn retire_unit_appear_fade(
     for (entity, fade) in &q {
         if let UnitAppearFade::Live { started } = fade {
             if now - started >= APPEAR_FADE_SECS {
-                // `try_remove`: wire-owned entity — the lifetime contract in `arm_appear_fade`.
+                // `try_remove`: the entity is wire-owned (`arm_appear_fade`).
                 commands.entity(entity).try_remove::<UnitAppearFade>();
             }
         }
     }
 }
 
-/// Persistent per-submesh fade material set — **the** source of truth for which material a part
-/// draws with, across every fade in the client: `cutout` = the steady opaque/alpha-test material,
-/// `blend` = its `AlphaMode::Blend` twin. Attached to every fadeable entity submesh at spawn.
-///
-/// Held persistently rather than copied into each fade (decision 0755): a latched pair is a
-/// snapshot of the part's light law at arm time, and a law that changes mid-ramp — a streamed
-/// indoor unit classifying while it appears, an NPC crossing a doorway as it fades out — cannot be
-/// expressed by one. Every fade instead resolves its material *per frame* through
-/// [`Self::material_for`].
+/// A fadeable part's materials, which every fade resolves per frame ([`Self::material_for`]):
+/// `cutout` steady, `blend` its `AlphaMode::Blend` twin.
 #[derive(Component, Clone)]
 pub struct FadeMaterials {
     pub cutout: Handle<WowModelMaterial>,
     pub blend: Handle<WowModelMaterial>,
-    /// The interior-BAKE variant's blend twin (probe-lit): a fade on a bake-classified part rides
-    /// this so its light stays the room's probe through the feather instead of jumping to the
-    /// exterior twin's lit-outdoor intensity (0355). `None` for parts without a bake variant.
+    /// The interior bake variant's blend twin, keeping a bake-lit part's room light as it feathers.
     pub bake_blend: Option<Handle<WowModelMaterial>>,
-    /// The depth-prime twin material ([`crate::model_render::zfill_material`] — the reference's
-    /// `M2UseZFill` clone, wow-re `m2-blend-promotion-zfill.md` §4, decision 0831). While this
-    /// part's instance alpha sits in `(0, 1)`, [`sync_zfill_twins`] keeps a colour-masked,
-    /// z-writing child mesh alive on it, drawn before the model's colour parts — one blended layer
-    /// everywhere, no self-overlap darkening. `None` for a batch whose material disables
-    /// z-write/z-test (the reference's own twin gate).
+    /// The depth-prime twin, the reference's `M2UseZFill` clone (`0x707f7d`): while the alpha is in
+    /// `(0, 1)` a z-writing, colour-masked child draws first, so the model blends as one layer.
+    /// `None` where the material disables z-write or z-test, the reference's own gate.
     pub zfill: Option<Handle<WowModelMaterial>>,
 }
 
 impl FadeMaterials {
-    /// The material a part should draw with, given its current interior law (`lit` — `None` for a
-    /// part the classifier doesn't light) and whether it is still `feathering` (`α < 1`).
-    ///
-    /// The two axes are independent and this is the one place they compose, so every fade writer —
-    /// the appear/despawn ramp ([`apply_render_fade`]) and the self-avatar zoom feather
-    /// ([`crate::player::apply_self_model_fade`]) — agrees on the answer regardless of which runs
-    /// last in the frame. Feathering picks the law's **blend** twin (the probe-lit one indoors, so
-    /// the room's light rides the fade rather than jumping to the exterior twin's outdoor
-    /// intensity — 0355); settled hands back the law's **steady** material, which is the
-    /// classifier's own choice ([`crate::interior::InteriorLit::steady_material`]).
+    /// The law's blend twin while `feathering`, its steady material otherwise; the one place the
+    /// two compose, so every fade writer agrees whichever runs last.
     pub fn material_for<'a>(
         &'a self,
         lit: Option<&'a crate::interior::InteriorLit>,
@@ -920,39 +630,24 @@ impl FadeMaterials {
     }
 }
 
-/// The material handles one batch fades *through*, as a spawn site borrows them — the inputs
-/// [`FadeMaterials`] is built from. `blend: None` means the batch cannot feather at all (a
-/// WMO-display batch builds no twin), which is the one legitimate reason for a part to spawn
-/// opaque while its unit is still ramping. A MULTIPLY batch (Mod/Mod2x) passes its **steady self**
-/// as the twin: its blend equation reads no alpha (decision 0528), so no material swap can feather
-/// it — instead it arms the ramp like any other part and `wow_model.wgsl` lerps its colour toward
-/// the blend identity by the tag alpha — 0865's mechanism, since proven the reference's own
-/// (preset 5 lerps the source colour by the instance alpha; decision 1489).
+/// The materials a spawning batch fades through. `blend: None` means it cannot feather (a
+/// WMO-display batch), the one reason to spawn opaque during the unit's ramp. A multiply batch
+/// (Mod, Mod2x) passes its steady self: its blend reads no alpha, so `wow_model.wgsl` lerps its
+/// colour toward the blend identity by the tag alpha, as the reference's preset 5 does.
 pub struct FadeSet<'a> {
     pub steady: &'a Handle<WowModelMaterial>,
     pub blend: Option<&'a Handle<WowModelMaterial>>,
     pub bake_blend: Option<&'a Handle<WowModelMaterial>>,
-    /// The depth-prime twin (decision 0831). Carried here for the same reason as the rest of the
-    /// set: it is needed exactly while the batch is feathering — which a card now does too.
     pub zfill: Option<&'a Handle<WowModelMaterial>>,
 }
 
-/// One batch's appear-fade membership for a spawn: the unit's clock ([`JoinedFade`]) folded with
-/// whether the batch is fade-capable at all.
-///
-/// **Every** batch spawn resolves it here and dresses through [`Self::dress`] — the body's mesh
-/// parts and its billboard cards, a held item's mesh parts and its cards. The law is a property of
-/// the *model*, not of how benilla happens to parent a batch: the reference has one instance alpha
-/// (`CM2Model+0x19c`) that every batch of the model draws through, billboard batches included, so a
-/// lane that skips this is a batch that pops opaque over a body still fading in. Both card lanes did
-/// exactly that until decision 0836.
+/// One batch's appear-fade membership, which every batch spawn (billboard cards included) resolves
+/// and dresses through: the reference draws every batch of a model through one instance alpha.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum PartFade {
-    /// No ramp to join (unit already appeared, or the batch cannot feather): open opaque.
+    /// No ramp to join, or the batch cannot feather: open opaque.
     Steady,
-    /// Join the unit's still-pending ramp — arm together with it once the world is on screen.
     Pending(f32),
-    /// Join the ramp already running, at its current position.
     Live(f32),
 }
 
@@ -966,9 +661,8 @@ impl PartFade {
         }
     }
 
-    /// The material and `MeshTag` alpha the spawn should OPEN on. A pending part opens on the blend
-    /// twin at ≈0 so it never flashes opaque for a frame before [`apply_render_fade`] takes over; a
-    /// joiner opens at the ramp's *current* alpha so it doesn't flash invisible either.
+    /// The material and `MeshTag` alpha the spawn opens on, so no part flashes before its first
+    /// [`apply_render_fade`].
     pub fn seed(self, set: &FadeSet<'_>, now: f32) -> (Handle<WowModelMaterial>, f32) {
         match self {
             Self::Steady => (set.steady.clone(), 1.0),
@@ -980,11 +674,8 @@ impl PartFade {
         }
     }
 
-    /// Dress the spawned batch: the persistent [`FadeMaterials`] record whenever it is fade-capable
-    /// at all — that is a *material record*, not a record of having armed a fade, and the stream-out
-    /// fade and the self-avatar zoom feather both re-arm from it — plus the arm itself when this
-    /// spawn is joining the unit's ramp. Returns whether it armed, which the attach path mirrors
-    /// onto the unit root so a later-resolving attachment can join the same ramp.
+    /// Insert [`FadeMaterials`] on any batch that can feather, whether or not it joins a ramp (the
+    /// teardown and zoom feather use it too), and arm the join; returns whether it armed.
     pub fn dress(self, child: &mut bevy::ecs::system::EntityCommands, set: &FadeSet<'_>) -> bool {
         if let Some(blend) = set.blend {
             child.insert(FadeMaterials {
@@ -996,8 +687,6 @@ impl PartFade {
         }
         match self {
             Self::Steady => false,
-            // `arm_appear_fade` starts the ramp once the world is on-screen (not behind the loading
-            // screen), so it plays where the player can actually see it.
             Self::Pending(since) => {
                 child.insert(PendingAppearFade { since });
                 true
@@ -1016,25 +705,13 @@ impl PartFade {
     }
 }
 
-/// Marks a streamed entity (the parent) whose object has gone away — out of range, destroyed, or
-/// released from the despawn-animation pin: instead of popping it out, [`apply_despawn_fade`]
-/// fades it out and then despawns it. `started < 0` ⇒ not yet armed/stamped.
-///
-/// **This is the reference's teardown, one hop below where an earlier round looked** (decision
-/// 2198). The object-manager destroy `0x464920` — which `SMSG_DESTROY_OBJECT` (`0x4674a0`) and the
-/// `SMSG_UPDATE_OBJECT` OUT_OF_RANGE **destroy** `0x465ec0` both reach (`0x465f4f`/`0x465fa6`;
-/// 2198 cited `0x465fd0` for this, which is the type-4/5 *block* arm and genuinely is reached —
-/// it just unpacks the packed guids and discards every one. The destroy runs earlier, off the
-/// leading-block check `0x4651e1`) — invokes the object's vtable
-/// slot 1, whose base `0x6145e0` unbinds the scene handle and hands the model to the
-/// **`SWModelFadeout` scheduler `0x672df0`**: the model outlives the object and its alpha is
-/// ramped to zero by the per-frame pump `0x672ef0` (wow-re `models/models.md` §"Doodad despawn
-/// fade", `object-layer/scratch/w2d2-decomp.c` `FUN_006145e0`). So the object *is* freed on the
-/// spot — the paragraph this supersedes was right about that — and the thing you watch fade is
-/// its orphaned model. One arm covers both wire routes, which is why one component does here.
-///
-/// 0067 settled the *look* from the director's eyes while the mechanism was unpinned; the
-/// mechanism is the scheduler; the curve and window it uses are 2203's.
+/// A streamed object gone away (out of range, destroyed, or released from its despawn pin), which
+/// [`apply_despawn_fade`] fades out and then despawns; `started < 0` is not yet armed. In the
+/// reference `SMSG_DESTROY_OBJECT` (`0x4674a0`) and `SMSG_UPDATE_OBJECT`'s out-of-range destroy
+/// (`0x465ec0`, run off the leading-block check `0x4651e1`, calling at `0x465f4f`/`0x465fa6`; the
+/// type-4/5 block arm `0x465fd0` only discards its guids) reach the object destroy `0x464920`,
+/// whose vtable slot 1 (base `0x6145e0`) hands the model to the `SWModelFadeout` scheduler
+/// (`0x672df0`): the object is freed at once and its orphaned model fades out.
 #[derive(Component)]
 pub struct DespawnFade {
     pub(crate) started: f32,
@@ -1047,39 +724,22 @@ impl Default for DespawnFade {
 }
 
 impl DespawnFade {
-    /// The instant this fade-out was armed, or `None` while the stamp is still the unarmed
-    /// sentinel — the shape [`model_render_alpha`] takes its `despawn_started` in.
-    ///
-    /// The sentinel is a negative `started`, and every caller that read the field had to know
-    /// that; asking here instead keeps the encoding inside the component that chose it.
+    /// The instant this fade-out armed, or `None` while `started` is still the negative sentinel.
     pub fn armed(&self) -> Option<f32> {
         (self.started >= 0.0).then_some(self.started)
     }
 }
 
-/// Drive the despawn fade-out. On first sight, arm a `{from: 1, to: 0}` [`RenderFade`] on **every
-/// fadeable descendant** (reusing the appear machinery — same cubic curve, material swap, classifier
-/// yield) and stamp the start; once [`APPEAR_FADE_SECS`] elapses, despawn the entity (children cascade).
-/// An entity with no fadeable geometry (cube / model-less) pops straight out — nothing to fade.
-///
-/// Descendants, not direct children: body submeshes hang directly under the unit root, but a held
-/// weapon / helm / shoulder is a child of a **joint** entity several levels down
-/// ([`crate::entities::BoneAttach`]) — the fade is a per-*unit* property (decision 0032's shape), so
-/// the whole tree fades as one instead of the body thinning around a still-opaque weapon.
-///
-/// **And the tree is not the whole model.** A BILLBOARD batch is a world ROOT that merely *follows*
-/// an anchor inside the tree (decision 0153), so the walk cannot reach it — the cards are picked up
-/// by testing their follow-anchor against the walked set, the same idiom
-/// [`crate::player::apply_self_model_fade`] uses (decision 0836).
+/// Arm a teardown [`RenderFade`] on every fadeable part in the tree (held items hang under joints,
+/// [`crate::entities::BoneAttach`]) and on the billboard cards following it, then despawn after
+/// [`APPEAR_FADE_SECS`]; with nothing fadeable, despawn at once.
 pub(crate) fn apply_despawn_fade(
     time: Res<Time>,
     mut commands: Commands,
     mut q: Query<(Entity, &mut DespawnFade)>,
     children_of: Query<&Children>,
-    // The tag, not a bare `With` marker: the ramp starts from the alpha the part is SHOWING (the
-    // scheduler's `startAlpha` argument — [`arm_fade_out`]), and the tag is where that lives.
-    // `Option`, because a part that never had one is the shader's untagged-⇒-opaque sentinel, not
-    // a part that cannot fade — tying fadeability to the tag's presence would pop it instead.
+    // The tag holds the alpha the teardown starts from. `Option`: an untagged part is opaque, not
+    // unfadeable.
     fm: Query<Option<&MeshTag>, With<FadeMaterials>>,
     cards: Query<(Entity, &crate::billboard::BillboardCard, Option<&MeshTag>), With<FadeMaterials>>,
 ) {
@@ -1117,17 +777,8 @@ pub(crate) fn apply_despawn_fade(
     }
 }
 
-/// Arm one fadeable entity's teardown ramp, **from the alpha it is actually showing**. The
-/// scheduler is handed `obj+0xf4`, the object's live transition alpha (wow-re, decision 2203), so a
-/// model torn down mid-appear-fade ramps down from where it stood — where a hardcoded `1.0` would
-/// snap it opaque first and then fade, a visible pop in the one case the fade exists to avoid.
-/// Ours lives in the part's `MeshTag`, which is the same channel the ramp is about to write.
-///
-/// No material is chosen here: [`apply_render_fade`] resolves it per frame from the part's live law
-/// (0755), so a bake-classified part fades out probe-lit — and keeps doing so if it re-classifies
-/// mid-ramp, which a pair latched at this instant could not express. `try_*`: a child (a held item
-/// mid-re-resolve, a gear swap) can be despawned by its own owner in the same frame — the
-/// lifetime contract in [`arm_appear_fade`].
+/// Arm one part's teardown from the alpha it shows, as the scheduler takes the live `obj+0xf4`: a
+/// model torn down mid-appear ramps down from where it stood.
 fn arm_fade_out(entity: Entity, now: f32, start_alpha: f32, commands: &mut Commands) {
     commands
         .entity(entity)
@@ -1141,18 +792,13 @@ fn arm_fade_out(entity: Entity, now: f32, start_alpha: f32, commands: &mut Comma
         .try_remove::<PendingAppearFade>();
 }
 
-/// The alpha a part is showing, as the teardown ramp's `startAlpha`. No tag at all is the shader's
-/// untagged-⇒-opaque sentinel ([`crate::mesh_tag::alpha_of`] reads a zero payload as `1.0`), which
-/// is the same answer for the same reason.
+/// The alpha a part shows, the teardown's `startAlpha`; no tag is opaque, as in the shader.
 fn start_alpha(tag: Option<&MeshTag>) -> f32 {
     tag.map_or(1.0, |t| crate::mesh_tag::alpha_of(t.0))
 }
 
-/// Depth-first helper for [`apply_despawn_fade`]: arm the fade-out on `entity` if it carries
-/// [`FadeMaterials`], and recurse into its children either way (a joint / held-item root carries none
-/// itself but has fadeable meshes beneath it). Every entity visited — parts, joints, attach roots,
-/// billboard anchors alike — is recorded in `walked`, which the caller uses to recognise the
-/// world-root billboard cards that follow this model.
+/// Arm every [`FadeMaterials`] part at or under `entity`, recording each visited entity in
+/// `walked` for the caller's billboard-card match.
 fn arm_despawn_descendants(
     entity: Entity,
     now: f32,
@@ -1163,9 +809,8 @@ fn arm_despawn_descendants(
     walked: &mut bevy::ecs::entity::EntityHashSet,
 ) {
     walked.insert(entity);
-    // The scheduler's own skip gate (`0x672e21`): a part already showing nothing is not worth a
-    // ramp, and an object whose every part is under it has no fade at all — `any` stays false and
-    // the caller pops it, which is the reference unlinking at `0x671ac0`.
+    // The scheduler's skip gate (`0x672e21`): a part below it gets no ramp, and an object with no
+    // part above it is unlinked at once (`0x671ac0`).
     if let Ok(tag) = fm.get(entity) {
         let start = start_alpha(tag);
         if start >= TEARDOWN_MIN_ALPHA {
@@ -1180,44 +825,28 @@ fn arm_despawn_descendants(
     }
 }
 
-/// The model-fade lane's own registrations (decision 1163, stage zero).
-///
-/// These five systems were registered by `EntitiesPlugin` — a *gameplay* plugin — for no reason
-/// beyond history: the fade lane grew inside the entity streamer and never claimed a plugin of its
-/// own. Nothing here is about streamed entities; it is the M2 render-alpha channel, which the
-/// terrain streamer's doodads and a world with no game in it need exactly as much. Owning the
-/// registrations is what lets the world viewer boot the lane without booting the entity streamer.
+/// The M2 render-alpha systems, registered apart from the entity streamer so a world with no game
+/// in it (the world viewer) runs them too.
 pub fn plugin(app: &mut App) {
-    // Arm a queued appear-fade once the world is on-screen, then drive it each frame; the despawn
-    // fade-out re-arms the same `RenderFade` channel on stream-out. All disjoint from the interior
-    // classifier + the doodad fade (they touch different entities / the same channel only while a
-    // fade is pending or live).
+    // No ordering against the interior classifier or the doodad fade: a live fade owns the channel.
     app.add_systems(
         Update,
         (
             arm_appear_fade,
             apply_despawn_fade,
             apply_render_fade,
-            // Retires the unit-root clock (`UnitAppearFade`) once its mirrored ramp completes, so
-            // a part spawning after the unit has fully appeared reads no marker and spawns steady
-            // (`entities::attach`/`entities::equipment` join off it).
             retire_unit_appear_fade,
         )
             .chain(),
     )
-    // Publish those same ramps as ONE number per model instance, for the consumers that are not
-    // meshes and so cannot read a `MeshTag`: an emitter's particles and a ribbon's strip (decision
-    // 0827 — the reference's `CM2Model+0x19c`). PostUpdate, so every Update-side fade writer and
-    // the camera controller's self feather have already run this frame, and before the effect sims
-    // that read it.
+    // After every `Update` fade writer and the self feather, before the effect sims that read it.
     .add_systems(
         PostUpdate,
         publish_model_alpha.before(crate::billboard::BillboardPlace),
     );
 }
 
-/// The composition walk, over a tree the engine never publishes an alpha for — a booth bake, whose
-/// value is final at build time.
+/// The composition walk over a tree with no published alpha, such as a booth bake.
 #[cfg(test)]
 mod chain_tests {
     use super::*;
@@ -1228,10 +857,6 @@ mod chain_tests {
         alphas.get(at)
     }
 
-    /// A model the engine composes nothing for reads its **declared** fade — the half that was
-    /// missing when a ghosted character-select body's wisps drew at full strength over it. And a
-    /// child composes onto it, which is the reference's `0x714000` recursion
-    /// (`child+0x19c = parent+0x19c × child+0x180`).
     #[test]
     fn an_uncomposed_tree_reads_its_declared_fade_and_children_compose_onto_it() {
         let mut app = App::new();
@@ -1250,9 +875,7 @@ mod chain_tests {
         );
     }
 
-    /// The PUBLISHED alpha wins where both exist — a streamed unit, whose published value already
-    /// has this frame's appear/despawn/self-feather ramps folded into the declared one. Reading
-    /// both would apply the declared fade twice.
+    /// Reading both would apply the declared fade twice.
     #[test]
     fn a_published_alpha_beats_the_declaration_it_was_computed_from() {
         let mut app = App::new();
@@ -1263,7 +886,6 @@ mod chain_tests {
         assert_eq!(composed(&mut app, unit), 0.2);
     }
 
-    /// The steady-state world still pays nothing: an entity with neither is opaque.
     #[test]
     fn an_entity_with_neither_is_opaque() {
         let mut app = App::new();
@@ -1276,14 +898,7 @@ mod chain_tests {
 mod tests {
     use super::*;
 
-    /// The `0x714000` recursion as a lookup (decision 0833). A weapon's enchant glow is **two**
-    /// links from the body wearing it — glow → item → wearer — and the director's report is what
-    /// happens when a lane has no expression for that at all: the glow's particles blazed at full
-    /// strength over a character that was still at alpha 0, because the site that spawned them
-    /// could name only its immediate host and was asked for the far end of the chain.
-    ///
-    /// The `dimmed` case pins the composition as the reference's **product** (own × parent's), not
-    /// a pick of one — that is what makes a fading item on a fading wearer behave.
+    /// A weapon glow is two links from its wearer: glow, item, wearer.
     #[test]
     fn an_attached_models_alpha_composes_through_the_whole_chain() {
         use bevy::ecs::system::SystemState;
@@ -1311,9 +926,6 @@ mod tests {
         );
     }
 
-    /// The cycle backstop: [`MAX_MODEL_CHAIN`] bounds the walk, so a link that somehow closes on
-    /// itself costs a few lookups instead of hanging the frame. Nothing builds one today — that is
-    /// exactly why the guard is worth a test rather than a comment.
     #[test]
     fn a_looping_chain_terminates() {
         use bevy::ecs::system::SystemState;
@@ -1327,19 +939,16 @@ mod tests {
         assert_eq!(state.get(&world).get(a), 1.0);
     }
 
-    /// The 0200 login crash, reproduced at the seam: [`arm_appear_fade`]'s query sees the entity
-    /// alive, a wire despawn applies first, and only then do the system's own commands land — the
-    /// `try_*` contract makes that a no-op instead of a panic. `SystemState::apply` after the
-    /// manual despawn recreates the exact interleaving of the parallel schedule.
+    /// `SystemState::apply` after a manual despawn recreates a wire destroy landing between the
+    /// system's query and its commands.
     #[test]
-    #[allow(clippy::type_complexity)] // the SystemState tuple IS the system's real signature
+    #[allow(clippy::type_complexity)] // the SystemState tuple is the system's own signature
     fn arm_appear_fade_tolerates_a_same_frame_wire_despawn() {
         use bevy::ecs::system::SystemState;
 
         let mut world = World::new();
         world.init_resource::<Time>();
-        // Default viewer = nothing covering the world = "world shown" — every pending fade arms
-        // this frame.
+        // The default viewer covers nothing, so every pending fade arms this frame.
         world.init_resource::<crate::view::Viewer>();
         let doomed = world.spawn(PendingAppearFade { since: 0.0 }).id();
 
@@ -1357,17 +966,11 @@ mod tests {
         let (time, viewer, commands, q, units) = state.get_mut(&mut world);
         arm_appear_fade(time, viewer, commands, q, units);
 
-        // The wire destroy beats the fade commands to the sync point.
         world.despawn(doomed);
         state.apply(&mut world); // would panic without the `try_*` contract
         assert!(world.get_entity(doomed).is_err(), "stays despawned");
     }
 
-    /// Decision 0755: one law-aware material rule, shared by every fade writer. A bake-classified
-    /// part feathers probe-lit and settles probe-lit; everything else rides the exterior pair. The
-    /// pair is resolved per frame from the part's LIVE law, so a part that classifies during its
-    /// ramp is lit by its room for the rest of it instead of finishing on the law that happened to
-    /// hold when the fade armed.
     #[test]
     fn the_material_rule_follows_the_law_not_the_arm_instant() {
         use crate::interior::{InteriorKind, InteriorLit};
@@ -1387,11 +990,11 @@ mod tests {
             zfill: None,
         };
 
-        // Unclassified (no `InteriorLit` at all — a WMO-display part): the exterior pair.
+        // Unclassified (a WMO-display part): the exterior pair.
         assert_eq!(*fm.material_for(None, true), blend);
         assert_eq!(*fm.material_for(None, false), cutout);
 
-        // Bake-CAPABLE but not yet resolved indoors (the state a part spawns in): exterior pair.
+        // Bake-capable but not yet resolved indoors, as a part spawns: the exterior pair.
         let kind = InteriorKind::Bake {
             material: bake.clone(),
             center: Vec3::ZERO,
@@ -1400,14 +1003,12 @@ mod tests {
         assert_eq!(*fm.material_for(Some(&unresolved), true), blend);
         assert_eq!(*fm.material_for(Some(&unresolved), false), cutout);
 
-        // The law flips to the room's bake MID-RAMP: the very next frame feathers probe-lit, and
-        // the latch settles on the bake variant — no law change, and so no pop, at the latch.
+        // The law flips to the room's bake mid-ramp: feathered and settled on the bake variant.
         let lit = InteriorLit::applied_bake_for_test(kind, cutout.clone());
         assert_eq!(*fm.material_for(Some(&lit), true), bake_blend);
         assert_eq!(*fm.material_for(Some(&lit), false), bake);
 
-        // A part with no bake blend twin authored falls back to the exterior blend rather than
-        // dropping the feather.
+        // No bake blend twin: the exterior blend, rather than no feather.
         let no_twin = FadeMaterials {
             bake_blend: None,
             zfill: None,
@@ -1418,17 +1019,12 @@ mod tests {
 
     #[test]
     fn trees_and_buildings_never_fade() {
-        // radius > 7.0 → always 1.0 regardless of distance.
         assert_eq!(doodad_fade_alpha(7.01, 0.0), 1.0);
         assert_eq!(doodad_fade_alpha(20.0, 500.0), 1.0);
         assert_eq!(doodad_fade_alpha(7.0001, 195.0), 1.0);
     }
 
-    /// The property the gx exile scan (B2, 1431) rests on: outside the band edges — with the
-    /// scan's own 1-yd hysteresis of margin — the alpha is EXACTLY the constant the retained
-    /// pass assumes (1.0 steady / 0.0 gone), and strictly between them inside. A band table
-    /// duplicated into the scan is the drift this test forbids: `fade_band` derives from the
-    /// same `BUCKETS` row `doodad_fade_alpha` evaluates.
+    /// A yard past each edge (the retained pass's hysteresis) the alpha is exactly 1 or 0.
     #[test]
     fn fade_band_edges_agree_with_the_alpha_they_summarize() {
         for radius in [0.0, 0.3, 0.5, 1.7, 2.5, 4.0, 7.0] {
@@ -1443,18 +1039,18 @@ mod tests {
 
     #[test]
     fn small_props_fade_40_to_50() {
-        // radius ≤ 0.5: band on d = dist − radius. Use radius 0.0 so d == dist for clean goldens.
+        // Radius 0, so `d` is the centre distance.
         let r = 0.0;
-        assert_eq!(doodad_fade_alpha(r, 39.0), 1.0); // before the band → opaque
-        assert_eq!(doodad_fade_alpha(r, 40.0), 1.0); // band start → opaque
-        assert!((doodad_fade_alpha(r, 45.0) - 0.5).abs() < 1e-6); // midpoint → half
-        assert_eq!(doodad_fade_alpha(r, 50.0), 0.0); // band end → gone
-        assert_eq!(doodad_fade_alpha(r, 60.0), 0.0); // past the band → gone
+        assert_eq!(doodad_fade_alpha(r, 39.0), 1.0);
+        assert_eq!(doodad_fade_alpha(r, 40.0), 1.0);
+        assert!((doodad_fade_alpha(r, 45.0) - 0.5).abs() < 1e-6);
+        assert_eq!(doodad_fade_alpha(r, 50.0), 0.0);
+        assert_eq!(doodad_fade_alpha(r, 60.0), 0.0);
     }
 
     #[test]
     fn radius_offsets_the_band() {
-        // d = dist − radius, so a 0.5-yd prop reaches band start (d=40) at center distance 40.5.
+        // A 0.5-yd prop reaches the band start (`d` = 40) at centre distance 40.5.
         assert_eq!(doodad_fade_alpha(0.5, 40.5), 1.0);
         assert!((doodad_fade_alpha(0.5, 45.5) - 0.5).abs() < 1e-6);
         assert_eq!(doodad_fade_alpha(0.5, 50.5), 0.0);
@@ -1462,7 +1058,6 @@ mod tests {
 
     #[test]
     fn mid_bucket_100_to_125() {
-        // 0.5 < radius ≤ 2.5 → band 100→125 (range 25). radius 2.5 → d = dist − 2.5.
         let r = 2.5;
         assert_eq!(doodad_fade_alpha(r, 100.0 + r), 1.0);
         assert!((doodad_fade_alpha(r, 112.5 + r) - 0.5).abs() < 1e-6);
@@ -1471,7 +1066,6 @@ mod tests {
 
     #[test]
     fn large_bucket_150_to_200() {
-        // 2.5 < radius ≤ 7.0 → band 150→200 (range 50). radius 5.0 → d = dist − 5.0.
         let r = 5.0;
         assert_eq!(doodad_fade_alpha(r, 150.0 + r), 1.0);
         assert!((doodad_fade_alpha(r, 175.0 + r) - 0.5).abs() < 1e-6);
@@ -1480,9 +1074,7 @@ mod tests {
 
     #[test]
     fn monotonic_bigger_fades_farther() {
-        // At a fixed far distance a larger prop should be more visible than a smaller one (bigger =
-        // fades at a greater distance). Compare a small prop (≤0.5, band ~40-50) vs a large one
-        // (≤7, band ~150-200) at 120 yd: small is long gone, large is still fully opaque.
+        // At 120 yd the small band (40 to 50) is long past and the large (150 to 200) not reached.
         let small = doodad_fade_alpha(0.3, 120.0);
         let large = doodad_fade_alpha(6.0, 120.0);
         assert_eq!(small, 0.0);
@@ -1492,16 +1084,16 @@ mod tests {
 
     #[test]
     fn appear_fade_is_cubic_0_to_1() {
-        assert_eq!(fade_alpha(0.0, 1.0, 0.0), 0.0); // spawn: invisible
-        assert!((fade_alpha(0.0, 1.0, 0.5) - 0.125).abs() < 1e-6); // t³: half-time ⇒ 1/8 (accelerating)
-        assert_eq!(fade_alpha(0.0, 1.0, 1.0), 1.0); // latches opaque
-        assert_eq!(fade_alpha(0.0, 1.0, -1.0), 0.0); // clamps below
-        assert_eq!(fade_alpha(0.0, 1.0, 2.0), 1.0); // clamps above
+        assert_eq!(fade_alpha(0.0, 1.0, 0.0), 0.0);
+        assert!((fade_alpha(0.0, 1.0, 0.5) - 0.125).abs() < 1e-6); // t³
+        assert_eq!(fade_alpha(0.0, 1.0, 1.0), 1.0);
+        assert_eq!(fade_alpha(0.0, 1.0, -1.0), 0.0);
+        assert_eq!(fade_alpha(0.0, 1.0, 2.0), 1.0);
     }
 
     #[test]
     fn despawn_fade_eases_to_0() {
-        // The same curve targeting 0 (the coming despawn fade-out): 1 + (0−1)·t³.
+        // The cubic run downward, `1 − t³`; the despawn itself runs `teardown_fade_alpha`.
         assert_eq!(fade_alpha(1.0, 0.0, 0.0), 1.0);
         assert!((fade_alpha(1.0, 0.0, 0.5) - 0.875).abs() < 1e-6);
         assert_eq!(fade_alpha(1.0, 0.0, 1.0), 0.0);
@@ -1509,19 +1101,17 @@ mod tests {
 
     #[test]
     fn self_fade_hidden_at_first_person() {
-        // Camera on top of the target (zoomed fully in): D ≤ SELF_FADE_HIDE ⇒ hard-hide.
         let nc = 1.0;
-        assert_eq!(self_model_fade_alpha(nc, nc, SELF_FADE_WINDOW), 0.0); // dist == nearclip → D = 0
-        assert_eq!(self_model_fade_alpha(0.0, nc, SELF_FADE_WINDOW), 0.0); // inside the near clip
+        assert_eq!(self_model_fade_alpha(nc, nc, SELF_FADE_WINDOW), 0.0);
+        assert_eq!(self_model_fade_alpha(0.0, nc, SELF_FADE_WINDOW), 0.0);
         assert_eq!(
             self_model_fade_alpha(nc + SELF_FADE_HIDE, nc, SELF_FADE_WINDOW),
             0.0
-        ); // exactly at the hide threshold
+        );
     }
 
     #[test]
     fn self_fade_opaque_when_zoomed_out() {
-        // Camera a full window (or more) beyond the near clip ⇒ fully opaque.
         let nc = 1.0;
         assert_eq!(
             self_model_fade_alpha(nc + SELF_FADE_WINDOW, nc, SELF_FADE_WINDOW),
@@ -1532,15 +1122,11 @@ mod tests {
 
     #[test]
     fn no_unit_marker_joins_steady() {
-        // A part attached to a unit with no in-flight appear-fade (already settled, or a WMO-display
-        // entity that never fades at all) spawns steady — matches today's long-after-login behavior.
         assert_eq!(join_unit_appear_fade(None), JoinedFade::Steady);
     }
 
     #[test]
     fn pending_unit_joins_at_the_same_since() {
-        // A part spawning while the unit is still behind the loading screen joins the same "arm once
-        // shown" timer — not its own, so both go live on the same frame.
         let since = 3.25;
         assert_eq!(
             join_unit_appear_fade(Some(UnitAppearFade::Pending { since })),
@@ -1559,11 +1145,7 @@ mod tests {
 
     #[test]
     fn joining_mid_ramp_reproduces_the_original_curve() {
-        // The whole point of copying `started` instead of resetting to zero or sampling a stored
-        // alpha: a part that joins 0.7s into the body's ramp must read the *same* alpha as the body
-        // does at every subsequent instant, because both derive it from one shared `started` through
-        // the same pure `fade_alpha` — no synchronization between the two entities is needed.
-        let started = 1.4; // the body's ramp began at t = 1.4s (arbitrary wall-clock origin)
+        let started = 1.4;
         let joined = join_unit_appear_fade(Some(UnitAppearFade::Live { started }));
         assert_eq!(joined, JoinedFade::Live { started });
         for now in [1.4f32, 1.7, 2.0, 2.9, 3.4] {
@@ -1579,11 +1161,6 @@ mod tests {
         }
     }
 
-    /// **The login symptom, at its cause** (decision 0827): a unit whose appear-fade has not been
-    /// armed yet is not being shown at all, so its render alpha is **0** — and the item sparkle
-    /// that reads this number is therefore invisible too, instead of burning at full strength in
-    /// front of a body that hasn't faded in. Then the ramp: the same cubic the mesh parts run, so
-    /// the pauldron's glow and the pauldron arrive together rather than 2 s apart.
     #[test]
     fn a_units_render_alpha_is_zero_until_it_is_shown_then_rides_the_same_cubic() {
         assert_eq!(
@@ -1619,18 +1196,14 @@ mod tests {
         );
     }
 
-    /// The other two writers of the same slot compose as a PRODUCT — the reference multiplies the
-    /// transition alpha into `+0x180` rather than keeping a second channel. The self-avatar feather
-    /// is what takes a held torch's flame out of your face in first person (ledger F05).
     #[test]
     fn the_render_alpha_multiplies_its_writers() {
-        // Zooming to first person: the body is opaque-by-appear but the feather is 0.
+        // First person: opaque by the appear ramp, but the feather is 0.
         assert_eq!(model_render_alpha(20.0, None, None, 0.0, 1.0), 0.0);
         assert!((model_render_alpha(20.0, None, None, 0.5, 1.0) - 0.5).abs() < 1e-6);
-        // Streaming out: the despawn ramp eases the same channel to nothing.
+        // Streaming out: the teardown takes the same channel to 0.
         assert_eq!(model_render_alpha(10.0, None, Some(10.0), 1.0, 1.0), 1.0);
         assert_eq!(model_render_alpha(12.0, None, Some(10.0), 1.0, 1.0), 0.0);
-        // Both at once stay a product, and the result can never leave [0, 1].
         let both = model_render_alpha(
             11.0,
             Some(UnitAppearFade::Live { started: 10.0 }),
@@ -1641,24 +1214,17 @@ mod tests {
         assert!((0.0..=1.0).contains(&both) && both > 0.0);
     }
 
-    /// **The stealth-particle symptom, at its cause**: the aura CharProc alpha (stealth 0.3,
-    /// invisibility 0.5) is a factor of the SAME render-alpha slot in the reference (`0x60d180`'s
-    /// recompute drives the same `StartAlphaFade` the appear-fade uses), which is what carries a
-    /// stealthed rogue's weapon-enchant glow and kit particles down with the body. Before this
-    /// factor existed, `ModelAlpha` stayed 1.0 under stealth and every emitter burned at full
-    /// brightness beside a 30 %-alpha body.
+    /// Stealth's aura alpha, 0.3.
     #[test]
     fn the_aura_alpha_is_a_factor_of_the_effect_render_alpha() {
         assert!((model_render_alpha(20.0, None, None, 1.0, 0.3) - 0.3).abs() < 1e-6);
-        // …and it composes with the other writers as a product, never a replacement.
         assert!((model_render_alpha(20.0, None, None, 0.5, 0.3) - 0.15).abs() < 1e-6);
         assert_eq!(model_render_alpha(20.0, None, Some(20.0), 1.0, 0.3), 0.3);
     }
 
     #[test]
     fn unit_fade_retires_after_the_appear_duration() {
-        // The join marker itself doesn't retire (that's `retire_unit_appear_fade`, an ECS system), but
-        // its retirement condition is a pure time check — pin it here so the threshold can't drift.
+        // `retire_unit_appear_fade`'s condition, a pure time check.
         let started = 5.0;
         let almost_done = started + APPEAR_FADE_SECS - 0.001;
         let done = started + APPEAR_FADE_SECS;
@@ -1668,25 +1234,17 @@ mod tests {
 
     #[test]
     fn self_fade_cosine_ramp_midpoint() {
-        // Half-way through the window the cosine smoothstep passes through 0.5 (cos(π/2) = 0).
+        // Mid-window the cosine smoothstep is 0.5 (cos(π/2) = 0).
         let nc = 1.0;
         let mid = nc + SELF_FADE_WINDOW / 2.0;
         assert!((self_model_fade_alpha(mid, nc, SELF_FADE_WINDOW) - 0.5).abs() < 1e-6);
-        // Monotonic: closer ⇒ more transparent than farther, across the ramp.
         let near = self_model_fade_alpha(nc + 0.4, nc, SELF_FADE_WINDOW);
         let far = self_model_fade_alpha(nc + 1.4, nc, SELF_FADE_WINDOW);
         assert!(near < far);
         assert!((0.0..=1.0).contains(&near) && (0.0..=1.0).contains(&far));
     }
 
-    /// **The stream-out half of decision 0836.** The arm walk descends `Children`, and a billboard
-    /// card is a world ROOT that only *follows* an anchor inside the tree — so a unit fading out
-    /// left its eye glow / gem cards at full strength for the whole 2 s and then blinked them out
-    /// with the despawn. They're picked up by their follow-anchor, exactly as the self-avatar
-    /// feather picks them up.
-    ///
-    /// The second card, following nothing of this unit's, is the negative half: the sweep is by
-    /// membership, not "every card on screen".
+    /// A billboard card is a world root matched by its follow-anchor; a stranger's is left alone.
     #[test]
     fn a_despawn_fade_reaches_the_models_billboard_cards() {
         let fm = || FadeMaterials {
@@ -1698,8 +1256,7 @@ mod tests {
         let mut app = App::new();
         app.add_plugins(MinimalPlugins);
         let unit = app.world_mut().spawn((Transform::default(), fm())).id();
-        // A joint under the unit, an attach root under it, and the card following that root —
-        // the real held-item shape, three levels deep.
+        // The held-item shape: a joint, an attach root under it, a card following that root.
         let joint = app.world_mut().spawn(Transform::default()).id();
         let root = app.world_mut().spawn(Transform::default()).id();
         app.world_mut().entity_mut(unit).add_child(joint);
@@ -1753,13 +1310,6 @@ mod inversion_tests {
     use super::*;
     use bevy::ecs::system::RunSystemOnce;
 
-    /// The two rewired inputs of [`publish_model_alpha`], end to end.
-    ///
-    /// Neither lane has a capture behind it — the golden six are scenery and carry no auras, and
-    /// nothing screenshots a first-person zoom — so this is the only thing standing between a
-    /// mis-wired multiplier and a director noticing that stealth stopped working. Both used to be
-    /// direct reads of gameplay types (`aura_visual::AuraNodes`, `player::CameraControl`); they are
-    /// now a component the game declares and a field on `view::Viewer`.
     #[test]
     fn a_declared_fade_and_the_self_feather_both_reach_the_composed_alpha() {
         let mut app = App::new();
diff --git a/crates/benilla-world/src/model_forms.rs b/crates/benilla-world/src/model_forms.rs
index d33ac40b..06c25c3e 100644
--- a/crates/benilla-world/src/model_forms.rs
+++ b/crates/benilla-world/src/model_forms.rs
@@ -1,21 +1,8 @@
-//! Paced model render-form building — the model-lane twin of the tile furnisher (decision 0834,
-//! closing 0832's named residual).
-//!
-//! The M2/WMO loaders ship **geometry, no meshes** (`ModelSubmesh::geometry`): a loader-built
-//! labeled sub-asset lands the instant its decode completes, and the render world ingests the
-//! whole model — a city root's thousands of group batches, a fresh row's hundreds of doodads —
-//! in ONE frame. Measured at the Stormwind line (pre-0834): 2000–3200 mesh assets per crossing,
-//! 44–119 ms wall on the worst frame, on every crossing including re-entries. No budget
-//! downstream of a load can spread work the loader has already packaged, so the build lives
-//! here: consumers `require()` the forms they need, and [`furnish_model_forms`] builds a bounded
-//! amount per frame while live — nearest requester first — uncapped behind the loading cover.
-//!
-//! One [`Entry`] per loaded model asset holds the built handles; every instance of the model
-//! shares them (the build runs once per asset, not per placement). The **static** form is
-//! `RENDER_WORLD`-only with its `Aabb` computed at build time (the exterior cull fails open on a
-//! missing bound — 0832's rule); the **skinned** twin keeps main-world data because the mouseover
-//! picker CPU-skins its vertices (`target::hover`), and it is built only for lanes that rig —
-//! which retires the loader's old always-built, mostly-unused twin (the 0019 deferral).
+//! Paced model render-form building. The M2 and WMO loaders ship geometry, not meshes: a loader's
+//! meshes would reach the render world a whole model in one frame. Consumers `require()` the
+//! forms they need, and [`furnish_model_forms`] builds a bounded amount per frame while live,
+//! nearest requester first, uncapped behind the loading cover. One [`Entry`] per model asset
+//! serves every instance.
 
 use std::collections::HashMap;
 use std::time::Instant;
@@ -32,20 +19,14 @@ pub(crate) const WANT_STATIC: u8 = 1;
 /// Request bit: the skinned twin (rigged lanes only).
 pub(crate) const WANT_SKINNED: u8 = 2;
 
-/// Per-frame build budget while live, in submeshes. The companion vertex budget below is the
-/// real governor for big WMO group batches; this cap bounds the per-mesh fixed cost (asset add +
-/// extract + prepare) the Stormwind leg measured dominating at ~3000 small doodad meshes per
-/// crossing. At 96/frame a whole city crossing's ~3000 meshes land in ~0.5 s of frames — inside
-/// the two-tile fog margin the 5×5 window gives a first contact.
+/// Per-frame build budget while live, in submeshes: it bounds the per-mesh fixed cost, so a city
+/// crossing's ~3000 small meshes land in about 0.5 s, inside the 5×5 window's two-tile fog margin.
 const MESH_BUDGET: usize = 96;
-/// Per-frame build budget while live, in vertices — the governor for the handful of huge group
-/// batches (tens of thousands of vertices each). A single submesh may exceed it alone; it then
-/// lands alone in its frame (a submesh is the atomic unit — at least one always builds, so
-/// progress is guaranteed).
+/// Per-frame build budget while live, in vertices, for the huge WMO group batches; a submesh over
+/// it builds alone in its frame.
 const VERT_BUDGET: usize = 16_384;
 
-/// A loaded model asset the forms cache keys by — the two model kinds share one cache because
-/// every consumer lane (placements, entities, markers, booths) handles both.
+/// A loaded model asset, M2 or WMO, as the forms cache keys it.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum ModelKey {
     M2(AssetId<M2Model>),
@@ -63,37 +44,31 @@ impl From<&Handle<WmoModel>> for ModelKey {
     }
 }
 
-/// One model's built render forms + its build cursors (`stat.len()` / `skin.len()` — resumed
-/// across frames, like a tile's cell cursor).
+/// One model's built forms; `stat.len()` and `skin.len()` are the build cursors across frames.
 #[derive(Default)]
 struct Entry {
-    /// The static form per submesh, with the `Aabb` computed at build (`None` = degenerate
-    /// geometry): consumers insert it explicitly — `RENDER_WORLD` meshes race Bevy's
-    /// `calculate_bounds`, and the exterior cull fails open on a missing bound.
+    /// The static form per submesh with its build-time `Aabb` (`None`: degenerate), which
+    /// consumers insert themselves: `calculate_bounds` races a `RENDER_WORLD` mesh, and the
+    /// exterior cull fails open without a bound.
     stat: Vec<(Handle<Mesh>, Option<Aabb>)>,
-    /// The skinned twin per submesh (rigged lanes only; main-world data kept for the picker).
+    /// The skinned twin per submesh, for rigged lanes only; it keeps main-world data because the
+    /// mouseover picker skins it on the CPU (`target::hover`).
     skin: Vec<Handle<Mesh>>,
-    /// Kinds ever requested (`WANT_*` bits). Sticky: demand for a form doesn't vanish because
-    /// one requester despawned mid-build — the entry frees with the asset.
+    /// Kinds ever requested (`WANT_*` bits), sticky until the asset frees.
     want: u8,
     /// Kinds fully built.
     done: u8,
-    /// This frame's most urgent requester (lower = sooner), reset after each furnish pass so a
-    /// vanished requester stops hoisting its model.
+    /// This frame's most urgent requester (lower is sooner), reset after each furnish pass.
     priority: i32,
 }
 
-/// The per-asset render-form cache. Entries are created by [`Self::require`], built by
-/// [`furnish_model_forms`], and dropped when the model asset itself leaves the store (the mesh
-/// handles drop with them; instances that already spawned keep theirs via `Mesh3d`).
+/// The per-asset render-form cache; an entry drops when its model asset leaves the store.
 #[derive(Resource, Default)]
 pub struct ModelForms {
     entries: HashMap<ModelKey, Entry>,
 }
 
-/// A borrowed view of one model's built forms for the assembler, index-parallel with the model's
-/// submeshes: the static handle + build-time `Aabb` per batch, plus the skinned twins when the
-/// lane rigs.
+/// One model's built forms for the assembler, index-parallel with its submeshes.
 #[derive(Clone, Copy)]
 pub struct FormSlices<'a> {
     pub stat: &'a [(Handle<Mesh>, Option<Aabb>)],
@@ -101,10 +76,8 @@ pub struct FormSlices<'a> {
 }
 
 impl ModelForms {
-    /// Record that a consumer needs `kinds` of this model's forms, at `priority` (lower =
-    /// sooner; pass the requester's tile/chunk distance). Returns `true` when every requested
-    /// kind is already built — the consumer's gate, polled the same way it polls the model
-    /// asset itself.
+    /// Record that a consumer needs `kinds` at `priority` (the requester's tile distance, lower is
+    /// sooner); `true` once every requested kind is built.
     pub(crate) fn require(&mut self, key: ModelKey, kinds: u8, priority: i32) -> bool {
         let e = self.entries.entry(key).or_default();
         e.want |= kinds;
@@ -112,8 +85,7 @@ impl ModelForms {
         e.done & kinds == kinds
     }
 
-    /// The built static forms (handle + build-time `Aabb` per submesh), or `None` until
-    /// [`Self::require`]`(…, WANT_STATIC, …)` has returned `true`.
+    /// The built static forms, or `None` until built.
     pub(crate) fn static_meshes(&self, key: ModelKey) -> Option<&[(Handle<Mesh>, Option<Aabb>)]> {
         let e = self.entries.get(&key)?;
         (e.done & WANT_STATIC != 0).then_some(e.stat.as_slice())
@@ -125,23 +97,17 @@ impl ModelForms {
         (e.done & WANT_SKINNED != 0).then_some(e.skin.as_slice())
     }
 
-    /// Request **both** forms of a model and report whether they are built — the gate every lane
-    /// whose instances can rig polls each frame (creatures, players, held items, spell effects,
-    /// animated GameObjects, the booths). Takes the model handle rather than a key: the key is
-    /// the cache's business, not the caller's.
+    /// Request both forms, `true` once built: the gate every lane whose instances can rig polls.
     pub fn require_rigged(&mut self, model: impl Into<ModelKey>, priority: i32) -> bool {
         self.require(model.into(), WANT_STATIC | WANT_SKINNED, priority)
     }
 
-    /// Request the **static** form only — the lanes whose instances never skin: WMO displays,
-    /// billboard cards, the particle-model quad source.
+    /// Request the static form only, for lanes whose instances never skin.
     pub fn require_static(&mut self, model: impl Into<ModelKey>, priority: i32) -> bool {
         self.require(model.into(), WANT_STATIC, priority)
     }
 
-    /// One model's built forms, index-parallel with its submeshes. Empty slices until the
-    /// matching `require_*` has returned `true` — a caller that spawns anyway gets default (dead)
-    /// handles rather than a panic, which is the same contract the assembler already documents.
+    /// One model's built forms, empty until the matching `require_*` returns `true`.
     pub fn slices(&self, model: impl Into<ModelKey>) -> FormSlices<'_> {
         let key = model.into();
         FormSlices {
@@ -150,7 +116,7 @@ impl ModelForms {
         }
     }
 
-    /// [`Self::ensure_now`] for **both** forms — the booth/glue/marker lanes' rigged models.
+    /// [`Self::ensure_now`] for both forms.
     pub fn ensure_now_rigged(
         &mut self,
         model: impl Into<ModelKey>,
@@ -160,7 +126,7 @@ impl ModelForms {
         self.ensure_now(model.into(), WANT_STATIC | WANT_SKINNED, submeshes, meshes);
     }
 
-    /// [`Self::ensure_now`] for the **static** form only.
+    /// [`Self::ensure_now`] for the static form only.
     pub(crate) fn ensure_now_static(
         &mut self,
         model: impl Into<ModelKey>,
@@ -170,9 +136,8 @@ impl ModelForms {
         self.ensure_now(model.into(), WANT_STATIC, submeshes, meshes);
     }
 
-    /// Build every requested-and-missing form of one model NOW, uncapped — the booth/glue/marker
-    /// lanes: one small model at a time, usually behind a screen whose job is to absorb exactly
-    /// this. The streaming lanes must go through [`Self::require`] + the paced furnisher instead.
+    /// Build a model's missing forms now, uncapped, for one-off lanes (booths, glue, markers);
+    /// streaming lanes go through [`Self::require`] and the paced furnisher.
     pub(crate) fn ensure_now(
         &mut self,
         key: ModelKey,
@@ -190,16 +155,13 @@ impl ModelForms {
         self.entries.remove(&key);
     }
 
-    /// Drop everything — leaving the world (`release_world`), where the per-asset `Unused`
-    /// events can no longer reach the world-live-gated furnisher.
+    /// Drop everything on leaving the world, where the gated furnisher no longer reads `Unused`.
     pub(crate) fn clear(&mut self) {
         self.entries.clear();
     }
 }
 
-/// Advance one entry's requested builds, bounded by `budget` submeshes and [`VERT_BUDGET`]
-/// vertices (via `verts`, shared across entries within a frame). Returns how many submeshes were
-/// built. Marks a kind done when its cursor has walked every submesh.
+/// Advance one entry's builds within `budget` submeshes and [`VERT_BUDGET`]; returns the count.
 fn build_entry(
     e: &mut Entry,
     kinds: u8,
@@ -238,10 +200,8 @@ fn build_entry(
     built
 }
 
-/// Build requested model forms, [`MESH_BUDGET`]/[`VERT_BUDGET`] per frame while live — most
-/// urgent requester first — uncapped behind the loading cover (entry/teleport/world-stale), which
-/// exists to absorb exactly that burst. At least one submesh always builds, so progress is
-/// guaranteed. Frees an entry when its model asset leaves the store.
+/// Build requested forms most urgent first, [`MESH_BUDGET`] and [`VERT_BUDGET`] per frame while
+/// live, uncapped behind the loading cover; at least one submesh always builds.
 pub(crate) fn furnish_model_forms(
     mut forms: ResMut<ModelForms>,
     m2s: Res<Assets<M2Model>>,
@@ -253,10 +213,7 @@ pub(crate) fn furnish_model_forms(
     mut wmo_events: MessageReader<AssetEvent<WmoModel>>,
 ) {
     let t0 = Instant::now();
-    // The free path: a model asset leaving the store (or replaced by a reload) drops its forms —
-    // the mesh handles' last cache-side strong refs go with it, so the GPU copies free once the
-    // last spawned instance is gone too. `Unused` fires for untracked (`RENDER_WORLD`-extracted)
-    // and tracked assets alike, exactly once (0832's counter rule).
+    // An asset leaving the store or reloading drops its forms; `Unused` fires once for any asset.
     for ev in m2_events.read() {
         if let AssetEvent::Unused { id }
         | AssetEvent::Removed { id }
@@ -276,7 +233,6 @@ pub(crate) fn furnish_model_forms(
 
     let cap = if focus.paced { MESH_BUDGET } else { usize::MAX };
 
-    // The frame's work list: entries with a requested kind still unbuilt, most urgent first.
     let mut pending: Vec<(i32, ModelKey)> = forms
         .entries
         .iter()
@@ -294,8 +250,7 @@ pub(crate) fn furnish_model_forms(
         if built >= cap || verts >= VERT_BUDGET {
             break;
         }
-        // The asset can lag its request (still decoding) or predecease it (dropped mid-build);
-        // both just skip — the entry builds when the asset lands, or frees on its event above.
+        // An asset still decoding or already dropped skips: it builds on landing or frees above.
         let submeshes: &[ModelSubmesh] = match key {
             ModelKey::M2(id) => match m2s.get(id) {
                 Some(m) => &m.submeshes,
@@ -319,9 +274,7 @@ pub(crate) fn furnish_model_forms(
 
 #[cfg(test)]
 mod tests {
-    /// The cap's arithmetic, kept honest in one place (the furnish.rs test's model twin): the
-    /// Stormwind crossing's measured ~3200 mesh burst must land in well under a second of frames
-    /// at 60 Hz — inside the fog margin a 5×5-window first contact gives.
+    /// The measured Stormwind crossing burst, ~3200 meshes, lands inside the fog margin at 60 Hz.
     #[test]
     fn a_city_crossing_furnishes_in_under_a_second() {
         let crossing_meshes: usize = 3200;
diff --git a/crates/benilla-world/src/model_render.rs b/crates/benilla-world/src/model_render.rs
index 08beb794..7dc4bcfc 100644
--- a/crates/benilla-world/src/model_render.rs
+++ b/crates/benilla-world/src/model_render.rs
@@ -1,7 +1,5 @@
-//! Shared world-model material build — the `WowModelMaterial` (a `StandardMaterial` base carrying the
-//! texture/alpha/cull + the `WowModelExt` shared-light extension that does the WoW shading) used for
-//! every M2/WMO instance: doodads, WMO buildings, creatures, and GameObjects. Deduped per owner by
-//! `(texture, blend, sidedness, kind, fade-variant)` so instances sharing a look batch into one draw.
+//! The `WowModelMaterial` build for every M2 and WMO instance: a `StandardMaterial` base for
+//! texture, alpha and cull plus the `WowModelExt` shading, deduped so a shared look is one draw.
 
 use benilla_formats::{ModelBlend, WmoBatchClass};
 use bevy::asset::AssetId;
@@ -19,56 +17,31 @@ mod visibility;
 
 pub use batch::{BatchVariants, EntityUvLane, M2BatchMaterials, ModelMaterials, SkyboxBatch};
 
-/// Yards of transparent-pass sort bias per authored batch-order step (`MatKey::batch_order` ×
-/// this, on `StandardMaterial::depth_bias` — bevy adds that field to the phase item's sort
-/// distance; positive = drawn later, the `sky_order` sign law). **Why it exists:** one model's
-/// coplanar transparent batches (the Naxx items' Opaque + Mod2x sheen + Blend overlay triples)
-/// share one mesh centre, so their sort distances TIE, and a tie is re-resolved every frame by
-/// whatever order the queue happens to iterate — in a churning scene (a city) the coplanar layers
-/// swap draw order frame to frame and the composite strobes (Mod2x-then-Blend ≠ Blend-then-Mod2x).
-/// The reference cannot express the bug: it ties every draw command of one instance to a single
-/// sort key and keeps the *authored command order* inside the tie (wow-re
-/// `m2-blend-promotion-zfill.md` §4/§6; MOBA file order for WMO). This epsilon reproduces that
-/// order through bevy's sort. Sized well under [`benilla_formats::owner_last_rung`]'s 1-yd floor
-/// (an effect still draws after every batch of its owner) and far over f32 noise on a ~500 yd
-/// sort distance (~4e-5).
-///
-/// It IS a pipeline-key axis when it reaches 1.0: the base `StandardMaterialKey` packs
-/// `depth_bias as i32` (only the extension `WowModelKey` excludes it — 0837's comment
-/// overclaimed), so the product is capped at [`BATCH_ORDER_SORT_CAP`] and applied to
-/// transparent-pass materials only (`model_material`).
+/// Yards of transparent sort bias per authored batch step: a model's coplanar batches tie on one
+/// mesh centre, and the reference keeps their authored order inside the instance's sort key
+/// (`0x707db1`). Under [`benilla_formats::owner_last_rung`]'s 1-yd floor, over f32 noise at 500 yd.
 pub(crate) const BATCH_ORDER_SORT_EPS: f32 = 1e-3;
 
-/// The eps product's ceiling: strictly under 1.0 so no batch index can mint a pipeline key
-/// (`as i32` == 0 for the whole band), and strictly under `FAR_KEY_PULL` so a capped batch's
-/// far-side twin still truncates onto the far band's single key integer. Batches past index
-/// 899 tie here — see the cap rationale at the one application site.
+/// The eps product's ceiling, since `depth_bias as i32` is a pipeline-key axis: under 1.0, and
+/// under `FAR_KEY_PULL` for the far twins. Past index 899 batches tie.
 pub(crate) const BATCH_ORDER_SORT_CAP: f32 = 0.9;
 
-/// `WOW_NO_ALPHATEST=1` — every cutout batch draws opaque (the A/B lever described at the
-/// [`model_material`] use site; the static-gx bake keys its cutout runs on the same read).
+/// `WOW_NO_ALPHATEST=1`: every cutout batch draws opaque, in the static-gx bake too.
 pub(crate) fn alphatest_disabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_NO_ALPHATEST").is_some())
 }
 
-/// `WOW_WMO_BIAS=0` — the WMO batch's clip-z nudge off (a bisect lever; see its use site). Read
-/// once: the use site runs per WMO batch on stream-in, thousands of times through a city's load.
+/// `WOW_WMO_BIAS=0`: the WMO batch clip-z nudge off.
 fn wmo_bias_off() -> bool {
     static OFF: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *OFF.get_or_init(|| matches!(std::env::var("WOW_WMO_BIAS").as_deref(), Ok("0")))
 }
 
-/// Material-dedup key: same texture + blend + sidedness + kind + fade-variant → one shared material.
+/// The material-dedup key: batches that agree on every field share one material.
 #[derive(PartialEq, Eq, Hash)]
 pub struct MatKey {
-    /// **Which light rig this material binds** — the `#[storage(90, …)]` buffer cloned into
-    /// `WowModelExt::light_buf`. A key axis because it is the one material input that is not a
-    /// property of the batch: the world lane binds the shared sun/sky buffer, a portrait booth
-    /// binds its frozen studio buffer, the char-select scene binds its own authored rig. Without
-    /// it two lanes building the same batch collide and the second gets the first's *lighting* —
-    /// which the booths avoided only by each keeping a private cache, a discipline nothing
-    /// enforced and which cost them any distance sweep (they never expired at all).
+    /// The bound light buffer: the world, a portrait booth and char select each bind their own.
     light: bevy::render::render_resource::BufferId,
     texture: Option<AssetId<Image>>,
     blend: ModelBlend,
@@ -78,118 +51,60 @@ pub struct MatKey {
     is_emissive: bool,
     is_additive: bool,
     fade_variant: bool,
-    /// M2 render flag 0x10 / 0x08 — disable depth write / depth test (`specialize` honours them).
+    /// M2 render flag 0x10 (0x08 for `no_depth_test`), honoured by `specialize`.
     no_depth_write: bool,
     no_depth_test: bool,
-    /// The batch's fog COLOUR policy ([`benilla_formats::FogPolicy`]) — packed into `clutter_fade.z`
-    /// bits 4-6 (`wow_model.wgsl`'s step-5 fog).
+    /// The batch's fog colour policy, packed into `clutter_fade.z` bits 4-6.
     fog_policy: benilla_formats::FogPolicy,
-    /// This batch's texture coordinates are **generated** — the sphere-map environment coordinate,
-    /// not the vertex UVs ([`benilla_formats::RenderSubmesh::env_map`]). Packed into
-    /// `clutter_fade.z` bit 12; a key axis because two batches sharing a texture but differing here
-    /// sample it completely differently. **Not** a `WowModelKey` axis — it swaps which UV the
-    /// FRAGMENT stage samples, no pipeline state, so it mints no pipeline (decision 0837).
+    /// The batch samples the generated sphere-map coordinate, not its vertex UVs.
     env_map: bool,
-    /// The batch's static terrain-shade selector ([`ShadeSel`]). Static per placement, so it dedups a
-    /// lit / matte / shaded material variant.
+    /// The static terrain-shade selector, fixed per placement.
     shade: ShadeSel,
-    /// Authored batch index + 1 (0 = a legacy/unordered caller). Every ordered batch (M2 and WMO)
-    /// folds it into the material's transparent SORT bias ([`BATCH_ORDER_SORT_EPS`]); WMO batches
-    /// additionally ride it into the vertex-stage clip-z nudge (the byte-verified MOBA draw-order
-    /// determinism, wow-5875-re models/scratch/wmo-batch-blend-depth-state.md).
+    /// Authored batch index + 1 (0 = unordered): the transparent sort bias of every batch, and for
+    /// WMO the clip-z nudge too (MOBA batches draw in strict file order, `0x6b4f10`/`0x6b5190`).
     batch_order: u16,
-    /// The batch's UV-animation identity (decision 0130 phase 3): the `Arc<UvAnim>` pointer, so
-    /// batches scrolling on different loops never share a material (their `sun_scale.zw` offsets
-    /// diverge every frame) while every instance of the same model batch does. Sound because the
-    /// `Arc` lives in the loaded model asset — one allocation per model per batch, stable while
-    /// loaded. `None` = static UVs (the overwhelming majority).
+    /// The `Arc<UvAnim>` pointer, stable while its model is loaded: one material per UV loop.
     uv_anim: Option<usize>,
-    /// The batch's animated-RGB-tint identity: the `Arc<RgbAnim>` pointer (same soundness argument
-    /// as [`Self::uv_anim`]), so batches tinting on different tracks never share a material while
-    /// every instance of the same model batch does. `None` = a static tint (the vertex bake).
+    /// The `Arc<RgbAnim>` pointer, keyed like [`Self::uv_anim`]; `None` is a static vertex tint.
     rgb_anim: Option<usize>,
-    /// The WMO batch's MOBA section (`None` for M2): an interior group's INT and TRANS batches take
-    /// different lighting lanes (`tint.w`), so they must never dedupe onto one material.
+    /// The WMO batch's MOBA section: an interior group's INT and TRANS batches light differently.
     wmo_class: Option<WmoBatchClass>,
-    /// The WMO MOMT SIDN night-glow colour (RGB gamma bytes; `None` = no SIDN / M2) — part of the
-    /// material identity so glass authored with different glow colours never dedupes together.
+    /// The WMO MOMT SIDN night-glow colour, gamma RGB bytes.
     sidn: Option<[u8; 3]>,
-    /// The WMO MOMT WINDOW flag — an interior-group batch on the brighter midpoint light.
+    /// The WMO MOMT WINDOW flag: an interior-group batch on the brighter midpoint light.
     window: bool,
-    /// This material is a **depth-prime twin** ([`zfill_material`] — the reference's `M2UseZFill`
-    /// clone command, wow-re `m2-blend-promotion-zfill.md` §4): colour writes masked off, blend off,
-    /// z-write on, drawn before its model's colour batches. Its own key axis so a twin can never
-    /// dedupe onto a colour material.
+    /// A depth-prime twin ([`zfill_material`], the reference's `M2UseZFill` clone at `0x707f7d`).
     zfill: bool,
-    /// This batch is part of a **WMO skybox** ([`crate::skybox`]) — the building-owned painted sky,
-    /// drawn on this lane like any other M2 since decision 1264. Its own key axis because the lane
-    /// changes pipeline state ([`SKY_DEPTH_MARKER`]: the far depth pinned at the vertex) and sort rung
-    /// ([`skybox_sort_bias`]), so a skybox batch must never dedupe onto the identical-looking world
-    /// batch — `CavernsOfTimeSky` and Elwynn share no texture today, but nothing enforces that and
-    /// the collision would be a world doodad silently drawn at the far plane.
+    /// A WMO skybox batch ([`crate::skybox`]), with its own pipeline and sort rung.
     sky_depth: bool,
-    /// **This material belongs to one placement, not to the batch** — `None` for the shared
-    /// material every instance of a model reuses, which is every batch but one measured class.
-    ///
-    /// The animated-material registries ([`crate::doodad_anim::UvAnimMaterials`] and its tint twin)
-    /// are keyed by MATERIAL, so a batch whose animated loop depends on **which sequence its
-    /// instance is playing** cannot share one and be right: the BRM lava bubbles key their whole
-    /// flipbook inside a 50 %-weighted variation of animation id 0, and their 15 placements re-roll
-    /// independently every ~3.3 s (decision 0768), so at any instant some are on slot 0 and some on
-    /// slot 1. Keying the material by the placement's anim host gives each its own row and its own
-    /// sequence (decision 1408); the population is 22 batch-channels across 6 models
-    /// (`benilla-extract uvslotscan`), and the clones expire on the same distance evictor as every
-    /// other material ([`scope_model_materials`], decision 0785).
+    /// The placement owning this material when its animated loop follows the instance's sequence
+    /// (the BRM lava bubbles' flipbook); `None` for the shared material.
     instance: Option<Entity>,
 }
 
-/// The per-material static terrain-shade **selector** baked into `sun_scale.x` — NOT an intensity
-/// itself. `wow_model.wgsl` thresholds the selector (≥0.85 / ≥0.5) into the byte-true INTENSITY
-/// family (decision 0354: 2.5 lit / 1.0 day-night / 0.5 MCSH-shadowed — `[node+0xa4]`) scaling the
-/// global SH eval. It is the static half of the verified per-category matrix (wow-re
-/// `m2-interior-doodad-base-light` §6/§8/§9, decision 0173) — dynamic entities
-/// (units/players/GameObjects) are always [`ShadeSel::Lit`] here and mix toward the shaded
-/// intensity per instance via the `MeshTag` shade byte ([`crate::entity_shade`]).
+/// The static terrain-shade selector in `sun_scale.x`, which the shader thresholds into the
+/// reference's intensities (2.5 lit, 1.0 day/night, 0.5 shadowed; `[node+0xa4]`, `0x69e280`).
+/// Entities are always [`ShadeSel::Lit`] and shade per instance by the `MeshTag` byte.
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 pub enum ShadeSel {
-    /// Lit ground, the boosted intensity family (the binary's 2.5): **every entity M2, and only
-    /// those** — a unit, a player, a GameObject. The 2.5 and its 3.3333/s chase live on the
-    /// WENTITY light node (vtable `0x810810`, hung off `[obj+0xe0]`); an object without one
-    /// cannot reach either. ADT map doodads were on this variant until 2050 and are not entities:
-    /// they are `CMapDoodadDef`s, whose `[+0xa4]` is only ever {0.0, 0.5, 1.0} and which have no
-    /// ramp target field at all (`+0xf8` is `m[2][3]` of their world matrix).
-    ///
-    /// Entities still select this, but what it *means* for them changed in 0809. The selector is
-    /// only the static half — the per-instance `MeshTag` shade byte carries the rest, and
-    /// [`crate::entity_shade`] now pins that byte to the day/night ×1.0 for units and players
-    /// (`0x672a20`'s null-node fallback commits with no per-node intensity multiply at all), while
-    /// GameObjects keep the real 2.5/0.5 chase. So for an entity this variant reads "on the light-node
-    /// path"; the node decides the amplitude.
+    /// Entity M2s only: the 2.5 and its 3.3333/s chase live on the WENTITY light node (vtable
+    /// `0x810810`, `[obj+0xe0]`), which [`crate::entity_shade`] ramps per instance into the
+    /// `MeshTag` byte for units, players and GameObjects alike.
     Lit,
-    /// Lit ground, intensity 1.0: **either doodad class** — an exterior WMO MODD prop *and* an ADT
-    /// map doodad, byte-verified never to reach the 2.5 site.
-    ///
-    /// The parenthetical this doc carried until 2050 — "a Stormwind street fountain is NOT
-    /// brightened like an Elwynn tree" — was exactly backwards about the tree: both are
-    /// `CMapDoodadDef`s and both commit 1.0 lit / 0.5 shadowed. What is brightened is the
-    /// *entity* walking past them. Measured over six trace frames: 111 identified MDDF
-    /// placements, 356 draws, gains only ∈ {0.5, 1.0}.
+    /// Lit ground at 1.0: exterior WMO MODD props and ADT map doodads, never the 2.5 site; a map
+    /// doodad's `CMapDoodadDef` `[+0xa4]` is only ever 0.0, 0.5 or 1.0.
     Matte,
-    /// The base sits on MCSH-shadowed terrain: the dim intensity (the binary's 0.5).
+    /// The base sits on MCSH-shadowed terrain: the reference's dim 0.5.
     Shaded,
-    /// Lit by an **authored M2 light rig** (the glue create booth, decision 0429): the lit value is
-    /// the order-2 SH probe in slot 0 of the material's *own* light buffer — the scene's ambient +
-    /// directional lights folded by `lighting::prop_probe_coeffs`, the same `Model2.bls` curve the
-    /// reference's vertex program runs — plus the per-vertex ≤3-nearest point term (the scene's
-    /// authored point lights ride the buffer's point table; a rig material is neither WMO nor
-    /// interior, so the vertex stage computes it). The world's sun/intensity machinery never
-    /// applies: a glue scene has no day/night, no MCSH, no storm band.
+    /// An authored M2 light rig (the glue create booth): the SH probe in slot 0 of the material's
+    /// own light buffer, on the reference's `Model2.bls` curve, plus up to three nearest point
+    /// lights; no sun or MCSH.
     Rig,
 }
 
 impl ShadeSel {
-    /// The `sun_scale.x` encoding `wow_model.wgsl` thresholds (≥1.5 ⇒ authored-rig probe;
-    /// ≥0.85 ⇒ ADT lit; ≥0.5 ⇒ matte; else shaded).
+    /// The `sun_scale.x` value, matching `wow_model.wgsl`'s thresholds (1.5 rig, 0.85 lit,
+    /// 0.5 matte, else shaded).
     pub fn selector(self) -> f32 {
         match self {
             ShadeSel::Lit => 1.0,
@@ -200,26 +115,13 @@ impl ShadeSel {
     }
 }
 
-/// A material-dedup cache. Each model-spawning subsystem (terrain doodads/WMOs, streamed entities)
-/// keeps its own so its handles drop with it — and, since decision 0793, so its entries expire by
-/// **distance** ([`benilla_assets::SpatialCache`]) instead of living until the next map change. A
-/// cache nobody sweeps (the `Local<MaterialCache>`s in the glue booth and the portrait bake) behaves
-/// exactly as it did: a plain dedup map.
+/// A material-dedup cache, one per model-spawning subsystem; entries expire by distance if swept.
 pub type MaterialCache = benilla_assets::SpatialCache<MatKey, Handle<WowModelMaterial>>;
 
-/// Build (or fetch the deduped) [`WowModelMaterial`] for a model batch: a `StandardMaterial` base
-/// carrying the texture/alpha/cull, plus the `WowModelExt` shared-light extension. `fade_variant`
-/// marks the `AlphaMode::Blend` twin every feather pass rides — the doodad distance fade AND the
-/// entity appear/despawn/aura fades (`entities::display` builds its twins with it too); steady
-/// materials pass `false`. `specialize` keys depth-write-ON on this bit for the twin.
-///
-/// A twin builder passes the **SOURCE batch's blend mode** (never `ModelBlend::Blend`): the twin
-/// always blends — the reference's promotion is transparent-pass membership, not a per-mode state
-/// (`m2-blend-promotion-zfill.md` §1) — but the alpha TEST under promotion keys on the *stored*
-/// blend mode (§2): AlphaKey keeps its 224/255 cutout while blending, Opaque runs with no alpha
-/// test at all. The source blend is what sets [`TWIN_CUTOUT_MARKER`] right (decision 0842: a twin
-/// built as `Blend` cut every texel under 224/255 out of a stealthed Opaque batch, which erased
-/// Gressil's blade body and left only its high-alpha rune pattern).
+/// Build or fetch the deduped [`WowModelMaterial`] for one model batch. `fade_variant` marks the
+/// blend twin every fade rides, built with the source blend, never `Blend`: the twin always blends
+/// (`0x70c1fd`) but its alpha test keys on the stored mode (`0x70c237`), so AlphaKey keeps its
+/// 224/255 cutout and Opaque has none.
 pub fn model_material(
     cache: &mut MaterialCache,
     materials: &mut Assets<WowModelMaterial>,
@@ -234,24 +136,14 @@ pub fn model_material(
     no_depth_write: bool,
     no_depth_test: bool,
     fog_policy: benilla_formats::FogPolicy,
-    // This batch's texture coordinates are GENERATED, not authored
-    // ([`benilla_formats::RenderSubmesh::env_map`]) — see [`MatKey::env_map`].
     env_map: bool,
     shade: ShadeSel,
-    // Authored batch index + 1 (0 = unordered): the transparent-pass ORDER of this batch among its
-    // model's other batches — see [`MatKey::batch_order`] and [`BATCH_ORDER_SORT_EPS`].
     batch_order: u16,
     uv_anim: Option<&std::sync::Arc<benilla_formats::UvAnim>>,
     rgb_anim: Option<&std::sync::Arc<benilla_formats::RgbAnim>>,
-    // The WMO batch's MOBA section (`None` for M2 batches) — with `is_interior`, it picks the
-    // batch's lighting lane (`tint.w`; see `WowModelExt::tint`).
     wmo_class: Option<WmoBatchClass>,
-    // The WMO window/glass law (`None`/`false` for M2): the MOMT SIDN night-glow colour and the
-    // WINDOW midpoint-light flag (`WowModelExt::sidn`).
     sidn: Option<[u8; 3]>,
     window: bool,
-    // This batch belongs to a **WMO skybox** — the sky lane: forced far depth, no rasterizer bias,
-    // and the skybox sort rung instead of the ordinary batch-order eps. See [`MatKey::sky_depth`].
     sky_depth: bool,
     light: &Buffer,
     // MONKEY (torch shadows Phase 3A): the shared torch depth image + table buffer, cloned into the
@@ -291,57 +183,28 @@ pub fn model_material(
     if let Some(h) = cache.fetch(&key) {
         return h;
     }
-    // Additive batches (M2 glow cards) ADD their colour to the framebuffer — so the warm glow isn't
-    // muted by the (cool, at night) background bleeding through. They go in the transparent pass
-    // (`AlphaMode::Blend`); the shader folds the radial alpha into the colour IN GAMMA SPACE
-    // (decision 0160) and `specialize` overrides the blend STATE to a pure (ONE, ONE) add. The
-    // additive marker is `clutter_fade.z` bit 2 — the shader gates the gamma-premultiply on the
-    // SAME bit specialize keys on (a stale "model_flags.w == 2.0" claim here once desynced the
-    // two: blend went pure-add while the premultiply never fired — the flat-square regression).
-    // `WOW_NO_ALPHATEST=1` draws every cutout batch opaque — the A/B for "is the alpha test
-    // itself discarding this surface?", which is otherwise indistinguishable in the pixels
-    // from the surface losing a depth test or never being submitted. (B38: the flip
-    // survives it unchanged, so the cutout is not what removes the awning.) It suppresses the
-    // fade twin's cutout marker too, so the A/B answers the same question mid-fade.
+    // An additive batch is a (ONE, ONE) add of gamma-space premultiplied colour: the shader and
+    // `specialize` must key on the same `clutter_fade.z` bit 2.
     let source_cutout = blend == ModelBlend::AlphaTest && !alphatest_disabled();
     let alpha_mode = if is_additive || fade_variant {
-        // A fade twin blends whatever its source blend is — the reference's promotion is
-        // transparent-pass membership (`m2-blend-promotion-zfill.md` §1); the source blend the
-        // caller passed decides only the cutout marker below.
+        // A fade twin always blends (`0x70c1fd`); its source blend only sets the cutout marker.
         AlphaMode::Blend
     } else {
         match blend {
             ModelBlend::Opaque => AlphaMode::Opaque,
             ModelBlend::AlphaTest if source_cutout => AlphaMode::Mask(VANILLA_ALPHA_KEY_REF),
             ModelBlend::AlphaTest => AlphaMode::Opaque,
-            // Mod/Mod2x ride the transparent pass (they multiply what's already drawn, so the
-            // scene under them must exist); `specialize` swaps the actual blend state to the
-            // byte-verified multiply factors via the marker bits below (decision 0528).
+            // Mod/Mod2x multiply what is drawn, so they need the scene under them; `specialize`
+            // sets the multiply factors from the marker bits below.
             ModelBlend::Blend | ModelBlend::Mod | ModelBlend::Mod2x => AlphaMode::Blend,
         }
     };
-    // Single-sided unless the M2's 0x04 flag is set (many canopy planes are one-directional).
+    // Single-sided unless the M2's 0x04 flag is set.
     let cull_mode = if two_sided { None } else { Some(Face::Back) };
-    // The authored batch order as a transparent sort bias ([`BATCH_ORDER_SORT_EPS`]): one model's
-    // coplanar batches draw in file order instead of re-flipping a sort tie every frame.
-    //
-    // TRANSPARENT-PASS ONLY, and CAPPED below 1.0 (decision 0938's tail — the Stormwind evening
-    // log). The bias is also the base `StandardMaterialKey`'s `depth_bias as i32` axis, which
-    // 0837's original comment believed excluded (only the EXTENSION key excludes it) — invisible
-    // while every product truncated to 0, until a city-scale WMO's root-scoped batch index
-    // (`assemble.rs`, u16 — Stormwind roots run past 2000) pushed the product to 1.0+ and each
-    // integer became a live-compiled pipeline. Opaque/mask batches take no bias at all: their
-    // pass never sorts by it, and the coplanar-stack job belongs to the vertex-stage depth nudge
-    // (0837's `sun_scale.y`), so a nonzero value was only a key leak. Transparent batches keep
-    // total order through index 899 and tie at the cap beyond it — safe, because the eps is
-    // load-bearing only for SAME-CENTRE stacks (M2 item overlays, always low-index); WMO batches
-    // sort by their own distinct mesh centres. The cap stays under `FAR_KEY_PULL` so a far twin
-    // of a capped batch still lands on the far band's one key integer.
-    //
-    // The SKY lane takes the same shape one rung down: a skybox is camera-anchored, so its view-z
-    // is a few tens of yards and it would sort after the world's transparents rather than behind
-    // them ([`crate::sky_order::WMO_SKYBOX_BIAS`]). Its opaque batches still take no bias — the
-    // painted cube faces are in the opaque pass, which is exactly where the reference puts them.
+    // Transparent batches only: opaque passes never sort by it. Tying past index 899 is safe:
+    // the eps matters only for same-centre stacks (M2 item overlays), and WMO batches sort by
+    // their own centres. Skybox transparents take their own rung under the world's; its painted
+    // cube faces draw opaque, as in the reference.
     let depth_bias = if !matches!(alpha_mode, AlphaMode::Blend) {
         0.0
     } else if sky_depth {
@@ -358,12 +221,9 @@ pub fn model_material(
             depth_bias,
             ..default()
         },
-        // No resolved texture → the reference DISABLES the texture stage and draws the batch in
-        // its flat vertex/material colour — i.e. WHITE modulate, byte-verified for the no-source
-        // runtime-texture case (wow-re m2-runtime-texture-null-bind.md, their 914a1abd: slot 0 →
-        // glDisable, no default texture, alpha test passes everywhere — the Westfall lamppost's
-        // "bulb on" pane). The old muted-brown debug tint was unfaithful. Blend/cull state still
-        // honoured — an untextured fade twin must keep its per-instance alpha path.
+        // No texture: the reference disables the texture stage and draws the flat vertex colour,
+        // a white modulate whose alpha test passes everywhere (`0x59baa0`). Blend and cull still
+        // apply, so an untextured fade twin keeps its alpha path.
         None => StandardMaterial {
             base_color: Color::WHITE,
             alpha_mode,
@@ -378,33 +238,17 @@ pub fn model_material(
         ExtendedMaterial {
             base,
             extension: WowModelExt {
-                // `clutter_fade.z` is unread by the shader, so it carries the per-batch pipeline markers
-                // `specialize` keys on: bit0 = no-depth-write (M2 0x10), bit1 = no-depth-test (0x08),
-                // bit2 = additive blend. (`x`/`y`/`w` stay the ground-clutter distance fade — `0` here.)
+                // x, y, w are the clutter fade (0 here); z packs the markers `specialize` keys on.
                 clutter_fade: Vec4::new(
                     0.0,
                     0.0,
-                    // Bit 3 = OPAQUE-INTENT: an opaque/alpha-key steady batch whose output alpha is
-                    // semantically meaningless (opaque/mask pipelines ignore it — only blend pipelines
-                    // read it). The shader pins such batches' output alpha to 1.0: a spec-level no-op
-                    // that armors against a multi-view pipeline-state mixup observed on macOS/Metal
-                    // (opaque WMO/M2 draws intermittently bound with blending enabled when an extra
-                    // camera exists, bleeding the garbage BLP alpha channel — the "pale film on
-                    // buildings" regression; full measured chain in the fix commit).
-                    // Bits 4-6 = the per-batch FOG POLICY (`FogPolicy` discriminant, wow-re
-                    // rf-weather-emission-timeline ROUND 4): 0 = scene so clutter/water materials —
-                    // which leave the byte's high bits 0 (see `WorldAssets::model_material`,
-                    // `water_fx`) — keep ordinary scene fog; 1/2/3 = the additive/Mod/Mod2x BLACK/
-                    // WHITE/GREY fog colours; 4 = fog disabled outright (render flag 0x02).
-                    // Bits 7/8 = the MULTIPLY blends (decision 0528): `specialize` swaps the pipeline
-                    // to the byte-verified factors — Mod DST_COLOR/ZERO, Mod2x DST_COLOR/SRC_COLOR
-                    // (exact on the 0161 gamma lane: the framebuffer holds gamma, like the reference).
-                    // Bit 10 = TWIN CUTOUT (decision 0842): this fade twin's SOURCE batch alpha-tests,
-                    // so the shader re-applies the hard 224/255 cutout on the unfaded alpha (the
-                    // reference's promoted-AlphaKey ALPHAREF = A×224 — the same fixed silhouette). An
-                    // Opaque source sets no bit: the reference disables its alpha test outright, steady
-                    // and promoted alike (`m2-blend-promotion-zfill.md` §2 keys ALPHAREF on the STORED
-                    // blend mode, mode 0 → ref 0).
+                    // Bits: 0 no depth write (M2 0x10), 1 no depth test (0x08), 2 additive,
+                    // 3 opaque intent (the shader pins alpha to 1.0: Metal has bound opaque
+                    // draws with blending on when an extra camera exists), 4-6 fog policy
+                    // (`0x70baf0`), 7 Mod (DST_COLOR, ZERO) and 8 Mod2x (DST_COLOR, SRC_COLOR),
+                    // exact because the framebuffer holds gamma as in the reference, 10 twin
+                    // cutout (the source alpha-tests: 224/255 on the unfaded alpha; an Opaque
+                    // source has no test, `0x70c237`), 12 env map, 13 sky depth.
                     f32::from(
                         u16::from(no_depth_write)
                             | (u16::from(no_depth_test) << 1)
@@ -423,19 +267,10 @@ pub fn model_material(
                     ),
                     0.0,
                 ),
-                // x = WMO (FFP N·L × MOCV, not the M2 SH probe); y = distance-fade blend variant; z = WMO
-                // interior group (sun off, baked MOCV carries the room); w = **unlit fullbright** (>0.5 ⇒
-                // bypass lighting in wow_model.wgsl): the M2 UNLIT (0x01) flag, or WMO UNLIT on an
-                // exterior-group batch (the interior drawer ignores it — section law, `wmo-lit-selector`).
-                // Additive is NOT fullbright: the real client *lights* additive batches unless 0x01 is set
-                // (wow-re `m2-no-envmap-texgen`'s lighting section — `DAT_00811fa8[4] = 1`), so an
-                // un-flagged additive (e.g. ArmorReflect shine) is lit. **That note's headline is
-                // otherwise wrong and this cite reaches only its lighting table** (decision 0971): the
-                // M2 path DOES generate env-map texcoords — in the vertex program, which the note's
-                // `SetRenderState` sweep could not see. See [`ENV_MAP_MARKER`].
-                // M2 Mod/Mod2x ARE fullbright regardless of 0x01 — the lighting table
-                // `DAT_00811fa8 = {1,1,1,1,1,0,0}` clears GL_LIGHTING for modes 5/6 (wow-re
-                // `m2-depth-blend-state`); WMO lighting stays flag-driven only (decision 0528).
+                // x WMO (FFP N·L × MOCV), y fade variant, z WMO interior group (sun off), w unlit:
+                // M2 UNLIT 0x01, or WMO UNLIT on an exterior group (`0x6b4f10`; the interior
+                // drawer `0x6b5190` ignores it). M2 Mod/Mod2x are always unlit, and additive is
+                // lit unless 0x01 is set (`DAT_00811fa8 = {1,1,1,1,1,0,0}`).
                 model_flags: Vec4::new(
                     if is_wmo { 1.0 } else { 0.0 },
                     if fade_variant { 1.0 } else { 0.0 },
@@ -448,26 +283,15 @@ pub fn model_material(
                         0.0
                     },
                 ),
-                // x = the static MCSH terrain-shade SELECTOR ([`ShadeSel`]: 1.0 ADT-lit / 0.6 matte /
-                // 0.2 shaded; shader thresholds at 0.85 and 0.5) that chooses which live sun LEVEL scales the
-                // FFP matte's diffuse term. Static per material (a doodad doesn't move), so it dedups the
-                // variants; moving entities are Lit here and mix per instance via the `MeshTag` shade byte.
-                // y = the WMO authored batch order, read by `wow_model.wgsl`'s VERTEX stage: it scales
-                // clip z by (1 + y·2⁻²³) so a later coplanar batch wins the reverse-Z depth test in any
-                // draw order — the byte-verified MOBA draw-order determinism. Uniform data by design:
-                // as a `WowModelKey` axis driving a fixed-function depth bias it made every batch index
-                // its own PIPELINE, and a first city sight compiled ~3000 of them synchronously on the
-                // render thread (decision 0837). `WOW_WMO_BIAS=0` (B38's A/B diagnostic) zeroes it here.
-                // zw = the batch's live **UV-animation offset** (decision 0130 phase 3, wow-re
-                // `m2-texanim-uv`: the real client adds the sampled translation to the stage UVs —
-                // translation is un-pivoted, and no placed doodad uses rotation/scaling). Seeded at
-                // t = 0 here; `doodad_anim::tick_anim_materials` re-samples it per drawn frame on the
-                // shared clock (frozen in captures).
+                // x the shade selector. y the WMO batch order, uniform data, not a pipeline key:
+                // the vertex stage scales clip z by (1 + y·2⁻²³), so a later coplanar batch wins
+                // in any draw order, as in MOBA order. zw the UV-animation offset at t = 0, the
+                // seed the per-frame table row is added to: `0x714260` adds the un-pivoted
+                // translation to the stage UVs, and no placed doodad rotates or scales them.
                 sun_scale: {
                     let uv0 = uv_anim.map_or([0.0, 0.0], |a| a.sample(0.0));
-                    // The clip-z nudge stays WMO-only: M2 coplanar layers pass GreaterEqual at exactly
-                    // equal depth (same mesh, same transform, same vertex path), and their ORDER is
-                    // the sort bias above — nudging their depth would be an unverified extra.
+                    // WMO only: M2 coplanar layers pass GreaterEqual at equal depth, and their
+                    // order is the sort bias.
                     let order = if !is_wmo || wmo_bias_off() {
                         0.0
                     } else {
@@ -475,14 +299,9 @@ pub fn model_material(
                     };
                     Vec4::new(shade.selector(), order, uv0[0], uv0[1])
                 },
-                // The animated M2Color tint's first key (identity white for static batches — their
-                // constant tint rides the vertex colours instead). A lane that never re-samples this
-                // shows exactly the old static bake; the effect lane clones + ticks it per instance.
-                // `w` = the WMO interior batch-class lane: an interior group's INT batches draw UNLIT
-                // (pure tex × MOCV) and its TRANS batches lerp lit↔bake by the MOCV alpha (wow-re
-                // `trace-forensics-abbey-interior-d3d` §2 — observed on the abbey at close range, the
-                // northshire "lit interior batch" datum having been a mis-identified unit). Exterior
-                // groups' batches (and every M2) ride 0 = the exterior law.
+                // xyz the animated M2Color tint's first key (white when static: the vertex colours
+                // carry it). w the WMO interior class: INT batches draw unlit tex × MOCV and TRANS
+                // batches lerp lit to baked by the MOCV alpha (`0x6b5190`); exterior and M2 are 0.
                 tint: {
                     let t0 = rgb_anim.map_or([1.0, 1.0, 1.0], |a| a.sample(0.0));
                     let class_lane = match (is_interior && is_wmo, wmo_class) {
@@ -492,9 +311,7 @@ pub fn model_material(
                     };
                     Vec4::new(t0[0], t0[1], t0[2], class_lane)
                 },
-                // The WMO window/glass law (`WowModelExt::sidn`): xyz = the authored SIDN emissive
-                // (gamma bytes /255 — the shader ramps it by the live night fraction on lit lanes),
-                // w = the WINDOW midpoint-light flag.
+                // xyz the SIDN emissive, ramped by the night fraction; w the WINDOW flag.
                 sidn: {
                     let c = sidn.unwrap_or([0, 0, 0]);
                     Vec4::new(
@@ -504,8 +321,7 @@ pub fn model_material(
                         if window { 1.0 } else { 0.0 },
                     )
                 },
-                // Static until a sampler registers this material (decision 1381) — then the
-                // table slot is baked in exactly once.
+                // Zero until a sampler registers this material and bakes its table slot in once.
                 anim_slots: Vec4::ZERO,
                 light_buf: light.clone(),
                 // MONKEY (torch shadows Phase 3A): the shared torch receiver bindings.
@@ -521,82 +337,46 @@ pub fn model_material(
 /// `clutter_fade.z` marker bit 9: this material is a depth-prime twin ([`zfill_material`]).
 pub(crate) const ZFILL_MARKER: u16 = 1 << 9;
 
-/// `clutter_fade.z` marker bit 10: this twin's SOURCE batch alpha-tests, so the shader re-applies
-/// the hard 224/255 cutout while blending (`wow_model.wgsl`). Set from the source blend mode by
-/// [`model_material`] (fade twins) and [`zfill_material`] (depth-prime twins); never on an
-/// Opaque-source twin — the reference runs mode 0 with the alpha test disabled, steady and
-/// promoted alike (`m2-blend-promotion-zfill.md` §2; decision 0842).
+/// `clutter_fade.z` marker bit 10: the twin's source alpha-tests, so the shader keeps the 224/255
+/// cutout while blending. Never on an Opaque source: mode 0 has no alpha test (`0x70c237`).
 pub(crate) const TWIN_CUTOUT_MARKER: u16 = 1 << 10;
 
-/// `clutter_fade.z` marker bit 12: this batch's texture coordinates are **generated**, so
-/// `wow_model.wgsl` derives them from the view-space reflection vector instead of sampling the
-/// (meaningless) vertex UVs — the reference's `texture_unit_lookup > 2` env stage. Bit 11 is
-/// [`FAR_SIDE_MARKER`]. Deliberately **not** a [`benilla_assets::materials::WowModelKey`] axis: it changes
-/// only what the fragment stage samples, so it needs no pipeline of its own (decision 0837).
+/// `clutter_fade.z` marker bit 12: texture coordinates from the view-space reflection vector, the
+/// reference's `texture_unit_lookup > 2` env stage; fragment-only, so not a `WowModelKey` axis.
 pub(crate) const ENV_MAP_MARKER: u16 = 1 << 12;
 
-/// `clutter_fade.z` marker bit 13: the **WMO-skybox lane** — this batch is part of a building's
-/// painted sky, so `specialize` compiles the shader's `WOW_SKY_DEPTH` branch (the far depth,
-/// pinned at the vertex — decision 2016) and drops the rasterizer bias constant. It *is* a
-/// [`benilla_assets::materials::WowModelKey`] axis, unlike [`ENV_MAP_MARKER`]: the pin belongs
-/// to exactly one camera-anchored model, and every other draw in the frame must keep the
-/// pipeline that leaves its depth real.
+/// `clutter_fade.z` marker bit 13: a WMO skybox batch, whose pipeline pins the far depth at the
+/// vertex with no raster bias; a `WowModelKey` axis, so every other draw keeps its real depth.
 pub(crate) const SKY_DEPTH_MARKER: u16 = 1 << 13;
 
-/// Sort-bias step per authored batch on the **WMO-skybox lane** — [`BATCH_ORDER_SORT_EPS`]'s job,
-/// resized for the rung it has to survive.
-///
-/// The plain 1e-3 eps cannot be used here: added to [`crate::sky_order::WMO_SKYBOX_BIAS`] (−6e4) it
-/// falls *under the f32 ulp at that magnitude* (2¹⁵·2⁻²³ = 0.0039), so every batch rounds onto the
-/// same bias and the sort tie the eps exists to break comes back in silence. This step is 4 ulps
-/// there — exactly representable, strictly monotone. The tie is not a rare coplanar case on this
-/// lane: a skybox is anchored at the eye, so *every* pair of its batches shares a sort distance,
-/// every frame.
+/// [`BATCH_ORDER_SORT_EPS`] for the WMO skybox lane: at the −6e4 rung the f32 ulp is 0.0039, so
+/// 1e-3 would round away; this step is 4 ulps. Every skybox batch pair ties, being eye-anchored.
 pub(crate) const SKYBOX_ORDER_EPS: f32 = 0.015625;
 
-/// The skybox band's ceiling. With [`FAR_KEY_PULL`] it keeps the whole band on ONE pipeline-key
-/// integer — 0837's law: the base `StandardMaterialKey` packs `depth_bias as i32`, so a band
-/// straddling an integer is a live pipeline compile per side. Pulled by just under 1 and capped at
-/// 0.9, every batch lands in `(RUNG − 0.99, RUNG − 0.09]`, which truncates toward zero onto the
-/// same integer for all of them. The cap ties batches past index 57 (`0.9 / SKYBOX_ORDER_EPS`); the
-/// largest skybox the chain ships is 21 batches (`CavernsOfTimeSky.m2`).
+/// The skybox band's ceiling: with [`FAR_KEY_PULL`] every batch lands on one pipeline-key integer.
+/// It ties past index 57; the largest skybox, `CavernsOfTimeSky.m2`, has 21 batches.
 pub(crate) const SKYBOX_ORDER_CAP: f32 = 0.9;
 
-/// This batch's slot in the skybox band: the lane rung, pulled onto one pipeline key, plus the
-/// authored batch order. See [`SKYBOX_ORDER_EPS`] and [`crate::sky_order::WMO_SKYBOX_BIAS`].
+/// A batch's slot in the skybox band: the rung, pulled onto one pipeline key, plus its order.
 fn skybox_sort_bias(batch_order: u16) -> f32 {
     crate::sky_order::WMO_SKYBOX_BIAS - FAR_KEY_PULL
         + (f32::from(batch_order) * SKYBOX_ORDER_EPS).min(SKYBOX_ORDER_CAP)
 }
 
-/// The twin's `Transparent3d` sort bias (yards; **negative = drawn earlier** — the sign law is
-/// `sky_order`'s module doc). It must clear the spread of one model's part AABB centres, so **all**
-/// of a fading model's twins draw before **any** of its colour parts — the reference achieves the
-/// same by tying every command of one instance to a single sort key (`cmd+0x14 = model+0x84`) and
-/// putting twins first inside the tie (`m2-blend-promotion-zfill.md` §4/§6). 8 yd covers every
-/// humanoid and mount; the residue (a model taller than 8 yd may keep a little self-overlap
-/// darkening at its extremities, and transparent scene content sorting within 8 yd behind a fading
-/// body draws after the prime and is depth-clipped where the body covers it) is recorded in
-/// decision 0831. The same field doubles as the rasterizer depth bias in relative ULPs — at −8 that
-/// is ~2⁻²⁰ relative, and its direction (twin marginally farther) only makes the colour pass's
-/// GreaterEqual test safer against cross-pipeline ULP noise.
+/// The depth-prime twin's sort bias in yards (negative draws earlier), past the spread of one
+/// model's part centres so all its twins draw before any colour part, as the reference's one sort
+/// key per instance with twins first does (`cmd+0x14 = model+0x84`, `0x707db1`, `0x70ae10`). 8 yd
+/// covers humanoids and mounts; a taller model can keep some self-overlap, and a transparent
+/// sorting within 8 yd behind a fading body draws after its prime and clips where the body covers
+/// it. As a raster depth bias it is ~2⁻²⁰ relative, away from the eye.
 pub(crate) const ZFILL_SORT_BIAS: f32 = -8.0;
 
-/// Build (or fetch) the **depth-prime twin** material for one fadeable entity batch — the
-/// reference's `M2UseZFill` clone (wow-re `m2-blend-promotion-zfill.md` §4, VERIFIED): while a
-/// model draws translucent (`0 < A < 1`), a colour-masked, blend-off, z-writing copy of each of its
-/// depth-writing batches draws first, so every colour fragment behind the model's own nearest
-/// surface fails the depth test — one blended layer everywhere, no self-overlap darkening.
-///
-/// `cutout` = **the source batch alpha-tests** (AlphaKey). It mirrors what the part's COLOUR pass
-/// discards, and must keep mirroring it: a twin that writes depth where the colour pass discards
-/// leaves an invisible depth wall inside the cutout holes. Only an AlphaKey source rides the fade
-/// twin's hard 224/255 cutout ([`TWIN_CUTOUT_MARKER`]); Opaque sources never alpha-test
-/// (`m2-blend-promotion-zfill.md` §2/§4 — the reference's twin keeps mode 1's test, mode 0 has
-/// none; decision 0842) and authored-Blend sources discard nothing either.
-///
-/// Everything that shapes only the *colour* (lighting lane, shade, fog, tint) is canonicalized so
-/// twins dedupe maximally — the `WOW_ZFILL` fragment returns before any of it.
+/// Build or fetch the depth-prime twin for one fadeable entity batch, the reference's
+/// `M2UseZFill` clone (`0x707f7d`): while a model is translucent, a colour-masked, z-writing copy
+/// of each depth-writing batch draws first, so only its nearest surface blends. `cutout` marks an
+/// AlphaKey source, whose twin keeps its alpha test as the reference's does (mode 0 has none,
+/// `0x70c237`); it must match what the colour pass discards, or the holes get depth walls.
+/// Colour-only inputs are canonical, so twins dedupe.
 pub fn zfill_material(
     cache: &mut MaterialCache,
     materials: &mut Assets<WowModelMaterial>,
@@ -623,8 +403,6 @@ pub fn zfill_material(
         no_depth_write: false,
         no_depth_test: false,
         fog_policy: benilla_formats::FogPolicy::Scene,
-        // A depth-prime twin writes no colour at all, so which UV it would have sampled cannot
-        // reach a pixel — one twin per source batch, whatever its texcoord source.
         env_map: false,
         shade: ShadeSel::Lit,
         batch_order: 0,
@@ -634,11 +412,8 @@ pub fn zfill_material(
         sidn: None,
         window: false,
         zfill: true,
-        // A depth-prime twin exists to write depth for a fading model; the sky writes none, so no
-        // skybox batch ever has one (`M2BatchMaterials::skybox` builds no twins at all).
+        // No skybox batch has a twin: the sky writes no depth.
         sky_depth: false,
-        // A z-fill twin carries no animated channel at all (no texture, no uv/rgb anim), so it can
-        // never be the per-placement lane — it stays the one shared depth prime per batch.
         instance: None,
     };
     if let Some(h) = cache.fetch(&key) {
@@ -647,8 +422,7 @@ pub fn zfill_material(
     let cull_mode = if two_sided { None } else { Some(Face::Back) };
     let base = StandardMaterial {
         base_color_texture: texture,
-        // Blend keeps the twin in the transparent pass, where the sort bias can place it before
-        // the colour parts; `specialize` masks the colour writes off and turns blend off.
+        // Blend for the transparent pass's sort; `specialize` turns blend and colour writes off.
         alpha_mode: AlphaMode::Blend,
         depth_bias: ZFILL_SORT_BIAS,
         double_sided: two_sided,
@@ -660,16 +434,13 @@ pub fn zfill_material(
         ExtendedMaterial {
             base,
             extension: WowModelExt {
-                // Bit 10 (the twin-cutout marker) drives the shader's hard 224/255 cutout — set
-                // exactly when the colour pass discards, so depth and colour coverage agree.
                 clutter_fade: Vec4::new(
                     0.0,
                     0.0,
                     f32::from(ZFILL_MARKER | if cutout { TWIN_CUTOUT_MARKER } else { 0 }),
                     0.0,
                 ),
-                // Not a fade twin (`model_flags.y` = 0): the zfill pipeline branch forces its own
-                // depth-write, and the cutout rides bit 10 above, so the bit has no work here.
+                // `y` stays 0: the zfill pipeline forces its own depth write.
                 model_flags: Vec4::ZERO,
                 sun_scale: Vec4::new(ShadeSel::Lit.selector(), 0.0, 0.0, 0.0),
                 tint: Vec4::new(1.0, 1.0, 1.0, 0.0),
@@ -686,20 +457,12 @@ pub fn zfill_material(
     handle
 }
 
-/// `clutter_fade.z` marker bit 11: this material is a **far-side-of-water twin** ([`far_twin_of`])
-/// — the water-plane interleave's mesh lane ([`crate::sky_order::FAR_SIDE_BIAS`], where the byte
-/// story lives). `WowModelExt::specialize` keys on it to keep the huge negative SORT rung out of
-/// the rasterizer `DepthBiasState` (at −4e4 that constant is a ~0.5% relative depth pull — enough
-/// to clip a blade's coplanar sheen/glow layers behind the blade's own opaque depth).
+/// `clutter_fade.z` marker bit 11: a far-side-of-water twin, whose −4e4 sort rung `specialize`
+/// keeps out of the raster depth bias (a 0.5% pull that clips coplanar sheen layers).
 pub(crate) const FAR_SIDE_MARKER: u16 = 1 << 11;
 
-/// The far-side twin of one transparent model material: the same look, dropped one water rung —
-/// [`crate::sky_order::FAR_SIDE_BIAS`] under its authored sort slot — so the water surface paints
-/// over it, plus the [`FAR_SIDE_MARKER`] pipeline bit that keeps the rung sort-only. Pure, so the
-/// twin's shape is testable without an `Assets` store; the identity holds for every variant the
-/// swap can meet (steady blend, fade twin, zfill twin — their own marker bits ride along).
-/// `pub(crate)`: the pipeline warm pass ([`crate::pipe_warm`]) builds its far-side warm variants
-/// through this same builder, so the twin's key encoding can never drift from the swap's.
+/// A transparent material's far-side twin, one water rung down so the water paints over it; the
+/// app's pipeline warm pass builds through this too, so their keys cannot drift.
 pub fn far_twin_of(near: &WowModelMaterial) -> WowModelMaterial {
     let mut far = near.clone();
     far.base.depth_bias = far_sort_bias(far.base.depth_bias);
@@ -707,34 +470,22 @@ pub fn far_twin_of(near: &WowModelMaterial) -> WowModelMaterial {
     far
 }
 
-/// Fractional pull on every far-side sort slot, so the whole batch-eps band shares ONE pipeline
-/// key. Bevy folds `depth_bias as i32` into the material's pipeline key (0837's law): unpulled,
-/// a batch-order-0 twin lands exactly on `FAR_SIDE_BIAS` while its eps-nudged siblings land a
-/// fraction above — truncating to TWO key integers, i.e. two live pipeline compiles where the
-/// descriptors are identical (`specialize` zeroes the raster constant for far twins either way).
-/// Pulled by just under 1, every `near ∈ [0, 0.99]` twin truncates to the same integer. Sort-side
-/// it is a uniform shift of the whole band, so nothing reorders (the effect lane's far draws sit
-/// `rung ≥ 1` above, and the margin only grows).
+/// The pull on every far-side sort slot, so every `near` in `[0, 0.99]` truncates to one
+/// pipeline-key integer; a uniform shift, so nothing reorders.
 const FAR_KEY_PULL: f32 = 0.99;
 
-/// The twin's sort slot: one water rung under wherever the source sat (a zfill twin keeps its −8
-/// under the far batches it primes; a colour batch keeps its batch eps), less [`FAR_KEY_PULL`]
-/// so the eps band collapses onto one pipeline-key integer.
+/// The twin's sort slot: one water rung under the source's, less [`FAR_KEY_PULL`].
 fn far_sort_bias(near: f32) -> f32 {
     near + crate::sky_order::FAR_SIDE_BIAS - FAR_KEY_PULL
 }
 
-/// The twin's `clutter_fade.z` marker word: [`FAR_SIDE_MARKER`] added, every other pipeline
-/// marker preserved (a fade twin's cutout, a zfill twin's prime, the multiply blends and the fog
-/// policy all keep their identity on the far side of the plane).
+/// The twin's `clutter_fade.z` word: [`FAR_SIDE_MARKER`] added, every other marker kept.
 fn far_markers(z: f32) -> f32 {
     f32::from(z as u16 | FAR_SIDE_MARKER)
 }
 
-/// The far twins alive right now: near material id → far twin, and the far id → near handle
-/// restore path. Both handles are strong — a twin pair lives exactly as long as some batch entity
-/// still carries its near identity (the sweep at the tail of [`classify_water_side`]), the same
-/// entity-bound lifetime `FadeMaterials`' handles get from their component.
+/// The live far twins, by near id and back. The handles are strong: a pair lives until
+/// [`classify_water_side`]'s sweep finds no batch carrying its near identity.
 #[derive(Resource, Default)]
 pub struct FarSideTwins {
     to_far: std::collections::HashMap<AssetId<WowModelMaterial>, Handle<WowModelMaterial>>,
@@ -742,9 +493,7 @@ pub struct FarSideTwins {
 }
 
 impl FarSideTwins {
-    /// The far twin of `near`, if one is live — the read-only side every material-handle owner
-    /// composes with, safe from a parallel walk. A miss means [`classify_water_side`] hasn't
-    /// built it yet: the caller keeps the near handle and picks the twin up next frame.
+    /// The live far twin of `near`; a miss means it is not built yet, and the caller keeps `near`.
     pub(crate) fn far_of(
         &self,
         near: &Handle<WowModelMaterial>,
@@ -752,9 +501,7 @@ impl FarSideTwins {
         self.to_far.get(&near.id())
     }
 
-    /// The near identity of a far twin, if `id` is one — the mat-anim draw scan asks, because
-    /// its registry keys are always near ids while a far-classified instance carries the twin's
-    /// (1375).
+    /// The near identity of a far twin, for the mat-anim registry, which keys by near id.
     pub(crate) fn near_of(
         &self,
         id: AssetId<WowModelMaterial>,
@@ -763,14 +510,8 @@ impl FarSideTwins {
     }
 }
 
-/// The far-axis compose every material-handle OWNER applies at its own write site: the handle it
-/// wants, dropped one water rung when the entity is marked [`FarSideOfWater`]. This is what lets
-/// N legitimate writers (the fade resolve, the aura author, the self feather, the doodad-fade
-/// authority) and the classifier all converge on ONE handle per frame — each derives its pick
-/// from state and composes the same axis, so change-gates hold and nobody re-swaps what another
-/// just wrote (the first cut fought exactly that way, per frame, forever). A cutout/opaque pick
-/// composes to itself: far twins exist only for transparent-pass materials, so the lookup misses
-/// and the pick stands.
+/// The handle a material owner writes: its pick, or the pick's far twin on a [`FarSideOfWater`]
+/// entity, so every writer agrees on one handle per frame. An opaque pick has no twin and stands.
 pub fn far_resolved<'a>(
     want: &'a Handle<WowModelMaterial>,
     far: bool,
@@ -783,62 +524,21 @@ pub fn far_resolved<'a>(
     }
 }
 
-/// This batch entity's transparent draw is on the eye's FAR side of the water plane — written by
-/// [`classify_water_side`], sparse (present only while far). For entities whose material handle
-/// the Visibility authority owns (the `DoodadFade` holders it pins to cutout/blend every frame,
-/// decision 0025's one-authority law), the marker IS the classification: the authority composes
-/// it into its own pick via [`FarSideTwins::far_of`] instead of a second writer fighting it —
-/// the same compose-don't-overwrite shape the fade alpha itself takes through that system.
+/// This batch draws on the eye's far side of the water plane; for a `DoodadFade` holder the
+/// Visibility authority composes it into its own pick.
 #[derive(Component)]
 pub struct FarSideOfWater;
 
-/// Classify every transparent M2 batch against the water plane and swap it onto (or off) its
-/// far-side twin — the MESH half of the water-plane interleave (byte-VERIFIED, wow-re
-/// `water-frame-straddle.md`: the reference splits CM2Scene transparents into above/below-water
-/// lists per model and draws the eye's far side *before* the water pass; 0911 shipped the effect
-/// half and named this one — the sighting it predicted arrived as "the sword reads crisp through
-/// the surface": the blade's Mod2x sheen and glow overlays drew after the water, untinted).
-///
-/// The grain is the reference's: every batch entity of one model instance carries the instance's
-/// own transform (the mesh offsets live in vertex space), so classifying each at its
-/// `GlobalTransform` IS the per-model split — one liquid hit at the model's placement, all its
-/// batches on one list. A slot-bearing instance inside the reference's `±r` band is a
-/// **straddler** and takes BOTH lists: its batches stay near and gain a far twin, each clipped at
-/// the waterline (the reference's `M2UseClipPlanes`; decision 2188, [`crate::straddle`]).
-/// Slot-0 content keeps the one-list sign test. WMO translucents never classify (the reference's
-/// lists are CM2Scene's; the WMO leg draws its own), and opaque/cutout batches settle by depth
-/// like any world geometry.
-///
-/// **Two lanes, one classification.** Entities whose handle the Visibility authority owns — the
-/// `DoodadFade` holders `debug_panel::apply_model_visibility` pins to cutout/blend every frame —
-/// get the [`FarSideOfWater`] marker and a pre-built twin; the authority composes both into its
-/// own pick (decision 0025's one-authority law — the first cut swapped their handles from here
-/// and the two writers re-swapped the same 550 coastal doodads every frame, forever). Everything
-/// else (equipment, spell-fx attachments, entity fade twins) is swapped here directly, after the
-/// fade resolve, deriving near-vs-far from the CURRENT handle so an upstream overwrite is
-/// re-classified the same frame instead of fought over.
-///
-/// **Reactive, not per-frame** (decision 0930; 0922 named the lever). A batch's verdict is a
-/// function of its transform, its handle, its layers, its ancestors' room claim, the loaded
-/// surfaces, and the eye's side — so a *clean* batch is skipped, and only the changed set
-/// re-classifies (~2.6k of ~40k parts on a measured Stormwind frame; the full sweep cost 2.2 ms).
-/// The frame promotes to the full walk — byte-identical to the old per-frame behaviour — whenever
-/// a global term that changes VERDICTS moves: the eye crosses the surface (every verdict
-/// inverts) or surfaces stream in/out. A part *despawn* changes no live verdict — it only
-/// obligates the twin GC's exact mark eventually — so it schedules a full walk behind
-/// [`GC_DEADLINE_SECS`] instead of promoting the same frame (decision 1462: walking streams
-/// parts out on 12–22 frames/s, and each promotion was a full re-classify of every part —
-/// lane B of 1461's walking tax; between full frames a pair orphaned by a handle overwrite —
-/// a fade settling to its cutout — lingers harmlessly, kept fresh by the mirror above, until
-/// the next edge sweeps it, and a GC-due twin lingers the same way). The room-claim trigger
-/// fans DOWN: the claim lives on the unit root, the batches are its descendants, and a claim
-/// can change with the unit standing still (a building streaming in under it re-claims at the
-/// same spot).
-/// How long a despawn-obligated twin GC may wait for its full walk (1462). Bounds how long an
-/// orphaned twin pair can outlive its last user — a handful of small material clones — while a
-/// walking regime's continuous despawn stream costs ~0.5 full walks/s instead of 12–22.
+/// How long the twin GC may wait for a full walk after a part despawns: it bounds an orphaned
+/// pair's life while walking's steady despawns cost ~0.5 full walks/s.
 const GC_DEADLINE_SECS: f32 = 2.0;
 
+/// Swap each transparent M2 batch onto or off its far-side twin: the reference draws a model's
+/// transparents on the eye's far side before the water pass (`0x707680`), split per model, and
+/// every batch carries its model's transform. An instance inside the `±r` band draws on both
+/// sides, clipped at the waterline (`M2UseClipPlanes`, [`crate::straddle`]); WMO translucents
+/// never classify. Only changed batches re-classify; the eye crossing the surface or surfaces
+/// streaming walk them all.
 #[allow(clippy::type_complexity)]
 pub(crate) fn classify_water_side(
     interleave: crate::particles::WaterInterleave,
@@ -846,10 +546,7 @@ pub(crate) fn classify_water_side(
     mut materials: ResMut<Assets<WowModelMaterial>>,
     mut near_edits: MessageReader<AssetEvent<WowModelMaterial>>,
     mut commands: Commands,
-    // The material-handle leg needs a ParamSet: `Changed<MeshMaterial3d>` reads the same ticks
-    // the walk's `&mut` writes (Bevy B0001), so the dirty-entity list is collected from `p0`
-    // before `p1` is borrowed. The transform/layers legs read ticks the walk only reads, so they
-    // stay plain sibling queries.
+    // A ParamSet: the `Changed` query would conflict with the walk's `&mut`.
     mut set: ParamSet<(
         Query<
             Entity,
@@ -869,7 +566,7 @@ pub(crate) fn classify_water_side(
                 Option<&MeshTag>,
                 Has<crate::straddle::StraddlesWater>,
             ),
-            // A straddle twin is the classification's OUTPUT, never its input.
+            // A straddle twin is the classification's output, never its input.
             Without<crate::straddle::StraddleTwinOf>,
         >,
     )>,
@@ -884,8 +581,7 @@ pub(crate) fn classify_water_side(
         ),
     >,
     reclaimed: Query<Entity, Changed<crate::wmo_portal::UnitWmoRoom>>,
-    // The straddle verdict's edge (decision 2188): an instance entering or leaving its water band
-    // re-classifies its whole subtree — the same fan-down as the room claim.
+    // An instance entering or leaving its water band re-classifies its whole subtree.
     rebanded: Query<Entity, Changed<crate::straddle::ModelWaterBand>>,
     clips: Res<crate::straddle::WaterClips>,
     children: Query<&Children>,
@@ -894,11 +590,8 @@ pub(crate) fn classify_water_side(
     mut eye_was_submerged: Local<Option<bool>>,
     mut gc_due: Local<Option<f32>>,
 ) {
-    // Mirror any near-asset edit into the live twin. Since decision 1381 the texanim/tint lane
-    // animates through the shared table (the twin's clone carries the same slot and seed, so it
-    // scrolls in phase with no mirror needed), which leaves this listener idle in the steady
-    // state — it now catches only genuine one-off near edits (a debug repaint, a future lane).
-    // Our own twin writes touch only far ids (never `to_far` keys), so this can't feed back.
+    // Mirror a near-asset edit into its live twin. Animation needs none (the twin's clone shares
+    // the table slot), and twin writes touch only far ids, so this cannot feed back.
     let edited: Vec<AssetId<WowModelMaterial>> = near_edits
         .read()
         .filter_map(|ev| match ev {
@@ -909,7 +602,7 @@ pub(crate) fn classify_water_side(
     for id in edited {
         if let (Some(near), Some(far)) = (materials.get(id).cloned(), twins.to_far.get(&id)) {
             let far = far.id();
-            // Can't fail: `to_far` holds the twin's strong handle, so its slot is live.
+            // Cannot fail: `to_far` holds the twin's strong handle.
             materials
                 .insert(far, far_twin_of(&near))
                 .expect("far twin slot is strongly held");
@@ -917,9 +610,8 @@ pub(crate) fn classify_water_side(
     }
     let eye = interleave.eye_submerged();
     let now = time.elapsed_secs();
-    // `last()` drains the reader — `next()` would leave the tail readable and re-arm NEXT frame
-    // as a spurious second deadline. The earliest despawn holds the deadline (`get_or_insert`):
-    // a steady despawn stream must not push the GC out forever.
+    // `last()` drains the reader (`next()` would re-arm next frame), and the earliest despawn
+    // holds the deadline, so a steady stream cannot push the GC out forever.
     if removed.read().last().is_some() {
         gc_due.get_or_insert(now + GC_DEADLINE_SECS);
     }
@@ -928,13 +620,11 @@ pub(crate) fn classify_water_side(
         || gc_due.is_some_and(|due| now >= due);
     *eye_was_submerged = Some(eye);
     if full {
-        // Any full walk runs the GC's exact mark, whatever triggered it — a pending deadline
-        // is satisfied, not merely postponed.
+        // Any full walk runs the GC's mark, which satisfies a pending deadline.
         *gc_due = None;
     }
 
     if full {
-        // The full walk — every part, plus the twin GC's exact mark-and-sweep.
         let mut used: std::collections::HashSet<AssetId<WowModelMaterial>> =
             std::collections::HashSet::new();
         for item in set.p1().iter_mut() {
@@ -948,9 +638,7 @@ pub(crate) fn classify_water_side(
                 item,
             );
         }
-        // Drop twin pairs whose near identity no live batch carries any more — the twin dies
-        // with its users. A respawned model refetches its near handle from its spawner's cache
-        // and the pair rebuilds lazily on the next far classification.
+        // Drop pairs whose near identity no live batch carries; a respawn rebuilds its pair lazily.
         if !twins.to_far.is_empty() {
             let stale: Vec<AssetId<WowModelMaterial>> = twins
                 .to_far
@@ -965,10 +653,7 @@ pub(crate) fn classify_water_side(
             }
         }
     } else {
-        // The reactive frame: only the changed set. `p0` collects first — the ParamSet frees it
-        // before `p1` — then the transform/layers leg and the room-claim fan-out come straight
-        // off their filters. An entity dirty on two legs classifies twice; the second pass
-        // no-ops (`far == far_now`).
+        // Only the changed set; an entity dirty on two legs classifies twice, the second a no-op.
         let handle_dirty: Vec<Entity> = set.p0().iter().collect();
         let mut parts = set.p1();
         for e in moved.iter().chain(handle_dirty) {
@@ -984,9 +669,8 @@ pub(crate) fn classify_water_side(
                 );
             }
         }
-        // A changed claim — or a changed straddle band (2188) — re-classifies the holder's whole
-        // subtree: both live on the unit root, the batches are its descendants (a nested holder
-        // shadows for its own subtree; re-classifying it from here anyway is idempotent).
+        // A changed room claim or straddle band re-classifies the holder's subtree: both live on
+        // the unit root, above its batches, and a claim can change with the unit standing still.
         let mut stack: Vec<Entity> = reclaimed.iter().chain(rebanded.iter()).collect();
         while let Some(e) = stack.pop() {
             if let Ok(ch) = children.get(e) {
@@ -1007,10 +691,8 @@ pub(crate) fn classify_water_side(
     }
 }
 
-/// One transparent-candidate batch as [`classify_part`] sees it: the entity, its transform, its
-/// layers, its handle (the channel this lane may swap), whether the Visibility authority owns
-/// that handle, whether it is marked far, its tag (the instance slot the straddle verdict is
-/// keyed on), and whether it is marked straddling.
+/// One candidate batch for [`classify_part`]: entity, transform, layers, handle, whether the
+/// Visibility authority owns the handle, marked far, tag (the straddle slot), marked straddling.
 type PartItem<'a> = (
     Entity,
     &'a GlobalTransform,
@@ -1022,9 +704,8 @@ type PartItem<'a> = (
     bool,
 );
 
-/// One batch entity's classification — the shared body of [`classify_water_side`]'s full and
-/// reactive paths. `used` collects the near identities live batches carry (the twin GC's mark);
-/// the reactive path passes `None` and leaves the sweep to the next full frame.
+/// Classify one batch. `used` collects the live near identities for the twin GC's mark; the
+/// reactive path passes `None`.
 fn classify_part(
     interleave: &crate::particles::WaterInterleave,
     clips: &crate::straddle::WaterClips,
@@ -1035,8 +716,7 @@ fn classify_part(
     (entity, gt, layers, mut mat, authority_owned, marked, tag, straddling): PartItem<'_>,
 ) {
     use bevy::camera::visibility::RenderLayers;
-    // A booth-layered batch belongs to its own camera and scene — no world water applies
-    // (the effect lane's own booth guard, `particles::sim`).
+    // A booth-layered batch has its own camera and scene, with no world water.
     if layers.is_some_and(|l| !l.intersects(&RenderLayers::default())) {
         return;
     }
@@ -1045,24 +725,19 @@ fn classify_part(
         Some(n) => (n.clone(), true),
         None => (mat.0.clone(), false),
     };
-    // This lane's current verdict: the marker (what every composing owner reads); the raw
-    // handle state seconds it for the lanes this system swaps itself.
+    // The current verdict: the marker, or the handle for the batches this system swaps itself.
     let far_now = marked || swapped;
     let qualifies = match materials.get(near.id()) {
         Some(m) => {
             matches!(m.base.alpha_mode, AlphaMode::Blend)
                 && m.extension.model_flags.x <= 0.5
-                // A WMO skybox is anchored at the eye and forces the far depth: it has no side of
-                // the water plane to be on, and the far twin's −4e4 would sink its own sort rung
-                // into the world band. The sky is never part of the interleave.
+                // A WMO skybox sits at the eye and the far depth, on no side of the water plane.
                 && (m.extension.clutter_fade.z as u16) & SKY_DEPTH_MARKER == 0
         }
         None => false,
     };
     if !qualifies {
-        // A marked part that settled back onto its opaque cutout (fade over, aura released)
-        // stops being a transparent draw at all — its side is nobody's business until it
-        // feathers again, and a doubled one stops being doubled.
+        // A part back on its opaque cutout has no side until it blends again.
         if marked {
             commands.entity(entity).remove::<FarSideOfWater>();
         }
@@ -1076,11 +751,8 @@ fn classify_part(
     if let Some(used) = used {
         used.insert(near.id());
     }
-    // **The straddle split** (decision 2188, [`crate::straddle`]): an instance inside its water
-    // band draws on BOTH lists. This batch keeps its NEAR identity — the fragment clips it to the
-    // eye's half — and `sync_straddle_twins` hangs its far twin beside it, clipped to the other.
-    // The verdict is the per-slot word the clip itself reads, so a batch is doubled exactly when
-    // its fragments are halved.
+    // A straddler keeps its near identity, clipped to the eye's half, and `sync_straddle_twins`
+    // hangs its far twin beside it; the verdict is the word the clip itself reads.
     let straddles = tag.is_some_and(|t| clips.straddles(crate::mesh_tag::rig_of(t.0)));
     if straddles != straddling {
         trace_side(
@@ -1099,7 +771,7 @@ fn classify_part(
         }
     }
     if straddles {
-        // Built here, where the store is writable — the twin sync only reads the map.
+        // Built here, where the store is writable; the twin sync only reads the map.
         far_twin(twins, materials, &near);
     }
     let far = !straddles
@@ -1107,13 +779,9 @@ fn classify_part(
     if far == far_now {
         return;
     }
-    // The swap's own trace (`WOW_MOVE_TRACE_TAGS=fx`): which batches crossed the plane this
-    // frame and which way — the numeric read for a sort question no pixel can answer, and
-    // naturally sparse (transitions only, never per-frame spam).
     trace_side(if far { "far-side" } else { "near-side" }, entity, gt);
     if far {
-        // Build (or fetch) the twin either way — every composing owner needs it live in the
-        // map before its own pick can resolve it.
+        // Built for an authority-owned batch too: its owner's pick resolves through the map.
         let far_h = far_twin(twins, materials, &near);
         commands.entity(entity).insert(FarSideOfWater);
         if !authority_owned {
@@ -1127,8 +795,7 @@ fn classify_part(
     }
 }
 
-/// The far twin of `near`, built on first ask. `near` must be a live asset — every caller has
-/// just proved it through the classifier's `qualifies`.
+/// The far twin of `near`, built on first ask; `near` must be live, as `qualifies` proved.
 fn far_twin(
     twins: &mut FarSideTwins,
     materials: &mut Assets<WowModelMaterial>,
@@ -1144,8 +811,7 @@ fn far_twin(
     h
 }
 
-/// `WOW_MOVE_TRACE_TAGS=fx`: one line per side transition of one batch — `far-side`/`near-side`
-/// for the one-list law, `straddle`/`unstraddle` for the two-list band.
+/// `WOW_MOVE_TRACE_TAGS=fx`: one line per side transition of one batch.
 fn trace_side(what: &str, entity: Entity, gt: &GlobalTransform) {
     if !benilla_assets::trace::enabled() {
         return;
@@ -1160,33 +826,17 @@ fn trace_side(what: &str, entity: Entity, gt: &GlobalTransform) {
     );
 }
 
-/// Replace the fog-policy bits (4-6) inside a packed `clutter_fade.z` marker word, preserving
-/// every other pipeline marker — bits 0-3 AND the Mod/Mod2x multiply markers in bits 7-8
-/// (decision 0528). The mask lives here, beside the packer above: the portrait booth's rig twin
-/// once truncated the word to `u8` and hand-masked `& 0x0f`, silently dropping the multiply
-/// markers — the char-select white-blade regression.
+/// Replace the fog-policy bits (4-6) of a packed `clutter_fade.z` word, keeping every other
+/// marker; the mask lives beside the packer so no caller masks the word by hand.
 pub fn replace_fog_policy(z: f32, policy: benilla_formats::FogPolicy) -> f32 {
     f32::from((z as u16 & !(7 << 4)) | ((policy as u16) << 4))
 }
 
-/// The model-render lane's own registrations (decision 1163, stage zero).
-///
-/// `FarSideTwins` is engine state in an engine module, and it was initialised by `EntitiesPlugin`
-/// purely because `model_render` had no plugin to put it in — which is how the world viewer's very
-/// first survey run found the model-`Visibility` authority reading a resource that did not exist.
+/// The model-render lane's registrations.
 pub fn plugin(app: &mut App) {
-    // The water-plane interleave's MESH half (the sibling of the effect half in `particles::sim`):
-    // every transparent M2 batch classifies against the water plane and takes its far-side twin, so
-    // the surface paints over a submerged model's sheen/glow layers. Two lanes: entities whose
-    // handle the Visibility authority owns (the `DoodadFade` holders it pins every frame, decision
-    // 0025) get a MARKER the authority composes into its own pick — so classify runs before
-    // `ModelVisSet`, and the pick sees this frame's side; everything else (equipment, spell-fx,
-    // fade twins) is swapped here directly, after the fade resolve whose choice it re-derives from
-    // the current handle. The self feather stays deliberately unordered: it composes the same
-    // marker through `far_resolved`, so the two writers can only disagree on a frame the marker
-    // itself flips — a one-frame stale side on the player's own parts at the instant the eye
-    // crosses the surface, inside the whole-screen atmosphere swap that crossing already is (the
-    // same accepted class as the interior law's one-frame lag, 0919).
+    // Before `ModelVisSet`, so the authority's pick sees this frame's side, and after the fade
+    // resolve. The self feather is unordered: it composes the same marker and can lag one frame
+    // as the eye crosses the surface.
     app.init_resource::<FarSideTwins>().add_systems(
         Update,
         classify_water_side
@@ -1194,19 +844,14 @@ pub fn plugin(app: &mut App) {
             .after(crate::model_fade::apply_render_fade)
             .before(crate::model_render::ModelVisSet),
     );
-    // **The model-`Visibility` authority** (decision 0025's one-writer law), which lived in
-    // `debug_panel` because the panel's toggles were its first input and now lives with the lane
-    // it is the authority *for*. `apply_model_visibility` reads the WMO portal PVS, so it runs
-    // after the compute that fills it.
+    // The model-`Visibility` authority, the one writer, after the portal PVS it reads.
     app.add_systems(
         Update,
         visibility::apply_model_visibility
             .after(crate::wmo_portal::WmoPvsSet)
             .in_set(ModelVisSet),
     );
-    // `WOW_VIS_TRACE=<label>`: watch one model's placements decide (see `visibility::VisTrace`).
-    // The resource is absent unless the env var names something, and the system's first line is
-    // the `None` check — so an ordinary run pays one `Option` read per frame.
+    // `WOW_VIS_TRACE=<label>` traces one model's placements.
     if let Some(trace) = visibility::VisTrace::from_env() {
         app.insert_resource(trace);
     }
@@ -1214,40 +859,29 @@ pub fn plugin(app: &mut App) {
         Update,
         visibility::trace_model_visibility.after(ModelVisSet),
     );
-    // The material dedup cache and its two evictors — the soft one (distance, decision 0785) and
-    // the hard one (a cross-map transition, decision 0729). Both used to live in `entities`, which
-    // owned the cache because the entity spawner was the first lane to want one; the glue booth
-    // and the portrait bake each kept a `Local` that nothing ever swept, which is exactly the
-    // unbounded residency `art_scope` was written to end.
+    // The material dedup cache and its evictors: by distance, and whole on a cross-map transition.
     app.init_resource::<ModelMaterials>()
         .add_systems(Update, (scope_model_materials, evict_model_materials));
-    // Deferred realization (`lazy`): a built material becomes an asset the frame something
-    // visible binds it. The top of `PostUpdate` — `Assets::insert` only QUEUES its
-    // `AssetEvent::Added`, so the sweep has to land before the store publishes
-    // (`AssetEventSystems`) or the bound entity loses a frame of drawing, and before
-    // `VisibilityPropagate` clears the view-visibility bits it reads. Both bounds and why they
-    // are the only two available: `lazy`'s module doc.
+    // A material becomes an asset the frame something visible binds it: before the store
+    // publishes its queued `Added` event and before `VisibilityPropagate` clears what it reads.
     app.add_systems(
         PostUpdate,
         lazy::realize_bound
             .before(bevy::asset::AssetEventSystems)
             .before(bevy::camera::visibility::VisibilitySystems::VisibilityPropagate),
     );
-    // Parking (`park`): a long-hidden streamed part puts its `Mesh3d` down. `Update`, after the
-    // authority, on last frame's propagated verdict — the order the module doc explains.
+    // A long-hidden streamed part puts its `Mesh3d` down, on last frame's propagated verdict.
     if park::enabled() {
         app.add_systems(Update, park::park_hidden_parts.after(ModelVisSet));
     }
 }
 
-/// Expire the material dedup by **distance** (decision 0785).
+/// Expire the material dedup by distance.
 fn scope_model_materials(mut scope: crate::art_scope::ArtScope, mut mats: ResMut<ModelMaterials>) {
     scope.apply(&mut mats.0, crate::art_scope::ArtSlot::ModelMats);
 }
 
-/// …and drop it whole on a cross-map transition (decision 0729 — see `MapChange` for why a clear
-/// is always safe mid-session). Every entry is get-or-insert at its use site, so a cleared one
-/// rebuilds on the next spawn that wants it.
+/// Drop the material dedup whole on a cross-map transition; entries rebuild on demand.
 fn evict_model_materials(
     mut changes: MessageReader<crate::world_map::MapChange>,
     mut mats: ResMut<ModelMaterials>,
@@ -1260,8 +894,7 @@ fn evict_model_materials(
     mats.0.clear();
 }
 
-/// Column order for the four [`ModelKind`]s wherever one is used as an index — the panel's
-/// toggles, its per-kind counts. `ModelKind`'s own index is private; this is the shared one.
+/// The index of a [`ModelKind`] in the panel's toggles and per-kind counts.
 pub fn kind_index(kind: ModelKind) -> usize {
     match kind {
         ModelKind::Doodad => 0,
@@ -1271,7 +904,7 @@ pub fn kind_index(kind: ModelKind) -> usize {
     }
 }
 
-/// Column order for the five [`ModelBlend`] layers — same role as [`kind_index`].
+/// The index of a [`ModelBlend`] layer, as [`kind_index`] is for kinds.
 pub fn blend_index(b: ModelBlend) -> usize {
     match b {
         ModelBlend::Opaque => 0,
@@ -1282,8 +915,7 @@ pub fn blend_index(b: ModelBlend) -> usize {
     }
 }
 
-/// Which world-model subsystem a spawned submesh belongs to — lets the panel scope toggles (e.g.
-/// hide doodads without touching NPCs).
+/// The world-model subsystem a spawned submesh belongs to, which the panel's toggles scope by.
 #[derive(Component, Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum ModelKind {
     Doodad,
@@ -1292,8 +924,7 @@ pub enum ModelKind {
     GameObject,
 }
 
-/// Tags every spawned model submesh with the metadata the panel toggles on: its subsystem and its
-/// blend mode (the "layer" — opaque trunk vs alpha-cut canopy).
+/// A spawned model submesh's subsystem and blend layer, which the panel toggles on.
 #[derive(Component, Clone, Copy)]
 #[require(ShadowOccluder)]
 pub struct ModelPart {
@@ -1327,8 +958,7 @@ impl Default for ShadowOccluder {
 #[derive(Component, Clone, Copy)]
 pub struct EntityPathWhy(pub &'static str);
 
-/// Ordering handle so the one system allowed to *override* the model-`Visibility` authority — the
-/// self-avatar first-person hide ([`crate::player`]) — can run **after** it and win the frame.
+/// The model-`Visibility` authority's set; the first-person self hide runs after it and wins.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct ModelVisSet;
 
@@ -1337,33 +967,22 @@ mod tests {
     use super::replace_fog_policy;
     use benilla_formats::FogPolicy;
 
-    /// Swapping the fog policy must preserve EVERY pipeline marker bit — 0-3 and the 0528
-    /// multiply markers in 7-8. The portrait booth's old hand-rolled `as u8 & 0x0f` dropped
-    /// bits 7-8 (the char-select white-blade regression this pins against).
     #[test]
     fn replace_fog_policy_preserves_pipeline_markers() {
-        // All marker bits set (0-3, 7-8) + fog policy Grey (3) in bits 4-6.
+        // Every marker bit (0-3, 7-8) set, fog policy Grey (3) in bits 4-6.
         let z = f32::from(0b1_1000_1111u16 | (3 << 4));
         let out = replace_fog_policy(z, FogPolicy::Off) as u16;
         assert_eq!(out & 0b1_1000_1111, 0b1_1000_1111, "markers preserved");
         assert_eq!((out >> 4) & 7, FogPolicy::Off as u16, "fog swapped");
-        // And the reverse direction: no stray bits invented.
+        // No stray bits invented.
         let out2 = replace_fog_policy(f32::from(0u16), FogPolicy::Grey) as u16;
         assert_eq!(out2, (FogPolicy::Grey as u16) << 4);
     }
 
-    /// The authored-batch-order sort epsilon sits in its working band: any realistic model's
-    /// last batch still biases UNDER the effect lane's owner-last rung floor (an item's glow
-    /// particles must draw after every batch of the item — 0719/0721), and one step is far above
-    /// f32 noise on a far-scene sort distance (~4e-5 at 500 yd), so the tie actually breaks.
-    /// Pins the constant against a careless resize in either direction — either end failing is
-    /// the Naxx-item strobe (coplanar layers re-flipping a sort tie every frame) or its dual
-    /// (effects interleaving into their owner's batches).
+    /// Too small and coplanar layers strobe; too large and effects interleave into their owner.
     #[test]
     fn batch_order_sort_eps_sits_between_f32_noise_and_the_effect_rung() {
-        // The CAPPED product is the deepest any batch can bias — "512 is past any shipped
-        // model" was this test's original premise, and Stormwind's root batch tables disproved
-        // it (indices past 2000; the 0938-tail live compiles at biases 1 and 2).
+        // The capped product is the deepest any batch can bias; WMO roots index past 2000.
         let deepest =
             (super::BATCH_ORDER_SORT_EPS * f32::from(u16::MAX)).min(super::BATCH_ORDER_SORT_CAP);
         assert!(
@@ -1375,12 +994,11 @@ mod tests {
             super::BATCH_ORDER_SORT_EPS > 8.0 * far_noise,
             "one order step must dominate f32 noise on a far sort distance"
         );
-        // Bevy's pipeline key truncates the WHOLE band to 0 — no batch index may mint a
-        // pipeline (0837, re-learned in 0938's tail): the cap holds for any u16.
+        // The pipeline key truncates the whole band to 0 for any u16 index.
         assert_eq!(deepest as i32, 0);
         const {
             assert!(super::BATCH_ORDER_SORT_CAP < 1.0);
-            // A capped batch's far twin still truncates onto the far band's ONE key integer.
+            // A capped batch's far twin still truncates onto the far band's one key integer.
             assert!(super::BATCH_ORDER_SORT_CAP < super::FAR_KEY_PULL);
         }
         assert_eq!(
@@ -1390,17 +1008,12 @@ mod tests {
         );
     }
 
-    /// The **WMO-skybox band**: the four properties the lane's whole ordering rests on, none of
-    /// which survives being reasoned about in prose (decision 1264). The band is arithmetic at a
-    /// magnitude where f32 stops being able to represent the steps, which is exactly how the
-    /// ordinary eps would have failed here in silence.
     #[test]
     fn the_skybox_band_orders_its_batches_on_one_pipeline_key() {
         // `CavernsOfTimeSky.m2` is 21 batches; `order` is the index + 1.
         let band: Vec<f32> = (0..=21).map(super::skybox_sort_bias).collect();
 
-        // 1. STRICTLY INCREASING — the whole point. At −6e4 the ordinary 1e-3 eps rounds every
-        //    one of these onto the same f32 and the sort tie the eps exists to break comes back.
+        // 1. Strictly increasing: at −6e4 the ordinary 1e-3 eps would round onto one f32.
         for pair in band.windows(2) {
             assert!(
                 pair[1] > pair[0],
@@ -1409,9 +1022,8 @@ mod tests {
             );
         }
 
-        // 2. ONE PIPELINE KEY for the whole band (0837's law: `StandardMaterialKey` packs
-        //    `depth_bias as i32`, so a band straddling an integer is a live compile per side).
-        //    Checked for ANY u16 order, not just the 21 real ones — the cap is what holds it.
+        // 2. One pipeline key for the whole band (`depth_bias as i32` is a key axis), for any
+        //    u16 order: the cap holds it.
         let key = band[0] as i32;
         for order in [0u16, 1, 21, 57, 58, 1000, u16::MAX] {
             assert_eq!(
@@ -1421,10 +1033,8 @@ mod tests {
             );
         }
 
-        // 3. UNDER EVERY WORLD TRANSPARENT. The deepest a world draw can sort is the far-side
-        //    water rung plus a far-plane view-z; the skybox's own camera-anchored view-z (its
-        //    shell radius, ~94 yd for Caverns of Time) rides on top of the rung and must not
-        //    close the gap.
+        // 3. Under every world transparent, even with the skybox's shell radius (~94 yd for
+        //    Caverns of Time) on its rung and a world draw at the far plane.
         const FAR_PLANE: f32 = 3000.0;
         const SHELL: f32 = 128.0;
         let deepest_world = crate::sky_order::FAR_SIDE_BIAS - FAR_PLANE - super::FAR_KEY_PULL;
@@ -1434,18 +1044,12 @@ mod tests {
              over it (sky_order::WMO_SKYBOX_BIAS)"
         );
 
-        // 4. The rung is the SMALLEST job it can be, per `sky_order`'s "as small as its ordering
-        //    job allows": a magnitude an order over the world band is margin, two is drift.
+        // 4. The rung stays within ten times the world band: margin, not drift.
         const {
             assert!(crate::sky_order::WMO_SKYBOX_BIAS > 10.0 * crate::sky_order::FAR_SIDE_BIAS);
         }
     }
 
-    /// The far-side twin is its source shifted exactly one water rung with the marker bit added —
-    /// and every OTHER marker bit rides along untouched (a fade twin's cutout, a zfill twin's
-    /// prime, the multiply blends and the fog policy all keep their pipeline identity on the far
-    /// side of the plane). The band stays coherent: a far zfill twin still primes before the far
-    /// colour batches it serves, and the deepest batch eps still clears the water rung's margin.
     #[test]
     fn far_twin_keeps_the_source_identity_one_rung_down() {
         assert_eq!(
@@ -1458,9 +1062,8 @@ mod tests {
                 < super::far_sort_bias(super::BATCH_ORDER_SORT_EPS * 512.0),
             "a far zfill twin still primes before its model's far colour batches"
         );
-        // The pull's whole point: the entire batch-eps band truncates to ONE pipeline-key
-        // integer (0837's law — `depth_bias as i32` is a key axis), and the zfill twin keeps
-        // its own single key one bracket down.
+        // The whole batch-eps band truncates to one pipeline-key integer; the zfill twin keeps
+        // its own one bracket down.
         assert_eq!(
             super::far_sort_bias(0.0) as i32,
             super::far_sort_bias(super::BATCH_ORDER_SORT_EPS * 512.0) as i32,
@@ -1482,8 +1085,7 @@ mod tests {
             src,
             "every other marker preserved"
         );
-        // The marker word stays f32-exact with every bit up to FAR_SIDE set (integers ≤ 2^12
-        // are exact in f32 — the packing's soundness bound).
+        // The marker word stays f32-exact with every bit up to `FAR_SIDE_MARKER` set.
         let all = src | super::FAR_SIDE_MARKER | 0x0f;
         assert_eq!(f32::from(all) as u16, all);
     }
diff --git a/crates/benilla-world/src/model_render/batch.rs b/crates/benilla-world/src/model_render/batch.rs
index 817bc060..9adc718e 100644
--- a/crates/benilla-world/src/model_render/batch.rs
+++ b/crates/benilla-world/src/model_render/batch.rs
@@ -1,24 +1,7 @@
-//! [`M2BatchMaterials`] — one authored batch's material identity, built in one place.
-//!
-//! An authored render batch ([`ModelSubmesh`]) already *carries* almost its whole material
-//! identity: texture, blend, sidedness, the M2 render flags (`0x04`/`0x08`/`0x10`), the fog
-//! policy, the generated-texcoord bit, the WMO MOMT law (MOBA class, SIDN, WINDOW). The only
-//! things a spawner chooses are which light lane the batch draws on and how many *variants* of it
-//! the lane needs. Everything else is read off the batch here — which is why the twenty-argument
-//! builder ([`super::model_material`]) has exactly two callers left outside this file, both of
-//! them the engine's own streamer and pipeline-warmer.
-//!
-//! **The variant set is the point.** One authored submesh renders as up to six deduped handles —
-//! steady, interior-matte, interior-bake, the bake's blend twin, the appear/distance-fade blend
-//! twin, and the depth-prime twin — and the law that decides which of them collapse onto each
-//! other (a multiply batch cannot feather through alpha; an authored-Blend batch already is its
-//! own twin; a `no_depth_write` batch primes nothing) is one law, recorded across decisions 0842,
-//! 0865, 0831 and 0355. It was written out by hand at seven spawn sites before this facade, each
-//! copy free to drift from the others.
-//!
-//! The dedup cache is one cache ([`ModelMaterials`]). It keys on the full material identity, so
-//! two lanes that build the same batch the same way get the same handle — which is the whole
-//! reason the cache exists, and was true of four separate caches only by luck.
+//! [`M2BatchMaterials`]: the materials an authored render batch ([`ModelSubmesh`]) draws with,
+//! read off the batch; a spawner picks only the light lane and the variants. A multiply batch
+//! cannot feather through alpha, an authored-Blend batch is its own twin, and a batch that writes
+//! no depth primes nothing.
 
 use benilla_assets::materials::{TorchBinds, WowModelMaterial};
 use benilla_assets::ModelSubmesh;
@@ -31,66 +14,48 @@ use super::{model_material, zfill_material, MaterialCache, ShadeSel};
 use crate::lighting::SharedLightBuffer;
 use crate::static_gx::TorchShared;
 
-/// The engine's one `WowModelMaterial` dedup cache. Swept by distance like every other art cache
-/// (`art_scope`) and cleared whole on a map change; an evicted entry costs one rebuild, never a
-/// wrong material, because [`super::MatKey`] determines the material completely.
+/// The engine's one `WowModelMaterial` dedup cache, swept by distance and cleared on a map change;
+/// an evicted entry costs a rebuild, never a wrong material, as [`super::MatKey`] is complete.
 #[derive(Resource, Default)]
 pub struct ModelMaterials(pub(crate) MaterialCache);
 
-/// The deduped handles one authored batch renders as. Field-accessed, never named by a caller:
-/// which of these a lane actually spawns is the lane's business, but *building* them is not.
+/// The deduped handles one authored batch renders as; a lane spawns the ones it needs.
 pub struct BatchVariants {
-    /// The steady exterior look — sky-lit, the material an instance draws with almost always.
+    /// The steady exterior material, sky-lit.
     pub steady: Handle<WowModelMaterial>,
-    /// The interior MATTE variant: the plain day/night pair at sun ×1.0 — the reference's
-    /// null-node fallback, taken when the footprint probe misses.
+    /// Interior matte: day/night at sun ×1.0, the reference's null-node fallback.
     pub interior: Handle<WowModelMaterial>,
-    /// The interior BAKE variant: interior-PROP mode, the shader evaluating the model's SH probe
-    /// by its `MeshTag` slot — the steady indoor law for every entity M2.
+    /// Interior bake: the model's SH probe by its `MeshTag` slot, every entity M2's indoor look.
     pub interior_bake: Handle<WowModelMaterial>,
-    /// The bake lane's blend twin — the probe-lit feather (decision 0355). Without it a fade
-    /// indoors swaps to the EXTERIOR twin and the light jumps mid-feather.
+    /// The bake's blend twin, so a fade indoors stays probe-lit.
     pub interior_bake_blend: Handle<WowModelMaterial>,
-    /// The `AlphaMode::Blend` twin every feather pass rides (spawn appear-fade, distance fade,
-    /// aura fades). Equal to [`Self::steady`] when the steady material already blends.
+    /// The `AlphaMode::Blend` twin every feather rides; [`Self::steady`] if that already blends.
     pub fade_blend: Handle<WowModelMaterial>,
-    /// The depth-prime twin (`m2-blend-promotion-zfill.md` §4). `None` for a batch that writes no
-    /// depth to prime — one that disables depth write/test, or a multiply batch.
+    /// The depth-prime twin (`0x707f7d`); `None` for a multiply batch or depth write/test off.
     pub zfill: Option<Handle<WowModelMaterial>>,
 }
 
-/// The **UV lane** an [`M2BatchMaterials::entity_variants`] call registers into (decision 2295) —
-/// the animated-material registry, the delta table (decision 1381) and, for the one measured class
-/// that needs it, the instance the materials belong to.
-///
-/// A bundle rather than three arguments because they are one thing — *where this batch's texture
-/// transform is delivered* — and because the shape that keeps failing on this lane is a caller who
-/// takes some of the pieces and not the rest.
+/// Where [`M2BatchMaterials::entity_variants`] registers a batch's texture transform: the
+/// animated-material registry, the delta table and, when it has one, the owning instance.
 pub struct EntityUvLane<'a> {
     pub reg: &'a mut crate::doodad_anim::UvAnimMaterials,
     pub table: &'a mut crate::mat_anim_table::MatAnimTable,
-    /// `Some` when these materials belong to ONE instance rather than to the batch — the clone a
-    /// spawner makes for a GameObject whose file-sequence slots bake different loops (1408's
-    /// population, reached from the entity side by 2295). `None` — the overwhelming majority — is
-    /// the shared, deduped material every instance of the batch draws through.
+    /// `Some` when the materials belong to one instance (a GameObject whose sequence slots bake
+    /// different loops); `None` is the shared material every instance of the batch draws through.
     pub instance: Option<Entity>,
 }
 
-/// The pair one skybox batch draws with ([`M2BatchMaterials::skybox`]): the authored blend at full
-/// weight, and the promoted SRC_ALPHA twin the 4-second crossfade rides (equal to `steady` when the
-/// authored blend already blends).
+/// One skybox batch's pair ([`M2BatchMaterials::skybox`]): the authored blend at full weight, and
+/// the SRC_ALPHA twin the 4-second crossfade rides.
 pub struct SkyboxBatch {
-    /// The batch at slot weight 1.0 — its authored blend mode, the material it has always had.
+    /// Slot weight 1.0: the authored blend mode.
     pub steady: Handle<WowModelMaterial>,
-    /// The blend-promotion twin for `0 < weight < 1` (wow-re `m2-blend-promotion-zfill.md`).
+    /// The blend-promotion twin for `0 < weight < 1` (`0x70c190`).
     pub fade_blend: Handle<WowModelMaterial>,
 }
 
-/// Build the material(s) an authored render batch draws with.
-///
-/// Every method returns `None` until the shared light buffer exists (it is created at startup in
-/// the render world's shadow; a spawner that runs before it must retry, not bake a material
-/// against nothing). [`Self::ready`] is the same question asked without building anything.
+/// Builds the materials an authored render batch draws with. Every method that needs the shared
+/// light buffer returns `None` until it exists; a spawner that runs earlier retries.
 #[derive(SystemParam)]
 pub struct M2BatchMaterials<'w> {
     cache: ResMut<'w, ModelMaterials>,
@@ -108,20 +73,15 @@ impl M2BatchMaterials<'_> {
         self.light.is_some() && self.torch.binds().is_some()
     }
 
-    /// The material store this param already holds — for a spawner that builds a batch's world
-    /// material here and then clones it against a light buffer of its own (the UI model tiles'
-    /// twin, decision 2013). Taking a second `ResMut<Assets<WowModelMaterial>>` beside this
-    /// param is a schedule-time conflict (B0002), which is why the store is reached through it.
+    /// The material store this param holds: a second `ResMut<Assets<WowModelMaterial>>` beside it
+    /// would be a Bevy system-param conflict.
     pub fn materials(&mut self) -> &mut Assets<WowModelMaterial> {
         &mut self.materials
     }
 
-    /// One steady material for an authored batch drawn in the world on the sky lane.
-    ///
-    /// `order` is the authored batch index + 1 (`0` = unordered), the transparent-pass sort bias
-    /// that keeps one model's coplanar layers in file order ([`super::BATCH_ORDER_SORT_EPS`]).
-    /// A WMO group batch takes the FFP N·L lane ([`ShadeSel::Matte`]) rather than the M2 lobe —
-    /// that is a property of the batch, not a caller's choice, so it is read off the batch here.
+    /// One steady, sky-lit material for a batch drawn in the world. `order` is the authored batch
+    /// index + 1 (`0` = unordered), the sort bias that keeps a model's coplanar layers in file
+    /// order ([`super::BATCH_ORDER_SORT_EPS`]).
     pub fn steady(
         &mut self,
         sub: &ModelSubmesh,
@@ -143,40 +103,13 @@ impl M2BatchMaterials<'_> {
         ))
     }
 
-    /// The material pair for a batch of a **WMO skybox** — the painted sky a building owns
-    /// ([`crate::skybox`]), which is an ordinary M2 and is drawn as one (decision 1264).
-    ///
-    /// Everything that makes it a *skybox* rather than a doodad is here, and it is only three
-    /// things. Blend mode, sidedness, the UNLIT and UNFOGGED bits, the alpha-key reference, the
-    /// multiply factors and the additive gamma premultiply all come off the authored batch, like
-    /// any other model's — which is the whole point: the lane this replaced read positions, UVs and
-    /// one texture and drew every batch opaque, so `CavernsOfTimeSky`'s six ADDITIVE star sheets
-    /// (near-white RGB whose stars live in the ALPHA channel) painted a flat white sheet over the
-    /// painted sky, and its planets and asteroid belts drew as dark opaque cards.
-    ///
-    /// - **The far depth** (`sky_depth`): the sky's whole occlusion law is that it writes the
-    ///   reverse-Z far value and lets the world paint over it ([`crate::sky_order`], "The depth
-    ///   law").
-    /// - **Depth-write OFF, always**, whatever the batch authored — a sky element leaves the
-    ///   z-buffer at its clear value so the forced-far glare quads stay occluded by world geometry
-    ///   alone (the rule [`crate::sky`] gives the gradient dome).
-    /// - **Depth-test ON, always**, and this one *overrides* the batch. Every `CavernsOfTimeSky`
-    ///   batch sets M2 flag `0x08` (no depth test), which on this lane becomes
-    ///   `CompareFunction::Always` and would paint the sky straight over the room around you. The
-    ///   flag is how the reference orders the sky pass *within* its own squashed depth slice
-    ///   (`[0.975, 0.98]`, painter's order, depth-write off); our port of that ordering is the sort
-    ///   rung ([`super::skybox_sort_bias`]), so honouring the flag here would be reading it twice.
-    ///
-    /// **The skybox DOES feather** — that is what the second handle is. The slot weight
-    /// (`[CM2Model+0x180]`, written per frame from the interior crossfade `[0xce9bdc]`) multiplies
-    /// into every batch's combined alpha, and a batch at `0 < A < 1` is *promoted* to
-    /// SRC_ALPHA/INV_SRC_ALPHA blending whatever its authored mode (wow-re
-    /// `m2-blend-promotion-zfill.md` — the same promotion every entity fade rides). So the 4-second
-    /// crossfade draws the sky alpha-blended over the still-standing celestial pass. `fade_blend`
-    /// is that promoted twin; a batch whose steady material already blends (authored Blend, or a
-    /// multiply batch riding the source-colour lerp) is its own twin, exactly
-    /// [`Self::entity_variants`]' law. No depth-prime twin: the sky never writes depth, so there
-    /// is nothing to prime ([`Self::zfill_for`]'s own rule).
+    /// The pair for a batch of a WMO skybox ([`crate::skybox`]), an ordinary M2 but for its depth:
+    /// it draws at the reverse-Z far value ([`crate::sky_order`]), never writes depth, and always
+    /// tests it, overriding M2 flag `0x08`, which the reference uses only to order the sky inside
+    /// its own depth slice `[0.975, 0.98]` (ported as [`super::skybox_sort_bias`]). The slot weight
+    /// (`[CM2Model+0x180]`, from the interior crossfade `[0xce9bdc]`) scales every batch's alpha,
+    /// and `0 < A < 1` promotes a batch to SRC_ALPHA blending (`0x70c190`): `fade_blend` is that
+    /// twin, or `steady` when the batch already blends.
     pub fn skybox(
         &mut self,
         sub: &benilla_formats::RenderSubmesh,
@@ -198,17 +131,13 @@ impl M2BatchMaterials<'_> {
                 sub.additive,
                 fade,
                 true,  // never writes depth
-                false, // …and never skips the test — see above
+                false, // …and never skips the test
                 sub.fog_policy,
                 sub.env_map,
-                ShadeSel::Lit, // unread: every skybox batch the chain ships authors UNLIT (0x01)
+                ShadeSel::Lit, // unread: every shipped skybox batch is UNLIT (0x01)
                 order,
-                // No texture-transform or M2Color loop is wired on this lane, and neither shipped
-                // skybox authors one (`CavernsOfTimeSky` has 0 texture transforms and 0 animated colour
-                // tracks; `StratholmeSkybox` is fully static). Wiring them means loading the skybox
-                // through the `M2Model` asset lane — which holds these as the `Arc`s the material key
-                // identifies them by, and is also what the asteroid belts' BONE animation needs. One
-                // move, when that lands; a locally-minted `Arc` here would be a dedup key with no owner.
+                // No texture-transform or colour loop: neither shipped skybox authors one. Wiring
+                // one needs the `M2Model` lane's `Arc`, which the material key identifies it by.
                 None,
                 None,
                 None, // M2: no MOBA class, no SIDN, no WINDOW
@@ -232,24 +161,10 @@ impl M2BatchMaterials<'_> {
         Some(SkyboxBatch { steady, fade_blend })
     }
 
-    /// One steady material for a batch drawn **off-world**, against a render target's own light
-    /// buffer instead of the world's: a portrait booth's frozen studio rig, the model pane's, the
-    /// char-select stage's. The buffer is a key axis ([`super::MatKey::light`]), so these share
-    /// the one dedup cache with the world lane without ever colliding with it.
-    ///
-    /// `rig` picks the scene's **own authored M2 light rig** ([`ShadeSel::Rig`] — the probe-slot SH
-    /// eval plus the buffer's point table, decisions 0429/0435) over the sky lane, and plays the
-    /// batch's authored UV animation: together, what a char-select scene is and a portrait bake
-    /// is not (a booth freezes at t = 0 and is never ground-shaded).
-    ///
-    /// `order` is the authored batch index + 1, exactly as [`Self::entity_variants`] and
-    /// [`Self::skybox`] take it — the transparent sort bias that makes a model's coplanar batches
-    /// draw in FILE order ([`super::BATCH_ORDER_SORT_EPS`]). This lane hardcoded `0` until 1449,
-    /// and an off-world scene is the one place where that is not a harmless default: every batch
-    /// of a glue scene hangs off the scene root, so they all share one transparent sort distance
-    /// AND one zero bias — a total tie, broken by whatever order `check_visibility` happened to
-    /// collect the view in that frame. `UI_Human`'s `groundshadow` decal and its `street` batch
-    /// swapped sides several times a second, which is the char-select plaza "lighting up".
+    /// One steady material lit by a render target's own light buffer (a portrait booth, the model
+    /// pane, char-select), which [`super::MatKey::light`] keys apart from the world. `rig` lights
+    /// by the scene's authored M2 rig ([`ShadeSel::Rig`]) and plays the UV animation. `order` must
+    /// be the batch index + 1: a glue scene's batches share one root, so equal biases flicker.
     pub fn off_world(
         &mut self,
         sub: &ModelSubmesh,
@@ -273,24 +188,9 @@ impl M2BatchMaterials<'_> {
         self.build(sub, texture, order, shade, false, false, rig, light, &torch)
     }
 
-    /// The full variant set an **entity** part needs: every M2 entity — unit, player, GameObject,
-    /// held item, spell effect — is built LIT and carries the same indoor pair, because the
-    /// reference hands every entity M2 the same entity-node fill (wow-re `unit-m2-shader-light`).
-    ///
-    /// **It also puts the batch on the UV lane** (decision 2295), and takes `uv` for exactly that
-    /// reason rather than leaving it to the caller: seeding a material's `sun_scale.zw` and
-    /// registering it for the per-frame sample are one fact — *this batch's texture transform
-    /// runs* — and the recurring bug on this lane is a caller that does one and not the other
-    /// (2038 marked without registering and froze every waterfall; a `play_uv` flip without a
-    /// registration would freeze every entity batch at its first key instead of its identity,
-    /// which is a different wrong frame, not a fix). Every variant that carries the loop is
-    /// registered here, because a unit walking indoors or feathering in swaps material and would
-    /// otherwise stop scrolling mid-stride.
-    ///
-    /// The **depth-prime twin is deliberately not registered**, matching the placed-doodad lane
-    /// (`terrain_stream::spawn::assemble` registers the cutout and blend materials and no other):
-    /// it draws only while a batch feathers, and its alpha test reading unscrolled UVs for those
-    /// frames is the behaviour the streamer has always had.
+    /// The variant set of any entity part, all lit with one indoor pair: the reference gives every
+    /// entity M2 the same entity-node fill (`0x672a20`). Registers each variant's UV loop on `uv`
+    /// in the same step; the depth-prime twin, drawn only mid-feather, is not registered.
     pub fn entity_variants(
         &mut self,
         sub: &ModelSubmesh,
@@ -333,12 +233,9 @@ impl M2BatchMaterials<'_> {
             &light,
             &torch,
         );
-        // A multiply batch (Mod/Mod2x) and an authored-Blend batch are their own twin: the first
-        // because its blend equation reads no alpha at all — the fade rides the shader's
-        // identity-lerp on the tag alpha instead (0865's mechanism, 1489-verified as the
-        // reference's own preset-5 shape) — the second because its colour pass already blends.
-        // Everything else gets a real twin, built from the SOURCE blend so the 224/255 cutout
-        // marker matches what the colour pass discards (decision 0842).
+        // A multiply batch fades by the shader's identity lerp (the reference's preset-5 shape)
+        // and a Blend batch already blends: both are their own twin. The rest twin from the
+        // source blend, so the 224/255 cutout matches the colour pass.
         let own_twin = matches!(
             sub.blend,
             ModelBlend::Blend | ModelBlend::Mod | ModelBlend::Mod2x
@@ -373,8 +270,7 @@ impl M2BatchMaterials<'_> {
                 &torch,
             )
         };
-        // On the lane, now, in the same call that built and seeded them. `register_entity_uv` is
-        // idempotent per material, so the variants that collapsed onto each other cost nothing.
+        // `register_entity_uv` is idempotent per material, so collapsed variants cost nothing.
         let loops = crate::doodad_anim::UvLoops::of(sub);
         if loops.animates() {
             for id in [
@@ -404,13 +300,8 @@ impl M2BatchMaterials<'_> {
         })
     }
 
-    /// The variant set for a **character composite** texture — a runtime-built body/hair atlas,
-    /// not an authored batch, so the caller supplies the blend and sidedness the composite is
-    /// drawn with (the body is opaque, hair alpha-cuts, a robe skirt keeps its own `0x04`).
-    ///
-    /// A composite sheet carries no blend-mode fog policy of its own, no generated texcoords, no
-    /// M2Color track, and is never a multiply batch — so unlike [`Self::entity_variants`] every
-    /// twin here is real and the depth-prime twin always exists.
+    /// The variant set for a character composite (a runtime body/hair atlas) with the caller's
+    /// blend and sidedness; never a multiply batch, so every twin is real.
     pub fn char_variants(
         &mut self,
         texture: Handle<Image>,
@@ -433,12 +324,9 @@ impl M2BatchMaterials<'_> {
                 fade,
                 false, // …nor depth-write/test disabled: body and hair are ordinary geometry
                 false,
-                // Body/hair are always opaque/alpha-cut, which the byte table fogs toward the
-                // scene colour anyway.
+                // Body and hair are opaque or alpha-cut, which the byte table fogs to the scene.
                 benilla_formats::FogPolicy::Scene,
-                // A composite body/hair sheet is sampled by the body's own authored UVs.
-                // Env-mapping reaches a character through the ArmorReflect batches of its HELD
-                // items, which spawn as ordinary M2 submeshes and carry their own flag.
+                // No env map: ArmorReflect reaches a character through its held items' batches.
                 false,
                 shade,
                 0,     // a composite is one sheet, not a batch in an authored order
@@ -459,9 +347,8 @@ impl M2BatchMaterials<'_> {
             interior_bake: mk(ShadeSel::Matte, true, false),
             interior_bake_blend: mk(ShadeSel::Matte, true, true),
             fade_blend: mk(ShadeSel::Lit, false, true),
-            // Decision 0831: character parts are opaque/alpha-cut and always z-writing, so every
-            // one twins. `cutout` mirrors the colour twin's 224/255 discard exactly — only an
-            // AlphaKey source alpha-tests while fading (decision 0842).
+            // Character parts always write depth, so every one twins; as in the colour twin, only
+            // an alpha-key source alpha-tests (224/255) while fading.
             zfill: Some(zfill_material(
                 &mut self.cache.0,
                 &mut self.materials,
@@ -474,15 +361,8 @@ impl M2BatchMaterials<'_> {
         })
     }
 
-    /// The three pieces the engine's **placed**-instance spawner still takes by hand: its cache,
-    /// its material store and the light buffer.
-    ///
-    /// A temporary seam, and a narrow one — the streamer's `spawn_model_entities` builds a
-    /// different variant set (two handles, not six: a placement's indoor law is decided once at
-    /// placement time by its probe slot, where an entity's is decided every frame by which room it
-    /// walked into), and its one caller outside the engine is `entities::wmo_props`, which 1163
-    /// classified as mis-filed engine code. The seam closes when that file moves, not by widening
-    /// this facade to a lane it does not serve.
+    /// The cache, store and light buffer for the placed-instance spawner, whose indoor look is set
+    /// once per placement.
     pub fn pieces(
         &mut self,
     ) -> Option<(
@@ -496,9 +376,7 @@ impl M2BatchMaterials<'_> {
         Some((&mut self.cache.0, &mut self.materials, light, torch))
     }
 
-    /// The depth-prime twin, or `None` for a batch that primes nothing: one that disables depth
-    /// write or test (it never writes the depth a twin would prime), or a multiply batch (which
-    /// never feathers, so there is no translucent frame to prime for).
+    /// The depth-prime twin; a multiply batch never feathers, so it primes nothing.
     fn zfill_for(
         &mut self,
         sub: &ModelSubmesh,
@@ -523,8 +401,7 @@ impl M2BatchMaterials<'_> {
         }
     }
 
-    /// The one call into the twenty-argument builder: every argument but the four this facade's
-    /// entry points choose is read straight off the authored batch.
+    /// The builder call: all but the shade, probe, fade and UV-play choices come off the batch.
     fn build(
         &mut self,
         sub: &ModelSubmesh,
@@ -542,13 +419,10 @@ impl M2BatchMaterials<'_> {
             &mut self.materials,
             texture,
             sub.blend,
-            // A billboard card is culled by the SAME rule as any other batch — the material's
-            // `0x04` flag, nothing else (decision 0629, bugs B05/B34).
+            // A billboard card culls by the material's `0x04` flag, like any other batch.
             sub.two_sided,
             sub.wmo_batch.is_some(),
-            // Interior-PROP mode (the SH-probe lane) when a variant asks for it; otherwise the
-            // batch's own authored interior bit, which is set for WMO group batches and never
-            // for M2.
+            // SH-probe mode when a variant asks; otherwise the authored interior bit (WMO only).
             probe || sub.interior,
             sub.emissive,
             sub.additive,
@@ -564,8 +438,7 @@ impl M2BatchMaterials<'_> {
             sub.wmo_batch,
             sub.sidn,
             sub.window,
-            // The sky lane is [`Self::skybox`]'s alone: it overrides depth state the authored batch
-            // asks for, so it cannot be one more variant built from `sub` here.
+            // The sky lane overrides the batch's depth state, so only `Self::skybox` builds it.
             false,
             light,
             torch,
@@ -578,10 +451,9 @@ impl M2BatchMaterials<'_> {
     }
 }
 
-/// A WMO group batch shades through the FFP N·L path, not the M2 lobe, so its `sun_scale` lane is
-/// unread — a property of the batch, not of the lane that spawns it. Every other batch is LIT: the
-/// verified §9 chain gives entity M2s the same 2.5/0.5 lane as ADT doodads, and the dynamic half
-/// (the MCSH sample at their feet) rides the per-instance `MeshTag` shade byte, not the material.
+/// A WMO group batch shades through the FFP N·L path, so its `sun_scale` is unread. Every other
+/// batch is lit on the entity 2.5/0.5 lane (`0x69e280`); the dynamic half, the MCSH sample at the
+/// entity's feet, rides the per-instance `MeshTag` shade byte.
 fn shade_for(sub: &ModelSubmesh) -> ShadeSel {
     if sub.wmo_batch.is_some() {
         ShadeSel::Matte
diff --git a/crates/benilla-world/src/model_render/lazy.rs b/crates/benilla-world/src/model_render/lazy.rs
index c14492c5..40027efe 100644
--- a/crates/benilla-world/src/model_render/lazy.rs
+++ b/crates/benilla-world/src/model_render/lazy.rs
@@ -1,62 +1,17 @@
-//! **Deferred material realization** — a `WowModelMaterial` becomes an *asset* the first frame
-//! something drawable is bound to it, not the moment a spawner builds it.
+//! Deferred material realization: a `WowModelMaterial` becomes an asset the first frame something
+//! bound to it is visible, not when a spawner builds it, since every live material costs per-frame
+//! CPU in wgpu's usage trackers whether drawn or not. The builder reserves a handle and parks the
+//! value here; [`realize_bound`] inserts it once a bound entity is view-visible, and a handle every
+//! holder dropped (`AssetEvent::Unused`) takes its parked value with it. A reader that clones a
+//! material before binding it calls [`realize`] first.
 //!
-//! Why: every material asset costs the GPU lane real per-frame CPU whether or not it is ever
-//! drawn. Bevy's non-bindless `AsBindGroup` gives each material its own bind group and one
-//! buffer per `#[uniform]` binding (two for this material), and wgpu's pass encoder allocates
-//! and clears usage trackers sized to the device's *live* buffer and texture counts for every
-//! render pass it encodes — a per-pass term that scales with residency, not with what is drawn.
-//! Measured on the crowd rig (1929's follow-on, the `wgpu_bufs=` census): 9.9k materials,
-//! 20.7k buffers and 10.2k bind groups alive at the Stormwind auction house with 36 entity
-//! batches drawn, because the batch builder ([`super::batch::M2BatchMaterials`]) hands every
-//! spawner its whole variant set — steady, the two interior lanes, their blend twins, the
-//! depth-prime twin — and the variants a batch never switches to sat in the store forever.
+//! The deadline is the store's event publish, not extraction: `Assets::insert` only queues an
+//! `AssetEvent::Added`, which `Assets::asset_events` publishes in `PostUpdate`, and an asset
+//! realized after that is not drawn that frame (a material swap blinks). So the sweep runs at the
+//! top of `PostUpdate`, before `AssetEventSystems` and before `VisibilityPropagate` resets the
+//! bits, and reads last frame's visibility; a fresh binding draws on its second frame.
 //!
-//! The mechanism: the builder reserves a handle (`Assets::reserve_handle`) and parks the built
-//! value here, keyed by the reserved id. [`realize_bound`] walks the bound handles and inserts
-//! the asset for every one whose entity is view-visible this frame. A handle every holder has
-//! dropped arrives as the store's own `AssetEvent::Unused` (it fires for a reserved id too) and
-//! the parked value goes with it. Nothing about the handles changes: a part still stores and
-//! swaps `Handle<WowModelMaterial>`s, and every reader that clones a material *before* binding
-//! it — the portrait booth's relight twins, a spell kit's per-instance copy, the pipeline
-//! warmer — calls [`realize`] first, which is a no-op for an asset that already exists.
-//!
-//! **The deadline is the store's event PUBLISH, not extraction.** `Assets::insert` does not
-//! announce anything: it pushes an `AssetEvent::Added` onto the store's private queue, and
-//! `Assets::<A>::asset_events` — scheduled by bevy_asset in **`PostUpdate`** — is what writes
-//! that queue into the message stream `extract_render_asset` reads. A sweep placed after it
-//! (this module's original `Last`) therefore realizes an asset the render world is not told
-//! about until the NEXT frame's publish, and `queue_material_meshes` skips every entity whose
-//! material is missing from `RenderAssets` — one frame of the object not drawn. That is
-//! invisible for a first bind (nothing was on screen to lose) and plainly visible for a
-//! **swap onto an entity that is already drawing**: the appear fade's blend→cutout latch, where
-//! a freshly logged-in NPC blinked out for a frame at the instant it finished fading in, and
-//! the doodad distance fade's latch and the far-side water twin behind it. Pinned by
-//! [`tests::the_sweep_publishes_its_added_in_the_frame_it_realizes`].
-//!
-//! **So the sweep is the top of `PostUpdate`, and the visibility it reads is last frame's** —
-//! not a preference, the only placement bevy's own graph leaves. `AssetEventSystems` is ordered
-//! *before* `CalculateBounds`, which is before `CheckVisibility` (bevy_camera's
-//! `VisibilityPlugin`), so "after this frame's verdict" and "before the publish" is a cycle; and
-//! `reset_view_visibility` (in `VisibilityPropagate`, also before `CheckVisibility`) clears every
-//! current bit, so a sweep between the two would read `false` for the whole world. Before both,
-//! `ViewVisibility::get` is still the previous frame's answer — which is exactly the right
-//! question here: the entity this exists to keep drawing is the one that WAS drawing and had its
-//! material swapped under it in `Update`.
-//!
-//! A binding whose entity was not visible last frame — a fresh spawn, an unparked part, the
-//! depth-prime twin `zfill::sync_zfill_twins` spawns in `PostUpdate` — realizes on the next
-//! sweep and draws on its second frame. That is what the `Last` placement did too (a
-//! just-spawned entity's material was realized on its spawn frame and published on the next),
-//! so nothing pays more than before, and everything that swaps pays a frame less.
-//!
-//! **The table is a process global, deliberately.** It is a side of `Assets<WowModelMaterial>`
-//! — "reserved, value parked" — that the asset store has no slot for, and the builder that
-//! needs it ([`super::model_material`]) is a free function with a two-dozen-argument signature
-//! reached from seven lanes through three caches (the engine's, the streamer's, the warmer's
-//! `Local`). Threading one more resource through all of them for what is a property of the
-//! store, not of any cache, is the wrong shape; one mutex, locked once per system run, is the
-//! right one. Main-world only, like the store it shadows.
+//! The parked table is a process-wide mutex beside the store; main world only.
 
 use std::collections::HashMap;
 use std::sync::Mutex;
@@ -67,9 +22,7 @@ use bevy::prelude::*;
 
 use benilla_assets::materials::WowModelMaterial;
 
-/// The parked values of one asset type: built, handle reserved, not yet in the store. Generic
-/// so the table's law is testable on a stub asset (a real `WowModelMaterial` carries a GPU
-/// buffer and cannot exist without a device).
+/// Built values of one asset type whose handles are reserved but not yet in the store.
 pub struct Parked<A: Asset>(HashMap<AssetId<A>, A>);
 
 impl<A: Asset> Default for Parked<A> {
@@ -86,9 +39,7 @@ impl<A: Asset> Parked<A> {
         handle
     }
 
-    /// Make the asset behind `id` exist now, if its value is parked. Returns whether the store
-    /// holds it afterwards — `false` only for an id this table never saw and the store does not
-    /// have (a foreign handle, or one already dropped everywhere).
+    /// Makes the asset behind `id` exist now; `false` only for a foreign or fully dropped handle.
     pub fn realize(&mut self, store: &mut Assets<A>, id: AssetId<A>) -> bool {
         if store.contains(id) {
             return true;
@@ -96,8 +47,7 @@ impl<A: Asset> Parked<A> {
         let Some(asset) = self.0.remove(&id) else {
             return false;
         };
-        // `Err` = the reserved index was dropped and re-minted with a new generation since this
-        // value was parked; the `Unused` purge simply has not run yet. Nothing to insert.
+        // `Err`: the index was re-minted since parking and the `Unused` purge has not run yet.
         store.insert(id, asset).is_ok()
     }
 
@@ -108,52 +58,39 @@ impl<A: Asset> Parked<A> {
         }
     }
 
-    /// The store reported `id` unused: whoever held the handle is gone, and so is the value.
+    /// Drops the value of a handle the store reported unused.
     pub fn purge(&mut self, id: AssetId<A>) {
         self.0.remove(&id);
     }
 
-    /// The value behind `id` **wherever it currently lives** — the store when the asset exists,
-    /// the parked half when it does not yet. `None` only when neither holds it (a foreign handle,
-    /// or one dropped everywhere).
-    ///
-    /// This is the address a build-time stamp needs. Deferral split "the material a spawner just
-    /// built" into two homes, and a lane that reaches for the store alone reads a *live feature*
-    /// as an absent asset: the mat-anim registration wrote its table slot with
-    /// `Assets::get_mut`, got `None` for every deferred material, and silently froze every
-    /// UV-scroll and animated-tint batch in the world (decision 2038). Realizing the asset to
-    /// stamp it would work and would also throw away exactly the residency deferral buys; the
-    /// stamp belongs in the value, not in the store it happens to be sitting outside of.
+    /// The value behind `id`, realized or parked: a build-time stamp writes here, since
+    /// `Assets::get_mut` reads a parked material as absent.
     pub fn value_mut<'a>(
         &'a mut self,
         store: &'a mut Assets<A>,
         id: AssetId<A>,
     ) -> Option<&'a mut A> {
-        // Store first: once realized it is the truth, and a parked value for a live id could
-        // only be a stale leftover.
+        // Store first: once realized it is the truth, and a parked value for it would be stale.
         if store.contains(id) {
             return store.get_mut(id);
         }
         self.0.get_mut(&id)
     }
 
-    /// [`Self::value_mut`]'s read-only twin — for a reader that must not dirty the asset
-    /// (`Assets::get_mut` marks it `Modified`, which is a bind-group rebuild on the Metal
-    /// non-bindless path: the exact cost 1381 removed from this lane).
+    /// Read-only [`Self::value_mut`], for a reader that must not mark the asset `Modified` (a
+    /// bind-group rebuild on the non-bindless path).
     pub fn value<'a>(&'a self, store: &'a Assets<A>, id: AssetId<A>) -> Option<&'a A> {
         store.get(id).or_else(|| self.0.get(&id))
     }
 
-    /// Either half holds a value for `id` — "this material is alive", the deferral-aware form of
-    /// `Assets::contains`. A registry that evicts on the store alone drops every entry whose
-    /// material is merely parked.
+    /// The deferral-aware `Assets::contains`: a registry that evicts on the store alone drops every
+    /// parked material.
     pub fn holds(&self, store: &Assets<A>, id: AssetId<A>) -> bool {
         store.contains(id) || self.0.contains_key(&id)
     }
 
-    /// Realize every parked value some *visible* binding names. `bound` yields each binding
-    /// with its view-visibility (`None` = not on the visibility lane at all — a booth part
-    /// before its camera, a test world — which counts as visible: bound is enough).
+    /// Realizes every parked value a visible binding names; a binding with no visibility (`None`:
+    /// a booth part before its camera) counts as visible.
     pub fn realize_visible(
         &mut self,
         store: &mut Assets<A>,
@@ -188,8 +125,7 @@ fn with_pending<R>(f: impl FnOnce(&mut Parked<WowModelMaterial>) -> R) -> R {
     f(guard.get_or_insert_with(Parked::default))
 }
 
-/// Reserve a handle for `material` and park the value until something bound to the handle is
-/// drawn. The builder's replacement for `Assets::add`.
+/// The builder's `Assets::add`: reserves a handle and parks the value until a binding draws.
 pub fn defer(
     materials: &Assets<WowModelMaterial>,
     material: WowModelMaterial,
@@ -197,25 +133,18 @@ pub fn defer(
     with_pending(|p| p.defer(materials, material))
 }
 
-/// Make the asset behind `id` exist now — see [`Parked::realize`].
+/// Makes the asset behind `id` exist now ([`Parked::realize`]).
 pub fn realize(materials: &mut Assets<WowModelMaterial>, id: AssetId<WowModelMaterial>) -> bool {
     with_pending(|p| p.realize(materials, id))
 }
 
-/// Insert every parked value. For a lane that reads materials back right after building them
-/// (the pipeline warmer, which inspects each variant it built to derive its far-side twins).
+/// Inserts every parked value, for a lane that reads materials back right after building them.
 pub fn realize_all(materials: &mut Assets<WowModelMaterial>) {
     with_pending(|p| p.realize_all(materials));
 }
 
-/// Apply `f` to a built material **wherever it lives** — see [`Parked::value_mut`]. `None` when
-/// neither the store nor the parked half holds `id`.
-///
-/// The write-side counterpart of [`realize`], and the right call for a **one-shot build-time
-/// stamp**: a lane that must leave a mark on a material it just built, without forcing the
-/// material into the store (which is what deferral exists to avoid) and without caring whether
-/// something has drawn it yet. The closure form is not a style choice — the parked table lives
-/// behind a mutex, so a `&mut` into it cannot leave the lock.
+/// Applies `f` to a built material wherever it lives ([`Parked::value_mut`]), for a build-time
+/// stamp that must not force it into the store; a closure, as the table is behind a mutex.
 pub fn with_material_mut<R>(
     materials: &mut Assets<WowModelMaterial>,
     id: AssetId<WowModelMaterial>,
@@ -224,10 +153,7 @@ pub fn with_material_mut<R>(
     with_pending(|p| p.value_mut(materials, id).map(f))
 }
 
-/// Read a built material **wherever it lives** — [`with_material_mut`]'s non-dirtying twin
-/// ([`Parked::value`]). What a readout wants: a probe that reached for the store alone would
-/// report a parked material's fields as absent and reproduce the very confusion it exists to
-/// resolve.
+/// Reads a built material wherever it lives, without dirtying it ([`Parked::value`]).
 pub fn with_material<R>(
     materials: &Assets<WowModelMaterial>,
     id: AssetId<WowModelMaterial>,
@@ -236,26 +162,19 @@ pub fn with_material<R>(
     with_pending(|p| p.value(materials, id).map(f))
 }
 
-/// Either half holds a value for `id` — see [`Parked::holds`]. The liveness test a registry
-/// keyed by material asset id must evict on; `Assets::contains` alone reads a parked material as
-/// dead.
+/// The liveness test a registry keyed by material id evicts on ([`Parked::holds`]).
 pub fn holds(materials: &Assets<WowModelMaterial>, id: AssetId<WowModelMaterial>) -> bool {
-    // The store answers without the lock, and a REALIZED material is the common case for
-    // everything a per-frame lane asks about (only a parked one can be undrawn), so the mutex is
-    // reached for exactly the entries the store cannot settle.
+    // The store answers the common, realized case without taking the lock.
     materials.contains(id) || with_pending(|p| p.holds(materials, id))
 }
 
-/// How many values are parked — the census figure beside `mats=`.
+/// How many values are parked (the census figure beside `mats=`).
 pub fn pending_len() -> usize {
     with_pending(|p| p.len())
 }
 
-/// The top of `PostUpdate`: realize the material of every bound entity that was view-visible on
-/// the last frame's verdict, and drop the parked value of every handle the store reports unused.
-/// Before `AssetEventSystems` (so the `Added` this insert queues is published in time for this
-/// frame's extraction) and before `VisibilityPropagate` (whose `reset_view_visibility` clears the
-/// bits this reads) — see the module doc's deadline paragraph for why those are the only bounds.
+/// Top of `PostUpdate`, before `AssetEventSystems` and `VisibilityPropagate`: realizes the
+/// material of every bound entity visible last frame and purges every handle reported unused.
 pub(super) fn realize_bound(
     bound: Query<(&MeshMaterial3d<WowModelMaterial>, Option<&ViewVisibility>)>,
     mut materials: ResMut<Assets<WowModelMaterial>>,
@@ -298,20 +217,14 @@ mod tests {
         assert!(!parked.realize(&mut store, stray.id()));
     }
 
-    /// **The law decision 2038 was written from**: a value that is only PARKED is still a live
-    /// material — writable in place, and `holds`-alive — so a lane that stamps a material it just
-    /// built lands its mark whether or not anything has drawn it yet, and a registry keyed by
-    /// asset id does not evict it as dead. Reaching for the store alone is what silently froze
-    /// every UV-scroll and animated-tint batch in the world.
+    /// A parked value is a live material: writable in place and `holds`-alive before any draw.
     #[test]
     fn a_parked_value_is_writable_and_counts_as_held() {
         let mut store = Assets::<Stub>::default();
         let mut parked = Parked::default();
         let deferred = parked.defer(&store, Stub(1));
-        // The store does not have it — the read that used to answer "no such material".
         assert!(!store.contains(deferred.id()));
         assert!(store.get_mut(deferred.id()).is_none());
-        // …and both deferral-aware reads do.
         assert!(parked.holds(&store, deferred.id()));
         assert_eq!(parked.value(&store, deferred.id()).map(|s| s.0), Some(1));
         parked
@@ -321,31 +234,20 @@ mod tests {
         // The stamp survives realization: the value goes into the store as written.
         assert!(parked.realize(&mut store, deferred.id()));
         assert_eq!(store.get(&deferred).map(|s| s.0), Some(7));
-        // Realized, the store is the half that answers — and still the same value.
         assert_eq!(parked.value(&store, deferred.id()).map(|s| s.0), Some(7));
         parked
             .value_mut(&mut store, deferred.id())
             .expect("realized values stay addressable")
             .0 = 9;
         assert_eq!(store.get(&deferred).map(|s| s.0), Some(9));
-        // An id neither half holds is the only `None` — and the only not-held.
         let stray = store.reserve_handle();
         assert!(!parked.holds(&store, stray.id()));
         assert!(parked.value(&store, stray.id()).is_none());
         assert!(parked.value_mut(&mut store, stray.id()).is_none());
     }
 
-    /// **The deadline is the publish, not the insert** — the law the `Last` placement broke.
-    /// `Assets::insert` only queues its `AssetEvent::Added`; `Assets::<A>::asset_events`
-    /// (bevy_asset, `PostUpdate`) is what writes it into the message stream the render world
-    /// extracts from. A sweep that realizes AFTER that system announces nothing this frame, so
-    /// `extract_render_asset` never extracts the material and `queue_material_meshes` skips every
-    /// entity bound to it — one frame not drawn, seen as a blink the instant an appear fade
-    /// latched from its blend twin onto its steady material.
-    ///
-    /// The reader stands in for extraction: `ExtractSchedule` runs immediately after `Last` and
-    /// reads the same message buffer, so "visible to a `Last` reader" is exactly "visible to
-    /// extraction".
+    /// The deadline is the publish, not the insert. The reader stands in for extraction, which
+    /// runs right after `Last` and reads the same message buffer.
     #[test]
     fn the_sweep_publishes_its_added_in_the_frame_it_realizes() {
         use bevy::asset::{AssetEvent, AssetEventSystems, AssetPlugin};
@@ -355,7 +257,7 @@ mod tests {
         struct Table(Parked<Stub>);
         #[derive(Resource)]
         struct Reserved(Handle<Stub>);
-        /// Frames on which a reader standing where extraction stands saw the `Added`.
+        /// Frames on which the extraction stand-in saw the `Added`.
         #[derive(Resource, Default)]
         struct Seen(Vec<u32>);
         #[derive(Resource, Default)]
@@ -383,8 +285,7 @@ mod tests {
             frame.0 += 1;
         }
 
-        /// An app whose realize sweep sits where `place` puts it; returns the frames on which
-        /// extraction could see the `Added`.
+        /// The frames extraction sees the `Added` on, with the sweep where `place` puts it.
         fn frames_added_was_visible(place: impl FnOnce(&mut App)) -> Vec<u32> {
             let mut app = App::new();
             app.add_plugins((MinimalPlugins, AssetPlugin::default()))
@@ -407,7 +308,7 @@ mod tests {
             app.world().resource::<Seen>().0.clone()
         }
 
-        // The shipped placement: realized in `Last`, published by the NEXT frame's PostUpdate.
+        // Realized in `Last`: published by the next frame's `PostUpdate`.
         assert_eq!(
             frames_added_was_visible(|app| {
                 app.add_systems(Last, realize_reserved.before(extraction_stand_in));
@@ -416,7 +317,7 @@ mod tests {
             "a `Last` realize is announced a frame late — the blink"
         );
 
-        // Where it lives now: the top of `PostUpdate`, ahead of the publish.
+        // Realized at the top of `PostUpdate`: published the same frame.
         assert_eq!(
             frames_added_was_visible(|app| {
                 app.add_systems(
diff --git a/crates/benilla-world/src/model_render/park.rs b/crates/benilla-world/src/model_render/park.rs
index 3830398e..31c81740 100644
--- a/crates/benilla-world/src/model_render/park.rs
+++ b/crates/benilla-world/src/model_render/park.rs
@@ -1,31 +1,10 @@
-//! **Parking hidden world submeshes** — a streamed model part that has been hidden for a while
-//! puts its `Mesh3d` down, and picks it up the frame its placement is shown again.
-//!
-//! Why: the retained pass draws the world, and the entity path keeps the batches it declines
-//! resident — 5.8k ADT-doodad submeshes at the Stormwind auction house, 5.3k of them hidden by
-//! the outdoor election or the far clip at any instant (decision 1947's census: WMO props whose
-//! class cannot merge, shared-geometry batches, exterior fader props). Bevy's own sweeps walk
-//! every `Mesh3d` whether it draws or not: the asset-changed marks, the specialization check,
-//! `calculate_bounds`, the previous-transform update, the visibility reset — ~0.4 ms of an
-//! alone city frame on the sampled profile, for rows that draw nothing. Without `Mesh3d` an
-//! entity is in none of those queries, and everything else it carries stays: the transform,
-//! the material handle, the tag, the pick mesh, the fade state.
-//!
-//! **The hysteresis is the point.** The election flips as the camera turns; parking on the
-//! first hidden frame would move a component per flip per part. A part parks after
-//! [`PARK_AFTER_FRAMES`] consecutive hidden frames and unparks the moment its root is shown —
-//! so a glance across the square costs nothing, and only what stays hidden gets cheap.
-//!
-//! **Timing, and the one landmine.** The root election writes in `PostUpdate`; this runs in
-//! `Update` on the next frame's verdict, which puts the re-inserted `Mesh3d` in place before
-//! that frame's `check_entities_needing_specialization` and visibility check. Inserting it
-//! later — after the visibility check, on an entity already view-visible — is the
-//! `specialize_material_meshes` tick unwrap `static_gx::cull` documents (B2, 1431), and the
-//! price of the safe order is one frame between a placement's election and its first draw.
-//! Every world model part takes part — the streamer's placements and the units' bodies alike
-//! (a raid standing round the camera keeps half its bodies behind it) — except parts on a
-//! render layer of their own: a portrait booth's mirror parts show and hide with the booth's
-//! wake, and its bake window is four frames.
+//! Parking hidden world submeshes: a model part hidden for [`PARK_AFTER_FRAMES`] puts its `Mesh3d`
+//! down, leaving every Bevy per-`Mesh3d` sweep, and picks it up once its root is shown again.
+//! This runs in `Update` on last frame's verdict, so a re-shown part draws a frame after its
+//! election but its `Mesh3d` is back before specialization and the visibility check: inserted
+//! after the visibility check on a visible entity, it trips Bevy's `specialize_material_meshes`
+//! tick unwrap. Parts on a render layer of their own (a portrait booth's, whose bake window is
+//! four frames) never park.
 
 use std::any::TypeId;
 
@@ -35,7 +14,8 @@ use bevy::prelude::*;
 
 use super::ModelPart;
 
-/// Consecutive hidden frames before a part parks — half a second at 60 Hz.
+/// Consecutive hidden frames before a part parks, half a second at 60 Hz, so a glance costs
+/// nothing.
 const PARK_AFTER_FRAMES: u16 = 30;
 
 /// The mesh a parked part put down, restored verbatim on unpark.
@@ -46,9 +26,8 @@ pub struct ParkedMesh(pub Handle<Mesh>);
 #[derive(Component, Default)]
 pub struct HiddenFrames(pub u16);
 
-/// `Update`, after the visibility authority: count hidden frames, park the long-hidden,
-/// unpark the shown. Reads last `PostUpdate`'s `InheritedVisibility` — the propagated verdict
-/// of this part's whole ancestry.
+/// Counts hidden frames, parks the long-hidden and unparks the shown, by last `PostUpdate`'s
+/// propagated `InheritedVisibility`.
 #[allow(clippy::type_complexity)]
 pub(super) fn park_hidden_parts(
     mut commands: Commands,
@@ -73,13 +52,9 @@ pub(super) fn park_hidden_parts(
                     .entity(entity)
                     .insert(Mesh3d(parked.0.clone()))
                     .remove::<ParkedMesh>()
-                    // Bevy's `Mesh3d` add hook pushes the mesh's `VisibilityClass` entry every
-                    // time the component is (re)added, and nothing ever dedups that list;
-                    // `check_visibility` queues an entity once PER entry, so each park →
-                    // unpark cycle drew the part one more time. Opaque parts hide it; an
-                    // additive glow card stacks on itself — the director's lamppost halo,
-                    // doubling after every teleport that hid it and healed only by a relog.
-                    // One entry per class, applied after the hook has run.
+                    // Bevy's `Mesh3d` add hook pushes a `VisibilityClass` entry on every re-add
+                    // and `check_visibility` queues an entity once per entry, so each cycle would
+                    // draw the part once more; dedup after the hook has run.
                     .queue(dedup_visibility_class);
             }
             if let Some(mut f) = frames {
@@ -105,7 +80,7 @@ pub(super) fn park_hidden_parts(
     }
 }
 
-/// Leave one entry per class in an entity's [`VisibilityClass`] (see the unpark site).
+/// Leaves one entry per class in an entity's [`VisibilityClass`].
 fn dedup_visibility_class(mut e: EntityWorldMut) {
     if let Some(mut class) = e.get_mut::<VisibilityClass>() {
         let mut seen: Vec<TypeId> = Vec::with_capacity(class.len());
@@ -120,7 +95,7 @@ fn dedup_visibility_class(mut e: EntityWorldMut) {
     }
 }
 
-/// `WOW_NO_MESH_PARK=1` — the A/B lever.
+/// `WOW_NO_MESH_PARK=1` turns parking off.
 pub(super) fn enabled() -> bool {
     std::env::var_os("WOW_NO_MESH_PARK").is_none()
 }
@@ -171,10 +146,7 @@ mod tests {
         assert_eq!(w.entity(e).get::<HiddenFrames>().unwrap().0, 0);
     }
 
-    /// Bevy's `Mesh3d` add hook pushes a `VisibilityClass` entry on every (re)add and
-    /// `check_visibility` queues an entity once per entry: without the dedup an unparked part
-    /// is drawn twice, three times after the next cycle — the stacking lamppost halo. The
-    /// world here registers the hook and the requirement exactly as bevy's plugin does.
+    /// The world registers the `Mesh3d` hook and required component as Bevy's plugin does.
     #[test]
     fn an_unparked_part_keeps_one_visibility_class_entry() {
         let mut w = World::new();
diff --git a/crates/benilla-world/src/model_render/visibility.rs b/crates/benilla-world/src/model_render/visibility.rs
index 46b2f346..03431202 100644
--- a/crates/benilla-world/src/model_render/visibility.rs
+++ b/crates/benilla-world/src/model_render/visibility.rs
@@ -1,9 +1,6 @@
-//! The world-model visibility apply system. Each frame it shows/hides every doodad/WMO/creature
-//! submesh from the panel's layer/type toggles AND the faithful far-clip wall-cull (nearest-point of
-//! the mesh AABB along the camera-forward axis, same plane as the per-pixel wall) plus the small-prop
-//! distance fade. The model-`Visibility` authority, with one *ordered* override: the self-avatar
-//! first-person hide (`player::apply_self_model_fade`) runs after this set ([`super::ModelVisSet`])
-//! and wins on the self body submeshes. Split from the panel UI/state in `super`.
+//! The one model `Visibility` authority: dev toggles, the far-clip wall, the distance fade, the
+//! portal PVS and the exterior window gate compose in one system. The first-person self-avatar
+//! hide runs after [`super::ModelVisSet`] and wins on the self body.
 
 use bevy::camera::primitives::Aabb;
 use bevy::mesh::MeshTag;
@@ -17,15 +14,9 @@ use crate::view::WorldCamera;
 use crate::wmo_portal::{WmoGroupVis, WmoPortalInstance};
 use benilla_assets::materials::WowModelMaterial;
 
-/// Show/hide each model submesh from the layer/type toggles **and** the faithful draw-distance cull.
-/// The toggles are a dev inspector; the distance test is real fidelity — in 1.12 every doodad/WMO
-/// **hard-pops** out past the `farclip` radius from the camera (no fade, no distance-LOD; the cull tests
-/// each placement against the `cameraPos ± farclip` AABB). We approximate
-/// that AABB with a radial distance to the placement origin, which reads the same in-frame.
-///
-/// Runs every frame (the camera moves, so this can't be snapshot-gated like a pure toggle), but only
-/// **writes** `Visibility` when a submesh's decision actually flips — so the steady-state cost is one
-/// squared-distance compare per submesh and no change-detection churn.
+/// Shows or hides each model submesh. A doodad or WMO part is culled once its bound lies wholly
+/// past the far-clip wall ([`crate::view::within_farclip`]), so a straddler dissolves through the
+/// per-pixel wall. Writes only on a flip.
 #[allow(clippy::type_complexity)]
 pub(super) fn apply_model_visibility(
     debug: Res<DebugState>,
@@ -38,38 +29,21 @@ pub(super) fn apply_model_visibility(
         ),
         With<WorldCamera>,
     >,
-    // The two edges the per-part skip below cannot read off its own row: a building streaming
-    // in (its portal set is new), and any owner's inherited verdict flipping (a card follows it).
-    // `Changed`, not `Added`: the PVS writer sets the tick only on a real change of the
-    // visible set, and that set moves when a building's asset lands frames after its spawn.
+    // Scene edges the per-part skip cannot read off its own row: a portal set changing (a
+    // building's asset lands frames after its spawn) and any owner's inherited verdict flipping.
     new_portals: Query<(), Changed<WmoPortalInstance>>,
     owner_flips: Query<(), Changed<InheritedVisibility>>,
-    // A part whose far-side mark was REMOVED reads as never marked; the classifier's full walk
-    // can strip it under a still camera (review 2026-09-04), and the strip must un-skip it.
+    // A far-side mark the classifier strips under a still camera must un-skip its part.
     mut unmarked: RemovedComponents<super::FarSideOfWater>,
-    // The per-frame WMO portal PVS (computed by `crate::wmo_portal`), read here so the cull composes
-    // with the toggles + far-clip in this single Visibility authority rather than fighting it.
     instances: Query<&WmoPortalInstance>,
-    // …and, for exactly the same reason, the exterior-scene window gate (decision 0784). It used to
-    // write `Visibility` itself in `PostUpdate`, i.e. AFTER this system — so on every object it
-    // admitted it silently undid the toggles, the far-clip cull and the portal PVS, including
-    // outdoors, where it wrote `Inherited` over all of them every single frame.
     windows: Res<crate::wmo_portal::ExteriorWindows>,
-    // The camera's OWN building is not exterior scene to itself: the reference draws the containing
-    // map object through the interior portal walk, never through the per-window exterior populate
-    // (`[0xc7b748]` is the branch, not a participant). Without this exemption, standing inside
-    // Stratholme would window-cull Stratholme's own walls.
+    // The camera's own building is not exterior scene: the reference draws it through the
+    // interior portal walk, never the per-window exterior populate (`[0xc7b748]` is the branch).
     claim: Res<crate::wmo_portal::CameraInteriorClaim>,
-    // The water-plane classification (`model_render::classify_water_side`) — read-only here: this
-    // system owns the DoodadFade handle pick, so the far-side axis composes INTO that pick (the
-    // marker + the twin map) instead of a second writer re-swapping the handle it just wrote —
-    // the exact fight decision 0025's one-authority law exists to prevent.
+    // Read-only: this system owns the `DoodadFade` handle pick, and the far side composes into it.
     far_twins: Res<super::FarSideTwins>,
-    // Every entity that can OWN a billboard card — the model root a card belongs to, or a joint of
-    // its rig, both of which carry the root's propagated verdict. Read-only, and for the same
-    // one-authority reason as the two above: a card is a world root, so nothing carries its owner's
-    // hide to it, and the mirror that used to live in `billboard::face_billboards` was ordered too
-    // late to survive (decision 1409).
+    // Billboard card owners (a model root or a rig joint): a card is a world root, so nothing
+    // else carries its owner's hide to it.
     card_owners: Query<&InheritedVisibility>,
     mut q: Query<(
         Entity,
@@ -87,11 +61,8 @@ pub(super) fn apply_model_visibility(
         Option<Ref<super::FarSideOfWater>>,
         Option<&crate::billboard::BillboardCard>,
     )>,
-    // The building's own MLIQ surfaces (canals, dungeon pools, Ragefire's lava). They carry a
-    // `WmoGroupVis` like every other piece of their group but no `ModelPart` — they are not model
-    // submeshes and take none of the toggle/far-clip/fade rules above. A second QUERY, deliberately
-    // not a second SYSTEM: decision 0025 wants one `Visibility` authority, and this keeps it
-    // (decision 0689 — a culled room's water must go with the room, same as its furniture).
+    // A building's MLIQ surfaces: a `WmoGroupVis` but no `ModelPart`, so none of the submesh
+    // rules. A query here rather than a second writer, so a culled room's water goes with it.
     mut group_only: Query<
         (
             &WmoGroupVis,
@@ -105,16 +76,11 @@ pub(super) fn apply_model_visibility(
     >,
 ) {
     let m = &debug.models;
-    // The (single) world Camera3d; the egui overlay is a Camera2d. None before it spawns → no distance
-    // cull that frame (toggles still apply).
     let cam_view = cam.iter().next();
     let cam_t = cam_view.as_ref().map(|(t, _, _)| t);
-    // Every whole-scene input of a part's verdict, still since last frame. With those still, a
-    // part whose own row is still too would come out of the walk below with the same
-    // `Visibility`, tag and material it already carries — so it skips the walk (decision 1979's
-    // floor: ~8.7 k resident parts re-verdicted on every still frame at the Stormwind pin).
-    // Both the propagated frame and the seat's own write: this system runs before propagation,
-    // so a teleport frame's move is only visible on the local `Transform` (see doodad_anim).
+    // Every whole-scene input still since last frame: a part whose own row is still too would
+    // come out unchanged, so it skips the walk. The camera's local `Transform` counts too: this
+    // runs before propagation, so a teleport's move shows only there.
     let scene_still = cam_view.as_ref().is_some_and(|(t, p, l)| {
         !t.is_changed() && !p.is_changed() && !l.as_ref().is_some_and(|l| l.is_changed())
     }) && !debug.is_changed()
@@ -126,17 +92,13 @@ pub(super) fn apply_model_visibility(
         && owner_flips.is_empty();
     let cam_pos = cam_t.map(|t| t.translation());
     let cam_fwd = cam_t.map(|t| Vec3::from(t.forward()));
-    // The exterior gate, built ONCE for the whole walk (it is a handful of 6-plane frusta) and then
-    // asked per submesh below — the same value `crate::exterior_cull` asks for the objects it owns.
     let gate = crate::exterior_cull::ExteriorGate::build(
         &windows,
         cam_view.as_ref().map(|(t, p, _)| (&**t, &**p)),
     );
-    // The placement the camera is standing in, exempt from its own window gate (see the param).
+    // The placement the camera stands in, exempt from its own window gate.
     let own_instance = claim.0.map(|c| c.room.instance);
-    // Parallel: this walks EVERY model submesh in residency — ~100k in a city — and at that N a
-    // serial walk alone blew half the 16.7 ms budget (the Stormwind fps hunt). Every write below
-    // is change-gated, so the steady state is a pure read fan-out.
+    // Parallel over every resident model submesh (~100k in a city); every write is change-gated.
     let unmarked: bevy::platform::collections::HashSet<Entity> = unmarked.read().collect();
     let unmarked = &unmarked;
     q.par_iter_mut().for_each(
@@ -169,17 +131,12 @@ pub(super) fn apply_model_visibility(
             let (group_vis, mat_anim) = (group_vis.as_deref(), mat_anim.as_deref());
             let toggled_on =
                 m.kind_visible[kind_index(part.kind)] && m.blend_visible[blend_index(part.blend)];
-            // `farclip` is the *world-doodad/WMO* draw distance only. Creatures/GameObjects come from the
-            // server's own visibility stream (already range-limited) and have separate unit-draw rules, so
-            // they're not culled here.
+            // `farclip` culls doodads and WMOs only: units and GameObjects come range-limited from
+            // the server's visibility stream.
             let distance_culled = matches!(part.kind, ModelKind::Doodad | ModelKind::Wmo);
             let pos = xf.translation();
-            // Cull by the NEAREST point of the submesh's bounding sphere, not its origin: an object
-            // straddling the hard far-clip wall stays drawn so the per-pixel wall (terrain/wow_model.wgsl)
-            // DISSOLVES it through the boundary, instead of the whole thing popping when its origin crosses
-            // the wall (the "snaps at the centre" artifact — worst for big trees/buildings). `Aabb` is the
-            // mesh bound (local); transform to world + uniform placement scale. Absent for a frame after
-            // spawn ⇒ fall back to origin distance.
+            // By the bounding sphere's nearest point, so a straddler stays drawn for the per-pixel
+            // wall to dissolve. No `Aabb` for a frame after spawn: the origin stands in.
             let in_range = match (distance_culled, cam_pos, cam_fwd) {
                 (false, _, _) | (_, None, _) | (_, _, None) => true,
                 (true, Some(c), Some(fwd)) => {
@@ -191,19 +148,14 @@ pub(super) fn apply_model_visibility(
                         ),
                         None => (pos, 0.0),
                     };
-                    // Planar depth along the camera-forward axis (the SAME coordinate the per-pixel wall
-                    // uses) of the bound's nearest point — so the cull and the wall agree and the object
-                    // dissolves through the boundary with no pop, even off-centre. The rule itself lives
-                    // in `view::within_farclip`; the particle draw-set gate reads the same one, because
-                    // an emitter outliving its own doodad past the wall is exactly what B39 reported.
+                    // The particle draw-set gate reads the same rule, so no emitter outlives its
+                    // doodad past the wall.
                     crate::view::within_farclip(view.farclip, c, fwd, center, radius)
                 }
             };
 
-            // Faithful size-bucketed per-object distance fade (`model_fade::doodad_fade_alpha`, the
-            // reference's `FUN_00683f80`). Only doodads/WMOs carry `DoodadFade`. Distance is measured to the
-            // model's bounding-sphere CENTRE (origin + the transformed bbox-centre offset), in the
-            // **horizontal** ground plane (Bevy XZ) — both verified against `FUN_006952a0`/`FUN_00683f80`.
+            // The size-bucketed distance fade (reference `0x683f80`), measured to the bounding
+            // sphere's centre in the horizontal plane (`0x6952a0`, `0x683f80`).
             let fade_alpha = match (fade, cam_pos) {
                 (Some(f), Some(c)) => {
                     let center = xf.transform_point(f.local_center);
@@ -213,12 +165,7 @@ pub(super) fn apply_model_visibility(
                 _ => 1.0,
             };
 
-            // WMO portal visibility: a group the camera can't reach through any portal is hidden — the
-            // faithful cull (decision 0031), computed per-frame by `crate::wmo_portal` and ANDed in here so
-            // it composes with the toggles + far-clip instead of a second Visibility writer. A submesh with
-            // no `WmoGroupVis` (every non-WMO entity, and a portal-less WMO) is never portal-culled; the
-            // panel's `portal_cull` switch disables it wholesale for an A/B against the old "draw every
-            // group" look.
+            // A WMO group no portal reaches is hidden; a part with no `WmoGroupVis` never is.
             let portal_visible = !m.portal_cull
                 || group_vis.is_none_or(|gv| {
                     instances
@@ -227,55 +174,33 @@ pub(super) fn apply_model_visibility(
                         .is_none_or(|inst| gv.drawn_by(inst))
                 });
 
-            // …and, off the SAME per-frame flood, which fog triple this piece's batch is pushed
-            // with: the client's per-group `[0xca7f00]` (wow-re round-6 Q-I — the group drawer
-            // `0x6b5190` and the group-doodad drawer `0x6b62e0` push the interior triple only under
-            // it; everything else inherits `push_fog`'s scene triple). `None` for every non-WMO
-            // entity, which leaves `INTERIOR_FOG_BIT` to the entity classifier — a unit's fog is
-            // staged by the unit's OWN classification, not by the room's gate.
+            // The same flood picks the fog: the group drawer `0x6b5190` and the group-doodad drawer
+            // `0x6b62e0` push the interior triple only under the per-group `[0xca7f00]`. `None`
+            // off-WMO leaves the bit to the entity classifier.
             let room_fog = group_vis.map(|gv| {
                 instances
                     .get(gv.instance)
                     .is_ok_and(|inst| gv.interior_fogged_by(inst))
             });
 
-            // The batch's animated material-alpha factor (decision 0130 phase 2): the sampled
-            // colour-alpha × transparency-weight loop, `1.0` for the untracked majority. Multiplied
-            // into the tag below, and into the cull here — the real client skips a batch whose
-            // combined alpha is ≤ 0 before even reading its blend mode (wow-re `m2-alpha-combine-cull`),
-            // so a flicker track at 0 hides the batch outright.
+            // The animated colour-alpha × transparency-weight factor, into the tag below and the
+            // cull here: the reference skips a batch whose alpha is ≤ 0 (`0x707b3a`).
             let mat_factor = mat_anim.map_or(1.0, |m| m.current);
 
-            // The exterior-scene window gate (decision 0774's law, decision 0784's placement):
-            // standing in a WMO interior, exterior content draws only through a portal window. ANDed
-            // in here rather than written by a second system, so it composes with everything above
-            // instead of overwriting it. Untagged content (units, GameObjects) is exempt by the
-            // carved law; the camera's own building is exempt because it is not exterior to itself.
+            // Inside a WMO, exterior content draws only through a portal window; untagged content
+            // (units, GameObjects) and the camera's own building are exempt.
             let own_building = group_vis.is_some_and(|gv| Some(gv.instance) == own_instance);
             let exterior_ok = !exterior || own_building || gate.admits(&xf, aabb);
 
-            // **A billboard card draws only while the model it is a batch OF draws** (decision
-            // 1409). A card is split out to a world root because its transform belongs to the
-            // billboard system, so it inherits nothing — and every hide that reaches its model
-            // through the scene graph (the exterior-scene election on a net root, a transport's
-            // off-map leg) reaches the card not at all. That is how an Orgrimmar bonfire's glow
-            // card went on burning over its own culled wood.
-            //
-            // The owner's `InheritedVisibility` is last propagate's — one frame of lag, the same
-            // accepted class as the interior law's. **Only on entity-lane cards**: a world-placement
-            // card is tagged `ExteriorScene` and `exterior_ok` above already gates it with the rest
-            // of its placement, while its owner is a joint of its own placement rig, which is never
-            // hidden apart from the model this system is already hiding whole.
-            // Fails OPEN on an unreadable owner: an owner that has gone is `face_billboards`'
-            // despawn case, and deciding a card's draw on absent information is how the world
-            // flickers.
+            // A billboard card draws only while its model does, by the owner's last-frame verdict.
+            // Entity-lane cards only: a placement's card is `ExteriorScene` and gated above. An
+            // unreadable owner fails open, as that is `face_billboards`' despawn case.
             let owner_hidden = !exterior
                 && card
                     .and_then(crate::billboard::BillboardCard::follows)
                     .is_some_and(|o| matches!(card_owners.get(o), Ok(v) if !v.get()));
 
-            // `Inherited` (not `Visible`) so child submeshes still respect a hidden parent root. A fully
-            // faded doodad (`fade_alpha == 0`) is culled just like an out-of-range one.
+            // `Inherited`, not `Visible`, so a hidden parent root still hides its children.
             let desired = if toggled_on
                 && in_range
                 && fade_alpha > 0.0
@@ -322,13 +247,9 @@ pub(super) fn apply_model_visibility(
             if let Some(mut tag) = tag {
                 let mut bits = tag.0;
                 if fade.is_some() || mat_anim.is_some_and(|m| !m.composes_unit_tag()) {
-                    // Glow cards render at AUTHORED brightness (decision 0159 — the dimmer knob died
-                    // with the faithful FFXGlow pass; the square-law is what keeps halos in check).
                     let alpha = fade_alpha * mat_factor;
-                    // `with_alpha` handles the `MeshTag == 0` opaque-sentinel (a *visible* glow card
-                    // dimmed to exactly 0 must not flip to full bright); a distance-faded doodad
-                    // (`fade_alpha == 0`) is Hidden anyway, so ≈0 bits there are equally fine.
-                    // Conventions: `crate::mesh_tag`.
+                    // `with_alpha` keeps a visible card dimmed to 0 off the `MeshTag == 0` opaque
+                    // sentinel.
                     bits = crate::mesh_tag::with_alpha(bits, alpha);
                 }
                 if let Some(on) = room_fog {
@@ -345,12 +266,9 @@ pub(super) fn apply_model_visibility(
                     } else {
                         &f.cutout
                     };
-                    // A feathering doodad on the eye's far side of the water plane takes the far
-                    // twin of the SAME pick (the water-plane interleave, `sky_order::FAR_SIDE_BIAS`)
-                    // — the classification is the marker's, the pick stays this system's. The
-                    // cutout never composes: an opaque draw settles against the water by depth. A
-                    // map miss = the twin isn't built yet (classify runs on transparent draws
-                    // only); keep the base and pick it up next frame.
+                    // A feathering doodad beyond the water plane takes its pick's far twin
+                    // (`sky_order::FAR_SIDE_BIAS`); an opaque draw settles by depth. A twin not
+                    // built yet keeps the base until next frame.
                     let want = if far_side && fade_alpha < 1.0 {
                         far_twins.far_of(base).unwrap_or(base)
                     } else {
@@ -364,14 +282,9 @@ pub(super) fn apply_model_visibility(
         },
     );
 
-    // The group-only audience — a building's MLIQ surfaces. Serial: a building has a handful of
-    // liquid surfaces, not the ~100k submeshes above — and change-gated like every write here.
-    //
-    // The gate is the **ever-visited latch**, not this frame's PVS: the client's render-record
-    // persistence (wow-re `wmo-record-persistence.md` @`00a766f6`) draws a visited MLIQ group's
-    // liquid every frame with no portal re-check for the rest of the world session — the Great
-    // Forge's walkway-level pool stays put when its group drops out of the flood (B65). An index
-    // past the latch fails OPEN (portal-less props never latch and must always draw).
+    // A building's MLIQ surfaces, gated by the ever-visited latch, not this frame's PVS: a group's
+    // liquid draws from its first visit for the rest of the placement's residency. An index past
+    // the latch fails open.
     for (gv, mut vis, xf, aabb, exterior, tag) in &mut group_only {
         let portal_ok = !m.portal_cull
             || instances.get(gv.instance).ok().is_none_or(|inst| {
@@ -379,19 +292,11 @@ pub(super) fn apply_model_visibility(
                     .iter()
                     .any(|&g| inst.liquid_visited.get(g as usize).copied().unwrap_or(true))
             });
-        // …and the same exterior-window term as the submesh walk: another building's canal is
-        // exterior content, the canal of the building you are standing in is not.
+        // The same exterior-window term as the submesh walk.
         let exterior_ok = !exterior || Some(gv.instance) == own_instance || gate.admits(xf, aabb);
-        // **A building's water rides the building's own toggle** — the reference's WMO liquid drain
-        // `0x684cd0` gates on `[0xc7b2a4] & 0x100`, the "Map objects" bit, NOT on the `0x1000000`
-        // "Water" bit the three ADT drains test (wow-re `terrain/scratch/liquid-window-gate.md` §5,
-        // decision 1657). Our `ModelKind::Wmo` toggle is that bit, and until now it hid a building
-        // and left its pool hanging in the air — which is also the shape a mis-placed pool takes, so
-        // the one instrument for telling those apart was itself producing the symptom.
-        //
-        // ADT liquid must NOT take this term and does not: it is `apply_exterior_cull`'s, which
-        // composes no toggles. The asymmetry is the reference's own, and it is per-*bit*, not an
-        // oversight to tidy up.
+        // A building's water rides the building's toggle: the reference's WMO liquid drain
+        // `0x684cd0` gates on the "Map objects" bit `[0xc7b2a4] & 0x100`, while the three ADT
+        // drains test the "Water" bit `0x1000000`. ADT liquid must not take this toggle.
         let toggled_on = m.kind_visible[kind_index(ModelKind::Wmo)];
         let want = if portal_ok && exterior_ok && toggled_on {
             Visibility::Inherited
@@ -401,13 +306,9 @@ pub(super) fn apply_model_visibility(
         if *vis != want {
             *vis = want;
         }
-        // …and the pool's fog lane, off the same per-frame flood as the room's walls (decision
-        // 1787). The reference's WMO liquid pass re-submits the interior fog block under the SAME
-        // `[0xca7f00]` as the geometry pass (wow-re `fog-env-state` §5's 6-site census), so a room
-        // and its water can never disagree; `liquid.wgsl` ANDs this with the surface's own static
-        // interior class. Note the term is the FLOOD's bit, not the ever-visited latch above: a
-        // pool the latch keeps drawing after its room left the PVS wears the scene fog, which is
-        // what the client's per-group toggle does with a group it is not currently walking.
+        // The pool's fog follows this frame's flood, not the latch, as the reference's WMO liquid
+        // pass pushes interior fog under the same `[0xca7f00]` as the geometry; a pool drawn by
+        // the latch alone wears scene fog. `liquid.wgsl` ANDs it with the surface's own class.
         if let Some(mut tag) = tag {
             let on = instances
                 .get(gv.instance)
@@ -420,42 +321,24 @@ pub(super) fn apply_model_visibility(
     }
 }
 
-/// `WOW_VIS_TRACE=<label-substring>` — **watch one model's placements decide, frame by frame.**
+/// `WOW_VIS_TRACE=<label-substring>` prints the verdicts of every model part whose `WorldObject`
+/// label contains it (any case), [`VIS_TRACE_HZ`] times a second, with `bound=` in world space:
 ///
-/// The `VIS_CENSUS` line counts what is drawn; it cannot answer "that thing vanished when I turned
-/// — who dropped it?". Two different systems can hide a model submesh and they fail in opposite
-/// directions:
-///
-/// - **`vis=Hidden`** — [`apply_model_visibility`] above said no: a toggle, the far-clip wall, a
-///   fully-faded doodad, an `A ≤ 0` material track, the portal PVS or the exterior window gate.
-/// - **`vis=Inherited inh=false`** — *this* part said yes and an **ancestor** said no. For a body
-///   part that is the exterior-scene election (decision 1270), which is decided once on the net
-///   root and inherits down; it is also how a transport hides its deck. Without this field the
-///   line was indistinguishable from the frustum case below — the election arrived after the
-///   trace did, and a body vanishing for the right reason would have read as a bound bug.
-/// - **`vis=Inherited inh=true view=false`** — everything of ours admitted it and **Bevy's frustum
-///   cull** dropped it, which means the entity's `Aabb` does not describe what it draws.
-///
-/// That second line is the whole of decisions 1259 and 1261 — an animated placement whose bound was
-/// its bind pose, and then the same bound silently recomputed at the twin swap — and both were
-/// diagnosed by reading code because nothing could be asked. `bound=` is printed in **world space**
-/// beside the camera, so "the box is nowhere near the bird" is visible directly rather than inferred.
-///
-/// Off (the env var unset) this system is one `Option` check per frame and no query iteration.
-/// Throttled to [`VIS_TRACE_HZ`]; matching is a case-insensitive substring of the `WorldObject`
-/// label (a model path), so `WOW_VIS_TRACE=bird01` follows every bird in residency.
+/// - `vis=Hidden`: [`apply_model_visibility`] said no.
+/// - `vis=Inherited inh=false`: an ancestor said no (the exterior-scene election, a transport).
+/// - `vis=Inherited inh=true view=false`: Bevy's frustum cull dropped it, so its `Aabb` does not
+///   describe what it draws.
 #[derive(Resource)]
 pub struct VisTrace {
     needle: String,
     next_at: f32,
 }
 
-/// Trace lines per second — enough to watch a verdict flip under a camera swing, sparse enough that
-/// a dozen placements don't bury the log.
+/// Trace passes per second.
 const VIS_TRACE_HZ: f32 = 4.0;
 
 impl VisTrace {
-    /// `None` unless `WOW_VIS_TRACE` names a substring — the whole cost of the instrument when off.
+    /// `None` unless `WOW_VIS_TRACE` names a substring.
     pub(crate) fn from_env() -> Option<Self> {
         std::env::var("WOW_VIS_TRACE")
             .ok()
@@ -467,8 +350,7 @@ impl VisTrace {
     }
 }
 
-/// What the trace reads per submesh: its identity, where it is, both verdicts, and the bound the
-/// second of them tested.
+/// What the trace reads per submesh.
 type TracedModels<'w, 's> = Query<
     'w,
     's,
@@ -478,20 +360,15 @@ type TracedModels<'w, 's> = Query<
         &'static GlobalTransform,
         &'static Visibility,
         &'static InheritedVisibility,
-        // `Option`: a chain-only node (anim host root — `crate::vis_chain`) has no sweep row;
-        // it must still appear in the trace rather than silently vanish from the instrument.
+        // A chain-only node (an anim host root) has no `ViewVisibility` but still traces.
         Option<&'static ViewVisibility>,
         Option<&'static Aabb>,
-        // Which lane the row is: a world-root billboard CARD inherits nothing, so `inh=true` on it
-        // means only "no parent", never "my model is drawn" — the one row where the second field
-        // must not be read as the owner's verdict (decision 1409).
+        // A billboard card inherits nothing, so its `inh=true` means only "no parent".
         Has<crate::billboard::BillboardCard>,
     ),
 >;
 
-/// The trace's printer — see [`VisTrace`]. Runs after the authority so `vis` is this frame's
-/// verdict, and reads `ViewVisibility` (last frame's frustum result, which is the freshest a
-/// same-frame reader can have) to separate our gates from the cull.
+/// Prints [`VisTrace`]; runs after the authority, so `vis` is this frame's and `view` last frame's.
 pub(super) fn trace_model_visibility(
     time: Res<Time>,
     trace: Option<ResMut<VisTrace>>,
@@ -512,9 +389,7 @@ pub(super) fn trace_model_visibility(
         if !object.label.to_ascii_lowercase().contains(&trace.needle) {
             continue;
         }
-        // World-space bound: the entity transform applied to the local box, which is exactly what
-        // Bevy's cull tests — so a bound that has parted company with the geometry shows up here as
-        // a centre nowhere near what the eye sees.
+        // The world-space bound Bevy's cull tests.
         let (centre, radius) = match aabb {
             Some(a) => (
                 xf.transform_point(Vec3::from(a.center)),
@@ -530,7 +405,7 @@ pub(super) fn trace_model_visibility(
              cam=[{px:.1},{py:.1},{pz:.1}]",
             label = object.label,
             inh = inherited.get(),
-            // "-" = chain-only node, no sweep row (never drawn, so no per-view verdict exists).
+            // "-": a chain-only node, never drawn.
             view = view.map_or("-".into(), |v| v.get().to_string()),
             ox = xf.translation().x,
             oy = xf.translation().y,
@@ -552,15 +427,6 @@ mod tests {
     use benilla_assets::BillboardInfo;
     use benilla_formats::{BillboardKind, ModelBlend};
 
-    /// **A billboard card draws only while the model it is a batch of draws** (decision 1409).
-    ///
-    /// A card is split out to a world root — its transform belongs to the billboard system — so
-    /// nothing carries its owner's hide to it. `billboard::face_billboards` used to mirror that
-    /// hide, and its own unit test proved it wrote `Hidden`; the write was thrown away every frame
-    /// because `BillboardPlace` is ordered only `before(CheckVisibility)`, so it landed after the
-    /// propagation that would have consumed it and this system overwrote it with `Inherited` in
-    /// the next `Update`. In Orgrimmar that was a bonfire's glow card burning over its own culled
-    /// wood. The term lives here now, where nothing runs after it.
     #[test]
     fn a_card_follows_its_owners_verdict() {
         let mut app = App::new();
@@ -614,8 +480,7 @@ mod tests {
             Visibility::Inherited,
             "a re-shown owner restores its card"
         );
-        // …and the owner going away must NOT blank the card: that is `face_billboards`' despawn
-        // case, and deciding a draw on absent information is how the world flickers.
+        // An owner going away must not blank the card: that is the despawn case.
         app.world_mut().entity_mut(owner).despawn();
         app.update();
         assert_eq!(
@@ -625,15 +490,8 @@ mod tests {
         );
     }
 
-    /// **A building's pool rides the building's own toggle** (decision 1657) — and ADT liquid must
-    /// not, which is the half that makes this a fidelity fact rather than a tidy-up.
-    ///
-    /// The reference gates its WMO liquid drain `0x684cd0` on `[0xc7b2a4] & 0x100`, the "Map
-    /// objects" bit, while the three ADT drains test the separate `0x1000000` "Water" bit (wow-re
-    /// `terrain/scratch/liquid-window-gate.md` §5). `ModelKind::Wmo` is our "Map objects" bit, and
-    /// without this term switching buildings off left every canal, fountain and dungeon pool
-    /// hanging in mid-air — which happens to be exactly what a mis-placed pool looks like, so the
-    /// one instrument for telling a water bug from a wall bug was manufacturing the symptom.
+    /// The reference's WMO liquid drain `0x684cd0` gates on the "Map objects" bit
+    /// `[0xc7b2a4] & 0x100` (`ModelKind::Wmo`), not the ADT drains' "Water" bit `0x1000000`.
     #[test]
     fn a_wmo_pool_rides_the_map_objects_toggle() {
         let mut app = App::new();
@@ -643,9 +501,8 @@ mod tests {
             .init_resource::<crate::wmo_portal::CameraInteriorClaim>()
             .init_resource::<super::super::FarSideTwins>()
             .add_systems(Update, apply_model_visibility);
-        // A portal-less prop's pool: `WmoGroupVis` with no `ModelPart` (the `group_only` audience),
-        // and an instance that carries no latch, so `portal_ok` fails open and the toggle is the
-        // only term in play.
+        // A portal-less prop's pool: its instance has no latch, so `portal_ok` fails open and the
+        // toggle is the only term in play.
         let instance = app.world_mut().spawn(()).id();
         let pool = app
             .world_mut()
@@ -676,8 +533,7 @@ mod tests {
             "buildings off: the water goes with the building, not on without it"
         );
 
-        // The control: the toggle that is NOT the Map-objects bit must not reach a pool. Doodads
-        // off leaves the canal alone — a single `kind_visible` bool ANDed carelessly would take it.
+        // The control: the doodad toggle must not reach a pool.
         app.world_mut()
             .resource_mut::<DebugState>()
             .models
diff --git a/crates/benilla-world/src/modkeys.rs b/crates/benilla-world/src/modkeys.rs
index 08826194..afa7bf62 100644
--- a/crates/benilla-world/src/modkeys.rs
+++ b/crates/benilla-world/src/modkeys.rs
@@ -1,84 +1,33 @@
-//! **The modifier keys** — the dev-overlay chord every instrument is bound on, and the
-//! stuck-modifier reconciliation that keeps the keyboard honest underneath it.
+//! The modifier keys: the dev-overlay chord every instrument is bound on, and the stuck-modifier
+//! reconciliation beneath it.
 //!
-//! The chord ([`dev_chord`]) lived in `debug_panel` because the panel was its first user; six
-//! modules then reached into a *debug overlay* to ask whether Ctrl+Shift was down — the player
-//! controller's free-fly toggle and land-here, the perf HUD, the sound mute, the inspector.
-//! Decision 1160 moves it here, where the leaf module that already owns modifier state is
-//! (92 lines, no dependants of its own). Nothing about "which two modifiers are the dev plane" is
-//! a debug-panel opinion.
-//!
-//! ## Stuck-modifier reconciliation against the OS's live flag state (decision 0606)
-//!
-//! macOS system shortcuts that grab the keyboard *without* de-focusing the window — the ⇧⌘5
-//! screenshot overlay is the canonical one — swallow the modifiers' release events: the overlay is
-//! a non-activating panel, so the app never receives `Focused(false)` (Bevy's stuck-key reset,
-//! `KeyboardFocusLost` → `release_all`, never fires), and winit only synthesizes modifier key
-//! events from `flagsChanged`, which the grabbed keyboard never delivers (verified in
-//! winit 0.30.13 `platform_impl/macos/view.rs::update_modifiers`). `ButtonInput<KeyCode>` then
-//! reports Shift/Cmd held indefinitely, and every bare-key binding — the action bar's number row
-//! behind `ui_script::input`'s bare-binding gate — goes dead until the user happens to tap the
-//! stuck modifier again.
-//!
-//! The fix: poll the OS's live modifier state (`+[NSEvent modifierFlags]` — hardware-derived and
-//! documented as independent of the event stream) once per frame, right after Bevy's own input
-//! collection, and **release** any modifier Bevy believes is down but the OS says is up.
-//! Release-only by design: the hardware state leads the event stream, so a legitimately
-//! just-pressed modifier is never wrongly released — whereas synthesizing *presses* from the poll
-//! could race in-flight release events and manufacture the same bug in reverse. The poll can't
-//! tell left from right within a family, so an up family releases both variants (only ever a
-//! correction — a genuinely held key keeps its family bit set and is never touched).
+//! A macOS shortcut that grabs the keyboard without de-focusing the window (the ⇧⌘5 screenshot
+//! overlay) swallows the modifiers' release events: no focus loss arrives, and winit synthesizes
+//! modifier events only from `flagsChanged`, which the grab withholds. Shift or Cmd then stays
+//! held and every bare-key binding goes dead. Each frame after Bevy's input collection, any
+//! modifier the OS's live state (`+[NSEvent modifierFlags]`) reports up is released, both sides of
+//! its family. Release only: synthesized presses could race in-flight release events.
 
 use bevy::prelude::*;
 
-/// How the dev plane is written on screen. Every surface that names a chord reads this instead of
-/// spelling one out, so the panel footer, the inspector badge and the mute checkbox can't drift from
-/// what [`dev_chord`] actually listens for.
+/// How the dev plane is written on screen; every surface that names the chord reads this.
 pub const DEV_CHORD: &str = "Ctrl+Shift";
 
-/// Did the **dev-overlay chord** — [`DEV_CHORD`]+*key* — just fire? (decisions 0585, 0867, 0870,
-/// 1043 — which moved the last two dev keys onto it, so the whole fleet is here now.)
+/// Whether the dev-overlay chord, [`DEV_CHORD`] + `key`, just fired. Exactly Ctrl and Shift, either
+/// side: Alt and Super block it, since AltGr is Ctrl+Alt and AltGr+Shift+key typed into chat must
+/// not fire. Of the reference's 152 default bindings only `CTRL-SHIFT-TAB` and
+/// `CTRL-SHIFT-PAGEDOWN` use this plane, and no letter does. Not gated on
+/// `ui_script::UiKeyboardCapture`: a chord is never typed text.
 ///
-/// The dev instruments used to sit on bare letters, which is a namespace we don't own: every letter is
-/// a *game* binding in the reference client, so `P` both opened the spellbook and toggled the perf HUD
-/// (0585). They moved to `Ctrl`+`Cmd`, and then off it: on Windows that is `Ctrl`+`Win`, a plane the
-/// shell owns and keeps extending — `Win+Ctrl+M` is Magnifier settings, which had our mute (0867).
-///
-/// **`Ctrl`+`Shift`, one plane on every OS** (0870, director's call). The alternative was keeping
-/// `Ctrl`+`Cmd` on macOS for its one real advantage — Cmd is outside the reference's binding namespace
-/// (1.12 builds binding names from `ALT-`/`CTRL-`/`SHIFT-` only), so nothing in game could *ever* claim
-/// it. That buys protection against a binding no default declares and no player has yet written, and
-/// it costs a per-OS split in the docs, the hints and the reader's head. One plane wins. It also drops
-/// our dependence on winit's `sendEvent:` swizzle, without which AppKit's swallowed `keyUp` under Cmd
-/// would latch a chord after one use (0585's macOS risk, now simply not run).
-///
-/// `Ctrl`+`Shift` is the emptiest plane the reference *can* name: of its 152 defaults, exactly two
-/// carry two modifiers — `CTRL-SHIFT-TAB` and `CTRL-SHIFT-PAGEDOWN` — and no letter at all.
-/// `Ctrl`+`Alt` was never available: that is AltGr, which European layouts type real characters with
-/// (decision 0702).
-///
-/// **Exactly those two modifiers and no others**, both sides of each. The block is what makes this
-/// plane safe to leave ungated below: AltGr+Shift+*key* is `Ctrl`+`Alt`+`Shift`+*key*, and a German
-/// layout typing one of those into chat must not fire an overlay.
-///
-/// **"No letter at all" was half the story, and the missing half cost us a plane's worth of safety**
-/// (decision 1142). The reference does not match bindings by equality alone: an exact miss re-probes
-/// **once** with the leftmost modifier dropped, so `CTRL-SHIFT-`*key* falls through to
-/// `SHIFT-`*key* — never to the bare letter, which is why this plane survived the correction at all,
-/// but far enough that `Ctrl`+`Shift`+`P` would open the pet paper doll (`SHIFT-P`,
-/// `TOGGLECHARACTER3`) under the perf HUD. So the other half of the rule now lives where the law
-/// itself does, in `bindings::BindingDispatch::resolve`: this plane spends the keyboard's
-/// **fallback probe**, and only that — an exact `CTRL-SHIFT-` binding, the reference's two included,
-/// still dispatches normally.
-///
-/// Deliberately **not** gated on [`crate::ui_script::UiKeyboardCapture`] the way the bare-key toggles
-/// were: a chord can't be mistaken for typed text, so the dev overlays stay reachable with the chat bar
-/// open.
+/// Deviation: the reference (`0x4b7990`) retries a binding miss once without the leftmost
+/// modifier, so `CTRL-SHIFT-P` would reach `SHIFT-P` (`TOGGLECHARACTER3`, the pet paper doll); in
+/// a run with dev affordances `bindings::BindingDispatch::resolve` skips that retry on this plane,
+/// because a dev chord must open nothing in game. An exact `CTRL-SHIFT-` binding still dispatches.
 pub fn dev_chord(keys: &ButtonInput<KeyCode>, key: KeyCode) -> bool {
     dev_plane(keys) && keys.just_pressed(key)
 }
 
-/// The modifier half of [`dev_chord`]. See there for why the plane is what it is.
+/// The modifier half of [`dev_chord`].
 fn dev_plane(keys: &ButtonInput<KeyCode>) -> bool {
     let ctrl = keys.any_pressed([KeyCode::ControlLeft, KeyCode::ControlRight]);
     let shift = keys.any_pressed([KeyCode::ShiftLeft, KeyCode::ShiftRight]);
@@ -91,22 +40,13 @@ fn dev_plane(keys: &ButtonInput<KeyCode>) -> bool {
     ctrl && shift && !blocked
 }
 
-/// Keys a **synthetic** input source is holding this frame — the probe harness's `WOW_PROBE_KEY`
-/// taps are the only writer today.
-///
-/// The reconciliation above polls the *hardware* flag state, which by construction reads "up" for
-/// a key no hand is on. Without this list a synthesized `Shift`/`Ctrl` is released the frame after
-/// it is pressed — and logged as a stuck-key correction, so the instrument reads as working while
-/// **no probe can reach a chord binding on macOS at all** (`SHIFT-V`'s friendly nameplates, the
-/// `Ctrl`+`Shift`+`F` free-fly the `"Shift"` tap name was added for). The engine owns the type
-/// because the reconciler does; whoever synthesizes input writes it, on every platform.
+/// Keys a synthetic input source (the probe's `WOW_PROBE_KEY` taps) holds this frame, written by
+/// whatever synthesizes input on every platform: the reconciler's hardware poll reads them as up
+/// and would release them a frame after the press.
 #[derive(Resource, Default)]
 pub struct SyntheticHold(pub Vec<KeyCode>);
 
-/// Is `code` a modifier Bevy holds down that nothing is legitimately holding — i.e. stuck, and the
-/// reconciler's to release? Pure, so the rule is testable off-platform (the reconciler itself
-/// needs AppKit and the main thread) — which is also why it is compiled for the test build of
-/// every platform, and only there off macOS.
+/// Whether Bevy holds `code` down with no synthetic source holding it: stuck, if the OS says up.
 #[cfg(any(target_os = "macos", test))]
 fn is_stuck(code: KeyCode, pressed: &ButtonInput<KeyCode>, hold: &SyntheticHold) -> bool {
     pressed.pressed(code) && !hold.0.contains(&code)
@@ -167,9 +107,8 @@ mod mac {
             if flags.contains(flag) {
                 continue;
             }
-            // Guarded so an in-sync frame (the overwhelmingly common case) never marks the
-            // resources changed — and a key a synthetic source is holding
-            // ([`super::SyntheticHold`]) is never "stuck": the hardware poll cannot see it.
+            // Guarded so an in-sync frame never marks the resources changed; a synthetic hold is
+            // never stuck, since the hardware poll cannot see it.
             let mut synthetic = false;
             for code in keys {
                 if super::is_stuck(code, &codes, &hold) {
@@ -210,11 +149,7 @@ mod tests {
         }
     }
 
-    /// One modifier is not the chord, and a third one names something else. The case that matters:
-    /// AltGr *is* `Ctrl`+`Alt`, so AltGr+Shift+key is a character a European layout types, never a
-    /// dev chord — the overlays are ungated while the chat bar is open. `Ctrl`+`Cmd` is likewise
-    /// nothing of ours now (0870): on Windows it is the shell's, `Win+Ctrl+M` being Magnifier
-    /// settings.
+    /// AltGr is Ctrl+Alt, so AltGr+Shift+key is typed text, never the chord.
     #[test]
     fn a_lone_or_extra_modifier_is_not_the_chord() {
         for held in [
@@ -228,11 +163,6 @@ mod tests {
         }
     }
 
-    /// A modifier a **synthetic** source is holding is never "stuck". The macOS reconciler polls
-    /// the hardware flags, which read up for a key no hand is on — so without the exemption a
-    /// synthesized chord dies the frame after it is pressed, and every `WOW_PROBE_KEY` chord
-    /// (`SHIFT-V`'s friendly nameplates, `Ctrl`+`Shift`+`F`'s free-fly) is unreachable on the
-    /// platform we develop on, while the log calls it a stuck-key fix.
     #[test]
     fn a_synthesized_modifier_is_not_stuck() {
         let held = keys(&[KeyCode::ShiftLeft]);
@@ -249,8 +179,6 @@ mod tests {
         );
     }
 
-    /// The label a hint prints is the plane actually listened for — one const, one predicate, so a
-    /// player is never told to press a key we stopped reading.
     #[test]
     fn the_label_matches_the_plane() {
         assert_eq!(DEV_CHORD, "Ctrl+Shift");
diff --git a/crates/benilla-world/src/particles.rs b/crates/benilla-world/src/particles.rs
index c6a2b3d3..b47622c2 100644
--- a/crates/benilla-world/src/particles.rs
+++ b/crates/benilla-world/src/particles.rs
@@ -1,27 +1,8 @@
-//! Faithful M2 particle emitters — the visible fire/glow of campfires, torches, braziers and candles.
-//!
-//! The 1.12 client simulates particles on the CPU and draws them as camera-facing, additive quads; we
-//! do the same (the GPU never touched the legacy particle path, and a CPU sim is the only way to match
-//! the integrator exactly — see decision 0014). Each [`ParticleEmitter`] owns a small pool of live
-//! particles: every frame we age + integrate the pool, then expand each live particle into a
-//! camera-facing quad written into the **shared effect-quad stream** ([`buffer::EffectQuads`],
-//! decision 0732 slice P1 — one CPU vertex vec + one GPU upload for the whole family, drawn by
-//! the dedicated lane in [`render`]; per-emitter `Mesh`/material assets are gone, and with them
-//! the per-frame allocator churn they priced). Every cloud is **anchored to its MODEL's live
-//! position** (the reference rebuilds the
-//! draw matrix with `translate(−emitterPos)` each frame — a moving model carries its flame, no
-//! world-frozen trails) while the emitter's BONE composes only each particle's birth: bone motion
-//! is baked per particle (an emitter orbiting on an animated bone — the food sparkle's global-
-//! sequence spin — births a moving ring of straight risers, never a swirling cloud; the client's
-//! only live-follow plumbing is file flag `0x4000`, unauthored by our content). File flag `0x10`
-//! additionally folds the live bone ROTATION at render instead of baking it at birth —
-//! byte-verified, wow-re `part-simspace-fields.md` + its `1f40db0b` corrections. The lane's
-//! fragment does the vanilla gamma-space combine (`shaders/wow_effect.wgsl`, decisions
-//! 0152/0161). The whole effect family — particles, ribbons, the decal family, water foam,
-//! precipitation — draws through the lane; `WowParticleMaterial` retired with slice P2 (0733).
-//!
-//! Over-life colour (incl. the alpha that is the additive weight), size and texture-cell are sampled
-//! from the parsed [`benilla_formats::OverLife`] ramp by the particle's normalized age.
+//! M2 particle emitters, simulated on the CPU as the 1.12 client does: each [`ParticleEmitter`]
+//! ages and integrates its pool every frame and expands it into camera-facing quads in the shared
+//! effect stream ([`buffer::EffectQuads`]) that the effect lane ([`render`]) draws. File flag
+//! `0x10` picks a particle's storage frame, and so whether a moving host leaves a trail; colour,
+//! alpha, size and texture cell follow the [`benilla_formats::OverLife`] ramp by normalized age.
 
 use benilla_assets::ModelEmitter;
 use benilla_formats::ParticleEmitterDef;
@@ -35,48 +16,28 @@ mod emitdump;
 mod model;
 mod quads;
 pub mod render;
-pub(crate) mod sim; // `SceneGates` is the ribbon sim's draw-set input too (decision 1294)
+pub(crate) mod sim; // `SceneGates` is the ribbon sim's draw-set input too
 
 use emit::{emit_local, next_u32, rand01, rand_s11};
 use sim::simulate_particles;
-// The water-plane interleave classification — shared with the ribbon sim (a trail is one of the
-// model's emitters and classifies the same way; `sky_order::FAR_SIDE_BIAS`).
+// The water-plane classification, shared with the ribbon sim.
 pub(crate) use sim::{far_side_of_water, model_far_side, water_height, WaterInterleave};
 
-/// This camera is **rate-throttled**: it renders on some frames and skips others *by our own
-/// pacing*, while the scene behind it keeps running at full rate. A frame it does not draw is a
-/// SKIPPED frame, not a sleeping scene — so the lanes that freeze with a sleeping booth camera
-/// ([`sim::simulate_particles`]) must keep simulating through it.
-///
-/// The distinction is the whole point (decision 1559). The draw-set law — an emitter ticks only
-/// inside a draw the frame performs, one frame's dt, no catch-up — is the *reference's*, and it
-/// is keyed on the reference's own cull. `boothHalfRate` (decision 1444) is **ours**: a camera it
-/// skips has a scene that is still posing at full rate (the skeleton's `AnimParked` keys on the
-/// booth's LOGICAL active state, never on the rendered frame). Reading our skip as the
-/// reference's cull ran the body panes' item emitters at half speed — director report B312,
-/// which 1444's own record had flagged as the law's honest consequence and which is not: our
-/// throttle must not reach the simulation at all.
-///
-/// Maintained on the booth camera entity by `portrait::gate_booth_cameras`, which owns both
-/// halves of the state (the logical `active` and the physical `render`). It marks the *regime*,
-/// not the parity — it is present for as long as the camera is being paced, on drawn frames and
-/// skipped ones alike, so the archetype does not churn every frame.
+/// A camera our own pacing (`boothHalfRate`) skips on some frames while its scene poses at full
+/// rate. The reference's draw-set law (a tick only in a drawn frame, no catch-up) keys on its cull,
+/// not this skip, so emitters keep simulating through it. `portrait::gate_booth_cameras` keeps it
+/// on for as long as the camera is paced, so the archetype does not churn.
 #[derive(Component)]
 pub struct ViewThrottled;
 
-/// Hard cap on a single emitter's live particle count — a backstop against a pathological model. Real
-/// props sit far under this (a campfire's steady state is `rate·lifespan` ≈ 30 + 24 particles).
+/// A backstop cap on one emitter's live particles; a campfire's steady state is about 30 + 24.
 const MAX_PARTICLES: usize = 1024;
 
-/// Live particle tuning, driven by the debug panel. Holds only the reference's own
-/// `particleDensity` CVar — a real game setting, not a dev knob. (The intensity/size/tint A/B
-/// sliders — director-confirmed compensation for since-fixed source bugs, 0150/0152 — are gone;
-/// the authored values are the only path.)
+/// Particle settings: the reference's `particleDensity` CVar, set from the debug panel.
 #[derive(Resource)]
 pub struct ParticleTuning {
-    /// The vanilla `particleDensity` CVar (byte-verified: handler `0x688fb0` clamps to
-    /// [0.25, 1.0], the getter's only two callers are the spawn-count `fmul`s). Scales emission
-    /// RATE only — never size, alpha, or draw distance. Default 1.0.
+    /// Clamped to [0.25, 1.0] by its handler (`0x688fb0`); it scales emission rate only (its
+    /// getter's two callers are the spawn-count `fmul`s), never size, alpha or draw distance.
     pub(crate) density: f32,
 }
 
@@ -86,206 +47,113 @@ impl Default for ParticleTuning {
     }
 }
 
-/// One live particle. Its frame is the emitter's storage space, which the file flag `0x10` picks
-/// — and the two spaces are the whole of the ride-vs-trail law (wow-re `part-emitter-motion.md`
-/// §2c-B, byte-settled; decision 1585):
-/// - **World mode** (flag `0x10` CLEAR — ~70 % of the corpus): `pos`/`vel` are **absolute world
-///   coordinates, Bevy axes**. The birth bakes everything — bone pose, model rotation, scale,
-///   position — through the live emitter matrix (`0x7b8acf`/`0x7b8b0f`), and the draw folds
-///   **nothing** back (`0x7b3f48` omits `rt+0x1fc`). Once a particle exists, no later act of its
-///   host can reach it: run, turn, or play any animation and the cloud hangs exactly where it was
-///   born, which is what makes a trail of length `host speed × particle lifetime`. Gravity is
-///   plain world down (Bevy `-Y`).
-/// - **Model mode** (`0x10` SET): `pos`/`vel` are the emitter's **local WoW model space** (Z up)
-///   and the draw re-applies the whole live placement transform every frame, rotation included
-///   (`0x7b8aa5`/`0x7b3efb`) — the rigid ride a carried torch (`Club_1H_Torch_A_01.m2` = `0x0011`)
-///   is flagged for, and the chandelier's flames riding its swing.
-///
-/// Storing world-relative coordinates and re-composing them against a live frame — which is what
-/// this comment described until 1585 — cannot express the CLEAR case: it can be made to cancel a
-/// host's translation, but its rotation still reaches every particle already born.
+/// One live particle, in the frame file flag `0x10` picks. Clear (world mode): `pos`/`vel` are
+/// world coordinates, Bevy axes (a transport's deck while riding one); the birth bakes bone pose,
+/// rotation, scale and position through the live emitter matrix (`0x7b8acf`/`0x7b8b0f`) and the
+/// draw folds nothing back (`0x7b3f48` omits `rt+0x1fc`), so a moving host leaves a trail. Set
+/// (model mode): `pos`/`vel` are WoW model space, Z up, and the draw re-applies the live placement
+/// (`0x7b8aa5`/`0x7b3efb`), the rigid ride of a carried torch.
 struct Particle {
     pos: Vec3,
     vel: Vec3,
     age: f32,
-    /// This particle's lifetime, captured at birth from the emitter's **current sampled**
-    /// lifespan channel (the reference passes it into each spawn as the kernels' `life_param` —
-    /// wow-re `part-shape-kernels.md`; the channel ANIMATES, e.g. Frost Nova 0.47 → 0.80 s, so a
-    /// shared `def.lifespan` is wrong twice over). Kill at `age >= life`; over-life ramps
-    /// normalize by it.
+    /// The emitter's lifespan channel sampled at birth (it animates: Frost Nova's runs 0.47 to
+    /// 0.80 s). The particle dies at `age >= life`, and its over-life ramps normalize by it.
     life: f32,
-    /// Spawn-time random phase for the twinkle LUT index (the reference hashes the particle's
-    /// pointer; same role — de-sync the flicker across particles).
+    /// A random twinkle-table phase; the reference hashes the particle's pointer to the same end.
     phase: u32,
-    /// The reference's particle+0xd bit 1 (set at spawn, cleared on the first integrate): a
-    /// particle's first frame skips the follow-delta add (wow-re `part-emitter-motion.md` §2).
+    /// `particle+0xd` bit 1: the first integrate skips the follow-delta add (`0x7b2680`).
     fresh: bool,
-    /// MODEL particles only (wow-re `part-model-particles.md`): the instance orientation
-    /// (stored frame; seeded from the birth fold) and its body-frame angular velocity — the
-    /// integrator applies the Rodrigues half-angle spin whenever `angvel` is non-zero. Quad
-    /// particles carry identity/zero.
+    /// Geometry particles only (`0x7b2420`, integrator `0x7b28e0`): stored-frame orientation and
+    /// body-frame angular velocity; a quad particle carries identity and zero.
     quat: Quat,
     angvel: Vec3,
 }
 
 impl ParticleEmitter {
-    /// The rig bone this emitter is mounted on — the scope key the depth probes filter by
-    /// (`$WOW_DEPTH_QUADS`, `$WOW_PARTICLE_DEPTHDUMP_BONES`).
+    /// The rig bone this emitter is mounted on, which the depth probes filter by.
     pub fn bone(&self) -> u16 {
         self.def.bone
     }
 }
 
-/// A spawned particle emitter: its parsed def + the placement that maps its local space to the world,
-/// the live pool, the fractional emission accumulator, and a per-emitter RNG; its quads go into
-/// the shared effect stream ([`buffer::EffectQuads`]) each frame. Despawns with its placement
-/// (the entity joins the placement's entity list).
+/// One spawned emitter: def, placement, live pool and emission state.
 #[derive(Component)]
 pub struct ParticleEmitter {
     def: ParticleEmitterDef,
-    /// Model→world (Bevy space): `world = placement · wow_to_bevy(local)`. Carries the placement scale.
-    /// Static for terrain doodads; refreshed each frame from [`Self::owner`] when set.
+    /// Model to world, Bevy space, refreshed from [`Self::owner`] when set.
     placement: Transform,
-    /// **The frame this cloud's WORLD-mode particles are stored in** — world on the ground, the
-    /// transport's deck while the owning model rides one ([`crate::ride_frame`], decision 1591).
-    ///
-    /// The `0x10` CLEAR store bakes a birth into absolute coordinates and never re-applies a live
-    /// matrix, which is what makes a trail. On a transport that leaves a rider's cloud behind the
-    /// vehicle, so the reference divides the ride matrix out at birth (`rt+0x1fc = srcMx · A⁻¹`)
-    /// and folds it back at draw (`0xcf5b68 = A · T · S`). MODEL-mode (`0x10` SET) emitters take
-    /// the verbatim-copy arm and never see `A` at all — they already ride their host rigidly.
+    /// World-mode particles' frame: world, or a ridden transport's deck ([`crate::ride_frame`]),
+    /// as the reference divides the ride matrix out at birth (`rt+0x1fc = srcMx · A⁻¹`) and folds
+    /// it back at draw (`0xcf5b68 = A · T · S`), so a rider's cloud does not trail the vehicle.
     pub(crate) ride: crate::ride_frame::StoredFrame,
-    /// The entity this emitter belongs to, if it follows one (a streamed creature/GameObject). Each
-    /// frame the emitter copies the owner's world transform into [`Self::placement`] (so it tracks a
-    /// moving prop) and **drains** once the owner is gone. `None` for terrain doodads, which carry
-    /// a fixed placement and despawn with their placement instead.
+    /// The entity followed, whose world transform becomes [`Self::placement`] each frame.
     owner: Option<Entity>,
-    /// What losing [`Self::owner`] means for this emitter — the spawn site's call, because only it
-    /// knows whether the owner entity going away is a MODEL BEING DESTROYED or an effect ending
-    /// (see [`OwnerLoss`]).
     on_owner_loss: OwnerLoss,
-    /// The owner died and this emitter is [`OwnerLoss::Drain`]: emission stops, the pool lives out
-    /// its lifespans at the frozen placement, and the emitter despawns itself when empty — live
-    /// particles finish instead of popping. Byte ground (wow-re
-    /// `ribbon-basis-emitter-lifecycle`, the 0202 dispatch's fold-back): the reference frees
-    /// emitters synchronously at the model dtor, its fade coming from the model staying alive
-    /// while emitters drain (the `HasLiveParticles` latch keeps a disabled emitter ticking) —
-    /// this drain reproduces that defer-until-drained shape from the owner side; see
-    /// `ribbons::RibbonTrail::owner` for the one OPEN half.
+    /// Draining after the owner's loss: no emission, the pool ages out in place, then despawns, as
+    /// the reference's `HasLiveParticles` latch (`0x7b5f60`) keeps a disabled emitter ticking.
     draining: bool,
-    /// The model instance whose [`crate::model_fade::ModelAlpha`] this cloud is multiplied by —
-    /// the reference's `emitter+0x1a8`, a per-frame copy of that model's `+0x19c` (`0x718960`
-    /// @`0x719073`), folded into each particle's ALPHA by the over-life sampler (`0x7b9b10`
-    /// @`0x7b9b42`; wow-re `part-scene-multipliers.md` §4's REFUTED negative + `part-additive-
-    /// combine.md` §6.1). For an ATTACHED model — a held item, a helm, a pauldron — it is the
-    /// WEARER's, because an attached model inherits its parent's computed alpha (decision 0827).
-    /// `None` ⇒ 1.0: a placed doodad instead multiplies its own distance fade ([`EmitterFade`]).
+    /// The model instance whose composed alpha multiplies this cloud: the reference's
+    /// `emitter+0x1a8`, a per-frame copy of the model's `+0x19c` (`0x718960` @`0x719073`) folded
+    /// in by the over-life sampler (`0x7b9b10` @`0x7b9b42`). A doodad multiplies its distance fade.
     alpha_src: Option<Entity>,
-    /// This frame's value of that alpha (1.0 until read).
     alpha: f32,
-    /// The **cloud anchor**: the entity whose live translation is this pool's SORT point (the
-    /// MODEL — a creature root, an effect-instance root, a held item's root), NOT the emitter's
-    /// bone joint. Since 1585 it carries no particle position — a world-mode store is frozen at
-    /// birth and a sort key is not a vertex — so this is a depth-ordering input only.
-    /// `None` = sort at the spawn placement (a placed doodad whose emitter rides a joint sorts at
-    /// the doodad, not the bone).
+    /// The model (never the bone joint) whose live translation is this pool's sort point, and
+    /// only that: a world-mode store is frozen at birth. `None` sorts at the spawn placement.
     anchor: Option<Entity>,
-    /// The object's **light node** — the entity whose [`crate::interior::ParticleLight`] this
-    /// cloud takes when it is LIT and standing in a WMO room. Held so a recursion CHILD that
-    /// wires up lit under an unlit parent can still register the edge
-    /// ([`wire_child_emitters`]); the [`crate::interior::EmitterLitBy`] component on this entity
-    /// is what the classifier actually walks.
+    /// The object's light node ([`crate::interior::ParticleLight`]), held so a lit child wired
+    /// under an unlit parent can register its edge late ([`wire_child_emitters`]).
     light_node: Option<Entity>,
-    /// The anchor's last-known world translation (kept when the entity vanishes so the pool
-    /// drains in place; init = the spawn placement's translation).
+    /// The anchor's last known world translation, kept so a draining pool stays in place.
     anchor_pos: Vec3,
     particles: Vec<Particle>,
     accumulator: f32,
-    /// The emitter origin's last-frame live world position (the reference's rt+0x248 prevPos,
-    /// refreshed EVERY frame — `0x7b5230` @0x7b5265): the one-frame Δ source for both
-    /// emitter-motion terms (follow-delta, velocity inherit). `None` until the first frame.
+    /// The emitter origin's world position last frame, the reference's `rt+0x248` (`0x7b5230`
+    /// @`0x7b5265`): the delta behind follow-delta and velocity inherit.
     emitter_prev: Option<Vec3>,
-    /// Velocity-inherit state (file flag 0x40, wow-re `part-emitter-motion.md` §1): the ~30 Hz
-    /// trigger accumulator (rt+0x254) and the held inherit velocity (rt+0x258.., world frame) —
-    /// recomputed only at a trigger, births read the held value between.
+    /// Velocity inherit (file flag `0x40`, `0x7b5230`): the ~30 Hz trigger accumulator
+    /// (`rt+0x254`) and the velocity held between triggers (`rt+0x258`).
     inherit_accum: f32,
     inherit_vel: Vec3,
-    /// Last frame's emission gate `(enabled && rate > 0)` — the rising-edge memory a BURST
-    /// emitter (file flag 0x8000) latches on: it births its one `ftol(rate)` puff the frame this
-    /// goes false→true and re-arms when it falls (the reference's `block+0x168`, wow-re
-    /// `part-emission-burst-flag.md` §1). Unused by continuous emitters.
+    /// Last frame's `enabled && rate > 0`: a burst emitter (file flag `0x8000`) births its one
+    /// `ftol(rate)` puff on the rising edge (the reference's `block+0x168`, `0x718f06`).
     gate_prev: bool,
-    /// Seconds since this emitter spawned — the clip clock the keyed emission-rate track samples
-    /// against (an effect model's emitters spawn at its clip start, so age == clip time). Ambient
-    /// props' constant tracks are age-invariant.
+    /// Seconds since spawn, the clip clock of a pinned lane's rate track.
     age: f32,
-    /// The emission clock's SEQUENCE source (`EmitTiming`, decision 0641's host resolution one
-    /// channel over): the entity whose live `AnimationPlayer` names the playing sequence + clip
-    /// time — a unit's / GameObject's emitters read the *playing* sequence's key window, so a
-    /// quest object's explosion fires in its one-shot clips and stays OFF at idle. `None` = a
-    /// pinned lane (placed doodad, effect rig, booth) on the spawn-age clock.
+    /// The entity whose live `AnimationPlayer` picks the sequence and clip time the tracks sample.
     host: Option<Entity>,
-    /// The sequence FILE slot the timing samples: the pinned slot an effect's rig armed, or the
-    /// host's last resolved slot (kept across frames where the host has no live player — the
-    /// pre-arm frame reads that slot's opening pose). `None` ⇒ slot 0 (the doodad law).
+    /// The sequence slot the timing samples: the idle seed, then the rig's or host's resolved one.
     seq: Option<usize>,
     rng: u32,
-    /// The OWNER model's reach from its origin in **world** yards (the authored
-    /// [`ModelEmitter::owner_reach`] × the placement scale) — the draw-order rung this cloud and
-    /// every CHILD cloud of it is biased by, so both clear the owner's own transparent batches
-    /// (see [`owner_last_bias`]). Children carry the parent's, not their recursion model's: a
-    /// child draws at the parent's anchor, so it is the parent's owner it has to clear.
+    /// The owner's reach in world yards, the draw-order rung ([`owner_last_bias`]) of this cloud
+    /// and its children, which draw at the parent's anchor and so must clear the parent's owner.
     owner_reach: f32,
-    /// The owner model's bound sphere (Bevy model-local centre, model-local radius) — the
-    /// water-plane classification input ([`ModelEmitter::water_bound`]; the law is
-    /// `sim::model_far_side`). Model-local: the live matrix supplies position and scale.
+    /// The owner's model-local bound sphere, for the water-plane classification.
     water_bound: (Vec3, f32),
-    /// The particle texture — the sim withholds pushing quads until it's resident: a
-    /// still-loading or failed-to-decode texture would otherwise flash the engine fallback
-    /// (white/magenta) through the additive blend. Particles still simulate meanwhile.
+    /// No quads until it is resident, or the engine fallback flashes through the additive blend.
     texture: Handle<Image>,
-    /// The draw-set gate's memory (was the emitter entity's `Visibility` flip): true while the
-    /// owner is out of the frame's draw set — the edge on which model-instance entities are
-    /// hidden. Quads need no flag: a gated pool simply pushes nothing into the shared stream.
+    /// True while the owner is out of the frame's draw set; a gated pool pushes no quads.
     gated: bool,
-    /// **The owner's own freeze** — the scene-level "this cloud is not being drawn" answer for a
-    /// scene whose CAMERA cannot give it (decision 2046). [`sim::booth_frozen`] reads a
-    /// booth-layered emitter's freeze off its camera's `is_active` bit, which is exact while one
-    /// camera means one scene — and the `<Model>` tile atlas broke that: EVERY orthographic pane
-    /// on the sheet shares one camera, and that camera is deliberately kept active whenever any
-    /// cell is packed, so a pane that leaves the paint list still has a camera saying "drawn".
-    /// The owner sets this instead, on the frame its own scene stops being drawn. The freeze it buys is exactly the
-    /// booth's — pool + age HELD, one frame's dt on re-entry, no catch-up, no quads — and, like
-    /// the booth's, it never applies to a [`Self::draining`] emitter, which has to run its pool
-    /// out or leak for the session.
+    /// The owner's freeze, for a scene its camera cannot report (all `<Model>` tile panes share one
+    /// camera): it holds pool and age, but never on a [`Self::draining`] emitter.
     frozen: bool,
-    /// The pending recursion model (wow-re `part-child-recursion.md`): once the asset resolves,
-    /// [`wire_child_emitters`] turns its own emitters (cap 4, the reference's `0x7b5dfe`) into
-    /// [`Self::children`] and clears this.
+    /// The pending recursion model (`0x7b5dd0`); [`wire_child_emitters`] turns up to 4 of its
+    /// emitters (`0x7b5dfe`) into [`Self::children`].
     recursion: Option<Handle<benilla_assets::M2Model>>,
-    /// CHILD emitters — driven once per live parent particle per frame at the particle's
-    /// position (never ambiently); each owns its pool and a [`ChildDraw`] mesh entity.
+    /// Child emitters, driven once per live parent particle per frame, never ambiently.
     children: Vec<ChildEmitter>,
-    /// The GEOMETRY model (wow-re `part-model-particles.md`): when authored, this emitter's
-    /// particles render as 3-D instances of it instead of quads — [`model::update_model_particles`]
-    /// grows/positions the instance pool below.
+    /// The geometry model (`0x7b1c80`, spawn driver `0x7b5550`): when authored, particles draw as
+    /// its instances instead of quads ([`model::update_model_particles`]).
     geometry: Option<Handle<benilla_assets::M2Model>>,
-    /// The live instance pool (one slot per drawn particle, grown on demand, hidden past the
-    /// live count). Each slot's mesh entities carry per-instance tint-clone materials.
+    /// One instance per drawn particle, grown on demand and hidden past the live count.
     model_instances: Vec<model::ModelInstance>,
-    /// The lane's size unit for this cloud's unflagged particle half-extents —
-    /// [`quads::DrawFrame::size_scale`]. `1.0` (a yard) for every world lane; a UI model tile
-    /// sets its pixels-per-unit through [`Self::set_size_scale`].
+    /// The half-extent unit ([`quads::DrawFrame::size_scale`]): a yard, or a UI tile's pixels.
     size_scale: f32,
-    /// The render-target rectangle this cloud is confined to, target pixels — see
-    /// [`Self::set_clip`]. `None` = the whole target (every world emitter).
+    /// The render-target rectangle, in pixels, this cloud is confined to ([`Self::set_clip`]).
     pub(crate) clip: Option<Vec4>,
 }
 
-/// One wired CHILD emitter (see [`ParticleEmitter::children`]): the recursion model's own
-/// emitter def + texture and a private pool. Simulated entirely inside the parent's sim block
-/// (no ECS ordering with the parent's fresh pool); its quads go into the shared stream as one
-/// draw of its own, at the parent's anchor and rung.
+/// A child emitter: the recursion model's def, texture and pool, drawn at the parent's anchor.
 struct ChildEmitter {
     def: ParticleEmitterDef,
     texture: Handle<Image>,
@@ -295,15 +163,12 @@ struct ChildEmitter {
     rng: u32,
 }
 
-/// Marker on a MODEL-particle instance entity ([`model`]) — keeps the sim's transform queries
-/// provably disjoint (the owner-read query excludes these; the instance write query requires
-/// it).
+/// Marks a geometry-particle instance ([`model`]), keeping the sim's reads and writes disjoint.
 #[derive(Component)]
 pub struct ChildDraw;
 
 #[cfg(test)]
 impl ChildEmitter {
-    /// A bare child for unit tests.
     fn bare(def: ParticleEmitterDef) -> Self {
         Self {
             def,
@@ -316,89 +181,58 @@ impl ChildEmitter {
     }
 }
 
-/// What becomes of a live pool when its owner entity goes away — the distinction the sim itself
-/// cannot make, because from inside it a despawned owner looks the same either way (decision 0826).
+/// What a live pool does when its owner entity goes away, which only the spawn site knows.
 #[derive(Clone, Copy, Default, PartialEq, Eq, Debug)]
 pub enum OwnerLoss {
-    /// The owner MODEL was destroyed: **free the emitter with it**, live particles and all. This
-    /// is the reference's own rule — a model's emitters are released synchronously at its dtor
-    /// (wow-re `ribbon-basis-emitter-lifecycle`) — and it is what an equipped item that is
-    /// replaced/unequipped, or a unit that streams out, must do. Draining instead left the cloud
-    /// hanging in world space for a whole lifespan while the character walked away from it.
+    /// The owner model was destroyed (an item replaced, a unit streamed out): free the pool with
+    /// it, as the reference frees a model's emitters at its dtor (`0x70e313`).
     Free,
-    /// The owner was reaped but the effect should finish: emission stops and the pool lives out
-    /// its lifespans at the frozen placement (a missile that impacted, a spell effect that
-    /// ended — the reference's model outliving its emitters while they drain). The default,
-    /// because it is what every pre-0826 caller got.
+    /// The effect ended (a missile impacted): stop emitting and let the pool age out in place, as
+    /// the reference's model outlives its draining emitters.
     #[default]
     Drain,
 }
 
-/// The live frames an emitter rides — bundled so a call site names each one instead of passing a
-/// row of positional `Option<Entity>`s (they are easy to swap and impossible to tell apart at the
-/// call). See the matching [`ParticleEmitter`] fields for what each frame does.
+/// The live entities an emitter rides, named so a call site cannot swap them.
 #[derive(Clone, Copy, Default)]
 pub struct EmitterFrames {
-    /// The entity whose live transform is this emitter's placement: `(entity, [0; 3])` for a
-    /// streamed creature/GameObject/held item (the whole model rides), or `(joint, bone_pivot)`
-    /// for an emitter riding its animated bone (0130 phase 4 — the pivot rebases the model-space
-    /// `def.position` into the joint's own frame, so an unanimated chain reproduces the static
-    /// path exactly). `None` for a static doodad (fixed placement, despawned by the placement's
-    /// own entity list).
+    /// The entity whose live transform is the placement: `(entity, [0; 3])` for a whole model,
+    /// `(joint, bone_pivot)` on an animated bone; `None` for a static doodad.
     pub owner: Option<(Entity, [f32; 3])>,
-    /// The cloud anchor — the MODEL, never the bone ([`ParticleEmitter::anchor`]).
+    /// The cloud anchor: the model, never the bone ([`ParticleEmitter::anchor`]).
     pub anchor: Option<Entity>,
-    /// The MODEL INSTANCE whose render alpha multiplies these particles
-    /// ([`ParticleEmitter::alpha_src`]).
+    /// The model instance whose render alpha multiplies these particles.
     pub alpha: Option<Entity>,
-    /// The **light node** this cloud shades under ([`ParticleEmitter::light_node`]): the net
-    /// entity root for a creature/GameObject, the WEARER for an equipped item (one node per
-    /// object — the reference aliases the wearer's collector into each attached model). `None`
-    /// for a lane with no entity light node of its own: a placed doodad or a WMO prop, whose
-    /// provider is the CMapDoodadDef twin rather than the WENTITY, and a booth, whose light is
-    /// its own buffer.
+    /// The light node: a creature's root, an equipped item's wearer (the reference aliases the
+    /// wearer's collector into each attached model); `None` for a doodad, a WMO prop or a booth.
     pub light_node: Option<Entity>,
     /// What losing `owner` means ([`OwnerLoss`]).
     pub on_owner_loss: OwnerLoss,
 }
 
-/// Spawn an emitter entity for one [`ModelEmitter`] at `placement`. `None` if the emitter has no
-/// resolved texture (nothing to draw); `frames` ties it to the live entities it rides.
 impl ParticleEmitter {
-    /// Live particle count — read by the perf probe ([`crate::capture`]).
+    /// Live particle count, for the perf probe ([`crate::capture`]).
     pub fn live(&self) -> usize {
         self.particles.len()
     }
 
-    /// Set the lane's size unit for this cloud — see [`quads::DrawFrame::size_scale`]. A UI
-    /// model tile (decision 2008) stores its cloud in device pixels and passes the reference's
-    /// pixels-per-model-unit for a particle's half-extent; every world lane leaves the default.
+    /// Set the half-extent unit; a UI model tile passes the reference's pixels per model unit.
     pub fn set_size_scale(&mut self, size_scale: f32) {
         self.size_scale = size_scale;
     }
 
-    /// Freeze or thaw this cloud from the OWNER's side — see [`Self::frozen`]. A draining emitter
-    /// ignores it.
-    ///
-    /// **Thawing clears [`Self::gated`]**, because the draw-set arm's cheap early-out
-    /// (`gated && gate_inputs_still && !fade.is_changed()`, decision 1979's floor) reads none of
-    /// the owner's inputs: a world-lane cloud left gated here on a still camera could never
-    /// re-enter its own draw set. One full gate evaluation on the thaw edge is the price.
-    /// **Confine this cloud's quads to a rectangle of the render target**, in target pixels —
-    /// the UI model tiles' cell ([`crate::particles::buffer::EffectDrawSpec::clip`], decision
-    /// 2093). `None` (the default, and every world emitter) draws over the whole target.
-    ///
-    /// A tile's cloud is quads in the shared atlas's own space, so without this a cloud that
-    /// reaches past its cell lands in the cell the shelf packed beside it — which the composite
-    /// hands to a different widget (B379: the autocast shine's golden `GlowStar` down the left
-    /// edge of a bag slot's cooldown). The reference has no atlas and no such reach: it draws
-    /// each `<Model>` with the widget's rect as the VIEWPORT.
+    /// Confine this cloud's quads to a UI tile's cell of the shared atlas, in pixels
+    /// ([`crate::particles::buffer::EffectDrawSpec::clip`]), as the reference draws each `<Model>`
+    /// with the widget's rect as its viewport; `None` draws over the whole target.
     pub fn set_clip(&mut self, clip: Option<Vec4>) {
         if self.clip != clip {
             self.clip = clip;
         }
     }
 
+    /// Freeze or thaw this cloud from the owner's side ([`Self::frozen`]). Thawing clears
+    /// [`Self::gated`]: the draw-set early-out reads none of the owner's inputs, so a cloud left
+    /// gated on a still camera would never re-enter its draw set.
     pub fn set_frozen(&mut self, frozen: bool) {
         self.frozen = frozen;
         if !frozen {
@@ -406,105 +240,63 @@ impl ParticleEmitter {
         }
     }
 
-    /// Is this cloud owner-frozen? ([`Self::set_frozen`]) — so an owner writing the same value
-    /// every frame need not touch the component and trip change detection.
+    /// Whether the owner froze this cloud, so an owner can skip a same-value write.
     pub fn is_frozen(&self) -> bool {
         self.frozen
     }
 
-    /// The authored def — read by the particle census probe ([`crate::capture`]), which prints
-    /// per-emitter facts (blend, texture, rate keys) beside the live count.
+    /// The authored def, for the particle census probe ([`crate::capture`]).
     pub fn def(&self) -> &ParticleEmitterDef {
         &self.def
     }
 
-    /// The particle texture handle — read by the phase probe ([`crate::capture`]) to report the
-    /// GPU-side image state beside the phase membership (a main-world-resident image whose GPU
-    /// prep failed leaves every draw silently skipped).
+    /// The particle texture, for the phase probe ([`crate::capture`]).
     pub fn texture(&self) -> &Handle<Image> {
         &self.texture
     }
 
-    /// The owner-last draw-order rung this emitter's effects take (see [`owner_last_bias`]).
-    ///
-    /// Read by the MODEL-particle draw ([`model::update_model_particles`]), whose instances are
-    /// built from the geometry model's own batch materials and would otherwise sit at rung 0 — so
-    /// a 3-D particle would be painted over by its own sibling quad cloud. The reference draws all
-    /// of a model's emitters in the one bracket; sharing this number is what says so.
+    /// The owner-last rung ([`owner_last_bias`]), which geometry particles share too: the
+    /// reference draws a model's emitters in one bracket.
     pub(super) fn owner_rung(&self) -> f32 {
         owner_last_bias(self.owner_reach)
     }
 
-    /// Is this emitter in the frame's draw set — i.e. did the draw-set gate let it tick and push
-    /// quads this frame? The instrument-side spelling of [`Self::gated`], read by the particle
-    /// census probe. (It read the entity's `Visibility` until slice P2 (0733) moved the family onto
-    /// the shared stream and emitter entities stopped carrying one — after which the probe's query
-    /// matched NOTHING and every column it printed, including B39's `drawn_beyond_wall` guard, was
-    /// a vacuous zero.)
+    /// Whether the draw-set gate let this emitter tick and push quads this frame.
     pub fn drawn(&self) -> bool {
         !self.gated
     }
 
-    /// This frame's MODEL render alpha ([`Self::alpha_src`]) — read by the MODEL-particle lane,
-    /// whose instances carry their alpha in a `MeshTag` rather than a vertex colour.
+    /// This frame's model render alpha, for the geometry-particle lane's `MeshTag`.
     pub fn render_alpha(&self) -> f32 {
         self.alpha
     }
 
-    /// The **cloud anchor** this emitter was spawned under ([`EmitterFrames::anchor`]) — the model
-    /// instance it belongs to. The identity an effect lane uses to find its own emitters when the
-    /// instance ends ([`Self::drain_on_owner_loss`]).
+    /// The model instance this emitter belongs to, by which an effect lane finds its emitters.
     pub fn anchor(&self) -> Option<Entity> {
         self.anchor
     }
 
-    /// The **emission clock's host** ([`EmitClock::Host`]) — the model instance whose live
-    /// `AnimationPlayer` names the sequence this emitter samples its rate/gate tracks against;
-    /// `None` for a pinned or effect clock. The read an instrument or a wiring test needs, because
-    /// the difference is invisible in every other observable: a hosted and a pinned emitter build,
-    /// pool, tick and draw identically, and differ only in *which* sequence's tracks they read —
-    /// which is the whole difference between a firearm's muzzle blast firing and never firing
-    /// (decision 2281).
+    /// The emission clock's host ([`EmitClock::Host`]); `None` for a pinned or effect clock.
     pub fn emit_host(&self) -> Option<Entity> {
         self.host
     }
 
-    /// Switch this emitter to [`OwnerLoss::Drain`] — **the effect is ending, so its already-emitted
-    /// particles must finish rather than pop** (wow-re `ceffect-particle-drain.md` §4a).
-    ///
-    /// The reference makes this distinction the same way, at the same moment. `0x6203e0` — the
-    /// teardown every ending `CEffect` reaches, whether by its completion callback or by the
-    /// same-slot replace — does **not** free the node: it pushes it onto the pending-destroy list
-    /// and hides it, which stops emission only. The particle draw path never reads a flag that
-    /// teardown clears (its own admission test is the live-particle count `emitter+0x64`,
-    /// `0x7b4b46`), so the survivors keep drawing and ageing out one at a time; `0x61f680` frees
-    /// the node on the first frame the aggregate `CM2Model+0x3d8` reads zero — **the free
-    /// condition and the draw condition are the same word**.
-    ///
-    /// It is deliberately NOT the spawn-time policy for an attached instance, because the *other*
-    /// way an effect's owner can vanish is the model dtor — a gear change, a display swap, a unit
-    /// streaming out — and there the reference frees the emitters synchronously and the pool must
-    /// go with the body (decisions 0826/0833: draining that case stranded ghost clouds in the air
-    /// where the character had been). Both look identical from inside the sim, so the ending side
-    /// says so explicitly.
+    /// Switch to [`OwnerLoss::Drain`]: the effect is ending, so its particles finish rather than
+    /// pop. The reference's `CEffect` teardown (`0x6203e0`) only hides and queues the node, which
+    /// stops emission; the draw admits by live-particle count (`emitter+0x64`, `0x7b4b46`), so the
+    /// survivors age out, and `0x61f680` frees the node once `CM2Model+0x3d8` reads zero. An
+    /// attached instance spawns `Free`, since a model dtor frees its emitters at once.
     pub fn drain_on_owner_loss(&mut self) {
         self.on_owner_loss = OwnerLoss::Drain;
     }
 
-    /// The cloud's live world anchor — the census probe's fallback distance subject for an emitter
-    /// with no [`EmitterFade`] (entity-owned: creatures, GameObjects, spell kits). A faded
-    /// emitter's distance is measured to its OWNER's sphere instead, because that sphere is what
-    /// the draw-set gate actually tests.
+    /// The cloud's live world anchor, the census probe's distance subject.
     pub fn anchor_world(&self) -> Vec3 {
         self.anchor_pos
     }
 
-    /// The cloud-orientation fingerprint — read by the particle census probe: the live cloud's
-    /// WORLD centroid, best-fit plane normal (unit), RMS thickness along it, and RMS in-plane
-    /// radius, from the same composition the quad expansion draws with. The numeric "which way
-    /// is this cloud actually facing" instrument: an orientation bug is settled by this number,
-    /// never by eyeballing a capture (method: timing/geometry are measured). `None` under 4
-    /// particles (no stable plane).
+    /// The cloud's world centroid, plane normal, RMS thickness and RMS in-plane radius as the
+    /// quads draw it, the census probe's orientation measure; `None` under 4 particles.
     pub fn cloud_fingerprint(&self) -> Option<(Vec3, Vec3, f32, f32)> {
         if self.particles.len() < 4 {
             return None;
@@ -526,9 +318,7 @@ impl ParticleEmitter {
             .collect();
         let n = world.len() as f32;
         let centroid = world.iter().sum::<Vec3>() / n;
-        // 3×3 covariance; the normal is its smallest-eigenvalue eigenvector — found by power-
-        // iterating for the two largest principal axes and crossing them (robust enough for a
-        // probe; exactness is not the point, the axis label is).
+        // The normal crosses the covariance's two largest axes, found by power iteration.
         let mut cov = Mat3::ZERO;
         for w in &world {
             let d = *w - centroid;
@@ -562,58 +352,29 @@ impl ParticleEmitter {
     }
 }
 
-/// Ties a terrain-doodad emitter to its owner doodad's byte-verified distance-fade law
-/// (`model_fade::doodad_fade_alpha`, `FUN_00683f80`): when the owner falls out of the draw set
-/// (fade ≤ 0 — a small prop past 50 yd, a mid prop past 125), the emitter neither simulates nor
-/// draws — the reference ticks particles as part of the owning model's animate step, which only
-/// runs for drawn models. This is the system that bounds the reference's emitter population; the
-/// particle-side rule (emission LOD, no cull — decision 0151) applies only WITHIN the draw set.
-/// Attached by the terrain spawn path; entity-owned emitters (creatures/GameObjects/spells) are
-/// bounded by server visibility instead and carry no fade.
-/// The rule is shared by BOTH emitter families — the quad clouds here and the ribbon trails in
-/// [`crate::ribbons`], which take this by value. `Clone` so one call site can build a placed
-/// model's gate ONCE and hand the same value to both, rather than two constructions that can drift.
+/// A placed model's draw-set gate, shared with its ribbons ([`crate::ribbons`]): out of the draw
+/// set an emitter neither simulates nor draws, as the reference ticks particles in the owning
+/// model's animate step, run only for drawn models; inside it only emission LOD applies.
+/// Entity-owned emitters carry none: server visibility bounds them.
 #[derive(Component, Clone)]
 pub struct EmitterFade {
-    /// World bounding-sphere radius of the OWNER doodad (selects the fade band).
+    /// The owner doodad's world bounding-sphere radius, which picks the fade band.
     pub radius: f32,
-    /// The owner doodad's world bbox centre — the fade measures horizontal distance to this
-    /// (matching the doodad's own gate in `debug_panel::visibility`), not the emitter position.
+    /// The owner's world bbox centre, which the fade measures to, not the emitter's position.
     pub center: Vec3,
-    /// The WMO placement whose doodad set this emitter's owner belongs to; `None` for an ADT map
-    /// doodad. Read only by the exterior-window term: a prop of the building the camera is standing
-    /// in is not exterior scene to itself, so its candle keeps burning (decision 0784's exemption,
-    /// which the owner submesh gets through `WmoGroupVis` — an emitter carries no such component,
-    /// so it carries the instance directly).
+    /// The WMO placement whose doodad set holds the owner (`None` for an ADT doodad), for the
+    /// exterior-window exemption: a prop of the building the camera stands in keeps burning.
     pub(crate) instance: Option<Entity>,
-    /// The **rooms** of [`Self::instance`] that name this owner — the prop's own
-    /// [`crate::wmo_portal::WmoGroupVis`], by value.
-    ///
-    /// It answers the question [`Self::instance`] cannot: not *which building am I furniture of*
-    /// (identity, for the exemption above) but *is the room I stand in drawn this frame*. The
-    /// reference never has to ask, because it instantiates a WMO's props out of each **visible**
-    /// group's own MODR list (`0x695aa0` from the visible-group walk `0x698720`, decision 0689) —
-    /// a prop in a culled room is never created, so it has no emitters to tick. We create props
-    /// once and cull them per frame, so every rider of a prop has to ask for itself, and this is
-    /// the one place the answer is spelled.
-    ///
-    /// `None` = not a building's prop (an ADT map doodad, a creature, a GameObject, a spell kit),
-    /// or a prop no group names at all — nothing claims it, so nothing gates it here. When it is
-    /// `Some`, its `instance` is the same entity as [`Self::instance`]: both are built from one
-    /// expression at one call site (`terrain_stream::spawn`), which is what keeps them from
-    /// drifting.
-    ///
-    /// By value and not as a component on the emitter entity, because a `WmoGroupVis` there would
-    /// enlist it in `apply_model_visibility`'s `group_only` query — a second `Visibility` writer on
-    /// an entity whose `Visibility` this lane does not read (decision 0025).
+    /// The rooms of [`Self::instance`] naming the owner, built with it in `terrain_stream::spawn`:
+    /// the reference admits a WMO prop to the frame's scene only for the groups its portal walk
+    /// reaches (`0x685d70` → `0x6838f0`), so a prop in a culled room has no emitters to tick. By
+    /// value, since a `WmoGroupVis` component would enlist the emitter in `apply_model_visibility`.
     pub(crate) room: Option<crate::wmo_portal::WmoGroupVis>,
 }
 
 impl EmitterFade {
-    /// A bare fade **sphere** — the gate of a placement that is nobody's furniture: an ADT map
-    /// doodad, a WMO root's own geometry, a prop on a moving transport. `center` is WORLD space,
-    /// already placed. The building-prop form goes through
-    /// [`crate::terrain_stream::emitter_fade`], which composes this with the instance and rooms.
+    /// The gate of a placement that is nobody's furniture, `center` in world space; a building's
+    /// prop goes through [`crate::terrain_stream::emitter_fade`].
     pub(crate) fn sphere(radius: f32, center: Vec3) -> Self {
         Self {
             radius,
@@ -623,44 +384,22 @@ impl EmitterFade {
         }
     }
 
-    /// This owner's distance-fade ALPHA (not the cutoff): the reference writes it into the
-    /// doodad's `CM2Model+0x180`, so it multiplies that model's particles exactly as it does its
-    /// batches (`FUN_00683f80` → `+0x180` → `+0x19c` → `emitter+0x1a8`, decision 0827). The
-    /// [`Self::in_draw_set`] gate is the same curve's zero crossing — this is the feather before
-    /// it, which is why a small prop's flame now thins out over its band instead of cutting.
+    /// The owner's distance-fade alpha, which multiplies its particles as it does its batches
+    /// (`0x683f80` → `+0x180` → `+0x19c` → `emitter+0x1a8`); the draw set ends at its zero.
     pub fn distance_alpha(&self, cam_pos: Vec3) -> f32 {
         let (dx, dz) = (self.center.x - cam_pos.x, self.center.z - cam_pos.z);
         crate::model_fade::doodad_fade_alpha(self.radius, (dx * dx + dz * dz).sqrt())
     }
 
-    /// The **draw-set admission rule** in one place: is the owner doodad in the frame's scene
-    /// worklist, and therefore does its emitter tick and draw this frame?
-    ///
-    /// Five terms, the first four against the owner's fade sphere (the reference's `[rec+0x68]`):
-    /// 1. the radius-tiered distance fade hasn't reached zero (`FUN_00683f80`),
-    /// 2. the sphere is inside the far-clip wall ([`crate::view::within_farclip`]),
-    /// 3. `lateral_in_frustum` — the caller's frustum sphere test on the side/near planes,
-    /// 4. `exterior_admitted` — the caller's exterior-window test (decision 0786),
-    /// 5. `room_admitted` — the caller's portal-PVS test ([`Self::room_admitted`], decision 0689).
-    ///
-    /// Term 2 is the one bug B39 was missing (decision 0678), and it cannot be folded into term 1:
-    /// [`crate::model_fade::doodad_fade_alpha`] returns a flat `1.0` for any owner bigger than
-    /// [`crate::model_fade::NEVER_FADE_RADIUS`], so for exactly the props that carry the big
-    /// effects — braziers, bonfires, portal frames — term 1 admits at *every* distance.
-    ///
-    /// Term 4 is the same omission one layer out. The reference links a doodad into the worklist
-    /// through the per-window populate walk `0x683700` and ticks its particles as part of that
-    /// model's animate step — so an unlinked doodad emits nothing. We gated the doodad's *mesh* and
-    /// left its emitter running, which is a mushroom's spore cloud hanging in a sealed dungeon (the
-    /// director's report: `plaguelandmushroom01`, 3 emitters, 59.7 yd through a wall).
-    ///
-    /// Term 5 is the same omission one layer *in*: the exterior window asks whether the BUILDING is
-    /// in the scene, and answers "yes" for every building the camera can see — which says nothing
-    /// about the sealed room inside it that this emitter's owner actually stands in. Ninety Caverns
-    /// of Time ribbon trails burned up through 200 yd of Tanaris rock on exactly that gap
-    /// (decision 1289); this is the shared spelling that decision named as the fix.
-    ///
-    /// Pure and total so the rule is pinned by tests without an ECS (the `model_fade` pattern).
+    /// Whether the owner is in the frame's scene worklist, so its emitters tick and draw. The
+    /// first four terms test the owner's fade sphere (`[rec+0x68]`):
+    /// 1. the size-banded distance fade is above zero (`0x683f80`),
+    /// 2. the sphere is inside the far-clip wall ([`crate::view::within_farclip`]), since term 1
+    ///    admits a never-fading owner (a brazier) at any distance,
+    /// 3. `lateral_in_frustum`, the side and near planes,
+    /// 4. `exterior_admitted`: the reference links a doodad into the worklist through the
+    ///    per-window populate walk (`0x683700`), and an unlinked one emits nothing,
+    /// 5. `room_admitted`, the portal PVS of the owner's room ([`Self::room_admitted`]).
     pub fn in_draw_set(
         &self,
         cam_pos: Vec3,
@@ -679,30 +418,25 @@ impl EmitterFade {
             && room_admitted
     }
 
-    /// **Term 5 for this emitter, given the live placement its rooms belong to** — kept beside the
-    /// rule for the same reason [`Self::exterior_admitted`] is, so the particle sim, the ribbon sim
-    /// and the meshless-host anim gate ask one question instead of three. The arms, and why the
-    /// last one fails CLOSED, are [`crate::wmo_portal::room_admits`] — shared with the light lane,
-    /// which rides the same rooms for the same reason.
+    /// Term 5 ([`crate::wmo_portal::room_admits`], failing closed when the placement is gone).
     pub fn room_admitted(&self, instance: Option<&crate::wmo_portal::WmoPortalInstance>) -> bool {
         crate::wmo_portal::room_admits(self.room.as_ref(), instance)
     }
 
-    /// Term 4 for this emitter, given the frame's gate and the placement the camera is inside. Kept
-    /// beside the rule so both callers — the particle sim and the meshless-host anim gate — ask the
-    /// same question instead of each re-deriving the exemption.
+    /// Term 4, given the frame's gate and the placement the camera is inside.
     pub fn exterior_admitted(
         &self,
         gate: &crate::exterior_cull::ExteriorGate,
         camera_instance: Option<Entity>,
     ) -> bool {
         if self.instance.is_some() && self.instance == camera_instance {
-            return true; // a prop of the building the camera stands in — not exterior to itself
+            return true; // a prop of the building the camera stands in is not exterior to it
         }
         gate.admits_sphere(self.center, self.radius)
     }
 }
 
+/// Spawn an emitter for one [`ModelEmitter`] at `placement`; `None` when it would draw nothing.
 pub fn spawn_emitter(
     commands: &mut Commands,
     emitter: &ModelEmitter,
@@ -714,9 +448,7 @@ pub fn spawn_emitter(
     if std::env::var_os("WOW_NO_PARTICLES").is_some() {
         return None;
     }
-    // A quad emitter with no resolved texture draws nothing; a GEOMETRY (model-particle)
-    // emitter never draws quads — the default handle stays non-resident, keeping its quad
-    // mesh permanently empty while the instances render.
+    // No texture: a quad emitter draws nothing, a geometry one keeps a never-resident default.
     let texture = match emitter.texture.clone() {
         Some(t) => t,
         None if emitter.geometry.is_some() => Handle::default(),
@@ -724,9 +456,7 @@ pub fn spawn_emitter(
     };
     let mut def = emitter.def.clone();
     let owner = frames.owner.map(|(entity, pivot)| {
-        // Rebase the model-space emitter origin into the owner frame (bone-local for a joint owner;
-        // pivot = 0 leaves it model-space for a whole-model owner). Same raw WoW axes throughout —
-        // the sim composes `def.position` with the owner's live transform at each birth.
+        // Rebase the emitter origin into the owner's frame, bone-local for a joint (raw WoW axes).
         def.position = [
             def.position[0] - pivot[0],
             def.position[1] - pivot[1],
@@ -734,41 +464,30 @@ pub fn spawn_emitter(
         ];
         entity
     });
-    // Gate on the rate track's PEAK over every sequence, not its first key: a one-shot burst
-    // emitter (the blood spurt's starflash/glowball, 0140 fold-back) keys `0 → 200 → 0` — value[0]
-    // is 0 but it absolutely emits.
+    // The rate's peak over every sequence, not its first key: a one-shot burst keys `0 → 200 → 0`.
     if def.params.peak_lifespan() <= 0.0 || def.timing.peak_rate() <= 0.0 {
         return None; // emits nothing
     }
-    // The starting slot is the model's **loader-idle** sequence, never "unknown" (decision 0936).
-    // The reference arms that sequence on every M2 instance at load, so an emitter always has a
-    // sequence to sample; leaving it `None` handed the slot resolution to `EmitTiming::idx`'s
-    // `unwrap_or(0)` degrade, which is the idle slot only by accident. On the Spawn/Stand/Despawn
-    // GameObjects slot 0 is the *Spawn* flourish, so a content-gated instance (nothing armed, so
-    // `playing_seq` never overrides this seed) sat at that slot's opening frame for ever — the
-    // Stormwind battlefield banner firing its spawn sparkle-tails on a loop.
+    // The model's loader-idle sequence, which the reference arms on every M2 at load; slot 0 can
+    // be a Spawn flourish (a Spawn/Stand/Despawn GameObject).
     let idle = Some(emitter.idle_seq);
     let (host, seq) = match clock {
         EmitClock::Pinned => (None, idle),
         EmitClock::Effect(s) => (None, s.or(idle)),
         EmitClock::Host(h) => (Some(h), idle),
     };
-    // The owner's reach is model-local; the rung is a view-space distance, so it takes the
-    // placement scale with it (a scaled-up creature's batches spread proportionally).
+    // The reach is model-local and the rung a view-space distance, so it takes the scale.
     let owner_reach = emitter.owner_reach * placement.scale.max_element();
     // Seed the RNG from the placement position so two campfires don't flicker in lockstep.
     let t = placement.translation;
     let rng = (t.x.to_bits() ^ t.y.to_bits().rotate_left(11) ^ t.z.to_bits().rotate_left(22))
         .wrapping_mul(0x9E37_79B9)
         | 1;
-    // A LIT emitter is a consumer of its object's light node, exactly as a lit mesh batch is —
-    // and it is frequently the ONLY one (all five of the Onyxia lava trap's mesh batches are
-    // unlit). Registering the edge here is what puts the object in front of the interior
-    // classifier at all; see [`crate::interior::EmitterLitBy`].
+    // A lit emitter consumes its object's light node as a lit batch does, and is often the only
+    // consumer (the Onyxia lava trap's batches are all unlit), so it registers the edge itself.
     let lit_node = frames.light_node.filter(|_| def.lit);
     let mut spawned = commands.spawn((
-        // The sim writes the anchor here each frame — the census/phase instruments'
-        // read point (the draw's own sort key rides the draw record instead).
+        // The sim writes the anchor here for the probes; the draw's sort key rides its record.
         Transform::IDENTITY,
         ParticleEmitter {
             def,
@@ -814,54 +533,22 @@ pub fn spawn_emitter(
     Some(spawned.id())
 }
 
-/// The **owner-last** draw-order rung: how far to bias one of a model's EFFECTS past that model's
-/// own transparent batches (`Transparent3d` sort key = view-space z **+ depth_bias**, ascending, so
-/// a positive bias draws LATER — the sign law lives in [`crate::sky_order`]).
-///
-/// The reference draws a model's emitters in their own push/pop bracket (`0x70d8b0`) *after* that
-/// model's batches, unconditionally — never interleaved with them. Bevy has one distance-sorted
-/// transparent list, and an effect mesh carries `NoFrustumCulling`, which suppresses the `Aabb`
-/// Bevy would otherwise sort by, so it sorts at its entity translation while each body batch sorts
-/// at its own bind-pose AABB centre a yard or two up the model. Both measured shapes of that:
-///
-/// - **Quad clouds** sort at the owner's ORIGIN, so the order flips with camera ELEVATION. On the
-///   voidwalker at 12 yd: at 0° the eye emitters land at transparent slots 324/325 with 5 of the 14
-///   blend batches still behind them; at 35° they drop to slots 7/8 and **all 14** draw over them —
-///   B16, the eye glow visible from below the eye horizon and gone from above (decision 0719).
-/// - **Ribbon trails** sort at the live head node, which sits *inside* the owner, so they interleave
-///   at every angle and the interleave MOVES. On the wisp at 6 yd, elevation 0°: its three streamers
-///   land at slots 310/317/324 among the wisp's own 14 blend batches, 6 batches deep each, and which
-///   batches are over which streamer changes frame to frame as the streamers whip (decision 0721).
-///
-/// `reach` is the owner's authored [`benilla_assets::ModelEmitter::owner_reach`] (or
-/// [`benilla_assets::ModelRibbon::owner_reach`]) in **world** yards — the model-local bound
-/// [`benilla_formats::m2_owner_reach`] measures, times the placement scale. View-space z is
-/// 1-Lipschitz in world position and no owner batch sorts farther than `reach` from its origin, so
-/// `z(origin) + reach ≥ z(any of its batch centres)`.
-///
-/// Every effect of one model must take the SAME rung, or the law is broken from the other side: the
-/// reference draws a model's emitters in file order within the bracket, so a quad cloud on rung 4
-/// beside a model-particle instance on rung 0 would paint over its own sibling.
-///
-/// The rounding, the ceiling and their reasons live with the shared implementation in
-/// [`benilla_formats::owner_last_rung`] — the survey tools (`emdump`, `benilla-extract
-/// fxordercensus`) print the same number this applies, and a rung computed twice drifts twice.
+/// The depth bias that draws a model's effects after its own transparent batches, as the reference
+/// brackets a model's emitters after its batches (`0x70d8b0`). Sort keys are view z plus bias,
+/// ascending ([`crate::sky_order`]); every batch centre lies within `reach` world yards of the
+/// origin and view z is 1-Lipschitz, so a rung above `reach` clears them. All of a model's effects
+/// take one rung, as the reference draws them in file order within the one bracket;
+/// [`benilla_formats::owner_last_rung`] rounds it.
 pub(crate) fn owner_last_bias(reach: f32) -> f32 {
     benilla_formats::owner_last_rung(reach)
 }
 
-/// Wire pending CHILD emitters (wow-re `part-child-recursion.md`, VERIFIED): once a parent's
-/// recursion model resolves, its own particle emitters — **capped at 4** (`0x7b5dfe`) — become
-/// the parent's children, each with its private pool (drawn from the shared stream at the
-/// parent's anchor and rung). The reference wires at the child model's async-load completion
-/// (`0x7b5dd0`); this system is that completion hook. A child never self-emits ambiently — its
-/// only particle source is the per-parent-particle drive in the sim.
-/// An emitter whose child-emitter model (`ParticleEmitter::recursion`) has not been resolved
-/// yet — the only emitters [`wire_child_emitters`] visits. Without it the wiring walked every
-/// resident emitter every frame to find the handful still waiting on a model (decision 1979).
+/// An emitter whose recursion model has not resolved, the only kind [`wire_child_emitters`] visits.
 #[derive(Component)]
 pub(crate) struct PendingChildren;
 
+/// Once a parent's recursion model resolves, make up to 4 of its emitters (`0x7b5dfe`) the
+/// parent's children, as the reference does at the model's async-load completion (`0x7b5dd0`).
 pub(crate) fn wire_child_emitters(
     mut commands: Commands,
     models: Res<Assets<benilla_assets::M2Model>>,
@@ -904,11 +591,8 @@ pub(crate) fn wire_child_emitters(
         emitter.recursion = None;
         emitter.children = children;
         commands.entity(entity).remove::<PendingChildren>();
-        // A child emitter is a whole emitter record of the recursion model with its own flag word,
-        // so it takes its own lighting verdict (the same rule its texture/blend/fog identity
-        // follows). A LIT child under an UNLIT parent is therefore a light-node consumer whose
-        // edge nothing registered at spawn — the parent's `def.lit` was false and the child did
-        // not exist yet. This is that late registration.
+        // A child has its own flag word and so its own lighting verdict: a lit child under an
+        // unlit parent registers the light edge here, since nothing did at spawn.
         if !registered && emitter.children.iter().any(|c| c.def.lit) {
             if let Some(node) = emitter.light_node {
                 commands
@@ -919,39 +603,24 @@ pub(crate) fn wire_child_emitters(
     }
 }
 
-/// Which sequence clock an emitter's rate/enabled tracks sample against
-/// ([`benilla_formats::EmitTiming`] — one baked loop per sequence, so the consumer names the
-/// sequence). Callers pick per lane at [`spawn_emitter`].
+/// The sequence clock the rate and enabled tracks sample ([`benilla_formats::EmitTiming`]).
 #[derive(Clone, Copy, Default)]
 pub enum EmitClock {
-    /// Slot 0 on the spawn-age clock — a placed doodad's one-time arm (the pre-per-sequence law,
-    /// still correct there), the portrait booths, and any lane with no rig to ask.
+    /// The loader-idle slot on the spawn-age clock: a placed doodad, a booth, a lane with no rig.
     #[default]
     Pinned,
-    /// The SPELL-FX lane: the rig's armed slot (a missile's InFlight is not file-order-first;
-    /// `None` = slot 0) on the spawn-age clock, like every pinned lane — the effect instance is
-    /// byte-verified fresh per play (decision 0858), so its gseq loops open at phase 0 with it.
+    /// A spell effect's armed slot (`None` is the idle) on the spawn-age clock: the instance is
+    /// fresh per play, so its global-sequence loops open at phase 0 with it.
     Effect(Option<usize>),
-    /// A live host's `AnimationPlayer` decides the slot **and the clip time** each frame — units
-    /// and GameObjects, whose playing sequence changes; the reference's `m2_animate` emitter
-    /// phase samples the CURRENT sequence record (wow-re `part-emission-rate-animated.md` §2).
+    /// A live `AnimationPlayer` picks the slot and clip time each frame, as the reference's animate
+    /// kernel samples the current sequence (`0x714260`).
     Host(Entity),
 }
 
-/// One frame of the emission front end: how many births the pool is owed, loaded into
-/// `accumulator` (fractional; the caller's birth loop drains whole particles). The reference's
-/// per-frame emitter pass + spawn driver (`0x718960` / `0x7b5550`, wow-re
-/// `part-emission-burst-flag.md` + `part-emission-rate-animated.md`):
-///
-/// - `rate`/`emitting` arrive already sampled from the playing sequence's key window
-///   ([`benilla_formats::EmitTiming`]) and the gate is `(enabled && rate > 0)`.
-/// - A **continuous** emitter (file flag 0x8000 clear) pours `rate · density·LOD · dt`.
-/// - A **BURST** emitter (flag set) loads `ftol(rate · density·LOD)` ONCE on the gate's rising
-///   edge and re-arms when it falls (a looping clip's next pass re-fires it); the pour never
-///   runs for it. This is what bounds the Feint/Eviscerate impact's plume+crescents at one puff
-///   ~67 ms in — over by ~0.5 s — while the same-shaped cast-hands flame pours its whole clip.
-///
-/// Returns the burst count loaded this frame (0.0 otherwise) — the `fx` trace's measurement hook.
+/// Load `accumulator` with this frame's owed births (the reference's emitter pass and spawn
+/// driver, `0x718960`/`0x7b5550`), gated on `emitting && rate > 0`. A continuous emitter (file flag
+/// `0x8000` clear) pours `rate · scale · dt`; a burst loads `ftol(rate · scale)` once on the gate's
+/// rising edge and re-arms when it falls. Returns the burst, for the `fx` trace.
 fn accumulate_emission(
     is_burst: bool,
     rate: f32,
@@ -979,27 +648,18 @@ fn accumulate_emission(
     burst
 }
 
-/// Registers the per-frame particle simulation/billboard system. Emitters are spawned by the terrain
-/// streamer (which owns placement lifecycles) via [`spawn_emitter`].
+/// Registers the effect lane and the particle systems; emitters come from [`spawn_emitter`].
 pub struct ParticlePlugin;
 
 impl Plugin for ParticlePlugin {
     fn build(&self, app: &mut App) {
-        // The whole effect family draws through the dedicated lane
-        // ([`render::EffectLanePlugin`]); `WowParticleMaterial` and its MaterialPlugin retired
-        // with slice P2 (0733 §1) when precipitation and water foam moved onto the stream.
         app.add_plugins(render::EffectLanePlugin)
             .init_resource::<ParticleTuning>()
             .init_resource::<buffer::EffectQuads>()
-            // PostUpdate, after the billboard joint palette: an emitter riding a billboarded
-            // bone must sample the REPLACED frame, same frame — an Update-time read gets the
-            // un-billboarded pose back (avian's fixed-loop sync re-propagates from locals), and
-            // the Demon Skin flames followed the character instead of the camera. This also
-            // retires the one-frame lag emitters on ANY animated joint carried while reading
-            // last frame's globals from Update.
-            //
-            // `begin_effect_frame` clears the shared stream before BOTH writers (the ribbon sim
-            // is the other), so the writer order between them stays free.
+            // After the billboard joint palette: an emitter on a billboarded bone must read this
+            // frame's replaced pose, which an `Update` read loses (avian's fixed-loop sync
+            // re-propagates from locals). `begin_effect_frame` clears the stream before both
+            // writers, this sim and the ribbon sim, so their order is free.
             .add_systems(
                 PostUpdate,
                 (
@@ -1014,15 +674,10 @@ impl Plugin for ParticlePlugin {
                     .in_set(crate::billboard::BillboardPlace)
                     .after(crate::billboard::billboard_joint_palette)
                     .after(crate::rig_anim::finalize_rig_worlds)
-                    // …and after the CARD facing pass, for the same reason one step further out:
-                    // an equipped item's emitter rides a mesh-less billboard *frame* card (its
-                    // bone chain reaches a billboard bone and an item model has no rig to carry
-                    // the palette replacement — decision 0813), so that card's transform has to be
-                    // this frame's before births read it.
+                    // And after card facing: an item's emitter can ride a meshless billboard card.
                     .after(crate::billboard::face_billboards),
             )
-            // The write-order tripwire's re-arm, once the frame's stream has been extracted
-            // (see `buffer::EffectQuads::cleared_this_frame`).
+            // Re-arm the write-order tripwire (`buffer::EffectQuads::cleared_this_frame`).
             .add_systems(Last, buffer::clear_effect_frame_flag);
     }
 }
@@ -1032,12 +687,11 @@ pub(crate) mod tests {
     use super::*;
     use benilla_formats::ParticleShape;
 
-    /// The minimal def, exposed for sibling-module tests (the sim's child-drive test).
+    /// The minimal def, for sibling-module tests.
     pub(crate) fn plain_def() -> ParticleEmitterDef {
         super::emit::tests::def(ParticleShape::Plane)
     }
 
-    /// A spawnable emitter whose owner model's loader-idle sequence is file slot `idle_seq`.
     fn model_emitter(idle_seq: usize) -> ModelEmitter {
         ModelEmitter {
             def: plain_def(),
@@ -1052,7 +706,6 @@ pub(crate) mod tests {
         }
     }
 
-    /// Spawn one emitter through [`spawn_emitter`] and report the sequence slot it was seeded with.
     fn seeded_slot(emitter: ModelEmitter, clock: EmitClock) -> Option<usize> {
         use bevy::ecs::system::RunSystemOnce;
         let mut app = App::new();
@@ -1065,17 +718,9 @@ pub(crate) mod tests {
         app.world().get::<ParticleEmitter>(e).unwrap().seq
     }
 
-    /// **The emitter's opening slot is its model's loader-idle sequence, not file slot 0.**
-    ///
-    /// A Spawn/Stand/Despawn GameObject (`DuelingFlag`-shaped — the battlefield banners, the
-    /// goobers, `ArenaFlag`) keeps its idle in slot 1; slot 0 is the Spawn flourish. Seeding `None`
-    /// handed the resolution to `EmitTiming::idx`'s `unwrap_or(0)` degrade, so a rig-less instance —
-    /// one whose constant-pose idle made the render gate skip the arm, so nothing ever overrode the
-    /// seed — sampled the Spawn gate at its opening frame for ever. That is the Stormwind
-    /// battlefield banner firing its spawn sparkle-tails on a permanent loop.
-    ///
-    /// Every clock takes the seed: `Host` because its player may arm nothing, `Pinned` because there
-    /// is no rig to ask at all, `Effect(None)` because an unarmed effect rig rests on the same idle.
+    /// A Spawn/Stand/Despawn GameObject (the battlefield banners) keeps its idle in slot 1, slot 0
+    /// being the Spawn flourish. Every clock takes the seed: `Host` because its player may arm
+    /// nothing, `Effect(None)` because an unarmed rig rests on the idle.
     #[test]
     fn an_emitter_opens_on_its_models_idle_slot_not_slot_zero() {
         let host = Entity::from_raw_u32(1).unwrap();
@@ -1086,22 +731,16 @@ pub(crate) mod tests {
         ] {
             assert_eq!(seeded_slot(model_emitter(1), clock), Some(1));
         }
-        // An effect rig that DID arm a slot still names it — the seed is a default, not an override.
+        // An armed effect slot still wins: the seed is a default.
         assert_eq!(
             seeded_slot(model_emitter(1), EmitClock::Effect(Some(2))),
             Some(2)
         );
-        // The ordinary model, whose idle IS slot 0, is unchanged.
         assert_eq!(seeded_slot(model_emitter(0), EmitClock::Pinned), Some(0));
     }
 
-    /// **The ending side asks for the drain; the spawn-time policy does not give it** (wow-re
-    /// `ceffect-particle-drain.md` §4a). An attached instance is spawned `Free` so that a model
-    /// dtor — a gear change, a display swap, a unit streaming out — takes its pool with the body
-    /// (0826/0833: draining that case stranded ghost clouds in the air). The *other* way an
-    /// effect's owner vanishes is the effect simply ending, and there the reference hides the node
-    /// and lets the particles age out. Both look identical from inside the sim, so the ending side
-    /// flips the policy explicitly — and this is the flip.
+    /// An attached instance spawns `Free`, so a model dtor takes its pool; an ending effect flips
+    /// it to `Drain` (`0x6203e0` hides the node, `0x61f680` frees it once drained).
     #[test]
     fn an_ending_instance_switches_its_emitters_from_free_to_drain() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1147,8 +786,7 @@ pub(crate) mod tests {
         );
     }
 
-    /// Camera at the origin looking down −Z (Bevy's convention), and an owner sphere `depth` yd
-    /// straight ahead — the geometry every draw-set test below uses.
+    /// The camera at the origin looking down −Z, the owner sphere `depth` yd straight ahead.
     fn gate(radius: f32, depth: f32, farclip: f32) -> bool {
         EmitterFade {
             radius,
@@ -1159,12 +797,8 @@ pub(crate) mod tests {
         .in_draw_set(Vec3::ZERO, Vec3::NEG_Z, farclip, true, true, true)
     }
 
-    /// **The owner-last rung, pinned** (decisions 0719/0721), through the wrapper the renderer
-    /// actually calls. The whole point of it is one inequality — the rung must be STRICTLY greater
-    /// than the owner's reach, or a batch centred at the edge of the model ties with the effect and
-    /// the draw order goes back to being whatever the queue emitted. The voidwalker (reach 3.666 yd
-    /// by the old vertex bound, 1.945 by the batch-centre one) is the measured case; the integer
-    /// reach is the one that would tie under a bare `ceil`.
+    /// The rung must clear the reach strictly, or a batch at the model's edge ties with the effect;
+    /// an integer reach would tie under a bare `ceil`. 3.666 yd is a voidwalker's vertex bound.
     #[test]
     fn the_owner_last_rung_always_clears_the_owner() {
         for reach in [0.0f32, 0.5, 1.0, 3.666, 4.0, 7.999, 12.0, 31.5] {
@@ -1172,32 +806,22 @@ pub(crate) mod tests {
             assert!(rung > reach, "rung {rung} must clear reach {reach}");
             assert_eq!(rung, rung.trunc(), "rung {rung} must be a whole yard");
         }
-        // A model too big for the ladder is capped rather than allowed to climb into
-        // `sky_order`'s rungs — it loses its own ordering, not the world's.
+        // Capped below `sky_order`'s rungs: a huge model loses its own ordering, not the world's.
         assert_eq!(owner_last_bias(500.0), 32.0);
         assert_eq!(owner_last_bias(-1.0), 1.0);
     }
 
-    /// **The B39 defect, pinned** (decision 0678). An owner bigger than `NEVER_FADE_RADIUS` never
-    /// distance-fades, so the fade term admits it at every distance — the far-clip term is the only
-    /// thing that stops its emitter. Reverting that term makes this test fail, which is the point:
-    /// a big fire prop's flames used to draw a kilometre away, over terrain the same wall had
-    /// already discarded.
     #[test]
     fn a_never_fading_owner_is_still_bounded_by_the_wall() {
         let big = crate::model_fade::NEVER_FADE_RADIUS + 5.0;
-        // The fade term alone says "draw" at any distance — that is what made this invisible.
         assert_eq!(crate::model_fade::doodad_fade_alpha(big, 5000.0), 1.0);
         assert!(gate(big, 500.0, 777.0), "inside the wall: draws");
         assert!(!gate(big, 1000.0, 777.0), "past the wall: must NOT draw");
-        // ...and it tracks the live farclip, not a constant: the same emitter at the vanilla
-        // minimum view distance is out, at the panel's maximum it is back in.
+        // The live farclip, not a constant: out at the minimum view distance, in at the maximum.
         assert!(!gate(big, 500.0, 177.0));
         assert!(gate(big, 1000.0, 1200.0));
     }
 
-    /// The wall never *replaces* the fade cutoff — a small prop still pops at its own band end
-    /// (40→50 yd) far inside the wall. Both terms are live; neither subsumes the other.
     #[test]
     fn the_wall_does_not_replace_the_size_fade() {
         assert!(gate(0.3, 45.0, 777.0), "mid-band: still drawing");
@@ -1207,8 +831,6 @@ pub(crate) mod tests {
         );
     }
 
-    /// The lateral frustum term is ANDed, not implied: an owner dead ahead and well inside the
-    /// wall is still out when the caller's frustum test rejects it (off-screen).
     #[test]
     fn the_lateral_frustum_term_is_anded() {
         let f = EmitterFade {
@@ -1219,21 +841,13 @@ pub(crate) mod tests {
         };
         assert!(f.in_draw_set(Vec3::ZERO, Vec3::NEG_Z, 777.0, true, true, true));
         assert!(!f.in_draw_set(Vec3::ZERO, Vec3::NEG_Z, 777.0, false, true, true));
-        // …and the exterior-window term is ANDed the same way (0786): a doodad no portal window
-        // admits is not in the worklist, so its emitter neither ticks nor draws.
+        // So is the exterior-window term.
         assert!(!f.in_draw_set(Vec3::ZERO, Vec3::NEG_Z, 777.0, true, false, true));
-        // …as is the room term (0689/1289): the window admits the BUILDING, the PVS admits the
-        // ROOM, and a prop in a culled room is one the reference never instantiated at all.
+        // And the room term: the window admits the building, the PVS the room.
         assert!(!f.in_draw_set(Vec3::ZERO, Vec3::NEG_Z, 777.0, true, true, false));
     }
 
-    /// **The exemption, on the emitter lane.** A sealed room (no windows) admits no exterior scene
-    /// — but the props of the building the camera is standing IN are not exterior to it, and their
-    /// flames must keep burning. Getting this wrong does not look like a cull bug; it looks like
-    /// walking into an inn snuffs its fireplace, which is why it is pinned rather than argued.
-    ///
-    /// The third case is the reported one: an ADT map doodad carries no building at all, so a
-    /// sealed room must stop it (`plaguelandmushroom01`'s spore cloud, seen through a wall).
+    /// A building's props are not exterior to a camera inside it; an ADT doodad belongs to none.
     #[test]
     fn a_sealed_room_keeps_its_own_props_burning_and_stops_everything_else() {
         use crate::exterior_cull::ExteriorGate;
@@ -1259,24 +873,15 @@ pub(crate) mod tests {
             !fade(None).exterior_admitted(&sealed, Some(here)),
             "an ADT map doodad belongs to no building — the reported mushroom"
         );
-        // Outdoors the gate stands down and every one of them emits again.
+        // Outdoors the gate stands down.
         for instance in [Some(here), Some(elsewhere), None] {
             assert!(fade(instance).exterior_admitted(&ExteriorGate::Open, Some(here)));
         }
-        // …and with no room claimed at all, `None == None` must NOT read as "my own building".
+        // With no instance on either side, `None == None` is not the camera's own building.
         assert!(!fade(None).exterior_admitted(&sealed, None));
     }
 
-    /// **A prop in a culled room emits nothing, and an orphaned emitter refuses.**
-    ///
-    /// The reference instantiates a WMO's props out of each VISIBLE group's own MODR list
-    /// (`0x695aa0` from the visible-group walk `0x698720`, decision 0689) — a prop in a culled room
-    /// is never created, so it has no emitters to tick. Our props' *meshes* are culled by exactly
-    /// this predicate and their emitters were not, which is how Caverns of Time's twelve
-    /// energy-trail props kept ninety additive ribbon strips burning up through 200 yd of rock into
-    /// Tanaris while every one of their submeshes was correctly hidden (decision 1289).
-    ///
-    /// All four arms, including the one that fails CLOSED where the rest of the cull fails open.
+    /// All four arms of the room gate, including the one that fails closed.
     #[test]
     fn a_prop_in_a_culled_room_emits_nothing_and_an_orphan_refuses() {
         use crate::wmo_portal::{WmoGroupVis, WmoPortalInstance};
@@ -1299,35 +904,24 @@ pub(crate) mod tests {
             }),
         };
 
-        // Not a building's prop at all — an ADT map doodad, a creature, a held item's streak.
+        // Not a building's prop: never gated.
         assert!(
             fade(None).room_admitted(Some(&cot)),
             "an unclaimed emitter is never gated"
         );
-        // The room the flood reached draws; the ones it did not, do not.
         assert!(fade(Some(&[0])).room_admitted(Some(&cot)));
         assert!(!fade(Some(&[1, 2])).room_admitted(Some(&cot)));
-        // A prop several rooms name draws while ANY of them is visible — the same `drawn_by` law
-        // the submeshes take, which is the whole point of sharing the predicate.
+        // A prop several rooms name draws while any is visible, the submeshes' `drawn_by` law.
         assert!(fade(Some(&[1, 0])).room_admitted(Some(&cot)));
-        // …and the asymmetry that must NOT be the cull's usual fail-open: an emitter whose
-        // placement has despawned refuses, rather than drawing one last frame through the hole
-        // where a building used to be.
+        // Unlike the rest of the cull, a despawned placement fails closed.
         assert!(
             !fade(Some(&[0])).room_admitted(None),
             "an orphaned emitter draws nothing"
         );
     }
 
-    /// The emitter gate and the owner mesh's own cull must agree on the boundary — they read the
-    /// same `within_farclip` now, and this pins that they cannot drift apart again. An emitter
-    /// admitted where its owner's mesh is culled IS bug B39.
-    ///
-    /// Scoped to owners **above** `NEVER_FADE_RADIUS` on purpose: there the size-fade term is a
-    /// constant `1.0`, so the gate reduces to the wall alone and the comparison is exact. Below it
-    /// the two rules legitimately differ (the mesh keeps drawing while the fade feathers it out),
-    /// so an equality there would be asserting something false — and these are the owners that
-    /// carry the big effects the report is about anyway.
+    /// Owners above `NEVER_FADE_RADIUS` only: there the fade term is a constant 1, so the gate is
+    /// the wall alone; below it the mesh keeps drawing while the fade feathers it out.
     #[test]
     fn the_emitter_gate_agrees_with_the_owner_meshs_cull() {
         let (cam, fwd) = (Vec3::ZERO, Vec3::NEG_Z);
@@ -1357,11 +951,7 @@ pub(crate) mod tests {
         }
     }
 
-    /// The BURST emission model (file flag 0x8000 — Feint/Eviscerate impact's plume+crescents):
-    /// one `ftol(rate·scale)` puff on the rising edge of `(enabled && rate > 0)`, latched while
-    /// the gate holds, re-armed when it falls. (The rate/enabled *sampling* laws — step vs lerp
-    /// vs held tail, per sequence window — are pinned in `benilla-formats`' `emit_timing` tests,
-    /// where the bake lives.)
+    /// File flag `0x8000`, as on the Feint and Eviscerate impact puffs.
     #[test]
     fn burst_emitter_fires_once_on_the_rising_edge() {
         let (mut acc, mut prev) = (0.0, false);
@@ -1381,8 +971,7 @@ pub(crate) mod tests {
         accumulate_emission(true, 30.0, true, 1.0, 0.016, &mut acc, &mut prev);
         accumulate_emission(true, 30.0, true, 1.0, 0.016, &mut acc, &mut prev);
         assert_eq!(acc, 0.0, "held-high gate stays latched — never a pour");
-        // The gate falls (drain/disable) → re-arms → the next rise bursts again (a looping
-        // clip's next pass), the count ftol-truncated through density·LOD.
+        // The gate falls and re-arms; the next rise bursts again, truncated through the scale.
         accumulate_emission(true, 30.0, false, 1.0, 0.016, &mut acc, &mut prev);
         assert_eq!(
             accumulate_emission(true, 30.0, true, 0.55, 0.016, &mut acc, &mut prev),
@@ -1391,8 +980,7 @@ pub(crate) mod tests {
         );
     }
 
-    /// The continuous emission model (flag clear) pours `rate·dt` — and drops its owed
-    /// fraction while disabled (the pre-existing drain hygiene).
+    /// A continuous emitter drops its owed fraction while disabled.
     #[test]
     fn continuous_emitter_pours_rate_dt() {
         let (mut acc, mut prev) = (0.0, false);
@@ -1403,9 +991,8 @@ pub(crate) mod tests {
         assert_eq!(acc, 0.0, "disabled zeroes the owed fraction");
     }
 
-    /// The follow-delta response line (`0x7b5d30`): the line through the two authored
-    /// (speed, fraction) samples; equal speeds degenerate to no response (the reference zeroes
-    /// slope and intercept).
+    /// The follow-delta response (`0x7b5d30`): the line through the two authored (speed,
+    /// fraction) samples, zeroed for equal speeds as in the reference.
     #[test]
     fn follow_line_matches_the_authored_two_point_response() {
         let mut d = super::emit::tests::def(ParticleShape::Plane);
diff --git a/crates/benilla-world/src/particles/buffer.rs b/crates/benilla-world/src/particles/buffer.rs
index 43106b9d..a829f3da 100644
--- a/crates/benilla-world/src/particles/buffer.rs
+++ b/crates/benilla-world/src/particles/buffer.rs
@@ -1,32 +1,8 @@
-//! The **shared effect stream** — the one CPU vertex stream every dynamic-effect family writes
-//! into each frame (particles, ribbons, and — since 0733 — the decal family, water foam, and
-//! precipitation), and the draw records that slice it (decisions 0732 P1/P2, 0733).
-//!
-//! Before this, every effect owned a `Mesh` asset rewritten per frame: ~145 mesh `Modified`
-//! events/frame at the LBRS pin, each a full free+realloc in Bevy's mesh allocator (no partial
-//! update exists — `allocator.rs:650`), and together they held the `AssetChanged<Mesh3d>`
-//! short-circuit open so every material type's specialization probe ran over its whole
-//! population every frame. One shared buffer + directly-constructed `Transparent3d` items
-//! (the bevy_ui_render shape) converts the whole family from population-priced to
-//! change-priced: one `write_buffer` per frame, zero mesh assets, zero material assets.
-//!
-//! The write protocol: a system calls [`EffectQuads::begin`], pushes **world-space** vertices —
-//! whole quads (4 corners in perimeter order, closed by the `[0,1,2, 0,2,3]` pattern) or a
-//! triangle list — then commits one draw for the range ([`EffectQuads::commit_quads`] /
-//! [`EffectQuads::commit_tris`]). The render half rebases every draw's vertices against its
-//! target view's camera position before upload (0733 §2 — absolute coordinates through the view
-//! transform shear thin geometry apart far from the origin; the precip module learned this
-//! empirically at ~9000 yd), builds the frame's index stream in sorted-item order, and merges
-//! sort-adjacent draws that share (pipeline, texture, light, fog) into single draw calls
-//! (0732 P2). The sort key is [`EffectDraw::anchor`] view-z + [`EffectDraw::bias`] — the ladder
-//! rungs (owner-last 0719/0721, the decal biases, foam's water tie-break) moved from material
-//! `depth_bias` into the item key (`sky_order`'s sign law); the rasterizer half of the old
-//! material `depth_bias` lives on as [`EffectDraw::raster_bias`] (the coplanar decals need it).
-//!
-//! The rebase is a *late* subtraction, which is fine until a producer's geometry is smaller than
-//! an f32 ULP at the position it writes — the rounding has already happened by then. The snow
-//! flake reached that (millimetre quads at ~5600-yd coordinates), so a draw may declare
-//! [`EffectDrawSpec::cam_relative`] and do the subtraction itself.
+//! The shared effect stream: one CPU vertex stream every dynamic-effect family writes each frame,
+//! and the draw records slicing it. A writer calls [`EffectQuads::begin`], pushes world-space
+//! vertices (whole quads in perimeter order, or a triangle list) and commits one draw for the
+//! range; the render half rebases them camera-relative for upload (absolute f32 shears thin
+//! geometry far from the origin) and sorts by [`EffectDraw::anchor`] view z plus the rung.
 
 use std::ops::Range;
 
@@ -35,41 +11,33 @@ use bevy::asset::AssetId;
 use bevy::prelude::*;
 use bevy::render::render_resource::Buffer;
 
-/// One vertex of the shared lane. **World-space** position in the stream; the render-world
-/// prepare pass rebases it camera-relative before upload (0733 §2), so instruments reading the
-/// stream (depth probe, depth dump) always see world coordinates — with one declared exception,
-/// [`EffectDrawSpec::cam_relative`], whose producer has already done the subtraction because its
-/// geometry is too small to survive being written in absolute-world f32 at all.
+/// One vertex of the lane: world-space in the stream, so instruments read world coordinates,
+/// except on a [`EffectDrawSpec::cam_relative`] draw.
 #[repr(C)]
 #[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
 pub struct EffectVertex {
     pub pos: [f32; 3],
     pub uv: [f32; 2],
-    /// RAW authored gamma-space RGBA (the GAMMA LANE invariant, 0161) — alpha is the blend
-    /// weight, never encoded.
+    /// Raw authored gamma-space RGBA; alpha is the blend weight, never encoded.
     pub color: [f32; 4],
 }
 
-/// The lane's blend variants (0733 §4) — a superset of the file-format enums it serves:
-/// [`ParticleBlend`]'s four, plus the multiplicative pair the decal family and rain need.
+/// The lane's blends: [`ParticleBlend`]'s four plus the multiplicative pair of decals and rain.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum EffectBlend {
-    /// `(SRC_ALPHA, ONE)` via premultiplied-alpha + the shader's gamma `rgb·a` fold (0160/0161).
+    /// `(SRC_ALPHA, ONE)`, as premultiplied alpha after the shader's gamma `rgb·a` fold.
     Add,
     /// Standard alpha blending.
     Alpha,
-    /// No blend, depth-write ON — drawn in the transparent bracket at the owner rung (0719).
+    /// No blend, depth write on, drawn in the transparent bracket at the owner rung.
     Opaque,
-    /// [`EffectBlend::Opaque`]'s state plus the fixed-function **alpha test** — the fragment is
-    /// discarded below `224/255` ([`benilla_assets`]'s `VANILLA_ALPHA_KEY_REF`, the same ref the
-    /// mesh path's cutouts take). EGxBlend 1, the debris/chip family; the byte chain that pins
-    /// blend-off + z-write-on + that ref is on [`ParticleBlend::AlphaKey`].
+    /// EGxBlend 1: [`EffectBlend::Opaque`]'s state plus an alpha test discarding below 224/255
+    /// (`VANILLA_ALPHA_KEY_REF`, the mesh cutouts' ref; see [`ParticleBlend::AlphaKey`]).
     AlphaKey,
-    /// `dst · lerp(1, src, α)` — bevy's `AlphaMode::Multiply` state (`(Dst, 1−srcα)` + shader
-    /// premultiply, bevy_pbr mesh.rs:2486): the blob shadow's `GL_DST_COLOR/GL_ZERO`-with-fade,
-    /// and `ModelBlend::Mod` (0528) at α = 1.
+    /// `dst · lerp(1, src, α)`, bevy's `AlphaMode::Multiply` state: the blob shadow's
+    /// `GL_DST_COLOR/GL_ZERO` with fade, and `ModelBlend::Mod` at α = 1.
     Multiply,
-    /// `2·src·dst` — `(Dst, Src)`, 0528's factors; rain's verified state (rf-weather-render).
+    /// `2·src·dst` as `(Dst, Src)`: rain's state.
     Mod2x,
 }
 
@@ -85,25 +53,13 @@ impl From<ParticleBlend> for EffectBlend {
 }
 
 impl EffectBlend {
-    /// The ground-fx mapping from a part's authored blend — `model_render.rs`'s law with the
-    /// lane's two named approximations: `AlphaTest` folds to `Alpha` (**deliberately not**
-    /// [`EffectBlend::AlphaKey`], which the particle side now takes — the groundscan census says
-    /// flat `Spells\` quads are blend batches, and a cutout ref on a soft-edged decal would bite
-    /// its fade), and the part renders unlit (spell fx are; a lit ground quad would differ — none
-    /// observed).
-    ///
-    /// `additive` is a SECOND, non-optional input because [`ModelBlend`] cannot express additive:
-    /// M2 blend modes 3/4 fold into its `Blend` variant (see its own doc, "Alpha-blended /
-    /// additive"), and the material path recovers them from `model_render`'s separate
-    /// `is_additive` flag. Taking only the enum made this function *unable* to be right for an
-    /// additive batch — every `Spells\` ground quad is mode 4, so Arcane Explosion / Blast Wave /
-    /// Battle Shout drew their black-backed additive art alpha-blended: an opaque black tile
-    /// (decision 0748). Keeping it in the signature is what stops the next caller repeating it.
+    /// The ground-fx mapping of a part's blend: `model_render`'s, with `additive` apart because M2
+    /// modes 3 and 4 fold into [`ModelBlend::Blend`]. Deviation: `AlphaTest` maps to `Alpha`,
+    /// because flat `Spells\` quads are blend batches and a cutout would bite a soft decal's fade;
+    /// and the part draws unlit, as no lit ground-fx part is known.
     pub fn from_model(blend: ModelBlend, additive: bool) -> Self {
         if additive {
-            // `BLEND_ADD` is byte-for-byte the material path's additive: the shader gamma-
-            // premultiplies (`rgb·α`) and returns α = 0, turning `(One, 1−srcα)` into pure
-            // addition — the same fold `specialize` gates on marker bit 2 (0160/0161).
+            // The material path's additive: the shader premultiplies `rgb·α` and returns α = 0.
             return EffectBlend::Add;
         }
         match blend {
@@ -124,33 +80,25 @@ pub enum EffectTopology {
     Tris,
 }
 
-/// The fog COLOUR policy for one draw — `params.x`/`params.y` of the effect shader; each
-/// variant is one canonical row of the render-world params uniform.
+/// One draw's fog colour policy, one canonical row of the shader's params uniform.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum EffectFog {
-    /// File flag 0x8 ("unfogged") — fog disabled outright (params.x = 0). Also the decal
-    /// family's and foam's verified state.
+    /// No fog (params.x = 0): file flag 0x8, the decals and foam.
     Off,
-    /// The ordinary day-night scene fog (params.x = 1) — Alpha/Opaque blends.
+    /// The scene fog (params.x = 1): Alpha and Opaque blends.
     Scene,
-    /// Fog toward BLACK (params.x = 2) — an Add-blend emitter fades under a veil instead of
-    /// gaining grey (the same per-blend fog table M2 batches take, `0x70baf0`).
+    /// Toward black (params.x = 2), for Add blends, from M2's per-blend fog table (`0x70baf0`).
     Black,
-    /// Fog toward WHITE (params.x = 3) — the `0x70baf0` table's Mod policy (a multiplier fades
-    /// to the identity, not to the scene colour). Ground-fx decals with `ModelBlend::Mod`.
+    /// Toward white (params.x = 3), the table's Mod policy: ground-fx `ModelBlend::Mod` decals.
     White,
-    /// Fog toward GREY-0.5 (params.x = 4) — the table's Mod2x policy (grey is 2·src·dst's
-    /// neutral). Ground-fx decals with `ModelBlend::Mod2x`.
+    /// Toward grey 0.5 (params.x = 4), the table's Mod2x policy: ground-fx Mod2x decals.
     Grey,
-    /// Rain's FORCED grey fog (scene fog off; params.y = 1 with zw = 70..75) — under Mod2x the
-    /// grey-0.5 fog colour is neutral, so this IS the streak/patter distance fade
-    /// (rf-weather-render Q3; the row values live with their law in `weather::precip`).
+    /// Rain's forced grey fog (params.y = 1, zw 70..75), its Mod2x distance fade (`0x59d350`).
     Rain,
 }
 
 impl EffectFog {
-    /// The policy for one particle/ribbon def — the exact table `particle_material` applied
-    /// (file flag 0x8 wins, then Add ⇒ black, else scene).
+    /// The policy for one particle or ribbon def.
     pub fn for_blend(flags: u32, blend: ParticleBlend) -> Self {
         if flags & 0x8 != 0 {
             EffectFog::Off
@@ -161,9 +109,7 @@ impl EffectFog {
         }
     }
 
-    /// The `0x70baf0` fog policy baked into a model material's `clutter_fade.z` bits 4..7
-    /// (`wow_model.wgsl:761` decodes the same field): 0 scene, 1 black, 2 white, 3 grey,
-    /// 4 unfogged — the ground-fx decal reads its part's authored policy through this.
+    /// The `0x70baf0` fog policy a model material packs in `clutter_fade.z` bits 4..7.
     pub fn from_model_policy(policy: u32) -> Self {
         match policy {
             1 => EffectFog::Black,
@@ -187,115 +133,62 @@ impl EffectFog {
     }
 }
 
-/// Where one draw's light comes from — the lane's third per-draw identity axis, beside
-/// [`EffectBlend`] and [`EffectFog`].
-///
-/// The reference has no particle material: it synthesizes an `M2Material` from the emitter's file
-/// record every draw and runs the ordinary per-batch state producer over it, so `GL_LIGHTING`
-/// lands on a particle quad exactly as it does on a mesh submesh — and the light it lands with is
-/// the **model's own light node**, not the scene's (wow-re `part-lit-normal-space.md` §5/§6). Which
-/// node the model is on is what these three variants name.
+/// Where one draw's light comes from. The reference builds an `M2Material` from each emitter
+/// record, so a particle is lit like a submesh, by its model's own light node (`0x672a20`).
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default)]
 pub enum EffectLighting {
-    /// The authored colour burns as it is. The lane's default, and every family but one: ribbons,
-    /// decals, the rings/reticle and precipitation are all authored to burn at their own colour,
-    /// as is an M2 emitter that SETS the file's unlit bit 0x1 (the fire and spell corpus, which is
-    /// why it stays bright at night).
+    /// Unlit: every family but M2 emitters, and the emitters that set the file's unlit bit 0x1.
     #[default]
     None,
-    /// The **scene's** light, applied per view in the fragment shader against the world up axis —
-    /// the outdoor lane, and the one a booth's own light buffer overrides. 400 of the corpus's
-    /// 7792 emitters clear the unlit bit and land here, nearly all of them `World\` environment
-    /// sheets: waterfall spray, chimney smoke, blown dust, snow, which read as full-white cutouts
-    /// against shaded terrain when the term is missing (the Zul'Gurub waterfall foam).
-    /// [`EffectDraw::lit`] is this variant and only this variant.
+    /// The scene's light, per view in the shader against world up (a booth's buffer overrides
+    /// it): a lit emitter outdoors, mostly `World\` environment sheets.
     Scene,
-    /// The emitter's model carries its **own committed light**: it stands inside a WMO room, where
-    /// the reference lights the object from its light node's footprint-MOCV words on a fixed axis
-    /// plus the room's MOLT points, and never from the day/night sun (`part-lit-normal-space.md`
-    /// §6.7, the WENTITY provider `0x6a7300`'s interior leg).
-    ///
-    /// A particle quad carries exactly one normal, so that whole node collapses to three floats
-    /// ([`crate::interior::ParticleLight`]) and the producer has **already folded them into this
-    /// draw's vertex colours** — which is why this shares a pipeline with [`Self::None`]: there is
-    /// nothing left for the shader to do. Per-draw constants belong in the vertex stream on a lane
-    /// whose whole design is one shared buffer of them.
+    /// The model's own committed light in a WMO room, never the sun (`0x6a7300`'s interior leg);
+    /// one normal per quad makes it one RGB, already folded into the vertex colours.
     Committed,
 }
 
-/// A per-emitter light-buffer override: this emitter's fragment reads THIS `WowLight` blob
-/// instead of the world's shared one. The glue-scene booths are the one author (decision 0539
-/// §5 — their braziers are fogged by the SCENE's own light buffer, the ModelFFX fog that
-/// covers the whole backdrop model); the call site inserts it on the spawned emitter entity.
+/// A per-emitter `WowLight` buffer read in place of the world's; the glue-scene booths set it.
 #[derive(Component, Clone)]
 pub struct EffectLightOverride(pub Buffer);
 
-/// One draw of the shared lane: a contiguous vertex range, its texture/blend/fog identity, and
-/// the sort point the render-world queue keys it by.
+/// One draw of the lane: a vertex range, its texture, blend and fog, and its sort point.
 pub struct EffectDraw {
-    /// The MAIN-world camera entity whose view this draw belongs to (the world camera, or a
-    /// booth camera for a booth-layered emitter — the sim already resolves this per emitter).
-    /// The render-world phase lookup keys on the retained view's main entity, so no
-    /// `RenderLayers` plumbing is needed render-side.
+    /// The main-world camera whose view draws this (the world's, or a booth's).
     pub cam: Entity,
     pub(crate) texture: AssetId<Image>,
     pub(crate) blend: EffectBlend,
     pub(crate) topology: EffectTopology,
     pub(crate) fog: EffectFog,
-    /// Does the SHADER multiply this draw's RGB by the scene's light? True for
-    /// [`EffectLighting::Scene`] alone — a pipeline-key axis, so the merge walk separates lit from
-    /// unlit runs through the pipeline id. A [`EffectLighting::Committed`] draw is `false`: its
-    /// light is already in the vertices.
+    /// The shader applies the scene's light: [`EffectLighting::Scene`] alone, a pipeline-key axis.
     pub lit: bool,
-    /// The cloud's sort point — the emitter anchor / ribbon head node / decal center, exactly
-    /// the sort point the material path used.
+    /// The sort point: the emitter anchor, ribbon head node or decal centre.
     pub(crate) anchor: Vec3,
-    /// The ladder rung added to the view-space sort distance — owner-last (0719/0721) for
-    /// emitters, the decal constants (ring/ground-fx 8192, shadow 4096), foam's +1 water
-    /// tie-break; `sky_order`'s sign law (positive draws later).
+    /// The rung added to the view-space sort distance (`sky_order`: positive draws later).
     pub(crate) bias: f32,
-    /// The rasterizer `DepthBiasState` constant for this draw's pipeline (0733 §4): the
-    /// coplanar decals keep the depth-offset half their materials carried (projected verts are
-    /// exact sub-pieces of drawn ground — clip-interpolated vertices land within ULPs of it);
-    /// everything free-floating passes 0. Nonzero ALSO selects the decal transform (0781):
-    /// the draw's verts skip the cam-relative rebase and run the world-mesh `clip_from_world`,
-    /// so the depth tie the bias settles is against the same arithmetic.
+    /// The rasterizer depth-bias constant, nonzero only for coplanar draws, which then skip the
+    /// rebase for the world meshes' own `clip_from_world`, so the tie it settles is like for like.
     pub(crate) raster_bias: i32,
-    /// The slope-scale half of the settle — see [`EffectDrawSpec::raster_slope`].
     pub(crate) raster_slope: f32,
-    /// Are this draw's vertices **already camera-relative**? See [`EffectDrawSpec::cam_relative`].
     pub(crate) cam_relative: bool,
-    /// Does this draw ignore the depth buffer? See [`EffectDrawSpec::no_depth_test`].
     pub(crate) no_depth_test: bool,
     /// Vertex range in [`EffectQuads::verts`] (a multiple of 4 for quads, 3 for tris).
     pub range: Range<u32>,
-    /// The producing entity — the phase probe's identity for this item (`item.entity.1`, so a
-    /// phase line still names the pool that produced it).
+    /// The producing entity, the item's identity in the phase (`item.entity.1`).
     pub main_entity: Entity,
-    /// [`EffectLightOverride`]'s buffer, when the producer carries one (`None` = the world's
-    /// shared light buffer).
+    /// [`EffectLightOverride`]'s buffer; `None` is the world's.
     pub(crate) light: Option<Buffer>,
-    /// The target-pixel rectangle this draw is clipped to — see [`EffectDrawSpec::clip`].
     pub(crate) clip: Option<Vec4>,
 }
 
-/// The frame's shared stream. Cleared at the top of `PostUpdate`'s effect set
-/// ([`begin_effect_frame`]), filled by the family systems, copied to the render world in
-/// `ExtractSchedule`.
+/// The frame's stream: cleared by [`begin_effect_frame`], filled by the families, extracted.
 #[derive(Resource)]
 pub struct EffectQuads {
     pub verts: Vec<EffectVertex>,
     pub draws: Vec<EffectDraw>,
-    /// Has [`begin_effect_frame`] run yet **this** frame? A writer that commits while this is
-    /// `false` ran BEFORE the clear, so everything it pushed is about to be erased — a silent,
-    /// total loss of that lane's frame, with its arithmetic entirely correct.
-    ///
-    /// This is the shape of B161: the chain beam declared its pose dependencies but not
-    /// `.after(begin_effect_frame)`, the clear carried one extra `.after` the beam did not, and
-    /// the beam became runnable first. Nothing warned; the lane simply never drew. The ordering
-    /// is unenforceable by the type system (any writer can forget an edge), so the protocol is
-    /// asserted here instead — [`Self::commit`] refuses a pre-clear write in debug builds, and
-    /// [`clear_effect_frame_flag`] arms it again in `Last`.
+    /// Has [`begin_effect_frame`] run this frame? A commit before it would be erased, so
+    /// [`Self::commit`] asserts it in debug builds: every writer needs
+    /// `.after(begin_effect_frame)`. [`clear_effect_frame_flag`] resets it in `Last`.
     cleared_this_frame: bool,
 }
 
@@ -304,90 +197,39 @@ impl Default for EffectQuads {
         Self {
             verts: Vec::new(),
             draws: Vec::new(),
-            // Armed, not tripped: a fixture that commits into a bare stream (most of the family's
-            // unit tests) is testing geometry, not schedule order, and has no clear to run. The
-            // `Last` re-arm is what makes the flag mean anything, and it only exists in an app
-            // carrying `ParticlePlugin` — where the very first frame's clear precedes any writer
-            // regardless, and a mis-ordered writer trips on frame two and every frame after.
+            // True, so a fixture with no clear can commit; the app's `Last` reset arms the check.
             cleared_this_frame: true,
         }
     }
 }
 
-/// Everything about one draw except its vertex range — the argument bundle `commit_quads` /
-/// `commit_tris` close a range with.
+/// Everything about one draw but its vertex range, as `commit_quads` and `commit_tris` take it.
 pub struct EffectDrawSpec {
     pub cam: Entity,
     pub texture: AssetId<Image>,
     pub blend: EffectBlend,
     pub fog: EffectFog,
-    /// Which light this draw's authored colour meets — see [`EffectLighting`]. The scene's term is
-    /// `clamp(ambient + diffuse·max(N·L,0))` against the **world up axis**, the same shape
-    /// `wow_model.wgsl` applies to a mesh: the reference's quad writer uploads one constant normal
-    /// for the whole draw — world +Z carried into eye space, against a light carried into the same
-    /// frame, so the product is the view-invariant `worldUp · worldLightDir` (wow-re
-    /// `part-lit-normal-space.md`; decision 1696 supersedes 0975's camera-facing reading). The
-    /// gate on whether an emitter takes any of it is the file's unlit bit
-    /// ([`benilla_formats::ParticleEmitterDef::lit`], byte law there).
+    /// The light the colour meets. The scene term is `clamp(ambient + diffuse·max(N·L, 0))` with
+    /// N world up: the reference uploads one normal per draw, world +Z (`0x7b3fd0`).
     pub lighting: EffectLighting,
     pub anchor: Vec3,
     pub bias: f32,
     pub raster_bias: i32,
-    /// The rasterizer `DepthBiasState` **slope-scale** half of this draw's settle — the term that
-    /// scales with the primitive's own depth slope, and the one a near-horizontal decal seen at a
-    /// grazing angle actually needs (a constant cannot follow a surface whose depth gradient runs
-    /// away from the eye). `0.0` for every family with no coplanar receiver.
-    ///
-    /// It exists because the reference has one: the sole `glPolygonOffset` site (`0x59bf0a`, a
-    /// hardcoded `0xc0800000`) arms `factor = −4.0` alongside the units term whenever EGxRs id `0`
-    /// is set non-zero, which is what the foam draw's `0x68fd0f` does. 1809.
+    /// The rasterizer depth-bias slope scale. The reference uses none: its one slope term
+    /// (`0x59bf0a`, `glPolygonOffset` factor `0xc0800000` = −4.0) is in the GL arm, never built.
     pub raster_slope: f32,
-    /// Set when the producer has **already** written camera-relative vertices, so
-    /// [`super::render`]'s rebase must skip this draw. The default (`false`) is the lane's
-    /// contract: producers write ABSOLUTE world positions and the rebase subtracts the camera
-    /// on the upload copy.
-    ///
-    /// It exists for **precision**, and precisely one family needs it. `EffectVertex::pos` is
-    /// f32, WoW world coordinates run to ±17066 yd, and the rebase happens *after* the producer's
-    /// rounding — so a vertex offset smaller than an ULP at the writing position is simply lost.
-    /// Every other family's geometry is centimetre-scale or bigger and never notices. The snow
-    /// flake is the lane's first **sub-centimetre** geometry: reproducing the reference's point
-    /// sprite (14 px at the eye) puts a near flake's half-extent at ~1.6 mm, which at Kharanos's
-    /// ~5600-yd coordinates is **3 ULPs** and at a map corner **0.8** — measured: a 14 px sprite
-    /// 0.3 yd from the eye loses 2.4 px of width there and 6+ px at the map edge, i.e. visible
-    /// size flicker and dropouts on exactly the flakes the eye is drawn to. Writing the offsets
-    /// camera-relative keeps every term small and the arithmetic exact.
-    ///
-    /// The sort [`Self::anchor`] stays absolute either way — it is not a vertex.
+    /// The producer wrote camera-relative vertices, so the upload rebase skips this draw: the
+    /// snow flake's sub-centimetre geometry, which absolute f32 world coordinates cannot hold.
+    /// [`Self::anchor`] stays absolute.
     pub cam_relative: bool,
-    /// **Draw over everything** — force the depth COMPARE to `Always`, so this draw is never
-    /// occluded by anything already in the depth buffer. Nothing is depth-*written* either way on
-    /// a blended draw, so it occludes nothing in turn.
-    ///
-    /// The lane's default is `false`, and it stays the default: a depth-tested transparent is what
-    /// every particle, ribbon, decal and streak wants. One family sets it — the weapon swing trail,
-    /// whose callback writes EGxRs id `0x10` to `0` (`0x6c686e`; GL `glDisable(GL_DEPTH_TEST)`,
-    /// D3D `ZFUNC = D3DCMP_ALWAYS`) so the arc is never eaten by the swinging character's own
-    /// shoulder (wow-re `charproc8-trail-draw-state.md` §1; decision 2076).
+    /// Depth compare `Always`: the weapon swing trail, whose callback turns the depth test off
+    /// (EGxRs id `0x10` = 0, `0x6c686e`) so the swinger's shoulder never eats the arc.
     pub no_depth_test: bool,
     pub main_entity: Entity,
     pub light: Option<Buffer>,
-    /// **Clip this draw to a rectangle of its RENDER TARGET, in target pixels** — `(min.x,
-    /// min.y, max.x, max.y)`, `None` for the whole target, which is every world family.
-    ///
-    /// It exists for the UI model tiles (decision 2008): every visible `<Model>` pane renders
-    /// into its own cell of ONE shared atlas, and a pane's particles are quads in that atlas's
-    /// space — so a cloud that reaches past its cell lands in the cell **next to** it, which the
-    /// composite hands to a different widget. The reference cannot have this: it draws each
-    /// `<Model>` straight into the back buffer with the widget's own rect as the VIEWPORT
-    /// (wow-re `modelframe-render-law.md` §6), and the scissor eats the overflow. One shared
-    /// camera cannot carry a viewport per pane, so the clip rides the draw instead and the
-    /// fragment discards outside it — the same picture, at the same rank.
-    ///
-    /// B379: the pet bar's autocast shine (`UI-AutoCastButton.m2` — four additive spline
-    /// emitters, no render batch at all) circles its button on the very edge with an ~8 px
-    /// half-extent, which spilled six pixels of golden `GlowStar` across the 2-texel gutter and
-    /// down the LEFT edge of whatever cooldown pane the shelf packed beside it.
+    /// A target-pixel clip rect `(min.x, min.y, max.x, max.y)`; `None` is the whole target. UI
+    /// model tiles share one atlas where the reference gives each `<Model>` its own viewport
+    /// (`0x59c730`), so the fragment discards outside the pane's cell.
     pub clip: Option<Vec4>,
 }
 
@@ -397,8 +239,7 @@ impl EffectQuads {
         self.verts.len() as u32
     }
 
-    /// Close a quad draw over everything pushed since `begin`. A range that gained no vertices
-    /// commits nothing — the idle steady state costs zero here (the a5521180 law, structural).
+    /// Close a quad draw over everything pushed since `begin`; an empty range commits nothing.
     pub fn commit_quads(&mut self, start: u32, spec: EffectDrawSpec) {
         debug_assert_eq!((self.verts.len() as u32 - start) % 4, 0, "whole quads only");
         self.commit(start, EffectTopology::Quads, spec);
@@ -445,16 +286,14 @@ impl EffectQuads {
     }
 }
 
-/// Clear the stream for a new frame — scheduled before every family's writer, so the writer
-/// order between them stays free.
+/// Clear the stream for a new frame; every family's writer runs after it.
 pub fn begin_effect_frame(mut quads: ResMut<EffectQuads>) {
     quads.verts.clear();
     quads.draws.clear();
     quads.cleared_this_frame = true;
 }
 
-/// Disarm the write-order tripwire for the next frame — `Last`, after the render world has
-/// extracted this frame's stream. See [`EffectQuads::cleared_this_frame`].
+/// Reset [`EffectQuads::cleared_this_frame`] in `Last`, after extraction.
 pub fn clear_effect_frame_flag(mut quads: ResMut<EffectQuads>) {
     quads.cleared_this_frame = false;
 }
@@ -463,11 +302,7 @@ pub fn clear_effect_frame_flag(mut quads: ResMut<EffectQuads>) {
 mod tests {
     use super::*;
 
-    /// The additive flag OVERRIDES the folded enum (decision 0748). `ModelBlend::Blend` means
-    /// "alpha-blended **or** additive" — M2 modes 2/3/4 all land there — so a mapping that reads
-    /// only the enum cannot be right. Every `Spells\` flat ground quad in the 1.12.1 corpus is
-    /// mode 4 (`m2batch`: ArcaneExplosion_Base, BattleShout_Cast_Base, …), and drawing those
-    /// alpha-blended painted their black-backed additive art as an opaque black tile.
+    /// M2 modes 2 to 4 fold into `ModelBlend::Blend`; flat `Spells\` ground quads are mode 4.
     #[test]
     fn additive_wins_over_the_folded_blend_enum() {
         for blend in [
@@ -486,8 +321,7 @@ mod tests {
         }
     }
 
-    /// The non-additive law is unchanged — `model_render.rs`'s mapping, with `AlphaTest` folded
-    /// to `Alpha` (the lane has no Mask variant; flat `Spells\` quads are blend batches).
+    /// `model_render`'s mapping, with `AlphaTest` folded to `Alpha`.
     #[test]
     fn non_additive_keeps_the_material_paths_law() {
         assert_eq!(
@@ -512,14 +346,8 @@ mod tests {
         );
     }
 
-    /// **B161, as an executable record.** The chain beam shipped with correct arithmetic and no
-    /// `.after(begin_effect_frame)` edge, and drew nothing at all — for weeks, silently.
-    ///
-    /// The mechanism is not "the writers race": it is that the clear carries one dependency the
-    /// writer does not (`face_billboards`), so the writer becomes *runnable first* and the clear
-    /// lands on top of it. This pair pins both halves — the failure mode, and the edge that fixes
-    /// it. The graph below is the real registration shape of `ParticlePlugin` (the clear) and
-    /// `EntitiesPlugin` (the beam sim), transcribed.
+    /// A writer without `.after(begin_effect_frame)` runs first when the clear carries a
+    /// dependency it lacks; the graph is `ParticlePlugin`'s clear and `EntitiesPlugin`'s beam.
     mod write_order {
         use super::*;
 
@@ -560,7 +388,7 @@ mod tests {
             );
         }
 
-        /// `edged`: whether the writer declares the load-bearing `.after(begin_effect_frame)`.
+        /// `edged`: whether the writer declares `.after(begin_effect_frame)`.
         fn run(edged: bool) -> App {
             let mut app = App::new();
             app.init_resource::<EffectQuads>();
@@ -588,12 +416,11 @@ mod tests {
                     .in_set(Place)
                     .after(joint_palette)
                     .after(finalize_rigs)
-                    // The extra dependency the beam sim lacked — the whole mechanism.
+                    // The dependency the writer lacks.
                     .after(face_billboards),
             );
             app.add_systems(Last, clear_effect_frame_flag);
-            // Two frames: the first arms the tripwire (a bare stream defaults to armed, and the
-            // `Last` re-arm has not run yet), the second is any ordinary frame.
+            // Two frames: the check only bites after the first `Last` reset.
             app.update();
             app.update();
             app
@@ -608,7 +435,7 @@ mod tests {
             assert_eq!(quads.verts.len(), 4);
         }
 
-        /// Without it, the write precedes the clear — the tripwire that now names the bug.
+        /// Without it, the write precedes the clear and the debug assert fires.
         #[test]
         #[should_panic(expected = "effect-stream write before `begin_effect_frame`")]
         fn without_the_edge_the_tripwire_names_it() {
@@ -617,26 +444,15 @@ mod tests {
     }
 }
 
-/// **Draw a batch of quads or triangles in the effect lane** — the stream's face for everything
-/// that is not a particle.
-///
-/// Six lanes push into this buffer and every one of them wrote the same eleven-field
-/// [`EffectDrawSpec`] literal, of which three fields are the same value at every gameplay site
-/// (`lighting: None`, `cam_relative: false`, `light: None` — the exceptions are all engine-internal:
-/// M2 emitters light, the snow slab writes camera-relative, the booths bind their own buffer).
-/// A caller was choosing eight things and restating three.
-///
-/// The builder is what keeps [`EffectBlend`] and [`EffectFog`] off the doorway: a lane says
-/// `.additive()` rather than naming an enum, and the defaults it does not mention are the lane's
-/// contract rather than a line it had to copy correctly.
+/// Draw a batch of quads or triangles in the effect lane: the writer for everything but
+/// particles, with the lane's defaults for what it does not set.
 #[derive(bevy::ecs::system::SystemParam)]
 pub struct WorldEffectDraw<'w> {
     quads: ResMut<'w, EffectQuads>,
 }
 
 impl<'w> WorldEffectDraw<'w> {
-    /// Open a batch drawn through `cam` with `texture`. Nothing is committed until [`EffectBatch`]
-    /// is closed with `tris()` or `quads()`, and a batch that gained no vertices commits nothing.
+    /// Open a batch drawn through `cam` with `texture`; it commits when closed, if not empty.
     pub fn batch(&mut self, cam: Entity, texture: AssetId<Image>) -> EffectBatch<'_> {
         let start = self.quads.begin();
         EffectBatch {
@@ -662,8 +478,7 @@ impl<'w> WorldEffectDraw<'w> {
     }
 }
 
-/// One open batch. Field-free by construction: a caller holds it just long enough to push
-/// vertices and close it, so the type never has to be named.
+/// One open batch, pushed to and closed by its caller.
 pub struct EffectBatch<'a> {
     quads: &'a mut EffectQuads,
     start: u32,
@@ -671,21 +486,20 @@ pub struct EffectBatch<'a> {
 }
 
 impl EffectBatch<'_> {
-    /// Add this batch's colour to the framebuffer — glows, rings, beams.
+    /// Additive: glows, rings, beams.
     pub fn additive(mut self) -> Self {
         self.spec.blend = EffectBlend::Add;
         self
     }
 
-    /// Blend it over what is already drawn, `SRC_ALPHA / INV_SRC_ALPHA` — the lane's default,
-    /// spelled out for a producer whose blend is a *verified* state rather than an unremarked one
-    /// (the swing trail's EGxRs `0x07 = 2`, which reads like it ought to be additive and is not).
+    /// `SRC_ALPHA / INV_SRC_ALPHA`, the default, for a reference alpha state (the swing trail's
+    /// EGxRs `0x07 = 2`).
     pub fn alpha(mut self) -> Self {
         self.spec.blend = EffectBlend::Alpha;
         self
     }
 
-    /// Multiply it into what is already drawn — the blob shadow's darkening.
+    /// Multiply into what is drawn: the blob shadow.
     pub fn multiply(mut self) -> Self {
         self.spec.blend = EffectBlend::Multiply;
         self
@@ -697,30 +511,26 @@ impl EffectBatch<'_> {
         self
     }
 
-    /// An explicit fog policy; the default is [`EffectFog::Off`], which is what every decal and
-    /// overlay wants (they burn at their own colour).
+    /// An explicit fog policy; the default is [`EffectFog::Off`].
     pub fn fog(mut self, fog: EffectFog) -> Self {
         self.spec.fog = fog;
         self
     }
 
-    /// Where this batch sorts from — a world point, not a vertex. Transparents are ordered by the
-    /// distance to this.
+    /// The world point this batch sorts by.
     pub fn anchored(mut self, at: Vec3) -> Self {
         self.spec.anchor = at;
         self
     }
 
-    /// This batch's rung on the draw-order ladder: the transparent sort bias and the rasterizer
-    /// depth-bias constant (`crate::sky_order::Rung`). The slope-scale half stays 0 — only the
-    /// foam lane carries one, and it builds its spec directly.
+    /// The draw-order rung: sort bias and raster depth-bias constant (`crate::sky_order::Rung`).
     pub fn rung(mut self, sort: f32, raster: i32) -> Self {
         self.spec.bias = sort;
         self.spec.raster_bias = raster;
         self
     }
 
-    /// Draw over everything, occluded by nothing — see [`EffectDrawSpec::no_depth_test`].
+    /// Occluded by nothing; see [`EffectDrawSpec::no_depth_test`].
     pub fn over_everything(mut self) -> Self {
         self.spec.no_depth_test = true;
         self
@@ -732,7 +542,7 @@ impl EffectBatch<'_> {
         self
     }
 
-    /// Push vertices already built elsewhere — the decal lanes project once and cache.
+    /// Push vertices built elsewhere (the decal lanes project once and cache).
     pub fn vertices(&mut self, verts: &[EffectVertex]) {
         self.quads.verts.extend_from_slice(verts);
     }
@@ -742,8 +552,7 @@ impl EffectBatch<'_> {
         self.quads.verts.extend(verts);
     }
 
-    /// The vertex sink, for a producer that writes in place rather than yielding — the chain
-    /// beam builds each strand into it directly.
+    /// The vertex sink, for a producer that writes in place.
     pub fn verts_mut(&mut self) -> &mut Vec<EffectVertex> {
         &mut self.quads.verts
     }
diff --git a/crates/benilla-world/src/particles/depthdump.rs b/crates/benilla-world/src/particles/depthdump.rs
index bad17920..6b6f2a1a 100644
--- a/crates/benilla-world/src/particles/depthdump.rs
+++ b/crates/benilla-world/src/particles/depthdump.rs
@@ -1,22 +1,8 @@
-//! `$WOW_PARTICLE_DEPTHDUMP` — the CPU half of the particle **depth-contest** measurement (B16).
-//!
-//! Prints, for every live world-lane quad emitter, the numbers the depth compare is decided by:
-//! each particle's quad centre in the world, its rendered half-extent, its view-space z, the NDC
-//! depth its quad carries — with the four corners' own NDC depths, so "all corners share the
-//! centre's depth" (wow-re `part-flush-emitter-depth.md` §4, the mechanism that lets a flush
-//! emitter draw) is *measured* in our pipeline, not assumed — and where the quad lands in
-//! **physical pixels**.
-//!
-//! Pair it with `WOW_DEPTH` at pixels inside the printed rect (same physical-pixel space; MSAA
-//! off): that probe answers *what depth the opaque pass left in the buffer*; this one answers
-//! *what depth our quad brings to the compare*. Reverse-Z: the fragment survives iff
-//! `dquad ≥ d_buffer`. `buffer view-z − quad view-z` at the centre pixel is the emitter's burial
-//! as our pipeline actually experiences it — the number to put beside the reference's 0.0058-yd
-//! burial / 33–53 % quad survival, without a single screenshot.
-//!
-//! `WOW_PARTICLE_DEPTHDUMP=<at>[,<frames>]` — dump every frame from `at` seconds elapsed for
-//! `<frames>` frames (default 8). One line per particle, capped at 4 per emitter per frame (a
-//! flush glow's particles are near-coincident; the cap keeps a 50/s pool readable).
+//! `$WOW_PARTICLE_DEPTHDUMP=<at>[,<frames>]`: from `at` seconds, for `frames` frames (default 8),
+//! the depth each world-lane particle quad brings to the compare: centre, half-extent, view z,
+//! NDC depth and its corners' span (the reference gives all four the centre's, `0x7b2a50`), and
+//! its rect in physical pixels. Pair it with `WOW_DEPTH` inside that rect (MSAA off): reverse-Z,
+//! the fragment survives iff `dquad ≥ d_buffer`.
 
 use bevy::camera::Projection;
 use bevy::prelude::*;
@@ -36,11 +22,7 @@ static WINDOW: std::sync::LazyLock<Option<(f32, u32)>> = std::sync::LazyLock::ne
     Some((at.trim().parse().ok()?, n.trim().parse().unwrap_or(8)))
 });
 
-/// Parsed `$WOW_PARTICLE_DEPTHDUMP_BONES` — dump ONLY emitters mounted on these bones (empty = all).
-/// A live world scene has dozens of drawing emitters; unfiltered, the dump floods the log and costs
-/// the framerate of the very session it is measuring. Scoping to the subject's bones (the
-/// voidwalker's eyes are 60/61) makes the dump free when the subject is off screen, so the window
-/// can stay open for a whole director-driven session instead of a timed guess.
+/// Parsed `$WOW_PARTICLE_DEPTHDUMP_BONES`: dump only emitters on these bones (empty: all).
 static BONES: std::sync::LazyLock<Vec<u32>> = std::sync::LazyLock::new(|| {
     std::env::var("WOW_PARTICLE_DEPTHDUMP_BONES")
         .ok()
@@ -53,8 +35,7 @@ pub(super) fn bone_selected(bone: u32) -> bool {
     BONES.is_empty() || BONES.contains(&bone)
 }
 
-/// This frame's dump index if the window is open (advances the counter), else `None`. Called once
-/// per `simulate_particles` run.
+/// This frame's dump index while the window is open, advancing the counter; call once a frame.
 pub(super) fn frame(elapsed: f32, count: &mut u32) -> Option<u32> {
     let (at, frames) = (*WINDOW)?;
     (elapsed >= at && *count < frames).then(|| {
@@ -72,37 +53,25 @@ pub(super) fn dump_emitter(
     particles: &[Particle],
     dframe: &DrawFrame,
     placement: &Transform,
-    // The world point births are folded through THIS frame (the sim's own `emitter_world`, passed
-    // rather than recomputed so it cannot drift from the formula births actually use). Tracked
-    // across a dump window it measures our **eye-bone sway** — the number wow-re's rig puts at
-    // 0.128 units (11.7 cm) over the Stand cycle, and the discriminator for "do our births sample
-    // the current animated palette or a rest pose" (`part-anchoring-live-bone.md` §5.2).
+    // The sim's own birth point this frame, passed so it cannot drift from what births use.
     birth_world: Vec3,
     basis: &CamBasis,
     cam_tf: &GlobalTransform,
     camera: &Camera,
     projection: &Projection,
-    // The sim's own draw gate: a non-resident texture means the expansion was SKIPPED and none
-    // of these quads rasterized — numbers that look drawable but weren't. Stated on the line so
-    // the reader can't pair a withheld pool with a framebuffer.
+    // False when the sim skipped expansion for a non-resident texture: none of these quads drew.
     texture_resident: bool,
-    // The quads THIS frame just wrote into the shared stream (world-space vertices — the exact
-    // data the draw consumes; the dump now runs right after expansion). Empty = the pool is
-    // live but nothing was pushed (non-resident texture / geometry emitter).
+    // The world-space quads this frame just wrote; empty when a live pool pushed nothing.
     written: &[EffectVertex],
 ) {
     let Some(vp) = camera.physical_viewport_size() else {
         return;
     };
-    // The stream's OWN quads, exactly as expansion wrote them — read back from the vertex data
-    // rather than recomputed, so vertex-data corruption is visible as itself. An EMPTY slice is
-    // a real state (the "drawable numbers, nothing in the vertex buffer" state this dump exists
-    // to make visible).
+    // The stream's own vertices, read back rather than recomputed so a bad write shows as itself.
     if written.is_empty() {
         info!("PARTICLE_DEPTHDUMP f={fidx} stream EMPTY (0 verts — pool live, nothing pushed)");
     } else {
-        // Per-quad diagonal |v2−v0| over the WHOLE range — the young (big) quads live at the
-        // tail, and only reading quad 0 (the oldest, smallest) once mis-called a mesh "sane".
+        // Every quad's diagonal: the oldest, smallest quads lead and the young, big ones trail.
         let diag = |q: &[EffectVertex; 4]| (Vec3::from(q[2].pos) - Vec3::from(q[0].pos)).length();
         let quads: Vec<f32> = written.as_chunks::<4>().0.iter().map(diag).collect();
         let (mut dmin, mut dmax) = (f32::MAX, f32::MIN);
@@ -125,8 +94,7 @@ pub(super) fn dump_emitter(
     }
     let view_from_world = cam_tf.to_matrix().inverse();
     let clip_from_view = projection.get_clip_from_view();
-    // (ndc, view-z) of a world point; `None` behind the near plane. The same matrices the frame
-    // renders with, so `ndc.z` IS the depth the rasterizer interpolates for this vertex.
+    // (ndc, view z) of a world point through the frame's own matrices; `None` behind the eye.
     let project = |world: Vec3| -> Option<(Vec3, f32)> {
         let v = view_from_world * world.extend(1.0);
         let clip = clip_from_view * v;
@@ -156,9 +124,7 @@ pub(super) fn dump_emitter(
         placement.translation.y,
         placement.translation.z,
     );
-    // Sample the pool EVENLY by index (retain order = age order), not the first four: the pool's
-    // head is its oldest, near-contemporary particles, and a cap there hides both the young end
-    // (the big, bright quads) and the pool's spatial spread across its age span.
+    // Sampled evenly by index (pool order is age order), so the young end and the spread show.
     let stride = (particles.len() / 4).max(1);
     for (i, p) in particles
         .iter()
@@ -169,18 +135,14 @@ pub(super) fn dump_emitter(
     {
         let center = particle_center(dframe, placement, p);
         let half = particle_half(def, placement, p, dframe.size_scale);
-        // The additive contribution's other factor: the over-life colour this particle's quad
-        // carries (raw authored values, as `expand_quads` pushes them).
+        // The over-life colour the quad carries, raw as `expand_quads` pushes it.
         let rgba = def.over_life.sample((p.age / p.life).clamp(0.0, 1.0)).color;
         let Some((ndc, viewz)) = project(center) else {
             info!("PARTICLE_DEPTHDUMP f={fidx} p{i} behind the camera");
             continue;
         };
         let c_px = px(ndc);
-        // The quad exactly as `expand_quads` builds it (spin ignored — a spun square covers the
-        // same disc). Each corner's own NDC depth goes into `corners=[min,max]`: if that span is
-        // not ≈ dquad on both ends, our billboard is NOT the constant-depth plane the reference's
-        // mechanism depends on — that would itself be the finding.
+        // The quad as `expand_quads` builds it, spin ignored; `corners` is its NDC depth span.
         let (r, u) = (basis.right * half, basis.up * half);
         let (mut lo, mut hi) = (Vec2::splat(f32::MAX), Vec2::splat(f32::MIN));
         let (mut dmin, mut dmax) = (f32::MAX, f32::MIN);
diff --git a/crates/benilla-world/src/particles/dumps.rs b/crates/benilla-world/src/particles/dumps.rs
index 8a8ee7b3..3771e1e5 100644
--- a/crates/benilla-world/src/particles/dumps.rs
+++ b/crates/benilla-world/src/particles/dumps.rs
@@ -1,11 +1,6 @@
-//! The particle lane's debug-instrument system plumbing, bundled into one parameter.
-//!
-//! `simulate_particles` sits exactly at Bevy's 16-system-parameter ceiling, and the lane carries
-//! two optional instruments — [`super::depthdump`] (`$WOW_PARTICLE_DEPTHDUMP`, the depth numbers
-//! a pool brings to the compare) and [`super::emitdump`] (`$WOW_EMIT_DUMP`, what the emission
-//! front end decided) — each of which would otherwise spend a parameter or two of its own. That
-//! ceiling should never be the reason an instrument doesn't get built (0022), so the
-//! pair shares one: both stay inert without their env, and the sim reads them through here.
+//! The particle lane's two debug instruments, [`super::depthdump`] and [`super::emitdump`], as one
+//! system parameter: `simulate_particles` sits at Bevy's 16-parameter ceiling. Both are inert
+//! without their env.
 
 use bevy::ecs::system::SystemParam;
 use bevy::prelude::*;
diff --git a/crates/benilla-world/src/particles/emit.rs b/crates/benilla-world/src/particles/emit.rs
index f3525817..ba7d6605 100644
--- a/crates/benilla-world/src/particles/emit.rs
+++ b/crates/benilla-world/src/particles/emit.rs
@@ -1,12 +1,10 @@
-//! The **emission shape kernel** and its RNG — where one birth's position + velocity direction
-//! come from, byte-verified against the reference's three vtable type-spawn generators (wow-re
-//! `part-shape-kernels.md`). Split from the emitter module face (`particles.rs`) purely along
-//! this concern; the laws and cites live on [`emit_local`] itself.
+//! The emission shape kernel and its RNG: one birth's position and direction, as the reference's
+//! three spawn generators make them (`0x7b8890` plane, `0x7b8d70` sphere, `0x7b9500` spline).
 
 use benilla_formats::ParticleEmitterDef;
 use bevy::prelude::*;
 
-/// xorshift32 — a dependency-free PRNG for particle jitter (visual only; determinism not required).
+/// xorshift32 for particle jitter: visual only, determinism not required.
 pub(super) fn next_u32(state: &mut u32) -> u32 {
     let mut x = *state;
     x ^= x << 13;
@@ -21,54 +19,33 @@ pub(crate) fn rand01(state: &mut u32) -> f32 {
     (next_u32(state) >> 8) as f32 / (1u32 << 24) as f32
 }
 
-/// A symmetric random `f32` in `(−1, 1)` — the reference's `S11` draw (its RNG builds ±spans with
-/// a ×2.0 constant; every emission distribution below is plain uniform, wow-re
-/// `part-shape-kernels.md` §4 — we mirror the distributions, not the bit stream).
+/// Uniform in (−1, 1): the reference's `S11` draw (`0x7b88dd`), same distribution, not stream.
 pub(super) fn rand_s11(state: &mut u32) -> f32 {
     rand01(state) * 2.0 - 1.0
 }
 
-/// The **emission shape kernel** (wow-re `part-shape-kernels.md`, byte-verified off the three
-/// vtable type-spawn generators): one birth's position + unit velocity direction, in the emitter's
-/// local WoW frame (Z up, origin at the emitter record's `position`). The caller applies the speed
-/// roll and the space-mode transform.
-///
-/// - **Plane** (`0x7b8890`): position uniform in the ±½·area rectangle — **local x takes
-///   `areaLength`, local y takes `areaWidth`** (wow-re `part-shape-kernels.md` §4, VERIFIED:
-///   `p = (r2·A_x·0.5, r1·A_y·0.5, 0)` with `A_x = rt+0x290 = EmissionAreaLength`,
-///   `A_y = rt+0x294 = EmissionAreaWidth`). The pairing is only observable on an **anisotropic**
-///   rectangle, which is why it stayed wrong through 0563/0566 — every emitter checked until
-///   Gressil's blade smoke authored a square area. Direction: a cone around +Z with **symmetric**
-///   angles θ = S11·verticalRange, φ = S11·horizontalRange (the reference draws ±range, not
-///   [0, range] — a one-sided cone tilted every flame the same way).
-/// - **Sphere** (`0x7b8d70`): radius uniform in [areaLength, areaWidth] (= min/max radius for this
-///   shape), position on the shell at latitude S11·verticalRange / longitude S11·horizontalRange;
-///   direction radial outward (flag `0x4000` ⇒ straight +Z instead).
-/// - **Spline** (`0x7b9500`): born ON the authored arc-length-parameterized Bézier chain at a
-///   uniform arc fraction in `[tMin, tMax]`; velocity = +Z spun about the local tangent by
-///   ψ = S11·spin (zero velocity when no spin; radial-from-pivot when zSource authored), plus
-///   an optional along-velocity scatter jitter — see the arm's comment.
-/// - Any shape with `zSource ≠ 0`: direction is **radial from the pivot** `(0, 0, zSource)` toward
-///   the birth point (fountains that arc outward from a point below the basin).
+/// One birth's position and unit direction in the emitter's local WoW frame (Z up, origin at the
+/// record's `position`), before the caller's speed roll and space mode:
+/// - plane (`0x7b8890`): uniform in the ±½·area rectangle, x from `areaLength` (`rt+0x290`) and
+///   y from `areaWidth` (`rt+0x294`), in a cone about +Z at θ = S11·verticalRange and
+///   φ = S11·horizontalRange;
+/// - sphere (`0x7b8d70`): radius uniform in [areaLength, areaWidth], on the shell at those two
+///   angles as latitude and longitude, direction radial (`sphere_up`: +Z);
+/// - any shape with `zSource ≠ 0`: direction radial from the pivot `(0, 0, zSource)`.
 pub(super) fn emit_local(
     def: &ParticleEmitterDef,
     now: &benilla_formats::ParamsNow,
     rng: &mut u32,
 ) -> (Vec3, Vec3) {
     let origin = Vec3::from(def.position);
-    // The emitter-frame R(+Z, 90°) applied at every branch's return — see the law note at the
-    // tail. Per the wow-re bytes the prepend is per-EMITTER and subclass-independent ("gated
-    // only by has-emitters"), so the spline kernel takes it exactly like sphere/plane (the
-    // 0563 landing missed this branch — caught by the compensation audit).
+    // The emitter frame's R(+Z, 90°), applied at every return, spline included: the reference
+    // prepends it per emitter, whatever the shape (`0x71907f`).
     let rot90 = |v: Vec3| Vec3::new(-v.y, v.x, v.z);
-    // SPLINE (`0x7b9500`, wow-re `part-shape-kernels.md` §3 — VERIFIED, incl. the scatter
-    // bytes): born ON the authored Bézier chain at arc fraction `t ∈ [tMin, tMax]` (the
-    // repurposed area fields). Velocity: radial from the zSource pivot when authored; else +Z
-    // rotated about the local spline tangent by ψ = S11·spin (the reference extracts the
-    // transposed row — a −ψ rotation — indistinguishable under the symmetric draw), with an
-    // optional `U01·scatter` position jitter along the velocity; else ZERO (the particle sits
-    // on the curve and only gravity/drag move it). A degenerate record (no parsed chain)
-    // falls through to the plane kernel, as before.
+    // Spline (`0x7b9500`): born on the authored Bézier chain at arc fraction t in [tMin, tMax]
+    // (the area fields). Direction: radial from the zSource pivot when authored; else +Z turned
+    // about the tangent by S11·spin (`vertical_range`; the reference's −ψ is the same
+    // distribution) and jittered along it by U01·scatter (`horizontal_range`); else zero. No
+    // parsed chain falls through to the plane kernel.
     if let (benilla_formats::ParticleShape::Spline, Some(spline)) = (def.shape, &def.spline) {
         let (t0, t1) = (
             now.area_length.clamp(0.0, 1.0),
@@ -91,11 +68,8 @@ pub(super) fn emit_local(
         };
         return (origin + rot90(pos - origin), rot90(dir));
     }
-    // Birth offset in the emitter frame (before the record-position translation). A sphere
-    // draws ONE lat/lon unit vector serving both the shell point and (below) the radial
-    // velocity — the reference reuses the exact sincos pair (`0x7b8fba`), which is what keeps a
-    // ZERO-radius sphere (the fireball impact's plume burst: min = max = 0) spraying uniformly
-    // instead of collapsing every direction to the degenerate normalize fallback.
+    // A sphere's one lat/lon unit vector is both the shell point and the radial direction (the
+    // reference reuses the sincos pair, `0x7b8fba`), so a zero-radius sphere still sprays.
     let (local, shell) = if def.shape == benilla_formats::ParticleShape::Sphere {
         let r = now.area_length + rand01(rng) * (now.area_width - now.area_length).max(0.0);
         let lat = rand_s11(rng) * now.vertical_range;
@@ -105,9 +79,7 @@ pub(super) fn emit_local(
         let shell = Vec3::new(clat * clon, clat * slon, slat); // unit by construction
         (r * shell, Some(shell))
     } else {
-        // x ← areaLength (rt+0x290), y ← areaWidth (rt+0x294) — the VERIFIED pairing, see the
-        // Plane bullet above. Both draws are iid S11, so which one feeds which axis changes the
-        // rectangle's ORIENTATION but not its distribution; that is the whole bug.
+        // x from areaLength, y from areaWidth: swapped, an anisotropic rectangle turns 90°.
         (
             Vec3::new(
                 rand_s11(rng) * 0.5 * now.area_length,
@@ -118,13 +90,13 @@ pub(super) fn emit_local(
         )
     };
     let dir = if now.z_source != 0.0 {
-        // Radial from the (0, 0, zSource) pivot — degenerate at the pivot itself falls back to +Z.
+        // Radial from the (0, 0, zSource) pivot; +Z at the pivot itself.
         (local - Vec3::new(0.0, 0.0, now.z_source)).normalize_or(Vec3::Z)
     } else if let Some(shell) = shell {
         if def.sphere_up() {
             Vec3::Z
         } else {
-            shell // radial outward — the same unit draw as the birth point
+            shell // radial: the same unit draw as the birth point
         }
     } else {
         let theta = rand_s11(rng) * now.vertical_range;
@@ -133,15 +105,9 @@ pub(super) fn emit_local(
         let (sp, cp) = phi.sin_cos();
         Vec3::new(st * cp, st * sp, ct)
     };
-    // The emitter-frame R(+Z, 90°) — wow-re `part-modelspace-animbone.md`, §5 byte-verified
-    // (`0x719114–0x719142`: axis literal (0,0,1), angle π·0.5, Rodrigues + mat4_mul into the
-    // per-frame emitter matrix rt+0x1fc): the reference prepends a fixed +90°-about-local-+Z
-    // to EVERY M2 particle emitter's bone matrix, applied to the kernel-relative vectors only
-    // (the record-position translation stays outside it). It is what turns the sphere kernel's
-    // local-XZ ring into the wheel PERPENDICULAR to a rotor bone's +X spin — the InstancePortal
-    // vortex swirling in place instead of tumbling edge-on — and what maps a billboard-bone
-    // starburst's spray plane onto the screen plane (the impact flashes). Applied at emission,
-    // so every consumer (anchored bake, model-space storage, child emitters) inherits it.
+    // The reference prepends a fixed +90° about local +Z to every M2 particle emitter's matrix
+    // (`0x719114`..`0x719142`, into `rt+0x1fc`), on the kernel-relative vectors only, not the
+    // record position; applied here at emission, every consumer inherits it.
     (origin + rot90(local), rot90(dir))
 }
 
@@ -150,25 +116,16 @@ pub(crate) mod tests {
     use super::*;
     use benilla_formats::ParticleShape;
 
-    /// The kernel-test parameter set (the values the old flattened def carried).
     pub(crate) fn now() -> benilla_formats::ParamsNow {
         crate::testing::particle_params_now()
     }
 
-    /// A minimal def for kernel tests — only the fields [`emit_local`] reads matter; the
-    /// sampled-parameter side is [`now`] (constant-baked into `params` for the sim tests).
     pub(crate) fn def(shape: ParticleShape) -> ParticleEmitterDef {
         crate::testing::particle_def(shape)
     }
 
-    /// Plane births stay in the ±½·area rectangle around the record position, and the cone is
-    /// SYMMETRIC (θ = S11·range — wow-re `part-shape-kernels.md`'s correction of our old
-    /// [0, range) draw): with a wide sample, x-velocities must land on both signs. The
-    /// rectangle rides the R(+Z,90°) emitter frame (`emit_local`'s tail): the kernel's
-    /// length-along-x/width-along-y rectangle lands **width-along-x, length-along-y**. Asserted on
-    /// an ANISOTROPIC area (2 × 4) so the pairing is actually pinned — a square area passes either
-    /// way, which is exactly how the swapped pairing survived 0563/0566 (Gressil's 0.1 × 1.1 blade
-    /// smoke drew the 1.1 yd curtain ACROSS the blade).
+    /// The cone is symmetric (`0x7b8890`), and after the R(+Z, 90°) frame width lies along x and
+    /// length along y, pinned on an anisotropic 2 × 4 area (a square one passes either way).
     #[test]
     fn plane_kernel_rect_bounds_and_symmetric_cone() {
         let d = def(ParticleShape::Plane);
@@ -194,9 +151,7 @@ pub(crate) mod tests {
             pos |= dir.x > 1e-3;
         }
         assert!(neg && pos, "symmetric cone covers both x signs");
-        // The PIN, not just the bound: the LONG extent must land on x. A swapped
-        // areaLength/areaWidth pairing caps `max_dx` at ½·length = 1.0 and pushes `max_dy` past it,
-        // so this pair of asserts is what fails on the 0563-era kernel.
+        // The long extent must land on x: a swapped pairing caps `max_dx` at ½·length = 1.0.
         assert!(
             max_dx > 1.5,
             "the wide extent (½·width = 2.0) rides x post-R, reached {max_dx}"
@@ -207,8 +162,7 @@ pub(crate) mod tests {
         );
     }
 
-    /// Sphere births sit on a shell with radius in [areaLength, areaWidth] (min/max radius for
-    /// this shape) and fly radially outward through the shell point.
+    /// A sphere's `areaLength` and `areaWidth` are its min and max radius.
     #[test]
     fn sphere_kernel_radius_bounds_and_radial_velocity() {
         let d = def(ParticleShape::Sphere);
@@ -229,9 +183,7 @@ pub(crate) mod tests {
         }
     }
 
-    /// A ZERO-radius sphere (min = max = 0 — the fireball impact's plume burst) still sprays its
-    /// velocities across the authored lat/lon spread: the direction is the shell unit vector
-    /// itself (`0x7b8fba` reuses the sincos pair), never a normalize of the (zero) birth offset.
+    /// The direction is the shell unit vector (`0x7b8fba`), not the zero offset normalized.
     #[test]
     fn zero_radius_sphere_still_disperses() {
         let d = def(ParticleShape::Sphere);
@@ -261,10 +213,7 @@ pub(crate) mod tests {
         );
     }
 
-    /// The SPLINE kernel (`0x7b9500`): births sit ON the authored chain (origin-composed) at
-    /// arc fractions inside [tMin, tMax]; zero spin ⇒ ZERO velocity; a spin range fans +Z
-    /// about the local tangent (here +X ⇒ the fan stays in the YZ plane), and scatter jitters
-    /// the position along the velocity by at most its own length.
+    /// `0x7b9500`: no spin, no velocity; a spin range fans +Z about the tangent, scatter along it.
     #[test]
     fn spline_kernel_births_on_the_chain() {
         let x = |v: f32| [v, 0.0, 0.0];
@@ -281,7 +230,7 @@ pub(crate) mod tests {
         n.vertical_range = 0.0;
         n.z_source = 0.0;
         let mut rng = 31u32;
-        // The R(+Z,90°) emitter frame (`emit_local`'s tail) turns the authored +X chain to +Y.
+        // The R(+Z, 90°) frame turns the authored +X chain to +Y.
         for _ in 0..64 {
             let (p, dir) = emit_local(&d, &n, &mut rng);
             let local = p - Vec3::new(1.0, 2.0, 3.0); // minus the record position
@@ -293,7 +242,7 @@ pub(crate) mod tests {
             assert_eq!((local.x, local.z), (0.0, 0.0));
             assert_eq!(dir, Vec3::ZERO, "no spin, no zSource: the flame stands");
         }
-        // A spin range fans +Z about the +X tangent — the kernel's YZ fan lands in XZ post-R.
+        // A spin range fans +Z about the +X tangent; after R the fan lies in XZ.
         n.vertical_range = 1.0;
         n.horizontal_range = 0.5; // scatter
         let (mut low, mut high) = (false, false);
@@ -304,14 +253,12 @@ pub(crate) mod tests {
             assert!(dir.z > 0.0, "±1 rad about +Z stays upward");
             low |= dir.x > 0.5;
             high |= dir.x < -0.5;
-            // The scatter jitter is along dir, bounded by its own length.
             let local = p - Vec3::new(1.0, 2.0, 3.0);
             assert!(local.x.hypot(local.z) <= 0.5 + 1e-3, "jitter ≤ scatter");
         }
         assert!(low && high, "the fan covers both spin signs");
     }
 
-    /// zSource ≠ 0 redirects any shape's velocity radially away from the (0, 0, zSource) pivot.
     #[test]
     fn z_source_pivots_the_velocity() {
         let d = def(ParticleShape::Plane);
diff --git a/crates/benilla-world/src/particles/emitdump.rs b/crates/benilla-world/src/particles/emitdump.rs
index ea947798..f0291823 100644
--- a/crates/benilla-world/src/particles/emitdump.rs
+++ b/crates/benilla-world/src/particles/emitdump.rs
@@ -1,33 +1,17 @@
-//! `$WOW_EMIT_DUMP` — what the emission front end **decided**, per emitter, for one model.
-//!
-//! The particle lane already has an asset-side dump (`benilla-extract m2part` — every authored
-//! field of every record) and a draw-side one ([`super::depthdump`] — the depth numbers a pool
-//! brings to the compare). The gap between them is where "this effect looks wrong" reports
-//! actually live: *which* sequence slot the emitter resolved, what the ten per-frame tracks
-//! sampled at that slot, and how many particles that produced. A model whose rate track keys
-//! `0` in one sequence and `526/s` in another looks identical in the asset dump and in the draw
-//! dump — only the resolved slot says which of the two is on screen.
-//!
-//! `WOW_EMIT_DUMP=<label-substring>[,<period-seconds>]` — every `period` seconds (default 2),
-//! print one line per live emitter whose owning model's [`crate::interact::WorldObject`] label
-//! contains the substring, case-insensitively. That label is the model path for doodads, WMO
-//! props and GameObjects and the unit name for creatures — the same string the hover inspector
-//! shows, so the filter is copied straight off the panel that prompted the question.
-//!
-//! Scoping by label is what keeps it usable in a populated scene: a Molten Core frame ticks
-//! hundreds of emitters, and an unfiltered per-emitter dump both floods the log and costs the
-//! framerate of the run it is measuring.
+//! `$WOW_EMIT_DUMP=<label-substring>[,<period-seconds>]`: what the emission front end decided.
+//! Every period (default 2 s), one line per live emitter whose model's
+//! [`crate::interact::WorldObject`] label (a model path, or a creature's name) contains the
+//! substring, case-insensitively: the resolved sequence slot, the tracks sampled at it, the count.
 
 use bevy::ecs::system::SystemParam;
 use bevy::prelude::*;
 
 use benilla_formats::{ParamsNow, ParticleEmitterDef};
 
-/// Parsed `$WOW_EMIT_DUMP`: `(lowercased label substring, period seconds)`. `None` = off, and
-/// every entry point below then does nothing at all.
+/// Parsed `$WOW_EMIT_DUMP`: (lowercased label substring, period seconds); `None` is off.
 static FILTER: std::sync::LazyLock<Option<(String, f32)>> = std::sync::LazyLock::new(|| {
     let v = std::env::var("WOW_EMIT_DUMP").ok()?;
-    // Only a trailing NUMBER is a period — a model path may itself contain a comma.
+    // Only a trailing number is a period: a model path may contain a comma.
     let (label, period) = match v
         .rsplit_once(',')
         .map(|(l, p)| (l, p.trim().parse::<f32>()))
@@ -38,23 +22,17 @@ static FILTER: std::sync::LazyLock<Option<(String, f32)>> = std::sync::LazyLock:
     Some((label.trim().to_ascii_lowercase(), period.max(0.1)))
 });
 
-/// The instrument's own system plumbing: the label lookup it filters by and its period clock.
-/// One [`SystemParam`] rather than two loose arguments — `simulate_particles` sits at Bevy's
-/// 16-parameter ceiling, and a debug affordance has no business spending two of them.
+/// The label lookup the instrument filters by and its period clock, as one [`SystemParam`].
 #[derive(SystemParam)]
 pub(super) struct EmitDump<'w, 's> {
-    /// The owning model's inspector identity. It rides the **drawn parts**, not the entity the
-    /// emitter hosts on (the picker hovers a mesh, so that is where `attach::dress` puts it) —
-    /// hence the child walk in [`EmitDump::label`]. Looking only at the owner is what made this
-    /// instrument's first outing print 10822 unlabelled lines.
+    /// The model's inspector label, which rides its drawn parts, not the emitter's host entity.
     labels: Query<'w, 's, &'static crate::interact::WorldObject>,
     parts: Query<'w, 's, &'static Children>,
     last: Local<'s, f32>,
 }
 
 impl EmitDump<'_, '_> {
-    /// Is this frame a dump tick? Advances the period clock when it is. Always `false` without
-    /// the env, so the per-emitter call site costs one atomic load per frame.
+    /// Is this frame a dump tick (advancing the period clock)? Always false without the env.
     pub(super) fn due(&mut self, now: f32) -> bool {
         let Some((_, period)) = FILTER.as_ref() else {
             return false;
@@ -66,9 +44,7 @@ impl EmitDump<'_, '_> {
         true
     }
 
-    /// This emitter's model identity: the owner's own [`crate::interact::WorldObject`] if it has
-    /// one, else the first drawn part under it that does — a GameObject/unit carries its label on
-    /// the submesh entities, and the emitter hosts on the root above them.
+    /// The owner's own label, else the first labelled drawn part under it.
     fn label(&self, owner: Option<Entity>) -> &str {
         let Some(e) = owner else { return "" };
         if let Ok(o) = self.labels.get(e) {
@@ -120,10 +96,10 @@ impl EmitDump<'_, '_> {
     }
 }
 
-/// One emitter's decision this frame — the sim's live values, not the authored ones.
+/// One emitter's decision this frame: the sim's live values, not the authored ones.
 pub(super) struct Decision<'a> {
     pub(super) def: &'a ParticleEmitterDef,
-    /// The sequence FILE slot the rate/gate/params tracks resolved to (`None` = degraded to 0).
+    /// The sequence file slot the rate, gate and params tracks resolved to; `None` degrades to 0.
     pub(super) seq: Option<usize>,
     /// Seconds into that slot's baked loop.
     pub(super) elapsed: f32,
@@ -131,7 +107,6 @@ pub(super) struct Decision<'a> {
     pub(super) emitting: bool,
     pub(super) live: usize,
     pub(super) now: &'a ParamsNow,
-    /// The emitter origin's live world position — the number that says whether a model's
-    /// emitters are spread across it or collapsed onto one point.
+    /// The emitter origin's live world position.
     pub(super) at: Vec3,
 }
diff --git a/crates/benilla-world/src/particles/model.rs b/crates/benilla-world/src/particles/model.rs
index 162c9045..965ea5d4 100644
--- a/crates/benilla-world/src/particles/model.rs
+++ b/crates/benilla-world/src/particles/model.rs
@@ -1,20 +1,10 @@
-//! **3-D MODEL particles** (wow-re `part-model-particles.md`, VERIFIED): an emitter whose
-//! record names a geometry model renders each live particle as a tiny 3-D instance of that
-//! model — quaternion-oriented, tumbling, over-life scaled and tinted — instead of a billboard
-//! quad (Whirlwind's blades, Cone of Cold's shards, the cyclones, Death Wish). The sim
-//! integrates position + spin ([`super::sim`]); this module owns the DRAW side: a per-emitter
-//! pool of instance entities grown on demand, positioned after the sim each frame.
-//!
-//! Draw law (`0x7b4840` → `0x7b4510`): per particle, the instance transform is the particle
-//! quaternion (× the emitter frame) at the particle position, scaled by the over-life SIZE
-//! ramp; over-life COLOR rides a per-instance tint clone (`WowModelExt::tint`, the fx-tint
-//! mechanism) and over-life ALPHA rides the per-instance `MeshTag` alpha field. The
-//! reference's optional per-emitter depth sort (rt+0x1ac & 0x10) is folded into the pool-order
-//! simplification named in decision 0148. The reference draws each instance through its
-//! generic model-render pass; our instances are the geometry model's submeshes with their own
-//! materials — mini-model *animation* (a rigged geometry model) is not run: every spell-corpus
-//! geometry target probed is a static mesh, and a rigged one would surface as a visibly stiff
-//! instance, the recorded trigger to extend this.
+//! Model particles: an emitter whose record names a geometry model draws each particle as a small
+//! instance of it (Whirlwind's blades), placed after the sim each frame (`0x7b4840` →
+//! `0x7b4510`): its quaternion at its position, scaled by over-life size, colour in a per-instance
+//! tint, alpha in the `MeshTag`. Each blended instance sorts by its own depth in the transparent
+//! pass; the reference visits an emitter's particles back to front only under `rt+0x1ac & 0x10`,
+//! and the order its model pass draws them in is untraced. Rigged models are not animated: every
+//! spell geometry model probed is static.
 
 use benilla_assets::coords::wow_to_bevy;
 use benilla_assets::M2Model;
@@ -27,20 +17,17 @@ use benilla_assets::materials::WowModelMaterial;
 
 use super::{ChildDraw, ParticleEmitter};
 
-/// A hard cap on one emitter's instance pool — far above any authored steady state
-/// (rate ≤ ~25/s × life ≤ 3 s across the corpus); particles past it simply aren't drawn.
+/// Cap on one emitter's instances (the corpus stays under ~25/s × 3 s); the rest don't draw.
 const MAX_INSTANCES: usize = 128;
 
-/// One pooled instance slot: the geometry model's submeshes as world-root [`ChildDraw`]
-/// entities (flat — no hierarchy, so the sim-frame transform write is exact), each with its
-/// per-instance tint-clone material.
+/// One pooled instance: the model's submeshes as flat world-root [`ChildDraw`] entities, so the
+/// direct transform write is exact, each with its own tint material.
 pub(super) struct ModelInstance {
     pub(super) meshes: Vec<(Entity, Handle<WowModelMaterial>)>,
 }
 
-/// Grow + position each model-particle emitter's instance pool from its freshly-simulated
-/// pool. Runs after [`super::sim::simulate_particles`] in the same set, so instances land on
-/// this frame's positions (the anchored-exactness rule).
+/// Grow and place each model-particle emitter's instances; runs after
+/// [`super::sim::simulate_particles`], so they land on this frame's positions.
 pub(super) fn update_model_particles(
     mut commands: Commands,
     models: Res<Assets<M2Model>>,
@@ -70,23 +57,16 @@ pub(super) fn update_model_particles(
         let Some(geometry) = emitter.geometry.clone() else {
             continue;
         };
-        // A GATED emitter's pool is frozen and the sim already edge-hid its instances
-        // (decision 1480): running this body anyway re-showed them the same frame —
-        // `Visibility::Inherited` below undid the hide, so a frozen emitter's shards drew
-        // forever — and kept every instance's Transform/GlobalTransform/MeshTag/material a
-        // per-frame write. The sim clears `gated` before this system in the same chained set,
-        // so a thawed pool resumes the frame it wakes.
+        // Gated: the sim hid these instances, and `Visibility::Inherited` below would re-show
+        // them. The sim clears `gated` first, so a thawed pool resumes the frame it wakes.
         if emitter.gated {
             continue;
         }
         let Some(model) = models.get(&geometry) else {
-            continue; // still loading — particles simulate meanwhile, nothing draws yet
+            continue; // still loading: particles simulate meanwhile, nothing draws yet
         };
-        // The geometry model's render forms, built NOW rather than paced (decision 0834): a
-        // spell's visual must not lag its cast, and a particle-geometry model is a handful of
-        // tiny batches — the booth-lane exception, not the streaming rule.
+        // Built now, not paced: a spell's visual must not lag its cast, and these models are tiny.
         forms.ensure_now_static(&geometry, &model.submeshes, &mut mesh_assets);
-        // Grow the pool to the live count (bounded).
         let rung = emitter.owner_rung();
         let want = emitter.particles.len().min(MAX_INSTANCES);
         while emitter.model_instances.len() < want {
@@ -96,8 +76,7 @@ pub(super) fn update_model_particles(
                 .iter()
                 .enumerate()
                 .map(|(pi, sub)| {
-                    // A fresh (never-deduped) material per instance — its `tint` is mutated
-                    // every frame by the over-life ramp, so instances must not share.
+                    // A fresh material per instance: the over-life ramp writes its tint.
                     let mut throwaway = MaterialCache::default();
                     let material = model_material(
                         &mut throwaway,
@@ -114,11 +93,11 @@ pub(super) fn update_model_particles(
                         sub.no_depth_test,
                         sub.fog_policy,
                         sub.env_map, // texture_unit_lookup > 2 ⇒ the runtime generates this batch's UVs
-                        // The same LIT lane as every entity M2 (the §9 chain).
+                        // Lit like every entity M2 (`0x69e280`).
                         ShadeSel::Lit,
                         0,
                         None,
-                        None, // over-life tint owns the channel — never the authored M2Color loop
+                        None, // the over-life tint owns the colour, never the M2Color loop
                         None,
                         None,
                         false,
@@ -127,30 +106,11 @@ pub(super) fn update_model_particles(
                         &torch,
                         None, // a shard's material is shared by the whole emitter
                     );
-                    // Realized at once: the over-life ramp writes this material through
-                    // `get_mut` every frame, from the first (`model_render::lazy`).
+                    // Realized now: the over-life ramp writes it every frame.
                     crate::model_render::lazy::realize(&mut materials, material.id());
-                    // The owner-last draw-order rung, stamped on after the fact: a 3-D model
-                    // particle is one of its owner's emitters exactly like the quad cloud beside
-                    // it, and the reference draws them in one bracket after that model's batches
-                    // (`ParticleEmitter::owner_rung`). It goes here rather than through
-                    // `model_material`, which is the shared M2-batch recipe: every batch in the
-                    // world would have to carry a particle-only argument and a cache-key field to
-                    // move one number. These instance materials are per-instance throwaways
-                    // (their `tint` is already mutated every frame), so nothing else sees it.
-                    //
-                    // BUCKETED, and transparent-pass only (decision 0945). On a material the rung
-                    // is also a *pipeline-key axis* (bevy folds `depth_bias as i32` into the key
-                    // — 0837's law), and 32 integer rungs × every blend state is an open key
-                    // space no warm pass can pre-compile: each first-seen combination was a
-                    // synchronous render-thread pipeline compile mid-spell-cast.
-                    // `owner_last_rung_bucket` snaps UP (0721's blessed direction) to the closed
-                    // set `pipe_warm`'s menagerie compiles behind the loading cover; the bucket
-                    // is ≥ the exact rung, so a shard never sorts under its sibling quad cloud
-                    // (which keeps the exact value — its rung is queue-side, never a material).
-                    // Opaque/mask shard batches take no rung at all: sort bias is a
-                    // transparent-pass concept, and on an opaque material it would only mint an
-                    // unwarmable pipeline variant.
+                    // The owner-last rung (`ParticleEmitter::owner_rung`), bucketed up: bevy keys
+                    // pipelines on `depth_bias`, only buckets are pre-warmed, and a bucket never
+                    // sorts a shard under its quad cloud. Opaque batches take no sort bias.
                     if let Some(m) = materials.get_mut(&material) {
                         if m.base.alpha_mode == AlphaMode::Blend {
                             m.base.depth_bias = benilla_formats::owner_last_rung_bucket(rung);
@@ -177,7 +137,6 @@ pub(super) fn update_model_particles(
                 .collect();
             emitter.model_instances.push(ModelInstance { meshes });
         }
-        // Position live slots; hide the rest.
         let anchored = !emitter.def.model_space();
         let inst_scale = if emitter.def.scale_size_by_instance() {
             emitter.placement.scale.x.max(1e-4)
@@ -196,16 +155,14 @@ pub(super) fn update_model_particles(
                 continue;
             };
             let u = (p.age / p.life).clamp(0.0, 1.0);
-            // 3-D model particles carry no texture atlas — only colour and size reach them.
+            // No texture atlas here: only colour and size reach a model particle.
             let ol = emitter.def.over_life.sample(u);
             let (mut rgba, size) = (ol.color, ol.size);
-            // The owning model's render alpha, same fold as the quad lane (decision 0827) — here
-            // into the instance's `MeshTag` alpha, which is where a 3-D particle carries it.
+            // The owning model's render alpha, into the instance's `MeshTag` alpha.
             rgba[3] *= emitter.render_alpha();
             let tf = if anchored {
                 Transform {
-                    // World mode: the instance transform IS the stored one (decision 1585) —
-                    // through the ride frame, which is the identity off a transport (1591).
+                    // World mode: through the ride frame (identity off a transport).
                     translation: emitter.ride.to_world(p.pos),
                     rotation: emitter.ride.rotation() * p.quat,
                     scale: Vec3::splat(size * inst_scale),
diff --git a/crates/benilla-world/src/particles/quads.rs b/crates/benilla-world/src/particles/quads.rs
index 1b0ed91b..e9f915d3 100644
--- a/crates/benilla-world/src/particles/quads.rs
+++ b/crates/benilla-world/src/particles/quads.rs
@@ -1,8 +1,6 @@
-//! The particle **quad expansion** — one pool of live particles → the camera-facing (or
-//! XY-plane) billboard mesh, exactly the reference's quad writer laws (`0x7b2a50` head,
-//! `0x7b3041` tail, the twinkle LUT, the `0x7b2dda` spin negate). Shared verbatim by a parent
-//! emitter and its CHILD emitters (`part-child-recursion.md`), which differ only in whose pool
-//! and def feed it.
+//! Quad expansion: one pool of live particles into camera-facing (or XY-plane) quads, the
+//! reference's quad writer (`0x7b2a50` head, `0x7b3041` tail), shared by child emitters
+//! (`0x7b5dd0`).
 
 use benilla_assets::coords::wow_to_bevy;
 use benilla_formats::ParticleEmitterDef;
@@ -11,9 +9,8 @@ use bevy::prelude::*;
 use super::buffer::EffectVertex;
 use super::{rand01, Particle};
 
-/// The 128-entry twinkle noise table — the reference seeds `DAT_00cf58f0` with uniform-random f32
-/// in [0,1) at startup (wow-re `part-quad-tail-twinkle.md`, byte-verified incl. the fill loop; we
-/// mirror the distribution with a fixed seed, not the reference's stream).
+/// The 128-entry twinkle noise table, uniform in [0, 1) like the reference's `0xcf58f0` (filled at
+/// startup by `0x706790`); a fixed seed, so the distribution matches but not the stream.
 static TWINKLE_LUT: std::sync::LazyLock<[f32; 128]> = std::sync::LazyLock::new(|| {
     let mut s = 0xC0FF_EE11u32;
     let mut t = [0.0f32; 128];
@@ -23,24 +20,16 @@ static TWINKLE_LUT: std::sync::LazyLock<[f32; 128]> = std::sync::LazyLock::new(|
     t
 });
 
-/// The twinkle noise sample for a particle: the byte-verified index (`0x7b2a86`) is
-/// `(floor(clamp(twinkleSpeed · age, 0, 255)) + particlePhase) & 0x7f` — the reference's phase is
-/// a per-particle pointer hash; ours is a spawn-time random ([`Particle::phase`]). The phase
-/// de-syncs the flicker across particles (without it a whole flame pulses in lockstep).
+/// Index `(floor(clamp(twinkleSpeed · age, 0, 255)) + phase) & 0x7f` (`0x7b2a86`); the reference's
+/// phase is a pointer hash, ours a spawn-time random ([`Particle::phase`]).
 fn twinkle_noise(twinkle_speed: f32, age: f32, phase: u32) -> f32 {
     let idx = ((twinkle_speed * age).clamp(0.0, 255.0) as u32).wrapping_add(phase) as usize & 0x7f;
     TWINKLE_LUT[idx]
 }
 
-/// The quad-spin angle (byte-verified: the negate at `0x7b2dda`, immediately before the fsincos
-/// fold, shared by the plain-rotated and Rodrigues legs): `spin·age`, **negated when the raw angle
-/// is negative on a particle whose pool-slot pointer carries bit 5** — the 0x20-byte `CParticle2`
-/// slots alternate that bit, so this is vanilla's entire rotation randomizer: a NEGATIVE-spin
-/// emitter counter-rotates half its cloud (the Fire Blast impact smoke reads as churning volume),
-/// a positive-spin one rotates uniformly. Same-age burst particles rotating in lockstep otherwise
-/// turn the whole cloud as one rigid picture — the director's "2D smoke". The reference's half-
-/// split is a pointer hash; ours is the same spawn-time [`Particle::phase`] the twinkle index uses
-/// (stable per particle, which a pool INDEX under `retain_mut` compaction would not be).
+/// `spin·age`, negated when negative on a particle whose 0x20-byte pool slot has address bit 5 set
+/// (`0x7b2dda`), so a negative-spin emitter counter-rotates half its cloud. Our bit 5 is
+/// [`Particle::phase`]'s, stable per particle where a pool index would not be.
 pub(super) fn spin_angle(spin: f32, age: f32, phase: u32) -> f32 {
     let angle = spin * age;
     if angle < 0.0 && phase & 0x20 != 0 {
@@ -50,63 +39,44 @@ pub(super) fn spin_angle(spin: f32, age: f32, phase: u32) -> f32 {
     }
 }
 
-/// The camera basis one frame of expansion billboards against. (No facing normal: the effect
-/// shader is unlit and never backface-culled, and the lane's vertex stream carries none — the
-/// old per-vertex `cam.face_normal` existed only to satisfy the mesh pipeline's layout.)
+/// The camera basis one frame of expansion billboards against.
 pub(super) struct CamBasis {
     pub(crate) right: Vec3,
     pub(crate) up: Vec3,
 }
 
-/// The cloud's draw frame: where its vertices are relative to ([`anchor`]) and how stored
-/// coordinates reach the world (the anchored/model split of [`super::Particle`]'s doc).
+/// How a cloud's stored coordinates reach the world (the two modes on [`super::Particle`]).
 pub(super) struct DrawFrame {
     pub(crate) anchored: bool,
-    /// The WORLD-mode store's **ride frame** `A` ([`crate::ride_frame`], decision 1591) — the
-    /// reference's `[ebp+8]` at `0x7b3d20`, folded forward on the `0x7b3f4f` leg. `None` off a
-    /// transport, which is every cloud on the ground, and then every fold below is the identity.
-    /// Model mode never reads it: `0x7b3efb` leaves `[ebp+8]` untouched.
+    /// World mode's ride frame `A`, the reference's `[ebp+8]` at `0x7b3d20`, folded on the
+    /// `0x7b3f4f` leg; the identity off a transport. Model mode never reads it (`0x7b3efb`).
     pub(crate) ride: crate::ride_frame::StoredFrame,
-    /// The owning MODEL's render alpha, folded into every particle's alpha channel — the
-    /// reference's `emitter+0x1a8` (decision 0827). 1.0 for a model that isn't fading.
+    /// The owning model's render alpha, folded into every particle's alpha (`emitter+0x1a8`).
     pub(crate) alpha: f32,
-    /// The lane's **size unit** — what one model unit of a particle's half-extent is in this
-    /// cloud's stored frame. `1.0` everywhere in the world (a yard is a yard). A UI model tile
-    /// (decision 2008) stores its particles in device pixels, and the reference maps a
-    /// widget's particle half-extent through the screen — `768·√(a²+1)` FrameXML units per
-    /// unit, the instance scale NOT included (wow-re `modelframe-clip-and-scale.md` §6) — so
-    /// the tile sets this to that many pixels per unit; an emitter flagged to scale with its
-    /// instance already reads the instance through `placement.scale` and takes 1.0 here.
+    /// One model unit of half-extent in the stored frame: 1.0 in the world, a UI tile's pixels per
+    /// unit (the reference's `768·√(a²+1)` FrameXML units, instance scale excluded, `0x7b2ba6`).
     pub(crate) size_scale: f32,
 }
 
-/// One particle's world-space quad centre — THE point [`expand_quads`] rasterizes around, factored
-/// out so the `WOW_PARTICLE_DEPTHDUMP` instrument reports the same value the GPU gets, not a
-/// re-derivation that can drift.
+/// One particle's world-space quad centre, shared by [`expand_quads`] and the depth dump.
 pub(super) fn particle_center(frame: &DrawFrame, placement: &Transform, p: &Particle) -> Vec3 {
     if frame.anchored {
-        // WORLD mode (`0x10` CLEAR): the store is absolute in its OWN frame and the draw never
-        // folds `rt+0x1fc` back — the reference's `0x7b3f48` (decision 1585, wow-re §2c-B). The
-        // one matrix that does fold is the ride frame, on the `0x7b3f4f` leg: `A · T · S`. Off a
-        // transport `A` is NULL and the store is world, which is the `0x7b3f95` leg.
+        // World mode (`0x10` clear): no `rt+0x1fc` fold (`0x7b3f48`), only the ride frame,
+        // `A · T · S` (`0x7b3f4f`); off a transport `A` is null, the store world (`0x7b3f95`).
         frame.ride.to_world(p.pos)
     } else {
-        // MODEL mode (`0x10` SET): the live emitter matrix, re-applied every frame — `0x7b3efb`.
+        // Model mode (`0x10` set): the live emitter matrix, re-applied every frame (`0x7b3efb`).
         placement.transform_point(wow_to_bevy([p.pos.x, p.pos.y, p.pos.z]))
     }
 }
 
-/// The twinklePercent draw-gate — mirrors [`expand_quads`]'s `0x7b2adc` skip, exported so the
-/// depth dump reports only particles that actually emit a quad. **If that condition changes,
-/// change this.**
+/// The twinklePercent draw gate; must match [`expand_quads`]'s `0x7b2adc` skip.
 pub(super) fn draw_gated(def: &ParticleEmitterDef, p: &Particle) -> bool {
     let noise = twinkle_noise(def.twinkle_speed, p.age, p.phase);
     def.twinkle_percent < 1.0 && noise > def.twinkle_percent
 }
 
-/// One particle's rendered half-extent — mirrors the `half` term inside [`expand_quads`] (over-life
-/// size × gated twinkle × instance scale), which computes it inline because it needs the noise and
-/// over-life samples for other attributes too. **If that expression changes, change this.**
+/// One particle's rendered half-extent; must match the `half` term in [`expand_quads`].
 pub(super) fn particle_half(
     def: &ParticleEmitterDef,
     placement: &Transform,
@@ -123,9 +93,8 @@ pub(super) fn particle_half(
     def.over_life.sample(u_age).size * def.twinkle(noise) * scale
 }
 
-/// Expand one pool into the shared effect-quad stream (whole quads, corner order closed by the
-/// lane's static `[0,1,2, 0,2,3]` index pattern). Vertices are **world-space** — the draw
-/// record carries the sort anchor now (see [`super::buffer`]).
+/// Expand one pool into the shared stream: world-space quads, corners in perimeter order for the
+/// lane's `[0,1,2, 0,2,3]` indices.
 pub(super) fn expand_quads(
     def: &ParticleEmitterDef,
     particles: &[Particle],
@@ -136,26 +105,15 @@ pub(super) fn expand_quads(
 ) {
     let anchored = frame.anchored;
     let (cam_right, cam_up) = (cam.right, cam.up);
-    // Size scales with the instance transform only when the emitter flags it (0x200) — an
-    // instance-scaled prop otherwise scales its particle *positions* only (wow-re B2). The
-    // unflagged size is in the lane's size unit ([`DrawFrame::size_scale`] — a yard, or a UI
-    // tile's pixels per model unit).
+    // Size takes the instance scale only when flagged (`0x7b2a50`), else the lane's size unit.
     let scale = if def.scale_size_by_instance() {
         placement.scale.x.max(1e-4)
     } else {
         frame.size_scale
     };
-    // The XY-quad head basis (file flag 0x1000, wow-re `part-tiled-corner-builder.md`,
-    // VERIFIED): the quad lies flat in the emitter's model-space XY plane carried by the
-    // LIVE model→world matrix — camera-independent (the impact crescents, state rings,
-    // fish-school splashes). Corners inherit the matrix's scale (the reference's `S·M`;
-    // separate from — and stacking with — the flag-0x200 size multiply above), and the
-    // live placement orients the plane in BOTH sim modes: the reference folds the emitter
-    // orientation into the corner matrix even when birth-baking positions (anchored mode).
-    // The corner square rides the same R(+Z,90°)-prepended emitter matrix as the particles
-    // (wow-re `part-modelspace-animbone.md`; we fold R at emission — `emit_local` — so here the
-    // basis vectors carry it explicitly): X̂ → R·X̂ = Ŷ, Ŷ → R·Ŷ = −X̂ — an in-plane quarter
-    // turn of every flat quad (invisible on round textures, load-bearing on crescents).
+    // XY quads (file flag 0x1000, `0x7b41a3`) lie flat in the emitter's XY plane under the live
+    // model matrix, its scale included, in both modes. The basis carries the emitter frame's
+    // R(+Z, 90°) (`0x719114`) itself, since births take it at emission: X̂ to Ŷ, Ŷ to −X̂.
     let plane_basis = def.xy_quad().then(|| {
         let s = placement.scale.x.max(1e-4);
         (
@@ -163,14 +121,9 @@ pub(super) fn expand_quads(
             placement.rotation * (wow_to_bevy([-1.0, 0.0, 0.0]) * s),
         )
     });
-    // Atlas walk (byte-verified `0x7b2a50` @0x7b2bd5 head / @0x7b304e tail, wow-re
-    // `part-cell-flipbook-ramp.md` §4): `col = idx & (COLUMNS−1)`, `row = idx >> log2(COLUMNS)`.
-    // COLUMNS is a power of two by construction — the reference validates it at load and falls
-    // back to a 1×1 grid otherwise, which the parse mirrors. **The column WRAPS and the row does
-    // NOT**: there is no clamp into the atlas anywhere on the reference's path, so an index past
-    // the last cell yields `V ≥ 1.0` and is handed to the sampler's (repeat) addressing — landing
-    // back on row 0, not on the final cell. 553 emitters author exactly that, at the tail of a
-    // flame's flipbook (decision 0685); a `min(rows·cols − 1)` here held the last cell instead.
+    // Atlas cell (`0x7b2bd5` head, `0x7b304e` tail): `col = idx & (cols − 1)`, `row = idx >>
+    // log2(cols)`, cols a power of two. The row is never clamped: past the last cell V ≥ 1 and
+    // the repeat sampler wraps to row 0, which 553 emitters reach at a flipbook's tail.
     let (cols, rows) = (def.tile_cols, def.tile_rows);
     let (inv_cols, inv_rows) = (1.0 / cols as f32, 1.0 / rows as f32);
     let cell_uv = |idx: u16| {
@@ -183,41 +136,24 @@ pub(super) fn expand_quads(
     };
     for p in particles {
         let noise = twinkle_noise(def.twinkle_speed, p.age, p.phase);
-        // The twinklePercent draw-gate (byte-verified `0x7b2adc`): while percent < 1 (never on
-        // placed content, which authors 1.0), a frame whose LUT sample exceeds it emits no
-        // quad at all — the reference's hard scintillation.
+        // The twinklePercent gate (`0x7b2adc`): below 1, a sample above it draws no quad.
         if def.twinkle_percent < 1.0 && noise > def.twinkle_percent {
             continue;
         }
         let u_age = (p.age / p.life).clamp(0.0, 1.0);
         let ol = def.over_life.sample(u_age);
         let (mut rgba, size) = (ol.color, ol.size);
-        // The MODEL's render alpha, folded into the ALPHA channel only — exactly where and how the
-        // reference does it: the sampler `0x7b9b10` takes it as its second argument and applies it
-        // at `0x7b9b42 fmul` to the alpha byte alone, RGB untouched (decision 0827). So a unit
-        // fading in fades its effects in with it, and a first-person avatar's torch stops burning
-        // in your face.
+        // The model's render alpha scales alpha alone, never RGB (`0x7b9b10`, the `0x7b9b42` fmul).
         rgba[3] *= frame.alpha;
-        // RAW authored RGB — the gamma-space decode happens ONCE, at the FFX combine
-        // (decision 0161's gamma lane; 0152/0150 are its shader-placement ancestry). Alpha is
-        // a blend weight — raw everywhere. Additive stacks sum in gamma like the reference's
-        // bytes; the byte buffer's SATURATION (a stack can never exceed 255) is restored at
-        // the FFX chain's scene reads (`ffx_glow.wgsl`, the Frost Nova mist diagnosis) — a
-        // too-bright additive stack is never this ramp's bug, do not "fix" it here.
-        // World-mode positions are already world and are drawn raw; model mode folds the whole
-        // live placement transform (the reference's rt-0x100 render fold, `0x7b3d20`).
+        // Raw authored gamma RGB: additive stacks sum in gamma like the reference's bytes, and
+        // the FFX chain's scene reads apply their 255 saturation (`ffx_glow.wgsl`), not this.
         let center = particle_center(frame, placement, p);
-        // `size` is the half-extent: the reference quad corners are ±1.0 (verified in wow-5875-re,
-        // `quad_expand`), so a vertex sits at `center ± size` and the world quad edge spans 2·size.
-        // Rendered half-size (wow-re B2, byte-verified `0x7b2a50`): the over-life ramp is the
-        // base, × the GATED twinkle flicker (skipped when min == max — `{0,0}` and `{1,1}`
-        // alike burn steady; the old base+rand reading collapsed the kobold candle to zero),
-        // × the instance scale iff flagged.
+        // `size` is the half-extent (corners ±1.0, `0x7b2d0c`), times the gated twinkle and the
+        // flagged instance scale; a twinkle range with min == max burns steady.
         let half = size * def.twinkle(noise) * scale;
-        // Within one cloud, quad order stays pool order — the reference's global per-particle
-        // painter sort is a named deliberate simplification. Between clouds, the draw record's
-        // anchor gives each its real sorted depth (the old anchor-relative vertex encoding's
-        // job — two overlapping smoke plumes must never sort-tie and swap per frame).
+        // Deviation: quads keep pool order within a cloud, without the reference's back-to-front
+        // sort (`0x7b3a10`), because only an alpha-blended cloud can show the order; between
+        // clouds, each draw record's anchor sorts it.
         let mut push_quad = |corners: [Vec3; 4], quv: [[f32; 2]; 4]| {
             for (c, t) in corners.iter().zip(quv) {
                 out.push(EffectVertex {
@@ -227,15 +163,12 @@ pub(super) fn expand_quads(
                 });
             }
         };
-        // HEAD quad (particleType 0/2), drawn first (`0x7b2bc9`): a camera-facing billboard,
-        // or — XY-quad emitters — the flat plane basis computed above.
+        // Head quad (particleType 0 or 2), drawn first (`0x7b2bc9`): a billboard, or the XY plane.
         if def.head_tail != 1 {
             let ((u0, u1), (v0, v1)) = cell_uv(ol.head_cell);
             let (base_r, base_u) = plane_basis.unwrap_or((cam_right, cam_up));
-            // Quad spin (file +0x198): rotate in-plane by `angle = spin·age` (the fcos/fsin
-            // fold at `0x7b2ddc`; on an XY quad the same form IS the reference's Rodrigues
-            // about the quad-plane normal, since `normal × base_r = base_u`). 0 for nearly
-            // every prop. A NEGATIVE spin counter-rotates half the cloud ([`spin_angle`]).
+            // Spin (file +0x198): in-plane by [`spin_angle`] (`0x7b2ddc`); on an XY quad this
+            // is the reference's Rodrigues about the plane normal, as `normal × base_r = base_u`.
             let (r, u) = if def.spin != 0.0 {
                 let (sa, ca) = spin_angle(def.spin, p.age, p.phase).sin_cos();
                 (
@@ -255,24 +188,12 @@ pub(super) fn expand_quads(
                 [[u0, v1], [u1, v1], [u1, v0], [u0, v0]],
             );
         }
-        // TAIL quad (particleType 1/2, byte-verified `0x7b3041`): a velocity-projected streak
-        // trailing the motion — world length |velocity|·tailTime (flag 0x400 grows it from
-        // zero with age), width 2·half perpendicular IN SCREEN SPACE, U running along the
-        // tail (0 at the particle → 1 at the tip). A view-parallel velocity (degenerate screen
-        // length) falls back to a plain billboard.
-        //
-        // The streak reads its **own** flipbook cell — a second, independently authored ramp
-        // (file+0x174..+0x17b), not the head's. The reference emits two cell indices per particle
-        // and the tail block reads the second (`[ebp-0x40]` @0x7b3054). 14 shipped emitters on a
-        // real atlas — Fire Bolt / Flamestrike / Banish / Hellfire / Vanish impacts, the elemental
-        // totems — author a head ramp that walks all 64 cells and a tail ramp pinned at cell 0;
-        // handing the head's cell to the streak animated it through the whole sheet (decision
-        // 0685, correcting wow-re's own `part-quad-tail-twinkle.md` §2).
+        // Tail quad (particleType 1 or 2, `0x7b3041`): |velocity|·tailTime back along the motion,
+        // 2·half wide in screen space, U from 0 at the particle to 1 at the tip, a billboard when
+        // the velocity is view-parallel; its own flipbook cell (file +0x174..+0x17b, `0x7b3054`).
         if def.head_tail >= 1 {
             let ((u0, u1), (v0, v1)) = cell_uv(ol.tail_cell);
             let vel_world = if anchored {
-                // The tail streak points back along the world velocity, so the stored direction
-                // takes the ride frame's rotation (never its translation — this is a vector).
                 frame.ride.dir_to_world(p.vel)
             } else {
                 placement.rotation * (placement.scale * wow_to_bevy(p.vel.to_array()))
@@ -319,8 +240,7 @@ mod tests {
     use super::{expand_quads, spin_angle, CamBasis, DrawFrame, Particle};
     use bevy::prelude::{Quat, Transform, Vec3};
 
-    /// The `0x7b2dda` negate: only a NEGATIVE angle on a bit-5 particle flips — a negative-spin
-    /// emitter counter-rotates exactly its bit-5 half, a positive-spin one never splits.
+    /// The `0x7b2dda` negate: only a negative angle on a bit-5 particle flips.
     #[test]
     fn negative_spin_counter_rotates_the_bit5_half() {
         assert_eq!(spin_angle(-3.0, 0.5, 0x20), 1.5, "bit 5 set: negated");
@@ -334,13 +254,8 @@ mod tests {
         assert_eq!(spin_angle(0.0, 0.5, 0xff), 0.0);
     }
 
-    /// **The model's render alpha reaches its particles, and ONLY their alpha** (decision 0827).
-    /// The reference folds `emitter+0x1a8` (a per-frame copy of the model's `CM2Model+0x19c`)
-    /// inside the over-life sampler `0x7b9b10`, at `0x7b9b42 fmul` — which writes the **alpha byte
-    /// alone** (`mov [eax+3],cl`); R/G/B never see it (`part-additive-combine.md` §6.1, the
-    /// refutation of `part-scene-multipliers.md` §4's old negative). A fold into RGB would look
-    /// almost right on an additive quad and be wrong on every alpha-blended one, so the channel
-    /// split is what this pins.
+    /// The reference folds `emitter+0x1a8`, the model's `CM2Model+0x19c`, into the alpha byte alone
+    /// (`0x7b9b10`, the `0x7b9b42` fmul).
     #[test]
     fn the_models_render_alpha_scales_particle_alpha_and_nothing_else() {
         let mut def = crate::particles::tests::plain_def();
diff --git a/crates/benilla-world/src/particles/render.rs b/crates/benilla-world/src/particles/render.rs
index aa602b98..dd1f42c3 100644
--- a/crates/benilla-world/src/particles/render.rs
+++ b/crates/benilla-world/src/particles/render.rs
@@ -1,34 +1,9 @@
-//! The **effect lane** — the render-world half of the shared effect stream (decisions 0732
-//! P1/P2, 0733): one vertex buffer + one per-frame index stream for every dynamic-effect
-//! family, drawn as directly-constructed [`Transparent3d`] items.
-//!
-//! The shape is bevy_ui_render's (`draw_indexed(range, 0, 0..1)` over a shared `RawBufferVec`,
-//! and its sorted-items batching walk), moved to the 3-D transparent phase:
-//!
-//! - **extract** copies the frame's CPU stream;
-//! - **queue** adds one item per draw record with **sort distance = view-space z of the draw
-//!   anchor + the ladder rung** — exactly the metric the material path produced
-//!   (`rangefinder.distance(center) + depth_bias`, bevy_pbr `material.rs:1307`), so ordering
-//!   against M2 blend batches, model-particle instances and the sky ladder is unchanged by
-//!   construction;
-//! - **prepare** (after `PhaseSort`) rebases each draw's vertices against its target view's
-//!   camera position (0733 §2 — the `ViewUniform.world_position` source value, so the shader's
-//!   reconstruction is exact; decal draws are exempt and stay absolute for the
-//!   `DECAL_WORLD_CLIP` mesh-matrix transform, 0781), uploads them, then walks the sorted
-//!   items building the frame's
-//!   index stream in draw order and **merging sort-adjacent items that share (pipeline,
-//!   texture, light, fog)** into one draw call. The merge rides bevy's own sorted-phase
-//!   contract: the phase renderer advances by `batch_range.len()` (`render_phase/mod.rs:1487`),
-//!   so a batch-opening item whose range spans its followers absorbs them — bevy_ui_render's
-//!   exact mechanism. Bevy's mesh batcher leaves items whose main entity owns no registered
-//!   mesh untouched (0732 audit III), so nothing else rewrites the ranges.
-//!
-//! Pipeline variants (0733 §4): Add = premultiplied-alpha + the shader's gamma `rgb·a` fold,
-//! Alpha = standard, Opaque = no blend with depth-write ON (in the transparent bracket at the
-//! owner rung — the 0719 reference law), Multiply = bevy's `AlphaMode::Multiply` state (the
-//! blob shadow's modulate; `ModelBlend::Mod` at α=1), Mod2x = 0528's `(Dst, Src)`. The decal
-//! family's rasterizer depth bias rides [`EffectPipelineKey::raster_bias`] — the half of the
-//! old material `depth_bias` that settles the coplanar depth tie against the drawn ground.
+//! The effect lane: the render-world half of the shared effect stream, drawn as [`Transparent3d`]
+//! items in bevy_ui_render's shape. Queue sorts each draw at its anchor's view z plus its rung,
+//! the material path's metric; prepare, after `PhaseSort`, rebases and uploads the vertices and
+//! merges sort-adjacent items sharing a `RunKey`: the phase renderer advances by
+//! `batch_range.len()`, so an opener spanning its followers absorbs them. Bevy's mesh batcher
+//! leaves the items alone while their main entities own no mesh.
 
 use std::ops::Range;
 
@@ -78,42 +53,29 @@ struct ExtractedDraw {
     blend: EffectBlend,
     topology: EffectTopology,
     fog: EffectFog,
-    /// The scene-light gate — a pipeline-key axis, so the merge walk's `RunKey` separates lit
-    /// from unlit runs through the pipeline id alone.
     lit: bool,
     anchor: Vec3,
     bias: f32,
     raster_bias: i32,
-    /// The slope-scale half of the settle — see [`super::buffer::EffectDrawSpec::raster_slope`].
     raster_slope: f32,
-    /// Vertices are already camera-relative — the prepare rebase skips this draw. See
-    /// [`super::buffer::EffectDrawSpec::cam_relative`].
     cam_relative: bool,
-    /// This draw ignores the depth buffer. See [`super::buffer::EffectDrawSpec::no_depth_test`].
     no_depth_test: bool,
-    /// Vertex range in the shared stream.
     range: Range<u32>,
-    /// A booth's scene-light override (0539 §5); `None` = the world's shared light buffer.
+    /// A booth's light buffer; `None` is the world's.
     light: Option<Buffer>,
-    /// The target-pixel clip rect — see [`super::buffer::EffectDrawSpec::clip`].
     clip: Option<Vec4>,
 }
 
-/// One GPU draw call after the merge walk: a contiguous index range plus the bind-group
-/// identity every item folded into it shares.
+/// One GPU draw after the merge walk: an index range and the bind-group identity its items share.
 struct MergedDraw {
     index_range: Range<u32>,
     texture: AssetId<Image>,
     light: Option<Buffer>,
-    /// The dynamic offset of this draw's row in [`EffectMeta::params`] — its fog policy and its
-    /// clip rect together, resolved by [`EffectMeta::build_params`].
+    /// This draw's fog and clip row in [`EffectMeta::params`].
     params_offset: u32,
 }
 
-/// The lane's per-frame GPU state: the shared vertex stream (rebased camera-relative in
-/// prepare), the frame's index stream (built in sorted-item order by the merge walk), the
-/// draw and merged-draw records, and the canonical fog-params uniform (one `vec4` per
-/// [`EffectFog`] policy, written once).
+/// The lane's per-frame GPU state: vertices, indices, draws, merged draws and params rows.
 #[derive(Resource)]
 pub struct EffectMeta {
     vertices: RawBufferVec<EffectVertex>,
@@ -124,14 +86,11 @@ pub struct EffectMeta {
     params: DynamicUniformBuffer<EffectParams>,
     /// The six canonical fog rows' dynamic offsets, in [`EffectFog::slot`] order.
     params_offsets: [u32; 6],
-    /// The params buffer as it was last written — the bind-group cache holds a binding into it,
-    /// so a re-created buffer has to invalidate that cache ([`prepare_effect_bind_groups`]).
+    /// The params buffer last written; a new one invalidates the bind-group cache.
     params_buffer: Option<BufferId>,
 }
 
-/// One row of the lane's per-draw uniform: the fog policy the shader reads, and the target-pixel
-/// rectangle it clips to. `clip.z <= clip.x` means **no clip**, which is every world draw and
-/// every canonical fog row.
+/// One per-draw uniform row: the fog policy and the target-pixel clip (`clip.z <= clip.x`: none).
 #[derive(Clone, Copy, bevy::render::render_resource::ShaderType)]
 struct EffectParams {
     fog: Vec4,
@@ -153,19 +112,13 @@ impl Default for EffectMeta {
     }
 }
 
-/// How many CLIPPED params rows one frame may carry. A clip is a UI model tile's cell, and a
-/// pane whose row does not fit degrades to the unclipped row — so this only has to cover the
-/// panes that can actually spill, which is the ones with emitters (the autocast shines, the two
-/// pings, the bag's item animation): a whole pet bar plus both pings is ten.
+/// Clipped params rows per frame; a pane past it draws unclipped (a pet bar and two pings is ten).
 const MAX_CLIP_ROWS: usize = 64;
 
 impl EffectMeta {
-    /// Write this frame's per-draw uniform rows and return the clipped ones' offsets, keyed by
-    /// `(fog slot, the clip rect's bits)`. The six canonical fog rows are always rows 0..6, in
-    /// [`EffectFog::slot`] order — `params.fog.x` carries the shader's fog COLOUR policy (the
-    /// `0x70baf0` table), `params.fog.y` the forced-fog enable with `zw` its start/end (rain's
-    /// verified 70..75 window — the constants live with their law in `weather::precip`), and
-    /// `params.clip` the target-pixel rectangle (`z <= x` = no clip).
+    /// Write this frame's uniform rows and return the clipped rows' offsets by (fog slot, clip
+    /// bits). Rows 0..6 are the fog policies in [`EffectFog::slot`] order: `fog.x` the colour
+    /// policy (`0x70baf0`), `fog.y` rain's forced fog with `zw` its start and end.
     fn build_params(
         &mut self,
         device: &RenderDevice,
@@ -215,19 +168,16 @@ impl EffectMeta {
     }
 }
 
-/// Per-(texture, light-buffer) bind groups (texture + sampler + light blob + params uniform),
-/// cached across frames — invalidated by that image's asset events, mirroring bevy_ui_render's
-/// cache. The light key is `None` for the world's shared buffer (startup-created, never
-/// re-created, so it cannot stale a cached group) or a booth scene blob's id (0539 §5).
+/// Bind groups per (texture, light buffer), cached until the image changes; the light key is
+/// `None` for the world's buffer, which is never re-created.
 #[derive(Resource, Default)]
 pub struct EffectBindGroups {
     images: HashMap<(AssetId<Image>, Option<BufferId>), BindGroup>,
-    /// The params buffer the cached groups were built against — see
-    /// [`prepare_effect_bind_groups`].
+    /// The params buffer the cached groups bind.
     params_buffer: Option<BufferId>,
 }
 
-/// The lane's pipeline: layouts + shader, specialized per (blend, raster bias, msaa, hdr).
+/// The lane's pipeline: layouts and shader, specialized per (blend, raster bias, msaa, hdr).
 #[derive(Resource)]
 pub struct EffectPipeline {
     view_layout: BindGroupLayoutDescriptor,
@@ -250,10 +200,9 @@ pub fn init_effect_pipeline(mut commands: Commands, asset_server: Res<AssetServe
             (
                 texture_2d(TextureSampleType::Float { filterable: true }),
                 sampler(SamplerBindingType::Filtering),
-                // The shared global light/fog blob (`lighting::global_light`) — sized at bind
-                // time; the WGSL struct pins the layout.
+                // The shared light and fog blob, sized at bind time; the WGSL struct pins it.
                 storage_buffer_read_only_sized(false, None),
-                // The per-draw fog-params `vec4`, dynamic-offset into the canonical rows.
+                // The per-draw params row, by dynamic offset.
                 uniform_buffer::<EffectParams>(true),
             ),
         ),
@@ -269,24 +218,15 @@ pub fn init_effect_pipeline(mut commands: Commands, asset_server: Res<AssetServe
 pub struct EffectPipelineKey {
     samples: u32,
     hdr: bool,
-    /// The draw's blend — the whole state-variant axis (0733 §4).
     blend: EffectBlend,
-    /// The rasterizer depth-bias constant (the decal family's coplanarity settle; 0 for
-    /// free-floating geometry). Three values exist ({0, 8192, 32768}), so the key space stays
-    /// small. Nonzero ALSO selects the `DECAL_WORLD_CLIP` transform (0781): a coplanar decal
-    /// keeps absolute verts and runs the mesh path's `clip_from_world`, so its depth ties
-    /// against the drawn ground within the bias.
+    /// The rasterizer depth-bias constant, 0 for free-floating geometry; nonzero also selects
+    /// `DECAL_WORLD_CLIP`, absolute verts through the mesh path's `clip_from_world`.
     raster_bias: i32,
-    /// The **slope-scale** half of the settle, keyed by bits because `f32` is not `Hash`/`Eq`.
-    /// Two values exist ({0.0, the foam's}), so the key space stays as small as `raster_bias`'s.
+    /// The depth-bias slope scale as bits: `f32` is not `Hash`.
     raster_slope_bits: u32,
-    /// Does the fragment multiply by the scene's matte light? The reference decides this per
-    /// emitter through a synthesized `M2Material` (`EffectDrawSpec::lit`), and it is a shader
-    /// def rather than a uniform bit so the 95% unlit majority keeps the identical instruction
-    /// stream it has today.
+    /// The fragment multiplies by the scene's light (`EFFECT_LIT`).
     lit: bool,
-    /// Does this draw ignore the depth buffer entirely (`depth_compare = Always`)? Two values
-    /// exist and only one family sets it — see [`super::buffer::EffectDrawSpec::no_depth_test`].
+    /// Depth compare `Always`; see [`super::buffer::EffectDrawSpec::no_depth_test`].
     no_depth_test: bool,
 }
 
@@ -297,19 +237,14 @@ impl SpecializedRenderPipeline for EffectPipeline {
         let vertex_layout = VertexBufferLayout::from_vertex_formats(
             VertexStepMode::Vertex,
             vec![
-                // position (camera-relative — prepare rebased it; 0733 §2. Decal draws are
-                // the exception: absolute world-space, transformed by `clip_from_world`; 0781)
+                // position: camera-relative, absolute for decals
                 VertexFormat::Float32x3,
                 // uv
                 VertexFormat::Float32x2,
-                // color (raw authored gamma RGBA)
+                // color: raw authored gamma RGBA
                 VertexFormat::Float32x4,
             ],
         );
-        // The blend states each family's material carried (0733 §4): Add/Alpha/Opaque are the
-        // P1 trio; Multiply is bevy's own `AlphaMode::Multiply` state (mesh.rs:2486 — the blob
-        // shadow's `dst·lerp(1, src, α)` with the shader-side premultiply); Mod2x is 0528's
-        // `(Dst, Src)` = `2·src·dst` (rain's verified state, ARMORREFLECT's law).
         let (blend, depth_write, blend_def) = match key.blend {
             EffectBlend::Add => (
                 Some(BlendState::PREMULTIPLIED_ALPHA_BLENDING),
@@ -318,8 +253,7 @@ impl SpecializedRenderPipeline for EffectPipeline {
             ),
             EffectBlend::Alpha => (Some(BlendState::ALPHA_BLENDING), false, "BLEND_ALPHA"),
             EffectBlend::Opaque => (None, true, "BLEND_OPAQUE"),
-            // EGxBlend 1: the same pipeline state as Opaque — the alpha TEST is the whole
-            // difference, and it lives in the fragment shader (wgpu has no `glAlphaFunc`).
+            // EGxBlend 1: Opaque's state, its alpha test in the shader (wgpu has no `glAlphaFunc`).
             EffectBlend::AlphaKey => (None, true, "BLEND_ALPHAKEY"),
             EffectBlend::Multiply => (
                 Some(BlendState {
@@ -351,24 +285,19 @@ impl SpecializedRenderPipeline for EffectPipeline {
             ),
         };
         let mut shader_defs = vec![blend_def.into()];
-        // The decal family (nonzero raster bias ⇔ ground-coplanar): absolute verts through
-        // `clip_from_world` — the same matrix, hence the same rounding, as the world-mesh
-        // shaders whose depth the bias must settle against. `prepare_effects` skips these
-        // draws' cam-relative rebase on the same predicate (decision 0781).
+        // Coplanar draws: absolute verts through the world meshes' own `clip_from_world`, so the
+        // bias settles against the same rounding; `prepare_effects` skips their rebase to match.
         if key.raster_bias != 0 {
             shader_defs.push("DECAL_WORLD_CLIP".into());
         }
-        // The scene's matte light on this draw's RGB (the emitter's synthesized-material
-        // `GL_LIGHTING`; `EffectDrawSpec::lit` carries the byte law).
         if key.lit {
             shader_defs.push("EFFECT_LIT".into());
         }
-        // `$WOW_PARTICLE_FLAT` — the fragment-input A/B (B16): solid magenta, no inputs.
+        // `$WOW_PARTICLE_FLAT`: solid magenta, no fragment inputs.
         if std::env::var_os("WOW_PARTICLE_FLAT").is_some() {
             shader_defs.push("WOW_PARTICLE_FLAT".into());
         }
-        // `$WOW_PARTICLE_NODEPTH` — the occlusion A/B (B16): force the depth COMPARE to
-        // `Always`, splitting "nothing is emitted" from "emitted and the depth buffer eats it".
+        // `$WOW_PARTICLE_NODEPTH`: depth compare `Always`, to tell occluded from never drawn.
         let depth_compare =
             if key.no_depth_test || std::env::var_os("WOW_PARTICLE_NODEPTH").is_some() {
                 CompareFunction::Always
@@ -422,8 +351,7 @@ impl SpecializedRenderPipeline for EffectPipeline {
     }
 }
 
-/// Copy the main world's frame stream into the lane, and drop bind-group cache entries for
-/// images that changed (the UI cache-invalidation shape).
+/// Copy the frame's stream in, and drop the cached bind groups of images that changed.
 fn extract_effects(
     mut meta: ResMut<EffectMeta>,
     mut bind_groups: ResMut<EffectBindGroups>,
@@ -464,9 +392,8 @@ fn extract_effects(
     }));
 }
 
-/// `$WOW_EFFECT_TRACE`'s lane names: which rung of the pre-water surface-decal band a draw's sort
-/// bias is, or `None` for everything else on the stream (particles, ribbons, foam, precipitation).
-/// Keyed on the sort rung — the only field that is unique per decal lane (`sky_order::Rung`).
+/// `$WOW_EFFECT_TRACE`'s name for a surface-decal draw, keyed on its sort rung, the one field
+/// unique per decal lane; `None` for everything else.
 fn decal_lane(bias: f32) -> Option<&'static str> {
     use crate::sky_order::Rung;
     match bias {
@@ -495,9 +422,7 @@ fn queue_effects(
     }
     let draw_function = draw_functions.read().id::<DrawEffects>();
     for (view, msaa) in &views {
-        // A draw targets ONE main-world camera (the world camera or a booth's — resolved by
-        // the sim); the phase map is keyed by the retained view, whose main entity IS that
-        // camera. Views without a transparent phase (shadow/prepass) fall out here.
+        // Views without a transparent phase (shadow, prepass) fall out here.
         let Some(phase) = phases.get_mut(&view.retained_view_entity) else {
             continue;
         };
@@ -520,15 +445,12 @@ fn queue_effects(
                 },
             );
             phase.add(Transparent3d {
-                // The material path's exact metric: view-space z of the sort point + the
-                // ladder rung (see the module doc).
+                // The material path's metric: the sort point's view z plus the rung.
                 distance: rangefinder.distance(&draw.anchor) + draw.bias,
                 pipeline,
                 entity: (Entity::PLACEHOLDER, MainEntity::from(draw.main_entity)),
                 draw_function,
-                // The draw-record index rides here until the prepare walk rewrites it to a
-                // merged-draw index (whose length spans the items it absorbed — the sorted
-                // phase renderer's own batching contract).
+                // The draw index, until the prepare walk rewrites it to a merged draw and span.
                 batch_range: (i as u32)..(i as u32 + 1),
                 extra_index: PhaseItemExtraIndex::None,
                 indexed: true,
@@ -537,9 +459,7 @@ fn queue_effects(
     }
 }
 
-/// The run identity the merge walk groups by: everything two adjacent items must share to be
-/// one GPU draw — pipeline (blend/bias/msaa/hdr), bind group (texture + light), and the params
-/// row (the fog policy AND the clip rect, which is why two panes' clouds never fold together).
+/// What adjacent items must share to merge: pipeline, texture, light buffer and params row.
 type RunKey = (
     bevy::render::render_resource::CachedRenderPipelineId,
     AssetId<Image>,
@@ -547,19 +467,14 @@ type RunKey = (
     u32,
 );
 
-/// The last frame's effect-draw census, `[items, merged draws]` — what `FPS_PROBE` prints as
-/// `fx=`: how many effect items the transparent phase carried and how many draws the
-/// adjacency merge left. Decision 1955 read it to refute the additive-window regroup: the
-/// merge already folds about half, and a commutative regroup added two folds in ninety.
+/// The last frame's `[effect items, merged draws]`, which `FPS_PROBE` prints as `fx=`.
 pub static EFFECT_DRAW_STATS: [std::sync::atomic::AtomicU32; 2] = [
     std::sync::atomic::AtomicU32::new(0),
     std::sync::atomic::AtomicU32::new(0),
 ];
 
-/// After `PhaseSort`: rebase each draw's vertices against its target view's camera position
-/// (0733 §2; decal draws are exempt — 0781), upload them, build the frame's index stream in
-/// sorted-item order while merging sort-adjacent compatible items into single draws, and write
-/// the canonical fog-params rows once.
+/// After `PhaseSort`: rebase and upload the vertices, then build the index stream in sorted
+/// order, merging adjacent compatible items.
 fn prepare_effects(
     device: Res<RenderDevice>,
     queue: Res<RenderQueue>,
@@ -569,12 +484,8 @@ fn prepare_effects(
     views: Query<&ExtractedView>,
 ) {
     let meta = &mut *meta;
-    // The rebase (0733 §2): subtract the draw's target camera position — the exact value the
-    // view's `ViewUniform.world_position` is built from (`view/mod.rs:985`), so the shader's
-    // `view_from_world`-rotation reconstruction is bitwise-consistent. The stream stays
-    // world-space main-world-side (instruments read it); only the upload copy moves.
-    // (A handful of extracted views; prepass/shadow views of the same camera collapse to the
-    // same translation.)
+    // Subtract the exact value `ViewUniform.world_position` is built from, so the shader's
+    // reconstruction matches bitwise; only the upload copy moves.
     let mut cams: HashMap<MainEntity, Vec3> = HashMap::default();
     for view in &views {
         cams.insert(
@@ -583,15 +494,11 @@ fn prepare_effects(
         );
     }
     for draw in &meta.draws {
-        // Decal draws stay ABSOLUTE: their pipeline transforms through `clip_from_world`
-        // (`DECAL_WORLD_CLIP`, the same `raster_bias != 0` predicate — decision 0781), so a
-        // rebase here would shift them a full camera-position off.
+        // Coplanar draws stay absolute: `DECAL_WORLD_CLIP` keys on the same `raster_bias != 0`.
         if draw.raster_bias != 0 {
             continue;
         }
-        // …and so does a draw whose producer already wrote camera-relative vertices: subtracting
-        // again would shift it a whole camera position off. That flag exists for f32 precision on
-        // sub-centimetre geometry — see [`super::buffer::EffectDrawSpec::cam_relative`].
+        // So does a draw its producer already wrote camera-relative.
         if draw.cam_relative {
             continue;
         }
@@ -608,31 +515,15 @@ fn prepare_effects(
     }
     meta.vertices.write_buffer(&device, &queue);
 
-    // The merge walk (0733 §3, the bevy_ui_render shape): one pass over each LIVE view's sorted
-    // items — the same views queue targeted, never the raw phase map (a map entry bevy hasn't
-    // swept yet would carry a dead frame's indices). Every effect item's indices are appended
-    // (quad pattern or identity tri-list); adjacent items sharing a [`RunKey`] fold into the
-    // run-opening item, whose `batch_range` is rewritten to
-    // `merged_index .. merged_index + run_len` — the phase renderer draws the opener once and
-    // advances past the absorbed items (`render_phase/mod.rs:1487`).
+    // The merge walk, over each live view's sorted items, never the raw phase map (an unswept
+    // entry carries a dead frame's indices): a run of items sharing a [`RunKey`] becomes one
+    // merged draw, and its opener's `batch_range` is rewritten to `merged .. merged + run_len`.
     let effect_fn = draw_functions.read().id::<DrawEffects>();
-    // `$WOW_EFFECT_TRACE` — the lane's own phase probe (the WOW_PHASE shape, decision 0665,
-    // asked of effect items): during the merge walk, record each **surface-decal** item — every
-    // rung of the pre-water band, named by [`decal_lane`] — with its **index in the sorted
-    // transparent phase**, its sort distance, and its appended index range, then log the phase
-    // totals. Splits "never pushed / never queued / merged away / submitted but the GPU state ate
-    // it" — the gap no pixel reading can see into — and, since 1789, reads the draw-order ladder
-    // straight off a live frame: `item 4` vs `item 81` is what B347 was, measured.
-    //
-    // The lane is keyed on the SORT rung because that is the one field unique per lane: the raster
-    // bias is shared (every ground decal rides `DECAL_RASTER`, and prints were being labelled
-    // shadows here for exactly that reason).
+    // `$WOW_EFFECT_TRACE`: each surface-decal item's phase index, sort distance and index
+    // range, then the frame's totals.
     let trace = effect_trace();
     let mut trace_lines: Vec<String> = Vec::new();
-    // The per-draw uniform rows, THIS frame: the six canonical fog policies plus one row per
-    // distinct (fog, clip) a clipped draw asks for. It is rebuilt every frame rather than once
-    // because the clip set is per-frame — the rows are a handful of `vec4` pairs, and the walk
-    // below needs the offsets to key its runs on.
+    // Rebuilt every frame: the clip set is per-frame, and the runs key on the row offsets.
     let clip_rows = meta.build_params(&device, &queue);
     meta.indices.clear();
     meta.merged.clear();
@@ -663,12 +554,8 @@ fn prepare_effects(
                 continue;
             }
             let (pipeline, draw_idx) = (item.pipeline, item.batch_range.start as usize);
-            // Defense in depth: `batch_range` is only a draw index if nothing else rewrote it.
-            // Every draw's probe identity is mesh-less, which keeps bevy's sorted-phase batcher
-            // off our items (it claims any item whose MAIN entity has a registered mesh and
-            // rewrites the range to an instance index — the Goldshire-teleport crash, where
-            // foam draws carried their water chunk). If a future violation sneaks in, degrade
-            // to one skipped item — never a render-thread panic.
+            // `batch_range` is a draw index only while bevy's batcher leaves the item alone, which
+            // it does while the main entity owns no mesh; otherwise skip the item, never panic.
             let Some(draw) = meta.draws.get(draw_idx) else {
                 close(&mut phase.items, &mut open, meta.merged.len());
                 phase.items[i].batch_range = 0..0;
@@ -705,8 +592,7 @@ fn prepare_effects(
             }
             let params_offset = match draw.clip {
                 None => meta.params_offsets[draw.fog.slot() as usize],
-                // A clipped draw whose row did not fit the frame's budget degrades to the
-                // unclipped one — the pre-2093 picture, never a wrong pixel elsewhere.
+                // A clipped draw past the row budget degrades to its unclipped row.
                 Some(clip) => *clip_rows
                     .get(&(draw.fog.slot(), clip.to_array().map(f32::to_bits)))
                     .unwrap_or(&meta.params_offsets[draw.fog.slot() as usize]),
@@ -782,9 +668,7 @@ fn prepare_effect_bind_groups(
     let Some(params_binding) = meta.params.binding() else {
         return;
     };
-    // The cached groups hold a binding INTO the params buffer, and that buffer is rebuilt every
-    // frame now (the clip rows are per-frame) — so a re-created buffer, which is what a growing
-    // row count produces, has to invalidate the cache or the groups bind freed memory.
+    // The cached groups bind into the params buffer: a re-created one invalidates them all.
     if bind_groups.params_buffer != meta.params_buffer {
         bind_groups.images.clear();
         bind_groups.params_buffer = meta.params_buffer;
@@ -794,8 +678,7 @@ fn prepare_effect_bind_groups(
         if bind_groups.images.contains_key(&key) {
             continue;
         }
-        // Not yet prepared GPU-side: the draw is skipped this frame (the same "withhold until
-        // resident" the main-world gate applies one asset-layer earlier).
+        // Not on the GPU yet: the draw is skipped this frame.
         let Some(image) = gpu_images.get(draw.texture) else {
             continue;
         };
@@ -860,12 +743,11 @@ impl<P: PhaseItem> RenderCommand<P> for DrawEffectBatch {
         pass: &mut TrackedRenderPass<'w>,
     ) -> RenderCommandResult {
         let meta = meta.into_inner();
-        // `batch_range.start` is the merged-draw index (the prepare walk's rewrite); its length
-        // is the item span the phase renderer advances by — not read here.
+        // `batch_range.start` is the merged-draw index; its length is the renderer's advance.
         let Some(draw) = meta.merged.get(item.batch_range().start as usize) else {
             return RenderCommandResult::Skip;
         };
-        // GPU image not prepared yet: withheld, exactly like the main-world residency gate.
+        // Image not on the GPU yet: withheld.
         let key = (draw.texture, draw.light.as_ref().map(|b| b.id()));
         let Some(image_bind_group) = bind_groups.into_inner().images.get(&key) else {
             return RenderCommandResult::Skip;
@@ -877,8 +759,7 @@ impl<P: PhaseItem> RenderCommand<P> for DrawEffectBatch {
         pass.set_bind_group(1, image_bind_group, &[draw.params_offset]);
         pass.set_vertex_buffer(0, vertices.slice(..));
         pass.set_index_buffer(indices.slice(..), IndexFormat::Uint32);
-        // The `$WOW_EFFECT_TRACE` tail: what draw_indexed ACTUALLY ran — read against the
-        // prepare-side item lines to see which appended ranges never reached the GPU.
+        // `$WOW_EFFECT_TRACE`: what `draw_indexed` actually ran.
         if effect_trace() {
             info!(
                 "effect draw: merged {} indices {:?}",
@@ -891,9 +772,7 @@ impl<P: PhaseItem> RenderCommand<P> for DrawEffectBatch {
     }
 }
 
-/// Registers the render-world half. The main-world [`EffectQuads`] resource and the family
-/// writers are their plugins' ([`super::ParticlePlugin`], [`crate::ribbons::RibbonPlugin`],
-/// the decal/foam/precip modules).
+/// Registers the render-world half; [`EffectQuads`] and its writers belong to the family plugins.
 pub struct EffectLanePlugin;
 
 impl Plugin for EffectLanePlugin {
@@ -912,8 +791,7 @@ impl Plugin for EffectLanePlugin {
                 Render,
                 (
                     queue_effects.in_set(RenderSystems::Queue),
-                    // After `PhaseSort` (the set ordering) — the merge walk needs the final
-                    // item order.
+                    // After `PhaseSort`: the merge walk needs the final item order.
                     prepare_effects.in_set(RenderSystems::PrepareResources),
                     prepare_effect_bind_groups.in_set(RenderSystems::PrepareBindGroups),
                 ),
@@ -921,9 +799,7 @@ impl Plugin for EffectLanePlugin {
     }
 }
 
-/// `$WOW_EFFECT_TRACE` — the effect lane's per-item / per-bind / per-draw trace, one read for
-/// the process: the three sites that asked the environment per frame (and per new bind group)
-/// now ask this.
+/// `$WOW_EFFECT_TRACE`: the lane's per-item, per-bind and per-draw trace, read once.
 fn effect_trace() -> bool {
     static TRACE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *TRACE.get_or_init(|| std::env::var_os("WOW_EFFECT_TRACE").is_some())
@@ -933,21 +809,18 @@ fn effect_trace() -> bool {
 mod tests {
     use bevy::math::{Mat3, Mat4, Vec3};
 
-    /// One rasterizer constant-bias unit for a `Depth32Float` value: `2^(e−23)`, the
-    /// next-representable step at that depth's exponent (the Vulkan/Metal float-depth scale
-    /// the pipeline's `DepthBiasState::constant` is multiplied by).
+    /// One constant-bias unit at a `Depth32Float` depth: `2^(e−23)`, the step at its exponent.
     fn bias_unit(depth: f32) -> f32 {
         f32::from_bits(depth.to_bits() + 1) - depth
     }
 
-    /// The world-mesh route: `clip_from_world × p` — `position_world_to_clip`
-    /// (terrain.wgsl / wow_model.wgsl), and `DECAL_WORLD_CLIP`'s transform.
+    /// The world meshes' and `DECAL_WORLD_CLIP`'s route: `clip_from_world × p`.
     fn depth_world(clip_from_world: &Mat4, p: Vec3) -> f32 {
         let c = *clip_from_world * p.extend(1.0);
         c.z / c.w
     }
 
-    /// The cam-relative route (0733 §2): prepare's rebase, then rotation + `clip_from_view`.
+    /// The cam-relative route: prepare's rebase, then rotation + `clip_from_view`.
     fn depth_cam_relative(
         view_from_world: &Mat4,
         clip_from_view: &Mat4,
@@ -959,18 +832,12 @@ mod tests {
         c.z / c.w
     }
 
-    /// 0781's premise, demonstrated in the two routes' exact arithmetic shapes: give both the
-    /// SAME ground vertex at WoW-scale coordinates, and the cam-relative route (0733 §2)
-    /// disagrees with the world-mesh route by the ORDER OF THE WHOLE 0781-era 4096-unit bias
-    /// at close camera distances — pure arithmetic divergence spending the margin that exists
-    /// to settle real geometry deltas (the CPU-baked decal verts vs the GPU-transformed render
-    /// verts; GPU per-pipeline FMA differences push the route term higher still). The
-    /// same-matrix route spends zero on it by construction. Coplanarity is a relationship with
-    /// the receiver's own transform: a decal must ride the receiver's matrix.
+    /// At WoW-scale coordinates the cam-relative route misses the world-mesh depth by the order of
+    /// a 4096-unit bias up close, while the same matrix matches bitwise: a decal rides its
+    /// receiver's matrix.
     #[test]
     fn decal_depth_ties_only_through_the_mesh_matrix() {
-        // A WMO floor vertex at eastern-Kalimdor-scale coordinates (bevy = (−wow.y, wow.z,
-        // −wow.x); magnitudes of several thousand yards are ordinary).
+        // A floor vertex at Kalimdor-scale coordinates (bevy = (−wow.y, wow.z, −wow.x)).
         let ground = Vec3::new(3807.13, 7.42, 7093.87);
         let clip_from_view =
             Mat4::perspective_infinite_reverse_rh(std::f32::consts::FRAC_PI_4, 16.0 / 9.0, 0.1);
@@ -980,21 +847,19 @@ mod tests {
             // The zoom sweep: camera 1.5..41 yd out along a fixed off-axis orbit offset.
             let d = 1.5 + step as f32 * 0.5;
             let cam = ground + dir * d;
-            // Bevy's own construction: camera world matrix, general inverse, premultiplied
-            // product (`ExtractedView`) — the rounding path the mesh shaders actually see.
+            // Bevy's own construction (`ExtractedView`), the rounding the mesh shaders see.
             let world_from_view = Mat4::look_at_rh(cam, ground, Vec3::Y).inverse();
             let view_from_world = world_from_view.inverse();
             let clip_from_world = clip_from_view * view_from_world;
             let mesh = depth_world(&clip_from_world, ground);
             let bias = 4096.0 * bias_unit(mesh);
-            // The fix: same matrix, same input — bitwise the same depth, zero divergence.
+            // Same matrix, same input: bitwise the same depth.
             assert_eq!(depth_world(&clip_from_world, ground), mesh);
             let route =
                 (depth_cam_relative(&view_from_world, &clip_from_view, ground, cam) - mesh).abs();
             worst_route_over_bias = worst_route_over_bias.max(route / bias);
         }
-        // Measured 0.93× at d=1.5 on this sweep; the assertion keeps headroom for
-        // platform-to-platform rounding differences while still pinning the order.
+        // 0.93× at d = 1.5 on this sweep; the bound leaves headroom for platform rounding.
         assert!(
             worst_route_over_bias > 0.5,
             "cam-relative route divergence stayed far inside the bias \
@@ -1003,33 +868,19 @@ mod tests {
         );
     }
 
-    /// 0781's named residual, sized (B131 — the director-confirmed flicker): the decal's verts
-    /// are CPU-baked world positions, the receiver's are GPU-transformed per frame, and the two
-    /// roundings displace the baked point from the drawn plane by a few ulps of the WORLD
-    /// COORDINATE — millimetres at city magnitudes. The depth conflict is that displacement's
-    /// component along the receiver's normal: a level street barely samples it (the y ulp at
-    /// street height is micro-scale), a *sloped* receiver takes the full horizontal ulps onto
-    /// its tilted normal — and the confirmed flicker walk was the Stormwind gate ramp. Model
-    /// the 3-ulp worst case (0781: "~1–3 ulps") at the walk's own coordinates across zoom and
-    /// slope, and pin both ends of the sizing.
-    ///
-    /// **Since 1817 it pins the raise as well as the floor.** The residual is 2.59× the 0781-era
-    /// +4096 margin, so it is also **1.30× the +8192** the selection ring and the ground-target
-    /// reticle rode until the RE showed they share the blob shadow's lane and therefore its
-    /// conflict — those two were under their own residual and had simply not been walked on a
-    /// slope. The measurement is per-lane-independent by construction: the residual is the
-    /// *bake's*, and the bake is one path, so one number serves every ground decal.
+    /// CPU-baked decal verts and GPU-transformed receiver verts differ by a few ulps of the world
+    /// coordinate, which a sloped receiver takes onto its normal as depth. Sized at 3 ulps on the
+    /// Stormwind gate ramp across zoom and slope: above an 8192-unit bias, under half of
+    /// `Rung::DECAL_RASTER`. One bake path, so one number serves every ground decal.
     #[test]
     fn raised_bias_dominates_the_bake_residual() {
         use crate::sky_order::Rung;
-        // The ramp mid-spot of the flicker walk: bevy (−wow.y, wow.z, −wow.x) of
-        // wow (−8843.41, 642.68, 95.92).
+        // The Stormwind gate ramp, wow (−8843.41, 642.68, 95.92) in bevy axes.
         let ground = Vec3::new(-642.68, 95.92, 8843.41);
         let clip_from_view =
             Mat4::perspective_infinite_reverse_rh(std::f32::consts::FRAC_PI_4, 16.0 / 9.0, 0.1);
         let ulp = |v: f32| f32::from_bits(v.to_bits() + 1) - v;
-        // 3 ulps per world axis, signs free — the worst displacement onto a unit normal n is
-        // the absolute sum.
+        // 3 ulps per world axis, signs free: the worst normal offset is the absolute sum.
         let worst_normal_offset = |n: Vec3| {
             3.0 * (n.x.abs() * ulp(ground.x)
                 + n.y.abs() * ulp(ground.y)
@@ -1053,8 +904,7 @@ mod tests {
                     let view_from_world = world_from_view.inverse();
                     let clip_from_world = clip_from_view * view_from_world;
                     let depth = depth_world(&clip_from_world, ground);
-                    // Window-depth cost of the offset along the normal, differenced in f64 so
-                    // the measurement isn't polluted by the very f32 noise it measures.
+                    // The offset's window-depth cost, differenced in f64 to keep f32 noise out.
                     let m = clip_from_world.as_dmat4();
                     let z_at = |p: bevy::math::DVec3| {
                         let c = m * p.extend(1.0);
diff --git a/crates/benilla-world/src/particles/sim.rs b/crates/benilla-world/src/particles/sim.rs
index d00df264..bfa80326 100644
--- a/crates/benilla-world/src/particles/sim.rs
+++ b/crates/benilla-world/src/particles/sim.rs
@@ -27,36 +27,25 @@ struct StepEnv {
     follow: Vec3,
 }
 
-/// One step of the verified vanilla integrator (`particle_integrate` @ `0x7b2680`): age/kill,
-/// the follow-delta add (before the velocity step, skipped once on a fresh particle — the
-/// `0x7b2744` branch), `pos += dt·v` with the gravity term on the frame's up axis
-/// (`pos.up −= ½·g·dt²`, `v.up −= g·dt`), then drag (`v −= min(dt·drag, 1)·v`) — and, for a
-/// sphere KILL-OUTBOUND emitter (`rt 0x800`,
-/// [`benilla_formats::ParticleEmitterDef::kill_outbound`]), the reference's tail test: the
-/// particle dies the frame `dot(stepVelocity, pos − origin) > 0`, where `stepVelocity` is the
-/// pre-gravity, pre-drag velocity (exactly the value the position update consumed — the byte
-/// order at `0x7b2680`) and `origin` is the emitter origin in the stored frame (the reference's
-/// stored coords put the emitter at zero; ours carry the anchor/bone offset, so the caller
-/// re-origins — same geometry). Returns false = dead.
+/// One step of the reference integrator (`0x7b2680`): age and kill; the follow-delta add, skipped
+/// on a fresh particle (`0x7b2744`); `pos += dt·v` with gravity on the frame's up axis
+/// (`pos.up −= ½·g·dt²`, `v.up −= g·dt`); drag `v −= min(dt·drag, 1)·v`. A kill-outbound emitter
+/// (`rt 0x800`) kills once `dot(stepVelocity, pos − origin) > 0`, with the pre-gravity velocity
+/// and the emitter origin in the stored frame. False is dead.
 fn integrate_particle(p: &mut Particle, env: &StepEnv) -> bool {
     let (dt, g) = (env.dt, env.gravity);
     p.age += dt;
-    // Kill at the particle's OWN birth-sampled lifetime (the emitter's lifespan channel
-    // animates — decision 0844; the reference feeds each spawn the current value).
+    // Its own birth-sampled lifetime: the reference feeds each spawn the current lifespan.
     if p.age >= p.life {
         return false;
     }
-    // FOLLOW-DELTA (file 0x4000, wow-re `part-emitter-motion.md` §2): the shared per-frame
-    // fraction of the emitter's motion, applied to every particle EXCEPT on its first
-    // integrate (the reference's particle+0xd bit — set at spawn, cleared here unconsumed).
+    // Follow-delta (file 0x4000, `0x7b2744`), skipped on the first integrate (particle+0xd).
     if p.fresh {
         p.fresh = false;
     } else {
         p.pos += env.follow;
     }
-    // MODEL-particle tumble (`0x7b28e0`, wow-re `part-model-particles.md`): the Rodrigues
-    // half-angle Δquat, body-frame right-multiply, skipped below the reference's 1e-4
-    // threshold — then the shared linear integrator below. Quad particles carry zero.
+    // Model-particle tumble (`0x7b28e0`): a body-frame Rodrigues step, skipped under 1e-4.
     let theta = p.angvel.length();
     if theta > 1e-4 {
         p.quat = (p.quat * Quat::from_axis_angle(p.angvel / theta, theta * dt)).normalize();
@@ -82,26 +71,10 @@ fn integrate_particle(p: &mut Particle, env: &StepEnv) -> bool {
     true
 }
 
-/// **The follow-delta fraction** (file flag `0x4000`, rt `0x40000`) — the share of the emitter's
-/// per-frame world translation that is added to every live particle on top of whatever its
-/// storage space already gives it (`speed` is `|Δ| / dt`, the yd/s the authored response is
-/// keyed on). Zero when unauthored, and zero for a degenerate response (equal authored speeds,
-/// which the reference answers by zeroing both).
-///
-/// **The ride-vs-trail baseline is NOT here** — it is the storage space itself (decision 1585).
-/// wow-re `part-emitter-motion.md` §2c-B: file `0x10` SET stores the raw emitter-LOCAL pos/vel
-/// (`0x7b8aa5`) and the draw folds the live emitter matrix `rt+0x1fc` back in every frame
-/// (`0x7b3efb`) ⇒ a rigid ride, keep `1.0`, for free. CLEAR bakes pos/vel through that matrix
-/// into WORLD at birth (`0x7b8acf`/`0x7b8b0f`) and the draw does *not* fold `rt+0x1fc`
-/// (`0x7b3f48`) ⇒ world-frozen, keep `0.0`, also for free. Spending a per-frame correction term
-/// to *simulate* either baseline is what decision 1578 did, and it could only ever approximate
-/// the translation half — see 1585.
-///
-/// This term is read independently of `0x10`: `0x7b5303` builds `rt+0x26c` and `0x7b2744` adds
-/// `rt+0x278` whatever `0x100` says. Over the CLEAR baseline it recovers a ride fraction —
-/// ArcaneShot's head glow, 0.1 @ 2.5 yd/s → 0.9 @ 16.7, riding the arrowhead while its three
-/// unflagged siblings hang frozen behind it. Over a SET baseline (12 emitters corpus-wide carry
-/// both) it genuinely leads, and we reproduce that literally.
+/// The follow-delta fraction (file flag `0x4000`, rt `0x40000`): the share of the emitter's
+/// per-frame translation added to every live particle, keyed on `speed` = |Δ|/dt in yd/s; zero
+/// when unauthored or degenerate. The ride-vs-trail baseline is the storage space, not this term,
+/// which applies whatever `0x10` says (`0x7b5303` builds `rt+0x26c`, `0x7b2744` adds `rt+0x278`).
 fn follow_fraction(def: &benilla_formats::ParticleEmitterDef, speed: f32) -> f32 {
     if !def.follow_emitter() {
         return 0.0;
@@ -111,11 +84,8 @@ fn follow_fraction(def: &benilla_formats::ParticleEmitterDef, speed: f32) -> f32
     })
 }
 
-/// The velocity-inherit trigger (wow-re `part-emitter-motion.md` §1, `0x7b5230` bytes
-/// 0x7b53ce–0x7b54ca): accumulate dt; once past 1/30 s (`_DAT_0081d82c`), hold
-/// `oneFrameΔ · ((1/30)/accum) · scale` — zeroed while nothing is live — and reset. Between
-/// triggers the held value stands (births keep reading it). The exact factor carries the ×1/30
-/// the first transcription sketch missed (a ~30× over-kick).
+/// The velocity-inherit trigger (`0x7b5230`, `0x7b53ce`..`0x7b54ca`): past 1/30 s of dt
+/// (`0x81d82c`), hold `oneFrameΔ · ((1/30)/accum) · scale`, zero with nothing live, and reset.
 fn inherit_trigger(accum: &mut f32, held: &mut Vec3, dt: f32, delta: Vec3, live: bool, scale: f32) {
     const INTERVAL: f32 = 1.0 / 30.0;
     *accum += dt;
@@ -129,16 +99,10 @@ fn inherit_trigger(accum: &mut f32, held: &mut Vec3, dt: f32, delta: Vec3, live:
     }
 }
 
-/// The per-frame CHILD drive (wow-re `part-child-recursion.md`, VERIFIED): each child's spawn
-/// accumulation runs **once per live parent particle** — the reference's `0x7b5b9f` call with
-/// the CHILD receiver and the parent context's translation swapped to the particle's
-/// post-integration position — so births land at whichever particle's call tips the child's
-/// own `rate·dt` accumulator (volume scales with the parent's live count), composed through
-/// the PARENT's rotation fold (the child's record position never composes — the context
-/// translation is REPLACED by the particle). Child file flag 0x40 routes the parent
-/// PARTICLE's velocity into the child's inherit add (`(1+S11·var)·v` — for children the
-/// inherit vector IS the particle velocity, copied per call at `0x7b5b5e`). A burst child
-/// latches on its first call of the rising-edge frame. A child never self-emits ambiently.
+/// The child drive (`0x7b5b9f`): a child's `rate·dt` accumulation runs once per live parent
+/// particle, births landing at that particle through the parent's rotation (the child's record
+/// position never composes). Child flag 0x40 adds `(1 + S11·var)·v` of the parent particle's
+/// velocity (`0x7b5b5e`). A child never emits on its own.
 fn drive_child(
     child: &mut ChildEmitter,
     now: &benilla_formats::ParamsNow,
@@ -166,8 +130,7 @@ fn drive_child(
             let (base, dir) = emit_local(&child.def, now, &mut child.rng);
             let local = base - origin;
             let speed = now.emission_speed * (1.0 + now.speed_variation * rand_s11(&mut child.rng));
-            // The parent particle's position is world in world mode (1585), so the child's
-            // offset/velocity fold is rotation+scale into WORLD — no frame is divided out.
+            // In world mode the parent particle is in world: the fold is rotation and scale only.
             let fold = |v: Vec3| {
                 if anchored {
                     placement.rotation * (placement.scale * wow_to_bevy(v.to_array()))
@@ -194,20 +157,10 @@ fn drive_child(
     }
 }
 
-/// A particle's **birth age** — the reference's third spawn-kernel argument, `U01 · w`
-/// (`0x7b88c4`/`0x7b88c7` in the plane kernel, byte-identical in sphere and spline; wow-re
-/// `part-birth-age-and-quad-edge.md` §1.3/§1.4).
-///
-/// `w` is **not** the lifespan, which is the reading that would halve every pool's steady-state
-/// population: the burst loop pushes a literal `0` (`0x7b5600`) and both continuous loops push the
-/// **substep dt** (`0x7b5779` interpolated, `0x7b57e2` plain). So a burst's N particles are all born
-/// at age 0 together, while a poured one is born already aged by a random fraction of the frame it
-/// was born in — which de-synchronises the births that share a frame, and is why a steady stream
-/// does not visibly pulse at the frame rate.
-///
-/// **Named approximation:** the reference substeps at a hard `0.1 s` (`[0x81d828]`, `0x7b58e7`), so
-/// its `w` is bounded by construction; we do not substep, so the frame delta is clamped here
-/// instead. Identical below 0.1 s, which is every frame that is not a hitch.
+/// Birth age `U01 · w`, the kernels' third argument (`0x7b88c4`, `0x7b88c7`): `w` is 0 for a burst
+/// (`0x7b5600`) and the substep dt for a pour (`0x7b5779`, `0x7b57e2`), so a stream's same-frame
+/// births de-synchronise. Deviation: `w` is the frame dt clamped to 0.1 s, because we do not
+/// substep as the reference does at 0.1 s (`0x81d828`, `0x7b58e7`); they differ only on a hitch.
 fn birth_age(is_burst: bool, dt: f32, rng: &mut u32) -> f32 {
     if is_burst {
         return 0.0;
@@ -215,41 +168,24 @@ fn birth_age(is_burst: bool, dt: f32, rng: &mut u32) -> f32 {
     rand01(rng) * dt.min(0.1)
 }
 
-/// The **draw-set gate's** scene inputs, bundled: the far-clip wall the gate bounds emitters at
-/// (0678), the exterior-window test a WMO interior applies to everything outside it (0786) with the
-/// camera's own room as its one exemption, and the per-frame portal PVS the rooms *inside* a
-/// building are gated by (0689/1289). One `SystemParam` because they are read together, at one
-/// place, and Bevy caps a system at 16 parameters — which `simulate_particles` already sits at, so
-/// the portal query joins this bundle rather than becoming a seventeenth.
-/// The **owner reads** — one bundle for the two questions this sim asks of an emitter's owner
-/// (a joint, a unit root, a placement submesh; never an emitter or child-draw entity, so both
-/// members are provably disjoint from the `&mut GlobalTransform` writes below): *where is it*,
-/// *is its model being drawn*, and *what is it standing on*. A `SystemParam` rather than three
-/// parameters because
-/// [`simulate_particles`] sits at Bevy's 16-param ceiling, and because the pair is one concept —
-/// the owner's frame — that no caller should be able to half-answer.
+/// What the sim asks of an emitter's owner: where it is, whether its model is drawn, and what it
+/// rides. Never an emitter or child-draw entity, so disjoint from the emitters' transform writes.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct Owners<'w, 's> {
     transforms:
         Query<'w, 's, &'static GlobalTransform, (Without<ParticleEmitter>, Without<ChildDraw>)>,
     visibility: Query<'w, 's, &'static InheritedVisibility>,
-    /// Which transport (if any) the owner's MODEL is riding — the frame world-mode particles are
-    /// stored in ([`crate::ride_frame`], decision 1591). Joined the bundle for the same reason the
-    /// portal query did: [`simulate_particles`] is at the ceiling.
+    /// The transport the owner's model rides, if any: world-mode particles' stored frame.
     rides: crate::ride_frame::RideFrames<'w, 's>,
 }
 
 impl Owners<'_, '_> {
-    /// The owner's live world position — read every frame, never from a stored anchor: a frozen
-    /// emitter stops refreshing its anchor, so gating on the stored one would latch a moving owner
-    /// out of existence the first time it crossed the wall.
+    /// The owner's live world position; a frozen emitter's stored anchor goes stale.
     fn at(&self, owner: Entity) -> Option<Vec3> {
         self.transforms.get(owner).ok().map(|gt| gt.translation())
     }
 
-    /// Is the owner's model NOT being drawn this frame — the entity lane's draw-set term (decision
-    /// 1409). Last propagate's verdict (one frame of lag on a hide that holds while the model is
-    /// culled), and an owner we cannot read is not hidden: it falls through to the drain path.
+    /// Is the owner's model undrawn (last propagate's verdict)? An unreadable owner is not hidden.
     fn hidden(&self, owner: Entity) -> bool {
         matches!(self.visibility.get(owner), Ok(v) if !v.get())
     }
@@ -261,13 +197,12 @@ pub(crate) struct SceneGates<'w, 's> {
     exterior_windows: Res<'w, crate::wmo_portal::ExteriorWindows>,
     camera_claim: Res<'w, crate::wmo_portal::CameraInteriorClaim>,
     portals: Query<'w, 's, &'static crate::wmo_portal::WmoPortalInstance>,
-    /// Streamed-in buildings this frame: a room admit can only change with the camera, a
-    /// window, a claim, a surface, or a new portal set — the last is this.
+    /// Buildings streamed in this frame, which can change a room admit.
     new_portals: Query<'w, 's, (), Changed<crate::wmo_portal::WmoPortalInstance>>,
 }
 
 impl SceneGates<'_, '_> {
-    /// Any of the three resources a draw-set verdict reads moved this frame.
+    /// Any input of a draw-set verdict moved this frame.
     pub(crate) fn changed(&self) -> bool {
         self.view.is_changed()
             || self.exterior_windows.is_changed()
@@ -275,9 +210,8 @@ impl SceneGates<'_, '_> {
             || !self.new_portals.is_empty()
     }
 
-    /// The three per-frame values every draw-set caller needs before it can ask
-    /// [`EmitterFade::in_draw_set`]: the far-clip wall, the built exterior gate, and the placement
-    /// the camera is standing in. Built ONCE per walk (the gate is a handful of 6-plane frusta).
+    /// The far-clip wall, the exterior gate and the camera's placement for
+    /// [`EmitterFade::in_draw_set`]; build once per walk.
     pub(crate) fn scene(
         &self,
         cam: Option<(&GlobalTransform, &Projection)>,
@@ -289,7 +223,7 @@ impl SceneGates<'_, '_> {
         )
     }
 
-    /// This emitter's term 5 — the live placement its rooms belong to, resolved and asked.
+    /// The room term: does the emitter's live placement admit its room?
     pub(crate) fn room_admits(&self, fade: &EmitterFade) -> bool {
         fade.room_admitted(
             fade.room
@@ -299,16 +233,12 @@ impl SceneGates<'_, '_> {
     }
 }
 
-/// The **water-plane interleave** inputs ([`crate::sky_order::FAR_SIDE_BIAS`], where the
-/// byte story lives): the loaded liquid surfaces, the eye's submersion verdict, and the room
-/// components an anchor's liquid claim resolves from. One `SystemParam` for the same 16-cap
-/// reason as [`SceneGates`].
+/// The water-plane interleave inputs ([`crate::sky_order::FAR_SIDE_BIAS`]): liquid surfaces, the
+/// eye's submersion, and the rooms an anchor's liquid claim resolves from.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct WaterInterleave<'w, 's> {
     water: Query<'w, 's, &'static crate::liquid::WaterChunkInfo>,
-    /// The spatial pre-filter every classification routes through: these lanes ask per DRAW
-    /// (every admitted emitter, every ribbon, every transparent mesh batch), and the full-walk
-    /// `surfaces_at` at that grain was the 2026-08-03 12-fps regression (`liquid::spatial`).
+    /// The spatial pre-filter every per-draw classification goes through.
     index: Res<'w, crate::liquid::WaterIndex>,
     underwater: Res<'w, crate::liquid::Underwater>,
     rooms: Query<'w, 's, &'static crate::wmo_portal::UnitWmoRoom>,
@@ -317,36 +247,22 @@ pub(crate) struct WaterInterleave<'w, 's> {
 }
 
 impl WaterInterleave<'_, '_> {
-    /// The eye's side of the water — the term that inverts EVERY verdict (`far = above XOR
-    /// submerged`). The mesh lane's reactive classifier re-runs its full walk on the frame this
-    /// flips; per-draw callers just read it through [`far_side_of_water_at`].
+    /// The eye's side of the water, which inverts every verdict (`far = above XOR submerged`).
     pub(crate) fn eye_submerged(&self) -> bool {
         self.underwater.0.any()
     }
 
-    /// True when the loaded-surface population changed since the borrowing system last ran (the
-    /// [`crate::liquid::WaterIndex`] rebuild edge) — any batch may have gained or lost the water
-    /// plane under it, so the mesh lane's reactive classifier promotes the frame to a full walk.
+    /// The loaded surfaces changed since this system last ran, so any verdict may have moved.
     pub(crate) fn surfaces_changed(&self) -> bool {
         self.index.is_changed()
     }
 }
 
-/// Is this draw on the EYE's **far side** of its local water plane — the point-and-slack core.
-///
-/// The reference splits its transparents into the above-water and below-water lists and the
-/// frame interleave draws the eye's far side *before* the water pass (dry eye: below is far;
-/// submerged: above is — `0x4836d6`). Membership is `above ⇔ d ≥ −r` against the nearest
-/// **admitted** surface over the point's XY (claim from the nearest ancestor with a room
-/// verdict; `Unknown` admits both sources, still floor-bounded per pool). **No admitted surface
-/// ⇒ the above list** (`+0x19c == 0 → A = 1`, wow-re `water-frame-straddle.md` §2) — the NEAR
-/// side for a dry eye and the FAR side for a submerged one: shore content seen from under the
-/// water draws before the surface, so the surface tints it (0921's correction of 0911's
-/// "no surface → near").
-///
-/// `r` is the caller's lane law: the model bound-sphere slack for emitters and ribbons
-/// ([`model_far_side`]), `0` for the mesh lane's no-clip-planes fallback (`A = d ≥ 0`,
-/// `0x7079ed`; decision 0919).
+/// Is this draw on the eye's far side of its local water plane? The reference draws that side's
+/// transparents before the water pass (dry eye: below; submerged: above; `0x4836d6`). Above is
+/// `d ≥ −r` against the nearest admitted surface, and no surface counts as above (`+0x19c == 0`,
+/// `0x707a10`). `r` is the lane's slack: the model's bound radius for emitters and ribbons
+/// ([`model_far_side`]), 0 for meshes (`0x7079ed`).
 pub(crate) fn far_side_of_water_at(
     w: &WaterInterleave,
     claim_seed: Option<Entity>,
@@ -361,25 +277,16 @@ pub(crate) fn far_side_of_water_at(
     }
 }
 
-/// How high `point_world` sits over its local water plane — `d = point − surface` (WoW Z, yd;
-/// Bevy Y is the same axis) against the nearest **admitted** surface over the point's XY, the
-/// claim taken from the nearest ancestor of `claim_seed` with a room verdict (`Unknown` admits
-/// both sources, still floor-bounded per pool). `None` = no admitted surface — the reference's
-/// `+0x19c == 0`, which every lane reads as the above list.
-///
-/// The one plane query behind both laws: [`far_side_of_water_at`]'s one-list membership, and
-/// the straddle split's two-list band (`crate::straddle`, decision 2188), which also needs the
-/// plane's height itself for the clip.
+/// `d = point − surface` in yd against the nearest admitted surface over the point, the claim
+/// taken from `claim_seed`'s nearest ancestor with a room verdict; `None` without one.
 pub(crate) fn water_height(
     w: &WaterInterleave,
     claim_seed: Option<Entity>,
     point_world: Vec3,
 ) -> Option<f32> {
     let wow = benilla_assets::coords::bevy_to_wow(point_world);
-    // The spatial pre-filter first — these lanes ask per DRAW, and the full `surfaces_at` walk
-    // at that grain was the 2026-08-03 12-fps regression (`liquid::spatial`). No candidate
-    // surface over this XY (the dominant dry-land case) is "no admitted surface" under every
-    // claim, so the room walk below is skipped with the scan.
+    // The spatial pre-filter first (a full walk per draw is too slow); no candidate over this
+    // XY, the dry-land case, skips the room walk too.
     let candidates = w.index.over(wow[0], wow[1]);
     if candidates.is_empty() {
         return None;
@@ -401,8 +308,7 @@ pub(crate) fn water_height(
         .min_by(|a, b| a.abs().total_cmp(&b.abs()))
 }
 
-/// The mesh lane's wrapper: the sign test at the batch's own transform (r = 0) — the
-/// reference's no-clip-planes fallback, `model_render::classify_water_side`'s law (0919).
+/// The mesh lane's test, at the batch's own transform with r = 0.
 pub(crate) fn far_side_of_water(
     w: &WaterInterleave,
     claim_seed: Option<Entity>,
@@ -411,18 +317,10 @@ pub(crate) fn far_side_of_water(
     far_side_of_water_at(w, claim_seed, anchor_world, 0.0)
 }
 
-/// The emitter/ribbon lane: **the water side is the MODEL's** (byte-VERIFIED, wow-re
-/// `water-frame-straddle.md` §6 — the 0921 correction of 0911's per-emitter gloss). The type-4
-/// walk dots the plane ONCE per model in its prologue — `world_matrix × bound-box centre`,
-/// slack `r = |matrix row 0| × header sphere radius` — and every emitter of the model reads
-/// that one cached boolean (`[ebp-8]` at `0x7085fa`); the ribbon leg reads the model's side-A
-/// verbatim (`0x7081f1`). So a shoulder flame cannot blink at the waterline: the verdict rides
-/// the model's deep, stable bound centre with a whole radius of slack, never the bobbing bone.
-///
-/// `model` = the instance-root entity — the cloud ANCHOR field ("the MODEL, never the bone"),
-/// whose `GlobalTransform` is the instance matrix; `bound` = the asset's
-/// [`benilla_assets::ModelEmitter::water_bound`]. No resolvable matrix → the sign test at
-/// `fallback_point` (the emitter's live anchor), r = 0.
+/// The emitter and ribbon lanes' water side is the model's: the reference tests the plane once per
+/// model at `world_matrix × bound centre` with slack `|row 0| × sphere radius`, and every emitter
+/// reads that verdict (`0x7085fa`; ribbons `0x7081f1`). `model` is the instance root, `bound` its
+/// [`benilla_assets::ModelEmitter::water_bound`]; with no matrix, r = 0 at `fallback_point`.
 pub(crate) fn model_far_side(
     w: &WaterInterleave,
     model: Option<Entity>,
@@ -440,62 +338,35 @@ pub(crate) fn model_far_side(
     }
 }
 
-/// The membership law alone, pure for the unit test: `above ⇔ d ≥ −r` (the reference's
-/// `fcompp; test ah,0x41; jp` at `0x7084cf` — a tie at `d == −r` lands above; NaN lands below,
-/// which `>=` gives for free). `d` = point − surface (WoW Z), `r ≥ 0` the lane's slack.
+/// `d ≥ −r` (`0x7084cf`): a tie is above, NaN below.
 fn is_above(d: f32, r: f32) -> bool {
     d >= -r
 }
 
-/// Does a booth-layered emitter freeze this frame? The rule the body panes' item effects turn on
-/// (decision 1559), stated once because it was got wrong by being written inline.
-///
-/// A booth camera that is **asleep** — `gate_booth_cameras` put its pane's window away — draws
-/// none of this lane, so its emitters freeze with it: pool + age held, one frame's dt on
-/// re-entry, no catch-up. That is the draw-set law's own shape (the reference ticks an emitter
-/// only inside a draw the frame performs) and it is keyed on the reference's own cull.
-///
-/// A camera that is merely **rate-throttled** ([`super::ViewThrottled`]) is not asleep. Its scene
-/// is posing at full rate; `boothHalfRate` (decision 1444) is *our* pacing of the render, and a
-/// frame we chose to skip is not a frame the reference culled. Reading the two as one ran the
-/// body panes' item effects at half speed for as long as a pane was open — director report B312.
-///
-/// A **draining** emitter never freezes either way: its pool has to run out, and freezing one
-/// strands it forever (the world arm's rule further down).
-///
-/// **This is the camera's half of the answer, not the whole of it** — see [`scene_frozen`].
+/// Does a booth-layered emitter freeze this frame (the camera's half of [`scene_frozen`])? A
+/// sleeping booth camera freezes it, as the reference ticks an emitter only inside a draw; a
+/// rate-throttled one ([`super::ViewThrottled`]) does not, its scene still running at full rate. A
+/// draining pool never freezes, or it could never empty.
 fn booth_frozen(cam_active: bool, throttled: bool, draining: bool) -> bool {
     !cam_active && !throttled && !draining
 }
 
-/// Does this emitter's SCENE freeze it this frame? The whole law, in one place because it has two
-/// sources and having only one of them was a defect (decision 2046).
-///
-/// [`booth_frozen`] asks about a CAMERA, and that was exact for as long as one camera meant one
-/// scene: every booth before the `<Model>` tiles owned its own. The tile atlas broke the premise —
-/// every orthographic pane on the sheet renders through ONE camera on ONE layer, and that camera
-/// is deliberately kept active whenever any cell is packed, because it is the camera that CLEARS
-/// the atlas. So the camera bit answers "drawn" for every pane on the sheet, including the ones
-/// that left the paint list, and the question can only be answered by the owner — which is what
-/// [`super::ParticleEmitter::set_frozen`] is.
-///
-/// `booth` is `(cam_active, throttled)` for a booth-layered emitter, `None` for a world-lane one.
-/// A **draining** pool ignores both sources, for [`booth_frozen`]'s reason.
+/// Does this emitter's scene freeze it: its booth camera, or its owner
+/// ([`super::ParticleEmitter::set_frozen`]), since one tile-atlas camera draws many panes?
+/// `booth` is `(cam_active, throttled)`, `None` in the world; draining overrides both.
 fn scene_frozen(booth: Option<(bool, bool)>, owner_frozen: bool, draining: bool) -> bool {
     booth.is_some_and(|(cam_active, throttled)| booth_frozen(cam_active, throttled, draining))
         || (owner_frozen && !draining)
 }
 
-/// Per-frame: emit, integrate, and expand each emitter's pool into the shared effect-quad
-/// stream ([`super::buffer::EffectQuads`]).
+/// Per frame: emit, integrate and expand each emitter's pool into the shared stream.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 pub(super) fn simulate_particles(
     time: Res<Time>,
     tuning: Res<ParticleTuning>,
-    // The draw-set gate's scene inputs — the far-clip wall (0678) and the exterior window test
-    // (0786); see [`SceneGates`].
+    // The draw-set gate's scene inputs: the far-clip wall, the exterior-window test (the camera's
+    // own room exempt) and the portal PVS of the rooms inside a building.
     gates: SceneGates,
-    // The water-plane interleave inputs — see [`WaterInterleave`] and [`far_side_of_water`].
     interleave: WaterInterleave,
     mut commands: Commands,
     cam: Query<
@@ -510,8 +381,7 @@ pub(super) fn simulate_particles(
         With<WorldCamera>,
     >,
     owners: Owners,
-    // MODEL-particle instance entities ([`super::model`]): the draw-set gate hides them with
-    // their frozen emitter.
+    // Model-particle instances, hidden with their frozen emitter.
     mut child_draws: Query<
         (&mut Transform, &mut GlobalTransform, &mut Visibility),
         (
@@ -522,13 +392,10 @@ pub(super) fn simulate_particles(
     >,
     images: Res<Assets<Image>>,
     mut quads: ResMut<EffectQuads>,
-    // The ground-snap probe (file 0x2000 births): terrain + WMO/doodad geometry, the walking
-    // collision audience.
+    // The ground-snap probe (file 0x2000): the walking collision geometry.
     spatial: SpatialQuery,
-    // The two per-MODEL multipliers a cloud carries out of its owner (see [`OwnerMultipliers`]).
     owner_mul: OwnerMultipliers,
-    // `Without<WorldCamera>`: the `&mut GlobalTransform` must be provably disjoint from the
-    // camera read above too (an emitter never rides the camera entity).
+    // `Without<WorldCamera>` keeps the `&mut GlobalTransform` disjoint from the camera read.
     mut emitters: Query<
         (
             Entity,
@@ -542,10 +409,7 @@ pub(super) fn simulate_particles(
         ),
         Without<WorldCamera>,
     >,
-    // Booth cameras (decision 0539 §5): a booth-layered emitter (the glue scenes' braziers)
-    // billboards against ITS camera, matched by layer intersection — the `face_booth_billboards`
-    // rule. `Without<ParticleEmitter>`/`Without<ChildDraw>` keep the read provably disjoint from
-    // the `&mut GlobalTransform` writes above.
+    // Booth cameras: a booth-layered emitter faces its own, matched by layer.
     booth_cams: Query<
         (
             Entity,
@@ -561,25 +425,19 @@ pub(super) fn simulate_particles(
             Without<ChildDraw>,
         ),
     >,
-    // Hosted emitters' sequence source (the unit/GameObject lane): the host root's live
-    // `AnimationPlayer` names the playing sequence + clip time, same resolution as the
-    // material-alpha sampler (`doodad_anim::playing_seq`).
+    // A hosted emitter's sequence: its host's live `AnimationPlayer` slot and clip time.
     hosts: Query<(&AnimationPlayer, &benilla_assets::ModelAnimations)>,
-    // The lane's two debug instruments' plumbing, sharing one parameter (see [`super::dumps`]):
-    // `$WOW_PARTICLE_DEPTHDUMP` and `$WOW_EMIT_DUMP`. Both inert without their env.
     mut dumps: super::dumps::Dumps,
 ) {
     let Ok((world_cam, cam_tf, frustum, camera, projection, cam_local)) = cam.single() else {
         return;
     };
-    // Clamp dt so a load hitch doesn't fling every particle out of existence in one step.
+    // Clamped so a load hitch cannot fling every particle out in one step.
     let dt = time.delta_secs().min(0.1);
     if dt <= 0.0 {
         return;
     }
-    // Every input of an emitter's draw-set verdict, still since last frame: the verdict is then
-    // still too, and a gated emitter can skip its sphere/window/room tests outright — 2.4 k
-    // resident emitters against 11 active in a parked city (decision 1979's floor).
+    // No draw-set input moved: a gated emitter's verdict stands, and its tests can be skipped.
     let gate_inputs_still = !cam_tf.is_changed()
         && !projection.is_changed()
         && !cam_local.as_ref().is_some_and(|l| l.is_changed())
@@ -591,16 +449,11 @@ pub(super) fn simulate_particles(
     let (_, cam_rot, _) = cam_tf.to_scale_rotation_translation();
     let cam_right = cam_rot * Vec3::X;
     let cam_up = cam_rot * Vec3::Y;
-    // The far-clip wall's axis — the SAME forward `debug_panel::visibility` measures the owner
-    // doodad's own cull along, so an emitter and its owner cross the wall together.
+    // The far-clip axis the owner doodad's own cull uses, so the two cross the wall together.
     let cam_fwd = Vec3::from(cam_tf.forward());
-    // The far-clip wall, the exterior gate and the camera's own room — built once for the whole
-    // emitter walk, the same values the model visibility authority and `exterior_cull` ask
-    // (0784/0786: one spelling of the window test).
+    // Built once per walk, the same values the model visibility gate uses.
     let (farclip, exterior_gate, camera_instance) = gates.scene(Some((&*cam_tf, &*projection)));
-    // `$WOW_PARTICLE_DEPTHDUMP` (B16): is this a dump frame? Decided once per run.
     let dump_frame = dumps.depth_frame(time.elapsed_secs());
-    // `$WOW_EMIT_DUMP`: is this a dump tick? Decided once per frame, for the whole walk.
     let emit_dump = dumps.emit.due(time.elapsed_secs());
 
     for (
@@ -614,18 +467,13 @@ pub(super) fn simulate_particles(
         lit_by,
     ) in &mut emitters
     {
-        // The camera this emitter's quads face + its emission-LOD distance origin — and, in the
-        // shared lane, the view its draw record targets: a booth-layered emitter uses its
-        // booth's camera (decision 0539 §5 — the glue scenes' braziers, which the WORLD camera
-        // would billboard sideways and LOD from a nonsense distance); everything else the world
-        // camera.
+        // The camera the quads face, the LOD measures from and the draw targets: a booth-layered
+        // emitter's booth camera, else the world camera.
         let booth = layers
             .filter(|l| !l.intersects(&RenderLayers::default()))
             .and_then(|l| booth_cams.iter().find(|(_, _, cl, ..)| cl.intersects(l)));
         let is_booth = booth.is_some();
-        // The scene freeze ([`scene_frozen`]) — a sleeping booth camera, or an owner that froze
-        // this cloud because its scene's camera cannot say so. Same shape either way: pool + age
-        // held, no quads, model-instance entities hidden on the edge.
+        // A frozen scene holds pool and age, pushes no quads, and hides model instances once.
         if scene_frozen(
             booth.map(|(_, _, _, c, throttled)| (c.is_active, throttled)),
             emitter.frozen,
@@ -653,25 +501,11 @@ pub(super) fn simulate_particles(
             }
             None => (world_cam, cam_pos, cam_right, cam_up),
         };
-        // Draw-set gate (byte-verified, decision 0171): the reference ticks an emitter only when
-        // its owner doodad is in the frame's scene worklist — admission = the frustum sphere test
-        // + the radius-tiered distance-fade cutoff (`FUN_00683f80`; alpha ≤ 0 is never inserted).
-        // A culled owner's emitter neither simulates nor draws: pool + age FROZEN
-        // (`[obj+0x88]` accumulates nothing while absent), and on re-entry it resumes from frozen
-        // state with one frame's dt — no catch-up, no refill. All three tests use the owner's fade
-        // sphere, matching the reference's `[rec+0x68]`.
-        //
-        // The **far-clip** term is the third test and it is load-bearing (decision 0678, bug B39):
-        // the reference's frustum is bounded by its projection far plane at `farclip`, ours is not
-        // — our projection far is ~3000 yd so the WDL horizon can draw behind the wall, and
-        // `intersects_sphere`'s far-plane term would therefore bound at 3000, not 777. Worse, the
-        // fade cutoff alone bounds NOTHING for a big owner: `doodad_fade_alpha` returns a flat 1.0
-        // above `NEVER_FADE_RADIUS` (7 yd) — trees, buildings, the large fire props. So every
-        // big-doodad emitter used to simulate and draw at ANY distance out to the streaming
-        // residency, long past the wall its own owner's mesh had already been culled by. That is
-        // "all effects render at unlimited distance", and it is why the terrain under them was
-        // already gone. `within_farclip` is the same rule the owner mesh uses in
-        // `debug_panel::visibility` — shared, so the two can no longer drift apart.
+        // The draw-set gate: the reference ticks an emitter only while its owner doodad is in the
+        // frame's worklist, by frustum sphere and distance-fade cutoff (`0x683f80`; the sphere is
+        // `[rec+0x68]`). Outside it pool and age freeze (`[obj+0x88]` accumulates nothing) and
+        // resume with one frame's dt. The far-clip term is needed: our projection's far plane is
+        // past `farclip`, and owners over `NEVER_FADE_RADIUS` never fade.
         if let Some(f) = fade.as_ref() {
             if emitter.gated && gate_inputs_still && !f.is_changed() {
                 continue;
@@ -680,8 +514,7 @@ pub(super) fn simulate_particles(
                 cam_pos,
                 cam_fwd,
                 farclip,
-                // Lateral planes only (`intersect_far = false`) — the depth bound is the farclip
-                // term inside `in_draw_set`, deliberately; see `view::within_farclip`.
+                // Lateral planes only: the depth bound is the farclip term.
                 frustum.intersects_sphere(
                     &CullSphere {
                         center: f.center.into(),
@@ -689,19 +522,13 @@ pub(super) fn simulate_particles(
                     },
                     false,
                 ),
-                // …and the exterior-window term (0786): standing in a WMO interior, a doodad
-                // outside is not in the worklist at all, so its emitter neither ticks nor draws —
-                // which the mesh gate already knew and this one did not.
+                // From inside a WMO, a doodad outside is not in the worklist.
                 f.exterior_admitted(&exterior_gate, camera_instance),
-                // …and the room term (0689/1289): the window above admits a whole BUILDING, which
-                // says nothing about the sealed room the owner prop actually stands in. The mesh
-                // gate has always known this one too, through the prop's own `WmoGroupVis`.
+                // The window admits a whole building, not the sealed room the prop stands in.
                 gates.room_admits(f),
             );
             if !in_set {
-                // Frozen: the pool writes no quads this frame (the shared stream is cleared
-                // per frame, so "not pushed" IS "not drawn"); model-instance entities mirror
-                // the gate on its edge, as the old entity-visibility flip did.
+                // Frozen: nothing pushed is nothing drawn; model instances hide once.
                 if !emitter.gated {
                     emitter.gated = true;
                     for slot in &emitter.model_instances {
@@ -716,46 +543,17 @@ pub(super) fn simulate_particles(
             }
             emitter.gated = false;
         } else if !is_booth && !emitter.draining {
-            // ENTITY-owned emitters (creatures, GameObjects, spell kits, WMO-prop deck lanterns)
-            // carry no `EmitterFade`, and the premise that excused them — "the population is
-            // bounded by server visibility instead" (`entities::wmo_props`) — is FALSE for
-            // transports, which vmangos streams map-wide. Measured (decision 0678): parked in
-            // Durotar, **56 emitters** were ticking and drawing at 4853–7080 yd — the deck
-            // lanterns of the Teldrassil↔Auberdine boat (`transports` 176244 "Moonspray") and its
-            // Menethil↔Auberdine neighbour, five to seven kilometres away. So the wall is applied
-            // to EVERY world-lane emitter, not just the faded ones. That is also the faithful
-            // shape: the reference ticks particles inside the owning model's animate step, which
-            // runs only for models the frame actually draws — and past `farclip` nothing is drawn.
-            //
-            // Three deliberate exclusions, each of which would be a bug the other way:
-            // - **booth-layered** emitters (glue/portrait scenes) — parked thousands of yards away
-            //   and drawn by their OWN camera, so the world wall says nothing about them;
-            //   `glue_booth` states the contract outright ("a glue scene always ticks").
-            // - **draining** emitters — freezing one strands it: it can never empty its pool, so it
-            //   never reaches the self-despawn below and leaks for the session.
-            // - an emitter whose **owner has vanished** — `subject` is `None`, so it falls through
-            //   to the drain path below rather than freezing before that can be noticed.
-            //
-            // The subject is read LIVE from the owner's transform, never from the stored anchor: a
-            // frozen emitter stops refreshing its anchor, so gating on the stored one would latch a
-            // moving owner out of existence the first time it crossed the wall.
+            // Entity-owned emitters carry no `EmitterFade`, and vmangos streams transports
+            // map-wide, so the far-clip wall applies to them too: the reference ticks particles
+            // only in the animate step of a model the frame draws. Exempt: booth emitters (their
+            // own camera), draining ones (a frozen pool never empties), a vanished owner (it
+            // drains). The subject is the owner's live position.
             let subject = match emitter.owner {
                 Some(o) => owners.at(o),
                 None => Some(emitter.anchor_pos),
             };
-            // **…and the owner's own draw verdict** (decision 1409). An emitter entity is a world
-            // root — `spawn_emitter` parents it to nothing, because its cloud is anchored, not
-            // carried — so every hide that reaches its model through the scene graph reaches the
-            // emitter not at all. The reference has no such gap: it ticks a model's particles
-            // inside that model's animate step, which runs only for models the frame draws. Ours
-            // ran regardless, which is a culled GameObject's fire still burning over bare ground —
-            // the Orgrimmar bonfires, flame and smoke intact with the wood gone. The world lane's
-            // `EmitterFade` says this in its own vocabulary (terms 4/5); the entity lane has no
-            // fade sphere to say it with, and its owner's propagated verdict is the same answer.
-            //
-            // `InheritedVisibility` is last propagate's — one frame of lag on a verdict that holds
-            // for as long as the model is culled — and an owner we cannot read falls through to the
-            // drain path below, exactly like a vanished one.
+            // And the owner's own draw verdict: an emitter is a world root, so a hide on its
+            // model's hierarchy never reaches it.
             let owner_hidden = emitter.owner.is_some_and(|o| owners.hidden(o));
             if let Some(at) = subject {
                 if owner_hidden || !crate::view::within_farclip(farclip, cam_pos, cam_fwd, at, 0.0)
@@ -809,12 +607,8 @@ pub(super) fn simulate_particles(
             frozen: _,
             clip,
         } = &mut *emitter;
-        // The water-interleave MODEL frame, captured before the draw-anchor local shadows the
-        // `anchor` field below: the cloud anchor is "the MODEL, never the bone" — its transform
-        // is the instance matrix the classification dots (`model_far_side`), and the room walk
-        // starts there too. The owner (possibly a JOINT) only seconds it as the walk seed when
-        // no anchor exists — a joint's transform is not the instance matrix, so that leg keeps
-        // the sign-test fallback (`water_gt = None`).
+        // The water test's model frame, before `anchor` is shadowed: the instance root. A joint
+        // owner only seeds the room walk, as a joint's transform is not the instance matrix.
         let water_model = (*anchor).or(*owner);
         let water_gt = (*anchor).and_then(|e| owners.transforms.get(e).ok().copied());
         let water_bound = *water_bound;
@@ -833,33 +627,20 @@ pub(super) fn simulate_particles(
             },
             None => (*seq, *age),
         };
-        // This frame's emitter PARAMETERS — the nine per-frame-sampled channels, on the same
-        // clock as the rate track (the reference's `m2_animate` emitter phase samples all ten;
-        // wow-re `part-emission-rate-animated.md` §1). Frost Nova rides its emission radius
-        // 0.19 → 13.2 yd out with the ring; Arcane Explosion 0 → 7.2 yd with the dome — births
-        // MUST read the frame's values, not `value[0]` (decision 0844).
-        // The instance's gseq cursor (0856/0858): the spawn age IS `sceneNow − attach` — the
-        // emitter spawns with its instance, and every lane's instance is fresh per play.
+        // The global-sequence cursor: the spawn age is `sceneNow − attach`.
         let gseq_now = f64::from(*age);
-        // Anchored mode (see [`Particle`]): positions are emitter-relative, so tracking a moving
-        // owner needs nothing beyond refreshing `placement` — the cloud rides the anchor for free
-        // (the reference's per-frame `translate(−emitterPos)` draw-matrix rebuild).
+        // `anchored` is world mode (file flag `0x10` clear); see [`Particle`].
         let anchored = !def.model_space();
 
-        // 0. If this emitter follows a streamed owner (creature/GameObject/joint), track its world
-        //    transform — or DRAIN once the owner is gone (missile impacted, effect reaped, unit
-        //    streamed out): the pool finishes its lifespans at the frozen placement, then the
-        //    emitter despawns itself. An instant despawn here popped every live particle of a
-        //    fireball's trail at the moment of impact.
+        // 0. Track a streamed owner's transform; once it is gone, free or drain per
+        //    `on_owner_loss`.
         if let Some(o) = *owner {
             match owners.transforms.get(o) {
                 Ok(gt) => *placement = gt.compute_transform(),
                 Err(_) => {
                     *owner = None;
                     match *on_owner_loss {
-                        // The owner MODEL is gone, so its effects go with it — the reference frees
-                        // a model's emitters at its dtor (decision 0826). Nothing to drain: an
-                        // unequipped torch's flame does not stay behind in the air.
+                        // The reference frees a model's emitters in its destructor: nothing drains.
                         OwnerLoss::Free => {
                             for slot in model_instances.iter() {
                                 for (e, _) in &slot.meshes {
@@ -871,10 +652,7 @@ pub(super) fn simulate_particles(
                         }
                         OwnerLoss::Drain => {
                             *draining = true;
-                            // The ghost-cloud event, named so a run can count it: this pool now
-                            // lives out its lifespans FROZEN in world space. Right for an effect
-                            // that ended in place (a missile impact), and the reason `Free` exists
-                            // for everything that is a model teardown.
+                            // The pool lives out its lifespans in place, like a missile's impact.
                             if !particles.is_empty() {
                                 debug!(
                                     "fx orphan: emitter {entity} ({}) lost its owner with {} \
@@ -900,13 +678,8 @@ pub(super) fn simulate_particles(
             commands.entity(entity).despawn();
             continue;
         }
-        // Dormant (decision 1979) — judged AFTER the owner-loss and drain-complete blocks above,
-        // which are the emitter's lifetime and must run every frame (review of 2026-09-04: a
-        // one-shot whose owner despawned never drained and lived for the session). Nothing
-        // alive, nothing draining, and the timing tracks say
-        // the emitter is not emitting at this clock — every placement, ride and water step
-        // below would compute state for zero particles. The clock derivation above already
-        // ran (it is what `emitting` reads, and `seq` must keep following the host).
+        // Dormant: nothing live, nothing draining, not emitting at this clock. Judged after the
+        // owner-loss and drain blocks and the clock, which must run every frame.
         if particles.is_empty()
             && !*draining
             && children.iter().all(|c| c.particles.is_empty())
@@ -914,17 +687,11 @@ pub(super) fn simulate_particles(
         {
             continue;
         }
-        // The MODEL's render alpha for this frame (decision 0827 — the reference's per-frame
-        // `emitter+0x1a8 = Model+0x19c` copy at `0x718960` @`0x719073`). Two disjoint sources, the
-        // same slot the reference writes both through: an entity-owned cloud takes its OWN model
-        // instance's composed alpha ([`crate::model_fade::ModelAlphas`] walks the attached-model
-        // chain, so a weapon glow's reaches the item's and the item's the wearer's — 0833), and a
-        // placed doodad's takes its own distance fade, whose cutoff the draw-set gate above
-        // already applies as a hard stop.
+        // The model's render alpha (`emitter+0x1a8 = Model+0x19c`, `0x718960` at `0x719073`): an
+        // entity cloud's composed model alpha, or a placed doodad's distance fade.
         *alpha = alpha_src.map_or(1.0, |e| owner_mul.alpha(e))
             * fade.as_ref().map_or(1.0, |f| f.distance_alpha(cam_pos));
-        // The cloud anchor (see the field doc): the model's live translation, or the last-known
-        // one while the pool drains. A whole-model owner keeps anchor == owner — identical math.
+        // The model's live translation, or the last known while the pool drains.
         match *anchor {
             Some(a) => {
                 if let Ok(gt) = owners.transforms.get(a) {
@@ -934,15 +701,11 @@ pub(super) fn simulate_particles(
             None if owner.is_none() => *anchor_pos = placement.translation,
             None => {} // joint-owned, unanchored (placed doodads): the spawn placement stands
         }
-        // `$WOW_EMIT_DUMP`'s subject: the model this cloud belongs to, captured here because
-        // `anchor` is shadowed by the draw anchor further down.
+        // `$WOW_EMIT_DUMP`'s model, taken before `anchor` is shadowed below.
         let dump_owner = (*host).or(*anchor);
 
-        // 0a. THE RIDE FRAME (`[CM2Model+0x17c]`, decision 1591) — which transport, if any, this
-        //     cloud's MODEL is standing on. Inherited down the `ParentModel` chain, so a held
-        //     weapon's sparkle takes its wearer's deck without either spawn site knowing.
-        //     A transport that has streamed out reads as no frame: that is the leave leg, and it
-        //     hands the cloud back to the world where it stood.
+        // 0a. The ride frame (`[CM2Model+0x17c]`): the transport the model stands on, inherited
+        //     down the `ParentModel` chain; one that streamed out reads as none.
         let deck = anchor
             .or(*owner)
             .and_then(|model| owners.rides.source(model))
@@ -953,13 +716,10 @@ pub(super) fn simulate_particles(
                     .ok()
                     .map(|gt| (t, crate::ride_frame::ride_matrix(gt)))
             })
-            // MODEL mode takes the reference's verbatim-copy arm at birth and ignores `[ebp+8]`
-            // at draw (`0x7b518e`/`0x7b3ef9`): it already rides its host rigidly, so `A` would
-            // ride it a second time.
+            // Model mode ignores the ride frame (`0x7b518e`, `0x7b3ef9`): it rides its host.
             .filter(|_| anchored);
-        // Boarding and leaving RE-EXPRESS every already-live particle — position and velocity
-        // (`0x7187f0` → `0x7b5e60`) — rather than snapping the cloud. Riding a *moving* deck folds
-        // nothing: the draw's live `A` is what carries it.
+        // Boarding and leaving re-express every live particle (`0x7187f0` → `0x7b5e60`); a
+        // moving deck folds nothing, the draw's live `A` carries it.
         if let Some(fold) = ride.retarget(deck) {
             let rot = Quat::from_mat3a(&fold.matrix3);
             for p in particles
@@ -969,23 +729,13 @@ pub(super) fn simulate_particles(
                 p.pos = fold.transform_point3(p.pos);
                 p.vel = rot * p.vel;
             }
-            // The emitter-motion state is stored-frame too, and it must cross the seam with the
-            // cloud: the Δ that keys the follow and inherit terms is a DIFFERENCE against last
-            // frame's origin, so leaving a stale one behind would read the frame change itself as
-            // ~1300 yd of emitter motion — one frame of `fraction` pinned at 1.0, which teleports
-            // the whole cloud on the step onto the lift. (The reference's `0x7b5e60` re-expresses
-            // "already-committed state" under the new parent; whether its `rt+0x248` is inside
-            // that is not settled at the bytes, and reproducing a one-frame pop would be building
-            // past the evidence either way.)
+            // The emitter-motion state crosses too, or the frame change reads as motion; whether
+            // the reference's `0x7b5e60` re-expresses `rt+0x248` is untraced.
             *emitter_prev = emitter_prev.map(|prev| fold.transform_point3(prev));
             *inherit_vel = rot * *inherit_vel;
         }
-        // The emitter matrix every birth is baked through: `rt+0x1fc = srcMx · A⁻¹` (`0x7b51b0`).
-        // Dividing the ride frame out HERE is what makes the whole rest of this system correct
-        // without a single further change — births, the child fold, the emitter-motion Δ, the
-        // inherit velocity and the kill-outbound origin all compose off this one transform, and
-        // all of them want the deck's frame while riding. `placement` itself stays WORLD: the
-        // emission LOD, the water-plane side and the model-mode draw are all world questions.
+        // Births bake through `rt+0x1fc = srcMx · A⁻¹` (`0x7b51b0`), so the stored-frame terms
+        // below are deck-relative; `placement` stays world for the LOD, water side and model draw.
         let emit_place = match ride.matrix() {
             Some(a) => {
                 let inv = a.inverse();
@@ -998,28 +748,17 @@ pub(super) fn simulate_particles(
             None => *placement,
         };
 
-        // 0b. The EMITTER-MOTION terms (wow-re `part-emitter-motion.md`, byte-verified): both
-        //     feed off the emitter origin's one-frame live world Δ. prevPos refreshes EVERY
-        //     frame (the reference's rt+0x248 @`0x7b5265`), so even a multi-frame inherit
-        //     window measures a single frame's motion. Consumption folds the world vector into
-        //     the particles' STORED frame exactly like a birth velocity: attach-local for
-        //     anchored mode; for model mode the reference adds the raw world vector to LOCAL
-        //     coords (a frame quirk) — we fold it into the local frame instead, since our
-        //     world axes are Bevy's, not WoW's (translation-dominant content is equivalent).
-        // In the STORED frame, deliberately: the reference's `rt+0x22c` is the translation row of
-        // `rt+0x1fc`, which already has `A⁻¹` folded in — so on a deck a rider standing still has
-        // no emitter motion at all, and the follow/inherit terms key off deck-relative speed.
+        // 0b. The emitter-motion terms feed off the origin's one-frame Δ in the stored frame
+        //     (`rt+0x22c`, the translation row of `rt+0x1fc`), refreshed every frame (`rt+0x248`,
+        //     `0x7b5265`). Deviation: in model mode the reference adds the raw world vector to
+        //     local coordinates; we fold it into the local frame, because our world axes are
+        //     Bevy's, not WoW's.
         let emitter_world = emit_place.transform_point(wow_to_bevy(def.position));
         let emitter_delta = emitter_prev.map_or(Vec3::ZERO, |prev| emitter_world - prev);
         *emitter_prev = Some(emitter_world);
-        // NOTE on the R(+Z,90°) emitter-frame law (`emit_local`'s tail): we apply R at EMISSION,
-        // so stored vectors are already post-R and every stored↔world fold here stays R-free —
-        // unlike the reference, which stores pre-R and folds R inside its draw matrix. The two
-        // compositions are equivalent; ours keeps a single application point.
-        // World → the particles' STORED frame. In world mode (`0x10` CLEAR) the store IS world,
-        // so this is the identity — the whole point of 1585: no live matrix is ever re-applied to
-        // an already-born particle, so nothing the host does afterwards (translate, turn, or play
-        // an animation that swings the emitter's bone) can reach it.
+        // R(+Z, 90°) is applied at emission, so stored vectors are post-R and these folds R-free;
+        // the reference folds it in its draw matrix, an equivalent composition.
+        // World to the stored frame: the identity in world mode.
         let to_stored = |world: Vec3, placement: &Transform| {
             if anchored {
                 world
@@ -1029,17 +768,13 @@ pub(super) fn simulate_particles(
                 ))
             }
         };
-        // The per-frame follow-delta ([`follow_fraction`]), folded into the stored frame and added
-        // to every live particle after its first integrate (the fresh-bit skip). The ride-vs-trail
-        // baseline is not here — the storage space supplies it (1585).
         let fraction = follow_fraction(def, emitter_delta.length() / dt);
         let follow = if fraction == 0.0 || emitter_delta == Vec3::ZERO {
             Vec3::ZERO
         } else {
             to_stored(fraction * emitter_delta, &emit_place)
         };
-        // VELOCITY INHERIT (file 0x40): the ~30 Hz trigger holds the inherit velocity births
-        // read; the live gate (rt+0x64) zeroes it while nothing is live.
+        // Velocity inherit (file 0x40): the 30 Hz trigger, zeroed with nothing live (rt+0x64).
         if def.inherits_emitter_motion() {
             inherit_trigger(
                 inherit_accum,
@@ -1051,33 +786,16 @@ pub(super) fn simulate_particles(
             );
         }
 
-        // The sequence clock (`EmitTiming`, decision 0641's structure one channel over): a HOSTED
-        // emitter reads its host's live playing sequence + clip time each frame — the reference's
-        // `m2_animate` emitter phase samples the CURRENT sequence record, which is why a quest
-        // GameObject's explosion fires in its one-shot clips and reads OFF in every idle window
-        // (bug B27). A host with no live player yet keeps its last slot at that slot's opening
-        // pose. Pinned lanes (doodads, effect rigs, booths) run their slot on the spawn-age
-        // clock; the baked loops wrap a looping band and end-hold a clamped one.
+        // Every track samples per frame on the current sequence's clock (`0x714260`): a hosted
+        // emitter's host's playing sequence and clip time, else its slot on the spawn-age clock.
+        // Births read the frame's values (Frost Nova's radius grows with its ring).
         let now = def.params.sample(clock_seq, elapsed_s, gseq_now);
 
-        // 1. Age + integrate the live pool. The verified vanilla integrator (`particle_integrate`
-        //    @ 0x7b2680): pos += dt·v with the gravity term on the UP axis (up += dt·v_up − ½·g·dt²;
-        //    v_up −= g·dt), then **drag**: v −= min(dt·drag, 1)·v (exponential velocity decay,
-        //    applied after gravity). Drag is load-bearing — a fast, long-lived, zero-gravity jet
-        //    (e.g. the CandelabraTallWall flame: speed 0.56, life 6, g 0, drag 10) relies on it to
-        //    stay a ~0.06 yd flicker; without it the particle coasts 3.3 yd to the ceiling. The
-        //    frame decides the up axis: WoW +Z in model mode, Bevy +Y in world mode (the math is
-        //    frame-independent otherwise — the reference integrates world-space particles with the
-        //    same kernel). Kill at age ≥ the particle's birth-sampled life. Gravity is a LIVE
-        //    per-frame emitter field (the integrator reads it each frame in the reference).
+        // 1. Integrate the live pool ([`integrate_particle`]): up is WoW +Z in model mode and Bevy
+        //    +Y in world mode; gravity is read live each frame, as the reference does.
         let g = now.gravity;
         let drag = def.drag;
-        // Sphere KILL-OUTBOUND emitters: the emitter origin in the stored frame — `def.position`
-        // composed exactly like a birth (world mode: the live world point, which is
-        // `emitter_world` itself; model mode: raw local). Every corpus author converges inward
-        // (negative speed); this is what stops the stream at the centre instead of spraying it
-        // out the far side. This one term is read LIVE in world mode by design: it is the
-        // emitter's current origin, not a birth property of any particle.
+        // Kill-outbound: the emitter's live origin in the stored frame, composed like a birth.
         let kill_origin = def.kill_outbound().then(|| {
             if anchored {
                 emitter_world
@@ -1095,24 +813,11 @@ pub(super) fn simulate_particles(
         };
         particles.retain_mut(|p| integrate_particle(p, &env));
 
-        // 2. Emit new particles — the owed-birth count comes from [`accumulate_emission`]
-        //    (continuous `rate·dt` pour, or a BURST emitter's one rising-edge puff — the emission
-        //    model split of wow-re `part-emission-burst-flag.md`). The rate is the keyed track
-        //    STEP-sampled at the emitter's clip clock — how a one-shot effect's emitters (rate
-        //    `0 → 200 → 0` over the first 133 ms, the blood spurt's starflash) fire at their
-        //    authored moment; constant ambient tracks are unaffected. Floored at 0 (a track tail
-        //    may legitimately go negative). Birth position/velocity come from the shape kernel
-        //    ([`emit_local`], wow-re `part-shape-kernels.md`).
-        //    Within the draw set the reference has NO particle-side distance cull or fade (wow-re
-        //    `part-distance-density.md`; population is bounded by the OWNER draw-set gate above —
-        //    decision 0171). Its one distance mechanism is this emission LOD (`0x7b5550`,
-        //    byte-verified): spawn count × clamp(1 − (camDist − 50)·0.02, 0.25, 1.0) — full rate
-        //    inside 50 yd, linear falloff, a 25% floor from 87.5 yd out, never zero — and × the
-        //    `particleDensity` CVar.
-        //    The enabled M2Track (file +0x1dc) gates NEW emission on the same clock — the
-        //    one-shot effects' choreography (a 200 ms hand flash inside a 1.0 s clip; the impact
-        //    model's six staggered windows). Live particles are untouched — they finish their
-        //    lifespans exactly like the drain above.
+        // 2. Emit: [`accumulate_emission`] owes births from a continuous pour or a burst's rising
+        //    edge (`0x718ec8`), at the rate track step-sampled on the clip clock; the enabled track
+        //    (file +0x1dc) gates new births only. The reference's one particle distance mechanism
+        //    is this emission LOD (`0x7b5550`): × clamp(1 − (camDist − 50)·0.02, 0.25, 1), then
+        //    × `particleDensity`.
         let emitting = !*draining && def.timing.emitting(clock_seq, elapsed_s, gseq_now);
         let rate = def.timing.rate(clock_seq, elapsed_s, gseq_now);
         let dist_lod =
@@ -1134,12 +839,9 @@ pub(super) fn simulate_particles(
             let (base, dir) = emit_local(def, &now, rng);
             let speed =
                 now.emission_speed * (1.0 + now.speed_variation * (rand01(rng) * 2.0 - 1.0));
-            // WORLD mode (`0x10` CLEAR) bakes the birth all the way into world through the live
-            // emitter matrix — the reference's `0x7b8b0f 0x7bca80(pos, E)` (with translation) and
-            // `0x7b8acf 0x7bcb40(vel, E)` (3×3). `placement` is the emitter's BONE transform in
-            // world, so `transform_point` is that matrix. Nothing is stored relative to anything
-            // that can later move. MODEL mode (`0x10` SET) stores raw emitter-local and the draw
-            // re-applies the live matrix instead (`0x7b8aa5`/`0x7b3efb`).
+            // World mode (`0x10` clear) bakes a birth into world through the live emitter matrix
+            // (`0x7b8b0f` → `0x7bca80`, `0x7b8acf` → `0x7bcb40`); model mode stores it local and
+            // the draw re-applies the matrix (`0x7b8aa5`, `0x7b3efb`).
             let (mut pos, vel) = if anchored {
                 (
                     emit_place.transform_point(wow_to_bevy(base.to_array())),
@@ -1149,16 +851,11 @@ pub(super) fn simulate_particles(
             } else {
                 (base, dir * speed)
             };
-            // GROUND SNAP (file 0x2000, [`benilla_formats::ParticleEmitterDef::ground_snap`]):
-            // at spawn only, world mode only, probe 20 yd straight down against terrain/WMO/
-            // doodad geometry (the walking collision audience — the reference's 0x100111 flag
-            // set); on a hit the particle stands ON the surface, lifted by its birth over-life
-            // SIZE. A miss leaves the spawn position untouched. `pos` is already world here, so
-            // the probe reads and writes it directly.
+            // Ground snap (file 0x2000): at birth, in world mode, a 20 yd probe down against the
+            // walking collision (the reference's flags `0x100111`) sets a hit particle on the
+            // surface, lifted by its birth size.
             if anchored && def.ground_snap() {
-                // The probe is a WORLD query against world geometry, so it runs on the world
-                // point and the answer comes back into the store (1591 — the identity off a
-                // transport). The drop is along world down, which a yaw-only `A` leaves alone.
+                // Probed at the world point and stored back; a yaw-only `A` keeps world down.
                 let world = ride.to_world(pos);
                 if let Some(hit) = spatial.cast_ray(world, Dir3::NEG_Y, 20.0, true, &snap_filter) {
                     pos = ride.to_stored(
@@ -1166,22 +863,16 @@ pub(super) fn simulate_particles(
                     );
                 }
             }
-            // VELOCITY INHERIT consumption (the shape kernels' closing block, gated on the
-            // flag): `vel += (1 + S11·speedVariation) · inherit`, its own S11 draw, in the
-            // stored frame (the block runs after the reference's space fold).
+            // Inherit (the kernels' closing block): `vel += (1 + S11·speedVariation) · inherit`.
             let vel = if def.inherits_emitter_motion() && *inherit_vel != Vec3::ZERO {
                 vel + (1.0 + now.speed_variation * rand_s11(rng))
                     * to_stored(*inherit_vel, &emit_place)
             } else {
                 vel
             };
-            // MODEL PARTICLES (wow-re `part-model-particles.md` §b): seed the instance
-            // orientation from the birth fold (the reference's transposed spawn-basis
-            // mat3→quat — the transpose is the row/column-major convention fold; net, the
-            // basis rotation) and roll the tumble with the VERIFIED asymmetry: only X honors
-            // `min + u·range`, Y/Z multiply a raw [1,2) mantissa by their range alone (their
-            // authored min is dead — a faithful original-client quirk). Flag 0x200 sign-flips
-            // each axis independently.
+            // Model particles (`0x7b2420`): orientation from the birth basis; the tumble's X is
+            // `min + u·range`, but Y and Z are a [1, 2) mantissa times the range, their min
+            // unused, as the reference rolls them.
             let (quat, angvel) = if def.geometry_model.is_some() {
                 let amin = def.angular_velocity_min;
                 let amax = def.angular_velocity_max;
@@ -1197,9 +888,7 @@ pub(super) fn simulate_particles(
                         }
                     }
                 }
-                // The seed basis is the R(+Z,90°)-prepended spawn matrix (`emit_local`'s law
-                // note): WoW local +Ẑ is Bevy +Ŷ under the 0002 map, so R rides as a +90°
-                // yaw appended to the frame rotation in both modes.
+                // R(+Z, 90°) is a +90° turn about Bevy +Y, appended to the frame rotation.
                 let r90 = Quat::from_rotation_y(std::f32::consts::FRAC_PI_2);
                 let quat = if anchored {
                     emit_place.rotation * r90
@@ -1223,14 +912,10 @@ pub(super) fn simulate_particles(
             });
         }
 
-        // 2b. CHILD emitters (wow-re `part-child-recursion.md`): each drives off the live pool
-        //     — post-integration, post-birth, exactly the window the reference's per-particle
-        //     child loop sees — with the child's OWN rate/enabled tracks on its own model's
-        //     slot-0 clock (a recursion model has no host of its own; the parent's age drives).
-        //     A draining parent stops driving; child pools live out their spans (the despawn
-        //     above waits for them).
+        // 2b. Children (`0x7b5550`) drive off the post-birth pool on their own tracks, slot 0 on
+        //     the parent's age; a draining parent stops driving them.
         for child in children.iter_mut() {
-            // A child cloud is its own fresh instance: its gseq cursor is its own age (0856).
+            // A child cloud is its own fresh instance: its gseq cursor is its own age.
             let c_emitting = !*draining && child.def.timing.emitting(None, *age, f64::from(*age));
             let c_rate = child.def.timing.rate(None, *age, f64::from(*age));
             let c_now = child.def.params.sample(None, *age, f64::from(*age));
@@ -1258,23 +943,15 @@ pub(super) fn simulate_particles(
                 .retain_mut(|p| integrate_particle(p, &c_env));
         }
 
-        // 3. Expand each pool into the shared effect-quad stream — per pool, only once its
-        //    texture is resident. While one streams (or failed to decode), the pool pushes
-        //    nothing rather than flash the engine fallback through the additive blend. An idle
-        //    pool pushes nothing and commits nothing — the old "don't rewrite an already-empty
-        //    mesh" guard is now the structure itself.
-        // The cloud's anchor: the emitter's live position — the draw record's SORT point (the
-        // transparent-phase depth this cloud takes; see `super::buffer`). Still published to
-        // the entity transform: the census probe and phase instruments read the anchor there.
+        // 3. Expand each pool once its texture is resident, never the fallback. The anchor is
+        //    the draw's sort point, also published on the entity for the instruments.
         let anchor = if anchored {
             *anchor_pos
         } else {
             placement.translation
         };
         entity_tf.translation = anchor;
-        // Post-propagation frame (we're post-palette in PostUpdate) — publish directly so any
-        // same-frame reader sees THIS frame's anchor (the `face_billboards` exactness rule;
-        // emitter entities live at the world root, so the direct write is exact).
+        // Written directly for same-frame readers: we run after propagation, at the world root.
         *entity_global = GlobalTransform::from(*entity_tf);
         let frame = DrawFrame {
             anchored,
@@ -1286,22 +963,10 @@ pub(super) fn simulate_particles(
             right: e_right,
             up: e_up,
         };
-        // A GEOMETRY (model-particle) emitter never draws quads — the reference's render
-        // dispatch skips the whole quad path when the model mode is on; its instances
-        // render via [`super::model::update_model_particles`].
+        // A geometry emitter draws instances ([`super::model`]), never quads.
         let want_quads = def.geometry_model.is_none() && images.contains(&*texture);
-        // Every effect of one model takes the SAME rung (0719/0721) — computed here per frame,
-        // where it used to be baked into the material's `depth_bias` at spawn. Plus the
-        // water-plane interleave ([`far_side_of_water`]): a cloud on the eye's far side of its
-        // local water plane drops under the water pass, so the surface paints over it — the
-        // swimming-enchant erase was these two sorting by raw view-z and flipping with camera
-        // angle. Booth emitters belong to their own camera and take no world rung.
-        // Classified at the MODEL — its transformed bound centre with the bound-radius slack —
-        // never at the emitter's live position: the reference dots the plane once per model in
-        // the walk prologue and every emitter reads that verdict (byte-VERIFIED, 0921 correcting
-        // 0911's per-emitter reading of `0x7084a0`). This is what makes a shoulder flame stable
-        // at the waterline: the bobbing bone doesn't enter, and the whole cloud only flips when
-        // the model's centre is a full radius under.
+        // One rung for every effect of a model, plus the water interleave: a cloud on the eye's
+        // far side sorts under the water pass, classified once per model (`0x7084a0`).
         let far = !is_booth
             && model_far_side(
                 &interleave,
@@ -1310,9 +975,7 @@ pub(super) fn simulate_particles(
                 water_bound,
                 placement.translation,
             );
-        // The classification's own trace (`WOW_MOVE_TRACE_TAGS=fx`): which clouds dropped under
-        // the water pass this frame — the numeric read for "the swimmer's enchant survives the
-        // surface", where a pixel can't say which side a draw sorted to.
+        // Trace tag `fx`: which clouds sorted under the water pass this frame.
         if far && !particles.is_empty() && benilla_assets::trace::enabled() {
             benilla_assets::trace::line(
                 "fx",
@@ -1335,10 +998,7 @@ pub(super) fn simulate_particles(
         if want_quads && !particles.is_empty() {
             expand_quads(def, particles, &frame, placement, &cam, &mut quads.verts);
         }
-        // `$WOW_PARTICLE_DEPTHDUMP` (B16): the depth numbers this pool brings to the compare —
-        // now over the quads THIS frame just wrote (the exact vertices the draw will consume).
-        // Booth emitters are skipped — their pixels belong to a booth camera's target, not the
-        // world depth buffer `WOW_DEPTH` reads.
+        // `$WOW_PARTICLE_DEPTHDUMP` over the quads just written; booths draw to their own target.
         if let Some(fidx) = dump_frame {
             if !is_booth
                 && def.geometry_model.is_none()
@@ -1351,8 +1011,7 @@ pub(super) fn simulate_particles(
                     particles,
                     &frame,
                     placement,
-                    // The instrument's frame is the world's, so hand it the world point (the
-                    // sim's own `emitter_world` is the STORE's origin — 1591).
+                    // The world point: `emitter_world` is in the stored frame.
                     ride.to_world(emitter_world),
                     &cam,
                     &cam_tf,
@@ -1363,9 +1022,7 @@ pub(super) fn simulate_particles(
                 );
             }
         }
-        // `$WOW_EMIT_DUMP`: what this emitter's front end decided this frame — the resolved
-        // sequence slot and what the ten tracks sampled at it. Placed here so `live` is the
-        // count AFTER this frame's births, i.e. what the draw below actually consumes.
+        // `$WOW_EMIT_DUMP`, here so `live` counts this frame's births.
         if emit_dump {
             dumps.emit.dump(
                 dump_owner,
@@ -1381,9 +1038,7 @@ pub(super) fn simulate_particles(
                 },
             );
         }
-        // The model's own committed light, if it has one. Resolved once per emitter and shared by
-        // the parent draw and every child draw: they are all batches of ONE model, and the
-        // reference has one light node per model.
+        // The model's committed light, shared by its child draws: one light node per model.
         let committed = owner_mul.committed_light(lit_by);
         let lighting = fold_committed_light(&mut quads.verts[start as usize..], def.lit, committed);
         quads.commit_quads(
@@ -1402,14 +1057,11 @@ pub(super) fn simulate_particles(
                 no_depth_test: false,
                 main_entity: entity,
                 light: light_override.map(|l| l.0.clone()),
-                // The pane cell a UI model tile's cloud is confined to (`set_clip`); `None` for
-                // every world emitter, which owns the whole target.
+                // A UI model tile's pane cell (`set_clip`); `None` in the world.
                 clip: *clip,
             },
         );
-        // CHILD pools: their own texture/blend/fog identity, the PARENT's anchor and rung
-        // (a child draws at the parent's anchor, and it is the parent's owner it must clear —
-        // `ParticleEmitter::owner_reach`'s doc).
+        // Child pools: their own texture, blend and fog, the parent's anchor and rung.
         for child in children.iter() {
             if child.particles.is_empty() || !images.contains(&child.texture) {
                 continue;
@@ -1435,10 +1087,7 @@ pub(super) fn simulate_particles(
                     texture: child.texture.id(),
                     blend: child.def.blend.into(),
                     fog: EffectFog::for_blend(child.def.flags, child.def.blend),
-                    // A child emitter is a whole emitter record of the recursion model, with its
-                    // own flag word and blend field — so it takes its OWN lighting verdict, never
-                    // the parent's (the same rule its texture/blend/fog identity follows above).
-                    // The NODE is the parent's: one light node per model, children included.
+                    // Its own record's lighting verdict, under the parent's light node.
                     lighting: child_lighting,
                     anchor,
                     bias,
@@ -1448,7 +1097,7 @@ pub(super) fn simulate_particles(
                     no_depth_test: false,
                     main_entity: entity,
                     light: light_override.map(|l| l.0.clone()),
-                    // A child cloud draws where its parent does — same cell, same clip.
+                    // The parent's cell and clip.
                     clip: *clip,
                 },
             );
@@ -1456,20 +1105,12 @@ pub(super) fn simulate_particles(
     }
 }
 
-/// The two per-MODEL multipliers a cloud carries out of its owner — its render alpha and its
-/// committed light.
-///
-/// Bundled because they are the same shape: one lookup from the emitter's owning model, multiplied
-/// into the cloud. (And because [`simulate_particles`] sits at bevy's 16-parameter ceiling — but
-/// that is the forcing function, not the reason.)
+/// The two per-model multipliers a cloud takes from its owner: render alpha and committed light.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct OwnerMultipliers<'w, 's> {
-    /// The per-model render alpha (decision 0827), composed along the attached-model chain (0833).
+    /// The per-model render alpha, composed along the attached-model chain.
     alphas: crate::model_fade::ModelAlphas<'w, 's>,
-    /// The light node a LIT emitter shades under when its model stands in a WMO room: the
-    /// reference lights the object from its OWN node, never from the day/night sun (wow-re
-    /// `part-lit-normal-space.md` §6.7). Absent = the exterior lane, which the shader applies
-    /// per view by itself.
+    /// A lit emitter's room light node inside a WMO, never the sun (`0x6a7300`); absent outdoors.
     lights: Query<'w, 's, &'static crate::interior::ParticleLight>,
 }
 
@@ -1485,20 +1126,8 @@ impl OwnerMultipliers<'_, '_> {
     }
 }
 
-/// Fold a model's **committed** light into the vertices this draw just pushed, and name what the
-/// draw's colour has met — the producer's half of [`EffectLighting::Committed`].
-///
-/// An emitter that clears the file's unlit bit is lit by its model's light NODE, and indoors that
-/// node is the room's, not the sky's (wow-re `part-lit-normal-space.md` §6.7). A particle quad
-/// carries exactly one normal, so the node collapses to one RGB per draw
-/// ([`crate::interior::ParticleLight`]) — and a per-draw constant on a lane whose whole design is
-/// one shared vertex buffer belongs in the vertices. The multiply is per-channel, constant over
-/// the draw and in the same gamma space the shader's own scene term uses, so it lands on exactly
-/// the value the fragment would have computed.
-///
-/// With no committed light the emitter is on the exterior lane and the shader applies the scene's
-/// term per view — which is also what a booth's own light buffer overrides, so that path must stay
-/// in the shader.
+/// Fold a lit emitter's committed light into the RGB it just pushed and return its lighting: one
+/// RGB per draw, multiplied in the shader's own gamma space. Without one the shader lights it.
 fn fold_committed_light(
     verts: &mut [EffectVertex],
     lit: bool,
@@ -1510,12 +1139,8 @@ fn fold_committed_light(
         (true, Some(mul)) => {
             for v in verts {
                 for (c, m) in v.color.iter_mut().zip(mul) {
-                    // Clamped on the PRODUCT, never on the multiplier: the reference's committed
-                    // light is unclamped arithmetic (`0x71c2f0`'s reconstruction has no saturate —
-                    // `0x4549a0` is three dword moves and a `ret`) and it is GL that clamps the
-                    // LIT VERTEX COLOUR at the end. Clamping the term instead would cap a bright
-                    // room's multiplier at 1 and quietly lose the brightening a dim emitter is
-                    // authored to receive (decision 1709).
+                    // Clamp the product, not the light, which the reference leaves unclamped
+                    // (`0x71c2f0`, `0x4549a0`): GL clamps the lit vertex colour.
                     *c = (*c * m).clamp(0.0, 1.0);
                 }
             }
@@ -1533,12 +1158,7 @@ mod tests {
     };
     use bevy::prelude::{Quat, Transform};
 
-    /// **A burst's particles are all born at age 0** — the burst spawn loop pushes a literal `0`
-    /// as the kernels' `w` (`0x7b5600`), so the whole puff shares one clock and ages as one body.
-    /// Reading `w` as the LIFESPAN instead — the shape an audit proposed here — would scatter the
-    /// puff over `[0, lifespan)`, halve its integrated brightness and halve every steady pool's
-    /// population, which is the arithmetic wow-re's own measured C1 (300 = rate x lifespan)
-    /// already ruled out. Pinned so that reading cannot come back.
+    /// The burst loop passes `w = 0` (`0x7b5600`): the whole puff ages as one.
     #[test]
     fn a_burst_births_every_particle_at_age_zero() {
         let mut rng = 0x1234_5678;
@@ -1549,8 +1169,6 @@ mod tests {
         assert_eq!(birth_age(true, 5.0, &mut rng), 0.0);
     }
 
-    /// A POURED particle is born aged by a random fraction of its own frame (`U01 . dt`), which is
-    /// what de-synchronises the births sharing one frame.
     #[test]
     fn a_poured_particle_is_born_aged_within_its_own_frame() {
         let mut rng = 0x9e37_79b9;
@@ -1564,8 +1182,7 @@ mod tests {
         assert!(saw_nonzero, "the seed is a real draw, not a constant 0");
     }
 
-    /// The reference substeps at a hard 0.1 s, so its `w` is bounded by construction; we do not
-    /// substep, so a hitch frame is clamped here instead (the named approximation in `birth_age`).
+    /// `birth_age`'s clamp stands in for the reference's 0.1 s substep.
     #[test]
     fn a_hitch_frame_cannot_birth_a_particle_older_than_the_substep_cap() {
         let mut rng = 0xdead_beef;
@@ -1586,11 +1203,7 @@ mod tests {
         ]
     }
 
-    /// The three lighting verdicts a draw can take, and what each does to the vertices the
-    /// producer just pushed. The one that matters is the third: a model standing in a WMO room
-    /// carries its OWN committed light, which for a particle is a per-draw constant — folded in
-    /// here, leaving the shader nothing to do. **Alpha is never touched**: it is the blend weight,
-    /// not a colour, and the additive fold `rgb·α` downstream would square the light if it were.
+    /// Alpha is never lit: it is the blend weight, and the additive `rgb·α` would square the light.
     #[test]
     fn a_committed_light_folds_into_the_rgb_and_leaves_the_blend_weight_alone() {
         let mut verts = one_quad();
@@ -1618,50 +1231,37 @@ mod tests {
         }
     }
 
-    /// The membership law (`0x7084cf`): `above ⇔ d ≥ −r` — the tie at `d == −r` lands ABOVE
-    /// (the reference's `jp` keeps it), NaN lands BELOW (unordered → the below push), and with
-    /// no slack (the mesh lane's r = 0) it degenerates to the sign test with `d = 0` above —
-    /// the same tie side as [`crate::player::camera`]'s waterline. The eye then picks which
-    /// list is FAR (`0x4836d6`): dry ⇒ below, submerged ⇒ above — exercised at the callers.
+    /// `0x7084cf`: a tie at `d == −r` is above, NaN below; r = 0 is the sign test, 0 above.
     #[test]
     fn membership_is_d_at_least_minus_r() {
-        // The slack: a model bobbing within its own radius of the plane stays ABOVE — the
-        // shoulder flame's stability at the waterline (0921).
+        // A model bobbing within its radius of the plane stays above.
         assert!(is_above(-0.5, 2.0));
         assert!(is_above(-2.0, 2.0), "tie at d == -r lands above");
         assert!(!is_above(-2.1, 2.0));
         // r = 0 (the mesh lane): the sign test, 0 above.
         assert!(is_above(0.0, 0.0));
         assert!(!is_above(-0.1, 0.0));
-        // NaN → below, the reference's unordered-compare branch — `>=` gives it for free.
+        // NaN is below, the reference's unordered-compare branch.
         assert!(!is_above(f32::NAN, 2.0));
     }
 
-    /// **A paced booth camera is not a sleeping one** (1559, director report B312). The draw-set
-    /// freeze belongs to a camera whose scene stopped; `boothHalfRate` skips a *render* over a
-    /// scene that is still posing at full rate, so the emitter owes it nothing. Conflating the
-    /// two is what ran the paper doll's item effects at half speed while its pane was open.
+    /// A throttled camera skips renders of a scene still posing at full rate: no freeze.
     #[test]
     fn a_throttled_booth_camera_does_not_freeze_its_emitters() {
-        // Asleep: the pane closed. Freeze — the reference's cull, faithfully.
+        // Asleep: the pane closed, the reference's cull.
         assert!(booth_frozen(false, false, false));
-        // Paced, on a frame it skipped: NOT frozen. This is the whole fix.
+        // Paced, on a skipped frame: not frozen.
         assert!(!booth_frozen(false, true, false));
-        // Paced, on a frame it drew: nothing to decide, it was never frozen.
+        // Paced, on a drawn frame.
         assert!(!booth_frozen(true, true, false));
         assert!(!booth_frozen(true, false, false));
-        // A draining pool runs out on any camera — freezing one strands it.
+        // A draining pool runs out on any camera.
         assert!(!booth_frozen(false, false, true));
         assert!(!booth_frozen(false, true, true));
     }
 
-    /// **A camera is not a scene any more** (decision 2046). Every booth before the `<Model>`
-    /// tile atlas owned its own camera, so `is_active` answered "is this scene drawn". The atlas
-    /// puts EVERY orthographic pane behind one camera that stays active whenever any cell is
-    /// packed — it is the camera that clears the sheet — so for a pane that left the paint list
-    /// the camera says "drawn" and only the owner can say otherwise. Before this, a hidden
-    /// autocast-shine pane's four spline emitters kept integrating AND kept pushing quads for the
-    /// whole 600-frame linger, at the cell the packer had since given to another pane.
+    /// The tile atlas's one camera stays active while any cell is packed, so only the owner can
+    /// freeze a pane that left the paint list.
     #[test]
     fn an_owner_freezes_a_cloud_whose_camera_still_says_drawn() {
         // The tile atlas's own shape: the camera is up, and the pane is not.
@@ -1670,16 +1270,16 @@ mod tests {
             scene_frozen(Some((true, false)), true, false),
             "the owner parked the pane — the camera cannot see that"
         );
-        // The booth's camera still answers entirely on its own where it owns the scene.
+        // A booth camera still freezes its own scene.
         assert!(scene_frozen(Some((false, false)), false, false));
         assert!(
             !scene_frozen(Some((false, true)), false, false),
             "…and a throttled camera is awake (1559)"
         );
-        // A world-lane emitter has no booth camera at all; the owner's lever still reaches it.
+        // A world-lane emitter has no booth camera; the owner still reaches it.
         assert!(!scene_frozen(None, false, false));
         assert!(scene_frozen(None, true, false));
-        // Draining overrides both sources, for `booth_frozen`'s reason.
+        // Draining overrides both.
         assert!(!scene_frozen(Some((false, false)), true, true));
         assert!(!scene_frozen(None, true, true));
     }
@@ -1708,10 +1308,7 @@ mod tests {
         }
     }
 
-    /// The sphere KILL-OUTBOUND tail test (`0x7b2680`, rt 0x800): an inward particle lives while
-    /// converging, dies the frame its motion turns away from the origin (after the crossing) —
-    /// and the test uses the PRE-drag step velocity against the UPDATED position, in that byte
-    /// order. Without a kill origin the same particle just integrates.
+    /// `0x7b2680`: the pre-drag step velocity against the updated position.
     #[test]
     fn kill_outbound_dies_at_the_centre_crossing() {
         let origin = Vec3::new(1.0, 2.0, 3.0);
@@ -1730,16 +1327,12 @@ mod tests {
         for _ in 0..5 {
             assert!(integrate_particle(&mut free, &free_env));
         }
-        // An OUTBOUND particle on a kill emitter dies on its first step (the authored content
-        // never does this — every kill author emits inward).
+        // An outbound particle dies on its first step; no authored emitter does this.
         let mut out = particle(origin + Vec3::X * 0.5, Vec3::X);
         assert!(!integrate_particle(&mut out, &kill));
     }
 
-    /// [`world_motion_kept`] — the ride-vs-trail law (wow-re `part-emitter-motion.md` §2c,
-    /// decision 1578). The emitter's own file flag `0x10` sets the baseline; the follow flag
-    /// `0x4000` adds the authored response on top; a degenerate response adds nothing. The host
-    /// class is not an input — the same unflagged def trails whoever carries it.
+    /// Flag `0x10` sets the ride-vs-trail baseline (`0x7b8a9a`); `0x4000` adds the response.
     #[test]
     fn follow_fraction_is_the_authored_response_and_nothing_else() {
         let plain = crate::particles::tests::plain_def(); // no flags
@@ -1759,8 +1352,7 @@ mod tests {
             "file 0x10 alone adds NO term: model mode's draw already re-applies the live emitter \
              matrix, which is the whole 100% ride"
         );
-        // ArcaneShot's authored pair: 0.1 @ 2.5 yd/s, 0.9 @ 16.667 — the head glow catching up
-        // over the world-frozen baseline its three siblings keep.
+        // ArcaneShot's authored pair: 0.1 at 2.5 yd/s, 0.9 at 16.667.
         let following = benilla_formats::ParticleEmitterDef {
             flags: 0x4000,
             follow_speed1: 2.5,
@@ -1785,19 +1377,14 @@ mod tests {
         assert_eq!(follow_fraction(&degenerate, 30.0), 0.0);
     }
 
-    /// **B154's regression, at the draw**: a world-mode particle is frozen at birth, so NOTHING
-    /// its host subsequently does — translate, turn, or swing the emitter's bone through an
-    /// animation — may move it. Decision 1578 cancelled the host's *translation* with a per-frame
-    /// correction and left its *rotation* reaching every live particle, which is what welded
-    /// Sprint's sparkle trail to the runner's chest bone (wow-re §2c-B: the CLEAR draw at
-    /// `0x7b3f48` folds `rt+0x1fc` back in NOT AT ALL).
+    /// The world-mode draw never folds `rt+0x1fc` back in (`0x7b3f48`).
     #[test]
     fn a_world_mode_particle_ignores_everything_its_host_does_after_birth() {
         use crate::particles::quads::{particle_center, DrawFrame};
         let born_at = Vec3::new(12.0, 3.0, -40.0);
         let p = particle(born_at, Vec3::ZERO);
         let frame = DrawFrame {
-            anchored: true, // 0x10 CLEAR — the world store
+            anchored: true, // 0x10 clear: the world store
             alpha: 1.0,
             ride: crate::ride_frame::StoredFrame::default(), // on the ground: no fold
             size_scale: 1.0,
@@ -1819,11 +1406,7 @@ mod tests {
         }
     }
 
-    /// …with exactly one exception, and it is the reason the ride frame exists (decision 1591):
-    /// a world-mode particle follows the **transport** its host is standing on, because its store
-    /// is the deck's frame and the draw re-projects through the deck's live pose (`A · T · S`,
-    /// `0x7b3f4f`). This is the director's Thunder Bluff report: without it a weapon's sparkle
-    /// stays at the height it was born and the rising lift streams it out below your feet.
+    /// The store is the deck's frame, drawn through the deck's live pose (`A · T · S`, `0x7b3f4f`).
     #[test]
     fn a_world_mode_particle_rides_the_transport_under_it() {
         use crate::particles::quads::{particle_center, DrawFrame};
@@ -1862,15 +1445,12 @@ mod tests {
         );
     }
 
-    /// The other half of the same law: model mode (`0x10` SET) rides its host rigidly, rotation
-    /// included — the carried torch. Storage space is the whole discriminator, so these two tests
-    /// together are the ride/trail law at the draw.
     #[test]
     fn a_model_mode_particle_rides_its_host_rigidly() {
         use crate::particles::quads::{particle_center, DrawFrame};
         let p = particle(Vec3::new(1.0, 0.0, 0.0), Vec3::ZERO); // WoW axes, 1 yd out on +X
         let frame = DrawFrame {
-            anchored: false, // 0x10 SET — the emitter-local store
+            anchored: false, // 0x10 set: the emitter-local store
             alpha: 1.0,
             ride: crate::ride_frame::StoredFrame::default(),
             size_scale: 1.0,
@@ -1892,9 +1472,7 @@ mod tests {
         );
     }
 
-    /// FOLLOW-DELTA (`0x7b2680` @0x7b2744, rt 0x40000): the shared per-frame vector moves every
-    /// live particle — except each particle's FIRST integrate, which consumes its fresh bit
-    /// instead (the reference's particle+0xd first-frame skip).
+    /// `0x7b2744`: the fresh bit (particle+0xd) skips the first integrate's add.
     #[test]
     fn follow_delta_skips_only_the_first_integrate() {
         let following = env(None, Vec3::X * 0.5);
@@ -1914,10 +1492,7 @@ mod tests {
         );
     }
 
-    /// The VELOCITY-INHERIT trigger law (`0x7b5230` 0x7b53ce–0x7b54ca): nothing until the
-    /// accumulator passes 1/30 s; at the trigger the held vector becomes
-    /// `oneFrameΔ·((1/30)/accum)·scale` (with the ×1/30 the first sketch missed), zero when
-    /// nothing is live; it HOLDS between triggers.
+    /// `0x7b5230`: held `oneFrameΔ·((1/30)/accum)·scale` past 1/30 s, zero with nothing live.
     #[test]
     fn inherit_trigger_fires_at_thirty_hertz_with_the_exact_factor() {
         let (mut accum, mut held) = (0.0, Vec3::ZERO);
@@ -1940,10 +1515,7 @@ mod tests {
         assert_eq!(held, Vec3::ZERO);
     }
 
-    /// The CHILD drive (`0x7b5b9f`): the child's accumulator receives one `rate·dt` per live
-    /// parent particle (volume ∝ live count), births land at parent-particle positions, and a
-    /// flag-0x40 child folds its parent particle's velocity into each birth. No parent
-    /// particles ⇒ a child never emits (its only source is the per-particle calls).
+    /// `0x7b5b9f`: one `rate·dt` per live parent particle, born at it with its velocity (0x40).
     #[test]
     fn child_drive_scales_with_the_parent_pool() {
         let mut child = ChildEmitter::bare(benilla_formats::ParticleEmitterDef {
@@ -1951,8 +1523,7 @@ mod tests {
             ..crate::particles::tests::plain_def()
         });
         child.def.timing = benilla_formats::EmitTiming::constant(100.0);
-        // Point emitter, zero own speed: births land exactly ON the parent particle and the
-        // whole birth velocity is the inherited term.
+        // Point emitter, zero speed: births land on the parent with only the inherited velocity.
         let c_now = benilla_formats::ParamsNow {
             emission_speed: 0.0,
             area_length: 0.0,
diff --git a/crates/benilla-world/src/ribbons.rs b/crates/benilla-world/src/ribbons.rs
index dd8bcde2..f4d0802e 100644
--- a/crates/benilla-world/src/ribbons.rs
+++ b/crates/benilla-world/src/ribbons.rs
@@ -1,23 +1,8 @@
-//! Faithful M2 **ribbon trails** — weapon enchant trails, wisp streamers, spell-missile trails.
-//!
-//! The 1.12 client simulates a ribbon as a ring of **edges**: each frame the emitter's bone-local
-//! origin is transformed by the live bone matrix into a node point, `floor(dt·edgesPerSecond +
-//! phase)` new edges (a vertex pair at `±heightAbove/heightBelow` across the node) are committed
-//! and backdated inside the frame, old edges age out at `edgeLifetime`, **gravity carries the
-//! stored verts along world +Z by `g·t²`** — up for the positive majority of the corpus — and the
-//! edge list renders as a triangle strip whose `u` texcoord slides with edge age (the texture's
-//! transparent tail fades the trail). Byte-exact spec: wow-5875-re
-//! `system/models/scratch/ribbon-emitter-spec.md`; the sim below transcribes it with the same
-//! simplifications as `particles` (distributions and frames mirrored, not the reference's exact
-//! float slots).
-//!
-//! Like particles, each trail writes its strip into the **shared effect-quad stream**
-//! ([`crate::particles::buffer::EffectQuads`], decision 0732 slice P1) — per segment, one quad
-//! duplicating the shared edge vertices (identical triangles to the old strip mesh; a few dozen
-//! extra vertices per trail buys the whole family one vertex layout and one index pattern). A
-//! trail rides its **owner** entity (a skinned model's host-bone joint, an item root, a
-//! missile); when the owner goes it drains — committed edges finish fading, then the trail
-//! despawns itself (the reference's enable-gate law).
+//! M2 ribbon trails: weapon enchant trails, wisp streamers, spell-missile trails. The 1.12 client
+//! keeps a ribbon as a ring of edges, vertex pairs across the node the live bone matrix places
+//! each frame, committed at `edgesPerSecond`, aged out at `edgeLifetime` and drawn as a strip whose
+//! `u` slides with age, so the texture's transparent tail is the fade. When its owner goes, a
+//! trail drains and despawns itself.
 
 use std::collections::VecDeque;
 
@@ -31,196 +16,118 @@ use bevy::prelude::*;
 use crate::particles::buffer::{EffectDrawSpec, EffectFog, EffectQuads, EffectVertex};
 use crate::view::WorldCamera;
 
-/// Hard cap on stored edges — a backstop against a pathological rate·lifetime (the reference's
-/// ring capacity is `ceil(rate·lifetime)+2`; shipped trails sit far below this).
+/// A backstop cap on stored edges; the reference's ring holds `ceil(rate·lifetime) + 2`.
 const MAX_EDGES: usize = 512;
 
-/// **What the ribbon lane did this frame** — live trails, and how many of them wrote a strip.
-///
-/// The parallel of [`crate::exterior_cull::ExteriorCullVerdict`], and here for the same reason: a
-/// trail carries no [`crate::model_render::ModelPart`] and no
-/// [`crate::particles::ParticleEmitter`], so it is invisible to the visibility census AND to the
-/// particle census. Ninety Caverns-of-Time energy trails burning across a Tanaris hillside read,
-/// on every instrument we had, as a scene with nothing in it.
+/// This frame's ribbon census: a trail carries no `ModelPart` or `ParticleEmitter`, so neither
+/// the visibility nor the particle census counts it.
 #[derive(Resource, Default)]
 pub struct RibbonVerdict {
-    /// Trails alive this frame (streaming or draining).
+    /// Trails alive this frame, streaming or draining.
     pub trails: usize,
-    /// …and how many committed a strip into the shared effect stream.
+    /// Trails that wrote a strip into the shared effect stream.
     pub drawn: usize,
 }
 
-/// One committed trail edge: the vertex pair across the node, in the trail's **stored** frame
-/// ([`RibbonTrail::ride`] — world on the ground, the deck on a transport), and its birth time on
-/// the shared clock.
+/// One committed edge: its vertex pair in the stored frame and its birth on the shared clock.
 struct Edge {
     top: Vec3,
     bottom: Vec3,
     born: f32,
-    /// Seconds this edge has been alive, carried explicitly because the reference does
-    /// ([`simulate_ribbons`]'s gravity note): its per-edge age array at `emitter+0x0c` is the term
-    /// the gravity increment reads, and an edge born part-way through a frame starts at its
-    /// **backdated** age, not zero.
+    /// Seconds alive from the backdated birth: the reference's per-edge age array
+    /// (`emitter+0x0c`), which the gravity step reads.
     age: f32,
 }
 
-/// This frame's gravity displacement for one live edge, in world **+Z (up)** yards — the
-/// reference's exact per-frame term (`ribbonage 0x7b7e60`, `0x7b8007`..`0x7b800f`):
-/// `gravity · ((age + age) + dt) · dt`, applied identically to both of the edge's vertices, with
-/// `age` advanced by `dt` straight after.
-///
-/// `(2a + dt)·dt ≡ (a + dt)² − a²`, so stepping it across an edge's life telescopes exactly to
-/// `Δz = gravity · t²` — no ½, no factor of 2, and **upward** for a positive `gravity` (the block
-/// is two `fadd`s with no `fchs`, on world-space positions in a +Z-up frame). See
-/// [`simulate_ribbons`] for why both halves of that mattered on screen.
+/// One frame's gravity rise for an edge, world +Z yards: the reference's
+/// `gravity · ((age + age) + dt) · dt` (`0x7b7e60`, `0x7b8007`..`0x7b800f`), then `age += dt`. It
+/// telescopes to `gravity · t²`, upward for a positive gravity (two `fadd`s, no `fchs`).
 fn gravity_step(gravity: f32, age: f32, dt: f32) -> f32 {
     gravity * ((age + age) + dt) * dt
 }
 
-/// A live ribbon trail riding `owner`. Positions are world-space; the mesh entity's transform is
-/// identity (like a particle emitter's).
+/// A live ribbon trail riding `owner`, drawn in world space; its translation is the sort anchor.
 #[derive(Component)]
 pub struct RibbonTrail {
     def: benilla_formats::RibbonEmitterDef,
-    /// The emission origin in the owner's frame: `wow_to_bevy(position − bone_pivot)` for a joint
-    /// owner (the same rig identity as particle emitters), `wow_to_bevy(position)` for a root.
+    /// The emission origin in the owner's frame (`position − bone_pivot` for a joint owner).
     local_offset: Vec3,
-    /// The node source — `None` once the owner is gone (missile impacted, effect reaped, item
-    /// unequipped): the trail then **drains** — commits nothing, ages its edges out, and
-    /// despawns itself with the last edge. The reference frees a model's emitters SYNCHRONOUSLY
-    /// at the model dtor (`0x70e313` — no orphan list; wow-re `ribbon-basis-emitter-lifecycle`);
-    /// its visible fade comes from keeping the MODEL alive while emitters drain (the
-    /// `HasLiveParticles 0x7b5f60` latch + the model's is-any-emitter-active flag). Our owners
-    /// despawn at their own moment (impact, reap), so this drain reproduces the
-    /// defer-until-drained shape; whether the client's effect controller actually polls the
-    /// active flag before destroy, or hard-cuts at animation end, is the one OPEN half
-    /// (CEffect-side, flagged in decision 0206).
+    /// The node source; `None` once the owner is gone and the trail drains. The reference frees a
+    /// model's emitters at its dtor (`0x70e313`) and keeps an ending effect's model while its
+    /// particles drain (`HasLiveParticles` `0x7b5f60`); whether its ribbons drain too is untraced.
     owner: Option<Entity>,
-    /// Which clock the `+0xc0` enable gate is sampled against, every frame ([`RibbonSeq`]).
+    /// The clock the `+0xc0` enable gate is sampled against every frame.
     seq: RibbonSeq,
-    /// The MODEL INSTANCE whose [`crate::model_fade::ModelAlpha`] decides whether this trail is
-    /// drawn at all (decision 0827). The reference's ribbon render leg reads the owning model's
-    /// render alpha (`block+0x3c × Model+0x19c`) and **drops the draw** below a threshold (wow-re
-    /// `ribbon-emitter-spec.md` §5) — so an invisible model has no streamer, which is what a
-    /// first-person avatar's enchant trail needs (ledger F05). Only the drop is implemented: the
-    /// note does not say the model alpha scales the strip's vertex colour the way it does a
-    /// particle's, and inventing a ramp on top of a gate would be building past the evidence.
-    /// `None` ⇒ always drawn (a placed prop, an effect instance).
+    /// The model whose [`crate::model_fade::ModelAlpha`] gates the draw (`None` always draws): the
+    /// reference's ribbon leg drops the draw below a render-alpha threshold (`0x707680`, alpha
+    /// `block+0x3c × Model+0x19c`). Whether that alpha also scales the strip is untraced.
     alpha_src: Option<Entity>,
-    /// **Is this trail's model in the frame's scene at all?** — the placed model's own
-    /// [`crate::particles::EmitterFade`], carried by value.
-    ///
-    /// A trail is one of its model's emitters, and the reference ticks and draws a model's
-    /// emitters — quad clouds and ribbons alike — inside **that model's** draw step. So a trail
-    /// takes exactly the gate the quad clouds beside it take, from the same construction at the
-    /// same spawn site: distance fade, the far-clip wall, the lateral frustum, the exterior window,
-    /// and the room ([`crate::particles::EmitterFade::in_draw_set`]). The ribbon lane used to have
-    /// **no term of any kind** here, which is how ninety Caverns of Time trails burned up through
-    /// 200 yd of Tanaris rock (decision 1289, the room term) and how a placed prop's streamer drew
-    /// past the far-clip wall its own mesh had already been culled by (bug B39, decision 0678 —
-    /// fixed for the quad clouds and left open here).
-    ///
-    /// By value and not as a component, because a trail entity holding an `EmitterFade` would be
-    /// picked up by the particle sim's own optional-fade query, and its `WmoGroupVis` inside would
-    /// enlist it in `apply_model_visibility`'s group query — a second `Visibility` writer on an
-    /// entity whose `Visibility` nobody reads (decision 0025).
-    ///
-    /// `None` = an ENTITY-owned trail (a creature, a GameObject, a missile, a held item), bounded
-    /// by server visibility and by [`Self::alpha_src`] instead — the same split
-    /// [`crate::particles::EmitterFade`] itself takes, and with the same far-clip backstop applied
-    /// in [`simulate_ribbons`] for the one lane server visibility does not bound (transports).
+    /// The placed model's [`crate::particles::EmitterFade`]: the reference ticks and draws a
+    /// model's emitters inside that model's draw step, so a trail takes its quad clouds' draw-set
+    /// gate. Held by value: as a component it would join the particle sim's fade query and, by its
+    /// `WmoGroupVis`, `apply_model_visibility`'s. `None` for an entity-owned trail.
     fade: Option<crate::particles::EmitterFade>,
-    /// **The frame the committed edges are expressed in** — world on the ground, the transport's
-    /// deck while the owning model rides one ([`crate::ride_frame`], decision 1591).
-    ///
-    /// A ribbon's whole point is that a committed edge never moves again, which is what draws a
-    /// streak behind a swinging weapon. On a transport that same rule streams the streak off the
-    /// back of the vehicle, so the reference stores the edges in the ride frame instead and
-    /// re-projects them through its live pose at draw — the ribbon twins of the particle folds
-    /// (birth `0x718dd8` → `0x7b76c0`, draw `0x70d87d` → `0x7b80c0`), and note the negative: the
-    /// ribbon birth has **no `0x100` gate**, so a trail is ride-framed unconditionally where a
-    /// particle cloud is only in world mode.
+    /// The frame the committed edges are stored in: world on the ground, the deck while the owning
+    /// model rides a transport ([`crate::ride_frame`]). The reference stores and re-projects them
+    /// (birth `0x718dd8` → `0x7b76c0`, draw `0x70d87d` → `0x7b80c0`) with no `0x100` gate: a
+    /// trail is always ride-framed, a particle cloud only in world mode.
     ride: crate::ride_frame::StoredFrame,
-    /// Committed edges, newest at the back, in [`Self::ride`]'s frame. The live head (the current
-    /// node) is appended at render time only, so the trail always connects to the emitter between
-    /// commits.
+    /// Committed edges, newest last; the live head is added only at draw.
     edges: VecDeque<Edge>,
     accumulator: f32,
-    /// Seconds since spawn — the clip clock the keyed look tracks (colour/alpha/heights) sample
-    /// against (an effect model's ribbons spawn at its clip start, so age == clip time — the
-    /// particle emitters' law; a persistent trail's constant tracks are age-invariant).
+    /// Seconds since spawn: the clip clock the keyed tracks sample, as an effect's ribbons spawn at
+    /// its clip start (a persistent trail's tracks are constant).
     age: f32,
     texture: Handle<Image>,
-    /// The owner-last draw-order rung ([`crate::particles::owner_last_bias`] over the owner's
-    /// world reach, computed at spawn) — a trail is one of its model's emitters and takes the
-    /// SAME rung as the quad clouds beside it (0721). Was the material's `depth_bias`; now the
-    /// draw record's sort-key add.
+    /// The owner-last draw-order rung its model's quad clouds take, added to the sort key.
     bias: f32,
-    /// The owner model's bound sphere ([`ModelRibbon::water_bound`]) — the water-plane side is
-    /// the MODEL's (0921): the ribbon leg reads the model's side-A boolean verbatim, slack
-    /// included, so the trail flips with its model's bound centre, never with its whipping head.
+    /// The owner model's bound sphere: the water-plane side is the model's, never the head's.
     water_bound: (Vec3, f32),
 }
 
 impl RibbonTrail {
-    /// The emitter bone this trail rides — the identity `WOW_PHASE=particles:<bone>` arms on, and
-    /// the one `emdump`/`m2anim` print, so an instrument line and an asset line name the same trail.
+    /// The emitter bone, the id `WOW_PHASE=particles:<bone>` arms on and the asset dumps print.
     pub fn bone(&self) -> u16 {
         self.def.bone
     }
 
-    /// The committed strip in **world** space — the points the draw rasterizes, folded out of the
-    /// store's ride frame ([`Self::ride`]). For instruments: the trail census measures this
-    /// strip's spread inside the DECK's frame, which is exactly the observable the ride law is
-    /// about ("does the streak hang still relative to the floor you're standing on?").
+    /// The committed strip in world space, as drawn; the trail census reads it.
     pub fn strip_world(&self) -> impl Iterator<Item = Vec3> + '_ {
         self.edges
             .iter()
             .flat_map(move |e| [self.ride.to_world(e.top), self.ride.to_world(e.bottom)])
     }
 
-    /// The transport this trail's edges are stored against — `None` on the ground.
+    /// The transport this trail's edges are stored against; `None` on the ground.
     pub fn deck(&self) -> Option<Entity> {
         self.ride.source()
     }
 
-    /// The authored edge lifetime (seconds) — the trail's own length in time, which is what a
-    /// streak's world extent divides by to give the host speed that drew it.
+    /// The authored edge lifetime (s); a streak's world length over it gives the host's speed.
     pub fn edge_lifetime(&self) -> f32 {
         self.def.edge_lifetime
     }
 
-    /// The authored blend, and how many edges are committed right now (0 = nothing drawn yet).
+    /// The authored blend and the committed edge count (0 = nothing drawn yet).
     pub fn shape(&self) -> (ParticleBlend, usize) {
         (self.def.blend, self.edges.len())
     }
 }
 
-/// What decides a trail's `+0xc0` **enable** gate — the reference's per-ribbon `block+0xbc` byte,
-/// which it re-reads every frame (wow-re `ribbon-emitter-spec.md` §6).
+/// What decides a trail's `+0xc0` enable gate: the reference's per-ribbon `block+0xbc` byte,
+/// re-read every frame (`0x717660`).
 #[derive(Clone, Copy)]
 pub enum RibbonSeq {
-    /// Re-read each frame from this entity's [`AnimationPlayer`] + [`ModelAnimations`] — the unit,
-    /// GameObject, doodad and effect-instance lanes, where the sequence **changes under the
-    /// trail**: a trap springs, a door opens, an effect model steps Stand → Hold → Decay.
+    /// The sequence this entity plays, re-read each frame, since a trap springs or a door opens.
     Host(Entity),
-    /// A fixed `AnimationData.dbc` id for the instance's life — a worn item rests in `Stand`(0),
-    /// and nothing on it will ever play anything else.
+    /// A fixed `AnimationData.dbc` id for life, such as a worn item's `Stand` (0).
     Fixed(u16),
 }
 
-/// Spawn a ribbon-trail entity for one [`ModelRibbon`], riding `owner` (a host-bone joint for a
-/// skinned model — pass the joint and the def's baked pivot does the rebase — or the model/item
-/// root). `seq` names the clock the per-sequence enable gate is sampled against (see
-/// [`RibbonSeq`]). `owner_scale` is the owner placement's largest scale component — the
-/// model-local [`ModelRibbon::owner_reach`] takes it to reach world yards, which is what the
-/// draw-order rung is measured in. `None` if the trail has no resolved texture or degenerate
-/// emission.
-///
-/// A gated trail still spawns: the gate is **live**, not a spawn-time decision, because the
-/// sequence that answers it changes while the instance lives. Refusing at spawn was correct only
-/// for the fixed-sequence lanes it was written for (a held item, a missile) and silently wrong for
-/// everything with a state machine — see [`simulate_ribbons`].
+/// Spawns a trail for one [`ModelRibbon`] riding `owner`: a host-bone joint (`use_pivot` rebases
+/// by the def's baked pivot) or a model or item root. `owner_scale`, the placement's largest scale,
+/// takes [`ModelRibbon::owner_reach`] to world yards for the draw-order rung. `None` without a
+/// texture or with degenerate emission. A gated trail still spawns: its gate is sampled live.
 pub fn spawn_ribbon(
     commands: &mut Commands,
     ribbon: &ModelRibbon,
@@ -231,14 +138,13 @@ pub fn spawn_ribbon(
     alpha_src: Option<Entity>,
     fade: Option<crate::particles::EmitterFade>,
 ) -> Option<Entity> {
-    // Perf-bisect kill-switch: $WOW_NO_PARTICLES also spawns no ribbons (one switch, whole family).
+    // `WOW_NO_PARTICLES` turns ribbons off too.
     if std::env::var_os("WOW_NO_PARTICLES").is_some() {
         return None;
     }
     let texture = ribbon.texture.clone()?;
     let def = ribbon.def.clone();
-    // The degenerate gate reads the tracks' PEAKS: a keyed slash (HolySmite) is born at height 0
-    // and flares mid-clip — its value[0] is exactly the zero this gate must not trip on.
+    // The peaks, not the first keys: a keyed slash (HolySmite) is born at height 0.
     if def.edges_per_second <= 0.0
         || (def.height_above.peak().max(0.0) + def.height_below.peak().max(0.0)) <= 0.0
     {
@@ -257,8 +163,7 @@ pub fn spawn_ribbon(
     Some(
         commands
             .spawn((
-                // The sim writes the trail's sort anchor (the live head node) here each frame
-                // — the phase probe's read point.
+                // The sim writes the sort anchor here each frame, where the phase probe reads it.
                 Transform::IDENTITY,
                 RibbonTrail {
                     local_offset: wow_to_bevy(local),
@@ -272,9 +177,7 @@ pub fn spawn_ribbon(
                     accumulator: 0.0,
                     age: 0.0,
                     texture,
-                    // The reference's "a model's emitters draw after that model's batches" —
-                    // the same rung the quad clouds take, from the same authored reach,
-                    // because a trail is one of the model's emitters.
+                    // A model's emitters draw after its batches: the quad clouds' rung and reach.
                     bias: crate::particles::owner_last_bias(ribbon.owner_reach * owner_scale),
                     water_bound: ribbon.water_bound,
                 },
@@ -283,33 +186,22 @@ pub fn spawn_ribbon(
     )
 }
 
-/// Per-frame: place the node from the owner's live transform, commit/expire edges, sag by
-/// gravity, and write the strip into the shared effect-quad stream.
+/// Per frame: places nodes, commits and expires edges, applies gravity and writes the strips.
 pub(crate) fn simulate_ribbons(
     time: Res<Time>,
     mut commands: Commands,
-    // Owner reads (joints/roots — never trail entities): disjoint from the trail query's
-    // `&mut GlobalTransform` below.
+    // Owners only, disjoint from the trail query's `&mut GlobalTransform`.
     transforms: Query<&GlobalTransform, Without<RibbonTrail>>,
-    // The `+0xc0` enable gate's clock: the sequence a [`RibbonSeq::Host`] instance is playing.
+    // The enable gate's clock for a `RibbonSeq::Host`.
     hosts: Query<(&AnimationPlayer, &benilla_assets::ModelAnimations)>,
     images: Res<Assets<Image>>,
     mut quads: ResMut<EffectQuads>,
-    // The owning model's render alpha — the trail's draw gate (decision 0827), composed along the
-    // attached-model chain (0833).
     model_alphas: crate::model_fade::ModelAlphas,
-    // Trails belong to the world lane (no booth ribbons; a booth-parked owner's strip is eaten
-    // by the shader's farclip wall, exactly as on the material path). The frustum/projection come
-    // with it because the draw-set gate below needs the same lateral test the quad clouds take.
+    // World lane only: a booth-parked owner's strip is cut by the shader's far-clip wall.
     world_cam: Query<(Entity, &GlobalTransform, &Frustum, &Projection), With<WorldCamera>>,
-    // The water-plane interleave inputs — a trail is one of the model's emitters and classifies
-    // above/below water like the quad clouds ([`crate::particles::far_side_of_water`]).
     interleave: crate::particles::WaterInterleave,
-    // The draw-set gate's scene inputs — far-clip wall, exterior window, portal PVS — the SAME
-    // bundle `simulate_particles` reads, so the two emitter families cannot answer differently
-    // ([`RibbonTrail::fade`]).
+    // The draw-set gate's scene inputs, the same bundle `simulate_particles` reads.
     gates: crate::particles::sim::SceneGates,
-    // Which transport (if any) each trail's MODEL is riding — the frame its edges are stored in.
     rides: crate::ride_frame::RideFrames,
     mut verdict: ResMut<RibbonVerdict>,
     mut trails: Query<
@@ -319,8 +211,7 @@ pub(crate) fn simulate_ribbons(
             &mut Transform,
             &mut GlobalTransform,
         ),
-        // The camera's `&GlobalTransform` read above must be provably disjoint from these writes
-        // (a trail never rides the camera entity) — the particle sim's emitter query says the same.
+        // Keeps the camera's `&GlobalTransform` read disjoint from these writes.
         Without<WorldCamera>,
     >,
 ) {
@@ -329,8 +220,7 @@ pub(crate) fn simulate_ribbons(
         return;
     };
     let cam_pos = cam_tf.translation();
-    // The far-clip wall's axis — the same forward the owner mesh's own cull measures along, so a
-    // trail and the model it belongs to cross the wall together.
+    // The owner mesh's far-clip axis, so a trail crosses the wall with its model.
     let cam_fwd = Vec3::from(cam_tf.forward());
     let (farclip, exterior_gate, camera_instance) = gates.scene(Some((cam_tf, projection)));
     let dt = time.delta_secs().min(0.1);
@@ -352,21 +242,13 @@ pub(crate) fn simulate_ribbons(
             water_bound,
         } = &mut *trail;
 
-        // Owner gone (despawned missile/creature, unequipped item root) → DRAIN: no new
-        // commits, the committed edges age out, and the trail despawns with its last edge
-        // (see [`RibbonTrail::owner`]).
         if owner.is_some_and(|o| !transforms.contains(o)) {
             *owner = None;
         }
         let head = owner.and_then(|o| transforms.get(o).ok()).map(|owner_gt| {
             let node = owner_gt.transform_point(*local_offset);
-            // Cross-section axis: the bone frame's local +Y — byte-VERIFIED (wow-re
-            // `ribbon-basis-emitter-lifecycle.md`, the 0202 dispatch's fold-back): `node_place
-            // 0x7b76c0` captures the basis fresh each frame from the live bone matrix, row 1
-            // (= bone-local +Y) being the ±heightAbove/Below span (`ribbon_frame_build
-            // 0x7b6990` fmuls only that pair). Sampling the live owner rotation here IS that
-            // per-frame capture. (First pinned by elimination on the fireball missile's
-            // authored bone pair; the bytes then confirmed it.)
+            // The cross-section axis is the live bone's local +Y: `0x7b76c0` captures the basis
+            // each frame, and `0x7b6990` spans `±heightAbove/Below` along that row alone.
             let axis = (owner_gt.rotation() * wow_to_bevy([0.0, 1.0, 0.0])).normalize_or(Vec3::Y);
             (node, axis)
         });
@@ -376,10 +258,8 @@ pub(crate) fn simulate_ribbons(
         }
         verdict.trails += 1;
 
-        // **The ride frame, this frame** — the transport the owning MODEL is on, inherited down
-        // the `ParentModel` chain (an enchant streamer's model is the weapon; the weapon's parent
-        // is its wearer). A transport that has streamed out reads as no frame, which is the leave
-        // leg: the edges are handed back to the world where they stood.
+        // The owning model's transport, up the `ParentModel` chain; one streamed out reads as
+        // none, which hands the edges back to the world where they stood.
         let deck = alpha_src
             .or(*owner)
             .and_then(|model| rides.source(model))
@@ -389,10 +269,8 @@ pub(crate) fn simulate_ribbons(
                     .ok()
                     .map(|gt| (t, crate::ride_frame::ride_matrix(gt)))
             });
-        // Boarding and leaving RE-EXPRESS the committed edges rather than snapping them (the
-        // reference's `0x7187f0` → `0x7b7bc0` on the NULL↔non-NULL edge). Riding a *moving* deck
-        // folds nothing at all — the draw's live `A` is what carries the strip, and touching the
-        // store as well would ride it twice.
+        // Boarding and leaving re-express the stored edges (the reference's `0x7187f0` →
+        // `0x7b7bc0`); a moving deck folds nothing, since the draw's live `A` carries the strip.
         if let Some(fold) = ride.retarget(deck) {
             for e in edges.iter_mut() {
                 e.top = fold.transform_point3(e.top);
@@ -400,32 +278,19 @@ pub(crate) fn simulate_ribbons(
             }
         }
         let (to_deck, to_world) = match ride.matrix() {
-            // One inverse per trail per frame, not one per edge.
             Some(a) => (Some(a.inverse()), Some(a)),
             None => (None, None),
         };
 
-        // The **draw-set** gate: is this trail's MODEL in the frame's scene at all? A trail is one
-        // of its model's emitters, and the reference ticks a model's emitters inside that model's
-        // draw step — so a culled model's trail neither commits nor ages. FROZEN, the same shape
-        // `simulate_particles` freezes a culled owner's pool in, resuming from frozen state with
-        // one frame's dt rather than catching up. Until now the ribbon lane had no term here at
-        // all: not distance, not the far-clip wall, not the frustum, not the exterior window, not
-        // the portal PVS (decisions 0678 / 0786 / 1289 — each of which closed this hole for the
-        // quad clouds and left it open for the strips).
-        //
-        // Only while the owner LIVES. Freezing a DRAINING trail strands it — it can never empty
-        // its edges, so it never reaches the self-despawn above and leaks for the session; the
-        // particle sim states the identical exclusion.
+        // The draw-set gate: the reference ticks a model's emitters inside its draw step, so a
+        // culled model's trail freezes, resuming with one frame's dt. A draining trail never
+        // freezes: frozen, it could never empty and despawn.
         let admitted = match (head, fade.as_ref()) {
-            // A placed model — an ADT map doodad or a WMO prop. The full five-term rule, in its
-            // one spelling, against the owner model's fade sphere.
             (Some(_), Some(f)) => f.in_draw_set(
                 cam_pos,
                 cam_fwd,
                 farclip,
-                // Lateral planes only (`intersect_far = false`): the depth bound is the far-clip
-                // term inside `in_draw_set`, deliberately — see `view::within_farclip`.
+                // Lateral planes only: the depth bound is `in_draw_set`'s far-clip term.
                 frustum.intersects_sphere(
                     &CullSphere {
                         center: f.center.into(),
@@ -436,62 +301,40 @@ pub(crate) fn simulate_ribbons(
                 f.exterior_admitted(&exterior_gate, camera_instance),
                 gates.room_admits(f),
             ),
-            // ENTITY-owned — a creature, a GameObject, a missile, a held item. No fade sphere:
-            // the population is bounded by server visibility, and by `alpha_src` below. Except
-            // transports, which vmangos streams MAP-WIDE, so the bare wall applies to every
-            // world-lane trail exactly as decision 0678 applies it to every world-lane emitter.
-            // Measured live from the owner, never from a stored anchor: a frozen trail stops
-            // refreshing its anchor, so gating on that would latch a moving owner out of
-            // existence the first time it crossed the wall.
+            // Entity-owned: server visibility bounds these, but vmangos streams transports
+            // map-wide, so the far-clip wall applies as to every world-lane emitter. Measured from
+            // the live node: a frozen trail's stale anchor would latch a moving owner out.
             (Some((node, _)), None) => {
                 crate::view::within_farclip(farclip, cam_pos, cam_fwd, node, 0.0)
             }
-            // Draining — never frozen (see above).
+            // Draining: never frozen.
             (None, _) => true,
         };
         if !admitted {
-            // Hold the clock with the trail. Edge expiry is measured against the SHARED clock
-            // (`now - born`), so a freeze that let `now` run on would age every stored edge out
-            // while the model was away and hand back an empty strip on re-entry — the opposite of
-            // "resumes from frozen state". Advancing `born` by the frame's dt keeps each edge's
-            // relative age exactly where the freeze found it.
+            // Expiry reads the shared clock (`now - born`), so a frozen trail moves `born` on by
+            // dt to hold each edge's age.
             for e in edges.iter_mut() {
                 e.born += dt;
             }
             continue;
         }
 
-        // The keyed look tracks sample on the trail's clip clock (see [`RibbonTrail::age`]):
-        // heights at edge-commit time (each edge keeps the width it was born with — the
-        // reference stores the vertex pair per edge), colour/alpha per frame for the whole strip.
+        // Heights sample at commit, since the reference stores each edge's vertex pair; colour
+        // and alpha sample per frame.
         *age += dt;
         let ms = *age * 1000.0;
         let h_above = def.height_above.sample_ms(ms).max(0.0);
         let h_below = def.height_below.sample_ms(ms).max(0.0);
 
-        // The `+0xc0` **enable** gate, sampled LIVE against the sequence the host is playing.
-        // SETTLED at the bytes (wow-re `ribbon-emitter-spec.md` §7, closed — the dispatch this
-        // session): the per-ribbon runtime byte `block+0xbc` IS the sampled `visibilityTrack`
-        // value. Complete writer census — ctor `0x71b34c` = 0, loader default `0x70f80e` = 1,
-        // then per frame `values[k0]` at `0x7176ee` (step arm) and `0x717714` (non-step arm; a u8
-        // track is never blended, so both copy the same raw byte) inside `0x714260`. No
-        // equipment/attach/sheathe writer exists anywhere. `0x718960` only READS it.
-        //
-        // Decision 1011 wired this and was right about the mechanism; decision 1013 unwound it on
-        // the strength of §7's then-open INFERENCE and was wrong. What actually made the trap look
-        // wrong was gravity (see below) — the low rig sank instead of rising, so the tuft the
-        // reference shows above the crown vanished and only the gated-off high rig had ever been
-        // producing anything visible, as a downward column. Two faults, one screenshot.
-        //
-        // Clearing the byte KILLS THE WHOLE RIBBON'S DRAW — `0x7080c2` jumps to the collect loop's
-        // continue at `0x708263`, emitting no record at all. The earlier "committed edges keep
-        // fading" gloss is withdrawn by the same pass, so this gates the DRAW, not just the
-        // commit: a trail whose gate clears vanishes on the frame it clears.
+        // The `+0xc0` enable gate, sampled live against the host's sequence. The per-ribbon byte
+        // `block+0xbc` is the sampled `visibilityTrack`: 0 from the ctor (`0x71b34c`), 1 from the
+        // loader (`0x70f80e`), then each frame `values[k0]` in `0x714260` (`0x7176ee` step arm,
+        // `0x717714` non-step arm); nothing else writes it and `0x718960` only reads it. A clear
+        // byte skips the ribbon's whole draw (`0x7080c2` jumps to `0x708263`), not just commits.
         let lit = def.visible.as_ref().is_none_or(|vis| match *seq {
             RibbonSeq::Fixed(a) => vis.at(a, 0.0),
             RibbonSeq::Host(h) => match hosts.get(h) {
-                // Sequences exist: the playing one answers, and `playing_seq` already degrades to
-                // the loader-idle clip. A slot with no clip row falls back to `Stand`(0).
+                // The playing sequence; a slot with no clip row reads as `Stand` (0).
                 Ok((player, anims)) => {
                     let (anim, t) = crate::doodad_anim::playing_seq(player, anims)
                         .and_then(|(slot, t)| {
@@ -500,62 +343,32 @@ pub(crate) fn simulate_ribbons(
                         .unwrap_or((0, 0.0));
                     vis.at(anim, t)
                 }
-                // No clock on the host at all — the instance is still being built this frame. The
-                // reference never has this window (its loader seed arms a sequence the moment the
-                // M2 goes LIVE, `0x70ebd0`), so answering "enabled" here would invent a state and
-                // pop one frame of every gated trail. Hold dark until the host can answer.
+                // No clock yet: the host is still being built. The reference arms a sequence as the
+                // M2 goes live (`0x70ebd0`), so this holds dark rather than invent a lit frame.
                 Err(_) => false,
             },
         });
         let head = lit.then_some(head).flatten();
 
-        // Expire old edges (front = oldest), move the rest under gravity, commit new ones at rate.
         while edges
             .front()
             .is_some_and(|e| now - e.born >= def.edge_lifetime)
         {
             edges.pop_front();
         }
-        // GRAVITY — byte-verified (`ribbonage 0x7b7e60`, the loop at `0x7b7fe7..0x7b807a`; wow-re
-        // `ribbon-emitter-spec.md` §4). Per frame, per live edge, into BOTH vertices' world z:
-        //
-        //     term = gravity · ((age + age) + dt) · dt   ;   age += dt
-        //
-        // `(2a + dt)·dt` is identically `(a + dt)² − a²`, and the age advance follows immediately,
-        // so the whole loop telescopes to a closed form — an edge sits at
-        //
-        //     z(t) = z_at_emit + gravity · t²        (t = seconds since commit, yards)
-        //
-        // with no ½ and no factor of 2. It is a **position** increment; the vertex is the only
-        // state besides the per-edge age, there is no velocity, and it is scaled by nothing (the
-        // interp factor the loop computes just above is never an operand here).
-        //
-        // And the sign is `fadd`, twice, with no `fchs` anywhere in the block: positions are world
-        // space, WoW's +Z is UP, so a **positive gravity makes the trail RISE**. The corpus agrees
-        // — of 590 ribbon records 86 are positive (totems 5.0, the cleanse family 0.5/1.0) and 16
-        // negative, including ±0.5 up/down PAIRS inside one model, which a single-signed reading
-        // cannot explain at all. Our old `pos.y -= 2·g·dt` was wrong twice over: constant velocity
-        // instead of `g·t²`, and falling instead of rising. On the Frost Trap that turned a
-        // 0.6–1.3 yd tuft rising off the crown into a 2–3 yd column smeared to the ground.
-        // The gravity axis is world up in EITHER store: `A` is `translate·Rz` (yaw only), and a
-        // yaw leaves `+Y` alone — so a trail sags/rises the same way on a deck as on the ground,
-        // with no fold. That invariance is why [`crate::ride_frame::ride_matrix`] drops
-        // pitch/roll rather than carrying the transport's full rotation.
+        // Gravity (`0x7b7e60`, loop `0x7b7fe7..0x7b807a`): both vertices of every live edge rise
+        // by `gravity_step`, with no velocity and no other scale. The axis is world up in either
+        // store, which is why `crate::ride_frame::ride_matrix` is yaw only.
         for e in edges.iter_mut() {
             let term = gravity_step(def.gravity, e.age, dt);
             e.top.y += term;
             e.bottom.y += term;
             e.age += dt;
         }
-        // EMISSION — `edgesPerSecond` is a true rate, not a per-frame cadence: the reference
-        // commits `n = floor(dt·eps + phase)` edges this frame, carries the fraction as the phase,
-        // and **backdates** each one inside the frame (wow-re §4.2). A one-edge-per-frame cap
-        // silently thins every trail below `eps` frames per second — the whole trail, at 30 fps
-        // with the Frost Trap's `eps` 30, is half the edges it should hold.
+        // Emission: the reference commits `floor(dt·eps + phase)` edges a frame, carries the
+        // fraction as the phase and backdates each inside the frame (`0x7b7f60`).
         if let Some((node, axis)) = head {
-            // BIRTH fold: the node and its cross-section axis are live WORLD values (the owner's
-            // bone matrix); an edge is committed in the store's frame. Off a transport this is the
-            // identity, which is the whole world.
+            // Birth fold: the live world node and axis into the store's frame.
             let (node, axis) = match to_deck {
                 Some(inv) => (inv.transform_point3(node), inv.transform_vector3(axis)),
                 None => (node, axis),
@@ -563,9 +376,7 @@ pub(crate) fn simulate_ribbons(
             *accumulator += def.edges_per_second * dt;
             let n = accumulator.floor().max(0.0);
             *accumulator -= n;
-            // Sub-frame backdating: the n-th edge of this frame was emitted `k/n · dt` ago (the
-            // node itself only has this frame's position, so the sample point is shared — the
-            // backdate is what the age, and therefore the gravity rise, is measured from).
+            // The edges share this frame's node; each ages, and rises, from its backdated birth.
             let n = (n as usize).min(MAX_EDGES.saturating_sub(edges.len()));
             for k in 0..n {
                 let back = dt * (n - 1 - k) as f32 / n as f32;
@@ -578,25 +389,16 @@ pub(crate) fn simulate_ribbons(
             }
         }
 
-        // Write the strip into the shared stream: live head first (while the owner lives), then
-        // committed edges newest→oldest. u slides with age across the tex-slot cell (the
-        // texture's transparent tail is the fade); v spans the cell band. An idle trail — no
-        // strip yet, or a non-resident texture — pushes nothing and commits nothing: the old
-        // "don't rewrite an already-empty mesh" guard is now the structure itself.
+        // The strip, head first: `u` slides with age across the tex-slot cell, `v` spans its band.
         if !images.contains(&*texture) {
             continue;
         }
-        // The gate again, on the DRAW: `0x7080c2` skips the whole record when the byte is 0, so a
-        // gated-off ribbon shows nothing — not a fading remainder. The sim above still ran (edges
-        // age and expire exactly as `ribbonage` ages them), which is what makes the trail resume
-        // mid-strip rather than from empty when the byte comes back.
+        // The gate on the draw (`0x7080c2`): a gated-off ribbon shows nothing, while its edges
+        // still age as `0x7b7e60` ages them, so it resumes mid-strip.
         if !lit {
             continue;
         }
-        // An invisible MODEL has no streamer: the reference's ribbon render leg reads the owning
-        // model's render alpha and drops the draw below a threshold (decision 0827). This is what
-        // takes your own weapon's enchant trail out of your face in first person, and keeps a
-        // not-yet-shown unit's trail off the screen while its body is still at alpha 0.
+        // An invisible model draws no streamer: a first-person weapon's, a unit's not yet shown.
         if alpha_src.is_some_and(|e| model_alphas.get(e) <= 1e-3) {
             continue;
         }
@@ -614,27 +416,21 @@ pub(crate) fn simulate_ribbons(
             f32::from(cell / cols) / f32::from(rows),
             f32::from(cell / cols + 1) / f32::from(rows),
         );
-        // RAW authored RGB — the gamma decode happens once in the effect shader (decision 0152),
-        // covering the texture term too. Alpha is a blend weight, raw.
+        // Raw authored RGB and alpha: the effect shader decodes gamma once, texture included.
         let rgb = def.color.sample_ms(ms);
         let rgba = [rgb[0], rgb[1], rgb[2], def.alpha.sample_ms(ms).max(0.0)];
-        // The trail's SORT anchor — the live head node (the point the material path's entity
-        // translation used to carry; same sort-tie flashing fix as the particle clouds).
-        // Draining trails anchor on their newest surviving edge.
-        // DRAW fold: stored → world (`0xcf5b68 = A · T · S`). The live head is already world —
-        // it was never committed.
+        // The sort anchor: the live head, or a draining trail's newest edge. The draw fold maps
+        // stored to world (`0xcf5b68 = A · T · S`); the head is already world.
         let out = |p: Vec3| to_world.map_or(p, |a| a.transform_point3(p));
         let anchor = head.map(|(node, _)| node).unwrap_or_else(|| {
             let e = edges.back().expect("n >= 2 ⇒ edges exist while draining");
             out((e.top + e.bottom) * 0.5)
         });
         entity_tf.translation = anchor;
-        // Post-propagation frame: publish directly (see the particle sim's matching note; trail
-        // entities live at the world root, the direct write is exact).
+        // After propagation, so publish directly; trail entities sit at the world root.
         *entity_global = GlobalTransform::from(*entity_tf);
-        // The edge sequence, head first then newest→oldest — each consecutive pair becomes one
-        // quad whose corner order reproduces the old strip's exact triangles: strip triangles
-        // (t₀,b₀,t₁),(b₀,b₁,t₁) = quad [b₀,b₁,t₁,t₀] under the lane's [0,1,2, 0,2,3] pattern.
+        // Each consecutive pair is one quad `[b₀, b₁, t₁, t₀]`, which the lane's `[0,1,2, 0,2,3]`
+        // splits into the strip's triangles `(t₀, b₀, t₁)` and `(b₀, b₁, t₁)`.
         let mut pairs: Vec<(Vec3, Vec3, f32)> = Vec::with_capacity(n);
         if let Some((node, axis)) = head {
             pairs.push((node + axis * h_above, node - axis * h_below, 0.0));
@@ -670,24 +466,16 @@ pub(crate) fn simulate_ribbons(
                 cam,
                 texture: texture.id(),
                 blend: def.blend.into(),
-                // params.x = the per-blend fog-colour policy (the M2 batch state setter's
-                // table, `0x70baf0` / wow-re ROUND 4 — ribbons ride the same trio): additive
-                // trails fog toward BLACK, fading under the storm veil instead of adding grey;
-                // alpha/opaque trails fog toward the scene colour. (No ribbon authors the
-                // particle "unfogged" file flag — pass 0.)
+                // The M2 batch state's per-blend fog colour (`0x70baf0`): additive trails fog
+                // toward black, the rest toward the scene colour. No ribbon has the unfogged flag.
                 fog: EffectFog::for_blend(0, def.blend),
-                // Ribbons keep the lane's unlit default: the M2 ribbon record has no flag word
-                // to read the particle path's unlit bit off, and the trail corpus is additive
-                // weapon/spell art authored to burn at its own colour. Revisit only with a
-                // byte law for the ribbon batch state, not by analogy with particles.
+                // Unlit: the ribbon record has no flag word for the particles' unlit bit, and the
+                // reference's ribbon batch lighting is untraced.
                 lighting: crate::particles::buffer::EffectLighting::None,
                 anchor,
-                // The owner rung, dropped under the water pass when the MODEL sits on the eye's
-                // far side of its water plane — the model's bound centre with the bound-radius
-                // slack, never the whipping head node (0921: the ribbon leg reads the model's
-                // side-A boolean verbatim, `0x7081f1`). The model frame is `alpha_src` — "the
-                // MODEL INSTANCE" — with the owner (possibly a joint) seconding as the walk
-                // seed; an unresolvable matrix falls back to the sign test at the head.
+                // The owner rung, dropped under the water pass when the model's bound, radius
+                // slack included, is on the eye's far side of its water plane (`0x7081f1`); with
+                // no model matrix, the head's side decides.
                 bias: *bias
                     + if crate::particles::model_far_side(
                         &interleave,
@@ -712,15 +500,13 @@ pub(crate) fn simulate_ribbons(
     }
 }
 
-/// Registers the per-frame ribbon simulation. Trails are spawned by the model spawn sites
-/// (creatures, held items, missiles, spell effects, doodads) via [`spawn_ribbon`].
+/// Registers the per-frame ribbon simulation; the model spawn sites call [`spawn_ribbon`].
 pub struct RibbonPlugin;
 
 impl Plugin for RibbonPlugin {
     fn build(&self, app: &mut App) {
-        // PostUpdate, after the billboard joint palette — same law and reason as the particle
-        // sim: a trail node on a billboarded/animated bone must sample the frame the palette
-        // just wrote (see `billboard_joint_palette`'s consumer note).
+        // After the billboard joint palette and the rig worlds: a node on a billboarded or
+        // animated bone samples the palette this frame wrote.
         app.init_resource::<RibbonVerdict>().add_systems(
             PostUpdate,
             simulate_ribbons
@@ -735,11 +521,6 @@ impl Plugin for RibbonPlugin {
 mod tests {
     use super::gravity_step;
 
-    /// The per-frame gravity term telescopes to the closed form the bytes imply: stepping
-    /// `gravity · ((2·age) + dt) · dt` and advancing `age` by `dt` leaves an edge exactly
-    /// `gravity · t²` from where it was emitted, **whatever the frame rate** — which is the
-    /// property that makes a trail look the same at 30 and 144 fps. Sign included: positive
-    /// gravity rises.
     #[test]
     fn gravity_telescopes_to_g_t_squared_at_any_frame_rate() {
         for &g in &[0.5_f32, 1.0, 1.5, 2.0, 5.0, -1.0] {
@@ -758,16 +539,13 @@ mod tests {
                 );
             }
         }
-        // The sign is the half that was inverted: a positive gravity RISES.
+        // A positive gravity rises.
         assert!(gravity_step(2.0, 0.0, 0.016) > 0.0);
         assert!(gravity_step(-1.0, 0.0, 0.016) < 0.0);
     }
 
-    /// The Frost Trap's four low streamers, with their authored `gravity` and `edgeLifetime`:
-    /// each rises `g·L²` = 0.605 / 1.000 / 1.215 / 1.280 yd over an edge's life, from a node at
-    /// model z 0.129. That is the compact tuft standing off a crown whose own geometry stops at
-    /// z 0.637 — and it is what the old constant-velocity fall (1.1–3.2 yd DOWNWARD from the
-    /// twelve upper streamers at z 1.55) turned into a column reaching the ground.
+    /// The Frost Trap's four low streamers (authored `gravity`, `edgeLifetime`) rise `g·L²` over an
+    /// edge's life from a node at model z 0.129, clearing the crown's own geometry at z 0.637.
     #[test]
     fn frost_trap_low_rig_rises_into_a_tuft_over_the_crown() {
         for (g, life, want) in [
diff --git a/crates/benilla-world/src/ride_frame.rs b/crates/benilla-world/src/ride_frame.rs
index 140d7315..54df3647 100644
--- a/crates/benilla-world/src/ride_frame.rs
+++ b/crates/benilla-world/src/ride_frame.rs
@@ -1,34 +1,20 @@
-//! The **ride frame** — `[CM2Model+0x17c]`, the world matrix of the transport a model is riding.
+//! The ride frame, `[CM2Model+0x17c]`: the world matrix of the transport a model is riding.
 //!
-//! A world-mode particle cloud (`0x10` CLEAR) and *every* ribbon trail store their committed
-//! content in absolute coordinates and never re-apply a live matrix to it. That is what makes a
-//! trail: run past a torch and the smoke hangs where it was born. On a **transport** the same
-//! rule would stream a rider's effects off the stern, so the reference stores them in the
-//! transport's frame instead and re-projects them live at draw. The mechanism is one matrix
-//! entering at exactly two sites, and they are inverses (wow-re
-//! `system/models/scratch/attach-matrix-is-the-transport-matrix.md`, §5 trio + orchestrator
-//! arbitration; benilla decision 1591, which named this gap and left it unbuilt):
+//! World-mode particle clouds (`0x10` clear) and every ribbon store committed content in absolute
+//! coordinates, so on a transport the reference stores them in the transport's frame and
+//! re-projects them live at draw. One matrix enters at two inverse sites:
 //!
 //! ```text
-//! A = translate(transport.pos) · Rz(transport.facing)    // 0x630ac0 — position and Z-facing only
-//!   = NULL for a model not riding anything
-//!
-//! BIRTH  0x7b5160:  rt+0x1fc = srcMx · A⁻¹      (A ≠ 0 and 0x100 CLEAR; else verbatim)
-//! DRAW   0x7b3d20:  0xcf5b68 = A · T · S        (0x100 CLEAR, [ebp+8] ≠ 0; else T·S)
-//! EDGE   0x7187f0:  on A changing NULL↔non-NULL, re-express every ALREADY-LIVE particle's
+//! A = translate(transport.pos) · Rz(transport.facing)    // 0x630ac0, NULL when not riding
+//! BIRTH  0x7b5160:  rt+0x1fc = srcMx · A⁻¹      (A ≠ 0 and 0x100 clear; else verbatim)
+//! DRAW   0x7b3d20:  0xcf5b68 = A · T · S        (0x100 clear, [ebp+8] ≠ 0; else T·S)
+//! EDGE   0x7187f0:  on A changing NULL↔non-NULL, re-express every live particle's
 //!                   position and velocity (0x7b5e60) and every ribbon's (0x7b7bc0)
 //! ```
 //!
-//! So a rider's effects are *stored* on the deck and *drawn* through the deck's live pose — they
-//! hang still relative to the deck, and boarding or leaving re-expresses the cloud instead of
-//! snapping it. The residual over a particle's life is exactly `A(t₀)⁻¹·A(t₁)`: the **transport's**
-//! motion since birth, never the host unit's own.
-//!
-//! **Where `A` lives.** On the MODEL, not the bone and not the emitter — and the reference copies
-//! the parent's pointer down to every child model each frame (`0x7142c1`, inside `m2_animate`), so
-//! a held weapon's enchant streamer inherits its wearer's transport without knowing anything about
-//! it. Our model child list is [`crate::model_fade::ParentModel`], so [`RideFrames`] walks that
-//! same chain — one component on the rider, inherited by everything hung off it.
+//! `A` lives on the model, not the bone or emitter, and the reference copies the parent's pointer
+//! to every child model each frame (`0x7142c1`, in the animate kernel `0x714260`), so
+//! [`RideFrames`] walks the [`crate::model_fade::ParentModel`] chain.
 
 use bevy::ecs::system::SystemParam;
 use bevy::math::Affine3A;
@@ -36,57 +22,35 @@ use bevy::prelude::*;
 
 use crate::model_fade::{ParentModel, MAX_MODEL_CHAIN};
 
-/// **This model instance is riding a transport** — the reference's `[CM2Model+0x17c]`, as the
-/// transport's entity rather than a copied matrix (the pose is read live, so a stored copy could
-/// only go stale).
-///
-/// Written by the layer that knows who is standing on what (`benilla-app`'s transport module) on
-/// the **rider's own model entity**; everything chained to it through [`ParentModel`] — held
-/// items, their enchant glows, spell kits — inherits it through [`RideFrames`], exactly as the
-/// reference's per-frame child copy does.
+/// This model instance rides a transport: `[CM2Model+0x17c]`, held as the transport's entity so
+/// the pose is read live. Set on the rider's own model; its [`ParentModel`] chain inherits it.
 #[derive(Component, Clone, Copy, Debug, PartialEq, Eq)]
 pub struct RideFrame(pub Entity);
 
-/// `A = translate(pos) · Rz(facing)` from a transport's live pose — **position and Z-facing only**,
-/// which is all `0x630ac0` builds it from (vtable `+0x14` position, `+0x18` Z-facing). Scale and
-/// any pitch/roll are deliberately dropped: `A` is a rigid ride-frame, and its inverse is applied
-/// to already-committed content, so anything non-rigid here would shear a live cloud.
-///
-/// Dropping pitch/roll is also what keeps gravity frame-free: world down is invariant under a yaw,
-/// so a stored cloud integrates with the same `-Y` on a deck as on the ground.
+/// `A = translate(pos) · Rz(facing)` from a transport's live pose: position and Z-facing only, all
+/// `0x630ac0` builds it from (vtable `+0x14`, `+0x18`). Yaw-only, it leaves gravity frame-free.
 pub fn ride_matrix(gt: &GlobalTransform) -> Affine3A {
     let (_, rot, translation) = gt.to_scale_rotation_translation();
     let yaw = rot.to_euler(EulerRot::YXZ).0;
     Affine3A::from_rotation_translation(Quat::from_rotation_y(yaw), translation)
 }
 
-/// Resolve a model instance's ride frame by walking the [`ParentModel`] chain — the reference's
-/// per-frame propagation of `[model+0x17c]` down the child list (`0x7142c1`), as a lookup.
-///
-/// Read-only and cheap: the chains are 1–3 links (unit → item → glow) and the walk stops at the
-/// first [`RideFrame`], so a world that is riding nothing pays one failed component fetch per
-/// emitter.
+/// A model instance's ride frame, looked up along its [`ParentModel`] chain: the reference's
+/// per-frame copy of `[model+0x17c]` down the child list (`0x7142c1`).
 #[derive(SystemParam)]
 pub struct RideFrames<'w, 's> {
     chain: Query<'w, 's, (Option<&'static RideFrame>, Option<&'static ParentModel>)>,
 }
 
-/// `WOW_NO_RIDE_FRAME=1` — the **A/B lever** (the shape `WOW_NO_FRAME_PACE` and
-/// `WOW_NO_RIG_REBASE` set): resolve no ride frame at all, which is the pre-1591 behaviour where a
-/// rider's world-mode effects are stored against the world and stream off the back of the deck.
-///
-/// It earns its branch because this law is *only* observable on a moving transport: an A/B needs a
-/// lift, a live login and a census on both sides, and without the lever the "before" half is a
-/// second checkout and a cold build every time anyone asks. Read once — an emitter asks this
-/// question every frame.
+/// `WOW_NO_RIDE_FRAME=1` resolves no ride frame, an A/B lever: a rider's effects then stream off
+/// the deck.
 fn disabled() -> bool {
     static OFF: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *OFF.get_or_init(|| std::env::var_os("WOW_NO_RIDE_FRAME").is_some())
 }
 
 impl RideFrames<'_, '_> {
-    /// The transport `instance` rides, inherited from its model chain. `None` on the ground —
-    /// which is every model in the world that is not standing on a boat, a zeppelin or a lift.
+    /// The transport `instance` rides, inherited from its model chain.
     pub fn source(&self, instance: Entity) -> Option<Entity> {
         if disabled() {
             return None;
@@ -105,24 +69,17 @@ impl RideFrames<'_, '_> {
     }
 }
 
-/// The frame an emitter's already-committed content is stored in, and the edge detector that keeps
-/// it honest — the state behind the reference's `0x7187f0` re-expression.
-///
-/// Carries the transport's **entity** (the identity: has the frame changed?) *and* its last-known
-/// **matrix** (the value: what a leave must re-express through, which must survive the transport
-/// itself despawning).
+/// The frame an emitter's committed content is stored in, and the edge detector behind the
+/// reference's `0x7187f0` re-expression. The entity says whether the frame changed; the last
+/// matrix outlives a despawned transport, since leaving re-expresses through it.
 #[derive(Clone, Copy, Default)]
 pub struct StoredFrame(Option<(Entity, Affine3A)>);
 
 impl StoredFrame {
-    /// Move the store to `now`, returning the rigid transform every already-stored **point** must
-    /// be re-expressed by (directions take its rotation) — `None` when the frame kept its identity,
-    /// which is the steady state both on the ground and while riding.
-    ///
-    /// Boarding folds `A⁻¹` (world → deck), leaving folds the old `A` (deck → world), and stepping
-    /// from one transport straight to another does both. The reference only wires the NULL↔non-NULL
-    /// edges, because `SetMoveBase` clears before it sets; composing the two is the same answer for
-    /// the case it never sees.
+    /// Move the store to `now`, returning the transform every stored point is re-expressed by
+    /// (directions take its rotation), or `None` while the transport is unchanged. Boarding folds
+    /// `A⁻¹`, leaving the old `A`, and a transport-to-transport step both: the reference wires only
+    /// the NULL↔non-NULL edges, since `SetMoveBase` clears before it sets.
     pub fn retarget(&mut self, now: Option<(Entity, Affine3A)>) -> Option<Affine3A> {
         let fold = match (self.0, now) {
             (None, Some((_, a))) => Some(a.inverse()),
@@ -134,8 +91,7 @@ impl StoredFrame {
         fold
     }
 
-    /// The live `A` stored content is expressed in — `None` in world space, where every fold in
-    /// this module is the identity and costs nothing.
+    /// The live `A` stored content is expressed in; `None` in world space.
     pub fn matrix(&self) -> Option<Affine3A> {
         self.0.map(|(_, a)| a)
     }
@@ -145,26 +101,24 @@ impl StoredFrame {
         self.0.map_or(p, |(_, a)| a.transform_point3(p))
     }
 
-    /// `stored → world` for a **direction** (a velocity): rotation only.
+    /// `stored → world` for a direction (a velocity): rotation only.
     pub fn dir_to_world(&self, v: Vec3) -> Vec3 {
         self.0.map_or(v, |(_, a)| a.transform_vector3(v))
     }
 
-    /// The transport whose frame this store is expressed in — for instruments, which need to name
-    /// the deck a trail is measured against.
+    /// The transport whose frame this store is expressed in.
     pub fn source(&self) -> Option<Entity> {
         self.0.map(|(e, _)| e)
     }
 
-    /// The store's own rotation — `Rz(facing)` — for a stored ORIENTATION rather than a point
-    /// (a 3-D model particle's instance quat).
+    /// The store's rotation, `Rz(facing)`, for a stored orientation (a model particle's quat).
     pub fn rotation(&self) -> Quat {
         self.0
             .map_or(Quat::IDENTITY, |(_, a)| Quat::from_mat3a(&a.matrix3))
     }
 
-    /// `world → stored`: the birth fold (`rt+0x1fc = srcMx · A⁻¹`), for the one-off world reads
-    /// that have to come back (a ground-snap probe hit).
+    /// `world → stored`: the birth fold (`rt+0x1fc = srcMx · A⁻¹`), for a world read that must
+    /// come back (a ground-snap hit).
     pub fn to_stored(&self, p: Vec3) -> Vec3 {
         self.0.map_or(p, |(_, a)| a.inverse().transform_point3(p))
     }
@@ -181,9 +135,7 @@ mod tests {
         )
     }
 
-    /// The steady states — on the ground and riding — must fold NOTHING. A re-expression that
-    /// fired every frame while riding would drag the cloud along with the deck twice over, which is
-    /// the rigid-ride bug the trail law exists to avoid.
+    /// A per-frame fold while riding would move the cloud with the deck twice.
     #[test]
     fn only_the_boundary_re_expresses() {
         let mut f = StoredFrame::default();
@@ -191,15 +143,13 @@ mod tests {
         let a = deck(Vec3::new(10.0, 5.0, 0.0), 0.5);
         assert!(f.retarget(Some(a)).is_some(), "board");
         assert!(f.retarget(Some(a)).is_none(), "riding, deck unmoved");
-        // The SAME transport at a NEW pose is still the same frame: the draw's live `A` carries
-        // the cloud, so nothing stored may be touched. This is the whole mechanism.
+        // The same transport at a new pose is the same frame: the draw's live `A` carries it.
         let moved = (a.0, Affine3A::from_translation(Vec3::new(10.0, 40.0, 0.0)));
         assert!(f.retarget(Some(moved)).is_none(), "the lift rose");
         assert!(f.retarget(None).is_some(), "leave");
     }
 
-    /// Boarding must leave a live particle exactly where it was in the world: the birth fold and
-    /// the draw fold are inverses, so `A · (A⁻¹ · p) == p`.
+    /// The birth and draw folds are inverses: `A · (A⁻¹ · p) == p`.
     #[test]
     fn boarding_moves_nothing_on_screen() {
         let mut f = StoredFrame::default();
@@ -214,8 +164,6 @@ mod tests {
         );
     }
 
-    /// …and leaving is the same identity in the other direction, so stepping off a moving lift
-    /// hands the cloud back to the world where it stood rather than snapping it to the origin.
     #[test]
     fn leaving_hands_the_cloud_back_in_place() {
         let mut f = StoredFrame::default();
diff --git a/crates/benilla-world/src/rig_anim.rs b/crates/benilla-world/src/rig_anim.rs
index 8b6f6d8a..f6ca92e6 100644
--- a/crates/benilla-world/src/rig_anim.rs
+++ b/crates/benilla-world/src/rig_anim.rs
@@ -1,23 +1,7 @@
-//! **The rig machinery the renderer needs** — pose storage, the pose post-pass window, the rig
-//! world composition, and the free-running global-sequence channels.
-//!
-//! Split out of `creature_anim` by 1160 stage two, along the line 1163 drew when it re-checked
-//! `finalize_rig_worlds` and found it was not gameplay behaviour at all: "its entire input set is
-//! rig/transform data, and its only `crate::` references are `billboard`, `rig_palette` and
-//! `WorldCamera` — all three engine. **Mis-filing, not behaviour.**" The same is true of the pose
-//! evaluator beside it (its only cross-module reference is `billboard`) and of the global-sequence
-//! driver (which has none at all).
-//!
-//! The line between this and what stayed is **machinery versus policy**. Evaluating an
-//! `AnimationPlayer` into per-bone locals, composing those into world matrices and palette rows,
-//! and running a model's free channels are things a second program must do to put an animated
-//! model in a world — so they are engine, and `benilla-worldview` gets them for free. *Which* clip
-//! a unit plays, when a mount rider re-seats, when a rig is worth parking — that is a game's
-//! business and stayed in `creature_anim`.
-//!
-//! [`AnimParked`] sits here for the same reason: `creature_anim::lod` decides *when* to park (a
-//! policy, reading net entities and the target), but the marker gates the pose evaluator and the
-//! billboard joint pass, both of which are here.
+//! The rig machinery the renderer needs: pose storage, the pose post-pass window, the rig world
+//! composition and the free-running global-sequence channels. Which clip a unit plays and when a
+//! rig parks are the game's policy (`creature_anim`); [`AnimParked`] lives here because it gates
+//! the pose evaluator and the billboard joint pass.
 
 use bevy::prelude::*;
 
@@ -30,14 +14,13 @@ pub use compose::{finalize_rig_worlds, PosePost};
 pub use global_seq::GlobalSeqDrive;
 pub use pose::{RigAnchor, RigFrame, RigPose};
 
-/// This rig's per-bone pose evaluation is parked (decision 0448): the pose evaluator and the pose
-/// post-passes skip it. The sequence clocks, the driver state machine, and the event scanner all
-/// keep running — parking turns *sampling* off, nothing else.
+/// Parks this rig's per-bone pose evaluation: the evaluator and the pose post-passes skip it,
+/// while the sequence clocks, the driver state machine and the event scanner keep running.
 #[derive(Component)]
 pub struct AnimParked;
 
-/// Wire the rig machinery in. Registered by `WorldPlugins`, so a program with no game still poses
-/// and composes the rigs it spawns.
+/// Registers the rig machinery; `WorldPlugins` adds it, so a program with no game still poses its
+/// rigs.
 pub fn plugin(app: &mut App) {
     global_seq::plugin(app);
     pose::plugin(app);
diff --git a/crates/benilla-world/src/rig_anim/compose.rs b/crates/benilla-world/src/rig_anim/compose.rs
index 749bc59e..e7aec4dc 100644
--- a/crates/benilla-world/src/rig_anim/compose.rs
+++ b/crates/benilla-world/src/rig_anim/compose.rs
@@ -1,36 +1,9 @@
-//! The collapsed rig's two composition passes (decision 0724) — what transform propagation and
-//! the billboard joint pass used to do through ~59 k bone entities, done on the [`RigPose`]
-//! arrays instead.
-//!
-//! **Model pass** ([`compose_rig_models`], pre-propagation): a pose-dirty rig forward-folds its
-//! `locals` into model-space affines — **including the `flags & 0x7` parent-matrix arm**, which
-//! needs nothing but model space (`RigPose::compose`) — and re-seats its consumer **anchors**
-//! (children of the rig's `joints_root`) from them, so ordinary propagation carries every consumer
-//! subtree (held items, nested effect rigs, the mount seat) at this frame's pose, exactly as the
-//! joint hierarchy did. Runs after [`PosePost`] (body twist, global sequences — the writers that
-//! follow the evaluator).
-//!
-//! **World pass** ([`finalize_rig_worlds`], post-propagation, inside
-//! [`crate::billboard::BillboardPlace`]): per rig needing it — pose-dirty, `joints_root` moved,
-//! or camera-faced — compose the chain `world_from_model × local…` **with the root's translation
-//! zeroed** (decision 0974: the whole chain runs rig-relative, because composing it at the map's
-//! ~9.5 k-yard coordinates spent an f32 ULP — ~1 mm — per matmul, freshly every frame), apply the
-//! byte-law bone replacements (`billboard_joint_palette`'s math verbatim: the arm again, in its
-//! world-space form, then billboard kinds take the camera basis, and descendants chain onto the
-//! replaced frames), write the palette rows (`frame × inverse_bindpose`, decision 0720) beside the
-//! rig's world origin (which the vertex stage adds back camera-relative), and re-seat the
-//! anchors sitting on replaced subtrees — including the same rigid-child re-walk and the same
-//! nested-rig do-not-enter rule as the entity pass. A re-seated subtree that carries another
-//! rig's model frame (the mounted rider's seat anchor, [`RigFrame`]) cascades: that rig
-//! re-finalizes in the same pass, so its palette never lags its seat.
-//!
-//! The arm appearing in BOTH passes is not a double application — each pass builds its own chain
-//! once, in its own space, and the two agree (see `RigPose::compose`). What it is NOT allowed to
-//! be is world-pass-only: the anchors are seated from the model pass, so an arm that ran only
-//! afterwards left every attached subtree riding the un-armed frame (decision 0945).
-//!
-//! A parked, stationary rig runs neither pass and uploads zero bytes (decision 0448's park
-//! observables carry over unchanged).
+//! The collapsed rig's two passes over the [`RigPose`] arrays. The model pass
+//! ([`compose_rig_models`]) folds locals into model space, the `flags & 0x7` arm included, and
+//! re-seats the anchors before propagation; the world pass ([`finalize_rig_worlds`]) composes
+//! rig-relative with the billboard camera basis, writes the palette rows and re-seats replaced
+//! subtrees. The arm runs in both passes, each on its own chain, so it is not applied twice; it
+//! must run in the model pass, since the anchors are seated from it.
 
 use bevy::mesh::skinning::SkinnedMeshInverseBindposes;
 use bevy::prelude::*;
@@ -41,23 +14,12 @@ use crate::view::WorldCamera;
 
 use super::{AnimParked, RigFrame, RigPose};
 
-/// The pose post-pass window: every writer of [`RigPose`] locals that runs after the evaluator
-/// (the body twist, the global-sequence channels) is a member; the model compose runs after the
-/// whole set. Configured after [`bevy::app::AnimationSystems`], before transform propagation.
+/// The pose post-pass window: the locals writers after the evaluator, before the model compose.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PosePost;
 
-/// Pre-propagation: fold each pose-dirty rig's locals into model-space affines and re-seat its
-/// anchors' local `Transform`s, so this frame's propagation places every consumer subtree at
-/// this frame's pose. `pose_dirty` stays raised — the world pass consumes and clears it.
-///
-/// A PARKED rig skips even this (decision 1365): the doodad lane's hosts are born pose-dirty and
-/// spend most of their residency parked with the flag still raised (the world pass, which clears
-/// it, also skips parked rigs), so an unfiltered pass re-composed every parked host's bind pose
-/// every frame. Nothing observable is lost — a parked rig's anchors were seated by its last
-/// composed frame (or by `RigPose::new`/`anchor_for` at bind pose), its consumers are out of the
-/// draw set by the same gate that parked it, and the wake drops the marker before this pass runs,
-/// so the first unparked frame composes the current pose before anything reads it.
+/// Fold each pose-dirty rig into model space and re-seat its anchors, leaving `pose_dirty` for
+/// the world pass. A parked rig is skipped; its wake unparks it before this runs.
 fn compose_rig_models(
     mut rigs: Query<&mut RigPose, Without<AnimParked>>,
     mut anchors: Query<&mut Transform>,
@@ -85,21 +47,16 @@ fn compose_rig_models(
     }
 }
 
-/// Translate a composed rig-relative frame back into world space (decision 0974).
+/// Translate a composed rig-relative frame back into world space.
 fn shift(g: GlobalTransform, origin: Vec3) -> GlobalTransform {
     let mut a = g.affine();
     a.translation += bevy::math::Vec3A::from(origin);
     GlobalTransform::from(a)
 }
 
-/// One rig's chain + which bones sit in a replaced subtree, composed **in the root's frame**: the
-/// caller passes `root_g` with its translation zeroed, so every frame out is rig-relative
-/// (decision 0974) and the whole chain runs at rig-sized magnitudes. `root_g` is otherwise the
-/// rig's `joints_root` propagated world — the model's own root frame `[model+0xfc]`, which is both
-/// what the `flags & 0x7` arm rebuilds a parent matrix out of and, for a mounted rider, its seat
-/// anchor (`0x714389`). `cam` is the camera basis (`None` = no camera, so only the arm applies).
-/// The math mirrors `billboard_joint_palette` operation for operation — rewrite the parent matrix,
-/// compose the local, then face — so the collapsed lane is bit-compatible with the entity lane.
+/// One rig's chain and its replaced bones from `root_g`, the root frame `[model+0xfc]` (for a
+/// rider, its seat anchor, `0x714389`), passed translation-zeroed; mirrors
+/// `billboard_joint_palette`.
 fn rig_worlds(
     rig: &RigPose,
     root_g: GlobalTransform,
@@ -114,8 +71,7 @@ fn rig_worlds(
             Some(p) => worlds[p],
             None => root_g,
         };
-        // `flags & 0x7` first: it changes the INPUT the billboard law is applied to, and the
-        // billboard switch below still runs (wow-re `billboard-bone-law.md` §9.1).
+        // The arm first (`0x714961`): it rewrites the billboard's input.
         let mut g = match rig.arms[i] {
             Some(arm) => {
                 touched[i] = true;
@@ -145,12 +101,8 @@ fn rig_worlds(
     (worlds, touched)
 }
 
-/// Seed one collapsed rig's palette rows from its CURRENT composed pose — the doodad lane's
-/// lazy-promote edge (decision 1365, the 0863 wake): the slot is claimed mid-frame and the
-/// skinned mesh swaps in the same frame, so the rows must be written NOW or the first skinned
-/// frame renders zeroed (origin-collapsed) rows. No camera basis — a billboard bone seeds at its
-/// composed pose and the world pass re-faces it this same frame (the promoted host is unparked
-/// and `has_billboard` puts it in the refresh set).
+/// Seed a rig's rows from its composed pose when the doodad lane claims its slot mid-frame, as
+/// the skinned mesh swaps in that same frame.
 pub(crate) fn seed_rig_rows(
     rig: &RigPose,
     root_g: GlobalTransform,
@@ -164,23 +116,12 @@ pub(crate) fn seed_rig_rows(
     palettes.write_rig_worlds(skin, &worlds, ibp, origin);
 }
 
-/// Post-propagation (inside `BillboardPlace`, chained after the entity lane's
-/// `billboard_joint_palette` and before `face_billboards`): finalize every rig that needs it —
-/// palette rows + replaced-subtree anchor re-seats, with the seat-frame cascade.
-#[allow(clippy::type_complexity)] // billboard_joint_palette's shape
+/// The world pass: palette rows, anchor re-seats and the seat-frame cascade.
+#[allow(clippy::type_complexity)]
 pub fn finalize_rig_worlds(
     cam: Query<&GlobalTransform, With<WorldCamera>>,
-    // `Option<&RigSkin>`, not `&RigSkin` (decision 1365): the doodad lane's rigs hold their
-    // palette slot lazily (allocated at first wake, reaped under pressure), and a slot-less rig
-    // still needs this pass for two things — clearing `pose_dirty` (or the model pass re-composes
-    // it every frame for ever) and, when it authors billboard/arm bones, the camera-dependent
-    // anchor re-seat its cards and emitters ride. The palette write alone is skipped.
-    // `Has<RigRider>`: a rider owns its slot's rows from the OTHER end (decision 1609 — the
-    // placement is composed in the HOST's rig frame, never from this absolute one), and decision
-    // 2281 gave that lane a posed arm, so an animated ranged prop arrives here with both a pose
-    // and a skin and must still not have its rows written twice from two different frames.
-    // Everything else this pass does for it — clearing `pose_dirty`, re-seating the anchors its
-    // emitters ride — is exactly what it needs.
+    // A slot-less doodad rig still needs `pose_dirty` cleared and its anchors re-seated; a
+    // `RigRider`'s rows are the rider lane's.
     mut rigs: Query<(
         Entity,
         &mut RigPose,
@@ -188,8 +129,7 @@ pub fn finalize_rig_worlds(
         Has<AnimParked>,
         Has<crate::rig_rider::RigRider>,
     )>,
-    // B0001: the `Changed` filter reads `GlobalTransform` ticks, which conflicts with the
-    // mutable frame query — a `ParamSet` sequences them (the refresh set is collected first).
+    // The `Changed` filter conflicts with the mutable query; the refresh set is collected first.
     mut worlds_params: ParamSet<(
         Query<(), Changed<GlobalTransform>>,
         Query<(&Transform, &mut GlobalTransform), Without<WorldCamera>>,
@@ -204,13 +144,8 @@ pub fn finalize_rig_worlds(
         .single()
         .ok()
         .map(|t| (*t.forward(), *t.right(), *t.up()));
-    // Which rigs refresh this frame: pose-dirty, model frame moved, or camera-faced — and never
-    // a parked one (decision 0739). The LOD gate ruled a parked rig un-viewable, so neither an
-    // idle's pose_dirty, a patrol's root motion, nor a billboard face can matter until the wake
-    // — which drops the marker before the same frame's pose evaluation, re-raising `pose_dirty`
-    // before this pass runs, so a woken rig's rows are current before anything draws them. (The
-    // world-space rows of a moving parked rig go stale on purpose — nothing reads them; at the
-    // LBRS pin the parked-but-patrolling re-writes were ~260 of the ~620 per-frame refreshes.)
+    // Refresh a rig that is pose-dirty, whose model frame moved or that billboards, never a parked
+    // one: its rows go stale on purpose, and the wake re-raises `pose_dirty` before this runs.
     let refresh: Vec<Entity> = {
         let roots_changed = worlds_params.p0();
         rigs.iter()
@@ -226,15 +161,11 @@ pub fn finalize_rig_worlds(
     if refresh.is_empty() {
         return;
     }
-    // The `WOW_RIG_COST` compose meter (decision 0736): how many rigs refresh and what the
-    // whole finalize pass costs, beside the palette's copy/write and upload lines.
     let cost_t0 = crate::rig_palette::rig_cost_enabled().then(std::time::Instant::now);
     let mut globals = worlds_params.p1();
-    // The rigid-child re-walk's do-not-enter set, exactly the entity pass's: a nested rig with
-    // its own billboard output owns its interior (and its root keeps the propagated frame).
+    // As in the entity pass, the re-walk does not enter a nested rig with its own billboard output.
     let fx_roots: bevy::platform::collections::HashSet<Entity> =
         hosts.iter().map(|r| r.root()).collect();
-    // Model frames re-seated by a patch walk → the rigs riding them re-finalize below.
     let mut cascade: Vec<Entity> = Vec::new();
     let mut finalize =
         |rig: &mut RigPose,
@@ -242,24 +173,15 @@ pub fn finalize_rig_worlds(
          globals: &mut Query<(&Transform, &mut GlobalTransform), Without<WorldCamera>>,
          cascade: &mut Vec<Entity>,
          root_moved: bool| {
-            // A slot-less rig with no special bones has nothing left for this pass: no rows to
-            // write, and its anchors were placed by the model pass + ordinary propagation. The
-            // caller still clears `pose_dirty` — which is the point of arriving here at all.
+            // A slot-less rig without special bones is done; the caller clears `pose_dirty`.
             if skin.is_none() && !rig.has_special && !root_moved {
                 return;
             }
             let Ok(root_g) = globals.get(rig.joints_root).map(|(_, g)| *g) else {
                 return;
             };
-            // **The chain is composed RIG-RELATIVE** (decision 0974): same root basis, translation
-            // zeroed. Every operation below — the `flags & 0x7` arm, the local compose, the
-            // billboard replacement — is translation-equivariant (the arm is 3×3 work plus a
-            // pivot-preserving translation; the billboard rewrites rotation only), so this yields
-            // exactly the world chain shifted by `−origin`, at rig-sized magnitudes. That is the
-            // fix: composing at Elwynn's ~9.5 k yards spent an f32 ULP (~1 mm) per matmul, freshly
-            // every frame because the pose is recomposed every frame, and that is the shimmer.
-            // (`WOW_NO_RIG_REBASE=1` makes this the map origin — the A/B lever for what the
-            // rebase is worth; see `rig_palette::rebase_origin`.)
+            // Rig-relative, which translation-equivariant steps allow: at ~9.5 k yards an f32 ULP
+            // (~1 mm) per matmul, fresh each frame, shimmers. `WOW_NO_RIG_REBASE=1` turns it off.
             let origin = crate::rig_palette::rebase_origin(root_g.translation());
             let root_rel = crate::rig_palette::rebase_global(root_g, origin);
             let (worlds, touched) = rig_worlds(rig, root_rel, cam_basis);
@@ -271,26 +193,15 @@ pub fn finalize_rig_worlds(
             if !rig.has_special && !root_moved {
                 return;
             }
-            // Anchors in replaced subtrees: re-seat their globals and re-compose their rigid
-            // children from the replaced frames — the entity pass's child walk, anchor-rooted.
-            //
-            // `root_moved` widens that to EVERY anchor. The touched-only rule assumes propagation
-            // already placed an untouched anchor correctly, and that assumption dies the moment
-            // this rig's own model frame is re-seated after propagation ran: a mounted rider's
-            // seat is patched here, so every one of its anchors is standing on the pre-patch
-            // frame. Its palette rows are rebuilt from `root_g` either way, which is why the BODY
-            // looked right while its attached items rode the stale seat — the mounted pauldron
-            // swinging on the gallop while the shoulder under it did not (decision 0945).
+            // Re-seat the anchors in replaced subtrees, or every anchor when a rider's seat moved
+            // after propagation, and re-compose their rigid children.
             let mut stack: Vec<(Entity, GlobalTransform)> = Vec::new();
             for &(bone, anchor) in &rig.anchors {
                 let b = bone as usize;
                 if !root_moved && !touched.get(b).copied().unwrap_or(false) {
                     continue;
                 }
-                // Anchors are ordinary scene-graph entities: their `GlobalTransform` is world
-                // space and every consumer (propagation, colliders, the effect lane, item
-                // placement) reads it as such — so the rig-relative frame goes back to absolute
-                // here. Only the PALETTE stays relative; that is the whole seam (decision 0974).
+                // Anchors are world-space scene entities; only the palette stays rig-relative.
                 let Some(world) = worlds.get(b).map(|&w| shift(w, origin)) else {
                     continue;
                 };
@@ -324,15 +235,12 @@ pub fn finalize_rig_worlds(
             continue;
         };
         let rig = rig.into_inner();
-        // A rider's rows are the rider lane's (see the query's note): hand `finalize` no skin so
-        // it does the anchors and nothing else.
+        // A rider's rows are the rider lane's: no skin, so only the anchors.
         let skin = skin.filter(|_| !rider);
         finalize(rig, skin, &mut globals, &mut cascade, false);
         rig.pose_dirty = false;
     }
-    // The cascade: a patch walk above moved some rig's model frame after it (or before it) ran —
-    // re-finalize against the fresh seat. One level deep by construction (a seat anchor's
-    // subtree holds no further seat anchors).
+    // Re-finalize each rig whose seat a patch walk moved; one level deep by construction.
     if !cascade.is_empty() {
         for (holder, rig, skin, _, rider) in &mut rigs {
             if !cascade.contains(&holder) {
@@ -354,8 +262,7 @@ pub fn finalize_rig_worlds(
     }
 }
 
-/// Register the model pass; the world pass is chained by [`crate::billboard::BillboardPlugin`]
-/// between the entity lane's joint pass and the card facing, where its readers sit.
+/// Register the model pass; [`crate::billboard::BillboardPlugin`] chains the world pass.
 pub fn plugin(app: &mut App) {
     app.configure_sets(
         PostUpdate,
@@ -395,20 +302,8 @@ mod tests {
         }
     }
 
-    /// **The mount seat, in the pass that decides it** — `compose`, pre-propagation, which is what
-    /// consumer anchors (the rider's seat, and every item hanging off the rider) are re-seated
-    /// from. The shape is `RidingHorse`'s: a spine bone that swings with the gallop, and the seat
-    /// bone under it carrying `flags = 0x6`.
-    ///
-    /// The seat must come out with the MODEL's orientation whatever the spine does, while still
-    /// being carried to the position the spine put it at — that is the byte law's pivot-preserving
-    /// tail (wow-re `billboard-bone-law.md` §9.1), and it is the whole reason a galloping horse
-    /// bobs its rider without rocking them. Asserted across a swept spine angle, because a single
-    /// sample cannot tell a discarded rotation from a lucky one.
-    ///
-    /// Pinning it HERE and not only in the world pass is the point of the regression: the arm was
-    /// applied post-propagation first, the anchors were seated from the un-armed matrix, and the
-    /// mounted pauldron swung 53° over the stride while the shoulder it hung off stood still.
+    /// `RidingHorse`'s seat, in the model pass: under a swinging spine, the `flags = 0x6` bone
+    /// keeps the model's orientation and rides the spine's position (`0x714caf`–`0x714d09`).
     #[test]
     fn a_flags_0x6_seat_bone_discards_the_gallop_before_the_anchors_are_seated() {
         let sk = skeleton(vec![
@@ -434,7 +329,7 @@ mod tests {
                 seat_rot.angle_between(Quat::IDENTITY) < 1e-4,
                 "the seat keeps the model's orientation at spine swing {swing}: got {seat_rot:?}"
             );
-            // …and it still RIDES the spine: the pivot is where the animated parent put it.
+            // It still rides the spine: the pivot is where the animated parent put it.
             let want = rig.model[1].transform_point3(Vec3::new(0.0, 0.5, 0.25));
             assert!(
                 (seat_pos - want).length() < 1e-4,
@@ -453,9 +348,6 @@ mod tests {
         );
     }
 
-    /// The model compose is the exact affine product entity propagation computed: a three-bone
-    /// chain with rotation + non-uniform scale folds to the same matrices as chained
-    /// `GlobalTransform::mul_transform`.
     #[test]
     fn compose_matches_entity_propagation() {
         let sk = skeleton(vec![
@@ -468,9 +360,7 @@ mod tests {
         rig.locals[1].scale = Vec3::new(2.0, 1.0, 0.5);
         rig.locals[1].rotation = Quat::from_rotation_x(-0.3);
         rig.compose();
-        // The oracle: GlobalTransform chaining from an identity root, exactly what propagation
-        // did through the joint entities. Compared as matrices — decomposing two identical
-        // affines can NaN an `angle_between` on a dot marginally past 1.
+        // Compared as matrices: decomposing two identical affines can NaN an `angle_between`.
         let mut g = GlobalTransform::IDENTITY;
         for i in 0..3 {
             g = g.mul_transform(rig.locals[i]);
@@ -483,10 +373,6 @@ mod tests {
         }
     }
 
-    /// The world pass reproduces `billboard_joint_palette`'s replacements: a lock-Z billboard
-    /// bone takes the camera basis (pivot/scale kept), its child chains onto the replaced frame,
-    /// and a `flags & 0x4` helper takes the model root's basis while its pivot still rides the
-    /// animated parent — the entity pass's three verified behaviours, computed from the arrays.
     #[test]
     fn world_pass_matches_the_entity_billboard_law() {
         let sk = skeleton(vec![
@@ -521,19 +407,17 @@ mod tests {
             Some(cam),
         );
         assert_eq!(touched, vec![true; 3], "the whole chain is replaced");
-        // Bone 0: pivot at the root-rotated authored spot, scale kept, lock-Z basis — upright
-        // kept axis, local −Z toward the viewer (the billboard.rs test's assertions).
+        // Bone 0: pivot at the root-rotated authored spot, scale kept, upright, facing the viewer.
         let (s0, r0, t0) = worlds[0].to_scale_rotation_translation();
         assert!((t0 - root_rot * Vec3::new(5.0, 1.0, 0.0)).length() < 1e-4);
         assert!((s0 - Vec3::splat(2.0)).length() < 1e-5, "scale preserved");
         assert!((r0 * Vec3::Y).dot(Vec3::Y) > 0.999, "kept axis upright");
         assert!((r0 * -Vec3::Z).dot(Vec3::Z) > 0.999, "faces the camera");
-        // Bone 1 chains onto the REPLACED parent: one parent-scaled unit up the new Y.
+        // Bone 1 chains onto the replaced parent: one parent-scaled unit up the new Y.
         let (s1, _, t1) = worlds[1].to_scale_rotation_translation();
         assert!((t1 - (t0 + r0 * (Vec3::Y * 2.0))).length() < 1e-4, "{t1}");
         assert!((s1 - Vec3::ONE).length() < 1e-5, "2 × 0.5 scale chain");
-        // Bone 2 (flags & 0x4): pivot carried by the animated parent's frame, basis taken from
-        // the model root — the parent here is unit-scaled, so the ratio leg reproduces it exactly.
+        // Bone 2 (`flags & 0x4`): pivot from the animated parent, basis from the model root.
         let (_, r2, t2) = worlds[2].to_scale_rotation_translation();
         let expect_t = worlds[1].transform_point(Vec3::Y);
         assert!((t2 - expect_t).length() < 1e-4, "pivot rides the parent");
@@ -543,8 +427,6 @@ mod tests {
         );
     }
 
-    /// An unreplaced chain has no touched bones and composes root × model verbatim — the common
-    /// rig costs the palette rows and nothing else.
     #[test]
     fn plain_rigs_touch_nothing() {
         let sk = skeleton(vec![joint(-1, Vec3::X), joint(0, Vec3::Y)]);
@@ -563,25 +445,14 @@ mod tests {
         }
     }
 
-    /// **The jitter pin** (decision 0974) — the measurement the rebase exists for.
-    ///
-    /// Compose the same idling six-bone chain frame by frame two ways — rooted at Goldshire's real
-    /// world coordinates, and rooted at the rig's own origin with the position carried alongside —
-    /// and score each against an f64 oracle of the identical chain. What matters is not the error
-    /// but its **frame-to-frame variation**: a constant offset is invisible, a per-frame one is
-    /// shimmer. The absolute route re-rounds to the f32 grid at ~9.5 k yards (1 ULP ≈ 0.98 mm)
-    /// every frame *because the pose changes every frame* — that is the long-standing "characters
-    /// look jittery up close" the director reported, and terrain is exempt only because it doesn't
-    /// move. The rebased chain runs at rig-sized magnitudes where an ULP is ~0.1 µm.
-    ///
-    /// Pinned as a ratio and an absolute ceiling: someone re-rooting this chain in world space
-    /// again — the natural-looking simplification — puts the shimmer straight back.
+    /// One idling chain composed at Goldshire's coordinates and rig-relative, each scored by how
+    /// its error against an f64 oracle changes per frame: at ~9.5 k yards an f32 ULP is ~0.98 mm,
+    /// re-rounded every frame; rig-relative it is ~0.1 µm.
     #[test]
     fn the_rebased_chain_does_not_re_round_at_world_scale_every_frame() {
         use bevy::math::{DAffine3, DVec3};
 
-        // Goldshire. `.go xyz -9464 62 56 0` — near the worst |coord| the 1.12 maps reach, and
-        // exactly where the report came from. Deliberately not integers: 9464.0 is exact in f32.
+        // Goldshire (`.go xyz -9464 62 56 0`), not integers, as 9464.0 is exact in f32.
         const ROOT: Vec3 = Vec3::new(-9464.31, 62.17, 56.91);
         const AMP: [f32; 6] = [0.010, 0.012, 0.008, 0.015, 0.020, 0.014]; // a breathing idle
 
@@ -595,10 +466,7 @@ mod tests {
         ]);
         let mut rig = RigPose::new(Entity::PLACEHOLDER, &sk);
         let tip = sk.joints.len() - 1;
-        // A FACING, and bones that swing on two axes. Without both, a chain whose motion happens to
-        // miss the large world axis measures almost nothing — an all-about-X rig at this root left
-        // the ~9.5 k x-coordinate static and scored 40× better than it has any right to. A real
-        // skeleton's limbs move in all three world axes; the pin has to too.
+        // A facing and two-axis swings, or the motion can miss the large world axis.
         let root_yaw = Quat::from_rotation_y(0.9);
 
         // The same chain in f64, from an identity root: the truth both routes are scored against.
@@ -641,13 +509,10 @@ mod tests {
         }
         let jitter = |e: &[DVec3]| e.windows(2).map(|w| w[1].distance(w[0])).sum::<f64>() / 179.0;
         let (abs_j, rel_j) = (jitter(&abs_err), jitter(&rel_err));
-        // The real per-frame motion of the tip — what the noise above has to be read against.
+        // The tip's real per-frame motion, the yardstick for the noise.
         let signal = jitter(&truths);
 
-        // `--nocapture` prints the measurement this pin was written from (yards):
-        //   abs_err 5.2e-4  rel_err 9.6e-8 | abs_j 7.4e-4  rel_j 1.0e-7 | signal 1.6e-3
-        // i.e. 0.74 mm of FRESH noise per frame against 1.65 mm of real motion — 45 % of a slow
-        // idle's apparent movement was rounding — and 1 Å after the rebase.
+        // Measured with `--nocapture` (yards): abs_j 7.4e-4, rel_j 1.0e-7, signal 1.6e-3.
         eprintln!(
             "abs_err mean={:.3e} rel_err mean={:.3e} abs_j={abs_j:.3e} rel_j={rel_j:.3e} \
              signal={signal:.3e} noise/signal abs={:.2} rel={:.5}",
@@ -656,7 +521,7 @@ mod tests {
             abs_j / signal,
             rel_j / signal,
         );
-        // The sweep has to actually move the tip, or every number above is measuring nothing.
+        // The idle must move the tip, or every number above measures nothing.
         assert!(
             signal > 1e-4,
             "the idle really does move the tip: {signal:.3e}"
diff --git a/crates/benilla-world/src/rig_anim/global_seq.rs b/crates/benilla-world/src/rig_anim/global_seq.rs
index 285a457b..d687ec8a 100644
--- a/crates/benilla-world/src/rig_anim/global_seq.rs
+++ b/crates/benilla-world/src/rig_anim/global_seq.rs
@@ -1,69 +1,36 @@
-//! Global-sequence bone channels — free-clock loops *independent* of the playing animation (the
-//! character eye-blink eyelid scale; resting fidget pulses; a spell effect's star twinkles).
-//! benilla's per-sequence reader deliberately drops them: they key off their own global-sequence
-//! timer, not the playing sequence's time band (`benilla_formats::parse_m2_animations`). This
-//! samples them on the instance's global-sequence clock and writes the driven joint components
-//! *after* the [`AnimationPlayer`] posed the skeleton.
-//!
-//! Ground truth (wow-5875-re `gseq-anchor.md`, byte-verified): the cursor is
-//! `(sceneClock − instanceAttachTime) % duration` — ONE free-running per-scene ms clock
-//! (`[scene+0xc]`, advanced once per scene update), snapshotted ONCE per model instance at attach
-//! (`CM2Model+0x68`, written unconditionally at `0x70eae1`). So a fresh instance starts its
-//! global sequences at phase 0, and two instances attached on different frames run at different
-//! phases — per-INSTANCE anchoring, not per-play arming (sequence tracks re-arm per play; the
-//! gseq anchor is stamped once). Spell effects are NOT an exception: the lifecycle is
-//! byte-verified fresh-per-play (wow-re `gseq-instance-lifecycle.md`: CreateModel always
-//! alloc→ctor→attach, teardown is a hard free, no pooling), and the director's own 3-cast
-//! apitrace shows the impact flash at the same +16-frame offset every cast — the apparent
-//! cast-to-cast scatter is particle randomness plus the moving cast-anim hands, not clock
-//! phase (decisions 0855/0856/0858). The canonical creature consumer is the eyelid:
-//! its scale is `0` (lid retracted, eye open) for ~96% of the loop and `1` (lid full, eye shut)
-//! for ~100 ms — the blink. Without this pass the eyelid sits at its default identity scale
-//! (full size) forever: eyes shut.
+//! Global-sequence bone channels: loops on a free clock (the eyelid blink, fidget pulses, an
+//! effect's twinkles), which the per-sequence reader drops. The reference's cursor is
+//! `(sceneClock − attachTime) % duration`, one ms clock per scene (`[scene+0xc]`) snapshotted once
+//! per model instance at attach (`CM2Model+0x68`, `0x70eae1`); a spell effect is a fresh instance
+//! per play (`0x707350`, freed at `0x70e170`, no pooling).
 
 use bevy::prelude::*;
 
 use benilla_assets::GlobalBone;
 
-/// One channel's write target: a live joint entity (the doodad/effect/booth lane) or a bone index
-/// into the host's [`super::RigPose`] locals (the collapsed unit lane, decision 0724).
+/// A joint entity (doodad, effect, booth) or a bone of the host's [`super::RigPose`].
 enum SeqTarget {
     Joint(Entity),
     Bone(u16),
 }
 
-/// Per-instance driver for a model's global-sequence bone channels: each channel's write target
-/// paired with its baked channels, plus the instance's clock **anchor** — the attach-time
-/// snapshot of the shared scene clock (`CM2Model+0x68`, module docs). Attached beside the
-/// [`AnimationPlayer`] on a skinned instance whose model carries any global-sequence track.
+/// A model instance's global-sequence channels and clock anchor.
 #[derive(Component)]
 pub struct GlobalSeqDrive {
-    /// `(write target, its baked global-sequence channels)`.
     bones: Vec<(SeqTarget, GlobalBone)>,
-    /// The attach snapshot of this instance's SCENE clock (secs): `None` until the first animate
-    /// tick stamps it (the instance's attach — the ref writes `+0x68` once, at attach).
+    /// The scene clock at attach (secs), stamped once, like the reference's `+0x68`.
     anchor: Option<f64>,
-    /// **This instance's scene clock**, when it is not the world's (secs). The kernel's Phase B
-    /// reads `[[model+0x2c]+0xc]` — the clock of the scene that OWNS the instance — and a
-    /// `<Model>` widget owns a private `CM2Scene` at `CSimpleModel+0x314`, advanced by the
-    /// widget's own `OnUpdate` and by nothing else (wow-re `gseq-anchor.md` §1/§2 +
-    /// `modelframe-animation-clock.md` §1.1/§3, both byte-verified). So a UI model tile writes
-    /// its pane's clock here every frame it draws and the phase rides the pane, not the world:
-    /// a pane whose frame is hidden stops its clock, and the spin resumes where it stopped.
-    /// `None` — every world lane — is the world scene's free-running clock (decision 2046).
+    /// The owning scene's clock (secs) when it is not the world's: the reference reads
+    /// `[[model+0x2c]+0xc]`, and a `<Model>` widget owns a private scene (`CSimpleModel+0x314`,
+    /// `0x76cfc0`) advanced only by its `OnUpdate` (`0x76d7f0`), so a hidden pane's clock stops.
     clock: Option<f64>,
-    /// Paused: skip the joint writes (the doodad host gates animation to drawn instances — wow-re
-    /// `doodad-anim-host.md`: the ref's kernel ticks at draw time, so a culled model isn't
-    /// evaluated). Creatures never pause. Resuming needs no re-seek: the cursor is a pure
-    /// function of the shared clock and the attach anchor, so a re-appearing doodad shows the
-    /// pose the clock dictates.
+    /// Skip the writes: the doodad lane pauses culled instances, as the reference evaluates a
+    /// model only when drawn (`0x707680`). The cursor is absolute, so a resume needs no seek.
     paused: bool,
 }
 
 impl GlobalSeqDrive {
-    /// Map each of the model's global-sequence bones to this instance's joint entity. `None` when the
-    /// model has no global-sequence tracks (the common case) or none resolve to a joint — the entity
-    /// then gets no component and the driver skips it.
+    /// Map the model's global-sequence bones to this instance's joint entities.
     pub fn new(global_bones: &[GlobalBone], joints: &[Entity]) -> Option<Self> {
         let bones: Vec<_> = global_bones
             .iter()
@@ -81,8 +48,7 @@ impl GlobalSeqDrive {
         })
     }
 
-    /// The collapsed-rig lane (decision 0724): channels write the host's [`super::RigPose`]
-    /// locals by bone index — no joint entities exist. Same `None` gate as [`Self::new`].
+    /// The collapsed-rig lane: channels write the host's [`super::RigPose`] locals by bone index.
     pub fn new_rig(global_bones: &[GlobalBone], nbones: usize) -> Option<Self> {
         let bones: Vec<_> = global_bones
             .iter()
@@ -97,30 +63,19 @@ impl GlobalSeqDrive {
         })
     }
 
-    /// Pause/resume the joint writes — the doodad draw gate's lever, and its only caller. (The
-    /// booth and UI-tile lanes park instead, with [`super::AnimParked`] on the root, which holds
-    /// the pose evaluation and the compose as well as these writes; this pause holds only the
-    /// writes, which is what the doodad lane wants for a host whose player it also stops.) While
-    /// paused the joints hold their last pose; resume lands on the anchored cursor with nothing
-    /// to catch up.
+    /// Hold only the writes, for the doodad draw gate; [`super::AnimParked`] also holds the pose.
     pub fn set_paused(&mut self, paused: bool) {
         self.paused = paused;
     }
 
-    /// Point this instance's channels at its own scene clock (secs) — see [`Self::clock`]. Written
-    /// per frame by the owner of a scene that is not the world's; never called by a world lane.
+    /// Set this instance's scene clock (secs), each frame, for a scene that is not the world's.
     pub fn set_clock(&mut self, secs: f64) {
         self.clock = Some(secs);
     }
 }
 
-/// Sample every drive's channels at its anchored cursor (`sceneNow − anchor`, stamping the
-/// anchor on the first tick — the attach) and write the driven bone — in the pose post-pass
-/// window ([`super::PosePost`], the same as the body twist), so the model compose folds it. A
-/// channel overwrites only its own component; a bone the playing animation never keyed (the
-/// eyelid) keeps its rest translation/rotation and takes only the global scale, so the eye opens
-/// and blinks over whatever gait is playing. The cursor wraps per channel in f64 (`t % period`)
-/// so a long-uptime clock keeps millisecond precision through the f32 sampler.
+/// Sample each drive at `sceneNow − anchor`, wrapped in f64 for a long uptime, and write only the
+/// driven components, so the eyelid blinks over any gait.
 fn apply_global_sequences(
     time: Res<Time>,
     mut drives: Query<(Entity, &mut GlobalSeqDrive, Has<super::AnimParked>)>,
@@ -129,14 +84,9 @@ fn apply_global_sequences(
 ) {
     let now = time.elapsed_secs_f64();
     for (host, mut drive, parked) in &mut drives {
-        // The clock is the instance's SCENE's — the world's for every world lane, and a `<Model>`
-        // widget's private one where the tile renderer wrote it ([`GlobalSeqDrive::clock`]).
         let scene_now = drive.clock.unwrap_or(now);
-        // The attach stamp happens even while parked/paused — the ref stamps +0x68 at attach,
-        // not at first draw.
+        // Stamped even while parked: the reference stamps `+0x68` at attach, not at first draw.
         let t = scene_now - *drive.anchor.get_or_insert(scene_now);
-        // A parked or paused instance skips only the WRITES — the cursor is absolute
-        // (decision 0448's absolute-clock ruling, now literal: nothing per-instance advances).
         if drive.paused || parked {
             continue;
         }
@@ -188,7 +138,7 @@ mod tests {
             bone: 75,
             translation: None,
             rotation: None,
-            // The real eyelid shape: open (0) at the loop start, shut (1) for the blink window, open again.
+            // The eyelid's shape: open (0), shut (1) for the blink, open again.
             scale: Some(GlobalSeqChannel {
                 period: 6.633,
                 keys: vec![
@@ -201,8 +151,7 @@ mod tests {
         }
     }
 
-    /// A linear-ramp channel (`scale = t`, long period) — phase differences are visible at any
-    /// absolute elapsed.
+    /// A linear ramp (`scale = t`, long period), so a phase difference shows at any elapsed time.
     fn ramp() -> GlobalBone {
         GlobalBone {
             bone: 0,
@@ -215,10 +164,7 @@ mod tests {
         }
     }
 
-    /// The anchor law (0856): a FRESH drive stamps its attach on its first tick, so a drive
-    /// spawned later reads a SMALLER cursor than one spawned earlier (per-instance phase — two
-    /// creatures attached on different frames blink at different times). Ticks are
-    /// deterministic via `TimeUpdateStrategy::ManualDuration`.
+    /// A drive spawned later reads a smaller cursor: the phase is per instance.
     #[test]
     fn fresh_drives_anchor_at_attach() {
         let mut app = App::new();
@@ -233,7 +179,6 @@ mod tests {
             .spawn(GlobalSeqDrive::new(&[ramp()], &[early_joint]).expect("a keyed channel maps"));
         app.update();
         app.update();
-        // A drive attached two ticks later.
         let late_joint = app.world_mut().spawn(Transform::default()).id();
         app.world_mut()
             .spawn(GlobalSeqDrive::new(&[ramp()], &[late_joint]).expect("a keyed channel maps"));
@@ -254,9 +199,6 @@ mod tests {
         );
     }
 
-    /// The eyelid channel itself still samples correctly at a given cursor — the blink window
-    /// reads shut, the long tail reads open (the channel sampler is untouched by the anchor
-    /// work; only who supplies `t` changed).
     #[test]
     fn eyelid_channel_samples_by_clock_value() {
         let bone = eyelid_bone();
@@ -275,12 +217,7 @@ mod tests {
         );
     }
 
-    /// The two write targets of the one sampler agree (decision 1360's second golden, built
-    /// AHEAD of the doodad collapse): the same channels driven through a joint entity
-    /// ([`GlobalSeqDrive::new`], the doodad/effect lane) and through a `RigPose` local
-    /// ([`GlobalSeqDrive::new_rig`], the collapsed lane) read **bit-identically** frame after
-    /// frame — the collapse changes where a sample lands, never what it is. Both drives spawn
-    /// the same frame, so the per-instance anchors coincide by the attach law.
+    /// Both drives spawn on the same frame, so their anchors coincide.
     #[test]
     fn joint_and_rig_targets_write_the_same_pose() {
         let full = GlobalBone {
diff --git a/crates/benilla-world/src/rig_anim/pose.rs b/crates/benilla-world/src/rig_anim/pose.rs
index 70768a8b..d41a7f4c 100644
--- a/crates/benilla-world/src/rig_anim/pose.rs
+++ b/crates/benilla-world/src/rig_anim/pose.rs
@@ -1,22 +1,7 @@
-//! The direct M2 pose evaluator (decision 0712): turn each rig's `AnimationPlayer` state into
-//! bone `Transform`s ourselves, off the baked [`PoseSource`], instead of routing per-bone entities
-//! through Bevy's `animate_targets` (0711's second lane — ~1.9 µs *per bone* of graph-walk +
-//! hash-lookup + boxed-curve machinery to produce, for most bones, a constant).
-//!
-//! The player stays the playback state machine — the driver's arms, cross-fades, weights, seeks,
-//! and completions are untouched — and this system reproduces `animate_targets`' *output* exactly
-//! (the goldens below run both side by side and assert bone-for-bone equality). The law, read from
-//! `bevy_animation-0.18.1` and pinned in 0712: per (bone, property), active nodes contribute in
-//! **ascending node-index order**, folded by `total += w; acc = interpolate(acc, v, w/total)`
-//! (`Vec3::lerp` / `Quat::slerp` — the same `Animatable` calls, so the math is bit-identical); a
-//! node contributes iff its weight ≠ 0 and `bone_masks[bone] & node_mask == 0` and its clip keys
-//! the channel; sampling clamps into the key span; a property no active clip keys is left alone
-//! (there is no rest-pose reset — the joint keeps what it has). Paused animations still evaluate
-//! at their frozen seek, exactly as Bevy does.
-//!
-//! Parking (decision 0448) is the [`AnimParked`] marker: a parked rig is skipped here — clocks,
-//! driver, and events all keep running — which preserves 0448's two observables (absolute-clock
-//! snap on wake, off-screen combat audibility) with no `AnimatedBy` repoint machinery.
+//! The M2 pose evaluator: poses each rig from its `AnimationPlayer` and the baked [`PoseSource`],
+//! matching `bevy_animation` 0.18.1's `animate_targets` bit for bit. Per bone and property, the
+//! contributing nodes (weight not 0, mask clear, channel keyed) fold in ascending node index by
+//! `acc = interpolate(acc, v, w / total)`, and an unkeyed property keeps its value.
 
 use benilla_assets::{ModelAnimations, ModelSkeleton, PoseSource};
 use bevy::animation::animatable::Animatable;
@@ -28,53 +13,34 @@ use bevy::transform::TransformSystems;
 use super::AnimParked;
 use crate::vis_chain::VisChainOnly;
 
-/// The collapsed rig's pose buffer (decision 0724), on the entity carrying the `AnimationPlayer`:
-/// one local `Transform` per bone in skeleton order — no joint entities at all (decision 0712's
-/// `PosedRig` handle grew into this when the ~59 k bone entities collapsed). Every pose writer —
-/// the evaluator below, the body twist, the global-sequence channels — writes `locals` and raises
-/// [`Self::pose_dirty`]; `compose` then folds the parent-sorted chain into per-bone model-space
-/// affines, and the world finalize (`creature_anim::compose`) turns those into palette rows and
-/// consumer-anchor frames.
+/// A rig's pose buffer, one local per bone in skeleton order, on the `AnimationPlayer`'s entity;
+/// writers raise [`Self::pose_dirty`], and `compose` folds the locals into model space.
 #[derive(Component)]
 pub struct RigPose {
-    /// The rig's model-space frame: the holder itself, its conform node, or a mounted rider's
-    /// seat anchor. Its `GlobalTransform` is `world_from_model`; the palette recomputes when it
-    /// moves.
+    /// The model frame: the holder, its conform node or a mounted rider's seat anchor.
     pub joints_root: Entity,
-    /// Per-bone local TRS, skeleton order — what the per-bone joint `Transform`s used to hold.
+    /// Per-bone local TRS, in skeleton order.
     pub locals: Vec<Transform>,
-    /// Per-bone **animated** model-space affine (`parent_model × local`), the product transform
-    /// propagation used to compute through the joint entities. Rebuilt by [`Self::compose`] for a
-    /// dirty rig, WITH the `flags & 0x7` arm folded in — it is model-space-computable and the
-    /// anchors are seated from these. Only the camera-dependent billboard replacement waits for
-    /// the world pass.
+    /// Per-bone model-space affines, `flags & 0x7` arm included; the anchors are seated from these.
     pub model: Vec<Affine3A>,
     pub parents: Vec<i16>,
-    /// The bone's billboard arm (`0x08/0x10/0x20/0x40`), for the world pass's camera replacement.
+    /// The bone's billboard flag (`0x08/0x10/0x20/0x40`), faced to the camera by the world pass.
     pub(crate) kinds: Vec<Option<benilla_formats::BillboardKind>>,
-    /// Bone flags `0x1/0x2/0x4`: how the bone's effective PARENT matrix is rebuilt from the model
-    /// root before it composes (`crate::billboard::parent_arm_matrix`).
+    /// Bone flags `0x1/0x2/0x4`: how the parent matrix is rebuilt from the model root.
     pub(crate) arms: Vec<Option<benilla_formats::ParentArm>>,
-    /// Each bone's BIND local translation — the pivot the arm preserves. `locals` carry the
-    /// ANIMATED translation, which the byte law rotates by the *new* basis; not interchangeable.
+    /// Bind-pose local translations, the pivots the arm preserves; `locals` hold the animated ones.
     pub(crate) binds: Vec<Vec3>,
-    /// Any bone billboards — the world pass re-faces this rig whenever it isn't parked.
     pub(crate) has_billboard: bool,
-    /// Any bone billboards or resets — the world pass's override walk runs at all.
+    /// A bone billboards or carries a parent arm, so the world pass's override walk runs.
     pub(crate) has_special: bool,
-    /// `(bone, anchor entity)` — the consumer anchors (attachments, markers, emitter/ribbon/
-    /// light/billboard-card bones), children of [`Self::joints_root`]. The compose pass re-seats
-    /// their local `Transform`s so ordinary propagation carries every consumer subtree — held
-    /// items, nested effect rigs, the mount seat — exactly as the joint hierarchy did.
+    /// Consumer anchors by bone, children of [`Self::joints_root`], re-seated by the compose pass.
     pub anchors: Vec<(u16, Entity)>,
-    /// A pose writer touched `locals` since the last world pass. Starts `true` so a rig that
-    /// never animates (bind pose) still gets its one palette write.
+    /// `locals` changed since the last world pass; starts raised so the bind pose is written.
     pub pose_dirty: bool,
 }
 
 impl RigPose {
-    /// Build the rig's buffer at bind pose (composed), `pose_dirty` armed for the first palette
-    /// write. Anchors are registered by the spawner as it creates them.
+    /// The rig at bind pose, composed; anchors come from [`Self::anchor_for`].
     pub fn new(joints_root: Entity, skeleton: &ModelSkeleton) -> Self {
         let locals: Vec<Transform> = skeleton
             .joints
@@ -105,23 +71,9 @@ impl RigPose {
         rig
     }
 
-    /// Forward-fold `locals` into `model` — the exact affine product transform propagation
-    /// computed through the joint entities (`parent_global.mul_transform(local)`, model-rooted).
-    /// M2 bones are parent-sorted (the format guarantees parent < child); a malformed child whose
-    /// parent follows it composes from the model root, matching the old hierarchy's `unwrap_or(root)`.
-    ///
-    /// The **`flags & 0x7` arm runs here**, in model space, with the model root as the identity —
-    /// which is what it *is*, relative to this rig. That is not a shortcut around the world-space
-    /// form the world pass uses: a model frame is a similarity (uniform scale), so `root_world ×
-    /// arm(P_model, I)` and `arm(root_world × P_model, root_world)` agree axis for axis, including
-    /// the ratio leg's per-axis magnitudes (the common factor cancels).
-    ///
-    /// Doing it here rather than only in the world pass is load-bearing, not a tidy-up. `model` is
-    /// what the pre-propagation pass re-seats consumer anchors from, so an arm applied only
-    /// afterwards leaves ordinary propagation to carry every attached subtree on the UN-armed
-    /// frame — and the world pass's patch walk deliberately does not enter a nested rig. That is
-    /// how a mounted rider's pauldron ended up riding the horse's gallop while the shoulder it
-    /// hangs off did not (decision 0945).
+    /// Fold `locals` into `model`, the `flags & 0x7` arm included since the anchors are seated
+    /// from it; a model frame is a similarity, so this agrees with the world pass's arm. M2 bones
+    /// are parent-sorted; a malformed child whose parent follows it composes from the root.
     pub(crate) fn compose(&mut self) {
         for i in 0..self.locals.len() {
             let local = self.locals[i].compute_affine();
@@ -141,13 +93,8 @@ impl RigPose {
         }
     }
 
-    /// This rig is rendered by an **off-world camera** (a portrait booth), so the world pass must
-    /// not camera-face its billboard bones: [`finalize_rig_worlds`](super::finalize_rig_worlds)
-    /// takes its basis from the `WorldCamera`, which is not the camera drawing this rig. Dropping
-    /// the kinds leaves those bones at their composed pose — exactly what the entity-joint booth
-    /// lane produced (its joints never carried a `BillboardJointRig`), while the booth's own card
-    /// facer counter-rotates each card's anchor to the booth camera. The `flags & 0x7` parent
-    /// arms stay: that law is camera-free and runs in [`Self::compose`] regardless.
+    /// For a rig drawn by an off-world camera (a portrait booth): drops the billboard kinds, which
+    /// the world pass would face to the `WorldCamera`; the camera-free parent arms stay.
     pub fn without_camera_billboards(mut self) -> Self {
         self.kinds.iter_mut().for_each(|k| *k = None);
         self.has_billboard = false;
@@ -155,19 +102,8 @@ impl RigPose {
         self
     }
 
-    /// The anchor entity standing in for `bone`, spawned on first demand (decision 1355): a
-    /// consumer that needs an *entity* on a bone — a held item's parent, an emitter's owner
-    /// frame, a quest marker's seat — resolves it here, and only bones something actually
-    /// consumes ever get one. At the LBRS pin, 96 % of the eagerly-spawned population hosted
-    /// nothing (decision 1354).
-    ///
-    /// The spawn seats from `model` — the same matrices the compose pass re-seats every anchor
-    /// from — so an anchor created mid-frame (a weapon equipped in combat) stands at the current
-    /// composed pose, never the rest pose. `rig` is the [`RigPose`] holder (`self` cannot know
-    /// its own entity); the anchor parents under [`Self::joints_root`] and dies with it.
-    ///
-    /// `None` = the bone is outside this skeleton (an out-of-range authored reference — the
-    /// consumer misses, as it always has).
+    /// The anchor entity for `bone`, spawned on first demand at the current composed pose under
+    /// [`Self::joints_root`]; `rig` is the [`RigPose`] holder.
     pub fn anchor_for(
         &mut self,
         commands: &mut Commands,
@@ -179,10 +115,7 @@ impl RigPose {
         }
         let m = self.model.get(bone as usize)?;
         let (scale, rotation, translation) = m.to_scale_rotation_translation();
-        // Visibility so an attached subtree (a held item under a hand anchor) inherits the
-        // owner's hide — chain only: an anchor renders nothing, and at the Goldshire pin the
-        // anchor population was the single largest never-rendering block in the per-camera
-        // visibility sweep (4.8k rows, decision 1441).
+        // Chain-only visibility: the anchor draws nothing, but its subtree inherits the hide.
         let anchor = commands
             .spawn((
                 Transform {
@@ -200,17 +133,8 @@ impl RigPose {
         Some(anchor)
     }
 
-    /// The world-space point `offset` under `bone` at the current composed pose — what a
-    /// consumer that only ever *reads* a position (the overhead anchor, a missile launch point,
-    /// the bowstring's nock) gets instead of an anchor entity, so those reads spawn nothing
-    /// (decision 1355). `root_global` is [`Self::joints_root`]'s `GlobalTransform` — exactly the
-    /// frame an anchor's own global would compose through.
-    ///
-    /// One deliberate difference from reading a spawned anchor: `model` carries the composed
-    /// pose with the `flags & 0x7` arm folded in but **not** the world pass's camera-billboard
-    /// replacement. No attachment point or event marker sits on a camera-faced bone (those bones
-    /// carry cards, which stay entity-anchored via [`Self::anchor_for`]), so nothing observable
-    /// rides on the difference.
+    /// The world point `offset` under `bone` at the composed pose, without an anchor entity; it
+    /// skips the camera billboard, which no attachment point or event marker sits on.
     pub fn posed_point(
         &self,
         root_global: &GlobalTransform,
@@ -226,26 +150,23 @@ impl RigPose {
     }
 }
 
-/// On every consumer anchor: which rig and bone it stands in for. The body twist's model-frame
-/// walk splices through it (a mounted rider's chain crosses the mount's seat bone), and the world
-/// pass uses it to cascade a re-seated root into dependent rigs.
+/// On every consumer anchor: the rig and bone it stands for. The body twist's model-frame walk
+/// splices through it (a mounted rider's chain crosses the mount's seat bone).
 #[derive(Component)]
 pub struct RigAnchor {
-    /// The rig holder (the entity carrying [`RigPose`]).
+    /// The rig holder, the entity carrying [`RigPose`].
     pub rig: Entity,
     pub bone: u16,
 }
 
-/// On an entity serving as some rig's `joints_root` while living inside ANOTHER rig's anchor
-/// subtree (the mounted rider's seat anchor under the mount's attachment-0 anchor): the world
-/// pass, having re-seated that subtree, re-finalizes the dependent rig too — its
-/// `world_from_model` moved after propagation ran.
+/// On a rig's `joints_root` inside another rig's anchor subtree (a rider's seat anchor under the
+/// mount's attachment-0 anchor): the world pass re-finalizes the rig after re-seating the subtree.
 #[derive(Component)]
 pub struct RigFrame(pub Entity);
 
 /// One active animation's evaluation inputs, resolved against the rig's [`PoseSource`].
 struct Active {
-    /// `AnimationNodeIndex::index()` — the sort key that reproduces Bevy's blend order.
+    /// `AnimationNodeIndex::index()`, the sort key that reproduces Bevy's blend order.
     node: usize,
     clip: usize,
     mask: u64,
@@ -255,21 +176,14 @@ struct Active {
     cursor: usize,
 }
 
-/// Evaluate every live rig's pose. Runs where `animate_targets` runs — inside [`AnimationSystems`]
-/// after `advance_animations` ticked the seek clocks — so the pose post-passes (body twist,
-/// global-sequence writes) and the model compose see it at the same point in the frame.
+/// Pose every live rig where `animate_targets` runs, after `advance_animations`.
 fn evaluate_rig_poses(
     mut rigs: Query<(&AnimationPlayer, &ModelAnimations, &mut RigPose), Without<AnimParked>>,
 ) {
-    // Parallel over rigs (decision 1945): a rig reads its shared clips and writes only its own
-    // pose, and a raid stands ~400 live rigs / ~12k bones — 0.4 ms of one thread's frame when
-    // walked serially, and this system sits on the main thread's critical path.
+    // Parallel: a rig reads shared clips and writes only its own pose.
     rigs.par_iter_mut().for_each(|(player, anims, mut rig)| {
         let src = &anims.pose;
-        // This rig's contributing animations, ascending by node index (Bevy's effective blend
-        // order — sorted children folded through a LIFO stack, see the module doc). One scratch
-        // per worker thread, reused across rigs: a `Vec` per rig per frame was an allocation
-        // and a free for every live rig on every frame (decision 1979's floor).
+        // The contributing animations in node order, in one scratch per worker thread.
         thread_local! {
             static ACTIVE: std::cell::RefCell<Vec<Active>> =
                 const { std::cell::RefCell::new(Vec::new()) };
@@ -299,8 +213,7 @@ fn evaluate_rig_poses(
             match active.as_mut_slice() {
                 [] => {}
                 [one] => {
-                    // The steady state: one looping gait. A single contribution commits at full
-                    // value whatever its weight (Bevy's register initializes unnormalized).
+                    // One contribution commits at full value whatever its weight.
                     rig.pose_dirty = true;
                     for pb in &src.clips[one.clip].bones {
                         if src.bone_masks.get(pb.bone as usize).copied().unwrap_or(0) & one.mask
@@ -331,17 +244,14 @@ fn evaluate_rig_poses(
     });
 }
 
-/// The multi-animation path (a cross-fade, a masked overlay, the grip): merge-walk the
-/// bone-sorted clips and fold each (bone, property)'s contributions in node order.
+/// Several animations: merge-walk the bone-sorted clips, folding each property in node order.
 fn blend_rig(src: &PoseSource, active: &mut [Active], rig: &mut RigPose) {
-    // Walk the next keyed bone across all clips until every cursor is spent.
     while let Some(bone) = active
         .iter()
         .filter_map(|a| src.clips[a.clip].bones.get(a.cursor).map(|b| b.bone))
         .min()
     {
         let bone_mask = src.bone_masks.get(bone as usize).copied().unwrap_or(0);
-        // Fold each property over the clips keying this bone, in node order (`active` is sorted).
         let mut translation: Option<(Vec3, f32)> = None;
         let mut rotation: Option<(Quat, f32)> = None;
         let mut scale: Option<(Vec3, f32)> = None;
@@ -355,7 +265,7 @@ fn blend_rig(src: &PoseSource, active: &mut [Active], rig: &mut RigPose) {
             };
             a.cursor += 1;
             if bone_mask & a.mask != 0 {
-                continue; // masked out for this node — no contribution, cursor still advances
+                continue; // masked out: no contribution, but the cursor advanced
             }
             fold(&mut translation, pb.translation.sample(a.seek), a.weight);
             fold(&mut rotation, pb.rotation.sample(a.seek), a.weight);
@@ -379,8 +289,7 @@ fn blend_rig(src: &PoseSource, active: &mut [Active], rig: &mut RigPose) {
     }
 }
 
-/// One property's running fold — Bevy's blend register verbatim: the first contribution lands at
-/// full value (carrying its weight), each later one at `w / total`.
+/// Bevy's blend register: the first contribution lands whole, each later one at `w / total`.
 #[inline]
 fn fold<T: Animatable>(register: &mut Option<(T, f32)>, sample: Option<T>, weight: f32) {
     let Some(v) = sample else { return };
@@ -393,8 +302,7 @@ fn fold<T: Animatable>(register: &mut Option<(T, f32)>, sample: Option<T>, weigh
     });
 }
 
-/// Register the evaluator in `animate_targets`' window: after the seek clocks tick, before the
-/// pose post-passes (which order `.after(AnimationSystems)`) and transform propagation.
+/// Register the evaluator in `animate_targets`' window, before the pose post-passes.
 pub fn plugin(app: &mut App) {
     app.add_systems(
         PostUpdate,
@@ -417,7 +325,6 @@ mod tests {
 
     use super::*;
 
-    /// One test clip's authored channels: per bone, optional key lists for T/R/S.
     #[derive(Clone, Default)]
     struct ClipSpec {
         bones: Vec<(u16, BoneSpec)>,
@@ -431,9 +338,7 @@ mod tests {
         s: Vec<(f32, Vec3)>,
     }
 
-    /// Build the graph + clips + pose source from specs, exactly as `m2.rs` does: the Bevy clip
-    /// through `AnimatableCurve`/`AnimatableKeyframeCurve`, the pose twin through
-    /// `PoseTrack`/`PoseClip`, node table beside each graph add.
+    /// Build the graph, clips and pose source from specs, as `m2.rs` does.
     fn build(
         app: &mut App,
         specs: &[ClipSpec],
@@ -526,7 +431,6 @@ mod tests {
         (graph, nodes, pose)
     }
 
-    /// A `ModelAnimations` carrying only what the evaluator reads (graph + pose).
     fn model_anims(graph: Handle<AnimationGraph>, pose: PoseSource) -> ModelAnimations {
         ModelAnimations {
             graph,
@@ -540,9 +444,7 @@ mod tests {
         }
     }
 
-    /// Spawn the two rigs: the Bevy-path oracle (per-joint targets, `animate_targets` evaluates
-    /// it) and the evaluator rig (a joint-less [`RigPose`] buffer). Returns `(oracle_root,
-    /// oracle_joints, ours_root)`.
+    /// The Bevy oracle rig and the evaluator's joint-less rig: `(oracle, oracle_joints, ours)`.
     fn twin_rigs(
         app: &mut App,
         nbones: u16,
@@ -603,9 +505,7 @@ mod tests {
         app
     }
 
-    /// Run `f` identically on both players, then step and assert every bone's local is
-    /// **exactly** equal between the oracle's joint `Transform`s and the evaluator's `locals`
-    /// array — same inputs, same `Animatable` calls, bit-identical outputs.
+    /// Every bone's local is bit-equal between the oracle's joints and the evaluator's `locals`.
     #[track_caller]
     fn assert_twins_equal(app: &mut App, oracle_joints: &[Entity], ours: Entity) {
         let rig = app.world().entity(ours).get::<RigPose>().unwrap();
@@ -620,8 +520,6 @@ mod tests {
         app.update();
     }
 
-    /// Run the same player mutation on each rig — identical inputs is the whole point of the
-    /// twin-rig golden.
     fn drive(
         app: &mut App,
         rigs: &[Entity],
@@ -639,8 +537,7 @@ mod tests {
         }
     }
 
-    /// The steady state (one looping clip): channels present and absent, exact equality mid-loop —
-    /// including a bone the clip never keys (both paths must leave it at its spawn value).
+    /// One looping clip, with a bone it never keys: both paths leave that bone at its spawn value.
     #[test]
     fn single_clip_matches_animate_targets() {
         let mut app = app();
@@ -665,15 +562,13 @@ mod tests {
                         s: vec![(0.0, Vec3::ONE), (0.8, Vec3::splat(2.0))],
                     },
                 ),
-                // bone 2 never keyed — the untouched-property law.
             ],
             mask: 0,
         };
         let (graph, nodes, pose) = build(&mut app, &[spec], vec![0, 0, 0]);
         let (oracle, oj, ours) = twin_rigs(&mut app, 3, &graph, &pose);
-        // One warm-up frame: Bevy's ThreadedAnimationGraphs builds off the graph asset's Added
-        // event, so `animate_targets` bails on the spawn frame (our evaluator doesn't need it and
-        // evaluates immediately — strictly earlier, not different). Compare from frame 2 on.
+        // One warm-up frame: Bevy's `ThreadedAnimationGraphs` builds on the graph asset's `Added`
+        // event, so `animate_targets` skips the spawn frame.
         app.update();
         drive(&mut app, &[oracle, ours], |p, _| {
             p.play(nodes[0]).repeat();
@@ -684,9 +579,6 @@ mod tests {
         }
     }
 
-    /// A cross-fade (`AnimationTransitions::play` mid-flight): main at weight 1 plus the fading
-    /// node's decaying weight — the normalized fold must match Bevy's frame for frame, and the
-    /// past-the-end clamp holds once the one-shot finishes.
     #[test]
     fn crossfade_matches_animate_targets() {
         let mut app = app();
@@ -722,7 +614,6 @@ mod tests {
             tr.play(p, nodes[0], Duration::ZERO).repeat();
         });
         step(&mut app, 0.1);
-        // Cross-fade into the run over 0.25 s; sample mid-fade several times.
         drive(&mut app, &[oracle, ours], |p, tr| {
             tr.play(p, nodes[1], Duration::from_secs_f32(0.25)).repeat();
         });
@@ -732,16 +623,13 @@ mod tests {
         }
     }
 
-    /// The masked upper-body overlay at weight 8 over a full-body base (the driver's one-shot
-    /// route), plus a weight-0 node that must contribute nothing: bones in the mask group blend
-    /// 8:1, bones outside it take the base alone.
     #[test]
     fn masked_overlay_matches_animate_targets() {
         let mut app = app();
         let base = ClipSpec {
             bones: vec![
                 (
-                    0, // "legs" — in mask group 2, the overlay must not touch it
+                    0, // "legs": in mask group 2, so the overlay must not touch it
                     BoneSpec {
                         t: vec![(0.0, Vec3::ZERO), (0.5, Vec3::X)],
                         r: vec![(0.0, Quat::IDENTITY), (0.5, Quat::from_rotation_y(1.0))],
@@ -749,7 +637,7 @@ mod tests {
                     },
                 ),
                 (
-                    1, // "torso" — both drive it, the 8:1 blend
+                    1, // "torso": both drive it, the 8:1 blend
                     BoneSpec {
                         t: vec![(0.0, Vec3::ZERO), (0.5, Vec3::Z)],
                         r: vec![(0.0, Quat::IDENTITY), (0.5, Quat::from_rotation_z(0.7))],
@@ -794,7 +682,6 @@ mod tests {
             )],
             mask: 0,
         };
-        // bone 0 is in mask group 2 (the "outside the upper subtree" group).
         let (graph, nodes, pose) = build(&mut app, &[base, overlay, idle], vec![1 << 2, 0]);
         let (oracle, oj, ours) = twin_rigs(&mut app, 2, &graph, &pose);
         app.update(); // warm-up: see single_clip_matches_animate_targets
@@ -807,8 +694,7 @@ mod tests {
             step(&mut app, 0.07);
             assert_twins_equal(&mut app, &oj, ours);
         }
-        // And the masked bone really is base-only: it moved off spawn (the base wrote it), yet
-        // never took the overlay's parked 9.0 constant.
+        // The masked bone is base-only: it never took the overlay's 9.0 constant.
         let t0 = app.world().entity(ours).get::<RigPose>().unwrap().locals[0];
         assert_ne!(
             t0.translation,
@@ -817,8 +703,7 @@ mod tests {
         );
     }
 
-    /// A parked rig is skipped (the 0448 gate's new mechanism): bones freeze while the clock
-    /// advances; unparking resumes sampling at the absolute clock.
+    /// Parked bones freeze while the clock advances; unparking resumes at the absolute clock.
     #[test]
     fn parked_rig_freezes_bones_only() {
         let mut app = app();
@@ -835,7 +720,7 @@ mod tests {
         };
         let (graph, nodes, pose) = build(&mut app, &[spec], vec![0]);
         let (oracle, oj, ours) = twin_rigs(&mut app, 1, &graph, &pose);
-        // The oracle twin runs unparked throughout — the absolute-clock witness.
+        // The oracle runs unparked throughout: the absolute-clock witness.
         drive(&mut app, &[oracle, ours], |p, _| {
             p.play(nodes[0]).repeat();
         });
@@ -851,19 +736,13 @@ mod tests {
         assert_twins_equal(&mut app, &oj, ours); // woke to the absolute-clock pose
     }
 
-    /// The DOODAD lane's drive pattern (decision 1360's golden, built AHEAD of the collapse):
-    /// the three player mutations `doodad_anim` performs — the FirstSeq arm
-    /// (`play(node).repeat()`), the variation re-roll's snap (`stop_all` + replay,
-    /// `reroll_doodad_variation`), and the draw gate's hide/resume (`stop_all`, then re-arm +
-    /// `seek_to` the absolute clock, `gate_doodad_anim`) — each run identically on the oracle
-    /// and the evaluator rig and asserted bit-equal, wraps and the untouched-property law
-    /// included. Green here means the joint-entity collapse only has to move consumers; the
-    /// drive semantics are already proven shared.
+    /// The doodad lane's three player mutations: the first-sequence arm, the variation re-roll's
+    /// snap (`stop_all`, replay) and the draw gate's hide and resume (`stop_all`, re-arm, seek).
     #[test]
     fn doodad_drive_pattern_matches_animate_targets() {
         let mut app = app();
-        // Clip A keys bones 0+1; clip B keys only bone 1 — so the re-roll snap leaves bone 0 on
-        // clip A's last-applied value on BOTH paths (the no-rest-reset law across a re-arm).
+        // Clip A keys bones 0 and 1, clip B only bone 1: the re-roll leaves bone 0 on A's last
+        // value on both paths.
         let spec_a = ClipSpec {
             bones: vec![
                 (
@@ -907,7 +786,7 @@ mod tests {
         });
         step(&mut app, 0.3);
         assert_twins_equal(&mut app, &oj, ours);
-        step(&mut app, 0.6); // past 0.8 — the repeat wrap
+        step(&mut app, 0.6); // past 0.8: the repeat wrap
         assert_twins_equal(&mut app, &oj, ours);
 
         // 2 · the re-roll snap: stop everything, hard-play the new variation.
@@ -918,15 +797,14 @@ mod tests {
         step(&mut app, 0.2);
         assert_twins_equal(&mut app, &oj, ours); // bone 0 untouched-by-B on both paths
 
-        // 3 · the draw gate's hide: stop (not pause — a paused animation is still sampled;
-        // stopped, both paths leave every target exactly where it stands).
+        // 3 · the draw gate's hide: stop, not pause, since a paused animation is still sampled.
         drive(&mut app, &rigs, |p, _| {
             p.stop_all();
         });
         step(&mut app, 0.15);
         assert_twins_equal(&mut app, &oj, ours);
 
-        // 4 · the resume: re-arm + seek to the shared-clock cursor, the gate's exact calls.
+        // 4 · the resume: re-arm and seek to the shared-clock cursor, the gate's exact calls.
         drive(&mut app, &rigs, |p, _| {
             p.stop_all();
             p.play(nodes[0]).repeat().seek_to(0.37);
diff --git a/crates/benilla-world/src/rig_palette.rs b/crates/benilla-world/src/rig_palette.rs
index 8e8e9132..80657af8 100644
--- a/crates/benilla-world/src/rig_palette.rs
+++ b/crates/benilla-world/src/rig_palette.rs
@@ -1,48 +1,8 @@
-//! The owned skin palette (decision 0720): benilla computes every skinned rig's joint palette
-//! itself and uploads it to a region of the shared light buffer; `wow_model.wgsl`'s vertex stage
-//! skins from it. This replaces Bevy's `SkinnedMesh` lane end to end — `extract_skins`'
-//! world-wide `Changed<GlobalTransform>` sweep and `prepare_skins`' full-staging-buffer rewrite
-//! (both O(everything), measured in decision 0718) become no-ops because no entity carries
-//! `SkinnedMesh` anymore (and no mesh carries Bevy's joint attributes, so the `SKINNED`
-//! pipeline path never compiles).
-//!
-//! The shape mirrors the interior-prop probe table (`lighting::prop_probes`), the house pattern:
-//! a main-world slab ([`RigPalettes`]) whose slots free themselves through a component hook
-//! ([`RigSkin`]'s `on_replace`), `Arc`-shared rows so the render-world extract is a pointer bump,
-//! and a `PrepareResources` upload that writes only what changed — here per-rig **dirty ranges**
-//! (a parked, stationary rig re-uploads nothing) plus the slot table on allocation changes.
-//!
-//! **Palettes are RIG-RELATIVE** (decision 0974): row `b` of rig `r` is
-//! `rig_from_joint(b) × inverse_bindpose(b)`, where `rig_from_joint` is the joint's world frame
-//! with the rig's own world origin subtracted off — same 3×3 as Bevy's `skin_model` would
-//! produce, translation measured from the rig root instead of the map's. The origin itself rides
-//! a parallel per-slot table ([`rig_origin_region_offset`]), and the vertex stage
-//! adds it back **camera-relative**, so a vertex never exists as an absolute world coordinate in
-//! f32. That is the whole point: at Elwynn's ~9.5 k-yard coordinates one f32 ULP is ~1 mm, the
-//! bone chain and the palette each spend one, and because the pose is recomposed every frame the
-//! rounding is *fresh noise every frame* — the long-standing character shimmer. Rig-relative
-//! numbers are ~1 yard, where an ULP is ~0.1 µm. (Rows stay 3 `vec4`s — the affine's rows; the
-//! fourth is implicit `[0,0,0,1]`.)
-//!
-//! The vertex stage reads the part's rig slot from its `MeshTag` rig field (`mesh_tag::rig_bits`),
-//! resolves the rig's base bone index through the slot table, and blends the four indexed bones'
-//! rows by the vertex weights — replacing (not composing with) the mesh's world matrix, exactly
-//! like Bevy skinning, then offsets by `origin − camera`.
-//!
-//! Both writers keep the convention — the collapsed lane ([`RigPalettes::write_rig_worlds`]) is
-//! handed frames already composed from a zero-translation root, so its rows are exact; the entity
-//! lane ([`RigPalettes::write_rig`]) subtracts the holder's world translation off globals Bevy
-//! propagated in absolute space, so its rows inherit whatever rounding propagation already spent
-//! (a named residual — killing it needs a floating origin, not a palette change).
-//!
-//! **Dirtiness is structural, not assumed**: every joint entity carries a [`RigJoint`] marker
-//! (planted by [`spawn_joints`]), and [`compute_rig_palettes`] runs one linear
-//! `Changed<GlobalTransform>` pass over exactly those entities — so *every* writer of a joint's
-//! world pose (the 0712 evaluator, the body twist, global-sequence channels, the billboard joint
-//! pass, a mount's seat, the terrain-conform node, plain movement) marks its rig by construction.
-//! The pass is rig-scoped (≈ the bone population), unlike the Bevy sweep it replaces (the whole
-//! world); Stage B of 0720 replaces it with writer-driven dirtying when the bone entities
-//! themselves collapse.
+//! The owned skin palette: every skinned rig's joint palette, computed here and uploaded to a
+//! region of the shared light buffer that `wow_model.wgsl`'s vertex stage skins from, in place of
+//! Bevy's `SkinnedMesh`. Rows are rig-relative (`rig_from_joint × inverse_bindpose`, the rig's
+//! origin subtracted) and the vertex stage adds `origin − camera` back, so no vertex is an
+//! absolute f32 world coordinate, whose ~1 mm ULP at ~9.5 k yards shimmers every frame.
 
 use std::sync::Arc;
 
@@ -59,24 +19,19 @@ use bevy::render::{Render, RenderApp, RenderSystems};
 use crate::mesh_tag::MAX_RIG_SLOTS;
 use crate::vis_chain::VisChainOnly;
 
-/// Bone capacity of the palette region — concurrently-resident skinned bones across every live
-/// rig (units, animated doodads, spell effects, booths). The LBRS census (0718) holds ~59 k unit
-/// bones + ~1.6 k doodad-rig bones; 128 k is head-room, at 48 B/bone = 6 MB of the shared buffer.
-/// Mirrored by `wow_model.wgsl`'s region declaration — keep in sync.
+/// Bone capacity across every live rig, about twice a Lower Blackrock Spire census (~61 k).
+/// Mirrored by `wow_model.wgsl`'s region declaration: keep in sync.
 pub(crate) const MAX_PALETTE_BONES: usize = 131_072;
 
-/// Bytes per bone in the palette region: 3 × vec4 rows of the affine.
+/// Bytes a bone: 3 `vec4` rows of the affine.
 const BONE_BYTES: u64 = 48;
 
-/// Byte offset of the rig slot table inside the shared light buffer (after the prop-probe
-/// region). One u32 per slot: the rig's base bone index.
+/// Byte offset of the rig slot table (a base bone index a slot), after the prop-probe region.
 pub(crate) fn rig_table_region_offset() -> u64 {
     crate::lighting::prop_probe_region_offset() + (7 * crate::lighting::MAX_PROP_PROBES * 16) as u64
 }
 
-/// Byte offset of the per-slot rig ORIGIN table (decision 0974) — one `vec4` per slot, `xyz` =
-/// the world position the rig's rows are measured from (`w` unused). Sits after the instance-tint
-/// table, mirroring `wow_model.wgsl`'s struct order.
+/// Byte offset of the rig origin table (a `vec4` a slot), after the tint table, as in the shader.
 pub(crate) fn rig_origin_region_offset() -> u64 {
     crate::instance_tint::region_offset() + crate::instance_tint::region_bytes()
 }
@@ -86,18 +41,13 @@ pub(crate) fn rig_origin_region_bytes() -> u64 {
     MAX_RIG_SLOTS as u64 * 16
 }
 
-/// Byte offset of the palette rows themselves — after the slot table, the per-instance tint table
-/// that shares this slot index ([`crate::instance_tint`], decision 0812), the origin table, and
-/// the mat-anim delta table ([`crate::mat_anim_table`], decision 1381), and the straddle clip
-/// table ([`crate::straddle`], decision 2188). The rows stay last because `wow_model.wgsl`
-/// declares them as the struct's one runtime-sized array.
+/// Byte offset of the palette rows, after the slot, tint, origin, mat-anim and straddle-clip
+/// tables: last, because `wow_model.wgsl` declares them as the struct's one runtime-sized array.
 pub(crate) fn palette_region_offset() -> u64 {
     crate::straddle::region_offset() + crate::straddle::region_bytes()
 }
 
-/// Total bytes the slot-indexed regions add to every `wow_light`-layout buffer
-/// (`lighting::light_blob_bytes`): the rig slot table, the instance-tint table, the origin table,
-/// the mat-anim table, the straddle clip table, the palette rows.
+/// Total bytes the slot-indexed regions add to every `wow_light`-layout buffer.
 pub(crate) fn palette_regions_bytes() -> u64 {
     (MAX_RIG_SLOTS * 4) as u64
         + crate::instance_tint::region_bytes()
@@ -107,23 +57,19 @@ pub(crate) fn palette_regions_bytes() -> u64 {
         + MAX_PALETTE_BONES as u64 * BONE_BYTES
 }
 
-/// The main-world palette table: rows + slot table behind `Arc` (the extract is a pointer bump),
-/// a slot slab and a coalescing bone-range free list, and the frame's dirty ranges.
+/// The main-world palette table: `Arc`-shared rows and slot table, the slot and bone-range slabs.
 #[derive(Resource)]
 pub struct RigPalettes {
-    /// `3 × MAX_PALETTE_BONES` vec4 rows — the CPU mirror (the mouseover picker reads it).
+    /// `3 × MAX_PALETTE_BONES` rows, the CPU mirror the mouseover picker reads.
     rows: Arc<Vec<[f32; 4]>>,
     /// The row buffer retired by the last clone (`rows_make_mut`), reused once unshared.
     spare: Option<Arc<Vec<[f32; 4]>>>,
     /// Slot → base bone index. Slot 0 is the tag's "no rig" sentinel and never allocated.
     table: Arc<Vec<u32>>,
-    /// Slot → the world position this rig's rows are measured from (decision 0974); `w` unused.
-    /// Written by the same call that writes the rows, so the pair can never disagree.
+    /// Slot → the world position its rows are measured from, written with the rows.
     origins: Arc<Vec<[f32; 4]>>,
-    /// Bumped whenever any origin changes — the origin table's upload gate for the shared buffer.
     origin_generation: u64,
-    /// Bumped only when a MIRRORED slot's origin changes, so a world full of walking creatures
-    /// does not re-push 32 KB into every booth buffer each frame.
+    /// Bumped only for a mirrored slot's origin, so world traffic skips the booth buffers.
     origin_mirror_generation: u64,
     /// Per-slot bone count; 0 = free slot.
     slot_len: Vec<u32>,
@@ -131,28 +77,20 @@ pub struct RigPalettes {
     slot_high: usize,
     /// Free bone ranges `(base, len)`, kept sorted by base and coalesced on free.
     free_ranges: Vec<(u32, u32)>,
-    /// Per slot: whether this rig's rows must ALSO reach the booth mirror buffers
-    /// ([`RigPaletteMirrors`]) — set for booth rigs only, so the world's rig traffic never
-    /// multiplies across the studio buffers.
+    /// Per slot: the rows also reach the booth mirror buffers ([`RigPaletteMirrors`]).
     mirrored: Vec<bool>,
     /// Bone ranges rewritten since the last publish; `.2` = the owning slot was mirrored.
     dirty: Vec<(u32, u32, bool)>,
-    /// Bumped on every alloc/free — the slot table's upload gate.
     table_generation: u64,
-    /// Peak concurrent slots / bones (the overflow diagnostic — near capacity ⇒ grow).
     peak_slots: usize,
     peak_bones: u32,
     live_bones: u32,
-    /// Allocations refused since the last census line (`WOW_RIG_CENSUS`) — the exhaustion
-    /// diagnosis's live denial rate (decision 0863). Read-and-reset by [`census_rig_palettes`].
+    /// Allocations refused since the last `WOW_RIG_CENSUS` line; reset by [`census_rig_palettes`].
     denied: u32,
-    /// Has the exhaustion warn already been logged this session? A latch, not a counter, and
-    /// deliberately never reset: [`Self::denied`] is `mem::take`n by the census, so gating the
-    /// warn on it would re-fire once per census window instead of once per session (2264).
+    /// The exhaustion warning's once-a-session latch, never reset: [`Self::denied`] resets with
+    /// each census, so gating on it would warn once a census window.
     denied_warned: bool,
-    /// `WOW_RIG_COST` meters (decision 0736 premise check): whole-vec deep copies this frame
-    /// (`Arc::make_mut` clones when the extract still holds last publish's reference), the µs
-    /// they took, and the rows (bones) written. Printed + reset by [`publish_rig_palettes`].
+    /// `WOW_RIG_COST` meters, printed and reset by [`publish_rig_palettes`].
     cost_copies: u32,
     cost_copy_us: f32,
     cost_rows: u32,
@@ -186,24 +124,14 @@ impl Default for RigPalettes {
     }
 }
 
-/// `WOW_RIG_COST=1`: the rig lane's per-frame cost split — copy vs compose vs upload — in
-/// grep-and-average lines beside `FPS_PROBE` (the 0736 premise meter; the 0734 lesson made
-/// premise checks law). Zero-cost when off: one env read, once.
+/// `WOW_RIG_COST=1`: per-frame `[rig-cost]` and `[rig-upload]` lines; one env read when off.
 pub fn rig_cost_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_RIG_COST").is_some())
 }
 
-/// Copy-on-write on the shared rows, timing the calls that actually copy: between a publish and
-/// the frame's first write the extract holds a second reference, so that write must clone. A
-/// static helper (not a method) so call sites keep their split-field borrows.
-///
-/// **The clone is bounded by the bone watermark, never the capacity** (decision 1479).
-/// `Arc::make_mut` cloned the whole 3×131072-row vec — ~6.3 MB, once per frame, at every spot in
-/// the world, however few rigs were awake (1473's fixed-tax finding). A fresh zeroed vec is a
-/// calloc — the kernel hands back zero pages untouched — so the real cost is the live-prefix
-/// memcpy alone: ~250 KB at a busy pin. Everything at or above the watermark is bitwise zero by
-/// invariant (see [`RigPalettes::bone_watermark`]), so the prefix IS the whole content.
+/// Copy-on-write on the shared rows: after a publish the extract holds a second reference, so the
+/// frame's first write clones, copying only the live prefix ([`RigPalettes::bone_watermark`]).
 fn rows_make_mut<'a>(
     rows: &'a mut Arc<Vec<[f32; 4]>>,
     spare: &mut Option<Arc<Vec<[f32; 4]>>>,
@@ -214,11 +142,8 @@ fn rows_make_mut<'a>(
     if Arc::strong_count(rows) > 1 || Arc::weak_count(rows) > 0 {
         let t = std::time::Instant::now();
         let live = 3 * watermark_bones as usize;
-        // The retired buffer from two publishes ago, once the render world has let go of it:
-        // copy the live prefix in and take it back. Its tail is stale — and never read: the GPU
-        // only ever receives dirty ranges, so what the CPU vector holds past the watermark
-        // reaches nothing (the calloc'd zeros it replaced were never uploaded either). A fresh
-        // allocation only while the render world still holds both.
+        // Reuse the buffer retired two publishes ago once the render world lets go; its stale
+        // tail is never uploaded, and `alloc` zeroes a range before use.
         let mut new = match spare.take().and_then(|a| Arc::try_unwrap(a).ok()) {
             Some(v) if v.len() == rows.len() => v,
             _ => vec![[0.0f32; 4]; rows.len()],
@@ -228,7 +153,6 @@ fn rows_make_mut<'a>(
         *copy_us += t.elapsed().as_secs_f32() * 1e6;
         *copies += 1;
     }
-    // Uniquely owned now — `make_mut` is a plain borrow.
     Arc::make_mut(rows)
 }
 
@@ -237,22 +161,13 @@ fn rebase(mut world: Affine3A, origin: Vec3) -> Affine3A {
     world
 }
 
-/// [`rebase`]'s `GlobalTransform` face — for the lanes that hand
-/// [`RigPalettes::write_rig_worlds`] frames Bevy propagated in absolute space, and for the
-/// collapsed lane's root (which composes its chain *from* the rebased root).
+/// [`rebase`] for a `GlobalTransform`.
 pub(crate) fn rebase_global(g: GlobalTransform, origin: Vec3) -> GlobalTransform {
     GlobalTransform::from(rebase(g.affine(), origin))
 }
 
-/// The origin a rig's rows are measured from, given its root's world translation — the ONE place
-/// the decision-0974 rebase can be switched off, so no caller can hold half the convention.
-///
-/// `WOW_NO_RIG_REBASE=1` is the A/B lever (the `WOW_NO_MOUNT_TILT` shape): it makes every rig's
-/// origin the *map* origin, so the chain composes in absolute world space and the rows carry
-/// ~9 k-yard translations again — the pre-0974 f32 rounding, and its shimmer, back on animated
-/// characters. The shader needs no branch for it: `frame · v + (0 − camera)` spends the ULP inside
-/// the big-times-small product exactly where the old route spent it inside `clip_from_world ×
-/// p_world`. Zero-cost when unset: one env read, once.
+/// The origin a rig's rows are measured from, its root's world translation: the rebase's one
+/// switch. `WOW_NO_RIG_REBASE=1` makes it the map origin, an A/B that brings the shimmer back.
 pub(crate) fn rebase_origin(root_world: Vec3) -> Vec3 {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     match *ON.get_or_init(|| std::env::var_os("WOW_NO_RIG_REBASE").is_none()) {
@@ -262,15 +177,8 @@ pub(crate) fn rebase_origin(root_world: Vec3) -> Vec3 {
 }
 
 impl RigPalettes {
-    /// Claim a slot + a bone range for a rig. `None` when either slab is exhausted — the caller
-    /// The bone offset above which every row is bitwise ZERO — the COW clone's bound (1479).
-    ///
-    /// The invariant, and why it holds: [`Self::alloc`] is first-fit over a sorted, coalescing
-    /// free list, so allocations pack low; [`Self::free`] zeroes the rows it returns **before**
-    /// the range re-enters the free list (its own `rows_make_mut` call still counts the range as
-    /// live, so the zeroing lands inside the copied prefix); and rows above everything ever
-    /// allocated are zeros from construction. So a tail free range that touches capacity is all
-    /// zeros, and its base bounds the content.
+    /// The bone offset above which no rig is allocated, the copy-on-write clone's bound; first-fit
+    /// allocation over a coalescing free list packs rigs low.
     fn bone_watermark(&self) -> u32 {
         match self.free_ranges.last() {
             Some(&(base, len)) if base + len == MAX_PALETTE_BONES as u32 => base,
@@ -278,13 +186,11 @@ impl RigPalettes {
         }
     }
 
-    /// warns and falls back to the static (bind-pose) mesh, graceful and visible in the log
-    /// rather than wrong.
+    /// Claim a slot and a bone range for a rig; `None` when either slab is exhausted.
     pub(crate) fn alloc(&mut self, bones: u32) -> Option<(u16, u32)> {
         if bones == 0 {
             return None;
         }
-        // First-fit range.
         let (i, &(base, len)) = self
             .free_ranges
             .iter()
@@ -303,10 +209,8 @@ impl RigPalettes {
         } else {
             self.free_ranges[i] = (base + bones, len - bones);
         }
-        // A fresh range starts at zero rows: the spare-buffer reuse (`rows_make_mut`) means the
-        // CPU mirror above the watermark is a previous occupant's pose, and three readers
-        // (`write_rig`'s torn-joint keep, `write_rider`'s unchanged compare, the computed-rig
-        // readbacks) assume an unallocated row is zero (review 2026-09-04).
+        // Zero the range: a reused spare buffer may hold a previous occupant's pose, and
+        // `write_rig`, `write_rider` and `computed_rigs` read a new rig's rows as zero.
         let (r0, r1) = (3 * base as usize, 3 * (base + bones) as usize);
         let wm = self.bone_watermark();
         let rows = rows_make_mut(
@@ -330,9 +234,8 @@ impl RigPalettes {
         Some((slot, base))
     }
 
-    /// Return a rig's slot + range. Rows are zeroed (a part's stale tag during the one-frame
-    /// despawn skew reads a degenerate matrix — collapsed at the origin — never another rig's
-    /// pose), and the range coalesces back into the free list.
+    /// Return a rig's slot and range. Its rows and origin are zeroed, so a part's stale tag in the
+    /// one-frame despawn skew reads a matrix collapsed at the origin, never another rig's pose.
     pub fn free(&mut self, slot: u16) {
         let s = slot as usize;
         let Some(&len) = self.slot_len.get(s).filter(|&&l| l > 0) else {
@@ -343,8 +246,8 @@ impl RigPalettes {
         self.free_slots.push(slot);
         self.live_bones -= len;
         self.table_generation += 1;
-        // Watermark BEFORE the range re-enters the free list — the zeroing below must land
-        // inside the copied prefix (the invariant's own ordering, [`Self::bone_watermark`]).
+        // The watermark before the range re-enters the free list, so the zeroing below lands
+        // inside the copied prefix.
         let wm = self.bone_watermark();
         let rows = rows_make_mut(
             &mut self.rows,
@@ -355,10 +258,8 @@ impl RigPalettes {
         );
         rows[3 * base as usize..3 * (base + len) as usize].fill([0.0; 4]);
         self.dirty.push((base, len, self.mirrored[s]));
-        // …and the origin with them, so "collapsed at the origin" stays literally true for a
-        // stale tag during the one-frame despawn skew (decision 0974).
         self.set_origin(slot, Vec3::ZERO);
-        // Insert sorted + coalesce with both neighbours.
+        // Insert sorted and coalesce with both neighbours.
         let i = self.free_ranges.partition_point(|&(b, _)| b < base);
         self.free_ranges.insert(i, (base, len));
         if i + 1 < self.free_ranges.len() {
@@ -377,9 +278,7 @@ impl RigPalettes {
         }
     }
 
-    /// Publish the world position slot `slot`'s rows are measured from (decision 0974). Called by
-    /// both row writers with the same origin they subtracted, so the pair is atomic by
-    /// construction — there is no frame where the shader can add a stale origin to fresh rows.
+    /// Publish a slot's origin, called by each row writer with the origin it subtracted.
     fn set_origin(&mut self, slot: u16, origin: Vec3) {
         let s = slot as usize;
         let word = [origin.x, origin.y, origin.z, 0.0];
@@ -394,15 +293,8 @@ impl RigPalettes {
         }
     }
 
-    /// Rewrite one rig's rows from its joints' world transforms × inverse bindposes, and mark the
-    /// range dirty. `n` is clamped to the allocated length (a malformed model whose joint list
-    /// and bindpose list disagree writes the shorter).
-    ///
-    /// `origin` is the rig holder's world translation: rows are written RELATIVE to it (decision
-    /// 0974) and the vertex stage adds it back. Unlike the collapsed lane, these globals were
-    /// propagated by Bevy in absolute world space, so subtracting the origin here cannot recover
-    /// precision propagation already spent — it buys the *clip-space* half of the fix only. Both
-    /// lanes must still agree on the convention, which is why it is not optional.
+    /// Rewrite one rig's rows from its joints' globals relative to `origin`, the holder's
+    /// translation; propagated in absolute space, they keep the rounding propagation spent.
     fn write_rig(
         &mut self,
         rig: &RigSkin,
@@ -439,15 +331,8 @@ impl RigPalettes {
         }
     }
 
-    /// The collapsed-rig lane's row write (decision 0724): the world pass hands the composed —
-    /// and billboard-replaced — per-bone frames directly; rows are `frame × ibp`, the same product
-    /// [`Self::write_rig`] reads off joint entities. `worlds` beyond the allocation (or the
-    /// bindpose list) is ignored, mirroring the entity path's clamp.
-    ///
-    /// The frames arrive already **rig-relative** (decision 0974) — the world pass composes the
-    /// chain from a zero-translation root — so nothing here spends a ~9 k-yard ULP and the rows
-    /// are exact to a rig-sized quantity. `origin` is the world position they are measured from;
-    /// the vertex stage adds it back camera-relative.
+    /// The collapsed lane's row write, `frame × ibp` over frames the world pass composed from a
+    /// zero-translation root, so the rows are exact at rig scale.
     pub(crate) fn write_rig_worlds(
         &mut self,
         rig: &RigSkin,
@@ -481,20 +366,9 @@ impl RigPalettes {
         }
     }
 
-    /// **The rider write** (decision 1609): fill every row of `slot` with ONE rigid frame, and
-    /// publish the world position it is measured from.
-    ///
-    /// An attached model rests at bind pose, where a palette row `world_from_joint × ibp` is the
-    /// placement matrix for every joint (`F × bind_j × bind_j⁻¹`) — so the whole model is one
-    /// frame repeated, and no inverse-bindpose list is consulted or needed. `frame` arrives in the
-    /// HOST rig's frame, at rig-sized magnitudes; `origin` is the host's world position, which the
-    /// vertex stage adds back camera-relative. The point of the whole lane is that the two are
-    /// never summed in f32 on the CPU (see [`crate::rig_rider`]).
-    ///
-    /// **Idempotent, deliberately.** Riders are re-derived every frame from the host's pose, so a
-    /// standing unit would otherwise dirty its rows — and pay an upload — for a value that has not
-    /// moved. The compare is bit equality, not an epsilon, exactly as the camera's own no-op write
-    /// gate is (decision 1362): a real sub-epsilon change must still land.
+    /// The rider write: every row of `slot` gets one rigid frame in the host rig's space (a model
+    /// at bind pose has one placement for every joint), with the host's position as origin. An
+    /// unchanged frame is a no-op, by bit equality so a sub-epsilon move still lands.
     pub(crate) fn write_rider(&mut self, slot: u16, frame: Affine3A, origin: Vec3) {
         let s = slot as usize;
         let (Some(&base), Some(&len)) = (self.table.get(s), self.slot_len.get(s)) else {
@@ -534,41 +408,29 @@ impl RigPalettes {
         self.dirty.push((base, len, mirrored));
     }
 
-    /// Flag a rig's rows to ALSO reach the booth mirror buffers ([`RigPaletteMirrors`]): the
-    /// booth spawners call it for their rigs — whose materials bind a studio light buffer, not
-    /// the shared one — right after allocation.
+    /// Flag a booth rig's rows to also reach the mirror buffers ([`RigPaletteMirrors`]).
     pub fn mark_mirrored(&mut self, slot: u16) {
         if let Some(m) = self.mirrored.get_mut(slot as usize) {
             *m = true;
         }
-        // Push the ORIGIN table to the mirrors on this edge, unconditionally (decision 0974). The
-        // mirror upload is gated on `origin_mirror_generation`, which only moves when a slot that
-        // is ALREADY mirrored changes — so a booth rig whose origin was written before this call
-        // (or written again to the same value after it) would leave the studio buffers holding a
-        // zero origin, and the booth's subject would render an Elwynn's-worth of yards away.
+        // Push the origin table to the mirrors unconditionally: the generation only moves for an
+        // already-mirrored slot, so an origin written before this call would never reach them.
         self.origin_mirror_generation += 1;
     }
 
-    /// The mouseover picker's read side: rig slot → **world-space** `Mat4` palette (the same
-    /// values Bevy's `skin_model` would compute), reconstructed from the rows. The stored rows are
-    /// rig-relative (decision 0974), so the slot's origin goes back on here — the picker ray is a
-    /// world-space ray, and it is not a precision consumer.
+    /// The mouseover picker's read: the slot's world-space palette, origin added back.
     pub fn world_palette(&self, slot: u16, bones: usize) -> Option<Vec<Mat4>> {
         let o = *self.origins.get(slot as usize)?;
         self.rows_at(slot, bones, [o[0], o[1], o[2]])
     }
 
-    /// The rig's palette rows **as the vertex stage blends them** — rig-relative (decision 0974),
-    /// the slot origin deliberately NOT added back. [`Self::world_palette`] is the picker's
-    /// world-space read; this is the PRECISION one, for the same reason [`Self::rider_placement`]
-    /// returns its pair unsummed: re-adding the ~9 k-yard origin would stamp the very f32 grid
-    /// the lane exists to avoid onto the measurement, and the instrument would then read its own
-    /// arithmetic as the defect.
+    /// The rig's rows as the vertex stage blends them, rig-relative: the precision read, since
+    /// adding the ~9 k-yard origin would put the f32 grid the lane avoids onto the measurement.
     pub fn rig_rows(&self, slot: u16, bones: usize) -> Option<Vec<Mat4>> {
         self.rows_at(slot, bones, [0.0; 3])
     }
 
-    /// Both reads above: the rows of `slot`, with `o` added onto the translation column.
+    /// The rows of `slot` as `Mat4`s, `o` added to the translation column.
     fn rows_at(&self, slot: u16, bones: usize, o: [f32; 3]) -> Option<Vec<Mat4>> {
         let s = slot as usize;
         let len = (*self.slot_len.get(s)? as usize).min(bones);
@@ -591,30 +453,20 @@ impl RigPalettes {
         )
     }
 
-    /// A slot's rig ORIGIN — the world position its rows are measured from, exactly as the vertex
-    /// stage reads it out of `rig_origin[slot]`. The instrument pairs it with [`Self::rig_rows`] to
-    /// reproduce the shader's own `frame_from_local * v + (frame_origin - view.world_position)`
-    /// without ever forming the absolute world coordinate the lane exists to avoid.
+    /// A slot's origin as the vertex stage reads it; with [`Self::rig_rows`] it reproduces the
+    /// shader's `frame_from_local * v + (frame_origin - view.world_position)`.
     pub fn slot_origin(&self, slot: u16) -> Option<Vec3> {
         let o = self.origins.get(slot as usize)?;
         Some(Vec3::new(o[0], o[1], o[2]))
     }
 
-    /// A rider slot's placement **as the vertex stage reads it** (decision 1609): its
-    /// `(rig_origin, row-0 translation)` pair, unsummed. The instrument read — `WOW_JITTER`
-    /// measures the row's own motion against the anchor's absolute world translation, and the
-    /// whole point of the lane is that only the first of those two is on an f32 grid coarse
-    /// enough to see. Summing them here would destroy exactly the thing being measured, which is
-    /// why this returns the pair and [`Self::world_palette`] (a picker read, not a precision one)
-    /// does not.
+    /// A rider slot's `(rig_origin, row-0 translation)` pair, unsummed, as `WOW_JITTER` measures
+    /// it: summing would put the origin's coarse f32 grid onto the row's own motion.
     pub fn rider_placement(&self, slot: u16) -> Option<(Vec3, Vec3)> {
         self.row_placement(slot, 0)
     }
 
-    /// The same pair for an arbitrary bone of a slot. A bind-pose rider repeats one frame across
-    /// every row, so row 0 answers for the model; a **posed** one (decision 2281 — the flexing
-    /// ranged prop) does not, and asking which bone is the only way to see that its rows differ at
-    /// all. `None` for an unallocated slot or a bone past its length.
+    /// The same pair for any bone: a posed rider (the flexing ranged prop) differs by row.
     pub fn row_placement(&self, slot: u16, bone: u32) -> Option<(Vec3, Vec3)> {
         let s = slot as usize;
         if bone >= *self.slot_len.get(s)? {
@@ -628,17 +480,15 @@ impl RigPalettes {
         ))
     }
 
-    /// How many live rigs have a COMPUTED palette (their first bone's first row is non-zero — a
-    /// freshly allocated or never-computed rig reads all-zero rows). The FPS probe prints it:
-    /// allocation without computation renders origin-collapsed rigs, and no other probe number
-    /// would catch that failure mode.
+    /// How many live rigs have a computed palette (a non-zero first row); the FPS probe prints it,
+    /// since an allocated but never-computed rig renders collapsed at the origin.
     pub fn computed_rigs(&self) -> usize {
         (0..self.slot_high)
             .filter(|&s| self.slot_len[s] > 0 && self.rows[3 * self.table[s] as usize] != [0.0; 4])
             .count()
     }
 
-    /// Live and peak occupancy `(slots, bones, peak_slots, peak_bones)` — the overflow diagnostic.
+    /// Live and peak occupancy: `(slots, bones, peak_slots, peak_bones)`.
     pub fn occupancy(&self) -> (usize, u32, usize, u32) {
         (
             self.slot_high - 1 - self.free_slots.len(),
@@ -648,27 +498,22 @@ impl RigPalettes {
         )
     }
 
-    /// Slots still allocatable right now — the pressure signal (decision 0863): the doodad
-    /// reaper starts reclaiming parked rigs under [`crate::doodad_anim::REAP_LOW_WATER`], and
-    /// the unit heal only rebuilds a starved visual when there is real room to succeed.
+    /// Slots still allocatable: the doodad reaper reclaims parked rigs below
+    /// [`crate::doodad_anim::REAP_LOW_WATER`], and the unit heal waits for room.
     pub fn slot_headroom(&self) -> usize {
         MAX_RIG_SLOTS - self.slot_high + self.free_slots.len()
     }
 }
 
-/// The unit whose visual was built WITHOUT a palette rig because the table was full at attach
-/// time (decision 0863) — it renders the static bind pose. [`crate::entities`]' heal system
-/// rebuilds it (the 0x60abe0 display-swap teardown, `Reattached` so it doesn't re-fade) once the
-/// table has headroom again; without this marker the denial was PERMANENT, the "statue mobs at
-/// the stream-in boundary" bug.
+/// A unit built without a palette rig because the table was full: it renders the bind pose until
+/// the app's `entities` heal rebuilds it (the `0x60abe0` display-swap teardown, `Reattached` so it
+/// does not re-fade) once there is headroom.
 #[derive(Component)]
 pub struct RigStarved;
 
-/// A registered rig, on the entity that owns its pose (the unit / doodad-host / booth root):
-/// its palette slot + the joint entities + the shared inverse bindposes. The hook frees the slot
-/// whoever despawns the rig — and `on_replace` (not `on_remove`) because a gear/display rebuild
-/// re-runs the attach on the SAME entity and insert-overwrites this component: `on_remove` never
-/// fires on an overwrite, and the old slot would leak until the unit despawned.
+/// A registered rig, on the entity that owns its pose: its palette slot, joint entities and inverse
+/// bindposes. The slot is freed `on_replace`, not `on_remove`, because a gear or display rebuild
+/// overwrites this component on the same entity, and `on_remove` does not fire on an overwrite.
 #[derive(Component)]
 #[component(on_replace = free_rig_skin)]
 pub struct RigSkin {
@@ -680,26 +525,18 @@ pub struct RigSkin {
 }
 
 impl RigSkin {
-    /// The rig's allocated bone count — the palette-facing length (the mouseover picker sizes
-    /// its palette read with it; the collapsed lane has no joint list to measure).
+    /// The rig's allocated bone count; the collapsed lane has no joint list to measure.
     pub fn bones(&self) -> u32 {
         self.len
     }
 
-    /// The rig's inverse bindposes — the instrument read. `WOW_JITTER`'s palette term probes the
-    /// rows at each bone's BIND position, which is the only honest way to ask "how far does a
-    /// vertex bound to this bone actually move" of the numbers the GPU blends: a row's own
-    /// translation column is the bind-space ORIGIN's image, a lever up to the model's full height
-    /// away from the bone, and differencing it reads a rotation as ~10x the displacement any real
-    /// vertex sees.
+    /// The rig's inverse bindposes, for `WOW_JITTER` to probe rows at each bone's bind position: a
+    /// row's translation column lies up to a model's height away, magnifying a rotation ~10x.
     pub fn ibp(&self) -> &Handle<SkinnedMeshInverseBindposes> {
         &self.ibp
     }
 
-    /// Allocate a palette rig for the collapsed lane (decision 0724): no joint entities — the
-    /// world pass hands composed frames to [`RigPalettes::write_rig_worlds`] instead, so the
-    /// entity-lane change sweep never touches this slot (empty `joints` make its `write_rig` a
-    /// no-op by construction).
+    /// Allocate a rig for the collapsed lane, written by [`RigPalettes::write_rig_worlds`].
     pub fn allocate_bones(
         palettes: &mut RigPalettes,
         bones: u32,
@@ -708,11 +545,7 @@ impl RigSkin {
         Self::allocate_inner(palettes, bones, Vec::new(), ibp)
     }
 
-    /// Allocate a palette rig over live joint entities (the effect/booth/equipment lane — the
-    /// change sweep computes its rows; doodads moved to [`Self::allocate_bones`], decision 1365).
-    /// `None` (with one loud warn per session — a promise this doc made for a long time before
-    /// the code kept it, 2264) when the table is full — the caller renders the
-    /// static bind-pose mesh instead.
+    /// Allocate a rig over live joints; `None` when full, and the caller renders the bind pose.
     pub fn allocate(
         palettes: &mut RigPalettes,
         joints: Vec<Entity>,
@@ -738,13 +571,8 @@ impl RigSkin {
             }),
             None => {
                 palettes.denied += 1;
-                // **Once per session, as this function's doc has always promised.** It did not
-                // keep that promise: the denial path warned on every call, and the lazy-doodad
-                // caller retries *every frame while the host is drawn*
-                // (`doodad_anim::lazy` — "table full — the warn fired; the gate retries while
-                // drawn"), so a crowded scene turned one fact into a per-frame flood that buries
-                // every other warning in the log. The repeats were never the signal anyway:
-                // `denied` is already counted here and already reported by the palette census.
+                // Once a session: the lazy-doodad caller retries every frame while drawn, and
+                // `denied` already counts the repeats for the census.
                 if !palettes.denied_warned {
                     palettes.denied_warned = true;
                     let (s, b, ps, pb) = palettes.occupancy();
@@ -766,34 +594,27 @@ fn free_rig_skin(mut world: DeferredWorld, ctx: HookContext) {
         .map(|r| r.slot)
         .expect("on_remove runs with the component still present");
     world.resource_mut::<RigPalettes>().free(slot);
-    // The slot indexes the per-instance TINT table too (decision 0812), and slots are recycled — so
-    // clear it on the same edge that frees it. Structural, not disciplinary: whatever kills a rig
-    // (despawn, gear/display rebuild) cannot leave a dead unit's colour behind for the next unit
-    // that allocates the slot, and no tinted-unit teardown path has to remember to.
+    // Slots are recycled and also index the tint table: clear it on the same edge, so no dead
+    // unit's colour reaches the slot's next owner.
     if let Some(mut tints) = world.get_resource_mut::<crate::instance_tint::InstanceTints>() {
         tints.clear(slot);
     }
-    // …and the straddle split's waterline (decision 2188), on the same index for the same reason:
-    // a recycled slot must not clip the next unit at the last one's water.
+    // And the straddle waterline, for the same reason.
     if let Some(mut clips) = world.get_resource_mut::<crate::straddle::WaterClips>() {
         clips.clear(slot);
     }
 }
 
-/// On every joint entity (planted by [`spawn_joints`]): the rig root whose palette this
-/// joint feeds. The change sweep below is a linear pass over exactly these.
+/// On every joint entity: the rig root whose palette it feeds, for the change sweep.
 #[derive(Component)]
 pub(crate) struct RigJoint(pub(crate) Entity);
 
-/// On every skinned part entity: the rig root, for CPU-side palette consumers (the mouseover
-/// picker's skinned ray test). The GPU side reads the same link from the part's `MeshTag` rig
-/// field instead.
+/// On every skinned part: the rig root, for CPU readers such as the mouseover picker.
 #[derive(Component)]
 pub struct RigPart(pub Entity);
 
-/// PostUpdate, after the billboard joint pass (the last joint-world writer): one linear
-/// `Changed<GlobalTransform>` sweep over the joint population → the set of rigs whose palettes
-/// must recompute this frame → rewrite exactly those rigs' rows.
+/// PostUpdate, after the billboard joint pass (the last joint-world writer): rewrite the rows of
+/// every rig with a joint whose `GlobalTransform` changed.
 fn compute_rig_palettes(
     changed: Query<&RigJoint, Changed<GlobalTransform>>,
     rigs: Query<&RigSkin>,
@@ -809,10 +630,8 @@ fn compute_rig_palettes(
         let Some(ibp) = ibps.get(&rig.ibp) else {
             continue;
         };
-        // The rig holder's own world translation is the rebasing origin (decision 0974): every
-        // joint is a descendant of it, so the rows come out rig-sized. Any origin would be
-        // *correct* — only precision cares that it sits near the geometry — so a holder without a
-        // global (mid-teardown) safely falls back to the map origin, i.e. the old behaviour.
+        // The holder's translation is the origin, so the rows come out rig-sized; any origin is
+        // correct and only precision cares, so a holder mid-teardown falls back to the map's.
         let origin = rebase_origin(
             worlds
                 .get(root)
@@ -823,7 +642,7 @@ fn compute_rig_palettes(
     }
 }
 
-/// The render-world mirror: `Arc` bumps + the frame's dirty ranges.
+/// The render-world mirror: `Arc` bumps and the frame's dirty ranges.
 #[derive(Resource, Clone, ExtractResource)]
 struct RigPaletteExtract {
     rows: Arc<Vec<[f32; 4]>>,
@@ -850,7 +669,7 @@ impl Default for RigPaletteExtract {
     }
 }
 
-/// Main world, after the compute: hand the frame's dirty ranges + the shared rows to extraction.
+/// Main world, after the compute: hand the frame's dirty ranges and the shared rows to extraction.
 fn publish_rig_palettes(mut palettes: ResMut<RigPalettes>, mut out: ResMut<RigPaletteExtract>) {
     if palettes.dirty.is_empty()
         && out.table_generation == palettes.table_generation
@@ -878,17 +697,13 @@ fn publish_rig_palettes(mut palettes: ResMut<RigPalettes>, mut out: ResMut<RigPa
     out.origin_mirror_generation = p.origin_mirror_generation;
 }
 
-/// Extra `wow_light`-layout buffers that mirror the palette regions (the glue/portrait booths'
-/// studio buffers — their skinned rigs bind those, not the shared buffer). Registered by key at
-/// booth creation; re-registration replaces (a rebuilt booth's old buffer drops).
+/// The glue and portrait booths' studio light buffers, which mirror the palette regions.
 #[derive(Resource, Clone, Default, ExtractResource)]
 pub struct RigPaletteMirrors(
     pub std::collections::HashMap<&'static str, bevy::render::render_resource::Buffer>,
 );
 
-/// What the last upload actually put on the GPU — the four independent change gates
-/// ([`upload_rig_palettes`]). `dirty` is an `Arc` pointer, not a counter: a new publish makes a
-/// new `Arc`.
+/// What the last upload put on the GPU; `dirty` is the published `Arc`'s pointer.
 #[derive(Default)]
 struct UploadedGenerations {
     table: Option<u64>,
@@ -897,9 +712,8 @@ struct UploadedGenerations {
     origin_mirror: Option<u64>,
 }
 
-/// Render world (`PrepareResources`): write the dirty rows + (on change) the slot table and the
-/// rig-origin table into the shared buffer and every registered mirror. A parked, stationary world
-/// costs zero bytes here.
+/// Render world (`PrepareResources`): write the dirty rows, and on change the slot and origin
+/// tables, into the shared buffer and every mirror.
 fn upload_rig_palettes(
     queue: Res<RenderQueue>,
     shared: Option<Res<crate::lighting::SharedLightBuffer>>,
@@ -908,14 +722,11 @@ fn upload_rig_palettes(
     mut last: Local<UploadedGenerations>,
 ) {
     let Some(data) = data else { return };
-    // The extract clones every frame; gate on content. `dirty` counts published dirty batches
-    // via the Arc pointer (a new publish makes a new Arc).
+    // The extract clones every frame, so gate on content.
     let dirty_ptr = Arc::as_ptr(&data.dirty) as u64;
     let table_new = last.table != Some(data.table_generation);
     let dirty_new = last.dirty != dirty_ptr && !data.dirty.is_empty();
-    // The origin table is 32 KB written whole (decision 0974): tiny beside the rows, and the
-    // mirrors take their own generation so a world full of walking creatures does not re-push it
-    // into every booth buffer each frame.
+    // The 32 KB origin table is written whole; the mirrors gate on their own generation.
     let origin_new = last.origin != Some(data.origin_generation) && !data.origins.is_empty();
     let origin_mirror_new =
         last.origin_mirror != Some(data.origin_mirror_generation) && !data.origins.is_empty();
@@ -931,11 +742,7 @@ fn upload_rig_palettes(
     let cost_t0 = rig_cost_enabled().then(std::time::Instant::now);
     let mut cost_calls = 0u32;
     let mut cost_bytes = 0u64;
-    // Coalesce the per-rig dirty ranges before touching the queue: rigs allocate contiguously,
-    // so a steady frame's ~750 one-rig ranges merge into a handful of runs — the 0724 ledger
-    // measured the per-range `write_buffer` loop at 2.7 ms/frame, almost all call overhead.
-    // Small gaps (a parked body between two live ones) are bridged for the same reason
-    // (`COALESCE_GAP_BONES`).
+    // Coalesce first: each `write_buffer` call costs far more than its bytes.
     let all = coalesce_ranges(data.dirty.iter().map(|&(b, l, _)| (b, l)).collect());
     let mirrored_only = coalesce_ranges(
         data.dirty
@@ -944,8 +751,7 @@ fn upload_rig_palettes(
             .map(|&(b, l, _)| (b, l))
             .collect(),
     );
-    // Every target sees the slot table; the shared buffer takes all dirty rows, the booth
-    // mirrors only the ranges flagged mirrored (their rigs) — world traffic never multiplies.
+    // Every target takes the slot table; the booth mirrors take only the mirrored ranges.
     let targets = shared
         .iter()
         .map(|s| (&s.0, false))
@@ -994,20 +800,11 @@ fn upload_rig_palettes(
     }
 }
 
-/// The gap (in bones) two dirty runs may leave between them and still upload as ONE
-/// `write_buffer`. A `queue.write_buffer` is not a memcpy: wgpu allocates a staging buffer per
-/// call, registers it, records the copy and releases it — a few microseconds of fixed cost
-/// against ~10 GB/s of copying, so re-sending up to this many *unchanged* rows (they are the
-/// live rows, straight out of `rows`; nothing stale can be written) is cheaper than a second
-/// call. Sized so the whole tolerance costs about what one call does. The case that needed it:
-/// a 40-man raid at the Stormwind auction house uploaded ~310 KB of rows in ~93 calls a frame
-/// (1929's `[rig-upload]` census), because parked bodies and idle props sit between the live
-/// rigs in the slab and a strictly-adjacent merge stops at every one of them.
+/// The widest gap, in bones, two dirty runs may leave and still upload as one `write_buffer`: a
+/// call's fixed cost (a staging buffer each) is about what re-sending this many live rows costs.
 const COALESCE_GAP_BONES: u32 = 256;
 
-/// Sort + merge overlapping, adjacent, and *nearly* adjacent (gap ≤ [`COALESCE_GAP_BONES`])
-/// `(base, len)` bone ranges into maximal runs. Rows inside a bridged gap are written with their
-/// current contents.
+/// Merge `(base, len)` bone ranges that overlap or lie within [`COALESCE_GAP_BONES`] into runs.
 fn coalesce_ranges(ranges: Vec<(u32, u32)>) -> Vec<(u32, u32)> {
     coalesce_ranges_with_gap(ranges, COALESCE_GAP_BONES)
 }
@@ -1027,12 +824,9 @@ fn coalesce_ranges_with_gap(mut ranges: Vec<(u32, u32)>, gap: u32) -> Vec<(u32,
     out
 }
 
-/// `WOW_RIG_CENSUS=<secs>` (any unparseable value = 5): a periodic one-line breakdown of WHO
-/// holds the palette's slots — per-lane slots(bones) with the doodad lane split live/parked by
-/// its draw gate, a bones-per-slot histogram, denials since the last line, and the prop-probe
-/// table's live/peak. The last matters because probes and rigs are the two `MeshTag`-slot-indexed
-/// tables competing for the same 30 payload bits — a re-split of either field must read both
-/// occupancies (decision 0863's exhaustion diagnosis). Zero-cost when off: one env read, once.
+/// `WOW_RIG_CENSUS=<secs>` (unparseable: 5): a periodic line of who holds the palette's slots, by
+/// lane, with a bones-per-slot histogram, denials, and the prop-probe table's occupancy: probes
+/// and rigs split the same 30 `MeshTag` payload bits, so a re-split must read both.
 fn rig_census_every() -> Option<f32> {
     static EVERY: std::sync::OnceLock<Option<f32>> = std::sync::OnceLock::new();
     *EVERY.get_or_init(|| {
@@ -1042,7 +836,7 @@ fn rig_census_every() -> Option<f32> {
     })
 }
 
-/// The `[rig-census]` printer (`WOW_RIG_CENSUS=<secs>`) — see [`rig_census_every`].
+/// The `[rig-census]` printer ([`rig_census_every`]).
 #[allow(clippy::type_complexity)] // one census's full lane classification
 fn census_rig_palettes(
     time: Res<Time<bevy::time::Real>>,
@@ -1063,8 +857,7 @@ fn census_rig_palettes(
         return;
     }
     *next = now + every;
-    // Lanes: doodad anim hosts (split by their draw gate), net units, everything else (held-item
-    // billboard rigs, spell-fx instances, booth rigs). `(slots, bones)` each.
+    // Lanes, `(slots, bones)` each: doodad hosts split by their draw gate, units, everything else.
     let (mut doodad, mut doodad_parked, mut unit, mut other) =
         ((0u32, 0u32), (0u32, 0u32), (0u32, 0u32), (0u32, 0u32));
     let mut hist = [0u32; 6]; // bones/slot: ≤2, 3–4, 5–8, 9–16, 17–32, 33+
@@ -1129,8 +922,8 @@ pub fn plugin(app: &mut App) {
                 publish_rig_palettes,
             )
                 .chain()
-                // After the last joint-world writer: propagation, then the billboard joint pass
-                // (which rewrites joint GlobalTransforms in place — see its module doc).
+                // After the last joint-world writer: propagation, then the billboard joint pass,
+                // which rewrites joint `GlobalTransform`s in place.
                 .after(crate::billboard::BillboardPlace),
         );
     if let Some(render) = app.get_sub_app_mut(RenderApp) {
@@ -1141,18 +934,8 @@ pub fn plugin(app: &mut App) {
     }
 }
 
-/// Spawn one entity per bone of a model's rest skeleton, parented into the bone tree, each
-/// carrying the [`RigJoint`] back-link to the rig root whose palette it fills.
-///
-/// Engine work that lived in `entities::attach` because the unit spawner was the first lane to
-/// want it — and the doodad animator, the portrait booth, the equipment spawner and the spell-fx
-/// spawner all reached across for it since. Its only cross-module reference was `RigJoint`, which
-/// is here, so this is where it goes. The lanes have been leaving one by one for the collapsed
-/// `RigPose` buffer (units 0724, doodads 1365, booths 1443); what remains is the **attached
-/// model** lanes — equipment and spell-fx, whose joints hang under someone else's bone.
-///
-/// `holder` is the rig root the palette belongs to; `root` is what an unparented joint attaches
-/// to. They differ for an attached model whose joints hang under someone else's bone.
+/// Spawn one entity per bone of a model's rest skeleton, each with a [`RigJoint`] to `holder`,
+/// the palette's rig root; `root` takes the parentless joints, and differs for an attached model.
 pub fn spawn_joints(
     commands: &mut Commands,
     root: Entity,
@@ -1164,11 +947,9 @@ pub fn spawn_joints(
         .iter()
         .map(|j| {
             commands
-                // Visibility too, not just Transform: held items and spell effects hang their
-                // visible roots under joints, and a gap in the chain both trips Bevy's B0004 and
-                // orphans those subtrees from the unit root's visibility (a hidden unit would
-                // keep its weapon on screen). Chain only — a joint renders nothing
-                // (`crate::vis_chain`).
+                // Visibility too: held items and spell effects hang under joints, and a gap in the
+                // chain warns in Bevy and leaves them visible under a hidden unit. A joint itself
+                // renders nothing (`crate::vis_chain`).
                 .spawn((
                     Transform::from_translation(j.local_translation),
                     Visibility::default(),
@@ -1200,13 +981,11 @@ mod tests {
         let (s3, b3) = p.alloc(30).unwrap();
         assert!(s1 >= 1, "slot 0 is the no-rig sentinel");
         assert_eq!((b1, b2, b3), (0, 10, 30));
-        // Free the middle range: the free list holds it separately…
         p.free(s2);
         assert_eq!(p.occupancy().0, 2);
-        // …an exact-fit alloc reuses it…
+        // An exact fit reuses the freed middle range.
         let (s4, b4) = p.alloc(20).unwrap();
         assert_eq!(b4, 10);
-        // …and freeing everything coalesces back to one range.
         p.free(s1);
         p.free(s4);
         p.free(s3);
@@ -1223,16 +1002,11 @@ mod tests {
         Arc::make_mut(&mut p.rows)[3 * base as usize] = [1.0; 4];
         p.free(slot);
         assert_eq!(p.rows[3 * base as usize], [0.0; 4]);
-        // The free is a dirty range too — the GPU mirror zeroes with us.
+        // The free is a dirty range too, so the GPU copy zeroes as well.
         assert!(p.dirty.contains(&(base, 2, false)));
     }
 
-    /// The COW clone copies the live prefix and nothing else (decision 1479): a shared-Arc write
-    /// used to `Arc::make_mut` all 3×131072 rows — ~6.3 MB, once per frame, wherever any rig
-    /// wrote — where the bone watermark bounds the content. The invariant it leans on is pinned
-    /// here too: rows at or above the watermark are bitwise zero, through alloc, write, free and
-    /// coalesce — including free()'s own ordering (watermark before the range re-enters the
-    /// list, so the zeroing lands inside the copied prefix).
+    /// The copy-on-write clone copies only the live prefix; a free while shared still zeroes.
     #[test]
     fn a_shared_arc_write_copies_only_the_live_prefix() {
         let mut p = RigPalettes::default();
@@ -1245,7 +1019,7 @@ mod tests {
             Arc::make_mut(&mut p.rows)[r] = [2.0; 4];
         }
         assert_eq!(p.bone_watermark(), 5, "first-fit packs the content low");
-        // The extract's held reference — the shared state every first-write-of-a-frame sees.
+        // The extract's held reference, as at every frame's first write.
         let held = p.rows.clone();
         let wm = p.bone_watermark();
         let rows = rows_make_mut(
@@ -1263,7 +1037,7 @@ mod tests {
             "the neighbour survived the prefix copy"
         );
         assert_eq!(held[0], [1.0; 4], "the held (extracted) side is untouched");
-        // Free the top rig while shared again: the zeroing must land inside the copied prefix.
+        // Free the top rig while shared: the zeroing must land inside the copied prefix.
         let held2 = p.rows.clone();
         p.free(s2);
         assert_eq!(
@@ -1315,10 +1089,6 @@ mod tests {
         assert!(p.alloc(1).is_some());
     }
 
-    /// **The rider write's two contracts** (decision 1609): one frame reaches EVERY row of the
-    /// slot — which is what makes an attached model's bind-pose palette equal its static
-    /// placement — and re-writing the same frame is a no-op, so a standing unit's five
-    /// attachments cost five compares a frame and never an upload.
     #[test]
     fn a_rider_frame_fills_every_row_and_re_writing_it_is_free() {
         let mut p = RigPalettes::default();
@@ -1333,9 +1103,6 @@ mod tests {
         assert_eq!(p.dirty.len(), 1, "the first write dirties the range");
         assert_eq!(p.dirty[0].1, 4, "and dirties ALL of it, not just row 0");
 
-        // Every row carries the same frame: a bind-pose model's `world_from_joint × ibp` is the
-        // placement itself for every joint, so the whole model is one matrix repeated. Read back
-        // through the picker's own reconstruction, which is the only public row reader.
         let pal = p.world_palette(skin.slot, 4).unwrap();
         let want = Mat4::from(Affine3A::from_translation(origin) * frame);
         for (b, m) in pal.iter().enumerate() {
@@ -1346,14 +1113,13 @@ mod tests {
         assert_eq!(o, origin);
         assert!(t.abs_diff_eq(Vec3::from(frame.translation), 1e-6));
 
-        // Idempotent: the standing-still case must not reach the upload.
         p.dirty.clear();
         p.write_rider(skin.slot, frame, origin);
         assert!(
             p.dirty.is_empty(),
             "an unchanged rider frame must not dirty its range"
         );
-        // A real move still lands — bit equality, not an epsilon (the 1362 gate's rule).
+        // A sub-epsilon move still lands: bit equality, not an epsilon.
         p.write_rider(
             skin.slot,
             Affine3A::from_translation(Vec3::new(0.3, 1.4, -0.2 + 1.0e-6)) * frame,
@@ -1362,15 +1128,11 @@ mod tests {
         assert_eq!(p.dirty.len(), 1, "a sub-millimetre move is still a move");
     }
 
-    /// The picker's read side puts the slot's ORIGIN back on (decision 0974) — rows are stored
-    /// rig-relative, so a reconstruction that forgot the origin would ray-test every skinned unit
-    /// against a copy of itself sitting at the map origin.
     #[test]
     fn world_palette_reconstructs_the_affine_including_the_rig_origin() {
         let mut p = RigPalettes::default();
         let (slot, base) = p.alloc(1).unwrap();
-        // A recognisable affine: rotate 90° about Y, translate (1,2,3) — inside a rig standing a
-        // long way from the map origin.
+        // A 90° turn about Y and a (1, 2, 3) offset, in a rig far from the map origin.
         let origin = Vec3::new(-9464.31, 62.17, 56.91);
         let m = Mat4::from_rotation_translation(
             Quat::from_rotation_y(std::f32::consts::FRAC_PI_2),
@@ -1387,12 +1149,11 @@ mod tests {
         let want = Mat4::from_translation(origin) * m;
         let pal = p.world_palette(slot, 1).unwrap();
         assert!(pal[0].abs_diff_eq(want, 1e-2), "{:?} vs {want:?}", pal[0]);
-        // A transformed point round-trips through the reconstruction.
         let q = Vec3::new(0.5, -1.0, 2.0);
         assert!(pal[0]
             .transform_point3(q)
             .abs_diff_eq(want.transform_point3(q), 1e-2));
-        // And the origin is really load-bearing here, not a rounding-sized detail.
+        // The origin is load-bearing here, not a rounding-sized detail.
         assert!(
             p.world_palette(slot, 1).unwrap()[0]
                 .w_axis
@@ -1415,7 +1176,7 @@ mod tests {
 
     #[test]
     fn dirty_ranges_coalesce_into_runs() {
-        // Adjacent + overlapping merge; a hole splits. Order-independent (upload sorts).
+        // Adjacent and overlapping merge, a hole splits, input order does not matter.
         assert_eq!(
             coalesce_ranges_with_gap(vec![(70, 5), (0, 10), (10, 20), (25, 10), (40, 5)], 0),
             vec![(0, 35), (40, 5), (70, 5)]
@@ -1425,8 +1186,7 @@ mod tests {
 
     #[test]
     fn dirty_ranges_bridge_small_gaps_but_not_large_ones() {
-        // A parked rig's rows between two live ones (the raid's ~93-call frame): bridged, so
-        // the run is one call. A gap wider than the tolerance still splits.
+        // A parked rig between two live ones is bridged; a wider gap still splits.
         assert_eq!(
             coalesce_ranges_with_gap(vec![(0, 10), (14, 6), (30, 5)], 4),
             vec![(0, 20), (30, 5)]
@@ -1445,12 +1205,8 @@ mod tests {
 
     #[test]
     fn region_layout_is_consistent() {
-        // The slot table sits after the probe region, then the per-instance tint table (decision
-        // 0812 — same slot index), then the rig-origin table (decision 0974 — same slot index
-        // again), the palette rows last, and the blob-size extension covers all four exactly
-        // (wow_model.wgsl mirrors this layout, and wgpu validates the bound size against the
-        // shader's struct at draw time — a mismatch here is a draw-time failure, which is why this
-        // is asserted rather than trusted).
+        // `wow_model.wgsl` mirrors this layout, and wgpu checks the bound size against its struct
+        // at draw time, so a mismatch fails there.
         assert_eq!(
             crate::instance_tint::region_offset() - rig_table_region_offset(),
             (MAX_RIG_SLOTS * 4) as u64,
@@ -1485,9 +1241,9 @@ mod tests {
                 + crate::straddle::region_bytes()
                 + (MAX_PALETTE_BONES as u64) * BONE_BYTES
         );
-        // One `vec4` per addressable slot — the shader declares `array<vec4<f32>, 2048>`.
+        // One `vec4` a slot: the shader declares `array<vec4<f32>, 2048>`.
         assert_eq!(rig_origin_region_bytes(), (MAX_RIG_SLOTS * 16) as u64);
-        // One word per addressable slot — the shader declares `array<u32, 2048>` for both tables.
+        // One word a slot: the shader declares `array<u32, 2048>` for both tables.
         assert_eq!(
             crate::instance_tint::region_bytes(),
             (MAX_RIG_SLOTS * 4) as u64
diff --git a/crates/benilla-world/src/rig_rider.rs b/crates/benilla-world/src/rig_rider.rs
index 6217ad76..2f23b828 100644
--- a/crates/benilla-world/src/rig_rider.rs
+++ b/crates/benilla-world/src/rig_rider.rs
@@ -1,53 +1,14 @@
-//! **The rider lane** (decision 1609): an attached model — a helm, a pauldron, a held weapon, a
-//! shield — placed by a palette frame measured in its WEARER's rig frame, so its position is
-//! never an absolute f32 world coordinate that gets recomputed every frame.
+//! The rider lane: an attached model (a helm, a pauldron, a held weapon, a shield) draws from a
+//! palette frame in its wearer's rig frame, never from an absolute f32 world position.
 //!
-//! ## Why an attached model needs its own lane at all
+//! As a scene-graph child its world position adds a yard-sized bone offset to a coordinate of
+//! thousands of yards each frame, landing on the f32 grid (`2⁻¹⁰ yd` from 8192 to 16384) and
+//! hopping while the body moves smoothly. At bind pose every palette row is the placement
+//! `F = host_basis × pose.model[bone] × T(offset)`, with `host_basis` the host's frame minus its
+//! translation, and the slot's `rig_origin` adds the world position back camera-relative.
 //!
-//! Decision 0974 moved the model lane camera-relative: a rig's palette rows are composed with the
-//! root's translation zeroed, the row's world position rides a per-slot `rig_origin`, and the
-//! vertex stage adds it back as `frame·v + (origin − camera)`. A standing unit's origin is
-//! **constant**, so its body is exact — the one f32 rounding left in it never moves.
-//!
-//! Its attachments were not. They are ordinary scene-graph entities: the attach anchor's
-//! `GlobalTransform` is `joints_root_world × bone_local`, a ~1-yard quantity added to a ~9500-yard
-//! one, recomputed every frame. WoW's coordinates run to ±17066 yd and an f32 in `[8192, 16384)`
-//! has an ULP of exactly `2⁻¹⁰ yd = 0.9766 mm`, so the sum lands on a 0.98 mm grid **on the large
-//! axis** while the bone under it moves smoothly across it. The rendered helm therefore holds
-//! still for a few frames and then snaps one whole ULP sideways, for ever, while the body it sits
-//! on moves exactly. Measured on the Goldshire Stormwind Guard (`WOW_JITTER`, 2698 frames): the
-//! anchors' per-frame Δ along that axis was **exactly 0 or exactly one ULP and nothing between**
-//! (1835 / 839 frames), their second difference was exactly one ULP on 53 % of frames, and the
-//! body bones' was 0.0094 mm — a factor of 104. At the reported close-up that is 0.83 px of hop
-//! every other frame on the helm, both pauldrons, the sword and the shield. 0974 named this
-//! residual and did not take it; this is taking it.
-//!
-//! ## The mechanism
-//!
-//! An attached model rests at **bind pose** — the item lane arms no `AnimationPlayer` and no
-//! global-sequence drive, which is why it draws a static mesh today. At bind pose every palette
-//! row of it is the *same* matrix: a row is `world_from_joint × inverse_bindpose`, and
-//! `world_from_joint = F × bind_model_j` with `inverse_bindpose_j = bind_model_j⁻¹`, so every row
-//! collapses to the placement `F` itself. So the whole model needs **one frame**, written into
-//! each of its rows, and the picture it draws is identical to the static mesh's — the change is
-//! precision and nothing else.
-//!
-//! And `F` is available exactly: `F = host_basis × pose.model[bone] × T(offset)`, where
-//! `host_basis` is the host's own frame with its translation zeroed — the same rig-relative basis
-//! 0974 composes the body in. Every factor is rig-sized, so `F` costs ~1e-7 yd, and the slot's
-//! `rig_origin` carries the host's world position through to the vertex stage, where it is added
-//! camera-relative. Nothing on the path is ever a big-plus-small sum.
-//!
-//! **The entity keeps its absolute `GlobalTransform`.** That is the whole reason this is a
-//! *palette* lane and not a rebase of the scene graph: collision, picking, the item glow, the
-//! bowstring and the booth mirrors all read an attached model's world position and all keep
-//! reading exactly what they read before. Only the rendered vertices change route.
-//!
-//! **Named residuals** (they keep the absolute route, and the staircase with it): billboard cards
-//! (spawned at world root by decision 0153), item glow instances (children of the item root with
-//! their own attachment offsets), the engine-drawn bowstring/fishing line, and the seven
-//! `welds_billboard` displays whose 0841/0854 joint rig is camera-replaced per frame and so is not
-//! a bind-pose rigid frame.
+//! The entity keeps its absolute `GlobalTransform`: collision, picking, the item glow and the
+//! bowstring read it; only the rendered vertices take this route.
 
 use bevy::mesh::skinning::SkinnedMeshInverseBindposes;
 use bevy::prelude::*;
@@ -55,49 +16,34 @@ use bevy::prelude::*;
 use crate::rig_anim::RigPose;
 use crate::rig_palette::{rebase_origin, RigPalettes, RigSkin};
 
-/// An attached model whose palette slot is placed from a bone of `host`'s rig, in `host`'s own rig
-/// frame (decision 1609). Lives on the attached model's root, beside the [`crate::rig_palette::RigSkin`]
-/// that owns the slot — so the slot is freed, and the rider forgotten, on the same despawn edge.
+/// An attached model placed from a bone of `host`'s rig, in that rig's frame; it sits beside the
+/// [`crate::rig_palette::RigSkin`] that owns its palette slot, so both go on one despawn.
 #[derive(Component, Clone, Copy)]
 pub struct RigRider {
     /// The rig this model hangs off.
     pub host: Entity,
-    /// The host bone it hangs from. Attachment points never sit on a camera-faced bone (the same
-    /// fact `RigPose::posed_point` rests on), so the composed `pose.model` frame — which carries
-    /// the `flags & 0x7` arm but not the world pass's billboard replacement — is the right input.
+    /// The host bone it hangs from. Attachment points never sit on a camera-faced bone, so the
+    /// composed `pose.model`, without the billboard replacement, is the right frame.
     pub bone: u16,
     /// The attachment point's own offset from that bone, model space.
     pub local: Vec3,
-    /// The palette slot the frame is written into; every row in it takes the same value.
+    /// The palette slot written; a bind-pose rider repeats one frame into every row.
     pub slot: u16,
 }
 
-/// Write every rider's frame. Ordered with the palette's own writers (see
-/// [`crate::rig_palette::plugin`]): after propagation and the billboard joint pass, so the host's
-/// `GlobalTransform` and composed pose are both this frame's, and before the publish.
-///
-/// A host that is missing, has no pose, or does not carry the named bone leaves the rider's rows
-/// alone — they hold the last frame written, which is what a torn-down joint gets in the entity
-/// lane too. [`RigPalettes::write_rider`] is idempotent, so a standing unit's riders cost one
-/// compare each and never reach the upload.
-///
-/// **A rider that carries a pose of its OWN is posed, not repeated** (decision 2281). 1609's
-/// "every row is the placement" collapse is a consequence of bind pose, and the ranged weapon prop
-/// does not rest at bind pose: the reference re-arms `[CGUnit+0xd24]`'s own M2 instance to
-/// BowPull(160) at `$BWP` and to BowRelease(161) / Stand(0) at `$BWR`, so its bones move. Such a
-/// rider's row `b` is `F × own.model[b] × ibp[b]` — the same placement `F`, composed with the
-/// prop's own model-space pose, every factor still rig-sized, so the precision property this whole
-/// lane exists for is untouched. The population is one prop per unit holding a DRAWN animated
-/// ranged weapon (46 of the 571 shipped weapon models author 160/161), which is why the posed arm
-/// re-writes unconditionally where the rigid arm compares first.
+/// Writes every rider's frame, with the palette's writers ([`crate::rig_palette::plugin`]): after
+/// propagation and the billboard joint pass, before the publish. A missing host, pose or bone
+/// leaves the rows at their last frame; [`RigPalettes::write_rider`] is idempotent, so a standing
+/// unit's riders cost a compare. A rider with its own pose, the ranged weapon the reference
+/// re-arms on `[CGUnit+0xd24]`'s instance (BowPull 160 at `$BWP`, BowRelease 161 or Stand 0 at
+/// `$BWR`), writes row `b` as `F × own.model[b] × ibp[b]`, every frame.
 pub(crate) fn write_rig_riders(
     riders: Query<(Entity, &RigRider)>,
     poses: Query<&RigPose>,
     skins: Query<&RigSkin>,
     frames: Query<&GlobalTransform>,
     ibps: Res<Assets<SkinnedMeshInverseBindposes>>,
-    // The posed arm's row scratch, reused across frames and riders — a posed prop is re-derived
-    // every frame and a fresh `Vec` per rider per frame is pure churn.
+    // Row scratch for the posed arm, reused across frames and riders.
     mut scratch: Local<Vec<GlobalTransform>>,
     mut palettes: ResMut<RigPalettes>,
 ) {
@@ -105,14 +51,8 @@ pub(crate) fn write_rig_riders(
         let Ok(pose) = poses.get(rider.host) else {
             continue;
         };
-        // **`joints_root`, never the host entity.** `pose.model` is model space *relative to the
-        // rig's own frame*, and that frame is only the unit itself in the ordinary case: a mounted
-        // rider's is its SEAT anchor and a terrain-conformed model's is its conform node
-        // (`entities::mount`, `entities::attach`). Composing through the unit's own transform
-        // instead would place a mounted character's helm and weapon by the gap between its feet
-        // and its saddle. This is the same frame `finalize_rig_worlds` writes the body's rows
-        // from and the same one `RigPose::posed_point` demands, so the body and everything hanging
-        // off it stay in ONE frame — which is the property the whole lane exists to keep.
+        // `joints_root`, never the host entity: the rig's frame is the seat anchor when mounted
+        // and the conform node when terrain-tilted, and the body's rows are written from it too.
         let Ok(root_g) = frames.get(pose.joints_root) else {
             continue;
         };
@@ -123,9 +63,8 @@ pub(crate) fn write_rig_riders(
         let mut basis = root_g.affine();
         basis.translation -= bevy::math::Vec3A::from(origin);
         let frame = basis * *bone * bevy::math::Affine3A::from_translation(rider.local);
-        // The prop's OWN pose, when it has one: compose each of its model-space bone frames onto
-        // the placement and let the ordinary world write lay the rows down. `write_rig_worlds`
-        // takes it from there — same `frame × ibp` row math, same origin word, same dirty push.
+        // A prop with its own pose: its bone frames compose onto the placement and are written as
+        // a body's rows.
         let posed = poses
             .get(entity)
             .ok()
@@ -149,23 +88,13 @@ mod tests {
     use crate::rig_palette::RigSkin;
     use bevy::math::{Affine3A, DVec3, Mat4};
 
-    /// **The rig's frame is `joints_root`'s, not the host entity's** — the one distinction that
-    /// separates a helm sitting on a head from one sitting a saddle's height below it.
-    ///
-    /// `RigPose::model` is model space measured from the rig's own frame, and that frame is the
-    /// unit itself only in the ordinary case: `entities::mount` re-points `joints_root` at the
-    /// SEAT anchor when a character mounts, and `entities::attach` at the conform node for a
-    /// terrain-tilted model. Both leave the unit's own `GlobalTransform` where it always was, so
-    /// composing a rider through it is wrong by exactly the seat offset — and wrong only while
-    /// mounted, which is the shape of bug that ships.
     #[test]
     fn a_rider_composes_through_the_rigs_own_frame_not_the_units() {
         let mut app = App::new();
         app.init_resource::<RigPalettes>();
-        // The posed arm's asset lookup (decision 2281); `AssetPlugin` provides it in the app.
+        // The posed arm's asset lookup; `AssetPlugin` provides it in the app.
         app.init_resource::<Assets<SkinnedMeshInverseBindposes>>();
-        // The seat: a yard and a half up and turned 90° — a mount's saddle, exaggerated so a
-        // composition through the wrong frame cannot land near the right answer by luck.
+        // A saddle, exaggerated so the wrong frame cannot land near the right answer by luck.
         const SEAT: Vec3 = Vec3::new(1.0, 1.5, -2.0);
         let seat = app
             .world_mut()
@@ -220,7 +149,6 @@ mod tests {
             want.translation
         );
         assert_eq!(origin, SEAT, "…and be measured from the rig's own frame");
-        // The failure this forbids: composing through the unit's own transform instead.
         let unit_g = *app.world().entity(unit).get::<GlobalTransform>().unwrap();
         let wrong = unit_g.affine()
             * Affine3A::from_translation(Vec3::new(0.0, 0.4, 0.0))
@@ -231,14 +159,6 @@ mod tests {
         );
     }
 
-    /// **A rider that poses writes DIFFERENT rows** (decision 2281) — the property that makes the
-    /// gun's bolt recoil and the bow's limbs bend without giving either the absolute-frame ULP
-    /// staircase 1609 removed.
-    ///
-    /// The subject is the flexing prop's shape: two bones, the second displaced by its own pose,
-    /// hanging off a host bone. Bind-pose riders repeat one frame into every row, so the test that
-    /// this lane has really changed is that row 1 is **not** row 0 — and that row 1 lands where the
-    /// composition `F × model[1]` says, in the host's frame with the host's origin word.
     #[test]
     fn a_posed_rider_composes_each_bone_instead_of_repeating_the_placement() {
         let mut app = App::new();
@@ -255,8 +175,7 @@ mod tests {
         host_pose.compose();
         app.world_mut().entity_mut(unit).insert(host_pose);
 
-        // Identity inverse bindposes, so a row reduces to `F × model[b]` and the arithmetic in the
-        // assertion is the mechanism rather than a second implementation of it.
+        // Identity inverse bindposes, so a row is `F × model[b]`.
         let ibp = app
             .world_mut()
             .resource_mut::<Assets<SkinnedMeshInverseBindposes>>()
@@ -266,8 +185,7 @@ mod tests {
             RigSkin::allocate_bones(&mut palettes, 2, ibp).unwrap()
         };
         let slot = skin.slot;
-        // The prop's OWN pose: bone 1 a third of a yard down its length — stand-in for the muzzle
-        // bone a firearm's BowRelease swings.
+        // The prop's own pose: bone 1 a third of a yard out, standing in for a firearm's muzzle.
         const MUZZLE: Vec3 = Vec3::new(0.33, 0.0, 0.0);
         let prop = app.world_mut().spawn_empty().id();
         let mut prop_pose = crate::testing::test_rig_pose(prop, &[Vec3::ZERO, MUZZLE]);
@@ -311,34 +229,19 @@ mod tests {
         );
     }
 
-    /// **The pin** (decision 1609), in the shape decision 0974 set for the body: score both
-    /// routes' *rendered motion* against an f64 oracle of the identical chain, at Goldshire, with
-    /// real glam f32 arithmetic — not a model of it.
-    ///
-    /// The subject is one attachment on a slow idle: a bone 1.9 yd up the model swinging ±0.02 rad
-    /// with a 4 s period, so it travels about a millimetre a frame — the regime the report came
-    /// from, and the one where an f32 ULP is a large fraction of the real motion.
-    ///
-    /// What separates the two routes is the SECOND difference. The chain's own curvature is
-    /// `A·ω²·dt²`, tens of microns here; the absolute route adds the ULP grid of a ~9481-yard
-    /// coordinate (`2⁻¹⁰ yd = 0.977 mm`) on top, because the rendered position holds still for
-    /// several frames and then hops one whole grid step. That is the staircase the director saw on
-    /// the helm, and it is what this test forbids coming back.
-    ///
-    /// The premise is asserted, not assumed (0974's own caution, which cost it a first version
-    /// that measured nothing): if a future edit leaves the chain moving along a *small* world
-    /// axis, the absolute route stops spending an ULP and the comparison silently proves nothing.
+    /// Scores both routes' second difference against an f64 oracle of the same chain: a bone
+    /// swinging ±0.02 rad at Goldshire, where the absolute route adds the 2⁻¹⁰ yd grid of a
+    /// ~9481 yd coordinate and the rider's frame only the chain's own curvature.
     #[test]
     fn a_riders_frame_does_not_re_round_an_attachment_at_world_scale() {
-        // Bevy-space Goldshire, from the report: |z| ≈ 9481.5 puts the ULP at exactly 2⁻¹⁰ yd.
+        // Bevy-space Goldshire: |z| ≈ 9481.5 puts the ULP at exactly 2⁻¹⁰ yd.
         const HOST: Vec3 = Vec3::new(-76.1, 58.47, 9481.53);
         const ULP: f32 = 1.0 / 1024.0;
         const FRAMES: usize = 240;
         const DT: f64 = 1.0 / 60.0;
-        // The M2 attachment point's own offset from the bone — an ordinary rig-sized quantity.
         let offset = Vec3::new(0.02, 0.03, 0.04);
 
-        // The bone swings about X, so its tip travels in y/z — and bevy z IS the ~9.5 k axis here.
+        // The bone swings about X, so its tip moves in y and z, and Bevy z is the ~9.5 k axis.
         let theta = |f: usize| 0.02 * (std::f64::consts::TAU * (f as f64 * DT) / 4.0).sin();
         let (mut abs, mut rel, mut oracle) = (Vec::new(), Vec::new(), Vec::new());
         for f in 0..FRAMES {
@@ -346,13 +249,10 @@ mod tests {
             let bone = Affine3A::from_rotation_x(t as f32)
                 * Affine3A::from_translation(Vec3::new(0.0, 1.9, 0.0));
             let local = Affine3A::from_translation(offset);
-            // The route the scene graph takes: the host's world affine × the bone × the offset,
-            // every product landing back in absolute f32 world space.
+            // The scene-graph route: every product lands in absolute f32 world space.
             let host = Affine3A::from_translation(HOST);
             abs.push(Vec3::from((host * bone * local).translation));
-            // The rider's route: the same chain in the host's own frame (translation zeroed). The
-            // world position rides the slot's `rig_origin` and is added camera-relative, so it
-            // contributes nothing to the MOTION measured here.
+            // The rider's route: the same chain in the host's frame; `rig_origin` carries the rest.
             let basis = Affine3A::from_translation(Vec3::ZERO);
             rel.push(Vec3::from((basis * bone * local).translation));
             // f64 truth for the same chain, measured from the host.
@@ -374,9 +274,7 @@ mod tests {
             .map(|i| (oracle[i] - 2.0 * oracle[i - 1] + oracle[i - 2]).length())
             .fold(0.0f64, f64::max) as f32;
 
-        // The premise: this chain really does exercise the large world axis, so the absolute route
-        // really is spending a whole ULP. Without this, a chain that drifted onto a small axis
-        // would make the comparison below pass while measuring nothing.
+        // The premise: the chain moves along the large axis, or the comparison measures nothing.
         let travel = (1..abs.len())
             .map(|i| (abs[i].z - abs[i - 1].z).abs())
             .fold(0.0f32, f32::max);
@@ -390,8 +288,6 @@ mod tests {
              (Δ² = {abs_d2} yd, ULP = {ULP})"
         );
 
-        // The verdict: the rider's frame carries the chain's own curvature and nothing else, while
-        // the absolute route carries a whole grid step on top of it — two orders apart.
         assert!(
             rel_d2 < 2.0 * true_d2 + 1.0e-6,
             "the rider frame must add nothing to the chain's own curvature \
@@ -403,8 +299,6 @@ mod tests {
              rider Δ² = {rel_d2} yd"
         );
 
-        // And the rider's frame agrees with f64 truth at rig scale, where the absolute route
-        // cannot: its answer is a ~9481-yard number and its error is that number's ULP.
         let rel_err = rel
             .iter()
             .zip(&oracle)
diff --git a/crates/benilla-world/src/schedule.rs b/crates/benilla-world/src/schedule.rs
index 3b957c77..86b4381e 100644
--- a/crates/benilla-world/src/schedule.rs
+++ b/crates/benilla-world/src/schedule.rs
@@ -1,67 +1,24 @@
-//! The cross-subsystem **frame ordering contract** for the world-transition pipeline.
-//!
-//! A teleport must not flash the half-loaded world: the moment the player snaps, the loading screen
-//! has to cover the swap *that same frame*. That requires four subsystems — owned by separate
-//! plugins — to run in a fixed order within `Update`:
-//!
-//! 0. [`WorldStage::Net`] — `net::apply_net_updates` drains the world stream into ECS entities and
-//!    surfaces the teleport/worldport as Bevy events, *before* the player reads them.
-//! 1. [`WorldStage::Input`] — `player::control` applies input + the teleport/worldport snap.
-//! 2. [`WorldStage::Stream`] — `terrain_stream::stream_terrain` reacts: swaps/streams tiles around the
-//!    NEW position and publishes residency ([`crate::loading_screen::WorldLoadProgress`]).
-//! 3. [`WorldStage::Present`] — `loading_screen::drive_loading_screen` reads that residency and shows/
-//!    hides the cover. Visibility set here propagates in `PostUpdate` and renders the same frame.
-//!
-//! Expressing this as a [`SystemSet`] (rather than `.after(some_fn)`) keeps each system + its private
-//! params encapsulated in its own module — plugins opt in with `.in_set(..)` and never reference one
-//! another's functions. Add future world-transition work to the matching stage.
+//! The frame ordering contract for the world-transition pipeline: a teleport's loading screen must
+//! cover the swap the same frame, so four subsystems run in [`WorldStage`] order within `Update`.
+//! Plugins join a stage with `.in_set(..)` and never name one another's functions.
 
 use bevy::prelude::*;
 
-/// **Is there a world?** — the run condition every world-*owning* subsystem gates on.
-///
-/// The world exists only while a character is in it. That reads as a truism and was, for most of
-/// this project, false: benilla began as a terrain viewer, so the streamers ran from `Startup` and
-/// the client loaded and simulated Elwynn Forest behind the login screen — 5095 tiles and tens of
-/// thousands of entities, anchored on a hardcoded [`crate::SPAWN_XY`], for a character who might
-/// be on another continent. 0540 gated the *camera* (the world was at least not drawn); 0772
-/// measured what was left — 5.5 cpu ms/frame of streaming, visibility sweeps, palette uploads and
-/// render-world prepare under a static background image, and a 638 ms worst frame — and left the
-/// load itself open as a director's call. The call: **don't load the world until we have to.**
-///
-/// Consumers gate on this, not on `in_state(InWorld)` written out by hand, so "what counts as
-/// having a world" has one definition to change. The camera's own gate
-/// ([`crate::player::setup::gate_world_camera`]) is deliberately *wider* — it also renders under
-/// an opaque loading screen, which is what compiles the world's pipelines before the first visible
-/// frame.
+/// The run condition every world-owning subsystem gates on: the world exists only while a
+/// character is in it. The camera's gate (`player::setup::gate_world_camera`) is wider: it also
+/// renders under an opaque loading screen, which compiles the world's pipelines early.
 pub(crate) fn world_is_live(live: Res<WorldLive>) -> bool {
     live.0
 }
 
-/// **Is there a world?**, as the engine's own one-bit fact rather than a read of the game's
-/// session state machine.
-///
-/// It was `Res<State<char_select::ClientState>>` — the engine asking a four-variant enum about
-/// screens it has no other business knowing (`Login`, `CharSelect`, `CharCreate`), which is a
-/// dependency `benilla-world` cannot have. Whatever owns the session writes this; a program with
-/// no session at all leaves it and gets a world, which is what `benilla-worldview` wants.
-///
-/// Deliberately **not** a `States`. A mirrored state applies at the next transition point, so
-/// every `OnExit` teardown would fire a frame after the screen it belongs to; and a Bevy
-/// `ComputedStates` — which would have no lag — cannot be implemented across the crate boundary
-/// this exists to create (foreign trait, foreign type). A resource plus [`world_left`] is the
-/// same two behaviours with neither problem.
+/// Whether a world is live, written by whatever owns the session. Not a `States`: a mirrored state
+/// applies at the next transition point, a frame late for every teardown.
 #[derive(Resource, Default, Clone, Copy, PartialEq, Eq)]
 pub struct WorldLive(pub bool);
 
-/// The **falling edge** of [`WorldLive`] — the teardown trigger that replaces
-/// `OnExit(Screen::InWorld)`.
-///
-/// Leaving the world releases it: without this a `/logout` back to character select leaves the
-/// whole streamed world resident and unowned, because the run condition above only stops it being
-/// *maintained*, which is precisely what makes an abandoned world immortal.
-///
-/// Each gated system gets its own `Local`, so each sees the edge exactly once.
+/// The falling edge of [`WorldLive`], the world's teardown trigger: the run condition only stops
+/// upkeep, so without it a logout leaves the streamed world resident. Each gated system has its
+/// own `Local`, so each sees the edge once.
 pub(crate) fn world_left(live: Res<WorldLive>, mut was_live: Local<bool>) -> bool {
     let left = *was_live && !live.0;
     *was_live = live.0;
@@ -71,19 +28,21 @@ pub(crate) fn world_left(live: Res<WorldLive>, mut was_live: Local<bool>) -> boo
 /// Ordered stages of the per-frame world-transition pipeline (configured `.chain()`ed in `Update`).
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum WorldStage {
-    /// Drain the world stream into ECS entities + surface teleport/worldport messages.
+    /// `net::apply_net_updates`: the world stream into entities, teleport and worldport surfaced
+    /// before the player reads them.
     Net,
-    /// Player input + teleport/worldport snap.
+    /// `player::control`: input and the teleport or worldport snap.
     Input,
-    /// Terrain residency: tile swap/stream around the (possibly just-snapped) position.
+    /// `terrain_stream::stream_terrain`: tiles around the possibly just-snapped position, and the
+    /// residency (`loading_screen::WorldLoadProgress`) the cover reads.
     Stream,
-    /// Loading-screen present: cover the world while the surrounding tiles aren't resident.
+    /// `loading_screen::drive_loading_screen`: the cover while the surrounding tiles are not
+    /// resident, set here and rendered the same frame.
     Present,
 }
 
-/// Installs the [`WorldStage`] ordering + the boot-order correction below. Add before the subsystem
-/// plugins (order doesn't matter — set configuration is resolved at schedule build), but *after*
-/// `DefaultPlugins`, which is where `StatesPlugin` seeds the order this fixes.
+/// Installs the [`WorldStage`] order and the boot-order fix below; add it after `DefaultPlugins`,
+/// whose `StatesPlugin` seeds the order the fix moves.
 pub(crate) struct SchedulePlugin;
 
 impl Plugin for SchedulePlugin {
@@ -103,35 +62,11 @@ impl Plugin for SchedulePlugin {
     }
 }
 
-/// **The initial state's `OnEnter` runs AFTER the app is built, not before it.**
-///
-/// `bevy_state` seeds the startup order with (`bevy_state-0.18.1/src/app.rs:308-309`):
-///
-/// ```ignore
-/// schedule.insert_after(PreUpdate, StateTransition);
-/// schedule.insert_startup_before(PreStartup, StateTransition);   // ← this one
-/// ```
-///
-/// so the one-shot transition that enters the *initial* state runs before `PreStartup` — ahead of
-/// every `Startup` system, i.e. ahead of the patch chain ([`benilla_assets::AssetSet::Open`]), the
-/// Lua VM, the mixer and every catalog. An `OnEnter` for the state the app boots into therefore
-/// sees an empty world, which is not what "on entering this state" means anywhere else.
-///
-/// Three subsystems each hit this independently and each wrote the same local workaround — spawn
-/// from a per-frame `Update` poll instead of the state edge:
-/// [`crate::login::screen::materialize_screen`], [`crate::char_select::screen::enter_select`] and
-/// `sound::glue::start_glue_music`. Their comments name it "the boot-order trap". It is one cause
-/// with three patches, which is the shape §3 says to go after rather than add a fourth to.
-///
-/// The fix is to move that single startup entry to the end: the initial transition now runs after
-/// `PostStartup`, so `OnEnter(<initial>)` observes a fully built app exactly like every later
-/// transition does. Safe here because **no `Startup` system in the workspace writes `NextState`**
-/// (every writer is an `Update` system), so nothing can be waiting on the transition to be applied
-/// mid-startup; and `insert_state`/`init_state` insert the `State<S>` resource directly at plugin
-/// build, so a `Startup` system reading `Res<State<..>>` is unaffected either way.
-///
-/// This does not retire the three workarounds — two of them also re-spawn when *async* client art
-/// lands, which is a different clock. It removes the boot-order reason to write a fourth.
+/// Run the initial state's `OnEnter` after startup. `bevy_state` seeds the startup
+/// `StateTransition` before `PreStartup` (`bevy_state-0.18.1/src/app.rs:309`), so an `OnEnter`
+/// for the boot state would run before the patch chain, the Lua VM, the mixer and every catalog;
+/// this moves it after `PostStartup`. Safe while no `Startup` system writes `NextState`;
+/// `insert_state`/`init_state` insert `State<S>` at plugin build either way.
 fn move_initial_state_transition_after_startup(app: &mut App) {
     use bevy::app::MainScheduleOrder;
     use bevy::state::state::StateTransition;
@@ -139,7 +74,7 @@ fn move_initial_state_transition_after_startup(app: &mut App) {
     let mut order = app.world_mut().resource_mut::<MainScheduleOrder>();
     let before = order.startup_labels.len();
     order.startup_labels.retain(|l| !(**l).eq(&StateTransition));
-    // Only re-seat what was actually there — if bevy_state ever stops seeding it, do not invent it.
+    // Re-seat only what was there: if `bevy_state` stops seeding it, do not invent it.
     if order.startup_labels.len() < before {
         order.insert_startup_after(PostStartup, StateTransition);
     }
@@ -152,9 +87,7 @@ mod tests {
 
     use super::SchedulePlugin;
 
-    /// A stand-in for whatever states the composing binary registers — this test is about the
-    /// boot-order re-seat, not about any particular state machine, and the engine no longer knows
-    /// the game's.
+    /// A stand-in for the composing binary's states.
     #[derive(States, Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
     enum Screen {
         #[default]
@@ -164,10 +97,6 @@ mod tests {
     #[derive(Resource)]
     struct BuiltAtStartup;
 
-    /// What [`super::move_initial_state_transition_after_startup`] buys: an `OnEnter` for the state
-    /// the app BOOTS INTO sees the resources `Startup` built. Without the re-seat this is false —
-    /// the initial transition runs ahead of `PreStartup` — and that is the boot-order trap three
-    /// subsystems each worked around by hand.
     #[test]
     fn the_initial_states_on_enter_sees_what_startup_built() {
         #[derive(Resource, Default)]
diff --git a/crates/benilla-world/src/shaders.rs b/crates/benilla-world/src/shaders.rs
index 434813ac..52183c43 100644
--- a/crates/benilla-world/src/shaders.rs
+++ b/crates/benilla-world/src/shaders.rs
@@ -1,34 +1,13 @@
-//! **The engine's WGSL, compiled into the binary** (decision 1175).
-//!
-//! The seven shaders under `src/shaders/` are the *engine's* — 1171's line, unchanged: the game's
-//! five live in `benilla-app`, and `embedded_asset!` is per-crate by construction, so the seam
-//! costs nothing to keep.
-//!
-//! Until 1175 these were served from a file asset root that `boot.rs` baked as
-//! `concat!(env!("CARGO_MANIFEST_DIR"), "/assets")` — an absolute path into the *build* machine's
-//! source tree. On any other machine it resolves to nothing and the world renders with no shaders
-//! at all: the "silently-no-shaders trap" `capture/mod.rs`'s header already named. Embedding is
-//! what makes the binary answer for its own content; `benilla-assets` has done it for its four
-//! since it had them, and this is the same move for the other twelve.
-//!
-//! **Why these calls live in a file directly under `src/`.** `embedded_asset!` derives the served
-//! path by stripping everything up to and including the crate's `src/` from `file!()`, then
-//! re-prefixing the crate name — and it does **not** normalize the result. Called from
-//! `src/sun/materials.rs` the shader would land at `embedded://benilla_world/sun/…`, and reaching
-//! back out with `"../shaders/x.wgsl"` would bake a literal `..` component into the virtual
-//! directory. One registration point at the root of `src/` is what keeps every path
-//! `embedded://benilla_world/shaders/<name>.wgsl`.
+//! The engine's WGSL, embedded in the binary; the game's shaders are embedded by `benilla-app`.
+//! These calls must stay in a file directly under `src/`: `embedded_asset!` derives the served
+//! path from `file!()` without normalizing it, so a call from a submodule would serve the shader
+//! under that module's directory instead of `embedded://benilla_world/shaders/<name>.wgsl`.
 
 use bevy::prelude::*;
 
-/// Compile the engine's seven WGSL files in and register them under
-/// `embedded://benilla_world/shaders/…`.
-///
-/// Added as the first member of [`crate::world_plugins::WorldPlugins`] rather than exposed as a
-/// free function a composition root must remember to call: a shader that fails to register is
-/// invisible until something tries to draw with it, which is the exact failure mode this record
-/// closes. `Plugin::build` runs at `add_plugins` time, and both binaries add `DefaultPlugins`
-/// (which creates the registry these calls fill) before `WorldPlugins`.
+/// Embed the engine's WGSL files under `embedded://benilla_world/shaders/`. The first member of
+/// [`crate::world_plugins::WorldPlugins`]; it needs `DefaultPlugins`, which creates the asset
+/// registry, added first.
 pub(crate) fn plugin(app: &mut App) {
     bevy::asset::embedded_asset!(app, "shaders/sky_vertex.wgsl");
     bevy::asset::embedded_asset!(app, "shaders/sky.wgsl");
@@ -47,13 +26,8 @@ mod tests {
     use bevy::asset::io::AssetSourceId;
     use bevy::prelude::*;
 
-    /// Every `.wgsl` under `src/shaders/` answers at `embedded://benilla_world/shaders/<name>`.
-    ///
-    /// `embedded_asset!` derives that path from `file!()` and does **not** normalize it, so it is
-    /// not something to reason about — this reads the bytes back through the same source a
-    /// material's `ShaderRef` goes through. Driving the loop off the *directory listing* is the
-    /// other half: a shader added without a registration line, or registered from a submodule
-    /// (which silently prefixes that module's directory), fails here instead of drawing nothing.
+    /// Reads each file on disk back through the embedded source a `ShaderRef` uses, so a shader
+    /// that is unregistered, or registered from a submodule, fails here instead of drawing nothing.
     #[test]
     fn every_engine_shader_answers_at_its_embedded_path() {
         let mut app = App::new();
diff --git a/crates/benilla-world/src/shaders/celestial.wgsl b/crates/benilla-world/src/shaders/celestial.wgsl
index 6700b09d..7ba44c8f 100644
--- a/crates/benilla-world/src/shaders/celestial.wgsl
+++ b/crates/benilla-world/src/shaders/celestial.wgsl
@@ -1,50 +1,9 @@
-// Celestial DISCS (the sun, the white moon, moon02) and their additive lens-flare GLARES — unlit,
-// gamma-correct billboards drawn over the sky dome. Discs get a world-space HORIZON CLIP + the
-// reference's PER-VERTEX ALPHA FADE, so a setting body melts into the horizon as a whole-disc gradient;
-// glares (mode `celestial.z` = 1) skip the clip — the reference's flare draw `0x7e57e0` never calls the
-// clip `0x6d1960`; the lens-flare envelope gates them — and ADD in gamma instead of blending.
-//
-// HORIZON (RE: 0x6d1960, wow-re celestial-bodies note Addendum #7 / decisions 0485+0523+0529 — VERIFIED
-// off the binary): every disc routes through the same clip+fade — the quad is clipped to the horizon
-// plane (height 0; new crossing vertices get alpha 0, a fully-below body is skipped), and the per-vertex
-// fade store is CONDITIONAL (guard `0x6d1ac5`): only vertices inside the 0.4-unit near-horizon band get
-// `alpha = clamp(2.5·height, 0, 1)`; every vertex ABOVE the band keeps the disc COLOUR's own alpha byte
-// — 0xFF for the sun/white moon (the per-frame diffuse broadcast), 0 for moon02 (its colour dword has no
-// writer), which is why the reference never shows a second moon: the draw runs, the blender paints
-// nothing. The rasterizer interpolates those vertex alphas, so a straddling sun grades 0-at-the-cut →
-// full-at-the-top across the WHOLE disc. We reconstruct exactly that per-fragment, in distance-invariant
-// sin-elevation terms (`k = 2.5·12 = 30` — the binary's band at its radius-12 disc) from the quad's
-// per-frame `span`; the earlier per-fragment band approximation (0485, then 0524's workaround for the
-// bar it caused) is superseded by decision 0529.
-//
-// GAMMA-SPACE BLEND — the gamma composite lane (decision 0161): the reference's framebuffer holds gamma
-// bytes and ALL its hardware blending happens in gamma space, so the faithful sky-body blend is a
-// GAMMA-space one. We emit a **premultiplied GAMMA** colour under `AlphaMode::Premultiplied`:
-// `out = (disc_gamma · a, a)` — the disc blends over the (gamma) dome exactly like the reference, letting the
-// blue night-dome bleed through the moon's feathered edges + horizon fade (the teal "halo"). Bevy hands us
-// `base.rgb` already LINEARISED (sRGB texture × linear base_color), so we round-trip `linear_to_srgb` to
-// recover the gamma disc colour first — the one conversion left in this shader.
-//
-// GAMMA-SPACE ADD (glare mode, `celestial.z` = 1; decision 0502): the reference's lens flares blend
-// SRC_ALPHA, ONE onto the gamma framebuffer (`0x7e5a16`) — the flare's gamma texel × the intensity byte is
-// ADDED to the scene's gamma bytes, saturating per channel (a warm disc + a warm flare clip to WHITE at
-// the core — the blown-out reference sun). A plain Bevy `AlphaMode::Add` adds LINEAR values, which
-// under-weights every mid-tone and can never saturate — the "too yellow" sun (the residual 0485/0500
-// recorded). Here: `out = (glare_gamma · a, 0.0)` under `AlphaMode::Add`'s (ONE, 1−src_alpha) blend
-// ⇒ `dst + gamma·a` — the reference's byte addition, with `a` = the lens-flare intensity envelope.
-//
-// SKY-PASS DEPTH (celestial-frame-anatomy pin; the law + its history in `sky_order.rs`): the reference
-// draws its whole sky in a squashed back depth slice with the depth TEST on — the glare last of all,
-// further back still (`[0.995, 1.0]`) — so the z-buffer occludes every sky element per-pixel behind
-// everything the world drew (a ridge, a wall, one leaf), while the sky itself (which writes no depth)
-// never blocks it. Same mechanism here: the quads' geometry stays on their shells (12 units for the
-// glare — its pinned screen footprint — and `far·0.85` for the discs), but EVERY vertex pins its
-// clip z to 0.0 — reverse-Z "infinitely far" (`sky_vertex.wgsl`, the stage every sky shader shares) —
-// under Bevy's GreaterEqual test: a fragment passes only where the depth buffer still holds the
-// clear value, i.e. where no opaque geometry drew. Discs used to pass their own rasterized depth
-// through, on the assumption that their shell sits beyond all world geometry; the WDL horizon ring
-// reaches past it, so a distant hill lost to a disc it should occlude. Until 2016 the pin was a
-// `frag_depth` write here, which cost the pipeline its early-Z; the vertex pin is the same number.
+// Celestial discs (sun, white moon, moon02) and their glares, blended in gamma space as the
+// reference blends onto gamma bytes. Discs take its horizon clip and fade (`0x6d1960`): clipped
+// at height 0 with alpha 0 there, `clamp(2.5 * height, 0, 1)` in the 0.4-unit band above
+// (`0x6d1ac5`), the colour's alpha byte beyond. Glares skip the clip (`0x7e57e0`) and add,
+// saturating, like the reference's SRC_ALPHA, ONE blend (`0x7e5a16`). Depth is the far pin in
+// `sky_vertex.wgsl`.
 
 #import bevy_pbr::{
     pbr_fragment::pbr_input_from_standard_material,
@@ -53,22 +12,14 @@
     mesh_view_bindings::view,
 }
 
-// Per-material control (set in `sun/materials.rs` `CelestialExt`). `.x` = the horizon alpha-ramp scale `k`
-// (`k = 30.0`: the binary's 0.4-unit band at its radius-12 disc, in sin-elevation terms — 0x6d1960).
-// `.y` = brightness multiplier — 1.0 everywhere (the old moon HDR boost died with
-// decision 0163; the moon's glow is FFXGlow's blur² on the disc's own bytes). `.z` = mode: 0 = disc
-// (horizon clip + premultiplied gamma blend), 1 = additive glare (no clip, gamma add). `.w` = the disc
-// COLOUR's own alpha byte (1.0 sun/white moon, 0.0 moon02 — its dword has no writer; Addendum #7).
+// `CelestialExt::fade`: `.x` the ramp slope in sin-elevation (`2.5 * height` at the reference's
+// radius 12 is `30 * y`), `.y` the brightness on RGB only, `.z` 0 for a disc and 1 for a glare,
+// `.w` the colour's alpha byte above the band, 0 for moon02 in clear weather (no writer).
 @group(#{MATERIAL_BIND_GROUP}) @binding(100) var<uniform> celestial: vec4<f32>;
-// The disc quad's vertical span in sin-elevation: `.x` = bottom edge, `.y` = top edge (written per
-// frame by the follow systems; unused in glare mode). The reference fade is PER-VERTEX (0x6d1960
-// stores alpha on the quad's vertices — conditionally, guard 0x6d1ac5 — and the rasterizer
-// interpolates), so the fragment reconstructs that interpolation from the span (decision 0529).
+// The disc quad's vertical span in sin-elevation, `.x` bottom edge and `.y` top edge, per frame.
 @group(#{MATERIAL_BIND_GROUP}) @binding(101) var<uniform> span: vec4<f32>;
 
-// The reference's per-VERTEX alpha rule at sin-elevation `y` (0x6d1960 + guard 0x6d1ac5): inside
-// the near-horizon band (`k·y < 1`) the vertex takes the fade ramp; above it it keeps the disc
-// colour's own alpha byte (`celestial.w`).
+// The reference's per-vertex alpha at sin-elevation `y`: the ramp inside the band, the byte above.
 fn vertex_alpha(y: f32) -> f32 {
     let ramp = y * celestial.x;
     return select(celestial.w, clamp(ramp, 0.0, 1.0), ramp < 1.0);
@@ -87,19 +38,8 @@ fn fragment(in: VertexOutput, @builtin(front_facing) is_front: bool) -> @locatio
 
     var a = base.a;
     if celestial.z < 0.5 {
-        // DISC: horizon clip + the reference's PER-VERTEX fade, reconstructed (0x6d1960 +
-        // Addendum #7, decision 0529). The binary clips the quad at height 0 (new crossing
-        // vertices, alpha exactly 0 — a fully-below body is skipped) and stores the band ramp on
-        // its vertices; the rasterizer interpolates. A setting sun is therefore a whole-disc
-        // gradient melting to 0 at the horizon cut — not a solid disc with a thin faded strip
-        // (the old per-fragment band, 0485/0524, sighted twice: moon02's black bar and the
-        // too-hard sunset). Here: interpolate the vertex rule linearly between the quad's
-        // clipped bottom edge and its top edge (`span`, sin-elevation — camera-facing quad, so
-        // the vertical axis maps to elevation), clip below the horizon. Elevated bodies
-        // (`k·span.x ≥ 1`) reduce to `a × celestial.w` exactly — the fixtures' regime. Glares
-        // skip all of it (0x7e57e0 never calls the clip; the lens-flare envelope gates them).
-        // The reference also alpha-tests GEQUAL 1/255; under our premultiplied blend a 0-alpha
-        // fragment already contributes nothing, so no discard.
+        // Disc: the vertex rule, interpolated from the clipped bottom edge to the top. The
+        // reference's GEQUAL 1/255 alpha test needs no discard: zero alpha adds nothing here.
         let dir = normalize(in.world_position.xyz - view.world_position.xyz);
         let y = dir.y;
         if y <= 0.0 {
@@ -113,17 +53,12 @@ fn fragment(in: VertexOutput, @builtin(front_facing) is_front: bool) -> @locatio
         }
     }
 
-    // GAMMA output — see the header. `base.rgb` is linear (Bevy); recover the gamma colour,
-    // premultiply by `a` in gamma space, emit raw onto the gamma buffer (0161). `celestial.y` =
-    // brightness (1.0 everywhere; multiplies the RGB only, so the blend's dst term is unaffected).
+    // `base.rgb` arrives linear (Bevy decodes the sRGB texture); the target takes gamma values.
     let gamma = linear_to_srgb(base.rgb);
-    // (The far depth for BOTH is the vertex stage's — see the header: a sky element survives only
-    // on pixels no opaque geometry claimed, the reference's back-slice depth test.)
     if celestial.z >= 0.5 {
-        // ADDITIVE GLARE: (rgb·a, alpha 0) under (ONE, 1−src_alpha) ⇒ `dst + gamma·a` — the
-        // reference's SRC_ALPHA, ONE byte addition, `a` = the lens-flare intensity envelope.
+        // Glare: alpha 0 under `AlphaMode::Add` gives `dst + gamma * a`, `a` the flare envelope.
         return vec4<f32>(gamma * a * celestial.y, 0.0);
     }
-    // DISC: premultiplied gamma blend (AlphaMode::Premultiplied).
+    // Disc: premultiplied gamma under `AlphaMode::Premultiplied`.
     return vec4<f32>(gamma * a * celestial.y, a);
 }
diff --git a/crates/benilla-world/src/shaders/cloud.wgsl b/crates/benilla-world/src/shaders/cloud.wgsl
index ad0afed6..084b54b8 100644
--- a/crates/benilla-world/src/shaders/cloud.wgsl
+++ b/crates/benilla-world/src/shaders/cloud.wgsl
@@ -1,22 +1,7 @@
-// The visible CLOUD LAYER — the reference's sky-dome cloud strip (wow-re
-// `cloud-coverage-pipeline.md` §3 + Addendum A).
-//
-// All color math already happened CPU-side, exactly like the reference: the kernel's `0x6cfb00`
-// port builds the RGBA image per regen (gradient + sun-aligned glow in gamma bytes, alpha = the
-// curve-mapped coverage byte) and uploads it — the reference binds that color buffer zero-copy to
-// its gx texture (`0x58ac70`). The fragment therefore only samples the texel and applies the dome
-// mesh's vertex-colour rim fade (ring alphas 0xff×9, 0x80, 0, 0 — `0x6d0530`).
-//
-// GAMMA: the texels are gamma bytes in a NON-sRGB texture (sampling returns them raw), and the
-// output is a premultiplied-gamma blend over the (gamma) sky, like the celestial discs
-// (decision 0161).
-
-//
-// SKY-PASS DEPTH (see `sky_order.rs`, "The depth law"): the dome's radius does not decide occlusion —
-// the reference draws the whole sky first, in a squashed back depth slice, and the opaque world paints
-// over it. The far depth reproduces that: clouds survive only where no world geometry drew. It is
-// pinned in the VERTEX stage (`sky_vertex.wgsl`, shared by every sky shader); this fragment writes
-// colour only and keeps its early-Z (2016).
+// The cloud dome. Its colour is CPU-side as in the reference: the kernel's `0x6cfb00` port builds
+// the image the reference binds as its texture (`0x58ac70`). This stage applies the dome's rim
+// fade (`0x6d0530`) and blends the raw gamma texels premultiplied. Depth is the far pin in
+// `sky_vertex.wgsl`.
 
 #import bevy_pbr::forward_io::VertexOutput
 
diff --git a/crates/benilla-world/src/shaders/ffx_glow.wgsl b/crates/benilla-world/src/shaders/ffx_glow.wgsl
index 965666be..24de1575 100644
--- a/crates/benilla-world/src/shaders/ffx_glow.wgsl
+++ b/crates/benilla-world/src/shaders/ffx_glow.wgsl
@@ -1,58 +1,32 @@
-// FFXGlow — the reference's full-screen glow, transcribed from the SHIPPED ARB programs
-// (Shaders\Pixel\FFXGlow.bls / FFXGauss4.bls, read straight out of the MPQ) + wow-re's ffxeffects
-// node (T3: the CPU-side pass math diffed bit-exact).
-//
-//   blur   = Gauss4(Gauss4(Box4(scene → ¼), horizontal), vertical)     weights ⅛ ⅜ ⅜ ⅛ (shipped)
-//   out    = lerp(screen, blur, z) + w · blur²                          (FFXGlow.bls, exact)
-//
-// `w` is the per-zone LightParams glow weight (authored data — ≈0.647 in Elwynn), `z` is the haze
-// mix — the drunk/underwater screen-toward-blur cross-fade (0 sober and dry; wow-re
-// drunk-blur-z.md, decision 1009 §A). The reference runs this in GAMMA bytes, and since 0161 the
-// whole frame composites in gamma too — but in a FLOAT buffer, which unlike the reference's byte
-// buffer does not saturate at 1.0 per draw. Every read of the scene RT below therefore clamps to
-// 1.0 first (the byte semantics restored at the read), does the byte math, and decodes once — the
-// present-encode then lands the reference's exact byte.
-// The blur² is the whole character of the vanilla glow: mid-tones (0.5 → 0.25) barely bloom,
-// highlights bloom fully — a square-law a linear-composite bloom cannot express (decision 0158).
-//
-// The geometry is fully byte-pinned (wow-re ffxeffects/scratch/blur-geometry.md): one Box4
-// downsample full→¼, Gauss4 at ±0.5/±2.5 texels, texel-centre base UVs with zero half-texel
-// residual — offsets transcribe as exact source-texel counts.
+// FFXGlow, the reference's full-screen glow (`FFXGlow.bls`, `FFXGauss4.bls`):
+//   blur = Gauss4(Gauss4(Box4(scene → ¼), horizontal), vertical)
+//   out  = lerp(screen, blur, z) + w · blur²
+// `w` is the zone's LightParams glow weight, `z` the drunk or underwater haze mix. Tap offsets
+// count source texels from texel-centre UVs, with no half-texel shift. The math runs on gamma
+// bytes, and every scene read clamps to 1.0 because the float target does not saturate.
 
 #import bevy_core_pipeline::fullscreen_vertex_shader::FullscreenVertexOutput
 
 @group(0) @binding(0) var in_tex: texture_2d<f32>;
 @group(0) @binding(1) var in_samp: sampler;
-// Combine-pass extras (unused — and unbound — in the downsample/blur passes).
+// Combine-pass bindings, unbound in the downsample and blur passes.
 @group(0) @binding(2) var blur_tex: texture_2d<f32>;
 struct FfxCombine {
-    // x = the zone glow weight `w` (BOTH combines' blur² weight — the death pack reuses it as
-    // primary.w); y = the FFXDeath gate (1 while ghost, else 0 — byte-verified instant, no ramp);
-    // z = the drunk/underwater haze mix; w = the deband-dither arm.
+    // x = zone glow weight `w` (both combines), y = FFXDeath gate (1 while a ghost, no ramp),
+    // z = haze mix, w = deband dither on.
     lane: vec4<f32>,
-    // xy = the GlowWave phases `(t mod 3174)/3174` and `(t mod 2805)/2805`; zw unused. Written on
-    // every frame, read only by `fs_combine_wave`.
+    // xy = the GlowWave phases `(t mod 3174)/3174` and `(t mod 2805)/2805`, t in ms; zw unused.
     wave: vec4<f32>,
 }
 @group(0) @binding(3) var<uniform> ffx: FfxCombine;
-// The 128×128 wave LUT and its own REPEAT sampler — bound on EVERY combine, sampled only by the
-// underwater entry. A bound-but-unsampled texture costs a dry frame nothing, and one layout keeps
-// the two entries interchangeable at draw time (the alternative, a second layout, would make the
-// pipeline swap a bind-group swap too).
+// The 128×128 wave LUT and its repeat sampler: bound on every combine, sampled only underwater.
 @group(0) @binding(4) var wave_tex: texture_2d<f32>;
 @group(0) @binding(5) var wave_samp: sampler;
 
 
 
-// The reference's ONE downsample: full → ¼ directly, via Box4 — 4 bilinear taps at source-texel
-// offsets {−1.5, +0.5}² (a 4×4 footprint; byte-pinned table 0xce89cc, wow-re blur-geometry.md).
-//
-// Each tap clamps to 1.0 BEFORE the average: the reference reads a BYTE scene RT, where an
-// additive stack saturated at 255 draw by draw — our float buffer keeps summing past 1.0, and an
-// unclamped read here feeds that super-white into `w·blur²`, which squares it into a huge hard
-// glow disc (the Frost Nova mist stack — ~400 additive puffs — reaches ~5–10 in-buffer). The
-// clamp is the byte buffer's saturating-add semantics applied at the lane's read (0161's own
-// premise: the framebuffer holds bytes).
+// Box4, full → ¼: four bilinear taps over a 4×4 footprint (`0xce89cc`), each clamped to 1.0 like
+// the reference's byte target; an unclamped super-white would square into a hard glow disc.
 @fragment
 fn fs_downsample(in: FullscreenVertexOutput) -> @location(0) vec4<f32> {
     let texel = 1.0 / vec2<f32>(textureDimensions(in_tex));
@@ -64,9 +38,7 @@ fn fs_downsample(in: FullscreenVertexOutput) -> @location(0) vec4<f32> {
         * 0.25;
 }
 
-// Gauss4: taps at ±0.5 (weight 0.375) and ±2.5 (weight 0.125) source texels — byte-pinned
-// (0x6cad10 tap arrays; corrects the earlier INFERRED ±1.5 outer tap). Weights are the shipped
-// FFXGauss4.bls constants.
+// Gauss4: taps at ±0.5 and ±2.5 source texels (0x6cad10), weights from FFXGauss4.bls.
 fn gauss4(uv: vec2<f32>, axis: vec2<f32>) -> vec4<f32> {
     let texel = axis / vec2<f32>(textureDimensions(in_tex));
     return textureSample(in_tex, in_samp, uv - 2.5 * texel) * 0.125
@@ -91,41 +63,17 @@ fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
     return select(hi, lo, c <= vec3<f32>(0.04045));
 }
 
-// The FFXGlow combine, byte-for-byte in gamma space (z = 0: the standard glow pass) — and, while
-// the ghost flag is up, the FFXDeath combine that REPLACES it (decision 0308 §7, byte-VERIFIED
-// wow-re death-pass.md: one active-pass slot `[0xce8bb4]` — the death composite swaps in whole,
-// activation is PLAYER_FLAGS_GHOST only, INSTANT, no time ramp). The shipped FFXDeath.bls:
-//   luma = sat(dot(screen + w·blur², (0.299, 0.587, 0.144)))     (Blizzard's 0.144, not 0.114)
-//   out  = luma + primary.rgb · sat(4·luma·(1−luma))
-// The CPU pack `0x6cb930` builds primary as `(LightParams.glow·255)<<24 | 0x5393A8`: rgb is the
-// CONSTANT steel blue-gray 0x53/0x93/0xA8, and primary.w (the blur² weight) is the same zone glow
-// the glow pass uses — so ffx.lane.x serves both combines and ffx.lane.y is a pure 0/1 gate.
-// **Deband dither** (`ffx.lane.w`, off by default — see `ffx_glow.rs`). The frame's ONE quantization
-// to 8 bits happens on `outg` below: it is a gamma-space float, and the surface's sRGB
-// present-encode rounds it to a byte. A smooth surface therefore steps in 1/255, and at the
-// gradients a lit character actually has (~1.3 levels/px on a bare arm) a body drifting the
-// 0.11 px/frame of a breathing idle needs ~7 FRAMES to accumulate one step — so the shading
-// updates at ~8 Hz on a 60 Hz display and every iso-luma contour crosses its threshold together.
-// Large motions clear a level per frame and hide it completely, which is exactly the
-// small-moves-tick / big-moves-smooth split the director reported.
-//
-// The hash is Bevy's own `screen_space_dither` (its tonemapping pass applies it and we skip that
-// pass entirely — `Tonemapping::None` returns before the node does anything, so
-// `DebandDither::Enabled` on our camera is dead code). It is a pure function of the PIXEL, not of
-// time: a still frame stays bitwise still, while a moving gradient's contour dissolves across
-// neighbouring pixels instead of snapping as one line.
-//
-// **This is a deliberate divergence.** The reference's framebuffer was 8-bit and undithered, so
-// byte-exactness and this are mutually exclusive; that is why it is opt-in and why the default
-// keeps the byte lane intact.
+// Deviation, opt-in (`WOW_DITHER=1`): a dither against banding, which the reference's 8-bit
+// framebuffer lacks. The hash is Bevy's `screen_space_dither`, copied here because Bevy applies
+// it only in the tonemapping pass that `Tonemapping::None` skips.
 fn screen_space_dither(frag_coord: vec2<f32>) -> vec3<f32> {
     var dither = vec3<f32>(dot(vec2<f32>(171.0, 231.0), frag_coord)).xxx;
     dither = fract(dither.rgb / vec3<f32>(103.0, 71.0, 97.0));
     return (dither - vec3<f32>(0.5)) / 255.0;
 }
 
-// The combine's one exit: dither (when armed) in GAMMA space — the space the present-encode
-// rounds in — then the frame's single decode, or, under `GAMMA_OUT`, no decode at all.
+// The combine's exit: dither in gamma space, where the present-encode rounds, then the frame's
+// one decode, which the sRGB present-encode reverses byte-exactly; none under `GAMMA_OUT`.
 fn combine_out(outg: vec3<f32>, alpha: f32, frag_coord: vec2<f32>) -> vec4<f32> {
     let dithered = clamp(
         outg + screen_space_dither(frag_coord) * step(0.5, ffx.lane.w),
@@ -133,36 +81,23 @@ fn combine_out(outg: vec3<f32>, alpha: f32, frag_coord: vec2<f32>) -> vec4<f32>
         vec3<f32>(1.0),
     );
 #ifdef GAMMA_OUT
-    // The gamma-lane exit (decision 2234): this combine is the UI camera's own ground pass, so it
-    // stores the byte it computed the way that lane's quads store theirs (`ui_quad.wgsl`: colour
-    // premultiplied by its own alpha, alpha as coverage) and leaves the frame's decode to the
-    // lane's end. It is exactly the value the backdrop quad used to re-encode from the float
-    // image, minus the image.
+    // The UI camera's ground pass stores premultiplied bytes like `ui_quad.wgsl`; the lane decodes.
     return vec4<f32>(dithered * alpha, alpha);
 #else
     return vec4<f32>(srgb_to_linear(dithered), alpha);
 #endif
 }
 
-// The combine both entries run — the dry one at the fragment's own UV, the underwater one at the
-// warped UV. `frag_coord` stays UNwarped: it seeds the deband dither, which is a property of the
-// destination pixel, not of where the scene was read from.
+// Both combines, at the plain or the warped UV; `frag_coord` stays unwarped for the dither.
 fn combine_body(uv: vec2<f32>, frag_coord: vec2<f32>) -> vec4<f32> {
-    // GAMMA LANE (0161): the whole frame is already gamma bytes — the blur ran on gamma (like
-    // the reference's byte RTs) and the combine is raw byte math. The single srgb_to_linear here
-    // is THE frame's one decode: the sRGB present-encode then restores every byte exactly.
     let scene = textureSample(in_tex, in_samp, uv);
-    // Clamped to [0, 1] like the downsample's taps: the byte framebuffer this term stands for
-    // could never exceed 255, and an unclamped super-white here keeps the whole additive stack
-    // hard-white after the min() below — the screen term must saturate BEFORE the glow add.
+    // Clamped like the downsample taps: the screen term must saturate before the glow add.
     let sg = clamp(scene.rgb, vec3<f32>(0.0), vec3<f32>(1.0));
     let bg = max(textureSample(blur_tex, in_samp, uv).rgb, vec3<f32>(0.0));
-    // The scene alpha rides through untouched: the window surface ignores it and the opaque-clear
-    // booths hold 1 everywhere — only the transparent-clear create booth reads it, to composite
-    // its baked model straight over the UI page.
+    // Scene alpha passes through; only the transparent-clear create booth reads it.
     if ffx.lane.y > 0.0 {
-        // The FFXDeath pack has no z lane (its COLOR rgb is the constant tint) — the ghost
-        // combine reads the un-hazed screen.
+        // FFXDeath replaces the glow while a ghost, unhazed (one pass slot, `[0xce8bb4]`). The
+        // 0.144 blue weight is as shipped; the tint is packed at `0x6cb930`.
         let glowed = sg + ffx.lane.x * bg * bg;
         let luma = clamp(dot(glowed, vec3<f32>(0.299, 0.587, 0.144)), 0.0, 1.0);
         let p = clamp(4.0 * luma * (1.0 - luma), 0.0, 1.0);
@@ -170,11 +105,8 @@ fn combine_body(uv: vec2<f32>, frag_coord: vec2<f32>) -> vec4<f32> {
         let outg = min(vec3<f32>(luma) + ghost_tint * p, vec3<f32>(1.0));
         return combine_out(outg, scene.a, frag_coord);
     }
-    // The z lane — the drunk/underwater haze: cross-fade the screen toward the ¼-res blur
-    // BEFORE the glow add (`out = lerp(screen, blur, z) + w·blur²`, the shipped FFXGlow.bls;
-    // wow-re drunk-blur-z.md). z = max(drunkFraction, 84/255 while the eye is submerged) — 0 in
-    // the ordinary sober pass, 1 = fully blurred at 100 inebriation. The blur term clamps like
-    // the screen term: it stands for the same byte RT.
+    // The haze fades toward the blur before the glow add; z is the larger of the drunk fraction
+    // and 84/255 while submerged.
     let hazed = mix(sg, min(bg, vec3<f32>(1.0)), ffx.lane.z);
     let outg = min(hazed + ffx.lane.x * bg * bg, vec3<f32>(1.0));
     return combine_out(outg, scene.a, frag_coord);
@@ -185,57 +117,23 @@ fn fs_combine(in: FullscreenVertexOutput) -> @location(0) vec4<f32> {
     return combine_body(in.uv, in.position.xy);
 }
 
-// **FFXGlowWave — the underwater screen warp.** (wow-re `ffxeffects/scratch/glow-wave-underwater.md`,
-// §5 cross-checked; benilla decision 1824.)
-//
-// While the camera eye is in ANY liquid the reference does not run the combine above at all:
-// `CFFXGlow::Render 0x6cc630` walks a *second* pass list, whose third pass is **FFXGlowWave**
-// (ctor `0x6cb1f0`, vtable `0x8114b4`, render `0x6cb310`) in place of FFXGlow. wow-re's note had
-// long carried that swap as an undecided "GlowWave, *or* a duplicate Glow"; the arms are mutually
-// exclusive (`ret` at `0x6cc403`, `push ebx` at `0x6cc404`) and the plain-Glow arm is unreachable
-// on both backends, so underwater is ALWAYS the wave.
-//
-// The two passes are instruction-identical except that GlowWave binds a third texture — a 128×128
-// two-channel bump map holding `du = sin(2πx/128)`, `dv = sin(2πy/128)` — and **displaces both the
-// screen and the blur texcoords by it**. Everything downstream (the haze cross-fade, the blur²
-// add, the gamma lane) is unchanged, which is why both entries share [`combine_body`]: the warp is
-// a change of *where* the combine reads, not of what it computes.
-//
-// The wave texcoord is an affine map of the screen UV. The reference builds it CPU-side per vertex
-// (`0x7bca80`) and hands the GPU three interpolated texcoord streams; an affine function of an
-// interpolated UV is the interpolation of that affine function, so evaluating it per fragment here
-// is the same map, not an approximation of it:
-//
-//     uv' = uv · R(10°) · S(W/128, 0.88·H/128) · T(p1, p2)
-//
-// with the two phases running INDEPENDENTLY off one millisecond clock — `(t mod 3174)/3174` and
-// `(t mod 2805)/2805`, i.e. 3.174 s and 2.805 s, rejoining only every ~49 minutes. The scale
-// constants multiply the destination's pixel dimensions (a `rewave.md` gloss had them multiplying
-// the phases; corrected at the bytes), so the wavelength is 128 px across and 145.45 px down
-// REGARDLESS of resolution, and the pattern is screen-fixed rather than world-locked.
-//
-// Amplitude is **3.0 full-res pixels** on both samples — the reference reaches that number twice
-// over, `(3.0, 0, 0, 3.0)` texels of the full RT and `0.75` texels of the ¼ RT being the same
-// distance, which is the cross-check that the blur sample warps by the same amount as the screen.
+// FFXGlowWave, the warp the reference runs instead of FFXGlow while the eye is in any liquid
+// (`0x6cc630`, `0x6cb310`): the same combine, both texcoords displaced by a 128×128 sine LUT. The
+// reference's per-vertex wave texcoord (`0x7bca80`) is affine in the screen UV, so per fragment
+// is exact: uv' = uv · R(10°) · S(W/128, 0.88·H/128) · T(p1, p2), fixed to screen pixels.
 const WAVE_ROT_RAD: f32 = 0.174532925; // 10°, the reference's rotation row
-const WAVE_LUT_EDGE: f32 = 128.0; // the LUT is 128×128 texels ([0xce89a0]'s 7-field descriptor)
-const WAVE_V_SCALE: f32 = 0.88; // [0xce89c0] — the v axis alone carries it; u's twin is 1.0
+const WAVE_LUT_EDGE: f32 = 128.0; // the LUT is 128×128 texels ([0xce89a0])
+const WAVE_V_SCALE: f32 = 0.88; // [0xce89c0]: the v axis only; u's scale is 1.0
 const WAVE_AMPLITUDE_PX: f32 = 3.0; // full-res pixels, both samples
 
-// The screen-UV offset the warp applies, in UV units. `screen` is the full-res scene in pixels.
+// The warp's screen-UV offset in UV units; `screen` is the full-res scene size in pixels.
 fn wave_offset(uv: vec2<f32>, screen: vec2<f32>) -> vec2<f32> {
     let c = cos(WAVE_ROT_RAD);
     let s = sin(WAVE_ROT_RAD);
     let scale = vec2<f32>(screen.x, WAVE_V_SCALE * screen.y) / WAVE_LUT_EDGE;
     let tex = vec2<f32>(c * uv.x - s * uv.y, s * uv.x + c * uv.y) * scale + ffx.wave.xy;
-    // SAMPLED, not evaluated: 128 texels of `sin` under LINEAR/REPEAT *is* the reference's sine —
-    // a piecewise-linear one, and its own. REPEAT is load-bearing and was the round's costliest
-    // near-miss: read as CLAMP, the effect dies over 90% of the screen (the scale runs the
-    // texcoord to 10 cycles across, so all but the first would pin to the edge texel).
-    //
-    // The 8-bit pack is biased back exactly as the shipped ps_2_0 permutation does — that blob
-    // carries `def c2 = (−0.5, 1.0, …)` and two extra instructions spelling `(x − 0.5)·2`, because
-    // the caps tier the live client selects hands it an UNSIGNED texture.
+    // Sampled, not evaluated: the reference's sine is a filtered LUT. The sampler must repeat,
+    // as the texcoord spans about 10 cycles; the unbias matches the shipped ps_2_0 shader.
     let d = (textureSample(wave_tex, wave_samp, tex).rg - vec2<f32>(0.5)) * 2.0;
     return d * WAVE_AMPLITUDE_PX / screen;
 }
diff --git a/crates/benilla-world/src/shaders/sky.wgsl b/crates/benilla-world/src/shaders/sky.wgsl
index 2fabcc7d..e25ae0fa 100644
--- a/crates/benilla-world/src/shaders/sky.wgsl
+++ b/crates/benilla-world/src/shaders/sky.wgsl
@@ -1,17 +1,6 @@
-// Sky-dome gradient — unlit. Paired with `sky.rs` (SkyExt). The five Light.dbc SkyColor stops
-// (zenith→horizon) + the fog colour (row 7) are interpolated PER-FRAGMENT by the view-direction
-// elevation. RE-VERIFIED mapping (WoW.exe FUN_006d0d10/FUN_006d0f50 + apitrace WoW.5 dome vertices):
-// one stop per ring at GEOMETRIC elevations above the horizon —
-//   SkyColor0 @ 90° (zenith) … SkyColor1 @ 16.8° … SkyColor2 @ 9.8° … SkyColor3 @ 3.7° …
-//   SkyColor4 @ 1.8° … and the horizon (0°) and below = the FOG colour (row 7).
-// So SkyColor0 dominates the whole upper sky; the gradient is crushed into the bottom ~17° and
-// converges into the distance fog at the horizon. Linear interp in elevation ≈ WoW's ring Gouraud.
-// SKY-PASS DEPTH (see `sky_order.rs`, "The depth law"): the dome's radius does not decide occlusion —
-// the reference draws the sky FIRST and the opaque world paints over it. The far depth makes the
-// dome a true backdrop: it fills only pixels no world geometry claimed, so a WDL hill drawn beyond
-// the dome's shell can never be over-painted by the gradient. That depth is pinned in the VERTEX
-// stage (`sky_vertex.wgsl`, shared by every sky shader) — this fragment writes colour only, so the
-// rasterizer's early-Z rejects the covered fraction of the screen before the gradient runs (2016).
+// The sky-dome gradient (`SkyExt`): the five Light.dbc SkyColor stops at the reference's ring
+// elevations, then the fog colour at and below the horizon (`0x6d0d10`, `0x6d0f50`), interpolated
+// per fragment by elevation. Depth is the far pin in `sky_vertex.wgsl`; this writes colour only.
 #import bevy_pbr::{
     forward_io::VertexOutput,
     mesh_view_bindings::view,
@@ -23,17 +12,13 @@ struct SkyColors {
     sky2: vec4<f32>, // 9.8°
     sky3: vec4<f32>, // 3.7°
     sky4: vec4<f32>, // 1.8°
-    fog: vec4<f32>,  // horizon (0°) and below — LightIntBand row 7
+    fog: vec4<f32>,  // horizon (0°) and below: LightIntBand row 7
     warp: vec4<f32>, // x = dawn/dusk warp strength S (0 = off), y = sun azimuth (rad), zw reserved
 };
 @group(#{MATERIAL_BIND_GROUP}) @binding(100) var<uniform> sky: SkyColors;
 
-// Sun-relative azimuth phase → glow factor `g` (`FUN_006d0f50` table `0xce9af8`, VERIFIED byte-exact off
-// its writer `FUN_006ce210`). 6 wrap-around keyframes, piecewise-linear like the engine's table sampler,
-// symmetric about phase 0.625. **Semantics (capture-reconciled — see the warp note below):** `g = +1.0`
-// (phase 0.125) is the IDENTITY case `(1−g)=0` → ring left untouched, and that phase lands on the SUN
-// bearing → the sun side is the bright, unwarped DBC stop. `g < 0` (trough −0.7 at phase 0.625) is the
-// ANTI-sun side → it pulls the ring toward the dark apex. `phase` is fract()'d into [0,1).
+// Glow `g` for a sun-relative azimuth phase, sampled linearly like `0x6d0f50` from the reference's
+// six-keyframe wrap-around table at `0xce9af8` (written by `0x6ce210`); 0.125 is the sun bearing.
 fn azimuth_glow(phase: f32) -> f32 {
     let p = fract(phase);
     if (p < 0.125) { return mix(0.0, 1.0, (p + 0.125) / 0.25); } // wrap 0.875(g0)→1.125(g1)
@@ -45,12 +30,8 @@ fn azimuth_glow(phase: f32) -> f32 {
     else { return mix(0.0, 1.0, (p - 0.875) / 0.25); } // wrap 0.875(g0)→1.125(g1)
 }
 
-// One mid-ring's warped colour for a single glow factor `g` (`FUN_006d0f50`, VERIFIED + dusk-capture
-// reconciled). `g ≥ 0`: desaturate toward SkyColor1 by `(1−g)·S²` (so g=+1 on the sun bearing = identity =
-// the bright raw stop). `g < 0` (anti-sun): a prepass toward SkyColor1 by `S`, then toward the apex
-// SkyColor0 by `0.7·(−g)·S²` — the darkest, desaturated away side. (`S²` = the prepass-S × per-segment-S
-// nesting; `0.7` is the binary const `0x7ffd7c`. All byte-verified; reproduces the WoW.10 dusk dome to
-// ~2/channel.)
+// One mid-ring's warped colour for glow `g` (`0x6d0f50`): `S^2` is the prepass S nested in the
+// per-segment S, and 0.7 is the constant at `0x7ffd7c`.
 fn warp_one(base: vec3<f32>, g: f32, s: f32) -> vec3<f32> {
     let s2 = s * s;
     if (g >= 0.0) {
@@ -61,27 +42,12 @@ fn warp_one(base: vec3<f32>, g: f32, s: f32) -> vec3<f32> {
 
 @fragment
 fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
-    // Direction from the camera to this dome fragment; elevation above the world horizon.
     let dir = normalize(in.world_position.xyz - view.world_position.xyz);
     let elev = degrees(asin(clamp(dir.y, -1.0, 1.0))); // −90..90, 0 = horizon
 
-    // Dawn/dusk azimuthal warp (FUN_006d0f50) — only when S>0 (sunrise ~06:30 / sunset ~21:30 in
-    // highlightSky=1 zones; the S-curve decays to 0 by ~midnight). RE-VERIFIED + reconciled against the
-    // WoW.10 dusk capture. Two corrections over the old per-fragment version:
-    //  (1) Warp ONLY the 4 mid rings (SkyColor1..4); the apex (SkyColor0) and the fog rim are UNWARPED.
-    //      The engine's warp loop touches only ring offsets 4/8/12/16, and the capture shows the apex+rim
-    //      uniform across azimuth. So we warp the mid-ring COLOURS here, then run the elevation gradient
-    //      with the warped mid-rings + the *unwarped* apex/fog — the upper sky (>16.8°) interpolates the
-    //      warped ring1 up to the unwarped apex, GL-Gouraud-faithful. (The old `ring_weight` smoothstep
-    //      warped the whole upper sky → at night it dragged the entire dome toward the black apex.)
-    //  (2) The lobe bearing: `+0.125` puts the SUN bearing at glow phase 0.125 (g=+1 → identity → the
-    //      bright raw stop) and the anti-sun at 0.625 (g=−0.7 → darkest). The old `+0.625` had it 180°
-    //      inverted — darkening the sun side and leaving the anti-sun bright. The warp does NOT brighten:
-    //      the sunset glow IS the unwarped sun-side stop; the warp only darkens/desaturates the rest.
-    // Per-vertex Gouraud: the engine bakes the warp at 24 azimuth segments and interpolates between, which
-    // smears the genuine g=0 discontinuity (away `(1−g)·S²` vs warm prepass `S`) across one 15° segment
-    // rather than the hard fragment edge a smooth eval would give. We emulate that — evaluate the warp at
-    // the two bracketing segment phases and lerp.
+    // Dawn/dusk warp (`0x6d0f50`): only the four mid rings, never the apex or the fog rim, and
+    // never brighter. The reference bakes it per vertex at 24 azimuth segments and interpolates,
+    // hence the lerp of two segments; `+ 0.125` puts the sun bearing at glow phase 0.125.
     var s1 = sky.sky1.rgb;
     var s2c = sky.sky2.rgb;
     var s3 = sky.sky3.rgb;
@@ -100,7 +66,7 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
         s4 = mix(warp_one(sky.sky4.rgb, g0, warp_s), warp_one(sky.sky4.rgb, g1, warp_s), f);
     }
 
-    // Elevation gradient: warped mid-rings + UNWARPED apex (SkyColor0) and fog rim.
+    // Elevation gradient, linear between rings like the reference's Gouraud-shaded dome.
     var col: vec3<f32>;
     if (elev <= 0.0) {
         col = sky.fog.rgb; // horizon and below = fog colour (row 7), unwarped
@@ -113,11 +79,10 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
     } else if (elev < 16.8) {
         col = mix(s2c, s1, (elev - 9.8) / (16.8 - 9.8));
     } else {
-        col = mix(s1, sky.sky0.rgb, (elev - 16.8) / (90.0 - 16.8)); // warped ring1 → UNWARPED apex
+        col = mix(s1, sky.sky0.rgb, (elev - 16.8) / (90.0 - 16.8)); // warped ring1 to the raw apex
     }
 
-    // Raw gamma out (GAMMA LANE, 0161): the reference draws the sky with GL_FRAMEBUFFER_SRGB OFF
-    // (CSky::Render @0x6d4940) — raw DBC bytes — which is now the whole pipeline's convention.
+    // Raw gamma out: the reference draws the sky as raw DBC bytes, sRGB off (`0x6d4940`).
     let rgb = col;
     return vec4<f32>(rgb, 1.0);
 }
diff --git a/crates/benilla-world/src/shaders/sky_vertex.wgsl b/crates/benilla-world/src/shaders/sky_vertex.wgsl
index 4e952d54..92951855 100644
--- a/crates/benilla-world/src/shaders/sky_vertex.wgsl
+++ b/crates/benilla-world/src/shaders/sky_vertex.wgsl
@@ -1,24 +1,10 @@
-// The sky pass's shared VERTEX stage — bevy 0.18.1's `mesh.wgsl` vertex verbatim (VERTEX_*
-// attributes; morph targets and skinning omitted — no sky mesh authors them) plus ONE line: the
-// clip-space z is pinned to the far plane. Every sky element — the gradient dome (`sky.wgsl`),
-// the cloud dome (`cloud.wgsl`), the star patches (`star.wgsl`), the celestial discs and glares
-// (`celestial.wgsl`) — draws through this stage; their fragments write colour only.
+// The vertex stage of every sky draw: bevy 0.18.1's `mesh.wgsl` vertex verbatim, minus the morph
+// targets and skinning no sky mesh has, plus one line pinning clip z to the far plane. A
+// `MaterialExtension` replaces the whole stage, so this copy must track bevy's on upgrades.
 //
-// THE DEPTH LAW, moved up a stage (`sky_order.rs`, "The depth law"; decision 2016). The reference
-// draws its whole sky first, in a squashed back depth slice, and the opaque world paints over it;
-// we draw the sky after the world, so the depth TEST does that job, and it only does it if the
-// sky's depth is behind everything. Until 2016 each sky fragment shader wrote
-// `@builtin(frag_depth) = 0.0` (reverse-Z "infinitely far"). That is the same number this stage
-// produces — clip z = 0 interpolates to NDC z = 0 for every fragment, exactly, whatever w is — but
-// a fragment-stage depth write costs the whole pipeline its early-Z: the hardware cannot reject a
-// fragment before the shader that decides its depth has run, so every sky fragment under a hill,
-// a wall or a leaf was shaded in full and then thrown away. A dome is a full-screen draw and its
-// gradient is not cheap; on an immediate-mode GPU (the Steam Deck's RDNA2, every Windows part)
-// that was the whole covered fraction of the screen shaded for nothing, twice a frame at night.
-// With the depth known at the vertex, the rasterizer's early test rejects those fragments
-// before the shader runs. Same pixels, less work — the change is invisible by construction.
-//
-// A `MaterialExtension` swaps the whole stage, so the mirror below must track bevy's on upgrades.
+// The reference draws its sky first in a back depth slice and the world paints over it; here the
+// sky draws after the world, so the depth test does that job. The pin is per vertex because a
+// fragment depth write would disable early-Z.
 
 #import bevy_pbr::{
     mesh_functions,
@@ -26,9 +12,8 @@
     view_transformations::position_world_to_clip,
 }
 
-/// Reverse-Z "infinitely far" — clip-space z = 0 ⇒ NDC depth 0.0 for every fragment, whatever w.
-/// Under bevy's `GreaterEqual` test a sky fragment then passes only where the depth buffer still
-/// holds its clear value (0.0): exactly the pixels no world geometry claimed.
+/// Reverse-Z "infinitely far": clip z = 0 gives NDC depth exactly 0.0 whatever w, so under bevy's
+/// `GreaterEqual` test a sky fragment passes only where the depth buffer still holds its clear 0.0.
 const SKY_FAR_CLIP_Z: f32 = 0.0;
 
 @vertex
@@ -55,8 +40,7 @@ fn vertex(vertex_no_morph: Vertex) -> VertexOutput {
 #ifdef VERTEX_POSITIONS
     out.world_position = mesh_functions::mesh_position_local_to_world(world_from_local, vec4<f32>(vertex.position, 1.0));
     out.position = position_world_to_clip(out.world_position.xyz);
-    // The one line that is ours (the header): the sky's depth is the far plane, decided here so
-    // the fragment stage writes none and keeps its early-Z.
+    // The one line not from bevy: the far-plane pin.
     out.position.z = SKY_FAR_CLIP_Z;
 #endif
 
diff --git a/crates/benilla-world/src/shaders/star.wgsl b/crates/benilla-world/src/shaders/star.wgsl
index 66f746e7..86c727d5 100644
--- a/crates/benilla-world/src/shaders/star.wgsl
+++ b/crates/benilla-world/src/shaders/star.wgsl
@@ -1,19 +1,6 @@
-// Night-sky stars (the `Stars.m2` patches) — premultiplied white dots over the sky dome.
-//
-// GAMMA-SPACE BLEND — the gamma composite lane (decision 0161): the reference's framebuffer holds
-// gamma bytes and all its hardware blending happens in gamma space, so the stars' faithful blend is
-// a GAMMA-space alpha blend of white-on-transparent dots (`Stars.blp`, ~98% transparent, mostly low
-// alpha). Under that lane our framebuffer likewise holds gamma bytes and ALL blending is gamma, so the
-// faithful output is simply premultiplied white at the dot's alpha: `(a, a, a, a)` with
-// `a` = texture alpha × the star-curve global alpha (`StandardMaterial::base_color` alpha, set
-// per-frame). Over the near-black night sky that lands on screen at gamma value `a` — the
-// reference's byte — with zero conversion math.
+// Night-sky stars (`Stars.m2`): white `Stars.blp` dots blended as premultiplied white in gamma
+// space, as the reference blends them. Depth is the far pin in `sky_vertex.wgsl`.
 
-// SKY-PASS DEPTH (see `sky_order.rs`, "The depth law"): the star dome's own geometry depth is not
-// what decides occlusion — the reference draws its whole sky FIRST, in a squashed back depth slice,
-// and the opaque world paints over it. The far depth reproduces that from the transparent pass:
-// stars survive only on pixels no world geometry claimed. It is pinned in the VERTEX stage
-// (`sky_vertex.wgsl`, shared by every sky shader); this fragment writes colour only (2016).
 #import bevy_pbr::{
     pbr_fragment::pbr_input_from_standard_material,
     forward_io::VertexOutput,
@@ -22,6 +9,6 @@
 @fragment
 fn fragment(in: VertexOutput, @builtin(front_facing) is_front: bool) -> @location(0) vec4<f32> {
     let pbr_input = pbr_input_from_standard_material(in, is_front);
-    let a = pbr_input.material.base_color.a; // dot texture alpha × the star-curve global alpha
-    return vec4<f32>(vec3<f32>(a), a); // premultiplied white — raw (GAMMA LANE, 0161)
+    let a = pbr_input.material.base_color.a; // texel alpha × the per-frame `base_color` alpha
+    return vec4<f32>(vec3<f32>(a), a); // premultiplied white, raw gamma
 }
diff --git a/crates/benilla-world/src/shaders/static_gx.wgsl b/crates/benilla-world/src/shaders/static_gx.wgsl
index 905829f0..ebe78d5a 100644
--- a/crates/benilla-world/src/shaders/static_gx.wgsl
+++ b/crates/benilla-world/src/shaders/static_gx.wgsl
@@ -1,31 +1,8 @@
-// The B1 retained static pass (decision 1429; `static_gx/mod.rs`): the never-fade order-free
-// static-world law of `wow_model.wgsl`, re-expressed over retained buffers — per-vertex
-// texture-array layer + flag bits (+ a per-item record) where the entity path had one
-// material per batch. Slice 1 = exterior ADT doodads; slice 2 adds WMO group geometry.
-//
-// **The law here MIRRORS `benilla_assets/shaders/wow_model.wgsl` and must track it** (the
-// terrain.wgsl precedent: naga_oil cannot import functions that reference another module's
-// bindings, so the shared pieces are copied with keep-in-sync notes at both ends). Mirrored
-// pieces, in order: the `WowLight` per-frame PREFIX (the buffer is bigger — probe/palette
-// regions ride the tail; binding a prefix-shaped struct against the same buffer is exactly
-// what terrain.wgsl does), `wow_normalize`, `point_light_sum`, the exterior-doodad sun family
-// (the Model2.bls order-2 lobe, 0803 — `min(I,1)` cap included, with its recorded caveat),
-// the WMO surface lanes (slice 2: MOCV inside the clamp under GL_COLOR_MATERIAL, the
-// INT/TRANS/EXT batch-class lanes, the WINDOW midpoint light, SIDN × night on lit lanes,
-// ZERO point lights, the authored batch-order clip-z nudge, the interior fog triple), the
-// interior-PROP probe lane (B4, decision 1433: the per-item slot rides the record table and
-// the probe rows live in the TAIL of the same shared buffer — zero live point lights, the
-// group-MOLR lobes are folded into the probe at spawn), the exterior-prop Matte fixed-1.0
-// family (B4), and the step-5 fog. Deliberately ABSENT (this lane never carries them): the
-// clutter/rig/fade/env-map/highlight/mat-anim lanes and per-instance tint (identity for
-// statics).
-//
-// Population contract (enforced by the collector's divert — `static_gx::StaticGx::divert`):
-// never-fade order-free non-animated statics (interior props are never-fade by law),
-// Opaque/AlphaTest only, no env-map, no depth flags; cells additionally
-// `ShadeSel::Lit`/`Shaded` only (the WMO lane never reads the selector; the prop lane adds
-// `Matte`). Output alpha is pinned 1.0 — every draw here is opaque-intent by admission
-// (wow_model.wgsl's bit-3 armor, as a constant).
+// The retained static-world pass: `wow_model.wgsl`'s shading for statics that never fade or
+// animate (ADT doodads, WMO groups, interior M2 props), with per-vertex flag words and a per-item
+// record in place of materials. `StaticGx::divert` admits opaque and alpha-tested batches with no
+// env map and no depth flags. The light prefix, helpers and lighting lanes copy `wow_model.wgsl`'s
+// and must stay in sync: naga_oil cannot import functions that use another module's bindings.
 
 #import bevy_pbr::{
     mesh_view_bindings::{lights, view},
@@ -38,8 +15,7 @@
 // the shadow textures the retained pass reads).
 const SHADOW_SUN_FLOOR: f32 = 0.45;
 
-// The shared global light's per-frame PREFIX (lighting::global_light; the full layout lives in
-// wow_model.wgsl — keep field order in sync with BOTH).
+// Prefix of lighting::global_light's buffer; field order in sync with it and wow_model.wgsl.
 struct WowLight {
     light_ambient: vec4<f32>,
     light_diffuse: vec4<f32>,
@@ -64,10 +40,7 @@ struct WowLight {
     // yards. wow_model.wgsl owns the full note.
     point_count: vec4<f32>,
     points: array<vec4<f32>, 512>,
-    // The interior-prop SH probe table (B4 — lighting::prop_probes, 7 rows per slot, 8192
-    // slots; wow_model.wgsl owns the layout note). Sits immediately after the point table in
-    // the shared buffer, so extending the mirrored prefix by one region is all it takes; the
-    // rig/tint/mat-anim regions beyond it stay unmirrored (statics never read them).
+    // lighting::prop_probes: 8192 slots of 7 rows; the buffer's later regions are not mirrored.
     prop_probes: array<vec4<f32>, 57344>,
 }
 @group(2) @binding(0) var<storage, read> wow_light: WowLight;
@@ -98,37 +71,32 @@ struct GxCell {
     origin: vec4<f32>,
 }
 @group(1) @binding(0) var<uniform> cell: GxCell;
-// The per-ITEM record table, indexed by the vertex word's low bits:
-// x = texture-array layer, y = the WMO authored batch order (the clip-z nudge; 0 on cells —
-// an exact no-op), z = the MOMT SIDN colour packed r|g<<8|b<<16 (gamma bytes), w = flags:
-// bit 0 the exile kill bit (B2), bits 1..=13 the interior-prop probe slot (B4), bit 14 the
-// per-frame INTERIOR FOG lane (1787 — the client's per-group `[0xca7f00]`).
+// The per-item records, indexed by the vertex word's low 16 bits: x the texture-array layer, y
+// the WMO batch order (0 on cells), z the MOMT SIDN colour r|g<<8|b<<16 in gamma bytes, w flags:
+// bit 0 exile kill, bits 1..=13 the interior-prop probe slot, bit 14 interior fog (`[0xca7f00]`).
 @group(1) @binding(1) var<storage, read> recs: array<vec4<u32>>;
 @group(1) @binding(2) var tex_array: texture_2d_array<f32>;
-// Repeat and clamp variants of the BLP model-albedo sampler (linear tri-filtered, aniso 8 —
-// exact parity with the entity path's per-image samplers; render.rs owns the rationale).
+// Repeat and clamp model-albedo samplers: trilinear, aniso 8, the same as the entity path's.
 @group(1) @binding(3) var samp_repeat: sampler;
 @group(1) @binding(4) var samp_clamp: sampler;
 
-// Vertex word bits — keep in sync with static_gx/mod.rs WORD_*.
+// Vertex word bits; keep in sync with static_gx/mod.rs WORD_*.
 const WORD_WRAP_X: u32 = 65536u;    // 1 << 16
 const WORD_WRAP_Y: u32 = 131072u;   // 1 << 17
 const WORD_UNLIT: u32 = 262144u;    // 1 << 18
 const WORD_FOG_OFF: u32 = 524288u;  // 1 << 19
-const WORD_SHADE_LIT: u32 = 1048576u; // 1 << 20 — no producer since 2050 (entities never divert here); kept, retiring it is a word-layout round
+const WORD_SHADE_LIT: u32 = 1048576u; // 1 << 20: ShadeSel::Lit, which no static carries
 const WORD_TEXTURED: u32 = 2097152u;  // 1 << 21
-// The WMO lane (slice 2) — the entity path's per-material facts as bits:
-const WORD_WMO: u32 = 4194304u;        // 1 << 22 — model_flags.x (the WMO surface laws)
-const WORD_INTERIOR: u32 = 8388608u;   // 1 << 23 — model_flags.z (interior group)
-const WORD_CLASS_INT: u32 = 16777216u; // 1 << 24 — tint.w == 1 (INT batch)
-const WORD_CLASS_TRANS: u32 = 33554432u; // 1 << 25 — tint.w == 2 (TRANS batch)
-const WORD_WINDOW: u32 = 67108864u;    // 1 << 26 — sidn.w (WINDOW midpoint light)
-const WORD_HAS_VC: u32 = 134217728u;   // 1 << 27 — the batch AUTHORED vertex colours
-                                       //           (the entity shader's VERTEX_COLORS def)
-// The prop lane (B4). INTERIOR without WMO = an interior M2 prop — the entity shader's own
-// `interior_prop = flags.z && !flags.x` split: probe lighting, interior fog, zero live
-// point lights.
-const WORD_MATTE: u32 = 268435456u;    // 1 << 28 — EITHER doodad class (ADT MDDF or exterior MODD prop): intensity FIXED 1.0 (2050)
+// The WMO lane: the entity path's per-material facts as bits.
+const WORD_WMO: u32 = 4194304u;        // 1 << 22: model_flags.x, a WMO surface
+const WORD_INTERIOR: u32 = 8388608u;   // 1 << 23: model_flags.z, an interior group
+const WORD_CLASS_INT: u32 = 16777216u; // 1 << 24: tint.w == 1, an INT batch
+const WORD_CLASS_TRANS: u32 = 33554432u; // 1 << 25: tint.w == 2, a TRANS batch
+const WORD_WINDOW: u32 = 67108864u;    // 1 << 26: sidn.w, the WINDOW midpoint light
+const WORD_HAS_VC: u32 = 134217728u;   // 1 << 27: the batch authors vertex colours
+// INTERIOR without WMO is an interior M2 prop, the entity shader's `interior_prop =
+// flags.z && !flags.x`: probe lighting, interior fog, no point lights.
+const WORD_MATTE: u32 = 268435456u;    // 1 << 28: ShadeSel::Matte, fixed intensity 1.0
 
 // MONKEY (room gate): record column `w` bits 15..=26 — this item's ROOM KEY, packed as
 // `group + 1`, so **0 means the item names no room** and takes every fixture (a terrain-cell item,
@@ -1267,8 +1235,7 @@ struct GxVertex {
     @location(2) uv: vec2<f32>,
     @location(3) word: u32,
     @location(4) anchor: vec3<f32>,
-    // MOCV / the baked constant tint (white where the batch authors none — WORD_HAS_VC says
-    // which; the entity path's ATTRIBUTE_COLOR, interpolated exactly like it).
+    // MOCV or the baked constant tint; white where the batch authors none (WORD_HAS_VC).
     @location(5) color: vec4<f32>,
 }
 
@@ -1295,10 +1262,8 @@ struct GxVsOut {
 @vertex
 fn vertex(v: GxVertex) -> GxVsOut {
     var out: GxVsOut;
-    // The exile kill bit (B2, 1431 — record column w, bit 0): a punched-out item's vertices
-    // all collapse to one constant point, so every triangle is zero-area and the rasterizer
-    // drops it — no fragments, no state change, one u32 write flipped it. Triangles never
-    // span items (the bake is item-contiguous), so a partial collapse cannot exist.
+    // Exile kill bit (record w bit 0): every vertex of the item collapses to one point, so its
+    // triangles are zero-area and rasterize nothing; triangles never span items.
     if ((recs[v.word & 0xffffu].w & 1u) != 0u) {
         out.position = vec4<f32>(0.0, 0.0, 2.0, 1.0);
         out.world_position = vec4<f32>(0.0);
@@ -1310,8 +1275,7 @@ fn vertex(v: GxVertex) -> GxVsOut {
         out.ext_sel = EXT_SEL_NONE;
         return out;
     }
-    // Camera-relative clip (0974/wow_model.wgsl): both addends are small — the recentred
-    // vertex and (cell origin − camera).
+    // Camera-relative for f32 precision: the recentred vertex plus (cell origin - camera).
     let p_cam = v.position + (cell.origin.xyz - view.world_position);
     let world = v.position + cell.origin.xyz;
     out.world_position = vec4<f32>(world, 1.0);
@@ -1321,10 +1285,8 @@ fn vertex(v: GxVertex) -> GxVsOut {
         view.view_from_world[2].xyz,
     );
     out.position = view.clip_from_view * vec4<f32>(view_rot * p_cam, 1.0);
-    // WMO authored batch order (the per-item record's y; wow_model.wgsl's `m.sun_scale.y`
-    // nudge verbatim): a later coplanar MOBA batch must WIN the reverse-Z GreaterEqual test
-    // in any draw order — load-bearing here, where the (bucket, texture, group) sort erases
-    // authored order by design. 0 on every cell item ⇒ ×1.0, an exact no-op.
+    // Authored MOBA batch order (record y, 0 on cells): a later coplanar batch wins reverse-Z
+    // GreaterEqual in any draw order, because the draw sort does not keep authored order.
     out.position.z *= 1.0 + f32(recs[v.word & 0xffffu].y) * 1.1920929e-7;
     out.world_normal = v.normal;
     out.uv = v.uv;
@@ -1368,16 +1330,13 @@ fn vertex(v: GxVertex) -> GxVsOut {
 
 @fragment
 fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
-    // The hard farclip wall — per-pixel planar eye-Z, same plane as the entity path.
+    // The hard farclip wall: per-pixel planar eye-Z, the same plane as the entity path.
     let eye_z = -(view.view_from_world * vec4<f32>(in.world_position.xyz, 1.0)).z;
     if (wow_light.fog_params.w > 0.0 && eye_z > wow_light.fog_params.w) {
         discard;
     }
-    // Sample: the item's array layer through the sampler matching its wrap flags. Both-repeat
-    // and both-clamp ride real samplers (exact parity); the rare MIXED batch keeps the repeat
-    // sampler plus the half-texel inset clamp on its clamped axis (0763's silhouette clamp,
-    // per axis). Both samples are taken unconditionally — `textureSample` needs uniform
-    // control flow for its derivatives — and the select is per fragment.
+    // The sampler follows the wrap flags; a mixed batch clamps its clamped axis a half texel in.
+    // Every sample runs unconditionally: implicit derivatives need uniform control flow.
     var base = vec4<f32>(1.0);
     let wrap_x = (in.word & WORD_WRAP_X) != 0u;
     let wrap_y = (in.word & WORD_WRAP_Y) != 0u;
@@ -1392,11 +1351,7 @@ fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
         if (!wrap_y) {
             uv_mixed.y = clamp(uv_mixed.y, inset.y, 1.0 - inset.y);
         }
-        // `view.mip_bias` (decision 1639) — the render-scale LOD compensation, 0.0 at native.
-        // Carried here as well as in wow_model.wgsl because this lane draws the same statics
-        // through its own sampler rather than through `pbr_input_from_standard_material`, which
-        // applies the bias for free; a lane that skipped it would blur out of step with the
-        // entity path drawing the identical art.
+        // The render-scale LOD bias: bevy's material path applies it for free, this lane by hand.
         let c_repeat = textureSampleBias(tex_array, samp_repeat, in.uv, layer, view.mip_bias);
         let c_clamp = textureSampleBias(tex_array, samp_clamp, in.uv, layer, view.mip_bias);
         let c_mixed = textureSampleBias(tex_array, samp_repeat, uv_mixed, layer, view.mip_bias);
@@ -1413,13 +1368,8 @@ fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
         discard;
     }
 #endif
-    // Lighting — the exterior-doodad lane verbatim (wow_model.wgsl steps 7+, 0803's lobe):
-    // both faces light from the SAME submitted normal (the FFP never enables
-    // GL_LIGHT_MODEL_TWO_SIDE). The entity shader's `select(-n, n, is_front)` exists to UNDO
-    // bevy_pbr's double-sided back-face negation; this pipeline never negated, so the raw
-    // baked normal IS the submitted normal and any select here would INTRODUCE the flip the
-    // entity path removes (the first capture A/B lit every back-facing canopy card from the
-    // wrong side — the felwood heatmap's bright clusters).
+    // Both faces light from the submitted normal (no GL_LIGHT_MODEL_TWO_SIDE in the reference);
+    // this pipeline never negates back faces, so it has no front-face select like wow_model.wgsl.
     let n_lit = wow_normalize(in.world_normal);
     // MONKEY (outdoor torch shadows): the EXTERIOR point term, cast-shadowed at night.
     //
@@ -1508,27 +1458,20 @@ fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
     // doodad lobe and the interior-prop probe lane (wow_model.wgsl computes them once too).
     let quad = vec4<f32>(n_lit.x * n_lit.y, n_lit.y * n_lit.z, n_lit.z * n_lit.z, n_lit.x * n_lit.z);
     let x2y2 = n_lit.x * n_lit.x - n_lit.y * n_lit.y;
-    // ATTRIBUTE_COLOR, pre-folded into the sampled base exactly where bevy_pbr folds it
-    // (`base_color *= in.color` before the texture multiply — commutative, so tex×vc is the
-    // same bits). **A colour-less batch takes the CONSTANT 1.0, never the interpolated
-    // white**: the entity path's fold literally does not exist without its VERTEX_COLORS
-    // shader-def, and GPU interpolation of a constant attribute is NOT exact — a barycentric
-    // sum lands at 1.0±ε, and `base × 0.99999994` re-rounds ~half of all textured pixels one
-    // byte down. That was the ±1/255 film over 300k pixels of house-south with the WMO lane
-    // OFF — the attribution sweep's cells-only leg is what separated it from the WMO bake's
-    // own (f64-fixed) quantization film.
+    // A colour-less batch takes a constant 1.0, not interpolated white: interpolating a constant
+    // attribute gives 1.0±ε, and base × 0.99999994 rounds about half the pixels one byte down.
     let has_vc = (in.word & WORD_HAS_VC) != 0u;
     let vc = select(vec4<f32>(1.0), in.color, has_vc);
     let folded = select(base.rgb, base.rgb * vc.rgb, has_vc);
     var rgb: vec3<f32>;
     if ((in.word & WORD_WMO) != 0u) {
-        // ---- the WMO surface lanes (slice 2) — wow_model.wgsl's is_wmo branch verbatim ----
+        // ---- WMO surfaces: wow_model.wgsl's is_wmo branch ----
         let interior = (in.word & WORD_INTERIOR) != 0u;
         let class_int = (in.word & WORD_CLASS_INT) != 0u;
         let class_trans = (in.word & WORD_CLASS_TRANS) != 0u;
-        let trans_a = vc.a; // 1.0 where no MOCV authored — the entity path's default
-        // WINDOW (MOMT 0x20) — interior drawer only: GL_LIGHT0 swapped to the brighter
-        // Direct/Ambient midpoint pair, ambient +16/255 saturating (0x6d37e0).
+        let trans_a = vc.a; // 1.0 where no MOCV is authored
+        // WINDOW (MOMT 0x20), interior drawer only: GL_LIGHT0 becomes the Direct/Ambient
+        // midpoint pair, ambient +16/255 saturating (0x6d37e0).
         let window_mid = 0.5 * (wow_light.light_ambient.rgb + wow_light.light_diffuse.rgb);
         // The window's directional half rides the sun, so it takes the shadow term (×1.0 exact
         // when the caster is off — no identity guard needed on a pure multiply).
@@ -1653,9 +1596,7 @@ fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
             vec3<f32>(0.0),
             vec3<f32>(1.0),
         );
-        // The entity algebra EXACTLY: bevy pre-folds vc into base and the shader divides it
-        // back out — (tex×vc)/max(vc, 1/255) is not tex in floats, so simplifying would
-        // break the pixel-identity bar.
+        // The entity path's algebra: (tex×vc)/max(vc, 1/255) is not tex in floats; keep it.
         let tex_rgb = folded / max(vc.rgb, vec3<f32>(1.0 / 255.0));
         rgb = tex_rgb * primary;
         rgb = shell_candle_add(rgb, base.rgb, ext_room_raw, ext_room_far);
@@ -1919,14 +1860,9 @@ fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
             }
         }
     } else if ((in.word & WORD_INTERIOR) != 0u) {
-        // ---- the interior M2-PROP lane (B4, decision 1433) — wow_model.wgsl's
-        // interior-prop branch verbatim: the folded per-instance SH probe (MODD ambient +
-        // the fixed-axis diffuse lobe + the owning group's MOLR lobes, folded ONCE at
-        // spawn), evaluated over the fragment normal. The slot rides the record table
-        // (w bits 1..14) where the entity path rode MeshTag bits 6..19. The soft SH wrap
-        // is the reference's authored response — deliberately NOT a hard max(N·L,0).
-        // point_lit is zero (vertex stage); inst_tint identity, no highlight, SIDN zero on
-        // every M2 batch — the combine collapses to folded × clamp(probe eval).
+        // ---- interior M2 props: wow_model.wgsl's interior-prop branch ----
+        // The spawn-folded SH probe (MODD ambient, fixed-axis diffuse, the group's MOLR lobes)
+        // over the fragment normal; its soft wrap is the reference's, not a hard max(N·L, 0).
         let probe = 7u * ((recs[in.word & 0xffffu].w >> 1u) & 0x1fffu);
         let n1 = vec4<f32>(n_lit, 1.0);
         let lit_prop = clamp(
@@ -1971,13 +1907,10 @@ fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
             }
         }
     } else {
-        // ---- the exterior ADT-doodad lane (slice 1) + the exterior MODD-prop family (B4) --
-        // The intensity family: statics are `mat_shade` only (no per-instance ramp byte —
-        // that is an entity concern): lit ground ⇒ mix(2.5,0.5,0)=2.5, MCSH-shadowed ⇒ 0.5,
-        // and the Matte mid-band (an exterior WMO MODD prop) FIXED 1.0 — the 2.5 site is one
-        // a MODD prop never reaches (§8b); then the recorded `min(I,1)` cap (unfaithful,
-        // kept in exact sync — 0803 §3; today it makes Matte and Lit read identically, and
-        // the distinct bit exists so lifting the cap cannot silently split this lane).
+        // ---- exterior ADT doodads and exterior MODD props ----
+        // Model2.bls order-2 SH sun lobe at intensity 0.5 Shaded (MCSH), 1.0 Matte, 2.5 Lit.
+        // Deviation: the `min(I, 1)` cap, as in wow_model.wgsl, since lifting it takes sun-facing
+        // surfaces past 1.0; Matte keeps its own bit so it stays 1.0 if the cap goes.
         let shade_t = select(1.0, 0.0, (in.word & WORD_SHADE_LIT) != 0u);
         let intensity = min(
             select(mix(2.5, 0.5, shade_t), 1.0, (in.word & WORD_MATTE) != 0u),
@@ -2029,21 +1962,13 @@ fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
         let primary = clamp(lit + point_lit, vec3<f32>(0.0), vec3<f32>(1.0));
         rgb = folded * primary;
     }
-    // Unlit fullbright (M2 UNLIT 0x01 / WMO UNLIT on an exterior-group batch): the albedo —
-    // texture × the folded vertex colour — with lighting off; no emission terms reach it.
+    // Unlit (M2 UNLIT 0x01, WMO UNLIT on an exterior group): texture × vertex colour, no light.
     if ((in.word & WORD_UNLIT) != 0u) {
         rgb = folded;
     }
-    // Step-5 fog (planar eye-Z; policy: Scene, or Off via the render-flag bit — the
-    // Black/White/Grey families belong to blends this lane excludes by admission). Interior
-    // WMO surfaces fog with the INTERIOR triple — the room keeps its warm MFOG haze
-    // (round-6 Q-I: one flag gates walls, pools and props alike).
-    // The interior fog lane is the per-frame record bit, NOT the baked `WORD_INTERIOR`: the
-    // client pushes the interior triple per GROUP under `[0xca7f00]` (`0x6b5190` for surfaces,
-    // `0x6b62e0` for the group's doodads — wow-re round-6 Q-I), and the flood decides it each
-    // frame (decision 1787, `wow_model.wgsl` carries the same law on its tag bit 30). Keyed on
-    // the batch's static interior flag instead, every true-interior group of a building wore the
-    // building's MFOG the moment the camera stood anywhere in it — B335.
+    // Planar eye-Z fog; other fog modes belong to blends never admitted here. The interior triple
+    // keys on the per-frame record bit, not `WORD_INTERIOR`: the client sets it per group under
+    // `[0xca7f00]` (`0x6b5190` for surfaces, `0x6b62e0` for the group's doodads).
     var fog_color = wow_light.fog_color;
     var fog_span = wow_light.fog_params.xy;
     if ((recs[in.word & 0xffffu].w & 16384u) != 0u) {
@@ -2055,6 +1980,6 @@ fn fragment(in: GxVsOut) -> @location(0) vec4<f32> {
         let factor = clamp((fog_span.y - eye_z) / denom, 0.0, 1.0);
         rgb = mix(fog_color.xyz, rgb, factor);
     }
-    // Raw gamma out (0161's lane); alpha pinned 1.0 — opaque-intent by admission.
+    // Gamma-space output; alpha pinned 1.0, every draw here is opaque.
     return vec4<f32>(rgb, 1.0);
 }
diff --git a/crates/benilla-world/src/shaders/wow_effect.wgsl b/crates/benilla-world/src/shaders/wow_effect.wgsl
index 201dd5ea..f6654dd9 100644
--- a/crates/benilla-world/src/shaders/wow_effect.wgsl
+++ b/crates/benilla-world/src/shaders/wow_effect.wgsl
@@ -1,30 +1,19 @@
-// WoW effect-lane shader — the shared effect stream's own pipeline (decisions 0732 P1/P2,
-// 0733: particles, ribbons, the decal family, water foam, precipitation). The fragment IS
-// wow_particle.wgsl's combine, freed of the StandardMaterial shell: the whole product is
-// authored gamma bytes — texture (Rgba8Unorm, deliberately NOT decoded on sample, the house
-// invariant) × the raw authored track colour riding the vertex colour. Multiplying them in
-// gamma space IS the vanilla math; the output is raw gamma — the buffer holds bytes end-to-end
-// and the frame's one decode lives in the FFXGlow combine (GAMMA LANE, 0161).
+// The effect-lane pass (particles, ribbons, decals, water foam, precipitation): texture bytes,
+// never decoded on sample, times the authored track colour in gamma space, as the reference
+// multiplies them. The output stays gamma; the FFXGlow combine decodes the frame once.
 //
-// Blend variants (pipeline shader defs, one per EffectBlend — 0733 §4):
-// - BLEND_ADD:      the premultiplied-alpha fold in GAMMA space (rgb ×= α, α = 0 under the
-//   (One, 1−srcα) blend state = pure addition) — the reference adds `src_g·α` bytes;
-//   premultiplying after a linear conversion inflates every soft edge by α^(1/2.2)
-//   (decision 0160, the fat glow-disc family).
+// Blend variants, one shader def per EffectBlend:
+// - BLEND_ADD:      (rgb·α, 0) under (One, 1−srcα), the reference's `src·α` byte add.
 // - BLEND_ALPHA:    straight (rgb, α) under standard alpha blending.
-// - BLEND_OPAQUE:   (rgb, 1) with blending off — the alpha-ignoring shape the material path's
-//   AlphaMode::Opaque produced.
-// - BLEND_ALPHAKEY: BLEND_OPAQUE's output behind the fixed-function ALPHA TEST — `discard` below
-//   224/255. wgpu has no `glAlphaFunc`, so the reference's EGxRs id 0x08 lands here.
-// - BLEND_MULTIPLY: premultiplied (rgb·α, α) under (Dst, 1−srcα) — `dst·lerp(1, rgb, α)`, the
-//   blob shadow's modulate-with-fade (and ModelBlend::Mod at α = 1).
-// - BLEND_MOD2X:    (rgb, 1) under (Dst, Src) = `2·src·dst` — rain's state; reads no alpha.
+// - BLEND_OPAQUE:   (rgb, 1) with blending off.
+// - BLEND_ALPHAKEY: BLEND_OPAQUE behind the alpha test (EGxRs id 0x08), a discard below 224/255.
+// - BLEND_MULTIPLY: (rgb·α, α) under (Dst, 1−srcα) = `dst·lerp(1, rgb, α)`, the blob shadow's
+//   modulate-with-fade and ModelBlend::Mod at α = 1.
+// - BLEND_MOD2X:    (rgb, 1) under (Dst, Src) = `2·src·dst`, rain's state; reads no alpha.
 
 #import bevy_render::view::View
 
-// The shared global light/fog buffer (`lighting::global_light`) — the SAME layout every world
-// shader mirrors (see wow_model.wgsl's declaration, the canonical copy). This lane reads only
-// the fog rows; the rest is layout ballast.
+// Prefix of `lighting::global_light`'s buffer; keep in sync with wow_model.wgsl's copy.
 struct WowLight {
     light_ambient: vec4<f32>,
     light_diffuse: vec4<f32>,
@@ -50,20 +39,10 @@ struct WowLight {
 @group(1) @binding(0) var effect_texture: texture_2d<f32>;
 @group(1) @binding(1) var effect_sampler: sampler;
 @group(1) @binding(2) var<storage, read> wow_light: WowLight;
-// Per-draw params (a dynamic offset into the canonical trio): x = the fog COLOUR policy
-// (0 = off — the "unfogged" file flag 0x8; 1 = scene — the ordinary day-night fog; 2 = BLACK —
-// an Add-blend emitter fades under a veil instead of gaining grey, the same per-blend fog
-// table M2 batches take, `0x70baf0`). y = forced-fog mode with zw = its start/end (the rain
-// lanes — unused until precipitation joins the lane in slice P2, kept so the struct is P2's
-// already).
-//
-// `clip` is the draw's **render-target rectangle in target pixels** — `(min.x, min.y, max.x,
-// max.y)`, and `z <= x` means the whole target, which is every world draw. The UI model tiles
-// are the one customer (decision 2093): every visible `<Model>` pane renders into its own cell
-// of ONE shared atlas, so a cloud reaching past its cell would land in the cell beside it and
-// be composited onto a different widget. The reference clips this with the widget's own rect as
-// the VIEWPORT (`modelframe-render-law.md` §6); one shared camera cannot carry a viewport per
-// pane, so the rect rides the draw and the fragment discards outside it.
+// Per-draw params. `fog`: x the fog colour policy, `0x70baf0`'s per-blend table (0 off for file
+// flag 0x8, 1 scene, 2 black for Add, 3 white for Mod, 4 grey for Mod2x); y rain's forced fog, zw
+// its start and end. `clip`: the target rect in pixels (min.xy, max.xy), the whole target when
+// z <= x; the reference clips a UI model to its widget's viewport, and model panes share an atlas.
 struct EffectParams {
     fog: vec4<f32>,
     clip: vec4<f32>,
@@ -74,12 +53,8 @@ struct EffectParams {
 const RAIN_FOG_GREY: vec3<f32> = vec3<f32>(0.50196078, 0.50196078, 0.50196078);
 
 struct Vertex {
-    // CAMERA-RELATIVE (0733 §2): prepare rebased the stream against this view's own
-    // world_position, so the big-coordinate cancellation never reaches the matrix product —
-    // absolute-coordinate verts through `clip_from_world` shear thin geometry apart far from
-    // the origin (the precip module's empirically-learned law at ~9000 yd).
-    // EXCEPT under DECAL_WORLD_CLIP (decision 0781): the decal family's verts arrive ABSOLUTE
-    // (prepare skips their rebase) and take the mesh path's own matrix in the vertex stage.
+    // Camera-relative for f32 precision (absolute verts through `clip_from_world` shear thin
+    // geometry far from the origin), except decals under DECAL_WORLD_CLIP, which arrive absolute.
     @location(0) position: vec3<f32>,
     @location(1) uv: vec2<f32>,
     @location(2) color: vec4<f32>,    // raw authored gamma RGBA; α is the blend weight
@@ -89,8 +64,7 @@ struct VertexOutput {
     @builtin(position) clip_position: vec4<f32>,
     @location(0) uv: vec2<f32>,
     @location(1) color: vec4<f32>,
-    // View-space depth (+ in front of the camera) — the fog/farclip planar eye-Z (exact on
-    // the cam-relative path, where the view transform is pure rotation).
+    // Planar eye-Z for fog and the farclip wall, positive in front of the camera.
     @location(2) view_z: f32,
 };
 
@@ -98,20 +72,15 @@ struct VertexOutput {
 fn vertex(v: Vertex) -> VertexOutput {
     var out: VertexOutput;
 #ifdef DECAL_WORLD_CLIP
-    // The decal family (raster_bias ≠ 0): ABSOLUTE world verts through `clip_from_world` —
-    // the SAME matrix every world-mesh shader runs (`position_world_to_clip` in terrain.wgsl /
-    // wow_model.wgsl). A decal's depth must tie against the drawn ground within the small
-    // rasterizer bias; the cam-relative route below reaches the same plane through different
-    // arithmetic, and at WoW-scale coordinates the two disagree by more than the bias — the
-    // flaky/wedge-shaped blob shadow (decision 0781). Same matrix, same jitter: the decal
-    // wobbles WITH its receiver instead of against it.
+    // Decals (raster_bias ≠ 0) take absolute verts through the world meshes' `clip_from_world`:
+    // their depth must tie the ground within the raster bias, and the cam-relative route rounds
+    // differently by more than that at world-scale coordinates.
     out.clip_position = view.clip_from_world * vec4<f32>(v.position, 1.0);
-    // Fog/farclip eye-Z via the full affine transform (yards-scale — rounding is irrelevant).
+    // Eye-Z via the full affine transform; its rounding is yard-scale and harmless.
     out.view_z = -(view.view_from_world * vec4<f32>(v.position, 1.0)).z;
 #else
-    // Free-floating families: cam-relative verts (0733 §2). view_from_world = [R | −R·cam];
-    // for a cam-relative point the translation column is exactly the subtraction prepare
-    // already did, so only the rotation remains.
+    // Cam-relative verts: view_from_world is [R | −R·cam] and the rebase already subtracted cam,
+    // so only the rotation applies.
     let view_pos = mat3x3<f32>(
         view.view_from_world[0].xyz,
         view.view_from_world[1].xyz,
@@ -127,9 +96,7 @@ fn vertex(v: Vertex) -> VertexOutput {
 
 @fragment
 fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
-    // The draw's target-rect clip (see `EffectParams::clip`). `@builtin(position)` is the
-    // framebuffer pixel, which for the UI tile atlas IS the atlas texel — so this is the
-    // scissor the reference gets from the widget's viewport, per fragment.
+    // The target-rect clip; `@builtin(position)` is the framebuffer pixel, a UI tile's atlas texel.
     if (wow_params.clip.z > wow_params.clip.x) {
         let p = in.clip_position.xy;
         if (p.x < wow_params.clip.x || p.y < wow_params.clip.y
@@ -137,71 +104,33 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
             discard;
         }
     }
-    // `$WOW_PARTICLE_FLAT` (B16 instrument): solid magenta, no inputs — see render.rs.
+    // `$WOW_PARTICLE_FLAT` debug instrument: solid magenta, no inputs.
 #ifdef WOW_PARTICLE_FLAT
     return vec4<f32>(1.0, 0.0, 1.0, 1.0);
 #else
-    // HARD FAR-CLIP WALL (faithful `farclip` ~777 yd) — see terrain.wgsl for the law. The
-    // reference has ONE projection far plane clipping the whole detailed world including the
-    // effect family; ours sits at ~3000 yd so every world shader emulates the wall per-pixel.
-    // Missing it here was bug B39. No pop: the scene fog end is `min(fog_end, farclip)`, so a
-    // quad reaching the wall has already faded to the fog colour — toward BLACK for an
-    // Add-blend emitter, i.e. to nothing under `One` blend.
+    // The hard farclip wall (the live `farclip`, 177 to 777 yd): the reference's far plane clips
+    // effects and ours is farther, so every world shader discards. The fog ends by the farclip, so
+    // this cuts only fog.
     if (wow_light.fog_params.w > 0.0 && in.view_z > wow_light.fog_params.w) {
         discard;
     }
-    // The gamma-space product — texture bytes × raw authored vertex colour, exactly what the
-    // reference multiplies.
-    // `view.mip_bias`: the render-scale LOD compensation (1639), 0.0 at native and above.
+    // Texture bytes × authored vertex colour in gamma space; `view.mip_bias` is the render-scale
+    // LOD compensation, 0.0 at native and above.
     let c = textureSampleBias(effect_texture, effect_sampler, in.uv, view.mip_bias) * in.color;
 #ifdef BLEND_ALPHAKEY
-    // THE FIXED-FUNCTION ALPHA TEST (EGxRs id 0x08 — `glAlphaFunc(GL_GEQUAL, ref/255)` +
-    // `glEnable(GL_ALPHA_TEST)`). `0x70c256` computes the ref from the RAW blend mode, so an
-    // AlphaKey emitter keeps `round(instanceAlpha × 224.0)` — 224 at full alpha — and `c.a` here
-    // is exactly the reference's fragment alpha: texture α × the over-life track α, GL_MODULATE.
-    // GEQUAL, so the test PASSES at the ref: discard strictly below it.
-    //
-    // Without it the debris family's transparent field paints solid — the Lesser Rock Elemental's
-    // chips drew as pale squares, PARTROCK.BLP's α = 0 surround at full opacity.
+    // The fixed-function alpha test (EGxRs id 0x08, `glAlphaFunc(GL_GEQUAL, ref/255)`): `0x70c256`
+    // sets ref = round(instanceAlpha × 224), 224 at full alpha, and `c.a` is the reference's
+    // fragment alpha (texture α × track α, GL_MODULATE). GEQUAL passes at the ref.
     if (c.a < 224.0 / 255.0) {
         discard;
     }
 #endif
     var rgb = c.rgb;
 #ifdef EFFECT_LIT
-    // SCENE LIGHTING (EGxRs id 0x0e), for the emitters that ask for it. A particle emitter owns
-    // no material: the reference synthesizes an `M2Material` from the emitter's file record every
-    // draw (`0x70d8b0`) and runs the SAME batch state producer as an ordinary mesh submesh, so
-    // `GL_LIGHTING` lands on a particle quad exactly as on geometry — enabled iff the emitter
-    // CLEARS file flag 0x1 and its blend mode is not Mod/Mod2x (wow-re `part-scene-multipliers.md`
-    // §1, byte-verified at `0x70baf0` @`0x70bb00`; the gate itself is `EffectDrawSpec::lit`).
-    //
-    // File bit 0x1 is the UNLIT flag — the inverse of the wowdev-wiki lore — so the fire and spell
-    // corpus (which sets it) stays bright at night, while the environment sheets that clear it
-    // take the world's light: waterfall spray, chimney smoke, blown dust, snow. Rendering those
-    // unlit is a full-white cutout against shaded terrain (the Zul'Gurub waterfall foam).
-    //
-    // The term is the fixed-function matte `wow_model.wgsl` applies to a mesh —
-    // `clamp(ambient + diffuse·max(N·L, 0))` — and **N is the WORLD UP axis, one constant for the
-    // whole draw** (wow-re `part-lit-normal-space.md`, §5-converged). The quad writer stores the
-    // same triple into all four vertices of every quad from a single per-draw global
-    // (`0xcf5878..80`, nine identical stores across the head/tail legs), and that global is set
-    // once per draw by `0x7b3fd0` from **row 2 of the VIEW matrix** (`0x58b0b0` = GetView, not
-    // GetWorld) — i.e. world +Z carried into eye space. The light is carried into the same frame
-    // (`0x71bce0` pre-multiplies the M2 light direction by `CM2Scene+0x9c`, and `glLightfv` is
-    // issued under the VIEW slot alone), so the rotation cancels and the product the hardware
-    // computes is exactly `worldUp · worldLightDir` — **invariant as the camera orbits**.
-    //
-    // We had a camera-facing normal here, read off a parenthetical in `part-scene-multipliers.md`
-    // §1 that was written about an emitter that is UNLIT and has since been corrected at the bytes
-    // (its polarity was inverted too: the LIT leg is the one that binds a real normal stream —
-    // vertex format 4, normal at +0x0c — while an UNLIT emitter's format has no normal element at
-    // all). It made this multiplier swing with the viewer: in Onyxia's Lair, where the trap dust is
-    // lit and additive, `ambient (0.22,0.26,0.29)` → `ambient + diffuse (1.00,0.93,0.74)` — a ~4×
-    // brightness change from nothing but turning the camera (decision 1696).
-    //
-    // N and L must be in the SAME frame; that is where the invariance comes from. Both are world
-    // here (Bevy axes: WoW's +Z up is Bevy +Y).
+    // Scene lighting (EGxRs id 0x0e, `0x70d8b0`) when the emitter clears the unlit flag 0x1 and
+    // its blend is not Mod or Mod2x (`0x70bb00`): the fixed-function matte with N = world up for
+    // the whole draw, as `0x7b3fd0` takes the normal from view row 2 and `0x71bce0` moves the
+    // light into that frame, so N·L holds as the camera orbits. Bevy +Y is WoW +Z.
     let L = -normalize(wow_light.light_sun.xyz);
     let N = vec3<f32>(0.0, 1.0, 0.0);
     let lit = clamp(
@@ -211,32 +140,26 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
     );
     rgb = rgb * lit;
 #endif
-    // The scene day-night fog — byte-verified ON the particle path (wow-re
-    // part-scene-multipliers.md): the reference runs the SAME per-vertex linear fog as world
-    // geometry — same start/end, same day-night colour, applied in gamma space BEFORE blend,
-    // with NO additive special-case. The blend equation then does the whole night split by
-    // itself. Missing fog was the "night smoke glows" bug. (Planar eye-Z, like terrain fog.)
+    // Scene fog: the world's linear fog (same start and end, planar eye-Z) in gamma space before
+    // the blend; only its colour follows the per-blend policy in `wow_params.fog.x`.
     if (wow_light.fog_color.w > 0.5 && wow_params.fog.x > 0.5) {
         let denom = max(wow_light.fog_params.y - wow_light.fog_params.x, 0.001);
         let factor = clamp((wow_light.fog_params.y - in.view_z) / denom, 0.0, 1.0);
-        // The fog COLOUR follows the policy in wow_params.fog.x (see its declaration).
         var fog_rgb = wow_light.fog_color.xyz;
         if (wow_params.fog.x > 1.5 && wow_params.fog.x < 2.5) { fog_rgb = vec3<f32>(0.0); }
         else if (wow_params.fog.x > 2.5 && wow_params.fog.x < 3.5) { fog_rgb = vec3<f32>(1.0); }
         else if (wow_params.fog.x > 3.5) { fog_rgb = RAIN_FOG_GREY; }
         rgb = mix(fog_rgb, rgb, factor);
     }
-    // The FORCED fog (rain weather): grey-0.5 over the params' own start/end, regardless of
-    // the scene fog state — under Mod2x the grey is neutral, so this IS the streak/patter
-    // distance fade (rf-weather-render Q3).
+    // Rain's forced fog: grey over the draw's own start/end, whatever the scene fog; grey is
+    // neutral under Mod2x, so this is the streaks' distance fade.
     if (wow_params.fog.y > 0.5) {
         let denom = max(wow_params.fog.w - wow_params.fog.z, 0.001);
         let factor = clamp((wow_params.fog.w - in.view_z) / denom, 0.0, 1.0);
         rgb = mix(RAIN_FOG_GREY, rgb, factor);
     }
 #ifdef BLEND_ADD
-    // GAMMA LANE (0161): gamma-premultiplied, raw out — N stacked faint quads SUM in gamma
-    // like the reference's bytes. α = 0 turns (One, 1−srcα) into pure addition.
+    // Premultiplied in gamma, so stacked quads sum like the reference's bytes.
     return vec4<f32>(rgb * c.a, 0.0);
 #else
 #ifdef BLEND_OPAQUE
@@ -247,12 +170,9 @@ fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
     return vec4<f32>(rgb, 1.0);
 #else
 #ifdef BLEND_MULTIPLY
-    // The modulate family: premultiplied for bevy's Multiply state — `dst·lerp(1, rgb, α)`
-    // (the blob shadow's fade-riding darken; `ModelBlend::Mod` at α = 1).
     return vec4<f32>(rgb * c.a, c.a);
 #else
 #ifdef BLEND_MOD2X
-    // `(Dst, Src)` reads no alpha (0528's no-alpha law).
     return vec4<f32>(rgb, 1.0);
 #else
     return vec4<f32>(rgb, c.a);
diff --git a/crates/benilla-world/src/sky.rs b/crates/benilla-world/src/sky.rs
index c327adb0..265fd9db 100644
--- a/crates/benilla-world/src/sky.rs
+++ b/crates/benilla-world/src/sky.rs
@@ -1,33 +1,12 @@
-//! Sky dome — the gradient backdrop. The real 1.12.1 client draws the sky FIRST each frame as an
-//! unlit, vertex-coloured dome with depth-write OFF (apitrace WoW.5: prog 140, GL_TRIANGLE_STRIP 300
-//! idx, no texture, additive); the gradient colours are the five `Light.dbc` `SkyColor` stops
-//! (LightIntBand rows 2–6) plus the fog colour (row 7), decoded into `WowLighting.{sky,fog_color}`.
+//! The sky dome, the gradient backdrop. The reference draws the sky first each frame as an unlit,
+//! vertex-coloured dome without depth writes: a camera-centred cap of 1 apex and 5 rings × 24
+//! segments, recentred by `−cos(45°)` so the rim sits at eye level (builder `0x6d0d10`, colours
+//! `0x6d0f50`). The five `Light.dbc` `SkyColor` stops (LightIntBand rows 2 to 6) sit one per ring
+//! at 90°, 16.8°, 9.8°, 3.7° and 1.8° of elevation, the horizon and below are the fog colour
+//! (row 7), and colour is linear in elevation between rings.
 //!
-//! **Geometry + mapping are RE-VERIFIED** (binary `WoW.exe`: builder `FUN_006d0d10`, colour gen
-//! `FUN_006d0f50`; cross-checked against the actual memcpy'd dome vertices in apitrace WoW.5 — both
-//! agree). WoW's dome is a camera-centred cap of 1 apex + 5 rings × 24 segments, recentred by
-//! `−cos(45°)` so the rim sits at eye level (horizon). The five stops sit one-per-ring at GEOMETRIC
-//! elevations (above the horizon): **SkyColor0 @ 90° (zenith), SkyColor1 @ 16.8°, SkyColor2 @ 9.8°,
-//! SkyColor3 @ 3.7°, SkyColor4 @ 1.8°**, and the **rim/horizon (0°) and below = the FOG colour**
-//! (row 7) — the sky converges into the distance fog at the horizon. GL Gouraud-interpolates between
-//! rings → piecewise-linear in elevation. So SkyColor0 dominates the whole upper sky and the gradient
-//! is crushed into the bottom ~17°.
-//!
-//! We reproduce the same *result* with a camera-centred sphere scaled to just inside the far plane
-//! and an unlit material that interpolates the stops **per-fragment** by the view-direction
-//! elevation (tessellation-independent → no banding). Like the reference, the dome does NOT write
-//! depth (the [`SkyExt::specialize`] hook) — the z-buffer stays clean over sky pixels, which is what
-//! lets the far-forced glare quads (`celestial.wgsl`) be occluded per-pixel by world geometry alone.
-//! The dome's own depth is likewise the far plane, pinned in the vertex stage every sky material
-//! shares (`sky_vertex.wgsl`; the law is in [`crate::sky_order`]), so the world always paints over
-//! the backdrop no matter how the radius compares to a given piece of geometry — the WDL horizon
-//! ring reaches past this shell. The dome tracks the camera
-//! *position* but stays world-aligned (identity rotation) so the gradient is fixed to the world
-//! horizon regardless of look direction.
-//!
-//! Deferred (not in this basic dome): the day/night sky-intensity scalar that pre-scales the stops,
-//! and the additive sun-azimuth glow (sun-side brightening) — both per `FUN_006d0f50`. Sun/moon discs
-//! and clouds are separate later layers.
+//! Here a world-aligned sphere around the camera interpolates the stops per fragment by view
+//! elevation, at the far plane ([`crate::sky_order`]), so world geometry always paints over it.
 
 use bevy::asset::RenderAssetUsages;
 use bevy::camera::Projection;
@@ -47,42 +26,39 @@ use crate::lighting::WowLighting;
 use crate::view::WorldCamera;
 use benilla_assets::AssetSet;
 
-/// Unlit gradient sky over a `StandardMaterial` shell — the shell only supplies `unlit` +
-/// `cull_mode: None` (the dome is viewed from the inside); the extension's fragment shader ignores PBR
-/// and outputs the elevation gradient.
+/// The unlit gradient sky; the `StandardMaterial` shell only supplies `unlit` and no culling.
 pub type SkyMaterial = ExtendedMaterial<StandardMaterial, SkyExt>;
 
-/// The five sky-gradient stops (zenith→horizon) + the fog/horizon colour, as shader uniforms packed
-/// onto one binding (100) — same packing trick as `WowModelExt` (`terrain.rs`). WGSL struct order
-/// must match this field order (each `Vec4` is 16 B, no implicit padding).
+/// The five sky stops, zenith to horizon, and the fog colour on one binding (100); `sky.wgsl`'s
+/// struct must match this field order.
 #[derive(Asset, AsBindGroup, Clone, TypePath)]
 pub struct SkyExt {
-    /// `SkyColor0` — zenith (90°).
+    /// `SkyColor0`: zenith (90°).
     #[uniform(100)]
     pub(crate) sky0: Vec4,
-    /// `SkyColor1` — 16.8°.
+    /// `SkyColor1`: 16.8°.
     #[uniform(100)]
     pub(crate) sky1: Vec4,
-    /// `SkyColor2` — 9.8°.
+    /// `SkyColor2`: 9.8°.
     #[uniform(100)]
     pub(crate) sky2: Vec4,
-    /// `SkyColor3` — 3.7°.
+    /// `SkyColor3`: 3.7°.
     #[uniform(100)]
     pub(crate) sky3: Vec4,
-    /// `SkyColor4` — 1.8° (last sky ring).
+    /// `SkyColor4`: 1.8°, the last sky ring.
     #[uniform(100)]
     pub(crate) sky4: Vec4,
-    /// Fog colour (LightIntBand row 7) — the horizon (0°) and below converge into this.
+    /// Fog colour (LightIntBand row 7): the horizon (0°) and below.
     #[uniform(100)]
     pub(crate) fog: Vec4,
-    /// Dawn/dusk azimuthal warp inputs (`FUN_006d0f50`): `x` = strength `S` (`WowLighting.sky_warp`,
-    /// 0 = no warp / midday), `y` = sun azimuth `atan2(sun.z, sun.x)` rad (Bevy world), `zw` reserved.
+    /// Dawn/dusk azimuthal warp (`0x6d0f50`): `x` the strength `S` (`WowLighting.sky_warp`, 0 for
+    /// none), `y` the sun azimuth `atan2(sun.z, sun.x)` in radians, `zw` reserved.
     #[uniform(100)]
     pub(crate) warp: Vec4,
 }
 
 impl MaterialExtension for SkyExt {
-    /// The shared sky vertex stage — the far-depth pin ([`crate::sky_order`], "The depth law").
+    /// The shared sky vertex stage, which pins depth to the far plane ([`crate::sky_order`]).
     fn vertex_shader() -> ShaderRef {
         crate::sky_order::SKY_VERTEX_SHADER.into()
     }
@@ -91,13 +67,8 @@ impl MaterialExtension for SkyExt {
         "embedded://benilla_world/shaders/sky.wgsl".into()
     }
 
-    /// Depth-write OFF — the reference draws its whole sky without writing depth (the apitrace
-    /// note in the module header, byte-confirmed by the `celestial-frame-anatomy` pin: every sky
-    /// element inherits `CSky::Render`'s depth-write-off state). Depth-TEST stays on, so terrain
-    /// still occludes the dome; what this buys is a clean z-buffer over sky pixels — the glare
-    /// quads (pinned to the far depth like the dome itself) are occluded per-pixel by *world*
-    /// geometry only, never by the backdrop dome they must shine over. Plus the state every sky
-    /// pipeline takes ([`crate::sky_order::sky_pipeline_state`]).
+    /// No depth write, as every sky element inherits from `CSky::Render` (`0x6d4940`); the depth
+    /// test stays on. The glare quads are then occluded by world geometry only, never the dome.
     fn specialize(
         _pipeline: &MaterialExtensionPipeline,
         descriptor: &mut RenderPipelineDescriptor,
@@ -116,8 +87,8 @@ impl MaterialExtension for SkyExt {
 #[derive(Component)]
 struct Sky;
 
-/// Sky-dome subsystem: registers the material, spawns the dome at startup, and per frame pins it to
-/// the camera + pushes the time-of-day `Light.dbc` sky/fog colours into its material.
+/// The sky dome: spawned at startup, pinned to the camera and fed the `Light.dbc` colours each
+/// frame.
 pub(crate) struct SkyPlugin;
 
 impl Plugin for SkyPlugin {
@@ -127,22 +98,16 @@ impl Plugin for SkyPlugin {
             .add_systems(
                 Update,
                 (
-                    // The dome's stops are the resolved atmosphere, so the push belongs on the
-                    // READ side of the resolve (`lighting::LightingConsumeSet`) — unordered it
-                    // runs at the top of `Update` and paints last frame's palette, which on a
-                    // surfacing frame is the underwater one (B354, decision 2032).
+                    // Reads the resolved atmosphere: unordered, it would paint last frame's
+                    // palette, the underwater one on a surfacing frame.
                     update_sky_colors.in_set(crate::lighting::LightingConsumeSet),
-                    // The dome stands down for a WMO skybox, so its gate must read the SETTLED
-                    // resolve, not whichever side of it the executor picked (`crate::skybox`).
+                    // The skybox and submersion gates must read their settled resolves.
                     apply_sky_visibility
                         .after(crate::skybox::SkyboxResolve)
                         .after(crate::liquid::SubmersionVerdict),
                 ),
             )
-            // Camera-anchored placement runs post-propagation (the BillboardPlace slot) off the
-            // camera's SAME-frame pose — the Update wiring read the last-frame camera (decision
-            // 0504; sub-visible at the dome's far radius, but it's the same latent bug the near
-            // glare quads made visible, so the whole camera-anchored class moved together).
+            // After propagation (`BillboardPlace`), from the camera's same-frame pose.
             .add_systems(
                 PostUpdate,
                 follow_camera.in_set(crate::billboard::BillboardPlace),
@@ -154,9 +119,7 @@ fn col(c: [f32; 3]) -> Vec4 {
     Vec4::new(c[0], c[1], c[2], 1.0)
 }
 
-/// A unit UV sphere (Y-up). `cull_mode: None` makes both faces visible, so winding doesn't matter.
-/// The gradient is per-fragment from the view direction, so a modest tessellation is plenty; the lower
-/// hemisphere resolves to the fog colour and is covered by terrain anyway.
+/// A unit UV sphere (Y-up); the gradient is per fragment, so a modest tessellation suffices.
 fn dome_mesh() -> Mesh {
     const STACKS: usize = 24;
     const SECTORS: usize = 48;
@@ -173,7 +136,7 @@ fn dome_mesh() -> Mesh {
             let (st, ct) = theta.sin_cos();
             let p = [sp * ct, cp, sp * st]; // y = cos(phi): +1 zenith, −1 nadir
             positions.push(p);
-            normals.push([-p[0], -p[1], -p[2]]); // inward (unused — unlit)
+            normals.push([-p[0], -p[1], -p[2]]); // inward (unused: unlit)
             uvs.push([u, v]);
         }
     }
@@ -230,9 +193,8 @@ fn setup_sky(
     ));
 }
 
-/// Pin the dome to the camera and scale it to just inside the far plane (the radius only has to keep
-/// the dome unclipped — occlusion is `sky_vertex.wgsl`'s far-depth pin). World-aligned (identity rotation)
-/// → the gradient stays fixed to the world horizon regardless of camera look direction.
+/// Pin the dome to the camera, world-aligned, just inside the far plane; the radius only keeps it
+/// unclipped, since occlusion is `sky_vertex.wgsl`'s far-depth pin.
 #[allow(clippy::type_complexity)]
 fn follow_camera(
     cam: Query<(&GlobalTransform, &Projection), With<WorldCamera>>,
@@ -251,21 +213,14 @@ fn follow_camera(
     tf.translation = cam_gt.translation();
     tf.rotation = Quat::IDENTITY;
     tf.scale = Vec3::splat(far * 0.9);
-    // Propagation already ran this frame — the direct global write is what renders.
+    // Propagation already ran this frame, so the direct global write is what renders.
     *gt = GlobalTransform::from(*tf);
 }
 
-/// Hide/show the dome from the debug panel's "disable sky dome" toggle — and stand it down entirely
-/// while a **WMO skybox** owns the backdrop ([`crate::skybox`]), or while the eye is **submerged**:
-/// a building whose group asks for its MOSB model replaces this gradient, it does not layer over it,
-/// and underwater the reference skips the whole sky pass (the scene driver's `0x6812a4` submerged
-/// test gates `CSky::Render 0x6d4940` — stars, discs, gradient band and cloud dome together;
-/// byte-VERIFIED, wow-re terrain "the liquid render state"). With the dome hidden the `ClearColor`
-/// backdrop (the row-7 fog colour — submerged, the murk — or black via "black backdrop") shows through.
-///
-/// The skybox gate is its **weight**, not the resolve: below the 0.99 threshold the dome still
-/// draws and the painted sky alpha-blends OVER it — the visible half of the 4-second crossfade
-/// ([`crate::skybox::SkyboxWeight`]).
+/// Hide the dome for the debug toggle, under a WMO skybox (its MOSB model replaces the gradient)
+/// and while submerged: the reference's submerged test (`0x6812a4`) skips `CSky::Render`
+/// (`0x6d4940`) whole. The skybox gate is its weight: below 0.99 the dome still draws under the
+/// crossfading skybox ([`crate::skybox::SkyboxWeight`]).
 fn apply_sky_visibility(
     debug: Res<DebugState>,
     skybox: Res<crate::skybox::SkyboxWeight>,
@@ -286,8 +241,7 @@ fn apply_sky_visibility(
     }
 }
 
-/// Push the time-of-day sky stops + fog colour (`WowLighting`, sampled from `Light.dbc`) into the dome
-/// material.
+/// Push the time-of-day sky stops and fog colour (`WowLighting`) into the dome material.
 fn update_sky_colors(
     light: Res<WowLighting>,
     dome: Query<&MeshMaterial3d<SkyMaterial>, With<Sky>>,
@@ -296,22 +250,18 @@ fn update_sky_colors(
     let Ok(handle) = dome.single() else {
         return;
     };
-    // Byte-quantized (`quant255` — Light.dbc stops are byte colors) and write-gated: the stops
-    // drift continuously with time-of-day, but an `Assets::get_mut` alone re-uploads the material
-    // every frame; gated, the dome only pays when a display-visible band actually moves.
+    // Quantized to bytes (Light.dbc stops are byte colours) and write-gated, since a `get_mut`
+    // alone re-uploads the material.
     let sky: Vec<Vec4> = light
         .sky
         .iter()
         .map(|c| col(benilla_assets::quant255(*c)))
         .collect();
     let f = benilla_assets::quant255(light.fog_color);
-    // `fog.w` unused by the shader (the old raw-vs-linearised A/B is gone — GAMMA LANE, 0161).
+    // `fog.w` is unused by the shader.
     let fog = Vec4::new(f[0], f[1], f[2], 0.0);
-    // Dawn/dusk warp: strength S + the sun's compass azimuth (Bevy world `atan2(z, x)` of the
-    // camera→sun direction). The warp's glow table is symmetric about this bearing, so the sun-facing
-    // dome quarter warms and the opposite side desaturates. S=0 (all midday / highlightSky=0 zones) →
-    // the shader leaves the gradient untouched. Azimuth/strength gate at 1/4096 — sub-visible
-    // steps of the warp's smooth glow table.
+    // Dawn/dusk warp: strength S and the sun's azimuth `atan2(z, x)`, quantized to 1/4096; S = 0
+    // (midday, or a `highlightSky` 0 zone) leaves the gradient untouched.
     let s = light.celestial_dir;
     let sun_az = s.z.atan2(s.x);
     let warp = Vec4::new(
diff --git a/crates/benilla-world/src/sky_order.rs b/crates/benilla-world/src/sky_order.rs
index 4e7d8f42..45f8aeb9 100644
--- a/crates/benilla-world/src/sky_order.rs
+++ b/crates/benilla-world/src/sky_order.rs
@@ -1,465 +1,173 @@
-//! The celestial draw-order ladder — the reference's **fixed sky pass order**, expressed as
-//! `Transparent3d` sort biases (wow-re `celestial-frame-anatomy`, §5-verified off the binary).
+//! The celestial draw-order ladder: the reference's fixed sky pass order as `Transparent3d` sort
+//! biases.
 //!
-//! The real client draws the frame `sky → opaque world → weather → glare`, and inside its sky pass
-//! (`CSky::Render 0x6d4940`, one squashed depth slice `[0.975, 0.98]`, depth-write off, painter's
-//! order): **stars → sun disc → white moon → moon02 → gradient strip (additive) → cloud dome** —
-//! so the clouds composite over a setting sun, rain falls in front of the whole sky, and the glare
-//! quads (their own back slice `[0.995, 1.0]`, the frame's LAST draw) paint over everything the
-//! z-buffer leaves visible.
+//! The 1.12 client draws `sky → opaque world → weather → glare`. Its sky pass (`CSky::Render`,
+//! `0x6d4940`) paints stars, sun disc, white moon, moon02, the additive gradient strip and the
+//! cloud dome, in that order, depth-write off in the slice `[0.975, 0.98]`; the glare quads take
+//! `[0.995, 1.0]` and draw last. Our sky is camera-anchored and Bevy sorts transparents back to
+//! front by `view-z + depth_bias`, so its rungs sit far below any world view-z. Rain has no bias:
+//! its view-z lands it after the sky and before the glare, the reference's weather slot; its order
+//! against world transparents is untraced.
 //!
-//! Bevy instead sorts every transparent by `view-z of the mesh center + depth_bias`, drawn
-//! back-to-front — and our celestial entities are camera-anchored, so their raw distances are
-//! sort-order accidents (the camera-centred cloud dome sat at ~0 = drawn LAST, painting clouds
-//! over rain and over the glare — backwards on both counts). These biases turn the accident back
-//! into the reference's fixed order: spaced far below any real in-scene view-z (≳ −far plane, a
-//! few ×10³) so world distances can never reorder the sky and every world transparent draws over
-//! it, with the glare *above* zero so it draws after the world and the rain — but still below
-//! [`Rung::NAMEPLATE`], which keeps world text on top of the flare (the
-//! reference draws its text later still).
+//! The sign: `Transparent3d` sorts ascending on view-space z (negative in front of the eye) plus
+//! the bias, so a positive bias draws later, on top. On a `StandardMaterial` the same field is the
+//! rasterizer's depth-bias constant, so a rung on a depth-tested draw stays as small as it can.
 //!
-//! Precipitation deliberately has NO bias: an unbiased view-z of a few tens of units lands rain
-//! after the biased sky and before the glare — the reference's `weather` slot — without pinning
-//! rain-vs-world-transparent order we have no byte law for.
-//!
-//! ## Which way the bias points — the sign, read off Bevy 0.18 (never guessed again)
-//!
-//! Every rung below is a *signed* number in one direction, and the direction was inverted here for
-//! a week (decision 0639 — the whole ladder ran upside down; names sorted UNDER the water that
-//! erased them). Verified in the bevy 0.18.1 sources, so the next edit can check rather than
-//! recall:
-//!
-//! - `ViewRangefinder3d::distance` (`bevy_render/src/render_phase/rangefinder.rs`) returns the
-//!   **view-space z** of the point — *negative* in front of the camera, and MORE negative the
-//!   farther away (its own unit test puts points behind the eye at `+1`/`+2`).
-//! - `Transparent3d` sorts **ascending** on that value (`bevy_core_pipeline/src/core_3d/mod.rs`:
-//!   "Values increase towards the camera. Back-to-front ordering for transparent means we need an
-//!   ascending sort") — so the first item drawn is the most negative = the farthest.
-//! - The queue adds the material's bias to it (`bevy_pbr/src/material.rs`,
-//!   `RenderPhaseType::Transparent`: `rangefinder.distance(&center) + depth_bias`).
-//!
-//! ⇒ **A POSITIVE bias draws LATER (on top); a NEGATIVE bias draws EARLIER (behind).** Bevy's own
-//! `StandardMaterial::depth_bias` doc says it in words: "a positive depth bias will render closer
-//! to the camera while negative values cause the material to render behind other objects".
-//!
-//! The magnitude is not free, because the same field is *also* the rasterizer's depth bias
-//! (`bevy_pbr/src/pbr_material.rs` packs it into the pipeline key → `DepthBiasState::constant`,
-//! applied in depth ULPs ≈ 2⁻²³ *relative*, the same knob [`crate::target::ring`] uses at 8192 to
-//! beat coplanar noise). It is harmless for the sky rungs (every sky fragment overwrites its own
-//! depth, below) but it perturbs the depth TEST of anything depth-tested, so the world-side rungs
-//! stay as small as their ordering job allows.
-//!
-//! ## The depth law — every sky vertex pins the far depth
-//!
-//! The biases above order the sky *against itself*. What orders it against the **world** is depth,
-//! and there the reference gives one rule for the whole pass: the sky draws FIRST, in a squashed
-//! back slice (`[0.975, 0.98]`, the glare further back at `[0.995, 1.0]`), depth-write off — so the
-//! opaque world simply paints over it, and no sky element can ever land in front of world geometry.
-//!
-//! Our sky draws *after* the world (Bevy's transparent pass), so the depth **test** has to do that
-//! job — which it only does if the sky's depth is behind everything. Each shell used to rely on its
-//! own camera-anchored radius for that (`far·0.85` discs, `far·0.87` clouds, `far·0.88` stars,
-//! `far·0.9` gradient dome), on the assumption that world geometry is always nearer. **It isn't:**
-//! the WDL horizon ring ([`crate::wdl`]) streams ±5 tiles ≈ 2.9 km and is drawn out to the far plane
-//! (3 km), so distant hills land in a band *behind* every shell — and stars, clouds and discs then
-//! passed the depth test in front of terrain the reference would have occluded them with (the
-//! sighting: stars showing *through* a fogged mountain range at night, decision 0588).
-//!
-//! So every sky VERTEX pins its clip z to `SKY_FAR_CLIP_Z = 0.0` — reverse-Z "infinitely far" —
-//! under Bevy's `GreaterEqual` test, in the one vertex stage every sky material shares
-//! (`sky_vertex.wgsl`, [`SKY_VERTEX_SHADER`]; `sky.wgsl`, `star.wgsl`, `cloud.wgsl` and
-//! `celestial.wgsl` are fragment stages that write colour only). Clip z = 0 interpolates to NDC
-//! depth 0 for every fragment whatever w is, so a sky element survives only where the depth
-//! buffer still holds the clear value: exactly "the world paints over the sky", independent of
-//! any shell radius. The shells now decide only *screen size and sky-internal parallax*, never
-//! occlusion.
-//!
-//! It was a `@builtin(frag_depth)` write in each fragment shader until decision 2016. Same number,
-//! wrong stage: a pipeline whose fragment decides its own depth cannot be early-Z rejected, so
-//! every dome fragment under a hill, a wall or a leaf was shaded in full and discarded late — a
-//! full-screen gradient (and the cloud dome, and the star patches) paid for the covered fraction
-//! of the screen on every frame. Pinned at the vertex the rasterizer rejects them first. The
-//! rasterizer's `DepthBiasState` constant then has to be zero on these pipelines
-//! ([`sky_pipeline_state`]): the rung each sky material carries in `depth_bias` is a SORT key,
-//! and the base `StandardMaterial` packs the same f32 into the bias constant — harmless while
-//! the fragment overwrote its depth, a perturbation of the pinned zero once it doesn't.
+//! The depth law: our sky draws after the world, so every sky vertex pins clip z to 0.0, reverse-Z
+//! infinitely far, in the shared vertex stage ([`SKY_VERTEX_SHADER`]): a sky fragment survives only
+//! where the depth buffer holds the clear value, as the reference's world paints over its sky, and
+//! no shell radius decides occlusion. Pinned at the vertex so early-Z rejects covered fragments,
+//! with [`sky_pipeline_state`] zeroing the raster bias that would move it.
 
 use bevy::render::render_resource::RenderPipelineDescriptor;
 
-/// The one vertex stage every sky material draws through — the far-depth pin (module doc, "The
-/// depth law"). A sky `MaterialExtension` returns this from `vertex_shader()`; the test below
-/// holds each of them to it.
+/// The vertex stage every sky material draws through, the far-depth pin (the depth law); each
+/// returns it from `vertex_shader()`, and the test below holds them to it.
 pub(crate) const SKY_VERTEX_SHADER: &str = "embedded://benilla_world/shaders/sky_vertex.wgsl";
 
-/// The pipeline state every sky material's `specialize` applies (module doc, "The depth law"):
-/// the rasterizer depth-bias constant back to zero, so the sort rung the material carries in
-/// `StandardMaterial::depth_bias` stays sort-only and the vertex stage's pinned far depth reaches
-/// the depth test untouched. Same split the model lane makes for its far-side and skybox twins
-/// (`benilla_assets::materials`, `WowModelExt::specialize`).
+/// Every sky material's `specialize` (the depth law): zero the rasterizer depth-bias constant, so
+/// the rung in `StandardMaterial::depth_bias` stays a sort key and the pinned depth is untouched.
 pub(crate) fn sky_pipeline_state(descriptor: &mut RenderPipelineDescriptor) {
     if let Some(ds) = descriptor.depth_stencil.as_mut() {
         ds.bias.constant = 0;
     }
 }
 
-/// Stars — the first celestial draw (`0x6d4a3f`): everything else in the sky paints over them, so
-/// theirs is the ladder's LOWEST rung (see the sign law above).
+/// Stars, the sky pass's first draw (`0x6d4a3f`): the ladder's lowest rung.
 pub(crate) const STARS_BIAS: f32 = -1.0e6;
-/// **The WMO skybox** ([`crate::skybox`]) — the building-owned painted sky, which replaces this
-/// whole ladder while it draws, so its rung never competes with one above. It needs a rung at all
-/// because a skybox is **an ordinary M2 and not an opaque backdrop**, which is what this module
-/// asserted until decision 1264: `CavernsOfTimeSky.m2` is 21 batches across four blend modes — a
-/// painted cube, six additive star sheets on the cube's own faces, five alpha-blended planet cards
-/// and three alpha-tested asteroid belts on rotating bones. Drawn opaque (the old lane read
-/// positions, UVs and one texture and nothing else) the additive star sheet — near-white RGB whose
-/// stars live in its ALPHA — paints a flat white sheet over the painted sky. That is the director's
-/// "the whole ceiling is white" in Caverns of Time.
-///
-/// The blended half of a skybox therefore lands in the transparent pass, camera-anchored, so its
-/// view-z is a few tens of yards and it would sort *after* the world. This rung sinks it under
-/// every world transparent: the deepest of those is [`FAR_SIDE_BIAS`] plus a far-plane view-z,
-/// ≈ −4.3e4, and the shell's own view-z rides on top of the rung — all four properties of the band
-/// are machine-checked in `model_render`'s
-/// `the_skybox_band_orders_its_batches_on_one_pipeline_key`. Kept as small as that job allows (the
-/// magnitude rationale above), because the rung is also what the batch-order epsilon has to
-/// survive: see `model_render::SKYBOX_ORDER_EPS`.
+/// The WMO skybox ([`crate::skybox`]), which replaces this ladder while it draws: an ordinary
+/// blended M2, so its camera-anchored batches need a rung under every world transparent (the
+/// deepest, [`FAR_SIDE_BIAS`] at the far plane, ≈ −4.3e4), and no deeper, so its batch-order step
+/// (`model_render::SKYBOX_ORDER_EPS`) stays above the f32 ulp here.
 pub(crate) const WMO_SKYBOX_BIAS: f32 = -6.0e4;
-/// The sun disc — second (`0x7e5b90` via `0x6d4a47`).
+/// The sun disc, second (`0x7e5b90` via `0x6d4a47`).
 pub(crate) const SUN_DISC_BIAS: f32 = -8.2e5;
-/// The white moon — third; where the discs cross, the moon paints over the sun.
+/// The white moon, third: where the discs cross, it paints over the sun.
 pub(crate) const WHITE_MOON_BIAS: f32 = -8.1e5;
-/// moon02 — fourth (invisible in clear weather; ordered for its weather-seed surfacing).
+/// moon02, fourth: invisible in clear weather, ordered for when the weather seed surfaces it.
 pub(crate) const MOON02_BIAS: f32 = -8.0e5;
-/// The cloud dome — last of the sky pass (`0x6d4a71`): clouds blend over a setting sun.
+/// The cloud dome, the sky pass's last draw (`0x6d4a71`): clouds blend over a setting sun.
 pub(crate) const CLOUDS_BIAS: f32 = -6.0e5;
-/// **Far-side model transparents** — the water-plane interleave's early half (byte-VERIFIED,
-/// wow-re `water-frame-straddle.md`): the reference splits M2 transparents into an above-water
-/// and a below-water list per model (per **emitter** for particles — each classifies onto exactly
-/// ONE list, `0x7084a0`), and `0x483460` draws the list on the eye's FAR side of the water plane
-/// *before* the water pass, the near side *after*. A draw classified far-side takes this rung —
-/// an effect plus its owner-last rung (capped at 32), a translucent M2 mesh batch plus its batch
-/// eps (≤ ~65 × 1e-3, `model_render::BATCH_ORDER_SORT_EPS`), a zfill twin minus its 8 — so it
-/// lands under [`WATER_BIAS`] with the owner-last law intact inside the band; near-side draws
-/// keep their natural slot above it. The flip on submersion is the interleave inversion
-/// (`0x4836d6 cmp eax,0xf`). Sort-only on every lane: the effect stream splits sort from raster
-/// by construction, and the mesh lane's far twin zeroes the raster constant back in
-/// `WowModelExt::specialize` (`clutter_fade.z` bit 11).
+/// Far-side model transparents, the water-plane interleave's early half: the reference splits M2
+/// transparents per model (`0x707680`; per emitter for particles, `0x7084a0`) and `0x483460` draws
+/// the eye's far side of the water plane before the water pass, the near side after, flipping on
+/// submersion (`0x4836d6`). Sort-only: the mesh lane's far twin zeroes its raster constant.
 pub(crate) const FAR_SIDE_BIAS: f32 = -4.0e4;
-/// **The water surface** — river/ocean/WMO water draw in a fixed frame slot between the two
-/// transparent halves (`0x6701d0 → 0x6816d0`: ocean → river → WMO liquid → foam), never view-z
-/// sorted against model transparents. One rung below the world band puts every unclassified
-/// world transparent after the water (the reference's near-side default) and the far-side
-/// effects before it. Magnitude: must clear the far plane (a few ×10³) so no world view-z can
-/// reorder a water chunk across it, while staying small as a rasterizer bias (this one rides a
-/// `StandardMaterial` base, so it IS also a depth-test bias — ~0.24% depth pull, half of what
-/// the nameplates ship at +4e4; the water-noon/name-water capture diffs are the shoreline check).
+/// The water surface: the reference draws ocean, river, WMO liquid, then foam in a fixed slot
+/// between the two transparent halves (`0x6701d0 → 0x6816d0`), never view-z sorted against model
+/// transparents. It rides a `StandardMaterial`, so it is also a depth-test bias (~0.24% pull).
 pub(crate) const WATER_BIAS: f32 = -2.0e4;
-/// **The water pass's own foam** — `CWater0Ripple`'s wade wake / standing ring, which the reference
-/// draws INSIDE the water group and AFTER every liquid queue has drained (`0x6816d0`: ocean → river
-/// → WMO liquid → foam). So foam is unconditionally over every water surface in the frame and still
-/// under the near-side world transparents that follow the pass.
-///
-/// It rode [`WATER_BIAS`]` + 1.0` until B348: `+1` is a *coplanar* tie-break, and the thing it has to
-/// beat is not one surface but the whole water band. A water chunk's key is `WATER_BIAS + its own
-/// view-z`, so the chunk one lattice over — 33 yd nearer the eye — outranks a foam patch by ~33,
-/// thirty times the tie-break, and paints over it: the director's "the wake goes dull, like another
-/// layer without the effect is over it". A rung, not an epsilon, is the fix, and the window is
-/// arithmetic: above every water key (`WATER_BIAS` + 0) even from the far plane, below every
-/// unbiased near-side transparent (view-z ≥ [`WORLD_VIEW_Z_FLOOR`]) even at the eye — i.e.
-/// `(WATER_BIAS − WORLD_VIEW_Z_FLOOR, WORLD_VIEW_Z_FLOOR)` = `(−1.7e4, −3e3)`, taken centred with
-/// 7e3 of margin at each end. Both ends are asserted below; the blanket 1e4 does not fit a 1.4e4
-/// window and is not claimed (the decal band's precedent).
+/// The water pass's own foam (`CWater0Ripple`'s wade wake), drawn inside the water group after
+/// every liquid queue (`0x6816d0`): over every water surface, under the near-side transparents. A
+/// rung, not a tie-break over [`WATER_BIAS`], since a chunk's key carries its own view-z.
 pub(crate) const FOAM_BIAS: f32 = -1.0e4;
-/// The sun/moon glare quads — the frame's last render (`0x483740` tail): over the clouds and the
-/// rain, under the nameplates; the z-buffer (their pinned far depth, `sky_vertex.wgsl`) is what
-/// occludes them. Only ~6× the far plane, not ~10⁵: a rung this far up is also a rasterizer bias
-/// (the sign law above), and nothing is gained by making it bigger than the ordering needs.
+/// The sun and moon glare quads, the frame's last render (`0x483740`): over the clouds and the
+/// rain, under the nameplates, occluded only by their pinned far depth.
 pub(crate) const GLARE_BIAS: f32 = 2.0e4;
 
-/// The floor of any world draw's view-z: the projection's ~3 km far plane, negated (the sign law
-/// above — view-z is negative in front of the eye, more negative the farther away). Two rungs
-/// order two draws *unconditionally* only when their gap exceeds this, so it is the unit the
-/// assert block measures the ladder's margins in.
+/// The floor of any world draw's view-z, the ~3 km far plane negated: two rungs order their draws
+/// unconditionally only when their gap exceeds it.
 pub(crate) const WORLD_VIEW_Z_FLOOR: f32 = -3.0e3;
 
-/// **The world-side rungs** — the biases lanes *outside* this module apply to their own draw, and
-/// the reason they are here rather than each next to its lane: they are one ladder. 1163 found the
-/// four of them scattered across `blob_shadow`, `ground_fx`, `nameplates` and `target::ring`, each
-/// documenting itself by pointing at one of the others ("the same constant, for the same reason,
-/// as the ring's"), which is a ladder held together by prose. The compile-time assert below can
-/// only check an order it can see — and 1163 left two out of view: the footprint print and the
-/// ground-target reticle each kept a private constant in its own lane, copied from a neighbour's
-/// number by the same prose 1163 came to end. Both are rungs now (B347).
-///
-/// Named as one type so a lane reaches the ladder, not a constant: `Rung::GROUND_FX`.
+/// The world-side rungs other lanes apply to their own draws, kept here as one ladder the
+/// compile-time asserts below can see whole.
 pub struct Rung;
 
 impl Rung {
-    /// The **coplanarity** rung — sort bias AND rasterizer depth-bias constant, one number for
-    /// both roles, and the home of the rationale the whole decal family shares. Projected decal
-    /// vertices are geometrically coplanar with the drawn ground, so without a bias the depth
-    /// test dissolves into per-pixel f32 noise (stipple, view-dependent bites); 8192 · 2⁻²³ pushes
-    /// their depth ~1e-3·distance toward the camera — far above the coplanar noise floor (an ulp
-    /// of Elwynn's 10⁴-yard coords), far below anything visible. Geometric lifts (0.1, 0.02) read
-    /// as hovering at grazing angles — director-confirmed. The reference fights the same
-    /// coplanarity with polygon offset (trace-verified), the fixed-function twin of this bias.
-    ///
-    /// It stays a *sort* rung only for **ground-fx spell decals**, which have no reference frame
-    /// slot to take: the real client draws those quads as ordinary M2 batches with no ground
-    /// conform anywhere in the spell-visual chain (`ground_fx`'s header) — conforming them is our
-    /// own improvement, so "wherever that M2 transparent sorts" is the honest answer and the
-    /// near-side default is after the water. Everything with a *known* slot moved to the
-    /// pre-water band below (B347).
+    /// The ground-fx spell decals' sort rung, after the water and every unbiased world transparent;
+    /// the reference draws these quads as ordinary M2 batches with no frame slot of their own.
     pub const GROUND_FX: f32 = 8192.0;
-    /// **The one rasterizer settle every ground decal shares** — every client of the shared
-    /// surface-decal projector (`decal.rs`): the selection ring, the unit blob shadow, spell
-    /// ground-fx quads, the footprints and the ground-target reticle. It funds the `GreaterEqual`
-    /// tie against the drawn ground (`DECAL_WORLD_CLIP`, 0781).
+    /// The rasterizer depth-bias constant every ground decal shares (ring, blob shadow, ground-fx,
+    /// footprints, reticle), winning the `GreaterEqual` tie against the ground over the bake
+    /// residual: ~1 to 3 world-coordinate ulps between CPU-baked verts and GPU-transformed ones.
     ///
-    /// **It used to be two constants, and the split was wrong** (1817, superseding B131's
-    /// `SHADOW_RASTER`): the ring and reticle rode +8192 on the claim that "the blob shadow is the
-    /// one lane that needs more". The binary groups them the other way — the blob shadow reaches
-    /// the SAME EGxRs id-`0` arming site as the ring, corpse marker, click marker and sky decal
-    /// (`0x6d7920` → `0x6d8047 call 0x6d7330` → `0x6d6fa0` → `0x6d7480`), and it is the
-    /// **footprints** that are a lane of their own (`0x69a54a` in `0x69a3e0`), at 10× (wow-re
-    /// `gx/scratch/decal-depth-bias-lanes.md`, §5 five-way). And our own measurement agrees with
-    /// the grouping: the residual is 0781's bake error — the decal's CPU-baked world verts vs the
-    /// receiver's GPU-transformed verts diverge by ~1–3 ulps of the *world coordinate*, millimetres
-    /// at city magnitudes — which is a property of the bake, identical on every lane that uses it.
-    /// `ground_fx` was a third value again, and not even a raster one: it passed `GROUND_FX as
-    /// i32`, a **sort** rung borrowed for a rasterizer field because the numbers coincided — 1806's
-    /// conflation, in the one place it had survived.
-    /// So one number, and it is the measured one: **the residual is 2.59× the +4096 margin and
-    /// therefore 1.30× the +8192 one**, i.e. the ring and the reticle were riding *under* their own
-    /// conflict and had simply not been walked on a slope yet. Pinned by
-    /// `raised_bias_dominates_the_bake_residual` (particles/render.rs), which now asserts both ends.
-    ///
-    /// **What is deliberately NOT ported: the reference's magnitudes, or its 1 : 10 : 20 ratio.**
-    /// Both are properties of a 24-bit *fixed-point forward-Z* buffer at near 0.1 / far 777 /
-    /// depth-range [0, 0.94], where a constant normalized-depth bias is worth `k · d²` yards —
-    /// 0.0065 yd at 10 yd on the ring lane, 0.16 yd at 50. Ours is reversed-Z **float**, where the
-    /// bias unit is the ULP at the primitive's own depth, so the same constant is worth `z · C ·
-    /// 2⁻²³` — **linear**, not quadratic. Neither profile converts into the other, and the quantity
-    /// that sets ours is a millimetre-scale bake residual that does not grow with distance at all.
-    /// The reference's 10× footprint step has no counterpart here for the same reason: the residual
-    /// is the bake's, and the bake is one path.
+    /// Deviation: one constant, not the reference's per-lane magnitudes (ring and shadow at one
+    /// site, `0x6d7480`; footprints 10x, `0x69a54a`; foam 20x), because those suit its 24-bit
+    /// fixed-point forward-Z buffer; in our reversed-Z float buffer the bias is ULP-relative, and
+    /// one bake path sets one residual.
     pub const DECAL_RASTER: i32 = 32768;
-    /// **The pre-water decal band, rung 1: the selection ring** (and, when they are built, the
-    /// corpse marker and the click-to-move marker — the same `+0x30` slot and the same call site).
-    ///
-    /// This rung shipped at **+8192** for months and was moved on a guess's opposite: 1785 left it
-    /// alone because the ring's frame slot was *unread*, and the RE it dispatched came back with a
-    /// slot earlier than anything guessed. `[node+0xb4] = 0x481540` → `0x4815d0` →
-    /// `0x48160c call [obj vt+0x38]` → `0x614ada call [obj vt+0x30]` → `0x608e00`: the ring is
-    /// emitted **from inside PHASE 1's own M2 node drain** (`0x6812c5 call 0x683dd0`), the same
-    /// loop body that then calls `0x6d78f0` for that node's blob shadow — so the family is not
-    /// merely before the water, it is before the footprints and before the M2 opaque pass too.
-    ///
-    /// **And the ring draws UNDER the shadow, not over it.** Per node the `+0x38` tick runs first
-    /// (`0x48160c`) and the shadow gate second (`0x683ec3`), so the additive ring goes down and the
-    /// modulate shadow darkens it. This ladder asserted the opposite for as long as both rungs have
-    /// existed — "where both decals stack the ring draws later deterministically" was a tie-break
-    /// invented here, not a fact read anywhere, and it was backwards.
+    /// The pre-water decal band, rung 1: the selection ring (and, when built, the corpse and
+    /// click-to-move markers). The reference emits it in phase 1's M2 node drain
+    /// (`0x6812c5 call 0x683dd0`; the node's `+0x38` tick, `0x48160c` → `0x608e00`) before the
+    /// node's shadow gate (`0x683ec3`), so the modulate shadow darkens the additive ring.
     pub const RING: f32 = -5.4e4;
-    /// **The pre-water decal band, rung 2: the unit blob shadow.**
-    ///
-    /// The reference draws its ground decals *before* the water, and B347 is what it costs not
-    /// to. The frame driver `0x483460` emits this one inside PHASE 1's opaque drain row
-    /// (`0x6812c5 call 0x683dd0` → `0x6d78f0` → `0x6d7920`; wow-re `unit-blob-shadow.md` Q1) —
-    /// in the same node-drain loop body as the ring above and immediately after it, before the
-    /// footprints, before the M2 opaque pass (`0x4836a6`), and long before the water surfaces,
-    /// which draw in phase 3 *between* the two M2 transparent passes (`water-frame-straddle.md`
-    /// §1). Every transparent in the world paints over a shadow there.
-    ///
-    /// Here it did the exact opposite. At the old **+4096** the shadow's key (`view-z + bias`)
-    /// beat every world transparent — [`WATER_BIAS`], [`FAR_SIDE_BIAS`], and the unbiased
-    /// near-side default — making it the one thing in the scene the water did not attenuate: a
-    /// crocolisk's blob read through a Stranglethorn river that hid the crocolisk itself, and the
-    /// player's read through the Stormwind mage-tower portal (B347, both shots).
-    ///
-    /// **Where the band fits.** Its keys must clear the world-transparent band below it and the
-    /// WMO-skybox band above it, each by more than a world view-z can travel (`WORLD_VIEW_Z_FLOOR`
-    /// — two rungs are only separated if their gap exceeds it). The deepest world transparent
-    /// sorts at `FAR_SIDE_BIAS − 8 − far ≈ −4.3e4`; the shallowest skybox batch at
-    /// `WMO_SKYBOX_BIAS − 0.09 ≈ −6.0e4` — a window of `(−5.7e4, −4.3e4)`, which the four rungs
-    /// take 2e3 apart, clearing the skybox by 3e3 below and the world band by ~5e3 above. The
-    /// assert block below is the
-    /// check, and it is arithmetic on the neighbours rather than a blanket 1e4: the window is only
-    /// 1.4e4 wide, so the ladder's usual margin does not fit and pretending it does would be the
-    /// lie. **The depth of the rung costs nothing at the rasterizer** — unlike [`WATER_BIAS`] and
-    /// the two rungs above, the effect stream carries sort and raster as separate fields
-    /// ([`DECAL_RASTER`](Rung::DECAL_RASTER) is this lane's other half).
+    /// The pre-water band, rung 2: the unit blob shadow, emitted in the same node drain right
+    /// after the ring (`0x6d78f0` → `0x6d7920`), before the footprints, the M2 opaque pass
+    /// (`0x4836a6`) and the water (phase 3, `0x6816d0`). Sort-only, its raster half being
+    /// [`DECAL_RASTER`](Rung::DECAL_RASTER). The band's window is `(−5.7e4, −4.3e4)`, between the
+    /// WMO-skybox band and the deepest world transparent.
     pub const SHADOW_SORT: f32 = -5.2e4;
-    /// **The pre-water band, rung 3: footprints** — the reference draws them at
-    /// `0x483654` (`0x670240` → `0x69a3e0`), one slot AFTER the shadow pass and still before the
-    /// M2 opaque pass, so a print paints over a shadow rather than under it. That was inverted
-    /// here: the print rode +2048 *below* the shadow's +4096, on a comment calling the reference's
-    /// frame order an open RE item — `water-frame-straddle.md` §1 had already closed it.
+    /// The pre-water band, rung 3: footprints, drawn at `0x483654` (`0x670240` → `0x69a3e0`) after
+    /// the shadows and before the M2 opaque pass, so a print paints over a shadow.
     pub const FOOTPRINT: f32 = -5.0e4;
-    /// **The pre-water band, rung 4: the ground-target reticle** — the reference's solid-receiver
-    /// pass (`0x4836c5`, flags `0x200122`) is the last decal before the water. Its *liquid* pass
-    /// (`0x483727`, flags `0xf0000`) is the family's one genuinely post-water draw, and it has no
-    /// counterpart here: liquid is not a `GroundDecalSurface` yet, so nothing we project can land
-    /// on a water surface at all. When it can, that half wants a rung above [`WATER_BIAS`] — not
-    /// this one.
+    /// The pre-water band, rung 4: the ground-target reticle's solid-receiver pass (`0x4836c5`,
+    /// flags `0x200122`), the last decal before the water. Its liquid pass (`0x483727`, flags
+    /// `0xf0000`) is not built: liquid is not a `GroundDecalSurface`, and it would need a rung
+    /// above [`WATER_BIAS`].
     pub const RETICLE: f32 = -4.8e4;
-    /// **The wade-foam decal's rasterizer settle.** `0x68fd0f` arms EGxRs id `0` for the foam draw
-    /// (`0x68fae0`), which is the client's third and largest ground-decal bias lane.
+    /// The wade-foam decal's rasterizer constant. The reference's foam draw (`0x68fd0f`,
+    /// `0x68fae0`) takes `D3DRS_DEPTHBIAS` = `−f32(footstepBias(0.125) × [0x810390])`, −2048 ULPs
+    /// of its 24-bit depth; its OpenGL arm's `−4.0` slope never runs, as `gxApi` defaults to
+    /// `"direct3d"` (`0x63a81d`). Reversed-Z flips the sign.
     ///
-    /// **The shipped value is `D3DRS_DEPTHBIAS = −1.2207217514514923e−04`** =
-    /// `−f32(footstepBias(0.125) × [0x810390])` — **−2048.03 ULPs** of the reference's 24-bit
-    /// buffer, 20× the ring/shadow lane and 2× the footprints' (VERIFIED, wow-re
-    /// `gx/scratch/decal-depth-bias-lanes.md`, §5 five-way, commit `6335d165`).
-    ///
-    /// **1809's `−8.0001` and its `factor = −4.0` were both dead code.** `gxApi` defaults to
-    /// `"direct3d"` (`0x63a81d`) and no shipped `WTF` overrides it, so `GxDevCreate` builds
-    /// `CGxDeviceD3d` and the OpenGL arm — the only place in the image where the `−4.0` slope
-    /// factor exists — never runs. The GL arm also hard-codes a `×65536` *16-bit* ULP conversion,
-    /// which is why every number derived from it came out **256× too small**. Measured from a
-    /// fully independent state: `factor = 0` on 2485 of 2485 client-originated `glPolygonOffset`
-    /// calls across four captures, which WoW's GL arm cannot emit.
-    ///
-    /// **The signs invert here.** Reference depth runs 0 = near, so its negative offset pulls
-    /// toward the eye; ours is reversed-Z (`CompareFunction::GreaterEqual`, near = 1), where toward
-    /// the eye is *larger* depth — so a ported term is positive.
-    ///
-    /// **We spend almost none of it, on purpose.** Our constant is in ULPs of a **float** buffer
-    /// (per-primitive — the quantisation 1806 is about), so its world pull is `z · C · 2⁻²³`:
-    /// ~1 µm per yard of view distance at `C = 8`. The reference's is `1.29847e−3 · d²` — 0.13 yd
-    /// at 10 yd, 0.52 at 20, 3.2 at 50 — and wow-re **measured, from framebuffer pixels on two
-    /// Northshire wade frames, that it does paint the splash decal onto dry bank**, by ~0.3–1.0 yd
-    /// at an 11.9-yd camera. That bleed is the thing the director reported twice (B348), so the
-    /// fidelity is available and deliberately not taken; the reference's own bound on it is not
-    /// the depth test but the texgen box plus the decal texture's alpha-0 border under CLAMP.
-    /// What ours funds instead is a guard against a driver rounding one pipeline's coplanar
-    /// arithmetic differently from another's — [`FOAM_RASTER_SLOPE`](Rung::FOAM_RASTER_SLOPE) has
-    /// the reason nothing more is needed.
+    /// Deviation: only a few ULPs, a guard against drivers rounding coplanar arithmetic
+    /// differently, because the reference's `1.29847e−3 · d²` yd pull paints the splash onto dry
+    /// bank (0.3 to 1.0 yd at an 11.9-yd camera, measured).
     pub const FOAM_RASTER: i32 = 8;
-    /// **The slope half is deliberately NOT armed — the tie it settles does not exist here** (B348
-    /// second round, 1811; supersedes 1809 §3's transcription).
-    ///
-    /// **The reference has no slope term at all** — 1811 argued this from our own geometry and the
-    /// bytes then confirmed it outright: `D3DRS_SLOPESCALEDEPTHBIAS` is written nowhere in the
-    /// image (`0xaf` never pushed, census of all 24 `call [reg+0xe4]` sites), and the `-4.0` that
-    /// 1809 ported lives only in the OpenGL arm the shipped client never constructs (see
-    /// [`FOAM_RASTER`](Rung::FOAM_RASTER)). A re-implementation that ports it is transcribing dead
-    /// code, and a grazing view of a ground plane is precisely where the two arms diverge most.
-    ///
-    /// 1811's own reason stands underneath, and is the one that would hold even if the term were
-    /// live: our foam patch is not a decal *over* the liquid surface — it **is** the
-    /// liquid surface's own triangles: [`water_fx::build_patch`] emits the wet cells straight out
-    /// of [`WaterChunkInfo`]'s grid, in the liquid mesh's own winding, through the same
-    /// `clip_from_world` (`DECAL_WORLD_CLIP`, 0781) against a mesh whose `Transform` is
-    /// `IDENTITY`. Same vertices, same matrix, same arithmetic — so the depths agree exactly and
-    /// `GreaterEqual` passes the tie on its own. That holds for the fullbright kinds too, which
-    /// are the only liquids that write depth at all (magma/slime are `AlphaMode::Opaque`; water is
-    /// `Blend`, depth-write off, so it never competes at all).
-    ///
-    /// What a slope term *does* buy, measured: a near-horizontal decal at a grazing angle has a
-    /// window-depth gradient of `n / (h · f)` per pixel (eye height `h` above the plane, focal
-    /// length `f` in pixels), so `factor · m` is a world-space pull of `factor · z² / (h · f)` —
-    /// **growing as the square of view distance, and the near plane cancels out**. Whole wet cells
-    /// are the unit of liquid geometry, so a shoreline carries a skirt of liquid-lattice triangles
-    /// over dry sand (up to 7 yd of it at the reported beach — `benilla-formats --example
-    /// water_here`), held back by nothing but the terrain having drawn first. Any pull toward the
-    /// eye spends that budget: at `4.0` the wake visibly washed onto the beach, which is what the
-    /// director reported twice.
+    /// Zero, as in the reference, which never writes `D3DRS_SLOPESCALEDEPTHBIAS`. The foam patch is
+    /// the liquid mesh's own triangles, so `GreaterEqual` wins the tie unaided, and a slope pull
+    /// (growing as z²) would spread the wake over the wet cells a shoreline lays on sand.
     pub const FOAM_RASTER_SLOPE: f32 = 0.0;
-    /// **The underwater drift cloud** — the mote field, at the reference's own frame slot
-    /// `0x483731`: after the water surface AND both M2 transparent passes, immediately before the
-    /// glare dispatch `0x483740`. The last world content in the frame (decision 1814).
-    ///
-    /// The window is narrow and this rung is checked against its actual NEIGHBOURS rather than the
-    /// blanket 1e4, exactly as the decal band is: it has to clear
-    /// [`GROUND_FX`](Rung::GROUND_FX) below and [`GLARE_BIAS`] above, and those are only 1.18e4
-    /// apart. Centred, that leaves ~5.8e3 each side — comfortably more than the
-    /// [`WORLD_VIEW_Z_FLOOR`] spread that is the most two anchors here can differ by, since the
-    /// cloud's anchor is the eye itself and a ground-fx decal's is at most a far plane away.
-    ///
-    /// One batch for the whole field, so there is no intra-cloud sort — which is right rather than
-    /// merely cheap: the reference submits all its survivors as **one indexed triangle list**
-    /// (`0x68f3c9`) in slot order, with depth WRITE off and no per-mote ordering anywhere.
+    /// The underwater drift cloud, at the reference's slot `0x483731`: after the water and both M2
+    /// transparent passes, just before the glare (`0x483740`). One batch, no per-mote sort: the
+    /// reference submits one indexed triangle list (`0x68f3c9`) with depth-write off.
     pub const DRIFT_CLOUD: f32 = 1.4e4;
-    /// **World text** — above the celestial glare, so a flare never washes a nameplate, and above
-    /// every sky rung. The reference draws its world text late in the frame (decision 0519).
-    /// Small on purpose: 6× the far plane is all the ordering needs, and this same field doubles
-    /// as the rasterizer depth bias on a layer that is depth-TESTED (walls must keep occluding
-    /// names). The sign was inverted here once and the water erased the glyphs (decision 0639).
+    /// World text, above the glare so a flare never washes a nameplate (the reference draws it late
+    /// in the frame); also the raster bias of a depth-tested layer, so no bigger than needed.
     pub const NAMEPLATE: f32 = 4.0e4;
 }
 
-/// The ladder IS the reference order — checked at compile time: monotonic through the sky pass,
-/// then the **pre-water decal band** (the reference's own decal slots, B347), then the water-plane
-/// interleave, then rain (unbiased view-z, ≈ 0), the glare above it, and the nameplates above the
-/// glare so text stays readable through a flare. Rung gaps stay wider than any view-z that could
-/// reorder them — over 10⁴ inside the sky (camera-anchored shells spread ±far·0.85 ≈ 2.6e3) and
-/// over 10⁴ on the world side (more than the far plane, a few ×10³) — except inside the decal
-/// band, which lives in a 1.4e4 window between two bands it must not touch and is therefore
-/// checked against its actual neighbours rather than the blanket.
+/// The ladder is the reference order, checked at compile time. Gaps exceed 1e4, more than any
+/// view-z spread, except in the narrow windows (the decal band, the foam, the drift cloud), which
+/// are checked against their neighbours.
 const _: () = {
     assert!(SUN_DISC_BIAS - STARS_BIAS > 1.0e4);
     assert!(WHITE_MOON_BIAS > SUN_DISC_BIAS && MOON02_BIAS > WHITE_MOON_BIAS);
     assert!(CLOUDS_BIAS - MOON02_BIAS > 1.0e4);
-    // The water-plane interleave: sky < far-side transparents < water < world transparents (the
-    // near-side default). The far-side band is FAR_SIDE_BIAS − 8 (a zfill twin) … + owner rung;
-    // owner rungs are capped well under the 1e4 margin (benilla_formats::owner_last_rung's
-    // ceiling) and the mesh batch eps under that.
+    // sky < far-side transparents < water < near-side transparents; a far-side draw's own offsets
+    // (zfill −8, owner rung, batch eps) stay far under 1e4.
     assert!(FAR_SIDE_BIAS - CLOUDS_BIAS > 1.0e4);
     assert!(WATER_BIAS - FAR_SIDE_BIAS > 1.0e4);
-    assert!(-3.0e3 - WATER_BIAS > 1.0e4); // world view-z floor = −far (the ~3 km projection) stays above
-                                          // Foam sits in the water pass, over every liquid surface and under the near-side default,
-                                          // whatever the two draws' distances are (B348).
+    // −3e3 is the world view-z floor, −far.
+    assert!(-3.0e3 - WATER_BIAS > 1.0e4);
+    // Foam: over every liquid surface and under the near-side default, at any distance.
     assert!(FOAM_BIAS + WORLD_VIEW_Z_FLOOR - WATER_BIAS > 1.0e3);
     assert!(WORLD_VIEW_Z_FLOOR - FOAM_BIAS > 1.0e3);
     assert!(Rung::GROUND_FX - CLOUDS_BIAS > 1.0e4);
     assert!(GLARE_BIAS - Rung::GROUND_FX > 1.0e4);
     assert!(Rung::NAMEPLATE - GLARE_BIAS > 1.0e4);
-    // The drift cloud sits between the ground-fx decals and the glare — the reference's `0x483731`,
-    // the frame's last world draw. Its window is 1.18e4 wide, so like the decal band it is measured
-    // against its neighbours rather than the blanket: the margin only has to beat the view-z spread
-    // two anchors here can differ by, and the cloud's anchor IS the eye.
+    // The drift cloud's anchor is the eye, so its margin need only beat one far plane.
     assert!(Rung::DRIFT_CLOUD - Rung::GROUND_FX > -WORLD_VIEW_Z_FLOOR);
     assert!(GLARE_BIAS - Rung::DRIFT_CLOUD > -WORLD_VIEW_Z_FLOOR);
-    // The raster margins are their own axis (B131) — not comparable to the sort rungs above, only
-    // to zero and to each other. One number for every ground decal (1817); the foam is not one of
-    // them, and takes far less.
+    // The raster constants are their own axis, comparable only to zero and to each other.
     assert!(Rung::DECAL_RASTER > 0 && Rung::FOAM_RASTER < Rung::DECAL_RASTER);
-    // The foam's settle is deliberately the SMALL one: unlike a ground decal its patch is the
-    // liquid mesh's own triangles, so it has no bake residual to dominate (1811). It pulls toward
-    // the eye under reversed-Z, so it is positive; a negative here would push it INTO its receiver.
+    // Positive pulls toward the eye under reversed-Z; negative would push foam into its receiver.
     assert!(Rung::FOAM_RASTER > 0);
-    // The slope half stays disarmed on this lane (1811): its pull grows as z² and it spends the
-    // wet-lattice skirt onto the beach, while the tie it would settle is already won by the patch
-    // being the liquid mesh's own triangles. A nonzero value here is a decision, not a tune.
     assert!(Rung::FOAM_RASTER_SLOPE == 0.0);
 
-    // ─── The pre-water decal band (B347, 1785/1789) ─────────────────────────────────────────
-    // Internally ordered as the reference's frame emits them — ring then shadow, both from
-    // PHASE 1's node drain (`0x6812c5 call 0x683dd0`: the `+0x38` tick at `0x48160c`, then the
-    // shadow gate at `0x683ec3`) → footprints (`0x483654`) → the reticle's solid pass
-    // (`0x4836c5`) — with a step far wider than the view-z two *stacked* decals can differ by
-    // (they share a patch of ground, so their anchors are yards apart, not kilometres).
+    // ─── The pre-water decal band ─────────────────────────────────────────
+    // Ring, shadow, footprints, reticle, each step wider than two stacked decals' view-z spread.
     assert!(Rung::SHADOW_SORT - Rung::RING > 1.0e3);
     assert!(Rung::FOOTPRINT - Rung::SHADOW_SORT > 1.0e3);
     assert!(Rung::RETICLE - Rung::FOOTPRINT > 1.0e3);
-    // And below EVERY world transparent whatever its distance — the deepest being a far-side
-    // zfill twin (−8) out at the far plane. This is the assert B347 was missing: at the old
-    // positive rungs the band sat above the water and above every M2 transparent, and the shadow
-    // was the one thing in the scene the water did not attenuate.
+    // Below every world transparent at any distance: the deepest is a far-side zfill twin (−8).
     assert!(FAR_SIDE_BIAS - 8.0 + WORLD_VIEW_Z_FLOOR - Rung::RETICLE > 1.0e3);
-    // ...and above the WMO-skybox band whatever the decal's distance, so a building's painted sky
-    // can never sort over a decal (it is depth-forced to the far plane as well, but the ladder
-    // does not get to lean on a second mechanism to state its own order). Measured at the band's
-    // FLOOR, which is the ring's rung.
+    // Above the WMO-skybox band at any distance, measured from the band's floor, the ring.
     assert!(Rung::RING + WORLD_VIEW_Z_FLOOR - WMO_SKYBOX_BIAS > 1.0e3);
 };
 
-/// The depth law (module doc) is a property of the **shaders**, so it is checked there: the shared
-/// vertex stage must pin the far depth, every sky material must draw through it, and no sky
-/// fragment shader may take the depth back (a `frag_depth` write is the same number at the cost of
-/// the pipeline's early-Z — decision 2016). Without this, a shell radius silently becomes
-/// load-bearing again the moment someone edits one of them — the exact regression 0588 fixed, and
-/// one that only shows up at night, on a mountainous horizon, past 2.6 km.
+/// The depth law, in the shaders: the shared vertex stage pins the far depth (without it stars
+/// show through distant hills), every sky material draws through it, and no fragment rewrites it.
 #[test]
 fn the_sky_depth_is_pinned_at_the_vertex_and_nowhere_else() {
     use bevy::pbr::Material;
@@ -477,9 +185,8 @@ fn the_sky_depth_is_pinned_at_the_vertex_and_nowhere_else() {
         ("star.wgsl", include_str!("shaders/star.wgsl")),
         ("cloud.wgsl", include_str!("shaders/cloud.wgsl")),
         ("celestial.wgsl", include_str!("shaders/celestial.wgsl")),
-        // The WMO skybox is no longer a shader of its own: it draws on the shared model lane, whose
-        // `WOW_SKY_DEPTH` branch obeys the same law and is asserted beside it
-        // (`benilla_assets::materials`, `the_sky_lane_pins_the_far_depth_at_the_vertex`).
+        // The WMO skybox draws on the shared model lane, whose `WOW_SKY_DEPTH` branch is held to
+        // the same law in `benilla_assets::materials`.
     ] {
         assert!(
             !src.contains("@builtin(frag_depth)"),
diff --git a/crates/benilla-world/src/skybox.rs b/crates/benilla-world/src/skybox.rs
index e6410da6..d4995c09 100644
--- a/crates/benilla-world/src/skybox.rs
+++ b/crates/benilla-world/src/skybox.rs
@@ -1,96 +1,19 @@
-//! The **skybox** — an authored sky model that stands in for the `Light.dbc` gradient dome, drawn
-//! camera-anchored in the sky slice.
+//! The skybox: an authored sky M2 standing in for the `Light.dbc` gradient dome, drawn
+//! camera-anchored at the far depth ([`crate::sky_order`]) through the ordinary M2 material lane
+//! ([`M2BatchMaterials::skybox`]).
 //!
-//! **Two sources feed one lane, and the DBC source wins.** A *building* asks for its own painted sky
-//! (the **MOSB**/`0x40000` mechanism derived below); the *death profile* asks for the ghost sky
-//! (`LightSkybox.dbc` via `LightParams.lightSkyboxID`, [`benilla_formats::LightCatalog::ghost_skybox`]).
-//! The reference keeps these in separate slots — the WMO's is loop slot A, the DBC's is the single
-//! slot B — and slot B, whose weight is hardcoded `1.0` whenever it is filled, makes
-//! `0x6d4ac1`–`0x6d4acc` skip loop A entirely: **an active DBC skybox suppresses the WMO one
-//! outright** (byte-VERIFIED, wow-re `lighting/scratch/wmo-skybox.md` §3–4). Here that is one
-//! `Option` with the DBC source taken first, because a resolve that produced both would have to
-//! decide anyway and the binary has already decided.
+//! Two slots feed it. A WMO root names a model in MOSB, and the reference draws it when any group
+//! the portal flood reaches carries flag `0x40000` (`0x6b42e0` inside the flood `0x6b41c0`,
+//! published to `[0xca8080]`, read at `0x681282`). The ghost sky (`LightSkybox.dbc`) fills the DBC
+//! slot, whose weight 1.0 skips the WMO slot outright (`0x6d4ac1`–`0x6d4acc`), so it is taken
+//! first.
 //!
-//! A WMO root can name a skybox model in its **MOSB** chunk, and a group can ask for it with group
-//! flag **`0x40000`**. Both halves matter, and the flag is tested **on the groups the portal flood
-//! REACHES, never on the group the camera stands in** — `0x6b42e0` sits inside the flood `0x6b41c0`
-//! with `ebx` = the group being *visited*, seeded from the containment list on the inside leg and
-//! from every frustum-visible EXTERIOR group on the outside leg (`0x6b3dd0`), recursing through
-//! portals at `0x6b4639` and re-testing at each step. The predicate is therefore
-//! *"any flood-reached group carries the bit, and the root names a MOSB"*, published to `[0xca8080]`
-//! and read once at `0x681282`.
-//!
-//! **That distinction is load-bearing, and getting it wrong is what shipped first.** In Stratholme's
-//! King's Square the camera stands in group 39 — the root's *only* EXTERIOR (`0x8`) group, which does
-//! **not** set `0x40000`. A containing-group test draws no skybox there; the reference draws the
-//! painted red sky, because 61 of the 83 groups its flood reaches from group 39 do carry the bit.
-//! (Checked on the asset: a BFS over `Stratholme_B`'s MOPR reaches 82 of 83 groups from group 39.)
-//! The corpus correlation that seeded the first attempt — across all 815 roots the bit never appears
-//! without a MOSB, 0 counter-examples (`benilla-extract skyboxscan`) — was true and still is; it just
-//! never established *which* group the renderer tests, and it was over-read as if it had.
-//!
-//! Five roots exercise both halves: **`Stratholme_B`**, the burning city, and the four Caverns of
-//! Time shells — which are *not* out of reach in 1.12, whatever the instance portals do.
-//! `CavernsofTime.wmo` is placed in the live world at Kalimdor tile (39, 47), MODF `uniqueId`
-//! 398759, and standing in the crater at `.go xyz -8437.16 -4222.44 -211.58 1` the cull's down-ray
-//! seeds group 29 (`flags 0x42805` — `SHOW_SKYBOX` set) and this resolve fires. An earlier note here
-//! read "unreleased" as "unreachable" and concluded this branch never actually picks; the director
-//! walked into it.
-//!
-//! Four more roots name a skybox no group ever asks for (DireMaul's
-//! instance shell, `Stratholme_A`, and the two Sunken Temple roots — whose MOSB isn't even a model
-//! path, it's the string "the temple of atal'hakkar"), so keying off the chunk alone would still
-//! paint skies the reference never shows. This is why Stratholme's sky is red where the zone light
-//! says otherwise: map 329's only reachable `Light.dbc` atmosphere (global row 341 → `LightParams`
-//! 336) is a khaki-brown gradient with a near-black apex, and it is not what draws in there.
-//!
-//! **A skybox is an ordinary M2, and is drawn as one** (decision 1264). This lane used to have a
-//! private mesh builder and a private material — positions, UVs, one texture, everything opaque —
-//! which is a faithful drawing of `StratholmeSkybox.m2` (three opaque batches × 8 verts, one texture
-//! pair per axis, no animation) and of nothing else. `CavernsOfTimeSky.m2` is the counter-example the
-//! chain also ships: **21 batches across four blend modes** — a painted cube, six ADDITIVE star
-//! sheets on the cube's own faces, five alpha-blended planet cards, three alpha-tested asteroid belts
-//! on rotating bones. Drawn opaque, the star sheet — whose RGB is near-white and whose stars live in
-//! its ALPHA channel — paints a flat white sheet over the painted sky, and the planets and belts
-//! become dark cards. That is the director's *"the whole ceiling is white … some of the cool effects
-//! seem missing"* in Caverns of Time.
-//!
-//! So the batches go through [`crate::model_render`]'s material lane like every other model
-//! ([`M2BatchMaterials::skybox`]), which is where the blend law, the 224/255 alpha-key reference, the
-//! additive gamma premultiply and the authored batch order already live, byte-verified. Three things
-//! are the *sky's* and are set here, not read off the batch: the forced far depth, depth-write off,
-//! and depth-test on — the rationale is on `skybox()`.
-//!
-//! Occlusion is **not** the box's radius: like every sky element it forces the far depth (the law is
-//! in [`crate::sky_order`]), so the world paints over it and the shell is free to sit inside the
-//! room's own geometry.
-//!
-//! **The slot has a WEIGHT, and the weight is the 4-second crossfade.** The WMO slot is filled per
-//! frame as `0x6d4810(0, [0xca8080], [0xce9bdc])` — and `[0xce9bdc]` is the camera-in-WMO interior
-//! crossfade, THE same number the MFOG fog lerp rides (±0.25/s = `[0x8115b0]`, clamped [0,1];
-//! wow-re `wmo-skybox.md` §3: "the skybox alpha and the interior fog blend are the same number").
-//! A slot draws only at weight > 0 (`0x6d4afe`), with the weight multiplied into every batch's
-//! combined alpha (`0x710cb0` → `[CM2Model+0x180]`) — and a batch at `0 < A < 1` is promoted to
-//! SRC_ALPHA blending whatever its authored mode (`m2-blend-promotion-zfill.md`), so walking
-//! through Stratholme's gate alpha-blends the painted sky in over the still-standing celestial
-//! pass over 4 seconds, and back out on leaving. Here: [`crate::lighting::WmoCrossfade`] publishes
-//! the number, [`SkyboxWeight`] resolves the slot's weight from it (the DBC/ghost slot is
-//! hardcoded 1.0 — that pop is faithful), and [`apply_skybox_visibility`] applies it through the
-//! entity feather rails (`MeshTag` alpha + the promotion twin).
-//!
-//! **Scope — the skybox replaces the WHOLE celestial pass, not just the backdrop.** `CSky::Render`
-//! carries one shared boolean (`0x6d49cd` sets it, `0x6d49fb`/`0x6d4a2e` clear it once any slot's
-//! weight exceeds `[0x808aac]` = 0.99) and `0x6d4a3b test edi,edi; je` skips **all six** element
-//! draws together — stars, sun disc, both moons, gradient band and cloud dome. There is no
-//! per-element gating; below the 0.99 threshold — i.e. for all but the last 40 ms of the fade —
-//! the six elements still draw and the skybox blends over them ([`SkyboxWeight::replaces_celestial`]).
-//! Confirmed in a live GL capture of the reference standing in King's Square:
-//! the entire `[0.975, 0.98]` sky slice is three `count=12` draws (the cube's three texture pairs)
-//! and nothing else, identically in every frame. Only the **glare** quads survive — they render on
-//! their own later path (`0x483740 → 0x6d48c0 → 0x7e57e0`), outside this pass.
-//!
-//! What the atmosphere drives (fog colour and distance, ambient, diffuse) is still untouched: no byte
-//! law says the flag reaches it, and the reference fogs the world normally underneath the painted sky.
+//! The WMO slot's weight is the camera-in-WMO interior crossfade `[0xce9bdc]`
+//! (`0x6d4810(0, [0xca8080], [0xce9bdc])`), the number the MFOG fog lerp rides. Above
+//! `[0x808aac]` = 0.99 a slot replaces the whole celestial pass (`0x6d4a3b`): stars, sun disc,
+//! both moons, gradient band and cloud dome; below it they draw under the sky. The glare quads
+//! draw on their own path (`0x483740` → `0x6d48c0` → `0x7e57e0`), and the fog, ambient and
+//! diffuse are untouched.
 
 use std::collections::HashSet;
 
@@ -105,78 +28,43 @@ use benilla_assets::materials::WowModelMaterial;
 use benilla_assets::WmoModel;
 use benilla_assets::{LockRecover, WorldAssets};
 
-/// MOGP/MOGI group flag **SHOW_SKYBOX** — this group draws its root's MOSB model as the sky (see the
-/// module doc for how the bit was identified). Mirrored between the root's MOGI table and each group
-/// file's MOGP header; we read the MOGP copy the loader already keeps in `WmoGroupNav::flags`.
+/// The MOGP/MOGI group flag asking for the root's MOSB sky; the loader keeps the MOGP copy in
+/// `WmoGroupNav::flags`.
 const SHOW_SKYBOX: u32 = 0x40000;
 
-/// The skybox model the camera's room asks for this frame — `None` (the overwhelming default) means
-/// the [`crate::sky`] gradient dome is the backdrop. Resolved from [`CameraInteriorClaim`]: the same
-/// down-ray seed that already names the camera's room for the MFOG fog resolve.
+/// The skybox model this frame asks for; `None` leaves the [`crate::sky`] gradient dome.
 #[derive(Resource, Default, PartialEq, Eq)]
 pub struct CameraSkybox(pub Option<String>);
 
-/// The resolved skybox's slot WEIGHT this frame — the second half of the resolve, and the number
-/// that makes the sky *crossfade* instead of pop (the report this closes). Per the byte law
-/// (module header + wow-re `wmo-skybox.md` §3–5):
-///
-/// - the **WMO slot's** weight is `[0xce9bdc]`, the camera-in-WMO interior crossfade — THE same
-///   number the MFOG fog lerp rides ([`crate::lighting::WmoCrossfade`], ±0.25/s, a 4-second fade
-///   in and out). Engagement is the fog's own (claim + MFOG count > 1 + a true-interior
-///   containing group), so at Stratholme's gate the painted sky fades in over the celestial pass
-///   exactly as the storm veil fades out of the streets;
-/// - the **DBC/ghost slot's** weight is hardcoded `1.0` whenever it is filled (`0x6d2260`) — the
-///   ghost sky pops, faithfully;
-/// - `0.0` when no skybox resolves — including a skybox *named* by the flood while the crossfade
-///   sits at 0 (standing outside the city gate: the flood reaches flagged groups through the
-///   doorway and publishes the name, but the reference draws a slot only at weight > 0, so no
-///   painted sky shows until you are actually in).
-///
-/// Consumers: [`apply_skybox_visibility`] (draw gate `weight > 0` = `0x6d4afe`, and the per-batch
-/// alpha), and the celestial stand-down gates in [`crate::sky`], [`crate::sun`] and
-/// [`crate::clouds`] via [`Self::replaces_celestial`].
+/// The skybox slot's weight this frame: the interior crossfade [`crate::lighting::WmoCrossfade`]
+/// (±0.25/s, `[0x8115b0]`) for a WMO sky, 1.0 for the ghost sky (`0x6d2260`), and 0 when none
+/// resolves.
 #[derive(Resource, Default, PartialEq)]
 pub struct SkyboxWeight(pub f32);
 
 impl SkyboxWeight {
-    /// Does the skybox replace the whole celestial pass this frame? `weight > 0.99`
-    /// (`[0x808aac]`, tested at `0x6d49e8`/`0x6d4a1f`): below it the six celestial elements
-    /// still draw and the skybox alpha-blends OVER them — that compositing is the visible half
-    /// of the 4-second crossfade.
+    /// Whether the skybox replaces the whole celestial pass: weight above `[0x808aac]` = 0.99
+    /// (`0x6d49e8`/`0x6d4a1f`); below it the sky blends over the six elements.
     pub fn replaces_celestial(&self) -> bool {
         self.0 > 0.99
     }
 }
 
-/// Marks one batch of a built skybox model, tagged with the model path it belongs to (a session can
-/// walk through more than one skybox building, and the built entities are cached, not rebuilt).
+/// One batch of a built skybox model.
 #[derive(Component)]
 struct SkyboxPart {
     /// The skybox model path this batch belongs to.
     path: String,
-    /// The batch's authored-blend material — what it draws with at weight 1.0.
+    /// The batch's authored-blend material, drawn at weight 1.0.
     steady: Handle<WowModelMaterial>,
-    /// The blend-promotion twin for `0 < weight < 1` (`m2-blend-promotion-zfill.md`; equal to
-    /// `steady` for a batch whose authored mode already blends).
+    /// The blend-promotion twin for `0 < weight < 1` (`0x811fe0`); `steady` itself when the batch
+    /// already blends.
     fade_blend: Handle<WowModelMaterial>,
 }
 
-/// This batch **spins**: every one of its vertices is wholly weighted to one parentless
-/// rotation-only bone, so the authored motion is a rigid transform about that bone's pivot and needs
-/// no skinning palette at all ([`benilla_formats::BoneSpin`]).
-///
-/// That is the whole reason the belts can turn here rather than on the `M2Model` asset lane, which
-/// is what decision 1264 assumed this would cost. A rig would want joint entities under the anchor,
-/// and the anchor is written *post-propagation* ([`follow_camera`], decision 0504's same-frame
-/// camera pose) — so its children's globals would be a frame stale, and fixing that means either
-/// giving up the same-frame pose or hand-writing joint globals. A rigid batch sidesteps the whole
-/// question: there are no children.
-///
-/// **Population, measured** (`benilla-extract m2batch`/`m2bones`): `CavernsOfTimeSky.m2`'s four
-/// asteroid-belt batches, `[1@1.00]×38`, `[2@1.00]×38`, `[3@1.00]×38` and `[3@1.00]×28`, on three
-/// parentless bones keying rotation alone over one 66.667 s loop. The other 17 batches ride bone 0,
-/// which has no track, and `StratholmeSkybox.m2` has no animation at all — so this is the entire
-/// animated content of every skybox the chain ships.
+/// A batch wholly weighted to one parentless rotation-only bone, so it spins rigidly about the
+/// bone's pivot ([`benilla_formats::BoneSpin`]) with no joint children, which would lag the
+/// post-propagation anchor a frame. Only `CavernsOfTimeSky.m2`'s four asteroid belts spin.
 #[derive(Component)]
 struct SkyboxSpin {
     /// The bone's pivot, in the same (Bevy) space the batch's vertices were baked into.
@@ -184,27 +72,20 @@ struct SkyboxSpin {
     spin: benilla_formats::BoneSpin,
 }
 
-/// Which skybox paths have been built already — a build is a chain read + BLP decodes, so it happens
-/// once per path per session and the entities are then just shown/hidden. A path that FAILED to load
-/// is recorded here too: the retry would fail identically every frame, and the gradient dome is the
-/// correct thing to fall back to.
+/// Skybox paths built this session, failed loads included, so a failure is not retried per frame.
 #[derive(Resource, Default)]
 struct BuiltSkyboxes(HashSet<String>);
 
-/// Ordering handle: [`CameraSkybox`] is settled for the frame after this set. `crate::sky`'s dome
-/// gate hangs off it, because the two backdrops must agree *within* a frame — one reading a stale
-/// resource is a frame with both drawn or neither.
+/// [`CameraSkybox`] is settled after this set; the dome's gate runs after it, so the two backdrops
+/// agree within a frame.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub(crate) struct SkyboxResolve;
 
-/// The WMO-skybox subsystem: resolve which model the camera's room wants, build it on first need,
-/// then show exactly that one and pin it to the camera.
+/// Resolves the wanted skybox, builds it on first need, shows it and pins it to the camera.
 pub(crate) struct SkyboxPlugin;
 
 impl Plugin for SkyboxPlugin {
     fn build(&self, app: &mut App) {
-        // No `MaterialPlugin` of its own any more: a skybox batch is a `WowModelMaterial` like every
-        // other model batch, and that plugin is already loaded.
         app.init_resource::<CameraSkybox>()
             .init_resource::<SkyboxWeight>()
             .init_resource::<BuiltSkyboxes>()
@@ -212,19 +93,14 @@ impl Plugin for SkyboxPlugin {
                 Update,
                 (resolve_camera_skybox, build_skybox, apply_skybox_visibility)
                     .chain()
-                    // The claim we read is written by the PVS pass in this same schedule. Unordered,
-                    // this reads whichever side of it the executor happened to pick — so a camera
-                    // move that changes rooms lands a frame late, or not at all on the frame it
-                    // matters, and the backdrop flickers between the painted sky and the gradient.
+                    // After the PVS pass, whose flood this reads the same frame.
                     .after(crate::wmo_portal::WmoPvsSet)
-                    // …and the slot weight is this frame's crossfade `t`, advanced by the lighting
-                    // resolve — a stale read here is a frame where the sky's alpha and the interior
-                    // fog disagree about how far into the building the camera is.
+                    // After the lighting resolve, so the weight is this frame's crossfade, as the
+                    // fog's is.
                     .after(crate::lighting::LightingResolveSet)
                     .in_set(SkyboxResolve),
             )
-            // Camera-anchored placement runs post-propagation off the SAME-frame camera pose — the
-            // slot decision 0504 moved every camera-anchored shell into.
+            // Camera-anchored placement runs after propagation, off this frame's camera pose.
             .add_systems(
                 PostUpdate,
                 follow_camera.in_set(crate::billboard::BillboardPlace),
@@ -232,20 +108,9 @@ impl Plugin for SkyboxPlugin {
     }
 }
 
-/// Which skybox does this frame ask for? **The flag is tested on the groups the portal flood
-/// REACHES, never on the group the camera stands in** (`0x6b42e0`, inside the flood `0x6b41c0`, with
-/// `ebx` = the group being visited). So the predicate is: *does any group in this placement's PVS
-/// carry `SHOW_SKYBOX`, and does its root name a MOSB?*
-///
-/// That distinction is the whole bug this replaced. Reading the **containing** group instead is
-/// wrong at Stratholme's King's Square: the BSP containment there is group 39, the root's only
-/// EXTERIOR (`0x8`) group, which does not set `SHOW_SKYBOX` — yet the reference draws the painted
-/// sky, because 61 of the 83 groups the flood reaches from group 39 do carry the bit. (Verified on
-/// the asset: BFS over `Stratholme_B`'s MOPR reaches 82 of 83 groups from group 39, 61 of them
-/// flagged.) The camera's down-ray CLAIM is a different resolver and is *not* cleared there — at
-/// the reported spot it seeds the street group g08 (`0x42805`, a true interior; pin-probed
-/// 2026-09-01, decision 1827) — which is what lets the crossfade weight engage in the square while
-/// the skybox *name* comes from the flood predicate above.
+/// Resolve the wanted skybox and its weight. A WMO sky needs a group of the placement's flood PVS,
+/// not the camera's own group, to carry [`SHOW_SKYBOX`] (`0x6b42e0`, `ebx` the group visited) and
+/// its root to name a MOSB; the weight rides the down-ray claim's crossfade, a separate resolver.
 fn resolve_camera_skybox(
     instances: Query<&crate::wmo_portal::WmoPortalInstance>,
     wmos: Res<Assets<WmoModel>>,
@@ -257,13 +122,8 @@ fn resolve_camera_skybox(
     mut want: ResMut<CameraSkybox>,
     mut weight: ResMut<SkyboxWeight>,
 ) {
-    // **The ghost sky first — it wins outright.** Slot B is filled at weight 1.0 and that makes the
-    // reference skip loop A entirely (module header, wow-re §3–4), so a dead player under
-    // Stratholme's painted sky sees DeathClouds, not the building's.
-    //
-    // Resolved from the SAME (map, camera position) seed the atmosphere uses, so the sky and the
-    // fog it hangs over come from one zone row. The ghost bit is `PLAYER_FLAGS` bit 0x10 — the same
-    // one `lighting::resolve` reads to select param slot 4 — so the two switch on the same frame.
+    // The ghost sky first, as its slot skips the WMO one. Resolved from the atmosphere's map and
+    // camera position, off the same ghost flag (`PLAYER_FLAGS` 0x10), so the two switch together.
     if viewer.ghost {
         let ghost_sky = sampler.as_ref().and_then(|s| {
             let pos = bevy_to_wow(cam.single().ok()?.translation());
@@ -274,34 +134,26 @@ fn resolve_camera_skybox(
             if want.0.as_deref() != Some(sky) {
                 want.0 = Some(sky.to_owned());
             }
-            // Slot B's weight is hardcoded 1.0 whenever it is filled (`0x6d26cb`/`0x6d26d0`):
-            // the ghost sky pops in whole, and — being > 0.99 — replaces the celestial pass on
-            // the same frame the death atmosphere lands.
+            // The DBC slot's weight is 1.0 whenever filled (`0x6d26cb`/`0x6d26d0`): it pops in.
             weight.set_if_neq(SkyboxWeight(1.0));
             return;
         }
     }
-    // `min()` rather than "first match": `Query` iteration order is not stable across frames, and a
-    // tie would otherwise alternate two backdrops frame to frame. Five roots qualify — Stratholme_B
-    // and the four Caverns of Time shells — and the tie-break is live code, not a formality: the
-    // note that used to sit here read "unreleased" as "unreachable" and concluded this can never
-    // pick twice. `CavernsofTime.wmo` is placed in the live world (decision 1264, and the module
-    // header above); two of its shells overlapping the camera is exactly the case `min()` settles.
+    // `min()`, not the first match: query order is unstable across frames, and two overlapping
+    // Caverns of Time shells both qualify.
     let resolved = instances
         .iter()
         .filter_map(|inst| {
             let model = wmos.get(&inst.handle)?;
-            // The MOSB test comes first and exits ~every instance in one deref: 810 of the chain's
-            // 815 roots name no skybox, so the group scan below is effectively never reached.
+            // The MOSB test first: 810 of the game's 815 WMO roots name no skybox.
             let sky = model.skybox.as_deref()?;
             model
                 .group_nav
                 .iter()
                 .enumerate()
                 .any(|(i, nav)| {
-                    // NOT the fail-open `unwrap_or(true)` the rest of the cull takes
-                    // ([`WmoGroupVis::drawn_by`]): there a lookup miss must never blank a building,
-                    // whereas here it would paint a full-screen sky over the entire world.
+                    // Fail closed, unlike the cull: a lookup miss here would paint a sky over the
+                    // whole world.
                     nav.flags & SHOW_SKYBOX != 0 && inst.visible.get(i).copied().unwrap_or(false)
                 })
                 .then(|| sky.to_owned())
@@ -310,20 +162,15 @@ fn resolve_camera_skybox(
     if want.0 != resolved {
         want.0 = resolved;
     }
-    // The WMO slot draws at the interior crossfade's weight — `[0xce9bdc]`, the SAME number the
-    // MFOG fog lerp rides — and at 0.0 when nothing resolved. A resolved name at weight 0 is a
-    // real state (the flood publishes through a doorway the camera hasn't walked into), and it is
-    // exactly the reference's: the slot is filled, and `0x6d4afe` declines to draw it.
+    // The WMO slot's weight is the interior crossfade `[0xce9bdc]`; a name seen through a doorway
+    // at weight 0 fills the slot, which `0x6d4afe` declines to draw.
     weight.set_if_neq(SkyboxWeight(match want.0 {
         Some(_) => crossfade.t(),
         None => 0.0,
     }));
 }
 
-/// Build the wanted skybox's entities the first time it is asked for. The models are small (3 batches
-/// for Stratholme, 21 for Caverns of Time) and there are five in the whole game, so a built one is
-/// kept for the session rather than torn down on leaving the room — walking in and out of
-/// Stratholme's gate must not re-decode art.
+/// Build the wanted skybox on first request; the models are small and few, so it stays built.
 fn build_skybox(
     mut commands: Commands,
     want: Res<CameraSkybox>,
@@ -339,18 +186,14 @@ fn build_skybox(
     if built.0.contains(path) {
         return;
     }
-    // The shared light buffer is created in the render world's shadow at startup; a build that ran
-    // before it would bake materials against nothing. Retry — and do NOT latch `built` here, or the
-    // first frame in the room would permanently give up on the sky.
+    // Before the shared light buffer exists: retry, without latching `built`.
     if !mats.ready() {
         return;
     }
     let Some(mut world_assets) = world_assets else {
-        return; // assetless dev run — the gradient dome stays the backdrop
+        return; // assetless run: the gradient dome stays the backdrop
     };
-    // The model's rigid spins, keyed by bone — empty for `StratholmeSkybox` and for a capture
-    // (`deterministic_run`), which keeps every animated lane on its bind pose so world baselines stay
-    // comparable across runs and branches, exactly as the doodad host's own arm does.
+    // The model's rigid spins by bone; none under a deterministic run, which keeps bind poses.
     let spins = if crate::dev_state::deterministic_run() {
         Default::default()
     } else {
@@ -382,9 +225,7 @@ fn build_skybox(
             .map(|p| wow_to_bevy(*p).to_array())
             .collect();
         mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, positions);
-        // The model lane's vertex stage declares `world_normal` unconditionally and fills it under
-        // `VERTEX_NORMALS`; the sky is unlit and never reads it, but the attribute has to be there
-        // for the layout the shared shader was compiled against.
+        // Unread by the unlit sky, but the shared shader's vertex layout needs it.
         mesh.insert_attribute(
             Mesh::ATTRIBUTE_NORMAL,
             sub.normals
@@ -394,15 +235,12 @@ fn build_skybox(
         );
         mesh.insert_attribute(Mesh::ATTRIBUTE_UV_0, sub.uvs.clone());
         mesh.insert_indices(Indices::U32(sub.indices.clone()));
-        // The batch's own authored address mode (decision 0763) — a skybox's UVs sit inside 0..1 for
-        // the cube faces, but Caverns of Time's asteroid belts tile theirs over ±21 wraps.
+        // The batch's authored address mode: Caverns of Time's belts wrap their UVs.
         let texture = sub
             .texture
             .as_deref()
             .and_then(|t| world_assets.texture(t, (sub.wrap_x, sub.wrap_y), &mut images));
-        // `i + 1` is the authored-batch-order convention (`0` = unordered): the transparent half of
-        // a skybox is camera-anchored, so every one of its batches shares a sort distance and the
-        // order is the only thing keeping the layers from re-flipping every frame.
+        // `i + 1`, the authored batch order (0 is unordered): every batch shares one sort distance.
         let Some(pair) = mats.skybox(sub, texture, u16::try_from(i + 1).unwrap_or(0)) else {
             return; // light buffer vanished mid-build; `built` is unlatched, so we retry
         };
@@ -412,9 +250,7 @@ fn build_skybox(
                 MeshMaterial3d(pair.steady.clone()),
                 Transform::default(),
                 Visibility::Hidden, // `apply_skybox_visibility` turns on exactly the wanted one
-                // The per-instance alpha the crossfade writes (bits 0..=5, the one field this
-                // population uses — no rig, no shade/probe, no flags; `apply_skybox_visibility`
-                // is its sole writer).
+                // The crossfade's alpha (bits 0..=5), written only by `apply_skybox_visibility`.
                 MeshTag(crate::mesh_tag::spawn_tag(0, 1.0)),
                 SkyboxPart {
                     path: path.to_string(),
@@ -433,13 +269,8 @@ fn build_skybox(
     built.0.insert(path.to_string());
 }
 
-/// The bone this batch is **wholly** weighted to, if any — the caller's half of
-/// [`benilla_formats::BoneSpin`]'s rigid-body condition, and the one half the bone table cannot
-/// answer: a vertex split between this bone and another is half a rigid body's worth of motion,
-/// which no single transform can produce.
-///
-/// `None` for a batch with no skin binding at all (every WMO batch, and any loader that didn't fill
-/// it) — the conservative answer, since an unweighted batch has nothing to spin about.
+/// The bone every vertex of this batch is wholly weighted to, if any: the batch's half of
+/// [`benilla_formats::BoneSpin`]'s rigid condition.
 fn sole_bone(sub: &benilla_formats::RenderSubmesh) -> Option<u16> {
     let bone = sub.joints.first()?[0];
     (sub.weights.len() == sub.joints.len()
@@ -447,25 +278,15 @@ fn sole_bone(sub: &benilla_formats::RenderSubmesh) -> Option<u16> {
             .joints
             .iter()
             .zip(&sub.weights)
-            // `> 0.999` rather than `== 1.0`: the weights are the file's 0..255 bytes normalised by
-            // their sum, so a wholly-bound vertex is exactly 1.0 today — but an equality test on a
-            // divided float is the kind of thing that silently stops matching.
+            // Not `== 1.0`: the weights are bytes normalised by their sum.
             .all(|(j, w)| j[0] == bone && w[0] > 0.999))
     .then_some(bone)
 }
 
-/// Show the wanted skybox's batches at this frame's slot weight and hide every other built one —
-/// the draw half of the 4-second crossfade. This is the sole `Visibility`, material and `MeshTag`
-/// writer for these entities (the gradient dome's own gate lives in [`crate::sky`], which reads
-/// [`SkyboxWeight`] — one authority per entity class, decision 0025).
-///
-/// Per slot the reference draws only at weight > 0 (`0x6d4afe fcomp 0.0`), with the weight
-/// multiplied into every batch's combined alpha (`0x710cb0` → `[CM2Model+0x180]`,
-/// `m2-alpha-combine-cull.md`) — and a batch at `0 < A < 1` is PROMOTED to
-/// SRC_ALPHA/INV_SRC_ALPHA blending whatever its authored mode (`m2-blend-promotion-zfill.md`),
-/// which is what lets an opaque painted cube fade. Here that is: weight ≤ 0 ⇒ hidden; weight < 1
-/// ⇒ the blend-promotion twin + the weight in the `MeshTag` alpha field (the same rails every
-/// entity feather rides); weight ≥ 1 ⇒ the steady authored material, alpha field full.
+/// Show the wanted skybox at the slot weight and hide every other, the sole `Visibility`, material
+/// and `MeshTag` writer for these entities. As the reference: hidden at weight 0 (`0x6d4afe`), the
+/// weight in every batch's alpha (`0x710cb0` → `[CM2Model+0x180]`), and below 1 the batch
+/// promoted to SRC_ALPHA blending whatever its mode (`0x811fe0`).
 fn apply_skybox_visibility(
     want: Res<CameraSkybox>,
     weight: Res<SkyboxWeight>,
@@ -504,38 +325,11 @@ fn apply_skybox_visibility(
     }
 }
 
-/// Pin the box to the camera, world-aligned (identity rotation) so the painted sky stays fixed to the
-/// world horizon however the camera turns — the same treatment [`crate::sky::follow_camera`] gives the
-/// gradient dome, minus its far-plane scaling.
-///
-/// The art is drawn at **authored scale** and that is deliberate. Every other shell here scales to a
-/// fraction of the far plane, but those radii were only ever standing in for occlusion, and the forced
-/// far depth ([`crate::sky_order`], "The depth law") retired that job. Scale is genuinely free here:
-/// the eye's offset inside the box scales with the box, so the *angles* the faces subtend — which is
-/// all a camera-anchored backdrop can show — are scale-invariant.
-///
-/// **The ANCHOR POINT is not free — and it is the model's ORIGIN, VERIFIED.** `CM2Model+0xbc` stays
-/// identity and `0x707680` is called with a **zeroed** recentre vector (`0x6d4b3a`–`0x6d4b48`) where
-/// the world M2 scene gets the live camera position — so the model's local origin sits exactly at the
-/// eye, with camera rotation and zero translation. (The capture agrees: the skybox's matrix is
-/// orthonormal with translation `(0,0,0)` while the very next model's carries a real offset.)
-///
-/// It matters because `StratholmeSkybox` is *not* centred on its origin: its 52.87 yd cube sits at
-/// z ∈ [−14.67, +38.20], leaving the eye 11.76 yd BELOW the box's centre. That asymmetry is authored,
-/// not incidental — the near-black ±Z pair covers only a **34.7°** cone about the zenith rather than
-/// a symmetric 45°, and the side pairs' painted horizon lands three-quarters down their gradient
-/// (v ≈ 0.72). Re-centring the box on the eye would be a visible change and a wrong one.
-/// A spinning batch ([`SkyboxSpin`]) composes its bone's rotation about the bone's own pivot INSIDE
-/// the anchor: `T(eye) · T(pivot) · R(t) · T(−pivot)`, which closes to the rotation itself plus the
-/// translation below. The pivot conjugation is not decoration — Caverns of Time's belt bones pivot
-/// ~3 yd off the model origin, and the eye sits AT that origin ~20 yd from the belt, so dropping it
-/// swings the whole ring through several degrees instead of turning it in place.
-///
-/// The clock is the scene's own elapsed time, wrapped by the sequence. **The phase origin is not
-/// byte-pinned** — the reference arms the model at load and samples a shared clock, so its phase is
-/// whatever the room's load moment was — and for a 66.7 s loop of an asteroid ring with no start
-/// event, phase is unobservable. Captures never reach here at all (the spin component is not
-/// attached under a deterministic run), so no golden frame depends on it.
+/// Pin the box to the camera, world-aligned and at authored scale, the model's origin at the eye as
+/// the reference places it (`0x707680` given a zeroed recentre vector, `0x6d4b3a`–`0x6d4b48`):
+/// `StratholmeSkybox` is authored off-centre, so recentring it would be wrong. A spinning batch
+/// turns about its bone's pivot inside the anchor, `T(eye) · T(pivot) · R(t) · T(−pivot)`, on the
+/// scene clock; the reference's phase starts at load, which a 66.7 s ring does not show.
 #[allow(clippy::type_complexity)]
 fn follow_camera(
     time: Res<Time>,
@@ -560,7 +354,7 @@ fn follow_camera(
         tf.translation = cam_gt.translation() + pivot - rot * pivot;
         tf.rotation = rot;
         tf.scale = Vec3::ONE;
-        // Propagation already ran this frame — the direct global write is what renders.
+        // Propagation already ran this frame: the direct global write is what renders.
         *gt = GlobalTransform::from(*tf);
     }
 }
@@ -569,14 +363,7 @@ fn follow_camera(
 mod tests {
     use super::*;
 
-    /// The renderer's half of the rigid-spin predicate, on the real art: exactly the four
-    /// asteroid-belt batches resolve to a bone the collector spins, and the other seventeen resolve
-    /// to bone 0 — which is *weighted* wholly, and simply has no track.
-    ///
-    /// The distinction matters and is why this asserts both columns. `sole_bone` returning `Some(0)`
-    /// for the painted cube is correct and harmless; it is the SPIN lookup that must come back empty
-    /// for it. A test that only checked "four parts spin" would pass just as well if the predicate
-    /// were selecting the wrong four.
+    /// On the real art: the seventeen other batches are wholly on bone 0, which has no track.
     #[test]
     fn only_the_belt_batches_of_the_caverns_sky_resolve_to_a_spinning_bone() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -587,8 +374,7 @@ mod tests {
 
         let bones: Vec<Option<u16>> = subs.iter().map(sole_bone).collect();
         assert_eq!(bones.len(), 21, "21 authored batches");
-        // Batches 5..=8 are the belts (`m2batch`: `[1@1.00]×38`, `[2@1.00]×38`, `[3@1.00]×38`,
-        // `[3@1.00]×28`); every other batch rides bone 0.
+        // Batches 5..=8 are the belts (`benilla-extract m2batch`); every other rides bone 0.
         assert_eq!(
             &bones[5..=8],
             &[Some(1), Some(2), Some(3), Some(3)],
diff --git a/crates/benilla-world/src/static_gx/bake.rs b/crates/benilla-world/src/static_gx/bake.rs
index 0eda072c..d4fe063a 100644
--- a/crates/benilla-world/src/static_gx/bake.rs
+++ b/crates/benilla-world/src/static_gx/bake.rs
@@ -1,7 +1,5 @@
-//! The bake half of the retained pass (split from `mod.rs` at the 1,000-line budget): the
-//! flush walks dirty-and-quiet cells/regions and [`bake_cell`] turns their items into one
-//! recentred mesh + per-item draw list. The f64 position leg's rationale lives on the
-//! function.
+//! The retained pass's bake: the flush turns each dirty, quiet cell or region into one recentred
+//! mesh and a per-item draw list ([`bake_cell`]).
 
 use benilla_assets::coords::wow_to_bevy;
 use bevy::asset::RenderAssetUsages;
@@ -18,20 +16,8 @@ use super::{
     WORD_SHADE_LIT, WORD_TEXTURED, WORD_UNLIT, WORD_WINDOW, WORD_WMO, WORD_WRAP_X, WORD_WRAP_Y,
 };
 
-/// The declined-batch census (`declined`), printed once a streaming burst SETTLES rather than on
-/// every count change.
-///
-/// Two things were wrong with printing on change. It fires from a `PostUpdate` system that runs
-/// every frame, so a zone streaming in emitted a near-identical INFO line per frame — a Goldshire
-/// login produced ten, climbing 8 → 1630, which reads like a fault rather than a residency count.
-/// And the line named only refusals, so it could not be told apart from a dead pass; `accepted` is
-/// now beside them (at Goldshire the refusals sit against a five-digit accepted population, which
-/// is the fact the line was missing).
-///
-/// The grain is the honest one for a running total: hold until the counts have not moved for
-/// [`CENSUS_SETTLE_FRAMES`], then print the total once — with [`CENSUS_MAX_HOLD_FRAMES`] as the
-/// ceiling, so a stream that never goes quiet (a long flight path) still reports instead of
-/// trading one silence for another.
+/// Print the declined-batch census, beside the accepted count, once the counts have sat still for
+/// [`CENSUS_SETTLE_FRAMES`], or after [`CENSUS_MAX_HOLD_FRAMES`] if they never do.
 fn census_declines(gx: &mut StaticGx, frame: u32) {
     if gx.declined == gx.declined_logged {
         return;
@@ -55,12 +41,10 @@ fn census_declines(gx: &mut StaticGx, frame: u32) {
     gx.declined_logged = d;
 }
 
-/// How long the decline counts must sit still before the census prints — ~1 s at 60 fps, which is
-/// shorter than a streaming burst and longer than the gaps inside one.
+/// Frames the counts sit still before the census prints (~1 s), longer than a burst's gaps.
 const CENSUS_SETTLE_FRAMES: u32 = 60;
 
-/// The ceiling on that hold — ~10 s at 60 fps. Counts that never settle (a flight path streaming
-/// continuously) report on this instead, so the throttle can never turn the census silent.
+/// The ceiling on that hold (~10 s), so counts that never settle, as on a flight path, still print.
 const CENSUS_MAX_HOLD_FRAMES: u32 = 600;
 
 /// Bake dirty-and-quiet cells into retained draw data; publish into [`render::GxWorld`].
@@ -69,8 +53,7 @@ pub(super) fn flush_static_gx(mut gx: ResMut<StaticGx>, mut meshes: ResMut<Asset
     gx.frame = gx.frame.wrapping_add(1);
     let frame = gx.frame;
     census_declines(&mut gx, frame);
-    // The reveal gate's "publish what you have" (see [`StaticGx::flush_now`]): consumed here, so
-    // one request bakes one flush's worth of dirty regions and the windows resume next frame.
+    // A `StaticGx::flush_now` request bakes one flush's worth; the windows resume next frame.
     let now = std::mem::take(&mut gx.flush_now);
     let StaticGx {
         cells,
@@ -88,9 +71,7 @@ pub(super) fn flush_static_gx(mut gx: ResMut<StaticGx>, mut meshes: ResMut<Asset
             world.cells.remove(&cell);
             continue;
         }
-        // Sort for render-side run coalescing: same bucket + same texture ⇒ adjacent, so the
-        // node draws one range per run instead of one per item (class-aware baking is a B2
-        // refinement — dims/format live render-side only).
+        // Sorted by (bucket, texture) so the node draws one range per run, not one per item.
         state
             .items
             .sort_by_key(|i| ((u8::from(i.cutout) << 1) | u8::from(i.two_sided), i.texture));
@@ -114,9 +95,7 @@ pub(super) fn flush_static_gx(mut gx: ResMut<StaticGx>, mut meshes: ResMut<Asset
             world.wmos.remove(&instance);
             continue;
         }
-        // The WMO sort adds the GROUP inside (bucket, texture): a run must be group-
-        // homogeneous — the flood selects ranges per group — and same-texture groups still
-        // sit adjacent so the coalescer fuses across items within one group.
+        // The group joins the key: the PVS selects per group, so a run must not cross one.
         state.items.sort_by_key(|i| {
             (
                 (u8::from(i.cutout) << 1) | u8::from(i.two_sided),
@@ -133,9 +112,7 @@ pub(super) fn flush_static_gx(mut gx: ResMut<StaticGx>, mut meshes: ResMut<Asset
         );
         world.wmos.insert(instance, std::sync::Arc::new(baked));
     }
-    // The prop regions (B4): the WMO loop's shape with the referrer SET as the selection
-    // grain — the sort keeps runs set-homogeneous, and the published draw carries the
-    // region's set list beside the per-set bounds `bake_cell` accumulated into `groups`.
+    // Prop regions: the referrer set is the selection key, and the draw carries the set list.
     for (&instance, state) in props.iter_mut() {
         if !bake_due(state, world.props.contains_key(&instance), frame, now) {
             continue;
@@ -164,14 +141,8 @@ pub(super) fn flush_static_gx(mut gx: ResMut<StaticGx>, mut meshes: ResMut<Asset
     }
 }
 
-/// Is this region's bake due? `now` is the reveal gate's request ([`StaticGx::flush_now`]) and
-/// overrides every window — the arrival burst it batches is known to be over.
-///
-/// Otherwise: a FIRST bake waits only the short window (fast appearance); a
-/// re-bake of a published region waits for the LONG quiet window (B3, decision 1432 — the
-/// admission trickle arrives spaced wider than the short window, so B2 re-baked cells once
-/// per arrival for minutes; 1431's cost map priced it), with the age cap so a never-quiet
-/// region still consolidates.
+/// Whether a dirty region bakes now: after the short quiet window first, the long one once
+/// published, at the age cap, or on `now` ([`StaticGx::flush_now`]).
 fn bake_due(state: &super::GxCell, published: bool, frame: u32, now: bool) -> bool {
     if !state.dirty {
         return false;
@@ -188,10 +159,8 @@ fn bake_due(state: &super::GxCell, published: bool, frame: u32, now: bool) -> bo
         || frame.wrapping_sub(state.dirty_since) >= MAX_DIRTY_FRAMES
 }
 
-/// B2 (1431): the bake reassigns item indices — remap each fader placement's kill targets
-/// to the post-sort order and mark the published bitmap stale. The scan runs right after
-/// the flush in the same chain, so the rebuilt bitmap rides the SAME frame's publish: a
-/// cell never draws with bits from a previous bake's indices.
+/// Remap each fader's kill targets to the post-sort item order and mark the bitmap stale. The
+/// scan runs next in the same chain, so no frame draws with a previous bake's indices.
 fn remap_fader_items(state: &mut super::GxCell) {
     if state.faders.is_empty() {
         return;
@@ -210,20 +179,11 @@ fn remap_fader_items(state: &mut super::GxCell) {
     state.bits_stale = true;
 }
 
-/// Build one cell's (or WMO region's) mesh (recentred — 0974's precision split; the node
-/// pushes the origin) and its per-item draw list, plus per-GROUP bounds for a WMO region
-/// (the cull's per-group admission tests them; empty for cells).
+/// Bake one cell's or region's recentred mesh, per-item draws and per-selection-key bounds.
 fn bake_cell(items: &[GxItem], meshes: &mut Assets<Mesh>) -> render::GxCellDraw {
     use bevy::math::DVec3;
-    // World positions accumulate in f64 and round to f32 only AFTER recentring. Baking
-    // `transform_point` in f32 quantized every vertex to the ULP of its ±9,000-yd world
-    // coordinate (~0.0005 yd) BEFORE the recentre could save it — 0974's exact defect,
-    // reintroduced at bake time. Indoors a pixel spans ~0.001 yd, so that was a half-pixel
-    // shift of every interpolant: the inn A/B's ±1/255 film over 800k pixels, while the
-    // tram — a map whose placements sit near the origin — matched at exactly 0. In f64 the
-    // 9,000-magnitude intermediate is exact to ~1e-12 and the subtraction hands the f32
-    // vertex only its SMALL recentred value; what remains against the entity path is the
-    // GPU's own rotate-at-local-magnitude rounding, which no bake can undercut.
+    // World positions stay f64 until recentred: an f32 coordinate near 9,000 yd rounds by up to
+    // ~0.0005 yd, half an indoor pixel, which would shift every interpolant.
     let mut positions64: Vec<DVec3> = Vec::new();
     let mut normals: Vec<[f32; 3]> = Vec::new();
     let mut uvs: Vec<[f32; 2]> = Vec::new();
@@ -233,14 +193,11 @@ fn bake_cell(items: &[GxItem], meshes: &mut Assets<Mesh>) -> render::GxCellDraw
     let mut indices: Vec<u32> = Vec::new();
     let mut draws: Vec<render::GxItemDraw> = Vec::new();
     let (mut mn, mut mx) = (DVec3::splat(f64::MAX), DVec3::splat(f64::MIN));
-    // Per-group world bounds (WMO regions): group index → (min, max).
     let mut group_bounds: Vec<(u16, DVec3, DVec3)> = Vec::new();
     for (item_idx, item) in items.iter().enumerate() {
         let sub = &item.geometry;
         let base = u32::try_from(positions64.len()).expect("gx cell under u32 vertices");
-        // Low 16 bits: the ITEM index — the render side's record table resolves it to a
-        // texture-array layer (+ the WMO per-item record; dims/format are render-side
-        // knowledge — see render.rs).
+        // Low 16 bits: the item index, which the render side's record table maps to a layer.
         let has_vc = sub.vertex_colors.len() == sub.positions.len();
         let word_flags = u32::try_from(item_idx).expect("gx cell under u16 items")
             | (u32::from(item.wrap_x) * WORD_WRAP_X)
@@ -251,10 +208,8 @@ fn bake_cell(items: &[GxItem], meshes: &mut Assets<Mesh>) -> render::GxCellDraw
             | (u32::from(item.matte) * WORD_MATTE)
             | (u32::from(item.texture.is_some()) * WORD_TEXTURED)
             | (u32::from(has_vc) * WORD_HAS_VC)
-            // An interior PROP is WORD_INTERIOR with WORD_WMO clear (B4) — the entity
-            // shader's own `interior_prop = flags.z && !flags.x` split. A slot-less prop
-            // (exterior, or probe-table overflow) keeps the exterior law, like the entity
-            // path's fallback.
+            // An interior prop is WORD_INTERIOR without WORD_WMO; a slot-less prop keeps the
+            // exterior law, as on the entity path.
             | item.prop.as_ref().map_or(0, |p| {
                 u32::from(p.slot.is_some()) * WORD_INTERIOR
             })
@@ -267,10 +222,8 @@ fn bake_cell(items: &[GxItem], meshes: &mut Assets<Mesh>) -> render::GxCellDraw
             });
         let anchor = item.transform.translation;
         let rot = item.transform.rotation;
-        // Position/normal baking mirrors the placement transform's algebra (scale, rotate,
-        // translate) with the position leg in f64 (see the header note); the normal rides
-        // rotation alone (uniform placement scale preserves direction), authored zero
-        // normals kept zero for the shader's `wow_normalize` DC collapse (1268).
+        // Scale, rotate, translate, as the placement transform does. Normals take the rotation
+        // alone (placement scale is uniform); a zero normal stays zero for `wow_normalize`.
         let rot64 = rot.as_dquat();
         let scale64 = item.transform.scale.as_dvec3();
         let t64 = item.transform.translation.as_dvec3();
@@ -290,21 +243,16 @@ fn bake_cell(items: &[GxItem], meshes: &mut Assets<Mesh>) -> render::GxCellDraw
             };
             normals.push(n.to_array());
             uvs.push(*sub.uvs.get(vi).unwrap_or(&[0.0, 0.0]));
-            // MOCV / the baked constant tint, exactly as the entity mesh carries
-            // ATTRIBUTE_COLOR (`model.rs` inserts `vertex_colors` raw); white where the batch
-            // authors none — bit-identical through every lane by the WORD_HAS_VC contract.
+            // MOCV or the baked constant tint, raw as on the entity mesh; white where none.
             colors.push(if has_vc {
                 sub.vertex_colors[vi]
             } else {
                 [1.0, 1.0, 1.0, 1.0]
             });
-            words.push(word_flags); // layer bits 0..16 resolve render-side (dims live there)
+            words.push(word_flags);
             anchors.push(anchor.to_array());
         }
-        // The selection grain: a WMO item's GROUP, a prop item's referrer SET (B4) — one
-        // field, because the node's range selection is the same mechanism for both (the
-        // per-frame bit vector just means "group visible" on one map and "set admitted" on
-        // the other).
+        // The selection key: a WMO item's group or a prop item's referrer set, selected alike.
         let sel_group = item
             .wmo
             .as_ref()
@@ -336,10 +284,8 @@ fn bake_cell(items: &[GxItem], meshes: &mut Assets<Mesh>) -> render::GxCellDraw
             enclosed: item.wmo.as_ref().is_some_and(|w| w.enclosed),
         });
     }
-    // Recentre for clip-space precision (0974): the shader reconstructs world = v + origin.
-    // The origin is the f32 ROUNDING of the f64 centre, and the subtraction runs in f64
-    // against that exact value — the vertex absorbs every bit the origin's rounding lost, so
-    // the only f32 quantization anywhere is of the SMALL recentred coordinate.
+    // The shader rebuilds world = v + origin. The origin is the f32-rounded centre and the
+    // subtraction runs in f64 against it, so only the small recentred value is quantized.
     let center = (mn + mx) * 0.5;
     let origin = center.as_vec3();
     let origin64 = origin.as_dvec3();
@@ -358,8 +304,7 @@ fn bake_cell(items: &[GxItem], meshes: &mut Assets<Mesh>) -> render::GxCellDraw
     mesh.insert_attribute(ATTRIBUTE_GX_WORD, words);
     mesh.insert_attribute(ATTRIBUTE_GX_ANCHOR, anchors);
     mesh.insert_indices(Indices::U32(indices));
-    // The kill bitmap opens all-zero (nothing killed); a cell with faders is marked
-    // `bits_stale` by the flush, so the scan overwrites this before the same frame's publish.
+    // All-zero; the flush marks a fader cell `bits_stale`, so the scan fills it before publish.
     let killed = vec![0u64; draws.len().div_ceil(64)];
     render::GxCellDraw {
         mesh: meshes.add(mesh),
@@ -375,7 +320,7 @@ fn bake_cell(items: &[GxItem], meshes: &mut Assets<Mesh>) -> render::GxCellDraw
                 )
             })
             .collect(),
-        sets: Vec::new(), // prop regions: the flush fills it from the collector's dedup list
+        sets: Vec::new(), // filled by the flush for a prop region
         killed,
         killed_rev: 0,
     }
@@ -390,11 +335,6 @@ mod tests {
     use benilla_formats::{ModelBlend, RenderSubmesh, WmoBatchClass};
     use std::sync::Arc;
 
-    /// **The census reports once per burst, and cannot be starved into silence.** It used to
-    /// print on any count change from a system that runs every frame, so a Goldshire login
-    /// emitted ten near-identical INFO lines climbing 8 → 1630 — a residency count that read as
-    /// a fault. Three things are pinned here: a moving count stays quiet, a settled one prints
-    /// exactly once, and a count that never settles still reports on the ceiling.
     #[test]
     fn the_decline_census_prints_once_a_burst_settles() {
         let mut gx = StaticGx::default();
@@ -403,13 +343,11 @@ mod tests {
             *frame += 1;
             census_declines(gx, *frame);
         };
-        // A burst: the count moves every frame, and nothing is reported while it does.
         for _ in 0..10 {
             gx.declined[3] += 1;
             tick(&mut gx, &mut frame);
         }
         assert_eq!(gx.declined_logged, [0; 5], "a moving count stays quiet");
-        // It settles: after the window, the total lands once and stays landed.
         for _ in 0..CENSUS_SETTLE_FRAMES {
             tick(&mut gx, &mut frame);
         }
@@ -419,7 +357,6 @@ mod tests {
             tick(&mut gx, &mut frame);
         }
         assert_eq!(gx.declined_logged, logged, "…once, not every frame after");
-        // A stream that never goes quiet reports on the ceiling instead of never.
         for _ in 0..CENSUS_MAX_HOLD_FRAMES + 1 {
             gx.declined[3] += 1;
             tick(&mut gx, &mut frame);
@@ -430,8 +367,6 @@ mod tests {
         );
     }
 
-    /// The census counts THIS world's population: a map change resets it, or the line reports the
-    /// sum of two worlds and reads as a leak (`static_merge::reset`'s own rationale).
     #[test]
     fn a_map_change_resets_the_census() {
         let mut gx = StaticGx::default();
@@ -443,9 +378,6 @@ mod tests {
         assert_eq!((gx.accepted, gx.declined[3]), (0, 0), "a fresh world");
     }
 
-    /// The bake cadence (B3, decision 1432): first bakes wait only the short window, re-bakes
-    /// of a published region wait for the long one, and the age cap consolidates a
-    /// never-quiet region regardless.
     #[test]
     fn the_bake_waits_short_first_and_long_after() {
         let mut state = super::super::GxCell::default();
@@ -470,8 +402,6 @@ mod tests {
             bake_due(&state, true, REBAKE_FRAMES, false),
             "published: long window"
         );
-        // The reveal gate's request overrides every window: a load that has finished arriving
-        // publishes what it holds instead of waiting out the quiet timer (decision 1498).
         state.last_change = IDLE_FRAMES;
         assert!(
             !bake_due(&state, false, IDLE_FRAMES, false),
@@ -489,18 +419,16 @@ mod tests {
         );
         state.dirty = true;
         state.last_change = 0;
-        // A cell that keeps changing (never quiet) still consolidates at the age cap.
+        // Changed this very frame, never quiet: the age cap still bakes it.
         state.last_change = MAX_DIRTY_FRAMES;
         assert!(bake_due(&state, true, MAX_DIRTY_FRAMES, false));
     }
 
-    /// A quiet cell bakes: one recentred mesh whose draws sort by (bucket, texture), each
-    /// item's word carrying its index + flags, index ranges contiguous over one index buffer.
     #[test]
     fn a_quiet_cell_bakes_sorted_contiguous_draws() {
         let mut gx = StaticGx::default();
         let g = tri([10.0, 0.0, 10.0]);
-        // A cutout item pushed FIRST must sort after the two opaque items.
+        // A cutout item pushed first must sort after the two opaque items.
         let mut cut = batch(&g, Vec3::new(5.0, 0.0, 5.0), None, ModelBlend::AlphaTest);
         cut.unlit = true;
         assert!(gx.divert(cut));
@@ -525,7 +453,6 @@ mod tests {
         assert_eq!(baked.draws.len(), 3);
         assert!(!baked.draws[0].cutout && !baked.draws[1].cutout);
         assert!(baked.draws[2].cutout, "the cutout item sorted last");
-        // Contiguity: each draw's range starts where the previous ended.
         assert_eq!(baked.draws[0].index_range, 0..3);
         assert_eq!(baked.draws[1].index_range, 3..6);
         assert_eq!(baked.draws[2].index_range, 6..9);
@@ -535,23 +462,16 @@ mod tests {
         else {
             panic!("gx word attribute missing")
         };
-        // Item indices ride the low bits in bake order; the cutout item (baked last, index 2)
-        // carries its UNLIT flag.
+        // The low bits carry the bake-order index; the cutout item (index 2) carries UNLIT.
         assert_eq!(words[0] & 0xffff, 0);
         assert_eq!(words[3] & 0xffff, 1);
         assert_eq!(words[6] & 0xffff, 2);
         assert_ne!(words[6] & WORD_UNLIT, 0);
         assert_eq!(words[0] & WORD_UNLIT, 0);
-        // Recentring (0974's split): the mesh-local bound centres exactly on zero by
-        // construction, and the origin carries the world offset (nonzero here — the items
-        // stand away from the world origin).
         assert!(Vec3::from(baked.aabb.center).length() < 1e-4);
         assert!(baked.origin.length() > 1.0);
     }
 
-    /// B2: after the bake's sort scatters a placement's batches through the item order, the
-    /// remap hands each fader exactly its own post-sort indices — the kill bits land on the
-    /// placement that crossed the band, never a neighbour.
     #[test]
     fn the_remap_names_each_faders_post_sort_items() {
         let mut gx = StaticGx::default();
@@ -564,9 +484,8 @@ mod tests {
             cutout: Handle::default(),
             blend: Handle::default(),
         };
-        // The exile unit is the PLACEMENT — its identity, shared by every batch (1534).
         let (p1, p2) = (object(1), object(2));
-        // Placement 1: a cutout batch (sorts LAST) + an opaque batch (sorts first)…
+        // Placement 1: a cutout batch (sorts last) and an opaque batch (sorts first)…
         let mut b = batch_of(
             &p1,
             &g,
@@ -595,23 +514,16 @@ mod tests {
             .sort_by_key(|i| ((u8::from(i.cutout) << 1) | u8::from(i.two_sided), i.texture));
         remap_fader_items(state);
         assert!(state.bits_stale, "the same-frame scan rebuilds the bitmap");
-        // The cutout batch sorted last (index 3); placement 1 owns one opaque slot + it.
         let f1 = &state.faders[&1].items;
         let f2 = &state.faders[&2].items;
         assert_eq!(f1.len(), 2);
         assert!(f1.contains(&3), "the cutout batch sorted to the tail");
         assert_eq!(f2.len(), 1);
         assert!(!f2.iter().any(|i| f1.contains(i)), "no shared kill targets");
-        // The never-fade item belongs to nobody.
         let claimed: usize = f1.len() + f2.len();
         assert_eq!(state.items.len() - claimed, 1);
     }
 
-    /// A WMO batch diverts into a region keyed by its INSTANCE entity (never a cell), the
-    /// shade refusal does not apply to it (the entity path passes `Matte` for every WMO
-    /// batch), and the baked region carries the slice-2 facts: group-homogeneous draws in
-    /// (bucket, texture, group) order, per-group bounds, the WMO word bits, and the per-item
-    /// order/SIDN records.
     #[test]
     fn a_wmo_batch_diverts_by_instance_and_bakes_group_ranges() {
         let mut gx = StaticGx::default();
@@ -628,17 +540,17 @@ mod tests {
             ext_night: false,
             enclosed: false,
         };
-        // An INT batch of group 2, pushed FIRST — Matte shade must NOT refuse it…
+        // An INT batch of group 2, pushed first…
         let mut b = batch(&g, Vec3::new(1.0, 0.0, 1.0), None, ModelBlend::Opaque);
         b.shade = ShadeSel::Matte;
         b.wmo = Some(wmo(2, Some(WmoBatchClass::Int), true));
         assert!(gx.divert(b));
-        // …a TRANS batch of group 1 (same bucket/texture — the sort must bring it first)…
+        // …a TRANS batch of group 1, same bucket and texture, which the sort must bring first…
         let mut b = batch(&g, Vec3::new(2.0, 0.0, 2.0), None, ModelBlend::Opaque);
         b.shade = ShadeSel::Matte;
         b.wmo = Some(wmo(1, Some(WmoBatchClass::Trans), true));
         assert!(gx.divert(b));
-        // …and an exterior-law batch of group 2 again (fuses with the first after the sort).
+        // …and an exterior-law batch of group 2, which sorts beside the first.
         let mut b = batch(&g, Vec3::new(3.0, 0.0, 3.0), None, ModelBlend::Opaque);
         b.shade = ShadeSel::Matte;
         b.wmo = Some(wmo(2, None, false));
@@ -654,21 +566,17 @@ mod tests {
         });
         let mut meshes = Assets::<Mesh>::default();
         let baked = bake_cell(&state.items, &mut meshes);
-        // Group 1 sorted ahead of group 2; ranges contiguous over one index buffer.
         assert_eq!(
             baked.draws.iter().map(|d| d.group).collect::<Vec<_>>(),
             vec![Some(1), Some(2), Some(2)]
         );
         assert_eq!(baked.draws[0].index_range, 0..3);
         assert_eq!(baked.draws[2].index_range, 6..9);
-        // Per-group bounds for the cull's admission walk.
         let mut groups: Vec<u16> = baked.groups.iter().map(|(g, _)| *g).collect();
         groups.sort_unstable();
         assert_eq!(groups, vec![1, 2]);
-        // The per-item records: authored order + SIDN ride the draw.
         assert_eq!(baked.draws[0].order, 2); // group 1's batch_order = group + 1
         assert_eq!(baked.draws[0].sidn, [10, 20, 30]);
-        // The word bits: WMO everywhere; TRANS/INT class lanes; WINDOW; no vertex colours.
         let mesh = meshes.get(&baked.mesh).unwrap();
         let Some(bevy::mesh::VertexAttributeValues::Uint32(words)) =
             mesh.attribute(ATTRIBUTE_GX_WORD)
@@ -688,22 +596,16 @@ mod tests {
         assert_eq!(w_ext & (WORD_CLASS_INT | WORD_CLASS_TRANS), 0);
         assert_ne!(w_trans & WORD_INTERIOR, 0);
         assert_eq!(w_ext & WORD_INTERIOR, 0);
-        // White default colours where none are authored (the bit-identity contract).
         let Some(bevy::mesh::VertexAttributeValues::Float32x4(colors)) =
             mesh.attribute(Mesh::ATTRIBUTE_COLOR)
         else {
             panic!("gx colour attribute missing")
         };
         assert_eq!(colors[0], [1.0, 1.0, 1.0, 1.0]);
-        // clear() empties the WMO side too.
         gx.clear();
         assert!(gx.wmos.is_empty());
     }
 
-    /// A prop region bakes with the referrer SET as the selection grain (B4): draws sort
-    /// (bucket, texture, set) and carry the set index in `group`, per-set bounds land in
-    /// `groups`, the interior slot rides the draw, and the word carries
-    /// INTERIOR-without-WMO for slotted items and MATTE for the exterior family.
     #[test]
     fn a_prop_region_bakes_set_ranges_and_slots() {
         let mut gx = StaticGx::default();
@@ -716,8 +618,7 @@ mod tests {
             groups: Arc::clone(groups),
             slot,
         };
-        // Set B pushed FIRST — the sort must bring set A (index 1? no: dedup order is
-        // arrival order, so B=0, A=1) ranges together and set-homogeneous.
+        // Set B arrives first, so the dedup gives B index 0 and A index 1.
         let mut b = batch(&g, Vec3::new(1.0, 0.0, 1.0), None, ModelBlend::Opaque);
         b.shade = ShadeSel::Matte;
         b.prop = Some(mk(&rooms_b, Some(42)));
@@ -740,7 +641,6 @@ mod tests {
         });
         let mut meshes = Assets::<Mesh>::default();
         let baked = bake_cell(&state.items, &mut meshes);
-        // Set 0 (rooms_b)'s two items sit adjacent; set 1 (rooms_a) follows.
         assert_eq!(
             baked.draws.iter().map(|d| d.group).collect::<Vec<_>>(),
             vec![Some(0), Some(0), Some(1)]
@@ -749,12 +649,10 @@ mod tests {
             baked.draws.iter().map(|d| d.slot).collect::<Vec<_>>(),
             vec![42, 43, 0]
         );
-        // Per-set bounds for the admission walk.
         let mut sets: Vec<u16> = baked.groups.iter().map(|(s, _)| *s).collect();
         sets.sort_unstable();
         assert_eq!(sets, vec![0, 1]);
-        // The word: a slotted item is INTERIOR without WMO; a slot-less Matte prop keeps
-        // the exterior law with the MATTE family bit.
+        // Slotted: INTERIOR without WMO. Slot-less: the exterior law with MATTE.
         let mesh = meshes.get(&baked.mesh).unwrap();
         let Some(bevy::mesh::VertexAttributeValues::Uint32(words)) =
             mesh.attribute(ATTRIBUTE_GX_WORD)
@@ -769,10 +667,7 @@ mod tests {
         assert_ne!(w_ext & WORD_MATTE, 0);
     }
 
-    /// Authored vertex colours bake RAW into ATTRIBUTE_COLOR and set the HAS_VC bit — the
-    /// entity mesh's exact carriage (`model.rs` inserts `vertex_colors` untransformed), which
-    /// is both MOCV's lane and the fix for the slice-1 gap where a doodad's baked constant
-    /// tint was silently dropped.
+    /// Raw, as `model.rs` inserts `vertex_colors` on the entity mesh.
     #[test]
     fn authored_vertex_colours_bake_raw_and_set_the_bit() {
         let mut gx = StaticGx::default();
diff --git a/crates/benilla-world/src/static_gx/cull.rs b/crates/benilla-world/src/static_gx/cull.rs
index 70c64321..f1adab2c 100644
--- a/crates/benilla-world/src/static_gx/cull.rs
+++ b/crates/benilla-world/src/static_gx/cull.rs
@@ -1,21 +1,16 @@
-//! The per-frame CPU scene walk of the retained pass (split from `mod.rs` at the
-//! 1,000-line budget) — the seven-term collapse at cell/group granularity, the dead-region
-//! reap, the fader exile scan (B2, decision 1431), and the `WOW_GX_CENSUS` agreement
-//! instrument.
+//! The retained pass's per-frame CPU scene walk: admission per cell, WMO group and prop set, the
+//! dead-region reap, the fader exile scan and the `WOW_GX_CENSUS` line.
 
 use bevy::prelude::*;
 
 use super::render::GxDoodadVis;
 use super::{FaderState, GxFader, StaticGx};
 
-/// Exile hysteresis (yd). Entry into the feather has NO slack — a retained draw at
-/// `alpha < 1` is wrong the frame it happens — but both exits (re-admission to Steady, the
-/// far-side despawn to Gone) require the camera this far past the crossing, so a camera
-/// parked exactly on a band edge cannot flap entities into and out of existence.
+/// Exile hysteresis in yards: entry into the feather is exact, but both exits need the camera this
+/// far past the edge, so a camera parked on one cannot flap.
 const FADE_HYST: f32 = 1.0;
 
-/// Where the exile state machine sits, as a value (the entity list stays on
-/// [`FaderState`]).
+/// [`FaderState`] without its entity list.
 #[derive(Clone, Copy, PartialEq, Debug)]
 enum FadeClass {
     Steady,
@@ -33,11 +28,8 @@ impl GxFader {
     }
 }
 
-/// The exile step: where a fader at horizontal centre-distance `d` should sit, given where
-/// it is now. Classifies on [`crate::model_fade::doodad_fade_alpha`] itself — the SAME
-/// function the entity authority evaluates per frame — so the two lanes cannot disagree at
-/// the entry edges; the exits shift the *sample point* by [`FADE_HYST`] instead of keeping a
-/// second band table.
+/// Where a fader at horizontal distance `d` moves from `current`, by the entity path's own
+/// [`crate::model_fade::doodad_fade_alpha`]; the exits shift the sample by [`FADE_HYST`].
 fn fade_step(radius: f32, d: f32, current: FadeClass) -> FadeClass {
     use crate::model_fade::doodad_fade_alpha as alpha;
     match current {
@@ -72,11 +64,8 @@ fn fade_step(radius: f32, d: f32, current: FadeClass) -> FadeClass {
     }
 }
 
-/// One referrer set's PVS verdict (B4): a prop is drawn from ANY of the rooms that name it,
-/// each bit read fail-open — `WmoGroupVis::drawn_by`'s exact rule at range-selection grain.
-/// An EMPTY set is always admitted (an unnamed prop carries no `WmoGroupVis` on the entity
-/// path and is never portal-culled; `drawn_by`'s `any()` on empty would read false, which is
-/// why the entity path never constructs the component for one).
+/// A referrer set's PVS verdict, `WmoGroupVis::drawn_by`'s rule: any named room visible, a missing
+/// bit fail-open. An empty set, an unnamed prop, is never portal-culled.
 fn set_admitted(visible: &[bool], rooms: &[u16]) -> bool {
     rooms.is_empty()
         || rooms
@@ -84,21 +73,14 @@ fn set_admitted(visible: &[bool], rooms: &[u16]) -> bool {
             .any(|&g| visible.get(usize::from(g)).copied().unwrap_or(true))
 }
 
-/// `WOW_GX_FADE_TRACE=1` — one line per exile transition (the live-probe instrument for the
-/// state machine: what crossed, where, into what).
+/// `WOW_GX_FADE_TRACE=1`: one line per exile transition.
 fn fade_trace() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_GX_FADE_TRACE").is_some())
 }
 
-/// Spawn one exiled placement as ordinary entities — the production assembler's own bundle
-/// for a static, non-billboard, exterior doodad batch (`assemble.rs`), from handle clones
-/// captured at divert time. The spawn flushes after `CheckVisibility` (the plugin's
-/// ordering law), so the entity first draws NEXT frame — seeded with the values the
-/// authority will confirm (blend twin + the live fade alpha in `MeshTag`); the authority
-/// owns it from the next `Update` on. The explicit `GlobalTransform`/`InheritedVisibility`
-/// are belts: next frame's propagation computes both before anything draws, but a fresh
-/// root should never sit a frame on defaults that place it at the origin, hidden.
+/// Spawn an exiled placement as `assemble.rs`'s own doodad bundle, seeded with the blend material
+/// and live fade alpha that the fade authority owns from the next `Update`.
 fn spawn_exile(commands: &mut Commands, f: &GxFader, alpha: f32, admitted: bool) -> Vec<Entity> {
     let mut ents = Vec::with_capacity(f.batches.len());
     for b in &f.batches {
@@ -110,7 +92,7 @@ fn spawn_exile(commands: &mut Commands, f: &GxFader, alpha: f32, admitted: bool)
                 b.cutout.clone()
             }),
             f.transform,
-            // A placement is a world root, so Transform IS the global (see the fn doc).
+            // A placement is a world root: its Transform is its global.
             GlobalTransform::from(f.transform),
             crate::model_render::ModelPart {
                 kind: crate::model_render::ModelKind::Doodad,
@@ -126,9 +108,7 @@ fn spawn_exile(commands: &mut Commands, f: &GxFader, alpha: f32, admitted: bool)
                 blend: b.blend.clone(),
             },
             crate::exterior_cull::ExteriorScene,
-            // The placement's own identity, not a lane-flavoured copy: a feathering doodad must
-            // name the same thing under the cursor whether the retained pass or these exiled
-            // entities are drawing it that frame (1534).
+            // The placement's own identity: the pick names it alike whichever lane draws it.
             (*f.object).clone(),
         ));
         if admitted {
@@ -150,27 +130,10 @@ fn spawn_exile(commands: &mut Commands, f: &GxFader, alpha: f32, admitted: bool)
     ents
 }
 
-/// The CPU scene walk (1429: "nothing needs a GPU-side visibility bitset") — frustum, the
-/// farclip wall, and the exterior window gate, each at cell granularity, published as this
-/// frame's visible list. Coarser than the entity path's per-submesh tests by design; the gate
-/// admits at Aabb granularity either way, so cell-whole is conservative (overdraw, never a
-/// hole).
-///
-/// Slice 2 adds the WMO half: per-GROUP admission over each retained region — the portal
-/// PVS bit (fail-open, honouring the panel's `portal_cull` A/B switch) ∧ frustum ∧ farclip
-/// ∧ the exterior gate with the own-building exemption (the camera's containing placement is
-/// not exterior to itself — `CameraInteriorClaim`, the same term the entity authority reads).
-/// This is ALSO where a dead region is reaped: the instance entity despawns with its
-/// placement, and that death — not the owner tile's — is the WMO release law (straddler
-/// handoffs keep the placement alive under a new owner).
-///
-/// B2 adds the fader exile scan: per cell, a cheap ring test (the camera's distance interval
-/// to the cell's fader centres against the union fade band) skips settled cells wholesale;
-/// a straddling cell walks its placements through [`fade_step`]. A placement entering the
-/// feather respawns as ordinary entities that first draw next frame, and its kill bits ARM
-/// on that same next frame — the retained item dies in the rendered frame the entity
-/// appears (the overlap protocol; see [`FaderState`]). A re-admit reverses both in ONE
-/// frame: the despawn lands before extract and the cleared bit rides the same publish.
+/// The CPU scene walk into this frame's visible lists: frustum, farclip and the exterior window
+/// gate per cell (conservative: overdraw, never a hole), plus the portal PVS per WMO group, the
+/// camera's own building exempt from the gate. A re-admitted exile despawns and clears its kill
+/// bit in the same frame.
 pub(super) fn cull_cells(
     mut commands: Commands,
     mut gx: ResMut<StaticGx>,
@@ -189,8 +152,6 @@ pub(super) fn cull_cells(
     instances: Query<&crate::wmo_portal::WmoPortalInstance>,
 ) {
     let _t = super::gx_perf_guard(1);
-    // Drain the lifecycle queue first: exiled entities whose seed died out from under them
-    // (owner release, map clear) — this scan owns the exile lifecycle end to end.
     for e in gx.pending_despawn.drain(..) {
         commands.entity(e).try_despawn();
     }
@@ -203,10 +164,8 @@ pub(super) fn cull_cells(
         fade_events,
         ..
     } = &mut *gx;
-    // Reap dead regions (instance despawned with its placement) — items and published draws.
-    // Prop regions share the instance lifecycle (B4): the instance dies exactly when the
-    // placement releases at refs 0, and a WMO placement never hands off (the straddler
-    // handoff is M2-only), so no owner-tile bookkeeping exists to go stale.
+    // Reap regions whose instance died with its placement; a WMO placement never changes owner
+    // tile (the straddler handoff is M2-only).
     wmos.retain(|e, _| instances.contains(*e));
     world.wmos.retain(|e, _| instances.contains(*e));
     props.retain(|e, _| instances.contains(*e));
@@ -223,7 +182,7 @@ pub(super) fn cull_cells(
     let doodads_on =
         m.kind_visible[crate::model_render::kind_index(crate::model_render::ModelKind::Doodad)];
 
-    // ---- The fader exile scan (B2, 1431) ----
+    // ---- The fader exile scan ----
     let cam_xz = Vec2::new(cam_pos.x, cam_pos.z);
     for (&key, cell) in cells.iter_mut() {
         if cell.faders.is_empty() {
@@ -232,9 +191,8 @@ pub(super) fn cull_cells(
         let Some((mn, mx)) = cell.fader_bounds else {
             continue;
         };
-        // The camera's distance interval to the fader-centre rect (2D), against the cell's
-        // band union — with the hysteresis margin folded in, so a wholesale verdict implies
-        // every per-placement verdict and one walk under it settles the whole cell.
+        // The camera's distance range to the fader centres against the band union, with the
+        // hysteresis margin, so a wholesale verdict holds for every placement.
         let dmin = cam_xz.distance(cam_xz.clamp(mn, mx));
         let corner = Vec2::new(
             if (cam_xz.x - mn.x).abs() > (cam_xz.x - mx.x).abs() {
@@ -255,13 +213,12 @@ pub(super) fn cull_cells(
         } else if dmin > far_max + FADE_HYST {
             Some(false) // every placement gone, with margin
         } else {
-            None // the ring straddles the cell — walk it
+            None // the ring straddles the cell: walk it
         };
         if verdict.is_some() && verdict == cell.settled && !cell.bits_stale {
             continue;
         }
-        // The cell-granular admission the exile seed borrows (the walk re-derives the exact
-        // per-entity verdict next Update; this only bridges the spawn frame).
+        // Cell-grain admission for the spawn frame; the entity path's own test runs next Update.
         let admitted = doodads_on
             && world.cells.get(&key).is_none_or(|d| {
                 gate.admits(&GlobalTransform::from_translation(d.origin), Some(&d.aabb))
@@ -269,9 +226,7 @@ pub(super) fn cull_cells(
         let mut bits_changed = cell.bits_stale;
         let mut unarmed_left = false;
         for f in cell.faders.values_mut() {
-            // The overlap protocol's second half: LAST frame's exile spawns flushed at the
-            // end of that frame's PostUpdate and first draw THIS frame — arm their kill bits
-            // now, so the retained item dies in the same rendered frame the entity appears.
+            // Last frame's exile spawns draw from this frame: arm their kill bits now.
             if let FaderState::Exiled { armed, .. } = &mut f.state {
                 if !*armed {
                     *armed = true;
@@ -307,9 +262,7 @@ pub(super) fn cull_cells(
                 FadeClass::Feather => {
                     fade_events[0] += 1;
                     let alpha = crate::model_fade::doodad_fade_alpha(f.radius, d);
-                    // Fresh spawns stay UNARMED this frame (their entities don't draw until
-                    // next frame — killing now would hole the handoff)… unless the fader was
-                    // already killed as Gone: those bits stay set, nothing to wait for.
+                    // Unarmed until the entities draw, unless it was Gone and is already killed.
                     let armed = old == FadeClass::Gone;
                     unarmed_left |= !armed;
                     FaderState::Exiled {
@@ -336,12 +289,9 @@ pub(super) fn cull_cells(
         cell.settled = if unarmed_left { None } else { verdict };
         if bits_changed {
             if let Some(draw) = world.cells.get_mut(&key) {
-                // Copy-on-write (1436): the region is Arc-shared with the render world's
-                // extracted clone; a real bitmap change — the only writer — pays one region
-                // copy here so the per-frame publish/extract clones stay refcount bumps.
+                // Copy-on-write: the region is shared with the render world's extracted clone.
                 let draw = std::sync::Arc::make_mut(draw);
-                // Rebuild whole from the states — cheap, and immune to index drift across
-                // re-bakes (the flush refreshed `items` and set `bits_stale` this frame).
+                // Rebuilt whole from the states, so a re-bake's new indices cannot drift.
                 draw.killed.iter_mut().for_each(|w| *w = 0);
                 for f in cell.faders.values() {
                     let killed = match f.state {
@@ -364,15 +314,11 @@ pub(super) fn cull_cells(
         }
     }
 
-    // The own-building exemption, shared by the WMO groups' gate term and the prop sets'
-    // (B4): the camera's containing placement is not exterior to itself (decision 0784's
-    // dynamic exemption — a static tag could not be right, the player walks in and out).
+    // The building the camera is in is not exterior to itself, for WMO groups and prop sets.
     let own = claim.0.map(|c| c.room.instance);
-    // The dev doodad toggle, cell-wholesale (see the module doc). The doodad phase — cells
-    // AND prop regions (B4; a WMO's furniture is the M2 scene, not the WMO phase) — sorts
-    // NEAR-FIRST as one list (B3, decision 1432): the 1.12 client's front-to-back band walk
-    // (32 bands × 33⅓ yd, `terrain.md` 0xc7bd40) at this lane's grain: the node draws the
-    // list in order, so early-z rejects the far entries' fragments instead of shading them.
+    // The dev doodad kind toggle hides every cell at once; the blend-layer toggles do not reach
+    // this lane. Cells and prop regions, both the M2 scene, sort near-first as one list: the 1.12
+    // client's front-to-back band walk (32 bands of 33⅓ yd, `0xc7bd40`) at cell grain.
     if doodads_on {
         let mut admitted: Vec<(u32, GxDoodadVis)> = Vec::new();
         for (&cell, draw) in &world.cells {
@@ -381,8 +327,6 @@ pub(super) fn cull_cells(
             if !crate::view::within_farclip(view.farclip, cam_pos, cam_fwd, center, radius) {
                 continue;
             }
-            // The camera's own frustum (bevy's `update_frusta` output — the same planes its
-            // per-entity cull tests), against the cell's world bound.
             let sphere = bevy::camera::primitives::Sphere {
                 center: center.into(),
                 radius,
@@ -390,10 +334,7 @@ pub(super) fn cull_cells(
             if !frustum.intersects_sphere(&sphere, false) {
                 continue;
             }
-            // ADT doodads are exterior scene (spawn tags them per submesh): from inside a WMO
-            // they draw only through a portal window. `admits` takes the same (transform,
-            // aabb) shape the per-entity term feeds it; cell granularity is conservative
-            // (overdraw, no hole).
+            // ADT doodads are exterior scene: from inside a WMO they draw only through a window.
             if !gate.admits(
                 &GlobalTransform::from_translation(draw.origin),
                 Some(&draw.aabb),
@@ -406,15 +347,10 @@ pub(super) fn cull_cells(
                 GxDoodadVis::Cell(cell),
             ));
         }
-        // The prop regions (B4) join the same list: admission per referrer SET — the PVS
-        // bit ORs over the set's rooms ([`set_admitted`] — `WmoGroupVis::drawn_by`'s
-        // fail-open read, behind the same panel switch), ∧ frustum ∧ farclip ∧ the exterior
-        // gate for NAMED sets with the own-building exemption. An empty set (an unnamed
-        // prop) admits bare and is never gated: 0784's untagged rule — no key, no exemption
-        // possible, so it is deliberately not gated blind.
+        // Prop regions join the list, admitted per referrer set: PVS (`set_admitted`), farclip,
+        // frustum, and the exterior gate for named sets only; an unnamed prop is never gated.
         for (&entity, draw) in &world.props {
-            // A region whose instance can't answer this frame keeps last frame's absence —
-            // one frame of the entity path's own arrival class (the WMO regions' rule).
+            // An instance not queryable yet (spawn-command latency) skips this frame.
             let Ok(inst) = instances.get(entity) else {
                 continue;
             };
@@ -427,11 +363,8 @@ pub(super) fn cull_cells(
                 let Some(rooms) = draw.sets.get(usize::from(*set)) else {
                     continue;
                 };
-                // The interior-fog lane is decided per SET whether or not the set draws — the
-                // record sync reads the whole vector, and a set the frustum drops this frame is
-                // back next frame with the same rooms. `set_admitted`'s fail-OPEN read is wrong
-                // here: `interior_fogged_by`'s fail-closed one is the fog rule (a missing bit
-                // must not paint a room's MFOG onto a prop).
+                // The fog lane is written for every set, drawn or not: the record sync reads the
+                // whole vector. A missing bit reads false (`interior_fogged_by`), not fail-open.
                 sel.fog[usize::from(*set)] = rooms.iter().any(|&g| {
                     inst.interior_fog
                         .get(usize::from(g))
@@ -473,13 +406,10 @@ pub(super) fn cull_cells(
         admitted.sort_unstable_by_key(|(d, _)| *d);
         world.visible.extend(admitted.into_iter().map(|(_, v)| v));
     }
-    // The WMO regions — the dev WMO toggle wholesale, then per-group admission; regions
-    // likewise ordered near-first (B3).
+    // WMO regions: the dev WMO toggle, then per-group admission, near-first.
     if m.kind_visible[crate::model_render::kind_index(crate::model_render::ModelKind::Wmo)] {
         let mut admitted: Vec<(u32, (Entity, crate::static_gx::render::GxSel))> = Vec::new();
         for (&entity, draw) in &world.wmos {
-            // A region whose instance can't answer this frame (spawn-command latency) keeps
-            // last frame's absence — one frame of the entity path's own arrival class.
             let Ok(inst) = instances.get(entity) else {
                 continue;
             };
@@ -490,15 +420,13 @@ pub(super) fn cull_cells(
             };
             let mut any = false;
             for (group, aabb) in &draw.groups {
-                // The fog lane first, for every group of the region and not only the drawn ones —
-                // see the prop site above for why.
+                // The fog lane for every group, drawn or not, as for prop sets.
                 sel.fog[usize::from(*group)] = inst
                     .interior_fog
                     .get(usize::from(*group))
                     .copied()
                     .unwrap_or(false);
-                // The portal PVS bit — the SAME fail-open read `WmoGroupVis::drawn_by` takes,
-                // behind the same panel switch.
+                // The portal PVS bit, fail-open like `WmoGroupVis::drawn_by`.
                 if m.portal_cull
                     && !inst
                         .visible
@@ -520,7 +448,7 @@ pub(super) fn cull_cells(
                 if !frustum.intersects_sphere(&sphere, false) {
                     continue;
                 }
-                // Another building is exterior scene; the camera's own is exempt (0784).
+                // Another building is exterior scene; the camera's own is exempt.
                 if Some(entity) != own
                     && !gate.admits(&GlobalTransform::from_translation(draw.origin), Some(aabb))
                 {
@@ -539,12 +467,8 @@ pub(super) fn cull_cells(
             .visible_wmos
             .extend(admitted.into_iter().map(|(_, v)| v));
     }
-    // `WOW_GX_CENSUS=1` — the slice-2 agreement instrument (1429: "LBRS-style drawn-count
-    // agreement"): each selected item IS one would-be submesh entity, so this line reads
-    // directly against the entity path's VIS_CENSUS/`drawn=` at the same pin (gx ≥ entity is
-    // the expected granularity coarsening; gx ≫ entity is a portal leak). ~1 Hz, env-gated.
-    // B2 adds the fader tallies (steady/exiled/gone) + the lifetime transition counters
-    // (exiles/readmits/gones) — the churn instrument for the exile protocol.
+    // `WOW_GX_CENSUS=1`: a selected item is one would-be entity-path submesh, so the counts read
+    // against the entity path's `VIS_CENSUS`; at or above it is coarser grain, far above a leak.
     static CENSUS: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     if *CENSUS.get_or_init(|| std::env::var_os("WOW_GX_CENSUS").is_some())
         && gx.frame.is_multiple_of(64)
@@ -637,8 +561,6 @@ pub(super) fn cull_cells(
 mod tests {
     use super::*;
 
-    /// The set admission mirrors `WmoGroupVis::drawn_by` exactly: any named room visible ⇒
-    /// drawn, missing bits fail-open, and the empty set (an unnamed prop) always admits.
     #[test]
     fn set_admission_is_any_of_named_rooms_fail_open() {
         let vis = [false, true, false];
@@ -649,29 +571,23 @@ mod tests {
         assert!(set_admitted(&vis, &[]), "an unnamed prop is never culled");
     }
 
-    /// The state machine against the fade law it mirrors: entry edges exact (the retained
-    /// draw must stop the frame the authority would feather), exit edges sticky by the
-    /// hysteresis (a camera parked on a band edge cannot flap).
     #[test]
     fn the_exile_step_enters_exact_and_exits_sticky() {
-        // radius 0 → band 40..50 (the small-prop bucket; golden in model_fade's tests).
+        // Radius 0 is the 40..50 yd band, `model_fade`'s small-prop bucket.
         let r = 0.0;
-        // Entry: steady holds through the band start, feathers strictly past it.
         assert_eq!(fade_step(r, 39.0, FadeClass::Steady), FadeClass::Steady);
         assert_eq!(fade_step(r, 40.0, FadeClass::Steady), FadeClass::Steady);
         assert_eq!(fade_step(r, 40.5, FadeClass::Steady), FadeClass::Feather);
-        // Direct steady→gone (a teleport past the band end).
+        // A teleport past the band end goes straight to Gone.
         assert_eq!(fade_step(r, 60.0, FadeClass::Steady), FadeClass::Gone);
-        // Exit to steady needs the hysteresis: at d=40.5 the +1yd probe still feathers.
+        // Exits need the 1 yd margin: at 40.5 the probe at 41.5 still feathers.
         assert_eq!(fade_step(r, 40.5, FadeClass::Feather), FadeClass::Feather);
         assert_eq!(fade_step(r, 39.0, FadeClass::Feather), FadeClass::Steady);
-        // Exit to gone likewise sticky on the far edge.
         assert_eq!(fade_step(r, 50.5, FadeClass::Feather), FadeClass::Feather);
         assert_eq!(fade_step(r, 51.5, FadeClass::Feather), FadeClass::Gone);
-        // Gone re-enters the feather the moment alpha is nonzero again…
+        // Gone feathers again as soon as alpha is nonzero, and needs the margin for Steady.
         assert_eq!(fade_step(r, 49.9, FadeClass::Gone), FadeClass::Feather);
         assert_eq!(fade_step(r, 50.0, FadeClass::Gone), FadeClass::Gone);
-        // …and jumps straight to steady only with the margin (a teleport close).
         assert_eq!(fade_step(r, 38.9, FadeClass::Gone), FadeClass::Steady);
     }
 }
diff --git a/crates/benilla-world/src/static_gx/mod.rs b/crates/benilla-world/src/static_gx/mod.rs
index 2e5acea7..22858cd9 100644
--- a/crates/benilla-world/src/static_gx/mod.rs
+++ b/crates/benilla-world/src/static_gx/mod.rs
@@ -1,124 +1,12 @@
-//! **The retained static-world pass — ON by default** (decisions 1429–1434;
-//! `WOW_STATIC_GX=0` opts out): the static world leaves bevy_pbr entirely and draws from
-//! retained buffers in one custom render node, cross-material — per-vertex texture-array
-//! layers + flag bits where the entity path had one material handle per batch. Grown in
-//! four slices: B1 never-fade doodads + WMO group geometry, B2 faders via the exile
-//! protocol, B3 the churn payments (shared pool, re-bake cadence, draw order, kill-aware
-//! runs), B4 the WMO-prop absorption; flipped default-on at 1434 after the director's eye
-//! passed at the pins.
+//! The retained static-world pass, on unless `WOW_STATIC_GX=0`: ADT doodads, WMO group geometry
+//! and WMO doodad props draw from retained, recentred buffers in one render node instead of
+//! bevy_pbr, at pixel parity with the entity path (`WOW_STATIC_MERGE=0 WOW_STATIC_GX=0`).
+//! Visibility is a CPU scene walk feeding retained draws, the reference's own shape. Only fade-1
+//! content draws here: a placement inside its fade band is exiled to ordinary entities.
 //!
-//! The correctness bar is pixel-identity against the entity path
-//! (`WOW_STATIC_MERGE=0 WOW_STATIC_GX=0` vs the armed default) at the capture fixtures —
-//! the on-demand A/B harness, not the director's eye (§7: captures are a regression tool).
-//!
-//! What it deliberately does NOT build (1429 stages them): horizon occlusion, class-aware
-//! index baking (items are sorted by `(bucket, texture)` main-world and coalesced into runs
-//! render-side; dims and format are only knowable there — BLP images are
-//! `RENDER_WORLD`-only), and any default flip.
-//!
-//! The visibility terms at this lane's granularity (1429's table): frustum + farclip + the
-//! exterior window gate are CPU per-CELL ([`cull_cells`] — the real client's own shape, a CPU
-//! scene walk feeding retained draws); fade is the EXILE PROTOCOL (B2, decision 1431 — see
-//! below); portal PVS and the billboard-owner term never apply to ADT doodads; the dev
-//! kind/blend toggles are honoured cell-wholesale via [`crate::dev_state::DebugState`]'s
-//! doodad toggle (a prototype coarsening — the entity path toggles per blend class).
-//!
-//! **B2 (decision 1431): faders ride the retained pass via the exile protocol.** The pass
-//! draws only fade = 1 content: a fader placement diverts with an exile SEED (uid + handle
-//! clones of the production bundle), and [`cull::cull_cells`]'s per-frame scan classifies it
-//! on `doodad_fade_alpha` — the same function the entity authority evaluates. Steady = drawn
-//! retained, no entity rows; Exiled (0 < α < 1) = every item takes the record-table KILL BIT
-//! (the vertex stage collapses it to a zero-area point) and the placement respawns as
-//! ordinary entities, so the feather is the entity path's own look by construction; Gone
-//! (α = 0) = killed, nothing spawned anywhere. Exits carry 1 yd hysteresis; entry none.
-//! The frame discipline is the OVERLAP PROTOCOL (1421's pop class, prevented structurally):
-//! an exile's entities flush at `PostUpdate`'s end and first draw NEXT frame, and the kill
-//! bit waits for them (`FaderState::Exiled::armed`) — the retained item dies in the same
-//! rendered frame the entity appears; a re-admit clears the bit and despawns in one frame
-//! (the despawn lands before extract, the cleared bit rides the same publish). Never order
-//! this chain's commands to flush mid-`PostUpdate` — the plugin's `chain_ignore_deferred`
-//! note records the bevy_pbr panic that forbids it. `WOW_STATIC_GX_FADE=0` is the fader
-//! lane-isolation lever; `WOW_GX_FADE_TRACE=1` logs transitions; the census carries
-//! `faders=`/`fade_events=`.
-//!
-//! Exclusions the collector refuses (each falls through to the ordinary merge/entity path, and
-//! the flush logs a one-line census — refusals beside the ACCEPTED count, once a streaming burst
-//! settles — so a declined population is never silent, and never mistakable for a dead pass in
-//! the other direction either): env-mapped
-//! batches (`texture_unit_lookup > 2` — view-generated UVs), the depth-flag oddities
-//! (`no_depth_write`/`no_depth_test` — pipeline-state per batch), and the `ShadeSel::Matte`/
-//! `Rig` families (exterior WMO MODD props ride the prop site, not this lane).
-//!
-//! **Slice-1 verdict (the first capture A/B, 2026-08-18):** against a selfcheck floor of
-//! exactly 0, the armed sweep reads MAE 0.000 on all four scenarios with 13–65 pixels per
-//! 5.8-Mpx frame differing by exactly 1/255 (float-order residue of the baked-transform
-//! arithmetic; zero pixels beyond 8) — pixel-identical to the quantization limit, ~1,500
-//! retained cell bakes participating. Two desk-found parity terms live in render.rs/the WGSL:
-//! the aniso-8 samplers, and the two-sided normal law (the entity shader's `select` UNDOES a
-//! bevy negation this pipeline never had — copying it flipped every back-facing canopy card).
-//!
-//! **Known B1 gaps** (B2+ owns them): dev-instrument identity (inspector/WOW_PICK name nothing
-//! — the weld/merge trade, one side table if missed) is **CLOSED by 1534**: the side table is the
-//! items' own [`GxItem::object`]/[`GxItem::local_aabb`], and [`pick`] is the lane answering the ray
-//! from this frame's published selection. The other one B1 left open — no
-//! `presentable()` coupling, so an unbaked region shows a hole for a beat on a cold arrival
-//! where the merge publishes `merge_pending` into the reveal cover (1419) — is **CLOSED by
-//! 1498**: [`StaticGx::undrawn_regions`] is that coupling, and [`StaticGx::flush_now`] is why
-//! it costs the load no extra frames. It was not a beat: it was the director's report of
-//! teleporting into a Stormwind with no Stormwind in it.
-//!
-//! **B3 (decision 1432): the churn 1431 priced is paid.** Texture arrays are ONE SHARED POOL
-//! across every cell and region (dedup by asset id; `pool.rs` owns the design note), layer
-//! copies encode exactly once, re-bakes ride the long quiet window ([`REBAKE_FRAMES`] —
-//! 1424's consolidate-on-quiet at bake grain), admitted cells and regions draw NEAR-FIRST
-//! (the 1.12 band walk's effect at cell grain), and killed items are dropped from the draw
-//! runs entirely rather than collapsed in the vertex stage (the WGSL collapse stays as belt).
-//!
-//! **Slice 2 (1429's second half): WMO group geometry.** An order-free WMO group batch diverts
-//! into a region keyed by its placement's [`crate::wmo_portal::WmoPortalInstance`] ENTITY —
-//! the PVS identity — with draws bucketed per (pipeline bucket × texture × GROUP), so the
-//! portal flood's per-frame verdict becomes CPU range selection over retained buffers (the
-//! design's load-bearing collapse: the client's own per-group draw records). Per-group
-//! admission each frame = the PVS bit (fail-open, honouring the `portal_cull` A/B switch) ∧
-//! frustum ∧ farclip ∧ the exterior window gate with the own-building exemption — the same
-//! seven-term collapse as cells, at group granularity. Region lifecycle follows the INSTANCE
-//! entity's death, never the owner tile: a straddler handoff keeps the placement (and its
-//! instance) alive under a new owner, and tile-keyed release would have dropped the retained
-//! geometry out from under it. The WMO lighting lanes (MOCV inside the clamp, INT/TRANS batch
-//! classes, SIDN night glow, WINDOW midpoint light, the interior fog triple, ZERO point
-//! lights, the authored batch-order clip-z nudge) mirror `wow_model.wgsl` in `static_gx.wgsl`.
-//!
-//! **B4 (decision 1433): the prop site joins the pass — A's blobs absorbed.** WMO doodad
-//! props (1418's lane 3, the population A merged) divert into PROP REGIONS keyed by the same
-//! instance entity as the WMO regions but held apart (props trickle in as their M2s load;
-//! a shared region would re-bake the building's geometry per arrival — B3's churn class).
-//! Admission is per REFERRER SET (the distinct room-sets naming this region's props): the
-//! PVS bit ORs over the set exactly like `WmoGroupVis::drawn_by`, ∧ frustum ∧ farclip ∧ the
-//! exterior gate with the own-building exemption — an empty set (an unnamed prop) admits
-//! bare and is never exterior-gated (0784's untagged rule). Interior props light from their
-//! folded SH probe: the slot rides the record table (w bits 1..14) and the shader reads the
-//! probe region of the SAME shared light buffer every material binds; live point lights are
-//! zero (folded at spawn), fog is the interior triple. Exterior props take the Matte
-//! fixed-1.0 sun family ([`WORD_MATTE`]). Declined and censused, not absorbed: exterior
-//! FADER props (the exile protocol has no prop shape — they keep the default path's own
-//! per-entity fade) and props of instance-less placements (no PVS identity). With B4, the
-//! armed lane leaves A's merge only the divert's declined families; the default flip is a
-//! later record's question. `WOW_STATIC_GX_PROP=0` is the lane-isolation lever.
-//!
-//! **Slice-2 verdict (2026-08-18):** floors exactly 0 on all 11 scenarios; the armed A/B
-//! reads MAE ≤ 0.003 with 99.9 % of differing pixels at exactly 1/255 and 2–35 px/frame
-//! beyond 8 (isolated silhouette-edge pixels) — the arithmetic floor of a baked
-//! re-expression, not a lane error; the tram (near-origin placements) matches at exactly 0.
-//! LBRS agreement: entity-lane WMO drops 33 → 0 drawn while the retained pass selects 2
-//! groups / 52 items, stable over the 300-frame window — the flood as range selection, no
-//! leak. Three desk-found laws this slice: texture-array layers DEDUPE by texture (per-item
-//! layers blew the 2,048 D2-array limit the moment Stormwind baked); the bake's position leg
-//! runs in f64 (`bake.rs` owns the note — the f32 world intermediate was 0974's defect
-//! reintroduced, half a pixel indoors); and a colour-less batch multiplies by CONSTANT 1.0,
-//! never the interpolated white (GPU interpolation of a constant is 1.0±ε and re-rounded
-//! ~half of all textured pixels one byte down). `WOW_STATIC_GX_WMO=0` is the lane-isolation
-//! lever that attributed the residue; `WOW_GX_CENSUS=1` is the agreement instrument; the
-//! `house-north-midnight` fixture is the one capture where SIDN is live pixels.
+//! Declined batches fall through to the merge or entity path, counted in a census: env-mapped
+//! (`texture_unit_lookup > 2`, view-generated UVs), depth-flagged, the `ShadeSel::Rig` family,
+//! exterior fader props, and props of a placement without a portal instance.
 
 use bevy::camera::primitives::Aabb;
 use bevy::mesh::MeshVertexAttribute;
@@ -150,32 +38,20 @@ pub use torch_depth::{
 };
 pub(crate) use torch_depth::register_shared as register_torch_shared;
 
-/// The doodad spatial cell — ¼ ADT tile, the same 133⅓-yd locality key the merge lanes use
-/// (`terrain_stream::merge::CELL`; 1413 round 2 proved the locality load-bearing).
+/// The doodad spatial cell, a quarter ADT tile (133⅓ yd), as `terrain_stream::merge::CELL`.
 const CELL: f32 = 533.333_3 / 4.0;
 
-/// Quiet frames before a dirty cell's FIRST bake (~¼ s at 60 Hz) — the merge's own close
-/// rationale: fast appearance, consolidation once the admission burst has moved on.
+/// Quiet frames before a dirty cell's first bake (~¼ s at 60 Hz).
 const IDLE_FRAMES: u32 = 15;
-/// Quiet frames before an already-published cell RE-bakes (~2 s) — 1424's spawn-fast/
-/// consolidate-on-quiet shape at bake granularity (B3, decision 1432): the admission trickle
-/// arrives in bursts spaced wider than [`IDLE_FRAMES`], so the short window re-baked cells
-/// once per arrival for minutes (1431 measured the churn); the long window batches a whole
-/// trickle span per re-bake. The cost is arrival latency for content joining an ALREADY-baked
-/// cell (distance-trickle admissions, under fog at the cell's range) — the entity path's own
-/// arrival class, slower by construction.
+/// Quiet frames before a published cell re-bakes (~2 s), wider than the admission trickle's gaps.
 const REBAKE_FRAMES: u32 = 120;
-/// A dirty cell this old re-bakes even if never quiet (~10 s) — the trickle must not be able
-/// to starve a re-bake forever.
+/// A dirty cell this old (~10 s) bakes even if never quiet, so a trickle cannot starve it.
 const MAX_DIRTY_FRAMES: u32 = 600;
 
-/// Per-vertex packed word: texture-array layer in bits 0..16, flag bits above —
-/// see `static_gx.wgsl` (kept in sync by the flush's packing below).
+/// Per-vertex word: the item index in bits 0..16, flag bits above, as `static_gx.wgsl` reads it.
 pub const ATTRIBUTE_GX_WORD: MeshVertexAttribute =
     MeshVertexAttribute::new("Gx_Word", 988_101, VertexFormat::Uint32);
-/// Per-vertex point-light anchor: the PLACEMENT origin (world space) — the entity path anchors
-/// its ≤3-nearest selection at the instance origin (`wow_model.wgsl`), and baking it per vertex
-/// keeps exact parity where the merged-blob path coarsened to the blob origin.
+/// Per-vertex point-light anchor: the placement's world origin, as in `wow_model.wgsl`.
 pub const ATTRIBUTE_GX_ANCHOR: MeshVertexAttribute =
     MeshVertexAttribute::new("Gx_Anchor", 988_102, VertexFormat::Float32x3);
 
@@ -185,87 +61,61 @@ const WORD_UNLIT: u32 = 1 << 18;
 const WORD_FOG_OFF: u32 = 1 << 19;
 const WORD_SHADE_LIT: u32 = 1 << 20;
 const WORD_TEXTURED: u32 = 1 << 21;
-// The WMO lane (slice 2) — mirrors of the entity path's per-material facts:
-// model_flags.x (the WMO surface laws: MOCV inside the clamp, zero point lights)…
+// The WMO lane, the entity path's material facts as bits. model_flags.x: a WMO surface.
 const WORD_WMO: u32 = 1 << 22;
-// …model_flags.z (interior group: the INT/TRANS/EXT batch-class lanes + the interior fog
-// triple)…
+// model_flags.z: an interior group.
 const WORD_INTERIOR: u32 = 1 << 23;
-// …tint.w == 1 / == 2 (the batch's MOBA class lane; EXT is both bits clear)…
+// tint.w == 1 and == 2: the MOBA INT and TRANS classes; EXT has both clear.
 const WORD_CLASS_INT: u32 = 1 << 24;
 const WORD_CLASS_TRANS: u32 = 1 << 25;
-// …sidn.w (the MOMT WINDOW midpoint light)…
+// sidn.w: the MOMT WINDOW midpoint light.
 const WORD_WINDOW: u32 = 1 << 26;
-// …and "this batch AUTHORED vertex colours": the entity shader's VERTEX_COLORS shader-def.
-// The gx layout always carries COLOR (white default), and white is bit-identical through
-// every lane EXCEPT the INT ×(1+4·MOCV.a) self-illumination override — the entity path's
-// colourless INT batch takes the no-COLORS combine (plain tex × lit), so the override must
-// key on authored colours, not on the lane.
+// The batch authors vertex colours. White passes every lane unchanged except INT's
+// ×(1 + 4·MOCV.a) self-illumination, which a colourless entity batch skips, so it keys on this.
 const WORD_HAS_VC: u32 = 1 << 27;
-// The prop lane (B4, decision 1433) — an exterior WMO MODD prop's Matte sun family: intensity
-// FIXED 1.0 (`ShadeSel::Matte`, the mid-band selector — the ADT 2.5 site is one a MODD prop
-// never reaches, §8b). A distinct bit rather than an alias of SHADE_LIT: under the recorded
-// `min(I,1)` cap the two read identically today, but the cap is the lane's one unfaithful
-// term (0803 §3) and lifting it must not silently split this lane's parity.
+// `ShadeSel::Matte`, fixed 1.0: a map doodad never reaches the 2.5 site (`0x69e4ad`). Not
+// `WORD_SHADE_LIT`, so lifting the shader's `min(I, 1)` cap leaves this at 1.0.
 const WORD_MATTE: u32 = 1 << 28;
-// An INTERIOR M2 prop (B4) is WORD_INTERIOR with WORD_WMO clear — exactly the entity shader's
-// `interior_prop = flags.z && !flags.x`: the per-item SH-probe lane (record-table slot),
-// interior fog, zero live point lights (the group-MOLR lobes are folded into the probe).
+// An interior M2 prop is WORD_INTERIOR with WORD_WMO clear, the entity shader's `interior_prop =
+// flags.z && !flags.x`: SH-probe light from its record slot, interior fog, no live point lights.
 
-/// Armed? **ON by default** (decision 1434: the B chapter's population story is complete —
-/// B1–B4 — with pixel parity at the quantization floor, legs negative at all four pins, and
-/// the director's eye passed at the pins). `WOW_STATIC_GX=0` is the opt-out lever — the A/B
-/// arm for every comparison this chapter still owes; `=1` still reads as an explicit on for
-/// anything that predates the flip. Read once; the plugin registers nothing when off.
+/// On unless `WOW_STATIC_GX=0`; read once, and the plugin registers nothing when off.
 pub fn enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_STATIC_GX").as_deref() != Ok("0"))
 }
 
-/// `WOW_WMO_BIAS=0` — B38's A/B diagnostic, honoured exactly where `model_material` honours
-/// it: the authored batch-order nudge bakes as zero.
+/// `WOW_WMO_BIAS=0`: the authored batch-order nudge bakes as zero, as in `model_material`.
 fn wmo_bias_disabled() -> bool {
     static OFF: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *OFF.get_or_init(|| matches!(std::env::var("WOW_WMO_BIAS").as_deref(), Ok("0")))
 }
 
-/// `WOW_STATIC_GX_WMO=0` — the slice-2 lane-isolation lever: the WMO half of the divert
-/// refuses wholesale (batches fall to the entity path), cells unaffected. Built for the
-/// parity sweep's attribution question — "is this dust the WMO film or a doodad regression?"
-/// — and kept: any future A/B on one lane needs exactly this.
+/// `WOW_STATIC_GX_WMO=0`: WMO group batches fall back to the entity path; cells are unaffected.
 fn wmo_lane_disabled() -> bool {
     static OFF: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *OFF.get_or_init(|| matches!(std::env::var("WOW_STATIC_GX_WMO").as_deref(), Ok("0")))
 }
 
-/// `WOW_STATIC_GX_FADE=0` — the B2 lane-isolation lever (the WMO lever's twin, decision
-/// 1431): fader batches fall back to the entity path wholesale; never-fade cells and WMO
-/// regions unaffected. The attribution instrument for any fader-lane A/B.
+/// `WOW_STATIC_GX_FADE=0`: fader batches fall back to the entity path; the rest is unaffected.
 pub(crate) fn fade_lane_disabled() -> bool {
     static OFF: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *OFF.get_or_init(|| matches!(std::env::var("WOW_STATIC_GX_FADE").as_deref(), Ok("0")))
 }
 
-/// `WOW_STATIC_GX_PROP=0` — the B4 lane-isolation lever (the family's third): WMO-prop
-/// batches refuse wholesale and fall back to the merge/entity path, cells and WMO regions
-/// unaffected. The attribution instrument for any prop-lane A/B.
+/// `WOW_STATIC_GX_PROP=0`: WMO-prop batches fall back to the merge or entity path.
 fn prop_lane_disabled() -> bool {
     static OFF: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *OFF.get_or_init(|| matches!(std::env::var("WOW_STATIC_GX_PROP").as_deref(), Ok("0")))
 }
 
-/// `WOW_GX_PERF=1` — the lane's own cost meter (1431's regression hunt): each armed system
-/// accumulates its wall time into [`GX_PERF`], and the cull prints + zeroes the set at
-/// ~1 Hz — `GX_PERF flush/cull/publish/prepare/node ms-per-frame`. Main-world and
-/// render-world sites share the table (atomics; the two threads never contend on cadence).
+/// `WOW_GX_PERF=1`: system wall times into [`GX_PERF`], printed and zeroed every 64 frames.
 pub(crate) fn gx_perf_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_GX_PERF").is_some())
 }
 
-/// Lifetime bytes of texture-array VRAM created by `assemble_region` (never decremented —
-/// a high-water ledger of what the per-cell arrays cost; the cache drop path frees the
-/// textures but the meter's question is how much this design ALLOCATES).
+/// Lifetime bytes of texture-array VRAM the pool has allocated, never decremented.
 pub(crate) static GX_VRAM: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
 
 /// Nanosecond accumulators: flush, cull, publish, prepare, node.
@@ -277,8 +127,7 @@ pub(crate) static GX_PERF: [std::sync::atomic::AtomicU64; 5] = [
     std::sync::atomic::AtomicU64::new(0),
 ];
 
-/// Scope guard timing one armed site into [`GX_PERF`] slot `i` — one line at the top of
-/// each measured fn; a no-op branch when the meter is off.
+/// Scope guard adding one site's wall time to [`GX_PERF`] slot `i`; a no-op when the meter is off.
 pub(crate) struct GxPerfGuard(Option<(usize, std::time::Instant)>);
 impl Drop for GxPerfGuard {
     fn drop(&mut self) {
@@ -294,20 +143,15 @@ pub(crate) fn gx_perf_guard(i: usize) -> GxPerfGuard {
     GxPerfGuard(gx_perf_enabled().then(|| (i, std::time::Instant::now())))
 }
 
-/// One diverted batch, held until its cell bakes (and retained after, so an owner-tile unload
-/// or a later admission can re-bake the cell without the entity path's help).
+/// One diverted batch, kept after its cell bakes so an unload or a later admission can re-bake.
 struct GxItem {
     geometry: Arc<RenderSubmesh>,
     transform: Transform,
-    /// This item's placement identity — what the inspector/`WOW_PICK` name when the cursor lands
-    /// on it (decision 1534). Shared per placement, so a 40-batch building costs one allocation.
+    /// The placement identity the pick names, shared by the placement's batches.
     object: Arc<crate::interact::WorldObject>,
-    /// The batch's model-local bound (the render form's build-time `Aabb`), kept for the pick's
-    /// broad phase — the drawn side recentres and unions its bounds per cell, which cannot
-    /// answer "which batch is under the cursor". `None` ⇒ narrow-tested unconditionally.
+    /// The batch's model-local bound for the pick's broad phase; `None` is always narrow-tested.
     local_aabb: Option<Aabb>,
-    /// The owner TILE — read only by [`StaticGx::release_owner`], i.e. only for cell items.
-    /// A WMO region's lifecycle keys on its instance entity instead (see `cull::cull_cells`).
+    /// The owner tile, read only by [`StaticGx::release_owner`]; regions follow their instance.
     owner: (i32, i32),
     texture: Option<AssetId<bevy::image::Image>>,
     /// Kept as a live handle so the render world's `GpuImage` can never be dropped from under
@@ -323,61 +167,43 @@ struct GxItem {
     shade_lit: bool,
     wrap_x: bool,
     wrap_y: bool,
-    /// The exterior-prop Matte sun family (B4): intensity fixed 1.0. False everywhere else.
+    /// The `ShadeSel::Matte` sun family, intensity fixed at 1.0.
     matte: bool,
-    /// `Some` on a WMO group-geometry item (slice 2) — the per-batch WMO facts the shader's
-    /// WMO lanes read.
     wmo: Option<GxItemWmo>,
-    /// `Some` on a WMO-prop item (B4, decision 1433) — the referrer-set index + probe slot.
     prop: Option<GxItemProp>,
-    /// `Some(uid)` on a FADER item (B2, decision 1431): the placement this item exiles with.
-    /// The flush maps post-sort item indices back to the cell's [`GxFader`] through it.
+    /// `Some(uid)` on a fader item: the placement it exiles with.
     fader: Option<u32>,
 }
 
-/// A WMO-prop item's baked facts (B4): which of its region's referrer SETS admits it (the
-/// index into [`GxCell::sets`] — the PVS admission ORs over the set's rooms, the entity
-/// path's `WmoGroupVis::drawn_by` at range-selection grain), and the interior prop's folded
-/// SH-probe slot (`None` = exterior light: an exterior MODD prop, or a probe-table overflow —
-/// the entity path's own fallback).
+/// A WMO-prop item's referrer set (an index into [`GxCell::sets`]) and folded SH-probe slot;
+/// `None` takes exterior light, as on the entity path.
 struct GxItemProp {
     set: u16,
     slot: Option<u16>,
 }
 
-/// One fader placement's exile seed + live state (B2, decision 1431): everything needed to
-/// respawn the placement's diverted batches as ordinary entities the frame the camera enters
-/// its feather band, and to punch its retained items out (the per-item kill bit) while any
-/// state but Steady holds. Lives in its cell, keyed by placement uniqueId; released with the
-/// owner tile exactly like the items.
+/// One fader placement's exile seed and state, keyed by uniqueId and released by owner tile.
 struct GxFader {
     owner: (i32, i32),
     uid: u32,
-    /// The placement's identity — carried onto the exiled entities' `WorldObject` so a feathering
-    /// doodad names the same thing whichever lane is drawing it that frame.
+    /// Carried onto the exiled entities, so the pick names the same placement in either lane.
     object: Arc<crate::interact::WorldObject>,
     transform: Transform,
     radius: f32,
-    /// Model-local fade-sphere centre; `transform` maps it to [`Self::center`].
     local_center: Vec3,
-    /// World-space fade-sphere centre — the scan measures horizontal distance to THIS, the
-    /// same point `apply_model_visibility` measures to (`FUN_006952a0`'s transformed centre).
+    /// World fade-sphere centre, which the scan measures horizontal distance to: the reference's
+    /// transformed centre (`0x6952a0`).
     center: Vec3,
-    /// Band edges from [`crate::model_fade::fade_band`] — the cell ring test's terms. The
-    /// state machine itself classifies on `doodad_fade_alpha` directly (one source).
+    /// Band edges from [`crate::model_fade::fade_band`], for the cell ring test only.
     near: f32,
     far: f32,
-    /// One seed per diverted batch, in divert order.
     batches: Vec<GxFaderBatch>,
-    /// This placement's item indices in the CURRENT bake (post-sort; refreshed by every
-    /// flush). Empty until the cell first bakes after the placement diverts.
+    /// This placement's item indices in the current bake, refreshed by every flush.
     items: Vec<u16>,
     state: FaderState,
 }
 
-/// One diverted batch's respawn payload — handle clones of exactly what the production
-/// assembler would have spawned (`assemble.rs`'s ordinary-part bundle), so the feather-band
-/// look is the entity path's own by construction.
+/// One diverted batch's respawn payload: handle clones of the bundle `assemble.rs` would spawn.
 struct GxFaderBatch {
     stat_mesh: Handle<Mesh>,
     aabb: Option<bevy::camera::primitives::Aabb>,
@@ -387,23 +213,18 @@ struct GxFaderBatch {
     geometry: Arc<RenderSubmesh>,
 }
 
-/// The exile state machine (B2). Steady = retained draws it (fade 1, no entity); Exiled =
-/// the placement lives as ordinary entities (the feather is the entity path's own look),
-/// kill bits set once `armed`; Gone = kill bits set, nothing drawn (fully faded — the
-/// entity path culls at alpha 0, this lane never spawns the rows at all).
+/// A fader's exile state. Steady: drawn retained at fade 1. Exiled: drawn as ordinary entities,
+/// its retained items killed once `armed`. Gone: fully faded, killed, nothing spawned.
 ///
-/// `armed` is the overlap protocol's one-frame delay: a fresh exile's entities flush at the
-/// end of `PostUpdate` (see the plugin's `chain_ignore_deferred` note) and first draw NEXT
-/// frame — the scan arms the kill bit on that same next frame, so the retained item dies in
-/// the rendered frame the entity appears. Killing on the spawn frame would open a one-frame
-/// hole: 1421's pop class.
+/// `armed` waits a frame: a fresh exile's entities first draw the next frame, so killing its
+/// retained items on the spawn frame would leave a one-frame hole.
 enum FaderState {
     Steady,
     Exiled { ents: Vec<Entity>, armed: bool },
     Gone,
 }
 
-/// A WMO item's baked facts (see [`GxWmoBatch`] for provenance).
+/// A WMO item's baked facts (see [`GxWmoBatch`]).
 struct GxItemWmo {
     group: u16,
     interior: bool,
@@ -420,97 +241,71 @@ struct GxItemWmo {
     class_lane: u8,
     sidn: [u8; 3],
     window: bool,
-    /// The authored batch order for the clip-z nudge (`sun_scale.y`'s mirror); zeroed when
-    /// `WOW_WMO_BIAS=0` exactly like `model_material`.
+    /// The authored batch order for the clip-z nudge; 0 under `WOW_WMO_BIAS=0`.
     order: u16,
 }
 
-/// A cell's collected items + bake state.
+/// A cell's or region's collected items and bake state.
 #[derive(Default)]
 struct GxCell {
     items: Vec<GxItem>,
     dirty: bool,
     last_change: u32,
-    /// The frame `dirty` last went false→true — [`MAX_DIRTY_FRAMES`]'s clock.
+    /// The frame `dirty` last went from false to true: [`MAX_DIRTY_FRAMES`]'s clock.
     dirty_since: u32,
-    /// The cell's fader placements (B2), keyed by placement uniqueId. Empty on WMO regions.
+    /// The cell's fader placements by uniqueId; empty on regions.
     faders: bevy::platform::collections::HashMap<u32, GxFader>,
-    /// The published kill bitmap no longer matches the fader states (a re-bake reassigned
-    /// item indices, or a state transitioned) — the scan rebuilds it whole and bumps the
-    /// draw's revision.
+    /// The published kill bitmap no longer matches the fader states; the scan rebuilds it.
     bits_stale: bool,
-    /// XZ bounds over the faders' sphere centres (the scan's cheap ring test); rebuilt on
-    /// insert/release.
+    /// XZ bounds of the faders' centres, for the scan's ring test.
     fader_bounds: Option<(Vec2, Vec2)>,
-    /// `(min near, max far)` over the cell's faders — the ring test's band union. Only read
-    /// while `faders` is non-empty.
+    /// `(min near, max far)` over the cell's faders: the ring test's band union.
     ring: (f32, f32),
-    /// The scan's last wholesale verdict for this cell (`None` = mixed/unknown → walk every
-    /// frame). A repeated all-steady / all-gone verdict skips the per-placement walk.
+    /// The scan's last wholesale verdict (all steady or all gone); `None` walks every frame.
     settled: Option<bool>,
-    /// The DISTINCT referrer sets of this region's prop items (B4; prop regions only —
-    /// empty on cells and WMO regions). An item's [`GxItemProp::set`] indexes here; content
-    /// dedup means props named by the same rooms share one selection bit and one run key.
+    /// A prop region's distinct referrer sets, indexed by [`GxItemProp::set`].
     sets: Vec<Arc<[u16]>>,
 }
 
-/// The main-world collector + the published draw set. One resource carries both halves so the
-/// divert (spawn), the flush, the unload hook and the cull all see one consistent state.
+/// The main-world collector and its published draw set.
 #[derive(Resource, Default)]
 pub struct StaticGx {
     cells: bevy::platform::collections::HashMap<(i32, i32), GxCell>,
-    /// The WMO regions (slice 2), keyed by placement instance entity — the same identity the
-    /// portal PVS is computed on, so range selection needs no translation table.
+    /// The WMO regions, keyed by placement instance entity, the portal PVS's own key.
     wmos: bevy::platform::collections::HashMap<Entity, GxCell>,
-    /// The PROP regions (B4, decision 1433), keyed by the SAME instance entity but held
-    /// apart from [`Self::wmos`] deliberately: props trickle in over seconds as their M2s
-    /// load, and sharing the building's region would convert every arrival into a re-bake
-    /// of the whole building's geometry — the exact churn class B3 paid down.
+    /// The prop regions, keyed by the same instance entity but apart from [`Self::wmos`]: props
+    /// trickle in as their M2s load, and sharing would re-bake the building per arrival.
     props: bevy::platform::collections::HashMap<Entity, GxCell>,
-    /// The published, extracted half — what the render node draws.
+    /// The published half the render node draws.
     pub(crate) world: render::GxWorld,
     frame: u32,
-    /// Declined-batch census (env-map / depth-flag / shade-family / prop-fader /
-    /// prop-without-instance refusals), logged once a streaming burst settles so a
-    /// silently-thinner population can't masquerade as covered (1429's no-silent-caps note).
+    /// Declined-batch census: env-map, depth-flag, shade-family, prop-fader, prop-no-instance.
     declined: [u32; 5],
     declined_logged: [u32; 5],
-    /// The census's last-seen counts, the frame they last MOVED, and the frame it last PRINTED —
-    /// the settle timer that turns a login's per-frame line storm into one line per burst. Before
-    /// it, the census fired on ANY count change from a `PostUpdate` system that runs every frame,
-    /// so streaming in a zone emitted a near-identical INFO line per frame (ten of them in one
-    /// Goldshire login). The two frame stamps are distinct on purpose: the settle window measures
-    /// from the last change, the ceiling from the last line, or a count that moves every frame
-    /// resets its own deadline forever and never reports.
+    /// The census's last-seen counts, the frame they last moved and the frame it last printed:
+    /// with one stamp, a count that moves every frame would never print.
     declined_seen: [u32; 5],
     declined_changed: u32,
     declined_printed: u32,
-    /// Batches the divert ACCEPTED, against which the refusals above are read. Without it the
-    /// census line cannot distinguish "1,630 declined out of ~25,000" from "the pass is dead" —
-    /// which is exactly the reading it forced when a log was triaged on 2026-09-06.
+    /// Printed beside the refusals, so a thin population never reads as a dead pass.
     accepted: u32,
-    /// Exiled entities whose seed died out from under them (owner release, map clear) —
-    /// drained and despawned by the scan, which owns the exile lifecycle end to end.
+    /// Exiled entities whose seed died (owner release, map clear), despawned by the next scan.
     pending_despawn: Vec<Entity>,
-    /// Lifetime exile-event counters (spawns, re-admits, gone-despawns) — the census line's
-    /// churn instrument.
+    /// Lifetime exile events for the census: spawns, re-admits, gone-despawns.
     fade_events: [u32; 3],
-    /// [`StaticGx::flush_now`]'s request: the next flush ignores every quiet window. Consumed
-    /// (cleared) by that flush.
+    /// [`StaticGx::flush_now`]'s request, cleared by the next flush.
     flush_now: bool,
 }
 
-/// The divert hook's per-call facts (everything is in scope at `assemble.rs`'s gate).
+/// The divert hook's per-call facts, gathered at `assemble.rs`'s gate.
 pub struct GxBatch<'a> {
     pub geometry: &'a Arc<RenderSubmesh>,
     pub transform: Transform,
-    /// The placement's shared identity — the pick's answer for geometry no entity owns (1534).
+    /// The placement's shared identity, the pick's answer for geometry no entity owns.
     pub object: &'a Arc<crate::interact::WorldObject>,
-    /// The batch's model-local build-time bound (the render form's `Aabb`) — the pick's broad
-    /// phase.
+    /// The batch's model-local build-time bound, for the pick's broad phase.
     pub aabb: Option<Aabb>,
-    /// The owner tile (cell items' release key; unread for WMO items — their region follows
-    /// the instance entity's lifetime).
+    /// The owner tile: a cell item's release key, unread for region items.
     pub owner: (i32, i32),
     pub texture: Option<Handle<bevy::image::Image>>,
     pub blend: ModelBlend,
@@ -520,36 +315,27 @@ pub struct GxBatch<'a> {
     pub env_map: bool,
     pub no_depth_write: bool,
     pub no_depth_test: bool,
-    /// Unread on the WMO lane (the entity path passes `ShadeSel::Matte` for every WMO batch
-    /// and its material never reads the selector) — the shade refusal applies to cells only.
+    /// Unread for WMO group batches, whose entity material never reads it.
     pub shade: ShadeSel,
-    /// `Some` = a WMO group-geometry batch (slice 2).
+    /// `Some` for a WMO group-geometry batch.
     pub wmo: Option<GxWmoBatch>,
-    /// `Some` = a WMO-prop batch (B4, decision 1433).
+    /// `Some` for a WMO-prop batch.
     pub prop: Option<GxPropBatch>,
-    /// `Some` = a FADER batch (B2, decision 1431): the exile seed. `None` on never-fade
-    /// batches, the WMO lane, and the prop lane (an exterior fader prop never diverts —
-    /// see the assemble gate).
+    /// `Some` for a fader batch: its exile seed. Never set on WMO or prop batches.
     pub fade: Option<GxFadeSeed>,
 }
 
-/// The prop half of [`GxBatch`] (B4): the building's instance entity (the region key, the
-/// PVS source, and the lifecycle — the instance dies with the placement, `refs` and all,
-/// so a prop region needs no owner-tile bookkeeping), the referrer set of rooms naming the
-/// prop (empty = unnamed: always admitted, never exterior-gated — 0784's untagged rule),
-/// and the interior prop's SH-probe slot.
+/// The prop half of [`GxBatch`]: the building's instance entity (region key, PVS source and
+/// lifetime), the rooms naming the prop (empty: always admitted) and its SH-probe slot.
 pub struct GxPropBatch {
     pub instance: Entity,
     pub groups: Arc<[u16]>,
     pub slot: Option<u16>,
 }
 
-/// The fader half of [`GxBatch`] (B2): the placement identity + the respawn payload the
-/// exile protocol spawns the feather-band entity from. Everything is a handle clone of what
-/// the production assembler holds at the divert point, so the exiled entity IS the entity
-/// path's bundle.
+/// The fader half of [`GxBatch`]: the fade sphere and the bundle the exile respawns.
 pub struct GxFadeSeed {
-    /// Bounding-sphere radius (yd, placement-scaled) — selects the fade band.
+    /// Bounding-sphere radius in yards, placement-scaled; selects the fade band.
     pub radius: f32,
     /// Model-local bbox centre; the fade distance is measured to its world image.
     pub local_center: Vec3,
@@ -559,12 +345,9 @@ pub struct GxFadeSeed {
     pub blend: Handle<benilla_assets::materials::WowModelMaterial>,
 }
 
-/// Where the divert hook is standing (`spawn/mod.rs` builds it, `assemble.rs` threads it):
-/// the site decides which population an eligible batch joins and which lifecycle key it
-/// takes — cells release by owner tile, WMO regions by instance death.
+/// The population a diverted batch joins: cells release by owner tile, regions by instance.
 pub enum GxSite<'a> {
-    /// A world-static ADT-doodad placement — cell items, released by owner tile. The exile unit
-    /// (B2) is the placement, identified by the shared [`GxBatch::object`] every site now carries.
+    /// A world-static ADT doodad placement: cell items.
     Doodad { owner: (i32, i32) },
     /// A WMO placement's group geometry: the pre-spawned `WmoPortalInstance` entity + the
     /// model's per-batch group map (`WmoModel::submesh_group`, index-parallel with batches).
@@ -586,14 +369,13 @@ pub enum GxSite<'a> {
     },
 }
 
-/// The WMO half of [`GxBatch`], gathered at the spawn site (`spawn/mod.rs` owns the instance
-/// entity; `assemble.rs` zips the per-batch group index out of `submesh_group`).
+/// The WMO half of [`GxBatch`].
 pub struct GxWmoBatch {
-    /// The placement's `WmoPortalInstance` entity — the region key AND the PVS source.
+    /// The placement's `WmoPortalInstance` entity: the region key and the PVS source.
     pub instance: Entity,
-    /// Absolute group index within the building (the PVS bit this batch's draws select on).
+    /// Absolute group index in the building: the PVS bit this batch selects on.
     pub group: u16,
-    /// This batch's group is a true interior (`MOGI & 0x48 == 0`) — `RenderSubmesh::interior`.
+    /// The group is a true interior (`MOGI & 0x48 == 0`).
     pub interior: bool,
     /// MONKEY (ext-class night law): EXTERIOR-class, but at BUILDING scale — an inn's shell or its
     /// basement stairwell, not a city district's. Resolved at the spawn site from the group's own
@@ -610,22 +392,14 @@ pub struct GxWmoBatch {
     pub sidn: Option<[u8; 3]>,
     /// The MOMT WINDOW midpoint-light flag.
     pub window: bool,
-    /// The authored batch order (batch index + 1) — the coplanar-MOBA clip-z nudge.
+    /// The authored batch order (batch index + 1), for the coplanar-MOBA clip-z nudge.
     pub batch_order: u16,
 }
 
 impl StaticGx {
-    /// **Collected geometry that draws nothing yet** — regions holding items whose bake has not
-    /// published (a first bake still inside its quiet window, [`IDLE_FRAMES`]).
-    ///
-    /// A retained region is a *hole in the frame* between the divert and its first publish: the
-    /// entity path no longer draws that geometry (slice 2 moved WMO group geometry here
-    /// wholesale), so a spawned building whose region has not baked is a building that is not on
-    /// screen. The reveal gate ([`crate::terrain_stream::WorldLoadProgress`]) reads this, which
-    /// is why it is published as a fact rather than left an internal of the bake.
-    ///
-    /// A *re-bake* of an already-published region is deliberately NOT counted: that region keeps
-    /// drawing its previous bake meanwhile, so it is content on screen, not a hole.
+    /// Regions whose first bake has not published: diverted geometry that nothing draws yet, which
+    /// the reveal gate ([`crate::terrain_stream::WorldLoadProgress`]) waits on. A published region
+    /// re-baking still draws its previous bake and does not count.
     pub(crate) fn undrawn_regions(&self) -> usize {
         let world = &self.world;
         let cells = self
@@ -646,10 +420,7 @@ impl StaticGx {
         cells + wmos + props
     }
 
-    /// The WMO lane's headline numbers for an instrument: regions **collected**, regions
-    /// **published** (baked, so drawable at all), and regions the cull **selected** this frame.
-    /// Collected-but-unpublished is the reveal hole [`Self::undrawn_regions`] counts; published
-    /// minus selected is ordinary culling.
+    /// WMO regions collected, published (baked, so drawable) and selected by this frame's cull.
     pub fn wmo_census(&self) -> (usize, usize, usize) {
         (
             self.wmos.len(),
@@ -658,12 +429,7 @@ impl StaticGx {
         )
     }
 
-    /// What this frame's scene walk actually **selected to draw** — doodad/prop draw entries,
-    /// WMO regions selected, and the admitted group bits summed across them. The companion to
-    /// [`Self::wmo_census`]: that one says what geometry EXISTS and is drawable, this one says
-    /// how much of it the cull let through. A frame where everything is published and almost
-    /// nothing is selected is a visibility fault, not a residency one — the distinction the
-    /// reveal audit could not make.
+    /// What this frame's walk selected: doodad-phase entries, WMO regions, and admitted WMO groups.
     pub fn draw_census(&self) -> (usize, usize, usize) {
         let groups = self
             .world
@@ -678,21 +444,12 @@ impl StaticGx {
         )
     }
 
-    /// **Bake every dirty region on the next flush, quiet window or not** — what the reveal gate
-    /// asks for once nothing more is arriving.
-    ///
-    /// The quiet windows ([`IDLE_FRAMES`]/[`REBAKE_FRAMES`]) exist to batch an *arrival trickle*
-    /// during play. The end of a load is not a trickle: the streamer knows the burst is over
-    /// (every wanted tile spawned, every focus placement up, the collider queue quiet), and
-    /// waiting another 15 frames there is 15 frames of a city that has spawned and cannot draw.
-    /// So the end of the burst says "publish what you have" instead of arming another timer.
+    /// Bake every dirty region on the next flush, quiet or not: the reveal gate's end of a load.
     pub(crate) fn flush_now(&mut self) {
         self.flush_now = true;
     }
 
-    /// Take one eligible batch instead of spawning it (or merging it). Returns `false` — and
-    /// tallies why — when the batch's facts fall outside the prototype's lane; the caller then
-    /// falls through to the ordinary path, exactly like a refused merge divert.
+    /// Take one batch instead of spawning or merging it; `false` sends it down the ordinary path.
     pub fn divert(&mut self, b: GxBatch<'_>) -> bool {
         if b.env_map {
             self.declined[0] += 1;
@@ -703,26 +460,14 @@ impl StaticGx {
             return false;
         }
         if b.wmo.is_some() && wmo_lane_disabled() {
-            return false; // the lane-isolation lever: WMO batches back to the entity path
+            return false;
         }
         if b.prop.is_some() && prop_lane_disabled() {
-            return false; // the B4 lever: prop batches back to the merge/entity path
+            return false;
         }
-        // The shade family gates CELLS only: the WMO lane never reads the selector (the
-        // entity path passes `Matte` for every WMO batch and lights on the FFP N·L).
-        //
-        // **`Matte` is now BOTH doodad classes' family, not just the prop lane's** (2050): an
-        // ADT map doodad is fixed-1.0 exactly like an exterior MODD prop, because they are one
-        // C++ class (`CMapDoodadDef`) and the 2.5 belongs to the WENTITY node, which neither
-        // has. So the arm no longer requires `prop.is_some()`. `Shaded` still lands on neither
-        // bit and still reads 0.5, because the shader's `shade_t` defaults to 1.0 without
-        // `WORD_SHADE_LIT`.
-        //
-        // That leaves `ShadeSel::Lit` with no producer in this lane at all — its three
-        // populations are ADT doodads, WMO group geometry and WMO props, and entities (the only
-        // holders of a light node) never divert here. The arm is kept as a backstop rather than
-        // deleted: retiring `WORD_SHADE_LIT` and its shader branch is a word-layout change and
-        // wants its own round, named in 2050 rather than folded in here.
+        // WMO group batches light on the FFP N·L and skip this. ADT doodads and MODD props are one
+        // class (`CMapDoodadDef`), `Matte` at 1.0: the 2.5 is the entity light node's, which
+        // neither has. `Shaded` reads 0.5; `Lit` has no producer here and is a backstop.
         let (shade_lit, matte) = match (&b.wmo, &b.prop, b.shade) {
             (Some(_), _, _) => (false, false),
             (None, _, ShadeSel::Matte) => (false, true),
@@ -763,8 +508,7 @@ impl StaticGx {
                 self.cells.entry(cell).or_default()
             }
         };
-        // A prop item resolves its referrer set to the region's dedup list (B4): same rooms
-        // ⇒ same selection bit ⇒ same run key, and the cull tests each distinct set once.
+        // Props named by the same rooms share one set index, so the cull tests each set once.
         let prop = b.prop.map(|p| {
             let set = match entry
                 .sets
@@ -782,15 +526,11 @@ impl StaticGx {
                 slot: p.slot,
             }
         });
-        // A fader batch (B2) registers its exile seed on the cell's placement entry. Fresh
-        // placements start Steady; the scan classifies them against the live camera the same
-        // frame their cell bakes (states run before the bitmap rebuild), so a placement that
-        // streams in beyond its band never draws retained for even one frame.
+        // A new fader is Steady until the scan classifies it the frame its cell bakes, before the
+        // bitmap rebuild, so one streaming in past its band never draws retained.
         let fader_uid = b.fade.as_ref().map(|_| b.object.id);
         if let Some(seed) = b.fade {
-            // A never-fade radius cannot reach here (the assemble gate builds a seed only
-            // for `!class.never_fade`), but a MAX band is the honest fallback: it reads
-            // "always steady", which IS never-fade semantics.
+            // Only faders carry a seed; a band-less radius reads as always steady.
             let (near, far) =
                 crate::model_fade::fade_band(seed.radius).unwrap_or((f32::MAX, f32::MAX));
             let uid = b.object.id;
@@ -818,8 +558,7 @@ impl StaticGx {
                 geometry: b.geometry.clone(),
             });
             if is_new {
-                // A later batch of the same placement shares its sphere and band — the
-                // ring/bounds caches move only when a placement joins.
+                // A placement's later batches share its sphere: the caches move only on a new one.
                 let c = Vec2::new(fader.center.x, fader.center.z);
                 entry.fader_bounds = Some(match entry.fader_bounds {
                     Some((mn, mx)) => (mn.min(c), mx.max(c)),
@@ -862,22 +601,15 @@ impl StaticGx {
         true
     }
 
-    /// Tally a prop-site refusal the divert never sees (B4): an exterior FADER prop (the
-    /// exile protocol has no prop shape — it keeps today's per-entity fade, the default
-    /// path's own look), or a whole prop on a placement WITHOUT an instance entity (no PVS
-    /// identity to key a region on). Censused so the declined population is never silent.
+    /// Count a prop the divert never sees: an exterior fader prop (the exile protocol has no prop
+    /// shape), or a prop of a placement without an instance entity.
     pub fn tally_prop_declined(&mut self, no_instance: bool) {
         self.declined[if no_instance { 4 } else { 3 }] += 1;
     }
 
-    /// Drop a dead owner tile's items and mark their cells for re-bake — the unload hook
-    /// (`terrain_stream`'s release loop calls this beside the straddler handoff; a diverted
-    /// batch has no entity, so nothing else could ever release it).
-    ///
-    /// **Cells only, deliberately.** A WMO region's items follow the placement's INSTANCE
-    /// entity (reaped in `cull::cull_cells` when it despawns): a straddler handoff keeps the
-    /// placement alive under a NEW owner tile, and dropping its retained geometry on the old
-    /// tile's death would blank a living building.
+    /// Drop a dead owner tile's cell items and mark their cells for re-bake; a diverted batch has
+    /// no entity, so nothing else releases it. Regions follow their instance entity instead: a
+    /// straddler handoff keeps a placement alive under a new owner tile.
     pub fn release_owner(&mut self, owner: (i32, i32)) {
         let frame = self.frame;
         let Self {
@@ -895,9 +627,7 @@ impl StaticGx {
                 cell.dirty = true;
                 cell.last_change = frame;
             }
-            // The fader seeds ride the same owner key. An exiled placement's entities are
-            // this lane's own spawns (nothing else knows them), so its death queues them;
-            // the scan drains the queue with `Commands` next pass.
+            // A dead exile's entities are this lane's own: they queue for the scan to despawn.
             let faders_before = cell.faders.len();
             cell.faders.retain(|_, f| {
                 if f.owner != owner {
@@ -926,10 +656,7 @@ impl StaticGx {
         }
     }
 
-    /// Map drop: everything goes (the streamer's `drop_streamed_world` — same staleness law as
-    /// the weld/merge accumulators beside this). Exiled entities queue for despawn — the map
-    /// transition despawns the placement lane's entities through the placement release, but
-    /// the exiles are this lane's own.
+    /// Map drop: everything goes, and the exiles, known only to this lane, queue for despawn.
     pub fn clear(&mut self) {
         let Self {
             cells,
@@ -951,9 +678,7 @@ impl StaticGx {
         self.world.props.clear();
         self.world.visible.clear();
         self.world.visible_wmos.clear();
-        // The census counts THIS world's population. `static_merge::reset` exists for exactly
-        // this reason — a cumulative counter carried across a map change reports the sum of two
-        // worlds and reads as a leak.
+        // The census counts this world only; carried across a map change it reads as a leak.
         self.declined = [0; 5];
         self.declined_logged = [0; 5];
         self.declined_seen = [0; 5];
@@ -973,28 +698,10 @@ impl Plugin for StaticGxPlugin {
         info!("static-gx: ARMED (default since 1434; WOW_STATIC_GX=0 opts out) — the retained static-world pass (1429–1434)");
         app.init_resource::<StaticGx>().add_systems(
             PostUpdate,
-            // Chained: bake, then this frame's scene walk (after the camera settles), then
-            // publish the extractable snapshot.
-            //
-            // `.after(CheckVisibility)` is LOAD-BEARING (B2, 1431): the scan SPAWNS exile
-            // entities via `Commands`, and a `PostUpdate` spawner that runs before the
-            // visibility check can have its queued commands flushed by ANY other system
-            // pair's auto sync point sitting before `CheckVisibility` (this app already has
-            // two: `exterior_cull` and `billboard` both order `.before(CheckVisibility)`
-            // with deferred params). A spawn surfacing there is VISIBLE this frame while
-            // bevy_pbr's per-entity specialization tick — recorded by
-            // `check_entities_needing_specialization`, which may already have run — arrives
-            // only next frame, and `specialize_material_meshes` UNWRAPS the tick of every
-            // visible entity: the render app panics (`bevy_pbr-0.18.1/material.rs:1061`,
-            // reproduced and pinned with a vendored diagnostic — the gap entities were
-            // exactly this scan's exiles, one frame each). Running after `CheckVisibility`
-            // makes the hazard structural nonsense: however early some sync point flushes
-            // our spawns, they cannot be seen by a visibility check that already ran — the
-            // entity is invisible its first frame, ticked and visible together the next,
-            // which is precisely the overlap protocol's arm delay (see `cull.rs`).
-            // `chain_ignore_deferred` keeps this chain from minting sync points of its own;
-            // `CheckVisibility` is itself after `UpdateFrusta`, so the frustum read is this
-            // frame's camera (B1 left that ambiguous — a latent fixed by the same pin).
+            // Bake, scene walk, publish; after `CheckVisibility`, which is load-bearing. A spawned
+            // exile flushed by an earlier sync point would be visible before bevy_pbr ticked its
+            // specialization, a render panic (`bevy_pbr-0.18.1/material.rs:1061`); after it, the
+            // exile shows the next frame, ticked. `chain_ignore_deferred` adds no sync points.
             (
                 bake::flush_static_gx,
                 cull::cull_cells,
@@ -1013,7 +720,7 @@ pub(crate) mod testkit {
     //! Shared test fixtures for the collector/bake test modules.
     use super::*;
 
-    /// A test placement identity — `uid` is the id the fader lane keys its exile unit on.
+    /// A test placement identity; `uid` keys the fader lane's exile unit.
     pub fn object(uid: u32) -> Arc<crate::interact::WorldObject> {
         Arc::new(crate::interact::WorldObject {
             kind: crate::model_render::ModelKind::Doodad,
@@ -1023,8 +730,7 @@ pub(crate) mod testkit {
         })
     }
 
-    /// The one identity [`batch`] borrows — a test that needs distinct placements uses
-    /// [`batch_of`] with its own [`object`].
+    /// The one identity [`batch`] borrows; distinct placements use [`batch_of`].
     fn shared_object() -> &'static Arc<crate::interact::WorldObject> {
         static O: std::sync::OnceLock<Arc<crate::interact::WorldObject>> =
             std::sync::OnceLock::new();
@@ -1084,10 +790,6 @@ mod tests {
     use super::testkit::{batch, batch_of, object, tri};
     use super::*;
 
-    /// A diverted batch is collected geometry that draws NOTHING until its region bakes — the
-    /// reveal hole [`StaticGx::undrawn_regions`] exists to publish, and the fact the reveal gate
-    /// keys on (decision 1498). Publishing the region clears it; a re-bake of a published region
-    /// is not a hole, because the previous bake is still on screen.
     #[test]
     fn a_collected_region_is_undrawn_until_it_publishes() {
         let mut gx = StaticGx::default();
@@ -1099,22 +801,12 @@ mod tests {
         );
         assert!(gx.divert(batch(&g, Vec3::ZERO, None, ModelBlend::Opaque)));
         assert_eq!(gx.undrawn_regions(), 1, "diverted, unbaked — a hole");
-        // What the bake does when it publishes a region: clears `dirty`.
+        // Publishing a region clears `dirty`.
         let cell = *gx.cells.keys().next().unwrap();
         gx.cells.get_mut(&cell).unwrap().dirty = false;
         assert_eq!(gx.undrawn_regions(), 0, "baked — on screen");
     }
 
-    /// The collector refuses exactly the recorded exclusion families — and says so in the
-    /// census — while an eligible batch diverts (1429's no-silent-caps note).
-    ///
-    /// **The shade-family exclusion is `Rig` now, not `Matte`** (2050). A cell arriving `Matte`
-    /// used to be refused, but only because nothing could produce one: ADT doodads were on
-    /// `Lit`, props carried `prop: Some`, group geometry `wmo: Some`. Since ADT doodads are the
-    /// fixed-1.0 family — the same C++ class as an exterior MODD prop — a `Matte` cell is the
-    /// ordinary case and MUST divert, which is what the added assertion below pins. What is left
-    /// genuinely excluded is the authored-rig booth material, which has no business in the
-    /// world's retained lane at all.
     #[test]
     fn the_divert_declines_the_excluded_families() {
         let mut gx = StaticGx::default();
@@ -1129,7 +821,6 @@ mod tests {
         b.shade = ShadeSel::Rig;
         assert!(!gx.divert(b), "a glue-booth rig material never diverts");
         assert_eq!(gx.declined, [1, 1, 1, 0, 0]);
-        // The ADT doodad's own family: a cell on fixed-1.0, no prop record.
         let mut b = batch(&g, Vec3::ZERO, None, ModelBlend::Opaque);
         b.shade = ShadeSel::Matte;
         assert!(
@@ -1140,9 +831,6 @@ mod tests {
         assert_eq!(gx.cells.len(), 1);
     }
 
-    /// A fader batch (B2) registers its exile seed on the cell — placement-keyed, band from
-    /// the fade law, items tagged with the uid — while a never-fade batch stays bare. The
-    /// same placement's second batch joins the SAME seed (one exile unit).
     #[test]
     fn a_fader_divert_registers_its_placement_seed() {
         let mut gx = StaticGx::default();
@@ -1155,8 +843,7 @@ mod tests {
             cutout: Handle::default(),
             blend: Handle::default(),
         };
-        // The exile unit is keyed by the PLACEMENT identity every lane shares (1534) — one
-        // object, two batches, one seed.
+        // One placement, two batches, one seed; a third, never-fade batch stays bare.
         let fence = object(77);
         let mut a = batch_of(
             &fence,
@@ -1186,7 +873,7 @@ mod tests {
         assert_eq!(cell.faders.len(), 1, "one placement, one exile unit");
         let f = &cell.faders[&77];
         assert_eq!(f.batches.len(), 2);
-        // Band from the fade law's own table: radius 0.4 → 40.4..50.4.
+        // Radius 0.4 takes the fade table's 40.4..50.4 band.
         assert!((f.near - 40.4).abs() < 1e-4 && (f.far - 50.4).abs() < 1e-4);
         assert!(matches!(f.state, FaderState::Steady));
         assert_eq!(cell.ring, (f.near, f.far));
@@ -1197,10 +884,7 @@ mod tests {
         );
     }
 
-    /// A prop batch (B4) diverts into a region keyed by its INSTANCE entity; props naming
-    /// the same rooms share one referrer-set index and a distinct set opens a new one; the
-    /// interior slot and the Matte family ride the item (Matte admits on this lane — still
-    /// refused on cells).
+    /// Props land in their instance's region, not a cell, with slot and Matte bit on the item.
     #[test]
     fn a_prop_divert_dedups_referrer_sets() {
         let mut gx = StaticGx::default();
@@ -1242,8 +926,6 @@ mod tests {
         assert!(gx.props.is_empty() && gx.world.props.is_empty());
     }
 
-    /// A dead owner drops its fader seeds with its items, and an exiled placement's entities
-    /// land on the despawn queue — nothing else knows those entities exist.
     #[test]
     fn a_dead_owner_queues_its_exiles() {
         let mut gx = StaticGx::default();
@@ -1277,8 +959,6 @@ mod tests {
         assert_eq!(gx.pending_despawn, vec![ghost]);
     }
 
-    /// A dead owner's items leave their cells and the re-bake drops to the survivors — the
-    /// unload hook's contract (a diverted batch has no entity; nothing else can release it).
     #[test]
     fn a_dead_owner_leaves_the_cells() {
         let mut gx = StaticGx::default();
diff --git a/crates/benilla-world/src/static_gx/pick.rs b/crates/benilla-world/src/static_gx/pick.rs
index 94ef7531..0c785be8 100644
--- a/crates/benilla-world/src/static_gx/pick.rs
+++ b/crates/benilla-world/src/static_gx/pick.rs
@@ -1,23 +1,7 @@
-//! The retained pass answers the ray — **the lane names what it drew** (decision 1534).
-//!
-//! Slices 1–2 and B4 moved the static world's geometry off per-placement entities into retained
-//! cell/region bakes. The pick declaration ([`crate::interact::PickMesh`] + `WorldObject`) rode
-//! those entities, so the divert took it with them: over an absorbed doodad, building or prop the
-//! inspector, the GO hover and `WOW_PICK` all answered *nothing*, and 0929's "pick geometry is
-//! declared, never inferred" rule made that silence indistinguishable from a correctly transparent
-//! surface. `mod.rs`'s B1 note called it out as a known gap and predicted "one side table if
-//! missed"; this is that table, held where the geometry already is.
-//!
-//! The lane implements [`PickSource`] rather than publishing records to a shared index for one
-//! reason: **only the lane knows what it actually drew this frame.** Its visibility is a CPU scene
-//! walk — frustum + farclip + the exterior window gate at CELL grain, the portal PVS bit per GROUP,
-//! the referrer-set OR per prop SET, and the exile kill bit per fader PLACEMENT — none of which is
-//! a `ViewVisibility` an outside walker could read. So the admission below is the *published
-//! verdict itself* ([`super::render::GxWorld::visible`] / `visible_wmos`, the very lists the render
-//! node draws from), not a re-derivation that could disagree with the pixels.
-//!
-//! Cost is paid only when someone casts: no per-frame bookkeeping exists for this, and the
-//! instruments that cast (the armed inspector, `WOW_PICK`) run at most once a frame.
+//! Picking for the retained pass: a diverted batch has no entity to carry a
+//! [`crate::interact::PickMesh`], so the lane answers the ray as a [`PickSource`]. Admission reads
+//! the published lists the render node draws from ([`super::render::GxWorld::visible`],
+//! `visible_wmos`), so the answer cannot disagree with the pixels.
 
 use std::sync::Arc;
 
@@ -29,8 +13,8 @@ use crate::interact::{ray_member, ray_mesh_bounds, PickSource, RayHit, WorldObje
 impl PickSource for StaticGx {
     fn cast_objects(&self, ray: Ray3d, all_hits: bool, out: &mut Vec<(Arc<WorldObject>, RayHit)>) {
         let (origin, dir) = (ray.origin, *ray.direction);
-        // Broad phase over every admitted item, nearest box entry first — the entity cast's own
-        // shape, so the narrow walk stops as soon as a confirmed hit beats every remaining box.
+        // Broad phase, nearest box entry first as in the entity cast: the narrow walk stops once a
+        // hit beats every remaining box.
         let mut candidates: Vec<(f32, &GxCell, usize)> = Vec::new();
         for entry in &self.world.visible {
             match entry {
@@ -39,9 +23,7 @@ impl PickSource for StaticGx {
                         continue;
                     };
                     gather(cell, origin, dir, &mut candidates, |cell, i| {
-                        // A fader draws retained only while Steady: Exiled means the placement is
-                        // feathering as ordinary entities (which carry their own declaration, and
-                        // would otherwise be named twice), Gone means nothing is drawn at all.
+                        // A fader draws here only while Steady; exiled, its entities answer.
                         match cell.items[i].fader {
                             Some(uid) => matches!(
                                 cell.faders.get(&uid).map(|f| &f.state),
@@ -92,9 +74,8 @@ impl PickSource for StaticGx {
     }
 }
 
-/// Add one region's admitted items to the broad-phase list. An item with no build-time bound is
-/// admitted at entry 0 and narrow-tested unconditionally — the entity cast's rule for a bound-less
-/// part, kept: a missing bound must never un-pick real geometry.
+/// Add one region's admitted items to the broad phase; an item without a bound enters at 0 and is
+/// always narrow-tested, as in the entity cast.
 fn gather<'a>(
     cell: &'a GxCell,
     origin: Vec3,
@@ -129,8 +110,8 @@ mod tests {
     use crate::interact::PickSource;
     use benilla_formats::ModelBlend;
 
-    /// Cast straight down through `tri([0,0,0])`'s footprint — its baked triangle lies in the
-    /// Bevy XZ plane at y = 0 over x,z ∈ [-1, 0] (`wow_to_bevy`).
+    /// Cast straight down through `tri([0,0,0])`, which bakes into the Bevy XZ plane at y = 0 over
+    /// x, z in [-1, 0].
     fn cast(gx: &StaticGx) -> Vec<(String, u32, f32)> {
         let ray = Ray3d::new(Vec3::new(-0.3, 5.0, -0.3), Dir3::NEG_Y);
         let mut out = Vec::new();
@@ -140,8 +121,6 @@ mod tests {
             .collect()
     }
 
-    /// **Decision 1534.** An item the cull SELECTED is named, at its own placement identity and
-    /// its own geometry — the pick answer the divert used to take away with the entity.
     #[test]
     fn a_selected_cell_item_is_named() {
         let mut gx = StaticGx::default();
@@ -153,8 +132,6 @@ mod tests {
             None,
             ModelBlend::Opaque
         )));
-        // Nothing is drawn until the cull selects the cell — and an unselected cell must be as
-        // transparent to the ray as an unculled entity's `ViewVisibility` makes it.
         assert!(cast(&gx).is_empty(), "an unselected cell is not pickable");
         gx.world.visible.push(GxDoodadVis::Cell((0, 0)));
         assert_eq!(
@@ -163,9 +140,7 @@ mod tests {
         );
     }
 
-    /// A fader draws retained only while STEADY. Once it exiles, the placement is drawing as
-    /// ordinary entities that carry their own declaration — so the lane must go quiet, or the
-    /// same tree is named twice, once by each half of the protocol.
+    /// Exiled, the placement draws as entities that carry their own pick, so the lane goes quiet.
     #[test]
     fn an_exiled_fader_stops_answering() {
         let mut gx = StaticGx::default();
diff --git a/crates/benilla-world/src/static_gx/pool.rs b/crates/benilla-world/src/static_gx/pool.rs
index 16d955b1..66203982 100644
--- a/crates/benilla-world/src/static_gx/pool.rs
+++ b/crates/benilla-world/src/static_gx/pool.rs
@@ -1,18 +1,6 @@
-//! The shared texture-array pool of the retained pass (B3, decision 1432; split from
-//! `render.rs` at the line budget — one concern: texture residency for the whole lane).
-//!
-//! B2's legs caught the per-cell array design's two driver taxes red-handed in a `sample` of
-//! the armed process: every re-bake recreated a cell's whole array set (`AGX::TextureGen4`
-//! hot — +154 MB of arrays in a 20-s walk), and the per-cell `pending` copy list was never
-//! drained, so the node re-encoded every visible cell's full layer-copy set EVERY FRAME
-//! (`checkDependentBlits` hot). The pool fixes both structurally: a texture is assigned one
-//! (class, layer) slot for the pool's lifetime — deduped across every cell and region — its
-//! layer copy is encoded ONCE (`drain_pending`, the same frame it is queued), and a re-bake
-//! touches no texture at all. Classes grow by SIBLING (a full class opens a bigger one
-//! beside it, capacity ×4), so an existing array is never replaced and no bind group ever
-//! goes stale; the cost is that runs cannot fuse across siblings, which leaves draw counts
-//! trivial either way. The pool resets only with the map (`prepare_static_gx` sees both
-//! published maps empty).
+//! The retained pass's shared texture-array pool. A texture keeps one (class, layer) slot, deduped
+//! across cells and regions, and its layer copy is encoded once. A full class opens a sibling
+//! rather than growing, so no bind group goes stale. The pool resets only with the map.
 
 use bevy::asset::AssetId;
 use bevy::image::Image;
@@ -21,8 +9,7 @@ use bevy::render::render_resource::*;
 use bevy::render::renderer::{RenderDevice, RenderQueue};
 use bevy::render::texture::GpuImage;
 
-/// One class of the pool: every pooled texture of one (size, format, mips) key, as one
-/// `texture_2d_array` with fixed capacity.
+/// Pooled textures of one (size, format, mips) key in one fixed-capacity `texture_2d_array`.
 struct GxPoolClass {
     size: Extent3d,
     format: TextureFormat,
@@ -32,17 +19,14 @@ struct GxPoolClass {
     capacity: u32,
     /// Layers assigned so far (≤ capacity).
     members: u32,
-    /// Layer copies queued but not yet encoded (source texture, destination layer) — drained
-    /// by [`GxTexturePool::drain_pending`] the SAME frame they are queued, exactly once.
+    /// Queued (source, layer) copies, encoded once by [`GxTexturePool::drain_pending`].
     pending: Vec<(Texture, u32)>,
 }
 
-/// A new class's starting capacity; siblings of a full key open at ×4 (8 → 32 → 128 → …,
-/// clamped to the device layer limit) — geometric growth without ever migrating a layer.
+/// A key's first capacity; each sibling opens at four times the largest, up to the layer limit.
 const POOL_BASE_CAPACITY: u32 = 8;
 
-/// The pool resource (render world). Assignment is stable for the pool's lifetime: a texture
-/// id maps to one (class, layer) until the map clears.
+/// The render-world pool: a texture id keeps its (class, layer) until the map clears.
 #[derive(bevy::prelude::Resource, Default)]
 pub(super) struct GxTexturePool {
     classes: Vec<GxPoolClass>,
@@ -80,8 +64,7 @@ impl GxTexturePool {
         slot
     }
 
-    /// The slot untextured items bind (the shader never samples them — the TEXTURED bit is
-    /// clear — but the bind group needs a D2-array view): a 1×1 white class, created once.
+    /// The 1×1 white class untextured items bind: never sampled, but the bind group needs a view.
     pub(super) fn white(
         &mut self,
         render_device: &RenderDevice,
@@ -128,8 +111,7 @@ impl GxTexturePool {
         self.classes.is_empty()
     }
 
-    /// Find a key's class with a free layer, or open one (a sibling at ×4 when the key's
-    /// classes are all full).
+    /// A key's class with a free layer, opening a new sibling when every one is full.
     fn class_with_room(
         &mut self,
         key: (Extent3d, TextureFormat, u32),
@@ -151,10 +133,7 @@ impl GxTexturePool {
             .max()
             .map_or(POOL_BASE_CAPACITY, |c| c.saturating_mul(4))
             .min(max_layers);
-        // The VRAM ledger (1431's regression hunt): bytes for the array about to be created —
-        // block-compressed at their block rate, else 4 B/texel — ×4/3 for mips, over the full
-        // CAPACITY (what the driver allocates). Pooled, this should go near-flat after the
-        // first minutes; a climbing ledger is the churn coming back.
+        // `GX_VRAM`: the array at capacity, BC at block rate else 4 B/texel, ×4/3 with mips.
         if super::gx_perf_enabled() {
             let per_layer = match key.1 {
                 TextureFormat::Bc1RgbaUnorm | TextureFormat::Bc1RgbaUnormSrgb => {
@@ -202,9 +181,8 @@ impl GxTexturePool {
         self.classes.len() - 1
     }
 
-    /// Encode + submit all queued layer copies (one encoder, one submit, then EMPTY — the
-    /// whole point; queue submissions are ordered, so the copies land before the frame's
-    /// render-graph submit).
+    /// Encode and submit every queued layer copy, emptying the queue; submissions are ordered, so
+    /// the copies land before the frame's render-graph submit.
     pub(super) fn drain_pending(
         &mut self,
         render_device: &RenderDevice,
@@ -228,14 +206,9 @@ impl GxTexturePool {
                     encoder.copy_texture_to_texture(
                         s,
                         dst,
-                        // The **physical** mip extent — rounded up to whole blocks. wgpu-core's
-                        // `validate_texture_copy_range` checks `copy_size % block_dimensions`
-                        // unconditionally (there is no "it's the whole mip" exemption), and a
-                        // BLP's authored chain bottoms out at 2x2 — below a BC block on EVERY
-                        // texture. Uncompressed formats have 1x1 blocks, so this is the identity
-                        // there and the line reads the same for both. Without the round-up, the
-                        // first BC texture pooled here is a validation error, and wgpu's default
-                        // handler makes that a process panic (decision 1626).
+                        // Rounded up to whole blocks: wgpu-core's `validate_texture_copy_range`
+                        // rejects a partial block even for a whole mip, and a BLP chain ends at
+                        // 2x2, under one BC block. Uncompressed blocks are 1x1.
                         Extent3d {
                             width: (class.size.width >> mip).max(1).div_ceil(block_w) * block_w,
                             height: (class.size.height >> mip).max(1).div_ceil(block_h) * block_h,
diff --git a/crates/benilla-world/src/static_gx/render.rs b/crates/benilla-world/src/static_gx/render.rs
index d71860b6..8f46a1fe 100644
--- a/crates/benilla-world/src/static_gx/render.rs
+++ b/crates/benilla-world/src/static_gx/render.rs
@@ -1,19 +1,7 @@
-//! The render-world half of the B1 retained pass (see `mod.rs`; decision 1429): extraction of
-//! the published cell set, per-cell GPU assembly (texture-array classes + the item→layer
-//! table), the pipeline family, and the draw node between the main opaque and transparent
-//! passes.
-//!
-//! Assembly happens where each fact lives: the MAIN world bakes geometry (it owns the
-//! submeshes) but cannot know texture dims/format (BLP images are `RENDER_WORLD`-only), so
-//! classing into `texture_2d_array`s happens HERE, once each member's `GpuImage` is resident.
-//! A cell whose textures aren't all loaded yet simply isn't drawn that frame (the entity path
-//! streams batches in piecewise; cell-granular appearance is the same arrival class, mostly
-//! under the load cover).
-//!
-//! **The arrays are ONE SHARED POOL, not per-cell (B3, decision 1432)** — `pool.rs` owns the
-//! design note (the two driver taxes 1431's `sample` caught, and how dedup + drain-once +
-//! sibling growth remove them structurally). Here, a re-bake costs a record table and a few
-//! bind groups, never a texture.
+//! The render-world half of the retained pass: extraction of the published set, per-region GPU
+//! assembly against the shared texture pool, the pipelines, and the draw node before the main
+//! opaque pass. Texture dims and formats exist only here (BLP images are `RENDER_WORLD`-only), so
+//! a region draws once every member's `GpuImage` is resident.
 
 use bevy::camera::primitives::Aabb;
 use bevy::core_pipeline::oit::OrderIndependentTransparencySettingsOffset;
@@ -50,9 +38,7 @@ use std::ops::Range;
 use bevy::core_pipeline::core_3d::graph::{Core3d, Node3d};
 use bevy::core_pipeline::core_3d::CORE_3D_DEPTH_FORMAT;
 
-/// One baked item's draw facts (index-parallel with the bake order; the vertex word's low bits
-/// carry this item's index, which the record table resolves to an array layer + the WMO
-/// per-item record).
+/// One baked item's draw facts, in bake order: the vertex word's low bits index its record.
 #[derive(Clone)]
 pub(crate) struct GxItemDraw {
     pub index_range: Range<u32>,
@@ -61,16 +47,13 @@ pub(crate) struct GxItemDraw {
     pub two_sided: bool,
     #[allow(dead_code)] // bake-side bookkeeping; the node draws by index range alone
     pub vertex_range: Range<u32>,
-    /// The range-selection key (`None` on cell items — always drawn): a WMO item's GROUP,
-    /// or a prop item's referrer-SET index (B4). A run never crosses a selection boundary,
-    /// so the per-frame verdict selects whole runs.
+    /// The selection key (a WMO group or a prop referrer set); `None` on cell items.
     pub group: Option<u16>,
     /// The authored batch order (the coplanar-MOBA clip-z nudge; 0 on cell items).
     pub order: u16,
     /// The MOMT SIDN night-glow colour (gamma bytes; zero on cell items).
     pub sidn: [u8; 3],
-    /// The interior prop's SH-probe slot (B4; 0 elsewhere — read only under the word's
-    /// INTERIOR-without-WMO lane). Rides the record table's w column, bits 1..14.
+    /// The interior prop's SH-probe slot, record column w bits 1..=13; 0 elsewhere.
     pub slot: u16,
     /// MONKEY (ext-class night law): this is an EXTERIOR-class WMO batch at BUILDING scale — the
     /// record table's bit 27 (see [`RECORD_EXT_NIGHT_BIT`]). False on cells, props and interior
@@ -82,39 +65,31 @@ pub(crate) struct GxItemDraw {
     pub enclosed: bool,
 }
 
-/// One baked cell (or WMO region), published by the main-world flush.
+/// One baked cell or region, published by the main-world flush.
 #[derive(Clone)]
 pub(crate) struct GxCellDraw {
     pub mesh: Handle<Mesh>,
-    /// The recentring origin (0974's precision split): shader world = vertex + origin.
+    /// The recentring origin: shader world = vertex + origin.
     pub origin: Vec3,
     /// Mesh-local bound (recentred); world bound = origin + this.
     pub aabb: Aabb,
     pub draws: Vec<GxItemDraw>,
-    /// The exile kill bitmap (B2, 1431): bit *i* set ⇒ item *i* is punched out of the
-    /// retained draw (its placement is feathering as ordinary entities, or fully faded).
-    /// Rebuilt in place by the main-world scan; all-zero on WMO regions.
+    /// The exile kill bitmap, bit i dropping item i; all-zero on regions.
     pub killed: Vec<u64>,
-    /// Bumped by the scan on every bitmap change — the render side syncs the record table's
-    /// kill column when it sees a revision it hasn't applied.
+    /// Bumped on every bitmap change; the render side re-syncs the kill column on a new one.
     pub killed_rev: u32,
-    /// Per-selection-grain mesh-local bounds (empty for cells): a WMO region's per-GROUP
-    /// bounds, or a prop region's per-referrer-SET bounds (B4) — what the cull's admission
-    /// walk tests.
+    /// Mesh-local bounds per selection key (group or referrer set) for the cull; empty on cells.
     pub groups: Vec<(u16, Aabb)>,
-    /// A prop region's distinct referrer sets (B4), indexed by the same u16 as `groups` /
-    /// item selection: the rooms the PVS admission ORs over (empty set = unnamed — admitted
-    /// bare, never exterior-gated). Empty on cells and WMO regions.
+    /// A prop region's distinct referrer sets, indexed like `groups`.
     pub sets: Vec<std::sync::Arc<[u16]>>,
 }
 
-/// Marks the ONE view the retained pass draws into — the world camera. Without this the node
-/// would run for EVERY Core3d view, including the portrait-booth bakes, and paint world cells
-/// into a portrait with the booth's view matrices (the cull list is the world camera's).
+/// Marks the world camera, the one view the pass draws into, so no portrait-booth view gets
+/// world cells.
 #[derive(Component, Clone, Copy, Default, ExtractComponent)]
 pub(crate) struct StaticGxView;
 
-/// Insert the marker on the world camera (idempotent — the camera can respawn).
+/// Mark the world camera, again whenever it respawns.
 fn mark_world_camera(
     mut commands: Commands,
     cam: Query<Entity, (With<crate::view::WorldCamera>, Without<StaticGxView>)>,
@@ -124,57 +99,42 @@ fn mark_world_camera(
     }
 }
 
-/// One admitted entry of the doodad-phase draw list (B4): ADT-doodad cells and WMO-prop
-/// regions are the SAME drain phase in the 1.12 order (both are the M2 scene, after the WMO
-/// phase), so the cull sorts them near-first TOGETHER — a far cell must not shade before a
-/// near building's furniture.
+/// One entry of the doodad-phase draw list: ADT-doodad cells and WMO-prop regions are one phase
+/// in the 1.12 order (the M2 scene, after the WMOs), so they sort near-first together.
 #[derive(Clone, PartialEq)]
 pub(crate) enum GxDoodadVis {
     Cell((i32, i32)),
-    /// A prop region + this frame's per-referrer-SET verdicts.
     Prop(Entity, GxSel),
 }
 
-/// One region's per-selection-grain verdicts for this frame — a WMO region's grain is the GROUP,
-/// a prop region's the referrer-SET index, and both index these vectors the same way.
+/// One region's verdicts this frame, indexed by group (WMO) or referrer set (props).
 #[derive(Clone, Default, PartialEq)]
 pub(crate) struct GxSel {
     /// Drawn this frame: PVS ∧ frustum ∧ farclip ∧ the exterior window gate.
     pub drawn: Vec<bool>,
-    /// On the interior fog lane — the client's per-group `[0xca7f00]`, resolved by the portal
-    /// flood ([`crate::wmo_portal::GroupPvs::interior_fog`]). Rides beside `drawn` because it is
-    /// the same walk's answer at the same grain, and because the node syncs it into the record
-    /// table exactly where it already syncs the kill column.
+    /// On the interior fog lane: the client's per-group `[0xca7f00]`, from the portal flood
+    /// ([`crate::wmo_portal::GroupPvs::interior_fog`]).
     pub fog: Vec<bool>,
 }
 
-/// The published half the render world clones each frame. The baked regions sit behind `Arc`
-/// (decision 1436): the 1435 band map priced the publish + extract clone pair at 0.39 ms/f —
-/// tens of thousands of `GxItemDraw`s memcpy'd twice a frame — so the per-frame clones are
-/// refcount bumps now, and the ONE writer that mutates a published region (the kill scan's
-/// bitmap rebuild) pays a copy-on-write of that region alone, only on a real fade transition.
+/// The published half the render world clones each frame. Regions sit behind `Arc`, so the clones
+/// are refcount bumps and the kill scan, the one writer, copies a region on write.
 #[derive(Clone, Default, Resource, ExtractResource)]
 pub(crate) struct GxWorld {
     pub cells: HashMap<(i32, i32), std::sync::Arc<GxCellDraw>>,
-    /// This frame's doodad-phase draw list, near-first across cells AND prop regions (B4):
-    /// frustum + farclip + exterior gate at cell/set granularity, PVS per set.
+    /// This frame's doodad-phase draw list, near-first across cells and prop regions.
     pub visible: Vec<GxDoodadVis>,
-    /// The WMO regions (slice 2), keyed by placement instance entity.
     pub wmos: HashMap<Entity, std::sync::Arc<GxCellDraw>>,
-    /// The prop regions (B4), keyed by the same instance entity as `wmos` (their lifecycle),
-    /// held apart so prop arrivals never re-bake building geometry.
+    /// The prop regions, keyed like `wmos` but apart, so a prop arrival never re-bakes a building.
     pub props: HashMap<Entity, std::sync::Arc<GxCellDraw>>,
-    /// This frame's per-group admission per region (indexed by absolute group index): the
-    /// portal flood's verdict collapsed to CPU range selection — the node draws exactly the
-    /// runs whose group bit is set.
+    /// This frame's per-group admission per WMO region; the node draws only admitted runs.
     pub visible_wmos: Vec<(Entity, GxSel)>,
 }
 
 use super::pool::GxTexturePool;
 
-/// Record column `w`, bit 14 — the per-item **interior fog** lane (decision 1787), written per
-/// frame by the fog sync and read by `static_gx.wgsl`'s fog select. Bit 0 is the exile kill bit
-/// and bits 1..=13 the interior-prop probe slot, so 14 is the first free bit.
+/// Record column w, bit 14: the item's interior fog lane, read by `static_gx.wgsl`. Bit 0 is the
+/// kill bit and bits 1..=13 the probe slot.
 const RECORD_FOG_BIT: u32 = 1 << 14;
 
 /// MONKEY (room gate): record column `w` bits 15..=26 — the item's ROOM KEY, `group + 1` so that
@@ -223,39 +183,30 @@ fn room_key(item: &GxItemDraw, sets: &[std::sync::Arc<[u16]>]) -> u32 {
 /// or gone item, so a far cell of fully-faded faders submits no vertex work at all (the WGSL
 /// kill-bit collapse stays as the belt for the same frame's record table).
 struct GxRun {
-    /// Index into the cell's `bind_groups` (NOT a pool class index).
+    /// Index into the region's `bind_groups`, not a pool class.
     slot: usize,
     cutout: bool,
     two_sided: bool,
     index_range: Range<u32>,
-    /// The WMO group every item in this run belongs to (`None` = a cell run, always drawn) —
-    /// the bake sorts group inside (bucket, texture), so runs are group-homogeneous by
-    /// construction and the flood's per-group verdict selects whole runs.
+    /// The run's selection key; `None` for a cell run, which always draws.
     group: Option<u16>,
 }
 
-/// A cell's assembled GPU state, cached across frames; rebuilt when the bake (mesh handle)
-/// changes — which, with the shared pool, costs a record table and a few bind groups, never
-/// a texture.
+/// A region's assembled GPU state, cached until its bake (mesh handle) changes.
 struct GxCellGpu {
     mesh: AssetId<Mesh>,
-    /// One bind group per pool class this cell's items touch: (pool class index, group).
+    /// One bind group per pool class the region's items touch: (pool class, bind group).
     bind_groups: Vec<(u16, BindGroup)>,
     record_table: Buffer,
     #[allow(dead_code)] // held alive for the bind groups that reference it
     cell_uniform: Buffer,
-    /// Per item: its index into `bind_groups` — the run key, kept for kill-driven run
-    /// rebuilds.
+    /// Per item, its index into `bind_groups`, kept for kill-driven run rebuilds.
     item_slot: Vec<u16>,
     runs: Vec<GxRun>,
-    /// CPU copy of the record table — the kill-bit sync rewrites column 3 and re-uploads.
+    /// CPU copy of the record table, which the kill and fog syncs rewrite and re-upload.
     records: Vec<[u32; 4]>,
-    /// The `killed_rev` this table last uploaded.
     killed_applied: u32,
-    /// The per-grain interior-fog verdict this table's records were last written from
-    /// ([`GxSel::fog`]) — empty until the first sync. Compared rather than revisioned: it is
-    /// tens of bools, it changes only when the camera changes rooms, and unlike the kill bitmap
-    /// it is produced by the per-frame cull rather than owned by the region.
+    /// The [`GxSel::fog`] the records were last written from; empty until the first sync.
     fog_applied: Vec<bool>,
 }
 
@@ -276,8 +227,7 @@ struct GxPipelines {
     torch_layout: BindGroupLayoutDescriptor,
     sampler: Sampler,
     sampler_clamp: Sampler,
-    /// Keyed `(cutout, two_sided)`; specialized for the world view's (samples, format) pair —
-    /// re-specialized if that pair ever changes (a window move across displays).
+    /// Keyed `(cutout, two_sided)`, re-specialized if the world view's (samples, format) changes.
     pipelines: HashMap<(bool, bool), CachedRenderPipelineId>,
     /// MONKEY (sun shadow perf): the key now carries the live `shadowFilter` too — the PCF branch
     /// is a shader DEF, so a change has to re-specialize the family. Once per CHANGE, not per
@@ -322,7 +272,7 @@ fn init_pipelines(
             (
                 // origin (xyz) + pad
                 uniform_buffer_sized(false, Some(std::num::NonZero::new(16).unwrap())),
-                // item → texture-array layer
+                // the per-item record table
                 storage_buffer_read_only_sized(false, None),
                 texture_2d_array(TextureSampleType::Float { filterable: true }),
                 sampler(SamplerBindingType::Filtering),
@@ -400,8 +350,7 @@ fn init_pipelines(
     });
 }
 
-/// The pipeline-key query: the world view's (samples, format) inputs (the marker keeps booth
-/// views out of it).
+/// The world view's pipeline-key inputs.
 type GxViewKey = (
     &'static ExtractedView,
     &'static Msaa,
@@ -409,10 +358,9 @@ type GxViewKey = (
     &'static StaticGxView,
 );
 
-/// The fixed interleaved vertex layout the bake authors — **attribute-ID order**, which is
-/// how Bevy interleaves a mesh's buffer: position (0), normal (1), uv (2), COLOR (5 — MOCV /
-/// the baked constant tint, white default), then the custom word + anchor (988_101/988_102).
-/// Kept in sync with `bake_cell` and `static_gx.wgsl`.
+/// The bake's interleaved vertex layout, in the attribute-id order Bevy interleaves by: position,
+/// normal, uv, colour, then the word and anchor (988_101, 988_102). Keep in sync with `bake_cell`
+/// and `static_gx.wgsl`.
 fn vertex_layout() -> VertexBufferLayout {
     VertexBufferLayout {
         array_stride: 64,
@@ -452,8 +400,7 @@ fn vertex_layout() -> VertexBufferLayout {
     }
 }
 
-/// (Re-)specialize the four pipelines for the world view's (samples, format), and assemble
-/// visible cells' GPU state: classes, arrays, layer table, bind groups, runs.
+/// Specialize the four pipelines for the world view, and assemble visible regions' GPU state.
 fn prepare_static_gx(
     gx: Res<GxWorld>,
     mut cache: ResMut<GxGpuCache>,
@@ -473,7 +420,6 @@ fn prepare_static_gx(
 ) {
     let shadow_gaussian = shadow_filter.map_or(true, |f| f.0);
     let _t = super::gx_perf_guard(3);
-    // The world view's pipeline key (the marker keeps booth views out of it).
     let Some((view, msaa, _, _)) = views.iter().next() else {
         return;
     };
@@ -559,9 +505,7 @@ fn prepare_static_gx(
         pipes.specialized_for = Some(key);
     }
 
-    // The map cleared (the main world published an empty set): the pool's assignments point
-    // at content the world no longer holds — reset it with the cache. Never fires on a mere
-    // area change; only `StaticGx::clear` empties ALL published maps.
+    // Every published map empty is a map change (`StaticGx::clear`): reset the pool and cache.
     if gx.cells.is_empty() && gx.wmos.is_empty() && gx.props.is_empty() {
         if !pool.is_empty() {
             *pool = GxTexturePool::default();
@@ -647,18 +591,13 @@ fn prepare_static_gx(
             cache.wmos.insert(*entity, gpu);
         }
     }
-    // Encode this frame's queued layer copies, exactly once (B3 — see the module doc; B2's
-    // per-cell pending list was never drained and re-encoded every frame).
     pool.drain_pending(&render_device, &render_queue);
 
-    // The exile kill-bit sync (B2, 1431): when the scan's bitmap revision moved, rewrite the
-    // record table's kill column, re-upload, and REBUILD THE RUNS (B3) so killed items stop
-    // being submitted at all. One whole-table write + one CPU coalesce per changed cell per
-    // change frame — band crossings are rare and a table is tens of KB; a cell that changed
-    // while out of view syncs on re-entry (the revision mismatch persists until applied).
+    // The kill-bit sync: on a new bitmap revision, rewrite the kill column, re-upload and rebuild
+    // the runs. A cell that changed out of view syncs on re-entry.
     for vis in &gx.visible {
         let GxDoodadVis::Cell(cell) = vis else {
-            continue; // prop regions carry no faders — their bitmap never revs
+            continue; // prop regions carry no faders
         };
         let (Some(gpu), Some(draw)) = (cache.cells.get_mut(cell), gx.cells.get(cell)) else {
             continue;
@@ -676,12 +615,8 @@ fn prepare_static_gx(
         gpu.killed_applied = draw.killed_rev;
     }
 
-    // The interior-fog sync (decision 1787): the client's per-group `[0xca7f00]` decides which
-    // fog triple a WMO group's surfaces — and its doodad props — are pushed with, so it is a
-    // per-frame property of the SELECTION, not of the bake. It rides the record table's w column
-    // (bit `RECORD_FOG_BIT`) beside the kill bit, written per item from its own selection grain.
-    // Rewritten only when the verdict actually moves — which is when the camera changes rooms —
-    // and it never touches run membership, so no coalesce is owed.
+    // The interior-fog sync: the client's per-group `[0xca7f00]` picks a WMO group's and its
+    // props' fog triple per frame; rewritten only when the verdict moves, runs untouched.
     let sync_fog = |gpu: &mut GxCellGpu, draw: &GxCellDraw, sel: &GxSel| {
         if gpu.fog_applied == sel.fog {
             return;
@@ -710,11 +645,8 @@ fn prepare_static_gx(
     }
 }
 
-/// Assemble one region's GPU state against the shared pool: pool slots for its textures, the
-/// per-item record table, one bind group per touched pool class, coalesced runs. `None` while
-/// any member texture is not yet resident — the region simply isn't drawn that frame (the
-/// entity path streams batches in piecewise; this is the same arrival class; slots already
-/// assigned stay assigned, so the retry finishes cheaper).
+/// Assemble one region's GPU state against the shared pool; `None`, and undrawn this frame, while
+/// any member texture is not resident (slots already assigned stay assigned).
 fn assemble_region(
     draw: &GxCellDraw,
     // MONKEY (room gate): this region's WMO placement instance (entity index), or 0 for a terrain
@@ -746,11 +678,9 @@ fn assemble_region(
             }
         });
     }
-    // The per-item record table: [layer, batch-order nudge, packed SIDN, kill bit + probe
-    // slot] per item — the vertex word's low bits index it. Column 3's bit 0 is the exile
-    // kill bit (B2), folded from the published bitmap here and kept in sync by
-    // `prepare_static_gx`'s revision check (hence COPY_DST); bits 1..14 carry the interior
-    // prop's SH-probe slot (B4 — 13 bits fits `MAX_PROP_PROBES` exactly).
+    // The per-item record table, indexed by the word's low bits: [layer, batch-order nudge, SIDN,
+    // flags]. Flags: bit 0 the kill bit, re-synced by revision (hence COPY_DST); bits 1..=13 the
+    // probe slot, 13 bits being `MAX_PROP_PROBES` exactly.
     let records: Vec<[u32; 4]> = draw
         .draws
         .iter()
@@ -806,7 +736,7 @@ fn assemble_region(
         ]),
         usage: BufferUsages::UNIFORM,
     });
-    // One bind group per DISTINCT pool class this region touches; items collapse to slots.
+    // One bind group per distinct pool class the region touches.
     let cell_layout = pipeline_cache.get_bind_group_layout(&pipes.cell_layout);
     let mut bind_groups: Vec<(u16, BindGroup)> = Vec::new();
     let mut item_slot: Vec<u16> = Vec::with_capacity(draw.draws.len());
@@ -841,16 +771,13 @@ fn assemble_region(
         runs,
         records,
         killed_applied: draw.killed_rev,
-        // Empty ⇒ the first fog sync always fires (the baked records carry no lane bit).
+        // Empty, so the first fog sync always writes.
         fog_applied: Vec::new(),
     })
 }
 
-/// Coalesce adjacent LIVE items sharing (slot, bucket, group) into draw runs (the bake sorted
-/// by (bucket, texture[, group]), so repeated textures and same-bucket spans fuse; a WMO run
-/// never crosses a group boundary — the selection grain). Killed items are skipped whole
-/// (B3): their vertices are never submitted, and the kill-bit sync rebuilds the runs on every
-/// bitmap revision — a fully-gone cell coalesces to NOTHING.
+/// Coalesce adjacent live items sharing (slot, bucket, group) into draw runs; a killed item is
+/// skipped, so a fully gone cell submits nothing.
 fn build_runs(draws: &[GxItemDraw], item_slot: &[u16], killed: &[u64]) -> Vec<GxRun> {
     let mut runs: Vec<GxRun> = Vec::new();
     for (i, item) in draws.iter().enumerate() {
@@ -1118,13 +1045,8 @@ impl ViewNode for StaticGxNode {
         };
         let meshes = world.resource::<RenderAssets<RenderMesh>>();
         let allocator = world.resource::<MeshAllocator>();
-        // Cells draw whole; a WMO region draws only the runs whose group the flood admitted
-        // this frame, a prop region only the runs whose referrer SET the walk admitted (the
-        // selection rides beside the gpu state — `None` = draw everything). WMO regions
-        // FIRST, then the doodad phase — cells and prop regions in one near-first order
-        // (B3/B4): the real client's own drain order (1429's byte-true anchor: terrain →
-        // WMO → … → doodad), and the buildings are the frame's best early-z occluders for
-        // the doodads behind them.
+        // WMO regions first, then the doodad phase near-first, the 1.12 client's WMO-then-doodad
+        // drain order. Cells draw whole; a region draws only its admitted runs.
         let mut resolved: Vec<(&GxCellGpu, &GxCellDraw, Option<&GxSel>)> = Vec::new();
         for (entity, sel) in &gx.visible_wmos {
             if let (Some(gpu), Some(draw)) = (cache.wmos.get(entity), gx.wmos.get(entity)) {
@@ -1149,10 +1071,8 @@ impl ViewNode for StaticGxNode {
         if resolved.is_empty() {
             return Ok(());
         }
-        // (Layer copies are encoded + submitted by `prepare_static_gx`'s pool drain, exactly
-        // once per texture — B3; the node encodes nothing outside its pass anymore.)
-        // The four bucket pipelines must all be compiled before the first draw (all-or-none:
-        // a cell drawing only its opaque half would flash cutout content off for a frame).
+        // All four pipelines or none: a region drawing only its opaque half would flash its
+        // cutout content off for a frame.
         let mut ready: HashMap<(bool, bool), &RenderPipeline> = HashMap::default();
         for (k, id) in &pipes.pipelines {
             match pipeline_cache.get_render_pipeline(*id) {
@@ -1164,8 +1084,7 @@ impl ViewNode for StaticGxNode {
         }
         let depth_attachment = depth.get_attachment(StoreOp::Store);
         let color_attachment = target.get_color_attachment();
-        // The pass's diagnostic span — `render/static_gx/elapsed_gpu` where the device times
-        // passes (Vulkan/DX12), the CPU span everywhere: the journal's `gpu_static` column (2008).
+        // `render/static_gx/elapsed_gpu` on Vulkan and DX12: the perf journal's `gpu_static`.
         let diagnostics = render_context.diagnostic_recorder();
         let mut pass = render_context.begin_tracked_render_pass(RenderPassDescriptor {
             label: Some("static_gx"),
@@ -1206,8 +1125,7 @@ impl ViewNode for StaticGxNode {
             pass.set_vertex_buffer(0, vslice.buffer.slice(..));
             pass.set_index_buffer(islice.buffer.slice(..), index_format);
             for run in &gpu.runs {
-                // The PVS range selection (1429's collapse): a WMO run draws iff its group's
-                // admission bit is set this frame; a cell run always draws.
+                // A region's run draws only if its selection key is admitted; a cell run always.
                 if let (Some(sel), Some(group)) = (sel, run.group) {
                     if !sel.drawn.get(usize::from(group)).copied().unwrap_or(false) {
                         continue;
@@ -1232,11 +1150,8 @@ impl ViewNode for StaticGxNode {
 
 /// Wire the render half (called by the plugin only when armed).
 pub(super) fn build(app: &mut App) {
-    // (The shader registers in `crate::shaders` with the other engine WGSL — `embedded_asset!`
-    // derives its path from the CALLING file, so registering here would mis-prefix it.)
-    // The main-world half lives inside `StaticGx`; `publish_gx_world` (registered by the
-    // plugin, chained after the scene walk) mirrors it into this standalone resource for
-    // `ExtractResourcePlugin` to clone.
+    // The shader registers in `crate::shaders`: `embedded_asset!` prefixes by the calling file.
+    // `publish_gx_world` mirrors `StaticGx`'s published half into this resource for extraction.
     app.add_plugins((
         ExtractResourcePlugin::<GxWorld>::default(),
         ExtractComponentPlugin::<StaticGxView>::default(),
@@ -1264,21 +1179,9 @@ pub(super) fn build(app: &mut App) {
             ),
         )
         .add_render_graph_node::<ViewNodeRunner<StaticGxNode>>(Core3d, StaticGxLabel)
-        // BEFORE bevy's opaque pass (decision 2016): the retained statics — every building and
-        // every steady doodad — are the frame's best early-Z occluders, and terrain's fragment is
-        // the frame's dearest (four splat layers, the alpha map, the baked shadow: six samples a
-        // pixel). Drawn first, the walls and trunks fill the depth buffer with early writes and
-        // the terrain behind them is rejected before it samples anything; drawn after (the order
-        // 1429 inherited from "bevy's pass, then ours"), every terrain fragment under a building
-        // was shaded in full and then overwritten. The same holds against the entity lane's
-        // creatures and animated doodads, which stand in front of nothing static as a rule. The
-        // pass takes the depth and colour CLEAR with it (bevy's attachments clear on first use,
-        // `DepthAttachment::get_attachment`); when nothing is visible it returns before touching
-        // either and the opaque pass clears as before. An immediate-mode GPU (the Steam Deck,
-        // every Windows part) is where this counts; a tile-based one (Apple) resolves opaque
-        // order in hardware and reads the same frame either way — which is why no measurement
-        // of this exists on the rig, and the player journal's `gpu_opaque`/`gpu_static` columns
-        // (2008) are where the number lands.
+        // Before bevy's opaque pass, as early-z occluders for terrain. This pass takes the depth
+        // and colour clear (attachments clear on first use); with nothing visible it returns
+        // untouched and the opaque pass clears.
         .add_render_graph_edges(
             Core3d,
             (Node3d::StartMainPass, StaticGxLabel, Node3d::MainOpaquePass),
@@ -1288,11 +1191,8 @@ pub(super) fn build(app: &mut App) {
 /// Copy the collector's published half into the extractable resource.
 pub(super) fn publish_gx_world(gx: Res<super::StaticGx>, mut out: ResMut<GxWorld>) {
     let _t = super::gx_perf_guard(2);
-    // Compare before writing: a parked frame's collector walk produces the same five
-    // structures it produced last frame, and an unconditional `clone_from` through `ResMut`
-    // both re-cloned them here and marked the resource changed, so the render world cloned
-    // the whole set again at extract — 1435's two 0.2 ms rows, paid on every frame that
-    // changed nothing (decision 1979). The maps hold `Arc`s, so identity is pointer identity.
+    // Write only what changed: a write through `ResMut` marks the resource changed, which costs a
+    // full clone at extract. The maps hold `Arc`s, so identity is pointer identity.
     fn same_arcs<K: std::hash::Hash + Eq>(
         a: &HashMap<K, std::sync::Arc<GxCellDraw>>,
         b: &HashMap<K, std::sync::Arc<GxCellDraw>>,
@@ -1339,9 +1239,6 @@ mod tests {
         }
     }
 
-    /// Runs fuse adjacent live items of one (slot, bucket, group); a killed item is dropped
-    /// whole and SPLITS the run around it (B3: no vertex work is submitted for killed rows);
-    /// a slot or bucket change breaks the run; an all-killed region coalesces to nothing.
     #[test]
     fn runs_fuse_live_items_and_split_at_kills() {
         let draws = vec![
@@ -1363,7 +1260,7 @@ mod tests {
         assert_eq!(runs.len(), 4);
         assert_eq!(runs[0].index_range, 0..3);
         assert_eq!(runs[1].index_range, 6..9);
-        // Kill everything: nothing is submitted at all.
+        // Kill everything: nothing is submitted.
         assert!(build_runs(&draws, &slots, &[0b11111u64]).is_empty());
     }
 }
diff --git a/crates/benilla-world/src/static_merge.rs b/crates/benilla-world/src/static_merge.rs
index 088e9f87..d629378f 100644
--- a/crates/benilla-world/src/static_merge.rs
+++ b/crates/benilla-world/src/static_merge.rs
@@ -1,40 +1,28 @@
-//! **`WOW_MERGE_CENSUS=1` — the production-merge population census** (decision 1417: "the
-//! census comes first").
-//!
-//! Tallies every batch the streamer walks through `spawn_model_entities` into the population
-//! classes 1417's lane-1 predicate carves — anim-excluded / interior prop / WMO vs doodad ×
-//! order-free vs transparent × never-fade vs fader — and prints the table once the stream has
-//! been quiet for two seconds. The point is to read lane 1's yield (and every later lane's
-//! go/no-go) off a live pin instead of a prior: 0922's ~40% transparent share and the
-//! bracket's 21k-row delta are the numbers this either confirms or replaces.
-//!
-//! Statics + a quiet-timer logger, not plumbed state: the tally site is deep in the assembler
-//! (which already threads eleven parameters), and this is a dev reading at a parked pin, not
-//! a production mechanism — the same trade `WOW_HIT_COST` made. Wall-clock quiet is likewise
-//! fine HERE (contrast the bracket's same-shaped flush timer, which 1417 retires for
-//! production in favour of the weld's close rule).
+//! The static merge's batch classes, and the `WOW_MERGE_CENSUS=1` census that tallies every
+//! spawned batch by class and prints the table once the stream has been quiet for 2 s. A dev
+//! reading, so the tallies are statics rather than state threaded through the assembler.
 
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Mutex;
 
 use bevy::prelude::*;
 
-/// Is the census armed? One read; the assembler tally and the logger both key on it.
+/// Whether `WOW_MERGE_CENSUS=1` armed the census, read once.
 pub fn census_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_MERGE_CENSUS").as_deref() == Ok("1"))
 }
 
-/// The classes, in the lane-1 predicate's own short-circuit order (1417). Indices are the
-/// atomics' layout — append, never reorder.
+/// The classes in the merge predicate's short-circuit order; the indices are the atomics' layout,
+/// so append, never reorder.
 const CLASS_NAMES: [&str; 9] = [
     "excluded: anim/billboard/mat-anim",
     "interior prop",
-    "wmo order-free never-fade", // measured 1:1 — never merges (1418)
+    "wmo order-free never-fade", // never merges: WMO group geometry is refused per site
     "wmo transparent",
-    "wmo FINITE-FADE (anomaly)", // WMOs enroll at radius = INFINITY; nonzero here = investigate
+    "wmo FINITE-FADE (anomaly)", // WMOs enroll at radius = INFINITY, so a count here is an anomaly
     "doodad order-free never-fade", // merges
-    "doodad order-free fader",   // merges (1418 — the dense class)
+    "doodad order-free fader",   // merges; the dense class
     "doodad transparent never-fade",
     "doodad transparent fader",
 ];
@@ -42,11 +30,8 @@ const MERGE_LANES: [usize; 3] = [1, 5, 6];
 
 static ROWS: [AtomicU64; 9] = [const { AtomicU64::new(0) }; 9];
 static VERTS: [AtomicU64; 9] = [const { AtomicU64::new(0) }; 9];
-/// Distinct would-be merge keys per class — each class's PREDICTED blob count under its
-/// lane's key (built from [`MergeSite::census_key`]), so a lane's honest row reduction
-/// (rows − blobs) is read off the table before the lane is built. The lane-1 smoke run is the
-/// estimator's validation anchor: 6,892 measured blobs at the SW pin. Spawn-time only, so a
-/// mutex is fine.
+/// Distinct would-be merge keys per class (`MergeSite::census_key`), the predicted blob count, so
+/// a lane's row reduction (rows − blobs) reads off the table. Spawn-time only, so a mutex is fine.
 static KEYS: std::sync::OnceLock<Mutex<[std::collections::HashSet<u64>; 9]>> =
     std::sync::OnceLock::new();
 
@@ -54,10 +39,8 @@ fn keys() -> &'static Mutex<[std::collections::HashSet<u64>; 9]> {
     KEYS.get_or_init(|| Mutex::new(std::array::from_fn(|_| std::collections::HashSet::new())))
 }
 
-/// Zero the tallies. Called from the map-change teardown (`drop_streamed_world`): the counters
-/// are cumulative and never decrement on tile unload, so without this a rig that logs in on one
-/// map and teleports to another prints the SUM of both worlds — the first LBRS read did exactly
-/// that (its doodad rows matched Stormwind's to the digit, because they WERE Stormwind's).
+/// Zero the tallies, at the map-change teardown (`drop_streamed_world`): they never decrement on
+/// tile unload, so after a teleport the table would print both maps' sum.
 pub fn reset() {
     for a in ROWS.iter().chain(VERTS.iter()) {
         a.store(0, Ordering::Relaxed);
@@ -67,13 +50,10 @@ pub fn reset() {
     }
 }
 
-/// One batch, classified exactly as 1417's lane-1 predicate sees it — built once per batch by
-/// the assembler and consumed by BOTH the census tally and the production divert, so the
-/// number the census prints and the population the merge takes can never drift apart.
-/// `excluded` is the bracket's anim predicate (anim host / billboard / alpha- uv- rgb-anim /
-/// per-seq material); `order_free` is `Opaque|AlphaTest && !additive` (0858's law: order
-/// information exists only on transparent-pass batches); `never_fade` is
-/// `radius > NEVER_FADE_RADIUS` (WMO group geometry's ∞ radius lands there by construction).
+/// One batch's merge class, built once by the assembler for both the census and the merge.
+/// `excluded`: any animation (anim host, billboard, alpha, uv or rgb anim, per-sequence material);
+/// `order_free`: `Opaque|AlphaTest`, not additive, since only transparent-pass batches carry draw
+/// order; `never_fade`: `radius > NEVER_FADE_RADIUS`, as WMO group geometry's infinite radius is.
 pub struct BatchClass {
     pub excluded: bool,
     pub interior_prop: bool,
@@ -82,9 +62,7 @@ pub struct BatchClass {
 }
 
 impl BatchClass {
-    /// The merge predicate (1417 lane 1, widened twice by 1418: faders when the fade channels
-    /// moved in-shader, interior props when the probe slot did — what remains here is "static
-    /// and order-free"; per-SITE refusal (WMO group geometry) lives in `divert`).
+    /// The merge predicate: static and order-free. A site's own refusal lives in its `divert`.
     pub fn merges(&self) -> bool {
         !self.excluded && self.order_free
     }
@@ -122,8 +100,7 @@ pub fn tally(class: &BatchClass, is_wmo: bool, verts: usize, key: Option<u64>) {
     }
 }
 
-/// Print the table once the stream has been quiet for 2 s; re-arm on any new tally (a fresh
-/// tile crossing prints a fresh table).
+/// Print the table once the stream has been quiet for 2 s; any new tally re-arms it.
 pub fn log_merge_census(time: Res<Time>, mut prev: Local<(u64, f32, bool)>) {
     let total: u64 = ROWS.iter().map(|a| a.load(Ordering::Relaxed)).sum();
     let (last, moved_at, printed) = &mut *prev;
@@ -148,9 +125,8 @@ pub fn log_merge_census(time: Res<Time>, mut prev: Local<(u64, f32, bool)>) {
         } else {
             ""
         };
-        // `blobs` = distinct would-be merge keys; `net` = the rows the lane would actually
-        // delete (rows − blobs) — the number the 44 ns/row derivative multiplies. Prop-class
-        // keys omit the referrer-set/probe-slot axes, so their net is an optimistic BOUND.
+        // `net` (rows − blobs) is the rows a lane would delete; prop-class keys omit the
+        // referrer-set and probe-slot axes, so their net is an upper bound.
         info!(
             "[merge-census] {name:<34} rows={rows:>7}  kverts={:>8}  blobs={blobs:>6}  net=-{:>6}{mark}",
             verts / 1000,
diff --git a/crates/benilla-world/src/straddle.rs b/crates/benilla-world/src/straddle.rs
index 208cc7b2..10f284b7 100644
--- a/crates/benilla-world/src/straddle.rs
+++ b/crates/benilla-world/src/straddle.rs
@@ -1,51 +1,18 @@
-//! **The straddle split** — a translucent model that crosses its water plane draws on BOTH sides
-//! of the water pass, each copy cut at the waterline (decision 2188; wow-re
-//! `terrain/scratch/water-frame-straddle.md` §2, byte-VERIFIED).
+//! The straddle split: a translucent model crossing its water plane draws on both sides of the
+//! water pass, each copy clipped at the waterline.
 //!
-//! **The reference.** The collector (`0x707680`) dots each model's bound-box centre (instance
-//! matrix × `(min+max)/2`) against the plane `{0,0,1,−surfaceZ}` from the model's own liquid hit,
-//! once per instance. With `M2UseClipPlanes` granted — the cvar's default `"1"`, caps-gated at
-//! `0x7066a6` — it keeps TWO side booleans, `A = d ≥ −r` (the above list) and `B = d ≤ r` (the
-//! below list), `r` the world-scaled bound radius. A model inside the `±r` band lands on BOTH
-//! lists, its z-fill depth primes ride the same booleans (`0x707ffe`/`0x708048`), and the mesh
-//! draw arm brackets each list's copy with a hardware clip plane at the waterline (`0x70baf0`
-//! @`0x70c094`–`0x70c103`). The frame interleave draws the eye's far list before the water and the
-//! near list after it (0911) — so the half under the surface is painted over by the water, and the
-//! half above it paints over the water.
+//! The reference (`0x707680`, `M2UseClipPlanes` at its default 1, caps-gated at `0x7066a6`) dots
+//! each instance's bound-box centre with its liquid plane `{0, 0, 1, −surfaceZ}` and keeps two
+//! booleans, above `d ≥ −r` and below `d ≤ r`, `r` the world-scaled bound radius. Inside the band
+//! a model and its depth primes (`0x707ffe`/`0x708048`) go on both lists, each copy under a clip
+//! plane at the waterline (`0x70baf0`, `0x70c094`–`0x70c103`): the eye's far list draws before the
+//! water, the near list after.
 //!
-//! **What benilla had.** The mesh lane (0919) shipped the no-clip-planes fallback only — one list
-//! per model, a bare sign test at the placement origin — and named the band as a gap. Its worst
-//! case was a unit fading in while standing in water (the director's report, 2026-09-11): the
-//! appear ramp puts every part on its blend twin, which is exactly when the lane classifies it;
-//! feet under the surface sent the WHOLE body to the far list; and because the fade twin and the
-//! depth prime both write depth, the part above the water primed its depth before the water drew.
-//! A body-shaped hole in the surface, with the head blended over the unwatered lake bed behind it
-//! — strongest at the ramp's start, where the body is least opaque.
-//!
-//! **The shape here — three pieces, one verdict:**
-//! - [`band_instances`] — per model instance (a root carrying a [`RigSkin`] slot and a
-//!   [`WorldUnit`] bound), the reference's two booleans at the transformed bound centre. A
-//!   straddler's plane goes into the per-slot [`WaterClips`] table — a region of the shared light
-//!   buffer on the same slot index as the body tint (0812) — and [`ModelWaterBand`] on the root is
-//!   the edge the classifier fans down from.
-//! - `model_render::classify_water_side` reads the SAME table word by the batch's `MeshTag` slot:
-//!   a straddling batch stays on its NEAR identity and is marked [`StraddlesWater`], and
-//!   [`sync_straddle_twins`] hangs a child on it carrying the FAR twin — the second list.
-//! - `wow_model.wgsl`'s `WOW_WATER_CLIP` block (every transparent-pass pipeline) is the clip plane:
-//!   a fragment of a straddling instance survives only on its own copy's side — the near copy
-//!   keeps the eye's half, the far twin (`FAR_SIDE_MARKER`) the other. [`keeps`] is the law's Rust
-//!   twin.
-//!
-//! The CPU twin set and the GPU clip read one word, so they cannot disagree: a batch is doubled
-//! exactly when its fragments are being halved.
-//!
-//! **Scope: slot-bearing instances.** The clip is per INSTANCE, and the one per-instance channel
-//! the fragment stage has is the rig slot — so the split covers every skinned wire body (units,
-//! players, rigged GameObjects), the parts carrying its slot (boneless geosets, billboard cards),
-//! and every model CHAINED to it — worn gear and hung spell kits, which own slots of their own
-//! since 1609 and take the body's word through their `ParentModel` link (decision 2190). Slot-0
-//! content — map doodads, unskinned models — keeps 0919's one-sided fallback; its only
-//! translucent episodes are the distance-fade ring's small props.
+//! The plane goes into the instance's rig-slot [`WaterClips`] word, which both the twin set
+//! (`model_render::classify_water_side`, [`sync_straddle_twins`]) and the shader's
+//! `WOW_WATER_CLIP` read, so they cannot disagree. Chained models (worn gear, spell kits) take
+//! their body's word. Slot-0 content (map doodads, unskinned models) keeps one list per model by a
+//! sign test at its origin; its only translucent moments are the distance-fade ring's small props.
 
 use std::sync::Arc;
 
@@ -66,21 +33,19 @@ use crate::particles::WaterInterleave;
 use crate::rig_palette::RigSkin;
 use crate::world_unit::WorldUnit;
 
-/// One slot's clip word: `[plane height, near side]` — the waterline's world height (Bevy Y,
-/// which is WoW Z) and the side the instance's NEAR copy keeps: `+1` above (a dry eye's near list
-/// is the above one), `−1` below (a submerged eye's, `0x4836d6`). A side of `0` is "not
-/// straddling" — every slot-0 instance, every slot nothing wrote, and every zeroed studio buffer.
+/// One slot's clip word, `[plane height, near side]`: the waterline's Bevy Y and the side the near
+/// copy keeps, `+1` above for a dry eye, `−1` below for a submerged one (`0x4836d6`), 0 when not
+/// straddling.
 pub type ClipWord = [f32; 2];
 
-/// The "no clip" word. Zero is identity, so a zeroed region is inert by construction: the
-/// portrait booths' studio buffers never receive this region's writes and keep it that way.
+/// The no-clip word; zero, so a zeroed region (a studio buffer's) is inert.
 pub const NO_CLIP: ClipWord = [0.0, 0.0];
 
-/// Bytes per slot in the clip region: two `f32` — `wow_model.wgsl`'s `array<vec2<f32>, 2048>`.
+/// Bytes per slot: two `f32`, `wow_model.wgsl`'s `array<vec2<f32>, 2048>`.
 const SLOT_BYTES: u64 = 8;
 
-/// Byte offset of the clip region inside a `wow_light`-layout buffer: after the mat-anim table,
-/// before the palette rows (which stay last — the shader's one runtime-sized array).
+/// The clip region's offset in a `wow_light` buffer: after the mat-anim table, before the palette
+/// rows, which stay last as the shader's one runtime-sized array.
 pub(crate) fn region_offset() -> u64 {
     crate::mat_anim_table::region_offset() + crate::mat_anim_table::region_bytes()
 }
@@ -90,9 +55,7 @@ pub(crate) fn region_bytes() -> u64 {
     MAX_RIG_SLOTS as u64 * SLOT_BYTES
 }
 
-/// The live per-slot clip table, indexed by the instance's `MeshTag` rig slot. `Arc`-shared so
-/// the render-world extract is a pointer bump, and generation-stamped so a world where nothing
-/// straddles uploads nothing at all.
+/// The clip table by `MeshTag` rig slot; generation-stamped, so a dry world uploads nothing.
 #[derive(Resource, Clone, ExtractResource)]
 pub struct WaterClips {
     slots: Arc<Vec<ClipWord>>,
@@ -109,8 +72,7 @@ impl Default for WaterClips {
 }
 
 impl WaterClips {
-    /// Set slot `slot`'s word. Slot 0 is the world's no-rig sentinel and is never written:
-    /// everything unskinned shares it.
+    /// Set a slot's word; slot 0, shared by everything unskinned, is never written.
     pub(crate) fn set(&mut self, slot: u16, word: ClipWord) {
         let i = slot as usize;
         if i == 0 || i >= MAX_RIG_SLOTS || self.slots[i] == word {
@@ -120,37 +82,29 @@ impl WaterClips {
         self.generation += 1;
     }
 
-    /// Back to "not straddling" — called from `RigSkin`'s free hook as well, so a recycled slot
-    /// can never hand a dead unit's waterline to the next unit that allocates it.
+    /// Back to not straddling; `RigSkin`'s free hook calls it, so a recycled slot starts dry.
     pub(crate) fn clear(&mut self, slot: u16) {
         self.set(slot, NO_CLIP);
     }
 
-    /// This slot's word (`NO_CLIP` for an out-of-range slot) — what a chained model inherits
-    /// from its wearer.
+    /// A slot's word, [`NO_CLIP`] out of range.
     pub(crate) fn word(&self, slot: u16) -> ClipWord {
         self.slots.get(slot as usize).copied().unwrap_or(NO_CLIP)
     }
 
-    /// Whether `slot`'s instance straddles its water plane — the classifier's read of the very
-    /// word the fragment clips by.
+    /// Whether a slot's instance straddles, read from the word the fragment clips by.
     pub(crate) fn straddles(&self, slot: u16) -> bool {
         self.slots.get(slot as usize).is_some_and(|w| w[1] != 0.0)
     }
 }
 
-/// On a model-instance root: whether its model straddles its water plane this frame. Written by
-/// [`band_instances`] (change-gated) and read as a change EDGE — `classify_water_side`
-/// re-classifies the holder's subtree when it flips, the same fan-down the room claim takes.
-/// Absent reads "no": it is inserted the first time an instance straddles.
+/// On an instance root: whether it straddles, a change edge that re-classifies its subtree.
 #[derive(Component, Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct ModelWaterBand {
     pub straddles: bool,
 }
 
-/// On a transparent batch of a straddling instance: the classifier's verdict that this batch
-/// draws on both lists. Sparse; [`sync_straddle_twins`] keeps a far twin alive exactly while it
-/// is present.
+/// On a transparent batch of a straddling instance: it draws on both lists, with a far twin.
 #[derive(Component)]
 pub(crate) struct StraddlesWater;
 
@@ -158,42 +112,28 @@ pub(crate) struct StraddlesWater;
 #[derive(Component)]
 pub(crate) struct StraddleTwin(Entity);
 
-/// On a twin: the batch it doubles for — the mirror's key, and the marker that keeps a twin out
-/// of the classifier's walk (a twin is the classification's output, never its input).
+/// On a twin: the batch it doubles, which also keeps it out of the classifier's walk.
 #[derive(Component)]
 pub(crate) struct StraddleTwinOf(Entity);
 
-/// The reference's two side booleans for a model whose bound centre sits `d` yd over its water
-/// plane, with slack `r`: `(above, below) = (d ≥ −r, d ≤ r)` (`0x7079a2`–`0x707a17`). Both ties
-/// are inclusive — `d == −r` keeps A (the emitter lane's `is_above`), `d == r` keeps B (`jp`
-/// @`0x7079e2`) — and a NaN keeps neither, which reads as "not straddling".
+/// The reference's side booleans for a bound centre `d` yd over its plane with slack `r`,
+/// `(d ≥ −r, d ≤ r)` (`0x7079a2`–`0x707a17`), both ties inclusive (`0x7079e2`); NaN keeps neither.
 pub(crate) fn side_booleans(d: f32, r: f32) -> (bool, bool) {
     (d >= -r, d <= r)
 }
 
-/// How far past the reference's `±r` band a straddler must travel before it stops straddling.
-///
-/// **Not a fidelity deviation.** A split draw is pixel-identical to the one-list draw for a model
-/// wholly on one side of its plane — one copy's half is simply empty — so where the verdict flips
-/// only decides what the draw COSTS, never what it shows. The reference recomputes its booleans
-/// every frame with no hysteresis because its flip is free (list membership); ours spawns or
-/// despawns a twin and swaps the batch's handle. Without this, a murloc bobbing 0.3 yd at the
-/// band's edge flipped nearly every frame (the 2188 live leg: 17 transitions on one body, three
-/// inside 40 ms).
+/// Exit hysteresis (yd) past the reference's `±r` band. Not a deviation: a split draw looks the
+/// same as one list for a model wholly on one side, so where it flips changes cost, not pixels.
 const STICKY_YD: f32 = 1.0;
 
-/// The straddle verdict with the sticky exit: an instance enters on the reference's band and
-/// leaves only once its centre is [`STICKY_YD`] past it. `was` = it straddled last time it was
-/// banded.
+/// The verdict: enter on the reference's band, leave [`STICKY_YD`] past it; `was` is the last one.
 pub(crate) fn straddles(d: f32, r: f32, was: bool) -> bool {
     let slack = if was { r + STICKY_YD } else { r };
     side_booleans(d, slack) == (true, true)
 }
 
-/// The clip plane's law — the Rust twin of `wow_model.wgsl`'s `WOW_WATER_CLIP` block: does a
-/// fragment at world height `y` survive on this copy of a batch? `far_copy` = the copy's material
-/// carries `FAR_SIDE_MARKER` (it is the twin on the eye's far list). A `0` side keeps everything,
-/// and a fragment exactly on the plane survives on both copies.
+/// The Rust twin of `wow_model.wgsl`'s `WOW_WATER_CLIP`: whether a fragment at height `y` survives
+/// on this copy (`far_copy`: the `FAR_SIDE_MARKER` twin); the plane itself survives on both.
 pub fn keeps(word: ClipWord, y: f32, far_copy: bool) -> bool {
     if word[1] == 0.0 {
         return true;
@@ -202,11 +142,8 @@ pub fn keeps(word: ClipWord, y: f32, far_copy: bool) -> bool {
     side * (y - word[0]) >= 0.0
 }
 
-/// The waterline a CHAINED model clips at: its nearest body's word, walked up the
-/// [`ParentModel`] chain from `start` (the model's parent). `link(k)` answers, for one link, its
-/// own palette slot, its parent, and whether it is a body; a broken chain, a body with no slot
-/// and a chain past [`MAX_MODEL_CHAIN`] all read "not straddling". Generic over the key so the
-/// walk is testable without an ECS.
+/// A chained model's word, its nearest body's up the [`ParentModel`] chain; a broken chain, a
+/// slotless body or one past [`MAX_MODEL_CHAIN`] reads not straddling.
 fn wearer_word<K: Copy>(
     start: K,
     clips: &WaterClips,
@@ -228,9 +165,7 @@ fn wearer_word<K: Copy>(
     NO_CLIP
 }
 
-/// The roots [`band_instances`] re-bands on an ordinary frame: an instance whose matrix, bound,
-/// slot or room claim moved. The eye crossing the surface and the surface population changing
-/// re-band everything.
+/// The roots re-banded on an ordinary frame: those whose matrix, bound, slot or room claim moved.
 type BandDirty = (
     With<RigSkin>,
     With<WorldUnit>,
@@ -242,7 +177,7 @@ type BandDirty = (
     )>,
 );
 
-/// A model chained to a body — worn gear and the spell kits hung on it — with its own slot.
+/// A model chained to a body (worn gear, a hung spell kit), with its own slot.
 type ChainedRoot<'a> = (
     Entity,
     &'a RigSkin,
@@ -250,8 +185,7 @@ type ChainedRoot<'a> = (
     Option<Mut<'a, ModelWaterBand>>,
 );
 
-/// A chained model whose slot or link is new this frame — it has no word yet, whatever its
-/// wearer's did.
+/// A chained model whose slot or link is new this frame, so it has no word yet.
 type ChainedFresh = (
     With<ParentModel>,
     Without<WorldUnit>,
@@ -267,22 +201,9 @@ type BandRoot<'a> = (
     Option<Mut<'a, ModelWaterBand>>,
 );
 
-/// **Band every model instance against its water plane** — the reference's two side booleans
-/// per instance, written where both halves of the split read them: the per-slot [`WaterClips`]
-/// word (the fragment's clip plane, the classifier's doubling verdict) and [`ModelWaterBand`]
-/// on the root (the classifier's re-classify edge).
-///
-/// **Every model chained to a body inherits the body's word** (decision 2190). Worn gear does not
-/// share its wearer's slot: since 1609 every ordinary item rides a rider slot of its own (0841's
-/// welded items a joint rig), so a helm, a pair of shoulders or a weapon at the waterline was
-/// never banded and kept the one-list fallback — the hole in the water the director still saw
-/// when the surface crossed a unit's gear. The body's band is the instance's verdict and its
-/// plane is the one water plane under it, and the clip is exact on any copy whatever side it
-/// lands, so the gear takes the word verbatim rather than a band of its own.
-///
-/// Update, after the submersion verdict and before `classify_water_side` — the auto-inserted
-/// sync point between them lands a first-time `ModelWaterBand` before the classifier looks, so
-/// the clip and the twin set flip on the same frame.
+/// Band every instance against its water plane into its [`WaterClips`] word and
+/// [`ModelWaterBand`]; a chained model, on a slot of its own, takes its body's word verbatim. The
+/// sync point before `classify_water_side` lands a new band before it looks.
 pub(crate) fn band_instances(
     interleave: WaterInterleave,
     mut clips: ResMut<WaterClips>,
@@ -320,9 +241,7 @@ pub(crate) fn band_instances(
             }
         }
     }
-    // The chained pass: every chained model when any body's word moved this frame (the gate is
-    // the table's own generation — a dry world, and a wet one standing still, skip it whole),
-    // otherwise only the chains that are new.
+    // The chained pass: every chain when a body's word moved (the generation did), else new ones.
     let link = |e: Entity| {
         links
             .get(e)
@@ -342,7 +261,7 @@ pub(crate) fn band_instances(
     }
 }
 
-/// One chained model's word — its wearer's, onto its own slot — and its band edge.
+/// Copy the wearer's word onto a chained model's slot and publish its band edge.
 fn chain_one(
     clips: &mut WaterClips,
     commands: &mut Commands,
@@ -354,8 +273,7 @@ fn chain_one(
     band_edge(commands, entity, band, word[1] != 0.0);
 }
 
-/// Publish an instance's verdict as its [`ModelWaterBand`] edge: change-gated on a live
-/// component, inserted the first time it straddles.
+/// Publish the verdict as [`ModelWaterBand`], change-gated, inserted when it first straddles.
 fn band_edge(
     commands: &mut Commands,
     entity: Entity,
@@ -373,7 +291,7 @@ fn band_edge(
     }
 }
 
-/// One instance's band — the shared body of [`band_instances`]' full and reactive paths.
+/// One instance's band, for both of [`band_instances`]' paths.
 fn band_one(
     interleave: &WaterInterleave,
     clips: &mut WaterClips,
@@ -381,10 +299,9 @@ fn band_one(
     near_side: f32,
     (entity, gt, unit, rig, band): BandRoot<'_>,
 ) {
-    // The reference's point and slack (§2/§6): the bound centre through the instance matrix, the
-    // radius through its row-0 scale. The game hands the armed idle's authored CAaBox rather than
-    // the header sphere, so the slack is that box's circumscribed sphere — never smaller than the
-    // model, and an over-wide band costs only a copy whose half the clip discards whole.
+    // The reference's point and slack: the bound centre through the instance matrix (`0x70848d`),
+    // the radius by its row-0 scale (`0x708478`). The bound here is the armed idle's CAaBox, so the
+    // slack is its circumscribed sphere; a wider band costs only a copy the clip empties.
     let was = band.as_ref().is_some_and(|b| b.straddles);
     let word = unit.bound.and_then(|b| {
         let centre = gt.transform_point(Vec3::from(b.center));
@@ -396,8 +313,7 @@ fn band_one(
     band_edge(commands, entity, band, word.is_some());
 }
 
-/// One straddle candidate as [`sync_straddle_twins`] sees it: the batch, what its twin copies
-/// (tag, mesh, handle, cull box and marker, layers), its verdict, and the twin it already has.
+/// A straddle candidate: the batch, what its twin copies, its verdict and its twin.
 type StraddleParts<'w, 's> = Query<
     'w,
     's,
@@ -418,13 +334,8 @@ type StraddleParts<'w, 's> = Query<
     ),
 >;
 
-/// Keep every straddling batch's far twin in sync with its verdict — spawn the twin child when
-/// the classifier marks the batch [`StraddlesWater`], despawn it when the mark goes — and mirror
-/// the batch's tag (the fade alpha moves every ramp frame; the slot rides it), mesh (a gear
-/// redress swaps it in place) and handle (composed down one water rung) onto a live twin.
-///
-/// PostUpdate, after the depth-prime sync: a zfill twin is a batch like any other here, so its
-/// own far twin mirrors the tag the zfill mirror has just written.
+/// Keep a far twin under each [`StraddlesWater`] batch, mirroring its tag, mesh and handle; after
+/// the depth-prime sync, so a zfill twin's own twin mirrors its fresh tag.
 pub(crate) fn sync_straddle_twins(
     mut commands: Commands,
     far: Res<FarSideTwins>,
@@ -439,8 +350,7 @@ pub(crate) fn sync_straddle_twins(
     for (part, tag, mesh, mat, straddling, twin, aabb, no_cull, layers) in &parts {
         match twin {
             None if straddling => {
-                // The classifier builds the far twin before it marks the batch; a miss means the
-                // batch's handle moved since, and next frame's classification rebuilds it.
+                // A miss: the handle moved since the twin was built; next frame rebuilds it.
                 let Some(far_h) = far.far_of(&mat.0) else {
                     continue;
                 };
@@ -452,8 +362,7 @@ pub(crate) fn sync_straddle_twins(
                     StraddleTwinOf(part),
                     ChildOf(part),
                 ));
-                // The twin culls exactly as its batch does: a skinned part's cull belongs to the
-                // body root's election, and its own box is the picker's (`attach::dress`).
+                // The twin culls exactly as its batch does.
                 if let Some(aabb) = aabb {
                     t.insert(*aabb);
                 }
@@ -477,7 +386,7 @@ pub(crate) fn sync_straddle_twins(
     }
     for (of, mut tag, mut mesh, mut mat) in &mut twins {
         let Ok((_, ptag, pmesh, pmat, ..)) = parts.get(of.0) else {
-            continue; // batch going away this frame — the child despawns with it
+            continue; // the batch is going away, and the child with it
         };
         if tag.0 != ptag.0 {
             tag.0 = ptag.0;
@@ -493,8 +402,7 @@ pub(crate) fn sync_straddle_twins(
     }
 }
 
-/// The split's instrument (`WOW_MOVE_TRACE=<path>`, tag `fx` — beside the classifier's
-/// `straddle`/`far-side` lines): one line per twin edge.
+/// `WOW_MOVE_TRACE=<path>`, tag `fx`: one line per twin armed or released.
 fn trace(what: &str, part: Entity) {
     if !benilla_assets::trace::enabled() {
         return;
@@ -502,9 +410,7 @@ fn trace(what: &str, part: Entity) {
     benilla_assets::trace::line("fx", &format!("straddle-twin {what} part={part}"));
 }
 
-/// Render world (`PrepareResources`): write the whole 16 KB region when anything changed — the
-/// shared buffer only. The portrait booths and the glue scene keep their zeroed region: nothing in
-/// a studio stands in world water.
+/// Render world: write the whole region to the shared buffer on a change; studio buffers stay zero.
 fn upload_water_clips(
     queue: Res<RenderQueue>,
     shared: Option<Res<crate::lighting::SharedLightBuffer>>,
@@ -525,7 +431,7 @@ fn upload_water_clips(
     );
 }
 
-/// The straddle split's registration (decision 2188).
+/// The straddle split's registration.
 pub fn plugin(app: &mut App) {
     app.init_resource::<WaterClips>()
         .add_plugins(ExtractResourcePlugin::<WaterClips>::default())
@@ -551,13 +457,9 @@ pub fn plugin(app: &mut App) {
 mod tests {
     use super::*;
 
-    /// The band is the reference's: a centre within `r` of the plane on EITHER side straddles,
-    /// both ties included; beyond it the model sits wholly on one list.
     #[test]
     fn the_band_is_plus_minus_r_inclusive() {
-        // A wading unit: centre 0.4 yd over the surface, 1.5 yd of slack — both lists.
         assert_eq!(side_booleans(0.4, 1.5), (true, true));
-        // Waist-deep the other way: centre under the surface, still inside the band.
         assert_eq!(side_booleans(-1.2, 1.5), (true, true));
         assert_eq!(side_booleans(-1.5, 1.5), (true, true), "d == −r keeps A");
         assert_eq!(side_booleans(1.5, 1.5), (true, true), "d == r keeps B");
@@ -573,8 +475,6 @@ mod tests {
         );
     }
 
-    /// Entry is the reference's band; exit is sticky by `STICKY_YD`, so a body bobbing at the
-    /// edge holds its verdict instead of re-spawning its twins every frame.
     #[test]
     fn the_exit_is_sticky_and_the_entry_is_not() {
         let r = 1.2;
@@ -593,9 +493,6 @@ mod tests {
         assert!(!straddles(f32::NAN, r, true), "NaN never splits");
     }
 
-    /// The clip plane: for a dry eye the near copy keeps the part above the water and the far
-    /// twin the part below; a submerged eye swaps them; the plane itself survives on both copies,
-    /// so the two halves meet without a seam.
     #[test]
     fn each_copy_keeps_its_own_half() {
         let dry = [10.0, 1.0];
@@ -623,8 +520,6 @@ mod tests {
         }
     }
 
-    /// Gear and kits take their BODY's word however deep the chain — a glow on a weapon on a unit
-    /// — and a chain that never reaches a body, or a body with no slot, clips nothing.
     #[test]
     fn a_chained_model_inherits_its_bodys_waterline() {
         let mut clips = WaterClips::default();
@@ -654,8 +549,6 @@ mod tests {
         assert_eq!(wearer_word(99, &clips, chain), NO_CLIP, "a broken chain");
     }
 
-    /// Every slot-0 draw in the world shares the word: writing it would clip terrain, WMOs and
-    /// doodads at one unit's waterline, so the setter refuses it — and a dry world never uploads.
     #[test]
     fn slot_zero_is_never_written_and_only_real_changes_upload() {
         let mut c = WaterClips::default();
@@ -674,8 +567,7 @@ mod tests {
         assert_eq!(c.generation, 2, "an out-of-range slot is dropped");
     }
 
-    /// The shader declares `array<vec2<f32>, 2048>` between two `vec4` arrays: the region must be
-    /// one 8-byte word per addressable slot and end on the 16-byte boundary the palette rows need.
+    /// The shader's `array<vec2<f32>, 2048>` sits between two `vec4` arrays: it ends on 16 bytes.
     #[test]
     fn the_region_is_one_vec2_per_slot_on_a_vec4_boundary() {
         assert_eq!(region_bytes(), (MAX_RIG_SLOTS * 8) as u64);
diff --git a/crates/benilla-world/src/sun/follow.rs b/crates/benilla-world/src/sun/follow.rs
index cf72c433..55388d35 100644
--- a/crates/benilla-world/src/sun/follow.rs
+++ b/crates/benilla-world/src/sun/follow.rs
@@ -1,25 +1,8 @@
-//! Per-frame positioning + tinting of the celestial layer — pin the sun and the white moon (each a
-//! disc with an additive lens-flare glare) and the star dome to their world directions, camera-facing;
-//! rewrite every disc/glare tint from the celestial diffuse band; drive the `0x6cf490` view-lerped
-//! glare scale/intensity and the star-curve global alpha. The DISCS sit just inside the far plane
-//! (terrain occludes them per-pixel, like the reference's far depth slice) and their horizon clip+fade
-//! lives in the shader ([`super::materials`]); the GLARE quads sit on the reference's **near sphere**
-//! (`cam + 12·dir`) with their fragment depth forced far (`celestial.wgsl`) — like the reference,
-//! the flare is dimmed by BOTH the z-buffer (per-pixel: a ridge, a wall, a leaf clips it — its
-//! `[0.995, 1.0]` back-slice depth test, the `celestial-frame-anatomy` pin) and the envelope —
-//! the slewed [`FlareGate`]: the per-body **dnCurve** day/night gate × the below-horizon
-//! smoothstep × the terrain/interior visibility (the occ3 fractional-probe stand-in),
-//! rate-limited like the reference's `[glare+0x30]` (decision 0508).
-//!
-//! **These systems run in `PostUpdate` after transform propagation** ([`crate::billboard::BillboardPlace`],
-//! the camera-anchored placement slot), reading the camera's SAME-frame propagated pose and writing
-//! `GlobalTransform` directly — the placement that renders. In plain `Update` they read the camera's
-//! *last*-frame `GlobalTransform` (Bevy syncs it only in `PostUpdate`): invisible at the far discs
-//! (error ≈ v·dt over ~2.5k units), but the near-sphere glare quads are ~200× more sensitive — one
-//! frame of camera motion is ~1% of their 12-unit distance, so the moon's halo visibly swam while
-//! strafing and pumped bigger/brighter running toward it, smaller/dimmer running away (the director's
-//! Westfall moonrise report; measured exactly one frame in the wiring test below — decision 0504,
-//! the billboard/nameplate lag's celestial sibling).
+//! Per-frame placement of the celestial layer: discs, glares and the star dome face the camera at
+//! their world directions, tinted by the celestial diffuse. The glares sit on the reference's near
+//! sphere (`cam + 12·dir`), clipped per pixel by depth (its `[0.995, 1.0]` slice, `0x7e5a0c`) and
+//! dimmed by the [`FlareGate`] envelope. These run after propagation and write `GlobalTransform`,
+//! so they place from this frame's camera: a frame of lag is ~1% of the glare's distance.
 
 use bevy::camera::Projection;
 use bevy::ecs::system::SystemParam;
@@ -37,43 +20,26 @@ use benilla_assets::AdtTile;
 use super::materials::{CelestialMaterial, StarMaterial};
 use super::{MoonPart, MoonSprite, StarDome, SunPart, SunSprite};
 
-/// Faithful body base angular size: every disc/glare is a **unit quad at radius 12** (`[0x80c4e8]`,
-/// decision 0485) — 1 world unit of quad scale subtends `2·atan(0.5/12) = 4.77°`, so a world-placed
-/// billboard scales by `0.0833 × (its size in the builder's world units) × its distance`.
+/// Every disc and glare is a unit quad at radius 12 (`[0x80c4e8]`), 4.77° per world unit, so a
+/// billboard at distance `d` scales by `0.0833 × size × d`.
 const SUN_SIZE: f32 = 0.0833;
 
-/// The lens-flare quads live on the reference's **near sphere**: `cam + 12·dir` (`[0x80c4e8]`), quad
-/// scale = the builder's world units directly — the same unit-quad-at-12 convention [`SUN_SIZE`]
-/// encodes for the far-placed discs, so the angular sizes are identical by construction. Far
-/// placement was our first "equivalent" and it broke at the byte-law flare size: a 20-unit quad at
-/// `far·0.85` pierced the sky-dome sphere (`far·0.9`) and the depth test cut it along the
-/// plane∩sphere circle — a giant faceted halo edge around the sun (decision 0500). At 12 units the
-/// quad can touch neither the dome nor the far plane; its DEPTH is forced far per-fragment instead
-/// (`celestial.wgsl` — the reference's own split: glare geometry on the near sphere, depth squashed
-/// to the `[0.995, 1.0]` back slice, drawn LAST in the frame; the sort slot is
-/// [`crate::sky_order::GLARE_BIAS`]).
+/// The glares sit on the reference's near sphere, `cam + 12·dir` (`[0x80c4e8]`), in world units,
+/// at the sky's far depth pin (`sky_vertex.wgsl`), drawn last ([`crate::sky_order::GLARE_BIAS`]).
 const GLARE_DIST: f32 = 12.0;
 
-/// Flare occlusion-march tuning: sample count and reach. The reach spans the whole DRAWN horizon —
-/// the detailed ADT ring (the farclip-derived window, ≈ ±867 units at 777) and the coarse WDL beyond it, out to just
-/// inside the far plane — so a distant WDL mountain that visibly hides the body also kills its flare
-/// (the moon shone through the Westfall ridge when the march stopped at 1000). 48 quadratic samples
-/// ⇒ ≤ ~117-unit spacing at the far end, well under a horizon mountain's footprint.
+/// The occlusion march: 48 quadratic samples to just inside the far plane, across the ADT ring and
+/// the WDL beyond, at most ~117 units apart at the far end.
 const FLARE_RAY_SAMPLES: u32 = 48;
 const FLARE_RAY_RANGE: f32 = 2800.0;
 
-/// Flare-envelope slew rates (per second) — `[glare+0x28]`/`[+0x2c]`, VERIFIED (wow-re
-/// celestial-bodies Addendum #5, decision 0508): the reference smooths the whole occlusion×dnCurve
-/// product with an **asymmetric LINEAR rate limiter** (`[glare+0x30]`, sole writer `0x6cf5ea`) —
-/// not an exponential ease. The sun's flare rises at 4.0/s, the moon's at 100/33 ≈ 3.03/s, and both
-/// fall at 50/33 ≈ 1.52/s (a killed flare takes ~0.66 s to go dark). Bit-exact `.rdata` constants.
+/// The envelope's linear slew rates per second (`[glare+0x28]`/`[+0x2c]`, applied by `0x6cf5ea`):
+/// the sun rises at 4.0, the moon at 100/33, and both fall at 50/33.
 const SUN_FLARE_RISE: f32 = 4.0; // [0xce97d0]
 const MOON_FLARE_RISE: f32 = f32::from_bits(0x4041_f07c); // [0xce9720] ≈ 3.0303
 const FLARE_FALL: f32 = f32::from_bits(0x3fc1_f07c); // [0xce97d4]/[0xce9724] ≈ 1.5152
 
-/// One celestial body's sprite row: transform + the body tag + its material — every disc AND glare
-/// rides [`CelestialMaterial`] (disc mode alpha-blends with the horizon clip; glare mode gamma-ADDS,
-/// the reference's SRC_ALPHA, ONE lens-flare blend — decision 0502).
+/// A body's sprite rows; every disc and glare rides [`CelestialMaterial`].
 type BodySprites<'w, 's, T> = Query<
     'w,
     's,
@@ -87,44 +53,32 @@ type BodySprites<'w, 's, T> = Query<
     Without<WorldCamera>,
 >;
 
-/// The `0x6cf490` lens-flare **view lerp**: `f = saturate((cosθ − 0.7) / 0.3)`, `cosθ` between the
-/// camera's facing and the body direction — the glare grows and brightens as the view swings onto it.
+/// The lens flare's view lerp (`0x6cf490`), growing as the view swings onto the body.
 fn view_lerp(cam_forward: Vec3, to_body: Vec3) -> f32 {
     ((cam_forward.dot(to_body) - 0.7) / 0.3).clamp(0.0, 1.0)
 }
 
-/// Below-horizon gate for the additive glares (they can't route the disc clip): a smoothstep on the
-/// body's `sin(elev)` → 0 at/below the horizon. Stands in for the reference's occlusion queries
-/// seeing a set body sink (a factor of the slew target, like them — Addendum #5; the day/night term
-/// they multiply is now modeled for real as the dnCurve).
+/// A smoothstep to 0 at the horizon for the glares, which skip the disc clip: our stand-in for the
+/// reference's occlusion query seeing a set body sink, a factor of the slew target (`0x6cf490`).
 fn horizon_gate(to_body: Vec3) -> f32 {
     let t = (to_body.y / 0.035).clamp(0.0, 1.0);
     t * t * (3.0 - 2.0 * t)
 }
 
-/// One step of the reference's `[glare+0x30]` **asymmetric linear slew** toward `target`
-/// (`0x6cf59b`-`0x6cf5ea`): rising is capped at `rise·dt`, falling at `fall·dt`, and the value
-/// never overshoots the target. Pure, for the unit test; the envelope maths live here.
+/// One step of the `[glare+0x30]` slew toward `target` (`0x6cf59b`-`0x6cf5ea`).
 fn flare_slew(current: f32, target: f32, rise: f32, fall: f32, dt: f32) -> f32 {
     current + (target - current).clamp(-fall * dt, rise * dt)
 }
 
-/// The disc quad's vertical span in **sin-elevation** — `(bottom edge, top edge, 0, 0)`, the
-/// per-frame input to the shader's per-vertex fade reconstruction ([`CelestialExt::span`],
-/// decision 0529). `dir_y` = sin(body elevation) (the Bevy camera→body direction's `y`); `size` =
-/// the quad's angular scale factor (`tf.scale / dist` — the ±0.5 quad subtends `2·atan(size/2)`).
-/// The camera-facing quad's vertical axis maps onto elevation, so the edges sit at
-/// `elevation ∓ atan(size/2)`.
+/// The disc quad's bottom and top edges in sin-elevation, `elevation ∓ atan(size / 2)`, for the
+/// shader's per-vertex fade; `size` is the quad's scale over its distance.
 pub(super) fn disc_span(dir_y: f32, size: f32) -> Vec4 {
     let elev = dir_y.clamp(-1.0, 1.0).asin();
     let half = (0.5 * size).atan();
     Vec4::new((elev - half).sin(), (elev + half).sin(), 0.0, 0.0)
 }
 
-/// [`benilla_assets::quantize`] a [`disc_span`] to 1/4096 sin-elevation steps — the write gate's
-/// floor for the one geometry lane the celestial writes carry. A step is ≪ one pixel of fade edge
-/// on any disc, while un-quantized the span drifts every frame with time-of-day and would defeat
-/// the gate.
+/// A [`disc_span`] in 1/4096 sin-elevation steps, so its drift does not defeat the write gate.
 fn quant_span(v: Vec4) -> Vec4 {
     Vec4::new(
         benilla_assets::quantize(v.x, 4096.0),
@@ -134,11 +88,8 @@ fn quant_span(v: Vec4) -> Vec4 {
     )
 }
 
-/// True when no resident-terrain column blocks the camera→body ray within [`FLARE_RAY_RANGE`].
-/// Pure over a height oracle (`Some(ground WoW z)` under a Bevy point, `None` = no terrain in that
-/// column — never an occluder), so the march is unit-testable without a streamed world. Quadratic
-/// sample spacing densifies near the camera, where a hill subtends the most sky. Bevy `y` IS WoW
-/// `z` (`coords::bevy_to_wow`), so the ray's own height is `p.y`.
+/// No terrain column blocks the ray within [`FLARE_RAY_RANGE`]; the samples densify near the
+/// camera, and Bevy `y` is WoW `z`, so the ray's height is `p.y`.
 fn flare_ray_clear(height_under: impl Fn(Vec3) -> Option<f32>, cam_pos: Vec3, dir: Vec3) -> bool {
     for i in 1..=FLARE_RAY_SAMPLES {
         let s = i as f32 / FLARE_RAY_SAMPLES as f32;
@@ -150,31 +101,17 @@ fn flare_ray_clear(height_under: impl Fn(Vec3) -> Option<f32>, cam_pos: Vec3, di
     true
 }
 
-/// Ray-grid side count for the occ3 fraction — 4×4 = 16 rays; the envelope slew smooths the 1/16
-/// quantization between frames.
+/// The occlusion grid's side: 4×4 rays, whose 1/16 steps the envelope slew smooths.
 const FLARE_FRACTION_GRID: u32 = 4;
 
-/// The grid's cell count — the fraction's denominator and the cached mask's width.
 const FLARE_CELLS: u32 = FLARE_FRACTION_GRID * FLARE_FRACTION_GRID;
 
-/// How many grid cells the probe re-marches per frame (decision 1436): the full 16×48-sample march
-/// every frame priced 0.45 ms/f — the biggest single system in the 1435 parked band map — for a
-/// value the slew rate-limits anyway. Two cells/frame refreshes the whole grid in 8 frames
-/// (0.13 s at 60 Hz), inside BOTH slew time constants (rise 0.25 s, fall 0.66 s), so the drip is
-/// invisible under the smoothing that already covers the grid's own quantization. The faithful
-/// end-state stays the reference's GPU occlusion query (`0x7e5220`, recorded below).
+/// Cells re-marched per frame: the grid refreshes in 8 frames, inside both slew time constants.
 const FLARE_RAYS_PER_FRAME: u32 = 2;
 
-/// The **visible fraction** of the body's quad footprint against resident terrain ∈ [0, 1] — our
-/// CPU stand-in for the reference's fractional occlusion probe (`0x7e5220`, Addendum #8): the real
-/// client draws the disc's OWN quad (same size/position) depth-tested inside a GPU occlusion query
-/// and uses `visiblePixels / projectedArea`, so a half-hidden sun carries ~half the flare. Here: a
-/// [`FLARE_FRACTION_GRID`]² ray grid over the quad's angular extent (`half` = the quad's angular
-/// half-size), each ray the same quadratic terrain march — fraction = clear rays / total rays.
-/// Terrain-only, like the march it generalizes; the reference's z-buffer probe also catches
-/// WMOs/doodads — the GPU-occlusion-query instrument remains the faithful end-state (recorded).
-/// Since decision 1436 the live path drips cells through [`flare_mask_update`] instead; the full
-/// one-call march stays as the convergence oracle for the tests.
+/// The visible fraction of the body's quad against terrain, a ray grid over its extent; the
+/// reference takes `visiblePixels / projectedArea` of the disc's quad from a GPU occlusion query
+/// (`0x7e5220`), WMOs and doodads included. The tests' oracle for the live drip.
 #[cfg(test)]
 fn flare_visible_fraction(
     height_under: impl Fn(Vec3) -> Option<f32>,
@@ -188,8 +125,7 @@ fn flare_visible_fraction(
     clear as f32 / FLARE_CELLS as f32
 }
 
-/// March ONE grid cell of the quad's [−half, +half]² angular footprint — the unit the round-robin
-/// re-prices per frame (decision 1436). Cell `c` = row `c / 4`, column `c % 4`, centre-sampled.
+/// Whether one cell's centre ray over the quad's `[−half, +half]²` footprint is clear.
 fn flare_cell_clear(
     height_under: impl Fn(Vec3) -> Option<f32>,
     cam_pos: Vec3,
@@ -197,7 +133,7 @@ fn flare_cell_clear(
     half: f32,
     cell: u32,
 ) -> bool {
-    // Any orthonormal frame across the camera-facing quad works — the probe is symmetric.
+    // Any orthonormal frame across the quad works: the probe is symmetric.
     let right = dir.cross(Vec3::Y).normalize_or_zero();
     let right = if right == Vec3::ZERO { Vec3::X } else { right };
     let up = right.cross(dir);
@@ -208,9 +144,7 @@ fn flare_cell_clear(
     flare_ray_clear(&height_under, cam_pos, d)
 }
 
-/// One frame's round-robin step over the cached cell mask (bit set = that cell's ray is clear):
-/// re-march `cells` cells from `cursor`, then read the WHOLE mask as the fraction. Pure, for the
-/// convergence test; [`FlareGate::envelope`] owns the state.
+/// Re-march `cells` cells from `cursor`, then read the whole mask (bit = clear) as the fraction.
 fn flare_mask_update(
     mask: &mut u16,
     cursor: &mut u32,
@@ -230,99 +164,47 @@ fn flare_mask_update(
     f32::from(mask.count_ones() as u16) / FLARE_CELLS as f32
 }
 
-/// The flare **envelope** — our build of the reference's `[glare+0x30]` smoothed intensity
-/// (Addenda #5+#8, decisions 0508+0532): each frame a slew target is assembled from the terms we
-/// model — the per-body **dnCurve** (`WowLighting.{sun,moon}_flare_dn`, the real day/night gate),
-/// the below-horizon smoothstep, and the **fractional** terrain visibility of the disc's quad
-/// ([`flare_visible_fraction`] — the reference's occ3 occlusion probe: a half-hidden sun carries
-/// ~half the flare; a camera in a WMO interior kills it, the roof) — and the envelope slews toward
-/// it linearly (rise per body, fall shared, never overshooting). Like the byte law, a zero
-/// dnCurve×horizon target skips the probe entirely (`0x6cf58c`). **occ1** — the cloud coverage
-/// over the body's sky point — is a caller-supplied factor now that the coverage field exists
-/// (`clouds`): sun `1−R`, moon the thin-cloud tent `1−|2(R−0.5)|`, sampled at the glare's
-/// 12-unit position exactly like `0x6cf7b0`/`0x6cf7d0`. The remaining unmodeled factors —
-/// **occ2** (scene async-occlusion, 1.0 in normal outdoor play) and the scene lens-flare-slot
-/// gate **(1−V)** (1.0 without scene-light flares) — stand at
-/// 1.0 (recorded residual, 0532). One instance per system → one slewed scalar per body
-/// (`follow_sun` the sun, `follow_moons` the white moon); seeds at 0 like the reference's `.bss`,
-/// so a flare always rises into view.
+/// The flare envelope, the reference's `[glare+0x30]`, seeded at 0 like its `.bss` and slewed
+/// toward dnCurve × horizon × cloud cover `occ1` (`0x6cf7b0`, `0x6cf7d0`) × the quad's visible
+/// fraction, 0 in a WMO interior; a 0 target skips the probe (`0x6cf58c`). Not modelled: the
+/// reference's `occ2` and lens-flare-slot gate `1−V`, both 1.0 outdoors without scene-light flares.
 #[derive(SystemParam)]
 pub(super) struct FlareGate<'w, 's> {
     time: Res<'w, Time>,
     streamer: Res<'w, TerrainStreamer>,
     adt_tiles: Res<'w, Assets<AdtTile>>,
-    /// The coarse whole-map WDL heightfield — the far leg of the march, beyond the resident ADT
-    /// ring (the same surface that draws the distant horizon mountains). Absent in assetless dev.
+    /// The whole-map WDL heightfield, the march's far leg beyond the ADT ring.
     wdl: Option<Res<'w, WdlStreamer>>,
     camera_interior: Res<'w, CameraInteriorClaim>,
-    /// The submerged-eye depth — the glare's own submersion fade (decision 1829). The glare is
-    /// NOT part of the sky pass the client skips underwater: it draws in its own top-level pass
-    /// (`0x6cf490` ← `0x6d48c0` ← `0x483740`, unconditional), while the sky is `0x6d4940` *inside*
-    /// `0x681070`, which is what `0x6812a4` skips. Both facts are true at once, which is why the
-    /// fade is live code and not a ramp on a pass that never runs.
+    /// For the glare's own submersion fade: its pass (`0x6cf490` ← `0x6d48c0` ← `0x483740`) is
+    /// outside the sky pass (`0x6d4940` in `0x681070`) that `0x6812a4` skips underwater.
     submerged: Res<'w, crate::liquid::SubmergedEye>,
-    /// The live cloud coverage field — the occ1 sample source (one field serves the glare and
-    /// the visible layer, like the reference).
+    /// The cloud coverage `occ1` samples; as in the reference, the visible clouds draw from it too.
     clouds: Res<'w, CloudCoverage>,
     env: Local<'s, f32>,
-    /// The occ3 grid's cached per-cell verdicts (bit = clear) and the round-robin cursor
-    /// (decision 1436): [`FLARE_RAYS_PER_FRAME`] cells re-march per active frame. `primed`
-    /// falls when the probe is skipped (night, interior, below horizon) so the first active
-    /// frame after a gap marches the whole grid instead of trusting a stale mask.
+    /// Cached cell verdicts (bit = clear); `primed` falls when the probe is skipped.
     mask: Local<'s, u16>,
     cursor: Local<'s, u32>,
     primed: Local<'s, bool>,
 }
 
-/// The glare's **submersion fade** — `1 − clamp(depth × 0.1, 0, 1)`, a 10-yard linear ramp on the
-/// glare alpha (wow-re `submerged-consumer-census.md`; decision 1829). `depth` is
-/// `liquidSurfaceHeight − probeZ` in world-Z yards, positive when submerged, so a dry camera reads
-/// `0` and the fade is the exact identity.
-///
-/// **This was a published negative until this round.** Two wow-re notes recorded the glare as
-/// having no submersion term; the read is one indirection out (`0x6cf4fe call [edx+0x10]` → the
-/// glare vtable's slot 4 → `0x6cf800`), which a direct-call census cannot see. It is worth
-/// implementing rather than filing as trivia: the glare is additive, so a black underwater
-/// celestial band would make it invisible anyway — and **288 of 374 `Light.dbc` rows (77%) carry a
-/// non-zero one**, so on most of the map there is a glare down there to fade.
-///
-/// Applies to the **sun and moon glares alike** (`0x6d48cf` / `0x6d48ea`; slot 4 of both glare
-/// vtables is `0x6cf800`, and they differ only at slot 3) and to **neither disc** — the discs have
-/// no submerged path at all, so suppressing them outright with the skipped sky pass is right. Both
-/// confirmed by census rather than assumed.
+/// The glares' submersion fade, a 10-yard ramp on `liquidSurfaceHeight − probeZ`, reached through
+/// vtable slot 4 (`0x6cf4fe call [edx+0x10]` → `0x6cf800`, from `0x6d48cf`/`0x6d48ea`); the discs
+/// have none, as their whole sky pass is skipped.
 fn submersion_glare_fade(depth: f32) -> f32 {
     1.0 - (depth * 0.1).clamp(0.0, 1.0)
 }
 
-/// The weather **celestial-alpha seed** (Addendum #6): under active weather the recompute writes
-/// `floor(255·(1−bcc))` over the five body colour alpha bytes (sun disc, sun glare, white-moon
-/// disc, moon glare, moon02) — gated `bcc > 0`, so clear weather leaves the per-frame broadcast
-/// `0xFF` (discs) and moon02's unwritten `0` untouched. Returns the byte-quantized seed, or
-/// `None` in clear weather.
+/// The weather alpha seed (`0x6d2c74`): with `bcc > 0` the recompute writes `floor(255·(1−bcc))`
+/// over all five body alpha bytes, moon02's included; clear weather leaves them alone.
 fn celestial_alpha_seed(bcc: f32) -> Option<f32> {
     (bcc > 0.0).then(|| (255.0 * (1.0 - bcc.min(1.0))).floor() / 255.0)
 }
 
 impl FlareGate<'_, '_> {
-    /// The slewed `[0, 1]` flare envelope along `dir` from the camera: slew target = `dn` (the
-    /// body's dnCurve sample) × the horizon smoothstep × `occ1` (the body's cloud occlusion) ×
-    /// the visible fraction of the body's quad (`half` = its angular half-size; the interior
-    /// claim zeroes it) and the **submersion fade** ([`submersion_glare_fade`]), all approached at
-    /// `rise`/[`FLARE_FALL`] per second.
-    ///
-    /// The fade is INSIDE the slew — one of the factors composed into the target, not a multiply on
-    /// the drawn alpha. `[glare+0x34]` is the per-frame target accumulator (reset to 1.0 at
-    /// `0x6cf499`); `0x6cf501`/`0x6cf504` multiply the fade into it, and the limiter first reads it
-    /// 158 bytes later at `0x6cf59b`, writing the envelope `[glare+0x30]` at `0x6cf5ea`. So
-    /// surfacing ramps the glare back in over the rise time rather than snapping.
-    ///
-    /// We shipped it the other way first, on the reasoning that a rate limiter should smooth
-    /// *visibility* and depth is not visibility. That reasoning was fine and the fact was against
-    /// it — wow-re's summary said the fade goes "into the glare alpha", which is the drawn byte
-    /// `[glare+0x1b]` and is not where it goes. Asked, and corrected at the bytes.
-    ///
-    /// It falls out that a deep camera (`fade == 0`) drives `base` to zero, which skips the terrain
-    /// ray march entirely — the reference's own `0x6cf58c` shortcut, for free.
+    /// The envelope along `dir`, `half` the quad's angular half-size. The submersion fade is inside
+    /// the slew, so surfacing ramps the glare back in: the target `[glare+0x34]` (reset at
+    /// `0x6cf499`) takes it at `0x6cf501`/`0x6cf504`, before the limiter reads it at `0x6cf59b`.
     fn envelope(
         &mut self,
         cam_pos: Vec3,
@@ -334,8 +216,7 @@ impl FlareGate<'_, '_> {
     ) -> f32 {
         let base = dn * horizon_gate(dir) * occ1 * submersion_glare_fade(self.submerged.depth);
         let target = if base > 0.0 && self.camera_interior.0.is_none() {
-            // Resident detailed terrain first; the coarse WDL surface everywhere else (it
-            // covers the whole map, so it also plugs the ADT-ring-to-farclip gap).
+            // Resident ADT terrain first, the whole-map WDL surface elsewhere.
             let (streamer, adt_tiles, wdl) = (&self.streamer, &self.adt_tiles, &self.wdl);
             let tile = std::cell::RefCell::new(None);
             let oracle = |p| {
@@ -347,9 +228,7 @@ impl FlareGate<'_, '_> {
                 )
                 .or_else(|| wdl.as_ref().and_then(|w| w.height_under(p)))
             };
-            // The round-robin drip (decision 1436): an unprimed mask marches every cell once,
-            // a primed one re-prices FLARE_RAYS_PER_FRAME — the slew smooths the ≤8-frame
-            // staleness exactly as it smooths the grid's own 1/16 quantization.
+            // Unprimed, march every cell; primed, `FLARE_RAYS_PER_FRAME` of them.
             let cells = if *self.primed {
                 FLARE_RAYS_PER_FRAME
             } else {
@@ -369,15 +248,9 @@ impl FlareGate<'_, '_> {
     }
 }
 
-/// Pin the sun's disc + glare to the **visible celestial sun** direction, camera-facing, and rewrite
-/// the tints from the per-frame celestial diffuse band (`WowLighting.celestial_tint`, the `0x6d2260`
-/// broadcast). The DISC sits just inside the far plane (terrain occludes it) and sets edge-first
-/// behind the horizon via the celestial.wgsl clip; its size is the unit quad × the day curve
-/// (`0xce8cac`: 2× at the dawn/dusk horizon → 1× midday). The GLARE is the `0x6cf490` lens flare on
-/// the near sphere ([`GLARE_DIST`]): quad scale `lerp(3, 20, f)` world units and intensity
-/// `lerp(0.5, 1, f)` on the view lerp, × the slewed [`FlareGate`] envelope (the sun's dnCurve makes
-/// it a DAY flare — full 07:30→19:30, gone by 21:00; decision 0508) — near-screen-filling star rays
-/// when you look into the sun. Disabled together with the sky dome.
+/// Place the sun's disc and glare, tinted by the `0x6d2260` broadcast. The disc is the unit quad ×
+/// the day curve (`0xce8cac`: 2× at the horizon, 1× at midday); the glare is `0x6cf490`'s flare,
+/// `lerp(3, 20, f)` units at `lerp(0.5, 1, f)` × the envelope, a day flare (07:30 to 19:30).
 pub(super) fn follow_sun(
     cam: Query<(&GlobalTransform, &Projection), With<WorldCamera>>,
     light: Res<WowLighting>,
@@ -389,8 +262,7 @@ pub(super) fn follow_sun(
     let Some((cam_gt, proj)) = cam.iter().next() else {
         return;
     };
-    // Track the **visible celestial sun** (which rises and sets in elevation), NOT the near-fixed
-    // lighting sun — `WowLighting.celestial_dir` is already the camera→sun (to-sun) direction.
+    // The visible sun, which rises and sets, not the near-fixed lighting sun.
     let to_light = light.celestial_dir.normalize_or_zero();
     if to_light == Vec3::ZERO {
         return;
@@ -399,21 +271,18 @@ pub(super) fn follow_sun(
         Projection::Perspective(p) => p.far,
         _ => 3000.0,
     };
-    let dist = far * 0.85; // inside the sky dome (far*0.9), so the sun draws over the gradient
+    let dist = far * 0.85; // inside the far plane; occlusion is the far-depth pin
     let cam_pos = cam_gt.translation();
     // Billboard: the quad's +Z normal faces back toward the camera (= −to_light).
     let rot = Quat::from_rotation_arc(Vec3::Z, -to_light);
-    let hidden = debug.lighting.disable_sky_dome; // the sun is part of the sky — hide it with the dome
+    let hidden = debug.lighting.disable_sky_dome; // part of the sky, hidden with the dome
     let f = view_lerp(*cam_gt.forward(), to_light);
-    // Byte-quantized at the source ([`benilla_assets::quant255`]) so the write gates below only
-    // fire on a display-visible change — the reference's own color lanes are bytes.
+    // Byte-quantized like the reference's colour lanes, so the write gates fire on visible change.
     let tint = benilla_assets::quant255(light.celestial_tint);
-    // The weather celestial-alpha seed — dims the disc + glare under active weather.
     let seed = celestial_alpha_seed(light.storm_bcc);
-    // The occlusion probe covers the disc's own quad (Addendum #8): its angular half-size.
+    // The occlusion probe (`0x7e5220`) covers the disc's own quad: its angular half-size.
     let sun_half = (0.5 * SUN_SIZE * light.sun_disc_scale).atan();
-    // occ1: cloud coverage over the sun's glare point (`0x6cf7b0` samples at glarePos = camera +
-    // 12·dir) — a cloud drifting over the sun dims the flare linearly.
+    // occ1: the cloud cover at the glare point, `cam + 12·dir` (`0x6cf7b0`), dims the flare.
     let occ1 = occ1_sun(gate.clouds.coverage(to_light * GLARE_DIST));
     let env30 = gate.envelope(
         cam_pos,
@@ -436,8 +305,7 @@ pub(super) fn follow_sun(
                 tf.scale = Vec3::splat(size * dist);
                 let color = Color::srgb(tint[0], tint[1], tint[2]);
                 let span = quant_span(disc_span(to_light.y, size));
-                // Above-band disc opacity: the 0xFF broadcast, overwritten by the weather
-                // seed under active weather ([`celestial_alpha_seed`]).
+                // Above-band opacity: the 0xFF broadcast, or the weather seed.
                 let fade_w = benilla_assets::quantize(seed.unwrap_or(1.0), 255.0);
                 benilla_assets::write_gated(
                     &mut mats,
@@ -456,17 +324,11 @@ pub(super) fn follow_sun(
             }
             SunPart::Glare => {
                 tf.translation = cam_pos + to_light * GLARE_DIST;
-                // `lerp(3, 20, f)` world units (sun endpoints `[0xce9838]`/`[0xce983c]`, base ×1.0)
-                // — on the near sphere the builder's units are the quad scale directly.
+                // `lerp(3, 20, f)` world units (`[0xce9838]`/`[0xce983c]`).
                 let units = 3.0 + 17.0 * f;
                 tf.scale = Vec3::splat(if hidden { 0.0 } else { units });
-                // Intensity: the view lerp's `lerp(0.5, 1, f)` (`[glare+0x9c]=0.5 → 1.0`, instant)
-                // × the slewed envelope (dnCurve × horizon × visibility — Addendum #5's
-                // `[+0x1b] = floor(255·lerp·[+0x30])` shape). Rides base_color alpha — the shader's
-                // glare mode ADDS `gamma(tint × texel) × a` onto the scene, the reference's
-                // SRC_ALPHA byte weighting (decision 0502).
-                // × the weather seed — the glare's alpha byte is the seed the per-frame pack
-                // modulates (Addendum #6: `oldByte` into `0x6cf490`), so storms dim the flare.
+                // Alpha is `lerp(0.5, 1, f)` (`[glare+0x9c]`) × the envelope × the weather seed,
+                // `0x6cf490`'s `[+0x1b] = floor(255·lerp·[+0x30])` on the seed byte.
                 let env =
                     benilla_assets::quantize((0.5 + 0.5 * f) * env30 * seed.unwrap_or(1.0), 255.0);
                 let color = Color::srgba(tint[0], tint[1], tint[2], env);
@@ -478,21 +340,14 @@ pub(super) fn follow_sun(
                 );
             }
         }
-        // Propagation already ran this frame — the direct global write is what renders.
+        // Propagation already ran, so the direct global write is what renders.
         *gt = GlobalTransform::from(*tf);
     }
 }
 
-/// Pin the white moon's disc + glare to the moon's world direction (azimuth 45°, the sun's bearing),
-/// camera-facing, at the same far distance as the sun, and rewrite both tints from the per-frame
-/// celestial diffuse band (the same `0x6d2260` broadcast the sun reads — the glare is WARM; the teal
-/// rim the director sees is the dome's night bands through the disc's feathered edge, decision 0485).
-/// Disc size = the unit quad × the white-moon base ×1.75 × the shared size curve (`0xce8c8c`, 1.5×
-/// at moonrise/set → 1× overhead); it rises/sets edge-first via the shader clip+fade. The GLARE quad
-/// = `2.0 ×` the same curve (`0x6cf490` overwrites both lerp endpoints with it; ≈1.14× the disc),
-/// intensity `lerp(0.1, 1, f)` on the view lerp × the slewed [`FlareGate`] envelope — whose moon
-/// dnCurve makes the halo a DEEP-NIGHT thing: nothing until 22:45, full only near midnight
-/// (decision 0508). Disabled with the sky dome.
+/// Place the white moon (azimuth 45°) and its glare, tinted by the same broadcast, and moon02. The
+/// disc is the unit quad × 1.75 × the size curve (`0xce8c8c`: 1.5× at the horizon, 1× overhead);
+/// the glare is 2.0 × that curve at `lerp(0.1, 1, f)` × the envelope, dark until 22:45.
 pub(super) fn follow_moons(
     cam: Query<(&GlobalTransform, &Projection), With<WorldCamera>>,
     light: Res<WowLighting>,
@@ -511,22 +366,17 @@ pub(super) fn follow_moons(
     let dist = far * 0.85;
     let cam_pos = cam_gt.translation();
     let hidden = debug.lighting.disable_sky_dome;
-    // Byte-quantized at the source, like [`follow_sun`] — the write gates fire on display-visible
-    // change only.
     let tint = benilla_assets::quant255(light.celestial_tint);
-    // The weather celestial-alpha seed — dims both moons' discs + the glare under active weather.
     let seed = celestial_alpha_seed(light.storm_bcc);
-    // One slewed envelope per frame, along the white moon's ray (only its glare exists). The moon's
-    // dnCurve inside the target is the load-bearing night gate: flat 0 until 22:45, full near
-    // midnight (decision 0508) — a 22:30 moonrise carries NO halo, exactly like the reference.
+    // One envelope, along the white moon's ray, the only glare; its dnCurve is 0 until 22:45.
     let to_white = light.moon_dir_white.normalize_or_zero();
     let env30 = if to_white == Vec3::ZERO {
         0.0
     } else {
-        // The occlusion probe covers the white moon's own disc quad (Addendum #8).
+        // The occlusion probe (`0x7e5220`) covers the white moon's own disc quad.
         let moon_half = (0.5 * SUN_SIZE * 1.75 * light.moon_disc_scale).atan();
-        // occ1: the moon's halo is a THIN-CLOUD effect — the tent `1−|2(R−0.5)|` (`0x6cf7d0`) is
-        // zero in a perfectly clear patch of sky AND under full cover, peaking on a wisp.
+        // occ1: the tent `1−|2(R−0.5)|` (`0x6cf7d0`), 0 in clear sky and under full cover,
+        // peaking on a wisp.
         let occ1 = occ1_moon(gate.clouds.coverage(to_white * GLARE_DIST));
         gate.envelope(
             cam_pos,
@@ -538,7 +388,7 @@ pub(super) fn follow_moons(
         )
     };
     for (mut tf, mut gt, moon, mat) in &mut sprites {
-        // moon02 rides its own phase-precessed bearing; the disc + glare share the white moon's.
+        // moon02 rides its own phase-precessed bearing; the disc and glare share the white moon's.
         let to_moon = match moon.part {
             MoonPart::Moon02 => light.moon_dir_02.normalize_or_zero(),
             _ => to_white,
@@ -575,12 +425,9 @@ pub(super) fn follow_moons(
                 );
             }
             MoonPart::Moon02 => {
-                // Base ×1.0, the shared size curve on moon02's own phase clock. The binary never
-                // writes its colour dword — black RGB, zero alpha, so the quad is invisible in
-                // clear weather (wow-re Addendum #7) — but the weather seed lands on its alpha
-                // byte like the other four: under active weather moon02 surfaces as the
-                // reference's faint dark disc (Addendum #6 C4). The span drives the per-vertex
-                // fade lane (0529) so a horizon crossing keeps the faithful sub-band wedge.
+                // Base ×1.0 on its own phase clock. Its colour (`0xce98a4`) is never written, black
+                // at alpha 0, but the weather seed lands on its alpha byte, a faint dark disc
+                // (`0x6d2c74`); the span still drives its wedge in the horizon band.
                 tf.translation = cam_pos + to_moon * dist;
                 let size = if hidden {
                     0.0
@@ -601,10 +448,7 @@ pub(super) fn follow_moons(
                 );
             }
             MoonPart::Glare => {
-                // `2.0 × the moon size curve` world units (`[0xce9718]=2.0`; both view-lerp
-                // endpoints get the curve, so the size is f-independent) — near-sphere placement,
-                // so the builder's units are the quad scale directly (same angular size as before:
-                // `2.0/12` rad ≈ 1.14× the disc).
+                // `2.0 × the size curve` (`[0xce9718]`) at both lerp ends, whatever `f`.
                 tf.translation = cam_pos + to_moon * GLARE_DIST;
                 let size = if hidden {
                     0.0
@@ -612,10 +456,9 @@ pub(super) fn follow_moons(
                     2.0 * light.moon_disc_scale
                 };
                 tf.scale = Vec3::splat(size);
-                // The view lerp's `lerp(0.1, 1, f)` (`[0xce9794]=0.1`, instant) × the slewed
-                // envelope (dnCurve × horizon × visibility) — Addendum #5's byte shape.
+                // `lerp(0.1, 1, f)` (`[0xce9794]`) × the envelope, `0x6cf490`'s byte shape.
                 let f = view_lerp(*cam_gt.forward(), to_moon);
-                // × the weather seed (the glare alpha byte the pack modulates, Addendum #6).
+                // × the weather seed on the glare's alpha byte (`0x6d2c74`).
                 let env =
                     benilla_assets::quantize((0.1 + 0.9 * f) * env30 * seed.unwrap_or(1.0), 255.0);
                 let color = Color::srgba(tint[0], tint[1], tint[2], env);
@@ -627,19 +470,13 @@ pub(super) fn follow_moons(
                 );
             }
         }
-        // Propagation already ran this frame — the direct global write is what renders.
+        // Propagation already ran, so the direct global write is what renders.
         *gt = GlobalTransform::from(*tf);
     }
 }
 
-/// Camera-anchor the star dome (just inside the sky gradient dome, at `far*0.88` — over the gradient at
-/// `far*0.9`, behind the sun/moon at `far*0.85`; the reference draws stars FIRST among the bodies —
-/// though the sky-internal order is the `sky_order` bias ladder and world occlusion is the far depth
-/// `sky_vertex.wgsl` pins, so this radius decides neither, only the dots' screen scale) and
-/// drive its **global alpha** from the verified star curve. The reference quantises the curve to the
-/// model-global byte `trunc(curve·254 + 1)` and SKIPS the draw below 2 (`0x6d1b50`/`0x7e6120`, decision
-/// 0485); each patch then multiplies its own authored transparency weight ([`StarDome::weight`]) under
-/// the global fade. Hidden (alpha 0) with the sky dome.
+/// Anchor the star dome and fade it by the model-global byte `trunc(curve·254 + 1)`, the draw
+/// skipped below 2 (`0x6d1b50`/`0x7e6120`), times each patch's [`StarDome::weight`].
 pub(super) fn follow_stars(
     cam: Query<(&GlobalTransform, &Projection), With<WorldCamera>>,
     light: Res<WowLighting>,
@@ -662,7 +499,6 @@ pub(super) fn follow_stars(
         Projection::Perspective(p) => p.far,
         _ => 3000.0,
     };
-    // The byte-exact global fade: byte = trunc(curve·254 + 1), skipped when < 2, else alpha = byte/255.
     let byte = (light.star_alpha * 254.0 + 1.0).trunc();
     let global = if debug.lighting.disable_sky_dome || byte < 2.0 {
         0.0
@@ -672,11 +508,9 @@ pub(super) fn follow_stars(
     for (mut tf, mut gt, mat, dome) in &mut stars {
         tf.translation = cam_gt.translation();
         tf.scale = Vec3::splat(far * 0.88);
-        // Propagation already ran this frame — the direct global write is what renders.
+        // Propagation already ran, so the direct global write is what renders.
         *gt = GlobalTransform::from(*tf);
-        // White dots; global fade × the patch's authored weight, multiplied onto the texture's
-        // per-dot alpha, then blended gamma-correctly by star.wgsl. The vertex alpha is a byte
-        // in the reference, so the product gates at 1/255 like the rest of the family.
+        // The fade × the patch weight, in 1/255 steps, as the reference's vertex alpha is a byte.
         let color = Color::srgba(
             1.0,
             1.0,
@@ -696,16 +530,13 @@ pub(super) fn follow_stars(
 mod glare_fade_tests {
     use super::submersion_glare_fade;
 
-    /// The 10-yard linear ramp, and — the half that matters most — the exact identity when dry.
-    /// A dry camera reads `depth = 0`, so this multiplies every glare in the game by 1.0; if that
-    /// were ever not exact, the feature would be a global dimmer rather than an underwater one.
+    /// Dry must be the exact identity, or the fade would dim every glare in the game.
     #[test]
     fn the_glare_fades_linearly_over_ten_yards() {
         assert_eq!(submersion_glare_fade(0.0), 1.0, "dry is the exact identity");
         assert_eq!(submersion_glare_fade(5.0), 0.5);
         assert_eq!(submersion_glare_fade(10.0), 0.0);
         assert_eq!(submersion_glare_fade(200.0), 0.0, "clamped, never negative");
-        // Linear in between, and monotone all the way down.
         let mut prev = 1.0;
         for i in 1..=10 {
             let f = submersion_glare_fade(i as f32);
@@ -722,14 +553,7 @@ mod tests {
     use crate::dev_state::DebugState;
     use crate::wmo_portal::CameraInteriorClaim;
 
-    /// The moonrise-halo lag regression (decision 0504): with the camera moving every frame, the
-    /// glare quad's rendered pose (`GlobalTransform`) must be placed from the SAME frame's camera —
-    /// zero error. The old plain-`Update` wiring read the camera's `GlobalTransform` (synced only in
-    /// `PostUpdate`), placing the quad from the *previous* frame's camera: this exact harness
-    /// measured the error at exactly one frame of camera motion (1.0 unit/frame here; `v·dt` live —
-    /// ~1% of the glare's 12-unit distance per 60 fps frame at run speed), which on screen was the
-    /// director's halo swim + toward/away size pump. Mirrors `SunPlugin`'s registration: PostUpdate,
-    /// the post-propagation [`crate::billboard::BillboardPlace`] slot, direct `GlobalTransform` write.
+    /// The glare is placed from the moving camera's same-frame pose, under `SunPlugin`'s wiring.
     #[test]
     fn glare_rides_the_same_frame_camera_while_moving() {
         let dir = Vec3::new(0.0, 0.5, -1.0).normalize();
@@ -739,8 +563,7 @@ mod tests {
         app.init_resource::<CameraInteriorClaim>();
         app.init_resource::<CloudCoverage>();
         app.init_resource::<DebugState>();
-        // Dry (depth 0) — this fixture is about the glare tracking the camera within one frame,
-        // and the submersion fade is the exact identity there, so it cannot perturb the assertion.
+        // Dry (depth 0), where the submersion fade is the exact identity.
         app.init_resource::<crate::liquid::SubmergedEye>();
         app.insert_resource(WowLighting {
             moon_dir_white: dir,
@@ -779,7 +602,6 @@ mod tests {
                 q.single_mut().unwrap().translation += dir * 1.0;
             },
         );
-        // The plugin's wiring: post-propagation placement in the BillboardPlace slot.
         app.configure_sets(
             PostUpdate,
             crate::billboard::BillboardPlace.after(bevy::transform::TransformSystems::Propagate),
@@ -823,8 +645,6 @@ mod tests {
         })
     }
 
-    /// The `[glare+0x30]` slew (Addendum #5, 0508): asymmetric LINEAR rates — rise capped per body,
-    /// fall shared and slower — and it clamps to the target instead of overshooting.
     #[test]
     fn flare_slew_is_asymmetric_linear_and_never_overshoots() {
         // Rising at the sun's 4.0/s: 0.1 s covers exactly 0.4.
@@ -843,7 +663,7 @@ mod tests {
     fn flare_ray_blocked_by_a_ridge_but_not_by_open_sky() {
         let cam = Vec3::new(0.0, 2.0, 0.0); // eye 2 units above the plain
         let low = Vec3::new(1.0, 0.01, 0.0).normalize(); // grazes under the 30-unit crest
-        let high = Vec3::new(1.0, 1.0, 0.0).normalize(); // 45° — well over it
+        let high = Vec3::new(1.0, 1.0, 0.0).normalize(); // 45°, well over it
         assert!(!flare_ray_clear(ridge, cam, low));
         assert!(flare_ray_clear(ridge, cam, high));
         // No terrain in any column (open ocean / unstreamed) is never an occluder.
@@ -859,11 +679,9 @@ mod tests {
             Vec3::new(e.cos(), e.sin(), 0.0)
         };
         let half = 2.0_f32.to_radians();
-        // Fully clear well above the crest line; fully blocked well under it.
         assert_eq!(flare_visible_fraction(ridge, cam, dir(12.0), half), 1.0);
         assert_eq!(flare_visible_fraction(ridge, cam, dir(1.0), half), 0.0);
-        // A disc straddling the crest line is PARTIALLY visible — the fractional occ3 law
-        // (Addendum #8: half-hidden sun → ~half flare), not the old all-or-nothing gate.
+        // Straddling the crest, partly visible (`0x7e5220`: half hidden, about half the flare).
         let frac = flare_visible_fraction(ridge, cam, dir(5.4), half);
         assert!(
             (0.25..=0.75).contains(&frac),
@@ -871,14 +689,13 @@ mod tests {
         );
     }
 
-    /// The 1436 round-robin drip is the full march, just spread over frames: priming reads the
-    /// exact full-march fraction, and a whole 2-cells-per-step cycle over an unchanged scene
-    /// lands back on it (the mask never reads a partial window — every step reads all 16 bits).
+    /// Priming reads the full march's fraction, and a whole drip cycle over an unchanged scene
+    /// lands back on it.
     #[test]
     fn flare_mask_drip_converges_to_the_full_march() {
         let cam = Vec3::new(0.0, 2.0, 0.0);
         let e = 5.4_f32.to_radians();
-        let dir = Vec3::new(e.cos(), e.sin(), 0.0); // straddles the ridge crest — a partial mask
+        let dir = Vec3::new(e.cos(), e.sin(), 0.0); // straddles the ridge crest: a partial mask
         let half = 2.0_f32.to_radians();
         let full = flare_visible_fraction(ridge, cam, dir, half);
         assert!((0.0..1.0).contains(&full), "oracle must be partial: {full}");
@@ -896,14 +713,10 @@ mod tests {
 
     #[test]
     fn disc_span_feeds_the_per_vertex_fade_regimes() {
-        // Elevated (every fixture's regime): the whole span sits far above the ~1.9° fade band
-        // (sin ≈ 1/30), so the shader's vertex rule returns the colour alpha at both edges — the
-        // disc renders exactly `a × a_disc`, unchanged from before 0529.
+        // Elevated: above the ~1.9° fade band (sin ≈ 1/30), so both edges take the colour alpha.
         let up = disc_span(30_f32.to_radians().sin(), 0.0833);
         assert!(up.x > 1.0 / 30.0 && up.y > up.x, "elevated: above the band");
-        // A 2×-sized setting sun with its centre 2° up straddles the horizon: bottom edge below
-        // 0 (clipped at the cut, alpha 0 there), top edge above the band (alpha = colour) — the
-        // whole-disc melt gradient.
+        // A 2× setting sun 2° up: bottom edge below the horizon, top edge above the band.
         let setting = disc_span(2_f32.to_radians().sin(), 0.1667);
         assert!(setting.x < 0.0, "setting: bottom edge under the horizon");
         assert!(setting.y > 1.0 / 30.0, "setting: top edge above the band");
@@ -912,14 +725,12 @@ mod tests {
         assert!((mid.x + mid.y).abs() < 1e-6);
     }
 
-    /// The weather celestial-alpha seed (Addendum #6): gated `bcc > 0` — clear weather leaves the
-    /// broadcast alphas alone — and byte-quantized `floor(255·(1−bcc))/255` under weather.
     #[test]
     fn weather_seed_is_gated_and_byte_quantized() {
         assert_eq!(celestial_alpha_seed(0.0), None);
         // Full storm: the seed zeroes every body alpha.
         assert_eq!(celestial_alpha_seed(1.0), Some(0.0));
-        // Half density: floor(255·0.5) = 127 — the byte floor, not a smooth 0.5.
+        // Half density: floor(255·0.5) = 127, the byte floor, not a smooth 0.5.
         let half = celestial_alpha_seed(0.5).unwrap();
         assert!((half - 127.0 / 255.0).abs() < 1e-6);
     }
diff --git a/crates/benilla-world/src/sun/materials.rs b/crates/benilla-world/src/sun/materials.rs
index 7f6347bf..8a605f54 100644
--- a/crates/benilla-world/src/sun/materials.rs
+++ b/crates/benilla-world/src/sun/materials.rs
@@ -1,7 +1,4 @@
-//! GPU materials for the celestial layer — the alpha-blended **disc** material (with the horizon clip +
-//! per-fragment alpha ramp) and the gamma-correct **star** material. Both are [`ExtendedMaterial`]s over
-//! `StandardMaterial`; the fragment shaders live in `src/shaders/{celestial,star}.wgsl`,
-//! compiled in and served as `embedded://benilla_world/shaders/…` (decision 1175).
+//! The celestial and star [`ExtendedMaterial`]s, drawn by `celestial.wgsl` and `star.wgsl`.
 
 use bevy::mesh::MeshVertexBufferLayoutRef;
 use bevy::pbr::{
@@ -15,47 +12,28 @@ use bevy::shader::ShaderRef;
 
 use crate::sky_order::{sky_pipeline_state, SKY_VERTEX_SHADER};
 
-/// Material for every celestial body sprite — the **discs** (sun, white moon, moon02) *and* their
-/// additive lens-flare **glares** — an [`ExtendedMaterial`] over `StandardMaterial` whose fragment
-/// shader (`celestial.wgsl`) replicates the unlit look **in gamma space** (the 0161 composite lane) in
-/// one of two modes ([`CelestialExt::fade`]`.z`): discs get the **world-space horizon clip +
-/// per-fragment alpha ramp** (the real `0x6d1960` clip+fade every disc routes through; decision 0485)
-/// under a premultiplied gamma blend; glares skip the clip and **ADD gamma bytes** under
-/// `AlphaMode::Add` — the reference's SRC_ALPHA, ONE lens-flare blend (`0x7e5a16`), which is what lets
-/// the flare saturate the sun's core to white (decision 0502; plain linear `Add` under-weighted every
-/// mid-tone — the "too yellow" sun).
+/// Every disc and glare, blended in gamma space like the reference. A disc takes the horizon clip
+/// and fade (`0x6d1960`) under a premultiplied blend; a glare skips it and adds gamma bytes, the
+/// reference's SRC_ALPHA, ONE flare blend (`0x7e5a16`), which saturates the sun's core to white.
 pub type CelestialMaterial = ExtendedMaterial<StandardMaterial, CelestialExt>;
 
-/// Per-material control. `fade.x` = the horizon alpha-ramp scale `k` (in sin-elevation terms;
-/// [`DISC_HORIZON_FADE`] for all three discs — the binary's 0.4-unit band at its radius-12 disc,
-/// clip+fade `0x6d1960`, decision 0485). `fade.w` = the disc COLOUR's own alpha byte: `1.0` for the
-/// sun/white moon (their diffuse broadcast writes 0xFF every frame), `0.0` for moon02 (its colour
-/// dword has no writer in the binary — the draw runs and paints nothing: the reference's invisible
-/// second moon; wow-re Addendum #7). The fade is the reference's PER-VERTEX conditional store
-/// (band vertices take the ramp instead of the colour alpha), which the fragment shader
-/// reconstructs by interpolating over [`CelestialExt::span`] — a setting body melts as a
-/// whole-disc gradient (decision 0529; supersedes the 0485 per-fragment band and 0524's
-/// workaround). Under active weather the follow systems overwrite `fade.w` with the celestial
-/// alpha seed `floor(255·(1−bcc))/255` on all three discs (`bcc` = weather density × 4, clamped —
-/// Addendum #6; `follow::celestial_alpha_seed`), so storms dim the bodies and surface moon02's
-/// faint dark disc. `fade.y` = a brightness multiplier on the emitted colour — `1.0` everywhere (the old
-/// moon `1.6` HDR boost died with decision 0163: the reference is LDR bytes and its moon glow is
-/// FFXGlow's blur² on the disc's own bytes). `fade.z` = mode: 0 = disc, 1 = additive glare (no
-/// clip, gamma add — the glares never route `0x6d1960`; their envelope gates them; `fade.w`/`span`
-/// unused there).
+/// The shader's controls. `fade`: `.x` the horizon ramp slope in sin-elevation
+/// ([`DISC_HORIZON_FADE`]); `.y` a brightness on RGB, 1.0; `.z` 0 for a disc, 1 for a glare,
+/// which never routes `0x6d1960`; `.w` the disc colour's alpha byte above the band, 1.0 from the
+/// 0xFF broadcast and 0 for moon02, whose colour has no writer (`0xce98a4`). Under weather `.w`
+/// takes the alpha seed `floor(255·(1−bcc))/255` (`0x6d2c74`), `bcc = min(1, density·4)`. The
+/// reference's per-vertex fade is interpolated across [`CelestialExt::span`].
 #[derive(Asset, AsBindGroup, Clone, TypePath, Default)]
 pub struct CelestialExt {
     #[uniform(100)]
     pub(super) fade: Vec4,
-    /// The disc quad's vertical span in sin-elevation — `.x` = bottom edge, `.y` = top edge —
-    /// written per frame by the follow systems ([`super::follow::disc_span`]). The shader
-    /// interpolates the per-vertex fade rule across it (decision 0529). `.zw` unused.
+    /// The disc quad's bottom (`.x`) and top (`.y`) edges in sin-elevation, written each frame.
     #[uniform(101)]
     pub(super) span: Vec4,
 }
 
 impl MaterialExtension for CelestialExt {
-    /// The shared sky vertex stage — the far-depth pin ([`crate::sky_order`], "The depth law").
+    /// The shared sky vertex stage, the far-depth pin ([`crate::sky_order`]).
     fn vertex_shader() -> ShaderRef {
         SKY_VERTEX_SHADER.into()
     }
@@ -75,25 +53,19 @@ impl MaterialExtension for CelestialExt {
     }
 }
 
-/// Disc horizon alpha-ramp scale, shared by every celestial disc: `alpha *= clamp(30·dir.y, 0, 1)` —
-/// the faithful `0x6d1960` fade (`alpha = clamp(2.5·height, 0, 1)` with the disc at radius 12 ⇒
-/// `2.5·12·dir.y`), a soft edge over the bottom ~1.9° of elevation; ≤ 0 clips (the reference skips
-/// the whole body below the horizon).
+/// The discs' horizon ramp slope: `0x6d1960`'s `clamp(2.5·height, 0, 1)` at radius 12 is
+/// `clamp(30·dir.y, 0, 1)`, a soft edge over the bottom ~1.9° of elevation; at or below 0 it clips.
 pub(super) const DISC_HORIZON_FADE: f32 = 30.0;
 
-/// Material for the **star** patches — an [`ExtendedMaterial`] over `StandardMaterial` whose fragment
-/// (`star.wgsl`) does a **gamma-correct premultiplied** blend so the soft white dots blend into the sky
-/// like the reference, instead of over-brightening (our linear-space alpha blend would; see the shader
-/// header). Used with `AlphaMode::Premultiplied`. `StarExt` carries no uniforms.
+/// The star patches, blended premultiplied in gamma space by `star.wgsl`, like the reference.
 pub type StarMaterial = ExtendedMaterial<StandardMaterial, StarExt>;
 
-/// Empty material extension — the star fragment needs no per-material uniforms (it reads the base-colour
-/// alpha = dot alpha × the star-curve global alpha).
+/// No uniforms: the star fragment reads the base colour's alpha, the star-curve fade.
 #[derive(Asset, AsBindGroup, Clone, TypePath, Default)]
 pub struct StarExt {}
 
 impl MaterialExtension for StarExt {
-    /// The shared sky vertex stage — the far-depth pin ([`crate::sky_order`], "The depth law").
+    /// The shared sky vertex stage, the far-depth pin ([`crate::sky_order`]).
     fn vertex_shader() -> ShaderRef {
         SKY_VERTEX_SHADER.into()
     }
diff --git a/crates/benilla-world/src/sun/mesh.rs b/crates/benilla-world/src/sun/mesh.rs
index 949f0aa6..4a7a6da4 100644
--- a/crates/benilla-world/src/sun/mesh.rs
+++ b/crates/benilla-world/src/sun/mesh.rs
@@ -1,6 +1,4 @@
-//! Pure geometry + sprite-texture builders for the celestial layer — no ECS, no systems: a unit billboard
-//! quad, the procedural star-field fallback mesh, and the baked soft-round sprite texture. Consumed by
-//! [`super::setup`].
+//! The celestial layer's billboard quad, procedural star field and soft round sprite.
 
 use bevy::asset::RenderAssetUsages;
 use bevy::image::Image;
@@ -30,8 +28,7 @@ pub(super) fn quad_mesh() -> Mesh {
     m
 }
 
-/// Deterministic per-star pseudo-random in `[0,1)` from an index — no `rand` dep, and stable across runs
-/// so the star field is the same every frame (no flicker). (A small integer bit-mix / hash.)
+/// A pseudo-random `[0, 1)` from an index, stable across frames so the stars never flicker.
 fn hash01(n: u32) -> f32 {
     let mut x = n.wrapping_mul(747_796_405).wrapping_add(2_891_336_453);
     x = (x ^ (x >> 16)).wrapping_mul(2_246_822_519);
@@ -39,15 +36,10 @@ fn hash01(n: u32) -> f32 {
     (x & 0x00ff_ffff) as f32 / 0x0100_0000 as f32
 }
 
-/// A procedural **star field**: `count` small camera-facing quads scattered over the upper hemisphere at
-/// unit radius (the caller scales to the star distance), each a soft dot. This replaces a tiled-texture
-/// dome — tiling `Stars.blp` over the whole hemisphere stretched its 256² dots into big pixelated blobs;
-/// scattered *small* quads read as crisp star points with no repetition and no magnification. Positions are
-/// deterministic (hashed by index), distributed by uniform hemisphere area with a touch of size variation.
-/// (`Stars.m2`'s authored point layout would be the byte-faithful version; this is a clean visual stand-in.)
-/// Each quad faces the centred camera (normal = −dir).
+/// The assetless stand-in for `Stars.m2`: `count` small quads facing the centre, over the upper
+/// hemisphere at unit radius, hashed by index and uniform by area, with some size variation.
 pub(super) fn star_field_mesh(count: u32) -> Mesh {
-    const SIZE: f32 = 0.0022; // half-size on the unit sphere → ~0.13° on-screen at the star distance
+    const SIZE: f32 = 0.0022; // half-size on the unit sphere, ~0.13°
     let mut positions = Vec::with_capacity(count as usize * 4);
     let mut uvs = Vec::with_capacity(count as usize * 4);
     let mut normals = Vec::with_capacity(count as usize * 4);
@@ -89,10 +81,8 @@ pub(super) fn star_field_mesh(count: u32) -> Mesh {
     m
 }
 
-/// Bake a soft **round** sprite texture: white RGB everywhere, alpha = a smooth radial disc that is
-/// opaque inside `core` and fades to fully transparent by `edge` (both normalised: 0 = centre, 1 =
-/// edge midpoint of the square). The transparent corners are what make the square quad read as a
-/// circle. `edge ≥ 1` lets the falloff run all the way to the quad edge (used for the soft glow).
+/// A white sprite whose alpha is opaque inside `core` and 0 beyond `edge` (0 = centre, 1 = the
+/// square's edge midpoint), with a smoothstep between.
 pub(super) fn radial_sprite(size: u32, core: f32, edge: f32) -> Image {
     let mut data = vec![0u8; (size * size * 4) as usize];
     let c = (size as f32 - 1.0) * 0.5;
@@ -101,7 +91,6 @@ pub(super) fn radial_sprite(size: u32, core: f32, edge: f32) -> Image {
             let dx = (x as f32 - c) / c;
             let dy = (y as f32 - c) / c;
             let r = (dx * dx + dy * dy).sqrt(); // 0 centre → 1 edge-mid → ~1.41 corner
-                                                // Smooth 1→0 ramp across [core, edge] (1 − smoothstep), so the disc has a soft AA edge.
             let t = ((r - core) / (edge - core)).clamp(0.0, 1.0);
             let a = 1.0 - (t * t * (3.0 - 2.0 * t));
             let i = ((y * size + x) * 4) as usize;
diff --git a/crates/benilla-world/src/sun/mod.rs b/crates/benilla-world/src/sun/mod.rs
index 6f2f8d65..cb4e813f 100644
--- a/crates/benilla-world/src/sun/mod.rs
+++ b/crates/benilla-world/src/sun/mod.rs
@@ -1,48 +1,12 @@
-//! Celestial sprites — the **sun** (disc + glare halo), the **white moon** (disc + glare), and the
-//! night-sky **stars**, drawn over the sky dome. Byte-pinned end to end by the wow-re celestial-bodies
-//! §5 (decision 0485): setup `0x6d1ba0` builds six bodies (sun/moon glares, three discs, stars), the
-//! builder `0x6d3b80` places each on a camera-centred sphere of radius 12 (`pos = cam + 12·dir`, world
-//! space — no local→world rotation), `CSky::Render 0x6d4940` draws stars → sun → white moon → moon02
-//! at a far depth slice with depth-write off (terrain occludes), and every disc routes through the
-//! shared horizon clip+fade `0x6d1960`. This subsystem's plugin is [`SunPlugin`] (kept that name though
-//! it covers every celestial body). Submodules, each its own concern:
-//! - [`materials`] — the disc clip+fade [`materials::CelestialMaterial`] and the gamma-correct star material.
-//! - [`mesh`] — pure quad / star-field / sprite-texture builders.
-//! - [`setup`] — the startup spawn of every celestial entity.
-//! - [`follow`] — the per-frame positioning, tinting, and fades.
-//!
-//! **The bodies** (all textures the real client's, from the patch chain):
-//! - **Sun disc** — `sunCenter.blp`, plain alpha blend, a 1.0-unit quad at radius 12 (angular diameter
-//!   `2·atan(0.5/12) = 4.77°`), size × the day curve (2× at the dawn/dusk horizon → 1× midday).
-//! - **Sun glare** — `sunGlare.blp` (a big dark radial glow with authored star rays), additive,
-//!   co-located; a **view-lerped lens flare** (`0x6cf490`): quad scale 3→20 world units as the view
-//!   axis swings onto the sun (`f = saturate((cosθ − 0.7)/0.3)`), intensity `lerp(0.5, 1, f)` × the
-//!   slewed dnCurve envelope — a DAY flare, full 07:30→19:30, gone by 21:00 (decision 0508).
-//! - **White moon** — `moon.blp`, alpha blend, base ×1.75, up at night (azimuth 45°, the sun's bearing).
-//! - **Moon glare** — `moonglare.blp` (a soft ring), additive, co-located; quad scale = `2.0 × the
-//!   moon size curve` (≈1.14× the disc, both endpoints overwritten per frame), intensity
-//!   `lerp(0.1, 1, f)` on the same view lerp × the slewed dnCurve envelope — a DEEP-NIGHT halo,
-//!   nothing until 22:45, full only near midnight (decision 0508).
-//! - **Stars** — the real `Stars.m2` patches, camera-anchored, global alpha = the star curve, each
-//!   patch × its authored transparency weight.
-//!
-//! **The tint law** (the big 0485 correction): the discs' and glares' RGB is NOT hardcoded — the real
-//! client broadcasts one DayNight **celestial diffuse** colour (`[0xce9c2c]` = LightIntBand sub-9,
-//! resolved per zone + time; alpha forced 0xFF) into the sun disc, sun glare, white-moon disc, and
-//! moon glare every frame. Warm cream at night, orange at dawn/dusk — the follow systems rewrite the
-//! material tints per frame. The engine's third disc (`moon02.blp`) has NO colour writer in the
-//! binary — it draws vertex-black at azimuth 135–165° on a phase-precessed schedule and can never
-//! read as a second moon. The director's Westfall observation (one moon, a TEAL rim) is reproduced
-//! NOT by any cool tint — the moon + its glare are warm — but by the dome's teal night bands
-//! (sub-3..6) alpha-blending through the moon disc's feathered edge + horizon fade.
-//!
-//! The DISCS are pinned at their body directions (`WowLighting.{celestial_dir, moon_dir_white}`) just
-//! inside the far plane, so terrain occludes them like the reference's far-depth-slice trick. The GLARE
-//! quads sit on the reference's own **near sphere** (`cam + 12·dir` — a far-placed quad at the byte-law
-//! flare size pierced the sky dome and the depth test cut a giant faceted halo edge; decision 0500);
-//! their envelope, not the depth buffer, hides an occluded flare (the [`follow`] terrain/interior
-//! visibility gate — the occlusion-query stand-in). Our camera fovy (45°) ≈ the reference's (44.1°), so
-//! plain world placement reproduces its projection in both axes.
+//! The celestial layer over the sky dome: the sun and white moon (each a disc and an additive
+//! glare), moon02 and the `Stars.m2` stars. The reference's setup `0x6d1ba0` builds the six
+//! bodies, the builder `0x6d3b80` places each at `cam + 12·dir`, `CSky::Render` (`0x6d4940`) draws
+//! stars, sun, white moon and moon02 in a far depth slice without depth writes, and every disc
+//! takes the horizon clip and fade `0x6d1960`. One broadcast celestial diffuse (`[0xce9c2c]`,
+//! LightIntBand sub-9, alpha 0xFF) tints every disc and glare but moon02, which has no colour
+//! writer; the white moon's teal rim is the dome's night bands (sub-3..6) through its feathered
+//! edge. Every body takes the sky's far-depth pin. The bodies are placed in plain world space, so
+//! they project through our camera's 45° fovy, where the reference's is 44.1° at 16:9.
 
 use bevy::pbr::MaterialPlugin;
 use bevy::prelude::*;
@@ -58,12 +22,12 @@ use follow::{follow_moons, follow_stars, follow_sun};
 pub use materials::{CelestialMaterial, StarMaterial};
 use setup::setup_sun;
 
-/// A sun billboard sprite — the disc or its additive lens-flare glare. `SunPart` selects which.
+/// Which sun sprite: the disc or its additive lens-flare glare.
 #[derive(Clone, Copy)]
 enum SunPart {
     /// The `sunCenter.blp` disc (alpha-blended, band-tinted, horizon clip+fade).
     Disc,
-    /// The additive lens flare (`sunGlare.blp`): view-lerped scale 3→20, intensity 0.5→1.
+    /// The additive lens flare (`sunGlare.blp`, `0x6cf490`): view-lerped scale 3→20, alpha 0.5→1.
     Glare,
 }
 
@@ -72,18 +36,15 @@ struct SunSprite {
     part: SunPart,
 }
 
-/// A moon billboard sprite — the white moon's disc, its additive glare ring, or the black moon02
-/// disc. `MoonPart` selects which.
+/// Which moon sprite: the white moon's disc, its additive glare ring, or moon02.
 #[derive(Clone, Copy)]
 enum MoonPart {
     /// The `moon.blp` disc (alpha-blended, band-tinted, horizon clip+fade).
     Disc,
-    /// The additive corona (`moonglare.blp`, a soft warm ring): scale `2.0 ×` the moon size curve,
-    /// intensity view-lerped 0.1→1.
+    /// The additive `moonglare.blp` ring: scale `2.0 ×` the size curve, view-lerped 0.1→1.
     Glare,
-    /// The engine's third disc (`moon02.blp`) — drawn every frame, vertex-BLACK (its colour field
-    /// has no writer in the binary), on its own phase-precessed bearing (az 135–165°). Never a
-    /// visible second moon; it faithfully darkens the stars behind it.
+    /// The third disc (`moon02.blp`), drawn every frame on its own phase-precessed bearing
+    /// (az 135–165°) at colour alpha 0, as its colour has no writer; the weather seed surfaces it.
     Moon02,
 }
 
@@ -92,24 +53,16 @@ struct MoonSprite {
     part: MoonPart,
 }
 
-/// A night-sky **star** mesh — one tag per `Stars.m2` patch (or the procedural fallback). Camera-anchored
-/// over the gradient dome, unlit + alpha-blended; its material's global alpha is driven each frame by the
-/// verified star curve (`WowLighting.star_alpha` — the model-global fade `[stars+0xb]/255`, byte =
-/// `trunc(curve·254+1)`, draw skipped below 2; wow-re celestial-bodies note, decision 0485). The faithful
-/// geometry is the real `Stars.m2` (authored star positions/sizes + UVs into `Stars.blp`/`Stars2.blp`);
-/// [`mesh::star_field_mesh`] is the assetless fallback. Built in [`setup::setup_sun`], anchored + faded in
-/// [`follow::follow_stars`].
+/// One `Stars.m2` patch or the fallback, faded by the star curve's model-global byte `[stars+0xb]`
+/// (`0x6d1b50`).
 #[derive(Component)]
 struct StarDome {
-    /// The patch's **authored transparency weight** — `Stars.m2` keys six static weights (1.0 … 0.25)
-    /// across its seven batches (`transparency_lookup` two-hop, the verified M2 alpha combine
-    /// `A = colorAlpha × weight`), so star groups differ in brightness. Multiplied under the global
-    /// star-curve alpha each frame; `1.0` for the procedural fallback.
+    /// The patch's authored transparency weight (`Stars.m2` keys 1.0 to 0.25 over its seven
+    /// batches, `A = colorAlpha × weight`), under the star-curve alpha; 1.0 for the fallback.
     weight: f32,
 }
 
-/// Sun-sprite subsystem: spawns the disc + glow billboards (+ the two moons + the stars) at startup and pins
-/// them to their bodies each frame (camera-facing, at each body's world direction just inside the far plane).
+/// The celestial layer: spawns the sun, moons and stars at startup and places them each frame.
 pub(crate) struct SunPlugin;
 
 impl Plugin for SunPlugin {
@@ -117,18 +70,13 @@ impl Plugin for SunPlugin {
         app.add_plugins(MaterialPlugin::<CelestialMaterial>::default())
             .add_plugins(MaterialPlugin::<StarMaterial>::default())
             .add_systems(Startup, setup_sun.after(AssetSet::Open))
-            // Post-propagation camera-anchored placement (the BillboardPlace slot): the follows read
-            // the camera's SAME-frame pose and write GlobalTransform directly. In plain Update they
-            // read the last-frame camera — one frame of motion is ~1% of the glare quads' 12-unit
-            // distance, a visible halo swim/size-pump while moving (decision 0504).
+            // After propagation, so the follows place from this frame's camera: a frame of lag is
+            // ~1% of the glare's 12-unit distance, a visible swim.
             .add_systems(
                 PostUpdate,
                 (follow_sun, follow_moons, follow_stars).in_set(crate::billboard::BillboardPlace),
             )
-            // The WMO-skybox + submersion suppression, ordered after both resolves for the same
-            // reason `crate::sky`'s dome gate is: backdrop and atmosphere must agree WITHIN a
-            // frame, or a frame shows the painted sky with our stars still punched through it
-            // (or the murk with the sun still up).
+            // After both resolves, so the skybox, the murk and these bodies agree within a frame.
             .add_systems(
                 Update,
                 apply_celestial_visibility
@@ -138,33 +86,14 @@ impl Plugin for SunPlugin {
     }
 }
 
-/// Hide the sky pass's own elements while a WMO skybox owns the sky ([`crate::skybox`]) — or while
-/// the eye is **submerged**.
-///
-/// `CSky::Render` gates its six draws on **one shared boolean** — `0x6d49cd` sets it, a filled skybox
-/// slot clears it (`0x6d49fb`/`0x6d4a2e`, once a slot's weight exceeds `[0x808aac]` = 0.99), and
-/// `0x6d4a3b test edi,edi; je` then skips **stars, sun disc, white moon, moon02, gradient band and
-/// cloud dome together**. There is no per-element gating, which is why this is one system and not
-/// five. Live-confirmed: standing in King's Square the reference's whole `[0.975, 0.98]` slice is
-/// three `count=12` draws — the skybox cube — and nothing else.
-///
-/// The gate is the slot's **weight**, never the resolve alone: through the body of the 4-second
-/// crossfade (weight ≤ 0.99) the six elements keep drawing and the skybox alpha-blends over them
-/// ([`crate::skybox::SkyboxWeight`]).
-///
-/// The **submerged eye** suppresses the same set one level up: the scene driver's `0x6812a4`
-/// submerged test skips the whole `CSky::Render` call (byte-VERIFIED, wow-re terrain "the liquid
-/// render state" — "the surface is drawn identically from below; what changes underwater is
-/// scene-wide atmosphere only"). Without it the discs keep drawing under the murk, tinted by the
-/// underwater LightParams' celestial band — which is black there, so the sun read as a black ball
-/// from under water (director report, 2026-08-03).
-///
-/// **The GLARES are deliberately exempt.** They are not in this pass: the reference renders them
-/// last, on their own path (`0x483740 → 0x6d48c0 → 0x7e57e0`), which the boolean never reaches — so
-/// a sun flare still blooms over the painted sky. (Whether the glare path carries its own submersion
-/// gate is a wow-re question in flight; until it lands the flare keeps its envelope behaviour.) The
-/// gradient band is [`crate::sky`]'s dome and the cloud dome is [`crate::clouds`]'s; each keeps its
-/// own authority (decision 0025) reading these same resources.
+/// Hide the sky pass's elements while a WMO skybox owns the sky or the eye is submerged.
+/// `CSky::Render` gates stars, sun disc, white moon, moon02, gradient and cloud dome on one
+/// boolean: `0x6d49cd` sets it, a skybox slot whose weight exceeds `[0x808aac]` = 0.99 clears it
+/// (`0x6d49fb`/`0x6d4a2e`), and `0x6d4a3b` then skips all six; through the 4 s crossfade they
+/// draw under the skybox. A submerged eye skips `CSky::Render` whole (`0x6812a4`), or the discs
+/// would draw black under the murk. The glares draw on their own path
+/// (`0x483740 → 0x6d48c0 → 0x7e57e0`), which neither gate reaches, and fade underwater
+/// themselves; the gradient and cloud domes ([`crate::sky`], [`crate::clouds`]) gate themselves.
 #[allow(clippy::type_complexity)]
 fn apply_celestial_visibility(
     skybox: Res<crate::skybox::SkyboxWeight>,
@@ -174,8 +103,7 @@ fn apply_celestial_visibility(
     mut stars: Query<&mut Visibility, (With<StarDome>, Without<SunSprite>, Without<MoonSprite>)>,
 ) {
     let suppressed = skybox.replaces_celestial() || underwater.0.any();
-    // `Inherited`, not `Visible`: these sprites hang off the celestial rig and must keep deferring to
-    // it when the skybox stands down, exactly as the cloud dome's gate does.
+    // Lifting the gate restores the spawn default, `Inherited`, never `Visible`.
     let want = |in_sky_pass: bool| {
         if in_sky_pass && suppressed {
             Visibility::Hidden
diff --git a/crates/benilla-world/src/sun/setup.rs b/crates/benilla-world/src/sun/setup.rs
index 433812e8..9c94b464 100644
--- a/crates/benilla-world/src/sun/setup.rs
+++ b/crates/benilla-world/src/sun/setup.rs
@@ -1,6 +1,4 @@
-//! Startup spawn of the celestial layer — the sun disc + glare, the white moon disc + its additive glare
-//! ring, and the night-sky stars (the real `Stars.m2` patches, or the procedural fallback). One `Startup`
-//! system ([`setup_sun`]); per-frame positioning + tinting live in [`super::follow`].
+//! The celestial layer's startup spawn.
 
 use bevy::asset::RenderAssetUsages;
 use bevy::image::Image;
@@ -26,20 +24,14 @@ pub(super) fn setup_sun(
     mut world_assets: Option<ResMut<WorldAssets>>,
 ) {
     let mesh = meshes.add(quad_mesh());
-    // Every body sprite uses `CelestialMaterial` (celestial.wgsl — the gamma lane, 0161). The DISCS
-    // (sun, white moon, moon02): unlit gamma-correct alpha-blend + the SHARED horizon clip+fade — the
-    // real client routes all three through the same `0x6d1960` (clip to the horizon; the fade store
-    // `clamp(2.5·height, 0, 1)` is CONDITIONAL on the near-horizon band, above which the disc keeps its
-    // colour's own alpha `a_disc`; body skipped entirely below the horizon — decision 0485 + wow-re
-    // Addendum #7). The GLARES: additive in GAMMA — the reference's SRC_ALPHA, ONE byte addition
-    // (`0x7e5a16`), no horizon clip (their lens-flare envelope gates them; decision 0502). Every RGB
-    // tint is the DayNight celestial diffuse band, rewritten per frame by the follow systems —
-    // base_color here is only the frame-0 seed.
+    // Discs take `0x6d1960`'s horizon clip and fade, keeping their colour's alpha `a_disc` above
+    // the band; glares add gamma bytes (`0x7e5a16`) with no clip. The follow systems rewrite every
+    // tint each frame, so `base_color` here is only the first frame's.
     let clip = |base: StandardMaterial, a_disc: f32| CelestialMaterial {
         base,
         extension: CelestialExt {
             fade: Vec4::new(DISC_HORIZON_FADE, 1.0, 0.0, a_disc),
-            span: Vec4::new(1.0, 1.0, 0.0, 0.0), // frame-0 seed (elevated); per-frame: follow
+            span: Vec4::new(1.0, 1.0, 0.0, 0.0), // first frame (elevated); the follows write it
         },
     };
     let glare = |base: StandardMaterial| CelestialMaterial {
@@ -49,8 +41,7 @@ pub(super) fn setup_sun(
             span: Vec4::ZERO,                    // unused in glare mode
         },
     };
-    // Sun disc: the real `sunCenter.blp` (white core → soft yellow edge, feathered alpha), tinted by the
-    // celestial band. Assetless dev falls back to a generated soft disc.
+    // The sun disc, `sunCenter.blp`, or a generated soft disc without assets.
     let sun_tex = world_assets
         .as_mut()
         .and_then(|a| a.sprite_texture("Textures\\sunCenter.blp", &mut images))
@@ -61,16 +52,13 @@ pub(super) fn setup_sun(
             base_color_texture: Some(sun_tex),
             unlit: true,
             cull_mode: None,
-            alpha_mode: AlphaMode::Premultiplied, // gamma-correct blend (celestial.wgsl) — like the reference
-            depth_bias: sky_order::SUN_DISC_BIAS, // second sky draw — over stars, under the moons/clouds
+            alpha_mode: AlphaMode::Premultiplied, // gamma-correct blend (celestial.wgsl)
+            depth_bias: sky_order::SUN_DISC_BIAS, // second sky draw, under the moons and clouds
             ..default()
         },
-        1.0, // colour alpha 0xFF — the per-frame diffuse broadcast (0x6d2914)
+        1.0, // colour alpha 0xFF, the per-frame diffuse broadcast (0x6d2914)
     ));
-    // Sun glare: the real `sunGlare.blp` — a big dark radial glow with authored star rays (dark texels ×
-    // a huge view-lerped quad = the lens flare; the added light stays gentle per pixel). Gamma-additive
-    // (glare mode); the tint (celestial band) and the intensity envelope ride base_color, rewritten per
-    // frame by `follow_sun`. Assetless dev falls back to a generated glow.
+    // The sun glare, `sunGlare.blp`: dark texels on a huge quad keep the added light gentle.
     let glare_tex = world_assets
         .as_mut()
         .and_then(|a| a.sprite_texture("Textures\\sunGlare.blp", &mut images))
@@ -81,7 +69,7 @@ pub(super) fn setup_sun(
         unlit: true,
         cull_mode: None,
         alpha_mode: AlphaMode::Add,
-        depth_bias: sky_order::GLARE_BIAS, // the frame's last render — over clouds and rain
+        depth_bias: sky_order::GLARE_BIAS, // the frame's last render, over clouds and rain
         ..default()
     }));
     commands.spawn((
@@ -100,12 +88,7 @@ pub(super) fn setup_sun(
             part: SunPart::Glare,
         },
     ));
-    // The WHITE MOON — one disc, the real `moon.blp` (neutral grey-white, feathered alpha edge), FULLY
-    // opaque (texture alpha only), tinted per frame by the same celestial band as the sun. The old
-    // hand-built composite (a cyan `Moon02.blp` backing + a 0.55-alpha front disc + a hand-cyan glare)
-    // is dead: it faked the reference's teal rim while the real mechanism is the band tint + the additive
-    // glare ring + the feathered edge over the night sky (decision 0485). Assetless dev falls back to a
-    // generated disc.
+    // The white moon, `moon.blp`, opaque but for its feathered texture alpha.
     let moon_tex = world_assets
         .as_mut()
         .and_then(|a| a.sprite_texture("textures\\moon.blp", &mut images))
@@ -117,10 +100,10 @@ pub(super) fn setup_sun(
             unlit: true,
             cull_mode: None,
             alpha_mode: AlphaMode::Premultiplied,
-            depth_bias: sky_order::WHITE_MOON_BIAS, // third sky draw — over the sun where they cross
+            depth_bias: sky_order::WHITE_MOON_BIAS, // third sky draw, over the sun where they cross
             ..default()
         },
-        1.0, // colour alpha 0xFF — the per-frame diffuse broadcast (0x6d2914)
+        1.0, // colour alpha 0xFF, the per-frame diffuse broadcast (0x6d2914)
     ));
     commands.spawn((
         Mesh3d(mesh.clone()),
@@ -130,30 +113,24 @@ pub(super) fn setup_sun(
             part: MoonPart::Disc,
         },
     ));
-    // MOON02 — the engine's third disc: the real `moon02.blp` (a cyan moon texture) whose colour
-    // dword (`[0xce98a4]`) has NO writer in the binary — RGB *and* alpha stay BSS-zero. The reference
-    // issues its draw every frame, but the quad renders with vertex alpha 0, so the blender paints
-    // NOTHING — the second moon is invisible in clear weather (the old "dark smudge that occludes
-    // stars" reading is superseded; director-verified against the reference; wow-re Addendum #7).
-    // `a_disc = 0.0` gates the whole quad multiplicatively — including the near-horizon fade band,
-    // where our per-fragment lane would otherwise render the reference's soft per-vertex crossing
-    // wedge as a hard black bar (decision 0524). Kept spawned for the future weather seed
-    // (`255·(1−bcc)` dims all three discs under cloud).
+    // moon02, `moon02.blp`: its colour dword (`[0xce98a4]`) has no writer, so above the horizon
+    // band the reference draws it every frame at alpha 0; only the band's ramp and the weather
+    // seed ever show it.
     let moon02_tex = world_assets
         .as_mut()
         .and_then(|a| a.sprite_texture("textures\\moon02.blp", &mut images))
         .unwrap_or_else(|| images.add(radial_sprite(128, 0.7, 0.97)));
     let moon02 = disc_mats.add(clip(
         StandardMaterial {
-            base_color: Color::BLACK, // the unwritten [0xce98a4] — BSS zero, forever
+            base_color: Color::BLACK, // the unwritten [0xce98a4], BSS zero
             base_color_texture: Some(moon02_tex),
             unlit: true,
             cull_mode: None,
             alpha_mode: AlphaMode::Premultiplied,
-            depth_bias: sky_order::MOON02_BIAS, // fourth sky draw — the last disc
+            depth_bias: sky_order::MOON02_BIAS, // fourth sky draw, the last disc
             ..default()
         },
-        0.0, // colour ALPHA is unwritten too — the invisible second moon (Addendum #7)
+        0.0, // its colour's alpha is unwritten too (`0xce98a4`)
     ));
     commands.spawn((
         Mesh3d(mesh.clone()),
@@ -163,11 +140,8 @@ pub(super) fn setup_sun(
             part: MoonPart::Moon02,
         },
     ));
-    // The moon's additive glare — the real `moonglare.blp` ring, co-located with the disc, tinted WARM
-    // by the same celestial band as everything else (the old hand-cyan tint faked the teal rim; the real
-    // rim is the dome's teal night bands through the disc's feathered edge). Gamma-additive (glare
-    // mode); tint × the lens-flare intensity envelope ride base_color, rewritten per frame by
-    // `follow_moons`.
+    // The moon glare, the `moonglare.blp` ring, warm under the same band; the teal rim is the
+    // dome's night bands through the disc's feathered edge.
     let white_glare_tex = world_assets
         .as_mut()
         .and_then(|a| a.sprite_texture("textures\\moonglare.blp", &mut images))
@@ -178,7 +152,7 @@ pub(super) fn setup_sun(
         unlit: true,
         cull_mode: None,
         alpha_mode: AlphaMode::Add,
-        depth_bias: sky_order::GLARE_BIAS, // the frame's last render — over clouds and rain
+        depth_bias: sky_order::GLARE_BIAS, // the frame's last render, over clouds and rain
         ..default()
     }));
     commands.spawn((
@@ -190,11 +164,7 @@ pub(super) fn setup_sun(
         },
     ));
 
-    // Stars — load the **real `Environments\Stars\Stars.m2`** (7 textured patches covering an upper-
-    // hemisphere cap, authored star positions/sizes + UVs into `Stars.blp`/`Stars2.blp` — so the dots map
-    // at their authored scale, unlike a hand-tiled dome). Built as unlit + alpha-blended meshes, normalised
-    // to a unit dome (`follow_stars` scales to the star distance + drives the global alpha). Without `./WoW`
-    // (assetless dev) fall back to the procedural dot field.
+    // The stars: `Stars.m2`'s patches on a unit dome, or the procedural field without assets.
     let star_subs = world_assets
         .as_mut()
         .and_then(|a| {
@@ -202,17 +172,13 @@ pub(super) fn setup_sun(
         })
         .filter(|s| !s.is_empty());
     if let Some(subs) = star_subs {
-        // Normalise by the global max radius → a unit dome (so `follow_stars` can scale it like the others).
         let radius = subs
             .iter()
             .flat_map(|s| s.positions.iter())
             .map(|p| (p[0] * p[0] + p[1] * p[1] + p[2] * p[2]).sqrt())
             .fold(0.0_f32, f32::max)
             .max(1e-3);
-        // One unlit alpha material per PATCH (not per texture): each batch keys its own authored
-        // transparency weight (`Stars.m2` weights 1.0 … 0.25 — dimmer and brighter star groups), which
-        // `follow_stars` multiplies under the star-curve global alpha, so materials can't be shared
-        // across patches with different weights. Base-colour alpha is driven per-frame.
+        // One material per patch, not per texture: each patch has its own transparency weight.
         let tex_white = world_assets
             .as_mut()
             .and_then(|a| a.texture("Environments\\Stars\\Stars.blp", (true, true), &mut images));
@@ -237,15 +203,13 @@ pub(super) fn setup_sun(
                 .as_deref()
                 .is_some_and(|t| t.to_lowercase().contains("stars2"));
             let tex = if is_blue { &tex_blue } else { &tex_white };
-            // The batch's authored static transparency weight — the alpha-combine bake carries any
-            // non-1 constant as a baked loop; sample it at t=0 (Stars.m2 is fully static).
+            // The batch's static transparency weight, baked as a loop; sampled at 0, as `Stars.m2`
+            // is static.
             let weight = sub
                 .alpha_anim
                 .as_ref()
                 .and_then(|a| a.seq(None).weight.as_ref())
                 .map_or(1.0, |w| w.sample(0.0));
-            // `StarMaterial` (star.wgsl) — gamma-correct premultiplied blend so the soft dots blend
-            // into the sky like the reference (our linear-space alpha blend over-brightens them).
             let mat = star_mats.add(StarMaterial {
                 base: StandardMaterial {
                     base_color: Color::srgba(1.0, 1.0, 1.0, 0.0), // alpha driven per-frame
@@ -253,9 +217,7 @@ pub(super) fn setup_sun(
                     unlit: true,
                     cull_mode: None,
                     alpha_mode: AlphaMode::Premultiplied,
-                    // The first sky draw — everything else paints over the stars (the ladder in
-                    // `sky_order`; camera-centred domes all sort at ~0 without a bias, leaving
-                    // the order to submission luck).
+                    // The first sky draw: everything else paints over the stars.
                     depth_bias: sky_order::STARS_BIAS,
                     ..default()
                 },
@@ -269,7 +231,7 @@ pub(super) fn setup_sun(
             ));
         }
     } else {
-        // Assetless fallback: a procedural scattered dot field (same gamma-correct StarMaterial).
+        // Without assets, the procedural dot field.
         let star_dot = images.add(radial_sprite(32, 0.2, 1.0));
         let star_mat = star_mats.add(StarMaterial {
             base: StandardMaterial {
@@ -278,7 +240,7 @@ pub(super) fn setup_sun(
                 unlit: true,
                 cull_mode: None,
                 alpha_mode: AlphaMode::Premultiplied,
-                depth_bias: sky_order::STARS_BIAS, // first sky draw — see the asset lane above
+                depth_bias: sky_order::STARS_BIAS, // first sky draw, as above
                 ..default()
             },
             extension: StarExt {},
diff --git a/crates/benilla-world/src/surface.rs b/crates/benilla-world/src/surface.rs
index 83151dc5..c6579683 100644
--- a/crates/benilla-world/src/surface.rs
+++ b/crates/benilla-world/src/surface.rs
@@ -1,34 +1,17 @@
-//! **What you are standing on** — the `TerrainType` id under a unit's feet, for every consumer of
-//! it (decision 1161).
+//! The `TerrainType` id under a unit's feet, answered in one place. The reference caches it per
+//! unit at `CGUnit+0xc60`, resolved on movement by an environment down-ray (`0x6a8a20`), and four
+//! readers share it: the `$FSD` footstep sound (`0x62341d`), the footprint decal (`0x5fc06e`), the
+//! footstep spray (`0x5fc20f`) and `0x623749`.
 //!
-//! The reference keeps this as one cached dword per unit, `CGUnit+0xc60`: an environment-node
-//! down-ray (`0x6a8a20`) resolves it on movement, and four readers consume that single value — the
-//! `$FSD` footstep sound (`0x62341d`), the footprint decal (`0x5fc06e`), the footstep spray
-//! (`0x5fc20f`) and `0x623749`. They cannot disagree about the ground, and neither can ours: this
-//! module is the one place the question is answered.
+//! A terrain probe (`0x69c320`) races a WMO probe (`0x6a8840`) over the building's collision
+//! faces, and the nearer surface supplies the type; here that race is the [`UnitWmoRoom`] claim.
+//! With a claim, [`surface_terrain_sample`] re-casts over the group's render faces and reads the
+//! hit face's `MOPY.material_id → MOMT+0x20`, a `TerrainType.dbc` id. Without one, the MCNK
+//! dominant layer goes through `GroundEffectTexture` to `TerrainType`. `None` is the reference's
+//! `−1`: silent, no print, and never a retry on the terrain under a claimed floor.
 //!
-//! **Two legs, arbitrated by nearest hit.** The client races a terrain probe (`0x69c320`) against a
-//! WMO probe (`0x6a8840`) over the building's COLLISION faces; whichever surface is nearer under
-//! the foot supplies the type. That arbitration is already ours — it is the same faces-only,
-//! terrain-raced down-ray that publishes [`UnitWmoRoom`], so a room claim *is* "the building won
-//! this column".
-//!
-//! - **WMO leg.** The claim names a group; [`surface_terrain_sample`] re-casts the column over that
-//!   group's RENDER faces and reads the hit face's `MOPY.material_id → MOMT+0x20` — a
-//!   `TerrainType.dbc` id carried by the surface itself, with no `GroundEffectTexture` hop.
-//! - **ADT leg.** No claim: the MCNK dominant layer → `GroundEffectTexture` → `TerrainType`, the
-//!   chain that was already here.
-//!
-//! `None` is the client's `−1` sentinel and means **silent, and no print** — not "try the other
-//! leg". A building that won the column but whose group has no render face under the probe is
-//! silent; falling back to the ground beneath the floor is exactly the bug this module exists to
-//! kill (B236's sequel: snow crunching inside the Kharanos inn, and snow prints on its floorboards,
-//! because the ADT leg answered indoors).
-//!
-//! **Known gap — exterior groups.** Both the claim and the render-face set are built for INTERIOR
-//! groups only, so a WMO surface authored on an *exterior* group (bridges and docks, `Wood`) still
-//! falls to the ADT leg. Wrong in the same direction as before this module, never newly wrong; the
-//! fix is widening the claim, not special-casing here.
+//! The claim covers interior groups only, so a surface on an exterior group (bridges and docks,
+//! `Wood`) still takes the terrain leg, unlike the reference; the fix belongs in the claim.
 
 use bevy::prelude::*;
 
@@ -43,9 +26,8 @@ use crate::wmo_portal::{
     indoors_at, surface_terrain_sample, UnitWmoRoom, WmoPortalInstance, POSITION_PROBE_LIFT,
 };
 
-/// The world state the surface question needs, as one `SystemParam` — the placements it rays, the
-/// terrain it races them against. Threaded as a query rather than read into a resource for the
-/// same reason `liquid::RoomPlacements` is: the answer must not outlive the placement.
+/// The placements and terrain the surface question rays, read live so no answer outlives its
+/// placement.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct SurfaceUnderfoot<'w, 's> {
     wmos: Res<'w, Assets<WmoModel>>,
@@ -55,8 +37,8 @@ pub(crate) struct SurfaceUnderfoot<'w, 's> {
 }
 
 impl SurfaceUnderfoot<'_, '_> {
-    /// The `TerrainType` id under `pos` (Bevy space) for a unit holding `room`, or `None` for the
-    /// client's `−1` — silent, no print. See the module docs for why `None` never retries.
+    /// The `TerrainType` id under `pos` (Bevy space) for a unit holding `room`; `None` is the
+    /// reference's `−1`.
     pub(crate) fn terrain_type(
         &self,
         cat: &FootstepCatalog,
@@ -67,9 +49,8 @@ impl SurfaceUnderfoot<'_, '_> {
             Some(room) => {
                 let inst = self.instances.get(room.instance).ok()?;
                 let model = self.wmos.get(&inst.handle)?;
-                // The SAME origin lift the claim's own ray used: feet rest on the floor plane, and
-                // a coplanar `z <= probe.z` test must not lose the floor to a rounding hair. Using
-                // a different origin here could resolve a different face than the one that won.
+                // The claim ray's own origin lift: a coplanar `z <= probe.z` test must not lose
+                // the floor, and another origin could hit a different face than the one that won.
                 let probe_world = pos + Vec3::Y * POSITION_PROBE_LIFT;
                 let local = inst
                     .world_from_local
@@ -82,22 +63,20 @@ impl SurfaceUnderfoot<'_, '_> {
         }
     }
 
-    /// The MCNK `areaId` under `pos` (Bevy space) — the *outdoor* leg of "where is this", with no
-    /// WMO-interior claim. The player's own area is [`crate::terrain_stream::CurrentArea`], which
-    /// includes that claim; this is what every other body gets.
+    /// The MCNK `areaId` under `pos` (Bevy space), without the WMO claim that the player's own
+    /// [`crate::terrain_stream::CurrentArea`] includes.
     pub fn area_id_under(&self, pos: Vec3) -> Option<u32> {
         area_id_under(&self.streamer, &self.adt_tiles, pos)
     }
 
-    /// The terrain height under `pos` (Bevy space), from the MCNK heightfield — `None` off the
-    /// streamed set. **Not** the physics trimesh: the two are allowed to differ, which is why
-    /// tracing a body through the world is a separate question (1164 item 11).
+    /// The MCNK heightfield's height under `pos` (Bevy space), `None` off the streamed set; not
+    /// the physics trimesh, which may differ.
     pub fn terrain_height_under(&self, pos: Vec3) -> Option<f32> {
         terrain_height_under(&self.streamer, &self.adt_tiles, pos)
     }
 
-    /// Is `feet_world` inside a building? The faces-only down-ray, raced against the terrain —
-    /// standing on the grass above a mine's tunnels is not standing in the mine.
+    /// Whether `feet_world` is inside a building: the faces-only down-ray raced against the
+    /// terrain, so the grass above a mine's tunnels is outdoors.
     pub fn indoors_at(&self, feet_world: Vec3) -> bool {
         indoors_at(
             &self.wmos,
diff --git a/crates/benilla-world/src/terrain_stream.rs b/crates/benilla-world/src/terrain_stream.rs
index e507f16b..32822b4a 100644
--- a/crates/benilla-world/src/terrain_stream.rs
+++ b/crates/benilla-world/src/terrain_stream.rs
@@ -1,18 +1,6 @@
-//! The terrain streamer — the world's sole terrain owner, built on `benilla-assets`.
-//!
-//! It **streams** the ground around the player through the standard `AssetServer` (the `mpq://` source +
-//! `AdtLoader`): it loads a `Handle<AdtTile>` for every tile in range and drops it when the tile leaves
-//! range — so residency, async loading, the decode cache, and refcounted unloading are all the engine's
-//! job now, not a bespoke worker/finalize pipeline. Per loaded tile it spawns: the merged terrain mesh +
-//! splat [`TerrainMaterial`]; an avian static terrain collider (a trimesh from the same merged mesh,
-//! riding the tile entity's lifecycle); the doodad/WMO placements (from `Handle<M2Model>`/`Handle<WmoModel>`,
-//! deduped by the `AssetServer`, each with its own static collider entity, with the same
-//! [`WowModelMaterial`] + [`DoodadFade`] components the legacy path used — so the existing
-//! visibility/fade/lighting systems govern them unchanged); the MCLQ water surfaces; and the ground
-//! clutter (scattered per chunk into `ClutterChunk`s the shared `stream_chunk_clutter` builds lazily).
-//! It also publishes loading-screen residency. Current-map directory + id come from
-//! [`CurrentMap`]/[`MapCatalogRes`] ([`crate::world_map`]); the clutter catalog + build lifecycle from
-//! [`crate::clutter::ClutterPlugin`].
+//! The terrain streamer, the world's one terrain owner: it loads every ADT tile in range through
+//! the `AssetServer`, spawns its cells, collider, placements, MCLQ water and ground clutter, and
+//! publishes the residency the loading screen reads.
 
 use std::collections::HashMap;
 use std::time::{Duration, Instant};
@@ -54,13 +42,9 @@ use spawn::prop_light::WmoDoodadInst;
 use spawn::spawn_loaded_placements;
 use weld::{flush_hull_welds, HullWelds};
 pub use window::StreamWindow;
-// The WMO prop-light machinery lives spawn-side (0830's named carve, executed in 0832); the two
-// outside consumers — `crate::interior` and `crate::entities`' `wmo_props` — keep their
-// `terrain_stream::X` paths, same as the `queries` items below.
+// The WMO prop-light items, for the interior classifier and the app's WMO props.
 pub use spawn::prop_light::{fold_interior_probe, hex_word, interior_light_up, PropLobeLight};
-// The shared placed-model assembler + the off-thread collider build — also the WMO-gameobject
-// doodad-prop path's spawner (`crate::entities`' `wmo_props`: the ship's sails ride the streamed
-// gameobject entity, and its cargo hulls ride the boat's kinematic body).
+// The placed-model assembler and off-thread collider build, shared with WMO gameobject props.
 pub use collider::{build_collider_task, placement_collider_data, PendingCollider};
 pub use spawn::{
     carried_light_claims, m2_anim_bound, m2_fade, point_light, spawn_model_entities,
@@ -73,131 +57,87 @@ pub use queries::{
     terrain_height_under_cached, AreaAuthoritySet, CurrentArea, ShadeResolve,
 };
 
-/// Wall-clock spent per frame spawning streamed-in geometry (terrain tiles in [`stream_terrain`],
-/// doodad/WMO placements in [`spawn_loaded_placements`]) before deferring the rest to the next frame.
-/// Building a static collider is a synchronous parry trimesh/QBVH build; without this cap a cold-start
-/// load spawns the whole ring at once and blocks the main thread (window beachball) for seconds. ~4 ms
-/// keeps each frame responsive while still streaming the world in quickly.
+/// Wall-clock per frame for spawning streamed tiles and placements before the rest waits a frame;
+/// uncapped, a cold start spawns the whole ring at once and blocks the main thread for seconds.
 const SPAWN_BUDGET: Duration = Duration::from_millis(4);
 
-/// The new streamer's residency state: which tiles are loaded and the entity each was spawned as.
-/// `pub(crate)` (fields private): the sound subsystem resolves ground lookups through
-/// [`ground_effect_under`] against the resident tiles.
+/// The streamer's residency state: the loaded tiles and the entity each spawned as.
 #[derive(Resource, Default)]
 pub struct TerrainStreamer {
-    /// Loaded tiles by `(tile_x, tile_y)`. The [`Handle<AdtTile>`] keeps the asset resident; dropping
-    /// it (on unload / map swap) lets the `AssetServer` release the tile and its sub-assets.
+    /// Loaded tiles by `(tile_x, tile_y)`; each handle keeps its asset resident.
     tiles: HashMap<(i32, i32), TileState>,
-    /// The map directory the loaded tiles are for (e.g. `"Azeroth"`); a change means a cross-map
-    /// teleport, so every tile is dropped and re-streamed for the new map.
+    /// The map directory the tiles are for; a change drops every tile.
     map_dir: Option<String>,
-    /// The focus tile [`stream_terrain`] last streamed around — the furnisher's nearest-first
-    /// ordering key, published here so it never recomputes the focus ladder a second time.
+    /// The focus tile last streamed around, the furnisher's nearest-first key.
     focus: (i32, i32),
-    /// The window's `(inner, outer)` half-widths as of last frame, so the reach is logged once
-    /// per change (the Terrain Distance slider) rather than per frame.
+    /// The window's `(inner, outer)` half-widths last frame, logged once per change.
     reach: Option<(i32, i32)>,
-    /// The current map's WDT tile index (decision 0476), requested with the map: ADT requests wait
-    /// for it and consult its `MAIN` grid — open ocean authors no tiles to ask for.
+    /// The map's WDT tile index: ADT requests wait for it and consult its `MAIN` grid.
     wdt: Option<Handle<WdtIndex>>,
-    /// The WDT failed to load (unheard of for a shipped map): stream ungated like pre-0476 rather
-    /// than showing no world. Reset on map change.
+    /// The WDT failed to load: stream every tile ungated rather than show no world.
     wdt_ungated: bool,
-    /// `true` once this map's global WMO has been registered as a placement (decision 0688) — on a
-    /// WMO-only map that one building is the whole world, so there is nothing else to stream.
-    /// Cleared on map change, which also releases the placement.
+    /// This WMO-only map's one building is registered as a placement.
     global_wmo: bool,
-    /// [`ViewFocus::paced`] as of last frame — so the residency latch can re-arm on the EDGE into
-    /// a load rather than on the level. A viewer with no avatar publishes `paced: false` forever
-    /// (`ViewFocus::camera`), and re-arming on the level would leave that viewer walking its focus
-    /// neighbourhood's every placement every frame for the rest of the run — the settled-work scan
-    /// the latch exists to stop.
+    /// [`ViewFocus::paced`] last frame: the residency latch re-arms on the edge into a load, since
+    /// a viewer with no avatar is unpaced forever and the level would re-arm it every frame.
     was_paced: bool,
-    /// The last frame found nothing to request, drop or spawn and every resident tile stood
-    /// furnished — so a frame with the same window, the same pacing and a complete load has
-    /// nothing to do and skips the window walk (three window-sized allocations and a scan of
-    /// every resident tile, on every still frame — decision 1979's floor).
+    /// Last frame had nothing to request, drop or spawn and every tile stood furnished, so an
+    /// unchanged frame skips the walk.
     settled: bool,
-    /// The focus tile the off-grid tripwire below last reported, so a focus parked outside the
-    /// map's WDT grid says so **once** rather than every frame. `None` while the focus is on the
-    /// grid (so re-entering the state re-reports).
+    /// The off-grid focus tile last warned about, so the warning fires once per tile.
     off_grid_reported: Option<(i32, i32)>,
 }
 
-/// The placement id the map-global WMO is registered under. A WMO-only map authors **no** ADT tiles
-/// at all, so it contributes no MODF/MDDF uniqueIds this could collide with — and the value is the
-/// one the file itself carries in the dead `uniqueId` slot (the reference overwrites it from its own
-/// counter at `0xc9a320`, having no more use for it than we do).
+/// The map-global WMO's placement id: a WMO-only map has no ADT uniqueIds to collide with, and
+/// this is the file's own dead `uniqueId` (the reference overwrites it from a counter, `0xc9a320`).
 const GLOBAL_WMO_UID: u32 = u32::MAX;
 
 impl TerrainStreamer {
-    /// Residency counts for the debug panel's World readout: `(spawned, requested)` — tiles fully
-    /// up (root + cells furnished) vs. every tile in the stream window (up + loading/furnishing).
+    /// `(spawned, requested)` tiles for the debug panel: furnished, and all in the window.
     pub fn residency(&self) -> (usize, usize) {
         let spawned = self.tiles.values().filter(|t| t.furnished).count();
         (spawned, self.tiles.len())
     }
 }
 
-/// One loaded tile: the resident asset handle, the terrain entity, and the placement ids it references.
+/// One loaded tile and everything it owns.
 struct TileState {
     handle: Handle<AdtTile>,
-    /// `None` until the `AdtTile` finishes loading and the terrain root entity is spawned (which is also
-    /// when this tile's placements are registered).
+    /// The terrain root, spawned once the `AdtTile` loads, when its placements register too.
     entity: Option<Entity>,
-    /// The tile's terrain material, made at root spawn and shared by every cell the furnisher hangs
-    /// off the root (one material per tile — the loader's arrays make that possible).
+    /// The tile's one terrain material, shared by every cell.
     material: Option<Handle<TerrainMaterial>>,
-    /// The furnishing cursor: the next `AdtTile::chunks` index whose cell [`furnish::furnish_tile_cells`]
-    /// should build. Cells land a few per frame while live (decision 0832) — the mesh-asset creation
-    /// IS the pacing point; everything downstream (extract, prepare, upload) follows its rate.
+    /// The index of the next cell (4×4 chunks) to furnish; cells land a few per frame while live.
     next_cell: usize,
-    /// `true` once every cell is up (or cells are ablated off): the "this tile is really resident"
-    /// bit the loading-screen accounting reads, so a reveal never shows a root with bare ground.
+    /// Every cell is up: the residency bit the loading screen counts.
     furnished: bool,
-    /// uniqueIds of the doodad/WMO placements this tile references — registered once the tile's `AdtTile`
-    /// loads, refcount-released when the tile unloads.
+    /// The uniqueIds of the placements this tile references, released when it unloads.
     placements: Vec<u32>,
-    /// The tile's water-surface entities (tile-exclusive, like the terrain mesh — despawned on unload).
     liquid: Vec<Entity>,
-    /// The tile's impassable-chunk wall collider, if it authors any (decision 1266). Its own static
-    /// body rather than a child of the root, matching the per-WMO walk/camera bakes: two colliders
-    /// with different audiences are two bodies, not a nested one.
+    /// The impassable-chunk wall collider, a body of its own since its audience differs.
     wall: Option<Entity>,
-    /// The tile's per-chunk `ClutterChunk` entities (tile-exclusive; their lazily-built clutter meshes
-    /// are children, so despawning these cascades to them).
+    /// The per-chunk `ClutterChunk`s, whose meshes are children and despawn with them.
     clutter: Vec<Entity>,
-    /// The welded map-doodad hull colliders this tile owns (decision 1369): batches of the hulls
-    /// whose placements registered here first, despawned with the tile like [`Self::wall`].
+    /// The welded doodad hull colliders of the placements that registered here first.
     welds: Vec<Entity>,
-    /// The merged static-render blobs this tile owns (decision 1417, `WOW_STATIC_MERGE`):
-    /// per-(cell × material) bakes of the doodads whose placements registered here first,
-    /// despawned with the tile exactly like [`Self::welds`].
+    /// Those placements' merged static-render blobs, per cell and material (`WOW_STATIC_MERGE`).
     merged: Vec<Entity>,
 }
 
-/// Doodad/WMO placements spawned **once** and shared across the tiles that reference them — the client's
-/// own cross-tile dedup (a building straddling N tiles is spawned once and refcounted). The model assets
-/// are loaded by `Handle`, so the `AssetServer` dedups the *decode*; this dedups the *instance*.
+/// Doodad and WMO placements, spawned once and refcounted across the tiles that list them.
 #[derive(Resource, Default)]
 pub(crate) struct Placements {
-    /// By MDDF/MODF uniqueId: the placement + how many loaded tiles reference it.
+    /// By MDDF/MODF uniqueId.
     by_id: HashMap<u32, Placement>,
-    /// Material dedup, so submeshes sharing a (texture, blend, sidedness, kind, fade-variant) share one
-    /// `WowModelMaterial` handle — what lets Bevy batch them (mirrors the old `model_material` cache).
+    /// The material dedup, so submeshes sharing a look share one handle and batch.
     materials: MaterialCache,
-    /// Registered-but-unspawned work — placements awaiting their model plus WMO props awaiting
-    /// their own M2s. Zero means the spawner's full [`Self::by_id`] walk has nothing to find, so
-    /// it returns without paying it (a resident city is thousands of placements, all spawned, in
-    /// steady state). Kept by the register/handoff/release sites here; the spawner itself settles
-    /// it as models land (and adds a WMO's props the moment they resolve).
+    /// Placements awaiting their model plus WMO props awaiting their M2s; at zero the spawner skips
+    /// its [`Self::by_id`] walk. Every register, handoff, release and spawn site keeps it.
     pending_spawns: usize,
 }
 
 impl Placements {
-    /// Every entity some registered placement owns — the set a despawn walks. The duplicate
-    /// census (`world_census`) subtracts it from the live `WorldObject` population: a placed
-    /// part alive outside this set outlived its registration, which is what a doubled prop is.
+    /// Every entity a registered placement owns; a placed part outside it is a doubled prop.
     pub(crate) fn owned(&self) -> std::collections::HashSet<Entity> {
         self.by_id
             .values()
@@ -206,99 +146,60 @@ impl Placements {
     }
 }
 
-/// A shared placement: its resident model handle, world transform, and spawned submesh entities. Doodad
-/// vs WMO is read off the [`ModelHandle`] variant, so it isn't stored separately.
+/// A shared placement: its model, transform and spawned entities.
 struct Placement {
     model: ModelHandle,
     transform: Transform,
-    /// Spawned submesh entities — empty until the model asset finishes loading (`spawned` then `true`).
-    /// WMO doodad-prop submeshes ([`Placement::doodads`]) are appended here too, so they despawn together.
+    /// Spawned submesh entities, WMO prop submeshes included so they despawn together.
     entities: Vec<Entity>,
-    /// `true` once we've spawned (or determined there's nothing to spawn) — so we don't retry.
+    /// Spawned, or found to have nothing to spawn.
     spawned: bool,
-    /// MODF doodad-set index (WMOs only; 0 for M2 doodads) — which extra prop set to show beyond set 0.
+    /// The MODF doodad set shown beside set 0 (WMOs only).
     doodad_set: u16,
-    /// MODF name-set index (WMOs only) — the placement's `WMOAreaTable.NameSetID` audio variant.
+    /// The MODF name set (WMOs only): the placement's `WMOAreaTable.NameSetID`.
     name_set: u16,
-    /// WMO doodad props (candle stands, banners) resolved once the WMO root loads — each its own M2,
-    /// spawned across frames as its asset arrives. Empty for M2-doodad placements.
+    /// WMO doodad props, resolved when the root loads and spawned as each M2 arrives.
     doodads: Vec<WmoDoodadInst>,
-    /// The placement's [`crate::wmo_portal::WmoPortalInstance`] entity, spawned with the building's
-    /// groups. Held so the props — which spawn later, as their own M2 assets land — can be tagged
-    /// with the same instance and cull alongside the group that owns them.
+    /// The building's portal instance, held so later props cull with the group that owns them.
     portal_instance: Option<Entity>,
     /// How many loaded tiles reference this placement; despawned when it hits zero.
     refs: u32,
-    /// The first tile to register this placement — loaded at that moment by construction. For an
-    /// M2 doodad this is its hull weld's owner tile (decision 1369; the lifetime argument is in
-    /// `weld`'s module doc). WMO placements never read it: their prop hulls weld per placement.
+    /// The tile owning an M2 doodad's hull weld and merged blobs, first the registering tile;
+    /// WMOs never read it.
     owner: (i32, i32),
 }
 
-/// How much of the world the streamer wants around the view focus is actually there. Written each
-/// frame by [`stream_terrain`] (tiles + placements) and [`finish_colliders`] (the attach queue).
-///
-/// It lived in `loading_screen` — the engine publishing its own residency fact to the wrong side
-/// of 1160's line (1163's finding). Two readers, and only one of them is a screen: the loading
-/// bar reads it to draw itself, and the **player's post-snap hold** reads it to decide when to let
-/// go (decision 0737 — the physics hold keys on this signal, never on ground contact). Both are
-/// the game asking the world what it has; neither is the world asking the game anything.
+/// How much of the world wanted around the view focus is there, read by the loading bar and by
+/// the post-snap physics hold, which keys on this and never on ground contact.
 #[derive(Resource, Default)]
 pub struct WorldLoadProgress {
-    /// Units done, of [`Self::total`]: desired tiles spawned + focus-neighbourhood placements up.
+    /// Units done of [`Self::total`]: desired tiles furnished, focus-neighbourhood placements up.
     pub ready: usize,
     pub total: usize,
-    /// Whether the tile under the view focus (the nearest desired tile) is spawned. `false` until the
-    /// streamer first runs, and again whenever a teleport/worldport drops the focus onto unloaded
-    /// ground — the backstop trigger (covers startup, cross-map worldport, AND far same-map
-    /// teleports like a cross-continent `.tele`, which don't change `CurrentMap`). During normal
-    /// streaming the focus tile is always resident, so it never fires spuriously.
+    /// The tile under the view focus is furnished; false at startup and whenever a teleport lands
+    /// on unloaded ground, same map or not, which is the loading screen's backstop trigger.
     pub focus_resident: bool,
-    /// The scene term (0737): the focus tile **and its 8 neighbours** are spawned with every
-    /// placement they reference (WMOs, doodads, WMO props) — "the buildings and trees around you
-    /// exist", which is what makes a reveal read as a world rather than bare terrain. Collider
-    /// quiet is deliberately *not* folded in here (it is published a stage apart); consumers use
-    /// [`Self::presentable`].
+    /// The focus tile and its 8 neighbours are up with every placement they reference; consumers
+    /// read [`Self::presentable`], which adds the backlogs.
     pub scene_ready: bool,
-    /// Outstanding collider attaches (decision 0610's queue) — published by `finish_colliders`.
+    /// Outstanding collider attaches, from `finish_colliders`.
     pub colliders_pending: usize,
-    /// Unflushed static-merge accumulators (1418, `WOW_STATIC_MERGE`) — published by
-    /// `flush_static_merge`. Merged world geometry that has not yet baked is a hole the reveal
-    /// must not show; same conservative semantics as the weld backlog inside
-    /// [`Self::colliders_pending`]. Always `0` with the lever off.
+    /// Unflushed static-merge accumulators (`WOW_STATIC_MERGE`), holes the reveal must not show.
     pub merge_pending: usize,
-    /// Focus-neighbourhood placements not yet spawned (the wait instrument's term).
+    /// Focus-neighbourhood placements not yet spawned.
     pub placements_pending: usize,
-    /// Retained-pass regions collected but not yet drawable (`StaticGx::undrawn_regions`) —
-    /// geometry that has *spawned* and still draws nothing.
-    ///
-    /// Since slice 2 (1429/1430) a WMO's group geometry leaves the entity path for the retained
-    /// pass, so "the placement spawned" stopped meaning "the building is on screen": between the
-    /// divert and its first bake the region is a hole. The reveal used to be gated on the spawn
-    /// alone and therefore lifted up to `IDLE_FRAMES` before the buildings could draw — a city of
-    /// bare ground for a quarter second. Same conservative semantics as the collider and merge
-    /// backlogs beside it.
+    /// Retained-pass regions spawned but not yet drawable (`StaticGx::undrawn_regions`).
     pub gx_pending: usize,
-    /// **Which tile these facts are about** — the focus tile the streamer computed this frame.
-    /// `None` until the streamer first runs (and again after `release_world`). The settle release
-    /// compares it against the tile under the avatar's own feet and refuses the resident release on
-    /// a mismatch (decision 1336): residency published for one tile must never unfreeze a body
-    /// standing on another — the fail-closed guard that makes any future focus/snap ordering
-    /// regression cost a logged 6 s timeout instead of a silent fall through the world.
+    /// The focus tile these facts are about. The settle release refuses on a mismatch with the
+    /// avatar's own tile, so residency for one tile never unfreezes a body on another.
     pub focus_tile: Option<(i32, i32)>,
-    /// Latched by the publisher once its own terms first read fully ready ([`Self::scene_ready`]
-    /// and [`Self::is_ready`]): the focus neighbourhood's per-placement walk is skipped from
-    /// then on — the counts stay at their converged values — until the focus lands on
-    /// unfurnished ground again (a worldport's map swap, a far teleport), which re-arms the full
-    /// accounting. [`Self::focus_tile`] and [`Self::focus_resident`] stay live every frame
-    /// regardless: the loading screen's backstop and the settle release key on them.
+    /// Latched once the load reads fully ready, freezing the counts until a new load re-arms it;
+    /// [`Self::focus_tile`] and [`Self::focus_resident`] stay live every frame regardless.
     pub complete: bool,
 }
 
 impl WorldLoadProgress {
-    /// 0..1 residency fraction for the bar — **0.0 when nothing is wanted yet** (the cold-start /
-    /// pre-`desired` frame), so the bar starts empty rather than flashing full. (Distinct from the
-    /// clear test [`Self::is_ready`], which treats `total == 0` as not-ready.)
+    /// The bar's 0..1 fraction, 0 while nothing is wanted yet so the bar starts empty.
     pub fn fraction(&self) -> f32 {
         if self.total == 0 {
             0.0
@@ -307,14 +208,13 @@ impl WorldLoadProgress {
         }
     }
 
-    /// True once every wanted unit is resident. Requires `total > 0` so the cold-start / post-swap
-    /// frame (before `desired` is computed) doesn't read as "done".
+    /// Every wanted unit is resident; `total == 0` is a frame before the window, never done.
     pub fn is_ready(&self) -> bool {
         self.total > 0 && self.ready >= self.total
     }
 
-    /// The world at the focus is presentable — the scene term plus a quiet collider queue. What
-    /// both consumers (the screen clear here, the settle release in the streamer) key on.
+    /// The scene term with no collider, merge or retained-pass backlog: what the loading cover and
+    /// the settle release key on.
     pub fn presentable(&self) -> bool {
         self.scene_ready
             && self.colliders_pending == 0
@@ -323,40 +223,30 @@ impl WorldLoadProgress {
     }
 }
 
-/// **Where the world should stream from** — the engine's one required input besides
-/// [`crate::world_map::CurrentMap`], written by whatever owns a viewer and read by every
-/// streaming lane (terrain, the WDL ring, the area authority, the form furnisher).
-///
-/// The streamer used to read `player::Player` directly, which is 1160's wire (a): the engine
-/// asking the game where the avatar is. Inverted, the question becomes the game's to answer, and
-/// a second program with no avatar at all (`benilla-worldview`) answers it from its free-fly
-/// camera without stubbing a player.
-///
-/// The ladder it encodes, unchanged (`0x695650`-era behaviour, decision 0772): a live attached
-/// avatar wins; with no avatar, the picked character's entry row; else the camera; else the spawn
-/// point. A **detached** eye (free-fly) skips straight to the camera — but keeps publishing the
-/// body's position, because the zone authority follows the character and not the camera.
+/// Where the world streams from, written by whatever owns a viewer and read by every streaming
+/// lane. The ladder: a live attached avatar, else the picked character's entry row, else the
+/// camera, else [`SPAWN_XY`]. A detached eye streams from the camera but keeps the body, which the
+/// zone authority follows.
 #[derive(Resource, Default, Clone, Copy)]
 pub struct ViewFocus {
-    /// The avatar's world position (wow coords) when one is live — present even while detached.
+    /// The avatar's position in wow coords when one is live, even while detached.
     body: Option<[f32; 3]>,
-    /// Is the eye following the body? `false` in free-fly, where the stream follows the camera.
+    /// The eye follows the body; false in free-fly.
     attached: bool,
-    /// The picked character's map + position, for the entry window before an avatar exists.
+    /// The picked character's map and position, before an avatar exists.
     entry: Option<(u32, [f32; 3])>,
-    /// Is the focus **settled** — steady enough to pace spawning behind the per-frame caps?
-    /// `false` through entry, a teleport and a world swap, when the loading cover is absorbing the
-    /// burst and a cap would only lengthen the reveal.
+    /// The focus is settled, so spawning is paced; false through entry, a teleport and a world
+    /// swap, while the loading cover absorbs the burst.
     pub(crate) paced: bool,
 }
 
 impl ViewFocus {
-    /// No viewer at all — follow the camera, or the spawn point if there is not even one.
+    /// No viewer: follow the camera, or the spawn point without one.
     pub fn camera() -> Self {
         Self::default()
     }
 
-    /// A live avatar at `wow`, with the eye on it. `paced` is the settled bit.
+    /// A live avatar at `wow` with the eye on it; `paced` is the settled bit.
     pub fn body(wow: [f32; 3], paced: bool) -> Self {
         Self {
             body: Some(wow),
@@ -366,19 +256,13 @@ impl ViewFocus {
         }
     }
 
-    /// **Is the stream following the body's own ground?** True only for an attached live avatar.
-    ///
-    /// The question anyone asking "is the world under the *player* loaded?" actually means. While
-    /// the eye is detached — free-fly, a cinematic fly-by — residency describes wherever the
-    /// camera went, so a consumer that reads it as a fact about the body is reading someone else's
-    /// tile. `release_post_snap_hold` already learned that the hard way (decision 1336) and tests
-    /// the tile itself; this is the cheap form for a consumer that only needs the yes/no.
+    /// The stream follows the body's own ground, so residency is a fact about the player; a
+    /// detached eye streams wherever the camera went.
     pub fn follows_body(&self) -> bool {
         self.attached && self.body.is_some()
     }
 
-    /// A live avatar whose eye has been **detached** (free-fly): the stream follows the camera,
-    /// the zone authority still follows the body.
+    /// A live avatar with the eye detached: the stream follows the camera, the zone the body.
     pub fn detached(wow: [f32; 3], paced: bool) -> Self {
         Self {
             attached: false,
@@ -386,8 +270,7 @@ impl ViewFocus {
         }
     }
 
-    /// No avatar yet — the picked character's own map and position, so world entry streams the
-    /// destination rather than wherever the camera was parked.
+    /// No avatar yet: stream the picked character's map and position, not the parked camera's.
     pub fn entry(map: u32, wow: [f32; 3]) -> Self {
         Self {
             entry: Some((map, wow)),
@@ -411,10 +294,8 @@ impl ViewFocus {
         }
     }
 
-    /// Which map the streamers should be loading — `current` once the server has said, and the
-    /// picked character's own map for the entry window before that. It **must** agree with
-    /// [`Self::resolve`]: a position from one map against the tile grid of another names tiles
-    /// that exist but are somewhere else entirely.
+    /// The map to stream: the picked character's before an avatar exists, else `current`. It must
+    /// agree with [`Self::resolve`], or a position names tiles on another map's grid.
     pub(crate) fn map(&self, current: Option<u32>) -> u32 {
         if self.body.is_none() {
             if let Some((map, _)) = self.entry {
@@ -424,77 +305,49 @@ impl ViewFocus {
         current.unwrap_or(0)
     }
 
-    /// The **body's** own position when there is one — what the zone/area authority measures from,
-    /// which is the character and never the free-fly camera.
+    /// The body's position, which the area authority measures from, never the camera's.
     pub(crate) fn body_pos(&self) -> Option<[f32; 3]> {
         self.body
     }
 
-    /// Is there a body **and** is the world under it the one it is standing in?
-    ///
-    /// The area authority's gate (1287) — the same bit [`ViewFocus::paced`] carries, read through
-    /// its own name because it answers a different question here. Through entry, a teleport and a
-    /// world swap the body has been snapped but its destination is still streaming, so the leaf
-    /// area under it is whatever tile happens to be resident: at first login that is the pre-snap
-    /// position's — the map centre, Eastern Plaguelands on map 0 and The Barrens on map 1 — and a
-    /// beat later the outdoor parent of an interior whose WMO claim has not landed yet. Publishing
-    /// those makes the client announce, play the music of, and join the channels of zones the
-    /// player was never in.
+    /// A body stands in a settled world: the area authority's gate. Through entry, a teleport and
+    /// a world swap the area under the body is a stale tile's, and publishing it would announce,
+    /// play and join the channels of zones the player was never in.
     pub(crate) fn body_settled(&self) -> bool {
         self.body.is_some() && self.paced
     }
 }
 
-/// **Where the world streams from when nothing else can say** — the Human start (Northshire),
-/// where `one`/`One` logs in, so a viewer sits in the middle of the loaded block rather than at
-/// Stormwind's edge.
-///
-/// The last rung of [`ViewFocus`]'s ladder, and the reason it lives here rather than at the crate
-/// root: it is the *streamer's* fallback, and an engine that cannot answer "where do I stream
-/// from" with no game attached is not an engine. It was a `lib.rs` const, which made it invisible
-/// to both walls — neither could see a crate-root item at all until the scan learned to.
+/// The stream focus when nothing else can say: the Human start in Northshire.
 pub const SPAWN_XY: (f32, f32) = (-8949.95, -132.49);
 
-/// A placement's model asset handle — an M2 doodad or a WMO building. Keeps the asset resident.
+/// A placement's model handle, which keeps the asset resident.
 enum ModelHandle {
     M2(Handle<M2Model>),
     Wmo(Handle<WmoModel>),
 }
 
-/// The terrain streamer plugin (added by `main` as the world's terrain owner).
-/// **Per-frame streamer activity** — what this streamer did this frame, bumped by the
-/// `WorldStage::Stream` chain as it works (a handful of integer adds + five self-timers,
-/// maintained unconditionally and zeroed by whoever reads them).
-///
-/// Exists because B181's symptom — a frame spike on every ADT tile-boundary crossing — is keyed to
-/// *what the streamer did that frame*, which no 1 Hz journal row can attribute: the spike frame
-/// needs its own row saying what was dropped, requested and spawned beside what the frame cost.
-/// `perf`'s stream trace is that reader, and it used to own this resource too, which meant the
-/// engine's own streaming account only existed if an instrument was installed (decision 1164 —
-/// the same mis-filing as `terrain_stream` writing its residency into `loading_screen`). The
-/// writer owns it now; the instrument reads it.
+/// What the streamer did this frame, bumped by the `WorldStage::Stream` chain and zeroed by its
+/// reader, so a frame spike can be read against what was dropped, requested and spawned.
 #[derive(Resource, Default)]
 pub struct StreamActivity {
-    /// Tiles whose owned entities (terrain root + cells, liquid, clutter) were despawned.
+    /// Tiles whose owned entities were despawned.
     pub tiles_dropped: u32,
-    /// Shared placements whose refcount hit zero (their entities despawned with them).
+    /// Shared placements whose refcount hit zero.
     pub placements_dropped: u32,
-    /// Entity handles despawned with those placements (submeshes, colliders, lights, props).
+    /// Entities despawned with those placements.
     pub placement_entities_dropped: u32,
-    /// New ADT asset requests fired.
     pub tiles_requested: u32,
-    /// Loaded tiles spawned (root + collider kicked off + placements registered + liquid + clutter).
     pub tiles_spawned: u32,
-    /// MCNK cell meshes built + spawned by the paced furnisher (decision 0832).
+    /// Terrain cells (4×4 MCNK chunks each) spawned by the furnisher.
     pub cells_spawned: u32,
-    /// Model submesh render forms built by the paced model furnisher (decision 0834).
+    /// Model submesh forms built by the model furnisher.
     pub model_meshes_built: u32,
     /// Placements (or WMO props) whose model landed and spawned.
     pub placements_spawned: u32,
-    /// Off-thread colliders attached.
     pub colliders_attached: u32,
-    /// Self-time of `stream_terrain` / `furnish_tile_cells` / `furnish_model_forms` /
-    /// `spawn_loaded_placements` / `finish_colliders` (ms).
+    /// Self-times in ms, in order: `stream_terrain`, `furnish_tile_cells`, `furnish_model_forms`,
+    /// `spawn_loaded_placements`, `finish_colliders`.
     pub stream_ms: f32,
     pub furnish_ms: f32,
     pub mfurnish_ms: f32,
@@ -503,8 +356,7 @@ pub struct StreamActivity {
 }
 
 impl StreamActivity {
-    /// Did the streamer *do* anything this frame? (The self-timers don't count: the desired-set
-    /// scan runs every frame and would make every row an "event".)
+    /// The streamer did something this frame; the self-timers, which run every frame, do not count.
     pub fn any_event(&self) -> bool {
         self.tiles_dropped
             + self.placements_dropped
@@ -522,10 +374,7 @@ pub(crate) struct TerrainPlugin;
 
 impl Plugin for TerrainPlugin {
     fn build(&self, app: &mut App) {
-        // The engine's own input resources, defaulted HERE so a second program that
-        // registers no game at all still boots: with no writer, `ViewFocus::camera()` is the
-        // free-fly answer and the streamer follows the camera (this is what `benilla-worldview`
-        // does, and why the spike needed a stub `Player` before this inversion).
+        // Defaulted here, so a program with no game boots and streams around the camera.
         app.init_resource::<ViewFocus>()
             .init_resource::<WorldLoadProgress>()
             .init_resource::<TerrainStreamer>()
@@ -535,15 +384,9 @@ impl Plugin for TerrainPlugin {
             .init_resource::<StaticMerge>()
             .init_resource::<crate::model_forms::ModelForms>()
             .init_resource::<CurrentArea>()
-            // **The streaming chain lives in `WorldStage::Stream`** — the load-bearing half of the
-            // frame ordering contract (schedule.rs): the teleport snap (Input) → the streamer
-            // recomputes focus + publishes residency HERE → the loading screen covers (Present),
-            // all in one frame, so a swap never renders uncovered. The legacy streamer carried
-            // this membership and the cutover to this one silently dropped it — the executor was
-            // then free to run the streamer *before* the snap, and the cover landed a frame late
-            // on exactly the burst frame (the `.tele` destination flash; decision 0738).
-            // `finish_colliders` heads the chain so the collider-queue depth the settle release
-            // and the Present-stage clear read is this frame's, not last frame's.
+            // In `WorldStage::Stream`, between the teleport snap (Input) and the loading cover
+            // (Present), so a swap never renders uncovered. `finish_colliders` heads the chain so
+            // the collider queue read downstream is this frame's.
             .add_systems(
                 Update,
                 (
@@ -557,59 +400,42 @@ impl Plugin for TerrainPlugin {
                 )
                     .chain()
                     .in_set(WorldStage::Stream)
-                    // **No world until a character is in one** (decision 0777). The whole chain,
-                    // not just the request side: with nothing streamed there is nothing to spawn,
-                    // no collider to finish and no WMO volume to mirror, and gating the head alone
-                    // would leave three systems walking empty queries to prove it every frame.
+                    // No world, and no chain, until a character is in one.
                     .run_if(crate::schedule::world_is_live),
             )
-            // The blob-visibility dump (`WOW_BLOB_VIS=1`) — a dev instrument, registered only
-            // when asked for; see `merge::log_blob_vis`.
+            // `WOW_BLOB_VIS=1`: the blob-visibility dump.
             .add_systems(
                 Update,
                 merge::log_blob_vis
                     .run_if(merge::blob_vis_enabled)
                     .run_if(crate::schedule::world_is_live),
             )
-            // The model-forms furnisher (decision 0834) runs UNGATED, unlike the chain above: the
-            // glue screens' character preview requests forms pre-world (`update_display_models`
-            // serves the glue stage too), and a world-live gate would starve it forever. Ordered
-            // before the placement spawner so a form completed this frame can land this frame;
-            // everything it does is demand-driven, so with no requests it is a no-op.
+            // Ungated: the glue screens' character preview requests forms before any world. Before
+            // the spawner, so a form finished this frame lands this frame.
             .add_systems(
                 Update,
                 crate::model_forms::furnish_model_forms
                     .in_set(WorldStage::Stream)
                     .before(spawn_loaded_placements),
             )
-            // Leaving the world releases it. Without this, a `/logout` back to character select
-            // would leave the whole streamed world resident and unowned — the gate above stops it
-            // being *maintained*, which is precisely what makes an abandoned world immortal.
+            // Leaving the world releases it; the gate above only stops it being maintained.
             .add_systems(
                 Update,
                 release_world
                     .run_if(crate::schedule::world_left)
-                    // Between the wire drain and the stream stage, so the release happens on the
-                    // frame the world went away — the promptness `OnExit` used to give it. The
-                    // session's publisher runs before `Net`, so this reads THIS frame's edge.
+                    // On the frame the world went away: the session publishes its edge before
+                    // `Net`, and the release lands before the stream stage.
                     .after(crate::schedule::WorldStage::Net)
                     .before(crate::schedule::WorldStage::Stream),
             )
-            // Within-map art residency (decision 0793): the placement material dedup expires by
-            // distance, so a long flight on one continent stops ratcheting. Ungated by
-            // `world_is_live` on purpose — a cache still holding the last world's art is exactly
-            // what should be draining while you sit at character select.
+            // Ungated, so the last world's art drains at character select too.
             .add_systems(Update, scope_placement_art)
-            // The WorldDetail re-scatter runs UNGATED: out of world the tile map is empty (a
-            // no-op walk) and the density tracker must never miss a boot-time config apply.
+            // Ungated, so the density tracker never misses a boot-time config apply.
             .add_systems(Update, rescatter_clutter)
             .add_systems(
                 Update,
-                // After the interior claim so the leaf override reads THIS frame's claim —
-                // the client resolves leaf + indoor + names from ONE node state in one pass
-                // (`0x67e510`); a stale-leaf/fresh-claim frame let the abbey login big-splash
-                // (the A ≠ subzone gate saw "Northshire Valley" against the abbey's name).
-                // `AreaAuthoritySet` lets the zone-text feed order after this in turn.
+                // After the interior claim: the reference resolves leaf, indoor and names from one
+                // node state in one pass (`0x67e510`).
                 update_current_area
                     .after(crate::wmo_portal::WmoPvsSet)
                     .in_set(AreaAuthoritySet),
@@ -617,11 +443,8 @@ impl Plugin for TerrainPlugin {
     }
 }
 
-/// Stream `AdtTile`s around the view focus: drop tiles that left range (releasing their placements),
-/// request newly-in-range tiles, and — as each finishes loading — spawn its terrain mesh + material and
-/// register its doodad/WMO placements. The desired square is gated on the map's WDT `MAIN` grid
-/// (decision 0476): a tile the map doesn't author is never requested — no NotFound error spam on
-/// open-ocean crossings, and the loading screen's ready/total counts only tiles that can exist.
+/// Stream `AdtTile`s around the view focus: drop tiles out of range, request the tiles in range
+/// that the WDT `MAIN` grid authors, spawn each as it loads, and publish residency.
 #[allow(clippy::type_complexity)] // the bundled asset_stores tuple
 fn stream_terrain(
     mut commands: Commands,
@@ -629,8 +452,7 @@ fn stream_terrain(
     placements: ResMut<Placements>,
     asset_server: Res<AssetServer>,
     tiles: Res<Assets<AdtTile>>,
-    // Bundled into one tuple param to stay within Bevy's 16-element system-param limit; destructured
-    // to the same bindings below.
+    // One tuple, under Bevy's 16-param system limit.
     asset_stores: (
         ResMut<Assets<TerrainMaterial>>,
         ResMut<Assets<Mesh>>,
@@ -650,22 +472,18 @@ fn stream_terrain(
     camera: Query<&Transform, With<WorldCamera>>,
     shared_light: Option<Res<SharedLightBuffer>>,
     cfg: Option<Res<RenderConfig>>,
-    // "Where are we, and how far do we look" — the server's map, the catalog that names its
-    // directory, and the live view distance the residency window derives from (1513). Bundled
-    // for the same param-limit reason as `asset_stores`.
+    // The server's map, the catalog naming its directory, and the view distance the window uses.
     location: (
         Option<Res<CurrentMap>>,
         Option<Res<MapCatalogRes>>,
         Res<crate::view::ViewDistance>,
     ),
     mut load_progress: Option<ResMut<WorldLoadProgress>>,
-    // Bundled for the same 16-param reason as `asset_stores`: the two stream-batch accumulators
-    // the map-change drop must clear.
+    // The stream-batch accumulators the map-change drop must clear.
     batchers: (
         ResMut<HullWelds>,
         ResMut<StaticMerge>,
-        // `None` only under `WOW_STATIC_GX=0` (the collector exists whenever the retained
-        // pass is armed — the default since 1434).
+        // `None` only under `WOW_STATIC_GX=0`.
         Option<ResMut<crate::static_gx::StaticGx>>,
     ),
 ) {
@@ -691,13 +509,8 @@ fn stream_terrain(
         return;
     };
 
-    // Cross-map teleport: the map directory changed → drop every loaded tile (despawn + release the
-    // handles + placements) so the new map streams in fresh, and request the new map's WDT (the
-    // tile-existence index every ADT request below consults).
+    // A new map directory: drop every tile and request the new map's WDT.
     if state.map_dir.as_deref() != Some(dir.as_str()) {
-        // Say which map's tiles we are about to spend the IO budget on, and how many we are
-        // throwing away to do it. Silent before, which is exactly why nobody noticed that every
-        // world entry began by streaming Northshire regardless of where the character was.
         info!(
             "terrain: streaming map {dir} (was {:?}, {} tiles released)",
             state.map_dir,
@@ -716,8 +529,7 @@ fn stream_terrain(
         state.wdt = Some(asset_server.load(format!("mpq://World/Maps/{dir}/{dir}.wdt")));
         state.wdt_ungated = false;
     }
-    // The WDT gate (0476). A missing/failed WDT (unheard of for a shipped map) falls back to the
-    // old ungated probing, warned once per map — a broken index must never mean "no world".
+    // A failed WDT falls back to ungated probing, warned once per map, never to no world.
     let wdt_index = state.wdt.as_ref().and_then(|h| wdts.get(h));
     if wdt_index.is_none() && !state.wdt_ungated {
         if let Some(h) = &state.wdt {
@@ -731,12 +543,9 @@ fn stream_terrain(
         }
     }
 
-    // A WMO-only map (decision 0688): the WDT says this map authors no terrain and its entire world
-    // is one building. Register it exactly like any ADT-placed WMO — same `Placement`, same
-    // spawn/collider/doodad/portal path — because that is what the reference does: its WDT branch
-    // hands the global MODF entry to the SAME consumer (`0x695650`) an ADT's MCRF walk does. It is
-    // registered once for the map and released on the map change above; nothing streams it in or
-    // out, since there is no "range" for a building that is the map.
+    // A WMO-only map is one building, registered like any ADT WMO, as the reference's WDT branch
+    // hands its global MODF entry to the MCRF walk's consumer (`0x695650`). Registered once per
+    // map, released on map change.
     if let Some(g) = wdt_index.and_then(|w| w.global_wmo()) {
         if !state.global_wmo {
             info!(
@@ -759,23 +568,13 @@ fn stream_terrain(
         }
     }
 
-    // Stream around the *view focus* — see [`ViewFocus`] for the ladder — as far as the view
-    // distance reaches: the residency window is the reference's own, derived from the live
-    // `farclip` in chunk units (`window`, decision 1513). The slider that moves the far-clip
-    // wall moves this with it.
+    // The residency window is the reference's, from the live `farclip` in chunk units.
     let center = focus.resolve(camera.single().ok().map(|c| c.translation));
     let window = StreamWindow::at(view.farclip, center[0], center[1]);
-    let tiling = cfg.as_ref().map(|c| c.tex_tiles).unwrap_or(8.0);
     let (cx, cy) = window.focus_tile();
     let same_window = state.focus == (cx, cy) && state.reach == Some((window.inner, window.outer));
-    // Never while a load is in flight: `paced` is false from a snap until the body settles, and
-    // the tail this skip bypasses is where the load is RELEASED — the retained pass's undrawn
-    // count that `presentable()` reads, the burst-over `flush_now`, and the settle hold. A
-    // skip that engaged the frame `complete` flipped, with the pass still baking the new
-    // cells, froze that count above zero and held the loading screen up for good — the
-    // .tele hang of 2026-09-04, the day after this skip landed (1982). So the skip needs a
-    // paced, presentable, complete world, and even then keeps the undrawn count fresh so a
-    // later rebake un-skips it.
+    // Skip an unchanged frame only in a paced, complete, presentable world, since the tail it
+    // bypasses releases a load; even then the undrawn count stays fresh, so a rebake un-skips it.
     if same_window
         && state.settled
         && focus.paced
@@ -791,8 +590,6 @@ fn stream_terrain(
         return;
     }
     state.focus = (cx, cy);
-    // One line per change of reach — the slider moved, or the first frame — so a run log says
-    // what the residency window was when a tile count or a frame cost was read off it.
     if state.reach != Some((window.inner, window.outer)) {
         state.reach = Some((window.inner, window.outer));
         info!(
@@ -804,29 +601,16 @@ fn stream_terrain(
         );
     }
 
-    // Desired set: every tile the outer window touches, clamped to the 64×64 tile grid — and
-    // filtered to tiles the WDT says exist (open ocean authors none; the reference's own
-    // `MAIN` bit-0 test at `0x69863c`). The filter also fixes the loading screen's accounting:
-    // `ready == total` is reachable on a coast, and any fallback-era entry for a nonexistent
-    // tile turns stale and unloads below.
+    // Every tile the outer window touches on the 64×64 grid, less those the WDT's `MAIN` bit 0
+    // says do not exist, as the reference tests (`0x69863c`).
     let mut desired = window.wanted_tiles();
     if let Some(w) = wdt_index {
         desired.retain(|&(tx, ty)| w.has_tile(tx as u32, ty as u32));
     }
 
-    // **The focus is off this map's tile grid** — the window touches no tile the WDT authors, so
-    // there is nothing to stream and nothing to wait for. On an ADT map that is never a place a
-    // body can legitimately stand: it means the focus was written in some *other* map's
-    // coordinates (the 2026-09-05 report — a rider composed through a cross-map transport whose
-    // own pose was still the source continent's) or has left the world entirely.
-    //
-    // It earns a tripwire because of what it does DOWNSTREAM and silently: `desired` empty makes
-    // `total == 0`, which [`WorldLoadProgress::is_ready`] reads as *not ready* — so the loading
-    // screen can never clear — while the vacuous arm below reports `focus_resident = true`, so the
-    // backstop that would have re-raised a cover cannot fire either. The player is left staring at
-    // a loading screen whose wait line reads `0/0 resident` with every other term nominal. Naming
-    // the map and the tile turns that into one greppable line. Once per focus tile, never a frame
-    // loop; `global_wmo` maps legitimately author no tiles and are excluded.
+    // A focus off the map's tile grid, usually one written in another map's coordinates, wants no
+    // tile, so `total == 0` and the loading cover can never clear. Warned once per focus tile;
+    // WMO-only maps author no tiles and are exempt.
     if wdt_index.is_some() && !state.global_wmo && desired.is_empty() {
         let focus_tile = window.focus_tile();
         if state.off_grid_reported != Some(focus_tile) {
@@ -844,33 +628,11 @@ fn stream_terrain(
         state.off_grid_reported = None;
     }
 
-    // Unload tiles no longer desired: despawn the terrain entity, release the placements, drop the
-    // handle. **Budgeted per frame** (B181): dropping the whole trailing row on the crossing frame
-    // freed ~1300 mesh assets — each tile's 256 chunk cells, CPU copies included — plus the tiles'
-    // decoded chunks and their placements' models, all in one frame. Measured (`WOW_STREAM_TRACE`,
-    // Emerald Dream flat-map pin): that free wave is the 2–3-dropped-interval spike on every ADT
-    // boundary crossing, while this chain's own systems — request, spawn, collider attach, each
-    // already budgeted — stayed under 3 ms. So the drop lane gets the same treatment: at most
-    // `unload_budget` tiles release per frame, farthest from the focus first. The un-drained
-    // remainder just stays resident a few frames longer — behind the direction of travel, and a
-    // re-cross inside the drain window finds its tile still loaded (no re-decode, no re-spawn).
-    // A cross-map swap is NOT budgeted (`drop_streamed_world` above): the loading screen covers
-    // it, and holding a dead map's tiles through a fresh map's IO burst helps nothing.
-    // **The keep-band** (B181): a tile is wanted inside the outer window but released only past
-    // it plus one chunk (`StreamWindow::keeps`) — hysteresis. Without it, a body pacing across
-    // the one chunk line that toggles a far tile cycles that tile per step: the reporter's own
-    // minimal repro (`.go` half a yard across, and back) re-decoded and re-spawned five tiles
-    // each way under the old tile-centred window, and the row's landing — not the streamer's
-    // own budgeted systems — is the frame spike (a fresh Undercity row lands ~3900 placements
-    // and ~1300 mesh assets). A band tile stays fully resident, so a re-cross finds it and
-    // streams NOTHING; the band's dedup entries need no art-sweep accommodation (0793's
-    // `radius_floor` is about art the streamer will re-fetch — a band tile is already spawned
-    // and never re-consults the caches). The reference releases by window membership alone
-    // (`0x6984f0`) — its reload is a cheap async read; ours is the spawn wave above.
-    //
-    // Ablation switch (`WOW_NO_TILE_DROP=1`): never release stale tiles — a crossing becomes a
-    // pure asset-ADD event and a re-cross a pure no-op, separating the load lane from the free
-    // lane when measuring a streaming cost. Residency grows for the life of the run; dev-only.
+    // Unload stale tiles, at most `unload_budget` per frame and farthest first, since a whole
+    // row's free wave is a frame spike; a cross-map swap is not budgeted, as the cover hides it.
+    // Deviation: a tile is released only one chunk past the outer window (`StreamWindow::keeps`),
+    // where the reference releases by window membership (`0x6984f0`), because our reload is a
+    // re-decode and re-spawn, not a cheap async read.
     let unload_budget = cfg.as_ref().map(|c| c.unload_budget).unwrap_or(1);
     let mut stale: Vec<(i32, i32)> = if tile_drop_disabled() {
         Vec::new()
@@ -902,25 +664,16 @@ fn stream_terrain(
                 &t.placements,
                 merge::merge_enabled(),
             );
-            // The B1 retained cells (1429): a diverted batch has no entity and no blob, so the
-            // dead owner's items leave here or never — the cells re-bake without them.
+            // A retained-pass batch has no entity or blob, so its owner's items leave here or
+            // never; the cells re-bake without them.
             if let Some(gx) = staticgx.as_deref_mut() {
                 gx.release_owner(c);
             }
         }
     }
 
-    // Request newly-desired tiles (the `AssetServer` dedups, so re-requesting a loaded one is
-    // free) — only once the WDT has answered (or failed into the ungated fallback): a request
-    // fired before the index lands could probe a tile that doesn't exist.
-    //
-    // **Staggered while live** (B181): a whole fresh row requested in one frame decodes in
-    // parallel and LANDS near-together — ~1300 mesh assets plus the texture arrays hitting the
-    // render world's prepare in one or two frames, a wave no app-side budget downstream of the
-    // request can spread. One fresh request per frame, nearest first, staggers the landings for
-    // the only cost of the window edge (~2 tiles out, in fog) filling over a few frames. World
-    // entry and teleports stay unstaggered: the loading screen exists to absorb that burst, and
-    // the settle release waits on exactly these tiles.
+    // Request new tiles once the WDT has answered. While paced, one per frame and nearest first,
+    // so a fresh row's landings stagger; entry and teleports request all at once under the cover.
     let mut fresh_empty = true;
     if wdt_index.is_some() || state.wdt_ungated {
         let live = focus.paced;
@@ -956,18 +709,15 @@ fn stream_terrain(
         }
     }
 
-    // Spawn any loaded-but-unspawned tile with the production terrain material, and register its
-    // placements. The material references the ONE shared global-light buffer (updated in place each
-    // frame), so a freshly-streamed tile is correctly lit + fogged on its first frame. Budgeted per
-    // frame (a tile's terrain collider is a big trimesh/QBVH build): on cold start the whole ring
-    // finishes loading near-together, and spawning every tile in one frame stalls the main thread.
+    // Spawn loaded tiles within the frame's budget. The material binds the shared light buffer,
+    // so a new tile is lit and fogged on its first frame.
     let tile_deadline = Instant::now() + SPAWN_BUDGET;
     for (&(tx, ty), tile) in state.tiles.iter_mut() {
         if tile.entity.is_some() {
             continue;
         }
         let Some(adt) = tiles.get(&tile.handle) else {
-            continue; // not loaded yet (or missing) — try again next frame
+            continue; // not loaded yet, or missing
         };
         let material = materials.add(ExtendedMaterial {
             base: terrain_base_material(),
@@ -975,7 +725,7 @@ fn stream_terrain(
                 layer_array: adt.layer_array.clone(),
                 alpha_array: adt.alpha_array.clone(),
                 shadow_array: adt.shadow_array.clone(),
-                params: Vec4::new(tiling, 0.0, 0.0, 0.0),
+                params: Vec4::new(benilla_formats::TERRAIN_LAYER_TILES, 0.0, 0.0, 0.0),
                 light_buf: shared_light.0.clone(),
                 // MONKEY (outdoor torch shadows: terrain): cloned per tile like the light buffer -
                 // a handle + a `Buffer` (an Arc), so the per-tile cost is two refcount bumps and
@@ -985,35 +735,18 @@ fn stream_terrain(
                 torch_buf: torch.table.clone(),
             },
         });
-        // Terrain collider (decision 0009): ONE static trimesh per tile, welded from the same decoded
-        // chunks the drawn cells are built from (so you stand on the visible ground), built off-thread
-        // (attached by `finish_colliders`) so a tile streaming in never hitches the frame. It rides the
-        // tile root's lifecycle — gone when the tile despawns, no separate bookkeeping.
+        // One static trimesh per tile from the drawn chunks, built off-thread, riding the root.
         let collider_data = terrain_collider_data(&adt.chunks);
-        // …and, separately, the tile's impassable-chunk fences (decision 1266, report B129). A
-        // SECOND collider because the audience is the point: the reference's fence is emitted only
-        // into the movement box gather, and its segment/ray path never reads the flag at all. So —
-        // the walk layer, where the body sees it and the camera boom does not, and unmarked, so it
-        // neither takes the selection ring nor clamps the mouse pick. An authored wall is not scenery.
+        // The impassable-chunk fences are a second collider, on the walk layer only: the reference
+        // emits them into the movement box gather alone, never its segment and ray path.
         let wall_data = impassable_wall_data(&adt.chunks);
-        // The tile ROOT draws nothing: it carries the collider and the surface roles, and its MCNK
-        // cells hang off it as children — one drawn object per 33.333 yd chunk. That is the unit the
-        // exterior-scene cull needs (decision 0780; a 533 yd slab the camera stands on intersects
-        // every portal window, so it could never be hidden), and it also gives Bevy's own frustum cull
-        // something smaller than half a kilometre to reject. Despawning the root takes the cells.
-        //
-        // The cells themselves do NOT spawn here (decision 0832): a whole row of tiles finishes
-        // decoding in one frame, and spawning ~1300 loader-built cell meshes at once handed the
-        // render world their entire extract/prepare/upload as one 80–105 ms (process-CPU) frame —
-        // the B181 first-contact spike. `furnish_tile_cells` (chained right after this system)
-        // builds them from `AdtTile::chunks` + `shading` a few per frame while live.
-        // Chain-only visibility (`crate::vis_chain`): the tile root renders nothing itself —
-        // its cell meshes are the drawn children, and they need the inheritance chain intact.
+        // The root draws nothing: it carries the collider and surface roles, and its cells of
+        // 4×4 chunks are children, a unit small enough for the exterior and frustum culls.
+        // `furnish_tile_cells` spawns them a few per frame; the root keeps the visibility chain.
         let mut tile_ent = commands.spawn((Transform::IDENTITY, Visibility::default()));
         tile_ent.vis_chain_only();
         if let Some((verts, tris)) = collider_data {
-            // `GroundDecalSurface`: terrain receives the selection ring (see `crate::collision`).
-            // `PickOccluder`: terrain clamps the mouse pick (the reference's world trace).
+            // Terrain takes the selection ring and clamps the pick (the reference's world trace).
             tile_ent.insert((
                 PendingCollider::new(build_collider_task(verts, tris), None, true),
                 GroundDecalSurface,
@@ -1033,10 +766,8 @@ fn stream_terrain(
         tile.material = Some(material);
         activity.tiles_spawned += 1;
 
-        // Register this tile's doodad/WMO placements (deduped + refcounted by uniqueId across tiles).
-        // The MCSH ground-shade is NOT sampled here: a doodad straddles several tiles and this one may
-        // not contain its origin, so the shade is resolved at spawn via a global lookup (see
-        // `doodad_ground_shade` / `spawn_loaded_placements`) — the reference's own per-frame model.
+        // Placements register by uniqueId; their ground shade resolves at spawn by a global lookup,
+        // since a doodad's origin may lie on another tile.
         for d in &adt.doodads {
             register_doodad(placements, &asset_server, d, (tx, ty));
             tile.placements.push(d.unique_id);
@@ -1046,7 +777,6 @@ fn stream_terrain(
             tile.placements.push(w.unique_id);
         }
 
-        // Spawn this tile's water surfaces (tile-exclusive — despawned with the tile, like its mesh).
         let mut liquid_ents = Vec::new();
         spawn_liquids(
             &mut commands,
@@ -1057,10 +787,7 @@ fn stream_terrain(
         );
         tile.liquid = liquid_ents;
 
-        // Scatter this tile's ground clutter into per-chunk `ClutterChunk` units (tile-owned; the
-        // shared `stream_chunk_clutter` builds + tears down their meshes lazily within the ~70 yd
-        // detail-doodad horizon, same as for the old streamer's chunks). Needs the app-side
-        // ground-effect catalog + density; absent before they're set up, so skipped until then.
+        // Ground clutter per chunk, meshed lazily within ~70 yd by `stream_chunk_clutter`.
         if let (Some(clutter), Some(clutter_cfg)) = (clutter.as_ref(), clutter_cfg.as_ref()) {
             let mut clutter_ents = Vec::new();
             scatter_tile_clutter(
@@ -1075,21 +802,13 @@ fn stream_terrain(
             tile.clutter = clutter_ents;
         }
 
-        // One tile spawned; if that used up the frame's budget, leave the rest for next frame (the
-        // `tile.entity.is_some()` guard above makes this re-entrant). The loading bar reflects the
-        // partial residency below, so it animates rather than jumping to full after a stall.
+        // Past the budget the rest waits a frame; the `entity` guard above makes this re-entrant.
         if Instant::now() >= tile_deadline {
             break;
         }
     }
 
-    // Publish residency for the loading screen: how many desired tiles are actually spawned,
-    // whether the tile under the view focus is up (the backstop trigger), and the scene term
-    // (decision 0737) — the focus tile + its 8 neighbours with every placement they reference, so
-    // "ready to reveal" means the buildings and trees around you exist, not just bare terrain. A
-    // focus tile that doesn't exist (map edge) counts as resident so we never get stuck waiting
-    // for ground that isn't there.
-    // The pacing edge, read and advanced once per frame (see [`TerrainStreamer::was_paced`]).
+    // Publish residency; the pacing edge is read and advanced once per frame.
     state.settled = stale_empty
         && fresh_empty
         && state
@@ -1099,74 +818,49 @@ fn stream_terrain(
     let was_paced = std::mem::replace(&mut state.was_paced, focus.paced);
     if let Some(p) = load_progress.as_mut() {
         p.focus_tile = Some((cx, cy));
-        // Resident = the focus tile is furnished — judged from the DESIRED set, not from the
-        // presence of a `state.tiles` entry: a desired tile whose request hasn't landed yet is
-        // absent from the map, and "no entry" must read as *not there*, never as "nothing to wait
-        // for". The vacuous arm is only for ground the WDT never authors (map edge, open ocean,
-        // a WMO-only map) — waiting there would hang forever on terrain that cannot exist.
+        // Judged from the desired set, so a desired tile not yet requested is not there; ground
+        // the WDT never authors counts as resident, or the wait would never end.
         p.focus_resident = if desired.contains(&(cx, cy)) {
             state.tiles.get(&(cx, cy)).is_some_and(|t| t.furnished)
         } else {
             true
         };
-        // Until the WDT answers we don't yet know what this map is made of, so nothing under the
-        // focus can be called resident. Without this the post-worldport frames before the index
-        // lands read as "ground is up" — harmless on an ADT map (the tile entries below close the
-        // gap a frame later) but on a WMO-only map, where `desired` is empty forever, it is the
-        // difference between a loading screen and a glimpse of the void.
+        // Nothing is resident before the WDT answers, or a WMO-only map would show the void.
         if wdt_index.is_none() && !state.wdt_ungated {
             p.focus_resident = false;
         }
-        // A WMO-only map's focus residency IS its one building's spawn (0688) — there is no
-        // tile to gate on. The bar/scene accounting for it lives in the gated block below.
+        // A WMO-only map's focus residency is its one building's spawn.
         if state.global_wmo {
             p.focus_resident &= placements
                 .by_id
                 .get(&GLOBAL_WMO_UID)
                 .is_some_and(|p| p.spawned);
         }
-        // `focus_tile`/`focus_resident` above stay live every frame — the loading screen's
-        // backstop and the settle release key on them. The counting below is only consumed
-        // while a load is underway, so once it has reported fully ready it latches off
-        // (`complete`) instead of walking the focus neighbourhood's every placement per frame
-        // forever. A focus on unfurnished ground IS a new load beginning (a worldport's map
-        // swap, a far teleport), so it re-arms the latch; `release_world`'s reset covers the
-        // logout → re-entry path.
+        // The counting below latches off once fully ready (`complete`); a focus on unfurnished
+        // ground is a new load and re-arms it.
         if !p.focus_resident {
             p.complete = false;
         }
-        // A **snap** re-arms it too, even onto ground that is already resident. `paced` is false
-        // exactly through entry, a teleport and a world swap (the game writes it from the settle
-        // hold), and a near teleport — `.tele` across a city, a summon — lands on furnished ground
-        // whose *buildings* may still be arriving. Without this the latch answers a fresh
-        // destination with the departure's converged numbers: `scene_ready` reads true because it
-        // was true where we left, and both consumers (the cover, the settle release) are told a
-        // world is presentable that nobody has looked at yet.
-        //
-        // On the EDGE into the load, not on the level — see [`TerrainStreamer::was_paced`].
+        // So does a snap onto furnished ground, whose buildings may still be arriving; on the edge
+        // into the load, not the level.
         if was_paced && !focus.paced {
             p.complete = false;
         }
         if !p.complete {
-            // "Spawned" means FURNISHED (root + every cell): the furnisher is uncapped while the
-            // cover is up, so this costs entry nothing — but it keeps a reveal from ever showing a
-            // root whose ground is still landing (`furnished` lags root spawn by one frame here,
-            // since the furnisher runs after this system in the same chain).
+            // Spawned means furnished, root and every cell, so a reveal never shows bare ground;
+            // it lags the root by a frame, as the furnisher runs after this system.
             let spawned = |c: &(i32, i32)| state.tiles.get(c).is_some_and(|t| t.furnished);
             p.total = desired.len();
             p.ready = desired.iter().filter(|c| spawned(c)).count();
-            // The focus neighbourhood's placements join the accounting (bar + scene term). A
-            // placement is *up* once its own model spawned AND its WMO props (each an M2 arriving
-            // on its own schedule) have — the furniture the reveal would otherwise pop in.
-            // Placements of tiles not yet spawned aren't known yet; the missing tile itself holds
-            // `scene_ready` down.
+            // The focus neighbourhood's placements count too, each up once its model and its WMO
+            // props have spawned; a tile not yet up holds `scene_ready` down itself.
             let mut near_pending = 0usize;
             let mut near_tile_missing = false;
             for dx in -1..=1i32 {
                 for dy in -1..=1i32 {
                     let c = (cx + dx, cy + dy);
                     if !desired.contains(&c) {
-                        continue; // off-grid or WDT says no tile — nothing to wait for
+                        continue; // no tile to wait for
                     }
                     match state.tiles.get(&c) {
                         Some(t) if t.furnished => {
@@ -1184,13 +878,9 @@ fn stream_terrain(
                 }
             }
             p.placements_pending = near_pending;
-            // `focus_resident` already folds the WDT gate and the global WMO's spawn, so both
-            // ride into the scene term through it.
+            // `focus_resident` already folds in the WDT gate and the global WMO's spawn.
             p.scene_ready = p.focus_resident && !near_tile_missing && near_pending == 0;
-            // A WMO-only map's bar and clear-condition ride the placement (0688). Counting it
-            // keeps `total > 0`, which is what `is_ready` requires before it will clear the
-            // screen at all; the scene term also waits for its props (the Stockade's 740
-            // candles are the reveal).
+            // A WMO-only map counts its one placement, props included, which keeps `total > 0`.
             if state.global_wmo {
                 let full = placements
                     .by_id
@@ -1202,17 +892,12 @@ fn stream_terrain(
             }
             p.complete = p.scene_ready && p.is_ready();
         }
-        // The retained pass's own residency (1429's lane): geometry that has spawned and cannot
-        // draw yet is a hole in the reveal exactly like an unattached collider is a hole in the
-        // floor. Published every frame — one map walk, no per-item work — because both consumers
-        // read `presentable()` and neither can see the bake.
+        // Spawned geometry that cannot draw yet is a hole in the reveal; published every frame.
         p.gx_pending = staticgx
             .as_deref()
             .map_or(0, crate::static_gx::StaticGx::undrawn_regions);
-        // …and once nothing else is outstanding, the burst is over by definition: ask the pass to
-        // publish what it holds instead of letting the quiet window add its own 15 frames to the
-        // end of every load. Gated on the load itself (`!paced` — entry, a teleport, a world
-        // swap), so steady-state play keeps the batching the windows exist for.
+        // During a load, once nothing else is outstanding, flush the pass rather than wait out
+        // its quiet window.
         if !focus.paced
             && p.gx_pending > 0
             && p.scene_ready
@@ -1223,23 +908,17 @@ fn stream_terrain(
                 gx.flush_now();
             }
         }
-        // Residency is *published* here and read by the mover's post-snap hold one stage later
-        // (`player::release_post_snap_hold`). The streamer is still the only authority on which
-        // map the colliders under the avatar belong to — it just states the fact now instead of
-        // reaching across 1160's line to act on it (decision 0737's release, inverted).
     }
     activity.stream_ms += t0.elapsed().as_secs_f32() * 1000.0;
 }
 
-/// `WOW_NO_TILE_DROP=1` — never release stale tiles (the ablation switch described at its use
-/// site in [`stream_terrain`]): a crossing becomes a pure asset-ADD event. Dev-only.
+/// `WOW_NO_TILE_DROP=1`: never release stale tiles, so a crossing only adds (dev-only).
 fn tile_drop_disabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_NO_TILE_DROP").is_some())
 }
 
-/// Register one M2 doodad placement: bump the refcount if it's already known, else load its model and
-/// record it (spawned later by [`spawn_loaded_placements`] once the asset is ready).
+/// Register one M2 doodad placement, or bump its refcount if already known.
 fn register_doodad(
     placements: &mut Placements,
     asset_server: &AssetServer,
@@ -1273,7 +952,7 @@ fn register_doodad(
     placements.pending_spawns += 1;
 }
 
-/// Register one WMO building placement (vanilla scale is 1, so no per-placement scale).
+/// Register one WMO placement, or bump its refcount; a 1.12 WMO placement has no scale.
 fn register_wmo(placements: &mut Placements, asset_server: &AssetServer, w: &WmoInstance) {
     if let Some(p) = placements.by_id.get_mut(&w.unique_id) {
         p.refs += 1;
@@ -1296,23 +975,14 @@ fn register_wmo(placements: &mut Placements, asset_server: &AssetServer, w: &Wmo
             doodads: Vec::new(),
             portal_instance: None,
             refs: 1,
-            owner: (0, 0), // unread for WMOs — their prop hulls weld per placement (1369)
+            owner: (0, 0), // unread for WMOs: their prop hulls weld per placement
         },
     );
     placements.pending_spawns += 1;
 }
 
-/// Despawn a tile's exclusively-owned entities — the terrain mesh, water surfaces, and per-chunk
-/// `ClutterChunk`s (whose built meshes are children, so the despawn cascades). Shared doodad/WMO
-/// placements are NOT touched here; they're refcount-released separately.
-/// Drop every streamed tile and the placements they reference — the world, released.
-///
-/// One body, two triggers, because they are the same event seen from different sides: a cross-map
-/// teleport ends the world you were in, and so does leaving for character select. The material
-/// dedup goes with the placements it deduped for — its strong handles are what kept every
-/// previous map's materials (and their textures) resident forever (the #bugs teleport leak), so it
-/// is cleared *here*, sharing the exact trigger of the teardown it belongs to, rather than hanging
-/// off `world_map::MapChange`.
+/// Drop every streamed tile and the placements they reference, on a cross-map teleport or on
+/// leaving the world; the material dedup goes too, or its handles would keep the old map's art.
 fn drop_streamed_world(
     commands: &mut Commands,
     state: &mut TerrainStreamer,
@@ -1333,26 +1003,19 @@ fn drop_streamed_world(
         release_placement(commands, placements, GLOBAL_WMO_UID, activity);
     }
     placements.materials.clear();
-    // The weld accumulators describe the world just dropped. Cleared HERE and not left to the
-    // flush system's dead-key discard, because tile keys are not unique across maps: the new
-    // map's tiles are requested (and their `TileState`s inserted) on this very frame, so a stale
-    // accumulator could weld the previous map's geometry into a same-numbered fresh tile.
+    // Cleared here, not by the flush's dead-key discard: tile keys repeat across maps, and the
+    // new map's tiles are inserted this same frame. The same holds for the merge accumulators,
+    // the census tallies and the retained cells.
     welds.clear();
-    // Same staleness argument for the merge accumulators (1417) and the census tallies: both
-    // describe the world just dropped, and tile keys repeat across maps.
     merge.clear();
-    // …and for the B1 retained cells (1429): cell keys repeat across maps too.
     if let Some(gx) = staticgx {
         gx.clear();
     }
     crate::static_merge::reset();
 }
 
-/// Expire the placement material dedup by **distance** (decision 0793) — the within-map half of
-/// [`drop_streamed_world`]'s clear. This is the big one: `mats` 2603 → 26786 over ten minutes on a
-/// same-map tour (decision 0785) is overwhelmingly submesh materials of doodads and buildings whose
-/// tiles unloaded thousands of yards ago. The placements themselves are already refcount-released;
-/// only the dedup kept their materials — and through them their textures — alive.
+/// Expire the placement material dedup by distance, the within-map half of
+/// [`drop_streamed_world`]'s clear.
 fn scope_placement_art(mut scope: crate::art_scope::ArtScope, mut placements: ResMut<Placements>) {
     scope.apply(
         &mut placements.materials,
@@ -1360,11 +1023,8 @@ fn scope_placement_art(mut scope: crate::art_scope::ArtScope, mut placements: Re
     );
 }
 
-/// Leaving `InWorld` (a `/logout` back to character select): release the world.
-///
-/// `map_dir`/`wdt` are cleared too, so the next entry reads as a fresh map rather than a resumed
-/// one — otherwise a re-entry on the SAME map would take the "nothing changed" path and stream
-/// against a `TerrainStreamer` whose tiles have all been despawned.
+/// Release the world on leaving it; `map_dir` and `wdt` clear too, so re-entering the same map
+/// streams afresh.
 fn release_world(
     mut commands: Commands,
     mut state: ResMut<TerrainStreamer>,
@@ -1372,8 +1032,7 @@ fn release_world(
     mut forms: ResMut<crate::model_forms::ModelForms>,
     mut progress: Option<ResMut<WorldLoadProgress>>,
     mut activity: ResMut<StreamActivity>,
-    // Bundled for the same reason as `stream_terrain`'s pair: the stream-batch
-    // accumulators the world drop must clear (and clippy's argument-count line).
+    // The stream-batch accumulators the drop must clear, bundled under clippy's argument count.
     batchers: (
         ResMut<HullWelds>,
         ResMut<StaticMerge>,
@@ -1388,9 +1047,7 @@ fn release_world(
         "terrain: leaving the world — releasing {} tiles",
         state.tiles.len()
     );
-    // The model-form cache frees per asset on `Unused` events; leaving the world drops the whole
-    // cache in one deterministic sweep instead — nothing world-scoped may survive a logout, and
-    // an entry whose asset another holder keeps resident would otherwise pin its meshes forever.
+    // Drop the whole model-form cache, or an entry another holder keeps would pin its meshes.
     forms.clear();
     drop_streamed_world(
         &mut commands,
@@ -1404,8 +1061,7 @@ fn release_world(
     state.map_dir = None;
     state.wdt = None;
     state.wdt_ungated = false;
-    // The residency the loading screen reads is about a world that no longer exists; leaving it
-    // standing would let the next entry clear its cover against the previous world's counts.
+    // Reset residency, or the next entry could clear its cover on this world's counts.
     if let Some(p) = progress.as_mut() {
         **p = WorldLoadProgress::default();
     }
@@ -1426,13 +1082,9 @@ fn despawn_tile_owned(commands: &mut Commands, t: &TileState) {
     }
 }
 
-/// The `WorldDetail` re-scatter (0992): 1.12's own setter law — writing the density CVar
-/// tail-calls the chunk-rebuild walk (`0x6725a0` → `0x6b1d20`, wow-re terrain.md), so a change
-/// re-scatters the LOADED tiles too, not just future streams. The fresh `ClutterChunk`s spawn
-/// unbuilt and the lazy builder re-meshes the ~70 yd bubble over the next frames. Watches the
-/// VALUE, not `is_changed()`, because the predicate is "the density moved" and not "the resource
-/// moved": `ClutterConfig` also carries the detail-doodad cutout, whose console command would
-/// otherwise re-scatter every loaded tile. First sight only arms.
+/// Re-scatter the loaded tiles when `WorldDetail` changes, as the reference's setter tail-calls
+/// the chunk rebuild (`0x6725a0` → `0x6b1d20`). It watches the density value, since
+/// `ClutterConfig` also holds the detail-doodad cutout; the first sight only arms.
 fn rescatter_clutter(
     mut commands: Commands,
     mut streamer: ResMut<TerrainStreamer>,
@@ -1478,10 +1130,8 @@ fn rescatter_clutter(
     }
 }
 
-/// Mirror the live, spawned WMO placement SET into [`WmoResidency`] each frame, so the interior
-/// classifier ([`crate::interior`]) re-tests standing entities when a building streams in/out under
-/// them (the down-ray itself reads the live portal instances). Rebuilt wholesale: few WMOs are ever
-/// resident, so it's cheap.
+/// Mirror the spawned WMO placements into [`WmoResidency`] each frame, so the interior classifier
+/// re-tests when a building streams in or out; rebuilt whole, as few WMOs are resident.
 fn sync_interior_volumes(placements: Res<Placements>, mut vols: ResMut<WmoResidency>) {
     vols.update(
         placements
@@ -1494,17 +1144,9 @@ fn sync_interior_volumes(placements: Res<Placements>, mut vols: ResMut<WmoReside
     );
 }
 
-/// **1417's owner-handoff re-emit.** A straddler's merged batches and welded hulls live with
-/// its OWNER tile (`Placement::owner`), so an owner unloading out from under a placement that
-/// a loaded neighbour still references left a permanent hole: the blob and hull died with the
-/// owner's tile, and a later re-cross of the owner only bumps refs (`register_doodad`) — the
-/// re-cross defect. Hand the placement to a still-loaded referrer instead and queue a respawn:
-/// the spawner re-runs the whole assembler under the new owner — the merge divert and the hull
-/// weld both read `p.owner` at spawn — so 1369's matching weld gap heals in the same stroke.
-/// The per-entity churn is invisible (the unload line sits past every fade band), and the
-/// respawned batches open as cell singletons that fold in on the next quiet window (1424's
-/// recon). M2 map doodads only: a WMO's prop blobs ride the placement's own entity list, and
-/// without the merge a surviving placement never lost anything (its entities are its own).
+/// Hand the dead tile's surviving M2 placements to a still-loaded referrer and queue a respawn:
+/// their merged batches and welded hulls live with the owner tile and died with it. Only with the
+/// merge on; a WMO's prop blobs ride its own entity list.
 fn handoff_straddlers(
     commands: &mut Commands,
     tiles: &HashMap<(i32, i32), TileState>,
@@ -1516,10 +1158,7 @@ fn handoff_straddlers(
     if !merge_on {
         return;
     }
-    // The straddlers first — the dead tile's M2 placements that survived the release with refs
-    // left (a handful to ~90 of its ~1k uids) — then ONE pass over each 8-neighbour's list. The
-    // old shape asked `Vec::contains` of every neighbour's whole list per straddler: 8 × ~1k
-    // compares × every straddler, on every tile drop (1697 item 2).
+    // The dead tile's M2 placements with refs left, then one pass over each neighbour's list.
     let mut straddlers: HashMap<u32, Option<(i32, i32)>> = uids
         .iter()
         .copied()
@@ -1532,10 +1171,10 @@ fn handoff_straddlers(
         .map(|uid| (uid, None))
         .collect();
     if straddlers.is_empty() {
-        return; // refs hit zero — released outright, nothing survives to hand off
+        return; // every one released outright
     }
-    // A straddler's other referrer shares its MDDF row across a tile seam, so it is an
-    // 8-neighbour of the dead owner; the full scan is a fallback for data that defies that.
+    // Another referrer shares the MDDF row across a tile seam, so it is an 8-neighbour; the full
+    // scan is the fallback.
     let neighbours = [-1i32, 0, 1]
         .iter()
         .flat_map(|dx| [-1i32, 0, 1].map(|dy| (dead.0 + dx, dead.1 + dy)))
@@ -1593,8 +1232,7 @@ fn handoff_straddlers(
     }
 }
 
-/// A tile referencing this placement unloaded: drop one ref, despawning its entities (render submeshes
-/// + the avian collider entity) at zero — the collider rides the placement's entity lifecycle.
+/// Drop one ref of a placement, despawning its entities, collider included, at zero.
 fn release_placement(
     commands: &mut Commands,
     placements: &mut Placements,
@@ -1610,8 +1248,7 @@ fn release_placement(
     };
     if drop_it {
         if let Some(p) = placements.by_id.remove(&uid) {
-            // The removed record may still owe spawns (a model that never landed, a building's
-            // props still arriving) — its share leaves the pending count with it.
+            // Its unspawned model and props leave the pending count with it.
             placements.pending_spawns -=
                 usize::from(!p.spawned) + p.doodads.iter().filter(|d| !d.spawned).count();
             activity.placements_dropped += 1;
@@ -1623,24 +1260,11 @@ fn release_placement(
     }
 }
 
-/// The terrain base material (the `TerrainExtension` does the real work).
-///
-/// **Single-sided, backface-culled** — the ground is see-through from underneath, exactly as the
-/// real client renders it (decision 0960; B193: testers see through 1.12.1's terrain from below, the
-/// way a WMO exterior reads from inside a cave; we drew it solid). The reference never sets
-/// `EGxRs 0x14` (`GL_CULL_FACE`) in its terrain-chunk pass `0x684510`/`0x6beb50`, so terrain inherits
-/// the device baseline `0x14 = 1` written by `0x593bf0` — culling ON, and wow-re's census of all 39
-/// `0x14` setters proves none leaks in unbracketed ahead of the terrain drain. Only the passes that
-/// *want* two sides clear it inside their own `Push`/`PopRenderState` bracket: the four liquid
-/// passes, and the WDL mesh `0x6bd780` (cull 0 at `0x6bd79d`) — which is why `wdl.rs` stays
-/// `cull_mode: None` while this one culls. Measured, not only derived: in the reference's own
-/// apitrace all 103 MCNK-format draws run cull-enabled and all 20 WDL draws cull-disabled.
-/// `double_sided: true` here was a Bevy default that no decision ever stood behind.
-///
-/// Rests on the winding: `terrain_fans_wind_ccw_seen_from_above` (benilla-formats) pins every MCNK
-/// fan CCW-from-above in WoW space, and `transform_is_a_proper_rotation` pins the WoW→Bevy map at
-/// det +1 — so the ground's front face points up under wgpu's `FrontFace::Ccw`. Flip either and
-/// terrain disappears from *above*.
+/// The terrain base material, backface-culled so the ground is see-through from below, as in the
+/// reference: its terrain pass (`0x684510`/`0x6beb50`) never sets `EGxRs 0x14` and keeps the
+/// device baseline cull on (`0x593bf0`); only the liquid passes and the WDL mesh clear it
+/// (`0x6bd780`, at `0x6bd79d`). Front faces point up only while the winding tests
+/// `terrain_fans_wind_ccw_seen_from_above` and `transform_is_a_proper_rotation` hold.
 fn terrain_base_material() -> StandardMaterial {
     StandardMaterial {
         base_color: Color::WHITE,
@@ -1655,7 +1279,7 @@ fn terrain_base_material() -> StandardMaterial {
 mod focus_tests {
     use super::*;
 
-    /// Stratholme's coordinates, and a camera parked where `player::setup` leaves it at boot.
+    /// Stratholme's map and position.
     const PICK: (u32, [f32; 3]) = (329, [3398.9, -3381.8, 142.7]);
     fn cam_at_northshire() -> Option<Vec3> {
         Some(wow_to_bevy([SPAWN_XY.0, SPAWN_XY.1, 100.0]))
@@ -1663,9 +1287,6 @@ mod focus_tests {
 
     #[test]
     fn the_pick_outranks_the_camera_until_the_avatar_exists() {
-        // The regression this guards is invisible and expensive: with the camera winning, world
-        // entry spends its scarcest IO on Northshire tiles for a character in Stratholme, then
-        // throws them away when the snap lands (decision 0777).
         let idle = ViewFocus::entry(PICK.0, PICK.1);
         assert_eq!(
             idle.map(Some(0)),
@@ -1677,8 +1298,7 @@ mod focus_tests {
 
     #[test]
     fn the_avatar_outranks_the_pick_once_it_is_in_the_world() {
-        // `pending_pick` deliberately survives world entry (0065's seamless reconnect re-answers
-        // with it), so a stale entry row must never pull the focus off a walking avatar.
+        // The entry row survives world entry, so it must never pull the focus off an avatar.
         let walking = ViewFocus::body([100.0, 200.0, 30.0], true);
         assert_eq!(walking.map(Some(1)), 1);
         let f = walking.resolve(cam_at_northshire());
@@ -1693,10 +1313,9 @@ mod focus_tests {
         let flying = ViewFocus::detached([100.0, 200.0, 30.0], true);
         let f = flying.resolve(cam_at_northshire());
         assert!((f[0] - SPAWN_XY.0).abs() < 0.01, "{f:?}");
-        // …and the body is still published, because the zone authority follows the character.
+        // The body is still published: the zone authority follows the character.
         assert_eq!(flying.body_pos(), Some([100.0, 200.0, 30.0]));
-        // A capture run: no roster, no avatar — the camera is the only answer, and the last-ditch
-        // fallback must still be the anchor rather than the origin.
+        // No avatar: the camera, else the spawn point, never the origin.
         assert!((ViewFocus::camera().resolve(cam_at_northshire())[0] - SPAWN_XY.0).abs() < 0.01);
         assert_eq!(
             ViewFocus::camera().resolve(None),
@@ -1760,9 +1379,6 @@ mod straddler_tests {
             .unwrap();
     }
 
-    /// The owner dies while a neighbour still lists the placement: ownership moves to the
-    /// neighbour and the placement is queued for respawn (entities down, `spawned` cleared) so
-    /// the assembler re-emits its merged batches and hulls under the new owner.
     #[test]
     fn a_dead_owner_hands_its_straddler_to_a_loaded_referrer() {
         let mut world = World::new();
@@ -1791,8 +1407,6 @@ mod straddler_tests {
         );
     }
 
-    /// A placement the dead tile merely referenced (owner elsewhere) is untouched, and the
-    /// whole pass is a no-op without the merge — a surviving placement never lost anything.
     #[test]
     fn non_owned_and_merge_off_placements_stay_untouched() {
         let mut world = World::new();
@@ -1801,7 +1415,7 @@ mod straddler_tests {
         let mut streamer = TerrainStreamer::default();
         streamer.tiles.insert((3, 5), tile_listing(&[7, 8]));
         let mut placements = Placements::default();
-        placements.by_id.insert(7, straddler((3, 5), vec![e1])); // owned by the SURVIVOR
+        placements.by_id.insert(7, straddler((3, 5), vec![e1])); // owned by the survivor
         placements.by_id.insert(8, straddler((3, 4), vec![e2])); // owned by the dead tile
         world.insert_resource(streamer);
         world.insert_resource(placements);
diff --git a/crates/benilla-world/src/terrain_stream/collider.rs b/crates/benilla-world/src/terrain_stream/collider.rs
index 2d9ec8b3..4b26d341 100644
--- a/crates/benilla-world/src/terrain_stream/collider.rs
+++ b/crates/benilla-world/src/terrain_stream/collider.rs
@@ -1,12 +1,6 @@
-//! Off-thread static-collider builds for streamed geometry (terrain tiles, doodads, WMOs,
-//! props). parry's trimesh/QBVH construction is the hundreds-of-ms cost that hitched the frame
-//! on stream-in, so the build runs on the async compute pool ([`build_collider_task`]) and
-//! [`finish_colliders`] attaches each result under a per-frame budget.
-//!
-//! The build being off-thread is only half the story: *attaching* the finished shape is main-thread
-//! structural work (an archetype move plus avian's required components and its on-insert
-//! mass-property hook), and the async pool finishes a streamed burst together — so a tile boundary
-//! used to attach the whole burst in a single frame. Decision 0610 measured that path and caps it.
+//! Static colliders for streamed geometry: parry's trimesh build runs on the async compute pool
+//! ([`build_collider_task`]) and [`finish_colliders`] attaches the results under a per-frame
+//! budget, since a streamed burst finishes together and each attach is main-thread work.
 
 use std::time::{Duration, Instant};
 
@@ -18,33 +12,27 @@ use bevy::prelude::*;
 use bevy::tasks::futures_lite::future;
 use bevy::tasks::{block_on, AsyncComputeTaskPool, Task};
 
-/// Wall-clock spent per frame *attaching* finished colliders before deferring the rest to a later
-/// frame — the collider twin of `SPAWN_BUDGET`, and for the same reason. Measured cost of one attach
-/// (decision 0610): ~0.004 ms per entity plus ~1.8e-5 ms per triangle, so a burst of a thousand-odd
-/// doodads (or a dozen tiles) landing together is the 9.45 ms of main-thread time the traced flight
-/// hitch spent here. Deferring is nearly free to *feel*: the streamer loads ahead of the view, so
-/// just-streamed static geometry going solid a few frames late is not yet reachable.
+/// Wall clock per frame for attaching finished colliders (one costs ~0.004 ms plus ~1.8e-5 ms per
+/// triangle); the rest wait, and the streamer loads far enough ahead that none is reachable yet.
 const ATTACH_BUDGET: Duration = Duration::from_millis(2);
 
-/// A static collider being built on the async compute pool (see [`build_collider_task`]); once the
-/// parry shape is ready, [`finish_colliders`] inserts it (with `layers`, for the WMO walk/camera
-/// audiences) onto this entity. Building off-thread keeps a big-WMO / terrain stream-in from hitching
-/// the frame.
+/// A test's override of [`ATTACH_BUDGET`]; `Duration::ZERO` attaches exactly one per call.
+#[derive(Resource)]
+pub(super) struct AttachBudget(pub(super) Duration);
+
+/// A static collider building on the async compute pool, which [`finish_colliders`] attaches to
+/// this entity.
 #[derive(Component)]
 pub struct PendingCollider {
     /// The in-flight parry build; taken the frame it completes.
     task: Option<Task<Collider>>,
-    /// The finished shape, parked here when [`ATTACH_BUDGET`] deferred its attach to a later frame.
-    /// A completed [`Task`] cannot be polled twice, so the shape needs somewhere to live between
-    /// "built" and "attached" — this is that somewhere, and it is why no finished build is dropped.
+    /// The finished shape, waiting out a deferred attach: a completed [`Task`] cannot be polled
+    /// twice.
     built: Option<Collider>,
     /// WMO walk / camera collision layer; `None` = the default layer (terrain, doodads, props).
     layers: Option<CollisionLayers>,
-    /// Insert `RigidBody::Static` with the collider — every world-anchored placement. `false` = a
-    /// bare collider that attaches to its nearest `RigidBody` ancestor: a transport deck prop's
-    /// hull riding the boat's kinematic body ([`crate::entities`]' wmo_props). A `Static` body
-    /// there would anchor the hull to the world at its spawn pose and the cargo would sail away
-    /// from its own collision.
+    /// Insert `RigidBody::Static` too. `false` for a transport deck prop, whose bare collider
+    /// rides the boat's kinematic body; a static one would stay at its spawn pose.
     static_body: bool,
 }
 
@@ -58,28 +46,28 @@ impl PendingCollider {
             static_body,
         }
     }
+
+    /// An already-built collider, so a test stages a burst without a thread pool.
+    #[cfg(test)]
+    fn ready(collider: Collider, layers: Option<CollisionLayers>, static_body: bool) -> Self {
+        Self {
+            task: None,
+            built: Some(collider),
+            layers,
+            static_body,
+        }
+    }
 }
 
-/// Attach off-thread-built colliders to their entities, at most [`ATTACH_BUDGET`] worth per frame.
-///
-/// Exclusive on purpose. The previous shape queued each attach as a deferred command, which put the
-/// whole burst into one `system_commands` block with nothing able to measure or stop it; owning the
-/// `&mut World` is what makes a deadline enforceable at all. Polling stays cheap — the traced cost of
-/// the poll pass over the entire pending set was ~0.005 ms — so the budget guards only the inserts.
+/// Attaches off-thread-built colliders, at most [`ATTACH_BUDGET`] worth per frame. Exclusive, so
+/// the deadline can stop mid-burst where deferred commands would all apply in one block.
 pub(super) fn finish_colliders(
     world: &mut World,
     state: &mut SystemState<Query<'static, 'static, (Entity, &mut PendingCollider)>>,
 ) {
-    // Pass 1 — poll in-flight builds. A completed task hands its shape to `built`, so running out of
-    // budget below can never drop a finished collider on the floor.
-    //
-    // Capped: a cold zone load queues *tens of thousands* of pending colliders (10 500 at once
-    // entering Stormwind), and the budget below can attach at most ~500 of the cheapest ones in a
-    // frame. Collecting every ready entity would rebuild a huge list each frame to use a slice of
-    // it. `READY_SCAN_CAP` bounds the ready list while staying far above what any frame can spend;
-    // the rest are picked up next frame (they stay in the query until attached, so none is skipped).
-    // The walk itself covers the whole set regardless (it is the ~0.005 ms part) — it also yields
-    // the queue-depth publish below.
+    // Pass 1: poll every in-flight build; a completed task hands its shape to `built`. The ready
+    // list is capped far above what a frame can attach (a cold zone load queues tens of
+    // thousands); the rest stay queued for the next frame.
     const READY_SCAN_CAP: usize = 2048;
     let t0 = Instant::now();
     let mut ready: Vec<Entity> = Vec::new();
@@ -96,15 +84,8 @@ pub(super) fn finish_colliders(
             ready.push(entity);
         }
     }
-    // Publish the queue depth (decision 0737): the loading-screen clear and the settle release
-    // both refuse to call the world presentable while attaches are outstanding — a spawned
-    // building whose collider still sits in this queue is exactly what a body must not be
-    // released onto. This system heads the Stream chain (0738), so the consumers read this
-    // frame's depth; the count is the depth entering the frame (attaches below shrink it next
-    // publish), which can only delay a release, never wrong one.
-    // The weld accumulators count as pending too (decision 1369): each unflushed batch becomes
-    // at least one collider on this queue, and the settle release must not let a body go while
-    // doodad hulls still sit in one. Same conservative semantics as the depth itself.
+    // The queue depth, unflushed welds included: the loading screen and the settle release wait
+    // on it, so no body is released onto geometry without its collider. An overcount only delays.
     let weld_backlog = world
         .get_resource::<super::weld::HullWelds>()
         .map_or(0, |w| w.unflushed());
@@ -113,7 +94,7 @@ pub(super) fn finish_colliders(
         progress.colliders_pending = pending + weld_backlog;
     }
     if ready.is_empty() {
-        // `get_`: the unit tests below drive this system on a minimal App without the perf layer.
+        // `get_`: the unit tests run without the perf layer.
         if let Some(mut activity) =
             world.get_resource_mut::<crate::terrain_stream::StreamActivity>()
         {
@@ -122,14 +103,14 @@ pub(super) fn finish_colliders(
         return;
     }
 
-    // Pass 2 — the main-thread cost. The budget is checked *after* each attach so one oversized
-    // collider still makes progress rather than stalling the queue forever (the rule
-    // `stream_terrain` already applies to its tile spawns).
+    // Pass 2: attach. The deadline is checked after each attach, so an oversized one still lands.
     let mut attached = 0u32;
-    let deadline = Instant::now() + ATTACH_BUDGET;
+    let budget = world
+        .get_resource::<AttachBudget>()
+        .map_or(ATTACH_BUDGET, |b| b.0);
+    let deadline = Instant::now() + budget;
     for entity in ready {
-        // The entity may have streamed out (despawned) while its collider was building, or had its
-        // slot reused — a no-op rather than a panic.
+        // The entity may have streamed out while its collider was building.
         let Ok(mut entity_mut) = world.get_entity_mut(entity) else {
             continue;
         };
@@ -155,9 +136,7 @@ pub(super) fn finish_colliders(
         activity.colliders_attached += attached;
         activity.collider_ms += t0.elapsed().as_secs_f32() * 1000.0;
     }
-    // The world a cached collision answer was computed against just changed — see
-    // [`crate::collision::ColliderEpoch`]. This is the attach half; removals are stamped by
-    // `track_collider_removals`.
+    // Invalidates cached collision answers (`crate::collision::ColliderEpoch`).
     if attached > 0 {
         if let Some(mut epoch) = world.get_resource_mut::<crate::collision::ColliderEpoch>() {
             epoch.bump();
@@ -165,30 +144,22 @@ pub(super) fn finish_colliders(
     }
 }
 
-/// `WOW_NO_DOODAD_BODIES=1` — spawn NO doodad/prop hulls at all (decision 1367's premise
-/// bracket): the ceiling of what the whole lane can be worth, measured by deleting it. The
-/// player loses doodad collision and the doodad pick clamp for the run — a measurement lever,
-/// never a setting. Terrain, impassable fences and WMO building colliders are untouched.
+/// `WOW_NO_DOODAD_BODIES=1` spawns no doodad or prop hulls: a measurement lever that drops their
+/// collision and pick clamp for the run.
 pub(crate) fn doodad_bodies_disabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_NO_DOODAD_BODIES").is_some())
 }
 
-/// `WOW_BARE_DOODAD_COLLIDERS=1` — doodad/prop hulls spawn as body-LESS colliders (decision
-/// 1367): avian 0.6 files a collider with no `ColliderOf` in its first-class **Standalone**
-/// tree (`collider_tree/proxy_key.rs`), still spatial-queryable and still a contact target, so
-/// this is the idiomatic collider-only shape itself, not an approximation of it. What the lever
-/// removes is the `RigidBody::Static` row weight — the velocities/mass/solver components the
-/// 1364 census counted 12.2k of at the Stormwind pin.
+/// `WOW_BARE_DOODAD_COLLIDERS=1` spawns doodad and prop hulls without `RigidBody::Static`: avian
+/// files a body-less collider as standalone, still spatial-queryable and a contact target.
 pub(crate) fn doodad_hulls_bare() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_BARE_DOODAD_COLLIDERS").is_some())
 }
 
-/// The world-space `(vertices, triangles)` for a model's static collider — its raw-WoW collision hull
-/// mapped through `wow_to_bevy` then the placement [`Transform`] (so the collider coincides with the
-/// drawn model). `None` for a hull-less model or an empty mesh. The (potentially expensive) parry build
-/// is deferred off-thread via [`build_collider_task`].
+/// A model's collision hull in world space as `(vertices, triangles)`: `wow_to_bevy`, then the
+/// placement [`Transform`].
 pub fn placement_collider_data(
     hull: Option<&CollisionMesh>,
     transform: &Transform,
@@ -212,14 +183,8 @@ pub fn placement_collider_data(
     Some((verts, tris))
 }
 
-/// The `(vertices, triangles)` for a terrain tile's static collider: **one** trimesh welded from the
-/// tile's decoded MCNK chunks, in the same world space they are drawn in (so you stand on the visible
-/// ground). `None` for a tile with no triangles at all.
-///
-/// Built from the decoded chunks rather than the render meshes because the tile no longer *has* one
-/// merged mesh to read (decision 0780) — and one collider per 33 yd cell would be 256 parry builds
-/// and 256 QBVHs where the ground is a single continuous surface. The mapping is the loader's,
-/// verbatim: `wow_to_bevy` per position, hole-masked indices rebased onto the running vertex count.
+/// A terrain tile's collider: one trimesh welded from its decoded MCNK chunks in draw space, the
+/// loader's hole-masked indices rebased onto the running vertex count.
 pub(super) fn terrain_collider_data(
     chunks: &[benilla_formats::ChunkMesh],
 ) -> Option<(Vec<Vec3>, Vec<[u32; 3]>)> {
@@ -240,57 +205,37 @@ pub(super) fn terrain_collider_data(
     (!tris.is_empty()).then_some((verts, tris))
 }
 
-/// How far an impassable chunk's fence rises above the chunk's own floor — the reference's literal
-/// `u = (0, 0, 32000.0)` (immediate `0x46fa0000` at `0x6ab599`), VERIFIED by wow-re's §5 on
-/// `0x6ab530` (`system/terrain/scratch/impassable-chunk-walls.md`).
-///
-/// It is a *reach*, not a height: the quad is based at `chunk+0x4c`, the chunk AABB's **min z**, so
-/// the fence stands on the chunk's lowest ground and rises 32 km. Nothing extends below — a mover
-/// under the chunk floor (a mine, a tunnel, the sea bed) passes beneath the wall, and that is the
-/// law, not an omission.
+/// How far an impassable chunk's fence rises from the chunk AABB's min z (`chunk+0x4c`): the
+/// reference's `(0, 0, 32000.0)` (`0x46fa0000` at `0x6ab599`, emitter `0x6ab530`). Nothing extends
+/// below, so a mover under the chunk floor (a mine, the sea bed) passes beneath.
 const FENCE_REACH: f32 = 32000.0;
 
-/// The `(vertices, triangles)` for a tile's **impassable-chunk fences** — the ADT-level invisible
-/// wall of report B129, in the same world space as the terrain collider.
+/// A tile's impassable-chunk fences as `(vertices, triangles)`, the reference's emitter
+/// `0x6ab530` reached from the movement box gather `0x6721b0 → 0x6aa8b0 → 0x6aadc0`. The flag is
+/// `CMapChunk+0xc & 0x40` (set at `0x6af5f0` from MCNK header bit 1, read only at `0x6aae2a`),
+/// tested once per chunk.
 ///
-/// The mechanism is the reference's, VERIFIED (wow-re §5 on the emitter `0x6ab530`, reached from
-/// the movement box gather `0x6721b0 → 0x6aa8b0 → 0x6aadc0`; the flag is `CMapChunk+0xc & 0x40`,
-/// written word-wide at `0x6af5f0` from MCNK header bit 1, and `0x6aae2a` is its only reader in the
-/// image):
+/// - Additive: the terrain under a flagged chunk stays walkable; the flag only adds a fence.
+/// - All four sides of every flagged chunk, neighbours unread, so a mover inside the band cannot
+///   cross within it either and no tile seam is ever consulted.
+/// - Outward normals: with the facing gate (`n·dir ≤ −1e-5`) you cannot walk in, and can always
+///   walk out.
+/// - `n.z == 0`: a fence is never a floor or a step.
 ///
-/// - **Additive, never subtractive.** The terrain under a flagged chunk stays exactly as walkable as
-///   any other; what the flag adds is a fence. Nothing is removed from the walkable set, which is
-///   why a flagged chunk holds you up rather than dropping you through.
-/// - **All four sides of every flagged chunk**, with no look at the neighbours. Two chunks side by
-///   side each keep their own shared-side fence, so a mover already inside the band cannot cross
-///   *within* it either — and the tile seam stops being a question, since nothing is ever asked
-///   about a chunk in another tile.
-/// - **Outward normals, so the fence is one-way.** Composed with the universal facing gate
-///   (`n·dir ≤ −1e-5`, decision 0970), entry is blocked and the same face is discarded on the way
-///   out: you cannot walk in, and if you start inside you can always walk out.
-/// - **Whole chunk.** The flag is tested once, before the reference's 8×8 cell loop opens — unlike
-///   holes and the no-doodad bits, which are per cell.
-/// - `n.z == 0` on all four, so a fence is never a floor and never something to step up onto.
-///
-/// The audience is the other half of the law and lives at the call site: the segment/ray path never
-/// reads the flag, so camera pull-in, mouse-pick and LOS are wall-blind, and terrain *height* is not
-/// gated at all.
+/// The segment and ray path never reads the flag: camera pull-in, mouse-pick and LOS are
+/// wall-blind, and terrain height is not gated.
 pub(super) fn impassable_wall_data(
     chunks: &[benilla_formats::ChunkMesh],
 ) -> Option<(Vec<Vec3>, Vec<[u32; 3]>)> {
     let mut verts: Vec<Vec3> = Vec::new();
     let mut tris: Vec<[u32; 3]> = Vec::new();
     for chunk in chunks.iter().filter(|c| c.impassable) {
-        // `chunk+0x4c`: the min corner of the AABB the reference folds over the chunk's 145 world
-        // vertices (`0x6b0e50`) — the chunk's lowest ground, wherever in the chunk it happens to be.
+        // `chunk+0x4c`: the min corner of the AABB over the chunk's 145 vertices (`0x6b0e50`).
         let Some(floor) = chunk.positions.iter().map(|p| p[2]).reduce(f32::min) else {
             continue; // a chunk with no vertices has no AABB to stand a fence on
         };
-        // The four footprint sides, from the corners of the 9×9 outer grid (stride 17: row `r`
-        // starts at `r·17`), each walked so that `(b−a)×(c−a)` points AWAY from the chunk. With +X
-        // north, +Y west and +Z up, a side whose outward normal is `n` must be walked along
-        // `t = ẑ × n`: south down the west side, north up the east side, west along the north side,
-        // east along the south side.
+        // The four sides from the 9×9 outer grid's corners (row `r` starts at `r·17`), each walked
+        // along `t = ẑ × n` (+X north, +Y west) so `(b−a)×(c−a)` points out of the chunk.
         const SIDES: [[usize; 2]; 4] = [
             [8, 0],     // north (row 0), walked east → west
             [136, 144], // south (row 8), walked west → east
@@ -317,10 +262,7 @@ pub(super) fn impassable_wall_data(
     (!tris.is_empty()).then_some((verts, tris))
 }
 
-/// Build a static-trimesh [`Collider`] on the **async compute pool** (parry's QBVH construction is the
-/// hundreds-of-ms cost that hitched the frame on big-WMO / terrain stream-in). [`finish_colliders`]
-/// attaches the result. A few-frame delay in collision for just-streamed *static* geometry is
-/// imperceptible — the streamer loads ahead of the view, so you never reach it before it's solid.
+/// Builds a static trimesh [`Collider`] on the async compute pool, for [`finish_colliders`].
 pub fn build_collider_task(verts: Vec<Vec3>, tris: Vec<[u32; 3]>) -> Task<Collider> {
     AsyncComputeTaskPool::get().spawn(async move { Collider::trimesh(verts, tris) })
 }
@@ -334,10 +276,8 @@ mod tests {
 
     use benilla_formats::{ChunkMesh, CHUNK_SIZE};
 
-    /// One MCNK at tile-grid `(index_x, index_y)`, flat at z = 0, carrying only what the wall
-    /// builder reads: the 9×9 outer grid in its stride-17 slots, the indices, and the flag. The
-    /// tile's NW corner sits at the WoW origin, so chunk `(ix, iy)` runs from `(−iy·C, −ix·C)`
-    /// south and east — rows step −x, columns step −y, exactly as `adt_to_tile_mesh` lays them out.
+    /// One flat MCNK at `(ix, iy)` with only what the wall builder reads. The tile's NW corner is
+    /// the WoW origin: rows step −x and columns −y, as `adt_to_tile_mesh` lays them out.
     fn chunk(ix: u32, iy: u32, impassable: bool) -> ChunkMesh {
         let (nw_x, nw_y) = (-(iy as f32) * CHUNK_SIZE, -(ix as f32) * CHUNK_SIZE);
         let mut positions = vec![[0.0_f32; 3]; 145];
@@ -380,9 +320,6 @@ mod tests {
         ])
     }
 
-    /// A flagged chunk is boxed in, and every face is wound OUTWARD — which is the whole mechanism:
-    /// composed with the one-sided movement law (0970), the fence blocks a mover walking in and is
-    /// discarded from behind, so the band cannot be entered and never traps what starts inside it.
     #[test]
     fn a_flagged_chunk_is_boxed_in_by_outward_facing_walls() {
         let chunks: Vec<ChunkMesh> = [(1, 1, true), (0, 1, false), (1, 0, false)]
@@ -409,12 +346,7 @@ mod tests {
         }
     }
 
-    /// Every flagged chunk keeps its **own** four sides, neighbours unread — so two side by side
-    /// carry a doubled fence on the boundary they share, wound apart. That is not redundancy: it is
-    /// what stops a mover already inside the band from crossing *within* it, since each chunk's
-    /// fence blocks entry to that chunk from any direction. It also makes the tile seam a non-issue,
-    /// because nothing is ever asked about a chunk in another tile — the case B129 is (the flagged
-    /// chunk is column 0 of `Azeroth_33_44`, the pin is column 15 of `Azeroth_32_44`).
+    /// Two flagged neighbours carry a doubled fence on their shared side, wound apart.
     #[test]
     fn every_flagged_chunk_fences_all_four_of_its_own_sides() {
         let chunks: Vec<ChunkMesh> = [(1, 1, true), (2, 1, true), (0, 1, false), (3, 1, false)]
@@ -424,8 +356,7 @@ mod tests {
         let (verts, tris) = impassable_wall_data(&chunks).expect("two flagged chunks");
         assert_eq!(tris.len(), 16, "four sides each, two triangles a side");
 
-        // The shared plane is WoW y = −2·CHUNK_SIZE ⇒ Bevy x = +2·CHUNK_SIZE. Both chunks put a
-        // face IN it, and the two must face opposite ways — each blocking entry to its own chunk.
+        // The shared plane: WoW y = −2·CHUNK_SIZE, Bevy x = +2·CHUNK_SIZE.
         let shared = 2.0 * CHUNK_SIZE;
         let normals: Vec<Vec3> = tris
             .iter()
@@ -449,13 +380,9 @@ mod tests {
         );
     }
 
-    /// A fence stands on the chunk's own floor and only ever rises — the reference bases the quad
-    /// at the chunk AABB's min z and adds `(0, 0, 32000)`. Nothing below: a mover under the chunk
-    /// floor (a mine, a tunnel, the sea bed) passes beneath the wall, and that is the law.
     #[test]
     fn a_fence_stands_on_the_chunk_floor_and_only_rises() {
-        // A chunk dished 12 yd below its corners, so "the floor" is a real minimum and not just the
-        // corner height the sides are built from.
+        // Dished 12 yd below its corners, so the floor is not the corners' height.
         let mut c = chunk(1, 1, true);
         c.positions[4 * 17 + 4][2] = -12.0;
         let (verts, _) = impassable_wall_data(&[c]).expect("walls");
@@ -472,22 +399,17 @@ mod tests {
         );
     }
 
-    /// The overwhelmingly common tile: no flag, no collider, nothing attached.
     #[test]
     fn a_tile_with_no_flagged_chunk_builds_no_wall() {
         let chunks = vec![chunk(0, 0, false), chunk(1, 0, false)];
         assert!(impassable_wall_data(&chunks).is_none());
     }
 
-    /// B129 end to end, on the shipped bytes and through the real cast: a body walking east from
-    /// Goudy's pin (`.go xyz -6601.98 -531.87 335.60 0`) is stopped where 1.12.1 stops it, at the
-    /// chunk boundary 1.46 yd away — and the SAME world built without the walls carries it straight
-    /// through, which is the report. Both halves matter: the second is the symptom reproduced, the
-    /// first is it gone, and a wall built at the wrong offset would satisfy neither. Skips without
-    /// client data.
+    /// On the shipped data, through the real cast: a body walking east from the pin stops at the
+    /// flagged chunk's boundary 1.46 yd away, as 1.12.1 stops it, and walks through without walls.
     #[test]
     fn a_body_walking_east_from_the_b129_pin_is_stopped_at_the_wall() {
-        /// Goudy's pin, and the MCNK boundary the flagged chunk starts at (WoW y; east is −y).
+        /// The pin, and the MCNK boundary the flagged chunk starts at (WoW y; east is −y).
         const PIN: [f32; 3] = [-6601.98, -531.87, 335.60];
         const WALL_Y: f32 = 32.0 * benilla_formats::TILE_SIZE - 528.0 * CHUNK_SIZE;
         const R: f32 = 0.5;
@@ -508,12 +430,10 @@ mod tests {
             .find_map(|t| benilla_formats::terrain_height_at(&t.chunks, PIN))
             .expect("terrain under the pin");
 
-        // How far the body gets walking east from a given height, in a world with the walls and in
-        // one without.
+        // How far a body walks east from height `z`, with or without the walls.
         let run_east = |walls: bool, z: f32| -> Option<f32> {
             let mut app = App::new();
-            // `WorldCollision` takes the mover's trace exclusions (the ghost/DOOR set, 1767), which the
-            // world plugins own and a bare harness does not run.
+            // `WorldCollision` reads the mover's trace exclusions, which the world plugins own.
             app.init_resource::<crate::collision::MoverTraceExclusions>();
             app.add_plugins((
                 MinimalPlugins,
@@ -555,12 +475,12 @@ mod tests {
 
         // Feet on the ground at the pin.
         let walking = ground + 1.0 + R;
-        // The report: nothing at all stops the body inside the 5 yd it walks.
+        // Without the walls nothing stops the body within the 5 yd it walks.
         assert!(
             run_east(false, walking).is_none(),
             "B129 itself — the terrain here does not stop a body, which is why the flag has to"
         );
-        // The fix: stopped, with the capsule's leading surface against the chunk boundary.
+        // With them, the capsule's leading surface stops at the chunk boundary.
         let d = run_east(true, walking).expect("the impassable chunk's fence stops the body");
         let leading_edge = -(wow_to_bevy([PIN[0], PIN[1], 0.0]).x + d) - R;
         assert!(
@@ -568,10 +488,8 @@ mod tests {
             "stopped at y={leading_edge}, wall is at y={WALL_Y} (travelled {d} yd)"
         );
 
-        // …and the other half of the same law: the fence is based at the flagged chunk's own floor
-        // and only rises, so a body BELOW that floor — a tunnel, a mine, the sea bed — crosses
-        // freely. Under the ground and out of the terrain's way, the only thing that could stop
-        // this cast is a fence reaching down, and the reference's does not.
+        // Below the flagged chunk's floor only a fence reaching down could stop the body, and the
+        // reference's does not.
         let floor = tiles
             .iter()
             .flat_map(|t| t.chunks.iter())
@@ -616,35 +534,61 @@ mod tests {
             bevy::asset::AssetPlugin::default(),
         ));
         app.init_asset::<Mesh>();
-        // Registers avian's collider hooks + required components, so an attach here costs what it
-        // costs in the client. Its schedules are never run — `run_system_once` drives ours alone.
+        // Avian's collider hooks, so an attach costs what it does in the client; its schedules
+        // never run.
         app.add_plugins(PhysicsPlugins::default());
         app.finish();
         app.cleanup();
         app
     }
 
-    /// The budget must both bite (a burst is spread over frames) and never lose a finished build.
-    /// The second half is the subtle one: a completed `Task` cannot be polled twice, so a deferred
-    /// attach has to park its shape rather than leave it in the task.
+    /// Polled until done, not slept for: the timing is the pool's and is not asserted.
+    #[test]
+    fn a_finished_task_hands_its_shape_over_and_attaches() {
+        let mut app = test_app();
+        let (verts, tris) = grid(4);
+        let task = build_collider_task(verts, tris);
+        let e = app
+            .world_mut()
+            .spawn((Transform::default(), PendingCollider::new(task, None, true)))
+            .id();
+        for _ in 0..100_000 {
+            app.world_mut().run_system_once(finish_colliders).unwrap();
+            if app.world().entity(e).contains::<Collider>() {
+                break;
+            }
+            std::thread::yield_now();
+        }
+        assert!(
+            app.world().entity(e).contains::<Collider>(),
+            "the pool finished the build (or never did — a hung pool, not a budget)"
+        );
+        assert!(
+            app.world().entity(e).contains::<RigidBody>(),
+            "a static body rides the attach"
+        );
+        assert!(app.world().get::<PendingCollider>(e).is_none());
+    }
+
+    /// Staged already built with a zero budget, so each call attaches exactly one.
     #[test]
     fn attach_budget_spreads_a_burst_without_losing_colliders() {
         const N: usize = 40;
         let mut app = test_app();
+        app.insert_resource(AttachBudget(std::time::Duration::ZERO));
         let (verts, tris) = grid(16);
         let entities: Vec<Entity> = (0..N)
             .map(|_| {
-                let task = build_collider_task(verts.clone(), tris.clone());
+                let collider = Collider::trimesh(verts.clone(), tris.clone());
                 app.world_mut()
-                    .spawn((Transform::default(), PendingCollider::new(task, None, true)))
+                    .spawn((
+                        Transform::default(),
+                        PendingCollider::ready(collider, None, true),
+                    ))
                     .id()
             })
             .collect();
 
-        // Let the pool finish every build, so the whole burst is ready at once — the tile-boundary
-        // case the budget exists for.
-        std::thread::sleep(std::time::Duration::from_millis(500));
-
         let attached = |app: &mut App| {
             entities
                 .iter()
@@ -653,11 +597,10 @@ mod tests {
         };
 
         app.world_mut().run_system_once(finish_colliders).unwrap();
-        let after_one = attached(&mut app);
-        assert!(after_one > 0, "budget starved the queue: nothing attached");
-        assert!(
-            after_one < N,
-            "budget never bit: all {N} attached in one frame ({after_one})"
+        assert_eq!(
+            attached(&mut app),
+            1,
+            "a zero budget is past after the first attach: exactly one lands per call"
         );
 
         // Drain: every remaining build must still land, none lost to the deferral.
diff --git a/crates/benilla-world/src/terrain_stream/furnish.rs b/crates/benilla-world/src/terrain_stream/furnish.rs
index 3f308e30..17b04ebc 100644
--- a/crates/benilla-world/src/terrain_stream/furnish.rs
+++ b/crates/benilla-world/src/terrain_stream/furnish.rs
@@ -1,17 +1,7 @@
-//! Paced per-cell tile furnishing — the fix for B181's *first-contact* spike (decision 0832).
-//!
-//! A landed tile's ~256 MCNK cell meshes used to arrive as loader-built sub-assets: the whole
-//! set (and, decodes bunching, usually the whole 5-tile row's ~1300) hit the render world's
-//! extract/prepare/upload in ONE frame — 80–105 ms of process CPU at the Emerald Dream pin,
-//! 120–240 ms at Undercity, on every first crossing of a tile line. No budget downstream of the
-//! loader could spread work the loader had already packaged, so the build moved here: each cell's
-//! mesh is made from the decoded [`AdtTile::chunks`] + [`AdtTile::shading`]
-//! ([`benilla_assets::chunk_to_mesh`]), a bounded number per frame while live, nearest tile
-//! first. Mesh-asset creation is the pacing point; everything downstream follows its rate.
-//!
-//! While the body is **not** live (entry, teleport, world-stale) the cap is off: the loading
-//! screen exists to absorb exactly that burst, and the residency the settle release reads counts
-//! *furnished* tiles, so the cover never lifts onto bare ground.
+//! Paced tile furnishing: cell meshes are built from a landed tile's decoded chunks
+//! ([`chunks_to_mesh`]) a bounded number per frame while live, nearest tile first, so crossing a
+//! tile line never uploads a whole row in one frame. While the body is not live (entry, teleport)
+//! the cap is off: the loading screen absorbs the burst and waits on furnished tiles.
 
 use std::time::Instant;
 
@@ -21,24 +11,19 @@ use bevy::prelude::*;
 
 use super::TerrainStreamer;
 
-/// Cells built per frame while live. Measured on the B181 carve: a landed cell mesh costs ~70 µs
-/// end-to-end (asset add + extract + prepare + upload, dev profile, Metal) — 64 ≈ 4.5 ms of
-/// render-side work per frame, and a whole fresh row (5 × 256 cells, two tiles out, in fog)
-/// furnishes in ~20 frames. The placement cap (`SPAWN_COUNT_CAP`) is this same idea one lane over.
+/// Chunks furnished per frame while live (four cells): a chunk's mesh costs ~70 µs from asset add
+/// to upload, so ~4.5 ms a frame.
 const CELL_SPAWN_CAP: usize = 64;
 
-/// A tile's 16×16 chunks furnish as 4×4 CELLS of 4×4 chunks each — one mesh, one entity, one
-/// draw per cell (decision 1945). A chunk was one draw each, and a city horizon is over a
-/// thousand of them a frame; every per-chunk fact is baked per vertex and the material is the
-/// tile's, so the cell mesh is the chunks' concatenation. `static_gx` and the merge lanes cut
-/// the world into the same 133⅓-yd cell for the same locality reason.
+/// A tile's 16×16 chunks furnish as 4×4 cells of 4×4 chunks, one mesh and one draw each: every
+/// per-chunk fact is baked per vertex and the material is the tile's. The 133⅓-yd cell matches
+/// `static_gx` and the merge lanes.
 const CELL_SPAN: usize = 4;
 const CELLS_PER_TILE: usize = (16 / CELL_SPAN) * (16 / CELL_SPAN);
 const CHUNKS_PER_CELL: usize = CELL_SPAN * CELL_SPAN;
 
-/// Build + spawn the cell entities of spawned-but-unfurnished tiles, [`CELL_SPAWN_CAP`] per frame
-/// while live, nearest tile to the stream focus first. Chained directly after `stream_terrain`
-/// (roots spawned there furnish from the same frame on) and before `spawn_loaded_placements`.
+/// Spawns the cell entities of unfurnished tiles, nearest the focus first, paced while live.
+/// Chained after `stream_terrain` and before `spawn_loaded_placements`.
 pub(super) fn furnish_tile_cells(
     mut commands: Commands,
     mut state: ResMut<TerrainStreamer>,
@@ -55,12 +40,8 @@ pub(super) fn furnish_tile_cells(
     } else {
         usize::MAX
     };
-    // Ablation switch (`WOW_NO_TILE_CELLS=1`): tiles stream — asset residency, collider,
-    // placements, liquid, clutter — without their per-chunk cell entities, isolating the
-    // render-entity lane from the asset lane when measuring a streaming cost. The B181 carve ran
-    // on it (a crossing's spike survived zero cells, exonerating the entity lane); the
-    // `WOW_NO_LIQUID`/`WOW_NO_PARTICLES` family's pattern. Tiles still MARK furnished, so the
-    // loading-screen residency (which now waits on furnishing) converges.
+    // `WOW_NO_TILE_CELLS=1`: tiles stream without cell entities, but still mark furnished so the
+    // loading screen converges.
     let ablated = tile_cells_disabled();
 
     let focus = state.focus;
@@ -83,9 +64,7 @@ pub(super) fn furnish_tile_cells(
         let (Some(root), Some(material)) = (tile.entity, tile.material.clone()) else {
             continue; // unreachable given the filter above, but never worth a panic
         };
-        // The handle keeps the asset resident for the tile's whole life, so a spawned tile's
-        // `AdtTile` is always here; a missing one (asset store torn down mid-shutdown) just
-        // leaves the tile unfurnished.
+        // Resident for the tile's life; missing only mid-shutdown, which leaves it unfurnished.
         let Some(adt) = tiles.get(&tile.handle) else {
             continue;
         };
@@ -106,14 +85,12 @@ pub(super) fn furnish_tile_cells(
                 })
                 .filter_map(|i| Some((adt.chunks.get(i)?, adt.shading.get(i)?)))
                 .collect();
-            // A hole-emptied cell yields no mesh (and costs nothing — it doesn't count).
+            // A hole-emptied cell yields no mesh and does not count.
             let Some(mesh) = chunks_to_mesh(&parts) else {
                 continue;
             };
-            // The cell's Aabb, computed HERE and inserted explicitly: the mesh is
-            // `RENDER_WORLD`-only, so Bevy's own `calculate_bounds` may find its data already
-            // extracted — and the exterior cull FAILS OPEN on a missing Aabb (an unbounded cell
-            // would draw forever, silently undoing 0780's cull unit).
+            // The Aabb is computed here: the mesh is `RENDER_WORLD`-only, so `calculate_bounds`
+            // may find it already extracted, and the exterior cull fails open on a missing Aabb.
             let aabb = mesh.compute_aabb();
             let handle = meshes.add(mesh);
             commands.entity(root).with_children(|cells| {
@@ -121,9 +98,8 @@ pub(super) fn furnish_tile_cells(
                     Mesh3d(handle),
                     MeshMaterial3d(material.clone()),
                     Transform::IDENTITY, // cell meshes are in absolute world coords
-                    // ADT terrain is exterior scene: from inside a WMO a cell draws only through
-                    // a portal window (`0x683bf0`, fed solely by the per-window walk `0x682fa0` —
-                    // see `crate::exterior_cull`).
+                    // Exterior scene: from inside a WMO a cell draws only through a portal window
+                    // (`0x683bf0`, fed only by the per-window walk `0x682fa0`).
                     crate::exterior_cull::ExteriorScene,
                 ));
                 if let Some(aabb) = aabb {
@@ -138,19 +114,16 @@ pub(super) fn furnish_tile_cells(
     activity.furnish_ms += t0.elapsed().as_secs_f32() * 1000.0;
 }
 
-/// `WOW_NO_TILE_CELLS=1` — furnish no per-chunk cell entities (the ablation switch described at
-/// its use site in [`furnish_tile_cells`]). Dev-only.
+/// `WOW_NO_TILE_CELLS=1` furnishes no cell entities (a dev measurement switch).
 fn tile_cells_disabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_NO_TILE_CELLS").is_some())
 }
 
-/// The one thing the furnisher promises the rest of the streamer: a tile is `furnished` only
-/// when its cursor walked every chunk (or cells are ablated off) — never merely "root exists".
+/// A tile is `furnished` only once its cursor has walked every cell, never when its root exists.
 #[cfg(test)]
 mod tests {
-    /// The cap's arithmetic, kept honest in one place: a full fresh row must furnish in well
-    /// under a second of frames at 60 Hz.
+    /// A fresh 5-tile row (5 × 256 chunks) must furnish within half a second at 60 Hz.
     #[test]
     fn a_fresh_row_furnishes_in_under_half_a_second() {
         let row_cells: usize = 5 * 256;
diff --git a/crates/benilla-world/src/terrain_stream/merge.rs b/crates/benilla-world/src/terrain_stream/merge.rs
index 425e133c..5233dae1 100644
--- a/crates/benilla-world/src/terrain_stream/merge.rs
+++ b/crates/benilla-world/src/terrain_stream/merge.rs
@@ -1,58 +1,18 @@
-//! **The production static-world consolidation, doodad lanes — ON by default** (1426;
-//! `WOW_STATIC_MERGE=0` opts out. Design 1417, lane order re-ranked by 1418's density
-//! verdict; the measured premise is 1413/1416's 44 ns/row tax).
+//! Static-world consolidation of doodad batches, on unless `WOW_STATIC_MERGE=0`. It runs behind
+//! the retained pass (`crate::static_gx`), which takes the static populations first: what reaches
+//! it is that pass's declined families, or everything under `WOW_STATIC_GX=0`.
 //!
-//! **Since 1434 this is the SECOND consolidator in line**: the retained pass
-//! (`crate::static_gx`, also default-on) takes the static populations first at the same
-//! assemble gate, and what reaches these accumulators under the defaults is its declined
-//! families (env-mapped, depth-flagged batches) plus everything under `WOW_STATIC_GX=0`,
-//! where this module is again the whole consolidation. The default flip deliberately
-//! removed no code here — this lane IS the A/B arm every gx comparison diffs against.
+//! The assembler diverts every fully static, order-free (`Opaque`/`AlphaTest`) batch that does not
+//! fade, and the flush bakes each ADT-doodad (owner tile, 133⅓-yd cell, material) or WMO-prop
+//! (placement, room set, material) group into one mesh with the placement transforms in its
+//! vertices. A blob closes at the vertex cap or after an idle tail; a doodad blob despawns with
+//! its tile (`TileState::merged`). Distance admission closes a cell in fragments during play, so a
+//! cell quiet for [`RECONSOLIDATE_IDLE_FRAMES`] re-bakes into one blob per vertex cap and the
+//! fragments retire after [`RETIRE_FRAMES`]. A straddler whose owner tile unloads is re-owned by
+//! a loaded referrer (`handoff_straddlers`) and re-diverts under it.
 //!
-//! The assembler diverts every ADT-doodad batch that is fully static (the bracket's anim
-//! exclusions), **order-free** (`Opaque`/`AlphaTest`, not additive: 0858's law that authored
-//! draw order exists only on transparent-pass batches) and not an interior-slot prop, into
-//! this buffer; the flush bakes each `(owner tile, 133⅓-yd cell, material)` group into ONE
-//! mesh entity with placement transforms baked into the vertices. **The fader lane (lane 2)
-//! is dev-opt-in only (`WOW_MERGE_FADERS=1`, decision 1423)**: each vertex carries its
-//! placement's fade sphere ([`benilla_assets::ATTRIBUTE_WOW_FADE_SPHERE`]) and
-//! `wow_model.wgsl`'s `WOW_MERGED_FADE` lane computes the faithful fade curve per vertex —
-//! alpha in-shader, `Hidden` as a clip-space collapse at zero — on the BLEND TWIN permanently
-//! (1420), the reference's own fading render state. The lane is correct per PIXEL but wrong
-//! per PHASE: one transparent draw with one sort key spanning a cell of depths, depth-write
-//! on, depth-kills per-entity faders behind its translucent pixels whenever the cell's sort
-//! centre lands beyond them (the director's popping lamppost — 1422 shrank the class,
-//! 1423 pulled the lane; the sort-near re-entry design is 1423's follow-up).
-//!
-//! The cell key preserves the frustum-cull locality the bracket's round 1 proved load-bearing
-//! (+1.38 without it, −0.93 with); the owner tile buys the weld's whole lifetime story — the
-//! blob lands in `TileState::merged` and despawns with its tile.
-//!
-//! **WMO group geometry never diverts (1418's verdict):** `batch_order` is a `MatKey` axis, so
-//! every WMO batch already owns a unique material handle — under the correct
-//! `(uid, group, material)` key the measured merge is EXACTLY 1:1, zero rows saved. The WMO
-//! share of the frame belongs to option B's cross-material retained draw, not to any
-//! entity-level lane. [`MergeSite::Wmo`] survives only to feed the census predictor.
-//!
-//! The close rule is the weld's (1369), not the bracket's wall clock: vertex cap + idle-frame
-//! tail — [`MERGE_IDLE_FRAMES`] (a quarter second) in settled play, ONE quiet frame under the
-//! arrival cover, where the settle release waits on the backlog (`merge_pending` is a
-//! `presentable()` term) and a fixed tail would push every world entry longer for nothing.
-//! Play-streaming then RE-CONSOLIDATES: distance admission trickles a cell's doodads in over
-//! the whole approach, gapped in seconds, so in-play closes shred a cell into fragments
-//! (Goldshire: 214/445 singleton blobs — 1421's census; its "1-frame tail" attribution was a
-//! misread, the in-play tail was already ¼ s and no sane tail bridges an approach). Fragments
-//! spawn fast — appearance latency is the tail's job — and once a cell's key has been quiet
-//! for [`RECONSOLIDATE_IDLE_FRAMES`] its fragments re-bake into one blob per vertex cap and
-//! the originals retire after an upload cushion ([`RETIRE_FRAMES`]).
-//! Dead-owner accumulators are discarded, and the whole buffer clears on map drop for the same
-//! tile-keys-repeat-across-maps reason the weld's does.
-//!
-//! The straddler gap (1417's lifecycle §) is CLOSED: when an owner tile unloads out from under
-//! a placement a loaded neighbour still references, `handoff_straddlers` (terrain_stream.rs)
-//! re-owns the placement to that referrer and queues a respawn, so its batches re-divert here
-//! under the new owner — and its hulls re-weld, closing 1369's matching collider gap whenever
-//! the merge is on.
+//! WMO group geometry never diverts: `batch_order` is a `MatKey` axis, so each WMO batch owns its
+//! material and a merge saves nothing ([`MergeSite::Wmo`] feeds only the census predictor).
 
 use std::collections::HashMap;
 use std::sync::Arc;
@@ -71,56 +31,36 @@ use crate::mesh_tag::alpha_bits;
 use crate::model_render::{ModelKind, ModelPart};
 use crate::wmo_portal::WmoGroupVis;
 
-/// Vertex cap per blob: bounds any one bake + upload, and keeps a blob's cull bound a
-/// neighbourhood rather than a zone (the weld's `WELD_MAX_TRIS` argument, in render units). A
-/// single oversized batch closes its blob immediately, same as an oversized hull.
+/// Vertex cap per blob: bounds one bake and upload and keeps the cull bound a neighbourhood.
 const MERGE_MAX_VERTS: usize = 65_536;
 
-/// Quiet frames that close a live accumulator in settled play — a quarter second, because a
-/// budget-paced burst's gaps are frames, not seconds. Under the arrival cover ONE quiet frame
-/// closes it instead: the settle release waits on the merge backlog, and a fixed tail would
-/// push every world entry longer for nothing (the weld's exact rule — its comment owns the
-/// reasoning).
+/// Quiet frames (a quarter second) that close an accumulator in settled play; under the arrival
+/// cover one quiet frame does, since the settle release waits on the backlog.
 const MERGE_IDLE_FRAMES: u32 = 15;
 
-/// Quiet frames before a settled cell's fragments re-bake into one blob (~3 s at 60 Hz): long
-/// enough that the approach's distance-admission trickle has moved past the cell, short enough
-/// that the fragment population stays transient. This is why the in-play tail can stay a
-/// quarter second: fast appearance first, consolidation once the cell goes quiet.
+/// Quiet frames (~3 s at 60 Hz) before a settled cell's fragments re-bake into one blob.
 const RECONSOLIDATE_IDLE_FRAMES: u32 = 180;
 
-/// Frames a replaced fragment keeps drawing after its consolidated successor spawns — the
-/// successor's mesh-upload cushion. The merged lanes are order-free (`Opaque`/`AlphaTest`), so
-/// the overlap double-draw is invisible; a gap instead (a despawn before the upload lands)
-/// would flicker the cell off, the exact defect class the 1421–1423 hunt closed.
+/// Frames a replaced fragment keeps drawing while its successor's mesh uploads: the overlap is
+/// invisible on order-free batches, where a gap would flicker the cell off.
 const RETIRE_FRAMES: u32 = 10;
 
-/// The doodad spatial cell, ¼ of an ADT tile — the retired `WOW_MEGA_STATIC` bracket's measured
-/// 133⅓-yd locality key. Its round 1 grouped by material alone and LOST (+1.38 cpu_ms at SW,
-/// drawn 400 → ~830): one blob per material spans the whole streamed scene, so its Aabb defeats
-/// the frustum cull and every blob's full vertex load encodes every frame. The cell restores
-/// locality; the distinct-material count (~5.6k at SW) remains the blob-count floor either way —
-/// the census finding that per-material merging alone cannot reach the few-hundred-row regime
-/// (decision 1413).
+/// The doodad spatial cell, ¼ of an ADT tile (133⅓ yd), so a blob's bound stays local enough for
+/// the frustum cull.
 const CELL: f32 = 533.333_3 / 4.0;
 
-/// One accumulating blob: shared geometry + placement transforms + per-placement fade
-/// spheres (index-parallel with `parts`), baked at flush.
+/// One accumulating blob; every list is index-parallel with `parts`.
 struct MergeAcc {
     parts: Vec<(Arc<RenderSubmesh>, Transform)>,
-    /// Each part's placement identity (index-parallel with `parts`) — what the pick names when
-    /// the cursor lands on this blob (decision 1534). Shared per placement, so a merged cell of
-    /// 300 trees holds 300 refcount bumps, not 300 strings.
+    /// Each part's placement identity, which the pick names.
     objects: Vec<Arc<crate::interact::WorldObject>>,
     spheres: Vec<Vec4>,
-    /// Interior-prop accs only (index-parallel with `parts`): each part's SH-probe slot, baked
-    /// per vertex at flush. Empty on every other lane — homogeneous per key by construction,
-    /// because the interior flag is a material axis and the material is in the key.
+    /// Each part's SH-probe slot, interior props only.
     slots: Vec<u32>,
     verts: usize,
     blend: ModelBlend,
     kind: ModelKind,
-    /// [`StaticMerge::frame`] at the last append — the idle clock.
+    /// [`StaticMerge::frame`] at the last append: the idle clock.
     last_add: u32,
 }
 
@@ -141,8 +81,7 @@ impl MergeAcc {
     }
 }
 
-/// One blob bake's input — an accumulator's view at close, or a re-consolidated cell's
-/// concatenation. Index-parallel slices; `slots` is empty on every non-interior lane.
+/// One blob bake's input as index-parallel slices: a closed accumulator or a re-consolidated cell.
 struct BlobSource<'a> {
     parts: &'a [(Arc<RenderSubmesh>, Transform)],
     objects: &'a [Arc<crate::interact::WorldObject>],
@@ -152,22 +91,18 @@ struct BlobSource<'a> {
     kind: ModelKind,
 }
 
-/// Where a diverted batch belongs — built once per placement by the spawn driver, consumed per
-/// batch by the assembler's divert.
+/// Where a diverted batch belongs, built once per placement by the spawn driver.
 pub enum MergeSite<'a> {
     /// An ADT map doodad: owned by its first-registering tile (the weld's ownership).
     Doodad { owner: (i32, i32) },
-    /// WMO group geometry: owned by its placement; `groups` is the asset's per-submesh group
-    /// index table (index-parallel with the submeshes the assembler iterates).
+    /// WMO group geometry: `groups` is the asset's per-submesh group index table.
     Wmo {
         uid: u32,
         groups: &'a [u16],
         portal_gated: bool,
     },
-    /// A WMO doodad prop (1418 lane 3): owned by its placement, keyed by the referrer-set of
-    /// rooms that name it (`groups` — the blob takes the same set-valued `WmoGroupVis` its
-    /// members carried) and, for an interior prop, carrying the per-prop SH-probe slot the
-    /// bake writes per vertex.
+    /// A WMO doodad prop: owned by its placement, keyed by the set of rooms that name it
+    /// (`groups`, the blob's `WmoGroupVis`) and, indoors, carrying its SH-probe slot.
     Prop {
         uid: u32,
         groups: &'a Arc<[u16]>,
@@ -176,9 +111,8 @@ pub enum MergeSite<'a> {
 }
 
 impl MergeSite<'_> {
-    /// The would-be merge key of one batch under this site, hashed — the census's blob-count
-    /// predictor (each lane's expected blob count = distinct keys in its class). Every site's
-    /// key here mirrors its real divert key exactly.
+    /// One batch's would-be merge key, hashed, for the census's blob-count predictor; it must
+    /// mirror the real divert key.
     pub fn census_key(
         &self,
         batch_idx: usize,
@@ -206,7 +140,7 @@ impl MergeSite<'_> {
     }
 }
 
-/// (owner tile, 133⅓-yd cell, material) — a doodad blob's identity.
+/// A doodad blob's identity: (owner tile, 133⅓-yd cell, material).
 type DoodadKey = ((i32, i32), (i32, i32), Handle<WowModelMaterial>);
 
 /// One spawned doodad blob retained with its bake input, so a shredded cell can re-bake.
@@ -218,46 +152,40 @@ struct SettledBlob {
     verts: usize,
 }
 
-/// A key's spawned blobs — the re-consolidation ledger's entry. `dirty` arms one evaluation
-/// after the next quiet window; a declined evaluation (nothing to win under the cap) does not
-/// re-run until a new fragment lands.
+/// A key's spawned blobs. `dirty` arms one re-consolidation check after the next quiet window; a
+/// declined one waits for a new fragment.
 struct SettledCell {
     blobs: Vec<SettledBlob>,
     blend: ModelBlend,
     kind: ModelKind,
-    /// [`StaticMerge::frame`] at the last fragment spawn — the quiet clock.
+    /// [`StaticMerge::frame`] at the last fragment spawn: the quiet clock.
     last_add: u32,
     dirty: bool,
 }
 
-/// A replaced fragment drawing out its successor's upload cushion (see [`RETIRE_FRAMES`]).
+/// A replaced fragment drawing out its successor's upload cushion ([`RETIRE_FRAMES`]).
 struct Retiring {
     entity: Entity,
     owner: (i32, i32),
     /// [`StaticMerge::frame`] when the successor spawned.
     since: u32,
 }
-/// (placement uid, referrer-set, material) — a prop blob's identity. The `Arc<[u16]>` hashes
-/// by CONTENT, so two props named by the same rooms share a blob and distinct sets never can.
+/// A prop blob's identity: (placement uid, room set, material); the `Arc<[u16]>` hashes by content.
 type PropKey = (u32, Arc<[u16]>, Handle<WowModelMaterial>);
 
-/// The in-flight merge accumulators. Same lifecycle discipline as [`super::weld::HullWelds`]:
-/// fed by the spawn chain, drained one chain-step later, cleared with the world it describes.
+/// The in-flight merge accumulators, fed by the spawn chain and cleared with the world.
 #[derive(Resource, Default)]
 pub struct StaticMerge {
-    /// Flush-system tick, the idle clock. Wrapping u32 — only ever read as a difference.
+    /// Flush-system tick, the idle clock; wrapping, read only as a difference.
     frame: u32,
     doodads: HashMap<DoodadKey, MergeAcc>,
     props: HashMap<PropKey, MergeAcc>,
-    /// Spawned doodad blobs retained per key with their bake inputs — the re-consolidation
-    /// ledger (see the module header: play-streaming's distance admission shreds a cell).
+    /// Spawned doodad blobs per key with their bake inputs, for re-consolidation.
     settled: HashMap<DoodadKey, SettledCell>,
     /// Replaced fragments still drawing out their successor's upload cushion.
     retiring: Vec<Retiring>,
-    /// Running totals since the last drain report (1417's VRAM honesty line): blobs spawned,
-    /// batches baked into them, vertices BAKED (every placement a copy) vs the vertices the
-    /// members' SHARED assets hold (each distinct geometry once — Arc identity), so the log
-    /// states the duplication factor the desk estimate guessed at ~3×.
+    /// Totals since the last drain report: blobs, batches, and baked vertices (a copy per
+    /// placement) against the shared assets' vertices (each geometry once).
     blobs: u64,
     batches: u64,
     baked_verts: u64,
@@ -266,21 +194,16 @@ pub struct StaticMerge {
     reported: bool,
 }
 
-/// Is the consolidation armed? Read once; the assembler divert and the flush both key on it.
-/// **ON by default** (1426: both recorded blockers closed — 1424 fragmentation, 1425 straddler
-/// handoff — and the director's eye passed lanes 1+3 at both pins). `WOW_STATIC_MERGE=0` is
-/// the opt-out lever; `=1` still reads as an explicit on for anything that predates the flip.
+/// Whether the consolidation is armed, read once: on unless `WOW_STATIC_MERGE=0`.
 pub fn merge_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_STATIC_MERGE").as_deref() != Ok("0"))
 }
 
 impl StaticMerge {
-    /// Take one mergeable batch into its accumulator. `fade_sphere` = the placement's world
-    /// fade center + radius, baked per vertex at flush (a never-fader carries its true radius
-    /// and the shader's `> 7` arm pins it opaque). `false` = this site never merges (WMO group
-    /// geometry and props — 1418's verdict / the referrer-set key) — the caller spawns the
-    /// batch individually, the fail-open arm.
+    /// Takes one mergeable batch into its accumulator. `fade_sphere` is the placement's world fade
+    /// centre and radius, baked per vertex (a never-fader's true radius hits the shader's `> 7`
+    /// opaque arm). `false` for WMO group geometry, which the caller spawns individually.
     pub(super) fn divert(
         &mut self,
         site: &MergeSite<'_>,
@@ -330,13 +253,11 @@ impl StaticMerge {
                 if let Some(slot) = slot {
                     acc.slots.push(u32::from(*slot));
                 }
-                // The material's interior axis makes a key all-interior or all-exterior; a
-                // ragged slot list would misindex the per-vertex bake, so it is a hard error.
+                // A key is all interior or all exterior; a ragged slot list misindexes the bake.
                 debug_assert!(acc.slots.is_empty() || acc.slots.len() == acc.parts.len() + 1);
                 acc
             }
-            // WMO group geometry never merges: measured 1:1 under its correct key (1418 —
-            // batch_order rides MatKey). The site exists for the census predictor.
+            // WMO group geometry never merges: each batch owns its material. Census only.
             MergeSite::Wmo { .. } => return false,
         };
         acc.spheres.push(fade_sphere);
@@ -356,9 +277,7 @@ impl StaticMerge {
         true
     }
 
-    /// Accumulators not yet baked — the reveal gate's term (`WorldLoadProgress::merge_pending`;
-    /// the weld's `unflushed` argument, on the render side). An overcount only delays a
-    /// release, never wrongs one.
+    /// Accumulators not yet baked, the reveal gate's `merge_pending`; an overcount only delays.
     pub(super) fn unflushed(&self) -> usize {
         self.doodads.len() + self.props.len()
     }
@@ -377,13 +296,9 @@ impl StaticMerge {
     }
 }
 
-/// Close ready accumulators into blob entities and hand each to its owner tile
-/// (`TileState::merged` — despawned with the tile, like the welds). A dead owner discards its
-/// accumulator: spawning a blob nothing owns is a leak (the weld's rule, and its reachability
-/// argument — the owner died past the unload line).
-///
-/// Runs in the Stream chain right after `flush_hull_welds`, for the weld's own reason: the
-/// frame's appends see the flush at a deterministic point and the owner lookups race nothing.
+/// Closes ready accumulators into blobs owned by their tile (`TileState::merged`) or placement,
+/// re-consolidates quiet cells and retires replaced fragments; a dead owner's accumulator is
+/// discarded. Runs in the Stream chain right after `flush_hull_welds`.
 pub(super) fn flush_static_merge(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,
@@ -412,8 +327,7 @@ pub(super) fn flush_static_merge(
             blobs += 1;
             let entity = spawn_blob(&mut commands, &mut meshes, &key.2, acc.source(), None, true);
             tile.merged.push(entity);
-            // Retain the bake input: a later admission wave under this key makes the cell a
-            // re-consolidation candidate once it goes quiet.
+            // Keep the bake input for a later re-consolidation.
             let cell = settled.entry(key.clone()).or_insert_with(|| SettledCell {
                 blobs: Vec::new(),
                 blend: acc.blend,
@@ -441,9 +355,8 @@ pub(super) fn flush_static_merge(
             return true;
         }
         blobs += 1;
-        // The blob takes exactly the vis/tagging its members had (spawn/mod.rs's prop site):
-        // the set-valued `WmoGroupVis` + `ExteriorScene` when the building has an instance and
-        // rooms name the prop; untagged otherwise (no key ⇒ no exemption possible — 0784).
+        // The members' tagging: `WmoGroupVis` and `ExteriorScene` when the building has an
+        // instance and rooms name the prop, untagged otherwise.
         let vis = (!key.1.is_empty())
             .then_some(p.portal_instance)
             .flatten()
@@ -462,10 +375,8 @@ pub(super) fn flush_static_merge(
         ));
         false
     });
-    // Re-consolidate settled cells (the module header owns the why): once a key has been quiet
-    // for the window and holds two or more fragments, re-bake them into one blob per vertex cap
-    // and retire the originals after the upload cushion. First-fit over whole fragments; only a
-    // strictly smaller shape is worth the churn.
+    // Re-consolidate quiet cells: first-fit whole fragments under the vertex cap, only when that
+    // makes strictly fewer blobs.
     let mut recon = (0u64, 0usize, 0usize); // (cells, fragments before, blobs after)
     {
         let StaticMerge {
@@ -551,8 +462,7 @@ pub(super) fn flush_static_merge(
             recon.0, recon.1, recon.2
         );
     }
-    // Retire replaced fragments once the successor's upload cushion has passed. A dead owner
-    // already despawned the entity with its tile — drop the record without touching it.
+    // Retire fragments past the cushion; a dead owner already despawned them with its tile.
     merge.retiring.retain(|r| {
         if frame.wrapping_sub(r.since) < RETIRE_FRAMES {
             return true;
@@ -567,13 +477,10 @@ pub(super) fn flush_static_merge(
     if blobs > 0 {
         merge.reported = false;
     }
-    // Publish the backlog for the reveal gate (this system sits in the Stream chain, so the
-    // consumers read this frame's depth — the weld's publish discipline).
     if let Some(progress) = progress.as_mut() {
         progress.merge_pending = merge.unflushed();
     }
-    // The drain report (1417's VRAM honesty line), once per settled wave: what the merge took
-    // and what the transform-baking duplication actually costs against the shared assets.
+    // The drain report, once per settled wave: what baking duplicates against the shared assets.
     if !merge.reported && merge.doodads.is_empty() && merge.props.is_empty() {
         merge.reported = true;
         debug!(
@@ -587,28 +494,16 @@ pub(super) fn flush_static_merge(
     }
 }
 
-/// `WOW_MERGE_FADERS=1` — the fader lane (lane 2) is OPT-IN dev-only since decision 1423:
-/// a fader blob is one transparent draw with ONE sort key covering a 133⅓-yd cell of content
-/// at DIFFERENT depths, drawn with the twin's faithful depth-write — and whenever the cell's
-/// sort centre lands beyond a per-entity fader, the blob draws first and its translucent
-/// pixels depth-kill the entity behind them (the director's popping lamppost; 1422's
-/// centre-sort only shrank the class, it cannot eliminate it). Under the default merge
-/// faders spawn per-entity — the configuration the director's eye passed. 1423's recorded
-/// re-entry (sort-near on a blob twin) was REFUTED before build (1428): the blob's
-/// opaque-intent pixels ride the same near-sorted transparent draw and erase any
-/// non-depth-writing card in front of them, O(1) and permanent. Lane 2 stays parked; the
-/// question folds into option B's retained draw, which bins opaque-intent content properly
-/// by construction.
+/// `WOW_MERGE_FADERS=1` merges fading doodads too (dev only). A fader blob is one transparent draw
+/// with one sort key over a cell of depths, and its depth write hides any per-entity fader it
+/// sorts ahead of, so by default faders spawn per entity.
 pub(crate) fn merge_faders_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_MERGE_FADERS").is_some())
 }
 
-/// `WOW_BLOB_VIS=1` — dump every merged blob's live visibility verdict every 2 s, plus any
-/// entity whose `WorldObject::id` is listed in `WOW_BLOB_VIS_UID` (comma-separated). The
-/// instrument for a "this popped in/out" report: run parked at the report's two points and
-/// diff which row flips (`vis`/`inh`/`view`), which separates a positional cull flip from a
-/// temporal one (a live pipeline compile, a late bake).
+/// `WOW_BLOB_VIS=1` prints every merged blob's visibility verdicts every 2 s, plus any entity
+/// whose `WorldObject::id` is in `WOW_BLOB_VIS_UID` (comma-separated).
 pub(crate) fn blob_vis_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_BLOB_VIS").is_some())
@@ -665,17 +560,9 @@ pub(crate) fn log_blob_vis(
     }
 }
 
-/// One blob bake (a closed accumulator, or a re-consolidated cell's chunk) → one blob entity
-/// carrying exactly what its members carried minus
-/// the per-placement machinery the shader lane now owns (1418): no `DoodadFade` (the baked
-/// fade spheres drive `WOW_MERGED_FADE`; `MeshTag` stays at opaque), `ExteriorScene` (every
-/// member had it), the union `Aabb` (authored: `NoAutoAabb`).
-///
-/// Its pick declaration is a [`PickBlob`], not a `PickMesh`: the baked mesh is the union of
-/// every member, so casting against it would answer "static-merge", which is what this blob's
-/// `WorldObject` said and why 1418's "nameable, not pickable" was a real loss of the inspector
-/// over merged content (decision 1534). The members carry the placement identities, and the
-/// entity keeps the broad phase and the drawn test it always had.
+/// Spawns one blob entity: no `DoodadFade` (the baked fade spheres drive `WOW_MERGED_FADE` and
+/// `MeshTag` stays opaque), the union `Aabb` under `NoAutoAabb`, and a `PickBlob` so a pick names
+/// the member placement it hits rather than the blob.
 fn spawn_blob(
     commands: &mut Commands,
     meshes: &mut Assets<Mesh>,
@@ -693,14 +580,11 @@ fn spawn_blob(
         kind,
     } = src;
     let n = parts.len();
-    // `center` is the blob's world position and therefore its TRANSPARENT-PHASE SORT KEY (the
-    // mesh is baked blob-local around it — decision 1422). On `Transform::IDENTITY` a fader
-    // blob sorted at the world origin: drawn first among all transparent content, its
-    // depth-write killing every transparent entity behind its translucent pixels.
+    // `center` is the blob's transparent sort key (the mesh is baked around it); at the world
+    // origin a fader blob would sort first and hide what is behind it.
     let (mesh, mn, mx, center) =
         merged_static_mesh_faded(parts, spheres, (!slots.is_empty()).then_some(slots));
-    // An interior blob's tag keeps the members' INTERIOR_FOG staging bit (the slot half of the
-    // payload is dead under WOW_MERGED_SLOT — the vertices carry it).
+    // An interior blob's tag keeps the INTERIOR_FOG bit; the vertices carry the slot.
     let tag = if slots.is_empty() {
         alpha_bits(1.0)
     } else {
@@ -714,8 +598,7 @@ fn spawn_blob(
         MeshTag(tag),
         Aabb::from_min_max(mn, mx),
         NoAutoAabb,
-        // The blob's own identity is the DRAW's, not a placement's — the members answer the
-        // pick, and this is only what a query for the blob entity itself reads.
+        // The draw's own identity; the members answer the pick.
         WorldObject {
             kind,
             label: "static-merge".into(),
@@ -787,7 +670,7 @@ mod tests {
         }
     }
 
-    /// A test placement identity — every divert carries one (decision 1534).
+    /// A test placement identity; every divert carries one.
     fn object() -> Arc<crate::interact::WorldObject> {
         Arc::new(crate::interact::WorldObject {
             kind: ModelKind::Doodad,
@@ -812,8 +695,6 @@ mod tests {
         ));
     }
 
-    /// Two doodads in the same cell on the same material accumulate into ONE blob; a third in
-    /// a different cell opens a second accumulator (the locality key round 1 proved out).
     #[test]
     fn cell_key_partitions_doodad_accumulators() {
         let mut merge = StaticMerge::default();
@@ -830,8 +711,6 @@ mod tests {
         assert_eq!(joint.spheres.len(), 2);
     }
 
-    /// WMO group geometry never diverts (1418's 1:1 verdict) — the site exists for the census
-    /// predictor only.
     #[test]
     fn wmo_site_refuses_the_divert() {
         let mut merge = StaticMerge::default();
@@ -869,8 +748,6 @@ mod tests {
         }
     }
 
-    /// An interior-prop blob (1418 lane 3) lands in its placement's entity list carrying the
-    /// set-valued room key, the per-vertex probe slots, and the INTERIOR_FOG-staged tag.
     #[test]
     fn interior_prop_blob_carries_rooms_and_baked_slots() {
         let mut app = test_app();
@@ -911,7 +788,7 @@ mod tests {
         let vis = app.world().get::<WmoGroupVis>(blob).unwrap();
         assert_eq!(vis.instance, instance);
         assert_eq!(&*vis.groups, &[3, 5]);
-        // The tag keeps the interior-fog staging bit with the slot half dead (probe 0).
+        // The tag keeps the interior-fog bit; its slot half is dead (probe 0).
         let tag = app.world().get::<MeshTag>(blob).unwrap();
         assert_eq!(tag.0, crate::mesh_tag::probe_bits(0));
         let mesh3d = app.world().get::<Mesh3d>(blob).unwrap().0.clone();
@@ -926,8 +803,7 @@ mod tests {
         }
     }
 
-    /// An EXTERIOR prop blob (no slots) bakes no slot attribute, and a prop no room names
-    /// takes no vis key and no exterior tag (the untagged-not-gated-blind rule, 0784).
+    /// An exterior prop blob bakes no slot attribute; one no room names takes no vis key or tag.
     #[test]
     fn exterior_and_unnamed_prop_blobs_stay_plain() {
         let mut app = test_app();
@@ -974,8 +850,6 @@ mod tests {
         assert!(mesh.attribute(ATTRIBUTE_WOW_FADE_SPHERE).is_some());
     }
 
-    /// The idle tail closes a quiet doodad accumulator into a blob owned by its tile, with the
-    /// authored bound, the per-vertex fade spheres, and no per-entity fade enrollment.
     #[test]
     fn idle_tail_closes_a_doodad_blob_onto_its_tile() {
         let mut app = test_app();
@@ -1005,7 +879,7 @@ mod tests {
             .world()
             .get::<crate::model_fade::DoodadFade>(blob)
             .is_none());
-        // The baked mesh carries one fade sphere per vertex — the WOW_MERGED_FADE contract.
+        // One fade sphere per vertex: the `WOW_MERGED_FADE` contract.
         let mesh3d = app.world().get::<Mesh3d>(blob).unwrap().0.clone();
         let meshes = app.world().resource::<Assets<Mesh>>();
         let mesh = meshes.get(&mesh3d).unwrap();
@@ -1013,7 +887,6 @@ mod tests {
         assert_eq!(spheres.len(), 3);
     }
 
-    /// A dead owner discards the accumulator — no blob, no leak (the weld's rule).
     #[test]
     fn dead_owner_discards_the_accumulator() {
         let mut app = test_app();
@@ -1045,8 +918,6 @@ mod tests {
             .clone()
     }
 
-    /// Play-streaming's admission trickle closes a cell in fragments; once the key goes quiet
-    /// they re-bake into ONE blob, the originals drawing out the upload cushion before retiring.
     #[test]
     fn a_settled_cell_reconsolidates_its_fragments() {
         let mut app = test_app();
@@ -1090,7 +961,7 @@ mod tests {
                 "a retired fragment must despawn"
             );
         }
-        // The consolidated mesh carries both placements — per-vertex fade spheres for 3+3 verts.
+        // Both placements' fade spheres, 3 + 3 vertices.
         let mesh3d = app.world().get::<Mesh3d>(after[0]).unwrap().0.clone();
         let meshes = app.world().resource::<Assets<Mesh>>();
         let spheres = meshes
@@ -1101,8 +972,7 @@ mod tests {
         assert_eq!(spheres.len(), 6);
     }
 
-    /// Two fragments already at the vertex cap re-bake into the same count — no win, so the
-    /// evaluation declines, keeps the originals, and does not run again until a new fragment.
+    /// Two fragments at the vertex cap cannot shrink, so the originals stay.
     #[test]
     fn reconsolidation_declines_when_the_cap_leaves_no_win() {
         let mut app = test_app();
@@ -1118,7 +988,7 @@ mod tests {
                 Vec3::ZERO,
                 MERGE_MAX_VERTS,
             );
-            // The cap closes each immediately — two fragments under one key.
+            // The cap closes each at once: two fragments under one key.
             flush_n(&mut app, 1);
         }
         let fragments = tile_merged(&app, (0, 0));
@@ -1131,8 +1001,7 @@ mod tests {
         );
     }
 
-    /// A dead owner drops its settled ledger without touching entities — the tile's own unload
-    /// despawned them, and a second despawn would be a bug.
+    /// The tile's own unload despawned the entities, so the ledger drops without touching them.
     #[test]
     fn a_dead_owner_drops_the_settled_ledger() {
         let mut app = test_app();
@@ -1157,7 +1026,6 @@ mod tests {
         assert!(app.world().resource::<StaticMerge>().settled.is_empty());
     }
 
-    /// The vertex cap closes an accumulator without waiting for the idle tail.
     #[test]
     fn vert_cap_closes_immediately() {
         let mut app = test_app();
diff --git a/crates/benilla-world/src/terrain_stream/queries.rs b/crates/benilla-world/src/terrain_stream/queries.rs
index 0079ad9a..68f79d28 100644
--- a/crates/benilla-world/src/terrain_stream/queries.rs
+++ b/crates/benilla-world/src/terrain_stream/queries.rs
@@ -1,6 +1,5 @@
-//! What the streamed world answers about a position: the spawn-time MCSH ground-shade lookup,
-//! the ground-effect/height queries the sound + clutter systems make against resident tiles, and
-//! the area authority (the `AreaTable.dbc` leaf under the player's feet, decision 0070).
+//! What the streamed world answers about a position: MCSH ground shade, ground effect, terrain
+//! height, and the area authority (the `AreaTable.dbc` leaf under the player's feet).
 
 use benilla_assets::coords::bevy_to_wow;
 use benilla_assets::AdtTile;
@@ -9,49 +8,28 @@ use bevy::prelude::*;
 
 use super::TerrainStreamer;
 
-/// The `AreaTable.dbc` id under the player's feet — the zone/subzone, from the containing
-/// resident chunk's MCNK `areaId` (decision 0070: drives zone music/ambience/reverb; later the
-/// minimap zone text). `None` until the ground tile is resident (or off-terrain). Written each
-/// frame by [`update_current_area`]; consumers change-detect on the inner value.
-///
-/// **It is scoped to the character session, not to the process** (decision 2130). It goes back to
-/// `None` the moment there is no avatar to measure from, so "we have not answered yet" is never
-/// spelled the same way as "here is the character before this one".
+/// The `AreaTable.dbc` id under the player's feet, written by [`update_current_area`]. `None` until
+/// the ground tile is resident, and again whenever there is no avatar: it lives with the character
+/// session, not the process.
 #[derive(Resource, Default, PartialEq, Eq)]
 pub struct CurrentArea(pub Option<u32>);
 
-/// Ordering handle on [`update_current_area`] — the leaf-authority write. The zone-text feed
-/// (`crate::area`) orders after it (which itself orders after the interior claim), so leaf +
-/// indoor bit + names always come from one coherent frame — the client's single-pass resolve.
-///
-/// **Every consumer that ACTS on the area belongs after it**, and the zone-channel walk is the
-/// case that proves it (decision 2130): unordered, it read whatever the previous frame had
-/// published and paid for the difference in `CMSG_JOIN_CHANNEL`/`CMSG_LEAVE_CHANNEL` traffic for
-/// zones the player was never in.
+/// The set of [`update_current_area`]. Every consumer that acts on the area orders after it, so
+/// leaf, indoor bit and names come from one frame (the reference resolves them in one pass).
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct AreaAuthoritySet;
 
 /// Outcome of the spawn-time MCSH ground-shade lookup.
 pub enum ShadeResolve {
-    /// The shade is known: `true` = the doodad's base sits on MCSH-shadowed terrain (sun ×0.5 in the
-    /// lobe), `false` = lit (×2.5, or a deliberate fallback when the ground tile isn't resident).
+    /// `true`: the base sits on MCSH-shadowed terrain; `false`: lit, or no loaded ground tile.
     Ready(bool),
-    /// The doodad's own ground tile is requested but hasn't decoded yet — defer the spawn one frame so a
-    /// straddling tree isn't baked lit before its true tile lands.
+    /// The ground tile is still decoding: defer the spawn a frame rather than bake it lit.
     Pending,
 }
 
-/// Resolve a doodad's terrain ground-shade the reference way: a GLOBAL world-position → tile → chunk
-/// MCSH lookup at the doodad's origin (the client's `0x69b350`), NOT a sample of whichever tile happened
-/// to register the placement — the latter is load-order/timing dependent and left straddling trees wrongly
-/// lit. `bevy_pos` is the doodad's origin (its `Transform.translation`).
-///
-/// - Ground tile resident + decoded → the true MCSH bit under the footprint.
-/// - Ground tile requested but still decoding → [`ShadeResolve::Pending`] (caller defers the spawn).
-/// - Ground tile not in the loaded set (a doodad straddling in from just beyond the ring) → `Ready(false)`:
-///   show it lit rather than hide it, matching the reference (a null tile reads lit until it streams in).
-///   (A doodad whose origin tile is *requested but never decodes* — a missing map-edge ADT — would defer
-///   indefinitely; that can't arise for a real placement, whose origin always lies in an existing tile.)
+/// A doodad's ground shade by a global position → tile → chunk MCSH lookup at its origin (the
+/// reference's `0x69b350`), not a sample of the tile that registered it. A tile outside the loaded
+/// set reads lit, as the reference's null tile does.
 pub fn doodad_ground_shade(
     streamer: &TerrainStreamer,
     adt_tiles: &Assets<AdtTile>,
@@ -68,13 +46,8 @@ pub fn doodad_ground_shade(
     }
 }
 
-/// The MCNK `areaId` under a **Bevy-space** position on the resident terrain — the OUTDOOR leg of
-/// the client's `GetAreaID 0x670250`, for any unit rather than the player.
-///
-/// [`CurrentArea`] is the player's authority and races a WMO interior claim ahead of this
-/// ([`update_current_area`]); there is no per-unit equivalent of that claim, so a caller asking
-/// about a *remote* unit gets the terrain answer alone. `None` off-terrain / mid-stream, and an
-/// `areaId` of 0 (unassigned in the data) reads as a miss, same as the player's resolver.
+/// The MCNK `areaId` under a Bevy-space position: the outdoor leg of the reference's `GetAreaID`
+/// (`0x670250`), for any unit, with no interior claim. An `areaId` of 0 (unassigned) is a miss.
 pub fn area_id_under(
     streamer: &TerrainStreamer,
     adt_tiles: &Assets<AdtTile>,
@@ -87,10 +60,7 @@ pub fn area_id_under(
     benilla_formats::area_id_at(&adt.chunks, wow).filter(|&id| id != 0)
 }
 
-/// The `GroundEffectTexture` id under a **Bevy-space** position on the resident terrain — the
-/// footstep terrain-type source (decision 0070 slice 3; the same global position→tile→chunk
-/// lookup shape as [`doodad_ground_shade`]). `None` off-terrain / mid-stream / no-effect cell —
-/// the footstep resolver falls back to its Dirt default.
+/// The `GroundEffectTexture` id under a Bevy-space position, the footstep terrain type.
 pub fn ground_effect_under(
     streamer: &TerrainStreamer,
     adt_tiles: &Assets<AdtTile>,
@@ -103,15 +73,10 @@ pub fn ground_effect_under(
     benilla_formats::ground_effect_at(&adt.chunks, wow)
 }
 
-/// The terrain surface height (raw WoW `z`) under a **Bevy-space** position on the resident terrain —
-/// the terrain leg of the client's down-ray arbitration (`FUN_006821f0`'s `0x69c320` probe, and the
-/// identical one in `GetAreaID 0x670250`), which races the WMO probe and wins the column whenever the
-/// ground is strictly nearer under the eye. Same global position→tile→chunk lookup shape as
-/// [`ground_effect_under`].
-///
-/// `None` means **no terrain surface in this column**, which the race must read as "no terrain hit",
-/// never as "ground at 0": off the streamed ring, mid-decode, or — the load-bearing case — the column
-/// falls in an MCNK hole, the cut-out through which a mine or cave entrance reaches its WMO interior.
+/// The terrain height (WoW `z`) under a Bevy-space position: the terrain leg of the reference's
+/// down-ray arbitration (`0x6821f0`'s `0x69c320` probe, also in `GetAreaID` `0x670250`), which
+/// wins the column when the ground is strictly nearer than the WMO. `None` is no terrain in the
+/// column (off the ring, decoding, or an MCNK hole over a cave mouth), never ground at 0.
 pub fn terrain_height_under(
     streamer: &TerrainStreamer,
     adt_tiles: &Assets<AdtTile>,
@@ -120,9 +85,7 @@ pub fn terrain_height_under(
     terrain_height_under_cached(streamer, adt_tiles, bevy_pos, &mut None)
 }
 
-/// [`terrain_height_under`] for a caller that asks many columns of the same tile in one go —
-/// the sun-flare march asks ~96 a frame along two rays (decision 1979): the tile resolution
-/// (a streamer map lookup and an asset lookup) is done once per tile change, not per column.
+/// [`terrain_height_under`] for many columns at once: the tile resolves once per tile change.
 pub fn terrain_height_under_cached<'a>(
     streamer: &TerrainStreamer,
     adt_tiles: &'a Assets<AdtTile>,
@@ -144,15 +107,10 @@ pub fn terrain_height_under_cached<'a>(
     benilla_formats::terrain_height_at(&adt.chunks, wow)
 }
 
-/// Track the `AreaTable` id under the player's feet. Faithful to the client's GetAreaID resolver
-/// (wow-re 0x670250): a WMO interior takes precedence over the terrain chunk when the down-ray
-/// keeps the WMO nearer — [`CurrentAreaInterior`] is exactly that player-position **faces-only**
-/// down-ray (wow-re `zonetext-indoor-bit.md`; the portal-legged render seed flipped in the abbey
-/// yard), so an indoor city (Ironforge, Undercity) reports its OWN area via
-/// `WMOAreaTable.AreaTableID` rather than the enclosing zone's terrain. Outdoors (no interior
-/// claim, or a group with no area row) it falls to the containing chunk's MCNK `areaId`. Holds
-/// the previous value while the tile is still decoding, so a tile-edge crossing never flickers
-/// through `None`.
+/// Tracks the `AreaTable` id under the player's feet as the reference's `GetAreaID` (`0x670250`)
+/// does: a WMO interior wins when the faces-only down-ray (`0x6a8a20`) finds it nearer, by its
+/// `WMOAreaTable.AreaTableID`; outdoors it is the chunk's MCNK `areaId`. Holds the last value
+/// while a tile decodes.
 pub(super) fn update_current_area(
     mut area: ResMut<CurrentArea>,
     focus: Res<crate::terrain_stream::ViewFocus>,
@@ -162,32 +120,17 @@ pub(super) fn update_current_area(
     wmo_areas: Option<Res<crate::wmo_portal::WmoAreas>>,
 ) {
     let Some(wow) = focus.body_pos() else {
-        // **No avatar — and the authority DIES with the character session** (decision 2130).
-        //
-        // The hold below is a within-session convenience (a tile-edge crossing must not flicker
-        // through `None`). Holding across the *session* boundary is a different thing entirely:
-        // this resource had exactly one writer, which only ever assigned `Some`, so once set it
-        // could never return to `None` for the life of the process — and the next character's
-        // login read the PREVIOUS character's zone until their own tiles decoded. The zone-channel
-        // walk believed it and joined `General - Stormwind City` for a character standing in the
-        // Eastern Plaguelands, then left it again a beat later; `sound/mod.rs`'s `world_audio_live`
-        // already carried a hand-written guard against the same staleness, which is the tell that
-        // the defect was the lifetime and not either consumer.
-        //
-        // `body_pos()` is `Some` only for a live avatar (`ViewFocus::body`/`detached`) and `None`
-        // for both glue-screen focuses, so this is the session edge without a state transition to
-        // subscribe to. A recoverable disconnect keeps the body as the local puppet (0065), so the
-        // area correctly survives one.
+        // No avatar: the area dies with the character session, or the next login reads this
+        // character's zone. `body_pos()` is `None` at both glue screens; a recoverable disconnect
+        // keeps the body, and the area with it.
         if area.0.is_some() {
             *area = CurrentArea(None);
         }
         return;
     };
     if !focus.body_settled() {
-        // …and one whose own world is still arriving has no area worth publishing: the leaf under
-        // it is not yet the leaf it is standing in. Hold the last real answer instead — the
-        // reference is behind a loading screen for exactly this window
-        // ([`ViewFocus::body_settled`], 1287).
+        // A body whose world is still arriving holds the last answer: the reference is behind a
+        // loading screen for this window.
         return;
     }
     // WMO interior first: the player's down-ray group resolved to its WMOAreaTable world area.
@@ -217,8 +160,7 @@ mod tests {
     use super::*;
     use bevy::ecs::system::RunSystemOnce;
 
-    /// A world with every resource [`update_current_area`] reads, and no terrain at all — so the
-    /// only thing under test is what the system does about the *body*, not what it finds under one.
+    /// Every resource [`update_current_area`] reads, and no terrain.
     fn bare_world() -> World {
         let mut w = World::new();
         w.init_resource::<CurrentArea>();
@@ -229,14 +171,6 @@ mod tests {
         w
     }
 
-    /// **The area authority dies with the character session** (decision 2130).
-    ///
-    /// It had exactly one writer, which only ever assigned `Some`, and nothing reset it — so once
-    /// a character had published a zone it stayed published for the life of the *process*. The
-    /// next login read it before its own tiles decoded, and the zone-channel walk turned that into
-    /// `CMSG_JOIN_CHANNEL` for the previous character's capital: the director logged into a
-    /// character in the Eastern Plaguelands and watched Stormwind City's three channels join and
-    /// then leave again.
     #[test]
     fn no_avatar_means_no_area() {
         let mut w = bare_world();
@@ -254,7 +188,7 @@ mod tests {
              tile-edge/flicker guard, and it stays"
         );
 
-        // …and then logged out. `ViewFocus` carries no body at either glue screen.
+        // …then logged out: no body at either glue screen.
         w.insert_resource(crate::terrain_stream::ViewFocus::camera());
         w.run_system_once(update_current_area).unwrap();
         assert_eq!(
@@ -264,7 +198,7 @@ mod tests {
              NEXT character's login reading THIS character's zone"
         );
 
-        // And the entry-window focus (decision 0777) is the same: a picked row is not a body.
+        // And the entry-window focus is the same: a picked row is not a body.
         w.insert_resource(CurrentArea(Some(1519)));
         w.insert_resource(crate::terrain_stream::ViewFocus::entry(
             0,
@@ -274,9 +208,7 @@ mod tests {
         assert_eq!(w.resource::<CurrentArea>().0, None);
     }
 
-    /// A **recoverable** disconnect keeps the avatar as the local puppet (0065), so the area must
-    /// survive one: nothing about the world under the player's feet changed when the socket died.
-    /// This is why the clear hangs off "is there a body" rather than off the net session.
+    /// A recoverable disconnect keeps the avatar as the local puppet, and with it the area.
     #[test]
     fn a_body_that_survives_a_drop_keeps_its_area() {
         let mut w = bare_world();
diff --git a/crates/benilla-world/src/terrain_stream/spawn/assemble.rs b/crates/benilla-world/src/terrain_stream/spawn/assemble.rs
index 898e5b7f..0691ba19 100644
--- a/crates/benilla-world/src/terrain_stream/spawn/assemble.rs
+++ b/crates/benilla-world/src/terrain_stream/spawn/assemble.rs
@@ -1,8 +1,4 @@
-//! The placed-model assembler: [`spawn_model_entities`] builds a model's submesh entities with the
-//! full doodad/WMO component set (production materials, fade, mesh tags, the doodad anim host and
-//! its skinned twins). Two consumers — the terrain streamer's world-static placements
-//! ([`super::spawn_loaded_placements`]) and the WMO-display gameobject's doodad props
-//! (`crate::entities`' `wmo_props`).
+//! Builds a placed model's submesh entities: materials, fade, mesh tags and the doodad anim host.
 
 use std::sync::Arc;
 
@@ -22,34 +18,21 @@ use crate::model_render::{model_material, MaterialCache, ShadeSel};
 use crate::model_render::{ModelKind, ModelPart};
 use benilla_assets::materials::{TorchBinds, WowModelMaterial};
 
-/// What one placement's animation host armed, for the consumers that spawn alongside its submeshes.
-/// All fields are *per placement*, not per model: the anchors are this instance's, and `arm` is
-/// this instance's own anim root, whose live player names the sequence it is currently playing.
+/// What one placement's anim host armed, for the fx spawned beside its submeshes.
 pub struct PlacementHost {
-    /// `(bone, anchor)` — the consumer anchors this placement minted (decision 1365): one entity
-    /// per bone something actually rides, registered in the host's `RigPose` (its compose passes
-    /// re-seat them) and pre-minted here for every emitter and ribbon bone the model authors, so
-    /// the fx spawns that run after the pose buffer is attached only look entities up.
+    /// `(bone, anchor)` for each bone something rides, every emitter and ribbon bone minted before
+    /// the pose buffer attaches.
     anchors: Vec<(u16, Entity)>,
-    /// This placement's anim-root entity. It rides the returned entity list so it despawns with the
-    /// placement, but it is **not geometry** — a caller tagging "everything this placement draws"
-    /// has to be able to leave it out, or it lands in a cull that can only fail open on a boundless
-    /// entity (decision 0784). Distinct from `arm`, which is `None` unless a sequence was armed.
+    /// The anim root, despawned with the placement but not geometry: a caller tagging what the
+    /// placement draws leaves it out.
     pub(crate) root: Entity,
-    /// The anim-root entity IF this placement armed a sequence; `None` on the gseq-only tier, where
-    /// nothing was armed and slot 0 is the honest answer.
-    ///
-    /// This used to be the armed slot as a plain `usize`, captured once at spawn. That was right
-    /// only while a placed doodad kept one variation for life — it re-rolls every play-window
-    /// (decision 0768), so a captured slot goes stale within about a second and the consumer has to
-    /// resolve against the live player instead.
+    /// The anim root if a sequence was armed, whose live player names the playing slot; `None` on
+    /// the gseq-only tier, which reads slot 0.
     pub arm: Option<Entity>,
 }
 
 impl PlacementHost {
-    /// The anchor standing in for `bone` — what `joints.get(bone)` used to answer. `None` = the
-    /// bone hosts nothing this placement consumes (or is outside the skeleton): the consumer
-    /// falls back exactly as it did on a missing joint.
+    /// The anchor for `bone`; `None` when nothing this placement spawns rides it.
     pub fn anchor(&self, bone: u16) -> Option<Entity> {
         self.anchors
             .iter()
@@ -60,28 +43,17 @@ impl PlacementHost {
 
 /// What [`spawn_model_entities`] spawned.
 pub struct SpawnedModel {
-    /// The caller's despawn list — everything this placement owns as world roots (anim host,
-    /// parts, world-root cards; owner-following cards manage their own lifecycle and stay out).
+    /// The despawn list: anim host, parts and world-root cards (a following card despawns itself).
     pub entities: Vec<Entity>,
-    /// Index-parallel with the `submeshes` slice: the entity each batch spawned, `None` where
-    /// no entity exists (a missing render form; historically also the retired `WOW_MEGA_STATIC`
-    /// bracket's divert). This exists
-    /// because POSITION IS A CONTRACT: the WMO path zips per-batch group indices against what
-    /// was spawned, and a skipped batch must hold its slot rather than shift every later batch
-    /// onto the wrong group — which is exactly what the bracket's bare `continue` did to the
-    /// surviving entities of a diverted building (found by 1417's constraint map).
+    /// Index-parallel with `submeshes`: each batch's entity, `None` where it diverted or had no
+    /// render form. The WMO path zips group indices against it, so a skipped batch holds its slot.
     pub by_batch: Vec<Option<Entity>>,
-    /// The anim host, when the model animates (see [`PlacementHost`]).
+    /// The anim host, when the model animates.
     pub host: Option<PlacementHost>,
 }
 
-/// Spawn a model's submeshes at `transform` with the full doodad/WMO component set. Returns the spawned
-/// entities (for refcounted despawn).
-///
-/// `pub(crate)`: two consumers — the terrain streamer's world-static placements here, and the
-/// WMO-display GameObject's doodad props ([`crate::entities`]'s `wmo_props`, the ship's sails), which
-/// pass a doodad-LOCAL `transform` + `card_owner` and parent the returned entities under the moving
-/// gameobject (every downstream system reads propagated `GlobalTransform`s, so the composition holds).
+/// Spawns a model's submeshes at `transform`. A transport's props pass a doodad-local `transform`
+/// and parent the result under the moving gameobject, as every reader uses `GlobalTransform`.
 pub fn spawn_model_entities(
     commands: &mut Commands,
     mat_cache: &mut MaterialCache,
@@ -90,113 +62,48 @@ pub fn spawn_model_entities(
     // MONKEY (torch shadows Phase 3A): the shared torch bindings, beside the light buffer.
     torch: &TorchBinds,
     submeshes: &[ModelSubmesh],
-    // The model's app-built render forms (decision 0834), index-parallel with `submeshes`: the
-    // static handle + its build-time `Aabb` per batch, and the skinned twins when this model's
-    // lane rigs (`None` otherwise). Callers gate on `ModelForms::require`, so by the time a
-    // placement spawns these are complete.
+    // Index-parallel with `submeshes`; complete, as callers gate on `ModelForms::require`.
     forms: crate::model_forms::FormSlices<'_>,
     transform: Transform,
-    // This placement's dev-instrument identity — model path, placement uniqueId, kind — shared
-    // by every batch it spawns. It is an INPUT rather than the blanket tag it used to be
-    // (`tag_world_object`, still applied to the returned entities) because a batch that DIVERTS
-    // spawns no entity to tag: the consolidating lanes carry this Arc into their own pick
-    // members instead, which is what keeps a merged or retained placement nameable (1534).
-    // `kind` also stands in for the old `is_wmo` flag — one source, so they cannot disagree.
+    // The placement's pick identity: a diverted batch spawns no entity, so its lane carries this.
     object: &Arc<crate::interact::WorldObject>,
-    // The static terrain-shade selector for every batch (the MCSH sample at this placement's base →
-    // `ShadeSel::Lit`/`Matte`/`Shaded`; see `model_render::ShadeSel`). Ignored by WMO group geometry
-    // and interior props (their lighting lanes don't read it).
+    // The MCSH terrain shade at the base; WMO group geometry and interior props ignore it.
     shade: ShadeSel,
-    // `Some(slot)` for an INTERIOR M2 prop: its folded SH probe's table slot, carried per-instance
-    // in `MeshTag` on EVERY batch of the model, billboard cards included (read by
-    // `wow_model.wgsl`'s interior-prop lane). Its ordinary batches are steady indoors; a card still
-    // distance-fades with its doodad, and the fade composes with the slot rather than clobbering it
-    // (decision 0778). `None` everywhere else (exterior props fade; WMO groups use their own
-    // per-submesh interior flag + batch class).
+    // An interior M2 prop's SH-probe slot, carried in `MeshTag` on every batch, cards included.
     interior_slot: Option<u16>,
-    // The placement's **draw-set gate** — its fade sphere plus, for a WMO prop, the building
-    // instance and the rooms that name it. `Some` on the world-static lanes, where the caller
-    // builds it ONCE ([`super::fx::emitter_fade`]) and hands the same value to every rider of the
-    // placement: the emitters, the ribbon trails, the glow lights — and, since 2059, the anim
-    // host, which used to fabricate its own with `instance: None, room: None` and so judged a
-    // particles-only WMO prop as exterior scene. Standing inside a sealed room that is
-    // `ExteriorGate::Windows([])`, which "admits nothing": every meshless prop of the building the
-    // camera was standing in was parked, its event track unscanned, and Stratholme's
-    // burning-building `$DSL` never fired.
-    //
-    // `None` on the entity-hosted lane (a transport's props), which carries no `EmitterFade` at
-    // all on purpose — a mover has no baked world point for one to measure from
-    // (`benilla_app::entities::wmo_props`). The bare sphere below is what its mesh lane needs, and
-    // `radius` is read for exactly that: in the `Some` arm the gate carries its own and this
-    // parameter is never consulted again.
+    // The placement's draw-set gate, shared with its emitters, ribbons, lights and anim host: a
+    // meshless prop's only verdict. `None` on the entity-hosted lane, as a mover has no baked
+    // world point to measure from; the mesh lane then builds a bare sphere from `radius`.
     fade: Option<&crate::particles::EmitterFade>,
     radius: f32,
     local_center: Vec3,
-    // The model's authored **all-animation** bound in Bevy model-local space
-    // ([`super::m2_anim_bound`]) — what an ANIMATED placement's submeshes are culled with instead of
-    // their bind-pose mesh bound, which the joint palette has left behind (decision 1259). `None` for
-    // WMO group geometry (no M2 header) and for a model with no authored box; a static placement
-    // ignores it and keeps the tighter per-batch bound.
+    // The all-animation box an animated placement is culled with; a static one ignores it.
     anim_bound: Option<Aabb>,
-    // `Some((model, now))` for an M2 placement: the doodad-animation gate (decision 0130) — an
-    // animated model spawns joints + the skinned twins; `now` is the clock origin. `None` for WMO
-    // group geometry.
+    // An M2 placement's model and anim clock origin; `None` for WMO group geometry.
     m2: Option<(&M2Model, f32)>,
-    // UV-animated material registry (decision 0130 phase 3): a batch with a `uv_anim` loop registers
-    // its material here so `tick_anim_materials` scrolls the shared offset while it is drawn.
     uv_reg: &mut crate::doodad_anim::UvAnimMaterials,
-    // Animated-tint material registry (the M2Color RGB twin of `uv_reg`): a batch with an
-    // `rgb_anim` loop registers its material here so `tick_anim_materials` re-samples the
-    // shared tint each frame.
     tint_reg: &mut crate::doodad_anim::TintAnimMaterials,
-    // The shared delta table both registries slot into (decision 1381) — registration allocates
-    // here and bakes the slot into the material.
     anim_table: &mut crate::mat_anim_table::MatAnimTable,
-    // **Is this placement a WMO doodad prop hanging off a streamed entity?** (The WMO-gameobject
-    // lane — a transport's deck cargo and cabin furniture.) It is the LANE, where `card_owner`
-    // below is only the anchor: that anchor is minted per placement and only when the model has
-    // billboard batches at all, so it answers "does this prop have cards to follow", never "which
-    // lane is this". Reading it as the lane is what left the marker below un-set on 133 of the
-    // ship's 134 props.
-    //
-    // What it decides here: [`crate::entity_shade::DoodadDefLit`] on every batch, which is the
-    // engine asserting its OWN invariant instead of trusting a caller to remember it (2047 — and
-    // 2041's lesson one level up). A prop's light is its `CMapDoodadDef`'s; it is under the net
-    // entity so it rides the deck, and the entity light node's descendant walk must pass it by.
+    // A WMO prop hosted on a streamed entity (a transport's cargo): every batch, cards included,
+    // then gets `DoodadDefLit`, as its light is its own `CMapDoodadDef`'s, not its host's. This
+    // is the lane; `card_owner` only says whether the prop has cards to follow.
     entity_hosted: bool,
-    // `Some(anchor)` for a prop spawned ON a streamed entity (the WMO-gameobject path): a boneless
-    // model's billboard cards FOLLOW this anchor (`BillboardCard::following` — the entity-path law,
-    // decision 0153) instead of baking a world pivot, so they track the moving owner and
-    // self-despawn with it; such cards are also excluded from the returned entity list (the caller
-    // parents that list, and a card is a world root the billboard pass writes absolutely).
-    // `None` for world-static placements (terrain), whose pivots never move.
+    // On a streamed entity, the anchor a boneless model's cards follow instead of a baked pivot;
+    // those cards stay world roots, out of the returned list.
     card_owner: Option<Entity>,
-    // `Some` on the world-static streamer paths lane 1 covers (ADT doodads + WMO group
-    // geometry): the production merge buffer and this placement's merge site (decision 1417,
-    // `WOW_STATIC_MERGE`). `None` on the WMO-prop and moving-gameobject paths.
+    // The merge buffer and this placement's site on the world-static lanes; `None` on a mover.
     mut merge: Option<(
         &mut super::super::merge::StaticMerge,
         super::super::merge::MergeSite<'_>,
     )>,
-    // `Some((collector, site))` on the world-static streamer paths the retained pass may
-    // take batches from (`WOW_STATIC_GX=1`, decisions 1429/1433; [`crate::static_gx`]):
-    // ADT doodads (slice 1, cell items by owner tile), WMO group geometry (slice 2, region
-    // items by portal-instance entity), and WMO props (B4, set-bucketed regions by the same
-    // instance). `None` on the moving-gameobject path, and on a prop path whose placement
-    // has no instance entity (no PVS identity — the site tallies those).
+    // The retained-pass collector and site on the world-static lanes; `None` on a mover and on a
+    // prop without an instance entity.
     mut staticgx: Option<(
         &mut crate::static_gx::StaticGx,
         crate::static_gx::GxSite<'_>,
     )>,
-    // Returns the spawned entities + the per-batch map + what the anim host armed for this
-    // placement, when the model animates: the joint set (bone-indexed) the emitter spawn rides
-    // its host bone off (0130 phase 4), and the FILE sequence slot its variation roll landed
-    // on, which the emitters' rate/gate tracks must be sampled against (decision 0760).
 ) -> SpawnedModel {
-    // One gate for this placement, from here down: the caller's when it has one, else the bare
-    // sphere (which is the same value `emitter_fade` would build from the same inputs — the
-    // constructor is shared, so the two arms cannot drift). Every `radius`/world-centre read below
-    // goes through it.
+    // The caller's gate, else the bare sphere; every radius or centre read below goes through it.
     let fade = match fade {
         Some(f) => f.clone(),
         None => {
@@ -206,16 +113,8 @@ pub fn spawn_model_entities(
     let kind = object.kind;
     let is_wmo = kind == ModelKind::Wmo;
     let mut out = Vec::with_capacity(submeshes.len());
-    // The doodad-animation host (decision 0130 phase 1): an animated model — most placed instances
-    // aren't, and stay on the static path below untouched — gets an anim-root + joint hierarchy +
-    // player/drive from [`crate::doodad_anim::spawn_anim_host`]; its ordinary submeshes then draw
-    // the skinned twin bound to those joints. Billboard batches keep today's camera-facing path
-    // (their transform is the billboard system's, and their glow-pulse already rides
-    // `BoneScaleAnim`). The host exists for every JOINT CONSUMER, not just skinned submeshes:
-    // emitters and ribbons ride their bone's joint too (0130 phase 4), so a particles-only model
-    // (0 render batches — the InstancePortal swirl, whose two emitters sit on the spinning rotor
-    // bones) still needs its joints driven. Only a model with nothing but billboard cards and no
-    // emitters/ribbons spawns no host.
+    // The anim host serves any joint consumer: a skinned part, an emitter or a ribbon. A model of
+    // billboard cards alone gets none, as the billboard system owns their transforms.
     let mut host = m2
         .filter(|(m, _)| {
             submeshes.iter().any(|s| s.billboard.is_none())
@@ -223,7 +122,7 @@ pub fn spawn_model_entities(
                 || !m.ribbons.is_empty()
         })
         .and_then(|(m, _)| crate::doodad_anim::spawn_anim_host(commands, m, transform));
-    // Captures freeze material-alpha clocks at 0 (deterministic frames) — read the env once.
+    // Captures freeze material-alpha clocks at 0, for deterministic frames.
     let mat_frozen = crate::dev_state::deterministic_run();
     let animated = host.is_some();
     let rig_root = host.as_ref().map(|h| h.root);
@@ -231,31 +130,14 @@ pub fn spawn_model_entities(
         out.push(h.root);
     }
     let mut skinned_meshes: Vec<Entity> = Vec::new();
-    // The parts the lazy-rig wake will promote static → skinned (decision 0863) — the ones that
-    // got a [`crate::doodad_anim::SkinnedTwin`] below.
+    // The parts with a `SkinnedTwin`, which the lazy rig's wake promotes to skinned.
     let mut lazy_parts: Vec<Entity> = Vec::new();
-    // The per-batch slot map (see [`SpawnedModel::by_batch`]) — every `continue` in the loop
-    // below leaves a `None` in place instead of shifting later batches.
+    // Every `continue` below leaves its batch's `None` in place.
     let mut by_batch: Vec<Option<Entity>> = vec![None; submeshes.len()];
-    // **Coplanar siblings ride ONE lane** — a batch whose M2 skin section is drawn by another
-    // batch of this same model never diverts into a consolidator, and neither does that sibling.
-    //
-    // Two batches naming one section rasterize the SAME triangles ([`RenderSubmesh::section`]): a
-    // base layer and the shine/reflect layer authored over it. The reference draws both from one
-    // vertex array under depth-write + LEQUAL, so the later batch wins that coplanar tie EXACTLY
-    // (wow-re `m2-depth-blend-state`). The consolidators exclude on per-batch facts — env-mapped
-    // UVs and the `0x10`/`0x08` depth flags (`static_gx::divert`), additive order (`merge`) — and a
-    // shine layer carries all of them, so the pair got split: base into the retained/merged lane,
-    // shine onto the entity path. Those two lanes reach the same world vertex by different
-    // arithmetic (the bake resolves it on the CPU in f64 and re-centres; the entity shader rotates
-    // it in f32 at local magnitude — `static_gx::bake`'s own note: "what remains against the entity
-    // path is the GPU's own rotate-at-local-magnitude rounding, which no bake can undercut"). A few
-    // ULPs is nothing between separate surfaces and everything between coplanar ones: the shine's
-    // reverse-Z GreaterEqual test against its own base becomes a per-pixel coin flip that re-rolls
-    // on every camera move — the ballista's bolt heads and shields dithering exactly the way B38's
-    // awning did (decision 0680). Keeping the section whole is the only place the two depths are
-    // equal by CONSTRUCTION; a depth bias would merely pick a winner for a tie we should never have
-    // created. It costs 264 sections across 221 world doodads (`m2_shared_section`).
+    // Coplanar siblings ride one lane: two batches naming one skin section draw the same
+    // triangles, which the reference draws from one vertex array under LEQUAL, so the later wins
+    // exactly (`0x70c190`). Split across lanes, the two reach each vertex by different float
+    // arithmetic and the depth test flickers, so neither diverts.
     let shared_geometry = shared_geometry(
         &submeshes
             .iter()
@@ -263,56 +145,26 @@ pub fn spawn_model_entities(
             .collect::<Vec<_>>(),
     );
     for (batch_idx, sub) in submeshes.iter().enumerate() {
-        // The batch's app-built render form (decision 0834). Callers gate spawning on the forms
-        // being complete, so a miss here is a broken contract — skip the batch rather than panic.
+        // A missing form is a broken caller contract: skip the batch rather than panic.
         let Some((stat_mesh, stat_aabb)) = forms.stat.get(batch_idx) else {
             continue;
         };
-        // Every batch (WMO and M2) carries its authored order (index + 1) into the material's
-        // transparent sort bias, so one model's coplanar layers draw in file order instead of
-        // re-flipping a sort tie every frame (`model_render::BATCH_ORDER_SORT_EPS`). WMO batches
-        // additionally ride it into the clip-z nudge that resolves coplanar layers in MOBA file
-        // order — the byte-verified client behaviour (wow-5875-re
-        // models/scratch/wmo-batch-blend-depth-state.md); `model_material` gates that half on
-        // `is_wmo`.
+        // The authored order biases the transparent sort, so coplanar layers draw in file order;
+        // a WMO batch also takes it into the clip-z nudge, as the reference draws MOBA batches in
+        // strict file order (`0x6b4f10`/`0x6b5190`).
         let batch_order = u16::try_from(batch_idx + 1).unwrap_or(u16::MAX);
         let interior = sub.interior || interior_slot.is_some();
-        // A billboard card is culled by the SAME rule as any other batch — its material's `0x04`
-        // flag, nothing else. This site used to force `|| sub.billboard.is_some()`, on the reasoning
-        // that a card whose plane normal points away from the viewer would backface-cull to nothing;
-        // that is precisely the mechanism the reference USES, and forcing it off is what drew the
-        // stray solid triangles beside working particle effects (decision 0629, bugs B05/B34).
-        // A billboard bone puts the model's +X toward the viewer, the cull is GL_BACK/CCW (wow-re
-        // `models.md` MOMT/M2 flag map, `m2-depth-blend-state.md` §0x04), so a −X-facing card is
-        // never seen — and an author who wanted one seen set `0x04` themselves: Elwynn's LampPost
-        // carries a two-sided −X card AND a single-sided +X glow card, one model, both rules.
+        // A billboard card culls by its `0x04` flag like any batch: the bone turns +X to the
+        // viewer and the cull is GL_BACK/CCW (`0x70c2b3`), so a −X card is meant to go unseen.
         let two_sided = sub.two_sided;
-        // A lit interior M2 prop submesh (not a WMO group): it carries its SH-probe slot in
-        // `MeshTag`, so the shader evaluates the room's probe instead of the sky base. **Billboard
-        // batches are included** — a chain or glow card is a batch of the same model, and the
-        // reference shades every batch of an object through one light node (decision 0778). They
-        // were excluded here on a since-stale worry that the distance fade would overwrite the
-        // slot: true before the 0355 re-lane, when the slot lived in the alpha bits, and false
-        // after it — the fade writes through `mesh_tag::with_alpha`, which composes with the slot
-        // (`debug_panel::visibility`). Excluding them left an interior card on an interior-mode
-        // material with NO slot in its tag, which the shader decodes as slot **0** — whichever
-        // probe won the streaming race, the same wrong-probe read the 0355 note below describes.
+        // An interior M2 prop's batches carry its SH-probe slot, cards included: the reference
+        // shades every batch of an object through one light node.
         let interior_probe = !is_wmo && interior_slot.is_some();
-        // …and the narrower half: only a NON-card interior prop is steady indoors. A card still
-        // distance-fades with its doodad (below — the halo must cull when the lamp does), so it
-        // keeps its fade twin and its `DoodadFade`.
+        // Only a non-card interior batch is steady; a card still fades with its lamp.
         let steady_interior_prop = interior_probe && sub.billboard.is_none();
-        // **Does this batch need a material of its own?** (decision 1408.) A batch whose UV or tint
-        // loop differs between sequences cannot share one: the registries are keyed by material,
-        // so a shared one has no instance to ask which sequence is playing — and these placements
-        // re-roll their variation independently every window (0768), so at any instant they are on
-        // different slots. Keying the material by this placement's anim host gives each its own
-        // registry entry, its own table row, and its own sequence. Everything else — every batch in
-        // the world but a measured 28 on this lane, 49 corpus-wide of 24103 (`uvslotscan`) — keeps
-        // the shared material it always had.
-        //
-        // No host ⇒ no sequence to read ⇒ share, and stay at the built seed: a per-sequence batch
-        // on a model the content gate declined is exactly today's frozen behaviour, not a new one.
+        // A batch whose UV or tint loop differs by sequence gets a material keyed by this
+        // placement's host, since placements re-roll their variations independently. Without a
+        // host it shares and stays at the built seed.
         let per_seq = sub.uv_seq.is_some() || sub.rgb_seq.is_some();
         let seq_owner = per_seq.then_some(rig_root).flatten();
         let cutout = model_material(
@@ -342,14 +194,9 @@ pub fn spawn_model_entities(
             torch,
             seq_owner,
         );
-        // The blend twin for the distance-fade feather pass (reuse the cutout when already blend, or when
-        // this is a non-fading interior prop). A MULTIPLY batch (Mod/Mod2x — the weapon-rack
-        // ARMORREFLECT sheen) also reuses its steady self: its blend equation reads no alpha, so
-        // no material swap can feather it — the fade rides the SOURCE COLOUR instead:
-        // `wow_model.wgsl` lerps a multiply batch's colour toward the blend identity by the tag
-        // alpha it already carries, which is the reference's own preset-5 mechanism (0865 built
-        // it as a deviation; 1489 re-lawed it byte-faithful), so the rack sheen rides the
-        // distance fade like everything else.
+        // The fade's blend twin, the cutout itself when already blended or never fading. A multiply
+        // batch (Mod, Mod2x) keeps its cutout too: it reads no alpha, so the shader fades its
+        // colour toward the blend identity, the reference's preset-5 mechanism.
         let blend = if steady_interior_prop
             || matches!(
                 sub.blend,
@@ -357,9 +204,7 @@ pub fn spawn_model_entities(
             ) {
             cutout.clone()
         } else {
-            // The SOURCE blend (Opaque or AlphaKey here) rides into the twin: fade_variant builds
-            // AlphaMode::Blend either way, and the source decides the twin's 224/255 cutout marker
-            // (only an AlphaKey source alpha-tests while fading — decision 0842).
+            // The source blend decides the twin's cutout: only AlphaKey alpha-tests while fading.
             model_material(
                 mat_cache,
                 materials,
@@ -388,9 +233,7 @@ pub fn spawn_model_entities(
                 seq_owner,
             )
         };
-        // The 1417 batch classification — ONE source for both the census tally and the
-        // production divert below, so the population the census prints and the population the
-        // merge takes can never drift apart.
+        // One classification for the census tally and the diverts, so the two cannot drift.
         let class = crate::static_merge::BatchClass {
             excluded: animated
                 || sub.billboard.is_some()
@@ -403,15 +246,9 @@ pub fn spawn_model_entities(
                 && !sub.additive,
             never_fade: fade.radius > crate::model_fade::NEVER_FADE_RADIUS,
         };
-        // A merged FADER blob lives permanently in the reference's own fading render state —
-        // the blend twin (blend on, cutout ref on unfaded alpha, depth-write forced on) — with
-        // per-vertex alpha; at fade 1.0 that state is pixel-identical to the steady cutout, so
-        // nothing changes while it is steady and the feather is the reference's smooth
-        // translucent ramp (1420, superseding 1419's ordered-dither erode, which quantized the
-        // ramp to 16 visible steps — the director's report). Never-faders keep the cutout and
-        // the opaque bins; a steady interior prop never fades at all, so it keeps the cutout
-        // AND bakes an infinite sphere (its members carry no `DoodadFade` — the merged path
-        // must not invent one).
+        // A merged fader stays in the reference's fading state, the blend twin with per-vertex
+        // alpha, which at fade 1.0 matches the cutout pixel for pixel. A steady interior prop
+        // keeps the cutout and an infinite sphere, as it carries no `DoodadFade`.
         let merge_mat = if class.never_fade || steady_interior_prop {
             &cutout
         } else {
@@ -428,23 +265,10 @@ pub fn spawn_model_entities(
                 .and_then(|(_, site)| site.census_key(batch_idx, merge_mat, &transform));
             crate::static_merge::tally(&class, is_wmo, sub.geometry.positions.len(), key);
         }
-        // The retained-pass divert (`WOW_STATIC_GX=1`, decisions 1429/1431/1433): an
-        // eligible order-free static batch leaves bevy_pbr entirely — no entity, no blob;
-        // `static_gx` draws it from retained buffers (per-cell for ADT doodads,
-        // per-instance group-bucketed for WMO group geometry — slice 2, per-instance
-        // set-bucketed for WMO props — B4). B2 admits DOODAD FADERS too: the batch rides
-        // in with its exile seed (the placement identity + handle clones of this exact
-        // bundle), and the scan respawns it through the entity path for the feather band.
-        // Checked BEFORE the merge divert (armed, this lane owns the populations lanes 1+3
-        // would have taken); a refused batch — the collector's own exclusions or a
-        // site/kind mismatch — falls through to the ordinary paths below, slot held like
-        // every other divert. Each site gates its own class: the doodad lane requires the
-        // seed for faders, the WMO lane is never-fade by construction (∞ radius), and the
-        // prop lane admits steady interior props + never-fade exterior props while an
-        // exterior FADER prop stays on the entity path (the exile protocol has no prop
-        // shape — that keep is today's default look) and is TALLIED, never silent.
-        // The census label for a batch that stays on the entity path (`EntityPathWhy`):
-        // refined below as each divert declines it.
+        // The retained-pass divert, tried before the merge: an eligible order-free batch leaves
+        // bevy_pbr for `static_gx`, a doodad fader with its fade seed so it can return as an entity
+        // inside its fade band. A refused batch falls through with its slot held; `why` is the
+        // census label for one left on the entity path.
         let mut why: &'static str = "gx-off";
         if let Some((gx, site)) = staticgx.as_mut() {
             let facts = if !crate::static_gx::enabled() {
@@ -480,9 +304,6 @@ pub fn spawn_model_entities(
                     crate::static_gx::GxSite::Doodad { owner }
                         if !is_wmo && class.merges() && !class.interior_prop =>
                     {
-                        // `fade_seed`, not `fade`: the placement's draw-set gate is in scope
-                        // here under that name, and shadowing it with the retained pass's
-                        // per-batch seed reads as the same thing twice.
                         let fade_seed = (!class.never_fade
                             && !crate::static_gx::fade_lane_disabled())
                         .then(|| crate::static_gx::GxFadeSeed {
@@ -493,9 +314,7 @@ pub fn spawn_model_entities(
                             cutout: cutout.clone(),
                             blend: blend.clone(),
                         });
-                        // Never-fade admits bare; a fader admits only WITH its seed (the
-                        // fade lane lever empties the seed, sending faders back to the
-                        // entity path).
+                        // A never-fader enters bare, a fader only with its seed.
                         (class.never_fade || fade_seed.is_some())
                             .then_some((*owner, None, None, fade_seed))
                     }
@@ -587,19 +406,14 @@ pub fn spawn_model_entities(
                 }
             }
         }
-        // The production consolidation divert (`WOW_STATIC_MERGE=1`, 1417/1418): an order-free
-        // static doodad batch — faders included, their fade rides the baked sphere through the
-        // shader's WOW_MERGED_FADE lane — merges into its site's blob instead of spawning. Its
-        // `by_batch` slot stays `None`; a refused divert (a WMO/prop site — 1418's verdict)
-        // falls through and spawns individually.
+        // The merge divert: an order-free static batch joins its site's blob, its slot left
+        // `None` and a fader's fade riding the baked sphere. WMO group geometry is refused.
         if let Some((merge, site)) = merge.as_mut() {
             if crate::terrain_stream::merge::merge_enabled()
                 && !shared_geometry[batch_idx]
                 && class.merges()
-                // The fader lane is OPT-IN (`WOW_MERGE_FADERS=1`, decision 1423): a fader —
-                // neither never-fade nor a steady interior prop — spawns per-entity by
-                // default; a cell-granular transparent draw with depth-write depth-kills
-                // per-entity faders behind its translucent pixels (the popping lamppost).
+                // Faders merge only under `WOW_MERGE_FADERS=1`: a fader blob's depth write hides
+                // the per-entity faders behind its translucent pixels.
                 && (class.never_fade
                     || steady_interior_prop
                     || crate::terrain_stream::merge::merge_faders_enabled())
@@ -618,13 +432,9 @@ pub fn spawn_model_entities(
                 continue;
             }
         }
-        // Register both variants' materials for the per-frame UV scroll (idempotent per material —
-        // every instance of the batch lands on the same deduped handle).
-        // A period-0 loop is a constant the material seed already wrote (`sample(0.0)` IS its
-        // forever value) — registering it would buy a per-frame re-write of the same number
-        // (1375), so only a real loop enters the registry.
-        // The per-placement lane first: its set replaces the shared loop outright, and it only
-        // arms when this placement actually has a host to read a sequence from.
+        // Register both materials for the UV scroll (idempotent per material). A per-sequence set
+        // replaces the shared loop when there is a host to read; a period-0 loop is a constant the
+        // seed already wrote, so it stays out.
         if let (Some(seqs), Some(host)) = (sub.uv_seq.as_ref(), seq_owner) {
             for id in [cutout.id(), blend.id()] {
                 crate::doodad_anim::register_uv(
@@ -649,8 +459,7 @@ pub fn spawn_model_entities(
                 );
             }
         }
-        // …and for the per-frame tint re-sample (the animated M2Color RGB, same shared clock —
-        // the same invisible seq-band phase divergence as the UV scroll, recorded there).
+        // Likewise for the animated M2Color RGB tint.
         if let (Some(seqs), Some(host)) = (sub.rgb_seq.as_ref(), seq_owner) {
             for id in [cutout.id(), blend.id()] {
                 crate::doodad_anim::register_tint(
@@ -675,33 +484,19 @@ pub fn spawn_model_entities(
                 );
             }
         }
-        // `MeshTag` is the per-instance lighting/fade scalar: an interior prop carries its SH-probe
-        // slot index here (the shader evaluates the folded probe instead of the sky base);
-        // everything else carries the distance-fade alpha (`1.0` = opaque, the no-fade default the
-        // fade system overwrites). The slot goes through the ONE typed constructor
-        // (`mesh_tag::probe_bits` — bits 16-29 since the 0355 re-lane): this site kept the old
-        // bits-0..=15 write through that re-lane, so every static interior prop read probe slot 0,
-        // taking whichever probe won the streaming race — the director's inn-doodad regression.
-        // ONE decision for "does this batch's payload carry a probe slot", read twice below —
-        // once for the tag's bits and once for the component that SAYS so
-        // ([`crate::mesh_tag::InteriorProbePayload`]). Two independent predicates could drift,
-        // and a reader that disagrees with the writer about which payload a part is on is
-        // exactly B373.
+        // `MeshTag`: an interior prop's probe slot through `mesh_tag::probe_bits`, else the fade
+        // alpha at 1.0. One predicate feeds both the tag and `InteriorProbePayload` below, so the
+        // payload's writer and readers cannot disagree.
         let probe_slot = interior_slot.filter(|_| interior_probe);
         let mesh_tag = match probe_slot {
             Some(slot) => MeshTag(crate::mesh_tag::probe_bits(slot)),
             None => MeshTag(alpha_bits(1.0)),
         };
-        // A billboard batch (glow card / chain) faces the camera each frame, so its transform is owned
-        // by the billboard system. It still distance-fades with its doodad (same `radius` band) — the
-        // fade only touches the material/`MeshTag`, not the transform — so the bright halo culls when the
-        // lamp does instead of hanging in the air far past it. The mesh is centred at the pivot, so the
-        // fade centre is `ZERO` (→ the entity's world translation = the pivot).
+        // A billboard card's transform is the billboard system's; it still fades with its doodad,
+        // from its pivot, where the mesh is centred (`ZERO`).
         let (entity, fade_center) = if let Some(info) = &sub.billboard {
-            // An animated doodad's card rides its billboard bone's live anchor (the swinging
-            // lamp's glow follows the swing — 0153 follow-up; the anchor frame bakes the pivot,
-            // the 0130 rig identity carried into the collapsed lane by 1365). A static doodad
-            // keeps the fixed placement-baked pivot.
+            // An animated doodad's card follows its billboard bone's anchor; a static one keeps
+            // the baked pivot.
             let card = match host.as_mut().and_then(|h| h.anchor(commands, info.bone)) {
                 Some(anchor) => BillboardCard::following_joint(info, anchor),
                 None => match card_owner {
@@ -718,29 +513,20 @@ pub fn spawn_model_entities(
                     blend: sub.blend,
                 },
                 crate::model_render::EntityPathWhy(why),
-                // The picker's triangles (decision 0857): the render forms are `RENDER_WORLD`-only,
-                // so the inspector/probe rays read the model's resident geometry. The caster
-                // centres a card at its pivot, the same bake the render form draws with.
+                // The picker's triangles, as the render forms are `RENDER_WORLD`-only.
                 crate::interact::PickMesh(sub.geometry.clone()),
                 mesh_tag,
                 card,
             ));
-            // The build-time Aabb, inserted explicitly: the static form is `RENDER_WORLD`-only,
-            // so Bevy's `calculate_bounds` can race extraction — and the exterior cull fails
-            // OPEN on a missing bound (0832's rule, extended to the model lane). `NoAutoAabb`
-            // says the bound is OURS: see the ordinary-part insert below for what derives it
-            // otherwise, and what that cost.
+            // The build-time Aabb, inserted here: `calculate_bounds` can race extraction of a
+            // `RENDER_WORLD` form, and the exterior cull fails open without a bound.
             if let Some(aabb) = stat_aabb {
                 card_entity.insert((*aabb, NoAutoAabb));
             }
             (card_entity.id(), Vec3::ZERO)
         } else {
-            // An animated doodad's ordinary submesh spawns on the STATIC form with its skinned
-            // twin waiting beside it (`SkinnedTwin`): the palette slot no longer exists at spawn
-            // — the draw gate allocates it at the placement's first wake and swaps the mesh in
-            // (decision 0863, `doodad_anim::lazy`). The twin comes from the app-built forms
-            // (0834); a lane that didn't request it (or a contract break) simply never promotes,
-            // rather than arm the picker with a joint-less "skinned" mesh.
+            // A part spawns static with its skinned twin beside it; the draw gate swaps the twin in
+            // at the placement's first wake. A part without a twin never promotes.
             let skinned_mesh = animated
                 .then(|| forms.skin.and_then(|s| s.get(batch_idx)).cloned())
                 .flatten();
@@ -753,28 +539,13 @@ pub fn spawn_model_entities(
                     blend: sub.blend,
                 },
                 crate::model_render::EntityPathWhy(why),
-                // The picker's triangles (decision 0857) — same rule as the card above.
                 crate::interact::PickMesh(sub.geometry.clone()),
                 mesh_tag,
             ));
-            // Every part now spawns static, so every part carries the build-time Aabb (the
-            // RENDER_WORLD rule above).
-            //
-            // For an ANIMATED placement that bind-pose bound is a lie, because the joints move the
-            // vertices while this entity's transform stays at the placement origin. Widen to the
-            // model's authored all-animation box (decision 1259) — the union, never the replacement,
-            // so the 152 corpus models whose authored box does not fully contain their own bind pose
-            // still bound their geometry. A billboard card is exempt: its entity transform FOLLOWS
-            // its joint every frame, so its own small bound travels with what it draws.
-            //
-            // **`NoAutoAabb` is what makes that bound survive** (decision 1261). Bevy's
-            // `calculate_bounds` runs TWO queries: one that inserts a bound where there is none,
-            // and one that **overwrites an existing bound** on `Changed<Mesh3d>`. The lazy rig
-            // swaps `Mesh3d` static → skinned at this placement's first draw-gate wake
-            // (`doodad_anim::lazy`), and the skinned twin shares the BIND-POSE geometry — so the
-            // second query recomputed the very box 1259 had just widened, and the birds went back
-            // to blinking a second after they streamed in. The bound here is authored, not derived;
-            // this component is how that is said.
+            // An animated placement's joints move the vertices away from the bind-pose bound, so
+            // it widens to the authored all-animation box; a card, which follows its joint, needs
+            // none. `NoAutoAabb` keeps the bound: `calculate_bounds` recomputes it on
+            // `Changed<Mesh3d>`, and the lazy rig swaps in a twin of bind-pose geometry.
             if let Some(aabb) =
                 cull_bound(stat_aabb.as_ref(), animated.then_some(anim_bound).flatten())
             {
@@ -792,43 +563,29 @@ pub fn spawn_model_entities(
                 commands
                     .entity(entity)
                     .insert(crate::rig_palette::RigPart(root));
-                // The draw-gate list is about visibility, not skinning — the bind-pose fallback
-                // part still represents the placement.
+                // The draw gate's list is about visibility, so a not-yet-skinned part counts.
                 skinned_meshes.push(entity);
             }
             (entity, local_center)
         };
         by_batch[batch_idx] = Some(entity);
-        // This batch's payload is a PROBE SLOT, said as a component so the exterior-payload
-        // writer can see it (`mesh_tag::InteriorProbePayload`). Cards included, for the same
-        // reason they carry the slot at all: they are batches of the same model, shaded through
-        // the same light node (0778) — and `entity_shade`'s card pass reaches a card by walking
-        // UP from its owner, a route its descendant-walk guard never covers.
+        // Says the payload is a probe slot, so the exterior-payload writer passes it by; cards too,
+        // as `entity_shade` reaches a card by walking up from its owner.
         if probe_slot.is_some() {
             commands
                 .entity(entity)
                 .insert(crate::mesh_tag::InteriorProbePayload);
         }
-        // …and, on the entity-hosted lane, that this batch's light is its own doodad def's rather
-        // than its host's. Asserted here rather than by the caller so the rule cannot be half
-        // applied: this is the site that knows about EVERY batch, cards included, and a card is
-        // exactly what the caller cannot reach (it is a world root kept out of the returned list,
-        // and the shade writer's card pass finds it by walking UP to the host).
+        // On the entity-hosted lane the batch is lit by its own doodad def, not its host; set
+        // here as only this site reaches every batch, cards included.
         if entity_hosted {
             commands
                 .entity(entity)
                 .insert(crate::entity_shade::DoodadDefLit);
         }
-        // Animated material alpha (decision 0130 phase 2): the rare batch whose colour-alpha/weight
-        // tracks animate (fire flicker) or constantly dim gets its per-instance sampler; the
-        // visibility authority composes the value into the render-alpha tag + the A ≤ 0 cull.
-        // Captures freeze the clock at 0 (deterministic frames). A lit interior prop composes the
-        // same way since the 0355 re-lane gave the probe-slot payload its own alpha field (bits
-        // 0..=15) — the 0130-era "partial alpha can't show on the colour payload" deferral is
-        // collected (bug B30: the Undercity lightshaft's authored 0.10/0.05 dimming).
-        // The scan marker (1375), same predicate as the registration above — so a marked row
-        // always has a registry key to match, and `tick_anim_materials` never has to visit an
-        // unmarked one.
+        // The scan marker, by the registration's own predicate, so `tick_anim_materials` visits
+        // only marked parts. A batch whose colour alpha animates or dims gets its own sampler,
+        // which the visibility authority composes into the tag and the A ≤ 0 cull.
         if sub.uv_anim.as_ref().is_some_and(|a| a.period > 0.0)
             || sub.rgb_anim.as_ref().is_some_and(|a| a.period > 0.0)
             || seq_owner.is_some()
@@ -846,8 +603,7 @@ pub fn spawn_model_entities(
                     mat_frozen,
                 ));
         }
-        // Distance fade for everything except a lit interior prop (whose `MeshTag` carries colour, and
-        // which is steady indoors). Adding `DoodadFade` is what makes the fade system drive the tag.
+        // `DoodadFade` lets the fade system drive the tag; a steady interior prop never fades.
         if !steady_interior_prop {
             commands.entity(entity).insert(DoodadFade {
                 radius: fade.radius,
@@ -856,21 +612,16 @@ pub fn spawn_model_entities(
                 blend,
             });
         }
-        // An entity-following card manages its own lifecycle (`face_billboards` despawns it with
-        // its owner) and must stay a world root — keep it out of the caller's parent/despawn list.
+        // A following card despawns with its owner and must stay a world root: keep it out.
         if sub.billboard.is_none() || card_owner.is_none() {
             out.push(entity);
         }
     }
-    // Arm the draw gate: animation runs iff any of these submeshes is drawn (`doodad_anim`) —
-    // or, for a meshless (particles-only) host, iff the placement's fade sphere is in the draw
-    // set (the same 0171 law its emitters gate on).
+    // Animation runs while a submesh is drawn or, for a meshless host, while its gate admits it.
     let arm = host.as_ref().and_then(|h| h.seq.map(|_| h.root));
     let placement_host = host.map(|mut h| {
         let now = m2.map(|(_, now)| now).unwrap_or_default();
-        // Pre-mint the fx consumers' anchors (decision 1365) while the pose buffer is still in
-        // hand: exactly the bones the model authors emitters/ribbons on, nothing speculative —
-        // the fx spawns that run after this only look the entities up ([`PlacementHost::anchor`]).
+        // Mint the emitter and ribbon bones' anchors while the pose buffer is in hand.
         if let Some((m, _)) = m2 {
             for bone in m
                 .emitters
@@ -883,25 +634,20 @@ pub fn spawn_model_entities(
         }
         commands.entity(h.root).insert(DoodadAnimHost {
             meshes: skinned_meshes,
-            // The caller's one gate, not a second construction of it (2059).
+            // The caller's gate itself, not a second construction of it.
             fade: fade.clone(),
             clip: h.clip,
             armed_at: now,
-            // Born already expired, so the first frame runs the holder setup's `variationIdx = -1`
-            // arm over the loader's var-0 seed — the reference's own two-stage load (decision 0768).
+            // Born expired, so frame one runs the holder's `variationIdx = -1` arm over the
+            // loader's var-0 seed, the reference's two-stage load.
             window_hi: f32::NEG_INFINITY,
             anim_id: h.anim_id,
-            // Born PARKED (decision 0863): the spawn frame's `Visibility` is the default-visible
-            // lie (the fade/cull authorities haven't classified the fresh parts yet), and the
-            // gate's promote requires a drawn frame ON TOP of `active` — so the first real
-            // verdict, not the spawn race, decides the slot. The gate flips this true the same
-            // first pass either way, so pose/resume semantics are unchanged.
+            // Born parked: the spawn frame's default `Visibility` is not yet a verdict, so the
+            // first real one decides the slot.
             active: false,
             parked_at: now,
         });
-        // The lazy palette rig (decision 0863): what the draw gate's first wake allocates and
-        // promotes. Only when the placement has skinnable parts at all — an emitter-only host
-        // (chimney smoke) never takes a slot, which under the eager design it wasted one on.
+        // The lazy rig, only with skinnable parts: an emitter-only host never takes a slot.
         if !lazy_parts.is_empty() {
             commands.entity(h.root).insert(crate::doodad_anim::LazyRig {
                 bones: h.bones(),
@@ -920,14 +666,9 @@ pub fn spawn_model_entities(
     }
 }
 
-/// The `Aabb` a placed submesh is culled with: its build-time bind-pose bound, widened by the
-/// model's authored all-animation box when this placement animates (decision 1259).
-///
-/// It is a **union**, not a swap, for one measured reason: 152 of the 9315 M2s that carry geometry
-/// author a header box that does not fully contain their own bind-pose vertices (worst case
-/// `Spells\Teleport.m2`, 19.9 yd short). The reference never notices — it tests the box's
-/// *circumsphere*, which swallows the shortfall — so a bare swap would be the one way this change
-/// could cull geometry the reference draws.
+/// A placed submesh's cull bound: the bind-pose bound, unioned with the authored all-animation box
+/// when animated. A union, as 152 of 9315 M2s author a box short of their own bind pose, which
+/// the reference's circumsphere test swallows.
 fn cull_bound(stat: Option<&Aabb>, anim: Option<Aabb>) -> Option<Aabb> {
     match (stat, anim) {
         (Some(s), Some(a)) => Some(Aabb::from_min_max(
@@ -939,13 +680,8 @@ fn cull_bound(stat: Option<&Aabb>, anim: Option<Aabb>) -> Option<Aabb> {
     }
 }
 
-/// Which batches share their triangles with another batch of the same model — the consolidator
-/// gate's predicate, over the batches' [`benilla_formats::RenderSubmesh::section`] indices in batch
-/// order. `true` at `i` means batch `i` names a section some other batch also names.
-///
-/// `None` (every WMO batch — no section concept) never shares: the WMO lanes keep their own
-/// MOBA-order law and are not what this closes. The list is a model's batch count long — tens at
-/// the very most — so the quadratic scan is cheaper than any map.
+/// Per batch, whether another batch of the model names the same skin section; a WMO batch (`None`)
+/// never shares. Quadratic, as a model has tens of batches at most.
 fn shared_geometry(sections: &[Option<u16>]) -> Vec<bool> {
     sections
         .iter()
@@ -957,10 +693,8 @@ fn shared_geometry(sections: &[Option<u16>]) -> Vec<bool> {
 mod tests {
     use super::*;
 
-    /// The bug's own numbers (`benilla-extract animboundscan`, `World\critter\birds\Bird01.m2`):
-    /// a 1.2 × 1.8 × 0.23 yd bind-pose box, and an authored all-animation box 67 × 18 × 7 yd that
-    /// reaches ~37 yd past it. Culled by the bind pose, the bird is dropped while its drawn
-    /// geometry is still on screen.
+    /// `World\critter\birds\Bird01.m2` (`benilla-extract animboundscan`): a 1.2 × 1.8 × 0.23 yd
+    /// bind-pose box and a 67 × 18 × 7 yd authored all-animation box.
     #[test]
     fn an_animated_placements_bound_covers_the_whole_flight_path() {
         // Bevy-space conversions of Bird01's two boxes (WoW (x,y,z) -> Bevy (-y, z, -x)).
@@ -973,18 +707,14 @@ mod tests {
             Vec3::new(13.571, 16.019, 36.605),
         );
         let widened = cull_bound(Some(&bind), Some(authored)).expect("a bound");
-        // Every corner of the authored box is inside the widened bound. `Aabb` stores
-        // centre/half-extents, so the reconstructed corners carry a float epsilon — hence the
-        // tolerance, which is ~7 orders of magnitude below anything a cull can see.
+        // `Aabb` stores centre and half-extents, so the rebuilt corners need a float tolerance.
         const EPS: f32 = 1e-4;
         assert!((widened.min() - EPS).cmple(authored.min()).all());
         assert!((widened.max() + EPS).cmpge(authored.max()).all());
-        // …and the bind-pose bound alone was ~37 yd short of it along the flight axis.
+        // The bind-pose bound alone is ~37 yd short along the flight axis.
         assert!(authored.max().z - bind.max().z > 36.0);
     }
 
-    /// The union arm, not a swap: an authored box that fails to contain the bind pose (152 corpus
-    /// models do) must not shrink the bound.
     #[test]
     fn a_short_authored_box_never_shrinks_the_bound() {
         let bind = Aabb::from_min_max(Vec3::splat(-5.0), Vec3::splat(5.0));
@@ -994,7 +724,6 @@ mod tests {
         assert!(Vec3::from(b.max()).abs_diff_eq(Vec3::new(40.0, 5.0, 5.0), 1e-4));
     }
 
-    /// A static placement is untouched — it keeps the tighter per-batch bind-pose bound.
     #[test]
     fn a_static_placement_keeps_its_per_batch_bound() {
         let bind = Aabb::from_min_max(Vec3::splat(-1.0), Vec3::splat(1.0));
@@ -1003,18 +732,14 @@ mod tests {
         assert!(Vec3::from(b.max()).abs_diff_eq(Vec3::splat(1.0), 1e-4));
     }
 
-    /// The ballista's own shape: section 10 drawn twice (base + shine) and section 4 drawn once.
-    /// Both members of the pair are flagged, not just the refusable one — the whole point is that
-    /// they travel together, so gating only the shine would leave the base in the retained lane
-    /// and the split exactly where it was.
+    /// The ballista's shape: section 10 drawn twice (base and shine), section 4 once.
     #[test]
     fn both_batches_of_a_shared_section_are_flagged() {
         let flags = shared_geometry(&[Some(4), Some(10), Some(10), Some(7)]);
         assert_eq!(flags, vec![false, true, true, false]);
     }
 
-    /// WMO batches carry no section, and `None == None` would otherwise make every WMO batch in a
-    /// group "shared" with every other — pulling the whole WMO population out of the retained lane.
+    /// WMO batches carry no section, and `None == None` must not count as sharing one.
     #[test]
     fn section_less_batches_never_share() {
         assert_eq!(shared_geometry(&[None, None, None]), vec![false; 3]);
diff --git a/crates/benilla-world/src/terrain_stream/spawn/fx.rs b/crates/benilla-world/src/terrain_stream/spawn/fx.rs
index 637ff272..7d398a7d 100644
--- a/crates/benilla-world/src/terrain_stream/spawn/fx.rs
+++ b/crates/benilla-world/src/terrain_stream/spawn/fx.rs
@@ -1,7 +1,4 @@
-//! Per-model light/particle dressing for placed models: the shared [`point_light`] recipe and the
-//! world-baked spawners the terrain path rides (M2/WMO point lights, particle emitters, ribbon
-//! trails). A transport prop takes the entity-owned shapes instead (`crate::entities`' `wmo_props`,
-//! decision 0474) — riding owners and prop-local children, never a world bake.
+//! A placed model's point lights, particle emitters and ribbon trails, baked at its placement.
 
 use benilla_assets::coords::{bevy_to_wow, wow_to_bevy};
 use benilla_assets::{ModelEmitter, ModelLight, WmoModel};
@@ -12,18 +9,11 @@ use bevy::prelude::*;
 use crate::lighting::WorldPointLight;
 use crate::particles;
 
-/// Light intensity for an M2 light of unit `diffuse_intensity`, in the units Bevy's `PointLight`
-/// used when it carried this (`linear_color × intensity/(4π)`), so `4π` makes the packer read exactly
-/// `diffuse_color × diffuse_intensity` — a clean, predictable base. `wow_model.wgsl` then applies the
-/// faithful WoW falloff `1/(0.7d+0.03d²)` (decision 0016). There is no gain dial any
-/// more: the 0273 `sh_c16.w` gain is retired and the commit is the reference's raw product
-/// (`global_light::commit_raw`).
+/// Unit intensity in the `PointLight` convention, which the packer's `/(4π)` undoes to exactly
+/// `diffuse_color × diffuse_intensity`; `wow_model.wgsl` applies the falloff `1/(0.7d + 0.03d²)`.
 const POINT_LIGHT_INTENSITY: f32 = 4.0 * std::f32::consts::PI;
-/// The packed per-light `range` (yd) — since 0285 this is the ≤3-nearest **selection-candidacy**
-/// radius around the receiving unit's anchor, not an evaluation cutoff (a committed GL light has
-/// none; the shader evaluates the selected lights at any distance, and att(48 yd) ≈ 0.01 is already
-/// invisible). Generous so a hall-scale WMO group whose center sits ~20 yd from its wall fixtures
-/// still gathers them — erring wide only ever admits negligible candidates.
+/// The ≤3-nearest selection radius (yd) around the lit unit's anchor, not a cutoff (a GL light has
+/// none; att(48 yd) ≈ 0.01), wide enough to reach a hall's fixtures ~20 yd from its centre.
 const POINT_LIGHT_RANGE: f32 = 48.0;
 /// MONKEY (wmo exterior points): how close an authored MOLT fixture has to stand to a prop's flame
 /// (yd) for that flame's SYNTHESISED light to be dropped as a duplicate. The vanilla convention is
@@ -32,16 +22,8 @@ const POINT_LIGHT_RANGE: f32 = 48.0;
 /// reaching the next prop along a street (Stormwind's street lamps are ≥ 8 yd apart).
 const MODD_SYNTH_DEDUPE: f32 = 2.5;
 
-/// The one [`WorldPointLight`] recipe for an authored WoW light source (M2 or WMO MOLT). The light only
-/// carries position + colour into the shared packed table; every lit surface — terrain, M2
-/// doodads/NPCs, and WMO walls/floors (decision 0273: the reference lights them all) — then selects
-/// its unit's ≤3 NEAREST from that table and applies the faithful falloff in-shader (decision 0285;
-/// the committed light is diffuse-only). `color` is the authored WoW RGB (linear, hue preserved);
-/// `intensity_scale` folds in the per-light authored intensity.
-///
-/// `pub(crate)`: the terrain path spawns it at a world-baked point below; a transport prop's light
-/// ([`crate::entities`]'s `wmo_props`) spawns it as a CHILD of the moving gameobject instead, so
-/// propagation carries the source with the hull.
+/// The [`WorldPointLight`] for an authored M2 or WMO MOLT light, `color` its linear RGB. As in the
+/// reference it lights terrain, M2s and WMO walls, each taking its unit's ≤3 nearest, diffuse only.
 pub fn point_light(color: [f32; 3], intensity_scale: f32) -> WorldPointLight {
     WorldPointLight {
         color,
@@ -50,16 +32,13 @@ pub fn point_light(color: [f32; 3], intensity_scale: f32) -> WorldPointLight {
     }
 }
 
-/// Spawn one [`WorldPointLight`] at `world` (Bevy space), appended to `out` so it rides the placement's
-/// lifecycle. The light recipe is [`point_light`].
 fn spawn_point_light(
     commands: &mut Commands,
     world: Vec3,
     color: [f32; 3],
     intensity_scale: f32,
-    // The rooms this source belongs to, for a light inside a building — `None` outdoors. A torch in
-    // a culled room is one the reference never instantiated, so it lights nothing
-    // ([`crate::lighting::LightRooms`], decision 0689).
+    // The light's rooms inside a building, `None` outdoors: a torch prop in a culled room is not
+    // in the reference's scene that frame, so it lights nothing.
     room: Option<crate::wmo_portal::WmoGroupVis>,
     // MONKEY (fire GO lights): tag a SYNTHESISED source so the packer can ride the live
     // `fireLightGain` cvar over it without respawning the world
@@ -673,40 +652,18 @@ pub(super) fn emitter_fade(
     }
 }
 
-/// Spawn a particle-emitter entity for each of a model's emitters at `transform`, appending them to
-/// `out` so they ride the placement's lifecycle (despawn when it streams out). Emitters with no
-/// resolved texture are skipped by [`particles::spawn_emitter`].
-///
-/// `host` is the placement's [`PlacementHost`] when it animates (0130 phase 4): each emitter then
-/// rides its host bone's ANCHOR (decision 1365 — the collapsed rig's stand-in for the joint,
-/// pre-minted by the assembler for exactly these bones) — the torch flame follows the flame-bone
-/// jiggle, the inn chandelier's candle flames swing with it. Riding is unconditional given a
-/// host: for a bone whose chain never animates the anchor holds its telescoped rest pivot, so
-/// `anchor · (position − pivot)` is byte-for-byte the static `placement · position` — no
-/// per-emitter classification needed.
-///
-/// `armed_seq` is the FILE sequence slot this placement's own arm rolled, and the emitters sample
-/// their rate/gate tracks against **that** slot. This site used to pass `EmitClock::Pinned` — slot 0,
-/// unconditionally — on the reasoning that a placed doodad arms once, so slot 0 is all it can ever
-/// play. The arm has rolled a frequency-weighted *variation* since 0130, so that stopped being true
-/// and nothing noticed: an emitter whose rate is keyed only in a later variation sampled a flat zero
-/// for ever and emitted nothing, on every placement, while still building, pooling and ticking.
-/// `benilla-extract partslotscan` counts **947** such emitters across **184** models; the one that
-/// surfaced it is the Blasted Lands lightning strike, whose whole burst lives in slot 1
-/// (decision 0760, bug B63).
+/// Spawns a model's emitters into `out`. With an anim `host` each rides its bone's anchor, which
+/// holds a bone that never animates at its rest pivot, so riding is exact for every emitter.
 pub(super) fn spawn_emitters_for(
     commands: &mut Commands,
     emitters: &[ModelEmitter],
     transform: Transform,
     host: Option<&super::assemble::PlacementHost>,
-    // The shared draw-set gate ([`emitter_fade`]), cloned onto every emitter this model spawns.
     fade: &particles::EmitterFade,
     out: &mut Vec<Entity>,
 ) {
     let arm = host.and_then(|h| h.arm);
     for em in emitters {
-        // Static placements (no anim host — the ~90% tier, and every capture) have no owner to
-        // follow; they despawn via the placement's entity list.
         let owner = host
             .and_then(|h| h.anchor(em.def.bone))
             .map(|a| (a, em.bone_pivot));
@@ -717,18 +674,14 @@ pub(super) fn spawn_emitters_for(
             particles::EmitterFrames {
                 owner,
                 anchor: None, // anchor at the placement: an animated bone never drags the cloud
-                // An animated doodad's rig goes when its placement unloads, and that IS this
-                // model being destroyed — free the pool with it, the same rule the WMO-prop lane
-                // beside this one already states (0826, missed here: a tile crossing left the
-                // brazier's flame draining at the old spot).
+                // An animated doodad's rig goes only when its placement unloads, the model's end,
+                // so the pool is freed rather than left draining at the old spot.
                 on_owner_loss: particles::OwnerLoss::Free,
                 ..default()
             },
-            // A placed doodad's arm is NOT one-time: it re-rolls its variation every play-window
-            // (decision 0768), so the emitters read the slot AND the clip time off the host's live
-            // player each frame — the same lane units and GameObjects use, and what the reference's
-            // `m2_animate` does for every model without distinction. A pinned slot was right only
-            // under the superseded "armed once at load" contract.
+            // A placed doodad re-rolls its variation every play window, so its emitters read the
+            // slot and clip time off the host's live player, as the reference's animate kernel
+            // (`0x714260`) does for every model.
             match arm {
                 Some(root) => particles::EmitClock::Host(root),
                 None => particles::EmitClock::Pinned,
@@ -740,21 +693,15 @@ pub(super) fn spawn_emitters_for(
     }
 }
 
-/// Spawn a ribbon trail for each of a model's ribbon emitters (wisp streamers, the Caverns-of-Time
-/// energy trails). A trail rides its host bone's anchor when the placement animates (same ride as
-/// [`spawn_emitters_for`]); a static placement's trail rides the first spawned submesh entity (its
-/// transform IS the placement). Trails self-despawn when their owner goes, so they don't join
-/// `out` — the placement's despawn cascades within a frame.
+/// Spawns a model's ribbon trails, each riding its host bone's anchor or, on a static placement,
+/// `fallback_owner`; a trail despawns with its owner, so none joins a despawn list.
 pub(super) fn spawn_ribbons_for(
     commands: &mut Commands,
     ribbons: &[benilla_assets::ModelRibbon],
     transform: Transform,
     host: Option<&super::assemble::PlacementHost>,
     fallback_owner: Option<Entity>,
-    // The SAME draw-set gate the quad clouds one function up are given ([`emitter_fade`]) — a trail
-    // is one of this model's emitters and is admitted by exactly the same five terms. It has to be
-    // carried explicitly because a trail rides a joint or a submesh, and neither of those states
-    // its owner model's fade sphere or its rooms ([`crate::ribbons::RibbonTrail::fade`]).
+    // The emitters' gate, carried because a joint or submesh owner states no fade sphere or rooms.
     fade: &particles::EmitterFade,
 ) {
     let arm = host.and_then(|h| h.arm);
@@ -766,9 +713,8 @@ pub(super) fn spawn_ribbons_for(
                 None => continue, // nothing to ride (an entity-less placement)
             },
         };
-        // The `+0xc0` enable gate reads the placement's live sequence, like its emitters one
-        // function up: an animated doodad re-rolls its variation every play window, so there is
-        // no arm-once answer. An unanimated placement has no clock and rests in `Stand`.
+        // The `+0xc0` enable gate reads the live sequence, as the emitters do; an unanimated
+        // placement has no clock and rests in `Stand`.
         crate::ribbons::spawn_ribbon(
             commands,
             rb,
@@ -779,7 +725,7 @@ pub(super) fn spawn_ribbons_for(
                 crate::ribbons::RibbonSeq::Fixed(0),
                 crate::ribbons::RibbonSeq::Host,
             ),
-            // No model-alpha source: a placed prop / effect instance is always drawn (0827).
+            // No model-alpha source: a placed prop / effect instance is always drawn.
             None,
             Some(fade.clone()),
         );
diff --git a/crates/benilla-world/src/terrain_stream/spawn/mod.rs b/crates/benilla-world/src/terrain_stream/spawn/mod.rs
index 16c38d00..0a13ea97 100644
--- a/crates/benilla-world/src/terrain_stream/spawn/mod.rs
+++ b/crates/benilla-world/src/terrain_stream/spawn/mod.rs
@@ -1,7 +1,4 @@
-//! Spawning streamed placements once their model assets land: the per-frame budgeted
-//! [`spawn_loaded_placements`] driver + WMO doodad-prop resolution and the small per-placement
-//! helpers (inspector tags, fade spheres). The submesh/material/fade component assembly lives in
-//! [`assemble`] ([`spawn_model_entities`]), the per-model point lights/emitters/ribbons in [`fx`].
+//! Spawns streamed placements as their model assets land, under a per-frame time and count budget.
 
 mod assemble;
 mod fx;
@@ -48,19 +45,11 @@ use super::{
 };
 use prop_light::{fold_interior_probe, PropLight, PropLobeLight, WmoDoodadInst};
 
-/// Placements (models or WMO props) spawned per frame while live — the count half of the landing
-/// budget; see the cap's comment in [`spawn_loaded_placements`]. ~150 × the measured ~50 µs
-/// downstream cost per landed placement ≈ half a 60 Hz frame of render-side work, and a fresh
-/// Undercity row (~3900 placements) fully furnishes in under half a second, two tiles out.
+/// Placements (models or WMO props) spawned per frame once paced: ~150 × ~50 µs of downstream
+/// cost each is about half a 60 Hz frame of render work.
 const SPAWN_COUNT_CAP: usize = 150;
 
-/// Spawn the submesh entities for any placement whose model asset has finished loading. Each submesh
-/// gets the production [`WowModelMaterial`] (cutout + blend twin) and the same `ModelPart`/`DoodadFade`/
-/// `MeshTag` components the old spawn used — so the existing visibility/fade/lighting systems take over.
-/// The nested resource tuple of [`spawn_loaded_placements`] (the 16-SystemParam ceiling): the
-/// prop-probe table, the stream-trace counters, the live/settling state the landing cap reads,
-/// and the model-forms cache (0834). The skin-palette table left with decision 0863 — a
-/// placement's rig slot is the draw gate's to claim at first wake now, not the spawner's.
+/// The nested resources of [`spawn_loaded_placements`], under Bevy's 16-parameter limit.
 type SpawnTables<'w> = (
     ResMut<'w, PropProbes>,
     ResMut<'w, crate::terrain_stream::StreamActivity>,
@@ -68,8 +57,7 @@ type SpawnTables<'w> = (
     ResMut<'w, ModelForms>,
     ResMut<'w, HullWelds>,
     ResMut<'w, StaticMerge>,
-    // `None` only under `WOW_STATIC_GX=0` (the resource exists whenever the retained pass
-    // is armed — the default since 1434).
+    // `None` only under `WOW_STATIC_GX=0`, when the retained pass is not armed.
     Option<ResMut<'w, crate::static_gx::StaticGx>>,
     // MONKEY (torch shadows Phase 3A): the shared torch bindings every spawned material takes
     // (nested here for the same 16-param reason as the rest of the tuple).
@@ -85,20 +73,15 @@ pub(super) fn spawn_loaded_placements(
     asset_server: Res<AssetServer>,
     shared_light: Option<Res<SharedLightBuffer>>,
     mut meshes: ResMut<Assets<Mesh>>,
-    // The shared per-kind animated liquid materials — WMO groups spawn their embedded water/lava/slime
-    // on these, same as MCLQ terrain water. Absent when the client has no data.
+    // The shared per-kind liquid materials WMO group liquids spawn on; absent without game data.
     liquid_assets: Option<Res<LiquidAssets>>,
-    // Read-only: the loaded-tile map + decoded tiles, for the global MCSH ground-shade lookup at spawn.
-    // `stream_terrain` (chained before this) owns them mutably; here we only read.
+    // For the MCSH ground-shade lookup; `stream_terrain`, chained before this, owns it mutably.
     streamer: Res<TerrainStreamer>,
     adt_tiles: Res<Assets<AdtTile>>,
     time: Res<Time>,
     mut uv_reg: ResMut<crate::doodad_anim::UvAnimMaterials>,
     mut tint_reg: ResMut<crate::doodad_anim::TintAnimMaterials>,
     mut anim_table: ResMut<crate::mat_anim_table::MatAnimTable>,
-    // Nested to stay inside Bevy's 16-element system-param tuple limit: the prop-probe table +
-    // the stream-trace counters + the live/settling state the landing cap reads + the
-    // model-forms cache (decision 0834).
     tables: SpawnTables,
 ) {
     let (mut probes, mut activity, focus, mut forms, mut welds, mut merge, mut staticgx, torch) =
@@ -117,20 +100,15 @@ pub(super) fn spawn_loaded_placements(
         return;
     }
     let t0 = Instant::now();
-    // The landing COUNT cap (B181), on top of the time budget below. The clock gates main-thread
-    // cost — but ~1000 one-submesh doodads pass a 4 ms budget in 2.5 ms and hand the render world
-    // their whole extract/specialize/upload wave in one frame: the measured 60–80 ms landing
-    // frame when a fresh Undercity row streams in. Counting bounds the downstream wave the clock
-    // cannot see. Idle until the body is live-and-settled — the entry/teleport cover exists to
-    // absorb exactly this burst, and capping under it would only lengthen the reveal.
+    // The count cap bounds the render-side wave a time budget misses; off until the focus is
+    // paced, as the loading cover absorbs the burst and a cap would only lengthen the reveal.
     let count_cap = if focus.paced {
         SPAWN_COUNT_CAP
     } else {
         usize::MAX
     };
     let mut spawned_n = 0usize;
-    // The animated-doodad clock origin (decision 0130): per-instance phase = spawn time, as in the
-    // reference (the arm-time cursor offset), and the draw gate seeks against it on resume.
+    // The anim clock origin: each instance's phase is its spawn time, as in the reference.
     let now = time.elapsed_secs();
     let light = &shared_light.0;
     let materials = materials.into_inner();
@@ -140,17 +118,12 @@ pub(super) fn spawn_loaded_placements(
         pending_spawns,
     } = placements.into_inner();
 
-    // Per-frame spawn budget. On cold start every tile's doodads/WMOs finish decoding near-together;
-    // spawning them all in one frame builds thousands of parry trimesh colliders synchronously and
-    // freezes the window for seconds. Spend at most `SPAWN_BUDGET` per frame and resume next frame
-    // (the `spawned` flags make this re-entrant) — a self-tuning cap: cheap doodads spawn many per
-    // frame, an expensive WMO collider one. At least one spawn always happens (the check is after the
-    // work), so progress is guaranteed.
+    // At most `SPAWN_BUDGET` per frame, resumed next frame through the `spawned` flags; the check
+    // follows the work, so every frame spawns at least one.
     let deadline = Instant::now() + SPAWN_BUDGET;
 
     'placements: for (&unique_id, p) in by_id.iter_mut() {
-        // 1. Spawn the model's own geometry once, on first load. For a WMO, also resolve its doodad
-        //    props (`p.doodads`) — spawned individually in step 2 as each prop's M2 asset arrives.
+        // 1. The model's own geometry, once; a WMO also resolves its doodad props for step 2.
         if !p.spawned {
             let entities = match &p.model {
                 ModelHandle::M2(h) => {
@@ -169,9 +142,6 @@ pub(super) fn spawn_loaded_placements(
                         }
                         continue; // model still loading — try next frame
                     };
-                    // The model's app-built render forms (decision 0834): request static — plus
-                    // the skinned twins iff the anim host will rig this model — and wait for the
-                    // paced furnisher, exactly as the placement waits for the asset itself.
                     let key = ModelKey::from(h);
                     let kinds = WANT_STATIC | if wants_rig(m) { WANT_SKINNED } else { 0 };
                     if !forms.require(
@@ -181,44 +151,25 @@ pub(super) fn spawn_loaded_placements(
                     ) {
                         continue;
                     }
-                    // Resolve the MCSH ground-shade the reference way: a GLOBAL world→tile→chunk lookup at
-                    // the doodad's origin, independent of which tile registered it or in what order.
-                    //
-                    // **An ADT map doodad is the FIXED-1.0 family, not the boosted one** (2050).
-                    // This site read `ShadeSel::Lit` (the 2.5 target) on the strength of wow-re
-                    // `m2-interior-doodad-base-light` §6, and §6 was wrong: a `CMapDoodadDef`'s
-                    // `[+0xa4]` is only ever {0.0, 0.5, 1.0}, and the class does not merely fail to
-                    // ramp — at `+0xf8`, where the ramp `0x69e770` reads its target, the doodad
-                    // class holds `m[2][3]` of its own world matrix. The 2.5 and the 3.3333/s chase
-                    // belong to the WENTITY light node (vtable `0x810810`, hung off `[obj+0xe0]`),
-                    // which a doodad has none of. Measured as well as read: 111 identified MDDF
-                    // placements over six trace frames, 356 draws, gains only ∈ {0.5, 1.0}, none
-                    // changing — while an entity walking out of shadow climbed 0.5 → 0.81 → 1.09 →
-                    // 1.3367 in the same frames. wow-re `models/scratch/
-                    // adt-doodad-sun-scale-vs-entity-node.md`.
-                    //
-                    // So this is the same family the exterior WMO MODD prop takes, and for the same
-                    // reason: they are one C++ class. Nothing renders differently today — the
-                    // shader's `min(I, 1)` already flattened the two — but the scale being
-                    // per-class is what has to be true BEFORE that cap can come off.
+                    // The MCSH ground shade, by a global world→tile→chunk lookup at the doodad's
+                    // origin as the reference does, whatever tile registered it. An ADT doodad is
+                    // the fixed 1.0 family, one class with the exterior WMO prop: its
+                    // `CMapDoodadDef` `[+0xa4]` is only ever 0.0, 0.5 or 1.0. The 2.5 boost and its
+                    // 3.3333/s ramp (`0x69e770`) belong to the entity light node (vtable
+                    // `0x810810`), which a doodad lacks; the 2.5's one reader is `0x69e4ad`.
                     let shade =
                         match doodad_ground_shade(&streamer, &adt_tiles, p.transform.translation) {
                             ShadeResolve::Ready(true) => ShadeSel::Shaded,
                             ShadeResolve::Ready(false) => ShadeSel::Matte,
-                            // The doodad's own ground tile is requested but still decoding — wait, so we don't
-                            // bake the lit fallback into a straddling tree whose true tile lands a frame later.
+                            // The ground tile is still decoding: wait, rather than bake the lit
+                            // fallback into a straddling tree whose tile lands a frame later.
                             ShadeResolve::Pending => continue,
                         };
                     let (radius, center) = m2_fade(&m.bounds, p.transform.scale.x);
                     let anim_bound = m2_anim_bound(&m.bounds);
-                    // The placement's ONE draw-set gate, built before the spawn because the
-                    // assembler now takes it too (2059): the mesh lane, the emitters, the ribbons
-                    // and the anim host are admitted or refused together, from one expression. A
-                    // map doodad is nobody's furniture, so it carries no instance and no rooms.
+                    // The placement's one draw-set gate; a map doodad has no instance or rooms.
                     let fade = emitter_fade(p.transform, (radius, center), None, None);
-                    // The placement's identity, built BEFORE the spawn: every lane that takes
-                    // a batch — entity, merge blob, retained cell — carries this same Arc, so
-                    // whichever one draws it, the pick names the placement (decision 1534).
+                    // The pick identity, carried by whichever lane takes a batch.
                     let object = Arc::new(WorldObject {
                         kind: ModelKind::Doodad,
                         label: handle_label(h),
@@ -255,37 +206,24 @@ pub(super) fn spawn_loaded_placements(
                         false, // world-static: not the entity-hosted lane
                         None,  // world-static placement: cards bake their world pivot
                         Some((&mut *merge, MergeSite::Doodad { owner: p.owner })),
-                        // The retained-pass collector (1429/1431) — ADT doodads are its lane.
                         staticgx
                             .as_deref_mut()
                             .map(|gx| (gx, crate::static_gx::GxSite::Doodad { owner: p.owner })),
                     );
                     // ADT doodads are exterior scene: from inside a WMO they draw only through a
-                    // portal window (`0x683700`, fed solely by the per-window walk `0x682fa0` — see
-                    // `crate::exterior_cull`). Tagged per submesh because a placement has no root
-                    // entity to carry the bound; the deviation from the reference's whole-object test
-                    // is recorded in `exterior_cull`'s module doc.
-                    //
-                    // The anim-host ROOT is skipped: it is a joint hierarchy, not geometry, so it has
-                    // no `Aabb` and lands in the cull's fail-open arm — harmless to draw (it draws
-                    // nothing) but it was 484 of the 6917 "tested" objects at one Stratholme pin,
-                    // which is exactly the kind of noise that makes the instrument stop meaning
-                    // anything. Tag what is drawn (decision 0784).
+                    // portal window (`0x683700`, fed only by the per-window walk `0x682fa0`).
+                    // Deviation: tagged per submesh, where the reference tests the whole object,
+                    // because a placement has no root entity to carry the bound. The anim-host root
+                    // is skipped: with no geometry it has no `Aabb`, and would only pad the counts.
                     let anim_root = host.as_ref().map(|h| h.root);
                     for e in ents.iter().filter(|e| Some(**e) != anim_root) {
                         commands
                             .entity(*e)
                             .insert(crate::exterior_cull::ExteriorScene);
                     }
-                    // Doodad collider (avian): a static trimesh hull baked at this placement's
-                    // transform, WELDED into its owner tile's batch (decision 1369 — the entity
-                    // granularity was ~0.8 cpu_ms of avian per-frame cost at Stormwind; see
-                    // `super::weld`). `None` ⇒ the model has no collision hull, so a hull-less
-                    // tree canopy stays pick-through, matching the reference's
-                    // collision-flagged-doodads-only world trace — the weld carries the
-                    // `PickOccluder` clamp for the hulls it absorbs.
-                    // (`!doodad_bodies_disabled()` / `!doodad_hulls_bare()`: the 1367 premise
-                    // levers. `hull_weld_disabled`: the pre-1369 per-placement shape, for A/B.)
+                    // The collision hull, welded into the owner tile's batch, which carries the
+                    // `PickOccluder` clamp. A hull-less model (a tree canopy) stays pick-through,
+                    // as the reference's world trace tests only collision-flagged doodads.
                     if let Some((verts, tris)) = (!doodad_bodies_disabled())
                         .then(|| placement_collider_data(m.collision.as_ref(), &p.transform))
                         .flatten()
@@ -307,9 +245,6 @@ pub(super) fn spawn_loaded_placements(
                             welds.add_tile(p.owner, verts, tris);
                         }
                     }
-                    // One gate for both emitter families. `None`/empty: an ADT map doodad
-                    // belongs to no building, so neither the window exemption nor the room
-                    // term has anything to key on.
                     spawn_emitters_for(
                         &mut commands,
                         &m.emitters,
@@ -378,36 +313,23 @@ pub(super) fn spawn_loaded_placements(
                         }
                         continue;
                     };
-                    // The building's app-built render forms (0834): static only — WMO group
-                    // geometry never skins. A city root's thousands of batches are exactly the
-                    // burst the paced furnisher exists to spread.
+                    // Static forms only: WMO group geometry never skins.
                     let key = ModelKey::from(h);
                     let prio = placement_priority(&streamer, p.transform.translation);
                     if !forms.require(key, WANT_STATIC, prio) {
                         continue;
                     }
-                    // WMOs carry no authored bounds → never size-fade (∞ radius), rely on the far-clip.
-                    // (`m2: None` ⇒ no anim host, so the joint half of the return is always empty.)
-                    // Hoisted above the spawn: the merge site needs it (a portal-gated building's
-                    // blobs take `WmoGroupVis`), and the instance logic below reuses it.
                     let has_portals = !m.portal_refs.is_empty() && !m.portal_infos.is_empty();
-                    // A building carries no authored M2 bounds, so its gate is the never-fade
-                    // sphere the `f32::INFINITY` radius below always meant. `m2: None` on this
-                    // lane ⇒ no anim host, so only the mesh half of the gate is ever read.
+                    // No authored bounds, so a WMO never size-fades; the far clip bounds it.
                     let fade = emitter_fade(p.transform, (f32::INFINITY, Vec3::ZERO), None, None);
-                    // The building's identity, shared by every lane that takes one of its batches
-                    // (decision 1534) — see the doodad site above.
                     let object = Arc::new(WorldObject {
                         kind: ModelKind::Wmo,
                         label: handle_label(h),
                         id: unique_id,
                         detail: String::new(),
                     });
-                    // The per-placement portal-cull instance, spawned BEFORE the batches so the
-                    // static-gx divert can key its retained region on it (slice 2 of 1429 — the
-                    // region's lifecycle IS this entity's). The group-vis tagging still runs
-                    // after the spawn, off `by_batch`; see the instance block below for why a
-                    // portal-less-but-named building spawns one too.
+                    // The portal-cull instance, spawned before the batches: the retained pass keys
+                    // its region on it, and the region lives as long as it does.
                     let instance = (has_portals || m.wmo_id != 0).then(|| {
                         commands
                             .spawn(WmoPortalInstance {
@@ -415,15 +337,10 @@ pub(super) fn spawn_loaded_placements(
                                 world_from_local: p.transform.compute_affine(),
                                 name_set: p.name_set,
                                 visible: vec![true; m.group_nav.len()],
-                                // Nothing wears the building's own fog until a flood says
-                                // it is on the chain (`WmoPortalInstance::interior_fog`).
+                                // Fogged only once a flood puts the group on the chain.
                                 interior_fog: vec![false; m.group_nav.len()],
                                 liquid_visited: vec![false; m.group_nav.len()],
-                                // The MOGP `groupLiquid` override, resolved once at spawn: 13
-                                // groups in the whole archive declare "this room is wholly
-                                // submerged" in place of carrying a liquid grid, and 5 of them are
-                                // placed — the Deeprun Tram's two flooded sections, the Prison
-                                // Oubliette, the MD crypt and the mountain cave (decision 1000).
+                                // MOGP `groupLiquid`: a room wholly submerged, with no liquid grid.
                                 flooded: m
                                     .group_nav
                                     .iter()
@@ -457,13 +374,13 @@ pub(super) fn spawn_loaded_placements(
                         },
                         p.transform,
                         &object,
-                        ShadeSel::Matte, // WMO lights on the FFP N·L path — the selector is unread
+                        ShadeSel::Matte, // unread: WMO lights on the FFP N·L path
                         None, // WMO groups carry their own per-submesh interior flag + batch class
                         Some(&fade),
                         f32::INFINITY,
                         Vec3::ZERO,
-                        None, // …and no authored M2 box: group geometry never animates
-                        None, // WMO group geometry is not an M2 — its doodad props animate below
+                        None, // no authored M2 box: group geometry never animates
+                        None, // not an M2: its doodad props animate below
                         &mut uv_reg,
                         &mut tint_reg,
                         &mut anim_table,
@@ -477,9 +394,7 @@ pub(super) fn spawn_loaded_placements(
                                 portal_gated: has_portals,
                             },
                         )),
-                        // Slice 2 (1429): WMO group geometry diverts into a retained region
-                        // keyed by the instance entity — only a placement WITH an instance
-                        // qualifies (no instance ⇒ no PVS identity ⇒ entity path).
+                        // A retained region keyed by the instance; without one there is no PVS key.
                         instance.and_then(|i| {
                             staticgx.as_deref_mut().map(|gx| {
                                 (
@@ -510,35 +425,21 @@ pub(super) fn spawn_loaded_placements(
                             );
                         }
                     }
-                    // A world WMO placement is exterior scene too (`0x6856c0`, fed by the same
-                    // per-window populate `0x682fa0`): from inside one building, another building
-                    // draws only through a portal window. 0774 left this ungated because these
-                    // entities already had a `Visibility` authority and a second writer would have
-                    // fought it — that is fixed at the root now, with the window term folded INTO
-                    // that authority (decision 0784), so the tag is safe to add.
-                    //
-                    // Tagging is unconditional and the **exemption is dynamic**: the camera's own
-                    // containing placement is not exterior to itself, which the authority decides
-                    // per frame from `CameraInteriorClaim`. A static "is this the player's building"
-                    // could not be right — the player walks in and out of it.
+                    // A world WMO is exterior scene too (`0x6856c0`, fed by the same walk
+                    // `0x682fa0`): from inside one building, another draws only through a portal
+                    // window. The tag is unconditional; the camera's own building is exempted per
+                    // frame from `CameraInteriorClaim`.
                     for e in &ents {
                         commands
                             .entity(*e)
                             .insert(crate::exterior_cull::ExteriorScene);
                     }
-                    // Portal visibility + interior tracking: tie every group submesh entity (the
-                    // `by_batch` map is index-parallel with the submeshes — the structural form of
-                    // what used to be a positional promise on `ents`, which the mega divert's
-                    // `continue` silently broke) back to one per-placement instance that holds the
-                    // placement transform + the per-frame visible set. The cull is per-group, so a building with a portal graph
-                    // gets tagged; a portal-less prop keeps all groups visible but still spawns the
-                    // instance when it carries a WMOAreaTable identity — the interior down-ray
-                    // (`wmo_portal::track_current_interior`) needs it. See `crate::wmo_portal`.
+                    // Tie each group's submeshes (`by_batch` is index-parallel with them) to the
+                    // instance. A portal-less building keeps every group visible but still gets an
+                    // instance when it has a WMOAreaTable identity, for the interior down-ray.
                     if let Some(instance) = instance {
                         if has_portals {
-                            // One shared single-group key per group — geometry belongs to exactly
-                            // one room, and sharing keeps the tag one allocation per group rather
-                            // than per submesh (a city is ~100k submeshes).
+                            // One shared key per group, not per submesh (a city has ~100k).
                             let group_key: Vec<Arc<[u16]>> = (0..m.group_nav.len() as u16)
                                 .map(|g| Arc::from([g].as_slice()))
                                 .collect();
@@ -552,21 +453,13 @@ pub(super) fn spawn_loaded_placements(
                                     .insert(WmoGroupVis { instance, groups });
                             }
                         }
-                        // The props spawn later — each waits on its own M2 — so they can't be
-                        // tagged here; hold the instance for them (decision 0689). Held for EVERY
-                        // instance, not just a portal-bearing one: since 0696 it is also the
-                        // placement identity each embedded pool is scoped by, and a portal-less
-                        // building's pool needs an owner exactly as much as a canal does.
+                        // Held for the props, which spawn later, and for any instance: it also
+                        // scopes the building's embedded pools, portals or not.
                         p.portal_instance = Some(instance);
                         ents.push(instance); // despawns with the placement
                     }
-                    // The building's embedded MLIQ liquid (Stormwind's canals + fountains, the
-                    // Ironforge lava, dungeon pools): one flat animated surface per group with water,
-                    // spawned at the placement transform on the shared per-kind material. (The group
-                    // zip above reads `by_batch`, so appends to `ents` no longer threaten it.)
-                    // Spawned a group at a time so each surface can take that group's cull key: a
-                    // pool belongs to the room it sits in, and a culled room's lava must go with it
-                    // (decision 0689 — the same defect as the props, on the same building).
+                    // The embedded MLIQ liquid, spawned a group at a time so each surface takes its
+                    // room's cull key: a culled room's lava goes with it.
                     for (gi, lq) in m.group_liquids.iter().enumerate() {
                         let Some(lq) = lq else { continue };
                         let first = ents.len();
@@ -576,13 +469,8 @@ pub(super) fn spawn_loaded_placements(
                             liquid_assets.as_deref(),
                             &mut meshes,
                             p.transform,
-                            // The group's own interior class (`MOGI & 0x48 == 0`) — which FOG BLOCK
-                            // its pool draws under, so an indoor pool hazes with the room the way
-                            // the walls beside it do (decision 0691's open lane).
+                            // Interior (`MOGI & 0x48 == 0`): the pool takes the room's fog.
                             m.group_bounds.get(gi).is_some_and(|g| g.interior),
-                            // …and the pool's SCOPE: the room it belongs to (0696 — only a subject
-                            // standing in this placement can be in it) plus that room's own floor
-                            // in world Z (0701 — and only one at or above it).
                             crate::liquid::WmoPool::new(
                                 p.portal_instance.map(|instance| WmoRoom {
                                     instance,
@@ -591,35 +479,13 @@ pub(super) fn spawn_loaded_placements(
                                 &p.transform,
                                 m.group_bounds.get(gi),
                             ),
-                            // The root's MOMT diffColor table — an interior pool's body colour.
+                            // The root's MOMT diffColor table: an interior pool's body colour.
                             &m.material_diff_color,
                             &mut ents,
                         );
-                        // Another building's canal is exterior scene like its walls (`0x6856c0`,
-                        // the same per-window populate). **Unconditional, like the walls at the
-                        // `ExteriorScene` site above** — decision 1652's second half, and a
-                        // structural fix with **no shipped symptom**, which is the honest framing.
-                        //
-                        // It used to be tagged only *inside* the `portal_instance` arm below,
-                        // because `WmoGroupVis` carries the instance the camera's-own-building
-                        // exemption is keyed on. That left a pool with NEITHER component — and so
-                        // no `Visibility` authority at all — whenever a placement got no instance
-                        // (`has_portals || m.wmo_id != 0`, ~line 334), while the same placement's
-                        // walls, tagged unconditionally, were window-culled normally.
-                        //
-                        // **That branch is dead on shipped 1.12.1 content** (`cargo run -p
-                        // benilla-formats --example wmo_ownerless_pools`): of 815 roots, 448 have
-                        // no portal graph and exactly ONE has `wmoID == 0` — and that one
-                        // (`pvp_alterac_ent01.wmo`) *does* carry portals. The two conditions never
-                        // coincide, so zero placements reach the hole and none of them carries
-                        // liquid. Kept anyway because it costs nothing and the asymmetry with the
-                        // walls two blocks up was a real defect in the code even where the data
-                        // never exercised it — but it must never be credited with a sighting.
-                        //
-                        // An instance-less placement can never BE the camera's claimed room (the
-                        // interior down-ray resolves through an instance), so there is no
-                        // exemption to lose: the tag alone is right for it, and
-                        // `apply_exterior_cull` is its sole authority exactly as for ADT liquid.
+                        // Another building's pool is exterior scene like its walls (`0x6856c0`),
+                        // tagged unconditionally: an instance-less placement is never the camera's
+                        // room, so the tag alone is right for it.
                         for &e in &ents[first..] {
                             commands
                                 .entity(e)
@@ -628,11 +494,8 @@ pub(super) fn spawn_loaded_placements(
                         if let Some(instance) = p.portal_instance {
                             let groups: Arc<[u16]> = Arc::from([gi as u16].as_slice());
                             for &e in &ents[first..] {
-                                // …and where there IS an instance, the pool rides its group with
-                                // the room (0689) and takes the exemption (0784) — which moves it
-                                // out of `apply_exterior_cull`'s query (`Without<WmoGroupVis>`)
-                                // and into the model-visibility authority, the one that can see
-                                // both terms.
+                                // With an instance the pool rides its room and the exemption;
+                                // `WmoGroupVis` moves it to the model-visibility authority.
                                 commands.entity(e).insert(WmoGroupVis {
                                     instance,
                                     groups: groups.clone(),
@@ -640,11 +503,8 @@ pub(super) fn spawn_loaded_placements(
                             }
                         }
                     }
-                    // Building colliders (avian): the flattened group tris baked at this placement's
-                    // transform — *two* meshes, because the client gathers different WMO faces for the
-                    // player body (walking: drops DETAIL) and the camera/LOS (drops NOCAMCOLLIDE, keeps
-                    // DETAIL). Each goes on its own collision layer so the player and camera queries pick
-                    // their audience (see `crate::collision`); a single trimesh can't be filtered per-face.
+                    // Two colliders, each on its layer: the reference gathers different faces for
+                    // the body (drops DETAIL) and the camera (drops NOCAMCOLLIDE, keeps DETAIL).
                     if let Some((verts, tris)) =
                         placement_collider_data(m.collision.as_ref(), &p.transform)
                     {
@@ -656,11 +516,10 @@ pub(super) fn spawn_loaded_placements(
                                         Some(walk_layers()),
                                         true,
                                     ),
-                                    // WMO walkable faces receive the selection ring (floors, steps).
+                                    // The walk faces take the selection ring (floors, steps).
                                     GroundDecalSurface,
-                                    // …and clamp the mouse pick: the byte-verified occluder face
-                                    // set is MOPY reject-mask 0x84, and the walk bake (reject 0x04)
-                                    // is its nearest existing bake — see `crate::collision`.
+                                    // Clamps the mouse pick. The reference's occluder faces are
+                                    // MOPY reject-mask 0x84; the walk bake (0x04) is the nearest.
                                     PickOccluder,
                                 ))
                                 .id(),
@@ -718,31 +577,24 @@ pub(super) fn spawn_loaded_placements(
                         &mut ents,
                     );
                     tag_world_object(&mut commands, &ents, &object);
-                    // Resolve the interior props for this instance's doodad set (set 0 + the selected
-                    // set), each composed onto the WMO's world transform; their M2s load async.
                     p.doodads = resolve_wmo_doodads(m, p.doodad_set, p.transform, &asset_server);
                     ents
                 }
             };
             p.spawned = true;
             p.entities = entities;
-            // The placement's own model landed; a WMO's just-resolved props (all unspawned)
-            // are new work the count takes on in the same stroke.
+            // The model landed; a WMO's just-resolved props join the pending count.
             *pending_spawns += p.doodads.iter().filter(|d| !d.spawned).count();
             *pending_spawns -= 1;
             activity.placements_spawned += 1;
             spawned_n += 1;
-            // Spent the frame's spawn budget on this model (a WMO with two collider meshes is the
-            // costly case) — defer the rest, including this placement's WMO props, to next frame.
+            // Budget spent: the rest, this placement's props included, waits for the next frame.
             if Instant::now() >= deadline || spawned_n >= count_cap {
                 break 'placements;
             }
         }
 
-        // 2. Spawn each WMO doodad prop as its M2 asset finishes loading (across frames). Their
-        //    entities join `p.entities`, so they despawn with the placement. Empty for M2 doodads.
-        // Copied out before the loop borrows `p.doodads`: the props tag onto the same portal
-        // instance their building's groups did (decision 0689).
+        // 2. Each WMO doodad prop as its M2 lands; its entities join `p.entities`.
         let portal_instance = p.portal_instance;
         // MONKEY (wmo exterior points): this placement's authored MOLT fixtures in world space —
         // the duplicate guard for the synthesised prop lights below (`spawn_lights_for`). Built
@@ -787,7 +639,6 @@ pub(super) fn spawn_loaded_placements(
                 }
                 continue; // this prop's M2 still loading
             };
-            // The prop's app-built render forms (0834) — same gate as its owning placement's.
             let key = ModelKey::from(&d.handle);
             let kinds = WANT_STATIC | if wants_rig(m) { WANT_SKINNED } else { 0 };
             if !forms.require(
@@ -797,44 +648,32 @@ pub(super) fn spawn_loaded_placements(
             ) {
                 continue;
             }
-            // The verified MODD lighting: an EXTERIOR-group WMO prop samples the terrain MCSH at
-            // its footprint like the reference's per-frame refresh `0x698c50` — plain matte (sun
-            // ×1.0) on lit ground, the shaded level on MCSH-shadowed ground, and NEVER the ADT 2.5
-            // boost (§8b: its one read site is unreachable from the WMO render band). An INTERIOR
-            // prop takes its per-instance SH probe instead — the selector is unread there.
+            // An exterior prop samples the MCSH at its footprint, as the reference's per-frame
+            // refresh `0x698c50` does: matte on lit ground, shaded under MCSH shadow, never the
+            // 2.5 boost (its one reader, `0x69e4ad`, is unreachable from the WMO render band).
             let shade = if matches!(d.light, PropLight::Interior { .. }) {
                 ShadeSel::Matte // interior lane; the selector is unread
             } else {
                 match doodad_ground_shade(&streamer, &adt_tiles, d.transform.translation) {
                     ShadeResolve::Ready(true) => ShadeSel::Shaded,
                     ShadeResolve::Ready(false) => ShadeSel::Matte,
-                    // The prop's ground tile is still decoding — defer this prop a frame (same rule
-                    // as an ADT doodad; the per-prop `spawned` flag makes it re-entrant).
+                    // The ground tile is still decoding: defer this prop a frame.
                     ShadeResolve::Pending => continue,
                 }
             };
             let (radius, center) = m2_fade(&m.bounds, d.transform.scale.x);
             let anim_bound = m2_anim_bound(&m.bounds);
-            // One gate for every rider of this prop: the prop rides its building's
-            // exterior-window exemption AND the portal PVS of the rooms that name it — the same
-            // `WmoGroupVis` the submeshes are culled by, so a prop's mesh, its flames, its
-            // streamers and (since 2059) its ANIM HOST are admitted or refused together
-            // (decisions 0786 / 0689 / 1289). Hoisted above the spawn because the assembler takes
-            // it now; a particles-only prop has no submesh to carry a verdict, so this is the only
-            // thing that tells its host it is furniture rather than exterior scene.
+            // The prop's one gate, with its building's window exemption and rooms: a particles-only
+            // prop's host has no other way to know it is furniture, not exterior scene.
             let fade = emitter_fade(
                 d.transform,
                 (radius, center),
                 portal_instance,
                 Some(&d.groups),
             );
-            // An interior prop's committed light, folded ONCE into its SH probe (the reference folds
-            // at doodad create + per-frame light commit; everything here is static, so once): the
-            // MODD-colour ambient + the diffuse lobe on the fixed interior axis + the owning group's
-            // MOLR lights windowed by their disk attenStart/attenEnd from the prop's REFERENCE POINT
-            // — the placement-transformed M2 vertex-box centre (the byte-cited `[def+0x5c]` anchor
-            // family `0x6952a0`/`0x713680`; the trace fit put it ~1.1 yd up on the abbey stand,
-            // between origin and centre — the centre satisfies every observed gain, residual OPEN).
+            // An interior prop's light, folded once into its SH probe: the reference refolds at
+            // each light commit, but every input here is static. The reference point is the placed
+            // M2 box centre, the `[def+0x5c]` anchor of `0x6952a0`/`0x713680`.
             let interior_slot = match &d.light {
                 PropLight::Exterior => None,
                 PropLight::Interior {
@@ -846,7 +685,7 @@ pub(super) fn spawn_loaded_placements(
                     let coeffs = fold_interior_probe(*ambient, *diffuse, ref_point, lights);
                     let slot = probes.alloc(coeffs);
                     if slot.is_none() {
-                        // Once per burst, not per prop — a city WMO can flood thousands in a frame.
+                        // Once per burst, not per prop: a city WMO can flood thousands in a frame.
                         let (live, peak) = probes.occupancy();
                         warn_once!(
                             "interior-prop probe table full (live {live}, peak {peak});                              overflowing props fall back to exterior light"
@@ -855,7 +694,6 @@ pub(super) fn spawn_loaded_placements(
                     slot
                 }
             };
-            // The prop's identity, shared with whichever lane takes its batches (1534).
             let object = Arc::new(WorldObject {
                 kind: ModelKind::Doodad,
                 label: handle_label(&d.handle),
@@ -895,8 +733,6 @@ pub(super) fn spawn_loaded_placements(
                 &mut anim_table,
                 false, // world-static: not the entity-hosted lane
                 None,  // world-static placement: cards bake their world pivot
-                // The prop merge site (1418 lane 3): keyed by the rooms that name the prop,
-                // slot baked per vertex for the interior lane.
                 Some((
                     &mut *merge,
                     MergeSite::Prop {
@@ -905,10 +741,8 @@ pub(super) fn spawn_loaded_placements(
                         slot: interior_slot,
                     },
                 )),
-                // The prop retained-pass site (B4, decision 1433): region keyed by the
-                // building's instance entity — the PVS identity AND the lifecycle. No
-                // instance ⇒ no region key ⇒ the merge/entity path, tallied per prop so
-                // the declined population is never silent.
+                // The retained-pass region is the building's instance, its PVS key and lifetime;
+                // without one the prop takes the merge or entity path, tallied.
                 match (portal_instance, staticgx.as_deref_mut()) {
                     (Some(instance), Some(gx)) => Some((
                         gx,
@@ -925,10 +759,8 @@ pub(super) fn spawn_loaded_placements(
                     _ => None,
                 },
             );
-            // The slot frees itself when the prop despawns (streaming out) — the component hook
-            // returns it to the table whoever does the despawn. A prop whose every batch
-            // diverted into a merge blob (1418 lane 3) spawns a bare carrier row for the hook:
-            // the blob aggregates many props and cannot own any single slot's lifetime.
+            // A despawn hook returns the slot to the table. A prop whose every batch merged spawns
+            // a bare carrier for it, since a blob cannot own one prop's slot.
             if let Some(slot) = interior_slot {
                 let owner = match ents.first() {
                     Some(&first) => first,
@@ -940,17 +772,10 @@ pub(super) fn spawn_loaded_placements(
                 };
                 commands.entity(owner).insert(PropProbeSlot(slot));
             }
-            // Portal-cull the prop with the rooms that name it — the reference commits a WMO's
-            // doodads per VISIBLE group (`0x695aa0` over the group's MODR refs, from the
-            // visible-group walk `0x698720`), so furniture never outlives its room (decision 0689)
-            // and a prop several rooms name is drawn from ANY of them. Every submesh spawned above
-            // is this one prop, so they all share the one key.
-            //
-            // The anim-host ROOT is skipped, for the reason the ADT site skips it (0784): it is a
-            // joint hierarchy, not geometry — no `ModelPart`, no `Aabb` — so it lands in the cull's
-            // fail-open arm and inflates every "objects tested" count without ever being drawn. The
-            // ADT lane has excluded it since 0784; this lane did not, which made the same root a
-            // silent passenger of the WMO prop path's counts.
+            // Cull the prop with the rooms that name it: the reference admits a WMO's doodads to
+            // the frame per group its portal walk reaches (`0x685d70` → `0x6838f0` over the
+            // group's MODR list), so a prop is drawn from any of them. The anim-host root is
+            // skipped, as at the ADT site.
             let anim_root = host.as_ref().map(|h| h.root);
             if let (Some(instance), false) = (portal_instance, d.groups.is_empty()) {
                 for &entity in ents.iter().filter(|e| Some(**e) != anim_root) {
@@ -959,22 +784,14 @@ pub(super) fn spawn_loaded_placements(
                             instance,
                             groups: d.groups.clone(),
                         },
-                        // Furniture is exterior scene when its building is (0784) — and exempt when
-                        // that building is the one the camera stands in. Keyed on the instance
-                        // `WmoGroupVis` carries, so a prop no group names (no key, no exemption
-                        // possible) is deliberately left untagged rather than gated blind.
+                        // Exterior scene with its building, exempt in the camera's own; a prop no
+                        // group names has no instance key, so it stays untagged.
                         crate::exterior_cull::ExteriorScene,
                     ));
                 }
             }
-            // Prop collider (avian): a static trimesh from the prop's collision hull at its world
-            // transform — collide-iff-hull, exactly like a map doodad, so a weapon rack / crate / cargo
-            // net is solid to both the player and the camera while a hull-less prop (banner, small
-            // candle) isn't. Default collision layer ⇒ both audiences. WELDED per placement
-            // (decision 1369): every prop of a building despawns with the building, so the batch
-            // has exactly the lifetime the individual hulls had — the weld flushes into
-            // `Placement::entities` one chain-step later. (The 1367 premise levers and the 1369
-            // A/B lever gate here exactly as at the map-doodad site above.)
+            // Solid to body and camera iff it has a collision hull, like a map doodad; welded per
+            // placement, as every prop despawns with its building.
             if let Some((verts, tris)) = (!doodad_bodies_disabled())
                 .then(|| placement_collider_data(m.collision.as_ref(), &d.transform))
                 .flatten()
@@ -988,7 +805,6 @@ pub(super) fn spawn_loaded_placements(
                                     None,
                                     !doodad_hulls_bare(),
                                 ),
-                                // A world-static WMO prop's hull clamps the mouse pick like any doodad.
                                 PickOccluder,
                             ))
                             .id(),
@@ -1055,17 +871,13 @@ pub(super) fn spawn_loaded_placements(
     activity.spawn_ms += t0.elapsed().as_secs_f32() * 1000.0;
 }
 
-/// Resolve a WMO instance's visible doodad props: the global set (0, always shown) plus the
-/// placement's MODF-selected set, each prop composed onto the WMO's world transform and given its M2
-/// handle (loaded async, spawned by [`spawn_loaded_placements`] when ready). Props with an unresolved
-/// name are skipped.
+/// A WMO placement's doodad props: set 0, always shown, plus its MODF-selected set.
 fn resolve_wmo_doodads(
     wmo: &WmoModel,
     doodad_set: u16,
     wmo_world: Transform,
     asset_server: &AssetServer,
 ) -> Vec<WmoDoodadInst> {
-    // Set 0 is the always-shown global set; a non-zero placement set adds one more.
     let mut ranges: Vec<(u32, u32)> = wmo
         .doodad_sets
         .first()
@@ -1090,10 +902,7 @@ fn resolve_wmo_doodads(
                 continue; // MODN name offset didn't resolve
             }
             let local = wmo_doodad_local(d.position, d.orientation, d.scale);
-            // Interior classification (MODR ownership) + the MODD-colour base + the owning group's
-            // MOLR refs were all resolved ONCE at asset load (`WmoModel::doodad_base`); here the
-            // placement composes the referenced lights into WORLD space so the spawn-time fold
-            // never needs the WMO asset again.
+            // The asset-level base, with its MOLR lights moved into world space for the fold.
             let light = match wmo.doodad_base.get(di) {
                 Some(DoodadBase::Interior(b)) => PropLight::Interior {
                     ambient: b.ambient,
@@ -1116,9 +925,7 @@ fn resolve_wmo_doodads(
             out.push(WmoDoodadInst {
                 handle: asset_server.load(m2_url(&d.model)),
                 transform: wmo_world.mul_transform(local),
-                // Every MODR referrer, inverted with the lighting base at load — the prop's
-                // portal-cull key, so a lantern is hidden with the room it hangs in (decision 0689)
-                // and a lava fall the rooms below and above both name survives either being culled.
+                // Every group whose MODR names the prop, inverted at asset load.
                 groups: wmo.doodad_groups.get(di).cloned().unwrap_or_default(),
                 light,
                 spawned: false,
@@ -1128,12 +935,8 @@ fn resolve_wmo_doodads(
     out
 }
 
-/// `WOW_FADE_NEAR="x,y,r"` — the "name that popping doodad" instrument: a WoW server-coordinate
-/// point (the same numbers `.go xyz` takes, director-verbatim) plus a horizontal radius in yards.
-/// Every placement spawning within `r` yd of the point logs its model path, fade radius (which
-/// selects the `model_fade` band), scale, and how many of its batches the static merge diverted —
-/// so a "this doodad pops in at .go X Y Z" report converts into the placement's actual fade
-/// inputs and its lane (merged fader / per-entity / WMO) in one parked probe run, no camera work.
+/// `WOW_FADE_NEAR="x,y,r"`: a server-coordinate point (as `.go xyz` takes) and a radius in yards;
+/// every placement spawning within it logs its model, fade radius, scale and diverted batches.
 fn fade_near_target() -> Option<(bevy::math::Vec2, f32)> {
     static T: std::sync::OnceLock<Option<(bevy::math::Vec2, f32)>> = std::sync::OnceLock::new();
     *T.get_or_init(|| {
@@ -1145,9 +948,7 @@ fn fade_near_target() -> Option<(bevy::math::Vec2, f32)> {
     })
 }
 
-/// One `[fade-near]` line for a placement inside the [`fade_near_target`] circle — shared by the
-/// doodad and WMO arms so the two print comparably. `radius` is the fade input (∞ for a WMO);
-/// `diverted` of `batches` went to the static merge (the lane readout).
+/// One `[fade-near]` line; `diverted` counts the batches that left the entity path.
 fn log_fade_near(
     kind: &str,
     label: &str,
@@ -1168,12 +969,9 @@ fn log_fade_near(
     );
 }
 
-/// A model handle's source path as a readable label for the object inspector (the asset path without
-/// the `mpq://` source prefix). Empty if the handle carries no path.
-/// A placement's model-forms build priority (decision 0834): its Chebyshev tile distance to the
-/// stream focus, scaled to leave the band below for the entity lane — a mob walking into view
-/// never queues behind a city's scenery. `translation` is Bevy space (the placement transform);
-/// `world_to_tile` wants WoW ground coords, the inverse of decision 0002's rotation.
+/// A placement's render-forms priority, lower sooner: its Chebyshev tile distance to the focus,
+/// above the entity lane's band so a unit coming into view never queues behind scenery.
+/// `translation` is Bevy space; `world_to_tile` takes WoW ground coordinates.
 fn placement_priority(streamer: &TerrainStreamer, translation: Vec3) -> i32 {
     let (tx, ty) = world_to_tile(-translation.z, -translation.x);
     let d = (tx as i32 - streamer.focus.0)
@@ -1189,14 +987,8 @@ fn handle_label<A: Asset>(handle: &Handle<A>) -> String {
         .unwrap_or_default()
 }
 
-/// Tag every spawned entity of a placement with its [`WorldObject`] identity (so the mouseover
-/// inspector can name it). Harmless on the non-mesh entities (colliders) — only mesh entities are
-/// ray-picked.
-///
-/// The identity is built by the caller and passed IN, because a batch that diverts into a
-/// consolidating lane spawns no entity for this to reach: the same Arc rides the divert as the
-/// lane's pick-member identity (decision 1534). This tag covers what the entity path did spawn —
-/// including the fx entities (emitters, ribbons, lights) that no lane ever takes.
+/// Tags a placement's spawned entities, fx included, with its [`WorldObject`] for the inspector; a
+/// diverted batch carries the same Arc in its lane instead.
 fn tag_world_object(commands: &mut Commands, ents: &[Entity], object: &Arc<WorldObject>) {
     for &e in ents {
         commands.entity(e).insert((**object).clone());
@@ -1237,24 +1029,19 @@ fn tag_light_owner(commands: &mut Commands, lights: &[Entity], object: &Arc<Worl
 /// the bird blinks out whenever that 1-yd box leaves the frustum while the bird itself is still on
 /// screen — the director's "birds in the sky often dis/appear based on the cam angle" (decision 1259).
 ///
-/// The reference tests one volume per doodad *object* and derives it from these same header fields:
-/// `0x683700` calls `0x682ef0(ecx = &[rec+0x5c] centre, [rec+0x68] radius)` → `0x686b80`, a 6-plane
-/// frustum **sphere** test, where `rec+0x5c` is the transformed `(min+max)/2` and `rec+0x68` is
-/// `bounding_sphere_radius × scale` (wow-5875-re `terrain/scratch/doodad-emitter-drawset-gate.md`
-/// §1c/§2a, VERIFIED; the same two fields [`m2_fade`] already reads). We keep the **box** rather than
-/// its circumsphere: it bounds the same geometry more tightly, and Bevy's cull is an OBB test anyway.
+/// Deviation: the box, where the reference tests its circumsphere (`0x683700` → `0x682ef0` →
+/// `0x686b80` on the `[rec+0x5c]` centre and `[rec+0x68]` radius × scale), because Bevy culls by
+/// box and the box is tighter.
 pub fn m2_anim_bound(bounds: &Option<M2Bounds>) -> Option<Aabb> {
     let b = bounds.as_ref()?;
     // The basis swap permutes and negates axes, so min/max have to be re-derived, not mapped.
     let (a, c) = (wow_to_bevy(b.bbox_min), wow_to_bevy(b.bbox_max));
     let (lo, hi) = (a.min(c), a.max(c));
-    // A model that authors a degenerate (all-zero) box would otherwise pin every submesh of an
-    // animated placement to a point at the origin — strictly worse than the bind pose it replaces.
+    // A degenerate (all-zero) authored box counts as none.
     (hi.cmpgt(lo).any()).then(|| Aabb::from_min_max(lo, hi))
 }
 
-/// The distance-fade size for an M2: world radius = authored bounding-sphere radius × placement scale;
-/// centre = authored bbox centre in Bevy model-local space. Absent bounds ⇒ never size-fade.
+/// An M2's fade sphere: authored sphere radius × scale, centred on the authored box (model-local).
 pub fn m2_fade(bounds: &Option<M2Bounds>, scale: f32) -> (f32, Vec3) {
     match bounds {
         Some(b) => {
diff --git a/crates/benilla-world/src/terrain_stream/spawn/prop_light.rs b/crates/benilla-world/src/terrain_stream/spawn/prop_light.rs
index 49f7534c..016427af 100644
--- a/crates/benilla-world/src/terrain_stream/spawn/prop_light.rs
+++ b/crates/benilla-world/src/terrain_stream/spawn/prop_light.rs
@@ -1,57 +1,37 @@
-//! The WMO prop-light machinery — a placed prop's resolved lighting and the interior SH fold.
-//!
-//! Split out of `terrain_stream.rs` (0830 named the carve; 0832 executed it): this is spawn-side
-//! state and math — consumed by the placement assembler, the WMO-gameobject prop lane
-//! (`crate::entities`' `wmo_props`) and the GameObject footprint classifier (`crate::interior`) —
-//! and none of it touches the streamer's residency logic. Paths outside the streamer are stable:
-//! `terrain_stream` re-exports [`fold_interior_probe`] and [`PropLobeLight`].
+//! WMO prop lighting: a placed prop's resolved light and the interior SH and particle folds.
 
 use std::sync::Arc;
 
 use benilla_assets::M2Model;
 use bevy::prelude::*;
 
-/// One WMO doodad prop instance: its M2 handle and the **world** transform (the WMO instance
-/// transform composed with the doodad's WMO-local transform), spawned once the M2 asset loads.
+/// One WMO doodad prop at its world transform, spawned once its M2 loads.
 pub(crate) struct WmoDoodadInst {
     pub(crate) handle: Handle<M2Model>,
     pub(crate) transform: Transform,
-    /// Every WMO group whose MODR names this prop — the portal-cull key, so a prop is hidden with
-    /// the rooms it furnishes and drawn while any one of them is visible. Empty for a MODD no group
-    /// references (the reference never instantiates one at all; we still show it, uncullable,
-    /// rather than change what draws today).
+    /// The groups whose MODR names this prop, its portal-cull key: drawn while any is visible.
+    /// Empty for a MODD no group names: never instantiated by the reference, drawn here with no
+    /// room gate.
     pub(crate) groups: Arc<[u16]>,
-    /// The prop's lighting ([`PropLight`], from `WmoModel::doodad_base` composed with this
-    /// placement): exterior sky-lit, or the interior MODD-colour base + its owning group's MOLR
-    /// lights placed in world space — folded into the prop's SH probe once its M2 loads (the fold
-    /// reference point needs the M2 bounds).
     pub(crate) light: PropLight,
     pub(crate) spawned: bool,
 }
 
-/// A WMO prop's placement-resolved lighting: the asset-level [`DoodadBase`](benilla_assets::DoodadBase)
-/// with the owning group's MOLR lights already transformed to WORLD (Bevy) space — so the
-/// spawn-time SH fold needs only the loaded M2's bounds (its reference point) and nothing from the
-/// WMO asset.
+/// A WMO prop's lighting, its MOLR lights already in world space for the spawn-time fold.
 pub(crate) enum PropLight {
     Exterior,
     Interior {
-        /// `cap96(MODD.colour)` — the ambient word (0–1 RGB).
+        /// The ambient word, `cap96(MODD.colour)` (0–1 RGB).
         ambient: [f32; 3],
-        /// `floor112(MODD.colour)` — the diffuse word, committed on the fixed interior axis.
+        /// The diffuse word, `floor112(MODD.colour)`, committed on the fixed interior axis.
         diffuse: [f32; 3],
-        /// The owning group's MOLR omni lights: world (Bevy) position, colour × intensity, and the
-        /// disk `attenStart`/`attenEnd` window (the fold's range gate).
+        /// The owning group's MOLR omni lights.
         lights: Vec<PropLobeLight>,
     },
 }
 
 impl PropLight {
-    /// The prop's lighting lane, as the mouseover inspector says it. A WMO prop that looks wrong is
-    /// almost always on the wrong *lane* or carrying an unbaked base — and neither is visible from
-    /// the model path alone, which is why Booty Bay's black entrance arch read as a texture bug for
-    /// as long as it did (decision 0969). `sky-lit` is the exterior lane; the interior lane prints
-    /// the MODD-colour words it actually commits, so a base of `#000000` names itself on hover.
+    /// The lighting lane for the mouseover inspector: `sky-lit`, or the interior words it commits.
     pub(crate) fn inspector_label(&self) -> String {
         let hex = |c: &[f32; 3]| hex_word(*c);
         match self {
@@ -70,17 +50,13 @@ impl PropLight {
     }
 }
 
-/// A committed light word (0–1 RGB) as `#rrggbb` — the reading every prop inspector prints, here
-/// once so the terrain lane's label and the WMO-gameobject lane's (`entities::wmo_props`) cannot
-/// drift into two different renderings of the same number.
+/// A committed light word (0–1 RGB) as `#rrggbb`, the one form every prop inspector prints.
 pub fn hex_word(c: [f32; 3]) -> String {
     let b = c.map(|v| (v * 255.0).round().clamp(0.0, 255.0) as u8);
     format!("#{:02x}{:02x}{:02x}", b[0], b[1], b[2])
 }
 
-/// One MOLR-referenced light as the interior fold consumes it (world Bevy space, colour
-/// pre-multiplied by the authored intensity). Shared by the MODD prop spawn fold and the
-/// GameObject footprint lane ([`crate::interior`] via [`crate::wmo_portal`]'s verdict).
+/// One MOLR light as the interior folds read it: world position and colour × intensity.
 pub struct PropLobeLight {
     pub pos: Vec3,
     pub color_i: [f32; 3],
@@ -88,51 +64,25 @@ pub struct PropLobeLight {
     pub atten_end: f32,
 }
 
-/// The **fixed-function** lane's committed light, evaluated at the world up axis — the single
-/// constant every LIT particle of a model standing in a WMO room is multiplied by.
-///
-/// A particle draw does **not** take the SH vertex program a mesh batch takes, and that is not an
-/// approximation either way — it is a structural fork. The batch-record TYPE dispatch
-/// (`70b613`/`70b61e jmp [eax*4+0x70b728]`) sends TYPE 0 (mesh) and TYPE 2 (batched doodads) to
-/// `0x70baf0` with the frame's `M2UseShaders` mask bit cached at `[esi+0x32f0]`, but TYPE 4
-/// (**particles**, `0x70d8b0`) — with 1, 3 and 5 — through the shared helper `0x70ca50`, which
-/// writes no such field and NULL-binds **both** program slots (`70ca74 SetState(0x40, 0)`,
-/// `70ca80 SetState(0x3f, 0)`). `0x70b360` zeroes `[esi+0x32f0]` at the head of every batch
-/// (`70b607`), and only `0x70cb30` (TYPE 0) and `0x70d330` (TYPE 2) ever write it back — so
-/// `0x70baf0`'s `70bb9c test eax,eax` reads 0 for a particle and `70bba4 je 0x70bdf2` takes the
-/// **fixed-function device-light commit** `0x71c730` unconditionally. wow-re
-/// `m2-lighting-lane-selector.md` §1(c2), triple-derived.
-///
-/// So the curve here is the hardware's `max(N·L, 0)`, **not** [`fold_interior_probe`]'s SH lobe —
-/// a mesh and its own particles share the room's committed WORDS and legitimately differ in the
-/// function applied to them (0.900 vs 0.869 on the key axis; the SH lobe also wraps around the
-/// back, where this clamps to nothing). Decision 1709 supersedes 1705's reading.
-///
-/// - **Slot 0** is the key light. `0x71c2f0` reconstructs it from the context's linear moments as
-///   `1.25·P − 0.25·DC` with **no clamp** (`0x4549a0` is three dword moves and a `ret 0xc`); with
-///   the interior leg's single directional `P == DC` exactly, so it reduces to the committed
-///   diffuse itself, and the ambient's `0.25·(DC − P)` correction is zero. `N` is world up and the
-///   axis is the fixed `(−0.30822, −0.30822, −0.9)`, so `N·L` is **0.9 at every camera angle**.
-/// - **Slots 1..3** are the ≤3 nearest MOLT points, diffuse-only (ambient and specular forced to 0
-///   at `71c7e3`/`71c7e6`), under GL's own distance attenuation `1/(0.7d + 0.03d²)` — constant
-///   term zero. Because N is world up, a room light at or below the emitter contributes exactly
-///   nothing.
-///
-/// Unclamped by design: the reference clamps the **product**, not the term (GL clamps the lit
-/// vertex colour), which is where `sim`'s fold does it.
+/// The fixed-function light at world up that every lit particle of a model in a WMO room takes. A
+/// particle batch (TYPE 4, `0x70d8b0`) goes through `0x70ca50`, which binds no vertex program, so
+/// `0x70baf0` takes the device-light commit `0x71c730`: `max(N·L, 0)` over the room's committed
+/// words, not [`fold_interior_probe`]'s SH lobe. Slot 0 is the committed diffuse (`0x71c2f0`
+/// rebuilds `1.25·P − 0.25·DC`, and one directional has `P == DC`), with `N·L` 0.9 on the fixed
+/// axis; slots 1..3 are the ≤3 nearest MOLT points, diffuse only, under `1/(0.7d + 0.03d²)`.
+/// Unclamped: GL clamps the lit colour, the product, which the particle sim does.
 pub fn interior_light_up(
     ambient: [f32; 3],
     diffuse: [f32; 3],
     ref_point: Vec3,
     lights: &[PropLobeLight],
 ) -> [f32; 3] {
-    // Toward-light, Bevy space — the same axis the SH fold puts the diffuse word on.
+    // Toward-light, Bevy space: the axis the SH fold puts the diffuse word on.
     let axis = Vec3::new(-0.30822, 0.9, -0.30822).normalize();
     let mut lit = Vec3::from_array(ambient) + Vec3::from_array(diffuse) * axis.y.max(0.0);
-    // The ≤3 NEAREST in range, which is the reference's 4-entry max-heap by squared distance
-    // (`0x71bf90`, `71bfca cmp esi,0x4`) minus slot 0. Membership is our own disk window — the
-    // reference's is `0x6a7ac0`'s radius test against the proxy's WMO instances, which we model
-    // the same way for the SH lane; see the residual in decision 1709.
+    // The ≤3 nearest: the reference's 4-entry max-heap by squared distance (`0x71bf90`) minus
+    // slot 0. Membership is the light's disk window, as in the SH fold; the reference's is
+    // `0x6a7ac0`'s radius test against the proxy's WMO instances.
     let mut near: Vec<(f32, &PropLobeLight)> = lights
         .iter()
         .map(|l| ((l.pos - ref_point).length(), l))
@@ -152,12 +102,8 @@ pub fn interior_light_up(
     lit.to_array()
 }
 
-/// Fold one interior committed light into its 7-row SH probe: the ambient word + the diffuse word
-/// as a directional on the FIXED interior axis + each MOLR lobe windowed by its disk
-/// attenStart/attenEnd from `ref_point` (the byte-verified `0x69e1c0` falloff: d ≤ start → 1;
-/// d ≥ end → excluded; else linear). One definition for both interior lanes — the MODD prop
-/// (spawn-time, MODD-colour words) and the GameObject footprint (classify-time, MOCV-derived
-/// words); the SH closed form itself is [`prop_probe_coeffs`](crate::lighting::prop_probe_coeffs).
+/// An interior light as its 7-row SH probe, each MOLR lobe windowed by its distance from
+/// `ref_point` (`0x69e1c0`: full inside `attenStart`, none past `attenEnd`, linear between).
 pub fn fold_interior_probe(
     ambient: [f32; 3],
     diffuse: [f32; 3],
@@ -187,14 +133,8 @@ pub fn fold_interior_probe(
 mod tests {
     use super::*;
 
-    /// GOLDEN — the exact worked case wow-re returned for the WENTITY interior leg (`0x6a7300`
-    /// → `0x71bce0`/`0x71bc70` → `0x71c2f0` → `0x71c730`), reproduced end to end. A floor MOCV
-    /// sample of `(70, 60, 50)`: the HSV boost fires (`70 < 168`, a uniform ×2.4 to `(168,144,120)`)
-    /// and the cap does not (`70 <= 96`, so the ambient word is the sample itself). With one
-    /// directional and no points, `0x71c2f0`'s `P == DC` exactly, so the committed diffuse IS the
-    /// boosted word and the ambient correction is zero — leaving `sample/255 · (2.4·0.9 + 1.0)`
-    /// = `sample/255 · 3.16` per channel. The tone-shaping is the classifier's (`floor168`/`cap96`);
-    /// this pins the arithmetic below it.
+    /// The reference's interior leg (`0x6a7300` → `0x71bce0`/`0x71bc70` → `0x71c2f0` →
+    /// `0x71c730`) on a (70, 60, 50) floor sample: `sample/255 · (2.4·0.9 + 1.0)` per channel.
     #[test]
     fn the_committed_interior_light_at_world_up_is_the_reference_worked_case() {
         let sample = [70.0f32, 60.0, 50.0].map(|c| c / 255.0);
@@ -211,10 +151,7 @@ mod tests {
         }
     }
 
-    /// A MOLT point light reaches a particle **only from above**. The normal is world up and the
-    /// term is the hardware's `max(N·L, 0)`, so a room light at or below the emitter contributes
-    /// exactly zero — the fixed-function lane has no wrap-around, which is precisely where it
-    /// parts company with the SH lobe a mesh batch takes.
+    /// With N world up, `max(N·L, 0)` has no wrap-around, unlike the SH lobe.
     #[test]
     fn a_room_light_below_the_emitter_contributes_nothing() {
         let lamp = |y: f32| PropLobeLight {
diff --git a/crates/benilla-world/src/terrain_stream/weld.rs b/crates/benilla-world/src/terrain_stream/weld.rs
index bcf1a7f0..8e9883b9 100644
--- a/crates/benilla-world/src/terrain_stream/weld.rs
+++ b/crates/benilla-world/src/terrain_stream/weld.rs
@@ -1,31 +1,11 @@
-//! Doodad-hull **welding** (decision 1369). The 1367 premise check measured ~0.8 cpu_ms at
-//! Stormwind riding the doodad-hull *population* — 12.2k collider entities' tree proxies, AABBs
-//! and per-collider row visits in avian's per-frame passes — and refuted the row-weight redesign
-//! (a body-less collider costs the same). So the fix is the terrain collider's own pattern
-//! (`terrain_collider_data` welds 256 chunks into one trimesh for exactly this reason): batch the
-//! world-static hulls into a few dozen welded trimeshes instead of thousands of individual ones.
-//! Same triangles, same layers, same [`PickOccluder`] clamp — collision and the mouse-pick
-//! answer are unchanged; only the entity granularity collapses. Identity was verified free to
-//! give up before this was built: the pick clamp consumes a *distance* (`update_pick_occlusion`),
-//! and the inspector/GO hover casts against resident [`PickMesh`] geometry, never these hulls.
+//! Doodad-hull welding: world-static hulls batch into a few dozen welded trimeshes instead of
+//! thousands of colliders, with the same triangles, layers and [`PickOccluder`] clamp (the clamp
+//! reads a distance, and hover picks cast against pick meshes, never these hulls).
 //!
-//! **Ownership** is the design's load-bearing choice (1367 named it the question to answer
-//! first):
-//!
-//! - **WMO props** weld per *placement* (keyed by uniqueId, batch-split by the caps below). Every
-//!   prop of a building despawns with the building (`Placement::entities`), so a weld pushed
-//!   there has exactly the lifetime the individual hulls had. No approximation — and on a
-//!   WMO-only map (an instance), the entire prop population welds under the one global placement.
-//! - **ADT map doodads** weld per the placement's **first-registering tile** (recorded by
-//!   `register_doodad`, when that tile is by construction loaded), the weld entity owned by that
-//!   tile (`TileState::welds`) like its impassable-wall collider. This is the one deliberate
-//!   deviation from per-placement lifetime: a straddler kept alive by a *second* tile keeps its
-//!   model when the owner unloads, but its hull goes with the owner's weld. The mismatch can only
-//!   open past the unload line — `radius + 1` tiles (over 500 yd of hysteresis alone) from the
-//!   focus, far past doodad draw fade — so no reachable or visible doodad ever misses its hull;
-//!   near a mover, every referencing tile is loaded, owner included. The converse (a phantom hull
-//!   outliving every model) cannot happen at all: the owner tile references the placement, so the
-//!   models live at least as long as the weld.
+//! - WMO props weld per placement (uniqueId) and despawn with it, as the single hulls did.
+//! - ADT doodads weld per the placement's first-registering tile and despawn with that tile. A
+//!   straddler another tile keeps alive loses its hull when the owner unloads, but only past the
+//!   unload line, far beyond any reachable or visible doodad.
 
 use std::collections::HashMap;
 
@@ -36,31 +16,23 @@ use crate::collision::PickOccluder;
 use crate::interact::WorldObject;
 use crate::model_render::ModelKind;
 
-/// Hull-count cap per weld. 12.2k hulls at the Stormwind pin batch into ~100 colliders at this
-/// size — the population collapse that IS the win — while keeping any one weld's broadphase AABB
-/// a neighbourhood, not a zone.
+/// Hull cap per weld: keeps a weld's broadphase AABB a neighbourhood, not a zone.
 const WELD_MAX_HULLS: u32 = 128;
 
-/// Triangle cap per weld: bounds the off-thread QBVH build and the single attach. At 0610's
-/// measured attach cost (~0.004 ms + 1.8e-5 ms/triangle) a full batch attaches in ~0.3 ms — well
-/// under `ATTACH_BUDGET`, so one weld can never eat a frame's attach queue. A single oversized
-/// hull (a bridge span) may exceed the cap alone; it then closes its batch immediately.
+/// Triangle cap per weld: a full batch attaches in ~0.3 ms, well under `ATTACH_BUDGET`. A single
+/// oversized hull exceeds it alone and closes its batch at once.
 const WELD_MAX_TRIS: usize = 16_384;
 
-/// Quiet frames that close a live batch's tail. The spawner lands a tile's placements over many
-/// budget-paced frames; a quarter second of silence means the burst is done. Under the loading
-/// cover the tail closes after ONE quiet frame instead: the settle release waits on the collider
-/// backlog (0737, via `finish_colliders`' publish), and a fixed quarter-second tail would push
-/// every world entry longer for nothing.
+/// Quiet frames (a quarter second) that close a batch in settled play; under the loading cover one
+/// quiet frame does, since the settle release waits on the collider backlog.
 const WELD_IDLE_FRAMES: u32 = 15;
 
-/// One accumulating weld: a world-space triangle soup, index-rebased as hulls append — the same
-/// concatenation `terrain_collider_data` does for its 256 chunks.
+/// One accumulating weld: a world-space triangle soup, indices rebased as hulls append.
 struct WeldAcc {
     verts: Vec<Vec3>,
     tris: Vec<[u32; 3]>,
     hulls: u32,
-    /// [`HullWelds::frame`] at the last append — the idle clock the tail flush reads.
+    /// [`HullWelds::frame`] at the last append: the idle clock.
     last_add: u32,
 }
 
@@ -81,14 +53,11 @@ impl WeldAcc {
     }
 }
 
-/// The in-flight weld accumulators, fed by `spawn_loaded_placements` and drained by
-/// [`flush_hull_welds`] one chain-step later. Cleared with the world it describes
-/// (`drop_streamed_world`) — a stale accumulator would otherwise weld the previous map's geometry
-/// into a new map's same-numbered tile, since tile keys are re-inserted at request time on the
-/// very frame the old world drops.
+/// The in-flight weld accumulators, drained by [`flush_hull_welds`]. Cleared with the world
+/// (`drop_streamed_world`): tile keys repeat across maps, so a stale one would weld into the next.
 #[derive(Resource, Default)]
 pub struct HullWelds {
-    /// Flush-system tick, the idle clock. Wrapping u32 — only ever read as a difference.
+    /// Flush-system tick, the idle clock; wrapping, read only as a difference.
     frame: u32,
     /// ADT map-doodad hulls by owner tile.
     tiles: HashMap<(i32, i32), WeldAcc>,
@@ -123,11 +92,8 @@ impl HullWelds {
             .append(verts, tris, frame);
     }
 
-    /// Accumulators not yet flushed into a [`PendingCollider`] — counted into
-    /// `WorldLoadProgress::colliders_pending` by `finish_colliders`, so the settle release never
-    /// lets a body go while doodad hulls still sit in a batch (each accumulator becomes at least
-    /// one pending collider). Like the queue depth itself, an overcount here (an accumulator a
-    /// later flush discards) can only delay a release, never wrong one.
+    /// Accumulators not yet flushed, counted into `colliders_pending` so the settle release waits
+    /// for them; an overcount only delays.
     pub(super) fn unflushed(&self) -> usize {
         self.tiles.len() + self.props.len()
     }
@@ -138,21 +104,15 @@ impl HullWelds {
     }
 }
 
-/// `WOW_NO_HULL_WELD=1` — spawn doodad/prop hulls one entity per placement, the pre-1369 shape:
-/// the welding A/B lever (the `WOW_NO_*` pattern), never a setting.
+/// `WOW_NO_HULL_WELD=1` spawns one hull entity per placement (a measurement lever).
 pub(super) fn hull_weld_disabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_NO_HULL_WELD").is_some())
 }
 
-/// Close ready batches into [`PendingCollider`] entities and hand each to its owner — tile welds
-/// onto `TileState::welds` (despawned with the tile, like the wall), prop welds into
-/// `Placement::entities` (despawned with the placement, like the hulls they replace). An
-/// accumulator whose owner is already gone is discarded: its hulls were only ever reachable past
-/// the unload line (module doc), and the alternative — spawning a weld nothing owns — is a leak.
-///
-/// Runs in the Stream chain right after `spawn_loaded_placements`, so the frame's appends see the
-/// flush at a deterministic point and the owner lookups race nothing.
+/// Closes ready batches into [`PendingCollider`] entities owned by their tile (`TileState::welds`)
+/// or placement (`Placement::entities`); a dead owner's batch is discarded. Runs right after
+/// `spawn_loaded_placements` in the Stream chain.
 pub(super) fn flush_hull_welds(
     mut commands: Commands,
     welds: ResMut<HullWelds>,
@@ -186,10 +146,8 @@ pub(super) fn flush_hull_welds(
     });
 }
 
-/// One closed batch → one off-thread trimesh build, carrying exactly what an individual hull
-/// carried: default layers (both audiences), the pick clamp, and — unless the 1367 lever bares
-/// it — a static body. Tagged for the census/inspector so the row is nameable, but with no
-/// `PickMesh`/`PickBox` it is not pickable (0929: pick geometry is declared, never inferred).
+/// One closed batch as one off-thread trimesh build with a single hull's components: default
+/// layers, the pick clamp and a static body unless `doodad_hulls_bare`. Not pickable.
 fn spawn_weld(commands: &mut Commands, acc: &mut WeldAcc) -> Entity {
     let verts = std::mem::take(&mut acc.verts);
     let tris = std::mem::take(&mut acc.tris);
@@ -259,8 +217,6 @@ mod tests {
         }
     }
 
-    /// Appending rebases indices onto the running vertex count — two 3-vert hulls weld into one
-    /// 6-vert soup whose second triangle indexes past the first.
     #[test]
     fn append_rebases_indices() {
         let mut welds = HullWelds::default();
@@ -274,8 +230,6 @@ mod tests {
         assert_eq!(welds.unflushed(), 1);
     }
 
-    /// A batch past the hull cap flushes on the next pass, and the weld entity lands in its
-    /// owner tile's `welds` (the despawn list).
     #[test]
     fn cap_flush_ties_weld_to_tile() {
         let mut app = test_app();
@@ -299,7 +253,6 @@ mod tests {
         assert!(app.world().get::<PickOccluder>(owned[0]).is_some());
     }
 
-    /// An under-cap batch holds while appends keep landing, then closes after the idle tail.
     #[test]
     fn idle_tail_closes_a_quiet_batch() {
         let mut app = test_app();
@@ -323,7 +276,6 @@ mod tests {
         assert_eq!(streamer.tiles.get(&(0, 0)).unwrap().welds.len(), 1);
     }
 
-    /// An accumulator whose owner tile is gone is discarded — no weld entity, no leak.
     #[test]
     fn dead_owner_discards_the_batch() {
         let mut app = test_app();
@@ -340,8 +292,6 @@ mod tests {
         assert_eq!(app.world().entities().len(), before);
     }
 
-    /// A prop batch flushes into its placement's entity list — the lifetime the individual
-    /// hulls had.
     #[test]
     fn prop_weld_lands_in_placement_entities() {
         let mut app = test_app();
diff --git a/crates/benilla-world/src/terrain_stream/window.rs b/crates/benilla-world/src/terrain_stream/window.rs
index e580d7b3..4d4cd111 100644
--- a/crates/benilla-world/src/terrain_stream/window.rs
+++ b/crates/benilla-world/src/terrain_stream/window.rs
@@ -1,24 +1,14 @@
-//! **The residency window** — how far around the view focus terrain is kept resident, derived
-//! from `farclip` exactly as the reference derives it (decision 1513).
+//! The residency window, derived from `farclip` (177..777) as the reference derives it:
+//! `SetFarClip` (`0x6725d0`) sets `r = 1 + trunc(farclip / 33.333)` chunks, and the world tick
+//! (`0x672730`) centres two windows on the viewer's chunk, the inner `idx ± r` (must be resident)
+//! and the outer `idx ± max(r + 2, 8)` (requested ahead, built under 5 ms a frame). Eviction is
+//! membership in the outer window, by tile (`[area+0x88]` vs `bounds >> 4`).
 //!
-//! The reference has one view-distance setting, the `farclip` CVar (the Video Options "Terrain
-//! Distance" slider, 177..777), and streams *from* it: `SetFarClip 0x6725d0` computes
-//! `r = 1 + trunc(farclip / 33.333)` **chunks** once, and the per-frame world tick (`0x672730`)
-//! centres two nested square windows on the viewer's chunk — the **inner** `idx ± r` (terrain that
-//! must be resident: the farclip disc rounded out to whole chunks) and the **outer**
-//! `idx ± max(r + 2, 8)` (requested ahead, built under a 5 ms/frame budget; the 8-chunk floor is
-//! 266⅔ yd). Eviction is pure membership in the outer window, at tile granularity (`[area+0x88]`
-//! vs `bounds >> 4`). Every number here is VERIFIED at the bytes — wow-re `terrain.md`,
-//! "Streaming residency", and `scratch/streaming-residency-and-forced-load.md` §1–§2.
-//!
-//! Two deliberate differences from the reference, both named in 1513:
-//! - **Whole tiles.** benilla loads, spawns and releases ADT tiles, not chunks; a tile is wanted iff
-//!   any of its chunks lies in the outer window. The reference builds chunk-by-chunk inside the
-//!   same windows, so the edge of its resident world is a chunk line and ours is a tile line.
-//! - **A one-chunk keep band** ([`KEEP_BAND_CHUNKS`]). The reference releases by membership alone
-//!   because its reload is a cheap async read; ours re-decodes and re-spawns a tile (B181's
-//!   frame spike), so a tile is wanted inside `outer` and released only past `outer + 1` —
-//!   hysteresis against a body pacing across the one chunk line that toggles a far tile.
+//! - Deviation: whole tiles, because benilla loads, spawns and releases ADT tiles, not chunks: a
+//!   tile is wanted when any of its chunks lies in the outer window, so the resident edge is a
+//!   tile line where the reference's is a chunk line.
+//! - Deviation: a one-chunk keep band ([`KEEP_BAND_CHUNKS`]), because a tile reload re-decodes and
+//!   re-spawns where the reference's is a cheap read: a tile releases only past `outer + 1`.
 
 use benilla_formats::{world_to_chunk, CHUNK_SIZE, TILE_SIZE};
 
@@ -26,15 +16,15 @@ use benilla_formats::{world_to_chunk, CHUNK_SIZE, TILE_SIZE};
 const CHUNKS_PER_TILE: i32 = 16;
 /// Chunk indices run `0..=1023` (64 tiles × 16), matching the reference's `[0, 0x3ff]` clamp.
 const CHUNK_MAX: i32 = 64 * CHUNKS_PER_TILE - 1;
-/// The outer window's floor in chunks — `max(r + 2, 8)` (`0x672966`–`0x67297b`).
+/// The outer window's floor in chunks: `max(r + 2, 8)` (`0x672966`–`0x67297b`).
 const OUTER_FLOOR_CHUNKS: i32 = 8;
-/// Chunks the outer window grows by for the *release* test only (see the module docs).
+/// Chunks the outer window grows by for the release test only.
 pub const KEEP_BAND_CHUNKS: i32 = 1;
 
 /// The two nested windows around one focus chunk, in chunk units on the tile-grid axes.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct StreamWindow {
-    /// The focus's chunk index `(chunk_x, chunk_y)` — the same axes as the tile grid.
+    /// The focus's chunk index `(chunk_x, chunk_y)`, on the tile grid's axes.
     pub focus: (i32, i32),
     /// Inner half-width in chunks: `1 + trunc(farclip / CHUNK_SIZE)`.
     pub inner: i32,
@@ -62,8 +52,7 @@ impl StreamWindow {
         )
     }
 
-    /// The inclusive tile range `((min_x, min_y), (max_x, max_y))` touched by the outer window
-    /// grown by `band` chunks, clamped to the 64×64 tile grid.
+    /// The tile range the outer window grown by `band` chunks touches, clamped to the grid.
     fn tile_range(&self, band: i32) -> ((i32, i32), (i32, i32)) {
         let half = self.outer + band;
         let lo = |c: i32| (c - half).clamp(0, CHUNK_MAX) / CHUNKS_PER_TILE;
@@ -74,7 +63,7 @@ impl StreamWindow {
         )
     }
 
-    /// Every tile the outer window touches — the set the streamer wants resident, in grid order.
+    /// Every tile the outer window touches, in grid order: the set the streamer wants resident.
     pub fn wanted_tiles(&self) -> Vec<(i32, i32)> {
         let ((x0, y0), (x1, y1)) = self.tile_range(0);
         let mut out = Vec::with_capacity(((x1 - x0 + 1) * (y1 - y0 + 1)) as usize);
@@ -86,30 +75,26 @@ impl StreamWindow {
         out
     }
 
-    /// Does the window still *keep* this tile — is it inside the outer window plus the keep band?
-    /// A resident tile that is not kept is stale and releases.
+    /// Whether a tile is inside the outer window plus the keep band.
     pub fn keeps(&self, tile: (i32, i32)) -> bool {
         let ((x0, y0), (x1, y1)) = self.tile_range(KEEP_BAND_CHUNKS);
         (x0..=x1).contains(&tile.0) && (y0..=y1).contains(&tile.1)
     }
 }
 
-/// The inner half-width in chunks for a view distance — `1 + trunc(farclip / 33.333)`
-/// (`0x6725e9 fmul −0.03 · __ftol · 1 − eax`). 777 ⇒ 24, 350 ⇒ 11, 177 ⇒ 6.
+/// The inner half-width in chunks, `1 + trunc(farclip / 33.333)` (`0x6725e9`: `fmul −0.03`,
+/// `__ftol`, `1 − eax`): 777 ⇒ 24, 350 ⇒ 11, 177 ⇒ 6.
 pub fn inner_radius(farclip: f32) -> i32 {
     1 + (farclip / CHUNK_SIZE).trunc() as i32
 }
 
-/// The outer half-width in chunks for an inner one — `max(inner + 2, 8)`.
+/// The outer half-width in chunks: `max(inner + 2, 8)`.
 pub fn outer_radius(inner: i32) -> i32 {
     (inner + 2).max(OUTER_FLOOR_CHUNKS)
 }
 
-/// How far, in yards, the corner of any tile this window can hold resident may lie from the
-/// focus — the bound a within-map art sweep must clear so it never evicts what the streamer is
-/// still holding (`art_scope::radius_floor`). A kept tile's far edge lies at most
-/// `outer + band + 16` chunks out per axis (the window's edge chunk plus the rest of that whole
-/// tile), on both axes at once at the corner.
+/// The farthest, in yards, a resident tile's corner can lie from the focus: the floor an art sweep
+/// must clear (`art_scope::radius_floor`) so it never evicts what the streamer still holds.
 pub fn max_resident_reach_yd(farclip: f32) -> f32 {
     let half = outer_radius(inner_radius(farclip)) + KEEP_BAND_CHUNKS + CHUNKS_PER_TILE;
     half as f32 * CHUNK_SIZE * std::f32::consts::SQRT_2 + TILE_SIZE
@@ -120,8 +105,7 @@ mod tests {
     use super::*;
     use benilla_formats::tile_to_world;
 
-    /// The radii are the bytes': 777 ⇒ 24/26, the registrar default 350 ⇒ 11/13, and at the
-    /// 177 floor the outer window sits on its 8-chunk floor, not at inner + 2.
+    /// 350 is the registered default; at 177 the outer window sits on its 8-chunk floor.
     #[test]
     fn the_radii_are_the_references() {
         assert_eq!(inner_radius(777.0), 24);
@@ -135,7 +119,7 @@ mod tests {
         assert_eq!(inner_radius(CHUNK_SIZE * 3.0 + 0.01), 4);
     }
 
-    /// A WoW-space point in chunk (5, 9) of tile (32, 44): the chunk index is that chunk.
+    /// The window at the centre of `chunk` in `tile`.
     fn at_chunk(farclip: f32, tile: (u32, u32), chunk: (i32, i32)) -> StreamWindow {
         let (ox, oy) = tile_to_world(tile.0, tile.1);
         let wy = oy - (chunk.0 as f32 + 0.5) * CHUNK_SIZE;
@@ -143,10 +127,8 @@ mod tests {
         StreamWindow::at(farclip, wx, wy)
     }
 
-    /// At 777 the outer window reaches 26 chunks — 1 tile + 10 chunks — so from a chunk in the
-    /// tile's middle band (5..=9) it touches two tiles each way (5×5), and from a chunk near an
-    /// edge only one tile on that side (4×4 at the corner chunk). The old fixed 5×5 was the
-    /// worst case of this, every time.
+    /// At 777 the outer window reaches 26 chunks: two tiles each way from the middle band (5×5);
+    /// from a corner chunk, two behind and one ahead (4×4).
     #[test]
     fn the_wanted_block_follows_the_focus_chunk() {
         let w = at_chunk(777.0, (32, 44), (7, 7));
@@ -165,16 +147,13 @@ mod tests {
         assert!(!tiles.contains(&(34, 44)));
     }
 
-    /// At the registrar default 350 the outer window is 13 chunks (433 yd): a 2×2 to 3×3 block —
-    /// the working set the slider is for.
+    /// At 350 the outer window is 13 chunks (433 yd): a 2×2 to 3×3 block.
     #[test]
     fn a_shorter_view_distance_wants_fewer_tiles() {
         assert_eq!(at_chunk(350.0, (32, 44), (7, 7)).wanted_tiles().len(), 9);
         assert_eq!(at_chunk(350.0, (32, 44), (15, 15)).wanted_tiles().len(), 4);
     }
 
-    /// The keep band is one chunk: a tile the outer window's edge just left is still kept, and
-    /// one a chunk further out is not.
     #[test]
     fn the_keep_band_is_one_chunk_of_hysteresis() {
         // From chunk 11 the outer window (26) reaches forward to chunk 37 = tile +2, chunk 5.
@@ -194,7 +173,6 @@ mod tests {
         }
     }
 
-    /// The windows clamp at the map's edge instead of naming tiles that do not exist.
     #[test]
     fn the_window_clamps_to_the_grid() {
         let w = at_chunk(777.0, (0, 63), (0, 15));
@@ -206,16 +184,13 @@ mod tests {
         assert!(w.keeps((0, 63)) && !w.keeps((-1, 63)) && !w.keeps((0, 64)));
     }
 
-    /// The art-scope floor clears the far corner of the widest block 777 can hold, and grows
-    /// with the view distance.
     #[test]
     fn the_resident_reach_bounds_the_block() {
         let reach = max_resident_reach_yd(777.0);
         // (26 + 1 + 16) chunks = 43 × 33⅓ = 1433 yd per axis; the corner is √2 of that, plus a tile.
         assert!((reach - (43.0 * CHUNK_SIZE * std::f32::consts::SQRT_2 + TILE_SIZE)).abs() < 0.01);
         assert!(max_resident_reach_yd(350.0) < reach);
-        // A wanted tile's far corner is inside the reach (worst case: the focus at a chunk's
-        // near edge, the tile at the window's far edge).
+        // A wanted tile's far corner lies inside the reach.
         let w = at_chunk(777.0, (32, 44), (9, 9));
         let (fx, fy) = (w.focus.0 as f32, w.focus.1 as f32);
         let far = w
diff --git a/crates/benilla-world/src/thread_qos.rs b/crates/benilla-world/src/thread_qos.rs
index 15f7c118..91a0c82a 100644
--- a/crates/benilla-world/src/thread_qos.rs
+++ b/crates/benilla-world/src/thread_qos.rs
@@ -1,21 +1,13 @@
-//! macOS thread QoS: keep frame-critical threads on the P-cores under system load.
-//!
-//! Apple Silicon schedules by QoS class, not fairness: a default-QoS thread queues behind any
-//! higher class for P-core time. The main thread is user-interactive out of the box (verified by
-//! probe — even bare `cargo run`, no bundle), but every worker Bevy spawns — compute pool, IO
-//! pool, the pipelined-rendering thread — starts at default, the same class as `rustc` or an OBS
-//! encoder. Under a background build the frame's own workers wait in the compiler's queue and the
-//! client drops to 20 fps while the retail client (whose workers are promoted, plus Game Mode)
-//! holds steady. Promoting the workers is the per-thread half of that story; the Game Mode half
-//! needs an app bundle and is release-track (decision 0609).
-//!
-//! `pthread_set_qos_class_self_np` is not bound by the `libc` crate, so the extern lives here.
-//! Everything is a no-op off macOS.
+//! macOS thread QoS: keep frame-critical threads on the P-cores under system load. Apple Silicon
+//! schedules by QoS class, and the main thread is user-interactive, but every worker Bevy spawns
+//! starts at default, the class of `rustc`, so a background build starves the frame's workers.
+//! `pthread_set_qos_class_self_np` is not in the `libc` crate, so the extern lives here; everything
+//! is a no-op off macOS.
 
 use bevy::prelude::*;
 use bevy::render::{Render, RenderApp, RenderSystems};
 
-/// QoS classes we actually use. Values are Darwin's `qos_class_t`.
+/// The QoS classes used here, as Darwin's `qos_class_t`.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[repr(u32)]
 pub enum QosClass {
@@ -23,21 +15,15 @@ pub enum QosClass {
     UserInteractive = 0x21,
     /// Work the frame is waiting on soon but not this frame (asset IO, async compute, net IO).
     UserInitiated = 0x19,
-    /// Darwin's unspecified/default class — where a *thread that will block for seconds* belongs.
-    /// Apple's duration table calls user-interactive "virtually instantaneous" and user-initiated
-    /// "a few seconds or less"; a multi-second shader-compile burst is neither. Metal's compiler
-    /// runs the compile at the **calling thread's** QoS, and Apple's own prescription for
-    /// pipeline prewarming is exactly this class (WWDC25 "Explore Metal 4 games":
-    /// "Set QoS class to default for pipeline prewarming and streaming", with sample code using
-    /// `QOS_CLASS_DEFAULT`). Decision 1117.
+    /// Darwin's default class, for a thread that blocks for seconds: Metal compiles at the calling
+    /// thread's QoS, and Apple prescribes this class for pipeline prewarming (WWDC25, "Explore
+    /// Metal 4 games").
     Default = 0x15,
 }
 
-/// Set while the *covered* pipeline-warm burst runs (decision 1117): the render thread spends
-/// that window blocked inside Metal pipeline compilation, and there is no frame to protect —
-/// the loading cover is a still image. Published by `pipe_warm`, applied by
-/// [`promote_render_thread`] on the render thread itself, which is the only thread that can set
-/// its own QoS.
+/// Set by `pipe_warm` while the covered pipeline-warm burst blocks the render thread in Metal
+/// compilation; [`promote_render_thread`] then drops that thread to `Default` from inside, since
+/// only a thread can set its own QoS.
 pub static COMPILE_BURST: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
 
 /// Promote the calling thread to `class`. Safe to call repeatedly; logs once on failure.
@@ -56,17 +42,9 @@ pub fn promote_current_thread(class: QosClass) {
     let _ = class;
 }
 
-/// Promotes the pipelined-rendering thread. Task-pool threads are promoted at spawn via
-/// `TaskPoolOptions::on_thread_spawn` (see `main.rs`), but Bevy spawns the render thread with a
-/// bare `std::thread::spawn` and no hook. An exclusive system runs on whichever thread drives the
-/// render schedule — the main thread during startup, the render thread once pipelined rendering
-/// takes over — so it re-runs each frame behind a thread-local latch instead of `run_once`.
-///
-/// It sits in `ExtractCommands`, the schedule's first set, beside bevy's own exclusive
-/// `apply_extract_commands`: an exclusive system is a barrier (the executor drains every running
-/// system before it and restarts the fan-out after), and at that point nothing is in flight to
-/// drain. Until 1697's scan named it, it lived in `Prepare` and cut that set's parallel
-/// prepare fan-out in two on every frame of every run — for a latch that fires once.
+/// Promotes the pipelined-rendering thread, which Bevy spawns with no hook. The exclusive system
+/// runs on whichever thread drives the render schedule, so it re-checks each frame behind a
+/// thread-local latch; it sits in `ExtractCommands`, where its barrier has nothing to drain.
 pub struct ThreadQosPlugin;
 
 impl Plugin for ThreadQosPlugin {
@@ -81,7 +59,7 @@ impl Plugin for ThreadQosPlugin {
     }
 }
 
-/// Read back the calling thread's QoS class (support for the macOS-only tests below).
+/// The calling thread's QoS class, for the tests.
 #[cfg(all(test, target_os = "macos"))]
 fn current_thread_qos() -> Option<u32> {
     unsafe extern "C" {
@@ -98,8 +76,7 @@ fn current_thread_qos() -> Option<u32> {
 }
 
 fn promote_render_thread(_world: &mut World) {
-    // The class this thread should be in *right now*: its normal frame-critical band, or the
-    // default band while it is the shader compiler's caller under a cover (1117).
+    // Frame-critical, or default while it is the shader compiler's caller under a cover.
     let want = if COMPILE_BURST.load(std::sync::atomic::Ordering::Relaxed) {
         QosClass::Default
     } else {
@@ -124,7 +101,6 @@ fn promote_render_thread(_world: &mut World) {
 mod tests {
     use super::*;
 
-    /// The promotion really lands: a fresh (default-QoS) thread reads back the class it set.
     #[test]
     fn promotion_applies_to_spawned_thread() {
         for class in [QosClass::UserInteractive, QosClass::UserInitiated] {
@@ -135,17 +111,14 @@ mod tests {
             })
             .join()
             .unwrap();
-            // A bare std thread spawns at default (0x15) — the gap this module closes.
+            // A bare std thread spawns at default (0x15).
             assert_eq!(observed.0, Some(0x15), "spawned thread not default-QoS");
             assert_eq!(observed.1, Some(class as u32), "promotion did not apply");
         }
     }
 
-    /// A spawned thread does NOT inherit its spawner's QoS class — it lands at default even when
-    /// the spawner is user-interactive. This is the load-bearing fact of decision 1109: kira
-    /// spawns its per-stream decode threads from the (promoted) main thread, and without
-    /// inheritance those threads sit *below* the promoted worker pools and starve under the
-    /// world-entry burst — hence `sound::mixer::PromotingSource` promoting from inside.
+    /// kira's decode threads, spawned from the promoted main thread, land at default too, which is
+    /// why `sound::mixer::PromotingSource` promotes from inside.
     #[test]
     fn qos_is_not_inherited_by_spawned_threads() {
         let (parent, child) = std::thread::spawn(|| {
diff --git a/crates/benilla-world/src/view.rs b/crates/benilla-world/src/view.rs
index 18e7d756..b27fcbe6 100644
--- a/crates/benilla-world/src/view.rs
+++ b/crates/benilla-world/src/view.rs
@@ -1,72 +1,38 @@
-//! **The view** — who is looking, with what optics, and how far the detailed world is drawn.
-//!
-//! Three things, one owner. [`WorldCamera`] marks *the* camera the scene is rendered through;
-//! [`CAM_FOVY`] is its fixed optic; [`ViewDistance`] is the faithful `nearclip`/`farclip` **pair**,
-//! which is the shape the reference keeps them in (2163).
-//!
-//! The marker and the optics were in `player::camera` until decision 1160's stage zero, and that
-//! was the single largest edge across the engine/game line: **26 engine files** — terrain
-//! streaming, the portal PVS, sun follow, picking, every effect sim — reached into the *player
-//! controller* to ask which camera to read. None of them care about a player; they care about the
-//! viewer, which a world editor and a serverless viewer have without one. `farclip` itself was
-//! promoted out of the debug panel earlier, for the same reason at a smaller scale: it was a
-//! `ModelDebug` field doing double duty, so it read as a debug knob rather than as config, and
-//! subsystems each kept their own idea of it.
-//!
-//! Read by: the hard far-clip **wall** (terrain/model/liquid/WDL/particle shaders, pushed as
-//! `fog_params.w` by `lighting::apply_wow_lighting`), the per-object **cull**
-//! (`model_render::apply_model_visibility`), the particle **draw-set gate**
-//! (`particles::sim::simulate_particles`) — both through [`within_farclip`] — and the terrain
-//! **residency window** (`terrain_stream::window`), which derives its reach from `farclip` the way
-//! the reference does (decision 1513). The player's lever is the Terrain Distance row of the
-//! options window (the `farclip` CVar); `$WOW_FARCLIP` is the headless one.
+//! The view: the camera the scene renders through ([`WorldCamera`]), its optic ([`CAM_FOVY`]),
+//! and how far the detailed world draws ([`ViewDistance`], the reference's `nearclip` and
+//! `farclip` pair). `farclip` bounds the per-pixel wall, the CPU cull ([`within_farclip`]) and
+//! the terrain residency window (`terrain_stream::window`), which derives its reach from it as the
+//! reference does.
 
 use bevy::prelude::*;
 
-/// **The viewer's own body**, as the world needs it — 1160's wire (a), the half that is not about
-/// where to stream.
-///
-/// Three engine lanes read the game's avatar for the same three facts and behind the *same*
-/// predicate (`active && !detached`): the WMO interior probe wants the eye's world point, the
-/// water foam wants a wading body, the precipitation slab wants the commanded planar speed its
-/// tilt keys on. None of them wants a `Player` — they want a body that may or may not be there.
-///
-/// `None` on [`Self::at`] means exactly what each of those sites used to spell out by hand: no
-/// live avatar, or an eye that has been detached from it. A program with no avatar at all leaves
-/// this defaulted and every lane takes its no-body branch, which is what the world viewer needs.
+/// The viewer's own body, as the world needs it: the eye point for the WMO interior probe, a wading
+/// body for the water foam, the commanded speed for the precipitation tilt. Defaulted, it is no
+/// body at all, which is what the world viewer runs with.
 #[derive(Resource, Clone, Copy)]
 pub struct Viewer {
-    /// The avatar's position in **Bevy** space, when one is live and the eye is on it.
+    /// The avatar's position in Bevy space; `None` with no live avatar or a detached eye.
     pub at: Option<Vec3>,
-    /// Its last-streamed CMovement flags (`MOVEMENTFLAGS`, cached at `unit+0x9e8`). `0` with no
-    /// body. Read through [`Self::translating`] / [`Self::turning`] rather than masked at each
-    /// site — the bit values are the wire's, and one restatement of them is one too many already.
+    /// Its last-streamed `MOVEMENTFLAGS` (the reference caches them at `unit+0x9e8`); 0, no body.
     pub move_flags: u32,
-    /// The **commanded** planar speed in yd/s (`[[player+0x118]+0x84]`): exactly zero with no
-    /// direction key held, live rather than a decayed measurement.
+    /// The commanded planar speed in yd/s (`[[player+0x118]+0x84]`), zero with no direction key.
     pub planar_speed: f32,
-    /// Its collision cylinder height in yards — the foam ring's radius input.
+    /// Its collision cylinder height in yards, the foam ring's radius input.
     pub height: f32,
-    /// The **first-person feather**: how opaque the viewer's own body is as the camera zooms into
-    /// it. `1.0` normally, ramping to `0.0` at full zoom-in. A property of the eye's relationship
-    /// to the body, which is why it rides here and not on the body.
+    /// The first-person feather: the body's opacity, `1.0` normally, `0.0` at full zoom-in.
     pub self_fade: f32,
-    /// **Drunkenness**, `0.0..=1.0` — `PLAYER_BYTES_3` byte 1 clamped at 100. The full-screen haze
-    /// is a property of the eye, not of any body in the scene.
+    /// Drunkenness, `0.0..=1.0`: `PLAYER_BYTES_3` byte 1, clamped at 100; the full-screen haze.
     pub drunk: f32,
-    /// Is the viewer a **ghost**? While the flag is up the active `LightParams` slot is 4 — the
-    /// death profile, applied instantly (decision 0308 §7, byte-verified `death-light.md`).
+    /// A ghost: the active `LightParams` slot is 4, the death profile, applied instantly
+    /// (`0x6d4620` sets it, `0x6d2260` re-derives it every frame).
     pub ghost: bool,
-    /// Is a loading cover over the world right now, so the viewer has not actually *seen* anything
-    /// yet? The appear ramp arms on this falling edge — the faithful trigger is "the player can
-    /// see the entity", and the residency proxy goes true well before the cover drops now that
-    /// the clear waits for the whole scene (decision 0737).
+    /// A loading cover is over the world. The appear ramp arms on its falling edge, since the
+    /// reference's trigger is the player seeing the entity.
     pub world_covered: bool,
 }
 
 impl Default for Viewer {
-    /// No body, and **nothing covering the world** — the defaults a program with no game boots
-    /// with. `self_fade` is `1.0`: absent an eye-to-body relationship, nothing is feathered.
+    /// No body and nothing covering the world; `self_fade` 1.0, nothing feathered.
     fn default() -> Self {
         Self {
             at: None,
@@ -82,120 +48,62 @@ impl Default for Viewer {
 }
 
 impl Viewer {
-    /// Is the body **translating**? The four direction bits (`& 0xf`) — the same test the
-    /// reference's water-ripple driver runs (`0x5fa760`).
+    /// The body is translating: the four direction bits (`& 0xf`), the test the reference's
+    /// water-ripple driver runs (`0x5fa760`).
     pub(crate) fn translating(&self) -> bool {
         self.move_flags & 0xf != 0
     }
 
-    /// Is it **turning in place**? The two keyboard turn bits (`& 0x30`). Strafe slides without
-    /// turning and is covered by [`Self::translating`]; a mouse-look body-step sets no flag at all.
+    /// The body is turning in place: the two keyboard turn bits (`& 0x30`). A strafe is
+    /// [`Self::translating`]; a mouse-look body step sets no flag.
     pub(crate) fn turning(&self) -> bool {
         self.move_flags & 0x30 != 0
     }
 }
 
-/// View distance in yards. `farclip` = WoW's `farclip` CVar — the ONE view distance: the far plane of
-/// the detailed world (geometry beyond it is clipped per-pixel, the wall, and the WDL horizon fills
-/// in beyond) **and** the reach of terrain residency (`terrain_stream::window`, decision 1513).
-/// Default **350** — the reference client's own registered default (decision 1624, superseding
-/// 0954's divergence to the clamp's max 777). 777 shipped as "the `Config.wtf` most players ran",
-/// but it is the *maximum*, and it is what every player gets before they touch anything: at 777 the
-/// residency window is 24 chunks per axis against 350's 11 ([`terrain_stream::window::inner_radius`]),
-/// ~4.8x the area streamed, drawn and held resident. The slider still reaches 777.
-///
-/// **`nearclip` is the second half of the same resource, because the reference stamps them
-/// together** (2163). Its per-frame camera outer `0x511bc0` reads both CVar records and writes the
-/// camera in four instructions, unconditionally, before the `[cam+0x48]` branch that picks the
-/// cinematic leg:
-///
-/// ```text
-/// 511bcf  mov  eax,[0xbe1078]        ; the `nearclip` record handle (cached by 0x50b728's Lookup)
-/// 511bd4  fld  dword [eax+0x24]      ; the record's float
-/// 511bdc  fstp dword [esi+0x38]      ; cam near
-/// 511bdf  mov  ecx,[0xbe0cc0]        ; the `farclip` record handle
-/// 511be5  fld  dword [ecx+0x24]
-/// 511be8  fstp dword [esi+0x3c]      ; cam far
-/// ```
-///
-/// So `nearclip` is a **live** setting there, not dead plumbing — see [`NEARCLIP_RANGE`] for the
-/// half-truth this field replaced.
+/// View distance in yards. `farclip`, the `farclip` CVar, is the one view distance: the detailed
+/// world's far wall and the reach of terrain residency; its default, 350, is the reference's
+/// registered one.
+/// `nearclip` shares the resource because `0x511bc0` stamps both onto the camera every frame, the
+/// `nearclip` record's float to `[cam+0x38]` (`0x511bd4`) and the `farclip` one's to `[cam+0x3c]`.
 #[derive(Resource, Clone, Copy)]
 pub struct ViewDistance {
     pub farclip: f32,
-    /// The camera **near-plane** distance in yards — WoW's `nearclip` CVar, re-stamped onto the
-    /// projection every frame by [`stamp_near_clip`] exactly as `0x511bc0` re-stamps `[cam+0x38]`.
+    /// The camera near plane in yards, the `nearclip` CVar ([`stamp_near_clip`]).
     pub nearclip: f32,
 }
 
-/// The settable range of [`ViewDistance::farclip`] — the vanilla `farclip` CVar clamp `[177, 777]`
-/// (validate callback `0x688d40`, wow-re `terrain.md` "Camera-distance CVars"), shared by the CVar
-/// apply, the options row and the `$WOW_FARCLIP` env knob so none can drift. It used to run to 1200
-/// as an A/B lever against the pre-wall "draw everything in the tile window" look; that look is
-/// gone and the window now follows this number, so the headroom went with it (1513).
+/// The settable range of [`ViewDistance::farclip`]: the reference's `farclip` clamp,
+/// `[0x81021c]` = 177 to `[0x80fed8]` = 777 in its validate callback `0x688d40`; shared by the
+/// CVar apply, the options row and `$WOW_FARCLIP`.
 pub const FARCLIP_RANGE: std::ops::RangeInclusive<f32> = 177.0..=777.0;
 
-/// The settable range of [`ViewDistance::nearclip`] — the vanilla `nearclip` CVar clamp, read off
-/// its own change callback `0x688d90` the way [`FARCLIP_RANGE`] is read off `0x688d40`: the two
-/// bounds are the f32s at `[0x8029d0]` = `0.01` and `[0x808300]` = `0.33`, and a value outside them
-/// is **refused** (the callback returns 0 after echoing `0x869abc` `"NearClip must be in range 0.01
-/// - 0.33"`), not clamped. Our apply clamps instead, which is this table's standing posture for
-/// every range (the consumer clamps at its own edge — `script::cvars`' module doc).
+/// The settable range of [`ViewDistance::nearclip`]: the bounds in the reference's `nearclip`
+/// change callback `0x688d90`, `[0x8029d0]` = 0.01 and `[0x808300]` = 0.33.
 ///
-/// **Positive control for that decode:** the same shape at `0x688d40` yields `[0x81021c]` = `177`
-/// and `[0x80fed8]` = `777`, which is [`FARCLIP_RANGE`] as it has stood since 1624.
-///
-/// **This const is the correction of a verified-but-partial finding** (2163). [`NEARCLIP_DEFAULT`]
-/// used to be a hardcoded `1.0 / 9.0` named `CAM_NEAR`, documented as "the reference's own 1/9,
-/// hardcoded in its camera ctor (`0x50a6c0`: `+0x38 = 0x3de38e39`) — the `nearclip` console cvar
-/// stores to a global with zero readers, dead plumbing". Every clause of that is true and the
-/// conclusion is wrong: the *derived global* `[0xc7b480]` is indeed dead (wow-re
-/// `cvar/scratch/graphics-cost-cvar-census.md` §8 lists it), but the camera never reads that global
-/// — it reads the **record**, every frame, at `0x511bd4`. So the ctor's 1/9 is the value the camera
-/// holds for exactly as long as it takes the first frame's outer to overwrite it, and is never
-/// rendered with. `worldview`'s own near plane had already drifted to `0.1` under a doc claiming it
-/// was "kept in step by hand" with the 1/9 — the drift was the tell.
+/// Deviation: the reference refuses a value outside them, echoing "NearClip must be in range
+/// 0.01 - 0.33" (`0x869abc`); ours clamps, as every CVar consumer here clamps at its own edge.
 pub const NEARCLIP_RANGE: std::ops::RangeInclusive<f32> = 0.01..=0.33;
 
-/// The world camera's multisampling level — WoW's **`gxMultisample`** CVar.
+/// The world camera's multisampling, the `gxMultisample` CVar: a sample count in [`MSAA_RANGE`],
+/// 1 meaning none, as both reference backends read it (D3D9 `0x599899`, GL `0x59de32`). Its
+/// default, 1, is the reference's: `CVar::Register` (`0x63a950`) takes it from the
+/// `VideoHardware.dbc` row `DetectHardware` (`0x641260`) matched, and every fallback row holds 1.
 ///
-/// Held on the reference's own scale: a **sample count**, clamped to [`MSAA_RANGE`] (`[1, 16]`,
-/// the reference's own clamp in the CVar callback at `0x63b250`), where **1 means no
-/// multisampling at all** — not "one sample of MSAA". Both of the reference's device backends read
-/// it that way: D3D9 at `0x599899` leaves `pp.MultiSampleType` at `D3DMULTISAMPLE_NONE` for any
-/// value `<= 1`, and the GL path at `0x59de32` never writes the `WGL_SAMPLE_BUFFERS_ARB` /
-/// `WGL_SAMPLES_ARB` pair at all — the attribute list simply terminates where they would begin.
-/// (wow-re `system/console/scratch/gxmultisample-default.md`, §5-verified 2026-08-26.)
-///
-/// **Default 1 — off — and that is the reference's own default, not a perf choice dressed up as
-/// fidelity.** The reference does not register a literal here: `CVar::Register` at `0x63a950` is
-/// handed a string `snprintf("%d")`'d at runtime from field 21 of the `VideoHardware.dbc` row that
-/// `DetectHardware` (`0x641260`) matched the GPU to. Across the shipped 193-row table that field
-/// only ever holds 1 (144 rows) or 2 (49 rows) — nothing higher exists anywhere in it — and all
-/// three rows reachable by the fallback match hold **1**. Every id in the table is 2004-era, so no
-/// modern GPU matches a specific row and the fallback is what answers: the string registered on
-/// any machine this client actually runs on today is `"1"`. Decision 1629.
-///
-/// **Latched, like the reference's own flag byte** (`CVar::Register` flags `3` = registered |
-/// latched; the callback echoes `"set pending gxRestart"`). The value here is the **pending** one:
-/// changing it persists and `GetCVar` reports it, but the device — here, the camera's `Msaa`
-/// component — keeps what it was born with until the next launch. That is not a limitation we are
-/// working around; it is the reference's behaviour, and it happens to be forced on us anyway,
-/// since swapping MSAA live leaves our post passes MSAA-mismatched and freezes the view.
+/// Latched, as the reference registers it ("set pending gxRestart"): a change persists, but the
+/// camera keeps its `Msaa` until the next launch (swapping it live would freeze our post passes).
 #[derive(Resource, Clone, Copy, PartialEq, Eq, Debug)]
 pub struct MsaaSetting {
-    /// The requested sample count, `[1, 16]`. 1 = no multisampling.
+    /// The requested sample count; 1 is none.
     pub samples: u32,
 }
 
-/// The settable range of [`MsaaSetting::samples`] — the reference's own `atoi`-then-clamp `[1, 16]`
-/// at `0x63b250`. Shared by the CVar apply and the `$WOW_MSAA` env knob so the two cannot drift.
+/// The settable range of [`MsaaSetting::samples`]: the reference's `atoi`-then-clamp at
+/// `0x63b250`.
 pub const MSAA_RANGE: std::ops::RangeInclusive<u32> = 1..=16;
 
 impl Default for MsaaSetting {
-    /// `$WOW_MSAA` overrides the default, **session-only** — the A/B lever, the same posture as
-    /// `$WOW_FARCLIP` (a value pinned into `config.toml` would make a measurement sticky). The
-    /// spellings it has always accepted are kept: `off`/`0`/`1` all mean none.
+    /// `$WOW_MSAA` overrides the default for the session; `off`, `0` and `1` all mean none.
     fn default() -> Self {
         let samples = match std::env::var("WOW_MSAA").ok().as_deref() {
             Some("off") => Some(1),
@@ -208,13 +116,9 @@ impl Default for MsaaSetting {
 }
 
 impl MsaaSetting {
-    /// The sample count as a Bevy [`Msaa`](bevy::render::view::Msaa) level.
-    ///
-    /// wgpu can only express 1/2/4/8, while the reference's range runs to 16, so a request lands on
-    /// the **largest expressible level at or below it**. That direction is the reference's own: its
-    /// device-init retry loop (`0x63b380`) steps the sample count *down* — `-= 2`, floored at 1 —
-    /// and only once it bottoms out does it start giving up depth and colour bits. Nothing anywhere
-    /// steps it up, so rounding down can never hand a player more than they asked for.
+    /// The sample count as a Bevy [`Msaa`](bevy::render::view::Msaa) level: wgpu expresses only 1,
+    /// 2, 4 and 8, so a request rounds down, the direction the reference's device-init retry loop
+    /// steps (`0x63b380`, `-= 2` floored at 1).
     pub fn level(self) -> bevy::render::view::Msaa {
         use bevy::render::view::Msaa;
         match self.samples {
@@ -226,30 +130,9 @@ impl MsaaSetting {
     }
 }
 
-/// The sample counts this run's GPU actually accepts — the guard between a player's
-/// `gxMultisample` and a wgpu validation error.
-///
-/// **This closes a hazard [`MsaaSetting`] itself opened.** Decision 1629 made the sample count a
-/// real setting a player can type, and nothing between the CVar and the GPU asked whether the GPU
-/// could do it. Bevy does not ask either — `bevy_render`'s `prepare_view_targets` writes
-/// `sample_count: msaa.samples()` into the descriptor unchecked (`view/mod.rs:1142`). wgpu *does*:
-/// `wgpu-core` tests the count against the format's `sample_count_supported` and fails
-/// `CreateTextureError::InvalidSampleCount` (`device/resource.rs:1316`), then tests it again on
-/// every pipeline rendering into that texture (`:3882`, `:3961`, `:4013`). A validation error on a
-/// texture rebuilt every frame is not a graceful degrade; it is the client dying on a value the
-/// player was invited to type. `gxMultisample 8` on a device that stops at 4x is the live case.
-///
-/// **Stepping down is the reference's own answer, not a defensive invention.** Its device-init
-/// retry loop at `0x63b380` walks the sample count *down* (`-= 2`, floored at 1) until the device
-/// accepts a mode, and only once it bottoms out does it begin surrendering depth and colour bits.
-/// A request the hardware cannot meet becoming the nearest one it can is therefore the faithful
-/// behaviour; refusing to boot is what would be unfaithful.
-///
-/// The three formats are every one we multisample into: the world camera's off-screen colour target
-/// (`Rgba16Float` — `benilla_app::world_backdrop`), `Core3d`'s depth (`CORE_3D_DEPTH_FORMAT` =
-/// `Depth32Float`), and the swapchain format the world viewer and the fallback camera render
-/// straight into. A count is granted only if **all three** take it: they are separate capability
-/// bits in wgpu, and a device may well offer 8x colour alongside 4x depth.
+/// The sample counts this GPU accepts in all three formats we multisample into (the
+/// `Rgba16Float` target, `Depth32Float` depth, the swapchain), each a separate wgpu capability;
+/// Bevy passes a count on unchecked, and wgpu fails validation on one the device lacks.
 fn supported_sample_counts(adapter: &bevy::render::renderer::RenderAdapter) -> Vec<u32> {
     use bevy::image::BevyDefault as _;
     use bevy::render::render_resource::TextureFormat;
@@ -272,9 +155,7 @@ fn supported_sample_counts(adapter: &bevy::render::renderer::RenderAdapter) -> V
         .collect()
 }
 
-/// The largest count in `supported` at or below `requested`, floored at 1 — no multisampling, which
-/// no device can refuse. The step-*down* direction is the reference's; see
-/// [`supported_sample_counts`].
+/// The largest count in `supported` at or below `requested`, floored at 1, which no device refuses.
 pub fn clamp_to_supported(requested: u32, supported: &[u32]) -> u32 {
     supported
         .iter()
@@ -284,38 +165,17 @@ pub fn clamp_to_supported(requested: u32, supported: &[u32]) -> u32 {
         .unwrap_or(1)
 }
 
-/// The multisample formats this run's device accepts, as the Video options dropdown offers them —
-/// `(color_bits, depth_bits, samples)`, ascending.
-///
-/// The reference's distilled triple list (`[0xb4b444]`, count `[0xb4b440]`, built by `0x48c3e0` out
-/// of the D3D `CheckDeviceMultiSampleType` sweep or the GL `wglGetPixelFormatAttribivARB` sweep) —
-/// here, whatever wgpu says it will take. Filled by [`MsaaSupportPlugin`] from the same enumeration
-/// that does the clamping, so the list a player picks from and the ceiling a typed value is clamped
-/// to cannot disagree.
-///
-/// Empty until the adapter exists (and forever, headless): an empty dropdown is the honest answer
-/// for a run with no device, and the Lua walks it zero times.
+/// The multisample formats this device accepts, `(color_bits, depth_bits, samples)` ascending, for
+/// the Video options dropdown, as the reference's triple list at `[0xb4b444]` (built by
+/// `0x48c3e0`); empty with no adapter.
 #[derive(Resource, Default, Clone, Debug)]
 pub struct MsaaFormats {
     pub formats: Vec<(u32, u32, u32)>,
 }
 
 impl MsaaFormats {
-    /// `requested`, stepped DOWN to the nearest count this device actually offers.
-    ///
-    /// **The single expression of "the device has the final say"** (decision 1643). It used to
-    /// exist only inside [`MsaaSupportPlugin::finish`], which runs once, before the first update —
-    /// i.e. against whatever [`MsaaSetting::default`] seeded, and therefore *before*
-    /// `config.toml` had been folded in. The doc two paragraphs up already claimed that "the list
-    /// a player picks from and the ceiling a typed value is clamped to cannot disagree"; a typed
-    /// value was in fact never clamped to it at all, and a saved `gxMultisample = 8` opened on a
-    /// GPU that stops at 4 handed the camera an 8 — the 2026-08-26 render-thread kill, one launch
-    /// later and on a machine the setting was never chosen on.
-    ///
-    /// **An empty list is no opinion, not a refusal.** Headless, or before the adapter exists,
-    /// there is no device to be wrong about and `requested` passes through — the same early-out
-    /// `finish` takes when there is no `RenderAdapter`. Clamping to 1 there would turn every
-    /// device-less test and every worldview boot into a silent "multisampling off".
+    /// `requested`, stepped down to the nearest count this device offers, for the startup clamp
+    /// and every CVar write; an empty list (no adapter) passes it through.
     pub fn clamp(&self, requested: u32) -> u32 {
         if self.formats.is_empty() {
             return requested;
@@ -325,14 +185,8 @@ impl MsaaFormats {
     }
 }
 
-/// Colour and depth bit counts for the dropdown's label, derived from the formats we actually
-/// render into rather than typed: `MULTISAMPLING_FORMAT_STRING` is
-/// `"%d-bit color %d-bit depth %dx multisample"`, and a number in it should be true.
-///
-/// The colour figure is the **swapchain**'s, not the world camera's off-screen `Rgba16Float`
-/// target. What the dropdown is describing is the mode the window is presented in — the thing the
-/// reference's enumerators were asking the device about — and quoting 64 there would be describing
-/// an internal buffer no player chose.
+/// Colour and depth bits for the dropdown's `MULTISAMPLING_FORMAT_STRING`, from the formats we
+/// render into; colour is the swapchain's, the mode the window presents in.
 fn dropdown_bit_depths() -> (u32, u32) {
     use bevy::image::BevyDefault as _;
     use bevy::render::render_resource::TextureFormat;
@@ -344,17 +198,8 @@ fn dropdown_bit_depths() -> (u32, u32) {
     )
 }
 
-/// Clamps [`MsaaSetting`] to what this run's GPU accepts, once, before anything spawns a camera.
-///
-/// **All the work is in `finish`, deliberately** — the same reason as
-/// `benilla_assets::gpu_blp::BlpGpuSupportPlugin`: `RenderAdapter` is inserted into the main world
-/// by `RenderPlugin::finish` (`bevy_render/src/lib.rs:419`), so it does not exist at `build` time
-/// and never exists at all in a headless app. Every plugin's `finish` completes before the runner's
-/// first update, and the cameras read `MsaaSetting` in `Startup` (1629's latch), so this is both
-/// the earliest honest moment and comfortably early enough.
-///
-/// Headless — no adapter, or no setting — changes nothing: such a run builds no swapchain to be
-/// wrong about.
+/// Clamps [`MsaaSetting`] to this GPU and publishes [`MsaaFormats`], in `finish`, the first moment
+/// `RenderAdapter` exists and still before any camera spawns; headless, it does nothing.
 pub struct MsaaSupportPlugin;
 
 impl Plugin for MsaaSupportPlugin {
@@ -369,7 +214,7 @@ impl Plugin for MsaaSupportPlugin {
             Some(adapter) => supported_sample_counts(adapter),
             None => return,
         };
-        // Published whether or not anything needs clamping: this is the dropdown's whole menu.
+        // Published whether or not anything clamps: it is the dropdown's whole menu.
         let (color_bits, depth_bits) = dropdown_bit_depths();
         app.insert_resource(MsaaFormats {
             formats: supported
@@ -380,17 +225,13 @@ impl Plugin for MsaaSupportPlugin {
         let Some(requested) = app.world().get_resource::<MsaaSetting>().map(|m| m.samples) else {
             return;
         };
-        // Through `MsaaFormats::clamp`, not `clamp_to_supported` directly: this seed clamp and the
-        // per-write clamp in `cvars::apply_to_knobs` must be the same rule, or the pair drifts
-        // exactly the way the missing half already did (1643).
+        // Through `MsaaFormats::clamp`, the same rule as the app's per-write `gxMultisample`
+        // clamp (`video::on_cvar`).
         let granted = app.world().resource::<MsaaFormats>().clamp(requested);
         if granted == requested {
             debug!("msaa: {requested}x accepted (this GPU offers {supported:?})");
             return;
         }
-        // At `warn`, not `debug`: the player asked for something and did not get it, and this is
-        // the only place that fact exists. A line that survives only in a debug build cannot answer
-        // "why won't my setting stick?" from a player's log.
         warn!(
             "msaa: this GPU does not offer {requested}x — using {granted}x (it offers {supported:?})"
         );
@@ -398,32 +239,22 @@ impl Plugin for MsaaSupportPlugin {
     }
 }
 
-/// The world camera's projection far plane in yards — the **horizon** plane, far beyond `farclip`
-/// on purpose so the coarse WDL ring draws behind the wall (decision 0684; the reference's own
-/// `horizonfarclip` is a second plane floored at `farclip + 528`, default 2112). One number, not a
-/// function of anything: the detailed world ends at `farclip` by the wall, never by this plane.
+/// The world camera's projection far plane in yards. Deviation: the reference projects the
+/// detailed world to `farclip` and the horizon to `horizonfarclip` (default 2112, floored at
+/// `farclip + 528`); ours has one far plane well beyond `farclip`, because the WDL ring draws in
+/// the same projection, and the detailed world ends at `farclip` by the wall.
 pub const CAM_FAR: f32 = 3000.0;
 
 impl ViewDistance {
-    /// Set the near plane from a `nearclip` write, under the reference's own bounds.
-    ///
-    /// **A method and not a public [`NEARCLIP_RANGE`] for the CVar host to clamp against**, which
-    /// is how `farclip` does it — because `farclip`'s range has a second consumer (the Terrain
-    /// Distance slider is built with those bounds) and this one does not, and `benilla-app`
-    /// naming one more engine item is what `tests/world_api_wall.rs` exists to make expensive.
-    /// The knob owning its own clamp is also the shape `ClutterConfig::set_frill_density` settled
-    /// on for the same question (2151).
+    /// Set the near plane from a `nearclip` write, clamped to [`NEARCLIP_RANGE`].
     pub fn set_nearclip(&mut self, v: f32) {
         self.nearclip = v.clamp(*NEARCLIP_RANGE.start(), *NEARCLIP_RANGE.end());
     }
 }
 
 impl Default for ViewDistance {
-    /// `$WOW_FARCLIP` (yd, clamped to [`FARCLIP_RANGE`]) overrides the 350 default. The options row is
-    /// the live lever, but a headless capture has no hands — and a horizon or fog report almost always
-    /// arrives with the director's slider somewhere other than the default (the 0684 gap was invisible
-    /// at 777 and glaring at 320), so reproducing one must not need a human. Read once at startup, like
-    /// the other capture-side knobs.
+    /// `$WOW_FARCLIP` (yd, clamped to [`FARCLIP_RANGE`]) overrides the 350 default, read once at
+    /// startup, so a headless capture can reproduce a player's view distance.
     fn default() -> Self {
         let farclip = std::env::var("WOW_FARCLIP")
             .ok()
@@ -438,24 +269,11 @@ impl Default for ViewDistance {
     }
 }
 
-/// Is a world bounding sphere inside the far-clip wall — i.e. does the detailed world still draw it?
-///
-/// **The one spelling of "is it nearer than `farclip`", shared by every CPU-side consumer.** The test is
-/// planar depth along the camera-forward axis (`(center − eye)·fwd`) of the sphere's NEAREST point, which
-/// is deliberately the *same coordinate* the per-pixel wall uses in the shaders (`terrain.wgsl` /
-/// `wow_model.wgsl` / `wow_effect.wgsl` all discard on eye-Z past `fog_params.w`). Agreeing on the
-/// coordinate is what makes an object straddling the boundary **dissolve** through it instead of popping
-/// when its origin crosses.
-///
-/// Radial distance would be the obvious alternative and it is wrong: it disagrees with the wall off-axis,
-/// so a wide object at the edge of the frame pops while its pixels were still being drawn.
-///
-/// ## Why this is not the camera's far plane
-/// The world camera's projection far is ~3000 yd — far *beyond* `farclip` on purpose, so the coarse WDL
-/// horizon can draw behind the wall. So the frustum's own far plane is **not** the reference's far plane,
-/// and a `Frustum::intersects_sphere(.., intersect_far = true)` is not a substitute for this test. In the
-/// reference there is one projection far plane at `farclip` and it bounds the detailed world; here that
-/// bound is this function plus the shaders' per-pixel discard, and nothing else.
+/// Whether a world bounding sphere is inside the far-clip wall, the one CPU-side test of it: planar
+/// depth along camera-forward to the sphere's nearest point, the coordinate the shaders' per-pixel
+/// wall discards on (eye-Z past `fog_params.w`), so a straddling object dissolves instead of
+/// popping. The frustum's far plane is [`CAM_FAR`], so it is no substitute: this test and the
+/// shaders' discard are the whole `farclip` bound.
 pub fn within_farclip(
     farclip: f32,
     cam_pos: Vec3,
@@ -466,27 +284,13 @@ pub fn within_farclip(
     (center - cam_pos).dot(cam_fwd) - radius <= farclip
 }
 
-/// Marks **the world camera** — the one flying the scene. Every "where is the viewer" consumer
-/// (terrain streaming, PVS, sun follow, sound listener, picking, the capture pin, …) filters on this,
-/// NOT on `Camera3d`: since the portrait booths (the portrait booths) there are multiple `Camera3d`s,
-/// and a bare `With<WorldCamera>` query silently reads (or writes!) an off-screen booth camera — exactly
-/// how the capture pin once yanked the booths to the scenario eye and blanked every portrait.
+/// Marks the world camera, the one the scene renders through. Viewer consumers filter on this, not
+/// on `Camera3d`: the portrait booths add off-screen `Camera3d`s.
 #[derive(Component)]
 pub struct WorldCamera;
 
-/// The `$WOW_MSAA` startup knob → a sample count, shared by both world-camera spawners
-/// (`benilla_world::worldview` and the app's `player::setup`) so the two can never disagree.
-///
-/// **8x is refused rather than passed through.** wgpu validates the sample count against the HDR
-/// target's format, and the WebGPU spec guarantees only `[1, 4]` for `Rgba16Float` (this Mac's
-/// adapter reports `[1, 2, 4]`). `WOW_MSAA=8` therefore panicked the render thread inside
-/// `prepare_view_targets` on frame one — an A/B leg that asked for it died with a wgpu validation
-/// error instead of returning an answer, which is how it was found. There is no adapter handle at
-/// camera-spawn time to query, so the honest move is to fall back to 4x and say so loudly: a
-/// usable knob and a legible failure beat a hard crash.
-///
-/// A STARTUP knob, not a live toggle: switching MSAA at runtime leaves the post-process passes
-/// (glow/egui) MSAA-mismatched and freezes the view, so A/B by restarting.
+/// The `$WOW_MSAA` knob as a Bevy `Msaa` level, 4x when unset. `8` falls back to 4x:
+/// `Rgba16Float` is only guaranteed `[1, 4]` samples, and there is no adapter to ask here.
 pub fn msaa_from_env() -> bevy::render::view::Msaa {
     use bevy::render::view::Msaa;
     match std::env::var("WOW_MSAA").ok().as_deref() {
@@ -503,42 +307,22 @@ pub fn msaa_from_env() -> bevy::render::view::Msaa {
     }
 }
 
-/// The **registered default** of the `nearclip` CVar — `"0.1"`, the default string at `0x84fb48`
-/// passed by `CVar::Register 0x63db90` at `0x68867a` (name `0x84ffb0` `"nearclip"`, help
-/// `"Near clip plane distance"`, callback `0x688d90`, record `[0xc7f348]`; wow-re
-/// `re/cvar/cvar-register-sites.tsv` row 187). 1804's law, so this is a `Same` row, not a choice.
-///
-/// The live value is [`ViewDistance::nearclip`]; this is only where it starts and what the
-/// off-world spawners ([`crate::worldview`], the depth probe) use when there is no CVar table.
-///
-/// **Why the number matters even though it is a tenth of a yard.** It was `1.0` from 0062 to 0905
-/// "for depth precision" — a rationale that predates knowing the pipeline: the projection is
-/// `perspective_infinite_reverse_rh` on a float depth buffer (the app's `capture::depth_probe`
-/// tests draw with the real one — it lives a crate up, so this is deliberately not a doc link),
-/// where `depth = near/z` makes relative precision — and our
-/// ULP-relative bias ladder ([`crate::sky_order`]) — independent of the near value. The small near
-/// is what keeps the whole waterline-crossing band (the corner-min submersion probe,
-/// `liquid::detect_submersion`) inches tall instead of a yard. It is also the distance the
-/// self-avatar fade completes over ([`crate::model_fade::self_model_fade_alpha`] takes it as
-/// `nearclip`), so the model finishes fading exactly as the near plane would begin to slice it —
-/// the coupling the reference has for free, both being `[cam+0x38]`.
+/// The `nearclip` CVar's registered default, 0.1 (the string at `0x84fb48`, registered at
+/// `0x68867a`, record `[0xc7f348]`); the camera ctor's 1/9 (`0x50a6c0`) is overwritten from the
+/// record in the first frame, before it renders. The small near keeps the waterline-crossing band
+/// inches tall (`liquid::detect_submersion`), and the self-avatar fade completes over it
+/// ([`crate::model_fade::self_model_fade_alpha`]), as in the reference, where both are
+/// `[cam+0x38]`.
 pub const NEARCLIP_DEFAULT: f32 = 0.1;
 
-/// **The reference's `0x511bc0`** — re-stamp the world camera's near plane from the live `nearclip`
-/// every frame, so a `SetCVar`/`/console nearclip` write reaches this frame's picture the way it
-/// does there (2163). The far plane is deliberately NOT stamped here: ours is [`CAM_FAR`], the
-/// horizon plane, and `farclip` is the wall — 0684's split, which the reference does not have.
-///
-/// Cheap enough to run unconditionally (one resource read, one component write on one entity), and
-/// unconditional is also what the reference does — it re-stamps on every frame, changed or not.
+/// The reference's `0x511bc0` near stamp: the live `nearclip` onto the world camera's projection
+/// every frame. The far plane is not stamped: ours is [`CAM_FAR`].
 pub fn stamp_near_clip(
     view: Res<ViewDistance>,
     mut cam: Query<&mut Projection, With<WorldCamera>>,
 ) {
     for mut proj in &mut cam {
-        // Read through `as_ref` first: taking `&mut` on a Bevy component marks it changed whether
-        // or not the write differs, and a projection that reports "changed" every frame is a lie
-        // every downstream `Changed<Projection>` has to pay for.
+        // `&mut` marks the component changed even when the value is equal, so compare first.
         let Projection::Perspective(current) = proj.as_ref() else {
             continue;
         };
@@ -550,39 +334,22 @@ pub fn stamp_near_clip(
         }
     }
 }
-/// The camera's vertical field of view (radians) — one constant shared by the projection
-/// (the camera spawn) and every consumer that needs the near rectangle's true shape. 45°, the value the
-/// projection has always used (Bevy's `PerspectiveProjection` default, ≈ the reference's 44.1° —
-/// [`crate::sun`]'s projection note); naming it here just stops the consumers drifting apart.
+/// The vertical field of view in radians, shared by the projection and every consumer of the near
+/// rectangle: 45°, Bevy's `PerspectiveProjection` default; the reference's follows the aspect,
+/// 44.1° at 16:9.
 pub const CAM_FOVY: f32 = std::f32::consts::FRAC_PI_4;
 
-/// **The world camera's world pose, made current before anything in `Update` reads it** — the
-/// set every `Update`-stage viewer authority must order after.
-///
-/// Bevy propagates `GlobalTransform` in `PostUpdate`. For the whole of `Update`, therefore, a
-/// camera's `GlobalTransform` is the pose it had **last** frame, while its `Transform` — written
-/// by the controller in [`crate::schedule::WorldStage::Input`] — is this frame's. Walking, the two
-/// differ by centimetres and nothing shows. On the frame a teleport snaps they differ by the whole
-/// jump, and an authority that decides *what may draw* off the stale one gates a frame drawn from
-/// the new pose with a verdict about the old place (decision 1503).
+/// The world camera's pose made current within `Update`, for every viewer authority there: Bevy
+/// propagates `GlobalTransform` in `PostUpdate`, a whole jump late after a teleport snap.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct CameraPoseSet;
 
-/// Copy the world camera's `Transform` into its `GlobalTransform` (see [`CameraPoseSet`]).
-///
-/// **Root cameras only.** The world camera is spawned unparented (both the fallback and the real
-/// one), and for a root the propagation Bevy will run in `PostUpdate` is exactly this copy — so
-/// this makes the same value available earlier and `PostUpdate` recomputes it identically. A
-/// camera that ever acquires a parent keeps Bevy's propagated value and its old one-frame lag,
-/// which is no worse than before and never silently wrong: the pose it reports is a real pose the
-/// camera had, just not this frame's.
-///
-/// Written through `set_if_neq` so a still camera does not flag `Changed<GlobalTransform>` every
-/// frame for the consumers that key on it.
-/// The root world cameras and their two transforms — see [`publish_camera_pose`].
+/// The root world cameras' two transforms: [`publish_camera_pose`] copies `Transform` into
+/// `GlobalTransform` early ([`CameraPoseSet`]), `set_if_neq` so a still camera stays unchanged.
 type RootCameraPose<'w, 's> =
     Query<'w, 's, (&'static Transform, &'static mut GlobalTransform), RootCamera>;
-/// A world camera Bevy will propagate as a root (no parent to inherit from).
+/// A world camera with no parent, for which Bevy's `PostUpdate` propagation is exactly that copy;
+/// a parented camera keeps Bevy's value and its one-frame lag.
 type RootCamera = (With<WorldCamera>, Without<ChildOf>);
 
 pub(crate) fn publish_camera_pose(mut cam: RootCameraPose) {
@@ -591,7 +358,7 @@ pub(crate) fn publish_camera_pose(mut cam: RootCameraPose) {
     }
 }
 
-/// The view lane's plugin — today, [`publish_camera_pose`] and its ordering contract.
+/// The view lane's plugin: [`stamp_near_clip`] and [`publish_camera_pose`].
 pub(crate) struct ViewPlugin;
 
 impl Plugin for ViewPlugin {
@@ -601,23 +368,15 @@ impl Plugin for ViewPlugin {
 }
 
 pub(crate) fn plugin(app: &mut App) {
-    // The reference's per-frame clip stamp (2163). In `Update` and not `PostUpdate` so a
-    // `SetCVar("nearclip", …)` drained this frame reaches this frame's projection, which is the
-    // ordering `0x511bc0` has for free by running inside the world-frame driver.
-    //
-    // The resource is init'd HERE and not only in `world_plugins`: a system's own plugin owes it
-    // its parameters, and a harness that adds this plugin for the pose set (`view::tests`) got a
-    // "Resource does not exist" panic instead. `init_resource` is idempotent, so the app's own
-    // registration still wins wherever it already ran.
+    // In `Update`, so this frame's `nearclip` write reaches this frame's projection, as `0x511bc0`
+    // runs inside the world-frame driver; initialized here too for a harness with only this plugin.
     app.init_resource::<ViewDistance>()
         .add_systems(Update, stamp_near_clip);
     app.add_systems(
         Update,
         publish_camera_pose
             .in_set(CameraPoseSet)
-            // After the controller that writes the camera's `Transform`
-            // ([`crate::schedule::WorldStage::Input`]) — the point of the whole system is to
-            // publish the pose the controller just chose, not the one before it.
+            // After the controller writes this frame's `Transform`.
             .after(crate::schedule::WorldStage::Input),
     );
 }
@@ -627,8 +386,7 @@ mod tests {
     use super::*;
     use bevy::ecs::system::RunSystemOnce;
 
-    /// **`0x511bc0`'s near stamp** — the live `nearclip` reaches the projection, and a projection
-    /// already holding it is not marked changed for the privilege (2163).
+    /// `0x511bc0`'s near stamp reaches the projection, and an unchanged one stays unmarked.
     #[test]
     fn the_near_plane_follows_the_cvar_and_settles() {
         let mut app = App::new();
@@ -643,7 +401,7 @@ mod tests {
                 }),
             ))
             .id();
-        // A player (or an addon's `ConsoleExec("nearClip 0.3")`) moves the knob.
+        // A `nearclip 0.3` write, from a player or an addon's `ConsoleExec`.
         app.insert_resource(ViewDistance {
             farclip: 350.0,
             nearclip: 0.3,
@@ -655,9 +413,7 @@ mod tests {
         };
         assert_eq!(near(&app), 0.3, "the stamp is the reference's, every frame");
 
-        // ...and the SECOND frame, with nothing moved, must not report the projection changed:
-        // `&mut` on a Bevy component marks it whether or not the write differs. (Verified by
-        // mutation: dropping the `as_ref` guard in `stamp_near_clip` fails exactly this line.)
+        // A second frame with nothing moved must not mark the projection changed.
         let tick = app.world().read_change_tick();
         app.update();
         assert_eq!(near(&app), 0.3);
@@ -673,10 +429,7 @@ mod tests {
         );
     }
 
-    /// The contract of [`CameraPoseSet`]: a system ordered after it, in the same `Update`, reads
-    /// the pose the controller wrote **this** frame — not the one Bevy will propagate at the end
-    /// of it. Written as the frame it fixes: move the camera the way a teleport snap does, and
-    /// assert the downstream authority sees the destination.
+    /// [`CameraPoseSet`]'s contract: a reader ordered after it sees this frame's teleport snap.
     #[test]
     fn a_reader_after_the_pose_set_sees_this_frames_camera() {
         #[derive(Resource, Default)]
@@ -716,8 +469,7 @@ mod tests {
         );
     }
 
-    /// A **parented** camera is left to Bevy's propagation: a plain copy of a child's local
-    /// `Transform` would be a wrong pose, which is worse than a frame-old right one.
+    /// A parented camera is left to Bevy: a child's local `Transform` is not a world pose.
     #[test]
     fn a_parented_camera_is_left_alone() {
         let mut app = App::new();
@@ -755,14 +507,12 @@ mod tests {
         assert!(at(700.0, 0.0));
         assert!(at(777.0, 0.0)); // exactly at the wall still draws (the shader discards past it)
         assert!(!at(778.0, 0.0));
-        // A big object straddling the wall stays in: its near side is still inside, and the
-        // per-pixel wall dissolves the far half. This is the no-pop property.
+        // A big object straddling the wall stays in; the per-pixel wall dissolves its far half.
         assert!(at(800.0, 30.0));
         assert!(!at(900.0, 30.0));
     }
 
-    /// Off-axis is where radial distance and the shader's eye-Z part company — the wall is a PLANE,
-    /// so a point 700 yd forward and 700 yd sideways (radially ~990) is still inside it.
+    /// A point 700 yd forward and 700 yd aside (radially ~990) is inside the planar wall.
     #[test]
     fn the_wall_is_a_plane_not_a_sphere() {
         let eye = Vec3::ZERO;
@@ -775,8 +525,7 @@ mod tests {
         );
     }
 
-    /// Behind the camera is trivially inside the wall (negative depth); the lateral frustum planes,
-    /// not this test, are what reject it. Pinned so nobody "fixes" this into an abs().
+    /// Behind the camera is inside the wall; the frustum's side planes reject it, never an `abs()`.
     #[test]
     fn behind_the_camera_is_not_this_tests_job() {
         let eye = Vec3::ZERO;
@@ -795,25 +544,20 @@ mod msaa_tests {
     use super::*;
     use bevy::render::view::Msaa;
 
-    /// The env-less default is **off**, and off is spelled 1 (the reference's scale), not 0.
-    /// Welded to the `gxMultisample` registration in `benilla-app`'s `cvars.rs` by its own test.
+    /// The default is off, spelled 1 on the reference's scale.
     #[test]
     fn the_default_is_the_references_one_sample_which_means_none() {
-        // Not `MsaaSetting::default()` — a test run under `$WOW_MSAA` would read the env and this
-        // is a claim about the literal.
+        // The literal, not `MsaaSetting::default()`, which reads `$WOW_MSAA`.
         let literal = MsaaSetting { samples: 1 };
         assert_eq!(literal.level(), Msaa::Off);
         assert_eq!(*MSAA_RANGE.start(), 1);
         assert_eq!(*MSAA_RANGE.end(), 16);
     }
 
-    /// A request lands on the largest level wgpu can express at or below it — the direction the
-    /// reference's own device-init retry loop steps (`0x63b380`, `-= 2` floored at 1). Never up:
-    /// asking for 3 must not silently buy 4 samples' worth of bandwidth.
+    /// A request steps down to the nearest offered count, as in the reference (`0x63b380`).
     #[test]
     fn an_unsupported_count_steps_down_to_the_nearest_the_device_offers() {
-        // The live hazard: a player types 8 on a device that stops at 4x. Stepping down is the
-        // reference's own retry direction (`0x63b380`), so this is faithful, not just safe.
+        // A player types 8 on a device that stops at 4x.
         let upto4 = [1, 2, 4];
         assert_eq!(clamp_to_supported(8, &upto4), 4);
         assert_eq!(clamp_to_supported(16, &upto4), 4);
@@ -828,29 +572,20 @@ mod msaa_tests {
         for n in all {
             assert_eq!(clamp_to_supported(n, &all), n, "{n}x should pass through");
         }
-        // Between two offered levels it still rounds DOWN — the direction is the whole point.
+        // Between two offered levels it rounds down.
         assert_eq!(clamp_to_supported(6, &all), 4);
         assert_eq!(clamp_to_supported(15, &all), 8);
     }
 
     #[test]
     fn a_device_that_offers_nothing_still_boots_at_one_sample() {
-        // `supported_sample_counts` returning empty means some format refused even 1x, which should
-        // be impossible — but the floor is 1 (no multisampling) rather than 0 or a panic, because a
-        // client that will not start is strictly worse than one that starts unaliased.
+        // An empty list means some format refused even 1x; the floor is still 1, not a panic.
         assert_eq!(clamp_to_supported(8, &[]), 1);
         assert_eq!(clamp_to_supported(1, &[]), 1);
         assert_eq!(MsaaSetting { samples: 1 }.level(), Msaa::Off);
     }
 
-    /// [`MsaaFormats::clamp`] — the one expression of "the device has the final say" (1643),
-    /// and both of its halves matter.
-    ///
-    /// A device list steps a request DOWN to something the GPU will actually take, which is what
-    /// stops a saved `gxMultisample` from reaching the camera as a wgpu validation error. An
-    /// EMPTY list is no opinion rather than a refusal: headless, and before the adapter exists,
-    /// there is no device to be wrong about — clamping to 1 there would turn every device-less
-    /// run into a silent "multisampling off", including the one this crate's own tests run in.
+    /// [`MsaaFormats::clamp`]: a device list steps a request down, an empty list passes it through.
     #[test]
     fn the_device_list_steps_down_and_an_empty_one_has_no_opinion() {
         let apple = MsaaFormats {
@@ -878,10 +613,9 @@ mod msaa_tests {
         assert_eq!(level(4), Msaa::Sample4);
         assert_eq!(level(7), Msaa::Sample4);
         assert_eq!(level(8), Msaa::Sample8);
-        // The reference clamps at 16; anything that reaches here is already in range, and the top
-        // of that range is still only eight samples of real hardware.
+        // The reference's top, 16, maps to wgpu's top level, 8.
         assert_eq!(level(16), Msaa::Sample8);
-        // 0 cannot arrive through the clamp, but the mapping must not panic if it ever does.
+        // 0 cannot pass the clamp, but must not panic.
         assert_eq!(level(0), Msaa::Off);
     }
 }
diff --git a/crates/benilla-world/src/vis_chain.rs b/crates/benilla-world/src/vis_chain.rs
index 7f58a243..f4b5b0cc 100644
--- a/crates/benilla-world/src/vis_chain.rs
+++ b/crates/benilla-world/src/vis_chain.rs
@@ -1,37 +1,20 @@
-//! The visibility-chain-only idiom: entities that carry hide-propagation but never render.
+//! Visibility-chain-only nodes: entities that carry hide-propagation to renderable descendants
+//! but never render (rig anchors, joints, anim-host, tile and net-object roots, attachment
+//! wrappers). Bevy sweeps every `ViewVisibility` row twice a frame and once more per active
+//! camera, renderable or not (bevy_camera 0.18.1, `visibility/mod.rs`), and `Visibility` requires
+//! the component, so [`VisChainOnly::vis_chain_only`] removes it after spawn and keeps
+//! `Visibility` and `InheritedVisibility`.
 //!
-//! Bevy's visibility pipeline sweeps **every `ViewVisibility` row** three times a frame —
-//! `reset_view_visibility` and `mark_newly_hidden_entities_invisible` once each, and
-//! `check_visibility` once **per active camera** (its query takes `VisibilityClass` as an
-//! `Option`, so carrying no renderable class does not exempt a row — verified in
-//! bevy_camera 0.18.1, `visibility/mod.rs`). A second camera (the portrait booth) re-bills
-//! the whole population.
-//!
-//! Most of our world entities that carry `Visibility` never render anything themselves: rig
-//! anchors, joint entities, anim-host roots, tile roots, net-object roots, attachment
-//! wrappers. They hold `Visibility` for one reason only — hide-propagation to renderable
-//! *descendants* (a hidden unit must hide its weapon), and that chain runs entirely on
-//! `Visibility` + `InheritedVisibility`. Their `ViewVisibility` row is pure sweep tax: at the
-//! Goldshire pin it was ~6.7k of the 25.2k-row population (decision 1441).
-//!
-//! `Visibility` `#[require]`s `ViewVisibility`, so the component can't be left out at spawn —
-//! it has to be removed right after. [`VisChainOnly::vis_chain_only`] is that removal, named:
-//! chain a call onto the spawn of any never-rendering node. The inheritance chain stays whole
-//! (B0004 validates `InheritedVisibility`, which stays), every `Mut`-write flip of
-//! `Visibility` keeps working, and the row leaves all three sweeps.
-//!
-//! One trap this idiom creates: a later `.insert(Visibility::…)` on the same entity re-adds
-//! `ViewVisibility` through the require machinery. Flip visibility on chain nodes through a
-//! `Mut<Visibility>` write (as every cull authority already does), or re-strip after the
-//! insert (see `transport.rs`, the one insert-based flip).
+//! Trap: a later `.insert(Visibility::…)` re-adds `ViewVisibility`; flip a chain node through a
+//! `Mut<Visibility>` write, or strip it again after the insert (as `transport.rs` does).
 
 use bevy::camera::visibility::ViewVisibility;
 use bevy::ecs::system::EntityCommands;
 
-/// Chain onto the spawn of a never-rendering hierarchy node — see the module doc.
+/// Chain onto the spawn of a never-rendering hierarchy node.
 pub trait VisChainOnly {
-    /// Keep `Visibility` + `InheritedVisibility` (the hide-propagation chain), remove
-    /// `ViewVisibility` (the per-camera sweep row).
+    /// Keep `Visibility` and `InheritedVisibility`, the hide-propagation chain; remove
+    /// `ViewVisibility`, the per-camera sweep row.
     fn vis_chain_only(&mut self) -> &mut Self;
 }
 
@@ -47,7 +30,6 @@ mod tests {
     use bevy::camera::visibility::{InheritedVisibility, Visibility};
     use bevy::prelude::*;
 
-    /// The contract: a chain-only node keeps the inheritance pair and sheds the sweep row.
     #[test]
     fn a_chain_only_node_keeps_inheritance_and_leaves_the_sweep() {
         let mut world = World::new();
diff --git a/crates/benilla-world/src/water_fx/mod.rs b/crates/benilla-world/src/water_fx/mod.rs
index 6923865e..4748dabb 100644
--- a/crates/benilla-world/src/water_fx/mod.rs
+++ b/crates/benilla-world/src/water_fx/mod.rs
@@ -1,61 +1,18 @@
-//! Water foam — the client's **`CWater0Ripple`** wade wake / standing ring / step-in splash,
-//! rebuilt as the reference's actual **record model** (decision 0264; supersedes the ribbon of 0240
-//! and the stamps of 0234).
+//! Water foam: the reference's `CWater0Ripple` wade wake, standing ring and step-in splash, as its
+//! pool records. A record holds a feet-anchored centre on the liquid surface, a heading, a start
+//! size, a growth rate, a lifetime and a peak alpha.
 //!
-//! Ground truth, twice over: the byte-exact RE (wow-5875-re `system/terrain/scratch/`
-//! `water-ripple-decal.md` + the `waterdecal-*.c` decomps, §5-verified) **and** two live GL traces
-//! of the reference reconstructed frame-by-frame (Northshire wade 2026-07-08 + standing-ring
-//! capture 2026-07-10; per-record texgen fits residual ≈ 0). The verified model:
+//! A record's geometry is built once, at emission, from the wet liquid cells under its final box,
+//! which clips foam at banks. Growth is texgen only: each frame the stencil maps `centre ± size(t)`
+//! to UV [0, 1] at the heading, clamped to its transparent border.
 //!
-//! - **A decal is a pool record, not a mesh idiom.** Per wading unit the client emits records into
-//!   a 128-slot pool (32 reserved for the active mover, 96 for everyone else — eviction only).
-//!   Each record: feet-anchored center (Z = the **liquid surface** height), heading, `size0`,
-//!   growth rate, lifetime, peak alpha, birth time.
-//! - **Geometry is built ONCE, at emission**, from the wet liquid-lattice cells overlapping the
-//!   record's *final* box (`size0 + growth·lifetime`) — which clips foam at banks. **Growth is
-//!   pure texgen**: each frame the texture maps the box `[center ± size(t)]` to UV `[0,1]`,
-//!   rotated to the heading; outside the box the stencil clamps to its transparent border (both
-//!   foam textures have alpha-0 edges; sampler CLAMP — measured; the 0240 "GL_REPEAT tiling" was
-//!   a misread). The shape *stretches* over a static patch as `size(t)` grows.
-//! - **Alpha** rises to the peak over `0.4·L`, decays to 0 over `0.6·L`; the record dies at `L`.
-//!   Vertex colour is flat white × that alpha; the **stencil's own near-black RGB is the
-//!   intensity** (the reference fragment is a full MODULATE — measured in its FFP GLSL:
-//!   `tex × diffuse` on RGB *and* A). Recolouring the stencil to white — 0234/0240's move — made
-//!   the foam ~20× too bright; that was the blown-out white wedge.
-//! - **Selection** (driver `0x5fa760`): translating (`MOVEMENTFLAGS & 0xf` — the avatar's real
-//!   flags; a velocity proxy for streamed units) → WAKE, V-apex **along** the movement vector;
-//!   turning in place (`& 0x30`) → full-size RING; standing → reduced RING (size ×0.6, growth
-//!   ×0.25, alpha ×0.8); plus a one-shot full RING on the wade-depth crossing (`0x6030c0`).
-//!   Emission gates on `depth < max(2·collisionHeight, 1.0)` — ≈4.06 yd for a human (decision
-//!   0489: surface SWIMMING sits well inside the gate at its ~1.52-yd rest depth, so a floating
-//!   or stroking swimmer keeps its ring/wake, matching the reference; only a real dive past
-//!   ~2 body heights silences it) — with a linear attenuation past half. One shared per-unit
-//!   cooldown cell paces both
-//!   kinds: rings every 400–450 ms, wakes one per ~0.625 yd of travel (the byte cadence laws —
-//!   the 0264 INTERIM constants are resolved, decision 0265).
+//! The driver (`0x5fa760`) emits a wake when translating, a ring when turning or standing, and a
+//! full ring on crossing the wade depth (`0x6030c0`).
 //!
-//! - **The patch sits ON the plane; its coplanar ties are settled in DEPTH, never by a lift**
-//!   (B348, 1807/1808). A decal's verts are the plane's own, so it ties with the water surface
-//!   everywhere and with the *terrain* along the shoreline, where the two cross. Lifting the patch
-//!   in world space wins that tie and also moves the geometry — and on a beach a vertical lift is a
-//!   horizontal overshoot: a decal `l` yards up keeps painting for `l / slope` yards past the
-//!   waterline, on dry sand (0.10 yd at the 29 % Stranglethorn beach the defect was reported on,
-//!   proportionally more on every flatter shore — measured with
-//!   `benilla-formats --example water_here`). **The reference agrees**: `0x68fd0f` arms a
-//!   depth-buffer bias and the foam vertices sit at the queried MCLQ height exactly, so there is no
-//!   geometric lift in the binary to be faithful to (the "−2048 GL units" this file cited for a
-//!   year is refuted; the real term is `footstepBias(0.125) × [0x810390]` = D3D `DEPTHBIAS −1/8192`).
-//!   Ours needs no settle at all, and that is worth stating rather than assuming (1811): the patch
-//!   is not a decal *over* the surface, it **is** the liquid mesh's own triangles — the same wet
-//!   cells, the same winding, through the same `clip_from_world` (`DECAL_WORLD_CLIP`, 0781) as a
-//!   mesh whose `Transform` is `IDENTITY` — so the depths agree exactly and `GreaterEqual` passes
-//!   the tie unaided. [`Rung::FOAM_RASTER`] stays as a few ULPs of insurance against a driver
-//!   rounding two pipelines differently; the **slope half is disarmed**, because its pull grows as
-//!   z² and the only thing it can reach is the skirt of wet-cell geometry lying over dry sand.
-//!
-//! The formulas + lifecycle math live in [`params`]; this half is the ECS: the emitter over the
-//! avatar + streamed units, the record pool, and one additive effect-stream draw per
-//! (chunk, category) with live records (fog OFF — the reference's verified foam render state).
+//! The patch is the liquid mesh's own triangles through the same `clip_from_world`, so the depth
+//! test settles its tie with the water; a lift would overshoot onto dry sand on a beach. The
+//! reference also lays foam at the MCLQ height, with only a depth bias (`0x68fd0f`):
+//! `0.125 × [0x810390]`, D3D `DEPTHBIAS` −1/8192.
 
 mod bob;
 mod params;
@@ -82,42 +39,31 @@ use params::{foam_params, foam_uv, rand01, record_alpha, record_size, WadeState}
 use params::{foam_gain, swim_ramp, tread_params, FoamLook, TREAD_INTERVAL};
 use params::{wake_cooldown, RING_INTERVAL};
 
-/// The two foam stencils (render categories: 0 = ring, 1 = wake). Loaded RAW — the alpha carries
-/// the shape, the near-black RGB carries the intensity (never recolour; see module doc).
+/// The ring and wake stencils, loaded raw: the alpha is the shape and the near-black RGB the
+/// intensity, as the reference modulates both, so foam recoloured white is about 20× too bright.
 const RING_TEXTURE: &str = "xtextures/splash/splash.blp";
 const WAKE_TEXTURE: &str = "xtextures/splash/wake.blp";
 
-/// Pool geometry (VERIFIED `0x68f8b0`/`0x68f9f0`): 128 records; the active mover allocates from
-/// `[0, 32)`, everyone else from `[32, 128)` — an anti-eviction partition, nothing more.
+/// The record pool (`0x68f8b0`, `0x68f9f0`): the active mover allocates from `[0, 32)` and
+/// everyone else from `[32, 128)`, so others never evict its records.
 const POOL_SIZE: usize = 128;
 const SELF_SLOTS: usize = 32;
 
-/// Step-in/out one-shot depth threshold, as a fraction of the unit's collision height (VERIFIED
-/// `0x6030c0`: feet-Z vs `0.4 × collision height` from CMovement+0xb4, crossing latched either
-/// direction). A human's 2.031 yd fires it ~0.81 yd deep, a gnome's 1.15 at ~0.46 — the unit's own
-/// `h` since decision 0645, where it used to be a human's for everybody.
+/// The step-in and step-out one-shot depth as a fraction of the unit's own collision height
+/// (`0x6030c0`, CMovement+0xb4), latched either way: about 0.81 yd for a human.
 const ONESHOT_DEPTH_FRAC: f32 = 0.4;
 
-/// The emission depth gate: **2 × the unit's collision height** (≈4.06 yd for a human, ≈2.3 for a
-/// gnome), floored at 1.0 like the reference's `max(…, 1.0)`. The gate field
-/// `[unit+0x297]` is the dword-indexed `+0xa5c` = CMovement+0xb4 = **collision height** —
-/// Q5(c) of wow-re `water-ripple-decal.md` cross-verifies the field identity; the note's
-/// depth-gate paragraph mislabels the same field "boundingRadius", and transcribing that label
-/// (`2 × UNIT_FIELD_BOUNDINGRADIUS` ≈ 0.78, clamped to a 1-yd gate) is what killed all foam the
-/// moment swim latched: the ~1.52-yd swim rest depth sat past the misread gate (decision 0489 —
-/// the director's ref-check shows surface swimmers foaming, which the true 4-yd gate allows).
+/// The emission depth gate, `max(2 × collision height, 1.0)`: about 4.06 yd for a human, so a
+/// surface swimmer at its 1.52-yd rest depth still foams. The field, `[unit+0x297]`, is
+/// CMovement+0xb4, the collision height, not `UNIT_FIELD_BOUNDINGRADIUS`.
 const GATE_DEPTH_FRAC: f32 = 2.0;
 
-/// Horizontal speed (yd/s) above which a streamed unit counts as translating — the velocity proxy
-/// for the reference's `MOVEMENTFLAGS & 0xf` bit-test (the avatar uses its real flags). A small
-/// guard over extrapolation jitter.
+/// Speed (yd/s) past which a streamed unit counts as translating: its `MOVEMENTFLAGS & 0xf` proxy.
 const MOVE_EPSILON: f32 = 0.5;
-/// Yaw rate (rad/s) above which a non-translating streamed unit counts as turning in place
-/// (the `& 0x30` proxy).
+/// Yaw rate (rad/s) past which a still streamed unit counts as turning: its `& 0x30` proxy.
 const TURN_EPSILON: f32 = 0.35;
 
-/// One live foam decal — a `CWater0Ripple` pool record. Geometry is static (built at emission);
-/// per-frame size/alpha are derived from `born` + the params (`params.rs`).
+/// A `CWater0Ripple` pool record: static geometry, with size and alpha derived from `born`.
 struct FoamRecord {
     /// Feet position at emission, WoW XY.
     center: [f32; 2],
@@ -126,28 +72,24 @@ struct FoamRecord {
     size0: f32,
     /// yd/s.
     growth: f32,
-    /// s; death at `born + lifetime`.
+    /// Seconds; the record dies at `born + lifetime`.
     lifetime: f32,
-    /// Peak vertex alpha.
     peak: f32,
     born: f32,
     /// Render category: ring (`splash.blp`) vs wake (`wake.blp`).
     ring: bool,
-    /// Static patch triangles (Bevy space, surface-lifted), from the wet liquid cells overlapping
-    /// the final box. Empty patches never allocate a record.
+    /// Static triangles in Bevy space, on the surface, from the wet cells under the final box.
     verts: Vec<Vec3>,
-    /// The liquid chunk that hosted the emission — foam meshes group per chunk so the transparent
-    /// pass sorts them with their water (then `depth_bias` wins the coplanar tie).
+    /// The liquid chunk that hosted the emission; records draw grouped per chunk.
     chunk: Entity,
 }
 
-/// Per-unit emitter state: the shared cooldown cell (`unit+0xc78` — ONE cell for both kinds: a
-/// ring pulse delays a following wake and vice versa, faithful), the step-in latch, and motion
-/// history for the streamed-unit velocity/yaw proxies.
+/// Per-unit emitter state: the cooldown cell both kinds share (`unit+0xc78`), so a ring delays the
+/// next wake and vice versa; the step-in latch; the motion history for the proxies.
 struct UnitFoam {
     last_pos: Option<Vec3>,
     last_yaw: Option<f32>,
-    /// Absolute time the next emission is allowed (the shared tick cooldown).
+    /// Absolute time the next emission is allowed.
     ready: f32,
     /// Step-in latch: currently deeper than the one-shot threshold.
     wading: bool,
@@ -157,7 +99,7 @@ struct UnitFoam {
     /// would start eating the wakes the same pass exists to make more visible.
     tread_ready: f32,
     rng: u32,
-    /// Fed this frame (drives retiring state for despawned units).
+    /// Fed this frame; an unfed unit's state retires.
     active: bool,
 }
 
@@ -175,8 +117,7 @@ impl UnitFoam {
     }
 }
 
-/// All foam state: the 128-slot record pool with its two allocation cursors, and the per-unit
-/// emitter states (the avatar keys [`Entity::PLACEHOLDER`] — it has no streamed entity of its own).
+/// The record pool, its cursors and the per-unit emitters; the avatar keys `Entity::PLACEHOLDER`.
 #[derive(Resource)]
 struct WaterFoam {
     pool: Vec<Option<FoamRecord>>,
@@ -196,36 +137,26 @@ impl Default for WaterFoam {
     }
 }
 
-/// Advance a partition cursor, returning the absolute pool slot to (over)write — the reference's
-/// oldest-in-partition eviction (VERIFIED: counters `0xc7f3b0` self / `0xc81d48` others).
+/// The next slot in a partition, its oldest record (counters `0xc7f3b0` self, `0xc81d48` others).
 fn alloc_slot(cursor: &mut usize, base: usize, len: usize) -> usize {
     let i = base + *cursor;
     *cursor = (*cursor + 1) % len;
     i
 }
 
-/// The two foam stencils (ring/wake), decoded raw at startup. The draws they feed carry the
-/// reference's **whole** foam render state (VERIFIED at the bytes — wow-re's §5 on `0x68fae0`,
-/// folded back as 1808): additive; **fog off** (`0x68fcd0`/`0x68fcd2`/`0x68fcd7` — *not*
-/// `0x68fcc1`, which is the blend value's `mov edx,3` and was this file's citation until then);
-/// **depth-tested `LEQUAL`, depth-write off**; and a depth-buffer bias armed at `0x68fd0f`.
-/// Sorted on [`crate::sky_order::FOAM_BIAS`], a rung over the whole water band, because
-/// `0x68fae0` is `0x6816d0`'s tail-jump on both arms of the submersion branch — one call per
-/// frame, after **all** liquid has drained, with no sort key in it anywhere.
+/// The two foam stencils. Their draws carry the reference's foam render state (`0x68fae0`):
+/// additive, fog off, depth-tested `LEQUAL` without depth write, and a depth bias (`0x68fd0f`).
 #[derive(Resource)]
 struct FoamAssets {
     ring: Handle<Image>,
     wake: Handle<Image>,
 }
 
-/// The foam draw's sort rung — [`crate::sky_order::FOAM_BIAS`], whose doc carries the arithmetic.
-/// It is a **rung above the whole water band**, not an epsilon over one surface: the reference
-/// drains every liquid queue before it draws foam, so no water surface in the frame can come after
-/// it. (It rode `WATER_BIAS + 1.0` until B348, where the water chunk one lattice nearer the eye
-/// outsorted the foam patch by ~33 and painted over it.)
+/// A rung over the whole water band, not an epsilon over one surface: the reference draws foam
+/// once per frame, after all liquid (`0x6816d0` tail-jumps to `0x68fae0` on both branches).
 use crate::sky_order::FOAM_BIAS;
 
-/// Load the stencils raw (CLAMP, no mips — the reference's measured sampler state).
+/// Loads the stencils raw, clamped and without mips, the reference's sampler state.
 fn setup_water_fx(
     mut commands: Commands,
     world_assets: Option<ResMut<WorldAssets>>,
@@ -244,8 +175,7 @@ fn setup_water_fx(
     commands.insert_resource(FoamAssets { ring, wake });
 }
 
-/// Decode a foam stencil, keeping its authored RGBA verbatim (raw gamma bytes, the house
-/// invariant — the near-black RGB is the intensity). `None` (with a warning) if missing.
+/// Decodes a foam stencil with its authored RGBA verbatim, as raw gamma bytes.
 fn foam_image(
     world_assets: &mut WorldAssets,
     path: &str,
@@ -276,10 +206,8 @@ fn foam_image(
     Some(images.add(image))
 }
 
-/// Build a record's static patch: every wet liquid cell whose XY bounds overlap the final box, cut
-/// into the same two triangles the liquid surface draws, surface-lifted, in Bevy space; plus the
-/// hosting chunk (the one containing the center). `None` when the center has no hosting water or no
-/// wet cell overlaps (off the edge).
+/// A record's static patch: every wet cell overlapping the final box, cut into the liquid surface's
+/// own two triangles in Bevy space, and the chunk that contains the centre.
 fn build_patch(
     center: [f32; 2],
     final_size: f32,
@@ -375,7 +303,7 @@ fn drive_unit(
     pos: Vec3,
     state: WadeState,
     scale: f32,
-    // The unit's collision height (yd) — both depth lines below are fractions of it (0645).
+    // The unit's collision height (yd), which both depth lines scale.
     h: f32,
     water: &Query<(Entity, &WaterChunkInfo, &FoamPatch)>,
     index: &WaterIndex,
@@ -387,13 +315,9 @@ fn drive_unit(
     let gate = (GATE_DEPTH_FRAC * h).max(1.0);
     foam_state.active = true;
     let wow = bevy_to_wow(pos);
-    // The surface height under the unit, from the wet cell it stands on — not the chunk's box and
-    // not the chunk's highest vertex, which on a sloped river put the wade depth ~2 yd out
-    // (decision 0642). Through [`WaterIndex`], not the full chunk walk: this line used to be a
-    // linear scan of every loaded surface (~2.2k at a city pin) PER UNIT PER FRAME — exactly the
-    // per-consumer shape `liquid/spatial.rs`'s module doc warns detonates; a dry-land unit now
-    // costs one hash miss. A dead index entry self-filters at `water.get` (the index contract),
-    // and overlapping surfaces were already first-match-in-arbitrary-order before this.
+    // The surface height from the wet cell underfoot: a chunk's box or top vertex puts a sloped
+    // river's wade depth 2 yd out. Through the index, so a dry unit costs one hash miss; a dead
+    // entry fails `water.get`, and overlapping surfaces take the first match.
     let Some(surface) = index.over(wow[0], wow[1]).iter().find_map(|&e| {
         let (_, info, _) = water.get(e).ok()?;
         info.surface_z_at(wow[0], wow[1])
@@ -403,9 +327,8 @@ fn drive_unit(
     };
     let depth = surface - wow[2];
 
-    // Step-in/out one-shot: fires once on crossing the wade depth in EITHER direction
-    // (`0x6030c0`, latched at `[+0x269]` — VERIFIED; the driver's mode-0xC9 call also clears the
-    // shared cooldown).
+    // The one-shot fires on crossing the wade depth either way (`0x6030c0`, latch `[+0x269]`);
+    // the driver's mode-0xC9 call also clears the cooldown.
     let wading_now = depth > ONESHOT_DEPTH_FRAC * h;
     let oneshot = wading_now != foam_state.wading;
     foam_state.wading = wading_now;
@@ -467,8 +390,7 @@ fn drive_unit(
     };
 }
 
-/// Per frame: run the driver for the avatar (its real movement flags — the reference's own
-/// selection bits) and for every streamed unit (the velocity/yaw proxy), emitting pool records.
+/// Runs the driver for the avatar on its movement flags, and for streamed units on the proxies.
 fn emit_water_foam(
     time: Res<Time>,
     quality: Res<benilla_assets::WaterQuality>,
@@ -493,7 +415,6 @@ fn emit_water_foam(
     }
 
     if !water.is_empty() {
-        // The avatar: byte-faithful selection off our own streamed movement flags.
         if let Some(body) = viewer.at {
             let uf = foam
                 .units
@@ -503,8 +424,7 @@ fn emit_water_foam(
             let vel = prev.map_or(Vec3::ZERO, |p| (body - p) / dt);
             let w = bevy_to_wow(vel);
             let speed = (w[0] * w[0] + w[1] * w[1]).sqrt();
-            // Byte-faithful selection off our own streamed movement flags (wow-re CWater0Ripple
-            // driver `0x5fa760`); the masks live on `Viewer`, next to the field they read.
+            // Selection off our own movement flags, as `0x5fa760` does; the masks live on `Viewer`.
             let state = if viewer.translating() {
                 WadeState::Translating {
                     speed,
@@ -532,7 +452,7 @@ fn emit_water_foam(
             );
         }
 
-        // Streamed units (the avatar's own wire ghost is excluded via `Without<SelfPlayer>`).
+        // Streamed units; `Without<ViewerUnit>` excludes the avatar's own wire ghost.
         for (entity, transform, unit) in &units {
             if !unit.wades {
                 continue;
@@ -590,11 +510,8 @@ fn emit_water_foam(
     foam.units.retain(|_, uf| uf.active);
 }
 
-/// Per frame (PostUpdate, after the stream clear): age the pool, drop dead records, and push
-/// one effect-stream draw per (chunk, category) with live records — positions static, UV = the
-/// texgen at `size(t)`, colour = white × the alpha ramp (the stencil's near-black RGB carries
-/// the intensity through the texture product). Sorted at the group's vert centroid + the water
-/// tie-break bias; a chunk that streamed out lets its records age out silently.
+/// Ages the pool and pushes one additive draw per (chunk, category) with live records: static
+/// positions, the texgen at `size(t)` and white times the alpha ramp.
 fn push_water_foam(
     time: Res<Time>,
     quality: Res<benilla_assets::WaterQuality>,
@@ -619,7 +536,7 @@ fn push_water_foam(
         }
     }
 
-    // Group record indices per (chunk, category) — each group is one contiguous draw.
+    // One contiguous draw per (chunk, category).
     let mut groups: HashMap<(Entity, bool), Vec<usize>> = HashMap::default();
     for (i, rec) in foam.pool.iter().enumerate() {
         let Some(rec) = rec else { continue };
@@ -660,8 +577,7 @@ fn push_water_foam(
                     assets.wake.id()
                 },
                 blend: EffectBlend::Add,
-                // The reference's foam render sets FOG off (VERIFIED `0x68fcd0`/`0x68fcd2`/
-                // `0x68fcd7`; the long-standing `0x68fcc1` citation was the blend setup — 1808).
+                // The reference's foam render sets fog off (`0x68fcd0`, `0x68fcd2`, `0x68fcd7`).
                 fog: EffectFog::Off,
                 // The reference's foam render is its own additive path (`0x68fae0`), not the
                 // M2 batch state producer — no GL_LIGHTING on it. Classic keeps that verbatim.
@@ -680,20 +596,13 @@ fn push_water_foam(
                 },
                 anchor: centroid / n as f32,
                 bias: FOAM_BIAS,
-                // A few ULPs of constant and **no slope term** (`Rung::FOAM_RASTER*`, whose docs
-                // carry the bytes and the reasoning, 1811): the patch is the liquid mesh's own
-                // triangles, so `GreaterEqual` already passes the coplanar tie and the only thing
-                // a pull toward the eye can reach is the wet-lattice skirt over dry sand. The
-                // nonzero constant also selects `DECAL_WORLD_CLIP`, so these absolute verts skip
-                // the cam-relative rebase and go through the world meshes' own matrix (0781) —
-                // which is what makes the two depths agree in the first place.
+                // A few ULPs and no slope, as the patch already ties the water. The nonzero
+                // constant selects `DECAL_WORLD_CLIP`, the world meshes' matrix, so depths agree.
                 raster_bias: crate::sky_order::Rung::FOAM_RASTER,
                 raster_slope: crate::sky_order::Rung::FOAM_RASTER_SLOPE,
                 cam_relative: false,
-                // NEVER the chunk entity: a draw's probe identity must not own a registered
-                // mesh, or bevy's sorted-phase batcher claims the item and rewrites its
-                // `batch_range` (gpu_preprocessing.rs keys purely on `item.main_entity()`) —
-                // the Goldshire-teleport crash. The chunk still keys the record grouping above.
+                // Never the chunk entity: an entity that owns a registered mesh lets bevy's
+                // sorted-phase batcher claim the item and rewrite its `batch_range`, a crash.
                 no_depth_test: false,
                 main_entity: Entity::PLACEHOLDER,
                 light: None,
@@ -703,11 +612,7 @@ fn push_water_foam(
     }
 }
 
-/// Ordering handle for the foam emitter — the `waterfx` capture fixture
-/// (`crate::capture::waterfx`) drives its synthetic wading dummy **before** this runs, so the
-/// emitter reads the motion through its normal velocity/yaw proxies on the same frame. The
-/// fixture registers itself against this set rather than being chained in here: an instrument
-/// that the engine has to name is not an instrument, it is a dependency.
+/// The foam emitter's set: the app's `waterfx` capture fixture moves its wading dummy before it.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct WaterFoamSet;
 
@@ -723,7 +628,7 @@ impl Plugin for WaterFxPlugin {
                     .in_set(WaterFoamSet)
                     .in_set(WorldStage::Present),
             )
-            // The stream push: PostUpdate after the frame's clear (emission ran in Update).
+            // The push runs after the frame's clear; emission ran in Update.
             .add_systems(PostUpdate, push_water_foam.after(begin_effect_frame));
         // MONKEY (swim waves) — the bodies' half: bobbing on the ocean's vertex swell. It shares
         // this module's water lookup shape and its depth law but nothing else (it emits no
@@ -736,10 +641,7 @@ impl Plugin for WaterFxPlugin {
 mod tests {
     use super::*;
 
-    /// The emitter reaches its water through [`WaterIndex`], end to end: a wading unit standing
-    /// in an indexed pool emits a record on its first frame (the step-in one-shot), and a unit
-    /// on dry land emits nothing. This is the regression fence for the index rewire — an empty
-    /// or stale index is a world with NO foam, which no helper-level test would catch.
+    /// An empty or stale index means no foam anywhere, which no helper-level test catches.
     #[test]
     fn the_emitter_finds_its_water_through_the_index() {
         let mut app = App::new();
@@ -783,8 +685,7 @@ mod tests {
             height: 2.0,
             bound: None,
         };
-        // Feet 1.5 yd under the surface — past the 0.4·h step-in line, so the one-shot ring
-        // fires on the first classified frame.
+        // Feet 1.5 yd under, past the 0.4·h step-in line: the one-shot fires on the first frame.
         app.world_mut().spawn((
             Transform::from_translation(wow_to_bevy([2.0, 2.0, 3.5])),
             unit(),
@@ -890,13 +791,9 @@ mod tests {
         assert_eq!(foam.other_cursor, 5);
     }
 
-    /// The patch builder: wet cells overlapping the final box make it in (surface-lifted), ones
-    /// outside stay out, and a dry position (no hosting chunk) yields no record.
     #[test]
     fn patch_clips_to_wet_cells() {
-        // A 3×3-vertex grid over `[0,10]²` — 4 cells of 5 yd. Only the near (0,0) cell is wet, so
-        // the far half of the box is dry ground the patch must not cover. The grid rides the info
-        // now (the swim query needs the same cells); `FoamPatch` is just the marker.
+        // Four 5-yd cells over `[0,10]²`; only (0,0) is wet, so the box's far half is dry ground.
         let mut positions = Vec::new();
         for j in 0..3 {
             for i in 0..3 {
@@ -915,8 +812,7 @@ mod tests {
         let (verts, _) = build_patch([2.0, 2.0], 1.5, &chunks).unwrap();
         assert_eq!(verts.len(), 6, "only the one wet cell overlaps");
         let wow = bevy_to_wow(verts[0]);
-        // ON the plane, to the bit — the coplanar tie is the rasterizer's, and a geometric lift
-        // here is a horizontal overshoot onto dry ground at every shoreline (B348).
+        // On the plane: a lift would overshoot onto dry ground at every shoreline.
         assert!(
             (wow[2] - 5.0).abs() < 1e-4,
             "the patch sits exactly on the liquid surface, unlifted"
diff --git a/crates/benilla-world/src/water_fx/params.rs b/crates/benilla-world/src/water_fx/params.rs
index c8556773..b5007dfd 100644
--- a/crates/benilla-world/src/water_fx/params.rs
+++ b/crates/benilla-world/src/water_fx/params.rs
@@ -1,24 +1,13 @@
-//! The CWater0Ripple **driver math** — pure functions (no ECS): the per-emission parameter
-//! formulas of `0x5fa760`, the record lifecycle (size growth + the 0.4/0.6 alpha ramp), and the
-//! render texgen. Every formula is byte-verified (the 0264 dispatch's §5 hand-trace closed the
-//! Ghidra-broken arg plumbing — wow-re `water-ripple-decal.md`, their `bb4793d7`) and validated
-//! against the two reference-trace reconstructions; the tests pin the envelopes.
-//!
-//! The 0264 INTERIM constants are gone (decision 0265): the wake-size factor was the reference
-//! *render* aging a record one frame before its first draw (an artifact of the capture's ~20 fps,
-//! not an emit multiplier — negligible at our frame rates), and the ring-lifetime factor was a
-//! circular fps estimate in the reconstruction (no such factor exists at the bytes). The cadences
-//! are now the byte laws: ring `400 ms + U[0,50)`, wake `~625/min(speed,20)` ms — one decal per
-//! ~0.6 yd of travel at any speed.
+//! The `CWater0Ripple` driver math as pure functions: `0x5fa760`'s per-emission parameters, the
+//! record lifecycle and the render texgen.
 
-/// Ring pulse interval (s): `400 + U[0,50)` cooldown ticks (VERIFIED `0x5fac41`–`0x5fac53` +
-/// FUN_00455c70's `(50·rng)>>32`; the tick rides the QPC-ms thunk `0x42b790`).
+/// Ring pulse interval in seconds: `400 + U[0, 50)` ms (`0x5fac41`..`0x5fac53`, the roll
+/// `(50·rng) >> 32` at `0x455c70`, millisecond ticks from `0x42b790`).
 pub(super) const RING_INTERVAL: (f32, f32) = (0.4, 0.45);
 
-/// Wake emission cooldown (s) at `speed` yd/s: `625/min(speed,20)` ms — a **distance law**, one
-/// decal per ~0.625 yd of travel (VERIFIED: the driver's `−1000.0` sign-flip makes a future
-/// deadline `now + k·625/min(speed,20)`; ≈ 89 ms at run speed). The jitter factor `k`'s spread is
-/// the one remaining INTERIM: the traces show ±~15%, the exact distribution wasn't pinned.
+/// Wake cooldown in seconds at `speed` yd/s: `k·625/min(speed, 20)` ms, one decal per 0.625 yd of
+/// travel. `k` is uniform in [0.9, 1.1); the reference's spread is about ±15%, its distribution
+/// untraced.
 pub(super) fn wake_cooldown(speed: f32, rng: &mut u32) -> f32 {
     let k = 0.9 + 0.2 * rand01(rng);
     k * 0.625 / speed.clamp(0.1, 20.0)
@@ -130,14 +119,14 @@ pub(super) enum WadeState {
     Standing,
 }
 
-/// Emission params for one record — the driver's computed values (`0x5fa760`), byte-verified.
+/// One record's emission parameters, as the driver computes them (`0x5fa760`).
 pub(super) struct FoamParams {
     pub(crate) size0: f32,
     /// yd/s.
     pub(crate) growth: f32,
     /// s.
     pub(crate) lifetime: f32,
-    /// Peak vertex alpha (`min(6 × driverAlpha, 1)` — the `0x68be62` transform, alpha-only).
+    /// Peak vertex alpha, `min(6 × driver alpha, 1)` (`0x68be62`).
     pub(crate) peak: f32,
     /// Render category: ring (`splash.blp`) vs wake (`wake.blp`).
     pub(crate) ring: bool,
@@ -178,12 +167,11 @@ pub(super) fn foam_params(
             growth *= 0.25;
             size0 *= 0.6;
         }
-        // Turning in place and the step-in one-shot take the unreduced ring params (the driver's
-        // standing-only branch skips them; `flagtable[1|3] = 0` keeps them ring-textured).
+        // Turning and the one-shot take the unreduced ring params: the driver's standing branch
+        // skips them, and `flagtable[1|3] = 0` keeps them ring-textured.
         _ => {}
     }
-    // Depth attenuation: past half the gate depth, everything ramps down linearly toward ×0.5
-    // (alpha, lifetime, size0 — never growth; VERIFIED).
+    // Past half the gate depth, alpha, lifetime and size0 (never growth) ramp down toward ×0.5.
     let half = gate * 0.5;
     if depth > half {
         let k = 0.5 + 0.5 * (gate - depth) / half;
@@ -233,8 +221,8 @@ pub(super) fn record_size(size0: f32, growth: f32, born: f32, now: f32) -> f32 {
     size0 + growth * (now - born)
 }
 
-/// A live record's alpha at `now`: the 0.4/0.6 rise/decay ramp to `peak` (rate table `0x810348 =
-/// [0.4, 0.4]`, both categories), 0 at (and past) the lifetime.
+/// A record's alpha at `now`: up to `peak` over the first 0.4 of its life and down to 0 over the
+/// rest (rate table `0x810348`, both categories).
 pub(super) fn record_alpha(peak: f32, lifetime: f32, born: f32, now: f32) -> f32 {
     let age = (now - born) / lifetime;
     if age <= 0.4 {
@@ -244,11 +232,9 @@ pub(super) fn record_alpha(peak: f32, lifetime: f32, born: f32, now: f32) -> f32
     }
 }
 
-/// The texgen (byte-verified: `uv = Rz(heading − π/2)·(v − center)/(2s) + 0.5`, world-axis
-/// aligned, geometry static, growth purely via this box; the fixed −π/2 is absorbed into our
-/// heading convention, which was fitted directly to the reference traces). `u` runs across the
-/// track, `v` runs *against* the heading — the wake chevron's apex (low `v` in `wake.blp`) lands
-/// ahead of the unit, arms trailing. Pinned by the golden test below.
+/// The texgen `uv = Rz(heading − π/2)·(p − center)/(2s) + 0.5`, with the −π/2 folded into the
+/// heading: `u` runs across the track and `v` against the heading, so the wake chevron's apex
+/// (low `v` in `wake.blp`) lands ahead of the unit.
 pub(super) fn foam_uv(center: [f32; 2], heading: f32, size: f32, p: [f32; 2]) -> [f32; 2] {
     let (dx, dy) = (p[0] - center[0], p[1] - center[1]);
     let (s, c) = heading.sin_cos();
@@ -259,8 +245,7 @@ pub(super) fn foam_uv(center: [f32; 2], heading: f32, size: f32, p: [f32; 2]) ->
     ]
 }
 
-/// xorshift32 + a 24-bit uniform — the same local-RNG idiom as `particles::rand01` (the reference
-/// rolls its own RNG per emission; we mirror the distribution, not the stream).
+/// xorshift32: the reference's RNG differs, so this matches its distribution, not its stream.
 fn next_u32(state: &mut u32) -> u32 {
     let mut x = *state;
     x ^= x << 13;
@@ -278,14 +263,12 @@ pub(super) fn rand01(state: &mut u32) -> f32 {
 mod tests {
     use super::*;
 
-    /// GOLDEN — the texgen signs against the reference trace fits (2026-07-08/10 captures): the
-    /// fitted affine `uv = A·p + t` measured `u` ACROSS the track and `v` AGAINST the heading —
-    /// the chevron apex (low `v`) lands ahead of the unit, arms trailing; the box `[c−s, c+s]`
-    /// spans one UV unit.
+    /// The signs of the affine texgen fitted to the reference's frames: `u` across the track, `v`
+    /// against the heading, and the box `[c−s, c+s]` one UV unit.
     #[test]
     fn texgen_matches_the_reference_fit() {
         let c = [-9016.0_f32, -226.0];
-        let h = 0.4637_f32; // ≈ 26.6° — the wade capture's early leg
+        let h = 0.4637_f32; // about 26.6°, a heading from the reference capture
         let s = 1.25_f32;
         let (sh, ch) = h.sin_cos();
         let uv_a = foam_uv(c, h, s, [c[0] + ch, c[1] + sh]); // 1 yd ahead
@@ -301,8 +284,6 @@ mod tests {
         assert!(edge[1].abs() < 1e-4, "box edge → v = 0: {edge:?}");
     }
 
-    /// The driver params at the byte formulas' operating points: a running wake (7 yd/s), a
-    /// standing ring, and the step-in one-shot.
     #[test]
     fn params_match_the_verified_formulas() {
         let mut rng = 1u32;
@@ -345,8 +326,6 @@ mod tests {
         }
     }
 
-    /// The cadence laws: ring 400–450 ms; wake = the ~0.625-yd distance law (~89 ms at run
-    /// speed, capped at speed 20).
     #[test]
     fn cadence_laws() {
         let mut rng = 3u32;
@@ -359,7 +338,6 @@ mod tests {
         assert!(RING_INTERVAL.0 >= 0.4 && RING_INTERVAL.1 <= 0.45);
     }
 
-    /// The depth gate and its attenuation: reject outside (0, radius2), attenuate past half.
     #[test]
     fn depth_gate_and_attenuation() {
         let mut rng = 7u32;
diff --git a/crates/benilla-world/src/wdl.rs b/crates/benilla-world/src/wdl.rs
index dec57ba8..fe7abb68 100644
--- a/crates/benilla-world/src/wdl.rs
+++ b/crates/benilla-world/src/wdl.rs
@@ -1,12 +1,7 @@
-//! Distant low-detail terrain (WDL): streams the map's coarse horizon heightmap around the view —
-//! beyond the detailed ADT ring — drawn unlit-white under a fog pair of its own that saturates it
-//! into the flat scene-fog colour (a "fog hull", decision 1521), the hills the reference shows on the
-//! horizon where ours used to fade to void. The parse + coarse mesh live in `benilla_formats::wdl`; this
-//! is just the Bevy streaming + render glue (one shared [`WdlMaterial`], one mesh per ring tile).
-//!
-//! Mechanism + RE (geometry/shading/fog/depth all VERIFIED from apitrace WoW.8 + the real `.wdl`).
-//! How it partitions against the detailed world — the reference's far-band **backdrop** law, and why a
-//! shared clip plane could not work — is `wdl.wgsl`'s header (decision 0684).
+//! Distant low-detail terrain (WDL): the map's coarse horizon heightmap streamed around the view
+//! beyond the ADT ring, drawn unlit under a fog pair of its own that saturates it to the flat
+//! scene-fog colour. The parse and mesh are `benilla_formats::wdl`; the reference's backdrop law
+//! that partitions it from the detailed world is `wdl.wgsl`'s header.
 
 use std::collections::HashMap;
 
@@ -24,29 +19,23 @@ use benilla_assets::MapCatalogRes;
 use benilla_assets::{AssetSet, RenderConfig, WorldAssets};
 use benilla_formats::WdlFile;
 
-/// Chebyshev tile radius the WDL ring covers around the view. WDL is flat haze at every distance (its
-/// own saturated fog pair, decision 1521) — what it contributes is silhouette, and hills 2–4 tiles out
-/// still rise above the horizon as fog-coloured silhouettes, so we extend toward the reference's
-/// `horizonfarclip` (~2112 yd ≈ 4 tiles). Drawn as a full ring; the
-/// shader makes it a **backdrop** — near plane at `farclip − 33`, depth clamped behind everything the
-/// detailed world can draw (`wdl.wgsl`'s header, decision 0684) — so it fills whatever the detailed
-/// world leaves empty and can never overlap it. (The reference's own far walk is a ±3-tile window.)
+/// Chebyshev tile radius of the WDL ring. The shader keeps it a backdrop (near plane at
+/// `farclip − 33`, depth behind the detailed world), so it only fills what that leaves empty.
+/// Deviation: 5, not the reference's ±3-tile far walk, because hills out to its `horizonfarclip`
+/// (2112 yd, about 4 tiles) still rise above the horizon as silhouettes.
 const WDL_RADIUS: u32 = 5;
 
-/// New WDL tiles built per frame — coarse meshes are cheap (545 verts), but a whole ring at once
-/// would hitch on zone load, so spread it.
+/// New WDL tiles built per frame (545 vertices each), so a whole ring does not hitch a zone load.
 const WDL_LOADS_PER_FRAME: usize = 8;
 
-/// The WDL subsystem: load the map's `.wdl` + a shared fog material at startup, then stream the
-/// coarse horizon ring in/out around the view each frame.
+/// Loads the map's `.wdl` and a shared material at startup, then streams the ring around the view.
 pub(crate) struct WdlPlugin;
 
 impl Plugin for WdlPlugin {
     fn build(&self, app: &mut App) {
         app.add_plugins(MaterialPlugin::<WdlMaterial>::default())
             .add_systems(Startup, setup_wdl.after(AssetSet::Open))
-            // The distant ring is world, and follows the world's lifecycle (decision 0777): it
-            // spawns only while a character is in one, and its meshes go when they leave.
+            // The ring follows the world's lifecycle: it spawns only while a world is live.
             .add_systems(Update, stream_wdl.run_if(crate::schedule::world_is_live))
             .add_systems(
                 Update,
@@ -58,31 +47,28 @@ impl Plugin for WdlPlugin {
     }
 }
 
-/// Streams the coarse WDL ring: the parsed file, the shared material every ring tile uses, and which
-/// ring tiles are currently spawned. (The material holds no fog of its own — it reads the shared
-/// global-light buffer, same as terrain and the models.)
+/// The parsed WDL, the shared ring material (it reads the global light buffer) and the spawned
+/// ring tiles.
 #[derive(Resource)]
 pub(crate) struct WdlStreamer {
     wdl: WdlFile,
-    /// `mapId` the loaded `wdl` is for; a cross-map teleport (≠ [`CurrentMap`]) reloads it.
+    /// The `mapId` of the loaded `wdl`; a cross-map teleport reloads it.
     map_id: u32,
     material: Handle<WdlMaterial>,
     loaded: HashMap<(u32, u32), Entity>,
 }
 
 impl WdlStreamer {
-    /// The drawn WDL surface height (raw WoW `z`) under a **Bevy-space** position — whole-map
-    /// coverage from the coarse horizon heightmap, exact to the rendered mesh
-    /// (`WdlFile::height_at`). The far leg of the lens-flare occlusion march
-    /// (`sun::follow::FlareGate`), beyond the resident detailed-terrain ring. `None` off the map
-    /// or where no WDL tile is authored (open ocean) — never an occluder there.
+    /// The drawn WDL height (raw WoW `z`) under a Bevy-space position, exact to the mesh: the far
+    /// leg of the flare occlusion march (`sun::follow::FlareGate`). `None` off the map or over
+    /// unauthored ocean.
     pub(crate) fn height_under(&self, bevy_pos: Vec3) -> Option<f32> {
         let wow = bevy_to_wow(bevy_pos);
         self.wdl.height_at(wow[0], wow[1])
     }
 }
 
-/// Marks a spawned WDL tile (so a future system could query/cull them as a group if needed).
+/// Marks a spawned WDL tile.
 #[derive(Component)]
 struct WdlTile;
 
@@ -95,7 +81,7 @@ fn setup_wdl(
     let (Some(_config), Some(world_assets)) = (config, world_assets) else {
         return; // no client data → no terrain at all, so no WDL
     };
-    // Default map = Azeroth (Eastern Kingdoms), matching world_map's DEFAULT_MAP_ID.
+    // Azeroth (Eastern Kingdoms), matching `world_map`'s `DEFAULT_MAP_ID`.
     let wdl = match WdlFile::load(&mut world_assets.chain.lock_recover(), "Azeroth") {
         Ok(w) => {
             info!(
@@ -109,9 +95,8 @@ fn setup_wdl(
             return;
         }
     };
-    // One shared material, reading the shared global light like terrain does — no seed and no
-    // per-frame push: `build_light_data` has already packed the fog by the first draw. Opaque ⇒
-    // depth-LEQUAL + depth-write, no blend (the verified WoW.8 state).
+    // Reads the shared global light, whose fog `build_light_data` packs before the first draw.
+    // Opaque: depth-LEQUAL with depth write and no blend, as the reference draws it.
     let material = materials.add(ExtendedMaterial {
         base: StandardMaterial {
             base_color: Color::WHITE,
@@ -141,18 +126,15 @@ fn stream_wdl(
     map_catalog: Option<Res<MapCatalogRes>>,
     mut meshes: ResMut<Assets<Mesh>>,
 ) {
-    // All four are absent together — there is no client data, so `setup_wdl` and `load_world_map`
-    // both bailed. `Option` rather than a hard `Res` because a missing resource is a *validation*
-    // failure, not a `None`: the system would never run, and Bevy's default handler panics the
-    // client (decision 1451). This one is gated on `world_is_live`, so it takes a world with no
-    // install to reach — which a player build in the wrong folder can still do.
+    // All four are absent without client data. `Option`, not `Res`: a missing `Res` fails
+    // validation, which panics the client, and a build run from the wrong folder gets here.
     let (Some(mut streamer), Some(assets), Some(current_map), Some(map_catalog)) =
         (streamer, assets, current_map, map_catalog)
     else {
         return;
     };
-    // The map the *focus* is on — `CurrentMap` once the snap has landed, the picked character's
-    // own map during world entry, so the ring is never built for the map we are leaving.
+    // The focus's map: the picked character's during world entry, so the ring is never built for
+    // the map being left.
     let map_id = focus.map(Some(current_map.0));
 
     // Cross-map teleport: reload the new map's `.wdl` and drop the old ring.
@@ -166,7 +148,7 @@ fn stream_wdl(
                     streamer.wdl = wdl;
                     streamer.map_id = map_id;
                 }
-                // No `.wdl` for this map (instances often lack one) → just clear the ring.
+                // No `.wdl` for this map (instances often lack one): clear the ring.
                 Err(_) => {
                     for (_, e) in streamer.loaded.drain() {
                         commands.entity(e).despawn();
@@ -177,16 +159,12 @@ fn stream_wdl(
         }
     }
 
-    // The same view focus the detailed streamer uses — literally the same resource now, rather
-    // than a copy under a comment claiming they agree (decision 0777).
+    // The detailed streamer's own view focus.
     let center = focus.resolve(camera.single().ok().map(|c| c.translation));
-    // The FULL window, the camera's own tile INCLUDED (`tiles_in_ring`'s doc is the why — at a
-    // lowered view distance the own tile *is* the near horizon, and dropping it leaves a gap the sky
-    // pours through). What bounds the band on the near side is the shader's near plane, never the
-    // streamed set, so this cannot toggle against the detailed streaming radius — a constant backdrop.
+    // The full window, the camera's own tile included (at a low view distance it is the near
+    // horizon); the shader's near plane bounds the band, never the streamed set.
     let desired = streamer.wdl.tiles_in_ring(center[0], center[1], WDL_RADIUS);
 
-    // Unload ring tiles no longer wanted.
     let stale: Vec<(u32, u32)> = streamer
         .loaded
         .keys()
@@ -199,7 +177,6 @@ fn stream_wdl(
         }
     }
 
-    // Load a few missing tiles this frame.
     let missing: Vec<(u32, u32)> = desired
         .into_iter()
         .filter(|c| !streamer.loaded.contains_key(c))
@@ -214,8 +191,8 @@ fn stream_wdl(
             .iter()
             .map(|p| wow_to_bevy(*p).to_array())
             .collect();
-        // Unlit + untextured: a constant up-normal and zero UV satisfy the StandardMaterial pipeline;
-        // the custom WDL shader reads neither (it outputs the flat fog colour).
+        // A constant normal and zero UV satisfy the `StandardMaterial` pipeline; the shader reads
+        // neither.
         let n = positions.len();
         let mut mesh = Mesh::new(
             PrimitiveTopology::TriangleList,
@@ -231,11 +208,9 @@ fn stream_wdl(
                 MeshMaterial3d(streamer.material.clone()),
                 Transform::IDENTITY,
                 WdlTile,
-                // The far band is exterior scene like the detailed tiles are: the reference's far
-                // walk `0x683040` is fed by the SAME per-window populate `0x682fa0`, so from a sealed
-                // room the horizon is not drawn either (`crate::exterior_cull`). One ring tile is one
-                // drawn object here, which is already the reference's far-tier granularity — this
-                // band never needed the chunk split the near tiles did (decision 0780).
+                // Exterior scene: the reference's far walk `0x683040` shares the per-window
+                // populate `0x682fa0`, so a sealed room hides the horizon (`crate::exterior_cull`).
+                // One ring tile is one object, the reference's far-tier granularity.
                 crate::exterior_cull::ExteriorScene,
             ))
             .id();
@@ -243,9 +218,7 @@ fn stream_wdl(
     }
 }
 
-/// Leaving the world drops the distant ring (decision 0777). The parsed `.wdl` itself stays — it is
-/// one small file, the resource `stream_wdl` needs to exist at all, and `height_under` is read by
-/// the sun's flare-occlusion march; what costs per frame is the spawned mesh set, and that goes.
+/// Leaving the world drops the ring; the parsed `.wdl` stays for `height_under`.
 fn release_wdl_ring(mut commands: Commands, streamer: Option<ResMut<WdlStreamer>>) {
     let Some(mut streamer) = streamer else { return };
     for (_, e) in streamer.loaded.drain() {
@@ -253,10 +226,8 @@ fn release_wdl_ring(mut commands: Commands, streamer: Option<ResMut<WdlStreamer>
     }
 }
 
-/// The backdrop law (`wdl.wgsl`'s header, decision 0684) is a property of the **shader**, so it is
-/// checked there — the same shape as `sky_order.rs`'s depth-law test, and for the same reason: the
-/// failure it guards is invisible except at a ridge crest on a fogged horizon, and the obvious "tidy-up"
-/// (go back to one shared clip plane, drop the frag-depth write) silently reintroduces it.
+/// The backdrop law lives in the shader, so it is checked there: a shared clip plane or a dropped
+/// frag-depth write reopens a seam visible only at a ridge crest on a fogged horizon.
 #[test]
 fn the_far_band_stays_a_depth_pushed_backdrop() {
     let src = benilla_assets::materials::WDL_WGSL;
@@ -272,12 +243,9 @@ fn the_far_band_stays_a_depth_pushed_backdrop() {
     );
 }
 
-/// The hull is a **fog hull**, not a fogged surface (decision 1521): the reference's far-band emitter
-/// submits its own fog pair — start `0`, end `1.0` (`0x6bd7ae`–`0x6bd7c8` inside `0x6bd780`) — so the
-/// hull is the flat fog colour at every distance. Reading the SCENE fog distances here is the bug this
-/// pins: the 33 yd overlap then sits inside the fog ramp, up to `33 / (end − start)` white (25% at
-/// farclip 177), a pale band above the fine terrain's fogged-out silhouette that grows as the view
-/// distance drops — and it is invisible at 777, so it can sit in the open for months.
+/// The reference's far-band emitter submits its own fog pair, start 0 and end 1.0 (`0x6bd7ae` to
+/// `0x6bd7c8` in `0x6bd780`), so the hull is the flat fog colour at every distance. Under the scene
+/// fog the 33 yd overlap shows as a pale band at low view distances.
 #[test]
 fn the_far_band_is_a_fog_hull_not_a_fogged_surface() {
     let src = benilla_assets::materials::WDL_WGSL;
diff --git a/crates/benilla-world/src/weather/mod.rs b/crates/benilla-world/src/weather/mod.rs
index ab8eed17..d2a1e144 100644
--- a/crates/benilla-world/src/weather/mod.rs
+++ b/crates/benilla-world/src/weather/mod.rs
@@ -1,28 +1,15 @@
-//! Weather — the `SMSG_WEATHER`-driven state machine and its render subsystems (decision 0310).
+//! Weather's visual state, driven by `SMSG_WEATHER`: the two channels of the reference's ramp
+//! (`0x67bc70`), each a clamped lerp over `(|Δ|·scale + 0.001)·10` seconds.
 //!
-//! The wire (`WeatherMessage`, bridged from the Net drain) carries `type/grade/sound/instant`;
-//! sound is already handled (`sound/weather.rs`). This module owns the **visual** state: the
-//! two ramped intensity channels of the real client's `weather_intensity_ramp` (`WoW.exe 0x67bc70`,
-//! byte-exact in wow-re `crates/lighting/src/weather_kernels.rs`):
+//! - Channel A, the effect intensity (scale 1), swings fully in about 10 s. The effect density is
+//!   `max((A − 0.25)·4/3, 0)`, so nothing falls below 0.25.
+//! - Channel B, the sky density (scale 4), has its endpoints clamped to [0, 0.25] by `SetWeather`
+//!   (`0x67baf0`), so it also swings in about 10 s. Lighting turns it into the storm blend
+//!   (`0x6d4500`): the overcast leads the rain up and starts clearing at once on the way down.
 //!
-//! - **channel A — effect intensity**: `t = elapsed_s / ((|to−from| + 0.001)·10)`, clamped lerp —
-//!   a full 0→1 swing takes ~10 s. The *effect density* handed to the precipitation pools is
-//!   `max((A − 0.25)·4/3, 0)`: below grade 0.25 nothing falls, 0.25..1 maps to 0..1.
-//! - **channel B — sky density**: the same law with `den = (|Δ|·4 + 0.001)·10`, but its
-//!   endpoints live in the **[0, 0.25] knee domain** — `SetWeather 0x67baf0` writes
-//!   `clamp(grade, 0, 0.25)` into them, so the ×4 cancels the quarter-span and B ALSO swings in
-//!   ~10 s (the 0310 fold misread the ×4 as "4× slower"; corrected in 0326). Published as
-//!   [`WeatherState::sky_density`] (0..0.25); lighting turns it into the **storm blend**
-//!   `bcc = min(1, B·4)` (`cloud_density_clamp 0x6d4500` — no sun term) and lerps the storm
-//!   `LightParams` record over the clear one — so the overcast/fog ramps linearly across the
-//!   whole swing: it leads the rain on the way up and clears immediately on the way down.
-//!
-//! The wire's last byte is **0 = smooth, nonzero = instant** — the net handler `0x48fa5f`
-//! INVERTS it (`test dl,dl; sete al`) before `SetWeather`, whose internal flag is 1 = smooth.
-//! vmangos always sends 0 (smooth); our `instant = u8 ≠ 0` decode is byte-correct end-to-end.
-//!
-//! The channels run on real elapsed time (the reference uses its ms tick `0x42c010`), so a
-//! transition keeps ramping through loading screens exactly like the real client.
+//! The wire's last byte is 0 for smooth, nonzero for instant: the net handler (`0x48fa5f`) inverts
+//! it for `SetWeather`, whose flag is 1 for smooth; vmangos always sends 0. The channels run on
+//! real time, like the reference's ms tick (`0x42c010`), so a ramp continues through loading.
 
 use bevy::prelude::*;
 
@@ -30,8 +17,7 @@ use crate::dev_state::DebugState;
 
 mod precip;
 
-/// Rain's forced-fog window — the effect lane's `EffectFog::Rain` params row reads the law
-/// from its owner (0733 §4).
+/// Rain's forced-fog window, read by the effect lane's `EffectFog::Rain` row.
 pub(crate) use precip::{RAIN_FOG_END, RAIN_FOG_START};
 
 /// Wire weather types (`SMSG_WEATHER` / vmangos `WeatherType`).
@@ -55,10 +41,7 @@ impl WeatherKind {
     }
 }
 
-/// One ramped intensity channel — the byte law of `weather_intensity_ramp` (`0x67bc70`):
-/// `value = clamped_lerp(from → to, elapsed / ((|to−from|·span_scale + 0.001)·10))`. Channel A
-/// uses `span_scale = 1` over the grade domain (~10 s per full swing); channel B `span_scale = 4`
-/// over the **[0, 0.25] knee domain** — also ~10 s per full swing (the ×4 cancels the quarter-span).
+/// One ramped channel of the reference's ramp (`0x67bc70`).
 #[derive(Clone, Copy, Debug)]
 struct Channel {
     from: f32,
@@ -79,18 +62,14 @@ impl Channel {
     }
 
     fn value(&self, now: f64) -> f32 {
-        // The `+0.001` sits INSIDE the abs (`0x67bc70`: `|Δ·span + 0.001|·10`) — sub-10 ms
-        // from the outside form, transcribed exactly anyway (0328 C1 nit).
+        // The `+ 0.001` sits inside the abs, as in `0x67bc70`.
         let den = ((self.to - self.from) * self.span_scale + 0.001).abs() * 10.0;
         let t = (((now - self.start) as f32) / den).clamp(0.0, 1.0);
         self.from + (self.to - self.from) * t
     }
 
-    /// Start ramping toward `target` from the **old target** — `SetWeather 0x67baf0` re-stamps
-    /// the epoch and writes `from ← old *target*` (`param_1[1] = *param_1`), NOT the current
-    /// ramped value. A mid-swing retarget therefore restarts the ramp from the previous
-    /// endpoint (a small jump the real client accepts); resuming from the current value was a
-    /// benilla-invented smoothing (corrected in 0326).
+    /// Ramps toward `target` from the old target, not the current value, as `SetWeather`
+    /// (`0x67baf0`) does: a mid-swing retarget jumps back to the previous endpoint.
     fn retarget(&mut self, target: f32, now: f64) {
         self.from = self.to;
         self.to = target;
@@ -104,45 +83,33 @@ impl Channel {
     }
 }
 
-/// The zone weather state — the client-side mirror of the reference's `CMapWeather` manager.
+/// The zone weather, the reference's `CMapWeather` manager.
 #[derive(Resource)]
 pub struct WeatherState {
     /// The latest wire type (`Fine` included).
     pub(crate) kind: WeatherKind,
-    /// The latest *non-fine* type — the effect the density applies to while a fine transition
-    /// drains the sky/particles. (The reference keeps per-type effect slots alive until their
-    /// density reaches 0; a direct type→type switch retargets the same channel, and the old
-    /// type's particles simply live out their few-second lifetimes.)
+    /// The type whose effect spawns; it follows every type change at once.
     pub effect_kind: WeatherKind,
     intensity: Channel,
     sky: Channel,
-    /// Channel A's raw value this frame (the wire grade, ramped) — published for instruments
-    /// (the `WOW_WEATHER_DUMP` pacing log). Consumers take the knee-mapped
-    /// [`WeatherState::effect_density`]: C3-VERIFIED (rf-weather-emission-timeline), the mist
-    /// rate's input is the knee density too — `2·max(intensity − 0.5, 0)·K·Q` where intensity
-    /// is `(A − 0.25)·4/3`, so mist starts at A > 0.625 (~6.25 s into a full upswing).
+    /// Channel A this frame, for instruments. Consumers take `effect_density`, which also feeds
+    /// the mist rate, so mist starts past A = 0.625.
     pub(crate) intensity_a: f32,
-    /// `max((A − 0.25)·4/3, 0)` — the density the active effect spawns at, resolved per frame.
+    /// The density the active effect spawns at, resolved per frame.
     pub effect_density: f32,
-    /// Channel B's current value — the slow sky/cloud density, resolved per frame.
+    /// Channel B this frame, the sky density in [0, 0.25].
     pub sky_density: f32,
-    /// The `weatherDensity` CVar (the video-options **Weather Intensity** setting, 0–3) — the
-    /// client-side particle-density step. Rendering only: it scales the spawn-rate gain of
-    /// rain/snow/mist through the quality table (see [`WeatherState::density_gain`]); it never
-    /// touches the wire grade, the ramps, or the storm/fog blend. Default 3 = the reference
-    /// install's live `Config.wtf` (`SET weatherDensity "3"`) — the look target.
+    /// The `weatherDensity` CVar, 0 to 3, which scales only the rain, snow and mist spawn rates.
+    /// Deviation: it defaults to 3 where the reference registers 2, because the precipitation
+    /// rates were graded against a reference install running 3.
     pub weather_density: u8,
-    /// Bumped on every wire TYPE change (fine included) — the Q-D cut signal (round 3): the
-    /// driver's cross-fade path stops emission at once (`0x67585d`), retires the open packet,
-    /// and discards every packet whose replay hasn't started (`0x67575a`). Same-type grade
-    /// changes (e.g. rain 1 → rain 0) do NOT cut — they drain via the ramp, rain thinning and
-    /// persisting, exactly as the director observed on `1 1 → 1 0` vs `1 1 → 0 0`.
+    /// Bumped on every wire type change, the cut: emission stops at once (`0x67585d`), the open
+    /// packet retires and every unreplayed packet is discarded (`0x67575a`). A same-type grade
+    /// change does not cut; the rain thins on the ramp.
     pub(crate) cut_seq: u32,
 }
 
-/// The `weatherDensity` quality table (`0x67b870`): setting 0–3 → spawn-rate gain `K` in
-/// `rate = K·P·grade`. The wx transcriptions carried quality 2's `0.66` as a constant, which
-/// under-spawned every effect ×1.52 vs the reference running at 3.
+/// The `weatherDensity` quality table (`0x67b870`): the spawn-rate gain `K` in `rate = K·P·grade`.
 const DENSITY_GAIN: [f32; 4] = [0.1, 0.33, 0.66, 1.0];
 
 impl Default for WeatherState {
@@ -162,30 +129,22 @@ impl Default for WeatherState {
 }
 
 impl WeatherState {
-    /// Apply one wire update (`SetWeather 0x67baf0` semantics: retarget both channels; `instant`
-    /// snaps them). A `Fine` packet targets 0 regardless of its grade.
+    /// Applies one wire update as `SetWeather` (`0x67baf0`); `Fine` targets 0 whatever its grade.
     fn apply(&mut self, kind: WeatherKind, grade: f32, instant: bool, now: f64) {
         let target = if kind == WeatherKind::Fine {
             0.0
         } else {
             grade.clamp(0.0, 1.0)
         };
-        // A TYPE change cuts (Q-D, round 3): emission stops instantly and the unreplayed
-        // pipeline is discarded — `effect_kind` flips to the NEW type at once (Fine ⇒ no
-        // effect spawns; a rain→snow swap starts snow while old rain drops fall out). Only a
-        // same-type grade change keeps the effect and drains it via the ramp.
+        // A type change cuts (`0x67585d`): `effect_kind` flips at once, so a rain-to-snow swap
+        // starts snow while the old drops fall out.
         if kind != self.kind {
             self.cut_seq = self.cut_seq.wrapping_add(1);
             self.effect_kind = kind;
         }
         self.kind = kind;
-        // Channel B (sky) lives in the **[0, 0.25] knee domain** — `SetWeather 0x67baf0` writes
-        // `clamp(grade, 0, 0.25)` into both B endpoints (the 0.25 @`0x8029b0`). With the ×4 in
-        // B's denominator this makes both channels swing in ~10 s, and `bcc = min(1, B·4)` ramps
-        // linearly over the WHOLE swing — fog visibly leads the rain up (rain needs A > 0.25)
-        // and starts clearing IMMEDIATELY on the way down. Feeding the full grade here (the
-        // 0310-era misread of the ×4 as "4× slower") pinned the fog at 100% for ~30 s of every
-        // downswing — the director's "takes a long time until it gets sunny" (0326).
+        // `SetWeather` clamps both sky endpoints to 0.25 (`0x8029b0`); the full grade here would
+        // hold the fog at 100% for most of every downswing.
         let sky_target = target.min(0.25);
         if instant {
             self.intensity.snap(target);
@@ -196,8 +155,7 @@ impl WeatherState {
         }
     }
 
-    /// Resolve the per-frame published values (the reference does this in the update driver
-    /// `0x67be40` → the ramp → the effect setters).
+    /// Resolves the frame's published values, as the reference's update driver (`0x67be40`) does.
     fn resolve(&mut self, now: f64) {
         let a = self.intensity.value(now);
         self.intensity_a = a;
@@ -205,14 +163,12 @@ impl WeatherState {
         self.sky_density = self.sky.value(now);
     }
 
-    /// The spawn-rate gain `K` for the current [`WeatherState::weather_density`] setting
-    /// (`0x67b870` quality table).
+    /// The spawn-rate gain `K` for the current `weather_density`.
     pub(crate) fn density_gain(&self) -> f32 {
         DENSITY_GAIN[usize::from(self.weather_density.min(3))]
     }
 
-    /// The spawn density for one effect type: the active effect gets the ramped density, every
-    /// other type 0 (its pool drains by particle lifetime).
+    /// The spawn density for one type: the active type's, else 0, so its pool drains by lifetime.
     pub(crate) fn density_for(&self, kind: WeatherKind) -> f32 {
         if self.effect_kind == kind {
             self.effect_density
@@ -222,21 +178,17 @@ impl WeatherState {
     }
 }
 
-/// The storm light-blend weight — `cloud_density_clamp 0x6d4500`: `bcc = min(1, density·4)`,
-/// purely the clamped sky density (no sun term). Lighting lerps the storm `LightParams` record
-/// over the clear one by this weight.
+/// The storm light-blend weight (`0x6d4500`), from the sky density alone with no sun term;
+/// lighting lerps the storm `LightParams` over the clear one by it.
 pub fn storm_blend(sky_density: f32) -> f32 {
     (sky_density * 4.0).min(1.0)
 }
 
-/// Label set for the weather tick — lighting's resolve runs `.after` this so the storm blend
-/// sees this frame's densities.
+/// The weather tick's set; lighting's resolve runs after it to see this frame's densities.
 #[derive(SystemSet, Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub(crate) struct WeatherTick;
 
-/// Drain wire updates into the channels and resolve the frame's densities. The debug panel's
-/// override (when armed) substitutes a synthetic wire update — the same path end-to-end.
-/// One step of the `WOW_WEATHER` script: apply (kind, grade, instant) at `at` seconds.
+/// One step of the `WOW_WEATHER` script: (kind, grade, instant) applied at `at` seconds.
 struct EnvStep {
     at: f64,
     kind: u32,
@@ -244,10 +196,8 @@ struct EnvStep {
     instant: bool,
 }
 
-/// Parse the `WOW_WEATHER` value: `;`-separated steps of `<type>,<grade>[,smooth][@<secs>]`
-/// (no `@` → t = 0). One step reproduces the old syntax; several script a transition — e.g.
-/// `1,0.9999,smooth;0,0,smooth@20` rains at boot and clears at t = 20 s, so downswing pacing
-/// is measurable headless.
+/// Parses `WOW_WEATHER`: `;`-separated steps of `<type>,<grade>[,smooth][@<secs>]`, so
+/// `1,0.9999,smooth;0,0,smooth@20` rains at boot and clears at 20 s.
 fn parse_env_script(v: &str) -> Vec<EnvStep> {
     v.split(';')
         .filter_map(|seg| {
@@ -276,9 +226,8 @@ fn weather_tick(
     mut next_dump: Local<f64>,
 ) {
     let now = time.elapsed_secs_f64();
-    // Dev/capture hook: the `WOW_WEATHER` script (see [`parse_env_script`]) drives the panel
-    // override, so captures and headless runs can force weather — or exercise live ramps in
-    // both directions — without a GM `.wchange`.
+    // The `WOW_WEATHER` script drives the panel override, so captures and headless runs can
+    // force weather without a GM `.wchange`.
     let script = env_script.get_or_insert_with(|| {
         std::env::var("WOW_WEATHER")
             .map(|v| parse_env_script(&v))
@@ -292,8 +241,8 @@ fn weather_tick(
         debug.weather.grade = step.grade;
         debug.weather.instant = step.instant;
     }
-    // A panel-armed override wins over the wire (and consumes the wire messages so a zone
-    // re-send doesn't fight the scrub); otherwise the wire drives.
+    // An armed panel override wins and consumes the wire messages, so a zone re-send cannot
+    // fight it.
     if debug.weather.force {
         if debug.weather.dirty {
             debug.weather.dirty = false;
@@ -317,8 +266,7 @@ fn weather_tick(
     }
     state.resolve(now);
 
-    // `WOW_WEATHER_DUMP=1`: print the live ramp at 1 Hz while a transition is in flight — the
-    // pacing instrument (the director's stopwatch vs the code, on real numbers, live pipeline).
+    // `WOW_WEATHER_DUMP=1` prints the live ramp at 1 Hz while a transition is in flight.
     if dump.is_none() {
         *dump = Some(std::env::var("WOW_WEATHER_DUMP").is_ok());
     }
@@ -339,20 +287,12 @@ fn weather_tick(
     }
 }
 
-/// Weather visuals: the state machine (this file) + the precipitation pools (`precip`).
-/// The storm light-blend itself lives in `lighting::update_time_lighting` (it owns the
-/// atmosphere resolve); it reads [`WeatherState`] `.after(WeatherTick)`.
+/// Weather visuals: the state machine and the precipitation pools. The storm light blend is
+/// lighting's, read after [`WeatherTick`].
 pub(crate) struct WeatherPlugin;
 
-/// **The weather command.** What the zone's weather should now be: `weather_type`/`grade`/
-/// `instant` drive the visuals' state machine ([`weather_tick`], decision 0310) and `sound_id`
-/// names the loop kit for the sound subsystem.
-///
-/// Owned here, written by whoever knows (decision 1160). It lived in `net` — where `SMSG_WEATHER`
-/// is decoded — and `NetPlugin` registered it, so the weather system could not run at all without
-/// a network stack: the world viewer's survey caught it as "Message not initialized" every frame.
-/// The engine owning the command and the game writing it is the same relationship the other way
-/// round, and it is the one that composes: an editor sets the weather with no server in sight.
+/// The zone's weather command: type, grade and `instant` drive the state machine, and `sound_id`
+/// names the sound loop kit. Owned here, so the world runs without a network stack.
 #[derive(Message, Clone, Copy)]
 pub struct WeatherMessage {
     pub weather_type: u32,
@@ -365,7 +305,7 @@ pub struct WeatherMessage {
 impl Plugin for WeatherPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<WeatherState>()
-            // The command is ours, so its registration is ours — see [`WeatherMessage`].
+            // Registered where the command is owned.
             .add_message::<WeatherMessage>()
             .add_systems(Update, weather_tick.in_set(WeatherTick));
         precip::register(app);
@@ -376,7 +316,6 @@ impl Plugin for WeatherPlugin {
 mod tests {
     use super::*;
 
-    /// The WOW_WEATHER script syntax: bare (old form), `,smooth`, and `@secs` steps.
     #[test]
     fn env_script_parses_steps() {
         let s = parse_env_script("1,0.9999,smooth;0,0,smooth@20");
@@ -385,13 +324,12 @@ mod tests {
         assert!((s[0].grade - 0.9999).abs() < 1e-6);
         assert_eq!((s[1].kind, s[1].instant), (0, false));
         assert!((s[1].at - 20.0).abs() < 1e-9);
-        // The old one-shot instant form still parses.
+        // A bare step is instant at t = 0.
         let s = parse_env_script("2,0.5");
         assert_eq!(s.len(), 1);
         assert!(s[0].instant && s[0].at == 0.0);
     }
 
-    /// Channel A: a 0→1 retarget crosses in ~10 s ((1·1+0.001)·10), the byte law.
     #[test]
     fn channel_a_full_swing_is_ten_seconds() {
         let mut c = Channel::new(1.0);
@@ -403,10 +341,7 @@ mod tests {
         assert_eq!(c.value(20.0), 1.0); // clamped
     }
 
-    /// Channel B runs the [0, 0.25] knee domain: a full sky swing (0→0.25) ALSO takes ~10 s
-    /// ((0.25·4+0.001)·10) — the ×4 cancels the quarter-span. The storm blend `min(1, B·4)`
-    /// therefore ramps linearly over the whole swing, both directions (0326: the "40 s sky"
-    /// was the 0310 misread, and it pinned the fog at 100% for ~30 s of every downswing).
+    /// A full sky swing, 0 to 0.25, also takes about 10 s: the ×4 cancels the quarter span.
     #[test]
     fn sky_swing_is_ten_seconds_and_clears_immediately() {
         let mut s = WeatherState::default();
@@ -414,7 +349,6 @@ mod tests {
         s.resolve(0.0);
         assert!((s.sky_density - 0.25).abs() < 1e-6, "knee-clamped target");
         assert!((storm_blend(s.sky_density) - 1.0).abs() < 1e-6);
-        // Downswing: fog starts clearing at once, gone in ~10 s.
         s.apply(WeatherKind::Fine, 0.0, false, 100.0);
         s.resolve(105.0);
         assert!(
@@ -426,8 +360,6 @@ mod tests {
         assert!(storm_blend(s.sky_density) < 0.01, "clear by ~10 s");
     }
 
-    /// A retarget mid-ramp restarts from the old *target* (`SetWeather`: `from ← old target`),
-    /// not the current ramped value — the byte behaviour, replacing the invented smoothing.
     #[test]
     fn retarget_restarts_from_old_target() {
         let mut c = Channel::new(1.0);
@@ -438,11 +370,10 @@ mod tests {
             (v - 1.0).abs() < 0.01,
             "restarts at the OLD target, got {v}"
         );
-        // Down-swing of Δ≈1 takes ≈10 s from the retarget epoch.
+        // A downswing of about 1 takes about 10 s from the retarget.
         assert!(c.value(15.2) < 0.01);
     }
 
-    /// The effect-density knee: nothing below grade 0.25; 0.25..1 maps to 0..1.
     #[test]
     fn effect_density_knee() {
         let mut s = WeatherState::default();
@@ -457,9 +388,6 @@ mod tests {
         assert!((s.effect_density - 0.5).abs() < 1e-5);
     }
 
-    /// The `weatherDensity` quality table (`0x67b870`) and its default: the reference install
-    /// runs `SET weatherDensity "3"` (K = 1.0) — the look target. The transcriptions' 0.66 is
-    /// setting 2, kept reachable via the panel.
     #[test]
     fn weather_density_gain_table() {
         let mut s = WeatherState::default();
@@ -473,28 +401,24 @@ mod tests {
         assert!((s.density_gain() - 1.0).abs() < 1e-6);
     }
 
-    /// A wire TYPE change cuts (Q-D): Fine flips the effect kind at once (emission stops that
-    /// frame — the pipeline discard rides `cut_seq`), while a same-type grade change keeps the
-    /// effect and drains it via the ramp — the director's `1 1 → 1 0` vs `1 1 → 0 0` split.
     #[test]
     fn type_change_cuts_same_type_drains() {
         let mut s = WeatherState::default();
         s.apply(WeatherKind::Rain, 1.0, true, 0.0);
         let seq = s.cut_seq;
-        // Same type, grade → 0: no cut; the effect drains on the ramp.
+        // Same type, grade to 0: no cut; the effect drains on the ramp.
         s.apply(WeatherKind::Rain, 0.0, false, 100.0);
         assert_eq!(s.cut_seq, seq);
         assert_eq!(s.effect_kind, WeatherKind::Rain);
         s.resolve(102.0);
         assert!(s.effect_density > 0.5, "mid-drain, still raining");
-        // Type change to Fine: cut — the effect kind flips immediately.
+        // A type change to Fine cuts, and the effect kind flips at once.
         s.apply(WeatherKind::Fine, 0.0, false, 105.0);
         assert_eq!(s.cut_seq, seq + 1);
         assert_eq!(s.effect_kind, WeatherKind::Fine);
         assert_eq!(s.density_for(WeatherKind::Rain), 0.0);
     }
 
-    /// The storm blend: bcc = min(1, 4·density) — full overcast by density 0.25.
     #[test]
     fn storm_blend_clamp() {
         assert_eq!(storm_blend(0.0), 0.0);
diff --git a/crates/benilla-world/src/weather/precip/census.rs b/crates/benilla-world/src/weather/precip/census.rs
index 95b81c9e..4172168a 100644
--- a/crates/benilla-world/src/weather/precip/census.rs
+++ b/crates/benilla-world/src/weather/precip/census.rs
@@ -1,47 +1,20 @@
-//! The precip **instruments** — the read-only field censuses the build loop logs at 1 Hz.
-//! Split from [`super::pool`], which owns the sim: nothing here mutates a pool or is read by
-//! one, and the two answer different questions — [`census`] reads the field **horizontally**
-//! (is there weather in front of me?), [`column`]/[`profile`] read it **vertically** (where
-//! does it stop overhead, and how abruptly?).
+//! Read-only censuses of the live precip field, logged at 1 Hz: [`census`] reads it horizontally
+//! (is there weather ahead?), [`column`] and [`profile`] vertically (where does it stop overhead,
+//! and how abruptly?).
 
 use bevy::math::Vec3;
 
 use super::pool::Drop;
 
-/// The eye band a census splits on: ±3 yd of the camera's height — the slice a player actually
-/// looks *through*, as opposed to the column of sky above them.
+/// The eye band a census counts: ±3 yd of the camera's height.
 const CENSUS_BAND: f32 = 3.0;
-/// The near-field radius a census counts: the sphere whose flakes dominate the look (the point
-/// sprite is 14 px at the eye and under 5 px past 30 yd).
+/// The near-field radius a census counts: the flakes that dominate the look.
 const CENSUS_NEAR: f32 = 15.0;
 
-/// A one-line **spatial** census of a live drop field, relative to the camera — the instrument
-/// for *"can you outrun the weather?"*, which the pool COUNTS alone cannot answer.
-///
-/// `axis` is a horizontal unit vector: the player's motion heading while they move, their view
-/// heading while they stand.
-///
-/// **`fwd`/`bwd` is the metric — read it first.** It splits the eye band about the plane through
-/// the camera ⊥ `axis`, reads ~50/50 on a centred field whatever the heading, and is what actually
-/// answers "is there weather in front of me". Measured across the 1159 fix: 3200/3350 standing,
-/// collapsing to 0 while running before the spawn-slab tilt and holding ~2115 after it.
-///
-/// **`centroid` is a weak second, and is easy to misread — it was, once.** Two biases sit on it:
-/// the drift heading is a fixed WORLD azimuth, so even a standing field's centroid sits
-/// `drift · mean_age` off along it (−5.5 yd at wire grade 0.6, −14 at 1.0, depending on which way
-/// the player faces); and it is *count-weighted*, so long-lived particles born high and to the rear
-/// dominate it. Under the slab tilt those two effects nearly cancel the forward shift at low grade:
-/// a Monte-Carlo of [`super::pool::spawn_particle`] predicts the running centroid improving only 9% at grade 0.6
-/// against 49% at 1.0, and the live client measured 11% and 61% — agreeing with the law while
-/// looking, on the centroid alone, like the fix had barely worked. Never conclude from it alone.
-///
-/// `frames` is the count since the previous census, and it is **not decoration**: `run_kind`'s
-/// budget is `rate · min(dt, 1/60)` with the remainder dropped, so emission per second scales with
-/// frame rate and a sub-60 fps leg measures a genuinely thinner field than a 60 fps one on
-/// identical code. Two census lines are only comparable at equal `frames` — measured, the field
-/// tracks `fps/60` and nothing else: 1542/2115 = 72.9% and 1598/2134 = 74.9% against frame-rate
-/// ratios of 71.8% and 73.0%. (An earlier revision of this line claimed 48%, which was an
-/// arithmetic slip on my part; it read as an unexplained anomaly and cost a wasted RE question.)
+/// A one-line spatial census of a live drop field relative to the camera; `axis` is the motion
+/// heading while moving, the view heading while standing. Read `fwd`/`bwd` first (~50/50 on a
+/// centred field): the centroid is biased by the world-fixed drift and long-lived particles.
+/// Below 60 fps emission scales with frame rate, so two lines compare only at equal `frames`.
 pub(super) fn census(
     drops: &[Drop],
     cam: Vec3,
@@ -75,44 +48,25 @@ pub(super) fn census(
     ))
 }
 
-/// The vertical profile's step, in yards — fine enough to resolve the alpha fade-in, which spans
-/// only the first `|v_z|` yards of fall (≈3.9 yd at wire grade 0.6).
+/// The profile's step in yards: fine enough to resolve the 1 s fade-in (~4 yd of fall).
 const CENSUS_TOP_STEP: f32 = 2.0;
-/// How far below the ceiling the profile reaches: 10 steps = 20 yd, which brackets the whole
-/// approach to the plateau at every grade (the fastest blizzard flake falls 6.5 yd in its fade).
+/// 10 steps reach 20 yd below the ceiling, past the fastest flake's 6.5 yd fade.
 const CENSUS_TOP_BANDS: usize = 10;
 
-/// The **vertical** profile of a live field, top-down from its own ceiling — the instrument for
-/// *"where does the snow stop, and how abruptly?"*, which neither the pool counts nor [`census`]'s
-/// horizontal split can answer.
-///
-/// This exists because the director reported the top edge of benilla's snowfall reading as a hard
-/// horizontal line where the reference's fades in. That is a claim about `flakes(height)`, so it
-/// is measured as `flakes(height)`: the ceiling, the alpha-weighted flakes per yard in 2 yd steps
-/// below it, and the plateau the profile is climbing toward.
-///
-/// **Alpha-weighted, deliberately.** The geometric ceiling is a razor plane by construction —
-/// every flake is born at local `z = +30` ([`super::pool::spawn_particle`]) — so a raw count *always* reports a
-/// hard edge and can never tell the two clients apart. What the eye sees is softened by the 1 s
-/// linear fade-in (`alpha = clamp01(t − f1)`, wow-re `rf-snow-flake-render` §2.4), and that fade is
-/// the only thing standing between a flat spawn plane and a visible cut. So the weight is the alpha
-/// the renderer actually emits, and the profile reads the way the look does: a soft edge climbs to
-/// the plateau over several steps, a hard one reaches it in the first.
-///
-/// `fade_in` is the kind's fade-in duration in seconds; pass `0.0` for a kind that has none (rain's
-/// streaks carry no vertex alpha), which weights every particle 1.
-///
-/// All densities are per **yard of height**, so the steps and the plateau are directly comparable.
+/// The vertical profile of a live field, top-down from its own ceiling, in alpha-weighted flakes
+/// per yard of height: it tells a faded top edge from a cut one. Alpha-weighted because every
+/// flake is born on the slab's plane, so a raw count always reads a cut; the eye sees the 1 s
+/// fade-in (`snowpoint.bls`). `fade_in` is 0 for a kind with no vertex alpha (rain).
 pub(super) struct Column {
-    /// The highest particle's height above the eye — the field's geometric ceiling.
+    /// The highest particle's height above the eye.
     pub(super) top: f32,
-    /// Alpha-weighted density per yard, in [`CENSUS_TOP_STEP`]-yd steps down from [`Column::top`].
+    /// Density per yard in [`CENSUS_TOP_STEP`]-yd steps down from [`Column::top`].
     pub(super) steps: [f32; CENSUS_TOP_BANDS],
-    /// Alpha-weighted density per yard through the eye band — what the steps climb toward.
+    /// Density per yard through the eye band, which the steps climb toward.
     pub(super) plateau: f32,
 }
 
-/// The measurement behind [`profile`], separated so tests read numbers instead of parsing prose.
+/// The measurement behind [`profile`].
 pub(super) fn column(drops: &[Drop], cam: Vec3, fade_in: f32) -> Option<Column> {
     let top = drops
         .iter()
@@ -168,9 +122,8 @@ mod tests {
     use super::*;
     use crate::weather::precip::{SNOW_FADE_IN, SNOW_VZ_BASE, SNOW_VZ_W};
 
-    /// A steady snow column: `n` flakes spread uniformly over the 40 yd from a ceiling at eye + 30
-    /// down to ground 10 below, each aged by how far it has already fallen at `vz`. This is the
-    /// shape a constant emission rate onto a flat spawn plane actually produces.
+    /// `n` flakes spread evenly from a ceiling at eye + 30 to ground 10 below, each aged by its
+    /// fall at `vz`: what a constant emission onto a flat spawn plane produces.
     fn steady_column(n: usize, vz: f32) -> Vec<Drop> {
         (0..n)
             .map(|i| {
@@ -186,21 +139,11 @@ mod tests {
             .collect()
     }
 
-    /// What the column profile has to be able to do is **tell a faded top edge from a cut one** —
-    /// it is the instrument for the director's "hard line" report, and an instrument that reads the
-    /// same either way would have closed that report on nothing.
-    ///
-    /// The geometric ceiling is a razor plane in both cases (every flake is born at local `z = +30`),
-    /// so the *only* thing that can soften it is the 1 s fade-in. Weighted by that fade, the top
-    /// step reads a quarter of the plateau and the profile climbs into it over the ≈3.9 yd a
-    /// grade-0.6 flake falls in its first second; with the fade switched off the identical field
-    /// reports its true cut — the first step already at the plateau.
+    /// The ceiling is a flat plane either way; only the 1 s fade-in can soften it.
     #[test]
     fn the_column_profile_separates_a_faded_edge_from_a_cut_one() {
-        // The director's wire grade 0.6 through the published knee (`0x67bcc8`,
-        // `max(0, (g − 0.25)·4/3)` = 0.4667). This is the BASE fall only, without
-        // `spawn_particle`'s `+w·rand()` spread — 3.63 yd/s against the live field's ~3.9 mean.
-        // One speed for every flake is what keeps the alpha profile analytic here.
+        // Wire grade 0.6 through the knee `max(0, (g − 0.25)·4/3)` (`0x67bcc8`), at the base
+        // fall speed only: one speed for every flake keeps the alpha profile analytic.
         let vz = SNOW_VZ_BASE + SNOW_VZ_W * ((0.6 - 0.25) * (4.0 / 3.0));
         let drops = steady_column(8000, vz);
 
@@ -214,7 +157,7 @@ mod tests {
         );
 
         let faded = column(&drops, Vec3::ZERO, SNOW_FADE_IN).expect("a populated field");
-        // Mean alpha over the top 2 yd is `1/vz` — a quarter of full at this grade.
+        // Mean alpha over the top 2 yd is `1/vz`, a quarter of full at this grade.
         let edge = faded.steps[0] / faded.plateau;
         assert!(
             (edge - 1.0 / vz).abs() < 0.05,
diff --git a/crates/benilla-world/src/weather/precip/mist.rs b/crates/benilla-world/src/weather/precip/mist.rs
index 92bd4d31..ac93e9df 100644
--- a/crates/benilla-world/src/weather/precip/mist.rs
+++ b/crates/benilla-world/src/weather/precip/mist.rs
@@ -1,21 +1,7 @@
-//! The companion mist — every precip type owns one in the reference (its own object: ctor
-//! `0x67a5b0`, spawn `0x67a990`, render `0x67ae20`; rain/snow texture `SnowMist01.blp`, sand
-//! `WeatherMistGrainy01.blp`). Spawn law: wow-re's **difftested** `mist.rs` transcription;
-//! lifetime/motion/fade semantics: the §5 ten-agent finding
-//! `system/lighting/scratch/rf-weather-mist-motion.md` (byte-arbitrated) — every constant here
-//! is now VERIFIED.
-//!
-//! The mechanism: up to 128 puffs, spawned at `2·max(density−0.5, 0)·K·Q` nodes/s (zero below
-//! the density knee), each born from draws in the **wind-heading frame** — a polar motion
-//! basis `dir` (per-type radius, azimuth −1.57±0.175, a gentle rise) and a box scatter
-//! (±22 × ±22 × ±12.5, ctor args stored verbatim) — placed `1.5·dir` upstream of the camera
-//! with `z = max(ground, seeded z) + 6`. Nodes live **2.7 ± 0.15 s** (the 1024 Hz weather
-//! clock), stream at `pos += dt·dir` (≈5 yd/s rain, ≈9 snow) plus a small isotropic
-//! `0.5·dt²·tail` rise-assist, and fade over **0.4 s** ramps to **full opacity** — a churning
-//! VOLUME of fog-coloured 12×12 quads through the camera's height band. (The *constant near
-//! haze* of reference rain is NOT these puffs — they are invisible within 6 yd — it is the
-//! weather→scene-fog coupling: the zone's clear↔storm LightParams fog lerped at
-//! `bcc = min(1, density·4)`, which `lighting::update_time_lighting` already applies.)
+//! The mist companion every precip type owns in the reference (ctor `0x67a5b0`, spawn
+//! `0x67a990`, render `0x67ae20`): up to 128 fog-coloured 12×12 puffs streaming through the
+//! camera's height band. The near haze of reference rain is not these puffs, invisible within
+//! 6 yd, but the scene fog's storm lerp at `min(1, density·4)` (`update_time_lighting`).
 
 use avian3d::prelude::{SpatialQuery, SpatialQueryFilter};
 use bevy::prelude::*;
@@ -25,102 +11,73 @@ use crate::weather::{WeatherKind, WeatherState};
 use super::pool::{HeightCache, CELL};
 use super::{rand01, wow_azimuth_to_bevy, WeatherWind};
 
-/// Mist spawn-rate gain `Q` — per **kind** and per leg. The rate is `2·max(density − 0.5, 0)·K·Q`
-/// nodes/s (each density param-set's step 5 → effect+0x3c = mist+0x20 accumulator).
-///
-/// **Snow carries its own pair and it is not rain's** (wow-re `weather_scalars`:
-/// `snow_density_param_set 0x6776c0` reads `0x80732c` = 24 / `0x80ffd8` = 48, against
-/// `rain_density_param_set 0x6749e0`'s `0x80ff9c` = 18 / `0x80ffa0` = 38). Applying rain's 38 to
-/// snow ran the snow mist at **0.79×** for as long as this constant was shared — the same class of
-/// mistake as reading a shared byte offset and assuming a shared table. Every scalar on these two
-/// paths is a *pair*; check the pair before reusing a number across kinds.
+/// Mist spawn-rate gain `Q` per kind and leg, in `2·max(density − 0.5, 0)·K·Q` nodes/s: rain
+/// `0x80ff9c` = 18 / `0x80ffa0` = 38 (`0x6749e0`), snow `0x80732c` = 24 / `0x80ffd8` = 48
+/// (`0x6776c0`). Every scalar on these paths is a per-kind pair.
 const MIST_Q_RAIN: f32 = if super::SHADER_LEG { 38.0 } else { 18.0 };
 const MIST_Q_SNOW: f32 = if super::SHADER_LEG { 48.0 } else { 24.0 };
-/// Node capacity (ctor arg; up to 128 camera-anchored puffs).
+/// Node capacity, a ctor argument.
 pub(super) const MIST_CAP: usize = 128;
-/// Puff quad size: 12×12 world units (ctor arg) → half-extent 6.
+/// Half the 12×12 puff quad (a ctor argument).
 const MIST_HALF: f32 = 6.0;
-/// Puff floor bias: `z = max(grid_ground, seeded z) + 6.0` (`mist_spawn 0x67a990`: the
-/// `size·0.5` term over the fog-grid sample). The **max** is what makes the mist a volume
-/// rather than a sheet.
+/// Puff floor bias, `z = max(ground, seeded z) + 6` (`0x67a990`): the max makes a volume.
 const MIST_FLOOR: f32 = 6.0;
-/// Placement box extents — ctor args {44, 44, 25} stored **verbatim** at mist+0x04/08/0c
-/// (VERIFIED: plain `mov`, no doubling); the spawn scatters `((m−1)−0.5)·ext` per axis in the
-/// wind-heading frame → **±22 × ±22 × ±12.5** around the cluster centre.
+/// Placement box: ctor args {44, 44, 25} stored as-is, so the scatter is ±22 × ±22 × ±12.5.
 const MIST_EXT_XY: f32 = 44.0;
 const MIST_EXT_Z: f32 = 25.0;
-/// The polar motion basis each node carries (`mist_spawn` draws 1–3, stored at node+0x114):
-/// azimuth `−1.57 ± 0.5·0.349` in the wind-heading frame (+0x24/+0x28), a per-type radius
-/// (below), rise `0.333 ± 0.5·0.0333` (`0x807a40`/`0x807334`). The node is born `1.5·dir`
-/// upstream of the camera (`0x80308c` = 1.5) and streams along `dir`.
+/// Each node's polar motion basis in the wind-heading frame (`0x67a990` draws 1–3; rise
+/// `0x807a40`, `0x807334`); it is born `1.5·dir` upstream of the camera (`0x80308c`).
 const MIST_AZ_BASE: f32 = -1.57;
 const MIST_AZ_SCALE: f32 = 0.349;
-/// Per-type radius base/span (mist+0x34/+0x38, ctor-verified): rain 5.0/1.2, snow 9.0/3.0.
-/// (Sand is 15.0/4.5 and lands with the sand slice.)
+/// Per-type radius base and span (ctor arguments).
 const MIST_R_RAIN: (f32, f32) = (5.0, 1.2);
 const MIST_R_SNOW: (f32, f32) = (9.0, 3.0);
 const MIST_DIR_Z_BASE: f32 = 0.333_333_34;
 const MIST_DIR_Z_SCALE: f32 = 0.033_333_335;
 const MIST_PLACE_SCALE: f32 = 1.5;
-/// Alpha (VERIFIED — there is **no 0.4 cap**): per corner,
-/// `round(255 · linearstep(6, 18, corner→cam) · trapezoid)`. The distance term rises with
-/// distance (puffs are invisible within 6 yd of the eye — the near haze is the scene fog, not
-/// these); a mid-life puff at ≥ 18 yd is **fully opaque** fog colour.
+/// Per-corner alpha `linearstep(6, 18, corner→cam)·trapezoid`, uncapped: a mid-life puff past
+/// 18 yd is fully opaque.
 const MIST_ALPHA_NEAR: f32 = 6.0;
 const MIST_ALPHA_FAR: f32 = 18.0;
-/// Node life (VERIFIED): draw 8 stamps `round((2.7 ± 0.15)·1024)` ticks of the **1024 Hz**
-/// weather clock (`0xc62970`) — life uniform in [2.55, 2.85) s.
+/// Node life, draw 8: `round((2.7 ± 0.15)·1024)` ticks of the 1024 Hz weather clock (`0xc62970`).
 const MIST_LIFE_BASE: f32 = 2.7;
 const MIST_LIFE_SCALE: f32 = 0.3;
-/// The fade trapezoid (VERIFIED): `clamp(age/0.4) · clamp((life−age)/0.4)` — mist+0x30 = 0.4
-/// is each ramp's DURATION in seconds (not an alpha cap); the plateau sits at 1.0.
+/// The fade trapezoid's ramp length in seconds, not an alpha cap.
 const MIST_FADE_S: f32 = 0.4;
-/// The node's tail draw (`mist_spawn` draw 7): `((m−1)−0.5)·3.333` ∈ ±1.667 — the isotropic
-/// `0.5·dt²·tail` term of the per-frame advance.
+/// The tail draw (`0x67a990` draw 7), ±1.667: the isotropic `0.5·dt²·tail` term of the advance.
 const MIST_TAIL_SCALE: f32 = 3.333_333_3;
-/// While a node sits below its terrain-follow target, `tail += 5/3` per FRAME (`0x80655c`,
-/// `0x67b421`) — a frame-rate-dependent rise-assist in the reference, transcribed as-is.
+/// Below its follow target a node's `tail` grows 5/3 per frame (`0x80655c`, `0x67b421`), a
+/// frame-rate-dependent rise-assist in the reference too.
 const MIST_TAIL_RISE: f32 = 5.0 / 3.0;
-/// The spawn **path lookahead** (round 7, `0x67a7a0`): up to 64 heights sampled one grid cell
-/// (`1.0417 = 0x80ff98`) apart along the node's horizontal heading; count =
-/// `min(64, round(planarSpeed · 0.96 / 1.0417))` (≈5 rain, ≈8 snow — a ~1 s lookahead).
+/// The spawn path lookahead (`0x67a7a0`): `min(64, round(planarSpeed·0.96/CELL))` heights, one
+/// grid cell apart along the node's heading, about 1 s of travel (≈5 rain, ≈8 snow).
 const MIST_LOOKAHEAD_SPEED_S: f32 = 0.96;
 const MIST_LOOKAHEAD_MAX: usize = 64;
-/// The slope-validity deltas over the baked samples (`0x67a8e1–0x67a933`): group `m` is invalid
-/// when `s[m+1]−s[m] > 0.5` or `s[m+2]−s[m] > 0.75` or `s[m+3]−s[m] > 1.0` — a WMO wall's
-/// roof-height jump trips it, so **puffs die at the wall and never enter the room**: the first
-/// invalid group truncates life to `life·(valid+1)/count`; zero valid ⇒ STILLBORN (`0x67a96c`).
+/// Slope validity (`0x67a8e1`–`0x67a933`): group `m` fails when `s[m+k] − s[m]` exceeds 0.5,
+/// 0.75, 1.0 for k = 1, 2, 3; life is cut to `(valid + 1)/count` of itself, so puffs die at walls.
 const MIST_SLOPE_1: f32 = 0.5;
 const MIST_SLOPE_2: f32 = 0.75;
 const MIST_SLOPE_3: f32 = 1.0;
-/// The follow's upward-only per-frame z-step cap (`0x67b433–5a`; the exact scalar order is
-/// flagged in wow-re for a transcription re-check).
+/// The follow's upward per-frame z step cap (`0x67b433`); its exact scalar order is untraced.
 const MIST_Z_STEP_CAP: f32 = 3.0;
 
-/// One mist puff: position, its stored motion basis, and the lifecycle.
+/// One mist puff.
 struct MistNode {
     pos: Vec3,
-    /// The wind-yawed polar direction (`mist_spawn` node+0x114): advanced `pos += dt·dir` per
-    /// frame (VERIFIED — the drift scalar is the frame dt, ≈|dir| yd/s, framerate-independent).
+    /// The wind-yawed motion basis, `pos += dt·dir` per frame: `|dir|` yd/s at any frame rate.
     dir: Vec3,
-    /// node+0x128: the isotropic `0.5·dt²·tail` term; grows 5/3 per frame while below the
-    /// ground-follow target (the rise-assist).
+    /// The isotropic `0.5·dt²·tail` term of the advance.
     tail: f32,
     age: f32,
-    /// Per-node life (2.7 ± 0.15 s on the 1024 Hz clock).
+    /// Seconds, cut short at spawn by the slope walk.
     life: f32,
-    /// The spawn-baked height profile along the node's own path — one sample per grid cell
-    /// (round 7, `0x67a7a0`; the render never queries the grid live — `0x67ae20` has ZERO grid
-    /// reads, refuting an interim render-side hide). The follow target lerps into this array;
-    /// the slope-validity walk at spawn already truncated life at the first jump, so a puff
-    /// FADES OUT before reaching a wall instead of drifting into the room.
+    /// The ground baked per cell at spawn (`0x67a7a0`); the render reads no grid (`0x67ae20`).
     path: Vec<f32>,
-    /// Horizontal speed (yd/s) — the baked-array index advances `speed·age/1.0417`.
+    /// Horizontal speed in yd/s; the path index advances `speed·age/CELL`.
     planar_speed: f32,
 }
 
-/// The mist companion pool — every precip type carries one (the reference builds it inside
-/// each effect ctor); it spawns only above the density 0.5 knee.
+/// The mist pool; it spawns only above the 0.5 density knee.
 #[derive(Default)]
 pub(super) struct Mist {
     nodes: Vec<MistNode>,
@@ -128,16 +85,13 @@ pub(super) struct Mist {
 }
 
 impl Mist {
-    /// The stop-flag retire (`0x67b234`, round 7): a wire TYPE change also retires the
-    /// SCHEDULED-but-unborn nodes — the spawn budget zeroes with the cut. Live nodes finish
-    /// their (possibly truncated) lives normally.
+    /// A type change retires the unborn nodes (`0x67b234`); live ones finish their lives.
     pub(super) fn cut(&mut self) {
         self.budget = 0.0;
     }
 }
 
-/// The slope-validity walk over the baked path (`0x67a8e1–0x67a933`): `Some(m)` = the first
-/// invalid group's index (`m` = how many groups were valid before it), `None` = all valid.
+/// The first invalid group's index, which is how many groups before it were valid.
 fn first_invalid_group(path: &[f32]) -> Option<usize> {
     let n = path.len();
     for m in 0..n {
@@ -149,36 +103,16 @@ fn first_invalid_group(path: &[f32]) -> Option<usize> {
     None
 }
 
-/// The mist's spawn accumulator — `acc := min(acc + dt·rate, MIST_CAP)` (`0x67b141`–`0x67b1aa`).
-///
-/// **This is the one precip layer whose density survives a frame-rate drop**, and the reason is
-/// this function. The drop kernels budget `rate · min(dt, 1/60)` and *discard* the remainder
-/// (verified: the constant at `0x80ffcc` has exactly six sites, one `fcomp`/`fld` pair per effect,
-/// and the count lands in a stack local that never persists) — so streaks and flakes thin in
-/// proportion to `fps/60`. The mist instead multiplies the **raw, uncapped** dt (`0xc62510` at
-/// `0x67b141`, absent from that six-site census), adds the carry, and stores it back
-/// (`0x67b172`), spending exactly one whole node per free slot (`0x67b261`: `fsub 1.0`) and
-/// keeping the fraction. A hitch therefore shifts the storm's **composition**, not just its
-/// density — the mist holds while the flakes thin.
-///
-/// The ceiling is `[mist+0x48]`, the **size field of the node container** at `mist+0x44`, written
-/// once from the ctor's 8th argument (`0x67a724`) which is `push 0x80` = **128 at all three call
-/// sites** (`0x674645` rain, `0x677448` snow, `0x679149` sand). It is a spiral-of-death guard and
-/// never a budget cap: the drain can only spend into a free slot and there are [`MIST_CAP`] of
-/// them, so 128 is the *smallest* ceiling that discards nothing the array could have absorbed.
-///
-/// benilla carried a bare, uncited `8.0` here. At the shader leg's 38 nodes/s that saturates after
-/// a **0.21 s** hitch (0.32 s at the CVar's default gain), against the binary's 3.4 s — quietly
-/// re-introducing the very frame-rate coupling the accumulator exists to prevent, and *only* on
-/// hitches. Decision 1159's follow-up.
+/// The spawn accumulator, `min(acc + dt·rate, MIST_CAP)` (`0x67b141`–`0x67b1aa`): the raw dt
+/// (`0xc62510`) with the fraction kept (`0x67b172`, `0x67b261`), so the mist holds through a
+/// hitch while the flakes thin. The ceiling, 128 at all three ctor call sites (`0x67a724`:
+/// `0x674645`, `0x677448`, `0x679149`), is a spiral guard, never a budget cap.
 fn accrue(budget: f32, rate: f32, dt: f32) -> f32 {
     (budget + rate * dt).min(MIST_CAP as f32)
 }
 
-/// The mist companion's frame: spawn-rate accumulator `budget += dt·2·max(density−0.5, 0)·K·Q`
-/// (the arg is the RAMPED effect density — the same `effect+0xd0` value the drop kinematics
-/// read, so the knee sits on the density, not the raw wire grade), one node per unit, cap 128;
-/// then every node streams along its motion basis and retires at end-of-life.
+/// The mist's frame: accrue, spawn one node per whole unit, stream, retire. The 0.5 knee sits on
+/// the ramped effect density the drop kinematics read (`effect+0xd0`), not the raw wire grade.
 pub(super) fn run_mist(
     mist: &mut Mist,
     weather: &WeatherState,
@@ -190,13 +124,8 @@ pub(super) fn run_mist(
     dt: f32,
     cam_pos: Vec3,
 ) {
-    // The ground samples cast from the SAME spawn plane as the active kind's drops — the
-    // reference has ONE fog grid per effect, and the grid must see ROOFS (drops die on them,
-    // round 3). Casting from the camera's own height put the ray UNDER the ceiling with the
-    // camera indoors: every sample saw the interior floor and the mist volume filled the room
-    // at floor+6 (director-caught, 2026-07-13 — the forge's ceiling quads). Sharing the plane
-    // also stops the height cache thrashing between the drop and mist passes (its clear
-    // triggers on a >8 yd plane move).
+    // One grid per effect: cast from the drops' spawn plane, since from the camera an indoor ray
+    // starts under the ceiling and fills the room, and two planes would thrash the height cache.
     let cast_plane = cam_pos.y
         + match weather.effect_kind {
             WeatherKind::Snow => super::SNOW_Z_OFF,
@@ -206,8 +135,8 @@ pub(super) fn run_mist(
         WeatherKind::Snow => (MIST_Q_SNOW, MIST_R_SNOW),
         _ => (MIST_Q_RAIN, MIST_R_RAIN),
     };
-    // Any active precip type drives its mist; sand's law differs (no 0.5 knee, no ×2) and
-    // lands with the sand slice.
+    // Sand takes the rain law here; the reference's sand mist has no 0.5 knee, no ×2 and a
+    // 15/4.5 radius.
     let rate = if weather.effect_kind != WeatherKind::Fine {
         2.0 * (weather.effect_density - 0.5).max(0.0) * weather.density_gain() * q
     } else {
@@ -217,8 +146,7 @@ pub(super) fn run_mist(
     let yaw = wind.mist_yaw();
     while mist.budget >= 1.0 && mist.nodes.len() < MIST_CAP {
         mist.budget -= 1.0;
-        // The difftested spawn (`mist_spawn 0x67a990`): a polar motion basis + a box scatter,
-        // both in the wind-heading frame; the node is born 1.5·|dir| upstream of the camera.
+        // A polar motion basis and a box scatter, both in the wind-heading frame (`0x67a990`).
         let az = MIST_AZ_BASE + (rand01(rng) - 0.5) * MIST_AZ_SCALE;
         let radius = r_base + (rand01(rng) - 0.5) * r_span;
         let rise = MIST_DIR_Z_BASE + (rand01(rng) - 0.5) * MIST_DIR_Z_SCALE;
@@ -230,14 +158,10 @@ pub(super) fn run_mist(
                 (rand01(rng) - 0.5) * MIST_EXT_XY,
             );
         let mut pos = cam_pos - dir * MIST_PLACE_SCALE + place;
-        // `z = max(ground, seeded z) + 6` — a VOLUME from ground+6 up through the camera's
-        // height band, not a ground sheet. Over a building "ground" is the ROOF (the grid is
-        // a max-from-above), so indoor volumes never fill.
+        // Over a building the ground is the roof (the grid is a max from above): rooms never fill.
         let ground = heights.ground_y(pos.x, pos.z, cast_plane, spatial, filter);
         pos.y = MIST_FLOOR + pos.y.max(ground);
-        // The spawn path lookahead (round 7): bake the height profile one cell at a time along
-        // the horizontal heading, walk the slope-validity groups, truncate life at the first
-        // jump — a wall's roof step kills the puff before it can enter the room.
+        // The lookahead: bake the path's ground, then cut life at the first slope jump (a wall).
         let planar = Vec3::new(dir.x, 0.0, dir.z);
         let planar_speed = planar.length();
         let n = ((planar_speed * MIST_LOOKAHEAD_SPEED_S / CELL).round() as usize)
@@ -272,10 +196,8 @@ pub(super) fn run_mist(
     }
     for n in &mut mist.nodes {
         n.age += dt;
-        // The verified per-frame advance: `pos += dt·dir + 0.5·dt²·tail` (isotropic tail
-        // term). The follow target is a LERP into the SPAWN-BAKED path profile (+6) — never a
-        // live grid query (round 7, `0x67ae20` reads no grid); while below it the tail grows
-        // 5/3 per frame and z steps up toward it, capped per frame.
+        // `pos += dt·dir + 0.5·dt²·tail`; the follow target lerps the baked path (+6), and below
+        // it the tail grows and z steps up, capped per frame.
         n.pos += n.dir * dt + Vec3::splat(0.5 * dt * dt * n.tail);
         let idx = (n.planar_speed * n.age / CELL).max(0.0);
         let (lo, hi) = (idx.floor() as usize, idx.ceil() as usize);
@@ -290,12 +212,8 @@ pub(super) fn run_mist(
     mist.nodes.retain(|n| n.age < n.life);
 }
 
-/// Mist puffs: 12×12 camera-facing quads, RGB = the CURRENT fog colour (one flat tint), alpha
-/// evaluated **per corner** — `linearstep(6, 18, corner→cam) · trapezoid(age)` at full range
-/// (the reference computes the distance ramp per billboard corner: `mistr_corner_dist` →
-/// `mistr_color_repack`; no peak cap) — so a quad hanging beside the camera still shows its
-/// far corners. Alpha-blended, fog off (the tint already IS the fog colour). Pushed onto the
-/// shared effect stream (0733), perimeter corner order for the quad-index pattern.
+/// Mist puffs: 12×12 camera-facing quads in the current fog colour (so drawn fog-off), alpha per
+/// corner (`0x67add0`, packed at `0x67ae20`) so a quad beside the camera shows its far corners.
 pub(super) fn push_mist(
     out: &mut Vec<crate::particles::buffer::EffectVertex>,
     mist: &Mist,
@@ -307,9 +225,7 @@ pub(super) fn push_mist(
     let r = cam_right * MIST_HALF;
     let u = cam_up * MIST_HALF;
     for node in mist.nodes.iter().take(MIST_CAP) {
-        // trapezoid = clamp(age/0.4) · clamp((life−age)/0.4) — 0.4 s ramps, plateau 1.0. The
-        // spawn lookahead already truncated `life` at the first slope jump, so a wall-bound
-        // puff rides this SAME ramp to zero before the wall — no separate hide.
+        // A wall-bound puff's life was cut at spawn, so this same ramp fades it before the wall.
         let trapezoid = (node.age / MIST_FADE_S).clamp(0.0, 1.0)
             * ((node.life - node.age) / MIST_FADE_S).clamp(0.0, 1.0);
         let c = node.pos;
@@ -336,28 +252,21 @@ pub(super) fn push_mist(
 mod tests {
     use super::*;
 
-    /// The mist accumulator carries a hitch's whole backlog, where the drop kernels would have
-    /// thrown it away — the one place precip density is frame-rate-independent.
-    ///
-    /// The old uncited `8.0` ceiling clipped that at a fifth of a second of stall. Pinned in the
-    /// units that matter: the shader leg's 38 nodes/s against the byte ceiling of [`MIST_CAP`].
+    /// The shader leg's 38 nodes/s against the ceiling of [`MIST_CAP`].
     #[test]
     fn a_hitch_keeps_its_mist_backlog_up_to_the_node_capacity() {
         let rate = 2.0 * (1.0 - 0.5) * 1.0 * MIST_Q_RAIN; // full density, weatherDensity 3 → 38/s
-                                                          // A 1 s stall: every node owed is still owed afterwards. The retired `8.0` kept 8 of 38.
         let after = accrue(0.0, rate, 1.0);
         assert!(
             (after - rate).abs() < 1e-3,
             "a 1 s stall owes {rate} nodes, accumulator kept {after}"
         );
-        // The ceiling is the node capacity, and it is a spiral guard, not a budget cap: nothing
-        // above `MIST_CAP` could ever be spent, because the drain needs a free slot per node.
         assert_eq!(accrue(0.0, rate, 60.0), MIST_CAP as f32);
         assert!(
             accrue(0.0, rate, 3.0) < MIST_CAP as f32,
             "a 3 s stall must still be carried whole — the binary's ceiling is 3.4 s at this rate"
         );
-        // The fraction is kept across frames rather than truncated (`0x67b172` stores it back).
+        // The fraction carries across frames (`0x67b172`).
         let dt = 1.0 / 60.0;
         let (mut budget, mut spawned) = (0.0f32, 0u32);
         for _ in 0..60 {
@@ -373,11 +282,7 @@ mod tests {
         );
     }
 
-    /// The mist is the one precip rate the reference does **not** couple to the frame rate: its
-    /// accumulator carries the sub-unit remainder across frames (`0x67b172`) where the drop
-    /// kernels throw theirs away. So a second of mist is a second of mist at any frame rate —
-    /// which is why 1165's `REF_FPS_GAIN` is applied to the flake rate alone. Halving this too,
-    /// for symmetry with the flakes, would be a fresh bug wearing consistency's clothes.
+    /// The reason `REF_FPS_GAIN` scales the drop rate alone.
     #[test]
     fn mist_throughput_does_not_move_with_the_frame_rate() {
         let rate = 2.0 * (1.0 - 0.5) * 1.0 * MIST_Q_SNOW;
@@ -397,9 +302,6 @@ mod tests {
         assert_eq!(over_a_second(144), 48);
     }
 
-    /// Rain and snow read **different** `Q` constants, and the pair is per leg. Pinned because
-    /// benilla shared rain's for as long as the constant was a single value, which ran snow's
-    /// mist at 38/48 = 0.79× — a defect no test could see while the number had nowhere to differ.
     #[test]
     fn snow_and_rain_mist_gains_are_separate_constants() {
         assert!(
@@ -410,16 +312,12 @@ mod tests {
             (MIST_Q_SNOW - 48.0).abs() < 1e-6,
             "snow shader Q = 0x80ffd8"
         );
-        // The knee and the doubling are shared; only Q splits, so the rates split in the same
-        // ratio at every density above the 0.5 knee.
+        // Only `Q` splits: the knee and the doubling are shared.
         let at = |q: f32, d: f32| 2.0 * (d - 0.5f32).max(0.0) * q;
         assert!((at(MIST_Q_SNOW, 1.0) / at(MIST_Q_RAIN, 1.0) - 48.0 / 38.0).abs() < 1e-6);
         assert_eq!(at(MIST_Q_SNOW, 0.5), 0.0, "the 0.5 knee is shared");
     }
 
-    /// The slope-validity walk (`0x67a8e1–0x67a933`): flat terrain passes whole; a roof-height
-    /// jump within 3 cells of spawn stillbirths (the k=3 delta trips at m=0); farther jumps
-    /// truncate at the first group that sees them.
     #[test]
     fn slope_walk_flags_the_wall() {
         assert_eq!(first_invalid_group(&[10.0, 10.2, 10.4, 10.6, 10.8]), None);
@@ -433,8 +331,7 @@ mod tests {
             first_invalid_group(&[10.0, 10.1, 10.2, 10.3, 15.0]),
             Some(1)
         );
-        // Gentle rises inside the deltas pass — the cumulative limits (0.5/0.75/1.0 over
-        // 1/2/3 cells) mean sustained slopes must stay under ~0.33 yd per cell.
+        // Gentle rises pass: a sustained slope must stay under ~0.33 yd per cell.
         assert_eq!(first_invalid_group(&[10.0, 10.3, 10.5, 10.7, 10.9]), None);
     }
 }
diff --git a/crates/benilla-world/src/weather/precip/mod.rs b/crates/benilla-world/src/weather/precip/mod.rs
index 059fdf29..812101ee 100644
--- a/crates/benilla-world/src/weather/precip/mod.rs
+++ b/crates/benilla-world/src/weather/precip/mod.rs
@@ -1,72 +1,8 @@
-//! Precipitation — the pooled rain/snow simulation, its ground layers, and the mist companion.
-//! Spawn kinematics from wow-re's byte-exact transcriptions (`crates/lighting/src/
-//! wx_rainspawn.rs`, `wx_snowspawn.rs`, `weather_init.rs`, `wx_leaf_fp.rs`, `weather_scalars.rs`);
-//! render laws from the §5 finding `system/lighting/scratch/rf-weather-render.md` (the
-//! render-law fold-back record). Implemented idiomatically (f32 math, Bevy space) — the *laws*
-//! (constants, rates, gates, blend states) are the reference's, the x87 quirks are not.
-//!
-//! The verified structure:
-//! - **Placement** is one law for both kinds ([`pool::spawn_particle`], wow-re
-//!   `wx-snow-placement-law.md`): `pos = R·(O − T·V) + 1.75·W + C`. The scatter `O` lies on the
-//!   plane the particle *arrives* on; `−T·V` back-projects it up its own velocity; **`R` leans the
-//!   whole slab into the direction of travel** by `65°·sat(speed/18)`; then the wind lead and the
-//!   live camera eye. `R` was missing until decision 1159 and its absence IS B233's second half —
-//!   without it a particle needs its entire fall to reach eye height, which a running player
-//!   outpaces (snow at grade 0.6: 7.8 s of fall against 54 yd of running, versus a 45 yd box).
-//! - **Rain**: drops scatter across 130×130 yd, `T = −37.5/Vz` (`0x674df6–e53`;
-//!   rf-weather-emission-timeline Q5 — the old "spawns AT eye height" read killed only the box's
-//!   z-RANDOM, not the constant lift, and made density camera-angle-dependent). Each drop dies
-//!   at the **terrain** under its spawn column and leaves a 0.25 s *patter* splash **1:1** (calm
-//!   wind only). Streaks draw as fixed-size comet-tail TRIANGLES (0.1 wide × 2.0 long) with
-//!   **no vertex colour** — the look is `RainDrop01.blp` (authored grey-128-neutral) under
-//!   **Mod2x** (`2·src·dst`) and a **forced grey fog** over 70..75 yd that IS the distance fade.
-//! - **Snow**: same rails, 90×90 box, slab lift +30, slow wandering kinematics — but a
-//!   completely different DRAW. The leg that runs is the ARB **point sprite** `0x678610`
-//!   (`glDrawArrays(GL_POINTS)`, `snowpoint.bls`), so a flake is sized in **pixels**,
-//!   `max(1, 14·clamp01(1 − 0.02·d))` — denominated in the ERA's screen height so the angle, not
-//!   the pixel count, carries to a modern display ([`SNOW_PX_REF_HEIGHT`], decision 1162) — with
-//!   alpha `clamp01(t − f1)` falling (a 1 s fade-in) and
-//!   `clamp01(1 − 4·(t − f2))` settled. Blend mode 2 (SrcAlpha, 1−SrcAlpha), fog OFF,
-//!   depth-write off, RGB white. The `1/12` world-space triangle of `0x678960` is the
-//!   fixed-function FALLBACK and never runs on real hardware — benilla drew it (as a *quad*,
-//!   times an invented size jitter) while taking the shader leg's population, which is B233's
-//!   "flakes seem too big" (decision 1149; wow-re `rf-snow-flake-render.md`).
-//! - **Mist**: every precip type carries a companion mist — its own object in the reference
-//!   (ctor `0x67a5b0`, spawn `0x67a990`, render `0x67ae20`); the law lives in [`mist`].
-//! - Ground heights come from a **lazy height cache** of the reference's weather ground
-//!   oracle (`0x67c760 → mgr+0x34 → 0x6b7070`): **WMO/doodad-AWARE** (round 3 Q-B, refuting
-//!   the round-2 "terrain-only" read) — after the terrain sample it probes the chunk's static
-//!   object refs and MAXes the hit (`CMapObj::IntersectSegment 0x6a37b0`, `0x6b7237–4a`), so
-//!   drops **land on roofs**: splashes on the inn roof, never inside, from any camera.
-//!   Independently, "no weather indoors" is the global weather-visible flag (`[0xca80c4]`) —
-//!   it kills the DRAW alone (`0x677380`/`0x6790b0`/`0x67a520`; simulation always runs — round-6
-//!   Q-H(b)); force-set with the camera outdoors (`0x6811d4`), and set from inside whenever an
-//!   exterior group survives the view-clipped portal-window pass (`0x6b42d9`) — rain shows
-//!   through a doorway the camera can SEE. See [`gate_weather_indoors`].
-//! - **Drift heading is WORLD-FIXED**: both spawn kernels centre the per-drop horizontal drift
-//!   on the constant azimuth −1.57 rad (`0x80ffbc`, R3/R3a) with a grade-scaled spread. The
-//!   **wind** — the local PLAYER's trailing-149-ms average velocity (`0x67c150`, a true yd/s
-//!   vector; the camera orbiting does not stir it) — enters ONLY through the spawn-box lead
-//!   (×1.75) and the streak APEX tilt (`lerp(0°, 45°, sat(|wind|/30))`, verified DOWNWIND) —
-//!   never the drift heading. (R10's spawn-plane tilt keys on the zone-ambient wind, which
-//!   benilla doesn't model yet; the patter gate keys on ridden-transport velocity — no gate on
-//!   foot.)
-//!
-//! - **The packet pipeline** (rf-weather-emission-timeline, rounds 2–3): drops are RECORDED
-//!   into an open packet, which renders NOTHING until it seals (shader legs draw only the
-//!   close-baked buffer) and its `baseTime = open + 6144/rate` stamp passes — a delay line
-//!   that hides an upswing's sparse early drizzle (first visible rain stochastic, mostly
-//!   ~8.5–14 s, AFTER the fog and mist) and lets committed rain persist through a same-type
-//!   clear-down. A wire TYPE change instead cuts: emission stops at once and the unreplayed
-//!   pipeline is discarded (`pool::Pool::cut`). A packet is also **retired outright** once its
-//!   open-time camera anchor falls further than [`RETIRE_DIST`] from the live eye
-//!   (`pool::Pool::retire_far`) — the teleport guard, which is why a `.go` no longer strands the
-//!   field at the position you left. See `pool` and [`SHADER_LEG`].
-//!
-//! Geometry is pushed per frame from the live pools onto the shared effect stream (0733):
-//! rain's Mod2x blend + forced fog are the lane's `EffectBlend::Mod2x` + `EffectFog::Rain`
-//! variants; snow and mist ride the Alpha/fog-off rows. Idle pools push nothing — the
-//! structural replacement for the old fixed-capacity meshes' write gate (the 0353 fps hunt).
+//! Precipitation: the pooled rain and snow simulation, its ground layers and the mist companion,
+//! drawn on the shared effect stream. The laws (constants, rates, gates, blend states) are the
+//! reference's, in f32 and Bevy space. Drops pass through a packet delay line, so an upswing's
+//! first rain shows at ~5 s or 8.5–14 s, after the fog and mist, and outlasts a same-type
+//! clear-down.
 
 use bevy::prelude::*;
 
@@ -92,91 +28,27 @@ use pool::{run_kind, HeightCache, Pool};
 use render::{push_flakes, push_patters, push_streaks, FlakeView};
 pub(crate) use wind::{wow_azimuth_to_bevy, WeatherWind};
 
-// ===== The reference's constants (byte-cited; render laws from wow-re rf-weather-render.md,
-// spawn kinematics from the wx_* transcriptions, packet pipeline from
-// rf-weather-emission-timeline) =====
+// ===== The reference's constants =====
 
-/// Which weather **leg** we run — the reference picks per the `useWeatherShaders` CVar
-/// (default "1", registered `0x67b81d`) AND a rain.bls/patter.bls ARB validation (`0x58b360`);
-/// the verdict lands in `effect+0`. **SHADER — settled in round 3** (2272, retracting 0332's
-/// fixed-func inference): the shader leg's ~10 s onset is real — close-only packet visibility
-/// (`0x6752b0` bakes at flush alone), the packet-1 forecast orphan, and the RNE parity stick
-/// (`0x6754cc`) stack into a stochastic onset (~75% in the 8.5–14 s band, ~25% at ~5 s), and
-/// only the shader populations (rain 35000, patters CAP-saturated) reproduce the director's
-/// observed density. LIVE-CAPTURE flag: repeated reference upswings should OCCASIONALLY show
-/// a ~5 s onset; an always-10 s reference means an unfound parity bias.
+/// The weather leg: the reference runs the shader leg unless `useWeatherShaders` (default 1,
+/// `0x67b81d`) is 0 or its ARB programs fail to validate (`0x58b360`); this always runs it.
 const SHADER_LEG: bool = true;
-/// Per-packet record capacity — `0x1800` = 6144 (`0x80ffc8` as float; the open stamp divides it
-/// by the live rate). NOT a live cap: packets form a growing list (`effect+0x8c`, TSList at
-/// `effect+0x70`), so the steady population is demand-bounded (`rate · fall_time`).
+/// Per-packet record capacity, 6144 (`0x80ffc8` as a float, which the open stamp divides by the
+/// rate). Not a population cap: packets form a growing list, so demand bounds the population.
 const PACKET_CAP: usize = 0x1800;
-/// **The anchor cull** — retirement condition 3 of the active-list walk (`0x677ff0`, tested
-/// `0x6780d3`–`0x678110` against `[0x810008]` = 200.0): a packet whose OPEN-time camera anchor is
-/// now further than this from the live eye is **discarded outright** — it leaves the render list
-/// the same frame and is not allowed to finish replaying.
-///
-/// The anchor (`pkt+0x3001c`) is written once, in the allocation block (`0x678598`), from that
-/// update's camera snapshot `0xc7cf20`, and its only readers image-wide are the three `fsub`s of
-/// this test; the comparison is **3-D**, not planar (`0x4549f0` sums all three squares,
-/// `0x678103 fsqrt`).
-///
-/// **This is a teleport / zone-change guard, not a motion mechanism**, and the arithmetic says so:
-/// a packet lives at most `close_age + fall_time` (snow ≈ 2.3 + 7.5 ≈ 10 s), so even an epic mount
-/// at ~14 yd/s carries the eye only ~140 yd from a live anchor. Nothing but a discontinuity trips
-/// it. See [`RETIRE_DROP_SLACK`] for how it reaches benilla's already-activated drops.
+/// The anchor cull, retirement condition 3 of the active-list walk (`0x677ff0`; `0x6780d3`–
+/// `0x678110` against `0x810008` = 200): a packet whose open-time anchor is farther than this
+/// from the eye, in 3-D (`0x4549f0`), is discarded outright. Only a teleport can trip it.
 const RETIRE_DIST: f32 = 200.0;
-/// Slack added to [`RETIRE_DIST`] for the **active-drop** half of the cull.
-///
-/// benilla splits what the reference keeps together: a flake lives in its packet's static buffer
-/// for the packet's whole life, so retiring the packet un-draws it, whereas here a record that
-/// replays becomes a free-standing [`pool::Drop`] with no packet identity left to test. The
-/// available proxy is the drop's own distance, and the honest way to use it is to make it
-/// **strictly weaker** than the reference's rule, so it can never retire a particle the reference
-/// would still be drawing:
-///
-/// > a flake is born inside the spawn box, i.e. at most `√(2·half_xy² + z_off²)` from the
-/// > emission origin (99.3 yd rain / 70.4 yd snow — a rotation preserves length, so the slab tilt
-/// > does not widen it), and that origin is the eye plus the wind lead `1.75·W` (`W` is the
-/// > player's own averaged velocity, ≤ ~25 yd for an epic mount). So the reference never draws a
-/// > flake past `200 + 99.3 + 25 ≈ 324` yd.
-///
-/// 50 yd covers the lead and the lateral drift over a fall with room to spare, and the *cases the
-/// rule exists for* clear any such threshold by three orders of magnitude — a `.go` moves the eye
-/// thousands of yards.
+/// Slack on [`RETIRE_DIST`] for active drops, which keep no packet here and go by their own
+/// distance. The reference draws no flake past `200 + box corner + 1.75·W` (≤ ~324 yd), so this
+/// cull is strictly weaker than its own and never retires a flake it would still draw.
 const RETIRE_DROP_SLACK: f32 = 50.0;
-/// Benilla's live+pending bound per effect (the reference has none — allocator-bounded): the
-/// leg's steady demand `rate · fall_time` plus one packet of pipeline lag, with headroom.
-///
-/// **Per kind, because the two demands differ by 1.7×** and one shared number silently clipped
-/// snow. Rain falls at ~28 yd/s from +37.5, so `35000 · 1.34 s ≈ 47k`; snow *sinks* at 5.5–6.5
-/// from +30, so `14000 · ~5.5 s ≈ 76k` — against the old shared `0xC000` = 49152 the snow field
-/// saturated, emission stalled at the bound, and the sky held ~64% of the reference's flakes.
-/// The vertex cost is the reason to keep these tight: the reference draws one *point* per flake
-/// (`glDrawArrays(GL_POINTS)`, 32 B), while benilla's shared effect stream draws a quad, so every
-/// flake costs 4 vertices here.
-///
-/// **`fall_time` is TERRAIN, not a constant — which is what the `0x18000` sizing missed.** A drop
-/// lives until the ground under it, so the demand scales with how far the ground falls away below
-/// the spawn plane, and that is a property of where the player is standing. Measured live (the
-/// 1 Hz field census, grade 1.0): Kharanos' bowl gives a mean fall of **29.6 yd** and a steady
-/// ~69k, while open ground 210 yd west gives **44.5 yd** and an unclipped demand of
-/// `14000 · 44.5/6.0 ≈ 104k` live plus a packet — past `0x18000` = 98304, so emission throttled
-/// and the field ran ~11% thin. Sized here off that measured worst case with headroom.
-///
-/// **Those demand figures predate 1165's halving** and are kept because they are what was
-/// measured. Re-measured after it (1166's probe, two Dun Morogh pins at effect density 0.60):
-/// **32.4k and 38.3k live** plus one full packet. Demand is *sub*-linear in density — a denser
-/// flake also falls faster ([`SNOW_VZ_W`]), so it lives less long — which puts grade 1.0 at
-/// ~48k + 6k, i.e. the snow bound now sits ~2.4× above its worst case. Deliberately not retuned:
-/// this is a **ceiling, not a reservation** (`pool_bound` is a spawn cap and [`POOL`] a `take(…)`
-/// guard; nothing here preallocates, the pools grow to live demand), so slack costs nothing, and
-/// it is right again the moment [`REF_MAXFPS`] is turned back to the byte-faithful 60.
-///
-/// **The tell that this bound is biting is `pending_len()` falling below [`PACKET_CAP`]**: the
-/// pipeline holds exactly one full packet whenever emission is unthrottled (measured 6110–6150 at
-/// both grades and both sites), so a census line reporting a *suppressed* pipe count is the clip,
-/// and the visible field is thinner than the law asks for. Read it that way before concluding
-/// anything about density from a `live` count.
+/// Deviation: a spawn ceiling on live plus pending drops, which the reference lacks, because each
+/// flake here costs a 4-vertex quad. Demand is `rate · fall_time` plus a packet, and the fall
+/// depends on the ground under the spawn plane, so this sits above the worst case measured at
+/// the ungained rate; nothing is preallocated. It bites when the state log's pipe count falls
+/// below [`PACKET_CAP`].
 const fn pool_bound(kind: WeatherKind) -> usize {
     match kind {
         WeatherKind::Snow => {
@@ -195,168 +67,90 @@ const fn pool_bound(kind: WeatherKind) -> usize {
         }
     }
 }
-/// The largest pool bound — the `take(…)` guard on a push, where the kind is already implied by
-/// which pool is being drawn.
+/// The largest pool bound, the `take(…)` guard on a push.
 const POOL: usize = pool_bound(WeatherKind::Snow);
-// Density gain `K` (`rate = K·P·grade` per second) is the live `weatherDensity` setting's table
-// entry — `WeatherState::density_gain()` (`0x67b870`: 0.1/0.33/0.66/1.0 for setting 0–3). The
-// transcriptions carried quality 2's 0.66 as a baked constant; the reference runs at 3 (K=1.0).
-/// Rain population `P` — fixed-func `0x80ffa8` = 6500, shader `0x80ffac` = 35000. (The old
-/// `_DAY/_NIGHT` labels were a misread; `effect+0` is the leg flag — see [`SHADER_LEG`].)
+// The density gain `K` in `rate = K·P·grade` is `WeatherState::density_gain()`, the
+// `weatherDensity` table (`0x67b870`: 0.1, 0.33, 0.66, 1.0 for settings 0 to 3).
+/// Rain population `P`: fixed-function `0x80ffa8` = 6500, shader `0x80ffac` = 35000.
 const RAIN_P: f32 = if SHADER_LEG { 35000.0 } else { 6500.0 };
-/// Snow population `P` — fixed-func `0x80ffdc` = 1300, shader `0x80ffe0` = 14000.
+/// Snow population `P`: fixed-function `0x80ffdc` = 1300, shader `0x80ffe0` = 14000.
 const SNOW_P: f32 = if SHADER_LEG { 14000.0 } else { 1300.0 };
-/// The frame cap the **reference install** runs at — `SET maxfps "30"` in its `Config.wtf`.
-///
-/// **This is a LOOK constant, not a byte-cited one** (the same species as [`SNOW_PX_REF_HEIGHT`],
-/// and it is here for the same reason). Do not "correct" it to 60 for fidelity: 60 *is* the
-/// byte-faithful value and it is what shipped before 1165.
-///
-/// The reference's per-frame budget is `min(dt, 1/60)·rate` with the remainder **discarded**
-/// (`0x67846f`–`0x678480`), so emission per second is `rate · min(1, fps/60)` — a client below
-/// 60 fps gets proportionally less precipitation. The trace measured the reference emitting
-/// exactly 233 flakes per frame, pinning `rate` to 14000/s nominal; at its own 30 fps cap that is
-/// **6990/s on screen, half of nominal**. benilla at 60+ fps runs the full 14000/s and reads twice
-/// as dense against the director's A/B with every constant identical on both sides.
-///
-/// So the number that needed denominating was the **frame rate the look was observed at**, exactly
-/// as 1162's `14` needed the screen height it was authored against. A quantity whose unit is
-/// "per frame" is denominated in a frame rate, and porting it forward means porting the
-/// denominator (1162 §2).
+/// Deviation: the drop rate is scaled to a 30 fps client, the frame rate the reference's look
+/// was matched at, because the reference budgets `min(dt, 1/60)·rate` and drops the remainder
+/// (`0x67846f`–`0x678480`), so it emits half its nominal rate at 30 fps. 60 is byte-faithful.
 const REF_MAXFPS: f32 = 30.0;
-/// [`REF_MAXFPS`] as a gain on the spawn rate: `min(1, REF_MAXFPS/60)`.
-///
-/// Applied to the **drop/flake** rate only, never to the mist. The drop kernels throw their
-/// sub-unit remainder away every frame, which is what couples them to the frame rate; the mist
-/// accumulator carries its leftover across frames (`0x67b172`, wow-re rounds 3–4) and is the one
-/// precip rate in the reference that is *already* frame-rate independent. Halving it too would be
-/// a second, unrelated error dressed as consistency.
+/// [`REF_MAXFPS`] as a gain on the drop rate. Never on the mist: its accumulator carries its
+/// remainder (`0x67b172`), so it is already frame-rate independent in the reference.
 const REF_FPS_GAIN: f32 = if REF_MAXFPS < 60.0 {
     REF_MAXFPS / 60.0
 } else {
     1.0
 };
-/// A patter lives 0.25 s (`patter_record_init 0x675280`: `lifetime = now + 0.25`).
+/// A patter lives 0.25 s (`0x675280`: `lifetime = now + 0.25`).
 const PATTER_LIFE: f32 = 0.25;
-/// Per-frame spawn budget uses `min(dt, 1/60)` (`wx_leaf_fp.rs::update_dt_accum 0x80ffcc`).
+/// Per-frame spawn budget uses `min(dt, 1/60)` (`0x80ffcc`).
 const DT_CAP: f32 = 1.0 / 60.0;
-/// The spawn box leads the camera by `wind_motion · 1.75` (the spawn kernels' R11, `0x8680f8`).
+/// The spawn box leads the camera by `1.75·wind` (`0x8680f8`).
 const WIND_LEAD: f32 = 1.75;
-/// The drift heading CENTRE — the bit-cited constant −1.57 rad (`0x80ffbc`, rain R3 / snow R3a):
-/// a **fixed WORLD azimuth** in the WoW frame, shared by rain and snow. The 0311-era code steered
-/// the drift by the live wind heading (falling back to 0 when calm) — the director's "rain
-/// direction seems different": calm-camera rain leaned toward an arbitrary Bevy axis instead of
-/// the reference's world-anchored one.
+/// The drift heading's centre, −1.57 rad (`0x80ffbc`): a fixed world azimuth in the WoW frame
+/// for rain and snow, never the wind's heading.
 const DRIFT_AZ_CENTER: f32 = -1.57;
-/// Rain fall speed: `vz = −28 − 4w − 2w·r` (`wx_rainspawn.rs` R6: 28.0/4.0/−2.0 bit-cited).
+/// Rain fall speed `vz = −28 − 4w − 2w·r` (`0x80306c`, `0x80ffb4`).
 const RAIN_VZ_BASE: f32 = 28.0;
 const RAIN_VZ_W: f32 = 4.0;
 const RAIN_VZ_RNG: f32 = 2.0;
-/// Rain horizontal drift: `((2r−1) + 9.49)·w + 0.01` (R4), heading spread `w·0.209 + 0.052` rad
-/// (R3) about the wind heading.
+/// Rain drift speed `((2r − 1) + 9.49)·w + 0.01`, heading spread `0.209·w + 0.052` rad.
 const RAIN_DRIFT_BASE: f32 = 9.49;
 const RAIN_DRIFT_EPS: f32 = 0.01;
 const RAIN_SPREAD_W: f32 = f32::from_bits(0x3e56_7750); // 0x80ffc4 ≈ 0.20944 (12°)
 const RAIN_SPREAD_BIAS: f32 = f32::from_bits(0x3d56_7750); // 0x80ffc0 ≈ 0.05236 (3°)
-/// The streak triangle (rf-weather-render Q1): base verts `head ∓ 0.05·RIGHT` (`0x80ff78`),
-/// apex `head + tilt·(2.0·antiVel̂)` (`0x80ff74`) — FIXED world-space sizes, not |vel|-scaled.
-/// No vertex colour/alpha; the look is the texture under Mod2x + the forced fog.
+/// The streak triangle: base `head ∓ 0.05·right` (`0x80ff78`), apex `head + tilt·(2·antiVel̂)`
+/// (`0x80ff74`), fixed world sizes, not scaled by speed; no vertex colour.
 const STREAK_HALF_W: f32 = 0.05;
 const STREAK_TAIL: f32 = 2.0;
-/// Rain's forced fog window (render-state 0x0a/0x0b, CPU leg): start 70, end 75 — under Mod2x
-/// the grey-0.5 fog colour is NEUTRAL, so this IS the streak distance fade. `pub(crate)`: the
-/// effect lane's canonical `EffectFog::Rain` params row is written from these (0733 §4).
+/// Rain's forced fog window (render states 0x0a/0x0b): under Mod2x its grey-0.5 colour is
+/// neutral, so this is the streak distance fade. `EffectFog::Rain`'s row is written from these.
 pub(crate) const RAIN_FOG_START: f32 = 70.0;
 pub(crate) const RAIN_FOG_END: f32 = 75.0;
-/// Patter triangle half-edges: `view_right/12` × `view_up/6` (`0x80e004`/`0x803568`, CONFIRMED).
+/// Patter triangle half-edges: `view_right/12` and `view_up/6` (`0x80e004`, `0x803568`).
 const PATTER_RIGHT: f32 = 1.0 / 12.0;
 const PATTER_UP: f32 = 1.0 / 6.0;
-/// Spawn-box horizontal half-extents (driver `0x67be40` ctor args): rain 130×130 (`0x43020000`),
-/// snow 90×90 (`0x42b40000`).
+/// Spawn-box horizontal half-extents, from the ctor args (`0x67be40`): rain 130×130
+/// (`0x43020000`), snow 90×90 (`0x42b40000`).
 const RAIN_HALF_XY: f32 = 65.0;
 const SNOW_HALF_XY: f32 = 45.0;
-/// The slab's lift in **slab-local** space — HALF the ctor vertical extent (rain 75 → +37.5,
-/// snow 60 → +30). Q5-CORRECTED (wow-re rf-weather-emission-timeline): the box's z-RANDOM is
-/// dead (`·0.0`) but the constant lift is not — `0x674df6–e53` builds `T = −37.5/Vz` and seeds
-/// `local.z = −T·Vz = +37.5`, back-projecting the drop so its trajectory passes the arrival-plane
-/// scatter point at t = T. The earlier "spawns AT eye height" read (rf-weather-render Q4) was
-/// the bug behind camera-angle-dependent density, the precip-free view above the horizon, and
-/// uphill terrain getting no rain (director-caught, 2026-07-12).
-///
-/// **It is not a world height.** The slab tilt rotates the local offset, so the realised spawn
-/// heights fan out to `z_off·cos α ∓ half_xy·sin α` — ~8..46 yd for snow at a 7 yd/s run, and the
-/// leading edge dips *below* the eye entirely past ~13 yd/s. Reading this as "the plane the
-/// particles are born on" is what made the untilted model look self-consistent (decision 1159).
+/// The slab's lift in slab-local space, half the ctor's vertical extent (rain 75, snow 60): the
+/// box's vertical random is dead but this lift is not (`0x674df6`, `T = −37.5/Vz`). Not a world
+/// height: the tilt fans spawn heights to `z_off·cos α ∓ half_xy·sin α`.
 const RAIN_Z_OFF: f32 = 37.5;
 const SNOW_Z_OFF: f32 = 30.0;
-/// Snow fall speed: `vz = −2 − 3.5m − m·r` (`wx_snowspawn.rs` R3c: 2.0/3.5 bit-cited) — calm
-/// flakes sink at 2 yd/s, a full blizzard at up to 6.5.
+/// Snow fall speed `vz = −2 − 3.5m − m·r` (`0x6778bc`–`0x6778ec`), 2 to 6.5 yd/s.
 const SNOW_VZ_BASE: f32 = 2.0;
 const SNOW_VZ_W: f32 = 3.5;
-/// Snow horizontal drift: `((r − 0.5) + 5.985)·m + 0.015` (R3b: 5.985/0.015 bit-cited).
+/// Snow horizontal drift `((r − 0.5) + 5.985)·m + 0.015`.
 const SNOW_DRIFT_OFF: f32 = 5.985;
 const SNOW_DRIFT_EPS: f32 = 0.015;
-/// Snow heading spread: `2π − 5.934·m` (R3a, `0x80fff4`) — calm snow wanders in ANY direction,
-/// a blizzard's flakes align to ±10° of the wind.
+/// Snow heading spread `2π − 5.934·m` (`0x80fff4`): any direction calm, ±10° in a blizzard.
 const SNOW_SPREAD_W: f32 = f32::from_bits(0x40bd_e44f); // ≈ 5.9341197
-/// Snow flake size — **`snowpoint.bls`'s point-size law, in WINDOW PIXELS** (wow-re
-/// `rf-snow-flake-render.md` §2.4, read at the shipped shader's bytes):
-///
-/// ```text
-/// pointsize(d) = max(1.0, 14.0 · clamp01(1 − 0.02·d))   pixels, d = |flake − eye| in yards
-/// ```
-///
-/// The snow leg that RUNS is `0x678610`, the ARB **point-sprite** pass
-/// (`glDrawArrays(GL_POINTS)`, one vertex per flake, `GL_COORD_REPLACE` texcoords,
-/// `GL_VERTEX_PROGRAM_POINT_SIZE_ARB`); `0x678960`'s 1/12 world-space triangle is the
-/// fixed-function fallback, dead on any GPU since ~2002 (ctor `0x677420` clears the leg flag only
-/// when `snowpoint.bls` fails to compile, `GL_ARB_point_sprite` is missing, or
-/// `useWeatherShaders` is 0). benilla drew the *fallback's* geometry while taking the *shader*
-/// leg's population — the two mutually exclusive sides of `0x6790c1` — and inflated it further
-/// with an invented per-flake size jitter; that pairing is what made the flakes read as far too
-/// big (B233, decision 1149).
-///
-/// **This is not a world size, and it is not `∝ 1/d`.** A flake 1 yd away is 14 px and one 30 yd
-/// away is 5.6 px — near flakes far smaller, and distant flakes far larger, than any fixed
-/// world-space quad. wgpu has no point-sprite size (WebGPU pins `PointList` at 1 px), so
-/// [`render::push_flakes`] reproduces the law by inverting the projection: a quad of world
-/// half-extent `px · z_view · tan(fovY/2) / viewport_height_px` covers exactly `px` pixels.
+/// Snow flake size in pixels, `snowpoint.bls`'s `max(1, 14·clamp01(1 − 0.02·d))`, `d` in yards:
+/// not a world size, not `1/d`. The point-sprite pass `0x678610` runs; `0x678960`'s 1/12
+/// triangle is the fallback, taken only when `snowpoint.bls` fails, `GL_ARB_point_sprite` is
+/// missing or `useWeatherShaders` is 0 (`0x677420`).
 const SNOW_PX_AT_EYE: f32 = 14.0;
-/// The screen height those pixels were authored against — **the resolution the size law is
-/// implicitly denominated in**, and the one term that has to be ours rather than the reference's.
-///
-/// `snowpoint.bls` sizes a flake in *framebuffer pixels*, so its **angular** size is
-/// `14 / framebuffer_height`. That was never a choice about looks — it is simply how
-/// `GL_VERTEX_PROGRAM_POINT_SIZE_ARB` works — and on 2004 hardware the framebuffer *was* the
-/// screen. Obey the number literally on a modern display and the flakes shrink in proportion to
-/// how good the monitor is: at the reference install's own `gxResolution 1280x800` a near flake
-/// spans `14/800` = **1.75%** of frame height, while benilla on a scale-factor-2 4K panel
-/// (physical ≈ 2144 tall) spans `14/2144` = **0.65%** — **2.7× smaller**, from resolution alone.
-/// That is B233's "the size of the snow is way too small" (director A/B, decision 1162), and it is
-/// the same failure mode `lib.rs` already records for FFXGlow's texel-pinned blur geometry.
-///
-/// So the law is evaluated in **era pixels** and converted to an angle, which makes the sprite
-/// resolution-independent: the live viewport height cancels out of
-/// `px · z · tan(fovY/2) / height` entirely. At an 800-px-tall window benilla draws exactly the
-/// reference's 14 physical pixels; at 4K it draws 37 physical pixels covering the same angle.
-///
-/// **This is the number to turn if the flakes still read wrong.** It is a look constant, not a
-/// byte-cited one — 800 is this install's `Config.wtf`, i.e. the resolution the director's own
-/// side-by-side was captured at. A different era resolution is a different (equally faithful)
-/// look: 640×480 would make them 1.67× bigger again.
+/// Deviation: flake pixels are pixels of an 800-px-tall screen, the height the look was matched
+/// at, converted to an angle, because the reference's literal framebuffer pixels shrink with
+/// resolution (2.7× smaller at 4K scale 2). At 800 px tall the reference's pixels are exact.
 const SNOW_PX_REF_HEIGHT: f32 = 800.0;
 /// The falloff slope: `1 − 0.02·d` reaches the 1 px floor at `d = 13/0.28 ≈ 46.4` yd.
 const SNOW_PX_FALLOFF: f32 = 0.02;
-/// `max(1.0, …)` — the floor the ARB program applies last.
+/// The 1 px floor the ARB program applies last.
 const SNOW_PX_MIN: f32 = 1.0;
-/// A settled flake fades over 0.25 s (`snow_patter_value`: `max(t,0) + 0.25`).
+/// A settled flake fades over 0.25 s (`0x678dfa`, constant `0x8029b0`: `max(t,0) + 0.25`).
 const SNOW_SETTLE_LIFE: f32 = 0.25;
-/// A FALLING flake fades **in** over its first second — the vertex program's
-/// `alpha = clamp01(t − f1)` (rf-snow-flake-render §2.4). benilla drew every falling flake at
-/// alpha 1.0, so the top of the column was a hard-edged sheet instead of a soft one.
+/// A falling flake fades in over its first second, the vertex program's `clamp01(t − f1)`.
 const SNOW_FADE_IN: f32 = 1.0;
 
-/// The precipitation state: per-kind pools + the mist companion + the shared xorshift RNG.
+/// The precipitation state: the per-kind pools, the mist and the shared RNG.
 #[derive(Resource)]
 pub(super) struct Precip {
     rain: Pool,
@@ -365,30 +159,20 @@ pub(super) struct Precip {
     rng: u32,
 }
 
-/// Is weather killed by the camera's room? The client's weather-visible flag `[0xca80c4]`
-/// inverted: cleared per frame (`0x6b38c1`), force-set with the camera outdoors (`0x6811d4`),
-/// and it gates the ENTIRE weather update+render dispatch (`0x677380`/`0x6790b0`/`0x67a520`:
-/// load, `je → ret`) — drops, patters, and mist together, with the wire state untouched. The
-/// flag's SECOND leg (recorded at `0x6b42d9`, folded 2026-07-13): with the camera in an
-/// interior it re-sets if an EXTERIOR-flagged group (`&0x148`) is portal-reachable — rain
-/// stays visible (and falling) through a doorway's frame; the reference through the inn's
-/// open door shows the storm running (director ref-shot). Only a room with no reachable
-/// outside kills the effect — there it FREEZES (drops hang, unrendered) and resumes on
-/// stepping out. Exact writer semantics are the Q-H carve (round 6); this is the recorded
-/// shape.
+/// Is weather hidden by the camera's room: the reference's weather-visible flag `[0xca80c4]`
+/// inverted, cleared per frame (`0x6b38c1`), set with the camera outdoors (`0x6811d4`) or an
+/// exterior group seen through a portal (`0x6b42d9`). The reference's dispatchers update the
+/// drops first and gate only the draw and the mist on it (`0x677380`, `0x6790b0`, `0x67a520`).
 #[derive(Resource, Default)]
 pub(super) struct WeatherIndoors(bool);
 
-/// Resolve [`WeatherIndoors`] from the camera's PVS-flood interior claim
-/// ([`CameraInteriorClaim`], written by the portal pass this frame). The flag gates both the
-/// sim ([`simulate_precip`] — the freeze) and the stream push ([`push_precip`] — frozen drops
-/// hang, unrendered, exactly the reference's `[0xca80c4]` draw kill).
+/// Resolves [`WeatherIndoors`] from the portal pass's [`CameraInteriorClaim`] this frame.
 fn gate_weather_indoors(claim: Res<CameraInteriorClaim>, mut indoors: ResMut<WeatherIndoors>) {
     indoors.0 = claim.0.is_some_and(|c| !c.exterior_visible);
 }
 
-/// xorshift32 → [0,1) — the reference's lagged-table generator is byte-known but its
-/// distribution is uniform; the mechanism needs uniformity, not that exact stream.
+/// Deviation: xorshift32 to [0, 1) instead of the reference's lagged-table generator, because
+/// the laws need only a uniform distribution, not its exact stream.
 fn rand01(rng: &mut u32) -> f32 {
     let mut x = *rng;
     x ^= x << 13;
@@ -398,12 +182,10 @@ fn rand01(rng: &mut u32) -> f32 {
     (x >> 8) as f32 / (1u32 << 24) as f32
 }
 
-/// Ground-layer capacity — the reference's patter pool is 0x1800 slots (`Packet<Patter,Rain>`),
-/// same as the drop pool; at grade 1 the 1:1 landing spawns keep ~rate·0.25 s ≈ 3–6k alive.
+/// Ground-layer capacity: the reference's patter packet holds 0x1800 (`Packet<Patter,Rain>`).
 const GROUND_CAP: usize = 0x1800;
 
-/// The four precip textures (loaded once; the stream's render-side residency gate withholds
-/// draws until they arrive).
+/// The four precip textures; the stream withholds their draws until they load.
 #[derive(Resource)]
 struct PrecipAssets {
     streak: Handle<Image>,
@@ -418,17 +200,12 @@ fn setup_precip(
     cam: Query<&GlobalTransform, With<WorldCamera>>,
     existing: Option<Res<Precip>>,
 ) {
-    // Lazy spawn on the first frame with a live camera (the same lifecycle as every other
-    // particle entity — M2 emitters spawn when terrain streams).
+    // Spawned on the first frame with a live camera.
     if existing.is_some() || cam.single().is_err() {
         return;
     }
-    // Streaks keep the authored mips (a solid bar survives minification); the splash + mist
-    // cut-outs load mip-0-only (`BlpVariant::Effect`) — they draw as world-space quads that are
-    // magnified far more often than minified, and their thin arms collapse under the mip chain.
-    // The FLAKE is the exception (`BlpVariant::PointSprite`): the reference's point sprite is
-    // 14 px at the eye and 1 px past 46 yd — a 4.5×–64× minification of a 64×64 texture, which
-    // is why the asset ships 7 mips. Mip-0-only there is flickering speckle, not crispness.
+    // Streaks keep their mips; the splash and mist cut-outs load mip 0 only, as their thin arms
+    // collapse under the chain; the flake keeps its 7 mips, drawn 4.5× to 64× minified.
     let effect = |s: &mut benilla_assets::BlpLoaderSettings| {
         s.variant = benilla_assets::BlpVariant::Effect;
     };
@@ -451,15 +228,13 @@ fn setup_precip(
     });
 }
 
-/// Per frame: wind, spawn budgets, integrate, land. (The geometry push is [`push_precip`]'s,
-/// in `PostUpdate` after the stream clear.)
+/// Per frame: wind, spawn budgets, integrate, land; [`push_precip`] draws in `PostUpdate`.
 fn simulate_precip(
     time: Res<Time>,
     weather: Res<WeatherState>,
     cam: Query<&GlobalTransform, With<WorldCamera>>,
     player: Query<&Transform, (With<crate::world_unit::ViewerUnit>, Without<WorldCamera>)>,
-    // The commanded planar speed the spawn slab's tilt keys on (`mgr+0x7c`) — live, not the
-    // wind's 149 ms average.
+    // The live commanded speed the slab tilt keys on (`mgr+0x7c`), not the averaged wind.
     viewer: Res<crate::view::Viewer>,
     spatial: SpatialQuery,
     indoors: Res<WeatherIndoors>,
@@ -467,16 +242,14 @@ fn simulate_precip(
     mut heights: ResMut<HeightCache>,
     mut precip: Option<ResMut<Precip>>,
     mut last_cut: Local<u32>,
-    // Frames since the previous census — the spawn budget scales with frame rate, so two census
-    // lines are only comparable at equal frame counts (see [`pool::census`]).
+    // Frames since the previous census line.
     mut census_frames: Local<u32>,
 ) {
     let Some(precip) = precip.as_deref_mut() else {
         return;
     };
-    // Indoors the whole effect freezes — the reference gates the update+render dispatch on
-    // `[0xca80c4]` (`je → ret`), so nothing spawns, integrates, ages, or rebuilds; the meshes
-    // are already hidden by [`gate_weather_indoors`].
+    // Indoors this freezes the whole effect, where the reference keeps simulating drops unseen
+    // and freezes only the mist.
     if indoors.0 {
         return;
     }
@@ -487,9 +260,7 @@ fn simulate_precip(
     }
     let now = time.elapsed_secs();
     let cam_pos = cam_tf.translation();
-    // The wind tracks the local PLAYER's motion (object 0x8fe) — orbiting the camera does not
-    // stir it. The camera stands in only when no player entity exists (captures, data-less), and
-    // then its own forward is the heading's sub-1-yd/s source.
+    // The wind tracks the player, not the camera; the camera stands in only when there is none.
     let (wind_pos, facing) = player
         .single()
         .map_or((cam_pos, cam_tf.forward().as_vec3()), |t| {
@@ -506,9 +277,7 @@ fn simulate_precip(
         ..
     } = precip;
 
-    // The Q-D type-change cut: a wire TYPE change (fine included) stops emission at once and
-    // discards the not-yet-replaying pipeline; playing cohorts and falling drops finish. The
-    // mist's scheduled-but-unborn nodes retire with it (`0x67b234`, round 7).
+    // A wire type change (fine included) stops emission (`0x67585d`) and cuts the pipeline.
     if weather.cut_seq != *last_cut {
         *last_cut = weather.cut_seq;
         rain.cut(now);
@@ -543,9 +312,7 @@ fn simulate_precip(
         cam_pos,
     );
 
-    // Throttled 1 Hz state log — the capture/live diagnosis instrument (debug builds only
-    // chatter when something is falling or queued in the packet pipeline). Second-resolution
-    // deliberately: the pipeline's visible-onset instant is what look-checks time against.
+    // The 1 Hz state log, while there is weather or anything left in the pools.
     *census_frames += 1;
     if (weather.effect_density > 0.0
         || !rain.drops.is_empty()
@@ -564,17 +331,13 @@ fn simulate_precip(
             snow.patters.len(),
             weather.effect_density,
         );
-        // …and WHERE those drops are relative to the player, which the counts cannot say. The
-        // split axis is the player's heading while they move and their view heading while they
-        // stand, so the standing reading is the ~50/50 baseline the moving one is read against.
+        // Where the drops are: split along the motion heading, or the view heading when standing.
         let motion = wind.vel.with_y(0.0);
         let axis = motion
             .try_normalize()
             .or_else(|| cam_tf.forward().as_vec3().with_y(0.0).try_normalize())
             .unwrap_or(Vec3::Z);
-        // …and, for the vertical question the horizontal census cannot answer, WHERE the field
-        // stops overhead and how sharply it gets there (the director's "hard line" report).
-        // Rain passes fade-in 0: its streaks carry no vertex alpha, so every drop weighs 1.
+        // And where the field stops overhead; rain's streaks carry no vertex alpha, so fade-in 0.
         for (name, pool, fade_in) in [("rain", &*rain, 0.0), ("snow", &*snow, SNOW_FADE_IN)] {
             if let Some(c) = census(&pool.drops, cam_pos, axis, motion.length(), *census_frames) {
                 debug!("weather field ({name}): {c}");
@@ -586,7 +349,7 @@ fn simulate_precip(
         *census_frames = 0;
     }
 
-    // ===== the mist companion (rf-weather-render Q6) =====
+    // ===== the mist companion =====
     {
         let Precip { mist, rng, .. } = precip;
         run_mist(
@@ -603,13 +366,10 @@ fn simulate_precip(
     }
 }
 
-/// Push the frame's precip geometry onto the shared effect stream (PostUpdate, after the
-/// stream clear): rain streaks + patters as Mod2x tri-lists under the forced grey fog (their
-/// textures are authored grey-128-neutral — checked: both backgrounds mean exactly RGB 128);
-/// snow and mist as alpha-blended quads with fog off (rf-weather-render Q3). All four draws
-/// anchor at the camera — view-z ≈ 0 sorts them after every world transparent, before the
-/// biased glare/nameplate rungs, exactly where the old camera-anchored layer entities landed.
-/// Indoors nothing is pushed — the frozen drops hang, unrendered (`[0xca80c4]`'s draw kill).
+/// Pushes the frame's precip onto the effect stream after its clear: rain as Mod2x triangles
+/// under the forced grey fog (both textures' grounds are exactly RGB 128), snow and mist as
+/// alpha quads with fog off (`0x678610`, `0x67ae20`). Anchored at the camera, they sort after
+/// every world transparent and before the biased glare and nameplate rungs.
 fn push_precip(
     precip: Option<Res<Precip>>,
     assets: Option<Res<PrecipAssets>>,
@@ -631,10 +391,7 @@ fn push_precip(
     let cam_pos = cam_tf.translation();
     let cam_right = cam_tf.right().as_vec3();
     let cam_up = cam_tf.up().as_vec3();
-    // Snow's size law is in ERA PIXELS (`snowpoint.bls` sizes in framebuffer pixels; benilla
-    // denominates them in the era's screen height so the *angle* carries over — see
-    // [`SNOW_PX_REF_HEIGHT`]). The live viewport is still required, but only as the "is this camera
-    // actually drawing?" gate: a camera with no sized target draws nothing this frame anyway.
+    // The live viewport only gates whether this camera draws: flakes are sized in era pixels.
     let flake_view = camera
         .physical_viewport_size()
         .filter(|vp| vp.y > 0)
@@ -645,8 +402,7 @@ fn push_precip(
             up: cam_up,
             world_per_px: match proj {
                 Projection::Perspective(p) => (p.fov * 0.5).tan(),
-                // An orthographic world camera has no perspective divide; the reference has no
-                // such mode, so there is nothing to be faithful to — keep the sprites sane.
+                // The reference has no orthographic mode; this keeps the sprites sane.
                 _ => (crate::view::CAM_FOVY * 0.5).tan(),
             } / SNOW_PX_REF_HEIGHT,
         });
@@ -655,15 +411,13 @@ fn push_precip(
         texture: texture.id(),
         blend,
         fog,
-        // Rain/snow ride the reference's own weather render state (its verified Mod2x /
-        // forced-grey-fog trio), not the M2 batch state producer — no GL_LIGHTING on them.
+        // The weather's own render state, not the M2 batch state: unlit.
         lighting: crate::particles::buffer::EffectLighting::None,
         anchor: cam_pos,
         bias: 0.0,
         raster_bias: 0,
         raster_slope: 0.0,
-        // Streaks, patters and mist are all centimetre-scale or bigger, so absolute world verts
-        // cost them nothing; the flake draw below overrides this (its quads are millimetres).
+        // Absolute verts suit centimetre-scale geometry; the flakes override this.
         cam_relative: false,
         no_depth_test: false,
         main_entity: Entity::PLACEHOLDER,
@@ -693,8 +447,7 @@ fn push_precip(
         quads.commit_quads(
             start,
             EffectDrawSpec {
-                // [`push_flakes`] wrote camera-relative offsets — the only family in the lane
-                // whose geometry is small enough for absolute-world f32 to lose it.
+                // `push_flakes` wrote camera-relative offsets: its millimetre quads need them.
                 cam_relative: true,
                 ..spec(&assets.flake, EffectBlend::Alpha, EffectFog::Off)
             },
diff --git a/crates/benilla-world/src/weather/precip/pool.rs b/crates/benilla-world/src/weather/precip/pool.rs
index 3a04b45d..7f64cace 100644
--- a/crates/benilla-world/src/weather/precip/pool.rs
+++ b/crates/benilla-world/src/weather/precip/pool.rs
@@ -1,59 +1,43 @@
-//! The precip **sim economics** — the drop/patter records, the packet delay-line, the
-//! ground oracle cache, and the per-kind frame (`run_kind`). Split from `precip`'s root;
-//! byte-cited constants stay in the root's table, ECS wiring stays in the root's systems.
+//! The precip simulation: the drop and patter records, the packet delay line, the ground height
+//! cache and the per-kind frame.
 
 use bevy::platform::collections::HashMap;
 
 use super::*;
 
-/// One falling particle. Positions/velocities are Bevy world space (y up).
+/// One falling particle, in Bevy world space (y up).
 pub(super) struct Drop {
     pub(super) pos: Vec3,
     pub(super) vel: Vec3,
-    /// Ground height (Bevy y) of the drop's CURRENT grid cell — dies (and may patter) on
-    /// reaching it. Re-sampled whenever the drop drifts into a new cell ([`Drop::cell`]): at
-    /// grade-1 rain the lateral drift is ~9.5 yd/s over a ~1.2 s fall (~11 yd), so the spawn
-    /// column's ground is the WRONG answer by up to a house — a drop seeded outside the inn's
-    /// porch drifted through the open front and splashed on the vestibule floor with the
-    /// terrain's height (director-caught, 2026-07-13). Whether the reference stores the spawn
-    /// answer or re-reads its grid per cell is open (Q-J); under a roof either reading keeps
-    /// splashes out of the room.
+    /// Ground height (Bevy y) of the drop's current grid cell, re-sampled on each new cell; the
+    /// drop dies and may patter there. The reference instead bakes the death once at birth, where
+    /// the velocity ray meets the grid (`0x675174` rain, `0x677c2f` snow, both `0x67cb60`).
     pub(super) land_y: f32,
-    /// The grid cell `land_y` was sampled for (see [`HeightCache`]).
+    /// The grid cell `land_y` was sampled for.
     pub(super) cell: (i32, i32),
-    /// Seconds since this particle became VISIBLE — the reference's `t − f1`, where `f1` is the
-    /// flake's birth stamp on its packet's clock. Snow's fade-in reads it (`rf-snow-flake-render`
-    /// §2.4); rain's streaks have no age term and ignore it. A record that replays late starts
-    /// at its own lag, exactly as `c_currentTime − f1` would.
+    /// Seconds since visible, the reference's `t − f1`; a late-replayed record starts at its lag.
     pub(super) age: f32,
 }
 
-/// A recorded drop waiting in the packet pipeline: replays at `at` (its packet's `baseTime`
-/// plus its record offset), and only once its packet has SEALED.
+/// A recorded drop: replays at `at` (`baseTime` plus its record offset) once its packet seals.
 struct Pending {
     at: f32,
     drop: Drop,
 }
 
-/// One drop packet — the reference's `Packet<Drop>` (rf-weather-emission-timeline, rounds
-/// 2–3). Records accumulate while OPEN; `baseTime` (`packet+0x36010`) is stamped ONLY at open
-/// (`0x67598c`: `baseTime = now + 6144/rate`) and the batch REPLAYS from it — a delay line
-/// (visible density = true density delayed by `6144/rate`). On shader hardware a packet draws
-/// ONLY from its static buffer, baked once at close (`0x6752b0`, sole caller = the flush
-/// `0x675a97`) — so an OPEN packet renders NOTHING: visibility needs sealed AND past its
-/// replay instant. Sparse upswing cohorts stamp far-future baseTimes and are never seen at
-/// record time (the very first packet stamps ~100 s out and genuinely ghost-replays its faint
-/// drizzle later — it passes the 60 s duration guard `[0x80ff6c]`; byte-faithful, kept).
+/// One drop packet (`Packet<Drop>`): `baseTime = now + 6144/rate`, stamped at open only
+/// (`0x67598c`), is when the batch replays. On the shader leg it draws only from a buffer baked
+/// at close (`0x6752b0`, called only from `0x675a97`). A sparse first packet stamps ~100 s out
+/// and still replays: the 60 s guard (`0x80ff6c`) bounds the replay span, not the delay.
 struct Packet {
-    /// `pkt+0x3001c` — the camera eye at OPEN, and the only thing [`RETIRE_DIST`] is measured
-    /// from. Written once (`0x678598`, from that update's `0xc7cf20` snapshot); never refreshed.
+    /// The eye at open, set once (`0x678598`, from `0xc7cf20`); [`RETIRE_DIST`] measures from it.
     anchor: Vec3,
-    /// `buildTime` — when the packet opened (record offsets are relative to this).
+    /// `buildTime`, when the packet opened; record offsets are relative to it.
     opened: f32,
-    /// `baseTime` — `opened + 6144/rate_at_open`: the instant replay starts.
+    /// `baseTime`, `opened + 6144/rate` at open: the instant replay starts.
     visible_at: f32,
     records: Vec<Pending>,
-    /// Total records ever pushed (records drain on activation; the CAP tracks this).
+    /// Records ever pushed; `records` drains on activation, the cap counts this.
     count: u32,
 }
 
@@ -65,31 +49,27 @@ pub(super) struct Patter {
     pub(super) variant: u8,
 }
 
-/// The per-kind pool (falling layer + ground layer) — its geometry rides the shared effect
-/// stream (0733), so it owns no meshes.
+/// One kind's falling and ground layers; its geometry rides the shared effect stream.
 #[derive(Default)]
 pub(super) struct Pool {
-    /// ACTIVE drops — falling, rendered, landing.
+    /// Active drops: falling, drawn, landing.
     pub(super) drops: Vec<Drop>,
-    /// The OPEN packet (recording; renders nothing).
+    /// The open packet, recording; it draws nothing.
     open: Option<Packet>,
-    /// SEALED packets — closed cohorts replaying (or waiting for) their baseTime windows.
+    /// Sealed packets, replaying or waiting for their `baseTime`.
     sealed: Vec<Packet>,
     pub(super) patters: Vec<Patter>,
 }
 
 impl Pool {
-    /// Records still in the pipeline (open + sealed) — the instrument's "pipe" count.
+    /// Records still in the pipeline, open and sealed: the state log's pipe count.
     pub(super) fn pending_len(&self) -> usize {
         self.open.as_ref().map_or(0, |p| p.records.len())
             + self.sealed.iter().map(|p| p.records.len()).sum::<usize>()
     }
 
-    /// Close-check + (re)open for this frame's recording; returns the packet's remaining
-    /// record space and the replay instant a record made NOW carries. Close conditions
-    /// (`0x675a6d` full ≥ 6144 / build age ≥ `P/6144` / past `baseTime`): closing SEALS the
-    /// packet (bakes its buffer — it may start drawing) and the next record opens a fresh one
-    /// stamped at the live rate.
+    /// Seals the open packet when full, `P/6144` old or past `baseTime` (`0x675a6d`), opens one at
+    /// the live rate, and returns its free space and the replay instant of a record made now.
     fn open_for(&mut self, now: f32, rate: f32, close_age: f32, cam: Vec3) -> (usize, f32) {
         if let Some(pk) = &self.open {
             if pk.count >= PACKET_CAP as u32 || now - pk.opened >= close_age || now >= pk.visible_at
@@ -118,32 +98,16 @@ impl Pool {
         }
     }
 
-    /// The TYPE-CHANGE cut (Q-D, driver `0x67be40` cross-fade): emission has already stopped
-    /// (`0x67585d`); the OPEN packet is retired unbaked (`0x6756b2–da` — it never drew, so it
-    /// is discarded), and every sealed packet whose replay hasn't started is unlinked
-    /// (`0x67575a`: discard when `curTick ≤ baseTime`) — the straggler tail dies here. Packets
-    /// already replaying finish their windows; active drops fall out normally (≤ ~1.3 s).
+    /// The type-change cut (`0x67be40`): the open packet is discarded unbaked (`0x6756b2`) and
+    /// every sealed one not yet replaying is unlinked (`0x67575a`); replaying ones finish.
     pub(super) fn cut(&mut self, now: f32) {
         self.open = None;
         self.sealed.retain(|p| now > p.visible_at);
     }
 
-    /// The **anchor cull** — retirement condition 3 ([`RETIRE_DIST`]), run at the top of the frame
-    /// exactly where the reference's active-list walk (`0x677ff0`) runs it, so the space it frees
-    /// is available to this frame's emission.
-    ///
-    /// Two halves, because benilla splits what the reference keeps in one buffer:
-    ///
-    /// - **Sealed packets** carry their anchor and are tested exactly as the bytes test them,
-    ///   3-D and against the live eye. The **open** packet is deliberately *not* tested: it is not
-    ///   in the reference's active list either (it is reached only by the stopping path, `cut`),
-    ///   and it falls to this cull one frame after it seals — which is precisely what the
-    ///   reference does with it.
-    /// - **Active drops** have no packet left to test, so they go by their own distance at a
-    ///   threshold slackened past anything the reference would still draw ([`RETIRE_DROP_SLACK`]).
-    ///
-    /// Retirement is a **discard, not a drain**: nothing here finishes replaying or finishes
-    /// falling, and a discarded flake never lands, so it leaves no patter behind.
+    /// The anchor cull ([`RETIRE_DIST`]), run before emission like the active-list walk
+    /// (`0x677ff0`): sealed packets by their anchor in 3-D, active drops by their own distance
+    /// ([`RETIRE_DROP_SLACK`]). The open packet is not in that list. A discard: no patter is left.
     pub(super) fn retire_far(&mut self, cam: Vec3, kind: WeatherKind) {
         let anchor_r2 = RETIRE_DIST * RETIRE_DIST;
         self.sealed
@@ -156,14 +120,10 @@ impl Pool {
     }
 }
 
-/// Lazy ground-height cache over the reference's weather ground oracle — the fog grid's
-/// sampler `0x6b7070` is **WMO/doodad-AWARE** (Q-B round 3, refuting the round-2 "terrain
-/// only" read): after the MCVT terrain sample it probes the chunk's static object refs ±200 yd
-/// (`CMapObj::IntersectSegment 0x6a37b0`) and MAXes the hit with terrain (`0x6b7237–4a`). So
-/// drops LAND ON ROOFS — splashes on the inn roof, never inside, from any camera. Benilla's
-/// equivalent: one downward ray per ~1.04-yd cell from the spawn plane against terrain +
-/// walk-WMO + doodads/GameObjects. Cleared when the spawn plane moves a story (the ray start
-/// decides which roofs it sees) or when it outgrows its bound.
+/// A lazy cache of the weather ground oracle (`0x67c760` → `0x6b7070`), the max of terrain and
+/// the chunk's WMO and doodad hits (`CMapObj::IntersectSegment` `0x6a37b0`, `0x6b7237`), so drops
+/// land on roofs. Here one downward ray per cell from the spawn plane; cleared when that plane
+/// moves a story (the ray start decides which roofs it sees) or the cache outgrows its bound.
 #[derive(Resource, Default)]
 pub(super) struct HeightCache {
     cells: HashMap<(i32, i32), f32>,
@@ -207,23 +167,20 @@ impl HeightCache {
         y
     }
 
-    /// The grid cell owning an XZ position (the reference's 1.0416666-yd stride).
+    /// The grid cell owning an XZ position.
     pub(super) fn key(x: f32, z: f32) -> (i32, i32) {
         ((x / CELL).floor() as i32, (z / CELL).floor() as i32)
     }
 }
 
-/// The reference's per-frame record count (`0x6754cc–ef`): `fistp(min(space, quota) − 0.5)`
-/// under round-nearest-EVEN — the x87 default. The parity matters: at `space = 1` this is
-/// `RNE(0.5) = 0` FOREVER, so a packet that lands on 6143 records can never full-close and
-/// seals only at the `P/6144` build age (5.7 s shader rain) — one of the three mechanisms
-/// behind the reference's stochastic ~5 s / ~10 s upswing onset (round 3 Q-A).
+/// The per-frame record count, `fistp(min(space, quota) − 0.5)` under x87 round-to-nearest-even
+/// (`0x6754cc`). The parity is load-bearing: at `space = 1` it is `RNE(0.5) = 0` forever, so a
+/// 6143-record packet never fills and seals only at the `P/6144` age.
 fn frame_count(space: usize, quota: f32) -> usize {
     ((space as f32).min(quota) - 0.5).round_ties_even().max(0.0) as usize
 }
 
-/// One kind's spawn box: `(half_xy, z_off)` — the horizontal half-extent of the scatter plane
-/// and the slab's local lift above it (HALF the ctor's vertical extent; see [`RAIN_Z_OFF`]).
+/// One kind's spawn box: the scatter plane's half-extent and the slab's local lift above it.
 pub(super) const fn spawn_box(kind: WeatherKind) -> (f32, f32) {
     match kind {
         WeatherKind::Rain => (RAIN_HALF_XY, RAIN_Z_OFF),
@@ -231,33 +188,15 @@ pub(super) const fn spawn_box(kind: WeatherKind) -> (f32, f32) {
     }
 }
 
-/// One particle's **placement law**, as a pure function of its five RNG draws — the reference's
-/// composed spawn (wow-re `wx-snow-placement-law.md`, `0x677750` snow / `0x674c50` rain):
+/// `(spawn, velocity)` from five random draws (`0x677750` snow, `0x674c50` rain), placed by:
 ///
 /// ```text
 /// pos = R(α, ĥ×ŷ)·(O − T·V)  +  1.75·W  +  C
 /// ```
 ///
-/// - `O` — the scatter, uniform over `±half_xy` on a **flat plane through the eye**, its vertical
-///   random dead (`·0.0` at `0x6777ce`). This is the plane the particle *arrives* on, not the one
-///   it is born on.
-/// - `T = z_off/|V.y|`, `O − T·V` — the back-projection up the particle's own velocity, so it
-///   starts `z_off` above the plane **in slab-local space** and passes its scatter point at `t = T`.
-/// - **`R` — the slab tilt into the direction of travel, and the term benilla was missing.**
-///   `α = 65°·sat(|W|/18)` about the horizontal axis ⊥ the heading ([`WeatherWind::slab`]).
-///   It rotates the **local offset only**: the velocity is written once at spawn and never
-///   re-touched, so drift stays world-fixed (`0x677a41` copies 3 dwords — position, not velocity).
-/// - `1.75·W + C` — the wind lead and the live camera eye, added AFTER the rotation, so the
-///   volume's origin rides the player while its *shape* leans.
-///
-/// Why the missing `R` was the whole of B233's "I can outrun the snow": untilted, every particle
-/// is born a flat `z_off` up and needs the full `T` to reach eye height — 7.8 s for snow at grade
-/// 0.6, during which a running player covers 54 yd against a 45 yd box. Tilted at a 7 yd/s run
-/// (α = 25.3°) the slab's leading corner is born ~8 yd up and ~53 yd ahead instead, arriving in
-/// ~2 s — so snow keeps meeting the runner head-on. Rain never showed the symptom because its
-/// `T` is 1.24 s, but it takes the same rotation.
-///
-/// Returns `(spawn, velocity)` in Bevy world space.
+/// `O` is the scatter on the eye plane where the particle arrives (its vertical draw is dead at
+/// `0x6777ce`), backed up its velocity by `T = z_off/|V.y|`. `R` ([`WeatherWind::slab`]) leans
+/// the offset but not the velocity (`0x677a41` copies position only), so drift is world-fixed.
 pub(super) fn spawn_particle(
     kind: WeatherKind,
     w: f32,
@@ -271,9 +210,8 @@ pub(super) fn spawn_particle(
         0.0,
         (r[1] - 0.5) * 2.0 * half_xy,
     );
-    // The byte kinematics (w = density): the drift heading centres on the WORLD-FIXED −1.57
-    // azimuth (0x80ffbc) ± a grade-scaled spread (the FULL width — `(r−0.5)` halves it) — rain
-    // stays a coherent sheet (±7.5° at grade 1); calm snow wanders anywhere (2π at grade 0).
+    // `w` is the density. The heading centres on the world-fixed −1.57 (`0x80ffbc`), spread by
+    // grade over its full width (`r − 0.5` halves it): rain ±7.5° at grade 1, calm snow 2π.
     let (vy, drift_mag, spread) = match kind {
         WeatherKind::Rain => (
             -(RAIN_VZ_BASE + RAIN_VZ_W * w + RAIN_VZ_RNG * w * r[2]),
@@ -292,8 +230,7 @@ pub(super) fn spawn_particle(
     (origin + slab * (scatter - vel * (z_off / -vy)), vel)
 }
 
-/// One kind's frame: record (RNE-counted, packet-stamped), activate sealed cohorts,
-/// integrate, land into the ground layer.
+/// One kind's frame: retire, record, activate sealed packets, integrate, land.
 pub(super) fn run_kind(
     pool: &mut Pool,
     kind: WeatherKind,
@@ -313,22 +250,16 @@ pub(super) fn run_kind(
         _ => SNOW_P,
     };
     let z_off = spawn_box(kind).1;
-    // Every ground probe this frame casts from ONE plane. It has to be a constant: the slab tilt
-    // spreads the spawn heights across `z_off·(cos α ∓ (half_xy/z_off)·sin α)` — ~8..46 yd at a
-    // 7 yd/s run — and [`HeightCache`] throws its whole grid away when the cast height moves 8 yd,
-    // so probing from each particle's own height would nuke the cache every few particles.
+    // Every probe this frame casts from one plane: the tilted slab spreads spawn heights over
+    // ~8..46 yd, and the height cache clears whenever the cast height moves 8 yd.
     let cast_plane = cam_pos.y + z_off;
 
-    // ===== retire (the active-list walk, before anything is emitted) =====
+    // ===== retire =====
     pool.retire_far(cam_pos, kind);
 
-    // ===== record (the emit gate + the RNE frame count) =====
-    // The per-frame emit gate (`0x6754a0`, threshold `[0x8015b8]` = 1.0): a frame records only
-    // when `min(dt, 1/60)·rate > 1.0` — below ~60 drops/s NOTHING spawns (no trickle of ones).
-    //
-    // `REF_FPS_GAIN` denominates the rate in the reference install's frame cap (1165) — the one
-    // deliberate departure from the byte law on this path, and the reason benilla no longer reads
-    // twice as dense as the A/B it is judged against.
+    // ===== record =====
+    // The emit gate (`0x6754a0`, `0x8015b8` = 1.0): a frame records only when its quota is over
+    // 1, so below ~60 drops/s nothing spawns. `REF_FPS_GAIN` is this path's one deviation.
     let rate = weather.density_gain() * p * density * REF_FPS_GAIN;
     let quota = rate * dt.min(DT_CAP);
     if quota > 1.0 {
@@ -336,8 +267,7 @@ pub(super) fn run_kind(
         let (space, replay_at) = pool.open_for(now, rate, close_age, cam_pos);
         let n = frame_count(space, quota)
             .min(pool_bound(kind).saturating_sub(pool.drops.len() + pool.pending_len()));
-        // The emission volume's origin: the live camera eye carried forward by the wind lead
-        // (`+1.75·W + C`, added AFTER the tilt — the volume rides the player, its shape leans).
+        // The volume's origin: the eye led by the wind (`1.75·W + C`, added after the tilt).
         let anchor = cam_pos + wind.vel * WIND_LEAD;
         let origin = Vec3::new(anchor.x, cam_pos.y, anchor.z);
         let w = density;
@@ -351,8 +281,7 @@ pub(super) fn run_kind(
             ];
             let (spawn, vel) = spawn_particle(kind, w, origin, wind.slab, r);
             let land_y = heights.ground_y(spawn.x, spawn.z, cast_plane, spatial, filter);
-            // Ground above the whole spawn column (a mountainside or roof over the box top) —
-            // the oracle reports ground ≥ spawn z and the drop dies at birth (`0x675051`).
+            // Ground at or above the spawn kills it at birth (`0x675051`).
             if land_y >= spawn.y {
                 continue;
             }
@@ -373,10 +302,9 @@ pub(super) fn run_kind(
         }
     }
 
-    // ===== activate: sealed cohorts replay their records from baseTime onward =====
-    // A record whose replay instant passed while its packet was still baking appears mid-
-    // window: fast-forward its fall (drift included — re-sample the ground at the cell it
-    // drifted to) and skip it if it already landed (no splash — an unseen landing never drew).
+    // ===== activate: sealed packets replay from `baseTime` =====
+    // A record whose instant passed while its packet was open appears mid-fall, on its new
+    // cell's ground; one that already landed is skipped with no splash.
     let drops = &mut pool.drops;
     for pk in &mut pool.sealed {
         let mut i = 0;
@@ -403,13 +331,9 @@ pub(super) fn run_kind(
     }
     pool.sealed.retain(|pk| !pk.records.is_empty());
 
-    // Ground layer. Rain: a patter is created **1:1 with each landing drop** (rf-weather-render
-    // Q5). The `|v|² ≤ 2` gate (0x6755c2, manager+0x5c) tests the RIDDEN-TRANSPORT velocity
-    // (object 0x903) — ≈0 whenever the player isn't on a moving transport — NOT the wind:
-    // running never kills splashes. Benilla has no ridden transports yet, so the gate always
-    // passes; when transports land, test the transport's planar speed² ≤ 2.0 here. Snow: every
-    // landing flake settles and fades over the `+0.25 s` window. Patter pool cap = 0x1800
-    // (byte-cited; at full shader rain the landing rate saturates it — Q-A round 3).
+    // Rain leaves one patter per landing drop (`0x6754a0`). The reference skips it when the
+    // ridden transport's `|v|² > 2` (`0x6755c2`, `mgr+0x5c`), never for running; here the gate
+    // always passes, with no transport speed wired. Snow settles and fades over 0.25 s.
     let ground_life = match kind {
         WeatherKind::Rain => PATTER_LIFE,
         _ => SNOW_SETTLE_LIFE,
@@ -417,10 +341,8 @@ pub(super) fn run_kind(
     let ground_gate = true;
 
     // ===== integrate + land =====
-    // The landing test runs against the ground of the drop's CURRENT cell (re-sampled on cell
-    // change — see [`Drop::land_y`]): a drop drifting under cover "lands" the moment its cell's
-    // ground (the roof top, the grid is a max-from-above) rises above it, and its patter sits ON
-    // that ground — the drip line splashes on the porch roof, never the room floor.
+    // Landing tests the current cell's ground, a max from above: a drop drifting under cover
+    // lands on the roof and splashes there, never on the floor below.
     let mut landed: Vec<Patter> = Vec::new();
     {
         pool.drops.retain_mut(|d| {
@@ -459,8 +381,7 @@ pub(super) fn run_kind(
 mod tests {
     use super::*;
 
-    /// A converged [`WeatherWind`] for a player running Bevy +X at `speed` — driven through the
-    /// real 149 ms window rather than hand-built, so these tests also pin the wiring.
+    /// A converged [`WeatherWind`] for a run along Bevy +X at `speed`, through the real window.
     fn wind_at(speed: f32) -> WeatherWind {
         let mut wind = WeatherWind::default();
         let dt = 1.0 / 60.0;
@@ -470,16 +391,12 @@ mod tests {
         wind
     }
 
-    /// The wire grade the director ran, through the published knee (`0x67bcc8`,
-    /// `max(0, (grade−0.25)·4/3)`) — the density the spawn kernel actually sees.
+    /// A wire grade through the knee (`0x67bcc8`): the density the spawn kernel sees.
     fn grade(wire: f32) -> f32 {
         ((wire - 0.25) * (4.0 / 3.0)).max(0.0)
     }
 
-    /// The slab **leans into the direction of travel** (`α = 65°·sat(|W|/18)`, `0x677965`–
-    /// `0x677a55`): at a 7 yd/s run the leading corner is born ~8 yd up and ~53 yd ahead instead
-    /// of a flat 30 up / 45 ahead, and the trailing corner rides up to ~46. Reproduces wow-re's
-    /// own worked numbers for `wx-snow-placement-law.md`.
+    /// At a 7 yd/s run the leading corner is born ~8 yd up and ~53 ahead, the trailing ~46 up.
     #[test]
     fn the_spawn_slab_leans_into_the_run() {
         let wind = wind_at(7.0);
@@ -488,19 +405,16 @@ mod tests {
         let trail = wind.slab * Vec3::new(-half_xy, z_off, 0.0);
         assert!(
             (lead.x - 53.5).abs() < 0.5 && (lead.y - 7.9).abs() < 0.5,
-            "leading corner {lead:?} — wow-re's worked value is (53.5, 7.9)"
+            "leading corner {lead:?} — the worked value is (53.5, 7.9)"
         );
         assert!(
             (trail.x + 27.9).abs() < 0.5 && (trail.y - 46.3).abs() < 0.5,
-            "trailing corner {trail:?} — wow-re's worked value is (−27.9, 46.3)"
+            "trailing corner {trail:?} — the worked value is (−27.9, 46.3)"
         );
-        // Standing still there is no heading to lean into, and the slab is flat.
         assert_eq!(wind_at(0.0).slab, Quat::IDENTITY);
     }
 
-    /// The two wind rotations are **separate ramps off the same axis**, not one constant reused:
-    /// at 18 yd/s the slab has saturated at 65° while the streak apex is only at 27°. Collapsing
-    /// them would silently halve the slab's lean at every running speed.
+    /// At 18 yd/s the slab has saturated at 65° while the streak apex is at 27°.
     #[test]
     fn the_slab_and_streak_tilts_are_distinct_ramps() {
         let wind = wind_at(18.0);
@@ -517,16 +431,8 @@ mod tests {
         );
     }
 
-    /// **B233's pin — a running player must keep meeting snow head-on.**
-    ///
-    /// For each particle, ask where it crosses EYE HEIGHT and where the camera is at that
-    /// instant. Untilted, a snowflake at the director's grade needs its whole ~7.8 s fall to get
-    /// there, and a 7 yd/s runner covers 54 yd in that time against a 45 yd box — so nearly every
-    /// arrival lands *behind* them. That is exactly what the live probe measured: the forward eye
-    /// band collapsed 25× and hit literally zero, and the field's centroid sat 36 yd back.
-    ///
-    /// The slab tilt is the term that fixes it, so this test asserts the *contrast*: the fix has
-    /// to be worth several times the broken behaviour, not merely nonzero.
+    /// Each particle's eye-height crossing against where the runner is then: untilted, a flake
+    /// at grade 0.6 falls ~7.8 s, long enough for a 7 yd/s runner to outrun nearly all of them.
     #[test]
     fn a_running_player_still_meets_snow_head_on() {
         let ahead_share = |speed: f32, slab: Quat| {
@@ -578,7 +484,7 @@ mod tests {
         assert!(
             tilted > 0.25,
             "with the slab tilt a runner should still meet a quarter or more of the arrivals \
-             head-on (wow-re's worked value is ~0.34); got {tilted:.3}"
+             head-on (the worked value is ~0.34); got {tilted:.3}"
         );
         assert!(
             tilted > flat * 3.0,
@@ -586,9 +492,7 @@ mod tests {
         );
     }
 
-    /// Rain takes the same rotation and must not change character: its fall is 1.24 s, so it
-    /// never had B233's problem, and the tilt shifts its arrival band forward without emptying
-    /// either side. (wow-re Q5: `[−61,+69]` → `[−45,+86]`.)
+    /// The tilt moves rain's arrival band from −61..+69 to −45..+86 yd, emptying neither side.
     #[test]
     fn the_tilt_leaves_rain_balanced() {
         let m = grade(0.6);
@@ -622,44 +526,33 @@ mod tests {
         );
     }
 
-    /// The whole of decision 1165, as arithmetic: benilla at 60 fps must put the same field on
-    /// screen as the **reference install** does at its own `SET maxfps "30"`, because that 30 fps
-    /// client is what the director's A/B is judged against. Byte-faithfully we ran at exactly
-    /// twice it — same `P`, same `K`, same knee — purely because the reference's per-frame budget
-    /// discards its remainder and so thins out below 60 fps.
+    /// At 60 fps with the gain, benilla emits what a reference capped at 30 fps does.
     #[test]
     fn the_frame_cap_gain_matches_the_reference_installs_throughput() {
-        // Nominal snow at wire grade 1.0, weatherDensity 3 (K = 1) — the trace's 14000/s.
+        // Nominal snow at wire grade 1.0 and weatherDensity 3 (K = 1): 14000/s.
         let raw = SNOW_P * grade(1.0);
-        // The reference's own law: a per-frame budget of `min(dt, 1/60)·rate` whose sub-unit
-        // remainder is discarded, so throughput falls off below 60 fps.
+        // The reference's budget `min(dt, 1/60)·rate`, its remainder discarded.
         let per_second = |rate: f32, fps: f32| {
             frame_count(PACKET_CAP, rate * (1.0 / fps).min(DT_CAP)) as f32 * fps
         };
 
-        // What the director is actually looking at: the reference at its `maxfps "30"`.
         let reference = per_second(raw, REF_MAXFPS);
         assert!(
             (reference / (raw * 0.5) - 1.0).abs() < 0.01,
             "a 30-capped reference emits half its nominal rate, got {reference} of {raw}"
         );
-        // benilla at 60 fps with the gain lands on that same field…
         let ours = per_second(raw * REF_FPS_GAIN, 60.0);
         assert!(
             (ours / reference - 1.0).abs() < 0.01,
             "ours {ours} must match the reference's {reference}"
         );
-        // …where byte-faithfully it ran at exactly twice it. This factor, not any constant, was
-        // the whole of the director's "way too dense" on B233.
+        // Without the gain it runs at twice the reference.
         assert!((per_second(raw, 60.0) / reference - 2.0).abs() < 0.01);
         // Above 60 fps the reference's own `min(dt, 1/60)` already flattens throughput, so the
         // gain does not compound with a fast machine.
         assert!((per_second(raw * REF_FPS_GAIN, 144.0) / ours - 1.0).abs() < 0.02);
     }
 
-    /// The RNE frame count (`0x6754cc–ef`, x87 round-nearest-even): normal quotas round to
-    /// the nearest count, and `space = 1` yields `RNE(0.5) = 0` — the parity stick that keeps
-    /// a 6143-record packet from ever full-closing.
     #[test]
     fn frame_count_rounds_nearest_even() {
         assert_eq!(frame_count(6144, 583.3), 583); // RNE(582.8)
@@ -669,26 +562,20 @@ mod tests {
         assert_eq!(frame_count(6144, 1.2), 1); // RNE(0.7) → 1
     }
 
-    /// The packet clock: baseTime is stamped at OPEN alone (`0x67598c`); a packet re-opens
-    /// (re-stamping at the live rate) once past its own baseTime or the `P/6144` build age.
-    /// Records replay ONLY after their packet seals (shader legs draw from the close-baked
-    /// buffer, `0x6752b0` ← `0x675a97` sole caller).
+    /// `baseTime` is stamped at open alone; past it, the packet reopens at the live rate.
     #[test]
     fn packet_seals_before_replaying() {
         let mut pool = Pool::default();
         let close_age = RAIN_P / PACKET_CAP as f32; // 35000/6144 ≈ 5.7 s
         let (_, at0) = pool.open_for(0.0, RAIN_P, close_age, Vec3::ZERO);
         assert!((at0 - PACKET_CAP as f32 / RAIN_P).abs() < 1e-3);
-        // 0.1 s later, same packet — the stamp is unchanged; the record offset advances.
+        // 0.1 s later, same packet: the stamp holds and the record offset advances.
         let (_, at1) = pool.open_for(0.1, RAIN_P * 2.0, close_age, Vec3::ZERO);
         assert!((at1 - (at0 + 0.1)).abs() < 1e-3);
-        // Past the baseTime the packet re-opens at the live rate.
         let (_, at2) = pool.open_for(1.0, RAIN_P * 2.0, close_age, Vec3::ZERO);
         assert!((at2 - (1.0 + PACKET_CAP as f32 / (RAIN_P * 2.0))).abs() < 1e-3);
     }
 
-    /// The Q-D type-change cut: the open packet is discarded unbaked, sealed-but-not-yet-
-    /// replaying packets are unlinked (`0x67575a`), replaying ones keep their records.
     #[test]
     fn cut_discards_the_unreplayed_pipeline() {
         let d = || Drop {
@@ -721,7 +608,7 @@ mod tests {
         pool.sealed.push(Packet {
             anchor: Vec3::ZERO,
             opened: 8.0,
-            visible_at: 60.0, // never started replaying — the straggler
+            visible_at: 60.0, // never started replaying
             records: vec![Pending {
                 at: 60.5,
                 drop: d(),
@@ -734,10 +621,7 @@ mod tests {
         assert!((pool.sealed[0].visible_at - 1.0).abs() < 1e-6);
     }
 
-    /// GT#1 under the round-3 shader-leg model: on a full upswing the earliest possible
-    /// replay is ~4.9 s (packet-1 is always the ~100 s forecast orphan) and the deterministic
-    /// fixed-dt path lands in the reference's observed 4.5–15 s onset band — never the
-    /// pre-pipeline 2.5 s.
+    /// A 10 s upswing's first visible rain lands in the reference's 4.5–15 s onset band.
     #[test]
     fn upswing_first_visible_rain_is_gated() {
         let mut pool = Pool::default();
@@ -769,7 +653,7 @@ mod tests {
                     }
                 }
             }
-            // Replay eligibility: sealed AND past the record instant.
+            // Replay needs the packet sealed and the record's instant past.
             for pk in &pool.sealed {
                 for r in &pk.records {
                     if r.at <= t {
@@ -785,10 +669,7 @@ mod tests {
         );
     }
 
-    /// Retirement condition 3 (`0x6780d3`–`0x678110` against `[0x810008]` = 200.0): a `.go`
-    /// teleport **discards** the field and everything queued behind it, instead of leaving it to
-    /// fall out at the old position over the ~7.5 s a flake takes to reach the ground. A 150 yd
-    /// walk — inside every distance the rule protects — touches nothing.
+    /// A teleport discards the field and its queue; a 150 yd walk touches nothing.
     #[test]
     fn a_teleport_retires_the_field_and_its_pipeline() {
         let field = || {
@@ -831,21 +712,16 @@ mod tests {
         );
     }
 
-    /// The active-drop half of the cull stands in for a packet test benilla no longer has the
-    /// identity to run, so it must be **strictly weaker** than the rule it replaces: keeping a
-    /// flake the reference has already retired costs a frame of latency, retiring one the
-    /// reference is still drawing is a visible hole. And the anchor rule itself must stay what
-    /// the bytes make it — a discontinuity guard that motion can never trip.
+    /// The drop cull is strictly weaker than the packet cull, which only a teleport can trip.
     #[test]
     fn the_drop_cull_never_beats_the_reference_to_a_flake() {
-        /// Ground speed at +100% (the epic mount), yd/s — the fastest the eye moves continuously.
+        /// Ground speed at +100% (the epic mount) in yd/s, the fastest continuous eye motion.
         const EPIC_MOUNT: f32 = 14.0;
         for kind in [WeatherKind::Rain, WeatherKind::Snow] {
             let (half_xy, z_off) = spawn_box(kind);
             let corner = 2.0f32.mul_add(half_xy * half_xy, z_off * z_off).sqrt();
-            // The widest a flake the reference is STILL DRAWING can sit from the eye: its
-            // packet's anchor is inside 200, the flake is inside the box's corner of the emission
-            // origin, and that origin leads the eye by `1.75·W`.
+            // The farthest a drawn flake can be: anchor within 200, flake within the box corner of
+            // the origin, origin leading the eye by `1.75·W`.
             let widest_drawn = RETIRE_DIST + corner + WIND_LEAD * EPIC_MOUNT;
             let ours = RETIRE_DIST + corner + RETIRE_DROP_SLACK;
             assert!(
@@ -853,8 +729,7 @@ mod tests {
                 "{kind:?}: culling at {ours:.1} yd would beat the reference's {widest_drawn:.1} yd"
             );
         }
-        // A snow packet lives at most `close_age + fall_time`; even at epic-mount speed that
-        // carries the eye barely half of `RETIRE_DIST`, so nothing but a teleport ever trips it.
+        // A snow packet's life at mount speed covers under half of `RETIRE_DIST`.
         let packet_life = SNOW_P / PACKET_CAP as f32 + SNOW_Z_OFF / (SNOW_VZ_BASE + SNOW_VZ_W);
         assert!(
             packet_life * EPIC_MOUNT < RETIRE_DIST,
diff --git a/crates/benilla-world/src/weather/precip/render.rs b/crates/benilla-world/src/weather/precip/render.rs
index 5aa32e41..9e55ff66 100644
--- a/crates/benilla-world/src/weather/precip/render.rs
+++ b/crates/benilla-world/src/weather/precip/render.rs
@@ -1,14 +1,8 @@
-//! The precip **stream pushers** — streak/patter/flake geometry emitted each frame from the
-//! live pools straight into the shared effect stream (0733; world-space, and the lane rebases
-//! camera-relative render-side — except the FLAKE draw, which writes camera-relative itself for
-//! f32 precision, see [`push_flakes`]). Split from `precip`'s root; geometry only, no sim state.
-//! Empty pools push nothing, so an idle sky costs zero here — the structural replacement for
-//! the old fixed-capacity meshes' `WriteGate` (the 0353 fps hunt).
+//! Streak, patter and flake geometry pushed each frame from the live pools onto the shared
+//! effect stream, in world space except the flakes, which are camera-relative.
 
-// Explicit, not `bevy::prelude::*`: the parent module's own prelude glob reaches this file
-// through `use super::*` below, and two globs supplying the same names had rustc crediting the
-// use to one or the other by platform — the "unused import" every non-macOS build warned on
-// (2205's next move 4).
+// Explicit, not `bevy::prelude::*`: the parent's prelude glob arrives through `use super::*`, and
+// two globs of the same names draw an unused-import warning on non-macOS builds.
 use bevy::math::{Quat, Vec3};
 
 use crate::particles::buffer::EffectVertex;
@@ -16,10 +10,7 @@ use crate::particles::buffer::EffectVertex;
 use super::pool::{Drop, Patter};
 use super::*;
 
-/// Falling-drop streaks — the verified triangle law (rf-weather-render Q1): per drop, base
-/// verts `head ∓ 0.05·RIGHT` (RIGHT = normalize(cross(toCam, antiVel)), camera-facing width
-/// axis), apex `head + M·(2.0·antiVel̂)` with M the wind-tilt applied to the APEX ONLY. UVs
-/// (0,1)/(1,1)/(0.5,0). No vertex colour/alpha (white; the look is the texture under Mod2x).
+/// Falling-drop streaks: one fixed-size triangle per drop, tilted at the apex only.
 pub(super) fn push_streaks(out: &mut Vec<EffectVertex>, drops: &[Drop], tilt: Quat, cam: Vec3) {
     let white = [1.0, 1.0, 1.0, 1.0];
     for d in drops.iter().take(POOL) {
@@ -41,9 +32,7 @@ pub(super) fn push_streaks(out: &mut Vec<EffectVertex>, drops: &[Drop], tilt: Qu
     }
 }
 
-/// Ground patters: one camera-facing **triangle** per splash (the byte geometry: corners
-/// `center − right`, `center + up`, `center + right` with `right = view_right/12`,
-/// `up = view_up/6`), animated left→right across its atlas row over the 0.25 s life.
+/// Ground patters: one camera-facing triangle per splash, stepping across its atlas row.
 pub(super) fn push_patters(
     out: &mut Vec<EffectVertex>,
     patters: &[Patter],
@@ -56,9 +45,8 @@ pub(super) fn push_patters(
         let t = (p.age / PATTER_LIFE).clamp(0.0, 1.0);
         let frame = ((t * 4.0) as u32).min(3) as f32;
         let (u0, v0) = (frame * 0.25, f32::from(p.variant) * 0.25);
-        // No vertex alpha (Mod2x has none): the atlas's 4 growth frames are the animation, and
-        // the texture's grey-128 background is neutral.
-        // The byte texcoord law (`wx_rainrender.rs` step 8): base-left, apex, base-right.
+        // No vertex alpha: the atlas's 4 frames are the animation, its grey-128 ground neutral.
+        // The texcoord law (`0x675ac0`): base-left, apex, base-right.
         for (pos, uv) in [
             (p.pos - right, [u0, v0 + 0.25]),
             (p.pos + up, [u0 + 0.125, v0 + 0.043]),
@@ -73,43 +61,23 @@ pub(super) fn push_patters(
     }
 }
 
-/// The camera terms [`push_flakes`] needs to turn the reference's **pixel** point size into a
-/// world-space quad. `snowpoint.bls` sizes a flake in window coordinates, so the size a flake
-/// gets is a property of the projection, not of the world.
+/// The camera terms [`push_flakes`] needs to turn a pixel point size into a world-space quad.
 pub(super) struct FlakeView {
     pub(super) eye: Vec3,
-    /// The camera's forward axis — a flake's *view depth* (`z`, the perspective divisor), which
-    /// is what the pixel↔world conversion keys on. Distinct from `|flake − eye|`, which is what
-    /// the size LAW keys on; off-axis flakes differ in the two.
+    /// For a flake's view depth, which the pixel-to-world conversion keys on; the size law keys
+    /// on the radial `|flake − eye|`, which differs off-axis.
     pub(super) forward: Vec3,
     pub(super) right: Vec3,
     pub(super) up: Vec3,
-    /// `tan(fovY/2) / SNOW_PX_REF_HEIGHT` — world units per **era pixel**, per unit of view depth.
-    /// A world length `L` at view depth `z` covers `L / (z · this)` era pixels, so a `px`-era-pixel
-    /// sprite wants half-extent `px · z · this`.
-    ///
-    /// The denominator is deliberately **not** the live viewport height — see
-    /// [`super::SNOW_PX_REF_HEIGHT`]. Dividing by the live height reproduces the reference's pixel
-    /// *count* and destroys its apparent size on any screen taller than the era's.
+    /// `tan(fovY/2) / SNOW_PX_REF_HEIGHT`, world units per era pixel per unit of view depth: a
+    /// `px` sprite at depth `z` wants half-extent `px·z·this`. Never the live viewport height.
     pub(super) world_per_px: f32,
 }
 
-/// Snow flakes — the ARB point-sprite leg `0x678610`, reproduced as screen-aligned quads because
-/// wgpu has no point size (WebGPU pins `PointList` at 1 px).
-///
-/// Per flake (wow-re `rf-snow-flake-render.md` §2.4, the shipped `snowpoint.bls` read verbatim):
-/// - size `max(1, 14·clamp01(1 − 0.02·d))` **era pixels**, `d = |flake − eye|` in yards — inverted
-///   through the projection into a world half-extent, so the on-screen footprint matches the
-///   reference's *angular* size at any resolution or fov (see [`super::SNOW_PX_REF_HEIGHT`] for
-///   why the era's screen height, and not the live one, is the denominator);
-/// - RGB white, alpha `clamp01(t − f1)` while falling (a 1 s linear fade-IN from spawn) and
-///   `clamp01(1 − 4·(t − f2))` once settled (the 0.25 s fade-out);
-/// - the whole texture per flake (`GL_COORD_REPLACE`), which the 0..1 UVs below reproduce.
-///
-/// There is **no per-flake size**: the 32-byte flake record has no spare field, the spawn draws
-/// exactly 5 RNG values (none a size), and both legs' size terms are per-draw constants.
-///
-/// `drops` = falling flakes; `settled` = landed ones fading out over the `+0.25 s` window.
+/// Snow flakes: the point-sprite leg `0x678610` as screen-aligned quads, since wgpu has no point
+/// size. Per `snowpoint.bls`: white, alpha `clamp01(t − f1)` while falling and
+/// `clamp01(1 − 4·(t − f2))` settled, the whole texture per flake (`GL_COORD_REPLACE`). There is
+/// no per-flake size: the 32-byte record has no spare field and none of the 5 spawn draws is one.
 pub(super) fn push_flakes(
     out: &mut Vec<EffectVertex>,
     drops: &[Drop],
@@ -117,24 +85,20 @@ pub(super) fn push_flakes(
     view: &FlakeView,
 ) {
     let mut sprite = |center: Vec3, alpha: f32| {
-        // CAMERA-RELATIVE from here down (the draw sets `EffectDrawSpec::cam_relative`, so the
-        // lane's rebase skips it). This is not a convenience: a near flake's half-extent is
-        // ~1.6 mm, which is 3 f32 ULPs at Kharanos's ~5600-yd coordinates and under 1 at a map
-        // corner — written absolutely, a 14 px sprite loses 2–7 px of width and flickers. Every
-        // term below is small, so the arithmetic is exact wherever in the world we are.
+        // Camera-relative (the draw sets `EffectDrawSpec::cam_relative`): a near flake's ~1.6 mm
+        // half-extent is 3 f32 ULPs at 5600 yd, so absolute coordinates lose it and flicker.
         let to_flake = center - view.eye;
         let z = to_flake.dot(view.forward);
         if z <= 0.0 {
-            return; // behind the eye — clipped anyway, and the pixel↔world map is undefined
+            return; // behind the eye, where the pixel-to-world map is undefined
         }
-        // The size law, in pixels, off the RADIAL distance; then pixels → world at this flake's
-        // view depth.
+        // The size law off the radial distance, then pixels to world at this view depth.
         let px = (SNOW_PX_AT_EYE * (1.0 - SNOW_PX_FALLOFF * to_flake.length()).clamp(0.0, 1.0))
             .max(SNOW_PX_MIN);
         let half = px * z * view.world_per_px;
         let r = view.right * half;
         let u = view.up * half;
-        // Perimeter order (bl, br, tr, tl) — the stream's quad-index pattern closes it.
+        // Perimeter order (bl, br, tr, tl) for the stream's quad-index pattern.
         for (pos, uv) in [
             (to_flake - r - u, [0.0, 1.0]),
             (to_flake + r - u, [1.0, 1.0]),
@@ -162,8 +126,7 @@ mod tests {
 
     const FOVY: f32 = std::f32::consts::FRAC_PI_4;
 
-    /// A camera at `eye` looking down −Z (Bevy's convention), 45° vertical fov — carrying the
-    /// production `world_per_px`, which denominates in the ERA height and not the render height.
+    /// A camera at `eye` looking down −Z, 45° vertical fov, with the production `world_per_px`.
     fn view_at(eye: Vec3) -> FlakeView {
         FlakeView {
             eye,
@@ -193,9 +156,7 @@ mod tests {
         }
     }
 
-    /// A flake's footprint, in real pixels, at a given render height — measured by pushing the
-    /// quad and projecting its corners through a real perspective matrix, never by re-deriving
-    /// the half-extent formula.
+    /// A flake's footprint in pixels at a render height, measured by projecting the pushed quad.
     fn footprint_px(d: f32, render_h: f32) -> f32 {
         // The RH projection Bevy builds: clip.w = −z_view, so a flake at z_view = −d has w = d.
         let proj = Mat4::perspective_rh(FOVY, 16.0 / 9.0, 0.1, 1000.0);
@@ -215,9 +176,7 @@ mod tests {
         window_y(Vec3::from(out[3].pos)) - window_y(Vec3::from(out[0].pos))
     }
 
-    /// **At the era's own screen height benilla draws the reference's pixels exactly** —
-    /// `max(1, 14·clamp01(1 − 0.02·d))`. This is the fidelity anchor; the test below is what
-    /// keeps it from being read as "14 px, always".
+    /// At the era's screen height the footprint is the reference's pixel count exactly.
     #[test]
     fn flake_covers_the_reference_pixel_footprint() {
         for d in [1.0f32, 5.0, 7.14, 20.0, 46.43, 60.0, 100.0] {
@@ -230,16 +189,7 @@ mod tests {
         }
     }
 
-    /// …and on a taller screen it grows to hold the same **angle**, rather than staying at 14 px
-    /// and shrinking away.
-    ///
-    /// `snowpoint.bls` sizes in framebuffer pixels because that is what
-    /// `GL_VERTEX_PROGRAM_POINT_SIZE_ARB` does, not as a statement about apparent size; on 2004
-    /// hardware the framebuffer *was* the screen. Obeyed literally, the flake's angular size falls
-    /// as `1/height` — the director's A/B put benilla's flakes 2.7× under the reference's purely
-    /// because a 4K scale-2 framebuffer is 2.7× taller than the reference install's 800
-    /// (decision 1162). Pin the invariant that fixed it: the fraction of the screen a flake covers
-    /// does not depend on the resolution.
+    /// On a taller screen a flake keeps the same share of the screen, not the same pixels.
     #[test]
     fn the_flake_holds_its_angle_across_resolutions() {
         for d in [1.0f32, 12.0, 30.0, 60.0] {
@@ -254,7 +204,7 @@ mod tests {
                     era * 100.0,
                 );
             }
-            // And the absolute pixel count really does scale, which is the whole change.
+            // The absolute pixel count scales with the height.
             let tall = footprint_px(d, 2144.0);
             let want = reference_px(d) * 2144.0 / SNOW_PX_REF_HEIGHT;
             assert!(
@@ -264,9 +214,7 @@ mod tests {
         }
     }
 
-    /// The two ends of the law, stated as absolutes so a regression is unmistakable: 14 px at the
-    /// eye, and the 1 px floor from 46.43 yd out — **not** a `1/d` world-space size, which would
-    /// blow up at the eye and vanish in the distance.
+    /// 14 px at the eye, the 1 px floor from 46.43 yd, linear between: not a `1/d` size.
     #[test]
     fn point_size_is_linear_in_distance_not_inverse() {
         assert!((reference_px(0.0) - 14.0).abs() < 1e-6);
@@ -276,9 +224,7 @@ mod tests {
             (reference_px(200.0) - 1.0).abs() < 1e-6,
             "flat past the floor"
         );
-        // A fixed world-size quad's pixel span is ∝ 1/d; this one FALLS OFF LINEARLY, so the
-        // ratio between 10 yd and 40 yd is 11.2/2.8 = 4, not 4 by coincidence of 1/d (which would
-        // also be 4) — pin the shape at a third point where the two laws disagree.
+        // 10 and 40 yd give a ratio of 4 under either law; 25 yd is where the two disagree.
         let (near, far) = (reference_px(10.0), reference_px(40.0));
         assert!((near - 11.2).abs() < 1e-4 && (far - 2.8).abs() < 1e-4);
         assert!(
@@ -288,8 +234,7 @@ mod tests {
         );
     }
 
-    /// Alpha: `clamp01(t − f1)` falling — a 1 s linear fade-IN from spawn — then
-    /// `clamp01(1 − 4·(t − f2))` settled. benilla drew every falling flake at 1.0.
+    /// Alpha `clamp01(t − f1)` while falling, then `clamp01(1 − 4·(t − f2))` settled.
     #[test]
     fn flake_alpha_fades_in_then_out() {
         let view = view();
@@ -321,13 +266,7 @@ mod tests {
         assert!((alpha_of(&[], &settled(0.25)) - 0.0).abs() < 1e-6);
     }
 
-    /// **The precision pin.** The same footprint, with the camera where the game actually puts it:
-    /// Kharanos (~5600 yd out) and the far corner of a 17066-yd map. `EffectVertex::pos` is f32,
-    /// and a near flake's half-extent is ~1.6 mm — 3 ULPs at 5600, under 1 at 17066. Written in
-    /// ABSOLUTE world coordinates (the lane's default, which subtracts the camera only later, on
-    /// the upload copy) a 14 px sprite loses 2–7 px of width and flickers; written camera-relative
-    /// it is exact anywhere. This test fails on the absolute form and passes on the relative one,
-    /// which is the only reason to have it.
+    /// Camera-relative verts keep a near flake's ~1.6 mm half-extent exact far from the origin.
     #[test]
     fn the_footprint_survives_being_far_from_the_world_origin() {
         let proj = Mat4::perspective_rh(FOVY, 16.0 / 9.0, 0.1, 1000.0);
@@ -344,10 +283,8 @@ mod tests {
                     &[],
                     &view,
                 );
-                // The emitted verts are camera-relative, so they project through the same matrix
-                // a camera at the origin would use — that IS the rebase the lane would have done.
-                // Rendered at the era height, so the expected footprint is the reference's own
-                // pixel count (this test is about precision, not about resolution).
+                // Camera-relative verts project as from a camera at the origin; at the era height
+                // the footprint is the reference's own pixel count.
                 let window_y = |p: Vec3| {
                     let clip = proj * p.extend(1.0);
                     (clip.y / clip.w + 1.0) * 0.5 * SNOW_PX_REF_HEIGHT
@@ -362,8 +299,7 @@ mod tests {
         }
     }
 
-    /// A flake behind the eye emits nothing — the pixel↔world map has no meaning at or behind the
-    /// projection plane, and the quad would be mirrored through the camera.
+    /// A flake behind the eye would be mirrored through the camera.
     #[test]
     fn flakes_behind_the_eye_are_dropped() {
         let mut out = Vec::new();
diff --git a/crates/benilla-world/src/weather/precip/wind.rs b/crates/benilla-world/src/weather/precip/wind.rs
index 4868b987..f21a3a8a 100644
--- a/crates/benilla-world/src/weather/precip/wind.rs
+++ b/crates/benilla-world/src/weather/precip/wind.rs
@@ -1,58 +1,38 @@
-//! The weather **wind** — the local player's trailing-average velocity (`0x67c150`) and the
-//! three frames derived from it: the **spawn-slab tilt**, the streak apex tilt, and the mist
-//! spawn yaw. Split from `precip`'s root; the sim/spawn economics stay there.
+//! The weather wind (`0x67c150`) and the rotations it drives: the streak apex tilt, the
+//! spawn-slab tilt and the mist spawn yaw.
 
 use bevy::prelude::*;
 
-/// Streak tilt: `lerp(0°, 45°, sat(|wind.xy|/30))` (`weather_wind_tilt 0x674a70`; 30 @`0x8680f0`,
-/// 45 @`0x8680f4`). Applied to the streak's APEX vertex only (the `M·(2·antiVel)` term).
+/// Streak tilt `lerp(0°, 45°, sat(|wind|/30))` (`0x674a70`; 30 at `0x8680f0`, 45 at `0x8680f4`),
+/// applied to the streak's apex vertex only.
 const WIND_TILT_DIV: f32 = 30.0;
 const WIND_TILT_MAX_DEG: f32 = 45.0;
 
-/// **Spawn-slab tilt**: `α = lerp(0°, 65°, sat(|wind|/18))` (`0x677965`–`0x677a55`). Shares the
-/// ⊥-heading axis with the streak tilt but is a *separate* rotation with its own ramp — steeper
-/// (65° vs 45°) and reaching full tilt at a lower speed (18 vs 30 yd/s). See
-/// [`super::pool::spawn_particle`] for what it does and why its absence was B233.
+/// Spawn-slab tilt `lerp(0°, 65°, sat(speed/18))` (`0x677965`–`0x677a55`): the streak tilt's
+/// axis, but a separate rotation with its own ramp.
 const SLAB_TILT_DIV: f32 = 18.0;
 const SLAB_TILT_MAX_DEG: f32 = 65.0;
 
-/// Wind = the **local player's** trailing-average velocity (`0x67c150`, verified: the list is
-/// per-frame position deltas of object 0x8fe — the player, not the camera — trimmed to a
-/// **~149 ms** window; `wind = Σ(Δpos)/((Σ(Δms)+1)·0.001)`, a true yd/s velocity). Orbiting
-/// the camera therefore does NOT stir the wind. The streak apex tilt and the spawn-box lead
-/// derive from it here.
-///
-/// **The spawn-slab tilt does not.** It keys on `mgr+0x7c`, which merges two sources at one store
-/// (`0x67bf91`): the ridden transport's averaged planar speed when `|mgr+0x5c|² > 2`, else the
-/// local player's own **live** CMovement speed `[[player+0x118]+0x84]`. benilla has no ridden
-/// transports yet, so it is always the second — [`crate::player::Player::planar_speed`], passed
-/// into [`Self::update`]. Averaging it would be wrong in both directions: late to lean in, and
-/// still leaning 150 ms after the player stops.
+/// The player's trailing-average velocity over ~149 ms in yd/s (`0x67c150`), from its own
+/// position deltas, so orbiting the camera does not stir it. The slab tilt keys on `mgr+0x7c`
+/// instead (`0x67bf91`): a ridden transport's averaged speed when `|mgr+0x5c|² > 2`, else the
+/// player's live speed, the only source here.
 #[derive(Resource)]
 pub(crate) struct WeatherWind {
     pub(super) last_pos: Option<Vec3>,
-    /// The trailing window: per-frame (Δseconds, Δpos), trimmed from the head to ≤ 149 ms.
+    /// Per-frame (Δseconds, Δpos), trimmed from the head to 149 ms.
     window: Vec<(f32, Vec3)>,
     /// The windowed planar velocity (Bevy x/z, y forced 0), yd/s.
     pub(super) vel: Vec3,
-    /// The wind heading (WoW frame, `manager+0x78`) — the wind's own azimuth at |wind| ≥ 1, the
-    /// unit's facing below it. Rewritten every frame; it does **not** hold through calm.
+    /// The wind heading (`mgr+0x78`, WoW frame), rewritten every frame.
     heading: f32,
-    /// The same heading as a **Bevy planar unit direction**. Kept alongside the angle rather than
-    /// re-derived from it, because the two angle conventions in this file are 90° apart and only
-    /// compose correctly as a *rotation*: [`heading`] is `atan2(y, x)` in the WoW frame, while
-    /// [`wow_azimuth_to_bevy`] reads its argument as the kernels' `(vx, vy) = (sin a, cos a)`
-    /// pair — i.e. `atan2(x, y)`. [`Self::mist_yaw`] composes them as a rotation and is fine;
-    /// feeding `heading` straight into `wow_azimuth_to_bevy` to get a *direction* would silently
-    /// yield an axis a quarter turn off.
+    /// The heading as a Bevy planar direction: `heading` is `atan2(y, x)` but
+    /// [`wow_azimuth_to_bevy`] reads `atan2(x, y)`, a quarter turn apart.
     heading_dir: Vec3,
-    /// Streak-field tilt (rotates the fall axis toward the motion), from `weather_wind_tilt`.
+    /// The streak apex tilt, leaning the fall axis toward the motion (`0x674a70`).
     pub(super) tilt: Quat,
-    /// The **spawn-slab** tilt — rotates each particle's slab-local offset into the direction of
-    /// travel, so the volume's leading edge is born low and close instead of a flat `z_off` up.
-    /// `α = 65°·sat(live_speed/18)`, linear from zero with **no dead zone** (`0x674ba0` is a plain
-    /// clamped lerp and `0x677965`–`0x677a41` has no branch at all): 9° at a 2.5 yd/s walk, 25.3°
-    /// at a 7 yd/s run, saturated from 18 up. Exactly identity at rest, on the same frame.
+    /// The spawn-slab tilt: linear from zero with no dead zone (`0x674ba0`,
+    /// `0x677965`–`0x677a41`), identity at rest on the same frame.
     pub(super) slab: Quat,
 }
 
@@ -71,14 +51,12 @@ impl Default for WeatherWind {
     }
 }
 
-/// The wind window length: `Σ(Δtick) ≤ 0x95 = 149 ms` (the pre-pass trims the delta list to a
-/// trailing ~149 ms).
+/// The wind window: the delta list is trimmed to `Σ(Δtick) ≤ 0x95` = 149 ms.
 const WIND_WINDOW_S: f32 = 0.149;
 
 impl WeatherWind {
-    /// `pos` — the local player's feet; `facing` — their aim as a Bevy direction (the heading's
-    /// source below 1 yd/s); `live_speed` — their commanded planar speed in yd/s
-    /// ([`crate::player::Player::planar_speed`], the reference's `mgr+0x7c`).
+    /// `pos` is the player's feet, `facing` their aim (the heading below 1 yd/s), `live_speed`
+    /// their commanded planar speed ([`crate::view::Viewer::planar_speed`], `mgr+0x7c`).
     pub(super) fn update(&mut self, pos: Vec3, facing: Vec3, live_speed: f32, dt: f32) {
         if dt <= 0.0 {
             return;
@@ -87,7 +65,7 @@ impl WeatherWind {
             Some(prev) => {
                 let mut d = pos - prev;
                 d.y = 0.0;
-                // A teleport/worldport delta is not wind — restart the window.
+                // A teleport delta is not wind: restart the window.
                 if d.length_squared() > (100.0 * dt).powi(2).max(100.0) {
                     self.window.clear();
                     d = Vec3::ZERO;
@@ -98,22 +76,18 @@ impl WeatherWind {
         };
         self.last_pos = Some(pos);
         self.window.push((dt, delta));
-        // Trim from the head to the trailing window (the reference's Σ(Δtick) ≤ 149 ms).
         let mut total: f32 = self.window.iter().map(|(d, _)| d).sum();
         while self.window.len() > 1 && total - self.window[0].0 >= WIND_WINDOW_S {
             total -= self.window[0].0;
             self.window.remove(0);
         }
         let sum_dpos: Vec3 = self.window.iter().map(|(_, d)| *d).sum();
-        // wind = Σ(Δpos) / ((Σ(Δms)+1)·0.001) — displacement over seconds, true yd/s.
+        // `Σ(Δpos)/((Σ(Δms) + 1)·0.001)`, the reference's formula, its +1 ms included.
         self.vel = sum_dpos / (total.mul_add(1000.0, 1.0) * 0.001);
 
         let mag2 = self.vel.length_squared();
-        // `mgr+0x78` (`0x67be40`): the `|W_xy| ≥ 1` test selects the heading's SOURCE — it does
-        // NOT suppress the write. All three of its legs store `[esi+0x78]` (`0x67bee0`/`0x67bef6`/
-        // `0x67bf02`), and below 1 yd/s the heading is overwritten with the **unit's own facing**
-        // (`0x67beff call [vtbl+0x18]`). The earlier "it HOLDS through calm" reading was wrong —
-        // corrected by wow-re alongside the slab tilt, `wx-snow-placement-law.md` §9.
+        // `mgr+0x78` (`0x67be40`): `|W| ≥ 1` picks the heading's source and every leg stores it
+        // (`0x67bee0`, `0x67bef6`, `0x67bf02`); below 1 yd/s it is the unit's facing (`0x67beff`).
         self.heading_dir = if mag2 >= 1.0 {
             self.vel / mag2.sqrt()
         } else {
@@ -125,10 +99,7 @@ impl WeatherWind {
         // wind_wow = (−dir.z, −dir.x) per the bevy→wow basis; heading = atan2(y, x).
         self.heading = (-self.heading_dir.x).atan2(-self.heading_dir.z);
 
-        // Both rotations turn about `ŷ × ĥ` = `(h.z, 0, −h.x)`: a positive angle about it carries
-        // `ŷ` toward `ĥ` (`R·ŷ = ŷcos + ĥsin`), i.e. leans into the heading. The handedness is
-        // verified for the streak — the apex tips DOWNWIND, rain rushing into a moving player —
-        // and wow-re re-derived it independently for the slab.
+        // Both turn about `ŷ × ĥ = (h.z, 0, −h.x)`, carrying `ŷ` to `ĥ`: the apex tips downwind.
         let lean = |dir: Vec3, speed: f32, div: f32, max_deg: f32| {
             Vec3::new(dir.z, 0.0, -dir.x)
                 .try_normalize()
@@ -139,16 +110,13 @@ impl WeatherWind {
                     )
                 })
         };
-        // The streak apex (`weather_wind_tilt 0x674a70`) keys on the AVERAGED wind, and dies below
-        // |wind|² < 0.001.
+        // The streak apex keys on the averaged wind and dies below `|wind|² < 0.001` (`0x674a70`).
         self.tilt = if mag2 < 0.001 {
             Quat::IDENTITY
         } else {
             lean(self.vel, mag2.sqrt(), WIND_TILT_DIV, WIND_TILT_MAX_DEG)
         };
-        // The slab keys on `mgr+0x7c` — the LIVE commanded speed, not the averaged wind, and not
-        // lagged by the 149 ms window. It is exactly 0 with no direction bit held, so this is
-        // identity at rest with no epsilon needed.
+        // The slab keys on the live speed, exactly 0 with no direction key held: no epsilon needed.
         self.slab = lean(
             self.heading_dir,
             live_speed,
@@ -157,27 +125,20 @@ impl WeatherWind {
         );
     }
 
-    /// The held wind heading (`manager+0x78`, WoW frame). Starts 0 = world north.
+    /// The wind heading (`mgr+0x78`, WoW frame); 0, world north, at start.
     pub(crate) fn heading_wow(&self) -> f32 {
         self.heading
     }
 
-    /// The mist spawn frame: a yaw about the vertical by **+heading**. `mist_spawn 0x67a990`
-    /// feeds `−mgr+0x78` into the Z-rotation builder `0x7bdd60` — a wrapper around `0x7bdb00`,
-    /// which is the NEGATED-handedness family (`M(axis, θ) = R_standard(axis, −θ)`, rf-mist-motion
-    /// Q3) — so the true rotation is `R_standard(+Z_wow, +heading)`, and WoW +Z ↔ Bevy +Y carries
-    /// the angle sign-intact. Net effect: the −1.57 base azimuth (south = anti-north) spins to
-    /// **anti-player-motion** — the stream always blows into a moving player's face, and holds
-    /// that axis when they stop. (The earlier `−heading` transcribed the builder's literal minus
-    /// into Bevy's standard API — a mirror; the director saw it as lateral drift.)
+    /// The mist spawn yaw, `+heading`: `0x67a990` passes `−heading` to `0x7bdd60`, whose core
+    /// `0x7bdb00` negates it, so the −1.57 stream blows into a moving player's face.
     pub(crate) fn mist_yaw(&self) -> Quat {
         Quat::from_rotation_y(self.heading_wow())
     }
 }
 
-/// A WoW-frame horizontal azimuth (the spawn kernels' `(vx, vy) = (mag·sin a, mag·cos a)` pair)
-/// as a Bevy unit direction: `wow (x,y,z) → bevy (−y, z, −x)` ⇒ `(sin a, cos a, 0) →
-/// (−cos a, 0, −sin a)`.
+/// A WoW-frame azimuth, the spawn kernels' `(vx, vy) = (sin a, cos a)`, as a Bevy unit direction:
+/// `wow (x, y, z) → bevy (−y, z, −x)` maps `(sin a, cos a, 0)` to `(−cos a, 0, −sin a)`.
 pub(crate) fn wow_azimuth_to_bevy(a: f32) -> Vec3 {
     Vec3::new(-a.cos(), 0.0, -a.sin())
 }
@@ -185,9 +146,6 @@ pub(crate) fn wow_azimuth_to_bevy(a: f32) -> Vec3 {
 #[cfg(test)]
 mod tests {
     use super::*;
-    /// The inline drift-azimuth mapping must agree with the canonical WoW→Bevy basis —
-    /// `(sin a, cos a, 0)_wow` is the spawn kernels' `(vx, vy)` pair, and the world-fixed
-    /// −1.57 centre only means anything if the frame conversion is the terrain's.
     #[test]
     fn wow_azimuth_matches_coords() {
         for i in 0..16 {
@@ -201,21 +159,13 @@ mod tests {
         }
     }
 
-    /// `mgr+0x78`'s `|W| ≥ 1` test picks the heading's **source**, it does not gate the store
-    /// (`0x67be40`: all three legs write `[esi+0x78]`). Moving, the heading is the wind's own
-    /// azimuth; on stopping it is **overwritten with the unit's facing** rather than held.
-    ///
-    /// This test previously asserted the opposite ("standing still again HOLDS it"). That reading
-    /// was wrong — corrected by wow-re in the same round that found the spawn-slab tilt. The
-    /// visible consequence is the mist frame: it re-aims to where the player is looking when they
-    /// stop, instead of staying pinned to the direction they last ran.
     #[test]
     fn heading_takes_the_facing_below_a_yard_per_second() {
         let dt = 1.0 / 60.0;
         let mut wind = WeatherWind::default();
         assert_eq!(wind.heading_wow(), 0.0);
         assert!(wind.mist_yaw().angle_between(Quat::IDENTITY) < 1e-6);
-        // Walk Bevy +X at 8 yd/s for 0.3 s — the ~149 ms window reads ~8 yd/s.
+        // Walk Bevy +X at 8 yd/s for 0.3 s.
         for i in 0..18 {
             wind.update(Vec3::X * (8.0 * dt * i as f32), Vec3::X, 8.0, dt);
         }
@@ -223,8 +173,7 @@ mod tests {
         // Bevy +X = WoW −Y ⇒ wind_wow = (0, −8) ⇒ heading −π/2.
         let moving = wind.heading_wow();
         assert!((moving + std::f32::consts::FRAC_PI_2).abs() < 1e-3);
-        // Stop, and turn to face Bevy −Z. The wind decays out of the window and the heading
-        // follows the FACING to 0 — it does not stay at the direction of travel.
+        // Stop facing Bevy −Z: the wind decays and the heading follows the facing to 0.
         let last = wind.last_pos.unwrap();
         for _ in 0..60 {
             wind.update(last, Vec3::NEG_Z, 0.0, dt);
@@ -239,10 +188,6 @@ mod tests {
         assert_eq!(wind.slab, Quat::IDENTITY);
     }
 
-    /// The slab's tilt keys on the LIVE commanded speed (`mgr+0x7c`), not the averaged wind: on
-    /// the very first frame of a run it is already at its full angle, and on the first frame of a
-    /// stop it is already flat — while `vel`, the 149 ms average, is still catching up in both
-    /// directions. Keying the tilt off `vel` would lean the slab in late and hold it late.
     #[test]
     fn the_slab_tracks_the_commanded_speed_not_the_averaged_wind() {
         let dt = 1.0 / 60.0;
@@ -270,10 +215,7 @@ mod tests {
         assert_eq!(wind.slab, Quat::IDENTITY, "but the slab is flat that frame");
     }
 
-    /// The mist stream is ANTI-player-motion (`0x67a990`: `−heading` through the negated
-    /// builder `0x7bdd60`→`0x7bdb00` = `R_std(+Z, +heading)`): a player moving along +v gets
-    /// the −1.57-base stream spun to blow along −v — into their face, passing the camera on
-    /// both sides. A sign regression here reads as lateral side-to-side drift.
+    /// The stream opposes the player's motion; a sign regression reads as lateral drift.
     #[test]
     fn mist_stream_blows_anti_motion() {
         let mut wind = WeatherWind::default();
diff --git a/crates/benilla-world/src/wmo_portal/audit/light_probe.rs b/crates/benilla-world/src/wmo_portal/audit/light_probe.rs
index 2de9880b..a7b5797f 100644
--- a/crates/benilla-world/src/wmo_portal/audit/light_probe.rs
+++ b/crates/benilla-world/src/wmo_portal/audit/light_probe.rs
@@ -1,9 +1,6 @@
-//! Entity-LIGHT down-ray probes over the audit harness's placed subjects: which group's face wins
-//! under a standing point, and which light LANE the entity classifier would apply there
-//! (exterior / day-night matte / footprint bake). Born from the 2026-07-13 director report —
-//! corridor characters reading as outdoor-lit, and per-step light flashes on the forge floor —
-//! these print the g00/g11 ownership boundary and the forge's bake/day-night face patchwork as
-//! maps, so a "it looks wrong HERE" becomes a fixture. Shares `Site`/`Subject` with the PVS audits.
+//! Entity-light down-ray probes over the audit harness's placed subjects: which group's face wins
+//! under a standing point, and which light lane the entity classifier applies there (exterior,
+//! day/night matte or footprint bake), printed as maps.
 
 use benilla_assets::coords::{bevy_to_wow, wow_to_bevy};
 use benilla_formats::{load_tile_mesh, mcsh_shadowed_at, open_chain};
@@ -15,11 +12,10 @@ use super::{
     floor_z_at, load_subject, reachable_spots, WmoModel, BLACKSMITH, EXTERIOR, GOLDSHIRE, WALK_STEP,
 };
 
-/// Orientation instrument: dump a tile's WMO placements (model path, uid, position) so a new
-/// [`Site`] can be pinned without hunting. `WOW_DUMP_TILE=map,x,y` (default Azeroth,31,49 —
-/// Goldshire).
+/// Dump a tile's WMO placements (model, uid, position), for pinning a new [`Site`]:
+/// `WOW_DUMP_TILE=map,x,y`, default Goldshire's `Azeroth,31,49`.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
+#[ignore = "instrument: run by hand — cargo test -p benilla-world --lib wmo_portal::audit::light_probe -- --ignored --nocapture"]
 fn dump_tile_placements() {
     let spec = std::env::var("WOW_DUMP_TILE").unwrap_or_else(|_| "Azeroth,31,49".into());
     let parts: Vec<&str> = spec.split(',').collect();
@@ -43,8 +39,7 @@ fn dump_tile_placements() {
     }
 }
 
-/// The raw down-ray winner, BEFORE the EXTERIOR classification hides it: which group's collision
-/// face is nearest below the probe (same candidate walk as `area_down_ray`), or `None` for no face.
+/// The nearest collision face below the probe as `(group, z)`, before the EXTERIOR classification.
 fn raw_downray_winner(model: &WmoModel, probe: [f32; 3]) -> Option<(usize, f32)> {
     let mut best: Option<(usize, f32)> = None;
     for (gi, tris) in model.group_collision_tris.iter().enumerate() {
@@ -59,14 +54,10 @@ fn raw_downray_winner(model: &WmoModel, probe: [f32; 3]) -> Option<(usize, f32)>
     best
 }
 
-/// **The forge-floor lane map** (director report 2026-07-13: crossing the blacksmith's fire-lit
-/// floor flashes the character's lighting per step). Grid the ground storey and print, per cell,
-/// the LANE the entity classifier would apply: a digit = footprint-BAKE (its group, mod 10),
-/// `D` = interior but MOPY&1 (day/night lane), `d` = interior but footprint MISS (day/night lane),
-/// `X` = an EXTERIOR group's face won (exterior lane), `·` = no floor. A patchwork of D/d/digit
-/// across the walkable floor is the per-step lane-flip mechanism made visible.
+/// The forge floor's lane map, per 0.5 yd cell: a digit is a footprint bake (group mod 10), `D`
+/// day/night by MOPY&1, `d` day/night by a footprint miss, `X` an exterior face, `·` no floor.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
+#[ignore = "instrument: run by hand — cargo test -p benilla-world --lib wmo_portal::audit::light_probe -- --ignored --nocapture"]
 fn forge_floor_lane_map() {
     let subject = load_subject(BLACKSMITH.wmo, Some(&BLACKSMITH));
     let model = &subject.model;
@@ -145,10 +136,8 @@ fn forge_floor_lane_map() {
         y += 0.5;
     }
 
-    // The face STACK under a transect across the D/0 patchwork: two coincident-z faces with
-    // different flags = the floor is authored as coplanar LAYERS, and the per-step lane flip is our
-    // nearest-face tie-break landing on either layer — a selection question for the bytes, not a
-    // smoothing one.
+    // The face stack along a transect: coincident-z faces with different flags are coplanar
+    // layers, between which the nearest-face tie-break can land on either.
     println!("\n-- face stacks, y=+0.1, x -2..+4 --");
     let mut x = -2.0f32;
     while x <= 4.0 {
@@ -157,8 +146,7 @@ fn forge_floor_lane_map() {
     }
 }
 
-/// Print every footprint face whose XY projection contains `(x, y)` at `z <= max_z`: z / group /
-/// MOPY flags, nearest first — the coplanar-layer census under one standing point.
+/// Print every footprint face over `(x, y)` at `z <= max_z` (z, group, MOPY flags), highest first.
 fn face_stack(model: &WmoModel, x: f32, y: f32, max_z: f32) {
     let mut hits: Vec<(f32, usize, u8)> = Vec::new();
     for (gi, fp) in model.group_footprints.iter().enumerate() {
@@ -186,14 +174,11 @@ fn face_stack(model: &WmoModel, x: f32, y: f32, max_z: f32) {
     println!("  ({x:+5.1},{y:+5.1})  [{}]", stack.join(" | "));
 }
 
-/// **The entity-light down-ray probe** (director report 2026-07-13: a character in the inn's
-/// entrance corridor lights like OUTDOORS in benilla; the reference lights it as indoors and its
-/// minimap titles the corridor "Lion's Pride Inn"). Sweep every reachable standing point of the
-/// Goldshire inn and print, per point, the raw nearest-face winner (group + z) and the classified
-/// verdict (`area_down_ray` — the entity classifier's exact leg, probe at feet+0.1, terrain-raced).
-/// Prints an XY map around the doorway so the g00/g11 ownership boundary is visible at a glance.
+/// The Goldshire inn: per reachable standing point, the raw nearest-face winner and the verdict
+/// (`area_down_ray` at feet + 0.1). The reference lights the entrance corridor as indoors, and
+/// its minimap names it "Lion's Pride Inn".
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
+#[ignore = "instrument: run by hand — cargo test -p benilla-world --lib wmo_portal::audit::light_probe -- --ignored --nocapture"]
 fn inn_corridor_light_probe() {
     let subject = load_subject(GOLDSHIRE.wmo, Some(&GOLDSHIRE));
     let model = &subject.model;
@@ -213,11 +198,10 @@ fn inn_corridor_light_probe() {
         );
     }
 
-    // Feet-level standing points, from the porch doorway inward (the corridor + taproom + porch).
+    // Feet-level standing points, flooding from the porch doorway.
     let spots = reachable_spots(&subject, [17.0, -2.6, 1.5]);
     println!("reachable spots: {}", spots.len());
 
-    // Per-spot: raw winner vs classified verdict, on the classifier's exact probe (feet + 0.1).
     type SpotRow = ([f32; 3], Option<(usize, f32)>, Option<usize>);
     let mut rows: Vec<SpotRow> = Vec::new();
     for s in &spots {
@@ -236,8 +220,8 @@ fn inn_corridor_light_probe() {
         rows.push((*s, raw, verdict));
     }
 
-    // The doorway XY map: one cell per WALK_STEP, '·' = no spot, 'o' = classified outdoors,
-    // digit = interior verdict's group (mod 10), 'X' = raw winner EXTERIOR-flagged (the demotion).
+    // The doorway map, one cell per WALK_STEP: '·' no spot, 'o' outdoors, a digit the interior
+    // verdict's group (mod 10), 'X' an EXTERIOR-flagged raw winner.
     let (x_lo, x_hi, y_lo, y_hi) = (2.0f32, 26.0f32, -12.0f32, 12.0f32);
     let cols = ((x_hi - x_lo) / WALK_STEP) as usize + 1;
     let rows_n = ((y_hi - y_lo) / WALK_STEP) as usize + 1;
@@ -261,14 +245,14 @@ fn inn_corridor_light_probe() {
         println!("  y{y:+6.1} {}", row.iter().collect::<String>());
     }
 
-    // The corridor's coplanar-layer census: which MOPY layers stack under the walk line — decides
-    // whether the ref's (flag-filtered) sample would bake here rather than day/night.
+    // The MOPY layers under the corridor's walk line, which decide whether the reference's
+    // flag-filtered sample bakes here rather than taking day/night.
     println!("\n-- corridor face stacks, y=-2.6 --");
     for x in [19.0f32, 17.5, 16.0] {
         face_stack(model, x, -2.6, 4.0);
     }
 
-    // The corridor transect the director walks: y ≈ -2.6 (the doorway seed), x from the porch in.
+    // The corridor transect: y ≈ -2.6 (the doorway seed), x from the porch inward.
     println!("\n-- transect y=-2.6, x 22→6 --");
     let mut x = 22.0f32;
     while x >= 6.0 {
@@ -303,8 +287,7 @@ fn inn_corridor_light_probe() {
                     }
                 )
             });
-            // The Bake-vs-DayNight fork the entity classifier takes on an interior verdict: the
-            // footprint (render-mesh MOCV) sample at the same probe.
+            // The classifier's bake or day/night fork: the footprint (MOCV) sample at the probe.
             let lane = if verdict.is_some() {
                 match footprint_sample(model, probe) {
                     Some((fg, mocv, false)) => format!("BAKE g{fg:02} mocv {mocv:?}"),
@@ -314,10 +297,9 @@ fn inn_corridor_light_probe() {
             } else {
                 "exterior".to_string()
             };
-            // The exterior-leg intensity discriminator: the terrain MCSH bit BENEATH the point
-            // (the reference samples it WMO-obliviously even on a porch floor — a building's baked
-            // ground shadow dims a porch character to 0.5; `unit-light-combine-storm.md` a4) — and
-            // the world WoW coords, so a live `.go` probe can stand exactly here.
+            // The terrain MCSH bit under the point, which sets the exterior intensity only over
+            // open terrain (on a WMO face the skip-shadow bit, `0x6a8bc7`, forces 2.5), and the
+            // world coords for a live `.go` to stand here.
             let (mcsh, world) = match subject.placed.as_ref() {
                 Some(p) => {
                     let w = bevy_to_wow(p.world_from_local.transform_point3(wow_to_bevy(probe)));
@@ -340,9 +322,8 @@ fn inn_corridor_light_probe() {
         x -= 0.5;
     }
 
-    // The OUTWARD extension (terrain-only, past the porch steps): where does the inn's baked
-    // ground shadow END along the walk-in line? The reference's exterior intensity ladder
-    // (2.5 path → 0.5 shadowed apron → 1.0 corridor → bake) hangs on this boundary.
+    // Terrain only, past the porch steps: where the inn's ground shadow ends along the walk-in
+    // line (open terrain lights at 2.5, or 0.5 in MCSH shadow).
     println!("\n-- outward y=-2.6, x 22→32 (terrain MCSH) --");
     if let Some(p) = subject.placed.as_ref() {
         let mut x = 22.0f32;
@@ -360,20 +341,13 @@ fn inn_corridor_light_probe() {
     }
 }
 
-/// **The world-point light probe**: classify ANY world position exactly as the entity light
-/// classifier would — per candidate placement in the point's 3×3 tile block, the raw down-ray
-/// winner (group + MOGP flags: EXTERIOR `0x8` / EXTERIOR_LIT `0x40`), the classified verdict,
-/// the footprint fork, plus the terrain race input and the MCSH bit under the point.
-/// `WOW_LIGHT_AT="map,x,y,z"` in raw WoW world coords (the tele table's numbers), so a
-/// director-reported "characters look wrong HERE" becomes one command. Born from the 2026-07-18
-/// report: chars/creatures mis-lit across the city WMOs (Booty Bay / Stormwind / Orgrimmar).
-///
-/// The point is the **down-ray lane's** anchor — a unit's position. A GameObject anchors at its
-/// world bounding-box CENTRE instead (decision 0776), so to read a GameObject's lane, probe at
-/// `z + centre` (`benilla-extract m2coll <model>` prints the box; the two Stratholme portcullises
-/// that found 0776 read `exterior` at their spawn z and `BAKE g02` at their centres).
+/// Classify any world point as the entity light classifier does, per placement in its 3×3 tile
+/// block (the raw winner and its MOGP flags, the verdict, the footprint fork, the MCSH bit), from
+/// `WOW_LIGHT_AT="map,x,y,z"` in raw WoW world coordinates. A GameObject anchors at its world
+/// bounding-box centre, not its position, so probe one at `z + centre`
+/// (`benilla-extract m2coll <model>` prints the box).
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
+#[ignore = "instrument: run by hand — cargo test -p benilla-world --lib wmo_portal::audit::light_probe -- --ignored --nocapture"]
 fn world_point_light_probe() {
     let spec =
         std::env::var("WOW_LIGHT_AT").unwrap_or_else(|_| "Kalimdor,1629.4,-4373.4,31.3".into());
@@ -408,9 +382,8 @@ fn world_point_light_probe() {
          {terrain_wow_z:?}, MCSH shadowed {mcsh:?} ==",
         placements.len()
     );
-    // `WOW_LIGHT_GRID=radius,step`: an MCSH shadow-field map around the point (X north ↑ printed
-    // top-down, Y west ← printed left) — structured building/cliff shadows say the texel decode is
-    // sane; noise says it's broken. `#` shadowed, `.` lit, ` ` no chunk.
+    // `WOW_LIGHT_GRID=radius,step`: the MCSH shadow field around the point, north up and west
+    // left; `#` shadowed, `.` lit, blank no chunk. Structured shadows mean the decode is sane.
     if let Ok(grid) = std::env::var("WOW_LIGHT_GRID") {
         let g: Vec<f32> = grid
             .split(',')
@@ -434,7 +407,7 @@ fn world_point_light_probe() {
             println!("  x{:+7.1} {row}", wx + i as f32 * step);
         }
     }
-    // The classifier's exact probe: the position + the float-safety lift.
+    // The classifier's own probe: the position plus the float-safety lift.
     let probe_world = wow_to_bevy([wx, wy, wz + super::super::interior::POSITION_PROBE_LIFT]);
     let mut subjects: std::collections::HashMap<String, super::Subject> =
         std::collections::HashMap::new();
@@ -450,8 +423,7 @@ fn world_point_light_probe() {
             .entry(w.model.clone())
             .or_insert_with(|| load_subject(&w.model, None));
         let model = &subject.model;
-        // The runtime's own column pre-filter (whole-model face AABB) — a placement that can't
-        // own the column stays silent, so a 9-tile city block prints only the claimants.
+        // The runtime's column pre-filter: only a placement that can own the column prints.
         let owns = model.collision_bounds.is_some_and(|(min, max)| {
             probe_local[0] >= min[0]
                 && probe_local[0] <= max[0]
@@ -498,8 +470,8 @@ fn world_point_light_probe() {
             }
             None => println!("   raw winner: none"),
         }
-        // This placement's own light-lane answer; the runtime arbitrates the NEAREST claim
-        // across all placements (`indoor_verdict_at`), so read the smallest-depth row's lane.
+        // This placement's own lane; the runtime takes the nearest claim across placements
+        // (`indoor_verdict_at`), so read the row with the smallest depth.
         let lane = match light {
             None => "exterior-on-terrain (sun + MCSH intensity)".to_string(),
             Some(c) if c.outdoor => format!(
diff --git a/crates/benilla-world/src/wmo_portal/audit/mod.rs b/crates/benilla-world/src/wmo_portal/audit/mod.rs
index 28a1c043..8f769a8d 100644
--- a/crates/benilla-world/src/wmo_portal/audit/mod.rs
+++ b/crates/benilla-world/src/wmo_portal/audit/mod.rs
@@ -1,32 +1,13 @@
-//! The WMO portal-cull **audit harness** (test-only, `#[ignore]`d — needs the game data): load a real
-//! building *at its real placement*, with the real ADT terrain under it, and sweep the two invariants
-//! the client upholds by construction. Every violation prints as a deterministic repro (exact
-//! model-space coordinates + a per-portal hop trace), so a director-found "it vanishes here" becomes a
-//! fixture instead of a guess.
+//! The WMO portal-cull audit harness (test-only): a real building at its real placement, over its
+//! ADT terrain, swept for the invariants the reference upholds; a violation prints as a repro with
+//! a per-portal hop trace. [`wmo_pvs_audit`]: from reachable standing points, an orbiting
+//! third-person camera that sees the player draws the player's group. [`wmo_outside_audit`]: a
+//! camera in the open air above the terrain is outside, and the exterior shell draws.
 //!
-//! - [`wmo_pvs_audit`] — the **inside** invariant: sweep reachable player standing points × orbiting
-//!   third-person camera positions (line-of-sight enforced against the camera-collision mesh, like the
-//!   real camera's pull-in) and assert **a camera that can see the player draws the player's group**.
-//!   Subject: the Goldshire inn (`WOW_AUDIT_WMO=<internal-path>` overrides it, without a placement).
-//! - [`wmo_outside_audit`] — the **outside** invariant: a camera in the open air above the terrain is
-//!   OUTSIDE, and the building's exterior shell draws. Subject: Fargodeep Mine, whose 21 tunnel groups
-//!   sprawl 150 yd under an Elwynn hillside while its one exterior group covers only the entrance
-//!   mound. Before the terrain race (decision 0258) a camera on the grass above the tunnels seeded
-//!   *inside* one of them and the flood culled the mine out from under the director's cursor. The same
-//!   test asserts the race does not over-fire and seal the mine: a standing point on a tunnel floor,
-//!   under the hill, still reads INSIDE.
-//!
-//! Run: `cargo test -p benilla wmo_ -- --ignored --nocapture`
-//!
-//! [`light_probe`] (sibling module) reuses this harness's placed subjects for the entity-LIGHT
-//! down-ray probes — per-point verdict/lane maps of the inn corridor and the forge floor.
-//!
-//! The inside oracle, refined (round 3): the invariant is **not** upheld by the real client at every
-//! camera position — a camera over a floorless pocket (under an open staircase, beside the basement
-//! ramp) reads "outside" in the real mechanism too, and the interior culls there as a *client*
-//! artifact. So seed-`None` violations are reported as **faithful-cull residue**, not failures; any
-//! seed-`Some` violation — the camera standing in one room while the flood can't reach the player's —
-//! is a hard failure.
+//! The reference itself reads "outside" over a floorless pocket (under an open staircase), so a
+//! violation whose camera seeds no group is faithful-cull residue; one that seeds a group fails.
+//! The asserting audits are data-gated and the instruments are `#[ignore]`d; all of them:
+//! `cargo test -p benilla-world --lib wmo_portal::audit -- --include-ignored --nocapture`
 
 use benilla_assets::coords::{bevy_to_wow, placement_rotation, wow_to_bevy};
 use benilla_assets::WmoGroupNav;
@@ -42,8 +23,8 @@ use super::{compute_pvs, down_ray_seeds, floor_z_at, terrain_z_local, WmoModel,
 mod light_probe;
 mod pin;
 
-/// A building at its real spot on a real map: the model, plus the MODF placement to find (by its
-/// `uniqueId`) in `tile`, whose 3×3 tile block supplies the terrain the down-ray races.
+/// A building at its real spot: the model, and the MODF placement to find by `uniqueId` in `tile`,
+/// whose 3×3 tile block supplies the terrain the down-ray races.
 #[derive(Clone, Copy)]
 struct Site {
     wmo: &'static str,
@@ -52,7 +33,7 @@ struct Site {
     uid: u32,
 }
 
-/// The Goldshire inn — a building standing ON the terrain (0233's repro site).
+/// The Goldshire inn, a building standing on the terrain.
 const GOLDSHIRE: Site = Site {
     wmo: r"World\wmo\Azeroth\Buildings\GoldshireInn\GoldshireInn.wmo",
     map: "Azeroth",
@@ -60,8 +41,7 @@ const GOLDSHIRE: Site = Site {
     uid: 71414,
 };
 
-/// Fargodeep Mine — an interior buried UNDER the terrain (decision 0258's repro site: the director's
-/// "wrongly not visible from the outside at a specific angle", `md_goldmine_varianta`, id 210351).
+/// Fargodeep Mine, an interior buried under the terrain.
 const FARGODEEP: Site = Site {
     wmo: r"world\wmo\dungeon\md_goldmine\md_goldmine_varianta.wmo",
     map: "Azeroth",
@@ -69,9 +49,8 @@ const FARGODEEP: Site = Site {
     uid: 210351,
 };
 
-/// The Deadmines dungeon shell — decision 0692's repro site: the zone-in tunnel (g35) opens through
-/// the swirl-portal doorway into a sealed pocket (g39) floored entirely with DETAIL faces, where the
-/// faithful down-ray legs find nothing and the client blanks the building around its own camera.
+/// The Deadmines shell: the zone-in tunnel (g35) opens through the swirl-portal doorway into a
+/// sealed pocket (g39) floored only with DETAIL faces, where the faithful down-ray legs miss.
 const DEADMINES: Site = Site {
     wmo: r"world\wmo\dungeon\az_deadmines\az_deadmines_b.wmo",
     map: "DeadminesInstance",
@@ -79,7 +58,7 @@ const DEADMINES: Site = Site {
     uid: 170633,
 };
 
-/// The Goldshire blacksmith — the fire-lit forge floor (the 2026-07-13 per-step light-flash report).
+/// The Goldshire blacksmith and its fire-lit forge floor.
 const BLACKSMITH: Site = Site {
     wmo: r"world\wmo\azeroth\buildings\goldshireblacksmith\goldshireblacksmith.wmo",
     map: "Azeroth",
@@ -87,8 +66,8 @@ const BLACKSMITH: Site = Site {
     uid: 96048,
 };
 
-/// Undercity — B26's site: 200+ groups under Tirisfal, whose one reported doorway culls the room on
-/// the far side from *both* sides of the arch (`.go xyz 1558.66 415.39 -62.16 0`).
+/// Undercity: 200+ groups under Tirisfal, and the pin probe's default subject, a doorway at
+/// `.go xyz 1558.66 415.39 -62.16 0`.
 const UNDERCITY: Site = Site {
     wmo: r"world\wmo\lorderon\undercity\undercity.wmo",
     map: "Azeroth",
@@ -96,16 +75,13 @@ const UNDERCITY: Site = Site {
     uid: 239598,
 };
 
-/// Ironforge — B65's site: the lava chasm under the Great Forge walkways. The walkable metal
-/// grates at lava level (world z≈421, e.g. `.go xyz -4845 -995 421 0`) live in cavern group g89
-/// (one portal, p114→g91); a camera over a grate/bed column seeds that group and the scene draws,
-/// while a column with nothing walkable below (the shaft-mouth sliver, the moat's bed gaps) reads
-/// "outside" and blanks the interior — which decision 1096 pins as the CLIENT'S OWN behaviour
-/// (wow-re `wmo-downray-liquid-audit.md`: no liquid leg, no fallback; the asset's patchy beds are
-/// the only thing keeping retail drawn over lava). The 2026-08-07 pins: `WOW_PIN_EYE=-4990,-960,470`
-/// reproduces a faithful blank column; `WOW_PIN_EYE=-4830,-1090,480` seeds g91 and draws; the
-/// still-open half of B65 (partial grate loss from seeded rim poses) is 1096's "NOT settled" leaf.
-#[allow(dead_code)] // pinned for `WOW_PIN_*` runs: the B65 repro coordinates live here
+/// Ironforge's lava chasm under the Great Forge. The grates at lava level (world z≈421,
+/// `.go xyz -4845 -995 421 0`) are cavern group g89 (one portal, p114 to g91); a camera over a
+/// column with nothing walkable below reads outside and blanks the interior, as the reference
+/// does: its down-ray's liquid cast is a dead edge here (`0x6be345`) and a miss retries nothing
+/// (`0x682207`). `WOW_PIN_EYE=-4990,-960,470` is such a column; `WOW_PIN_EYE=-4830,-1090,480`
+/// seeds g91 and draws.
+#[allow(dead_code)] // aimed at by `WOW_PIN_*` runs
 const IRONFORGE: Site = Site {
     wmo: r"world\wmo\khazmodan\cities\ironforge\ironforge.wmo",
     map: "Azeroth",
@@ -113,9 +89,8 @@ const IRONFORGE: Site = Site {
     uid: 7706,
 };
 
-/// Shadowfang Keep — B335's site: the courtyard whose far doorways read as a flat blue-cyan wash.
-/// Its two courtyard groups (g38, g72) are EXTERIOR_LIT (`0x40`) while the rooms behind their
-/// arches (g61, g60) are true interiors, which is the shape the interior-fog chain gate turns on.
+/// Shadowfang Keep: two EXTERIOR_LIT (`0x40`) courtyard groups (g38, g72) with true interiors
+/// behind their arches (g61, g60), the shape the interior-fog chain gate turns on.
 /// `.go xyz -214.30 2211.84 79.78 33` looks at the arches; `-213.90 2236.15 79.78` is inside g61.
 const SHADOWFANG: Site = Site {
     wmo: r"world\wmo\dungeon\ld_shadowfang\ld_shadowfanginterior.wmo",
@@ -124,11 +99,9 @@ const SHADOWFANG: Site = Site {
     uid: 218202,
 };
 
-/// Darnassus — the 2026-09-02 report's site: one placement, 104 groups, **50 of them exterior**, and
-/// the city's outdoor areas stitched to each other and to every shop by portals. That shape is what
-/// makes it the discriminating subject for Pass 2: standing in a shop, the doorway admits the one
-/// outdoor group beyond it, and everything else the director can see through that doorway is reached
-/// only by WALKING ON from there (decision 1853). `.go xyz 10188.36 2348.35 1328.96 1` is the pin.
+/// Darnassus: one placement, 104 groups, 50 of them exterior, its outdoor areas portal-linked to
+/// each other and to every shop, so from a shop most of the city is reached only by Pass 2 walking
+/// on past the doorway's outdoor group. `.go xyz 10188.36 2348.35 1328.96 1` is the pin.
 const DARNASSUS: Site = Site {
     wmo: r"world\wmo\kalimdor\darnassis\darnassis.wmo",
     map: "Kalimdor",
@@ -136,11 +109,10 @@ const DARNASSUS: Site = Site {
     uid: 352798,
 };
 
-/// Eye height above a floor point for both the standing player and the seated camera samples.
+/// Eye height above a floor point, for the player and the camera samples.
 const EYE_HEIGHT: f32 = 1.7;
 
-/// The subject model + the camera-collision mesh (for the LOS pull-in) + the flattened
-/// walking-collision mesh (for the reachability flood's headroom probes) + the real placement.
+/// The subject model, its camera and flattened walking collision meshes, and its placement.
 struct Subject {
     model: WmoModel,
     cam_pos: Vec<[f32; 3]>,
@@ -148,12 +120,11 @@ struct Subject {
     walk_pos: Vec<[f32; 3]>,
     walk_idx: Vec<u32>,
     names: Vec<String>,
-    /// `None` for a `WOW_AUDIT_WMO` override — then the down-ray runs with no terrain leg.
+    /// `None` for a `WOW_AUDIT_WMO` override, whose down-ray has no terrain leg.
     placed: Option<Placed>,
 }
 
-/// A subject's placement in the world, and the ADT terrain around it — everything the terrain leg of
-/// the down-ray needs, in exactly the frames the runtime uses.
+/// A subject's placement and the ADT terrain around it, in the frames the runtime uses.
 struct Placed {
     world_from_local: Affine3A,
     local_from_world: Affine3A,
@@ -161,8 +132,8 @@ struct Placed {
 }
 
 impl Subject {
-    /// The terrain surface under a model-space eye, in model-space `z` — what `compute_wmo_pvs` hands
-    /// [`down_ray_seeds`] each frame. `None` with no placement, off-tile, or over an MCNK hole.
+    /// The terrain under a model-space eye as model-space `z`, as the runtime hands it to
+    /// [`down_ray_seeds`]; `None` with no placement, off-tile or over an MCNK hole.
     fn terrain_z(&self, eye_local: [f32; 3]) -> Option<f32> {
         let p = self.placed.as_ref()?;
         let eye_world = p.world_from_local.transform_point3(wow_to_bevy(eye_local));
@@ -177,10 +148,8 @@ impl Subject {
     }
 }
 
-/// Load `internal` from the local game data, mirroring the asset loader's nav/collision construction
-/// (`benilla-assets::wmo`): MOGI bounds, MOGP flags/portal-ref spans, and the per-group
-/// walking-collision face set (every non-DETAIL face — the down-ray's Leg A). With a [`Site`], also
-/// resolve the MODF placement and load the terrain the down-ray races.
+/// Load `internal` from the install as the asset loader builds a WMO's nav and collision
+/// (`benilla-assets::wmo`); with a [`Site`], also its placement and the terrain the down-ray races.
 fn load_subject(internal: &str, site: Option<&Site>) -> Subject {
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let mut chain = open_chain(&data).expect("open MPQ chain");
@@ -224,8 +193,7 @@ fn load_subject(internal: &str, site: Option<&Site>) -> Subject {
         let Ok(gbytes) = chain.read(&format!("{stem}_{gi:03}.wmo")) else {
             continue;
         };
-        // The group's MLIQ surface, exactly as the asset loader stores it — the down-ray's liquid
-        // leg (B65) needs it, so the pin probe must carry it too or an over-lava eye can't replay.
+        // The MLIQ surface as the asset loader stores it, for the down-ray's liquid leg.
         group_liquids[gi] = benilla_formats::wmo_group_liquid_mesh(&gbytes);
         group_footprints[gi] = wmo_group_footprint_tris(&gbytes);
         if let (Some(h), Some(nav)) = (wmo_group_header(&gbytes), group_nav.get_mut(gi)) {
@@ -236,9 +204,8 @@ fn load_subject(internal: &str, site: Option<&Site>) -> Subject {
             nav.fog_indices = h.fog_indices;
         }
         accumulate_wmo_group_camera_collision(&gbytes, &mut cam_pos, &mut cam_idx);
-        // The down-ray's Leg A face set — the per-group walking-collision gather (every non-DETAIL
-        // face, no orientation filter), exactly what the asset loader now stores. The flat walk mesh
-        // (headroom probes) is fed from the same buffers.
+        // Leg A's face set, as the asset loader stores it: every non-DETAIL face, no orientation
+        // filter. The flat walk mesh is fed from the same buffers.
         let mut cp: Vec<[f32; 3]> = Vec::new();
         let mut ci: Vec<u32> = Vec::new();
         accumulate_wmo_group_collision(&gbytes, &mut cp, &mut ci);
@@ -254,8 +221,7 @@ fn load_subject(internal: &str, site: Option<&Site>) -> Subject {
         let base = walk_pos.len() as u32;
         walk_pos.extend_from_slice(&cp);
         walk_idx.extend(ci.iter().map(|i| i + base));
-        // Leg C's fallback set — the camera-only complement (DETAIL set, NOCAMCOLLIDE clear),
-        // exactly as the asset loader stores it (decision 0692).
+        // Leg C's fallback set: the camera-only faces (DETAIL set, NOCAMCOLLIDE clear).
         let (mut dp, mut di): (Vec<[f32; 3]>, Vec<u32>) = (Vec::new(), Vec::new());
         benilla_formats::accumulate_wmo_group_camera_only_collision(&gbytes, &mut dp, &mut di);
         for t in di.as_chunks::<3>().0 {
@@ -319,9 +285,8 @@ fn load_subject(internal: &str, site: Option<&Site>) -> Subject {
     }
 }
 
-/// Resolve a [`Site`]'s MODF placement (by `uniqueId`) and gather the terrain of its 3×3 tile block —
-/// a big building's footprint, and any camera orbiting it, can leave the centre tile. The transform is
-/// built exactly as the streamer builds it (`terrain_stream`: `wow_to_bevy` position × MODF Euler).
+/// Resolve a [`Site`]'s MODF placement and gather its 3×3 tile block's terrain, with the transform
+/// built as the streamer builds it (`wow_to_bevy` position, MODF Euler rotation).
 fn load_placement(chain: &mut benilla_formats::Chain, site: &Site) -> Placed {
     let (cx, cy) = site.tile;
     let mut chunks = Vec::new();
@@ -357,18 +322,16 @@ fn load_placement(chain: &mut benilla_formats::Chain, site: &Site) -> Placed {
 
 /// The cell size of the reachability flood's walk grid (yd).
 const WALK_STEP: f32 = 0.5;
-/// Max step-up per grid step — stairs are ~0.4-yd risers; a player mounts them, not walls.
+/// Max step-up per cell: stairs are ~0.4 yd risers.
 const MAX_CLIMB: f32 = 1.05;
-/// Max step-down per grid step (walking down stairs / small ledges; falls are not walking).
+/// Max step-down per cell; a fall is not walking.
 const MAX_DROP: f32 = 2.5;
-/// Required clearance above a standing point (yd) — the player capsule.
+/// Clearance above a standing point (yd), the player capsule.
 const HEADROOM: f32 = 1.8;
 
-/// **Reachable** standing points: a BFS over a [`WALK_STEP`] grid across the walking-collision faces,
-/// seeded at `start` — only spots a player can actually walk to, stepping at most [`MAX_CLIMB`] up /
-/// [`MAX_DROP`] down per cell with [`HEADROOM`] clear above. This kills the phantom "standing spots"
-/// (beam tops, doorway lintels, sealed roof-void ceilings) that the raw face-centroid sweep produced —
-/// every violation from these spots is a place the director could actually stand.
+/// The standing points a player can walk to from `start`: a flood over a [`WALK_STEP`] grid of
+/// walking-collision faces, at most [`MAX_CLIMB`] up or [`MAX_DROP`] down per cell with
+/// [`HEADROOM`] clear, so beam tops and lintels never count.
 fn reachable_spots(subject: &Subject, start: [f32; 3]) -> Vec<[f32; 3]> {
     let model = &subject.model;
     let key = |x: f32, y: f32, z: f32| {
@@ -378,7 +341,7 @@ fn reachable_spots(subject: &Subject, start: [f32; 3]) -> Vec<[f32; 3]> {
             (z / WALK_STEP).round() as i32,
         )
     };
-    // Ground the seed onto the nearest face below it.
+    // The highest face between `below` and `above`.
     let ground = |x: f32, y: f32, below: f32, above: f32| -> Option<f32> {
         model
             .group_collision_tris
@@ -400,10 +363,8 @@ fn reachable_spots(subject: &Subject, start: [f32; 3]) -> Vec<[f32; 3]> {
         )
         .is_none()
     };
-    // No walking through walls: the chest-height segment between the two cells must be clear of the
-    // walking mesh (risers sit below it, door lintels above; a wall or rail blocks it). Without this
-    // the flood leaks into sealed voids wherever floor levels align across a wall (the porch roof
-    // void off the stair landing — the phantom family the flood exists to kill).
+    // No walking through walls: the chest-height segment between two cells must miss the walking
+    // mesh (risers sit below it, lintels above), or the flood leaks into sealed voids.
     let clear_between = |x: f32, y: f32, z: f32, nx: f32, ny: f32, nz: f32| {
         let h = z.max(nz) + 0.6;
         let (dx, dy) = (nx - x, ny - y);
@@ -448,8 +409,7 @@ fn reachable_spots(subject: &Subject, start: [f32; 3]) -> Vec<[f32; 3]> {
     spots
 }
 
-/// Möller–Trumbore, WoW model space: nearest hit `t` along `dir` (unit) from `orig`, within `max_t`,
-/// against an indexed triangle mesh.
+/// Möller–Trumbore in WoW model space: the nearest hit `t` along unit `dir` within `max_t`.
 fn nearest_hit_mesh(
     positions: &[[f32; 3]],
     indices: &[u32],
@@ -505,8 +465,7 @@ fn nearest_hit(subject: &Subject, orig: [f32; 3], dir: [f32; 3], max_t: f32) ->
     nearest_hit_mesh(&subject.cam_pos, &subject.cam_idx, orig, dir, max_t)
 }
 
-/// The audit's camera: perspective * look-at, both in Bevy axes (`world_from_local` = identity, so
-/// world space == `wow_to_bevy(model space)` — the same convention `compute_pvs` projects with).
+/// The audit's camera, in Bevy axes with an identity placement, as `compute_pvs` projects.
 fn clip_from_world(eye_local: [f32; 3], target_local: [f32; 3]) -> Mat4 {
     let eye = wow_to_bevy(eye_local);
     let target = wow_to_bevy(target_local);
@@ -515,7 +474,7 @@ fn clip_from_world(eye_local: [f32; 3], target_local: [f32; 3]) -> Mat4 {
     proj * view
 }
 
-/// One flood re-run with the shared [`TraceLog`] recorder — the diagnosis attached to a violation.
+/// A flood re-run with the [`TraceLog`] recorder, printed with a violation.
 fn trace_flood(subject: &Subject, eye_local: [f32; 3], clip: &Mat4) {
     let terrain = subject.terrain_z(eye_local);
     let mut log = super::probe::TraceLog::new(&subject.model, eye_local, terrain);
@@ -530,30 +489,18 @@ fn trace_flood(subject: &Subject, eye_local: [f32; 3], clip: &Mat4) {
     print!("{}", log.text);
 }
 
-/// Sampling step (yd) of the outside audit's world-column grid, and the camera heights above the
-/// terrain surface it probes — a third-person camera's whole vertical band over open ground.
+/// The outside audit's column step (yd), and its camera heights above the ground.
 const OUTSIDE_STEP: f32 = 3.0;
 const OUTSIDE_HEIGHTS: [f32; 4] = [0.5, 1.7, 4.0, 9.0];
 
-/// **The outside invariant.** Over a column where the whole building lies **below the ground surface**,
-/// a camera anywhere above that ground is outside it — and the building's exterior shell therefore
-/// draws. Fargodeep Mine is the extreme shape: a 150-yd tunnel network buried under an Elwynn hillside,
-/// with a single exterior group covering only the entrance mound. Without the terrain race, every camera
-/// column over the hill seeds *inside* a tunnel, the flood starts in a room the camera cannot see out
-/// of, and the mine's entrance — the only part of it above ground — is culled (decision 0258).
-///
-/// The oracle is deliberately restricted to **buried** columns, because "the eye is above the terrain"
-/// alone does not mean "the eye is outdoors": a WMO surface can sit above the ADT ground (the mine's own
-/// entrance mound stands ~9 yd proud of it; an inn's floor is a foot above it), and an eye over such a
-/// surface reads INSIDE in the real client too — its WMO hit is genuinely nearer than the terrain's. The
-/// mound columns are covered by the second class below, through the exterior-group rule.
-///
-/// The last section is the guard against the race *over*-firing and sealing the mine: a player standing
-/// on a tunnel floor is below the hill's surface, so the terrain is not on their down-segment at all,
-/// and the WMO must still win the column.
+/// Over a column where the whole building lies below the ground, a camera anywhere above the
+/// ground is outside, so the exterior shell draws; Fargodeep Mine's 150 yd of tunnels lie under a
+/// hillside, its one exterior group over the entrance mound. Where a WMO surface stands above the
+/// ground, an eye over it reads inside in the reference too, so there only an exterior group's
+/// column is asserted. A standing point on a tunnel floor, under the hill, still reads inside.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
 fn wmo_outside_audit() {
+    let _data = benilla_formats::wow_data_or_skip!();
     let subject = load_subject(FARGODEEP.wmo, Some(&FARGODEEP));
     let model = &subject.model;
     let placed = subject.placed.as_ref().expect("placed");
@@ -562,7 +509,6 @@ fn wmo_outside_audit() {
         .collect();
     assert!(!exteriors.is_empty(), "subject has no exterior group");
 
-    // The model's XY extent, walked as a world grid: the columns of hillside a camera can stand over.
     let (mut lo, mut hi) = ([f32::INFINITY; 2], [f32::NEG_INFINITY; 2]);
     for g in &model.group_bounds {
         for a in 0..2 {
@@ -583,7 +529,7 @@ fn wmo_outside_audit() {
                 origin[0] + i as f32 * OUTSIDE_STEP,
                 origin[1] + j as f32 * OUTSIDE_STEP,
             );
-            // The ground here, if this column carries terrain at all (a hole hands it to the WMO).
+            // The ground here, if the column has terrain (a hole hands it to the WMO).
             let Some(tz) = terrain_height_at(&placed.chunks, [wx, wy, 0.0]) else {
                 continue;
             };
@@ -598,9 +544,8 @@ fn wmo_outside_audit() {
                 continue;
             };
             if top_z >= probe[2] {
-                // A WMO surface stands above the ground here (the entrance mound). Only the columns
-                // whose topmost surface is an EXTERIOR group are asserted — an eye over an *indoor*
-                // surface that pokes above ground reads inside in the client too, faithfully.
+                // A WMO surface above the ground (the entrance mound): asserted only when it is an
+                // exterior group's, since over an indoor one the reference reads inside too.
                 proud += 1;
                 if model.group_nav[top_g].flags & EXTERIOR == 0 {
                     continue;
@@ -644,8 +589,8 @@ fn wmo_outside_audit() {
     }
     let inside_violations = violations;
 
-    // The race must not seal the mine: ground a standing point on each interior group's own collision
-    // and assert the eye there still reads INSIDE (the hill's surface is above it, off the segment).
+    // The race must not seal the mine: an eye standing on each interior group's own floor, under
+    // the hill's surface, still reads inside.
     let mut sealed: Vec<usize> = Vec::new();
     let mut probed = 0u32;
     for gi in 0..model.group_nav.len() {
@@ -688,9 +633,7 @@ fn wmo_outside_audit() {
     );
 }
 
-/// The building's topmost collision face over model column `(x, y)`: `(group, z)` of the highest face
-/// any group carries there, or `None` if no group's mesh covers the column. Used to tell a *buried*
-/// column (whole building below ground) from one where a WMO surface stands proud of the terrain.
+/// The highest collision face over model column `(x, y)`, as `(group, z)`.
 fn column_top(model: &WmoModel, x: f32, y: f32) -> Option<(usize, f32)> {
     let mut best: Option<(usize, f32)> = None;
     for (gi, tris) in model.group_collision_tris.iter().enumerate() {
@@ -705,9 +648,8 @@ fn column_top(model: &WmoModel, x: f32, y: f32) -> Option<(usize, f32)> {
     best
 }
 
-/// A standing eye inside group `gi`: drop onto the highest of the group's own collision faces beneath
-/// its face-vertex centroid column, then stand [`EYE_HEIGHT`] above it. `None` when the centroid column
-/// has no face under it (a ring-shaped room) — the caller skips that group.
+/// A standing eye in group `gi`: [`EYE_HEIGHT`] above the highest of its own faces under its
+/// vertex centroid; `None` when no face is there (a ring-shaped room).
 fn interior_standing_eye(model: &WmoModel, gi: usize) -> Option<[f32; 3]> {
     let tris = model.group_collision_tris.get(gi)?;
     if tris.is_empty() {
@@ -732,9 +674,9 @@ fn interior_standing_eye(model: &WmoModel, gi: usize) -> Option<[f32; 3]> {
 }
 
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
 fn wmo_pvs_audit() {
-    // The env override names a subject with no known placement — then there is no terrain leg.
+    let _data = benilla_formats::wow_data_or_skip!();
+    // An override subject has no known placement, so no terrain leg.
     let over = std::env::var("WOW_AUDIT_WMO").ok();
     let internal = over.clone().unwrap_or_else(|| GOLDSHIRE.wmo.to_string());
     let subject = load_subject(&internal, over.is_none().then_some(&GOLDSHIRE));
@@ -777,8 +719,7 @@ fn wmo_pvs_audit() {
     }
 
     // --- the sweep ---
-    // Standing spots come from the reachability flood, seeded at the porch doorway (override with
-    // `WOW_AUDIT_START=x,y,z` for another subject) — every spot is somewhere a player can walk.
+    // Standing spots flood from the porch doorway, or from `WOW_AUDIT_START=x,y,z`.
     let start: [f32; 3] = std::env::var("WOW_AUDIT_START")
         .ok()
         .and_then(|s| {
@@ -797,7 +738,7 @@ fn wmo_pvs_audit() {
         for c in spots.iter().step_by(5) {
             let player = [c[0], c[1], c[2] + EYE_HEIGHT];
             let Some(gp) = subject.seeds(player).in_group else {
-                continue; // outside / exterior standing spot — no interior invariant to hold
+                continue; // an outdoor standing spot: no interior invariant to hold
             };
             for az_i in 0..8 {
                 let az = az_i as f32 * std::f32::consts::TAU / 8.0;
@@ -805,7 +746,7 @@ fn wmo_pvs_audit() {
                     let el = elev_deg.to_radians();
                     let dir = [az.cos() * el.cos(), az.sin() * el.cos(), el.sin()];
                     for radius in [2.0f32, 4.5, 8.0] {
-                        // LOS pull-in: the camera never ends up behind a wall it can't see through.
+                        // LOS pull-in: the camera never ends up behind a wall.
                         let reach = nearest_hit(&subject, player, dir, radius)
                             .map_or(radius, |t| (t - 0.3).max(t * 0.5));
                         let eye = [
@@ -866,8 +807,7 @@ fn wmo_pvs_audit() {
         trace_flood(&subject, *eye, &clip_from_world(*eye, *player));
     }
     println!("\ngroup names: {:?}", subject.names);
-    // Seed-None residue is the real client's own cull at that camera spot (module doc); only a
-    // seed-Some violation is ours.
+    // A camera that seeds no group culls in the reference too; only a seeded one is ours.
     let hard: Vec<_> = violations
         .iter()
         .filter(|(_, _, _, gc)| gc.is_some())
@@ -884,15 +824,13 @@ fn wmo_pvs_audit() {
     );
 }
 
-/// Decision 0692's repro, on the shipped data: the camera pulled back from the Deadmines zone-in
-/// crosses the swirl-portal doorway into the sealed g35/g39 pocket, whose floor is entirely DETAIL
-/// faces — camera collision holds the eye there (every back-hemisphere ray hits a camera face within
-/// ~16 yd) while Legs A+B find nothing, and the client's own verdict blanks the building around its
-/// own camera. Leg C must name the pocket's room; the terrain race must still own the columns where
-/// its answer is right (the hilltop lid ~272 yd above the tunnel).
+/// A camera pulled back from the Deadmines zone-in crosses the swirl-portal doorway into the sealed
+/// g35/g39 pocket, floored only with DETAIL faces: camera collision holds the eye there while Legs
+/// A and B find nothing, and the reference blanks the building. Leg C, ours, must name the pocket's
+/// room, and the terrain race must still own the columns above the hilltop lid, ~272 yd up.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
 fn wmo_camera_void_audit() {
+    let _data = benilla_formats::wow_data_or_skip!();
     let subject = load_subject(DEADMINES.wmo, Some(&DEADMINES));
     // The zone-in head: areatrigger 78's destination (-14.5732, -385.475, 62.4561) + head height,
     // mapped through the MODF placement (uid 170633) into B-local space.
@@ -902,8 +840,8 @@ fn wmo_camera_void_audit() {
         Some(35),
         "the entrance tunnel must stay Leg A's answer — Leg C never touches a faithful verdict"
     );
-    // Eyes along the swept camera path behind the head: level-back at 8/12/13.2 yd and the raised
-    // zoom arc. All sit past the last walking-gather floor; each must still name the pocket's room.
+    // Eyes on the camera path behind the head, level at 8/12/13.2 yd and on the raised zoom arc,
+    // all past the last walking-gather floor.
     for eye in [
         [260.6, -137.3, 34.6],
         [256.6, -137.4, 34.6],
@@ -920,8 +858,7 @@ fn wmo_camera_void_audit() {
         );
         assert!(s.across.is_none(), "Leg C seeds a single root");
     }
-    // Above the hilltop lid the terrain race owns the column: an eye over open ground must stay
-    // outside — the fallback's terrain gate keeps the divergence out of the client's right answers.
+    // Above the hilltop lid the terrain is below the eye, so the race owns the column, not Leg C.
     assert_eq!(
         subject.seeds([255.4, -137.4, 280.0]).in_group,
         None,
@@ -929,23 +866,16 @@ fn wmo_camera_void_audit() {
     );
 }
 
-/// **The Deeprun Tram's undersea tube — the map with no `Light.dbc` row.**
-///
-/// Map 369 carries no `Light.dbc` sphere at all (not even a falloff-0 global, unlike maps 0/1), so
-/// every scrap of its atmosphere has to come from the building: the root's MFOG. `Subway.wmo`
-/// authors four records, and the undersea stretch is record **2** — pos `(25, -1256, -117)`,
-/// radii 154/247, colour RGB(30,53,100), end 236.1 yd, start scalar 0.05. The camera's group
-/// there (`Subway_002`, flags `0x2805` ⇒ INTERIOR) names it: `fogIds = (2,0,0,0)`.
-///
-/// This pins the two links that have to hold for that fog to reach the frame — the down-ray seed
-/// claiming the tunnel group, and the selector resolving record 2 over the record-0 seed — on a
-/// **global (WDT `MODF`) WMO**, the placement shape the rest of this module's sites never exercise.
+/// The Deeprun Tram (map 369) has no `Light.dbc` sphere, not even a global one, so its undersea
+/// atmosphere is the root's MFOG record 2 (colour 30,53,100, end 236.1 yd), named by the tunnel
+/// group `Subway_002` (flags `0x2805`, `fogIds = (2,0,0,0)`). Pins the down-ray claiming that group
+/// and the selector resolving record 2, on a global (WDT `MODF`) WMO.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
 fn deeprun_tram_undersea_claims_its_own_mfog() {
+    let _data = benilla_formats::wow_data_or_skip!();
     let subject = load_subject(r"World\wmo\Dungeon\AZ_Subway\Subway.wmo", None);
     let model = &subject.model;
-    // The undersea tunnel group, by its authored fog list rather than a hardcoded index.
+    // The undersea tunnel group; the asserts below check its fog list and flags.
     let gi = 2usize;
     let nav = &model.group_nav[gi];
     assert_eq!(
diff --git a/crates/benilla-world/src/wmo_portal/audit/pin.rs b/crates/benilla-world/src/wmo_portal/audit/pin.rs
index 9f9e10aa..b5fc4139 100644
--- a/crates/benilla-world/src/wmo_portal/audit/pin.rs
+++ b/crates/benilla-world/src/wmo_portal/audit/pin.rs
@@ -1,8 +1,6 @@
-//! **The pin probe** — a director's `.go xyz` / `/shot` report, replayed offline through the real
-//! flood. The sibling sweeps in [`super`] ask "does the invariant hold anywhere in this building";
-//! this asks "what happened at exactly *that* spot", which is the question a bug report actually
-//! poses. It reuses the harness's placed subjects and the same [`TraceLog`](super::super::probe)
-//! recorder the in-client dump button writes, so there is no second flood to drift.
+//! The pin probe: one reported spot replayed offline through the real flood, with the same
+//! [`TraceLog`](super::super::probe) recorder as the in-client dump button; and the site
+//! regressions pinned at such spots.
 
 use benilla_assets::coords::{bevy_to_wow, wow_to_bevy};
 use bevy::math::{Mat4, Vec3};
@@ -14,9 +12,7 @@ use super::{
     IRONFORGE, SHADOWFANG, UNDERCITY,
 };
 
-/// The named subjects `WOW_PIN_SITE` selects — every [`Site`] the harness carries, so a report at a
-/// building we have already stood in is one word rather than four env vars (whose `WOW_PIN_WMO`
-/// backslash quoting is its own trap). Unknown names list themselves.
+/// The subjects `WOW_PIN_SITE` names: every [`Site`] the harness carries.
 const NAMED_SITES: &[(&str, Site)] = &[
     ("goldshire", GOLDSHIRE),
     ("fargodeep", FARGODEEP),
@@ -28,9 +24,8 @@ const NAMED_SITES: &[(&str, Site)] = &[
     ("darnassus", DARNASSUS),
 ];
 
-/// The pin family's shared env targeting: `WOW_PIN_SITE=<name>` picks a [`NAMED_SITES`] subject
-/// (default [`UNDERCITY`]), and `WOW_PIN_WMO`/`_MAP`/`_TILE`/`_UID` each override one field of it —
-/// so an unnamed building still works, and a named one needs no quoting.
+/// `WOW_PIN_SITE=<name>` picks a [`NAMED_SITES`] subject (default [`UNDERCITY`]), and
+/// `WOW_PIN_WMO`, `_MAP`, `_TILE` and `_UID` each override one field of it.
 fn site_from_env() -> Site {
     let base = match std::env::var("WOW_PIN_SITE") {
         Ok(name) => {
@@ -65,12 +60,10 @@ fn site_from_env() -> Site {
     }
 }
 
-/// **The group census** — the pin probe's gazetteer: every group's flags, portal-edge count, and
-/// bbox in BOTH frames (model-local and WoW world, via the same placement transform the pin uses),
-/// so a "which group is that thing on my screen" question becomes a grep instead of a guess. Same
-/// `WOW_PIN_*` targeting as the pin probe.
+/// The group census: every group's flags, portal edges and bbox in the model and world frames,
+/// aimed by the same `WOW_PIN_*` variables as the pin probe.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
+#[ignore = "instrument: aimed by WOW_PIN_*, run by hand — cargo test -p benilla-world --lib wmo_portal::audit::pin -- --ignored --nocapture"]
 fn wmo_group_census() {
     let site = site_from_env();
     let subject = load_subject(site.wmo, Some(&site));
@@ -78,8 +71,7 @@ fn wmo_group_census() {
         .placed
         .as_ref()
         .expect("the census needs a placement");
-    // The MLIQ leg the harness's nav skips: re-read each group file for its liquid grid, so the
-    // census can say "this group owns the lava" (local-space z range of its wet vertices).
+    // Each group's liquid, read from its file: the local z range of its liquid vertices.
     let data = benilla_formats::wow_data().expect("no WoW install found (set $WOW_DATA)");
     let chain = benilla_formats::open_chain(&data).expect("open MPQ chain (set WOW_DATA)");
     let stem = site.wmo.strip_suffix(".wmo").unwrap_or(site.wmo);
@@ -101,10 +93,8 @@ fn wmo_group_census() {
         site.wmo,
         subject.model.group_nav.len()
     );
-    // The root's MFOG table, once. Every group line below names the ≤4 record indices it points
-    // at, and the fog a room ends up wearing is one of these — which is the whole diagnosis when a
-    // far room reads as a flat wash of one colour (B335: SFK's `0xff28444f` at end 106.9 yd). The
-    // colour is decoded exactly as [`super::super::fog`] decodes it (`0xAARRGGBB`).
+    // The root's MFOG table, once; each group line below names up to four of its records. The
+    // colour decodes as [`super::super::fog`] decodes it (`0xAARRGGBB`).
     for (i, f) in subject.model.fogs.iter().enumerate() {
         println!(
             "mfog f{i}: flags {:#x} pos ({:.1},{:.1},{:.1}) r[{:.2},{:.2}] end {:.1} start×{:.3} = {:.1} rgb({},{},{})",
@@ -123,7 +113,7 @@ fn wmo_group_census() {
         );
     }
     // `WOW_PIN_COL=<world-x,world-y>`: every walking-collision face crossing that column, per group,
-    // as world z — the down-ray's Leg A candidate list for one spot, without running the flood.
+    // as world z; the down-ray's Leg A candidates for one spot.
     if let Some((cx, cy)) = std::env::var("WOW_PIN_COL").ok().and_then(|v| {
         let c: Vec<f32> = v.split(',').filter_map(|p| p.trim().parse().ok()).collect();
         (c.len() == 2).then(|| (c[0], c[1]))
@@ -149,9 +139,9 @@ fn wmo_group_census() {
                 }
             }
         }
-        // The unfiltered contrast: every face in the FILE crossing this column, with its MOPY
-        // flags — a face listed here but not above is one our walking gather dropped, which
-        // against the client's mask (`0x84`, a strict superset of our `0x04` skip) is a parse
+        // Every face in the file at this column, with its MOPY flags. The reference's walking
+        // reject mask `0x84` is DETAIL (`0x04`) plus a transient BSP visited bit (`0x80`), so it
+        // skips exactly the faces ours does; a face without `0x04` missing above is a parse
         // divergence, not a filter choice.
         println!("-- raw file faces at the column (all MOPY flags) --");
         for gi in 0..subject.model.group_nav.len() {
@@ -186,9 +176,8 @@ fn wmo_group_census() {
             }
         }
     }
-    // `WOW_PIN_FLOOR=<local-z>`: dump every walking-collision face whose centroid sits within 3 yd
-    // of that height, as world x/y — the "where exactly is the walkable metalwork at lava level"
-    // map a screenshot-pose reconstruction needs.
+    // `WOW_PIN_FLOOR=<local-z>`: every walking-collision face whose centroid is within 3 yd of that
+    // height, in world coordinates.
     if let Some(floor_z) = std::env::var("WOW_PIN_FLOOR")
         .ok()
         .and_then(|v| v.parse::<f32>().ok())
@@ -212,7 +201,6 @@ fn wmo_group_census() {
         }
     }
     for (gi, g) in subject.model.group_nav.iter().enumerate() {
-        // World bbox: transform all 8 local corners, take the WoW-frame min/max.
         let mut wmin = [f32::INFINITY; 3];
         let mut wmax = [f32::NEG_INFINITY; 3];
         for c in 0..8 {
@@ -266,8 +254,8 @@ fn wmo_group_census() {
                 .map(|(lo, hi)| format!("  LIQUID local z[{lo:.1},{hi:.1}]"))
                 .unwrap_or_default(),
         );
-        // Which MFOG records this group's MOGP header points at, and whether the group is on the
-        // INTERIOR fog lane at all (`flags & 0x48 == 0` — the drawer router's own test).
+        // The group's MFOG records, and whether it is on the interior fog lane at all
+        // (`flags & 0x48 == 0`, the drawer router's own test).
         println!(
             "     fog {:?}{}",
             g.fog_indices,
@@ -277,10 +265,7 @@ fn wmo_group_census() {
                 "  scene-lane (0x48 set)"
             }
         );
-        // The group's portal edges, each placed in WoW world space. The group lines above answer
-        // "which room is that"; without this the doorway between two of them is a local-space
-        // vertex span nobody can point at in game, so a `.go xyz` report can't name the portal it
-        // is standing in front of.
+        // The group's portal edges in WoW world space, to name the portal at a `.go xyz` spot.
         let start = g.ref_start as usize;
         let end = (start + g.ref_count as usize).min(subject.model.portal_refs.len());
         for r in &subject.model.portal_refs[start..end] {
@@ -301,8 +286,7 @@ fn wmo_group_census() {
                 }
             }
             let w = bevy_to_wow(placed.world_from_local.transform_point3(wow_to_bevy(c)));
-            // Widest chord across the polygon (yd) — a doorway's opening, so "did that hop really
-            // have a 3-yd gap to see through" is answered without re-projecting by hand.
+            // The widest chord across the polygon (yd): the doorway's opening.
             let span = verts
                 .iter()
                 .flat_map(|a| {
@@ -320,22 +304,16 @@ fn wmo_group_census() {
     }
 }
 
-/// **The pin probe** — a director's `.go xyz` / `/shot` report, replayed through the real flood.
-///
-/// A bug report names a *place*, and until now turning that place into evidence meant launching the
-/// client, walking there, and clicking the panel's dump button. This runs the same flood offline: give
-/// it the WoW-world eye and look point the report carries and it prints the down-ray's seed evidence,
-/// every portal hop's verdict, and the resulting visible set — the fixture a diagnosis starts from.
+/// The pin probe: a report's eye and look point, in WoW world coordinates, run through the real
+/// flood offline, printing the down-ray's seed evidence, every portal hop's verdict and the visible
+/// set. Its output is derived from the game data: keep it out of the repo.
 ///
 /// ```text
 /// WOW_PIN_EYE=1565.2,417.1,-56.2 WOW_PIN_LOOK=1517.5,406.7,-67.1 \
-///   cargo test -p benilla wmo_pin_probe -- --ignored --nocapture
+///   cargo test -p benilla-world --lib wmo_pin_probe -- --ignored --nocapture
 /// ```
-///
-/// The subject defaults to [`UNDERCITY`] (B26); `WOW_PIN_WMO` + `WOW_PIN_UID` + `WOW_PIN_MAP` +
-/// `WOW_PIN_TILE` retarget it at another placement. Output is Blizzard-derived — keep it out of the repo.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
+#[ignore = "instrument: aimed by WOW_PIN_*, run by hand — cargo test -p benilla-world --lib wmo_portal::audit::pin -- --ignored --nocapture"]
 fn wmo_pin_probe() {
     fn xyz(var: &str, default: [f32; 3]) -> [f32; 3] {
         let Ok(s) = std::env::var(var) else {
@@ -359,13 +337,11 @@ fn wmo_pin_probe() {
     let eye = to_local(eye_world_wow);
     let look = to_local(look_world_wow);
 
-    // The camera exactly as the per-frame pass builds it: clip_from_world in Bevy world space, with
-    // the real placement transform, so portal projection sees what the runtime sees.
+    // The camera as the per-frame pass builds it, in Bevy world space with the real placement.
     let eye_bevy = placed.world_from_local.transform_point3(wow_to_bevy(eye));
     let look_bevy = placed.world_from_local.transform_point3(wow_to_bevy(look));
-    // The app's real projection by default (`CAM_FOVY`; near/far don't matter — the flood clips
-    // against the 4 side planes only). `WOW_PIN_FOVY`/`WOW_PIN_ASPECT` override both to replay a
-    // dump header's recorded values exactly (a window is rarely 16:9).
+    // The app's projection by default (the flood clips only against the side planes, so near and
+    // far do not matter); `WOW_PIN_FOVY` and `WOW_PIN_ASPECT` replay a dump header's values.
     let scalar = |var: &str, default: f32| {
         std::env::var(var).map_or(default, |s| {
             s.trim()
@@ -410,8 +386,7 @@ fn wmo_pin_probe() {
         &placed.world_from_local,
         &mut log,
     );
-    // The trace's per-group preamble is 200+ lines on a city — keep only the hop verdicts and the
-    // seed evidence, which is what a "why is that room gone" question actually reads.
+    // Only the seed evidence and the hop verdicts, not the per-group preamble.
     for line in log.text.lines() {
         if !line.trim_start().starts_with('g') || line.contains("->") {
             println!("{line}");
@@ -430,9 +405,8 @@ fn wmo_pin_probe() {
         vis.len(),
         pvs.visible.len()
     );
-    // The interior-fog gate (`[0xca7f00]`, [`super::super::GroupPvs`]): which of those groups wear
-    // the building's own MFOG triple, and which inherit the scene fog. B335 is read straight off
-    // this line — the room behind the courtyard's arches must NOT be on it.
+    // The interior-fog gate (`[0xca7f00]`, [`super::super::GroupPvs`]): the groups that wear the
+    // building's own MFOG rather than the scene fog.
     let fogged: Vec<usize> = pvs
         .interior_fog
         .iter()
@@ -442,8 +416,8 @@ fn wmo_pin_probe() {
         .collect();
     println!("interior-fog lane: {fogged:?}");
 
-    // The portal graph of every group the flood reached. A flood that stops has either run out of
-    // edges or had them all rejected, and only the edge list tells the two apart.
+    // The portal graph of every group the flood reached: only the edge list tells a flood that ran
+    // out of edges from one whose edges were all rejected.
     println!("-- portal graph of the visible set --");
     for &gi in &vis {
         let g = &model.group_nav[gi];
@@ -469,9 +443,8 @@ fn wmo_pin_probe() {
         );
     }
 
-    // The portal geometry behind every hop verdict above: plane + vertex extent, for each portal
-    // referenced by a group that contains the eye or the look point — the "which side is the eye
-    // actually on" question needs the plane, not the verdict.
+    // The plane and vertex extent of every portal of a group holding the eye or the look point:
+    // which side the eye is on needs the plane, not the verdict.
     println!("-- portals of the groups containing eye/look --");
     for (gi, g) in model.group_nav.iter().enumerate() {
         let holds = |p: [f32; 3]| (0..3).all(|k| p[k] >= g.bbox_min[k] && p[k] <= g.bbox_max[k]);
@@ -505,8 +478,7 @@ fn wmo_pin_probe() {
         }
     }
 
-    // Which room is the director looking *at*? Report every group whose MOGI bbox contains the look
-    // point, with its verdict — the culled one there is the bug.
+    // Every group whose MOGI bbox holds the look point, with its verdict.
     println!("-- groups containing the look point --");
     for (gi, g) in model.group_nav.iter().enumerate() {
         let inside = (0..3).all(|k| look[k] >= g.bbox_min[k] && look[k] <= g.bbox_max[k]);
@@ -527,22 +499,14 @@ fn wmo_pin_probe() {
     }
 }
 
-/// **B335's fixture** — the Shadowfang courtyard's far doorways, as an invariant instead of a
-/// screenshot. The reported spot (`.go xyz -224.01 2168.63 79.79 33`, third-person camera behind)
-/// stands in the open courtyard **g38**, whose MOGP flags carry `0x40` EXTERIOR_LIT; the two arches
-/// at the back of it open (through the second courtyard **g72**, also `0x40`) into room **g61**, a
-/// true interior. The report was that g61 fills with a flat blue-cyan at distance: that colour is
-/// this building's own MFOG record — `rgb(40,68,79)`, end 106.9 yd, start 10.7 — which at 70 yd is
-/// nearly saturated, while the reference shows the room under the scene fog (map 33 noon: end 333,
-/// start 83 ⇒ no fog at all at that range).
-///
-/// So the assertion is not about visibility — the flood reaches g61 from anywhere in the courtyard,
-/// and always did. It is about which fog lane it lands on: the seed's own group takes the interior
-/// lane, and the chain breaks below the exterior-lit courtyards, so **g61 must be on the scene
-/// lane**. The control is the seed itself, which must stay on the interior lane.
+/// From the EXTERIOR_LIT (`0x40`) courtyard g38 (`.go xyz -224.01 2168.63 79.79 33`), the arches
+/// open through courtyard g72, also `0x40`, into the true interior g61. The reference draws g61
+/// under the scene fog (map 33 at noon: start 83, end 333, none at 70 yd), not the building's MFOG
+/// (rgb 40,68,79, start 10.7, end 106.9 yd), because the interior-fog chain breaks at an
+/// exterior-lit group. The control stands in g61, which takes its own MFOG.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
 fn shadowfang_courtyard_leaves_the_far_room_on_the_scene_fog() {
+    let _data = benilla_formats::wow_data_or_skip!();
     let site = SHADOWFANG;
     let subject = load_subject(site.wmo, Some(&site));
     let placed = subject
@@ -551,7 +515,7 @@ fn shadowfang_courtyard_leaves_the_far_room_on_the_scene_fog() {
         .expect("the fixture needs a placement");
     let to_local =
         |wow: [f32; 3]| bevy_to_wow(placed.local_from_world.transform_point3(wow_to_bevy(wow)));
-    // The reported camera: third-person behind the player at the fountain, aimed at the p50 arches.
+    // A third-person camera behind the player at the fountain, aimed at the p50 arches.
     let eye_world = [-227.1_f32, 2157.0, 83.7];
     let look_world = [-212.5_f32, 2232.3, 84.2];
     let eye = to_local(eye_world);
@@ -611,8 +575,8 @@ fn shadowfang_courtyard_leaves_the_far_room_on_the_scene_fog() {
          screenshot shows: not one navy pixel in the frame"
     );
 
-    // The control, from a true interior: standing in g61 itself, the room DOES take the lane —
-    // otherwise this fixture would pass on a gate that is simply always off.
+    // The control: from inside g61 the room takes the interior lane, so a gate that is always off
+    // fails here.
     let inside = to_local([-213.90, 2236.15, 81.5]);
     let inside_bevy = placed
         .world_from_local
@@ -633,22 +597,14 @@ fn shadowfang_courtyard_leaves_the_far_room_on_the_scene_fog() {
     );
 }
 
-/// **1792 §5's fixture** — the sibling case to [`shadowfang_courtyard_leaves_the_far_room_on_the_scene_fog`],
-/// one room further in. Stand *inside* g61 (the director's own "standing inside it" pin) and look
-/// back the way they came: the flood reaches three more true-interior rooms across the courtyards,
-/// and every one of them is off the interior-fog chain. Their walls take the scene fog, which is
-/// 1787 working — but a unit standing in one classifies indoors by its OWN down-ray, so before the
-/// `[P+0x98]` conjunct it wore this building's MFOG regardless. g13 is a 14x18x13 room whose centre
-/// is 91 yd from the eye, where that MFOG (start 10.7, end 106.9) is ~84 % saturated toward
-/// rgb(40,68,79) while the scene fog at map 33 noon (start 83, end 333) is ~3 %: the mob reads as a
-/// flat teal cut-out in an unfogged room.
-///
-/// The invariant this pins is that the case is REACHABLE — a visible true interior off the chain —
-/// because it is what makes the conjunct load-bearing rather than theoretical. The conjunct itself
-/// is `crate::interior`'s `a_settled_anchor_follows_its_rooms_fog_gate_without_moving`.
+/// From inside g61, looking back across the courtyards, the flood reaches true-interior rooms that
+/// are off the interior-fog chain. A unit in one classifies indoors by its own down-ray, so the
+/// `[P+0x98]` conjunct is what puts it on the scene fog: g13's centre is 91 yd from the eye, where
+/// the building's MFOG is ~84% saturated and the scene fog ~3%. The conjunct's own test is
+/// `crate::interior`'s `a_settled_anchor_follows_its_rooms_fog_gate_without_moving`.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
 fn shadowfang_sees_true_interiors_that_are_off_the_fog_chain() {
+    let _data = benilla_formats::wow_data_or_skip!();
     let site = SHADOWFANG;
     let subject = load_subject(site.wmo, Some(&site));
     let placed = subject
@@ -683,11 +639,9 @@ fn shadowfang_sees_true_interiors_that_are_off_the_fog_chain() {
             pvs.visible[g] && !pvs.interior_fog[g] && subject.model.group_nav[g].flags & 0x48 == 0
         })
         .collect();
-    // And the other half of the verdict, end to end on the real data: a unit standing in one of
-    // those rooms attaches to it. Same ray and same `0x48` mask the light classifier's attach uses
-    // (`crate::interior` → `indoor_verdict_at`), cast from a point the body occupies — so the room
-    // it claims is the key the fog gate is asked at. g13 claims g13 (indoor, off the chain ⇒ the
-    // scene fog), and the control g61 claims g61 (indoor, ON the chain ⇒ the building's MFOG).
+    // A unit standing in one of those rooms attaches to it, by the light classifier's own ray and
+    // `0x48` mask (`indoor_verdict_at`): g13 claims g13, off the chain, and the control g61 claims
+    // g61, on it.
     let attach_room = |gi: usize| {
         let g = &subject.model.group_nav[gi];
         let centre = [
@@ -733,30 +687,17 @@ fn shadowfang_sees_true_interiors_that_are_off_the_fog_chain() {
     );
 }
 
-/// **Decision 1853's fixture — Pass 2 WALKS ON from the window, it does not merely mark.**
-///
-/// The reference's Pass 2 ends its per-group predicate in `0x6b3d39 call 0x6b41c0` — the portal
-/// recursion, the same entry point Pass 1 uses — not in the callback draw `0x6b4160` (that is Pass
-/// 3's, and only Pass 3's). Decision 1826 shipped Pass 2 as a *marking* pass: a window admitted an
-/// exterior group's own MOGI box and stopped there. Everything the walk would have reached THROUGH
-/// that group — the next courtyard, the shop behind it, the terrace one portal further on — stayed
-/// culled, and from inside a Darnassus shop that is most of the city.
-///
-/// Darnassus is the discriminating subject because it is one placement with 104 groups, 50 of them
-/// exterior, and its outdoor areas are stitched to each other and to every shop by portals — so the
-/// walk-on has somewhere to go. A building whose shell is one disconnected group (the Goldshire inn)
-/// cannot tell the two implementations apart at all.
-///
-/// The measurement is the **gain**: groups the Pass-2 walk entered that no window admitted directly
-/// and Pass 1 never reached. Under the marking implementation the gain is zero by construction.
+/// Pass 2 walks on from a window rather than only marking the group it admits: the reference ends
+/// its per-group predicate in the portal recursion (`0x6b3d39 call 0x6b41c0`), Pass 1's own entry,
+/// not in Pass 3's callback draw (`0x6b4160`). Measured as the gain, the groups the Pass 2 walk
+/// entered that no window admitted and Pass 1 never reached, from each Darnassus interior with a
+/// doorway; the city's portal-linked outdoor areas give the walk somewhere to go.
 #[test]
-#[ignore = "needs the local game data (WoW/Data); run with --ignored"]
 fn darnassus_pass_two_walks_on_from_the_window() {
+    let _data = benilla_formats::wow_data_or_skip!();
     use std::collections::HashSet;
 
-    /// Splits the flood's `entered` steps into Pass 1's and Pass 2's, and records which groups a
-    /// window admitted directly — everything needed to name what the walk-on, and only the walk-on,
-    /// delivered.
+    /// The flood's `entered` steps split by pass, and the groups a window admitted directly.
     #[derive(Default)]
     struct WalkOn {
         in_pass2: bool,
@@ -796,9 +737,8 @@ fn darnassus_pass_two_walks_on_from_the_window() {
     let placed = subject.placed.as_ref().expect("Darnassus has a placement");
     let nav = &subject.model.group_nav;
 
-    // Every true interior with a doorway is a pose: stand on its floor, look out through its first
-    // portal. That is the director's own description of the report — "standing here looking out
-    // through the doorway" — swept over the whole city instead of one spot.
+    // Every true interior with a doorway is a pose: stand on its floor and look out through its
+    // first portal.
     let mut poses = 0usize;
     let mut total_gain = 0usize;
     let mut best: Option<(usize, usize, usize)> = None; // (gain, group, exterior drawn)
@@ -811,8 +751,8 @@ fn darnassus_pass_two_walks_on_from_the_window() {
             (g.bbox_min[1] + g.bbox_max[1]) * 0.5,
             g.bbox_min[2] + super::EYE_HEIGHT,
         ];
-        // The run is only evidence if the seed actually names the room we meant to stand in — a
-        // bbox centre can sit in a wall, over a stairwell, or above a mezzanine floor.
+        // Only a pose whose seed names the intended room counts: a bbox centre can sit in a wall,
+        // over a stairwell or above a mezzanine floor.
         if subject.seeds(eye).in_group != Some(gi) {
             continue;
         }
diff --git a/crates/benilla-world/src/wmo_portal/fog.rs b/crates/benilla-world/src/wmo_portal/fog.rs
index 504245c4..193c71cd 100644
--- a/crates/benilla-world/src/wmo_portal/fog.rs
+++ b/crates/benilla-world/src/wmo_portal/fog.rs
@@ -1,68 +1,46 @@
-//! The camera-in-interior **WMO fog** resolve — which MFOG record's fog the room wants this frame.
+//! The camera-in-interior WMO fog: which MFOG record's fog the camera's room wants this frame.
 //!
-//! The byte law (wow-re `rf-weather-emission-timeline` ROUND 5, selector `0x69de20`, sole caller
-//! the scene-fog orchestrator `0x6cee30`): when the camera stands in a WMO, the scene fog crossfades
-//! toward the building's **own** MFOG fog — this is why a storm's veil never fogs the Goldshire
-//! inn's tavern. Selection: **seed = record 0** (the WMO default fog), then walk the camera group's
-//! MOGP fog-index byte list (≤4 slots): a record is a candidate iff the WMO-local camera is within
-//! its `largerRadius` and `!(flags & 1)`; candidates blend over the seed by weight
-//! `1 − (d − smallerRadius)/(largerRadius − smallerRadius)`, nearest last. The selector's
-//! `count == 1` bail means **no interior fog engages — the room keeps the SCENE fog, storm veil
-//! included**. Settled EMPIRICALLY by two director ref-shots (2026-07-13): the forge (one "null
-//! fog" record) shows the storm's even veil on every interior surface, near walls included (the
-//! negative-start floor), while the inn (two authored records) is warm and clear. A brief
-//! interim reading ("record 0 still engages") made one-record rooms too crisp — the thing that
-//! had made the veil look wrong before it was the mist volume filling the room (a separate,
-//! since-fixed bug), not the veil itself. QG-6 (wow-re board, recast): byte-confirm the staging
-//! slots simply hold scene values at count == 1.
-//!
-//! This module only picks the **target** triple ([`CameraWmoFog`], written by the PVS pass — the
-//! camera's group falls out of the portal flood's down-ray seed for free). The 4-second crossfade
-//! ramp and the actual scene-fog lerp live in `crate::lighting` (`update_time_lighting`), the
-//! benilla twin of `0x6cee30` — and the ramp value it publishes (`WmoCrossfade`) is ALSO the WMO
-//! skybox's slot alpha: "the skybox alpha and the interior fog blend are the same number"
-//! (wow-re `wmo-skybox.md` §3; `crate::skybox`).
-//!
-//! One explicitly-chosen reading remains: portal-less props never run the flood (all-visible fast
-//! path), so they never engage — no shipped prop is an enterable room. (The claim mask itself is
-//! carved: bit 0x8 alone, round-6 Q-H(c).)
+//! The selector `0x69de20` bails when the root has exactly one MFOG record (`0x69de4b`), as five in
+//! six shipped roots do, and the room keeps the scene fog; past the bail it seeds with record 0
+//! (`0x69ded2`). `select_wmo_fog` then blends over the seed, by the radius falloff and nearest
+//! last, every record the group's fog indices name, index 0 included, that holds the camera inside
+//! its outer radius with `flags & 1` clear. The 4 s crossfade is `crate::lighting`'s. A
+//! portal-less prop runs no flood and never engages; no shipped prop is an enterable room.
 
 use benilla_formats::WmoFog;
 use bevy::prelude::*;
 
-/// The MFOG fog target selected for the camera this frame (`None` = the camera does not stand in
-/// a WMO interior group, or the building carries no MFOG at all — no shipped root does). Written
-/// by the PVS pass ([`super::compute_wmo_pvs`]); consumed by the scene-fog stage
-/// (`crate::lighting`).
+/// The MFOG fog target for the camera this frame: `None` when no containing group of the camera is
+/// a true interior, or the root has under two records. Written by the PVS pass
+/// ([`super::compute_wmo_pvs`]), read by `crate::lighting`.
 #[derive(Resource, Default, Clone, Copy, PartialEq)]
 pub struct CameraWmoFog(pub Option<WmoFogTarget>);
 
-/// One resolved MFOG fog triple, in the record's own units — the staging transform
-/// (`end = min(end, farclip)`, `start = end × start_scalar`, `0x6cef43–62`) is the consumer's.
+/// One resolved MFOG fog triple in the record's own units; the staging transform is the consumer's
+/// (`end = min(end, farclip)`, `start = end × start_scalar`, `0x6cef43`–`0x6cef62`).
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct WmoFogTarget {
-    /// Fog colour, linear-file RGB 0..1 (the MFOG dword is `0xAARRGGBB`).
+    /// Fog colour, RGB 0..1 as filed (the MFOG dword reads `0xAARRGGBB`).
     pub(crate) color: [f32; 3],
     /// Fog end distance (yd), unclamped.
     pub(crate) end: f32,
-    /// Fog start as a **fraction of end** — 1.12.1 multiplies, never subtracts (`fmul 0x6cef56`).
+    /// Fog start as a fraction of end: the 1.12 client multiplies, never subtracts (`0x6cef56`).
     pub(crate) start_scalar: f32,
 }
 
-/// Resolve the fog target for a camera standing in group `fog_indices` of a WMO with `fogs`
-/// records, `eye_local` in WMO model space (WoW axes). `None` on the `count == 1` bail.
+/// The fog target for a camera at `eye_local` (WMO model space, WoW axes) in a group with
+/// `fog_indices`; `None` on the one-record bail.
 pub(super) fn select_wmo_fog(
     fogs: &[WmoFog],
     fog_indices: [u8; 4],
     eye_local: [f32; 3],
 ) -> Option<WmoFogTarget> {
-    // The `count == 1` bail (`0x69de20`'s head): a one-record room keeps the SCENE fog — the
-    // ref forge's even storm veil (see the module doc; director-settled 2026-07-13).
+    // The one-record bail (`0x69de4b`): the room keeps the scene fog.
     if fogs.len() < 2 {
         return None;
     }
-    // Candidates from the group's fog-index list: radius-tested, `flags & 1` excluded, then
-    // distance-sorted so the NEAREST blends last (the client folds its ≤4-nearest array).
+    // Candidates from the group's fog indices: radius-tested, `flags & 1` excluded, sorted so the
+    // nearest blends last (the client folds its up-to-4-nearest array).
     let mut cands: Vec<(f32, &WmoFog)> = fog_indices
         .iter()
         .filter_map(|&i| fogs.get(i as usize))
@@ -72,7 +50,7 @@ pub(super) fn select_wmo_fog(
             (d <= rec.radius_outer).then_some((d, rec))
         })
         .collect();
-    cands.sort_by(|a, b| b.0.total_cmp(&a.0)); // farthest first — nearest folds last
+    cands.sort_by(|a, b| b.0.total_cmp(&a.0)); // farthest first, nearest folds last
     let mut acc = triple(&fogs[0]); // seed: the WMO default fog
     for (d, rec) in cands {
         let span = rec.radius_outer - rec.radius_inner;
@@ -99,7 +77,7 @@ fn triple(rec: &WmoFog) -> WmoFogTarget {
     }
 }
 
-/// MFOG colour dword → RGB 0..1 (`CImVector` in memory is B,G,R,A ⇒ the LE dword reads `0xAARRGGBB`).
+/// MFOG colour dword to RGB 0..1: B,G,R,A in memory (`CImVector`) reads as LE `0xAARRGGBB`.
 fn unpack_argb(c: u32) -> [f32; 3] {
     [
         ((c >> 16) & 0xff) as f32 / 255.0,
@@ -134,24 +112,20 @@ mod tests {
 
     #[test]
     fn single_record_keeps_the_scene_fog() {
-        // The forge/chapel shape: one "null fog" record ⇒ NO engagement — the room keeps the
-        // scene fog, storm veil included (the ref forge's even indoor veil; director-settled
-        // 2026-07-13 after a brief record-0 interim made those rooms too crisp).
         let fogs = [rec(0, [0.0; 3], 0.0, 0.0, 444.4, 0xffffffff)];
         assert!(select_wmo_fog(&fogs, [0; 4], [0.0; 3]).is_none());
     }
 
     #[test]
     fn out_of_radius_and_flagged_records_leave_the_seed() {
-        // The Goldshire inn's shape: default record 0 + a flags&1 record 1 the groups point at —
-        // record 1 is excluded from the candidate walk, so the seed (record 0) is the fog.
+        // The Goldshire inn's shape: the groups point at record 1, which carries `flags & 1`.
         let fogs = [
             rec(0, [0.0; 3], 0.0, 3.36, 194.4, 0xfffad890),
             rec(1, [12.3, -0.6, 2.8], 0.0, 3.36, 83.3, 0xfffdcf9e),
         ];
         let t = select_wmo_fog(&fogs, [1, 0, 0, 0], [12.3, -0.6, 2.8]).expect("engaged");
         assert!((t.end - 194.4).abs() < 1e-3, "seed wins: {t:?}");
-        // The dword decodes ARGB → warm cream.
+        // The dword decodes as ARGB: warm cream.
         assert!((t.color[0] - 250.0 / 255.0).abs() < 1e-4);
         assert!((t.color[2] - 144.0 / 255.0).abs() < 1e-4);
     }
@@ -162,13 +136,13 @@ mod tests {
             rec(0, [0.0; 3], 0.0, 0.0, 200.0, 0xff000000),
             rec(0, [10.0, 0.0, 0.0], 5.0, 25.0, 80.0, 0xffffffff),
         ];
-        // Camera at the record's centre (d = 0 ≤ inner) → full weight, the room fog verbatim.
+        // At the record's centre (d = 0 ≤ inner): full weight, the room fog verbatim.
         let t = select_wmo_fog(&fogs, [1, 0, 0, 0], [10.0, 0.0, 0.0]).unwrap();
         assert!((t.end - 80.0).abs() < 1e-4);
-        // Half-way through the falloff band (d = 15 → w = 0.5) → the midpoint.
+        // Half-way through the falloff band (d = 15, w = 0.5): the midpoint.
         let t = select_wmo_fog(&fogs, [1, 0, 0, 0], [25.0, 0.0, 0.0]).unwrap();
         assert!((t.end - 140.0).abs() < 1e-3, "got {t:?}");
-        // Beyond the outer radius → the seed alone.
+        // Beyond the outer radius: the seed alone.
         let t = select_wmo_fog(&fogs, [1, 0, 0, 0], [40.0, 0.0, 0.0]).unwrap();
         assert!((t.end - 200.0).abs() < 1e-4);
     }
diff --git a/crates/benilla-world/src/wmo_portal/interior.rs b/crates/benilla-world/src/wmo_portal/interior.rs
index b1bdfefa..26c8c3f4 100644
--- a/crates/benilla-world/src/wmo_portal/interior.rs
+++ b/crates/benilla-world/src/wmo_portal/interior.rs
@@ -1,29 +1,13 @@
-//! The player's WMO-interior claims — the two down-ray identities published each frame:
-//!
-//! - [`CurrentWmoInterior`] — the RENDER/AUDIO seed's claim (faces + portal crossings,
-//!   [`super::seed::down_ray_seeds`]): what room the flood seeds from; consumed by the
-//!   interior-audio resolver (`sound::interior`) and the minimap inside-zoom.
-//! - [`CurrentAreaInterior`] — the ZONE-TEXT/AREA claim (faces only, [`super::seed::area_down_ray`];
-//!   wow-re `zonetext-indoor-bit.md`, the CGLight node's `+0x90` bit 0): drives the leaf-area
-//!   override (`terrain_stream`) and the `ZONE_CHANGED` family's indoor election + naming
-//!   (`area`). The legs differ exactly where the abbey-yard bug lived — a doorway portal under
-//!   the eye seeds the render flood without making you indoors.
-//!
-//! Split from `wmo_portal/mod.rs` (the portal-cull flood) when the second claim landed; the
-//! public faces re-export from there.
+//! The WMO-interior claims published each frame: [`CurrentWmoInterior`], the player's claim by the
+//! render seed's ray (faces and portal crossings), and [`CurrentAreaInterior`], the zone-text claim
+//! (faces only, the CGLight node's `+0x90` bit 0 set by `0x6a87f0`). A doorway portal under the
+//! eye seeds the render flood without making you indoors.
 
 use bevy::math::Affine3A;
 use bevy::prelude::*;
 
-/// The `WMOAreaTable` catalog — every WMO group's world-area row: its `AreaTable` id and its
-/// audio identity (sound provider, ambience, zone music, the entry fanfare). Absent when the
-/// client data didn't load.
-///
-/// It lived in `sound::interior` because sound loaded it first (1163's finding), which put a
-/// building's own data on the far side of the world boundary from the building. Two lanes resolve
-/// against it and only one of them is audio: the area authority (`terrain_stream::queries`) reads
-/// a WMO interior's `AreaTable` id from here before it falls back to the terrain chunk, which is
-/// the faithful order — a room's zone name comes from the room.
+/// The `WMOAreaTable` catalog: each WMO group's `AreaTable` id and audio identity; absent when the
+/// client data did not load. A room's zone name comes from here before the terrain chunk's.
 #[derive(Resource)]
 pub(crate) struct WmoAreas(pub(crate) benilla_formats::WmoAreaCatalog);
 
@@ -53,36 +37,18 @@ use super::seed::{area_down_ray, down_ray_claim, down_ray_seeds, up_ray_claim, D
 use super::{WmoPortalInstance, WmoRoom, WorldCamera, EXTERIOR, EXTERIOR_LIT};
 use crate::terrain_stream::{terrain_height_under, PropLobeLight, TerrainStreamer};
 
-/// The WMO interior the camera eye is currently in — the `WMOAreaTable` join keys of the group
-/// owning the nearest surface under the eye ([`down_ray_group`], the client's faithful down-ray), or
-/// `None` in the open world. Written per frame here; consumed by the interior-audio resolver
-/// (`sound::interior`) and any future interior consumer (light, fog, minimap names).
+/// The WMO interior the player is in: the `WMOAreaTable` keys of the group owning the nearest
+/// surface under the probe ([`down_ray_seeds`]), or `None` in the open world.
 #[derive(Resource, Default, Clone, Copy, PartialEq, Eq)]
 pub struct CurrentWmoInterior(pub Option<WmoInteriorKeys>);
 
-/// The **room** the player stands in — the same down-ray claim [`CurrentWmoInterior`] names, but as
-/// the placement identity ([`WmoRoom`]) rather than the `WMOAreaTable` join keys. Written by
-/// [`track_current_interior`] in the same pass (no second ray).
-///
-/// Its consumer is the liquid query's scope key (decision 0696): a building's MLIQ pool belongs to
-/// that building, so only a subject standing in *that placement* can be in it. Before this, "indoors"
-/// was a bare `bool` and every WMO pool on the map answered — the Uldaman entrance read as submerged
-/// under a mushroom cave's water 186 yd overhead, in a building the player was 191 yd below.
+/// The room the player stands in: the claim [`CurrentWmoInterior`] names, as a placement identity.
+/// It scopes the liquid query: a building's MLIQ pool holds only a subject in that placement.
 #[derive(Resource, Default, Clone, Copy, PartialEq, Eq)]
 pub struct PlayerWmoRoom(pub Option<WmoRoom>);
 
-/// The WMO room **one remote unit** stands in — its own liquid claim, the per-unit twin of
-/// [`PlayerWmoRoom`].
-///
-/// It exists because the liquid query's `None` ("no interior claim for this subject") arm was a
-/// standing gap: every consumer that walks *units* rather than the local player — the creature swim
-/// marker, the wade splash, the footstep splash slot, the remote-motion depth — passed it, so both
-/// sources answered and an ADT lake claimed anything beneath it. In Undercity's Rogues' Quarter the
-/// NPCs stood 95 yd under Tirisfal's water at z 32.93 and swam on dry stone, in the same rooms the
-/// player (who *did* have a claim) walked normally (decision 0696).
-///
-/// Re-rayed only when the unit MOVES or a building streams in/out — a room changes at doorways, not
-/// per frame — so a town full of standing NPCs costs one position compare each.
+/// The WMO room a remote unit stands in, its own liquid claim, re-rayed only when the unit moves
+/// or a building streams in or out.
 #[derive(Component, Clone, Copy, Default, PartialEq)]
 pub struct UnitWmoRoom {
     room: Option<WmoRoom>,
@@ -97,9 +63,8 @@ impl UnitWmoRoom {
         self.room
     }
 
-    /// A synthetic claim for tests that exercise a room consumer (the anim-LOD gate's room leg)
-    /// without running the tracker. Not `#[cfg(test)]`: the consumer under test is
-    /// `benilla-app`'s, and a dependent crate does not compile this one's test cfg.
+    /// A synthetic claim for tests of a room consumer. Not `#[cfg(test)]`: the consumer under test
+    /// is `benilla-app`'s, and a dependent crate does not compile this one's test cfg.
     pub fn claimed(room: WmoRoom) -> Self {
         Self {
             room: Some(room),
@@ -117,34 +82,22 @@ pub struct WmoInteriorKeys {
     pub group_area_id: u32,
 }
 
-/// The probe height above the player's feet (yd) for the RENDER/AUDIO seed's down-ray
-/// ([`down_ray_seeds`] — chest/head-ish, the listener). The faces-only AREA/light legs do NOT use
-/// it: the client casts those from the position itself (`zonetext-indoor-bit.md` (b)), and lifting
-/// the origin breaks the terrain race exactly where a hillside is buried ABOVE an interior floor —
-/// NSabbey's NW room sits cut into the hill (buried terrain local z ≈ 2.0 vs floor 0.3), so a
-/// feet+1.7 origin saw the buried terrain as the nearest surface and read the room as outdoors
-/// (director-caught flap, 2026-07-12). A ray from the feet can never hit terrain above its origin.
+/// Height (yd) above the feet of [`CurrentWmoInterior`]'s probe. The position-cast legs cast from
+/// the feet (`0x6a8a20`): a lifted origin can take terrain buried above a floor as nearest.
 pub const INTERIOR_PROBE_HEIGHT: f32 = 1.7;
 
-/// Float-safety lift (yd) for the position-cast legs: feet rest ON the floor plane (physics skin,
-/// server-snapped NPC z), and a coplanar `z <= eye.z` test must not lose the floor to a rounding
-/// hair. Far below any buried-terrain scale — semantically still "cast from the position".
+/// Float-safety lift (yd) for the position-cast legs: feet rest on the floor plane, and a coplanar
+/// `z <= eye.z` test must not lose the floor to rounding.
 pub(crate) const POSITION_PROBE_LIFT: f32 = 0.1;
 
-/// The **zone-text/area** indoor claim — the player's CGLight-node twin (wow-re
-/// `zonetext-indoor-bit.md`, `[node+0x90]` bit 0): the WMOAreaTable keys of the group owning the
-/// nearest **face** under the player, faces-only ([`area_down_ray`] — no portal leg, EXTERIOR
-/// groups excluded, terrain race, 1000 yd), or `None` = outdoors. This — not the render/audio
-/// seed [`CurrentWmoInterior`] — drives the leaf-area override (`terrain_stream`) and the
-/// `ZONE_CHANGED`/`ZONE_CHANGED_INDOORS` election + indoor naming (`area`). The two diverge
-/// exactly where the yard bug lived: a doorway portal under the eye seeds the RENDER flood
-/// without making you indoors.
+/// The zone-text indoor claim, the CGLight node's `[node+0x90]` bit 0 (`0x6a87f0`): the keys of
+/// the group owning the nearest face under the player (faces only, EXTERIOR excluded, terrain
+/// raced, 1000 yd), or `None` outdoors.
 #[derive(Resource, Default, Clone, Copy, PartialEq, Eq)]
 pub struct CurrentAreaInterior(pub Option<WmoInteriorKeys>);
 
-/// Track the player's zone-text indoor claim ([`CurrentAreaInterior`]): per placed building, run
-/// the faces-only down-ray from the player's position; first interior claim wins. Camera fallback
-/// before login, like [`track_current_interior`].
+/// Track [`CurrentAreaInterior`]: per placed building, the faces-only down-ray from the player's
+/// position, first claim wins; the camera stands in before login.
 pub(super) fn track_area_interior(
     wmos: Res<Assets<WmoModel>>,
     viewer: Res<crate::view::Viewer>,
@@ -154,9 +107,7 @@ pub(super) fn track_area_interior(
     adt_tiles: Res<Assets<AdtTile>>,
     mut current: ResMut<CurrentAreaInterior>,
 ) {
-    // Cast from the POSITION (float-safety lift only) — the client's recipe (`zonetext-indoor-bit`
-    // (b)); a lifted origin sees hillside buried ABOVE an interior floor and misreads outdoors
-    // (see [`POSITION_PROBE_LIFT`]).
+    // Cast from the position, lifted only for float safety, as the client does (`0x6a8a20`).
     let eye_world = if let Some(body) = viewer.at {
         body + Vec3::Y * POSITION_PROBE_LIFT
     } else if let Some(cam_t) = cam.iter().next() {
@@ -179,9 +130,8 @@ pub(super) fn track_area_interior(
             continue; // no face of this building can own the probe column
         }
         let terrain_local = terrain.map(|z| terrain_z_local(&local_from_world, eye_world, z));
-        // The zone-text law: `0x8` alone — a `0x40`-only street group IS "indoors" for area naming
-        // (`[node+0x90]` bit 0 is set before the `0x40` test; the light law differs, see
-        // [`indoor_verdict_at`]).
+        // The zone-text law is `0x8` alone: a `0x40`-only street group is indoors for naming
+        // (`[node+0x90]` bit 0 is set before the `0x40` test).
         if let Some(gi) = area_down_ray(
             &model.group_collision_tris,
             &model.group_collision_bounds,
@@ -204,14 +154,9 @@ pub(super) fn track_area_interior(
     }
 }
 
-/// Track which WMO interior the **player** is in: run every placed building's down-ray and
-/// publish the first interior claim. The probe is the player's position, not the camera — the
-/// client's audio listener sits at the character (`SoundListenerAtCharacter` default "1", wow-re
-/// `benilla-pins.md` B10) and the interior identity is character state (the minimap zone name),
-/// so a camera swinging through a wall must not flap the chapel's ambience (director-caught
-/// flicker, 2026-07-03). The camera is the fallback before login / detached free-fly.
-/// Independent of the PVS compute (which early-outs on portal-less models — a portal-less hut
-/// still has a floor to stand on; the *render* seed stays the camera, as the client's does).
+/// Track [`CurrentWmoInterior`] and [`PlayerWmoRoom`] from the character, where the client's audio
+/// listener sits (`SoundListenerAtCharacter` default 1, `0x457890`), not the camera, which stands
+/// in before login. Portal-less models count, unlike in the PVS.
 pub(super) fn track_current_interior(
     wmos: Res<Assets<WmoModel>>,
     viewer: Res<crate::view::Viewer>,
@@ -229,9 +174,8 @@ pub(super) fn track_current_interior(
     } else {
         return;
     };
-    // The terrain leg of the down-ray, sampled once for the eye's column (the client's `GetAreaID`
-    // races the same two probes at `0x670345`) — a mine tunnel under a hill must not claim the
-    // player standing on the grass above it.
+    // The terrain leg, sampled once for the column (`GetAreaID` races the same two probes,
+    // `0x670345`): a tunnel under a hill must not claim the player on the grass above it.
     let terrain = terrain_height_under(&streamer, &adt_tiles, eye_world);
     let mut found = None;
     let mut found_room = None;
@@ -251,7 +195,7 @@ pub(super) fn track_current_interior(
                 name_set: u32::from(inst.name_set),
                 group_area_id: model.group_nav.get(gi).map_or(0, |g| g.area_table_id),
             });
-            // The same claim as a placement identity — the liquid query's scope key (0696).
+            // The same claim as a placement identity, the liquid query's scope key.
             found_room = Some(WmoRoom {
                 instance: entity,
                 group: gi as u16,
@@ -267,23 +211,14 @@ pub(super) fn track_current_interior(
     }
 }
 
-/// Squared distance (yd²) a unit must move before its room claim is re-rayed. A room changes at a
-/// doorway, not continuously, so this is a travel gate rather than a precision one: the claim can
-/// lag a transition by at most this distance, which for a swim/submersion verdict is well inside the
-/// wade band. Deliberately coarser than `interior::RESAMPLE_DIST_SQ` (the light classifier's ~0,
-/// which must not quantize a *continuous* MOCV field into steps — a room index has no such field).
+/// Squared distance (yd²) a unit must move before its room is re-rayed: a room changes at doorways,
+/// so the claim may lag a transition by this much, well inside the wade band.
 const UNIT_ROOM_RESAMPLE_DIST_SQ: f32 = 0.25 * 0.25;
 
-/// Maintain [`UnitWmoRoom`] on every net entity: the room its position stands in, from the same
-/// faces-only down-ray the zone-text claim uses ([`area_down_ray`], EXTERIOR `0x8` excluded, terrain
-/// raced) cast from the unit's own position.
-///
-/// The leg is the **position-cast faces** one, not the render seed's lifted eye + portal race: the
-/// client casts its position legs from the position itself (`zonetext-indoor-bit.md` (b)), and a unit
-/// is a position, not a camera. Which leg the reference's *own* per-unit liquid depth uses — and
-/// whether it scopes to the containing GROUP rather than the placement — is the open half of the
-/// wow-re dispatch 0696 re-asked; this is the claim that makes the query *scoped at all*, and it is
-/// re-pointable at one call site when that lands.
+/// Maintain [`UnitWmoRoom`] on every net entity with the faces-only down-ray of the zone-text
+/// claim, cast from the unit's own position as the client casts its position legs (`0x6a8a20`).
+/// Which leg the reference's per-unit liquid depth uses, and whether it scopes to the group rather
+/// than the placement, is untraced.
 pub(super) fn track_unit_interiors(
     mut commands: Commands,
     wmos: Res<Assets<WmoModel>>,
@@ -300,13 +235,10 @@ pub(super) fn track_unit_interiors(
 ) {
     let generation = residency.generation();
     for (entity, transform, body, claim) in &mut units {
-        // World position, not the local one: a mounted unit's `Transform` is seat-relative
-        // (0441), and its room is decided where it actually stands.
+        // World position, not the local one: a mounted unit's `Transform` is seat-relative.
         let pos = transform.translation();
-        // The re-test gate: a settled unit in an unchanged world keeps its room for free. A
-        // building streaming in UNDER a standing NPC must still re-claim it — that is the whole
-        // point of the generation leg, and without it a creature spawned before its own dungeon
-        // would hold an "outdoors" claim and read the lake overhead forever.
+        // A settled unit keeps its room; the generation leg re-claims one a building streamed in
+        // under, or it would read the lake overhead forever.
         if let Some(claim) = claim.as_ref() {
             if claim.generation == generation
                 && pos.distance_squared(claim.at) < UNIT_ROOM_RESAMPLE_DIST_SQ
@@ -314,12 +246,8 @@ pub(super) fn track_unit_interiors(
                 continue;
             }
         }
-        // The under-floor fallback's reach for THIS body: the height of its own bound's centre
-        // above its origin, floored at [`ROOM_UNDER_FLOOR_TOLERANCE`]. A placed object's origin is
-        // wherever the artist put it *inside its own model*, so the middle of that model is a point
-        // the body genuinely occupies — self-scaling, and it cannot reach a floor the body does not
-        // already straddle. The flat tolerance alone left Orgrimmar's Onyxia trophy post (origin
-        // 3.25 yd under group 133's floor) still reading outdoors.
+        // The under-floor fallback reaches the body's bound centre, at least the tolerance: a
+        // point the body occupies, so it finds no floor the body does not straddle.
         let reach = body
             .bound
             .map(|b| transform.transform_point(Vec3::from(b.center)).y - pos.y)
@@ -337,8 +265,7 @@ pub(super) fn track_unit_interiors(
                     *claim = next;
                 }
             }
-            // `try_insert`: a unit despawning this frame (the net teardown) applies before this
-            // command, and the insert must not panic at apply time.
+            // `try_insert`: a unit despawned this frame by the net teardown must not panic here.
             None => {
                 commands.entity(entity).try_insert(next);
             }
@@ -346,31 +273,13 @@ pub(super) fn track_unit_interiors(
     }
 }
 
-/// The FLOOR on how far above its own origin a body's room claim looks for the surface it stands
-/// on, when the position cast found nothing at all below it ([`room_at`]'s second pass). The reach
-/// itself is per body — the height of its own bound's centre, see [`track_unit_interiors`] — and
-/// this is what a body with no bound yet, or a squat one, gets.
-///
-/// **A placed object's origin is wherever the artist put it, and for anything planted in the ground
-/// that is UNDER the surface** — a firepit's origin sits in the pit, a signpost's at the buried foot
-/// of its post. A ray down from such an origin passes beneath the floor the object stands on and
-/// finds nothing, so the body reads "outdoors" in the middle of a building. Orgrimmar: 32 of 133
-/// streamed bodies at once, measured 0.45–1.16 yd under their floor face (decision 1409).
-///
-/// Two yards covers that spread with margin and cannot reach the storey above — no room we draw is
-/// under two yards tall. A **fallback, not a lift**: it runs only where the position cast found no
-/// face at all, so it can turn "outdoors" into a room and can never move a body between two rooms it
-/// was already choosing from. The primary pass keeps [`POSITION_PROBE_LIFT`] and the buried-terrain
-/// race that constant was chosen for.
+/// The least reach (yd) of [`room_at`]'s second pass above a body's origin. A planted object's
+/// origin can sit under its floor (Orgrimmar's props, 0.45 to 1.16 yd); two yards covers that and
+/// reaches no storey above.
 pub(crate) const ROOM_UNDER_FLOOR_TOLERANCE: f32 = 2.0;
 
-/// The WMO room a world position stands in — the placement + group of the nearest **face** under it,
-/// faces-only ([`area_down_ray`], EXTERIOR `0x8` excluded, terrain raced), first claim wins; on a
-/// total miss, a second pass from `reach` higher catches a body whose origin is authored below the
-/// surface it stands on ([`ROOM_UNDER_FLOOR_TOLERANCE`]).
-///
-/// The shared body of the per-unit claim; the same shape as [`track_area_interior`]'s loop, returning
-/// the placement identity instead of the `WMOAreaTable` keys.
+/// The WMO room a world position stands in, by the faces-only ray; only on a miss, a second pass
+/// from `reach` higher finds a body whose origin sits below its floor.
 fn room_at(
     wmos: &Assets<WmoModel>,
     instances: &Query<(Entity, &WmoPortalInstance)>,
@@ -383,7 +292,7 @@ fn room_at(
         .or_else(|| room_cast(wmos, instances, streamer, adt_tiles, feet_world, reach))
 }
 
-/// One faces-only room cast from `feet_world + rise` — the shared body of [`room_at`]'s two passes.
+/// One faces-only room cast from `feet_world + rise`.
 fn room_cast(
     wmos: &Assets<WmoModel>,
     instances: &Query<(Entity, &WmoPortalInstance)>,
@@ -399,7 +308,7 @@ fn room_cast(
             continue;
         };
         if model.wmo_id == 0 {
-            continue; // the same placement set the player's own claim walks
+            continue; // as the player's own claim skips it
         }
         let local_from_world = inst.world_from_local.inverse();
         let probe_local = bevy_to_wow(local_from_world.transform_point3(probe_world));
@@ -425,21 +334,9 @@ fn room_cast(
     None
 }
 
-/// Whether a world position stands INDOORS **for the unit LIGHT law** — the nearest surface under
-/// it (cast from the position itself, [`POSITION_PROBE_LIFT`]) is a face of some placed WMO group
-/// whose flags carry neither EXTERIOR (`0x8`) nor EXTERIOR_LIT (`0x40`) ([`area_down_ray`], faces
-/// only, terrain-raced). This is the ENTITY light classifier's predicate (`crate::interior`): the
-/// client's classify `0x6a87f0` forks the node's LIGHTING class on `MOGI & 0x48` — both bits →
-/// the exterior leg (`or [node+0xc],0x4`: sun diffuse, MCSH 2.5/0.5 intensity, scene fog; wow-re
-/// `m2-interior-doodad-base-light.md`, `unit-m2-shader-light.md`) — which DIVERGES from the
-/// zone-text indoor bit (`0x8` alone) exactly on the `0x40`-only city street groups: Stormwind's
-/// pavement and Orgrimmar's valleys are "indoors" for area naming yet sunlit (decision 0475; keying
-/// the light off the zone-text bit flat-lit every unit in those cities). The face geometry is
-/// robust exactly where group BOUNDING BOXES are not — a room's box bottom can float above its own
-/// walkable floor when the floor polys belong to a neighbouring group (NSabbey group 3: box min z
-/// 1.84 vs floor ≈0.3), which split a standing body's feet-level parts onto the exterior law
-/// (director-caught, 2026-07-12). Unlike the AREA claim ([`track_area_interior`]), a WMO without a
-/// `WMOAreaTable` identity still counts — lighting is about the room's geometry, not its name.
+/// Whether a world position is indoors for the unit light law: the nearest surface under it is a
+/// face of a WMO group with neither `0x8` nor `0x40`, the lighting-class fork on `MOGI & 0x48`
+/// (`0x6a87f0`). A WMO without a `WMOAreaTable` identity counts.
 pub fn indoors_at<'a>(
     wmos: &Assets<WmoModel>,
     instances: impl IntoIterator<Item = &'a WmoPortalInstance>,
@@ -461,78 +358,46 @@ pub fn indoors_at<'a>(
     )
 }
 
-/// Which ATTACH a light node uses to find its WMO group — the reference's `[node+0x90]` bit 13
-/// (`0x2000`), written once at node creation from the descriptor TYPEMASK (`0x613e10`/`0x670db0`)
-/// and read by the mode dispatch `0x6a86d0` (`6a8714 test ah,0x20`; `6a871c jmp 0x6a8c10` SET /
-/// `6a8721 jmp 0x6a8a20` CLEAR). **There is no subclass or vtable test anywhere in the dispatch** —
-/// the mode bit is the whole fork, so the two lanes are a property of the OBJECT KIND, not of the
-/// shading law (which stays one law for every entity M2; see [`crate::interior`]).
+/// Which attach a light node uses to find its WMO group: `[node+0x90]` bit `0x2000`, set at node
+/// creation from the typemask (`0x613e10`/`0x670db0`) and read by the dispatch `0x6a86d0`, which
+/// has no subclass test: the lane follows the object kind, not the shading law.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum LightAttach {
-    /// Units, players, and ADT/WMO doodads — the down-ray attach `0x6a8a20`, cast from the node
-    /// POSITION (`[node+0xa8]`, the env-query position `0x6717d0` syncs at `671a48`).
+    /// Units, players and ADT/WMO doodads: the down-ray attach `0x6a8a20`, from the node position
+    /// (`[node+0xa8]`).
     DownRay,
-    /// GameObjects — the CONTAINMENT attach `0x6a8c10` → `0x6a8ed0`, whose segment starts at
-    /// `[node+0x5c]`: the node's world bounding-box **centre** (`0x6717d0` writes the world box to
-    /// `node+0x44` at `671973`, then `671978 call 0x621160` sums min+max and `× [0x7ffa24]=0.5`
-    /// lands the centre at `node+0x5c`). Its face query casts DOWN 1000 and, on a miss, **retries
-    /// UP 1000** (`6a908d..6a90c7`) — a GameObject may sit a hair under its own floor and still
-    /// belong to the room.
+    /// GameObjects: the containment attach `0x6a8c10` → `0x6a8ed0`, from the world bounding-box
+    /// centre (`[node+0x5c]`, `0x6717d0`); on a downward miss it retries 1000 yd up (`0x6a908d`).
     Containment,
 }
 
-/// A position's resolved interior LIGHT verdict — [`indoors_at`] plus, for the GameObject lane,
-/// the footprint bake ([`crate::interior`] folds it into the object's SH probe).
+/// A position's interior light verdict, with the footprint bake when indoors.
 pub enum IndoorVerdict {
-    /// No WMO face claim under the position — standing on/over open terrain: the exterior law
-    /// with the MCSH-driven 2.5/0.5 intensity.
+    /// No WMO face under the position: the exterior law, MCSH-driven 2.5/0.5 intensity.
     Outdoors,
-    /// The nearest claim is an outdoor-class WMO face (`MOGI & 0x48` — a street, deck, porch):
-    /// the exterior law at the FORCED-LIT 2.5 target — the terrain MCSH beneath the building is
-    /// NOT sampled. Byte-verified (0477 interim → 0480 confirmed; wow-re `unit-wmo-mcsh-gate.md`,
-    /// the §5 that CORRECTED `unit-light-combine-storm.md` a4): the shared down-ray attach
-    /// `0x6a8a20` sets skip-shadow `[node+0xd]|=0x2` on its WMO branch for EVERY node subclass
-    /// (`0x6a8bc7` — a4's "doodad-only" reading was wrong) and clears it on the terrain branch;
-    /// the exterior intensity leg then commits constant 2.5 when set, samples MCSH only when
-    /// clear. The director's Booty Bay A/B (deck NPCs sunlit over shadowed buried terrain) was
-    /// this gate, not a decode error.
+    /// An outdoor-class WMO face (`MOGI & 0x48`) is nearest: the exterior law at the forced-lit
+    /// 2.5, not sampling the terrain MCSH beneath (`0x6a8a20` sets skip-shadow `[node+0xd] |= 0x2`
+    /// on its WMO branch for every node subclass, `0x6a8bc7`).
     OutdoorsOnWmo,
-    /// Indoors, but the footprint lane yields the day/night pair instead of a bake: the render-mesh
-    /// ray missed every MOCV face, or the hit face's MOPY bit 0x1 selects the exterior colours
-    /// (wow-re `m2-interior-doodad-base-light` §11's binary selector). The plain matte variant.
+    /// Indoors, but the footprint ray missed every MOCV face or the hit face's MOPY bit 0x1
+    /// selects the exterior colours (`0x6a8410`): the plain matte variant.
     DayNight,
-    /// Indoors over baked floor: the hit's barycentric MOCV bytes (the floor-168/cap-96 inputs)
-    /// plus the hit group's MOLR lobes in world (Bevy) space, colour × intensity.
+    /// Indoors over a baked floor: the hit's barycentric MOCV bytes and the hit group's MOLR lobes
+    /// in world (Bevy) space, colour × intensity.
     Baked {
         mocv: [u8; 3],
         lobes: Vec<PropLobeLight>,
     },
 }
 
-/// Resolve a position's interior light verdict: the [`down_ray_claim`] classify (collision faces,
-/// the `0x48` LIGHTING-class law — decision 0475, terrain race) runs per placement and the
-/// **nearest claim across placements wins** — the client's one global nearest-hit (a unit inside a
-/// Booty Bay hut sits in the same column as the city deck 30 yd below; the hut's floor must own
-/// the verdict regardless of instance iteration order). An outdoor-class winner is
-/// [`IndoorVerdict::OutdoorsOnWmo`]; an interior winner runs the FOOTPRINT ray on the same
-/// placement's render mesh + baked MOCV (the entity node's env-update attach `0x6717d0` →
-/// `0x69e4c0` — wow-re `wmo-lit-selector.md`, trace-decisive on the abbey INNBENCH draws). The
-/// MOLR gate is the FOOTPRINT hit's group — the group whose bake the sample took (the byte
-/// plumbing between the two rays is OPEN; the abbey benches satisfy both readings).
+/// A position's interior light verdict: the [`down_ray_claim`] classify runs per placement and the
+/// nearest claim across placements wins, the client's one global nearest hit. An interior winner
+/// runs the footprint ray on that placement's mesh (`0x6717d0` → `0x69e4c0`); the MOLR lobes come
+/// from the footprint hit's group, where the reference's link between the two rays is untraced.
 ///
-/// `anchor_world` is **the attach's own anchor**, not "the position": the node position for
-/// [`LightAttach::DownRay`], the model's world bounding-box CENTRE for
-/// [`LightAttach::Containment`] (see the enum for the bytes). A GameObject's origin routinely sits
-/// at or under its own floor — a Stratholme portcullis spawns 15 cm below the corridor slab — and
-/// a ray from there leaves the building entirely; the reference never casts from there (0776).
-/// `Containment` also takes the reference's UPWARD retry on the footprint leg (`6a908d`), so an
-/// object resting a hair below its floor still bakes from it.
-///
-/// Returns the winning **room** alongside the verdict — the caller's own key for the placement that
-/// won, paired with the claim's group index — `None` on both outdoor arms. That pair is the
-/// reference's per-(instance, group) render record `P`: the light node's attach is what creates it
-/// (`0x685f85` → `[P+0x98]`), and it is the key the interior-FOG gate is asked at, separately from
-/// the light law (decision 1792 §4). Callers that only want the bool pass `()` as the key.
+/// `anchor_world` is the attach's anchor ([`LightAttach`]). Also returns the winning room as
+/// `(key, group)`, or `None` outdoors: the per-(instance, group) render record the attach creates
+/// (`0x685f85`, `[P+0x98]`), where the interior-fog gate is asked. Pass `()` as the key to skip it.
 pub fn indoor_verdict_at<'a, K: Copy>(
     wmos: &Assets<WmoModel>,
     instances: impl IntoIterator<Item = (K, &'a WmoPortalInstance)>,
@@ -544,12 +409,8 @@ pub fn indoor_verdict_at<'a, K: Copy>(
     let probe_world = anchor_world + Vec3::Y * POSITION_PROBE_LIFT;
     let terrain = terrain_height_under(streamer, adt_tiles, probe_world);
     let mut best: Option<(DownRayClaim, &WmoModel, &WmoPortalInstance, [f32; 3], K)> = None;
-    // The containment lane's UPWARD retry (`0x6a8ed0`'s `6a9093 fadd ds:0x8022cc`): a GameObject's
-    // light node anchors at its authored-box centre, which for a particle-heavy model sits well
-    // BELOW the floor it stands on — 104 of Onyxia's lava traps anchor ~40 yd under the chamber
-    // (their authored box reaches 98 yd past their own geometry). The reference recovers by casting
-    // up; run it only when the whole downward pass came back empty, so a claim is never arbitrated
-    // against one made in the other direction. See [`up_ray_claim`].
+    // The containment lane's upward retry (`0x6a9093`, +1000 yd) runs only when the whole downward
+    // pass found nothing, so no claim is arbitrated against one cast the other way.
     let instances: Vec<(K, &WmoPortalInstance)> = instances.into_iter().collect();
     for retry_up in [false, true] {
         if retry_up && (best.is_some() || !matches!(attach, LightAttach::Containment)) {
@@ -599,16 +460,11 @@ pub fn indoor_verdict_at<'a, K: Copy>(
     if claim.outdoor {
         return (IndoorVerdict::OutdoorsOnWmo, None);
     }
-    // The ROOM the light node attached to, for every indoor verdict below. It is the ATTACH ray's
-    // group (`0x6a8a20`'s claim), not the footprint sample's: the reference's per-(instance,group)
-    // render record hangs off the node's attach, and the footprint leg is a later, separate ray
-    // that only picks the bake colours. The two agree on every floor where one face owns both.
+    // The room is the attach ray's group (`0x6a8a20`), not the footprint sample's: the render
+    // record hangs off the attach, and the footprint ray only picks the bake colours.
     let room = Some((key, claim.group));
-    // Indoors — run the footprint sample on the winning placement's render mesh. The containment
-    // lane retries UPWARD on a miss (`6a908d..6a90c7`); the down-ray lane has no such leg here (its
-    // own retry is a second DOWNWARD cast from 1000 above, `6a8ab0`, which cannot reach a face
-    // above the anchor either). Bounded to the placement the claim already won: an unbounded
-    // upward claim would let a bridge deck 40 yd overhead adopt a unit standing in the open.
+    // The footprint sample, on the winning placement only (an unbounded upward retry would let a
+    // deck overhead adopt a unit in the open); the down-ray lane never retries upward (`0x6a8ab0`).
     let sample = footprint_sample(model, probe_local).or_else(|| {
         matches!(attach, LightAttach::Containment)
             .then(|| footprint_sample_above(model, probe_local))
@@ -639,14 +495,10 @@ pub fn indoor_verdict_at<'a, K: Copy>(
     (IndoorVerdict::Baked { mocv, lobes }, room)
 }
 
-/// The footprint down-ray: the nearest render-mesh face below `probe_local` across the model's
-/// interior groups' [`FootprintTris`] — its group index, the hit's barycentric MOCV (rounded to
-/// bytes: the reference's `0x6a77e0` consumes a byte colour), and whether the face's MOPY bit 0x1
-/// selects the day/night lane. The candidate set is pre-filtered at parse (COLLISION/VISITED faces
-/// rejected, the client's BSP-walk mask 0x88 — `wmo_group_footprint_tris`); an exact-distance tie
-/// keeps the LATER face, the client's inclusive `test ah,0x41; jp` compare (wow-re
-/// `unit-light-combine-storm.md` — its BSP traversal order is not modelled here, so which face is
-/// "later" can differ; after the 0x88 filter no observed floor still carries coplanar ties).
+/// The footprint down-ray: the nearest render face below the probe in the interior groups (faces
+/// pre-filtered by the client's BSP mask 0x88), with its group, its barycentric MOCV in bytes
+/// (`0x6a77e0` takes a byte colour) and whether MOPY bit 0x1 selects day/night. An exact tie keeps
+/// the later face (`0x6bc780`), in face order rather than BSP order; no floor was seen with one.
 pub(super) fn footprint_sample(
     model: &WmoModel,
     probe_local: [f32; 3],
@@ -654,38 +506,24 @@ pub(super) fn footprint_sample(
     footprint_scan(model, probe_local, false, None).map(|(g, c, m, _)| (g, c, m))
 }
 
-/// The footstep surface's **material ray** (decision 1161) — the second of the client's two rays.
-/// The first (the collision-face down-ray that races terrain) has already picked `group`; this
-/// re-casts the same column over that group's RENDER faces and reads the winning face's
-/// `TerrainType` id: `MOPY[face].material_id → MOMT[id].ground_type` (`0x6a26c0`).
-///
-/// It is the *same* candidate set the lighting sample walks, and not by coincidence: both are the
-/// client's `0x88`-reject face walk ([`FOOTPRINT_REJECT`](benilla_formats::FootprintTris) — a
-/// COLLISION or VISITED face is invisible to either). The two rays deliberately see different
-/// geometry, which is why a floor authored as a render sheet over a separate collision sheet
-/// resolves its *material* off the render layer while the arbitration used the collision one.
-///
-/// `None` = the client's `−1`: no accepted render face under the probe in that group, or a
-/// material id past the root's MOMT. The caller must read that as **silent**, never as a reason to
-/// fall back to the terrain leg — the building won the column either way.
+/// The footstep material ray, the second of the client's two: re-cast over `group`'s render faces,
+/// the winning face's `MOPY` material → `MOMT` ground type (`0x6a26c0`). `None` is the client's
+/// `-1`, silent: never a reason to fall back to terrain, since the building won the column.
 pub(crate) fn surface_terrain_sample(
     model: &WmoModel,
     group: usize,
     probe_local: [f32; 3],
 ) -> Option<u32> {
     let (_, _, _, material) = footprint_scan(model, probe_local, false, Some(group))?;
-    // The client indexes MOMT unchecked; the assets hold the invariant (every `0xFF` face carries
-    // MOPY `0x08` and was dropped at parse). We bounds-check rather than inherit a latent OOB.
+    // The client indexes MOMT unchecked, safe because every `0xFF` face was dropped at parse.
     model
         .material_ground_type
         .get(usize::from(material))
         .copied()
 }
 
-/// The containment attach's **upward retry** (`6a908d`: the down leg missed, so the segment is
-/// rebuilt from the anchor to `anchor.z + 1000` and re-cast): the nearest render-mesh face ABOVE
-/// the probe, same group/MOCV/MOPY answer as [`footprint_sample`]. A GameObject whose origin — or
-/// even whose box centre — settles below its own floor is still lit by that floor.
+/// The containment attach's upward retry (`0x6a908d`, re-cast to `anchor.z + 1000`): the nearest
+/// render face above the probe.
 pub(super) fn footprint_sample_above(
     model: &WmoModel,
     probe_local: [f32; 3],
@@ -693,10 +531,9 @@ pub(super) fn footprint_sample_above(
     footprint_scan(model, probe_local, true, None).map(|(g, c, m, _)| (g, c, m))
 }
 
-/// The shared body of the footprint/material legs: `up` flips which side of the probe a face must
-/// lie on and which of the candidates wins (nearest, in the cast's own direction); `only_group`
-/// restricts the scan to a single group, which is what the material ray needs — the arbitration
-/// has already chosen the group, and the nearest render face *overall* can belong to another one.
+/// The footprint and material rays: `up` flips which side of the probe a face must lie on (the
+/// nearest in the cast's direction wins); `only_group` holds the material ray to the group the
+/// arbitration chose, since the nearest render face overall can belong to another.
 fn footprint_scan(
     model: &WmoModel,
     probe_local: [f32; 3],
@@ -710,21 +547,16 @@ fn footprint_scan(
         if only_group.is_some_and(|g| g != gi) {
             continue;
         }
-        // Broad phase on the load-derived face bounds (the 0330 rule — from the faces, never an
-        // authored box, so the cull is exact): a down-ray at (px, py) can hit no face of a group
-        // whose XY face bounds exclude the column, and no face whose LOWEST vertex is already
-        // above the probe (interpolated z ≥ the face set's min z). Without this every re-rayed
-        // entity scanned every interior group of the whole model — the Stormwind live-frame cost
-        // (decision 0364).
+        // Broad phase on the face-derived bounds, never an authored box, so the cull is exact: skip
+        // a group whose XY bounds exclude the column or whose faces all lie past the probe.
         if let Some(Some((min, max))) = model.group_footprint_bounds.get(gi) {
             let past_probe = if up { max[2] < pz } else { min[2] > pz };
             if px < min[0] || px > max[0] || py < min[1] || py > max[1] || past_probe {
                 continue;
             }
         }
-        // The narrow phase: the group's column index when it has one, else every face. The index
-        // yields a superset in ascending face order (`column_grid`), so the exact-z tie below —
-        // "the LATER face wins" — resolves exactly as the linear scan resolved it.
+        // Narrow phase: the column index, else every face. The index yields faces in ascending
+        // order, so the later-face-wins tie resolves as the linear scan does.
         let mut consider = |ti: usize| {
             let Some(tri) = fp.indices.get(ti * 3..ti * 3 + 3) else {
                 return;
@@ -786,12 +618,8 @@ fn footprint_scan(
     })
 }
 
-/// Whether a probe column (model-local WoW coords) can hit any of a building's collision faces:
-/// inside the whole-model face AABB ([`WmoModel::collision_bounds`]) in XY, with faces reaching
-/// at/below the probe. Exact-conservative for the faces-only down-ray — `floor_z_at` accepts only
-/// inside a triangle's XY projection at z ≥ the set's min — so a skipped instance could never have
-/// answered. This is what keeps a camera in open country at one AABB test per resident building
-/// instead of a full face scan (the 2026-07-12 fps regression).
+/// Whether a probe column (model-local) can hit any of a building's collision faces: inside the
+/// face AABB in XY with faces on the cast's side. Exact, and one test per building in open country.
 fn column_in_collision_bounds(
     bounds: Option<([f32; 3], [f32; 3])>,
     probe: [f32; 3],
@@ -802,20 +630,14 @@ fn column_in_collision_bounds(
             && probe[0] <= max[0]
             && probe[1] >= min[1]
             && probe[1] <= max[1]
-            // The cast's own half-space: a DOWNWARD ray can hit nothing in a building that ends
-            // above the probe, an UPWARD one nothing in a building that ends below it. Keeping the
-            // downward spelling for the upward retry is what silently kept that retry inert — a
-            // probe 40 yd under Onyxia's floor sits below the lair's own collision floor, so the
-            // instance was culled here and the retry never ran on it at all.
+            // The cast's own half-space: a downward ray hits nothing in a building wholly above the
+            // probe, an upward one nothing in a building wholly below it.
             && if up { max[2] >= probe[2] } else { min[2] <= probe[2] }
     })
 }
 
-/// The terrain surface under `eye_world` (given as raw WoW `z`), expressed in a placement's model-space
-/// `z` — the frame [`down_ray_pick`](seed::down_ray_pick) races in. The surface point sits in the eye's
-/// own column, so it maps straight through the inverse placement: MODF placements carry yaw only, and
-/// under a yaw a world-vertical column is a model-vertical one. (A pitched/rolled placement would tilt
-/// the down-ray itself, an approximation the whole probe already makes.)
+/// The terrain surface under `eye_world` (raw WoW `z`) as a placement's model-space `z`, the frame
+/// the down-ray races in; exact for a yaw-only placement, where a vertical column stays vertical.
 pub fn terrain_z_local(local_from_world: &Affine3A, eye_world: Vec3, terrain_wow_z: f32) -> f32 {
     let eye_wow = bevy_to_wow(eye_world);
     let surface = wow_to_bevy([eye_wow[0], eye_wow[1], terrain_wow_z]);
@@ -828,7 +650,7 @@ mod tests {
     use benilla_assets::footprint_tri_bounds;
     use benilla_formats::FootprintTris;
 
-    /// A model with nothing but footprint groups — the sample under test reads only those.
+    /// A model with nothing but footprint groups, all the sample reads.
     fn bare_model() -> WmoModel {
         WmoModel {
             wmo_id: 0,
@@ -865,8 +687,7 @@ mod tests {
     }
 
     /// Two single-face footprint groups: group 0 owns the floor under the probe (z = 0), group 1
-    /// sits far away in XY with a HIGHER face (z = 5) that would shadow group 0's hit if a broken
-    /// cull ever let its column test slip.
+    /// sits far off in XY with a higher face (z = 5) that would shadow it through a broken cull.
     fn two_group_footprints() -> Vec<Option<FootprintTris>> {
         let face = |offset: [f32; 3], material: u8| FootprintTris {
             positions: vec![
@@ -885,9 +706,8 @@ mod tests {
         ]
     }
 
-    /// A dungeon-scale footprint group: a `n × n` grid of floor quads at a sawtooth height, so a
-    /// column's answer depends on WHICH face wins, not merely on hitting something. Big enough
-    /// (>= 64 faces) that [`ColumnGrid::build`] actually indexes it.
+    /// A dungeon-scale footprint group: an `n × n` grid of floor quads at a sawtooth height, so a
+    /// column's answer depends on which face wins; 64 faces or more, so `ColumnGrid` indexes it.
     fn slab_field(n: usize) -> FootprintTris {
         let (mut positions, mut indices, mut mocv, mut mopy_flags) =
             (Vec::new(), Vec::new(), Vec::new(), Vec::new());
@@ -895,7 +715,7 @@ mod tests {
         for iy in 0..n {
             for ix in 0..n {
                 let (x, y) = (ix as f32 * 4.0, iy as f32 * 4.0);
-                // Sawtooth z so neighbouring quads differ — a mis-picked face changes the verdict.
+                // Sawtooth z: a mis-picked face changes the verdict.
                 let z = ((ix + iy) % 3) as f32 * 0.5;
                 let base = positions.len() as u16;
                 positions.extend_from_slice(&[
@@ -920,11 +740,8 @@ mod tests {
         }
     }
 
-    /// **The material ray reads the hit FACE's material, inside the group the arbitration chose.**
-    /// The group restriction is the whole point (decision 1161): the first ray already picked the
-    /// group off the *collision* faces, so a nearer render face in a different group must not steal
-    /// the answer. And a group with no face under the column is the client's `−1` — silent — not an
-    /// invitation to go looking elsewhere.
+    /// The material ray reads the hit face's material inside the group the arbitration chose; a
+    /// group with no face under the column is silent, the client's `-1`.
     #[test]
     fn material_ray_resolves_per_group_and_bounds_checks() {
         let mut model = bare_model();
@@ -932,27 +749,19 @@ mod tests {
         model.group_footprint_bounds = footprint_tri_bounds(&model.group_footprints);
         // A root MOMT: material 0 unauthored ("None"), 1 = Wood (TerrainType 4), 2 = Snow (3).
         model.material_ground_type = vec![10, 4, 3];
-        // Over group 0's floor, asking about group 0: its own face's material.
         assert_eq!(surface_terrain_sample(&model, 0, [0.0, 0.0, 2.0]), Some(4));
-        // The same column asked about group 1 — whose only face is 100 yd away — is silent, and
-        // must NOT wander into group 0's face.
+        // Group 1's only face is 100 yd away: silent, never group 0's face.
         assert_eq!(surface_terrain_sample(&model, 1, [0.0, 0.0, 2.0]), None);
-        // Group 1's own column resolves group 1's material.
         assert_eq!(
             surface_terrain_sample(&model, 1, [103.0, 103.0, 7.0]),
             Some(3)
         );
-        // A material id past the root's MOMT is the bounds check the client doesn't do: silent,
-        // never an out-of-range index.
+        // A material id past the root's MOMT is silent.
         model.material_ground_type = vec![10];
         assert_eq!(surface_terrain_sample(&model, 0, [0.0, 0.0, 2.0]), None);
     }
 
-    /// **The column index never changes a verdict.** Same model, same columns, indexed vs not:
-    /// identical `(group, MOCV, MOPY)` every time — including the exact-z ties the sawtooth field
-    /// manufactures, where the answer depends on the "later face wins" rule the index's ascending
-    /// order preserves. This is what lets the index be a pure accelerator for the lighting lane
-    /// (the 0330/0364 exactness contract, one rung deeper: inside the group, not just at it).
+    /// The column index never changes a verdict, the sawtooth's exact-z ties included.
     #[test]
     fn footprint_column_index_is_exact() {
         let mut model = bare_model();
@@ -981,44 +790,38 @@ mod tests {
         );
     }
 
-    /// The broad phase is a pure skip, never a re-ranking: the verdict with load-derived face
-    /// bounds equals the verdict with NO bounds at all (the fixtures' `Vec::new()` — every group
-    /// scanned). Pins the 0364 footprint cull's exactness contract, the 0330 argument one lane
-    /// over: a column outside a group's face bounds could never have answered.
+    /// The broad phase is a pure skip: the verdict with face bounds equals the verdict with none.
     #[test]
     fn footprint_bounds_cull_is_exact() {
         let mut model = bare_model();
         model.group_footprints = two_group_footprints();
-        // Probe over group 0's face, above it. Unculled baseline first (no bounds).
+        // Over group 0's face; the unculled baseline first.
         let probe = [-1.0, -1.0, 2.0];
         let unculled = footprint_sample(&model, probe);
         assert_eq!(unculled, Some((0, [10, 20, 30], false)));
         model.group_footprint_bounds = footprint_tri_bounds(&model.group_footprints);
         assert_eq!(footprint_sample(&model, probe), unculled);
-        // Between the groups: neither owns the column — both agree on a miss.
+        // Between the groups: both agree on a miss.
         model.group_footprint_bounds = Vec::new();
         assert_eq!(footprint_sample(&model, [50.0, 50.0, 2.0]), None);
         model.group_footprint_bounds = footprint_tri_bounds(&model.group_footprints);
         assert_eq!(footprint_sample(&model, [50.0, 50.0, 2.0]), None);
-        // Below every face: the bounds' min-z leg and the scan agree on a miss.
+        // Below every face: the min-z leg and the scan agree on a miss.
         model.group_footprint_bounds = Vec::new();
         assert_eq!(footprint_sample(&model, [-1.0, -1.0, -1.0]), None);
         model.group_footprint_bounds = footprint_tri_bounds(&model.group_footprints);
         assert_eq!(footprint_sample(&model, [-1.0, -1.0, -1.0]), None);
     }
 
-    /// **The containment attach's upward retry** (`6a908d..6a90c7`): the down leg missed, so the
-    /// segment is re-cast toward `anchor.z + 1000` and the nearest face ABOVE answers — with the
-    /// same group / MOCV / MOPY it would have given from below. This is the leg a GameObject
-    /// resting a hair under its own floor needs; the down-ray lane never takes it (decision 0776).
+    /// The containment attach's upward retry (`0x6a908d`): after a downward miss the nearest face
+    /// above answers, with the group, MOCV and MOPY it gives from below.
     #[test]
     fn the_upward_retry_finds_the_floor_a_sunk_object_sits_under() {
         let mut model = bare_model();
         model.group_footprints = two_group_footprints();
         model.group_footprint_bounds = footprint_tri_bounds(&model.group_footprints);
 
-        // Group 0's face is at z = 0, over the column (-1,-1). Sit 2 cm UNDER it, as a portcullis
-        // spawned below its own slab does.
+        // 2 cm under group 0's face at z = 0, as a portcullis spawned below its own slab sits.
         let sunk = [-1.0, -1.0, -0.02];
         assert_eq!(
             footprint_sample(&model, sunk),
@@ -1030,7 +833,7 @@ mod tests {
             Some((0, [10, 20, 30], false)),
             "the retry finds the slab it is sunk into, and reads the same bake"
         );
-        // From above, the two legs swap roles — the retry must not become a second downward scan.
+        // From above the legs swap roles: the retry must not become a second downward scan.
         let over = [-1.0, -1.0, 2.0];
         assert_eq!(
             footprint_sample(&model, over),
@@ -1041,13 +844,11 @@ mod tests {
             None,
             "nothing above the probe, so the retry declines rather than re-finding the floor"
         );
-        // The upward leg honours the broad phase the same way: group 1's face (z = 5) sits far off
-        // in XY, so a column that misses it in XY misses it looking up too.
+        // The upward leg honours the broad phase: group 1's face (z = 5) is off this column in XY.
         assert_eq!(footprint_sample_above(&model, [-1.0, -1.0, 1.0]), None);
     }
 
-    /// The derived bounds cover only vertices a face actually references — an orphan vertex
-    /// (parsed but unindexed) must not inflate the cull box.
+    /// The derived bounds cover only vertices a face references: an orphan must not inflate them.
     #[test]
     fn footprint_bounds_ignore_unreferenced_vertices() {
         let mut fps = two_group_footprints();
diff --git a/crates/benilla-world/src/wmo_portal/mod.rs b/crates/benilla-world/src/wmo_portal/mod.rs
index d3afd34d..9eebc0ed 100644
--- a/crates/benilla-world/src/wmo_portal/mod.rs
+++ b/crates/benilla-world/src/wmo_portal/mod.rs
@@ -1,34 +1,21 @@
-//! WMO portal-based visibility culling — the per-frame pass that decides which of a building's groups
-//! are reachable through portals from the camera's current group, so an interior the camera can't see
-//! through any doorway (the Stormwind cathedral above the Trade District) is not drawn.
+//! WMO portal culling: each frame, which of a building's groups are reachable through portals from
+//! the camera's current group.
 //!
-//! This is the **faithful** mechanism, re-derived from `WoW.exe` 5875 (`wow-5875-re`
-//! `system/models/models.md` → "WMO portal-based visibility culling", VERIFIED). The client carries a
-//! 2-D screen rectangle as its working frustum and floods the portal graph from the camera's group:
-//! for each portal it (1) tests the camera is on the portal's front side, (2) projects the portal
-//! polygon to a screen rect, (3) intersects that with the incoming rect, and (4) recurses into the
-//! neighbour with the narrowed rect — terminating a branch the moment the rect collapses to zero area.
-//! That collapse is exactly why the cathedral culls from the Trade District but draws from the gates.
+//! The 1.12 client's recursion (`0x6b41c0`) floods the portal graph from the camera's group with a
+//! screen rect as its frustum: per portal it tests that the camera is on the front side, projects
+//! the portal to a screen rect, intersects that with the carried rect and recurses with the result,
+//! ending a branch when the rect collapses. That is why the Stormwind cathedral culls from the
+//! Trade District but draws from the gates.
 //!
-//! Exterior shells: a building's outer-shell group (an inn's walls/roof) often carries **no portals**, so
-//! the interior flood can't reach it. The client draws exterior groups from inside via a separate
-//! *deferred-window* pass, **gated** on the flood having reached a doorway onto the outdoors
-//! (`wow-5875-re` `wmo-insideleg-phase3.md`): reach none and the whole pass is skipped — you can't
-//! see out. Reach one and, **per window**, every `0x8` group visible in a frustum clipped to that
-//! doorway becomes a **flood root of its own** (`0x6b3d39 call 0x6b41c0` — the same recursion, not a
-//! draw), carrying that window's rect onward through the graph. So a doorway shows you the courtyard
-//! beyond it *and* what the courtyard's own portals show, narrowing all the way (decision 1853).
+//! From inside, exterior shells draw only through deferred windows, doorways the flood reached onto
+//! an `0x8` group (none skips the pass, `0x6b3c87`): per window, every `0x8` group inside a frustum
+//! clipped to that doorway becomes a flood root (`0x6b3d39 call 0x6b41c0`), carrying its rect on.
 //!
-//! Seam: this module only **computes** the per-group visible set ([`WmoPortalInstance::visible`]). The
-//! single `Visibility` authority ([`crate::debug_panel`]'s `apply_model_visibility`, decision 0025)
-//! reads it and ANDs it with the dev toggles + the far-clip cull — we never write `Visibility` here.
-//!
-//! Current-group seed: the **downward raycast** in [`seed`] — the byte-audited client mechanism
-//! (`wow-5875-re` `wmo-current-group.md` + `wmo-portal-audit.md`): walking-collision faces race portal
-//! crossings under the eye, and the verdict is a **seed set** (in-group + across-group), each flooded
-//! as an independent root. The epsilons here (side test exactly `0.0`, rect collapse `0.001`, the
-//! `w`-clamp pair, the `0.1` near-parallel snap) are the client's own constants, read from the binary
-//! — do not "fix" them to tolerances without re-deriving there first.
+//! This module computes each group's visible bit ([`WmoPortalInstance::visible`]); the one
+//! `Visibility` authority, `crate::model_render`'s `apply_model_visibility`, ANDs it with the rest.
+//! The seed is the down-ray in [`seed`]. The epsilons here (the side test at exactly `0.0`, rect
+//! collapse `0.001`, the `w`-clamp pair, the `0.1` near-parallel snap) are the client's own: do
+//! not loosen them into tolerances.
 
 use std::sync::Arc;
 
@@ -49,8 +36,8 @@ use interior::{track_area_interior, track_current_interior, track_unit_interiors
 pub use interior::{
     CurrentAreaInterior, CurrentWmoInterior, PlayerWmoRoom, UnitWmoRoom, WmoInteriorKeys,
 };
+use probe::TraceLog;
 pub use probe::WmoCullProbe;
-use probe::{TraceLog, PROBE_DUMP_PATH};
 pub use room_vis::room_pvs_visible;
 use seed::dominant_axes;
 pub use seed::{down_ray_seeds, floor_z_at, DownRaySeeds};
@@ -64,105 +51,73 @@ use bevy::camera::Projection;
 use bevy::math::{Affine3A, Vec4};
 use bevy::prelude::*;
 
-/// MOGP EXTERIOR flag — an "outdoor" group. The flood defers these to the open world rather than
-/// treating them as portal-gated interiors (and seeds the outside leg from them).
+/// MOGP EXTERIOR, an outdoor group: it seeds the outside leg, and a portal onto one opens a window.
 const EXTERIOR: u32 = 0x8;
 
-/// MOGP EXTERIOR_LIT flag — an interior-graph group lit as OUTDOORS. The unit light classify
-/// (`0x6a87f0`) forks its LIGHTING class on `MOGI & 0x48` — `0x8` **or** `0x40` → the exterior leg
-/// (`or [node+0xc],0x4`: sun diffuse × the MCSH-driven 2.5/0.5 intensity, scene fog) — while the
-/// zone-text indoor bit (`[node+0x90]` bit 0) keys on `0x8` alone, so a `0x40`-only group is
-/// "indoors" for area naming but sunlit (wow-re `zonetext-indoor-bit.md` §b,
-/// `m2-interior-doodad-base-light.md` §the-classify, `unit-m2-shader-light.md`). The city street
-/// WMOs are exactly this: Stormwind's streets (115 of 306 groups) and Orgrimmar's valleys are
-/// `0x40`-without-`0x8` (decision 0475).
+/// MOGP EXTERIOR_LIT, an interior-graph group lit as outdoors: the unit light classify (`0x6a87f0`)
+/// takes the exterior leg on `MOGI & 0x48`, the zone-text bit on `0x8` alone. Stormwind's streets
+/// (115 of 306 groups) and Orgrimmar's valleys are `0x40` without `0x8`.
 const EXTERIOR_LIT: u32 = 0x40;
 
-/// Eye-on-portal-plane band (WMO yards): an eye within this of a portal's plane **and inside its
-/// polygon** gets the full-screen rect for that portal (the client's `0x6b46f0` special case, band
-/// `|d| <= 0.01` at `0x8029d0`). The side test still runs — the recorded "skip the side test" flag is
-/// dead code in the client (`wow-5875-re` `wmo-portal-audit.md` Q1 correction).
+/// Eye-on-portal-plane band (yd): an eye this close to a portal's plane and inside its polygon gets
+/// the full-screen rect (`0x6b46f0`, `|d| <= 0.01` at `0x8029d0`). The side test still runs: the
+/// recorded skip flag is dead code (`0x6b43c9`).
 const ON_PLANE_EPS: f32 = 0.01;
-/// The `|w|` band below which a clip-space vertex's `w` is substituted before the perspective divide —
-/// the client's `0x801360` (`0.001`), strict `<`.
+/// The `|w|` band below which a clip-space vertex's `w` is substituted before the divide
+/// (`0x801360`, `0.001`, strict `<`).
 const W_CLAMP_BAND: f32 = 0.001;
-/// The substituted `w` — **positive regardless of the vertex's sign** (the client's `1e-5` immediate
-/// `0x3727c5ac`). A vertex with `w <= -0.001` is NOT clamped: it divides by its real negative `w`.
+/// The substituted `w`, positive whatever the vertex's sign (the `1e-5` immediate `0x3727c5ac`); a
+/// vertex with `w <= -0.001` divides by its real negative `w`.
 const W_CLAMP_SUB: f32 = 1.0e-5;
-/// Minimum NDC extent for a narrowed screen rect to count as non-empty — the client's zero-area eps
-/// `0x801360` (`0.001`); a collapsed window kills the branch.
+/// Minimum NDC extent of a narrowed rect (`0x801360`, `0.001`); a collapse kills the branch.
 const RECT_EPS: f32 = 0.001;
-/// Ray-vs-plane near-parallel threshold on the denominator (the client's f64 `0x811658` = `0.0001`):
-/// below it, the down-ray is parallel to the portal plane and the crossing exists only via the snap.
+/// Near-parallel threshold on the ray-plane denominator (the f64 `0x811658`, `0.0001`): below it
+/// the down-ray crosses a portal only through the snap.
 const PORTAL_NEAR_PARALLEL: f32 = 1.0e-4;
-/// The "eye embedded in the plane" snap window (yd) for a near-parallel portal (the client's `0.1`
-/// immediate pushed at `0x6a40c0`): a vertical doorway counts as crossed by the vertical down-ray only
-/// while the eye is within this of its plane.
+/// The snap window (yd) for a near-parallel portal (the `0.1` pushed at `0x6a40c0`): a vertical
+/// doorway counts as crossed only while the eye is this close to its plane.
 const PORTAL_PLANE_SNAP: f32 = 0.1;
-/// Nearest-crossing accept eps for the portal leg (the client's `0x80c4f4` ≈ `1e-4`): a portal crossing
-/// within this of the running nearest face hit still wins — a floor-hole portal coincident with the
-/// slab's collision faces flips the room at the plane.
+/// Nearest-crossing accept eps for the portal leg (`0x80c4f4`, about `1e-4`): a portal crossing
+/// this close to the nearest face hit still wins, so a floor-hole portal flips the room.
 const NEAREST_TIE_EPS: f32 = 1.0e-4;
-/// MOGI/MOGP `0x10000` — the **callback-pass** group. The reference draws these in a third pass of
-/// its own (`0x6b3d6f..0x6b3dbc`), against the FULL camera frustum and gated on nothing, and Pass 2
-/// explicitly skips them (`0x6b3d0b`). Both passes read the bit off MOGI; benilla's
-/// [`WmoGroupNav::flags`] is MOGP, which wow-re verified is a strict SUPERSET of MOGI differing by
-/// exactly `0x1|0x4|0x200|0x800|0x1000` in all 5219 shipped groups — so the two agree on this bit
-/// and on [`EXTERIOR`], which is why reading MOGP here is safe.
-///
-/// 24 groups in 1.12 carry it: 14 in `stormwind.wmo` (the canals and the tall district shell),
-/// 6 across the two Dire Maul roots, and the 4 Razorfen enclosing shells that also carry `0x8`.
+/// MOGI/MOGP `0x10000`, the callback-pass group: drawn in a third pass (`0x6b3d6f..0x6b3dbc`)
+/// against the full camera frustum, gated on nothing, and skipped by Pass 2 (`0x6b3d0b`). Both
+/// passes read MOGI; [`WmoGroupNav::flags`] is MOGP, which differs only by
+/// `0x1|0x4|0x200|0x800|0x1000` in all 5219 shipped groups (the loader `0x6c4530`), so the two
+/// agree here and on [`EXTERIOR`]. 24 groups carry it: 14 in `stormwind.wmo`, 6 in Dire Maul and
+/// the 4 Razorfen enclosing shells.
 const CALLBACK_PASS: u32 = 0x10000;
-/// The client's deferred-window worklist is a **fixed 16 records with no bound check** (`0x6b37b0`);
-/// nothing in the shipped data comes near it. We do not reproduce the overflow — emulating a buffer
-/// overrun is not fidelity — but we do watch the number, because a flood producing more windows than
-/// the reference's own designers left room for is far more likely to be OUR bug than the data's
-/// (decision 1148: one Trade District room once opened eleven windows onto Elwynn).
+/// The client's deferred-window worklist holds a fixed 16 records with no bound check
+/// (`0x6b37b0`). Shipped data never nears it, so a flood past it is flagged as our bug.
 const WORKLIST_CAP: usize = 16;
-/// Recursion depth cap — the client's own, `[0xcb004c]` seeded from `[0x86b6b8]` = **10**, refreshed
-/// by every `depth = 0` entry (so Pass 2's re-seeds each get a fresh ten hops, RE 2026-09-02). Ours
-/// was a guessed backstop of 64 until the byte read; dropping it to the real number changes nothing
-/// measurable in any audited building — Darnassus's walk-on gain is identical at 10 and 64, and all
-/// 13 real-data sweeps are unmoved — which is the answer you want from a cap: it is a cycle
-/// backstop, not a visibility term.
+/// Recursion depth cap, the client's own: `[0xcb004c]` seeded from `[0x86b6b8]` = 10 at every
+/// depth-0 entry, so each Pass-2 root gets ten fresh hops. A cycle backstop, not a visibility term.
 const DEPTH_CAP: u32 = 10;
-/// Hard cap on flood iterations — a runaway-graph backstop; real WMOs settle far below this.
+/// Hard cap on flood iterations, a runaway-graph backstop; real WMOs settle far below it.
 const MAX_ITERS: u32 = 1 << 16;
 
-/// An NDC axis-aligned rectangle `[min_x, min_y, max_x, max_y]` — the "screen frustum" carried through
-/// the flood. The full screen is `[-1, -1, 1, 1]`.
+/// An NDC rectangle `[min_x, min_y, max_x, max_y]`, the screen frustum the flood carries.
 pub(crate) type Rect = [f32; 4];
 const FULL_SCREEN: Rect = [-1.0, -1.0, 1.0, 1.0];
 
-/// The **deferred exterior-window worklist** — the doorways through which the outdoor world is
-/// allowed to draw this frame, as NDC rects ([`Rect`]).
-///
-/// This is the client's `[0xcbe324]` list (count `[0xcbe320]`, stride `0x14` =
-/// `{x0, y0, x1, y1, portalMaxPlaneDist}` in 0..1 screen space), which the world-scene driver
-/// `0x681070` copies into `0xc7cb7c` and then walks **once per window**, with the frustum narrowed to
-/// that window's rect. `0x682fa0` is the only producer for every exterior bucket, so no window in
-/// frame means no exterior content at all (`0x681199 jbe 0x681204` skips the whole walk on count 0).
-///
-/// [`Self::Unrestricted`] is the driver's **outside leg** (`0x6811ca`): with no containing WMO the
-/// client runs one populate walk against the literal full-screen rect, i.e. the ordinary view frustum.
+/// The deferred exterior-window worklist: the doorways the outdoor world may draw through this
+/// frame, as NDC rects. The client's `[0xcbe324]` list (count `[0xcbe320]`), which the scene
+/// driver `0x681070` copies to `0xc7cb7c` and walks once per window, the frustum narrowed to it;
+/// `0x682fa0` is the only exterior producer, so no window means no exterior content (`0x681199`).
 #[derive(Resource, Default, Clone, PartialEq, Debug)]
 pub enum ExteriorWindows {
-    /// The camera is not inside a WMO interior — the whole frustum is the window.
+    /// The driver's outside leg (`0x6811ca`): no containing WMO, the whole frustum is the window.
     #[default]
     Unrestricted,
-    /// The camera is inside. Exterior content draws only where it survives one of these sub-frusta;
-    /// **empty means nothing exterior draws**, which is the sealed-room case and is correct.
+    /// The camera is inside: exterior content draws only where it survives one of these, and an
+    /// empty list, the sealed room, draws none.
     Windows(Vec<Rect>),
 }
 
-/// Static tag on every portal-culled WMO piece — a group render submesh, a group's MLIQ surface, a
-/// MODD prop — naming which placement instance it belongs to and which absolute group indices can
-/// draw it, so the visibility authority can look up their per-frame PVS bits.
-///
-/// Geometry and liquid belong to exactly one group. A **prop** can be named by many: the reference
-/// draws doodads per *visible* group out of that group's own MODR, so every referrer is an
-/// independent chance to be drawn (see [`Self::drawn_by`]). Built once per group/prop at spawn, so
-/// the `Arc` is one allocation per key, not one per submesh.
+/// Tag on every portal-culled WMO piece (a group submesh, a group's MLIQ surface, a MODD prop): its
+/// placement instance and the absolute groups that can draw it. Geometry and liquid belong to one
+/// group; a prop can be named by many, as the reference admits a prop from any visited group whose
+/// MODR names it. Built once per group or prop at spawn.
 #[derive(Component, Clone)]
 pub struct WmoGroupVis {
     pub(crate) instance: Entity,
@@ -195,39 +150,25 @@ impl WmoGroupVis {
             .any(|&g| inst.visible.get(g as usize).copied().unwrap_or(true))
     }
 
-    /// The interior-fog verdict: this piece takes the building's MFOG triple iff **any** naming
-    /// group does ([`WmoPortalInstance::interior_fog`], the client's `[0xca7f00]`). ORed for the
-    /// same reason `drawn_by` ORs — a prop several rooms name is drawn from any of them, so it
-    /// wears the fog of any of them. A lookup miss reads FALSE, the opposite of `drawn_by`'s
-    /// fail-open: a missing bit here must not paint a room's fog onto the open world, and the scene
-    /// fog is what every un-gated surface already wears.
+    /// Takes the building's MFOG triple iff any naming group does (the client's `[0xca7f00]`,
+    /// [`WmoPortalInstance::interior_fog`]). A miss reads false, unlike `drawn_by`: a missing bit
+    /// must not paint a room's fog onto the open world.
     pub fn interior_fogged_by(&self, inst: &WmoPortalInstance) -> bool {
         self.groups.iter().any(|&g| inst.fogs_group(g))
     }
 }
 
-/// **Is a room-bound RIDER drawn this frame?** — [`WmoGroupVis::drawn_by`] resolved for the lanes
-/// that carry their rooms *by value* rather than as a component, because their entity is not a
-/// model submesh: a prop's particle clouds and ribbon trails
-/// ([`crate::particles::EmitterFade::room_admitted`]) and a building's point-light sources
-/// ([`crate::lighting::LightRooms`]).
+/// Is a room-bound rider drawn this frame? [`WmoGroupVis::drawn_by`] for lanes that carry their
+/// rooms by value: a prop's particles and ribbons
+/// ([`crate::particles::EmitterFade::room_admitted`]) and a building's point lights
+/// ([`crate::lighting::LightRooms`]). The reference admits a WMO prop only in frames the portal
+/// walk visits its group (`0x6838f0`, from the visit callback `0x685d70`), so a prop in a culled
+/// room is neither drawn, animated nor particle-ticked.
 ///
-/// Every one of them exists for the same reason. The reference instantiates a WMO's furniture out
-/// of each **visible** group's own MODR list (`0x695aa0` from the visible-group walk `0x698720`,
-/// decision 0689), so a prop in a culled room is never created and has nothing to tick, draw or
-/// light with. We create props once and cull them per frame, so each rider has to ask for itself —
-/// and this is where the question is spelled, once, for all of them.
-///
-/// - **No rooms** — admitted. An ADT map doodad, a creature, a held item: nothing claims it.
-/// - **Rooms, placement resident** — `drawn_by`: the identical predicate the owner's own submeshes
-///   are culled by, so a model and its riders can never disagree about which frame they are in.
-/// - **Rooms, placement gone** — refused, where `drawn_by` itself fails OPEN. Deliberate, and the
-///   one asymmetric arm: a rider outlives its building by the frame between the placement
-///   despawning and the cascade reaching it, and one frame of an additive strip — or a torch —
-///   hanging where a building used to be is a bright artefact, where one frame of a missing one is
-///   nothing at all. [`crate::skybox`]'s skybox resolve refuses on the same asymmetry, and 1276 is
-///   the general rule: an unknown with a testable answer must be tested, but where the error
-///   directions are lopsided, take the cheap one.
+/// - No rooms: admitted (an ADT doodad, a creature, a held item).
+/// - Rooms, placement resident: `drawn_by`, the predicate the owner's submeshes are culled by.
+/// - Rooms, placement gone: refused, where `drawn_by` fails open. A rider outlives its building by
+///   a frame, and a stray bright strip or torch is an artefact where a missing one is nothing.
 pub fn room_admits(room: Option<&WmoGroupVis>, instance: Option<&WmoPortalInstance>) -> bool {
     match (room, instance) {
         (None, _) => true,
@@ -236,58 +177,38 @@ pub fn room_admits(room: Option<&WmoGroupVis>, instance: Option<&WmoPortalInstan
     }
 }
 
-/// One placed WMO building's portal-cull state. Spawned alongside the building's geometry; despawns
-/// with the placement (it's pushed into the placement's entity list).
+/// One placed WMO's portal-cull state, spawned with its geometry and despawned with the placement.
 #[derive(Component)]
 pub struct WmoPortalInstance {
-    /// The building asset (portal graph + per-group nav).
+    /// The building asset (portal graph and per-group nav).
     pub handle: Handle<WmoModel>,
-    /// Placement transform as Bevy **model→world**. A portal vertex is WoW model space, so it reaches
-    /// world via `world_from_local * wow_to_bevy(v)` — the same path `build_submesh_mesh` bakes the
-    /// rendered geometry through, so portals and walls live in one space.
+    /// Placement transform, Bevy model→world: a WoW-space portal vertex reaches world as
+    /// `world_from_local * wow_to_bevy(v)`, the path the rendered geometry takes.
     pub world_from_local: Affine3A,
-    /// The placement's `MODF.nameSet` — the `WMOAreaTable.NameSetID` audio/naming variant
-    /// (one abbey model serves Northshire and Tyr's Hand by name set).
+    /// The placement's `MODF.nameSet`, the `WMOAreaTable.NameSetID` variant (one abbey model
+    /// serves Northshire and Tyr's Hand by name set).
     pub name_set: u16,
-    /// Per-group visibility (indexed by absolute group index) for this frame; `true` = in the portal
-    /// PVS. Seeded all-`true` (everything shows until the first compute, and forever for portal-less
-    /// props).
+    /// Per-group PVS bit this frame, by absolute group index; seeded all-true, which a portal-less
+    /// prop keeps.
     pub visible: Vec<bool>,
-    /// Per-group **interior-fog** gate for this frame (the client's `[0xca7f00]`): `true` = this
-    /// group's surfaces and its doodads draw with the building's MFOG triple, `false` = they
-    /// inherit the scene fog. Computed by the same flood as `visible` — see [`GroupPvs`] for the
-    /// rule and the byte cites. Seeded all-`false`: nothing wears a room's fog until a flood says
-    /// so, and a portal-less prop (which never floods) never does.
+    /// Per-group interior-fog gate this frame (the client's `[0xca7f00]`, see [`GroupPvs`]): `true`
+    /// draws the group and its doodads with the building's MFOG triple, `false` with the scene fog.
+    /// Seeded all-false, which a portal-less prop keeps.
     pub interior_fog: Vec<bool>,
-    /// Per-group **ever-visited** latch — the client's render-record persistence (wow-re
-    /// `wmo-record-persistence.md`, landed wow-re main @`00a766f6`): the visit callback `0x685d70`
-    /// creates a per-(instance,group) record the first time the flood visits a group, the record
-    /// pools are cleared only at world init/teardown, and a recorded MLIQ group's **liquid surface
-    /// draws every frame with no portal/frustum re-check** (`0xc7cb04` list, walk `0x684cd0 →
-    /// 0x6b62e0`). So liquid is gated on *ever seen*, not on this frame's PVS — the Great Forge's
-    /// walkway-level pool must not vanish when its group drops out of the flood. Latched by
-    /// [`compute_wmo_pvs`] from `visible`; starts all-`false` (a never-visited group's liquid is
-    /// genuinely absent in the reference until first visit). Lifetime is the placement's residency,
-    /// not the world session — a restreamed placement re-latches from the first flood, a small
-    /// divergence from the client's global pools noted in the B65 decision record.
+    /// Per-group ever-visited latch: once the flood visits a group, its MLIQ surface draws for the
+    /// rest of the placement's residency, whatever this frame's PVS. Latched by
+    /// [`compute_wmo_pvs`]; starts all-false.
     pub liquid_visited: Vec<bool>,
-    /// Per-group **whole-group submersion** (indexed by absolute group index), from the group's
-    /// MOGP `groupLiquid` override: `Some(kind)` means standing anywhere inside this group is
-    /// standing under liquid — at every Z, with no surface grid involved at all.
-    ///
-    /// Baked at spawn rather than resolved per query because it is a property of the *room*, and
-    /// the room is already what the liquid query carries ([`crate::liquid::LiquidClaim`]). Empty on
-    /// a placement spawned before its model resolved.
+    /// Per-group whole-group submersion from MOGP `groupLiquid`: `Some(kind)` means anywhere in the
+    /// group is under liquid, at every z. Baked at spawn; empty on a placement spawned before its
+    /// model resolved.
     pub flooded: Vec<Option<benilla_formats::LiquidKind>>,
 }
 
 impl WmoPortalInstance {
-    /// **Is one group on this frame's interior-fog chain?** — the client's `[0xca7f00]` read for a
-    /// single group, which is the grain every consumer of the gate actually asks at: a WMO piece
-    /// ORs it over the groups that name it ([`WmoGroupVis::interior_fogged_by`]), and a unit asks
-    /// it of the one room its light node attached to (`crate::interior`, the `[P+0x98]` conjunct
-    /// of decision 1792 §4). A group past the set reads FALSE — see `interior_fogged_by` for why
-    /// this one fails closed where `drawn_by` fails open.
+    /// The `[0xca7f00]` bit for one group, the grain every consumer asks at: a WMO piece ORs it
+    /// over its groups, a unit asks it of the room its light node attached to. A group past the set
+    /// reads false.
     pub fn fogs_group(&self, group: u16) -> bool {
         self.interior_fog
             .get(group as usize)
@@ -296,15 +217,10 @@ impl WmoPortalInstance {
     }
 }
 
-/// One WMO **room**: a placed building's instance entity plus the absolute group index inside it.
-///
-/// This is the client's `[0xc7b748]` (the camera-containing placed map-object — wow-re
-/// `models/scratch/wmo-current-group.md`) paired with the current group index its visible-group set
-/// `0xc7cd88` carries. It is the identity every "which room is this subject in" answer resolves to,
-/// and — since decision 0696 — the **scope key of the liquid query**: a building's pool belongs to a
-/// room, so only a subject standing in that placement can be in it. A liquid footprint has no floor,
-/// so without an owner a pool claims every position under its XY forever, in any building, at any
-/// depth (Uldaman read as submerged under a *mushroom cave's* water 186 yd overhead).
+/// One WMO room: a placement's instance entity and an absolute group index in it, the client's
+/// `[0xc7b748]` (the camera's containing placed map object) with the group its containing-group
+/// set `0xc7cd88` carries. It is also the liquid query's scope key: a liquid footprint has no
+/// floor, so an unowned pool would claim every position under it.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct WmoRoom {
     /// The placement's [`WmoPortalInstance`] entity.
@@ -313,35 +229,28 @@ pub struct WmoRoom {
     pub group: u16,
 }
 
-/// The camera's PVS-flood interior claim this frame — `None` with the camera over open world or
-/// an EXTERIOR (`0x8`) group's floor; an EXTERIOR_LIT-only porch (`0x40`) still claims (the
-/// `[0xc7b748]` writer's 0x8-only rejection, round-6 Q-H(c)). Written by [`compute_wmo_pvs`] off
-/// the same down-ray seed the flood runs; consumed by the weather-visible gate
-/// (`weather::precip`) and by the camera-eye submersion verdict (`liquid::detect_submersion` —
-/// the reference's per-frame environment probe `0x6809c0` picks the WMO group's MLIQ over the ADT
-/// liquid on exactly this global, wow-re `terrain/scratch/fog-env-state.md` §1).
-/// When `Some`, `exterior_visible` reports whether this placement's flood
-/// reached an EXTERIOR-flagged group (`flags & 0x148`) through a screen-rect-surviving portal
-/// window — the carved pass-2 law of the weather flag `[0xca80c4]` (`0x6b42d9`, round-6 Q-H(a)):
-/// rain stays visible — and falling — through a doorway the camera can SEE; face away and the
-/// window clips out, killing the draw that frame (view-dependent by design).
+/// The camera's interior claim this frame: `None` over the open world or an EXTERIOR (`0x8`)
+/// group's floor, while an EXTERIOR_LIT-only porch still claims (the `[0xc7b748]` writer rejects on
+/// `0x8` alone, `0x6be451`). Written by [`compute_wmo_pvs`] from the flood's own seed; the
+/// reference's environment probe `0x6809c0` picks the WMO group's MLIQ over the ADT liquid on it.
 #[derive(Resource, Default, Clone, Copy, PartialEq)]
 pub struct CameraInteriorClaim(pub Option<InteriorClaim>);
 
 /// See [`CameraInteriorClaim`].
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct InteriorClaim {
-    /// The room the camera EYE is in — the placement + its current group.
+    /// The room the camera eye is in: the placement and its current group.
     pub room: WmoRoom,
-    /// An EXTERIOR-flagged group (`flags & 0x148`) is in the claiming placement's PVS.
+    /// A group with any of `0x148` is in the placement's PVS: the weather flag `[0xca80c4]`
+    /// (`0x6b42d9`), so rain shows through a doorway the camera can see.
     pub(crate) exterior_visible: bool,
 }
 
-/// Ordering handle so the `Visibility` authority can run **after** the PVS is computed this frame.
+/// Ordering handle so the `Visibility` authority runs after this frame's PVS.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct WmoPvsSet;
 
-/// Registers the per-frame PVS compute. The apply side lives in [`crate::debug_panel`].
+/// Registers the per-frame PVS compute; the apply side is `crate::model_render`'s.
 pub struct WmoPortalPlugin;
 
 impl Plugin for WmoPortalPlugin {
@@ -366,22 +275,19 @@ impl Plugin for WmoPortalPlugin {
                 track_unit_interiors,
             )
                 .in_set(WmoPvsSet)
-                // **On this frame's camera pose, not last frame's** (decision 1503). The flood,
-                // the interior claim and the exterior windows all key on the eye, and every one of
-                // them decides what the frame is allowed to draw. Unordered, this set could even
-                // run before the controller had moved the camera at all; ordered here it answers
-                // about the eye the frame will be rendered from.
+                // On this frame's camera pose: the flood, the claim and the windows key on the eye
+                // and decide what the frame may draw.
                 .after(crate::view::CameraPoseSet),
         );
     }
 }
 
-/// Max drop (yd) for the current-group down-ray: a floor more than this far below the eye doesn't count
-/// as "the room you're in" (you're over open space ⇒ outside). Matches the client's ray length (`1760`).
+/// Max drop (yd) for the current-group down-ray, the client's ray length: a floor further below
+/// is not the room you are in.
 const MAX_FLOOR_DROP: f32 = 1760.0;
 
-/// Recompute each resident WMO's per-group visible set from the camera. Cheap: a handful of buildings,
-/// each a small portal flood; a portal-less prop just stays all-visible.
+/// Recompute each resident WMO's per-group visible set from the camera; a portal-less prop stays
+/// all-visible.
 fn compute_wmo_pvs(
     wmos: Res<Assets<WmoModel>>,
     cam: Query<(&GlobalTransform, &Projection), With<WorldCamera>>,
@@ -393,28 +299,25 @@ fn compute_wmo_pvs(
     mut camera_claim: ResMut<CameraInteriorClaim>,
     mut camera_windows: ResMut<ExteriorWindows>,
 ) {
-    // The world Camera3d (the egui overlay is a Camera2d). None before it spawns ⇒ leave last frame's
-    // sets untouched (everything was visible, which is the safe default).
+    // No world camera yet: keep last frame's sets, all visible.
     let Some((cam_t, proj)) = cam.iter().next() else {
         return;
     };
     let clip_from_world = proj.get_clip_from_view() * cam_t.to_matrix().inverse();
     let eye_world = cam_t.translation();
-    // Publish the pose this authority ran on (see [`WmoCullProbe::eye`]).
     probe.eye = eye_world;
-    // The terrain leg of the seed's down-ray, sampled once for the camera's column: the client casts the
-    // same segment at the ground and drops the WMO hit when the ground is nearer (`FUN_006821f0`).
+    // The seed's terrain leg, sampled once for the camera's column (`0x6821f0`).
     let terrain = terrain_height_under(&streamer, &adt_tiles, eye_world);
-    // `WOW_CULLDUMP=1` re-requests the dump every frame (last writer wins): a headless capture has
-    // no panel button, and the first frames race asset residency, so a one-shot request from
-    // startup would photograph an empty world.
-    static ENV_DUMP: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
-    let dump = std::mem::take(&mut probe.dump_requested)
-        || *ENV_DUMP.get_or_init(|| std::env::var_os("WOW_CULLDUMP").is_some());
-    // The camera pose IN FULL: replaying a dump in the pin probe needs forward + fov + aspect, not
-    // just the eye — B65's first dump recorded only the eye and the replay had to reconstruct the
-    // look from the player's position.
-    let mut dump_text = dump.then(|| {
+    // `WOW_CULLDUMP=<path>` re-requests the dump every frame, last writer wins: a headless run has
+    // no panel button, and a one-shot request at startup would catch an empty world.
+    static ENV_DUMP: std::sync::OnceLock<Option<std::path::PathBuf>> = std::sync::OnceLock::new();
+    let dump_to = probe.dump_to.take().or_else(|| {
+        ENV_DUMP
+            .get_or_init(|| std::env::var_os("WOW_CULLDUMP").map(std::path::PathBuf::from))
+            .clone()
+    });
+    // The full camera pose: replaying a dump needs forward, fov and aspect, not just the eye.
+    let mut dump_text = dump_to.is_some().then(|| {
         let fwd = cam_t.forward();
         let (fovy, aspect) = match proj {
             Projection::Perspective(p) => (p.fov, p.aspect_ratio),
@@ -423,27 +326,22 @@ fn compute_wmo_pvs(
         format!("eye world: {eye_world:?}\nforward: {fwd:?} fovy {fovy:.4} aspect {aspect:.4}\n")
     });
 
-    // The camera's MFOG fog target + interior claim — resolved from the same down-ray seed the
-    // flood runs anyway (see [`fog`]); the first placement whose seed claims a TRUE INTERIOR
-    // group wins both.
+    // The fog target and the claim come from the flood's own seed; the first placement whose seed
+    // claims a non-exterior group wins both.
     let mut fog_target: Option<WmoFogTarget> = None;
     let mut claim: Option<InteriorClaim> = None;
-    // `None` here = the driver's outside leg (no containing map object): one full-screen walk.
+    // `None` is the driver's outside leg: no containing map object, one full-screen walk.
     let mut windows: Option<Vec<Rect>> = None;
     for (entity, mut inst) in &mut instances {
         let Some(model) = wmos.get(&inst.handle) else {
             continue;
         };
         let groups = model.group_nav.len();
-        // A WMO with no portal graph (single-group props, doors) is never culled — keep all groups on.
-        // Written through the change gate below like the flood's own answer: this branch used to
-        // deref-mut every portal-less prop every frame, which marked the whole population changed
-        // and would defeat any future `Changed<WmoPortalInstance>` run condition (the 1364 item-2
-        // precondition) before it was born.
+        // A WMO with no portal graph (single-group props, doors) is never culled, and never on the
+        // interior-fog lane. Written through the change gate: marking every prop changed each frame
+        // would defeat `Changed<WmoPortalInstance>`.
         if model.portal_refs.is_empty() || model.portal_infos.is_empty() {
             let held = inst.bypass_change_detection();
-            // …and never on the interior fog lane: a portal-less prop runs no flood, so there is
-            // no chain to be on (the same reading the fog resolve takes — see [`fog`]'s module doc).
             let mut changed = false;
             if held.visible.len() != groups || held.visible.iter().any(|v| !*v) {
                 held.visible = vec![true; groups];
@@ -459,23 +357,17 @@ fn compute_wmo_pvs(
             continue;
         }
         let world_from_local = inst.world_from_local;
-        // The eye in this WMO's model space (WoW axes): the down-ray origin (seed) and the portal
-        // front-side test point. The down-ray from the camera is robust on its own — a collision-shoved
-        // camera still drops onto the floor beneath it — so there's no player-position seed any more.
+        // The eye in model space (WoW axes): the down-ray origin and the front-side test point.
         let local_from_world = world_from_local.inverse();
         let eye_local = bevy_to_wow(local_from_world.transform_point3(eye_world));
         let terrain_local = terrain.map(|z| terrain_z_local(&local_from_world, eye_world, z));
-        // ONE flood, with whichever recorders are attached — the dump must never change the answer
-        // it is photographing. It used to be an `if dump { trace } else { tap }`, so `WOW_CULLDUMP=1`
-        // skipped the claim/fog/window computation outright and every dumped run reported
-        // `room=none windows=unrestricted` no matter where the camera stood; the trace file said
-        // `seed: in Some(102)` on the same frame. That cost a wrong reading while diagnosing 1148.
+        // One flood with every recorder attached: the dump must never change the answer it records.
         let mut tap = SeedTap::default();
         let mut log = dump_text
             .is_some()
             .then(|| TraceLog::new(model, eye_local, terrain_local));
-        // Compare-then-write (1362's shape): a parked camera's flood answers the same set every
-        // frame, and writing it anyway re-marked every instance changed — see the branch above.
+        // Compare, then write: a parked camera's flood repeats its answer, and a blind write would
+        // mark every instance changed.
         let mut fresh = compute_pvs_traced(
             model,
             eye_local,
@@ -493,8 +385,7 @@ fn compute_wmo_pvs(
             inst.set_changed();
         }
         if let (Some(text), Some(log)) = (&mut dump_text, &log) {
-            // Which building this trace belongs to — the dump lists every placement in range, and
-            // an id alone cannot tell two night-elf houses apart. The origin can.
+            // The origin tells apart two placements of one model in the dump.
             let o = world_from_local.translation;
             text.push_str(&format!(
                 "placement @ world ({:.1}, {:.1}, {:.1}) — {} deferred window(s) {:?}, {} walk steps\n",
@@ -508,12 +399,8 @@ fn compute_wmo_pvs(
             text.push_str(&log.text);
             text.push_str(&format!("visible: {:?}\n\n", inst.visible));
         }
-        // Interior-fog + weather claims off the seed already computed. The claim mask is
-        // bit 0x8 ALONE (`[0xc7b748]` writer `0x6be451/77` tests only EXTERIOR — round 6
-        // Q-H(c)): an EXTERIOR_LIT-only porch/courtyard (`0x40`) still claims the camera
-        // and engages this WMO's MFOG fog; the weather gate reads whether the placement's
-        // flood reached an exterior group (already view-clipped — the deferred-window gate
-        // fires only when the doorway's screen rect survives, the carved pass-1 law).
+        // The claim rejects on `0x8` alone (the `[0xc7b748]` writer, `0x6be451`/`0x6be477`): a
+        // `0x40`-only porch still claims the camera.
         if claim.is_none() {
             if let Some(gi) = tap.in_group {
                 if model
@@ -521,22 +408,10 @@ fn compute_wmo_pvs(
                     .get(gi)
                     .is_some_and(|n| n.flags & EXTERIOR == 0)
                 {
-                    // **The MFOG engagement conjunct** (wow-re `models/scratch/wmo-interior-fog-gate.md`,
-                    // §5 VERIFIED; the byteOut loop `0x69de5f`–`0x69dea0` over the camera's containing
-                    // set `0xc7cd88`): the interior fog target exists only when one of the camera's
-                    // ≤2 CONTAINING groups — the down-ray's in-group and its across-portal partner,
-                    // which is exactly that set — is a TRUE interior, `flags & 0x48 == 0`. In an
-                    // exterior-LIT courtyard the client's `t` decays to 0 and the interior triple
-                    // equals the scene triple; no surface of the building is on the lane either
-                    // (decision 1787), so what this conjunct actually decides is the fog of an
-                    // interior-classified UNIT standing in the building, which reads the triple by
-                    // its own classification and would otherwise wear a courtyard's MFOG.
-                    //
-                    // The candidate walk reads THAT group's own MOGP fog indices (`grp+0x34`), not
-                    // the containing group's unconditionally — a courtyard's indices never engage.
-                    // The interior CLAIM below keeps the `0x8`-alone test it has always had: the
-                    // `[0xc7b748]` writer rejects on EXTERIOR only (round-6 Q-H(c)), and the weather
-                    // gate and the submersion probe both read the claim, not this.
+                    // The MFOG target exists only when one of the camera's containing groups (the
+                    // in-group and across-group, `0xc7cd88`) is a true interior, with no `0x48`
+                    // (the byteOut loop `0x69de5f`–`0x69dea0`). Its candidates come from the
+                    // first such group's fog indices.
                     fog_target = [Some(gi), tap.across]
                         .into_iter()
                         .flatten()
@@ -558,31 +433,16 @@ fn compute_wmo_pvs(
                             .zip(&inst.visible)
                             .any(|(n, v)| *v && n.flags & 0x148 != 0),
                     });
-                    // The deferred exterior-window list is this claiming placement's alone: the
-                    // reference floods the CONTAINING map object (`[0xc7b748]`) and defers that
-                    // flood's windows. It arrives already built — [`GroupPvs::windows`], the same
-                    // list the flood's own Pass 2 tested this building's exterior groups against.
-                    //
-                    // The push test inside it is [`opens_a_window`] — `0x8` ALONE, NOT the `0x148`
-                    // the `exterior_visible` line above reads. Those two are neighbours in the
-                    // binary and neighbours here, and 0774 recorded them as *correlated, not
-                    // equivalent*; the port read `0x148` anyway, which made every
-                    // `0x40`-without-`0x8` group a doorway onto the open world. Stormwind's streets
-                    // are 115 of its 306 groups (decision 0475), so one Trade District room opened
-                    // eleven windows onto Elwynn — decision 1148.
+                    // The exterior windows are the claiming placement's alone: the reference floods
+                    // the containing map object (`[0xc7b748]`) and defers that flood's windows,
+                    // the list Pass 2 already used. Its push test is `0x8` alone
+                    // (`opens_a_window`), not the `0x148` of `exterior_visible` above.
                     windows = Some(std::mem::take(&mut fresh.windows));
                 }
             }
         }
-        // The render-record persistence latch (`liquid_visited` — the client's per-(instance,group)
-        // visit records): a group entering the PVS this frame stays "visited" for the rest of this
-        // placement's residency, and the visibility authority draws its MLIQ surface off THIS latch,
-        // never off the per-frame `visible`.
-        // Through the change gate like the flood's own answer above: this latch used to be
-        // written through `Mut` for every visible building on every frame, which marked the
-        // whole resident population changed and held `Changed<WmoPortalInstance>` open — the
-        // one term of the visibility walk's still-frame skip (1979/1982) that a city can never
-        // satisfy. A slot that actually flips is a PVS change and marks, as `visible` does.
+        // The `liquid_visited` latch, through the change gate: only a slot that flips marks the
+        // instance changed.
         let held = inst.bypass_change_detection();
         let mut latched = false;
         if held.liquid_visited.len() != groups {
@@ -612,33 +472,28 @@ fn compute_wmo_pvs(
     if *camera_windows != want_windows {
         *camera_windows = want_windows;
     }
-    if let Some(mut text) = dump_text {
-        // The frame's published verdict, after every placement has had its say: which room claimed
-        // the camera and what the open world is allowed to draw through. The per-placement traces
-        // above say what each flood found; only this says what the scene actually got.
+    if let Some((mut text, path)) = dump_text.zip(dump_to) {
+        // The frame's published verdict, after every placement: the claim and the windows.
         text.push_str(&format!("CAMERA CLAIM: {:?}\n", camera_claim.0));
         text.push_str(&format!("EXTERIOR WINDOWS: {:?}\n", *camera_windows));
-        match std::fs::write(PROBE_DUMP_PATH, &text) {
-            Ok(()) => info!("wmo cull trace written to {PROBE_DUMP_PATH}"),
-            Err(e) => warn!("wmo cull trace: cannot write {PROBE_DUMP_PATH}: {e}"),
+        // The folder is made only when there is a trace to put in it.
+        if let Some(parent) = path.parent() {
+            let _ = std::fs::create_dir_all(parent);
+        }
+        match std::fs::write(&path, &text) {
+            Ok(()) => info!("wmo cull trace written to {}", path.display()),
+            Err(e) => warn!("wmo cull trace: cannot write {}: {e}", path.display()),
         }
     }
 }
 
-/// The per-frame [`FloodTrace`] tap: the down-ray's in-group seed (the camera's current group), which
-/// the interior-fog resolve reads — no duplicate down-ray.
-///
-/// The deferred windows used to be reconstructed here, by filtering every entered step for an
-/// exterior destination. They are [`GroupPvs::windows`] now — the flood's own output — because the
-/// flood's **Pass 2** needs the identical list to decide which exterior groups draw (decision 1826),
-/// and two filters over the same steps are two places for the push test to drift.
+/// The per-frame [`FloodTrace`] tap: the down-ray's seeds, for the claim and the fog without a
+/// second down-ray.
 #[derive(Default)]
 struct SeedTap {
     in_group: Option<usize>,
-    /// The down-ray's ACROSS-portal seed. With [`Self::in_group`] this is the client's
-    /// `0xc7cd88` — the camera's ≤2 *containing* groups, which the MFOG engagement conjunct
-    /// tests (and which is NOT the flood's visible set, a confusion wow-re corrected in
-    /// `models/scratch/wmo-interior-fog-gate.md`).
+    /// The across-portal seed; with [`Self::in_group`], the client's `0xc7cd88`, the camera's
+    /// containing groups (not the flood's visible set).
     across: Option<usize>,
 }
 impl FloodTrace for SeedTap {
@@ -648,47 +503,33 @@ impl FloodTrace for SeedTap {
     }
 }
 
-/// **The deferred-window push test.** A flood step opens a window onto the OPEN WORLD exactly when
-/// its DESTINATION group carries `0x8` — the recursion resolves the neighbour and tests
-/// `0x6b44f8 test byte [eax+0x10],0x8; 0x6b44fc je <skip-defer>` before pushing the clipped rect into
-/// `[0xcbe324]`/`[0xcbe320]` (wow-re `models/scratch/wmo-insideleg-phase3.md`, "Worklist
-/// provenance", and the record layout in `wmo-antiportal-and-window-record.md` — VERIFIED at the
-/// bytes). **`0xcbe310` is not the array**: the fill's `lea edi,[4*ecx+0xcbe310]` is an addressing
-/// form whose addend is never dereferenced (record 0 is at `0xcbe324`), and `0xcbe310` itself is
-/// the tail of the per-frame view-projection matrix `[0xcbe2d8]+0x38`. wow-re's ledger row for
-/// `0x6b4680` called it the "antiportal quad depth"; that was a Ghidra artifact and is corrected
-/// there now. Nothing else qualifies: not [`EXTERIOR_LIT`], not the weather global's
-/// `0x148` (that mask lives at `0x6b42d0` and drives `[0xca80c4]`, a *correlated but different*
-/// signal — decision 0774 said so and the port read it anyway; decision 1148).
+/// The deferred-window push test: a flood step opens a window onto the open world exactly when its
+/// destination group carries `0x8` (`0x6b44f8 test byte [eax+0x10],0x8` before the push into
+/// `[0xcbe324]`). Not [`EXTERIOR_LIT`], and not the weather flag's `0x148` (`0x6b42d0`, driving
+/// `[0xca80c4]`), a correlated but different signal.
 fn opens_a_window(nav: &[WmoGroupNav], to: usize) -> bool {
     nav.get(to).is_some_and(|n| n.flags & EXTERIOR != 0)
 }
 
-/// A tap on the flood's per-portal decisions. The `()` impl is a no-op the per-frame path uses; the
-/// probe dump and the audit harness pass a real recorder — one flood implementation, no trace copy to
-/// drift.
+/// A tap on the flood's per-portal decisions: `()` is the per-frame no-op, and the probe dump and
+/// the audit harness pass a recorder, so there is one flood and no traced copy.
 pub(crate) trait FloodTrace {
     fn seed(&mut self, _seeds: DownRaySeeds) {}
     fn side_fail(&mut self, _from: usize, _portal: u16, _to: usize, _d: f32) {}
     fn rect_none(&mut self, _from: usize, _portal: u16, _to: usize) {}
     fn rect_collapse(&mut self, _from: usize, _portal: u16, _to: usize) {}
     fn entered(&mut self, _from: usize, _portal: u16, _to: usize, _rect: Rect, _on_plane: bool) {}
-    /// One Pass-2 verdict: an EXTERIOR group tested against the whole deferred worklist. Without
-    /// this, "why is that wall still drawn?" has no reading at all — the flood's own hop lines
-    /// never mention a group no portal reaches, which is exactly the population Pass 2 decides.
+    /// One Pass-2 verdict: an EXTERIOR group against one deferred window.
     fn pass2(&mut self, _group: usize, _flags: u32, _window: usize, _admitted: bool) {}
     /// One Pass-3 verdict: a `0x10000` callback-pass group against the full frustum.
     fn pass3(&mut self, _group: usize, _flags: u32, _admitted: bool) {}
-    /// The flood produced more deferred windows than the reference's fixed worklist holds — a
-    /// tripwire on OUR flood, not a client behaviour (see [`WORKLIST_CAP`]).
+    /// More deferred windows than the reference's worklist holds: a tripwire on our flood
+    /// ([`WORKLIST_CAP`]).
     fn worklist_over_cap(&mut self, _windows: usize) {}
 }
 impl FloodTrace for () {}
 
-/// **Two recorders on one flood.** The per-frame path always needs the [`SeedTap`]; the dump wants a
-/// [`TraceLog`] as well. Pairing them keeps that a single flood — the alternative (branch on "are we
-/// dumping" and run one or the other) is what let `WOW_CULLDUMP=1` silently drop the claim/window
-/// computation and report a room the same trace file contradicted.
+/// Two recorders on one flood: the per-frame [`SeedTap`] and the dump's [`TraceLog`].
 impl<A: FloodTrace, B: FloodTrace> FloodTrace for (&mut A, &mut B) {
     fn seed(&mut self, seeds: DownRaySeeds) {
         self.0.seed(seeds);
@@ -724,7 +565,7 @@ impl<A: FloodTrace, B: FloodTrace> FloodTrace for (&mut A, &mut B) {
     }
 }
 
-/// An absent recorder records nothing — so "attach the dump only when asked" costs no second flood.
+/// An absent recorder records nothing, so the dump costs no second flood.
 impl<T: FloodTrace> FloodTrace for Option<T> {
     fn seed(&mut self, seeds: DownRaySeeds) {
         if let Some(t) = self {
@@ -768,13 +609,9 @@ impl<T: FloodTrace> FloodTrace for Option<T> {
     }
 }
 
-/// The portal flood. Returns the per-group visible set (indexed by absolute group index). `eye_local` is
-/// the camera in WMO model space (WoW axes): it seeds the flood (the group whose floor it stands over —
-/// the down-ray) and drives the per-portal front-side test. `clip_from_world` / `world_from_local`
-/// project a portal vertex (WoW model space) to clip space via `clip_from_world * world_from_local *
-/// wow_to_bevy(v)`. (The per-frame pass now calls [`compute_pvs_traced`] directly with a
-/// [`SeedTap`] — the interior-fog resolve reads the seed — so this trace-less wrapper serves the
-/// audit harness.)
+/// The portal flood's per-group visible set, for the audit harness. `eye_local` is the camera in
+/// WMO model space (WoW axes), the seed and the front-side test point; a portal vertex reaches clip
+/// space as `clip_from_world * world_from_local * wow_to_bevy(v)`.
 #[cfg(test)]
 fn compute_pvs(
     model: &WmoModel,
@@ -794,54 +631,35 @@ fn compute_pvs(
     .visible
 }
 
-/// What one flood publishes per group: this frame's PVS bit, and whether the group draws with the
-/// building's **interior fog** triple rather than the scene fog.
-///
-/// The second is the client's per-group `[0xca7f00]` — the gate on BOTH interior-fog pushes, the
-/// group drawer `0x6b5190` and the group-doodad drawer `0x6b62e0` (wow-re
-/// `lighting/scratch/rf-weather-emission-timeline.md` round-6 Q-I, `terrain/scratch/fog-env-state.md`
-/// §block 2). Decision 0347 modelled the LANE (interior triple on shared-light rows 18-19, selected
-/// by the batch's own `flags & 0x48` interior bit) and recorded this gate as *"not modelled"*; B335
-/// is that gap seen from the Shadowfang courtyard, where the room two exterior-lit courtyards away
-/// wore the building's MFOG teal at 70 yd while the reference showed it under the scene fog.
-///
-/// The rule here: the seed's own group takes the lane (`0x6b3b4c`/`0x6b3df5` force it), and the walk
-/// carries it to a neighbour only while no group on the path has `flags & 0x48` — the interior-chain
-/// anchor breaking at an exterior/exterior-lit group (`0x6b424f` → `0x6b42c6`, QL-1). A `0x48` group
-/// is drawn by the exterior drawer `0x6b4f10`, which pushes no fog at all, so its own bit is inert;
-/// what the break decides is the rooms BEYOND it.
+/// What one flood publishes per group: this frame's PVS bit and the interior-fog bit, the client's
+/// `[0xca7f00]`, which gates both interior-fog pushes (the group drawer `0x6b5190` and the group
+/// liquid drawer `0x6b62e0`). A group takes the fog when the walk reaches it from one of the
+/// camera's containing groups through true interiors only: the recursion's interior-chain anchor
+/// clears at any `flags & 0x48` hop (`0x6b424f` → `0x6b42c6`). A `0x48` group is drawn by the
+/// exterior drawer `0x6b4f10`, which pushes no fog, so the break decides the rooms beyond it.
 pub(crate) struct GroupPvs {
     /// Per absolute group index: in this frame's portal PVS.
     pub(crate) visible: Vec<bool>,
-    /// Per absolute group index: draws with the interior fog triple (the `[0xca7f00]` equivalent).
+    /// Per absolute group index: draws with the interior fog triple.
     pub(crate) interior_fog: Vec<bool>,
-    /// The **deferred exterior-window worklist** this flood left behind — the client's
-    /// `[0xcbe324]` records (count `[0xcbe320]`), one clipped NDC [`Rect`] per doorway the flood
-    /// reached onto an `0x8` group. Two consumers, and that is the point of publishing it here:
-    /// the flood's own Pass 2 (which exterior groups of THIS building draw) and
-    /// [`ExteriorWindows`] (what of the open world draws), which the reference likewise feeds from
-    /// one list — `0x681070` `rep movsd`s the very same records into `0xc7cb7c`.
+    /// The deferred exterior-window worklist this flood left, the client's `[0xcbe324]` records:
+    /// one clipped NDC rect per doorway reached onto an `0x8` group. Pass 2 and [`ExteriorWindows`]
+    /// both read it, as the reference feeds both from one list (`0x681070` copies it).
     pub(crate) windows: Vec<Rect>,
-    /// How many stack steps every run of the walk took this frame — Pass 1 plus one Pass-2 replay
-    /// per window. Instrument only (the dump prints it): Pass 2 re-floods from every window-admitted
-    /// exterior group, so this is the number to watch if a dense root ever gets expensive, and the
-    /// number that would pin it against [`MAX_ITERS`] if a portal cycle ever ran away.
+    /// Stack steps across every run of the walk this frame, Pass 1 and each Pass-2 replay; the dump
+    /// prints it.
     pub(crate) iters: u32,
 }
 
-/// One step on the portal walk's stack: the group to enter, the group it was entered FROM (so the
-/// entry portal is never re-crossed), the working screen rect, the recursion depth, and whether the
-/// path that got here kept an unbroken interior chain from the seed.
+/// One step on the walk's stack: the group to enter, the group it was entered from (so the entry
+/// portal is never re-crossed), the screen rect, the depth, and whether the path kept an unbroken
+/// interior chain from the seed.
 type Step = (usize, usize, Rect, u32, bool);
 
-/// The portal walk `0x6b41c0`, and the per-FRAME state every run of it shares.
-///
-/// The inside leg runs this walk **twice** (`wow-5875-re` `models/scratch/wmo-insideleg-phase3.md`,
-/// §5 1v1 VERIFIED): once from the camera's own group (Pass 1, `0x6b3c05 call 0x6b41c0`) and again
-/// from every exterior group a deferred window admits (Pass 2, `0x6b3d39 call 0x6b41c0` — **the same
-/// recursion**, not a draw call). Holding the walk in one place is what makes the second run actually
-/// be the same walk: the visible set, the fog lane, the per-portal window stamp and the runaway
-/// backstop are all per-frame, not per-pass.
+/// The portal walk `0x6b41c0` and the per-frame state its runs share. The inside leg runs it from
+/// the camera's groups (Pass 1, `0x6b3c05`) and again from every exterior group a deferred window
+/// admits (Pass 2, `0x6b3d39`, the same recursion); the visible set, the fog lane, the window
+/// stamps and the backstop are per frame, not per pass.
 struct Flood<'a> {
     model: &'a WmoModel,
     eye_local: [f32; 3],
@@ -849,24 +667,21 @@ struct Flood<'a> {
     world_from_local: &'a Affine3A,
     visible: Vec<bool>,
     interior_fog: Vec<bool>,
-    /// The **deferred exterior-window worklist** Pass 1 leaves behind — the client's `[0xcbe324]`
-    /// records, reset to empty at `0x6b3b51` and filled by the recursion at `0x6b4541`.
+    /// The deferred exterior-window worklist Pass 1 leaves: the client's `[0xcbe324]` records,
+    /// reset at `0x6b3b51` and filled at `0x6b4541`.
     windows: Vec<Rect>,
-    /// The client's per-frame stamp on the PORTAL record (`0x6b4505`, `[esi+0x18]` vs `[0xca8014]`):
-    /// a portal contributes **at most one** window per frame, however many paths the flood reaches it
-    /// by. It guards the store alone — the recursion runs regardless — so this is a dedup, never a
-    /// skip. First push wins, which our stack walk resolves the same way the reference's does.
+    /// The client's per-frame stamp on the portal record (`0x6b4505`, `[esi+0x18]` vs
+    /// `[0xca8014]`): a portal adds at most one window per frame, however many paths reach it. It
+    /// guards the store only, never the recursion; the first push wins.
     portal_pushed: Vec<bool>,
-    /// Runaway backstop, counted across every run of the walk in this frame (see [`MAX_ITERS`]).
+    /// Runaway backstop, counted across every run of the walk this frame ([`MAX_ITERS`]).
     iters: u32,
 }
 
 impl Flood<'_> {
-    /// Drain `stack`, entering each step's group and crossing its portals.
-    ///
-    /// `record_windows` is the client's inside-leg flag `[0xcde5ac]` — set for Pass 1 only
-    /// (`0x6b3b47`, cleared `0x6b3c1a`), which is why Pass 1 is the ONLY run that records deferred
-    /// windows: the push itself is guarded on it (`0x6b4511`).
+    /// Drain `stack`, entering each step's group and crossing its portals. `record_windows` is the
+    /// client's inside-leg flag `[0xcde5ac]`, set for Pass 1 only (`0x6b3b47`, cleared `0x6b3c1a`),
+    /// and the push is guarded on it (`0x6b4511`).
     fn walk<T: FloodTrace>(&mut self, stack: &mut Vec<Step>, record_windows: bool, trace: &mut T) {
         let model = self.model;
         let nav = &model.group_nav;
@@ -877,25 +692,16 @@ impl Flood<'_> {
                 continue;
             }
             self.visible[g] = true;
-            // The interior-fog gate ([`GroupPvs::interior_fog`]): this group draws with the
-            // building's own MFOG triple iff the walk that reached it kept an unbroken interior
-            // chain from the seed AND the group is itself a true interior. ORed over paths — a
-            // group two walks reach takes the lane if EITHER kept the chain.
-            //
-            // The second term is the DRAWER ROUTER folded in (`0x6b3fe8` picks interior-vs-exterior
-            // on the same `flags & 0x48`): an exterior/exterior-lit group is drawn by `0x6b4f10`,
-            // which pushes no fog at all, so `[0xca7f00]` cannot reach its surfaces however the walk
-            // got there — and that is true of the SEED's own group too when the camera stands in a
-            // courtyard. Folding it here rather than ANDing it in each of the three consuming lanes
-            // keeps one definition of "which fog does this room wear".
+            // The interior fog, ORed over paths: an unbroken interior chain, and a true interior
+            // group, since the drawer router (`0x6b3fe8`, `flags & 0x48`) sends any other to
+            // `0x6b4f10`, which pushes no fog, the seed's own group included.
             self.interior_fog[g] |= chain && nav[g].flags & (EXTERIOR | EXTERIOR_LIT) == 0;
             if depth >= DEPTH_CAP {
                 continue;
             }
             let nav_g = &nav[g];
-            // The chain breaks BELOW an exterior/exterior-lit group, never at the seed: the seed
-            // forces the lane on for its own group (`0x6b3b4c`/`0x6b3df5`), and a `flags & 0x48`
-            // group is the anchor the walk's chain breaks at (`0x6b424f` → `0x6b42c6`).
+            // The chain breaks past an exterior or exterior-lit group, where the anchor clears
+            // (`0x6b424f` → `0x6b42c6`).
             let chain_on = chain && nav_g.flags & (EXTERIOR | EXTERIOR_LIT) == 0;
             let start = nav_g.ref_start as usize;
             let end = (start + nav_g.ref_count as usize).min(model.portal_refs.len());
@@ -908,11 +714,9 @@ impl Flood<'_> {
                 let Some(info) = model.portal_infos.get(r.portal as usize) else {
                     continue;
                 };
-                // Front-side test: the camera must be on the `side`-oriented half-space to enter.
-                // The threshold IS zero — skip iff `d' < 0` strictly, enter on exactly-0 (the
-                // client's `DAT_007ffd74 = 0.0`) — and it ALWAYS runs: the recorded on-plane "skip
-                // the side test" flag is dead code in the client (`wmo-portal-audit.md` Q1
-                // correction).
+                // Front-side test on the `side`-oriented half-space: skip only on `d < 0`, enter on
+                // exactly 0 (the client's `0x7ffd74`, 0.0); it always runs, as the on-plane skip
+                // flag is dead code (`0x6b43c9`).
                 let mut d = info.plane[0] * eye_local[0]
                     + info.plane[1] * eye_local[1]
                     + info.plane[2] * eye_local[2]
@@ -924,12 +728,11 @@ impl Flood<'_> {
                     trace.side_fail(g, r.portal, neighbour, d);
                     continue;
                 }
-                // The eye standing in this portal's plane (inside its polygon) gets the full-screen
-                // rect (the client's `0x6b46f0` special case). Without this, a camera crossing a
-                // doorway clips the room ahead to nothing for a frame.
+                // An eye in the portal gets the full screen (`0x6b46f0`), or a camera crossing a
+                // doorway would clip the room ahead to nothing for a frame.
                 let on_plane = eye_on_portal(&model.portal_vertices, info, eye_local);
-                // Project the portal polygon to a screen rect; intersect with the carried rect.
-                // Either collapsing to zero area kills this branch (the cathedral case).
+                // The portal's screen rect, intersected with the carried one; a collapse kills the
+                // branch.
                 let prect = if on_plane {
                     FULL_SCREEN
                 } else {
@@ -951,10 +754,8 @@ impl Flood<'_> {
                     continue;
                 };
                 trace.entered(g, r.portal, neighbour, inter, on_plane);
-                // Reaching a portal onto an exterior group records a deferred window — the client's
-                // push at `0x6b44f8`(test `0x8`)/`0x6b4539`(count)/`0x6b4541`(rect).
-                // [`opens_a_window`] is the predicate, shared with nothing else because there IS
-                // nothing else: this is the one place the worklist is built.
+                // A portal onto an exterior group records a deferred window (`0x6b44f8` tests
+                // `0x8`, `0x6b4539` counts, `0x6b4541` stores the rect).
                 if record_windows && opens_a_window(nav, neighbour) {
                     if let Some(stamp) = self.portal_pushed.get_mut(r.portal as usize) {
                         if !*stamp {
@@ -969,8 +770,7 @@ impl Flood<'_> {
     }
 }
 
-/// [`compute_pvs`] with a [`FloodTrace`] tap on every decision — the same flood the frame runs;
-/// the probe dump and the audit harness pass a recorder, the per-frame path passes `()`.
+/// The portal flood with a [`FloodTrace`] tap on every decision, the flood the frame runs.
 fn compute_pvs_traced<T: FloodTrace>(
     model: &WmoModel,
     eye_local: [f32; 3],
@@ -992,27 +792,16 @@ fn compute_pvs_traced<T: FloodTrace>(
         iters: 0,
     };
 
-    // Seed: the down-ray's set — the camera's current group AND, when the nearest crossing was a
-    // portal, the group on its other side. Each is an independent flood ROOT with the full screen
-    // (the client appends both to the visible-group set `0xc7cd88` and the inside leg loops `visit()`
-    // over the whole set — `wow-5875-re` `wmo-portal-audit.md` Q2; seeding only the containing group
-    // under-floods at exactly the near-portal moment the second root exists to cover). Over no surface
-    // (open air) or an exterior one ⇒ the outside leg, seeding each EXTERIOR group full-screen (Bevy
-    // then frustum-culls the genuinely off-screen ones by their Aabb).
+    // Seed: the down-ray's set, each an independent full-screen root (the client appends both to
+    // the containing-group set `0xc7cd88` and visits each, `0x6b3bd4`–`0x6b3c10`). Over no surface
+    // or an exterior one, the outside leg seeds every EXTERIOR group full-screen.
     let mut stack: Vec<Step> = Vec::new();
     let seeds = down_ray_seeds(model, eye_local, terrain_z);
     trace.seed(seeds);
-    // **The inside-leg flag** — the client's `[0xcde5ac]`, set only for Pass 1 of `0x6b3b20`
-    // (`0x6b3b47`, cleared `0x6b3c1a`), which is why Pass 1 is the ONLY pass that records deferred
-    // windows: the push itself is guarded on it (`0x6b4511`). And `0x6b3b20` runs at all only when
-    // the camera has a CONTAINING map object — `[0xc7b748]`, whose writer rejects an `0x8` group
-    // outright (round-6 Q-H(c), the same rule the interior claim below takes).
-    //
-    // So the eye standing on a building's own porch or outer terrace is the driver's OUTSIDE leg
-    // (`0x6811ca`): no worklist, no Pass 2, the building drawn like any other placement. Without
-    // this guard our flood would seed inside that exterior group anyway, push windows from its
-    // portal steps, and then let Pass 2 cull the rest of the shell from a vantage where the
-    // reference frustum-tests every group normally.
+    // The inside-leg flag `[0xcde5ac]`: Pass 1 of `0x6b3b20` alone records windows, and
+    // `0x6b3b20` runs only with a containing map object, `[0xc7b748]`, whose writer rejects an
+    // `0x8` group (`0x6be451`). An eye over a building's own `0x8` porch is the driver's outside
+    // leg (`0x6811ca`): no worklist, no Pass 2.
     let inside_leg = seeds
         .in_group
         .and_then(|gi| nav.get(gi))
@@ -1025,8 +814,8 @@ fn compute_pvs_traced<T: FloodTrace>(
             }
         }
         None => {
-            // The outside leg — no containing map object, so nothing takes the interior fog lane
-            // (the client's selector bails on `[0xc7b748] == 0` ahead of all of this, round 5 Q-G).
+            // The outside leg: no containing map object, so no interior fog (the selector
+            // `0x69de20` bails on `[0xc7b748] == 0`).
             for (gi, g) in nav.iter().enumerate() {
                 if g.flags & EXTERIOR != 0 {
                     stack.push((gi, usize::MAX, FULL_SCREEN, 0, false));
@@ -1034,52 +823,28 @@ fn compute_pvs_traced<T: FloodTrace>(
             }
         }
     }
-    // **Pass 1 — the interior flood** (`0x6b3bd4..0x6b3c10`), the only run that records windows.
+    // Pass 1, the interior flood (`0x6b3bd4..0x6b3c10`), the only run that records windows.
     flood.walk(&mut stack, inside_leg, trace);
 
-    // **Pass 2 — the deferred exterior-window replay** (`0x6b3c73..0x6b3d6f`), carved at the bytes in
-    // `wow-5875-re` `models/scratch/wmo-insideleg-phase3.md` (§5 1v1, VERIFIED). Gated on the worklist
-    // being non-empty (`0x6b3c87 jbe 0x6b3d6f` — a sealed room draws no exterior shell at all), and
-    // then, **per window**, every group is admitted on `0x8 ∧ visible against a frustum clipped to
-    // THAT window` (`0x6b3d13` / `0x6b3d22`) — never against the full view.
-    //
-    // **And an admitted group is FLOODED FROM, not merely marked** (`0x6b3d39 call 0x6b41c0` — the
-    // portal recursion, the identical entry point Pass 1 uses; the callback draw `0x6b4160` is Pass
-    // 3's and only Pass 3's). Decision 1826 shipped this as a marking pass, which is why a city
-    // whose outdoor areas are stitched together by portals — Darnassus is one WMO with 104 groups,
-    // 50 of them exterior — lost every shell the doorway's own rect did not directly touch. The
-    // window admits the *first* group; the walk carries that window's rect onward through the
-    // graph, narrowing at each portal exactly as Pass 1 does.
-    //
-    // We used to mark EVERY `0x8` group visible the moment any window existed, against the full
-    // frustum, with a comment calling it "a benign over-draw". It is not benign: it is the
-    // building's own far side drawing through its own walls, and decision 0784 had already flagged
-    // this exact line — *"the exemption is per placement, not per group … if a case turns up where
-    // it is not, this is the line to revisit"*. The case is the carve itself.
-    //
-    // The sub-frustum is [`crate::exterior_cull::window_frustum`] — the same construction the open
-    // world is gated by, and **deliberately not** its narrowness reject. That reject is the
-    // entry gate of the scene walk `0x682fa0`, not part of the volume builder `0x682930` (which
-    // contains no compare at all); 1826 applied it here too and blanked the containing building's
-    // whole shell for every window in the `[0.001, 0.02)` NDC band — above the recursion's own
-    // collapse guard, below the scene walk's. So a doorway too narrow to admit a hillside can
-    // still admit a wall, which is the reference's own asymmetry.
+    // Pass 2, the deferred-window replay (`0x6b3c73..0x6b3d6f`): skipped with an empty worklist
+    // (`0x6b3c87`), so a sealed room draws no exterior shell. Per window, each `0x8` group inside a
+    // frustum clipped to that window (`0x6b3d13`/`0x6b3d22`) is flooded from, not merely marked
+    // (`0x6b3d39 call 0x6b41c0`), the walk carrying the window's rect on. The sub-frustum is
+    // `crate::exterior_cull::window_frustum` without its narrowness reject, which gates the scene
+    // walk `0x682fa0` and not the volume builder `0x682930`: a doorway too narrow to admit a
+    // hillside still admits a wall.
     if flood.windows.len() > WORKLIST_CAP {
         trace.worklist_over_cap(flood.windows.len());
     }
-    // The worklist is fixed once Pass 1 ends (`[0xcde5ac]` is clear from here on), so replaying it
-    // by value keeps the borrow honest without copying anything that can still change.
+    // The worklist is fixed once Pass 1 ends, so it is replayed by value.
     let worklist = std::mem::take(&mut flood.windows);
     for (wi, rect) in worklist.iter().enumerate() {
         let frustum = crate::exterior_cull::window_frustum(*rect, clip_from_world);
-        // Every MOGI group is a candidate against every window — the reference's inner loop carries
-        // no "already drawn" short-circuit, and one that skipped a visible group would also skip the
-        // walk THROUGH it, which is the half of Pass 2 that reaches the rest of the city.
+        // Every group is a candidate against every window: the reference has no already-drawn
+        // skip, and skipping a visible group would also skip the walk through it.
         let mut roots: Vec<Step> = Vec::new();
         for (gi, g) in nav.iter().enumerate() {
-            // `¬0x10000 ∧ 0x8` — the client's `0x6b3d0b`/`0x6b3d13`, in that order. A callback-pass
-            // group is Pass 3's alone (below); admitting it here too would be the double-submit the
-            // reference's two predicates exist to prevent.
+            // `¬0x10000 ∧ 0x8` (`0x6b3d0b`, `0x6b3d13`): a callback-pass group is Pass 3's alone.
             if g.flags & (EXTERIOR | CALLBACK_PASS) != EXTERIOR {
                 continue;
             }
@@ -1093,31 +858,12 @@ fn compute_pvs_traced<T: FloodTrace>(
     }
     flood.windows = worklist;
 
-    // **Pass 3 — the callback pass** (`0x6b3d6f..0x6b3dbc`). Two things make it unlike Pass 2, and
-    // both matter: it tests the group against the **full camera frustum** (no window narrowing —
-    // there is no `0x682930` call on this path), and it is the `jbe` **fall-through**, so it runs
-    // even when the worklist is empty. A `0x10000` group therefore draws from a SEALED interior
-    // room, where nothing else of the building's outside does. Its draw is `0x6b4160` → `0x685d70`,
-    // the same per-group draw callback the flood itself uses, minus the portal recursion.
-    //
-    // **Both legs, unlike the two passes above.** Those live in `0x6b3b20`, which runs only when the
-    // camera has a containing map object; but the camera-OUTSIDE seed `0x6b3dd0` walks the same MOGI
-    // array with the same fork — `flags & 0x10000 -> 0x6b4160`, `flags & 0x8` frustum-pass -> the
-    // portal flood — so a callback group is drawn from outdoors by the identical callback. Gating
-    // this on the inside leg would have left 20 of the 24 undrawable from anywhere, including
-    // `stormwind.wmo#086`, a 322×236×258 yd piece of the city (wow-re ledger row `0x6b3dd0`).
-    //
-    // What this restores: the 24 groups no pass of ours reached from inside — 14 in `stormwind.wmo`
-    // (the canals and the tall district shell), 6 across the two Dire Maul roots, and Razorfen
-    // Downs'/Kraul's four 450–520 yd enclosing shells. Those last four also carry `0x8`, so before
-    // this they were window-tested by Pass 2 and vanished whenever no doorway showed them; the
-    // reference draws them regardless.
-    // **All four dispatch arms across both legs frustum-test the MOGI AABB first** — inside Pass 3 at
-    // `0x6b3d9d`, the outside `0x10000` arm at `0x6b3f2d`, and the two `0x8` arms — with byte-identical
-    // setup (`lea ecx,[eax+4]` = the record's six AABB floats, `call 0x682f60`, `test eax,eax; jne`,
-    // culled = nonzero), differing only in stack slots. `0x6b4160` itself is `__thiscall(root,
-    // groupIndex)`, `ret 4`: no rect, depth, owner or per-group stamp that could make the legs
-    // diverge.
+    // Pass 3, the callback pass (`0x6b3d6f..0x6b3dbc`): each `0x10000` group against the full
+    // camera frustum (no `0x682930` here), and the `jbe` fall-through, so it runs with an empty
+    // worklist too and a callback group draws even from a sealed room (`0x6b4160` → `0x685d70`,
+    // the flood's per-group callback without the recursion). Both legs run it: the camera-outside
+    // seed `0x6b3dd0` forks on the same bit. Every arm frustum-tests the MOGI AABB first
+    // (`0x6b3d9d`, `0x6b3f2d`, `call 0x682f60`).
     let base = Frustum::from_clip_from_world(clip_from_world);
     for (gi, g) in nav.iter().enumerate() {
         if flood.visible[gi] || g.flags & CALLBACK_PASS == 0 {
@@ -1136,21 +882,16 @@ fn compute_pvs_traced<T: FloodTrace>(
     }
 }
 
-/// A group's MOGI bounding box as a Bevy-space [`Aabb`] in the placement's LOCAL frame — the
-/// candidate bound Pass 2 hands the window frustum (the client's `0x682f60` takes the same per-group
-/// box out of the root's group-info array).
-///
-/// [`benilla_assets::coords::wow_to_bevy`] is a signed axis permutation, so an axis-aligned box maps
-/// to an axis-aligned box exactly: transforming the two corners and taking the componentwise
-/// min/max is the whole conversion, with no hull to rebuild.
+/// A group's MOGI bounding box as a Bevy-space [`Aabb`] in the placement's local frame, the bound
+/// the frustum tests take (the client's `0x682f60` takes the same box). `wow_to_bevy` is a signed
+/// axis permutation, so the two corners' min and max are the whole conversion.
 fn group_aabb(nav: &WmoGroupNav) -> Aabb {
     let a = wow_to_bevy(nav.bbox_min);
     let b = wow_to_bevy(nav.bbox_max);
     Aabb::from_min_max(a.min(b), a.max(b))
 }
 
-/// The portal's polygon vertices (WoW model space), or `None` if the span is out of range or
-/// degenerate (< 3 vertices).
+/// The portal's polygon (WoW model space), or `None` if the span is out of range or under 3.
 fn portal_poly<'a>(
     portal_vertices: &'a [[f32; 3]],
     info: &WmoPortalInfo,
@@ -1160,10 +901,8 @@ fn portal_poly<'a>(
     (verts.len() >= 3).then_some(verts)
 }
 
-/// Does the eye lie **in** this portal — within [`ON_PLANE_EPS`] of its plane (inclusive, the client's
-/// `|d| <= 0.01`) and inside its polygon (dominant-axis 2-D projection, the client's `0x7c23e0`)? The
-/// flood then gives the portal the full-screen rect — the client's `0x6b46f0` special case. The side
-/// test still applies (Q1 correction: the skip flag is dead).
+/// Does the eye lie in this portal: within [`ON_PLANE_EPS`] of its plane, inclusive, and inside its
+/// polygon (dominant-axis projection, `0x7c23e0`)? The flood then gives it the full screen.
 fn eye_on_portal(portal_vertices: &[[f32; 3]], info: &WmoPortalInfo, eye: [f32; 3]) -> bool {
     let [nx, ny, nz, d] = info.plane;
     if (nx * eye[0] + ny * eye[1] + nz * eye[2] + d).abs() > ON_PLANE_EPS {
@@ -1172,7 +911,7 @@ fn eye_on_portal(portal_vertices: &[[f32; 3]], info: &WmoPortalInfo, eye: [f32;
     let Some(verts) = portal_poly(portal_vertices, info) else {
         return false;
     };
-    // Project out the plane's dominant axis; the eye is on the plane, so its projection is itself.
+    // The eye is on the plane, so projecting out the dominant axis keeps it in place.
     let (u, v) = dominant_axes(info.plane);
     point_in_poly_2d(verts.iter().map(|p| (p[u], p[v])), (eye[u], eye[v]))
 }
@@ -1194,15 +933,11 @@ fn point_in_poly_2d(pts: impl Iterator<Item = (f32, f32)> + Clone, p: (f32, f32)
     inside
 }
 
-/// Project a portal polygon to its NDC bounding rectangle — the client's `0x6b46f0`: transform to
-/// clip space, Sutherland–Hodgman clip against the four **side** planes of the view pyramid (there is
-/// NO near-plane clip), then min/max the per-vertex NDC with the faithful `w` handling: `|w| < 0.001`
-/// substitutes `w = +1e-5` (positive regardless of the vertex's sign); a vertex still carrying
-/// `w <= -0.001` divides by its real negative `w`, so its **mirrored** NDC enters the rect. That is
-/// what keeps a doorway the eye is straddling wide open (the boundary points at the eye clamp to
-/// `+1e-5` and blow the rect out) instead of collapsing it for a frame. The rect is returned raw
-/// (un-clamped) — the caller's intersect with the carried rect bounds it. `None` iff the polygon is
-/// fully clipped (degenerate / off-screen) — the client's `rc.flags |= 0x1` skip.
+/// A portal polygon's NDC bounding rect, the client's `0x6b46f0`: to clip space, clipped against
+/// the four side planes only (no near plane), then the per-vertex NDC min and max, where
+/// `|w| < 0.001` becomes `+1e-5` and a vertex with `w <= -0.001` divides by its own negative `w`,
+/// its mirrored NDC entering the rect. So a doorway the eye straddles blows open instead of
+/// collapsing. Unclamped; `None` when fully clipped (the client's `rc.flags |= 0x1` skip).
 fn portal_screen_rect(
     model: &WmoModel,
     info: &WmoPortalInfo,
@@ -1210,7 +945,7 @@ fn portal_screen_rect(
     world_from_local: &Affine3A,
 ) -> Option<Rect> {
     let verts = portal_poly(&model.portal_vertices, info)?;
-    // WoW model vertex → world → clip (the same path the rendered geometry takes).
+    // WoW model vertex → world → clip, the path the rendered geometry takes.
     let clip: Vec<Vec4> = verts
         .iter()
         .map(|v| {
@@ -1237,11 +972,10 @@ fn portal_screen_rect(
     Some([min_x, min_y, max_x, max_y])
 }
 
-/// Sutherland–Hodgman clip of a clip-space polygon against the four **side** planes of the view
-/// pyramid (`x ≥ −w`, `x ≤ w`, `y ≥ −w`, `y ≤ w`, each linear in clip space — the client's guard
-/// pyramid `0xc7d0dc` fed to `poly_clip 0x6b4a80`). Deliberately no near plane: a polygon spanning
-/// the eye survives as boundary points at/near `w = 0`, which the caller's `w`-clamp handles — the
-/// faithful behaviour. `None` if fewer than 3 vertices remain (fully clipped).
+/// Sutherland–Hodgman clip of a clip-space polygon against the four side planes (`x ≥ −w`, `x ≤ w`,
+/// `y ≥ −w`, `y ≤ w`; the client's guard pyramid `0xc7d0dc` fed to `0x6b4a80`). No near plane: a
+/// polygon spanning the eye survives as points near `w = 0` for the caller's `w`-clamp. `None`
+/// under 3 vertices.
 fn clip_side_planes(poly: &[Vec4]) -> Option<Vec<Vec4>> {
     const PLANES: [fn(&Vec4) -> f32; 4] =
         [|v| v.w + v.x, |v| v.w - v.x, |v| v.w + v.y, |v| v.w - v.y];
@@ -1269,7 +1003,7 @@ fn clip_side_planes(poly: &[Vec4]) -> Option<Vec<Vec4>> {
     Some(cur)
 }
 
-/// Intersect two NDC rects; `None` if they don't overlap with non-zero area.
+/// Intersect two NDC rects; `None` unless the overlap spans [`RECT_EPS`] on both axes.
 fn intersect_rect(a: Rect, b: Rect) -> Option<Rect> {
     let rect = [
         a[0].max(b[0]),
@@ -1289,10 +1023,7 @@ mod tests {
 
     use benilla_assets::WmoPortalRef;
 
-    /// A prop is drawn while ANY room that names it is visible — the reference's per-visible-group
-    /// MODR walk. Blackrock's lava falls hang through up to 19 groups; keying them to one owner hid
-    /// the fall from every camera angle whose flood reached a different referrer. Geometry (a
-    /// single-group key) is unaffected, and an index past the visible set fails OPEN.
+    /// Any visible referrer draws a prop; an index past the visible set fails open.
     #[test]
     fn a_prop_is_drawn_while_any_of_its_rooms_is_visible() {
         let inst = WmoPortalInstance {
@@ -1322,10 +1053,7 @@ mod tests {
         assert!(key(&[9]).drawn_by(&inst), "index past the set fails open");
     }
 
-    /// The interior-fog key ORs like `drawn_by` — a prop several rooms name wears the fog of any
-    /// of them — but a lookup miss reads FALSE where `drawn_by`'s reads true. The asymmetry is
-    /// deliberate: a missing PVS bit must not blank a building, and a missing fog bit must not
-    /// paint a room's MFOG onto something the flood never placed.
+    /// The interior-fog key ORs like `drawn_by`, but a lookup miss reads false.
     #[test]
     fn the_interior_fog_key_ors_over_rooms_and_fails_closed() {
         let inst = WmoPortalInstance {
@@ -1364,13 +1092,9 @@ mod tests {
         );
     }
 
-    /// **Only `0x8` opens a window onto the open world** (`0x6b44f8`), and the flag values here are
-    /// Stormwind's own, read off a live cull trace at the director's `.go xyz -8798.70 478.64 95.79`
-    /// (decision 1148). The city is 306 groups of which **exactly one** — `g46`, `0x08809` — carries
-    /// `0x8`; the streets and rooms are `0x40`-without-`0x8` (decision 0475). Testing the weather
-    /// global's `0x148` instead turned all eleven rooms the flood reached from that spot into
-    /// doorways onto Elwynn, one of them 74% of the screen wide. If this test ever goes green on
-    /// `0x148` again, the whole exterior cull is off in every city.
+    /// Only `0x8` opens a window (`0x6b44f8`). The flags are Stormwind's own, from a live cull
+    /// trace: of its 306 groups only `g46` (`0x08809`) carries `0x8`; its streets and rooms are
+    /// `0x40` without `0x8`.
     #[test]
     fn only_an_exterior_group_opens_a_window_onto_the_open_world() {
         let g = |flags: u32| WmoGroupNav {
@@ -1383,7 +1107,7 @@ mod tests {
             fog_indices: [0; 4],
             group_liquid: 0xf,
         };
-        // Stormwind's real group flags: the rooms/streets the flood reached from the reported spot…
+        // Stormwind rooms and streets…
         let nav = [g(0x0b841), g(0x0a841), g(0x0ba41), g(0x08809), g(0x02a05)];
         for to in [0, 1, 2] {
             assert!(
@@ -1393,13 +1117,12 @@ mod tests {
             );
         }
         assert!(!opens_a_window(&nav, 4), "0x02a05 carries neither bit");
-        // …and g46, the city's single exterior shell, which is the only real window.
+        // …and g46, the city's one exterior shell.
         assert!(
             opens_a_window(&nav, 3),
             "0x08809 carries 0x8 — this one IS the open world"
         );
-        // A destination past the nav (a corrupt MOPR ref) fails CLOSED: an unknown group is not
-        // evidence of a doorway, and failing open here is the bug this test exists to catch.
+        // A destination past the nav (a corrupt MOPR ref) fails closed: no doorway.
         assert!(
             !opens_a_window(&nav, 99),
             "an out-of-range group is no window"
@@ -1408,7 +1131,7 @@ mod tests {
 
     #[test]
     fn eye_on_portal_only_within_the_band_and_polygon() {
-        // A vertical doorway portal in the x=0 plane, spanning y ∈ [-2,2], z ∈ [0,4].
+        // A vertical doorway in the x=0 plane, spanning y ∈ [-2,2], z ∈ [0,4].
         let verts = vec![
             [0.0, -2.0, 0.0],
             [0.0, 2.0, 0.0],
@@ -1420,12 +1143,11 @@ mod tests {
             count: 4,
             plane: [1.0, 0.0, 0.0, 0.0],
         };
-        // In the plane, inside the polygon ⇒ the doorway is wide open.
         assert!(eye_on_portal(&verts, &info, [0.0, 0.0, 2.0]));
         assert!(eye_on_portal(&verts, &info, [0.005, 1.5, 3.5]));
-        // In the plane but outside the polygon (above the door) ⇒ not standing in it.
+        // In the plane but above the door.
         assert!(!eye_on_portal(&verts, &info, [0.0, 0.0, 5.0]));
-        // Inside the polygon's span but off the plane ⇒ the normal side/rect path applies.
+        // Within the door's span but off the plane.
         assert!(!eye_on_portal(&verts, &info, [0.5, 0.0, 2.0]));
     }
 
@@ -1440,12 +1162,11 @@ mod tests {
 
     #[test]
     fn intersect_rect_collapses_to_none() {
-        // Overlapping rects intersect to the overlap.
         assert_eq!(
             intersect_rect([-1.0, -1.0, 0.0, 0.0], [-0.5, -0.5, 1.0, 1.0]),
             Some([-0.5, -0.5, 0.0, 0.0])
         );
-        // Disjoint rects ⇒ the window collapses (the cathedral-cull termination).
+        // Disjoint rects: the window collapses.
         assert_eq!(
             intersect_rect([-1.0, -1.0, -0.5, -0.5], [0.5, 0.5, 1.0, 1.0]),
             None
@@ -1459,30 +1180,27 @@ mod tests {
 
     #[test]
     fn clip_side_planes_drops_behind_and_off_screen_keeps_straddling() {
-        // Fully behind the eye (w < 0, inside the mirror cone) ⇒ outside every side half-space ⇒
-        // fully clipped, like the client's rc.flags |= 0x1.
+        // Fully behind the eye (w < 0, inside the mirror cone): outside every side half-space.
         let behind = [
             Vec4::new(0.0, 0.0, 0.0, -1.0),
             Vec4::new(0.1, 0.0, 0.0, -1.0),
             Vec4::new(0.0, 0.1, 0.0, -1.0),
         ];
         assert!(clip_side_planes(&behind).is_none());
-        // Fully in front and on-screen ⇒ unchanged triangle.
         let front = [
             Vec4::new(0.0, 0.0, 0.0, 1.0),
             Vec4::new(0.5, 0.0, 0.0, 1.0),
             Vec4::new(0.0, 0.5, 0.0, 1.0),
         ];
         assert_eq!(clip_side_planes(&front).map(|p| p.len()), Some(3));
-        // Fully off-screen laterally (x > w for every vertex) ⇒ fully clipped.
+        // Off-screen laterally, x > w for every vertex.
         let off = [
             Vec4::new(2.0, 0.0, 0.0, 1.0),
             Vec4::new(3.0, 0.0, 0.0, 1.0),
             Vec4::new(2.0, 1.0, 0.0, 1.0),
         ];
         assert!(clip_side_planes(&off).is_none());
-        // Straddling the eye plane (one vertex behind): survives — the boundary points land at/near
-        // w = 0 for the w-clamp to handle. THIS is the case a near-plane clip would mishandle.
+        // Straddling the eye plane, one vertex behind: survives, with boundary points near w = 0.
         let straddle = [
             Vec4::new(0.0, -0.5, 0.0, 1.0),
             Vec4::new(0.0, 0.5, 0.0, 1.0),
@@ -1493,10 +1211,8 @@ mod tests {
 
     #[test]
     fn portal_rect_explodes_open_on_the_doorway_approach() {
-        // The camera 0.05 yd before the doorway plane (outside the 0.01 on-plane band), looking
-        // through it: the polygon fills far past the screen edges, and with no near-plane clip the
-        // rect must blow out to cover the whole screen — the client's protection for the approach
-        // frames (the crossing frame itself is the on-plane full-screen case).
+        // The camera 0.05 yd before the doorway plane, outside the 0.01 on-plane band, looking
+        // through it: with no near-plane clip the rect blows out to the whole screen.
         let model = portal_model();
         let info = &model.portal_infos[0];
         // WoW (−0.05, 0, 0) → Bevy (0, 0, 0.05); looking along WoW +x <=> Bevy −z.
@@ -1509,7 +1225,6 @@ mod tests {
         let rect = portal_screen_rect(&model, info, &clip, &Affine3A::IDENTITY)
             .expect("a doorway ahead must keep a rect");
         let inter = intersect_rect(FULL_SCREEN, rect).expect("must overlap the screen");
-        // The window is the whole screen while the eye is this deep in the doorway.
         assert!(inter[0] <= -0.99 && inter[1] <= -0.99 && inter[2] >= 0.99 && inter[3] >= 0.99);
     }
 
@@ -1517,8 +1232,7 @@ mod tests {
     fn portal_rect_is_none_when_fully_behind_the_camera() {
         let model = portal_model();
         let info = &model.portal_infos[0];
-        // Camera 5 yd past the doorway (WoW +x maps to Bevy −z), still looking further along −z:
-        // the doorway is squarely behind ⇒ fully clipped ⇒ no rect.
+        // Camera 5 yd past the doorway (WoW +x is Bevy −z), looking on along −z.
         let view = Mat4::look_at_rh(
             bevy::math::Vec3::new(0.0, 0.0, -5.0),
             bevy::math::Vec3::new(0.0, 0.0, -10.0),
@@ -1528,20 +1242,13 @@ mod tests {
         assert!(portal_screen_rect(&model, info, &clip, &Affine3A::IDENTITY).is_none());
     }
 
-    /// **Pass 2 is a per-window test, not a blanket** (decision 1826, `wow-5875-re`
-    /// `wmo-insideleg-phase3.md` `0x6b3d13`/`0x6b3d22`). One interior room with a narrow doorway onto
-    /// the outdoors, and two portal-disconnected exterior shells: one straight through the doorway,
-    /// one 30 yd off to the side. The reference draws each `0x8` group only where a *deferred
-    /// window* admits it, so the shell in the doorway draws and the one beside it does not.
-    ///
-    /// Before 1826 we set every `0x8` group visible the moment any window existed — so `g3`, a wall
-    /// no doorway shows, drew through the room's own walls. If this test ever goes green with `g3`
-    /// visible again, the building's far side is leaking again.
+    /// Pass 2 is a per-window test (`0x6b3d13`/`0x6b3d22`): of two portal-disconnected shells, the
+    /// one through the doorway draws and the one 30 yd aside does not.
     #[test]
     fn pass_two_admits_only_the_exterior_shells_a_doorway_shows() {
         let model = doorway_model();
         // Eye 3 yd back from the doorway, WoW (-3, 0, 1) = Bevy (0, 1, 3), looking along WoW +x
-        // (Bevy −z) — straight through the opening.
+        // (Bevy −z), straight through the opening.
         let eye_local = [-3.0, 0.0, 1.0];
         let view = Mat4::look_at_rh(
             bevy::math::Vec3::new(0.0, 1.0, 3.0),
@@ -1576,9 +1283,8 @@ mod tests {
              leaves it culled, which from a Darnassus shop is most of the city"
         );
 
-        // The control: widen the window to the whole screen (stand IN the doorway, which takes the
-        // on-plane full-screen branch) and the side shell comes back — proving the cull above is the
-        // window's doing and not the group's.
+        // The control: standing in the doorway takes the full-screen branch, and the side shell
+        // comes back, so the cull above is the window's.
         let in_door = compute_pvs_traced(
             &model,
             [0.0, 0.0, 1.0],
@@ -1593,25 +1299,19 @@ mod tests {
         );
     }
 
-    /// **Pass 3 draws a `0x10000` group from a SEALED room** — the `jbe` fall-through at
-    /// `0x6b3d6f`, against the full frustum, gated on nothing (decision 1826). This is the half
-    /// Pass 2 cannot express: with an empty worklist Pass 2 does not run at all, and every `0x8`
-    /// group is correctly dark, yet a callback-pass group still draws.
-    ///
-    /// The subjects in the real data are Razorfen Downs'/Kraul's 450–520 yd enclosing shells (which
-    /// carry `0x8` **and** `0x10000`, so Pass 2 alone would have culled them whenever no doorway
-    /// showed them) and Stormwind's canals.
+    /// Pass 3 draws a `0x10000` group from a sealed room (the `jbe` fall-through at `0x6b3d6f`):
+    /// with an empty worklist every `0x8` group is dark, yet the callback group draws, as
+    /// Razorfen's enclosing shells (`0x8` and `0x10000`) and Stormwind's canals do.
     #[test]
     fn pass_three_draws_a_callback_group_from_a_sealed_room() {
-        // The doorway model with its portal graph removed: the room is sealed, so the flood reaches
-        // nothing and leaves no windows. g1..g3 keep their `0x8`; g3 also gains `0x10000`.
+        // The doorway model, sealed: no portals, no windows. g1..g3 keep `0x8`; g3 gains `0x10000`.
         let mut model = doorway_model();
         model.portal_refs.clear();
         model.group_nav[0].ref_count = 0;
         model.group_nav[1].ref_count = 0;
         model.group_nav[3].flags |= CALLBACK_PASS;
-        // g3 sits 30 yd off-axis; aim the camera at it so the FULL frustum contains it while no
-        // window ever could — WoW (2..6, 30..34) → Bevy x ∈ [-34,-30], z ∈ [-6,-2].
+        // Aim at g3, 30 yd off-axis, so the full frustum holds it: WoW (2..6, 30..34) is Bevy
+        // x ∈ [-34,-30], z ∈ [-6,-2].
         let view = Mat4::look_at_rh(
             bevy::math::Vec3::new(0.0, 1.0, 3.0),
             bevy::math::Vec3::new(-32.0, 1.0, -4.0),
@@ -1641,8 +1341,7 @@ mod tests {
             "the 0x10000 group draws anyway: Pass 3 is the jbe fall-through, full frustum, ungated"
         );
 
-        // The control: Pass 3 is a frustum test, not an unconditional pass. Turn away from g3 and it
-        // goes dark — otherwise this test would pass just as well on a blanket.
+        // The control: Pass 3 is still a frustum test, so facing away darkens g3.
         let away = Mat4::perspective_rh(0.9, 16.0 / 9.0, 0.1, 1000.0)
             * Mat4::look_at_rh(
                 bevy::math::Vec3::new(0.0, 1.0, 3.0),
@@ -1662,10 +1361,8 @@ mod tests {
             "a callback group behind the camera is still frustum-culled"
         );
 
-        // …and the OUTSIDE leg draws it too — the camera-outside seed `0x6b3dd0` forks on the same
-        // `0x10000` before its `0x8` frustum-pass. Eye over open ground (no floor under it ⇒ no
-        // containing group), so the flood takes its outside branch and seeds only `0x8` groups;
-        // g3 has no portal refs and would be unreachable, yet the callback arm still draws it.
+        // The outside leg draws it too (`0x6b3dd0` forks on the same bit): an eye with no floor
+        // under it seeds only `0x8` groups, and g3, with no portal refs, is Pass 3's alone.
         let outside = compute_pvs_traced(
             &model,
             [-3.0, 0.0, 500.0],
@@ -1681,10 +1378,9 @@ mod tests {
         );
     }
 
-    /// One interior room (`g0`) whose single doorway (`p0`, WoW x=0, y ∈ [-0.5,0.5], z ∈ [0,2]) opens
-    /// onto an exterior group (`g1`), plus two portal-DISCONNECTED exterior shells: `g2` straight
-    /// ahead through the opening, `g3` 30 yd to the side. `g0` carries a floor at z=0 so the down-ray
-    /// seeds the flood there.
+    /// An interior room `g0` (floor at z=0, the seed) whose doorway `p0` (WoW x=0, y ∈ [-0.5,0.5],
+    /// z ∈ [0,2]) opens onto exterior `g1`, two portal-disconnected exterior shells, `g2` ahead
+    /// through the opening and `g3` 30 yd aside, and `g4`, reached only through `g2`.
     fn doorway_model() -> WmoModel {
         let nav = |flags: u32, min: [f32; 3], max: [f32; 3], ref_start: u16, ref_count: u16| {
             WmoGroupNav {
@@ -1710,7 +1406,7 @@ mod tests {
                 [0.0, 0.5, 0.0],
                 [0.0, 0.5, 2.0],
                 [0.0, -0.5, 2.0],
-                // p1, the back door of the disconnected shell g2 — g4's only way in.
+                // p1, the back door of g2 and g4's only way in.
                 [6.0, -0.5, 0.0],
                 [6.0, 0.5, 0.0],
                 [6.0, 0.5, 2.0],
@@ -1728,9 +1424,8 @@ mod tests {
                     plane: [1.0, 0.0, 0.0, -6.0],
                 },
             ],
-            // g0 -> g1 and back. `side = -1` puts the eye at x < 0 on the entering half-space.
-            // Then g2 -> g4 and back, through p1: g2 has no edge to the seed's side of the graph, so
-            // the ONLY route to g4 is Pass 2 admitting g2 and then walking on through it.
+            // g0 ↔ g1, `side = -1` putting the eye at x < 0 on the entering half-space; then
+            // g2 ↔ g4 through p1, reachable only by Pass 2 admitting g2 and walking on.
             portal_refs: vec![
                 WmoPortalRef {
                     portal: 0,
@@ -1765,8 +1460,7 @@ mod tests {
         }
     }
 
-    /// A bare model holding one vertical doorway portal in the WoW x=0 plane (y ∈ [-1,1], z ∈ [-1,1]),
-    /// i.e. straddling the world origin.
+    /// A bare model with one vertical doorway portal in the WoW x=0 plane, y and z in [-1,1].
     fn portal_model() -> WmoModel {
         WmoModel {
             wmo_id: 0,
diff --git a/crates/benilla-world/src/wmo_portal/probe.rs b/crates/benilla-world/src/wmo_portal/probe.rs
index 7643001d..1d1d36d7 100644
--- a/crates/benilla-world/src/wmo_portal/probe.rs
+++ b/crates/benilla-world/src/wmo_portal/probe.rs
@@ -1,8 +1,6 @@
-//! The portal-cull probe + trace instrument (decision 0022 — instruments as first-class): the live
-//! seed/visibility readout the debug panel shows, and the on-demand full-trace dump that turns a
-//! director-found "it vanishes here" into an exact fixture (eye coordinates, seed evidence, and every
-//! portal hop's verdict). The flood itself lives in the parent module; [`TraceLog`] records through
-//! the [`FloodTrace`](super::FloodTrace) tap, so there is no second flood to drift.
+//! The portal-cull probe: an on-demand trace dump that turns a spot where something vanishes into
+//! a fixture (the eye, the seed's evidence, every portal hop's verdict). [`TraceLog`] records
+//! through the [`FloodTrace`](super::FloodTrace) tap, so there is no second flood.
 
 use bevy::prelude::*;
 
@@ -11,25 +9,22 @@ use super::{
     MAX_FLOOR_DROP,
 };
 
-/// The portal-cull probe (decision 0022 — instruments as first-class): an on-demand full trace dump —
-/// the "found a spot where it vanishes" loop: click dump at the broken spot, and the exact seed evidence
-/// + per-portal verdicts land in a file the audit harness can replay as a fixture.
+/// The portal-cull probe: dumped at a broken spot, the seed's evidence and every portal verdict
+/// land in a file the audit harness can replay as a fixture.
 #[derive(Resource, Default)]
 pub struct WmoCullProbe {
-    /// Set by the panel's dump button; the next compute writes the trace file and clears it.
-    pub dump_requested: bool,
-    /// **The eye the PVS, the interior claim and the exterior windows were computed from** —
-    /// the visibility authority's own pose, recorded so an instrument can compare it against the
-    /// pose the frame actually draws from. Ordinary movement makes the two identical to within a
-    /// centimetre; a snap is where they can disagree by the whole teleport.
+    /// Set by the panel's dump button: the file the next compute writes the trace to, then
+    /// clears. Always a path handed in, never one this crate builds: a cwd-relative one is the
+    /// read-only install folder when the binary runs from there. The panel resolves it under
+    /// `benilla-config/Diagnostics/`; `WOW_CULLDUMP=<path>` is the headless spelling.
+    pub dump_to: Option<std::path::PathBuf>,
+    /// The eye the PVS, the interior claim and the exterior windows were computed from, for
+    /// comparison with the pose the frame draws from; a snap is where the two differ.
     pub eye: Vec3,
 }
 
-/// Where the dump button writes its trace — under `target/` so it never lands in the repo.
-pub(super) const PROBE_DUMP_PATH: &str = "target/wmo-cull-trace.txt";
-
-/// The probe dump's recorder: the seed's evidence (floor faces + portal crossings under the eye's
-/// column) plus every hop verdict, as text.
+/// The dump's recorder: the seed's evidence (floor faces and portal crossings under the eye's
+/// column) and every hop verdict, as text.
 pub(crate) struct TraceLog {
     pub(crate) text: String,
 }
@@ -40,8 +35,8 @@ impl TraceLog {
             "wmo {}: eye local ({:.2}, {:.2}, {:.2})\n",
             model.wmo_id, eye[0], eye[1], eye[2]
         );
-        // The terrain leg the WMO hit races: a surface above the eye was never crossed by the down
-        // segment; one below it beats any WMO face deeper still, and the eye is over open ground.
+        // The terrain leg the WMO hit races: a surface above the eye is off the down segment; one
+        // below it beats any deeper WMO face, and the eye is over open ground.
         text.push_str(&match terrain_z {
             None => "  terrain under: none (off-tile, mid-decode, or an MCNK hole)\n".to_string(),
             Some(z) if z > eye[2] => format!("  terrain under: none (surface z={z:.2} is ABOVE the eye — not on the down segment)\n"),
@@ -58,8 +53,8 @@ impl TraceLog {
                 g.ref_count
             ));
         }
-        // The seed's evidence: the top collision face per group under the eye's column, and every
-        // portal crossing (incl. near-parallel snap candidates) the down-ray's Leg B would consider.
+        // The seed's evidence: the top collision face per group under the eye, and every portal
+        // crossing the down-ray's Leg B would consider, near-parallel snap candidates included.
         for (gi, tris) in model.group_collision_tris.iter().enumerate() {
             let mut best = f32::NEG_INFINITY;
             for tri in tris {
@@ -82,7 +77,7 @@ impl TraceLog {
                 };
                 let [nx, ny, nz, d] = info.plane;
                 if nz.abs() < super::PORTAL_NEAR_PARALLEL {
-                    // A vertical doorway: only the 0.1-yd embedded-in-plane snap can cross it.
+                    // A vertical doorway: only the 0.1 yd in-plane snap can cross it.
                     let dist = nx * eye[0] + ny * eye[1] + nz * eye[2] + d;
                     if dist.abs() <= super::PORTAL_PLANE_SNAP {
                         text.push_str(&format!(
diff --git a/crates/benilla-world/src/wmo_portal/room_vis.rs b/crates/benilla-world/src/wmo_portal/room_vis.rs
index ec1d1b6a..edad4555 100644
--- a/crates/benilla-world/src/wmo_portal/room_vis.rs
+++ b/crates/benilla-world/src/wmo_portal/room_vis.rs
@@ -1,12 +1,8 @@
-//! **Is a claimed WMO room visible this frame?** — the one answer two elections share.
-//!
-//! The reference elects an object standing in a WMO group with its building (`0x6834e0`, inside
-//! the WMO-group render path): if the group isn't rendered this frame, the object is pass 2 —
-//! neither drawn nor ticked. Two of our systems ask exactly that question of a body's
-//! [`UnitWmoRoom`] claim: the anim-LOD gate (`creature_anim::lod`, decision 0739 — parks the
-//! pose) and the body draw election (`crate::exterior_cull`, decision 1475 — hides the root).
-//! One function answers both, so the two can never drift apart (the drift is how 0448's park and
-//! 0648's draw ended up disagreeing for a month — decision 1473).
+//! Is a claimed WMO room visible this frame? The reference elects an object standing in a WMO
+//! group with its building (`0x6834e0`, in the WMO-group render path): when the group is not
+//! rendered, the object is neither drawn nor ticked. The anim-LOD gate (`creature_anim::lod`) and
+//! the body draw election (`crate::exterior_cull`) both ask it of a body's [`UnitWmoRoom`], and one
+//! function answers both so they cannot disagree.
 
 use bevy::prelude::*;
 
@@ -14,9 +10,8 @@ use benilla_assets::{WmoGroupNav, WmoModel, WmoPortalRef};
 
 use super::{UnitWmoRoom, WmoPortalInstance, WmoRoom};
 
-/// The room leg's resolve chain: unit claim → placement instance → model → PVS bits. Fail-open
-/// at every seam (no claim, despawned placement, still-loading model) — a lookup miss must never
-/// hide or park a drawable body.
+/// Whether a body's claimed room is visible this frame. Every seam (no claim, a despawned
+/// placement, a loading model) fails open: a lookup miss must never hide or park a body.
 pub fn room_pvs_visible(
     room: Option<&UnitWmoRoom>,
     instances: &Query<&WmoPortalInstance>,
@@ -34,12 +29,9 @@ pub fn room_pvs_visible(
     room_visible(&inst.visible, &model.group_nav, &model.portal_refs, group)
 }
 
-/// Is the claimed group — or any group one portal hop from it — in the PVS? The one-hop union is
-/// the doorway-straddle guard: a body can extend past its feet's room only through a portal
-/// opening, so the neighbour set bounds everything of the unit that could be on screen. Indices
-/// out of range read visible (fail-open, [`super::WmoGroupVis::drawn_by`]'s convention); a group
-/// with no portal refs at all can only be seen with the camera inside it (the flood cannot reach
-/// it), which the direct bit already answered.
+/// Is the claimed group, or any group one portal hop from it, in the PVS? The hop is the
+/// doorway-straddle guard: a body extends past its room only through a portal opening. An index
+/// out of range reads visible, as in [`super::WmoGroupVis::drawn_by`].
 fn room_visible(visible: &[bool], nav: &[WmoGroupNav], refs: &[WmoPortalRef], group: u16) -> bool {
     let vis = |g: usize| visible.get(g).copied().unwrap_or(true);
     if vis(group as usize) {
@@ -59,8 +51,7 @@ fn room_visible(visible: &[bool], nav: &[WmoGroupNav], refs: &[WmoPortalRef], gr
 mod tests {
     use super::*;
 
-    /// A [`WmoGroupNav`] whose only meaningful fields are its portal-ref slice — these tests
-    /// never touch flags/bounds.
+    /// A [`WmoGroupNav`] whose only meaningful fields are its portal-ref slice.
     fn nav(ref_start: u16, ref_count: u16) -> WmoGroupNav {
         WmoGroupNav {
             flags: 0,
@@ -82,9 +73,7 @@ mod tests {
         }
     }
 
-    /// The room predicate's whole truth table: direct bit, the one-hop straddle guard, the
-    /// all-dark verdict, the sealed room, and both fail-open seams (group past every table, a
-    /// ref slice past the refs vec).
+    /// Direct bit, the straddle guard, all dark, the sealed room, and both fail-open seams.
     #[test]
     fn room_visible_covers_the_hop_guard_and_fails_open() {
         // Groups 0 ↔ 1 share one portal; group 2 is sealed (no refs).
diff --git a/crates/benilla-world/src/wmo_portal/seed.rs b/crates/benilla-world/src/wmo_portal/seed.rs
index 6373b658..afd190ad 100644
--- a/crates/benilla-world/src/wmo_portal/seed.rs
+++ b/crates/benilla-world/src/wmo_portal/seed.rs
@@ -1,45 +1,26 @@
-//! The current-group **down-ray** — which room is the camera in, and which flood roots follow.
+//! The current-group down-ray: which room the camera is in, and which flood roots follow.
 //!
-//! The faithful port of the client's per-frame probe (`FUN_006821f0` → `FUN_006be250` → `0x6a3f80`;
-//! `wow-5875-re` `system/models/scratch/wmo-current-group.md` + `wmo-portal-audit.md` Q2/Q3/Q4/Q5):
-//! a vertical ray from the eye down `1760` yd races two legs, nearest crossing wins —
+//! The 1.12 client's per-frame probe (`0x6821f0` → `0x6be250` → `0x6a3f80`) casts 1760 yd down
+//! from the eye, and the nearest crossing wins:
 //!
-//! - **Leg A — walking-collision faces** (the client's collision BSP, MOPY mask `0x84`): every
-//!   non-DETAIL face, **no orientation filter** — stair treads, risers, ledges, sloped trim all count.
-//!   A render-face `|n.z|` floor heuristic here is exactly what mis-seeded doorways (the straddle) and
-//!   slab edges: the real face set tracks the room boundary to sub-yard, the proxy lagged it (Q4/Q5).
-//! - **Leg B — portal crossings** (`0x6a3f80`): where the ray crosses a portal polygon, the group is
-//!   picked by the eye's **side of the portal plane** (`group_a iff (signed_dist ≥ 0) == (side > 0)`,
-//!   else the neighbour) — the vertically-stacked tie-break (a stairwell's floor-hole portal flips the
-//!   room the instant the eye crosses the plane). A near-parallel portal (a vertical doorway vs the
-//!   vertical ray, `|denom| < 1e-4`) counts as crossed only while the eye is within the `0.1`-yd snap
-//!   window of its plane (`0x7c22b0`'s parallel branch). A crossing within `~1e-4` of the nearest face
-//!   hit still wins (`0x80c4f4`) — a floor-hole portal coincident with the slab's faces flips the room.
+//! - Leg A, walking-collision faces (the collision BSP, MOPY mask `0x84`): every non-DETAIL face,
+//!   with no orientation filter.
+//! - Leg B, portal crossings (`0x6a3f80`): the eye's side of the portal plane picks the group
+//!   (`group_a iff (signed_dist ≥ 0) == (side > 0)`). A near-parallel portal (`|denom| < 1e-4`)
+//!   counts only within the 0.1 yd snap of its plane (`0x7c22b0`), and a crossing within about
+//!   1e-4 of the nearest face hit still wins (`0x80c4f4`).
+//! - The terrain race: the WMO hit is dropped only when terrain on the same segment is strictly
+//!   nearer (`0x6822a2`; `GetAreaID` `0x670250` arbitrates alike at `0x670345`). Terrain above the
+//!   eye is off the segment, so a tunnel under a hill stays inside.
 //!
-//! The verdict is a **set**, not a single group: the in-group plus (for a portal win) the across-group,
-//! both appended to the client's visible-group set `0xc7cd88` and each flooded as an independent root
-//! (Q2). An exterior winner or no crossing within the ray ⇒ outside (empty set, the outside leg).
+//! The verdict is the in-group plus, for a portal win, the across-group: the containing-group set
+//! `0xc7cd88`, each flooded as its own root (`0x6b3bd4`–`0x6b3c10`). An exterior winner or no
+//! crossing is outside.
 //!
-//! - **The terrain race** (`terrain_z`): the same down-segment is cast against the **terrain** — the
-//!   client runs both probes and drops the WMO hit when the ground is *strictly* nearer
-//!   (`FUN_006821f0` `0x6822a2 fld t_terrain; fcomp t_wmo; test ah,5; jp` — falls through to clear the
-//!   WMO flag only on `t_terrain < t_wmo`; `GetAreaID 0x670250` arbitrates identically at `0x670345`).
-//!   Equal keeps the WMO. Without this leg a camera standing on open ground **above a buried interior**
-//!   — a mine dug into a hillside — reads "inside a tunnel" and the flood culls the building out from
-//!   under it (decision 0258; it is what 0233 deferred). Terrain *above* the eye is not on the
-//!   down-segment at all, which is exactly what keeps a real tunnel reading INSIDE, and a column in an
-//!   MCNK hole has no terrain surface to hit, which is how a mine entrance stays walkable.
-//!
-//! - **Leg C — the camera-void fallback** (decision 0692; **ours**, not the client's): only when Legs
-//!   A and B both miss AND no terrain surface sits at or below the eye's column, the same race runs
-//!   once more over the **camera-only** faces (DETAIL set, NOCAMCOLLIDE clear — the faces that stop
-//!   the camera but never carried the walking BSP). The client returns "outside" here and blanks the
-//!   building — reproducible in 5875 at the Deadmines entrance, whose behind-the-portal pocket is
-//!   floored entirely with DETAIL faces: the camera is sealed in by its own collision yet the flood
-//!   loses it. An eye that camera-collision itself proves is between interior surfaces, under ground
-//!   level, names the room that owns the surface below it instead. The gates keep the divergence out
-//!   of every place the client's verdict is *right*: any terrain at/below the eye (doorsteps, streets,
-//!   open country) or any Leg A/B result leaves the faithful answer untouched.
+//! Deviation: when legs A and B both miss and no terrain lies at or below the eye, Leg C runs the
+//! same race over the camera-only faces (DETAIL without NOCAMCOLLIDE), because the 1.12 client
+//! blanks the whole building from a pocket floored only with DETAIL faces, as at the Deadmines
+//! entrance.
 
 use benilla_assets::column_grid::ColumnGrid;
 use benilla_assets::{WmoGroupNav, WmoModel, WmoPortalInfo, WmoPortalRef};
@@ -50,18 +31,16 @@ use super::{
     PORTAL_PLANE_SNAP,
 };
 
-/// The down-ray's verdict: the camera's current group, plus — when the nearest crossing below the eye
-/// was a portal — the group on that portal's other side. Both become flood roots (the client's
-/// visible-group set `0xc7cd88`, cardinality 0/1/2). `in_group == None` ⇒ outside (and `across` is
-/// `None` too — the client appends nothing when the instance is cleared).
+/// The down-ray's verdict: the camera's group and, when the nearest crossing was a portal, the
+/// group across it, both flood roots (the containing-group set `0xc7cd88`). Outside, both are
+/// `None`.
 #[derive(Clone, Copy, Default, PartialEq, Eq, Debug)]
 pub struct DownRaySeeds {
     pub in_group: Option<usize>,
     pub(crate) across: Option<usize>,
 }
 
-/// [`down_ray_pick`] from the asset's stored pieces. `terrain_z` is the terrain surface height in
-/// **this model's local space** under the eye's column (see [`down_ray_pick`]).
+/// [`down_ray_pick`] over the asset's stored pieces; `terrain_z` is in this model's local space.
 pub fn down_ray_seeds(model: &WmoModel, eye: [f32; 3], terrain_z: Option<f32>) -> DownRaySeeds {
     down_ray_pick(
         &model.group_collision_tris,
@@ -76,12 +55,9 @@ pub fn down_ray_seeds(model: &WmoModel, eye: [f32; 3], terrain_z: Option<f32>) -
     )
 }
 
-/// The eye's current group (see the module doc for the mechanism and its provenance).
-///
-/// `terrain_z` is the ADT terrain surface height under the eye's column, expressed in **WMO model
-/// space** (the down-ray's own frame), or `None` where there is no terrain surface to hit — off the
-/// streamed tiles, or a hole cut through the ground into this very interior. It is the client's second
-/// probe, and it wins the column whenever it is *strictly* nearer to the eye than the WMO's hit.
+/// The eye's current group, by the module doc's mechanism. `terrain_z` is the terrain height under
+/// the eye in WMO model space, or `None` where there is none to hit: off the streamed tiles, or a
+/// hole cut through the ground into this interior.
 pub(crate) fn down_ray_pick(
     tris: &[Vec<[[f32; 3]; 3]>],
     grids: &[Option<ColumnGrid>],
@@ -93,8 +69,7 @@ pub(crate) fn down_ray_pick(
     eye: [f32; 3],
     terrain_z: Option<f32>,
 ) -> DownRaySeeds {
-    // The group broad-phase the whole probe shares: the eye's column must fall within the group's XY
-    // bounds, and the group must reach at/below the eye.
+    // Broad phase: the column inside the group's XY bounds, its bottom at or below the eye.
     let in_column = |g: &WmoGroupNav| {
         eye[0] >= g.bbox_min[0]
             && eye[0] <= g.bbox_max[0]
@@ -103,15 +78,14 @@ pub(crate) fn down_ray_pick(
             && g.bbox_min[2] <= eye[2]
     };
 
-    // Leg A — walking-collision faces: the highest crossing of the column at or below the eye.
+    // Leg A, walking-collision faces: the highest crossing at or below the eye.
     let mut best_z = f32::NEG_INFINITY;
     let mut best: Option<usize> = None;
     for (gi, g) in nav.iter().enumerate() {
         if !in_column(g) {
             continue;
         }
-        // Narrowed by the group's column index where it has one — same faces, same order (see
-        // `down_ray_claim`).
+        // The column index, where the group has one, yields the same faces in the same order.
         let mut consider = |tri: &[[f32; 3]; 3]| {
             if let Some(z) = floor_z_at(tri, eye[0], eye[1]) {
                 if z <= eye[2] && z > best_z {
@@ -133,7 +107,7 @@ pub(crate) fn down_ray_pick(
         }
     }
 
-    // Leg B — portal crossings, racing the face hit with the tie-break (a coincident portal wins).
+    // Leg B, portal crossings, racing the face hit; a coincident portal wins the tie.
     let mut across: Option<usize> = None;
     for (gi, g) in nav.iter().enumerate() {
         if !in_column(g) {
@@ -147,8 +121,7 @@ pub(crate) fn down_ray_pick(
             };
             let [nx, ny, nz, d] = info.plane;
             let z = if nz.abs() < PORTAL_NEAR_PARALLEL {
-                // Near-parallel (a vertical doorway vs the vertical ray): crossed only while the eye
-                // is embedded in the plane — the 0.1-yd snap window — and then at the eye itself.
+                // A vertical doorway: crossed, at the eye, only within the 0.1 yd snap.
                 if (nx * eye[0] + ny * eye[1] + nz * eye[2] + d).abs() > PORTAL_PLANE_SNAP {
                     continue;
                 }
@@ -169,16 +142,15 @@ pub(crate) fn down_ray_pick(
             if !point_in_poly_dominant(verts, info.plane, [eye[0], eye[1], z]) {
                 continue;
             }
-            // The plane-side pick (client `0x6a4130..0x6a4159`): the eye's side of the portal plane,
-            // oriented by `side`, chooses between the walked group and the neighbour.
+            // The plane-side pick (`0x6a4130..0x6a4159`): the eye's side, oriented by `side`, picks
+            // the walked group or the neighbour.
             let d_signed = nx * eye[0] + ny * eye[1] + nz * eye[2] + d;
             let chosen = if (d_signed >= 0.0) == (r.side > 0) {
                 gi
             } else {
                 r.group as usize
             };
-            // A dead neighbour ref (`0xffff`) can't be a room — leave the crossing to the other
-            // side's ref (same portal, mirrored), or to the face leg.
+            // A dead neighbour ref (`0xffff`) is no room: leave the crossing to the mirrored ref.
             if nav.get(chosen).is_none() {
                 continue;
             }
@@ -189,15 +161,10 @@ pub(crate) fn down_ray_pick(
         }
     }
 
-    // Outside: nothing within the ray length, or the winning surface belongs to an exterior group
-    // (the client clears the instance for either — and then appends no seeds).
+    // Outside: nothing within the ray, or an exterior winner; the client appends no seeds.
     let Some(in_group) = best else {
-        // Leg C — the camera-void fallback (decision 0692; ours, the module doc has the case).
-        // Fires only when BOTH faithful legs found nothing AND no terrain surface sits at or below
-        // the eye: an under-ground eye with a camera-collidable DETAIL surface below it is between
-        // interior surfaces the camera itself cannot leave, and blanking the building there is the
-        // client artifact the director rejected. Same race, same broad phase, same exterior and
-        // ray-length rules as Leg A; a single root, no `across` (no portal was crossed).
+        // Leg C, the camera-void fallback (the module doc's deviation): only when both legs missed
+        // and no terrain lies at or below the eye. Leg A's rules; one root, no `across`.
         if terrain_z.is_some_and(|tz| tz <= eye[2]) {
             return DownRaySeeds::default();
         }
@@ -228,10 +195,8 @@ pub(crate) fn down_ray_pick(
     {
         return DownRaySeeds::default();
     }
-    // The terrain race. A terrain surface above the eye was never crossed by the downward segment, so
-    // it is not a hit at all (this is what keeps a tunnel under a hill reading INSIDE). A terrain hit
-    // that is **strictly** nearer than the WMO's — i.e. sits above it — means the eye is standing over
-    // open ground: outside. A tie keeps the WMO, matching the client's strict `<`.
+    // The terrain race: terrain above the eye is off the segment; terrain strictly nearer than the
+    // WMO hit is open ground, outside; a tie keeps the WMO (the client's strict `<`).
     if terrain_z.is_some_and(|tz| tz <= eye[2] && tz > best_z) {
         return DownRaySeeds::default();
     }
@@ -241,30 +206,20 @@ pub(crate) fn down_ray_pick(
     }
 }
 
-/// The ZONE-TEXT down-ray length: the client's `[0x8022cc] = 1000.0` (wow-re
-/// `zonetext-indoor-bit.md` (b)) — shorter than the render current-group probe's 1760.
+/// The zone-text ray length, the client's `[0x8022cc]` = 1000.0; the render probe's is 1760.
 const ZONE_RAY_LEN: f32 = 1000.0;
 
-/// The position-cast indoor predicate's ray — **faces only, no portal leg** (wow-re
-/// `zonetext-indoor-bit.md`, VERIFIED): the CGLight node's down-ray attach `0x6a8a20` casts the
-/// position straight down [`ZONE_RAY_LEN`] and races {terrain hit, WMO face hit} — WMO wins ties
-/// (`t_wmo <= t_terr`, `0x6a8b15`) — then classifies by the winning group's MOGP flags against
-/// `outdoor_mask`: a masked flag → outdoors, else indoors. The classify `0x6a87f0` has TWO sinks
-/// with DIFFERENT masks, so the caller picks its law:
+/// The position-cast indoor predicate, faces only: the CGLight node's down-ray attach `0x6a8a20`
+/// casts [`ZONE_RAY_LEN`] down, races terrain against WMO faces with the WMO winning ties
+/// (`0x6a8b15`), and classifies the winning group's flags against `outdoor_mask`. The classify
+/// `0x6a87f0` has two sinks:
 ///
-/// - **zone-text/area** (`[node+0x90]` bit 0): [`EXTERIOR`] alone — a `0x40`-only street group is
-///   "indoors" for area naming (the bit is set before the `0x40` test);
-/// - **unit lighting class** (`[node+0xc]` bit 2/4): `EXTERIOR | `[`super::EXTERIOR_LIT`] — the
-///   fork is `MOGI & 0x48` (`6a880d test al,0x8` / `6a8823 test al,0x40`, both → `or
-///   [node+0xc],0x4`), so Stormwind/Orgrimmar street units light as sunlit outdoors (0475).
+/// - zone-text (`[node+0x90]` bit 0): [`EXTERIOR`] alone, so a `0x40`-only street is indoors;
+/// - unit lighting (`[node+0xc]`): `EXTERIOR | EXTERIOR_LIT`, the fork on `MOGI & 0x48`
+///   (`0x6a880d`, `0x6a8823`).
 ///
-/// The portal-crossing leg of [`down_ray_pick`] belongs to the CAMERA's current-group system (the
-/// render seed), **not** this predicate — running it here was the abbey-yard bug: a doorway plane
-/// under the eye claimed the interior while the real client's face ray still saw terrain/exterior
-/// pavement.
-///
-/// Returns the interior group index, or `None` = outdoors (no face, terrain won, or an
-/// outdoor-class winner — [`down_ray_claim`] is the un-collapsed form that keeps the distinction).
+/// The portal leg belongs to the camera's render seed alone: a doorway plane under the eye must
+/// not claim the interior. `None` is outdoors; [`down_ray_claim`] keeps an outdoor-class winner.
 pub(crate) fn area_down_ray(
     tris: &[Vec<[[f32; 3]; 3]>],
     bounds: &[Option<([f32; 3], [f32; 3])>],
@@ -278,25 +233,20 @@ pub(crate) fn area_down_ray(
         .and_then(|c| (!c.outdoor).then_some(c.group))
 }
 
-/// A position-cast down-ray's un-collapsed claim on one placement: the winning face's group, its
-/// depth below the probe, and the caller's-mask outdoor classification. `None` when no face is
-/// within the ray or strictly-nearer terrain steals the column — this placement sees the position
-/// standing over open ground.
+/// A position-cast ray's claim on one placement before the outdoor collapse: the winning face's
+/// group, its depth, and its outdoor class under the caller's mask.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) struct DownRayClaim {
     pub(crate) group: usize,
-    /// Depth of the winning face below the probe (yd). Placements are rigid (rotation +
-    /// translation), so depths are comparable ACROSS placements — the entity light chain
-    /// arbitrates its multi-placement winner by it (the client's one global nearest-hit).
+    /// Depth (yd) of the winning face along the cast. Placements are rigid, so depths compare
+    /// across placements: the light chain's one global nearest hit.
     pub(crate) depth: f32,
-    /// The winning group carries a flag in the caller's `outdoor_mask` (an outdoor-class surface).
+    /// The winning group carries a flag in the caller's `outdoor_mask`.
     pub(crate) outdoor: bool,
 }
 
-/// [`area_down_ray`] without the outdoor collapse (see it for the mechanism + provenance): the
-/// entity LIGHT chain needs to distinguish "outdoors because an EXTERIOR/EXTERIOR_LIT face won"
-/// from "outdoors because only terrain is below" — a deck unit and a field unit take different
-/// intensity laws (decision 0477).
+/// [`area_down_ray`] without the outdoor collapse: the light chain tells an outdoor-class face (a
+/// deck) from open terrain.
 pub(crate) fn down_ray_claim(
     tris: &[Vec<[[f32; 3]; 3]>],
     bounds: &[Option<([f32; 3], [f32; 3])>],
@@ -318,28 +268,12 @@ pub(crate) fn down_ray_claim(
     )
 }
 
-/// The same claim cast **upward** — the containment lane's retry, and only its retry.
-///
-/// `0x6a8ed0` anchors a GameObject's light node at the world bounding-box CENTRE (`[node+0x5c]`,
-/// decision 0776), and that box is the M2's **authored header** box — `0x713640` copies
-/// `MD20+0xB4` into it, where the sibling `0x713700` copies the *collision* box at `+0xD0`. For a
-/// particle-heavy model the authored box is enormous: `ONYZIASLAIRLAVATRAP.M2` authors one
-/// reaching 98.42 yd past its own bind pose (`benilla-extract animboundscan`), putting the anchor
-/// ~40 yd under the floor the object is standing on.
-///
-/// **The reference's own anchor is underground too**, and it recovers with a `+1000`-yd upward
-/// retry on the face ray — `6a908d fld [ebp-0x38]` / `6a9093 fadd ds:0x8022cc`, inside the
-/// containment body `0x6a8ed0` — which finds the floor from beneath it. wow-re
-/// `gobj-light-probe-points.md`.
-///
-/// [`footprint_sample_above`](super::interior::footprint_sample_above) is the SAME retry one stage
-/// later, and benilla had that half and not this one: 104 of Onyxia's lava traps never reached the
-/// footprint at all, because the claim that gates it came back empty and the verdict was
-/// "outdoors" before any colour was sampled.
-///
-/// **No terrain race here.** The downward cast loses its column to strictly-nearer terrain
-/// (standing over open ground); a cast going *up* from under a floor cannot meaningfully lose to
-/// the ground below it.
+/// The same claim cast upward: the containment lane's retry, and only that. `0x6a8ed0` anchors a
+/// GameObject's light node at its world bounding-box centre (`[node+0x5c]`), and that box is the M2
+/// header's authored one (`0x713640` copies `MD20+0xB4`, not the collision box `0x713700` copies),
+/// which can put a particle-heavy model's anchor 40 yd under its floor. The reference retries
+/// 1000 yd upward (`0x6a908d`, `0x6a9093`). No terrain race: a cast up from under a floor cannot
+/// lose to the ground below it.
 pub(crate) fn up_ray_claim(
     tris: &[Vec<[[f32; 3]; 3]>],
     bounds: &[Option<([f32; 3], [f32; 3])>],
@@ -351,8 +285,8 @@ pub(crate) fn up_ray_claim(
     ray_claim(tris, bounds, grids, nav, eye, None, outdoor_mask, true)
 }
 
-/// The shared body: `up` flips which side of the probe a face must lie on and which candidate
-/// wins — the nearest one in the cast's own direction, exactly as `footprint_scan` does it.
+/// The shared body: `up` flips which side of the probe a face must lie on; the nearest in the
+/// cast's direction wins.
 fn ray_claim(
     tris: &[Vec<[[f32; 3]; 3]>],
     bounds: &[Option<([f32; 3], [f32; 3])>],
@@ -363,18 +297,9 @@ fn ray_claim(
     outdoor_mask: u32,
     up: bool,
 ) -> Option<DownRayClaim> {
-    // Candidate selection is per FACE — the client's query is bbox-free (`zonetext-indoor-bit.md`
-    // (b): "No bbox, no portals, no camera"; the column containment lives inside `floor_z_at`).
-    // An AUTHORED group-box pre-cull once lived here, and it broke exactly where a MOGI box
-    // understates its geometry: NSabbey group 3's box bottom (z 1.84) floats above its own floor
-    // polys (z ≈ 0.3), so a probe at feet+0.1 dipped under the box, culled the whole group's
-    // faces, and the standing player's indoor verdict flapped (director-caught, 2026-07-12).
-    // The broad phase below is different in kind: `bounds` is the AABB **of the faces themselves**
-    // ([`WmoModel::group_collision_bounds`], computed at load), so the cull is exact — `floor_z_at`
-    // only hits inside a triangle's XY projection at z ≥ that group's min, and a group whose face
-    // bounds exclude the column can contribute nothing. Dropping the pre-cull entirely instead
-    // scanned every face of every resident building every frame: the 2026-07-12 fps regression
-    // (~8 ms/frame at Northshire).
+    // Candidates are per face: the client's query has no bbox, portals or camera (`0x6a8a20`).
+    // The broad phase is the AABB of the faces themselves (`group_collision_bounds`), never a
+    // group's authored box, which can float above its own floor; so the cull is exact.
     let column_owned = |gi: usize| {
         bounds.get(gi).copied().flatten().is_some_and(|(min, max)| {
             eye[0] >= min[0]
@@ -394,9 +319,8 @@ fn ray_claim(
         if !column_owned(gi) {
             continue;
         }
-        // The narrow phase: the group's column index when it has one, else its whole face list.
-        // The index yields a superset in ascending order (`column_grid`), so the first-wins tie on
-        // an exact `z` match below resolves exactly as the linear scan resolved it.
+        // Narrow phase: the column index, else every face. The index keeps ascending order, so an
+        // exact-`z` tie resolves first-wins as the linear scan does.
         let mut consider = |tri: &[[f32; 3]; 3]| {
             if let Some(z) = floor_z_at(tri, eye[0], eye[1]) {
                 let ahead = if up { z >= eye[2] } else { z <= eye[2] };
@@ -419,17 +343,17 @@ fn ray_claim(
         }
     }
     let in_group = best?;
-    // Beyond the ray → no claim at all.
+    // Beyond the ray: no claim.
     let depth = if up { best_z - eye[2] } else { eye[2] - best_z };
     if depth > ZONE_RAY_LEN {
         return None;
     }
-    // The terrain race: strictly-nearer terrain wins the column (standing over open ground);
-    // a tie keeps the WMO (`0x6a8b15`'s `t_wmo <= t_terr`).
+    // The terrain race: strictly nearer terrain wins the column; a tie keeps the WMO
+    // (`0x6a8b15`, `t_wmo <= t_terr`).
     if terrain_z.is_some_and(|tz| tz <= eye[2] && tz > best_z) {
         return None;
     }
-    // The caller's-law classification of the winner (`0x6a87f0` against `outdoor_mask`).
+    // The winner's class under the caller's law (`0x6a87f0` against `outdoor_mask`).
     let outdoor = nav
         .get(in_group)
         .is_none_or(|g| g.flags & outdoor_mask != 0);
@@ -441,7 +365,7 @@ fn ray_claim(
 }
 
 /// Point-in-polygon with the plane's dominant axis projected out (the client's `0x7c23e0`), for a
-/// point already on/near the plane.
+/// point on or near the plane.
 fn point_in_poly_dominant(verts: &[[f32; 3]], plane: [f32; 4], p: [f32; 3]) -> bool {
     let (u, v) = dominant_axes(plane);
     point_in_poly_2d(verts.iter().map(|q| (q[u], q[v])), (p[u], p[v]))
@@ -511,7 +435,7 @@ mod tests {
         .in_group
     }
 
-    /// `down_ray_pick` with a portal graph, no terrain — the pre-terrain-race fixtures.
+    /// `down_ray_pick` with a portal graph and no terrain.
     fn no_terrain(
         tris: &[Vec<[[f32; 3]; 3]>],
         nav: &[WmoGroupNav],
@@ -535,26 +459,23 @@ mod tests {
 
     #[test]
     fn face_leg_picks_the_group_of_the_nearest_face_below() {
-        // A tall outer group (floor z=0) with a small room nested inside it (floor z=10) — the
-        // vertical-nest case the bbox heuristic got wrong.
+        // A tall outer group (floor z=0) with a small room nested inside it (floor z=10).
         let outer = nav(0, [-30.0, -30.0, 0.0], [30.0, 30.0, 100.0], 0, 0);
         let room = nav(0, [-5.0, -5.0, 10.0], [5.0, 5.0, 16.0], 0, 0);
         let groups = [outer, room];
         let tris = [quad(0.0, 30.0), quad(10.0, 5.0)];
-        // Standing in the room (z=12): the room's floor (z=10) is nearer than the outer floor (z=0).
         assert_eq!(faces_only(&tris, &groups, [0.0, 0.0, 12.0]), Some(1));
-        // Below the room floor (z=5): only the outer floor is below ⇒ outer.
+        // Below the room floor: only the outer floor is below.
         assert_eq!(faces_only(&tris, &groups, [0.0, 0.0, 5.0]), Some(0));
-        // Out where only the big outer floor spans ⇒ outer.
         assert_eq!(faces_only(&tris, &groups, [20.0, 20.0, 5.0]), Some(0));
-        // No face anywhere near below (past MAX_FLOOR_DROP) ⇒ outside.
+        // Past MAX_FLOOR_DROP: outside.
         assert_eq!(faces_only(&tris, &groups, [0.0, 0.0, 5000.0]), None);
     }
 
     #[test]
     fn face_leg_is_orientation_agnostic() {
-        // A steep ramp face (nearly a wall — |n.z|/|n| ≈ 0.1, well under the old 0.3 floor filter)
-        // still owns the column: the walking-collision leg has no normal filter (audit Q3).
+        // A near-wall ramp face (|n.z|/|n| ≈ 0.1) still owns the column: the down-ray's segment
+        // query, run with the walking mask `0x84`, has no normal filter in its leaf (`0x6bc700`).
         let g = nav(0, [-10.0, -10.0, 0.0], [10.0, 10.0, 120.0], 0, 0);
         let steep = vec![[[-1.0, -1.0, 0.0], [1.0, -1.0, 0.0], [0.0, 1.0, 20.0]]];
         assert_eq!(faces_only(&[steep], &[g], [0.0, 0.0, 30.0]), Some(0));
@@ -562,8 +483,6 @@ mod tests {
 
     #[test]
     fn face_leg_exterior_face_reads_as_outside() {
-        // Standing over an EXTERIOR group's surface ⇒ outside (null), like the client clearing the
-        // instance.
         let ext = nav(EXTERIOR, [-30.0, -30.0, 0.0], [30.0, 30.0, 100.0], 0, 0);
         assert_eq!(
             faces_only(&[quad(0.0, 30.0)], &[ext], [0.0, 0.0, 5.0]),
@@ -571,8 +490,7 @@ mod tests {
         );
     }
 
-    /// A horizontal portal polygon (quad, radius `r`) at height `z`, plane `z - h = 0`
-    /// (normal +Z), starting at `start_vertex` 0.
+    /// A horizontal portal quad (radius `r`) at height `z`, normal +Z, from vertex 0.
     fn horizontal_portal(z: f32, r: f32) -> (Vec<[f32; 3]>, WmoPortalInfo) {
         let verts = vec![[-r, -r, z], [r, -r, z], [r, r, z], [-r, r, z]];
         let info = WmoPortalInfo {
@@ -586,8 +504,8 @@ mod tests {
     /// Per-group triangle sets, as the model stores them.
     type GroupTris = [Vec<[[f32; 3]; 3]>; 2];
 
-    /// The Goldshire-stairs shape: group 0 = the stairwell (floor z=0), group 1 = the taproom whose
-    /// floor-hole portal sits at z=10 over the stairwell column.
+    /// The Goldshire stairs: group 0 is the stairwell (floor z=0), group 1 the taproom whose
+    /// floor-hole portal sits at z=10 over the stairwell.
     fn stairwell() -> ([WmoGroupNav; 2], GroupTris) {
         let stair = nav(0, [-5.0, -5.0, 0.0], [5.0, 5.0, 11.0], 0, 1);
         let taproom = nav(0, [-20.0, -20.0, 10.0], [20.0, 20.0, 20.0], 1, 1);
@@ -611,9 +529,8 @@ mod tests {
                 side: 1,
             }, // taproom's ref: taproom is on the +normal side
         ];
-        // Eye above the hole plane (z=12): the portal crossing (z=10) beats the stair floor (z=0);
-        // the eye's side picks the TAPROOM as in-group, and the stairwell rides along as the
-        // across-group — BOTH are flood roots (the client's two-member seed set).
+        // Eye above the hole (z=12): the crossing beats the stair floor, the side pick names the
+        // taproom, and the stairwell rides along as the across-group.
         assert_eq!(
             no_terrain(&tris, &groups, &pverts, &infos, &refs, [0.0, 0.0, 12.0]),
             DownRaySeeds {
@@ -621,8 +538,7 @@ mod tests {
                 across: Some(0)
             }
         );
-        // Eye below the plane (z=5, on the stairs): the crossing is above the eye ⇒ face leg ⇒
-        // stairs alone (no portal crossing ⇒ no across-group).
+        // Eye below the plane (z=5): the face leg alone, the stairs with no across-group.
         assert_eq!(
             no_terrain(&tris, &groups, &pverts, &infos, &refs, [0.0, 0.0, 5.0]),
             DownRaySeeds {
@@ -630,7 +546,7 @@ mod tests {
                 across: None
             }
         );
-        // Eye above the plane but outside the hole polygon ⇒ no crossing, no floor ⇒ outside.
+        // Above the plane but outside the hole: no crossing, no floor, outside.
         assert_eq!(
             no_terrain(&tris, &groups, &pverts, &infos, &refs, [10.0, 10.0, 12.0]),
             DownRaySeeds::default()
@@ -639,7 +555,7 @@ mod tests {
 
     #[test]
     fn portal_crossing_respects_the_side_orientation() {
-        // Same stairwell but the portal plane's normal points DOWN (−Z), so the side flags mirror.
+        // The same stairwell with the portal normal pointing down (−Z): the side flags mirror.
         let (groups, tris) = stairwell();
         let verts = vec![
             [-5.0, -5.0, 10.0],
@@ -676,11 +592,10 @@ mod tests {
 
     #[test]
     fn coincident_portal_beats_the_slab_face_by_the_tie_eps() {
-        // The slab's collision face and the floor-hole portal share z=10 exactly. The eye above must
-        // resolve to the portal's side pick (the taproom), not the slab face's own group — the
-        // client's ~1e-4 nearest-accept lets the portal win the tie.
+        // The slab's collision face and the floor-hole portal share z=10: the portal's side pick
+        // (the taproom) wins the tie by the client's ~1e-4 nearest-accept.
         let (groups, mut tris) = stairwell();
-        tris[0].extend(quad(10.0, 5.0)); // a slab face owned by the STAIR group, coincident with p0
+        tris[0].extend(quad(10.0, 5.0)); // a slab face owned by the stair group, coincident with p0
         let (pverts, pinfo) = horizontal_portal(10.0, 5.0);
         let refs = [
             WmoPortalRef {
@@ -702,13 +617,11 @@ mod tests {
 
     #[test]
     fn vertical_doorway_snaps_only_within_the_window() {
-        // A vertical doorway portal in the x=0 plane between room A (x<0, floor z=0) and room B
-        // (x>0, floor z=0), both floors owned by room A's mesh right up to x=+0.5 — the straddle:
-        // the face under the column lags the room boundary.
+        // A vertical doorway in the x=0 plane between room A (x<0) and room B (x>0), with room A's
+        // floor running past it to x=0.5: the face under the column lags the room boundary.
         let room_a = nav(0, [-10.0, -10.0, 0.0], [0.5, 10.0, 10.0], 0, 1);
         let room_b = nav(0, [-0.5, -10.0, 0.0], [10.0, 10.0, 10.0], 1, 1);
         let groups = [room_a, room_b];
-        // Room A's floor extends past the doorway to x=0.5; room B's floor starts at 0.5.
         let tris = [
             vec![
                 [[-10.0, -10.0, 0.0], [0.5, -10.0, 0.0], [0.5, 10.0, 0.0]],
@@ -742,9 +655,8 @@ mod tests {
                 side: 1,
             }, // room B is on the +normal side
         ];
-        // Eye 0.05 past the plane into room B, inside the doorway: within the 0.1-yd snap — the
-        // doorway counts as crossed at the eye, beating room A's floor face; the side pick says B,
-        // and A rides along as the across-group. The straddle is covered by the seed set.
+        // Eye 0.05 into room B, within the 0.1 yd snap: the doorway is crossed at the eye and beats
+        // room A's floor; B is the in-group and A rides along.
         assert_eq!(
             no_terrain(&tris, &groups, &verts, &infos, &refs, [0.05, 0.0, 1.7]),
             DownRaySeeds {
@@ -752,10 +664,8 @@ mod tests {
                 across: Some(0)
             }
         );
-        // Eye 0.3 past the plane: beyond the snap window — the doorway is NOT crossed (the client's
-        // parallel branch returns no hit) and the face under the column decides: still room A's mesh
-        // at x=0.3, so the seed is room A. The real client is protected here by the collision mesh
-        // tracking the boundary to sub-yard — the mechanism, not a doorway tolerance (audit Q5).
+        // Eye 0.3 in, beyond the snap: the doorway is not crossed and room A's floor decides. Real
+        // collision meshes track the room boundary to sub-yard (`0x6b92b0`).
         assert_eq!(
             no_terrain(&tris, &groups, &verts, &infos, &refs, [0.3, 0.0, 1.7]),
             DownRaySeeds {
@@ -765,9 +675,7 @@ mod tests {
         );
     }
 
-    /// `area_down_ray` over per-group tris on the zone-text law (`0x8` alone), with the bounds
-    /// computed from the faces (the load-time path, via the shared helper — fixtures and the
-    /// loader can't disagree).
+    /// `area_down_ray` on the zone-text law (`0x8` alone), with the loader's own face bounds.
     fn area_ray(
         tris: &[Vec<[[f32; 3]; 3]>],
         nav: &[WmoGroupNav],
@@ -779,21 +687,15 @@ mod tests {
         area_down_ray(tris, &bounds, &grids, nav, eye, terrain_z, EXTERIOR)
     }
 
-    /// **A body planted UNDER the floor it stands on is invisible to the position cast, and the
-    /// under-floor fallback is what finds it** (decision 1409). Orgrimmar's bonfires, braziers,
-    /// meat racks and shop signs are authored 0.45–1.16 yd below the group floor they sit in — a
-    /// ray down from the origin passes beneath that floor and reports open ground, which the
-    /// exterior-scene election reads as "outdoors" and hides. `room_at`'s second pass re-casts from
-    /// `ROOM_UNDER_FLOOR_TOLERANCE` higher; this pins both halves of why that works: the cast from
-    /// the origin really does miss, the lifted one really does find the same floor, and the lift is
-    /// far enough to cover the measured spread and no further.
+    /// A body planted under its floor is invisible to the position cast; `room_at`'s lifted second
+    /// pass finds the same floor, and reaches no further than the tolerance.
     #[test]
     fn an_under_floor_origin_is_found_only_by_the_lifted_cast() {
         let floor = [quad(0.0, 20.0)];
         let nav = [nav(0, [-20.0, -20.0, 0.0], [20.0, 20.0, 0.0], 0, 0)];
         let lift = super::super::interior::POSITION_PROBE_LIFT;
         let tol = super::super::interior::ROOM_UNDER_FLOOR_TOLERANCE;
-        // The worst measured burial (Orgrimmar bonfire 177026, 1.16 yd under group 134's floor).
+        // Orgrimmar's measured burials, 1.16 yd the worst (bonfire 177026).
         for buried in [0.45_f32, 1.16] {
             let feet = -buried;
             assert_eq!(
@@ -807,8 +709,7 @@ mod tests {
                 "the under-floor fallback must find it ({buried} yd)"
             );
         }
-        // …and the lift is a tolerance, not a licence: a floor further above than it stays unclaimed,
-        // which is what keeps the storey above out of reach.
+        // A floor further above than the tolerance stays unclaimed: no reach to the storey above.
         assert_eq!(
             area_ray(&floor, &nav, [0.0, 0.0, -(tol + 1.0) + lift + tol], None),
             None,
@@ -816,21 +717,17 @@ mod tests {
         );
     }
 
-    /// **The column index never changes a down-ray verdict.** A dungeon-shaped face set (a big
-    /// stack of small floor quads at varying heights, spread over several groups) answered with
-    /// the per-group column index must equal the answer from the plain linear scan, column for
-    /// column — group, depth and outdoor class. The index is a narrow phase, and a narrow phase
-    /// that can re-rank moves a unit's room, its light and the zone name.
+    /// The column index never changes a down-ray claim: group, depth and outdoor class all match
+    /// the linear scan, column for column.
     #[test]
     fn down_ray_column_index_is_exact() {
-        // Three stacked storeys of floor tiles in the same XY column range — the Blackrock shape
-        // that defeats the per-group bounds broad phase (every group owns the column).
+        // Three stacked storeys over the same XY range, so every group owns every column.
         let storey = |z: f32| -> Vec<[[f32; 3]; 3]> {
             let mut out = Vec::new();
             for ix in 0..10 {
                 for iy in 0..10 {
                     let (x, y) = (ix as f32 * 3.0, iy as f32 * 3.0);
-                    // Vary z within the storey so which tile wins is observable.
+                    // Vary z within the storey so the winning tile is observable.
                     let tz = z + ((ix + iy) % 4) as f32 * 0.25;
                     out.push([[x, y, tz], [x + 3.0, y, tz], [x + 3.0, y + 3.0, tz]]);
                     out.push([[x, y, tz], [x + 3.0, y + 3.0, tz], [x, y + 3.0, tz]]);
@@ -880,11 +777,8 @@ mod tests {
 
     #[test]
     fn area_ray_face_bounds_survive_a_lying_authored_box() {
-        // The NSabbey group-3 shape (director-caught flap, 2026-07-12): the AUTHORED nav box
-        // bottom (z 1.84) floats above the group's own floor polys (z 0.3). A probe cast from the
-        // position (feet + 0.1 ≈ 0.4) dips under the authored box — the old authored-box pre-cull
-        // dropped the group here. The broad phase must be the FACE-derived bounds, which reach
-        // down to the real floor; reintroducing any authored-box cull fails this test.
+        // Northshire Abbey group 3: the authored box bottom (z 1.84) floats above the group's own
+        // floor (z 0.3), so a position probe (z 0.4) is under the box. Any authored-box cull fails.
         let lying_box = nav(0, [-10.0, -10.0, 1.84], [10.0, 10.0, 20.0], 0, 0);
         let tris = [quad(0.3, 10.0)]; // the group's real floor, below its authored box
         assert_eq!(
@@ -895,9 +789,7 @@ mod tests {
 
     #[test]
     fn area_ray_broad_phase_is_exactly_conservative() {
-        // Two groups side by side; the broad phase must scan only the owning column — and must
-        // never change an answer: inside either column the verdict matches the face scan, outside
-        // both it is None (nothing to hit).
+        // Two groups side by side: the broad phase never changes an answer.
         let g0 = nav(0, [-10.0, -10.0, 0.0], [0.0, 10.0, 10.0], 0, 0);
         let g1 = nav(0, [5.0, -10.0, 0.0], [15.0, 10.0, 10.0], 0, 0);
         let west = vec![
@@ -914,14 +806,12 @@ mod tests {
         assert_eq!(area_ray(&tris, &navs, [10.0, 0.0, 3.0], None), Some(1));
         // In the gap between the buildings: no face owns the column.
         assert_eq!(area_ray(&tris, &navs, [2.5, 0.0, 5.0], None), None);
-        // Over a group but BELOW its faces: the column reaches nothing at/below the eye.
+        // Over a group but below its faces.
         assert_eq!(area_ray(&tris, &navs, [10.0, 0.0, 1.0], None), None);
     }
 
     #[test]
     fn area_ray_exterior_and_terrain_race_hold() {
-        // The EXTERIOR-flag and terrain-race legs are unchanged by the broad phase: an exterior
-        // group's surface reads outdoors, and strictly-nearer terrain steals the column.
         let ext = nav(EXTERIOR, [-10.0, -10.0, 0.0], [10.0, 10.0, 10.0], 0, 0);
         assert_eq!(
             area_ray(&[quad(0.0, 10.0)], &[ext], [0.0, 0.0, 1.0], None),
@@ -940,9 +830,8 @@ mod tests {
 
     #[test]
     fn exterior_lit_group_splits_the_two_laws() {
-        // The Stormwind-street shape (decision 0475): a `0x40`-only group (EXTERIOR_LIT, no
-        // EXTERIOR) is "indoors" on the zone-text law (`[node+0x90]` bit 0 keys on `0x8` alone)
-        // but OUTDOORS on the unit-lighting law (the `0x6a87f0` class fork keys on `MOGI & 0x48`).
+        // A Stormwind street: a `0x40`-only group is indoors on the zone-text law (`0x8` alone)
+        // but outdoors on the unit-lighting law (`MOGI & 0x48`).
         let street = nav(EXTERIOR_LIT, [-10.0, -10.0, 0.0], [10.0, 10.0, 10.0], 0, 0);
         let tris = [quad(0.0, 10.0)];
         let (bounds, _) = benilla_assets::collision_tri_bounds(&tris);
@@ -969,12 +858,9 @@ mod tests {
 
     #[test]
     fn the_upward_retry_recovers_a_floor_from_beneath_it() {
-        // The Onyxia lava trap's shape. A GameObject's light node anchors at its AUTHORED-box
-        // centre, and that model's box reaches 98 yd past its own geometry, so the anchor sits
-        // ~40 yd under the chamber floor it stands on. The downward cast finds nothing — every
-        // face is ABOVE the probe — and the reference recovers with the containment lane's
-        // `+1000` upward retry (`6a908d`/`6a9093`). Before it, 104 traps in a WMO-only interior
-        // classified as outdoors and took the day/night sun, meshes and particles alike.
+        // An Onyxia lava trap anchors about 40 yd under its chamber floor (its authored box reaches
+        // 98 yd past its geometry): the downward cast finds nothing and the upward retry
+        // (`0x6a908d`) finds the floor.
         let room = nav(0, [-10.0, -10.0, 0.0], [10.0, 10.0, 10.0], 0, 0);
         let tris = [quad(0.0, 10.0)]; // the chamber floor at z = 0
         let (bounds, _) = benilla_assets::collision_tri_bounds(&tris);
@@ -993,7 +879,7 @@ mod tests {
             "depth is measured along the cast's own direction, got {}",
             c.depth
         );
-        // The retry is still a RAY, not a licence: a face below the probe never claims it.
+        // The retry is still a ray: a face below the probe never claims it.
         assert_eq!(
             up_ray_claim(&tris, &bounds, &[], &[room], [0.0, 0.0, 40.0], mask),
             None
@@ -1002,10 +888,8 @@ mod tests {
 
     #[test]
     fn down_ray_claim_distinguishes_deck_from_terrain() {
-        // The Booty Bay boardwalk shape (decision 0477): the un-collapsed claim keeps the
-        // "outdoors ON an outdoor-class WMO face" vs "outdoors over terrain" distinction the
-        // collapsed `area_down_ray` erases — a deck unit forces the lit 2.5, a field unit takes
-        // the MCSH fork. Depth is the cross-placement arbitration key.
+        // A Booty Bay boardwalk: the claim tells an outdoor-class face from open terrain, which
+        // `area_down_ray` collapses.
         let deck = nav(
             EXTERIOR | EXTERIOR_LIT,
             [-10.0, -10.0, 0.0],
@@ -1016,7 +900,7 @@ mod tests {
         let tris = [quad(5.0, 10.0)]; // the deck surface, 30-ish yd over terrain at z -25
         let (bounds, _) = benilla_assets::collision_tri_bounds(&tris);
         let mask = EXTERIOR | EXTERIOR_LIT;
-        // Standing on the deck (terrain far below): an OUTDOOR claim, depth = probe − face.
+        // On the deck, terrain far below: an outdoor claim, depth = probe − face.
         let c = down_ray_claim(
             &tris,
             &bounds,
@@ -1029,7 +913,7 @@ mod tests {
         .expect("the deck face claims the column");
         assert!(c.outdoor && c.group == 0);
         assert!((c.depth - 0.5).abs() < 1e-6);
-        // Terrain strictly nearer (probe over open ground above a buried deck): no claim at all.
+        // Terrain strictly nearer, over a buried deck: no claim.
         assert_eq!(
             down_ray_claim(
                 &tris,
@@ -1042,7 +926,6 @@ mod tests {
             ),
             None
         );
-        // An interior group's face under the same probe: a non-outdoor claim.
         let room = nav(0, [-10.0, -10.0, 0.0], [10.0, 10.0, 10.0], 0, 0);
         let c = down_ray_claim(&tris, &bounds, &[], &[room], [0.0, 0.0, 5.5], None, mask)
             .expect("the room face claims the column");
@@ -1062,10 +945,10 @@ mod tests {
 
     #[test]
     fn terrain_race_drops_a_buried_interior_but_spares_one_under_the_hill() {
-        // One indoor group: a mine tunnel with its floor at z=0, ceiling bbox to z=10.
+        // A mine tunnel with its floor at z=0, its box to z=10.
         let mine = nav(0, [-20.0, -20.0, 0.0], [20.0, 20.0, 10.0], 0, 0);
         let tris = [quad(0.0, 20.0)];
-        // A camera 2 yd over the tunnel floor. With no terrain leg (or terrain far below), it is inside.
+        // A camera 2 yd over the tunnel floor, no terrain: inside.
         assert_eq!(
             down_ray_pick(
                 &tris,
@@ -1081,9 +964,7 @@ mod tests {
             .in_group,
             Some(0)
         );
-        // The hillside surface sits at z=8, between the eye (z=2) and... no: the eye is BELOW the
-        // surface, so the surface is above the eye and off the down-segment — a real tunnel under a
-        // hill still reads INSIDE.
+        // Hillside terrain at z=8 is above the eye, off the segment: the tunnel stays inside.
         assert_eq!(
             down_ray_pick(
                 &tris,
@@ -1099,8 +980,7 @@ mod tests {
             .in_group,
             Some(0)
         );
-        // Now the camera is in open air 12 yd up, and the ground surface is at z=8 — below the eye and
-        // ABOVE the tunnel floor (z=0). The terrain wins the column: outside.
+        // A camera 12 yd up over ground at z=8, above the tunnel floor: the terrain wins, outside.
         assert_eq!(
             down_ray_pick(
                 &tris,
@@ -1116,8 +996,7 @@ mod tests {
             .in_group,
             None
         );
-        // A terrain surface exactly coincident with the WMO floor keeps the WMO (the client's strict
-        // `<`: equal is not "strictly nearer").
+        // Terrain exactly at the WMO floor keeps the WMO (the client's strict `<`).
         assert_eq!(
             down_ray_pick(
                 &tris,
@@ -1133,7 +1012,7 @@ mod tests {
             .in_group,
             Some(0)
         );
-        // A terrain surface just above the floor (z=0.1 vs floor 0) steals the column.
+        // Terrain just above the floor steals the column.
         assert_eq!(
             down_ray_pick(
                 &tris,
@@ -1153,12 +1032,12 @@ mod tests {
 
     #[test]
     fn camera_void_fallback_names_the_detail_floored_room() {
-        // The Deadmines-pocket shape (decision 0692): an interior group whose only floor is DETAIL
-        // faces — present in the camera-only set, absent from the walking set.
+        // The Deadmines pocket: an interior group floored only with DETAIL faces, which are in the
+        // camera-only set and not the walking set.
         let pocket = nav(0, [-10.0, -10.0, 0.0], [10.0, 10.0, 12.0], 0, 0);
         let walk: [Vec<[[f32; 3]; 3]>; 1] = [Vec::new()];
         let detail = [quad(0.0, 10.0)];
-        // Both faithful legs miss, no terrain below ⇒ Leg C names the room, single root.
+        // Legs A and B miss, no terrain below: Leg C names the room, a single root.
         let s = down_ray_pick(
             &walk,
             &[],
@@ -1172,7 +1051,7 @@ mod tests {
         );
         assert_eq!(s.in_group, Some(0));
         assert_eq!(s.across, None);
-        // Terrain under a hill (surface above the eye) is off the down-segment: Leg C still fires.
+        // Terrain above the eye is off the segment: Leg C still fires.
         assert_eq!(
             down_ray_pick(
                 &walk,
@@ -1194,8 +1073,7 @@ mod tests {
     fn camera_void_fallback_defers_to_terrain_and_to_the_walking_leg() {
         let pocket = nav(0, [-10.0, -10.0, 0.0], [10.0, 10.0, 12.0], 0, 0);
         let detail = [quad(0.0, 10.0)];
-        // Any terrain surface at/below the eye (a doorstep decal over open ground) keeps the client's
-        // outside verdict — the fallback's gate.
+        // Any terrain at or below the eye keeps the client's outside verdict.
         assert_eq!(
             down_ray_pick(
                 &[Vec::new()],
@@ -1211,8 +1089,7 @@ mod tests {
             .in_group,
             None
         );
-        // A walking-leg answer anywhere (even a lower floor of another group) pre-empts Leg C: the
-        // faithful verdict is never touched.
+        // A walking-leg answer, even a lower floor of another group, pre-empts Leg C.
         let hall = nav(0, [-30.0, -30.0, -5.0], [30.0, 30.0, 12.0], 0, 0);
         let walk = [Vec::new(), quad(-5.0, 30.0)];
         let det2: [Vec<[[f32; 3]; 3]>; 2] = [quad(0.0, 10.0), Vec::new()];
@@ -1231,7 +1108,7 @@ mod tests {
             .in_group,
             Some(1)
         );
-        // An EXTERIOR group's detail surface reads as outside, mirroring Leg A's rule.
+        // An EXTERIOR group's detail surface reads as outside, as in Leg A.
         let ext = nav(EXTERIOR, [-10.0, -10.0, 0.0], [10.0, 10.0, 12.0], 0, 0);
         assert_eq!(
             down_ray_pick(
diff --git a/crates/benilla-world/src/world_census.rs b/crates/benilla-world/src/world_census.rs
index 4f619074..3426e0a5 100644
--- a/crates/benilla-world/src/world_census.rs
+++ b/crates/benilla-world/src/world_census.rs
@@ -1,25 +1,7 @@
-//! **[`WorldCensus`] — what the engine drew this frame, published as a fact.**
-//!
-//! Every number an instrument wants about a rendered frame — how many submeshes exist, how many
-//! survived to `ViewVisibility`, which subsystem each belongs to, what the exterior-scene gate did,
-//! how many emitters are alive, what the asset caches are holding, what got rewritten since the
-//! last frame — is a fact the *renderer* owns. Before this module the probes read it by querying
-//! the renderer's own components and resources directly, and that one file
-//! (`capture/probes/live_fps.rs`) named nine engine internals nobody else outside the engine
-//! needed: four material aliases, the two exterior-cull types, the two portal types, and the
-//! camera's interior claim. Decision 1164 sorts all nine into CLOSE with the same remedy —
-//! *publish the census, not the components* — and this is that census.
-//!
-//! It is one read-only [`SystemParam`] and one snapshot type. An instrument adds the param, calls
-//! [`WorldCensus::take`] on the frame it cares about, and formats the snapshot however its own
-//! output contract wants. **No `println!` lives here**: the line shapes (`VIS_CENSUS`,
-//! `MAT_CHURN`, `ASSET_DUMP`) are the probes' greppable contract, not the engine's, and an engine
-//! that formats its callers' output has the boundary backwards.
-//!
-//! The one part that is opt-in is the churn window: counting `AssetEvent::Modified` per asset type
-//! costs a `MessageReader` per type per frame, so [`WorldCensus::churn_counters`] installs them
-//! and an ordinary run carries none. **Which** types are counted is engine knowledge (it is the
-//! engine's material set); **whether** to count is the instrument's call.
+//! [`WorldCensus`]: what the engine drew this frame, as plain data for instruments. An instrument
+//! calls [`WorldCensus::take`] on the frame it wants and formats the report itself; the line
+//! shapes (`VIS_CENSUS`, `MAT_CHURN`, `ASSET_DUMP`) belong to the probes. The churn window is
+//! opt-in, since [`WorldCensus::churn_counters`] costs a `MessageReader` per asset type per frame.
 
 use std::collections::HashMap;
 
@@ -35,31 +17,19 @@ use crate::particles::ParticleEmitter;
 use crate::wmo_portal::{CameraInteriorClaim, ExteriorWindows, WmoGroupVis};
 use benilla_assets::materials::WowModelMaterial;
 
-/// A read-only view of the engine's drawn state — the whole of it, as one system parameter.
-///
-/// Deliberately one param and not eight: `drive_live_fps` sits at Bevy's 16-param ceiling, and
-/// every instrument that wants any of this wants most of it, taken from the *same frame*. Two
-/// instruments each assembling their own half is how the two disagree.
+/// A read-only view of the engine's drawn state as one system parameter, so an instrument at
+/// Bevy's 16-parameter ceiling can take all of it from the same frame.
 #[derive(SystemParam)]
 pub struct WorldCensus<'w, 's> {
-    /// Every spawned model submesh, with the facts that make a visible one accountable.
     parts: Query<'w, 's, CensusData>,
     emitters: Query<'w, 's, &'static ParticleEmitter>,
-    /// The placement registry, for the duplicate census (`orphan_parts=`): a placed part alive
-    /// that no registered placement owns. Optional for a viewer with no streamer.
     placements: Option<Res<'w, crate::terrain_stream::Placements>>,
     streamer: Option<Res<'w, crate::terrain_stream::TerrainStreamer>>,
-    /// The exterior-scene gate's two terms (decision 0774) and what the cull actually did with
-    /// them. Optional so the census works in a viewer that has not installed the portal system.
     claim: Option<Res<'w, CameraInteriorClaim>>,
     windows: Option<Res<'w, ExteriorWindows>>,
     verdict: Option<Res<'w, ExteriorCullVerdict>>,
-    /// The visibility authority's own pose (see [`CensusReport::pvs_eye`]).
     cull_probe: Option<Res<'w, crate::wmo_portal::WmoCullProbe>>,
-    /// Which backdrop is drawing — the gradient dome, or a building's own MOSB sky
-    /// ([`crate::skybox`]). Optional for the same reason as the portal terms above.
     skybox: Option<Res<'w, crate::skybox::CameraSkybox>>,
-    /// The ribbon lane's own verdict — the third effect population, counted nowhere else.
     ribbons: Option<Res<'w, crate::ribbons::RibbonVerdict>>,
     mats: Res<'w, Assets<WowModelMaterial>>,
     meshes: Res<'w, Assets<Mesh>>,
@@ -68,99 +38,73 @@ pub struct WorldCensus<'w, 's> {
     uv_reg: Res<'w, UvAnimMaterials>,
     tint_reg: Res<'w, TintAnimMaterials>,
     server: Res<'w, AssetServer>,
-    /// Present only once [`WorldCensus::churn_counters`] has been installed.
     churn: Option<ResMut<'w, ChurnCensus>>,
 }
 
-/// One frame's census, in the order an instrument prints it. Plain data on purpose: an instrument
-/// holding this holds no engine component, no engine resource and no engine type it has to name.
+/// One frame's census as plain data, in the order an instrument prints it.
 #[derive(Default)]
 pub struct CensusReport {
-    /// Every model submesh that exists.
     pub submeshes: usize,
-    /// Placed (doodad/WMO) parts alive that no registered placement owns — the duplicate
-    /// census. Zero in a healthy world; a doubled prop is exactly one of these per part.
+    /// Placed doodad and WMO parts that no registered placement owns: zero in a healthy world, one
+    /// per part of a doubled prop.
     pub orphan_parts: usize,
-    /// Parts whose `VisibilityClass` holds a duplicate entry — each is queued and drawn once
-    /// per entry (`model_render::park`'s dedup is the fix; this is the census that names a
-    /// regression).
+    /// Parts whose `VisibilityClass` lists a class twice; each is queued and drawn once per entry.
     pub stacked_parts: usize,
     /// The orphans by `(placement id, model label, parts)`, most parts first.
     pub orphans: Vec<(u32, String, usize)>,
     /// Resident tiles `(furnished, in window)`, off the streamer.
     pub tiles: Option<(usize, usize)>,
-    /// …and how many of them the render world will actually draw (`ViewVisibility`).
+    /// Submeshes the render world will draw (`ViewVisibility`).
     pub drawn: usize,
-    /// Visible submeshes per model subsystem — `(column name, visible, of-those-gated)` — in a
-    /// fixed column order, because a census whose columns move cannot be diffed across runs.
+    /// Visible submeshes per model subsystem, `(column, visible, of those gated)`, in fixed order.
     pub kinds: [(&'static str, usize, usize); 4],
-    /// Resident submeshes per model subsystem, same column order as `kinds` — hidden or not.
-    /// A city's hidden twins (the retained pass draws them) ride every per-`Mesh3d` sweep
-    /// whether they draw or not, and this is the count that prices them.
+    /// Resident submeshes per model subsystem, hidden or not, in `kinds`' column order.
     pub resident: [usize; 4],
     /// Resident submeshes per `EntityPathWhy` label (the streamer's reason a batch is an
     /// entity), most first; `"-"` for the untagged (units, GameObjects, the app lane).
     pub why: Vec<(&'static str, usize)>,
-    /// Of every [`ExteriorScene`]-tagged submesh: how many exist, how many the cull wrote `Hidden`
-    /// on, how many were exempt (the camera's own placement — decision 0784), and how many carry
-    /// **no `Aabb`**, which is the cull's fail-open arm admitting them unconditionally.
+    /// Of the [`ExteriorScene`]-tagged submeshes: how many exist, are `Hidden`, are exempt (the
+    /// camera's own placement), and have no `Aabb`, which the cull admits unconditionally.
     pub tagged: usize,
     pub hidden: usize,
     pub exempt: usize,
     pub no_aabb: usize,
-    /// Tagged, bounded, not exempt, and yet not `Hidden` — the escapees, `(label, is a billboard
-    /// card, count)`, most first. A tagged object the cull left un-hidden is a defect by
-    /// construction, which is why this is not behind a flag.
+    /// Tagged, bounded, not exempt and still not `Hidden`, as `(label, is a billboard card,
+    /// count)`, most first: each one is a cull defect.
     pub escaped: Vec<(String, bool, usize)>,
-    /// Visible submeshes per distinct label, `(label, gated, count)` — ungated first (the leak
-    /// candidates), then most-drawn first. The "so WHICH trees are they?" list.
+    /// Visible submeshes per label, `(label, gated, count)`, ungated first, then most drawn.
     pub labels: Vec<(String, bool, usize)>,
     pub emitters: usize,
     pub active_emitters: usize,
     pub particles: usize,
-    /// Ribbon trails alive, and how many wrote a strip — `None` if the lane is not installed.
-    /// The `emitters`/`particles` pair above covers only the QUAD half of the effect stream;
-    /// trails are the other half and had no counter at all.
+    /// Ribbon trails alive and how many wrote a strip; `None` without the ribbon lane.
     pub ribbons: Option<(usize, usize)>,
-    /// The WMO group the camera claims — `"g07"`, or `"none"` over open world. `None` when the
-    /// portal system is not installed at all, which is a different statement from "not indoors".
+    /// The WMO group the camera claims (`"g07"`, or `"none"` outdoors); `None` without portals.
     pub room: Option<String>,
     /// `"unrestricted"`, or the number of window sub-frusta. `None` with [`CensusReport::room`].
     pub windows: Option<String>,
-    /// **The eye the portal authority computed [`Self::room`], [`Self::windows`] and every group's
-    /// PVS from.** Not necessarily the eye this frame draws from: the authority runs in `Update`
-    /// off the camera's propagated transform, so it is answering about wherever the camera was
-    /// when that transform was last written. Walking makes the difference a centimetre; a
-    /// teleport makes it the whole jump, and this is the column that says so.
+    /// The eye the portal authority computed [`Self::room`], [`Self::windows`] and the PVS from,
+    /// the last propagated camera transform; after a teleport it lags the drawn eye.
     pub pvs_eye: Option<Vec3>,
-    /// The backdrop actually drawing: `"dome"` for the `Light.dbc` gradient, else the WMO skybox
-    /// model a building's PVS asked for. `None` when the WMO-sky lane is not installed.
-    ///
-    /// Here because a skybox is the one draw that can repaint the whole frame while being
-    /// invisible to every other line in this report: its batches carry no [`ModelPart`], so they
-    /// are not in `submeshes`, not in `drawn`, not in `kinds`, and not in `labels`. Standing
-    /// outdoors in Tanaris with a purple sky and no purple *object* on any list is exactly the
-    /// state that has to be readable, and before this it was not.
+    /// The backdrop: `"dome"` for the `Light.dbc` gradient, else the WMO skybox model (whose
+    /// batches carry no [`ModelPart`], so no other count sees them); `None` without that lane.
     pub sky: Option<String>,
     /// What the exterior cull did this frame, `None` if it did not run.
     pub cull: Option<CullTerms>,
-    /// Resident asset counts — the leak meter. A tour probe reading the same counts as a fresh
-    /// control is what "torn down" means, machine-checked.
+    /// Resident asset counts: the leak meter.
     pub mats: usize,
-    /// Built materials parked by `model_render::lazy`, not yet assets — the variants nothing
-    /// visible has bound. `mats` counts realized ones only.
+    /// Built materials `model_render::lazy` parks until something visible binds them.
     pub mats_parked: usize,
     pub meshes: usize,
     pub images: usize,
     pub uv_anims: usize,
     pub tint_anims: usize,
-    /// `AssetEvent::Modified` totals per asset type since the window opened, sorted by type name.
+    /// `AssetEvent::Modified` totals per asset type since the window opened, sorted by label.
     /// Empty unless [`WorldCensus::churn_counters`] is installed.
     pub churn: Vec<(&'static str, usize)>,
 }
 
-/// [`ExteriorCullVerdict`] relayed as plain numbers — see that type for what each term means and
-/// why `tested` is the one no other instrument can see.
+/// [`ExteriorCullVerdict`] as plain numbers; that type documents each term.
 pub struct CullTerms {
     /// The window count it was given, or `"unrestricted"`.
     pub windows: String,
@@ -168,19 +112,16 @@ pub struct CullTerms {
     pub tested: usize,
     pub hidden: usize,
     pub unbounded: usize,
-    /// The body leg, kept apart from `tested`/`hidden` — see the verdict's own note for why summing
-    /// a two-dozen audience into a tens-of-thousands one erases it.
+    /// The body leg, counted apart from `tested` and `hidden`.
     pub bodies: usize,
     pub bodies_hidden: usize,
-    /// The liquid subset of `tested`/`hidden` — see the verdict's own note for why a few dozen
-    /// surfaces summed into tens of thousands of terrain cells is an invisible leg (1652).
+    /// The liquid subset of `tested` and `hidden`.
     pub liquid: usize,
     pub liquid_hidden: usize,
 }
 
 impl WorldCensus<'_, '_> {
-    /// Install the per-asset-type churn counters (in `First`, before anything can modify an
-    /// asset this frame). Off by default — see the module header for the split of who decides.
+    /// Installs the per-asset-type churn counters in `First`, before anything modifies an asset.
     pub fn churn_counters(app: &mut App) {
         app.init_resource::<ChurnCensus>();
         Self::count_churn::<bevy::image::Image>(app, "image");
@@ -196,29 +137,25 @@ impl WorldCensus<'_, '_> {
         Self::count_churn::<crate::clouds::CloudMaterial>(app, "cloud");
     }
 
-    /// Add one more asset type to the churn window under `label`. The engine counts its own
-    /// materials in [`WorldCensus::churn_counters`]; a host with materials of its own (the UI
-    /// pass, a tool's overlay) folds them in here rather than keeping a second, disagreeing
-    /// census. Call after `churn_counters`, which is what creates the tally.
+    /// Adds an asset type to the churn window under `label`, for a host's own materials; call it
+    /// after `churn_counters`, which creates the tally.
     pub fn count_churn<A: bevy::asset::Asset>(app: &mut App, label: &'static str) {
         app.add_systems(First, churn_counter::<A>(label));
     }
 
-    /// Open a fresh churn window. Warmup noise — streaming, shader warms — otherwise reads as a
-    /// steady-state ratchet, so the instrument calls this on the first frame it actually samples.
+    /// Opens a fresh churn window; call it on the first sampled frame so warm-up is not counted.
     pub fn restart_churn(&mut self) {
         if let Some(churn) = self.churn.as_mut() {
             churn.0.clear();
         }
     }
 
-    /// Snapshot this frame.
-    /// Live particles this instant — the one census number cheap enough to sample per frame
-    /// (a fold over the emitters, no part walk): a spell burst's signature on a tail frame.
+    /// Live particles now: a fold over the emitters, cheap enough to sample every frame.
     pub fn live_particles(&self) -> usize {
         self.emitters.iter().map(|p| p.live()).sum()
     }
 
+    /// Snapshot this frame.
     pub fn take(&self) -> CensusReport {
         let own_instance = self
             .claim
@@ -241,14 +178,9 @@ impl WorldCensus<'_, '_> {
             self.parts.iter()
         {
             submeshes += 1;
-            // A part whose `VisibilityClass` lists its mesh class more than once is queued
-            // that many times a frame — drawn stacked on itself (`model_render::park`).
             stacked_parts += usize::from(class.is_some_and(|c| c.len() > 1));
-            // The duplicate census: a doodad/WMO part is spawned by exactly one placement and
-            // recorded on it; one alive outside every placement's list outlived a respawn. The
-            // one population that lives outside the registry by design is the retained pass's
-            // fader EXILES (`static_gx::cull`, decision 1431): the feather-band respawns are
-            // recorded on their fader seed, not on the placement, and they name themselves.
+            // A placed part outside every placement's list outlived a respawn, except the retained
+            // pass's fader exiles (`static_gx::cull`), recorded on their fader seed instead.
             let exile = path_why.is_some_and(|w| w.0 == "exile");
             if let (Some(owned), Some(o), false) = (owned.as_ref(), object, exile) {
                 if matches!(o.kind, ModelKind::Doodad | ModelKind::Wmo) && !owned.contains(&entity)
@@ -260,9 +192,7 @@ impl WorldCensus<'_, '_> {
             *why.entry(path_why.map_or("-", |w| w.0)).or_default() += 1;
             drawn += usize::from(vis.get());
             if gated {
-                // The camera's own placement is not exterior scene to itself (decision 0784) and
-                // is *supposed* to draw; without that subtraction the escapee list is all
-                // room-you-are-in furniture and says nothing.
+                // The camera's own placement is supposed to draw, so it is not an escapee.
                 let exempt = group.is_some_and(|g| Some(g.instance) == own_instance);
                 tagged += 1;
                 hidden += usize::from(*want == Visibility::Hidden);
@@ -373,10 +303,8 @@ impl WorldCensus<'_, '_> {
         }
     }
 
-    /// Every resident image/mesh/model by asset-server path, sorted, plus the counts that have no
-    /// path (runtime-built) in that same order. Diffing a tour probe's inventory against a fresh
-    /// control's names exactly which files a teardown left behind — the leak meter's magnifying
-    /// glass, and the one census answer expensive enough to ask for separately.
+    /// Every resident image, mesh and model by asset path, sorted, plus the unpathed
+    /// (runtime-built) counts in that order; apart from [`Self::take`] because it is expensive.
     pub fn resident_assets(&self) -> (Vec<String>, [usize; 3]) {
         let mut lines: Vec<String> = Vec::new();
         let mut unpathed = [0usize; 3];
@@ -407,7 +335,6 @@ impl WorldCensus<'_, '_> {
     }
 }
 
-/// What the census reads off every model submesh — the query shape.
 type CensusData = (
     Entity,
     &'static ViewVisibility,
@@ -422,11 +349,11 @@ type CensusData = (
     Option<&'static bevy::camera::visibility::VisibilityClass>,
 );
 
-/// The census column order, pinned: entry `i` names [`kind_index`]'s slot `i`. Column positions
-/// in a line other tools diff, so they move for nobody.
+/// The census column order: entry `i` names [`kind_index`]'s slot `i`. Other tools diff these
+/// columns, so the order is fixed.
 const KIND_COLUMNS: [&str; 4] = ["doodad", "wmo", "creature", "gameobject"];
 
-/// [`ModelKind`] has a private index; the census pins its own — see [`KIND_COLUMNS`].
+/// The census's own index for a [`ModelKind`], pinned to [`KIND_COLUMNS`].
 fn kind_index(kind: ModelKind) -> usize {
     match kind {
         ModelKind::Doodad => 0,
@@ -436,15 +363,13 @@ fn kind_index(kind: ModelKind) -> usize {
     }
 }
 
-/// `AssetEvent::Modified` counts per asset type across a window. A modified material re-creates
-/// its uniform buffers + bind group that frame (the Metal non-bindless path), and a modified
-/// image/mesh re-uploads — the teleport leak's CPU engine was exactly a per-frame ratchet of this
-/// shape, so the floor hunt names the types instead of guessing suspects one at a time.
+/// `AssetEvent::Modified` counts per asset type across a window: a modified material rebuilds its
+/// uniform buffers and bind group that frame (non-bindless), a modified image or mesh re-uploads.
 #[derive(Resource, Default)]
 struct ChurnCensus(std::collections::BTreeMap<&'static str, usize>);
 
-/// One census counter for asset type `A`, folding this frame's `Modified` events in under `label`
-/// (a short stable name — the `type_name` of an `ExtendedMaterial` alias is unreadable).
+/// Counts asset type `A`'s `Modified` events under `label`, a short stable name (an
+/// `ExtendedMaterial` alias's `type_name` is unreadable).
 fn churn_counter<A: bevy::asset::Asset>(
     label: &'static str,
 ) -> impl FnMut(MessageReader<bevy::asset::AssetEvent<A>>, ResMut<ChurnCensus>) {
diff --git a/crates/benilla-world/src/world_map.rs b/crates/benilla-world/src/world_map.rs
index 208e8ce4..76c9c776 100644
--- a/crates/benilla-world/src/world_map.rs
+++ b/crates/benilla-world/src/world_map.rs
@@ -1,10 +1,5 @@
-//! World-map state: the `Map.dbc` catalog + the current `mapId`, shared by every subsystem that keys
-//! off "which map are we on" — the terrain and WDL streamers, the loading screen, and time-of-day
-//! lighting.
-//!
-//! These were historically defined inside the terrain streamer, but they're world state, not
-//! streamer-private: four other subsystems reach for them. They live here so any of them — and either
-//! terrain streamer, old or new — can read them without depending on the terrain streamer's setup.
+//! World-map state: the `Map.dbc` catalog and the current map id, for every subsystem that keys
+//! off the map (the terrain and WDL streamers, the loading screen, time-of-day lighting).
 
 use benilla_assets::MapCatalogRes;
 use benilla_formats::load_map_catalog;
@@ -13,18 +8,11 @@ use bevy::prelude::*;
 use benilla_assets::LockRecover;
 use benilla_assets::{AssetSet, WorldAssets};
 
-/// Default `mapId` (Eastern Kingdoms / Azeroth) — terrain is set up here before the world stream
-/// arrives and tells us the character's real map. A worldport then bumps [`CurrentMap`].
+/// The map before the server names one: Eastern Kingdoms (`Map.dbc` id 0).
 pub(crate) const DEFAULT_MAP_ID: u32 = 0;
 
-/// `$WOW_MAP` — the map a **server-less** run starts on, as a `Map.dbc` id (`0` = Azeroth,
-/// `1` = Kalimdor). Unset gives [`DEFAULT_MAP_ID`].
-///
-/// **Set-but-unparseable is a hard error, deliberately.** This used to fall back to Azeroth, so
-/// `WOW_MAP=Kalimdor` silently photographed the wrong continent — the capture came back as empty
-/// ocean with the subject floating in it, which reads as a renderer bug and costs a session the
-/// time to chase one. An instrument that answers the wrong question quietly is worse than one that
-/// refuses.
+/// `$WOW_MAP`: the `Map.dbc` id a server-less run starts on (`0` Azeroth, `1` Kalimdor), unset
+/// giving [`DEFAULT_MAP_ID`]. A value that does not parse panics rather than falling back.
 fn map_id_from_env() -> u32 {
     match std::env::var("WOW_MAP") {
         Err(_) => DEFAULT_MAP_ID,
@@ -34,30 +22,21 @@ fn map_id_from_env() -> u32 {
     }
 }
 
-/// The map the player is currently on. Written by `player::control` when it drains the world stream's
-/// worldport; watched by the terrain + WDL streamers (reload ADTs/WDL for the new map), the loading
-/// screen (cover the swap), and time-of-day lighting (per-map outdoor light).
+/// The map the player is on, rewritten by the game on every worldport, login's included.
 #[derive(Resource, Clone, Copy)]
 pub struct CurrentMap(pub u32);
 
-/// A cross-map transition, observed as a [`CurrentMap`] flip — the **world-scope teardown
-/// signal**. Every module that dedups map-scoped assets behind a strong-handle cache reads this
-/// and clears its own cache (the #bugs teleport leak: those caches pinned every map ever visited,
-/// and each retained uv/tint-animated material re-uploaded per frame, forever). A clear is always
-/// safe mid-session — live users hold handle clones, so it only drops the *dedup*; the assets die
-/// when their last user despawns, and the next spawn rebuilds under the loading screen. Carries
-/// no payload: every evictor clears unconditionally, and [`announce_map_change`] logs the
-/// transition itself.
+/// A cross-map transition, the world-scope teardown signal: every map-scoped strong-handle cache
+/// clears on it, since one that kept its handles would pin every map visited. A clear is safe
+/// mid-session, as live users hold their own handles.
 #[derive(Message, Clone, Copy)]
 pub struct MapChange;
 
-/// Startup set the world-map catalog loads in, so the terrain/WDL streamers can order their own setup
-/// after it (they read [`MapCatalogRes`]/[`CurrentMap`] the moment they initialize).
+/// The startup set the map catalog loads in, which the streamers' setup runs after.
 #[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub(crate) struct WorldMapLoad;
 
-/// Loads `Map.dbc` into [`MapCatalogRes`] and seeds [`CurrentMap`] at startup (after the patch chain
-/// opens), before any map-keyed subsystem sets up.
+/// Loads `Map.dbc` and seeds [`CurrentMap`] at startup, after the patch chain opens.
 pub(crate) struct WorldMapPlugin;
 
 impl Plugin for WorldMapPlugin {
@@ -70,10 +49,8 @@ impl Plugin for WorldMapPlugin {
     }
 }
 
-/// Announce every [`CurrentMap`] flip as a [`MapChange`]. The `Local` holds the last *announced*
-/// map, so the startup seed (the first observation) announces nothing — there is no old map to
-/// tear down. Watching the resource rather than the worldport wire keeps one definition of
-/// "the map changed", and a same-map worldport (an instance re-enter) correctly stays silent.
+/// Announce every [`CurrentMap`] flip as a [`MapChange`]; the startup seed and a same-map
+/// worldport announce nothing.
 fn announce_map_change(
     map: Option<Res<CurrentMap>>,
     mut last: Local<Option<u32>>,
@@ -91,7 +68,7 @@ fn announce_map_change(
     }
 }
 
-/// Read `Map.dbc` off the shared patch chain into [`MapCatalogRes`] and seed [`CurrentMap`].
+/// Read `Map.dbc` off the patch chain into [`MapCatalogRes`] and seed [`CurrentMap`].
 fn load_world_map(mut commands: Commands, world_assets: Option<Res<WorldAssets>>) {
     let Some(world_assets) = world_assets else {
         return;
@@ -101,15 +78,8 @@ fn load_world_map(mut commands: Commands, world_assets: Option<Res<WorldAssets>>
         Ok(c) => {
             info!("Map.dbc: {} maps catalogued", c.len());
             commands.insert_resource(MapCatalogRes(c));
-            // `$WOW_MAP` seeds a different continent for a SERVER-LESS run (a `WOW_CAPTURE=vista`
-            // shot in Kalimdor, say — a `Map.dbc` id; 1 = Kalimdor). Live sessions are unaffected:
-            // `player::wire_in` overwrites this from the server's world-verify the moment it says
-            // where we are. Without it every headless capture is stuck in Eastern Kingdoms, and a
-            // horizon report from anywhere else cannot be reproduced.
-            //
-            // A named capture scenario carries its own map (`capture::scenarios::Scenario::map`)
-            // and writes it here before this runs, so the golden sweep's Kalimdor shots need no env
-            // at all — see `capture::CapturePlugin::build` (decision 0743).
+            // `$WOW_MAP` picks a server-less run's map (a named capture scenario sets it before
+            // `Startup`); a live session's `player::wire_in` overwrites it from the server.
             let map = map_id_from_env();
             commands.insert_resource(CurrentMap(map));
         }
diff --git a/crates/benilla-world/src/world_plugins.rs b/crates/benilla-world/src/world_plugins.rs
index 4ba16db0..05a1fb5a 100644
--- a/crates/benilla-world/src/world_plugins.rs
+++ b/crates/benilla-world/src/world_plugins.rs
@@ -1,34 +1,5 @@
-//! **[`WorldPlugins`] — the engine, as one name.**
-//!
-//! Decision 1160 splits the world renderer out of `benilla-app`; 1164 counted what a second
-//! program has to name to use it and found **31 of the 214 items were plugin registrations** — one
-//! per engine module, every one named by the composition root and by nothing else. That is not an
-//! API, it is an assembly manual, and it made the engine's doorway look five times wider than the
-//! engine's actual vocabulary. Published as a group, the whole set is one item and the members go
-//! back to being internals.
-//!
-//! **The order below is load-bearing and is the client's own**, so the two binaries stay diffable
-//! (it was `worldview::engine`, "the cut line written down", before it was this). Two edges inside
-//! it are documented dependencies rather than taste: `SkyboxPlugin` registers after `SkyPlugin`,
-//! whose dome it stands down, and `PerfPlugin` after the debug panel, whose egui context it
-//! needs (both instruments, and both the client's to add in that order now). `ArtScopePlugin` before `AssetPlugin` is *not* one — its own comment says so — but it
-//! costs nothing to keep.
-//!
-//! **What is deliberately NOT here.** `pipe_warm` looks engine-adjacent and is not: the viewer
-//! disproved it by running, grinding 1051 ms main-thread hitches warming the *game's* pipeline set
-//! (nameplates, blob shadows, the UI quad lane, the portrait booths) for a frame that would never
-//! be drawn. It is a client instrument and stays with the client.
-//!
-//! `debug_panel`, `perf` and the particle census are **not** here either, and the reason they once
-//! had to be is worth keeping: the panel was the model-`Visibility` authority (the WMO portal PVS
-//! is applied through it, decisions 0025/0031), so the world did not draw without it. That
-//! authority is `model_render`'s now and the toggles it reads are `dev_state`'s, so the panel is an
-//! instrument again — which is what 1160 wanted, instruments at the top of the stack rather than
-//! the bottom. `art_scope` stays: within-map art residency is engine behaviour, not a readout, and
-//! a viewer that never evicts is a viewer that measures the wrong thing.
-//!
-//! This is what makes `benilla-worldview` mean something. With the instruments out, the viewer is
-//! the engine and nothing else, and every gameplay resource it still needs shows up as a stub.
+//! [`WorldPlugins`]: the world engine as one plugin group, instruments left to the program. The
+//! order is the client's own, so the client and `benilla-worldview` stay diffable.
 
 use avian3d::prelude::*;
 use bevy::app::PluginGroupBuilder;
@@ -36,66 +7,32 @@ use bevy::prelude::*;
 
 use benilla_assets::materials::{TerrainMaterial, WowModelMaterial};
 
-/// Everything `benilla-world` will own, in one group. One `add_plugins(WorldPlugins)` installs the
-/// engine; nothing in it may reach for a server, a player, or a UI.
+/// The engine in one group; nothing in it may reach for a server, a player or a UI.
 pub struct WorldPlugins;
 
 impl PluginGroup for WorldPlugins {
     fn build(self) -> PluginGroupBuilder {
         PluginGroupBuilder::start::<Self>()
-            // The engine's own WGSL, compiled into the binary (decision 1175). First in the group
-            // because every material below specializes against a shader handle, and a shader that
-            // was never registered fails silently — as a whole world drawn with nothing on it.
+            // The engine's WGSL first: every material below specializes against it, and an
+            // unregistered shader fails silently.
             .add(crate::shaders::plugin)
             .add(MaterialPlugin::<TerrainMaterial>::default())
             .add(MaterialPlugin::<WowModelMaterial>::default())
-            // Physics (avian3d): collider storage + collider BVH + shape-casts for the character
-            // controller (decision 0009). The streamed terrain/placement entities carry
-            // `Collider`s; the player drives `MoveAndSlide` against them. No character controller
-            // rides them in the viewer, but the ray-caster and the shape queries do.
+            // Physics (avian3d): colliders, their BVH and the shape-casts of controller and picker.
             .add_group(PhysicsPlugins::default())
-            // ...but NOT the contact pipeline. Nothing in this workspace reads a contact:
-            // `CollisionStart`, `CollisionEnd`, `ContactPair` and `Collisions` have zero
-            // consumers, because the player is a shape-cast controller and units carry no
-            // colliders at all. The broad phase is the only thing that *creates* contact pairs,
-            // so disabling it leaves the narrow phase and the solver iterating an empty
-            // `ContactGraph` — every resource still exists (`BroadPhaseCorePlugin` owns
-            // `ContactGraph`/`JointGraph`), and the collider BVH the shape-casts actually ride
-            // is `ColliderTreePlugin`'s, untouched.
-            //
-            // This is not a micro-optimisation. Pairs were still generated for every
-            // kinematic-or-standalone collider overlapping the static world, and each one cost a
-            // parry `contact_manifolds_composite_shape_composite_shape` — trimesh vs trimesh,
-            // against 65k-triangle terrain tiles — recomputed every physics tick, and Bevy's
-            // fixed-timestep catch-up runs up to 16 ticks in one frame (`Time<Virtual>`'s stock
-            // 250 ms `max_delta`). Four stall captures across three sessions caught the main
-            // thread inside `update_narrow_phase` for 12–41% of their samples; the run that
-            // prompted this stalled >600 ms three times in five minutes. Decision 1232.
+            // No contact pipeline: nothing reads a contact (the player is a shape-cast controller,
+            // units carry no colliders), and trimesh pairs against terrain tiles cost whole ticks.
+            // The collider BVH the shape-casts ride is `ColliderTreePlugin`'s, kept.
             .disable::<BvhBroadPhasePlugin>()
-            // …and NOT the dynamics pipeline either (decision 1445 — stage 2 of the same diet,
-            // on the same recorded premise as `SubstepCount(1)` below: the world has ZERO
-            // `RigidBody::Dynamic` bodies, zero joints, zero velocity/force consumers — verified
-            // by grep across the workspace, only Static colliders and Kinematic transports that
-            // write their `Position` directly). With no contacts (broad phase off) and no
-            // dynamic bodies, the solver bodies, the integrators, the xpbd joint solver, CCD,
-            // islands/sleeping, the joint graphs, mass-property upkeep, the narrow phase's
-            // empty-graph iteration and the render-side interpolation (zero
-            // `TransformInterpolation` users; transports tick in `Update` at render rate) were
-            // pure fixed-tick schedule overhead — ~60% of a parked frame's physics share on the
-            // 1445 trace. What stays is exactly what benilla consumes: the collider storage +
-            // backend, the collider BVH (`ColliderTreePlugin`) and spatial queries the
-            // controller/pick shape-casts ride, collider transform propagation, and the
-            // Transform↔Position sync. Revisit the moment a dynamic body enters the world —
-            // the `SubstepCount` note below is the standing tripwire.
+            // No dynamics either: the world has no dynamic bodies, joints or force consumers, only
+            // static colliders and kinematic transports that write `Position` directly, and no
+            // `TransformInterpolation` user. Re-enable when a dynamic body enters the world.
             .disable::<ForcePlugin>()
             .disable::<MassPropertyPlugin>()
             .disable::<NarrowPhasePlugin<Collider>>()
             .disable::<JointPlugin>()
             .disable::<PhysicsInterpolationPlugin>()
-            // `SolverSchedulePlugin` deliberately STAYS: it owns the `PhysicsSchedule`'s
-            // step-set scaffolding (the chain every kept system's `in_set` ordering hangs off —
-            // removing it left the collider-tree systems floating and tripped the ambiguity
-            // gate), plus the substep runner, which now runs a near-empty schedule.
+            // `SolverSchedulePlugin` stays: it owns the step sets every kept system orders on.
             .disable::<SolverBodyPlugin>()
             .disable::<IntegratorPlugin>()
             .disable::<SolverPlugin>()
@@ -109,225 +46,138 @@ impl PluginGroup for WorldPlugins {
             .disable::<avian3d::dynamics::solver::joint_graph::JointGraphPlugin<DistanceJoint>>()
             .disable::<avian3d::dynamics::solver::joint_graph::JointGraphPlugin<SphericalJoint>>()
             .add(WorldFoundation)
-            // The per-frame world-transition ordering (Input → Stream → Present) the loading
-            // screen relies on to cover a teleport the same frame it happens. See `schedule.rs`.
+            // The per-frame transition order (Input → Stream → Present) by which the loading
+            // screen covers a teleport the frame it happens.
             .add(crate::schedule::SchedulePlugin)
-            // World-interaction foundation: mouseover picking + object identity (the debug
-            // inspector reads it now; hover tooltips / contextual cursor / targeting will later).
+            // Mouseover picking and object identity.
             .add(crate::interact::InteractPlugin)
-            // M2 billboard cards (glow halos, chains) — faced to the camera each frame.
+            // M2 billboard cards (glow halos, chains), faced to the camera each frame.
             .add(crate::billboard::BillboardPlugin)
-            // The owned skin palette (decision 0720): every skinned rig's joint matrices, computed
-            // by us and skinned in wow_model.wgsl — Bevy's SkinnedMesh lane is fully replaced.
-            // The ground-fx decal lane (1164: 326 lines of pure render that had been
-            // filed in the app). Its ordering rides the billboard place set, which is why the
-            // lane registers itself rather than asking a caller to know that.
+            // The ground-fx decal lane, which orders itself on the billboard place set.
             .add(crate::ground_fx::plugin)
             .add(crate::frame_pace::plugin)
+            // The skin palette: every rig's joint matrices, skinned in `wow_model.wgsl` in place of
+            // Bevy's `SkinnedMesh`.
             .add(crate::rig_palette::plugin)
-            // The rig machinery beside the palette it fills: the pose evaluator, the pose
-            // post-pass window, the world/palette composition, and the global-sequence channels.
-            // Split out of `creature_anim` (1163's re-check of `finalize_rig_worlds`) — the game
-            // still decides which clip plays; posing and composing are the world's.
+            // The rig machinery the palette reads: pose evaluation, composition and the global
+            // sequences; the game decides which clip plays.
             .add(crate::rig_anim::plugin)
-            // The per-instance body tint (decision 0812), on the same slot index as that palette:
-            // the aura state kit's CharProc-1 colour, in its own region of the shared light buffer.
+            // The per-instance body tint (a state kit's CharProc-1 colour), on the palette's slot.
             .add(crate::instance_tint::plugin)
-            // The mat-anim delta table (decision 1381), one region over: the per-frame samples of
-            // every UV/tint-animated batch material, so animating a waterfall never mutates its
-            // material asset again.
+            // The mat-anim table: each frame's UV and tint samples, so no material is mutated.
             .add(crate::mat_anim_table::plugin)
-            // The M2 render lane's three own plugins (decision 1163, stage zero). All three used to
-            // be registered by `EntitiesPlugin` — the entity streamer — which is why booting the
-            // engine without the game left the model-`Visibility` authority reading a
-            // `FarSideTwins` that nobody had created. Nothing in them is about streamed entities:
-            // it is the render-alpha channel, the water-plane far-side twins, and the depth-prime
-            // twins, all of which a terrain doodad needs exactly as much as an NPC does.
+            // The M2 render lane: render alpha, water far-side twins and depth-prime twins.
             .add(crate::model_fade::plugin)
             .add(crate::model_render::plugin)
             .add(crate::zfill::plugin)
-            // The straddle split (decision 2188): a translucent model crossing its water plane draws
-            // on both sides of the water pass, each half clipped at the waterline — the band
-            // verdict, the per-slot clip region and the far-side twins, beside the two lanes
-            // (water-side twins, depth primes) it composes with.
+            // The straddle split, beside the two lanes it composes with.
             .add(crate::straddle::plugin)
-            // Within-map art residency (decision 0793): the dedup caches expire by DISTANCE, so a
-            // long flight inside one map stops ratcheting. Before `AssetPlugin` only so the census
-            // resource exists for anything that reads it at startup; it needs no ordering.
+            // Within-map art residency: the dedup caches expire by distance.
             .add(crate::art_scope::ArtScopePlugin)
-            // Foundation: opens the patch chain + inserts WorldAssets/RenderConfig
-            // (`AssetSet::Open`), which every other subsystem's startup runs after.
+            // Opens the patch chain (`AssetSet::Open`), which every other startup runs after.
             .add(crate::assets::AssetPlugin)
-            // World-map state (Map.dbc catalog + CurrentMap), loaded right after the chain opens —
-            // the terrain/WDL streamers, loading screen, and lighting all key off it.
+            // Map.dbc and the current map, keyed off by the streamers, loading screen and lighting.
             .add(crate::world_map::WorldMapPlugin)
-            // Time-of-day lighting: sun + WoW shader colors, sky background, per-frame
-            // update→apply.
             .add(crate::lighting::LightingPlugin)
-            // Sky dome: the Light.dbc gradient backdrop (camera-centred), driven by that lighting.
+            // Sky dome: the Light.dbc gradient backdrop (camera-centred), driven by the lighting.
             .add(crate::sky::SkyPlugin)
-            // WMO skybox: the authored sky a building's `0x40000` group swaps in for that gradient
-            // (Stratholme's burning city) — registered after SkyPlugin, whose dome it stands down.
+            // The WMO skybox, after `SkyPlugin`, whose dome it stands down.
             .add(crate::skybox::SkyboxPlugin)
-            // Cloud coverage: the reference's procedural field — glare occlusion (occ1) + the
-            // visible layer.
+            // Clouds: the reference's procedural field, glare occlusion and the visible layer.
             .add(crate::clouds::CloudsPlugin)
-            // Weather: the SMSG_WEATHER state machine driving the storm light-blend +
-            // precipitation (decision 0310). Lighting reads its densities `.after(WeatherTick)`.
+            // Weather (`SMSG_WEATHER`): the storm light blend and precipitation.
             .add(crate::weather::WeatherPlugin)
-            // Sun disc + glow halo: the celestial sprites WoW draws at the sun (RE'd from
-            // CSky::Render).
+            // The sun disc and glow halo (`CSky::Render`).
             .add(crate::sun::SunPlugin)
-            // Interior lighting classifier: lights M2 entities (GameObjects/NPCs/other players)
-            // standing inside a WMO room off the baked floor colour, day/night-independent (the
-            // streamer fills its volume registry).
+            // The interior classifier: M2 entities in a WMO room lit off its baked floor colour.
             .add(crate::interior::InteriorPlugin)
             .add(crate::entity_shade::EntityShadePlugin)
-            // The world camera's pose, published before the `Update`-stage viewer authorities
-            // below read it (decision 1503) — without it they answer about where the camera was
-            // last frame, which on a teleport frame is the place we just left.
+            // The world camera's pose, published before the viewer authorities below read it.
             .add(crate::view::ViewPlugin)
-            // WMO portal visibility: per-frame, decides which of a building's groups are reachable
-            // through portals from the camera's group, so the Stormwind cathedral culls from the
-            // Trade District. Only computes the PVS; the `Visibility` authority
-            // (`model_render::visibility`) applies it (decisions 0025/0031).
+            // The WMO portal PVS: groups reachable from the camera's, applied by `model_render`.
             .add(crate::wmo_portal::WmoPortalPlugin)
-            // The exterior scene draws only through portal windows the flood left behind (decision
-            // 0774): from inside a building, terrain and ADT doodads are gated on the deferred
-            // window worklist.
+            // From inside a building, the exterior draws only through the flood's portal windows.
             .add(crate::exterior_cull::ExteriorCullPlugin)
-            // Doodad animation (decision 0130): placed M2s loop their first sequence + global
-            // sequences, gated to drawn instances.
+            // Doodad animation: placed M2s loop their first and global sequences while drawn.
             .add(crate::doodad_anim::DoodadAnimPlugin)
-            // Ground clutter: the GroundEffect catalog + the lazy per-chunk build lifecycle, owned
-            // independently of the terrain streamer (so the streamer can be swapped). Whichever
-            // streamer is active scatters into the ClutterChunks this builds.
+            // Ground clutter: the catalog and per-chunk build; the active streamer scatters.
             .add(crate::clutter::ClutterPlugin)
             // Distant low-detail terrain (WDL): the fogged horizon hills beyond the streamed tiles.
             .add(crate::wdl::WdlPlugin)
             // Liquid: animated lake/river/ocean water surfaces (MCLQ), spawned with their tile.
             .add(crate::liquid::LiquidPlugin)
-            // Particle emitters: the additive flames/glows of campfires, torches, braziers
-            // (decision 0014).
             .add(crate::particles::ParticlePlugin)
-            // Water foam decals (CWater0Ripple wake/ring/step-in splash) — the record model,
-            // rebuilt from the byte RE + two reference-trace reconstructions (decision 0264).
+            // Water foam decals (`CWater0Ripple`): wake, ring and step-in splash.
             .add(crate::water_fx::WaterFxPlugin)
             .add(crate::ffx_glow::FfxGlowPlugin)
             .add(crate::ribbons::RibbonPlugin)
             // Stuck-modifier reconciliation: macOS system shortcuts (⇧⌘5) swallow modifier
-            // releases without a focus loss, wedging every bare-key binding (decision 0606).
+            // releases without a focus loss, wedging every bare-key binding.
             .add(crate::modkeys::ModKeysPlugin)
-            // Terrain streaming: the benilla-assets `AdtTile` pipeline — streams tiles around the
-            // viewer through the `AssetServer`, owning the terrain mesh/material/collision,
-            // doodads/WMOs, liquid, clutter, and loading-screen residency. Last, as in both
-            // binaries before this group existed.
+            // Terrain streaming (`AdtTile` through the `AssetServer`): tiles with their doodads,
+            // WMOs, liquid and clutter.
             .add(crate::terrain_stream::TerrainPlugin)
     }
 }
 
-/// The engine's bare settings — the two avian tunings, the view distance, the dev state. A plugin only
-/// because a [`PluginGroup`] holds plugins and these are `insert_resource` calls; it sits where the
-/// client and the viewer both had them, immediately after `PhysicsPlugins`, because
-/// [`SubstepCount`] overwrites avian's own default and must therefore land after it.
+/// The engine's bare settings, after `PhysicsPlugins`: [`SubstepCount`] overwrites its default.
 struct WorldFoundation;
 
 impl Plugin for WorldFoundation {
     fn build(&self, app: &mut App) {
-        // One solver substep, not avian's 6: the world has NO dynamic bodies (static terrain,
-        // kinematic transports/attachments; the player is a shape-cast controller), so the substep
-        // loop's contact/joint solving iterates over nothing — and kinematic motion integrates
-        // exactly (constant velocity, no forces) at any substep count. Six substeps were pure
-        // fixed-tick schedule overhead (~10 substep-schedule runs per frame on the idle-floor
-        // ledger). Revisit if a dynamic body ever enters the world.
+        // One solver substep, not avian's 6: with no dynamic bodies, kinematic motion is exact at
+        // any count. Revisit when a dynamic body enters the world.
         app.insert_resource(SubstepCount(1))
-            // WoW gravity (19.29 yd/s², binary-derived — now a feel knob, not a fidelity target)
-            // replaces avian's 9.81 default.
+            // WoW's 19.29 yd/s² gravity for avian's 9.81; a feel knob, not a fidelity target.
             .insert_resource(Gravity(Vec3::NEG_Y * 19.291_105))
-            // The faithful view distance (`farclip`) — one source of truth for the wall + the
-            // per-object cull (and, post-split, the stream radius). See `view.rs`.
+            // The view distance (`farclip`), one source for the far wall and the per-object cull.
             .init_resource::<crate::view::ViewDistance>()
-            // The world camera's multisampling level (`gxMultisample`, decision 1629) — read
-            // ONCE, at the camera's spawn, because the reference's own flag says latched.
+            // `gxMultisample`, read once at the camera's spawn, as the reference latches it.
             .init_resource::<crate::view::MsaaSetting>()
             .init_resource::<crate::view::MsaaFormats>()
-            // The process texture filter policy (`trilinear` / `anisotropic`) — read ONCE, at the
-            // CVar load, for the same reason: a sampler is baked into an uploaded texture and the
-            // reference's own UI says "enabled upon restart".
+            // The texture filter (`trilinear`, `anisotropic`), read once at the CVar load: the
+            // reference applies it on restart.
             .init_resource::<benilla_assets::TexFilterSetting>()
-            // ...and the clamp that keeps it inside what this GPU will actually accept. Runs in
-            // plugin `finish()`, so it lands between the render adapter appearing and `Startup`
-            // reading the setting — see `view::MsaaSupportPlugin`.
+            // Its clamp to what this GPU accepts, in `finish()`, between the adapter and `Startup`.
             .add_plugins(crate::view::MsaaSupportPlugin)
-            // The viewer's body (wire (a)'s kinematics half) — defaulted by the engine so a
-            // program with no avatar leaves it empty and every reader takes its no-body branch.
+            // The viewer's body, empty in a program with no avatar.
             .init_resource::<crate::view::Viewer>()
-            // The dev state (decision 0026): the always-present config layer eight subsystems
-            // read, whose defaults ARE the player behaviour. The debug panel is only its editor
-            // and may not be installed at all.
+            // The dev state, whose defaults are the player's; the debug panel only edits it.
             .init_resource::<crate::dev_state::DebugState>()
             .add_systems(Last, crate::dev_state::count_still_inputs)
-            // The collider-set stamp every cached collision answer is dated against
-            // (`collision::ColliderEpoch`). Tracked in `First` so a removal is stamped before any
-            // consumer runs; the attach half is stamped by the streamer's own attach loop.
+            // The collider-set stamp cached collision answers are dated by; a removal is stamped in
+            // `First`, before any consumer.
             .init_resource::<crate::collision::ColliderEpoch>()
             .init_resource::<crate::collision::MoverTraceExclusions>()
             .add_systems(First, crate::collision::track_collider_removals);
-        // Avian's pre-step copy of Bevy's transform propagation is OFF by default (the 1370
-        // bracket surfaced the lane; the 3-round SW split then measured the skip at −0.40
-        // cpu_ms, negative in every round): `PhysicsTransformPlugin` re-registers
-        // `mark_dirty_trees`/`propagate_parent_transforms`/`sync_simple_transforms` to run
-        // before each physics step — a second whole-world transform sweep on top of
-        // PostUpdate's own. Our world is static geometry plus kinematic movers
-        // (`transport::tick_transports`) that mirror `Position`/`Rotation` directly — built
-        // that way precisely because the sync's own timing already lagged — so the pre-step
-        // sweep buys nothing. The one Transform-moved collider class left is an opening door
-        // (a GameObject's model-local hull riding its pose): it reaches physics one frame late
-        // via PostUpdate's own propagation — transient, bounded, imperceptible.
-        // `WOW_PHYS_PREPROP=1` restores avian's upstream default (the A/B lever back).
+        // No pre-step transform propagation: movers write `Position`/`Rotation` directly, so a
+        // second whole-world sweep buys nothing; an opening door's hull reaches physics a frame
+        // late. `WOW_PHYS_PREPROP=1` restores avian's default.
         if std::env::var_os("WOW_PHYS_PREPROP").is_none() {
             app.insert_resource(avian3d::physics_transform::PhysicsTransformConfig {
                 propagate_before_physics: false,
                 ..Default::default()
             });
         }
-        // `WOW_PHYS_HZ=<hz>` — run the fixed loop at a different rate. An EXPERIMENT lever
-        // (1370 item 10): avian's per-tick stack is the fixed loop's ONLY occupant (nothing
-        // first-party lives in any fixed schedule — zero-hit grep, re-verified at flip time),
-        // so 8 vs the default 64 prices the whole-avian bracket in one leg. A measurement
-        // lever, never a setting: at 8 Hz the spatial trees ingest streamed colliders up to
-        // 125 ms late, which the player's shape-cast controller would feel at a tile seam.
+        // `WOW_PHYS_HZ=<hz>`: the fixed loop's rate, a measurement lever and never a setting (at
+        // 8 Hz streamed colliders reach the spatial trees up to 125 ms late).
         if let Some(hz) = std::env::var("WOW_PHYS_HZ")
             .ok()
             .and_then(|v| v.parse::<f64>().ok())
         {
             app.insert_resource(bevy::time::Time::<bevy::time::Fixed>::from_hz(hz));
         }
-        // Static transform tracking is ALWAYS on — the adaptive default pays two serial
-        // full-population scans per frame (`mark_dirty_trees`'s `count()` calls; a `Changed`
-        // filter count degrades to full iteration) to decide whether >30% of the world moved
-        // this frame. Ours never has: movers are the streamed units, 1–3% of a world that is
-        // overwhelmingly static placements — the check can only ever conclude "track", so the
-        // two scans are its entire price. Pinned, not a knob: no scene benilla renders can be
-        // on the other side of the threshold.
+        // Static transform tracking always on: movers are 1–3% of the world, so the adaptive
+        // check's two full scans a frame could only ever conclude "track".
         app.insert_resource(bevy::transform::systems::StaticTransformOptimizations::enabled());
-        // The retained static-world pass — ON by default (1429–1434; `WOW_STATIC_GX=0`
-        // opts out; the module doc owns the design). Registers NOTHING when opted out —
-        // the divert sites see `None` for its resource and the render graph never gains
-        // the node.
+        // The retained static-world pass; `WOW_STATIC_GX=0` opts out, registering nothing.
         app.add_plugins(crate::static_gx::StaticGxPlugin);
-        // `WOW_MERGE_CENSUS=1` — the 1417 population census (module doc): tally rides the
-        // assembler, this is just the quiet-timer printer.
+        // `WOW_MERGE_CENSUS=1`: the merge census printer.
         if crate::static_merge::census_enabled() {
             app.add_systems(bevy::app::Update, crate::static_merge::log_merge_census);
         }
-        // `WOW_UPLOAD_BUDGET=<MB>` — cap the render app's per-frame GPU asset upload (bevy's
-        // `RenderAssetBytesPerFrame`, unlimited by default; only assets implementing `byte_len`
-        // participate, which covers meshes and images — exactly the streaming payload). An
-        // EXPERIMENT lever for the arrival burst: the LBRS arrival trace (2026-08-17) put the
-        // fat frames in drawable/render-schedule WAITS while streamed uploads land — every
-        // suspect system's own CPU was flat, avian's whole stack included — so pacing the
-        // uploads is the candidate fix, and this knob prices it before anything is redesigned.
+        // `WOW_UPLOAD_BUDGET=<MB>`: cap the per-frame GPU upload of meshes and images (bevy's
+        // `RenderAssetBytesPerFrame`, unlimited by default), a measurement lever.
         if let Some(mb) = std::env::var("WOW_UPLOAD_BUDGET")
             .ok()
             .and_then(|v| v.parse::<usize>().ok())
@@ -336,29 +186,10 @@ impl Plugin for WorldFoundation {
                 mb * 1024 * 1024,
             ));
         }
-        // Direct draws on EVERY camera — the default, not a knob (1374/1376). Bevy's indirect
-        // lane is a per-draw indirect encode loop on Metal (no MULTI_DRAW_INDIRECT) plus the GPU
-        // preprocessing dispatches, and the 1374 bracket priced it ~4.3 cpu_ms at LBRS on 0.18 —
-        // shipped unclaimed for the campaign's whole run because 1364's knob under-measured it
-        // (the UI Camera2d leak, 1370). `WOW_INDIRECT=1` restores the upstream default for
-        // re-pricing. 1370's note that the lever must cover every camera, not just the world's,
-        // is why this covers `Camera` itself rather than our own marker.
-        //
-        // **A REQUIRED COMPONENT, not a sweep** (decision 1488). 1374/1376 shipped this as an
-        // `Update` system that inserted the marker on any camera lacking it, and that is a latent
-        // GPU crash: bevy's own doc on `NoIndirectDrawing` says *"This component should only be
-        // added when initially spawning a camera. Adding or removing after spawn can result in
-        // unspecified behavior"*, and the unspecified behaviour is concrete —
-        // `get_or_create_work_item_buffer` latches Direct-vs-Indirect work-item buffers the FIRST
-        // time it sees a view (`Entry::Occupied` returns the existing one, forever), while the
-        // preprocessing node picks its pipeline from the LIVE `Has<NoIndirectDrawing>`. A camera
-        // extracted once before the sweep's deferred insert lands therefore keeps Indirect buffers
-        // under a direct pipeline for the rest of its life, and the next dispatch is a wgpu
-        // validation panic ("bind group … not compatible … Assigned entry with binding 7 not
-        // found"). Measured: the sweep was flagging 18 cameras late at startup and one 0.5 s in.
-        // `player::setup` already knew the rule for the world camera ("it must ride the SPAWN: the
-        // phase cache latches the preprocessing mode the first time it sees the view") — this
-        // gives every other camera the same guarantee, atomically, with no frame to lose.
+        // Direct draws on every camera: Bevy's indirect lane is a per-draw encode loop on Metal
+        // (no MULTI_DRAW_INDIRECT) plus GPU preprocessing; `WOW_INDIRECT=1` restores it. A
+        // required component, as `NoIndirectDrawing` must ride a camera's spawn: the work-item
+        // buffers latch the first time a view is seen, and a later insert panics in wgpu.
         if std::env::var_os("WOW_INDIRECT").is_none() {
             app.register_required_components::<bevy::camera::Camera, bevy::render::view::NoIndirectDrawing>();
         }
diff --git a/crates/benilla-world/src/world_point.rs b/crates/benilla-world/src/world_point.rs
index 4d44bf37..2fd637b5 100644
--- a/crates/benilla-world/src/world_point.rs
+++ b/crates/benilla-world/src/world_point.rs
@@ -1,28 +1,8 @@
-//! **[`WorldPoint`] — what is at this point, and where is this subject.**
-//!
-//! One read-only [`SystemParam`] answering the questions a caller asks *of the world* rather than
-//! of one of its subsystems: is there liquid here, how high is its surface, whose room does it
-//! belong to, what is the eye submerged in, where is the nearest water you can hear.
-//!
-//! Decision 1164 counted 23 engine items whose only reason for being public was that a gameplay
-//! system had to assemble this query by hand — four `Query`s, three `Res`es and six free functions
-//! threaded through each other in the right order, re-written at every call site. Assembling a
-//! query by hand is also how a call site gets it *wrong*: the "swim in air" family (0634 → 0696 →
-//! 0701) is three separate bugs whose common shape was a caller passing the wrong context, and
-//! every one of them had to be fixed at N call sites instead of one.
-//!
-//! **The subject is the parameter, and it is an [`Entity`] or a role — never an engine component.**
-//! Before this, a caller asking about a unit had to carry `Option<&UnitWmoRoom>` in its own query
-//! and hand it in; the room tracker's component was gameplay API purely because of that. Now the
-//! caller says *which unit*, and the world looks up its own bookkeeping. That is the difference
-//! between an API and a wiring diagram.
-//!
-//! **Deliberately not merged with tracing a body through the world** (1164 item 11, `WorldCollision`):
-//! `ground_normal_under` reads the physics trimesh and `terrain_height_under` reads the MCNK
-//! heightfield, and they answer different questions about "the ground" that are allowed to differ.
-//!
-//! Two precedents this generalises, one on each side of the line: `surface::SurfaceUnderfoot` and
-//! `sun::follow::FlareGate`.
+//! [`WorldPoint`]: what is at a point and where a subject is, asked of the world rather than of one
+//! subsystem: liquid and its surface height, whose room it is, what the eye is submerged in, the
+//! nearest audible water. The subject is an [`Entity`] or a role, never an engine component.
+//! `terrain_height_under` reads the MCNK heightfield, not the physics trimesh that
+//! `WorldCollision` traces, and the two may differ.
 
 use bevy::ecs::system::SystemParam;
 use bevy::prelude::*;
@@ -37,68 +17,45 @@ use crate::wmo_portal::{
     CameraInteriorClaim, CurrentAreaInterior, CurrentWmoInterior, PlayerWmoRoom, UnitWmoRoom,
 };
 
-/// Whose question it is — the liquid query's delegation + scope key (decisions 0634/0696/0701).
-///
-/// It is not decoration and it is not optional: inside a building only *that placement's* MLIQ
-/// answers, outdoors only the ADT's. A caller that cannot say who is asking is a caller that will
-/// read a lake through a ceiling.
+/// Whose question it is: inside a building only that placement's MLIQ answers, outdoors only the
+/// ADT's.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum Subject {
     /// The player's own body, from the interior down-ray `wmo_portal` runs each frame.
     Player,
-    /// The camera eye — the reference's `[0xc7b748]` branch in the environment probe `0x6809c0`.
-    /// A separate subject from the body on purpose: the two disagree whenever the camera is out of
-    /// the room the feet are in, and it is the *eye* that decides the submerged view.
+    /// The camera eye: the reference's `[0xc7b748]` branch of the environment probe `0x6809c0`.
+    /// It differs from the body when the camera is outside the feet's room, and decides the
+    /// submerged view.
     Eye,
-    /// A streamed unit, by entity. Its room is looked up here; the caller does not carry it.
+    /// A streamed unit; its room is looked up here.
     Unit(Entity),
 }
 
-/// The world, asked about a point. Every field is read-only and every writer of every one of them
-/// is engine-internal, so this can never conflict with a caller's own parameters.
+/// The world, asked about a point; read-only, so it never conflicts with a caller's parameters.
 #[derive(SystemParam)]
 pub struct WorldPoint<'w, 's> {
     liquids: Query<'w, 's, &'static WaterChunkInfo>,
-    /// The XY grid over the loaded surfaces ([`crate::liquid::WaterIndex`]): a point query walks
-    /// the handful of surfaces over that cell, not every loaded one. The verdict is identical to
-    /// the full walk by construction (a surface is registered in every cell its box overlaps —
-    /// spatial.rs), and it is what keeps the per-unit askers — the swim mark, the splash line,
-    /// the ground clamp, one each per moving creature per frame — off a 650-surface walk apiece
-    /// (decision 1979: ~0.35 ms of a raid's main thread was those three walks).
+    /// The XY grid over loaded surfaces: a point query walks only its cell's surfaces.
     index: Res<'w, crate::liquid::WaterIndex>,
-    /// Liquid surfaces that also carry a sound class — the ambient-loop scan's population.
+    /// Liquid surfaces that also carry a sound class: the ambient-loop scan's population.
     sound_sources: Query<'w, 's, (&'static LiquidSoundSource, &'static WaterChunkInfo)>,
-    /// The placed buildings a room's whole-group submersion override resolves against (1000).
+    /// The placed buildings a room's whole-group submersion override resolves against.
     placements: RoomPlacements<'w, 's>,
     player_room: Res<'w, PlayerWmoRoom>,
     eye_room: Res<'w, CameraInteriorClaim>,
     unit_rooms: Query<'w, 's, &'static UnitWmoRoom>,
     underwater: Res<'w, Underwater>,
-    /// What you are standing on — the terrain/WMO surface race (decision 1161). Folded in rather
-    /// than left beside: it is the same question about the same point, and 1164 named it this
-    /// facade's seed.
     surface: SurfaceUnderfoot<'w, 's>,
-    /// Where the player is, as the three answers that disagree on purpose: the finest MCNK area
-    /// (the client's own `GetAreaID`), the *render* interior claim, and the *zone-text* one.
+    /// Where the player is, as three answers that disagree on purpose: the finest MCNK area (the
+    /// client's own `GetAreaID`), the render-ray interior claim and the zone-text one.
     area: Res<'w, CurrentArea>,
     interior: Res<'w, CurrentWmoInterior>,
     area_interior: Res<'w, CurrentAreaInterior>,
     wmo_areas: Option<Res<'w, crate::wmo_portal::WmoAreas>>,
 }
 
-/// **Seed a headless `World` with everything [`WorldPoint`] needs to be constructible.**
-///
-/// [`WorldPoint`] is a facade over ten resources that the world plugins insert during startup, and a
-/// `RunSystemOnce` harness runs none of them — so a test that touches it fails not with an assertion
-/// but with `SystemParamValidationError { message: "Resource does not exist" }`, naming whichever
-/// field happens to be first. That error is the same whatever the test was about, which makes it a
-/// tax on every harness that ever reaches the world facade rather than a signal about any of them.
-///
-/// One call here is the whole of it, and it stays correct by construction: a resource added to
-/// [`WorldPoint`] is added here in the same edit, instead of being discovered by three unrelated
-/// test modules failing at once. The defaults are the empty world — no rooms claimed, no liquid, no
-/// area — which is what a geometry harness wants: it supplies the geometry it is about and nothing
-/// else answers.
+/// Seeds a headless `World` (a `RunSystemOnce` harness runs no startup plugins) with every resource
+/// [`WorldPoint`] needs, as the empty world; a resource added to [`WorldPoint`] is added here too.
 pub fn init_world_point_resources(world: &mut bevy::prelude::World) {
     world.init_resource::<crate::liquid::WaterIndex>();
     world.init_resource::<Underwater>();
@@ -113,18 +70,18 @@ pub fn init_world_point_resources(world: &mut bevy::prelude::World) {
     world.init_resource::<CurrentAreaInterior>();
 }
 
-/// The nearest wet point of one liquid sound class — see [`WorldPoint::nearest_liquid_per_class`].
+/// The nearest wet point of one liquid sound class ([`WorldPoint::nearest_liquid_per_class`]).
 pub struct NearestLiquid {
     /// Squared distance from the query point, in WoW yards.
     pub(crate) dist_sq: f32,
-    /// The wet point itself, WoW space — the slew target.
+    /// The wet point, WoW space: the slew target.
     pub point: [f32; 3],
     /// The surface's sound-class nibble (`class = n & 3`, `FluidSpeed = n & 0xc`).
     pub nibble: u8,
 }
 
 impl WorldPoint<'_, '_> {
-    /// Whose liquid answers for `who` — the query's context.
+    /// Whose liquid answers for `who`.
     pub fn claim(&self, who: Subject) -> LiquidClaim {
         match who {
             Subject::Player => player_claim(&self.player_room, &self.placements),
@@ -133,14 +90,7 @@ impl WorldPoint<'_, '_> {
         }
     }
 
-    /// Has the room tracker reached this subject yet?
-    ///
-    /// `false` only on a unit's very first frame. It matters because an unsettled claim admits
-    /// *both* liquid sources — the exact false positive 0696 removed — so a state a subject can
-    /// only ENTER (swimming) must wait for it, while a state it can LEAVE must not.
-    /// The loaded surfaces whose footprint box covers `wow`'s XY — the index's candidates,
-    /// resolved to their chunk infos (a surface despawned since the index's last maintenance
-    /// simply resolves to nothing).
+    /// The loaded surfaces whose box covers `wow`'s XY.
     fn over(&self, wow: [f32; 3]) -> impl Iterator<Item = &WaterChunkInfo> {
         self.index
             .over(wow[0], wow[1])
@@ -148,43 +98,37 @@ impl WorldPoint<'_, '_> {
             .filter_map(|&e| self.liquids.get(e).ok())
     }
 
+    /// Whether the room tracker has reached this subject (false only on a unit's first frame). An
+    /// unsettled claim admits both liquid sources, so a state a subject can only enter (swimming)
+    /// must wait for it; one it can leave must not.
     pub fn room_settled(&self, who: Subject) -> bool {
         self.claim(who) != LiquidClaim::Unknown
     }
 
-    /// The liquid at `wow` for this subject, nearest surface first, or `None` for dry.
-    ///
-    /// Every liquid, not only water: **you swim in lava and slime too** (0634).
+    /// The liquid at `wow` for this subject, nearest surface first, lava and slime included.
     pub fn liquid_at(&self, who: Subject, wow: [f32; 3]) -> Option<LiquidHit> {
         liquid_at(self.over(wow), wow, self.claim(who))
     }
 
-    /// The **water** surface height at `wow` for this subject — [`Self::liquid_at`] with the
-    /// fullbright kinds (magma, slime) filtered out, for the consumers that are specifically about
-    /// water: the splash, the wake foam, footstep depth.
+    /// The water surface height at `wow`: [`Self::liquid_at`] without magma and slime.
     pub fn water_surface_at(&self, who: Subject, wow: [f32; 3]) -> Option<f32> {
         water_surface_at(self.over(wow), wow, self.claim(who))
     }
 
-    /// Every loaded liquid footprint covering this XY, one human-readable line each — the body of
-    /// the `/liquid` chat instrument. Prints every candidate, not just the winner, so a surface
-    /// that should not be claiming is visible next to the one that should.
+    /// Every loaded liquid footprint over this XY, winner or not, for the `/liquid` command.
     pub fn describe_liquid_at(&self, who: Subject, wow: [f32; 3]) -> Vec<String> {
         describe_at(self.over(wow), wow, self.claim(who))
     }
 
-    /// What the camera eye is currently submerged in — **which liquid, not merely whether**. The
-    /// kind is load-bearing: water reads the zone's underwater slot, magma and slime read fixed
-    /// global rows (byte-verified `0x6d2371`).
+    /// Which liquid the camera eye is in: water reads the zone's underwater slot, magma and slime
+    /// fixed global rows (`0x6d2371`).
     pub fn submersion(&self) -> benilla_formats::Submersion {
         self.underwater.0
     }
 
-    /// The `TerrainType` id under a subject's feet — the `$FSD` footstep sound, the footprint
-    /// decal and the footstep spray all read this one value, and the reference keeps it as one
-    /// cached dword per unit for exactly that reason (`CGUnit+0xc60`). `pos` is Bevy space.
-    ///
-    /// `None` is the client's `−1` sentinel: **silent, and no print** — never "try the other leg".
+    /// The `TerrainType` id under a subject's feet, read by the `$FSD` sound, the footprint decal
+    /// and the spray alike; the reference caches one per unit (`CGUnit+0xc60`). `pos` is Bevy
+    /// space. `None` is the client's `-1`: silent, no print, no fallback to the other leg.
     pub fn terrain_type(
         &self,
         catalog: &benilla_formats::FootstepCatalog,
@@ -194,16 +138,14 @@ impl WorldPoint<'_, '_> {
         self.surface.terrain_type(catalog, self.unit_room(who), pos)
     }
 
-    /// Which WMO group a subject stands in, if a building owns its column — the number a
-    /// diagnostic prints to say *which leg answered*. `None` is the open world.
+    /// Which WMO group a subject stands in; `None` in the open world.
     pub fn room_group(&self, who: Subject) -> Option<u16> {
         self.unit_room(who)
             .and_then(UnitWmoRoom::room)
             .map(|r| r.group)
     }
 
-    /// The per-unit room component, for the two engine calls that still take one. Only `Unit`
-    /// subjects have one: the player's and the eye's rooms are resources of their own.
+    /// Only a `Unit` subject has a room component; the player's and the eye's are resources.
     fn unit_room(&self, who: Subject) -> Option<&UnitWmoRoom> {
         match who {
             Subject::Unit(e) => self.unit_rooms.get(e).ok(),
@@ -211,15 +153,13 @@ impl WorldPoint<'_, '_> {
         }
     }
 
-    /// The finest area the player stands in — the client's own `GetAreaID`, WMO-interior claim
-    /// included (decision 0232's leaf authority). `None` until the ground tile is resident, or
-    /// off-terrain.
+    /// The finest area the player stands in, the client's `GetAreaID` with the WMO-interior claim;
+    /// `None` until the ground tile is resident, or off-terrain.
     pub fn area(&self) -> Option<u32> {
         self.area.0
     }
 
-    /// The MCNK `areaId` under an arbitrary point (Bevy space) — the outdoor leg alone. Use
-    /// [`Self::area`] for the player, whose claim is richer.
+    /// The MCNK `areaId` under a point (Bevy space), outdoors only; see [`Self::area`].
     pub fn area_id_under(&self, pos: Vec3) -> Option<u32> {
         self.surface.area_id_under(pos)
     }
@@ -229,25 +169,21 @@ impl WorldPoint<'_, '_> {
         self.surface.terrain_height_under(pos)
     }
 
-    /// Is this point inside a building? The faces-only down-ray, raced against the terrain.
+    /// Whether this point is inside a building: the faces-only down-ray, raced against the terrain.
     pub fn indoors_at(&self, feet_world: Vec3) -> bool {
         self.surface.indoors_at(feet_world)
     }
 
-    /// The player's **render** interior claim — the `WMOAreaTable` join keys of the room the
-    /// down-ray puts them in, or `None` in the open world. Drives the interior audio resolver and
-    /// the minimap's indoor overlay.
+    /// The player's render interior claim: the `WMOAreaTable` join keys of the group the down-ray
+    /// under the character finds (under the camera when there is no body), or `None` in the open
+    /// world. The interior audio reads it.
     pub fn interior(&self) -> Option<crate::wmo_portal::WmoInteriorKeys> {
         self.interior.0
     }
 
-    /// The `WMOAreaTable` row of the room the eye is in — the interior's own identity: its
-    /// `AreaTable` id and its audio FKs (sound provider, ambience, zone music, entry fanfare).
-    /// `None` in the open world, or when the client data did not load.
-    ///
-    /// The resolve is a three-step fallback the engine owns (exact group row → whole-WMO default →
-    /// name-set-0), so a caller asks the world what room it is in and gets the room, not a catalog
-    /// and a lookup rule to re-implement.
+    /// The `WMOAreaTable` row of the player's room (its `AreaTable` id and audio keys), by
+    /// exact group row, then the whole-WMO default, then name set 0; `None` in the open world or
+    /// without client data.
     pub fn interior_row(&self) -> Option<benilla_formats::WmoArea> {
         let keys = self.interior()?;
         let areas = self.wmo_areas.as_ref()?;
@@ -256,14 +192,10 @@ impl WorldPoint<'_, '_> {
             .resolve(keys.wmo_id, keys.name_set, keys.group_area_id)
     }
 
-    /// The two **exact-key** `WMOAreaTable` rows the zone-text indoor naming reads (`0x67e670`
-    /// (d)/(d-ii)): the hit GROUP's row, which re-populates the subzone, and the WMO's default
-    /// (`−1`) row, which may override the zone. Returned with the claim's own keys, because the
-    /// naming law dedups on the hit group's identity.
-    ///
-    /// **Exact key, no name-set retry** — deliberately not [`Self::interior_row`]'s three-step
-    /// resolve. The audio identity wants the nearest row it can find; the zone text wants the row
-    /// the client would have found, and a fallback here invents a name the reference never shows.
+    /// The two exact-key `WMOAreaTable` rows zone-text naming reads (`0x67e670`): the hit group's,
+    /// which sets the subzone, and the WMO's default (`-1`) row, which may override the zone, with
+    /// the claim's keys for dedup. No name-set fallback, unlike [`Self::interior_row`]: the
+    /// reference names a room only by exact key.
     pub fn area_interior_rows(
         &self,
     ) -> Option<(
@@ -283,17 +215,16 @@ impl WorldPoint<'_, '_> {
         ))
     }
 
-    /// The player's **zone-text** interior claim, which is deliberately not the same question: a
-    /// doorway portal under the eye seeds the render flood without making you indoors
-    /// (wow-re `zonetext-indoor-bit.md`).
+    /// The player's zone-text interior claim: indoors comes from a down-ray under the player alone
+    /// (`0x6a87f0`), so a doorway portal under the eye does not count.
     pub fn area_interior(&self) -> Option<crate::wmo_portal::WmoInteriorKeys> {
         self.area_interior.0
     }
 
-    /// The nearest wet point to `wow` within `radius`, one per liquid **sound class**, indexed by
-    /// class (`nibble & 3`) — the scan behind the ambient liquid loops (`0x462b50`'s
-    /// `nearest_liquid` walk). The class split and the AABB-clamp nearest point are the world's;
-    /// the priority order, the voice cap and the slew are the sound system's.
+    /// The nearest wet point to `wow` within `radius` for each liquid sound class (`nibble & 3`),
+    /// the scan behind the ambient liquid loops (reference: `0x6723f0` → `0x68af10` →
+    /// `0x68b0d0`). The class split and the AABB-clamped nearest point are the world's; priority,
+    /// the voice cap and the slew are the sound system's.
     pub fn nearest_liquid_per_class(
         &self,
         wow: [f32; 3],
@@ -326,12 +257,6 @@ mod tests {
     use crate::wmo_portal::WmoRoom;
     use bevy::ecs::system::RunSystemOnce;
 
-    /// **The one semantic change this facade makes**, pinned: a caller used to fetch
-    /// `Option<&UnitWmoRoom>` in its own query and hand it in; now it names the unit and the world
-    /// looks the room up. Those must be the same answer, including the two `None` cases — a unit
-    /// the room tracker has not reached, and an entity that is not a unit at all. Getting this
-    /// wrong is silent: every consumer would simply read the open world's liquid indoors, which is
-    /// the "swim in air" family (0634/0696/0701) coming back through the front door.
     #[test]
     fn a_unit_subject_resolves_to_that_units_own_room() {
         let mut world = World::new();
@@ -352,8 +277,7 @@ mod tests {
                 assert_eq!(point.room_group(Subject::Unit(indoors)), Some(7));
                 assert_eq!(point.room_group(Subject::Unit(outdoors)), None);
                 assert_eq!(point.room_group(Subject::Unit(untracked)), None);
-                // The player and the eye are resources, never a unit's component — asking them for
-                // a *unit's* room must not silently answer with somebody else's.
+                // The player's and the eye's rooms are resources, never a unit's component.
                 assert_eq!(point.room_group(Subject::Player), None);
                 assert_eq!(point.room_group(Subject::Eye), None);
             })
diff --git a/crates/benilla-world/src/world_unit.rs b/crates/benilla-world/src/world_unit.rs
index c980d48b..641f1ed4 100644
--- a/crates/benilla-world/src/world_unit.rs
+++ b/crates/benilla-world/src/world_unit.rs
@@ -1,95 +1,35 @@
-//! **A body standing in the world** — what the engine needs to know about a unit, and nothing
-//! about where it came from.
+//! A body standing in the world: what the engine needs to know about a unit, and nothing about
+//! where it came from. The game puts [`WorldUnit`] on every unit and [`ViewerUnit`] on the one the
+//! eye belongs to.
 //!
-//! Five engine lanes filtered on `net::NetEntity` and `net::SelfPlayer` to mean "a streamed unit"
-//! and "the viewer's own", and one of them also read the wire record's scale and the game's
-//! collision-height component. None of that is wire knowledge: the fade resolver wants to know
-//! which root is the avatar so first person can feather it, the shade sampler wants the same, the
-//! room tracker wants every body that can be inside a building, the palette census wants to label
-//! its lanes, and the foam emitter wants a cylinder with a radius. A world renderer cannot depend
-//! on a protocol crate's entity record to answer any of them.
-//!
-//! So the game states it. [`WorldUnit`] on every unit entity, [`ViewerUnit`] on the one the eye
-//! belongs to — both written by whatever spawns bodies, both meaningless to a program that spawns
-//! none, which is exactly the property `benilla-worldview` needs.
-//!
-//! **State it at the spawn when the body must be live the same frame.** `entities::
-//! publish_world_units` reconciles every `NetEntity` into a `WorldUnit`, but it runs between the
-//! wire drain and the rest of the frame — which is right for bodies that arrive on the wire, and
-//! one frame late for anything spawned after that slot. The water-foam fixture spawns in
-//! `WorldStage::Present` and lost its first frame of ripple to exactly this, shifting every
-//! ripple's age for the whole aged capture. Treat `WorldUnit` like `Transform`: part of what it
-//! means to spawn a body, with the reconciler as the wire path's safety net rather than the only
-//! writer.
-//!
-//! **This is a restatement, not a second source of truth**, and the difference matters: the fields
-//! are copies of facts the game already owns (`NetEntity::scale`, `CollisionHeight`), refreshed by
-//! one system on change. A stale copy is a wrong foam radius, not a wrong world — and the
-//! alternative, handing the engine the wire record, is the dependency this whole stage exists to
-//! delete.
+//! State `WorldUnit` at the spawn, like `Transform`, when the body must be live the same frame:
+//! the wire reconciler (`entities::publish_world_units`) runs right after the wire drain, a frame
+//! late for anything spawned later. Its fields copy facts the game owns (`NetEntity::scale`,
+//! `CollisionHeight`), refreshed on change.
 
 use bevy::prelude::*;
 
-/// A unit body the world can act on: it wades, it takes ground shade, it claims a WMO room, it
-/// holds a rig palette slot.
-///
-/// **Every field is an engine fact.** The first cut carried the wire's own `EntityKind` here and
-/// let the foam ask "is this a `TYPEID_UNIT`" — which made a 37 k-line protocol crate a dependency
-/// of the renderer for one three-line question, and put the wire's vocabulary in the engine's
-/// mouth. 1177 swapped the question for the one the engine actually has ([`wades`](Self::wades))
-/// and `benilla-protocol` left this crate's manifest; that absence is the whole gate.
+/// A unit body the world can act on: it wades, takes ground shade, claims a WMO room and holds a
+/// rig palette slot. Every field is an engine fact; `benilla-protocol` is not a dependency here.
 #[derive(Component, Clone, Copy, Debug)]
 pub struct WorldUnit {
-    /// Does this body **displace water** — does it push a ripple ring and drag a wake.
-    ///
-    /// A creature or a player does; a chest, a mailbox or a spell's ground anchor standing in a
-    /// lake does not. The game decides (it is the only side that knows what it spawned), the
-    /// engine only reads.
-    ///
-    /// A required field rather than a marker component, deliberately: an unstated marker is a body
-    /// that silently makes no foam, and this component exists precisely because that class of
-    /// omission "nobody notices until a screenshot". A field the compiler makes you answer cannot
-    /// be forgotten.
+    /// Whether this body displaces water (a ripple ring and a wake): a creature or a player does,
+    /// a chest or a spell's ground anchor does not. A field, so no spawn can leave it unstated.
     pub wades: bool,
     /// The instance's model scale, as the ripple ring's radius input.
     pub scale: f32,
-    /// The collision cylinder's height in yards, the ring's other input.
-    ///
-    /// A body whose display has not resolved yet carries the **client's ctor default**, never
-    /// `0.0` — at zero every depth line collapses and the body swims on dry land, which is what
-    /// `entities::CollisionHeight`'s own `Default` impl exists to prevent. The first cut of this
-    /// component defaulted it to zero and the water-foam fixture caught it: 91 k pixels of wrong
-    /// ripple, in a lane none of the six scenery captures covers.
+    /// The collision cylinder's height in yards, the ring's other input. Before the display
+    /// resolves it is the reference's constructor default, never `0.0`, at which the body swims on
+    /// dry land.
     pub height: f32,
-    /// The box the world may **cull this body by**, in model space — or `None` for a body the world
-    /// must not decide.
-    ///
-    /// The third of this component's size facts, beside [`scale`](Self::scale) and
-    /// [`height`](Self::height), and here for the same reason they are: one place answers "how big
-    /// is this body", and a second component for the culling half is the drift that ends with two
-    /// extents disagreeing.
-    ///
-    /// It exists because standing in a sealed WMO room the reference never *submits* an outdoor
-    /// object at all (`crate::exterior_cull`, decision 1270) — so the cull needs one whole-object
-    /// AABB per body, on its root, which is the reference's own granularity. The game supplies the
-    /// loader-armed idle's authored CAaBox (decision 0637 — a skinned body's bind-pose box is not
-    /// where it draws), unscaled: the root transform already carries the display scale.
-    ///
-    /// **`None` means one thing only: not the world's to decide.** In 1.12 content that is the
-    /// transport, whose root `Visibility` its own tick writes every frame — a second writer there
-    /// is the fight decision 0025 forbids.
-    ///
-    /// A body whose model has **not resolved yet** is elected all the same, with a degenerate box
-    /// at its own origin. That is not a fallback, it is the honest bound: the origin is the
-    /// server's position and is known exactly from the body's first frame, while the model's extent
-    /// crosses two reconcilers before it arrives. Admitting the body meanwhile was a real defect,
-    /// not a conservative default — every streamed mob drew for one full frame through a sealed
-    /// room's ceiling, and at a cavern's frame rate one frame is most of a second (1270 §5).
+    /// The whole-object model-space box the world may cull this body by: from inside a sealed WMO
+    /// room the reference never submits an outdoor object (`crate::exterior_cull`). The game
+    /// supplies the idle animation's authored CAaBox, unscaled; a body whose model has not resolved
+    /// is culled as a degenerate box at its origin, not admitted. `None` is not the world's to
+    /// decide: the transport, whose root `Visibility` its own tick writes.
     pub bound: Option<bevy::camera::primitives::Aabb>,
 }
 
-/// …and this one is the **viewer's own** body. A marker rather than a bool on [`WorldUnit`]
-/// because every engine use of it is a query *filter* (`Has<…>`, `Without<…>`), which a field
-/// cannot be.
+/// The viewer's own body; a marker because every use is a query filter.
 #[derive(Component)]
 pub struct ViewerUnit;
diff --git a/crates/benilla-world/src/worldview.rs b/crates/benilla-world/src/worldview.rs
index 2385ddc4..82ceea0f 100644
--- a/crates/benilla-world/src/worldview.rs
+++ b/crates/benilla-world/src/worldview.rs
@@ -1,24 +1,7 @@
-//! `benilla-worldview` — **the engine with no game attached**, and the wall that keeps it that way.
-//!
-//! Decision 1160. `benilla-app` is being split: the world renderer becomes `benilla-world`, and the
-//! game stands on it. A crate boundary alone cannot hold that line — in Bevy two systems couple
-//! with no symbol crossing between them (a `Res<player::Player>` read needs that resource to exist
-//! at *runtime*; move the type somewhere neutral and the crate graph is satisfied while the
-//! coupling is fully intact). So the enforcer is a **second binary**: this one. It boots the engine
-//! plugin set, spawns a free-fly camera, and flies over Elwynn — with no server, no login, no UI,
-//! no player. Wire a game concept back into the engine and this stops working *that day, loudly*.
-//!
-//! It is also the world editor's first milestone: a window that loads a map and lets you fly
-//! around is where `benilla-editor` starts.
-//!
-//! ## Reading this file
-//!
-//! The plugin list below is **the proposed cut line**, written down. Everything registered here is
-//! claimed for `benilla-world`; everything in [`crate::run`] and not here is claimed for the game.
-//! The `STUB` block is the spike's finding: the gameplay resources the engine reads *as data* and
-//! which a stub therefore satisfies. Each stub is a line item on the work order — the engine should
-//! end up not needing it (decision 1160, "the nine wires"), and until it doesn't, the stub says so
-//! out loud rather than the coupling hiding inside a working game.
+//! `benilla-worldview`: the engine with no game attached, and the wall that keeps it that way. It
+//! boots the engine plugins with a free-fly camera over Elwynn and no server, login, UI or player,
+//! so a game concept wired back into the engine breaks it. A crate boundary alone cannot hold that
+//! line: two Bevy systems couple through a runtime resource with no symbol crossing between them.
 
 use bevy::camera::{PerspectiveProjection, Projection};
 use bevy::core_pipeline::tonemapping::Tonemapping;
@@ -34,24 +17,15 @@ use crate::build_id::BuildId;
 use crate::terrain_stream::SPAWN_XY;
 use crate::thread_qos;
 
-/// Where the viewer opens, in WoW world coords. Northshire, Elwynn — the same anchor the client
-/// boots on ([`crate::terrain_stream::SPAWN_XY`]), so the two binaries stream the same tiles and a difference
-/// between them is a difference in the *engine*, not in where they are standing.
+/// Where the viewer opens, in WoW world coords: Northshire, the client's own boot anchor
+/// ([`crate::terrain_stream::SPAWN_XY`]), so both binaries stream the same tiles.
 const VIEW_START: (f32, f32) = SPAWN_XY;
 
 /// Height above the spawn point the camera opens at, in yards.
 const VIEW_START_HEIGHT: f32 = 60.0;
 
-/// `WOW_WORLDVIEW_AT=<x>,<y>[,<z>]` — **open the viewer somewhere else** (raw WoW coords; `z`
-/// defaults to [`VIEW_OPEN_Z`]). The viewer is the only **live, server-less** run we have — a real
-/// clock, real streaming, no login — and it was pinned to Northshire, so every question that needs
-/// time to pass at a named spot had to go through the capture harness, which freezes the clock by
-/// design. That is the gap decision 2038 was diagnosed across: the registration half was
-/// answerable in a capture, the per-frame tick was not, at any position but one.
-///
-/// Unparseable or absent leaves the viewer at [`VIEW_START`] — the enforcer's own anchor, which
-/// must stay the default (the two binaries stream the same tiles, and a difference between them is
-/// a difference in the engine).
+/// `WOW_WORLDVIEW_AT=<x>,<y>[,<z>]` opens the viewer elsewhere (raw WoW coords, `z` defaulting to
+/// [`VIEW_OPEN_Z`]); unparseable or absent stays at [`VIEW_START`], which must remain the default.
 fn view_start() -> [f32; 3] {
     let Some(v) = std::env::var("WOW_WORLDVIEW_AT").ok() else {
         return [VIEW_START.0, VIEW_START.1, VIEW_OPEN_Z];
@@ -67,45 +41,29 @@ fn view_start() -> [f32; 3] {
     }
 }
 
-/// The look-at point's height when `WOW_WORLDVIEW_AT` names no `z` — high enough over Northshire
-/// to clear the valley floor, which is what the viewer has always opened above.
+/// The look-at height when `WOW_WORLDVIEW_AT` names no `z`, clear of the Northshire valley floor.
 const VIEW_OPEN_Z: f32 = 100.0;
 
-/// Near plane, in yards. The viewer has no CVar table, so it opens at the `nearclip` CVar's
-/// registered default and stays there — **read from the const now, not copied** (2163): "kept in
-/// step by hand" is what this line used to say while holding `0.1` against a `CAM_NEAR` of `1/9`,
-/// and the drift is what showed the 1/9 was wrong in the first place.
+/// Near plane in yards: the `nearclip` CVar's default, since the viewer has no CVar table.
 const NEAR: f32 = crate::view::NEARCLIP_DEFAULT;
 
-/// Vertical FOV in radians — vanilla's 90° horizontal at 4:3.
+/// Vertical FOV in radians (70°), wider than the client camera's [`crate::view::CAM_FOVY`].
 const FOVY: f32 = 1.221_730_5;
 
-/// Build and run the world viewer. `build` is the launcher shim's compile-time git stamp, exactly
-/// as for [`crate::run`].
+/// Builds and runs the world viewer; `build` is the launcher shim's compile-time git stamp.
 pub fn run(build: BuildId) -> AppExit {
     let mut app = App::new();
     app.insert_resource(build);
 
-    // **The survey switch** (`WOW_WORLDVIEW_SURVEY=1`) — the split's instrument, and the reason the
-    // spike is one run instead of one rebuild per finding. Bevy's default error handler panics on
-    // the first system whose parameters don't validate, so a viewer missing N gameplay resources
-    // reports exactly one of them; downgraded to `warn`, a single run names all N and the log IS
-    // the work order (decision 1160). Off by default, because for the finished enforcer the panic
-    // is the point: wire a game concept back into the engine and this binary must stop, loudly.
+    // `WOW_WORLDVIEW_SURVEY=1` turns Bevy's panic on unvalidated system parameters into a
+    // warning, so one run names every missing resource.
     if std::env::var("WOW_WORLDVIEW_SURVEY").as_deref() == Ok("1") {
         warn!("worldview: SURVEY mode — unmet dependencies are warnings, not panics");
         app.set_error_handler(bevy::ecs::error::warn);
     }
 
-    // **The check** (`WOW_WORLDVIEW_CHECK[=seconds]`) — the survey, made into a gate. It collects
-    // every distinct fault instead of dying on the first, runs for a bounded time, prints the set
-    // and exits non-zero if it is non-empty. `scripts/gates.sh` runs this on every commit.
-    //
-    // This exists because the enforcer rotted. It is a binary whose entire purpose is to fail
-    // loudly the day a game concept is wired back into the engine — and it had been failing on
-    // frame one, unnoticed, because nothing ran it (decision 1164). A tripwire nobody trips is not
-    // a tripwire. The wall test measures the doorway on every `cargo test`; this measures the
-    // other half, the coupling that crosses no symbol at all.
+    // `WOW_WORLDVIEW_CHECK[=seconds]`, the survey as a gate: it records every distinct fault, runs
+    // for a bounded time, prints the set and exits non-zero if any; `scripts/gates.sh` runs it.
     let check = check_seconds();
     if let Some(secs) = check {
         app.set_error_handler(record_fault);
@@ -113,8 +71,7 @@ pub fn run(build: BuildId) -> AppExit {
             .add_systems(Update, end_check);
     }
 
-    // The `mpq://` asset source must be registered BEFORE `AssetPlugin` (inside `DefaultPlugins`)
-    // builds — same order, same reason, same install resolver (1175) as the client's boot.
+    // The `mpq://` source must be registered before `AssetPlugin` (in `DefaultPlugins`) builds.
     match benilla_formats::wow_data() {
         Some(data_dir) => {
             if let Err(e) = benilla_assets::register_mpq_source(&mut app, &data_dir) {
@@ -136,8 +93,7 @@ pub fn run(build: BuildId) -> AppExit {
                 let (w, h) = v.split_once('x')?;
                 Some(UVec2::new(w.parse().ok()?, h.parse().ok()?))
             })
-            // Small + cornered for a run nothing photographs (decision 1148, the client's own
-            // rule): the check reads the error log, not the framebuffer.
+            // Small for a run that reads no pixels, as in the client.
             .unwrap_or(if crate::bgwin::no_pixel_run() {
                 UVec2::new(640, 360)
             } else {
@@ -149,8 +105,7 @@ pub fn run(build: BuildId) -> AppExit {
         } else {
             bevy::window::PresentMode::default()
         },
-        // Same rule as the client (decision 0703): an instrumented run never fights the
-        // director's screen.
+        // As in the client: an instrumented run opens unfocused, below normal windows.
         focused: !background,
         window_level: if background {
             bevy::window::WindowLevel::AlwaysOnBottom
@@ -161,23 +116,17 @@ pub fn run(build: BuildId) -> AppExit {
     }))
     .add_plugins(thread_qos::ThreadQosPlugin)
     .add_plugins(crate::bgwin::BgWinPlugin)
-    // The third launch-time platform correction, and the client's own (decision 1528): macOS's
-    // `Cmd+Q` is wired to `terminate:`, which leaves the event loop without ever running another
-    // frame. Here that costs the check its verdict — `report_check` turns the `AppExit` into the
-    // process exit code, and there is no `AppExit` — so the viewer wants it for the same reason
-    // the client does, one layer of consequence down.
+    // macOS `Cmd+Q` is wired to `terminate:`, which leaves the event loop with no `AppExit`, and
+    // `report_check` needs one for the exit code.
     .add_plugins(crate::mac_quit::MacQuitPlugin);
 
-    // **The cut line**, and the whole of it: everything `benilla-world` will own, in one name
-    // (decision 1164, `crate::world_plugins`). This binary and the client add the identical group,
-    // so a divergence between them is no longer possible to write by accident — which is what the
-    // hand-kept twin list here was for.
+    // The cut line: the engine's whole plugin group, the same one the client adds.
     app.add_plugins(crate::world_plugins::WorldPlugins);
     stubs(&mut app);
 
     app.add_plugins(plugin);
 
-    // Registered AFTER `AssetPlugin` (they go into the live `AssetServer`) — the client's order.
+    // After `AssetPlugin`: the loaders go into the live `AssetServer`, as in the client.
     benilla_assets::register_asset_loaders(&mut app);
 
     let exit = app.run();
@@ -187,17 +136,13 @@ pub fn run(build: BuildId) -> AppExit {
     }
 }
 
-/// `WOW_WORLDVIEW_CHECK` — unset is off; bare (or unparseable) is [`CHECK_SECS_DEFAULT`]; a number
-/// is that many seconds. Long enough that the asset chain opens and the first tiles stream, which
-/// is when the streaming half of the engine first runs.
+/// `WOW_WORLDVIEW_CHECK` in seconds: unset is off, bare or unparseable is [`CHECK_SECS_DEFAULT`].
 fn check_seconds() -> Option<f32> {
     let v = std::env::var("WOW_WORLDVIEW_CHECK").ok()?;
     Some(v.trim().parse().unwrap_or(CHECK_SECS_DEFAULT))
 }
 
-/// How long the check runs when it is not given a number. Ten seconds is past the asset chain,
-/// past `Startup`, and into streamed tiles on a warm cache — every system in the engine set has
-/// been offered to the executor by then, which is what validates its parameters.
+/// Long enough on a warm cache for every engine system to run and validate its parameters.
 const CHECK_SECS_DEFAULT: f32 = 10.0;
 
 /// Wall-clock seconds the check runs for.
@@ -209,8 +154,7 @@ struct CheckDeadline(f32);
 static FAULTS: std::sync::Mutex<std::collections::BTreeSet<String>> =
     std::sync::Mutex::new(std::collections::BTreeSet::new());
 
-/// The check's error handler: record, warn, carry on — so one run names every fault rather than
-/// the first one.
+/// The check's error handler: records and warns, so one run names every fault.
 fn record_fault(error: bevy::ecs::error::BevyError, ctx: bevy::ecs::error::ErrorContext) {
     let entry = format!("{} `{}`: {error}", ctx.kind(), ctx.name());
     warn!("worldview: {entry}");
@@ -230,7 +174,7 @@ fn end_check(
     }
 }
 
-/// Print the check's verdict and turn it into a process exit code — the whole point of the mode.
+/// Prints the check's verdict and makes it the process exit code.
 fn report_check(exit: AppExit) -> AppExit {
     let faults = FAULTS
         .lock()
@@ -247,8 +191,7 @@ fn report_check(exit: AppExit) -> AppExit {
          fact is parked on the game side. Decision 1160.",
         faults.len()
     );
-    // The no-install run (`WOW_DATA=`, decision 1451) fails for a different reason than 1160's,
-    // and the run that trips it is a gate line nobody is watching — so it says which reason.
+    // A run with no install (`WOW_DATA=`) faults for a different reason, so it says which.
     if benilla_formats::wow_data().is_none() {
         println!(
             "WORLDVIEW_CHECK ran with NO INSTALL: a fault here is a system taking a resource that \
@@ -258,34 +201,11 @@ fn report_check(exit: AppExit) -> AppExit {
     }
     AppExit::error()
 }
-/// **What the engine still needs told, and nothing more.**
-///
-/// This used to be five stubs — the 1160 spike's whole finding: a fake `Player` mirrored from the
-/// camera every frame, the game's session enum asserted, `ServerTime`, the loading screen, the
-/// UI's pointer bool. Every one of them was the engine reaching across the line for a fact, and
-/// each retired by the edit its record named rather than by growing a nicer stub:
-///
-/// - "where is the viewer" → `terrain_stream::ViewFocus` + `view::Viewer`, which the engine
-///   defaults, so a program with no avatar follows its camera.
-/// - "what time is it" → `lighting::WorldTime`, defaulting to noon.
-/// - "is the cover up" → `view::Viewer::world_covered`, defaulting to no.
-/// - "is the pointer over the UI" → the engine stopped asking; `cursor` and `bindings` own it.
-///
-/// What is left is one bit, and it is configuration rather than a stub: **is there a world**.
-///
-/// ## What this function CANNOT prove — read this before trusting it
-///
-/// A stub existed here because something *panicked*. Coupling that never panics is invisible to
-/// this binary: an ordering edge onto an unregistered system is silently dropped by Bevy, an
-/// `Option<Res<…>>` read just sees `None`, and a query filtered on a component nobody spawns
-/// simply matches nothing. All three classes were found by *static* sweeps, not by running this —
-/// the panic list is a floor on the work order, never a ceiling (decision 1163).
+/// What the engine still needs told: only whether there is a world. Coupling that never panics is
+/// invisible to this binary: an ordering edge onto an unregistered system is dropped, an
+/// `Option<Res<…>>` sees `None`, and a query on a component nobody spawns matches nothing.
 fn stubs(app: &mut App) {
-    // ── The world-existence gate ──────────────────────────────────────────────────────────────
-    // The viewer's world is permanently live. This used to assert the *game's* session state
-    // (`char_select::ClientState::InWorld`) because the engine read it directly; since 1160's
-    // wire (b) the engine owns a one-bit `WorldLive` that whatever composes it writes, so the
-    // viewer just says yes.
+    // The viewer's world is always live; whatever composes the engine writes `WorldLive`.
     app.insert_resource(crate::schedule::WorldLive(true));
 }
 
@@ -298,19 +218,14 @@ fn plugin(app: &mut App) {
     .add_systems(Update, fly.in_set(crate::schedule::WorldStage::Input));
 
     // `WOW_WORLDVIEW_SHOT=<png>` (at `WOW_WORLDVIEW_SHOT_AT` seconds, default 20) writes one frame
-    // and exits. The client's own live shot (`capture::LiveShotPlugin`) can't serve here: its
-    // subject gate reads `SelfPlayer`, the name cache and the net writer, none of which the engine
-    // has. This is the viewer's own — deliberately gateless, because a viewer has no subject to be
-    // aimed at, only a scene. Post-split it is how `benilla-world` gets a visual regression
-    // baseline of its own, with no game in the frame to move underneath it.
+    // and exits, with no subject gate: the client's live shot needs a player the engine lacks.
     if std::env::var("WOW_WORLDVIEW_SHOT").is_ok() {
         app.add_systems(Update, shoot_and_exit);
     }
 }
 
-/// The one-shot frame writer behind `WOW_WORLDVIEW_SHOT` — fires once, then gives the screenshot
-/// observer a couple of seconds to reach the disk before exiting (the write is asynchronous; an
-/// immediate exit is how a "clean run" ends with no PNG, decision 0743).
+/// Fires the `WOW_WORLDVIEW_SHOT` screenshot once and exits two seconds later: the write is
+/// asynchronous, and an immediate exit loses the PNG.
 fn shoot_and_exit(
     time: Res<Time>,
     mut commands: Commands,
@@ -337,9 +252,7 @@ fn shoot_and_exit(
     }
 }
 
-/// The free-fly camera. The client's own `FlyCam` is gameplay-side today and comes over in stage
-/// zero (decision 1160); until it does, this is the viewer's own — deliberately the *minimum* that
-/// proves the engine renders, not a second implementation to keep in step.
+/// The viewer's minimal free-fly camera, not a twin of the client's `FlyCam`.
 #[derive(Component)]
 struct ViewCam {
     yaw: f32,
@@ -373,8 +286,7 @@ fn spawn_view_camera(mut commands: Commands, msaa: Res<crate::view::MsaaSetting>
     ));
 }
 
-/// WASD + Space/C fly, right-drag look, Ctrl boost, scroll to change speed. The editor's
-/// navigation, not the game's.
+/// WASD, Space and C fly, a right or left drag looks, Ctrl boosts, the wheel sets speed.
 fn fly(
     time: Res<Time>,
     keys: Res<ButtonInput<KeyCode>>,
diff --git a/crates/benilla-world/src/zfill.rs b/crates/benilla-world/src/zfill.rs
index 8997698e..644c2ec2 100644
--- a/crates/benilla-world/src/zfill.rs
+++ b/crates/benilla-world/src/zfill.rs
@@ -1,33 +1,18 @@
-//! **The depth-prime twin** — the reference's `M2UseZFill` ("z-fill transparent objects", default
-//! ON) reproduced for fading/stealthed entities (decision 0831; wow-re
-//! `m2-blend-promotion-zfill.md` §4, VERIFIED at the bytes).
+//! The depth-prime twin: the reference's `M2UseZFill` ("z-fill transparent objects", default on,
+//! `0x82e748`). For a translucent instance (`0 < A < 1`: stealth, the appear and despawn ramps,
+//! the self-avatar feather) its collector clones each z-writing mesh command into a twin drawn
+//! first (comparator key `cmd+0x08` descending in the instance's tie), colour masked off, blend
+//! off, z-write on, so overlapping parts blend as one layer, not `0.3` over `0.3`.
+//! [`sync_zfill_twins`] keeps such a twin child, sharing mesh, transform and tag, on each fadeable
+//! part while its `MeshTag` alpha is translucent.
 //!
-//! The mechanism it reproduces: when a model instance draws translucent (`0 < A < 1` — stealth's
-//! CharProc 0.3, the appear/despawn ramps, the self-avatar zoom feather), the reference's collector
-//! CLONES each of its z-writing mesh commands into a twin that draws **first** (comparator key
-//! `cmd+0x08` desc inside the instance's sort-key tie), **colour-masked off** (`glColorMask 0`),
-//! **blend off**, **z-write ON**. The whole model's nearest-surface depth is therefore in the
-//! buffer before any of its colour batches draw, each colour fragment passes the depth test only at
-//! that nearest surface, and every interior/overlapped layer fails — **one blended layer
-//! everywhere**. Without it, a stealthed body's overlapping parts compound `0.3` over `0.3` into
-//! the darker patches of ledger B182.
+//! Deviation: the reference twins every translucent command, authored-blend glass included; here
+//! twins exist only during an instance alpha episode, so every steady-state look is untouched.
 //!
-//! The benilla shape: [`sync_zfill_twins`] watches every fadeable part
-//! ([`FadeMaterials::zfill`] carries the twin material, built next to the part's blend twin) and
-//! keeps a **twin child mesh** alive on it exactly while the part's `MeshTag` alpha is translucent
-//! ([`crate::mesh_tag::translucent`]). The twin shares the part's mesh, transform and tag (same
-//! skinned pose, same rig slot), and its material's `specialize` masks the colour writes off and
-//! forces z-write on; its ordering comes from the material's negative `Transparent3d` sort bias
-//! ([`crate::model_render::ZFILL_SORT_BIAS`]).
-//!
-//! Two deliberate departures from the reference, both recorded in 0831:
-//! - **Scope**: the reference twins every translucent mesh command always (authored-Blend glass
-//!   included); we twin only while an instance alpha episode is live, so every steady-state look is
-//!   untouched.
-//! - **Ordering**: the reference ties one instance's commands to a single sort key and puts twins
-//!   first inside the tie; Bevy sorts per-entity, so the twins ride a fixed −8 yd bias instead —
-//!   transparent scene content sorting within that window behind a fading body draws after the
-//!   prime and is depth-clipped where the body covers it, for the seconds the episode lasts.
+//! Deviation: Bevy sorts per entity, so twins lead by a fixed −8 yd sort bias
+//! ([`crate::model_render::ZFILL_SORT_BIAS`]) instead of by the instance's sort-key tie;
+//! transparent content within that window behind a fading body is depth-clipped where the body
+//! covers it, for the episode.
 
 use bevy::camera::visibility::RenderLayers;
 use bevy::mesh::MeshTag;
@@ -35,27 +20,16 @@ use bevy::prelude::*;
 
 use crate::model_fade::FadeMaterials;
 
-/// On a fadeable part: its live depth-prime twin entity. Present exactly while the part draws
-/// translucent — [`sync_zfill_twins`] is the only writer.
+/// On a fadeable part: its live twin, present exactly while the part draws translucent.
 #[derive(Component)]
 pub(crate) struct ZfillTwin(Entity);
 
-/// On a twin: the part it primes for. The mesh/tag re-sync key, and the marker that keeps the twin
-/// out of every part query (writers key on [`FadeMaterials`], which a twin never carries; this side
-/// of the disjointness is the `Without` in the queries below).
+/// On a twin: the part it primes, and the marker that keeps twins out of part queries.
 #[derive(Component)]
 pub(crate) struct ZfillTwinOf(Entity);
 
-/// Keep every fadeable part's depth-prime twin in sync with its episode: spawn the twin child when
-/// the part's tag alpha enters the translucent band, despawn it when the tag settles (opaque or the
-/// part itself despawns — a child dies with its parent), and mirror the part's mesh + tag onto a
-/// live twin (a gear-change redress swaps the part's mesh in place, 0835; the rig slot rides the
-/// tag, so the twin skins into the same pose as the surface it primes).
-///
-/// Runs in `PostUpdate`, after every Update-side tag writer (the aura author, the appear/despawn
-/// ramp, the self feather) — the twin's first frame is the episode's first frame.
-/// One fadeable part as [`sync_zfill_twins`] sees it: its twin material source, live tag, mesh,
-/// and (maybe) the twin it already has.
+/// One fadeable part as [`sync_zfill_twins`] sees it: twin material, live tag, mesh, and its twin
+/// if it has one.
 type ZfillParts<'w, 's> = Query<
     'w,
     's,
@@ -65,10 +39,7 @@ type ZfillParts<'w, 's> = Query<
         &'static MeshTag,
         &'static Mesh3d,
         Option<&'static ZfillTwin>,
-        // The part's render layer, when it is not on the default one. A world part carries none
-        // and the twin needs none; a BOOTH part is on its booth's own layer, and a twin that did
-        // not copy it would prime depth in the WORLD view (where it is invisible and useless)
-        // while the booth body it exists for stayed multi-layered.
+        // A booth part's own render layer, which its twin must copy to prime the booth's view.
         Option<&'static RenderLayers>,
     ),
     Without<ZfillTwinOf>,
@@ -81,7 +52,7 @@ pub(crate) fn sync_zfill_twins(
 ) {
     for (part, fm, tag, mesh, twin, layers) in &parts {
         let Some(mat) = fm.zfill.as_ref() else {
-            continue; // no-z-write / Mod / Mod2x batch — the reference's own twin gate
+            continue; // no-z-write, Mod or Mod2x batch: the reference's own twin gate
         };
         let active = crate::mesh_tag::translucent(tag.0);
         match twin {
@@ -110,11 +81,9 @@ pub(crate) fn sync_zfill_twins(
         }
     }
     for (of, mut tag, mut mesh) in &mut twins {
-        // The part's tag moves every fade frame (its alpha bits); mirroring it keeps the rig slot
-        // — the half the twin's vertex stage actually reads — correct across a redress or a slot
-        // reassignment without a dedicated edge.
+        // Mirroring the part's tag and mesh keeps the rig slot right across a redress or reslot.
         let Ok((_, _, ptag, pmesh, _, _)) = parts.get(of.0) else {
-            continue; // part going away this frame — the child despawns with it
+            continue; // the part is going away; the child despawns with it
         };
         if tag.0 != ptag.0 {
             tag.0 = ptag.0;
@@ -125,9 +94,7 @@ pub(crate) fn sync_zfill_twins(
     }
 }
 
-/// The layer's instrument (`WOW_MOVE_TRACE=<path>`, tag `zfl`): one line per twin edge, so "did
-/// the depth prime actually arm on this body" is answered from the trace beside the `aur` lines —
-/// a stealth press prints `aur arm … target 0.30` and then one `zfl arm` per fadeable part.
+/// Trace tag `zfl` (`WOW_MOVE_TRACE=<path>`): one line per twin arm or release.
 fn trace(what: &str, part: Entity, tag: u32) {
     if !benilla_assets::trace::enabled() {
         return;
@@ -135,19 +102,14 @@ fn trace(what: &str, part: Entity, tag: u32) {
     benilla_assets::trace::line("zfl", &format!("{what} part={part} tag={tag:#010x}"));
 }
 
-/// The depth-prime lane's own registration (decision 1163, stage zero) — `EntitiesPlugin`'s last
-/// piece of the render lane.
+/// The depth-prime lane's registration.
 pub fn plugin(app: &mut App) {
-    // The depth-prime twins (decision 0831 — the reference's `M2UseZFill`): PostUpdate, after the
-    // Update-side tag writers, so a twin arms on its episode's first frame.
+    // PostUpdate, after every Update-side tag writer, so a twin arms on its episode's first frame.
     app.add_systems(PostUpdate, sync_zfill_twins);
 }
 
 #[cfg(test)]
 mod tests {
-    /// The activation band, pinned against the tag encoding it reads: the untagged sentinel and a
-    /// full alpha field are opaque (no twin), every ramp value in between is translucent (twin),
-    /// and the flag bits never leak into the decision.
     #[test]
     fn the_twin_arms_exactly_on_the_translucent_band() {
         use crate::mesh_tag;
@@ -162,12 +124,12 @@ mod tests {
                 "mid-ramp {alpha} must arm the twin"
             );
         }
-        // alpha_bits floors a non-positive alpha at field value 1 — still armed, matching the
-        // reference (only A ≤ 0 culls the batch, and that never reaches a tag).
+        // `alpha_bits` floors a non-positive alpha at 1, still armed: in the reference only A ≤ 0
+        // culls the batch, and that never reaches a tag.
         assert!(mesh_tag::translucent(mesh_tag::with_alpha(0, 0.0)));
         // The standalone flag bits are not payload: a highlighted-but-untagged instance is opaque.
         assert!(!mesh_tag::translucent(mesh_tag::HIGHLIGHT_BIT));
-        // …and a highlighted mid-ramp instance still arms.
+        // A highlighted mid-ramp instance still arms.
         assert!(mesh_tag::translucent(
             mesh_tag::with_alpha(0, 0.3) | mesh_tag::HIGHLIGHT_BIT
         ));
diff --git a/crates/benilla-worldview/Cargo.toml b/crates/benilla-worldview/Cargo.toml
index a7a7d236..714b5e0e 100644
--- a/crates/benilla-worldview/Cargo.toml
+++ b/crates/benilla-worldview/Cargo.toml
@@ -3,14 +3,13 @@ name = "benilla-worldview"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "The world viewer: the engine with no game attached — and the wall that keeps the split honest (decision 1160)"
+description = "The world viewer: the engine with no game attached, which keeps the engine and game split honest"
 
 [lints]
 workspace = true
 
 [dependencies]
-# **Only the engine.** This is the edge the binary exists to hold: if a world concept
-# ever needs the game, this line is what refuses to let it.
+# Only the engine, never a game crate: a world concept that needs the game fails to build here.
 benilla-world = { path = "../benilla-world" }
 
 [build-dependencies]
@@ -19,6 +18,5 @@ benilla-buildstamp = { path = "../benilla-buildstamp" }
 [[bin]]
 name = "benilla-worldview"
 path = "src/main.rs"
-# Same reason as the `benilla` shim: test-building this bin would relink the app in the test
-# profile on every sha change, which is the tax the shims exist to kill (decision 0993).
+# Test-building this bin would relink it on every commit, since the build stamp changes.
 test = false
diff --git a/crates/benilla-worldview/build.rs b/crates/benilla-worldview/build.rs
index a5826caa..89c95e58 100644
--- a/crates/benilla-worldview/build.rs
+++ b/crates/benilla-worldview/build.rs
@@ -1,4 +1,4 @@
-//! Stamps the commit this binary was built from — see `benilla-buildstamp`, which owns the rule.
+//! Stamps the commit this binary was built from.
 
 fn main() {
     benilla_buildstamp::emit();
diff --git a/crates/benilla-worldview/src/main.rs b/crates/benilla-worldview/src/main.rs
index 52829547..f99659ba 100644
--- a/crates/benilla-worldview/src/main.rs
+++ b/crates/benilla-worldview/src/main.rs
@@ -1,18 +1,6 @@
-//! The `benilla-worldview` launcher — the world viewer's shim, the `benilla` launcher's twin.
-//!
-//! **What this binary is for** (decision 1160): `benilla-app` is being split into `benilla-world`
-//! (the engine: renders a WoW world, streams it, flies over it, clicks on it) and the game that
-//! stands on it. A crate boundary alone cannot hold that line — in Bevy, code couples through
-//! *resources at runtime* with no symbol crossing between the crates — so the enforcer is a second
-//! program that boots the engine with **no game attached**. It is built by
-//! `cargo clippy --workspace --all-targets`, which is already a gate, so wiring a game concept back
-//! into the engine breaks it the same day.
-//!
-//! It is also where `benilla-editor` starts: a window that loads a map and lets you fly around is
-//! the editor's first milestone.
-//!
-//! Like `benilla`, this is a shim so the every-commit git stamp dirties ~20 lines instead of the
-//! app crate (decision 0993).
+//! The `benilla-worldview` launcher: boots the `benilla-world` engine with no game attached, so an
+//! engine system that needs a gameplay resource fails here, a coupling no compiler sees. Like
+//! `benilla`, a shim that carries the build stamp, so a new commit recompiles only these lines.
 
 use benilla_world::build_id::BuildId;
 
diff --git a/crates/benilla/Cargo.toml b/crates/benilla/Cargo.toml
index 4505c87c..179cf1a0 100644
--- a/crates/benilla/Cargo.toml
+++ b/crates/benilla/Cargo.toml
@@ -3,26 +3,21 @@ name = "benilla"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "The launcher: build.rs stamps the git build id, main() hands it to benilla-app. A shim, so the stamp's every-commit rebuild dirties this package and not the app crate (decision 0993)"
+description = "The launcher: build.rs stamps the git build id and main() hands it to benilla-app, so a new commit rebuilds this package and not the app crate"
 
 [lints]
 workspace = true
 
 [features]
-# The dev/player seam, forwarded (decisions 0026 + 1173): this shim is the binary a player would
-# run, so `cargo build -p benilla --no-default-features` is the player build — and the gate.
+# The dev/player seam: `cargo build -p benilla --no-default-features` is the player build.
 default = ["dev"]
 dev = ["benilla-app/dev"]
-# Forwarded profiling switches, so `cargo run --features tracy -p benilla` keeps working.
+# Profiling switches, forwarded so `cargo run -p benilla --features tracy` works.
 tracy = ["benilla-app/tracy"]
 trace_chrome = ["benilla-app/trace_chrome"]
 
 [dependencies]
-# `default-features = false` is LOAD-BEARING, not tidiness: without it `cargo build -p benilla
-# --no-default-features` still builds the library with ITS defaults (a path dep gets its own),
-# so the player-build gate would compile the full dev tree and pass no matter what. Measured on
-# 1174's first green run — `cargo tree` listed bevy_egui either way. The `dev` feature above is
-# what turns the instruments back on, and it is on by default here.
+# `default-features = false`, or `--no-default-features` here still builds benilla-app with `dev`.
 benilla-app = { path = "../benilla-app", default-features = false }
 
 [build-dependencies]
@@ -31,6 +26,5 @@ benilla-buildstamp = { path = "../benilla-buildstamp" }
 [[bin]]
 name = "benilla"
 path = "src/main.rs"
-# No tests live here — and test-building this bin would relink the whole app in the test profile
-# on every sha change, which is the exact tax the shim exists to kill (decision 0993).
+# No tests here, and test-building this bin would relink the whole app on every commit.
 test = false
diff --git a/crates/benilla/build.rs b/crates/benilla/build.rs
index 16916596..89c95e58 100644
--- a/crates/benilla/build.rs
+++ b/crates/benilla/build.rs
@@ -1,5 +1,4 @@
-//! Stamps the commit this binary was built from — see `benilla-buildstamp`, which owns the rule
-//! (and the reason it lives in this ~30-line shim rather than in `benilla-app`: decision 0993).
+//! Stamps the commit this binary was built from.
 
 fn main() {
     benilla_buildstamp::emit();
diff --git a/crates/benilla/src/main.rs b/crates/benilla/src/main.rs
index 99151983..b14bc7ea 100644
--- a/crates/benilla/src/main.rs
+++ b/crates/benilla/src/main.rs
@@ -1,9 +1,5 @@
-//! The `benilla` launcher — a shim whose whole job is to carry `build.rs`'s git stamp.
-//!
-//! Everything real lives in `benilla-app`; this package exists so the build-id stamp — whose
-//! watched git paths make cargo re-dirty the package on **every** commit, rebase, and checkout
-//! (see `build.rs`'s header) — invalidates these few lines and a relink instead of the whole app
-//! crate, its clippy pass, and its integration-test links. Decision 0993 has the measurements.
+//! The `benilla` launcher: a shim that carries the build stamp, so a new commit recompiles these
+//! few lines and relinks instead of rebuilding `benilla-app`.
 
 use benilla_app::BuildId;
 
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 00000000..7f8cdf83
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,85 @@
+# Contributing
+
+benilla is a faithful 1.12.1 client. It is the foundation people build on, not the place to get
+creative: a change is accepted when it makes benilla more like 1.12.1 or fixes a bug, with
+evidence from the reference, in one small piece, with the gates green. Everything else is a
+fork, and forks are welcome.
+
+## What gets in
+
+- A fix for a bug, with how to see it before and after.
+- A step closer to 1.12.1: a missing packet, verb, window, effect or behaviour, done the way
+  the real client does it.
+- A correction where benilla and the reference disagree, with the reference fact stated.
+
+## What does not
+
+- Features 1.12.1 does not have, and behaviour changed because it seems better. A deviation
+  from the reference is the maintainer's call and is recorded where it lives; a pull request is
+  not the place to propose one.
+- Anything from a WoW install: art, models, sounds, maps, data. The one exception is interface
+  code (FrameXML and GlueXML), and only through the migration recipe in `docs/METHOD.md`.
+- Big or mixed changes. One change per pull request, small enough to read in one sitting.
+
+## How a change is judged
+
+1. `scripts/gates.sh` is green: fmt, clippy with warnings denied, the workspace tests (once
+   with the client data, once without, so a test that reads the install has to declare it), the
+   doc-link and render-pass lints, the player build with its own tests, and the engine boot
+   checks.
+2. The reference fact is stated: what 1.12.1 does, and where that is known from (the client's
+   behaviour you observed, a DBC field, a FrameXML line, a packet capture). The names and shapes
+   under `reference/` are the surface benilla tracks.
+3. A comment where it matters, one line, saying what the code does and the 1.12 fact behind it.
+   No history.
+4. The commit message says what changed, for a player or a developer, in one line.
+
+## Setting up
+
+- **The toolchain.** Stable Rust (`rust-toolchain.toml` adds clippy and rustfmt) and a C
+  compiler, because the client's Lua is vendored and built from source. On macOS the Xcode
+  command line tools, which also supply libclang for the audio bindings; on Linux the ALSA and
+  udev development packages and pkg-config. `python3` runs two of the gates.
+- **A 1.12.1 install of your own.** `WOW_DATA=<its Data folder>`, or a `WoW` link at the repo
+  root, which only a dev build sees: the player build looks for `Data/` or `WoW/Data/` beside
+  the binary. benilla reads the install and never writes into it. `WOW_DATA=` (set, empty)
+  means "no install", which is how the no-install boot is tested on a machine that has one.
+- **Without the install, green is hollow.** About a thousand tests read the install and skip
+  when it is absent; six more read a corpus of vanilla addons (`BENILLA_ADDON_CORPUS=<a folder
+  of addons>`, or a `wow-addons-vanilla` link at the root), third-party content that is not in
+  this repo. `scripts/gates.sh` and `scripts/check.sh` print how many tests skipped and why.
+  Where the data is, `BENILLA_REQUIRE_DATA=1` turns a skip into a failure, and the gates set it
+  themselves when the install and the corpus both resolve.
+- **A server to test against.** Any 1.12.1 server; `WOW_HOST` names it (default
+  `localhost:3724`). A scripted run has no default account: `WOW_USER`, `WOW_PASS` and
+  `WOW_CHAR` name a test account on your server whose login kicks nobody, all three, either in
+  the environment or in a `.probe-identity` file at the repo root (one per line, never
+  committed), and `scripts/smoke.sh` (the live login gate) refuses without them. The probes
+  drive the body with GM commands, so give that account the top GM level.
+- **Running it unattended.** The rules are `docs/METHOD.md`, "The local server"; these are the
+  switches.
+  - `WOW_UNATTENDED=1` reconnects instead of waiting at a dialog, and exits non-zero on a login
+    it cannot pass. `WOW_NOSOUND=1` runs silent. A capture (`WOW_CAPTURE`) is both, and a rig
+    (`WOW_RIG`) is unattended. `WOW_ALLOW_ACCOUNT=1` overrides the account guard.
+  - On vmangos, `WOW_RIG="tauren druid 60 gear:heal-preraid-bis spec:heal-preraid-bis
+    at:ThunderBluff"` finds or creates that character on the account and applies the server's
+    premade sets (`WOW_RIG="gear:?"` lists them). `WOW_PROBE_CHAT="<command>"` sends one GM
+    command and logs the reply as `net: server says`. An account named `probe` and digits is
+    shielded: every world entry sends `.cheat god on`, `.die` clears it for a death test, and
+    `WOW_GOD=off` leaves it off.
+  - A trace is `WOW_MOVE_TRACE=<file>`, filtered with `WOW_MOVE_TRACE_TAGS` (`"move,snd,in"`) and
+    ended by `WOW_PROBE_EXIT_AT=<seconds>`; grep it for the `rly` and `snd` lines.
+  - A capture runs through `scripts/visual.sh`, whose recipe is the header of
+    `crates/benilla-app/src/capture/mod.rs`. Pixel questions go through `benilla-visual crop`,
+    `series` and `hotspot`.
+- **The loop.** `cargo play` builds and runs the play profile. `scripts/check.sh` verifies a
+  round of work; `scripts/gates.sh` is the full chain, and it opens a window for the engine boot
+  checks, so it needs a display. Work on a branch.
+
+## Reporting a bug
+
+Open an issue: what you did, what you saw and what 1.12.1 does instead, with the server and the
+platform you ran on. Questions and ideas are welcome there or on the Discord linked from the
+README.
+
+Working with an AI agent is expected. The agent reads `AGENTS.md`, and the same rules bind it.
diff --git a/docs/MAP.md b/docs/MAP.md
new file mode 100644
index 00000000..e94ece58
--- /dev/null
+++ b/docs/MAP.md
@@ -0,0 +1,548 @@
+# benilla — generated map
+
+> **GENERATED** by `scripts/genmap.sh` from the code — do not edit by hand; rerun the script
+> when what's built changes. *What-is* only: the *what-changed* is in git. No timestamp —
+> identical code yields an identical map.
+
+## Crates
+
+- **benilla-adt** (no Bevy) — ADT terrain-tile reader for WoW 1.12.1 (build 5875)
+- **benilla-app** (Bevy) — The Bevy app as a library: everything but the build-id stamp, which lives in the `benilla` launcher so a new commit does not rebuild this crate
+- **benilla-assets** (Bevy) — Bevy AssetSource + AssetLoaders over the WoW 1.12.1 MPQ patch chain
+- **benilla-blp** (no Bevy) — BLP2 texture decoder for WoW 1.12.1 (build 5875)
+- **benilla-buildstamp** (no Bevy) — The git build-id stamp shared by the launchers' build scripts
+- **benilla-bytes** (no Bevy) — Bounds-checked byte readers and IFF chunk iteration shared by the format parsers
+- **benilla-dbc** (no Bevy) — WDBC (client DBC) reader for WoW 1.12.1 (build 5875)
+- **benilla-formats** (no Bevy) — WoW 1.12.1 asset-format adapters (MPQ/BLP/DBC/ADT/WDT) and the benilla-extract CLI
+- **benilla-m2** (no Bevy) — M2 (MD20) model reader for WoW 1.12.1 (build 5875)
+- **benilla-mpq** (no Bevy) — Read-only MPQ archive reader for WoW 1.12.1 (build 5875)
+- **benilla-protocol** (no Bevy) — WoW 1.12.1 auth (SRP6) + world wire protocol and the benilla-auth CLI
+- **benilla-srp** (no Bevy) — WoW 1.12.1 (build 5875) SRP6 client and world-header crypto
+- **benilla-ui** (no Bevy) — Engine-free WoW UI engine core: TOC and FrameXML parsing, templates, anchors, z-order
+- **benilla-visual** (no Bevy) — Perceptual image diff for the visual A/B render harness
+- **benilla-wdt** (no Bevy) — WDT map tile-table reader and tile/world coordinates for WoW 1.12.1 (build 5875)
+- **benilla-wmo** (no Bevy) — WMO (root and group) reader for WoW 1.12.1 (build 5875)
+- **benilla-world** (Bevy) — The world renderer: terrain, water, sky, weather, models, lighting, collision and the frame ladder; everything needed to put something in a world and ask the world about itself, with no game attached
+- **benilla-worldview** (no Bevy) — The world viewer: the engine with no game attached, which keeps the engine and game split honest
+- **benilla** (no Bevy) — The launcher: build.rs stamps the git build id and main() hands it to benilla-app, so a new commit rebuilds this package and not the app crate
+
+## App subsystems — Bevy plugins in load order (`crates/benilla-app/src/lib.rs`)
+
+- ThreadQosPlugin
+- BgWinPlugin
+- MacQuitPlugin
+- WorldPlugins
+- DevToolsPlugin
+- FpsJournalPlugin
+- GamePlugins
+- DevProbesPlugin
+
+### Behind the `dev` feature (`crates/benilla-app/src/dev.rs` — compiled out by `--no-default-features`)
+
+- DebugPanelPlugin
+- PerfPlugin
+- HoverLogPlugin
+- AssetChurnPlugin
+- PreflightPlugin
+- ProbeShieldPlugin
+- CapturePlugin
+- LiveShotPlugin
+- ProbeRigPlugin
+- ProbeFocusPlugin
+- ProbeChatPlugin
+- ProbeLuaPlugin
+- ProbeDragPlugin
+- ProbeHoverPlugin
+- ProbeKeyPlugin
+- ProbeExitPlugin
+- PickProbePlugin
+- PhaseProbePlugin
+- DepthProbePlugin
+- NodeProbePlugin
+- ProbeResizePlugin
+- ParticleCensusPlugin
+- GroundCensusPlugin
+- LiftCensusPlugin
+- StallPlugin
+- TrailCensusPlugin
+- UnitVisualsPlugin
+- JitterMeterPlugin
+- DressCensusPlugin
+- RevealAuditPlugin
+- EntityCensusPlugin
+- SchedCensusPlugin
+- ProbeMeleePlugin
+- ProbePartnerPlugin
+- ProbeCrossingPlugin
+- ProbeTaxiPlugin
+- ProbeGuardPoiPlugin
+- ProbeBgQueuePlugin
+- ProbeBgPlugin
+- ProbeMailPlugin
+- ProbeAuctionPlugin
+- ProbeBankPlugin
+- ProbeBinderPlugin
+- ProbeServicePlugin
+- ProbeVendorSwapPlugin
+- ProbeModelCameraPlugin
+- ProbeGmTicketPlugin
+- ProbeCharterPlugin
+- ProbeBookPlugin
+- ProbeStonePlugin
+- ProbeChestPlugin
+- ProbeGoQuestPlugin
+- ProbeClamPlugin
+- ProbeCastCancelPlugin
+- ProbeCharCreatePlugin
+- LiveFpsPlugin
+- ProbeLookPlugin
+- ProbePitchPlugin
+- ProbeCamPlugin
+
+## Modules (top-level, per crate)
+
+- **benilla-adt** (lib.rs): combined_alpha 
+- **benilla-app** (lib.rs): addon_harness area area_poi area_trigger asset_churn aura_visual bindings blob_shadow bowstring camera_shake capture char_create char_select chat_bubble chr_classes cinematic combat_log combat_text console crash creature_anim cursor cvars death debug_panel dev doodad_events entities fishing_line footprints game_plugins game_tip glue glue_strings go_anim go_templates hover_log items loading_screen local_state login minimap name_persist nameplates names net npc_text opaque2d pending_item_ops perf pipe_warm player poi_marker portrait preflight probe_shield query_cache quest_markers raid_marks ranged_flex realm_select realmlist run_mode screen_fade screenshot shaders shutdown smart_rect sound spell swing_refusal target test_support text_filter text_reshape textinput transport tutorial ui_action ui_auction ui_aura ui_bank ui_battlefield ui_battlefield_positions ui_battlefield_score ui_bind_confirm ui_binder ui_cast ui_char ui_chat ui_craft ui_dialog_verbs ui_dressup ui_duel ui_follow ui_gamma ui_gm_ticket ui_gossip ui_guild ui_hide ui_honor ui_inspect ui_instance ui_item_text ui_items ui_layout ui_logout ui_loot ui_loot_roll ui_macro ui_mail ui_merchant ui_mirror ui_models ui_net ui_party ui_pass ui_pet ui_pet_book ui_pet_doll ui_pet_stats ui_petition ui_quest ui_quest_log ui_quest_share ui_reputation ui_saved ui_script ui_session ui_shapeshift ui_social ui_spellbook ui_stable ui_summon ui_tabard ui_talent ui_talent_wipe ui_taxi ui_text ui_tooltip ui_trade ui_tradeskill ui_trainer ui_unit ui_world_map video vplates weapon_trail world_backdrop world_state world_state_ui 
+- **benilla-assets** (lib.rs): adt anim_rng blp column_grid coords gpu_blp m2 materials minimap_grid model spatial_cache terrain tex_filter trace wdt wmo world_assets 
+- **benilla-formats** (lib.rs): anim_data area_poi area_sound area_table area_trigger auction_house bank_bag_slot_prices camera_shakes chain characters chat_channels chr_classes cinematics creature_families creature_sound creature_types creatures dbc death_thud durability elevators emit_timing emote_text emotes environmental_damage exhaustion factions footsteps game_tips gameobjects garble gm_ticket_category ground_effects install item_random_properties item_sounds item_visuals itembagfamily itemclass items itemsets itemsubclass languages light liquid loading_screen lock lock_type macro_icons maps material minimap_translate models npc_greeting page_text_material particles pet_stats quest_headers quest_info race_pvp_team race_sound ribbons server_messages sheathe skill_lines sound_entries sound_provider sound_water spell_focus spell_mechanic spell_visual spells stable_slot_prices stationery talents taxi taxi_nodes taxi_path terrain text_filter_lists tga transport_period transports unit_blood value_track vocal_ui_sounds wdl weapon_impact weapon_swing wmo_area world_map_area world_map_continent world_map_overlay world_state_ui zone_map 
+- **benilla-m2** (lib.rs): error model skin tests track 
+- **benilla-mpq** (lib.rs): crypto 
+- **benilla-protocol** (lib.rs): auth events guid messages wire world 
+- **benilla-srp** (lib.rs): vanilla_header 
+- **benilla-ui** (lib.rs): bindings_xml civil framexml justify layout loader markup messages order script source strings toc widget 
+- **benilla-visual** (lib.rs): relight 
+- **benilla-world** (lib.rs): art_scope assets bgwin billboard boot build_id clouds clutter collision decal dev_state doodad_anim entity_shade exterior_cull ffx_glow final_pass frame_pace ground_fx instance_tint interact interior lighting liquid log_ring mac_quit map_proj mat_anim_table mesh_tag model_fade model_forms model_render modkeys particles ribbons ride_frame rig_anim rig_palette rig_rider schedule shaders sky sky_order skybox static_gx static_merge straddle sun surface terrain_stream thread_qos view vis_chain water_fx wdl weather wmo_portal world_census world_map world_plugins world_point world_unit worldview zfill 
+
+## CLI binaries
+
+- `benilla-auth` (in benilla-protocol)
+- `benilla-extract` (in benilla-formats)
+- `benilla-world` (in benilla-protocol)
+- `blpx` (in benilla-blp)
+- `mpqx` (in benilla-formats)
+
+## WGSL shaders (`crates/*/src/shaders/`, embedded)
+
+- `embedded://benilla_app/shaders/ui_add.wgsl`
+- `embedded://benilla_app/shaders/ui_gamma.wgsl`
+- `embedded://benilla_app/shaders/ui_node_gamma.wgsl`
+- `embedded://benilla_app/shaders/ui_quad.wgsl`
+- `embedded://benilla_app/shaders/ui_slice_gamma.wgsl`
+- `embedded://benilla_assets/shaders/liquid.wgsl`
+- `embedded://benilla_assets/shaders/terrain.wgsl`
+- `embedded://benilla_assets/shaders/wdl.wgsl`
+- `embedded://benilla_assets/shaders/wow_model.wgsl`
+- `embedded://benilla_world/shaders/celestial.wgsl`
+- `embedded://benilla_world/shaders/cloud.wgsl`
+- `embedded://benilla_world/shaders/ffx_glow.wgsl`
+- `embedded://benilla_world/shaders/sky_vertex.wgsl`
+- `embedded://benilla_world/shaders/sky.wgsl`
+- `embedded://benilla_world/shaders/star.wgsl`
+- `embedded://benilla_world/shaders/static_gx.wgsl`
+- `embedded://benilla_world/shaders/wow_effect.wgsl`
+
+## Instruments — `$WOW_*` switches (env-var read sites)
+
+> The headless/dev instrument fleet, discovered from the code: every `WOW_*` env var
+> some `.rs` reads, and where it's read — the doc comment at the read site is the
+> semantics. (The in-window surfaces — the Ctrl+Shift dev-chord overlays — are plugins
+> above; this indexes the switches that don't announce themselves.)
+
+- `WOW_ADDON_PROBE_AWAIT_INVITE` — benilla-protocol/examples/addon_chat_probe.rs
+- `WOW_ADDON_PROBE_TRACE` — benilla-protocol/examples/addon_chat_probe.rs
+- `WOW_ALLOW_ACCOUNT` — benilla-app/src/login/mod.rs, benilla-app/src/run_mode.rs
+- `WOW_AMBIGUITY_DUMP` — benilla-app/src/game_plugins.rs
+- `WOW_ANIM_COST` — benilla-app/src/creature_anim/driver.rs
+- `WOW_ANIM_PARK_ALL` — benilla-app/src/creature_anim/lod.rs
+- `WOW_ANISO` — benilla-app/src/cvars.rs, benilla-assets/src/tex_filter.rs
+- `WOW_API_DUMP` — benilla-app/tests/world_api_wall.rs
+- `WOW_ARCH_CENSUS` — benilla-app/src/perf/mod.rs
+- `WOW_ART_RADIUS` — benilla-world/src/art_scope.rs
+- `WOW_ASSET_CHURN` — benilla-app/src/asset_churn.rs
+- `WOW_ASSET_DUMP` — benilla-app/src/capture/probes/live_fps.rs
+- `WOW_AUDIO_LIVE` — benilla-app/src/sound/output/mod.rs
+- `WOW_AUDIO_NO_RT` — benilla-app/src/sound/output/mod.rs
+- `WOW_AUDIT_` — benilla-world/src/bgwin.rs
+- `WOW_AUDIT_START` — benilla-world/src/wmo_portal/audit/mod.rs
+- `WOW_AUDIT_WMO` — benilla-world/src/wmo_portal/audit/mod.rs
+- `WOW_BARE_DOODAD_COLLIDERS` — benilla-world/src/terrain_stream/collider.rs
+- `WOW_BG` — benilla-world/src/bgwin.rs
+- `WOW_BLOB_VIS` — benilla-world/src/terrain_stream/merge.rs
+- `WOW_BLOB_VIS_UID` — benilla-world/src/terrain_stream/merge.rs
+- `WOW_BOOTH_DUMP` — benilla-app/src/portrait/test_bake.rs
+- `WOW_BOOTH_LOG` — benilla-app/src/portrait/mod.rs
+- `WOW_BUBBLE_TRACE` — benilla-app/src/chat_bubble.rs
+- `WOW_CAM_CHANGED` — benilla-app/src/perf/mod.rs
+- `WOW_CAM_DUMP` — benilla-app/src/player/camera.rs
+- `WOW_CAPTURE` — benilla-app/src/capture/mod.rs, benilla-app/src/capture/scenarios.rs, benilla-app/src/char_select/addons.rs, benilla-app/src/cvars.rs, benilla-app/src/lib.rs, benilla-app/src/local_state.rs, benilla-app/src/login/mod.rs, benilla-app/src/name_persist.rs, benilla-app/src/net.rs, benilla-app/src/player/camera_saved.rs, benilla-app/src/run_mode.rs, benilla-app/src/sound/mod.rs, benilla-app/src/ui_chat/settings.rs, benilla-app/src/ui_chat/tests.rs, benilla-app/src/ui_macro/tests.rs, benilla-app/src/ui_saved.rs, benilla-app/src/ui_script/addons.rs, benilla-app/src/ui_script/mod.rs, benilla-app/src/ui_script/world_entry_tests.rs, benilla-app/src/video.rs, benilla-world/src/bgwin.rs, benilla-world/src/clouds/mod.rs, benilla-world/src/dev_state.rs
+- `WOW_CAPTURE_AGE` — benilla-app/src/capture/mod.rs
+- `WOW_CAPTURE_DEADLINE` — benilla-app/src/capture/mod.rs
+- `WOW_CAPTURE_OUT` — benilla-app/src/capture/mod.rs
+- `WOW_CAPTURE_REHOVER` — benilla-app/src/ui_script/mod.rs
+- `WOW_CAPTURE_STABLE` — benilla-app/src/capture/mod.rs
+- `WOW_CAPTURE_UI` — benilla-app/src/capture/scenarios.rs, benilla-app/src/ui_script/mod.rs, benilla-app/src/video.rs
+- `WOW_CAST_TRACE` — benilla-app/src/net.rs
+- `WOW_CHAR` — benilla-app/src/capture/probe_mail.rs, benilla-app/src/char_select/mod.rs, benilla-app/src/cvars.rs, benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/net/io.rs, benilla-app/src/realm_select/smoke.rs, benilla-app/src/run_mode.rs
+- `WOW_CHARCREATE_DIALS` — benilla-app/src/char_create/mod.rs
+- `WOW_CHARCREATE_NAME` — benilla-app/src/char_create/mod.rs
+- `WOW_CHARCREATE_PICK` — benilla-app/src/capture/mod.rs, benilla-app/src/char_create/mod.rs
+- `WOW_CHARCREATE_SHOT` — benilla-app/src/char_create/mod.rs, benilla-world/src/bgwin.rs
+- `WOW_CHARCREATE_SHOT_OUT` — benilla-app/src/char_create/mod.rs
+- `WOW_CHARSELECT_ADDONS` — benilla-app/src/char_select/mod.rs
+- `WOW_CHARSELECT_DIALOG` — benilla-app/src/char_select/mod.rs
+- `WOW_CHARSELECT_PICK` — benilla-app/src/char_select/mod.rs, benilla-app/src/cvars.rs
+- `WOW_CHARSELECT_SHOT` — benilla-world/src/bgwin.rs
+- `WOW_CHARSELECT_SHOT_AT` — benilla-app/src/char_select/mod.rs
+- `WOW_CHARSELECT_SHOT_OUT` — benilla-app/src/char_select/mod.rs
+- `WOW_CHARSELECT_WALK` — benilla-app/src/char_select/mod.rs
+- `WOW_CLAMP_COST` — benilla-app/src/net/motion/spline.rs
+- `WOW_CLAMP_SEAT` — benilla-app/src/net/motion/spline.rs
+- `WOW_CLAMP_TRACE` — benilla-app/src/net/motion/spline.rs
+- `WOW_CLOCK` — benilla-world/src/dev_state.rs
+- `WOW_CLOUD_DUMP` — benilla-world/src/clouds/mod.rs
+- `WOW_CLUSTERS` — benilla-app/src/player/setup.rs
+- `WOW_CLUTTER_ALPHA` — benilla-world/src/clutter.rs
+- `WOW_CLUTTER_DENSITY` — benilla-app/src/cvars.rs, benilla-app/src/lib.rs, benilla-world/src/clutter.rs
+- `WOW_CLUTTER_FADE` — benilla-world/src/clutter.rs
+- `WOW_COLUMN_COST` — benilla-assets/src/column_grid.rs
+- `WOW_CPU_CENSUS` — benilla-app/src/perf/census.rs
+- `WOW_CRASH_INJECT` — benilla-app/src/perf/crash_inject.rs
+- `WOW_CREATE_SPLINE` — benilla-app/src/net/motion/spline.rs
+- `WOW_CREATE_TEST` — benilla-app/src/portrait/glue_booth.rs, benilla-world/src/bgwin.rs
+- `WOW_CULL_TRACE` — benilla-world/src/exterior_cull.rs
+- `WOW_CULLDUMP` — benilla-world/src/wmo_portal/mod.rs
+- `WOW_CURSOR_TRACE` — benilla-app/src/cursor.rs
+- `WOW_DATA` — benilla-app/src/local_state.rs, benilla-formats/src/install.rs, benilla-formats/tests/wow_data_env.rs, benilla-formats/tests/wow_data_none.rs
+- `WOW_DEMO_BOTTOM_BARS` — benilla-app/src/ui_script/mod.rs
+- `WOW_DEPTH` — benilla-app/src/capture/depth_probe.rs, benilla-app/src/dev.rs, benilla-world/src/bgwin.rs
+- `WOW_DEPTH_AFTER` — benilla-app/src/capture/depth_probe.rs
+- `WOW_DEPTH_AT` — benilla-app/src/capture/depth_probe.rs
+- `WOW_DEPTH_COUNT` — benilla-app/src/capture/depth_probe.rs
+- `WOW_DEPTH_QUADS` — benilla-app/src/capture/depth_probe.rs, benilla-app/src/dev.rs
+- `WOW_DITHER` — benilla-world/src/ffx_glow.rs
+- `WOW_DPI` — benilla-app/src/video.rs
+- `WOW_DRESS_CENSUS` — benilla-app/src/capture/probes/dress_census.rs, benilla-app/src/dev.rs
+- `WOW_DRESS_CENSUS_RADIUS` — benilla-app/src/capture/probes/dress_census.rs
+- `WOW_DRIFT_DUMP` — benilla-world/src/liquid/drift.rs
+- `WOW_DUMP_TILE` — benilla-world/src/wmo_portal/audit/light_probe.rs
+- `WOW_EFFECT_TRACE` — benilla-world/src/particles/render.rs
+- `WOW_EMIT_DUMP` — benilla-world/src/particles/emitdump.rs
+- `WOW_ENTITY_CENSUS` — benilla-app/src/capture/probes/world_census.rs, benilla-app/src/dev.rs
+- `WOW_FADE_NEAR` — benilla-world/src/terrain_stream/spawn/mod.rs
+- `WOW_FARCLIP` — benilla-app/src/cvars.rs, benilla-world/src/view.rs
+- `WOW_FEED_COST` — benilla-app/src/ui_items/feed.rs
+- `WOW_FEED_GATE_CHECK` — benilla-app/src/ui_script/gate.rs, benilla-world/src/bgwin.rs
+- `WOW_FEED_GATE_TRACE` — benilla-app/src/ui_script/gate.rs, benilla-world/src/bgwin.rs
+- `WOW_FIXED_DT` — benilla-world/src/frame_pace.rs
+- `WOW_FOG_DUMP` — benilla-world/src/lighting/resolve.rs, benilla-world/src/liquid/query.rs
+- `WOW_FOLLOW_TRACE` — benilla-app/src/player/follow.rs
+- `WOW_FORCE_SUB` — benilla-world/src/liquid/mod.rs
+- `WOW_FPS_` — benilla-world/src/bgwin.rs
+- `WOW_FPS_JOURNAL` — benilla-app/src/perf/journal.rs
+- `WOW_FPS_PROBE` — benilla-app/src/capture/mod.rs
+- `WOW_FRAME_PHASES` — benilla-app/src/perf/phases.rs
+- `WOW_FREEZE_UI_MESH` — benilla-app/src/ui_pass.rs
+- `WOW_FX_AGE` — benilla-app/src/capture/mod.rs
+- `WOW_FX_AT` — benilla-app/src/capture/mod.rs
+- `WOW_FX_AZ` — benilla-app/src/capture/mod.rs
+- `WOW_FX_CENSUS` — benilla-app/src/capture/probes/fx_draw_census.rs
+- `WOW_FX_DISPLAY` — benilla-app/src/capture/mod.rs
+- `WOW_FX_DIST` — benilla-app/src/capture/mod.rs
+- `WOW_FX_EL` — benilla-app/src/capture/mod.rs
+- `WOW_FX_FLY` — benilla-app/src/capture/mod.rs
+- `WOW_FX_GO` — benilla-app/src/capture/mod.rs
+- `WOW_FX_GO_STATE` — benilla-app/src/capture/mod.rs
+- `WOW_FX_GO_TYPE` — benilla-app/src/capture/mod.rs
+- `WOW_FX_GROUND` — benilla-app/src/capture/mod.rs
+- `WOW_FX_HOLD` — benilla-app/src/capture/mod.rs
+- `WOW_FX_MINUTE` — benilla-app/src/capture/mod.rs
+- `WOW_FX_MODEL` — benilla-app/src/capture/mod.rs
+- `WOW_FX_SCALE` — benilla-app/src/capture/mod.rs
+- `WOW_FX_TURN` — benilla-app/src/capture/mod.rs
+- `WOW_FX_UP` — benilla-app/src/capture/mod.rs
+- `WOW_FX_YAW` — benilla-app/src/capture/mod.rs
+- `WOW_GHOST_PROBE` — benilla-app/src/death/mod.rs
+- `WOW_GLUE_ROUNDTRIP` — benilla-app/src/char_select/mod.rs, benilla-world/src/bgwin.rs
+- `WOW_GLYPH_CACHE` — benilla-app/src/ui_text/engine/gpu.rs
+- `WOW_GM` — benilla-app/src/probe_shield.rs
+- `WOW_GOD` — benilla-app/src/preflight.rs, benilla-app/src/probe_shield.rs
+- `WOW_GPU_MS` — benilla-app/src/perf/gpu.rs
+- `WOW_GPU_PASSES` — benilla-app/src/perf/journal.rs
+- `WOW_GROUND_CENSUS` — benilla-app/src/capture/probes/ground_census.rs, benilla-app/src/dev.rs
+- `WOW_GROUND_CENSUS_RADIUS` — benilla-app/src/capture/probes/ground_census.rs
+- `WOW_GX_CENSUS` — benilla-world/src/static_gx/cull.rs
+- `WOW_GX_FADE_TRACE` — benilla-world/src/static_gx/cull.rs
+- `WOW_GX_PERF` — benilla-world/src/static_gx/mod.rs
+- `WOW_HIT_COST` — benilla-app/src/ui_script/input.rs
+- `WOW_HOST` — benilla-app/src/cvars.rs, benilla-app/src/realmlist.rs
+- `WOW_HOVER_LOG` — benilla-app/src/hover_log.rs
+- `WOW_HOVER_LOG_REPORT` — benilla-app/src/lib.rs
+- `WOW_HOVER_PROBE` — benilla-app/src/target/hover_probe.rs
+- `WOW_INDIRECT` — benilla-world/src/world_plugins.rs
+- `WOW_INTERIOR_COST` — benilla-world/src/interior.rs
+- `WOW_INTERIOR_LOG` — benilla-world/src/entity_shade.rs, benilla-world/src/interior.rs, benilla-world/src/model_fade.rs
+- `WOW_IO_BUFFER` — benilla-app/src/sound/mixer.rs
+- `WOW_JITTER` — benilla-app/src/capture/probes/jitter.rs, benilla-app/src/dev.rs
+- `WOW_JITTER_RAW` — benilla-app/src/capture/probes/jitter.rs
+- `WOW_LAYOUT_DERIVE_TRACE` — benilla-ui/src/script/model.rs
+- `WOW_LAYOUT_PROF` — benilla-ui/src/script/layout.rs
+- `WOW_LAYOUT_TOUCH_TRACE` — benilla-ui/src/script/model.rs
+- `WOW_LAYOUT_VERIFY` — benilla-ui/src/script/layout.rs
+- `WOW_LIFT_CENSUS` — benilla-app/src/capture/probes/lift_census.rs, benilla-app/src/dev.rs
+- `WOW_LIGHT_AT` — benilla-world/src/wmo_portal/audit/light_probe.rs
+- `WOW_LIGHT_DUMP` — benilla-world/src/lighting/global_light.rs, benilla-world/src/lighting/resolve.rs
+- `WOW_LIGHT_GRID` — benilla-world/src/wmo_portal/audit/light_probe.rs
+- `WOW_LIQUID_DC` — benilla-assets/src/world_assets/images.rs
+- `WOW_LIVE_` — benilla-world/src/bgwin.rs
+- `WOW_LIVE_FPS` — benilla-app/src/capture/probes/live_fps.rs, benilla-app/src/dev.rs, benilla-world/src/bgwin.rs
+- `WOW_LIVE_FPS_AT` — benilla-app/src/capture/probes/live_fps.rs
+- `WOW_LIVE_FPS_MOVE` — benilla-app/src/capture/probes/live_fps.rs
+- `WOW_LIVE_SHOT` — benilla-app/src/capture/live_shot.rs, benilla-app/src/dev.rs
+- `WOW_LIVE_SHOT_AT` — benilla-app/src/capture/live_shot.rs
+- `WOW_LIVE_SHOT_COUNT` — benilla-app/src/capture/live_shot.rs
+- `WOW_LIVE_SHOT_EVERY` — benilla-app/src/capture/live_shot.rs
+- `WOW_LOGIN_SHOT` — benilla-world/src/bgwin.rs
+- `WOW_LOGIN_SHOT_OUT` — benilla-app/src/login/screen.rs
+- `WOW_LOGIN_SMOKE` — benilla-app/src/char_select/mod.rs, benilla-app/src/login/mod.rs, benilla-app/src/login/smoke.rs, benilla-world/src/bgwin.rs
+- `WOW_LOGIN_SMOKE_HOLD` — benilla-app/src/login/smoke.rs
+- `WOW_LOGOUT_SMOKE` — benilla-app/src/char_select/mod.rs, benilla-world/src/bgwin.rs
+- `WOW_MAP` — benilla-app/src/capture/mod.rs, benilla-world/src/world_map.rs
+- `WOW_MATANIM_DUTY` — benilla-world/src/doodad_anim/mat_anim.rs
+- `WOW_MATANIM_LIVE` — benilla-world/src/doodad_anim/mat_anim.rs
+- `WOW_MATANIM_PROBE` — benilla-world/src/doodad_anim/mat_anim.rs
+- `WOW_MERGE_CENSUS` — benilla-world/src/static_merge.rs
+- `WOW_MERGE_FADERS` — benilla-world/src/terrain_stream/merge.rs
+- `WOW_MERGED_FADE` — benilla-assets/src/materials.rs
+- `WOW_MERGED_SLOT` — benilla-assets/src/materials.rs
+- `WOW_MESH_EVENTS` — benilla-app/src/perf/mod.rs
+- `WOW_MESH_HOLDERS` — benilla-app/src/perf/mod.rs
+- `WOW_MESH_TOUCH` — benilla-app/src/perf/mod.rs
+- `WOW_MIX_TAP` — benilla-app/src/sound/mix_tap.rs
+- `WOW_MM_BLIP_PROBE` — benilla-app/src/minimap/mod.rs, benilla-world/src/bgwin.rs
+- `WOW_MM_PROBE` — benilla-app/src/capture/mod.rs, benilla-app/src/minimap/mod.rs, benilla-world/src/bgwin.rs
+- `WOW_MM_STATS` — benilla-app/src/minimap/mod.rs
+- `WOW_MM_ZOOM` — benilla-app/src/minimap/mod.rs
+- `WOW_MOVE_SPEED` — benilla-app/src/player/setup.rs
+- `WOW_MOVE_TRACE` — benilla-assets/src/trace.rs
+- `WOW_MOVE_TRACE_TAGS` — benilla-assets/src/trace.rs
+- `WOW_MSAA` — benilla-app/src/cvars.rs, benilla-world/src/view.rs
+- `WOW_MT_EXTRACT` — benilla-app/src/lib.rs
+- `WOW_MT_POSTUPDATE` — benilla-app/src/lib.rs
+- `WOW_MT_UPDATE` — benilla-app/src/lib.rs
+- `WOW_NAME_AZ` — benilla-app/src/capture/mod.rs
+- `WOW_NAME_DIST` — benilla-app/src/capture/mod.rs
+- `WOW_NAME_EL` — benilla-app/src/capture/mod.rs
+- `WOW_NAME_H` — benilla-app/src/capture/mod.rs
+- `WOW_NO_ALPHATEST` — benilla-world/src/model_render.rs
+- `WOW_NO_ANIM_LOD` — benilla-app/src/creature_anim/lod.rs, benilla-app/src/lib.rs
+- `WOW_NO_BC` — benilla-assets/src/gpu_blp.rs
+- `WOW_NO_DOODAD_BODIES` — benilla-world/src/terrain_stream/collider.rs
+- `WOW_NO_DRAW_ELECTION` — benilla-world/src/exterior_cull.rs
+- `WOW_NO_FFX` — benilla-world/src/ffx_glow.rs
+- `WOW_NO_FRAME_PACE` — benilla-world/src/frame_pace.rs
+- `WOW_NO_HULL_WELD` — benilla-world/src/terrain_stream/weld.rs
+- `WOW_NO_INDIRECT` — benilla-app/src/player/setup.rs
+- `WOW_NO_LIQUID` — benilla-world/src/liquid/mod.rs
+- `WOW_NO_MESH_PARK` — benilla-world/src/model_render/park.rs
+- `WOW_NO_MOUNT_TILT` — benilla-app/src/entities/conform.rs
+- `WOW_NO_PARTICLES` — benilla-world/src/liquid/drift.rs, benilla-world/src/particles.rs, benilla-world/src/ribbons.rs
+- `WOW_NO_RIDE_FRAME` — benilla-world/src/ride_frame.rs
+- `WOW_NO_RIG_REBASE` — benilla-world/src/rig_palette.rs
+- `WOW_NO_ROOM_LOD` — benilla-app/src/creature_anim/lod.rs
+- `WOW_NO_TILE_CELLS` — benilla-world/src/terrain_stream/furnish.rs
+- `WOW_NO_TILE_DROP` — benilla-world/src/terrain_stream.rs
+- `WOW_NO_TWIST` — benilla-app/src/creature_anim/twist.rs
+- `WOW_NODE_PROBE` — benilla-app/src/capture/probes/world_census.rs, benilla-app/src/dev.rs, benilla-world/src/bgwin.rs
+- `WOW_NOPORTALCULL` — benilla-world/src/dev_state.rs
+- `WOW_NOSOUND` — benilla-app/src/sound/mod.rs
+- `WOW_NOVSYNC` — benilla-app/src/video.rs, benilla-world/src/worldview.rs
+- `WOW_OCEAN_DEPTH_DIV` — benilla-formats/src/liquid.rs
+- `WOW_PANEL` — benilla-world/src/dev_state.rs
+- `WOW_PART_CHURN` — benilla-app/src/perf/mod.rs
+- `WOW_PARTICLE_CENSUS` — benilla-app/src/capture/probes/particle_census.rs, benilla-app/src/dev.rs, benilla-world/src/bgwin.rs
+- `WOW_PARTICLE_DEPTHDUMP` — benilla-world/src/particles/depthdump.rs
+- `WOW_PARTICLE_DEPTHDUMP_BONES` — benilla-world/src/particles/depthdump.rs
+- `WOW_PARTICLE_FLAT` — benilla-world/src/particles/render.rs
+- `WOW_PARTICLE_NODEPTH` — benilla-world/src/particles/render.rs
+- `WOW_PASS` — benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/run_mode.rs
+- `WOW_PERF_HUD` — benilla-app/src/perf/hud.rs
+- `WOW_PHASE` — benilla-app/src/capture/phase_probe.rs, benilla-app/src/dev.rs, benilla-world/src/bgwin.rs
+- `WOW_PHASE_AT` — benilla-app/src/capture/phase_probe.rs
+- `WOW_PHASE_COUNT` — benilla-app/src/capture/phase_probe.rs
+- `WOW_PHYS_HZ` — benilla-world/src/world_plugins.rs
+- `WOW_PHYS_PREPROP` — benilla-world/src/world_plugins.rs
+- `WOW_PICK` — benilla-app/src/capture/pick_probe.rs, benilla-app/src/dev.rs, benilla-world/src/bgwin.rs
+- `WOW_PICK_AT` — benilla-app/src/capture/pick_probe.rs
+- `WOW_PICK_COUNT` — benilla-app/src/capture/pick_probe.rs
+- `WOW_PICK_EVERY` — benilla-app/src/capture/pick_probe.rs
+- `WOW_PIN_ASPECT` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_COL` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_EYE` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_FLOOR` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_FOVY` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_LOOK` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_MAP` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_SITE` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_TILE` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_UID` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIN_WMO` — benilla-world/src/wmo_portal/audit/pin.rs
+- `WOW_PIPE_TRACE` — benilla-app/src/pipe_warm/mod.rs
+- `WOW_POINTS_DUMP` — benilla-world/src/lighting/global_light.rs
+- `WOW_PORTRAIT_TEST` — benilla-app/src/portrait/mod.rs, benilla-app/src/portrait/test_bake.rs, benilla-world/src/bgwin.rs
+- `WOW_PORTRAIT_TEST_SKIN` — benilla-app/src/portrait/test_bake.rs
+- `WOW_PROBE` — benilla-app/src/dev.rs, benilla-app/src/lib.rs, benilla-world/src/bgwin.rs
+- `WOW_PROBE_AUCTION` — benilla-app/src/dev.rs
+- `WOW_PROBE_BANK` — benilla-app/src/dev.rs
+- `WOW_PROBE_BG` — benilla-app/src/capture/probe_bg.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_BG_SAMPLES` — benilla-app/src/capture/probe_bg.rs
+- `WOW_PROBE_BGQUEUE` — benilla-app/src/dev.rs
+- `WOW_PROBE_BINDER` — benilla-app/src/dev.rs
+- `WOW_PROBE_BOOK` — benilla-app/src/dev.rs
+- `WOW_PROBE_CAM` — benilla-app/src/capture/probe_cam.rs
+- `WOW_PROBE_CHARCREATE` — benilla-app/src/capture/probe_charcreate.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_CHARCREATE_KEEP` — benilla-app/src/capture/probe_charcreate.rs
+- `WOW_PROBE_CHARTER` — benilla-app/src/dev.rs
+- `WOW_PROBE_CHAT` — benilla-app/src/capture/probes/act.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_CHAT_AT` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_CHAT_EVERY` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_CHEST` — benilla-app/src/capture/probe_chest.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_CLAM` — benilla-app/src/capture/probe_clam.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_DOCK` — benilla-app/src/capture/probe_crossing.rs
+- `WOW_PROBE_DRAG` — benilla-app/src/capture/probes/act.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_DRAG_AT` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_DRAG_LUA` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_DRAG_STEP` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_EXIT_AT` — benilla-app/src/capture/probes/run.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_GMTICKET` — benilla-app/src/dev.rs
+- `WOW_PROBE_GOQUEST` — benilla-app/src/capture/probe_goquest.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_HOVER` — benilla-app/src/capture/probes/act.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_HOVER_AT` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_HOVER_DUTY` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_HOVER_JITTER` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_HOVER_STEP` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_KEY` — benilla-app/src/capture/probes/act.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_LOOK` — benilla-app/src/capture/probe_look.rs
+- `WOW_PROBE_LUA` — benilla-app/src/capture/probes/act.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_LUA_AGAIN` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_LUA_AT` — benilla-app/src/capture/probes/act.rs
+- `WOW_PROBE_MAIL` — benilla-app/src/dev.rs
+- `WOW_PROBE_MODEL_CAMERA` — benilla-app/src/dev.rs
+- `WOW_PROBE_NAME_TRACE` — benilla-app/src/nameplates.rs
+- `WOW_PROBE_PARK` — benilla-app/src/capture/probes/run.rs
+- `WOW_PROBE_PITCH` — benilla-app/src/capture/probe_pitch.rs
+- `WOW_PROBE_RESIZE` — benilla-app/src/capture/probes/run.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_SERVICE` — benilla-app/src/dev.rs
+- `WOW_PROBE_SHARED_SKIN` — benilla-app/src/entities/attach/char_skin.rs
+- `WOW_PROBE_STONE` — benilla-app/src/capture/probe_stone.rs, benilla-app/src/dev.rs
+- `WOW_PROBE_UI_ONE_TEX` — benilla-app/src/ui_pass.rs
+- `WOW_PROBE_UNCAP` — benilla-app/src/capture/mod.rs
+- `WOW_PROBE_VENDOR_SWAP` — benilla-app/src/dev.rs
+- `WOW_PROBE_VSYNC` — benilla-app/src/capture/mod.rs
+- `WOW_REALM` — benilla-app/src/realm_select/mod.rs
+- `WOW_REALM_SMOKE` — benilla-app/src/realm_select/smoke.rs
+- `WOW_REFUSE_LOGIN` — benilla-app/src/net/io.rs
+- `WOW_REMOTE_FLAT` — benilla-app/src/net/motion/remote.rs
+- `WOW_REMOTE_IDLE_GATE` — benilla-app/src/net/motion/remote.rs
+- `WOW_REMOTE_SNAP` — benilla-app/src/net/motion/remote.rs
+- `WOW_RENDER_SCALE` — benilla-app/src/cvars.rs, benilla-app/src/world_backdrop.rs
+- `WOW_RES_CENSUS` — benilla-app/src/perf/census.rs
+- `WOW_RESIZE` — benilla-app/src/capture/mod.rs
+- `WOW_REVEAL` — benilla-app/src/capture/probes/reveal.rs, benilla-app/src/dev.rs
+- `WOW_RIG` — benilla-app/src/capture/probe_rig.rs, benilla-app/src/dev.rs, benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/probe_shield.rs, benilla-app/src/realm_select/smoke.rs, benilla-app/src/run_mode.rs, benilla-world/src/bgwin.rs
+- `WOW_RIG_CENSUS` — benilla-world/src/rig_palette.rs
+- `WOW_RIG_COST` — benilla-world/src/rig_palette.rs
+- `WOW_RIG_SKIN` — benilla-assets/src/materials.rs
+- `WOW_ROW_BLOAT` — benilla-app/src/perf/census.rs, benilla-app/src/perf/mod.rs
+- `WOW_SCHED_CENSUS` — benilla-app/src/dev.rs, benilla-world/src/bgwin.rs
+- `WOW_SHADE_CENSUS` — benilla-world/src/entity_shade.rs
+- `WOW_SHOT_REQUIRE` — benilla-app/src/capture/live_shot.rs
+- `WOW_SHOT_REQUIRE_DIST` — benilla-app/src/capture/live_shot.rs
+- `WOW_SKY_DEPTH` — benilla-assets/src/materials.rs
+- `WOW_SOUND_PROBE` — benilla-app/src/sound/probe.rs
+- `WOW_STALL` — benilla-app/src/capture/probes/stall.rs, benilla-app/src/dev.rs
+- `WOW_STALL_INJECT` — benilla-app/src/perf/stall.rs
+- `WOW_STALL_SAMPLE` — benilla-app/src/perf/stall.rs
+- `WOW_STATIC_GX` — benilla-world/src/static_gx/mod.rs
+- `WOW_STATIC_GX_FADE` — benilla-world/src/static_gx/mod.rs
+- `WOW_STATIC_GX_PROP` — benilla-world/src/static_gx/mod.rs
+- `WOW_STATIC_GX_WMO` — benilla-world/src/static_gx/mod.rs
+- `WOW_STATIC_MERGE` — benilla-world/src/terrain_stream/merge.rs
+- `WOW_STREAM_TRACE` — benilla-app/src/perf/mod.rs
+- `WOW_TAB_TRACE` — benilla-app/src/target/scan.rs
+- `WOW_TABHOVER` — benilla-app/src/capture/fixtures.rs
+- `WOW_TEARDOWN_INJECT` — benilla-app/src/perf/stall.rs
+- `WOW_TEXT_PROBE` — benilla-app/src/ui_script/extract/text.rs
+- `WOW_THREADS` — benilla-world/src/boot.rs
+- `WOW_TILE_DUMP` — benilla-app/src/ui_models/mod.rs
+- `WOW_TILE_TRACE` — benilla-app/src/ui_models/mod.rs
+- `WOW_TILE_UNLOAD` — benilla-world/src/assets/mod.rs
+- `WOW_TINT_PROBE` — benilla-app/src/aura_visual.rs
+- `WOW_TRAIL_CENSUS` — benilla-app/src/capture/probes/trail_census.rs, benilla-app/src/dev.rs
+- `WOW_TRILINEAR` — benilla-app/src/cvars.rs, benilla-assets/src/tex_filter.rs
+- `WOW_TWIST_GAP` — benilla-app/src/player/body_pose.rs
+- `WOW_UI_COST` — benilla-app/src/ui_script/extract/mod.rs
+- `WOW_UI_DIFF` — benilla-app/src/ui_pass.rs, benilla-app/src/ui_script/extract/mod.rs
+- `WOW_UI_GATE` — benilla-app/src/ui_script/extract/mod.rs
+- `WOW_UI_HANDLERS` — benilla-ui/src/script/handler_prof.rs
+- `WOW_UI_PICK` — benilla-app/src/ui_script/extract/mod.rs
+- `WOW_UI_PROBE` — benilla-app/src/ui_pass.rs
+- `WOW_UI_SCALE` — benilla-app/src/cvars.rs, benilla-app/src/ui_script/mod.rs
+- `WOW_UI_SPLICE_VERIFY` — benilla-app/src/ui_script/extract/mod.rs
+- `WOW_UISCRIPT_DUMP` — benilla-app/tests/ui_script_wall.rs
+- `WOW_UNATTENDED` — benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/run_mode.rs, benilla-world/src/bgwin.rs
+- `WOW_UNIT_VISUALS` — benilla-app/src/capture/probes/visual_census.rs, benilla-app/src/dev.rs
+- `WOW_UNIT_VISUALS_RADIUS` — benilla-app/src/capture/probes/visual_census.rs
+- `WOW_UPLOAD_BUDGET` — benilla-world/src/world_plugins.rs
+- `WOW_USER` — benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/run_mode.rs
+- `WOW_VIS_DUMP` — benilla-app/src/capture/probes/live_fps.rs
+- `WOW_VIS_TRACE` — benilla-world/src/model_render/visibility.rs
+- `WOW_VISTA_AT` — benilla-app/src/capture/mod.rs
+- `WOW_VISTA_FACE` — benilla-app/src/capture/mod.rs
+- `WOW_VISTA_MIN` — benilla-app/src/capture/mod.rs
+- `WOW_VISTA_PITCH` — benilla-app/src/capture/mod.rs
+- `WOW_VPLATE_TRACE` — benilla-app/src/vplates.rs
+- `WOW_WARM_SLICE` — benilla-app/src/pipe_warm/mod.rs
+- `WOW_WATER_CLIP` — benilla-assets/src/materials.rs
+- `WOW_WAVE_DUMP` — benilla-world/src/ffx_glow.rs
+- `WOW_WEATHER` — benilla-world/src/weather/mod.rs
+- `WOW_WEATHER_DUMP` — benilla-world/src/weather/mod.rs
+- `WOW_WFX_AGE` — benilla-app/src/capture/mod.rs
+- `WOW_WFX_AT` — benilla-app/src/capture/mod.rs
+- `WOW_WFX_AZ` — benilla-app/src/capture/mod.rs
+- `WOW_WFX_DEPTH` — benilla-app/src/capture/mod.rs
+- `WOW_WFX_DIST` — benilla-app/src/capture/mod.rs
+- `WOW_WFX_EL` — benilla-app/src/capture/mod.rs
+- `WOW_WFX_HEAD` — benilla-app/src/capture/mod.rs
+- `WOW_WFX_MODE` — benilla-app/src/capture/mod.rs
+- `WOW_WFX_SPEED` — benilla-app/src/capture/mod.rs
+- `WOW_WIN` — benilla-app/src/video.rs, benilla-world/src/worldview.rs
+- `WOW_WMO_BIAS` — benilla-world/src/model_render.rs, benilla-world/src/static_gx/mod.rs
+- `WOW_WORLDVIEW_` — benilla-world/src/bgwin.rs
+- `WOW_WORLDVIEW_AT` — benilla-world/src/worldview.rs
+- `WOW_WORLDVIEW_CHECK` — benilla-world/src/bgwin.rs, benilla-world/src/worldview.rs
+- `WOW_WORLDVIEW_SHOT` — benilla-world/src/worldview.rs
+- `WOW_WORLDVIEW_SHOT_AT` — benilla-world/src/worldview.rs
+- `WOW_WORLDVIEW_SURVEY` — benilla-world/src/worldview.rs
+
+## Scripts (`scripts/`)
+
+- `doc-links.py` — Fail on a doc link whose target is declared nowhere in the workspace.
+- `gen-message-catalog.py` — Generate `crates/benilla-ui/src/messages/catalog.rs` from `reference/1.12-message-catalog.tsv`.
+- `gen-reference-events.py` — Regenerate `reference/1.12-events.tsv`: each 1.12 FrameScript event and the arguments it carries.
+- `gen-reference-globals.py` — Regenerate `reference/1.12-globals.tsv`: the 1.12.1 client's global namespace, by origin.
+- `gen-reference-verb-events.py` — Regenerate `reference/1.12-verb-events.tsv`: the events 1.12 Lua verbs fire, keyed by verb.
+- `mixsum.py` — Read a `$WOW_MIX_TAP` capture and say, in numbers, what the mix was doing when.
+- `pass-span-lint.py` — Refuse a second open `pass_span` on the same render pass (a wgpu validation error on Vulkan).
+- `soundprobe.py` — Read back a `$WOW_SOUND_PROBE` capture and name the mechanism behind a speaker-breaking sound.
+- `vplsum.py` — Read a `vpl`/`bub` overlay trace and say where the motion came from: projection, solve or snap.
+- `api-coverage.sh` — Addon-API coverage: how much of the 1.12.1 client's global surface benilla's UI VM presents.
+- `check.sh` — The in-loop verify: fmt everywhere, clippy and test on the changed crates and their dependents.
+- `cine.sh` — Play one cinematic on the probe and print what happened, as a timeline.
+- `gates.sh` — The land gate chain: every gate in order, stopping at the first failure.
+- `genmap.sh` — Generate docs/MAP.md, the map of what is built, from what is on disk.
+- `probe-identity.sh` — Who a scripted run logs in as; sourced by smoke.sh, cine.sh and summon-live.sh, never run alone.
+- `smoke.sh` — The clean-run gate: boot the real client, log out, re-enter, walk the realm list, check the log.
+- `soundprobe.sh` — Start the client in sound measuring mode: record the mix before and after the output limiter.
+- `summon-live.sh` — Two-client live summon probe: a second account summons this checkout's character, which accepts.
+- `visual.sh` — Visual A/B harness: capture deterministic screenshots and diff them against a baseline.
+
diff --git a/docs/METHOD.md b/docs/METHOD.md
new file mode 100644
index 00000000..fe8cd76c
--- /dev/null
+++ b/docs/METHOD.md
@@ -0,0 +1,102 @@
+# METHOD — how benilla is built
+
+benilla is a from-scratch World of Warcraft 1.12.1 client in Rust and Bevy. It reads the game's
+data from the player's own install, speaks the original protocol to any 1.12.1 server, and does
+not build a server or simulate the game. The reference client is the spec: benilla does what
+1.12.1 does, as a modern, idiomatic client.
+
+## The rule for every change
+
+A change is right when it makes benilla more like 1.12.1 or fixes a bug, with evidence from the
+reference, in one small piece, with the gates green. A deviation from the reference is the
+maintainer's call alone, and each one is written down where it lives: a CVar's `Deviates` row, a
+comment naming the reference fact and why we differ. Anything else is a fork.
+
+## The loop
+
+1. **The reference first.** For anything fidelity-defining, get the mechanism from the real
+   client before building: its behaviour, a DBC field, a FrameXML line, a packet capture. The
+   names and shapes under `reference/` are the surface benilla tracks.
+2. **Build it idiomatically.** Modern Bevy and Rust, performance woven in from the start.
+   Implement the mechanism well; do not ape a quirk that is a bug.
+3. **Measure, never eyeball.** Timing, delay, ordering and feel are settled with instruments:
+   trace timestamps, byte-derived numbers, a numeric probe. A capture confirms an existence
+   fact; it cannot measure time. Never search for a viewpoint: take the one simplest shot, and
+   if it does not settle the question, hand over a precise script ("log in, look at X, does Y?").
+4. **Close the loop on the symptom.** A bug reported as seen is closed by reproducing it at the
+   reported spot first, fixing, and showing the same instrument clean there plus one adjacent
+   state. Green gates and an existing mechanism are never that evidence.
+5. **Prove the run before reading the result.** A live result is evidence once the run is valid
+   from numbers: preflight banner clean, camera and body where intended, the subject in frame,
+   the window long enough. A negative from an unproven run is not evidence.
+6. **Commit small and often; land by pull request.** Atomic commits, explicit paths, on a
+   branch; main moves only by a squash-merged pull request, one commit per piece of work.
+   No "done" and no commit without saying what was verified and how the result was judged.
+
+## Hard rules
+
+- **Never commit anything from the install.** Art, models, sounds, maps, data: the install is
+  read at runtime from a gitignored path, and everyone provides their own. The one exception is
+  interface code: FrameXML and GlueXML run off the player's own patch chain, and our own
+  counterparts under `assets/ui` stay until they retire.
+- **The install is read-only.** benilla never writes into the WoW folder: no screenshot, log,
+  cache or scratch file. `scripts/smoke.sh` fails a run that leaves the install changed.
+- **Local state lives in one folder**, `benilla-config/` beside the binary, and every path to
+  it resolves through `crate::local_state`. Player settings are CVars persisted as a diff in
+  `benilla-config/config.toml`.
+- **UI is stock-first: a window is migrated, not authored.** The end state is the stock 1.12
+  FrameXML executed off the player's own chain. `assets/ui` does not grow: a test names its
+  files and fails on a new one. A window is built by pointing `benilla.toc` at the stock file,
+  deleting ours and building the engine verbs it calls, never stubbing one to make the file
+  load.
+- **A setting's default is the reference's default.** Every option boots at the stock 1.12
+  value. Shipping another value costs an explicit `Deviates` row with the reason, and a test
+  fails a row that drifts either way.
+- **Our code is MIT OR Apache-2.0**, which is a claim about provenance: no original client
+  code, no bundled assets.
+
+## Where things live
+
+- `docs/METHOD.md`, this file: rules and method. Never state, never a log.
+- `docs/MAP.md`: what is built, generated from the code by `scripts/genmap.sh` at every land.
+  Read it to orient; never edit or commit it by hand.
+- git: the history. No changelogs, no status docs, no "what we did" narratives.
+- The code: a comment says what the code does and the 1.12 fact behind it, in a line. No
+  history, no stories.
+
+## Gates
+
+- **The land gates**: `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets
+  -- -D warnings`, `cargo test --workspace`, the doc-link and render-pass lints, the player
+  build without the `dev` feature with its own tests, and the engine boot checks, as
+  `scripts/gates.sh`. It runs on the tree that lands, before it lands; it is memoized on the
+  tree. The tests that read the install or the addon corpus skip where the data is absent, and
+  the gate prints the count; where the data is, a skip is a failure (`BENILLA_REQUIRE_DATA=1`).
+  The workspace tests then run a second time with `WOW_DATA=` (no install), so a test that
+  reads the install without opening with `wow_data_or_skip!` fails here and not on a clone.
+- **Per round**: `scripts/check.sh`, scoped to the changed crates and their dependents. Run each
+  gate once per round; `tee` the output to a file and grep the file.
+- **A clean run** is the fourth gate: `scripts/smoke.sh`, a live login and logout against the
+  local server. For wire work the gate is a live run with a trace (`WOW_MOVE_TRACE=<path>`,
+  tags filtered), never a capture: capture mode has no network.
+- **Platform seams**: a `cfg(target_os)`, a `[target.'cfg(…)']` dependency, a `#[link]` or an
+  `extern "system"` is invisible to the gates of the platform you are on. Say in the commit
+  which platforms you built.
+
+## The local server
+
+benilla talks to any 1.12.1 server: `WOW_HOST` names it (default `localhost`), `WOW_USER` and
+`WOW_PASS` together log in without typing, `WOW_CHAR` picks the character. There is no default
+account. These bind every session and every agent:
+
+- A scripted run logs in as the account its checkout declares in `.probe-identity` (the three
+  variables, one per line, never committed), or as the three variables name; never as a
+  player's, because a login kicks whoever holds the account, and the client refuses a scripted
+  login from a checkout on any account but the declared one.
+- Every unattended run says so: `WOW_UNATTENDED=1`. An agent's run is silent: `WOW_NOSOUND=1`.
+- No unattended combat probes.
+- Anything about hostility, reaction colour, nameplates, threat, damage or breath runs with
+  `WOW_GM=off`.
+- Read the preflight banner before debugging anything else.
+
+The switches for such a run are `docs/CONTRIBUTING.md`, "Running it unattended".
diff --git a/reference/1.12-event-catalog.tsv b/reference/1.12-event-catalog.tsv
new file mode 100644
index 00000000..f5030486
--- /dev/null
+++ b/reference/1.12-event-catalog.tsv
@@ -0,0 +1,427 @@
+# FrameScript C->Lua event catalog of the 1.12.1 client (WoW.exe build 5875): eventId -> name.
+# Source: the event-name pointer array at .data 0xbe1198 (stride 4, 0x225 = 549 slots), passed
+#   at 0x48fea1-0x48feab (`mov edx,0x225; mov ecx,0xbe1198; call 0x703d90`). 0x703d90 builds the
+#   runtime 16-byte-stride dispatch table [0xceef68] as table[i].name = strdup(nameArray[i])
+#   (0x703e06-0x703e2e), so the id passed to FrameScript_SignalEvent 0x703e50 / 0x703f50 is
+#   this index.
+# Slots 0..15 carry no `mov imm32` name write in this scan (they are set from a register at
+#   0x51acbf and neighbours).
+0	UNIT_PET
+2	UNIT_PET
+16	UNIT_HEALTH
+17	UNIT_MANA
+18	UNIT_RAGE
+19	UNIT_FOCUS
+20	UNIT_ENERGY
+21	UNIT_HAPPINESS
+22	UNIT_MAXHEALTH
+23	UNIT_MAXMANA
+24	UNIT_MAXRAGE
+25	UNIT_MAXFOCUS
+26	UNIT_MAXENERGY
+27	UNIT_MAXHAPPINESS
+28	UNIT_LEVEL
+29	UNIT_FACTION
+30	UNIT_DISPLAYPOWER
+40	UNIT_FLAGS
+41	UNIT_AURA
+107	UNIT_AURA
+120	UNIT_ATTACK_SPEED
+121	UNIT_ATTACK_SPEED
+122	UNIT_RANGEDDAMAGE
+128	UNIT_DAMAGE
+129	UNIT_DAMAGE
+130	UNIT_DAMAGE
+131	UNIT_DAMAGE
+132	UNIT_LOYALTY
+135	UNIT_PET_EXPERIENCE
+136	UNIT_PET_EXPERIENCE
+137	UNIT_DYNAMIC_FLAGS
+143	UNIT_PET_TRAINING_POINTS
+144	UNIT_STATS
+145	UNIT_STATS
+146	UNIT_STATS
+147	UNIT_STATS
+148	UNIT_STATS
+149	UNIT_RESISTANCES
+150	UNIT_RESISTANCES
+151	UNIT_RESISTANCES
+152	UNIT_RESISTANCES
+153	UNIT_RESISTANCES
+154	UNIT_RESISTANCES
+155	UNIT_RESISTANCES
+159	UNIT_ATTACK_POWER
+160	UNIT_ATTACK_POWER
+161	UNIT_ATTACK_POWER
+162	UNIT_RANGED_ATTACK_POWER
+163	UNIT_RANGED_ATTACK_POWER
+164	UNIT_RANGED_ATTACK_POWER
+165	UNIT_RANGEDDAMAGE
+166	UNIT_RANGEDDAMAGE
+167	UNIT_MANA
+174	UNIT_MANA
+182	UNIT_COMBAT
+183	UNIT_NAME_UPDATE
+184	UNIT_PORTRAIT_UPDATE
+185	UNIT_MODEL_CHANGED
+186	UNIT_INVENTORY_CHANGED
+187	UNIT_CLASSIFICATION_CHANGED
+188	ITEM_LOCK_CHANGED
+189	PLAYER_XP_UPDATE
+190	PLAYER_REGEN_DISABLED
+191	PLAYER_REGEN_ENABLED
+192	PLAYER_AURAS_CHANGED
+193	PLAYER_ENTER_COMBAT
+194	PLAYER_LEAVE_COMBAT
+195	PLAYER_TARGET_CHANGED
+196	PLAYER_CONTROL_LOST
+197	PLAYER_CONTROL_GAINED
+198	PLAYER_FARSIGHT_FOCUS_CHANGED
+199	PLAYER_LEVEL_UP
+200	PLAYER_MONEY
+201	PLAYER_DAMAGE_DONE_MODS
+202	PLAYER_COMBO_POINTS
+203	ZONE_CHANGED
+204	ZONE_CHANGED_INDOORS
+205	ZONE_CHANGED_NEW_AREA
+206	MINIMAP_ZONE_CHANGED
+207	MINIMAP_UPDATE_ZOOM
+208	SCREENSHOT_SUCCEEDED
+209	SCREENSHOT_FAILED
+210	ACTIONBAR_SHOWGRID
+211	ACTIONBAR_HIDEGRID
+212	ACTIONBAR_PAGE_CHANGED
+213	ACTIONBAR_SLOT_CHANGED
+214	ACTIONBAR_UPDATE_STATE
+215	ACTIONBAR_UPDATE_USABLE
+216	ACTIONBAR_UPDATE_COOLDOWN
+217	UPDATE_BONUS_ACTIONBAR
+218	PARTY_MEMBERS_CHANGED
+219	PARTY_LEADER_CHANGED
+220	PARTY_MEMBER_ENABLE
+221	PARTY_MEMBER_DISABLE
+222	PARTY_LOOT_METHOD_CHANGED
+223	SYSMSG
+224	UI_ERROR_MESSAGE
+225	UI_INFO_MESSAGE
+226	UPDATE_CHAT_COLOR
+227	CHAT_MSG_ADDON
+228	CHAT_MSG_SAY
+229	CHAT_MSG_PARTY
+230	CHAT_MSG_RAID
+231	CHAT_MSG_GUILD
+232	CHAT_MSG_OFFICER
+233	CHAT_MSG_YELL
+234	CHAT_MSG_WHISPER
+235	CHAT_MSG_WHISPER_INFORM
+236	CHAT_MSG_EMOTE
+237	CHAT_MSG_TEXT_EMOTE
+238	CHAT_MSG_SYSTEM
+239	CHAT_MSG_MONSTER_SAY
+240	CHAT_MSG_MONSTER_YELL
+241	CHAT_MSG_MONSTER_WHISPER
+242	CHAT_MSG_MONSTER_EMOTE
+243	CHAT_MSG_CHANNEL
+244	CHAT_MSG_CHANNEL_JOIN
+245	CHAT_MSG_CHANNEL_LEAVE
+246	CHAT_MSG_CHANNEL_LIST
+247	CHAT_MSG_CHANNEL_NOTICE
+248	CHAT_MSG_CHANNEL_NOTICE_USER
+249	CHAT_MSG_AFK
+250	CHAT_MSG_DND
+251	CHAT_MSG_COMBAT_LOG
+252	CHAT_MSG_IGNORED
+253	CHAT_MSG_SKILL
+254	CHAT_MSG_LOOT
+255	CHAT_MSG_MONEY
+256	CHAT_MSG_RAID_LEADER
+257	CHAT_MSG_RAID_WARNING
+258	LANGUAGE_LIST_CHANGED
+259	TIME_PLAYED_MSG
+260	SPELLS_CHANGED
+261	CURRENT_SPELL_CAST_CHANGED
+262	SPELL_UPDATE_COOLDOWN
+263	SPELL_UPDATE_USABLE
+264	CHARACTER_POINTS_CHANGED
+265	SKILL_LINES_CHANGED
+266	ITEM_PUSH
+267	LOOT_OPENED
+268	LOOT_SLOT_CLEARED
+269	LOOT_CLOSED
+270	PLAYER_LOGIN
+271	PLAYER_LOGOUT
+272	PLAYER_ENTERING_WORLD
+273	PLAYER_LEAVING_WORLD
+274	PLAYER_ALIVE
+275	PLAYER_DEAD
+276	PLAYER_CAMPING
+277	PLAYER_QUITING
+278	LOGOUT_CANCEL
+279	RESURRECT_REQUEST
+280	PARTY_INVITE_REQUEST
+281	PARTY_INVITE_CANCEL
+282	GUILD_INVITE_REQUEST
+283	GUILD_INVITE_CANCEL
+284	GUILD_MOTD
+285	TRADE_REQUEST
+286	TRADE_REQUEST_CANCEL
+287	LOOT_BIND_CONFIRM
+288	EQUIP_BIND_CONFIRM
+289	AUTOEQUIP_BIND_CONFIRM
+290	USE_BIND_CONFIRM
+291	DELETE_ITEM_CONFIRM
+292	CURSOR_UPDATE
+293	ITEM_TEXT_BEGIN
+294	ITEM_TEXT_TRANSLATION
+295	ITEM_TEXT_READY
+296	ITEM_TEXT_CLOSED
+297	GOSSIP_SHOW
+298	GOSSIP_ENTER_CODE
+299	GOSSIP_CLOSED
+300	QUEST_GREETING
+301	QUEST_DETAIL
+302	QUEST_PROGRESS
+303	QUEST_COMPLETE
+304	QUEST_FINISHED
+305	QUEST_ITEM_UPDATE
+306	TAXIMAP_OPENED
+307	TAXIMAP_CLOSED
+308	QUEST_LOG_UPDATE
+309	TRAINER_SHOW
+310	TRAINER_UPDATE
+311	TRAINER_CLOSED
+312	CVAR_UPDATE
+313	TRADE_SKILL_SHOW
+314	TRADE_SKILL_UPDATE
+315	TRADE_SKILL_CLOSE
+316	MERCHANT_SHOW
+317	MERCHANT_UPDATE
+318	MERCHANT_CLOSED
+319	TRADE_SHOW
+320	TRADE_CLOSED
+321	TRADE_UPDATE
+322	TRADE_ACCEPT_UPDATE
+323	TRADE_TARGET_ITEM_CHANGED
+324	TRADE_PLAYER_ITEM_CHANGED
+325	TRADE_MONEY_CHANGED
+326	PLAYER_TRADE_MONEY
+327	BAG_OPEN
+328	BAG_UPDATE
+329	BAG_CLOSED
+330	BAG_UPDATE_COOLDOWN
+331	LOCALPLAYER_PET_RENAMED
+332	UNIT_ATTACK
+333	UNIT_DEFENSE
+334	PET_ATTACK_START
+335	PET_ATTACK_STOP
+336	UPDATE_MOUSEOVER_UNIT
+337	SPELLCAST_START
+338	SPELLCAST_STOP
+339	SPELLCAST_FAILED
+340	SPELLCAST_INTERRUPTED
+341	SPELLCAST_DELAYED
+342	SPELLCAST_CHANNEL_START
+343	SPELLCAST_CHANNEL_UPDATE
+344	SPELLCAST_CHANNEL_STOP
+345	PLAYER_GUILD_UPDATE
+346	QUEST_ACCEPT_CONFIRM
+347	PLAYERBANKSLOTS_CHANGED
+348	BANKFRAME_OPENED
+349	BANKFRAME_CLOSED
+350	PLAYERBANKBAGSLOTS_CHANGED
+351	FRIENDLIST_UPDATE
+352	IGNORELIST_UPDATE
+353	PET_BAR_UPDATE
+354	PET_BAR_UPDATE_COOLDOWN
+355	PET_BAR_SHOWGRID
+356	PET_BAR_HIDEGRID
+357	MINIMAP_PING
+358	CHAT_MSG_COMBAT_MISC_INFO
+359	CRAFT_SHOW
+360	CRAFT_UPDATE
+361	CRAFT_CLOSE
+362	MIRROR_TIMER_START
+363	MIRROR_TIMER_PAUSE
+364	MIRROR_TIMER_STOP
+365	WORLD_MAP_UPDATE
+366	WORLD_MAP_NAME_UPDATE
+367	AUTOFOLLOW_BEGIN
+368	AUTOFOLLOW_END
+370	CINEMATIC_START
+371	CINEMATIC_STOP
+372	UPDATE_FACTION
+373	CLOSE_WORLD_MAP
+374	OPEN_TABARD_FRAME
+375	CLOSE_TABARD_FRAME
+376	TABARD_CANSAVE_CHANGED
+377	SHOW_COMPARE_TOOLTIP
+378	GUILD_REGISTRAR_SHOW
+379	GUILD_REGISTRAR_CLOSED
+380	DUEL_REQUESTED
+381	DUEL_OUTOFBOUNDS
+382	DUEL_INBOUNDS
+383	DUEL_FINISHED
+384	TUTORIAL_TRIGGER
+385	PET_DISMISS_START
+386	UPDATE_BINDINGS
+387	UPDATE_SHAPESHIFT_FORMS
+388	WHO_LIST_UPDATE
+389	UPDATE_LFG
+390	PETITION_SHOW
+391	PETITION_CLOSED
+392	EXECUTE_CHAT_LINE
+393	UPDATE_MACROS
+394	UPDATE_TICKET
+395	UPDATE_CHAT_WINDOWS
+396	CONFIRM_XP_LOSS
+397	CORPSE_IN_RANGE
+398	CORPSE_IN_INSTANCE
+399	CORPSE_OUT_OF_RANGE
+400	UPDATE_GM_STATUS
+401	PLAYER_UNGHOST
+402	BIND_ENCHANT
+403	REPLACE_ENCHANT
+404	TRADE_REPLACE_ENCHANT
+405	PLAYER_UPDATE_RESTING
+406	UPDATE_EXHAUSTION
+407	PLAYER_FLAGS_CHANGED
+408	GUILD_ROSTER_UPDATE
+409	GM_PLAYER_INFO
+410	MAIL_SHOW
+411	MAIL_CLOSED
+412	SEND_MAIL_MONEY_CHANGED
+413	SEND_MAIL_COD_CHANGED
+414	MAIL_SEND_INFO_UPDATE
+415	MAIL_SEND_SUCCESS
+416	MAIL_INBOX_UPDATE
+417	BATTLEFIELDS_SHOW
+418	BATTLEFIELDS_CLOSED
+419	UPDATE_BATTLEFIELD_STATUS
+420	UPDATE_BATTLEFIELD_SCORE
+421	AUCTION_HOUSE_SHOW
+422	AUCTION_HOUSE_CLOSED
+423	NEW_AUCTION_UPDATE
+424	AUCTION_ITEM_LIST_UPDATE
+425	AUCTION_OWNED_LIST_UPDATE
+426	AUCTION_BIDDER_LIST_UPDATE
+427	PET_UI_UPDATE
+428	PET_UI_CLOSE
+429	ADDON_LOADED
+430	VARIABLES_LOADED
+431	MACRO_ACTION_FORBIDDEN
+432	ADDON_ACTION_FORBIDDEN
+433	MEMORY_EXHAUSTED
+434	MEMORY_RECOVERED
+435	START_AUTOREPEAT_SPELL
+436	STOP_AUTOREPEAT_SPELL
+437	PET_STABLE_SHOW
+438	PET_STABLE_UPDATE
+439	PET_STABLE_UPDATE_PAPERDOLL
+440	PET_STABLE_CLOSED
+441	CHAT_MSG_COMBAT_SELF_HITS
+442	CHAT_MSG_COMBAT_SELF_MISSES
+443	CHAT_MSG_COMBAT_PET_HITS
+444	CHAT_MSG_COMBAT_PET_MISSES
+445	CHAT_MSG_COMBAT_PARTY_HITS
+446	CHAT_MSG_COMBAT_PARTY_MISSES
+447	CHAT_MSG_COMBAT_FRIENDLYPLAYER_HITS
+448	CHAT_MSG_COMBAT_FRIENDLYPLAYER_MISSES
+449	CHAT_MSG_COMBAT_HOSTILEPLAYER_HITS
+450	CHAT_MSG_COMBAT_HOSTILEPLAYER_MISSES
+451	CHAT_MSG_COMBAT_CREATURE_VS_SELF_HITS
+452	CHAT_MSG_COMBAT_CREATURE_VS_SELF_MISSES
+453	CHAT_MSG_COMBAT_CREATURE_VS_PARTY_HITS
+454	CHAT_MSG_COMBAT_CREATURE_VS_PARTY_MISSES
+455	CHAT_MSG_COMBAT_CREATURE_VS_CREATURE_HITS
+456	CHAT_MSG_COMBAT_CREATURE_VS_CREATURE_MISSES
+457	CHAT_MSG_COMBAT_FRIENDLY_DEATH
+458	CHAT_MSG_COMBAT_HOSTILE_DEATH
+459	CHAT_MSG_COMBAT_XP_GAIN
+460	CHAT_MSG_COMBAT_HONOR_GAIN
+461	CHAT_MSG_SPELL_SELF_DAMAGE
+462	CHAT_MSG_SPELL_SELF_BUFF
+463	CHAT_MSG_SPELL_PET_DAMAGE
+464	CHAT_MSG_SPELL_PET_BUFF
+465	CHAT_MSG_SPELL_PARTY_DAMAGE
+466	CHAT_MSG_SPELL_PARTY_BUFF
+467	CHAT_MSG_SPELL_FRIENDLYPLAYER_DAMAGE
+468	CHAT_MSG_SPELL_FRIENDLYPLAYER_BUFF
+469	CHAT_MSG_SPELL_HOSTILEPLAYER_DAMAGE
+470	CHAT_MSG_SPELL_HOSTILEPLAYER_BUFF
+471	CHAT_MSG_SPELL_CREATURE_VS_SELF_DAMAGE
+472	CHAT_MSG_SPELL_CREATURE_VS_SELF_BUFF
+473	CHAT_MSG_SPELL_CREATURE_VS_PARTY_DAMAGE
+474	CHAT_MSG_SPELL_CREATURE_VS_PARTY_BUFF
+475	CHAT_MSG_SPELL_CREATURE_VS_CREATURE_DAMAGE
+476	CHAT_MSG_SPELL_CREATURE_VS_CREATURE_BUFF
+477	CHAT_MSG_SPELL_TRADESKILLS
+478	CHAT_MSG_SPELL_DAMAGESHIELDS_ON_SELF
+479	CHAT_MSG_SPELL_DAMAGESHIELDS_ON_OTHERS
+480	CHAT_MSG_SPELL_AURA_GONE_SELF
+481	CHAT_MSG_SPELL_AURA_GONE_PARTY
+482	CHAT_MSG_SPELL_AURA_GONE_OTHER
+483	CHAT_MSG_SPELL_ITEM_ENCHANTMENTS
+484	CHAT_MSG_SPELL_BREAK_AURA
+485	CHAT_MSG_SPELL_PERIODIC_SELF_DAMAGE
+486	CHAT_MSG_SPELL_PERIODIC_SELF_BUFFS
+487	CHAT_MSG_SPELL_PERIODIC_PARTY_DAMAGE
+488	CHAT_MSG_SPELL_PERIODIC_PARTY_BUFFS
+489	CHAT_MSG_SPELL_PERIODIC_FRIENDLYPLAYER_DAMAGE
+490	CHAT_MSG_SPELL_PERIODIC_FRIENDLYPLAYER_BUFFS
+491	CHAT_MSG_SPELL_PERIODIC_HOSTILEPLAYER_DAMAGE
+492	CHAT_MSG_SPELL_PERIODIC_HOSTILEPLAYER_BUFFS
+493	CHAT_MSG_SPELL_PERIODIC_CREATURE_DAMAGE
+494	CHAT_MSG_SPELL_PERIODIC_CREATURE_BUFFS
+495	CHAT_MSG_SPELL_FAILED_LOCALPLAYER
+496	CHAT_MSG_BG_SYSTEM_NEUTRAL
+497	CHAT_MSG_BG_SYSTEM_ALLIANCE
+498	CHAT_MSG_BG_SYSTEM_HORDE
+499	RAID_ROSTER_UPDATE
+500	UPDATE_PENDING_MAIL
+501	UPDATE_INVENTORY_ALERTS
+502	UPDATE_TRADESKILL_RECAST
+503	OPEN_MASTER_LOOT_LIST
+504	UPDATE_MASTER_LOOT_LIST
+505	START_LOOT_ROLL
+506	CANCEL_LOOT_ROLL
+507	CONFIRM_LOOT_ROLL
+508	INSTANCE_BOOT_START
+509	INSTANCE_BOOT_STOP
+510	LEARNED_SPELL_IN_TAB
+511	DISPLAY_SIZE_CHANGED
+512	CONFIRM_TALENT_WIPE
+513	CONFIRM_BINDER
+514	MAIL_FAILED
+515	CLOSE_INBOX_ITEM
+516	CONFIRM_SUMMON
+517	BILLING_NAG_DIALOG
+518	IGR_BILLING_NAG_DIALOG
+519	MEETINGSTONE_CHANGED
+520	PLAYER_SKINNED
+521	TABARD_SAVE_PENDING
+522	UNIT_QUEST_LOG_CHANGED
+523	PLAYER_PVP_KILLS_CHANGED
+524	PLAYER_PVP_RANK_CHANGED
+525	INSPECT_HONOR_UPDATE
+526	UPDATE_WORLD_STATES
+527	AREA_SPIRIT_HEALER_IN_RANGE
+528	AREA_SPIRIT_HEALER_OUT_OF_RANGE
+529	CONFIRM_PET_UNLEARN
+530	PLAYTIME_CHANGED
+531	UPDATE_LFG_TYPES
+532	UPDATE_LFG_LIST
+533	CHAT_MSG_COMBAT_FACTION_CHANGE
+534	START_MINIGAME
+535	MINIGAME_UPDATE
+536	READY_CHECK
+537	RAID_TARGET_UPDATE
+538	GMSURVEY_DISPLAY
+539	UPDATE_INSTANCE_INFO
+541	CHAT_MSG_RAID_BOSS_EMOTE
+542	COMBAT_TEXT_UPDATE
+543	LOTTERY_SHOW
+544	CHAT_MSG_FILTERED
+545	QUEST_WATCH_UPDATE
+546	CHAT_MSG_BATTLEGROUND
+547	CHAT_MSG_BATTLEGROUND_LEADER
+548	LOTTERY_ITEM_UPDATE
diff --git a/reference/1.12-event-firesites.tsv b/reference/1.12-event-firesites.tsv
new file mode 100644
index 00000000..9542b0b8
--- /dev/null
+++ b/reference/1.12-event-firesites.tsv
@@ -0,0 +1,522 @@
+# C->Lua event fire sites of the 1.12.1 client (build 5875): every call and tail-jmp to
+# FrameScript_SignalEvent (0x703e50, ecx=eventId) and SignalEvent2 (0x703f50, [esp]=eventId +
+# printf-style arg_format). eventId is resolved via 1.12-event-catalog.tsv; "dyn" = computed
+# (e.g. a UnitField update loop); a blank name = the id has no entry in the name table.
+#
+# arg_format is the format string the site pushes: a declaration, not a census of what the
+# caller pushed. The marshaller 0x704f10 consumes one vararg per directive (%f eight bytes,
+# everything else four), so a format that declares more than its caller pushed hands Lua
+# undefined values. Of the 149 SignalEvent2 sites exactly three do: 0x496230
+# TRADE_REPLACE_ENCHANT "%s%s%d" declares 3 and pushes 2; 0x5e4527 and 0x5e7960 UPDATE_TICKET
+# "%d%s%f%f%f%d%d" declare 10 dwords and push 7 (their sibling 0x5e45e2 pushes the full 12).
+# Every other site's format matches its caller.
+#
+# The name column resolves every id through the in-game table (0xbe1198, 549 entries). 0x703d90
+# is called twice with different populations, 0x46a88f with (0xb41e70, 26) for the glue phase
+# and 0x48feab with (0xbe1198, 549) for the world, and rebuilds [0xceef68] wholesale from
+# whichever it is handed, so the same integer names a different event in the two phases, and
+# 0x703e50 bounds-checks nothing. 22 rows here sit in a `Source\Glue\` TU (0x46aa34;
+# 0x46bc9d-0x46c52e inside 0x46b930; 0x46e73d; 0x47461e): their ids belong to the glue space and
+# are never named from 1.12-event-catalog.tsv; their names are blank here. 0x46aa34 fires id 22,
+# which is FRAMES_LOADED in the glue table (GlueParent.lua:94), not the in-game UNIT_MAXHEALTH.
+#
+# An event with no row here is not an event with no producer. This covers the two signal
+# helpers' own call/jmp sites, and the per-field UNIT_* family reaches them through a wrapper:
+# 0x515e50(&guid, id) fans out over the unit tokens and fires 0x703f50(id, "%s", token) at
+# 0x515e7a, the "?" row below. Its 38 callers carry the id in edx; one of them, 0x51bd5b in the
+# UpdateField watch callback 0x51bd50, computes it as (registered field byte offset >> 2), so
+# ids 0x00-0xb5 (every named unit descriptor field, UNIT_FLAGS 40 included) are produced there
+# and appear nowhere in this file. 0x51bd50 is the sole producer of 40; its fire condition is a
+# repe cmpsb of the watched span against the object's shadow, at 0x4655bb. Most other
+# 0x515e50 sites carry a literal id in edx, absent here too at any magnitude: {0x10 0x16 0x1c
+# 0x1d 0x1e 0x29 0xb7 0xb8 0xb9 0xba 0xbb 0x159 0x197 0x20a}. So 0x197 = 407
+# PLAYER_FLAGS_CHANGED (0x5eea35 mov edx,0x197 / 0x5eea3d call 0x515e50, inside the
+# PLAYER_FLAGS delta handler 0x5ee990) lies outside 0x00-0xb5 and still has a producer. Same
+# shape for 0x5de4b0 (id = its userdata, arg1 hardcoded "player") and 0x49b199 (id from the
+# table at 0x8062e0).
+fire_site_va	dispatcher	eventId	name	arg_format
+0x4018df	SignalEvent2	259	TIME_PLAYED_MSG	%d%d
+0x46aa34	SignalEvent	22		
+0x46b04d	SignalEvent2	3		%s
+0x46b0ac	SignalEvent2	3		%s%s
+0x46b0d2	SignalEvent2	3		%s
+0x46b1a4	SignalEvent2	3		%s%s
+0x46b1e7	SignalEvent2	3		%s%s
+0x46b26c	SignalEvent2	3		%s%s
+0x46b2c4	SignalEvent2	3		%s%s
+0x46b31e	SignalEvent2	3		%s%s
+0x46b388	SignalEvent2	23	UNIT_MAXMANA	%s
+0x46b3c0	SignalEvent2	3		%s%s
+0x46b48b	SignalEvent	5		
+0x46b4a8	SignalEvent2	23	UNIT_MAXMANA	%s
+0x46b4cd	SignalEvent2	23	UNIT_MAXMANA	%s
+0x46b5a5	SignalEvent2	3		%s%s
+0x46b5c2	SignalEvent2	23	UNIT_MAXMANA	%s
+0x46b848	SignalEvent2	0	UNIT_PET	%s
+0x46b8af	SignalEvent2	3		%s%s
+0x46b8fa	SignalEvent2	3		%s%s
+0x46b964	SignalEvent2	21	UNIT_HAPPINESS	%s
+0x46bac8	SignalEvent	5		
+0x46bb15	SignalEvent2	25	UNIT_MAXFOCUS	%d%d%d%d%d%d%d%d%d%d
+0x46bc9d	SignalEvent2	3		%s%s
+0x46bdfc	SignalEvent2	4		%s%s
+0x46be81	SignalEvent2	4		%s%s
+0x46be96	SignalEvent2	4		%s
+0x46bee7	SignalEvent2	3		%s%s
+0x46bf6f	SignalEvent2	3		%s%s%s
+0x46bf91	SignalEvent	5		
+0x46c04a	SignalEvent2	4		%s
+0x46c08f	SignalEvent	5		
+0x46c0b4	SignalEvent2	?		%s
+0x46c0dd	SignalEvent	5		
+0x46c103	SignalEvent2	4		%s
+0x46c129	SignalEvent	5		
+0x46c133	SignalEvent	12		
+0x46c15e	SignalEvent2	4		%s
+0x46c183	SignalEvent2	3		%s%s
+0x46c1a2	SignalEvent	13		
+0x46c298	SignalEvent2	3		%s%s
+0x46c52e	SignalEvent	15		
+0x46c5b0	SignalEvent2	3		%s%s
+0x46c62e	SignalEvent	2	UNIT_PET	
+0x46c68f	SignalEvent2	3		%s%s
+0x46e73d	SignalEvent	9		
+0x46e9cb	SignalEvent	9		
+0x46ea1a	SignalEvent	9		
+0x46eb44	SignalEvent2	18	UNIT_RAGE	%d%d
+0x46ec26	SignalEvent	9		
+0x46ec42	SignalEvent2	18	UNIT_RAGE	%d%d
+0x47120c	SignalEvent2	3		%s%s
+0x47256d	SignalEvent	7		
+0x4725e1	SignalEvent	7		
+0x472732	SignalEvent	7		
+0x47276c	SignalEvent2	8		%d
+0x4735d2	SignalEvent2	23	UNIT_MAXMANA	%s
+0x47461e	SignalEvent	5		
+0x474b39	SignalEvent2	3		%s%s
+0x474b94	SignalEvent	17	UNIT_MANA	
+0x474c81	SignalEvent	16	UNIT_HEALTH	
+0x474cb3	SignalEvent2	3		%s%s
+0x488cd5	SignalEvent2	312	CVAR_UPDATE	%s%s
+0x48edda	SignalEvent	370	CINEMATIC_START	
+0x48f095	SignalEvent	371	CINEMATIC_STOP	
+0x48f3eb	SignalEvent2	279	RESURRECT_REQUEST	%s
+0x48f412	SignalEvent2	520	PLAYER_SKINNED	%d
+0x48f42b	SignalEvent2	280	PARTY_INVITE_REQUEST	%s
+0x48f445	SignalEvent	281	PARTY_INVITE_CANCEL	
+0x48f45c	SignalEvent2	282	GUILD_INVITE_REQUEST	%s%s
+0x48f475	SignalEvent	283	GUILD_INVITE_CANCEL	
+0x48fa17	SignalEvent	526	UPDATE_WORLD_STATES	
+0x490959	SignalEvent	270	PLAYER_LOGIN	
+0x49096a	SignalEvent	272	PLAYER_ENTERING_WORLD	
+0x490b4d	SignalEvent	273	PLAYER_LEAVING_WORLD	
+0x490b77	SignalEvent	371	CINEMATIC_STOP	
+0x490c2a	SignalEvent	271	PLAYER_LOGOUT	
+0x49156a	SignalEvent	430	VARIABLES_LOADED	
+0x491be8	SignalEvent2	266	ITEM_PUSH	%d%s
+0x49211a	SignalEvent	dyn		
+0x492124	SignalEvent	399	CORPSE_OUT_OF_RANGE	
+0x4922d1	SignalEvent	527	AREA_SPIRIT_HEALER_IN_RANGE	
+0x4929b3	SignalEvent	336	UPDATE_MOUSEOVER_UNIT	
+0x492f5c	SignalEvent	511	DISPLAY_SIZE_CHANGED	
+0x4930c7	SignalEvent	209	SCREENSHOT_FAILED	
+0x49389c	SignalEvent	195	PLAYER_TARGET_CHANGED	
+0x493a73	SignalEvent	195	PLAYER_TARGET_CHANGED	
+0x4945ca	SignalEvent2	?		%s
+0x49468b	SignalEvent2	182	UNIT_COMBAT	%s%s%s%d%d
+0x49493f	SignalEvent	205	ZONE_CHANGED_NEW_AREA	
+0x49495f	SignalEvent	?		
+0x4949cb	SignalEvent	206	MINIMAP_ZONE_CHANGED	
+0x4949e7	SignalEvent	206	MINIMAP_ZONE_CHANGED	
+0x494add	SignalEvent	431	MACRO_ACTION_FORBIDDEN	
+0x494afb	SignalEvent2	432	ADDON_ACTION_FORBIDDEN	%s
+0x494c54	SignalEvent	292	CURSOR_UPDATE	
+0x494d10	SignalEvent	200	PLAYER_MONEY	
+0x49515e	SignalEvent	292	CURSOR_UPDATE	
+0x495248	SignalEvent	200	PLAYER_MONEY	
+0x4952cc	SignalEvent	292	CURSOR_UPDATE	
+0x4953c0	SignalEvent2	291	DELETE_ITEM_CONFIRM	%s%d
+0x495415	SignalEvent	188	ITEM_LOCK_CHANGED	
+0x495455	SignalEvent	188	ITEM_LOCK_CHANGED	
+0x49557d	SignalEvent	188	ITEM_LOCK_CHANGED	
+0x49563d	SignalEvent2	433	MEMORY_EXHAUSTED	%d
+0x495656	SignalEvent	434	MEMORY_RECOVERED	
+0x4956e9	SignalEvent	518	IGR_BILLING_NAG_DIALOG	
+0x495700	SignalEvent2	517	BILLING_NAG_DIALOG	%d
+0x495741	SignalEvent	518	IGR_BILLING_NAG_DIALOG	
+0x49581e	SignalEvent2	517	BILLING_NAG_DIALOG	%d
+0x49587d	SignalEvent	275	PLAYER_DEAD	
+0x495893	SignalEvent	274	PLAYER_ALIVE	
+0x4958f7	SignalEvent	197	PLAYER_CONTROL_GAINED	
+0x49590b	SignalEvent	196	PLAYER_CONTROL_LOST	
+0x4960a3	SignalEvent	402	BIND_ENCHANT	
+0x4960e4	SignalEvent2	403	REPLACE_ENCHANT	%s%s
+0x496230	SignalEvent2	404	TRADE_REPLACE_ENCHANT	%s%s%d
+0x49630d	SignalEvent	dyn		
+0x496359	SignalEvent	508	INSTANCE_BOOT_START	
+0x49636e	SignalEvent	509	INSTANCE_BOOT_STOP	
+0x4963ce	SignalEvent	516	CONFIRM_SUMMON	
+0x4996be	SignalEvent	395	UPDATE_CHAT_WINDOWS	
+0x49971b	SignalEvent2	226	UPDATE_CHAT_COLOR	%s%f%f%f
+0x499793	SignalEvent2	226	UPDATE_CHAT_COLOR	%s%f%f%f
+0x499939	SignalEvent	395	UPDATE_CHAT_WINDOWS	
+0x499993	SignalEvent2	226	UPDATE_CHAT_COLOR	%s%f%f%f
+0x499a03	SignalEvent2	226	UPDATE_CHAT_COLOR	%s%f%f%f
+0x49a95f	SignalEvent2	227	CHAT_MSG_ADDON	%s%s%s%s
+0x49b199	SignalEvent2	?		%s%s%s%s%s%s%d%d%s%d
+0x49b975	SignalEvent	258	LANGUAGE_LIST_CHANGED	
+0x49bddc	SignalEvent	526	UPDATE_WORLD_STATES	
+0x49e1a7	SignalEvent	539	UPDATE_INSTANCE_INFO	
+0x49eb21	SignalEvent	395	UPDATE_CHAT_WINDOWS	
+0x49eb5f	SignalEvent	395	UPDATE_CHAT_WINDOWS	
+0x4a00a9	SignalEvent	395	UPDATE_CHAT_WINDOWS	
+0x4a098b	SignalEvent2	226	UPDATE_CHAT_COLOR	%s%f%f%f
+0x4a6ce4	SignalEvent	365	WORLD_MAP_UPDATE	
+0x4a7835	SignalEvent	373	CLOSE_WORLD_MAP	
+0x4aa15b	SignalEvent	418	BATTLEFIELDS_CLOSED	
+0x4aa308	SignalEvent	420	UPDATE_BATTLEFIELD_SCORE	
+0x4aa7d1	SignalEvent	417	BATTLEFIELDS_SHOW	
+0x4aab05	SignalEvent	419	UPDATE_BATTLEFIELD_STATUS	
+0x4ac195	SignalEvent	366	WORLD_MAP_NAME_UPDATE	
+0x4acd42	SignalEvent	410	MAIL_SHOW	
+0x4acda3	SignalEvent	411	MAIL_CLOSED	
+0x4ace19	SignalEvent	412	SEND_MAIL_MONEY_CHANGED	
+0x4ace23	SignalEvent	413	SEND_MAIL_COD_CHANGED	
+0x4ace2d	SignalEvent	415	MAIL_SEND_SUCCESS	
+0x4ad02a	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4ad16a	SignalEvent	514	MAIL_FAILED	
+0x4ad5d6	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4ad605	SignalEvent	500	UPDATE_PENDING_MAIL	
+0x4ad66b	SignalEvent	500	UPDATE_PENDING_MAIL	
+0x4ad772	SignalEvent2	515	CLOSE_INBOX_ITEM	%d
+0x4ad7a3	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4ad87d	SignalEvent2	515	CLOSE_INBOX_ITEM	%d
+0x4ad8ae	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4ad8fc	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4ad966	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4adc44	SignalEvent	412	SEND_MAIL_MONEY_CHANGED	
+0x4adc88	SignalEvent	413	SEND_MAIL_COD_CHANGED	
+0x4add9d	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4adeba	SignalEvent	500	UPDATE_PENDING_MAIL	
+0x4ae0de	SignalEvent	414	MAIL_SEND_INFO_UPDATE	
+0x4ae71f	SignalEvent	414	MAIL_SEND_INFO_UPDATE	
+0x4ae98d	SignalEvent	414	MAIL_SEND_INFO_UPDATE	
+0x4aeaf8	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4af08f	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4af0af	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4af34f	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4af5bf	SignalEvent	416	MAIL_INBOX_UPDATE	
+0x4b2904	SignalEvent	387	UPDATE_SHAPESHIFT_FORMS	
+0x4b2b92	SignalEvent2	510	LEARNED_SPELL_IN_TAB	%d
+0x4b2e4e	SignalEvent	387	UPDATE_SHAPESHIFT_FORMS	
+0x4b302f	SignalEvent	260	SPELLS_CHANGED	
+0x4b31ba	SignalEvent	262	SPELL_UPDATE_COOLDOWN	
+0x4b3246	SignalEvent	263	SPELL_UPDATE_USABLE	
+0x4b325a	SignalEvent	261	CURRENT_SPELL_CAST_CHANGED	
+0x4b54ad	SignalEvent2	384	TUTORIAL_TRIGGER	%d
+0x4b5890	SignalEvent2	384	TUTORIAL_TRIGGER	%d
+0x4b649d	SignalEvent	386	UPDATE_BINDINGS	
+0x4b805b	SignalEvent	386	UPDATE_BINDINGS	
+0x4ba1a2	SignalEvent	499	RAID_ROSTER_UPDATE	
+0x4ba348	SignalEvent	537	RAID_TARGET_UPDATE	
+0x4ba53a	SignalEvent	536	READY_CHECK	
+0x4ba57b	SignalEvent	499	RAID_ROSTER_UPDATE	
+0x4ba5db	SignalEvent	537	RAID_TARGET_UPDATE	
+0x4babef	SignalEvent	499	RAID_ROSTER_UPDATE	
+0x4bada6	SignalEvent	499	RAID_ROSTER_UPDATE	
+0x4badb0	SignalEvent	218	PARTY_MEMBERS_CHANGED	
+0x4bc85b	SignalEvent2	2	UNIT_PET	%s
+0x4bc907	SignalEvent	428	PET_UI_CLOSE	
+0x4bc911	SignalEvent	353	PET_BAR_UPDATE	
+0x4bc956	SignalEvent	353	PET_BAR_UPDATE	
+0x4bc979	SignalEvent	353	PET_BAR_UPDATE	
+0x4bcb6d	SignalEvent	353	PET_BAR_UPDATE	
+0x4bcc81	SignalEvent	353	PET_BAR_UPDATE	
+0x4bcdcb	SignalEvent	353	PET_BAR_UPDATE	
+0x4bce75	SignalEvent	355	PET_BAR_SHOWGRID	
+0x4bce85	SignalEvent	356	PET_BAR_HIDEGRID	
+0x4bce95	SignalEvent	354	PET_BAR_UPDATE_COOLDOWN	
+0x4bd438	SignalEvent	353	PET_BAR_UPDATE	
+0x4bd6b4	SignalEvent	353	PET_BAR_UPDATE	
+0x4bd722	SignalEvent2	385	PET_DISMISS_START	%d
+0x4bdb54	SignalEvent	353	PET_BAR_UPDATE	
+0x4bf260	SignalEvent2	322	TRADE_ACCEPT_UPDATE	%d%d
+0x4bf29f	SignalEvent2	322	TRADE_ACCEPT_UPDATE	%d%d
+0x4bf414	SignalEvent2	323	TRADE_TARGET_ITEM_CHANGED	%d
+0x4bf452	SignalEvent2	323	TRADE_TARGET_ITEM_CHANGED	%d
+0x4bf487	SignalEvent2	324	TRADE_PLAYER_ITEM_CHANGED	%d
+0x4bf4ab	SignalEvent	326	PLAYER_TRADE_MONEY	
+0x4bf4b5	SignalEvent	200	PLAYER_MONEY	
+0x4bf4d6	SignalEvent	325	TRADE_MONEY_CHANGED	
+0x4bf522	SignalEvent	320	TRADE_CLOSED	
+0x4bf630	SignalEvent	326	PLAYER_TRADE_MONEY	
+0x4bf63a	SignalEvent	200	PLAYER_MONEY	
+0x4bf644	SignalEvent	319	TRADE_SHOW	
+0x4bf705	SignalEvent	319	TRADE_SHOW	
+0x4bf832	SignalEvent	286	TRADE_REQUEST_CANCEL	
+0x4bfaef	SignalEvent2	324	TRADE_PLAYER_ITEM_CHANGED	%d
+0x4bfbea	SignalEvent	326	PLAYER_TRADE_MONEY	
+0x4bfbf5	SignalEvent	200	PLAYER_MONEY	
+0x4bfc3f	SignalEvent2	324	TRADE_PLAYER_ITEM_CHANGED	%d
+0x4bfdce	SignalEvent	326	PLAYER_TRADE_MONEY	
+0x4c034f	SignalEvent	321	TRADE_UPDATE	
+0x4c1dac	SignalEvent	269	LOOT_CLOSED	
+0x4c1ee6	SignalEvent	267	LOOT_OPENED	
+0x4c1f77	SignalEvent2	268	LOOT_SLOT_CLEARED	%d
+0x4c1fe0	SignalEvent	267	LOOT_OPENED	
+0x4c21d4	SignalEvent2	287	LOOT_BIND_CONFIRM	%u
+0x4c2240	SignalEvent	267	LOOT_OPENED	
+0x4c276f	SignalEvent2	268	LOOT_SLOT_CLEARED	%d
+0x4c2862	SignalEvent2	268	LOOT_SLOT_CLEARED	%d
+0x4c28d1	SignalEvent	503	OPEN_MASTER_LOOT_LIST	
+0x4c290f	SignalEvent2	287	LOOT_BIND_CONFIRM	%u
+0x4c2b37	SignalEvent	267	LOOT_OPENED	
+0x4c2fbf	SignalEvent	504	UPDATE_MASTER_LOOT_LIST	
+0x4c3e48	SignalEvent	543	LOTTERY_SHOW	
+0x4c4123	SignalEvent	548	LOTTERY_ITEM_UPDATE	
+0x4c4cd5	SignalEvent	534	START_MINIGAME	
+0x4c4cdf	SignalEvent	535	MINIGAME_UPDATE	
+0x4c4d0a	SignalEvent	535	MINIGAME_UPDATE	
+0x4c6f56	SignalEvent	525	INSPECT_HONOR_UPDATE	
+0x4c7098	SignalEvent2	264	CHARACTER_POINTS_CHANGED	%d%d
+0x4c7110	SignalEvent2	186	UNIT_INVENTORY_CHANGED	%s
+0x4c728d	SignalEvent2	347	PLAYERBANKSLOTS_CHANGED	%s
+0x4c72e0	SignalEvent2	186	UNIT_INVENTORY_CHANGED	%s
+0x4c8085	SignalEvent	501	UPDATE_INVENTORY_ALERTS	
+0x4c8509	SignalEvent2	186	UNIT_INVENTORY_CHANGED	%s
+0x4ca38f	SignalEvent	519	MEETINGSTONE_CHANGED	
+0x4cac9b	SignalEvent	437	PET_STABLE_SHOW	
+0x4cad88	SignalEvent	438	PET_STABLE_UPDATE	
+0x4cae3a	SignalEvent	440	PET_STABLE_CLOSED	
+0x4cb3bf	SignalEvent	438	PET_STABLE_UPDATE	
+0x4cba5f	SignalEvent	439	PET_STABLE_UPDATE_PAPERDOLL	
+0x4cc5d0	SignalEvent	424	AUCTION_ITEM_LIST_UPDATE	
+0x4cc703	SignalEvent	424	AUCTION_ITEM_LIST_UPDATE	
+0x4cc769	SignalEvent	426	AUCTION_BIDDER_LIST_UPDATE	
+0x4cd09e	SignalEvent	426	AUCTION_BIDDER_LIST_UPDATE	
+0x4cd143	SignalEvent	424	AUCTION_ITEM_LIST_UPDATE	
+0x4cd301	SignalEvent	425	AUCTION_OWNED_LIST_UPDATE	
+0x4cd3a8	SignalEvent	424	AUCTION_ITEM_LIST_UPDATE	
+0x4cd5e6	SignalEvent	421	AUCTION_HOUSE_SHOW	
+0x4cd602	SignalEvent	422	AUCTION_HOUSE_CLOSED	
+0x4cd678	SignalEvent	423	NEW_AUCTION_UPDATE	
+0x4cd8cf	SignalEvent	424	AUCTION_ITEM_LIST_UPDATE	
+0x4cdcef	SignalEvent	425	AUCTION_OWNED_LIST_UPDATE	
+0x4cdddf	SignalEvent	426	AUCTION_BIDDER_LIST_UPDATE	
+0x4ce03e	SignalEvent	424	AUCTION_ITEM_LIST_UPDATE	
+0x4ce09e	SignalEvent	425	AUCTION_OWNED_LIST_UPDATE	
+0x4ce101	SignalEvent	426	AUCTION_BIDDER_LIST_UPDATE	
+0x4ce2ff	SignalEvent	423	NEW_AUCTION_UPDATE	
+0x4ce576	SignalEvent	423	NEW_AUCTION_UPDATE	
+0x4cf29f	SignalEvent	424	AUCTION_ITEM_LIST_UPDATE	
+0x4cf2bf	SignalEvent	425	AUCTION_OWNED_LIST_UPDATE	
+0x4cf2df	SignalEvent	426	AUCTION_BIDDER_LIST_UPDATE	
+0x4d117a	SignalEvent2	408	GUILD_ROSTER_UPDATE	%d
+0x4d1188	SignalEvent	408	GUILD_ROSTER_UPDATE	
+0x4d2ff2	SignalEvent	265	SKILL_LINES_CHANGED	
+0x4d346f	SignalEvent	265	SKILL_LINES_CHANGED	
+0x4d3598	SignalEvent	265	SKILL_LINES_CHANGED	
+0x4d3e3a	SignalEvent	265	SKILL_LINES_CHANGED	
+0x4d4a88	SignalEvent2	380	DUEL_REQUESTED	%s
+0x4d4aa5	SignalEvent	381	DUEL_OUTOFBOUNDS	
+0x4d4ac5	SignalEvent	382	DUEL_INBOUNDS	
+0x4d4b6a	SignalEvent	383	DUEL_FINISHED	
+0x4d569e	SignalEvent	372	UPDATE_FACTION	
+0x4d56f6	SignalEvent	372	UPDATE_FACTION	
+0x4d5984	SignalEvent	372	UPDATE_FACTION	
+0x4d5db0	SignalEvent	372	UPDATE_FACTION	
+0x4d7468	SignalEvent	311	TRAINER_CLOSED	
+0x4d7b73	SignalEvent	309	TRAINER_SHOW	
+0x4d83f9	SignalEvent	310	TRAINER_UPDATE	
+0x4d8ca0	SignalEvent	310	TRAINER_UPDATE	
+0x4d8cc0	SignalEvent	310	TRAINER_UPDATE	
+0x4d8ce0	SignalEvent	310	TRAINER_UPDATE	
+0x4dba96	SignalEvent	306	TAXIMAP_OPENED	
+0x4dc15f	SignalEvent	307	TAXIMAP_CLOSED	
+0x4de534	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4de816	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4ded98	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4dedba	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4dedd6	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4def20	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4df28f	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4df840	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4e07ef	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4e081f	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4e083f	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4e1559	SignalEvent	308	QUEST_LOG_UPDATE	
+0x4e1fdc	SignalEvent	299	GOSSIP_CLOSED	
+0x4e22b5	SignalEvent	297	GOSSIP_SHOW	
+0x4e237e	SignalEvent2	298	GOSSIP_ENTER_CODE	%d
+0x4e332d	SignalEvent	296	ITEM_TEXT_CLOSED	
+0x4e33a2	SignalEvent	296	ITEM_TEXT_CLOSED	
+0x4e34a4	SignalEvent	293	ITEM_TEXT_BEGIN	
+0x4e367c	SignalEvent	295	ITEM_TEXT_READY	
+0x4e3783	SignalEvent	295	ITEM_TEXT_READY	
+0x4e3860	SignalEvent	295	ITEM_TEXT_READY	
+0x4e437f	SignalEvent	192	PLAYER_AURAS_CHANGED	
+0x4e501d	SignalEvent	217	UPDATE_BONUS_ACTIONBAR	
+0x4e58c5	SignalEvent	210	ACTIONBAR_SHOWGRID	
+0x4e58d5	SignalEvent	211	ACTIONBAR_HIDEGRID	
+0x4e5998	SignalEvent2	213	ACTIONBAR_SLOT_CHANGED	%d
+0x4e5bf5	SignalEvent	214	ACTIONBAR_UPDATE_STATE	
+0x4e5c53	SignalEvent	215	ACTIONBAR_UPDATE_USABLE	
+0x4e5c65	SignalEvent	216	ACTIONBAR_UPDATE_COOLDOWN	
+0x4e7655	SignalEvent	212	ACTIONBAR_PAGE_CHANGED	
+0x4e82a9	SignalEvent	219	PARTY_LEADER_CHANGED	
+0x4e82c2	SignalEvent	219	PARTY_LEADER_CHANGED	
+0x4e8495	SignalEvent	218	PARTY_MEMBERS_CHANGED	
+0x4e85c5	SignalEvent	218	PARTY_MEMBERS_CHANGED	
+0x4e86b6	SignalEvent2	220	PARTY_MEMBER_ENABLE	%d
+0x4e87fa	SignalEvent	222	PARTY_LOOT_METHOD_CHANGED	
+0x4e8b0e	SignalEvent	531	UPDATE_LFG_TYPES	
+0x4e8c70	SignalEvent	531	UPDATE_LFG_TYPES	
+0x4e8d46	SignalEvent	532	UPDATE_LFG_LIST	
+0x4e8f45	SignalEvent	532	UPDATE_LFG_LIST	
+0x4ee48d	SignalEvent2	357	MINIMAP_PING	%s%f%f
+0x4f0dfb	SignalEvent	393	UPDATE_MACROS	
+0x4f153c	SignalEvent2	392	EXECUTE_CHAT_LINE	%s
+0x4f402c	SignalEvent	391	PETITION_CLOSED	
+0x4f41b4	SignalEvent	390	PETITION_SHOW	
+0x4f430c	SignalEvent	390	PETITION_SHOW	
+0x4f433f	SignalEvent	390	PETITION_SHOW	
+0x4f43ad	SignalEvent	390	PETITION_SHOW	
+0x4f5003	SignalEvent	378	GUILD_REGISTRAR_SHOW	
+0x4f503a	SignalEvent	379	GUILD_REGISTRAR_CLOSED	
+0x4f588d	SignalEvent	374	OPEN_TABARD_FRAME	
+0x4f58f8	SignalEvent	375	CLOSE_TABARD_FRAME	
+0x4f5fef	SignalEvent	361	CRAFT_CLOSE	
+0x4f6017	SignalEvent	361	CRAFT_CLOSE	
+0x4f6040	SignalEvent	359	CRAFT_SHOW	
+0x4f661a	SignalEvent	360	CRAFT_UPDATE	
+0x4f6bf0	SignalEvent	360	CRAFT_UPDATE	
+0x4f8495	SignalEvent	350	PLAYERBANKBAGSLOTS_CHANGED	
+0x4f84df	SignalEvent	349	BANKFRAME_CLOSED	
+0x4f8522	SignalEvent	348	BANKFRAME_OPENED	
+0x4f8e8a	SignalEvent2	328	BAG_UPDATE	%d
+0x4f92b5	SignalEvent2	329	BAG_CLOSED	%d
+0x4f9343	SignalEvent2	328	BAG_UPDATE	%d
+0x4f93bf	SignalEvent2	328	BAG_UPDATE	%d
+0x4f93d5	SignalEvent	330	BAG_UPDATE_COOLDOWN	
+0x4f9434	SignalEvent2	327	BAG_OPEN	%d
+0x4f9469	SignalEvent2	327	BAG_OPEN	%d
+0x4facaa	SignalEvent	317	MERCHANT_UPDATE	
+0x4fad92	SignalEvent	316	MERCHANT_SHOW	
+0x4fae2c	SignalEvent	318	MERCHANT_CLOSED	
+0x4faea5	SignalEvent	317	MERCHANT_UPDATE	
+0x4faebd	SignalEvent	317	MERCHANT_UPDATE	
+0x4fb115	SignalEvent	317	MERCHANT_UPDATE	
+0x4fb575	SignalEvent	317	MERCHANT_UPDATE	
+0x4fc884	SignalEvent	315	TRADE_SKILL_CLOSE	
+0x4fc930	SignalEvent	315	TRADE_SKILL_CLOSE	
+0x4fc99f	SignalEvent	313	TRADE_SKILL_SHOW	
+0x4fd164	SignalEvent	314	TRADE_SKILL_UPDATE	
+0x4fd725	SignalEvent	314	TRADE_SKILL_UPDATE	
+0x4fd745	SignalEvent	314	TRADE_SKILL_UPDATE	
+0x4fd765	SignalEvent	314	TRADE_SKILL_UPDATE	
+0x4fd781	SignalEvent	502	UPDATE_TRADESKILL_RECAST	
+0x4fd7a8	SignalEvent	502	UPDATE_TRADESKILL_RECAST	
+0x4fd7e1	SignalEvent	502	UPDATE_TRADESKILL_RECAST	
+0x500ee5	SignalEvent	300	QUEST_GREETING	
+0x50105d	SignalEvent	303	QUEST_COMPLETE	
+0x501120	SignalEvent	302	QUEST_PROGRESS	
+0x501217	SignalEvent	304	QUEST_FINISHED	
+0x501903	SignalEvent	305	QUEST_ITEM_UPDATE	
+0x5019fe	SignalEvent2	346	QUEST_ACCEPT_CONFIRM	%s%s
+0x515e7a	SignalEvent2	?		%s
+0x51f5ad	SignalEvent2	429	ADDON_LOADED	%s
+0x5aae97	SignalEvent	278	LOGOUT_CANCEL	
+0x5aaf17	SignalEvent	?		
+0x5aaf72	SignalEvent	278	LOGOUT_CANCEL	
+0x5ab2f5	SignalEvent	6		
+0x5ad9f2	SignalEvent	388	WHO_LIST_UPDATE	
+0x5ae141	SignalEvent	388	WHO_LIST_UPDATE	
+0x5ae867	SignalEvent	351	FRIENDLIST_UPDATE	
+0x5ae92d	SignalEvent	352	IGNORELIST_UPDATE	
+0x5d48a8	SignalEvent	200	PLAYER_MONEY	
+0x5d859a	SignalEvent	188	ITEM_LOCK_CHANGED	
+0x5d9222	SignalEvent	290	USE_BIND_CONFIRM	
+0x5d94b9	SignalEvent	188	ITEM_LOCK_CHANGED	
+0x5dd15e	SignalEvent2	545	QUEST_WATCH_UPDATE	%d
+0x5ddd6e	SignalEvent	347	PLAYERBANKSLOTS_CHANGED	
+0x5ddf4b	SignalEvent	200	PLAYER_MONEY	
+0x5ddffa	SignalEvent	202	PLAYER_COMBO_POINTS	
+0x5de14e	SignalEvent	198	PLAYER_FARSIGHT_FOCUS_CHANGED	
+0x5de167	SignalEvent	198	PLAYER_FARSIGHT_FOCUS_CHANGED	
+0x5de4c1	SignalEvent2	?		%s
+0x5de4e8	SignalEvent	406	UPDATE_EXHAUSTION	
+0x5dea2a	SignalEvent	401	PLAYER_UNGHOST	
+0x5deb20	SignalEvent2	213	ACTIONBAR_SLOT_CHANGED	%d
+0x5deecb	SignalEvent2	162	UNIT_RANGED_ATTACK_POWER	%s
+0x5df837	SignalEvent2	396	CONFIRM_XP_LOSS	%d
+0x5dfa3f	SignalEvent2	512	CONFIRM_TALENT_WIPE	%d
+0x5dfc5f	SignalEvent2	529	CONFIRM_PET_UNLEARN	%d
+0x5dfec3	SignalEvent2	513	CONFIRM_BINDER	%s
+0x5e05fc	SignalEvent	521	TABARD_SAVE_PENDING	
+0x5e0907	SignalEvent	376	TABARD_CANSAVE_CHANGED	
+0x5e0ee4	SignalEvent2	288	EQUIP_BIND_CONFIRM	%d
+0x5e16c6	SignalEvent2	289	AUTOEQUIP_BIND_CONFIRM	%d
+0x5e27b5	SignalEvent	345	PLAYER_GUILD_UPDATE	
+0x5e2b38	SignalEvent2	28	UNIT_LEVEL	%s
+0x5e3b20	SignalEvent	267	LOOT_OPENED	
+0x5e413e	SignalEvent2	199	PLAYER_LEVEL_UP	%d%d%d%d%d%d%d%d%d
+0x5e4527	SignalEvent2	394	UPDATE_TICKET	%d%s%f%f%f%d%d
+0x5e45e2	SignalEvent2	394	UPDATE_TICKET	%d%s%f%f%f%d%d
+0x5e461d	SignalEvent2	394	UPDATE_TICKET	%d%s
+0x5e4689	SignalEvent2	400	UPDATE_GM_STATUS	%d
+0x5e5e7b	SignalEvent2	545	QUEST_WATCH_UPDATE	%d
+0x5e6c66	SignalEvent	218	PARTY_MEMBERS_CHANGED	
+0x5e7172	SignalEvent	521	TABARD_SAVE_PENDING	
+0x5e728d	SignalEvent2	284	GUILD_MOTD	%s
+0x5e7960	SignalEvent2	394	UPDATE_TICKET	%d%s%f%f%f%d%d
+0x5e797b	SignalEvent	538	GMSURVEY_DISPLAY	
+0x5e79cc	SignalEvent2	364	MIRROR_TIMER_STOP	%s
+0x5e7a11	SignalEvent2	363	MIRROR_TIMER_PAUSE	%s%d
+0x5e7a9a	SignalEvent2	362	MIRROR_TIMER_START	%s%d%d%d%d%s
+0x5e9b78	SignalEvent2	221	PARTY_MEMBER_DISABLE	%d
+0x5e9ba5	SignalEvent2	364	MIRROR_TIMER_STOP	%s
+0x5ec68b	SignalEvent	296	ITEM_TEXT_CLOSED	
+0x5ec6c5	SignalEvent2	294	ITEM_TEXT_TRANSLATION	%f
+0x5ed97f	SignalEvent2	332	UNIT_ATTACK	%s
+0x5ed99f	SignalEvent2	332	UNIT_ATTACK	%s
+0x5ed9b3	SignalEvent2	333	UNIT_DEFENSE	%s
+0x5ed9c7	SignalEvent2	162	UNIT_RANGED_ATTACK_POWER	%s
+0x5eeaf7	SignalEvent	405	PLAYER_UPDATE_RESTING	
+0x5eeb6f	SignalEvent	530	PLAYTIME_CHANGED	
+0x5ef037	SignalEvent	391	PETITION_CLOSED	
+0x5ef16b	SignalEvent	379	GUILD_REGISTRAR_CLOSED	
+0x5ef29c	SignalEvent	390	PETITION_SHOW	
+0x5fefb8	SignalEvent	274	PLAYER_ALIVE	
+0x5ff533	SignalEvent	191	PLAYER_REGEN_ENABLED	
+0x5ff79f	SignalEvent	335	PET_ATTACK_STOP	
+0x604b17	SignalEvent	331	LOCALPLAYER_PET_RENAMED	
+0x604c1b	SignalEvent	427	PET_UI_UPDATE	
+0x60fb84	SignalEvent	368	AUTOFOLLOW_END	
+0x610071	SignalEvent2	367	AUTOFOLLOW_BEGIN	%s
+0x61b2c7	SignalEvent2	506	CANCEL_LOOT_ROLL	%d
+0x61b452	SignalEvent2	505	START_LOOT_ROLL	%d%d
+0x61b6f3	SignalEvent2	506	CANCEL_LOOT_ROLL	%d
+0x61b7ac	SignalEvent2	505	START_LOOT_ROLL	%d%d
+0x61bc12	SignalEvent2	506	CANCEL_LOOT_ROLL	%d
+0x61be8b	SignalEvent2	507	CONFIRM_LOOT_ROLL	%d%d
+0x61bf2a	SignalEvent2	506	CANCEL_LOOT_ROLL	%d
+0x6256ff	SignalEvent	193	PLAYER_ENTER_COMBAT	
+0x625778	SignalEvent	194	PLAYER_LEAVE_COMBAT	
+0x6268d3	SignalEvent2	542	COMBAT_TEXT_UPDATE	%s%s%s
+0x62694d	SignalEvent2	542	COMBAT_TEXT_UPDATE	%s%s%s
+0x62699c	SignalEvent2	542	COMBAT_TEXT_UPDATE	%s%s
+0x6269c3	SignalEvent2	542	COMBAT_TEXT_UPDATE	%s%s
+0x6269e2	SignalEvent2	542	COMBAT_TEXT_UPDATE	%s
+0x6d902a	SignalEvent	207	MINIMAP_UPDATE_ZOOM	
+0x6d95b8	SignalEvent	207	MINIMAP_UPDATE_ZOOM	
+0x6e224a	SignalEvent	340	SPELLCAST_INTERRUPTED	
+0x6e4a50	SignalEvent	338	SPELLCAST_STOP	
+0x6e5952	SignalEvent	435	START_AUTOREPEAT_SPELL	
+0x6e70c3	SignalEvent	528	AREA_SPIRIT_HEALER_OUT_OF_RANGE	
+0x6e74d0	SignalEvent	338	SPELLCAST_STOP	
+0x6e7532	SignalEvent2	341	SPELLCAST_DELAYED	%d
+0x6e75d0	SignalEvent2	342	SPELLCAST_CHANNEL_START	%d%s
+0x6e7611	SignalEvent2	343	SPELLCAST_CHANNEL_UPDATE	%d
+0x6e7627	SignalEvent	344	SPELLCAST_CHANNEL_STOP	
+0x6e7a53	SignalEvent2	337	SPELLCAST_START	%s%d
+0x6ea170	SignalEvent	436	STOP_AUTOREPEAT_SPELL	
diff --git a/reference/1.12-events.tsv b/reference/1.12-events.tsv
new file mode 100644
index 00000000..e31f163d
--- /dev/null
+++ b/reference/1.12-events.tsv
@@ -0,0 +1,410 @@
+# The 1.12.1 client's FrameScript events and the arguments their producers push.
+# Generated by scripts/gen-reference-events.py from reference/1.12-event-catalog.tsv
+# and reference/1.12-event-firesites.tsv.
+#
+# arg_formats  `|`-separated, one per distinct producer shape. `()` = zero Lua values.
+#              Directives: %s string, %d/%u number, %f number. An event with two
+#              producers of different shapes carries both; which one fires depends
+#              on the transition, not the name.
+# conf         exact = gate on it. advisory = a contributing site declares more
+#              varargs than it pushes. none = no producer family reaches it here,
+#              which does not mean it has none; never gate on it.
+# producers    signal (0x703e50, no varargs) | signal2 (0x703f50, format-driven) |
+#              unit-field-bridge (0x51bbb0/0x51bd50 -> 0x515e50, always %s) |
+#              token-fanout (0x515e50 with a literal id, also %s).
+# 394 events, 278 with a known producer; 22 glue-space fire sites dropped.
+name	ids	producers	arg_formats	conf	note
+ACTIONBAR_HIDEGRID	211	signal	()	exact	
+ACTIONBAR_PAGE_CHANGED	212	signal	()	exact	
+ACTIONBAR_SHOWGRID	210	signal	()	exact	
+ACTIONBAR_SLOT_CHANGED	213	signal2	%d	exact	
+ACTIONBAR_UPDATE_COOLDOWN	216	signal	()	exact	
+ACTIONBAR_UPDATE_STATE	214	signal	()	exact	
+ACTIONBAR_UPDATE_USABLE	215	signal	()	exact	
+ADDON_ACTION_FORBIDDEN	432	signal2	%s	exact	
+ADDON_LOADED	429	signal2	%s	exact	
+AREA_SPIRIT_HEALER_IN_RANGE	527	signal	()	exact	
+AREA_SPIRIT_HEALER_OUT_OF_RANGE	528	signal	()	exact	
+AUCTION_BIDDER_LIST_UPDATE	426	signal	()	exact	
+AUCTION_HOUSE_CLOSED	422	signal	()	exact	
+AUCTION_HOUSE_SHOW	421	signal	()	exact	
+AUCTION_ITEM_LIST_UPDATE	424	signal	()	exact	
+AUCTION_OWNED_LIST_UPDATE	425	signal	()	exact	
+AUTOEQUIP_BIND_CONFIRM	289	signal2	%d	exact	
+AUTOFOLLOW_BEGIN	367	signal2	%s	exact	
+AUTOFOLLOW_END	368	signal	()	exact	
+BAG_CLOSED	329	signal2	%d	exact	
+BAG_OPEN	327	signal2	%d	exact	
+BAG_UPDATE	328	signal2	%d	exact	
+BAG_UPDATE_COOLDOWN	330	signal	()	exact	
+BANKFRAME_CLOSED	349	signal	()	exact	
+BANKFRAME_OPENED	348	signal	()	exact	
+BATTLEFIELDS_CLOSED	418	signal	()	exact	
+BATTLEFIELDS_SHOW	417	signal	()	exact	
+BILLING_NAG_DIALOG	517	signal2	%d	exact	
+BIND_ENCHANT	402	signal	()	exact	
+CANCEL_LOOT_ROLL	506	signal2	%d	exact	
+CHARACTER_POINTS_CHANGED	264	signal2	%d%d	exact	
+CHAT_MSG_ADDON	227	signal2	%s%s%s%s	exact	
+CHAT_MSG_AFK	249		?	none	
+CHAT_MSG_BATTLEGROUND	546		?	none	
+CHAT_MSG_BATTLEGROUND_LEADER	547		?	none	
+CHAT_MSG_BG_SYSTEM_ALLIANCE	497		?	none	
+CHAT_MSG_BG_SYSTEM_HORDE	498		?	none	
+CHAT_MSG_BG_SYSTEM_NEUTRAL	496		?	none	
+CHAT_MSG_CHANNEL	243		?	none	
+CHAT_MSG_CHANNEL_JOIN	244		?	none	
+CHAT_MSG_CHANNEL_LEAVE	245		?	none	
+CHAT_MSG_CHANNEL_LIST	246		?	none	
+CHAT_MSG_CHANNEL_NOTICE	247		?	none	
+CHAT_MSG_CHANNEL_NOTICE_USER	248		?	none	
+CHAT_MSG_COMBAT_CREATURE_VS_CREATURE_HITS	455		?	none	
+CHAT_MSG_COMBAT_CREATURE_VS_CREATURE_MISSES	456		?	none	
+CHAT_MSG_COMBAT_CREATURE_VS_PARTY_HITS	453		?	none	
+CHAT_MSG_COMBAT_CREATURE_VS_PARTY_MISSES	454		?	none	
+CHAT_MSG_COMBAT_CREATURE_VS_SELF_HITS	451		?	none	
+CHAT_MSG_COMBAT_CREATURE_VS_SELF_MISSES	452		?	none	
+CHAT_MSG_COMBAT_FACTION_CHANGE	533		?	none	
+CHAT_MSG_COMBAT_FRIENDLYPLAYER_HITS	447		?	none	
+CHAT_MSG_COMBAT_FRIENDLYPLAYER_MISSES	448		?	none	
+CHAT_MSG_COMBAT_FRIENDLY_DEATH	457		?	none	
+CHAT_MSG_COMBAT_HONOR_GAIN	460		?	none	
+CHAT_MSG_COMBAT_HOSTILEPLAYER_HITS	449		?	none	
+CHAT_MSG_COMBAT_HOSTILEPLAYER_MISSES	450		?	none	
+CHAT_MSG_COMBAT_HOSTILE_DEATH	458		?	none	
+CHAT_MSG_COMBAT_LOG	251		?	none	
+CHAT_MSG_COMBAT_MISC_INFO	358		?	none	
+CHAT_MSG_COMBAT_PARTY_HITS	445		?	none	
+CHAT_MSG_COMBAT_PARTY_MISSES	446		?	none	
+CHAT_MSG_COMBAT_PET_HITS	443		?	none	
+CHAT_MSG_COMBAT_PET_MISSES	444		?	none	
+CHAT_MSG_COMBAT_SELF_HITS	441		?	none	
+CHAT_MSG_COMBAT_SELF_MISSES	442		?	none	
+CHAT_MSG_COMBAT_XP_GAIN	459		?	none	
+CHAT_MSG_DND	250		?	none	
+CHAT_MSG_EMOTE	236		?	none	
+CHAT_MSG_FILTERED	544		?	none	
+CHAT_MSG_GUILD	231		?	none	
+CHAT_MSG_IGNORED	252		?	none	
+CHAT_MSG_LOOT	254		?	none	
+CHAT_MSG_MONEY	255		?	none	
+CHAT_MSG_MONSTER_EMOTE	242		?	none	
+CHAT_MSG_MONSTER_SAY	239		?	none	
+CHAT_MSG_MONSTER_WHISPER	241		?	none	
+CHAT_MSG_MONSTER_YELL	240		?	none	
+CHAT_MSG_OFFICER	232		?	none	
+CHAT_MSG_PARTY	229		?	none	
+CHAT_MSG_RAID	230		?	none	
+CHAT_MSG_RAID_BOSS_EMOTE	541		?	none	
+CHAT_MSG_RAID_LEADER	256		?	none	
+CHAT_MSG_RAID_WARNING	257		?	none	
+CHAT_MSG_SAY	228		?	none	
+CHAT_MSG_SKILL	253		?	none	
+CHAT_MSG_SPELL_AURA_GONE_OTHER	482		?	none	
+CHAT_MSG_SPELL_AURA_GONE_PARTY	481		?	none	
+CHAT_MSG_SPELL_AURA_GONE_SELF	480		?	none	
+CHAT_MSG_SPELL_BREAK_AURA	484		?	none	
+CHAT_MSG_SPELL_CREATURE_VS_CREATURE_BUFF	476		?	none	
+CHAT_MSG_SPELL_CREATURE_VS_CREATURE_DAMAGE	475		?	none	
+CHAT_MSG_SPELL_CREATURE_VS_PARTY_BUFF	474		?	none	
+CHAT_MSG_SPELL_CREATURE_VS_PARTY_DAMAGE	473		?	none	
+CHAT_MSG_SPELL_CREATURE_VS_SELF_BUFF	472		?	none	
+CHAT_MSG_SPELL_CREATURE_VS_SELF_DAMAGE	471		?	none	
+CHAT_MSG_SPELL_DAMAGESHIELDS_ON_OTHERS	479		?	none	
+CHAT_MSG_SPELL_DAMAGESHIELDS_ON_SELF	478		?	none	
+CHAT_MSG_SPELL_FAILED_LOCALPLAYER	495		?	none	
+CHAT_MSG_SPELL_FRIENDLYPLAYER_BUFF	468		?	none	
+CHAT_MSG_SPELL_FRIENDLYPLAYER_DAMAGE	467		?	none	
+CHAT_MSG_SPELL_HOSTILEPLAYER_BUFF	470		?	none	
+CHAT_MSG_SPELL_HOSTILEPLAYER_DAMAGE	469		?	none	
+CHAT_MSG_SPELL_ITEM_ENCHANTMENTS	483		?	none	
+CHAT_MSG_SPELL_PARTY_BUFF	466		?	none	
+CHAT_MSG_SPELL_PARTY_DAMAGE	465		?	none	
+CHAT_MSG_SPELL_PERIODIC_CREATURE_BUFFS	494		?	none	
+CHAT_MSG_SPELL_PERIODIC_CREATURE_DAMAGE	493		?	none	
+CHAT_MSG_SPELL_PERIODIC_FRIENDLYPLAYER_BUFFS	490		?	none	
+CHAT_MSG_SPELL_PERIODIC_FRIENDLYPLAYER_DAMAGE	489		?	none	
+CHAT_MSG_SPELL_PERIODIC_HOSTILEPLAYER_BUFFS	492		?	none	
+CHAT_MSG_SPELL_PERIODIC_HOSTILEPLAYER_DAMAGE	491		?	none	
+CHAT_MSG_SPELL_PERIODIC_PARTY_BUFFS	488		?	none	
+CHAT_MSG_SPELL_PERIODIC_PARTY_DAMAGE	487		?	none	
+CHAT_MSG_SPELL_PERIODIC_SELF_BUFFS	486		?	none	
+CHAT_MSG_SPELL_PERIODIC_SELF_DAMAGE	485		?	none	
+CHAT_MSG_SPELL_PET_BUFF	464		?	none	
+CHAT_MSG_SPELL_PET_DAMAGE	463		?	none	
+CHAT_MSG_SPELL_SELF_BUFF	462		?	none	
+CHAT_MSG_SPELL_SELF_DAMAGE	461		?	none	
+CHAT_MSG_SPELL_TRADESKILLS	477		?	none	
+CHAT_MSG_SYSTEM	238		?	none	
+CHAT_MSG_TEXT_EMOTE	237		?	none	
+CHAT_MSG_WHISPER	234		?	none	
+CHAT_MSG_WHISPER_INFORM	235		?	none	
+CHAT_MSG_YELL	233		?	none	
+CINEMATIC_START	370	signal	()	exact	
+CINEMATIC_STOP	371	signal	()	exact	
+CLOSE_INBOX_ITEM	515	signal2	%d	exact	
+CLOSE_TABARD_FRAME	375	signal	()	exact	
+CLOSE_WORLD_MAP	373	signal	()	exact	
+COMBAT_TEXT_UPDATE	542	signal2	%s|%s%s|%s%s%s	exact	
+CONFIRM_BINDER	513	signal2	%s	exact	
+CONFIRM_LOOT_ROLL	507	signal2	%d%d	exact	
+CONFIRM_PET_UNLEARN	529	signal2	%d	exact	
+CONFIRM_SUMMON	516	signal	()	exact	
+CONFIRM_TALENT_WIPE	512	signal2	%d	exact	
+CONFIRM_XP_LOSS	396	signal2	%d	exact	
+CORPSE_IN_INSTANCE	398		?	none	
+CORPSE_IN_RANGE	397		?	none	
+CORPSE_OUT_OF_RANGE	399	signal	()	exact	
+CRAFT_CLOSE	361	signal	()	exact	
+CRAFT_SHOW	359	signal	()	exact	
+CRAFT_UPDATE	360	signal	()	exact	
+CURRENT_SPELL_CAST_CHANGED	261	signal	()	exact	
+CURSOR_UPDATE	292	signal	()	exact	
+CVAR_UPDATE	312	signal2	%s%s	exact	
+DELETE_ITEM_CONFIRM	291	signal2	%s%d	exact	
+DISPLAY_SIZE_CHANGED	511	signal	()	exact	
+DUEL_FINISHED	383	signal	()	exact	
+DUEL_INBOUNDS	382	signal	()	exact	
+DUEL_OUTOFBOUNDS	381	signal	()	exact	
+DUEL_REQUESTED	380	signal2	%s	exact	
+EQUIP_BIND_CONFIRM	288	signal2	%d	exact	
+EXECUTE_CHAT_LINE	392	signal2	%s	exact	
+FRIENDLIST_UPDATE	351	signal	()	exact	
+GMSURVEY_DISPLAY	538	signal	()	exact	
+GM_PLAYER_INFO	409		?	none	
+GOSSIP_CLOSED	299	signal	()	exact	
+GOSSIP_ENTER_CODE	298	signal2	%d	exact	
+GOSSIP_SHOW	297	signal	()	exact	
+GUILD_INVITE_CANCEL	283	signal	()	exact	
+GUILD_INVITE_REQUEST	282	signal2	%s%s	exact	
+GUILD_MOTD	284	signal2	%s	exact	
+GUILD_REGISTRAR_CLOSED	379	signal	()	exact	
+GUILD_REGISTRAR_SHOW	378	signal	()	exact	
+GUILD_ROSTER_UPDATE	408	signal|signal2	%d|()	exact	
+IGNORELIST_UPDATE	352	signal	()	exact	
+IGR_BILLING_NAG_DIALOG	518	signal	()	exact	
+INSPECT_HONOR_UPDATE	525	signal	()	exact	
+INSTANCE_BOOT_START	508	signal	()	exact	
+INSTANCE_BOOT_STOP	509	signal	()	exact	
+ITEM_LOCK_CHANGED	188	signal	()	exact	
+ITEM_PUSH	266	signal2	%d%s	exact	
+ITEM_TEXT_BEGIN	293	signal	()	exact	
+ITEM_TEXT_CLOSED	296	signal	()	exact	
+ITEM_TEXT_READY	295	signal	()	exact	
+ITEM_TEXT_TRANSLATION	294	signal2	%f	exact	
+LANGUAGE_LIST_CHANGED	258	signal	()	exact	
+LEARNED_SPELL_IN_TAB	510	signal2	%d	exact	
+LOCALPLAYER_PET_RENAMED	331	signal	()	exact	
+LOGOUT_CANCEL	278	signal	()	exact	
+LOOT_BIND_CONFIRM	287	signal2	%u	exact	
+LOOT_CLOSED	269	signal	()	exact	
+LOOT_OPENED	267	signal	()	exact	
+LOOT_SLOT_CLEARED	268	signal2	%d	exact	
+LOTTERY_ITEM_UPDATE	548	signal	()	exact	
+LOTTERY_SHOW	543	signal	()	exact	
+MACRO_ACTION_FORBIDDEN	431	signal	()	exact	
+MAIL_CLOSED	411	signal	()	exact	
+MAIL_FAILED	514	signal	()	exact	
+MAIL_INBOX_UPDATE	416	signal	()	exact	
+MAIL_SEND_INFO_UPDATE	414	signal	()	exact	
+MAIL_SEND_SUCCESS	415	signal	()	exact	
+MAIL_SHOW	410	signal	()	exact	
+MEETINGSTONE_CHANGED	519	signal	()	exact	
+MEMORY_EXHAUSTED	433	signal2	%d	exact	
+MEMORY_RECOVERED	434	signal	()	exact	
+MERCHANT_CLOSED	318	signal	()	exact	
+MERCHANT_SHOW	316	signal	()	exact	
+MERCHANT_UPDATE	317	signal	()	exact	
+MINIGAME_UPDATE	535	signal	()	exact	
+MINIMAP_PING	357	signal2	%s%f%f	exact	
+MINIMAP_UPDATE_ZOOM	207	signal	()	exact	
+MINIMAP_ZONE_CHANGED	206	signal	()	exact	
+MIRROR_TIMER_PAUSE	363	signal2	%s%d	exact	
+MIRROR_TIMER_START	362	signal2	%s%d%d%d%d%s	exact	
+MIRROR_TIMER_STOP	364	signal2	%s	exact	
+NEW_AUCTION_UPDATE	423	signal	()	exact	
+OPEN_MASTER_LOOT_LIST	503	signal	()	exact	
+OPEN_TABARD_FRAME	374	signal	()	exact	
+PARTY_INVITE_CANCEL	281	signal	()	exact	
+PARTY_INVITE_REQUEST	280	signal2	%s	exact	
+PARTY_LEADER_CHANGED	219	signal	()	exact	
+PARTY_LOOT_METHOD_CHANGED	222	signal	()	exact	
+PARTY_MEMBERS_CHANGED	218	signal	()	exact	
+PARTY_MEMBER_DISABLE	221	signal2	%d	exact	
+PARTY_MEMBER_ENABLE	220	signal2	%d	exact	
+PETITION_CLOSED	391	signal	()	exact	
+PETITION_SHOW	390	signal	()	exact	
+PET_ATTACK_START	334		?	none	
+PET_ATTACK_STOP	335	signal	()	exact	
+PET_BAR_HIDEGRID	356	signal	()	exact	
+PET_BAR_SHOWGRID	355	signal	()	exact	
+PET_BAR_UPDATE	353	signal	()	exact	
+PET_BAR_UPDATE_COOLDOWN	354	signal	()	exact	
+PET_DISMISS_START	385	signal2	%d	exact	
+PET_STABLE_CLOSED	440	signal	()	exact	
+PET_STABLE_SHOW	437	signal	()	exact	
+PET_STABLE_UPDATE	438	signal	()	exact	
+PET_STABLE_UPDATE_PAPERDOLL	439	signal	()	exact	
+PET_UI_CLOSE	428	signal	()	exact	
+PET_UI_UPDATE	427	signal	()	exact	
+PLAYERBANKBAGSLOTS_CHANGED	350	signal	()	exact	
+PLAYERBANKSLOTS_CHANGED	347	signal|signal2	%s|()	exact	
+PLAYER_ALIVE	274	signal	()	exact	
+PLAYER_AURAS_CHANGED	192	signal	()	exact	
+PLAYER_CAMPING	276		?	none	
+PLAYER_COMBO_POINTS	202	signal	()	exact	
+PLAYER_CONTROL_GAINED	197	signal	()	exact	
+PLAYER_CONTROL_LOST	196	signal	()	exact	
+PLAYER_DAMAGE_DONE_MODS	201		?	none	
+PLAYER_DEAD	275	signal	()	exact	
+PLAYER_ENTERING_WORLD	272	signal	()	exact	
+PLAYER_ENTER_COMBAT	193	signal	()	exact	
+PLAYER_FARSIGHT_FOCUS_CHANGED	198	signal	()	exact	
+PLAYER_FLAGS_CHANGED	407	token-fanout	%s	exact	
+PLAYER_GUILD_UPDATE	345	signal|token-fanout	%s|()	exact	
+PLAYER_LEAVE_COMBAT	194	signal	()	exact	
+PLAYER_LEAVING_WORLD	273	signal	()	exact	
+PLAYER_LEVEL_UP	199	signal2	%d%d%d%d%d%d%d%d%d	exact	
+PLAYER_LOGIN	270	signal	()	exact	
+PLAYER_LOGOUT	271	signal	()	exact	
+PLAYER_MONEY	200	signal	()	exact	
+PLAYER_PVP_KILLS_CHANGED	523		?	none	
+PLAYER_PVP_RANK_CHANGED	524		?	none	
+PLAYER_QUITING	277		?	none	
+PLAYER_REGEN_DISABLED	190		?	none	
+PLAYER_REGEN_ENABLED	191	signal	()	exact	
+PLAYER_SKINNED	520	signal2	%d	exact	
+PLAYER_TARGET_CHANGED	195	signal	()	exact	
+PLAYER_TRADE_MONEY	326	signal	()	exact	
+PLAYER_UNGHOST	401	signal	()	exact	
+PLAYER_UPDATE_RESTING	405	signal	()	exact	
+PLAYER_XP_UPDATE	189		?	none	
+PLAYTIME_CHANGED	530	signal	()	exact	
+QUEST_ACCEPT_CONFIRM	346	signal2	%s%s	exact	
+QUEST_COMPLETE	303	signal	()	exact	
+QUEST_DETAIL	301		?	none	
+QUEST_FINISHED	304	signal	()	exact	
+QUEST_GREETING	300	signal	()	exact	
+QUEST_ITEM_UPDATE	305	signal	()	exact	
+QUEST_LOG_UPDATE	308	signal	()	exact	
+QUEST_PROGRESS	302	signal	()	exact	
+QUEST_WATCH_UPDATE	545	signal2	%d	exact	
+RAID_ROSTER_UPDATE	499	signal	()	exact	
+RAID_TARGET_UPDATE	537	signal	()	exact	
+READY_CHECK	536	signal	()	exact	
+REPLACE_ENCHANT	403	signal2	%s%s	exact	
+RESURRECT_REQUEST	279	signal2	%s	exact	
+SCREENSHOT_FAILED	209	signal	()	exact	
+SCREENSHOT_SUCCEEDED	208		?	none	
+SEND_MAIL_COD_CHANGED	413	signal	()	exact	
+SEND_MAIL_MONEY_CHANGED	412	signal	()	exact	
+SHOW_COMPARE_TOOLTIP	377		?	none	
+SKILL_LINES_CHANGED	265	signal	()	exact	
+SPELLCAST_CHANNEL_START	342	signal2	%d%s	exact	
+SPELLCAST_CHANNEL_STOP	344	signal	()	exact	
+SPELLCAST_CHANNEL_UPDATE	343	signal2	%d	exact	
+SPELLCAST_DELAYED	341	signal2	%d	exact	
+SPELLCAST_FAILED	339		?	none	
+SPELLCAST_INTERRUPTED	340	signal	()	exact	
+SPELLCAST_START	337	signal2	%s%d	exact	
+SPELLCAST_STOP	338	signal	()	exact	
+SPELLS_CHANGED	260	signal	()	exact	
+SPELL_UPDATE_COOLDOWN	262	signal	()	exact	
+SPELL_UPDATE_USABLE	263	signal	()	exact	
+START_AUTOREPEAT_SPELL	435	signal	()	exact	
+START_LOOT_ROLL	505	signal2	%d%d	exact	
+START_MINIGAME	534	signal	()	exact	
+STOP_AUTOREPEAT_SPELL	436	signal	()	exact	
+SYSMSG	223		?	none	
+TABARD_CANSAVE_CHANGED	376	signal	()	exact	
+TABARD_SAVE_PENDING	521	signal	()	exact	
+TAXIMAP_CLOSED	307	signal	()	exact	
+TAXIMAP_OPENED	306	signal	()	exact	
+TIME_PLAYED_MSG	259	signal2	%d%d	exact	
+TRADE_ACCEPT_UPDATE	322	signal2	%d%d	exact	
+TRADE_CLOSED	320	signal	()	exact	
+TRADE_MONEY_CHANGED	325	signal	()	exact	
+TRADE_PLAYER_ITEM_CHANGED	324	signal2	%d	exact	
+TRADE_REPLACE_ENCHANT	404	signal2	%s%s%d	advisory	0x496230 declares more varargs than it pushes — do not copy
+TRADE_REQUEST	285		?	none	
+TRADE_REQUEST_CANCEL	286	signal	()	exact	
+TRADE_SHOW	319	signal	()	exact	
+TRADE_SKILL_CLOSE	315	signal	()	exact	
+TRADE_SKILL_SHOW	313	signal	()	exact	
+TRADE_SKILL_UPDATE	314	signal	()	exact	
+TRADE_TARGET_ITEM_CHANGED	323	signal2	%d	exact	
+TRADE_UPDATE	321	signal	()	exact	
+TRAINER_CLOSED	311	signal	()	exact	
+TRAINER_SHOW	309	signal	()	exact	
+TRAINER_UPDATE	310	signal	()	exact	
+TUTORIAL_TRIGGER	384	signal2	%d	exact	
+UI_ERROR_MESSAGE	224		?	none	
+UI_INFO_MESSAGE	225		?	none	
+UNIT_ATTACK	332	signal2	%s	exact	
+UNIT_ATTACK_POWER	159|160|161	unit-field-bridge	%s	exact	
+UNIT_ATTACK_SPEED	120|121	unit-field-bridge	%s	exact	
+UNIT_AURA	41|107	token-fanout|unit-field-bridge	%s	exact	
+UNIT_CLASSIFICATION_CHANGED	187	token-fanout	%s	exact	
+UNIT_COMBAT	182	signal2	%s%s%s%d%d	exact	
+UNIT_DAMAGE	128|129|130|131	unit-field-bridge	%s	exact	
+UNIT_DEFENSE	333	signal2	%s	exact	
+UNIT_DISPLAYPOWER	30	token-fanout|unit-field-bridge	%s	exact	
+UNIT_DYNAMIC_FLAGS	137	unit-field-bridge	%s	exact	
+UNIT_ENERGY	20	unit-field-bridge	%s	exact	
+UNIT_FACTION	29	token-fanout|unit-field-bridge	%s	exact	
+UNIT_FLAGS	40	unit-field-bridge	%s	exact	
+UNIT_FOCUS	19	unit-field-bridge	%s	exact	
+UNIT_HAPPINESS	21	signal2|unit-field-bridge	%s	exact	
+UNIT_HEALTH	16	signal|token-fanout|unit-field-bridge	%s|()	exact	
+UNIT_INVENTORY_CHANGED	186	signal2|token-fanout	%s	exact	
+UNIT_LEVEL	28	signal2|token-fanout|unit-field-bridge	%s	exact	
+UNIT_LOYALTY	132	unit-field-bridge	%s	exact	
+UNIT_MANA	17|167|174	signal|unit-field-bridge	%s|()	exact	
+UNIT_MAXENERGY	26	unit-field-bridge	%s	exact	
+UNIT_MAXFOCUS	25	signal2|unit-field-bridge	%d%d%d%d%d%d%d%d%d%d|%s	exact	
+UNIT_MAXHAPPINESS	27	unit-field-bridge	%s	exact	
+UNIT_MAXHEALTH	22	token-fanout|unit-field-bridge	%s	exact	
+UNIT_MAXMANA	23	signal2|unit-field-bridge	%s	exact	
+UNIT_MAXRAGE	24	unit-field-bridge	%s	exact	
+UNIT_MODEL_CHANGED	185	token-fanout	%s	exact	
+UNIT_NAME_UPDATE	183	token-fanout	%s	exact	
+UNIT_PET	0|2	signal|signal2|unit-field-bridge	%s|()	exact	
+UNIT_PET_EXPERIENCE	135|136	unit-field-bridge	%s	exact	
+UNIT_PET_TRAINING_POINTS	143	unit-field-bridge	%s	exact	
+UNIT_PORTRAIT_UPDATE	184	token-fanout	%s	exact	
+UNIT_QUEST_LOG_CHANGED	522	token-fanout	%s	exact	
+UNIT_RAGE	18	signal2|unit-field-bridge	%d%d|%s	exact	
+UNIT_RANGEDDAMAGE	122|165|166	unit-field-bridge	%s	exact	
+UNIT_RANGED_ATTACK_POWER	162|163|164	signal2|unit-field-bridge	%s	exact	
+UNIT_RESISTANCES	149|150|151|152|153|154|155	unit-field-bridge	%s	exact	
+UNIT_STATS	144|145|146|147|148	unit-field-bridge	%s	exact	
+UPDATE_BATTLEFIELD_SCORE	420	signal	()	exact	
+UPDATE_BATTLEFIELD_STATUS	419	signal	()	exact	
+UPDATE_BINDINGS	386	signal	()	exact	
+UPDATE_BONUS_ACTIONBAR	217	signal	()	exact	
+UPDATE_CHAT_COLOR	226	signal2	%s%f%f%f	exact	
+UPDATE_CHAT_WINDOWS	395	signal	()	exact	
+UPDATE_EXHAUSTION	406	signal	()	exact	
+UPDATE_FACTION	372	signal	()	exact	
+UPDATE_GM_STATUS	400	signal2	%d	exact	
+UPDATE_INSTANCE_INFO	539	signal	()	exact	
+UPDATE_INVENTORY_ALERTS	501	signal	()	exact	
+UPDATE_LFG	389		?	none	
+UPDATE_LFG_LIST	532	signal	()	exact	
+UPDATE_LFG_TYPES	531	signal	()	exact	
+UPDATE_MACROS	393	signal	()	exact	
+UPDATE_MASTER_LOOT_LIST	504	signal	()	exact	
+UPDATE_MOUSEOVER_UNIT	336	signal	()	exact	
+UPDATE_PENDING_MAIL	500	signal	()	exact	
+UPDATE_SHAPESHIFT_FORMS	387	signal	()	exact	
+UPDATE_TICKET	394	signal2	%d%s|%d%s%f%f%f%d%d	advisory	0x5e4527 declares more varargs than it pushes — do not copy; 0x5e7960 declares more varargs than it pushes — do not copy
+UPDATE_TRADESKILL_RECAST	502	signal	()	exact	
+UPDATE_WORLD_STATES	526	signal	()	exact	
+USE_BIND_CONFIRM	290	signal	()	exact	
+VARIABLES_LOADED	430	signal	()	exact	
+WHO_LIST_UPDATE	388	signal	()	exact	
+WORLD_MAP_NAME_UPDATE	366	signal	()	exact	
+WORLD_MAP_UPDATE	365	signal	()	exact	
+ZONE_CHANGED	203		?	none	
+ZONE_CHANGED_INDOORS	204		?	none	
+ZONE_CHANGED_NEW_AREA	205	signal	()	exact	
diff --git a/reference/1.12-globals.tsv b/reference/1.12-globals.tsv
new file mode 100644
index 00000000..412b537b
--- /dev/null
+++ b/reference/1.12-globals.tsv
@@ -0,0 +1,21562 @@
+# The 1.12.1 client's global namespace. Generated by scripts/gen-reference-globals.py.
+# Source: a capture of the running client's in-world _G (the maintainer's),
+# attributed against the complete 1.12 shipped-UI corpus.
+# Also every name that corpus defines but the capture lacks, as type `lod`: the
+# twelve Blizzard_* addons are LoadOnDemand, so a live dump misses them unless
+# their windows were opened.
+# name	type	origin(lua|engine|framexml)
+ABANDON_PET	string	framexml
+ABANDON_QUEST	string	framexml
+ABANDON_QUEST_CONFIRM	string	framexml
+ABANDON_QUEST_CONFIRM_WITH_ITEMS	string	framexml
+ABILITIES	string	framexml
+ABILITYBOOK_BUTTON	string	framexml
+ABSORB	string	framexml
+ABSORB_TRAILER	string	framexml
+ACCEPT	string	framexml
+ACCOUNT_BINDINGS	lod	framexml
+ACTIONBAR_LABEL	string	framexml
+ADDITIONAL_COMMENTS	string	framexml
+ADDMEMBER	string	framexml
+ADDON_ACTION_FORBIDDEN	string	framexml
+ADDON_BANNED	string	framexml
+ADDON_CORRUPT	string	framexml
+ADDON_DEP_BANNED	string	framexml
+ADDON_DEP_CORRUPT	string	framexml
+ADDON_DEP_DISABLED	string	framexml
+ADDON_DEP_INSECURE	string	framexml
+ADDON_DEP_INTERFACE_VERSION	string	framexml
+ADDON_DEP_MISSING	string	framexml
+ADDON_DEP_NOT_DEMAND_LOADED	string	framexml
+ADDON_DISABLED	string	framexml
+ADDON_INSECURE	string	framexml
+ADDON_INTERFACE_VERSION	string	framexml
+ADDON_LOAD_FAILED	string	framexml
+ADDON_MISSING	string	framexml
+ADDON_NOT_DEMAND_LOADED	string	framexml
+ADDON_UNKNOWN_ERROR	string	framexml
+ADD_CHANNEL	string	framexml
+ADD_CHAT_CHANNEL	string	framexml
+ADD_FRIEND	string	framexml
+ADD_FRIEND_LABEL	string	framexml
+ADD_GUILDMEMBER_LABEL	string	framexml
+ADD_GUILDRANK_LABEL	string	framexml
+ADD_IGNORE_LABEL	string	framexml
+ADD_RAIDMEMBER_LABEL	string	framexml
+ADD_RAID_MEMBER	string	framexml
+ADVANCED_OPTIONS	string	framexml
+ADVANCED_OPTIONS_TOOLTIP	string	framexml
+AGILITY_COLON	string	framexml
+AGILITY_TOOLTIP	string	framexml
+ALL	string	framexml
+ALLIED	string	framexml
+ALL_INVENTORY_SLOTS	string	framexml
+ALL_SUBCLASSES	string	framexml
+ALREADY_LEARNED	string	framexml
+ALWAYS	string	framexml
+ALWAYS_SHOW_MULTIBARS	string	framexml
+ALWAYS_SHOW_MULTIBARS_TEXT	string	framexml
+AMBIENCE_VOLUME	string	framexml
+AMMOSLOT	string	framexml
+AMMO_DAMAGE_TEMPLATE	string	framexml
+AMMO_SCHOOL_DAMAGE_TEMPLATE	string	framexml
+AMOUNT_PAID_COLON	string	framexml
+AMOUNT_RECEIVED_COLON	string	framexml
+AMOUNT_TO_SEND	string	framexml
+ANIMATION	string	framexml
+ANISOTROPIC	string	framexml
+ANISOTROPIC_VALUES	table	framexml
+AREA_SPIRIT_HEAL	string	framexml
+ARMOR	string	framexml
+ARMOR_COLON	string	framexml
+ARMOR_TEMPLATE	string	framexml
+ARMOR_TOOLTIP	string	framexml
+ASSIGNED_COLON	string	framexml
+ASSIST_ATTACK	string	framexml
+ATTACHMENT_TEXT	string	framexml
+ATTACK	string	framexml
+ATTACK_BUTTON_FLASH_TIME	number	framexml
+ATTACK_COLON	string	framexml
+ATTACK_POWER_COLON	string	framexml
+ATTACK_POWER_MAGIC_NUMBER	number	framexml
+ATTACK_POWER_TOOLTIP	string	framexml
+ATTACK_SPEED_COLON	string	framexml
+ATTACK_SPEED_TOOLTIP1	string	framexml
+ATTACK_TOOLTIP	string	framexml
+ATTACK_TOOLTIP_SUBTEXT	string	framexml
+AT_WAR	string	framexml
+AUCTIONS	string	framexml
+AUCTIONS_BUTTON_HEIGHT	lod	framexml
+AUCTION_BUYOUT_ERROR	string	framexml
+AUCTION_CREATOR	string	framexml
+AUCTION_DISPLAY_ON_CHARACTER	lod	framexml
+AUCTION_DURATION	string	framexml
+AUCTION_DURATION_ERROR	string	framexml
+AUCTION_EXPIRED_MAIL_SUBJECT	string	framexml
+AUCTION_HOUSE_CUT_COLON	string	framexml
+AUCTION_ITEM	string	framexml
+AUCTION_ITEM_TEXT	string	framexml
+AUCTION_OUTBID_MAIL_SUBJECT	string	framexml
+AUCTION_REMOVED_MAIL_SUBJECT	string	framexml
+AUCTION_SOLD_MAIL_SUBJECT	string	framexml
+AUCTION_TIMER_UPDATE_DELAY	lod	framexml
+AUCTION_TIME_LEFT1	string	framexml
+AUCTION_TIME_LEFT1_DETAIL	string	framexml
+AUCTION_TIME_LEFT2	string	framexml
+AUCTION_TIME_LEFT2_DETAIL	string	framexml
+AUCTION_TIME_LEFT3	string	framexml
+AUCTION_TIME_LEFT3_DETAIL	string	framexml
+AUCTION_TIME_LEFT4	string	framexml
+AUCTION_TIME_LEFT4_DETAIL	string	framexml
+AUCTION_TITLE	string	framexml
+AUCTION_WON_MAIL_SUBJECT	string	framexml
+AURAADDEDOTHERHARMFUL	string	framexml
+AURAADDEDOTHERHELPFUL	string	framexml
+AURAADDEDSELFHARMFUL	string	framexml
+AURAADDEDSELFHELPFUL	string	framexml
+AURAAPPLICATIONADDEDOTHERHARMFUL	string	framexml
+AURAAPPLICATIONADDEDOTHERHELPFUL	string	framexml
+AURAAPPLICATIONADDEDSELFHARMFUL	string	framexml
+AURAAPPLICATIONADDEDSELFHELPFUL	string	framexml
+AURACHANGEDOTHER	string	framexml
+AURACHANGEDSELF	string	framexml
+AURADISPELOTHER	string	framexml
+AURADISPELSELF	string	framexml
+AURAREMOVEDOTHER	string	framexml
+AURAREMOVEDSELF	string	framexml
+AURASTOLENOTHEROTHER	string	framexml
+AURASTOLENOTHERSELF	string	framexml
+AURASTOLENSELFOTHER	string	framexml
+AURASTOLENSELFSELF	string	framexml
+AURA_END	string	framexml
+AUTOFOLLOWSTART	string	framexml
+AUTOFOLLOWSTOP	string	framexml
+AUTOFOLLOWSTOPCOMBAT	string	framexml
+AUTOFOLLOW_STATUS_FADETIME	number	framexml
+AUTO_FOLLOW_SPEED	string	framexml
+AUTO_JOIN_GUILD_CHANNEL	string	framexml
+AUTO_QUEST_WATCH	string	framexml
+AUTO_QUEST_WATCH_TEXT	string	framexml
+AUTO_SELF_CAST_TEXT	string	framexml
+AVAILABLE	string	framexml
+AVAILABLE_QUESTS	string	framexml
+AVAILABLE_SERVICES	string	framexml
+AVERAGE_WAIT_TIME	string	framexml
+AbandonQuest	function	engine
+AbandonSkill	function	engine
+AcceptAreaSpiritHeal	function	engine
+AcceptBattlefieldPort	function	engine
+AcceptDuel	function	engine
+AcceptGroup	function	engine
+AcceptGuild	function	engine
+AcceptQuest	function	engine
+AcceptResurrect	function	engine
+AcceptSkillUps	function	engine
+AcceptTrade	function	engine
+AcceptXPLoss	function	engine
+ActionBarButtonTemplate	lod	framexml
+ActionBarDownButton	table	framexml
+ActionBarUpButton	table	framexml
+ActionBar_PageDown	function	framexml
+ActionBar_PageUp	function	framexml
+ActionButton1	table	framexml
+ActionButton10	table	framexml
+ActionButton10Border	table	framexml
+ActionButton10Cooldown	table	framexml
+ActionButton10Count	table	framexml
+ActionButton10Flash	table	framexml
+ActionButton10HotKey	table	framexml
+ActionButton10Icon	table	framexml
+ActionButton10Name	table	framexml
+ActionButton10NormalTexture	table	framexml
+ActionButton11	table	framexml
+ActionButton11Border	table	framexml
+ActionButton11Cooldown	table	framexml
+ActionButton11Count	table	framexml
+ActionButton11Flash	table	framexml
+ActionButton11HotKey	table	framexml
+ActionButton11Icon	table	framexml
+ActionButton11Name	table	framexml
+ActionButton11NormalTexture	table	framexml
+ActionButton12	table	framexml
+ActionButton12Border	table	framexml
+ActionButton12Cooldown	table	framexml
+ActionButton12Count	table	framexml
+ActionButton12Flash	table	framexml
+ActionButton12HotKey	table	framexml
+ActionButton12Icon	table	framexml
+ActionButton12Name	table	framexml
+ActionButton12NormalTexture	table	framexml
+ActionButton1Border	table	framexml
+ActionButton1Cooldown	table	framexml
+ActionButton1Count	table	framexml
+ActionButton1Flash	table	framexml
+ActionButton1HotKey	table	framexml
+ActionButton1Icon	table	framexml
+ActionButton1Name	table	framexml
+ActionButton1NormalTexture	table	framexml
+ActionButton2	table	framexml
+ActionButton2Border	table	framexml
+ActionButton2Cooldown	table	framexml
+ActionButton2Count	table	framexml
+ActionButton2Flash	table	framexml
+ActionButton2HotKey	table	framexml
+ActionButton2Icon	table	framexml
+ActionButton2Name	table	framexml
+ActionButton2NormalTexture	table	framexml
+ActionButton3	table	framexml
+ActionButton3Border	table	framexml
+ActionButton3Cooldown	table	framexml
+ActionButton3Count	table	framexml
+ActionButton3Flash	table	framexml
+ActionButton3HotKey	table	framexml
+ActionButton3Icon	table	framexml
+ActionButton3Name	table	framexml
+ActionButton3NormalTexture	table	framexml
+ActionButton4	table	framexml
+ActionButton4Border	table	framexml
+ActionButton4Cooldown	table	framexml
+ActionButton4Count	table	framexml
+ActionButton4Flash	table	framexml
+ActionButton4HotKey	table	framexml
+ActionButton4Icon	table	framexml
+ActionButton4Name	table	framexml
+ActionButton4NormalTexture	table	framexml
+ActionButton5	table	framexml
+ActionButton5Border	table	framexml
+ActionButton5Cooldown	table	framexml
+ActionButton5Count	table	framexml
+ActionButton5Flash	table	framexml
+ActionButton5HotKey	table	framexml
+ActionButton5Icon	table	framexml
+ActionButton5Name	table	framexml
+ActionButton5NormalTexture	table	framexml
+ActionButton6	table	framexml
+ActionButton6Border	table	framexml
+ActionButton6Cooldown	table	framexml
+ActionButton6Count	table	framexml
+ActionButton6Flash	table	framexml
+ActionButton6HotKey	table	framexml
+ActionButton6Icon	table	framexml
+ActionButton6Name	table	framexml
+ActionButton6NormalTexture	table	framexml
+ActionButton7	table	framexml
+ActionButton7Border	table	framexml
+ActionButton7Cooldown	table	framexml
+ActionButton7Count	table	framexml
+ActionButton7Flash	table	framexml
+ActionButton7HotKey	table	framexml
+ActionButton7Icon	table	framexml
+ActionButton7Name	table	framexml
+ActionButton7NormalTexture	table	framexml
+ActionButton8	table	framexml
+ActionButton8Border	table	framexml
+ActionButton8Cooldown	table	framexml
+ActionButton8Count	table	framexml
+ActionButton8Flash	table	framexml
+ActionButton8HotKey	table	framexml
+ActionButton8Icon	table	framexml
+ActionButton8Name	table	framexml
+ActionButton8NormalTexture	table	framexml
+ActionButton9	table	framexml
+ActionButton9Border	table	framexml
+ActionButton9Cooldown	table	framexml
+ActionButton9Count	table	framexml
+ActionButton9Flash	table	framexml
+ActionButton9HotKey	table	framexml
+ActionButton9Icon	table	framexml
+ActionButton9Name	table	framexml
+ActionButton9NormalTexture	table	framexml
+ActionButtonDown	function	framexml
+ActionButtonTemplate	lod	framexml
+ActionButtonUp	function	framexml
+ActionButton_GetPagedID	function	framexml
+ActionButton_HideGrid	function	framexml
+ActionButton_IsFlashing	function	framexml
+ActionButton_OnEvent	function	framexml
+ActionButton_OnLoad	function	framexml
+ActionButton_OnUpdate	function	framexml
+ActionButton_SetTooltip	function	framexml
+ActionButton_ShowGrid	function	framexml
+ActionButton_StartFlash	function	framexml
+ActionButton_StopFlash	function	framexml
+ActionButton_Update	function	framexml
+ActionButton_UpdateCooldown	function	framexml
+ActionButton_UpdateCount	function	framexml
+ActionButton_UpdateFlash	function	framexml
+ActionButton_UpdateHotkeys	function	framexml
+ActionButton_UpdateState	function	framexml
+ActionButton_UpdateUsable	function	framexml
+ActionHasRange	function	engine
+AddChatWindowChannel	function	engine
+AddChatWindowMessages	function	engine
+AddFriend	function	engine
+AddIgnore	function	engine
+AddOrDelIgnore	function	engine
+AddQuestWatch	function	engine
+AddSkillUp	function	engine
+AddTradeMoney	function	engine
+AdvancedOptions	table	framexml
+AdvancedOptionsActionBars	table	framexml
+AdvancedOptionsActionBarsTitle	table	framexml
+AdvancedOptionsChat	table	framexml
+AdvancedOptionsChatTitle	table	framexml
+AdvancedOptionsCombatText	table	framexml
+AdvancedOptionsCombatTextTitle	table	framexml
+AdvancedOptionsRaid	table	framexml
+AdvancedOptionsRaidTitle	table	framexml
+AppendToFile	function	engine
+AssistByName	function	engine
+AssistUnit	function	engine
+AttackTarget	function	engine
+AttributeFrameTemplate	lod	framexml
+AuctionClassButtonTemplate	lod	framexml
+AuctionDressUpBackgroundBot	lod	framexml
+AuctionDressUpBackgroundTop	lod	framexml
+AuctionDressUpFrame	lod	framexml
+AuctionDressUpFrameCloseButton	lod	framexml
+AuctionDressUpFrameResetButton	lod	framexml
+AuctionDressUpFrameTop	lod	framexml
+AuctionDressUpModel	lod	framexml
+AuctionDressUpModelRotateLeftButton	lod	framexml
+AuctionDressUpModelRotateRightButton	lod	framexml
+AuctionFilterButton1	lod	framexml
+AuctionFilterButton10	lod	framexml
+AuctionFilterButton11	lod	framexml
+AuctionFilterButton12	lod	framexml
+AuctionFilterButton13	lod	framexml
+AuctionFilterButton14	lod	framexml
+AuctionFilterButton15	lod	framexml
+AuctionFilterButton2	lod	framexml
+AuctionFilterButton3	lod	framexml
+AuctionFilterButton4	lod	framexml
+AuctionFilterButton5	lod	framexml
+AuctionFilterButton6	lod	framexml
+AuctionFilterButton7	lod	framexml
+AuctionFilterButton8	lod	framexml
+AuctionFilterButton9	lod	framexml
+AuctionFrame	lod	framexml
+AuctionFrameAuctions	lod	framexml
+AuctionFrameAuctions_OnEvent	lod	framexml
+AuctionFrameAuctions_OnLoad	lod	framexml
+AuctionFrameAuctions_OnShow	lod	framexml
+AuctionFrameAuctions_Update	lod	framexml
+AuctionFrameBid	lod	framexml
+AuctionFrameBid_OnEvent	lod	framexml
+AuctionFrameBid_OnLoad	lod	framexml
+AuctionFrameBid_OnShow	lod	framexml
+AuctionFrameBid_Update	lod	framexml
+AuctionFrameBrowse	lod	framexml
+AuctionFrameBrowse_InitClasses	lod	framexml
+AuctionFrameBrowse_OnEvent	lod	framexml
+AuctionFrameBrowse_OnLoad	lod	framexml
+AuctionFrameBrowse_OnShow	lod	framexml
+AuctionFrameBrowse_Search	lod	framexml
+AuctionFrameBrowse_Update	lod	framexml
+AuctionFrameCloseButton	lod	framexml
+AuctionFrameFilter_OnClick	lod	framexml
+AuctionFrameFilters_Update	lod	framexml
+AuctionFrameFilters_UpdateClasses	lod	framexml
+AuctionFrameFilters_UpdateInvTypes	lod	framexml
+AuctionFrameFilters_UpdateSubClasses	lod	framexml
+AuctionFrameItem_OnEnter	lod	framexml
+AuctionFrameMoneyFrame	lod	framexml
+AuctionFrameTab1	lod	framexml
+AuctionFrameTab2	lod	framexml
+AuctionFrameTab3	lod	framexml
+AuctionFrameTab_OnClick	lod	framexml
+AuctionFrame_GetTimeLeftText	lod	framexml
+AuctionFrame_GetTimeLeftTooltipText	lod	framexml
+AuctionFrame_Hide	lod	framexml
+AuctionFrame_LoadUI	function	framexml
+AuctionFrame_OnEvent	lod	framexml
+AuctionFrame_OnLoad	lod	framexml
+AuctionFrame_OnShow	lod	framexml
+AuctionFrame_Show	lod	framexml
+AuctionFrame_UpdateTimeLeft	lod	framexml
+AuctionPortraitTexture	lod	framexml
+AuctionRadioButtonTemplate	lod	framexml
+AuctionSellItemButton_OnEvent	lod	framexml
+AuctionSortButtonTemplate	lod	framexml
+AuctionTabTemplate	lod	framexml
+AuctionsBidSort	lod	framexml
+AuctionsButton1	lod	framexml
+AuctionsButton2	lod	framexml
+AuctionsButton3	lod	framexml
+AuctionsButton4	lod	framexml
+AuctionsButton5	lod	framexml
+AuctionsButton6	lod	framexml
+AuctionsButton7	lod	framexml
+AuctionsButton8	lod	framexml
+AuctionsButton9	lod	framexml
+AuctionsButtonTemplate	lod	framexml
+AuctionsButton_OnClick	lod	framexml
+AuctionsBuyoutErrorText	lod	framexml
+AuctionsBuyoutText	lod	framexml
+AuctionsCancelAuctionButton	lod	framexml
+AuctionsCloseButton	lod	framexml
+AuctionsCreateAuctionButton	lod	framexml
+AuctionsDepositMoneyFrame	lod	framexml
+AuctionsDepositText	lod	framexml
+AuctionsDurationSort	lod	framexml
+AuctionsDurationText	lod	framexml
+AuctionsFrameAuctions_ValidateAuction	lod	framexml
+AuctionsHighBidderSort	lod	framexml
+AuctionsItemButton	lod	framexml
+AuctionsItemText	lod	framexml
+AuctionsLongAuctionButton	lod	framexml
+AuctionsMediumAuctionButton	lod	framexml
+AuctionsNextPageButton	lod	framexml
+AuctionsPrevPageButton	lod	framexml
+AuctionsPriceText	lod	framexml
+AuctionsQualitySort	lod	framexml
+AuctionsRadioButton_OnClick	lod	framexml
+AuctionsScrollFrame	lod	framexml
+AuctionsSearchCountText	lod	framexml
+AuctionsShortAuctionButton	lod	framexml
+AuctionsTabText	lod	framexml
+AuctionsTitle	lod	framexml
+AutoEquipCursorItem	function	engine
+AutoFollowStatus	table	framexml
+AutoFollowStatusText	table	framexml
+AutoFollowStatus_OnEvent	function	framexml
+AutoFollowStatus_OnLoad	function	framexml
+AutoFollowStatus_OnUpdate	function	framexml
+AutoQuestWatch_CheckDeleted	function	framexml
+AutoQuestWatch_Insert	function	framexml
+AutoQuestWatch_OnUpdate	function	framexml
+AutoQuestWatch_Update	function	framexml
+AvailableQuestsText	table	framexml
+AvailableServicesText	table	framexml
+BACK	string	framexml
+BACKGROUND	string	framexml
+BACKPACK_TOOLTIP	string	framexml
+BACKSLOT	string	framexml
+BAGSLOT	string	framexml
+BAGSLOTTEXT	string	framexml
+BAGS_ONLY	string	framexml
+BAG_CANT_STACK	string	framexml
+BAG_CANT_SWAP	string	framexml
+BAG_DROP_TOO_FAR_AWAY	string	framexml
+BAG_ERROR	string	framexml
+BAG_FULL	string	framexml
+BAG_ITEM_ALREADY_BOUND	string	framexml
+BAG_ITEM_CLASS_MISMATCH	string	framexml
+BAG_ITEM_MAX_COUNT_EXCEEDED	string	framexml
+BAG_ITEM_NOT_FOUND	string	framexml
+BAG_ITEM_SPLIT_FAILED	string	framexml
+BAG_ITEM_SUBTYPE_MISMATCH	string	framexml
+BAG_ITEM_TOO_FEW_TO_SPLIT	string	framexml
+BAG_NOT_A_CONTAINER	string	framexml
+BAG_NOT_EMPTY	string	framexml
+BAG_NOT_ENOUGH_GOLD	string	framexml
+BAG_NOT_EQUIPPABLE	string	framexml
+BAG_NOT_OWNER	string	framexml
+BAG_SLOT_EMPTY	string	framexml
+BAG_SLOT_NOT_EMPTY	string	framexml
+BANKSLOTPURCHASE	string	framexml
+BANKSLOTPURCHASE_LABEL	string	framexml
+BANK_BAG	string	framexml
+BANK_BAG_PURCHASE	string	framexml
+BANK_CONTAINER	number	framexml
+BASIC_LABEL	string	framexml
+BASIC_OPTIONS_TOOLTIP	string	framexml
+BATTLEFIELDMINIMAP_OPACITY_LABEL	string	framexml
+BATTLEFIELDMINIMAP_OPTIONS_LABEL	string	framexml
+BATTLEFIELDS	string	framexml
+BATTLEFIELD_CONFIRM_STATUS	string	framexml
+BATTLEFIELD_FULL	string	framexml
+BATTLEFIELD_GROUP_JOIN	string	framexml
+BATTLEFIELD_IN_BATTLEFIELD	string	framexml
+BATTLEFIELD_IN_QUEUE	string	framexml
+BATTLEFIELD_JOIN	string	framexml
+BATTLEFIELD_LEVEL	string	framexml
+BATTLEFIELD_MAP_HEIGHT	number	framexml
+BATTLEFIELD_MAP_WIDTH	number	framexml
+BATTLEFIELD_MINIMAP	string	framexml
+BATTLEFIELD_MINIMAP_UPDATE_RATE	lod	framexml
+BATTLEFIELD_NAME	string	framexml
+BATTLEFIELD_QUEUE_CONFIRM	string	framexml
+BATTLEFIELD_QUEUE_STATUS	string	framexml
+BATTLEFIELD_SHUTDOWN_TIMER	number	framexml
+BATTLEFIELD_TAB_FADE_TIME	lod	framexml
+BATTLEFIELD_TAB_OFFSET_Y	number	framexml
+BATTLEFIELD_TAB_SHOW_DELAY	lod	framexml
+BATTLEFIELD_TIMER_DELAY	number	framexml
+BATTLEFIELD_TIMER_THRESHOLDS	table	framexml
+BATTLEFIELD_TIMER_THRESHOLD_INDEX	number	framexml
+BATTLEFIELD_ZONES_DISPLAYED	number	framexml
+BATTLEFIELD_ZONES_HEIGHT	number	framexml
+BATTLEGROUND_INSTANCE_TOOLTIP	string	framexml
+BG_TEXTURE_HEIGHT	number	framexml
+BID	string	framexml
+BIDS	string	framexml
+BID_STATUS	string	framexml
+BILLING_NAG_DIALOG	string	framexml
+BILLING_NAG_WARNING	string	framexml
+BILLING_NAG_WARNING_P1	string	framexml
+BINDING_HEADER_ACTIONBAR	string	framexml
+BINDING_HEADER_BLANK	string	framexml
+BINDING_HEADER_CAMERA	string	framexml
+BINDING_HEADER_CHAT	string	framexml
+BINDING_HEADER_INTERFACE	string	framexml
+BINDING_HEADER_ITUNES_REMOTE	string	framexml
+BINDING_HEADER_MISC	string	framexml
+BINDING_HEADER_MOVEMENT	string	framexml
+BINDING_HEADER_MULTIACTIONBAR	string	framexml
+BINDING_HEADER_RAID_TARGET	string	framexml
+BINDING_HEADER_TARGETING	string	framexml
+BINDING_NAME_ACTIONBUTTON1	string	framexml
+BINDING_NAME_ACTIONBUTTON10	string	framexml
+BINDING_NAME_ACTIONBUTTON11	string	framexml
+BINDING_NAME_ACTIONBUTTON12	string	framexml
+BINDING_NAME_ACTIONBUTTON2	string	framexml
+BINDING_NAME_ACTIONBUTTON3	string	framexml
+BINDING_NAME_ACTIONBUTTON4	string	framexml
+BINDING_NAME_ACTIONBUTTON5	string	framexml
+BINDING_NAME_ACTIONBUTTON6	string	framexml
+BINDING_NAME_ACTIONBUTTON7	string	framexml
+BINDING_NAME_ACTIONBUTTON8	string	framexml
+BINDING_NAME_ACTIONBUTTON9	string	framexml
+BINDING_NAME_ACTIONPAGE1	string	framexml
+BINDING_NAME_ACTIONPAGE2	string	framexml
+BINDING_NAME_ACTIONPAGE3	string	framexml
+BINDING_NAME_ACTIONPAGE4	string	framexml
+BINDING_NAME_ACTIONPAGE5	string	framexml
+BINDING_NAME_ACTIONPAGE6	string	framexml
+BINDING_NAME_ALLNAMEPLATES	string	framexml
+BINDING_NAME_ASSISTTARGET	string	framexml
+BINDING_NAME_ATTACKTARGET	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON1	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON10	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON2	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON3	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON4	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON5	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON6	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON7	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON8	string	framexml
+BINDING_NAME_BONUSACTIONBUTTON9	string	framexml
+BINDING_NAME_CAMERAZOOMIN	string	framexml
+BINDING_NAME_CAMERAZOOMOUT	string	framexml
+BINDING_NAME_CHATBOTTOM	string	framexml
+BINDING_NAME_CHATPAGEDOWN	string	framexml
+BINDING_NAME_CHATPAGEUP	string	framexml
+BINDING_NAME_COMBATLOGBOTTOM	string	framexml
+BINDING_NAME_COMBATLOGPAGEDOWN	string	framexml
+BINDING_NAME_COMBATLOGPAGEUP	string	framexml
+BINDING_NAME_FLIPCAMERAYAW	string	framexml
+BINDING_NAME_FOLLOWTARGET	string	framexml
+BINDING_NAME_FRIENDNAMEPLATES	string	framexml
+BINDING_NAME_ITUNES_BACKTRACK	string	framexml
+BINDING_NAME_ITUNES_NEXTTRACK	string	framexml
+BINDING_NAME_ITUNES_PLAYPAUSE	string	framexml
+BINDING_NAME_ITUNES_VOLUMEDOWN	string	framexml
+BINDING_NAME_ITUNES_VOLUMEUP	string	framexml
+BINDING_NAME_JUMP	string	framexml
+BINDING_NAME_MASTERVOLUMEDOWN	string	framexml
+BINDING_NAME_MASTERVOLUMEUP	string	framexml
+BINDING_NAME_MINIMAPZOOMIN	string	framexml
+BINDING_NAME_MINIMAPZOOMOUT	string	framexml
+BINDING_NAME_MOVEANDSTEER	string	framexml
+BINDING_NAME_MOVEBACKWARD	string	framexml
+BINDING_NAME_MOVEFORWARD	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON1	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON10	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON11	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON12	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON2	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON3	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON4	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON5	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON6	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON7	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON8	string	framexml
+BINDING_NAME_MULTIACTIONBAR1BUTTON9	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON1	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON10	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON11	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON12	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON2	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON3	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON4	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON5	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON6	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON7	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON8	string	framexml
+BINDING_NAME_MULTIACTIONBAR2BUTTON9	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON1	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON10	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON11	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON12	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON2	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON3	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON4	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON5	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON6	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON7	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON8	string	framexml
+BINDING_NAME_MULTIACTIONBAR3BUTTON9	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON1	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON10	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON11	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON12	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON2	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON3	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON4	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON5	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON6	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON7	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON8	string	framexml
+BINDING_NAME_MULTIACTIONBAR4BUTTON9	string	framexml
+BINDING_NAME_NAMEPLATES	string	framexml
+BINDING_NAME_NEXTACTIONPAGE	string	framexml
+BINDING_NAME_NEXTVIEW	string	framexml
+BINDING_NAME_OPENALLBAGS	string	framexml
+BINDING_NAME_OPENCHAT	string	framexml
+BINDING_NAME_OPENCHATSLASH	string	framexml
+BINDING_NAME_PETATTACK	string	framexml
+BINDING_NAME_PITCHDOWN	string	framexml
+BINDING_NAME_PITCHUP	string	framexml
+BINDING_NAME_PREVIOUSACTIONPAGE	string	framexml
+BINDING_NAME_PREVVIEW	string	framexml
+BINDING_NAME_RAIDTARGET1	string	framexml
+BINDING_NAME_RAIDTARGET2	string	framexml
+BINDING_NAME_RAIDTARGET3	string	framexml
+BINDING_NAME_RAIDTARGET4	string	framexml
+BINDING_NAME_RAIDTARGET5	string	framexml
+BINDING_NAME_RAIDTARGET6	string	framexml
+BINDING_NAME_RAIDTARGET7	string	framexml
+BINDING_NAME_RAIDTARGET8	string	framexml
+BINDING_NAME_RAIDTARGETNONE	string	framexml
+BINDING_NAME_REPLY	string	framexml
+BINDING_NAME_REPLY2	string	framexml
+BINDING_NAME_RESETVIEW1	string	framexml
+BINDING_NAME_RESETVIEW2	string	framexml
+BINDING_NAME_RESETVIEW3	string	framexml
+BINDING_NAME_RESETVIEW4	string	framexml
+BINDING_NAME_RESETVIEW5	string	framexml
+BINDING_NAME_SAVEVIEW1	string	framexml
+BINDING_NAME_SAVEVIEW2	string	framexml
+BINDING_NAME_SAVEVIEW3	string	framexml
+BINDING_NAME_SAVEVIEW4	string	framexml
+BINDING_NAME_SAVEVIEW5	string	framexml
+BINDING_NAME_SCREENSHOT	string	framexml
+BINDING_NAME_SELFACTIONBUTTON1	string	framexml
+BINDING_NAME_SELFACTIONBUTTON10	string	framexml
+BINDING_NAME_SELFACTIONBUTTON11	string	framexml
+BINDING_NAME_SELFACTIONBUTTON12	string	framexml
+BINDING_NAME_SELFACTIONBUTTON2	string	framexml
+BINDING_NAME_SELFACTIONBUTTON3	string	framexml
+BINDING_NAME_SELFACTIONBUTTON4	string	framexml
+BINDING_NAME_SELFACTIONBUTTON5	string	framexml
+BINDING_NAME_SELFACTIONBUTTON6	string	framexml
+BINDING_NAME_SELFACTIONBUTTON7	string	framexml
+BINDING_NAME_SELFACTIONBUTTON8	string	framexml
+BINDING_NAME_SELFACTIONBUTTON9	string	framexml
+BINDING_NAME_SETVIEW1	string	framexml
+BINDING_NAME_SETVIEW2	string	framexml
+BINDING_NAME_SETVIEW3	string	framexml
+BINDING_NAME_SETVIEW4	string	framexml
+BINDING_NAME_SETVIEW5	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON1	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON10	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON2	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON3	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON4	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON5	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON6	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON7	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON8	string	framexml
+BINDING_NAME_SHAPESHIFTBUTTON9	string	framexml
+BINDING_NAME_SITORSTAND	string	framexml
+BINDING_NAME_STRAFELEFT	string	framexml
+BINDING_NAME_STRAFERIGHT	string	framexml
+BINDING_NAME_TARGETLASTHOSTILE	string	framexml
+BINDING_NAME_TARGETNEARESTENEMY	string	framexml
+BINDING_NAME_TARGETNEARESTFRIEND	string	framexml
+BINDING_NAME_TARGETPARTYMEMBER1	string	framexml
+BINDING_NAME_TARGETPARTYMEMBER2	string	framexml
+BINDING_NAME_TARGETPARTYMEMBER3	string	framexml
+BINDING_NAME_TARGETPARTYMEMBER4	string	framexml
+BINDING_NAME_TARGETPARTYPET1	string	framexml
+BINDING_NAME_TARGETPARTYPET2	string	framexml
+BINDING_NAME_TARGETPARTYPET3	string	framexml
+BINDING_NAME_TARGETPARTYPET4	string	framexml
+BINDING_NAME_TARGETPET	string	framexml
+BINDING_NAME_TARGETPREVIOUSENEMY	string	framexml
+BINDING_NAME_TARGETPREVIOUSFRIEND	string	framexml
+BINDING_NAME_TARGETSELF	string	framexml
+BINDING_NAME_TOGGLEABILITYBOOK	string	framexml
+BINDING_NAME_TOGGLEACTIONBARLOCK	string	framexml
+BINDING_NAME_TOGGLEAUTORUN	string	framexml
+BINDING_NAME_TOGGLEAUTOSELFCAST	string	framexml
+BINDING_NAME_TOGGLEBACKPACK	string	framexml
+BINDING_NAME_TOGGLEBAG1	string	framexml
+BINDING_NAME_TOGGLEBAG2	string	framexml
+BINDING_NAME_TOGGLEBAG3	string	framexml
+BINDING_NAME_TOGGLEBAG4	string	framexml
+BINDING_NAME_TOGGLEBAG5	string	framexml
+BINDING_NAME_TOGGLEBATTLEFIELDMINIMAP	string	framexml
+BINDING_NAME_TOGGLECHARACTER0	string	framexml
+BINDING_NAME_TOGGLECHARACTER1	string	framexml
+BINDING_NAME_TOGGLECHARACTER2	string	framexml
+BINDING_NAME_TOGGLECHARACTER3	string	framexml
+BINDING_NAME_TOGGLECHARACTER4	string	framexml
+BINDING_NAME_TOGGLECOMBATLOG	string	framexml
+BINDING_NAME_TOGGLEFPS	string	framexml
+BINDING_NAME_TOGGLEFRIENDSTAB	string	framexml
+BINDING_NAME_TOGGLEGAMEMENU	string	framexml
+BINDING_NAME_TOGGLEGUILDTAB	string	framexml
+BINDING_NAME_TOGGLEIGNORETAB	string	framexml
+BINDING_NAME_TOGGLEKEYRING	string	framexml
+BINDING_NAME_TOGGLEMINIMAP	string	framexml
+BINDING_NAME_TOGGLEMUSIC	string	framexml
+BINDING_NAME_TOGGLEPETBOOK	string	framexml
+BINDING_NAME_TOGGLEQUESTLOG	string	framexml
+BINDING_NAME_TOGGLERAIDTAB	string	framexml
+BINDING_NAME_TOGGLERUN	string	framexml
+BINDING_NAME_TOGGLESHEATH	string	framexml
+BINDING_NAME_TOGGLESOCIAL	string	framexml
+BINDING_NAME_TOGGLESOUND	string	framexml
+BINDING_NAME_TOGGLESPELLBOOK	string	framexml
+BINDING_NAME_TOGGLETALENTS	string	framexml
+BINDING_NAME_TOGGLEUI	string	framexml
+BINDING_NAME_TOGGLEWHOTAB	string	framexml
+BINDING_NAME_TOGGLEWORLDMAP	string	framexml
+BINDING_NAME_TOGGLEWORLDSTATESCORES	string	framexml
+BINDING_NAME_TURNLEFT	string	framexml
+BINDING_NAME_TURNRIGHT	string	framexml
+BIND_ENCHANT	string	framexml
+BIND_KEY_TO_COMMAND	string	framexml
+BIND_ZONE_DISPLAY	string	framexml
+BLOCK	string	framexml
+BLOCK_TRADES	string	framexml
+BLOCK_TRAILER	string	framexml
+BLx	lod	framexml
+BLy	lod	framexml
+BONUSACTIONBAR_SLIDETIME	number	framexml
+BONUSACTIONBAR_XPOS	number	framexml
+BONUSACTIONBAR_YPOS	number	framexml
+BOOKTYPE_PET	string	framexml
+BOOKTYPE_SPELL	string	framexml
+BOSS	string	framexml
+BOTTOMLEFT_ACTIONBAR_PAGE	number	framexml
+BOTTOMRIGHT_ACTIONBAR_PAGE	number	framexml
+BREATH_LABEL	string	framexml
+BROWSE	string	framexml
+BROWSE_AUCTIONS	string	framexml
+BROWSE_FILTER_HEIGHT	lod	framexml
+BROWSE_NO_RESULTS	string	framexml
+BROWSE_SEARCH_TEXT	string	framexml
+BRx	lod	framexml
+BRy	lod	framexml
+BUFFERING	string	framexml
+BUFFER_DOUBLE	string	framexml
+BUFF_ALPHA_VALUE	number	framexml
+BUFF_DURATION_WARNING_TIME	number	framexml
+BUFF_FLASH_TIME_OFF	number	framexml
+BUFF_FLASH_TIME_ON	number	framexml
+BUFF_MIN_ALPHA	number	framexml
+BUFF_WARNING_TIME	number	framexml
+BUG_BUTTON	string	framexml
+BUG_CATEGORY1	string	framexml
+BUG_CATEGORY10	string	framexml
+BUG_CATEGORY11	string	framexml
+BUG_CATEGORY12	string	framexml
+BUG_CATEGORY13	string	framexml
+BUG_CATEGORY14	string	framexml
+BUG_CATEGORY15	string	framexml
+BUG_CATEGORY2	string	framexml
+BUG_CATEGORY3	string	framexml
+BUG_CATEGORY4	string	framexml
+BUG_CATEGORY5	string	framexml
+BUG_CATEGORY6	string	framexml
+BUG_CATEGORY7	string	framexml
+BUG_CATEGORY8	string	framexml
+BUG_CATEGORY9	string	framexml
+BUG_CATEGORY_CHOOSE	string	framexml
+BUG_CATEGORY_ERROR	string	framexml
+BUG_SUBMITTED	string	framexml
+BUG_SUBMIT_FAILED	string	framexml
+BUYBACK	string	framexml
+BUYBACK_ITEMS_PER_PAGE	number	framexml
+BUYBACK_THIS_ITEM	string	framexml
+BUYOUT	string	framexml
+BUYOUT_AUCTION_CONFIRMATION	string	framexml
+BUYOUT_COST	string	framexml
+BUYOUT_PRICE	string	framexml
+BackpackButton_OnClick	function	framexml
+BagSlotButtonTemplate	lod	framexml
+BagSlotButton_OnClick	function	framexml
+BagSlotButton_OnDrag	function	framexml
+BagSlotButton_OnEnter	function	framexml
+BagSlotButton_OnShiftClick	function	framexml
+BankButtonIDToInvSlotID	function	engine
+BankCloseButton	table	framexml
+BankFrame	table	framexml
+BankFrameBag1	table	framexml
+BankFrameBag1Count	table	framexml
+BankFrameBag1HighlightFrame	table	framexml
+BankFrameBag1HighlightFrameTexture	table	framexml
+BankFrameBag1IconTexture	table	framexml
+BankFrameBag1NormalTexture	table	framexml
+BankFrameBag1Stock	table	framexml
+BankFrameBag2	table	framexml
+BankFrameBag2Count	table	framexml
+BankFrameBag2HighlightFrame	table	framexml
+BankFrameBag2HighlightFrameTexture	table	framexml
+BankFrameBag2IconTexture	table	framexml
+BankFrameBag2NormalTexture	table	framexml
+BankFrameBag2Stock	table	framexml
+BankFrameBag3	table	framexml
+BankFrameBag3Count	table	framexml
+BankFrameBag3HighlightFrame	table	framexml
+BankFrameBag3HighlightFrameTexture	table	framexml
+BankFrameBag3IconTexture	table	framexml
+BankFrameBag3NormalTexture	table	framexml
+BankFrameBag3Stock	table	framexml
+BankFrameBag4	table	framexml
+BankFrameBag4Count	table	framexml
+BankFrameBag4HighlightFrame	table	framexml
+BankFrameBag4HighlightFrameTexture	table	framexml
+BankFrameBag4IconTexture	table	framexml
+BankFrameBag4NormalTexture	table	framexml
+BankFrameBag4Stock	table	framexml
+BankFrameBag5	table	framexml
+BankFrameBag5Count	table	framexml
+BankFrameBag5HighlightFrame	table	framexml
+BankFrameBag5HighlightFrameTexture	table	framexml
+BankFrameBag5IconTexture	table	framexml
+BankFrameBag5NormalTexture	table	framexml
+BankFrameBag5Stock	table	framexml
+BankFrameBag6	table	framexml
+BankFrameBag6Count	table	framexml
+BankFrameBag6HighlightFrame	table	framexml
+BankFrameBag6HighlightFrameTexture	table	framexml
+BankFrameBag6IconTexture	table	framexml
+BankFrameBag6NormalTexture	table	framexml
+BankFrameBag6Stock	table	framexml
+BankFrameBagButton_OnLoad	function	framexml
+BankFrameBaseButton_OnLoad	function	framexml
+BankFrameDetailMoneyFrame	table	framexml
+BankFrameDetailMoneyFrameCopperButton	table	framexml
+BankFrameDetailMoneyFrameCopperButtonText	table	framexml
+BankFrameDetailMoneyFrameGoldButton	table	framexml
+BankFrameDetailMoneyFrameGoldButtonText	table	framexml
+BankFrameDetailMoneyFrameSilverButton	table	framexml
+BankFrameDetailMoneyFrameSilverButtonText	table	framexml
+BankFrameItem1	table	framexml
+BankFrameItem10	table	framexml
+BankFrameItem10Count	table	framexml
+BankFrameItem10IconTexture	table	framexml
+BankFrameItem10NormalTexture	table	framexml
+BankFrameItem10Stock	table	framexml
+BankFrameItem11	table	framexml
+BankFrameItem11Count	table	framexml
+BankFrameItem11IconTexture	table	framexml
+BankFrameItem11NormalTexture	table	framexml
+BankFrameItem11Stock	table	framexml
+BankFrameItem12	table	framexml
+BankFrameItem12Count	table	framexml
+BankFrameItem12IconTexture	table	framexml
+BankFrameItem12NormalTexture	table	framexml
+BankFrameItem12Stock	table	framexml
+BankFrameItem13	table	framexml
+BankFrameItem13Count	table	framexml
+BankFrameItem13IconTexture	table	framexml
+BankFrameItem13NormalTexture	table	framexml
+BankFrameItem13Stock	table	framexml
+BankFrameItem14	table	framexml
+BankFrameItem14Count	table	framexml
+BankFrameItem14IconTexture	table	framexml
+BankFrameItem14NormalTexture	table	framexml
+BankFrameItem14Stock	table	framexml
+BankFrameItem15	table	framexml
+BankFrameItem15Count	table	framexml
+BankFrameItem15IconTexture	table	framexml
+BankFrameItem15NormalTexture	table	framexml
+BankFrameItem15Stock	table	framexml
+BankFrameItem16	table	framexml
+BankFrameItem16Count	table	framexml
+BankFrameItem16IconTexture	table	framexml
+BankFrameItem16NormalTexture	table	framexml
+BankFrameItem16Stock	table	framexml
+BankFrameItem17	table	framexml
+BankFrameItem17Count	table	framexml
+BankFrameItem17IconTexture	table	framexml
+BankFrameItem17NormalTexture	table	framexml
+BankFrameItem17Stock	table	framexml
+BankFrameItem18	table	framexml
+BankFrameItem18Count	table	framexml
+BankFrameItem18IconTexture	table	framexml
+BankFrameItem18NormalTexture	table	framexml
+BankFrameItem18Stock	table	framexml
+BankFrameItem19	table	framexml
+BankFrameItem19Count	table	framexml
+BankFrameItem19IconTexture	table	framexml
+BankFrameItem19NormalTexture	table	framexml
+BankFrameItem19Stock	table	framexml
+BankFrameItem1Count	table	framexml
+BankFrameItem1IconTexture	table	framexml
+BankFrameItem1NormalTexture	table	framexml
+BankFrameItem1Stock	table	framexml
+BankFrameItem2	table	framexml
+BankFrameItem20	table	framexml
+BankFrameItem20Count	table	framexml
+BankFrameItem20IconTexture	table	framexml
+BankFrameItem20NormalTexture	table	framexml
+BankFrameItem20Stock	table	framexml
+BankFrameItem21	table	framexml
+BankFrameItem21Count	table	framexml
+BankFrameItem21IconTexture	table	framexml
+BankFrameItem21NormalTexture	table	framexml
+BankFrameItem21Stock	table	framexml
+BankFrameItem22	table	framexml
+BankFrameItem22Count	table	framexml
+BankFrameItem22IconTexture	table	framexml
+BankFrameItem22NormalTexture	table	framexml
+BankFrameItem22Stock	table	framexml
+BankFrameItem23	table	framexml
+BankFrameItem23Count	table	framexml
+BankFrameItem23IconTexture	table	framexml
+BankFrameItem23NormalTexture	table	framexml
+BankFrameItem23Stock	table	framexml
+BankFrameItem24	table	framexml
+BankFrameItem24Count	table	framexml
+BankFrameItem24IconTexture	table	framexml
+BankFrameItem24NormalTexture	table	framexml
+BankFrameItem24Stock	table	framexml
+BankFrameItem2Count	table	framexml
+BankFrameItem2IconTexture	table	framexml
+BankFrameItem2NormalTexture	table	framexml
+BankFrameItem2Stock	table	framexml
+BankFrameItem3	table	framexml
+BankFrameItem3Count	table	framexml
+BankFrameItem3IconTexture	table	framexml
+BankFrameItem3NormalTexture	table	framexml
+BankFrameItem3Stock	table	framexml
+BankFrameItem4	table	framexml
+BankFrameItem4Count	table	framexml
+BankFrameItem4IconTexture	table	framexml
+BankFrameItem4NormalTexture	table	framexml
+BankFrameItem4Stock	table	framexml
+BankFrameItem5	table	framexml
+BankFrameItem5Count	table	framexml
+BankFrameItem5IconTexture	table	framexml
+BankFrameItem5NormalTexture	table	framexml
+BankFrameItem5Stock	table	framexml
+BankFrameItem6	table	framexml
+BankFrameItem6Count	table	framexml
+BankFrameItem6IconTexture	table	framexml
+BankFrameItem6NormalTexture	table	framexml
+BankFrameItem6Stock	table	framexml
+BankFrameItem7	table	framexml
+BankFrameItem7Count	table	framexml
+BankFrameItem7IconTexture	table	framexml
+BankFrameItem7NormalTexture	table	framexml
+BankFrameItem7Stock	table	framexml
+BankFrameItem8	table	framexml
+BankFrameItem8Count	table	framexml
+BankFrameItem8IconTexture	table	framexml
+BankFrameItem8NormalTexture	table	framexml
+BankFrameItem8Stock	table	framexml
+BankFrameItem9	table	framexml
+BankFrameItem9Count	table	framexml
+BankFrameItem9IconTexture	table	framexml
+BankFrameItem9NormalTexture	table	framexml
+BankFrameItem9Stock	table	framexml
+BankFrameItemButtonBag_OnClick	function	framexml
+BankFrameItemButtonBag_OnShiftClick	function	framexml
+BankFrameItemButtonGeneric_OnClick	function	framexml
+BankFrameItemButton_OnEvent	function	framexml
+BankFrameItemButton_OnLoad	function	framexml
+BankFrameItemButton_OnUpdate	function	framexml
+BankFrameItemButton_UpdateLock	function	framexml
+BankFrameMoneyFrame	table	framexml
+BankFrameMoneyFrameCopperButton	table	framexml
+BankFrameMoneyFrameCopperButtonText	table	framexml
+BankFrameMoneyFrameGoldButton	table	framexml
+BankFrameMoneyFrameGoldButtonText	table	framexml
+BankFrameMoneyFrameSilverButton	table	framexml
+BankFrameMoneyFrameSilverButtonText	table	framexml
+BankFramePurchaseButton	table	framexml
+BankFramePurchaseButtonText	table	framexml
+BankFramePurchaseInfo	table	framexml
+BankFrameSlotCost	table	framexml
+BankFrameTitleText	table	framexml
+BankFrame_OnEvent	function	framexml
+BankFrame_OnLoad	function	framexml
+BankItemButtonBagTemplate	lod	framexml
+BankItemButtonGenericTemplate	lod	framexml
+BankItemButtonTemplate	lod	framexml
+BankPortraitTexture	table	framexml
+BasicOptions	table	framexml
+BasicOptionsCamera	table	framexml
+BasicOptionsCameraTitle	table	framexml
+BasicOptionsDisplay	table	framexml
+BasicOptionsDisplayTitle	table	framexml
+BasicOptionsGeneral	table	framexml
+BasicOptionsGeneralTitle	table	framexml
+BasicOptionsHelp	table	framexml
+BasicOptionsHelpTitle	table	framexml
+BattlefieldButtonTemplate	lod	framexml
+BattlefieldButton_OnClick	function	framexml
+BattlefieldFrame	table	framexml
+BattlefieldFrameCancelButton	table	framexml
+BattlefieldFrameCancelButtonText	table	framexml
+BattlefieldFrameCloseButton	table	framexml
+BattlefieldFrameFrameLabel	table	framexml
+BattlefieldFrameGroupJoinButton	table	framexml
+BattlefieldFrameGroupJoinButtonText	table	framexml
+BattlefieldFrameJoinButton	table	framexml
+BattlefieldFrameJoinButtonText	table	framexml
+BattlefieldFrameJoinButton_OnClick	function	framexml
+BattlefieldFrameNameHeader	table	framexml
+BattlefieldFramePortrait	table	framexml
+BattlefieldFrameZoneDescription	table	framexml
+BattlefieldFrame_OnEvent	function	framexml
+BattlefieldFrame_OnLoad	function	framexml
+BattlefieldFrame_OnUpdate	function	framexml
+BattlefieldFrame_Update	function	framexml
+BattlefieldFrame_UpdateStatus	function	framexml
+BattlefieldListScrollFrame	table	framexml
+BattlefieldListScrollFrameScrollBar	table	framexml
+BattlefieldListScrollFrameScrollBarScrollDownButton	table	framexml
+BattlefieldListScrollFrameScrollBarScrollUpButton	table	framexml
+BattlefieldListScrollFrameScrollBarThumbTexture	table	framexml
+BattlefieldListScrollFrameScrollChildFrame	table	framexml
+BattlefieldMinimap	lod	framexml
+BattlefieldMinimap1	lod	framexml
+BattlefieldMinimap10	lod	framexml
+BattlefieldMinimap11	lod	framexml
+BattlefieldMinimap12	lod	framexml
+BattlefieldMinimap2	lod	framexml
+BattlefieldMinimap3	lod	framexml
+BattlefieldMinimap4	lod	framexml
+BattlefieldMinimap5	lod	framexml
+BattlefieldMinimap6	lod	framexml
+BattlefieldMinimap7	lod	framexml
+BattlefieldMinimap8	lod	framexml
+BattlefieldMinimap9	lod	framexml
+BattlefieldMinimapBackground	lod	framexml
+BattlefieldMinimapCloseButton	lod	framexml
+BattlefieldMinimapCorner	lod	framexml
+BattlefieldMinimapCorpse	lod	framexml
+BattlefieldMinimapDefaults	lod	framexml
+BattlefieldMinimapDropDown_Initialize	lod	framexml
+BattlefieldMinimapFlag1	lod	framexml
+BattlefieldMinimapFlag2	lod	framexml
+BattlefieldMinimapOptions	lod	framexml
+BattlefieldMinimapParty1	lod	framexml
+BattlefieldMinimapParty2	lod	framexml
+BattlefieldMinimapParty3	lod	framexml
+BattlefieldMinimapParty4	lod	framexml
+BattlefieldMinimapRaid1	lod	framexml
+BattlefieldMinimapRaid10	lod	framexml
+BattlefieldMinimapRaid11	lod	framexml
+BattlefieldMinimapRaid12	lod	framexml
+BattlefieldMinimapRaid13	lod	framexml
+BattlefieldMinimapRaid14	lod	framexml
+BattlefieldMinimapRaid15	lod	framexml
+BattlefieldMinimapRaid16	lod	framexml
+BattlefieldMinimapRaid17	lod	framexml
+BattlefieldMinimapRaid18	lod	framexml
+BattlefieldMinimapRaid19	lod	framexml
+BattlefieldMinimapRaid2	lod	framexml
+BattlefieldMinimapRaid20	lod	framexml
+BattlefieldMinimapRaid21	lod	framexml
+BattlefieldMinimapRaid22	lod	framexml
+BattlefieldMinimapRaid23	lod	framexml
+BattlefieldMinimapRaid24	lod	framexml
+BattlefieldMinimapRaid25	lod	framexml
+BattlefieldMinimapRaid26	lod	framexml
+BattlefieldMinimapRaid27	lod	framexml
+BattlefieldMinimapRaid28	lod	framexml
+BattlefieldMinimapRaid29	lod	framexml
+BattlefieldMinimapRaid3	lod	framexml
+BattlefieldMinimapRaid30	lod	framexml
+BattlefieldMinimapRaid31	lod	framexml
+BattlefieldMinimapRaid32	lod	framexml
+BattlefieldMinimapRaid33	lod	framexml
+BattlefieldMinimapRaid34	lod	framexml
+BattlefieldMinimapRaid35	lod	framexml
+BattlefieldMinimapRaid36	lod	framexml
+BattlefieldMinimapRaid37	lod	framexml
+BattlefieldMinimapRaid38	lod	framexml
+BattlefieldMinimapRaid39	lod	framexml
+BattlefieldMinimapRaid4	lod	framexml
+BattlefieldMinimapRaid40	lod	framexml
+BattlefieldMinimapRaid5	lod	framexml
+BattlefieldMinimapRaid6	lod	framexml
+BattlefieldMinimapRaid7	lod	framexml
+BattlefieldMinimapRaid8	lod	framexml
+BattlefieldMinimapRaid9	lod	framexml
+BattlefieldMinimapRaidUnitTemplate	lod	framexml
+BattlefieldMinimapResizeBottomRight	lod	framexml
+BattlefieldMinimapTab	lod	framexml
+BattlefieldMinimapTab_OnClick	lod	framexml
+BattlefieldMinimapUnitTemplate	lod	framexml
+BattlefieldMinimapUnit_OnEnter	lod	framexml
+BattlefieldMinimap_CreatePOI	lod	framexml
+BattlefieldMinimap_LoadUI	function	framexml
+BattlefieldMinimap_OnEvent	lod	framexml
+BattlefieldMinimap_OnLoad	lod	framexml
+BattlefieldMinimap_OnUpdate	lod	framexml
+BattlefieldMinimap_SaveOpacity	lod	framexml
+BattlefieldMinimap_SetOpacity	lod	framexml
+BattlefieldMinimap_ShowOpacity	lod	framexml
+BattlefieldMinimap_Toggle	lod	framexml
+BattlefieldMinimap_ToggleLock	lod	framexml
+BattlefieldMinimap_TogglePlayers	lod	framexml
+BattlefieldMinimap_Update	lod	framexml
+BattlefieldZone1	table	framexml
+BattlefieldZone10	table	framexml
+BattlefieldZone10Highlight	table	framexml
+BattlefieldZone10Status	table	framexml
+BattlefieldZone10Text	table	framexml
+BattlefieldZone11	table	framexml
+BattlefieldZone11Highlight	table	framexml
+BattlefieldZone11Status	table	framexml
+BattlefieldZone11Text	table	framexml
+BattlefieldZone12	table	framexml
+BattlefieldZone12Highlight	table	framexml
+BattlefieldZone12Status	table	framexml
+BattlefieldZone12Text	table	framexml
+BattlefieldZone1Highlight	table	framexml
+BattlefieldZone1Status	table	framexml
+BattlefieldZone1Text	table	framexml
+BattlefieldZone2	table	framexml
+BattlefieldZone2Highlight	table	framexml
+BattlefieldZone2Status	table	framexml
+BattlefieldZone2Text	table	framexml
+BattlefieldZone3	table	framexml
+BattlefieldZone3Highlight	table	framexml
+BattlefieldZone3Status	table	framexml
+BattlefieldZone3Text	table	framexml
+BattlefieldZone4	table	framexml
+BattlefieldZone4Highlight	table	framexml
+BattlefieldZone4Status	table	framexml
+BattlefieldZone4Text	table	framexml
+BattlefieldZone5	table	framexml
+BattlefieldZone5Highlight	table	framexml
+BattlefieldZone5Status	table	framexml
+BattlefieldZone5Text	table	framexml
+BattlefieldZone6	table	framexml
+BattlefieldZone6Highlight	table	framexml
+BattlefieldZone6Status	table	framexml
+BattlefieldZone6Text	table	framexml
+BattlefieldZone7	table	framexml
+BattlefieldZone7Highlight	table	framexml
+BattlefieldZone7Status	table	framexml
+BattlefieldZone7Text	table	framexml
+BattlefieldZone8	table	framexml
+BattlefieldZone8Highlight	table	framexml
+BattlefieldZone8Status	table	framexml
+BattlefieldZone8Text	table	framexml
+BattlefieldZone9	table	framexml
+BattlefieldZone9Highlight	table	framexml
+BattlefieldZone9Status	table	framexml
+BattlefieldZone9Text	table	framexml
+BattlegroundShine	table	framexml
+BattlegroundShineFadeIn	function	framexml
+BattlegroundShineFadeOut	function	framexml
+BeginTrade	function	engine
+Bhgt	lod	framexml
+BidBidButton	lod	framexml
+BidBidPrice	lod	framexml
+BidBidSort	lod	framexml
+BidBidText	lod	framexml
+BidButton1	lod	framexml
+BidButton2	lod	framexml
+BidButton3	lod	framexml
+BidButton4	lod	framexml
+BidButton5	lod	framexml
+BidButton6	lod	framexml
+BidButton7	lod	framexml
+BidButton8	lod	framexml
+BidButton9	lod	framexml
+BidButtonTemplate	lod	framexml
+BidButton_OnClick	lod	framexml
+BidBuyoutButton	lod	framexml
+BidBuyoutSort	lod	framexml
+BidCloseButton	lod	framexml
+BidDurationSort	lod	framexml
+BidLevelSort	lod	framexml
+BidNextPageButton	lod	framexml
+BidPrevPageButton	lod	framexml
+BidQualitySort	lod	framexml
+BidScrollFrame	lod	framexml
+BidSearchCountText	lod	framexml
+BidStatusSort	lod	framexml
+BidTitle	lod	framexml
+BindEnchant	function	engine
+BlackoutWorld	table	framexml
+BonusActionBarFrame	table	framexml
+BonusActionBarTexture0	table	framexml
+BonusActionBarTexture1	table	framexml
+BonusActionBar_OnEvent	function	framexml
+BonusActionBar_OnLoad	function	framexml
+BonusActionBar_OnUpdate	function	framexml
+BonusActionBar_SetButtonTransitionState	function	framexml
+BonusActionButton1	table	framexml
+BonusActionButton10	table	framexml
+BonusActionButton10Border	table	framexml
+BonusActionButton10Cooldown	table	framexml
+BonusActionButton10Count	table	framexml
+BonusActionButton10Flash	table	framexml
+BonusActionButton10HotKey	table	framexml
+BonusActionButton10Icon	table	framexml
+BonusActionButton10Name	table	framexml
+BonusActionButton10NormalTexture	table	framexml
+BonusActionButton11	table	framexml
+BonusActionButton11Border	table	framexml
+BonusActionButton11Cooldown	table	framexml
+BonusActionButton11Count	table	framexml
+BonusActionButton11Flash	table	framexml
+BonusActionButton11HotKey	table	framexml
+BonusActionButton11Icon	table	framexml
+BonusActionButton11Name	table	framexml
+BonusActionButton11NormalTexture	table	framexml
+BonusActionButton12	table	framexml
+BonusActionButton12Border	table	framexml
+BonusActionButton12Cooldown	table	framexml
+BonusActionButton12Count	table	framexml
+BonusActionButton12Flash	table	framexml
+BonusActionButton12HotKey	table	framexml
+BonusActionButton12Icon	table	framexml
+BonusActionButton12Name	table	framexml
+BonusActionButton12NormalTexture	table	framexml
+BonusActionButton1Border	table	framexml
+BonusActionButton1Cooldown	table	framexml
+BonusActionButton1Count	table	framexml
+BonusActionButton1Flash	table	framexml
+BonusActionButton1HotKey	table	framexml
+BonusActionButton1Icon	table	framexml
+BonusActionButton1Name	table	framexml
+BonusActionButton1NormalTexture	table	framexml
+BonusActionButton2	table	framexml
+BonusActionButton2Border	table	framexml
+BonusActionButton2Cooldown	table	framexml
+BonusActionButton2Count	table	framexml
+BonusActionButton2Flash	table	framexml
+BonusActionButton2HotKey	table	framexml
+BonusActionButton2Icon	table	framexml
+BonusActionButton2Name	table	framexml
+BonusActionButton2NormalTexture	table	framexml
+BonusActionButton3	table	framexml
+BonusActionButton3Border	table	framexml
+BonusActionButton3Cooldown	table	framexml
+BonusActionButton3Count	table	framexml
+BonusActionButton3Flash	table	framexml
+BonusActionButton3HotKey	table	framexml
+BonusActionButton3Icon	table	framexml
+BonusActionButton3Name	table	framexml
+BonusActionButton3NormalTexture	table	framexml
+BonusActionButton4	table	framexml
+BonusActionButton4Border	table	framexml
+BonusActionButton4Cooldown	table	framexml
+BonusActionButton4Count	table	framexml
+BonusActionButton4Flash	table	framexml
+BonusActionButton4HotKey	table	framexml
+BonusActionButton4Icon	table	framexml
+BonusActionButton4Name	table	framexml
+BonusActionButton4NormalTexture	table	framexml
+BonusActionButton5	table	framexml
+BonusActionButton5Border	table	framexml
+BonusActionButton5Cooldown	table	framexml
+BonusActionButton5Count	table	framexml
+BonusActionButton5Flash	table	framexml
+BonusActionButton5HotKey	table	framexml
+BonusActionButton5Icon	table	framexml
+BonusActionButton5Name	table	framexml
+BonusActionButton5NormalTexture	table	framexml
+BonusActionButton6	table	framexml
+BonusActionButton6Border	table	framexml
+BonusActionButton6Cooldown	table	framexml
+BonusActionButton6Count	table	framexml
+BonusActionButton6Flash	table	framexml
+BonusActionButton6HotKey	table	framexml
+BonusActionButton6Icon	table	framexml
+BonusActionButton6Name	table	framexml
+BonusActionButton6NormalTexture	table	framexml
+BonusActionButton7	table	framexml
+BonusActionButton7Border	table	framexml
+BonusActionButton7Cooldown	table	framexml
+BonusActionButton7Count	table	framexml
+BonusActionButton7Flash	table	framexml
+BonusActionButton7HotKey	table	framexml
+BonusActionButton7Icon	table	framexml
+BonusActionButton7Name	table	framexml
+BonusActionButton7NormalTexture	table	framexml
+BonusActionButton8	table	framexml
+BonusActionButton8Border	table	framexml
+BonusActionButton8Cooldown	table	framexml
+BonusActionButton8Count	table	framexml
+BonusActionButton8Flash	table	framexml
+BonusActionButton8HotKey	table	framexml
+BonusActionButton8Icon	table	framexml
+BonusActionButton8Name	table	framexml
+BonusActionButton8NormalTexture	table	framexml
+BonusActionButton9	table	framexml
+BonusActionButton9Border	table	framexml
+BonusActionButton9Cooldown	table	framexml
+BonusActionButton9Count	table	framexml
+BonusActionButton9Flash	table	framexml
+BonusActionButton9HotKey	table	framexml
+BonusActionButton9Icon	table	framexml
+BonusActionButton9Name	table	framexml
+BonusActionButton9NormalTexture	table	framexml
+BonusActionButtonDown	function	framexml
+BonusActionButtonTemplate	lod	framexml
+BonusActionButtonUp	function	framexml
+BonusActionButton_OnEvent	function	framexml
+BrowseBidButton	lod	framexml
+BrowseBidPrice	lod	framexml
+BrowseBidText	lod	framexml
+BrowseButton1	lod	framexml
+BrowseButton2	lod	framexml
+BrowseButton3	lod	framexml
+BrowseButton4	lod	framexml
+BrowseButton5	lod	framexml
+BrowseButton6	lod	framexml
+BrowseButton7	lod	framexml
+BrowseButton8	lod	framexml
+BrowseButtonTemplate	lod	framexml
+BrowseButton_OnClick	lod	framexml
+BrowseBuyoutButton	lod	framexml
+BrowseCloseButton	lod	framexml
+BrowseCurrentBidSort	lod	framexml
+BrowseDropDown	lod	framexml
+BrowseDropDownName	lod	framexml
+BrowseDropDown_Initialize	lod	framexml
+BrowseDropDown_OnClick	lod	framexml
+BrowseDropDown_OnLoad	lod	framexml
+BrowseDurationSort	lod	framexml
+BrowseFilterScrollFrame	lod	framexml
+BrowseHighBidderSort	lod	framexml
+BrowseIsUsableText	lod	framexml
+BrowseLevelHyphen	lod	framexml
+BrowseLevelSort	lod	framexml
+BrowseLevelText	lod	framexml
+BrowseMaxLevel	lod	framexml
+BrowseMinLevel	lod	framexml
+BrowseName	lod	framexml
+BrowseNameText	lod	framexml
+BrowseNextPageButton	lod	framexml
+BrowseNoResultsText	lod	framexml
+BrowsePrevPageButton	lod	framexml
+BrowseQualitySort	lod	framexml
+BrowseScrollFrame	lod	framexml
+BrowseSearchButton	lod	framexml
+BrowseSearchButton_OnUpdate	lod	framexml
+BrowseSearchCountText	lod	framexml
+BrowseSearchDotsText	lod	framexml
+BrowseShowOnCharacterText	lod	framexml
+BrowseTabText	lod	framexml
+BrowseTitle	lod	framexml
+BuffButton0	table	framexml
+BuffButton0Count	table	framexml
+BuffButton0Duration	table	framexml
+BuffButton0Icon	table	framexml
+BuffButton1	table	framexml
+BuffButton10	table	framexml
+BuffButton10Count	table	framexml
+BuffButton10Duration	table	framexml
+BuffButton10Icon	table	framexml
+BuffButton11	table	framexml
+BuffButton11Count	table	framexml
+BuffButton11Duration	table	framexml
+BuffButton11Icon	table	framexml
+BuffButton12	table	framexml
+BuffButton12Count	table	framexml
+BuffButton12Duration	table	framexml
+BuffButton12Icon	table	framexml
+BuffButton13	table	framexml
+BuffButton13Count	table	framexml
+BuffButton13Duration	table	framexml
+BuffButton13Icon	table	framexml
+BuffButton14	table	framexml
+BuffButton14Count	table	framexml
+BuffButton14Duration	table	framexml
+BuffButton14Icon	table	framexml
+BuffButton15	table	framexml
+BuffButton15Count	table	framexml
+BuffButton15Duration	table	framexml
+BuffButton15Icon	table	framexml
+BuffButton16	table	framexml
+BuffButton16Border	table	framexml
+BuffButton16Count	table	framexml
+BuffButton16Duration	table	framexml
+BuffButton16Icon	table	framexml
+BuffButton17	table	framexml
+BuffButton17Border	table	framexml
+BuffButton17Count	table	framexml
+BuffButton17Duration	table	framexml
+BuffButton17Icon	table	framexml
+BuffButton18	table	framexml
+BuffButton18Border	table	framexml
+BuffButton18Count	table	framexml
+BuffButton18Duration	table	framexml
+BuffButton18Icon	table	framexml
+BuffButton19	table	framexml
+BuffButton19Border	table	framexml
+BuffButton19Count	table	framexml
+BuffButton19Duration	table	framexml
+BuffButton19Icon	table	framexml
+BuffButton1Count	table	framexml
+BuffButton1Duration	table	framexml
+BuffButton1Icon	table	framexml
+BuffButton2	table	framexml
+BuffButton20	table	framexml
+BuffButton20Border	table	framexml
+BuffButton20Count	table	framexml
+BuffButton20Duration	table	framexml
+BuffButton20Icon	table	framexml
+BuffButton21	table	framexml
+BuffButton21Border	table	framexml
+BuffButton21Count	table	framexml
+BuffButton21Duration	table	framexml
+BuffButton21Icon	table	framexml
+BuffButton22	table	framexml
+BuffButton22Border	table	framexml
+BuffButton22Count	table	framexml
+BuffButton22Duration	table	framexml
+BuffButton22Icon	table	framexml
+BuffButton23	table	framexml
+BuffButton23Border	table	framexml
+BuffButton23Count	table	framexml
+BuffButton23Duration	table	framexml
+BuffButton23Icon	table	framexml
+BuffButton2Count	table	framexml
+BuffButton2Duration	table	framexml
+BuffButton2Icon	table	framexml
+BuffButton3	table	framexml
+BuffButton3Count	table	framexml
+BuffButton3Duration	table	framexml
+BuffButton3Icon	table	framexml
+BuffButton4	table	framexml
+BuffButton4Count	table	framexml
+BuffButton4Duration	table	framexml
+BuffButton4Icon	table	framexml
+BuffButton5	table	framexml
+BuffButton5Count	table	framexml
+BuffButton5Duration	table	framexml
+BuffButton5Icon	table	framexml
+BuffButton6	table	framexml
+BuffButton6Count	table	framexml
+BuffButton6Duration	table	framexml
+BuffButton6Icon	table	framexml
+BuffButton7	table	framexml
+BuffButton7Count	table	framexml
+BuffButton7Duration	table	framexml
+BuffButton7Icon	table	framexml
+BuffButton8	table	framexml
+BuffButton8Count	table	framexml
+BuffButton8Duration	table	framexml
+BuffButton8Icon	table	framexml
+BuffButton9	table	framexml
+BuffButton9Count	table	framexml
+BuffButton9Duration	table	framexml
+BuffButton9Icon	table	framexml
+BuffButtonDurationTemplate	lod	framexml
+BuffButtonHarmful	lod	framexml
+BuffButtonHelpful	lod	framexml
+BuffButtonTempEnchant	lod	framexml
+BuffButtonTemplate	lod	framexml
+BuffButton_OnClick	function	framexml
+BuffButton_OnEvent	function	framexml
+BuffButton_OnLoad	function	framexml
+BuffButton_OnUpdate	function	framexml
+BuffButton_Update	function	framexml
+BuffButtons_UpdatePositions	function	framexml
+BuffFrame	table	framexml
+BuffFrameFlashState	number	framexml
+BuffFrameFlashTime	number	framexml
+BuffFrameUpdateTime	number	framexml
+BuffFrame_EnchantButton_OnEnter	function	framexml
+BuffFrame_EnchantButton_OnUpdate	function	framexml
+BuffFrame_Enchant_OnUpdate	function	framexml
+BuffFrame_OnLoad	function	framexml
+BuffFrame_OnUpdate	function	framexml
+BuffFrame_UpdateDuration	function	framexml
+BuildColoredListString	function	framexml
+BuildListString	function	framexml
+BuildMultilineTooltip	function	framexml
+ButtonInventorySlot	function	framexml
+ButtonPulse_OnUpdate	function	framexml
+ButtonPulse_StopPulse	function	framexml
+BuyGuildCharter	function	engine
+BuyMerchantItem	function	engine
+BuyRandomPicks	function	engine
+BuySkillTier	function	engine
+BuyStableSlot	function	engine
+BuyTrainerService	function	engine
+BuybackFrameBotLeft	table	framexml
+BuybackFrameBotRight	table	framexml
+BuybackFrameTopLeft	table	framexml
+BuybackFrameTopRight	table	framexml
+BuybackItem	function	engine
+BuyoutPrice	lod	framexml
+Bwid	lod	framexml
+CALIBRATION_TEXT	string	framexml
+CAMERA_ALWAYS	string	framexml
+CAMERA_FOLLOWING_STYLE	string	framexml
+CAMERA_LABEL	string	framexml
+CAMERA_LOCKED	string	framexml
+CAMERA_MODE	string	framexml
+CAMERA_NEVER	string	framexml
+CAMERA_SMART	string	framexml
+CAMP_NOW	string	framexml
+CAMP_TIMER	string	framexml
+CANCEL	string	framexml
+CANCEL_AUCTION	string	framexml
+CANCEL_AUCTION_CONFIRMATION	string	framexml
+CANCEL_AUCTION_CONFIRMATION_MONEY	string	framexml
+CANT_AFFORD_ITEM	string	framexml
+CANT_USE_ITEM	string	framexml
+CASH_ON_DELIVERY	string	framexml
+CASTING_BAR_ALPHA_STEP	number	framexml
+CASTING_BAR_FLASH_STEP	number	framexml
+CASTING_BAR_HOLD_TIME	number	framexml
+CAST_WHILE_MOVING	string	framexml
+CATEGORY_TO_NOT_DISPLAY	number	framexml
+CHANCE_TO_BLOCK	string	framexml
+CHANCE_TO_CRIT	string	framexml
+CHANCE_TO_DODGE	string	framexml
+CHANCE_TO_PARRY	string	framexml
+CHANGE_INSTANCE	string	framexml
+CHANGE_MACRO_NAME_ICON	string	framexml
+CHANNELING	string	framexml
+CHANNELS	string	framexml
+CHARACTER	string	framexml
+CHARACTERFRAME_SUBFRAMES	table	framexml
+CHARACTER_BINDINGS	lod	framexml
+CHARACTER_BUTTON	string	framexml
+CHARACTER_INFO	string	framexml
+CHARACTER_KEY_BINDINGS	string	framexml
+CHARACTER_POINTS1_COLON	string	framexml
+CHARACTER_POINTS2_COLON	string	framexml
+CHARACTER_POINTS_CHANGED	string	framexml
+CHARACTER_SPECIFIC_KEYBINDINGS	string	framexml
+CHARACTER_SPECIFIC_KEYBINDING_TOOLTIP	string	framexml
+CHARACTER_SPECIFIC_MACROS	string	framexml
+CHATLOGDISABLED	string	framexml
+CHATLOGENABLED	string	framexml
+CHAT_AFK_GET	string	framexml
+CHAT_ANNOUNCEMENTS_OFF_NOTICE	string	framexml
+CHAT_ANNOUNCEMENTS_ON_NOTICE	string	framexml
+CHAT_BANNED_NOTICE	string	framexml
+CHAT_BATTLEGROUND_GET	string	framexml
+CHAT_BATTLEGROUND_LEADER_GET	string	framexml
+CHAT_BATTLEGROUND_SEND	string	framexml
+CHAT_BUBBLES_TEXT	string	framexml
+CHAT_BUTTON_FLASH_TIME	number	framexml
+CHAT_CHANNEL_GET	string	framexml
+CHAT_CHANNEL_JOIN_GET	string	framexml
+CHAT_CHANNEL_LEAVE_GET	string	framexml
+CHAT_CHANNEL_LIST_GET	string	framexml
+CHAT_CHANNEL_OWNER_NOTICE	string	framexml
+CHAT_CHANNEL_SEND	string	framexml
+CHAT_COMBAT_CREATURE_VS_CREATURE_HITS_GET	string	framexml
+CHAT_COMBAT_CREATURE_VS_CREATURE_MISSES_GET	string	framexml
+CHAT_COMBAT_CREATURE_VS_PARTY_HITS_GET	string	framexml
+CHAT_COMBAT_CREATURE_VS_PARTY_MISSES_GET	string	framexml
+CHAT_COMBAT_CREATURE_VS_SELF_HITS_GET	string	framexml
+CHAT_COMBAT_CREATURE_VS_SELF_MISSES_GET	string	framexml
+CHAT_COMBAT_ERROR_GET	string	framexml
+CHAT_COMBAT_FRIENDLYPLAYER_HITS_GET	string	framexml
+CHAT_COMBAT_FRIENDLYPLAYER_MISSES_GET	string	framexml
+CHAT_COMBAT_FRIENDLY_DEATH_GET	string	framexml
+CHAT_COMBAT_HOSTILEPLAYER_HITS_GET	string	framexml
+CHAT_COMBAT_HOSTILEPLAYER_MISSES_GET	string	framexml
+CHAT_COMBAT_HOSTILE_DEATH_GET	string	framexml
+CHAT_COMBAT_LOG_ERROR_GET	string	framexml
+CHAT_COMBAT_LOG_MISC_INFO_GET	string	framexml
+CHAT_COMBAT_MISC_INFO_GET	string	framexml
+CHAT_COMBAT_PARTY_HITS_GET	string	framexml
+CHAT_COMBAT_PARTY_MISSES_GET	string	framexml
+CHAT_COMBAT_PET_HITS_GET	string	framexml
+CHAT_COMBAT_PET_MISSES_GET	string	framexml
+CHAT_COMBAT_SELF_HITS_GET	string	framexml
+CHAT_COMBAT_SELF_MISSES_GET	string	framexml
+CHAT_DND_GET	string	framexml
+CHAT_EMOTE_GET	string	framexml
+CHAT_EMOTE_SEND	string	framexml
+CHAT_EMOTE_UNKNOWN	string	framexml
+CHAT_FILTERED	string	framexml
+CHAT_FLAG_AFK	string	framexml
+CHAT_FLAG_DND	string	framexml
+CHAT_FLAG_GM	string	framexml
+CHAT_FONT_HEIGHTS	table	framexml
+CHAT_FRAME_FADE_TIME	number	framexml
+CHAT_FRAME_TEXTURES	table	framexml
+CHAT_GUILD_DEMOTE_SEND	string	framexml
+CHAT_GUILD_GET	string	framexml
+CHAT_GUILD_INVITE_SEND	string	framexml
+CHAT_GUILD_LEADER_SEND	string	framexml
+CHAT_GUILD_MOTD_SEND	string	framexml
+CHAT_GUILD_PROMOTE_SEND	string	framexml
+CHAT_GUILD_SEND	string	framexml
+CHAT_GUILD_UNINVITE_SEND	string	framexml
+CHAT_HELP_TEXT_LINE1	string	framexml
+CHAT_HELP_TEXT_LINE10	string	framexml
+CHAT_HELP_TEXT_LINE11	string	framexml
+CHAT_HELP_TEXT_LINE12	string	framexml
+CHAT_HELP_TEXT_LINE13	string	framexml
+CHAT_HELP_TEXT_LINE14	string	framexml
+CHAT_HELP_TEXT_LINE15	string	framexml
+CHAT_HELP_TEXT_LINE16	string	framexml
+CHAT_HELP_TEXT_LINE2	string	framexml
+CHAT_HELP_TEXT_LINE3	string	framexml
+CHAT_HELP_TEXT_LINE4	string	framexml
+CHAT_HELP_TEXT_LINE5	string	framexml
+CHAT_HELP_TEXT_LINE6	string	framexml
+CHAT_HELP_TEXT_LINE7	string	framexml
+CHAT_HELP_TEXT_LINE8	string	framexml
+CHAT_HELP_TEXT_LINE9	string	framexml
+CHAT_IGNORED	string	framexml
+CHAT_INVALID_NAME_NOTICE	string	framexml
+CHAT_INVITE_NOTICE	string	framexml
+CHAT_INVITE_SEND	string	framexml
+CHAT_INVITE_WRONG_FACTION_NOTICE	string	framexml
+CHAT_JOIN_HELP	string	framexml
+CHAT_LABEL	string	framexml
+CHAT_LOCKED	string	framexml
+CHAT_LOCKED_TEXT	string	framexml
+CHAT_MODERATION_OFF_NOTICE	string	framexml
+CHAT_MODERATION_ON_NOTICE	string	framexml
+CHAT_MONSTER_EMOTE_GET	string	framexml
+CHAT_MONSTER_SAY_GET	string	framexml
+CHAT_MONSTER_WHISPER_GET	string	framexml
+CHAT_MONSTER_YELL_GET	string	framexml
+CHAT_MSG_AFK	string	framexml
+CHAT_MSG_BATTLEGROUND	string	framexml
+CHAT_MSG_BATTLEGROUND_LEADER	string	framexml
+CHAT_MSG_BG_SYSTEM_ALLIANCE	string	framexml
+CHAT_MSG_BG_SYSTEM_HORDE	string	framexml
+CHAT_MSG_BG_SYSTEM_NEUTRAL	string	framexml
+CHAT_MSG_CHANNEL_LIST	string	framexml
+CHAT_MSG_COMBAT_CREATURE_VS_CREATURE_HITS	string	framexml
+CHAT_MSG_COMBAT_CREATURE_VS_CREATURE_MISSES	string	framexml
+CHAT_MSG_COMBAT_CREATURE_VS_PARTY_HITS	string	framexml
+CHAT_MSG_COMBAT_CREATURE_VS_PARTY_MISSES	string	framexml
+CHAT_MSG_COMBAT_CREATURE_VS_SELF_HITS	string	framexml
+CHAT_MSG_COMBAT_CREATURE_VS_SELF_MISSES	string	framexml
+CHAT_MSG_COMBAT_FACTION_CHANGE	string	framexml
+CHAT_MSG_COMBAT_FRIENDLYPLAYER_HITS	string	framexml
+CHAT_MSG_COMBAT_FRIENDLYPLAYER_MISSES	string	framexml
+CHAT_MSG_COMBAT_FRIENDLY_DEATH	string	framexml
+CHAT_MSG_COMBAT_HONOR_GAIN	string	framexml
+CHAT_MSG_COMBAT_HOSTILEPLAYER_HITS	string	framexml
+CHAT_MSG_COMBAT_HOSTILEPLAYER_MISSES	string	framexml
+CHAT_MSG_COMBAT_HOSTILE_DEATH	string	framexml
+CHAT_MSG_COMBAT_LOG_ERROR	string	framexml
+CHAT_MSG_COMBAT_LOG_MISC_INFO	string	framexml
+CHAT_MSG_COMBAT_MISC_INFO	string	framexml
+CHAT_MSG_COMBAT_PARTY_HITS	string	framexml
+CHAT_MSG_COMBAT_PARTY_MISSES	string	framexml
+CHAT_MSG_COMBAT_PET_HITS	string	framexml
+CHAT_MSG_COMBAT_PET_MISSES	string	framexml
+CHAT_MSG_COMBAT_SELF_HITS	string	framexml
+CHAT_MSG_COMBAT_SELF_MISSES	string	framexml
+CHAT_MSG_COMBAT_XP_GAIN	string	framexml
+CHAT_MSG_DND	string	framexml
+CHAT_MSG_EMOTE	string	framexml
+CHAT_MSG_FILTERED	string	framexml
+CHAT_MSG_GUILD	string	framexml
+CHAT_MSG_IGNORED	string	framexml
+CHAT_MSG_LOOT	string	framexml
+CHAT_MSG_MONEY	string	framexml
+CHAT_MSG_MONSTER_EMOTE	string	framexml
+CHAT_MSG_MONSTER_SAY	string	framexml
+CHAT_MSG_MONSTER_WHISPER	string	framexml
+CHAT_MSG_MONSTER_YELL	string	framexml
+CHAT_MSG_OFFICER	string	framexml
+CHAT_MSG_PARTY	string	framexml
+CHAT_MSG_RAID	string	framexml
+CHAT_MSG_RAID_BOSS_EMOTE	string	framexml
+CHAT_MSG_RAID_LEADER	string	framexml
+CHAT_MSG_RAID_WARNING	string	framexml
+CHAT_MSG_SAY	string	framexml
+CHAT_MSG_SKILL	string	framexml
+CHAT_MSG_SPELL_AURA_GONE_OTHER	string	framexml
+CHAT_MSG_SPELL_AURA_GONE_PARTY	string	framexml
+CHAT_MSG_SPELL_AURA_GONE_SELF	string	framexml
+CHAT_MSG_SPELL_BREAK_AURA	string	framexml
+CHAT_MSG_SPELL_CREATURE_VS_CREATURE_BUFF	string	framexml
+CHAT_MSG_SPELL_CREATURE_VS_CREATURE_DAMAGE	string	framexml
+CHAT_MSG_SPELL_CREATURE_VS_PARTY_BUFF	string	framexml
+CHAT_MSG_SPELL_CREATURE_VS_PARTY_DAMAGE	string	framexml
+CHAT_MSG_SPELL_CREATURE_VS_SELF_BUFF	string	framexml
+CHAT_MSG_SPELL_CREATURE_VS_SELF_DAMAGE	string	framexml
+CHAT_MSG_SPELL_DAMAGESHIELDS_ON_OTHERS	string	framexml
+CHAT_MSG_SPELL_DAMAGESHIELDS_ON_SELF	string	framexml
+CHAT_MSG_SPELL_FAILED_LOCALPLAYER	string	framexml
+CHAT_MSG_SPELL_FRIENDLYPLAYER_BUFF	string	framexml
+CHAT_MSG_SPELL_FRIENDLYPLAYER_DAMAGE	string	framexml
+CHAT_MSG_SPELL_HOSTILEPLAYER_BUFF	string	framexml
+CHAT_MSG_SPELL_HOSTILEPLAYER_DAMAGE	string	framexml
+CHAT_MSG_SPELL_ITEM_ENCHANTMENTS	string	framexml
+CHAT_MSG_SPELL_PARTY_BUFF	string	framexml
+CHAT_MSG_SPELL_PARTY_DAMAGE	string	framexml
+CHAT_MSG_SPELL_PERIODIC_CREATURE_BUFFS	string	framexml
+CHAT_MSG_SPELL_PERIODIC_CREATURE_DAMAGE	string	framexml
+CHAT_MSG_SPELL_PERIODIC_FRIENDLYPLAYER_BUFFS	string	framexml
+CHAT_MSG_SPELL_PERIODIC_FRIENDLYPLAYER_DAMAGE	string	framexml
+CHAT_MSG_SPELL_PERIODIC_HOSTILEPLAYER_BUFFS	string	framexml
+CHAT_MSG_SPELL_PERIODIC_HOSTILEPLAYER_DAMAGE	string	framexml
+CHAT_MSG_SPELL_PERIODIC_PARTY_BUFFS	string	framexml
+CHAT_MSG_SPELL_PERIODIC_PARTY_DAMAGE	string	framexml
+CHAT_MSG_SPELL_PERIODIC_SELF_BUFFS	string	framexml
+CHAT_MSG_SPELL_PERIODIC_SELF_DAMAGE	string	framexml
+CHAT_MSG_SPELL_PET_BUFF	string	framexml
+CHAT_MSG_SPELL_PET_DAMAGE	string	framexml
+CHAT_MSG_SPELL_SELF_BUFF	string	framexml
+CHAT_MSG_SPELL_SELF_DAMAGE	string	framexml
+CHAT_MSG_SPELL_TRADESKILLS	string	framexml
+CHAT_MSG_SYSTEM	string	framexml
+CHAT_MSG_TEXT_EMOTE	string	framexml
+CHAT_MSG_WHISPER	string	framexml
+CHAT_MSG_WHISPER_INFORM	string	framexml
+CHAT_MSG_YELL	string	framexml
+CHAT_MUTED_NOTICE	string	framexml
+CHAT_NAME_TEMPLATE	string	framexml
+CHAT_NOT_MEMBER_NOTICE	string	framexml
+CHAT_NOT_MODERATED_NOTICE	string	framexml
+CHAT_NOT_MODERATOR_NOTICE	string	framexml
+CHAT_NOT_OWNER_NOTICE	string	framexml
+CHAT_OFFICER_GET	string	framexml
+CHAT_OFFICER_SEND	string	framexml
+CHAT_OPTIONS_LABEL	string	framexml
+CHAT_OWNER_CHANGED_NOTICE	string	framexml
+CHAT_PARTY_GET	string	framexml
+CHAT_PARTY_SEND	string	framexml
+CHAT_PASSWORD_CHANGED_NOTICE	string	framexml
+CHAT_PLAYER_ALREADY_MEMBER_NOTICE	string	framexml
+CHAT_PLAYER_BANNED_NOTICE	string	framexml
+CHAT_PLAYER_INVITED_NOTICE	string	framexml
+CHAT_PLAYER_INVITE_BANNED_NOTICE	string	framexml
+CHAT_PLAYER_KICKED_NOTICE	string	framexml
+CHAT_PLAYER_NOT_BANNED_NOTICE	string	framexml
+CHAT_PLAYER_NOT_FOUND_NOTICE	string	framexml
+CHAT_PLAYER_UNBANNED_NOTICE	string	framexml
+CHAT_PROMOTE_SEND	string	framexml
+CHAT_RAID_BOSS_EMOTE_GET	string	framexml
+CHAT_RAID_GET	string	framexml
+CHAT_RAID_LEADER_GET	string	framexml
+CHAT_RAID_SEND	string	framexml
+CHAT_RAID_WARNING_GET	string	framexml
+CHAT_RAID_WARNING_SEND	string	framexml
+CHAT_SAY_GET	string	framexml
+CHAT_SAY_SEND	string	framexml
+CHAT_SET_MODERATOR_NOTICE	string	framexml
+CHAT_SET_VOICE_NOTICE	string	framexml
+CHAT_SPELL_AURA_GONE_OTHER_GET	string	framexml
+CHAT_SPELL_AURA_GONE_PARTY_GET	string	framexml
+CHAT_SPELL_AURA_GONE_SELF_GET	string	framexml
+CHAT_SPELL_BREAK_AURA_GET	string	framexml
+CHAT_SPELL_CREATURE_VS_CREATURE_BUFF_GET	string	framexml
+CHAT_SPELL_CREATURE_VS_CREATURE_DAMAGE_GET	string	framexml
+CHAT_SPELL_CREATURE_VS_PARTY_BUFF_GET	string	framexml
+CHAT_SPELL_CREATURE_VS_PARTY_DAMAGE_GET	string	framexml
+CHAT_SPELL_CREATURE_VS_SELF_BUFF_GET	string	framexml
+CHAT_SPELL_CREATURE_VS_SELF_DAMAGE_GET	string	framexml
+CHAT_SPELL_DAMAGESHIELDS_ON_OTHERS_GET	string	framexml
+CHAT_SPELL_DAMAGESHIELDS_ON_SELF_GET	string	framexml
+CHAT_SPELL_FRIENDLYPLAYER_BUFF_GET	string	framexml
+CHAT_SPELL_FRIENDLYPLAYER_DAMAGE_GET	string	framexml
+CHAT_SPELL_HOSTILEPLAYER_BUFF_GET	string	framexml
+CHAT_SPELL_HOSTILEPLAYER_DAMAGE_GET	string	framexml
+CHAT_SPELL_ITEM_ENCHANTMENTS_GET	string	framexml
+CHAT_SPELL_PARTY_BUFF_GET	string	framexml
+CHAT_SPELL_PARTY_DAMAGE_GET	string	framexml
+CHAT_SPELL_PERIODIC_CREATURE_BUFFS_GET	string	framexml
+CHAT_SPELL_PERIODIC_CREATURE_DAMAGE_GET	string	framexml
+CHAT_SPELL_PERIODIC_FRIENDLYPLAYER_BUFFS_GET	string	framexml
+CHAT_SPELL_PERIODIC_FRIENDLYPLAYER_DAMAGE_GET	string	framexml
+CHAT_SPELL_PERIODIC_HOSTILEPLAYER_BUFFS_GET	string	framexml
+CHAT_SPELL_PERIODIC_HOSTILEPLAYER_DAMAGE_GET	string	framexml
+CHAT_SPELL_PERIODIC_PARTY_BUFFS_GET	string	framexml
+CHAT_SPELL_PERIODIC_PARTY_DAMAGE_GET	string	framexml
+CHAT_SPELL_PERIODIC_SELF_BUFFS_GET	string	framexml
+CHAT_SPELL_PERIODIC_SELF_DAMAGE_GET	string	framexml
+CHAT_SPELL_PET_BUFF_GET	string	framexml
+CHAT_SPELL_PET_DAMAGE_GET	string	framexml
+CHAT_SPELL_SELF_BUFF_GET	string	framexml
+CHAT_SPELL_SELF_DAMAGE_GET	string	framexml
+CHAT_SPELL_TRADESKILLS_GET	string	framexml
+CHAT_SUSPENDED_NOTICE	string	framexml
+CHAT_TAB_SHOW_DELAY	number	framexml
+CHAT_TELL_ALERT_TIME	number	framexml
+CHAT_THROTTLED_NOTICE	string	framexml
+CHAT_UNINVITE_SEND	string	framexml
+CHAT_UNSET_MODERATOR_NOTICE	string	framexml
+CHAT_UNSET_VOICE_NOTICE	string	framexml
+CHAT_WHISPER_GET	string	framexml
+CHAT_WHISPER_INFORM_GET	string	framexml
+CHAT_WHISPER_SEND	string	framexml
+CHAT_WRONG_FACTION_NOTICE	string	framexml
+CHAT_WRONG_PASSWORD_NOTICE	string	framexml
+CHAT_YELL_GET	string	framexml
+CHAT_YELL_SEND	string	framexml
+CHAT_YOU_CHANGED_NOTICE	string	framexml
+CHAT_YOU_JOINED_NOTICE	string	framexml
+CHAT_YOU_LEFT_NOTICE	string	framexml
+CHESTSLOT	string	framexml
+CHOOSE_BOX	string	framexml
+CHOOSE_STATIONERY	string	framexml
+CHOSEN_FOR_GMSURVEY	string	framexml
+CINEMATIC_SUBTITLES	string	framexml
+CLASS	string	framexml
+CLASS_FILTERS	lod	framexml
+CLASS_SKILLS	string	framexml
+CLASS_TRAINER_SKILLS_DISPLAYED	lod	framexml
+CLASS_TRAINER_SKILL_HEIGHT	lod	framexml
+CLEARED_AFK	string	framexml
+CLEARED_DND	string	framexml
+CLEAR_AFK	string	framexml
+CLICK_CAMERA_STYLE	string	framexml
+CLICK_TO_LEARN	string	framexml
+CLICK_TO_MOVE	string	framexml
+CLIENT_RESTART_ALERT	string	framexml
+CLOSE	string	framexml
+CLOSES_IN	string	framexml
+CLOSE_CHAT_WINDOW	string	framexml
+CLOSE_LOG	string	framexml
+COD	string	framexml
+CODAmount	lod	framexml
+COD_AMOUNT	string	framexml
+COD_CONFIRMATION	string	framexml
+COD_INSUFFICIENT_MONEY	string	framexml
+COD_PAYMENT	string	framexml
+COIN_BUTTON_WIDTH	number	framexml
+COLOR	string	framexml
+COLOR_PICKER	string	framexml
+COMBATFEEDBACK_FADEINTIME	number	framexml
+COMBATFEEDBACK_FADEOUTTIME	number	framexml
+COMBATFEEDBACK_HOLDTIME	number	framexml
+COMBATHITCRITOTHEROTHER	string	framexml
+COMBATHITCRITOTHERSELF	string	framexml
+COMBATHITCRITSCHOOLOTHEROTHER	string	framexml
+COMBATHITCRITSCHOOLOTHERSELF	string	framexml
+COMBATHITCRITSCHOOLSELFOTHER	string	framexml
+COMBATHITCRITSELFOTHER	string	framexml
+COMBATHITOTHEROTHER	string	framexml
+COMBATHITOTHERSELF	string	framexml
+COMBATHITSCHOOLOTHEROTHER	string	framexml
+COMBATHITSCHOOLOTHERSELF	string	framexml
+COMBATHITSCHOOLSELFOTHER	string	framexml
+COMBATHITSELFOTHER	string	framexml
+COMBATLOGDISABLED	string	framexml
+COMBATLOGENABLED	string	framexml
+COMBATLOG_DISHONORGAIN	string	framexml
+COMBATLOG_HONORAWARD	string	framexml
+COMBATLOG_HONORGAIN	string	framexml
+COMBATLOG_XPGAIN	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION1	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION1_GROUP	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION1_RAID	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION2	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION2_GROUP	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION2_RAID	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION4	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION4_GROUP	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION4_RAID	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION5	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION5_GROUP	string	framexml
+COMBATLOG_XPGAIN_EXHAUSTION5_RAID	string	framexml
+COMBATLOG_XPGAIN_FIRSTPERSON	string	framexml
+COMBATLOG_XPGAIN_FIRSTPERSON_GROUP	string	framexml
+COMBATLOG_XPGAIN_FIRSTPERSON_RAID	string	framexml
+COMBATLOG_XPGAIN_FIRSTPERSON_UNNAMED	string	framexml
+COMBATLOG_XPGAIN_FIRSTPERSON_UNNAMED_GROUP	string	framexml
+COMBATLOG_XPGAIN_FIRSTPERSON_UNNAMED_RAID	string	framexml
+COMBATLOG_XPLOSS_FIRSTPERSON_UNNAMED	string	framexml
+COMBAT_ENEMY	string	framexml
+COMBAT_ERROR	string	framexml
+COMBAT_LOG	string	framexml
+COMBAT_MESSAGES	string	framexml
+COMBAT_MISC	string	framexml
+COMBAT_PARTY	string	framexml
+COMBAT_SELF	string	framexml
+COMBAT_TEXT_COMBO_POINTS	string	framexml
+COMBAT_TEXT_COMBO_POINTS_P1	string	framexml
+COMBAT_TEXT_CRIT_MAXHEIGHT	lod	framexml
+COMBAT_TEXT_CRIT_MINHEIGHT	lod	framexml
+COMBAT_TEXT_CRIT_SCALE_TIME	lod	framexml
+COMBAT_TEXT_CRIT_SHRINKTIME	lod	framexml
+COMBAT_TEXT_FADEOUT_TIME	lod	framexml
+COMBAT_TEXT_FLOAT_MODE	string	framexml
+COMBAT_TEXT_FLOAT_MODE_LABEL	string	framexml
+COMBAT_TEXT_HEIGHT	lod	framexml
+COMBAT_TEXT_HONOR_GAINED	string	framexml
+COMBAT_TEXT_LABEL	string	framexml
+COMBAT_TEXT_LOCATIONS	lod	framexml
+COMBAT_TEXT_LOW_HEALTH_THRESHOLD	lod	framexml
+COMBAT_TEXT_LOW_MANA_THRESHOLD	lod	framexml
+COMBAT_TEXT_MAX_OFFSET	lod	framexml
+COMBAT_TEXT_SCROLLSPEED	lod	framexml
+COMBAT_TEXT_SCROLL_ARC	string	framexml
+COMBAT_TEXT_SCROLL_DOWN	string	framexml
+COMBAT_TEXT_SCROLL_DOWN_TEXT	string	framexml
+COMBAT_TEXT_SCROLL_FUNCTION	lod	framexml
+COMBAT_TEXT_SCROLL_UP	string	framexml
+COMBAT_TEXT_SHOW_AURAS	string	framexml
+COMBAT_TEXT_SHOW_AURAS_TEXT	string	framexml
+COMBAT_TEXT_SHOW_AURA_FADE	string	framexml
+COMBAT_TEXT_SHOW_AURA_FADE_TEXT	string	framexml
+COMBAT_TEXT_SHOW_COMBAT_STATE	string	framexml
+COMBAT_TEXT_SHOW_COMBAT_STATE_TEXT	string	framexml
+COMBAT_TEXT_SHOW_COMBO_POINTS	string	framexml
+COMBAT_TEXT_SHOW_COMBO_POINTS_TEXT	string	framexml
+COMBAT_TEXT_SHOW_DODGE_PARRY_MISS	string	framexml
+COMBAT_TEXT_SHOW_DODGE_PARRY_MISS_TEXT	string	framexml
+COMBAT_TEXT_SHOW_FRIENDLY_NAMES	string	framexml
+COMBAT_TEXT_SHOW_FRIENDLY_NAMES_TEXT	string	framexml
+COMBAT_TEXT_SHOW_HONOR_GAINED	string	framexml
+COMBAT_TEXT_SHOW_HONOR_GAINED_TEXT	string	framexml
+COMBAT_TEXT_SHOW_LOW_HEALTH_MANA	string	framexml
+COMBAT_TEXT_SHOW_LOW_HEALTH_MANA_TEXT	string	framexml
+COMBAT_TEXT_SHOW_MANA	string	framexml
+COMBAT_TEXT_SHOW_MANA_TEXT	string	framexml
+COMBAT_TEXT_SHOW_REACTIVES	string	framexml
+COMBAT_TEXT_SHOW_REACTIVES_TEXT	string	framexml
+COMBAT_TEXT_SHOW_REPUTATION	string	framexml
+COMBAT_TEXT_SHOW_REPUTATION_TEXT	string	framexml
+COMBAT_TEXT_SHOW_RESISTANCES	string	framexml
+COMBAT_TEXT_SHOW_RESISTANCES_TEXT	string	framexml
+COMBAT_TEXT_SPACING	lod	framexml
+COMBAT_TEXT_STAGGER_RANGE	lod	framexml
+COMBAT_TEXT_TO_ANIMATE	lod	framexml
+COMBAT_TEXT_TYPE_INFO	lod	framexml
+COMBOFRAME_FADE_IN	number	framexml
+COMBOFRAME_FADE_OUT	number	framexml
+COMBOFRAME_HIGHLIGHT_FADE_IN	number	framexml
+COMBOFRAME_SHINE_FADE_IN	number	framexml
+COMBOFRAME_SHINE_FADE_OUT	number	framexml
+COMBO_FRAME_LAST_NUM_POINTS	number	framexml
+COMMAND	string	framexml
+COMMENTS_COLON	string	framexml
+COMPLETE	string	framexml
+COMPLETE_QUEST	string	framexml
+CONFIRMED_DELETING_CHARACTER_SPECIFIC_BINDINGS	lod	framexml
+CONFIRM_BATTLEFIELD_ENTRY	string	framexml
+CONFIRM_BINDER	string	framexml
+CONFIRM_BUY_BANK_SLOT	string	framexml
+CONFIRM_DELETING_CHARACTER_SPECIFIC_BINDINGS	string	framexml
+CONFIRM_GUILD_DISBAND	string	framexml
+CONFIRM_GUILD_LEAVE	string	framexml
+CONFIRM_GUILD_PROMOTE	string	framexml
+CONFIRM_LEAVE_QUEUE	string	framexml
+CONFIRM_LOOT_DISTRIBUTION	string	framexml
+CONFIRM_LOSE_BINDING_CHANGES	string	framexml
+CONFIRM_PET_UNLEARN	string	framexml
+CONFIRM_RESET_INSTANCES	string	framexml
+CONFIRM_SUMMON	string	framexml
+CONFIRM_TALENT_WIPE	string	framexml
+CONFIRM_XP_LOSS	string	framexml
+CONFIRM_XP_LOSS_AGAIN	string	framexml
+CONFIRM_XP_LOSS_AGAIN_NO_SICKNESS	string	framexml
+CONFIRM_XP_LOSS_NO_SICKNESS	string	framexml
+CONTAINER_OFFSET_X	number	framexml
+CONTAINER_OFFSET_Y	number	framexml
+CONTAINER_SCALE	number	framexml
+CONTAINER_SLOTS	string	framexml
+CONTAINER_SPACING	number	framexml
+CONTAINER_WIDTH	number	framexml
+CONTESTED_TERRITORY	string	framexml
+CONTINENT	string	framexml
+CONTINUE	string	framexml
+CONTROLS_LABEL	string	framexml
+CONVERT_TO_RAID	string	framexml
+COOLDOWN_REMAINING	string	framexml
+COPPER	string	framexml
+COPPER_PER_GOLD	number	framexml
+COPPER_PER_SILVER	number	framexml
+COPY_NAME	string	framexml
+CORPSE	string	framexml
+CORPSE_RED	string	framexml
+CORPSE_TOOLTIP	string	framexml
+COSTS_LABEL	string	framexml
+CRAFTS_DISPLAYED	lod	framexml
+CRAFT_SKILL_HEIGHT	lod	framexml
+CREATE	string	framexml
+CREATED_ITEM	string	framexml
+CREATED_ITEM_MULTIPLE	string	framexml
+CREATE_ALL	string	framexml
+CREATE_AUCTION	string	framexml
+CREATE_MACROS	string	framexml
+CREATURE	string	framexml
+CRUSHING_TRAILER	string	framexml
+CURRENTLY_EQUIPPED	string	framexml
+CURRENT_ACTIONBAR_PAGE	number	framexml
+CURRENT_BATTLEFIELD_QUEUES	table	framexml
+CURRENT_BID	string	framexml
+CURRENT_GUILD_MOTD	string	framexml
+CURRENT_PET	string	framexml
+CURRENT_QUESTS	string	framexml
+CURRENT_TARGETTARGET	lod	framexml
+CURSOR_OFFSET_X	number	framexml
+CURSOR_OFFSET_Y	number	framexml
+CURSOR_OLD_X	lod	framexml
+CURSOR_OLD_Y	lod	framexml
+CalculateAuctionDeposit	function	engine
+CameraOrSelectOrMoveStart	function	engine
+CameraOrSelectOrMoveStop	function	engine
+CameraZoomIn	function	engine
+CameraZoomOut	function	engine
+CanEditGuildInfo	function	engine
+CanEditMOTD	function	engine
+CanEditOfficerNote	function	engine
+CanEditPublicNote	function	engine
+CanGuildDemote	function	engine
+CanGuildInvite	function	engine
+CanGuildPromote	function	engine
+CanGuildRemove	function	engine
+CanInspect	function	engine
+CanJoinBattlefieldAsGroup	function	engine
+CanMerchantRepair	function	engine
+CanOpenPanels	function	framexml
+CanSendAuctionQuery	function	engine
+CanShowResetInstances	function	engine
+CanSignPetition	function	engine
+CanViewOfficerNote	function	engine
+CancelAreaSpiritHeal	function	engine
+CancelAuction	function	engine
+CancelDuel	function	engine
+CancelLogout	function	engine
+CancelMeetingStoneRequest	function	engine
+CancelPendingEquip	function	engine
+CancelPlayerBuff	function	engine
+CancelSkillUps	function	engine
+CancelTrackingBuff	function	engine
+CancelTrade	function	engine
+CancelTradeAccept	function	engine
+CaptureBar_Create	function	framexml
+CaptureBar_Update	function	framexml
+CastPetAction	function	engine
+CastShapeshiftForm	function	engine
+CastSpell	function	engine
+CastSpellByName	function	engine
+CastingBarBorder	table	framexml
+CastingBarFlash	table	framexml
+CastingBarFrame	table	framexml
+CastingBarFrameStatusBar	table	framexml
+CastingBarFrame_OnEvent	function	framexml
+CastingBarFrame_OnLoad	function	framexml
+CastingBarFrame_OnUpdate	function	framexml
+CastingBarFrame_UpdatePosition	lod	framexml
+CastingBarSpark	table	framexml
+CastingBarText	table	framexml
+ChangeActionBarPage	function	engine
+ChangeChatColor	function	engine
+ChannelBan	function	engine
+ChannelInvite	function	engine
+ChannelKick	function	engine
+ChannelMenuChatTypeGroups	table	framexml
+ChannelModerate	function	engine
+ChannelModerator	function	engine
+ChannelMute	function	engine
+ChannelToggleAnnouncements	function	engine
+ChannelUnban	function	engine
+ChannelUnmoderator	function	engine
+ChannelUnmute	function	engine
+CharacterAmmoSlot	table	framexml
+CharacterAmmoSlotCooldown	table	framexml
+CharacterAmmoSlotCount	table	framexml
+CharacterAmmoSlotIconTexture	table	framexml
+CharacterAmmoSlotNormalTexture	table	framexml
+CharacterAmmoSlotStock	table	framexml
+CharacterArmorFrame	table	framexml
+CharacterArmorFrameLabel	table	framexml
+CharacterArmorFrameStat	table	framexml
+CharacterArmorFrameStatText	table	framexml
+CharacterAttackFrame	table	framexml
+CharacterAttackFrameLabel	table	framexml
+CharacterAttackFrameStat	table	framexml
+CharacterAttackFrameStatText	table	framexml
+CharacterAttackPowerFrame	table	framexml
+CharacterAttackPowerFrameLabel	table	framexml
+CharacterAttackPowerFrameStat	table	framexml
+CharacterAttackPowerFrameStatText	table	framexml
+CharacterAttributesFrame	table	framexml
+CharacterBackSlot	table	framexml
+CharacterBackSlotCooldown	table	framexml
+CharacterBackSlotCount	table	framexml
+CharacterBackSlotIconTexture	table	framexml
+CharacterBackSlotNormalTexture	table	framexml
+CharacterBackSlotStock	table	framexml
+CharacterBag0Slot	table	framexml
+CharacterBag0SlotCooldown	table	framexml
+CharacterBag0SlotCount	table	framexml
+CharacterBag0SlotIconTexture	table	framexml
+CharacterBag0SlotItemAnim	table	framexml
+CharacterBag0SlotNormalTexture	table	framexml
+CharacterBag0SlotStock	table	framexml
+CharacterBag1Slot	table	framexml
+CharacterBag1SlotCooldown	table	framexml
+CharacterBag1SlotCount	table	framexml
+CharacterBag1SlotIconTexture	table	framexml
+CharacterBag1SlotItemAnim	table	framexml
+CharacterBag1SlotNormalTexture	table	framexml
+CharacterBag1SlotStock	table	framexml
+CharacterBag2Slot	table	framexml
+CharacterBag2SlotCooldown	table	framexml
+CharacterBag2SlotCount	table	framexml
+CharacterBag2SlotIconTexture	table	framexml
+CharacterBag2SlotItemAnim	table	framexml
+CharacterBag2SlotNormalTexture	table	framexml
+CharacterBag2SlotStock	table	framexml
+CharacterBag3Slot	table	framexml
+CharacterBag3SlotCooldown	table	framexml
+CharacterBag3SlotCount	table	framexml
+CharacterBag3SlotIconTexture	table	framexml
+CharacterBag3SlotItemAnim	table	framexml
+CharacterBag3SlotNormalTexture	table	framexml
+CharacterBag3SlotStock	table	framexml
+CharacterChestSlot	table	framexml
+CharacterChestSlotCooldown	table	framexml
+CharacterChestSlotCount	table	framexml
+CharacterChestSlotIconTexture	table	framexml
+CharacterChestSlotNormalTexture	table	framexml
+CharacterChestSlotStock	table	framexml
+CharacterDamageFrame	table	framexml
+CharacterDamageFrameLabel	table	framexml
+CharacterDamageFrameStat	table	framexml
+CharacterDamageFrameStatText	table	framexml
+CharacterDamageFrame_OnEnter	function	framexml
+CharacterFeetSlot	table	framexml
+CharacterFeetSlotCooldown	table	framexml
+CharacterFeetSlotCount	table	framexml
+CharacterFeetSlotIconTexture	table	framexml
+CharacterFeetSlotNormalTexture	table	framexml
+CharacterFeetSlotStock	table	framexml
+CharacterFinger0Slot	table	framexml
+CharacterFinger0SlotCooldown	table	framexml
+CharacterFinger0SlotCount	table	framexml
+CharacterFinger0SlotIconTexture	table	framexml
+CharacterFinger0SlotNormalTexture	table	framexml
+CharacterFinger0SlotStock	table	framexml
+CharacterFinger1Slot	table	framexml
+CharacterFinger1SlotCooldown	table	framexml
+CharacterFinger1SlotCount	table	framexml
+CharacterFinger1SlotIconTexture	table	framexml
+CharacterFinger1SlotNormalTexture	table	framexml
+CharacterFinger1SlotStock	table	framexml
+CharacterFrame	table	framexml
+CharacterFrameCloseButton	table	framexml
+CharacterFramePortrait	table	framexml
+CharacterFrameTab1	table	framexml
+CharacterFrameTab1HighlightTexture	table	framexml
+CharacterFrameTab1Left	table	framexml
+CharacterFrameTab1LeftDisabled	table	framexml
+CharacterFrameTab1Middle	table	framexml
+CharacterFrameTab1MiddleDisabled	table	framexml
+CharacterFrameTab1Right	table	framexml
+CharacterFrameTab1RightDisabled	table	framexml
+CharacterFrameTab1Text	table	framexml
+CharacterFrameTab2	table	framexml
+CharacterFrameTab2HighlightTexture	table	framexml
+CharacterFrameTab2Left	table	framexml
+CharacterFrameTab2LeftDisabled	table	framexml
+CharacterFrameTab2Middle	table	framexml
+CharacterFrameTab2MiddleDisabled	table	framexml
+CharacterFrameTab2Right	table	framexml
+CharacterFrameTab2RightDisabled	table	framexml
+CharacterFrameTab2Text	table	framexml
+CharacterFrameTab3	table	framexml
+CharacterFrameTab3HighlightTexture	table	framexml
+CharacterFrameTab3Left	table	framexml
+CharacterFrameTab3LeftDisabled	table	framexml
+CharacterFrameTab3Middle	table	framexml
+CharacterFrameTab3MiddleDisabled	table	framexml
+CharacterFrameTab3Right	table	framexml
+CharacterFrameTab3RightDisabled	table	framexml
+CharacterFrameTab3Text	table	framexml
+CharacterFrameTab4	table	framexml
+CharacterFrameTab4HighlightTexture	table	framexml
+CharacterFrameTab4Left	table	framexml
+CharacterFrameTab4LeftDisabled	table	framexml
+CharacterFrameTab4Middle	table	framexml
+CharacterFrameTab4MiddleDisabled	table	framexml
+CharacterFrameTab4Right	table	framexml
+CharacterFrameTab4RightDisabled	table	framexml
+CharacterFrameTab4Text	table	framexml
+CharacterFrameTab5	table	framexml
+CharacterFrameTab5HighlightTexture	table	framexml
+CharacterFrameTab5Left	table	framexml
+CharacterFrameTab5LeftDisabled	table	framexml
+CharacterFrameTab5Middle	table	framexml
+CharacterFrameTab5MiddleDisabled	table	framexml
+CharacterFrameTab5Right	table	framexml
+CharacterFrameTab5RightDisabled	table	framexml
+CharacterFrameTab5Text	table	framexml
+CharacterFrameTabButtonTemplate	lod	framexml
+CharacterFrameTab_OnClick	function	framexml
+CharacterFrame_OnEvent	function	framexml
+CharacterFrame_OnHide	function	framexml
+CharacterFrame_OnLoad	function	framexml
+CharacterFrame_OnShow	function	framexml
+CharacterFrame_ShowSubFrame	function	framexml
+CharacterGuildText	table	framexml
+CharacterHandsSlot	table	framexml
+CharacterHandsSlotCooldown	table	framexml
+CharacterHandsSlotCount	table	framexml
+CharacterHandsSlotIconTexture	table	framexml
+CharacterHandsSlotNormalTexture	table	framexml
+CharacterHandsSlotStock	table	framexml
+CharacterHeadSlot	table	framexml
+CharacterHeadSlotCooldown	table	framexml
+CharacterHeadSlotCount	table	framexml
+CharacterHeadSlotIconTexture	table	framexml
+CharacterHeadSlotNormalTexture	table	framexml
+CharacterHeadSlotStock	table	framexml
+CharacterLegsSlot	table	framexml
+CharacterLegsSlotCooldown	table	framexml
+CharacterLegsSlotCount	table	framexml
+CharacterLegsSlotIconTexture	table	framexml
+CharacterLegsSlotNormalTexture	table	framexml
+CharacterLegsSlotStock	table	framexml
+CharacterLevelText	table	framexml
+CharacterMainHandSlot	table	framexml
+CharacterMainHandSlotCooldown	table	framexml
+CharacterMainHandSlotCount	table	framexml
+CharacterMainHandSlotIconTexture	table	framexml
+CharacterMainHandSlotNormalTexture	table	framexml
+CharacterMainHandSlotStock	table	framexml
+CharacterMicroButton	table	framexml
+CharacterMicroButton_OnEvent	function	framexml
+CharacterMicroButton_OnLoad	function	framexml
+CharacterMicroButton_SetNormal	function	framexml
+CharacterMicroButton_SetPushed	function	framexml
+CharacterModelFrame	table	framexml
+CharacterModelFrameRotateLeftButton	table	framexml
+CharacterModelFrameRotateRightButton	table	framexml
+CharacterModelFrame_OnMouseUp	function	framexml
+CharacterNameFrame	table	framexml
+CharacterNameText	table	framexml
+CharacterNeckSlot	table	framexml
+CharacterNeckSlotCooldown	table	framexml
+CharacterNeckSlotCount	table	framexml
+CharacterNeckSlotIconTexture	table	framexml
+CharacterNeckSlotNormalTexture	table	framexml
+CharacterNeckSlotStock	table	framexml
+CharacterRangedAttackFrame	table	framexml
+CharacterRangedAttackFrameLabel	table	framexml
+CharacterRangedAttackFrameStat	table	framexml
+CharacterRangedAttackFrameStatText	table	framexml
+CharacterRangedAttackPowerFrame	table	framexml
+CharacterRangedAttackPowerFrameLabel	table	framexml
+CharacterRangedAttackPowerFrameStat	table	framexml
+CharacterRangedAttackPowerFrameStatText	table	framexml
+CharacterRangedDamageFrame	table	framexml
+CharacterRangedDamageFrameLabel	table	framexml
+CharacterRangedDamageFrameStat	table	framexml
+CharacterRangedDamageFrameStatText	table	framexml
+CharacterRangedDamageFrame_OnEnter	function	framexml
+CharacterRangedSlot	table	framexml
+CharacterRangedSlotCooldown	table	framexml
+CharacterRangedSlotCount	table	framexml
+CharacterRangedSlotIconTexture	table	framexml
+CharacterRangedSlotNormalTexture	table	framexml
+CharacterRangedSlotStock	table	framexml
+CharacterResistanceFrame	table	framexml
+CharacterSecondaryHandSlot	table	framexml
+CharacterSecondaryHandSlotCooldown	table	framexml
+CharacterSecondaryHandSlotCount	table	framexml
+CharacterSecondaryHandSlotIconTexture	table	framexml
+CharacterSecondaryHandSlotNormalTexture	table	framexml
+CharacterSecondaryHandSlotStock	table	framexml
+CharacterShirtSlot	table	framexml
+CharacterShirtSlotCooldown	table	framexml
+CharacterShirtSlotCount	table	framexml
+CharacterShirtSlotIconTexture	table	framexml
+CharacterShirtSlotNormalTexture	table	framexml
+CharacterShirtSlotStock	table	framexml
+CharacterShoulderSlot	table	framexml
+CharacterShoulderSlotCooldown	table	framexml
+CharacterShoulderSlotCount	table	framexml
+CharacterShoulderSlotIconTexture	table	framexml
+CharacterShoulderSlotNormalTexture	table	framexml
+CharacterShoulderSlotStock	table	framexml
+CharacterStatFrame1	table	framexml
+CharacterStatFrame1Label	table	framexml
+CharacterStatFrame1Stat	table	framexml
+CharacterStatFrame1StatText	table	framexml
+CharacterStatFrame2	table	framexml
+CharacterStatFrame2Label	table	framexml
+CharacterStatFrame2Stat	table	framexml
+CharacterStatFrame2StatText	table	framexml
+CharacterStatFrame3	table	framexml
+CharacterStatFrame3Label	table	framexml
+CharacterStatFrame3Stat	table	framexml
+CharacterStatFrame3StatText	table	framexml
+CharacterStatFrame4	table	framexml
+CharacterStatFrame4Label	table	framexml
+CharacterStatFrame4Stat	table	framexml
+CharacterStatFrame4StatText	table	framexml
+CharacterStatFrame5	table	framexml
+CharacterStatFrame5Label	table	framexml
+CharacterStatFrame5Stat	table	framexml
+CharacterStatFrame5StatText	table	framexml
+CharacterTabardSlot	table	framexml
+CharacterTabardSlotCooldown	table	framexml
+CharacterTabardSlotCount	table	framexml
+CharacterTabardSlotIconTexture	table	framexml
+CharacterTabardSlotNormalTexture	table	framexml
+CharacterTabardSlotStock	table	framexml
+CharacterTitleText	table	framexml
+CharacterTrinket0Slot	table	framexml
+CharacterTrinket0SlotCooldown	table	framexml
+CharacterTrinket0SlotCount	table	framexml
+CharacterTrinket0SlotIconTexture	table	framexml
+CharacterTrinket0SlotNormalTexture	table	framexml
+CharacterTrinket0SlotStock	table	framexml
+CharacterTrinket1Slot	table	framexml
+CharacterTrinket1SlotCooldown	table	framexml
+CharacterTrinket1SlotCount	table	framexml
+CharacterTrinket1SlotIconTexture	table	framexml
+CharacterTrinket1SlotNormalTexture	table	framexml
+CharacterTrinket1SlotStock	table	framexml
+CharacterWaistSlot	table	framexml
+CharacterWaistSlotCooldown	table	framexml
+CharacterWaistSlotCount	table	framexml
+CharacterWaistSlotIconTexture	table	framexml
+CharacterWaistSlotNormalTexture	table	framexml
+CharacterWaistSlotStock	table	framexml
+CharacterWristSlot	table	framexml
+CharacterWristSlotCooldown	table	framexml
+CharacterWristSlotCount	table	framexml
+CharacterWristSlotIconTexture	table	framexml
+CharacterWristSlotNormalTexture	table	framexml
+CharacterWristSlotStock	table	framexml
+ChatEdit_AddHistory	function	framexml
+ChatEdit_ExtractChannel	function	framexml
+ChatEdit_ExtractTellTarget	function	framexml
+ChatEdit_GetLastTellTarget	function	framexml
+ChatEdit_GetLastToldTarget	function	framexml
+ChatEdit_GetNextTellTarget	function	framexml
+ChatEdit_OnEnterPressed	function	framexml
+ChatEdit_OnEscapePressed	function	framexml
+ChatEdit_OnInputLanguageChanged	function	framexml
+ChatEdit_OnLoad	function	framexml
+ChatEdit_OnShow	function	framexml
+ChatEdit_OnSpacePressed	function	framexml
+ChatEdit_OnTabPressed	function	framexml
+ChatEdit_OnTextChanged	function	framexml
+ChatEdit_OnTextSet	function	framexml
+ChatEdit_OnUpdate	function	framexml
+ChatEdit_ParseText	function	framexml
+ChatEdit_SendText	function	framexml
+ChatEdit_SetLastTellTarget	function	framexml
+ChatEdit_SetLastToldTarget	function	framexml
+ChatEdit_UpdateHeader	function	framexml
+ChatFontNormal	table	framexml
+ChatFrame1	table	framexml
+ChatFrame10TabDockRegion	table	framexml
+ChatFrame10TabDockRegionHighlight	table	framexml
+ChatFrame1Background	table	framexml
+ChatFrame1BottomButton	table	framexml
+ChatFrame1BottomButtonFlash	table	framexml
+ChatFrame1DownButton	table	framexml
+ChatFrame1ResizeBottom	table	framexml
+ChatFrame1ResizeBottomLeft	table	framexml
+ChatFrame1ResizeBottomLeftTexture	table	framexml
+ChatFrame1ResizeBottomRight	table	framexml
+ChatFrame1ResizeBottomRightTexture	table	framexml
+ChatFrame1ResizeBottomTexture	table	framexml
+ChatFrame1ResizeLeft	table	framexml
+ChatFrame1ResizeLeftTexture	table	framexml
+ChatFrame1ResizeRight	table	framexml
+ChatFrame1ResizeRightTexture	table	framexml
+ChatFrame1ResizeTop	table	framexml
+ChatFrame1ResizeTopLeft	table	framexml
+ChatFrame1ResizeTopLeftTexture	table	framexml
+ChatFrame1ResizeTopRight	table	framexml
+ChatFrame1ResizeTopRightTexture	table	framexml
+ChatFrame1ResizeTopTexture	table	framexml
+ChatFrame1Tab	table	framexml
+ChatFrame1TabDockRegion	table	framexml
+ChatFrame1TabDockRegionHighlight	table	framexml
+ChatFrame1TabDropDown	table	framexml
+ChatFrame1TabDropDownButton	table	framexml
+ChatFrame1TabDropDownButtonDisabledTexture	table	framexml
+ChatFrame1TabDropDownButtonHighlightTexture	table	framexml
+ChatFrame1TabDropDownButtonNormalTexture	table	framexml
+ChatFrame1TabDropDownButtonPushedTexture	table	framexml
+ChatFrame1TabDropDownLeft	table	framexml
+ChatFrame1TabDropDownMiddle	table	framexml
+ChatFrame1TabDropDownRight	table	framexml
+ChatFrame1TabDropDownText	table	framexml
+ChatFrame1TabFlash	table	framexml
+ChatFrame1TabLeft	table	framexml
+ChatFrame1TabMiddle	table	framexml
+ChatFrame1TabRight	table	framexml
+ChatFrame1TabText	table	framexml
+ChatFrame1UpButton	table	framexml
+ChatFrame2	table	framexml
+ChatFrame2Background	table	framexml
+ChatFrame2BottomButton	table	framexml
+ChatFrame2BottomButtonFlash	table	framexml
+ChatFrame2DownButton	table	framexml
+ChatFrame2ResizeBottom	table	framexml
+ChatFrame2ResizeBottomLeft	table	framexml
+ChatFrame2ResizeBottomLeftTexture	table	framexml
+ChatFrame2ResizeBottomRight	table	framexml
+ChatFrame2ResizeBottomRightTexture	table	framexml
+ChatFrame2ResizeBottomTexture	table	framexml
+ChatFrame2ResizeLeft	table	framexml
+ChatFrame2ResizeLeftTexture	table	framexml
+ChatFrame2ResizeRight	table	framexml
+ChatFrame2ResizeRightTexture	table	framexml
+ChatFrame2ResizeTop	table	framexml
+ChatFrame2ResizeTopLeft	table	framexml
+ChatFrame2ResizeTopLeftTexture	table	framexml
+ChatFrame2ResizeTopRight	table	framexml
+ChatFrame2ResizeTopRightTexture	table	framexml
+ChatFrame2ResizeTopTexture	table	framexml
+ChatFrame2Tab	table	framexml
+ChatFrame2TabDockRegion	table	framexml
+ChatFrame2TabDockRegionHighlight	table	framexml
+ChatFrame2TabDropDown	table	framexml
+ChatFrame2TabDropDownButton	table	framexml
+ChatFrame2TabDropDownButtonDisabledTexture	table	framexml
+ChatFrame2TabDropDownButtonHighlightTexture	table	framexml
+ChatFrame2TabDropDownButtonNormalTexture	table	framexml
+ChatFrame2TabDropDownButtonPushedTexture	table	framexml
+ChatFrame2TabDropDownLeft	table	framexml
+ChatFrame2TabDropDownMiddle	table	framexml
+ChatFrame2TabDropDownRight	table	framexml
+ChatFrame2TabDropDownText	table	framexml
+ChatFrame2TabFlash	table	framexml
+ChatFrame2TabLeft	table	framexml
+ChatFrame2TabMiddle	table	framexml
+ChatFrame2TabRight	table	framexml
+ChatFrame2TabText	table	framexml
+ChatFrame2UpButton	table	framexml
+ChatFrame3	table	framexml
+ChatFrame3Background	table	framexml
+ChatFrame3BottomButton	table	framexml
+ChatFrame3BottomButtonFlash	table	framexml
+ChatFrame3DownButton	table	framexml
+ChatFrame3ResizeBottom	table	framexml
+ChatFrame3ResizeBottomLeft	table	framexml
+ChatFrame3ResizeBottomLeftTexture	table	framexml
+ChatFrame3ResizeBottomRight	table	framexml
+ChatFrame3ResizeBottomRightTexture	table	framexml
+ChatFrame3ResizeBottomTexture	table	framexml
+ChatFrame3ResizeLeft	table	framexml
+ChatFrame3ResizeLeftTexture	table	framexml
+ChatFrame3ResizeRight	table	framexml
+ChatFrame3ResizeRightTexture	table	framexml
+ChatFrame3ResizeTop	table	framexml
+ChatFrame3ResizeTopLeft	table	framexml
+ChatFrame3ResizeTopLeftTexture	table	framexml
+ChatFrame3ResizeTopRight	table	framexml
+ChatFrame3ResizeTopRightTexture	table	framexml
+ChatFrame3ResizeTopTexture	table	framexml
+ChatFrame3Tab	table	framexml
+ChatFrame3TabDockRegion	table	framexml
+ChatFrame3TabDockRegionHighlight	table	framexml
+ChatFrame3TabDropDown	table	framexml
+ChatFrame3TabDropDownButton	table	framexml
+ChatFrame3TabDropDownButtonDisabledTexture	table	framexml
+ChatFrame3TabDropDownButtonHighlightTexture	table	framexml
+ChatFrame3TabDropDownButtonNormalTexture	table	framexml
+ChatFrame3TabDropDownButtonPushedTexture	table	framexml
+ChatFrame3TabDropDownLeft	table	framexml
+ChatFrame3TabDropDownMiddle	table	framexml
+ChatFrame3TabDropDownRight	table	framexml
+ChatFrame3TabDropDownText	table	framexml
+ChatFrame3TabFlash	table	framexml
+ChatFrame3TabLeft	table	framexml
+ChatFrame3TabMiddle	table	framexml
+ChatFrame3TabRight	table	framexml
+ChatFrame3TabText	table	framexml
+ChatFrame3UpButton	table	framexml
+ChatFrame4	table	framexml
+ChatFrame4Background	table	framexml
+ChatFrame4BottomButton	table	framexml
+ChatFrame4BottomButtonFlash	table	framexml
+ChatFrame4DownButton	table	framexml
+ChatFrame4ResizeBottom	table	framexml
+ChatFrame4ResizeBottomLeft	table	framexml
+ChatFrame4ResizeBottomLeftTexture	table	framexml
+ChatFrame4ResizeBottomRight	table	framexml
+ChatFrame4ResizeBottomRightTexture	table	framexml
+ChatFrame4ResizeBottomTexture	table	framexml
+ChatFrame4ResizeLeft	table	framexml
+ChatFrame4ResizeLeftTexture	table	framexml
+ChatFrame4ResizeRight	table	framexml
+ChatFrame4ResizeRightTexture	table	framexml
+ChatFrame4ResizeTop	table	framexml
+ChatFrame4ResizeTopLeft	table	framexml
+ChatFrame4ResizeTopLeftTexture	table	framexml
+ChatFrame4ResizeTopRight	table	framexml
+ChatFrame4ResizeTopRightTexture	table	framexml
+ChatFrame4ResizeTopTexture	table	framexml
+ChatFrame4Tab	table	framexml
+ChatFrame4TabDockRegion	table	framexml
+ChatFrame4TabDockRegionHighlight	table	framexml
+ChatFrame4TabDropDown	table	framexml
+ChatFrame4TabDropDownButton	table	framexml
+ChatFrame4TabDropDownButtonDisabledTexture	table	framexml
+ChatFrame4TabDropDownButtonHighlightTexture	table	framexml
+ChatFrame4TabDropDownButtonNormalTexture	table	framexml
+ChatFrame4TabDropDownButtonPushedTexture	table	framexml
+ChatFrame4TabDropDownLeft	table	framexml
+ChatFrame4TabDropDownMiddle	table	framexml
+ChatFrame4TabDropDownRight	table	framexml
+ChatFrame4TabDropDownText	table	framexml
+ChatFrame4TabFlash	table	framexml
+ChatFrame4TabLeft	table	framexml
+ChatFrame4TabMiddle	table	framexml
+ChatFrame4TabRight	table	framexml
+ChatFrame4TabText	table	framexml
+ChatFrame4UpButton	table	framexml
+ChatFrame5	table	framexml
+ChatFrame5Background	table	framexml
+ChatFrame5BottomButton	table	framexml
+ChatFrame5BottomButtonFlash	table	framexml
+ChatFrame5DownButton	table	framexml
+ChatFrame5ResizeBottom	table	framexml
+ChatFrame5ResizeBottomLeft	table	framexml
+ChatFrame5ResizeBottomLeftTexture	table	framexml
+ChatFrame5ResizeBottomRight	table	framexml
+ChatFrame5ResizeBottomRightTexture	table	framexml
+ChatFrame5ResizeBottomTexture	table	framexml
+ChatFrame5ResizeLeft	table	framexml
+ChatFrame5ResizeLeftTexture	table	framexml
+ChatFrame5ResizeRight	table	framexml
+ChatFrame5ResizeRightTexture	table	framexml
+ChatFrame5ResizeTop	table	framexml
+ChatFrame5ResizeTopLeft	table	framexml
+ChatFrame5ResizeTopLeftTexture	table	framexml
+ChatFrame5ResizeTopRight	table	framexml
+ChatFrame5ResizeTopRightTexture	table	framexml
+ChatFrame5ResizeTopTexture	table	framexml
+ChatFrame5Tab	table	framexml
+ChatFrame5TabDockRegion	table	framexml
+ChatFrame5TabDockRegionHighlight	table	framexml
+ChatFrame5TabDropDown	table	framexml
+ChatFrame5TabDropDownButton	table	framexml
+ChatFrame5TabDropDownButtonDisabledTexture	table	framexml
+ChatFrame5TabDropDownButtonHighlightTexture	table	framexml
+ChatFrame5TabDropDownButtonNormalTexture	table	framexml
+ChatFrame5TabDropDownButtonPushedTexture	table	framexml
+ChatFrame5TabDropDownLeft	table	framexml
+ChatFrame5TabDropDownMiddle	table	framexml
+ChatFrame5TabDropDownRight	table	framexml
+ChatFrame5TabDropDownText	table	framexml
+ChatFrame5TabFlash	table	framexml
+ChatFrame5TabLeft	table	framexml
+ChatFrame5TabMiddle	table	framexml
+ChatFrame5TabRight	table	framexml
+ChatFrame5TabText	table	framexml
+ChatFrame5UpButton	table	framexml
+ChatFrame6	table	framexml
+ChatFrame6Background	table	framexml
+ChatFrame6BottomButton	table	framexml
+ChatFrame6BottomButtonFlash	table	framexml
+ChatFrame6DownButton	table	framexml
+ChatFrame6ResizeBottom	table	framexml
+ChatFrame6ResizeBottomLeft	table	framexml
+ChatFrame6ResizeBottomLeftTexture	table	framexml
+ChatFrame6ResizeBottomRight	table	framexml
+ChatFrame6ResizeBottomRightTexture	table	framexml
+ChatFrame6ResizeBottomTexture	table	framexml
+ChatFrame6ResizeLeft	table	framexml
+ChatFrame6ResizeLeftTexture	table	framexml
+ChatFrame6ResizeRight	table	framexml
+ChatFrame6ResizeRightTexture	table	framexml
+ChatFrame6ResizeTop	table	framexml
+ChatFrame6ResizeTopLeft	table	framexml
+ChatFrame6ResizeTopLeftTexture	table	framexml
+ChatFrame6ResizeTopRight	table	framexml
+ChatFrame6ResizeTopRightTexture	table	framexml
+ChatFrame6ResizeTopTexture	table	framexml
+ChatFrame6Tab	table	framexml
+ChatFrame6TabDockRegion	table	framexml
+ChatFrame6TabDockRegionHighlight	table	framexml
+ChatFrame6TabDropDown	table	framexml
+ChatFrame6TabDropDownButton	table	framexml
+ChatFrame6TabDropDownButtonDisabledTexture	table	framexml
+ChatFrame6TabDropDownButtonHighlightTexture	table	framexml
+ChatFrame6TabDropDownButtonNormalTexture	table	framexml
+ChatFrame6TabDropDownButtonPushedTexture	table	framexml
+ChatFrame6TabDropDownLeft	table	framexml
+ChatFrame6TabDropDownMiddle	table	framexml
+ChatFrame6TabDropDownRight	table	framexml
+ChatFrame6TabDropDownText	table	framexml
+ChatFrame6TabFlash	table	framexml
+ChatFrame6TabLeft	table	framexml
+ChatFrame6TabMiddle	table	framexml
+ChatFrame6TabRight	table	framexml
+ChatFrame6TabText	table	framexml
+ChatFrame6UpButton	table	framexml
+ChatFrame7	table	framexml
+ChatFrame7Background	table	framexml
+ChatFrame7BottomButton	table	framexml
+ChatFrame7BottomButtonFlash	table	framexml
+ChatFrame7DownButton	table	framexml
+ChatFrame7ResizeBottom	table	framexml
+ChatFrame7ResizeBottomLeft	table	framexml
+ChatFrame7ResizeBottomLeftTexture	table	framexml
+ChatFrame7ResizeBottomRight	table	framexml
+ChatFrame7ResizeBottomRightTexture	table	framexml
+ChatFrame7ResizeBottomTexture	table	framexml
+ChatFrame7ResizeLeft	table	framexml
+ChatFrame7ResizeLeftTexture	table	framexml
+ChatFrame7ResizeRight	table	framexml
+ChatFrame7ResizeRightTexture	table	framexml
+ChatFrame7ResizeTop	table	framexml
+ChatFrame7ResizeTopLeft	table	framexml
+ChatFrame7ResizeTopLeftTexture	table	framexml
+ChatFrame7ResizeTopRight	table	framexml
+ChatFrame7ResizeTopRightTexture	table	framexml
+ChatFrame7ResizeTopTexture	table	framexml
+ChatFrame7Tab	table	framexml
+ChatFrame7TabDockRegion	table	framexml
+ChatFrame7TabDockRegionHighlight	table	framexml
+ChatFrame7TabDropDown	table	framexml
+ChatFrame7TabDropDownButton	table	framexml
+ChatFrame7TabDropDownButtonDisabledTexture	table	framexml
+ChatFrame7TabDropDownButtonHighlightTexture	table	framexml
+ChatFrame7TabDropDownButtonNormalTexture	table	framexml
+ChatFrame7TabDropDownButtonPushedTexture	table	framexml
+ChatFrame7TabDropDownLeft	table	framexml
+ChatFrame7TabDropDownMiddle	table	framexml
+ChatFrame7TabDropDownRight	table	framexml
+ChatFrame7TabDropDownText	table	framexml
+ChatFrame7TabFlash	table	framexml
+ChatFrame7TabLeft	table	framexml
+ChatFrame7TabMiddle	table	framexml
+ChatFrame7TabRight	table	framexml
+ChatFrame7TabText	table	framexml
+ChatFrame7UpButton	table	framexml
+ChatFrame8TabDockRegion	table	framexml
+ChatFrame8TabDockRegionHighlight	table	framexml
+ChatFrame9TabDockRegion	table	framexml
+ChatFrame9TabDockRegionHighlight	table	framexml
+ChatFrameEditBox	table	framexml
+ChatFrameEditBoxHeader	table	framexml
+ChatFrameEditBoxLanguage	table	framexml
+ChatFrameEditBoxLeft	table	framexml
+ChatFrameEditBoxRight	table	framexml
+ChatFrameEditBoxTemplate	lod	framexml
+ChatFrameMenuButton	table	framexml
+ChatFrameTemplate	lod	framexml
+ChatFrame_ActivateCombatMessages	function	framexml
+ChatFrame_AddChannel	function	framexml
+ChatFrame_AddMessageGroup	function	framexml
+ChatFrame_ChatPageDown	function	framexml
+ChatFrame_ChatPageUp	function	framexml
+ChatFrame_DisplayChatHelp	function	framexml
+ChatFrame_DisplayGameTime	function	framexml
+ChatFrame_DisplayGuildHelp	function	framexml
+ChatFrame_DisplayHelpText	function	framexml
+ChatFrame_DisplayMacroHelpText	function	framexml
+ChatFrame_DisplayStartupText	function	framexml
+ChatFrame_DisplayTimePlayed	function	framexml
+ChatFrame_OnEvent	function	framexml
+ChatFrame_OnHyperlinkShow	function	framexml
+ChatFrame_OnLoad	function	framexml
+ChatFrame_OnMouseWheel	function	framexml
+ChatFrame_OnUpdate	function	framexml
+ChatFrame_OpenChat	function	framexml
+ChatFrame_OpenMenu	function	framexml
+ChatFrame_RegisterForChannels	function	framexml
+ChatFrame_RegisterForMessages	function	framexml
+ChatFrame_RemoveAllChannels	function	framexml
+ChatFrame_RemoveAllMessageGroups	function	framexml
+ChatFrame_RemoveChannel	function	framexml
+ChatFrame_RemoveMessageGroup	function	framexml
+ChatFrame_ReplyTell	function	framexml
+ChatFrame_ReplyTell2	function	framexml
+ChatFrame_ScrollDown	function	framexml
+ChatFrame_ScrollToBottom	function	framexml
+ChatFrame_ScrollUp	function	framexml
+ChatFrame_SendTell	function	framexml
+ChatFrame_TimeBreakDown	function	framexml
+ChatMenu	table	framexml
+ChatMenuButton1	table	framexml
+ChatMenuButton10	table	framexml
+ChatMenuButton10ShortcutText	table	framexml
+ChatMenuButton11	table	framexml
+ChatMenuButton11ShortcutText	table	framexml
+ChatMenuButton12	table	framexml
+ChatMenuButton12ShortcutText	table	framexml
+ChatMenuButton13	table	framexml
+ChatMenuButton13ShortcutText	table	framexml
+ChatMenuButton14	table	framexml
+ChatMenuButton14ShortcutText	table	framexml
+ChatMenuButton15	table	framexml
+ChatMenuButton15ShortcutText	table	framexml
+ChatMenuButton16	table	framexml
+ChatMenuButton16ShortcutText	table	framexml
+ChatMenuButton17	table	framexml
+ChatMenuButton17ShortcutText	table	framexml
+ChatMenuButton18	table	framexml
+ChatMenuButton18ShortcutText	table	framexml
+ChatMenuButton19	table	framexml
+ChatMenuButton19ShortcutText	table	framexml
+ChatMenuButton1ShortcutText	table	framexml
+ChatMenuButton2	table	framexml
+ChatMenuButton20	table	framexml
+ChatMenuButton20ShortcutText	table	framexml
+ChatMenuButton21	table	framexml
+ChatMenuButton21ShortcutText	table	framexml
+ChatMenuButton22	table	framexml
+ChatMenuButton22ShortcutText	table	framexml
+ChatMenuButton23	table	framexml
+ChatMenuButton23ShortcutText	table	framexml
+ChatMenuButton24	table	framexml
+ChatMenuButton24ShortcutText	table	framexml
+ChatMenuButton25	table	framexml
+ChatMenuButton25ShortcutText	table	framexml
+ChatMenuButton26	table	framexml
+ChatMenuButton26ShortcutText	table	framexml
+ChatMenuButton27	table	framexml
+ChatMenuButton27ShortcutText	table	framexml
+ChatMenuButton28	table	framexml
+ChatMenuButton28ShortcutText	table	framexml
+ChatMenuButton29	table	framexml
+ChatMenuButton29ShortcutText	table	framexml
+ChatMenuButton2ShortcutText	table	framexml
+ChatMenuButton3	table	framexml
+ChatMenuButton30	table	framexml
+ChatMenuButton30ShortcutText	table	framexml
+ChatMenuButton31	table	framexml
+ChatMenuButton31ShortcutText	table	framexml
+ChatMenuButton32	table	framexml
+ChatMenuButton32ShortcutText	table	framexml
+ChatMenuButton3ShortcutText	table	framexml
+ChatMenuButton4	table	framexml
+ChatMenuButton4ShortcutText	table	framexml
+ChatMenuButton5	table	framexml
+ChatMenuButton5ShortcutText	table	framexml
+ChatMenuButton6	table	framexml
+ChatMenuButton6ShortcutText	table	framexml
+ChatMenuButton7	table	framexml
+ChatMenuButton7ShortcutText	table	framexml
+ChatMenuButton8	table	framexml
+ChatMenuButton8ShortcutText	table	framexml
+ChatMenuButton9	table	framexml
+ChatMenuButton9ShortcutText	table	framexml
+ChatMenu_Emote	function	framexml
+ChatMenu_Guild	function	framexml
+ChatMenu_OnLoad	function	framexml
+ChatMenu_OnShow	function	framexml
+ChatMenu_Party	function	framexml
+ChatMenu_Reply	function	framexml
+ChatMenu_Say	function	framexml
+ChatMenu_SetChatType	function	framexml
+ChatMenu_VoiceMacro	function	framexml
+ChatMenu_Whisper	function	framexml
+ChatMenu_Yell	function	framexml
+ChatTabTemplate	lod	framexml
+ChatTypeGroup	table	framexml
+ChatTypeInfo	table	framexml
+CheckBinderDist	function	engine
+CheckInbox	function	engine
+CheckInteractDistance	function	engine
+CheckPetUntrainerDist	function	engine
+CheckReadyCheckTime	function	engine
+CheckSpiritHealerDist	function	engine
+CheckTalentMasterDist	function	engine
+CinematicFrame	table	framexml
+CinematicFrame_OnEvent	function	framexml
+CinematicFrame_OnLoad	function	framexml
+ClassTrainerCancelButton	lod	framexml
+ClassTrainerCollapseAllButton	lod	framexml
+ClassTrainerCollapseAllButton_OnClick	lod	framexml
+ClassTrainerCostLabel	lod	framexml
+ClassTrainerDetailMoneyFrame	lod	framexml
+ClassTrainerDetailScrollChildFrame	lod	framexml
+ClassTrainerDetailScrollFrame	lod	framexml
+ClassTrainerDetailScrollFrameTemplate	lod	framexml
+ClassTrainerExpandButtonFrame	lod	framexml
+ClassTrainerExpandTabLeft	lod	framexml
+ClassTrainerExpandTabMiddle	lod	framexml
+ClassTrainerFrame	lod	framexml
+ClassTrainerFrameBottomLeft	lod	framexml
+ClassTrainerFrameBottomRight	lod	framexml
+ClassTrainerFrameCloseButton	lod	framexml
+ClassTrainerFrameFilterDropDown	lod	framexml
+ClassTrainerFrameFilterDropDown_Initialize	lod	framexml
+ClassTrainerFrameFilterDropDown_OnClick	lod	framexml
+ClassTrainerFrameFilterDropDown_OnLoad	lod	framexml
+ClassTrainerFramePortrait	lod	framexml
+ClassTrainerFrame_Hide	lod	framexml
+ClassTrainerFrame_LoadUI	function	framexml
+ClassTrainerFrame_OnEvent	lod	framexml
+ClassTrainerFrame_OnLoad	lod	framexml
+ClassTrainerFrame_Show	lod	framexml
+ClassTrainerFrame_Update	lod	framexml
+ClassTrainerGreetingText	lod	framexml
+ClassTrainerHorizontalBarLeft	lod	framexml
+ClassTrainerListScrollFrame	lod	framexml
+ClassTrainerListScrollFrameTemplate	lod	framexml
+ClassTrainerMoneyFrame	lod	framexml
+ClassTrainerNameText	lod	framexml
+ClassTrainerSkill1	lod	framexml
+ClassTrainerSkill10	lod	framexml
+ClassTrainerSkill11	lod	framexml
+ClassTrainerSkill2	lod	framexml
+ClassTrainerSkill3	lod	framexml
+ClassTrainerSkill4	lod	framexml
+ClassTrainerSkill5	lod	framexml
+ClassTrainerSkill6	lod	framexml
+ClassTrainerSkill7	lod	framexml
+ClassTrainerSkill8	lod	framexml
+ClassTrainerSkill9	lod	framexml
+ClassTrainerSkillButtonTemplate	lod	framexml
+ClassTrainerSkillButton_OnClick	lod	framexml
+ClassTrainerSkillDescription	lod	framexml
+ClassTrainerSkillHighlight	lod	framexml
+ClassTrainerSkillHighlightFrame	lod	framexml
+ClassTrainerSkillIcon	lod	framexml
+ClassTrainerSkillName	lod	framexml
+ClassTrainerSkillRequirements	lod	framexml
+ClassTrainerSubSkillName	lod	framexml
+ClassTrainerTrainButton	lod	framexml
+ClassTrainerTrainButton_OnClick	lod	framexml
+ClassTrainer_HideSkillDetails	lod	framexml
+ClassTrainer_SelectFirstLearnableSkill	lod	framexml
+ClassTrainer_SetSelection	lod	framexml
+ClassTrainer_SetSubTextColor	lod	framexml
+ClassTrainer_SetToClassTrainer	lod	framexml
+ClassTrainer_SetToTradeSkillTrainer	lod	framexml
+ClassTrainer_ShowSkillDetails	lod	framexml
+ClearCursor	function	engine
+ClearInspectPlayer	function	engine
+ClearSendMail	function	engine
+ClearTarget	function	engine
+ClearTutorials	function	engine
+ClickAuctionSellItemButton	function	engine
+ClickSendMailItemButton	function	engine
+ClickStablePet	function	engine
+ClickTargetTradeButton	function	engine
+ClickTradeButton	function	engine
+CloseAllBags	function	framexml
+CloseAllWindows	function	framexml
+CloseAllWindows_WithExceptions	function	framexml
+CloseAuctionHouse	function	engine
+CloseAuctionStaticPopups	lod	framexml
+CloseBackpack	function	framexml
+CloseBag	function	framexml
+CloseBankBagFrames	function	framexml
+CloseBankFrame	function	engine
+CloseBattlefield	function	engine
+CloseCraft	function	engine
+CloseDropDownMenus	function	framexml
+CloseGossip	function	engine
+CloseGuildRegistrar	function	engine
+CloseGuildRoster	function	engine
+CloseItemText	function	engine
+CloseLoot	function	engine
+CloseLottery	function	engine
+CloseMail	function	engine
+CloseMenus	function	framexml
+CloseMerchant	function	engine
+ClosePetStables	function	engine
+ClosePetition	function	engine
+CloseQuest	function	engine
+CloseTabardCreation	function	engine
+CloseTaxiMap	function	engine
+CloseTrade	function	engine
+CloseTradeSkill	function	engine
+CloseTrainer	function	engine
+CloseWindows	function	framexml
+CoinPickupCancelButton	table	framexml
+CoinPickupCancelButtonText	table	framexml
+CoinPickupCopperIcon	table	framexml
+CoinPickupFrame	table	framexml
+CoinPickupFrameCancel_Click	function	framexml
+CoinPickupFrameLeft_Click	function	framexml
+CoinPickupFrameOkay_Click	function	framexml
+CoinPickupFrameRight_Click	function	framexml
+CoinPickupFrame_OnChar	function	framexml
+CoinPickupFrame_OnHide	function	framexml
+CoinPickupFrame_OnKeyDown	function	framexml
+CoinPickupGoldIcon	table	framexml
+CoinPickupLeftButton	table	framexml
+CoinPickupOkayButton	table	framexml
+CoinPickupOkayButtonText	table	framexml
+CoinPickupRightButton	table	framexml
+CoinPickupSilverIcon	table	framexml
+CoinPickupText	table	framexml
+CollapseCraftSkillLine	function	engine
+CollapseFactionHeader	function	engine
+CollapseQuestHeader	function	engine
+CollapseSkillHeader	function	engine
+CollapseTradeSkillSubClass	function	engine
+CollapseTrainerSkillLine	function	engine
+ColorPickerCancelButton	table	framexml
+ColorPickerCancelButtonText	table	framexml
+ColorPickerFrame	table	framexml
+ColorPickerFrameHeader	table	framexml
+ColorPickerOkayButton	table	framexml
+ColorPickerOkayButtonText	table	framexml
+ColorPickerWheel	table	framexml
+ColorSwatch	table	framexml
+CombatFeedbackText	table	framexml
+CombatFeedback_Initialize	function	framexml
+CombatFeedback_OnCombatEvent	function	framexml
+CombatFeedback_OnUpdate	function	framexml
+CombatLogFont	table	framexml
+CombatLogMenuChatTypeGroups	table	framexml
+CombatText	lod	framexml
+CombatText1	lod	framexml
+CombatText10	lod	framexml
+CombatText11	lod	framexml
+CombatText12	lod	framexml
+CombatText13	lod	framexml
+CombatText14	lod	framexml
+CombatText15	lod	framexml
+CombatText16	lod	framexml
+CombatText17	lod	framexml
+CombatText18	lod	framexml
+CombatText19	lod	framexml
+CombatText2	lod	framexml
+CombatText20	lod	framexml
+CombatText3	lod	framexml
+CombatText4	lod	framexml
+CombatText5	lod	framexml
+CombatText6	lod	framexml
+CombatText7	lod	framexml
+CombatText8	lod	framexml
+CombatText9	lod	framexml
+CombatTextFont	table	framexml
+CombatTextTemplate	lod	framexml
+CombatText_AddMessage	lod	framexml
+CombatText_ClearAnimationList	lod	framexml
+CombatText_FountainScroll	lod	framexml
+CombatText_GetAvailableString	lod	framexml
+CombatText_GetOldestString	lod	framexml
+CombatText_OnEvent	lod	framexml
+CombatText_OnLoad	lod	framexml
+CombatText_OnUpdate	lod	framexml
+CombatText_RemoveMessage	lod	framexml
+CombatText_StandardScroll	lod	framexml
+CombatText_UpdateDisplayedMessages	lod	framexml
+ComboFrame	table	framexml
+ComboPoint1	table	framexml
+ComboPoint1Highlight	table	framexml
+ComboPoint1Shine	table	framexml
+ComboPoint2	table	framexml
+ComboPoint2Highlight	table	framexml
+ComboPoint2Shine	table	framexml
+ComboPoint3	table	framexml
+ComboPoint3Highlight	table	framexml
+ComboPoint3Shine	table	framexml
+ComboPoint4	table	framexml
+ComboPoint4Highlight	table	framexml
+ComboPoint4Shine	table	framexml
+ComboPoint5	table	framexml
+ComboPoint5Highlight	table	framexml
+ComboPoint5Shine	table	framexml
+ComboPointShineFadeIn	function	framexml
+ComboPointShineFadeOut	function	framexml
+ComboPointTemplate	lod	framexml
+ComboPointsFrame_OnEvent	function	framexml
+CompleteQuest	function	engine
+ConfirmAcceptQuest	function	engine
+ConfirmBindOnUse	function	engine
+ConfirmBinder	function	engine
+ConfirmLootRoll	function	engine
+ConfirmPetUnlearn	function	engine
+ConfirmReadyCheck	function	engine
+ConfirmSummon	function	engine
+ConfirmTalentWipe	function	engine
+ConsoleExec	function	engine
+ContainerFrame1	table	framexml
+ContainerFrame10	table	framexml
+ContainerFrame10BackgroundBottom	table	framexml
+ContainerFrame10BackgroundMiddle1	table	framexml
+ContainerFrame10BackgroundMiddle2	table	framexml
+ContainerFrame10BackgroundTop	table	framexml
+ContainerFrame10CloseButton	table	framexml
+ContainerFrame10Item1	table	framexml
+ContainerFrame10Item10	table	framexml
+ContainerFrame10Item10Cooldown	table	framexml
+ContainerFrame10Item10Count	table	framexml
+ContainerFrame10Item10IconTexture	table	framexml
+ContainerFrame10Item10NormalTexture	table	framexml
+ContainerFrame10Item10Stock	table	framexml
+ContainerFrame10Item11	table	framexml
+ContainerFrame10Item11Cooldown	table	framexml
+ContainerFrame10Item11Count	table	framexml
+ContainerFrame10Item11IconTexture	table	framexml
+ContainerFrame10Item11NormalTexture	table	framexml
+ContainerFrame10Item11Stock	table	framexml
+ContainerFrame10Item12	table	framexml
+ContainerFrame10Item12Cooldown	table	framexml
+ContainerFrame10Item12Count	table	framexml
+ContainerFrame10Item12IconTexture	table	framexml
+ContainerFrame10Item12NormalTexture	table	framexml
+ContainerFrame10Item12Stock	table	framexml
+ContainerFrame10Item13	table	framexml
+ContainerFrame10Item13Cooldown	table	framexml
+ContainerFrame10Item13Count	table	framexml
+ContainerFrame10Item13IconTexture	table	framexml
+ContainerFrame10Item13NormalTexture	table	framexml
+ContainerFrame10Item13Stock	table	framexml
+ContainerFrame10Item14	table	framexml
+ContainerFrame10Item14Cooldown	table	framexml
+ContainerFrame10Item14Count	table	framexml
+ContainerFrame10Item14IconTexture	table	framexml
+ContainerFrame10Item14NormalTexture	table	framexml
+ContainerFrame10Item14Stock	table	framexml
+ContainerFrame10Item15	table	framexml
+ContainerFrame10Item15Cooldown	table	framexml
+ContainerFrame10Item15Count	table	framexml
+ContainerFrame10Item15IconTexture	table	framexml
+ContainerFrame10Item15NormalTexture	table	framexml
+ContainerFrame10Item15Stock	table	framexml
+ContainerFrame10Item16	table	framexml
+ContainerFrame10Item16Cooldown	table	framexml
+ContainerFrame10Item16Count	table	framexml
+ContainerFrame10Item16IconTexture	table	framexml
+ContainerFrame10Item16NormalTexture	table	framexml
+ContainerFrame10Item16Stock	table	framexml
+ContainerFrame10Item17	table	framexml
+ContainerFrame10Item17Cooldown	table	framexml
+ContainerFrame10Item17Count	table	framexml
+ContainerFrame10Item17IconTexture	table	framexml
+ContainerFrame10Item17NormalTexture	table	framexml
+ContainerFrame10Item17Stock	table	framexml
+ContainerFrame10Item18	table	framexml
+ContainerFrame10Item18Cooldown	table	framexml
+ContainerFrame10Item18Count	table	framexml
+ContainerFrame10Item18IconTexture	table	framexml
+ContainerFrame10Item18NormalTexture	table	framexml
+ContainerFrame10Item18Stock	table	framexml
+ContainerFrame10Item19	table	framexml
+ContainerFrame10Item19Cooldown	table	framexml
+ContainerFrame10Item19Count	table	framexml
+ContainerFrame10Item19IconTexture	table	framexml
+ContainerFrame10Item19NormalTexture	table	framexml
+ContainerFrame10Item19Stock	table	framexml
+ContainerFrame10Item1Cooldown	table	framexml
+ContainerFrame10Item1Count	table	framexml
+ContainerFrame10Item1IconTexture	table	framexml
+ContainerFrame10Item1NormalTexture	table	framexml
+ContainerFrame10Item1Stock	table	framexml
+ContainerFrame10Item2	table	framexml
+ContainerFrame10Item20	table	framexml
+ContainerFrame10Item20Cooldown	table	framexml
+ContainerFrame10Item20Count	table	framexml
+ContainerFrame10Item20IconTexture	table	framexml
+ContainerFrame10Item20NormalTexture	table	framexml
+ContainerFrame10Item20Stock	table	framexml
+ContainerFrame10Item21	table	framexml
+ContainerFrame10Item21Cooldown	table	framexml
+ContainerFrame10Item21Count	table	framexml
+ContainerFrame10Item21IconTexture	table	framexml
+ContainerFrame10Item21NormalTexture	table	framexml
+ContainerFrame10Item21Stock	table	framexml
+ContainerFrame10Item22	table	framexml
+ContainerFrame10Item22Cooldown	table	framexml
+ContainerFrame10Item22Count	table	framexml
+ContainerFrame10Item22IconTexture	table	framexml
+ContainerFrame10Item22NormalTexture	table	framexml
+ContainerFrame10Item22Stock	table	framexml
+ContainerFrame10Item23	table	framexml
+ContainerFrame10Item23Cooldown	table	framexml
+ContainerFrame10Item23Count	table	framexml
+ContainerFrame10Item23IconTexture	table	framexml
+ContainerFrame10Item23NormalTexture	table	framexml
+ContainerFrame10Item23Stock	table	framexml
+ContainerFrame10Item24	table	framexml
+ContainerFrame10Item24Cooldown	table	framexml
+ContainerFrame10Item24Count	table	framexml
+ContainerFrame10Item24IconTexture	table	framexml
+ContainerFrame10Item24NormalTexture	table	framexml
+ContainerFrame10Item24Stock	table	framexml
+ContainerFrame10Item25	table	framexml
+ContainerFrame10Item25Cooldown	table	framexml
+ContainerFrame10Item25Count	table	framexml
+ContainerFrame10Item25IconTexture	table	framexml
+ContainerFrame10Item25NormalTexture	table	framexml
+ContainerFrame10Item25Stock	table	framexml
+ContainerFrame10Item26	table	framexml
+ContainerFrame10Item26Cooldown	table	framexml
+ContainerFrame10Item26Count	table	framexml
+ContainerFrame10Item26IconTexture	table	framexml
+ContainerFrame10Item26NormalTexture	table	framexml
+ContainerFrame10Item26Stock	table	framexml
+ContainerFrame10Item27	table	framexml
+ContainerFrame10Item27Cooldown	table	framexml
+ContainerFrame10Item27Count	table	framexml
+ContainerFrame10Item27IconTexture	table	framexml
+ContainerFrame10Item27NormalTexture	table	framexml
+ContainerFrame10Item27Stock	table	framexml
+ContainerFrame10Item28	table	framexml
+ContainerFrame10Item28Cooldown	table	framexml
+ContainerFrame10Item28Count	table	framexml
+ContainerFrame10Item28IconTexture	table	framexml
+ContainerFrame10Item28NormalTexture	table	framexml
+ContainerFrame10Item28Stock	table	framexml
+ContainerFrame10Item29	table	framexml
+ContainerFrame10Item29Cooldown	table	framexml
+ContainerFrame10Item29Count	table	framexml
+ContainerFrame10Item29IconTexture	table	framexml
+ContainerFrame10Item29NormalTexture	table	framexml
+ContainerFrame10Item29Stock	table	framexml
+ContainerFrame10Item2Cooldown	table	framexml
+ContainerFrame10Item2Count	table	framexml
+ContainerFrame10Item2IconTexture	table	framexml
+ContainerFrame10Item2NormalTexture	table	framexml
+ContainerFrame10Item2Stock	table	framexml
+ContainerFrame10Item3	table	framexml
+ContainerFrame10Item30	table	framexml
+ContainerFrame10Item30Cooldown	table	framexml
+ContainerFrame10Item30Count	table	framexml
+ContainerFrame10Item30IconTexture	table	framexml
+ContainerFrame10Item30NormalTexture	table	framexml
+ContainerFrame10Item30Stock	table	framexml
+ContainerFrame10Item31	table	framexml
+ContainerFrame10Item31Cooldown	table	framexml
+ContainerFrame10Item31Count	table	framexml
+ContainerFrame10Item31IconTexture	table	framexml
+ContainerFrame10Item31NormalTexture	table	framexml
+ContainerFrame10Item31Stock	table	framexml
+ContainerFrame10Item32	table	framexml
+ContainerFrame10Item32Cooldown	table	framexml
+ContainerFrame10Item32Count	table	framexml
+ContainerFrame10Item32IconTexture	table	framexml
+ContainerFrame10Item32NormalTexture	table	framexml
+ContainerFrame10Item32Stock	table	framexml
+ContainerFrame10Item33	table	framexml
+ContainerFrame10Item33Cooldown	table	framexml
+ContainerFrame10Item33Count	table	framexml
+ContainerFrame10Item33IconTexture	table	framexml
+ContainerFrame10Item33NormalTexture	table	framexml
+ContainerFrame10Item33Stock	table	framexml
+ContainerFrame10Item34	table	framexml
+ContainerFrame10Item34Cooldown	table	framexml
+ContainerFrame10Item34Count	table	framexml
+ContainerFrame10Item34IconTexture	table	framexml
+ContainerFrame10Item34NormalTexture	table	framexml
+ContainerFrame10Item34Stock	table	framexml
+ContainerFrame10Item35	table	framexml
+ContainerFrame10Item35Cooldown	table	framexml
+ContainerFrame10Item35Count	table	framexml
+ContainerFrame10Item35IconTexture	table	framexml
+ContainerFrame10Item35NormalTexture	table	framexml
+ContainerFrame10Item35Stock	table	framexml
+ContainerFrame10Item36	table	framexml
+ContainerFrame10Item36Cooldown	table	framexml
+ContainerFrame10Item36Count	table	framexml
+ContainerFrame10Item36IconTexture	table	framexml
+ContainerFrame10Item36NormalTexture	table	framexml
+ContainerFrame10Item36Stock	table	framexml
+ContainerFrame10Item3Cooldown	table	framexml
+ContainerFrame10Item3Count	table	framexml
+ContainerFrame10Item3IconTexture	table	framexml
+ContainerFrame10Item3NormalTexture	table	framexml
+ContainerFrame10Item3Stock	table	framexml
+ContainerFrame10Item4	table	framexml
+ContainerFrame10Item4Cooldown	table	framexml
+ContainerFrame10Item4Count	table	framexml
+ContainerFrame10Item4IconTexture	table	framexml
+ContainerFrame10Item4NormalTexture	table	framexml
+ContainerFrame10Item4Stock	table	framexml
+ContainerFrame10Item5	table	framexml
+ContainerFrame10Item5Cooldown	table	framexml
+ContainerFrame10Item5Count	table	framexml
+ContainerFrame10Item5IconTexture	table	framexml
+ContainerFrame10Item5NormalTexture	table	framexml
+ContainerFrame10Item5Stock	table	framexml
+ContainerFrame10Item6	table	framexml
+ContainerFrame10Item6Cooldown	table	framexml
+ContainerFrame10Item6Count	table	framexml
+ContainerFrame10Item6IconTexture	table	framexml
+ContainerFrame10Item6NormalTexture	table	framexml
+ContainerFrame10Item6Stock	table	framexml
+ContainerFrame10Item7	table	framexml
+ContainerFrame10Item7Cooldown	table	framexml
+ContainerFrame10Item7Count	table	framexml
+ContainerFrame10Item7IconTexture	table	framexml
+ContainerFrame10Item7NormalTexture	table	framexml
+ContainerFrame10Item7Stock	table	framexml
+ContainerFrame10Item8	table	framexml
+ContainerFrame10Item8Cooldown	table	framexml
+ContainerFrame10Item8Count	table	framexml
+ContainerFrame10Item8IconTexture	table	framexml
+ContainerFrame10Item8NormalTexture	table	framexml
+ContainerFrame10Item8Stock	table	framexml
+ContainerFrame10Item9	table	framexml
+ContainerFrame10Item9Cooldown	table	framexml
+ContainerFrame10Item9Count	table	framexml
+ContainerFrame10Item9IconTexture	table	framexml
+ContainerFrame10Item9NormalTexture	table	framexml
+ContainerFrame10Item9Stock	table	framexml
+ContainerFrame10MoneyFrame	table	framexml
+ContainerFrame10MoneyFrameCopperButton	table	framexml
+ContainerFrame10MoneyFrameCopperButtonText	table	framexml
+ContainerFrame10MoneyFrameGoldButton	table	framexml
+ContainerFrame10MoneyFrameGoldButtonText	table	framexml
+ContainerFrame10MoneyFrameSilverButton	table	framexml
+ContainerFrame10MoneyFrameSilverButtonText	table	framexml
+ContainerFrame10Name	table	framexml
+ContainerFrame10Portrait	table	framexml
+ContainerFrame10PortraitButton	table	framexml
+ContainerFrame11	table	framexml
+ContainerFrame11BackgroundBottom	table	framexml
+ContainerFrame11BackgroundMiddle1	table	framexml
+ContainerFrame11BackgroundMiddle2	table	framexml
+ContainerFrame11BackgroundTop	table	framexml
+ContainerFrame11CloseButton	table	framexml
+ContainerFrame11Item1	table	framexml
+ContainerFrame11Item10	table	framexml
+ContainerFrame11Item10Cooldown	table	framexml
+ContainerFrame11Item10Count	table	framexml
+ContainerFrame11Item10IconTexture	table	framexml
+ContainerFrame11Item10NormalTexture	table	framexml
+ContainerFrame11Item10Stock	table	framexml
+ContainerFrame11Item11	table	framexml
+ContainerFrame11Item11Cooldown	table	framexml
+ContainerFrame11Item11Count	table	framexml
+ContainerFrame11Item11IconTexture	table	framexml
+ContainerFrame11Item11NormalTexture	table	framexml
+ContainerFrame11Item11Stock	table	framexml
+ContainerFrame11Item12	table	framexml
+ContainerFrame11Item12Cooldown	table	framexml
+ContainerFrame11Item12Count	table	framexml
+ContainerFrame11Item12IconTexture	table	framexml
+ContainerFrame11Item12NormalTexture	table	framexml
+ContainerFrame11Item12Stock	table	framexml
+ContainerFrame11Item13	table	framexml
+ContainerFrame11Item13Cooldown	table	framexml
+ContainerFrame11Item13Count	table	framexml
+ContainerFrame11Item13IconTexture	table	framexml
+ContainerFrame11Item13NormalTexture	table	framexml
+ContainerFrame11Item13Stock	table	framexml
+ContainerFrame11Item14	table	framexml
+ContainerFrame11Item14Cooldown	table	framexml
+ContainerFrame11Item14Count	table	framexml
+ContainerFrame11Item14IconTexture	table	framexml
+ContainerFrame11Item14NormalTexture	table	framexml
+ContainerFrame11Item14Stock	table	framexml
+ContainerFrame11Item15	table	framexml
+ContainerFrame11Item15Cooldown	table	framexml
+ContainerFrame11Item15Count	table	framexml
+ContainerFrame11Item15IconTexture	table	framexml
+ContainerFrame11Item15NormalTexture	table	framexml
+ContainerFrame11Item15Stock	table	framexml
+ContainerFrame11Item16	table	framexml
+ContainerFrame11Item16Cooldown	table	framexml
+ContainerFrame11Item16Count	table	framexml
+ContainerFrame11Item16IconTexture	table	framexml
+ContainerFrame11Item16NormalTexture	table	framexml
+ContainerFrame11Item16Stock	table	framexml
+ContainerFrame11Item17	table	framexml
+ContainerFrame11Item17Cooldown	table	framexml
+ContainerFrame11Item17Count	table	framexml
+ContainerFrame11Item17IconTexture	table	framexml
+ContainerFrame11Item17NormalTexture	table	framexml
+ContainerFrame11Item17Stock	table	framexml
+ContainerFrame11Item18	table	framexml
+ContainerFrame11Item18Cooldown	table	framexml
+ContainerFrame11Item18Count	table	framexml
+ContainerFrame11Item18IconTexture	table	framexml
+ContainerFrame11Item18NormalTexture	table	framexml
+ContainerFrame11Item18Stock	table	framexml
+ContainerFrame11Item19	table	framexml
+ContainerFrame11Item19Cooldown	table	framexml
+ContainerFrame11Item19Count	table	framexml
+ContainerFrame11Item19IconTexture	table	framexml
+ContainerFrame11Item19NormalTexture	table	framexml
+ContainerFrame11Item19Stock	table	framexml
+ContainerFrame11Item1Cooldown	table	framexml
+ContainerFrame11Item1Count	table	framexml
+ContainerFrame11Item1IconTexture	table	framexml
+ContainerFrame11Item1NormalTexture	table	framexml
+ContainerFrame11Item1Stock	table	framexml
+ContainerFrame11Item2	table	framexml
+ContainerFrame11Item20	table	framexml
+ContainerFrame11Item20Cooldown	table	framexml
+ContainerFrame11Item20Count	table	framexml
+ContainerFrame11Item20IconTexture	table	framexml
+ContainerFrame11Item20NormalTexture	table	framexml
+ContainerFrame11Item20Stock	table	framexml
+ContainerFrame11Item21	table	framexml
+ContainerFrame11Item21Cooldown	table	framexml
+ContainerFrame11Item21Count	table	framexml
+ContainerFrame11Item21IconTexture	table	framexml
+ContainerFrame11Item21NormalTexture	table	framexml
+ContainerFrame11Item21Stock	table	framexml
+ContainerFrame11Item22	table	framexml
+ContainerFrame11Item22Cooldown	table	framexml
+ContainerFrame11Item22Count	table	framexml
+ContainerFrame11Item22IconTexture	table	framexml
+ContainerFrame11Item22NormalTexture	table	framexml
+ContainerFrame11Item22Stock	table	framexml
+ContainerFrame11Item23	table	framexml
+ContainerFrame11Item23Cooldown	table	framexml
+ContainerFrame11Item23Count	table	framexml
+ContainerFrame11Item23IconTexture	table	framexml
+ContainerFrame11Item23NormalTexture	table	framexml
+ContainerFrame11Item23Stock	table	framexml
+ContainerFrame11Item24	table	framexml
+ContainerFrame11Item24Cooldown	table	framexml
+ContainerFrame11Item24Count	table	framexml
+ContainerFrame11Item24IconTexture	table	framexml
+ContainerFrame11Item24NormalTexture	table	framexml
+ContainerFrame11Item24Stock	table	framexml
+ContainerFrame11Item25	table	framexml
+ContainerFrame11Item25Cooldown	table	framexml
+ContainerFrame11Item25Count	table	framexml
+ContainerFrame11Item25IconTexture	table	framexml
+ContainerFrame11Item25NormalTexture	table	framexml
+ContainerFrame11Item25Stock	table	framexml
+ContainerFrame11Item26	table	framexml
+ContainerFrame11Item26Cooldown	table	framexml
+ContainerFrame11Item26Count	table	framexml
+ContainerFrame11Item26IconTexture	table	framexml
+ContainerFrame11Item26NormalTexture	table	framexml
+ContainerFrame11Item26Stock	table	framexml
+ContainerFrame11Item27	table	framexml
+ContainerFrame11Item27Cooldown	table	framexml
+ContainerFrame11Item27Count	table	framexml
+ContainerFrame11Item27IconTexture	table	framexml
+ContainerFrame11Item27NormalTexture	table	framexml
+ContainerFrame11Item27Stock	table	framexml
+ContainerFrame11Item28	table	framexml
+ContainerFrame11Item28Cooldown	table	framexml
+ContainerFrame11Item28Count	table	framexml
+ContainerFrame11Item28IconTexture	table	framexml
+ContainerFrame11Item28NormalTexture	table	framexml
+ContainerFrame11Item28Stock	table	framexml
+ContainerFrame11Item29	table	framexml
+ContainerFrame11Item29Cooldown	table	framexml
+ContainerFrame11Item29Count	table	framexml
+ContainerFrame11Item29IconTexture	table	framexml
+ContainerFrame11Item29NormalTexture	table	framexml
+ContainerFrame11Item29Stock	table	framexml
+ContainerFrame11Item2Cooldown	table	framexml
+ContainerFrame11Item2Count	table	framexml
+ContainerFrame11Item2IconTexture	table	framexml
+ContainerFrame11Item2NormalTexture	table	framexml
+ContainerFrame11Item2Stock	table	framexml
+ContainerFrame11Item3	table	framexml
+ContainerFrame11Item30	table	framexml
+ContainerFrame11Item30Cooldown	table	framexml
+ContainerFrame11Item30Count	table	framexml
+ContainerFrame11Item30IconTexture	table	framexml
+ContainerFrame11Item30NormalTexture	table	framexml
+ContainerFrame11Item30Stock	table	framexml
+ContainerFrame11Item31	table	framexml
+ContainerFrame11Item31Cooldown	table	framexml
+ContainerFrame11Item31Count	table	framexml
+ContainerFrame11Item31IconTexture	table	framexml
+ContainerFrame11Item31NormalTexture	table	framexml
+ContainerFrame11Item31Stock	table	framexml
+ContainerFrame11Item32	table	framexml
+ContainerFrame11Item32Cooldown	table	framexml
+ContainerFrame11Item32Count	table	framexml
+ContainerFrame11Item32IconTexture	table	framexml
+ContainerFrame11Item32NormalTexture	table	framexml
+ContainerFrame11Item32Stock	table	framexml
+ContainerFrame11Item33	table	framexml
+ContainerFrame11Item33Cooldown	table	framexml
+ContainerFrame11Item33Count	table	framexml
+ContainerFrame11Item33IconTexture	table	framexml
+ContainerFrame11Item33NormalTexture	table	framexml
+ContainerFrame11Item33Stock	table	framexml
+ContainerFrame11Item34	table	framexml
+ContainerFrame11Item34Cooldown	table	framexml
+ContainerFrame11Item34Count	table	framexml
+ContainerFrame11Item34IconTexture	table	framexml
+ContainerFrame11Item34NormalTexture	table	framexml
+ContainerFrame11Item34Stock	table	framexml
+ContainerFrame11Item35	table	framexml
+ContainerFrame11Item35Cooldown	table	framexml
+ContainerFrame11Item35Count	table	framexml
+ContainerFrame11Item35IconTexture	table	framexml
+ContainerFrame11Item35NormalTexture	table	framexml
+ContainerFrame11Item35Stock	table	framexml
+ContainerFrame11Item36	table	framexml
+ContainerFrame11Item36Cooldown	table	framexml
+ContainerFrame11Item36Count	table	framexml
+ContainerFrame11Item36IconTexture	table	framexml
+ContainerFrame11Item36NormalTexture	table	framexml
+ContainerFrame11Item36Stock	table	framexml
+ContainerFrame11Item3Cooldown	table	framexml
+ContainerFrame11Item3Count	table	framexml
+ContainerFrame11Item3IconTexture	table	framexml
+ContainerFrame11Item3NormalTexture	table	framexml
+ContainerFrame11Item3Stock	table	framexml
+ContainerFrame11Item4	table	framexml
+ContainerFrame11Item4Cooldown	table	framexml
+ContainerFrame11Item4Count	table	framexml
+ContainerFrame11Item4IconTexture	table	framexml
+ContainerFrame11Item4NormalTexture	table	framexml
+ContainerFrame11Item4Stock	table	framexml
+ContainerFrame11Item5	table	framexml
+ContainerFrame11Item5Cooldown	table	framexml
+ContainerFrame11Item5Count	table	framexml
+ContainerFrame11Item5IconTexture	table	framexml
+ContainerFrame11Item5NormalTexture	table	framexml
+ContainerFrame11Item5Stock	table	framexml
+ContainerFrame11Item6	table	framexml
+ContainerFrame11Item6Cooldown	table	framexml
+ContainerFrame11Item6Count	table	framexml
+ContainerFrame11Item6IconTexture	table	framexml
+ContainerFrame11Item6NormalTexture	table	framexml
+ContainerFrame11Item6Stock	table	framexml
+ContainerFrame11Item7	table	framexml
+ContainerFrame11Item7Cooldown	table	framexml
+ContainerFrame11Item7Count	table	framexml
+ContainerFrame11Item7IconTexture	table	framexml
+ContainerFrame11Item7NormalTexture	table	framexml
+ContainerFrame11Item7Stock	table	framexml
+ContainerFrame11Item8	table	framexml
+ContainerFrame11Item8Cooldown	table	framexml
+ContainerFrame11Item8Count	table	framexml
+ContainerFrame11Item8IconTexture	table	framexml
+ContainerFrame11Item8NormalTexture	table	framexml
+ContainerFrame11Item8Stock	table	framexml
+ContainerFrame11Item9	table	framexml
+ContainerFrame11Item9Cooldown	table	framexml
+ContainerFrame11Item9Count	table	framexml
+ContainerFrame11Item9IconTexture	table	framexml
+ContainerFrame11Item9NormalTexture	table	framexml
+ContainerFrame11Item9Stock	table	framexml
+ContainerFrame11MoneyFrame	table	framexml
+ContainerFrame11MoneyFrameCopperButton	table	framexml
+ContainerFrame11MoneyFrameCopperButtonText	table	framexml
+ContainerFrame11MoneyFrameGoldButton	table	framexml
+ContainerFrame11MoneyFrameGoldButtonText	table	framexml
+ContainerFrame11MoneyFrameSilverButton	table	framexml
+ContainerFrame11MoneyFrameSilverButtonText	table	framexml
+ContainerFrame11Name	table	framexml
+ContainerFrame11Portrait	table	framexml
+ContainerFrame11PortraitButton	table	framexml
+ContainerFrame12	table	framexml
+ContainerFrame12BackgroundBottom	table	framexml
+ContainerFrame12BackgroundMiddle1	table	framexml
+ContainerFrame12BackgroundMiddle2	table	framexml
+ContainerFrame12BackgroundTop	table	framexml
+ContainerFrame12CloseButton	table	framexml
+ContainerFrame12Item1	table	framexml
+ContainerFrame12Item10	table	framexml
+ContainerFrame12Item10Cooldown	table	framexml
+ContainerFrame12Item10Count	table	framexml
+ContainerFrame12Item10IconTexture	table	framexml
+ContainerFrame12Item10NormalTexture	table	framexml
+ContainerFrame12Item10Stock	table	framexml
+ContainerFrame12Item11	table	framexml
+ContainerFrame12Item11Cooldown	table	framexml
+ContainerFrame12Item11Count	table	framexml
+ContainerFrame12Item11IconTexture	table	framexml
+ContainerFrame12Item11NormalTexture	table	framexml
+ContainerFrame12Item11Stock	table	framexml
+ContainerFrame12Item12	table	framexml
+ContainerFrame12Item12Cooldown	table	framexml
+ContainerFrame12Item12Count	table	framexml
+ContainerFrame12Item12IconTexture	table	framexml
+ContainerFrame12Item12NormalTexture	table	framexml
+ContainerFrame12Item12Stock	table	framexml
+ContainerFrame12Item13	table	framexml
+ContainerFrame12Item13Cooldown	table	framexml
+ContainerFrame12Item13Count	table	framexml
+ContainerFrame12Item13IconTexture	table	framexml
+ContainerFrame12Item13NormalTexture	table	framexml
+ContainerFrame12Item13Stock	table	framexml
+ContainerFrame12Item14	table	framexml
+ContainerFrame12Item14Cooldown	table	framexml
+ContainerFrame12Item14Count	table	framexml
+ContainerFrame12Item14IconTexture	table	framexml
+ContainerFrame12Item14NormalTexture	table	framexml
+ContainerFrame12Item14Stock	table	framexml
+ContainerFrame12Item15	table	framexml
+ContainerFrame12Item15Cooldown	table	framexml
+ContainerFrame12Item15Count	table	framexml
+ContainerFrame12Item15IconTexture	table	framexml
+ContainerFrame12Item15NormalTexture	table	framexml
+ContainerFrame12Item15Stock	table	framexml
+ContainerFrame12Item16	table	framexml
+ContainerFrame12Item16Cooldown	table	framexml
+ContainerFrame12Item16Count	table	framexml
+ContainerFrame12Item16IconTexture	table	framexml
+ContainerFrame12Item16NormalTexture	table	framexml
+ContainerFrame12Item16Stock	table	framexml
+ContainerFrame12Item17	table	framexml
+ContainerFrame12Item17Cooldown	table	framexml
+ContainerFrame12Item17Count	table	framexml
+ContainerFrame12Item17IconTexture	table	framexml
+ContainerFrame12Item17NormalTexture	table	framexml
+ContainerFrame12Item17Stock	table	framexml
+ContainerFrame12Item18	table	framexml
+ContainerFrame12Item18Cooldown	table	framexml
+ContainerFrame12Item18Count	table	framexml
+ContainerFrame12Item18IconTexture	table	framexml
+ContainerFrame12Item18NormalTexture	table	framexml
+ContainerFrame12Item18Stock	table	framexml
+ContainerFrame12Item19	table	framexml
+ContainerFrame12Item19Cooldown	table	framexml
+ContainerFrame12Item19Count	table	framexml
+ContainerFrame12Item19IconTexture	table	framexml
+ContainerFrame12Item19NormalTexture	table	framexml
+ContainerFrame12Item19Stock	table	framexml
+ContainerFrame12Item1Cooldown	table	framexml
+ContainerFrame12Item1Count	table	framexml
+ContainerFrame12Item1IconTexture	table	framexml
+ContainerFrame12Item1NormalTexture	table	framexml
+ContainerFrame12Item1Stock	table	framexml
+ContainerFrame12Item2	table	framexml
+ContainerFrame12Item20	table	framexml
+ContainerFrame12Item20Cooldown	table	framexml
+ContainerFrame12Item20Count	table	framexml
+ContainerFrame12Item20IconTexture	table	framexml
+ContainerFrame12Item20NormalTexture	table	framexml
+ContainerFrame12Item20Stock	table	framexml
+ContainerFrame12Item21	table	framexml
+ContainerFrame12Item21Cooldown	table	framexml
+ContainerFrame12Item21Count	table	framexml
+ContainerFrame12Item21IconTexture	table	framexml
+ContainerFrame12Item21NormalTexture	table	framexml
+ContainerFrame12Item21Stock	table	framexml
+ContainerFrame12Item22	table	framexml
+ContainerFrame12Item22Cooldown	table	framexml
+ContainerFrame12Item22Count	table	framexml
+ContainerFrame12Item22IconTexture	table	framexml
+ContainerFrame12Item22NormalTexture	table	framexml
+ContainerFrame12Item22Stock	table	framexml
+ContainerFrame12Item23	table	framexml
+ContainerFrame12Item23Cooldown	table	framexml
+ContainerFrame12Item23Count	table	framexml
+ContainerFrame12Item23IconTexture	table	framexml
+ContainerFrame12Item23NormalTexture	table	framexml
+ContainerFrame12Item23Stock	table	framexml
+ContainerFrame12Item24	table	framexml
+ContainerFrame12Item24Cooldown	table	framexml
+ContainerFrame12Item24Count	table	framexml
+ContainerFrame12Item24IconTexture	table	framexml
+ContainerFrame12Item24NormalTexture	table	framexml
+ContainerFrame12Item24Stock	table	framexml
+ContainerFrame12Item25	table	framexml
+ContainerFrame12Item25Cooldown	table	framexml
+ContainerFrame12Item25Count	table	framexml
+ContainerFrame12Item25IconTexture	table	framexml
+ContainerFrame12Item25NormalTexture	table	framexml
+ContainerFrame12Item25Stock	table	framexml
+ContainerFrame12Item26	table	framexml
+ContainerFrame12Item26Cooldown	table	framexml
+ContainerFrame12Item26Count	table	framexml
+ContainerFrame12Item26IconTexture	table	framexml
+ContainerFrame12Item26NormalTexture	table	framexml
+ContainerFrame12Item26Stock	table	framexml
+ContainerFrame12Item27	table	framexml
+ContainerFrame12Item27Cooldown	table	framexml
+ContainerFrame12Item27Count	table	framexml
+ContainerFrame12Item27IconTexture	table	framexml
+ContainerFrame12Item27NormalTexture	table	framexml
+ContainerFrame12Item27Stock	table	framexml
+ContainerFrame12Item28	table	framexml
+ContainerFrame12Item28Cooldown	table	framexml
+ContainerFrame12Item28Count	table	framexml
+ContainerFrame12Item28IconTexture	table	framexml
+ContainerFrame12Item28NormalTexture	table	framexml
+ContainerFrame12Item28Stock	table	framexml
+ContainerFrame12Item29	table	framexml
+ContainerFrame12Item29Cooldown	table	framexml
+ContainerFrame12Item29Count	table	framexml
+ContainerFrame12Item29IconTexture	table	framexml
+ContainerFrame12Item29NormalTexture	table	framexml
+ContainerFrame12Item29Stock	table	framexml
+ContainerFrame12Item2Cooldown	table	framexml
+ContainerFrame12Item2Count	table	framexml
+ContainerFrame12Item2IconTexture	table	framexml
+ContainerFrame12Item2NormalTexture	table	framexml
+ContainerFrame12Item2Stock	table	framexml
+ContainerFrame12Item3	table	framexml
+ContainerFrame12Item30	table	framexml
+ContainerFrame12Item30Cooldown	table	framexml
+ContainerFrame12Item30Count	table	framexml
+ContainerFrame12Item30IconTexture	table	framexml
+ContainerFrame12Item30NormalTexture	table	framexml
+ContainerFrame12Item30Stock	table	framexml
+ContainerFrame12Item31	table	framexml
+ContainerFrame12Item31Cooldown	table	framexml
+ContainerFrame12Item31Count	table	framexml
+ContainerFrame12Item31IconTexture	table	framexml
+ContainerFrame12Item31NormalTexture	table	framexml
+ContainerFrame12Item31Stock	table	framexml
+ContainerFrame12Item32	table	framexml
+ContainerFrame12Item32Cooldown	table	framexml
+ContainerFrame12Item32Count	table	framexml
+ContainerFrame12Item32IconTexture	table	framexml
+ContainerFrame12Item32NormalTexture	table	framexml
+ContainerFrame12Item32Stock	table	framexml
+ContainerFrame12Item33	table	framexml
+ContainerFrame12Item33Cooldown	table	framexml
+ContainerFrame12Item33Count	table	framexml
+ContainerFrame12Item33IconTexture	table	framexml
+ContainerFrame12Item33NormalTexture	table	framexml
+ContainerFrame12Item33Stock	table	framexml
+ContainerFrame12Item34	table	framexml
+ContainerFrame12Item34Cooldown	table	framexml
+ContainerFrame12Item34Count	table	framexml
+ContainerFrame12Item34IconTexture	table	framexml
+ContainerFrame12Item34NormalTexture	table	framexml
+ContainerFrame12Item34Stock	table	framexml
+ContainerFrame12Item35	table	framexml
+ContainerFrame12Item35Cooldown	table	framexml
+ContainerFrame12Item35Count	table	framexml
+ContainerFrame12Item35IconTexture	table	framexml
+ContainerFrame12Item35NormalTexture	table	framexml
+ContainerFrame12Item35Stock	table	framexml
+ContainerFrame12Item36	table	framexml
+ContainerFrame12Item36Cooldown	table	framexml
+ContainerFrame12Item36Count	table	framexml
+ContainerFrame12Item36IconTexture	table	framexml
+ContainerFrame12Item36NormalTexture	table	framexml
+ContainerFrame12Item36Stock	table	framexml
+ContainerFrame12Item3Cooldown	table	framexml
+ContainerFrame12Item3Count	table	framexml
+ContainerFrame12Item3IconTexture	table	framexml
+ContainerFrame12Item3NormalTexture	table	framexml
+ContainerFrame12Item3Stock	table	framexml
+ContainerFrame12Item4	table	framexml
+ContainerFrame12Item4Cooldown	table	framexml
+ContainerFrame12Item4Count	table	framexml
+ContainerFrame12Item4IconTexture	table	framexml
+ContainerFrame12Item4NormalTexture	table	framexml
+ContainerFrame12Item4Stock	table	framexml
+ContainerFrame12Item5	table	framexml
+ContainerFrame12Item5Cooldown	table	framexml
+ContainerFrame12Item5Count	table	framexml
+ContainerFrame12Item5IconTexture	table	framexml
+ContainerFrame12Item5NormalTexture	table	framexml
+ContainerFrame12Item5Stock	table	framexml
+ContainerFrame12Item6	table	framexml
+ContainerFrame12Item6Cooldown	table	framexml
+ContainerFrame12Item6Count	table	framexml
+ContainerFrame12Item6IconTexture	table	framexml
+ContainerFrame12Item6NormalTexture	table	framexml
+ContainerFrame12Item6Stock	table	framexml
+ContainerFrame12Item7	table	framexml
+ContainerFrame12Item7Cooldown	table	framexml
+ContainerFrame12Item7Count	table	framexml
+ContainerFrame12Item7IconTexture	table	framexml
+ContainerFrame12Item7NormalTexture	table	framexml
+ContainerFrame12Item7Stock	table	framexml
+ContainerFrame12Item8	table	framexml
+ContainerFrame12Item8Cooldown	table	framexml
+ContainerFrame12Item8Count	table	framexml
+ContainerFrame12Item8IconTexture	table	framexml
+ContainerFrame12Item8NormalTexture	table	framexml
+ContainerFrame12Item8Stock	table	framexml
+ContainerFrame12Item9	table	framexml
+ContainerFrame12Item9Cooldown	table	framexml
+ContainerFrame12Item9Count	table	framexml
+ContainerFrame12Item9IconTexture	table	framexml
+ContainerFrame12Item9NormalTexture	table	framexml
+ContainerFrame12Item9Stock	table	framexml
+ContainerFrame12MoneyFrame	table	framexml
+ContainerFrame12MoneyFrameCopperButton	table	framexml
+ContainerFrame12MoneyFrameCopperButtonText	table	framexml
+ContainerFrame12MoneyFrameGoldButton	table	framexml
+ContainerFrame12MoneyFrameGoldButtonText	table	framexml
+ContainerFrame12MoneyFrameSilverButton	table	framexml
+ContainerFrame12MoneyFrameSilverButtonText	table	framexml
+ContainerFrame12Name	table	framexml
+ContainerFrame12Portrait	table	framexml
+ContainerFrame12PortraitButton	table	framexml
+ContainerFrame1BackgroundBottom	table	framexml
+ContainerFrame1BackgroundMiddle1	table	framexml
+ContainerFrame1BackgroundMiddle2	table	framexml
+ContainerFrame1BackgroundTop	table	framexml
+ContainerFrame1CloseButton	table	framexml
+ContainerFrame1Item1	table	framexml
+ContainerFrame1Item10	table	framexml
+ContainerFrame1Item10Cooldown	table	framexml
+ContainerFrame1Item10Count	table	framexml
+ContainerFrame1Item10IconTexture	table	framexml
+ContainerFrame1Item10NormalTexture	table	framexml
+ContainerFrame1Item10Stock	table	framexml
+ContainerFrame1Item11	table	framexml
+ContainerFrame1Item11Cooldown	table	framexml
+ContainerFrame1Item11Count	table	framexml
+ContainerFrame1Item11IconTexture	table	framexml
+ContainerFrame1Item11NormalTexture	table	framexml
+ContainerFrame1Item11Stock	table	framexml
+ContainerFrame1Item12	table	framexml
+ContainerFrame1Item12Cooldown	table	framexml
+ContainerFrame1Item12Count	table	framexml
+ContainerFrame1Item12IconTexture	table	framexml
+ContainerFrame1Item12NormalTexture	table	framexml
+ContainerFrame1Item12Stock	table	framexml
+ContainerFrame1Item13	table	framexml
+ContainerFrame1Item13Cooldown	table	framexml
+ContainerFrame1Item13Count	table	framexml
+ContainerFrame1Item13IconTexture	table	framexml
+ContainerFrame1Item13NormalTexture	table	framexml
+ContainerFrame1Item13Stock	table	framexml
+ContainerFrame1Item14	table	framexml
+ContainerFrame1Item14Cooldown	table	framexml
+ContainerFrame1Item14Count	table	framexml
+ContainerFrame1Item14IconTexture	table	framexml
+ContainerFrame1Item14NormalTexture	table	framexml
+ContainerFrame1Item14Stock	table	framexml
+ContainerFrame1Item15	table	framexml
+ContainerFrame1Item15Cooldown	table	framexml
+ContainerFrame1Item15Count	table	framexml
+ContainerFrame1Item15IconTexture	table	framexml
+ContainerFrame1Item15NormalTexture	table	framexml
+ContainerFrame1Item15Stock	table	framexml
+ContainerFrame1Item16	table	framexml
+ContainerFrame1Item16Cooldown	table	framexml
+ContainerFrame1Item16Count	table	framexml
+ContainerFrame1Item16IconTexture	table	framexml
+ContainerFrame1Item16NormalTexture	table	framexml
+ContainerFrame1Item16Stock	table	framexml
+ContainerFrame1Item17	table	framexml
+ContainerFrame1Item17Cooldown	table	framexml
+ContainerFrame1Item17Count	table	framexml
+ContainerFrame1Item17IconTexture	table	framexml
+ContainerFrame1Item17NormalTexture	table	framexml
+ContainerFrame1Item17Stock	table	framexml
+ContainerFrame1Item18	table	framexml
+ContainerFrame1Item18Cooldown	table	framexml
+ContainerFrame1Item18Count	table	framexml
+ContainerFrame1Item18IconTexture	table	framexml
+ContainerFrame1Item18NormalTexture	table	framexml
+ContainerFrame1Item18Stock	table	framexml
+ContainerFrame1Item19	table	framexml
+ContainerFrame1Item19Cooldown	table	framexml
+ContainerFrame1Item19Count	table	framexml
+ContainerFrame1Item19IconTexture	table	framexml
+ContainerFrame1Item19NormalTexture	table	framexml
+ContainerFrame1Item19Stock	table	framexml
+ContainerFrame1Item1Cooldown	table	framexml
+ContainerFrame1Item1Count	table	framexml
+ContainerFrame1Item1IconTexture	table	framexml
+ContainerFrame1Item1NormalTexture	table	framexml
+ContainerFrame1Item1Stock	table	framexml
+ContainerFrame1Item2	table	framexml
+ContainerFrame1Item20	table	framexml
+ContainerFrame1Item20Cooldown	table	framexml
+ContainerFrame1Item20Count	table	framexml
+ContainerFrame1Item20IconTexture	table	framexml
+ContainerFrame1Item20NormalTexture	table	framexml
+ContainerFrame1Item20Stock	table	framexml
+ContainerFrame1Item21	table	framexml
+ContainerFrame1Item21Cooldown	table	framexml
+ContainerFrame1Item21Count	table	framexml
+ContainerFrame1Item21IconTexture	table	framexml
+ContainerFrame1Item21NormalTexture	table	framexml
+ContainerFrame1Item21Stock	table	framexml
+ContainerFrame1Item22	table	framexml
+ContainerFrame1Item22Cooldown	table	framexml
+ContainerFrame1Item22Count	table	framexml
+ContainerFrame1Item22IconTexture	table	framexml
+ContainerFrame1Item22NormalTexture	table	framexml
+ContainerFrame1Item22Stock	table	framexml
+ContainerFrame1Item23	table	framexml
+ContainerFrame1Item23Cooldown	table	framexml
+ContainerFrame1Item23Count	table	framexml
+ContainerFrame1Item23IconTexture	table	framexml
+ContainerFrame1Item23NormalTexture	table	framexml
+ContainerFrame1Item23Stock	table	framexml
+ContainerFrame1Item24	table	framexml
+ContainerFrame1Item24Cooldown	table	framexml
+ContainerFrame1Item24Count	table	framexml
+ContainerFrame1Item24IconTexture	table	framexml
+ContainerFrame1Item24NormalTexture	table	framexml
+ContainerFrame1Item24Stock	table	framexml
+ContainerFrame1Item25	table	framexml
+ContainerFrame1Item25Cooldown	table	framexml
+ContainerFrame1Item25Count	table	framexml
+ContainerFrame1Item25IconTexture	table	framexml
+ContainerFrame1Item25NormalTexture	table	framexml
+ContainerFrame1Item25Stock	table	framexml
+ContainerFrame1Item26	table	framexml
+ContainerFrame1Item26Cooldown	table	framexml
+ContainerFrame1Item26Count	table	framexml
+ContainerFrame1Item26IconTexture	table	framexml
+ContainerFrame1Item26NormalTexture	table	framexml
+ContainerFrame1Item26Stock	table	framexml
+ContainerFrame1Item27	table	framexml
+ContainerFrame1Item27Cooldown	table	framexml
+ContainerFrame1Item27Count	table	framexml
+ContainerFrame1Item27IconTexture	table	framexml
+ContainerFrame1Item27NormalTexture	table	framexml
+ContainerFrame1Item27Stock	table	framexml
+ContainerFrame1Item28	table	framexml
+ContainerFrame1Item28Cooldown	table	framexml
+ContainerFrame1Item28Count	table	framexml
+ContainerFrame1Item28IconTexture	table	framexml
+ContainerFrame1Item28NormalTexture	table	framexml
+ContainerFrame1Item28Stock	table	framexml
+ContainerFrame1Item29	table	framexml
+ContainerFrame1Item29Cooldown	table	framexml
+ContainerFrame1Item29Count	table	framexml
+ContainerFrame1Item29IconTexture	table	framexml
+ContainerFrame1Item29NormalTexture	table	framexml
+ContainerFrame1Item29Stock	table	framexml
+ContainerFrame1Item2Cooldown	table	framexml
+ContainerFrame1Item2Count	table	framexml
+ContainerFrame1Item2IconTexture	table	framexml
+ContainerFrame1Item2NormalTexture	table	framexml
+ContainerFrame1Item2Stock	table	framexml
+ContainerFrame1Item3	table	framexml
+ContainerFrame1Item30	table	framexml
+ContainerFrame1Item30Cooldown	table	framexml
+ContainerFrame1Item30Count	table	framexml
+ContainerFrame1Item30IconTexture	table	framexml
+ContainerFrame1Item30NormalTexture	table	framexml
+ContainerFrame1Item30Stock	table	framexml
+ContainerFrame1Item31	table	framexml
+ContainerFrame1Item31Cooldown	table	framexml
+ContainerFrame1Item31Count	table	framexml
+ContainerFrame1Item31IconTexture	table	framexml
+ContainerFrame1Item31NormalTexture	table	framexml
+ContainerFrame1Item31Stock	table	framexml
+ContainerFrame1Item32	table	framexml
+ContainerFrame1Item32Cooldown	table	framexml
+ContainerFrame1Item32Count	table	framexml
+ContainerFrame1Item32IconTexture	table	framexml
+ContainerFrame1Item32NormalTexture	table	framexml
+ContainerFrame1Item32Stock	table	framexml
+ContainerFrame1Item33	table	framexml
+ContainerFrame1Item33Cooldown	table	framexml
+ContainerFrame1Item33Count	table	framexml
+ContainerFrame1Item33IconTexture	table	framexml
+ContainerFrame1Item33NormalTexture	table	framexml
+ContainerFrame1Item33Stock	table	framexml
+ContainerFrame1Item34	table	framexml
+ContainerFrame1Item34Cooldown	table	framexml
+ContainerFrame1Item34Count	table	framexml
+ContainerFrame1Item34IconTexture	table	framexml
+ContainerFrame1Item34NormalTexture	table	framexml
+ContainerFrame1Item34Stock	table	framexml
+ContainerFrame1Item35	table	framexml
+ContainerFrame1Item35Cooldown	table	framexml
+ContainerFrame1Item35Count	table	framexml
+ContainerFrame1Item35IconTexture	table	framexml
+ContainerFrame1Item35NormalTexture	table	framexml
+ContainerFrame1Item35Stock	table	framexml
+ContainerFrame1Item36	table	framexml
+ContainerFrame1Item36Cooldown	table	framexml
+ContainerFrame1Item36Count	table	framexml
+ContainerFrame1Item36IconTexture	table	framexml
+ContainerFrame1Item36NormalTexture	table	framexml
+ContainerFrame1Item36Stock	table	framexml
+ContainerFrame1Item3Cooldown	table	framexml
+ContainerFrame1Item3Count	table	framexml
+ContainerFrame1Item3IconTexture	table	framexml
+ContainerFrame1Item3NormalTexture	table	framexml
+ContainerFrame1Item3Stock	table	framexml
+ContainerFrame1Item4	table	framexml
+ContainerFrame1Item4Cooldown	table	framexml
+ContainerFrame1Item4Count	table	framexml
+ContainerFrame1Item4IconTexture	table	framexml
+ContainerFrame1Item4NormalTexture	table	framexml
+ContainerFrame1Item4Stock	table	framexml
+ContainerFrame1Item5	table	framexml
+ContainerFrame1Item5Cooldown	table	framexml
+ContainerFrame1Item5Count	table	framexml
+ContainerFrame1Item5IconTexture	table	framexml
+ContainerFrame1Item5NormalTexture	table	framexml
+ContainerFrame1Item5Stock	table	framexml
+ContainerFrame1Item6	table	framexml
+ContainerFrame1Item6Cooldown	table	framexml
+ContainerFrame1Item6Count	table	framexml
+ContainerFrame1Item6IconTexture	table	framexml
+ContainerFrame1Item6NormalTexture	table	framexml
+ContainerFrame1Item6Stock	table	framexml
+ContainerFrame1Item7	table	framexml
+ContainerFrame1Item7Cooldown	table	framexml
+ContainerFrame1Item7Count	table	framexml
+ContainerFrame1Item7IconTexture	table	framexml
+ContainerFrame1Item7NormalTexture	table	framexml
+ContainerFrame1Item7Stock	table	framexml
+ContainerFrame1Item8	table	framexml
+ContainerFrame1Item8Cooldown	table	framexml
+ContainerFrame1Item8Count	table	framexml
+ContainerFrame1Item8IconTexture	table	framexml
+ContainerFrame1Item8NormalTexture	table	framexml
+ContainerFrame1Item8Stock	table	framexml
+ContainerFrame1Item9	table	framexml
+ContainerFrame1Item9Cooldown	table	framexml
+ContainerFrame1Item9Count	table	framexml
+ContainerFrame1Item9IconTexture	table	framexml
+ContainerFrame1Item9NormalTexture	table	framexml
+ContainerFrame1Item9Stock	table	framexml
+ContainerFrame1MoneyFrame	table	framexml
+ContainerFrame1MoneyFrameCopperButton	table	framexml
+ContainerFrame1MoneyFrameCopperButtonText	table	framexml
+ContainerFrame1MoneyFrameGoldButton	table	framexml
+ContainerFrame1MoneyFrameGoldButtonText	table	framexml
+ContainerFrame1MoneyFrameSilverButton	table	framexml
+ContainerFrame1MoneyFrameSilverButtonText	table	framexml
+ContainerFrame1Name	table	framexml
+ContainerFrame1Portrait	table	framexml
+ContainerFrame1PortraitButton	table	framexml
+ContainerFrame2	table	framexml
+ContainerFrame2BackgroundBottom	table	framexml
+ContainerFrame2BackgroundMiddle1	table	framexml
+ContainerFrame2BackgroundMiddle2	table	framexml
+ContainerFrame2BackgroundTop	table	framexml
+ContainerFrame2CloseButton	table	framexml
+ContainerFrame2Item1	table	framexml
+ContainerFrame2Item10	table	framexml
+ContainerFrame2Item10Cooldown	table	framexml
+ContainerFrame2Item10Count	table	framexml
+ContainerFrame2Item10IconTexture	table	framexml
+ContainerFrame2Item10NormalTexture	table	framexml
+ContainerFrame2Item10Stock	table	framexml
+ContainerFrame2Item11	table	framexml
+ContainerFrame2Item11Cooldown	table	framexml
+ContainerFrame2Item11Count	table	framexml
+ContainerFrame2Item11IconTexture	table	framexml
+ContainerFrame2Item11NormalTexture	table	framexml
+ContainerFrame2Item11Stock	table	framexml
+ContainerFrame2Item12	table	framexml
+ContainerFrame2Item12Cooldown	table	framexml
+ContainerFrame2Item12Count	table	framexml
+ContainerFrame2Item12IconTexture	table	framexml
+ContainerFrame2Item12NormalTexture	table	framexml
+ContainerFrame2Item12Stock	table	framexml
+ContainerFrame2Item13	table	framexml
+ContainerFrame2Item13Cooldown	table	framexml
+ContainerFrame2Item13Count	table	framexml
+ContainerFrame2Item13IconTexture	table	framexml
+ContainerFrame2Item13NormalTexture	table	framexml
+ContainerFrame2Item13Stock	table	framexml
+ContainerFrame2Item14	table	framexml
+ContainerFrame2Item14Cooldown	table	framexml
+ContainerFrame2Item14Count	table	framexml
+ContainerFrame2Item14IconTexture	table	framexml
+ContainerFrame2Item14NormalTexture	table	framexml
+ContainerFrame2Item14Stock	table	framexml
+ContainerFrame2Item15	table	framexml
+ContainerFrame2Item15Cooldown	table	framexml
+ContainerFrame2Item15Count	table	framexml
+ContainerFrame2Item15IconTexture	table	framexml
+ContainerFrame2Item15NormalTexture	table	framexml
+ContainerFrame2Item15Stock	table	framexml
+ContainerFrame2Item16	table	framexml
+ContainerFrame2Item16Cooldown	table	framexml
+ContainerFrame2Item16Count	table	framexml
+ContainerFrame2Item16IconTexture	table	framexml
+ContainerFrame2Item16NormalTexture	table	framexml
+ContainerFrame2Item16Stock	table	framexml
+ContainerFrame2Item17	table	framexml
+ContainerFrame2Item17Cooldown	table	framexml
+ContainerFrame2Item17Count	table	framexml
+ContainerFrame2Item17IconTexture	table	framexml
+ContainerFrame2Item17NormalTexture	table	framexml
+ContainerFrame2Item17Stock	table	framexml
+ContainerFrame2Item18	table	framexml
+ContainerFrame2Item18Cooldown	table	framexml
+ContainerFrame2Item18Count	table	framexml
+ContainerFrame2Item18IconTexture	table	framexml
+ContainerFrame2Item18NormalTexture	table	framexml
+ContainerFrame2Item18Stock	table	framexml
+ContainerFrame2Item19	table	framexml
+ContainerFrame2Item19Cooldown	table	framexml
+ContainerFrame2Item19Count	table	framexml
+ContainerFrame2Item19IconTexture	table	framexml
+ContainerFrame2Item19NormalTexture	table	framexml
+ContainerFrame2Item19Stock	table	framexml
+ContainerFrame2Item1Cooldown	table	framexml
+ContainerFrame2Item1Count	table	framexml
+ContainerFrame2Item1IconTexture	table	framexml
+ContainerFrame2Item1NormalTexture	table	framexml
+ContainerFrame2Item1Stock	table	framexml
+ContainerFrame2Item2	table	framexml
+ContainerFrame2Item20	table	framexml
+ContainerFrame2Item20Cooldown	table	framexml
+ContainerFrame2Item20Count	table	framexml
+ContainerFrame2Item20IconTexture	table	framexml
+ContainerFrame2Item20NormalTexture	table	framexml
+ContainerFrame2Item20Stock	table	framexml
+ContainerFrame2Item21	table	framexml
+ContainerFrame2Item21Cooldown	table	framexml
+ContainerFrame2Item21Count	table	framexml
+ContainerFrame2Item21IconTexture	table	framexml
+ContainerFrame2Item21NormalTexture	table	framexml
+ContainerFrame2Item21Stock	table	framexml
+ContainerFrame2Item22	table	framexml
+ContainerFrame2Item22Cooldown	table	framexml
+ContainerFrame2Item22Count	table	framexml
+ContainerFrame2Item22IconTexture	table	framexml
+ContainerFrame2Item22NormalTexture	table	framexml
+ContainerFrame2Item22Stock	table	framexml
+ContainerFrame2Item23	table	framexml
+ContainerFrame2Item23Cooldown	table	framexml
+ContainerFrame2Item23Count	table	framexml
+ContainerFrame2Item23IconTexture	table	framexml
+ContainerFrame2Item23NormalTexture	table	framexml
+ContainerFrame2Item23Stock	table	framexml
+ContainerFrame2Item24	table	framexml
+ContainerFrame2Item24Cooldown	table	framexml
+ContainerFrame2Item24Count	table	framexml
+ContainerFrame2Item24IconTexture	table	framexml
+ContainerFrame2Item24NormalTexture	table	framexml
+ContainerFrame2Item24Stock	table	framexml
+ContainerFrame2Item25	table	framexml
+ContainerFrame2Item25Cooldown	table	framexml
+ContainerFrame2Item25Count	table	framexml
+ContainerFrame2Item25IconTexture	table	framexml
+ContainerFrame2Item25NormalTexture	table	framexml
+ContainerFrame2Item25Stock	table	framexml
+ContainerFrame2Item26	table	framexml
+ContainerFrame2Item26Cooldown	table	framexml
+ContainerFrame2Item26Count	table	framexml
+ContainerFrame2Item26IconTexture	table	framexml
+ContainerFrame2Item26NormalTexture	table	framexml
+ContainerFrame2Item26Stock	table	framexml
+ContainerFrame2Item27	table	framexml
+ContainerFrame2Item27Cooldown	table	framexml
+ContainerFrame2Item27Count	table	framexml
+ContainerFrame2Item27IconTexture	table	framexml
+ContainerFrame2Item27NormalTexture	table	framexml
+ContainerFrame2Item27Stock	table	framexml
+ContainerFrame2Item28	table	framexml
+ContainerFrame2Item28Cooldown	table	framexml
+ContainerFrame2Item28Count	table	framexml
+ContainerFrame2Item28IconTexture	table	framexml
+ContainerFrame2Item28NormalTexture	table	framexml
+ContainerFrame2Item28Stock	table	framexml
+ContainerFrame2Item29	table	framexml
+ContainerFrame2Item29Cooldown	table	framexml
+ContainerFrame2Item29Count	table	framexml
+ContainerFrame2Item29IconTexture	table	framexml
+ContainerFrame2Item29NormalTexture	table	framexml
+ContainerFrame2Item29Stock	table	framexml
+ContainerFrame2Item2Cooldown	table	framexml
+ContainerFrame2Item2Count	table	framexml
+ContainerFrame2Item2IconTexture	table	framexml
+ContainerFrame2Item2NormalTexture	table	framexml
+ContainerFrame2Item2Stock	table	framexml
+ContainerFrame2Item3	table	framexml
+ContainerFrame2Item30	table	framexml
+ContainerFrame2Item30Cooldown	table	framexml
+ContainerFrame2Item30Count	table	framexml
+ContainerFrame2Item30IconTexture	table	framexml
+ContainerFrame2Item30NormalTexture	table	framexml
+ContainerFrame2Item30Stock	table	framexml
+ContainerFrame2Item31	table	framexml
+ContainerFrame2Item31Cooldown	table	framexml
+ContainerFrame2Item31Count	table	framexml
+ContainerFrame2Item31IconTexture	table	framexml
+ContainerFrame2Item31NormalTexture	table	framexml
+ContainerFrame2Item31Stock	table	framexml
+ContainerFrame2Item32	table	framexml
+ContainerFrame2Item32Cooldown	table	framexml
+ContainerFrame2Item32Count	table	framexml
+ContainerFrame2Item32IconTexture	table	framexml
+ContainerFrame2Item32NormalTexture	table	framexml
+ContainerFrame2Item32Stock	table	framexml
+ContainerFrame2Item33	table	framexml
+ContainerFrame2Item33Cooldown	table	framexml
+ContainerFrame2Item33Count	table	framexml
+ContainerFrame2Item33IconTexture	table	framexml
+ContainerFrame2Item33NormalTexture	table	framexml
+ContainerFrame2Item33Stock	table	framexml
+ContainerFrame2Item34	table	framexml
+ContainerFrame2Item34Cooldown	table	framexml
+ContainerFrame2Item34Count	table	framexml
+ContainerFrame2Item34IconTexture	table	framexml
+ContainerFrame2Item34NormalTexture	table	framexml
+ContainerFrame2Item34Stock	table	framexml
+ContainerFrame2Item35	table	framexml
+ContainerFrame2Item35Cooldown	table	framexml
+ContainerFrame2Item35Count	table	framexml
+ContainerFrame2Item35IconTexture	table	framexml
+ContainerFrame2Item35NormalTexture	table	framexml
+ContainerFrame2Item35Stock	table	framexml
+ContainerFrame2Item36	table	framexml
+ContainerFrame2Item36Cooldown	table	framexml
+ContainerFrame2Item36Count	table	framexml
+ContainerFrame2Item36IconTexture	table	framexml
+ContainerFrame2Item36NormalTexture	table	framexml
+ContainerFrame2Item36Stock	table	framexml
+ContainerFrame2Item3Cooldown	table	framexml
+ContainerFrame2Item3Count	table	framexml
+ContainerFrame2Item3IconTexture	table	framexml
+ContainerFrame2Item3NormalTexture	table	framexml
+ContainerFrame2Item3Stock	table	framexml
+ContainerFrame2Item4	table	framexml
+ContainerFrame2Item4Cooldown	table	framexml
+ContainerFrame2Item4Count	table	framexml
+ContainerFrame2Item4IconTexture	table	framexml
+ContainerFrame2Item4NormalTexture	table	framexml
+ContainerFrame2Item4Stock	table	framexml
+ContainerFrame2Item5	table	framexml
+ContainerFrame2Item5Cooldown	table	framexml
+ContainerFrame2Item5Count	table	framexml
+ContainerFrame2Item5IconTexture	table	framexml
+ContainerFrame2Item5NormalTexture	table	framexml
+ContainerFrame2Item5Stock	table	framexml
+ContainerFrame2Item6	table	framexml
+ContainerFrame2Item6Cooldown	table	framexml
+ContainerFrame2Item6Count	table	framexml
+ContainerFrame2Item6IconTexture	table	framexml
+ContainerFrame2Item6NormalTexture	table	framexml
+ContainerFrame2Item6Stock	table	framexml
+ContainerFrame2Item7	table	framexml
+ContainerFrame2Item7Cooldown	table	framexml
+ContainerFrame2Item7Count	table	framexml
+ContainerFrame2Item7IconTexture	table	framexml
+ContainerFrame2Item7NormalTexture	table	framexml
+ContainerFrame2Item7Stock	table	framexml
+ContainerFrame2Item8	table	framexml
+ContainerFrame2Item8Cooldown	table	framexml
+ContainerFrame2Item8Count	table	framexml
+ContainerFrame2Item8IconTexture	table	framexml
+ContainerFrame2Item8NormalTexture	table	framexml
+ContainerFrame2Item8Stock	table	framexml
+ContainerFrame2Item9	table	framexml
+ContainerFrame2Item9Cooldown	table	framexml
+ContainerFrame2Item9Count	table	framexml
+ContainerFrame2Item9IconTexture	table	framexml
+ContainerFrame2Item9NormalTexture	table	framexml
+ContainerFrame2Item9Stock	table	framexml
+ContainerFrame2MoneyFrame	table	framexml
+ContainerFrame2MoneyFrameCopperButton	table	framexml
+ContainerFrame2MoneyFrameCopperButtonText	table	framexml
+ContainerFrame2MoneyFrameGoldButton	table	framexml
+ContainerFrame2MoneyFrameGoldButtonText	table	framexml
+ContainerFrame2MoneyFrameSilverButton	table	framexml
+ContainerFrame2MoneyFrameSilverButtonText	table	framexml
+ContainerFrame2Name	table	framexml
+ContainerFrame2Portrait	table	framexml
+ContainerFrame2PortraitButton	table	framexml
+ContainerFrame3	table	framexml
+ContainerFrame3BackgroundBottom	table	framexml
+ContainerFrame3BackgroundMiddle1	table	framexml
+ContainerFrame3BackgroundMiddle2	table	framexml
+ContainerFrame3BackgroundTop	table	framexml
+ContainerFrame3CloseButton	table	framexml
+ContainerFrame3Item1	table	framexml
+ContainerFrame3Item10	table	framexml
+ContainerFrame3Item10Cooldown	table	framexml
+ContainerFrame3Item10Count	table	framexml
+ContainerFrame3Item10IconTexture	table	framexml
+ContainerFrame3Item10NormalTexture	table	framexml
+ContainerFrame3Item10Stock	table	framexml
+ContainerFrame3Item11	table	framexml
+ContainerFrame3Item11Cooldown	table	framexml
+ContainerFrame3Item11Count	table	framexml
+ContainerFrame3Item11IconTexture	table	framexml
+ContainerFrame3Item11NormalTexture	table	framexml
+ContainerFrame3Item11Stock	table	framexml
+ContainerFrame3Item12	table	framexml
+ContainerFrame3Item12Cooldown	table	framexml
+ContainerFrame3Item12Count	table	framexml
+ContainerFrame3Item12IconTexture	table	framexml
+ContainerFrame3Item12NormalTexture	table	framexml
+ContainerFrame3Item12Stock	table	framexml
+ContainerFrame3Item13	table	framexml
+ContainerFrame3Item13Cooldown	table	framexml
+ContainerFrame3Item13Count	table	framexml
+ContainerFrame3Item13IconTexture	table	framexml
+ContainerFrame3Item13NormalTexture	table	framexml
+ContainerFrame3Item13Stock	table	framexml
+ContainerFrame3Item14	table	framexml
+ContainerFrame3Item14Cooldown	table	framexml
+ContainerFrame3Item14Count	table	framexml
+ContainerFrame3Item14IconTexture	table	framexml
+ContainerFrame3Item14NormalTexture	table	framexml
+ContainerFrame3Item14Stock	table	framexml
+ContainerFrame3Item15	table	framexml
+ContainerFrame3Item15Cooldown	table	framexml
+ContainerFrame3Item15Count	table	framexml
+ContainerFrame3Item15IconTexture	table	framexml
+ContainerFrame3Item15NormalTexture	table	framexml
+ContainerFrame3Item15Stock	table	framexml
+ContainerFrame3Item16	table	framexml
+ContainerFrame3Item16Cooldown	table	framexml
+ContainerFrame3Item16Count	table	framexml
+ContainerFrame3Item16IconTexture	table	framexml
+ContainerFrame3Item16NormalTexture	table	framexml
+ContainerFrame3Item16Stock	table	framexml
+ContainerFrame3Item17	table	framexml
+ContainerFrame3Item17Cooldown	table	framexml
+ContainerFrame3Item17Count	table	framexml
+ContainerFrame3Item17IconTexture	table	framexml
+ContainerFrame3Item17NormalTexture	table	framexml
+ContainerFrame3Item17Stock	table	framexml
+ContainerFrame3Item18	table	framexml
+ContainerFrame3Item18Cooldown	table	framexml
+ContainerFrame3Item18Count	table	framexml
+ContainerFrame3Item18IconTexture	table	framexml
+ContainerFrame3Item18NormalTexture	table	framexml
+ContainerFrame3Item18Stock	table	framexml
+ContainerFrame3Item19	table	framexml
+ContainerFrame3Item19Cooldown	table	framexml
+ContainerFrame3Item19Count	table	framexml
+ContainerFrame3Item19IconTexture	table	framexml
+ContainerFrame3Item19NormalTexture	table	framexml
+ContainerFrame3Item19Stock	table	framexml
+ContainerFrame3Item1Cooldown	table	framexml
+ContainerFrame3Item1Count	table	framexml
+ContainerFrame3Item1IconTexture	table	framexml
+ContainerFrame3Item1NormalTexture	table	framexml
+ContainerFrame3Item1Stock	table	framexml
+ContainerFrame3Item2	table	framexml
+ContainerFrame3Item20	table	framexml
+ContainerFrame3Item20Cooldown	table	framexml
+ContainerFrame3Item20Count	table	framexml
+ContainerFrame3Item20IconTexture	table	framexml
+ContainerFrame3Item20NormalTexture	table	framexml
+ContainerFrame3Item20Stock	table	framexml
+ContainerFrame3Item21	table	framexml
+ContainerFrame3Item21Cooldown	table	framexml
+ContainerFrame3Item21Count	table	framexml
+ContainerFrame3Item21IconTexture	table	framexml
+ContainerFrame3Item21NormalTexture	table	framexml
+ContainerFrame3Item21Stock	table	framexml
+ContainerFrame3Item22	table	framexml
+ContainerFrame3Item22Cooldown	table	framexml
+ContainerFrame3Item22Count	table	framexml
+ContainerFrame3Item22IconTexture	table	framexml
+ContainerFrame3Item22NormalTexture	table	framexml
+ContainerFrame3Item22Stock	table	framexml
+ContainerFrame3Item23	table	framexml
+ContainerFrame3Item23Cooldown	table	framexml
+ContainerFrame3Item23Count	table	framexml
+ContainerFrame3Item23IconTexture	table	framexml
+ContainerFrame3Item23NormalTexture	table	framexml
+ContainerFrame3Item23Stock	table	framexml
+ContainerFrame3Item24	table	framexml
+ContainerFrame3Item24Cooldown	table	framexml
+ContainerFrame3Item24Count	table	framexml
+ContainerFrame3Item24IconTexture	table	framexml
+ContainerFrame3Item24NormalTexture	table	framexml
+ContainerFrame3Item24Stock	table	framexml
+ContainerFrame3Item25	table	framexml
+ContainerFrame3Item25Cooldown	table	framexml
+ContainerFrame3Item25Count	table	framexml
+ContainerFrame3Item25IconTexture	table	framexml
+ContainerFrame3Item25NormalTexture	table	framexml
+ContainerFrame3Item25Stock	table	framexml
+ContainerFrame3Item26	table	framexml
+ContainerFrame3Item26Cooldown	table	framexml
+ContainerFrame3Item26Count	table	framexml
+ContainerFrame3Item26IconTexture	table	framexml
+ContainerFrame3Item26NormalTexture	table	framexml
+ContainerFrame3Item26Stock	table	framexml
+ContainerFrame3Item27	table	framexml
+ContainerFrame3Item27Cooldown	table	framexml
+ContainerFrame3Item27Count	table	framexml
+ContainerFrame3Item27IconTexture	table	framexml
+ContainerFrame3Item27NormalTexture	table	framexml
+ContainerFrame3Item27Stock	table	framexml
+ContainerFrame3Item28	table	framexml
+ContainerFrame3Item28Cooldown	table	framexml
+ContainerFrame3Item28Count	table	framexml
+ContainerFrame3Item28IconTexture	table	framexml
+ContainerFrame3Item28NormalTexture	table	framexml
+ContainerFrame3Item28Stock	table	framexml
+ContainerFrame3Item29	table	framexml
+ContainerFrame3Item29Cooldown	table	framexml
+ContainerFrame3Item29Count	table	framexml
+ContainerFrame3Item29IconTexture	table	framexml
+ContainerFrame3Item29NormalTexture	table	framexml
+ContainerFrame3Item29Stock	table	framexml
+ContainerFrame3Item2Cooldown	table	framexml
+ContainerFrame3Item2Count	table	framexml
+ContainerFrame3Item2IconTexture	table	framexml
+ContainerFrame3Item2NormalTexture	table	framexml
+ContainerFrame3Item2Stock	table	framexml
+ContainerFrame3Item3	table	framexml
+ContainerFrame3Item30	table	framexml
+ContainerFrame3Item30Cooldown	table	framexml
+ContainerFrame3Item30Count	table	framexml
+ContainerFrame3Item30IconTexture	table	framexml
+ContainerFrame3Item30NormalTexture	table	framexml
+ContainerFrame3Item30Stock	table	framexml
+ContainerFrame3Item31	table	framexml
+ContainerFrame3Item31Cooldown	table	framexml
+ContainerFrame3Item31Count	table	framexml
+ContainerFrame3Item31IconTexture	table	framexml
+ContainerFrame3Item31NormalTexture	table	framexml
+ContainerFrame3Item31Stock	table	framexml
+ContainerFrame3Item32	table	framexml
+ContainerFrame3Item32Cooldown	table	framexml
+ContainerFrame3Item32Count	table	framexml
+ContainerFrame3Item32IconTexture	table	framexml
+ContainerFrame3Item32NormalTexture	table	framexml
+ContainerFrame3Item32Stock	table	framexml
+ContainerFrame3Item33	table	framexml
+ContainerFrame3Item33Cooldown	table	framexml
+ContainerFrame3Item33Count	table	framexml
+ContainerFrame3Item33IconTexture	table	framexml
+ContainerFrame3Item33NormalTexture	table	framexml
+ContainerFrame3Item33Stock	table	framexml
+ContainerFrame3Item34	table	framexml
+ContainerFrame3Item34Cooldown	table	framexml
+ContainerFrame3Item34Count	table	framexml
+ContainerFrame3Item34IconTexture	table	framexml
+ContainerFrame3Item34NormalTexture	table	framexml
+ContainerFrame3Item34Stock	table	framexml
+ContainerFrame3Item35	table	framexml
+ContainerFrame3Item35Cooldown	table	framexml
+ContainerFrame3Item35Count	table	framexml
+ContainerFrame3Item35IconTexture	table	framexml
+ContainerFrame3Item35NormalTexture	table	framexml
+ContainerFrame3Item35Stock	table	framexml
+ContainerFrame3Item36	table	framexml
+ContainerFrame3Item36Cooldown	table	framexml
+ContainerFrame3Item36Count	table	framexml
+ContainerFrame3Item36IconTexture	table	framexml
+ContainerFrame3Item36NormalTexture	table	framexml
+ContainerFrame3Item36Stock	table	framexml
+ContainerFrame3Item3Cooldown	table	framexml
+ContainerFrame3Item3Count	table	framexml
+ContainerFrame3Item3IconTexture	table	framexml
+ContainerFrame3Item3NormalTexture	table	framexml
+ContainerFrame3Item3Stock	table	framexml
+ContainerFrame3Item4	table	framexml
+ContainerFrame3Item4Cooldown	table	framexml
+ContainerFrame3Item4Count	table	framexml
+ContainerFrame3Item4IconTexture	table	framexml
+ContainerFrame3Item4NormalTexture	table	framexml
+ContainerFrame3Item4Stock	table	framexml
+ContainerFrame3Item5	table	framexml
+ContainerFrame3Item5Cooldown	table	framexml
+ContainerFrame3Item5Count	table	framexml
+ContainerFrame3Item5IconTexture	table	framexml
+ContainerFrame3Item5NormalTexture	table	framexml
+ContainerFrame3Item5Stock	table	framexml
+ContainerFrame3Item6	table	framexml
+ContainerFrame3Item6Cooldown	table	framexml
+ContainerFrame3Item6Count	table	framexml
+ContainerFrame3Item6IconTexture	table	framexml
+ContainerFrame3Item6NormalTexture	table	framexml
+ContainerFrame3Item6Stock	table	framexml
+ContainerFrame3Item7	table	framexml
+ContainerFrame3Item7Cooldown	table	framexml
+ContainerFrame3Item7Count	table	framexml
+ContainerFrame3Item7IconTexture	table	framexml
+ContainerFrame3Item7NormalTexture	table	framexml
+ContainerFrame3Item7Stock	table	framexml
+ContainerFrame3Item8	table	framexml
+ContainerFrame3Item8Cooldown	table	framexml
+ContainerFrame3Item8Count	table	framexml
+ContainerFrame3Item8IconTexture	table	framexml
+ContainerFrame3Item8NormalTexture	table	framexml
+ContainerFrame3Item8Stock	table	framexml
+ContainerFrame3Item9	table	framexml
+ContainerFrame3Item9Cooldown	table	framexml
+ContainerFrame3Item9Count	table	framexml
+ContainerFrame3Item9IconTexture	table	framexml
+ContainerFrame3Item9NormalTexture	table	framexml
+ContainerFrame3Item9Stock	table	framexml
+ContainerFrame3MoneyFrame	table	framexml
+ContainerFrame3MoneyFrameCopperButton	table	framexml
+ContainerFrame3MoneyFrameCopperButtonText	table	framexml
+ContainerFrame3MoneyFrameGoldButton	table	framexml
+ContainerFrame3MoneyFrameGoldButtonText	table	framexml
+ContainerFrame3MoneyFrameSilverButton	table	framexml
+ContainerFrame3MoneyFrameSilverButtonText	table	framexml
+ContainerFrame3Name	table	framexml
+ContainerFrame3Portrait	table	framexml
+ContainerFrame3PortraitButton	table	framexml
+ContainerFrame4	table	framexml
+ContainerFrame4BackgroundBottom	table	framexml
+ContainerFrame4BackgroundMiddle1	table	framexml
+ContainerFrame4BackgroundMiddle2	table	framexml
+ContainerFrame4BackgroundTop	table	framexml
+ContainerFrame4CloseButton	table	framexml
+ContainerFrame4Item1	table	framexml
+ContainerFrame4Item10	table	framexml
+ContainerFrame4Item10Cooldown	table	framexml
+ContainerFrame4Item10Count	table	framexml
+ContainerFrame4Item10IconTexture	table	framexml
+ContainerFrame4Item10NormalTexture	table	framexml
+ContainerFrame4Item10Stock	table	framexml
+ContainerFrame4Item11	table	framexml
+ContainerFrame4Item11Cooldown	table	framexml
+ContainerFrame4Item11Count	table	framexml
+ContainerFrame4Item11IconTexture	table	framexml
+ContainerFrame4Item11NormalTexture	table	framexml
+ContainerFrame4Item11Stock	table	framexml
+ContainerFrame4Item12	table	framexml
+ContainerFrame4Item12Cooldown	table	framexml
+ContainerFrame4Item12Count	table	framexml
+ContainerFrame4Item12IconTexture	table	framexml
+ContainerFrame4Item12NormalTexture	table	framexml
+ContainerFrame4Item12Stock	table	framexml
+ContainerFrame4Item13	table	framexml
+ContainerFrame4Item13Cooldown	table	framexml
+ContainerFrame4Item13Count	table	framexml
+ContainerFrame4Item13IconTexture	table	framexml
+ContainerFrame4Item13NormalTexture	table	framexml
+ContainerFrame4Item13Stock	table	framexml
+ContainerFrame4Item14	table	framexml
+ContainerFrame4Item14Cooldown	table	framexml
+ContainerFrame4Item14Count	table	framexml
+ContainerFrame4Item14IconTexture	table	framexml
+ContainerFrame4Item14NormalTexture	table	framexml
+ContainerFrame4Item14Stock	table	framexml
+ContainerFrame4Item15	table	framexml
+ContainerFrame4Item15Cooldown	table	framexml
+ContainerFrame4Item15Count	table	framexml
+ContainerFrame4Item15IconTexture	table	framexml
+ContainerFrame4Item15NormalTexture	table	framexml
+ContainerFrame4Item15Stock	table	framexml
+ContainerFrame4Item16	table	framexml
+ContainerFrame4Item16Cooldown	table	framexml
+ContainerFrame4Item16Count	table	framexml
+ContainerFrame4Item16IconTexture	table	framexml
+ContainerFrame4Item16NormalTexture	table	framexml
+ContainerFrame4Item16Stock	table	framexml
+ContainerFrame4Item17	table	framexml
+ContainerFrame4Item17Cooldown	table	framexml
+ContainerFrame4Item17Count	table	framexml
+ContainerFrame4Item17IconTexture	table	framexml
+ContainerFrame4Item17NormalTexture	table	framexml
+ContainerFrame4Item17Stock	table	framexml
+ContainerFrame4Item18	table	framexml
+ContainerFrame4Item18Cooldown	table	framexml
+ContainerFrame4Item18Count	table	framexml
+ContainerFrame4Item18IconTexture	table	framexml
+ContainerFrame4Item18NormalTexture	table	framexml
+ContainerFrame4Item18Stock	table	framexml
+ContainerFrame4Item19	table	framexml
+ContainerFrame4Item19Cooldown	table	framexml
+ContainerFrame4Item19Count	table	framexml
+ContainerFrame4Item19IconTexture	table	framexml
+ContainerFrame4Item19NormalTexture	table	framexml
+ContainerFrame4Item19Stock	table	framexml
+ContainerFrame4Item1Cooldown	table	framexml
+ContainerFrame4Item1Count	table	framexml
+ContainerFrame4Item1IconTexture	table	framexml
+ContainerFrame4Item1NormalTexture	table	framexml
+ContainerFrame4Item1Stock	table	framexml
+ContainerFrame4Item2	table	framexml
+ContainerFrame4Item20	table	framexml
+ContainerFrame4Item20Cooldown	table	framexml
+ContainerFrame4Item20Count	table	framexml
+ContainerFrame4Item20IconTexture	table	framexml
+ContainerFrame4Item20NormalTexture	table	framexml
+ContainerFrame4Item20Stock	table	framexml
+ContainerFrame4Item21	table	framexml
+ContainerFrame4Item21Cooldown	table	framexml
+ContainerFrame4Item21Count	table	framexml
+ContainerFrame4Item21IconTexture	table	framexml
+ContainerFrame4Item21NormalTexture	table	framexml
+ContainerFrame4Item21Stock	table	framexml
+ContainerFrame4Item22	table	framexml
+ContainerFrame4Item22Cooldown	table	framexml
+ContainerFrame4Item22Count	table	framexml
+ContainerFrame4Item22IconTexture	table	framexml
+ContainerFrame4Item22NormalTexture	table	framexml
+ContainerFrame4Item22Stock	table	framexml
+ContainerFrame4Item23	table	framexml
+ContainerFrame4Item23Cooldown	table	framexml
+ContainerFrame4Item23Count	table	framexml
+ContainerFrame4Item23IconTexture	table	framexml
+ContainerFrame4Item23NormalTexture	table	framexml
+ContainerFrame4Item23Stock	table	framexml
+ContainerFrame4Item24	table	framexml
+ContainerFrame4Item24Cooldown	table	framexml
+ContainerFrame4Item24Count	table	framexml
+ContainerFrame4Item24IconTexture	table	framexml
+ContainerFrame4Item24NormalTexture	table	framexml
+ContainerFrame4Item24Stock	table	framexml
+ContainerFrame4Item25	table	framexml
+ContainerFrame4Item25Cooldown	table	framexml
+ContainerFrame4Item25Count	table	framexml
+ContainerFrame4Item25IconTexture	table	framexml
+ContainerFrame4Item25NormalTexture	table	framexml
+ContainerFrame4Item25Stock	table	framexml
+ContainerFrame4Item26	table	framexml
+ContainerFrame4Item26Cooldown	table	framexml
+ContainerFrame4Item26Count	table	framexml
+ContainerFrame4Item26IconTexture	table	framexml
+ContainerFrame4Item26NormalTexture	table	framexml
+ContainerFrame4Item26Stock	table	framexml
+ContainerFrame4Item27	table	framexml
+ContainerFrame4Item27Cooldown	table	framexml
+ContainerFrame4Item27Count	table	framexml
+ContainerFrame4Item27IconTexture	table	framexml
+ContainerFrame4Item27NormalTexture	table	framexml
+ContainerFrame4Item27Stock	table	framexml
+ContainerFrame4Item28	table	framexml
+ContainerFrame4Item28Cooldown	table	framexml
+ContainerFrame4Item28Count	table	framexml
+ContainerFrame4Item28IconTexture	table	framexml
+ContainerFrame4Item28NormalTexture	table	framexml
+ContainerFrame4Item28Stock	table	framexml
+ContainerFrame4Item29	table	framexml
+ContainerFrame4Item29Cooldown	table	framexml
+ContainerFrame4Item29Count	table	framexml
+ContainerFrame4Item29IconTexture	table	framexml
+ContainerFrame4Item29NormalTexture	table	framexml
+ContainerFrame4Item29Stock	table	framexml
+ContainerFrame4Item2Cooldown	table	framexml
+ContainerFrame4Item2Count	table	framexml
+ContainerFrame4Item2IconTexture	table	framexml
+ContainerFrame4Item2NormalTexture	table	framexml
+ContainerFrame4Item2Stock	table	framexml
+ContainerFrame4Item3	table	framexml
+ContainerFrame4Item30	table	framexml
+ContainerFrame4Item30Cooldown	table	framexml
+ContainerFrame4Item30Count	table	framexml
+ContainerFrame4Item30IconTexture	table	framexml
+ContainerFrame4Item30NormalTexture	table	framexml
+ContainerFrame4Item30Stock	table	framexml
+ContainerFrame4Item31	table	framexml
+ContainerFrame4Item31Cooldown	table	framexml
+ContainerFrame4Item31Count	table	framexml
+ContainerFrame4Item31IconTexture	table	framexml
+ContainerFrame4Item31NormalTexture	table	framexml
+ContainerFrame4Item31Stock	table	framexml
+ContainerFrame4Item32	table	framexml
+ContainerFrame4Item32Cooldown	table	framexml
+ContainerFrame4Item32Count	table	framexml
+ContainerFrame4Item32IconTexture	table	framexml
+ContainerFrame4Item32NormalTexture	table	framexml
+ContainerFrame4Item32Stock	table	framexml
+ContainerFrame4Item33	table	framexml
+ContainerFrame4Item33Cooldown	table	framexml
+ContainerFrame4Item33Count	table	framexml
+ContainerFrame4Item33IconTexture	table	framexml
+ContainerFrame4Item33NormalTexture	table	framexml
+ContainerFrame4Item33Stock	table	framexml
+ContainerFrame4Item34	table	framexml
+ContainerFrame4Item34Cooldown	table	framexml
+ContainerFrame4Item34Count	table	framexml
+ContainerFrame4Item34IconTexture	table	framexml
+ContainerFrame4Item34NormalTexture	table	framexml
+ContainerFrame4Item34Stock	table	framexml
+ContainerFrame4Item35	table	framexml
+ContainerFrame4Item35Cooldown	table	framexml
+ContainerFrame4Item35Count	table	framexml
+ContainerFrame4Item35IconTexture	table	framexml
+ContainerFrame4Item35NormalTexture	table	framexml
+ContainerFrame4Item35Stock	table	framexml
+ContainerFrame4Item36	table	framexml
+ContainerFrame4Item36Cooldown	table	framexml
+ContainerFrame4Item36Count	table	framexml
+ContainerFrame4Item36IconTexture	table	framexml
+ContainerFrame4Item36NormalTexture	table	framexml
+ContainerFrame4Item36Stock	table	framexml
+ContainerFrame4Item3Cooldown	table	framexml
+ContainerFrame4Item3Count	table	framexml
+ContainerFrame4Item3IconTexture	table	framexml
+ContainerFrame4Item3NormalTexture	table	framexml
+ContainerFrame4Item3Stock	table	framexml
+ContainerFrame4Item4	table	framexml
+ContainerFrame4Item4Cooldown	table	framexml
+ContainerFrame4Item4Count	table	framexml
+ContainerFrame4Item4IconTexture	table	framexml
+ContainerFrame4Item4NormalTexture	table	framexml
+ContainerFrame4Item4Stock	table	framexml
+ContainerFrame4Item5	table	framexml
+ContainerFrame4Item5Cooldown	table	framexml
+ContainerFrame4Item5Count	table	framexml
+ContainerFrame4Item5IconTexture	table	framexml
+ContainerFrame4Item5NormalTexture	table	framexml
+ContainerFrame4Item5Stock	table	framexml
+ContainerFrame4Item6	table	framexml
+ContainerFrame4Item6Cooldown	table	framexml
+ContainerFrame4Item6Count	table	framexml
+ContainerFrame4Item6IconTexture	table	framexml
+ContainerFrame4Item6NormalTexture	table	framexml
+ContainerFrame4Item6Stock	table	framexml
+ContainerFrame4Item7	table	framexml
+ContainerFrame4Item7Cooldown	table	framexml
+ContainerFrame4Item7Count	table	framexml
+ContainerFrame4Item7IconTexture	table	framexml
+ContainerFrame4Item7NormalTexture	table	framexml
+ContainerFrame4Item7Stock	table	framexml
+ContainerFrame4Item8	table	framexml
+ContainerFrame4Item8Cooldown	table	framexml
+ContainerFrame4Item8Count	table	framexml
+ContainerFrame4Item8IconTexture	table	framexml
+ContainerFrame4Item8NormalTexture	table	framexml
+ContainerFrame4Item8Stock	table	framexml
+ContainerFrame4Item9	table	framexml
+ContainerFrame4Item9Cooldown	table	framexml
+ContainerFrame4Item9Count	table	framexml
+ContainerFrame4Item9IconTexture	table	framexml
+ContainerFrame4Item9NormalTexture	table	framexml
+ContainerFrame4Item9Stock	table	framexml
+ContainerFrame4MoneyFrame	table	framexml
+ContainerFrame4MoneyFrameCopperButton	table	framexml
+ContainerFrame4MoneyFrameCopperButtonText	table	framexml
+ContainerFrame4MoneyFrameGoldButton	table	framexml
+ContainerFrame4MoneyFrameGoldButtonText	table	framexml
+ContainerFrame4MoneyFrameSilverButton	table	framexml
+ContainerFrame4MoneyFrameSilverButtonText	table	framexml
+ContainerFrame4Name	table	framexml
+ContainerFrame4Portrait	table	framexml
+ContainerFrame4PortraitButton	table	framexml
+ContainerFrame5	table	framexml
+ContainerFrame5BackgroundBottom	table	framexml
+ContainerFrame5BackgroundMiddle1	table	framexml
+ContainerFrame5BackgroundMiddle2	table	framexml
+ContainerFrame5BackgroundTop	table	framexml
+ContainerFrame5CloseButton	table	framexml
+ContainerFrame5Item1	table	framexml
+ContainerFrame5Item10	table	framexml
+ContainerFrame5Item10Cooldown	table	framexml
+ContainerFrame5Item10Count	table	framexml
+ContainerFrame5Item10IconTexture	table	framexml
+ContainerFrame5Item10NormalTexture	table	framexml
+ContainerFrame5Item10Stock	table	framexml
+ContainerFrame5Item11	table	framexml
+ContainerFrame5Item11Cooldown	table	framexml
+ContainerFrame5Item11Count	table	framexml
+ContainerFrame5Item11IconTexture	table	framexml
+ContainerFrame5Item11NormalTexture	table	framexml
+ContainerFrame5Item11Stock	table	framexml
+ContainerFrame5Item12	table	framexml
+ContainerFrame5Item12Cooldown	table	framexml
+ContainerFrame5Item12Count	table	framexml
+ContainerFrame5Item12IconTexture	table	framexml
+ContainerFrame5Item12NormalTexture	table	framexml
+ContainerFrame5Item12Stock	table	framexml
+ContainerFrame5Item13	table	framexml
+ContainerFrame5Item13Cooldown	table	framexml
+ContainerFrame5Item13Count	table	framexml
+ContainerFrame5Item13IconTexture	table	framexml
+ContainerFrame5Item13NormalTexture	table	framexml
+ContainerFrame5Item13Stock	table	framexml
+ContainerFrame5Item14	table	framexml
+ContainerFrame5Item14Cooldown	table	framexml
+ContainerFrame5Item14Count	table	framexml
+ContainerFrame5Item14IconTexture	table	framexml
+ContainerFrame5Item14NormalTexture	table	framexml
+ContainerFrame5Item14Stock	table	framexml
+ContainerFrame5Item15	table	framexml
+ContainerFrame5Item15Cooldown	table	framexml
+ContainerFrame5Item15Count	table	framexml
+ContainerFrame5Item15IconTexture	table	framexml
+ContainerFrame5Item15NormalTexture	table	framexml
+ContainerFrame5Item15Stock	table	framexml
+ContainerFrame5Item16	table	framexml
+ContainerFrame5Item16Cooldown	table	framexml
+ContainerFrame5Item16Count	table	framexml
+ContainerFrame5Item16IconTexture	table	framexml
+ContainerFrame5Item16NormalTexture	table	framexml
+ContainerFrame5Item16Stock	table	framexml
+ContainerFrame5Item17	table	framexml
+ContainerFrame5Item17Cooldown	table	framexml
+ContainerFrame5Item17Count	table	framexml
+ContainerFrame5Item17IconTexture	table	framexml
+ContainerFrame5Item17NormalTexture	table	framexml
+ContainerFrame5Item17Stock	table	framexml
+ContainerFrame5Item18	table	framexml
+ContainerFrame5Item18Cooldown	table	framexml
+ContainerFrame5Item18Count	table	framexml
+ContainerFrame5Item18IconTexture	table	framexml
+ContainerFrame5Item18NormalTexture	table	framexml
+ContainerFrame5Item18Stock	table	framexml
+ContainerFrame5Item19	table	framexml
+ContainerFrame5Item19Cooldown	table	framexml
+ContainerFrame5Item19Count	table	framexml
+ContainerFrame5Item19IconTexture	table	framexml
+ContainerFrame5Item19NormalTexture	table	framexml
+ContainerFrame5Item19Stock	table	framexml
+ContainerFrame5Item1Cooldown	table	framexml
+ContainerFrame5Item1Count	table	framexml
+ContainerFrame5Item1IconTexture	table	framexml
+ContainerFrame5Item1NormalTexture	table	framexml
+ContainerFrame5Item1Stock	table	framexml
+ContainerFrame5Item2	table	framexml
+ContainerFrame5Item20	table	framexml
+ContainerFrame5Item20Cooldown	table	framexml
+ContainerFrame5Item20Count	table	framexml
+ContainerFrame5Item20IconTexture	table	framexml
+ContainerFrame5Item20NormalTexture	table	framexml
+ContainerFrame5Item20Stock	table	framexml
+ContainerFrame5Item21	table	framexml
+ContainerFrame5Item21Cooldown	table	framexml
+ContainerFrame5Item21Count	table	framexml
+ContainerFrame5Item21IconTexture	table	framexml
+ContainerFrame5Item21NormalTexture	table	framexml
+ContainerFrame5Item21Stock	table	framexml
+ContainerFrame5Item22	table	framexml
+ContainerFrame5Item22Cooldown	table	framexml
+ContainerFrame5Item22Count	table	framexml
+ContainerFrame5Item22IconTexture	table	framexml
+ContainerFrame5Item22NormalTexture	table	framexml
+ContainerFrame5Item22Stock	table	framexml
+ContainerFrame5Item23	table	framexml
+ContainerFrame5Item23Cooldown	table	framexml
+ContainerFrame5Item23Count	table	framexml
+ContainerFrame5Item23IconTexture	table	framexml
+ContainerFrame5Item23NormalTexture	table	framexml
+ContainerFrame5Item23Stock	table	framexml
+ContainerFrame5Item24	table	framexml
+ContainerFrame5Item24Cooldown	table	framexml
+ContainerFrame5Item24Count	table	framexml
+ContainerFrame5Item24IconTexture	table	framexml
+ContainerFrame5Item24NormalTexture	table	framexml
+ContainerFrame5Item24Stock	table	framexml
+ContainerFrame5Item25	table	framexml
+ContainerFrame5Item25Cooldown	table	framexml
+ContainerFrame5Item25Count	table	framexml
+ContainerFrame5Item25IconTexture	table	framexml
+ContainerFrame5Item25NormalTexture	table	framexml
+ContainerFrame5Item25Stock	table	framexml
+ContainerFrame5Item26	table	framexml
+ContainerFrame5Item26Cooldown	table	framexml
+ContainerFrame5Item26Count	table	framexml
+ContainerFrame5Item26IconTexture	table	framexml
+ContainerFrame5Item26NormalTexture	table	framexml
+ContainerFrame5Item26Stock	table	framexml
+ContainerFrame5Item27	table	framexml
+ContainerFrame5Item27Cooldown	table	framexml
+ContainerFrame5Item27Count	table	framexml
+ContainerFrame5Item27IconTexture	table	framexml
+ContainerFrame5Item27NormalTexture	table	framexml
+ContainerFrame5Item27Stock	table	framexml
+ContainerFrame5Item28	table	framexml
+ContainerFrame5Item28Cooldown	table	framexml
+ContainerFrame5Item28Count	table	framexml
+ContainerFrame5Item28IconTexture	table	framexml
+ContainerFrame5Item28NormalTexture	table	framexml
+ContainerFrame5Item28Stock	table	framexml
+ContainerFrame5Item29	table	framexml
+ContainerFrame5Item29Cooldown	table	framexml
+ContainerFrame5Item29Count	table	framexml
+ContainerFrame5Item29IconTexture	table	framexml
+ContainerFrame5Item29NormalTexture	table	framexml
+ContainerFrame5Item29Stock	table	framexml
+ContainerFrame5Item2Cooldown	table	framexml
+ContainerFrame5Item2Count	table	framexml
+ContainerFrame5Item2IconTexture	table	framexml
+ContainerFrame5Item2NormalTexture	table	framexml
+ContainerFrame5Item2Stock	table	framexml
+ContainerFrame5Item3	table	framexml
+ContainerFrame5Item30	table	framexml
+ContainerFrame5Item30Cooldown	table	framexml
+ContainerFrame5Item30Count	table	framexml
+ContainerFrame5Item30IconTexture	table	framexml
+ContainerFrame5Item30NormalTexture	table	framexml
+ContainerFrame5Item30Stock	table	framexml
+ContainerFrame5Item31	table	framexml
+ContainerFrame5Item31Cooldown	table	framexml
+ContainerFrame5Item31Count	table	framexml
+ContainerFrame5Item31IconTexture	table	framexml
+ContainerFrame5Item31NormalTexture	table	framexml
+ContainerFrame5Item31Stock	table	framexml
+ContainerFrame5Item32	table	framexml
+ContainerFrame5Item32Cooldown	table	framexml
+ContainerFrame5Item32Count	table	framexml
+ContainerFrame5Item32IconTexture	table	framexml
+ContainerFrame5Item32NormalTexture	table	framexml
+ContainerFrame5Item32Stock	table	framexml
+ContainerFrame5Item33	table	framexml
+ContainerFrame5Item33Cooldown	table	framexml
+ContainerFrame5Item33Count	table	framexml
+ContainerFrame5Item33IconTexture	table	framexml
+ContainerFrame5Item33NormalTexture	table	framexml
+ContainerFrame5Item33Stock	table	framexml
+ContainerFrame5Item34	table	framexml
+ContainerFrame5Item34Cooldown	table	framexml
+ContainerFrame5Item34Count	table	framexml
+ContainerFrame5Item34IconTexture	table	framexml
+ContainerFrame5Item34NormalTexture	table	framexml
+ContainerFrame5Item34Stock	table	framexml
+ContainerFrame5Item35	table	framexml
+ContainerFrame5Item35Cooldown	table	framexml
+ContainerFrame5Item35Count	table	framexml
+ContainerFrame5Item35IconTexture	table	framexml
+ContainerFrame5Item35NormalTexture	table	framexml
+ContainerFrame5Item35Stock	table	framexml
+ContainerFrame5Item36	table	framexml
+ContainerFrame5Item36Cooldown	table	framexml
+ContainerFrame5Item36Count	table	framexml
+ContainerFrame5Item36IconTexture	table	framexml
+ContainerFrame5Item36NormalTexture	table	framexml
+ContainerFrame5Item36Stock	table	framexml
+ContainerFrame5Item3Cooldown	table	framexml
+ContainerFrame5Item3Count	table	framexml
+ContainerFrame5Item3IconTexture	table	framexml
+ContainerFrame5Item3NormalTexture	table	framexml
+ContainerFrame5Item3Stock	table	framexml
+ContainerFrame5Item4	table	framexml
+ContainerFrame5Item4Cooldown	table	framexml
+ContainerFrame5Item4Count	table	framexml
+ContainerFrame5Item4IconTexture	table	framexml
+ContainerFrame5Item4NormalTexture	table	framexml
+ContainerFrame5Item4Stock	table	framexml
+ContainerFrame5Item5	table	framexml
+ContainerFrame5Item5Cooldown	table	framexml
+ContainerFrame5Item5Count	table	framexml
+ContainerFrame5Item5IconTexture	table	framexml
+ContainerFrame5Item5NormalTexture	table	framexml
+ContainerFrame5Item5Stock	table	framexml
+ContainerFrame5Item6	table	framexml
+ContainerFrame5Item6Cooldown	table	framexml
+ContainerFrame5Item6Count	table	framexml
+ContainerFrame5Item6IconTexture	table	framexml
+ContainerFrame5Item6NormalTexture	table	framexml
+ContainerFrame5Item6Stock	table	framexml
+ContainerFrame5Item7	table	framexml
+ContainerFrame5Item7Cooldown	table	framexml
+ContainerFrame5Item7Count	table	framexml
+ContainerFrame5Item7IconTexture	table	framexml
+ContainerFrame5Item7NormalTexture	table	framexml
+ContainerFrame5Item7Stock	table	framexml
+ContainerFrame5Item8	table	framexml
+ContainerFrame5Item8Cooldown	table	framexml
+ContainerFrame5Item8Count	table	framexml
+ContainerFrame5Item8IconTexture	table	framexml
+ContainerFrame5Item8NormalTexture	table	framexml
+ContainerFrame5Item8Stock	table	framexml
+ContainerFrame5Item9	table	framexml
+ContainerFrame5Item9Cooldown	table	framexml
+ContainerFrame5Item9Count	table	framexml
+ContainerFrame5Item9IconTexture	table	framexml
+ContainerFrame5Item9NormalTexture	table	framexml
+ContainerFrame5Item9Stock	table	framexml
+ContainerFrame5MoneyFrame	table	framexml
+ContainerFrame5MoneyFrameCopperButton	table	framexml
+ContainerFrame5MoneyFrameCopperButtonText	table	framexml
+ContainerFrame5MoneyFrameGoldButton	table	framexml
+ContainerFrame5MoneyFrameGoldButtonText	table	framexml
+ContainerFrame5MoneyFrameSilverButton	table	framexml
+ContainerFrame5MoneyFrameSilverButtonText	table	framexml
+ContainerFrame5Name	table	framexml
+ContainerFrame5Portrait	table	framexml
+ContainerFrame5PortraitButton	table	framexml
+ContainerFrame6	table	framexml
+ContainerFrame6BackgroundBottom	table	framexml
+ContainerFrame6BackgroundMiddle1	table	framexml
+ContainerFrame6BackgroundMiddle2	table	framexml
+ContainerFrame6BackgroundTop	table	framexml
+ContainerFrame6CloseButton	table	framexml
+ContainerFrame6Item1	table	framexml
+ContainerFrame6Item10	table	framexml
+ContainerFrame6Item10Cooldown	table	framexml
+ContainerFrame6Item10Count	table	framexml
+ContainerFrame6Item10IconTexture	table	framexml
+ContainerFrame6Item10NormalTexture	table	framexml
+ContainerFrame6Item10Stock	table	framexml
+ContainerFrame6Item11	table	framexml
+ContainerFrame6Item11Cooldown	table	framexml
+ContainerFrame6Item11Count	table	framexml
+ContainerFrame6Item11IconTexture	table	framexml
+ContainerFrame6Item11NormalTexture	table	framexml
+ContainerFrame6Item11Stock	table	framexml
+ContainerFrame6Item12	table	framexml
+ContainerFrame6Item12Cooldown	table	framexml
+ContainerFrame6Item12Count	table	framexml
+ContainerFrame6Item12IconTexture	table	framexml
+ContainerFrame6Item12NormalTexture	table	framexml
+ContainerFrame6Item12Stock	table	framexml
+ContainerFrame6Item13	table	framexml
+ContainerFrame6Item13Cooldown	table	framexml
+ContainerFrame6Item13Count	table	framexml
+ContainerFrame6Item13IconTexture	table	framexml
+ContainerFrame6Item13NormalTexture	table	framexml
+ContainerFrame6Item13Stock	table	framexml
+ContainerFrame6Item14	table	framexml
+ContainerFrame6Item14Cooldown	table	framexml
+ContainerFrame6Item14Count	table	framexml
+ContainerFrame6Item14IconTexture	table	framexml
+ContainerFrame6Item14NormalTexture	table	framexml
+ContainerFrame6Item14Stock	table	framexml
+ContainerFrame6Item15	table	framexml
+ContainerFrame6Item15Cooldown	table	framexml
+ContainerFrame6Item15Count	table	framexml
+ContainerFrame6Item15IconTexture	table	framexml
+ContainerFrame6Item15NormalTexture	table	framexml
+ContainerFrame6Item15Stock	table	framexml
+ContainerFrame6Item16	table	framexml
+ContainerFrame6Item16Cooldown	table	framexml
+ContainerFrame6Item16Count	table	framexml
+ContainerFrame6Item16IconTexture	table	framexml
+ContainerFrame6Item16NormalTexture	table	framexml
+ContainerFrame6Item16Stock	table	framexml
+ContainerFrame6Item17	table	framexml
+ContainerFrame6Item17Cooldown	table	framexml
+ContainerFrame6Item17Count	table	framexml
+ContainerFrame6Item17IconTexture	table	framexml
+ContainerFrame6Item17NormalTexture	table	framexml
+ContainerFrame6Item17Stock	table	framexml
+ContainerFrame6Item18	table	framexml
+ContainerFrame6Item18Cooldown	table	framexml
+ContainerFrame6Item18Count	table	framexml
+ContainerFrame6Item18IconTexture	table	framexml
+ContainerFrame6Item18NormalTexture	table	framexml
+ContainerFrame6Item18Stock	table	framexml
+ContainerFrame6Item19	table	framexml
+ContainerFrame6Item19Cooldown	table	framexml
+ContainerFrame6Item19Count	table	framexml
+ContainerFrame6Item19IconTexture	table	framexml
+ContainerFrame6Item19NormalTexture	table	framexml
+ContainerFrame6Item19Stock	table	framexml
+ContainerFrame6Item1Cooldown	table	framexml
+ContainerFrame6Item1Count	table	framexml
+ContainerFrame6Item1IconTexture	table	framexml
+ContainerFrame6Item1NormalTexture	table	framexml
+ContainerFrame6Item1Stock	table	framexml
+ContainerFrame6Item2	table	framexml
+ContainerFrame6Item20	table	framexml
+ContainerFrame6Item20Cooldown	table	framexml
+ContainerFrame6Item20Count	table	framexml
+ContainerFrame6Item20IconTexture	table	framexml
+ContainerFrame6Item20NormalTexture	table	framexml
+ContainerFrame6Item20Stock	table	framexml
+ContainerFrame6Item21	table	framexml
+ContainerFrame6Item21Cooldown	table	framexml
+ContainerFrame6Item21Count	table	framexml
+ContainerFrame6Item21IconTexture	table	framexml
+ContainerFrame6Item21NormalTexture	table	framexml
+ContainerFrame6Item21Stock	table	framexml
+ContainerFrame6Item22	table	framexml
+ContainerFrame6Item22Cooldown	table	framexml
+ContainerFrame6Item22Count	table	framexml
+ContainerFrame6Item22IconTexture	table	framexml
+ContainerFrame6Item22NormalTexture	table	framexml
+ContainerFrame6Item22Stock	table	framexml
+ContainerFrame6Item23	table	framexml
+ContainerFrame6Item23Cooldown	table	framexml
+ContainerFrame6Item23Count	table	framexml
+ContainerFrame6Item23IconTexture	table	framexml
+ContainerFrame6Item23NormalTexture	table	framexml
+ContainerFrame6Item23Stock	table	framexml
+ContainerFrame6Item24	table	framexml
+ContainerFrame6Item24Cooldown	table	framexml
+ContainerFrame6Item24Count	table	framexml
+ContainerFrame6Item24IconTexture	table	framexml
+ContainerFrame6Item24NormalTexture	table	framexml
+ContainerFrame6Item24Stock	table	framexml
+ContainerFrame6Item25	table	framexml
+ContainerFrame6Item25Cooldown	table	framexml
+ContainerFrame6Item25Count	table	framexml
+ContainerFrame6Item25IconTexture	table	framexml
+ContainerFrame6Item25NormalTexture	table	framexml
+ContainerFrame6Item25Stock	table	framexml
+ContainerFrame6Item26	table	framexml
+ContainerFrame6Item26Cooldown	table	framexml
+ContainerFrame6Item26Count	table	framexml
+ContainerFrame6Item26IconTexture	table	framexml
+ContainerFrame6Item26NormalTexture	table	framexml
+ContainerFrame6Item26Stock	table	framexml
+ContainerFrame6Item27	table	framexml
+ContainerFrame6Item27Cooldown	table	framexml
+ContainerFrame6Item27Count	table	framexml
+ContainerFrame6Item27IconTexture	table	framexml
+ContainerFrame6Item27NormalTexture	table	framexml
+ContainerFrame6Item27Stock	table	framexml
+ContainerFrame6Item28	table	framexml
+ContainerFrame6Item28Cooldown	table	framexml
+ContainerFrame6Item28Count	table	framexml
+ContainerFrame6Item28IconTexture	table	framexml
+ContainerFrame6Item28NormalTexture	table	framexml
+ContainerFrame6Item28Stock	table	framexml
+ContainerFrame6Item29	table	framexml
+ContainerFrame6Item29Cooldown	table	framexml
+ContainerFrame6Item29Count	table	framexml
+ContainerFrame6Item29IconTexture	table	framexml
+ContainerFrame6Item29NormalTexture	table	framexml
+ContainerFrame6Item29Stock	table	framexml
+ContainerFrame6Item2Cooldown	table	framexml
+ContainerFrame6Item2Count	table	framexml
+ContainerFrame6Item2IconTexture	table	framexml
+ContainerFrame6Item2NormalTexture	table	framexml
+ContainerFrame6Item2Stock	table	framexml
+ContainerFrame6Item3	table	framexml
+ContainerFrame6Item30	table	framexml
+ContainerFrame6Item30Cooldown	table	framexml
+ContainerFrame6Item30Count	table	framexml
+ContainerFrame6Item30IconTexture	table	framexml
+ContainerFrame6Item30NormalTexture	table	framexml
+ContainerFrame6Item30Stock	table	framexml
+ContainerFrame6Item31	table	framexml
+ContainerFrame6Item31Cooldown	table	framexml
+ContainerFrame6Item31Count	table	framexml
+ContainerFrame6Item31IconTexture	table	framexml
+ContainerFrame6Item31NormalTexture	table	framexml
+ContainerFrame6Item31Stock	table	framexml
+ContainerFrame6Item32	table	framexml
+ContainerFrame6Item32Cooldown	table	framexml
+ContainerFrame6Item32Count	table	framexml
+ContainerFrame6Item32IconTexture	table	framexml
+ContainerFrame6Item32NormalTexture	table	framexml
+ContainerFrame6Item32Stock	table	framexml
+ContainerFrame6Item33	table	framexml
+ContainerFrame6Item33Cooldown	table	framexml
+ContainerFrame6Item33Count	table	framexml
+ContainerFrame6Item33IconTexture	table	framexml
+ContainerFrame6Item33NormalTexture	table	framexml
+ContainerFrame6Item33Stock	table	framexml
+ContainerFrame6Item34	table	framexml
+ContainerFrame6Item34Cooldown	table	framexml
+ContainerFrame6Item34Count	table	framexml
+ContainerFrame6Item34IconTexture	table	framexml
+ContainerFrame6Item34NormalTexture	table	framexml
+ContainerFrame6Item34Stock	table	framexml
+ContainerFrame6Item35	table	framexml
+ContainerFrame6Item35Cooldown	table	framexml
+ContainerFrame6Item35Count	table	framexml
+ContainerFrame6Item35IconTexture	table	framexml
+ContainerFrame6Item35NormalTexture	table	framexml
+ContainerFrame6Item35Stock	table	framexml
+ContainerFrame6Item36	table	framexml
+ContainerFrame6Item36Cooldown	table	framexml
+ContainerFrame6Item36Count	table	framexml
+ContainerFrame6Item36IconTexture	table	framexml
+ContainerFrame6Item36NormalTexture	table	framexml
+ContainerFrame6Item36Stock	table	framexml
+ContainerFrame6Item3Cooldown	table	framexml
+ContainerFrame6Item3Count	table	framexml
+ContainerFrame6Item3IconTexture	table	framexml
+ContainerFrame6Item3NormalTexture	table	framexml
+ContainerFrame6Item3Stock	table	framexml
+ContainerFrame6Item4	table	framexml
+ContainerFrame6Item4Cooldown	table	framexml
+ContainerFrame6Item4Count	table	framexml
+ContainerFrame6Item4IconTexture	table	framexml
+ContainerFrame6Item4NormalTexture	table	framexml
+ContainerFrame6Item4Stock	table	framexml
+ContainerFrame6Item5	table	framexml
+ContainerFrame6Item5Cooldown	table	framexml
+ContainerFrame6Item5Count	table	framexml
+ContainerFrame6Item5IconTexture	table	framexml
+ContainerFrame6Item5NormalTexture	table	framexml
+ContainerFrame6Item5Stock	table	framexml
+ContainerFrame6Item6	table	framexml
+ContainerFrame6Item6Cooldown	table	framexml
+ContainerFrame6Item6Count	table	framexml
+ContainerFrame6Item6IconTexture	table	framexml
+ContainerFrame6Item6NormalTexture	table	framexml
+ContainerFrame6Item6Stock	table	framexml
+ContainerFrame6Item7	table	framexml
+ContainerFrame6Item7Cooldown	table	framexml
+ContainerFrame6Item7Count	table	framexml
+ContainerFrame6Item7IconTexture	table	framexml
+ContainerFrame6Item7NormalTexture	table	framexml
+ContainerFrame6Item7Stock	table	framexml
+ContainerFrame6Item8	table	framexml
+ContainerFrame6Item8Cooldown	table	framexml
+ContainerFrame6Item8Count	table	framexml
+ContainerFrame6Item8IconTexture	table	framexml
+ContainerFrame6Item8NormalTexture	table	framexml
+ContainerFrame6Item8Stock	table	framexml
+ContainerFrame6Item9	table	framexml
+ContainerFrame6Item9Cooldown	table	framexml
+ContainerFrame6Item9Count	table	framexml
+ContainerFrame6Item9IconTexture	table	framexml
+ContainerFrame6Item9NormalTexture	table	framexml
+ContainerFrame6Item9Stock	table	framexml
+ContainerFrame6MoneyFrame	table	framexml
+ContainerFrame6MoneyFrameCopperButton	table	framexml
+ContainerFrame6MoneyFrameCopperButtonText	table	framexml
+ContainerFrame6MoneyFrameGoldButton	table	framexml
+ContainerFrame6MoneyFrameGoldButtonText	table	framexml
+ContainerFrame6MoneyFrameSilverButton	table	framexml
+ContainerFrame6MoneyFrameSilverButtonText	table	framexml
+ContainerFrame6Name	table	framexml
+ContainerFrame6Portrait	table	framexml
+ContainerFrame6PortraitButton	table	framexml
+ContainerFrame7	table	framexml
+ContainerFrame7BackgroundBottom	table	framexml
+ContainerFrame7BackgroundMiddle1	table	framexml
+ContainerFrame7BackgroundMiddle2	table	framexml
+ContainerFrame7BackgroundTop	table	framexml
+ContainerFrame7CloseButton	table	framexml
+ContainerFrame7Item1	table	framexml
+ContainerFrame7Item10	table	framexml
+ContainerFrame7Item10Cooldown	table	framexml
+ContainerFrame7Item10Count	table	framexml
+ContainerFrame7Item10IconTexture	table	framexml
+ContainerFrame7Item10NormalTexture	table	framexml
+ContainerFrame7Item10Stock	table	framexml
+ContainerFrame7Item11	table	framexml
+ContainerFrame7Item11Cooldown	table	framexml
+ContainerFrame7Item11Count	table	framexml
+ContainerFrame7Item11IconTexture	table	framexml
+ContainerFrame7Item11NormalTexture	table	framexml
+ContainerFrame7Item11Stock	table	framexml
+ContainerFrame7Item12	table	framexml
+ContainerFrame7Item12Cooldown	table	framexml
+ContainerFrame7Item12Count	table	framexml
+ContainerFrame7Item12IconTexture	table	framexml
+ContainerFrame7Item12NormalTexture	table	framexml
+ContainerFrame7Item12Stock	table	framexml
+ContainerFrame7Item13	table	framexml
+ContainerFrame7Item13Cooldown	table	framexml
+ContainerFrame7Item13Count	table	framexml
+ContainerFrame7Item13IconTexture	table	framexml
+ContainerFrame7Item13NormalTexture	table	framexml
+ContainerFrame7Item13Stock	table	framexml
+ContainerFrame7Item14	table	framexml
+ContainerFrame7Item14Cooldown	table	framexml
+ContainerFrame7Item14Count	table	framexml
+ContainerFrame7Item14IconTexture	table	framexml
+ContainerFrame7Item14NormalTexture	table	framexml
+ContainerFrame7Item14Stock	table	framexml
+ContainerFrame7Item15	table	framexml
+ContainerFrame7Item15Cooldown	table	framexml
+ContainerFrame7Item15Count	table	framexml
+ContainerFrame7Item15IconTexture	table	framexml
+ContainerFrame7Item15NormalTexture	table	framexml
+ContainerFrame7Item15Stock	table	framexml
+ContainerFrame7Item16	table	framexml
+ContainerFrame7Item16Cooldown	table	framexml
+ContainerFrame7Item16Count	table	framexml
+ContainerFrame7Item16IconTexture	table	framexml
+ContainerFrame7Item16NormalTexture	table	framexml
+ContainerFrame7Item16Stock	table	framexml
+ContainerFrame7Item17	table	framexml
+ContainerFrame7Item17Cooldown	table	framexml
+ContainerFrame7Item17Count	table	framexml
+ContainerFrame7Item17IconTexture	table	framexml
+ContainerFrame7Item17NormalTexture	table	framexml
+ContainerFrame7Item17Stock	table	framexml
+ContainerFrame7Item18	table	framexml
+ContainerFrame7Item18Cooldown	table	framexml
+ContainerFrame7Item18Count	table	framexml
+ContainerFrame7Item18IconTexture	table	framexml
+ContainerFrame7Item18NormalTexture	table	framexml
+ContainerFrame7Item18Stock	table	framexml
+ContainerFrame7Item19	table	framexml
+ContainerFrame7Item19Cooldown	table	framexml
+ContainerFrame7Item19Count	table	framexml
+ContainerFrame7Item19IconTexture	table	framexml
+ContainerFrame7Item19NormalTexture	table	framexml
+ContainerFrame7Item19Stock	table	framexml
+ContainerFrame7Item1Cooldown	table	framexml
+ContainerFrame7Item1Count	table	framexml
+ContainerFrame7Item1IconTexture	table	framexml
+ContainerFrame7Item1NormalTexture	table	framexml
+ContainerFrame7Item1Stock	table	framexml
+ContainerFrame7Item2	table	framexml
+ContainerFrame7Item20	table	framexml
+ContainerFrame7Item20Cooldown	table	framexml
+ContainerFrame7Item20Count	table	framexml
+ContainerFrame7Item20IconTexture	table	framexml
+ContainerFrame7Item20NormalTexture	table	framexml
+ContainerFrame7Item20Stock	table	framexml
+ContainerFrame7Item21	table	framexml
+ContainerFrame7Item21Cooldown	table	framexml
+ContainerFrame7Item21Count	table	framexml
+ContainerFrame7Item21IconTexture	table	framexml
+ContainerFrame7Item21NormalTexture	table	framexml
+ContainerFrame7Item21Stock	table	framexml
+ContainerFrame7Item22	table	framexml
+ContainerFrame7Item22Cooldown	table	framexml
+ContainerFrame7Item22Count	table	framexml
+ContainerFrame7Item22IconTexture	table	framexml
+ContainerFrame7Item22NormalTexture	table	framexml
+ContainerFrame7Item22Stock	table	framexml
+ContainerFrame7Item23	table	framexml
+ContainerFrame7Item23Cooldown	table	framexml
+ContainerFrame7Item23Count	table	framexml
+ContainerFrame7Item23IconTexture	table	framexml
+ContainerFrame7Item23NormalTexture	table	framexml
+ContainerFrame7Item23Stock	table	framexml
+ContainerFrame7Item24	table	framexml
+ContainerFrame7Item24Cooldown	table	framexml
+ContainerFrame7Item24Count	table	framexml
+ContainerFrame7Item24IconTexture	table	framexml
+ContainerFrame7Item24NormalTexture	table	framexml
+ContainerFrame7Item24Stock	table	framexml
+ContainerFrame7Item25	table	framexml
+ContainerFrame7Item25Cooldown	table	framexml
+ContainerFrame7Item25Count	table	framexml
+ContainerFrame7Item25IconTexture	table	framexml
+ContainerFrame7Item25NormalTexture	table	framexml
+ContainerFrame7Item25Stock	table	framexml
+ContainerFrame7Item26	table	framexml
+ContainerFrame7Item26Cooldown	table	framexml
+ContainerFrame7Item26Count	table	framexml
+ContainerFrame7Item26IconTexture	table	framexml
+ContainerFrame7Item26NormalTexture	table	framexml
+ContainerFrame7Item26Stock	table	framexml
+ContainerFrame7Item27	table	framexml
+ContainerFrame7Item27Cooldown	table	framexml
+ContainerFrame7Item27Count	table	framexml
+ContainerFrame7Item27IconTexture	table	framexml
+ContainerFrame7Item27NormalTexture	table	framexml
+ContainerFrame7Item27Stock	table	framexml
+ContainerFrame7Item28	table	framexml
+ContainerFrame7Item28Cooldown	table	framexml
+ContainerFrame7Item28Count	table	framexml
+ContainerFrame7Item28IconTexture	table	framexml
+ContainerFrame7Item28NormalTexture	table	framexml
+ContainerFrame7Item28Stock	table	framexml
+ContainerFrame7Item29	table	framexml
+ContainerFrame7Item29Cooldown	table	framexml
+ContainerFrame7Item29Count	table	framexml
+ContainerFrame7Item29IconTexture	table	framexml
+ContainerFrame7Item29NormalTexture	table	framexml
+ContainerFrame7Item29Stock	table	framexml
+ContainerFrame7Item2Cooldown	table	framexml
+ContainerFrame7Item2Count	table	framexml
+ContainerFrame7Item2IconTexture	table	framexml
+ContainerFrame7Item2NormalTexture	table	framexml
+ContainerFrame7Item2Stock	table	framexml
+ContainerFrame7Item3	table	framexml
+ContainerFrame7Item30	table	framexml
+ContainerFrame7Item30Cooldown	table	framexml
+ContainerFrame7Item30Count	table	framexml
+ContainerFrame7Item30IconTexture	table	framexml
+ContainerFrame7Item30NormalTexture	table	framexml
+ContainerFrame7Item30Stock	table	framexml
+ContainerFrame7Item31	table	framexml
+ContainerFrame7Item31Cooldown	table	framexml
+ContainerFrame7Item31Count	table	framexml
+ContainerFrame7Item31IconTexture	table	framexml
+ContainerFrame7Item31NormalTexture	table	framexml
+ContainerFrame7Item31Stock	table	framexml
+ContainerFrame7Item32	table	framexml
+ContainerFrame7Item32Cooldown	table	framexml
+ContainerFrame7Item32Count	table	framexml
+ContainerFrame7Item32IconTexture	table	framexml
+ContainerFrame7Item32NormalTexture	table	framexml
+ContainerFrame7Item32Stock	table	framexml
+ContainerFrame7Item33	table	framexml
+ContainerFrame7Item33Cooldown	table	framexml
+ContainerFrame7Item33Count	table	framexml
+ContainerFrame7Item33IconTexture	table	framexml
+ContainerFrame7Item33NormalTexture	table	framexml
+ContainerFrame7Item33Stock	table	framexml
+ContainerFrame7Item34	table	framexml
+ContainerFrame7Item34Cooldown	table	framexml
+ContainerFrame7Item34Count	table	framexml
+ContainerFrame7Item34IconTexture	table	framexml
+ContainerFrame7Item34NormalTexture	table	framexml
+ContainerFrame7Item34Stock	table	framexml
+ContainerFrame7Item35	table	framexml
+ContainerFrame7Item35Cooldown	table	framexml
+ContainerFrame7Item35Count	table	framexml
+ContainerFrame7Item35IconTexture	table	framexml
+ContainerFrame7Item35NormalTexture	table	framexml
+ContainerFrame7Item35Stock	table	framexml
+ContainerFrame7Item36	table	framexml
+ContainerFrame7Item36Cooldown	table	framexml
+ContainerFrame7Item36Count	table	framexml
+ContainerFrame7Item36IconTexture	table	framexml
+ContainerFrame7Item36NormalTexture	table	framexml
+ContainerFrame7Item36Stock	table	framexml
+ContainerFrame7Item3Cooldown	table	framexml
+ContainerFrame7Item3Count	table	framexml
+ContainerFrame7Item3IconTexture	table	framexml
+ContainerFrame7Item3NormalTexture	table	framexml
+ContainerFrame7Item3Stock	table	framexml
+ContainerFrame7Item4	table	framexml
+ContainerFrame7Item4Cooldown	table	framexml
+ContainerFrame7Item4Count	table	framexml
+ContainerFrame7Item4IconTexture	table	framexml
+ContainerFrame7Item4NormalTexture	table	framexml
+ContainerFrame7Item4Stock	table	framexml
+ContainerFrame7Item5	table	framexml
+ContainerFrame7Item5Cooldown	table	framexml
+ContainerFrame7Item5Count	table	framexml
+ContainerFrame7Item5IconTexture	table	framexml
+ContainerFrame7Item5NormalTexture	table	framexml
+ContainerFrame7Item5Stock	table	framexml
+ContainerFrame7Item6	table	framexml
+ContainerFrame7Item6Cooldown	table	framexml
+ContainerFrame7Item6Count	table	framexml
+ContainerFrame7Item6IconTexture	table	framexml
+ContainerFrame7Item6NormalTexture	table	framexml
+ContainerFrame7Item6Stock	table	framexml
+ContainerFrame7Item7	table	framexml
+ContainerFrame7Item7Cooldown	table	framexml
+ContainerFrame7Item7Count	table	framexml
+ContainerFrame7Item7IconTexture	table	framexml
+ContainerFrame7Item7NormalTexture	table	framexml
+ContainerFrame7Item7Stock	table	framexml
+ContainerFrame7Item8	table	framexml
+ContainerFrame7Item8Cooldown	table	framexml
+ContainerFrame7Item8Count	table	framexml
+ContainerFrame7Item8IconTexture	table	framexml
+ContainerFrame7Item8NormalTexture	table	framexml
+ContainerFrame7Item8Stock	table	framexml
+ContainerFrame7Item9	table	framexml
+ContainerFrame7Item9Cooldown	table	framexml
+ContainerFrame7Item9Count	table	framexml
+ContainerFrame7Item9IconTexture	table	framexml
+ContainerFrame7Item9NormalTexture	table	framexml
+ContainerFrame7Item9Stock	table	framexml
+ContainerFrame7MoneyFrame	table	framexml
+ContainerFrame7MoneyFrameCopperButton	table	framexml
+ContainerFrame7MoneyFrameCopperButtonText	table	framexml
+ContainerFrame7MoneyFrameGoldButton	table	framexml
+ContainerFrame7MoneyFrameGoldButtonText	table	framexml
+ContainerFrame7MoneyFrameSilverButton	table	framexml
+ContainerFrame7MoneyFrameSilverButtonText	table	framexml
+ContainerFrame7Name	table	framexml
+ContainerFrame7Portrait	table	framexml
+ContainerFrame7PortraitButton	table	framexml
+ContainerFrame8	table	framexml
+ContainerFrame8BackgroundBottom	table	framexml
+ContainerFrame8BackgroundMiddle1	table	framexml
+ContainerFrame8BackgroundMiddle2	table	framexml
+ContainerFrame8BackgroundTop	table	framexml
+ContainerFrame8CloseButton	table	framexml
+ContainerFrame8Item1	table	framexml
+ContainerFrame8Item10	table	framexml
+ContainerFrame8Item10Cooldown	table	framexml
+ContainerFrame8Item10Count	table	framexml
+ContainerFrame8Item10IconTexture	table	framexml
+ContainerFrame8Item10NormalTexture	table	framexml
+ContainerFrame8Item10Stock	table	framexml
+ContainerFrame8Item11	table	framexml
+ContainerFrame8Item11Cooldown	table	framexml
+ContainerFrame8Item11Count	table	framexml
+ContainerFrame8Item11IconTexture	table	framexml
+ContainerFrame8Item11NormalTexture	table	framexml
+ContainerFrame8Item11Stock	table	framexml
+ContainerFrame8Item12	table	framexml
+ContainerFrame8Item12Cooldown	table	framexml
+ContainerFrame8Item12Count	table	framexml
+ContainerFrame8Item12IconTexture	table	framexml
+ContainerFrame8Item12NormalTexture	table	framexml
+ContainerFrame8Item12Stock	table	framexml
+ContainerFrame8Item13	table	framexml
+ContainerFrame8Item13Cooldown	table	framexml
+ContainerFrame8Item13Count	table	framexml
+ContainerFrame8Item13IconTexture	table	framexml
+ContainerFrame8Item13NormalTexture	table	framexml
+ContainerFrame8Item13Stock	table	framexml
+ContainerFrame8Item14	table	framexml
+ContainerFrame8Item14Cooldown	table	framexml
+ContainerFrame8Item14Count	table	framexml
+ContainerFrame8Item14IconTexture	table	framexml
+ContainerFrame8Item14NormalTexture	table	framexml
+ContainerFrame8Item14Stock	table	framexml
+ContainerFrame8Item15	table	framexml
+ContainerFrame8Item15Cooldown	table	framexml
+ContainerFrame8Item15Count	table	framexml
+ContainerFrame8Item15IconTexture	table	framexml
+ContainerFrame8Item15NormalTexture	table	framexml
+ContainerFrame8Item15Stock	table	framexml
+ContainerFrame8Item16	table	framexml
+ContainerFrame8Item16Cooldown	table	framexml
+ContainerFrame8Item16Count	table	framexml
+ContainerFrame8Item16IconTexture	table	framexml
+ContainerFrame8Item16NormalTexture	table	framexml
+ContainerFrame8Item16Stock	table	framexml
+ContainerFrame8Item17	table	framexml
+ContainerFrame8Item17Cooldown	table	framexml
+ContainerFrame8Item17Count	table	framexml
+ContainerFrame8Item17IconTexture	table	framexml
+ContainerFrame8Item17NormalTexture	table	framexml
+ContainerFrame8Item17Stock	table	framexml
+ContainerFrame8Item18	table	framexml
+ContainerFrame8Item18Cooldown	table	framexml
+ContainerFrame8Item18Count	table	framexml
+ContainerFrame8Item18IconTexture	table	framexml
+ContainerFrame8Item18NormalTexture	table	framexml
+ContainerFrame8Item18Stock	table	framexml
+ContainerFrame8Item19	table	framexml
+ContainerFrame8Item19Cooldown	table	framexml
+ContainerFrame8Item19Count	table	framexml
+ContainerFrame8Item19IconTexture	table	framexml
+ContainerFrame8Item19NormalTexture	table	framexml
+ContainerFrame8Item19Stock	table	framexml
+ContainerFrame8Item1Cooldown	table	framexml
+ContainerFrame8Item1Count	table	framexml
+ContainerFrame8Item1IconTexture	table	framexml
+ContainerFrame8Item1NormalTexture	table	framexml
+ContainerFrame8Item1Stock	table	framexml
+ContainerFrame8Item2	table	framexml
+ContainerFrame8Item20	table	framexml
+ContainerFrame8Item20Cooldown	table	framexml
+ContainerFrame8Item20Count	table	framexml
+ContainerFrame8Item20IconTexture	table	framexml
+ContainerFrame8Item20NormalTexture	table	framexml
+ContainerFrame8Item20Stock	table	framexml
+ContainerFrame8Item21	table	framexml
+ContainerFrame8Item21Cooldown	table	framexml
+ContainerFrame8Item21Count	table	framexml
+ContainerFrame8Item21IconTexture	table	framexml
+ContainerFrame8Item21NormalTexture	table	framexml
+ContainerFrame8Item21Stock	table	framexml
+ContainerFrame8Item22	table	framexml
+ContainerFrame8Item22Cooldown	table	framexml
+ContainerFrame8Item22Count	table	framexml
+ContainerFrame8Item22IconTexture	table	framexml
+ContainerFrame8Item22NormalTexture	table	framexml
+ContainerFrame8Item22Stock	table	framexml
+ContainerFrame8Item23	table	framexml
+ContainerFrame8Item23Cooldown	table	framexml
+ContainerFrame8Item23Count	table	framexml
+ContainerFrame8Item23IconTexture	table	framexml
+ContainerFrame8Item23NormalTexture	table	framexml
+ContainerFrame8Item23Stock	table	framexml
+ContainerFrame8Item24	table	framexml
+ContainerFrame8Item24Cooldown	table	framexml
+ContainerFrame8Item24Count	table	framexml
+ContainerFrame8Item24IconTexture	table	framexml
+ContainerFrame8Item24NormalTexture	table	framexml
+ContainerFrame8Item24Stock	table	framexml
+ContainerFrame8Item25	table	framexml
+ContainerFrame8Item25Cooldown	table	framexml
+ContainerFrame8Item25Count	table	framexml
+ContainerFrame8Item25IconTexture	table	framexml
+ContainerFrame8Item25NormalTexture	table	framexml
+ContainerFrame8Item25Stock	table	framexml
+ContainerFrame8Item26	table	framexml
+ContainerFrame8Item26Cooldown	table	framexml
+ContainerFrame8Item26Count	table	framexml
+ContainerFrame8Item26IconTexture	table	framexml
+ContainerFrame8Item26NormalTexture	table	framexml
+ContainerFrame8Item26Stock	table	framexml
+ContainerFrame8Item27	table	framexml
+ContainerFrame8Item27Cooldown	table	framexml
+ContainerFrame8Item27Count	table	framexml
+ContainerFrame8Item27IconTexture	table	framexml
+ContainerFrame8Item27NormalTexture	table	framexml
+ContainerFrame8Item27Stock	table	framexml
+ContainerFrame8Item28	table	framexml
+ContainerFrame8Item28Cooldown	table	framexml
+ContainerFrame8Item28Count	table	framexml
+ContainerFrame8Item28IconTexture	table	framexml
+ContainerFrame8Item28NormalTexture	table	framexml
+ContainerFrame8Item28Stock	table	framexml
+ContainerFrame8Item29	table	framexml
+ContainerFrame8Item29Cooldown	table	framexml
+ContainerFrame8Item29Count	table	framexml
+ContainerFrame8Item29IconTexture	table	framexml
+ContainerFrame8Item29NormalTexture	table	framexml
+ContainerFrame8Item29Stock	table	framexml
+ContainerFrame8Item2Cooldown	table	framexml
+ContainerFrame8Item2Count	table	framexml
+ContainerFrame8Item2IconTexture	table	framexml
+ContainerFrame8Item2NormalTexture	table	framexml
+ContainerFrame8Item2Stock	table	framexml
+ContainerFrame8Item3	table	framexml
+ContainerFrame8Item30	table	framexml
+ContainerFrame8Item30Cooldown	table	framexml
+ContainerFrame8Item30Count	table	framexml
+ContainerFrame8Item30IconTexture	table	framexml
+ContainerFrame8Item30NormalTexture	table	framexml
+ContainerFrame8Item30Stock	table	framexml
+ContainerFrame8Item31	table	framexml
+ContainerFrame8Item31Cooldown	table	framexml
+ContainerFrame8Item31Count	table	framexml
+ContainerFrame8Item31IconTexture	table	framexml
+ContainerFrame8Item31NormalTexture	table	framexml
+ContainerFrame8Item31Stock	table	framexml
+ContainerFrame8Item32	table	framexml
+ContainerFrame8Item32Cooldown	table	framexml
+ContainerFrame8Item32Count	table	framexml
+ContainerFrame8Item32IconTexture	table	framexml
+ContainerFrame8Item32NormalTexture	table	framexml
+ContainerFrame8Item32Stock	table	framexml
+ContainerFrame8Item33	table	framexml
+ContainerFrame8Item33Cooldown	table	framexml
+ContainerFrame8Item33Count	table	framexml
+ContainerFrame8Item33IconTexture	table	framexml
+ContainerFrame8Item33NormalTexture	table	framexml
+ContainerFrame8Item33Stock	table	framexml
+ContainerFrame8Item34	table	framexml
+ContainerFrame8Item34Cooldown	table	framexml
+ContainerFrame8Item34Count	table	framexml
+ContainerFrame8Item34IconTexture	table	framexml
+ContainerFrame8Item34NormalTexture	table	framexml
+ContainerFrame8Item34Stock	table	framexml
+ContainerFrame8Item35	table	framexml
+ContainerFrame8Item35Cooldown	table	framexml
+ContainerFrame8Item35Count	table	framexml
+ContainerFrame8Item35IconTexture	table	framexml
+ContainerFrame8Item35NormalTexture	table	framexml
+ContainerFrame8Item35Stock	table	framexml
+ContainerFrame8Item36	table	framexml
+ContainerFrame8Item36Cooldown	table	framexml
+ContainerFrame8Item36Count	table	framexml
+ContainerFrame8Item36IconTexture	table	framexml
+ContainerFrame8Item36NormalTexture	table	framexml
+ContainerFrame8Item36Stock	table	framexml
+ContainerFrame8Item3Cooldown	table	framexml
+ContainerFrame8Item3Count	table	framexml
+ContainerFrame8Item3IconTexture	table	framexml
+ContainerFrame8Item3NormalTexture	table	framexml
+ContainerFrame8Item3Stock	table	framexml
+ContainerFrame8Item4	table	framexml
+ContainerFrame8Item4Cooldown	table	framexml
+ContainerFrame8Item4Count	table	framexml
+ContainerFrame8Item4IconTexture	table	framexml
+ContainerFrame8Item4NormalTexture	table	framexml
+ContainerFrame8Item4Stock	table	framexml
+ContainerFrame8Item5	table	framexml
+ContainerFrame8Item5Cooldown	table	framexml
+ContainerFrame8Item5Count	table	framexml
+ContainerFrame8Item5IconTexture	table	framexml
+ContainerFrame8Item5NormalTexture	table	framexml
+ContainerFrame8Item5Stock	table	framexml
+ContainerFrame8Item6	table	framexml
+ContainerFrame8Item6Cooldown	table	framexml
+ContainerFrame8Item6Count	table	framexml
+ContainerFrame8Item6IconTexture	table	framexml
+ContainerFrame8Item6NormalTexture	table	framexml
+ContainerFrame8Item6Stock	table	framexml
+ContainerFrame8Item7	table	framexml
+ContainerFrame8Item7Cooldown	table	framexml
+ContainerFrame8Item7Count	table	framexml
+ContainerFrame8Item7IconTexture	table	framexml
+ContainerFrame8Item7NormalTexture	table	framexml
+ContainerFrame8Item7Stock	table	framexml
+ContainerFrame8Item8	table	framexml
+ContainerFrame8Item8Cooldown	table	framexml
+ContainerFrame8Item8Count	table	framexml
+ContainerFrame8Item8IconTexture	table	framexml
+ContainerFrame8Item8NormalTexture	table	framexml
+ContainerFrame8Item8Stock	table	framexml
+ContainerFrame8Item9	table	framexml
+ContainerFrame8Item9Cooldown	table	framexml
+ContainerFrame8Item9Count	table	framexml
+ContainerFrame8Item9IconTexture	table	framexml
+ContainerFrame8Item9NormalTexture	table	framexml
+ContainerFrame8Item9Stock	table	framexml
+ContainerFrame8MoneyFrame	table	framexml
+ContainerFrame8MoneyFrameCopperButton	table	framexml
+ContainerFrame8MoneyFrameCopperButtonText	table	framexml
+ContainerFrame8MoneyFrameGoldButton	table	framexml
+ContainerFrame8MoneyFrameGoldButtonText	table	framexml
+ContainerFrame8MoneyFrameSilverButton	table	framexml
+ContainerFrame8MoneyFrameSilverButtonText	table	framexml
+ContainerFrame8Name	table	framexml
+ContainerFrame8Portrait	table	framexml
+ContainerFrame8PortraitButton	table	framexml
+ContainerFrame9	table	framexml
+ContainerFrame9BackgroundBottom	table	framexml
+ContainerFrame9BackgroundMiddle1	table	framexml
+ContainerFrame9BackgroundMiddle2	table	framexml
+ContainerFrame9BackgroundTop	table	framexml
+ContainerFrame9CloseButton	table	framexml
+ContainerFrame9Item1	table	framexml
+ContainerFrame9Item10	table	framexml
+ContainerFrame9Item10Cooldown	table	framexml
+ContainerFrame9Item10Count	table	framexml
+ContainerFrame9Item10IconTexture	table	framexml
+ContainerFrame9Item10NormalTexture	table	framexml
+ContainerFrame9Item10Stock	table	framexml
+ContainerFrame9Item11	table	framexml
+ContainerFrame9Item11Cooldown	table	framexml
+ContainerFrame9Item11Count	table	framexml
+ContainerFrame9Item11IconTexture	table	framexml
+ContainerFrame9Item11NormalTexture	table	framexml
+ContainerFrame9Item11Stock	table	framexml
+ContainerFrame9Item12	table	framexml
+ContainerFrame9Item12Cooldown	table	framexml
+ContainerFrame9Item12Count	table	framexml
+ContainerFrame9Item12IconTexture	table	framexml
+ContainerFrame9Item12NormalTexture	table	framexml
+ContainerFrame9Item12Stock	table	framexml
+ContainerFrame9Item13	table	framexml
+ContainerFrame9Item13Cooldown	table	framexml
+ContainerFrame9Item13Count	table	framexml
+ContainerFrame9Item13IconTexture	table	framexml
+ContainerFrame9Item13NormalTexture	table	framexml
+ContainerFrame9Item13Stock	table	framexml
+ContainerFrame9Item14	table	framexml
+ContainerFrame9Item14Cooldown	table	framexml
+ContainerFrame9Item14Count	table	framexml
+ContainerFrame9Item14IconTexture	table	framexml
+ContainerFrame9Item14NormalTexture	table	framexml
+ContainerFrame9Item14Stock	table	framexml
+ContainerFrame9Item15	table	framexml
+ContainerFrame9Item15Cooldown	table	framexml
+ContainerFrame9Item15Count	table	framexml
+ContainerFrame9Item15IconTexture	table	framexml
+ContainerFrame9Item15NormalTexture	table	framexml
+ContainerFrame9Item15Stock	table	framexml
+ContainerFrame9Item16	table	framexml
+ContainerFrame9Item16Cooldown	table	framexml
+ContainerFrame9Item16Count	table	framexml
+ContainerFrame9Item16IconTexture	table	framexml
+ContainerFrame9Item16NormalTexture	table	framexml
+ContainerFrame9Item16Stock	table	framexml
+ContainerFrame9Item17	table	framexml
+ContainerFrame9Item17Cooldown	table	framexml
+ContainerFrame9Item17Count	table	framexml
+ContainerFrame9Item17IconTexture	table	framexml
+ContainerFrame9Item17NormalTexture	table	framexml
+ContainerFrame9Item17Stock	table	framexml
+ContainerFrame9Item18	table	framexml
+ContainerFrame9Item18Cooldown	table	framexml
+ContainerFrame9Item18Count	table	framexml
+ContainerFrame9Item18IconTexture	table	framexml
+ContainerFrame9Item18NormalTexture	table	framexml
+ContainerFrame9Item18Stock	table	framexml
+ContainerFrame9Item19	table	framexml
+ContainerFrame9Item19Cooldown	table	framexml
+ContainerFrame9Item19Count	table	framexml
+ContainerFrame9Item19IconTexture	table	framexml
+ContainerFrame9Item19NormalTexture	table	framexml
+ContainerFrame9Item19Stock	table	framexml
+ContainerFrame9Item1Cooldown	table	framexml
+ContainerFrame9Item1Count	table	framexml
+ContainerFrame9Item1IconTexture	table	framexml
+ContainerFrame9Item1NormalTexture	table	framexml
+ContainerFrame9Item1Stock	table	framexml
+ContainerFrame9Item2	table	framexml
+ContainerFrame9Item20	table	framexml
+ContainerFrame9Item20Cooldown	table	framexml
+ContainerFrame9Item20Count	table	framexml
+ContainerFrame9Item20IconTexture	table	framexml
+ContainerFrame9Item20NormalTexture	table	framexml
+ContainerFrame9Item20Stock	table	framexml
+ContainerFrame9Item21	table	framexml
+ContainerFrame9Item21Cooldown	table	framexml
+ContainerFrame9Item21Count	table	framexml
+ContainerFrame9Item21IconTexture	table	framexml
+ContainerFrame9Item21NormalTexture	table	framexml
+ContainerFrame9Item21Stock	table	framexml
+ContainerFrame9Item22	table	framexml
+ContainerFrame9Item22Cooldown	table	framexml
+ContainerFrame9Item22Count	table	framexml
+ContainerFrame9Item22IconTexture	table	framexml
+ContainerFrame9Item22NormalTexture	table	framexml
+ContainerFrame9Item22Stock	table	framexml
+ContainerFrame9Item23	table	framexml
+ContainerFrame9Item23Cooldown	table	framexml
+ContainerFrame9Item23Count	table	framexml
+ContainerFrame9Item23IconTexture	table	framexml
+ContainerFrame9Item23NormalTexture	table	framexml
+ContainerFrame9Item23Stock	table	framexml
+ContainerFrame9Item24	table	framexml
+ContainerFrame9Item24Cooldown	table	framexml
+ContainerFrame9Item24Count	table	framexml
+ContainerFrame9Item24IconTexture	table	framexml
+ContainerFrame9Item24NormalTexture	table	framexml
+ContainerFrame9Item24Stock	table	framexml
+ContainerFrame9Item25	table	framexml
+ContainerFrame9Item25Cooldown	table	framexml
+ContainerFrame9Item25Count	table	framexml
+ContainerFrame9Item25IconTexture	table	framexml
+ContainerFrame9Item25NormalTexture	table	framexml
+ContainerFrame9Item25Stock	table	framexml
+ContainerFrame9Item26	table	framexml
+ContainerFrame9Item26Cooldown	table	framexml
+ContainerFrame9Item26Count	table	framexml
+ContainerFrame9Item26IconTexture	table	framexml
+ContainerFrame9Item26NormalTexture	table	framexml
+ContainerFrame9Item26Stock	table	framexml
+ContainerFrame9Item27	table	framexml
+ContainerFrame9Item27Cooldown	table	framexml
+ContainerFrame9Item27Count	table	framexml
+ContainerFrame9Item27IconTexture	table	framexml
+ContainerFrame9Item27NormalTexture	table	framexml
+ContainerFrame9Item27Stock	table	framexml
+ContainerFrame9Item28	table	framexml
+ContainerFrame9Item28Cooldown	table	framexml
+ContainerFrame9Item28Count	table	framexml
+ContainerFrame9Item28IconTexture	table	framexml
+ContainerFrame9Item28NormalTexture	table	framexml
+ContainerFrame9Item28Stock	table	framexml
+ContainerFrame9Item29	table	framexml
+ContainerFrame9Item29Cooldown	table	framexml
+ContainerFrame9Item29Count	table	framexml
+ContainerFrame9Item29IconTexture	table	framexml
+ContainerFrame9Item29NormalTexture	table	framexml
+ContainerFrame9Item29Stock	table	framexml
+ContainerFrame9Item2Cooldown	table	framexml
+ContainerFrame9Item2Count	table	framexml
+ContainerFrame9Item2IconTexture	table	framexml
+ContainerFrame9Item2NormalTexture	table	framexml
+ContainerFrame9Item2Stock	table	framexml
+ContainerFrame9Item3	table	framexml
+ContainerFrame9Item30	table	framexml
+ContainerFrame9Item30Cooldown	table	framexml
+ContainerFrame9Item30Count	table	framexml
+ContainerFrame9Item30IconTexture	table	framexml
+ContainerFrame9Item30NormalTexture	table	framexml
+ContainerFrame9Item30Stock	table	framexml
+ContainerFrame9Item31	table	framexml
+ContainerFrame9Item31Cooldown	table	framexml
+ContainerFrame9Item31Count	table	framexml
+ContainerFrame9Item31IconTexture	table	framexml
+ContainerFrame9Item31NormalTexture	table	framexml
+ContainerFrame9Item31Stock	table	framexml
+ContainerFrame9Item32	table	framexml
+ContainerFrame9Item32Cooldown	table	framexml
+ContainerFrame9Item32Count	table	framexml
+ContainerFrame9Item32IconTexture	table	framexml
+ContainerFrame9Item32NormalTexture	table	framexml
+ContainerFrame9Item32Stock	table	framexml
+ContainerFrame9Item33	table	framexml
+ContainerFrame9Item33Cooldown	table	framexml
+ContainerFrame9Item33Count	table	framexml
+ContainerFrame9Item33IconTexture	table	framexml
+ContainerFrame9Item33NormalTexture	table	framexml
+ContainerFrame9Item33Stock	table	framexml
+ContainerFrame9Item34	table	framexml
+ContainerFrame9Item34Cooldown	table	framexml
+ContainerFrame9Item34Count	table	framexml
+ContainerFrame9Item34IconTexture	table	framexml
+ContainerFrame9Item34NormalTexture	table	framexml
+ContainerFrame9Item34Stock	table	framexml
+ContainerFrame9Item35	table	framexml
+ContainerFrame9Item35Cooldown	table	framexml
+ContainerFrame9Item35Count	table	framexml
+ContainerFrame9Item35IconTexture	table	framexml
+ContainerFrame9Item35NormalTexture	table	framexml
+ContainerFrame9Item35Stock	table	framexml
+ContainerFrame9Item36	table	framexml
+ContainerFrame9Item36Cooldown	table	framexml
+ContainerFrame9Item36Count	table	framexml
+ContainerFrame9Item36IconTexture	table	framexml
+ContainerFrame9Item36NormalTexture	table	framexml
+ContainerFrame9Item36Stock	table	framexml
+ContainerFrame9Item3Cooldown	table	framexml
+ContainerFrame9Item3Count	table	framexml
+ContainerFrame9Item3IconTexture	table	framexml
+ContainerFrame9Item3NormalTexture	table	framexml
+ContainerFrame9Item3Stock	table	framexml
+ContainerFrame9Item4	table	framexml
+ContainerFrame9Item4Cooldown	table	framexml
+ContainerFrame9Item4Count	table	framexml
+ContainerFrame9Item4IconTexture	table	framexml
+ContainerFrame9Item4NormalTexture	table	framexml
+ContainerFrame9Item4Stock	table	framexml
+ContainerFrame9Item5	table	framexml
+ContainerFrame9Item5Cooldown	table	framexml
+ContainerFrame9Item5Count	table	framexml
+ContainerFrame9Item5IconTexture	table	framexml
+ContainerFrame9Item5NormalTexture	table	framexml
+ContainerFrame9Item5Stock	table	framexml
+ContainerFrame9Item6	table	framexml
+ContainerFrame9Item6Cooldown	table	framexml
+ContainerFrame9Item6Count	table	framexml
+ContainerFrame9Item6IconTexture	table	framexml
+ContainerFrame9Item6NormalTexture	table	framexml
+ContainerFrame9Item6Stock	table	framexml
+ContainerFrame9Item7	table	framexml
+ContainerFrame9Item7Cooldown	table	framexml
+ContainerFrame9Item7Count	table	framexml
+ContainerFrame9Item7IconTexture	table	framexml
+ContainerFrame9Item7NormalTexture	table	framexml
+ContainerFrame9Item7Stock	table	framexml
+ContainerFrame9Item8	table	framexml
+ContainerFrame9Item8Cooldown	table	framexml
+ContainerFrame9Item8Count	table	framexml
+ContainerFrame9Item8IconTexture	table	framexml
+ContainerFrame9Item8NormalTexture	table	framexml
+ContainerFrame9Item8Stock	table	framexml
+ContainerFrame9Item9	table	framexml
+ContainerFrame9Item9Cooldown	table	framexml
+ContainerFrame9Item9Count	table	framexml
+ContainerFrame9Item9IconTexture	table	framexml
+ContainerFrame9Item9NormalTexture	table	framexml
+ContainerFrame9Item9Stock	table	framexml
+ContainerFrame9MoneyFrame	table	framexml
+ContainerFrame9MoneyFrameCopperButton	table	framexml
+ContainerFrame9MoneyFrameCopperButtonText	table	framexml
+ContainerFrame9MoneyFrameGoldButton	table	framexml
+ContainerFrame9MoneyFrameGoldButtonText	table	framexml
+ContainerFrame9MoneyFrameSilverButton	table	framexml
+ContainerFrame9MoneyFrameSilverButtonText	table	framexml
+ContainerFrame9Name	table	framexml
+ContainerFrame9Portrait	table	framexml
+ContainerFrame9PortraitButton	table	framexml
+ContainerFrameItemButtonTemplate	lod	framexml
+ContainerFrameItemButton_OnClick	function	framexml
+ContainerFrameItemButton_OnEnter	function	framexml
+ContainerFrameItemButton_OnLoad	function	framexml
+ContainerFrameItemButton_OnUpdate	function	framexml
+ContainerFrameTemplate	lod	framexml
+ContainerFrame_GenerateFrame	function	framexml
+ContainerFrame_GetOpenFrame	function	framexml
+ContainerFrame_OnEvent	function	framexml
+ContainerFrame_OnHide	function	framexml
+ContainerFrame_OnLoad	function	framexml
+ContainerFrame_OnShow	function	framexml
+ContainerFrame_Update	function	framexml
+ContainerFrame_UpdateCooldown	function	framexml
+ContainerIDToInventoryID	function	engine
+ConvertToRaid	function	engine
+CooldownFrameTemplate	lod	framexml
+CooldownFrame_OnAnimFinished	function	framexml
+CooldownFrame_OnUpdateModel	function	framexml
+CooldownFrame_SetTimer	function	framexml
+Craft1	lod	framexml
+Craft2	lod	framexml
+Craft3	lod	framexml
+Craft4	lod	framexml
+Craft5	lod	framexml
+Craft6	lod	framexml
+Craft7	lod	framexml
+Craft8	lod	framexml
+CraftButtonTemplate	lod	framexml
+CraftButton_OnClick	lod	framexml
+CraftCancelButton	lod	framexml
+CraftCollapseAllButton	lod	framexml
+CraftCollapseAllButton_OnClick	lod	framexml
+CraftCost	lod	framexml
+CraftCreateButton	lod	framexml
+CraftDescription	lod	framexml
+CraftDetailHeaderLeft	lod	framexml
+CraftDetailScrollChildFrame	lod	framexml
+CraftDetailScrollFrame	lod	framexml
+CraftExpandButtonFrame	lod	framexml
+CraftExpandTabLeft	lod	framexml
+CraftExpandTabMiddle	lod	framexml
+CraftExpandTabRight	lod	framexml
+CraftFrame	lod	framexml
+CraftFrameCloseButton	lod	framexml
+CraftFramePointsLabel	lod	framexml
+CraftFramePointsText	lod	framexml
+CraftFramePortrait	lod	framexml
+CraftFrameTitleText	lod	framexml
+CraftFrame_Hide	lod	framexml
+CraftFrame_LoadUI	function	framexml
+CraftFrame_OnEvent	lod	framexml
+CraftFrame_OnLoad	lod	framexml
+CraftFrame_SetSelection	lod	framexml
+CraftFrame_Show	lod	framexml
+CraftFrame_Update	lod	framexml
+CraftHighlight	lod	framexml
+CraftHighlightFrame	lod	framexml
+CraftHorizontalBarLeft	lod	framexml
+CraftIcon	lod	framexml
+CraftItemTemplate	lod	framexml
+CraftListScrollFrame	lod	framexml
+CraftMoneyFrame	lod	framexml
+CraftName	lod	framexml
+CraftRankFrame	lod	framexml
+CraftReagent1	lod	framexml
+CraftReagent2	lod	framexml
+CraftReagent3	lod	framexml
+CraftReagent4	lod	framexml
+CraftReagent5	lod	framexml
+CraftReagent6	lod	framexml
+CraftReagent7	lod	framexml
+CraftReagent8	lod	framexml
+CraftReagentLabel	lod	framexml
+CraftRequirements	lod	framexml
+CraftSkillBorderLeft	lod	framexml
+CraftSkillBorderRight	lod	framexml
+CraftSubTypeColor	lod	framexml
+CraftTypeColor	lod	framexml
+Craft_UpdateTrainingPoints	lod	framexml
+CreateFont	function	engine
+CreateFrame	function	engine
+CreateMacro	function	engine
+CreateMiniWorldMapArrowFrame	function	engine
+CreateWorldMapArrowFrame	function	engine
+CurrentQuestsText	table	framexml
+CursorCanGoInSlot	function	engine
+CursorHasItem	function	engine
+CursorHasMoney	function	engine
+CursorHasSpell	function	engine
+CursorOnUpdate	function	framexml
+CursorUpdate	function	framexml
+DAMAGE	string	framexml
+DAMAGESHIELDOTHEROTHER	string	framexml
+DAMAGESHIELDOTHERSELF	string	framexml
+DAMAGESHIELDSELFOTHER	string	framexml
+DAMAGE_BONUS_TOOLTIP	string	framexml
+DAMAGE_COLON	string	framexml
+DAMAGE_PER_SECOND	string	framexml
+DAMAGE_TEMPLATE	string	framexml
+DAMAGE_TEMPLATE_WITH_SCHOOL	string	framexml
+DAMAGE_TEXT_FONT	string	framexml
+DAMAGE_TOOLTIP	string	framexml
+DAYS	string	framexml
+DAYS_ABBR	string	framexml
+DAYS_ABBR_P1	string	framexml
+DAYS_P1	string	framexml
+DAY_ONELETTER_ABBR	string	framexml
+DEAD	string	framexml
+DEATHBINDALREADYBOUND	string	framexml
+DEATHBIND_SUCCESSFUL	string	framexml
+DEATHS	string	framexml
+DEATHS_TOOLTIP	string	framexml
+DEATH_CORPSE_SKINNED	string	framexml
+DEATH_EFFECT	string	framexml
+DEATH_RELEASE	string	framexml
+DEATH_RELEASE_NOTIMER	string	framexml
+DEATH_RELEASE_TIMER	string	framexml
+DEBUFF_MAX_DISPLAY	number	framexml
+DECLINE	string	framexml
+DEFAULTS	string	framexml
+DEFAULT_AFK_MESSAGE	string	framexml
+DEFAULT_AGILITY_TOOLTIP	string	framexml
+DEFAULT_BATTLEFIELD_TAB_ALPHA	lod	framexml
+DEFAULT_BINDINGS	lod	framexml
+DEFAULT_CHATFRAME_ALPHA	number	framexml
+DEFAULT_CHATFRAME_COLOR	table	framexml
+DEFAULT_CHAT_FRAME	table	framexml
+DEFAULT_DND_MESSAGE	string	framexml
+DEFAULT_INTELLECT_TOOLTIP	string	framexml
+DEFAULT_POI_ICON_SIZE	lod	framexml
+DEFAULT_SPIRIT_TOOLTIP	string	framexml
+DEFAULT_STAMINA_TOOLTIP	string	framexml
+DEFAULT_STRENGTH_TOOLTIP	string	framexml
+DEFAULT_TOOLTIP_POSITION	number	framexml
+DEFENSE_COLON	string	framexml
+DEFENSE_TOOLTIP	string	framexml
+DEFLECT	string	framexml
+DELETE	string	framexml
+DELETE_GOOD_ITEM	string	framexml
+DELETE_ITEM	string	framexml
+DELETE_ITEM_CONFIRM_STRING	string	framexml
+DELETE_MAIL_CONFIRMATION	string	framexml
+DELETE_MONEY_CONFIRMATION	string	framexml
+DEMOTE	string	framexml
+DEPOSIT_COLON	string	framexml
+DESKTOP_GAMMA	string	framexml
+DISABLE	string	framexml
+DISABLE_SPAM_FILTER	string	framexml
+DISGUISE	string	framexml
+DISHONORABLE_KILLS	string	framexml
+DISPELFAILEDOTHEROTHER	string	framexml
+DISPELFAILEDOTHERSELF	string	framexml
+DISPELFAILEDSELFOTHER	string	framexml
+DISPELFAILEDSELFSELF	string	framexml
+DISPLAY	string	framexml
+DISPLAY_ON_CHARACTER	string	framexml
+DISPLAY_ON_CHAR_TOOLTIP	string	framexml
+DK	string	framexml
+DOCKED_CHAT_FRAMES	table	framexml
+DOCK_COPY	table	framexml
+DODGE	string	framexml
+DPS_TEMPLATE	string	framexml
+DRESSUP_FRAME	string	framexml
+DRESSUP_FRAME_INSTRUCTIONS	string	framexml
+DRUID_INTELLECT_TOOLTIP	string	framexml
+DRUNK_MESSAGE_OTHER1	string	framexml
+DRUNK_MESSAGE_OTHER2	string	framexml
+DRUNK_MESSAGE_OTHER3	string	framexml
+DRUNK_MESSAGE_OTHER4	string	framexml
+DRUNK_MESSAGE_SELF1	string	framexml
+DRUNK_MESSAGE_SELF2	string	framexml
+DRUNK_MESSAGE_SELF3	string	framexml
+DRUNK_MESSAGE_SELF4	string	framexml
+DUEL	string	framexml
+DUEL_COUNTDOWN	string	framexml
+DUEL_OUTOFBOUNDS_TIMER	string	framexml
+DUEL_REQUESTED	string	framexml
+DUEL_WINNER_KNOCKOUT	string	framexml
+DUEL_WINNER_RETREAT	string	framexml
+DUNGEON_DIFFICULTY1	string	framexml
+DUNGEON_DIFFICULTY2	string	framexml
+DUNGEON_DIFFICULTY3	string	framexml
+DURABILITYDAMAGE_DEATH	string	framexml
+DURABILITY_TEMPLATE	string	framexml
+DebuffTypeColor	table	framexml
+DeclineGroup	function	engine
+DeclineGuild	function	engine
+DeclineQuest	function	engine
+DeclineResurrect	function	engine
+DelIgnore	function	engine
+DeleteCursorItem	function	engine
+DeleteFile	function	engine
+DeleteGMTicket	function	engine
+DeleteInboxItem	function	engine
+DeleteMacro	function	engine
+DemoteAssistant	function	engine
+DialogBoxFrame	lod	framexml
+DialogButtonHighlightText	table	framexml
+DialogButtonHighlightTexture	lod	framexml
+DialogButtonNormalText	table	framexml
+DialogButtonNormalTexture	lod	framexml
+DialogButtonPushedTexture	lod	framexml
+DisableAddOn	function	engine
+DisableAllAddOns	function	engine
+Disable_BagButtons	function	framexml
+DisplayButton2	lod	framexml
+DisplayChannelOwner	function	engine
+DoCraft	function	engine
+DoEmote	function	engine
+DoReadyCheck	function	engine
+DoTradeSkill	function	engine
+DockRegionTemplate	lod	framexml
+DrawOneHopLines	function	framexml
+DrawRouteLine	function	framexml
+DressUpBackgroundBotLeft	table	framexml
+DressUpBackgroundBotRight	table	framexml
+DressUpBackgroundTopLeft	table	framexml
+DressUpBackgroundTopRight	table	framexml
+DressUpFrame	table	framexml
+DressUpFrameCancelButton	table	framexml
+DressUpFrameCancelButtonText	table	framexml
+DressUpFrameCloseButton	table	framexml
+DressUpFrameDescriptionText	table	framexml
+DressUpFramePortrait	table	framexml
+DressUpFrameResetButton	table	framexml
+DressUpFrameResetButtonText	table	framexml
+DressUpFrameTitleText	table	framexml
+DressUpItem	function	framexml
+DressUpItemLink	function	framexml
+DressUpModel	table	framexml
+DressUpModelRotateLeftButton	table	framexml
+DressUpModelRotateRightButton	table	framexml
+DressUpTexturePath	function	framexml
+DropCursorMoney	function	engine
+DropDownList1	table	framexml
+DropDownList1Backdrop	table	framexml
+DropDownList1Button1	table	framexml
+DropDownList1Button10	table	framexml
+DropDownList1Button10Check	table	framexml
+DropDownList1Button10ColorSwatch	table	framexml
+DropDownList1Button10ColorSwatchNormalTexture	table	framexml
+DropDownList1Button10ColorSwatchSwatchBg	table	framexml
+DropDownList1Button10ExpandArrow	table	framexml
+DropDownList1Button10Highlight	table	framexml
+DropDownList1Button10Icon	table	framexml
+DropDownList1Button10InvisibleButton	table	framexml
+DropDownList1Button10NormalText	table	framexml
+DropDownList1Button11	table	framexml
+DropDownList1Button11Check	table	framexml
+DropDownList1Button11ColorSwatch	table	framexml
+DropDownList1Button11ColorSwatchNormalTexture	table	framexml
+DropDownList1Button11ColorSwatchSwatchBg	table	framexml
+DropDownList1Button11ExpandArrow	table	framexml
+DropDownList1Button11Highlight	table	framexml
+DropDownList1Button11Icon	table	framexml
+DropDownList1Button11InvisibleButton	table	framexml
+DropDownList1Button11NormalText	table	framexml
+DropDownList1Button12	table	framexml
+DropDownList1Button12Check	table	framexml
+DropDownList1Button12ColorSwatch	table	framexml
+DropDownList1Button12ColorSwatchNormalTexture	table	framexml
+DropDownList1Button12ColorSwatchSwatchBg	table	framexml
+DropDownList1Button12ExpandArrow	table	framexml
+DropDownList1Button12Highlight	table	framexml
+DropDownList1Button12Icon	table	framexml
+DropDownList1Button12InvisibleButton	table	framexml
+DropDownList1Button12NormalText	table	framexml
+DropDownList1Button13	table	framexml
+DropDownList1Button13Check	table	framexml
+DropDownList1Button13ColorSwatch	table	framexml
+DropDownList1Button13ColorSwatchNormalTexture	table	framexml
+DropDownList1Button13ColorSwatchSwatchBg	table	framexml
+DropDownList1Button13ExpandArrow	table	framexml
+DropDownList1Button13Highlight	table	framexml
+DropDownList1Button13Icon	table	framexml
+DropDownList1Button13InvisibleButton	table	framexml
+DropDownList1Button13NormalText	table	framexml
+DropDownList1Button14	table	framexml
+DropDownList1Button14Check	table	framexml
+DropDownList1Button14ColorSwatch	table	framexml
+DropDownList1Button14ColorSwatchNormalTexture	table	framexml
+DropDownList1Button14ColorSwatchSwatchBg	table	framexml
+DropDownList1Button14ExpandArrow	table	framexml
+DropDownList1Button14Highlight	table	framexml
+DropDownList1Button14Icon	table	framexml
+DropDownList1Button14InvisibleButton	table	framexml
+DropDownList1Button14NormalText	table	framexml
+DropDownList1Button15	table	framexml
+DropDownList1Button15Check	table	framexml
+DropDownList1Button15ColorSwatch	table	framexml
+DropDownList1Button15ColorSwatchNormalTexture	table	framexml
+DropDownList1Button15ColorSwatchSwatchBg	table	framexml
+DropDownList1Button15ExpandArrow	table	framexml
+DropDownList1Button15Highlight	table	framexml
+DropDownList1Button15Icon	table	framexml
+DropDownList1Button15InvisibleButton	table	framexml
+DropDownList1Button15NormalText	table	framexml
+DropDownList1Button16	table	framexml
+DropDownList1Button16Check	table	framexml
+DropDownList1Button16ColorSwatch	table	framexml
+DropDownList1Button16ColorSwatchNormalTexture	table	framexml
+DropDownList1Button16ColorSwatchSwatchBg	table	framexml
+DropDownList1Button16ExpandArrow	table	framexml
+DropDownList1Button16Highlight	table	framexml
+DropDownList1Button16Icon	table	framexml
+DropDownList1Button16InvisibleButton	table	framexml
+DropDownList1Button16NormalText	table	framexml
+DropDownList1Button17	table	framexml
+DropDownList1Button17Check	table	framexml
+DropDownList1Button17ColorSwatch	table	framexml
+DropDownList1Button17ColorSwatchNormalTexture	table	framexml
+DropDownList1Button17ColorSwatchSwatchBg	table	framexml
+DropDownList1Button17ExpandArrow	table	framexml
+DropDownList1Button17Highlight	table	framexml
+DropDownList1Button17Icon	table	framexml
+DropDownList1Button17InvisibleButton	table	framexml
+DropDownList1Button17NormalText	table	framexml
+DropDownList1Button18	table	framexml
+DropDownList1Button18Check	table	framexml
+DropDownList1Button18ColorSwatch	table	framexml
+DropDownList1Button18ColorSwatchNormalTexture	table	framexml
+DropDownList1Button18ColorSwatchSwatchBg	table	framexml
+DropDownList1Button18ExpandArrow	table	framexml
+DropDownList1Button18Highlight	table	framexml
+DropDownList1Button18Icon	table	framexml
+DropDownList1Button18InvisibleButton	table	framexml
+DropDownList1Button18NormalText	table	framexml
+DropDownList1Button19	table	framexml
+DropDownList1Button19Check	table	framexml
+DropDownList1Button19ColorSwatch	table	framexml
+DropDownList1Button19ColorSwatchNormalTexture	table	framexml
+DropDownList1Button19ColorSwatchSwatchBg	table	framexml
+DropDownList1Button19ExpandArrow	table	framexml
+DropDownList1Button19Highlight	table	framexml
+DropDownList1Button19Icon	table	framexml
+DropDownList1Button19InvisibleButton	table	framexml
+DropDownList1Button19NormalText	table	framexml
+DropDownList1Button1Check	table	framexml
+DropDownList1Button1ColorSwatch	table	framexml
+DropDownList1Button1ColorSwatchNormalTexture	table	framexml
+DropDownList1Button1ColorSwatchSwatchBg	table	framexml
+DropDownList1Button1ExpandArrow	table	framexml
+DropDownList1Button1Highlight	table	framexml
+DropDownList1Button1Icon	table	framexml
+DropDownList1Button1InvisibleButton	table	framexml
+DropDownList1Button1NormalText	table	framexml
+DropDownList1Button2	table	framexml
+DropDownList1Button20	table	framexml
+DropDownList1Button20Check	table	framexml
+DropDownList1Button20ColorSwatch	table	framexml
+DropDownList1Button20ColorSwatchNormalTexture	table	framexml
+DropDownList1Button20ColorSwatchSwatchBg	table	framexml
+DropDownList1Button20ExpandArrow	table	framexml
+DropDownList1Button20Highlight	table	framexml
+DropDownList1Button20Icon	table	framexml
+DropDownList1Button20InvisibleButton	table	framexml
+DropDownList1Button20NormalText	table	framexml
+DropDownList1Button21	table	framexml
+DropDownList1Button21Check	table	framexml
+DropDownList1Button21ColorSwatch	table	framexml
+DropDownList1Button21ColorSwatchNormalTexture	table	framexml
+DropDownList1Button21ColorSwatchSwatchBg	table	framexml
+DropDownList1Button21ExpandArrow	table	framexml
+DropDownList1Button21Highlight	table	framexml
+DropDownList1Button21Icon	table	framexml
+DropDownList1Button21InvisibleButton	table	framexml
+DropDownList1Button21NormalText	table	framexml
+DropDownList1Button22	table	framexml
+DropDownList1Button22Check	table	framexml
+DropDownList1Button22ColorSwatch	table	framexml
+DropDownList1Button22ColorSwatchNormalTexture	table	framexml
+DropDownList1Button22ColorSwatchSwatchBg	table	framexml
+DropDownList1Button22ExpandArrow	table	framexml
+DropDownList1Button22Highlight	table	framexml
+DropDownList1Button22Icon	table	framexml
+DropDownList1Button22InvisibleButton	table	framexml
+DropDownList1Button22NormalText	table	framexml
+DropDownList1Button23	table	framexml
+DropDownList1Button23Check	table	framexml
+DropDownList1Button23ColorSwatch	table	framexml
+DropDownList1Button23ColorSwatchNormalTexture	table	framexml
+DropDownList1Button23ColorSwatchSwatchBg	table	framexml
+DropDownList1Button23ExpandArrow	table	framexml
+DropDownList1Button23Highlight	table	framexml
+DropDownList1Button23Icon	table	framexml
+DropDownList1Button23InvisibleButton	table	framexml
+DropDownList1Button23NormalText	table	framexml
+DropDownList1Button24	table	framexml
+DropDownList1Button24Check	table	framexml
+DropDownList1Button24ColorSwatch	table	framexml
+DropDownList1Button24ColorSwatchNormalTexture	table	framexml
+DropDownList1Button24ColorSwatchSwatchBg	table	framexml
+DropDownList1Button24ExpandArrow	table	framexml
+DropDownList1Button24Highlight	table	framexml
+DropDownList1Button24Icon	table	framexml
+DropDownList1Button24InvisibleButton	table	framexml
+DropDownList1Button24NormalText	table	framexml
+DropDownList1Button25	table	framexml
+DropDownList1Button25Check	table	framexml
+DropDownList1Button25ColorSwatch	table	framexml
+DropDownList1Button25ColorSwatchNormalTexture	table	framexml
+DropDownList1Button25ColorSwatchSwatchBg	table	framexml
+DropDownList1Button25ExpandArrow	table	framexml
+DropDownList1Button25Highlight	table	framexml
+DropDownList1Button25Icon	table	framexml
+DropDownList1Button25InvisibleButton	table	framexml
+DropDownList1Button25NormalText	table	framexml
+DropDownList1Button26	table	framexml
+DropDownList1Button26Check	table	framexml
+DropDownList1Button26ColorSwatch	table	framexml
+DropDownList1Button26ColorSwatchNormalTexture	table	framexml
+DropDownList1Button26ColorSwatchSwatchBg	table	framexml
+DropDownList1Button26ExpandArrow	table	framexml
+DropDownList1Button26Highlight	table	framexml
+DropDownList1Button26Icon	table	framexml
+DropDownList1Button26InvisibleButton	table	framexml
+DropDownList1Button26NormalText	table	framexml
+DropDownList1Button27	table	framexml
+DropDownList1Button27Check	table	framexml
+DropDownList1Button27ColorSwatch	table	framexml
+DropDownList1Button27ColorSwatchNormalTexture	table	framexml
+DropDownList1Button27ColorSwatchSwatchBg	table	framexml
+DropDownList1Button27ExpandArrow	table	framexml
+DropDownList1Button27Highlight	table	framexml
+DropDownList1Button27Icon	table	framexml
+DropDownList1Button27InvisibleButton	table	framexml
+DropDownList1Button27NormalText	table	framexml
+DropDownList1Button28	table	framexml
+DropDownList1Button28Check	table	framexml
+DropDownList1Button28ColorSwatch	table	framexml
+DropDownList1Button28ColorSwatchNormalTexture	table	framexml
+DropDownList1Button28ColorSwatchSwatchBg	table	framexml
+DropDownList1Button28ExpandArrow	table	framexml
+DropDownList1Button28Highlight	table	framexml
+DropDownList1Button28Icon	table	framexml
+DropDownList1Button28InvisibleButton	table	framexml
+DropDownList1Button28NormalText	table	framexml
+DropDownList1Button29	table	framexml
+DropDownList1Button29Check	table	framexml
+DropDownList1Button29ColorSwatch	table	framexml
+DropDownList1Button29ColorSwatchNormalTexture	table	framexml
+DropDownList1Button29ColorSwatchSwatchBg	table	framexml
+DropDownList1Button29ExpandArrow	table	framexml
+DropDownList1Button29Highlight	table	framexml
+DropDownList1Button29Icon	table	framexml
+DropDownList1Button29InvisibleButton	table	framexml
+DropDownList1Button29NormalText	table	framexml
+DropDownList1Button2Check	table	framexml
+DropDownList1Button2ColorSwatch	table	framexml
+DropDownList1Button2ColorSwatchNormalTexture	table	framexml
+DropDownList1Button2ColorSwatchSwatchBg	table	framexml
+DropDownList1Button2ExpandArrow	table	framexml
+DropDownList1Button2Highlight	table	framexml
+DropDownList1Button2Icon	table	framexml
+DropDownList1Button2InvisibleButton	table	framexml
+DropDownList1Button2NormalText	table	framexml
+DropDownList1Button3	table	framexml
+DropDownList1Button30	table	framexml
+DropDownList1Button30Check	table	framexml
+DropDownList1Button30ColorSwatch	table	framexml
+DropDownList1Button30ColorSwatchNormalTexture	table	framexml
+DropDownList1Button30ColorSwatchSwatchBg	table	framexml
+DropDownList1Button30ExpandArrow	table	framexml
+DropDownList1Button30Highlight	table	framexml
+DropDownList1Button30Icon	table	framexml
+DropDownList1Button30InvisibleButton	table	framexml
+DropDownList1Button30NormalText	table	framexml
+DropDownList1Button31	table	framexml
+DropDownList1Button31Check	table	framexml
+DropDownList1Button31ColorSwatch	table	framexml
+DropDownList1Button31ColorSwatchNormalTexture	table	framexml
+DropDownList1Button31ColorSwatchSwatchBg	table	framexml
+DropDownList1Button31ExpandArrow	table	framexml
+DropDownList1Button31Highlight	table	framexml
+DropDownList1Button31Icon	table	framexml
+DropDownList1Button31InvisibleButton	table	framexml
+DropDownList1Button31NormalText	table	framexml
+DropDownList1Button32	table	framexml
+DropDownList1Button32Check	table	framexml
+DropDownList1Button32ColorSwatch	table	framexml
+DropDownList1Button32ColorSwatchNormalTexture	table	framexml
+DropDownList1Button32ColorSwatchSwatchBg	table	framexml
+DropDownList1Button32ExpandArrow	table	framexml
+DropDownList1Button32Highlight	table	framexml
+DropDownList1Button32Icon	table	framexml
+DropDownList1Button32InvisibleButton	table	framexml
+DropDownList1Button32NormalText	table	framexml
+DropDownList1Button3Check	table	framexml
+DropDownList1Button3ColorSwatch	table	framexml
+DropDownList1Button3ColorSwatchNormalTexture	table	framexml
+DropDownList1Button3ColorSwatchSwatchBg	table	framexml
+DropDownList1Button3ExpandArrow	table	framexml
+DropDownList1Button3Highlight	table	framexml
+DropDownList1Button3Icon	table	framexml
+DropDownList1Button3InvisibleButton	table	framexml
+DropDownList1Button3NormalText	table	framexml
+DropDownList1Button4	table	framexml
+DropDownList1Button4Check	table	framexml
+DropDownList1Button4ColorSwatch	table	framexml
+DropDownList1Button4ColorSwatchNormalTexture	table	framexml
+DropDownList1Button4ColorSwatchSwatchBg	table	framexml
+DropDownList1Button4ExpandArrow	table	framexml
+DropDownList1Button4Highlight	table	framexml
+DropDownList1Button4Icon	table	framexml
+DropDownList1Button4InvisibleButton	table	framexml
+DropDownList1Button4NormalText	table	framexml
+DropDownList1Button5	table	framexml
+DropDownList1Button5Check	table	framexml
+DropDownList1Button5ColorSwatch	table	framexml
+DropDownList1Button5ColorSwatchNormalTexture	table	framexml
+DropDownList1Button5ColorSwatchSwatchBg	table	framexml
+DropDownList1Button5ExpandArrow	table	framexml
+DropDownList1Button5Highlight	table	framexml
+DropDownList1Button5Icon	table	framexml
+DropDownList1Button5InvisibleButton	table	framexml
+DropDownList1Button5NormalText	table	framexml
+DropDownList1Button6	table	framexml
+DropDownList1Button6Check	table	framexml
+DropDownList1Button6ColorSwatch	table	framexml
+DropDownList1Button6ColorSwatchNormalTexture	table	framexml
+DropDownList1Button6ColorSwatchSwatchBg	table	framexml
+DropDownList1Button6ExpandArrow	table	framexml
+DropDownList1Button6Highlight	table	framexml
+DropDownList1Button6Icon	table	framexml
+DropDownList1Button6InvisibleButton	table	framexml
+DropDownList1Button6NormalText	table	framexml
+DropDownList1Button7	table	framexml
+DropDownList1Button7Check	table	framexml
+DropDownList1Button7ColorSwatch	table	framexml
+DropDownList1Button7ColorSwatchNormalTexture	table	framexml
+DropDownList1Button7ColorSwatchSwatchBg	table	framexml
+DropDownList1Button7ExpandArrow	table	framexml
+DropDownList1Button7Highlight	table	framexml
+DropDownList1Button7Icon	table	framexml
+DropDownList1Button7InvisibleButton	table	framexml
+DropDownList1Button7NormalText	table	framexml
+DropDownList1Button8	table	framexml
+DropDownList1Button8Check	table	framexml
+DropDownList1Button8ColorSwatch	table	framexml
+DropDownList1Button8ColorSwatchNormalTexture	table	framexml
+DropDownList1Button8ColorSwatchSwatchBg	table	framexml
+DropDownList1Button8ExpandArrow	table	framexml
+DropDownList1Button8Highlight	table	framexml
+DropDownList1Button8Icon	table	framexml
+DropDownList1Button8InvisibleButton	table	framexml
+DropDownList1Button8NormalText	table	framexml
+DropDownList1Button9	table	framexml
+DropDownList1Button9Check	table	framexml
+DropDownList1Button9ColorSwatch	table	framexml
+DropDownList1Button9ColorSwatchNormalTexture	table	framexml
+DropDownList1Button9ColorSwatchSwatchBg	table	framexml
+DropDownList1Button9ExpandArrow	table	framexml
+DropDownList1Button9Highlight	table	framexml
+DropDownList1Button9Icon	table	framexml
+DropDownList1Button9InvisibleButton	table	framexml
+DropDownList1Button9NormalText	table	framexml
+DropDownList1MenuBackdrop	table	framexml
+DropDownList2	table	framexml
+DropDownList2Backdrop	table	framexml
+DropDownList2Button1	table	framexml
+DropDownList2Button10	table	framexml
+DropDownList2Button10Check	table	framexml
+DropDownList2Button10ColorSwatch	table	framexml
+DropDownList2Button10ColorSwatchNormalTexture	table	framexml
+DropDownList2Button10ColorSwatchSwatchBg	table	framexml
+DropDownList2Button10ExpandArrow	table	framexml
+DropDownList2Button10Highlight	table	framexml
+DropDownList2Button10Icon	table	framexml
+DropDownList2Button10InvisibleButton	table	framexml
+DropDownList2Button10NormalText	table	framexml
+DropDownList2Button11	table	framexml
+DropDownList2Button11Check	table	framexml
+DropDownList2Button11ColorSwatch	table	framexml
+DropDownList2Button11ColorSwatchNormalTexture	table	framexml
+DropDownList2Button11ColorSwatchSwatchBg	table	framexml
+DropDownList2Button11ExpandArrow	table	framexml
+DropDownList2Button11Highlight	table	framexml
+DropDownList2Button11Icon	table	framexml
+DropDownList2Button11InvisibleButton	table	framexml
+DropDownList2Button11NormalText	table	framexml
+DropDownList2Button12	table	framexml
+DropDownList2Button12Check	table	framexml
+DropDownList2Button12ColorSwatch	table	framexml
+DropDownList2Button12ColorSwatchNormalTexture	table	framexml
+DropDownList2Button12ColorSwatchSwatchBg	table	framexml
+DropDownList2Button12ExpandArrow	table	framexml
+DropDownList2Button12Highlight	table	framexml
+DropDownList2Button12Icon	table	framexml
+DropDownList2Button12InvisibleButton	table	framexml
+DropDownList2Button12NormalText	table	framexml
+DropDownList2Button13	table	framexml
+DropDownList2Button13Check	table	framexml
+DropDownList2Button13ColorSwatch	table	framexml
+DropDownList2Button13ColorSwatchNormalTexture	table	framexml
+DropDownList2Button13ColorSwatchSwatchBg	table	framexml
+DropDownList2Button13ExpandArrow	table	framexml
+DropDownList2Button13Highlight	table	framexml
+DropDownList2Button13Icon	table	framexml
+DropDownList2Button13InvisibleButton	table	framexml
+DropDownList2Button13NormalText	table	framexml
+DropDownList2Button14	table	framexml
+DropDownList2Button14Check	table	framexml
+DropDownList2Button14ColorSwatch	table	framexml
+DropDownList2Button14ColorSwatchNormalTexture	table	framexml
+DropDownList2Button14ColorSwatchSwatchBg	table	framexml
+DropDownList2Button14ExpandArrow	table	framexml
+DropDownList2Button14Highlight	table	framexml
+DropDownList2Button14Icon	table	framexml
+DropDownList2Button14InvisibleButton	table	framexml
+DropDownList2Button14NormalText	table	framexml
+DropDownList2Button15	table	framexml
+DropDownList2Button15Check	table	framexml
+DropDownList2Button15ColorSwatch	table	framexml
+DropDownList2Button15ColorSwatchNormalTexture	table	framexml
+DropDownList2Button15ColorSwatchSwatchBg	table	framexml
+DropDownList2Button15ExpandArrow	table	framexml
+DropDownList2Button15Highlight	table	framexml
+DropDownList2Button15Icon	table	framexml
+DropDownList2Button15InvisibleButton	table	framexml
+DropDownList2Button15NormalText	table	framexml
+DropDownList2Button16	table	framexml
+DropDownList2Button16Check	table	framexml
+DropDownList2Button16ColorSwatch	table	framexml
+DropDownList2Button16ColorSwatchNormalTexture	table	framexml
+DropDownList2Button16ColorSwatchSwatchBg	table	framexml
+DropDownList2Button16ExpandArrow	table	framexml
+DropDownList2Button16Highlight	table	framexml
+DropDownList2Button16Icon	table	framexml
+DropDownList2Button16InvisibleButton	table	framexml
+DropDownList2Button16NormalText	table	framexml
+DropDownList2Button17	table	framexml
+DropDownList2Button17Check	table	framexml
+DropDownList2Button17ColorSwatch	table	framexml
+DropDownList2Button17ColorSwatchNormalTexture	table	framexml
+DropDownList2Button17ColorSwatchSwatchBg	table	framexml
+DropDownList2Button17ExpandArrow	table	framexml
+DropDownList2Button17Highlight	table	framexml
+DropDownList2Button17Icon	table	framexml
+DropDownList2Button17InvisibleButton	table	framexml
+DropDownList2Button17NormalText	table	framexml
+DropDownList2Button18	table	framexml
+DropDownList2Button18Check	table	framexml
+DropDownList2Button18ColorSwatch	table	framexml
+DropDownList2Button18ColorSwatchNormalTexture	table	framexml
+DropDownList2Button18ColorSwatchSwatchBg	table	framexml
+DropDownList2Button18ExpandArrow	table	framexml
+DropDownList2Button18Highlight	table	framexml
+DropDownList2Button18Icon	table	framexml
+DropDownList2Button18InvisibleButton	table	framexml
+DropDownList2Button18NormalText	table	framexml
+DropDownList2Button19	table	framexml
+DropDownList2Button19Check	table	framexml
+DropDownList2Button19ColorSwatch	table	framexml
+DropDownList2Button19ColorSwatchNormalTexture	table	framexml
+DropDownList2Button19ColorSwatchSwatchBg	table	framexml
+DropDownList2Button19ExpandArrow	table	framexml
+DropDownList2Button19Highlight	table	framexml
+DropDownList2Button19Icon	table	framexml
+DropDownList2Button19InvisibleButton	table	framexml
+DropDownList2Button19NormalText	table	framexml
+DropDownList2Button1Check	table	framexml
+DropDownList2Button1ColorSwatch	table	framexml
+DropDownList2Button1ColorSwatchNormalTexture	table	framexml
+DropDownList2Button1ColorSwatchSwatchBg	table	framexml
+DropDownList2Button1ExpandArrow	table	framexml
+DropDownList2Button1Highlight	table	framexml
+DropDownList2Button1Icon	table	framexml
+DropDownList2Button1InvisibleButton	table	framexml
+DropDownList2Button1NormalText	table	framexml
+DropDownList2Button2	table	framexml
+DropDownList2Button20	table	framexml
+DropDownList2Button20Check	table	framexml
+DropDownList2Button20ColorSwatch	table	framexml
+DropDownList2Button20ColorSwatchNormalTexture	table	framexml
+DropDownList2Button20ColorSwatchSwatchBg	table	framexml
+DropDownList2Button20ExpandArrow	table	framexml
+DropDownList2Button20Highlight	table	framexml
+DropDownList2Button20Icon	table	framexml
+DropDownList2Button20InvisibleButton	table	framexml
+DropDownList2Button20NormalText	table	framexml
+DropDownList2Button21	table	framexml
+DropDownList2Button21Check	table	framexml
+DropDownList2Button21ColorSwatch	table	framexml
+DropDownList2Button21ColorSwatchNormalTexture	table	framexml
+DropDownList2Button21ColorSwatchSwatchBg	table	framexml
+DropDownList2Button21ExpandArrow	table	framexml
+DropDownList2Button21Highlight	table	framexml
+DropDownList2Button21Icon	table	framexml
+DropDownList2Button21InvisibleButton	table	framexml
+DropDownList2Button21NormalText	table	framexml
+DropDownList2Button22	table	framexml
+DropDownList2Button22Check	table	framexml
+DropDownList2Button22ColorSwatch	table	framexml
+DropDownList2Button22ColorSwatchNormalTexture	table	framexml
+DropDownList2Button22ColorSwatchSwatchBg	table	framexml
+DropDownList2Button22ExpandArrow	table	framexml
+DropDownList2Button22Highlight	table	framexml
+DropDownList2Button22Icon	table	framexml
+DropDownList2Button22InvisibleButton	table	framexml
+DropDownList2Button22NormalText	table	framexml
+DropDownList2Button23	table	framexml
+DropDownList2Button23Check	table	framexml
+DropDownList2Button23ColorSwatch	table	framexml
+DropDownList2Button23ColorSwatchNormalTexture	table	framexml
+DropDownList2Button23ColorSwatchSwatchBg	table	framexml
+DropDownList2Button23ExpandArrow	table	framexml
+DropDownList2Button23Highlight	table	framexml
+DropDownList2Button23Icon	table	framexml
+DropDownList2Button23InvisibleButton	table	framexml
+DropDownList2Button23NormalText	table	framexml
+DropDownList2Button24	table	framexml
+DropDownList2Button24Check	table	framexml
+DropDownList2Button24ColorSwatch	table	framexml
+DropDownList2Button24ColorSwatchNormalTexture	table	framexml
+DropDownList2Button24ColorSwatchSwatchBg	table	framexml
+DropDownList2Button24ExpandArrow	table	framexml
+DropDownList2Button24Highlight	table	framexml
+DropDownList2Button24Icon	table	framexml
+DropDownList2Button24InvisibleButton	table	framexml
+DropDownList2Button24NormalText	table	framexml
+DropDownList2Button25	table	framexml
+DropDownList2Button25Check	table	framexml
+DropDownList2Button25ColorSwatch	table	framexml
+DropDownList2Button25ColorSwatchNormalTexture	table	framexml
+DropDownList2Button25ColorSwatchSwatchBg	table	framexml
+DropDownList2Button25ExpandArrow	table	framexml
+DropDownList2Button25Highlight	table	framexml
+DropDownList2Button25Icon	table	framexml
+DropDownList2Button25InvisibleButton	table	framexml
+DropDownList2Button25NormalText	table	framexml
+DropDownList2Button26	table	framexml
+DropDownList2Button26Check	table	framexml
+DropDownList2Button26ColorSwatch	table	framexml
+DropDownList2Button26ColorSwatchNormalTexture	table	framexml
+DropDownList2Button26ColorSwatchSwatchBg	table	framexml
+DropDownList2Button26ExpandArrow	table	framexml
+DropDownList2Button26Highlight	table	framexml
+DropDownList2Button26Icon	table	framexml
+DropDownList2Button26InvisibleButton	table	framexml
+DropDownList2Button26NormalText	table	framexml
+DropDownList2Button27	table	framexml
+DropDownList2Button27Check	table	framexml
+DropDownList2Button27ColorSwatch	table	framexml
+DropDownList2Button27ColorSwatchNormalTexture	table	framexml
+DropDownList2Button27ColorSwatchSwatchBg	table	framexml
+DropDownList2Button27ExpandArrow	table	framexml
+DropDownList2Button27Highlight	table	framexml
+DropDownList2Button27Icon	table	framexml
+DropDownList2Button27InvisibleButton	table	framexml
+DropDownList2Button27NormalText	table	framexml
+DropDownList2Button28	table	framexml
+DropDownList2Button28Check	table	framexml
+DropDownList2Button28ColorSwatch	table	framexml
+DropDownList2Button28ColorSwatchNormalTexture	table	framexml
+DropDownList2Button28ColorSwatchSwatchBg	table	framexml
+DropDownList2Button28ExpandArrow	table	framexml
+DropDownList2Button28Highlight	table	framexml
+DropDownList2Button28Icon	table	framexml
+DropDownList2Button28InvisibleButton	table	framexml
+DropDownList2Button28NormalText	table	framexml
+DropDownList2Button29	table	framexml
+DropDownList2Button29Check	table	framexml
+DropDownList2Button29ColorSwatch	table	framexml
+DropDownList2Button29ColorSwatchNormalTexture	table	framexml
+DropDownList2Button29ColorSwatchSwatchBg	table	framexml
+DropDownList2Button29ExpandArrow	table	framexml
+DropDownList2Button29Highlight	table	framexml
+DropDownList2Button29Icon	table	framexml
+DropDownList2Button29InvisibleButton	table	framexml
+DropDownList2Button29NormalText	table	framexml
+DropDownList2Button2Check	table	framexml
+DropDownList2Button2ColorSwatch	table	framexml
+DropDownList2Button2ColorSwatchNormalTexture	table	framexml
+DropDownList2Button2ColorSwatchSwatchBg	table	framexml
+DropDownList2Button2ExpandArrow	table	framexml
+DropDownList2Button2Highlight	table	framexml
+DropDownList2Button2Icon	table	framexml
+DropDownList2Button2InvisibleButton	table	framexml
+DropDownList2Button2NormalText	table	framexml
+DropDownList2Button3	table	framexml
+DropDownList2Button30	table	framexml
+DropDownList2Button30Check	table	framexml
+DropDownList2Button30ColorSwatch	table	framexml
+DropDownList2Button30ColorSwatchNormalTexture	table	framexml
+DropDownList2Button30ColorSwatchSwatchBg	table	framexml
+DropDownList2Button30ExpandArrow	table	framexml
+DropDownList2Button30Highlight	table	framexml
+DropDownList2Button30Icon	table	framexml
+DropDownList2Button30InvisibleButton	table	framexml
+DropDownList2Button30NormalText	table	framexml
+DropDownList2Button31	table	framexml
+DropDownList2Button31Check	table	framexml
+DropDownList2Button31ColorSwatch	table	framexml
+DropDownList2Button31ColorSwatchNormalTexture	table	framexml
+DropDownList2Button31ColorSwatchSwatchBg	table	framexml
+DropDownList2Button31ExpandArrow	table	framexml
+DropDownList2Button31Highlight	table	framexml
+DropDownList2Button31Icon	table	framexml
+DropDownList2Button31InvisibleButton	table	framexml
+DropDownList2Button31NormalText	table	framexml
+DropDownList2Button32	table	framexml
+DropDownList2Button32Check	table	framexml
+DropDownList2Button32ColorSwatch	table	framexml
+DropDownList2Button32ColorSwatchNormalTexture	table	framexml
+DropDownList2Button32ColorSwatchSwatchBg	table	framexml
+DropDownList2Button32ExpandArrow	table	framexml
+DropDownList2Button32Highlight	table	framexml
+DropDownList2Button32Icon	table	framexml
+DropDownList2Button32InvisibleButton	table	framexml
+DropDownList2Button32NormalText	table	framexml
+DropDownList2Button3Check	table	framexml
+DropDownList2Button3ColorSwatch	table	framexml
+DropDownList2Button3ColorSwatchNormalTexture	table	framexml
+DropDownList2Button3ColorSwatchSwatchBg	table	framexml
+DropDownList2Button3ExpandArrow	table	framexml
+DropDownList2Button3Highlight	table	framexml
+DropDownList2Button3Icon	table	framexml
+DropDownList2Button3InvisibleButton	table	framexml
+DropDownList2Button3NormalText	table	framexml
+DropDownList2Button4	table	framexml
+DropDownList2Button4Check	table	framexml
+DropDownList2Button4ColorSwatch	table	framexml
+DropDownList2Button4ColorSwatchNormalTexture	table	framexml
+DropDownList2Button4ColorSwatchSwatchBg	table	framexml
+DropDownList2Button4ExpandArrow	table	framexml
+DropDownList2Button4Highlight	table	framexml
+DropDownList2Button4Icon	table	framexml
+DropDownList2Button4InvisibleButton	table	framexml
+DropDownList2Button4NormalText	table	framexml
+DropDownList2Button5	table	framexml
+DropDownList2Button5Check	table	framexml
+DropDownList2Button5ColorSwatch	table	framexml
+DropDownList2Button5ColorSwatchNormalTexture	table	framexml
+DropDownList2Button5ColorSwatchSwatchBg	table	framexml
+DropDownList2Button5ExpandArrow	table	framexml
+DropDownList2Button5Highlight	table	framexml
+DropDownList2Button5Icon	table	framexml
+DropDownList2Button5InvisibleButton	table	framexml
+DropDownList2Button5NormalText	table	framexml
+DropDownList2Button6	table	framexml
+DropDownList2Button6Check	table	framexml
+DropDownList2Button6ColorSwatch	table	framexml
+DropDownList2Button6ColorSwatchNormalTexture	table	framexml
+DropDownList2Button6ColorSwatchSwatchBg	table	framexml
+DropDownList2Button6ExpandArrow	table	framexml
+DropDownList2Button6Highlight	table	framexml
+DropDownList2Button6Icon	table	framexml
+DropDownList2Button6InvisibleButton	table	framexml
+DropDownList2Button6NormalText	table	framexml
+DropDownList2Button7	table	framexml
+DropDownList2Button7Check	table	framexml
+DropDownList2Button7ColorSwatch	table	framexml
+DropDownList2Button7ColorSwatchNormalTexture	table	framexml
+DropDownList2Button7ColorSwatchSwatchBg	table	framexml
+DropDownList2Button7ExpandArrow	table	framexml
+DropDownList2Button7Highlight	table	framexml
+DropDownList2Button7Icon	table	framexml
+DropDownList2Button7InvisibleButton	table	framexml
+DropDownList2Button7NormalText	table	framexml
+DropDownList2Button8	table	framexml
+DropDownList2Button8Check	table	framexml
+DropDownList2Button8ColorSwatch	table	framexml
+DropDownList2Button8ColorSwatchNormalTexture	table	framexml
+DropDownList2Button8ColorSwatchSwatchBg	table	framexml
+DropDownList2Button8ExpandArrow	table	framexml
+DropDownList2Button8Highlight	table	framexml
+DropDownList2Button8Icon	table	framexml
+DropDownList2Button8InvisibleButton	table	framexml
+DropDownList2Button8NormalText	table	framexml
+DropDownList2Button9	table	framexml
+DropDownList2Button9Check	table	framexml
+DropDownList2Button9ColorSwatch	table	framexml
+DropDownList2Button9ColorSwatchNormalTexture	table	framexml
+DropDownList2Button9ColorSwatchSwatchBg	table	framexml
+DropDownList2Button9ExpandArrow	table	framexml
+DropDownList2Button9Highlight	table	framexml
+DropDownList2Button9Icon	table	framexml
+DropDownList2Button9InvisibleButton	table	framexml
+DropDownList2Button9NormalText	table	framexml
+DropDownList2MenuBackdrop	table	framexml
+DropDownList3	table	framexml
+DropDownList3Backdrop	table	framexml
+DropDownList3Button1	table	framexml
+DropDownList3Button10	table	framexml
+DropDownList3Button10Check	table	framexml
+DropDownList3Button10ColorSwatch	table	framexml
+DropDownList3Button10ColorSwatchNormalTexture	table	framexml
+DropDownList3Button10ColorSwatchSwatchBg	table	framexml
+DropDownList3Button10ExpandArrow	table	framexml
+DropDownList3Button10Highlight	table	framexml
+DropDownList3Button10Icon	table	framexml
+DropDownList3Button10InvisibleButton	table	framexml
+DropDownList3Button10NormalText	table	framexml
+DropDownList3Button11	table	framexml
+DropDownList3Button11Check	table	framexml
+DropDownList3Button11ColorSwatch	table	framexml
+DropDownList3Button11ColorSwatchNormalTexture	table	framexml
+DropDownList3Button11ColorSwatchSwatchBg	table	framexml
+DropDownList3Button11ExpandArrow	table	framexml
+DropDownList3Button11Highlight	table	framexml
+DropDownList3Button11Icon	table	framexml
+DropDownList3Button11InvisibleButton	table	framexml
+DropDownList3Button11NormalText	table	framexml
+DropDownList3Button12	table	framexml
+DropDownList3Button12Check	table	framexml
+DropDownList3Button12ColorSwatch	table	framexml
+DropDownList3Button12ColorSwatchNormalTexture	table	framexml
+DropDownList3Button12ColorSwatchSwatchBg	table	framexml
+DropDownList3Button12ExpandArrow	table	framexml
+DropDownList3Button12Highlight	table	framexml
+DropDownList3Button12Icon	table	framexml
+DropDownList3Button12InvisibleButton	table	framexml
+DropDownList3Button12NormalText	table	framexml
+DropDownList3Button13	table	framexml
+DropDownList3Button13Check	table	framexml
+DropDownList3Button13ColorSwatch	table	framexml
+DropDownList3Button13ColorSwatchNormalTexture	table	framexml
+DropDownList3Button13ColorSwatchSwatchBg	table	framexml
+DropDownList3Button13ExpandArrow	table	framexml
+DropDownList3Button13Highlight	table	framexml
+DropDownList3Button13Icon	table	framexml
+DropDownList3Button13InvisibleButton	table	framexml
+DropDownList3Button13NormalText	table	framexml
+DropDownList3Button14	table	framexml
+DropDownList3Button14Check	table	framexml
+DropDownList3Button14ColorSwatch	table	framexml
+DropDownList3Button14ColorSwatchNormalTexture	table	framexml
+DropDownList3Button14ColorSwatchSwatchBg	table	framexml
+DropDownList3Button14ExpandArrow	table	framexml
+DropDownList3Button14Highlight	table	framexml
+DropDownList3Button14Icon	table	framexml
+DropDownList3Button14InvisibleButton	table	framexml
+DropDownList3Button14NormalText	table	framexml
+DropDownList3Button15	table	framexml
+DropDownList3Button15Check	table	framexml
+DropDownList3Button15ColorSwatch	table	framexml
+DropDownList3Button15ColorSwatchNormalTexture	table	framexml
+DropDownList3Button15ColorSwatchSwatchBg	table	framexml
+DropDownList3Button15ExpandArrow	table	framexml
+DropDownList3Button15Highlight	table	framexml
+DropDownList3Button15Icon	table	framexml
+DropDownList3Button15InvisibleButton	table	framexml
+DropDownList3Button15NormalText	table	framexml
+DropDownList3Button16	table	framexml
+DropDownList3Button16Check	table	framexml
+DropDownList3Button16ColorSwatch	table	framexml
+DropDownList3Button16ColorSwatchNormalTexture	table	framexml
+DropDownList3Button16ColorSwatchSwatchBg	table	framexml
+DropDownList3Button16ExpandArrow	table	framexml
+DropDownList3Button16Highlight	table	framexml
+DropDownList3Button16Icon	table	framexml
+DropDownList3Button16InvisibleButton	table	framexml
+DropDownList3Button16NormalText	table	framexml
+DropDownList3Button17	table	framexml
+DropDownList3Button17Check	table	framexml
+DropDownList3Button17ColorSwatch	table	framexml
+DropDownList3Button17ColorSwatchNormalTexture	table	framexml
+DropDownList3Button17ColorSwatchSwatchBg	table	framexml
+DropDownList3Button17ExpandArrow	table	framexml
+DropDownList3Button17Highlight	table	framexml
+DropDownList3Button17Icon	table	framexml
+DropDownList3Button17InvisibleButton	table	framexml
+DropDownList3Button17NormalText	table	framexml
+DropDownList3Button18	table	framexml
+DropDownList3Button18Check	table	framexml
+DropDownList3Button18ColorSwatch	table	framexml
+DropDownList3Button18ColorSwatchNormalTexture	table	framexml
+DropDownList3Button18ColorSwatchSwatchBg	table	framexml
+DropDownList3Button18ExpandArrow	table	framexml
+DropDownList3Button18Highlight	table	framexml
+DropDownList3Button18Icon	table	framexml
+DropDownList3Button18InvisibleButton	table	framexml
+DropDownList3Button18NormalText	table	framexml
+DropDownList3Button19	table	framexml
+DropDownList3Button19Check	table	framexml
+DropDownList3Button19ColorSwatch	table	framexml
+DropDownList3Button19ColorSwatchNormalTexture	table	framexml
+DropDownList3Button19ColorSwatchSwatchBg	table	framexml
+DropDownList3Button19ExpandArrow	table	framexml
+DropDownList3Button19Highlight	table	framexml
+DropDownList3Button19Icon	table	framexml
+DropDownList3Button19InvisibleButton	table	framexml
+DropDownList3Button19NormalText	table	framexml
+DropDownList3Button1Check	table	framexml
+DropDownList3Button1ColorSwatch	table	framexml
+DropDownList3Button1ColorSwatchNormalTexture	table	framexml
+DropDownList3Button1ColorSwatchSwatchBg	table	framexml
+DropDownList3Button1ExpandArrow	table	framexml
+DropDownList3Button1Highlight	table	framexml
+DropDownList3Button1Icon	table	framexml
+DropDownList3Button1InvisibleButton	table	framexml
+DropDownList3Button1NormalText	table	framexml
+DropDownList3Button2	table	framexml
+DropDownList3Button20	table	framexml
+DropDownList3Button20Check	table	framexml
+DropDownList3Button20ColorSwatch	table	framexml
+DropDownList3Button20ColorSwatchNormalTexture	table	framexml
+DropDownList3Button20ColorSwatchSwatchBg	table	framexml
+DropDownList3Button20ExpandArrow	table	framexml
+DropDownList3Button20Highlight	table	framexml
+DropDownList3Button20Icon	table	framexml
+DropDownList3Button20InvisibleButton	table	framexml
+DropDownList3Button20NormalText	table	framexml
+DropDownList3Button21	table	framexml
+DropDownList3Button21Check	table	framexml
+DropDownList3Button21ColorSwatch	table	framexml
+DropDownList3Button21ColorSwatchNormalTexture	table	framexml
+DropDownList3Button21ColorSwatchSwatchBg	table	framexml
+DropDownList3Button21ExpandArrow	table	framexml
+DropDownList3Button21Highlight	table	framexml
+DropDownList3Button21Icon	table	framexml
+DropDownList3Button21InvisibleButton	table	framexml
+DropDownList3Button21NormalText	table	framexml
+DropDownList3Button22	table	framexml
+DropDownList3Button22Check	table	framexml
+DropDownList3Button22ColorSwatch	table	framexml
+DropDownList3Button22ColorSwatchNormalTexture	table	framexml
+DropDownList3Button22ColorSwatchSwatchBg	table	framexml
+DropDownList3Button22ExpandArrow	table	framexml
+DropDownList3Button22Highlight	table	framexml
+DropDownList3Button22Icon	table	framexml
+DropDownList3Button22InvisibleButton	table	framexml
+DropDownList3Button22NormalText	table	framexml
+DropDownList3Button23	table	framexml
+DropDownList3Button23Check	table	framexml
+DropDownList3Button23ColorSwatch	table	framexml
+DropDownList3Button23ColorSwatchNormalTexture	table	framexml
+DropDownList3Button23ColorSwatchSwatchBg	table	framexml
+DropDownList3Button23ExpandArrow	table	framexml
+DropDownList3Button23Highlight	table	framexml
+DropDownList3Button23Icon	table	framexml
+DropDownList3Button23InvisibleButton	table	framexml
+DropDownList3Button23NormalText	table	framexml
+DropDownList3Button24	table	framexml
+DropDownList3Button24Check	table	framexml
+DropDownList3Button24ColorSwatch	table	framexml
+DropDownList3Button24ColorSwatchNormalTexture	table	framexml
+DropDownList3Button24ColorSwatchSwatchBg	table	framexml
+DropDownList3Button24ExpandArrow	table	framexml
+DropDownList3Button24Highlight	table	framexml
+DropDownList3Button24Icon	table	framexml
+DropDownList3Button24InvisibleButton	table	framexml
+DropDownList3Button24NormalText	table	framexml
+DropDownList3Button25	table	framexml
+DropDownList3Button25Check	table	framexml
+DropDownList3Button25ColorSwatch	table	framexml
+DropDownList3Button25ColorSwatchNormalTexture	table	framexml
+DropDownList3Button25ColorSwatchSwatchBg	table	framexml
+DropDownList3Button25ExpandArrow	table	framexml
+DropDownList3Button25Highlight	table	framexml
+DropDownList3Button25Icon	table	framexml
+DropDownList3Button25InvisibleButton	table	framexml
+DropDownList3Button25NormalText	table	framexml
+DropDownList3Button26	table	framexml
+DropDownList3Button26Check	table	framexml
+DropDownList3Button26ColorSwatch	table	framexml
+DropDownList3Button26ColorSwatchNormalTexture	table	framexml
+DropDownList3Button26ColorSwatchSwatchBg	table	framexml
+DropDownList3Button26ExpandArrow	table	framexml
+DropDownList3Button26Highlight	table	framexml
+DropDownList3Button26Icon	table	framexml
+DropDownList3Button26InvisibleButton	table	framexml
+DropDownList3Button26NormalText	table	framexml
+DropDownList3Button27	table	framexml
+DropDownList3Button27Check	table	framexml
+DropDownList3Button27ColorSwatch	table	framexml
+DropDownList3Button27ColorSwatchNormalTexture	table	framexml
+DropDownList3Button27ColorSwatchSwatchBg	table	framexml
+DropDownList3Button27ExpandArrow	table	framexml
+DropDownList3Button27Highlight	table	framexml
+DropDownList3Button27Icon	table	framexml
+DropDownList3Button27InvisibleButton	table	framexml
+DropDownList3Button27NormalText	table	framexml
+DropDownList3Button28	table	framexml
+DropDownList3Button28Check	table	framexml
+DropDownList3Button28ColorSwatch	table	framexml
+DropDownList3Button28ColorSwatchNormalTexture	table	framexml
+DropDownList3Button28ColorSwatchSwatchBg	table	framexml
+DropDownList3Button28ExpandArrow	table	framexml
+DropDownList3Button28Highlight	table	framexml
+DropDownList3Button28Icon	table	framexml
+DropDownList3Button28InvisibleButton	table	framexml
+DropDownList3Button28NormalText	table	framexml
+DropDownList3Button29	table	framexml
+DropDownList3Button29Check	table	framexml
+DropDownList3Button29ColorSwatch	table	framexml
+DropDownList3Button29ColorSwatchNormalTexture	table	framexml
+DropDownList3Button29ColorSwatchSwatchBg	table	framexml
+DropDownList3Button29ExpandArrow	table	framexml
+DropDownList3Button29Highlight	table	framexml
+DropDownList3Button29Icon	table	framexml
+DropDownList3Button29InvisibleButton	table	framexml
+DropDownList3Button29NormalText	table	framexml
+DropDownList3Button2Check	table	framexml
+DropDownList3Button2ColorSwatch	table	framexml
+DropDownList3Button2ColorSwatchNormalTexture	table	framexml
+DropDownList3Button2ColorSwatchSwatchBg	table	framexml
+DropDownList3Button2ExpandArrow	table	framexml
+DropDownList3Button2Highlight	table	framexml
+DropDownList3Button2Icon	table	framexml
+DropDownList3Button2InvisibleButton	table	framexml
+DropDownList3Button2NormalText	table	framexml
+DropDownList3Button3	table	framexml
+DropDownList3Button30	table	framexml
+DropDownList3Button30Check	table	framexml
+DropDownList3Button30ColorSwatch	table	framexml
+DropDownList3Button30ColorSwatchNormalTexture	table	framexml
+DropDownList3Button30ColorSwatchSwatchBg	table	framexml
+DropDownList3Button30ExpandArrow	table	framexml
+DropDownList3Button30Highlight	table	framexml
+DropDownList3Button30Icon	table	framexml
+DropDownList3Button30InvisibleButton	table	framexml
+DropDownList3Button30NormalText	table	framexml
+DropDownList3Button31	table	framexml
+DropDownList3Button31Check	table	framexml
+DropDownList3Button31ColorSwatch	table	framexml
+DropDownList3Button31ColorSwatchNormalTexture	table	framexml
+DropDownList3Button31ColorSwatchSwatchBg	table	framexml
+DropDownList3Button31ExpandArrow	table	framexml
+DropDownList3Button31Highlight	table	framexml
+DropDownList3Button31Icon	table	framexml
+DropDownList3Button31InvisibleButton	table	framexml
+DropDownList3Button31NormalText	table	framexml
+DropDownList3Button32	table	framexml
+DropDownList3Button32Check	table	framexml
+DropDownList3Button32ColorSwatch	table	framexml
+DropDownList3Button32ColorSwatchNormalTexture	table	framexml
+DropDownList3Button32ColorSwatchSwatchBg	table	framexml
+DropDownList3Button32ExpandArrow	table	framexml
+DropDownList3Button32Highlight	table	framexml
+DropDownList3Button32Icon	table	framexml
+DropDownList3Button32InvisibleButton	table	framexml
+DropDownList3Button32NormalText	table	framexml
+DropDownList3Button3Check	table	framexml
+DropDownList3Button3ColorSwatch	table	framexml
+DropDownList3Button3ColorSwatchNormalTexture	table	framexml
+DropDownList3Button3ColorSwatchSwatchBg	table	framexml
+DropDownList3Button3ExpandArrow	table	framexml
+DropDownList3Button3Highlight	table	framexml
+DropDownList3Button3Icon	table	framexml
+DropDownList3Button3InvisibleButton	table	framexml
+DropDownList3Button3NormalText	table	framexml
+DropDownList3Button4	table	framexml
+DropDownList3Button4Check	table	framexml
+DropDownList3Button4ColorSwatch	table	framexml
+DropDownList3Button4ColorSwatchNormalTexture	table	framexml
+DropDownList3Button4ColorSwatchSwatchBg	table	framexml
+DropDownList3Button4ExpandArrow	table	framexml
+DropDownList3Button4Highlight	table	framexml
+DropDownList3Button4Icon	table	framexml
+DropDownList3Button4InvisibleButton	table	framexml
+DropDownList3Button4NormalText	table	framexml
+DropDownList3Button5	table	framexml
+DropDownList3Button5Check	table	framexml
+DropDownList3Button5ColorSwatch	table	framexml
+DropDownList3Button5ColorSwatchNormalTexture	table	framexml
+DropDownList3Button5ColorSwatchSwatchBg	table	framexml
+DropDownList3Button5ExpandArrow	table	framexml
+DropDownList3Button5Highlight	table	framexml
+DropDownList3Button5Icon	table	framexml
+DropDownList3Button5InvisibleButton	table	framexml
+DropDownList3Button5NormalText	table	framexml
+DropDownList3Button6	table	framexml
+DropDownList3Button6Check	table	framexml
+DropDownList3Button6ColorSwatch	table	framexml
+DropDownList3Button6ColorSwatchNormalTexture	table	framexml
+DropDownList3Button6ColorSwatchSwatchBg	table	framexml
+DropDownList3Button6ExpandArrow	table	framexml
+DropDownList3Button6Highlight	table	framexml
+DropDownList3Button6Icon	table	framexml
+DropDownList3Button6InvisibleButton	table	framexml
+DropDownList3Button6NormalText	table	framexml
+DropDownList3Button7	table	framexml
+DropDownList3Button7Check	table	framexml
+DropDownList3Button7ColorSwatch	table	framexml
+DropDownList3Button7ColorSwatchNormalTexture	table	framexml
+DropDownList3Button7ColorSwatchSwatchBg	table	framexml
+DropDownList3Button7ExpandArrow	table	framexml
+DropDownList3Button7Highlight	table	framexml
+DropDownList3Button7Icon	table	framexml
+DropDownList3Button7InvisibleButton	table	framexml
+DropDownList3Button7NormalText	table	framexml
+DropDownList3Button8	table	framexml
+DropDownList3Button8Check	table	framexml
+DropDownList3Button8ColorSwatch	table	framexml
+DropDownList3Button8ColorSwatchNormalTexture	table	framexml
+DropDownList3Button8ColorSwatchSwatchBg	table	framexml
+DropDownList3Button8ExpandArrow	table	framexml
+DropDownList3Button8Highlight	table	framexml
+DropDownList3Button8Icon	table	framexml
+DropDownList3Button8InvisibleButton	table	framexml
+DropDownList3Button8NormalText	table	framexml
+DropDownList3Button9	table	framexml
+DropDownList3Button9Check	table	framexml
+DropDownList3Button9ColorSwatch	table	framexml
+DropDownList3Button9ColorSwatchNormalTexture	table	framexml
+DropDownList3Button9ColorSwatchSwatchBg	table	framexml
+DropDownList3Button9ExpandArrow	table	framexml
+DropDownList3Button9Highlight	table	framexml
+DropDownList3Button9Icon	table	framexml
+DropDownList3Button9InvisibleButton	table	framexml
+DropDownList3Button9NormalText	table	framexml
+DropDownList3MenuBackdrop	table	framexml
+DropFunc	lod	framexml
+DropItemOnUnit	function	engine
+DurabilityChest	table	framexml
+DurabilityFeet	table	framexml
+DurabilityFrame	table	framexml
+DurabilityFrame_OnUpdate	function	framexml
+DurabilityFrame_SetAlerts	function	framexml
+DurabilityFrame_UpdatePosition	lod	framexml
+DurabilityHands	table	framexml
+DurabilityHead	table	framexml
+DurabilityLegs	table	framexml
+DurabilityOffWeapon	table	framexml
+DurabilityRanged	table	framexml
+DurabilityShield	table	framexml
+DurabilityShoulders	table	framexml
+DurabilityWaist	table	framexml
+DurabilityWeapon	table	framexml
+DurabilityWrists	table	framexml
+EDIT_TICKET	string	framexml
+EFFECTS_LABEL	string	framexml
+ELITE	string	framexml
+EMBLEM_BACKGROUND	string	framexml
+EMBLEM_BORDER	string	framexml
+EMBLEM_BORDER_COLOR	string	framexml
+EMBLEM_SYMBOL	string	framexml
+EMBLEM_SYMBOL_COLOR	string	framexml
+EMOTE100_CMD1	string	framexml
+EMOTE100_CMD2	string	framexml
+EMOTE100_TOKEN	string	framexml
+EMOTE101_CMD	string	framexml
+EMOTE101_CMD1	string	framexml
+EMOTE101_CMD2	string	framexml
+EMOTE101_CMD3	string	framexml
+EMOTE101_TOKEN	string	framexml
+EMOTE102_CMD1	string	framexml
+EMOTE102_CMD2	string	framexml
+EMOTE102_TOKEN	string	framexml
+EMOTE103_CMD1	string	framexml
+EMOTE103_CMD2	string	framexml
+EMOTE103_TOKEN	string	framexml
+EMOTE104_CMD1	string	framexml
+EMOTE104_CMD2	string	framexml
+EMOTE104_TOKEN	string	framexml
+EMOTE105_CMD1	string	framexml
+EMOTE105_CMD2	string	framexml
+EMOTE105_TOKEN	string	framexml
+EMOTE106_CMD1	string	framexml
+EMOTE106_CMD2	string	framexml
+EMOTE106_TOKEN	string	framexml
+EMOTE107_CMD1	string	framexml
+EMOTE107_CMD2	string	framexml
+EMOTE107_CMD3	string	framexml
+EMOTE107_TOKEN	string	framexml
+EMOTE108_CMD1	string	framexml
+EMOTE108_CMD2	string	framexml
+EMOTE108_TOKEN	string	framexml
+EMOTE109_CMD1	string	framexml
+EMOTE109_CMD2	string	framexml
+EMOTE109_CMD3	string	framexml
+EMOTE109_TOKEN	string	framexml
+EMOTE10_CMD1	string	framexml
+EMOTE10_CMD2	string	framexml
+EMOTE10_CMD3	string	framexml
+EMOTE10_CMD4	string	framexml
+EMOTE10_TOKEN	string	framexml
+EMOTE110_CMD1	string	framexml
+EMOTE110_CMD2	string	framexml
+EMOTE110_TOKEN	string	framexml
+EMOTE111_CMD1	string	framexml
+EMOTE111_CMD2	string	framexml
+EMOTE111_TOKEN	string	framexml
+EMOTE112_CMD1	string	framexml
+EMOTE112_CMD2	string	framexml
+EMOTE112_CMD3	string	framexml
+EMOTE112_CMD4	string	framexml
+EMOTE112_TOKEN	string	framexml
+EMOTE113_CMD1	string	framexml
+EMOTE113_CMD2	string	framexml
+EMOTE113_TOKEN	string	framexml
+EMOTE114_CMD1	string	framexml
+EMOTE114_CMD2	string	framexml
+EMOTE114_CMD3	string	framexml
+EMOTE114_TOKEN	string	framexml
+EMOTE115_CMD1	string	framexml
+EMOTE115_CMD2	string	framexml
+EMOTE115_TOKEN	string	framexml
+EMOTE116_CMD1	string	framexml
+EMOTE116_CMD2	string	framexml
+EMOTE116_TOKEN	string	framexml
+EMOTE117_CMD1	string	framexml
+EMOTE117_CMD2	string	framexml
+EMOTE117_TOKEN	string	framexml
+EMOTE118_CMD1	string	framexml
+EMOTE118_CMD2	string	framexml
+EMOTE118_TOKEN	string	framexml
+EMOTE119_CMD1	string	framexml
+EMOTE119_CMD2	string	framexml
+EMOTE119_TOKEN	string	framexml
+EMOTE11_CMD1	string	framexml
+EMOTE11_CMD2	string	framexml
+EMOTE11_TOKEN	string	framexml
+EMOTE120_CMD1	string	framexml
+EMOTE120_CMD2	string	framexml
+EMOTE120_TOKEN	string	framexml
+EMOTE121_CMD1	string	framexml
+EMOTE121_CMD2	string	framexml
+EMOTE121_TOKEN	string	framexml
+EMOTE122_CMD1	string	framexml
+EMOTE122_CMD2	string	framexml
+EMOTE122_TOKEN	string	framexml
+EMOTE123_CMD1	string	framexml
+EMOTE123_CMD2	string	framexml
+EMOTE123_CMD3	string	framexml
+EMOTE123_CMD4	string	framexml
+EMOTE123_TOKEN	string	framexml
+EMOTE124_CMD1	string	framexml
+EMOTE124_CMD2	string	framexml
+EMOTE124_TOKEN	string	framexml
+EMOTE125_CMD1	string	framexml
+EMOTE125_CMD2	string	framexml
+EMOTE125_TOKEN	string	framexml
+EMOTE126_CMD1	string	framexml
+EMOTE126_CMD2	string	framexml
+EMOTE126_CMD3	string	framexml
+EMOTE126_CMD4	string	framexml
+EMOTE126_TOKEN	string	framexml
+EMOTE127_CMD1	string	framexml
+EMOTE127_CMD2	string	framexml
+EMOTE127_CMD3	string	framexml
+EMOTE127_CMD4	string	framexml
+EMOTE127_TOKEN	string	framexml
+EMOTE128_CMD1	string	framexml
+EMOTE128_CMD2	string	framexml
+EMOTE128_TOKEN	string	framexml
+EMOTE129_CMD1	string	framexml
+EMOTE129_CMD2	string	framexml
+EMOTE129_TOKEN	string	framexml
+EMOTE12_CMD1	string	framexml
+EMOTE12_CMD2	string	framexml
+EMOTE12_TOKEN	string	framexml
+EMOTE130_CMD1	string	framexml
+EMOTE130_CMD2	string	framexml
+EMOTE130_CMD3	string	framexml
+EMOTE130_CMD4	string	framexml
+EMOTE130_TOKEN	string	framexml
+EMOTE131_CMD1	string	framexml
+EMOTE131_CMD2	string	framexml
+EMOTE131_TOKEN	string	framexml
+EMOTE132_CMD1	string	framexml
+EMOTE132_CMD2	string	framexml
+EMOTE132_TOKEN	string	framexml
+EMOTE133_CMD1	string	framexml
+EMOTE133_CMD2	string	framexml
+EMOTE133_TOKEN	string	framexml
+EMOTE134_CMD1	string	framexml
+EMOTE134_CMD2	string	framexml
+EMOTE134_TOKEN	string	framexml
+EMOTE135_CMD1	string	framexml
+EMOTE135_CMD2	string	framexml
+EMOTE135_TOKEN	string	framexml
+EMOTE136_CMD1	string	framexml
+EMOTE136_CMD2	string	framexml
+EMOTE136_CMD3	string	framexml
+EMOTE136_CMD4	string	framexml
+EMOTE136_TOKEN	string	framexml
+EMOTE137_CMD1	string	framexml
+EMOTE137_CMD2	string	framexml
+EMOTE137_TOKEN	string	framexml
+EMOTE138_CMD1	string	framexml
+EMOTE138_CMD2	string	framexml
+EMOTE138_TOKEN	string	framexml
+EMOTE139_CMD1	string	framexml
+EMOTE139_CMD2	string	framexml
+EMOTE139_TOKEN	string	framexml
+EMOTE13_CMD1	string	framexml
+EMOTE13_CMD2	string	framexml
+EMOTE13_CMD3	string	framexml
+EMOTE13_CMD4	string	framexml
+EMOTE13_TOKEN	string	framexml
+EMOTE140_CMD1	string	framexml
+EMOTE140_CMD2	string	framexml
+EMOTE140_TOKEN	string	framexml
+EMOTE141_CMD1	string	framexml
+EMOTE141_CMD2	string	framexml
+EMOTE141_TOKEN	string	framexml
+EMOTE142_CMD1	string	framexml
+EMOTE142_CMD2	string	framexml
+EMOTE142_TOKEN	string	framexml
+EMOTE143_CMD1	string	framexml
+EMOTE143_CMD2	string	framexml
+EMOTE143_TOKEN	string	framexml
+EMOTE144_CMD1	string	framexml
+EMOTE144_CMD2	string	framexml
+EMOTE144_TOKEN	string	framexml
+EMOTE145_CMD1	string	framexml
+EMOTE145_CMD2	string	framexml
+EMOTE145_TOKEN	string	framexml
+EMOTE146_CMD1	string	framexml
+EMOTE146_CMD2	string	framexml
+EMOTE146_TOKEN	string	framexml
+EMOTE147_CMD1	string	framexml
+EMOTE147_CMD2	string	framexml
+EMOTE147_TOKEN	string	framexml
+EMOTE148_CMD1	string	framexml
+EMOTE148_CMD2	string	framexml
+EMOTE148_TOKEN	string	framexml
+EMOTE149_CMD1	string	framexml
+EMOTE149_CMD2	string	framexml
+EMOTE149_TOKEN	string	framexml
+EMOTE14_CMD1	string	framexml
+EMOTE14_CMD2	string	framexml
+EMOTE14_TOKEN	string	framexml
+EMOTE150_CMD1	string	framexml
+EMOTE150_CMD2	string	framexml
+EMOTE150_TOKEN	string	framexml
+EMOTE151_CMD1	string	framexml
+EMOTE151_CMD2	string	framexml
+EMOTE151_TOKEN	string	framexml
+EMOTE152_CMD1	string	framexml
+EMOTE152_CMD2	string	framexml
+EMOTE152_TOKEN	string	framexml
+EMOTE153_CMD1	string	framexml
+EMOTE153_CMD2	string	framexml
+EMOTE153_TOKEN	string	framexml
+EMOTE154_CMD1	string	framexml
+EMOTE154_CMD2	string	framexml
+EMOTE154_TOKEN	string	framexml
+EMOTE155_CMD1	string	framexml
+EMOTE155_CMD2	string	framexml
+EMOTE155_TOKEN	string	framexml
+EMOTE156_CMD1	string	framexml
+EMOTE156_CMD2	string	framexml
+EMOTE156_TOKEN	string	framexml
+EMOTE157_CMD1	string	framexml
+EMOTE157_CMD2	string	framexml
+EMOTE157_TOKEN	string	framexml
+EMOTE158_CMD1	string	framexml
+EMOTE158_CMD2	string	framexml
+EMOTE158_TOKEN	string	framexml
+EMOTE159_CMD1	string	framexml
+EMOTE159_CMD2	string	framexml
+EMOTE159_TOKEN	string	framexml
+EMOTE15_CMD1	string	framexml
+EMOTE15_CMD2	string	framexml
+EMOTE15_TOKEN	string	framexml
+EMOTE160_CMD1	string	framexml
+EMOTE160_CMD2	string	framexml
+EMOTE160_TOKEN	string	framexml
+EMOTE161_CMD1	string	framexml
+EMOTE161_CMD2	string	framexml
+EMOTE161_TOKEN	string	framexml
+EMOTE162_CMD1	string	framexml
+EMOTE162_CMD2	string	framexml
+EMOTE162_TOKEN	string	framexml
+EMOTE163_CMD1	string	framexml
+EMOTE163_CMD2	string	framexml
+EMOTE163_TOKEN	string	framexml
+EMOTE164_CMD1	string	framexml
+EMOTE164_CMD2	string	framexml
+EMOTE164_TOKEN	string	framexml
+EMOTE165_CMD1	string	framexml
+EMOTE165_CMD2	string	framexml
+EMOTE165_TOKEN	string	framexml
+EMOTE166_CMD1	string	framexml
+EMOTE166_CMD2	string	framexml
+EMOTE166_TOKEN	string	framexml
+EMOTE167_CMD1	string	framexml
+EMOTE167_CMD2	string	framexml
+EMOTE167_TOKEN	string	framexml
+EMOTE168_CMD1	string	framexml
+EMOTE168_CMD2	string	framexml
+EMOTE168_TOKEN	string	framexml
+EMOTE169_CMD1	string	framexml
+EMOTE169_CMD2	string	framexml
+EMOTE169_TOKEN	string	framexml
+EMOTE16_CMD1	string	framexml
+EMOTE16_CMD2	string	framexml
+EMOTE16_TOKEN	string	framexml
+EMOTE170_CMD1	string	framexml
+EMOTE170_CMD2	string	framexml
+EMOTE170_TOKEN	string	framexml
+EMOTE17_CMD1	string	framexml
+EMOTE17_CMD2	string	framexml
+EMOTE17_TOKEN	string	framexml
+EMOTE18_CMD1	string	framexml
+EMOTE18_CMD2	string	framexml
+EMOTE18_CMD3	string	framexml
+EMOTE18_CMD4	string	framexml
+EMOTE18_TOKEN	string	framexml
+EMOTE19_CMD1	string	framexml
+EMOTE19_CMD2	string	framexml
+EMOTE19_CMD3	string	framexml
+EMOTE19_CMD4	string	framexml
+EMOTE19_CMD5	string	framexml
+EMOTE19_CMD6	string	framexml
+EMOTE19_TOKEN	string	framexml
+EMOTE1_CMD1	string	framexml
+EMOTE1_CMD2	string	framexml
+EMOTE1_TOKEN	string	framexml
+EMOTE20_CMD1	string	framexml
+EMOTE20_CMD2	string	framexml
+EMOTE20_TOKEN	string	framexml
+EMOTE21_CMD1	string	framexml
+EMOTE21_CMD2	string	framexml
+EMOTE21_TOKEN	string	framexml
+EMOTE22_CMD1	string	framexml
+EMOTE22_CMD2	string	framexml
+EMOTE22_CMD3	string	framexml
+EMOTE22_CMD4	string	framexml
+EMOTE22_CMD5	string	framexml
+EMOTE22_CMD6	string	framexml
+EMOTE22_TOKEN	string	framexml
+EMOTE23_CMD1	string	framexml
+EMOTE23_CMD2	string	framexml
+EMOTE23_TOKEN	string	framexml
+EMOTE24_CMD1	string	framexml
+EMOTE24_CMD2	string	framexml
+EMOTE24_TOKEN	string	framexml
+EMOTE25_CMD1	string	framexml
+EMOTE25_CMD2	string	framexml
+EMOTE25_TOKEN	string	framexml
+EMOTE26_CMD1	string	framexml
+EMOTE26_CMD2	string	framexml
+EMOTE26_CMD3	string	framexml
+EMOTE26_CMD4	string	framexml
+EMOTE26_CMD5	string	framexml
+EMOTE26_CMD6	string	framexml
+EMOTE26_TOKEN	string	framexml
+EMOTE27_CMD1	string	framexml
+EMOTE27_CMD2	string	framexml
+EMOTE27_TOKEN	string	framexml
+EMOTE28_CMD1	string	framexml
+EMOTE28_CMD2	string	framexml
+EMOTE28_TOKEN	string	framexml
+EMOTE29_CMD1	string	framexml
+EMOTE29_CMD2	string	framexml
+EMOTE29_CMD3	string	framexml
+EMOTE29_CMD4	string	framexml
+EMOTE29_TOKEN	string	framexml
+EMOTE2_CMD1	string	framexml
+EMOTE2_CMD2	string	framexml
+EMOTE2_TOKEN	string	framexml
+EMOTE30_CMD1	string	framexml
+EMOTE30_CMD2	string	framexml
+EMOTE30_CMD3	string	framexml
+EMOTE30_CMD4	string	framexml
+EMOTE30_TOKEN	string	framexml
+EMOTE31_CMD1	string	framexml
+EMOTE31_CMD2	string	framexml
+EMOTE31_TOKEN	string	framexml
+EMOTE32_CMD1	string	framexml
+EMOTE32_CMD2	string	framexml
+EMOTE32_CMD3	string	framexml
+EMOTE32_CMD4	string	framexml
+EMOTE32_CMD5	string	framexml
+EMOTE32_CMD6	string	framexml
+EMOTE32_TOKEN	string	framexml
+EMOTE33_CMD1	string	framexml
+EMOTE33_CMD2	string	framexml
+EMOTE33_TOKEN	string	framexml
+EMOTE34_CMD1	string	framexml
+EMOTE34_CMD2	string	framexml
+EMOTE34_TOKEN	string	framexml
+EMOTE35_CMD1	string	framexml
+EMOTE35_CMD2	string	framexml
+EMOTE35_TOKEN	string	framexml
+EMOTE36_CMD1	string	framexml
+EMOTE36_CMD2	string	framexml
+EMOTE36_CMD3	string	framexml
+EMOTE36_CMD4	string	framexml
+EMOTE36_TOKEN	string	framexml
+EMOTE37_CMD1	string	framexml
+EMOTE37_CMD2	string	framexml
+EMOTE37_TOKEN	string	framexml
+EMOTE38_CMD1	string	framexml
+EMOTE38_CMD2	string	framexml
+EMOTE38_CMD3	string	framexml
+EMOTE38_CMD4	string	framexml
+EMOTE38_CMD5	string	framexml
+EMOTE38_CMD6	string	framexml
+EMOTE38_TOKEN	string	framexml
+EMOTE39_CMD1	string	framexml
+EMOTE39_CMD2	string	framexml
+EMOTE39_TOKEN	string	framexml
+EMOTE3_CMD1	string	framexml
+EMOTE3_CMD2	string	framexml
+EMOTE3_CMD3	string	framexml
+EMOTE3_CMD4	string	framexml
+EMOTE3_TOKEN	string	framexml
+EMOTE40_CMD1	string	framexml
+EMOTE40_CMD2	string	framexml
+EMOTE40_TOKEN	string	framexml
+EMOTE41_CMD1	string	framexml
+EMOTE41_CMD2	string	framexml
+EMOTE41_CMD3	string	framexml
+EMOTE41_CMD4	string	framexml
+EMOTE41_TOKEN	string	framexml
+EMOTE42_CMD1	string	framexml
+EMOTE42_CMD2	string	framexml
+EMOTE42_CMD3	string	framexml
+EMOTE42_CMD4	string	framexml
+EMOTE42_TOKEN	string	framexml
+EMOTE43_CMD1	string	framexml
+EMOTE43_CMD2	string	framexml
+EMOTE43_CMD3	string	framexml
+EMOTE43_CMD4	string	framexml
+EMOTE43_CMD5	string	framexml
+EMOTE43_CMD6	string	framexml
+EMOTE43_TOKEN	string	framexml
+EMOTE44_CMD1	string	framexml
+EMOTE44_CMD2	string	framexml
+EMOTE44_CMD3	string	framexml
+EMOTE44_TOKEN	string	framexml
+EMOTE45_CMD1	string	framexml
+EMOTE45_CMD2	string	framexml
+EMOTE45_TOKEN	string	framexml
+EMOTE46_CMD1	string	framexml
+EMOTE46_CMD2	string	framexml
+EMOTE46_TOKEN	string	framexml
+EMOTE47_CMD1	string	framexml
+EMOTE47_CMD2	string	framexml
+EMOTE47_TOKEN	string	framexml
+EMOTE48_CMD1	string	framexml
+EMOTE48_CMD2	string	framexml
+EMOTE48_TOKEN	string	framexml
+EMOTE49_CMD1	string	framexml
+EMOTE49_CMD2	string	framexml
+EMOTE49_CMD3	string	framexml
+EMOTE49_CMD4	string	framexml
+EMOTE49_TOKEN	string	framexml
+EMOTE4_CMD1	string	framexml
+EMOTE4_CMD2	string	framexml
+EMOTE4_CMD3	string	framexml
+EMOTE4_CMD4	string	framexml
+EMOTE4_TOKEN	string	framexml
+EMOTE50_CMD1	string	framexml
+EMOTE50_CMD2	string	framexml
+EMOTE50_CMD3	string	framexml
+EMOTE50_CMD4	string	framexml
+EMOTE50_CMD5	string	framexml
+EMOTE50_CMD6	string	framexml
+EMOTE50_TOKEN	string	framexml
+EMOTE51_CMD1	string	framexml
+EMOTE51_CMD2	string	framexml
+EMOTE51_TOKEN	string	framexml
+EMOTE52_CMD1	string	framexml
+EMOTE52_CMD2	string	framexml
+EMOTE52_CMD3	string	framexml
+EMOTE52_CMD4	string	framexml
+EMOTE52_TOKEN	string	framexml
+EMOTE53_CMD1	string	framexml
+EMOTE53_CMD2	string	framexml
+EMOTE53_TOKEN	string	framexml
+EMOTE54_CMD1	string	framexml
+EMOTE54_CMD2	string	framexml
+EMOTE54_TOKEN	string	framexml
+EMOTE55_CMD1	string	framexml
+EMOTE55_CMD2	string	framexml
+EMOTE55_CMD3	string	framexml
+EMOTE55_CMD4	string	framexml
+EMOTE55_CMD5	string	framexml
+EMOTE55_CMD6	string	framexml
+EMOTE55_TOKEN	string	framexml
+EMOTE56_CMD1	string	framexml
+EMOTE56_CMD2	string	framexml
+EMOTE56_CMD3	string	framexml
+EMOTE56_CMD4	string	framexml
+EMOTE56_TOKEN	string	framexml
+EMOTE57_CMD1	string	framexml
+EMOTE57_CMD2	string	framexml
+EMOTE57_TOKEN	string	framexml
+EMOTE58_CMD1	string	framexml
+EMOTE58_CMD2	string	framexml
+EMOTE58_CMD3	string	framexml
+EMOTE58_CMD4	string	framexml
+EMOTE58_CMD5	string	framexml
+EMOTE58_CMD6	string	framexml
+EMOTE58_TOKEN	string	framexml
+EMOTE59_CMD1	string	framexml
+EMOTE59_CMD2	string	framexml
+EMOTE59_CMD3	string	framexml
+EMOTE59_CMD4	string	framexml
+EMOTE59_TOKEN	string	framexml
+EMOTE5_CMD1	string	framexml
+EMOTE5_CMD2	string	framexml
+EMOTE5_CMD3	string	framexml
+EMOTE5_CMD4	string	framexml
+EMOTE5_CMD5	string	framexml
+EMOTE5_CMD6	string	framexml
+EMOTE5_TOKEN	string	framexml
+EMOTE60_CMD1	string	framexml
+EMOTE60_CMD2	string	framexml
+EMOTE60_CMD3	string	framexml
+EMOTE60_TOKEN	string	framexml
+EMOTE61_CMD1	string	framexml
+EMOTE61_CMD2	string	framexml
+EMOTE61_CMD3	string	framexml
+EMOTE61_CMD4	string	framexml
+EMOTE61_TOKEN	string	framexml
+EMOTE62_CMD1	string	framexml
+EMOTE62_CMD2	string	framexml
+EMOTE62_CMD3	string	framexml
+EMOTE62_CMD4	string	framexml
+EMOTE62_CMD5	string	framexml
+EMOTE62_CMD6	string	framexml
+EMOTE62_CMD7	string	framexml
+EMOTE62_CMD8	string	framexml
+EMOTE62_TOKEN	string	framexml
+EMOTE63_CMD1	string	framexml
+EMOTE63_CMD2	string	framexml
+EMOTE63_TOKEN	string	framexml
+EMOTE64_CMD1	string	framexml
+EMOTE64_CMD2	string	framexml
+EMOTE64_TOKEN	string	framexml
+EMOTE65_CMD1	string	framexml
+EMOTE65_CMD2	string	framexml
+EMOTE65_TOKEN	string	framexml
+EMOTE66_CMD1	string	framexml
+EMOTE66_CMD2	string	framexml
+EMOTE66_TOKEN	string	framexml
+EMOTE67_CMD1	string	framexml
+EMOTE67_CMD2	string	framexml
+EMOTE67_TOKEN	string	framexml
+EMOTE68_CMD1	string	framexml
+EMOTE68_CMD2	string	framexml
+EMOTE68_CMD3	string	framexml
+EMOTE68_CMD4	string	framexml
+EMOTE68_TOKEN	string	framexml
+EMOTE69_CMD1	string	framexml
+EMOTE69_CMD2	string	framexml
+EMOTE69_CMD3	string	framexml
+EMOTE69_CMD4	string	framexml
+EMOTE69_TOKEN	string	framexml
+EMOTE6_CMD1	string	framexml
+EMOTE6_CMD2	string	framexml
+EMOTE6_TOKEN	string	framexml
+EMOTE70_CMD1	string	framexml
+EMOTE70_CMD2	string	framexml
+EMOTE70_TOKEN	string	framexml
+EMOTE71_CMD1	string	framexml
+EMOTE71_CMD2	string	framexml
+EMOTE71_TOKEN	string	framexml
+EMOTE72_CMD1	string	framexml
+EMOTE72_CMD2	string	framexml
+EMOTE72_TOKEN	string	framexml
+EMOTE73_CMD1	string	framexml
+EMOTE73_CMD2	string	framexml
+EMOTE73_TOKEN	string	framexml
+EMOTE74_CMD1	string	framexml
+EMOTE74_CMD2	string	framexml
+EMOTE74_TOKEN	string	framexml
+EMOTE75_CMD1	string	framexml
+EMOTE75_CMD2	string	framexml
+EMOTE75_TOKEN	string	framexml
+EMOTE76_CMD1	string	framexml
+EMOTE76_CMD2	string	framexml
+EMOTE76_TOKEN	string	framexml
+EMOTE77_CMD1	string	framexml
+EMOTE77_CMD2	string	framexml
+EMOTE77_TOKEN	string	framexml
+EMOTE78_CMD1	string	framexml
+EMOTE78_CMD2	string	framexml
+EMOTE78_TOKEN	string	framexml
+EMOTE79_CMD1	string	framexml
+EMOTE79_CMD2	string	framexml
+EMOTE79_TOKEN	string	framexml
+EMOTE7_CMD1	string	framexml
+EMOTE7_CMD2	string	framexml
+EMOTE7_TOKEN	string	framexml
+EMOTE80_CMD1	string	framexml
+EMOTE80_CMD2	string	framexml
+EMOTE80_CMD3	string	framexml
+EMOTE80_CMD4	string	framexml
+EMOTE80_CMD5	string	framexml
+EMOTE80_CMD6	string	framexml
+EMOTE80_TOKEN	string	framexml
+EMOTE81_CMD1	string	framexml
+EMOTE81_CMD2	string	framexml
+EMOTE81_TOKEN	string	framexml
+EMOTE82_CMD1	string	framexml
+EMOTE82_CMD2	string	framexml
+EMOTE82_CMD3	string	framexml
+EMOTE82_CMD4	string	framexml
+EMOTE82_TOKEN	string	framexml
+EMOTE83_CMD1	string	framexml
+EMOTE83_TOKEN	string	framexml
+EMOTE84_CMD1	string	framexml
+EMOTE84_CMD2	string	framexml
+EMOTE84_TOKEN	string	framexml
+EMOTE85_CMD1	string	framexml
+EMOTE85_CMD2	string	framexml
+EMOTE85_TOKEN	string	framexml
+EMOTE86_CMD1	string	framexml
+EMOTE86_CMD2	string	framexml
+EMOTE86_TOKEN	string	framexml
+EMOTE87_CMD1	string	framexml
+EMOTE87_CMD2	string	framexml
+EMOTE87_TOKEN	string	framexml
+EMOTE88_CMD1	string	framexml
+EMOTE88_CMD2	string	framexml
+EMOTE88_TOKEN	string	framexml
+EMOTE89_CMD1	string	framexml
+EMOTE89_CMD2	string	framexml
+EMOTE89_TOKEN	string	framexml
+EMOTE8_CMD1	string	framexml
+EMOTE8_CMD2	string	framexml
+EMOTE8_TOKEN	string	framexml
+EMOTE90_CMD1	string	framexml
+EMOTE90_CMD2	string	framexml
+EMOTE90_TOKEN	string	framexml
+EMOTE91_CMD1	string	framexml
+EMOTE91_CMD2	string	framexml
+EMOTE91_TOKEN	string	framexml
+EMOTE92_CMD1	string	framexml
+EMOTE92_CMD2	string	framexml
+EMOTE92_TOKEN	string	framexml
+EMOTE93_CMD1	string	framexml
+EMOTE93_CMD2	string	framexml
+EMOTE93_TOKEN	string	framexml
+EMOTE94_CMD1	string	framexml
+EMOTE94_CMD2	string	framexml
+EMOTE94_TOKEN	string	framexml
+EMOTE95_CMD1	string	framexml
+EMOTE95_CMD2	string	framexml
+EMOTE95_CMD3	string	framexml
+EMOTE95_CMD4	string	framexml
+EMOTE95_TOKEN	string	framexml
+EMOTE96_CMD1	string	framexml
+EMOTE96_CMD2	string	framexml
+EMOTE96_CMD3	string	framexml
+EMOTE96_CMD4	string	framexml
+EMOTE96_TOKEN	string	framexml
+EMOTE97_CMD1	string	framexml
+EMOTE97_CMD2	string	framexml
+EMOTE97_TOKEN	string	framexml
+EMOTE98_CMD1	string	framexml
+EMOTE98_CMD2	string	framexml
+EMOTE98_CMD3	string	framexml
+EMOTE98_CMD4	string	framexml
+EMOTE98_CMD5	string	framexml
+EMOTE98_CMD6	string	framexml
+EMOTE98_TOKEN	string	framexml
+EMOTE99_CMD1	string	framexml
+EMOTE99_CMD2	string	framexml
+EMOTE99_CMD3	string	framexml
+EMOTE99_CMD4	string	framexml
+EMOTE99_CMD5	string	framexml
+EMOTE99_CMD6	string	framexml
+EMOTE99_CMD7	string	framexml
+EMOTE99_CMD8	string	framexml
+EMOTE99_TOKEN	string	framexml
+EMOTE9_CMD1	string	framexml
+EMOTE9_CMD2	string	framexml
+EMOTE9_TOKEN	string	framexml
+EMOTE_MESSAGE	string	framexml
+EMOTE_STATE_KNEEL	string	framexml
+EMPTY	string	framexml
+EMPTY_STABLE_SLOT	string	framexml
+ENABLE_ALL_SHADERS	string	framexml
+ENABLE_ALL_SOUND	string	framexml
+ENABLE_AMBIENCE	string	framexml
+ENABLE_EMOTE_SOUNDS	string	framexml
+ENABLE_ERROR_SPEECH	string	framexml
+ENABLE_GROUP_SPEECH	string	framexml
+ENABLE_MUSIC	string	framexml
+ENABLE_MUSIC_LOOPING	string	framexml
+ENABLE_SOUND	string	framexml
+ENABLE_SOUND_AT_CHARACTER	string	framexml
+ENABLE_TUTORIAL_TEXT	string	framexml
+ENCHANT_SLOT	string	framexml
+ENCLOSED_MONEY	string	framexml
+ENERGY	string	framexml
+ENERGY_COST	string	framexml
+ENERGY_COST_PER_TIME	string	framexml
+ENERGY_POINTS	string	framexml
+ENSCRIBE	string	framexml
+ENTERING_COMBAT	string	framexml
+ENTER_BATTLE	string	framexml
+ENTER_CODE	string	framexml
+ENTER_MACRO_LABEL	string	framexml
+ENVIRONMENT_DETAIL	string	framexml
+EQUIP_CONTAINER	string	framexml
+EQUIP_NO_DROP	string	framexml
+ERROR_CAPS	string	framexml
+ERR_2HANDED_EQUIPPED	string	framexml
+ERR_2HSKILLNOTFOUND	string	framexml
+ERR_ABILITY_COOLDOWN	string	framexml
+ERR_ALREADY_INVITED_TO_GUILD_S	string	framexml
+ERR_ALREADY_IN_GROUP_S	string	framexml
+ERR_ALREADY_IN_GUILD	string	framexml
+ERR_ALREADY_IN_GUILD_S	string	framexml
+ERR_ALREADY_TRADING	string	framexml
+ERR_AMMO_ONLY	string	framexml
+ERR_APPROACHING_NO_PLAY_TIME	string	framexml
+ERR_APPROACHING_PARTIAL_PLAY_TIME	string	framexml
+ERR_ATTACK_CHARMED	string	framexml
+ERR_ATTACK_CONFUSED	string	framexml
+ERR_ATTACK_DEAD	string	framexml
+ERR_ATTACK_FLEEING	string	framexml
+ERR_ATTACK_MOUNTED	string	framexml
+ERR_ATTACK_PACIFIED	string	framexml
+ERR_ATTACK_PREVENTED_BY_MECHANIC_S	string	framexml
+ERR_ATTACK_STUNNED	string	framexml
+ERR_AUCTION_BAG	string	framexml
+ERR_AUCTION_BID_INCREMENT	string	framexml
+ERR_AUCTION_BID_OWN	string	framexml
+ERR_AUCTION_BID_PLACED	string	framexml
+ERR_AUCTION_BOUND_ITEM	string	framexml
+ERR_AUCTION_CONJURED_ITEM	string	framexml
+ERR_AUCTION_DATABASE_ERROR	string	framexml
+ERR_AUCTION_EXPIRED_S	string	framexml
+ERR_AUCTION_HIGHER_BID	string	framexml
+ERR_AUCTION_LOOT_ITEM	string	framexml
+ERR_AUCTION_MIN_BID	string	framexml
+ERR_AUCTION_OUTBID_S	string	framexml
+ERR_AUCTION_QUEST_ITEM	string	framexml
+ERR_AUCTION_REMOVED	string	framexml
+ERR_AUCTION_REMOVED_S	string	framexml
+ERR_AUCTION_REPAIR_ITEM	string	framexml
+ERR_AUCTION_SOLD_S	string	framexml
+ERR_AUCTION_STARTED	string	framexml
+ERR_AUCTION_WON_S	string	framexml
+ERR_AUCTION_WRAPPED_ITEM	string	framexml
+ERR_AUTOFOLLOW_TOO_FAR	string	framexml
+ERR_AUTOLOOT_MONEY_S	string	framexml
+ERR_BADATTACKFACING	string	framexml
+ERR_BADATTACKPOS	string	framexml
+ERR_BAD_PLAYER_NAME_S	string	framexml
+ERR_BAG_FULL	string	framexml
+ERR_BAG_IN_BAG	string	framexml
+ERR_BANKSLOT_FAILED_TOO_MANY	string	framexml
+ERR_BANKSLOT_INSUFFICIENT_FUNDS	string	framexml
+ERR_BANKSLOT_NOTBANKER	string	framexml
+ERR_BANK_FULL	string	framexml
+ERR_BG_PLAYER_JOINED_SS	string	framexml
+ERR_BG_PLAYER_LEFT_S	string	framexml
+ERR_BUTTON_LOCKED	string	framexml
+ERR_CANNOTCREATEDIRECTORY	string	framexml
+ERR_CANNOTCREATEFILE	string	framexml
+ERR_CANTATTACK_NOTSTANDING	string	framexml
+ERR_CANT_EQUIP_EVER	string	framexml
+ERR_CANT_EQUIP_LEVEL_I	string	framexml
+ERR_CANT_EQUIP_RANK	string	framexml
+ERR_CANT_EQUIP_REPUTATION	string	framexml
+ERR_CANT_EQUIP_SKILL	string	framexml
+ERR_CANT_INTERACT_SHAPESHIFTED	string	framexml
+ERR_CANT_STACK	string	framexml
+ERR_CANT_SWAP	string	framexml
+ERR_CANT_USE_DISARMED	string	framexml
+ERR_CANT_USE_ITEM	string	framexml
+ERR_CANT_WRAP_BAGS	string	framexml
+ERR_CANT_WRAP_BOUND	string	framexml
+ERR_CANT_WRAP_EQUIPPED	string	framexml
+ERR_CANT_WRAP_STACKABLE	string	framexml
+ERR_CANT_WRAP_UNIQUE	string	framexml
+ERR_CANT_WRAP_WRAPPED	string	framexml
+ERR_CHAT_PLAYER_AMBIGUOUS_S	string	framexml
+ERR_CHAT_PLAYER_NOT_FOUND_S	string	framexml
+ERR_CHAT_RESTRICTED	string	framexml
+ERR_CHAT_WHILE_DEAD	string	framexml
+ERR_CHAT_WRONG_FACTION	string	framexml
+ERR_CHEST_IN_USE	string	framexml
+ERR_CLICK_ON_ITEM_TO_FEED	string	framexml
+ERR_CLIENT_LOCKED_OUT	string	framexml
+ERR_COMBAT_DAMAGE_SSI	string	framexml
+ERR_COMMAND_NEEDS_TARGET	string	framexml
+ERR_DEATHBINDALREADYBOUND	string	framexml
+ERR_DEATHBIND_SUCCESS_S	string	framexml
+ERR_DECLINE_GROUP_S	string	framexml
+ERR_DESTROY_NONEMPTY_BAG	string	framexml
+ERR_DISMOUNT_NOPET	string	framexml
+ERR_DISMOUNT_NOTMOUNTED	string	framexml
+ERR_DISMOUNT_NOTYOURPET	string	framexml
+ERR_DOOR_LOCKED	string	framexml
+ERR_DROP_BOUND_ITEM	string	framexml
+ERR_DUEL_CANCELLED	string	framexml
+ERR_DUEL_REQUESTED	string	framexml
+ERR_DUNGEON_DIFFICULTY_CHANGED_S	string	framexml
+ERR_DUNGEON_DIFFICULTY_FAILED	string	framexml
+ERR_EAT_WHILE_MOVNG	string	framexml
+ERR_EMBLEMERROR_NOTABARDGEOSET	string	framexml
+ERR_EQUIP_TRADE_ITEM	string	framexml
+ERR_EXHAUSTION_EXHAUSTED	string	framexml
+ERR_EXHAUSTION_NORMAL	string	framexml
+ERR_EXHAUSTION_RESTED	string	framexml
+ERR_EXHAUSTION_TIRED	string	framexml
+ERR_EXHAUSTION_WELLRESTED	string	framexml
+ERR_FEIGN_DEATH_RESISTED	string	framexml
+ERR_FILTERING_YOU_S	string	framexml
+ERR_FISH_ESCAPED	string	framexml
+ERR_FISH_NOT_HOOKED	string	framexml
+ERR_FOOD_COOLDOWN	string	framexml
+ERR_FRIEND_ADDED_S	string	framexml
+ERR_FRIEND_ALREADY_S	string	framexml
+ERR_FRIEND_DB_ERROR	string	framexml
+ERR_FRIEND_ERROR	string	framexml
+ERR_FRIEND_LIST_FULL	string	framexml
+ERR_FRIEND_NOT_FOUND	string	framexml
+ERR_FRIEND_OFFLINE_S	string	framexml
+ERR_FRIEND_ONLINE_SS	string	framexml
+ERR_FRIEND_REMOVED_S	string	framexml
+ERR_FRIEND_SELF	string	framexml
+ERR_FRIEND_WRONG_FACTION	string	framexml
+ERR_GENERIC_NO_TARGET	string	framexml
+ERR_GENERIC_STUNNED	string	framexml
+ERR_GROUP_DISBANDED	string	framexml
+ERR_GROUP_FULL	string	framexml
+ERR_GROUP_JOIN_BATTLEGROUND_DESERTERS	string	framexml
+ERR_GROUP_JOIN_BATTLEGROUND_FAIL	string	framexml
+ERR_GROUP_JOIN_BATTLEGROUND_S	string	framexml
+ERR_GROUP_JOIN_BATTLEGROUND_TOO_MANY	string	framexml
+ERR_GUILDEMBLEM_COLORSPRESENT	string	framexml
+ERR_GUILDEMBLEM_INVALIDVENDOR	string	framexml
+ERR_GUILDEMBLEM_INVALID_TABARD_COLORS	string	framexml
+ERR_GUILDEMBLEM_NOGUILD	string	framexml
+ERR_GUILDEMBLEM_NOTENOUGHMONEY	string	framexml
+ERR_GUILDEMBLEM_NOTGUILDMASTER	string	framexml
+ERR_GUILDEMBLEM_SAME	string	framexml
+ERR_GUILDEMBLEM_SUCCESS	string	framexml
+ERR_GUILD_ACCEPT	string	framexml
+ERR_GUILD_CREATE_S	string	framexml
+ERR_GUILD_DECLINE_S	string	framexml
+ERR_GUILD_DEMOTE_SSS	string	framexml
+ERR_GUILD_DISBANDED	string	framexml
+ERR_GUILD_DISBAND_S	string	framexml
+ERR_GUILD_DISBAND_SELF	string	framexml
+ERR_GUILD_ENTER_NAME	string	framexml
+ERR_GUILD_FOUNDER_S	string	framexml
+ERR_GUILD_INTERNAL	string	framexml
+ERR_GUILD_INVITE_S	string	framexml
+ERR_GUILD_JOIN_S	string	framexml
+ERR_GUILD_LEADER_CHANGED_SS	string	framexml
+ERR_GUILD_LEADER_IS_S	string	framexml
+ERR_GUILD_LEADER_LEAVE	string	framexml
+ERR_GUILD_LEADER_S	string	framexml
+ERR_GUILD_LEADER_SELF	string	framexml
+ERR_GUILD_LEAVE_RESULT	string	framexml
+ERR_GUILD_LEAVE_S	string	framexml
+ERR_GUILD_NAME_EXISTS_S	string	framexml
+ERR_GUILD_NAME_INVALID	string	framexml
+ERR_GUILD_NAME_INVALID_SPACE	string	framexml
+ERR_GUILD_NAME_MIXED_LANGUAGES	string	framexml
+ERR_GUILD_NAME_NAME_CONSECUTIVE_SPACES	string	framexml
+ERR_GUILD_NAME_PROFANE	string	framexml
+ERR_GUILD_NAME_RESERVED	string	framexml
+ERR_GUILD_NAME_TOO_SHORT	string	framexml
+ERR_GUILD_NOT_ALLIED	string	framexml
+ERR_GUILD_PERMISSIONS	string	framexml
+ERR_GUILD_PLAYER_NOT_FOUND_S	string	framexml
+ERR_GUILD_PLAYER_NOT_IN_GUILD	string	framexml
+ERR_GUILD_PLAYER_NOT_IN_GUILD_S	string	framexml
+ERR_GUILD_PROMOTE_SSS	string	framexml
+ERR_GUILD_QUIT_S	string	framexml
+ERR_GUILD_RANKS_LOCKED	string	framexml
+ERR_GUILD_RANK_IN_USE	string	framexml
+ERR_GUILD_RANK_TOO_HIGH_S	string	framexml
+ERR_GUILD_RANK_TOO_LOW_S	string	framexml
+ERR_GUILD_REMOVE_SELF	string	framexml
+ERR_GUILD_REMOVE_SS	string	framexml
+ERR_IGNORE_ADDED_S	string	framexml
+ERR_IGNORE_ALREADY_S	string	framexml
+ERR_IGNORE_AMBIGUOUS	string	framexml
+ERR_IGNORE_FULL	string	framexml
+ERR_IGNORE_NOT_FOUND	string	framexml
+ERR_IGNORE_REMOVED_S	string	framexml
+ERR_IGNORE_SELF	string	framexml
+ERR_IGNORING_YOU_S	string	framexml
+ERR_INITIATE_TRADE_S	string	framexml
+ERR_INSPECT_S	string	framexml
+ERR_INTERNAL_BAG_ERROR	string	framexml
+ERR_INVALID_ATTACK_TARGET	string	framexml
+ERR_INVALID_FOLLOW_TARGET	string	framexml
+ERR_INVALID_INSPECT_TARGET	string	framexml
+ERR_INVALID_ITEM_TARGET	string	framexml
+ERR_INVALID_PETNAME	string	framexml
+ERR_INVALID_PROMOTION_CODE	string	framexml
+ERR_INVALID_RAID_TARGET	string	framexml
+ERR_INVITED_TO_GROUP_S	string	framexml
+ERR_INVITED_TO_GUILD	string	framexml
+ERR_INVITED_TO_GUILD_SS	string	framexml
+ERR_INVITE_PLAYER_S	string	framexml
+ERR_INVITE_SELF	string	framexml
+ERR_INV_FULL	string	framexml
+ERR_ITEM_CANT_BE_DESTROYED	string	framexml
+ERR_ITEM_COOLDOWN	string	framexml
+ERR_ITEM_LOCKED	string	framexml
+ERR_ITEM_MAX_COUNT	string	framexml
+ERR_ITEM_NOT_FOUND	string	framexml
+ERR_JOINED_GROUP_S	string	framexml
+ERR_KILLED_BY_S	string	framexml
+ERR_LEARN_ABILITY_S	string	framexml
+ERR_LEARN_RECIPE_S	string	framexml
+ERR_LEARN_SPELL_S	string	framexml
+ERR_LEFT_GROUP_S	string	framexml
+ERR_LEFT_GROUP_YOU	string	framexml
+ERR_LOGGING_OUT	string	framexml
+ERR_LOGOUT_FAILED	string	framexml
+ERR_LOOT_BAD_FACING	string	framexml
+ERR_LOOT_CANT_LOOT_THAT_NOW	string	framexml
+ERR_LOOT_DIDNT_KILL	string	framexml
+ERR_LOOT_GONE	string	framexml
+ERR_LOOT_LOCKED	string	framexml
+ERR_LOOT_MASTER_INV_FULL	string	framexml
+ERR_LOOT_MASTER_OTHER	string	framexml
+ERR_LOOT_MASTER_UNIQUE_ITEM	string	framexml
+ERR_LOOT_NOTSTANDING	string	framexml
+ERR_LOOT_NO_UI	string	framexml
+ERR_LOOT_PLAYER_NOT_FOUND	string	framexml
+ERR_LOOT_ROLL_PENDING	string	framexml
+ERR_LOOT_STUNNED	string	framexml
+ERR_LOOT_TOO_FAR	string	framexml
+ERR_LOOT_WHILE_INVULNERABLE	string	framexml
+ERR_MAIL_BAG	string	framexml
+ERR_MAIL_BOUND_ITEM	string	framexml
+ERR_MAIL_CONJURED_ITEM	string	framexml
+ERR_MAIL_DATABASE_ERROR	string	framexml
+ERR_MAIL_QUEST_ITEM	string	framexml
+ERR_MAIL_REACHED_CAP	string	framexml
+ERR_MAIL_SENT	string	framexml
+ERR_MAIL_TARGET_NOT_FOUND	string	framexml
+ERR_MAIL_TO_SELF	string	framexml
+ERR_MEETING_STONE_GROUP_FULL	string	framexml
+ERR_MEETING_STONE_INVALID_LEVEL	string	framexml
+ERR_MEETING_STONE_IN_PROGRESS	string	framexml
+ERR_MEETING_STONE_IN_QUEUE_S	string	framexml
+ERR_MEETING_STONE_LEFT_QUEUE_S	string	framexml
+ERR_MEETING_STONE_MEMBER_ADDED_S	string	framexml
+ERR_MEETING_STONE_MEMBER_STILL_IN_QUEUE	string	framexml
+ERR_MEETING_STONE_MUST_BE_LEADER	string	framexml
+ERR_MEETING_STONE_NOT_LEADER	string	framexml
+ERR_MEETING_STONE_NO_RAID_GROUP	string	framexml
+ERR_MEETING_STONE_OTHER_MEMBER_LEFT	string	framexml
+ERR_MEETING_STONE_PARTY_KICKED_FROM_QUEUE	string	framexml
+ERR_MEETING_STONE_SUCCESS	string	framexml
+ERR_MOUNT_ALREADYMOUNTED	string	framexml
+ERR_MOUNT_FORCEDDISMOUNT	string	framexml
+ERR_MOUNT_INVALIDMOUNTEE	string	framexml
+ERR_MOUNT_LOOTING	string	framexml
+ERR_MOUNT_NOTMOUNTABLE	string	framexml
+ERR_MOUNT_NOTYOURPET	string	framexml
+ERR_MOUNT_OTHER	string	framexml
+ERR_MOUNT_RACECANTMOUNT	string	framexml
+ERR_MOUNT_SHAPESHIFTED	string	framexml
+ERR_MOUNT_TOOFARAWAY	string	framexml
+ERR_MUST_EQUIP_ITEM	string	framexml
+ERR_MUST_REPAIR_DURABILITY	string	framexml
+ERR_NEWTAXIPATH	string	framexml
+ERR_NEW_LEADER_S	string	framexml
+ERR_NEW_LEADER_YOU	string	framexml
+ERR_NEW_LOOT_MASTER_S	string	framexml
+ERR_NOAMMO_S	string	framexml
+ERR_NOEMOTEWHILERUNNING	string	framexml
+ERR_NOTYOURPET	string	framexml
+ERR_NOT_A_BAG	string	framexml
+ERR_NOT_ENOUGH_GOLD	string	framexml
+ERR_NOT_ENOUGH_MONEY	string	framexml
+ERR_NOT_EQUIPPABLE	string	framexml
+ERR_NOT_IN_BATTLEGROUND	string	framexml
+ERR_NOT_IN_COMBAT	string	framexml
+ERR_NOT_IN_GROUP	string	framexml
+ERR_NOT_IN_RAID	string	framexml
+ERR_NOT_LEADER	string	framexml
+ERR_NOT_OWNER	string	framexml
+ERR_NOT_WHILE_DISARMED	string	framexml
+ERR_NOT_WHILE_SHAPESHIFTED	string	framexml
+ERR_NO_ATTACK_TARGET	string	framexml
+ERR_NO_BANK_HERE	string	framexml
+ERR_NO_BANK_SLOT	string	framexml
+ERR_NO_GUILD_CHARTER	string	framexml
+ERR_NO_ITEMS_WHILE_SHAPESHIFTED	string	framexml
+ERR_NO_PET	string	framexml
+ERR_NO_REPLY_TARGET	string	framexml
+ERR_NO_SLOT_AVAILABLE	string	framexml
+ERR_NULL_PETNAME	string	framexml
+ERR_OBJECT_IS_BUSY	string	framexml
+ERR_ONLY_ONE_AMMO	string	framexml
+ERR_ONLY_ONE_BOLT	string	framexml
+ERR_ONLY_ONE_QUIVER	string	framexml
+ERR_OUT_OF_ENERGY	string	framexml
+ERR_OUT_OF_FOCUS	string	framexml
+ERR_OUT_OF_HEALTH	string	framexml
+ERR_OUT_OF_MANA	string	framexml
+ERR_OUT_OF_RAGE	string	framexml
+ERR_OUT_OF_RANGE	string	framexml
+ERR_PASSIVE_ABILITY	string	framexml
+ERR_PETITION_ALREADY_SIGNED	string	framexml
+ERR_PETITION_CREATOR	string	framexml
+ERR_PETITION_DECLINED_S	string	framexml
+ERR_PETITION_IN_GUILD	string	framexml
+ERR_PETITION_NOT_ENOUGH_SIGNATURES	string	framexml
+ERR_PETITION_NOT_SAME_SERVER	string	framexml
+ERR_PETITION_OFFERED_S	string	framexml
+ERR_PETITION_SIGNED	string	framexml
+ERR_PETITION_SIGNED_S	string	framexml
+ERR_PET_BROKEN	string	framexml
+ERR_PET_NOT_RENAMEABLE	string	framexml
+ERR_PET_SPELL_AFFECTING_COMBAT	string	framexml
+ERR_PET_SPELL_ALREADY_KNOWN_S	string	framexml
+ERR_PET_SPELL_DEAD	string	framexml
+ERR_PET_SPELL_NOT_BEHIND	string	framexml
+ERR_PET_SPELL_OUT_OF_RANGE	string	framexml
+ERR_PET_SPELL_ROOTED	string	framexml
+ERR_PET_SPELL_TARGETS_DEAD	string	framexml
+ERR_PLAYER_BUSY_S	string	framexml
+ERR_PLAYER_DEAD	string	framexml
+ERR_PLAYER_DIED_S	string	framexml
+ERR_PLAYER_WRONG_FACTION	string	framexml
+ERR_PLAY_TIME_EXCEEDED	string	framexml
+ERR_POTION_COOLDOWN	string	framexml
+ERR_PROFICIENCY_GAINED_S	string	framexml
+ERR_PROFICIENCY_NEEDED	string	framexml
+ERR_PVP_TOGGLE_OFF	string	framexml
+ERR_PVP_TOGGLE_ON	string	framexml
+ERR_QUEST_ACCEPTED_S	string	framexml
+ERR_QUEST_ADD_FOUND_SII	string	framexml
+ERR_QUEST_ADD_ITEM_SII	string	framexml
+ERR_QUEST_ADD_KILL_SII	string	framexml
+ERR_QUEST_ALREADY_ON	string	framexml
+ERR_QUEST_COMPLETE_S	string	framexml
+ERR_QUEST_FAILED_BAG_FULL_S	string	framexml
+ERR_QUEST_FAILED_LOW_LEVEL	string	framexml
+ERR_QUEST_FAILED_MAX_COUNT_S	string	framexml
+ERR_QUEST_FAILED_MISSING_ITEMS	string	framexml
+ERR_QUEST_FAILED_NOT_ENOUGH_MONEY	string	framexml
+ERR_QUEST_FAILED_S	string	framexml
+ERR_QUEST_FAILED_WRONG_RACE	string	framexml
+ERR_QUEST_LOG_FULL	string	framexml
+ERR_QUEST_MUST_CHOOSE	string	framexml
+ERR_QUEST_NEED_PREREQS	string	framexml
+ERR_QUEST_OBJECTIVE_COMPLETE_S	string	framexml
+ERR_QUEST_ONLY_ONE_TIMED	string	framexml
+ERR_QUEST_PUSH_ACCEPTED_S	string	framexml
+ERR_QUEST_PUSH_ALREADY_DONE_S	string	framexml
+ERR_QUEST_PUSH_BUSY_S	string	framexml
+ERR_QUEST_PUSH_DECLINED_S	string	framexml
+ERR_QUEST_PUSH_INVALID_S	string	framexml
+ERR_QUEST_PUSH_LOG_FULL_S	string	framexml
+ERR_QUEST_PUSH_ONQUEST_S	string	framexml
+ERR_QUEST_PUSH_SUCCESS_S	string	framexml
+ERR_QUEST_PUSH_TOO_FAR_S	string	framexml
+ERR_QUEST_REWARD_EXP_I	string	framexml
+ERR_QUEST_REWARD_ITEM_S	string	framexml
+ERR_QUEST_REWARD_MONEY_S	string	framexml
+ERR_QUEST_UNKNOWN_COMPLETE	string	framexml
+ERR_RAID_GROUP_FULL	string	framexml
+ERR_RAID_GROUP_ONLY	string	framexml
+ERR_RAID_LEADER_READY_CHECK_START_S	string	framexml
+ERR_RAID_MEMBER_ADDED_S	string	framexml
+ERR_RAID_MEMBER_REMOVED_S	string	framexml
+ERR_RAID_YOU_JOINED	string	framexml
+ERR_RAID_YOU_LEFT	string	framexml
+ERR_READY_CHECK_IN_PROGRESS	string	framexml
+ERR_RECEIVE_ITEM_S	string	framexml
+ERR_RESTRICTED_ACCOUNT	string	framexml
+ERR_SET_LOOT_FREEFORALL	string	framexml
+ERR_SET_LOOT_GROUP	string	framexml
+ERR_SET_LOOT_MASTER	string	framexml
+ERR_SET_LOOT_NBG	string	framexml
+ERR_SET_LOOT_ROUNDROBIN	string	framexml
+ERR_SET_LOOT_THRESHOLD_S	string	framexml
+ERR_SKILL_GAINED_S	string	framexml
+ERR_SKILL_UP_SI	string	framexml
+ERR_SLOT_EMPTY	string	framexml
+ERR_SPECIFY_MASTER_LOOTER	string	framexml
+ERR_SPELL_ALREADY_KNOWN_S	string	framexml
+ERR_SPELL_COOLDOWN	string	framexml
+ERR_SPELL_FAILED_ALREADY_AT_FULL_HEALTH	string	framexml
+ERR_SPELL_FAILED_ALREADY_AT_FULL_POWER_S	string	framexml
+ERR_SPELL_FAILED_EQUIPPED_ITEM	string	framexml
+ERR_SPELL_FAILED_EQUIPPED_ITEM_CLASS_S	string	framexml
+ERR_SPELL_FAILED_NOTUNSHEATHED	string	framexml
+ERR_SPELL_FAILED_REAGENTS	string	framexml
+ERR_SPELL_FAILED_REAGENTS_GENERIC	string	framexml
+ERR_SPELL_FAILED_S	string	framexml
+ERR_SPELL_FAILED_SHAPESHIFT_FORM_S	string	framexml
+ERR_SPELL_FAILED_SS	string	framexml
+ERR_SPELL_FAILED_TITLE	string	framexml
+ERR_SPELL_FAILED_TOTEMS	string	framexml
+ERR_SPELL_OUT_OF_RANGE	string	framexml
+ERR_SPELL_UNLEARNED_S	string	framexml
+ERR_SPLIT_FAILED	string	framexml
+ERR_TALENT_WIPE_ERROR	string	framexml
+ERR_TAME_FAILED	string	framexml
+ERR_TARGET_LOGGING_OUT	string	framexml
+ERR_TARGET_NOT_IN_GROUP_S	string	framexml
+ERR_TARGET_STUNNED	string	framexml
+ERR_TAXINOPATH	string	framexml
+ERR_TAXINOPATHS	string	framexml
+ERR_TAXINOSUCHPATH	string	framexml
+ERR_TAXINOTENOUGHMONEY	string	framexml
+ERR_TAXINOTSTANDING	string	framexml
+ERR_TAXINOTVISITED	string	framexml
+ERR_TAXINOVENDORNEARBY	string	framexml
+ERR_TAXIPLAYERALREADYMOUNTED	string	framexml
+ERR_TAXIPLAYERBUSY	string	framexml
+ERR_TAXIPLAYERMOVING	string	framexml
+ERR_TAXIPLAYERSHAPESHIFTED	string	framexml
+ERR_TAXISAMENODE	string	framexml
+ERR_TAXITOOFARAWAY	string	framexml
+ERR_TAXIUNSPECIFIEDSERVERERROR	string	framexml
+ERR_TICKET_ALREADY_EXISTS	string	framexml
+ERR_TICKET_CREATE_ERROR	string	framexml
+ERR_TICKET_DB_ERROR	string	framexml
+ERR_TICKET_NO_TEXT	string	framexml
+ERR_TICKET_UPDATE_ERROR	string	framexml
+ERR_TOOBUSYTOFOLLOW	string	framexml
+ERR_TOO_FAR_TO_ATTACK	string	framexml
+ERR_TOO_FEW_TO_SPLIT	string	framexml
+ERR_TOO_MANY_CHAT_CHANNELS	string	framexml
+ERR_TOO_MANY_SPECIAL_BAGS	string	framexml
+ERR_TRADE_BAG	string	framexml
+ERR_TRADE_BAG_FULL	string	framexml
+ERR_TRADE_BLOCKED_S	string	framexml
+ERR_TRADE_BOUND_ITEM	string	framexml
+ERR_TRADE_CANCELLED	string	framexml
+ERR_TRADE_COMPLETE	string	framexml
+ERR_TRADE_EQUIPPED_BAG	string	framexml
+ERR_TRADE_GROUND_ITEM	string	framexml
+ERR_TRADE_MAX_COUNT_EXCEEDED	string	framexml
+ERR_TRADE_QUEST_ITEM	string	framexml
+ERR_TRADE_REQUEST_S	string	framexml
+ERR_TRADE_TARGET_BAG_FULL	string	framexml
+ERR_TRADE_TARGET_DEAD	string	framexml
+ERR_TRADE_TARGET_MAX_COUNT_EXCEEDED	string	framexml
+ERR_TRADE_TOO_FAR	string	framexml
+ERR_TRADE_WRONG_REALM	string	framexml
+ERR_UNHEALTHY_TIME	string	framexml
+ERR_UNINVITE_YOU	string	framexml
+ERR_UNIT_NOT_FOUND	string	framexml
+ERR_USE_BAD_ANGLE	string	framexml
+ERR_USE_CANT_IMMUNE	string	framexml
+ERR_USE_CANT_OPEN	string	framexml
+ERR_USE_DESTROYED	string	framexml
+ERR_USE_LOCKED	string	framexml
+ERR_USE_LOCKED_WITH_ITEM_S	string	framexml
+ERR_USE_LOCKED_WITH_SPELL_KNOWN_SI	string	framexml
+ERR_USE_LOCKED_WITH_SPELL_S	string	framexml
+ERR_USE_OBJECT_MOVING	string	framexml
+ERR_USE_SPELL_FOCUS	string	framexml
+ERR_USE_TOO_FAR	string	framexml
+ERR_VENDOR_HATES_YOU	string	framexml
+ERR_VENDOR_NOT_INTERESTED	string	framexml
+ERR_VENDOR_SOLD_OUT	string	framexml
+ERR_VENDOR_TOO_FAR	string	framexml
+ERR_WRONG_BAG_TYPE	string	framexml
+ERR_WRONG_BAG_TYPE_SUBCLASS	string	framexml
+ERR_WRONG_DIRECTION_FOR_ATTACK	string	framexml
+ERR_WRONG_SLOT	string	framexml
+ERR_ZONE_EXPLORED	string	framexml
+ERR_ZONE_EXPLORED_XP	string	framexml
+EVADE	string	framexml
+EXHAUSTION_LABEL	string	framexml
+EXHAUST_TOOLTIP1	string	framexml
+EXHAUST_TOOLTIP2	string	framexml
+EXHAUST_TOOLTIP3	string	framexml
+EXHAUST_TOOLTIP4	string	framexml
+EXIT	string	framexml
+EXIT_GAME	string	framexml
+EXOTICS	string	framexml
+EXPERIENCE_COLON	string	framexml
+EditBoxOnEnterPressed	lod	framexml
+EditBoxOnEscapePressed	lod	framexml
+EditBoxOnTextChanged	lod	framexml
+EditMacro	function	engine
+EmoteList	table	framexml
+EmoteMenu	table	framexml
+EmoteMenuButton1	table	framexml
+EmoteMenuButton10	table	framexml
+EmoteMenuButton10ShortcutText	table	framexml
+EmoteMenuButton11	table	framexml
+EmoteMenuButton11ShortcutText	table	framexml
+EmoteMenuButton12	table	framexml
+EmoteMenuButton12ShortcutText	table	framexml
+EmoteMenuButton13	table	framexml
+EmoteMenuButton13ShortcutText	table	framexml
+EmoteMenuButton14	table	framexml
+EmoteMenuButton14ShortcutText	table	framexml
+EmoteMenuButton15	table	framexml
+EmoteMenuButton15ShortcutText	table	framexml
+EmoteMenuButton16	table	framexml
+EmoteMenuButton16ShortcutText	table	framexml
+EmoteMenuButton17	table	framexml
+EmoteMenuButton17ShortcutText	table	framexml
+EmoteMenuButton18	table	framexml
+EmoteMenuButton18ShortcutText	table	framexml
+EmoteMenuButton19	table	framexml
+EmoteMenuButton19ShortcutText	table	framexml
+EmoteMenuButton1ShortcutText	table	framexml
+EmoteMenuButton2	table	framexml
+EmoteMenuButton20	table	framexml
+EmoteMenuButton20ShortcutText	table	framexml
+EmoteMenuButton21	table	framexml
+EmoteMenuButton21ShortcutText	table	framexml
+EmoteMenuButton22	table	framexml
+EmoteMenuButton22ShortcutText	table	framexml
+EmoteMenuButton23	table	framexml
+EmoteMenuButton23ShortcutText	table	framexml
+EmoteMenuButton24	table	framexml
+EmoteMenuButton24ShortcutText	table	framexml
+EmoteMenuButton25	table	framexml
+EmoteMenuButton25ShortcutText	table	framexml
+EmoteMenuButton26	table	framexml
+EmoteMenuButton26ShortcutText	table	framexml
+EmoteMenuButton27	table	framexml
+EmoteMenuButton27ShortcutText	table	framexml
+EmoteMenuButton28	table	framexml
+EmoteMenuButton28ShortcutText	table	framexml
+EmoteMenuButton29	table	framexml
+EmoteMenuButton29ShortcutText	table	framexml
+EmoteMenuButton2ShortcutText	table	framexml
+EmoteMenuButton3	table	framexml
+EmoteMenuButton30	table	framexml
+EmoteMenuButton30ShortcutText	table	framexml
+EmoteMenuButton31	table	framexml
+EmoteMenuButton31ShortcutText	table	framexml
+EmoteMenuButton32	table	framexml
+EmoteMenuButton32ShortcutText	table	framexml
+EmoteMenuButton3ShortcutText	table	framexml
+EmoteMenuButton4	table	framexml
+EmoteMenuButton4ShortcutText	table	framexml
+EmoteMenuButton5	table	framexml
+EmoteMenuButton5ShortcutText	table	framexml
+EmoteMenuButton6	table	framexml
+EmoteMenuButton6ShortcutText	table	framexml
+EmoteMenuButton7	table	framexml
+EmoteMenuButton7ShortcutText	table	framexml
+EmoteMenuButton8	table	framexml
+EmoteMenuButton8ShortcutText	table	framexml
+EmoteMenuButton9	table	framexml
+EmoteMenuButton9ShortcutText	table	framexml
+EmoteMenu_Click	function	framexml
+EmoteMenu_OnLoad	function	framexml
+EmptyQuestLogFrame	table	framexml
+EnableAddOn	function	engine
+EnableAllAddOns	function	engine
+Enable_BagButtons	function	framexml
+EnumerateFrames	function	engine
+EnumerateServerChannels	function	engine
+EquipCursorItem	function	engine
+EquipPendingItem	function	engine
+ErrorFont	table	framexml
+ExhaustionLevelFillBar	table	framexml
+ExhaustionTick	table	framexml
+ExhaustionTickHighlight	table	framexml
+ExhaustionTickNormal	table	framexml
+ExhaustionTick_OnLoad	function	framexml
+ExhaustionTick_OnUpdate	function	framexml
+ExhaustionTick_Update	function	framexml
+ExhaustionToolTipText	function	framexml
+ExpandCraftSkillLine	function	engine
+ExpandFactionHeader	function	engine
+ExpandQuestHeader	function	engine
+ExpandSkillHeader	function	engine
+ExpandTradeSkillSubClass	function	engine
+ExpandTrainerSkillLine	function	engine
+ExtendedUI	table	framexml
+FACING_WRONG_DIRECTION	string	framexml
+FACTION	string	framexml
+FACTION_ALLIANCE	string	framexml
+FACTION_BAR_COLORS	table	framexml
+FACTION_CONTROLLED_TERRITORY	string	framexml
+FACTION_HORDE	string	framexml
+FACTION_INACTIVE	string	framexml
+FACTION_OTHER	string	framexml
+FACTION_STANDING_CHANGED	string	framexml
+FACTION_STANDING_DECREASED	string	framexml
+FACTION_STANDING_INCREASED	string	framexml
+FACTION_STANDING_LABEL1	string	framexml
+FACTION_STANDING_LABEL1_FEMALE	string	framexml
+FACTION_STANDING_LABEL2	string	framexml
+FACTION_STANDING_LABEL2_FEMALE	string	framexml
+FACTION_STANDING_LABEL3	string	framexml
+FACTION_STANDING_LABEL3_FEMALE	string	framexml
+FACTION_STANDING_LABEL4	string	framexml
+FACTION_STANDING_LABEL4_FEMALE	string	framexml
+FACTION_STANDING_LABEL5	string	framexml
+FACTION_STANDING_LABEL5_FEMALE	string	framexml
+FACTION_STANDING_LABEL6	string	framexml
+FACTION_STANDING_LABEL6_FEMALE	string	framexml
+FACTION_STANDING_LABEL7	string	framexml
+FACTION_STANDING_LABEL7_FEMALE	string	framexml
+FACTION_STANDING_LABEL8	string	framexml
+FACTION_STANDING_LABEL8_FEMALE	string	framexml
+FADEFRAMES	table	framexml
+FAILED	string	framexml
+FARCLIP	string	framexml
+FCFChannelDropDown_OnClick	function	framexml
+FCFDropDown_LoadChannels	function	framexml
+FCFDropDown_LoadChatTypes	function	framexml
+FCFDropDown_LoadServerChannels	function	framexml
+FCFMessageTypeDropDown_OnClick	function	framexml
+FCFOptionsDropDown_Initialize	function	framexml
+FCFOptionsDropDown_OnLoad	function	framexml
+FCFServerChannelsDropDown_OnClick	function	framexml
+FCF_CancelFontColorSettings	function	framexml
+FCF_CancelWindowColorSettings	function	framexml
+FCF_ChatTabFadeFinished	function	framexml
+FCF_Close	function	framexml
+FCF_DockFrame	function	framexml
+FCF_DockUpdate	function	framexml
+FCF_FlashTab	function	framexml
+FCF_GetActiveDockRegion	function	framexml
+FCF_GetButtonSide	function	framexml
+FCF_GetCurrentChatFrame	function	framexml
+FCF_GetCurrentChatFrameID	function	framexml
+FCF_GetNumActiveChatFrames	function	framexml
+FCF_Get_ChatLocked	function	framexml
+FCF_IsValidChatFrame	function	framexml
+FCF_JoinNewChannel	function	framexml
+FCF_LoadChatSubTypes	function	framexml
+FCF_NewChatWindow	function	framexml
+FCF_OnUpdate	function	framexml
+FCF_OpenNewWindow	function	framexml
+FCF_RenameChatWindow_Popup	function	framexml
+FCF_Resize	function	framexml
+FCF_SaveDock	function	framexml
+FCF_SelectDockFrame	function	framexml
+FCF_SetButtonSide	function	framexml
+FCF_SetChatTypeColor	function	framexml
+FCF_SetChatWindowBackGroundColor	function	framexml
+FCF_SetChatWindowFontSize	function	framexml
+FCF_SetChatWindowOpacity	function	framexml
+FCF_SetLocked	function	framexml
+FCF_SetTabPosition	function	framexml
+FCF_SetWindowAlpha	function	framexml
+FCF_SetWindowColor	function	framexml
+FCF_SetWindowName	function	framexml
+FCF_Set_ChatLocked	function	framexml
+FCF_Set_NormalChat	function	framexml
+FCF_Set_SimpleChat	function	framexml
+FCF_StopResize	function	framexml
+FCF_StripChatMsg	function	framexml
+FCF_TabCompare	function	framexml
+FCF_Tab_OnClick	function	framexml
+FCF_ToggleLock	function	framexml
+FCF_UnDockFrame	function	framexml
+FCF_UpdateButtonSide	function	framexml
+FCF_UpdateCombatLogPosition	function	framexml
+FCF_UpdateDockPosition	function	framexml
+FCF_ValidateChatFramePosition	function	framexml
+FEEDPET_LOG_FIRSTPERSON	string	framexml
+FEEDPET_LOG_THIRDPERSON	string	framexml
+FEETSLOT	string	framexml
+FEMALE	string	framexml
+FILTER	string	framexml
+FILTERS	string	framexml
+FINGER0SLOT	string	framexml
+FINGER1SLOT	string	framexml
+FIRST_AVAILABLE	string	framexml
+FIRST_AVAILABLE_TOOLTIP	string	framexml
+FIX_LAG	string	framexml
+FLAG_COUNT_TEMPLATE	string	framexml
+FLASHFRAMES	table	framexml
+FOCUS	string	framexml
+FOCUS_COST	string	framexml
+FOCUS_COST_PER_TIME	string	framexml
+FOCUS_POINTS	string	framexml
+FOLLOW	string	framexml
+FOLLOW_TERRAIN	string	framexml
+FONT_COLOR_CODE_CLOSE	string	framexml
+FONT_SIZE	string	framexml
+FONT_SIZE_TEMPLATE	string	framexml
+FOOD_TIMER	string	framexml
+FOREIGN_SERVER_LABEL	string	framexml
+FRAMERATE_FREQUENCY	number	framexml
+FRAMERATE_LABEL	string	framexml
+FREE_FOR_ALL_TERRITORY	string	framexml
+FRIENDNAMEPLATES_ON	lod	framexml
+FRIENDS	string	framexml
+FRIENDSFRAME_SUBFRAMES	table	framexml
+FRIENDS_FRAME_FRIEND_HEIGHT	number	framexml
+FRIENDS_FRAME_GUILD_HEIGHT	number	framexml
+FRIENDS_FRAME_IGNORE_HEIGHT	number	framexml
+FRIENDS_FRAME_WHO_HEIGHT	number	framexml
+FRIENDS_LEVEL_TEMPLATE	string	framexml
+FRIENDS_LIST	string	framexml
+FRIENDS_LIST_OFFLINE_TEMPLATE	string	framexml
+FRIENDS_LIST_TEMPLATE	string	framexml
+FRIENDS_TO_DISPLAY	number	framexml
+FROM	string	framexml
+FULL_SCREEN_GLOW	string	framexml
+FactionMouseOver	table	framexml
+FactionToggleAtWar	function	engine
+FadingFrame_OnLoad	function	framexml
+FadingFrame_OnUpdate	function	framexml
+FadingFrame_SetFadeInTime	function	framexml
+FadingFrame_SetFadeOutTime	function	framexml
+FadingFrame_SetHoldTime	function	framexml
+FadingFrame_Show	function	framexml
+FauxScrollFrameTemplate	lod	framexml
+FauxScrollFrame_GetOffset	function	framexml
+FauxScrollFrame_OnVerticalScroll	function	framexml
+FauxScrollFrame_SetOffset	function	framexml
+FauxScrollFrame_Update	function	framexml
+FilterButton_SetType	lod	framexml
+FlagTutorial	function	engine
+FlipCameraYaw	function	engine
+FloatingChatFrameTemplate	lod	framexml
+FloatingChatFrame_OnEvent	function	framexml
+FloatingChatFrame_OnLoad	function	framexml
+FloatingChatFrame_Update	function	framexml
+FollowByName	function	engine
+FollowUnit	function	engine
+ForceLogout	function	engine
+ForceQuit	function	engine
+FrameXML_Debug	function	engine
+FramerateLabel	table	framexml
+FramerateText	table	framexml
+FriendsDropDown	table	framexml
+FriendsDropDownButton	table	framexml
+FriendsDropDownButtonDisabledTexture	table	framexml
+FriendsDropDownButtonHighlightTexture	table	framexml
+FriendsDropDownButtonNormalTexture	table	framexml
+FriendsDropDownButtonPushedTexture	table	framexml
+FriendsDropDownLeft	table	framexml
+FriendsDropDownMiddle	table	framexml
+FriendsDropDownRight	table	framexml
+FriendsDropDownText	table	framexml
+FriendsFrame	table	framexml
+FriendsFrameAddFriendButton	table	framexml
+FriendsFrameAddFriendButtonText	table	framexml
+FriendsFrameBottomLeft	table	framexml
+FriendsFrameBottomRight	table	framexml
+FriendsFrameButtonTemplate	lod	framexml
+FriendsFrameCloseButton	table	framexml
+FriendsFrameDropDown_Initialize	function	framexml
+FriendsFrameFriendButton1	table	framexml
+FriendsFrameFriendButton10	table	framexml
+FriendsFrameFriendButton10ButtonText	table	framexml
+FriendsFrameFriendButton10ButtonTextInfo	table	framexml
+FriendsFrameFriendButton10ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton1ButtonText	table	framexml
+FriendsFrameFriendButton1ButtonTextInfo	table	framexml
+FriendsFrameFriendButton1ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton2	table	framexml
+FriendsFrameFriendButton2ButtonText	table	framexml
+FriendsFrameFriendButton2ButtonTextInfo	table	framexml
+FriendsFrameFriendButton2ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton3	table	framexml
+FriendsFrameFriendButton3ButtonText	table	framexml
+FriendsFrameFriendButton3ButtonTextInfo	table	framexml
+FriendsFrameFriendButton3ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton4	table	framexml
+FriendsFrameFriendButton4ButtonText	table	framexml
+FriendsFrameFriendButton4ButtonTextInfo	table	framexml
+FriendsFrameFriendButton4ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton5	table	framexml
+FriendsFrameFriendButton5ButtonText	table	framexml
+FriendsFrameFriendButton5ButtonTextInfo	table	framexml
+FriendsFrameFriendButton5ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton6	table	framexml
+FriendsFrameFriendButton6ButtonText	table	framexml
+FriendsFrameFriendButton6ButtonTextInfo	table	framexml
+FriendsFrameFriendButton6ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton7	table	framexml
+FriendsFrameFriendButton7ButtonText	table	framexml
+FriendsFrameFriendButton7ButtonTextInfo	table	framexml
+FriendsFrameFriendButton7ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton8	table	framexml
+FriendsFrameFriendButton8ButtonText	table	framexml
+FriendsFrameFriendButton8ButtonTextInfo	table	framexml
+FriendsFrameFriendButton8ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton9	table	framexml
+FriendsFrameFriendButton9ButtonText	table	framexml
+FriendsFrameFriendButton9ButtonTextInfo	table	framexml
+FriendsFrameFriendButton9ButtonTextNameLocation	table	framexml
+FriendsFrameFriendButton_OnClick	function	framexml
+FriendsFrameFriendsScrollFrame	table	framexml
+FriendsFrameFriendsScrollFrameScrollBar	table	framexml
+FriendsFrameFriendsScrollFrameScrollBarScrollDownButton	table	framexml
+FriendsFrameFriendsScrollFrameScrollBarScrollUpButton	table	framexml
+FriendsFrameFriendsScrollFrameScrollBarThumbTexture	table	framexml
+FriendsFrameFriendsScrollFrameScrollChildFrame	table	framexml
+FriendsFrameGroupInviteButton	table	framexml
+FriendsFrameGroupInviteButtonText	table	framexml
+FriendsFrameGuildPlayerStatusButtonTemplate	lod	framexml
+FriendsFrameGuildStatusButtonTemplate	lod	framexml
+FriendsFrameGuildStatusButton_OnClick	function	framexml
+FriendsFrameIgnoreButton1	table	framexml
+FriendsFrameIgnoreButton10	table	framexml
+FriendsFrameIgnoreButton10ButtonText	table	framexml
+FriendsFrameIgnoreButton10ButtonTextName	table	framexml
+FriendsFrameIgnoreButton11	table	framexml
+FriendsFrameIgnoreButton11ButtonText	table	framexml
+FriendsFrameIgnoreButton11ButtonTextName	table	framexml
+FriendsFrameIgnoreButton12	table	framexml
+FriendsFrameIgnoreButton12ButtonText	table	framexml
+FriendsFrameIgnoreButton12ButtonTextName	table	framexml
+FriendsFrameIgnoreButton13	table	framexml
+FriendsFrameIgnoreButton13ButtonText	table	framexml
+FriendsFrameIgnoreButton13ButtonTextName	table	framexml
+FriendsFrameIgnoreButton14	table	framexml
+FriendsFrameIgnoreButton14ButtonText	table	framexml
+FriendsFrameIgnoreButton14ButtonTextName	table	framexml
+FriendsFrameIgnoreButton15	table	framexml
+FriendsFrameIgnoreButton15ButtonText	table	framexml
+FriendsFrameIgnoreButton15ButtonTextName	table	framexml
+FriendsFrameIgnoreButton16	table	framexml
+FriendsFrameIgnoreButton16ButtonText	table	framexml
+FriendsFrameIgnoreButton16ButtonTextName	table	framexml
+FriendsFrameIgnoreButton17	table	framexml
+FriendsFrameIgnoreButton17ButtonText	table	framexml
+FriendsFrameIgnoreButton17ButtonTextName	table	framexml
+FriendsFrameIgnoreButton18	table	framexml
+FriendsFrameIgnoreButton18ButtonText	table	framexml
+FriendsFrameIgnoreButton18ButtonTextName	table	framexml
+FriendsFrameIgnoreButton19	table	framexml
+FriendsFrameIgnoreButton19ButtonText	table	framexml
+FriendsFrameIgnoreButton19ButtonTextName	table	framexml
+FriendsFrameIgnoreButton1ButtonText	table	framexml
+FriendsFrameIgnoreButton1ButtonTextName	table	framexml
+FriendsFrameIgnoreButton2	table	framexml
+FriendsFrameIgnoreButton20	table	framexml
+FriendsFrameIgnoreButton20ButtonText	table	framexml
+FriendsFrameIgnoreButton20ButtonTextName	table	framexml
+FriendsFrameIgnoreButton2ButtonText	table	framexml
+FriendsFrameIgnoreButton2ButtonTextName	table	framexml
+FriendsFrameIgnoreButton3	table	framexml
+FriendsFrameIgnoreButton3ButtonText	table	framexml
+FriendsFrameIgnoreButton3ButtonTextName	table	framexml
+FriendsFrameIgnoreButton4	table	framexml
+FriendsFrameIgnoreButton4ButtonText	table	framexml
+FriendsFrameIgnoreButton4ButtonTextName	table	framexml
+FriendsFrameIgnoreButton5	table	framexml
+FriendsFrameIgnoreButton5ButtonText	table	framexml
+FriendsFrameIgnoreButton5ButtonTextName	table	framexml
+FriendsFrameIgnoreButton6	table	framexml
+FriendsFrameIgnoreButton6ButtonText	table	framexml
+FriendsFrameIgnoreButton6ButtonTextName	table	framexml
+FriendsFrameIgnoreButton7	table	framexml
+FriendsFrameIgnoreButton7ButtonText	table	framexml
+FriendsFrameIgnoreButton7ButtonTextName	table	framexml
+FriendsFrameIgnoreButton8	table	framexml
+FriendsFrameIgnoreButton8ButtonText	table	framexml
+FriendsFrameIgnoreButton8ButtonTextName	table	framexml
+FriendsFrameIgnoreButton9	table	framexml
+FriendsFrameIgnoreButton9ButtonText	table	framexml
+FriendsFrameIgnoreButton9ButtonTextName	table	framexml
+FriendsFrameIgnoreButtonTemplate	lod	framexml
+FriendsFrameIgnoreButton_OnClick	function	framexml
+FriendsFrameIgnorePlayerButton	table	framexml
+FriendsFrameIgnorePlayerButtonText	table	framexml
+FriendsFrameIgnoreScrollFrame	table	framexml
+FriendsFrameIgnoreScrollFrameScrollBar	table	framexml
+FriendsFrameIgnoreScrollFrameScrollBarScrollDownButton	table	framexml
+FriendsFrameIgnoreScrollFrameScrollBarScrollUpButton	table	framexml
+FriendsFrameIgnoreScrollFrameScrollBarThumbTexture	table	framexml
+FriendsFrameIgnoreScrollFrameScrollChildFrame	table	framexml
+FriendsFrameRemoveFriendButton	table	framexml
+FriendsFrameRemoveFriendButtonText	table	framexml
+FriendsFrameSendMessageButton	table	framexml
+FriendsFrameSendMessageButtonText	table	framexml
+FriendsFrameStopIgnoreButton	table	framexml
+FriendsFrameStopIgnoreButtonText	table	framexml
+FriendsFrameTab1	table	framexml
+FriendsFrameTab1HighlightTexture	table	framexml
+FriendsFrameTab1Left	table	framexml
+FriendsFrameTab1LeftDisabled	table	framexml
+FriendsFrameTab1Middle	table	framexml
+FriendsFrameTab1MiddleDisabled	table	framexml
+FriendsFrameTab1Right	table	framexml
+FriendsFrameTab1RightDisabled	table	framexml
+FriendsFrameTab1Text	table	framexml
+FriendsFrameTab2	table	framexml
+FriendsFrameTab2HighlightTexture	table	framexml
+FriendsFrameTab2Left	table	framexml
+FriendsFrameTab2LeftDisabled	table	framexml
+FriendsFrameTab2Middle	table	framexml
+FriendsFrameTab2MiddleDisabled	table	framexml
+FriendsFrameTab2Right	table	framexml
+FriendsFrameTab2RightDisabled	table	framexml
+FriendsFrameTab2Text	table	framexml
+FriendsFrameTab3	table	framexml
+FriendsFrameTab3HighlightTexture	table	framexml
+FriendsFrameTab3Left	table	framexml
+FriendsFrameTab3LeftDisabled	table	framexml
+FriendsFrameTab3Middle	table	framexml
+FriendsFrameTab3MiddleDisabled	table	framexml
+FriendsFrameTab3Right	table	framexml
+FriendsFrameTab3RightDisabled	table	framexml
+FriendsFrameTab3Text	table	framexml
+FriendsFrameTab4	table	framexml
+FriendsFrameTab4HighlightTexture	table	framexml
+FriendsFrameTab4Left	table	framexml
+FriendsFrameTab4LeftDisabled	table	framexml
+FriendsFrameTab4Middle	table	framexml
+FriendsFrameTab4MiddleDisabled	table	framexml
+FriendsFrameTab4Right	table	framexml
+FriendsFrameTab4RightDisabled	table	framexml
+FriendsFrameTab4Text	table	framexml
+FriendsFrameTabTemplate	lod	framexml
+FriendsFrameTitleText	table	framexml
+FriendsFrameToggleTab1	table	framexml
+FriendsFrameToggleTab1HighlightTexture	table	framexml
+FriendsFrameToggleTab1Left	table	framexml
+FriendsFrameToggleTab1LeftDisabled	table	framexml
+FriendsFrameToggleTab1Middle	table	framexml
+FriendsFrameToggleTab1MiddleDisabled	table	framexml
+FriendsFrameToggleTab1Right	table	framexml
+FriendsFrameToggleTab1RightDisabled	table	framexml
+FriendsFrameToggleTab1Text	table	framexml
+FriendsFrameToggleTab2	table	framexml
+FriendsFrameToggleTab2HighlightTexture	table	framexml
+FriendsFrameToggleTab2Left	table	framexml
+FriendsFrameToggleTab2LeftDisabled	table	framexml
+FriendsFrameToggleTab2Middle	table	framexml
+FriendsFrameToggleTab2MiddleDisabled	table	framexml
+FriendsFrameToggleTab2Right	table	framexml
+FriendsFrameToggleTab2RightDisabled	table	framexml
+FriendsFrameToggleTab2Text	table	framexml
+FriendsFrameTopLeft	table	framexml
+FriendsFrameTopRight	table	framexml
+FriendsFrameWhoButtonTemplate	lod	framexml
+FriendsFrameWhoButton_OnClick	function	framexml
+FriendsFrame_GroupInvite	function	framexml
+FriendsFrame_OnEvent	function	framexml
+FriendsFrame_OnHide	function	framexml
+FriendsFrame_OnLoad	function	framexml
+FriendsFrame_OnShow	function	framexml
+FriendsFrame_RemoveFriend	function	framexml
+FriendsFrame_SendMessage	function	framexml
+FriendsFrame_ShowDropdown	function	framexml
+FriendsFrame_ShowSubFrame	function	framexml
+FriendsFrame_UnIgnore	function	framexml
+FriendsFrame_Update	function	framexml
+FriendsListFrame	table	framexml
+FriendsList_Update	function	framexml
+GAINING_LOYALTY	string	framexml
+GAMEFIELD_DESELECT_TEXT	string	framexml
+GAMETIME_DAWN	number	framexml
+GAMETIME_DUSK	number	framexml
+GAME_VERSION_LABEL	string	framexml
+GAMMA	string	framexml
+GENERAL	string	framexml
+GENERAL_HELPFRAME	table	framexml
+GENERAL_MACROS	string	framexml
+GENERIC_MIN	string	framexml
+GENERIC_MIN_P1	string	framexml
+GENERIC_SEC	string	framexml
+GENERIC_SEC_P1	string	framexml
+GIVE_LOOT	string	framexml
+GLANCING_TRAILER	string	framexml
+GMCategoryButtonTemplate	lod	framexml
+GMRequestPlayerInfo	function	engine
+GMSURVEYRATING1	string	framexml
+GMSURVEYRATING2	string	framexml
+GMSURVEYRATING3	string	framexml
+GMSURVEYRATING4	string	framexml
+GMSURVEYRATING5	string	framexml
+GMSURVEY_EXCELLENT	string	framexml
+GMSURVEY_NA_SPACING	lod	framexml
+GMSURVEY_POOR	string	framexml
+GMSURVEY_RATING_SPACING	lod	framexml
+GMSURVEY_REQUEST_TEXT	string	framexml
+GMSURVEY_SUBMITTED	string	framexml
+GMSURVEY_TITLE	string	framexml
+GMSurveyAdditionalCommentsText	lod	framexml
+GMSurveyAnswerSubmit	function	engine
+GMSurveyBottom	lod	framexml
+GMSurveyBottomFiller	lod	framexml
+GMSurveyBottomLeft	lod	framexml
+GMSurveyBottomRight	lod	framexml
+GMSurveyCancelButton	lod	framexml
+GMSurveyCloseButton	lod	framexml
+GMSurveyCommentFrame	lod	framexml
+GMSurveyCommentScrollFrame	lod	framexml
+GMSurveyCommentSubmit	function	engine
+GMSurveyFrame	lod	framexml
+GMSurveyFrameComment	lod	framexml
+GMSurveyFrameSetWidth	lod	framexml
+GMSurveyFrame_LoadUI	function	framexml
+GMSurveyFrame_Update	lod	framexml
+GMSurveyHeader	lod	framexml
+GMSurveyHeaderCenter	lod	framexml
+GMSurveyHeaderLeft	lod	framexml
+GMSurveyHeaderRight	lod	framexml
+GMSurveyHeaderText	lod	framexml
+GMSurveyLeft	lod	framexml
+GMSurveyMiddle	lod	framexml
+GMSurveyMiddleFiller	lod	framexml
+GMSurveyQuestion	function	engine
+GMSurveyQuestion1	lod	framexml
+GMSurveyQuestion10	lod	framexml
+GMSurveyQuestion2	lod	framexml
+GMSurveyQuestion3	lod	framexml
+GMSurveyQuestion4	lod	framexml
+GMSurveyQuestion5	lod	framexml
+GMSurveyQuestion6	lod	framexml
+GMSurveyQuestion7	lod	framexml
+GMSurveyQuestion8	lod	framexml
+GMSurveyQuestion9	lod	framexml
+GMSurveyQuestionTemplate	lod	framexml
+GMSurveyRadioButtonTemplate	lod	framexml
+GMSurveyRadioButton_OnClick	lod	framexml
+GMSurveyRight	lod	framexml
+GMSurveyScrollChildFrame	lod	framexml
+GMSurveyScrollFrame	lod	framexml
+GMSurveySubmit	function	engine
+GMSurveySubmitButton	lod	framexml
+GMSurveySubmitButton_OnClick	lod	framexml
+GMSurveyTop	lod	framexml
+GMSurveyTopFiller	lod	framexml
+GMSurveyTopLeft	lod	framexml
+GMSurveyTopRight	lod	framexml
+GMTICKET_CHECK_INTERVAL	number	framexml
+GM_EMAIL_NAME	string	framexml
+GM_SURVEY_NOT_APPLICABLE	string	framexml
+GM_TICKET_ESCALATED	string	framexml
+GM_TICKET_HIGH_VOLUME	string	framexml
+GM_TICKET_SERVICE_SOON	string	framexml
+GM_TICKET_UNAVAILABLE	string	framexml
+GM_TICKET_WAIT_TIME	string	framexml
+GOLD	string	framexml
+GOODBYE	string	framexml
+GOSSIP_OPTIONS	string	framexml
+GRAY_FONT_COLOR	table	framexml
+GRAY_FONT_COLOR_CODE	string	framexml
+GREED	string	framexml
+GREEN_FONT_COLOR	table	framexml
+GREEN_FONT_COLOR_CODE	string	framexml
+GROUP	string	framexml
+GROUPS	string	framexml
+GROUP_INVITE	string	framexml
+GUILD	string	framexml
+GUILDADDRANK_BUTTON_TOOLTIP	string	framexml
+GUILDCONTROL	string	framexml
+GUILDCONTROL_ALLOWRANK	string	framexml
+GUILDCONTROL_OPTION1	string	framexml
+GUILDCONTROL_OPTION10	string	framexml
+GUILDCONTROL_OPTION11	string	framexml
+GUILDCONTROL_OPTION12	string	framexml
+GUILDCONTROL_OPTION13	string	framexml
+GUILDCONTROL_OPTION2	string	framexml
+GUILDCONTROL_OPTION3	string	framexml
+GUILDCONTROL_OPTION4	string	framexml
+GUILDCONTROL_OPTION5	string	framexml
+GUILDCONTROL_OPTION6	string	framexml
+GUILDCONTROL_OPTION7	string	framexml
+GUILDCONTROL_OPTION8	string	framexml
+GUILDCONTROL_OPTION9	string	framexml
+GUILDCONTROL_RANKLABEL	string	framexml
+GUILDCONTROL_SELECTRANK	string	framexml
+GUILDMEMBERS_TO_DISPLAY	number	framexml
+GUILDMEMBER_ALERT	string	framexml
+GUILDMOTD_BUTTON_TOOLTIP	string	framexml
+GUILDNOTE_BUTTON_TOOLTIP	string	framexml
+GUILDOFFICERNOTE_BUTTON_TOOLTIP	string	framexml
+GUILDREMOVERANK_BUTTON_TOOLTIP	string	framexml
+GUILD_CHARTER	string	framexml
+GUILD_CHARTER_CREATOR	string	framexml
+GUILD_CHARTER_PURCHASE	string	framexml
+GUILD_CHARTER_REGISTER	string	framexml
+GUILD_CHARTER_TEMPLATE	string	framexml
+GUILD_CHARTER_TITLE	string	framexml
+GUILD_CREST_DESIGN	string	framexml
+GUILD_DETAIL_NORM_HEIGHT	number	framexml
+GUILD_DETAIL_OFFICER_HEIGHT	number	framexml
+GUILD_FRAME_TITLE	string	framexml
+GUILD_HELP_TEXT_LINE1	string	framexml
+GUILD_HELP_TEXT_LINE10	string	framexml
+GUILD_HELP_TEXT_LINE11	string	framexml
+GUILD_HELP_TEXT_LINE12	string	framexml
+GUILD_HELP_TEXT_LINE13	string	framexml
+GUILD_HELP_TEXT_LINE2	string	framexml
+GUILD_HELP_TEXT_LINE3	string	framexml
+GUILD_HELP_TEXT_LINE4	string	framexml
+GUILD_HELP_TEXT_LINE5	string	framexml
+GUILD_HELP_TEXT_LINE6	string	framexml
+GUILD_HELP_TEXT_LINE7	string	framexml
+GUILD_HELP_TEXT_LINE8	string	framexml
+GUILD_HELP_TEXT_LINE9	string	framexml
+GUILD_INFORMATION	string	framexml
+GUILD_INFO_EDITLABEL	string	framexml
+GUILD_INFO_TEMPLATE	string	framexml
+GUILD_INVITATION	string	framexml
+GUILD_LEAVE	string	framexml
+GUILD_MEMBER_OPTIONS	string	framexml
+GUILD_MEMBER_TEMPLATE	string	framexml
+GUILD_MESSAGE	string	framexml
+GUILD_MOTD	string	framexml
+GUILD_MOTD_EDITLABEL	string	framexml
+GUILD_MOTD_LABEL	string	framexml
+GUILD_MOTD_LABEL2	string	framexml
+GUILD_MOTD_TEMPLATE	string	framexml
+GUILD_NAME	string	framexml
+GUILD_NAME_TEMPLATE	string	framexml
+GUILD_NOTES_LABEL	string	framexml
+GUILD_NOTE_EDITLABEL	string	framexml
+GUILD_NOT_ALLIED_S	string	framexml
+GUILD_OFFICERNOTES_LABEL	string	framexml
+GUILD_OFFICERNOTE_EDITLABEL	string	framexml
+GUILD_OFFICER_NOTE	string	framexml
+GUILD_ONLINE_LABEL	string	framexml
+GUILD_PETITION_LEADER_INSTRUCTIONS	string	framexml
+GUILD_PETITION_MEMBER_INSTRUCTIONS	string	framexml
+GUILD_PROMOTE	string	framexml
+GUILD_RANK0_DESC	string	framexml
+GUILD_RANK1_DESC	string	framexml
+GUILD_RANK2_DESC	string	framexml
+GUILD_RANK3_DESC	string	framexml
+GUILD_RANK4_DESC	string	framexml
+GUILD_REGISTRAR_PURCHASE_TEXT	string	framexml
+GUILD_ROSTER_TEMPLATE	string	framexml
+GUILD_STATUS	string	framexml
+GUILD_TEMPLATE	string	framexml
+GUILD_TITLE_TEMPLATE	string	framexml
+GUILD_TOTAL	string	framexml
+GUILD_TOTALONLINE	string	framexml
+GUILD_TOTAL_P1	string	framexml
+GameFontBlack	table	framexml
+GameFontDarkGraySmall	table	framexml
+GameFontDisable	table	framexml
+GameFontDisableLarge	table	framexml
+GameFontDisableSmall	table	framexml
+GameFontGreen	table	framexml
+GameFontGreenLarge	table	framexml
+GameFontGreenSmall	table	framexml
+GameFontHighlight	table	framexml
+GameFontHighlightLarge	table	framexml
+GameFontHighlightSmall	table	framexml
+GameFontHighlightSmallOutline	table	framexml
+GameFontNormal	table	framexml
+GameFontNormalHuge	table	framexml
+GameFontNormalLarge	table	framexml
+GameFontNormalSmall	table	framexml
+GameFontRed	table	framexml
+GameFontRedLarge	table	framexml
+GameFontRedSmall	table	framexml
+GameFontWhite	table	framexml
+GameMenuButtonContinue	table	framexml
+GameMenuButtonContinueText	table	framexml
+GameMenuButtonKeybindings	table	framexml
+GameMenuButtonKeybindingsText	table	framexml
+GameMenuButtonLogout	table	framexml
+GameMenuButtonLogoutText	table	framexml
+GameMenuButtonMacros	table	framexml
+GameMenuButtonMacrosText	table	framexml
+GameMenuButtonOptions	table	framexml
+GameMenuButtonOptionsText	table	framexml
+GameMenuButtonQuit	table	framexml
+GameMenuButtonQuitText	table	framexml
+GameMenuButtonSoundOptions	table	framexml
+GameMenuButtonSoundOptionsText	table	framexml
+GameMenuButtonTemplate	lod	framexml
+GameMenuButtonUIOptions	table	framexml
+GameMenuButtonUIOptionsText	table	framexml
+GameMenuFrame	table	framexml
+GameMenuFrameHeader	table	framexml
+GameTimeFrame	table	framexml
+GameTimeFrame_Update	function	framexml
+GameTimeFrame_UpdateTooltip	function	framexml
+GameTimeTexture	table	framexml
+GameTime_GetTime	function	framexml
+GameTooltip	table	framexml
+GameTooltipHeaderText	table	framexml
+GameTooltipMoneyFrame	table	framexml
+GameTooltipMoneyFrameCopperButton	table	framexml
+GameTooltipMoneyFrameCopperButtonText	table	framexml
+GameTooltipMoneyFrameGoldButton	table	framexml
+GameTooltipMoneyFrameGoldButtonText	table	framexml
+GameTooltipMoneyFrameSilverButton	table	framexml
+GameTooltipMoneyFrameSilverButtonText	table	framexml
+GameTooltipStatusBar	table	framexml
+GameTooltipStatusBarTexture	table	framexml
+GameTooltipTemplate	lod	framexml
+GameTooltipText	table	framexml
+GameTooltipTextLeft1	table	framexml
+GameTooltipTextLeft10	table	framexml
+GameTooltipTextLeft11	table	framexml
+GameTooltipTextLeft12	table	framexml
+GameTooltipTextLeft13	table	framexml
+GameTooltipTextLeft14	table	framexml
+GameTooltipTextLeft15	table	framexml
+GameTooltipTextLeft16	table	framexml
+GameTooltipTextLeft17	table	framexml
+GameTooltipTextLeft18	table	framexml
+GameTooltipTextLeft19	table	framexml
+GameTooltipTextLeft2	table	framexml
+GameTooltipTextLeft20	table	framexml
+GameTooltipTextLeft21	table	framexml
+GameTooltipTextLeft22	table	framexml
+GameTooltipTextLeft23	table	framexml
+GameTooltipTextLeft24	table	framexml
+GameTooltipTextLeft25	table	framexml
+GameTooltipTextLeft26	table	framexml
+GameTooltipTextLeft27	table	framexml
+GameTooltipTextLeft28	table	framexml
+GameTooltipTextLeft29	table	framexml
+GameTooltipTextLeft3	table	framexml
+GameTooltipTextLeft30	table	framexml
+GameTooltipTextLeft4	table	framexml
+GameTooltipTextLeft5	table	framexml
+GameTooltipTextLeft6	table	framexml
+GameTooltipTextLeft7	table	framexml
+GameTooltipTextLeft8	table	framexml
+GameTooltipTextLeft9	table	framexml
+GameTooltipTextRight1	table	framexml
+GameTooltipTextRight10	table	framexml
+GameTooltipTextRight11	table	framexml
+GameTooltipTextRight12	table	framexml
+GameTooltipTextRight13	table	framexml
+GameTooltipTextRight14	table	framexml
+GameTooltipTextRight15	table	framexml
+GameTooltipTextRight16	table	framexml
+GameTooltipTextRight17	table	framexml
+GameTooltipTextRight18	table	framexml
+GameTooltipTextRight19	table	framexml
+GameTooltipTextRight2	table	framexml
+GameTooltipTextRight20	table	framexml
+GameTooltipTextRight21	table	framexml
+GameTooltipTextRight22	table	framexml
+GameTooltipTextRight23	table	framexml
+GameTooltipTextRight24	table	framexml
+GameTooltipTextRight25	table	framexml
+GameTooltipTextRight26	table	framexml
+GameTooltipTextRight27	table	framexml
+GameTooltipTextRight28	table	framexml
+GameTooltipTextRight29	table	framexml
+GameTooltipTextRight3	table	framexml
+GameTooltipTextRight30	table	framexml
+GameTooltipTextRight4	table	framexml
+GameTooltipTextRight5	table	framexml
+GameTooltipTextRight6	table	framexml
+GameTooltipTextRight7	table	framexml
+GameTooltipTextRight8	table	framexml
+GameTooltipTextRight9	table	framexml
+GameTooltipTextSmall	table	framexml
+GameTooltipTexture1	table	framexml
+GameTooltipTexture2	table	framexml
+GameTooltipTexture3	table	framexml
+GameTooltip_AddNewbieTip	function	framexml
+GameTooltip_ClearMoney	function	framexml
+GameTooltip_OnHide	function	framexml
+GameTooltip_OnLoad	function	framexml
+GameTooltip_SetDefaultAnchor	function	framexml
+GameTooltip_UnitColor	function	framexml
+GenderTagInfo	table	framexml
+GetAbandonQuestItems	function	engine
+GetAbandonQuestName	function	engine
+GetActionAutocast	function	engine
+GetActionBarToggles	function	engine
+GetActionCooldown	function	engine
+GetActionCount	function	engine
+GetActionText	function	engine
+GetActionTexture	function	engine
+GetActiveLevel	function	engine
+GetActiveTitle	function	engine
+GetAddOnDependencies	function	engine
+GetAddOnInfo	function	engine
+GetAddOnMetadata	function	engine
+GetAdjustedSkillPoints	function	engine
+GetAreaSpiritHealerTime	function	engine
+GetAuctionHouseDepositRate	function	engine
+GetAuctionInvTypes	function	engine
+GetAuctionItemClasses	function	engine
+GetAuctionItemInfo	function	engine
+GetAuctionItemLink	function	engine
+GetAuctionItemSubClasses	function	engine
+GetAuctionItemTimeLeft	function	engine
+GetAuctionSellItemInfo	function	engine
+GetAvailableLevel	function	engine
+GetAvailableTitle	function	engine
+GetBagName	function	engine
+GetBankSlotCost	function	engine
+GetBaseMip	function	engine
+GetBattlefieldEstimatedWaitTime	function	engine
+GetBattlefieldFlagPosition	function	engine
+GetBattlefieldInfo	function	engine
+GetBattlefieldInstanceExpiration	function	engine
+GetBattlefieldInstanceInfo	function	engine
+GetBattlefieldInstanceRunTime	function	engine
+GetBattlefieldMapIconScale	function	engine
+GetBattlefieldPortExpiration	function	engine
+GetBattlefieldPosition	function	engine
+GetBattlefieldScore	function	engine
+GetBattlefieldStatData	function	engine
+GetBattlefieldStatInfo	function	engine
+GetBattlefieldStatus	function	engine
+GetBattlefieldTimeWaited	function	engine
+GetBattlefieldWinner	function	engine
+GetBidderAuctionItems	function	engine
+GetBillingTimeRested	function	engine
+GetBindLocation	function	engine
+GetBinding	function	engine
+GetBindingAction	function	engine
+GetBindingKey	function	engine
+GetBindingText	function	framexml
+GetBlockChance	function	engine
+GetBonusBarOffset	function	engine
+GetBuildInfo	function	engine
+GetBuybackItemInfo	function	engine
+GetCVar	function	engine
+GetCVarDefault	function	engine
+GetCenterFrame	function	framexml
+GetChannelList	function	engine
+GetChannelName	function	engine
+GetChatTypeIndex	function	engine
+GetChatWindowChannels	function	engine
+GetChatWindowInfo	function	engine
+GetChatWindowMessages	function	engine
+GetCoinIcon	function	engine
+GetComboPoints	function	engine
+GetContainerItemCooldown	function	engine
+GetContainerItemInfo	function	engine
+GetContainerItemLink	function	engine
+GetContainerNumSlots	function	engine
+GetCorpseMapPosition	function	engine
+GetCorpseRecoveryDelay	function	engine
+GetCraftButtonToken	function	engine
+GetCraftDescription	function	engine
+GetCraftDisplaySkillLine	function	engine
+GetCraftIcon	function	engine
+GetCraftInfo	function	engine
+GetCraftItemLink	function	engine
+GetCraftName	function	engine
+GetCraftNumReagents	function	engine
+GetCraftReagentInfo	function	engine
+GetCraftReagentItemLink	function	engine
+GetCraftSelectionIndex	function	engine
+GetCraftSkillLine	function	engine
+GetCraftSpellFocus	function	engine
+GetCurrentBindingSet	function	engine
+GetCurrentMapContinent	function	engine
+GetCurrentMapZone	function	engine
+GetCurrentMultisampleFormat	function	engine
+GetCurrentResolution	function	engine
+GetCursorMoney	function	engine
+GetCursorPosition	function	engine
+GetDamageBonusStat	function	engine
+GetDebugStats	function	engine
+GetDefaultLanguage	function	engine
+GetDifficultyColor	function	framexml
+GetDodgeChance	function	engine
+GetDoodadAnim	function	engine
+GetDoublewideFrame	function	framexml
+GetFactionInfo	function	engine
+GetFarclip	function	engine
+GetFirstTradeSkill	function	engine
+GetFramerate	function	engine
+GetFriendInfo	function	engine
+GetFullScreenFrame	function	framexml
+GetGMStatus	function	engine
+GetGMTicket	function	engine
+GetGMTicketCategories	function	engine
+GetGameTime	function	engine
+GetGamma	function	engine
+GetGenderTag	function	framexml
+GetGossipActiveQuests	function	engine
+GetGossipAvailableQuests	function	engine
+GetGossipOptions	function	engine
+GetGossipText	function	engine
+GetGreetingText	function	engine
+GetGuildCharterCost	function	engine
+GetGuildInfo	function	engine
+GetGuildInfoText	function	engine
+GetGuildRecruitmentMode	function	engine
+GetGuildRosterInfo	function	engine
+GetGuildRosterLastOnline	function	engine
+GetGuildRosterMOTD	function	engine
+GetGuildRosterSelection	function	engine
+GetGuildRosterShowOffline	function	engine
+GetIgnoreName	function	engine
+GetInboxHeaderInfo	function	engine
+GetInboxInvoiceInfo	function	engine
+GetInboxItem	function	engine
+GetInboxNumItems	function	engine
+GetInboxText	function	engine
+GetInspectHonorData	function	engine
+GetInspectPVPRankProgress	function	engine
+GetInstanceBootTimeRemaining	function	engine
+GetInventoryAlertStatus	function	engine
+GetInventoryItemBroken	function	engine
+GetInventoryItemCooldown	function	engine
+GetInventoryItemCount	function	engine
+GetInventoryItemLink	function	engine
+GetInventoryItemQuality	function	engine
+GetInventoryItemTexture	function	engine
+GetInventorySlotInfo	function	engine
+GetItemInfo	function	engine
+GetItemQualityColor	function	engine
+GetJackpotAmount	function	engine
+GetKeyRingSize	function	framexml
+GetLFGResults	function	engine
+GetLFGTypeEntries	function	engine
+GetLFGTypes	function	engine
+GetLanguageByIndex	function	engine
+GetLastLotteryNumbers	function	engine
+GetLeftFrame	function	framexml
+GetLocale	function	engine
+GetLookingForGroup	function	engine
+GetLootMethod	function	engine
+GetLootRollItemInfo	function	engine
+GetLootRollItemLink	function	engine
+GetLootRollTimeLeft	function	engine
+GetLootSlotInfo	function	engine
+GetLootSlotLink	function	engine
+GetLootThreshold	function	engine
+GetLotteryPrizeInfo	function	engine
+GetMacroIconInfo	function	engine
+GetMacroIndexByName	function	engine
+GetMacroInfo	function	engine
+GetMapContinents	function	engine
+GetMapInfo	function	engine
+GetMapLandmarkInfo	function	engine
+GetMapOverlayInfo	function	engine
+GetMapZones	function	engine
+GetMasterLootCandidate	function	engine
+GetMaterialTextColors	function	framexml
+GetMeetingStoneStatusText	function	engine
+GetMerchantItemInfo	function	engine
+GetMerchantItemLink	function	engine
+GetMerchantItemMaxStack	function	engine
+GetMerchantNumItems	function	engine
+GetMinigameState	function	engine
+GetMinigameType	function	engine
+GetMinimapZoneText	function	engine
+GetMoney	function	engine
+GetMoneyPrizes	function	engine
+GetMouseFocus	function	engine
+GetMultisampleFormats	function	engine
+GetNetStats	function	engine
+GetNextDrawTime	function	engine
+GetNextStableSlotCost	function	engine
+GetNumActiveQuests	function	engine
+GetNumAddOns	function	engine
+GetNumAuctionItems	function	engine
+GetNumAvailableQuests	function	engine
+GetNumBankSlots	function	engine
+GetNumBattlefieldFlagPositions	function	engine
+GetNumBattlefieldPositions	function	engine
+GetNumBattlefieldScores	function	engine
+GetNumBattlefieldStats	function	engine
+GetNumBattlefields	function	engine
+GetNumBindings	function	engine
+GetNumBuybackItems	function	engine
+GetNumCrafts	function	engine
+GetNumFactions	function	engine
+GetNumFrames	function	engine
+GetNumFriends	function	engine
+GetNumGuildMembers	function	engine
+GetNumIgnores	function	engine
+GetNumLFGResults	function	engine
+GetNumLaguages	function	engine
+GetNumLootItems	function	engine
+GetNumLotteryPrizes	function	engine
+GetNumMacroIcons	function	engine
+GetNumMacros	function	engine
+GetNumMapLandmarks	function	engine
+GetNumMapOverlays	function	engine
+GetNumPackages	function	engine
+GetNumPartyMembers	function	engine
+GetNumPastDrawResults	function	engine
+GetNumPetitionNames	function	engine
+GetNumQuestChoices	function	engine
+GetNumQuestItems	function	engine
+GetNumQuestLeaderBoards	function	engine
+GetNumQuestLogChoices	function	engine
+GetNumQuestLogEntries	function	engine
+GetNumQuestLogRewards	function	engine
+GetNumQuestRewards	function	engine
+GetNumQuestWatches	function	engine
+GetNumRaidMembers	function	engine
+GetNumRoutes	function	engine
+GetNumSavedInstances	function	engine
+GetNumShapeshiftForms	function	engine
+GetNumSkillLines	function	engine
+GetNumSpellTabs	function	engine
+GetNumStablePets	function	engine
+GetNumStableSlots	function	engine
+GetNumStationeries	function	engine
+GetNumTalentTabs	function	engine
+GetNumTalents	function	engine
+GetNumTradeSkills	function	engine
+GetNumTrainerServices	function	engine
+GetNumWhoResults	function	engine
+GetNumWorldStateUI	function	engine
+GetObjectiveText	function	engine
+GetOwnerAuctionItems	function	engine
+GetPVPLastWeekStats	function	engine
+GetPVPLifetimeStats	function	engine
+GetPVPRankInfo	function	engine
+GetPVPRankProgress	function	engine
+GetPVPSessionStats	function	engine
+GetPVPThisWeekStats	function	engine
+GetPVPYesterdayStats	function	engine
+GetPackageInfo	function	engine
+GetParryChance	function	engine
+GetPartyLeaderIndex	function	engine
+GetPartyMember	function	engine
+GetPastDrawResult	function	engine
+GetPetActionCooldown	function	engine
+GetPetActionInfo	function	engine
+GetPetActionsUsable	function	engine
+GetPetExperience	function	engine
+GetPetFoodTypes	function	engine
+GetPetHappiness	function	engine
+GetPetIcon	function	engine
+GetPetLoyalty	function	engine
+GetPetTimeRemaining	function	engine
+GetPetTrainingPoints	function	engine
+GetPetitionInfo	function	engine
+GetPetitionNameInfo	function	engine
+GetPlayerBuff	function	engine
+GetPlayerBuffApplications	function	engine
+GetPlayerBuffDispelType	function	engine
+GetPlayerBuffTexture	function	engine
+GetPlayerBuffTimeLeft	function	engine
+GetPlayerMapPosition	function	engine
+GetPlayerTradeMoney	function	engine
+GetPluralIndex	function	framexml
+GetPluralTag	function	framexml
+GetProgressText	function	engine
+GetQuestBackgroundMaterial	function	engine
+GetQuestGreenRange	function	engine
+GetQuestIndexForTimer	function	engine
+GetQuestIndexForWatch	function	engine
+GetQuestItemInfo	function	engine
+GetQuestItemLink	function	engine
+GetQuestLogChoiceInfo	function	engine
+GetQuestLogIndexByName	function	framexml
+GetQuestLogItemLink	function	engine
+GetQuestLogLeaderBoard	function	engine
+GetQuestLogPushable	function	engine
+GetQuestLogQuestText	function	engine
+GetQuestLogRequiredMoney	function	engine
+GetQuestLogRewardInfo	function	engine
+GetQuestLogRewardMoney	function	engine
+GetQuestLogRewardSpell	function	engine
+GetQuestLogSelection	function	engine
+GetQuestLogTimeLeft	function	engine
+GetQuestLogTitle	function	engine
+GetQuestMoneyToGet	function	engine
+GetQuestReward	function	engine
+GetQuestText	function	engine
+GetQuestTimers	function	engine
+GetRaidRosterInfo	function	engine
+GetRaidRosterSelection	function	engine
+GetRaidTargetIndex	function	engine
+GetRealZoneText	function	engine
+GetRealmName	function	engine
+GetRefreshRates	function	engine
+GetReleaseTimeRemaining	function	engine
+GetRepairAllCost	function	engine
+GetResSicknessDuration	function	engine
+GetRestState	function	engine
+GetRewardMoney	function	engine
+GetRewardSpell	function	engine
+GetRewardText	function	engine
+GetSavedInstanceInfo	function	engine
+GetScreenHeight	function	engine
+GetScreenHeightScale	function	framexml
+GetScreenResolutions	function	engine
+GetScreenWidth	function	engine
+GetScreenWidthScale	function	framexml
+GetSelectedAuctionItem	function	engine
+GetSelectedBattlefield	function	engine
+GetSelectedFaction	function	engine
+GetSelectedFriend	function	engine
+GetSelectedIgnore	function	engine
+GetSelectedSkill	function	engine
+GetSelectedStablePet	function	engine
+GetSelectedStationeryTexture	function	engine
+GetSendMailCOD	function	engine
+GetSendMailItem	function	engine
+GetSendMailMoney	function	engine
+GetSendMailPrice	function	engine
+GetShapeshiftFormCooldown	function	engine
+GetShapeshiftFormInfo	function	engine
+GetSkillLineInfo	function	engine
+GetSlashCmdTarget	function	framexml
+GetSpellAutocast	function	engine
+GetSpellCooldown	function	engine
+GetSpellName	function	engine
+GetSpellTabInfo	function	engine
+GetSpellTexture	function	engine
+GetStablePetFoodTypes	function	engine
+GetStablePetInfo	function	engine
+GetStationeryInfo	function	engine
+GetSubZoneText	function	engine
+GetSummonConfirmAreaName	function	engine
+GetSummonConfirmSummoner	function	engine
+GetSummonConfirmTimeLeft	function	engine
+GetTabardCreationCost	function	engine
+GetTabardInfo	function	engine
+GetTalentInfo	function	engine
+GetTalentPrereqs	function	engine
+GetTalentTabInfo	function	engine
+GetTargetTradeMoney	function	engine
+GetTerrainMip	function	engine
+GetTexLodBias	function	engine
+GetText	function	framexml
+GetTime	function	engine
+GetTimeToWellRested	function	engine
+GetTitleText	function	engine
+GetTrackingTexture	function	engine
+GetTradePlayerItemInfo	function	engine
+GetTradePlayerItemLink	function	engine
+GetTradeSkillCooldown	function	engine
+GetTradeSkillIcon	function	engine
+GetTradeSkillInfo	function	engine
+GetTradeSkillInvSlotFilter	function	engine
+GetTradeSkillInvSlots	function	engine
+GetTradeSkillItemLink	function	engine
+GetTradeSkillItemStats	function	engine
+GetTradeSkillLine	function	engine
+GetTradeSkillNumMade	function	engine
+GetTradeSkillNumReagents	function	engine
+GetTradeSkillReagentInfo	function	engine
+GetTradeSkillReagentItemLink	function	engine
+GetTradeSkillSelectionIndex	function	engine
+GetTradeSkillSubClassFilter	function	engine
+GetTradeSkillSubClasses	function	engine
+GetTradeSkillTools	function	engine
+GetTradeTargetItemInfo	function	engine
+GetTradeTargetItemLink	function	engine
+GetTradeskillRepeatCount	function	engine
+GetTrainerGreetingText	function	engine
+GetTrainerSelectionIndex	function	engine
+GetTrainerServiceAbilityReq	function	engine
+GetTrainerServiceCost	function	engine
+GetTrainerServiceDescription	function	engine
+GetTrainerServiceIcon	function	engine
+GetTrainerServiceInfo	function	engine
+GetTrainerServiceLevelReq	function	engine
+GetTrainerServiceNumAbilityReq	function	engine
+GetTrainerServiceSkillLine	function	engine
+GetTrainerServiceSkillReq	function	engine
+GetTrainerServiceStepIncrease	function	engine
+GetTrainerServiceStepReq	function	engine
+GetTrainerServiceTypeFilter	function	engine
+GetTrainerSkillLineFilter	function	engine
+GetTrainerSkillLines	function	engine
+GetUnitName	function	framexml
+GetVideoCaps	function	engine
+GetWatchedFactionInfo	function	engine
+GetWaterDetail	function	engine
+GetWeaponEnchantInfo	function	engine
+GetWhoInfo	function	engine
+GetWorldDetail	function	engine
+GetWorldLocMapPosition	function	engine
+GetWorldStateUIInfo	function	engine
+GetXPExhaustion	function	engine
+GetZonePVPInfo	function	engine
+GetZoneText	function	engine
+GiveMasterLoot	function	engine
+GossipFrame	table	framexml
+GossipFrameActiveQuestsUpdate	function	framexml
+GossipFrameAvailableQuestsUpdate	function	framexml
+GossipFrameCloseButton	table	framexml
+GossipFrameGreetingGoodbyeButton	table	framexml
+GossipFrameGreetingGoodbyeButtonText	table	framexml
+GossipFrameGreetingPanel	table	framexml
+GossipFrameGreetingPanelMaterialBotLeft	table	framexml
+GossipFrameGreetingPanelMaterialBotRight	table	framexml
+GossipFrameGreetingPanelMaterialTopLeft	table	framexml
+GossipFrameGreetingPanelMaterialTopRight	table	framexml
+GossipFrameNpcNameText	table	framexml
+GossipFrameOptionsUpdate	function	framexml
+GossipFramePanelTemplate	lod	framexml
+GossipFramePortrait	table	framexml
+GossipFrameUpdate	function	framexml
+GossipFrame_OnEvent	function	framexml
+GossipFrame_OnLoad	function	framexml
+GossipGreetingScrollChildFrame	table	framexml
+GossipGreetingScrollFrame	table	framexml
+GossipGreetingScrollFrameScrollBar	table	framexml
+GossipGreetingScrollFrameScrollBarScrollDownButton	table	framexml
+GossipGreetingScrollFrameScrollBarScrollUpButton	table	framexml
+GossipGreetingScrollFrameScrollBarThumbTexture	table	framexml
+GossipGreetingText	table	framexml
+GossipNpcNameFrame	table	framexml
+GossipResize	function	framexml
+GossipSpacerFrame	table	framexml
+GossipTitleButton1	table	framexml
+GossipTitleButton10	table	framexml
+GossipTitleButton10GossipIcon	table	framexml
+GossipTitleButton11	table	framexml
+GossipTitleButton11GossipIcon	table	framexml
+GossipTitleButton12	table	framexml
+GossipTitleButton12GossipIcon	table	framexml
+GossipTitleButton13	table	framexml
+GossipTitleButton13GossipIcon	table	framexml
+GossipTitleButton14	table	framexml
+GossipTitleButton14GossipIcon	table	framexml
+GossipTitleButton15	table	framexml
+GossipTitleButton15GossipIcon	table	framexml
+GossipTitleButton16	table	framexml
+GossipTitleButton16GossipIcon	table	framexml
+GossipTitleButton17	table	framexml
+GossipTitleButton17GossipIcon	table	framexml
+GossipTitleButton18	table	framexml
+GossipTitleButton18GossipIcon	table	framexml
+GossipTitleButton19	table	framexml
+GossipTitleButton19GossipIcon	table	framexml
+GossipTitleButton1GossipIcon	table	framexml
+GossipTitleButton2	table	framexml
+GossipTitleButton20	table	framexml
+GossipTitleButton20GossipIcon	table	framexml
+GossipTitleButton21	table	framexml
+GossipTitleButton21GossipIcon	table	framexml
+GossipTitleButton22	table	framexml
+GossipTitleButton22GossipIcon	table	framexml
+GossipTitleButton23	table	framexml
+GossipTitleButton23GossipIcon	table	framexml
+GossipTitleButton24	table	framexml
+GossipTitleButton24GossipIcon	table	framexml
+GossipTitleButton25	table	framexml
+GossipTitleButton25GossipIcon	table	framexml
+GossipTitleButton26	table	framexml
+GossipTitleButton26GossipIcon	table	framexml
+GossipTitleButton27	table	framexml
+GossipTitleButton27GossipIcon	table	framexml
+GossipTitleButton28	table	framexml
+GossipTitleButton28GossipIcon	table	framexml
+GossipTitleButton29	table	framexml
+GossipTitleButton29GossipIcon	table	framexml
+GossipTitleButton2GossipIcon	table	framexml
+GossipTitleButton3	table	framexml
+GossipTitleButton30	table	framexml
+GossipTitleButton30GossipIcon	table	framexml
+GossipTitleButton31	table	framexml
+GossipTitleButton31GossipIcon	table	framexml
+GossipTitleButton32	table	framexml
+GossipTitleButton32GossipIcon	table	framexml
+GossipTitleButton3GossipIcon	table	framexml
+GossipTitleButton4	table	framexml
+GossipTitleButton4GossipIcon	table	framexml
+GossipTitleButton5	table	framexml
+GossipTitleButton5GossipIcon	table	framexml
+GossipTitleButton6	table	framexml
+GossipTitleButton6GossipIcon	table	framexml
+GossipTitleButton7	table	framexml
+GossipTitleButton7GossipIcon	table	framexml
+GossipTitleButton8	table	framexml
+GossipTitleButton8GossipIcon	table	framexml
+GossipTitleButton9	table	framexml
+GossipTitleButton9GossipIcon	table	framexml
+GossipTitleButtonTemplate	lod	framexml
+GossipTitleButton_OnClick	function	framexml
+GreetingText	table	framexml
+GroupLootDropDown	table	framexml
+GroupLootDropDownButton	table	framexml
+GroupLootDropDownButtonDisabledTexture	table	framexml
+GroupLootDropDownButtonHighlightTexture	table	framexml
+GroupLootDropDownButtonNormalTexture	table	framexml
+GroupLootDropDownButtonPushedTexture	table	framexml
+GroupLootDropDownLeft	table	framexml
+GroupLootDropDownMiddle	table	framexml
+GroupLootDropDownRight	table	framexml
+GroupLootDropDownText	table	framexml
+GroupLootDropDown_GiveLoot	function	framexml
+GroupLootDropDown_Initialize	function	framexml
+GroupLootDropDown_OnLoad	function	framexml
+GroupLootFrame1	table	framexml
+GroupLootFrame1Corner	table	framexml
+GroupLootFrame1Decoration	table	framexml
+GroupLootFrame1GreedButton	table	framexml
+GroupLootFrame1IconFrame	table	framexml
+GroupLootFrame1IconFrameIcon	table	framexml
+GroupLootFrame1Name	table	framexml
+GroupLootFrame1NameFrame	table	framexml
+GroupLootFrame1PassButton	table	framexml
+GroupLootFrame1RollButton	table	framexml
+GroupLootFrame1SlotTexture	table	framexml
+GroupLootFrame1Timer	table	framexml
+GroupLootFrame1TimerBar	table	framexml
+GroupLootFrame2	table	framexml
+GroupLootFrame2Corner	table	framexml
+GroupLootFrame2Decoration	table	framexml
+GroupLootFrame2GreedButton	table	framexml
+GroupLootFrame2IconFrame	table	framexml
+GroupLootFrame2IconFrameIcon	table	framexml
+GroupLootFrame2Name	table	framexml
+GroupLootFrame2NameFrame	table	framexml
+GroupLootFrame2PassButton	table	framexml
+GroupLootFrame2RollButton	table	framexml
+GroupLootFrame2SlotTexture	table	framexml
+GroupLootFrame2Timer	table	framexml
+GroupLootFrame2TimerBar	table	framexml
+GroupLootFrame3	table	framexml
+GroupLootFrame3Corner	table	framexml
+GroupLootFrame3Decoration	table	framexml
+GroupLootFrame3GreedButton	table	framexml
+GroupLootFrame3IconFrame	table	framexml
+GroupLootFrame3IconFrameIcon	table	framexml
+GroupLootFrame3Name	table	framexml
+GroupLootFrame3NameFrame	table	framexml
+GroupLootFrame3PassButton	table	framexml
+GroupLootFrame3RollButton	table	framexml
+GroupLootFrame3SlotTexture	table	framexml
+GroupLootFrame3Timer	table	framexml
+GroupLootFrame3TimerBar	table	framexml
+GroupLootFrame4	table	framexml
+GroupLootFrame4Corner	table	framexml
+GroupLootFrame4Decoration	table	framexml
+GroupLootFrame4GreedButton	table	framexml
+GroupLootFrame4IconFrame	table	framexml
+GroupLootFrame4IconFrameIcon	table	framexml
+GroupLootFrame4Name	table	framexml
+GroupLootFrame4NameFrame	table	framexml
+GroupLootFrame4PassButton	table	framexml
+GroupLootFrame4RollButton	table	framexml
+GroupLootFrame4SlotTexture	table	framexml
+GroupLootFrame4Timer	table	framexml
+GroupLootFrame4TimerBar	table	framexml
+GroupLootFrameTemplate	lod	framexml
+GroupLootFrame_OnEvent	function	framexml
+GroupLootFrame_OnShow	function	framexml
+GroupLootFrame_OnUpdate	function	framexml
+GroupLootFrame_OpenNewFrame	function	framexml
+GuildControlAddRank	function	engine
+GuildControlCheckboxUpdate	function	framexml
+GuildControlDelRank	function	engine
+GuildControlGetNumRanks	function	engine
+GuildControlGetRankFlags	function	engine
+GuildControlGetRankName	function	engine
+GuildControlPopupAcceptButton	table	framexml
+GuildControlPopupAcceptButtonText	table	framexml
+GuildControlPopupAcceptButton_OnClick	function	framexml
+GuildControlPopupFrame	table	framexml
+GuildControlPopupFrameAddRankButton	table	framexml
+GuildControlPopupFrameAddRankButton_OnUpdate	function	framexml
+GuildControlPopupFrameCancelButton	table	framexml
+GuildControlPopupFrameCancelButtonText	table	framexml
+GuildControlPopupFrameCheckbox1	table	framexml
+GuildControlPopupFrameCheckbox10	table	framexml
+GuildControlPopupFrameCheckbox10Label	table	framexml
+GuildControlPopupFrameCheckbox11	table	framexml
+GuildControlPopupFrameCheckbox11Label	table	framexml
+GuildControlPopupFrameCheckbox12	table	framexml
+GuildControlPopupFrameCheckbox12Label	table	framexml
+GuildControlPopupFrameCheckbox13	table	framexml
+GuildControlPopupFrameCheckbox13Label	table	framexml
+GuildControlPopupFrameCheckbox1Label	table	framexml
+GuildControlPopupFrameCheckbox2	table	framexml
+GuildControlPopupFrameCheckbox2Label	table	framexml
+GuildControlPopupFrameCheckbox3	table	framexml
+GuildControlPopupFrameCheckbox3Label	table	framexml
+GuildControlPopupFrameCheckbox4	table	framexml
+GuildControlPopupFrameCheckbox4Label	table	framexml
+GuildControlPopupFrameCheckbox5	table	framexml
+GuildControlPopupFrameCheckbox5Label	table	framexml
+GuildControlPopupFrameCheckbox6	table	framexml
+GuildControlPopupFrameCheckbox6Label	table	framexml
+GuildControlPopupFrameCheckbox7	table	framexml
+GuildControlPopupFrameCheckbox7Label	table	framexml
+GuildControlPopupFrameCheckbox8	table	framexml
+GuildControlPopupFrameCheckbox8Label	table	framexml
+GuildControlPopupFrameCheckbox9	table	framexml
+GuildControlPopupFrameCheckbox9Label	table	framexml
+GuildControlPopupFrameCheckboxTemplate	lod	framexml
+GuildControlPopupFrameCheckboxes	table	framexml
+GuildControlPopupFrameDropDown	table	framexml
+GuildControlPopupFrameDropDownButton	table	framexml
+GuildControlPopupFrameDropDownButtonDisabledTexture	table	framexml
+GuildControlPopupFrameDropDownButtonHighlightTexture	table	framexml
+GuildControlPopupFrameDropDownButtonNormalTexture	table	framexml
+GuildControlPopupFrameDropDownButtonPushedTexture	table	framexml
+GuildControlPopupFrameDropDownButton_OnClick	function	framexml
+GuildControlPopupFrameDropDownLeft	table	framexml
+GuildControlPopupFrameDropDownMiddle	table	framexml
+GuildControlPopupFrameDropDownRight	table	framexml
+GuildControlPopupFrameDropDownText	table	framexml
+GuildControlPopupFrameDropDown_Initialize	function	framexml
+GuildControlPopupFrameDropDown_OnLoad	function	framexml
+GuildControlPopupFrameEditBox	table	framexml
+GuildControlPopupFrameRemoveRankButton	table	framexml
+GuildControlPopupFrameRemoveRankButton_OnClick	function	framexml
+GuildControlPopupFrameRemoveRankButton_OnUpdate	function	framexml
+GuildControlPopupFrame_OnHide	function	framexml
+GuildControlPopupFrame_OnLoad	function	framexml
+GuildControlPopupFrame_OnShow	function	framexml
+GuildControlSaveRank	function	engine
+GuildControlSetRank	function	engine
+GuildControlSetRankFlag	function	engine
+GuildDemoteByName	function	engine
+GuildDisband	function	engine
+GuildFrame	table	framexml
+GuildFrameAddMemberButton	table	framexml
+GuildFrameAddMemberButtonText	table	framexml
+GuildFrameButton1	table	framexml
+GuildFrameButton10	table	framexml
+GuildFrameButton10Class	table	framexml
+GuildFrameButton10Group	table	framexml
+GuildFrameButton10Level	table	framexml
+GuildFrameButton10Name	table	framexml
+GuildFrameButton10Zone	table	framexml
+GuildFrameButton11	table	framexml
+GuildFrameButton11Class	table	framexml
+GuildFrameButton11Group	table	framexml
+GuildFrameButton11Level	table	framexml
+GuildFrameButton11Name	table	framexml
+GuildFrameButton11Zone	table	framexml
+GuildFrameButton12	table	framexml
+GuildFrameButton12Class	table	framexml
+GuildFrameButton12Group	table	framexml
+GuildFrameButton12Level	table	framexml
+GuildFrameButton12Name	table	framexml
+GuildFrameButton12Zone	table	framexml
+GuildFrameButton13	table	framexml
+GuildFrameButton13Class	table	framexml
+GuildFrameButton13Group	table	framexml
+GuildFrameButton13Level	table	framexml
+GuildFrameButton13Name	table	framexml
+GuildFrameButton13Zone	table	framexml
+GuildFrameButton1Class	table	framexml
+GuildFrameButton1Group	table	framexml
+GuildFrameButton1Level	table	framexml
+GuildFrameButton1Name	table	framexml
+GuildFrameButton1Zone	table	framexml
+GuildFrameButton2	table	framexml
+GuildFrameButton2Class	table	framexml
+GuildFrameButton2Group	table	framexml
+GuildFrameButton2Level	table	framexml
+GuildFrameButton2Name	table	framexml
+GuildFrameButton2Zone	table	framexml
+GuildFrameButton3	table	framexml
+GuildFrameButton3Class	table	framexml
+GuildFrameButton3Group	table	framexml
+GuildFrameButton3Level	table	framexml
+GuildFrameButton3Name	table	framexml
+GuildFrameButton3Zone	table	framexml
+GuildFrameButton4	table	framexml
+GuildFrameButton4Class	table	framexml
+GuildFrameButton4Group	table	framexml
+GuildFrameButton4Level	table	framexml
+GuildFrameButton4Name	table	framexml
+GuildFrameButton4Zone	table	framexml
+GuildFrameButton5	table	framexml
+GuildFrameButton5Class	table	framexml
+GuildFrameButton5Group	table	framexml
+GuildFrameButton5Level	table	framexml
+GuildFrameButton5Name	table	framexml
+GuildFrameButton5Zone	table	framexml
+GuildFrameButton6	table	framexml
+GuildFrameButton6Class	table	framexml
+GuildFrameButton6Group	table	framexml
+GuildFrameButton6Level	table	framexml
+GuildFrameButton6Name	table	framexml
+GuildFrameButton6Zone	table	framexml
+GuildFrameButton7	table	framexml
+GuildFrameButton7Class	table	framexml
+GuildFrameButton7Group	table	framexml
+GuildFrameButton7Level	table	framexml
+GuildFrameButton7Name	table	framexml
+GuildFrameButton7Zone	table	framexml
+GuildFrameButton8	table	framexml
+GuildFrameButton8Class	table	framexml
+GuildFrameButton8Group	table	framexml
+GuildFrameButton8Level	table	framexml
+GuildFrameButton8Name	table	framexml
+GuildFrameButton8Zone	table	framexml
+GuildFrameButton9	table	framexml
+GuildFrameButton9Class	table	framexml
+GuildFrameButton9Group	table	framexml
+GuildFrameButton9Level	table	framexml
+GuildFrameButton9Name	table	framexml
+GuildFrameButton9Zone	table	framexml
+GuildFrameColumnHeader1	table	framexml
+GuildFrameColumnHeader1Left	table	framexml
+GuildFrameColumnHeader1Middle	table	framexml
+GuildFrameColumnHeader1Right	table	framexml
+GuildFrameColumnHeader2	table	framexml
+GuildFrameColumnHeader2Left	table	framexml
+GuildFrameColumnHeader2Middle	table	framexml
+GuildFrameColumnHeader2Right	table	framexml
+GuildFrameColumnHeader3	table	framexml
+GuildFrameColumnHeader3Left	table	framexml
+GuildFrameColumnHeader3Middle	table	framexml
+GuildFrameColumnHeader3Right	table	framexml
+GuildFrameColumnHeader4	table	framexml
+GuildFrameColumnHeader4Left	table	framexml
+GuildFrameColumnHeader4Middle	table	framexml
+GuildFrameColumnHeader4Right	table	framexml
+GuildFrameColumnHeaderTemplate	lod	framexml
+GuildFrameControlButton	table	framexml
+GuildFrameControlButtonText	table	framexml
+GuildFrameControlButton_OnUpdate	function	framexml
+GuildFrameDemoteButton	table	framexml
+GuildFrameGuildInformationButton	table	framexml
+GuildFrameGuildInformationButtonText	table	framexml
+GuildFrameGuildListToggleButton	table	framexml
+GuildFrameGuildListToggleButton_OnClick	function	framexml
+GuildFrameGuildStatusButton1	table	framexml
+GuildFrameGuildStatusButton10	table	framexml
+GuildFrameGuildStatusButton10Name	table	framexml
+GuildFrameGuildStatusButton10Note	table	framexml
+GuildFrameGuildStatusButton10Online	table	framexml
+GuildFrameGuildStatusButton10Rank	table	framexml
+GuildFrameGuildStatusButton11	table	framexml
+GuildFrameGuildStatusButton11Name	table	framexml
+GuildFrameGuildStatusButton11Note	table	framexml
+GuildFrameGuildStatusButton11Online	table	framexml
+GuildFrameGuildStatusButton11Rank	table	framexml
+GuildFrameGuildStatusButton12	table	framexml
+GuildFrameGuildStatusButton12Name	table	framexml
+GuildFrameGuildStatusButton12Note	table	framexml
+GuildFrameGuildStatusButton12Online	table	framexml
+GuildFrameGuildStatusButton12Rank	table	framexml
+GuildFrameGuildStatusButton13	table	framexml
+GuildFrameGuildStatusButton13Name	table	framexml
+GuildFrameGuildStatusButton13Note	table	framexml
+GuildFrameGuildStatusButton13Online	table	framexml
+GuildFrameGuildStatusButton13Rank	table	framexml
+GuildFrameGuildStatusButton1Name	table	framexml
+GuildFrameGuildStatusButton1Note	table	framexml
+GuildFrameGuildStatusButton1Online	table	framexml
+GuildFrameGuildStatusButton1Rank	table	framexml
+GuildFrameGuildStatusButton2	table	framexml
+GuildFrameGuildStatusButton2Name	table	framexml
+GuildFrameGuildStatusButton2Note	table	framexml
+GuildFrameGuildStatusButton2Online	table	framexml
+GuildFrameGuildStatusButton2Rank	table	framexml
+GuildFrameGuildStatusButton3	table	framexml
+GuildFrameGuildStatusButton3Name	table	framexml
+GuildFrameGuildStatusButton3Note	table	framexml
+GuildFrameGuildStatusButton3Online	table	framexml
+GuildFrameGuildStatusButton3Rank	table	framexml
+GuildFrameGuildStatusButton4	table	framexml
+GuildFrameGuildStatusButton4Name	table	framexml
+GuildFrameGuildStatusButton4Note	table	framexml
+GuildFrameGuildStatusButton4Online	table	framexml
+GuildFrameGuildStatusButton4Rank	table	framexml
+GuildFrameGuildStatusButton5	table	framexml
+GuildFrameGuildStatusButton5Name	table	framexml
+GuildFrameGuildStatusButton5Note	table	framexml
+GuildFrameGuildStatusButton5Online	table	framexml
+GuildFrameGuildStatusButton5Rank	table	framexml
+GuildFrameGuildStatusButton6	table	framexml
+GuildFrameGuildStatusButton6Name	table	framexml
+GuildFrameGuildStatusButton6Note	table	framexml
+GuildFrameGuildStatusButton6Online	table	framexml
+GuildFrameGuildStatusButton6Rank	table	framexml
+GuildFrameGuildStatusButton7	table	framexml
+GuildFrameGuildStatusButton7Name	table	framexml
+GuildFrameGuildStatusButton7Note	table	framexml
+GuildFrameGuildStatusButton7Online	table	framexml
+GuildFrameGuildStatusButton7Rank	table	framexml
+GuildFrameGuildStatusButton8	table	framexml
+GuildFrameGuildStatusButton8Name	table	framexml
+GuildFrameGuildStatusButton8Note	table	framexml
+GuildFrameGuildStatusButton8Online	table	framexml
+GuildFrameGuildStatusButton8Rank	table	framexml
+GuildFrameGuildStatusButton9	table	framexml
+GuildFrameGuildStatusButton9Name	table	framexml
+GuildFrameGuildStatusButton9Note	table	framexml
+GuildFrameGuildStatusButton9Online	table	framexml
+GuildFrameGuildStatusButton9Rank	table	framexml
+GuildFrameGuildStatusColumnHeader1	table	framexml
+GuildFrameGuildStatusColumnHeader1Left	table	framexml
+GuildFrameGuildStatusColumnHeader1Middle	table	framexml
+GuildFrameGuildStatusColumnHeader1Right	table	framexml
+GuildFrameGuildStatusColumnHeader2	table	framexml
+GuildFrameGuildStatusColumnHeader2Left	table	framexml
+GuildFrameGuildStatusColumnHeader2Middle	table	framexml
+GuildFrameGuildStatusColumnHeader2Right	table	framexml
+GuildFrameGuildStatusColumnHeader3	table	framexml
+GuildFrameGuildStatusColumnHeader3Left	table	framexml
+GuildFrameGuildStatusColumnHeader3Middle	table	framexml
+GuildFrameGuildStatusColumnHeader3Right	table	framexml
+GuildFrameGuildStatusColumnHeader4	table	framexml
+GuildFrameGuildStatusColumnHeader4Left	table	framexml
+GuildFrameGuildStatusColumnHeader4Middle	table	framexml
+GuildFrameGuildStatusColumnHeader4Right	table	framexml
+GuildFrameLFGButton	table	framexml
+GuildFrameLFGButtonText	table	framexml
+GuildFrameLFGFrame	table	framexml
+GuildFrameLFGFrameLeft	table	framexml
+GuildFrameLFGFrameMiddle	table	framexml
+GuildFrameLFGFrameRight	table	framexml
+GuildFrameNotesLabel	table	framexml
+GuildFrameNotesText	table	framexml
+GuildFrameOnlineTotals	table	framexml
+GuildFramePromoteButton	table	framexml
+GuildFrameTotals	table	framexml
+GuildFrame_GetLastOnline	function	framexml
+GuildInfo	function	engine
+GuildInfoCancelButton	table	framexml
+GuildInfoCancelButtonText	table	framexml
+GuildInfoCloseButton	table	framexml
+GuildInfoCorner	table	framexml
+GuildInfoEditBox	table	framexml
+GuildInfoFrame	table	framexml
+GuildInfoFrameScrollFrame	table	framexml
+GuildInfoFrameScrollFrameScrollBar	table	framexml
+GuildInfoFrameScrollFrameScrollBarScrollDownButton	table	framexml
+GuildInfoFrameScrollFrameScrollBarScrollUpButton	table	framexml
+GuildInfoFrameScrollFrameScrollBarThumbTexture	table	framexml
+GuildInfoSaveButton	table	framexml
+GuildInfoSaveButtonText	table	framexml
+GuildInfoTextBackground	table	framexml
+GuildInfoTitle	table	framexml
+GuildInviteByName	function	engine
+GuildLeave	function	engine
+GuildListScrollFrame	table	framexml
+GuildListScrollFrameScrollBar	table	framexml
+GuildListScrollFrameScrollBarScrollDownButton	table	framexml
+GuildListScrollFrameScrollBarScrollUpButton	table	framexml
+GuildListScrollFrameScrollBarThumbTexture	table	framexml
+GuildListScrollFrameScrollChildFrame	table	framexml
+GuildMOTDEditButton	table	framexml
+GuildMemberDetailCloseButton	table	framexml
+GuildMemberDetailCorner	table	framexml
+GuildMemberDetailFrame	table	framexml
+GuildMemberDetailLevel	table	framexml
+GuildMemberDetailName	table	framexml
+GuildMemberDetailNoteLabel	table	framexml
+GuildMemberDetailOfficerNoteLabel	table	framexml
+GuildMemberDetailOnlineLabel	table	framexml
+GuildMemberDetailOnlineText	table	framexml
+GuildMemberDetailRankLabel	table	framexml
+GuildMemberDetailRankText	table	framexml
+GuildMemberDetailZoneLabel	table	framexml
+GuildMemberDetailZoneText	table	framexml
+GuildMemberGroupInviteButton	table	framexml
+GuildMemberGroupInviteButtonText	table	framexml
+GuildMemberNoteBackground	table	framexml
+GuildMemberOfficerNoteBackground	table	framexml
+GuildMemberRemoveButton	table	framexml
+GuildMemberRemoveButtonText	table	framexml
+GuildPlayerStatusFrame	table	framexml
+GuildPromoteByName	function	engine
+GuildRegistrarButton1	table	framexml
+GuildRegistrarButton2	table	framexml
+GuildRegistrarButton3	lod	framexml
+GuildRegistrarCostLabel	table	framexml
+GuildRegistrarFrame	table	framexml
+GuildRegistrarFrameCancelButton	table	framexml
+GuildRegistrarFrameCancelButtonText	table	framexml
+GuildRegistrarFrameCloseButton	table	framexml
+GuildRegistrarFrameEditBox	table	framexml
+GuildRegistrarFrameGoodbyeButton	table	framexml
+GuildRegistrarFrameGoodbyeButtonText	table	framexml
+GuildRegistrarFrameNpcNameText	table	framexml
+GuildRegistrarFramePortrait	table	framexml
+GuildRegistrarFramePurchaseButton	table	framexml
+GuildRegistrarFramePurchaseButtonText	table	framexml
+GuildRegistrarGreetingFrame	table	framexml
+GuildRegistrarMoneyFrame	table	framexml
+GuildRegistrarMoneyFrameCopperButton	table	framexml
+GuildRegistrarMoneyFrameCopperButtonText	table	framexml
+GuildRegistrarMoneyFrameGoldButton	table	framexml
+GuildRegistrarMoneyFrameGoldButtonText	table	framexml
+GuildRegistrarMoneyFrameSilverButton	table	framexml
+GuildRegistrarMoneyFrameSilverButtonText	table	framexml
+GuildRegistrarNpcNameFrame	table	framexml
+GuildRegistrarPurchaseFrame	table	framexml
+GuildRegistrarPurchaseText	table	framexml
+GuildRegistrarText	table	framexml
+GuildRegistrar_OnShow	function	framexml
+GuildRegistrar_ShowPurchaseFrame	function	framexml
+GuildRoster	function	engine
+GuildRosterSetOfficerNote	function	engine
+GuildRosterSetPublicNote	function	engine
+GuildSetLeaderByName	function	engine
+GuildSetMOTD	function	engine
+GuildStatusFrame	table	framexml
+GuildStatus_Update	function	framexml
+GuildUninviteByName	function	engine
+HANDSSLOT	string	framexml
+HAPPINESS	string	framexml
+HAPPINESS_POINTS	string	framexml
+HARASSMENT	string	framexml
+HARASSMENT_POLICY_TEXT	string	framexml
+HARASSMENT_TEXT	string	framexml
+HARDWARE_CURSOR	string	framexml
+HAVE_MAIL	string	framexml
+HEADSLOT	string	framexml
+HEAD_BOB	string	framexml
+HEALEDCRITOTHEROTHER	string	framexml
+HEALEDCRITOTHERSELF	string	framexml
+HEALEDCRITSELFOTHER	string	framexml
+HEALEDCRITSELFSELF	string	framexml
+HEALEDOTHEROTHER	string	framexml
+HEALEDOTHERSELF	string	framexml
+HEALEDSELFOTHER	string	framexml
+HEALEDSELFSELF	string	framexml
+HEALTH	string	framexml
+HEALTH_COLON	string	framexml
+HEALTH_COST	string	framexml
+HEALTH_COST_PER_TIME	string	framexml
+HEALTH_LOW	string	framexml
+HELPFRAME_ACCOUNT_BULLET1	string	framexml
+HELPFRAME_ACCOUNT_BULLET2	string	framexml
+HELPFRAME_ACCOUNT_BULLET3	string	framexml
+HELPFRAME_ACCOUNT_BULLET4	string	framexml
+HELPFRAME_ACCOUNT_BULLET_TITLE1	string	framexml
+HELPFRAME_ACCOUNT_BUTTON_TEXT	string	framexml
+HELPFRAME_ACCOUNT_ENDTEXT	string	framexml
+HELPFRAME_ACCOUNT_TEXT	string	framexml
+HELPFRAME_ACCOUNT_TITLE	string	framexml
+HELPFRAME_BUG_BUTTON_DESCRIPTION	string	framexml
+HELPFRAME_BUG_BUTTON_TEXT	string	framexml
+HELPFRAME_BULLET_SPACING	number	framexml
+HELPFRAME_CHARACTER_BULLET1	string	framexml
+HELPFRAME_CHARACTER_BULLET2	string	framexml
+HELPFRAME_CHARACTER_BULLET3	string	framexml
+HELPFRAME_CHARACTER_BULLET4	string	framexml
+HELPFRAME_CHARACTER_BULLET5	string	framexml
+HELPFRAME_CHARACTER_BULLET_TITLE1	string	framexml
+HELPFRAME_CHARACTER_BUTTON_TEXT	string	framexml
+HELPFRAME_CHARACTER_TEXT	string	framexml
+HELPFRAME_CHARACTER_TITLE	string	framexml
+HELPFRAME_ENVIRONMENTAL_BULLET1	string	framexml
+HELPFRAME_ENVIRONMENTAL_BULLET2	string	framexml
+HELPFRAME_ENVIRONMENTAL_BULLET3	string	framexml
+HELPFRAME_ENVIRONMENTAL_BULLET4	string	framexml
+HELPFRAME_ENVIRONMENTAL_BULLET5	string	framexml
+HELPFRAME_ENVIRONMENTAL_BULLET6	string	framexml
+HELPFRAME_ENVIRONMENTAL_BULLET_TITLE1	string	framexml
+HELPFRAME_ENVIRONMENTAL_BULLET_TITLE2	string	framexml
+HELPFRAME_ENVIRONMENTAL_BUTTON_TEXT	string	framexml
+HELPFRAME_ENVIRONMENTAL_TEXT	string	framexml
+HELPFRAME_ENVIRONMENTAL_TITLE	string	framexml
+HELPFRAME_FRAMES	table	framexml
+HELPFRAME_GENERAL_BUTTON_DESCRIPTION	string	framexml
+HELPFRAME_GENERAL_BUTTON_TEXT	string	framexml
+HELPFRAME_GM_BUTTON_DESCRIPTION	string	framexml
+HELPFRAME_GM_BUTTON_TEXT	string	framexml
+HELPFRAME_GUILD_BULLET1	string	framexml
+HELPFRAME_GUILD_BULLET2	string	framexml
+HELPFRAME_GUILD_BULLET3	string	framexml
+HELPFRAME_GUILD_BULLET_TITLE1	string	framexml
+HELPFRAME_GUILD_BUTTON_TEXT	string	framexml
+HELPFRAME_GUILD_TEXT	string	framexml
+HELPFRAME_GUILD_TITLE	string	framexml
+HELPFRAME_HARASSMENT_BUTTON_DESCRIPTION	string	framexml
+HELPFRAME_HARASSMENT_BUTTON_TEXT	string	framexml
+HELPFRAME_HOME_BUTTON_TEXT	string	framexml
+HELPFRAME_HOME_ISSUE1	string	framexml
+HELPFRAME_HOME_ISSUE1_HEADER	string	framexml
+HELPFRAME_HOME_ISSUE2	string	framexml
+HELPFRAME_HOME_ISSUE2_HEADER	string	framexml
+HELPFRAME_HOME_ISSUE3	string	framexml
+HELPFRAME_HOME_ISSUE3_HEADER	string	framexml
+HELPFRAME_HOME_TEXT	string	framexml
+HELPFRAME_HOME_TEXT1	string	framexml
+HELPFRAME_HOME_TEXT2	string	framexml
+HELPFRAME_ITEM_BULLET1	string	framexml
+HELPFRAME_ITEM_BULLET2	string	framexml
+HELPFRAME_ITEM_BULLET3	string	framexml
+HELPFRAME_ITEM_BULLET4	string	framexml
+HELPFRAME_ITEM_BULLET5	string	framexml
+HELPFRAME_ITEM_BULLET6	string	framexml
+HELPFRAME_ITEM_BULLET7	string	framexml
+HELPFRAME_ITEM_BULLET_TITLE1	string	framexml
+HELPFRAME_ITEM_BULLET_TITLE2	string	framexml
+HELPFRAME_ITEM_BUTTON_TEXT	string	framexml
+HELPFRAME_ITEM_TEXT	string	framexml
+HELPFRAME_ITEM_TITLE	string	framexml
+HELPFRAME_NONQUEST_BULLET1	string	framexml
+HELPFRAME_NONQUEST_BULLET2	string	framexml
+HELPFRAME_NONQUEST_BULLET3	string	framexml
+HELPFRAME_NONQUEST_BULLET4	string	framexml
+HELPFRAME_NONQUEST_BULLET5	string	framexml
+HELPFRAME_NONQUEST_BULLET6	string	framexml
+HELPFRAME_NONQUEST_BULLET7	string	framexml
+HELPFRAME_NONQUEST_BULLET_TITLE1	string	framexml
+HELPFRAME_NONQUEST_BULLET_TITLE2	string	framexml
+HELPFRAME_NONQUEST_BUTTON_TEXT	string	framexml
+HELPFRAME_NONQUEST_TEXT	string	framexml
+HELPFRAME_NONQUEST_TITLE	string	framexml
+HELPFRAME_OPENTICKET_EDITTEXT	string	framexml
+HELPFRAME_OPENTICKET_TEXT	string	framexml
+HELPFRAME_OTHER_BUTTON_DESCRIPTION	string	framexml
+HELPFRAME_OTHER_BUTTON_TEXT	string	framexml
+HELPFRAME_QUEST_BULLET1	string	framexml
+HELPFRAME_QUEST_BULLET2	string	framexml
+HELPFRAME_QUEST_BULLET3	string	framexml
+HELPFRAME_QUEST_BULLET4	string	framexml
+HELPFRAME_QUEST_BULLET5	string	framexml
+HELPFRAME_QUEST_BULLET_TITLE1	string	framexml
+HELPFRAME_QUEST_BULLET_TITLE2	string	framexml
+HELPFRAME_QUEST_BUTTON_TEXT	string	framexml
+HELPFRAME_QUEST_TEXT	string	framexml
+HELPFRAME_QUEST_TITLE	string	framexml
+HELPFRAME_SECTION_SPACING	number	framexml
+HELPFRAME_STUCK_BUTTON_DESCRIPTION	string	framexml
+HELPFRAME_STUCK_BUTTON_TEXT	string	framexml
+HELPFRAME_STUCK_TEXT1	string	framexml
+HELPFRAME_SUGGESTION_BUTTON_DESCRIPTION	string	framexml
+HELPFRAME_SUGGESTION_BUTTON_TEXT	string	framexml
+HELPFRAME_TECHNICAL_BULLET1	string	framexml
+HELPFRAME_TECHNICAL_BULLET2	string	framexml
+HELPFRAME_TECHNICAL_BULLET3	string	framexml
+HELPFRAME_TECHNICAL_BULLET4	string	framexml
+HELPFRAME_TECHNICAL_BULLET5	string	framexml
+HELPFRAME_TECHNICAL_BULLET6	string	framexml
+HELPFRAME_TECHNICAL_BULLET7	string	framexml
+HELPFRAME_TECHNICAL_BULLET_TITLE1	string	framexml
+HELPFRAME_TECHNICAL_BULLET_TITLE2	string	framexml
+HELPFRAME_TECHNICAL_BUTTON_TEXT	string	framexml
+HELPFRAME_TECHNICAL_TEXT	string	framexml
+HELPFRAME_TECHNICAL_TITLE	string	framexml
+HELP_BUTTON	string	framexml
+HELP_FRAME_TITLE	string	framexml
+HELP_LABEL	string	framexml
+HELP_TEXT_LINE1	string	framexml
+HELP_TEXT_LINE10	string	framexml
+HELP_TEXT_LINE11	string	framexml
+HELP_TEXT_LINE12	string	framexml
+HELP_TEXT_LINE13	string	framexml
+HELP_TEXT_LINE14	string	framexml
+HELP_TEXT_LINE15	string	framexml
+HELP_TEXT_LINE2	string	framexml
+HELP_TEXT_LINE3	string	framexml
+HELP_TEXT_LINE4	string	framexml
+HELP_TEXT_LINE5	string	framexml
+HELP_TEXT_LINE6	string	framexml
+HELP_TEXT_LINE7	string	framexml
+HELP_TEXT_LINE8	string	framexml
+HELP_TEXT_LINE9	string	framexml
+HELP_TEXT_SIMPLE	string	framexml
+HELP_TICKET_ABANDON	string	framexml
+HELP_TICKET_ABANDON_CONFIRM	string	framexml
+HELP_TICKET_EDIT	string	framexml
+HELP_TICKET_EDIT_ABANDON	string	framexml
+HELP_TICKET_QUEUE_DISABLED	string	framexml
+HERTZ	string	framexml
+HIDE	string	framexml
+HIDE_OUTDOOR_WORLD_STATE	string	framexml
+HIDE_OUTDOOR_WORLD_STATE_TEXT	string	framexml
+HIDE_PARTY_INTERFACE	string	framexml
+HIDE_PARTY_INTERFACE_TEXT	string	framexml
+HIDE_PULLOUT_BG	string	framexml
+HIGH	string	framexml
+HIGHLIGHT_FONT_COLOR	table	framexml
+HIGHLIGHT_FONT_COLOR_CODE	string	framexml
+HIGH_BIDDER	string	framexml
+HK	string	framexml
+HOME	string	framexml
+HOME_INN	string	framexml
+HONOR	string	framexml
+HONORABLE_KILLS	string	framexml
+HONORABLE_KILLS_TOOLTIP	string	framexml
+HONOR_CONTRIBUTION_POINTS	string	framexml
+HONOR_GAINED	string	framexml
+HONOR_GAINED_TOOLTIP	string	framexml
+HONOR_HIGHEST_RANK	string	framexml
+HONOR_LASTWEEK	string	framexml
+HONOR_LIFETIME	string	framexml
+HONOR_STANDING	string	framexml
+HONOR_THISWEEK	string	framexml
+HONOR_THIS_SESSION	string	framexml
+HONOR_YESTERDAY	string	framexml
+HOURS	string	framexml
+HOURS_ABBR	string	framexml
+HOURS_ABBR_P1	string	framexml
+HOURS_P1	string	framexml
+HOUR_ONELETTER_ABBR	string	framexml
+HP	string	framexml
+HP_TEMPLATE	string	framexml
+HUNTER_AGILITY_TOOLTIP	string	framexml
+HUNTER_INTELLECT_TOOLTIP	string	framexml
+HasAction	function	engine
+HasFullControl	function	engine
+HasInspectHonorData	function	engine
+HasKey	function	engine
+HasNewMail	function	engine
+HasPetSpells	function	engine
+HasPetUI	function	engine
+HasSoulstone	function	engine
+HasWandEquipped	function	engine
+HealthBar_OnValueChanged	function	framexml
+HelpFrame	table	framexml
+HelpFrameBug	table	framexml
+HelpFrameBugDivider	table	framexml
+HelpFrameBugDividerLeft	table	framexml
+HelpFrameBugDividerMiddle	table	framexml
+HelpFrameBugDividerRight	table	framexml
+HelpFrameBulletPointTemplate	lod	framexml
+HelpFrameBulletTitle1	table	framexml
+HelpFrameBulletTitle2	table	framexml
+HelpFrameButton1	table	framexml
+HelpFrameButton10	table	framexml
+HelpFrameButton10Description	table	framexml
+HelpFrameButton10Text	table	framexml
+HelpFrameButton1Description	table	framexml
+HelpFrameButton1Text	table	framexml
+HelpFrameButton2	table	framexml
+HelpFrameButton2Description	table	framexml
+HelpFrameButton2Text	table	framexml
+HelpFrameButton3	table	framexml
+HelpFrameButton3Description	table	framexml
+HelpFrameButton3Text	table	framexml
+HelpFrameButton4	table	framexml
+HelpFrameButton4Description	table	framexml
+HelpFrameButton4Text	table	framexml
+HelpFrameButton5	table	framexml
+HelpFrameButton5Description	table	framexml
+HelpFrameButton5Text	table	framexml
+HelpFrameButton6	table	framexml
+HelpFrameButton6Description	table	framexml
+HelpFrameButton6Text	table	framexml
+HelpFrameButton7	table	framexml
+HelpFrameButton7Description	table	framexml
+HelpFrameButton7Text	table	framexml
+HelpFrameButton8	table	framexml
+HelpFrameButton8Description	table	framexml
+HelpFrameButton8Text	table	framexml
+HelpFrameButton9	table	framexml
+HelpFrameButton9Description	table	framexml
+HelpFrameButton9Text	table	framexml
+HelpFrameButton_OnClick	function	framexml
+HelpFrameCloseButton	table	framexml
+HelpFrameDividerTemplate	lod	framexml
+HelpFrameEndText	table	framexml
+HelpFrameGM	table	framexml
+HelpFrameGMBack	table	framexml
+HelpFrameGMBackText	table	framexml
+HelpFrameGMCancel	table	framexml
+HelpFrameGMCancelText	table	framexml
+HelpFrameGMScrollFrame	table	framexml
+HelpFrameGMScrollFrameScrollBar	table	framexml
+HelpFrameGMScrollFrameScrollBarBottom	table	framexml
+HelpFrameGMScrollFrameScrollBarMiddle	table	framexml
+HelpFrameGMScrollFrameScrollBarScrollDownButton	table	framexml
+HelpFrameGMScrollFrameScrollBarScrollUpButton	table	framexml
+HelpFrameGMScrollFrameScrollBarThumbTexture	table	framexml
+HelpFrameGMScrollFrameScrollBarTop	table	framexml
+HelpFrameGMScrollFrameScrollChildFrame	table	framexml
+HelpFrameGM_Update	function	framexml
+HelpFrameGM_UpdateCategories	function	framexml
+HelpFrameGeneral	table	framexml
+HelpFrameGeneralBack	table	framexml
+HelpFrameGeneralBackText	table	framexml
+HelpFrameGeneralBullet1	table	framexml
+HelpFrameGeneralBullet10	table	framexml
+HelpFrameGeneralBullet10Text	table	framexml
+HelpFrameGeneralBullet1Text	table	framexml
+HelpFrameGeneralBullet2	table	framexml
+HelpFrameGeneralBullet2Text	table	framexml
+HelpFrameGeneralBullet3	table	framexml
+HelpFrameGeneralBullet3Text	table	framexml
+HelpFrameGeneralBullet4	table	framexml
+HelpFrameGeneralBullet4Text	table	framexml
+HelpFrameGeneralBullet5	table	framexml
+HelpFrameGeneralBullet5Text	table	framexml
+HelpFrameGeneralBullet6	table	framexml
+HelpFrameGeneralBullet6Text	table	framexml
+HelpFrameGeneralBullet7	table	framexml
+HelpFrameGeneralBullet7Text	table	framexml
+HelpFrameGeneralBullet8	table	framexml
+HelpFrameGeneralBullet8Text	table	framexml
+HelpFrameGeneralBullet9	table	framexml
+HelpFrameGeneralBullet9Text	table	framexml
+HelpFrameGeneralButton	table	framexml
+HelpFrameGeneralButton2	table	framexml
+HelpFrameGeneralButton2Left	table	framexml
+HelpFrameGeneralButton2Middle	table	framexml
+HelpFrameGeneralButton2Right	table	framexml
+HelpFrameGeneralButton2Text	table	framexml
+HelpFrameGeneralButtonLeft	table	framexml
+HelpFrameGeneralButtonMiddle	table	framexml
+HelpFrameGeneralButtonRight	table	framexml
+HelpFrameGeneralButtonText	table	framexml
+HelpFrameGeneralButton_OnClick	function	framexml
+HelpFrameGeneralCancel	table	framexml
+HelpFrameGeneralCancelText	table	framexml
+HelpFrameGeneralTitle	table	framexml
+HelpFrameGeneralTitleText	table	framexml
+HelpFrameGeneralTitleText2	table	framexml
+HelpFrameHarassment	table	framexml
+HelpFrameHarassmentBack	table	framexml
+HelpFrameHarassmentBackText	table	framexml
+HelpFrameHarassmentCancel	table	framexml
+HelpFrameHarassmentCancelText	table	framexml
+HelpFrameHarassmentDivider	table	framexml
+HelpFrameHarassmentDivider2	table	framexml
+HelpFrameHarassmentDivider2Left	table	framexml
+HelpFrameHarassmentDivider2Middle	table	framexml
+HelpFrameHarassmentDivider2Right	table	framexml
+HelpFrameHarassmentDividerLeft	table	framexml
+HelpFrameHarassmentDividerMiddle	table	framexml
+HelpFrameHarassmentDividerRight	table	framexml
+HelpFrameHarassmentText	table	framexml
+HelpFrameHeader	table	framexml
+HelpFrameHome	table	framexml
+HelpFrameHomeButtonTemplate	lod	framexml
+HelpFrameHomeCancel	table	framexml
+HelpFrameHomeCancelText	table	framexml
+HelpFrameHomeIssue1	table	framexml
+HelpFrameHomeIssue1Header	table	framexml
+HelpFrameHomeIssue2	table	framexml
+HelpFrameHomeIssue2Header	table	framexml
+HelpFrameHomeIssue3	table	framexml
+HelpFrameHomeIssue3Header	table	framexml
+HelpFrameHomeIssues	table	framexml
+HelpFrameHomeIssuesLeft	table	framexml
+HelpFrameHomeIssuesMiddle	table	framexml
+HelpFrameHomeIssuesRight	table	framexml
+HelpFrameHomeIssuesText	table	framexml
+HelpFrameHomePvpPolicyUrl	table	framexml
+HelpFrameHomeText1	table	framexml
+HelpFrameHomeText2	table	framexml
+HelpFrameHomeTitle	table	framexml
+HelpFrameOpenTicket	table	framexml
+HelpFrameOpenTicketCancel	table	framexml
+HelpFrameOpenTicketCancelText	table	framexml
+HelpFrameOpenTicketDivider	table	framexml
+HelpFrameOpenTicketDividerLeft	table	framexml
+HelpFrameOpenTicketDividerMiddle	table	framexml
+HelpFrameOpenTicketDividerRight	table	framexml
+HelpFrameOpenTicketDropDown_Initialize	function	framexml
+HelpFrameOpenTicketDropDown_OnClick	function	framexml
+HelpFrameOpenTicketDropDown_OnLoad	function	framexml
+HelpFrameOpenTicketDropDown_OnShow	function	framexml
+HelpFrameOpenTicketLabel	table	framexml
+HelpFrameOpenTicketScrollFrame	table	framexml
+HelpFrameOpenTicketScrollFrameScrollBar	table	framexml
+HelpFrameOpenTicketScrollFrameScrollBarBottom	table	framexml
+HelpFrameOpenTicketScrollFrameScrollBarMiddle	table	framexml
+HelpFrameOpenTicketScrollFrameScrollBarScrollDownButton	table	framexml
+HelpFrameOpenTicketScrollFrameScrollBarScrollUpButton	table	framexml
+HelpFrameOpenTicketScrollFrameScrollBarThumbTexture	table	framexml
+HelpFrameOpenTicketScrollFrameScrollBarTop	table	framexml
+HelpFrameOpenTicketSubmit	table	framexml
+HelpFrameOpenTicketSubmitText	table	framexml
+HelpFrameOpenTicketSubmit_OnClick	function	framexml
+HelpFrameOpenTicketText	table	framexml
+HelpFrameOpenTicket_OnEvent	function	framexml
+HelpFramePhysicalHarassment	table	framexml
+HelpFramePhysicalHarassmentButton	table	framexml
+HelpFramePhysicalHarassmentButtonLeft	table	framexml
+HelpFramePhysicalHarassmentButtonMiddle	table	framexml
+HelpFramePhysicalHarassmentButtonRight	table	framexml
+HelpFramePhysicalHarassmentButtonText	table	framexml
+HelpFramePhysicalHarassmentDescription	table	framexml
+HelpFramePhysicalHarassmentText	table	framexml
+HelpFramePhysicalHarassmentTipText	table	framexml
+HelpFrameStuck	table	framexml
+HelpFrameStuckBack	table	framexml
+HelpFrameStuckBackText	table	framexml
+HelpFrameStuckCancel	table	framexml
+HelpFrameStuckCancelText	table	framexml
+HelpFrameStuckStuck	table	framexml
+HelpFrameStuckStuckLeft	table	framexml
+HelpFrameStuckStuckMiddle	table	framexml
+HelpFrameStuckStuckRight	table	framexml
+HelpFrameStuckStuckText	table	framexml
+HelpFrameStuckText1	table	framexml
+HelpFrameStuckTitle	table	framexml
+HelpFrameUnstick_OnClick	function	framexml
+HelpFrameVerbalHarassment	table	framexml
+HelpFrameVerbalHarassmentButton	table	framexml
+HelpFrameVerbalHarassmentButtonLeft	table	framexml
+HelpFrameVerbalHarassmentButtonMiddle	table	framexml
+HelpFrameVerbalHarassmentButtonRight	table	framexml
+HelpFrameVerbalHarassmentButtonText	table	framexml
+HelpFrameVerbalHarassmentDescription	table	framexml
+HelpFrameVerbalHarassmentText	table	framexml
+HelpFrameVerbalHarassmentTipText	table	framexml
+HelpFrame_OnEvent	function	framexml
+HelpFrame_OnLoad	function	framexml
+HelpFrame_OnShow	function	framexml
+HelpFrame_SetupGeneralFrame	function	framexml
+HelpFrame_ShowFrame	function	framexml
+HelpMicroButton	table	framexml
+HideBonusActionBar	function	framexml
+HideDropDownMenu	function	framexml
+HideFriendNameplates	function	engine
+HideNameplates	function	engine
+HidePartyFrame	function	framexml
+HidePetActionBar	function	framexml
+HideRepairCursor	function	engine
+HideTextStatusBarText	function	framexml
+HideUIPanel	function	framexml
+HideWatchedReputationBarText	function	framexml
+HonorFrame	table	framexml
+HonorFrameContributionButtonTemplate	lod	framexml
+HonorFrameCurrentDK	table	framexml
+HonorFrameCurrentDKText	table	framexml
+HonorFrameCurrentDKValue	table	framexml
+HonorFrameCurrentHK	table	framexml
+HonorFrameCurrentHKText	table	framexml
+HonorFrameCurrentHKValue	table	framexml
+HonorFrameCurrentPVPRank	table	framexml
+HonorFrameCurrentPVPTitle	table	framexml
+HonorFrameCurrentSessionTitle	table	framexml
+HonorFrameDKButtonTemplate	lod	framexml
+HonorFrameHKButtonTemplate	lod	framexml
+HonorFrameLastWeekContribution	table	framexml
+HonorFrameLastWeekContributionText	table	framexml
+HonorFrameLastWeekContributionValue	table	framexml
+HonorFrameLastWeekHK	table	framexml
+HonorFrameLastWeekHKText	table	framexml
+HonorFrameLastWeekHKValue	table	framexml
+HonorFrameLastWeekStanding	table	framexml
+HonorFrameLastWeekStandingText	table	framexml
+HonorFrameLastWeekStandingValue	table	framexml
+HonorFrameLastWeekTitle	table	framexml
+HonorFrameLifeTimeDK	table	framexml
+HonorFrameLifeTimeDKText	table	framexml
+HonorFrameLifeTimeDKValue	table	framexml
+HonorFrameLifeTimeHK	table	framexml
+HonorFrameLifeTimeHKText	table	framexml
+HonorFrameLifeTimeHKValue	table	framexml
+HonorFrameLifeTimeRank	table	framexml
+HonorFrameLifeTimeRankText	table	framexml
+HonorFrameLifeTimeRankValue	table	framexml
+HonorFrameLifeTimeTitle	table	framexml
+HonorFrameProgressBar	table	framexml
+HonorFrameProgressBarBar	table	framexml
+HonorFrameProgressButton	table	framexml
+HonorFramePvPIcon	table	framexml
+HonorFrameRankButton	table	framexml
+HonorFrameRankButtonTemplate	lod	framexml
+HonorFrameStandingButtonTemplate	lod	framexml
+HonorFrameTextButtonTemplate	lod	framexml
+HonorFrameThisWeekContribution	table	framexml
+HonorFrameThisWeekContributionText	table	framexml
+HonorFrameThisWeekContributionValue	table	framexml
+HonorFrameThisWeekHK	table	framexml
+HonorFrameThisWeekHKText	table	framexml
+HonorFrameThisWeekHKValue	table	framexml
+HonorFrameThisWeekTitle	table	framexml
+HonorFrameYesterdayContribution	table	framexml
+HonorFrameYesterdayContributionText	table	framexml
+HonorFrameYesterdayContributionValue	table	framexml
+HonorFrameYesterdayHK	table	framexml
+HonorFrameYesterdayHKText	table	framexml
+HonorFrameYesterdayHKValue	table	framexml
+HonorFrameYesterdayTitle	table	framexml
+HonorFrame_OnEvent	function	framexml
+HonorFrame_OnLoad	function	framexml
+HonorFrame_Update	function	framexml
+HonorGuildText	table	framexml
+HonorLevelText	table	framexml
+HorizontalMultiBar1	lod	framexml
+HorizontalMultiBar2	lod	framexml
+ID	string	framexml
+IDLE_MESSAGE	string	framexml
+IGNORE	string	framexml
+IGNORES_TO_DISPLAY	number	framexml
+IGNORE_LIST	string	framexml
+IGNORE_PLAYER	string	framexml
+IGR_BILLING_NAG_DIALOG	string	framexml
+IMMUNE	string	framexml
+IMMUNEDAMAGECLASSOTHEROTHER	string	framexml
+IMMUNEDAMAGECLASSOTHERSELF	string	framexml
+IMMUNEDAMAGECLASSSELFOTHER	string	framexml
+IMMUNEOTHEROTHER	string	framexml
+IMMUNEOTHERSELF	string	framexml
+IMMUNESELFOTHER	string	framexml
+IMMUNESELFSELF	string	framexml
+IMMUNESPELLOTHEROTHER	string	framexml
+IMMUNESPELLOTHERSELF	string	framexml
+IMMUNESPELLSELFOTHER	string	framexml
+IMMUNESPELLSELFSELF	string	framexml
+INBOX	string	framexml
+INBOXITEMS_TO_DISPLAY	number	framexml
+INCREASE_POTENTIAL	string	framexml
+INITIAL_TALENT_OFFSET_X	lod	framexml
+INITIAL_TALENT_OFFSET_Y	lod	framexml
+INPUT_CHINESE	string	framexml
+INPUT_JAPANESE	string	framexml
+INPUT_KOREAN	string	framexml
+INPUT_ROMAN	string	framexml
+INSPECT	string	framexml
+INSPECTFRAME_SUBFRAMES	lod	framexml
+INSPECT_NOTIFY	string	framexml
+INSTAKILLOTHER	string	framexml
+INSTAKILLSELF	string	framexml
+INSTANCE	string	framexml
+INSTANCE_BOOT_TIMER	string	framexml
+INSTANCE_COMPLETE_MESSAGE	string	framexml
+INSTANCE_RESET_FAILED	string	framexml
+INSTANCE_RESET_FAILED_OFFLINE	string	framexml
+INSTANCE_RESET_FAILED_ZONING	string	framexml
+INSTANCE_RESET_SUCCESS	string	framexml
+INSTANCE_SAVED	string	framexml
+INSTANCE_SHUTDOWN_MESSAGE	string	framexml
+INTELLECT_COLON	string	framexml
+INTELLECT_TOOLTIP	string	framexml
+INTERRUPT	string	framexml
+INTERRUPTED	string	framexml
+INT_SPELL_DURATION_DAYS	string	framexml
+INT_SPELL_DURATION_HOURS	string	framexml
+INT_SPELL_DURATION_HOURS_P1	string	framexml
+INT_SPELL_DURATION_MIN	string	framexml
+INT_SPELL_DURATION_SEC	string	framexml
+INT_SPELL_POINTS_SPREAD_TEMPLATE	string	framexml
+INVENTORY_ALERT_COLORS	table	framexml
+INVENTORY_ALERT_STATUS_SLOTS	table	framexml
+INVENTORY_FULL	string	framexml
+INVENTORY_TOOLTIP	string	framexml
+INVERT_MOUSE	string	framexml
+INVITATION	string	framexml
+INVTYPE_2HWEAPON	string	framexml
+INVTYPE_BAG	string	framexml
+INVTYPE_BODY	string	framexml
+INVTYPE_CHEST	string	framexml
+INVTYPE_CLOAK	string	framexml
+INVTYPE_FEET	string	framexml
+INVTYPE_FINGER	string	framexml
+INVTYPE_HAND	string	framexml
+INVTYPE_HEAD	string	framexml
+INVTYPE_HOLDABLE	string	framexml
+INVTYPE_LEGS	string	framexml
+INVTYPE_NECK	string	framexml
+INVTYPE_RANGED	string	framexml
+INVTYPE_RELIC	string	framexml
+INVTYPE_ROBE	string	framexml
+INVTYPE_SHIELD	string	framexml
+INVTYPE_SHOULDER	string	framexml
+INVTYPE_TABARD	string	framexml
+INVTYPE_TRINKET	string	framexml
+INVTYPE_WAIST	string	framexml
+INVTYPE_WEAPON	string	framexml
+INVTYPE_WEAPONMAINHAND	string	framexml
+INVTYPE_WEAPONOFFHAND	string	framexml
+INVTYPE_WRIST	string	framexml
+ITEMENCHANTMENTADDOTHEROTHER	string	framexml
+ITEMENCHANTMENTADDOTHERSELF	string	framexml
+ITEMENCHANTMENTADDSELFOTHER	string	framexml
+ITEMENCHANTMENTADDSELFSELF	string	framexml
+ITEMENCHANTMENTREMOVEOTHER	string	framexml
+ITEMENCHANTMENTREMOVESELF	string	framexml
+ITEMPRESENTINOFFHAND	string	framexml
+ITEMS	string	framexml
+ITEMSLOTTEXT	string	framexml
+ITEM_BIND_ON_EQUIP	string	framexml
+ITEM_BIND_ON_PICKUP	string	framexml
+ITEM_BIND_ON_USE	string	framexml
+ITEM_BIND_QUEST	string	framexml
+ITEM_CANT_BE_DESTROYED	string	framexml
+ITEM_CLASSES_ALLOWED	string	framexml
+ITEM_CONJURED	string	framexml
+ITEM_COOLDOWN_TIME_DAYS	string	framexml
+ITEM_COOLDOWN_TIME_DAYS_P1	string	framexml
+ITEM_COOLDOWN_TIME_HOURS	string	framexml
+ITEM_COOLDOWN_TIME_HOURS_P1	string	framexml
+ITEM_COOLDOWN_TIME_MIN	string	framexml
+ITEM_COOLDOWN_TIME_SEC	string	framexml
+ITEM_CREATED_BY	string	framexml
+ITEM_DURATION_DAYS	string	framexml
+ITEM_DURATION_HOURS	string	framexml
+ITEM_DURATION_MIN	string	framexml
+ITEM_DURATION_SEC	string	framexml
+ITEM_ENCHANT_DISCLAIMER	string	framexml
+ITEM_ENCHANT_TIME_LEFT_DAYS	string	framexml
+ITEM_ENCHANT_TIME_LEFT_DAYS_P1	string	framexml
+ITEM_ENCHANT_TIME_LEFT_HOURS	string	framexml
+ITEM_ENCHANT_TIME_LEFT_HOURS_P1	string	framexml
+ITEM_ENCHANT_TIME_LEFT_MIN	string	framexml
+ITEM_ENCHANT_TIME_LEFT_SEC	string	framexml
+ITEM_LEVEL	string	framexml
+ITEM_LEVEL_AND_MIN	string	framexml
+ITEM_MIN_LEVEL	string	framexml
+ITEM_MIN_SKILL	string	framexml
+ITEM_MOD_AGILITY	string	framexml
+ITEM_MOD_HEALTH	string	framexml
+ITEM_MOD_INTELLECT	string	framexml
+ITEM_MOD_MANA	string	framexml
+ITEM_MOD_SPIRIT	string	framexml
+ITEM_MOD_STAMINA	string	framexml
+ITEM_MOD_STRENGTH	string	framexml
+ITEM_MOUSE_OVER	string	framexml
+ITEM_NO_DROP	string	framexml
+ITEM_OPENABLE	string	framexml
+ITEM_PROPOSED_ENCHANT	string	framexml
+ITEM_PURCHASED_COLON	string	framexml
+ITEM_QUALITY0_DESC	string	framexml
+ITEM_QUALITY1_DESC	string	framexml
+ITEM_QUALITY2_DESC	string	framexml
+ITEM_QUALITY3_DESC	string	framexml
+ITEM_QUALITY4_DESC	string	framexml
+ITEM_QUALITY5_DESC	string	framexml
+ITEM_QUALITY6_DESC	string	framexml
+ITEM_QUALITY_COLORS	table	framexml
+ITEM_RACES_ALLOWED	string	framexml
+ITEM_RANDOM_ENCHANT	string	framexml
+ITEM_READABLE	string	framexml
+ITEM_REQ_REPUTATION	string	framexml
+ITEM_REQ_SKILL	string	framexml
+ITEM_RESIST_ALL	string	framexml
+ITEM_RESIST_SINGLE	string	framexml
+ITEM_SET_BONUS	string	framexml
+ITEM_SET_BONUS_GRAY	string	framexml
+ITEM_SET_NAME	string	framexml
+ITEM_SIGNABLE	string	framexml
+ITEM_SOLD_COLON	string	framexml
+ITEM_SOULBOUND	string	framexml
+ITEM_SPELL_CHARGES	string	framexml
+ITEM_SPELL_CHARGES_P1	string	framexml
+ITEM_SPELL_EFFECT	string	framexml
+ITEM_SPELL_KNOWN	string	framexml
+ITEM_SPELL_TRIGGER_ONEQUIP	string	framexml
+ITEM_SPELL_TRIGGER_ONPROC	string	framexml
+ITEM_SPELL_TRIGGER_ONUSE	string	framexml
+ITEM_STARTS_QUEST	string	framexml
+ITEM_SUFFIX_TEMPLATE	string	framexml
+ITEM_TEXT_FROM	string	framexml
+ITEM_UNIQUE	string	framexml
+ITEM_UNIQUE_MULTIPLE	string	framexml
+ITEM_UNSELLABLE	string	framexml
+ITEM_WRAPPED_BY	string	framexml
+ITEM_WRITTEN_BY	string	framexml
+ITEM_WRONG_CLASS	string	framexml
+ITEM_WRONG_RACE	string	framexml
+IgnoreFrameToggleTab1	table	framexml
+IgnoreFrameToggleTab1HighlightTexture	table	framexml
+IgnoreFrameToggleTab1Left	table	framexml
+IgnoreFrameToggleTab1LeftDisabled	table	framexml
+IgnoreFrameToggleTab1Middle	table	framexml
+IgnoreFrameToggleTab1MiddleDisabled	table	framexml
+IgnoreFrameToggleTab1Right	table	framexml
+IgnoreFrameToggleTab1RightDisabled	table	framexml
+IgnoreFrameToggleTab1Text	table	framexml
+IgnoreFrameToggleTab2	table	framexml
+IgnoreFrameToggleTab2HighlightTexture	table	framexml
+IgnoreFrameToggleTab2Left	table	framexml
+IgnoreFrameToggleTab2LeftDisabled	table	framexml
+IgnoreFrameToggleTab2Middle	table	framexml
+IgnoreFrameToggleTab2MiddleDisabled	table	framexml
+IgnoreFrameToggleTab2Right	table	framexml
+IgnoreFrameToggleTab2RightDisabled	table	framexml
+IgnoreFrameToggleTab2Text	table	framexml
+IgnoreListFrame	table	framexml
+IgnoreList_Update	function	framexml
+InCinematic	function	engine
+InGuildCheck	function	framexml
+InRepairMode	function	engine
+InboxCloseButton	table	framexml
+InboxCurrentPage	table	framexml
+InboxFrame	table	framexml
+InboxFrameItem_OnEnter	function	framexml
+InboxFrame_OnClick	function	framexml
+InboxFrame_Update	function	framexml
+InboxItemCanDelete	function	engine
+InboxNextPage	function	framexml
+InboxNextPageButton	table	framexml
+InboxPrevPage	function	framexml
+InboxPrevPageButton	table	framexml
+InboxTitleText	table	framexml
+InitiateTrade	function	engine
+InputBoxTemplate	lod	framexml
+InspectBackSlot	lod	framexml
+InspectChestSlot	lod	framexml
+InspectFeetSlot	lod	framexml
+InspectFinger0Slot	lod	framexml
+InspectFinger1Slot	lod	framexml
+InspectFrame	lod	framexml
+InspectFrameCloseButton	lod	framexml
+InspectFramePortrait	lod	framexml
+InspectFrameTab1	lod	framexml
+InspectFrameTab2	lod	framexml
+InspectFrameTab_OnClick	lod	framexml
+InspectFrame_LoadUI	function	framexml
+InspectFrame_OnEvent	lod	framexml
+InspectFrame_OnHide	lod	framexml
+InspectFrame_OnLoad	lod	framexml
+InspectFrame_OnShow	lod	framexml
+InspectFrame_OnUpdate	lod	framexml
+InspectFrame_Show	lod	framexml
+InspectFrame_ShowSubFrame	lod	framexml
+InspectGuildText	lod	framexml
+InspectHandsSlot	lod	framexml
+InspectHeadSlot	lod	framexml
+InspectHonorFrame	lod	framexml
+InspectHonorFrameCurrentDK	lod	framexml
+InspectHonorFrameCurrentHK	lod	framexml
+InspectHonorFrameCurrentPVPRank	lod	framexml
+InspectHonorFrameCurrentPVPTitle	lod	framexml
+InspectHonorFrameCurrentSessionTitle	lod	framexml
+InspectHonorFrameLastWeekContribution	lod	framexml
+InspectHonorFrameLastWeekHK	lod	framexml
+InspectHonorFrameLastWeekStanding	lod	framexml
+InspectHonorFrameLastWeekTitle	lod	framexml
+InspectHonorFrameLifeTimeDK	lod	framexml
+InspectHonorFrameLifeTimeHK	lod	framexml
+InspectHonorFrameLifeTimeRank	lod	framexml
+InspectHonorFrameLifeTimeTitle	lod	framexml
+InspectHonorFrameProgressBar	lod	framexml
+InspectHonorFrameProgressButton	lod	framexml
+InspectHonorFramePvPIcon	lod	framexml
+InspectHonorFrameRankButton	lod	framexml
+InspectHonorFrameThisWeekContribution	lod	framexml
+InspectHonorFrameThisWeekHK	lod	framexml
+InspectHonorFrameThisWeekTitle	lod	framexml
+InspectHonorFrameYesterdayContribution	lod	framexml
+InspectHonorFrameYesterdayHK	lod	framexml
+InspectHonorFrameYesterdayTitle	lod	framexml
+InspectHonorFrame_OnEvent	lod	framexml
+InspectHonorFrame_OnLoad	lod	framexml
+InspectHonorFrame_OnShow	lod	framexml
+InspectHonorFrame_Update	lod	framexml
+InspectLegsSlot	lod	framexml
+InspectLevelText	lod	framexml
+InspectMainHandSlot	lod	framexml
+InspectModelFrame	lod	framexml
+InspectModelFrame_OnLoad	lod	framexml
+InspectModelFrame_OnUpdate	lod	framexml
+InspectModelRotateLeftButton	lod	framexml
+InspectModelRotateLeftButton_OnClick	lod	framexml
+InspectModelRotateRightButton	lod	framexml
+InspectModelRotateRightButton_OnClick	lod	framexml
+InspectNameFrame	lod	framexml
+InspectNameText	lod	framexml
+InspectNeckSlot	lod	framexml
+InspectPaperDollFrame	lod	framexml
+InspectPaperDollFrame_OnEvent	lod	framexml
+InspectPaperDollFrame_OnLoad	lod	framexml
+InspectPaperDollFrame_OnShow	lod	framexml
+InspectPaperDollFrame_SetLevel	lod	framexml
+InspectPaperDollItemSlotButtonTemplate	lod	framexml
+InspectPaperDollItemSlotButton_OnClick	lod	framexml
+InspectPaperDollItemSlotButton_OnEvent	lod	framexml
+InspectPaperDollItemSlotButton_OnLoad	lod	framexml
+InspectPaperDollItemSlotButton_Update	lod	framexml
+InspectRangedSlot	lod	framexml
+InspectSecondaryHandSlot	lod	framexml
+InspectShirtSlot	lod	framexml
+InspectShoulderSlot	lod	framexml
+InspectTabardSlot	lod	framexml
+InspectTitleText	lod	framexml
+InspectTrinket0Slot	lod	framexml
+InspectTrinket1Slot	lod	framexml
+InspectUnit	function	framexml
+InspectWaistSlot	lod	framexml
+InspectWristSlot	lod	framexml
+InviteByName	function	engine
+InviteToParty	function	engine
+InvoiceTextFontNormal	table	framexml
+InvoiceTextFontSmall	table	framexml
+IsActionInRange	function	engine
+IsAddOnLoadOnDemand	function	engine
+IsAddOnLoaded	function	engine
+IsAlreadyInQueue	function	framexml
+IsAltKeyDown	function	engine
+IsAttackAction	function	engine
+IsAuctionSortReversed	function	engine
+IsAutoRepeatAction	function	engine
+IsBagOpen	function	framexml
+IsConsumableAction	function	engine
+IsControlKeyDown	function	engine
+IsCurrentAction	function	engine
+IsCurrentCast	function	engine
+IsCurrentQuestFailed	function	engine
+IsEquippedAction	function	engine
+IsFactionInactive	function	engine
+IsFishingLoot	function	engine
+IsGuildLeader	function	engine
+IsInGuild	function	engine
+IsInInstance	function	engine
+IsInMeetingStoneQueue	function	engine
+IsInventoryItemLocked	function	engine
+IsLinuxClient	function	engine
+IsMacClient	function	engine
+IsMouselooking	function	engine
+IsOptionFrameOpen	function	framexml
+IsPartyLeader	function	engine
+IsPetAttackActive	function	engine
+IsQuestCompletable	function	engine
+IsQuestWatched	function	engine
+IsRaidLeader	function	engine
+IsRaidOfficer	function	engine
+IsResting	function	engine
+IsShiftKeyDown	function	engine
+IsSpellPassive	function	engine
+IsTalentTrainer	function	engine
+IsTradeskillTrainer	function	engine
+IsTrainerServiceLearnSpell	function	engine
+IsTrainerServiceSkillStep	function	engine
+IsTrainerServiceTradeSkill	function	engine
+IsUnitOnQuest	function	engine
+IsUsableAction	function	engine
+IsUsableCheckButton	lod	framexml
+IsVendorActive	function	engine
+IsWindowsClient	function	engine
+ItemAnimTemplate	lod	framexml
+ItemAnim_OnAnimFinished	function	framexml
+ItemAnim_OnEvent	function	framexml
+ItemAnim_OnLoad	function	framexml
+ItemButtonTemplate	lod	framexml
+ItemRefCloseButton	table	framexml
+ItemRefTooltip	table	framexml
+ItemRefTooltipMoneyFrame	table	framexml
+ItemRefTooltipMoneyFrameCopperButton	table	framexml
+ItemRefTooltipMoneyFrameCopperButtonText	table	framexml
+ItemRefTooltipMoneyFrameGoldButton	table	framexml
+ItemRefTooltipMoneyFrameGoldButtonText	table	framexml
+ItemRefTooltipMoneyFrameSilverButton	table	framexml
+ItemRefTooltipMoneyFrameSilverButtonText	table	framexml
+ItemRefTooltipStatusBar	table	framexml
+ItemRefTooltipStatusBarTexture	table	framexml
+ItemRefTooltipTextLeft1	table	framexml
+ItemRefTooltipTextLeft10	table	framexml
+ItemRefTooltipTextLeft11	table	framexml
+ItemRefTooltipTextLeft12	table	framexml
+ItemRefTooltipTextLeft13	table	framexml
+ItemRefTooltipTextLeft14	table	framexml
+ItemRefTooltipTextLeft15	table	framexml
+ItemRefTooltipTextLeft16	table	framexml
+ItemRefTooltipTextLeft17	table	framexml
+ItemRefTooltipTextLeft18	table	framexml
+ItemRefTooltipTextLeft19	table	framexml
+ItemRefTooltipTextLeft2	table	framexml
+ItemRefTooltipTextLeft20	table	framexml
+ItemRefTooltipTextLeft21	table	framexml
+ItemRefTooltipTextLeft22	table	framexml
+ItemRefTooltipTextLeft23	table	framexml
+ItemRefTooltipTextLeft24	table	framexml
+ItemRefTooltipTextLeft25	table	framexml
+ItemRefTooltipTextLeft26	table	framexml
+ItemRefTooltipTextLeft27	table	framexml
+ItemRefTooltipTextLeft28	table	framexml
+ItemRefTooltipTextLeft29	table	framexml
+ItemRefTooltipTextLeft3	table	framexml
+ItemRefTooltipTextLeft30	table	framexml
+ItemRefTooltipTextLeft4	table	framexml
+ItemRefTooltipTextLeft5	table	framexml
+ItemRefTooltipTextLeft6	table	framexml
+ItemRefTooltipTextLeft7	table	framexml
+ItemRefTooltipTextLeft8	table	framexml
+ItemRefTooltipTextLeft9	table	framexml
+ItemRefTooltipTextRight1	table	framexml
+ItemRefTooltipTextRight10	table	framexml
+ItemRefTooltipTextRight11	table	framexml
+ItemRefTooltipTextRight12	table	framexml
+ItemRefTooltipTextRight13	table	framexml
+ItemRefTooltipTextRight14	table	framexml
+ItemRefTooltipTextRight15	table	framexml
+ItemRefTooltipTextRight16	table	framexml
+ItemRefTooltipTextRight17	table	framexml
+ItemRefTooltipTextRight18	table	framexml
+ItemRefTooltipTextRight19	table	framexml
+ItemRefTooltipTextRight2	table	framexml
+ItemRefTooltipTextRight20	table	framexml
+ItemRefTooltipTextRight21	table	framexml
+ItemRefTooltipTextRight22	table	framexml
+ItemRefTooltipTextRight23	table	framexml
+ItemRefTooltipTextRight24	table	framexml
+ItemRefTooltipTextRight25	table	framexml
+ItemRefTooltipTextRight26	table	framexml
+ItemRefTooltipTextRight27	table	framexml
+ItemRefTooltipTextRight28	table	framexml
+ItemRefTooltipTextRight29	table	framexml
+ItemRefTooltipTextRight3	table	framexml
+ItemRefTooltipTextRight30	table	framexml
+ItemRefTooltipTextRight4	table	framexml
+ItemRefTooltipTextRight5	table	framexml
+ItemRefTooltipTextRight6	table	framexml
+ItemRefTooltipTextRight7	table	framexml
+ItemRefTooltipTextRight8	table	framexml
+ItemRefTooltipTextRight9	table	framexml
+ItemRefTooltipTexture1	table	framexml
+ItemRefTooltipTexture2	table	framexml
+ItemRefTooltipTexture3	table	framexml
+ItemTextCloseButton	table	framexml
+ItemTextCurrentPage	table	framexml
+ItemTextFontNormal	table	framexml
+ItemTextFrame	table	framexml
+ItemTextFrame_OnEvent	function	framexml
+ItemTextFrame_OnLoad	function	framexml
+ItemTextFrame_OnUpdate	function	framexml
+ItemTextGetCreator	function	engine
+ItemTextGetItem	function	engine
+ItemTextGetMaterial	function	engine
+ItemTextGetPage	function	engine
+ItemTextGetText	function	engine
+ItemTextHasNextPage	function	engine
+ItemTextMaterialBotLeft	table	framexml
+ItemTextMaterialBotRight	table	framexml
+ItemTextMaterialTopLeft	table	framexml
+ItemTextMaterialTopRight	table	framexml
+ItemTextNextPage	function	engine
+ItemTextNextPageButton	table	framexml
+ItemTextPageScrollChild	table	framexml
+ItemTextPageText	table	framexml
+ItemTextPrevPage	function	engine
+ItemTextPrevPageButton	table	framexml
+ItemTextScrollFrame	table	framexml
+ItemTextScrollFrameBottom	table	framexml
+ItemTextScrollFrameMiddle	table	framexml
+ItemTextScrollFrameScrollBar	table	framexml
+ItemTextScrollFrameScrollBarScrollDownButton	table	framexml
+ItemTextScrollFrameScrollBarScrollUpButton	table	framexml
+ItemTextScrollFrameScrollBarThumbTexture	table	framexml
+ItemTextScrollFrameTop	table	framexml
+ItemTextStatusBar	table	framexml
+ItemTextTitleText	table	framexml
+JOINED_PARTY	string	framexml
+JOIN_AS_GROUP	string	framexml
+JOIN_AS_GROUP_TOOLTIP	string	framexml
+JOIN_NEW_CHANNEL	string	framexml
+JoinBattlefield	function	engine
+JoinChannelByName	function	engine
+Jump	function	engine
+KEY1	string	framexml
+KEY2	string	framexml
+KEYBINDINGFRAME_MOUSEWHEEL_ERROR	string	framexml
+KEYRING	string	framexml
+KEYRING_CONTAINER	number	framexml
+KEY_APOSTROPHE	string	framexml
+KEY_BACKSLASH	string	framexml
+KEY_BACKSPACE	string	framexml
+KEY_BACKSPACE_MAC	string	framexml
+KEY_BINDINGS	string	framexml
+KEY_BINDINGS_DISPLAYED	lod	framexml
+KEY_BINDING_HEIGHT	lod	framexml
+KEY_BOUND	string	framexml
+KEY_BUTTON3	string	framexml
+KEY_BUTTON4	string	framexml
+KEY_BUTTON5	string	framexml
+KEY_COMMA	string	framexml
+KEY_DELETE	string	framexml
+KEY_DELETE_MAC	string	framexml
+KEY_DOWN	string	framexml
+KEY_END	string	framexml
+KEY_ENTER	string	framexml
+KEY_ENTER_MAC	string	framexml
+KEY_ESCAPE	string	framexml
+KEY_HOME	string	framexml
+KEY_INSERT	string	framexml
+KEY_INSERT_MAC	string	framexml
+KEY_LEFT	string	framexml
+KEY_LEFTBRACKET	string	framexml
+KEY_MINUS	string	framexml
+KEY_MOUSEWHEELDOWN	string	framexml
+KEY_MOUSEWHEELUP	string	framexml
+KEY_NUMLOCK	string	framexml
+KEY_NUMLOCK_MAC	string	framexml
+KEY_NUMPAD0	string	framexml
+KEY_NUMPAD1	string	framexml
+KEY_NUMPAD2	string	framexml
+KEY_NUMPAD3	string	framexml
+KEY_NUMPAD4	string	framexml
+KEY_NUMPAD5	string	framexml
+KEY_NUMPAD6	string	framexml
+KEY_NUMPAD7	string	framexml
+KEY_NUMPAD8	string	framexml
+KEY_NUMPAD9	string	framexml
+KEY_NUMPADDECIMAL	string	framexml
+KEY_NUMPADDIVIDE	string	framexml
+KEY_NUMPADMINUS	string	framexml
+KEY_NUMPADMULTIPLY	string	framexml
+KEY_NUMPADPLUS	string	framexml
+KEY_PAGEDOWN	string	framexml
+KEY_PAGEUP	string	framexml
+KEY_PAUSE	string	framexml
+KEY_PAUSE_MAC	string	framexml
+KEY_PERIOD	string	framexml
+KEY_PLUS	string	framexml
+KEY_PRINTSCREEN	string	framexml
+KEY_PRINTSCREEN_MAC	string	framexml
+KEY_RIGHT	string	framexml
+KEY_RIGHTBRACKET	string	framexml
+KEY_SCROLLLOCK	string	framexml
+KEY_SCROLLLOCK_MAC	string	framexml
+KEY_SEMICOLON	string	framexml
+KEY_SLASH	string	framexml
+KEY_SPACE	string	framexml
+KEY_TAB	string	framexml
+KEY_TILDE	string	framexml
+KEY_UNBOUND_ERROR	string	framexml
+KEY_UP	string	framexml
+KILLING_BLOWS	string	framexml
+KILLING_BLOW_TOOLTIP	string	framexml
+KILLS	string	framexml
+KNOWLEDGE_BASE	string	framexml
+KNOWN_TALENTS_HEADER	string	framexml
+KeyBindingButton_OnClick	lod	framexml
+KeyBindingFrame	lod	framexml
+KeyBindingFrameBinding1	lod	framexml
+KeyBindingFrameBinding10	lod	framexml
+KeyBindingFrameBinding11	lod	framexml
+KeyBindingFrameBinding12	lod	framexml
+KeyBindingFrameBinding13	lod	framexml
+KeyBindingFrameBinding14	lod	framexml
+KeyBindingFrameBinding15	lod	framexml
+KeyBindingFrameBinding16	lod	framexml
+KeyBindingFrameBinding17	lod	framexml
+KeyBindingFrameBinding2	lod	framexml
+KeyBindingFrameBinding3	lod	framexml
+KeyBindingFrameBinding4	lod	framexml
+KeyBindingFrameBinding5	lod	framexml
+KeyBindingFrameBinding6	lod	framexml
+KeyBindingFrameBinding7	lod	framexml
+KeyBindingFrameBinding8	lod	framexml
+KeyBindingFrameBinding9	lod	framexml
+KeyBindingFrameBindingButtonTemplate	lod	framexml
+KeyBindingFrameBindingTemplate	lod	framexml
+KeyBindingFrameCancelButton	lod	framexml
+KeyBindingFrameCharacterButton	lod	framexml
+KeyBindingFrameCommandLabel	lod	framexml
+KeyBindingFrameDefaultButton	lod	framexml
+KeyBindingFrameHeader	lod	framexml
+KeyBindingFrameHeaderText	lod	framexml
+KeyBindingFrameKey1Label	lod	framexml
+KeyBindingFrameKey2Label	lod	framexml
+KeyBindingFrameOkayButton	lod	framexml
+KeyBindingFrameOutputText	lod	framexml
+KeyBindingFrameScrollFrame	lod	framexml
+KeyBindingFrameUnbindButton	lod	framexml
+KeyBindingFrame_ChangeBindingProfile	lod	framexml
+KeyBindingFrame_LoadUI	function	framexml
+KeyBindingFrame_OnKeyDown	lod	framexml
+KeyBindingFrame_OnLoad	lod	framexml
+KeyBindingFrame_OnShow	lod	framexml
+KeyBindingFrame_SetBinding	lod	framexml
+KeyBindingFrame_Update	lod	framexml
+KeyBindingFrame_UpdateUnbindKey	lod	framexml
+KeyRingButton	table	framexml
+KeyRingButtonIDToInvSlotID	function	engine
+KeyRingButtonItemAnim	table	framexml
+KeyRingItemButton_OnClick	function	framexml
+LABEL_NOTE	string	framexml
+LANGUAGE	string	framexml
+LASTONLINE	string	framexml
+LASTONLINE_DAYS	string	framexml
+LASTONLINE_DAYS_P1	string	framexml
+LASTONLINE_HOURS	string	framexml
+LASTONLINE_HOURS_P1	string	framexml
+LASTONLINE_MINS	string	framexml
+LASTONLINE_MONTHS	string	framexml
+LASTONLINE_MONTHS_P1	string	framexml
+LASTONLINE_YEARS	string	framexml
+LASTONLINE_YEARS_P1	string	framexml
+LAST_ONLINE_COLON	string	framexml
+LAST_TUTORIAL_BUTTON_SHOWN	lod	framexml
+LAUGH_WORD1	string	framexml
+LAUGH_WORD2	string	framexml
+LAUGH_WORD3	string	framexml
+LAUGH_WORD4	string	framexml
+LAUGH_WORD5	string	framexml
+LAUGH_WORD6	string	framexml
+LAUGH_WORD7	string	framexml
+LAUGH_WORD8	string	framexml
+LAUGH_WORD9	string	framexml
+LEARN_SKILL_TEMPLATE	string	framexml
+LEAVE_QUEUE	string	framexml
+LEAVING_COMBAT	string	framexml
+LEFT_ACTIONBAR_PAGE	number	framexml
+LEFT_PARTY	string	framexml
+LEGSSLOT	string	framexml
+LESS_THAN_ONE_MINUTE	string	framexml
+LEVEL	string	framexml
+LEVEL_ABBR	string	framexml
+LEVEL_GAINED	string	framexml
+LEVEL_RANGE	string	framexml
+LEVEL_REQUIRED	string	framexml
+LEVEL_TOO_LOW	string	framexml
+LEVEL_UP	string	framexml
+LEVEL_UP_CHAR_POINTS	string	framexml
+LEVEL_UP_CHAR_POINTS_P1	string	framexml
+LEVEL_UP_HEALTH	string	framexml
+LEVEL_UP_HEALTH_MANA	string	framexml
+LEVEL_UP_SKILL_POINTS	string	framexml
+LEVEL_UP_SKILL_POINTS_P1	string	framexml
+LEVEL_UP_STAT	string	framexml
+LFGQuery	function	engine
+LFG_LABEL	string	framexml
+LIGHTYELLOW_FONT_COLOR_CODE	string	framexml
+LOCALE_enGB	boolean	framexml
+LOCATION_COLON	string	framexml
+LOCK	string	framexml
+LOCKED	string	framexml
+LOCKED_WITH_ITEM	string	framexml
+LOCKED_WITH_SPELL	string	framexml
+LOCKED_WITH_SPELL_KNOWN	string	framexml
+LOCK_ACTIONBAR	string	framexml
+LOCK_ACTIONBAR_TEXT	string	framexml
+LOCK_BATTLEFIELDMINIMAP	string	framexml
+LOCK_WINDOW	string	framexml
+LOGOUT	string	framexml
+LOG_PERIODIC_EFFECTS	string	framexml
+LOOKING	string	framexml
+LOOT	string	framexml
+LOOTFRAME_NUMBUTTONS	number	framexml
+LOOT_FREE_FOR_ALL	string	framexml
+LOOT_GONE	string	framexml
+LOOT_GROUP_LOOT	string	framexml
+LOOT_ITEM	string	framexml
+LOOT_ITEM_CREATED_SELF	string	framexml
+LOOT_ITEM_CREATED_SELF_MULTIPLE	string	framexml
+LOOT_ITEM_MULTIPLE	string	framexml
+LOOT_ITEM_PUSHED_SELF	string	framexml
+LOOT_ITEM_PUSHED_SELF_MULTIPLE	string	framexml
+LOOT_ITEM_SELF	string	framexml
+LOOT_ITEM_SELF_MULTIPLE	string	framexml
+LOOT_MASTER_LOOTER	string	framexml
+LOOT_METHOD	string	framexml
+LOOT_MONEY	string	framexml
+LOOT_MONEY_SPLIT	string	framexml
+LOOT_NEED_BEFORE_GREED	string	framexml
+LOOT_NEXT_PAGE	string	framexml
+LOOT_NO_DROP	string	framexml
+LOOT_PROMOTE	string	framexml
+LOOT_ROLL_ALL_PASSED	string	framexml
+LOOT_ROLL_GREED	string	framexml
+LOOT_ROLL_GREED_SELF	string	framexml
+LOOT_ROLL_NEED	string	framexml
+LOOT_ROLL_NEED_SELF	string	framexml
+LOOT_ROLL_PASSED	string	framexml
+LOOT_ROLL_PASSED_SELF	string	framexml
+LOOT_ROLL_ROLLED	string	framexml
+LOOT_ROLL_ROLLED_GREED	string	framexml
+LOOT_ROLL_ROLLED_GREED_SELF	string	framexml
+LOOT_ROLL_ROLLED_NEED	string	framexml
+LOOT_ROLL_ROLLED_NEED_SELF	string	framexml
+LOOT_ROLL_ROLLED_SELF	string	framexml
+LOOT_ROLL_START	string	framexml
+LOOT_ROLL_WON	string	framexml
+LOOT_ROLL_WON_NO_SPAM_GREED	string	framexml
+LOOT_ROLL_WON_NO_SPAM_NEED	string	framexml
+LOOT_ROLL_YOU_WON	string	framexml
+LOOT_ROLL_YOU_WON_NO_SPAM_GREED	string	framexml
+LOOT_ROLL_YOU_WON_NO_SPAM_NEED	string	framexml
+LOOT_ROUND_ROBIN	string	framexml
+LOOT_THRESHOLD	string	framexml
+LOSING_LOYALTY	string	framexml
+LOW	string	framexml
+LanguageMenu	table	framexml
+LanguageMenuButton1	table	framexml
+LanguageMenuButton10	table	framexml
+LanguageMenuButton10ShortcutText	table	framexml
+LanguageMenuButton11	table	framexml
+LanguageMenuButton11ShortcutText	table	framexml
+LanguageMenuButton12	table	framexml
+LanguageMenuButton12ShortcutText	table	framexml
+LanguageMenuButton13	table	framexml
+LanguageMenuButton13ShortcutText	table	framexml
+LanguageMenuButton14	table	framexml
+LanguageMenuButton14ShortcutText	table	framexml
+LanguageMenuButton15	table	framexml
+LanguageMenuButton15ShortcutText	table	framexml
+LanguageMenuButton16	table	framexml
+LanguageMenuButton16ShortcutText	table	framexml
+LanguageMenuButton17	table	framexml
+LanguageMenuButton17ShortcutText	table	framexml
+LanguageMenuButton18	table	framexml
+LanguageMenuButton18ShortcutText	table	framexml
+LanguageMenuButton19	table	framexml
+LanguageMenuButton19ShortcutText	table	framexml
+LanguageMenuButton1ShortcutText	table	framexml
+LanguageMenuButton2	table	framexml
+LanguageMenuButton20	table	framexml
+LanguageMenuButton20ShortcutText	table	framexml
+LanguageMenuButton21	table	framexml
+LanguageMenuButton21ShortcutText	table	framexml
+LanguageMenuButton22	table	framexml
+LanguageMenuButton22ShortcutText	table	framexml
+LanguageMenuButton23	table	framexml
+LanguageMenuButton23ShortcutText	table	framexml
+LanguageMenuButton24	table	framexml
+LanguageMenuButton24ShortcutText	table	framexml
+LanguageMenuButton25	table	framexml
+LanguageMenuButton25ShortcutText	table	framexml
+LanguageMenuButton26	table	framexml
+LanguageMenuButton26ShortcutText	table	framexml
+LanguageMenuButton27	table	framexml
+LanguageMenuButton27ShortcutText	table	framexml
+LanguageMenuButton28	table	framexml
+LanguageMenuButton28ShortcutText	table	framexml
+LanguageMenuButton29	table	framexml
+LanguageMenuButton29ShortcutText	table	framexml
+LanguageMenuButton2ShortcutText	table	framexml
+LanguageMenuButton3	table	framexml
+LanguageMenuButton30	table	framexml
+LanguageMenuButton30ShortcutText	table	framexml
+LanguageMenuButton31	table	framexml
+LanguageMenuButton31ShortcutText	table	framexml
+LanguageMenuButton32	table	framexml
+LanguageMenuButton32ShortcutText	table	framexml
+LanguageMenuButton3ShortcutText	table	framexml
+LanguageMenuButton4	table	framexml
+LanguageMenuButton4ShortcutText	table	framexml
+LanguageMenuButton5	table	framexml
+LanguageMenuButton5ShortcutText	table	framexml
+LanguageMenuButton6	table	framexml
+LanguageMenuButton6ShortcutText	table	framexml
+LanguageMenuButton7	table	framexml
+LanguageMenuButton7ShortcutText	table	framexml
+LanguageMenuButton8	table	framexml
+LanguageMenuButton8ShortcutText	table	framexml
+LanguageMenuButton9	table	framexml
+LanguageMenuButton9ShortcutText	table	framexml
+LanguageMenu_Click	function	framexml
+LanguageMenu_LoadLanguages	function	framexml
+LanguageMenu_OnEvent	function	framexml
+LanguageMenu_OnLoad	function	framexml
+LearnTalent	function	engine
+LeaveBattlefield	function	engine
+LeaveChannelByName	function	engine
+LeaveParty	function	engine
+ListChannelByName	function	engine
+ListChannels	function	engine
+LoadAddOn	function	engine
+LoadBindings	function	engine
+LoadMicroButtonTextures	function	framexml
+Localize	function	framexml
+LocalizeFrames	function	framexml
+LockPetActionBar	function	framexml
+LoggingChat	function	engine
+LoggingCombat	function	engine
+Logout	function	engine
+LootButton1	table	framexml
+LootButton1Count	table	framexml
+LootButton1IconTexture	table	framexml
+LootButton1NormalTexture	table	framexml
+LootButton1Stock	table	framexml
+LootButton1Text	table	framexml
+LootButton2	table	framexml
+LootButton2Count	table	framexml
+LootButton2IconTexture	table	framexml
+LootButton2NormalTexture	table	framexml
+LootButton2Stock	table	framexml
+LootButton2Text	table	framexml
+LootButton3	table	framexml
+LootButton3Count	table	framexml
+LootButton3IconTexture	table	framexml
+LootButton3NormalTexture	table	framexml
+LootButton3Stock	table	framexml
+LootButton3Text	table	framexml
+LootButton4	table	framexml
+LootButton4Count	table	framexml
+LootButton4IconTexture	table	framexml
+LootButton4NormalTexture	table	framexml
+LootButton4Stock	table	framexml
+LootButton4Text	table	framexml
+LootButtonTemplate	lod	framexml
+LootCloseButton	table	framexml
+LootFrame	table	framexml
+LootFrameDownButton	table	framexml
+LootFrameItem_OnClick	function	framexml
+LootFrameNext	table	framexml
+LootFramePortraitOverlay	table	framexml
+LootFramePrev	table	framexml
+LootFrameUpButton	table	framexml
+LootFrame_OnEvent	function	framexml
+LootFrame_OnHide	function	framexml
+LootFrame_OnLoad	function	framexml
+LootFrame_OnShow	function	framexml
+LootFrame_PageDown	function	framexml
+LootFrame_PageUp	function	framexml
+LootFrame_Update	function	framexml
+LootSlot	function	engine
+LootSlotIsCoin	function	engine
+LootSlotIsItem	function	engine
+LowHealthFrame	table	framexml
+LowerBlackBar	table	framexml
+LowerFrameLevel	function	framexml
+MACRO	string	framexml
+MACROFRAME_CHAR_LIMIT	string	framexml
+MACROS	string	framexml
+MACRO_ACTION_FORBIDDEN	string	framexml
+MACRO_HELP_TEXT_LINE1	string	framexml
+MACRO_HELP_TEXT_LINE2	string	framexml
+MACRO_HELP_TEXT_LINE3	string	framexml
+MACRO_HELP_TEXT_LINE4	string	framexml
+MACRO_HELP_TEXT_LINE5	string	framexml
+MACRO_ICON_ROW_HEIGHT	lod	framexml
+MACRO_POPUP_CHOOSE_ICON	string	framexml
+MACRO_POPUP_TEXT	string	framexml
+MAGE_INTELLECT_TOOLTIP	string	framexml
+MAGIC_RESISTANCES_COLON	string	framexml
+MAIL_COD_ERROR	string	framexml
+MAIL_LABEL	string	framexml
+MAIL_LETTER_TOOLTIP	string	framexml
+MAIL_REPLY_PREFIX	string	framexml
+MAIL_RETURN	string	framexml
+MAIL_SUBJECT_LABEL	string	framexml
+MAIL_TO_LABEL	string	framexml
+MAINHANDSLOT	string	framexml
+MAINMENUBAR_LATENCY_LABEL	string	framexml
+MAINMENU_BUTTON	string	framexml
+MAIN_MENU	string	framexml
+MALE	string	framexml
+MANA	string	framexml
+MANAGE_ACCOUNT	string	framexml
+MANAGE_ACCOUNT_URL	string	framexml
+MANA_COLON	string	framexml
+MANA_COST	string	framexml
+MANA_COST_PER_TIME	string	framexml
+MANA_LOW	string	framexml
+MANA_POINTS	string	framexml
+MARKED_AFK	string	framexml
+MARKED_AFK_MESSAGE	string	framexml
+MARKED_DND	string	framexml
+MASTERY_POINTS_SPENT	string	framexml
+MASTER_LOOT_THREHOLD	number	framexml
+MASTER_VOLUME	string	framexml
+MATERIAL_TEXT_COLOR_TABLE	table	framexml
+MATERIAL_TITLETEXT_COLOR_TABLE	table	framexml
+MAXIMUM_BID_PRICE	lod	framexml
+MAX_BATTLEFIELD_QUEUES	number	framexml
+MAX_BG_TEXTURES	number	framexml
+MAX_COD_AMOUNT	number	framexml
+MAX_COMBO_POINTS	number	framexml
+MAX_CONTAINER_ITEMS	number	framexml
+MAX_CRAFT_REAGENTS	lod	framexml
+MAX_FOLLOW_DIST	string	framexml
+MAX_GENDER_INDICES	number	framexml
+MAX_GENERAL_BULLETS	number	framexml
+MAX_GUILDCONTROL_OPTIONS	number	framexml
+MAX_HP_TEMPLATE	string	framexml
+MAX_IGNORE	number	framexml
+MAX_LEARNABLE_PROFESSIONS	lod	framexml
+MAX_MACROS	lod	framexml
+MAX_NUM_ARROW_TEXTURES	lod	framexml
+MAX_NUM_BRANCH_TEXTURES	lod	framexml
+MAX_NUM_ITEMS	number	framexml
+MAX_NUM_PARTY_MEMBERS	number	framexml
+MAX_NUM_QUESTS	number	framexml
+MAX_NUM_STAT_COLUMNS	number	framexml
+MAX_NUM_TALENTS	lod	framexml
+MAX_NUM_TALENT_TIERS	lod	framexml
+MAX_OBJECTIVES	number	framexml
+MAX_PARTY_DEBUFFS	number	framexml
+MAX_PARTY_MEMBERS	number	framexml
+MAX_PARTY_TOOLTIP_BUFFS	number	framexml
+MAX_PARTY_TOOLTIP_DEBUFFS	number	framexml
+MAX_PETITION_SIGNATURES	number	framexml
+MAX_PLAYER_LEVEL	number	framexml
+MAX_PLURAL_INDICES	number	framexml
+MAX_QUESTLOG_QUESTS	number	framexml
+MAX_QUESTS	number	framexml
+MAX_QUESTWATCH_LINES	number	framexml
+MAX_QUEST_WATCH_TIMER	number	framexml
+MAX_RADIO_BUTTONS	lod	framexml
+MAX_RAID_INFOS	number	framexml
+MAX_RAID_MEMBERS	number	framexml
+MAX_REQUIRED_ITEMS	number	framexml
+MAX_SKILLLINE_TABS	number	framexml
+MAX_SPELLS	number	framexml
+MAX_SPELL_PAGES	number	framexml
+MAX_SURVEY_QUESTIONS	lod	framexml
+MAX_TALENT_TABS	lod	framexml
+MAX_TARGET_BUFFS	number	framexml
+MAX_TARGET_DEBUFFS	number	framexml
+MAX_TRADABLE_ITEMS	number	framexml
+MAX_TRADE_ITEMS	number	framexml
+MAX_TRADE_SKILL_REAGENTS	lod	framexml
+MAX_TUTORIAL_ALERTS	number	framexml
+MAX_WATCHABLE_QUESTS	number	framexml
+MAX_WHOS_FROM_SERVER	number	framexml
+MAX_WORLDSTATE_SCORE_BUTTONS	number	framexml
+MEETINGSTONE_LEVEL	string	framexml
+MEETINGSTONE_TOOLTIP	string	framexml
+MELEE_ATTACK	string	framexml
+MELEE_ATTACK_POWER	string	framexml
+MELEE_ATTACK_POWER_TOOLTIP	string	framexml
+MEMBERS	string	framexml
+MEMBERS_PER_RAID_GROUP	number	framexml
+MEMORY_EXHAUSTED	string	framexml
+MERCHANT	string	framexml
+MERCHANT_BUYBACK	string	framexml
+MERCHANT_ITEMS_PER_PAGE	number	framexml
+MERCHANT_STOCK	string	framexml
+MESSAGE_SCROLLBUTTON_INITIAL_DELAY	number	framexml
+MESSAGE_SCROLLBUTTON_SCROLL_DELAY	number	framexml
+MESSAGE_TYPES	string	framexml
+MILLISECONDS_ABBR	string	framexml
+MINIMAPPING_FADE_TIMER	number	framexml
+MINIMAPPING_TIMER	number	framexml
+MINIMAP_LABEL	string	framexml
+MINUTES	string	framexml
+MINUTES_ABBR	string	framexml
+MINUTES_ABBR_P1	string	framexml
+MINUTES_P1	string	framexml
+MINUTE_ONELETTER_ABBR	string	framexml
+MIRRORTIMER_NUMTIMERS	number	framexml
+MISCELLANEOUS	string	framexml
+MISS	string	framexml
+MISSEDOTHEROTHER	string	framexml
+MISSEDOTHERSELF	string	framexml
+MISSEDSELFOTHER	string	framexml
+MODIFIERS_COLON	string	framexml
+MONEY	string	framexml
+MONEY_BUTTON_SPACING	number	framexml
+MONEY_BUTTON_SPACING_SMALL	number	framexml
+MONEY_ICON_WIDTH	number	framexml
+MONEY_ICON_WIDTH_SMALL	number	framexml
+MORE_REAGENTS	string	framexml
+MOUSE_LOOK_SPEED	string	framexml
+MOUSE_SENSITIVITY	string	framexml
+MOVE_TO_INACTIVE	string	framexml
+MOVING_CHATFRAME	lod	framexml
+MOVING_RAID_MEMBER	lod	framexml
+MOVING_RAID_PULLOUT	lod	framexml
+MP	string	framexml
+MULTISAMPLE	string	framexml
+MULTISAMPLING_FORMAT_STRING	string	framexml
+MUSIC_VOLUME	string	framexml
+MacroButton1	lod	framexml
+MacroButton10	lod	framexml
+MacroButton11	lod	framexml
+MacroButton12	lod	framexml
+MacroButton13	lod	framexml
+MacroButton14	lod	framexml
+MacroButton15	lod	framexml
+MacroButton16	lod	framexml
+MacroButton17	lod	framexml
+MacroButton18	lod	framexml
+MacroButton2	lod	framexml
+MacroButton3	lod	framexml
+MacroButton4	lod	framexml
+MacroButton5	lod	framexml
+MacroButton6	lod	framexml
+MacroButton7	lod	framexml
+MacroButton8	lod	framexml
+MacroButton9	lod	framexml
+MacroButtonTemplate	lod	framexml
+MacroButton_OnClick	lod	framexml
+MacroDeleteButton	lod	framexml
+MacroEditButton	lod	framexml
+MacroEditButton_OnClick	lod	framexml
+MacroExitButton	lod	framexml
+MacroFrame	lod	framexml
+MacroFrameButtonTemplate	lod	framexml
+MacroFrameCharLimitText	lod	framexml
+MacroFrameCloseButton	lod	framexml
+MacroFrameEnterMacroText	lod	framexml
+MacroFramePortrait	lod	framexml
+MacroFrameScrollFrame	lod	framexml
+MacroFrameSelectedMacroBackground	lod	framexml
+MacroFrameSelectedMacroButton	lod	framexml
+MacroFrameSelectedMacroName	lod	framexml
+MacroFrameTab1	lod	framexml
+MacroFrameTab2	lod	framexml
+MacroFrameText	lod	framexml
+MacroFrameTextBackground	lod	framexml
+MacroFrameTextButton	lod	framexml
+MacroFrame_AddMacroLine	lod	framexml
+MacroFrame_HideDetails	lod	framexml
+MacroFrame_LoadUI	function	framexml
+MacroFrame_OnHide	lod	framexml
+MacroFrame_OnLoad	lod	framexml
+MacroFrame_OnShow	lod	framexml
+MacroFrame_SaveMacro	lod	framexml
+MacroFrame_SelectMacro	lod	framexml
+MacroFrame_SetAccountMacros	lod	framexml
+MacroFrame_SetCharacterMacros	lod	framexml
+MacroFrame_Show	lod	framexml
+MacroFrame_ShowDetails	lod	framexml
+MacroFrame_Update	lod	framexml
+MacroHorizontalBarLeft	lod	framexml
+MacroNewButton	lod	framexml
+MacroNewButton_OnClick	lod	framexml
+MacroPopupButton1	lod	framexml
+MacroPopupButton10	lod	framexml
+MacroPopupButton11	lod	framexml
+MacroPopupButton12	lod	framexml
+MacroPopupButton13	lod	framexml
+MacroPopupButton14	lod	framexml
+MacroPopupButton15	lod	framexml
+MacroPopupButton16	lod	framexml
+MacroPopupButton17	lod	framexml
+MacroPopupButton18	lod	framexml
+MacroPopupButton19	lod	framexml
+MacroPopupButton2	lod	framexml
+MacroPopupButton20	lod	framexml
+MacroPopupButton3	lod	framexml
+MacroPopupButton4	lod	framexml
+MacroPopupButton5	lod	framexml
+MacroPopupButton6	lod	framexml
+MacroPopupButton7	lod	framexml
+MacroPopupButton8	lod	framexml
+MacroPopupButton9	lod	framexml
+MacroPopupButtonTemplate	lod	framexml
+MacroPopupButton_OnClick	lod	framexml
+MacroPopupCancelButton	lod	framexml
+MacroPopupEditBox	lod	framexml
+MacroPopupFrame	lod	framexml
+MacroPopupFrame_OnHide	lod	framexml
+MacroPopupFrame_OnShow	lod	framexml
+MacroPopupFrame_Update	lod	framexml
+MacroPopupNameLeft	lod	framexml
+MacroPopupNameMiddle	lod	framexml
+MacroPopupNameRight	lod	framexml
+MacroPopupOkayButton	lod	framexml
+MacroPopupOkayButton_OnClick	lod	framexml
+MacroPopupOkayButton_Update	lod	framexml
+MacroPopupScrollFrame	lod	framexml
+MagicResFrame1	table	framexml
+MagicResFrame2	table	framexml
+MagicResFrame3	table	framexml
+MagicResFrame4	table	framexml
+MagicResFrame5	table	framexml
+MagicResText1	table	framexml
+MagicResText2	table	framexml
+MagicResText3	table	framexml
+MagicResText4	table	framexml
+MagicResText5	table	framexml
+MagicResistanceFrameTemplate	lod	framexml
+MailFrame	table	framexml
+MailFrameBotLeft	table	framexml
+MailFrameBotRight	table	framexml
+MailFrameTab1	table	framexml
+MailFrameTab1HighlightTexture	table	framexml
+MailFrameTab1Left	table	framexml
+MailFrameTab1LeftDisabled	table	framexml
+MailFrameTab1Middle	table	framexml
+MailFrameTab1MiddleDisabled	table	framexml
+MailFrameTab1Right	table	framexml
+MailFrameTab1RightDisabled	table	framexml
+MailFrameTab1Text	table	framexml
+MailFrameTab2	table	framexml
+MailFrameTab2HighlightTexture	table	framexml
+MailFrameTab2Left	table	framexml
+MailFrameTab2LeftDisabled	table	framexml
+MailFrameTab2Middle	table	framexml
+MailFrameTab2MiddleDisabled	table	framexml
+MailFrameTab2Right	table	framexml
+MailFrameTab2RightDisabled	table	framexml
+MailFrameTab2Text	table	framexml
+MailFrameTab_OnClick	function	framexml
+MailFrameTopLeft	table	framexml
+MailFrameTopRight	table	framexml
+MailFrame_OnEvent	function	framexml
+MailFrame_Onload	function	framexml
+MailItem1	table	framexml
+MailItem1Button	table	framexml
+MailItem1ButtonCOD	table	framexml
+MailItem1ButtonIcon	table	framexml
+MailItem1ButtonSlot	table	framexml
+MailItem1ExpireTime	table	framexml
+MailItem1Sender	table	framexml
+MailItem1Subject	table	framexml
+MailItem2	table	framexml
+MailItem2Button	table	framexml
+MailItem2ButtonCOD	table	framexml
+MailItem2ButtonIcon	table	framexml
+MailItem2ButtonSlot	table	framexml
+MailItem2ExpireTime	table	framexml
+MailItem2Sender	table	framexml
+MailItem2Subject	table	framexml
+MailItem3	table	framexml
+MailItem3Button	table	framexml
+MailItem3ButtonCOD	table	framexml
+MailItem3ButtonIcon	table	framexml
+MailItem3ButtonSlot	table	framexml
+MailItem3ExpireTime	table	framexml
+MailItem3Sender	table	framexml
+MailItem3Subject	table	framexml
+MailItem4	table	framexml
+MailItem4Button	table	framexml
+MailItem4ButtonCOD	table	framexml
+MailItem4ButtonIcon	table	framexml
+MailItem4ButtonSlot	table	framexml
+MailItem4ExpireTime	table	framexml
+MailItem4Sender	table	framexml
+MailItem4Subject	table	framexml
+MailItem5	table	framexml
+MailItem5Button	table	framexml
+MailItem5ButtonCOD	table	framexml
+MailItem5ButtonIcon	table	framexml
+MailItem5ButtonSlot	table	framexml
+MailItem5ExpireTime	table	framexml
+MailItem5Sender	table	framexml
+MailItem5Subject	table	framexml
+MailItem6	table	framexml
+MailItem6Button	table	framexml
+MailItem6ButtonCOD	table	framexml
+MailItem6ButtonIcon	table	framexml
+MailItem6ButtonSlot	table	framexml
+MailItem6ExpireTime	table	framexml
+MailItem6Sender	table	framexml
+MailItem6Subject	table	framexml
+MailItem7	table	framexml
+MailItem7Button	table	framexml
+MailItem7ButtonCOD	table	framexml
+MailItem7ButtonIcon	table	framexml
+MailItem7ButtonSlot	table	framexml
+MailItem7ExpireTime	table	framexml
+MailItem7Sender	table	framexml
+MailItem7Subject	table	framexml
+MailItemTemplate	lod	framexml
+MailTextFontNormal	table	framexml
+MainMenuBar	table	framexml
+MainMenuBarArtFrame	table	framexml
+MainMenuBarBackpackButton	table	framexml
+MainMenuBarBackpackButtonCount	table	framexml
+MainMenuBarBackpackButtonIconTexture	table	framexml
+MainMenuBarBackpackButtonItemAnim	table	framexml
+MainMenuBarBackpackButtonNormalTexture	table	framexml
+MainMenuBarBackpackButtonStock	table	framexml
+MainMenuBarExpText	table	framexml
+MainMenuBarLeftEndCap	table	framexml
+MainMenuBarMaxLevelBar	table	framexml
+MainMenuBarMicroButton	lod	framexml
+MainMenuBarOverlayFrame	table	framexml
+MainMenuBarPageNumber	table	framexml
+MainMenuBarPerformanceBar	table	framexml
+MainMenuBarPerformanceBarFrame	table	framexml
+MainMenuBarPerformanceBarFrameButton	table	framexml
+MainMenuBarRightEndCap	table	framexml
+MainMenuBarTexture0	table	framexml
+MainMenuBarTexture1	table	framexml
+MainMenuBarTexture2	table	framexml
+MainMenuBarTexture3	table	framexml
+MainMenuBar_UpdateKeyRing	function	framexml
+MainMenuExpBar	table	framexml
+MainMenuExpBar_Update	function	framexml
+MainMenuMaxLevelBar0	table	framexml
+MainMenuMaxLevelBar1	table	framexml
+MainMenuMaxLevelBar2	table	framexml
+MainMenuMaxLevelBar3	table	framexml
+MainMenuMicroButton	table	framexml
+MainMenuXPBarTexture0	table	framexml
+MainMenuXPBarTexture1	table	framexml
+MainMenuXPBarTexture2	table	framexml
+MainMenuXPBarTexture3	table	framexml
+MakeMinigameMove	function	engine
+ManaBarColor	table	framexml
+MasterFont	table	framexml
+MeleeAttackBackgroundBottom	table	framexml
+MeleeAttackBackgroundMiddle	table	framexml
+MeleeAttackBackgroundTop	table	framexml
+MerchantBuyBackItem	table	framexml
+MerchantBuyBackItemItemButton	table	framexml
+MerchantBuyBackItemItemButtonCount	table	framexml
+MerchantBuyBackItemItemButtonIconTexture	table	framexml
+MerchantBuyBackItemItemButtonNormalTexture	table	framexml
+MerchantBuyBackItemItemButtonStock	table	framexml
+MerchantBuyBackItemMoneyFrame	table	framexml
+MerchantBuyBackItemMoneyFrameCopperButton	table	framexml
+MerchantBuyBackItemMoneyFrameCopperButtonText	table	framexml
+MerchantBuyBackItemMoneyFrameGoldButton	table	framexml
+MerchantBuyBackItemMoneyFrameGoldButtonText	table	framexml
+MerchantBuyBackItemMoneyFrameSilverButton	table	framexml
+MerchantBuyBackItemMoneyFrameSilverButtonText	table	framexml
+MerchantBuyBackItemName	table	framexml
+MerchantBuyBackItemNameFrame	table	framexml
+MerchantBuyBackItemSlotTexture	table	framexml
+MerchantFrame	table	framexml
+MerchantFrameBottomLeftBorder	table	framexml
+MerchantFrameBottomRightBorder	table	framexml
+MerchantFrameCloseButton	table	framexml
+MerchantFramePortrait	table	framexml
+MerchantFrameTab1	table	framexml
+MerchantFrameTab1HighlightTexture	table	framexml
+MerchantFrameTab1Left	table	framexml
+MerchantFrameTab1LeftDisabled	table	framexml
+MerchantFrameTab1Middle	table	framexml
+MerchantFrameTab1MiddleDisabled	table	framexml
+MerchantFrameTab1Right	table	framexml
+MerchantFrameTab1RightDisabled	table	framexml
+MerchantFrameTab1Text	table	framexml
+MerchantFrameTab2	table	framexml
+MerchantFrameTab2HighlightTexture	table	framexml
+MerchantFrameTab2Left	table	framexml
+MerchantFrameTab2LeftDisabled	table	framexml
+MerchantFrameTab2Middle	table	framexml
+MerchantFrameTab2MiddleDisabled	table	framexml
+MerchantFrameTab2Right	table	framexml
+MerchantFrameTab2RightDisabled	table	framexml
+MerchantFrameTab2Text	table	framexml
+MerchantFrame_OnEvent	function	framexml
+MerchantFrame_OnHide	function	framexml
+MerchantFrame_OnLoad	function	framexml
+MerchantFrame_OnShow	function	framexml
+MerchantFrame_Update	function	framexml
+MerchantFrame_UpdateBuybackInfo	function	framexml
+MerchantFrame_UpdateMerchantInfo	function	framexml
+MerchantItem1	table	framexml
+MerchantItem10	table	framexml
+MerchantItem10ItemButton	table	framexml
+MerchantItem10ItemButtonCount	table	framexml
+MerchantItem10ItemButtonIconTexture	table	framexml
+MerchantItem10ItemButtonNormalTexture	table	framexml
+MerchantItem10ItemButtonStock	table	framexml
+MerchantItem10MoneyFrame	table	framexml
+MerchantItem10MoneyFrameCopperButton	table	framexml
+MerchantItem10MoneyFrameCopperButtonText	table	framexml
+MerchantItem10MoneyFrameGoldButton	table	framexml
+MerchantItem10MoneyFrameGoldButtonText	table	framexml
+MerchantItem10MoneyFrameSilverButton	table	framexml
+MerchantItem10MoneyFrameSilverButtonText	table	framexml
+MerchantItem10Name	table	framexml
+MerchantItem10NameFrame	table	framexml
+MerchantItem10SlotTexture	table	framexml
+MerchantItem11	table	framexml
+MerchantItem11ItemButton	table	framexml
+MerchantItem11ItemButtonCount	table	framexml
+MerchantItem11ItemButtonIconTexture	table	framexml
+MerchantItem11ItemButtonNormalTexture	table	framexml
+MerchantItem11ItemButtonStock	table	framexml
+MerchantItem11MoneyFrame	table	framexml
+MerchantItem11MoneyFrameCopperButton	table	framexml
+MerchantItem11MoneyFrameCopperButtonText	table	framexml
+MerchantItem11MoneyFrameGoldButton	table	framexml
+MerchantItem11MoneyFrameGoldButtonText	table	framexml
+MerchantItem11MoneyFrameSilverButton	table	framexml
+MerchantItem11MoneyFrameSilverButtonText	table	framexml
+MerchantItem11Name	table	framexml
+MerchantItem11NameFrame	table	framexml
+MerchantItem11SlotTexture	table	framexml
+MerchantItem12	table	framexml
+MerchantItem12ItemButton	table	framexml
+MerchantItem12ItemButtonCount	table	framexml
+MerchantItem12ItemButtonIconTexture	table	framexml
+MerchantItem12ItemButtonNormalTexture	table	framexml
+MerchantItem12ItemButtonStock	table	framexml
+MerchantItem12MoneyFrame	table	framexml
+MerchantItem12MoneyFrameCopperButton	table	framexml
+MerchantItem12MoneyFrameCopperButtonText	table	framexml
+MerchantItem12MoneyFrameGoldButton	table	framexml
+MerchantItem12MoneyFrameGoldButtonText	table	framexml
+MerchantItem12MoneyFrameSilverButton	table	framexml
+MerchantItem12MoneyFrameSilverButtonText	table	framexml
+MerchantItem12Name	table	framexml
+MerchantItem12NameFrame	table	framexml
+MerchantItem12SlotTexture	table	framexml
+MerchantItem1ItemButton	table	framexml
+MerchantItem1ItemButtonCount	table	framexml
+MerchantItem1ItemButtonIconTexture	table	framexml
+MerchantItem1ItemButtonNormalTexture	table	framexml
+MerchantItem1ItemButtonStock	table	framexml
+MerchantItem1MoneyFrame	table	framexml
+MerchantItem1MoneyFrameCopperButton	table	framexml
+MerchantItem1MoneyFrameCopperButtonText	table	framexml
+MerchantItem1MoneyFrameGoldButton	table	framexml
+MerchantItem1MoneyFrameGoldButtonText	table	framexml
+MerchantItem1MoneyFrameSilverButton	table	framexml
+MerchantItem1MoneyFrameSilverButtonText	table	framexml
+MerchantItem1Name	table	framexml
+MerchantItem1NameFrame	table	framexml
+MerchantItem1SlotTexture	table	framexml
+MerchantItem2	table	framexml
+MerchantItem2ItemButton	table	framexml
+MerchantItem2ItemButtonCount	table	framexml
+MerchantItem2ItemButtonIconTexture	table	framexml
+MerchantItem2ItemButtonNormalTexture	table	framexml
+MerchantItem2ItemButtonStock	table	framexml
+MerchantItem2MoneyFrame	table	framexml
+MerchantItem2MoneyFrameCopperButton	table	framexml
+MerchantItem2MoneyFrameCopperButtonText	table	framexml
+MerchantItem2MoneyFrameGoldButton	table	framexml
+MerchantItem2MoneyFrameGoldButtonText	table	framexml
+MerchantItem2MoneyFrameSilverButton	table	framexml
+MerchantItem2MoneyFrameSilverButtonText	table	framexml
+MerchantItem2Name	table	framexml
+MerchantItem2NameFrame	table	framexml
+MerchantItem2SlotTexture	table	framexml
+MerchantItem3	table	framexml
+MerchantItem3ItemButton	table	framexml
+MerchantItem3ItemButtonCount	table	framexml
+MerchantItem3ItemButtonIconTexture	table	framexml
+MerchantItem3ItemButtonNormalTexture	table	framexml
+MerchantItem3ItemButtonStock	table	framexml
+MerchantItem3MoneyFrame	table	framexml
+MerchantItem3MoneyFrameCopperButton	table	framexml
+MerchantItem3MoneyFrameCopperButtonText	table	framexml
+MerchantItem3MoneyFrameGoldButton	table	framexml
+MerchantItem3MoneyFrameGoldButtonText	table	framexml
+MerchantItem3MoneyFrameSilverButton	table	framexml
+MerchantItem3MoneyFrameSilverButtonText	table	framexml
+MerchantItem3Name	table	framexml
+MerchantItem3NameFrame	table	framexml
+MerchantItem3SlotTexture	table	framexml
+MerchantItem4	table	framexml
+MerchantItem4ItemButton	table	framexml
+MerchantItem4ItemButtonCount	table	framexml
+MerchantItem4ItemButtonIconTexture	table	framexml
+MerchantItem4ItemButtonNormalTexture	table	framexml
+MerchantItem4ItemButtonStock	table	framexml
+MerchantItem4MoneyFrame	table	framexml
+MerchantItem4MoneyFrameCopperButton	table	framexml
+MerchantItem4MoneyFrameCopperButtonText	table	framexml
+MerchantItem4MoneyFrameGoldButton	table	framexml
+MerchantItem4MoneyFrameGoldButtonText	table	framexml
+MerchantItem4MoneyFrameSilverButton	table	framexml
+MerchantItem4MoneyFrameSilverButtonText	table	framexml
+MerchantItem4Name	table	framexml
+MerchantItem4NameFrame	table	framexml
+MerchantItem4SlotTexture	table	framexml
+MerchantItem5	table	framexml
+MerchantItem5ItemButton	table	framexml
+MerchantItem5ItemButtonCount	table	framexml
+MerchantItem5ItemButtonIconTexture	table	framexml
+MerchantItem5ItemButtonNormalTexture	table	framexml
+MerchantItem5ItemButtonStock	table	framexml
+MerchantItem5MoneyFrame	table	framexml
+MerchantItem5MoneyFrameCopperButton	table	framexml
+MerchantItem5MoneyFrameCopperButtonText	table	framexml
+MerchantItem5MoneyFrameGoldButton	table	framexml
+MerchantItem5MoneyFrameGoldButtonText	table	framexml
+MerchantItem5MoneyFrameSilverButton	table	framexml
+MerchantItem5MoneyFrameSilverButtonText	table	framexml
+MerchantItem5Name	table	framexml
+MerchantItem5NameFrame	table	framexml
+MerchantItem5SlotTexture	table	framexml
+MerchantItem6	table	framexml
+MerchantItem6ItemButton	table	framexml
+MerchantItem6ItemButtonCount	table	framexml
+MerchantItem6ItemButtonIconTexture	table	framexml
+MerchantItem6ItemButtonNormalTexture	table	framexml
+MerchantItem6ItemButtonStock	table	framexml
+MerchantItem6MoneyFrame	table	framexml
+MerchantItem6MoneyFrameCopperButton	table	framexml
+MerchantItem6MoneyFrameCopperButtonText	table	framexml
+MerchantItem6MoneyFrameGoldButton	table	framexml
+MerchantItem6MoneyFrameGoldButtonText	table	framexml
+MerchantItem6MoneyFrameSilverButton	table	framexml
+MerchantItem6MoneyFrameSilverButtonText	table	framexml
+MerchantItem6Name	table	framexml
+MerchantItem6NameFrame	table	framexml
+MerchantItem6SlotTexture	table	framexml
+MerchantItem7	table	framexml
+MerchantItem7ItemButton	table	framexml
+MerchantItem7ItemButtonCount	table	framexml
+MerchantItem7ItemButtonIconTexture	table	framexml
+MerchantItem7ItemButtonNormalTexture	table	framexml
+MerchantItem7ItemButtonStock	table	framexml
+MerchantItem7MoneyFrame	table	framexml
+MerchantItem7MoneyFrameCopperButton	table	framexml
+MerchantItem7MoneyFrameCopperButtonText	table	framexml
+MerchantItem7MoneyFrameGoldButton	table	framexml
+MerchantItem7MoneyFrameGoldButtonText	table	framexml
+MerchantItem7MoneyFrameSilverButton	table	framexml
+MerchantItem7MoneyFrameSilverButtonText	table	framexml
+MerchantItem7Name	table	framexml
+MerchantItem7NameFrame	table	framexml
+MerchantItem7SlotTexture	table	framexml
+MerchantItem8	table	framexml
+MerchantItem8ItemButton	table	framexml
+MerchantItem8ItemButtonCount	table	framexml
+MerchantItem8ItemButtonIconTexture	table	framexml
+MerchantItem8ItemButtonNormalTexture	table	framexml
+MerchantItem8ItemButtonStock	table	framexml
+MerchantItem8MoneyFrame	table	framexml
+MerchantItem8MoneyFrameCopperButton	table	framexml
+MerchantItem8MoneyFrameCopperButtonText	table	framexml
+MerchantItem8MoneyFrameGoldButton	table	framexml
+MerchantItem8MoneyFrameGoldButtonText	table	framexml
+MerchantItem8MoneyFrameSilverButton	table	framexml
+MerchantItem8MoneyFrameSilverButtonText	table	framexml
+MerchantItem8Name	table	framexml
+MerchantItem8NameFrame	table	framexml
+MerchantItem8SlotTexture	table	framexml
+MerchantItem9	table	framexml
+MerchantItem9ItemButton	table	framexml
+MerchantItem9ItemButtonCount	table	framexml
+MerchantItem9ItemButtonIconTexture	table	framexml
+MerchantItem9ItemButtonNormalTexture	table	framexml
+MerchantItem9ItemButtonStock	table	framexml
+MerchantItem9MoneyFrame	table	framexml
+MerchantItem9MoneyFrameCopperButton	table	framexml
+MerchantItem9MoneyFrameCopperButtonText	table	framexml
+MerchantItem9MoneyFrameGoldButton	table	framexml
+MerchantItem9MoneyFrameGoldButtonText	table	framexml
+MerchantItem9MoneyFrameSilverButton	table	framexml
+MerchantItem9MoneyFrameSilverButtonText	table	framexml
+MerchantItem9Name	table	framexml
+MerchantItem9NameFrame	table	framexml
+MerchantItem9SlotTexture	table	framexml
+MerchantItemButton_OnClick	function	framexml
+MerchantItemButton_OnLoad	function	framexml
+MerchantItemTemplate	lod	framexml
+MerchantMoneyFrame	table	framexml
+MerchantMoneyFrameCopperButton	table	framexml
+MerchantMoneyFrameCopperButtonText	table	framexml
+MerchantMoneyFrameGoldButton	table	framexml
+MerchantMoneyFrameGoldButtonText	table	framexml
+MerchantMoneyFrameSilverButton	table	framexml
+MerchantMoneyFrameSilverButtonText	table	framexml
+MerchantNameText	table	framexml
+MerchantNextPageButton	table	framexml
+MerchantNextPageButton_OnClick	function	framexml
+MerchantPageText	table	framexml
+MerchantPrevPageButton	table	framexml
+MerchantPrevPageButton_OnClick	function	framexml
+MerchantRepairAllButton	table	framexml
+MerchantRepairAllIcon	table	framexml
+MerchantRepairItemButton	table	framexml
+MerchantRepairText	table	framexml
+MessageFrameScrollButton_OnLoad	function	framexml
+MessageFrameScrollButton_OnUpdate	function	framexml
+MicroButtonPortrait	table	framexml
+MicroButtonTooltipText	function	framexml
+MiniMapBattlefieldBorder	table	framexml
+MiniMapBattlefieldDropDown	table	framexml
+MiniMapBattlefieldDropDownButton	table	framexml
+MiniMapBattlefieldDropDownButtonDisabledTexture	table	framexml
+MiniMapBattlefieldDropDownButtonHighlightTexture	table	framexml
+MiniMapBattlefieldDropDownButtonNormalTexture	table	framexml
+MiniMapBattlefieldDropDownButtonPushedTexture	table	framexml
+MiniMapBattlefieldDropDownLeft	table	framexml
+MiniMapBattlefieldDropDownMiddle	table	framexml
+MiniMapBattlefieldDropDownRight	table	framexml
+MiniMapBattlefieldDropDownText	table	framexml
+MiniMapBattlefieldDropDown_Initialize	function	framexml
+MiniMapBattlefieldDropDown_OnLoad	function	framexml
+MiniMapBattlefieldFrame	table	framexml
+MiniMapBattlefieldIcon	table	framexml
+MiniMapMailBorder	table	framexml
+MiniMapMailFrame	table	framexml
+MiniMapMailIcon	table	framexml
+MiniMapMeetingStoneBorder	table	framexml
+MiniMapMeetingStoneFrame	table	framexml
+MiniMapMeetingStoneIcon	table	framexml
+MiniMapPing	table	framexml
+MiniMapPing_FadeOut	function	framexml
+MiniMapTrackingBorder	table	framexml
+MiniMapTrackingFrame	table	framexml
+MiniMapTrackingIcon	table	framexml
+Minimap	table	framexml
+MinimapBackdrop	table	framexml
+MinimapBorder	table	framexml
+MinimapBorderTop	table	framexml
+MinimapCluster	table	framexml
+MinimapToggleButton	table	framexml
+MinimapZoneText	table	framexml
+MinimapZoneTextButton	table	framexml
+MinimapZoomIn	table	framexml
+MinimapZoomOut	table	framexml
+Minimap_OnClick	function	framexml
+Minimap_OnEvent	function	framexml
+Minimap_OnLoad	function	framexml
+Minimap_OnUpdate	function	framexml
+Minimap_SetPing	function	framexml
+Minimap_Update	function	framexml
+Minimap_ZoomIn	function	framexml
+Minimap_ZoomInClick	function	framexml
+Minimap_ZoomOut	function	framexml
+Minimap_ZoomOutClick	function	framexml
+MirrorTimer1	table	framexml
+MirrorTimer1Border	table	framexml
+MirrorTimer1StatusBar	table	framexml
+MirrorTimer1Text	table	framexml
+MirrorTimer2	table	framexml
+MirrorTimer2Border	table	framexml
+MirrorTimer2StatusBar	table	framexml
+MirrorTimer2Text	table	framexml
+MirrorTimer3	table	framexml
+MirrorTimer3Border	table	framexml
+MirrorTimer3StatusBar	table	framexml
+MirrorTimer3Text	table	framexml
+MirrorTimerColors	table	framexml
+MirrorTimerFrame_OnEvent	function	framexml
+MirrorTimerFrame_OnLoad	function	framexml
+MirrorTimerFrame_OnUpdate	function	framexml
+MirrorTimerTemplate	lod	framexml
+MirrorTimer_Show	function	framexml
+Model_OnLoad	function	framexml
+Model_OnUpdate	function	framexml
+Model_RotateLeft	function	framexml
+Model_RotateRight	function	framexml
+MoneyFrameTemplate	lod	framexml
+MoneyFrame_OnEvent	function	framexml
+MoneyFrame_OnLoad	function	framexml
+MoneyFrame_SetType	function	framexml
+MoneyFrame_Update	function	framexml
+MoneyFrame_UpdateMoney	function	framexml
+MoneyInputFrameTemplate	lod	framexml
+MoneyInputFrame_ClearFocus	function	framexml
+MoneyInputFrame_GetCopper	function	framexml
+MoneyInputFrame_OnTextChanged	function	framexml
+MoneyInputFrame_ResetMoney	function	framexml
+MoneyInputFrame_SetCopper	function	framexml
+MoneyInputFrame_SetMode	function	framexml
+MoneyInputFrame_SetNextFocus	function	framexml
+MoneyInputFrame_SetOnvalueChangedFunc	function	framexml
+MoneyInputFrame_SetPreviousFocus	function	framexml
+MoneyInputFrame_SetTextColor	function	framexml
+MoneyTypeInfo	table	framexml
+MouseIsOver	function	framexml
+MouselookStart	function	engine
+MouselookStop	function	engine
+MoveBackwardStart	function	engine
+MoveBackwardStop	function	engine
+MoveForwardStart	function	engine
+MoveForwardStop	function	engine
+MovePanelToCenter	function	framexml
+MovePanelToLeft	function	framexml
+MoveViewDownStart	function	engine
+MoveViewDownStop	function	engine
+MoveViewInStart	function	engine
+MoveViewInStop	function	engine
+MoveViewLeftStart	function	engine
+MoveViewLeftStop	function	engine
+MoveViewOutStart	function	engine
+MoveViewOutStop	function	engine
+MoveViewRightStart	function	engine
+MoveViewRightStop	function	engine
+MoveViewUpStart	function	engine
+MoveViewUpStop	function	engine
+MultiActionBarFrame_OnLoad	function	framexml
+MultiActionBar_HideAllGrids	function	framexml
+MultiActionBar_ShowAllGrids	function	framexml
+MultiActionBar_Update	function	framexml
+MultiActionBar_UpdateGrid	function	framexml
+MultiActionBar_UpdateGridVisibility	function	framexml
+MultiActionButtonDown	function	framexml
+MultiActionButtonUp	function	framexml
+MultiBar1ButtonTemplate	lod	framexml
+MultiBar1_IsVisible	function	framexml
+MultiBar2ButtonTemplate	lod	framexml
+MultiBar2_IsVisible	function	framexml
+MultiBar3ButtonTemplate	lod	framexml
+MultiBar3_IsVisible	function	framexml
+MultiBar4ButtonTemplate	lod	framexml
+MultiBar4_IsVisible	function	framexml
+MultiBarBottomLeft	table	framexml
+MultiBarBottomLeftButton1	table	framexml
+MultiBarBottomLeftButton10	table	framexml
+MultiBarBottomLeftButton10Border	table	framexml
+MultiBarBottomLeftButton10Cooldown	table	framexml
+MultiBarBottomLeftButton10Count	table	framexml
+MultiBarBottomLeftButton10Flash	table	framexml
+MultiBarBottomLeftButton10HotKey	table	framexml
+MultiBarBottomLeftButton10Icon	table	framexml
+MultiBarBottomLeftButton10Name	table	framexml
+MultiBarBottomLeftButton10NormalTexture	table	framexml
+MultiBarBottomLeftButton11	table	framexml
+MultiBarBottomLeftButton11Border	table	framexml
+MultiBarBottomLeftButton11Cooldown	table	framexml
+MultiBarBottomLeftButton11Count	table	framexml
+MultiBarBottomLeftButton11Flash	table	framexml
+MultiBarBottomLeftButton11HotKey	table	framexml
+MultiBarBottomLeftButton11Icon	table	framexml
+MultiBarBottomLeftButton11Name	table	framexml
+MultiBarBottomLeftButton11NormalTexture	table	framexml
+MultiBarBottomLeftButton12	table	framexml
+MultiBarBottomLeftButton12Border	table	framexml
+MultiBarBottomLeftButton12Cooldown	table	framexml
+MultiBarBottomLeftButton12Count	table	framexml
+MultiBarBottomLeftButton12Flash	table	framexml
+MultiBarBottomLeftButton12HotKey	table	framexml
+MultiBarBottomLeftButton12Icon	table	framexml
+MultiBarBottomLeftButton12Name	table	framexml
+MultiBarBottomLeftButton12NormalTexture	table	framexml
+MultiBarBottomLeftButton1Border	table	framexml
+MultiBarBottomLeftButton1Cooldown	table	framexml
+MultiBarBottomLeftButton1Count	table	framexml
+MultiBarBottomLeftButton1Flash	table	framexml
+MultiBarBottomLeftButton1HotKey	table	framexml
+MultiBarBottomLeftButton1Icon	table	framexml
+MultiBarBottomLeftButton1Name	table	framexml
+MultiBarBottomLeftButton1NormalTexture	table	framexml
+MultiBarBottomLeftButton2	table	framexml
+MultiBarBottomLeftButton2Border	table	framexml
+MultiBarBottomLeftButton2Cooldown	table	framexml
+MultiBarBottomLeftButton2Count	table	framexml
+MultiBarBottomLeftButton2Flash	table	framexml
+MultiBarBottomLeftButton2HotKey	table	framexml
+MultiBarBottomLeftButton2Icon	table	framexml
+MultiBarBottomLeftButton2Name	table	framexml
+MultiBarBottomLeftButton2NormalTexture	table	framexml
+MultiBarBottomLeftButton3	table	framexml
+MultiBarBottomLeftButton3Border	table	framexml
+MultiBarBottomLeftButton3Cooldown	table	framexml
+MultiBarBottomLeftButton3Count	table	framexml
+MultiBarBottomLeftButton3Flash	table	framexml
+MultiBarBottomLeftButton3HotKey	table	framexml
+MultiBarBottomLeftButton3Icon	table	framexml
+MultiBarBottomLeftButton3Name	table	framexml
+MultiBarBottomLeftButton3NormalTexture	table	framexml
+MultiBarBottomLeftButton4	table	framexml
+MultiBarBottomLeftButton4Border	table	framexml
+MultiBarBottomLeftButton4Cooldown	table	framexml
+MultiBarBottomLeftButton4Count	table	framexml
+MultiBarBottomLeftButton4Flash	table	framexml
+MultiBarBottomLeftButton4HotKey	table	framexml
+MultiBarBottomLeftButton4Icon	table	framexml
+MultiBarBottomLeftButton4Name	table	framexml
+MultiBarBottomLeftButton4NormalTexture	table	framexml
+MultiBarBottomLeftButton5	table	framexml
+MultiBarBottomLeftButton5Border	table	framexml
+MultiBarBottomLeftButton5Cooldown	table	framexml
+MultiBarBottomLeftButton5Count	table	framexml
+MultiBarBottomLeftButton5Flash	table	framexml
+MultiBarBottomLeftButton5HotKey	table	framexml
+MultiBarBottomLeftButton5Icon	table	framexml
+MultiBarBottomLeftButton5Name	table	framexml
+MultiBarBottomLeftButton5NormalTexture	table	framexml
+MultiBarBottomLeftButton6	table	framexml
+MultiBarBottomLeftButton6Border	table	framexml
+MultiBarBottomLeftButton6Cooldown	table	framexml
+MultiBarBottomLeftButton6Count	table	framexml
+MultiBarBottomLeftButton6Flash	table	framexml
+MultiBarBottomLeftButton6HotKey	table	framexml
+MultiBarBottomLeftButton6Icon	table	framexml
+MultiBarBottomLeftButton6Name	table	framexml
+MultiBarBottomLeftButton6NormalTexture	table	framexml
+MultiBarBottomLeftButton7	table	framexml
+MultiBarBottomLeftButton7Border	table	framexml
+MultiBarBottomLeftButton7Cooldown	table	framexml
+MultiBarBottomLeftButton7Count	table	framexml
+MultiBarBottomLeftButton7Flash	table	framexml
+MultiBarBottomLeftButton7HotKey	table	framexml
+MultiBarBottomLeftButton7Icon	table	framexml
+MultiBarBottomLeftButton7Name	table	framexml
+MultiBarBottomLeftButton7NormalTexture	table	framexml
+MultiBarBottomLeftButton8	table	framexml
+MultiBarBottomLeftButton8Border	table	framexml
+MultiBarBottomLeftButton8Cooldown	table	framexml
+MultiBarBottomLeftButton8Count	table	framexml
+MultiBarBottomLeftButton8Flash	table	framexml
+MultiBarBottomLeftButton8HotKey	table	framexml
+MultiBarBottomLeftButton8Icon	table	framexml
+MultiBarBottomLeftButton8Name	table	framexml
+MultiBarBottomLeftButton8NormalTexture	table	framexml
+MultiBarBottomLeftButton9	table	framexml
+MultiBarBottomLeftButton9Border	table	framexml
+MultiBarBottomLeftButton9Cooldown	table	framexml
+MultiBarBottomLeftButton9Count	table	framexml
+MultiBarBottomLeftButton9Flash	table	framexml
+MultiBarBottomLeftButton9HotKey	table	framexml
+MultiBarBottomLeftButton9Icon	table	framexml
+MultiBarBottomLeftButton9Name	table	framexml
+MultiBarBottomLeftButton9NormalTexture	table	framexml
+MultiBarBottomRight	table	framexml
+MultiBarBottomRightButton1	table	framexml
+MultiBarBottomRightButton10	table	framexml
+MultiBarBottomRightButton10Border	table	framexml
+MultiBarBottomRightButton10Cooldown	table	framexml
+MultiBarBottomRightButton10Count	table	framexml
+MultiBarBottomRightButton10Flash	table	framexml
+MultiBarBottomRightButton10HotKey	table	framexml
+MultiBarBottomRightButton10Icon	table	framexml
+MultiBarBottomRightButton10Name	table	framexml
+MultiBarBottomRightButton10NormalTexture	table	framexml
+MultiBarBottomRightButton11	table	framexml
+MultiBarBottomRightButton11Border	table	framexml
+MultiBarBottomRightButton11Cooldown	table	framexml
+MultiBarBottomRightButton11Count	table	framexml
+MultiBarBottomRightButton11Flash	table	framexml
+MultiBarBottomRightButton11HotKey	table	framexml
+MultiBarBottomRightButton11Icon	table	framexml
+MultiBarBottomRightButton11Name	table	framexml
+MultiBarBottomRightButton11NormalTexture	table	framexml
+MultiBarBottomRightButton12	table	framexml
+MultiBarBottomRightButton12Border	table	framexml
+MultiBarBottomRightButton12Cooldown	table	framexml
+MultiBarBottomRightButton12Count	table	framexml
+MultiBarBottomRightButton12Flash	table	framexml
+MultiBarBottomRightButton12HotKey	table	framexml
+MultiBarBottomRightButton12Icon	table	framexml
+MultiBarBottomRightButton12Name	table	framexml
+MultiBarBottomRightButton12NormalTexture	table	framexml
+MultiBarBottomRightButton1Border	table	framexml
+MultiBarBottomRightButton1Cooldown	table	framexml
+MultiBarBottomRightButton1Count	table	framexml
+MultiBarBottomRightButton1Flash	table	framexml
+MultiBarBottomRightButton1HotKey	table	framexml
+MultiBarBottomRightButton1Icon	table	framexml
+MultiBarBottomRightButton1Name	table	framexml
+MultiBarBottomRightButton1NormalTexture	table	framexml
+MultiBarBottomRightButton2	table	framexml
+MultiBarBottomRightButton2Border	table	framexml
+MultiBarBottomRightButton2Cooldown	table	framexml
+MultiBarBottomRightButton2Count	table	framexml
+MultiBarBottomRightButton2Flash	table	framexml
+MultiBarBottomRightButton2HotKey	table	framexml
+MultiBarBottomRightButton2Icon	table	framexml
+MultiBarBottomRightButton2Name	table	framexml
+MultiBarBottomRightButton2NormalTexture	table	framexml
+MultiBarBottomRightButton3	table	framexml
+MultiBarBottomRightButton3Border	table	framexml
+MultiBarBottomRightButton3Cooldown	table	framexml
+MultiBarBottomRightButton3Count	table	framexml
+MultiBarBottomRightButton3Flash	table	framexml
+MultiBarBottomRightButton3HotKey	table	framexml
+MultiBarBottomRightButton3Icon	table	framexml
+MultiBarBottomRightButton3Name	table	framexml
+MultiBarBottomRightButton3NormalTexture	table	framexml
+MultiBarBottomRightButton4	table	framexml
+MultiBarBottomRightButton4Border	table	framexml
+MultiBarBottomRightButton4Cooldown	table	framexml
+MultiBarBottomRightButton4Count	table	framexml
+MultiBarBottomRightButton4Flash	table	framexml
+MultiBarBottomRightButton4HotKey	table	framexml
+MultiBarBottomRightButton4Icon	table	framexml
+MultiBarBottomRightButton4Name	table	framexml
+MultiBarBottomRightButton4NormalTexture	table	framexml
+MultiBarBottomRightButton5	table	framexml
+MultiBarBottomRightButton5Border	table	framexml
+MultiBarBottomRightButton5Cooldown	table	framexml
+MultiBarBottomRightButton5Count	table	framexml
+MultiBarBottomRightButton5Flash	table	framexml
+MultiBarBottomRightButton5HotKey	table	framexml
+MultiBarBottomRightButton5Icon	table	framexml
+MultiBarBottomRightButton5Name	table	framexml
+MultiBarBottomRightButton5NormalTexture	table	framexml
+MultiBarBottomRightButton6	table	framexml
+MultiBarBottomRightButton6Border	table	framexml
+MultiBarBottomRightButton6Cooldown	table	framexml
+MultiBarBottomRightButton6Count	table	framexml
+MultiBarBottomRightButton6Flash	table	framexml
+MultiBarBottomRightButton6HotKey	table	framexml
+MultiBarBottomRightButton6Icon	table	framexml
+MultiBarBottomRightButton6Name	table	framexml
+MultiBarBottomRightButton6NormalTexture	table	framexml
+MultiBarBottomRightButton7	table	framexml
+MultiBarBottomRightButton7Border	table	framexml
+MultiBarBottomRightButton7Cooldown	table	framexml
+MultiBarBottomRightButton7Count	table	framexml
+MultiBarBottomRightButton7Flash	table	framexml
+MultiBarBottomRightButton7HotKey	table	framexml
+MultiBarBottomRightButton7Icon	table	framexml
+MultiBarBottomRightButton7Name	table	framexml
+MultiBarBottomRightButton7NormalTexture	table	framexml
+MultiBarBottomRightButton8	table	framexml
+MultiBarBottomRightButton8Border	table	framexml
+MultiBarBottomRightButton8Cooldown	table	framexml
+MultiBarBottomRightButton8Count	table	framexml
+MultiBarBottomRightButton8Flash	table	framexml
+MultiBarBottomRightButton8HotKey	table	framexml
+MultiBarBottomRightButton8Icon	table	framexml
+MultiBarBottomRightButton8Name	table	framexml
+MultiBarBottomRightButton8NormalTexture	table	framexml
+MultiBarBottomRightButton9	table	framexml
+MultiBarBottomRightButton9Border	table	framexml
+MultiBarBottomRightButton9Cooldown	table	framexml
+MultiBarBottomRightButton9Count	table	framexml
+MultiBarBottomRightButton9Flash	table	framexml
+MultiBarBottomRightButton9HotKey	table	framexml
+MultiBarBottomRightButton9Icon	table	framexml
+MultiBarBottomRightButton9Name	table	framexml
+MultiBarBottomRightButton9NormalTexture	table	framexml
+MultiBarLeft	table	framexml
+MultiBarLeftButton1	table	framexml
+MultiBarLeftButton10	table	framexml
+MultiBarLeftButton10Border	table	framexml
+MultiBarLeftButton10Cooldown	table	framexml
+MultiBarLeftButton10Count	table	framexml
+MultiBarLeftButton10Flash	table	framexml
+MultiBarLeftButton10HotKey	table	framexml
+MultiBarLeftButton10Icon	table	framexml
+MultiBarLeftButton10Name	table	framexml
+MultiBarLeftButton10NormalTexture	table	framexml
+MultiBarLeftButton11	table	framexml
+MultiBarLeftButton11Border	table	framexml
+MultiBarLeftButton11Cooldown	table	framexml
+MultiBarLeftButton11Count	table	framexml
+MultiBarLeftButton11Flash	table	framexml
+MultiBarLeftButton11HotKey	table	framexml
+MultiBarLeftButton11Icon	table	framexml
+MultiBarLeftButton11Name	table	framexml
+MultiBarLeftButton11NormalTexture	table	framexml
+MultiBarLeftButton12	table	framexml
+MultiBarLeftButton12Border	table	framexml
+MultiBarLeftButton12Cooldown	table	framexml
+MultiBarLeftButton12Count	table	framexml
+MultiBarLeftButton12Flash	table	framexml
+MultiBarLeftButton12HotKey	table	framexml
+MultiBarLeftButton12Icon	table	framexml
+MultiBarLeftButton12Name	table	framexml
+MultiBarLeftButton12NormalTexture	table	framexml
+MultiBarLeftButton1Border	table	framexml
+MultiBarLeftButton1Cooldown	table	framexml
+MultiBarLeftButton1Count	table	framexml
+MultiBarLeftButton1Flash	table	framexml
+MultiBarLeftButton1HotKey	table	framexml
+MultiBarLeftButton1Icon	table	framexml
+MultiBarLeftButton1Name	table	framexml
+MultiBarLeftButton1NormalTexture	table	framexml
+MultiBarLeftButton2	table	framexml
+MultiBarLeftButton2Border	table	framexml
+MultiBarLeftButton2Cooldown	table	framexml
+MultiBarLeftButton2Count	table	framexml
+MultiBarLeftButton2Flash	table	framexml
+MultiBarLeftButton2HotKey	table	framexml
+MultiBarLeftButton2Icon	table	framexml
+MultiBarLeftButton2Name	table	framexml
+MultiBarLeftButton2NormalTexture	table	framexml
+MultiBarLeftButton3	table	framexml
+MultiBarLeftButton3Border	table	framexml
+MultiBarLeftButton3Cooldown	table	framexml
+MultiBarLeftButton3Count	table	framexml
+MultiBarLeftButton3Flash	table	framexml
+MultiBarLeftButton3HotKey	table	framexml
+MultiBarLeftButton3Icon	table	framexml
+MultiBarLeftButton3Name	table	framexml
+MultiBarLeftButton3NormalTexture	table	framexml
+MultiBarLeftButton4	table	framexml
+MultiBarLeftButton4Border	table	framexml
+MultiBarLeftButton4Cooldown	table	framexml
+MultiBarLeftButton4Count	table	framexml
+MultiBarLeftButton4Flash	table	framexml
+MultiBarLeftButton4HotKey	table	framexml
+MultiBarLeftButton4Icon	table	framexml
+MultiBarLeftButton4Name	table	framexml
+MultiBarLeftButton4NormalTexture	table	framexml
+MultiBarLeftButton5	table	framexml
+MultiBarLeftButton5Border	table	framexml
+MultiBarLeftButton5Cooldown	table	framexml
+MultiBarLeftButton5Count	table	framexml
+MultiBarLeftButton5Flash	table	framexml
+MultiBarLeftButton5HotKey	table	framexml
+MultiBarLeftButton5Icon	table	framexml
+MultiBarLeftButton5Name	table	framexml
+MultiBarLeftButton5NormalTexture	table	framexml
+MultiBarLeftButton6	table	framexml
+MultiBarLeftButton6Border	table	framexml
+MultiBarLeftButton6Cooldown	table	framexml
+MultiBarLeftButton6Count	table	framexml
+MultiBarLeftButton6Flash	table	framexml
+MultiBarLeftButton6HotKey	table	framexml
+MultiBarLeftButton6Icon	table	framexml
+MultiBarLeftButton6Name	table	framexml
+MultiBarLeftButton6NormalTexture	table	framexml
+MultiBarLeftButton7	table	framexml
+MultiBarLeftButton7Border	table	framexml
+MultiBarLeftButton7Cooldown	table	framexml
+MultiBarLeftButton7Count	table	framexml
+MultiBarLeftButton7Flash	table	framexml
+MultiBarLeftButton7HotKey	table	framexml
+MultiBarLeftButton7Icon	table	framexml
+MultiBarLeftButton7Name	table	framexml
+MultiBarLeftButton7NormalTexture	table	framexml
+MultiBarLeftButton8	table	framexml
+MultiBarLeftButton8Border	table	framexml
+MultiBarLeftButton8Cooldown	table	framexml
+MultiBarLeftButton8Count	table	framexml
+MultiBarLeftButton8Flash	table	framexml
+MultiBarLeftButton8HotKey	table	framexml
+MultiBarLeftButton8Icon	table	framexml
+MultiBarLeftButton8Name	table	framexml
+MultiBarLeftButton8NormalTexture	table	framexml
+MultiBarLeftButton9	table	framexml
+MultiBarLeftButton9Border	table	framexml
+MultiBarLeftButton9Cooldown	table	framexml
+MultiBarLeftButton9Count	table	framexml
+MultiBarLeftButton9Flash	table	framexml
+MultiBarLeftButton9HotKey	table	framexml
+MultiBarLeftButton9Icon	table	framexml
+MultiBarLeftButton9Name	table	framexml
+MultiBarLeftButton9NormalTexture	table	framexml
+MultiBarRight	table	framexml
+MultiBarRightButton1	table	framexml
+MultiBarRightButton10	table	framexml
+MultiBarRightButton10Border	table	framexml
+MultiBarRightButton10Cooldown	table	framexml
+MultiBarRightButton10Count	table	framexml
+MultiBarRightButton10Flash	table	framexml
+MultiBarRightButton10HotKey	table	framexml
+MultiBarRightButton10Icon	table	framexml
+MultiBarRightButton10Name	table	framexml
+MultiBarRightButton10NormalTexture	table	framexml
+MultiBarRightButton11	table	framexml
+MultiBarRightButton11Border	table	framexml
+MultiBarRightButton11Cooldown	table	framexml
+MultiBarRightButton11Count	table	framexml
+MultiBarRightButton11Flash	table	framexml
+MultiBarRightButton11HotKey	table	framexml
+MultiBarRightButton11Icon	table	framexml
+MultiBarRightButton11Name	table	framexml
+MultiBarRightButton11NormalTexture	table	framexml
+MultiBarRightButton12	table	framexml
+MultiBarRightButton12Border	table	framexml
+MultiBarRightButton12Cooldown	table	framexml
+MultiBarRightButton12Count	table	framexml
+MultiBarRightButton12Flash	table	framexml
+MultiBarRightButton12HotKey	table	framexml
+MultiBarRightButton12Icon	table	framexml
+MultiBarRightButton12Name	table	framexml
+MultiBarRightButton12NormalTexture	table	framexml
+MultiBarRightButton1Border	table	framexml
+MultiBarRightButton1Cooldown	table	framexml
+MultiBarRightButton1Count	table	framexml
+MultiBarRightButton1Flash	table	framexml
+MultiBarRightButton1HotKey	table	framexml
+MultiBarRightButton1Icon	table	framexml
+MultiBarRightButton1Name	table	framexml
+MultiBarRightButton1NormalTexture	table	framexml
+MultiBarRightButton2	table	framexml
+MultiBarRightButton2Border	table	framexml
+MultiBarRightButton2Cooldown	table	framexml
+MultiBarRightButton2Count	table	framexml
+MultiBarRightButton2Flash	table	framexml
+MultiBarRightButton2HotKey	table	framexml
+MultiBarRightButton2Icon	table	framexml
+MultiBarRightButton2Name	table	framexml
+MultiBarRightButton2NormalTexture	table	framexml
+MultiBarRightButton3	table	framexml
+MultiBarRightButton3Border	table	framexml
+MultiBarRightButton3Cooldown	table	framexml
+MultiBarRightButton3Count	table	framexml
+MultiBarRightButton3Flash	table	framexml
+MultiBarRightButton3HotKey	table	framexml
+MultiBarRightButton3Icon	table	framexml
+MultiBarRightButton3Name	table	framexml
+MultiBarRightButton3NormalTexture	table	framexml
+MultiBarRightButton4	table	framexml
+MultiBarRightButton4Border	table	framexml
+MultiBarRightButton4Cooldown	table	framexml
+MultiBarRightButton4Count	table	framexml
+MultiBarRightButton4Flash	table	framexml
+MultiBarRightButton4HotKey	table	framexml
+MultiBarRightButton4Icon	table	framexml
+MultiBarRightButton4Name	table	framexml
+MultiBarRightButton4NormalTexture	table	framexml
+MultiBarRightButton5	table	framexml
+MultiBarRightButton5Border	table	framexml
+MultiBarRightButton5Cooldown	table	framexml
+MultiBarRightButton5Count	table	framexml
+MultiBarRightButton5Flash	table	framexml
+MultiBarRightButton5HotKey	table	framexml
+MultiBarRightButton5Icon	table	framexml
+MultiBarRightButton5Name	table	framexml
+MultiBarRightButton5NormalTexture	table	framexml
+MultiBarRightButton6	table	framexml
+MultiBarRightButton6Border	table	framexml
+MultiBarRightButton6Cooldown	table	framexml
+MultiBarRightButton6Count	table	framexml
+MultiBarRightButton6Flash	table	framexml
+MultiBarRightButton6HotKey	table	framexml
+MultiBarRightButton6Icon	table	framexml
+MultiBarRightButton6Name	table	framexml
+MultiBarRightButton6NormalTexture	table	framexml
+MultiBarRightButton7	table	framexml
+MultiBarRightButton7Border	table	framexml
+MultiBarRightButton7Cooldown	table	framexml
+MultiBarRightButton7Count	table	framexml
+MultiBarRightButton7Flash	table	framexml
+MultiBarRightButton7HotKey	table	framexml
+MultiBarRightButton7Icon	table	framexml
+MultiBarRightButton7Name	table	framexml
+MultiBarRightButton7NormalTexture	table	framexml
+MultiBarRightButton8	table	framexml
+MultiBarRightButton8Border	table	framexml
+MultiBarRightButton8Cooldown	table	framexml
+MultiBarRightButton8Count	table	framexml
+MultiBarRightButton8Flash	table	framexml
+MultiBarRightButton8HotKey	table	framexml
+MultiBarRightButton8Icon	table	framexml
+MultiBarRightButton8Name	table	framexml
+MultiBarRightButton8NormalTexture	table	framexml
+MultiBarRightButton9	table	framexml
+MultiBarRightButton9Border	table	framexml
+MultiBarRightButton9Cooldown	table	framexml
+MultiBarRightButton9Count	table	framexml
+MultiBarRightButton9Flash	table	framexml
+MultiBarRightButton9HotKey	table	framexml
+MultiBarRightButton9Icon	table	framexml
+MultiBarRightButton9Name	table	framexml
+MultiBarRightButton9NormalTexture	table	framexml
+MultibarGrid_IsVisible	function	framexml
+Multibar_EmptyFunc	function	framexml
+NAME	string	framexml
+NAMEPLATES_ON	lod	framexml
+NAMEPLATE_FONT	string	framexml
+NAME_CHAT_WINDOW	string	framexml
+NECKSLOT	string	framexml
+NEED	string	framexml
+NEW	string	framexml
+NEWBIE_TOOLTIP_ABANDONQUEST	string	framexml
+NEWBIE_TOOLTIP_ADDFRIEND	string	framexml
+NEWBIE_TOOLTIP_ADDMEMBER	string	framexml
+NEWBIE_TOOLTIP_ALLIANCE	string	framexml
+NEWBIE_TOOLTIP_BATTLEFIELDMINIMAP_OPTIONS	string	framexml
+NEWBIE_TOOLTIP_BATTLEFIELD_GROUP_JOIN	string	framexml
+NEWBIE_TOOLTIP_CHARACTER	string	framexml
+NEWBIE_TOOLTIP_CHATMENU	string	framexml
+NEWBIE_TOOLTIP_CHATOPTIONS	string	framexml
+NEWBIE_TOOLTIP_DEMOTE	string	framexml
+NEWBIE_TOOLTIP_DISHONORABLE_KILLS	string	framexml
+NEWBIE_TOOLTIP_ENCHANTSLOT	string	framexml
+NEWBIE_TOOLTIP_ENTER_BATTLEGROUND	string	framexml
+NEWBIE_TOOLTIP_FIRST_AVAILABLE	string	framexml
+NEWBIE_TOOLTIP_FRIENDSTAB	string	framexml
+NEWBIE_TOOLTIP_GROUPINVITE	string	framexml
+NEWBIE_TOOLTIP_GUILDCONTROL	string	framexml
+NEWBIE_TOOLTIP_GUILDGROUPINVITE	string	framexml
+NEWBIE_TOOLTIP_GUILDPUBLICNOTE	string	framexml
+NEWBIE_TOOLTIP_GUILDREMOVE	string	framexml
+NEWBIE_TOOLTIP_GUILDTAB	string	framexml
+NEWBIE_TOOLTIP_GUILD_MEMBER_OPTIONS	string	framexml
+NEWBIE_TOOLTIP_HEALTHBAR	string	framexml
+NEWBIE_TOOLTIP_HELP	string	framexml
+NEWBIE_TOOLTIP_HONORABLE_KILLS	string	framexml
+NEWBIE_TOOLTIP_HONOR_CONTRIBUTION_POINTS	string	framexml
+NEWBIE_TOOLTIP_HONOR_STANDING	string	framexml
+NEWBIE_TOOLTIP_HORDE	string	framexml
+NEWBIE_TOOLTIP_IGNOREPLAYER	string	framexml
+NEWBIE_TOOLTIP_IGNORETAB	string	framexml
+NEWBIE_TOOLTIP_LATENCY	string	framexml
+NEWBIE_TOOLTIP_MAINMENU	string	framexml
+NEWBIE_TOOLTIP_MANABAR0	string	framexml
+NEWBIE_TOOLTIP_MANABAR1	string	framexml
+NEWBIE_TOOLTIP_MANABAR2	string	framexml
+NEWBIE_TOOLTIP_MANABAR3	string	framexml
+NEWBIE_TOOLTIP_MANABAR4	string	framexml
+NEWBIE_TOOLTIP_MINIMAPTOGGLE	string	framexml
+NEWBIE_TOOLTIP_PARTYOPTIONS	string	framexml
+NEWBIE_TOOLTIP_PLAYEROPTIONS	string	framexml
+NEWBIE_TOOLTIP_PROMOTE	string	framexml
+NEWBIE_TOOLTIP_PVPFFA	string	framexml
+NEWBIE_TOOLTIP_QUESTLOG	string	framexml
+NEWBIE_TOOLTIP_RAIDTAB	string	framexml
+NEWBIE_TOOLTIP_RANK	string	framexml
+NEWBIE_TOOLTIP_RANK_POSITION	string	framexml
+NEWBIE_TOOLTIP_REMOVEFRIEND	string	framexml
+NEWBIE_TOOLTIP_SENDMESSAGE	string	framexml
+NEWBIE_TOOLTIP_SHAREQUEST	string	framexml
+NEWBIE_TOOLTIP_SOCIAL	string	framexml
+NEWBIE_TOOLTIP_SPELLBOOK	string	framexml
+NEWBIE_TOOLTIP_STOPIGNORE	string	framexml
+NEWBIE_TOOLTIP_TALENTS	string	framexml
+NEWBIE_TOOLTIP_UNIT_DUEL	string	framexml
+NEWBIE_TOOLTIP_UNIT_FOLLOW	string	framexml
+NEWBIE_TOOLTIP_UNIT_FREE_FOR_ALL	string	framexml
+NEWBIE_TOOLTIP_UNIT_GROUP_LOOT	string	framexml
+NEWBIE_TOOLTIP_UNIT_INSPECT	string	framexml
+NEWBIE_TOOLTIP_UNIT_INVITE	string	framexml
+NEWBIE_TOOLTIP_UNIT_LEAVE_PARTY	string	framexml
+NEWBIE_TOOLTIP_UNIT_LOOT_THRESHOLD	string	framexml
+NEWBIE_TOOLTIP_UNIT_MASTER_LOOTER	string	framexml
+NEWBIE_TOOLTIP_UNIT_NEED_BEFORE_GREED	string	framexml
+NEWBIE_TOOLTIP_UNIT_PET_ABANDON	string	framexml
+NEWBIE_TOOLTIP_UNIT_PET_DISMISS	string	framexml
+NEWBIE_TOOLTIP_UNIT_PET_PAPERDOLL	string	framexml
+NEWBIE_TOOLTIP_UNIT_PET_RENAME	string	framexml
+NEWBIE_TOOLTIP_UNIT_PROMOTE	string	framexml
+NEWBIE_TOOLTIP_UNIT_ROUND_ROBIN	string	framexml
+NEWBIE_TOOLTIP_UNIT_TRADE	string	framexml
+NEWBIE_TOOLTIP_UNIT_UNINVITE	string	framexml
+NEWBIE_TOOLTIP_WHOTAB	string	framexml
+NEWBIE_TOOLTIP_WORLDMAP	string	framexml
+NEWBIE_TOOLTIP_XPBAR	string	framexml
+NEW_CHAT_WINDOW	string	framexml
+NEW_LEADER	string	framexml
+NEXT	string	framexml
+NEXT_ABILITY	string	framexml
+NO	string	framexml
+NONE	string	framexml
+NONEQUIPSLOT	string	framexml
+NONE_CAPS	string	framexml
+NORMAL_FONT_COLOR	table	framexml
+NORMAL_FONT_COLOR_CODE	string	framexml
+NOTE	string	framexml
+NOTE_COLON	string	framexml
+NOTE_SUBMITTED	string	framexml
+NOTE_SUBMIT_FAILED	string	framexml
+NOT_APPLICABLE	string	framexml
+NOT_BOUND	string	framexml
+NOT_ENOUGH_MANA	string	framexml
+NOT_IN_GROUP	string	framexml
+NOT_TAMEABLE	string	framexml
+NOT_YET_SIGNED	string	framexml
+NO_ATTACHMENTS	string	framexml
+NO_BIDS	string	framexml
+NO_EMPTY_KEYRING_SLOTS_ERROR	string	framexml
+NO_EQUIPMENT_SLOTS_AVAILABLE	string	framexml
+NO_RAID_INSTANCES_SAVED	string	framexml
+NO_RESPONSE	string	framexml
+NUMBER_OF_RESULTS_TEMPLATE	string	framexml
+NUMGOSSIPBUTTONS	number	framexml
+NUM_ACTIONBAR_BUTTONS	number	framexml
+NUM_ACTIONBAR_PAGES	number	framexml
+NUM_ALWAYS_UP_UI_FRAMES	number	framexml
+NUM_AUCTIONS_TO_DISPLAY	lod	framexml
+NUM_AUCTION_ITEMS_PER_PAGE	lod	framexml
+NUM_BAG_FRAMES	number	framexml
+NUM_BAG_SLOTS	number	framexml
+NUM_BANKBAGSLOTS	number	framexml
+NUM_BANKGENERIC_SLOTS	number	framexml
+NUM_BATTLEFIELDMAP_OVERLAYS	lod	framexml
+NUM_BATTLEFIELDMAP_POIS	lod	framexml
+NUM_BIDS_TO_DISPLAY	lod	framexml
+NUM_BONUS_ACTION_SLOTS	number	framexml
+NUM_BROWSE_TO_DISPLAY	lod	framexml
+NUM_CHAT_WINDOWS	number	framexml
+NUM_COMBAT_TEXT_LINES	lod	framexml
+NUM_CONTAINER_COLUMNS	number	framexml
+NUM_CONTAINER_FRAMES	number	framexml
+NUM_EXTENDED_UI_FRAMES	number	framexml
+NUM_FACTIONS_DISPLAYED	number	framexml
+NUM_FILTERS_TO_DISPLAY	lod	framexml
+NUM_GM_CATEGORIES_TO_DISPLAY	number	framexml
+NUM_GROUP_LOOT_FRAMES	number	framexml
+NUM_ICONS_PER_ROW	lod	framexml
+NUM_ICON_ROWS	lod	framexml
+NUM_MACRO_ICONS_SHOWN	lod	framexml
+NUM_MULTIBAR_BUTTONS	number	framexml
+NUM_PET_ACTION_SLOTS	number	framexml
+NUM_PET_RESISTANCE_TYPES	number	framexml
+NUM_PET_STABLE_SLOTS	number	framexml
+NUM_PET_STATS	number	framexml
+NUM_RAID_GROUPS	number	framexml
+NUM_RAID_MEMBERS	string	framexml
+NUM_RAID_PULLOUT_FRAMES	lod	framexml
+NUM_REMEMBERED_TELLS	number	framexml
+NUM_RESISTANCE_TYPES	number	framexml
+NUM_SHAPESHIFT_SLOTS	number	framexml
+NUM_SHOPPING_TOOLTIPS	number	framexml
+NUM_STATS	number	framexml
+NUM_TALENT_COLUMNS	lod	framexml
+NUM_TAXI_BUTTONS	number	framexml
+NUM_TAXI_ROUTES	number	framexml
+NUM_WORLDMAP_DETAIL_TILES	number	framexml
+NUM_WORLDMAP_FLAGS	number	framexml
+NUM_WORLDMAP_OVERLAYS	number	framexml
+NUM_WORLDMAP_POIS	number	framexml
+NUM_WORLDMAP_POI_COLUMNS	number	framexml
+NewGMTicket	function	engine
+NextPageButton_OnClick	function	framexml
+NextView	function	engine
+NoPlayTime	function	engine
+NotWhileDeadError	function	engine
+NotifyInspect	function	engine
+NumTaxiNodes	function	engine
+NumberFontNormal	table	framexml
+NumberFontNormalHuge	table	framexml
+NumberFontNormalLarge	table	framexml
+NumberFontNormalSmall	table	framexml
+NumberFontNormalSmallGray	table	framexml
+NumberFontNormalYellow	table	framexml
+OBJECT_ALPHA	string	framexml
+OFFICER_NOTE_COLON	string	framexml
+OKAY	string	framexml
+ONLY_EMPTY_BAGS	string	framexml
+OPACITY	string	framexml
+OPENMAIL	string	framexml
+OPEN_DROPDOWNMENUS	table	framexml
+OPEN_FILTER_LIST	lod	framexml
+OPEN_LOCK_OTHER	string	framexml
+OPEN_LOCK_SELF	string	framexml
+OPTIONAL	string	framexml
+OPTIONS_BRIGHTNESS	string	framexml
+OPTIONS_FARCLIP_MAX	number	framexml
+OPTIONS_FARCLIP_MIN	number	framexml
+OPTIONS_FRAME_WIDTH	number	framexml
+OPTIONS_MENU	string	framexml
+OPTION_LOGOUT_REQUIREMENT	string	framexml
+OPTION_RESTART_REQUIREMENT	string	framexml
+OPTION_TOOLTIP_ALWAYS_SHOW_MULTIBARS	string	framexml
+OPTION_TOOLTIP_AMBIENCE_VOLUME	string	framexml
+OPTION_TOOLTIP_ANIMATION	string	framexml
+OPTION_TOOLTIP_ANISOTROPIC	string	framexml
+OPTION_TOOLTIP_ASSIST_ATTACK	string	framexml
+OPTION_TOOLTIP_AUTO_FOLLOW_SPEED	string	framexml
+OPTION_TOOLTIP_AUTO_JOIN_GUILD_CHANNEL	string	framexml
+OPTION_TOOLTIP_AUTO_QUEST_WATCH	string	framexml
+OPTION_TOOLTIP_AUTO_SELF_CAST	string	framexml
+OPTION_TOOLTIP_BLOCK_TRADES	string	framexml
+OPTION_TOOLTIP_BUFFERING	string	framexml
+OPTION_TOOLTIP_CAMERA1	string	framexml
+OPTION_TOOLTIP_CAMERA2	string	framexml
+OPTION_TOOLTIP_CAMERA3	string	framexml
+OPTION_TOOLTIP_CAMERA_ALWAYS	string	framexml
+OPTION_TOOLTIP_CAMERA_NEVER	string	framexml
+OPTION_TOOLTIP_CAMERA_SMART	string	framexml
+OPTION_TOOLTIP_CHAT_BUBBLES	string	framexml
+OPTION_TOOLTIP_CHAT_LOCKED	string	framexml
+OPTION_TOOLTIP_CINEMATIC_SUBTITLES	string	framexml
+OPTION_TOOLTIP_CLEAR_AFK	string	framexml
+OPTION_TOOLTIP_CLICKCAMERA_LOCKED	string	framexml
+OPTION_TOOLTIP_CLICKCAMERA_NEVER	string	framexml
+OPTION_TOOLTIP_CLICKCAMERA_SMART	string	framexml
+OPTION_TOOLTIP_CLICK_CAMERA1	string	framexml
+OPTION_TOOLTIP_CLICK_CAMERA2	string	framexml
+OPTION_TOOLTIP_CLICK_CAMERA3	string	framexml
+OPTION_TOOLTIP_CLICK_CAMERA_STYLE	string	framexml
+OPTION_TOOLTIP_CLICK_TO_MOVE	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_MODE	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SCROLL_DOWN	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_AURAS	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_AURA_FADE	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_COMBAT_STATE	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_COMBO_POINTS	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_DODGE_PARRY_MISS	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_FRIENDLY_NAMES	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_HONOR_GAINED	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_LOW_HEALTH_MANA	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_MANA	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_REACTIVES	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_REPUTATION	string	framexml
+OPTION_TOOLTIP_COMBAT_TEXT_SHOW_RESISTANCES	string	framexml
+OPTION_TOOLTIP_DEATH_EFFECT	string	framexml
+OPTION_TOOLTIP_DISABLE_SPAM_FILTER	string	framexml
+OPTION_TOOLTIP_ENABLE_ALL_SHADERS	string	framexml
+OPTION_TOOLTIP_ENABLE_ALL_SOUND	string	framexml
+OPTION_TOOLTIP_ENABLE_AMBIENCE	string	framexml
+OPTION_TOOLTIP_ENABLE_EMOTE_SOUNDS	string	framexml
+OPTION_TOOLTIP_ENABLE_ERROR_SPEECH	string	framexml
+OPTION_TOOLTIP_ENABLE_GROUP_SPEECH	string	framexml
+OPTION_TOOLTIP_ENABLE_MUSIC	string	framexml
+OPTION_TOOLTIP_ENABLE_MUSIC_LOOPING	string	framexml
+OPTION_TOOLTIP_ENABLE_SOUND_AT_CHARACTER	string	framexml
+OPTION_TOOLTIP_ENVIRONMENT_DETAIL	string	framexml
+OPTION_TOOLTIP_FARCLIP	string	framexml
+OPTION_TOOLTIP_FIX_LAG	string	framexml
+OPTION_TOOLTIP_FOLLOW_TERRAIN	string	framexml
+OPTION_TOOLTIP_FULL_SCREEN_GLOW	string	framexml
+OPTION_TOOLTIP_GAMEFIELD_DESELECT	string	framexml
+OPTION_TOOLTIP_GAMMA	string	framexml
+OPTION_TOOLTIP_GUILDMEMBER_ALERT	string	framexml
+OPTION_TOOLTIP_HARDWARE_CURSOR	string	framexml
+OPTION_TOOLTIP_HEAD_BOB	string	framexml
+OPTION_TOOLTIP_HIDE_OUTDOOR_WORLD_STATE	string	framexml
+OPTION_TOOLTIP_HIDE_PARTY_INTERFACE	string	framexml
+OPTION_TOOLTIP_INVERT_MOUSE	string	framexml
+OPTION_TOOLTIP_LOCK_ACTIONBAR	string	framexml
+OPTION_TOOLTIP_LOG_PERIODIC_EFFECTS	string	framexml
+OPTION_TOOLTIP_MASTER_VOLUME	string	framexml
+OPTION_TOOLTIP_MAX_FOLLOW_DIST	string	framexml
+OPTION_TOOLTIP_MOUSE_LOOK_SPEED	string	framexml
+OPTION_TOOLTIP_MOUSE_SENSITIVITY	string	framexml
+OPTION_TOOLTIP_MULTISAMPLING	string	framexml
+OPTION_TOOLTIP_MUSIC_VOLUME	string	framexml
+OPTION_TOOLTIP_OBJECT_ALPHA	string	framexml
+OPTION_TOOLTIP_PARTY_CHAT_BUBBLES	string	framexml
+OPTION_TOOLTIP_PET_NAMEPLATES	string	framexml
+OPTION_TOOLTIP_PET_SPELL_DAMAGE	string	framexml
+OPTION_TOOLTIP_PHONG_SHADING	string	framexml
+OPTION_TOOLTIP_PROFANITY_FILTER	string	framexml
+OPTION_TOOLTIP_REMOVE_CHAT_DELAY	string	framexml
+OPTION_TOOLTIP_SCROLL_ARC	string	framexml
+OPTION_TOOLTIP_SCROLL_DOWN	string	framexml
+OPTION_TOOLTIP_SCROLL_UP	string	framexml
+OPTION_TOOLTIP_SHOW_BUFF_DURATION	string	framexml
+OPTION_TOOLTIP_SHOW_CASTABLE_BUFFS	string	framexml
+OPTION_TOOLTIP_SHOW_CLOAK	string	framexml
+OPTION_TOOLTIP_SHOW_COMBAT_TEXT	string	framexml
+OPTION_TOOLTIP_SHOW_DAMAGE	string	framexml
+OPTION_TOOLTIP_SHOW_DISPELLABLE_DEBUFFS	string	framexml
+OPTION_TOOLTIP_SHOW_GUILD_NAMES	string	framexml
+OPTION_TOOLTIP_SHOW_HELM	string	framexml
+OPTION_TOOLTIP_SHOW_LOOT_SPAM	string	framexml
+OPTION_TOOLTIP_SHOW_MULTIBAR1	string	framexml
+OPTION_TOOLTIP_SHOW_MULTIBAR2	string	framexml
+OPTION_TOOLTIP_SHOW_MULTIBAR3	string	framexml
+OPTION_TOOLTIP_SHOW_MULTIBAR4	string	framexml
+OPTION_TOOLTIP_SHOW_NEWBIE_TIPS	string	framexml
+OPTION_TOOLTIP_SHOW_NPC_NAMES	string	framexml
+OPTION_TOOLTIP_SHOW_OWN_NAME	string	framexml
+OPTION_TOOLTIP_SHOW_PARTY_BACKGROUND	string	framexml
+OPTION_TOOLTIP_SHOW_PARTY_PETS	string	framexml
+OPTION_TOOLTIP_SHOW_PET_MELEE_DAMAGE	string	framexml
+OPTION_TOOLTIP_SHOW_PLAYER_NAMES	string	framexml
+OPTION_TOOLTIP_SHOW_PLAYER_TITLES	string	framexml
+OPTION_TOOLTIP_SHOW_QUEST_FADING	string	framexml
+OPTION_TOOLTIP_SHOW_TARGET_OF_TARGET	string	framexml
+OPTION_TOOLTIP_SHOW_TIPOFTHEDAY	string	framexml
+OPTION_TOOLTIP_SHOW_TUTORIALS	string	framexml
+OPTION_TOOLTIP_SHOW_UNIT_NAMES	string	framexml
+OPTION_TOOLTIP_SIMPLE_CHAT	string	framexml
+OPTION_TOOLTIP_SMART_PIVOT	string	framexml
+OPTION_TOOLTIP_SOUND_VOLUME	string	framexml
+OPTION_TOOLTIP_SPELL_DETAIL	string	framexml
+OPTION_TOOLTIP_STATUS_BAR	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET1	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET2	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET3	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET4	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET5	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET_ALWAYS	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET_PARTY	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET_RAID	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET_RAID_AND_PARTY	string	framexml
+OPTION_TOOLTIP_TARGETOFTARGET_SOLO	string	framexml
+OPTION_TOOLTIP_TERRAIN_HIGHLIGHTS	string	framexml
+OPTION_TOOLTIP_TERRAIN_TEXTURE	string	framexml
+OPTION_TOOLTIP_TEXTURE_DETAIL	string	framexml
+OPTION_TOOLTIP_TRILINEAR	string	framexml
+OPTION_TOOLTIP_UI_SCALE	string	framexml
+OPTION_TOOLTIP_USE_DESKTOP_GAMMA	string	framexml
+OPTION_TOOLTIP_USE_REFRESH	string	framexml
+OPTION_TOOLTIP_USE_RESOLUTION	string	framexml
+OPTION_TOOLTIP_USE_UBERTOOLTIPS	string	framexml
+OPTION_TOOLTIP_USE_UISCALE	string	framexml
+OPTION_TOOLTIP_USE_WEATHER_SHADER	string	framexml
+OPTION_TOOLTIP_VERTEX_ANIMATION_SHADERS	string	framexml
+OPTION_TOOLTIP_VERTICAL_SYNC	string	framexml
+OPTION_TOOLTIP_WATER_COLLISION	string	framexml
+OPTION_TOOLTIP_WEATHER_DETAIL	string	framexml
+OPTION_TOOLTIP_WINDOWED_MAXIMIZED	string	framexml
+OPTION_TOOLTIP_WINDOWED_MODE	string	framexml
+OPTION_TOOLTIP_WORLD_LOD	string	framexml
+OTHER_MESSAGES	string	framexml
+OUTBID	string	framexml
+OUTBID_BY	string	framexml
+OUT_OF_ENERGY	string	framexml
+OUT_OF_FOCUS	string	framexml
+OUT_OF_HEALTH	string	framexml
+OUT_OF_MANA	string	framexml
+OUT_OF_RAGE	string	framexml
+OfferPetition	function	engine
+OffhandHasWeapon	function	engine
+OfficerNoteText	table	framexml
+OnAccept	lod	framexml
+OnCancel	lod	framexml
+OnHide	lod	framexml
+OnMenuLoad	function	framexml
+OnShow	lod	framexml
+OnUpdate	lod	framexml
+OpacityFrame	table	framexml
+OpacityFrameCloseButton	table	framexml
+OpacityFrameSlider	table	framexml
+OpacityFrameSliderText	table	framexml
+OpacitySliderFrame	table	framexml
+OpacitySliderFrameText	table	framexml
+OpenAllBags	function	framexml
+OpenBackpack	function	framexml
+OpenBag	function	framexml
+OpenCoinPickupFrame	function	framexml
+OpenMailArithmeticLine	table	framexml
+OpenMailAttachmentText	table	framexml
+OpenMailBodyText	table	framexml
+OpenMailCancelButton	table	framexml
+OpenMailCancelButtonText	table	framexml
+OpenMailCloseButton	table	framexml
+OpenMailDeleteButton	table	framexml
+OpenMailDeleteButtonText	table	framexml
+OpenMailDepositMoneyFrame	table	framexml
+OpenMailDepositMoneyFrameCopperButton	table	framexml
+OpenMailDepositMoneyFrameCopperButtonText	table	framexml
+OpenMailDepositMoneyFrameGoldButton	table	framexml
+OpenMailDepositMoneyFrameGoldButtonText	table	framexml
+OpenMailDepositMoneyFrameSilverButton	table	framexml
+OpenMailDepositMoneyFrameSilverButtonText	table	framexml
+OpenMailFrame	table	framexml
+OpenMailFrameBotLeft	table	framexml
+OpenMailFrameBotRight	table	framexml
+OpenMailFrameIcon	table	framexml
+OpenMailFrameTopLeft	table	framexml
+OpenMailFrameTopRight	table	framexml
+OpenMailFrame_OnHide	function	framexml
+OpenMailHorizontalBarLeft	table	framexml
+OpenMailHouseCutMoneyFrame	table	framexml
+OpenMailHouseCutMoneyFrameCopperButton	table	framexml
+OpenMailHouseCutMoneyFrameCopperButtonText	table	framexml
+OpenMailHouseCutMoneyFrameGoldButton	table	framexml
+OpenMailHouseCutMoneyFrameGoldButtonText	table	framexml
+OpenMailHouseCutMoneyFrameSilverButton	table	framexml
+OpenMailHouseCutMoneyFrameSilverButtonText	table	framexml
+OpenMailInvoiceAmountReceived	table	framexml
+OpenMailInvoiceBuyMode	table	framexml
+OpenMailInvoiceDeposit	table	framexml
+OpenMailInvoiceFrame	table	framexml
+OpenMailInvoiceHouseCut	table	framexml
+OpenMailInvoiceItemLabel	table	framexml
+OpenMailInvoicePurchaser	table	framexml
+OpenMailInvoiceSalePrice	table	framexml
+OpenMailLetterButton	table	framexml
+OpenMailLetterButtonCount	table	framexml
+OpenMailLetterButtonIconTexture	table	framexml
+OpenMailLetterButtonNormalTexture	table	framexml
+OpenMailLetterButtonStock	table	framexml
+OpenMailMoneyButton	table	framexml
+OpenMailMoneyButtonCount	table	framexml
+OpenMailMoneyButtonIconTexture	table	framexml
+OpenMailMoneyButtonNormalTexture	table	framexml
+OpenMailMoneyButtonStock	table	framexml
+OpenMailPackageButton	table	framexml
+OpenMailPackageButtonCount	table	framexml
+OpenMailPackageButtonIconTexture	table	framexml
+OpenMailPackageButtonNormalTexture	table	framexml
+OpenMailPackageButtonStock	table	framexml
+OpenMailPackage_OnEnter	function	framexml
+OpenMailReplyButton	table	framexml
+OpenMailReplyButtonText	table	framexml
+OpenMailSalePriceMoneyFrame	table	framexml
+OpenMailSalePriceMoneyFrameCopperButton	table	framexml
+OpenMailSalePriceMoneyFrameCopperButtonText	table	framexml
+OpenMailSalePriceMoneyFrameGoldButton	table	framexml
+OpenMailSalePriceMoneyFrameGoldButtonText	table	framexml
+OpenMailSalePriceMoneyFrameSilverButton	table	framexml
+OpenMailSalePriceMoneyFrameSilverButtonText	table	framexml
+OpenMailScrollChildFrame	table	framexml
+OpenMailScrollFrame	table	framexml
+OpenMailScrollFrameScrollBar	table	framexml
+OpenMailScrollFrameScrollBarScrollDownButton	table	framexml
+OpenMailScrollFrameScrollBarScrollUpButton	table	framexml
+OpenMailScrollFrameScrollBarThumbTexture	table	framexml
+OpenMailSender	table	framexml
+OpenMailSenderLabel	table	framexml
+OpenMailSubject	table	framexml
+OpenMailSubjectLabel	table	framexml
+OpenMailTitleText	table	framexml
+OpenMailTransactionAmountMoneyFrame	table	framexml
+OpenMailTransactionAmountMoneyFrameCopperButton	table	framexml
+OpenMailTransactionAmountMoneyFrameCopperButtonText	table	framexml
+OpenMailTransactionAmountMoneyFrameGoldButton	table	framexml
+OpenMailTransactionAmountMoneyFrameGoldButtonText	table	framexml
+OpenMailTransactionAmountMoneyFrameSilverButton	table	framexml
+OpenMailTransactionAmountMoneyFrameSilverButtonText	table	framexml
+OpenMail_Delete	function	framexml
+OpenMail_Reply	function	framexml
+OpenMail_Update	function	framexml
+OpenStackSplitFrame	function	framexml
+OpenStationeryBackgroundLeft	table	framexml
+OpenStationeryBackgroundRight	table	framexml
+OpenTrainer	function	engine
+OpeningCinematic	function	engine
+OptionFrameBoxTemplate	lod	framexml
+OptionsButtonTemplate	lod	framexml
+OptionsCheckButtonTemplate	lod	framexml
+OptionsFrame	table	framexml
+OptionsFrameBrightness	table	framexml
+OptionsFrameBrightnessTitle	table	framexml
+OptionsFrameCancel	table	framexml
+OptionsFrameCancelText	table	framexml
+OptionsFrameCheckButton1	table	framexml
+OptionsFrameCheckButton10	table	framexml
+OptionsFrameCheckButton10Text	table	framexml
+OptionsFrameCheckButton11	table	framexml
+OptionsFrameCheckButton11Text	table	framexml
+OptionsFrameCheckButton12	table	framexml
+OptionsFrameCheckButton12Text	table	framexml
+OptionsFrameCheckButton13	table	framexml
+OptionsFrameCheckButton13Text	table	framexml
+OptionsFrameCheckButton14	table	framexml
+OptionsFrameCheckButton14Text	table	framexml
+OptionsFrameCheckButton15	table	framexml
+OptionsFrameCheckButton15Text	table	framexml
+OptionsFrameCheckButton16	table	framexml
+OptionsFrameCheckButton16Text	table	framexml
+OptionsFrameCheckButton17	table	framexml
+OptionsFrameCheckButton17Text	table	framexml
+OptionsFrameCheckButton18	table	framexml
+OptionsFrameCheckButton18Text	table	framexml
+OptionsFrameCheckButton1Text	table	framexml
+OptionsFrameCheckButton2	table	framexml
+OptionsFrameCheckButton2Text	table	framexml
+OptionsFrameCheckButton3	table	framexml
+OptionsFrameCheckButton3Text	table	framexml
+OptionsFrameCheckButton4	table	framexml
+OptionsFrameCheckButton4Text	table	framexml
+OptionsFrameCheckButton5	table	framexml
+OptionsFrameCheckButton5Text	table	framexml
+OptionsFrameCheckButton6	table	framexml
+OptionsFrameCheckButton6Text	table	framexml
+OptionsFrameCheckButton7	table	framexml
+OptionsFrameCheckButton7Text	table	framexml
+OptionsFrameCheckButton8	table	framexml
+OptionsFrameCheckButton8Text	table	framexml
+OptionsFrameCheckButton9	table	framexml
+OptionsFrameCheckButton9Text	table	framexml
+OptionsFrameCheckButtons	table	framexml
+OptionsFrameDefaults	table	framexml
+OptionsFrameDefaultsText	table	framexml
+OptionsFrameDisplay	table	framexml
+OptionsFrameDisplayTitle	table	framexml
+OptionsFrameHeader	table	framexml
+OptionsFrameMiscellaneous	table	framexml
+OptionsFrameMiscellaneousTitle	table	framexml
+OptionsFrameMultiSampleDropDown	table	framexml
+OptionsFrameMultiSampleDropDownButton	table	framexml
+OptionsFrameMultiSampleDropDownButtonDisabledTexture	table	framexml
+OptionsFrameMultiSampleDropDownButtonHighlightTexture	table	framexml
+OptionsFrameMultiSampleDropDownButtonNormalTexture	table	framexml
+OptionsFrameMultiSampleDropDownButtonPushedTexture	table	framexml
+OptionsFrameMultiSampleDropDownLabel	table	framexml
+OptionsFrameMultiSampleDropDownLeft	table	framexml
+OptionsFrameMultiSampleDropDownMiddle	table	framexml
+OptionsFrameMultiSampleDropDownRight	table	framexml
+OptionsFrameMultiSampleDropDownText	table	framexml
+OptionsFrameMultiSampleDropDown_Initialize	function	framexml
+OptionsFrameMultiSampleDropDown_OnClick	function	framexml
+OptionsFrameMultiSampleDropDown_OnLoad	function	framexml
+OptionsFrameOkay	table	framexml
+OptionsFrameOkayText	table	framexml
+OptionsFramePixelShaders	table	framexml
+OptionsFramePixelShadersTitle	table	framexml
+OptionsFrameRefreshDropDown	table	framexml
+OptionsFrameRefreshDropDownButton	table	framexml
+OptionsFrameRefreshDropDownButtonDisabledTexture	table	framexml
+OptionsFrameRefreshDropDownButtonHighlightTexture	table	framexml
+OptionsFrameRefreshDropDownButtonNormalTexture	table	framexml
+OptionsFrameRefreshDropDownButtonPushedTexture	table	framexml
+OptionsFrameRefreshDropDownLabel	table	framexml
+OptionsFrameRefreshDropDownLeft	table	framexml
+OptionsFrameRefreshDropDownMiddle	table	framexml
+OptionsFrameRefreshDropDownRight	table	framexml
+OptionsFrameRefreshDropDownText	table	framexml
+OptionsFrameRefreshDropDown_Initialize	function	framexml
+OptionsFrameRefreshDropDown_OnClick	function	framexml
+OptionsFrameRefreshDropDown_OnLoad	function	framexml
+OptionsFrameResolutionButton_OnClick	function	framexml
+OptionsFrameResolutionDropDown	table	framexml
+OptionsFrameResolutionDropDownButton	table	framexml
+OptionsFrameResolutionDropDownButtonDisabledTexture	table	framexml
+OptionsFrameResolutionDropDownButtonHighlightTexture	table	framexml
+OptionsFrameResolutionDropDownButtonNormalTexture	table	framexml
+OptionsFrameResolutionDropDownButtonPushedTexture	table	framexml
+OptionsFrameResolutionDropDownLabel	table	framexml
+OptionsFrameResolutionDropDownLeft	table	framexml
+OptionsFrameResolutionDropDownMiddle	table	framexml
+OptionsFrameResolutionDropDownRight	table	framexml
+OptionsFrameResolutionDropDownText	table	framexml
+OptionsFrameResolutionDropDown_Initialize	function	framexml
+OptionsFrameResolutionDropDown_LoadResolutions	function	framexml
+OptionsFrameResolutionDropDown_OnLoad	function	framexml
+OptionsFrameSlider1	table	framexml
+OptionsFrameSlider1High	table	framexml
+OptionsFrameSlider1Low	table	framexml
+OptionsFrameSlider1Text	table	framexml
+OptionsFrameSlider1Thumb	table	framexml
+OptionsFrameSlider2	table	framexml
+OptionsFrameSlider2High	table	framexml
+OptionsFrameSlider2Low	table	framexml
+OptionsFrameSlider2Text	table	framexml
+OptionsFrameSlider2Thumb	table	framexml
+OptionsFrameSlider3	table	framexml
+OptionsFrameSlider3High	table	framexml
+OptionsFrameSlider3Low	table	framexml
+OptionsFrameSlider3Text	table	framexml
+OptionsFrameSlider3Thumb	table	framexml
+OptionsFrameSlider4	table	framexml
+OptionsFrameSlider4High	table	framexml
+OptionsFrameSlider4Low	table	framexml
+OptionsFrameSlider4Text	table	framexml
+OptionsFrameSlider4Thumb	table	framexml
+OptionsFrameSlider5	table	framexml
+OptionsFrameSlider5High	table	framexml
+OptionsFrameSlider5Low	table	framexml
+OptionsFrameSlider5Text	table	framexml
+OptionsFrameSlider5Thumb	table	framexml
+OptionsFrameSlider6	table	framexml
+OptionsFrameSlider6High	table	framexml
+OptionsFrameSlider6Low	table	framexml
+OptionsFrameSlider6Text	table	framexml
+OptionsFrameSlider6Thumb	table	framexml
+OptionsFrameSlider7	table	framexml
+OptionsFrameSlider7High	table	framexml
+OptionsFrameSlider7Low	table	framexml
+OptionsFrameSlider7Text	table	framexml
+OptionsFrameSlider7Thumb	table	framexml
+OptionsFrameSlider8	table	framexml
+OptionsFrameSlider8High	table	framexml
+OptionsFrameSlider8Low	table	framexml
+OptionsFrameSlider8Text	table	framexml
+OptionsFrameSlider8Thumb	table	framexml
+OptionsFrameSlider9	table	framexml
+OptionsFrameSlider9High	table	framexml
+OptionsFrameSlider9Low	table	framexml
+OptionsFrameSlider9Text	table	framexml
+OptionsFrameSlider9Thumb	table	framexml
+OptionsFrameSliders	table	framexml
+OptionsFrameWorldAppearance	table	framexml
+OptionsFrameWorldAppearanceTitle	table	framexml
+OptionsFrame_Cancel	function	framexml
+OptionsFrame_DisableCheckBox	function	framexml
+OptionsFrame_DisableDropDown	function	framexml
+OptionsFrame_DisableSlider	function	framexml
+OptionsFrame_EnableCheckBox	function	framexml
+OptionsFrame_EnableDropDown	function	framexml
+OptionsFrame_EnableSlider	function	framexml
+OptionsFrame_GetMultisampleFormats	function	framexml
+OptionsFrame_GetRefreshRates	function	framexml
+OptionsFrame_Init	function	framexml
+OptionsFrame_Load	function	framexml
+OptionsFrame_OnEvent	function	framexml
+OptionsFrame_Save	function	framexml
+OptionsFrame_SetDefaults	function	framexml
+OptionsFrame_UpdateCheckboxes	function	framexml
+OptionsFrame_UpdateGammaControls	function	framexml
+OptionsFrame_UpdateUIScaleControls	function	framexml
+OptionsSliderTemplate	lod	framexml
+OtherMenuChatTypeGroups	table	framexml
+OutOfControlFrame	table	framexml
+PACKAGEITEMS_TO_DISPLAY	number	framexml
+PAGE_NUMBER	string	framexml
+PALADIN_INTELLECT_TOOLTIP	string	framexml
+PALADIN_STRENGTH_TOOLTIP	string	framexml
+PARENS_TEMPLATE	string	framexml
+PARRIED	string	framexml
+PARRY	string	framexml
+PARTY	string	framexml
+PARTYBACKGROUND_OPACITY	number	framexml
+PARTYKILLOTHER	string	framexml
+PARTY_CHAT_BUBBLES_TEXT	string	framexml
+PARTY_INVITE	string	framexml
+PARTY_LEAVE	string	framexml
+PARTY_MESSAGE	string	framexml
+PARTY_OPTIONS_LABEL	string	framexml
+PARTY_PROMOTE	string	framexml
+PARTY_QUEST_STATUS_NONE	string	framexml
+PARTY_QUEST_STATUS_ON	string	framexml
+PARTY_UNINVITE	string	framexml
+PASS	string	framexml
+PASSIVE_PARENS	string	framexml
+PASSIVE_SPELL_FONT_COLOR	table	framexml
+PERCENT_SYMBOL	string	framexml
+PERFORMANCEBAR_LOW_LATENCY	number	framexml
+PERFORMANCEBAR_MEDIUM_LATENCY	number	framexml
+PERFORMANCEBAR_UPDATE_INTERVAL	number	framexml
+PERIODICAURADAMAGEOTHEROTHER	string	framexml
+PERIODICAURADAMAGEOTHERSELF	string	framexml
+PERIODICAURADAMAGESELFOTHER	string	framexml
+PERIODICAURADAMAGESELFSELF	string	framexml
+PERIODICAURAHEALOTHEROTHER	string	framexml
+PERIODICAURAHEALOTHERSELF	string	framexml
+PERIODICAURAHEALSELFOTHER	string	framexml
+PERIODICAURAHEALSELFSELF	string	framexml
+PERIODIC_MESSAGES	string	framexml
+PET	string	framexml
+PETACTIONBAR_SLIDETIME	number	framexml
+PETACTIONBAR_XPOS	number	framexml
+PETACTIONBAR_YPOS	number	framexml
+PETITION_CREATOR	string	framexml
+PETITION_GAME_MASTER	string	framexml
+PETITION_NUM_SIGNATURES	string	framexml
+PETITION_NUM_SIGNATURES_P1	string	framexml
+PETITION_QUEUE_ACTIVE	number	framexml
+PETITION_TITLE	string	framexml
+PETTAME_ANOTHERSUMMONACTIVE	string	framexml
+PETTAME_CREATUREALREADYOWNED	string	framexml
+PETTAME_DEAD	string	framexml
+PETTAME_INTERNALERROR	string	framexml
+PETTAME_INVALIDCREATURE	string	framexml
+PETTAME_NOPETAVAILABLE	string	framexml
+PETTAME_NOTDEAD	string	framexml
+PETTAME_NOTTAMEABLE	string	framexml
+PETTAME_TOOHIGHLEVEL	string	framexml
+PETTAME_TOOMANY	string	framexml
+PETTAME_UNITSCANTTAME	string	framexml
+PETTAME_UNKNOWNERROR	string	framexml
+PET_ABANDON	string	framexml
+PET_ACTION_ATTACK	string	framexml
+PET_ACTION_DISMISS	string	framexml
+PET_ACTION_FOLLOW	string	framexml
+PET_ACTION_WAIT	string	framexml
+PET_AGGRESSIVE	string	framexml
+PET_AGGRESSIVE_TEXTURE	string	framexml
+PET_ATTACK	string	framexml
+PET_ATTACK_TEXTURE	string	framexml
+PET_DAMAGE_PERCENTAGE	string	framexml
+PET_DEFENSIVE	string	framexml
+PET_DEFENSIVE_TEXTURE	string	framexml
+PET_DIET_TEMPLATE	string	framexml
+PET_DISMISS	string	framexml
+PET_DISMISS_TEXTURE	string	framexml
+PET_FOLLOW	string	framexml
+PET_FOLLOW_TEXTURE	string	framexml
+PET_HAPPINESS1	string	framexml
+PET_HAPPINESS2	string	framexml
+PET_HAPPINESS3	string	framexml
+PET_LOYALTY_GAIN	string	framexml
+PET_LOYALTY_LOSS	string	framexml
+PET_MODE_AGGRESSIVE	string	framexml
+PET_MODE_DEFENSIVE	string	framexml
+PET_MODE_PASSIVE	string	framexml
+PET_PAPERDOLL	string	framexml
+PET_PASSIVE	string	framexml
+PET_PASSIVE_TEXTURE	string	framexml
+PET_RENAME	string	framexml
+PET_RENAME_CONFIRMATION	string	framexml
+PET_RENAME_LABEL	string	framexml
+PET_SPELLS_TEMPLATE	string	framexml
+PET_SPELL_NOPATH	string	framexml
+PET_TIME_LEFT_MINUTES	string	framexml
+PET_TIME_LEFT_SECONDS	string	framexml
+PET_TYPE_DEMON	string	framexml
+PET_TYPE_PET	string	framexml
+PET_WAIT	string	framexml
+PET_WAIT_TEXTURE	string	framexml
+PHONG_SHADING	string	framexml
+PHYSICAL_HARASSMENT	string	framexml
+PHYSICAL_HARASSMENT_DESCRIPTION	string	framexml
+PHYSICAL_HARASSMENT_TEXT1	string	framexml
+PHYSICAL_HARASSMENT_TEXT2	string	framexml
+PHYSICAL_HARASSMENT_TEXT3	string	framexml
+PHYSICAL_HARASSMENT_TEXT4	string	framexml
+PHYSICAL_HARASSMENT_TEXT5	string	framexml
+PHYSICAL_HARASSMENT_TEXT6	string	framexml
+PI	number	engine
+PIXEL_SHADERS	string	framexml
+PLAYER	string	framexml
+PLAYER_COUNT_ALLIANCE	string	framexml
+PLAYER_COUNT_ALLIANCE_P1	string	framexml
+PLAYER_COUNT_HORDE	string	framexml
+PLAYER_COUNT_HORDE_P1	string	framexml
+PLAYER_LEVEL	string	framexml
+PLAYER_LEVEL_UP	string	framexml
+PLAYER_LOGOUT_FAILED	string	framexml
+PLAYER_LOGOUT_FAILED_ERROR	string	framexml
+PLAYER_NOT_FOUND	string	framexml
+PLAYER_OFFLINE	string	framexml
+PLAYER_OPTIONS_LABEL	string	framexml
+PLAYER_STATUS	string	framexml
+PLAYTIME_TIRED	string	framexml
+PLAYTIME_UNHEALTHY	string	framexml
+PLUS_AMMO_DAMAGE_TEMPLATE	string	framexml
+PLUS_AMMO_SCHOOL_DAMAGE_TEMPLATE	string	framexml
+PLUS_DAMAGE_TEMPLATE	string	framexml
+PLUS_DAMAGE_TEMPLATE_WITH_SCHOOL	string	framexml
+PLUS_SINGLE_DAMAGE_TEMPLATE	string	framexml
+POTION_TIMER	string	framexml
+POWERGAINOTHEROTHER	string	framexml
+POWERGAINOTHERSELF	string	framexml
+POWERGAINSELFOTHER	string	framexml
+POWERGAINSELFSELF	string	framexml
+PREFERENCES	string	framexml
+PREV	string	framexml
+PREVIOUS_BATTLEFIELD_MOD	number	framexml
+PREVIOUS_BATTLEFIELD_QUEUES	table	framexml
+PRIEST_INTELLECT_TOOLTIP	string	framexml
+PRIMARY	string	framexml
+PRIMARY_SKILLS	string	framexml
+PROCRESISTOTHEROTHER	string	framexml
+PROCRESISTOTHERSELF	string	framexml
+PROCRESISTSELFOTHER	string	framexml
+PROCRESISTSELFSELF	string	framexml
+PROC_EVENT0_DESC	string	framexml
+PROC_EVENT1024_DESC	string	framexml
+PROC_EVENT128_DESC	string	framexml
+PROC_EVENT16_DESC	string	framexml
+PROC_EVENT1_DESC	string	framexml
+PROC_EVENT2048_DESC	string	framexml
+PROC_EVENT256_DESC	string	framexml
+PROC_EVENT2_DESC	string	framexml
+PROC_EVENT32_DESC	string	framexml
+PROC_EVENT3_DESC	string	framexml
+PROC_EVENT4_DESC	string	framexml
+PROC_EVENT512_DESC	string	framexml
+PROC_EVENT64_DESC	string	framexml
+PROC_EVENT8_DESC	string	framexml
+PROFANITY_FILTER	string	framexml
+PROFESSION_CONFIRMATION1	string	framexml
+PROFESSION_CONFIRMATION2	string	framexml
+PROFFESSION_CONFIRMATION2	string	framexml
+PROFICIENCIES	string	framexml
+PROFICIENCIES_COLON	string	framexml
+PROFICIENCY_NEEDED	string	framexml
+PROMOTE	string	framexml
+PUBLICNOTE_BUTTON_TOOLTIP	string	framexml
+PUBLIC_NOTE	string	framexml
+PULSEBUTTONS	table	framexml
+PURCHASE	string	framexml
+PURCHASED_BY_COLON	string	framexml
+PVPArenaTextString	table	framexml
+PVPFFA	string	framexml
+PVPInfoTextString	table	framexml
+PVP_DISABLED	string	framexml
+PVP_ENABLED	string	framexml
+PVP_MEDAL1	string	framexml
+PVP_MEDAL2	string	framexml
+PVP_MEDAL3	string	framexml
+PVP_MEDAL4	string	framexml
+PVP_MEDAL5	string	framexml
+PVP_MEDAL6	string	framexml
+PVP_MEDAL7	string	framexml
+PVP_MEDAL8	string	framexml
+PVP_POLICY_URL	string	framexml
+PVP_RANK_10_0	string	framexml
+PVP_RANK_10_0_FEMALE	string	framexml
+PVP_RANK_10_1	string	framexml
+PVP_RANK_10_1_FEMALE	string	framexml
+PVP_RANK_11_0	string	framexml
+PVP_RANK_11_0_FEMALE	string	framexml
+PVP_RANK_11_1	string	framexml
+PVP_RANK_11_1_FEMALE	string	framexml
+PVP_RANK_12_0	string	framexml
+PVP_RANK_12_0_FEMALE	string	framexml
+PVP_RANK_12_1	string	framexml
+PVP_RANK_12_1_FEMALE	string	framexml
+PVP_RANK_13_0	string	framexml
+PVP_RANK_13_0_FEMALE	string	framexml
+PVP_RANK_13_1	string	framexml
+PVP_RANK_13_1_FEMALE	string	framexml
+PVP_RANK_14_0	string	framexml
+PVP_RANK_14_0_FEMALE	string	framexml
+PVP_RANK_14_1	string	framexml
+PVP_RANK_14_1_FEMALE	string	framexml
+PVP_RANK_15_0	string	framexml
+PVP_RANK_15_0_FEMALE	string	framexml
+PVP_RANK_15_1	string	framexml
+PVP_RANK_15_1_FEMALE	string	framexml
+PVP_RANK_16_0	string	framexml
+PVP_RANK_16_0_FEMALE	string	framexml
+PVP_RANK_16_1	string	framexml
+PVP_RANK_16_1_FEMALE	string	framexml
+PVP_RANK_17_0	string	framexml
+PVP_RANK_17_0_FEMALE	string	framexml
+PVP_RANK_17_1	string	framexml
+PVP_RANK_17_1_FEMALE	string	framexml
+PVP_RANK_18_0	string	framexml
+PVP_RANK_18_0_FEMALE	string	framexml
+PVP_RANK_18_1	string	framexml
+PVP_RANK_18_1_FEMALE	string	framexml
+PVP_RANK_19_0	string	framexml
+PVP_RANK_19_0_FEMALE	string	framexml
+PVP_RANK_19_1	string	framexml
+PVP_RANK_19_1_FEMALE	string	framexml
+PVP_RANK_1_0	string	framexml
+PVP_RANK_1_0_FEMALE	string	framexml
+PVP_RANK_1_1	string	framexml
+PVP_RANK_1_1_FEMALE	string	framexml
+PVP_RANK_2_0	string	framexml
+PVP_RANK_2_0_FEMALE	string	framexml
+PVP_RANK_2_1	string	framexml
+PVP_RANK_2_1_FEMALE	string	framexml
+PVP_RANK_3_0	string	framexml
+PVP_RANK_3_0_FEMALE	string	framexml
+PVP_RANK_3_1	string	framexml
+PVP_RANK_3_1_FEMALE	string	framexml
+PVP_RANK_4_0	string	framexml
+PVP_RANK_4_0_FEMALE	string	framexml
+PVP_RANK_4_1	string	framexml
+PVP_RANK_4_1_FEMALE	string	framexml
+PVP_RANK_5_0	string	framexml
+PVP_RANK_5_0_FEMALE	string	framexml
+PVP_RANK_5_1	string	framexml
+PVP_RANK_5_1_FEMALE	string	framexml
+PVP_RANK_6_0	string	framexml
+PVP_RANK_6_0_FEMALE	string	framexml
+PVP_RANK_6_1	string	framexml
+PVP_RANK_6_1_FEMALE	string	framexml
+PVP_RANK_7_0	string	framexml
+PVP_RANK_7_0_FEMALE	string	framexml
+PVP_RANK_7_1	string	framexml
+PVP_RANK_7_1_FEMALE	string	framexml
+PVP_RANK_8_0	string	framexml
+PVP_RANK_8_0_FEMALE	string	framexml
+PVP_RANK_8_1	string	framexml
+PVP_RANK_8_1_FEMALE	string	framexml
+PVP_RANK_9_0	string	framexml
+PVP_RANK_9_0_FEMALE	string	framexml
+PVP_RANK_9_1	string	framexml
+PVP_RANK_9_1_FEMALE	string	framexml
+PVP_RANK_CIVILIAN	string	framexml
+PVP_RANK_CIVILIAN_FEMALE	string	framexml
+PVP_RANK_LEADER	string	framexml
+PVP_TOGGLE_OFF_VERBOSE	string	framexml
+PVP_TOGGLE_ON_VERBOSE	string	framexml
+PanelTemplates_DeselectTab	function	framexml
+PanelTemplates_DisableTab	function	framexml
+PanelTemplates_EnableTab	function	framexml
+PanelTemplates_GetSelectedTab	function	framexml
+PanelTemplates_SelectTab	function	framexml
+PanelTemplates_SetDisabledTabState	function	framexml
+PanelTemplates_SetNumTabs	function	framexml
+PanelTemplates_SetTab	function	framexml
+PanelTemplates_TabResize	function	framexml
+PanelTemplates_Tab_OnClick	function	framexml
+PanelTemplates_UpdateTabs	function	framexml
+PaperDollFormatStat	function	framexml
+PaperDollFrame	table	framexml
+PaperDollFrame_OnEvent	function	framexml
+PaperDollFrame_OnHide	function	framexml
+PaperDollFrame_OnLoad	function	framexml
+PaperDollFrame_OnShow	function	framexml
+PaperDollFrame_SetArmor	function	framexml
+PaperDollFrame_SetAttackBothHands	function	framexml
+PaperDollFrame_SetAttackPower	function	framexml
+PaperDollFrame_SetCharacterPoints	lod	framexml
+PaperDollFrame_SetDamage	function	framexml
+PaperDollFrame_SetDefense	function	framexml
+PaperDollFrame_SetGuild	function	framexml
+PaperDollFrame_SetLevel	function	framexml
+PaperDollFrame_SetRangedAttack	function	framexml
+PaperDollFrame_SetRangedAttackPower	function	framexml
+PaperDollFrame_SetRangedDamage	function	framexml
+PaperDollFrame_SetResistances	function	framexml
+PaperDollFrame_SetStats	function	framexml
+PaperDollItemSlotButtonTemplate	lod	framexml
+PaperDollItemSlotButton_OnClick	function	framexml
+PaperDollItemSlotButton_OnEnter	function	framexml
+PaperDollItemSlotButton_OnEvent	function	framexml
+PaperDollItemSlotButton_OnLoad	function	framexml
+PaperDollItemSlotButton_OnUpdate	function	framexml
+PaperDollItemSlotButton_Update	function	framexml
+PaperDollItemSlotButton_UpdateLock	function	framexml
+PaperDollStatTooltip	function	framexml
+PartialPlayTime	function	engine
+PartyBuffButtonTemplate	lod	framexml
+PartyFrameDropDown_Initialize	function	framexml
+PartyFrameDropDown_OnLoad	function	framexml
+PartyMemberBackground	table	framexml
+PartyMemberBackground_SaveOpacity	function	framexml
+PartyMemberBackground_SetOpacity	function	framexml
+PartyMemberBackground_ToggleOpacity	function	framexml
+PartyMemberBuffTooltip	table	framexml
+PartyMemberBuffTooltipBuff1	table	framexml
+PartyMemberBuffTooltipBuff10	table	framexml
+PartyMemberBuffTooltipBuff10Border	table	framexml
+PartyMemberBuffTooltipBuff10Icon	table	framexml
+PartyMemberBuffTooltipBuff11	table	framexml
+PartyMemberBuffTooltipBuff11Border	table	framexml
+PartyMemberBuffTooltipBuff11Icon	table	framexml
+PartyMemberBuffTooltipBuff12	table	framexml
+PartyMemberBuffTooltipBuff12Border	table	framexml
+PartyMemberBuffTooltipBuff12Icon	table	framexml
+PartyMemberBuffTooltipBuff13	table	framexml
+PartyMemberBuffTooltipBuff13Border	table	framexml
+PartyMemberBuffTooltipBuff13Icon	table	framexml
+PartyMemberBuffTooltipBuff14	table	framexml
+PartyMemberBuffTooltipBuff14Border	table	framexml
+PartyMemberBuffTooltipBuff14Icon	table	framexml
+PartyMemberBuffTooltipBuff15	table	framexml
+PartyMemberBuffTooltipBuff15Border	table	framexml
+PartyMemberBuffTooltipBuff15Icon	table	framexml
+PartyMemberBuffTooltipBuff16	table	framexml
+PartyMemberBuffTooltipBuff16Border	table	framexml
+PartyMemberBuffTooltipBuff16Icon	table	framexml
+PartyMemberBuffTooltipBuff1Border	table	framexml
+PartyMemberBuffTooltipBuff1Icon	table	framexml
+PartyMemberBuffTooltipBuff2	table	framexml
+PartyMemberBuffTooltipBuff2Border	table	framexml
+PartyMemberBuffTooltipBuff2Icon	table	framexml
+PartyMemberBuffTooltipBuff3	table	framexml
+PartyMemberBuffTooltipBuff3Border	table	framexml
+PartyMemberBuffTooltipBuff3Icon	table	framexml
+PartyMemberBuffTooltipBuff4	table	framexml
+PartyMemberBuffTooltipBuff4Border	table	framexml
+PartyMemberBuffTooltipBuff4Icon	table	framexml
+PartyMemberBuffTooltipBuff5	table	framexml
+PartyMemberBuffTooltipBuff5Border	table	framexml
+PartyMemberBuffTooltipBuff5Icon	table	framexml
+PartyMemberBuffTooltipBuff6	table	framexml
+PartyMemberBuffTooltipBuff6Border	table	framexml
+PartyMemberBuffTooltipBuff6Icon	table	framexml
+PartyMemberBuffTooltipBuff7	table	framexml
+PartyMemberBuffTooltipBuff7Border	table	framexml
+PartyMemberBuffTooltipBuff7Icon	table	framexml
+PartyMemberBuffTooltipBuff8	table	framexml
+PartyMemberBuffTooltipBuff8Border	table	framexml
+PartyMemberBuffTooltipBuff8Icon	table	framexml
+PartyMemberBuffTooltipBuff9	table	framexml
+PartyMemberBuffTooltipBuff9Border	table	framexml
+PartyMemberBuffTooltipBuff9Icon	table	framexml
+PartyMemberBuffTooltipDebuff1	table	framexml
+PartyMemberBuffTooltipDebuff1Border	table	framexml
+PartyMemberBuffTooltipDebuff1Icon	table	framexml
+PartyMemberBuffTooltipDebuff2	table	framexml
+PartyMemberBuffTooltipDebuff2Border	table	framexml
+PartyMemberBuffTooltipDebuff2Icon	table	framexml
+PartyMemberBuffTooltipDebuff3	table	framexml
+PartyMemberBuffTooltipDebuff3Border	table	framexml
+PartyMemberBuffTooltipDebuff3Icon	table	framexml
+PartyMemberBuffTooltipDebuff4	table	framexml
+PartyMemberBuffTooltipDebuff4Border	table	framexml
+PartyMemberBuffTooltipDebuff4Icon	table	framexml
+PartyMemberBuffTooltipDebuff5	table	framexml
+PartyMemberBuffTooltipDebuff5Border	table	framexml
+PartyMemberBuffTooltipDebuff5Icon	table	framexml
+PartyMemberBuffTooltipDebuff6	table	framexml
+PartyMemberBuffTooltipDebuff6Border	table	framexml
+PartyMemberBuffTooltipDebuff6Icon	table	framexml
+PartyMemberBuffTooltipDebuff7	table	framexml
+PartyMemberBuffTooltipDebuff7Border	table	framexml
+PartyMemberBuffTooltipDebuff7Icon	table	framexml
+PartyMemberBuffTooltipDebuff8	table	framexml
+PartyMemberBuffTooltipDebuff8Border	table	framexml
+PartyMemberBuffTooltipDebuff8Icon	table	framexml
+PartyMemberBuffTooltip_Update	function	framexml
+PartyMemberFrame1	table	framexml
+PartyMemberFrame1Debuff1	table	framexml
+PartyMemberFrame1Debuff1Border	table	framexml
+PartyMemberFrame1Debuff1Icon	table	framexml
+PartyMemberFrame1Debuff2	table	framexml
+PartyMemberFrame1Debuff2Border	table	framexml
+PartyMemberFrame1Debuff2Icon	table	framexml
+PartyMemberFrame1Debuff3	table	framexml
+PartyMemberFrame1Debuff3Border	table	framexml
+PartyMemberFrame1Debuff3Icon	table	framexml
+PartyMemberFrame1Debuff4	table	framexml
+PartyMemberFrame1Debuff4Border	table	framexml
+PartyMemberFrame1Debuff4Icon	table	framexml
+PartyMemberFrame1Disconnect	table	framexml
+PartyMemberFrame1DropDown	table	framexml
+PartyMemberFrame1DropDownButton	table	framexml
+PartyMemberFrame1DropDownButtonDisabledTexture	table	framexml
+PartyMemberFrame1DropDownButtonHighlightTexture	table	framexml
+PartyMemberFrame1DropDownButtonNormalTexture	table	framexml
+PartyMemberFrame1DropDownButtonPushedTexture	table	framexml
+PartyMemberFrame1DropDownLeft	table	framexml
+PartyMemberFrame1DropDownMiddle	table	framexml
+PartyMemberFrame1DropDownRight	table	framexml
+PartyMemberFrame1DropDownText	table	framexml
+PartyMemberFrame1HealthBar	table	framexml
+PartyMemberFrame1LeaderIcon	table	framexml
+PartyMemberFrame1ManaBar	table	framexml
+PartyMemberFrame1MasterIcon	table	framexml
+PartyMemberFrame1Name	table	framexml
+PartyMemberFrame1PVPIcon	table	framexml
+PartyMemberFrame1PetFrame	table	framexml
+PartyMemberFrame1PetFrameDebuff1	table	framexml
+PartyMemberFrame1PetFrameDebuff1Border	table	framexml
+PartyMemberFrame1PetFrameDebuff1Icon	table	framexml
+PartyMemberFrame1PetFrameDebuff2	table	framexml
+PartyMemberFrame1PetFrameDebuff2Border	table	framexml
+PartyMemberFrame1PetFrameDebuff2Icon	table	framexml
+PartyMemberFrame1PetFrameDebuff3	table	framexml
+PartyMemberFrame1PetFrameDebuff3Border	table	framexml
+PartyMemberFrame1PetFrameDebuff3Icon	table	framexml
+PartyMemberFrame1PetFrameDebuff4	table	framexml
+PartyMemberFrame1PetFrameDebuff4Border	table	framexml
+PartyMemberFrame1PetFrameDebuff4Icon	table	framexml
+PartyMemberFrame1PetFrameHealthBar	table	framexml
+PartyMemberFrame1PetFrameName	table	framexml
+PartyMemberFrame1PetFramePortrait	table	framexml
+PartyMemberFrame1PetFrameTexture	table	framexml
+PartyMemberFrame1Portrait	table	framexml
+PartyMemberFrame1Status	table	framexml
+PartyMemberFrame1Texture	table	framexml
+PartyMemberFrame2	table	framexml
+PartyMemberFrame2Debuff1	table	framexml
+PartyMemberFrame2Debuff1Border	table	framexml
+PartyMemberFrame2Debuff1Icon	table	framexml
+PartyMemberFrame2Debuff2	table	framexml
+PartyMemberFrame2Debuff2Border	table	framexml
+PartyMemberFrame2Debuff2Icon	table	framexml
+PartyMemberFrame2Debuff3	table	framexml
+PartyMemberFrame2Debuff3Border	table	framexml
+PartyMemberFrame2Debuff3Icon	table	framexml
+PartyMemberFrame2Debuff4	table	framexml
+PartyMemberFrame2Debuff4Border	table	framexml
+PartyMemberFrame2Debuff4Icon	table	framexml
+PartyMemberFrame2Disconnect	table	framexml
+PartyMemberFrame2DropDown	table	framexml
+PartyMemberFrame2DropDownButton	table	framexml
+PartyMemberFrame2DropDownButtonDisabledTexture	table	framexml
+PartyMemberFrame2DropDownButtonHighlightTexture	table	framexml
+PartyMemberFrame2DropDownButtonNormalTexture	table	framexml
+PartyMemberFrame2DropDownButtonPushedTexture	table	framexml
+PartyMemberFrame2DropDownLeft	table	framexml
+PartyMemberFrame2DropDownMiddle	table	framexml
+PartyMemberFrame2DropDownRight	table	framexml
+PartyMemberFrame2DropDownText	table	framexml
+PartyMemberFrame2HealthBar	table	framexml
+PartyMemberFrame2LeaderIcon	table	framexml
+PartyMemberFrame2ManaBar	table	framexml
+PartyMemberFrame2MasterIcon	table	framexml
+PartyMemberFrame2Name	table	framexml
+PartyMemberFrame2PVPIcon	table	framexml
+PartyMemberFrame2PetFrame	table	framexml
+PartyMemberFrame2PetFrameDebuff1	table	framexml
+PartyMemberFrame2PetFrameDebuff1Border	table	framexml
+PartyMemberFrame2PetFrameDebuff1Icon	table	framexml
+PartyMemberFrame2PetFrameDebuff2	table	framexml
+PartyMemberFrame2PetFrameDebuff2Border	table	framexml
+PartyMemberFrame2PetFrameDebuff2Icon	table	framexml
+PartyMemberFrame2PetFrameDebuff3	table	framexml
+PartyMemberFrame2PetFrameDebuff3Border	table	framexml
+PartyMemberFrame2PetFrameDebuff3Icon	table	framexml
+PartyMemberFrame2PetFrameDebuff4	table	framexml
+PartyMemberFrame2PetFrameDebuff4Border	table	framexml
+PartyMemberFrame2PetFrameDebuff4Icon	table	framexml
+PartyMemberFrame2PetFrameHealthBar	table	framexml
+PartyMemberFrame2PetFrameName	table	framexml
+PartyMemberFrame2PetFramePortrait	table	framexml
+PartyMemberFrame2PetFrameTexture	table	framexml
+PartyMemberFrame2Portrait	table	framexml
+PartyMemberFrame2Status	table	framexml
+PartyMemberFrame2Texture	table	framexml
+PartyMemberFrame3	table	framexml
+PartyMemberFrame3Debuff1	table	framexml
+PartyMemberFrame3Debuff1Border	table	framexml
+PartyMemberFrame3Debuff1Icon	table	framexml
+PartyMemberFrame3Debuff2	table	framexml
+PartyMemberFrame3Debuff2Border	table	framexml
+PartyMemberFrame3Debuff2Icon	table	framexml
+PartyMemberFrame3Debuff3	table	framexml
+PartyMemberFrame3Debuff3Border	table	framexml
+PartyMemberFrame3Debuff3Icon	table	framexml
+PartyMemberFrame3Debuff4	table	framexml
+PartyMemberFrame3Debuff4Border	table	framexml
+PartyMemberFrame3Debuff4Icon	table	framexml
+PartyMemberFrame3Disconnect	table	framexml
+PartyMemberFrame3DropDown	table	framexml
+PartyMemberFrame3DropDownButton	table	framexml
+PartyMemberFrame3DropDownButtonDisabledTexture	table	framexml
+PartyMemberFrame3DropDownButtonHighlightTexture	table	framexml
+PartyMemberFrame3DropDownButtonNormalTexture	table	framexml
+PartyMemberFrame3DropDownButtonPushedTexture	table	framexml
+PartyMemberFrame3DropDownLeft	table	framexml
+PartyMemberFrame3DropDownMiddle	table	framexml
+PartyMemberFrame3DropDownRight	table	framexml
+PartyMemberFrame3DropDownText	table	framexml
+PartyMemberFrame3HealthBar	table	framexml
+PartyMemberFrame3LeaderIcon	table	framexml
+PartyMemberFrame3ManaBar	table	framexml
+PartyMemberFrame3MasterIcon	table	framexml
+PartyMemberFrame3Name	table	framexml
+PartyMemberFrame3PVPIcon	table	framexml
+PartyMemberFrame3PetFrame	table	framexml
+PartyMemberFrame3PetFrameDebuff1	table	framexml
+PartyMemberFrame3PetFrameDebuff1Border	table	framexml
+PartyMemberFrame3PetFrameDebuff1Icon	table	framexml
+PartyMemberFrame3PetFrameDebuff2	table	framexml
+PartyMemberFrame3PetFrameDebuff2Border	table	framexml
+PartyMemberFrame3PetFrameDebuff2Icon	table	framexml
+PartyMemberFrame3PetFrameDebuff3	table	framexml
+PartyMemberFrame3PetFrameDebuff3Border	table	framexml
+PartyMemberFrame3PetFrameDebuff3Icon	table	framexml
+PartyMemberFrame3PetFrameDebuff4	table	framexml
+PartyMemberFrame3PetFrameDebuff4Border	table	framexml
+PartyMemberFrame3PetFrameDebuff4Icon	table	framexml
+PartyMemberFrame3PetFrameHealthBar	table	framexml
+PartyMemberFrame3PetFrameName	table	framexml
+PartyMemberFrame3PetFramePortrait	table	framexml
+PartyMemberFrame3PetFrameTexture	table	framexml
+PartyMemberFrame3Portrait	table	framexml
+PartyMemberFrame3Status	table	framexml
+PartyMemberFrame3Texture	table	framexml
+PartyMemberFrame4	table	framexml
+PartyMemberFrame4Debuff1	table	framexml
+PartyMemberFrame4Debuff1Border	table	framexml
+PartyMemberFrame4Debuff1Icon	table	framexml
+PartyMemberFrame4Debuff2	table	framexml
+PartyMemberFrame4Debuff2Border	table	framexml
+PartyMemberFrame4Debuff2Icon	table	framexml
+PartyMemberFrame4Debuff3	table	framexml
+PartyMemberFrame4Debuff3Border	table	framexml
+PartyMemberFrame4Debuff3Icon	table	framexml
+PartyMemberFrame4Debuff4	table	framexml
+PartyMemberFrame4Debuff4Border	table	framexml
+PartyMemberFrame4Debuff4Icon	table	framexml
+PartyMemberFrame4Disconnect	table	framexml
+PartyMemberFrame4DropDown	table	framexml
+PartyMemberFrame4DropDownButton	table	framexml
+PartyMemberFrame4DropDownButtonDisabledTexture	table	framexml
+PartyMemberFrame4DropDownButtonHighlightTexture	table	framexml
+PartyMemberFrame4DropDownButtonNormalTexture	table	framexml
+PartyMemberFrame4DropDownButtonPushedTexture	table	framexml
+PartyMemberFrame4DropDownLeft	table	framexml
+PartyMemberFrame4DropDownMiddle	table	framexml
+PartyMemberFrame4DropDownRight	table	framexml
+PartyMemberFrame4DropDownText	table	framexml
+PartyMemberFrame4HealthBar	table	framexml
+PartyMemberFrame4LeaderIcon	table	framexml
+PartyMemberFrame4ManaBar	table	framexml
+PartyMemberFrame4MasterIcon	table	framexml
+PartyMemberFrame4Name	table	framexml
+PartyMemberFrame4PVPIcon	table	framexml
+PartyMemberFrame4PetFrame	table	framexml
+PartyMemberFrame4PetFrameDebuff1	table	framexml
+PartyMemberFrame4PetFrameDebuff1Border	table	framexml
+PartyMemberFrame4PetFrameDebuff1Icon	table	framexml
+PartyMemberFrame4PetFrameDebuff2	table	framexml
+PartyMemberFrame4PetFrameDebuff2Border	table	framexml
+PartyMemberFrame4PetFrameDebuff2Icon	table	framexml
+PartyMemberFrame4PetFrameDebuff3	table	framexml
+PartyMemberFrame4PetFrameDebuff3Border	table	framexml
+PartyMemberFrame4PetFrameDebuff3Icon	table	framexml
+PartyMemberFrame4PetFrameDebuff4	table	framexml
+PartyMemberFrame4PetFrameDebuff4Border	table	framexml
+PartyMemberFrame4PetFrameDebuff4Icon	table	framexml
+PartyMemberFrame4PetFrameHealthBar	table	framexml
+PartyMemberFrame4PetFrameName	table	framexml
+PartyMemberFrame4PetFramePortrait	table	framexml
+PartyMemberFrame4PetFrameTexture	table	framexml
+PartyMemberFrame4Portrait	table	framexml
+PartyMemberFrame4Status	table	framexml
+PartyMemberFrame4Texture	table	framexml
+PartyMemberFrameTemplate	lod	framexml
+PartyMemberFrame_OnClick	function	framexml
+PartyMemberFrame_OnEvent	function	framexml
+PartyMemberFrame_OnLoad	function	framexml
+PartyMemberFrame_OnUpdate	function	framexml
+PartyMemberFrame_RefreshPetBuffs	function	framexml
+PartyMemberFrame_UpdateLeader	function	framexml
+PartyMemberFrame_UpdateMember	function	framexml
+PartyMemberFrame_UpdateMemberHealth	function	framexml
+PartyMemberFrame_UpdatePet	function	framexml
+PartyMemberFrame_UpdatePvPStatus	function	framexml
+PartyMemberHealthCheck	function	framexml
+PartyMemberPetFrameTemplate	lod	framexml
+PartyMemberPetFrame_OnClick	function	framexml
+PartyPetBuffButtonTemplate	lod	framexml
+PeriodicLogMenuChatTypeGroups	table	framexml
+PersonalNoteText	table	framexml
+PetAbandon	function	engine
+PetActionBarFrame	table	framexml
+PetActionBarFrame_OnUpdate	function	framexml
+PetActionBar_HideGrid	function	framexml
+PetActionBar_OnEvent	function	framexml
+PetActionBar_OnLoad	function	framexml
+PetActionBar_ShowGrid	function	framexml
+PetActionBar_Update	function	framexml
+PetActionBar_UpdateCooldowns	function	framexml
+PetActionButton1	table	framexml
+PetActionButton10	table	framexml
+PetActionButton10AutoCast	table	framexml
+PetActionButton10AutoCastable	table	framexml
+PetActionButton10Border	table	framexml
+PetActionButton10Cooldown	table	framexml
+PetActionButton10Count	table	framexml
+PetActionButton10Flash	table	framexml
+PetActionButton10HotKey	table	framexml
+PetActionButton10Icon	table	framexml
+PetActionButton10Name	table	framexml
+PetActionButton10NormalTexture	table	framexml
+PetActionButton10NormalTexture2	table	framexml
+PetActionButton1AutoCast	table	framexml
+PetActionButton1AutoCastable	table	framexml
+PetActionButton1Border	table	framexml
+PetActionButton1Cooldown	table	framexml
+PetActionButton1Count	table	framexml
+PetActionButton1Flash	table	framexml
+PetActionButton1HotKey	table	framexml
+PetActionButton1Icon	table	framexml
+PetActionButton1Name	table	framexml
+PetActionButton1NormalTexture	table	framexml
+PetActionButton1NormalTexture2	table	framexml
+PetActionButton2	table	framexml
+PetActionButton2AutoCast	table	framexml
+PetActionButton2AutoCastable	table	framexml
+PetActionButton2Border	table	framexml
+PetActionButton2Cooldown	table	framexml
+PetActionButton2Count	table	framexml
+PetActionButton2Flash	table	framexml
+PetActionButton2HotKey	table	framexml
+PetActionButton2Icon	table	framexml
+PetActionButton2Name	table	framexml
+PetActionButton2NormalTexture	table	framexml
+PetActionButton2NormalTexture2	table	framexml
+PetActionButton3	table	framexml
+PetActionButton3AutoCast	table	framexml
+PetActionButton3AutoCastable	table	framexml
+PetActionButton3Border	table	framexml
+PetActionButton3Cooldown	table	framexml
+PetActionButton3Count	table	framexml
+PetActionButton3Flash	table	framexml
+PetActionButton3HotKey	table	framexml
+PetActionButton3Icon	table	framexml
+PetActionButton3Name	table	framexml
+PetActionButton3NormalTexture	table	framexml
+PetActionButton3NormalTexture2	table	framexml
+PetActionButton4	table	framexml
+PetActionButton4AutoCast	table	framexml
+PetActionButton4AutoCastable	table	framexml
+PetActionButton4Border	table	framexml
+PetActionButton4Cooldown	table	framexml
+PetActionButton4Count	table	framexml
+PetActionButton4Flash	table	framexml
+PetActionButton4HotKey	table	framexml
+PetActionButton4Icon	table	framexml
+PetActionButton4Name	table	framexml
+PetActionButton4NormalTexture	table	framexml
+PetActionButton4NormalTexture2	table	framexml
+PetActionButton5	table	framexml
+PetActionButton5AutoCast	table	framexml
+PetActionButton5AutoCastable	table	framexml
+PetActionButton5Border	table	framexml
+PetActionButton5Cooldown	table	framexml
+PetActionButton5Count	table	framexml
+PetActionButton5Flash	table	framexml
+PetActionButton5HotKey	table	framexml
+PetActionButton5Icon	table	framexml
+PetActionButton5Name	table	framexml
+PetActionButton5NormalTexture	table	framexml
+PetActionButton5NormalTexture2	table	framexml
+PetActionButton6	table	framexml
+PetActionButton6AutoCast	table	framexml
+PetActionButton6AutoCastable	table	framexml
+PetActionButton6Border	table	framexml
+PetActionButton6Cooldown	table	framexml
+PetActionButton6Count	table	framexml
+PetActionButton6Flash	table	framexml
+PetActionButton6HotKey	table	framexml
+PetActionButton6Icon	table	framexml
+PetActionButton6Name	table	framexml
+PetActionButton6NormalTexture	table	framexml
+PetActionButton6NormalTexture2	table	framexml
+PetActionButton7	table	framexml
+PetActionButton7AutoCast	table	framexml
+PetActionButton7AutoCastable	table	framexml
+PetActionButton7Border	table	framexml
+PetActionButton7Cooldown	table	framexml
+PetActionButton7Count	table	framexml
+PetActionButton7Flash	table	framexml
+PetActionButton7HotKey	table	framexml
+PetActionButton7Icon	table	framexml
+PetActionButton7Name	table	framexml
+PetActionButton7NormalTexture	table	framexml
+PetActionButton7NormalTexture2	table	framexml
+PetActionButton8	table	framexml
+PetActionButton8AutoCast	table	framexml
+PetActionButton8AutoCastable	table	framexml
+PetActionButton8Border	table	framexml
+PetActionButton8Cooldown	table	framexml
+PetActionButton8Count	table	framexml
+PetActionButton8Flash	table	framexml
+PetActionButton8HotKey	table	framexml
+PetActionButton8Icon	table	framexml
+PetActionButton8Name	table	framexml
+PetActionButton8NormalTexture	table	framexml
+PetActionButton8NormalTexture2	table	framexml
+PetActionButton9	table	framexml
+PetActionButton9AutoCast	table	framexml
+PetActionButton9AutoCastable	table	framexml
+PetActionButton9Border	table	framexml
+PetActionButton9Cooldown	table	framexml
+PetActionButton9Count	table	framexml
+PetActionButton9Flash	table	framexml
+PetActionButton9HotKey	table	framexml
+PetActionButton9Icon	table	framexml
+PetActionButton9Name	table	framexml
+PetActionButton9NormalTexture	table	framexml
+PetActionButton9NormalTexture2	table	framexml
+PetActionButtonDown	function	framexml
+PetActionButtonTemplate	lod	framexml
+PetActionButtonUp	function	framexml
+PetActionButton_OnClick	function	framexml
+PetActionButton_OnDragStart	function	framexml
+PetActionButton_OnEnter	function	framexml
+PetActionButton_OnEvent	function	framexml
+PetActionButton_OnLeave	function	framexml
+PetActionButton_OnLoad	function	framexml
+PetActionButton_OnReceiveDrag	function	framexml
+PetActionButton_SetHotkeys	function	framexml
+PetActionButton_StartFlash	function	framexml
+PetActionButton_StopFlash	function	framexml
+PetAggressiveMode	function	engine
+PetArmorFrame	table	framexml
+PetArmorFrameLabel	table	framexml
+PetArmorFrameStat	table	framexml
+PetArmorFrameStatText	table	framexml
+PetAttack	function	engine
+PetAttackFrame	table	framexml
+PetAttackFrameLabel	table	framexml
+PetAttackFrameStat	table	framexml
+PetAttackFrameStatText	table	framexml
+PetAttackModeTexture	table	framexml
+PetAttackPowerFrame	table	framexml
+PetAttackPowerFrameLabel	table	framexml
+PetAttackPowerFrameStat	table	framexml
+PetAttackPowerFrameStatText	table	framexml
+PetAttributesFrame	table	framexml
+PetCanBeAbandoned	function	engine
+PetCanBeRenamed	function	engine
+PetDamageFrame	table	framexml
+PetDamageFrameLabel	table	framexml
+PetDamageFrameStat	table	framexml
+PetDamageFrameStatText	table	framexml
+PetDefenseFrame	table	framexml
+PetDefenseFrameLabel	table	framexml
+PetDefenseFrameStat	table	framexml
+PetDefenseFrameStatText	table	framexml
+PetDefensiveMode	function	engine
+PetDismiss	function	engine
+PetExpBar_Update	function	framexml
+PetFollow	function	engine
+PetFrame	table	framexml
+PetFrameDebuff1	table	framexml
+PetFrameDebuff1Border	table	framexml
+PetFrameDebuff1Icon	table	framexml
+PetFrameDebuff2	table	framexml
+PetFrameDebuff2Border	table	framexml
+PetFrameDebuff2Icon	table	framexml
+PetFrameDebuff3	table	framexml
+PetFrameDebuff3Border	table	framexml
+PetFrameDebuff3Icon	table	framexml
+PetFrameDebuff4	table	framexml
+PetFrameDebuff4Border	table	framexml
+PetFrameDebuff4Icon	table	framexml
+PetFrameDropDown	table	framexml
+PetFrameDropDownButton	table	framexml
+PetFrameDropDownButtonDisabledTexture	table	framexml
+PetFrameDropDownButtonHighlightTexture	table	framexml
+PetFrameDropDownButtonNormalTexture	table	framexml
+PetFrameDropDownButtonPushedTexture	table	framexml
+PetFrameDropDownLeft	table	framexml
+PetFrameDropDownMiddle	table	framexml
+PetFrameDropDownRight	table	framexml
+PetFrameDropDownText	table	framexml
+PetFrameDropDown_Initialize	function	framexml
+PetFrameDropDown_OnLoad	function	framexml
+PetFrameHappiness	table	framexml
+PetFrameHappinessTexture	table	framexml
+PetFrameHealthBar	table	framexml
+PetFrameHealthBarText	table	framexml
+PetFrameManaBar	table	framexml
+PetFrameManaBarText	table	framexml
+PetFrameTexture	table	framexml
+PetFrame_OnClick	function	framexml
+PetFrame_OnEvent	function	framexml
+PetFrame_OnLoad	function	framexml
+PetFrame_OnUpdate	function	framexml
+PetFrame_SetHappiness	function	framexml
+PetFrame_Update	function	framexml
+PetHasActionBar	function	engine
+PetHitIndicator	table	framexml
+PetLevelText	table	framexml
+PetLoyaltyText	table	framexml
+PetMagicResFrame1	table	framexml
+PetMagicResFrame2	table	framexml
+PetMagicResFrame3	table	framexml
+PetMagicResFrame4	table	framexml
+PetMagicResFrame5	table	framexml
+PetMagicResText1	table	framexml
+PetMagicResText2	table	framexml
+PetMagicResText3	table	framexml
+PetMagicResText4	table	framexml
+PetMagicResText5	table	framexml
+PetModelFrame	table	framexml
+PetModelFrameRotateLeftButton	table	framexml
+PetModelFrameRotateRightButton	table	framexml
+PetName	table	framexml
+PetNameText	table	framexml
+PetPaperDollCloseButton	table	framexml
+PetPaperDollCloseButtonText	table	framexml
+PetPaperDollFrame	table	framexml
+PetPaperDollFrameExpBar	table	framexml
+PetPaperDollFrameExpBarText	table	framexml
+PetPaperDollFrame_OnEvent	function	framexml
+PetPaperDollFrame_OnHide	function	framexml
+PetPaperDollFrame_OnLoad	function	framexml
+PetPaperDollFrame_OnShow	function	framexml
+PetPaperDollFrame_SetResistances	function	framexml
+PetPaperDollFrame_SetStats	function	framexml
+PetPaperDollFrame_Update	function	framexml
+PetPaperDollPetInfo	table	framexml
+PetPaperDollXPBar1	table	framexml
+PetPassiveMode	function	engine
+PetPortrait	table	framexml
+PetRename	function	engine
+PetResistanceFrame	table	framexml
+PetStableCostLabel	table	framexml
+PetStableCostMoneyFrame	table	framexml
+PetStableCostMoneyFrameCopperButton	table	framexml
+PetStableCostMoneyFrameCopperButtonText	table	framexml
+PetStableCostMoneyFrameGoldButton	table	framexml
+PetStableCostMoneyFrameGoldButtonText	table	framexml
+PetStableCostMoneyFrameSilverButton	table	framexml
+PetStableCostMoneyFrameSilverButtonText	table	framexml
+PetStableCurrentPet	table	framexml
+PetStableCurrentPetBackground	table	framexml
+PetStableCurrentPetIconTexture	table	framexml
+PetStableCurrentPetNormalTexture	table	framexml
+PetStableFrame	table	framexml
+PetStableFrameBottomLeft	table	framexml
+PetStableFrameBottomRight	table	framexml
+PetStableFrameCloseButton	table	framexml
+PetStableFramePortrait	table	framexml
+PetStableLevelText	table	framexml
+PetStableLoyaltyText	table	framexml
+PetStableModel	table	framexml
+PetStableModelRotateLeftButton	table	framexml
+PetStableModelRotateRightButton	table	framexml
+PetStableMoneyFrame	table	framexml
+PetStableMoneyFrameCopperButton	table	framexml
+PetStableMoneyFrameCopperButtonText	table	framexml
+PetStableMoneyFrameGoldButton	table	framexml
+PetStableMoneyFrameGoldButtonText	table	framexml
+PetStableMoneyFrameSilverButton	table	framexml
+PetStableMoneyFrameSilverButtonText	table	framexml
+PetStablePetInfo	table	framexml
+PetStablePurchaseButton	table	framexml
+PetStablePurchaseButtonText	table	framexml
+PetStableSlotTemplate	lod	framexml
+PetStableSlotText	table	framexml
+PetStableStabledPet1	table	framexml
+PetStableStabledPet1Background	table	framexml
+PetStableStabledPet1IconTexture	table	framexml
+PetStableStabledPet1NormalTexture	table	framexml
+PetStableStabledPet2	table	framexml
+PetStableStabledPet2Background	table	framexml
+PetStableStabledPet2IconTexture	table	framexml
+PetStableStabledPet2NormalTexture	table	framexml
+PetStableTitleLabel	table	framexml
+PetStable_NoPetsAllowed	function	framexml
+PetStable_OnEvent	function	framexml
+PetStable_OnLoad	function	framexml
+PetStable_Update	function	framexml
+PetStatFrame1	table	framexml
+PetStatFrame1Label	table	framexml
+PetStatFrame1Stat	table	framexml
+PetStatFrame1StatText	table	framexml
+PetStatFrame2	table	framexml
+PetStatFrame2Label	table	framexml
+PetStatFrame2Stat	table	framexml
+PetStatFrame2StatText	table	framexml
+PetStatFrame3	table	framexml
+PetStatFrame3Label	table	framexml
+PetStatFrame3Stat	table	framexml
+PetStatFrame3StatText	table	framexml
+PetStatFrame4	table	framexml
+PetStatFrame4Label	table	framexml
+PetStatFrame4Stat	table	framexml
+PetStatFrame4StatText	table	framexml
+PetStatFrame5	table	framexml
+PetStatFrame5Label	table	framexml
+PetStatFrame5Stat	table	framexml
+PetStatFrame5StatText	table	framexml
+PetStopAttack	function	engine
+PetTab_Update	function	framexml
+PetTrainingPointLabel	table	framexml
+PetTrainingPointText	table	framexml
+PetWait	function	engine
+PetitionFrame	table	framexml
+PetitionFrameCancelButton	table	framexml
+PetitionFrameCancelButtonText	table	framexml
+PetitionFrameCharterName	table	framexml
+PetitionFrameCharterTitle	table	framexml
+PetitionFrameCloseButton	table	framexml
+PetitionFrameInstructions	table	framexml
+PetitionFrameMasterName	table	framexml
+PetitionFrameMasterTitle	table	framexml
+PetitionFrameMemberName1	table	framexml
+PetitionFrameMemberName2	table	framexml
+PetitionFrameMemberName3	table	framexml
+PetitionFrameMemberName4	table	framexml
+PetitionFrameMemberName5	table	framexml
+PetitionFrameMemberName6	table	framexml
+PetitionFrameMemberName7	table	framexml
+PetitionFrameMemberName8	table	framexml
+PetitionFrameMemberName9	table	framexml
+PetitionFrameMemberTitle	table	framexml
+PetitionFrameNpcNameText	table	framexml
+PetitionFramePortrait	table	framexml
+PetitionFrameRenameButton	table	framexml
+PetitionFrameRenameButtonText	table	framexml
+PetitionFrameRequestButton	table	framexml
+PetitionFrameRequestButtonText	table	framexml
+PetitionFrameSignButton	table	framexml
+PetitionFrameSignButtonText	table	framexml
+PetitionFrame_Update	function	framexml
+PetitionNpcNameFrame	table	framexml
+PetitionText	table	framexml
+PhysicalAbuseTip1	table	framexml
+PhysicalAbuseTip1Text	table	framexml
+PhysicalAbuseTip2	table	framexml
+PhysicalAbuseTip2Text	table	framexml
+PhysicalAbuseTip3	table	framexml
+PhysicalAbuseTip3Text	table	framexml
+PhysicalAbuseTip4	table	framexml
+PhysicalAbuseTip4Text	table	framexml
+PhysicalAbuseTip5	table	framexml
+PhysicalAbuseTip5Text	table	framexml
+PickupAction	function	engine
+PickupBagFromSlot	function	engine
+PickupContainerItem	function	engine
+PickupFunc	lod	framexml
+PickupInventoryItem	function	engine
+PickupMacro	function	engine
+PickupMerchantItem	function	engine
+PickupPetAction	function	engine
+PickupPlayerMoney	function	engine
+PickupSpell	function	engine
+PickupStablePet	function	engine
+PickupTradeMoney	function	engine
+PitchDownStart	function	engine
+PitchDownStop	function	engine
+PitchUpStart	function	engine
+PitchUpStop	function	engine
+PlaceAction	function	engine
+PlaceAuctionBid	function	engine
+PlayClickSound	function	framexml
+PlayMusic	function	engine
+PlaySound	function	engine
+PlaySoundFile	function	engine
+PlayerAttackBackground	table	framexml
+PlayerAttackGlow	table	framexml
+PlayerAttackIcon	table	framexml
+PlayerFrame	table	framexml
+PlayerFrameBackground	table	framexml
+PlayerFrameDropDown	table	framexml
+PlayerFrameDropDownButton	table	framexml
+PlayerFrameDropDownButtonDisabledTexture	table	framexml
+PlayerFrameDropDownButtonHighlightTexture	table	framexml
+PlayerFrameDropDownButtonNormalTexture	table	framexml
+PlayerFrameDropDownButtonPushedTexture	table	framexml
+PlayerFrameDropDownLeft	table	framexml
+PlayerFrameDropDownMiddle	table	framexml
+PlayerFrameDropDownRight	table	framexml
+PlayerFrameDropDownText	table	framexml
+PlayerFrameDropDown_Initialize	function	framexml
+PlayerFrameDropDown_OnLoad	function	framexml
+PlayerFrameGroupIndicator	table	framexml
+PlayerFrameGroupIndicatorLeft	table	framexml
+PlayerFrameGroupIndicatorMiddle	table	framexml
+PlayerFrameGroupIndicatorRight	table	framexml
+PlayerFrameGroupIndicatorText	table	framexml
+PlayerFrameHealthBar	table	framexml
+PlayerFrameHealthBarText	table	framexml
+PlayerFrameManaBar	table	framexml
+PlayerFrameManaBarText	table	framexml
+PlayerFrameTexture	table	framexml
+PlayerFrame_OnClick	function	framexml
+PlayerFrame_OnEvent	function	framexml
+PlayerFrame_OnLoad	function	framexml
+PlayerFrame_OnReceiveDrag	function	framexml
+PlayerFrame_OnUpdate	function	framexml
+PlayerFrame_Update	function	framexml
+PlayerFrame_UpdateGroupIndicator	function	framexml
+PlayerFrame_UpdatePartyLeader	function	framexml
+PlayerFrame_UpdatePlaytime	function	framexml
+PlayerFrame_UpdatePvPStatus	function	framexml
+PlayerFrame_UpdateStatus	function	framexml
+PlayerHasSpells	function	engine
+PlayerHitIndicator	table	framexml
+PlayerLeaderIcon	table	framexml
+PlayerLevelText	table	framexml
+PlayerMasterIcon	table	framexml
+PlayerName	table	framexml
+PlayerPVPIcon	table	framexml
+PlayerPVPIconHitArea	table	framexml
+PlayerPlayTime	table	framexml
+PlayerPlayTimeIcon	table	framexml
+PlayerPortrait	table	framexml
+PlayerRestGlow	table	framexml
+PlayerRestIcon	table	framexml
+PlayerStatBackgroundBottom	table	framexml
+PlayerStatBackgroundMiddle	table	framexml
+PlayerStatBackgroundTop	table	framexml
+PlayerStatusGlow	table	framexml
+PlayerStatusTexture	table	framexml
+PlayerStatus_OnUpdate	function	framexml
+PlayerTradeItemTemplate	lod	framexml
+PositionMiniWorldMapArrowFrame	function	engine
+PositionWorldMapArrowFrame	function	engine
+PrevPageButton_OnClick	function	framexml
+PrevView	function	engine
+ProcessMapClick	function	engine
+PromoteByName	function	engine
+PromoteToAssistant	function	engine
+PromoteToPartyLeader	function	engine
+PurchaseSlot	function	engine
+PutItemInBackpack	function	engine
+PutItemInBag	function	engine
+PutKeyInKeyRing	function	framexml
+QUALITY	string	framexml
+QUESTINFO_FADE_IN	number	framexml
+QUESTLOG_BUTTON	string	framexml
+QUESTLOG_NO_QUESTS_TEXT	string	framexml
+QUESTLOG_QUEST_HEIGHT	number	framexml
+QUESTS_COLON	string	framexml
+QUESTS_DISPLAYED	number	framexml
+QUEST_ACCEPT	string	framexml
+QUEST_COMPLETE	string	framexml
+QUEST_DESCRIPTION	string	framexml
+QUEST_DESCRIPTION_GRADIENT_CPS	number	framexml
+QUEST_DESCRIPTION_GRADIENT_LENGTH	number	framexml
+QUEST_FACTION_NEEDED	string	framexml
+QUEST_FADING_DISABLE	string	framexml
+QUEST_FAILED	string	framexml
+QUEST_FAILED_TAG	string	framexml
+QUEST_HARD	string	framexml
+QUEST_ITEMS_NEEDED	string	framexml
+QUEST_LOG	string	framexml
+QUEST_LOG_COUNT_TEMPLATE	string	framexml
+QUEST_MONSTERS_KILLED	string	framexml
+QUEST_OBJECTIVES	string	framexml
+QUEST_OBJECTS_FOUND	string	framexml
+QUEST_REWARDS	string	framexml
+QUEST_TIMERS	string	framexml
+QUEST_WATCH_LIST	table	framexml
+QUEST_WATCH_NO_EXPIRE	number	framexml
+QUEST_WATCH_NO_OBJECTIVES	string	framexml
+QUEST_WATCH_TOOLTIP	string	framexml
+QUEST_WATCH_TOO_MANY	string	framexml
+QUEUE_TIME_UNAVAILABLE	string	framexml
+QUIT	string	framexml
+QUIT_NOW	string	framexml
+QUIT_TIMER	string	framexml
+QueryAuctionItems	function	engine
+QuestChooseRewardError	function	engine
+QuestDescription	table	framexml
+QuestDetailAcceptButton_OnClick	function	framexml
+QuestDetailDeclineButton_OnClick	function	framexml
+QuestDetailItem1	table	framexml
+QuestDetailItem10	table	framexml
+QuestDetailItem10Count	table	framexml
+QuestDetailItem10IconTexture	table	framexml
+QuestDetailItem10Name	table	framexml
+QuestDetailItem10NameFrame	table	framexml
+QuestDetailItem1Count	table	framexml
+QuestDetailItem1IconTexture	table	framexml
+QuestDetailItem1Name	table	framexml
+QuestDetailItem1NameFrame	table	framexml
+QuestDetailItem2	table	framexml
+QuestDetailItem2Count	table	framexml
+QuestDetailItem2IconTexture	table	framexml
+QuestDetailItem2Name	table	framexml
+QuestDetailItem2NameFrame	table	framexml
+QuestDetailItem3	table	framexml
+QuestDetailItem3Count	table	framexml
+QuestDetailItem3IconTexture	table	framexml
+QuestDetailItem3Name	table	framexml
+QuestDetailItem3NameFrame	table	framexml
+QuestDetailItem4	table	framexml
+QuestDetailItem4Count	table	framexml
+QuestDetailItem4IconTexture	table	framexml
+QuestDetailItem4Name	table	framexml
+QuestDetailItem4NameFrame	table	framexml
+QuestDetailItem5	table	framexml
+QuestDetailItem5Count	table	framexml
+QuestDetailItem5IconTexture	table	framexml
+QuestDetailItem5Name	table	framexml
+QuestDetailItem5NameFrame	table	framexml
+QuestDetailItem6	table	framexml
+QuestDetailItem6Count	table	framexml
+QuestDetailItem6IconTexture	table	framexml
+QuestDetailItem6Name	table	framexml
+QuestDetailItem6NameFrame	table	framexml
+QuestDetailItem7	table	framexml
+QuestDetailItem7Count	table	framexml
+QuestDetailItem7IconTexture	table	framexml
+QuestDetailItem7Name	table	framexml
+QuestDetailItem7NameFrame	table	framexml
+QuestDetailItem8	table	framexml
+QuestDetailItem8Count	table	framexml
+QuestDetailItem8IconTexture	table	framexml
+QuestDetailItem8Name	table	framexml
+QuestDetailItem8NameFrame	table	framexml
+QuestDetailItem9	table	framexml
+QuestDetailItem9Count	table	framexml
+QuestDetailItem9IconTexture	table	framexml
+QuestDetailItem9Name	table	framexml
+QuestDetailItem9NameFrame	table	framexml
+QuestDetailItemChooseText	table	framexml
+QuestDetailItemReceiveText	table	framexml
+QuestDetailMoneyFrame	table	framexml
+QuestDetailMoneyFrameCopperButton	table	framexml
+QuestDetailMoneyFrameCopperButtonText	table	framexml
+QuestDetailMoneyFrameGoldButton	table	framexml
+QuestDetailMoneyFrameGoldButtonText	table	framexml
+QuestDetailMoneyFrameSilverButton	table	framexml
+QuestDetailMoneyFrameSilverButtonText	table	framexml
+QuestDetailObjectiveTitleText	table	framexml
+QuestDetailRewardTitleText	table	framexml
+QuestDetailScrollChildFrame	table	framexml
+QuestDetailScrollFrame	table	framexml
+QuestDetailScrollFrameScrollBar	table	framexml
+QuestDetailScrollFrameScrollBarScrollDownButton	table	framexml
+QuestDetailScrollFrameScrollBarScrollUpButton	table	framexml
+QuestDetailScrollFrameScrollBarThumbTexture	table	framexml
+QuestDetailSpellLearnText	table	framexml
+QuestDifficultyColor	table	framexml
+QuestFont	table	framexml
+QuestFontHighlight	table	framexml
+QuestFontNormalSmall	table	framexml
+QuestFrame	table	framexml
+QuestFrameAcceptButton	table	framexml
+QuestFrameAcceptButtonText	table	framexml
+QuestFrameCancelButton	table	framexml
+QuestFrameCancelButtonText	table	framexml
+QuestFrameCloseButton	table	framexml
+QuestFrameCompleteButton	table	framexml
+QuestFrameCompleteButtonText	table	framexml
+QuestFrameCompleteQuestButton	table	framexml
+QuestFrameCompleteQuestButtonText	table	framexml
+QuestFrameDeclineButton	table	framexml
+QuestFrameDeclineButtonText	table	framexml
+QuestFrameDetailPanel	table	framexml
+QuestFrameDetailPanelMaterialBotLeft	table	framexml
+QuestFrameDetailPanelMaterialBotRight	table	framexml
+QuestFrameDetailPanelMaterialTopLeft	table	framexml
+QuestFrameDetailPanelMaterialTopRight	table	framexml
+QuestFrameDetailPanel_OnShow	function	framexml
+QuestFrameDetailPanel_OnUpdate	function	framexml
+QuestFrameExitButton	table	framexml
+QuestFrameExitButtonText	table	framexml
+QuestFrameGoodbyeButton	table	framexml
+QuestFrameGoodbyeButtonText	table	framexml
+QuestFrameGreetingGoodbyeButton	table	framexml
+QuestFrameGreetingGoodbyeButtonText	table	framexml
+QuestFrameGreetingPanel	table	framexml
+QuestFrameGreetingPanelMaterialBotLeft	table	framexml
+QuestFrameGreetingPanelMaterialBotRight	table	framexml
+QuestFrameGreetingPanelMaterialTopLeft	table	framexml
+QuestFrameGreetingPanelMaterialTopRight	table	framexml
+QuestFrameGreetingPanel_OnShow	function	framexml
+QuestFrameItems_Update	function	framexml
+QuestFrameNpcNameText	table	framexml
+QuestFramePanelTemplate	lod	framexml
+QuestFramePortrait	table	framexml
+QuestFrameProgressItems_Update	function	framexml
+QuestFrameProgressPanel	table	framexml
+QuestFrameProgressPanelMaterialBotLeft	table	framexml
+QuestFrameProgressPanelMaterialBotRight	table	framexml
+QuestFrameProgressPanelMaterialTopLeft	table	framexml
+QuestFrameProgressPanelMaterialTopRight	table	framexml
+QuestFrameProgressPanel_OnShow	function	framexml
+QuestFramePushQuestButton	table	framexml
+QuestFramePushQuestButtonText	table	framexml
+QuestFrameRewardPanel	table	framexml
+QuestFrameRewardPanelMaterialBotLeft	table	framexml
+QuestFrameRewardPanelMaterialBotRight	table	framexml
+QuestFrameRewardPanelMaterialTopLeft	table	framexml
+QuestFrameRewardPanelMaterialTopRight	table	framexml
+QuestFrameRewardPanel_OnShow	function	framexml
+QuestFrame_GetMaterial	function	framexml
+QuestFrame_OnEvent	function	framexml
+QuestFrame_OnHide	function	framexml
+QuestFrame_OnLoad	function	framexml
+QuestFrame_OnShow	function	framexml
+QuestFrame_SetAsLastShown	function	framexml
+QuestFrame_SetMaterial	function	framexml
+QuestFrame_SetPortrait	function	framexml
+QuestFrame_SetTextColor	function	framexml
+QuestFrame_SetTitleTextColor	function	framexml
+QuestGoodbyeButton_OnClick	function	framexml
+QuestGreetingFrameHorizontalBreak	table	framexml
+QuestGreetingScrollChildFrame	table	framexml
+QuestGreetingScrollFrame	table	framexml
+QuestGreetingScrollFrameScrollBar	table	framexml
+QuestGreetingScrollFrameScrollBarScrollDownButton	table	framexml
+QuestGreetingScrollFrameScrollBarScrollUpButton	table	framexml
+QuestGreetingScrollFrameScrollBarThumbTexture	table	framexml
+QuestItemTemplate	lod	framexml
+QuestItem_OnClick	function	framexml
+QuestLogCollapseAllButton	table	framexml
+QuestLogCollapseAllButtonCheck	table	framexml
+QuestLogCollapseAllButtonGroupMates	table	framexml
+QuestLogCollapseAllButtonHighlight	table	framexml
+QuestLogCollapseAllButtonNormalText	table	framexml
+QuestLogCollapseAllButtonTag	table	framexml
+QuestLogCollapseAllButton_OnClick	function	framexml
+QuestLogCountLeft	table	framexml
+QuestLogCountMiddle	table	framexml
+QuestLogCountRight	table	framexml
+QuestLogDescriptionTitle	table	framexml
+QuestLogDetailScrollChildFrame	table	framexml
+QuestLogDetailScrollFrame	table	framexml
+QuestLogDetailScrollFrameScrollBar	table	framexml
+QuestLogDetailScrollFrameScrollBarScrollDownButton	table	framexml
+QuestLogDetailScrollFrameScrollBarScrollUpButton	table	framexml
+QuestLogDetailScrollFrameScrollBarThumbTexture	table	framexml
+QuestLogDummyText	table	framexml
+QuestLogExpandButtonFrame	table	framexml
+QuestLogExpandTabLeft	table	framexml
+QuestLogExpandTabMiddle	table	framexml
+QuestLogFrame	table	framexml
+QuestLogFrameAbandonButton	table	framexml
+QuestLogFrameAbandonButtonText	table	framexml
+QuestLogFrameCloseButton	table	framexml
+QuestLogHighlightFrame	table	framexml
+QuestLogItem1	table	framexml
+QuestLogItem10	table	framexml
+QuestLogItem10Count	table	framexml
+QuestLogItem10IconTexture	table	framexml
+QuestLogItem10Name	table	framexml
+QuestLogItem10NameFrame	table	framexml
+QuestLogItem1Count	table	framexml
+QuestLogItem1IconTexture	table	framexml
+QuestLogItem1Name	table	framexml
+QuestLogItem1NameFrame	table	framexml
+QuestLogItem2	table	framexml
+QuestLogItem2Count	table	framexml
+QuestLogItem2IconTexture	table	framexml
+QuestLogItem2Name	table	framexml
+QuestLogItem2NameFrame	table	framexml
+QuestLogItem3	table	framexml
+QuestLogItem3Count	table	framexml
+QuestLogItem3IconTexture	table	framexml
+QuestLogItem3Name	table	framexml
+QuestLogItem3NameFrame	table	framexml
+QuestLogItem4	table	framexml
+QuestLogItem4Count	table	framexml
+QuestLogItem4IconTexture	table	framexml
+QuestLogItem4Name	table	framexml
+QuestLogItem4NameFrame	table	framexml
+QuestLogItem5	table	framexml
+QuestLogItem5Count	table	framexml
+QuestLogItem5IconTexture	table	framexml
+QuestLogItem5Name	table	framexml
+QuestLogItem5NameFrame	table	framexml
+QuestLogItem6	table	framexml
+QuestLogItem6Count	table	framexml
+QuestLogItem6IconTexture	table	framexml
+QuestLogItem6Name	table	framexml
+QuestLogItem6NameFrame	table	framexml
+QuestLogItem7	table	framexml
+QuestLogItem7Count	table	framexml
+QuestLogItem7IconTexture	table	framexml
+QuestLogItem7Name	table	framexml
+QuestLogItem7NameFrame	table	framexml
+QuestLogItem8	table	framexml
+QuestLogItem8Count	table	framexml
+QuestLogItem8IconTexture	table	framexml
+QuestLogItem8Name	table	framexml
+QuestLogItem8NameFrame	table	framexml
+QuestLogItem9	table	framexml
+QuestLogItem9Count	table	framexml
+QuestLogItem9IconTexture	table	framexml
+QuestLogItem9Name	table	framexml
+QuestLogItem9NameFrame	table	framexml
+QuestLogItemChooseText	table	framexml
+QuestLogItemReceiveText	table	framexml
+QuestLogListScrollFrame	table	framexml
+QuestLogListScrollFrameScrollBar	table	framexml
+QuestLogListScrollFrameScrollBarScrollDownButton	table	framexml
+QuestLogListScrollFrameScrollBarScrollUpButton	table	framexml
+QuestLogListScrollFrameScrollBarThumbTexture	table	framexml
+QuestLogListScrollFrameScrollChildFrame	table	framexml
+QuestLogMicroButton	table	framexml
+QuestLogMoneyFrame	table	framexml
+QuestLogMoneyFrameCopperButton	table	framexml
+QuestLogMoneyFrameCopperButtonText	table	framexml
+QuestLogMoneyFrameGoldButton	table	framexml
+QuestLogMoneyFrameGoldButtonText	table	framexml
+QuestLogMoneyFrameSilverButton	table	framexml
+QuestLogMoneyFrameSilverButtonText	table	framexml
+QuestLogNoQuestsText	table	framexml
+QuestLogObjective1	table	framexml
+QuestLogObjective10	table	framexml
+QuestLogObjective2	table	framexml
+QuestLogObjective3	table	framexml
+QuestLogObjective4	table	framexml
+QuestLogObjective5	table	framexml
+QuestLogObjective6	table	framexml
+QuestLogObjective7	table	framexml
+QuestLogObjective8	table	framexml
+QuestLogObjective9	table	framexml
+QuestLogObjectivesText	table	framexml
+QuestLogPushQuest	function	engine
+QuestLogQuestCount	table	framexml
+QuestLogQuestDescription	table	framexml
+QuestLogQuestTitle	table	framexml
+QuestLogRequiredMoneyFrame	table	framexml
+QuestLogRequiredMoneyFrameCopperButton	table	framexml
+QuestLogRequiredMoneyFrameCopperButtonText	table	framexml
+QuestLogRequiredMoneyFrameGoldButton	table	framexml
+QuestLogRequiredMoneyFrameGoldButtonText	table	framexml
+QuestLogRequiredMoneyFrameSilverButton	table	framexml
+QuestLogRequiredMoneyFrameSilverButtonText	table	framexml
+QuestLogRequiredMoneyText	table	framexml
+QuestLogRewardItemTemplate	lod	framexml
+QuestLogRewardItem_OnClick	function	framexml
+QuestLogRewardTitleText	table	framexml
+QuestLogSkillHighlight	table	framexml
+QuestLogSpacerFrame	table	framexml
+QuestLogSpellLearnText	table	framexml
+QuestLogTimerText	table	framexml
+QuestLogTitle1	table	framexml
+QuestLogTitle1Check	table	framexml
+QuestLogTitle1GroupMates	table	framexml
+QuestLogTitle1Highlight	table	framexml
+QuestLogTitle1NormalText	table	framexml
+QuestLogTitle1Tag	table	framexml
+QuestLogTitle2	table	framexml
+QuestLogTitle2Check	table	framexml
+QuestLogTitle2GroupMates	table	framexml
+QuestLogTitle2Highlight	table	framexml
+QuestLogTitle2NormalText	table	framexml
+QuestLogTitle2Tag	table	framexml
+QuestLogTitle3	table	framexml
+QuestLogTitle3Check	table	framexml
+QuestLogTitle3GroupMates	table	framexml
+QuestLogTitle3Highlight	table	framexml
+QuestLogTitle3NormalText	table	framexml
+QuestLogTitle3Tag	table	framexml
+QuestLogTitle4	table	framexml
+QuestLogTitle4Check	table	framexml
+QuestLogTitle4GroupMates	table	framexml
+QuestLogTitle4Highlight	table	framexml
+QuestLogTitle4NormalText	table	framexml
+QuestLogTitle4Tag	table	framexml
+QuestLogTitle5	table	framexml
+QuestLogTitle5Check	table	framexml
+QuestLogTitle5GroupMates	table	framexml
+QuestLogTitle5Highlight	table	framexml
+QuestLogTitle5NormalText	table	framexml
+QuestLogTitle5Tag	table	framexml
+QuestLogTitle6	table	framexml
+QuestLogTitle6Check	table	framexml
+QuestLogTitle6GroupMates	table	framexml
+QuestLogTitle6Highlight	table	framexml
+QuestLogTitle6NormalText	table	framexml
+QuestLogTitle6Tag	table	framexml
+QuestLogTitleButtonTemplate	lod	framexml
+QuestLogTitleButton_OnClick	function	framexml
+QuestLogTitleButton_OnEnter	function	framexml
+QuestLogTitleButton_OnEvent	function	framexml
+QuestLogTitleButton_OnLoad	function	framexml
+QuestLogTitleText	table	framexml
+QuestLogTrack	table	framexml
+QuestLogTrackTitle	table	framexml
+QuestLogTrackTracking	table	framexml
+QuestLog_GetFirstSelectableQuest	function	framexml
+QuestLog_OnEvent	function	framexml
+QuestLog_OnHide	function	framexml
+QuestLog_OnLoad	function	framexml
+QuestLog_OnShow	function	framexml
+QuestLog_OnUpdate	function	framexml
+QuestLog_SetFirstValidSelection	function	framexml
+QuestLog_SetSelection	function	framexml
+QuestLog_Update	function	framexml
+QuestLog_UpdatePartyInfoTooltip	function	framexml
+QuestLog_UpdateQuestDetails	function	framexml
+QuestMoneyFrame_OnLoad	function	framexml
+QuestNpcNameFrame	table	framexml
+QuestObjectiveText	table	framexml
+QuestProgressCompleteButton_OnClick	function	framexml
+QuestProgressItem1	table	framexml
+QuestProgressItem1Count	table	framexml
+QuestProgressItem1IconTexture	table	framexml
+QuestProgressItem1Name	table	framexml
+QuestProgressItem1NameFrame	table	framexml
+QuestProgressItem2	table	framexml
+QuestProgressItem2Count	table	framexml
+QuestProgressItem2IconTexture	table	framexml
+QuestProgressItem2Name	table	framexml
+QuestProgressItem2NameFrame	table	framexml
+QuestProgressItem3	table	framexml
+QuestProgressItem3Count	table	framexml
+QuestProgressItem3IconTexture	table	framexml
+QuestProgressItem3Name	table	framexml
+QuestProgressItem3NameFrame	table	framexml
+QuestProgressItem4	table	framexml
+QuestProgressItem4Count	table	framexml
+QuestProgressItem4IconTexture	table	framexml
+QuestProgressItem4Name	table	framexml
+QuestProgressItem4NameFrame	table	framexml
+QuestProgressItem5	table	framexml
+QuestProgressItem5Count	table	framexml
+QuestProgressItem5IconTexture	table	framexml
+QuestProgressItem5Name	table	framexml
+QuestProgressItem5NameFrame	table	framexml
+QuestProgressItem6	table	framexml
+QuestProgressItem6Count	table	framexml
+QuestProgressItem6IconTexture	table	framexml
+QuestProgressItem6Name	table	framexml
+QuestProgressItem6NameFrame	table	framexml
+QuestProgressRequiredItemsText	table	framexml
+QuestProgressRequiredMoneyFrame	table	framexml
+QuestProgressRequiredMoneyFrameCopperButton	table	framexml
+QuestProgressRequiredMoneyFrameCopperButtonText	table	framexml
+QuestProgressRequiredMoneyFrameGoldButton	table	framexml
+QuestProgressRequiredMoneyFrameGoldButtonText	table	framexml
+QuestProgressRequiredMoneyFrameSilverButton	table	framexml
+QuestProgressRequiredMoneyFrameSilverButtonText	table	framexml
+QuestProgressRequiredMoneyText	table	framexml
+QuestProgressScrollChildFrame	table	framexml
+QuestProgressScrollFrame	table	framexml
+QuestProgressScrollFrameScrollBar	table	framexml
+QuestProgressScrollFrameScrollBarScrollDownButton	table	framexml
+QuestProgressScrollFrameScrollBarScrollUpButton	table	framexml
+QuestProgressScrollFrameScrollBarThumbTexture	table	framexml
+QuestProgressText	table	framexml
+QuestProgressTitleText	table	framexml
+QuestRewardCancelButton_OnClick	function	framexml
+QuestRewardCompleteButton_OnClick	function	framexml
+QuestRewardItem1	table	framexml
+QuestRewardItem10	table	framexml
+QuestRewardItem10Count	table	framexml
+QuestRewardItem10IconTexture	table	framexml
+QuestRewardItem10Name	table	framexml
+QuestRewardItem10NameFrame	table	framexml
+QuestRewardItem1Count	table	framexml
+QuestRewardItem1IconTexture	table	framexml
+QuestRewardItem1Name	table	framexml
+QuestRewardItem1NameFrame	table	framexml
+QuestRewardItem2	table	framexml
+QuestRewardItem2Count	table	framexml
+QuestRewardItem2IconTexture	table	framexml
+QuestRewardItem2Name	table	framexml
+QuestRewardItem2NameFrame	table	framexml
+QuestRewardItem3	table	framexml
+QuestRewardItem3Count	table	framexml
+QuestRewardItem3IconTexture	table	framexml
+QuestRewardItem3Name	table	framexml
+QuestRewardItem3NameFrame	table	framexml
+QuestRewardItem4	table	framexml
+QuestRewardItem4Count	table	framexml
+QuestRewardItem4IconTexture	table	framexml
+QuestRewardItem4Name	table	framexml
+QuestRewardItem4NameFrame	table	framexml
+QuestRewardItem5	table	framexml
+QuestRewardItem5Count	table	framexml
+QuestRewardItem5IconTexture	table	framexml
+QuestRewardItem5Name	table	framexml
+QuestRewardItem5NameFrame	table	framexml
+QuestRewardItem6	table	framexml
+QuestRewardItem6Count	table	framexml
+QuestRewardItem6IconTexture	table	framexml
+QuestRewardItem6Name	table	framexml
+QuestRewardItem6NameFrame	table	framexml
+QuestRewardItem7	table	framexml
+QuestRewardItem7Count	table	framexml
+QuestRewardItem7IconTexture	table	framexml
+QuestRewardItem7Name	table	framexml
+QuestRewardItem7NameFrame	table	framexml
+QuestRewardItem8	table	framexml
+QuestRewardItem8Count	table	framexml
+QuestRewardItem8IconTexture	table	framexml
+QuestRewardItem8Name	table	framexml
+QuestRewardItem8NameFrame	table	framexml
+QuestRewardItem9	table	framexml
+QuestRewardItem9Count	table	framexml
+QuestRewardItem9IconTexture	table	framexml
+QuestRewardItem9Name	table	framexml
+QuestRewardItem9NameFrame	table	framexml
+QuestRewardItemChooseText	table	framexml
+QuestRewardItemHighlight	table	framexml
+QuestRewardItemReceiveText	table	framexml
+QuestRewardItemTemplate	lod	framexml
+QuestRewardItem_OnClick	function	framexml
+QuestRewardMoneyFrame	table	framexml
+QuestRewardMoneyFrameCopperButton	table	framexml
+QuestRewardMoneyFrameCopperButtonText	table	framexml
+QuestRewardMoneyFrameGoldButton	table	framexml
+QuestRewardMoneyFrameGoldButtonText	table	framexml
+QuestRewardMoneyFrameSilverButton	table	framexml
+QuestRewardMoneyFrameSilverButtonText	table	framexml
+QuestRewardRewardTitleText	table	framexml
+QuestRewardScrollChildFrame	table	framexml
+QuestRewardScrollFrame	table	framexml
+QuestRewardScrollFrameScrollBar	table	framexml
+QuestRewardScrollFrameScrollBarScrollDownButton	table	framexml
+QuestRewardScrollFrameScrollBarScrollUpButton	table	framexml
+QuestRewardScrollFrameScrollBarThumbTexture	table	framexml
+QuestRewardSpellLearnText	table	framexml
+QuestRewardText	table	framexml
+QuestRewardTitleText	table	framexml
+QuestSpacerFrame	table	framexml
+QuestTimer1	table	framexml
+QuestTimer10	table	framexml
+QuestTimer10Text	table	framexml
+QuestTimer11	table	framexml
+QuestTimer11Text	table	framexml
+QuestTimer12	table	framexml
+QuestTimer12Text	table	framexml
+QuestTimer13	table	framexml
+QuestTimer13Text	table	framexml
+QuestTimer14	table	framexml
+QuestTimer14Text	table	framexml
+QuestTimer15	table	framexml
+QuestTimer15Text	table	framexml
+QuestTimer16	table	framexml
+QuestTimer16Text	table	framexml
+QuestTimer17	table	framexml
+QuestTimer17Text	table	framexml
+QuestTimer18	table	framexml
+QuestTimer18Text	table	framexml
+QuestTimer19	table	framexml
+QuestTimer19Text	table	framexml
+QuestTimer1Text	table	framexml
+QuestTimer2	table	framexml
+QuestTimer20	table	framexml
+QuestTimer20Text	table	framexml
+QuestTimer2Text	table	framexml
+QuestTimer3	table	framexml
+QuestTimer3Text	table	framexml
+QuestTimer4	table	framexml
+QuestTimer4Text	table	framexml
+QuestTimer5	table	framexml
+QuestTimer5Text	table	framexml
+QuestTimer6	table	framexml
+QuestTimer6Text	table	framexml
+QuestTimer7	table	framexml
+QuestTimer7Text	table	framexml
+QuestTimer8	table	framexml
+QuestTimer8Text	table	framexml
+QuestTimer9	table	framexml
+QuestTimer9Text	table	framexml
+QuestTimerButton_OnClick	function	framexml
+QuestTimerFrame	table	framexml
+QuestTimerFrame_OnEvent	function	framexml
+QuestTimerFrame_OnHide	function	framexml
+QuestTimerFrame_OnLoad	function	framexml
+QuestTimerFrame_OnShow	function	framexml
+QuestTimerFrame_OnUpdate	function	framexml
+QuestTimerFrame_Update	function	framexml
+QuestTimerFrame_UpdatePosition	lod	framexml
+QuestTimerHeader	table	framexml
+QuestTimerTemplate	lod	framexml
+QuestTitleButton1	table	framexml
+QuestTitleButton10	table	framexml
+QuestTitleButton11	table	framexml
+QuestTitleButton12	table	framexml
+QuestTitleButton13	table	framexml
+QuestTitleButton14	table	framexml
+QuestTitleButton15	table	framexml
+QuestTitleButton16	table	framexml
+QuestTitleButton17	table	framexml
+QuestTitleButton18	table	framexml
+QuestTitleButton19	table	framexml
+QuestTitleButton2	table	framexml
+QuestTitleButton20	table	framexml
+QuestTitleButton21	table	framexml
+QuestTitleButton22	table	framexml
+QuestTitleButton23	table	framexml
+QuestTitleButton24	table	framexml
+QuestTitleButton25	table	framexml
+QuestTitleButton26	table	framexml
+QuestTitleButton27	table	framexml
+QuestTitleButton28	table	framexml
+QuestTitleButton29	table	framexml
+QuestTitleButton3	table	framexml
+QuestTitleButton30	table	framexml
+QuestTitleButton31	table	framexml
+QuestTitleButton32	table	framexml
+QuestTitleButton4	table	framexml
+QuestTitleButton5	table	framexml
+QuestTitleButton6	table	framexml
+QuestTitleButton7	table	framexml
+QuestTitleButton8	table	framexml
+QuestTitleButton9	table	framexml
+QuestTitleButtonTemplate	lod	framexml
+QuestTitleButton_OnClick	function	framexml
+QuestTitleFont	table	framexml
+QuestTitleText	table	framexml
+QuestWatchFontTemplate	lod	framexml
+QuestWatchFrame	table	framexml
+QuestWatchLine1	table	framexml
+QuestWatchLine10	table	framexml
+QuestWatchLine11	table	framexml
+QuestWatchLine12	table	framexml
+QuestWatchLine13	table	framexml
+QuestWatchLine14	table	framexml
+QuestWatchLine15	table	framexml
+QuestWatchLine16	table	framexml
+QuestWatchLine17	table	framexml
+QuestWatchLine18	table	framexml
+QuestWatchLine19	table	framexml
+QuestWatchLine2	table	framexml
+QuestWatchLine20	table	framexml
+QuestWatchLine21	table	framexml
+QuestWatchLine22	table	framexml
+QuestWatchLine23	table	framexml
+QuestWatchLine24	table	framexml
+QuestWatchLine25	table	framexml
+QuestWatchLine26	table	framexml
+QuestWatchLine27	table	framexml
+QuestWatchLine28	table	framexml
+QuestWatchLine29	table	framexml
+QuestWatchLine3	table	framexml
+QuestWatchLine30	table	framexml
+QuestWatchLine4	table	framexml
+QuestWatchLine5	table	framexml
+QuestWatchLine6	table	framexml
+QuestWatchLine7	table	framexml
+QuestWatchLine8	table	framexml
+QuestWatchLine9	table	framexml
+QuestWatchQuestName	table	framexml
+QuestWatch_Update	function	framexml
+Quit	function	engine
+RACE	string	framexml
+RACE_CLASS_ONLY	string	framexml
+RACIAL_SKILLS	string	framexml
+RAGE	string	framexml
+RAGE_COST	string	framexml
+RAGE_COST_PER_TIME	string	framexml
+RAGE_POINTS	string	framexml
+RAID	string	framexml
+RAIDOPTIONS_MENU	string	framexml
+RAID_AND_PARTY	string	framexml
+RAID_ASSISTANT_TOKEN	string	framexml
+RAID_BOSS_MESSAGE	string	framexml
+RAID_CLASS_COLORS	table	framexml
+RAID_CONTROL	string	framexml
+RAID_DESCRIPTION	string	framexml
+RAID_GROUPS	string	framexml
+RAID_INFO	string	framexml
+RAID_INFORMATION	string	framexml
+RAID_INFO_DESC	string	framexml
+RAID_INSTANCE_INFO_FMT	string	framexml
+RAID_INSTANCE_INFO_HDR	string	framexml
+RAID_INSTANCE_WARNING_HOURS	string	framexml
+RAID_INSTANCE_WARNING_HOURS_P1	string	framexml
+RAID_INSTANCE_WARNING_MIN	string	framexml
+RAID_INSTANCE_WARNING_MIN_P1	string	framexml
+RAID_INSTANCE_WARNING_MIN_SOON	string	framexml
+RAID_INSTANCE_WARNING_MIN_SOON_P1	string	framexml
+RAID_INSTANCE_WELCOME	string	framexml
+RAID_LEADER_TOKEN	string	framexml
+RAID_MEMBERS_AFK	string	framexml
+RAID_MEMBER_NOT_READY	string	framexml
+RAID_MESSAGE	string	framexml
+RAID_PULLOUT_BUTTON_HEIGHT	lod	framexml
+RAID_SUBGROUP_LISTS	lod	framexml
+RAID_TARGET_1	string	framexml
+RAID_TARGET_2	string	framexml
+RAID_TARGET_3	string	framexml
+RAID_TARGET_4	string	framexml
+RAID_TARGET_5	string	framexml
+RAID_TARGET_6	string	framexml
+RAID_TARGET_7	string	framexml
+RAID_TARGET_8	string	framexml
+RAID_TARGET_ICON	string	framexml
+RAID_TARGET_ICON_DIMENSION	number	framexml
+RAID_TARGET_TEXTURE_COLUMNS	number	framexml
+RAID_TARGET_TEXTURE_DIMENSION	number	framexml
+RAID_TARGET_TEXTURE_ROWS	number	framexml
+RAID_WARNING_MESSAGE	string	framexml
+RANDOM_ROLL_RESULT	string	framexml
+RANGEDSLOT	string	framexml
+RANGED_ATTACK	string	framexml
+RANGED_ATTACK_POWER	string	framexml
+RANGED_ATTACK_POWER_TOOLTIP	string	framexml
+RANGED_ATTACK_TOOLTIP	string	framexml
+RANGED_DAMAGE_TOOLTIP	string	framexml
+RANGE_INDICATOR	string	framexml
+RANK	string	framexml
+RANK_COLON	string	framexml
+RANK_POSITION	string	framexml
+RARITY	string	framexml
+READY_CHECK	string	framexml
+READY_CHECK_MESSAGE	string	framexml
+READY_CHECK_NO_AFK	string	framexml
+READY_CHECK_START	string	framexml
+READY_CHECK_YOU_WERE_AFK	string	framexml
+RECOVER_CORPSE	string	framexml
+RECOVER_CORPSE_INSTANCE	string	framexml
+RECOVER_CORPSE_TIMER	string	framexml
+RED_FONT_COLOR	table	framexml
+RED_FONT_COLOR_CODE	string	framexml
+REFLECT	string	framexml
+REFRESH	string	framexml
+REFRESH_RATE	string	framexml
+RELICSLOT	string	framexml
+REMOVE	string	framexml
+REMOVE_CHAT_DELAY	string	framexml
+REMOVE_CHAT_DELAY_TEXT	string	framexml
+REMOVE_FRIEND	string	framexml
+REMOVE_GUILDMEMBER_LABEL	string	framexml
+RENAME_CHAT_WINDOW	string	framexml
+RENAME_GUILD	string	framexml
+RENAME_GUILD_LABEL	string	framexml
+REPAIR_ALL_ITEMS	string	framexml
+REPAIR_AN_ITEM	string	framexml
+REPAIR_COST	string	framexml
+REPAIR_ITEMS	string	framexml
+REPLACE_ENCHANT	string	framexml
+REPLY_MESSAGE	string	framexml
+REPORT_PHYSICAL_HARASSMENT	string	framexml
+REPORT_VERBAL_HARASSMENT	string	framexml
+REPUTATION	string	framexml
+REPUTATIONFRAME_FACTIONHEIGHT	number	framexml
+REPUTATION_AT_WAR_DESCRIPTION	string	framexml
+REPUTATION_FACTION_DESCRIPTION	string	framexml
+REPUTATION_STANDING_DESCRIPTION	string	framexml
+REPUTATION_STATUS_AT_PEACE	string	framexml
+REPUTATION_STATUS_AT_WAR	string	framexml
+REPUTATION_STATUS_NOT_AT_PEACE	string	framexml
+REPUTATION_STATUS_PERMANENT_AT_PEACE	string	framexml
+REPUTATION_STATUS_PERMANENT_AT_WAR	string	framexml
+REQUEST_SIGNATURE	string	framexml
+REQUIRED_MONEY	string	framexml
+REQUIRED_REST_HOURS	number	framexml
+REQUIRES_LABEL	string	framexml
+RESET	string	framexml
+RESETS_IN	string	framexml
+RESET_INSTANCES	string	framexml
+RESET_TO_DEFAULT	string	framexml
+RESET_TUTORIALS	string	framexml
+RESIST	string	framexml
+RESISTANCE0_NAME	string	framexml
+RESISTANCE1_NAME	string	framexml
+RESISTANCE2_NAME	string	framexml
+RESISTANCE3_NAME	string	framexml
+RESISTANCE4_NAME	string	framexml
+RESISTANCE5_NAME	string	framexml
+RESISTANCE6_NAME	string	framexml
+RESISTANCE_EXCELLENT	string	framexml
+RESISTANCE_FAIR	string	framexml
+RESISTANCE_GOOD	string	framexml
+RESISTANCE_LABEL	string	framexml
+RESISTANCE_NONE	string	framexml
+RESISTANCE_POOR	string	framexml
+RESISTANCE_TEMPLATE	string	framexml
+RESISTANCE_TOOLTIP_SUBTEXT	string	framexml
+RESISTANCE_TYPE0	string	framexml
+RESISTANCE_TYPE1	string	framexml
+RESISTANCE_TYPE2	string	framexml
+RESISTANCE_TYPE3	string	framexml
+RESISTANCE_TYPE4	string	framexml
+RESISTANCE_TYPE5	string	framexml
+RESISTANCE_TYPE6	string	framexml
+RESISTANCE_VERYGOOD	string	framexml
+RESIST_TRAILER	string	framexml
+RESOLUTION	string	framexml
+RESURRECTABLE	string	framexml
+RESURRECT_REQUEST	string	framexml
+RESURRECT_REQUEST_NO_SICKNESS	string	framexml
+RESURRECT_REQUEST_NO_SICKNESS_TIMER	string	framexml
+RESURRECT_REQUEST_TIMER	string	framexml
+RETURN_TO_GAME	string	framexml
+RETURN_TO_WORLD	string	framexml
+REWARD_CHOICES	string	framexml
+REWARD_CHOOSE	string	framexml
+REWARD_ITEMS	string	framexml
+REWARD_ITEMS_ONLY	string	framexml
+REWARD_SPELL	string	framexml
+REWARD_TRADESKILL_SPELL	string	framexml
+RIGHT_ACTIONBAR_PAGE	number	framexml
+RIGHT_CLICK_MESSAGE	string	framexml
+ROGUE_AGILITY_TOOLTIP	string	framexml
+ROTATIONS_PER_SECOND	number	framexml
+ROWS_IN_BG_TEXTURE	number	framexml
+RaidBossEmoteFrame	table	framexml
+RaidBuffButtonTemplate	lod	framexml
+RaidButton_OnClick	lod	framexml
+RaidFrame	table	framexml
+RaidFrameAddMemberButton	lod	framexml
+RaidFrameAddMemberButton_Update	lod	framexml
+RaidFrameConvertToRaidButton	table	framexml
+RaidFrameConvertToRaidButtonText	table	framexml
+RaidFrameDropDown_Initialize	lod	framexml
+RaidFrameRaidDescription	table	framexml
+RaidFrameRaidInfoButton	table	framexml
+RaidFrameRaidInfoButtonText	table	framexml
+RaidFrameReadyCheckButton	lod	framexml
+RaidFrameReadyCheckButton_Update	lod	framexml
+RaidFrame_LoadUI	function	framexml
+RaidFrame_OnEvent	function	framexml
+RaidFrame_OnLoad	function	framexml
+RaidFrame_Update	function	framexml
+RaidGroup1	lod	framexml
+RaidGroup2	lod	framexml
+RaidGroup3	lod	framexml
+RaidGroup4	lod	framexml
+RaidGroup5	lod	framexml
+RaidGroup6	lod	framexml
+RaidGroup7	lod	framexml
+RaidGroup8	lod	framexml
+RaidGroupButton1	lod	framexml
+RaidGroupButton10	lod	framexml
+RaidGroupButton11	lod	framexml
+RaidGroupButton12	lod	framexml
+RaidGroupButton13	lod	framexml
+RaidGroupButton14	lod	framexml
+RaidGroupButton15	lod	framexml
+RaidGroupButton16	lod	framexml
+RaidGroupButton17	lod	framexml
+RaidGroupButton18	lod	framexml
+RaidGroupButton19	lod	framexml
+RaidGroupButton2	lod	framexml
+RaidGroupButton20	lod	framexml
+RaidGroupButton21	lod	framexml
+RaidGroupButton22	lod	framexml
+RaidGroupButton23	lod	framexml
+RaidGroupButton24	lod	framexml
+RaidGroupButton25	lod	framexml
+RaidGroupButton26	lod	framexml
+RaidGroupButton27	lod	framexml
+RaidGroupButton28	lod	framexml
+RaidGroupButton29	lod	framexml
+RaidGroupButton3	lod	framexml
+RaidGroupButton30	lod	framexml
+RaidGroupButton31	lod	framexml
+RaidGroupButton32	lod	framexml
+RaidGroupButton33	lod	framexml
+RaidGroupButton34	lod	framexml
+RaidGroupButton35	lod	framexml
+RaidGroupButton36	lod	framexml
+RaidGroupButton37	lod	framexml
+RaidGroupButton38	lod	framexml
+RaidGroupButton39	lod	framexml
+RaidGroupButton4	lod	framexml
+RaidGroupButton40	lod	framexml
+RaidGroupButton5	lod	framexml
+RaidGroupButton6	lod	framexml
+RaidGroupButton7	lod	framexml
+RaidGroupButton8	lod	framexml
+RaidGroupButton9	lod	framexml
+RaidGroupButtonTemplate	lod	framexml
+RaidGroupButton_OnClick	lod	framexml
+RaidGroupButton_OnDragStart	lod	framexml
+RaidGroupButton_OnDragStop	lod	framexml
+RaidGroupButton_OnEnter	lod	framexml
+RaidGroupFrame_OnEvent	lod	framexml
+RaidGroupFrame_OnHide	lod	framexml
+RaidGroupFrame_OnLoad	lod	framexml
+RaidGroupFrame_OnUpdate	lod	framexml
+RaidGroupFrame_Update	lod	framexml
+RaidGroupFrame_UpdateHealth	lod	framexml
+RaidGroupFrame_UpdateLevel	lod	framexml
+RaidGroupSlotTemplate	lod	framexml
+RaidGroupTemplate	lod	framexml
+RaidGroup_ResetSlotButtons	lod	framexml
+RaidInfoCloseButton	table	framexml
+RaidInfoDetailCorner	table	framexml
+RaidInfoDetailHeader	table	framexml
+RaidInfoFrame	table	framexml
+RaidInfoFrame_Update	function	framexml
+RaidInfoHeader	table	framexml
+RaidInfoIDLabel	table	framexml
+RaidInfoInstance1	table	framexml
+RaidInfoInstance10	table	framexml
+RaidInfoInstance10ID	table	framexml
+RaidInfoInstance10Name	table	framexml
+RaidInfoInstance10Reset	table	framexml
+RaidInfoInstance1ID	table	framexml
+RaidInfoInstance1Name	table	framexml
+RaidInfoInstance1Reset	table	framexml
+RaidInfoInstance2	table	framexml
+RaidInfoInstance2ID	table	framexml
+RaidInfoInstance2Name	table	framexml
+RaidInfoInstance2Reset	table	framexml
+RaidInfoInstance3	table	framexml
+RaidInfoInstance3ID	table	framexml
+RaidInfoInstance3Name	table	framexml
+RaidInfoInstance3Reset	table	framexml
+RaidInfoInstance4	table	framexml
+RaidInfoInstance4ID	table	framexml
+RaidInfoInstance4Name	table	framexml
+RaidInfoInstance4Reset	table	framexml
+RaidInfoInstance5	table	framexml
+RaidInfoInstance5ID	table	framexml
+RaidInfoInstance5Name	table	framexml
+RaidInfoInstance5Reset	table	framexml
+RaidInfoInstance6	table	framexml
+RaidInfoInstance6ID	table	framexml
+RaidInfoInstance6Name	table	framexml
+RaidInfoInstance6Reset	table	framexml
+RaidInfoInstance7	table	framexml
+RaidInfoInstance7ID	table	framexml
+RaidInfoInstance7Name	table	framexml
+RaidInfoInstance7Reset	table	framexml
+RaidInfoInstance8	table	framexml
+RaidInfoInstance8ID	table	framexml
+RaidInfoInstance8Name	table	framexml
+RaidInfoInstance8Reset	table	framexml
+RaidInfoInstance9	table	framexml
+RaidInfoInstance9ID	table	framexml
+RaidInfoInstance9Name	table	framexml
+RaidInfoInstance9Reset	table	framexml
+RaidInfoInstanceLabel	table	framexml
+RaidInfoInstanceTemplate	lod	framexml
+RaidInfoScrollChildFrame	table	framexml
+RaidInfoScrollFrame	table	framexml
+RaidInfoScrollFrameBottom	table	framexml
+RaidInfoScrollFrameScrollBar	table	framexml
+RaidInfoScrollFrameScrollBarScrollDownButton	table	framexml
+RaidInfoScrollFrameScrollBarScrollUpButton	table	framexml
+RaidInfoScrollFrameScrollBarThumbTexture	table	framexml
+RaidInfoScrollFrameTop	table	framexml
+RaidInfoSubheader	table	framexml
+RaidOptionsFrame_UpdatePartyFrames	function	framexml
+RaidPulloutButtonTemplate	lod	framexml
+RaidPulloutButton_OnClick	lod	framexml
+RaidPulloutButton_OnDragStart	lod	framexml
+RaidPulloutButton_OnEvent	lod	framexml
+RaidPulloutButton_UpdateDead	lod	framexml
+RaidPulloutDropDown_Initialize	lod	framexml
+RaidPulloutDropDown_OnLoad	lod	framexml
+RaidPulloutFrameTemplate	lod	framexml
+RaidPulloutStopMoving	lod	framexml
+RaidPullout_GenerateClassFrame	lod	framexml
+RaidPullout_GenerateGroupFrame	lod	framexml
+RaidPullout_GetFrame	lod	framexml
+RaidPullout_OnEvent	lod	framexml
+RaidPullout_Update	lod	framexml
+RaidWarningFrame	table	framexml
+RaidWarningFrame_OnEvent	function	framexml
+RaidWarningFrame_OnLoad	function	framexml
+RaiseFrameLevel	function	framexml
+RandomRoll	function	engine
+RangedAttackBackgroundBottom	table	framexml
+RangedAttackBackgroundMiddle	table	framexml
+RangedAttackBackgroundTop	table	framexml
+ReadFile	function	engine
+ReadyCheckFrame	lod	framexml
+ReadyCheckFrameNoButton	lod	framexml
+ReadyCheckFrameText	lod	framexml
+ReadyCheckFrameYesButton	lod	framexml
+ReadyCheckPortrait	lod	framexml
+ReadyCheck_OnUpdate	lod	framexml
+RecipientTradeItemTemplate	lod	framexml
+RefreshBuffs	function	framexml
+RefreshMoneyFrame	function	framexml
+RegisterCVar	function	engine
+RegisterForSave	function	engine
+ReloadUI	function	engine
+RemoveChatWindowChannel	function	engine
+RemoveChatWindowMessages	function	engine
+RemoveFriend	function	engine
+RemoveQuestWatch	function	engine
+RemoveSkillUp	function	engine
+RenamePetition	function	engine
+RepairAllItems	function	engine
+ReplaceEnchant	function	engine
+ReplaceTradeEnchant	function	engine
+RepopMe	function	engine
+ReputationBar1	table	framexml
+ReputationBar10	table	framexml
+ReputationBar10AtWarCheck	table	framexml
+ReputationBar10Check	table	framexml
+ReputationBar10FactionName	table	framexml
+ReputationBar10FactionStanding	table	framexml
+ReputationBar10Highlight1	table	framexml
+ReputationBar10Highlight2	table	framexml
+ReputationBar10ReputationBarLeft	table	framexml
+ReputationBar10ReputationBarRight	table	framexml
+ReputationBar11	table	framexml
+ReputationBar11AtWarCheck	table	framexml
+ReputationBar11Check	table	framexml
+ReputationBar11FactionName	table	framexml
+ReputationBar11FactionStanding	table	framexml
+ReputationBar11Highlight1	table	framexml
+ReputationBar11Highlight2	table	framexml
+ReputationBar11ReputationBarLeft	table	framexml
+ReputationBar11ReputationBarRight	table	framexml
+ReputationBar12	table	framexml
+ReputationBar12AtWarCheck	table	framexml
+ReputationBar12Check	table	framexml
+ReputationBar12FactionName	table	framexml
+ReputationBar12FactionStanding	table	framexml
+ReputationBar12Highlight1	table	framexml
+ReputationBar12Highlight2	table	framexml
+ReputationBar12ReputationBarLeft	table	framexml
+ReputationBar12ReputationBarRight	table	framexml
+ReputationBar13	table	framexml
+ReputationBar13AtWarCheck	table	framexml
+ReputationBar13Check	table	framexml
+ReputationBar13FactionName	table	framexml
+ReputationBar13FactionStanding	table	framexml
+ReputationBar13Highlight1	table	framexml
+ReputationBar13Highlight2	table	framexml
+ReputationBar13ReputationBarLeft	table	framexml
+ReputationBar13ReputationBarRight	table	framexml
+ReputationBar14	table	framexml
+ReputationBar14AtWarCheck	table	framexml
+ReputationBar14Check	table	framexml
+ReputationBar14FactionName	table	framexml
+ReputationBar14FactionStanding	table	framexml
+ReputationBar14Highlight1	table	framexml
+ReputationBar14Highlight2	table	framexml
+ReputationBar14ReputationBarLeft	table	framexml
+ReputationBar14ReputationBarRight	table	framexml
+ReputationBar15	table	framexml
+ReputationBar15AtWarCheck	table	framexml
+ReputationBar15Check	table	framexml
+ReputationBar15FactionName	table	framexml
+ReputationBar15FactionStanding	table	framexml
+ReputationBar15Highlight1	table	framexml
+ReputationBar15Highlight2	table	framexml
+ReputationBar15ReputationBarLeft	table	framexml
+ReputationBar15ReputationBarRight	table	framexml
+ReputationBar1AtWarCheck	table	framexml
+ReputationBar1Check	table	framexml
+ReputationBar1FactionName	table	framexml
+ReputationBar1FactionStanding	table	framexml
+ReputationBar1Highlight1	table	framexml
+ReputationBar1Highlight2	table	framexml
+ReputationBar1ReputationBarLeft	table	framexml
+ReputationBar1ReputationBarRight	table	framexml
+ReputationBar2	table	framexml
+ReputationBar2AtWarCheck	table	framexml
+ReputationBar2Check	table	framexml
+ReputationBar2FactionName	table	framexml
+ReputationBar2FactionStanding	table	framexml
+ReputationBar2Highlight1	table	framexml
+ReputationBar2Highlight2	table	framexml
+ReputationBar2ReputationBarLeft	table	framexml
+ReputationBar2ReputationBarRight	table	framexml
+ReputationBar3	table	framexml
+ReputationBar3AtWarCheck	table	framexml
+ReputationBar3Check	table	framexml
+ReputationBar3FactionName	table	framexml
+ReputationBar3FactionStanding	table	framexml
+ReputationBar3Highlight1	table	framexml
+ReputationBar3Highlight2	table	framexml
+ReputationBar3ReputationBarLeft	table	framexml
+ReputationBar3ReputationBarRight	table	framexml
+ReputationBar4	table	framexml
+ReputationBar4AtWarCheck	table	framexml
+ReputationBar4Check	table	framexml
+ReputationBar4FactionName	table	framexml
+ReputationBar4FactionStanding	table	framexml
+ReputationBar4Highlight1	table	framexml
+ReputationBar4Highlight2	table	framexml
+ReputationBar4ReputationBarLeft	table	framexml
+ReputationBar4ReputationBarRight	table	framexml
+ReputationBar5	table	framexml
+ReputationBar5AtWarCheck	table	framexml
+ReputationBar5Check	table	framexml
+ReputationBar5FactionName	table	framexml
+ReputationBar5FactionStanding	table	framexml
+ReputationBar5Highlight1	table	framexml
+ReputationBar5Highlight2	table	framexml
+ReputationBar5ReputationBarLeft	table	framexml
+ReputationBar5ReputationBarRight	table	framexml
+ReputationBar6	table	framexml
+ReputationBar6AtWarCheck	table	framexml
+ReputationBar6Check	table	framexml
+ReputationBar6FactionName	table	framexml
+ReputationBar6FactionStanding	table	framexml
+ReputationBar6Highlight1	table	framexml
+ReputationBar6Highlight2	table	framexml
+ReputationBar6ReputationBarLeft	table	framexml
+ReputationBar6ReputationBarRight	table	framexml
+ReputationBar7	table	framexml
+ReputationBar7AtWarCheck	table	framexml
+ReputationBar7Check	table	framexml
+ReputationBar7FactionName	table	framexml
+ReputationBar7FactionStanding	table	framexml
+ReputationBar7Highlight1	table	framexml
+ReputationBar7Highlight2	table	framexml
+ReputationBar7ReputationBarLeft	table	framexml
+ReputationBar7ReputationBarRight	table	framexml
+ReputationBar8	table	framexml
+ReputationBar8AtWarCheck	table	framexml
+ReputationBar8Check	table	framexml
+ReputationBar8FactionName	table	framexml
+ReputationBar8FactionStanding	table	framexml
+ReputationBar8Highlight1	table	framexml
+ReputationBar8Highlight2	table	framexml
+ReputationBar8ReputationBarLeft	table	framexml
+ReputationBar8ReputationBarRight	table	framexml
+ReputationBar9	table	framexml
+ReputationBar9AtWarCheck	table	framexml
+ReputationBar9Check	table	framexml
+ReputationBar9FactionName	table	framexml
+ReputationBar9FactionStanding	table	framexml
+ReputationBar9Highlight1	table	framexml
+ReputationBar9Highlight2	table	framexml
+ReputationBar9ReputationBarLeft	table	framexml
+ReputationBar9ReputationBarRight	table	framexml
+ReputationBarTemplate	lod	framexml
+ReputationBar_OnClick	function	framexml
+ReputationDetailAtWarCheckBox	table	framexml
+ReputationDetailAtWarCheckBoxText	table	framexml
+ReputationDetailCloseButton	table	framexml
+ReputationDetailCorner	table	framexml
+ReputationDetailDivider	table	framexml
+ReputationDetailFactionDescription	table	framexml
+ReputationDetailFactionName	table	framexml
+ReputationDetailFrame	table	framexml
+ReputationDetailInactiveCheckBox	table	framexml
+ReputationDetailInactiveCheckBoxText	table	framexml
+ReputationDetailMainScreenCheckBox	table	framexml
+ReputationDetailMainScreenCheckBoxText	table	framexml
+ReputationFrame	table	framexml
+ReputationFrameFactionLabel	table	framexml
+ReputationFrameStandingLabel	table	framexml
+ReputationFrame_OnEvent	function	framexml
+ReputationFrame_OnLoad	function	framexml
+ReputationFrame_OnShow	function	framexml
+ReputationFrame_Update	function	framexml
+ReputationHeader1	table	framexml
+ReputationHeader10	table	framexml
+ReputationHeader10Highlight	table	framexml
+ReputationHeader10NormalText	table	framexml
+ReputationHeader11	table	framexml
+ReputationHeader11Highlight	table	framexml
+ReputationHeader11NormalText	table	framexml
+ReputationHeader12	table	framexml
+ReputationHeader12Highlight	table	framexml
+ReputationHeader12NormalText	table	framexml
+ReputationHeader13	table	framexml
+ReputationHeader13Highlight	table	framexml
+ReputationHeader13NormalText	table	framexml
+ReputationHeader14	table	framexml
+ReputationHeader14Highlight	table	framexml
+ReputationHeader14NormalText	table	framexml
+ReputationHeader15	table	framexml
+ReputationHeader15Highlight	table	framexml
+ReputationHeader15NormalText	table	framexml
+ReputationHeader1Highlight	table	framexml
+ReputationHeader1NormalText	table	framexml
+ReputationHeader2	table	framexml
+ReputationHeader2Highlight	table	framexml
+ReputationHeader2NormalText	table	framexml
+ReputationHeader3	table	framexml
+ReputationHeader3Highlight	table	framexml
+ReputationHeader3NormalText	table	framexml
+ReputationHeader4	table	framexml
+ReputationHeader4Highlight	table	framexml
+ReputationHeader4NormalText	table	framexml
+ReputationHeader5	table	framexml
+ReputationHeader5Highlight	table	framexml
+ReputationHeader5NormalText	table	framexml
+ReputationHeader6	table	framexml
+ReputationHeader6Highlight	table	framexml
+ReputationHeader6NormalText	table	framexml
+ReputationHeader7	table	framexml
+ReputationHeader7Highlight	table	framexml
+ReputationHeader7NormalText	table	framexml
+ReputationHeader8	table	framexml
+ReputationHeader8Highlight	table	framexml
+ReputationHeader8NormalText	table	framexml
+ReputationHeader9	table	framexml
+ReputationHeader9Highlight	table	framexml
+ReputationHeader9NormalText	table	framexml
+ReputationHeaderTemplate	lod	framexml
+ReputationListScrollFrame	table	framexml
+ReputationListScrollFrameScrollBar	table	framexml
+ReputationListScrollFrameScrollBarScrollDownButton	table	framexml
+ReputationListScrollFrameScrollBarScrollUpButton	table	framexml
+ReputationListScrollFrameScrollBarThumbTexture	table	framexml
+ReputationListScrollFrameScrollChildFrame	table	framexml
+ReputationWatchBar	table	framexml
+ReputationWatchBarOverlayFrame	table	framexml
+ReputationWatchBarTexture0	table	framexml
+ReputationWatchBarTexture1	table	framexml
+ReputationWatchBarTexture2	table	framexml
+ReputationWatchBarTexture3	table	framexml
+ReputationWatchBar_Update	function	framexml
+ReputationWatchStatusBar	table	framexml
+ReputationWatchStatusBarBackground	table	framexml
+ReputationWatchStatusBarText	table	framexml
+ReputationXPBarTexture0	table	framexml
+ReputationXPBarTexture1	table	framexml
+ReputationXPBarTexture2	table	framexml
+ReputationXPBarTexture3	table	framexml
+RequestBattlefieldPositions	function	engine
+RequestBattlefieldScoreData	function	engine
+RequestInspectHonorData	function	engine
+RequestRaidInfo	function	engine
+RequestTimePlayed	function	engine
+ResetChatColors	function	engine
+ResetCursor	function	engine
+ResetDisabledAddOns	function	engine
+ResetInstances	function	engine
+ResetPerformanceValues	function	engine
+ResetTutorials	function	engine
+ResetView	function	engine
+RestartGx	function	engine
+RestoreVideoDefaults	function	engine
+ResurrectHasSickness	function	engine
+ResurrectHasTimer	function	engine
+RetrieveCorpse	function	engine
+ReturnInboxItem	function	engine
+RollOnLoot	function	engine
+RunBinding	function	engine
+RunScript	function	engine
+SALE_PRICE_COLON	string	framexml
+SAVE	string	framexml
+SAY	string	framexml
+SAY_MESSAGE	string	framexml
+SCORE_FLAGS_CAPTURED	string	framexml
+SCORE_FLAGS_RETURNED	string	framexml
+SCORE_HONORABLE_KILLS	string	framexml
+SCORE_HONOR_GAINED	string	framexml
+SCORE_KILLING_BLOWS	string	framexml
+SCREENSHOT_FAILURE	string	framexml
+SCREENSHOT_STATUS_FADETIME	number	framexml
+SCREENSHOT_SUCCESS	string	framexml
+SEARCH	string	framexml
+SEARCHING_FOR_ITEMS	string	framexml
+SECONDARY	string	framexml
+SECONDARYHANDSLOT	string	framexml
+SECONDARY_SKILLS	string	framexml
+SECONDS	string	framexml
+SECONDS_ABBR	string	framexml
+SECONDS_ABBR_P1	string	framexml
+SECONDS_P1	string	framexml
+SECOND_ONELETTER_ABBR	string	framexml
+SELECTED_CHAT_FRAME	table	framexml
+SELECTED_DOCK_FRAME	table	framexml
+SELECT_CATEGORY	string	framexml
+SELFKILLOTHER	string	framexml
+SENDMAIL	string	framexml
+SENDMAIL_TEXT	string	framexml
+SEND_BUG	string	framexml
+SEND_LABEL	string	framexml
+SEND_MAIL_COST	string	framexml
+SEND_MESSAGE	string	framexml
+SEND_MONEY	string	framexml
+SEND_MONEY_CONFIRMATION	string	framexml
+SEND_SUGGEST	string	framexml
+SERVER_CHANNELS	string	framexml
+SET_GUILDMOTD_LABEL	string	framexml
+SET_GUILDOFFICERNOTE_LABEL	string	framexml
+SET_GUILDPLAYERNOTE_LABEL	string	framexml
+SHAMAN_INTELLECT_TOOLTIP	string	framexml
+SHAMAN_STRENGTH_TOOLTIP	string	framexml
+SHARE_QUEST	string	framexml
+SHARE_QUEST_TEXT	string	framexml
+SHIELD_BLOCK_TEMPLATE	string	framexml
+SHIRTSLOT	string	framexml
+SHOULDERSLOT	string	framexml
+SHOW_BATTLEFIELDMINIMAP_PLAYERS	string	framexml
+SHOW_BATTLEFIELD_MINIMAP	string	framexml
+SHOW_BUFFS	string	framexml
+SHOW_BUFF_DURATIONS	string	framexml
+SHOW_BUFF_DURATION_TEXT	string	framexml
+SHOW_CASTABLE_BUFFS	string	framexml
+SHOW_CASTABLE_BUFFS_TEXT	string	framexml
+SHOW_CLOAK	string	framexml
+SHOW_COMBAT_TEXT	string	framexml
+SHOW_COMBAT_TEXT_TEXT	string	framexml
+SHOW_DAMAGE_TEXT	string	framexml
+SHOW_DEBUFFS	string	framexml
+SHOW_DISPELLABLE_DEBUFFS	string	framexml
+SHOW_DISPELLABLE_DEBUFFS_TEXT	string	framexml
+SHOW_FACTION_ON_MAINSCREEN	string	framexml
+SHOW_FRIENDS_LIST	string	framexml
+SHOW_FULLSCREEN_STATUS	string	framexml
+SHOW_GUILD_NAMES	string	framexml
+SHOW_HELM	string	framexml
+SHOW_IGNORE_LIST	string	framexml
+SHOW_KEYRING	number	framexml
+SHOW_LOOT_SPAM	string	framexml
+SHOW_MULTIBAR1_TEXT	string	framexml
+SHOW_MULTIBAR2_TEXT	string	framexml
+SHOW_MULTIBAR3_TEXT	string	framexml
+SHOW_MULTIBAR4_TEXT	string	framexml
+SHOW_MULTI_ACTIONBAR_1	lod	framexml
+SHOW_MULTI_ACTIONBAR_2	lod	framexml
+SHOW_MULTI_ACTIONBAR_3	lod	framexml
+SHOW_MULTI_ACTIONBAR_4	lod	framexml
+SHOW_NEWBIE_TIPS	string	framexml
+SHOW_NEWBIE_TIPS_TEXT	string	framexml
+SHOW_NPC_NAMES	string	framexml
+SHOW_OFFLINE_GUILD_MEMBERS	number	framexml
+SHOW_OFFLINE_MEMBERS	string	framexml
+SHOW_OWN_NAME	string	framexml
+SHOW_PARTY_BACKGROUND	string	framexml
+SHOW_PARTY_BACKGROUND_TEXT	string	framexml
+SHOW_PARTY_PETS	string	framexml
+SHOW_PARTY_PETS_TEXT	string	framexml
+SHOW_PET_MELEE_DAMAGE	string	framexml
+SHOW_PET_NAMEPLATES	string	framexml
+SHOW_PET_SPELL_DAMAGE	string	framexml
+SHOW_PLAYER_NAMES	string	framexml
+SHOW_PLAYER_TITLES	string	framexml
+SHOW_QUEST_FADING_TEXT	string	framexml
+SHOW_TARGET_OF_TARGET	string	framexml
+SHOW_TARGET_OF_TARGET_STATE	string	framexml
+SHOW_TARGET_OF_TARGET_TEXT	string	framexml
+SHOW_TIPOFTHEDAY_TEXT	string	framexml
+SHOW_TUTORIALS	string	framexml
+SHOW_UNIT_NAMES	string	framexml
+SIGN_CHARTER	string	framexml
+SILVER	string	framexml
+SILVER_PER_GOLD	number	framexml
+SIMPLECASTOTHEROTHER	string	framexml
+SIMPLECASTOTHERSELF	string	framexml
+SIMPLECASTSELFOTHER	string	framexml
+SIMPLECASTSELFSELF	string	framexml
+SIMPLEPERFORMOTHEROTHER	string	framexml
+SIMPLEPERFORMOTHERSELF	string	framexml
+SIMPLEPERFORMSELFOTHER	string	framexml
+SIMPLEPERFORMSELFSELF	string	framexml
+SIMPLE_CHAT	string	framexml
+SIMPLE_CHAT_TEXT	string	framexml
+SINGLE_DAMAGE_TEMPLATE	string	framexml
+SKILL	string	framexml
+SKILLFRAME_SKILL_HEIGHT	number	framexml
+SKILLS	string	framexml
+SKILLS_TO_DISPLAY	number	framexml
+SKILL_DESCRIPTION	string	framexml
+SKILL_INCREMENT_COST	string	framexml
+SKILL_INCREMENT_COST_SINGULAR	string	framexml
+SKILL_LEARNING_COST	string	framexml
+SKILL_LEARNING_COST_SINGULAR	string	framexml
+SKILL_LEVEL	string	framexml
+SKILL_POINTS_TOOLTIP	string	framexml
+SKILL_RANK_UP	string	framexml
+SLASH_ASSIST1	string	framexml
+SLASH_ASSIST2	string	framexml
+SLASH_ASSIST3	string	framexml
+SLASH_ASSIST4	string	framexml
+SLASH_BATTLEGROUND1	string	framexml
+SLASH_BATTLEGROUND2	string	framexml
+SLASH_BATTLEGROUND3	string	framexml
+SLASH_BATTLEGROUND4	string	framexml
+SLASH_CAST1	string	framexml
+SLASH_CAST2	string	framexml
+SLASH_CAST3	string	framexml
+SLASH_CAST4	string	framexml
+SLASH_CHANNEL1	string	framexml
+SLASH_CHANNEL2	string	framexml
+SLASH_CHANNEL3	string	framexml
+SLASH_CHANNEL4	string	framexml
+SLASH_CHATLOG1	string	framexml
+SLASH_CHATLOG2	string	framexml
+SLASH_CHAT_AFK1	string	framexml
+SLASH_CHAT_AFK2	string	framexml
+SLASH_CHAT_ANNOUNCE1	string	framexml
+SLASH_CHAT_ANNOUNCE2	string	framexml
+SLASH_CHAT_ANNOUNCE3	string	framexml
+SLASH_CHAT_ANNOUNCE4	string	framexml
+SLASH_CHAT_BAN1	string	framexml
+SLASH_CHAT_BAN2	string	framexml
+SLASH_CHAT_CINVITE1	string	framexml
+SLASH_CHAT_CINVITE2	string	framexml
+SLASH_CHAT_CINVITE3	string	framexml
+SLASH_CHAT_CINVITE4	string	framexml
+SLASH_CHAT_DND1	string	framexml
+SLASH_CHAT_DND2	string	framexml
+SLASH_CHAT_DND3	string	framexml
+SLASH_CHAT_HELP1	string	framexml
+SLASH_CHAT_HELP2	string	framexml
+SLASH_CHAT_HELP3	string	framexml
+SLASH_CHAT_HELP4	string	framexml
+SLASH_CHAT_HELP5	string	framexml
+SLASH_CHAT_KICK1	string	framexml
+SLASH_CHAT_KICK2	string	framexml
+SLASH_CHAT_MODERATE1	string	framexml
+SLASH_CHAT_MODERATE2	string	framexml
+SLASH_CHAT_MODERATOR1	string	framexml
+SLASH_CHAT_MODERATOR2	string	framexml
+SLASH_CHAT_MODERATOR3	string	framexml
+SLASH_CHAT_MODERATOR4	string	framexml
+SLASH_CHAT_MUTE1	string	framexml
+SLASH_CHAT_MUTE2	string	framexml
+SLASH_CHAT_MUTE3	string	framexml
+SLASH_CHAT_MUTE4	string	framexml
+SLASH_CHAT_MUTE5	string	framexml
+SLASH_CHAT_MUTE6	string	framexml
+SLASH_CHAT_OWNER1	string	framexml
+SLASH_CHAT_OWNER2	string	framexml
+SLASH_CHAT_PASSWORD1	string	framexml
+SLASH_CHAT_PASSWORD2	string	framexml
+SLASH_CHAT_PASSWORD3	string	framexml
+SLASH_CHAT_PASSWORD4	string	framexml
+SLASH_CHAT_PASSWORD5	string	framexml
+SLASH_CHAT_UNBAN1	string	framexml
+SLASH_CHAT_UNBAN2	string	framexml
+SLASH_CHAT_UNMODERATOR1	string	framexml
+SLASH_CHAT_UNMODERATOR2	string	framexml
+SLASH_CHAT_UNMODERATOR3	string	framexml
+SLASH_CHAT_UNMODERATOR4	string	framexml
+SLASH_CHAT_UNMUTE1	string	framexml
+SLASH_CHAT_UNMUTE2	string	framexml
+SLASH_CHAT_UNMUTE3	string	framexml
+SLASH_CHAT_UNMUTE4	string	framexml
+SLASH_CHAT_UNMUTE5	string	framexml
+SLASH_CHAT_UNMUTE6	string	framexml
+SLASH_CLEAR1	string	framexml
+SLASH_CLEAR2	string	framexml
+SLASH_COMBATLOG1	string	framexml
+SLASH_COMBATLOG2	string	framexml
+SLASH_CONSOLE1	string	framexml
+SLASH_CONSOLE2	string	framexml
+SLASH_DUEL1	string	framexml
+SLASH_DUEL2	string	framexml
+SLASH_DUEL_CANCEL1	string	framexml
+SLASH_DUEL_CANCEL2	string	framexml
+SLASH_DUEL_CANCEL3	string	framexml
+SLASH_DUEL_CANCEL4	string	framexml
+SLASH_DUEL_CANCEL5	string	framexml
+SLASH_DUEL_CANCEL6	string	framexml
+SLASH_EMOTE1	string	framexml
+SLASH_EMOTE2	string	framexml
+SLASH_EMOTE3	string	framexml
+SLASH_EMOTE4	string	framexml
+SLASH_EMOTE5	string	framexml
+SLASH_EMOTE6	string	framexml
+SLASH_EMOTE7	string	framexml
+SLASH_EMOTE8	string	framexml
+SLASH_FOLLOW1	string	framexml
+SLASH_FOLLOW2	string	framexml
+SLASH_FOLLOW3	string	framexml
+SLASH_FOLLOW4	string	framexml
+SLASH_FOLLOW5	string	framexml
+SLASH_FOLLOW6	string	framexml
+SLASH_FRIENDS1	string	framexml
+SLASH_FRIENDS2	string	framexml
+SLASH_FRIENDS3	string	framexml
+SLASH_FRIENDS4	string	framexml
+SLASH_GUILD1	string	framexml
+SLASH_GUILD2	string	framexml
+SLASH_GUILD3	string	framexml
+SLASH_GUILD4	string	framexml
+SLASH_GUILD5	string	framexml
+SLASH_GUILD6	string	framexml
+SLASH_GUILD7	string	framexml
+SLASH_GUILD8	string	framexml
+SLASH_GUILD_DEMOTE1	string	framexml
+SLASH_GUILD_DEMOTE2	string	framexml
+SLASH_GUILD_DEMOTE3	string	framexml
+SLASH_GUILD_DEMOTE4	string	framexml
+SLASH_GUILD_DISBAND1	string	framexml
+SLASH_GUILD_DISBAND2	string	framexml
+SLASH_GUILD_DISBAND3	string	framexml
+SLASH_GUILD_DISBAND4	string	framexml
+SLASH_GUILD_HELP1	string	framexml
+SLASH_GUILD_HELP2	string	framexml
+SLASH_GUILD_HELP3	string	framexml
+SLASH_GUILD_HELP4	string	framexml
+SLASH_GUILD_HELP5	string	framexml
+SLASH_GUILD_INFO1	string	framexml
+SLASH_GUILD_INFO2	string	framexml
+SLASH_GUILD_INFO3	string	framexml
+SLASH_GUILD_INFO4	string	framexml
+SLASH_GUILD_INVITE1	string	framexml
+SLASH_GUILD_INVITE2	string	framexml
+SLASH_GUILD_INVITE3	string	framexml
+SLASH_GUILD_INVITE4	string	framexml
+SLASH_GUILD_LEADER1	string	framexml
+SLASH_GUILD_LEADER2	string	framexml
+SLASH_GUILD_LEADER3	string	framexml
+SLASH_GUILD_LEADER4	string	framexml
+SLASH_GUILD_LEAVE1	string	framexml
+SLASH_GUILD_LEAVE2	string	framexml
+SLASH_GUILD_LEAVE3	string	framexml
+SLASH_GUILD_LEAVE4	string	framexml
+SLASH_GUILD_MOTD1	string	framexml
+SLASH_GUILD_MOTD2	string	framexml
+SLASH_GUILD_MOTD3	string	framexml
+SLASH_GUILD_MOTD4	string	framexml
+SLASH_GUILD_PROMOTE1	string	framexml
+SLASH_GUILD_PROMOTE2	string	framexml
+SLASH_GUILD_PROMOTE3	string	framexml
+SLASH_GUILD_PROMOTE4	string	framexml
+SLASH_GUILD_ROSTER1	string	framexml
+SLASH_GUILD_ROSTER2	string	framexml
+SLASH_GUILD_ROSTER3	string	framexml
+SLASH_GUILD_ROSTER4	string	framexml
+SLASH_GUILD_UNINVITE1	string	framexml
+SLASH_GUILD_UNINVITE2	string	framexml
+SLASH_GUILD_UNINVITE3	string	framexml
+SLASH_GUILD_UNINVITE4	string	framexml
+SLASH_GUILD_WHO1	string	framexml
+SLASH_GUILD_WHO2	string	framexml
+SLASH_GUILD_WHO3	string	framexml
+SLASH_GUILD_WHO4	string	framexml
+SLASH_GUILD_WHO5	string	framexml
+SLASH_GUILD_WHO6	string	framexml
+SLASH_HELP1	string	framexml
+SLASH_HELP2	string	framexml
+SLASH_HELP3	string	framexml
+SLASH_HELP4	string	framexml
+SLASH_HELP5	string	framexml
+SLASH_HELP6	string	framexml
+SLASH_IGNORE1	string	framexml
+SLASH_IGNORE2	string	framexml
+SLASH_INSPECT1	string	framexml
+SLASH_INSPECT2	string	framexml
+SLASH_INSPECT3	string	framexml
+SLASH_INSPECT4	string	framexml
+SLASH_INVITE1	string	framexml
+SLASH_INVITE2	string	framexml
+SLASH_INVITE3	string	framexml
+SLASH_INVITE4	string	framexml
+SLASH_INVITE5	string	framexml
+SLASH_INVITE6	string	framexml
+SLASH_JOIN1	string	framexml
+SLASH_JOIN2	string	framexml
+SLASH_JOIN3	string	framexml
+SLASH_JOIN4	string	framexml
+SLASH_JOIN5	string	framexml
+SLASH_JOIN6	string	framexml
+SLASH_JOIN7	string	framexml
+SLASH_LEAVE1	string	framexml
+SLASH_LEAVE2	string	framexml
+SLASH_LEAVE3	string	framexml
+SLASH_LEAVE4	string	framexml
+SLASH_LEAVE5	string	framexml
+SLASH_LEAVE6	string	framexml
+SLASH_LEAVE7	string	framexml
+SLASH_LIST_CHANNEL1	string	framexml
+SLASH_LIST_CHANNEL2	string	framexml
+SLASH_LIST_CHANNEL3	string	framexml
+SLASH_LIST_CHANNEL4	string	framexml
+SLASH_LIST_CHANNEL5	string	framexml
+SLASH_LIST_CHANNEL6	string	framexml
+SLASH_LIST_CHANNEL7	string	framexml
+SLASH_LOGOUT1	string	framexml
+SLASH_LOGOUT2	string	framexml
+SLASH_LOGOUT3	string	framexml
+SLASH_LOGOUT4	string	framexml
+SLASH_LOOT_FFA1	string	framexml
+SLASH_LOOT_FFA2	string	framexml
+SLASH_LOOT_MASTER1	string	framexml
+SLASH_LOOT_MASTER2	string	framexml
+SLASH_LOOT_ROUNDROBIN1	string	framexml
+SLASH_LOOT_ROUNDROBIN2	string	framexml
+SLASH_MACRO1	string	framexml
+SLASH_MACRO2	string	framexml
+SLASH_MACRO3	string	framexml
+SLASH_MACRO4	string	framexml
+SLASH_MACROHELP1	string	framexml
+SLASH_MACROHELP2	string	framexml
+SLASH_MACROHELP3	string	framexml
+SLASH_OFFICER1	string	framexml
+SLASH_OFFICER2	string	framexml
+SLASH_OFFICER3	string	framexml
+SLASH_OFFICER4	string	framexml
+SLASH_PARTY1	string	framexml
+SLASH_PARTY2	string	framexml
+SLASH_PARTY3	string	framexml
+SLASH_PARTY4	string	framexml
+SLASH_PLAYED1	string	framexml
+SLASH_PLAYED2	string	framexml
+SLASH_PROMOTE1	string	framexml
+SLASH_PROMOTE2	string	framexml
+SLASH_PROMOTE3	string	framexml
+SLASH_PROMOTE4	string	framexml
+SLASH_PVP1	string	framexml
+SLASH_PVP2	string	framexml
+SLASH_QUIT1	string	framexml
+SLASH_QUIT2	string	framexml
+SLASH_QUIT3	string	framexml
+SLASH_QUIT4	string	framexml
+SLASH_RAID1	string	framexml
+SLASH_RAID2	string	framexml
+SLASH_RAID3	string	framexml
+SLASH_RAID4	string	framexml
+SLASH_RAID5	string	framexml
+SLASH_RAID6	string	framexml
+SLASH_RAID_INFO1	string	framexml
+SLASH_RAID_INFO2	string	framexml
+SLASH_RAID_WARNING1	string	framexml
+SLASH_RAID_WARNING2	string	framexml
+SLASH_RANDOM1	string	framexml
+SLASH_RANDOM2	string	framexml
+SLASH_RANDOM3	string	framexml
+SLASH_RANDOM4	string	framexml
+SLASH_RANDOM5	string	framexml
+SLASH_RANDOM6	string	framexml
+SLASH_RANDOM7	string	framexml
+SLASH_READYCHECK1	string	framexml
+SLASH_READYCHECK2	string	framexml
+SLASH_REMOVEFRIEND1	string	framexml
+SLASH_REMOVEFRIEND2	string	framexml
+SLASH_REMOVEFRIEND3	string	framexml
+SLASH_REMOVEFRIEND4	string	framexml
+SLASH_REPLY1	string	framexml
+SLASH_REPLY2	string	framexml
+SLASH_REPLY3	string	framexml
+SLASH_REPLY4	string	framexml
+SLASH_SAVEGUILDROSTER1	string	framexml
+SLASH_SAVEGUILDROSTER2	string	framexml
+SLASH_SAY1	string	framexml
+SLASH_SAY2	string	framexml
+SLASH_SAY3	string	framexml
+SLASH_SAY4	string	framexml
+SLASH_SCRIPT1	string	framexml
+SLASH_SCRIPT2	string	framexml
+SLASH_SCRIPT3	string	framexml
+SLASH_SCRIPT4	string	framexml
+SLASH_TARGET1	string	framexml
+SLASH_TARGET2	string	framexml
+SLASH_TARGET3	string	framexml
+SLASH_TARGET4	string	framexml
+SLASH_TIME1	string	framexml
+SLASH_TIME2	string	framexml
+SLASH_TRADE1	string	framexml
+SLASH_TRADE2	string	framexml
+SLASH_TRADE3	string	framexml
+SLASH_TRADE4	string	framexml
+SLASH_UNIGNORE1	string	framexml
+SLASH_UNIGNORE2	string	framexml
+SLASH_UNINVITE1	string	framexml
+SLASH_UNINVITE2	string	framexml
+SLASH_UNINVITE3	string	framexml
+SLASH_UNINVITE4	string	framexml
+SLASH_UNINVITE5	string	framexml
+SLASH_UNINVITE6	string	framexml
+SLASH_UNINVITE7	string	framexml
+SLASH_UNINVITE8	string	framexml
+SLASH_VOICEMACRO1	string	framexml
+SLASH_VOICEMACRO2	string	framexml
+SLASH_WHISPER1	string	framexml
+SLASH_WHISPER10	string	framexml
+SLASH_WHISPER2	string	framexml
+SLASH_WHISPER3	string	framexml
+SLASH_WHISPER4	string	framexml
+SLASH_WHISPER5	string	framexml
+SLASH_WHISPER6	string	framexml
+SLASH_WHISPER7	string	framexml
+SLASH_WHISPER8	string	framexml
+SLASH_WHISPER9	string	framexml
+SLASH_WHO1	string	framexml
+SLASH_WHO2	string	framexml
+SLASH_YELL1	string	framexml
+SLASH_YELL2	string	framexml
+SLASH_YELL3	string	framexml
+SLASH_YELL4	string	framexml
+SLASH_YELL5	string	framexml
+SLASH_YELL6	string	framexml
+SLASH_YELL7	string	framexml
+SLURRED_SPEECH	string	framexml
+SMART_PIVOT	string	framexml
+SOCIALS	string	framexml
+SOCIAL_BUTTON	string	framexml
+SOLD_BY_COLON	string	framexml
+SOLO	string	framexml
+SORT_QUEST	string	framexml
+SOUNDOPTIONS_MENU	string	framexml
+SOUND_VOLUME	string	framexml
+SPEAKERMODE	string	framexml
+SPEAKERMODE_HEADPHONES	string	framexml
+SPEAKERMODE_STEREO	string	framexml
+SPEAKERMODE_SURROUND	string	framexml
+SPECIAL_SKILLS	string	framexml
+SPEED	string	framexml
+SPELLBLOCKEDOTHEROTHER	string	framexml
+SPELLBLOCKEDOTHERSELF	string	framexml
+SPELLBLOCKEDSELFOTHER	string	framexml
+SPELLBOOK	string	framexml
+SPELLBOOK_ABILITIES_BUTTON	string	framexml
+SPELLBOOK_BUTTON	string	framexml
+SPELLBOOK_PAGENUMBERS	table	framexml
+SPELLCASTGOOTHER	string	framexml
+SPELLCASTGOOTHERTARGETTED	string	framexml
+SPELLCASTGOSELF	string	framexml
+SPELLCASTGOSELFTARGETTED	string	framexml
+SPELLCASTOTHERSTART	string	framexml
+SPELLCASTSELFSTART	string	framexml
+SPELLDEFLECTEDOTHEROTHER	string	framexml
+SPELLDEFLECTEDOTHERSELF	string	framexml
+SPELLDEFLECTEDSELFOTHER	string	framexml
+SPELLDEFLECTEDSELFSELF	string	framexml
+SPELLDISMISSPETOTHER	string	framexml
+SPELLDISMISSPETSELF	string	framexml
+SPELLDODGEDOTHEROTHER	string	framexml
+SPELLDODGEDOTHERSELF	string	framexml
+SPELLDODGEDSELFOTHER	string	framexml
+SPELLDODGEDSELFSELF	string	framexml
+SPELLDURABILITYDAMAGEALLOTHEROTHER	string	framexml
+SPELLDURABILITYDAMAGEALLOTHERSELF	string	framexml
+SPELLDURABILITYDAMAGEALLSELFOTHER	string	framexml
+SPELLDURABILITYDAMAGEOTHEROTHER	string	framexml
+SPELLDURABILITYDAMAGEOTHERSELF	string	framexml
+SPELLDURABILITYDAMAGESELFOTHER	string	framexml
+SPELLEVADEDOTHEROTHER	string	framexml
+SPELLEVADEDOTHERSELF	string	framexml
+SPELLEVADEDSELFOTHER	string	framexml
+SPELLEVADEDSELFSELF	string	framexml
+SPELLEXTRAATTACKSOTHER	string	framexml
+SPELLEXTRAATTACKSOTHER_SINGULAR	string	framexml
+SPELLEXTRAATTACKSSELF	string	framexml
+SPELLEXTRAATTACKSSELF_SINGULAR	string	framexml
+SPELLFAILCASTOTHER	string	framexml
+SPELLFAILCASTSELF	string	framexml
+SPELLFAILPERFORMOTHER	string	framexml
+SPELLFAILPERFORMSELF	string	framexml
+SPELLHAPPINESSDRAINOTHER	string	framexml
+SPELLHAPPINESSDRAINSELF	string	framexml
+SPELLIMMUNEOTHEROTHER	string	framexml
+SPELLIMMUNEOTHERSELF	string	framexml
+SPELLIMMUNESELFOTHER	string	framexml
+SPELLIMMUNESELFSELF	string	framexml
+SPELLINTERRUPTOTHEROTHER	string	framexml
+SPELLINTERRUPTOTHERSELF	string	framexml
+SPELLINTERRUPTSELFOTHER	string	framexml
+SPELLLOGABSORBOTHEROTHER	string	framexml
+SPELLLOGABSORBOTHERSELF	string	framexml
+SPELLLOGABSORBSELFOTHER	string	framexml
+SPELLLOGABSORBSELFSELF	string	framexml
+SPELLLOGCRITOTHEROTHER	string	framexml
+SPELLLOGCRITOTHERSELF	string	framexml
+SPELLLOGCRITSCHOOLOTHEROTHER	string	framexml
+SPELLLOGCRITSCHOOLOTHERSELF	string	framexml
+SPELLLOGCRITSCHOOLSELFOTHER	string	framexml
+SPELLLOGCRITSCHOOLSELFSELF	string	framexml
+SPELLLOGCRITSELFOTHER	string	framexml
+SPELLLOGCRITSELFSELF	string	framexml
+SPELLLOGOTHEROTHER	string	framexml
+SPELLLOGOTHERSELF	string	framexml
+SPELLLOGSCHOOLOTHEROTHER	string	framexml
+SPELLLOGSCHOOLOTHERSELF	string	framexml
+SPELLLOGSCHOOLSELFOTHER	string	framexml
+SPELLLOGSCHOOLSELFSELF	string	framexml
+SPELLLOGSELFOTHER	string	framexml
+SPELLLOGSELFSELF	string	framexml
+SPELLMISSOTHEROTHER	string	framexml
+SPELLMISSOTHERSELF	string	framexml
+SPELLMISSSELFOTHER	string	framexml
+SPELLMISSSELFSELF	string	framexml
+SPELLPARRIEDOTHEROTHER	string	framexml
+SPELLPARRIEDOTHERSELF	string	framexml
+SPELLPARRIEDSELFOTHER	string	framexml
+SPELLPARRIEDSELFSELF	string	framexml
+SPELLPERFORMGOOTHER	string	framexml
+SPELLPERFORMGOOTHERTARGETTED	string	framexml
+SPELLPERFORMGOSELF	string	framexml
+SPELLPERFORMGOSELFTARGETTED	string	framexml
+SPELLPERFORMOTHERSTART	string	framexml
+SPELLPERFORMSELFSTART	string	framexml
+SPELLPOWERDRAINOTHEROTHER	string	framexml
+SPELLPOWERDRAINOTHERSELF	string	framexml
+SPELLPOWERDRAINSELFOTHER	string	framexml
+SPELLPOWERDRAINSELFSELF	string	framexml
+SPELLPOWERLEECHOTHEROTHER	string	framexml
+SPELLPOWERLEECHOTHERSELF	string	framexml
+SPELLPOWERLEECHSELFOTHER	string	framexml
+SPELLREFLECTOTHEROTHER	string	framexml
+SPELLREFLECTOTHERSELF	string	framexml
+SPELLREFLECTSELFOTHER	string	framexml
+SPELLREFLECTSELFSELF	string	framexml
+SPELLRESISTOTHEROTHER	string	framexml
+SPELLRESISTOTHERSELF	string	framexml
+SPELLRESISTSELFOTHER	string	framexml
+SPELLRESISTSELFSELF	string	framexml
+SPELLS	string	framexml
+SPELLSPLITDAMAGEOTHEROTHER	string	framexml
+SPELLSPLITDAMAGEOTHERSELF	string	framexml
+SPELLSPLITDAMAGESELFOTHER	string	framexml
+SPELLS_PER_PAGE	number	framexml
+SPELLTEACHOTHEROTHER	string	framexml
+SPELLTEACHOTHERSELF	string	framexml
+SPELLTEACHSELFOTHER	string	framexml
+SPELLTEACHSELFSELF	string	framexml
+SPELLTERSEPERFORM_OTHER	string	framexml
+SPELLTERSEPERFORM_SELF	string	framexml
+SPELLTERSE_OTHER	string	framexml
+SPELLTERSE_SELF	string	framexml
+SPELL_CAST_CHANNELED	string	framexml
+SPELL_CAST_TIME_INSTANT	string	framexml
+SPELL_CAST_TIME_INSTANT_NO_MANA	string	framexml
+SPELL_CAST_TIME_MIN	string	framexml
+SPELL_CAST_TIME_RANGED	string	framexml
+SPELL_CAST_TIME_SEC	string	framexml
+SPELL_DETAIL	string	framexml
+SPELL_DURATION	string	framexml
+SPELL_DURATION_DAYS	string	framexml
+SPELL_DURATION_HOURS	string	framexml
+SPELL_DURATION_MIN	string	framexml
+SPELL_DURATION_SEC	string	framexml
+SPELL_DURATION_UNTIL_CANCELLED	string	framexml
+SPELL_EQUIPPED_ITEM	string	framexml
+SPELL_EQUIPPED_ITEM_NOSPACE	string	framexml
+SPELL_FAILED_AFFECTING_COMBAT	string	framexml
+SPELL_FAILED_ALREADY_BEING_TAMED	string	framexml
+SPELL_FAILED_ALREADY_HAVE_CHARM	string	framexml
+SPELL_FAILED_ALREADY_HAVE_SUMMON	string	framexml
+SPELL_FAILED_ALREADY_OPEN	string	framexml
+SPELL_FAILED_AURA_BOUNCED	string	framexml
+SPELL_FAILED_BAD_IMPLICIT_TARGETS	string	framexml
+SPELL_FAILED_BAD_TARGETS	string	framexml
+SPELL_FAILED_CANT_BE_CHARMED	string	framexml
+SPELL_FAILED_CANT_BE_DISENCHANTED	string	framexml
+SPELL_FAILED_CANT_BE_PROSPECTED	string	framexml
+SPELL_FAILED_CANT_CAST_ON_TAPPED	string	framexml
+SPELL_FAILED_CANT_DUEL_WHILE_INVISIBLE	string	framexml
+SPELL_FAILED_CANT_DUEL_WHILE_STEALTHED	string	framexml
+SPELL_FAILED_CANT_STEALTH	string	framexml
+SPELL_FAILED_CASTER_AURASTATE	string	framexml
+SPELL_FAILED_CASTER_DEAD	string	framexml
+SPELL_FAILED_CHARMED	string	framexml
+SPELL_FAILED_CHEST_IN_USE	string	framexml
+SPELL_FAILED_CONFUSED	string	framexml
+SPELL_FAILED_DAMAGE_IMMUNE	string	framexml
+SPELL_FAILED_DISENCHANT_WHILE_LOOTING	string	framexml
+SPELL_FAILED_EQUIPPED_ITEM	string	framexml
+SPELL_FAILED_EQUIPPED_ITEM_CLASS	string	framexml
+SPELL_FAILED_EQUIPPED_ITEM_CLASS_MAINHAND	string	framexml
+SPELL_FAILED_EQUIPPED_ITEM_CLASS_OFFHAND	string	framexml
+SPELL_FAILED_ERROR	string	framexml
+SPELL_FAILED_FIZZLE	string	framexml
+SPELL_FAILED_FLEEING	string	framexml
+SPELL_FAILED_FOOD_LOWLEVEL	string	framexml
+SPELL_FAILED_HIGHLEVEL	string	framexml
+SPELL_FAILED_IMMUNE	string	framexml
+SPELL_FAILED_INTERRUPTED	string	framexml
+SPELL_FAILED_INTERRUPTED_COMBAT	string	framexml
+SPELL_FAILED_ITEM_ALREADY_ENCHANTED	string	framexml
+SPELL_FAILED_ITEM_GONE	string	framexml
+SPELL_FAILED_ITEM_NOT_FOUND	string	framexml
+SPELL_FAILED_ITEM_NOT_READY	string	framexml
+SPELL_FAILED_LEVEL_REQUIREMENT	string	framexml
+SPELL_FAILED_LEVEL_REQUIREMENT_PET	string	framexml
+SPELL_FAILED_LINE_OF_SIGHT	string	framexml
+SPELL_FAILED_LOWLEVEL	string	framexml
+SPELL_FAILED_LOW_CASTLEVEL	string	framexml
+SPELL_FAILED_MAINHAND_EMPTY	string	framexml
+SPELL_FAILED_MIN_SKILL	string	framexml
+SPELL_FAILED_MOVING	string	framexml
+SPELL_FAILED_NEED_AMMO	string	framexml
+SPELL_FAILED_NEED_AMMO_POUCH	string	framexml
+SPELL_FAILED_NEED_EXOTIC_AMMO	string	framexml
+SPELL_FAILED_NOPATH	string	framexml
+SPELL_FAILED_NOTHING_TO_DISPEL	string	framexml
+SPELL_FAILED_NOTHING_TO_STEAL	string	framexml
+SPELL_FAILED_NOT_BEHIND	string	framexml
+SPELL_FAILED_NOT_FISHABLE	string	framexml
+SPELL_FAILED_NOT_HERE	string	framexml
+SPELL_FAILED_NOT_INFRONT	string	framexml
+SPELL_FAILED_NOT_IN_CONTROL	string	framexml
+SPELL_FAILED_NOT_KNOWN	string	framexml
+SPELL_FAILED_NOT_MOUNTED	string	framexml
+SPELL_FAILED_NOT_ON_TAXI	string	framexml
+SPELL_FAILED_NOT_ON_TRANSPORT	string	framexml
+SPELL_FAILED_NOT_READY	string	framexml
+SPELL_FAILED_NOT_SHAPESHIFT	string	framexml
+SPELL_FAILED_NOT_STANDING	string	framexml
+SPELL_FAILED_NOT_TRADEABLE	string	framexml
+SPELL_FAILED_NOT_TRADING	string	framexml
+SPELL_FAILED_NOT_UNSHEATHED	string	framexml
+SPELL_FAILED_NOT_WHILE_FATIGUED	string	framexml
+SPELL_FAILED_NOT_WHILE_GHOST	string	framexml
+SPELL_FAILED_NOT_WHILE_TRADING	string	framexml
+SPELL_FAILED_NO_AMMO	string	framexml
+SPELL_FAILED_NO_CHAMPION	string	framexml
+SPELL_FAILED_NO_CHARGES_REMAIN	string	framexml
+SPELL_FAILED_NO_COMBO_POINTS	string	framexml
+SPELL_FAILED_NO_DUELING	string	framexml
+SPELL_FAILED_NO_EDIBLE_CORPSES	string	framexml
+SPELL_FAILED_NO_ENDURANCE	string	framexml
+SPELL_FAILED_NO_FISH	string	framexml
+SPELL_FAILED_NO_ITEMS_WHILE_SHAPESHIFTED	string	framexml
+SPELL_FAILED_NO_MOUNTS_ALLOWED	string	framexml
+SPELL_FAILED_NO_PET	string	framexml
+SPELL_FAILED_ONLY_ABOVEWATER	string	framexml
+SPELL_FAILED_ONLY_BATTLEGROUNDS	string	framexml
+SPELL_FAILED_ONLY_DAYTIME	string	framexml
+SPELL_FAILED_ONLY_INDOORS	string	framexml
+SPELL_FAILED_ONLY_MOUNTED	string	framexml
+SPELL_FAILED_ONLY_NIGHTTIME	string	framexml
+SPELL_FAILED_ONLY_OUTDOORS	string	framexml
+SPELL_FAILED_ONLY_SHAPESHIFT	string	framexml
+SPELL_FAILED_ONLY_STEALTHED	string	framexml
+SPELL_FAILED_ONLY_UNDERWATER	string	framexml
+SPELL_FAILED_OUT_OF_RANGE	string	framexml
+SPELL_FAILED_PACIFIED	string	framexml
+SPELL_FAILED_POSSESSED	string	framexml
+SPELL_FAILED_PREVENTED_BY_MECHANIC	string	framexml
+SPELL_FAILED_PROSPECT_NEED_MORE	string	framexml
+SPELL_FAILED_PROSPECT_WHILE_LOOTING	string	framexml
+SPELL_FAILED_REAGENTS	string	framexml
+SPELL_FAILED_REPUTATION	string	framexml
+SPELL_FAILED_REQUIRES_AREA	string	framexml
+SPELL_FAILED_REQUIRES_SPELL_FOCUS	string	framexml
+SPELL_FAILED_ROOTED	string	framexml
+SPELL_FAILED_SILENCED	string	framexml
+SPELL_FAILED_SPELL_IN_PROGRESS	string	framexml
+SPELL_FAILED_SPELL_LEARNED	string	framexml
+SPELL_FAILED_SPELL_UNAVAILABLE	string	framexml
+SPELL_FAILED_SPELL_UNAVAILABLE_PET	string	framexml
+SPELL_FAILED_STUNNED	string	framexml
+SPELL_FAILED_TARGETS_DEAD	string	framexml
+SPELL_FAILED_TARGET_AFFECTING_COMBAT	string	framexml
+SPELL_FAILED_TARGET_AURASTATE	string	framexml
+SPELL_FAILED_TARGET_DUELING	string	framexml
+SPELL_FAILED_TARGET_ENEMY	string	framexml
+SPELL_FAILED_TARGET_ENRAGED	string	framexml
+SPELL_FAILED_TARGET_FREEFORALL	string	framexml
+SPELL_FAILED_TARGET_FRIENDLY	string	framexml
+SPELL_FAILED_TARGET_IN_COMBAT	string	framexml
+SPELL_FAILED_TARGET_IS_PLAYER	string	framexml
+SPELL_FAILED_TARGET_NOT_DEAD	string	framexml
+SPELL_FAILED_TARGET_NOT_GHOST	string	framexml
+SPELL_FAILED_TARGET_NOT_IN_INSTANCE	string	framexml
+SPELL_FAILED_TARGET_NOT_IN_PARTY	string	framexml
+SPELL_FAILED_TARGET_NOT_IN_RAID	string	framexml
+SPELL_FAILED_TARGET_NOT_LOOTED	string	framexml
+SPELL_FAILED_TARGET_NOT_PLAYER	string	framexml
+SPELL_FAILED_TARGET_NO_POCKETS	string	framexml
+SPELL_FAILED_TARGET_NO_WEAPONS	string	framexml
+SPELL_FAILED_TARGET_UNSKINNABLE	string	framexml
+SPELL_FAILED_TOO_CLOSE	string	framexml
+SPELL_FAILED_TOO_MANY_OF_ITEM	string	framexml
+SPELL_FAILED_TOO_MANY_SKILLS	string	framexml
+SPELL_FAILED_TOTEMS	string	framexml
+SPELL_FAILED_TRAINING_POINTS	string	framexml
+SPELL_FAILED_TRANSFORM_UNUSABLE	string	framexml
+SPELL_FAILED_TRY_AGAIN	string	framexml
+SPELL_FAILED_UNIT_NOT_BEHIND	string	framexml
+SPELL_FAILED_UNIT_NOT_INFRONT	string	framexml
+SPELL_FAILED_UNKNOWN	string	framexml
+SPELL_FAILED_WRONG_PET_FOOD	string	framexml
+SPELL_FAILED_WRONG_WEATHER	string	framexml
+SPELL_INSTANT_EFFECT	string	framexml
+SPELL_LASTING_EFFECT	string	framexml
+SPELL_MESSAGES	string	framexml
+SPELL_NOT_SHAPESHIFTED	string	framexml
+SPELL_NOT_SHAPESHIFTED_NOSPACE	string	framexml
+SPELL_ON_NEXT_RANGED	string	framexml
+SPELL_ON_NEXT_SWING	string	framexml
+SPELL_OTHER_MESSAGES	string	framexml
+SPELL_PASSIVE	string	framexml
+SPELL_PASSIVE_EFFECT	string	framexml
+SPELL_POINTS_SPREAD_TEMPLATE	string	framexml
+SPELL_RANGE	string	framexml
+SPELL_RANGE_AREA	string	framexml
+SPELL_REAGENTS	string	framexml
+SPELL_RECAST_TIME_INSTANT	string	framexml
+SPELL_RECAST_TIME_MIN	string	framexml
+SPELL_RECAST_TIME_SEC	string	framexml
+SPELL_REQUIRED_FORM	string	framexml
+SPELL_REQUIRED_FORM_NOSPACE	string	framexml
+SPELL_SCHOOL0_CAP	string	framexml
+SPELL_SCHOOL0_NAME	string	framexml
+SPELL_SCHOOL1_CAP	string	framexml
+SPELL_SCHOOL1_NAME	string	framexml
+SPELL_SCHOOL2_CAP	string	framexml
+SPELL_SCHOOL2_NAME	string	framexml
+SPELL_SCHOOL3_CAP	string	framexml
+SPELL_SCHOOL3_NAME	string	framexml
+SPELL_SCHOOL4_CAP	string	framexml
+SPELL_SCHOOL4_NAME	string	framexml
+SPELL_SCHOOL5_CAP	string	framexml
+SPELL_SCHOOL5_NAME	string	framexml
+SPELL_SCHOOL6_CAP	string	framexml
+SPELL_SCHOOL6_NAME	string	framexml
+SPELL_SCHOOLALL	string	framexml
+SPELL_SCHOOLMAGICAL	string	framexml
+SPELL_SKILL_LINE	string	framexml
+SPELL_STAT0_NAME	string	framexml
+SPELL_STAT1_NAME	string	framexml
+SPELL_STAT2_NAME	string	framexml
+SPELL_STAT3_NAME	string	framexml
+SPELL_STAT4_NAME	string	framexml
+SPELL_STATALL	string	framexml
+SPELL_TARGET_CENTER_CASTER	string	framexml
+SPELL_TARGET_CENTER_LOC	string	framexml
+SPELL_TARGET_CHAIN_TEMPLATE	string	framexml
+SPELL_TARGET_CONE_TEMPLATE	string	framexml
+SPELL_TARGET_CREATURE_TYPE12_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE13_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE1_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE2_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE3_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE8_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE_DEAD12_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE_DEAD13_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE_DEAD1_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE_DEAD2_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE_DEAD3_DESC	string	framexml
+SPELL_TARGET_CREATURE_TYPE_DEAD8_DESC	string	framexml
+SPELL_TARGET_MULTIPLE_TEMPLATE	string	framexml
+SPELL_TARGET_TEMPLATE	string	framexml
+SPELL_TARGET_TYPE0_DESC	string	framexml
+SPELL_TARGET_TYPE10_DESC	string	framexml
+SPELL_TARGET_TYPE11_DESC	string	framexml
+SPELL_TARGET_TYPE12_DESC	string	framexml
+SPELL_TARGET_TYPE13_DESC	string	framexml
+SPELL_TARGET_TYPE14_DESC	string	framexml
+SPELL_TARGET_TYPE15_DESC	string	framexml
+SPELL_TARGET_TYPE16_DESC	string	framexml
+SPELL_TARGET_TYPE17_DESC	string	framexml
+SPELL_TARGET_TYPE1_DESC	string	framexml
+SPELL_TARGET_TYPE2_DESC	string	framexml
+SPELL_TARGET_TYPE3_DESC	string	framexml
+SPELL_TARGET_TYPE4_DESC	string	framexml
+SPELL_TARGET_TYPE5_DESC	string	framexml
+SPELL_TARGET_TYPE6_DESC	string	framexml
+SPELL_TARGET_TYPE7_DESC	string	framexml
+SPELL_TARGET_TYPE8_DESC	string	framexml
+SPELL_TARGET_TYPE9_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD11_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD12_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD13_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD14_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD16_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD17_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD1_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD2_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD3_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD4_DESC	string	framexml
+SPELL_TARGET_TYPE_DEAD8_DESC	string	framexml
+SPELL_TIMER	string	framexml
+SPELL_TIME_REMAINING_DAYS	string	framexml
+SPELL_TIME_REMAINING_DAYS_P1	string	framexml
+SPELL_TIME_REMAINING_HOURS	string	framexml
+SPELL_TIME_REMAINING_HOURS_P1	string	framexml
+SPELL_TIME_REMAINING_MIN	string	framexml
+SPELL_TIME_REMAINING_MIN_P1	string	framexml
+SPELL_TIME_REMAINING_SEC	string	framexml
+SPELL_TIME_REMAINING_SEC_P1	string	framexml
+SPELL_TOTEMS	string	framexml
+SPELL_USE_ALL_ENERGY	string	framexml
+SPELL_USE_ALL_FOCUS	string	framexml
+SPELL_USE_ALL_HEALTH	string	framexml
+SPELL_USE_ALL_MANA	string	framexml
+SPELL_USE_ALL_RAGE	string	framexml
+SPIRIT_COLON	string	framexml
+SPIRIT_TOOLTIP	string	framexml
+STABLED_PETS	string	framexml
+STABLES	string	framexml
+STABLE_SLOT_TEXT	string	framexml
+STAMINA_COLON	string	framexml
+STAMINA_TOOLTIP	string	framexml
+STANDARD_TEXT_FONT	string	framexml
+STANDING	string	framexml
+STARTING_PRICE	string	framexml
+STARTUP_TEXT_LINE1	string	framexml
+STARTUP_TEXT_LINE2	string	framexml
+STARTUP_TEXT_LINE3	string	framexml
+STARTUP_TEXT_LINE4	string	framexml
+STATE_AlwaysShowMultiBars	lod	framexml
+STATE_AlwaysShowMultibars	lod	framexml
+STATE_MULTI_ACTIONBAR_1	lod	framexml
+STATE_MultiBar1	lod	framexml
+STATE_MultiBar2	lod	framexml
+STATE_MultiBar3	lod	framexml
+STATE_MultiBar4	lod	framexml
+STATICPOPUP_NUMDIALOGS	number	framexml
+STATIONERYITEMS_TO_DISPLAY	number	framexml
+STATIONERY_ICON_ROW_HEIGHT	number	framexml
+STATIONERY_PATH	string	framexml
+STATSFRAME_UPDATE_TIME	number	framexml
+STATS_LABEL	string	framexml
+STATUS_BAR_TEXT	string	framexml
+STAT_TEMPLATE	string	framexml
+STOP_IGNORE	string	framexml
+STRENGTH_COLON	string	framexml
+STRENGTH_TOOLTIP	string	framexml
+STUCK_BUTTON2_TEXT	string	framexml
+STUCK_BUTTON_TEXT	string	framexml
+STUCK_OPTION	string	framexml
+STUN	string	framexml
+STUNNED	string	framexml
+STUN_CAPS	string	framexml
+SUBMIT	string	framexml
+SUGGESTFRAME_TITLE	string	framexml
+SUGGEST_SUBMITTED	string	framexml
+SUGGEST_SUBMIT_FAILED	string	framexml
+SUGGEST_TOOLTIP_TEXT	string	framexml
+SYSTEM_MESSAGES	string	framexml
+SaveBindings	function	engine
+SaveView	function	engine
+Screenshot	function	engine
+ScreenshotStatus	table	framexml
+ScreenshotStatusText	table	framexml
+ScreenshotStatus_OnEvent	function	framexml
+ScreenshotStatus_OnLoad	function	framexml
+ScreenshotStatus_OnUpdate	function	framexml
+ScriptErrors	table	framexml
+ScriptErrorsButton	table	framexml
+ScriptErrors_Message	table	framexml
+ScrollFrameTemplate_OnMouseWheel	function	framexml
+ScrollFrame_OnLoad	function	framexml
+ScrollFrame_OnScrollRangeChanged	function	framexml
+ScrollingEdit_OnCursorChanged	function	framexml
+ScrollingEdit_OnTextChanged	function	framexml
+ScrollingEdit_OnUpdate	function	framexml
+SecondsToTime	function	framexml
+SecondsToTimeAbbrev	function	framexml
+SelectActiveQuest	function	engine
+SelectAvailableQuest	function	engine
+SelectCraft	function	engine
+SelectGossipActiveQuest	function	engine
+SelectGossipAvailableQuest	function	engine
+SelectGossipOption	function	engine
+SelectPackage	function	engine
+SelectQuestLogEntry	function	engine
+SelectStationery	function	engine
+SelectTradeSkill	function	engine
+SelectTrainerService	function	engine
+SendAddonMessage	function	engine
+SendChatMessage	function	engine
+SendMail	function	engine
+SendMailBodyEditBox	table	framexml
+SendMailCODButton	table	framexml
+SendMailCODButtonText	table	framexml
+SendMailCancelButton	table	framexml
+SendMailCancelButtonText	table	framexml
+SendMailCostMoneyFrame	table	framexml
+SendMailCostMoneyFrameCopperButton	table	framexml
+SendMailCostMoneyFrameCopperButtonText	table	framexml
+SendMailCostMoneyFrameGoldButton	table	framexml
+SendMailCostMoneyFrameGoldButtonText	table	framexml
+SendMailCostMoneyFrameSilverButton	table	framexml
+SendMailCostMoneyFrameSilverButtonText	table	framexml
+SendMailErrorCoin	table	framexml
+SendMailErrorText	table	framexml
+SendMailFrame	table	framexml
+SendMailFrame_CanSend	function	framexml
+SendMailFrame_Reset	function	framexml
+SendMailFrame_SendMail	function	framexml
+SendMailFrame_SendeeAutocomplete	function	framexml
+SendMailFrame_Update	function	framexml
+SendMailHorizontalBarLeft	table	framexml
+SendMailMailButton	table	framexml
+SendMailMailButtonText	table	framexml
+SendMailMailButton_OnClick	function	framexml
+SendMailMoney	table	framexml
+SendMailMoneyCopper	table	framexml
+SendMailMoneyCopperLeft	table	framexml
+SendMailMoneyCopperMiddle	table	framexml
+SendMailMoneyCopperRight	table	framexml
+SendMailMoneyFrame	table	framexml
+SendMailMoneyFrameCopperButton	table	framexml
+SendMailMoneyFrameCopperButtonText	table	framexml
+SendMailMoneyFrameGoldButton	table	framexml
+SendMailMoneyFrameGoldButtonText	table	framexml
+SendMailMoneyFrameSilverButton	table	framexml
+SendMailMoneyFrameSilverButtonText	table	framexml
+SendMailMoneyGold	table	framexml
+SendMailMoneyGoldLeft	table	framexml
+SendMailMoneyGoldMiddle	table	framexml
+SendMailMoneyGoldRight	table	framexml
+SendMailMoneySilver	table	framexml
+SendMailMoneySilverLeft	table	framexml
+SendMailMoneySilverMiddle	table	framexml
+SendMailMoneySilverRight	table	framexml
+SendMailMoneyText	table	framexml
+SendMailNameEditBox	table	framexml
+SendMailNameEditBoxLeft	table	framexml
+SendMailNameEditBoxMiddle	table	framexml
+SendMailNameEditBoxRight	table	framexml
+SendMailPackageButton	table	framexml
+SendMailPackageButtonCount	table	framexml
+SendMailPackageButton_OnClick	function	framexml
+SendMailRadioButtonTemplate	lod	framexml
+SendMailRadioButton_OnClick	function	framexml
+SendMailScrollChildFrame	table	framexml
+SendMailScrollFrame	table	framexml
+SendMailScrollFrameScrollBar	table	framexml
+SendMailScrollFrameScrollBarScrollDownButton	table	framexml
+SendMailScrollFrameScrollBarScrollUpButton	table	framexml
+SendMailScrollFrameScrollBarThumbTexture	table	framexml
+SendMailSendMoneyButton	table	framexml
+SendMailSendMoneyButtonText	table	framexml
+SendMailStationeryButton	lod	framexml
+SendMailSubjectEditBox	table	framexml
+SendMailSubjectEditBoxLeft	table	framexml
+SendMailSubjectEditBoxMiddle	table	framexml
+SendMailSubjectEditBoxRight	table	framexml
+SendMailTitleText	table	framexml
+SendWho	function	engine
+SetAbandonQuest	function	engine
+SetActionBarToggles	function	engine
+SetAuctionDressUpBackground	lod	framexml
+SetBagPortaitTexture	function	engine
+SetBaseMip	function	engine
+SetBattlefieldScoreFaction	function	engine
+SetBinding	function	engine
+SetButtonPulse	function	framexml
+SetCVar	function	engine
+SetCenterFrame	function	framexml
+SetChannelOwner	function	engine
+SetChannelPassword	function	engine
+SetChatMouseOverDelay	function	framexml
+SetChatWindowAlpha	function	engine
+SetChatWindowColor	function	engine
+SetChatWindowDocked	function	engine
+SetChatWindowLocked	function	engine
+SetChatWindowName	function	engine
+SetChatWindowShown	function	engine
+SetChatWindowSize	function	engine
+SetConsoleKey	function	engine
+SetCursor	function	engine
+SetDesaturation	function	framexml
+SetDoodadAnim	function	engine
+SetDoublewideFrame	function	framexml
+SetDressUpBackground	function	framexml
+SetEuropeanNumbers	function	engine
+SetFactionActive	function	engine
+SetFactionInactive	function	engine
+SetFarclip	function	engine
+SetFullScreenFrame	function	framexml
+SetGamma	function	engine
+SetGuildInfoText	function	engine
+SetGuildRecruitmentMode	function	engine
+SetGuildRosterSelection	function	engine
+SetGuildRosterShowOffline	function	engine
+SetInventoryPortaitTexture	function	engine
+SetItemButtonCount	function	framexml
+SetItemButtonDesaturated	function	framexml
+SetItemButtonNameFrameVertexColor	function	framexml
+SetItemButtonNormalTextureVertexColor	function	framexml
+SetItemButtonSlotVertexColor	function	framexml
+SetItemButtonStock	function	framexml
+SetItemButtonTexture	function	framexml
+SetItemButtonTextureVertexColor	function	framexml
+SetItemRef	function	framexml
+SetLayoutMode	function	engine
+SetLeftFrame	function	framexml
+SetLookingForGroup	function	engine
+SetLootMethod	function	engine
+SetLootPortrait	function	engine
+SetLootThreshold	function	engine
+SetMapToCurrentZone	function	engine
+SetMapZoom	function	engine
+SetMoneyFrameColor	function	framexml
+SetMultisampleFormat	function	engine
+SetPetStablePaperdoll	function	engine
+SetPortraitTexture	function	engine
+SetPortraitToTexture	function	engine
+SetRaidRosterSelection	function	engine
+SetRaidSubgroup	function	engine
+SetRaidTarget	function	engine
+SetRaidTargetIcon	function	framexml
+SetRaidTargetIconTexture	function	framexml
+SetScreenResolution	function	engine
+SetSelectedAuctionItem	function	engine
+SetSelectedBattlefield	function	engine
+SetSelectedFaction	function	engine
+SetSelectedFriend	function	engine
+SetSelectedIgnore	function	engine
+SetSelectedSkill	function	engine
+SetSendMailCOD	function	engine
+SetSendMailMoney	function	engine
+SetTalentButtonLocation	lod	framexml
+SetTaxiMap	function	engine
+SetTerrainMip	function	engine
+SetTexLodBias	function	engine
+SetTextStatusBarText	function	framexml
+SetTextStatusBarTextPrefix	function	framexml
+SetTextStatusBarTextZeroText	function	framexml
+SetTooltipMoney	function	framexml
+SetTradeMoney	function	engine
+SetTradeSkillInvSlotFilter	function	engine
+SetTradeSkillSubClassFilter	function	engine
+SetTrainerServiceTypeFilter	function	engine
+SetTrainerSkillLineFilter	function	engine
+SetView	function	engine
+SetWatchedFactionIndex	function	engine
+SetWaterDetail	function	engine
+SetWhoToUI	function	engine
+SetWorldDetail	function	engine
+SetZoneText	function	framexml
+SetupFullscreenScale	function	engine
+ShapeshiftBarFrame	table	framexml
+ShapeshiftBarLeft	table	framexml
+ShapeshiftBarMiddle	table	framexml
+ShapeshiftBarRight	table	framexml
+ShapeshiftBar_ChangeForm	function	framexml
+ShapeshiftBar_OnEvent	function	framexml
+ShapeshiftBar_OnLoad	function	framexml
+ShapeshiftBar_Update	function	framexml
+ShapeshiftBar_UpdatePosition	function	framexml
+ShapeshiftBar_UpdateState	function	framexml
+ShapeshiftButton1	table	framexml
+ShapeshiftButton10	table	framexml
+ShapeshiftButton10Border	table	framexml
+ShapeshiftButton10Cooldown	table	framexml
+ShapeshiftButton10Count	table	framexml
+ShapeshiftButton10Flash	table	framexml
+ShapeshiftButton10HotKey	table	framexml
+ShapeshiftButton10Icon	table	framexml
+ShapeshiftButton10Name	table	framexml
+ShapeshiftButton10NormalTexture	table	framexml
+ShapeshiftButton1Border	table	framexml
+ShapeshiftButton1Cooldown	table	framexml
+ShapeshiftButton1Count	table	framexml
+ShapeshiftButton1Flash	table	framexml
+ShapeshiftButton1HotKey	table	framexml
+ShapeshiftButton1Icon	table	framexml
+ShapeshiftButton1Name	table	framexml
+ShapeshiftButton1NormalTexture	table	framexml
+ShapeshiftButton2	table	framexml
+ShapeshiftButton2Border	table	framexml
+ShapeshiftButton2Cooldown	table	framexml
+ShapeshiftButton2Count	table	framexml
+ShapeshiftButton2Flash	table	framexml
+ShapeshiftButton2HotKey	table	framexml
+ShapeshiftButton2Icon	table	framexml
+ShapeshiftButton2Name	table	framexml
+ShapeshiftButton2NormalTexture	table	framexml
+ShapeshiftButton3	table	framexml
+ShapeshiftButton3Border	table	framexml
+ShapeshiftButton3Cooldown	table	framexml
+ShapeshiftButton3Count	table	framexml
+ShapeshiftButton3Flash	table	framexml
+ShapeshiftButton3HotKey	table	framexml
+ShapeshiftButton3Icon	table	framexml
+ShapeshiftButton3Name	table	framexml
+ShapeshiftButton3NormalTexture	table	framexml
+ShapeshiftButton4	table	framexml
+ShapeshiftButton4Border	table	framexml
+ShapeshiftButton4Cooldown	table	framexml
+ShapeshiftButton4Count	table	framexml
+ShapeshiftButton4Flash	table	framexml
+ShapeshiftButton4HotKey	table	framexml
+ShapeshiftButton4Icon	table	framexml
+ShapeshiftButton4Name	table	framexml
+ShapeshiftButton4NormalTexture	table	framexml
+ShapeshiftButton5	table	framexml
+ShapeshiftButton5Border	table	framexml
+ShapeshiftButton5Cooldown	table	framexml
+ShapeshiftButton5Count	table	framexml
+ShapeshiftButton5Flash	table	framexml
+ShapeshiftButton5HotKey	table	framexml
+ShapeshiftButton5Icon	table	framexml
+ShapeshiftButton5Name	table	framexml
+ShapeshiftButton5NormalTexture	table	framexml
+ShapeshiftButton6	table	framexml
+ShapeshiftButton6Border	table	framexml
+ShapeshiftButton6Cooldown	table	framexml
+ShapeshiftButton6Count	table	framexml
+ShapeshiftButton6Flash	table	framexml
+ShapeshiftButton6HotKey	table	framexml
+ShapeshiftButton6Icon	table	framexml
+ShapeshiftButton6Name	table	framexml
+ShapeshiftButton6NormalTexture	table	framexml
+ShapeshiftButton7	table	framexml
+ShapeshiftButton7Border	table	framexml
+ShapeshiftButton7Cooldown	table	framexml
+ShapeshiftButton7Count	table	framexml
+ShapeshiftButton7Flash	table	framexml
+ShapeshiftButton7HotKey	table	framexml
+ShapeshiftButton7Icon	table	framexml
+ShapeshiftButton7Name	table	framexml
+ShapeshiftButton7NormalTexture	table	framexml
+ShapeshiftButton8	table	framexml
+ShapeshiftButton8Border	table	framexml
+ShapeshiftButton8Cooldown	table	framexml
+ShapeshiftButton8Count	table	framexml
+ShapeshiftButton8Flash	table	framexml
+ShapeshiftButton8HotKey	table	framexml
+ShapeshiftButton8Icon	table	framexml
+ShapeshiftButton8Name	table	framexml
+ShapeshiftButton8NormalTexture	table	framexml
+ShapeshiftButton9	table	framexml
+ShapeshiftButton9Border	table	framexml
+ShapeshiftButton9Cooldown	table	framexml
+ShapeshiftButton9Count	table	framexml
+ShapeshiftButton9Flash	table	framexml
+ShapeshiftButton9HotKey	table	framexml
+ShapeshiftButton9Icon	table	framexml
+ShapeshiftButton9Name	table	framexml
+ShapeshiftButton9NormalTexture	table	framexml
+ShapeshiftButtonTemplate	lod	framexml
+ShoppingTooltip1	table	framexml
+ShoppingTooltip1MoneyFrame	table	framexml
+ShoppingTooltip1MoneyFrameCopperButton	table	framexml
+ShoppingTooltip1MoneyFrameCopperButtonText	table	framexml
+ShoppingTooltip1MoneyFrameGoldButton	table	framexml
+ShoppingTooltip1MoneyFrameGoldButtonText	table	framexml
+ShoppingTooltip1MoneyFrameSilverButton	table	framexml
+ShoppingTooltip1MoneyFrameSilverButtonText	table	framexml
+ShoppingTooltip1TextLeft1	table	framexml
+ShoppingTooltip1TextLeft10	table	framexml
+ShoppingTooltip1TextLeft11	table	framexml
+ShoppingTooltip1TextLeft12	table	framexml
+ShoppingTooltip1TextLeft13	table	framexml
+ShoppingTooltip1TextLeft14	table	framexml
+ShoppingTooltip1TextLeft15	table	framexml
+ShoppingTooltip1TextLeft16	table	framexml
+ShoppingTooltip1TextLeft17	table	framexml
+ShoppingTooltip1TextLeft18	table	framexml
+ShoppingTooltip1TextLeft19	table	framexml
+ShoppingTooltip1TextLeft2	table	framexml
+ShoppingTooltip1TextLeft20	table	framexml
+ShoppingTooltip1TextLeft21	table	framexml
+ShoppingTooltip1TextLeft22	table	framexml
+ShoppingTooltip1TextLeft23	table	framexml
+ShoppingTooltip1TextLeft24	table	framexml
+ShoppingTooltip1TextLeft25	table	framexml
+ShoppingTooltip1TextLeft26	table	framexml
+ShoppingTooltip1TextLeft27	table	framexml
+ShoppingTooltip1TextLeft28	table	framexml
+ShoppingTooltip1TextLeft29	table	framexml
+ShoppingTooltip1TextLeft3	table	framexml
+ShoppingTooltip1TextLeft30	table	framexml
+ShoppingTooltip1TextLeft4	table	framexml
+ShoppingTooltip1TextLeft5	table	framexml
+ShoppingTooltip1TextLeft6	table	framexml
+ShoppingTooltip1TextLeft7	table	framexml
+ShoppingTooltip1TextLeft8	table	framexml
+ShoppingTooltip1TextLeft9	table	framexml
+ShoppingTooltip1TextRight1	table	framexml
+ShoppingTooltip1TextRight10	table	framexml
+ShoppingTooltip1TextRight11	table	framexml
+ShoppingTooltip1TextRight12	table	framexml
+ShoppingTooltip1TextRight13	table	framexml
+ShoppingTooltip1TextRight14	table	framexml
+ShoppingTooltip1TextRight15	table	framexml
+ShoppingTooltip1TextRight16	table	framexml
+ShoppingTooltip1TextRight17	table	framexml
+ShoppingTooltip1TextRight18	table	framexml
+ShoppingTooltip1TextRight19	table	framexml
+ShoppingTooltip1TextRight2	table	framexml
+ShoppingTooltip1TextRight20	table	framexml
+ShoppingTooltip1TextRight21	table	framexml
+ShoppingTooltip1TextRight22	table	framexml
+ShoppingTooltip1TextRight23	table	framexml
+ShoppingTooltip1TextRight24	table	framexml
+ShoppingTooltip1TextRight25	table	framexml
+ShoppingTooltip1TextRight26	table	framexml
+ShoppingTooltip1TextRight27	table	framexml
+ShoppingTooltip1TextRight28	table	framexml
+ShoppingTooltip1TextRight29	table	framexml
+ShoppingTooltip1TextRight3	table	framexml
+ShoppingTooltip1TextRight30	table	framexml
+ShoppingTooltip1TextRight4	table	framexml
+ShoppingTooltip1TextRight5	table	framexml
+ShoppingTooltip1TextRight6	table	framexml
+ShoppingTooltip1TextRight7	table	framexml
+ShoppingTooltip1TextRight8	table	framexml
+ShoppingTooltip1TextRight9	table	framexml
+ShoppingTooltip1Texture1	table	framexml
+ShoppingTooltip1Texture2	table	framexml
+ShoppingTooltip1Texture3	table	framexml
+ShoppingTooltip2	table	framexml
+ShoppingTooltip2MoneyFrame	table	framexml
+ShoppingTooltip2MoneyFrameCopperButton	table	framexml
+ShoppingTooltip2MoneyFrameCopperButtonText	table	framexml
+ShoppingTooltip2MoneyFrameGoldButton	table	framexml
+ShoppingTooltip2MoneyFrameGoldButtonText	table	framexml
+ShoppingTooltip2MoneyFrameSilverButton	table	framexml
+ShoppingTooltip2MoneyFrameSilverButtonText	table	framexml
+ShoppingTooltip2TextLeft1	table	framexml
+ShoppingTooltip2TextLeft10	table	framexml
+ShoppingTooltip2TextLeft11	table	framexml
+ShoppingTooltip2TextLeft12	table	framexml
+ShoppingTooltip2TextLeft13	table	framexml
+ShoppingTooltip2TextLeft14	table	framexml
+ShoppingTooltip2TextLeft15	table	framexml
+ShoppingTooltip2TextLeft16	table	framexml
+ShoppingTooltip2TextLeft17	table	framexml
+ShoppingTooltip2TextLeft18	table	framexml
+ShoppingTooltip2TextLeft19	table	framexml
+ShoppingTooltip2TextLeft2	table	framexml
+ShoppingTooltip2TextLeft20	table	framexml
+ShoppingTooltip2TextLeft21	table	framexml
+ShoppingTooltip2TextLeft22	table	framexml
+ShoppingTooltip2TextLeft23	table	framexml
+ShoppingTooltip2TextLeft24	table	framexml
+ShoppingTooltip2TextLeft25	table	framexml
+ShoppingTooltip2TextLeft26	table	framexml
+ShoppingTooltip2TextLeft27	table	framexml
+ShoppingTooltip2TextLeft28	table	framexml
+ShoppingTooltip2TextLeft29	table	framexml
+ShoppingTooltip2TextLeft3	table	framexml
+ShoppingTooltip2TextLeft30	table	framexml
+ShoppingTooltip2TextLeft4	table	framexml
+ShoppingTooltip2TextLeft5	table	framexml
+ShoppingTooltip2TextLeft6	table	framexml
+ShoppingTooltip2TextLeft7	table	framexml
+ShoppingTooltip2TextLeft8	table	framexml
+ShoppingTooltip2TextLeft9	table	framexml
+ShoppingTooltip2TextRight1	table	framexml
+ShoppingTooltip2TextRight10	table	framexml
+ShoppingTooltip2TextRight11	table	framexml
+ShoppingTooltip2TextRight12	table	framexml
+ShoppingTooltip2TextRight13	table	framexml
+ShoppingTooltip2TextRight14	table	framexml
+ShoppingTooltip2TextRight15	table	framexml
+ShoppingTooltip2TextRight16	table	framexml
+ShoppingTooltip2TextRight17	table	framexml
+ShoppingTooltip2TextRight18	table	framexml
+ShoppingTooltip2TextRight19	table	framexml
+ShoppingTooltip2TextRight2	table	framexml
+ShoppingTooltip2TextRight20	table	framexml
+ShoppingTooltip2TextRight21	table	framexml
+ShoppingTooltip2TextRight22	table	framexml
+ShoppingTooltip2TextRight23	table	framexml
+ShoppingTooltip2TextRight24	table	framexml
+ShoppingTooltip2TextRight25	table	framexml
+ShoppingTooltip2TextRight26	table	framexml
+ShoppingTooltip2TextRight27	table	framexml
+ShoppingTooltip2TextRight28	table	framexml
+ShoppingTooltip2TextRight29	table	framexml
+ShoppingTooltip2TextRight3	table	framexml
+ShoppingTooltip2TextRight30	table	framexml
+ShoppingTooltip2TextRight4	table	framexml
+ShoppingTooltip2TextRight5	table	framexml
+ShoppingTooltip2TextRight6	table	framexml
+ShoppingTooltip2TextRight7	table	framexml
+ShoppingTooltip2TextRight8	table	framexml
+ShoppingTooltip2TextRight9	table	framexml
+ShoppingTooltip2Texture1	table	framexml
+ShoppingTooltip2Texture2	table	framexml
+ShoppingTooltip2Texture3	table	framexml
+ShoppingTooltipTemplate	lod	framexml
+ShowBattlefieldList	function	engine
+ShowBonusActionBar	function	framexml
+ShowBuybackSellCursor	function	engine
+ShowCloak	function	engine
+ShowContainerSellCursor	function	engine
+ShowFriendNameplates	function	engine
+ShowFriends	function	engine
+ShowHelm	function	engine
+ShowIgnorePanel	function	framexml
+ShowInspectCursor	function	engine
+ShowInventorySellCursor	function	engine
+ShowMacroFrame	function	framexml
+ShowMerchantSellCursor	function	engine
+ShowMiniWorldMapArrowFrame	function	engine
+ShowNameplates	function	engine
+ShowOnPlayerCheckButton	lod	framexml
+ShowPartyFrame	function	framexml
+ShowPetActionBar	function	framexml
+ShowReadyCheck	lod	framexml
+ShowRepairCursor	function	engine
+ShowTextStatusBarText	function	framexml
+ShowUIPanel	function	framexml
+ShowWatchedReputationBarText	function	framexml
+ShowWhoPanel	function	framexml
+ShowWorldMapArrowFrame	function	engine
+ShowingCloak	function	engine
+ShowingHelm	function	engine
+SignPetition	function	engine
+SitOrStand	function	engine
+SkillBar_OnClick	function	framexml
+SkillDetailCostText	table	framexml
+SkillDetailDescriptionText	table	framexml
+SkillDetailFrame_SetStatusBar	function	framexml
+SkillDetailScrollChildFrame	table	framexml
+SkillDetailScrollFrame	table	framexml
+SkillDetailScrollFrameScrollBar	table	framexml
+SkillDetailScrollFrameScrollBarScrollDownButton	table	framexml
+SkillDetailScrollFrameScrollBarScrollUpButton	table	framexml
+SkillDetailScrollFrameScrollBarThumbTexture	table	framexml
+SkillDetailStatusBar	table	framexml
+SkillDetailStatusBarBackground	table	framexml
+SkillDetailStatusBarBar	table	framexml
+SkillDetailStatusBarBorder	table	framexml
+SkillDetailStatusBarFillBar	table	framexml
+SkillDetailStatusBarLearnSkillButton	table	framexml
+SkillDetailStatusBarLeftArrow	table	framexml
+SkillDetailStatusBarRightArrow	table	framexml
+SkillDetailStatusBarSkillName	table	framexml
+SkillDetailStatusBarSkillRank	table	framexml
+SkillDetailStatusBarUnlearnButton	table	framexml
+SkillFrame	table	framexml
+SkillFrameAcceptButton	lod	framexml
+SkillFrameCancelButton	table	framexml
+SkillFrameCancelButtonText	table	framexml
+SkillFrameCollapseAllButton	table	framexml
+SkillFrameCollapseAllButtonNormalTexture	table	framexml
+SkillFrameExpandButtonFrame	table	framexml
+SkillFrameExpandTabLeft	table	framexml
+SkillFrameExpandTabMiddle	table	framexml
+SkillFrameExpandTabRight	table	framexml
+SkillFrameHorizontalBarLeft	table	framexml
+SkillFrame_OnEvent	function	framexml
+SkillFrame_OnLoad	function	framexml
+SkillFrame_OnShow	function	framexml
+SkillFrame_SetStatusBar	function	framexml
+SkillFrame_UpdateSkills	function	framexml
+SkillLabelTemplate	lod	framexml
+SkillListScrollFrame	table	framexml
+SkillListScrollFrameScrollBar	table	framexml
+SkillListScrollFrameScrollBarScrollDownButton	table	framexml
+SkillListScrollFrameScrollBarScrollUpButton	table	framexml
+SkillListScrollFrameScrollBarThumbTexture	table	framexml
+SkillListScrollFrameScrollChildFrame	table	framexml
+SkillRankFrame1	table	framexml
+SkillRankFrame10	table	framexml
+SkillRankFrame10Background	table	framexml
+SkillRankFrame10Bar	table	framexml
+SkillRankFrame10Border	table	framexml
+SkillRankFrame10BorderHighlight	table	framexml
+SkillRankFrame10BorderNormal	table	framexml
+SkillRankFrame10FillBar	table	framexml
+SkillRankFrame10SkillName	table	framexml
+SkillRankFrame10SkillRank	table	framexml
+SkillRankFrame11	table	framexml
+SkillRankFrame11Background	table	framexml
+SkillRankFrame11Bar	table	framexml
+SkillRankFrame11Border	table	framexml
+SkillRankFrame11BorderHighlight	table	framexml
+SkillRankFrame11BorderNormal	table	framexml
+SkillRankFrame11FillBar	table	framexml
+SkillRankFrame11SkillName	table	framexml
+SkillRankFrame11SkillRank	table	framexml
+SkillRankFrame12	table	framexml
+SkillRankFrame12Background	table	framexml
+SkillRankFrame12Bar	table	framexml
+SkillRankFrame12Border	table	framexml
+SkillRankFrame12BorderHighlight	table	framexml
+SkillRankFrame12BorderNormal	table	framexml
+SkillRankFrame12FillBar	table	framexml
+SkillRankFrame12SkillName	table	framexml
+SkillRankFrame12SkillRank	table	framexml
+SkillRankFrame1Background	table	framexml
+SkillRankFrame1Bar	table	framexml
+SkillRankFrame1Border	table	framexml
+SkillRankFrame1BorderHighlight	table	framexml
+SkillRankFrame1BorderNormal	table	framexml
+SkillRankFrame1FillBar	table	framexml
+SkillRankFrame1SkillName	table	framexml
+SkillRankFrame1SkillRank	table	framexml
+SkillRankFrame2	table	framexml
+SkillRankFrame2Background	table	framexml
+SkillRankFrame2Bar	table	framexml
+SkillRankFrame2Border	table	framexml
+SkillRankFrame2BorderHighlight	table	framexml
+SkillRankFrame2BorderNormal	table	framexml
+SkillRankFrame2FillBar	table	framexml
+SkillRankFrame2SkillName	table	framexml
+SkillRankFrame2SkillRank	table	framexml
+SkillRankFrame3	table	framexml
+SkillRankFrame3Background	table	framexml
+SkillRankFrame3Bar	table	framexml
+SkillRankFrame3Border	table	framexml
+SkillRankFrame3BorderHighlight	table	framexml
+SkillRankFrame3BorderNormal	table	framexml
+SkillRankFrame3FillBar	table	framexml
+SkillRankFrame3SkillName	table	framexml
+SkillRankFrame3SkillRank	table	framexml
+SkillRankFrame4	table	framexml
+SkillRankFrame4Background	table	framexml
+SkillRankFrame4Bar	table	framexml
+SkillRankFrame4Border	table	framexml
+SkillRankFrame4BorderHighlight	table	framexml
+SkillRankFrame4BorderNormal	table	framexml
+SkillRankFrame4FillBar	table	framexml
+SkillRankFrame4SkillName	table	framexml
+SkillRankFrame4SkillRank	table	framexml
+SkillRankFrame5	table	framexml
+SkillRankFrame5Background	table	framexml
+SkillRankFrame5Bar	table	framexml
+SkillRankFrame5Border	table	framexml
+SkillRankFrame5BorderHighlight	table	framexml
+SkillRankFrame5BorderNormal	table	framexml
+SkillRankFrame5FillBar	table	framexml
+SkillRankFrame5SkillName	table	framexml
+SkillRankFrame5SkillRank	table	framexml
+SkillRankFrame6	table	framexml
+SkillRankFrame6Background	table	framexml
+SkillRankFrame6Bar	table	framexml
+SkillRankFrame6Border	table	framexml
+SkillRankFrame6BorderHighlight	table	framexml
+SkillRankFrame6BorderNormal	table	framexml
+SkillRankFrame6FillBar	table	framexml
+SkillRankFrame6SkillName	table	framexml
+SkillRankFrame6SkillRank	table	framexml
+SkillRankFrame7	table	framexml
+SkillRankFrame7Background	table	framexml
+SkillRankFrame7Bar	table	framexml
+SkillRankFrame7Border	table	framexml
+SkillRankFrame7BorderHighlight	table	framexml
+SkillRankFrame7BorderNormal	table	framexml
+SkillRankFrame7FillBar	table	framexml
+SkillRankFrame7SkillName	table	framexml
+SkillRankFrame7SkillRank	table	framexml
+SkillRankFrame8	table	framexml
+SkillRankFrame8Background	table	framexml
+SkillRankFrame8Bar	table	framexml
+SkillRankFrame8Border	table	framexml
+SkillRankFrame8BorderHighlight	table	framexml
+SkillRankFrame8BorderNormal	table	framexml
+SkillRankFrame8FillBar	table	framexml
+SkillRankFrame8SkillName	table	framexml
+SkillRankFrame8SkillRank	table	framexml
+SkillRankFrame9	table	framexml
+SkillRankFrame9Background	table	framexml
+SkillRankFrame9Bar	table	framexml
+SkillRankFrame9Border	table	framexml
+SkillRankFrame9BorderHighlight	table	framexml
+SkillRankFrame9BorderNormal	table	framexml
+SkillRankFrame9FillBar	table	framexml
+SkillRankFrame9SkillName	table	framexml
+SkillRankFrame9SkillRank	table	framexml
+SkillSortButton	lod	framexml
+SkillStatusBarTemplate	lod	framexml
+SkillTypeLabel1	table	framexml
+SkillTypeLabel10	table	framexml
+SkillTypeLabel10NormalTexture	table	framexml
+SkillTypeLabel11	table	framexml
+SkillTypeLabel11NormalTexture	table	framexml
+SkillTypeLabel12	table	framexml
+SkillTypeLabel12NormalTexture	table	framexml
+SkillTypeLabel1NormalTexture	table	framexml
+SkillTypeLabel2	table	framexml
+SkillTypeLabel2NormalTexture	table	framexml
+SkillTypeLabel3	table	framexml
+SkillTypeLabel3NormalTexture	table	framexml
+SkillTypeLabel4	table	framexml
+SkillTypeLabel4NormalTexture	table	framexml
+SkillTypeLabel5	table	framexml
+SkillTypeLabel5NormalTexture	table	framexml
+SkillTypeLabel6	table	framexml
+SkillTypeLabel6NormalTexture	table	framexml
+SkillTypeLabel7	table	framexml
+SkillTypeLabel7NormalTexture	table	framexml
+SkillTypeLabel8	table	framexml
+SkillTypeLabel8NormalTexture	table	framexml
+SkillTypeLabel9	table	framexml
+SkillTypeLabel9NormalTexture	table	framexml
+SlashCmdList	table	framexml
+SlidingActionBarTexture0	table	framexml
+SlidingActionBarTexture1	table	framexml
+SmallMoneyFrameTemplate	lod	framexml
+SmallMoneyFrame_OnLoad	function	framexml
+SmallTextTooltip	table	framexml
+SmallTextTooltipText	table	framexml
+SocialsMicroButton	table	framexml
+SortAuctionItems	function	engine
+SortButton_UpdateArrow	lod	framexml
+SortGuildRoster	function	engine
+SortWho	function	engine
+SoundOptionsCheckButtonTemplate	lod	framexml
+SoundOptionsCheckButton_OnClick	function	framexml
+SoundOptionsFrame	table	framexml
+SoundOptionsFrameCancel	table	framexml
+SoundOptionsFrameCancelText	table	framexml
+SoundOptionsFrameCheckButton1	table	framexml
+SoundOptionsFrameCheckButton1Text	table	framexml
+SoundOptionsFrameCheckButton2	table	framexml
+SoundOptionsFrameCheckButton2Text	table	framexml
+SoundOptionsFrameCheckButton4	table	framexml
+SoundOptionsFrameCheckButton4Text	table	framexml
+SoundOptionsFrameCheckButton5	table	framexml
+SoundOptionsFrameCheckButton5Text	table	framexml
+SoundOptionsFrameCheckButton6	table	framexml
+SoundOptionsFrameCheckButton6Text	table	framexml
+SoundOptionsFrameCheckButton7	table	framexml
+SoundOptionsFrameCheckButton7Text	table	framexml
+SoundOptionsFrameCheckButton8	table	framexml
+SoundOptionsFrameCheckButton8Text	table	framexml
+SoundOptionsFrameCheckButtons	table	framexml
+SoundOptionsFrameDefaults	table	framexml
+SoundOptionsFrameDefaultsText	table	framexml
+SoundOptionsFrameHeader	table	framexml
+SoundOptionsFrameOkay	table	framexml
+SoundOptionsFrameOkayText	table	framexml
+SoundOptionsFrameSlider1	table	framexml
+SoundOptionsFrameSlider1High	table	framexml
+SoundOptionsFrameSlider1Low	table	framexml
+SoundOptionsFrameSlider1Text	table	framexml
+SoundOptionsFrameSlider1Thumb	table	framexml
+SoundOptionsFrameSlider2	table	framexml
+SoundOptionsFrameSlider2High	table	framexml
+SoundOptionsFrameSlider2Low	table	framexml
+SoundOptionsFrameSlider2Text	table	framexml
+SoundOptionsFrameSlider2Thumb	table	framexml
+SoundOptionsFrameSlider3	table	framexml
+SoundOptionsFrameSlider3High	table	framexml
+SoundOptionsFrameSlider3Low	table	framexml
+SoundOptionsFrameSlider3Text	table	framexml
+SoundOptionsFrameSlider3Thumb	table	framexml
+SoundOptionsFrameSlider4	table	framexml
+SoundOptionsFrameSlider4High	table	framexml
+SoundOptionsFrameSlider4Low	table	framexml
+SoundOptionsFrameSlider4Text	table	framexml
+SoundOptionsFrameSlider4Thumb	table	framexml
+SoundOptionsFrameSliders	table	framexml
+SoundOptionsFrame_Cancel	function	framexml
+SoundOptionsFrame_Init	function	framexml
+SoundOptionsFrame_Load	function	framexml
+SoundOptionsFrame_MasterVolumeDown	function	framexml
+SoundOptionsFrame_MasterVolumeUp	function	framexml
+SoundOptionsFrame_OnEvent	function	framexml
+SoundOptionsFrame_SetDefaults	function	framexml
+SoundOptionsFrame_ToggleMusic	function	framexml
+SoundOptionsFrame_ToggleSound	function	framexml
+SoundOptionsFrame_UpdateDependencies	function	framexml
+SoundOptionsSliderTemplate	lod	framexml
+SoundOptionsSlider_OnValueChanged	function	framexml
+SpellBookCloseButton	table	framexml
+SpellBookFrame	table	framexml
+SpellBookFrameTabButton1	table	framexml
+SpellBookFrameTabButton2	table	framexml
+SpellBookFrameTabButton3	table	framexml
+SpellBookFrameTabButtonTemplate	lod	framexml
+SpellBookFrame_OnEvent	function	framexml
+SpellBookFrame_OnHide	function	framexml
+SpellBookFrame_OnLoad	function	framexml
+SpellBookFrame_OnShow	function	framexml
+SpellBookFrame_SetTabType	function	framexml
+SpellBookFrame_Update	function	framexml
+SpellBookNextPageButton	table	framexml
+SpellBookPageText	table	framexml
+SpellBookPrevPageButton	table	framexml
+SpellBookSkillLineTab1	table	framexml
+SpellBookSkillLineTab1Flash	table	framexml
+SpellBookSkillLineTab2	table	framexml
+SpellBookSkillLineTab2Flash	table	framexml
+SpellBookSkillLineTab3	table	framexml
+SpellBookSkillLineTab3Flash	table	framexml
+SpellBookSkillLineTab4	table	framexml
+SpellBookSkillLineTab4Flash	table	framexml
+SpellBookSkillLineTab5	table	framexml
+SpellBookSkillLineTab5Flash	table	framexml
+SpellBookSkillLineTab6	table	framexml
+SpellBookSkillLineTab6Flash	table	framexml
+SpellBookSkillLineTab7	table	framexml
+SpellBookSkillLineTab7Flash	table	framexml
+SpellBookSkillLineTab8	table	framexml
+SpellBookSkillLineTab8Flash	table	framexml
+SpellBookSkillLineTabTemplate	lod	framexml
+SpellBookSkillLineTab_OnClick	function	framexml
+SpellBookTabFlashFrame	table	framexml
+SpellBookTitleText	table	framexml
+SpellBook_GetCurrentPage	function	framexml
+SpellBook_GetSpellID	function	framexml
+SpellBook_UpdatePageArrows	function	framexml
+SpellButton1	table	framexml
+SpellButton10	table	framexml
+SpellButton10AutoCast	table	framexml
+SpellButton10AutoCastable	table	framexml
+SpellButton10Background	table	framexml
+SpellButton10Cooldown	table	framexml
+SpellButton10Highlight	table	framexml
+SpellButton10IconTexture	table	framexml
+SpellButton10NormalTexture	table	framexml
+SpellButton10SpellName	table	framexml
+SpellButton10SubSpellName	table	framexml
+SpellButton11	table	framexml
+SpellButton11AutoCast	table	framexml
+SpellButton11AutoCastable	table	framexml
+SpellButton11Background	table	framexml
+SpellButton11Cooldown	table	framexml
+SpellButton11Highlight	table	framexml
+SpellButton11IconTexture	table	framexml
+SpellButton11NormalTexture	table	framexml
+SpellButton11SpellName	table	framexml
+SpellButton11SubSpellName	table	framexml
+SpellButton12	table	framexml
+SpellButton12AutoCast	table	framexml
+SpellButton12AutoCastable	table	framexml
+SpellButton12Background	table	framexml
+SpellButton12Cooldown	table	framexml
+SpellButton12Highlight	table	framexml
+SpellButton12IconTexture	table	framexml
+SpellButton12NormalTexture	table	framexml
+SpellButton12SpellName	table	framexml
+SpellButton12SubSpellName	table	framexml
+SpellButton1AutoCast	table	framexml
+SpellButton1AutoCastable	table	framexml
+SpellButton1Background	table	framexml
+SpellButton1Cooldown	table	framexml
+SpellButton1Highlight	table	framexml
+SpellButton1IconTexture	table	framexml
+SpellButton1NormalTexture	table	framexml
+SpellButton1SpellName	table	framexml
+SpellButton1SubSpellName	table	framexml
+SpellButton2	table	framexml
+SpellButton2AutoCast	table	framexml
+SpellButton2AutoCastable	table	framexml
+SpellButton2Background	table	framexml
+SpellButton2Cooldown	table	framexml
+SpellButton2Highlight	table	framexml
+SpellButton2IconTexture	table	framexml
+SpellButton2NormalTexture	table	framexml
+SpellButton2SpellName	table	framexml
+SpellButton2SubSpellName	table	framexml
+SpellButton3	table	framexml
+SpellButton3AutoCast	table	framexml
+SpellButton3AutoCastable	table	framexml
+SpellButton3Background	table	framexml
+SpellButton3Cooldown	table	framexml
+SpellButton3Highlight	table	framexml
+SpellButton3IconTexture	table	framexml
+SpellButton3NormalTexture	table	framexml
+SpellButton3SpellName	table	framexml
+SpellButton3SubSpellName	table	framexml
+SpellButton4	table	framexml
+SpellButton4AutoCast	table	framexml
+SpellButton4AutoCastable	table	framexml
+SpellButton4Background	table	framexml
+SpellButton4Cooldown	table	framexml
+SpellButton4Highlight	table	framexml
+SpellButton4IconTexture	table	framexml
+SpellButton4NormalTexture	table	framexml
+SpellButton4SpellName	table	framexml
+SpellButton4SubSpellName	table	framexml
+SpellButton5	table	framexml
+SpellButton5AutoCast	table	framexml
+SpellButton5AutoCastable	table	framexml
+SpellButton5Background	table	framexml
+SpellButton5Cooldown	table	framexml
+SpellButton5Highlight	table	framexml
+SpellButton5IconTexture	table	framexml
+SpellButton5NormalTexture	table	framexml
+SpellButton5SpellName	table	framexml
+SpellButton5SubSpellName	table	framexml
+SpellButton6	table	framexml
+SpellButton6AutoCast	table	framexml
+SpellButton6AutoCastable	table	framexml
+SpellButton6Background	table	framexml
+SpellButton6Cooldown	table	framexml
+SpellButton6Highlight	table	framexml
+SpellButton6IconTexture	table	framexml
+SpellButton6NormalTexture	table	framexml
+SpellButton6SpellName	table	framexml
+SpellButton6SubSpellName	table	framexml
+SpellButton7	table	framexml
+SpellButton7AutoCast	table	framexml
+SpellButton7AutoCastable	table	framexml
+SpellButton7Background	table	framexml
+SpellButton7Cooldown	table	framexml
+SpellButton7Highlight	table	framexml
+SpellButton7IconTexture	table	framexml
+SpellButton7NormalTexture	table	framexml
+SpellButton7SpellName	table	framexml
+SpellButton7SubSpellName	table	framexml
+SpellButton8	table	framexml
+SpellButton8AutoCast	table	framexml
+SpellButton8AutoCastable	table	framexml
+SpellButton8Background	table	framexml
+SpellButton8Cooldown	table	framexml
+SpellButton8Highlight	table	framexml
+SpellButton8IconTexture	table	framexml
+SpellButton8NormalTexture	table	framexml
+SpellButton8SpellName	table	framexml
+SpellButton8SubSpellName	table	framexml
+SpellButton9	table	framexml
+SpellButton9AutoCast	table	framexml
+SpellButton9AutoCastable	table	framexml
+SpellButton9Background	table	framexml
+SpellButton9Cooldown	table	framexml
+SpellButton9Highlight	table	framexml
+SpellButton9IconTexture	table	framexml
+SpellButton9NormalTexture	table	framexml
+SpellButton9SpellName	table	framexml
+SpellButton9SubSpellName	table	framexml
+SpellButtonTemplate	lod	framexml
+SpellButton_OnClick	function	framexml
+SpellButton_OnEnter	function	framexml
+SpellButton_OnEvent	function	framexml
+SpellButton_OnLoad	function	framexml
+SpellButton_OnUpdate	function	framexml
+SpellButton_UpdateButton	function	framexml
+SpellButton_UpdateSelection	function	framexml
+SpellCanTargetUnit	function	engine
+SpellIsTargeting	function	engine
+SpellLogMenuChatTypeGroups	table	framexml
+SpellLogOtherMenuChatTypeGroups	table	framexml
+SpellStopCasting	function	engine
+SpellStopTargeting	function	engine
+SpellTargetUnit	function	engine
+SpellbookMicroButton	table	framexml
+SplitContainerItem	function	engine
+StablePet	function	engine
+StackSplitCancelButton	table	framexml
+StackSplitCancelButtonText	table	framexml
+StackSplitFrame	table	framexml
+StackSplitFrameCancel_Click	function	framexml
+StackSplitFrameLeft_Click	function	framexml
+StackSplitFrameOkay_Click	function	framexml
+StackSplitFrameRight_Click	function	framexml
+StackSplitFrame_OnChar	function	framexml
+StackSplitFrame_OnHide	function	framexml
+StackSplitFrame_OnKeyDown	function	framexml
+StackSplitLeftButton	table	framexml
+StackSplitOkayButton	table	framexml
+StackSplitOkayButtonText	table	framexml
+StackSplitRightButton	table	framexml
+StackSplitText	table	framexml
+StandingMouseOver	table	framexml
+StartAuction	function	engine
+StartDelay	lod	framexml
+StartDuel	function	engine
+StartDuelUnit	function	engine
+StartPrice	lod	framexml
+StatFrameTemplate	lod	framexml
+StaticPopup1	table	framexml
+StaticPopup1AlertIcon	table	framexml
+StaticPopup1Button1	table	framexml
+StaticPopup1Button2	table	framexml
+StaticPopup1CloseButton	table	framexml
+StaticPopup1EditBox	table	framexml
+StaticPopup1MoneyFrame	table	framexml
+StaticPopup1MoneyFrameCopperButton	table	framexml
+StaticPopup1MoneyFrameCopperButtonText	table	framexml
+StaticPopup1MoneyFrameGoldButton	table	framexml
+StaticPopup1MoneyFrameGoldButtonText	table	framexml
+StaticPopup1MoneyFrameSilverButton	table	framexml
+StaticPopup1MoneyFrameSilverButtonText	table	framexml
+StaticPopup1Text	table	framexml
+StaticPopup1WideEditBox	table	framexml
+StaticPopup1WideEditBoxLeft	table	framexml
+StaticPopup1WideEditBoxRight	table	framexml
+StaticPopup2	table	framexml
+StaticPopup2AlertIcon	table	framexml
+StaticPopup2Button1	table	framexml
+StaticPopup2Button2	table	framexml
+StaticPopup2CloseButton	table	framexml
+StaticPopup2EditBox	table	framexml
+StaticPopup2MoneyFrame	table	framexml
+StaticPopup2MoneyFrameCopperButton	table	framexml
+StaticPopup2MoneyFrameCopperButtonText	table	framexml
+StaticPopup2MoneyFrameGoldButton	table	framexml
+StaticPopup2MoneyFrameGoldButtonText	table	framexml
+StaticPopup2MoneyFrameSilverButton	table	framexml
+StaticPopup2MoneyFrameSilverButtonText	table	framexml
+StaticPopup2Text	table	framexml
+StaticPopup2WideEditBox	table	framexml
+StaticPopup2WideEditBoxLeft	table	framexml
+StaticPopup2WideEditBoxRight	table	framexml
+StaticPopup3	table	framexml
+StaticPopup3AlertIcon	table	framexml
+StaticPopup3Button1	table	framexml
+StaticPopup3Button2	table	framexml
+StaticPopup3CloseButton	table	framexml
+StaticPopup3EditBox	table	framexml
+StaticPopup3MoneyFrame	table	framexml
+StaticPopup3MoneyFrameCopperButton	table	framexml
+StaticPopup3MoneyFrameCopperButtonText	table	framexml
+StaticPopup3MoneyFrameGoldButton	table	framexml
+StaticPopup3MoneyFrameGoldButtonText	table	framexml
+StaticPopup3MoneyFrameSilverButton	table	framexml
+StaticPopup3MoneyFrameSilverButtonText	table	framexml
+StaticPopup3Text	table	framexml
+StaticPopup3WideEditBox	table	framexml
+StaticPopup3WideEditBoxLeft	table	framexml
+StaticPopup3WideEditBoxRight	table	framexml
+StaticPopup4	table	framexml
+StaticPopup4AlertIcon	table	framexml
+StaticPopup4Button1	table	framexml
+StaticPopup4Button2	table	framexml
+StaticPopup4CloseButton	table	framexml
+StaticPopup4EditBox	table	framexml
+StaticPopup4MoneyFrame	table	framexml
+StaticPopup4MoneyFrameCopperButton	table	framexml
+StaticPopup4MoneyFrameCopperButtonText	table	framexml
+StaticPopup4MoneyFrameGoldButton	table	framexml
+StaticPopup4MoneyFrameGoldButtonText	table	framexml
+StaticPopup4MoneyFrameSilverButton	table	framexml
+StaticPopup4MoneyFrameSilverButtonText	table	framexml
+StaticPopup4Text	table	framexml
+StaticPopup4WideEditBox	table	framexml
+StaticPopup4WideEditBoxLeft	table	framexml
+StaticPopup4WideEditBoxRight	table	framexml
+StaticPopupButtonTemplate	lod	framexml
+StaticPopupDialogs	table	framexml
+StaticPopupTemplate	lod	framexml
+StaticPopup_EditBoxOnEnterPressed	function	framexml
+StaticPopup_EditBoxOnEscapePressed	function	framexml
+StaticPopup_EditBoxOnTextChanged	function	framexml
+StaticPopup_EscapePressed	function	framexml
+StaticPopup_FindVisible	function	framexml
+StaticPopup_Hide	function	framexml
+StaticPopup_OnClick	function	framexml
+StaticPopup_OnHide	function	framexml
+StaticPopup_OnShow	function	framexml
+StaticPopup_OnUpdate	function	framexml
+StaticPopup_Resize	function	framexml
+StaticPopup_Show	function	framexml
+StaticPopup_Visible	function	framexml
+StationeryBackgroundLeft	table	framexml
+StationeryBackgroundRight	table	framexml
+StationeryPopupButton1	table	framexml
+StationeryPopupButton1Icon	table	framexml
+StationeryPopupButton1MoneyFrame	table	framexml
+StationeryPopupButton1MoneyFrameCopperButton	table	framexml
+StationeryPopupButton1MoneyFrameCopperButtonText	table	framexml
+StationeryPopupButton1MoneyFrameGoldButton	table	framexml
+StationeryPopupButton1MoneyFrameGoldButtonText	table	framexml
+StationeryPopupButton1MoneyFrameSilverButton	table	framexml
+StationeryPopupButton1MoneyFrameSilverButtonText	table	framexml
+StationeryPopupButton1Name	table	framexml
+StationeryPopupButton1NameFrame	table	framexml
+StationeryPopupButton2	table	framexml
+StationeryPopupButton2Icon	table	framexml
+StationeryPopupButton2MoneyFrame	table	framexml
+StationeryPopupButton2MoneyFrameCopperButton	table	framexml
+StationeryPopupButton2MoneyFrameCopperButtonText	table	framexml
+StationeryPopupButton2MoneyFrameGoldButton	table	framexml
+StationeryPopupButton2MoneyFrameGoldButtonText	table	framexml
+StationeryPopupButton2MoneyFrameSilverButton	table	framexml
+StationeryPopupButton2MoneyFrameSilverButtonText	table	framexml
+StationeryPopupButton2Name	table	framexml
+StationeryPopupButton2NameFrame	table	framexml
+StationeryPopupButton3	table	framexml
+StationeryPopupButton3Icon	table	framexml
+StationeryPopupButton3MoneyFrame	table	framexml
+StationeryPopupButton3MoneyFrameCopperButton	table	framexml
+StationeryPopupButton3MoneyFrameCopperButtonText	table	framexml
+StationeryPopupButton3MoneyFrameGoldButton	table	framexml
+StationeryPopupButton3MoneyFrameGoldButtonText	table	framexml
+StationeryPopupButton3MoneyFrameSilverButton	table	framexml
+StationeryPopupButton3MoneyFrameSilverButtonText	table	framexml
+StationeryPopupButton3Name	table	framexml
+StationeryPopupButton3NameFrame	table	framexml
+StationeryPopupButton4	table	framexml
+StationeryPopupButton4Icon	table	framexml
+StationeryPopupButton4MoneyFrame	table	framexml
+StationeryPopupButton4MoneyFrameCopperButton	table	framexml
+StationeryPopupButton4MoneyFrameCopperButtonText	table	framexml
+StationeryPopupButton4MoneyFrameGoldButton	table	framexml
+StationeryPopupButton4MoneyFrameGoldButtonText	table	framexml
+StationeryPopupButton4MoneyFrameSilverButton	table	framexml
+StationeryPopupButton4MoneyFrameSilverButtonText	table	framexml
+StationeryPopupButton4Name	table	framexml
+StationeryPopupButton4NameFrame	table	framexml
+StationeryPopupButton5	table	framexml
+StationeryPopupButton5Icon	table	framexml
+StationeryPopupButton5MoneyFrame	table	framexml
+StationeryPopupButton5MoneyFrameCopperButton	table	framexml
+StationeryPopupButton5MoneyFrameCopperButtonText	table	framexml
+StationeryPopupButton5MoneyFrameGoldButton	table	framexml
+StationeryPopupButton5MoneyFrameGoldButtonText	table	framexml
+StationeryPopupButton5MoneyFrameSilverButton	table	framexml
+StationeryPopupButton5MoneyFrameSilverButtonText	table	framexml
+StationeryPopupButton5Name	table	framexml
+StationeryPopupButton5NameFrame	table	framexml
+StationeryPopupButtonTemplate	lod	framexml
+StationeryPopupButton_OnClick	function	framexml
+StationeryPopupCancelButton	table	framexml
+StationeryPopupCancelButtonText	table	framexml
+StationeryPopupFrame	table	framexml
+StationeryPopupFrame_Update	function	framexml
+StationeryPopupOkayButton	table	framexml
+StationeryPopupOkayButtonText	table	framexml
+StationeryPopupScrollFrame	table	framexml
+StationeryPopupScrollFrameScrollBar	table	framexml
+StationeryPopupScrollFrameScrollBarScrollDownButton	table	framexml
+StationeryPopupScrollFrameScrollBarScrollUpButton	table	framexml
+StationeryPopupScrollFrameScrollBarThumbTexture	table	framexml
+StationeryPopupScrollFrameScrollChildFrame	table	framexml
+StatsFrame	table	framexml
+StatsFrameText	table	framexml
+StatsFrame_OnLoad	function	framexml
+StatsFrame_OnUpdate	function	framexml
+StopCinematic	function	engine
+StopMusic	function	engine
+StrafeLeftStart	function	engine
+StrafeLeftStop	function	engine
+StrafeRightStart	function	engine
+StrafeRightStop	function	engine
+Stuck	function	engine
+SubSpellFont	table	framexml
+SubZoneTextFont	table	framexml
+SubZoneTextFrame	table	framexml
+SubZoneTextString	table	framexml
+SubmitNumbers	function	engine
+SwapRaidSubgroup	function	engine
+SystemFont	table	framexml
+TABARDSLOT	string	framexml
+TABARDVENDORALREADYSETGREETING	string	framexml
+TABARDVENDORCOST	string	framexml
+TABARDVENDORGREETING	string	framexml
+TABARDVENDORNOGUILDGREETING	string	framexml
+TAKE_ATTACHMENTS	string	framexml
+TAKE_GM_SURVEY	string	framexml
+TALENTS	string	framexml
+TALENTS_BUTTON	string	framexml
+TALENT_ARROW_TEXTURECOORDS	lod	framexml
+TALENT_BRANCH_ARRAY	lod	framexml
+TALENT_BRANCH_TEXTURECOORDS	lod	framexml
+TALENT_BUTTON_SIZE	lod	framexml
+TALENT_FRAME_WAS_SHOWN	lod	framexml
+TALENT_POINTS_TOOLTIP	string	framexml
+TALENT_TRAINER	string	framexml
+TAMEABLE	string	framexml
+TARGET	string	framexml
+TARGET_RAID_SLOT	lod	framexml
+TARGET_TOKEN_NOT_FOUND	string	framexml
+TASKS_COLON	string	framexml
+TAXINODEYOUAREHERE	string	framexml
+TAXIROUTE_LINEFACTOR	number	framexml
+TAXIROUTE_LINEFACTOR_2	number	framexml
+TAXISAMENODE	string	framexml
+TAXI_MAP_HEIGHT	number	framexml
+TAXI_MAP_WIDTH	number	framexml
+TERRAIN_HIGHLIGHTS	string	framexml
+TERRAIN_MIP	string	framexml
+TEST_TAG_TEST	string	framexml
+TEXT	function	framexml
+TEXTURE_DETAIL	string	framexml
+TICKET_STATUS1	string	framexml
+TICKET_TYPE1	string	framexml
+TICKET_TYPE2	string	framexml
+TICKET_TYPE3	string	framexml
+TICKET_TYPE4	string	framexml
+TIME_DAYHOURMINUTESECOND	string	framexml
+TIME_ELAPSED	string	framexml
+TIME_PLAYED_LEVEL	string	framexml
+TIME_PLAYED_MSG	string	framexml
+TIME_PLAYED_TOTAL	string	framexml
+TIME_REMAINING	string	framexml
+TIME_TEMPLATE_LONG	string	framexml
+TIME_TO_PORT	string	framexml
+TIME_TWELVEHOURAM	string	framexml
+TIME_TWELVEHOURPM	string	framexml
+TIME_TWENTYFOURHOURS	string	framexml
+TIME_UNTIL_DELETED	string	framexml
+TIME_UNTIL_RETURNED	string	framexml
+TITLE_TEMPLATE	string	framexml
+TLx	lod	framexml
+TLy	lod	framexml
+TOGGLESTICKYCAMERA	string	framexml
+TOOLTIP_DEFAULT_BACKGROUND_COLOR	table	framexml
+TOOLTIP_DEFAULT_COLOR	table	framexml
+TOOLTIP_TALENT_LEARN	string	framexml
+TOOLTIP_TALENT_NEXT_RANK	string	framexml
+TOOLTIP_TALENT_PREREQ	string	framexml
+TOOLTIP_TALENT_PREREQ_P1	string	framexml
+TOOLTIP_TALENT_RANK	string	framexml
+TOOLTIP_TALENT_TIER_POINTS	string	framexml
+TOOLTIP_UNIT_LEVEL	string	framexml
+TOOLTIP_UNIT_LEVEL_CLASS	string	framexml
+TOOLTIP_UNIT_LEVEL_CLASS_TYPE	string	framexml
+TOOLTIP_UNIT_LEVEL_TYPE	string	framexml
+TOOLTIP_UPDATE_TIME	number	framexml
+TOO_FAR_TO_LOOT	string	framexml
+TRACK_QUEST	string	framexml
+TRADE	string	framexml
+TRADEFRAME_ENCHANT_SLOT_LABEL	string	framexml
+TRADEFRAME_NOT_MODIFIED_TEXT	string	framexml
+TRADESKILL_LOG_FIRSTPERSON	string	framexml
+TRADESKILL_LOG_THIRDPERSON	string	framexml
+TRADESKILL_SERVICE_LEARN	string	framexml
+TRADESKILL_SERVICE_STEP	string	framexml
+TRADE_SKILLS	string	framexml
+TRADE_SKILLS_DISPLAYED	lod	framexml
+TRADE_SKILL_HEIGHT	lod	framexml
+TRADE_SKILL_TITLE	string	framexml
+TRADE_WITH_QUESTION	string	framexml
+TRAIN	string	framexml
+TRAINER_CAST_TIME_INSTANT	string	framexml
+TRAINER_CAST_TIME_MIN	string	framexml
+TRAINER_CAST_TIME_SEC	string	framexml
+TRAINER_COOLDOWN_TIME_INSTANT	string	framexml
+TRAINER_COOLDOWN_TIME_MIN	string	framexml
+TRAINER_COOLDOWN_TIME_SEC	string	framexml
+TRAINER_COST_SP	string	framexml
+TRAINER_COST_SP_RED	string	framexml
+TRAINER_COST_TP	string	framexml
+TRAINER_COST_TP_RED	string	framexml
+TRAINER_FILTER_AVAILABLE	lod	framexml
+TRAINER_FILTER_UNAVAILABLE	lod	framexml
+TRAINER_FILTER_USED	lod	framexml
+TRAINER_LIST_SP	string	framexml
+TRAINER_LIST_TP	string	framexml
+TRAINER_MANA_COST	string	framexml
+TRAINER_MANA_COST_PER_TIME	string	framexml
+TRAINER_PET_LEVEL	string	framexml
+TRAINER_PET_LEVEL_RED	string	framexml
+TRAINER_PET_SPELL_LABEL	string	framexml
+TRAINER_RANGE	string	framexml
+TRAINER_REQ_ABILITY	string	framexml
+TRAINER_REQ_ABILITY_RED	string	framexml
+TRAINER_REQ_LEVEL	string	framexml
+TRAINER_REQ_LEVEL_RED	string	framexml
+TRAINER_REQ_SKILL_RANK	string	framexml
+TRAINER_REQ_SKILL_RANK_RED	string	framexml
+TRAINING_POINTS	string	framexml
+TRAINING_POINTS_LABEL	string	framexml
+TRANSFER_ABORT_ERROR	string	framexml
+TRANSFER_ABORT_MAX_PLAYERS	string	framexml
+TRANSFER_ABORT_NOT_FOUND	string	framexml
+TRANSFER_ABORT_TOO_MANY_INSTANCES	string	framexml
+TRANSFER_ABORT_ZONE_IN_COMBAT	string	framexml
+TRILINEAR_FILTERING	string	framexml
+TRINKET0SLOT	string	framexml
+TRINKET1SLOT	string	framexml
+TRIPLE_BUFFER	string	framexml
+TRx	lod	framexml
+TRy	lod	framexml
+TURN_IN_ITEMS	string	framexml
+TUTORIAL1	string	framexml
+TUTORIAL10	string	framexml
+TUTORIAL11	string	framexml
+TUTORIAL12	string	framexml
+TUTORIAL13	string	framexml
+TUTORIAL14	string	framexml
+TUTORIAL15	string	framexml
+TUTORIAL16	string	framexml
+TUTORIAL17	string	framexml
+TUTORIAL18	string	framexml
+TUTORIAL19	string	framexml
+TUTORIAL2	string	framexml
+TUTORIAL20	string	framexml
+TUTORIAL21	string	framexml
+TUTORIAL22	string	framexml
+TUTORIAL23	string	framexml
+TUTORIAL24	string	framexml
+TUTORIAL25	string	framexml
+TUTORIAL26	string	framexml
+TUTORIAL27	string	framexml
+TUTORIAL28	string	framexml
+TUTORIAL29	string	framexml
+TUTORIAL3	string	framexml
+TUTORIAL30	string	framexml
+TUTORIAL31	string	framexml
+TUTORIAL32	string	framexml
+TUTORIAL33	string	framexml
+TUTORIAL34	string	framexml
+TUTORIAL35	string	framexml
+TUTORIAL36	string	framexml
+TUTORIAL37	string	framexml
+TUTORIAL38	string	framexml
+TUTORIAL39	string	framexml
+TUTORIAL4	string	framexml
+TUTORIAL40	string	framexml
+TUTORIAL41	string	framexml
+TUTORIAL42	string	framexml
+TUTORIAL43	string	framexml
+TUTORIAL44	string	framexml
+TUTORIAL45	string	framexml
+TUTORIAL46	string	framexml
+TUTORIAL47	string	framexml
+TUTORIAL48	string	framexml
+TUTORIAL49	string	framexml
+TUTORIAL5	string	framexml
+TUTORIAL50	string	framexml
+TUTORIAL6	string	framexml
+TUTORIAL7	string	framexml
+TUTORIAL8	string	framexml
+TUTORIAL9	string	framexml
+TUTORIALFRAME_QUEUE	table	framexml
+TUTORIAL_TITLE1	string	framexml
+TUTORIAL_TITLE10	string	framexml
+TUTORIAL_TITLE11	string	framexml
+TUTORIAL_TITLE12	string	framexml
+TUTORIAL_TITLE13	string	framexml
+TUTORIAL_TITLE14	string	framexml
+TUTORIAL_TITLE15	string	framexml
+TUTORIAL_TITLE16	string	framexml
+TUTORIAL_TITLE17	string	framexml
+TUTORIAL_TITLE18	string	framexml
+TUTORIAL_TITLE19	string	framexml
+TUTORIAL_TITLE2	string	framexml
+TUTORIAL_TITLE20	string	framexml
+TUTORIAL_TITLE21	string	framexml
+TUTORIAL_TITLE22	string	framexml
+TUTORIAL_TITLE23	string	framexml
+TUTORIAL_TITLE24	string	framexml
+TUTORIAL_TITLE25	string	framexml
+TUTORIAL_TITLE26	string	framexml
+TUTORIAL_TITLE27	string	framexml
+TUTORIAL_TITLE28	string	framexml
+TUTORIAL_TITLE29	string	framexml
+TUTORIAL_TITLE3	string	framexml
+TUTORIAL_TITLE30	string	framexml
+TUTORIAL_TITLE31	string	framexml
+TUTORIAL_TITLE32	string	framexml
+TUTORIAL_TITLE33	string	framexml
+TUTORIAL_TITLE34	string	framexml
+TUTORIAL_TITLE35	string	framexml
+TUTORIAL_TITLE36	string	framexml
+TUTORIAL_TITLE37	string	framexml
+TUTORIAL_TITLE38	string	framexml
+TUTORIAL_TITLE39	string	framexml
+TUTORIAL_TITLE4	string	framexml
+TUTORIAL_TITLE40	string	framexml
+TUTORIAL_TITLE41	string	framexml
+TUTORIAL_TITLE42	string	framexml
+TUTORIAL_TITLE43	string	framexml
+TUTORIAL_TITLE44	string	framexml
+TUTORIAL_TITLE45	string	framexml
+TUTORIAL_TITLE46	string	framexml
+TUTORIAL_TITLE47	string	framexml
+TUTORIAL_TITLE48	string	framexml
+TUTORIAL_TITLE49	string	framexml
+TUTORIAL_TITLE5	string	framexml
+TUTORIAL_TITLE50	string	framexml
+TUTORIAL_TITLE6	string	framexml
+TUTORIAL_TITLE7	string	framexml
+TUTORIAL_TITLE8	string	framexml
+TUTORIAL_TITLE9	string	framexml
+TWOHANDEDWEAPONBEINGWIELDED	string	framexml
+TWO_HANDED	string	framexml
+TabButtonTemplate	lod	framexml
+TabardCharacterModelFrame_OnLoad	function	framexml
+TabardCharacterModelFrame_OnUpdate	function	framexml
+TabardCharacterModelRotateLeftButton	table	framexml
+TabardCharacterModelRotateLeftButton_OnClick	function	framexml
+TabardCharacterModelRotateRightButton	table	framexml
+TabardCharacterModelRotateRightButton_OnClick	function	framexml
+TabardCustomization_Left	function	framexml
+TabardCustomization_Right	function	framexml
+TabardFrame	table	framexml
+TabardFrameAcceptButton	table	framexml
+TabardFrameAcceptButtonText	table	framexml
+TabardFrameBackground	table	framexml
+TabardFrameCancelButton	table	framexml
+TabardFrameCancelButtonText	table	framexml
+TabardFrameCloseButton	table	framexml
+TabardFrameCostFrame	table	framexml
+TabardFrameCostLabel	table	framexml
+TabardFrameCostMoneyFrame	table	framexml
+TabardFrameCostMoneyFrameCopperButton	table	framexml
+TabardFrameCostMoneyFrameCopperButtonText	table	framexml
+TabardFrameCostMoneyFrameGoldButton	table	framexml
+TabardFrameCostMoneyFrameGoldButtonText	table	framexml
+TabardFrameCostMoneyFrameSilverButton	table	framexml
+TabardFrameCostMoneyFrameSilverButtonText	table	framexml
+TabardFrameCustomization1	table	framexml
+TabardFrameCustomization1Left	table	framexml
+TabardFrameCustomization1LeftButton	table	framexml
+TabardFrameCustomization1Middle	table	framexml
+TabardFrameCustomization1Right	table	framexml
+TabardFrameCustomization1RightButton	table	framexml
+TabardFrameCustomization1Text	table	framexml
+TabardFrameCustomization2	table	framexml
+TabardFrameCustomization2Left	table	framexml
+TabardFrameCustomization2LeftButton	table	framexml
+TabardFrameCustomization2Middle	table	framexml
+TabardFrameCustomization2Right	table	framexml
+TabardFrameCustomization2RightButton	table	framexml
+TabardFrameCustomization2Text	table	framexml
+TabardFrameCustomization3	table	framexml
+TabardFrameCustomization3Left	table	framexml
+TabardFrameCustomization3LeftButton	table	framexml
+TabardFrameCustomization3Middle	table	framexml
+TabardFrameCustomization3Right	table	framexml
+TabardFrameCustomization3RightButton	table	framexml
+TabardFrameCustomization3Text	table	framexml
+TabardFrameCustomization4	table	framexml
+TabardFrameCustomization4Left	table	framexml
+TabardFrameCustomization4LeftButton	table	framexml
+TabardFrameCustomization4Middle	table	framexml
+TabardFrameCustomization4Right	table	framexml
+TabardFrameCustomization4RightButton	table	framexml
+TabardFrameCustomization4Text	table	framexml
+TabardFrameCustomization5	table	framexml
+TabardFrameCustomization5Left	table	framexml
+TabardFrameCustomization5LeftButton	table	framexml
+TabardFrameCustomization5Middle	table	framexml
+TabardFrameCustomization5Right	table	framexml
+TabardFrameCustomization5RightButton	table	framexml
+TabardFrameCustomization5Text	table	framexml
+TabardFrameCustomizationBorder	table	framexml
+TabardFrameCustomizationFrame	table	framexml
+TabardFrameCustomizeTemplate	lod	framexml
+TabardFrameEmblemBottomLeft	table	framexml
+TabardFrameEmblemBottomRight	table	framexml
+TabardFrameEmblemTopLeft	table	framexml
+TabardFrameEmblemTopRight	table	framexml
+TabardFrameGreetingText	table	framexml
+TabardFrameMoneyFrame	table	framexml
+TabardFrameMoneyFrameCopperButton	table	framexml
+TabardFrameMoneyFrameCopperButtonText	table	framexml
+TabardFrameMoneyFrameGoldButton	table	framexml
+TabardFrameMoneyFrameGoldButtonText	table	framexml
+TabardFrameMoneyFrameSilverButton	table	framexml
+TabardFrameMoneyFrameSilverButtonText	table	framexml
+TabardFrameNameText	table	framexml
+TabardFrameOuterFrameBottom	table	framexml
+TabardFrameOuterFrameBottomLeft	table	framexml
+TabardFrameOuterFrameBottomRight	table	framexml
+TabardFrameOuterFrameLeftBottom	table	framexml
+TabardFrameOuterFrameLeftTop	table	framexml
+TabardFrameOuterFrameRightBottom	table	framexml
+TabardFrameOuterFrameRightTop	table	framexml
+TabardFrameOuterFrameTop	table	framexml
+TabardFrameOuterFrameTopLeft	table	framexml
+TabardFrameOuterFrameTopRight	table	framexml
+TabardFramePortrait	table	framexml
+TabardFrame_OnEvent	function	framexml
+TabardFrame_OnLoad	function	framexml
+TabardFrame_UpdateButtons	function	framexml
+TabardFrame_UpdateTextures	function	framexml
+TabardModel	table	framexml
+TakeInboxItem	function	engine
+TakeInboxMoney	function	engine
+TakeInboxTextItem	function	engine
+TakeScreenshot	function	framexml
+TakeTaxiNode	function	engine
+TalentArrowTemplate	lod	framexml
+TalentBranchTemplate	lod	framexml
+TalentButtonTemplate	lod	framexml
+TalentFrame	lod	framexml
+TalentFrameArrow1	lod	framexml
+TalentFrameArrow10	lod	framexml
+TalentFrameArrow11	lod	framexml
+TalentFrameArrow12	lod	framexml
+TalentFrameArrow13	lod	framexml
+TalentFrameArrow14	lod	framexml
+TalentFrameArrow15	lod	framexml
+TalentFrameArrow16	lod	framexml
+TalentFrameArrow17	lod	framexml
+TalentFrameArrow18	lod	framexml
+TalentFrameArrow19	lod	framexml
+TalentFrameArrow2	lod	framexml
+TalentFrameArrow20	lod	framexml
+TalentFrameArrow21	lod	framexml
+TalentFrameArrow22	lod	framexml
+TalentFrameArrow23	lod	framexml
+TalentFrameArrow24	lod	framexml
+TalentFrameArrow25	lod	framexml
+TalentFrameArrow26	lod	framexml
+TalentFrameArrow27	lod	framexml
+TalentFrameArrow28	lod	framexml
+TalentFrameArrow29	lod	framexml
+TalentFrameArrow3	lod	framexml
+TalentFrameArrow30	lod	framexml
+TalentFrameArrow4	lod	framexml
+TalentFrameArrow5	lod	framexml
+TalentFrameArrow6	lod	framexml
+TalentFrameArrow7	lod	framexml
+TalentFrameArrow8	lod	framexml
+TalentFrameArrow9	lod	framexml
+TalentFrameArrowFrame	lod	framexml
+TalentFrameBackgroundBottomLeft	lod	framexml
+TalentFrameBackgroundBottomRight	lod	framexml
+TalentFrameBackgroundTopLeft	lod	framexml
+TalentFrameBackgroundTopRight	lod	framexml
+TalentFrameBranch1	lod	framexml
+TalentFrameBranch10	lod	framexml
+TalentFrameBranch11	lod	framexml
+TalentFrameBranch12	lod	framexml
+TalentFrameBranch13	lod	framexml
+TalentFrameBranch14	lod	framexml
+TalentFrameBranch15	lod	framexml
+TalentFrameBranch16	lod	framexml
+TalentFrameBranch17	lod	framexml
+TalentFrameBranch18	lod	framexml
+TalentFrameBranch19	lod	framexml
+TalentFrameBranch2	lod	framexml
+TalentFrameBranch20	lod	framexml
+TalentFrameBranch21	lod	framexml
+TalentFrameBranch22	lod	framexml
+TalentFrameBranch23	lod	framexml
+TalentFrameBranch24	lod	framexml
+TalentFrameBranch25	lod	framexml
+TalentFrameBranch26	lod	framexml
+TalentFrameBranch27	lod	framexml
+TalentFrameBranch28	lod	framexml
+TalentFrameBranch29	lod	framexml
+TalentFrameBranch3	lod	framexml
+TalentFrameBranch30	lod	framexml
+TalentFrameBranch4	lod	framexml
+TalentFrameBranch5	lod	framexml
+TalentFrameBranch6	lod	framexml
+TalentFrameBranch7	lod	framexml
+TalentFrameBranch8	lod	framexml
+TalentFrameBranch9	lod	framexml
+TalentFrameCancelButton	lod	framexml
+TalentFrameCloseButton	lod	framexml
+TalentFramePointsLeft	lod	framexml
+TalentFramePointsMiddle	lod	framexml
+TalentFramePointsRight	lod	framexml
+TalentFramePortrait	lod	framexml
+TalentFrameScrollChildFrame	lod	framexml
+TalentFrameScrollFrame	lod	framexml
+TalentFrameSpentPoints	lod	framexml
+TalentFrameTab1	lod	framexml
+TalentFrameTab2	lod	framexml
+TalentFrameTab3	lod	framexml
+TalentFrameTab4	lod	framexml
+TalentFrameTab5	lod	framexml
+TalentFrameTab_OnClick	lod	framexml
+TalentFrameTalent1	lod	framexml
+TalentFrameTalent10	lod	framexml
+TalentFrameTalent11	lod	framexml
+TalentFrameTalent12	lod	framexml
+TalentFrameTalent13	lod	framexml
+TalentFrameTalent14	lod	framexml
+TalentFrameTalent15	lod	framexml
+TalentFrameTalent16	lod	framexml
+TalentFrameTalent17	lod	framexml
+TalentFrameTalent18	lod	framexml
+TalentFrameTalent19	lod	framexml
+TalentFrameTalent2	lod	framexml
+TalentFrameTalent20	lod	framexml
+TalentFrameTalent3	lod	framexml
+TalentFrameTalent4	lod	framexml
+TalentFrameTalent5	lod	framexml
+TalentFrameTalent6	lod	framexml
+TalentFrameTalent7	lod	framexml
+TalentFrameTalent8	lod	framexml
+TalentFrameTalent9	lod	framexml
+TalentFrameTalentPoints	lod	framexml
+TalentFrameTalentPointsText	lod	framexml
+TalentFrameTalent_OnClick	lod	framexml
+TalentFrameTalent_OnEvent	lod	framexml
+TalentFrameTitleText	lod	framexml
+TalentFrame_DrawLines	lod	framexml
+TalentFrame_GetArrowTexture	lod	framexml
+TalentFrame_GetArrowTextureCount	lod	framexml
+TalentFrame_GetBranchTexture	lod	framexml
+TalentFrame_GetBranchTextureCount	lod	framexml
+TalentFrame_LoadUI	function	framexml
+TalentFrame_OnEvent	lod	framexml
+TalentFrame_OnHide	lod	framexml
+TalentFrame_OnLoad	lod	framexml
+TalentFrame_OnShow	lod	framexml
+TalentFrame_ResetArrowTextureCount	lod	framexml
+TalentFrame_ResetBranchTextureCount	lod	framexml
+TalentFrame_ResetBranches	lod	framexml
+TalentFrame_SetArrowTexture	lod	framexml
+TalentFrame_SetBranchTexture	lod	framexml
+TalentFrame_SetPrereqs	lod	framexml
+TalentFrame_Toggle	lod	framexml
+TalentFrame_Update	lod	framexml
+TalentFrame_UpdateTalentPoints	lod	framexml
+TalentMicroButton	table	framexml
+TalentMicroButton_OnEvent	function	framexml
+TalentTabTemplate	lod	framexml
+TargetBuffButtonTemplate	lod	framexml
+TargetByName	function	engine
+TargetDeadText	table	framexml
+TargetDebuffButtonTemplate	lod	framexml
+TargetDebuffButton_Update	function	framexml
+TargetFrame	table	framexml
+TargetFrameBackground	table	framexml
+TargetFrameBuff1	table	framexml
+TargetFrameBuff1Icon	table	framexml
+TargetFrameBuff2	table	framexml
+TargetFrameBuff2Icon	table	framexml
+TargetFrameBuff3	table	framexml
+TargetFrameBuff3Icon	table	framexml
+TargetFrameBuff4	table	framexml
+TargetFrameBuff4Icon	table	framexml
+TargetFrameBuff5	table	framexml
+TargetFrameBuff5Icon	table	framexml
+TargetFrameDebuff1	table	framexml
+TargetFrameDebuff10	table	framexml
+TargetFrameDebuff10Border	table	framexml
+TargetFrameDebuff10Count	table	framexml
+TargetFrameDebuff10Icon	table	framexml
+TargetFrameDebuff11	table	framexml
+TargetFrameDebuff11Border	table	framexml
+TargetFrameDebuff11Count	table	framexml
+TargetFrameDebuff11Icon	table	framexml
+TargetFrameDebuff12	table	framexml
+TargetFrameDebuff12Border	table	framexml
+TargetFrameDebuff12Count	table	framexml
+TargetFrameDebuff12Icon	table	framexml
+TargetFrameDebuff13	table	framexml
+TargetFrameDebuff13Border	table	framexml
+TargetFrameDebuff13Count	table	framexml
+TargetFrameDebuff13Icon	table	framexml
+TargetFrameDebuff14	table	framexml
+TargetFrameDebuff14Border	table	framexml
+TargetFrameDebuff14Count	table	framexml
+TargetFrameDebuff14Icon	table	framexml
+TargetFrameDebuff15	table	framexml
+TargetFrameDebuff15Border	table	framexml
+TargetFrameDebuff15Count	table	framexml
+TargetFrameDebuff15Icon	table	framexml
+TargetFrameDebuff16	table	framexml
+TargetFrameDebuff16Border	table	framexml
+TargetFrameDebuff16Count	table	framexml
+TargetFrameDebuff16Icon	table	framexml
+TargetFrameDebuff1Border	table	framexml
+TargetFrameDebuff1Count	table	framexml
+TargetFrameDebuff1Icon	table	framexml
+TargetFrameDebuff2	table	framexml
+TargetFrameDebuff2Border	table	framexml
+TargetFrameDebuff2Count	table	framexml
+TargetFrameDebuff2Icon	table	framexml
+TargetFrameDebuff3	table	framexml
+TargetFrameDebuff3Border	table	framexml
+TargetFrameDebuff3Count	table	framexml
+TargetFrameDebuff3Icon	table	framexml
+TargetFrameDebuff4	table	framexml
+TargetFrameDebuff4Border	table	framexml
+TargetFrameDebuff4Count	table	framexml
+TargetFrameDebuff4Icon	table	framexml
+TargetFrameDebuff5	table	framexml
+TargetFrameDebuff5Border	table	framexml
+TargetFrameDebuff5Count	table	framexml
+TargetFrameDebuff5Icon	table	framexml
+TargetFrameDebuff6	table	framexml
+TargetFrameDebuff6Border	table	framexml
+TargetFrameDebuff6Count	table	framexml
+TargetFrameDebuff6Icon	table	framexml
+TargetFrameDebuff7	table	framexml
+TargetFrameDebuff7Border	table	framexml
+TargetFrameDebuff7Count	table	framexml
+TargetFrameDebuff7Icon	table	framexml
+TargetFrameDebuff8	table	framexml
+TargetFrameDebuff8Border	table	framexml
+TargetFrameDebuff8Count	table	framexml
+TargetFrameDebuff8Icon	table	framexml
+TargetFrameDebuff9	table	framexml
+TargetFrameDebuff9Border	table	framexml
+TargetFrameDebuff9Count	table	framexml
+TargetFrameDebuff9Icon	table	framexml
+TargetFrameDropDown	table	framexml
+TargetFrameDropDownButton	table	framexml
+TargetFrameDropDownButtonDisabledTexture	table	framexml
+TargetFrameDropDownButtonHighlightTexture	table	framexml
+TargetFrameDropDownButtonNormalTexture	table	framexml
+TargetFrameDropDownButtonPushedTexture	table	framexml
+TargetFrameDropDownLeft	table	framexml
+TargetFrameDropDownMiddle	table	framexml
+TargetFrameDropDownRight	table	framexml
+TargetFrameDropDownText	table	framexml
+TargetFrameDropDown_Initialize	function	framexml
+TargetFrameDropDown_OnLoad	function	framexml
+TargetFrameHealthBar	table	framexml
+TargetFrameManaBar	table	framexml
+TargetFrameNameBackground	table	framexml
+TargetFrameTexture	table	framexml
+TargetFrameTextureFrame	table	framexml
+TargetFrame_CheckClassification	function	framexml
+TargetFrame_CheckDead	function	framexml
+TargetFrame_CheckDishonorableKill	function	framexml
+TargetFrame_CheckFaction	function	framexml
+TargetFrame_CheckLevel	function	framexml
+TargetFrame_HealthUpdate	function	framexml
+TargetFrame_OnClick	function	framexml
+TargetFrame_OnEvent	function	framexml
+TargetFrame_OnHide	function	framexml
+TargetFrame_OnLoad	function	framexml
+TargetFrame_OnShow	function	framexml
+TargetFrame_OnUpdate	function	framexml
+TargetFrame_Update	function	framexml
+TargetFrame_UpdateRaidTargetIcon	function	framexml
+TargetHealthCheck	function	framexml
+TargetHighLevelTexture	table	framexml
+TargetLastEnemy	function	engine
+TargetLastTarget	function	engine
+TargetLeaderIcon	table	framexml
+TargetLevelText	table	framexml
+TargetName	table	framexml
+TargetNearestEnemy	function	engine
+TargetNearestFriend	function	engine
+TargetNearestPartyMember	function	engine
+TargetNearestRaidMember	function	engine
+TargetPVPIcon	table	framexml
+TargetPortrait	table	framexml
+TargetRaidTargetIcon	table	framexml
+TargetUnit	function	engine
+TargetofTargetBackground	table	framexml
+TargetofTargetBuffButtonTemplate	lod	framexml
+TargetofTargetDeadText	table	framexml
+TargetofTargetFrame	table	framexml
+TargetofTargetFrameDebuff1	table	framexml
+TargetofTargetFrameDebuff1Border	table	framexml
+TargetofTargetFrameDebuff1Icon	table	framexml
+TargetofTargetFrameDebuff2	table	framexml
+TargetofTargetFrameDebuff2Border	table	framexml
+TargetofTargetFrameDebuff2Icon	table	framexml
+TargetofTargetFrameDebuff3	table	framexml
+TargetofTargetFrameDebuff3Border	table	framexml
+TargetofTargetFrameDebuff3Icon	table	framexml
+TargetofTargetFrameDebuff4	table	framexml
+TargetofTargetFrameDebuff4Border	table	framexml
+TargetofTargetFrameDebuff4Icon	table	framexml
+TargetofTargetHealthBar	table	framexml
+TargetofTargetHealthCheck	function	framexml
+TargetofTargetManaBar	table	framexml
+TargetofTargetName	table	framexml
+TargetofTargetPortrait	table	framexml
+TargetofTargetTexture	table	framexml
+TargetofTargetTextureFrame	table	framexml
+TargetofTarget_CheckDead	function	framexml
+TargetofTarget_OnClick	function	framexml
+TargetofTarget_OnUpdate	function	framexml
+TargetofTarget_Update	function	framexml
+TaxiButtonTemplate	lod	framexml
+TaxiButtonTypes	table	framexml
+TaxiCloseButton	table	framexml
+TaxiFrame	table	framexml
+TaxiFrame_OnEvent	function	framexml
+TaxiFrame_OnLoad	function	framexml
+TaxiGetDestX	function	engine
+TaxiGetDestY	function	engine
+TaxiGetSrcX	function	engine
+TaxiGetSrcY	function	engine
+TaxiMap	table	framexml
+TaxiMerchant	table	framexml
+TaxiNodeCost	function	engine
+TaxiNodeGetType	function	engine
+TaxiNodeName	function	engine
+TaxiNodeOnButtonEnter	function	framexml
+TaxiNodePosition	function	engine
+TaxiNodeSetCurrent	function	engine
+TaxiPortrait	table	framexml
+TaxiRouteMap	table	framexml
+TempEnchant1	table	framexml
+TempEnchant1Border	table	framexml
+TempEnchant1Count	table	framexml
+TempEnchant1Duration	table	framexml
+TempEnchant1Icon	table	framexml
+TempEnchant2	table	framexml
+TempEnchant2Border	table	framexml
+TempEnchant2Count	table	framexml
+TempEnchant2Duration	table	framexml
+TempEnchant2Icon	table	framexml
+TemporaryEnchantFrame	table	framexml
+TextAlphaDependentFrame	table	framexml
+TextEmoteSort	function	framexml
+TextEmoteSpeechList	table	framexml
+TextStatusBar	lod	framexml
+TextStatusBarText	table	framexml
+TextStatusBarTextSmall	table	framexml
+TextStatusBar_Initialize	function	framexml
+TextStatusBar_OnEvent	function	framexml
+TextStatusBar_OnValueChanged	function	framexml
+TextStatusBar_UpdateTextString	function	framexml
+TicketStatusButton	table	framexml
+TicketStatusFrame	table	framexml
+TicketStatusFrame_OnEvent	function	framexml
+TicketStatusTime	table	framexml
+TicketStatusTitleText	table	framexml
+TicketStatus_OnUpdate	function	framexml
+ToggleAutoRun	function	engine
+ToggleBackpack	function	framexml
+ToggleBag	function	framexml
+ToggleBattlefieldMinimap	function	framexml
+ToggleCharacter	function	framexml
+ToggleCollision	function	engine
+ToggleCollisionDisplay	function	engine
+ToggleCombatLog	function	framexml
+ToggleDropDownMenu	function	framexml
+ToggleFramerate	function	framexml
+ToggleFriendsFrame	function	framexml
+ToggleGameMenu	function	framexml
+ToggleGuildInfoFrame	function	framexml
+ToggleHelpFrame	function	framexml
+ToggleInspect	lod	framexml
+ToggleKeyRing	function	framexml
+ToggleMinimap	function	framexml
+ToggleMouseMove	function	engine
+TogglePVP	function	engine
+TogglePerformanceDisplay	function	engine
+TogglePerformanceValues	function	engine
+TogglePetAutocast	function	engine
+TogglePlayerBounds	function	engine
+TogglePortals	function	engine
+ToggleQuestLog	function	framexml
+ToggleRun	function	engine
+ToggleSheath	function	engine
+ToggleSpellAutocast	function	engine
+ToggleSpellBook	function	framexml
+ToggleStats	function	framexml
+ToggleTalentFrame	function	framexml
+ToggleTris	function	engine
+ToggleWorldMap	function	framexml
+ToggleWorldStateScoreFrame	function	framexml
+TradeFrame	table	framexml
+TradeFrameCancelButton	table	framexml
+TradeFrameCancelButtonText	table	framexml
+TradeFrameCancelButton_OnClick	function	framexml
+TradeFrameCloseButton	table	framexml
+TradeFramePlayerEnchantText	table	framexml
+TradeFramePlayerNameText	table	framexml
+TradeFramePlayerPortrait	table	framexml
+TradeFrameRecipientEnchantText	table	framexml
+TradeFrameRecipientNameText	table	framexml
+TradeFrameRecipientPortrait	table	framexml
+TradeFrameTradeButton	table	framexml
+TradeFrameTradeButtonText	table	framexml
+TradeFrame_GetAvailableSlot	function	framexml
+TradeFrame_OnEvent	function	framexml
+TradeFrame_OnHide	function	framexml
+TradeFrame_OnLoad	function	framexml
+TradeFrame_OnMouseUp	function	framexml
+TradeFrame_OnShow	function	framexml
+TradeFrame_SetAcceptState	function	framexml
+TradeFrame_Update	function	framexml
+TradeFrame_UpdateMoney	function	framexml
+TradeFrame_UpdatePlayerItem	function	framexml
+TradeFrame_UpdateTargetItem	function	framexml
+TradeHighlightPlayer	table	framexml
+TradeHighlightPlayerBottom	table	framexml
+TradeHighlightPlayerEnchant	table	framexml
+TradeHighlightPlayerEnchantBottom	table	framexml
+TradeHighlightPlayerEnchantMiddle	table	framexml
+TradeHighlightPlayerEnchantTop	table	framexml
+TradeHighlightPlayerMiddle	table	framexml
+TradeHighlightPlayerTop	table	framexml
+TradeHighlightRecipient	table	framexml
+TradeHighlightRecipientBottom	table	framexml
+TradeHighlightRecipientEnchant	table	framexml
+TradeHighlightRecipientEnchantBottom	table	framexml
+TradeHighlightRecipientEnchantMiddle	table	framexml
+TradeHighlightRecipientEnchantTop	table	framexml
+TradeHighlightRecipientMiddle	table	framexml
+TradeHighlightRecipientTop	table	framexml
+TradeHighlightTemplate	lod	framexml
+TradeItemTemplate	lod	framexml
+TradePlayerInputMoneyFrame	table	framexml
+TradePlayerInputMoneyFrameCopper	table	framexml
+TradePlayerInputMoneyFrameCopperLeft	table	framexml
+TradePlayerInputMoneyFrameCopperMiddle	table	framexml
+TradePlayerInputMoneyFrameCopperRight	table	framexml
+TradePlayerInputMoneyFrameGold	table	framexml
+TradePlayerInputMoneyFrameGoldLeft	table	framexml
+TradePlayerInputMoneyFrameGoldMiddle	table	framexml
+TradePlayerInputMoneyFrameGoldRight	table	framexml
+TradePlayerInputMoneyFrameSilver	table	framexml
+TradePlayerInputMoneyFrameSilverLeft	table	framexml
+TradePlayerInputMoneyFrameSilverMiddle	table	framexml
+TradePlayerInputMoneyFrameSilverRight	table	framexml
+TradePlayerItem1	table	framexml
+TradePlayerItem1ItemButton	table	framexml
+TradePlayerItem1ItemButtonCount	table	framexml
+TradePlayerItem1ItemButtonIconTexture	table	framexml
+TradePlayerItem1ItemButtonNormalTexture	table	framexml
+TradePlayerItem1ItemButtonStock	table	framexml
+TradePlayerItem1Name	table	framexml
+TradePlayerItem1NameFrame	table	framexml
+TradePlayerItem1SlotTexture	table	framexml
+TradePlayerItem2	table	framexml
+TradePlayerItem2ItemButton	table	framexml
+TradePlayerItem2ItemButtonCount	table	framexml
+TradePlayerItem2ItemButtonIconTexture	table	framexml
+TradePlayerItem2ItemButtonNormalTexture	table	framexml
+TradePlayerItem2ItemButtonStock	table	framexml
+TradePlayerItem2Name	table	framexml
+TradePlayerItem2NameFrame	table	framexml
+TradePlayerItem2SlotTexture	table	framexml
+TradePlayerItem3	table	framexml
+TradePlayerItem3ItemButton	table	framexml
+TradePlayerItem3ItemButtonCount	table	framexml
+TradePlayerItem3ItemButtonIconTexture	table	framexml
+TradePlayerItem3ItemButtonNormalTexture	table	framexml
+TradePlayerItem3ItemButtonStock	table	framexml
+TradePlayerItem3Name	table	framexml
+TradePlayerItem3NameFrame	table	framexml
+TradePlayerItem3SlotTexture	table	framexml
+TradePlayerItem4	table	framexml
+TradePlayerItem4ItemButton	table	framexml
+TradePlayerItem4ItemButtonCount	table	framexml
+TradePlayerItem4ItemButtonIconTexture	table	framexml
+TradePlayerItem4ItemButtonNormalTexture	table	framexml
+TradePlayerItem4ItemButtonStock	table	framexml
+TradePlayerItem4Name	table	framexml
+TradePlayerItem4NameFrame	table	framexml
+TradePlayerItem4SlotTexture	table	framexml
+TradePlayerItem5	table	framexml
+TradePlayerItem5ItemButton	table	framexml
+TradePlayerItem5ItemButtonCount	table	framexml
+TradePlayerItem5ItemButtonIconTexture	table	framexml
+TradePlayerItem5ItemButtonNormalTexture	table	framexml
+TradePlayerItem5ItemButtonStock	table	framexml
+TradePlayerItem5Name	table	framexml
+TradePlayerItem5NameFrame	table	framexml
+TradePlayerItem5SlotTexture	table	framexml
+TradePlayerItem6	table	framexml
+TradePlayerItem6ItemButton	table	framexml
+TradePlayerItem6ItemButtonCount	table	framexml
+TradePlayerItem6ItemButtonIconTexture	table	framexml
+TradePlayerItem6ItemButtonNormalTexture	table	framexml
+TradePlayerItem6ItemButtonStock	table	framexml
+TradePlayerItem6Name	table	framexml
+TradePlayerItem6NameFrame	table	framexml
+TradePlayerItem6SlotTexture	table	framexml
+TradePlayerItem7	table	framexml
+TradePlayerItem7ItemButton	table	framexml
+TradePlayerItem7ItemButtonCount	table	framexml
+TradePlayerItem7ItemButtonIconTexture	table	framexml
+TradePlayerItem7ItemButtonNormalTexture	table	framexml
+TradePlayerItem7ItemButtonStock	table	framexml
+TradePlayerItem7Name	table	framexml
+TradePlayerItem7NameFrame	table	framexml
+TradePlayerItem7SlotTexture	table	framexml
+TradeRecipientItem1	table	framexml
+TradeRecipientItem1ItemButton	table	framexml
+TradeRecipientItem1ItemButtonCount	table	framexml
+TradeRecipientItem1ItemButtonIconTexture	table	framexml
+TradeRecipientItem1ItemButtonNormalTexture	table	framexml
+TradeRecipientItem1ItemButtonStock	table	framexml
+TradeRecipientItem1Name	table	framexml
+TradeRecipientItem1NameFrame	table	framexml
+TradeRecipientItem1SlotTexture	table	framexml
+TradeRecipientItem2	table	framexml
+TradeRecipientItem2ItemButton	table	framexml
+TradeRecipientItem2ItemButtonCount	table	framexml
+TradeRecipientItem2ItemButtonIconTexture	table	framexml
+TradeRecipientItem2ItemButtonNormalTexture	table	framexml
+TradeRecipientItem2ItemButtonStock	table	framexml
+TradeRecipientItem2Name	table	framexml
+TradeRecipientItem2NameFrame	table	framexml
+TradeRecipientItem2SlotTexture	table	framexml
+TradeRecipientItem3	table	framexml
+TradeRecipientItem3ItemButton	table	framexml
+TradeRecipientItem3ItemButtonCount	table	framexml
+TradeRecipientItem3ItemButtonIconTexture	table	framexml
+TradeRecipientItem3ItemButtonNormalTexture	table	framexml
+TradeRecipientItem3ItemButtonStock	table	framexml
+TradeRecipientItem3Name	table	framexml
+TradeRecipientItem3NameFrame	table	framexml
+TradeRecipientItem3SlotTexture	table	framexml
+TradeRecipientItem4	table	framexml
+TradeRecipientItem4ItemButton	table	framexml
+TradeRecipientItem4ItemButtonCount	table	framexml
+TradeRecipientItem4ItemButtonIconTexture	table	framexml
+TradeRecipientItem4ItemButtonNormalTexture	table	framexml
+TradeRecipientItem4ItemButtonStock	table	framexml
+TradeRecipientItem4Name	table	framexml
+TradeRecipientItem4NameFrame	table	framexml
+TradeRecipientItem4SlotTexture	table	framexml
+TradeRecipientItem5	table	framexml
+TradeRecipientItem5ItemButton	table	framexml
+TradeRecipientItem5ItemButtonCount	table	framexml
+TradeRecipientItem5ItemButtonIconTexture	table	framexml
+TradeRecipientItem5ItemButtonNormalTexture	table	framexml
+TradeRecipientItem5ItemButtonStock	table	framexml
+TradeRecipientItem5Name	table	framexml
+TradeRecipientItem5NameFrame	table	framexml
+TradeRecipientItem5SlotTexture	table	framexml
+TradeRecipientItem6	table	framexml
+TradeRecipientItem6ItemButton	table	framexml
+TradeRecipientItem6ItemButtonCount	table	framexml
+TradeRecipientItem6ItemButtonIconTexture	table	framexml
+TradeRecipientItem6ItemButtonNormalTexture	table	framexml
+TradeRecipientItem6ItemButtonStock	table	framexml
+TradeRecipientItem6Name	table	framexml
+TradeRecipientItem6NameFrame	table	framexml
+TradeRecipientItem6SlotTexture	table	framexml
+TradeRecipientItem7	table	framexml
+TradeRecipientItem7ItemButton	table	framexml
+TradeRecipientItem7ItemButtonCount	table	framexml
+TradeRecipientItem7ItemButtonIconTexture	table	framexml
+TradeRecipientItem7ItemButtonNormalTexture	table	framexml
+TradeRecipientItem7ItemButtonStock	table	framexml
+TradeRecipientItem7Name	table	framexml
+TradeRecipientItem7NameFrame	table	framexml
+TradeRecipientItem7SlotTexture	table	framexml
+TradeRecipientMoneyFrame	table	framexml
+TradeRecipientMoneyFrameCopperButton	table	framexml
+TradeRecipientMoneyFrameCopperButtonText	table	framexml
+TradeRecipientMoneyFrameGoldButton	table	framexml
+TradeRecipientMoneyFrameGoldButtonText	table	framexml
+TradeRecipientMoneyFrameSilverButton	table	framexml
+TradeRecipientMoneyFrameSilverButtonText	table	framexml
+TradeSkillCancelButton	lod	framexml
+TradeSkillCollapseAllButton	lod	framexml
+TradeSkillCollapseAllButton_OnClick	lod	framexml
+TradeSkillCreateAllButton	lod	framexml
+TradeSkillCreateButton	lod	framexml
+TradeSkillDecrementButton	lod	framexml
+TradeSkillDetailHeaderLeft	lod	framexml
+TradeSkillDetailScrollChildFrame	lod	framexml
+TradeSkillDetailScrollFrame	lod	framexml
+TradeSkillExpandButtonFrame	lod	framexml
+TradeSkillExpandTabLeft	lod	framexml
+TradeSkillExpandTabMiddle	lod	framexml
+TradeSkillExpandTabRight	lod	framexml
+TradeSkillFilterFrame_LoadInvSlots	lod	framexml
+TradeSkillFilterFrame_LoadSubClasses	lod	framexml
+TradeSkillFrame	lod	framexml
+TradeSkillFrameCloseButton	lod	framexml
+TradeSkillFrameDecrement_OnClick	lod	framexml
+TradeSkillFrameIncrement_OnClick	lod	framexml
+TradeSkillFramePortrait	lod	framexml
+TradeSkillFrameTitleText	lod	framexml
+TradeSkillFrame_Hide	lod	framexml
+TradeSkillFrame_LoadUI	function	framexml
+TradeSkillFrame_OnEvent	lod	framexml
+TradeSkillFrame_OnLoad	lod	framexml
+TradeSkillFrame_SetSelection	lod	framexml
+TradeSkillFrame_Show	lod	framexml
+TradeSkillFrame_Update	lod	framexml
+TradeSkillHighlight	lod	framexml
+TradeSkillHighlightFrame	lod	framexml
+TradeSkillHorizontalBarLeft	lod	framexml
+TradeSkillIncrementButton	lod	framexml
+TradeSkillInputBox	lod	framexml
+TradeSkillInvSlotDropDown	lod	framexml
+TradeSkillInvSlotDropDownButton_OnClick	lod	framexml
+TradeSkillInvSlotDropDown_Initialize	lod	framexml
+TradeSkillInvSlotDropDown_OnLoad	lod	framexml
+TradeSkillInvSlotDropDown_OnShow	lod	framexml
+TradeSkillItemTemplate	lod	framexml
+TradeSkillListScrollFrame	lod	framexml
+TradeSkillRankFrame	lod	framexml
+TradeSkillReagent1	lod	framexml
+TradeSkillReagent2	lod	framexml
+TradeSkillReagent3	lod	framexml
+TradeSkillReagent4	lod	framexml
+TradeSkillReagent5	lod	framexml
+TradeSkillReagent6	lod	framexml
+TradeSkillReagent7	lod	framexml
+TradeSkillReagent8	lod	framexml
+TradeSkillReagentLabel	lod	framexml
+TradeSkillRequirementLabel	lod	framexml
+TradeSkillRequirementText	lod	framexml
+TradeSkillSkill1	lod	framexml
+TradeSkillSkill2	lod	framexml
+TradeSkillSkill3	lod	framexml
+TradeSkillSkill4	lod	framexml
+TradeSkillSkill5	lod	framexml
+TradeSkillSkill6	lod	framexml
+TradeSkillSkill7	lod	framexml
+TradeSkillSkill8	lod	framexml
+TradeSkillSkillBorderLeft	lod	framexml
+TradeSkillSkillButtonTemplate	lod	framexml
+TradeSkillSkillButton_OnClick	lod	framexml
+TradeSkillSkillCooldown	lod	framexml
+TradeSkillSkillIcon	lod	framexml
+TradeSkillSkillIconCount	lod	framexml
+TradeSkillSkillLineName	lod	framexml
+TradeSkillSkillName	lod	framexml
+TradeSkillSubClassDropDown	lod	framexml
+TradeSkillSubClassDropDownButton_OnClick	lod	framexml
+TradeSkillSubClassDropDown_Initialize	lod	framexml
+TradeSkillSubClassDropDown_OnLoad	lod	framexml
+TradeSkillSubClassDropDown_OnShow	lod	framexml
+TradeSkillTypeColor	lod	framexml
+TurnInGuildCharter	function	engine
+TurnLeftStart	function	engine
+TurnLeftStop	function	engine
+TurnOrActionStart	function	engine
+TurnOrActionStop	function	engine
+TurnRightStart	function	engine
+TurnRightStop	function	engine
+TutorialFrame	table	framexml
+TutorialFrameAlertButton1	table	framexml
+TutorialFrameAlertButton10	table	framexml
+TutorialFrameAlertButton2	table	framexml
+TutorialFrameAlertButton3	table	framexml
+TutorialFrameAlertButton4	table	framexml
+TutorialFrameAlertButton5	table	framexml
+TutorialFrameAlertButton6	table	framexml
+TutorialFrameAlertButton7	table	framexml
+TutorialFrameAlertButton8	table	framexml
+TutorialFrameAlertButton9	table	framexml
+TutorialFrameAlertButtonTemplate	lod	framexml
+TutorialFrameCheckButton	table	framexml
+TutorialFrameCheckButtonText	table	framexml
+TutorialFrameCheckboxText	table	framexml
+TutorialFrameOkayButton	table	framexml
+TutorialFrameParent	table	framexml
+TutorialFrameText	table	framexml
+TutorialFrameTitle	table	framexml
+TutorialFrame_CheckIntro	function	framexml
+TutorialFrame_GetAlertButton	function	framexml
+TutorialFrame_HideAllAlerts	function	framexml
+TutorialFrame_NewTutorial	function	framexml
+TutorialFrame_OnHide	function	framexml
+TutorialFrame_Update	function	framexml
+TutorialsEnabled	function	engine
+TwentyFourHourTime	number	framexml
+UICheckButtonTemplate	lod	framexml
+UIChildWindows	table	framexml
+UIDROPDOWNMENU_BORDER_HEIGHT	number	framexml
+UIDROPDOWNMENU_BUTTON_HEIGHT	number	framexml
+UIDROPDOWNMENU_DEFAULT_TEXT_HEIGHT	number	framexml
+UIDROPDOWNMENU_INIT_MENU	string	framexml
+UIDROPDOWNMENU_MAXBUTTONS	number	framexml
+UIDROPDOWNMENU_MAXLEVELS	number	framexml
+UIDROPDOWNMENU_MENU_LEVEL	number	framexml
+UIDROPDOWNMENU_MENU_VALUE	lod	framexml
+UIDROPDOWNMENU_OPEN_MENU	lod	framexml
+UIDROPDOWNMENU_SHOW_TIME	number	framexml
+UIDropDownListTemplate	lod	framexml
+UIDropDownMenuButtonTemplate	lod	framexml
+UIDropDownMenuButton_GetChecked	function	framexml
+UIDropDownMenuButton_GetName	function	framexml
+UIDropDownMenuButton_OnClick	function	framexml
+UIDropDownMenuButton_OpenColorPicker	function	framexml
+UIDropDownMenuTemplate	lod	framexml
+UIDropDownMenu_AddButton	function	framexml
+UIDropDownMenu_ClearAll	function	framexml
+UIDropDownMenu_DisableButton	function	framexml
+UIDropDownMenu_EnableButton	function	framexml
+UIDropDownMenu_GetCurrentDropDown	function	framexml
+UIDropDownMenu_GetSelectedID	function	framexml
+UIDropDownMenu_GetSelectedName	function	framexml
+UIDropDownMenu_GetSelectedValue	function	framexml
+UIDropDownMenu_GetText	function	framexml
+UIDropDownMenu_Initialize	function	framexml
+UIDropDownMenu_JustifyText	function	framexml
+UIDropDownMenu_OnUpdate	function	framexml
+UIDropDownMenu_Refresh	function	framexml
+UIDropDownMenu_SetAnchor	function	framexml
+UIDropDownMenu_SetButtonText	function	framexml
+UIDropDownMenu_SetButtonWidth	function	framexml
+UIDropDownMenu_SetSelectedID	function	framexml
+UIDropDownMenu_SetSelectedName	function	framexml
+UIDropDownMenu_SetSelectedValue	function	framexml
+UIDropDownMenu_SetText	function	framexml
+UIDropDownMenu_SetWidth	function	framexml
+UIDropDownMenu_StartCounting	function	framexml
+UIDropDownMenu_StopCounting	function	framexml
+UIErrorsFrame	table	framexml
+UIErrorsFrame_OnEvent	function	framexml
+UIErrorsFrame_OnLoad	function	framexml
+UIFrameFade	function	framexml
+UIFrameFadeIn	function	framexml
+UIFrameFadeOut	function	framexml
+UIFrameFadeRemoveFrame	function	framexml
+UIFrameFadeUpdate	function	framexml
+UIFrameFlash	function	framexml
+UIFrameFlashRemoveFrame	function	framexml
+UIFrameFlashStop	function	framexml
+UIFrameFlashSwitch	function	framexml
+UIFrameFlashUpdate	function	framexml
+UIFrameIsFading	function	framexml
+UIFrameIsFlashing	function	framexml
+UIMENU_BORDER_HEIGHT	number	framexml
+UIMENU_BORDER_WIDTH	number	framexml
+UIMENU_BUTTON_HEIGHT	number	framexml
+UIMENU_BUTTON_WIDTH	number	framexml
+UIMENU_NUMBUTTONS	number	framexml
+UIMENU_TIMEOUT	number	framexml
+UIMenuButtonTemplate	lod	framexml
+UIMenuButton_OnClick	function	framexml
+UIMenuButton_OnEnter	function	framexml
+UIMenuButton_OnLeave	function	framexml
+UIMenuButton_OnLoad	function	framexml
+UIMenuTemplate	lod	framexml
+UIMenu_AddButton	function	framexml
+UIMenu_Initialize	function	framexml
+UIMenu_OnShow	function	framexml
+UIMenu_OnUpdate	function	framexml
+UIMenu_StartCounting	function	framexml
+UIMenu_StopCounting	function	framexml
+UIMenus	table	framexml
+UIOPTIONS_MENU	string	framexml
+UIOptionsBlackground	table	framexml
+UIOptionsCheckButtonTemplate	lod	framexml
+UIOptionsFrame	table	framexml
+UIOptionsFrameCameraDropDown	table	framexml
+UIOptionsFrameCameraDropDownButton	table	framexml
+UIOptionsFrameCameraDropDownButtonDisabledTexture	table	framexml
+UIOptionsFrameCameraDropDownButtonHighlightTexture	table	framexml
+UIOptionsFrameCameraDropDownButtonNormalTexture	table	framexml
+UIOptionsFrameCameraDropDownButtonPushedTexture	table	framexml
+UIOptionsFrameCameraDropDownLabel	table	framexml
+UIOptionsFrameCameraDropDownLeft	table	framexml
+UIOptionsFrameCameraDropDownMiddle	table	framexml
+UIOptionsFrameCameraDropDownRight	table	framexml
+UIOptionsFrameCameraDropDownText	table	framexml
+UIOptionsFrameCameraDropDown_Initialize	function	framexml
+UIOptionsFrameCameraDropDown_OnClick	function	framexml
+UIOptionsFrameCameraDropDown_OnLoad	function	framexml
+UIOptionsFrameCancel	table	framexml
+UIOptionsFrameCancelText	table	framexml
+UIOptionsFrameCheckButton1	table	framexml
+UIOptionsFrameCheckButton11	table	framexml
+UIOptionsFrameCheckButton11Text	table	framexml
+UIOptionsFrameCheckButton12	table	framexml
+UIOptionsFrameCheckButton12Text	table	framexml
+UIOptionsFrameCheckButton13	table	framexml
+UIOptionsFrameCheckButton13Text	table	framexml
+UIOptionsFrameCheckButton14	table	framexml
+UIOptionsFrameCheckButton14Text	table	framexml
+UIOptionsFrameCheckButton15	table	framexml
+UIOptionsFrameCheckButton15Text	table	framexml
+UIOptionsFrameCheckButton16	table	framexml
+UIOptionsFrameCheckButton16Text	table	framexml
+UIOptionsFrameCheckButton18	table	framexml
+UIOptionsFrameCheckButton18Text	table	framexml
+UIOptionsFrameCheckButton19	table	framexml
+UIOptionsFrameCheckButton19Text	table	framexml
+UIOptionsFrameCheckButton1Text	table	framexml
+UIOptionsFrameCheckButton2	table	framexml
+UIOptionsFrameCheckButton20	table	framexml
+UIOptionsFrameCheckButton20Text	table	framexml
+UIOptionsFrameCheckButton21	table	framexml
+UIOptionsFrameCheckButton21Text	table	framexml
+UIOptionsFrameCheckButton22	table	framexml
+UIOptionsFrameCheckButton22Text	table	framexml
+UIOptionsFrameCheckButton23	table	framexml
+UIOptionsFrameCheckButton23Text	table	framexml
+UIOptionsFrameCheckButton24	table	framexml
+UIOptionsFrameCheckButton24Text	table	framexml
+UIOptionsFrameCheckButton26	table	framexml
+UIOptionsFrameCheckButton26Text	table	framexml
+UIOptionsFrameCheckButton27	table	framexml
+UIOptionsFrameCheckButton27Text	table	framexml
+UIOptionsFrameCheckButton28	table	framexml
+UIOptionsFrameCheckButton28Text	table	framexml
+UIOptionsFrameCheckButton29	table	framexml
+UIOptionsFrameCheckButton29Text	table	framexml
+UIOptionsFrameCheckButton2Text	table	framexml
+UIOptionsFrameCheckButton3	table	framexml
+UIOptionsFrameCheckButton30	table	framexml
+UIOptionsFrameCheckButton30Text	table	framexml
+UIOptionsFrameCheckButton31	table	framexml
+UIOptionsFrameCheckButton31Text	table	framexml
+UIOptionsFrameCheckButton32	table	framexml
+UIOptionsFrameCheckButton32Text	table	framexml
+UIOptionsFrameCheckButton33	table	framexml
+UIOptionsFrameCheckButton33Text	table	framexml
+UIOptionsFrameCheckButton34	table	framexml
+UIOptionsFrameCheckButton34Text	table	framexml
+UIOptionsFrameCheckButton35	table	framexml
+UIOptionsFrameCheckButton35Text	table	framexml
+UIOptionsFrameCheckButton36	table	framexml
+UIOptionsFrameCheckButton36Text	table	framexml
+UIOptionsFrameCheckButton37	table	framexml
+UIOptionsFrameCheckButton37Text	table	framexml
+UIOptionsFrameCheckButton38	table	framexml
+UIOptionsFrameCheckButton38Text	table	framexml
+UIOptionsFrameCheckButton39	table	framexml
+UIOptionsFrameCheckButton39Text	table	framexml
+UIOptionsFrameCheckButton3Text	table	framexml
+UIOptionsFrameCheckButton40	table	framexml
+UIOptionsFrameCheckButton40Text	table	framexml
+UIOptionsFrameCheckButton41	table	framexml
+UIOptionsFrameCheckButton41Text	table	framexml
+UIOptionsFrameCheckButton42	table	framexml
+UIOptionsFrameCheckButton42Text	table	framexml
+UIOptionsFrameCheckButton43	table	framexml
+UIOptionsFrameCheckButton43Text	table	framexml
+UIOptionsFrameCheckButton44	table	framexml
+UIOptionsFrameCheckButton44Text	table	framexml
+UIOptionsFrameCheckButton45	table	framexml
+UIOptionsFrameCheckButton45Text	table	framexml
+UIOptionsFrameCheckButton46	table	framexml
+UIOptionsFrameCheckButton46Text	table	framexml
+UIOptionsFrameCheckButton47	table	framexml
+UIOptionsFrameCheckButton47Text	table	framexml
+UIOptionsFrameCheckButton48	table	framexml
+UIOptionsFrameCheckButton48Text	table	framexml
+UIOptionsFrameCheckButton49	table	framexml
+UIOptionsFrameCheckButton49Text	table	framexml
+UIOptionsFrameCheckButton5	table	framexml
+UIOptionsFrameCheckButton50	table	framexml
+UIOptionsFrameCheckButton50Text	table	framexml
+UIOptionsFrameCheckButton51	table	framexml
+UIOptionsFrameCheckButton51Text	table	framexml
+UIOptionsFrameCheckButton52	table	framexml
+UIOptionsFrameCheckButton52Text	table	framexml
+UIOptionsFrameCheckButton53	table	framexml
+UIOptionsFrameCheckButton53Text	table	framexml
+UIOptionsFrameCheckButton54	table	framexml
+UIOptionsFrameCheckButton54Text	table	framexml
+UIOptionsFrameCheckButton55	table	framexml
+UIOptionsFrameCheckButton55Text	table	framexml
+UIOptionsFrameCheckButton56	table	framexml
+UIOptionsFrameCheckButton56Text	table	framexml
+UIOptionsFrameCheckButton57	table	framexml
+UIOptionsFrameCheckButton57Text	table	framexml
+UIOptionsFrameCheckButton58	table	framexml
+UIOptionsFrameCheckButton58Text	table	framexml
+UIOptionsFrameCheckButton59	table	framexml
+UIOptionsFrameCheckButton59Text	table	framexml
+UIOptionsFrameCheckButton5Text	table	framexml
+UIOptionsFrameCheckButton6	table	framexml
+UIOptionsFrameCheckButton60	table	framexml
+UIOptionsFrameCheckButton60Text	table	framexml
+UIOptionsFrameCheckButton61	table	framexml
+UIOptionsFrameCheckButton61Text	table	framexml
+UIOptionsFrameCheckButton62	table	framexml
+UIOptionsFrameCheckButton62Text	table	framexml
+UIOptionsFrameCheckButton63	table	framexml
+UIOptionsFrameCheckButton63Text	table	framexml
+UIOptionsFrameCheckButton64	table	framexml
+UIOptionsFrameCheckButton64Text	table	framexml
+UIOptionsFrameCheckButton65	table	framexml
+UIOptionsFrameCheckButton65Text	table	framexml
+UIOptionsFrameCheckButton66	table	framexml
+UIOptionsFrameCheckButton66Text	table	framexml
+UIOptionsFrameCheckButton67	table	framexml
+UIOptionsFrameCheckButton67Text	table	framexml
+UIOptionsFrameCheckButton68	table	framexml
+UIOptionsFrameCheckButton68Text	table	framexml
+UIOptionsFrameCheckButton69	table	framexml
+UIOptionsFrameCheckButton69Text	table	framexml
+UIOptionsFrameCheckButton6Text	table	framexml
+UIOptionsFrameCheckButton7	table	framexml
+UIOptionsFrameCheckButton7Text	table	framexml
+UIOptionsFrameCheckButton8	table	framexml
+UIOptionsFrameCheckButton8Text	table	framexml
+UIOptionsFrameCheckButton9	table	framexml
+UIOptionsFrameCheckButton9Text	table	framexml
+UIOptionsFrameCheckButtons	table	framexml
+UIOptionsFrameClickCameraDropDown	table	framexml
+UIOptionsFrameClickCameraDropDownButton	table	framexml
+UIOptionsFrameClickCameraDropDownButtonDisabledTexture	table	framexml
+UIOptionsFrameClickCameraDropDownButtonHighlightTexture	table	framexml
+UIOptionsFrameClickCameraDropDownButtonNormalTexture	table	framexml
+UIOptionsFrameClickCameraDropDownButtonPushedTexture	table	framexml
+UIOptionsFrameClickCameraDropDownLabel	table	framexml
+UIOptionsFrameClickCameraDropDownLeft	table	framexml
+UIOptionsFrameClickCameraDropDownMiddle	table	framexml
+UIOptionsFrameClickCameraDropDownRight	table	framexml
+UIOptionsFrameClickCameraDropDownText	table	framexml
+UIOptionsFrameClickCameraDropDown_Initialize	function	framexml
+UIOptionsFrameClickCameraDropDown_OnClick	function	framexml
+UIOptionsFrameClickCameraDropDown_OnLoad	function	framexml
+UIOptionsFrameCombatTextDropDown	table	framexml
+UIOptionsFrameCombatTextDropDownButton	table	framexml
+UIOptionsFrameCombatTextDropDownButtonDisabledTexture	table	framexml
+UIOptionsFrameCombatTextDropDownButtonHighlightTexture	table	framexml
+UIOptionsFrameCombatTextDropDownButtonNormalTexture	table	framexml
+UIOptionsFrameCombatTextDropDownButtonPushedTexture	table	framexml
+UIOptionsFrameCombatTextDropDownLabel	table	framexml
+UIOptionsFrameCombatTextDropDownLeft	table	framexml
+UIOptionsFrameCombatTextDropDownMiddle	table	framexml
+UIOptionsFrameCombatTextDropDownRight	table	framexml
+UIOptionsFrameCombatTextDropDownText	table	framexml
+UIOptionsFrameCombatTextDropDown_Initialize	function	framexml
+UIOptionsFrameCombatTextDropDown_OnClick	function	framexml
+UIOptionsFrameCombatTextDropDown_OnLoad	function	framexml
+UIOptionsFrameDefaults	table	framexml
+UIOptionsFrameDefaultsText	table	framexml
+UIOptionsFrameMultiBar_Reset	function	framexml
+UIOptionsFrameOkay	table	framexml
+UIOptionsFrameOkayText	table	framexml
+UIOptionsFrameResetTutorials	table	framexml
+UIOptionsFrameResetTutorialsText	table	framexml
+UIOptionsFrameSlider1	table	framexml
+UIOptionsFrameSlider1High	table	framexml
+UIOptionsFrameSlider1Low	table	framexml
+UIOptionsFrameSlider1Text	table	framexml
+UIOptionsFrameSlider1Thumb	table	framexml
+UIOptionsFrameSlider2	table	framexml
+UIOptionsFrameSlider2High	table	framexml
+UIOptionsFrameSlider2Low	table	framexml
+UIOptionsFrameSlider2Text	table	framexml
+UIOptionsFrameSlider2Thumb	table	framexml
+UIOptionsFrameSlider3	table	framexml
+UIOptionsFrameSlider3High	table	framexml
+UIOptionsFrameSlider3Low	table	framexml
+UIOptionsFrameSlider3Text	table	framexml
+UIOptionsFrameSlider3Thumb	table	framexml
+UIOptionsFrameSlider4	table	framexml
+UIOptionsFrameSlider4High	table	framexml
+UIOptionsFrameSlider4Low	table	framexml
+UIOptionsFrameSlider4Text	table	framexml
+UIOptionsFrameSlider4Thumb	table	framexml
+UIOptionsFrameSliders	table	framexml
+UIOptionsFrameTab1	table	framexml
+UIOptionsFrameTab1HighlightTexture	table	framexml
+UIOptionsFrameTab1Left	table	framexml
+UIOptionsFrameTab1LeftDisabled	table	framexml
+UIOptionsFrameTab1Middle	table	framexml
+UIOptionsFrameTab1MiddleDisabled	table	framexml
+UIOptionsFrameTab1Right	table	framexml
+UIOptionsFrameTab1RightDisabled	table	framexml
+UIOptionsFrameTab1Text	table	framexml
+UIOptionsFrameTab2	table	framexml
+UIOptionsFrameTab2HighlightTexture	table	framexml
+UIOptionsFrameTab2Left	table	framexml
+UIOptionsFrameTab2LeftDisabled	table	framexml
+UIOptionsFrameTab2Middle	table	framexml
+UIOptionsFrameTab2MiddleDisabled	table	framexml
+UIOptionsFrameTab2Right	table	framexml
+UIOptionsFrameTab2RightDisabled	table	framexml
+UIOptionsFrameTab2Text	table	framexml
+UIOptionsFrameTargetofTargetDropDown	table	framexml
+UIOptionsFrameTargetofTargetDropDownButton	table	framexml
+UIOptionsFrameTargetofTargetDropDownButtonDisabledTexture	table	framexml
+UIOptionsFrameTargetofTargetDropDownButtonHighlightTexture	table	framexml
+UIOptionsFrameTargetofTargetDropDownButtonNormalTexture	table	framexml
+UIOptionsFrameTargetofTargetDropDownButtonPushedTexture	table	framexml
+UIOptionsFrameTargetofTargetDropDownLabel	table	framexml
+UIOptionsFrameTargetofTargetDropDownLeft	table	framexml
+UIOptionsFrameTargetofTargetDropDownMiddle	table	framexml
+UIOptionsFrameTargetofTargetDropDownRight	table	framexml
+UIOptionsFrameTargetofTargetDropDownText	table	framexml
+UIOptionsFrameTargetofTargetDropDown_Initialize	function	framexml
+UIOptionsFrameTargetofTargetDropDown_OnClick	function	framexml
+UIOptionsFrameTargetofTargetDropDown_OnLoad	function	framexml
+UIOptionsFrameTitle	table	framexml
+UIOptionsFrame_Init	function	framexml
+UIOptionsFrame_Load	function	framexml
+UIOptionsFrame_OnEvent	function	framexml
+UIOptionsFrame_Save	function	framexml
+UIOptionsFrame_SetDamageCheckBoxes	function	framexml
+UIOptionsFrame_SetDefaults	function	framexml
+UIOptionsFrame_UpdateDependencies	function	framexml
+UIPARENT_MANAGED_FRAME_POSITIONS	table	framexml
+UIPanelButtonDisabledDownTexture	lod	framexml
+UIPanelButtonDisabledTexture	lod	framexml
+UIPanelButtonDownTexture	lod	framexml
+UIPanelButtonGrayTemplate	lod	framexml
+UIPanelButtonHighlightTexture	lod	framexml
+UIPanelButtonTemplate	lod	framexml
+UIPanelButtonTemplate2	lod	framexml
+UIPanelButtonUpTexture	lod	framexml
+UIPanelCloseButton	lod	framexml
+UIPanelScrollBarButton	lod	framexml
+UIPanelScrollBarTemplate	lod	framexml
+UIPanelScrollDownButtonTemplate	lod	framexml
+UIPanelScrollFrameTemplate	lod	framexml
+UIPanelScrollUpButtonTemplate	lod	framexml
+UIPanelWindows	table	framexml
+UIParent	table	framexml
+UIParentLoadAddOn	function	framexml
+UIParent_ManageFramePositions	function	framexml
+UIParent_OnEvent	function	framexml
+UIParent_OnLoad	function	framexml
+UIRadioButtonTemplate	lod	framexml
+UISpecialFrames	table	framexml
+UI_SCALE	string	framexml
+UKNOWNBEING	string	framexml
+UNAVAILABLE	string	framexml
+UNBIND	string	framexml
+UNITDESTROYEDOTHER	string	framexml
+UNITDIESOTHER	string	framexml
+UNITDIESSELF	string	framexml
+UNITNAME_TITLE	string	framexml
+UNITNAME_TITLE_CHARM	string	framexml
+UNITNAME_TITLE_CREATION	string	framexml
+UNITNAME_TITLE_GUARDIAN	string	framexml
+UNITNAME_TITLE_MINION	string	framexml
+UNITNAME_TITLE_PET	string	framexml
+UNITPOPUP_BORDER_HEIGHT	number	framexml
+UNITPOPUP_BORDER_WIDTH	number	framexml
+UNITPOPUP_BUTTON_HEIGHT	number	framexml
+UNITPOPUP_NUMBUTTONS	number	framexml
+UNITPOPUP_SPACER_SPACING	number	framexml
+UNITPOPUP_TIMEOUT	number	framexml
+UNITPOPUP_TITLE_HEIGHT	number	framexml
+UNIT_LETHAL_LEVEL_DEAD_TEMPLATE	string	framexml
+UNIT_LETHAL_LEVEL_TEMPLATE	string	framexml
+UNIT_LEVEL_DEAD_TEMPLATE	string	framexml
+UNIT_LEVEL_TEMPLATE	string	framexml
+UNIT_NAME_FONT	string	framexml
+UNIT_PLUS_LEVEL_TEMPLATE	string	framexml
+UNIT_PVP_NAME	string	framexml
+UNIT_SKINNABLE	string	framexml
+UNIT_TYPE_LETHAL_LEVEL_TEMPLATE	string	framexml
+UNIT_TYPE_LEVEL_TEMPLATE	string	framexml
+UNIT_TYPE_PLUS_LEVEL_TEMPLATE	string	framexml
+UNKNOWN	string	framexml
+UNKNOWNOBJECT	string	framexml
+UNLEARN	string	framexml
+UNLEARN_SKILL	string	framexml
+UNLEARN_SKILL_TOOLTIP	string	framexml
+UNLOCK_WINDOW	string	framexml
+UPDATE_DELAY	number	framexml
+USABLE_ITEMS	string	framexml
+USE	string	framexml
+USED	string	framexml
+USE_ITEM	string	framexml
+USE_NO_DROP	string	framexml
+USE_SOULSTONE	string	framexml
+USE_UBERTOOLTIPS	string	framexml
+USE_UISCALE	string	framexml
+USE_WEATHER_SHADER	string	framexml
+UninviteByName	function	engine
+UninviteFromParty	function	engine
+UninviteFromRaid	function	engine
+UnitAffectingCombat	function	engine
+UnitArmor	function	engine
+UnitAttackBothHands	function	engine
+UnitAttackPower	function	engine
+UnitAttackSpeed	function	engine
+UnitBuff	function	engine
+UnitCanAssist	function	engine
+UnitCanAttack	function	engine
+UnitCanCooperate	function	engine
+UnitCharacterPoints	function	engine
+UnitClass	function	engine
+UnitClassification	function	engine
+UnitCreatureFamily	function	engine
+UnitCreatureType	function	engine
+UnitDamage	function	engine
+UnitDebuff	function	engine
+UnitDefense	function	engine
+UnitExists	function	engine
+UnitFactionGroup	function	engine
+UnitFrameHealthBar_Initialize	function	framexml
+UnitFrameHealthBar_OnValueChanged	function	framexml
+UnitFrameHealthBar_Update	function	framexml
+UnitFrameManaBar_Initialize	function	framexml
+UnitFrameManaBar_Update	function	framexml
+UnitFrame_Initialize	function	framexml
+UnitFrame_OnEnter	function	framexml
+UnitFrame_OnEvent	function	framexml
+UnitFrame_OnLeave	function	framexml
+UnitFrame_OnUpdate	function	framexml
+UnitFrame_Update	function	framexml
+UnitFrame_UpdateManaType	function	framexml
+UnitHasRelicSlot	function	engine
+UnitHealth	function	engine
+UnitHealthMax	function	engine
+UnitInParty	function	engine
+UnitInRaid	function	engine
+UnitIsCharmed	function	engine
+UnitIsCivilian	function	engine
+UnitIsConnected	function	engine
+UnitIsCorpse	function	engine
+UnitIsDead	function	engine
+UnitIsDeadOrGhost	function	engine
+UnitIsEnemy	function	engine
+UnitIsFriend	function	engine
+UnitIsGhost	function	engine
+UnitIsPVP	function	engine
+UnitIsPVPFreeForAll	function	engine
+UnitIsPartyLeader	function	engine
+UnitIsPlayer	function	engine
+UnitIsPlusMob	function	engine
+UnitIsTapped	function	engine
+UnitIsTappedByPlayer	function	engine
+UnitIsTrivial	function	engine
+UnitIsUnit	function	engine
+UnitIsVisible	function	engine
+UnitLevel	function	engine
+UnitLootMethod	table	framexml
+UnitMana	function	engine
+UnitManaMax	function	engine
+UnitName	function	engine
+UnitOnTaxi	function	engine
+UnitPVPName	function	engine
+UnitPVPRank	function	engine
+UnitPlayerControlled	function	engine
+UnitPlayerOrPetInParty	function	engine
+UnitPlayerOrPetInRaid	function	engine
+UnitPopupButtons	table	framexml
+UnitPopupFrames	table	framexml
+UnitPopupMenus	table	framexml
+UnitPopupShown	table	framexml
+UnitPopup_HideButtons	function	framexml
+UnitPopup_OnClick	function	framexml
+UnitPopup_OnUpdate	function	framexml
+UnitPopup_ShowMenu	function	framexml
+UnitPowerType	function	engine
+UnitRace	function	engine
+UnitRangedAttack	function	engine
+UnitRangedAttackPower	function	engine
+UnitRangedDamage	function	engine
+UnitReaction	function	engine
+UnitReactionColor	table	framexml
+UnitResistance	function	engine
+UnitSex	function	engine
+UnitStat	function	engine
+UnitXP	function	engine
+UnitXPMax	function	engine
+UnlockPetActionBar	function	framexml
+UnstablePet	function	engine
+UpdateBagButtonHighlight	function	framexml
+UpdateBagSlotStatus	function	framexml
+UpdateCoinPickupFrame	function	framexml
+UpdateDeposit	lod	framexml
+UpdateFunc	lod	framexml
+UpdateGMTicket	function	engine
+UpdateInventoryAlertStatus	function	engine
+UpdateMapHighlight	function	engine
+UpdateMicroButtons	function	framexml
+UpdateNameplates	function	framexml
+UpdatePartyMemberBackground	function	framexml
+UpdateSpells	function	engine
+UpdateStackSplitFrame	function	framexml
+UpdateTalentButton	function	framexml
+UpdateWorldMapArrowFrames	function	engine
+UpperBlackBar	table	framexml
+UseAction	function	engine
+UseContainerItem	function	engine
+UseInventoryItem	function	engine
+UseSoulstone	function	engine
+VERBAL_HARASSMENT	string	framexml
+VERBAL_HARASSMENT_DESCRIPTION	string	framexml
+VERBAL_HARASSMENT_TEXT1	string	framexml
+VERBAL_HARASSMENT_TEXT2	string	framexml
+VERBAL_HARASSMENT_TEXT3	string	framexml
+VERBAL_HARASSMENT_TEXT4	string	framexml
+VERTEX_ANIMATION_SHADERS	string	framexml
+VERTICAL_SYNC	string	framexml
+VICTORY_TEXT0	string	framexml
+VICTORY_TEXT1	string	framexml
+VIDEOOPTIONS_MENU	string	framexml
+VIEWABLE_ACTION_BAR_PAGES	table	framexml
+VISIBLE_CONTAINER_SPACING	number	framexml
+VOICEMACRO_0_Dw_0	string	framexml
+VOICEMACRO_0_Dw_0_FEMALE	string	framexml
+VOICEMACRO_0_Dw_1	string	framexml
+VOICEMACRO_0_Dw_1_FEMALE	string	framexml
+VOICEMACRO_0_Gn_0	string	framexml
+VOICEMACRO_0_Gn_0_FEMALE	string	framexml
+VOICEMACRO_0_Gn_1	string	framexml
+VOICEMACRO_0_Gn_1_FEMALE	string	framexml
+VOICEMACRO_0_Gn_2_FEMALE	string	framexml
+VOICEMACRO_0_Hu_0	string	framexml
+VOICEMACRO_0_Hu_0_FEMALE	string	framexml
+VOICEMACRO_0_Hu_1	string	framexml
+VOICEMACRO_0_Hu_1_FEMALE	string	framexml
+VOICEMACRO_0_Ni_0	string	framexml
+VOICEMACRO_0_Ni_0_FEMALE	string	framexml
+VOICEMACRO_0_Ni_1	string	framexml
+VOICEMACRO_0_Ni_1_FEMALE	string	framexml
+VOICEMACRO_0_Ni_2	string	framexml
+VOICEMACRO_0_Or_0	string	framexml
+VOICEMACRO_0_Or_0_FEMALE	string	framexml
+VOICEMACRO_0_Or_1	string	framexml
+VOICEMACRO_0_Or_1_FEMALE	string	framexml
+VOICEMACRO_0_Sc_0	string	framexml
+VOICEMACRO_0_Sc_0_FEMALE	string	framexml
+VOICEMACRO_0_Sc_1	string	framexml
+VOICEMACRO_0_Sc_1_FEMALE	string	framexml
+VOICEMACRO_0_Ta_0	string	framexml
+VOICEMACRO_0_Ta_0_FEMALE	string	framexml
+VOICEMACRO_0_Ta_1	string	framexml
+VOICEMACRO_0_Ta_1_FEMALE	string	framexml
+VOICEMACRO_0_Ta_2	string	framexml
+VOICEMACRO_0_Tr_0	string	framexml
+VOICEMACRO_0_Tr_0_FEMALE	string	framexml
+VOICEMACRO_0_Tr_1	string	framexml
+VOICEMACRO_0_Tr_1_FEMALE	string	framexml
+VOICEMACRO_10_Dw_0	string	framexml
+VOICEMACRO_10_Dw_0_FEMALE	string	framexml
+VOICEMACRO_10_Dw_1	string	framexml
+VOICEMACRO_10_Dw_1_FEMALE	string	framexml
+VOICEMACRO_10_Gn_0	string	framexml
+VOICEMACRO_10_Gn_0_FEMALE	string	framexml
+VOICEMACRO_10_Gn_1	string	framexml
+VOICEMACRO_10_Gn_1_FEMALE	string	framexml
+VOICEMACRO_10_Hu_0	string	framexml
+VOICEMACRO_10_Hu_0_FEMALE	string	framexml
+VOICEMACRO_10_Hu_1	string	framexml
+VOICEMACRO_10_Hu_1_FEMALE	string	framexml
+VOICEMACRO_10_Ni_0	string	framexml
+VOICEMACRO_10_Ni_0_FEMALE	string	framexml
+VOICEMACRO_10_Ni_1	string	framexml
+VOICEMACRO_10_Ni_1_FEMALE	string	framexml
+VOICEMACRO_10_Or_0	string	framexml
+VOICEMACRO_10_Or_0_FEMALE	string	framexml
+VOICEMACRO_10_Or_1	string	framexml
+VOICEMACRO_10_Or_1_FEMALE	string	framexml
+VOICEMACRO_10_Or_2_FEMALE	string	framexml
+VOICEMACRO_10_Sc_0	string	framexml
+VOICEMACRO_10_Sc_0_FEMALE	string	framexml
+VOICEMACRO_10_Sc_1	string	framexml
+VOICEMACRO_10_Sc_1_FEMALE	string	framexml
+VOICEMACRO_10_Ta_0	string	framexml
+VOICEMACRO_10_Ta_0_FEMALE	string	framexml
+VOICEMACRO_10_Ta_1	string	framexml
+VOICEMACRO_10_Ta_1_FEMALE	string	framexml
+VOICEMACRO_10_Tr_0	string	framexml
+VOICEMACRO_10_Tr_0_FEMALE	string	framexml
+VOICEMACRO_10_Tr_1	string	framexml
+VOICEMACRO_10_Tr_1_FEMALE	string	framexml
+VOICEMACRO_12_Dw_0	string	framexml
+VOICEMACRO_12_Dw_0_FEMALE	string	framexml
+VOICEMACRO_12_Dw_1	string	framexml
+VOICEMACRO_12_Dw_1_FEMALE	string	framexml
+VOICEMACRO_12_Dw_2	string	framexml
+VOICEMACRO_12_Dw_2_FEMALE	string	framexml
+VOICEMACRO_12_Dw_3	string	framexml
+VOICEMACRO_12_Gn_0	string	framexml
+VOICEMACRO_12_Gn_0_FEMALE	string	framexml
+VOICEMACRO_12_Gn_1	string	framexml
+VOICEMACRO_12_Gn_1_FEMALE	string	framexml
+VOICEMACRO_12_Gn_2	string	framexml
+VOICEMACRO_12_Gn_2_FEMALE	string	framexml
+VOICEMACRO_12_Gn_3	string	framexml
+VOICEMACRO_12_Hu_0	string	framexml
+VOICEMACRO_12_Hu_0_FEMALE	string	framexml
+VOICEMACRO_12_Hu_1	string	framexml
+VOICEMACRO_12_Hu_1_FEMALE	string	framexml
+VOICEMACRO_12_Hu_2	string	framexml
+VOICEMACRO_12_Hu_2_FEMALE	string	framexml
+VOICEMACRO_12_Hu_3	string	framexml
+VOICEMACRO_12_Ni_0	string	framexml
+VOICEMACRO_12_Ni_0_FEMALE	string	framexml
+VOICEMACRO_12_Ni_1	string	framexml
+VOICEMACRO_12_Ni_1_FEMALE	string	framexml
+VOICEMACRO_12_Ni_2	string	framexml
+VOICEMACRO_12_Ni_2_FEMALE	string	framexml
+VOICEMACRO_12_Ni_3_FEMALE	string	framexml
+VOICEMACRO_12_Or_0	string	framexml
+VOICEMACRO_12_Or_0_FEMALE	string	framexml
+VOICEMACRO_12_Or_1	string	framexml
+VOICEMACRO_12_Or_1_FEMALE	string	framexml
+VOICEMACRO_12_Or_2	string	framexml
+VOICEMACRO_12_Or_2_FEMALE	string	framexml
+VOICEMACRO_12_Sc_0	string	framexml
+VOICEMACRO_12_Sc_0_FEMALE	string	framexml
+VOICEMACRO_12_Sc_1	string	framexml
+VOICEMACRO_12_Sc_1_FEMALE	string	framexml
+VOICEMACRO_12_Sc_2	string	framexml
+VOICEMACRO_12_Sc_2_FEMALE	string	framexml
+VOICEMACRO_12_Ta_0	string	framexml
+VOICEMACRO_12_Ta_0_FEMALE	string	framexml
+VOICEMACRO_12_Ta_1	string	framexml
+VOICEMACRO_12_Ta_1_FEMALE	string	framexml
+VOICEMACRO_12_Ta_2	string	framexml
+VOICEMACRO_12_Ta_2_FEMALE	string	framexml
+VOICEMACRO_12_Tr_0	string	framexml
+VOICEMACRO_12_Tr_0_FEMALE	string	framexml
+VOICEMACRO_12_Tr_1	string	framexml
+VOICEMACRO_12_Tr_1_FEMALE	string	framexml
+VOICEMACRO_12_Tr_2	string	framexml
+VOICEMACRO_12_Tr_2_FEMALE	string	framexml
+VOICEMACRO_13_Dw_0	string	framexml
+VOICEMACRO_13_Dw_0_FEMALE	string	framexml
+VOICEMACRO_13_Dw_1	string	framexml
+VOICEMACRO_13_Dw_1_FEMALE	string	framexml
+VOICEMACRO_13_Dw_2	string	framexml
+VOICEMACRO_13_Dw_2_FEMALE	string	framexml
+VOICEMACRO_13_Gn_0	string	framexml
+VOICEMACRO_13_Gn_0_FEMALE	string	framexml
+VOICEMACRO_13_Gn_1	string	framexml
+VOICEMACRO_13_Gn_1_FEMALE	string	framexml
+VOICEMACRO_13_Gn_2	string	framexml
+VOICEMACRO_13_Gn_2_FEMALE	string	framexml
+VOICEMACRO_13_Gn_3	string	framexml
+VOICEMACRO_13_Gn_3_FEMALE	string	framexml
+VOICEMACRO_13_Hu_0	string	framexml
+VOICEMACRO_13_Hu_0_FEMALE	string	framexml
+VOICEMACRO_13_Hu_1	string	framexml
+VOICEMACRO_13_Hu_1_FEMALE	string	framexml
+VOICEMACRO_13_Hu_2	string	framexml
+VOICEMACRO_13_Hu_2_FEMALE	string	framexml
+VOICEMACRO_13_Ni_0	string	framexml
+VOICEMACRO_13_Ni_0_FEMALE	string	framexml
+VOICEMACRO_13_Ni_1	string	framexml
+VOICEMACRO_13_Ni_1_FEMALE	string	framexml
+VOICEMACRO_13_Ni_2	string	framexml
+VOICEMACRO_13_Ni_2_FEMALE	string	framexml
+VOICEMACRO_13_Or_0	string	framexml
+VOICEMACRO_13_Or_0_FEMALE	string	framexml
+VOICEMACRO_13_Or_1	string	framexml
+VOICEMACRO_13_Or_1_FEMALE	string	framexml
+VOICEMACRO_13_Or_2	string	framexml
+VOICEMACRO_13_Or_2_FEMALE	string	framexml
+VOICEMACRO_13_Sc_0	string	framexml
+VOICEMACRO_13_Sc_0_FEMALE	string	framexml
+VOICEMACRO_13_Sc_1	string	framexml
+VOICEMACRO_13_Sc_1_FEMALE	string	framexml
+VOICEMACRO_13_Sc_2	string	framexml
+VOICEMACRO_13_Sc_2_FEMALE	string	framexml
+VOICEMACRO_13_Ta_0	string	framexml
+VOICEMACRO_13_Ta_0_FEMALE	string	framexml
+VOICEMACRO_13_Ta_1	string	framexml
+VOICEMACRO_13_Ta_1_FEMALE	string	framexml
+VOICEMACRO_13_Ta_2	string	framexml
+VOICEMACRO_13_Ta_2_FEMALE	string	framexml
+VOICEMACRO_13_Tr_0	string	framexml
+VOICEMACRO_13_Tr_0_FEMALE	string	framexml
+VOICEMACRO_13_Tr_1	string	framexml
+VOICEMACRO_13_Tr_1_FEMALE	string	framexml
+VOICEMACRO_13_Tr_2	string	framexml
+VOICEMACRO_13_Tr_2_FEMALE	string	framexml
+VOICEMACRO_14_Dw_0	string	framexml
+VOICEMACRO_14_Dw_0_FEMALE	string	framexml
+VOICEMACRO_14_Dw_1	string	framexml
+VOICEMACRO_14_Dw_1_FEMALE	string	framexml
+VOICEMACRO_14_Dw_2	string	framexml
+VOICEMACRO_14_Dw_2_FEMALE	string	framexml
+VOICEMACRO_14_Dw_3	string	framexml
+VOICEMACRO_14_Gn_0	string	framexml
+VOICEMACRO_14_Gn_0_FEMALE	string	framexml
+VOICEMACRO_14_Gn_1	string	framexml
+VOICEMACRO_14_Gn_1_FEMALE	string	framexml
+VOICEMACRO_14_Gn_2	string	framexml
+VOICEMACRO_14_Gn_2_FEMALE	string	framexml
+VOICEMACRO_14_Hu_0	string	framexml
+VOICEMACRO_14_Hu_0_FEMALE	string	framexml
+VOICEMACRO_14_Hu_1	string	framexml
+VOICEMACRO_14_Hu_1_FEMALE	string	framexml
+VOICEMACRO_14_Hu_2	string	framexml
+VOICEMACRO_14_Hu_2_FEMALE	string	framexml
+VOICEMACRO_14_Ni_0	string	framexml
+VOICEMACRO_14_Ni_0_FEMALE	string	framexml
+VOICEMACRO_14_Ni_1	string	framexml
+VOICEMACRO_14_Ni_1_FEMALE	string	framexml
+VOICEMACRO_14_Ni_2	string	framexml
+VOICEMACRO_14_Ni_2_FEMALE	string	framexml
+VOICEMACRO_14_Or_0	string	framexml
+VOICEMACRO_14_Or_0_FEMALE	string	framexml
+VOICEMACRO_14_Or_1	string	framexml
+VOICEMACRO_14_Or_1_FEMALE	string	framexml
+VOICEMACRO_14_Or_2	string	framexml
+VOICEMACRO_14_Or_2_FEMALE	string	framexml
+VOICEMACRO_14_Or_3	string	framexml
+VOICEMACRO_14_Or_3_FEMALE	string	framexml
+VOICEMACRO_14_Sc_0	string	framexml
+VOICEMACRO_14_Sc_0_FEMALE	string	framexml
+VOICEMACRO_14_Sc_1	string	framexml
+VOICEMACRO_14_Sc_1_FEMALE	string	framexml
+VOICEMACRO_14_Sc_2	string	framexml
+VOICEMACRO_14_Sc_2_FEMALE	string	framexml
+VOICEMACRO_14_Ta_0	string	framexml
+VOICEMACRO_14_Ta_0_FEMALE	string	framexml
+VOICEMACRO_14_Ta_1	string	framexml
+VOICEMACRO_14_Ta_1_FEMALE	string	framexml
+VOICEMACRO_14_Ta_2	string	framexml
+VOICEMACRO_14_Ta_2_FEMALE	string	framexml
+VOICEMACRO_14_Tr_0	string	framexml
+VOICEMACRO_14_Tr_0_FEMALE	string	framexml
+VOICEMACRO_14_Tr_1	string	framexml
+VOICEMACRO_14_Tr_1_FEMALE	string	framexml
+VOICEMACRO_14_Tr_2	string	framexml
+VOICEMACRO_14_Tr_2_FEMALE	string	framexml
+VOICEMACRO_14_Tr_3	string	framexml
+VOICEMACRO_15_Dw_0	string	framexml
+VOICEMACRO_15_Dw_0_FEMALE	string	framexml
+VOICEMACRO_15_Dw_1	string	framexml
+VOICEMACRO_15_Dw_1_FEMALE	string	framexml
+VOICEMACRO_15_Dw_2	string	framexml
+VOICEMACRO_15_Dw_2_FEMALE	string	framexml
+VOICEMACRO_15_Dw_3	string	framexml
+VOICEMACRO_15_Gn_0	string	framexml
+VOICEMACRO_15_Gn_0_FEMALE	string	framexml
+VOICEMACRO_15_Gn_1	string	framexml
+VOICEMACRO_15_Gn_1_FEMALE	string	framexml
+VOICEMACRO_15_Gn_2	string	framexml
+VOICEMACRO_15_Gn_2_FEMALE	string	framexml
+VOICEMACRO_15_Hu_0	string	framexml
+VOICEMACRO_15_Hu_0_FEMALE	string	framexml
+VOICEMACRO_15_Hu_1	string	framexml
+VOICEMACRO_15_Hu_1_FEMALE	string	framexml
+VOICEMACRO_15_Hu_2	string	framexml
+VOICEMACRO_15_Hu_2_FEMALE	string	framexml
+VOICEMACRO_15_Hu_3	string	framexml
+VOICEMACRO_15_Ni_0	string	framexml
+VOICEMACRO_15_Ni_0_FEMALE	string	framexml
+VOICEMACRO_15_Ni_1	string	framexml
+VOICEMACRO_15_Ni_1_FEMALE	string	framexml
+VOICEMACRO_15_Ni_2	string	framexml
+VOICEMACRO_15_Ni_2_FEMALE	string	framexml
+VOICEMACRO_15_Or_0	string	framexml
+VOICEMACRO_15_Or_0_FEMALE	string	framexml
+VOICEMACRO_15_Or_1	string	framexml
+VOICEMACRO_15_Or_1_FEMALE	string	framexml
+VOICEMACRO_15_Or_2	string	framexml
+VOICEMACRO_15_Or_2_FEMALE	string	framexml
+VOICEMACRO_15_Sc_0	string	framexml
+VOICEMACRO_15_Sc_0_FEMALE	string	framexml
+VOICEMACRO_15_Sc_1	string	framexml
+VOICEMACRO_15_Sc_1_FEMALE	string	framexml
+VOICEMACRO_15_Sc_2	string	framexml
+VOICEMACRO_15_Sc_2_FEMALE	string	framexml
+VOICEMACRO_15_Ta_0	string	framexml
+VOICEMACRO_15_Ta_0_FEMALE	string	framexml
+VOICEMACRO_15_Ta_1	string	framexml
+VOICEMACRO_15_Ta_1_FEMALE	string	framexml
+VOICEMACRO_15_Ta_2	string	framexml
+VOICEMACRO_15_Ta_2_FEMALE	string	framexml
+VOICEMACRO_15_Tr_0	string	framexml
+VOICEMACRO_15_Tr_0_FEMALE	string	framexml
+VOICEMACRO_15_Tr_1	string	framexml
+VOICEMACRO_15_Tr_1_FEMALE	string	framexml
+VOICEMACRO_15_Tr_2	string	framexml
+VOICEMACRO_15_Tr_2_FEMALE	string	framexml
+VOICEMACRO_15_Tr_3	string	framexml
+VOICEMACRO_16_Dw_0	string	framexml
+VOICEMACRO_16_Dw_0_FEMALE	string	framexml
+VOICEMACRO_16_Dw_1	string	framexml
+VOICEMACRO_16_Dw_1_FEMALE	string	framexml
+VOICEMACRO_16_Dw_2	string	framexml
+VOICEMACRO_16_Dw_2_FEMALE	string	framexml
+VOICEMACRO_16_Dw_3	string	framexml
+VOICEMACRO_16_Dw_3_FEMALE	string	framexml
+VOICEMACRO_16_Gn_0	string	framexml
+VOICEMACRO_16_Gn_0_FEMALE	string	framexml
+VOICEMACRO_16_Gn_1	string	framexml
+VOICEMACRO_16_Gn_1_FEMALE	string	framexml
+VOICEMACRO_16_Gn_2	string	framexml
+VOICEMACRO_16_Gn_2_FEMALE	string	framexml
+VOICEMACRO_16_Hu_0	string	framexml
+VOICEMACRO_16_Hu_0_FEMALE	string	framexml
+VOICEMACRO_16_Hu_1	string	framexml
+VOICEMACRO_16_Hu_1_FEMALE	string	framexml
+VOICEMACRO_16_Hu_2	string	framexml
+VOICEMACRO_16_Hu_2_FEMALE	string	framexml
+VOICEMACRO_16_Ni_0	string	framexml
+VOICEMACRO_16_Ni_0_FEMALE	string	framexml
+VOICEMACRO_16_Ni_1	string	framexml
+VOICEMACRO_16_Ni_1_FEMALE	string	framexml
+VOICEMACRO_16_Ni_2	string	framexml
+VOICEMACRO_16_Ni_2_FEMALE	string	framexml
+VOICEMACRO_16_Or_0	string	framexml
+VOICEMACRO_16_Or_0_FEMALE	string	framexml
+VOICEMACRO_16_Or_1	string	framexml
+VOICEMACRO_16_Or_1_FEMALE	string	framexml
+VOICEMACRO_16_Or_2	string	framexml
+VOICEMACRO_16_Or_2_FEMALE	string	framexml
+VOICEMACRO_16_Sc_0	string	framexml
+VOICEMACRO_16_Sc_0_FEMALE	string	framexml
+VOICEMACRO_16_Sc_1	string	framexml
+VOICEMACRO_16_Sc_1_FEMALE	string	framexml
+VOICEMACRO_16_Sc_2	string	framexml
+VOICEMACRO_16_Sc_2_FEMALE	string	framexml
+VOICEMACRO_16_Ta_0	string	framexml
+VOICEMACRO_16_Ta_0_FEMALE	string	framexml
+VOICEMACRO_16_Ta_1	string	framexml
+VOICEMACRO_16_Ta_1_FEMALE	string	framexml
+VOICEMACRO_16_Ta_2	string	framexml
+VOICEMACRO_16_Ta_2_FEMALE	string	framexml
+VOICEMACRO_16_Ta_3	string	framexml
+VOICEMACRO_16_Tr_0	string	framexml
+VOICEMACRO_16_Tr_0_FEMALE	string	framexml
+VOICEMACRO_16_Tr_1	string	framexml
+VOICEMACRO_16_Tr_1_FEMALE	string	framexml
+VOICEMACRO_16_Tr_2	string	framexml
+VOICEMACRO_16_Tr_2_FEMALE	string	framexml
+VOICEMACRO_17_Dw_0	string	framexml
+VOICEMACRO_17_Dw_0_FEMALE	string	framexml
+VOICEMACRO_17_Dw_1	string	framexml
+VOICEMACRO_17_Dw_1_FEMALE	string	framexml
+VOICEMACRO_17_Dw_2	string	framexml
+VOICEMACRO_17_Dw_2_FEMALE	string	framexml
+VOICEMACRO_17_Gn_0	string	framexml
+VOICEMACRO_17_Gn_0_FEMALE	string	framexml
+VOICEMACRO_17_Gn_1	string	framexml
+VOICEMACRO_17_Gn_1_FEMALE	string	framexml
+VOICEMACRO_17_Gn_2	string	framexml
+VOICEMACRO_17_Gn_2_FEMALE	string	framexml
+VOICEMACRO_17_Hu_0	string	framexml
+VOICEMACRO_17_Hu_0_FEMALE	string	framexml
+VOICEMACRO_17_Hu_1	string	framexml
+VOICEMACRO_17_Hu_1_FEMALE	string	framexml
+VOICEMACRO_17_Hu_2	string	framexml
+VOICEMACRO_17_Hu_2_FEMALE	string	framexml
+VOICEMACRO_17_Ni_0	string	framexml
+VOICEMACRO_17_Ni_0_FEMALE	string	framexml
+VOICEMACRO_17_Ni_1	string	framexml
+VOICEMACRO_17_Ni_1_FEMALE	string	framexml
+VOICEMACRO_17_Ni_2	string	framexml
+VOICEMACRO_17_Ni_2_FEMALE	string	framexml
+VOICEMACRO_17_Or_0	string	framexml
+VOICEMACRO_17_Or_0_FEMALE	string	framexml
+VOICEMACRO_17_Or_1	string	framexml
+VOICEMACRO_17_Or_1_FEMALE	string	framexml
+VOICEMACRO_17_Or_2	string	framexml
+VOICEMACRO_17_Or_2_FEMALE	string	framexml
+VOICEMACRO_17_Sc_0	string	framexml
+VOICEMACRO_17_Sc_0_FEMALE	string	framexml
+VOICEMACRO_17_Sc_1	string	framexml
+VOICEMACRO_17_Sc_1_FEMALE	string	framexml
+VOICEMACRO_17_Sc_2_FEMALE	string	framexml
+VOICEMACRO_17_Ta_0	string	framexml
+VOICEMACRO_17_Ta_0_FEMALE	string	framexml
+VOICEMACRO_17_Ta_1	string	framexml
+VOICEMACRO_17_Ta_1_FEMALE	string	framexml
+VOICEMACRO_17_Ta_2	string	framexml
+VOICEMACRO_17_Ta_2_FEMALE	string	framexml
+VOICEMACRO_17_Tr_0	string	framexml
+VOICEMACRO_17_Tr_0_FEMALE	string	framexml
+VOICEMACRO_17_Tr_1	string	framexml
+VOICEMACRO_17_Tr_1_FEMALE	string	framexml
+VOICEMACRO_17_Tr_2	string	framexml
+VOICEMACRO_17_Tr_2_FEMALE	string	framexml
+VOICEMACRO_18_Dw_0	string	framexml
+VOICEMACRO_18_Dw_0_FEMALE	string	framexml
+VOICEMACRO_18_Dw_1	string	framexml
+VOICEMACRO_18_Dw_1_FEMALE	string	framexml
+VOICEMACRO_18_Dw_2	string	framexml
+VOICEMACRO_18_Dw_2_FEMALE	string	framexml
+VOICEMACRO_18_Dw_3	string	framexml
+VOICEMACRO_18_Dw_3_FEMALE	string	framexml
+VOICEMACRO_18_Dw_4	string	framexml
+VOICEMACRO_18_Gn_0	string	framexml
+VOICEMACRO_18_Gn_0_FEMALE	string	framexml
+VOICEMACRO_18_Gn_1	string	framexml
+VOICEMACRO_18_Gn_1_FEMALE	string	framexml
+VOICEMACRO_18_Gn_2	string	framexml
+VOICEMACRO_18_Gn_2_FEMALE	string	framexml
+VOICEMACRO_18_Gn_3_FEMALE	string	framexml
+VOICEMACRO_18_Hu_0	string	framexml
+VOICEMACRO_18_Hu_0_FEMALE	string	framexml
+VOICEMACRO_18_Hu_1	string	framexml
+VOICEMACRO_18_Hu_1_FEMALE	string	framexml
+VOICEMACRO_18_Hu_2	string	framexml
+VOICEMACRO_18_Hu_2_FEMALE	string	framexml
+VOICEMACRO_18_Ni_0	string	framexml
+VOICEMACRO_18_Ni_0_FEMALE	string	framexml
+VOICEMACRO_18_Ni_1	string	framexml
+VOICEMACRO_18_Ni_1_FEMALE	string	framexml
+VOICEMACRO_18_Ni_2	string	framexml
+VOICEMACRO_18_Ni_2_FEMALE	string	framexml
+VOICEMACRO_18_Or_0	string	framexml
+VOICEMACRO_18_Or_0_FEMALE	string	framexml
+VOICEMACRO_18_Or_1	string	framexml
+VOICEMACRO_18_Or_1_FEMALE	string	framexml
+VOICEMACRO_18_Or_2	string	framexml
+VOICEMACRO_18_Or_2_FEMALE	string	framexml
+VOICEMACRO_18_Sc_0	string	framexml
+VOICEMACRO_18_Sc_0_FEMALE	string	framexml
+VOICEMACRO_18_Sc_1	string	framexml
+VOICEMACRO_18_Sc_1_FEMALE	string	framexml
+VOICEMACRO_18_Sc_2	string	framexml
+VOICEMACRO_18_Sc_2_FEMALE	string	framexml
+VOICEMACRO_18_Sc_3_FEMALE	string	framexml
+VOICEMACRO_18_Ta_0	string	framexml
+VOICEMACRO_18_Ta_0_FEMALE	string	framexml
+VOICEMACRO_18_Ta_1	string	framexml
+VOICEMACRO_18_Ta_1_FEMALE	string	framexml
+VOICEMACRO_18_Ta_2	string	framexml
+VOICEMACRO_18_Ta_2_FEMALE	string	framexml
+VOICEMACRO_18_Tr_0	string	framexml
+VOICEMACRO_18_Tr_0_FEMALE	string	framexml
+VOICEMACRO_18_Tr_1	string	framexml
+VOICEMACRO_18_Tr_1_FEMALE	string	framexml
+VOICEMACRO_18_Tr_2	string	framexml
+VOICEMACRO_18_Tr_2_FEMALE	string	framexml
+VOICEMACRO_19_Dw_0	string	framexml
+VOICEMACRO_19_Dw_0_FEMALE	string	framexml
+VOICEMACRO_19_Dw_1	string	framexml
+VOICEMACRO_19_Dw_1_FEMALE	string	framexml
+VOICEMACRO_19_Dw_2	string	framexml
+VOICEMACRO_19_Dw_2_FEMALE	string	framexml
+VOICEMACRO_19_Dw_3	string	framexml
+VOICEMACRO_19_Dw_3_FEMALE	string	framexml
+VOICEMACRO_19_Dw_4	string	framexml
+VOICEMACRO_19_Dw_4_FEMALE	string	framexml
+VOICEMACRO_19_Dw_5	string	framexml
+VOICEMACRO_19_Gn_0	string	framexml
+VOICEMACRO_19_Gn_0_FEMALE	string	framexml
+VOICEMACRO_19_Gn_1	string	framexml
+VOICEMACRO_19_Gn_1_FEMALE	string	framexml
+VOICEMACRO_19_Gn_2	string	framexml
+VOICEMACRO_19_Gn_2_FEMALE	string	framexml
+VOICEMACRO_19_Gn_3	string	framexml
+VOICEMACRO_19_Gn_3_FEMALE	string	framexml
+VOICEMACRO_19_Gn_4_FEMALE	string	framexml
+VOICEMACRO_19_Hu_0	string	framexml
+VOICEMACRO_19_Hu_0_FEMALE	string	framexml
+VOICEMACRO_19_Hu_1	string	framexml
+VOICEMACRO_19_Hu_1_FEMALE	string	framexml
+VOICEMACRO_19_Hu_2	string	framexml
+VOICEMACRO_19_Hu_2_FEMALE	string	framexml
+VOICEMACRO_19_Hu_3	string	framexml
+VOICEMACRO_19_Hu_4	string	framexml
+VOICEMACRO_19_Hu_5	string	framexml
+VOICEMACRO_19_Ni_0	string	framexml
+VOICEMACRO_19_Ni_0_FEMALE	string	framexml
+VOICEMACRO_19_Ni_1	string	framexml
+VOICEMACRO_19_Ni_1_FEMALE	string	framexml
+VOICEMACRO_19_Ni_2	string	framexml
+VOICEMACRO_19_Ni_2_FEMALE	string	framexml
+VOICEMACRO_19_Ni_3	string	framexml
+VOICEMACRO_19_Ni_3_FEMALE	string	framexml
+VOICEMACRO_19_Ni_4	string	framexml
+VOICEMACRO_19_Or_0	string	framexml
+VOICEMACRO_19_Or_0_FEMALE	string	framexml
+VOICEMACRO_19_Or_1	string	framexml
+VOICEMACRO_19_Or_1_FEMALE	string	framexml
+VOICEMACRO_19_Or_2	string	framexml
+VOICEMACRO_19_Or_2_FEMALE	string	framexml
+VOICEMACRO_19_Or_3	string	framexml
+VOICEMACRO_19_Or_3_FEMALE	string	framexml
+VOICEMACRO_19_Or_4	string	framexml
+VOICEMACRO_19_Or_4_FEMALE	string	framexml
+VOICEMACRO_19_Or_5	string	framexml
+VOICEMACRO_19_Or_5_FEMALE	string	framexml
+VOICEMACRO_19_Sc_0	string	framexml
+VOICEMACRO_19_Sc_0_FEMALE	string	framexml
+VOICEMACRO_19_Sc_1	string	framexml
+VOICEMACRO_19_Sc_1_FEMALE	string	framexml
+VOICEMACRO_19_Sc_2	string	framexml
+VOICEMACRO_19_Sc_2_FEMALE	string	framexml
+VOICEMACRO_19_Sc_3	string	framexml
+VOICEMACRO_19_Sc_3_FEMALE	string	framexml
+VOICEMACRO_19_Sc_4	string	framexml
+VOICEMACRO_19_Sc_4_FEMALE	string	framexml
+VOICEMACRO_19_Sc_5	string	framexml
+VOICEMACRO_19_Sc_5_FEMALE	string	framexml
+VOICEMACRO_19_Ta_0	string	framexml
+VOICEMACRO_19_Ta_0_FEMALE	string	framexml
+VOICEMACRO_19_Ta_1	string	framexml
+VOICEMACRO_19_Ta_1_FEMALE	string	framexml
+VOICEMACRO_19_Ta_2	string	framexml
+VOICEMACRO_19_Ta_2_FEMALE	string	framexml
+VOICEMACRO_19_Ta_3	string	framexml
+VOICEMACRO_19_Ta_3_FEMALE	string	framexml
+VOICEMACRO_19_Ta_4	string	framexml
+VOICEMACRO_19_Ta_4_FEMALE	string	framexml
+VOICEMACRO_19_Ta_5	string	framexml
+VOICEMACRO_19_Tr_0	string	framexml
+VOICEMACRO_19_Tr_0_FEMALE	string	framexml
+VOICEMACRO_19_Tr_1	string	framexml
+VOICEMACRO_19_Tr_1_FEMALE	string	framexml
+VOICEMACRO_19_Tr_2	string	framexml
+VOICEMACRO_19_Tr_2_FEMALE	string	framexml
+VOICEMACRO_19_Tr_3	string	framexml
+VOICEMACRO_19_Tr_3_FEMALE	string	framexml
+VOICEMACRO_19_Tr_4_FEMALE	string	framexml
+VOICEMACRO_1_Dw_0	string	framexml
+VOICEMACRO_1_Dw_0_FEMALE	string	framexml
+VOICEMACRO_1_Dw_1	string	framexml
+VOICEMACRO_1_Dw_1_FEMALE	string	framexml
+VOICEMACRO_1_Gn_0	string	framexml
+VOICEMACRO_1_Gn_0_FEMALE	string	framexml
+VOICEMACRO_1_Hu_0	string	framexml
+VOICEMACRO_1_Hu_0_FEMALE	string	framexml
+VOICEMACRO_1_Hu_1	string	framexml
+VOICEMACRO_1_Hu_1_FEMALE	string	framexml
+VOICEMACRO_1_Ni_0	string	framexml
+VOICEMACRO_1_Ni_0_FEMALE	string	framexml
+VOICEMACRO_1_Ni_1	string	framexml
+VOICEMACRO_1_Ni_1_FEMALE	string	framexml
+VOICEMACRO_1_Or_0	string	framexml
+VOICEMACRO_1_Or_0_FEMALE	string	framexml
+VOICEMACRO_1_Or_1	string	framexml
+VOICEMACRO_1_Or_1_FEMALE	string	framexml
+VOICEMACRO_1_Or_2	string	framexml
+VOICEMACRO_1_Sc_0	string	framexml
+VOICEMACRO_1_Sc_0_FEMALE	string	framexml
+VOICEMACRO_1_Sc_1	string	framexml
+VOICEMACRO_1_Sc_1_FEMALE	string	framexml
+VOICEMACRO_1_Ta_0	string	framexml
+VOICEMACRO_1_Ta_0_FEMALE	string	framexml
+VOICEMACRO_1_Ta_1	string	framexml
+VOICEMACRO_1_Ta_1_FEMALE	string	framexml
+VOICEMACRO_1_Ta_2_FEMALE	string	framexml
+VOICEMACRO_1_Tr_0	string	framexml
+VOICEMACRO_1_Tr_0_FEMALE	string	framexml
+VOICEMACRO_1_Tr_1	string	framexml
+VOICEMACRO_1_Tr_1_FEMALE	string	framexml
+VOICEMACRO_20_Dw_0	string	framexml
+VOICEMACRO_20_Dw_0_FEMALE	string	framexml
+VOICEMACRO_20_Dw_1	string	framexml
+VOICEMACRO_20_Dw_1_FEMALE	string	framexml
+VOICEMACRO_20_Dw_2	string	framexml
+VOICEMACRO_20_Dw_2_FEMALE	string	framexml
+VOICEMACRO_20_Dw_3	string	framexml
+VOICEMACRO_20_Dw_3_FEMALE	string	framexml
+VOICEMACRO_20_Dw_4	string	framexml
+VOICEMACRO_20_Dw_4_FEMALE	string	framexml
+VOICEMACRO_20_Dw_5	string	framexml
+VOICEMACRO_20_Dw_5_FEMALE	string	framexml
+VOICEMACRO_20_Dw_6	string	framexml
+VOICEMACRO_20_Gn_0	string	framexml
+VOICEMACRO_20_Gn_0_FEMALE	string	framexml
+VOICEMACRO_20_Gn_1	string	framexml
+VOICEMACRO_20_Gn_1_FEMALE	string	framexml
+VOICEMACRO_20_Gn_2	string	framexml
+VOICEMACRO_20_Gn_2_FEMALE	string	framexml
+VOICEMACRO_20_Gn_3	string	framexml
+VOICEMACRO_20_Gn_3_FEMALE	string	framexml
+VOICEMACRO_20_Gn_4	string	framexml
+VOICEMACRO_20_Gn_5	string	framexml
+VOICEMACRO_20_Hu_0	string	framexml
+VOICEMACRO_20_Hu_0_FEMALE	string	framexml
+VOICEMACRO_20_Hu_1	string	framexml
+VOICEMACRO_20_Hu_1_FEMALE	string	framexml
+VOICEMACRO_20_Hu_2	string	framexml
+VOICEMACRO_20_Hu_2_FEMALE	string	framexml
+VOICEMACRO_20_Hu_3	string	framexml
+VOICEMACRO_20_Hu_3_FEMALE	string	framexml
+VOICEMACRO_20_Hu_4	string	framexml
+VOICEMACRO_20_Hu_4_FEMALE	string	framexml
+VOICEMACRO_20_Hu_5	string	framexml
+VOICEMACRO_20_Hu_5_FEMALE	string	framexml
+VOICEMACRO_20_Hu_6_FEMALE	string	framexml
+VOICEMACRO_20_Ni_0	string	framexml
+VOICEMACRO_20_Ni_0_FEMALE	string	framexml
+VOICEMACRO_20_Ni_1	string	framexml
+VOICEMACRO_20_Ni_1_FEMALE	string	framexml
+VOICEMACRO_20_Ni_2	string	framexml
+VOICEMACRO_20_Ni_2_FEMALE	string	framexml
+VOICEMACRO_20_Ni_3	string	framexml
+VOICEMACRO_20_Ni_3_FEMALE	string	framexml
+VOICEMACRO_20_Ni_4	string	framexml
+VOICEMACRO_20_Ni_4_FEMALE	string	framexml
+VOICEMACRO_20_Ni_5	string	framexml
+VOICEMACRO_20_Ni_6	string	framexml
+VOICEMACRO_20_Ni_7	string	framexml
+VOICEMACRO_20_Or_0	string	framexml
+VOICEMACRO_20_Or_0_FEMALE	string	framexml
+VOICEMACRO_20_Or_1	string	framexml
+VOICEMACRO_20_Or_1_FEMALE	string	framexml
+VOICEMACRO_20_Or_2	string	framexml
+VOICEMACRO_20_Or_2_FEMALE	string	framexml
+VOICEMACRO_20_Or_3	string	framexml
+VOICEMACRO_20_Or_3_FEMALE	string	framexml
+VOICEMACRO_20_Or_4	string	framexml
+VOICEMACRO_20_Or_4_FEMALE	string	framexml
+VOICEMACRO_20_Or_5	string	framexml
+VOICEMACRO_20_Or_5_FEMALE	string	framexml
+VOICEMACRO_20_Sc_0	string	framexml
+VOICEMACRO_20_Sc_0_FEMALE	string	framexml
+VOICEMACRO_20_Sc_1	string	framexml
+VOICEMACRO_20_Sc_1_FEMALE	string	framexml
+VOICEMACRO_20_Sc_2	string	framexml
+VOICEMACRO_20_Sc_2_FEMALE	string	framexml
+VOICEMACRO_20_Sc_3	string	framexml
+VOICEMACRO_20_Sc_3_FEMALE	string	framexml
+VOICEMACRO_20_Sc_4	string	framexml
+VOICEMACRO_20_Sc_4_FEMALE	string	framexml
+VOICEMACRO_20_Sc_5_FEMALE	string	framexml
+VOICEMACRO_20_Sc_6_FEMALE	string	framexml
+VOICEMACRO_20_Sc_7_FEMALE	string	framexml
+VOICEMACRO_20_Ta_0	string	framexml
+VOICEMACRO_20_Ta_0_FEMALE	string	framexml
+VOICEMACRO_20_Ta_1	string	framexml
+VOICEMACRO_20_Ta_1_FEMALE	string	framexml
+VOICEMACRO_20_Ta_2	string	framexml
+VOICEMACRO_20_Ta_2_FEMALE	string	framexml
+VOICEMACRO_20_Ta_3	string	framexml
+VOICEMACRO_20_Ta_3_FEMALE	string	framexml
+VOICEMACRO_20_Ta_4	string	framexml
+VOICEMACRO_20_Tr_0	string	framexml
+VOICEMACRO_20_Tr_0_FEMALE	string	framexml
+VOICEMACRO_20_Tr_1	string	framexml
+VOICEMACRO_20_Tr_1_FEMALE	string	framexml
+VOICEMACRO_20_Tr_2	string	framexml
+VOICEMACRO_20_Tr_2_FEMALE	string	framexml
+VOICEMACRO_20_Tr_3	string	framexml
+VOICEMACRO_20_Tr_3_FEMALE	string	framexml
+VOICEMACRO_20_Tr_4	string	framexml
+VOICEMACRO_20_Tr_4_FEMALE	string	framexml
+VOICEMACRO_20_Tr_5	string	framexml
+VOICEMACRO_2_Dw_0	string	framexml
+VOICEMACRO_2_Dw_0_FEMALE	string	framexml
+VOICEMACRO_2_Dw_1	string	framexml
+VOICEMACRO_2_Dw_1_FEMALE	string	framexml
+VOICEMACRO_2_Gn_0	string	framexml
+VOICEMACRO_2_Gn_0_FEMALE	string	framexml
+VOICEMACRO_2_Gn_1	string	framexml
+VOICEMACRO_2_Gn_1_FEMALE	string	framexml
+VOICEMACRO_2_Gn_2	string	framexml
+VOICEMACRO_2_Hu_0	string	framexml
+VOICEMACRO_2_Hu_0_FEMALE	string	framexml
+VOICEMACRO_2_Hu_1	string	framexml
+VOICEMACRO_2_Hu_1_FEMALE	string	framexml
+VOICEMACRO_2_Ni_0	string	framexml
+VOICEMACRO_2_Ni_0_FEMALE	string	framexml
+VOICEMACRO_2_Ni_1	string	framexml
+VOICEMACRO_2_Ni_1_FEMALE	string	framexml
+VOICEMACRO_2_Ni_2_FEMALE	string	framexml
+VOICEMACRO_2_Or_0	string	framexml
+VOICEMACRO_2_Or_0_FEMALE	string	framexml
+VOICEMACRO_2_Or_1	string	framexml
+VOICEMACRO_2_Or_1_FEMALE	string	framexml
+VOICEMACRO_2_Or_2	string	framexml
+VOICEMACRO_2_Or_2_FEMALE	string	framexml
+VOICEMACRO_2_Sc_0	string	framexml
+VOICEMACRO_2_Sc_0_FEMALE	string	framexml
+VOICEMACRO_2_Sc_1	string	framexml
+VOICEMACRO_2_Sc_1_FEMALE	string	framexml
+VOICEMACRO_2_Ta_0	string	framexml
+VOICEMACRO_2_Ta_0_FEMALE	string	framexml
+VOICEMACRO_2_Ta_1	string	framexml
+VOICEMACRO_2_Ta_1_FEMALE	string	framexml
+VOICEMACRO_2_Ta_2	string	framexml
+VOICEMACRO_2_Tr_0	string	framexml
+VOICEMACRO_2_Tr_0_FEMALE	string	framexml
+VOICEMACRO_2_Tr_1	string	framexml
+VOICEMACRO_2_Tr_1_FEMALE	string	framexml
+VOICEMACRO_3_Dw_0	string	framexml
+VOICEMACRO_3_Dw_0_FEMALE	string	framexml
+VOICEMACRO_3_Dw_1	string	framexml
+VOICEMACRO_3_Dw_1_FEMALE	string	framexml
+VOICEMACRO_3_Dw_2	string	framexml
+VOICEMACRO_3_Gn_0	string	framexml
+VOICEMACRO_3_Gn_0_FEMALE	string	framexml
+VOICEMACRO_3_Gn_1	string	framexml
+VOICEMACRO_3_Gn_1_FEMALE	string	framexml
+VOICEMACRO_3_Gn_2	string	framexml
+VOICEMACRO_3_Gn_2_FEMALE	string	framexml
+VOICEMACRO_3_Hu_0	string	framexml
+VOICEMACRO_3_Hu_0_FEMALE	string	framexml
+VOICEMACRO_3_Hu_1	string	framexml
+VOICEMACRO_3_Hu_1_FEMALE	string	framexml
+VOICEMACRO_3_Ni_0	string	framexml
+VOICEMACRO_3_Ni_0_FEMALE	string	framexml
+VOICEMACRO_3_Ni_1	string	framexml
+VOICEMACRO_3_Ni_1_FEMALE	string	framexml
+VOICEMACRO_3_Or_0	string	framexml
+VOICEMACRO_3_Or_0_FEMALE	string	framexml
+VOICEMACRO_3_Or_1	string	framexml
+VOICEMACRO_3_Or_1_FEMALE	string	framexml
+VOICEMACRO_3_Sc_0	string	framexml
+VOICEMACRO_3_Sc_0_FEMALE	string	framexml
+VOICEMACRO_3_Sc_1	string	framexml
+VOICEMACRO_3_Sc_1_FEMALE	string	framexml
+VOICEMACRO_3_Ta_0	string	framexml
+VOICEMACRO_3_Ta_0_FEMALE	string	framexml
+VOICEMACRO_3_Ta_1	string	framexml
+VOICEMACRO_3_Ta_1_FEMALE	string	framexml
+VOICEMACRO_3_Tr_0	string	framexml
+VOICEMACRO_3_Tr_0_FEMALE	string	framexml
+VOICEMACRO_3_Tr_1	string	framexml
+VOICEMACRO_3_Tr_1_FEMALE	string	framexml
+VOICEMACRO_4_Dw_0	string	framexml
+VOICEMACRO_4_Dw_0_FEMALE	string	framexml
+VOICEMACRO_4_Dw_1	string	framexml
+VOICEMACRO_4_Dw_1_FEMALE	string	framexml
+VOICEMACRO_4_Dw_2	string	framexml
+VOICEMACRO_4_Gn_0	string	framexml
+VOICEMACRO_4_Gn_0_FEMALE	string	framexml
+VOICEMACRO_4_Gn_1	string	framexml
+VOICEMACRO_4_Gn_1_FEMALE	string	framexml
+VOICEMACRO_4_Hu_0	string	framexml
+VOICEMACRO_4_Hu_0_FEMALE	string	framexml
+VOICEMACRO_4_Hu_1	string	framexml
+VOICEMACRO_4_Hu_1_FEMALE	string	framexml
+VOICEMACRO_4_Ni_0	string	framexml
+VOICEMACRO_4_Ni_0_FEMALE	string	framexml
+VOICEMACRO_4_Ni_1	string	framexml
+VOICEMACRO_4_Ni_1_FEMALE	string	framexml
+VOICEMACRO_4_Ni_2_FEMALE	string	framexml
+VOICEMACRO_4_Or_0	string	framexml
+VOICEMACRO_4_Or_0_FEMALE	string	framexml
+VOICEMACRO_4_Or_1	string	framexml
+VOICEMACRO_4_Or_1_FEMALE	string	framexml
+VOICEMACRO_4_Or_2	string	framexml
+VOICEMACRO_4_Or_2_FEMALE	string	framexml
+VOICEMACRO_4_Sc_0	string	framexml
+VOICEMACRO_4_Sc_0_FEMALE	string	framexml
+VOICEMACRO_4_Sc_1	string	framexml
+VOICEMACRO_4_Sc_1_FEMALE	string	framexml
+VOICEMACRO_4_Ta_0	string	framexml
+VOICEMACRO_4_Ta_0_FEMALE	string	framexml
+VOICEMACRO_4_Ta_1	string	framexml
+VOICEMACRO_4_Ta_1_FEMALE	string	framexml
+VOICEMACRO_4_Tr_0	string	framexml
+VOICEMACRO_4_Tr_0_FEMALE	string	framexml
+VOICEMACRO_4_Tr_1	string	framexml
+VOICEMACRO_4_Tr_1_FEMALE	string	framexml
+VOICEMACRO_5_Dw_0	string	framexml
+VOICEMACRO_5_Dw_0_FEMALE	string	framexml
+VOICEMACRO_5_Dw_1	string	framexml
+VOICEMACRO_5_Dw_1_FEMALE	string	framexml
+VOICEMACRO_5_Gn_0	string	framexml
+VOICEMACRO_5_Gn_0_FEMALE	string	framexml
+VOICEMACRO_5_Gn_1	string	framexml
+VOICEMACRO_5_Gn_1_FEMALE	string	framexml
+VOICEMACRO_5_Hu_0	string	framexml
+VOICEMACRO_5_Hu_0_FEMALE	string	framexml
+VOICEMACRO_5_Hu_1	string	framexml
+VOICEMACRO_5_Hu_1_FEMALE	string	framexml
+VOICEMACRO_5_Ni_0	string	framexml
+VOICEMACRO_5_Ni_0_FEMALE	string	framexml
+VOICEMACRO_5_Ni_1	string	framexml
+VOICEMACRO_5_Ni_1_FEMALE	string	framexml
+VOICEMACRO_5_Or_0	string	framexml
+VOICEMACRO_5_Or_0_FEMALE	string	framexml
+VOICEMACRO_5_Or_1	string	framexml
+VOICEMACRO_5_Or_1_FEMALE	string	framexml
+VOICEMACRO_5_Sc_0	string	framexml
+VOICEMACRO_5_Sc_0_FEMALE	string	framexml
+VOICEMACRO_5_Sc_1	string	framexml
+VOICEMACRO_5_Sc_1_FEMALE	string	framexml
+VOICEMACRO_5_Ta_0	string	framexml
+VOICEMACRO_5_Ta_0_FEMALE	string	framexml
+VOICEMACRO_5_Ta_1	string	framexml
+VOICEMACRO_5_Ta_1_FEMALE	string	framexml
+VOICEMACRO_5_Tr_0	string	framexml
+VOICEMACRO_5_Tr_0_FEMALE	string	framexml
+VOICEMACRO_5_Tr_1	string	framexml
+VOICEMACRO_5_Tr_1_FEMALE	string	framexml
+VOICEMACRO_6_Dw_0	string	framexml
+VOICEMACRO_6_Dw_0_FEMALE	string	framexml
+VOICEMACRO_6_Dw_1	string	framexml
+VOICEMACRO_6_Dw_1_FEMALE	string	framexml
+VOICEMACRO_6_Dw_2	string	framexml
+VOICEMACRO_6_Gn_0	string	framexml
+VOICEMACRO_6_Gn_0_FEMALE	string	framexml
+VOICEMACRO_6_Gn_1	string	framexml
+VOICEMACRO_6_Hu_0	string	framexml
+VOICEMACRO_6_Hu_0_FEMALE	string	framexml
+VOICEMACRO_6_Hu_1	string	framexml
+VOICEMACRO_6_Hu_1_FEMALE	string	framexml
+VOICEMACRO_6_Ni_0	string	framexml
+VOICEMACRO_6_Ni_0_FEMALE	string	framexml
+VOICEMACRO_6_Ni_1	string	framexml
+VOICEMACRO_6_Ni_1_FEMALE	string	framexml
+VOICEMACRO_6_Or_0	string	framexml
+VOICEMACRO_6_Or_0_FEMALE	string	framexml
+VOICEMACRO_6_Or_1	string	framexml
+VOICEMACRO_6_Or_1_FEMALE	string	framexml
+VOICEMACRO_6_Sc_0	string	framexml
+VOICEMACRO_6_Sc_0_FEMALE	string	framexml
+VOICEMACRO_6_Sc_1	string	framexml
+VOICEMACRO_6_Sc_1_FEMALE	string	framexml
+VOICEMACRO_6_Ta_0	string	framexml
+VOICEMACRO_6_Ta_0_FEMALE	string	framexml
+VOICEMACRO_6_Ta_1	string	framexml
+VOICEMACRO_6_Ta_1_FEMALE	string	framexml
+VOICEMACRO_6_Tr_0	string	framexml
+VOICEMACRO_6_Tr_0_FEMALE	string	framexml
+VOICEMACRO_6_Tr_1	string	framexml
+VOICEMACRO_6_Tr_1_FEMALE	string	framexml
+VOICEMACRO_7_Dw_0	string	framexml
+VOICEMACRO_7_Dw_0_FEMALE	string	framexml
+VOICEMACRO_7_Dw_1	string	framexml
+VOICEMACRO_7_Dw_1_FEMALE	string	framexml
+VOICEMACRO_7_Dw_2	string	framexml
+VOICEMACRO_7_Gn_0	string	framexml
+VOICEMACRO_7_Gn_0_FEMALE	string	framexml
+VOICEMACRO_7_Gn_1	string	framexml
+VOICEMACRO_7_Gn_1_FEMALE	string	framexml
+VOICEMACRO_7_Hu_0	string	framexml
+VOICEMACRO_7_Hu_0_FEMALE	string	framexml
+VOICEMACRO_7_Hu_1	string	framexml
+VOICEMACRO_7_Hu_1_FEMALE	string	framexml
+VOICEMACRO_7_Hu_2	string	framexml
+VOICEMACRO_7_Hu_2_FEMALE	string	framexml
+VOICEMACRO_7_Ni_0	string	framexml
+VOICEMACRO_7_Ni_0_FEMALE	string	framexml
+VOICEMACRO_7_Ni_1	string	framexml
+VOICEMACRO_7_Ni_1_FEMALE	string	framexml
+VOICEMACRO_7_Or_0	string	framexml
+VOICEMACRO_7_Or_0_FEMALE	string	framexml
+VOICEMACRO_7_Or_1	string	framexml
+VOICEMACRO_7_Or_1_FEMALE	string	framexml
+VOICEMACRO_7_Sc_0	string	framexml
+VOICEMACRO_7_Sc_0_FEMALE	string	framexml
+VOICEMACRO_7_Sc_1	string	framexml
+VOICEMACRO_7_Sc_1_FEMALE	string	framexml
+VOICEMACRO_7_Ta_0	string	framexml
+VOICEMACRO_7_Ta_0_FEMALE	string	framexml
+VOICEMACRO_7_Ta_1	string	framexml
+VOICEMACRO_7_Ta_1_FEMALE	string	framexml
+VOICEMACRO_7_Ta_2	string	framexml
+VOICEMACRO_7_Tr_0	string	framexml
+VOICEMACRO_7_Tr_0_FEMALE	string	framexml
+VOICEMACRO_7_Tr_1	string	framexml
+VOICEMACRO_7_Tr_1_FEMALE	string	framexml
+VOICEMACRO_7_Tr_2	string	framexml
+VOICEMACRO_7_Tr_2_FEMALE	string	framexml
+VOICEMACRO_8_Dw_0	string	framexml
+VOICEMACRO_8_Dw_0_FEMALE	string	framexml
+VOICEMACRO_8_Dw_1	string	framexml
+VOICEMACRO_8_Dw_1_FEMALE	string	framexml
+VOICEMACRO_8_Dw_2	string	framexml
+VOICEMACRO_8_Dw_2_FEMALE	string	framexml
+VOICEMACRO_8_Gn_0	string	framexml
+VOICEMACRO_8_Gn_0_FEMALE	string	framexml
+VOICEMACRO_8_Gn_1	string	framexml
+VOICEMACRO_8_Gn_1_FEMALE	string	framexml
+VOICEMACRO_8_Hu_0	string	framexml
+VOICEMACRO_8_Hu_0_FEMALE	string	framexml
+VOICEMACRO_8_Hu_1	string	framexml
+VOICEMACRO_8_Hu_1_FEMALE	string	framexml
+VOICEMACRO_8_Ni_0	string	framexml
+VOICEMACRO_8_Ni_0_FEMALE	string	framexml
+VOICEMACRO_8_Ni_1	string	framexml
+VOICEMACRO_8_Ni_1_FEMALE	string	framexml
+VOICEMACRO_8_Or_0	string	framexml
+VOICEMACRO_8_Or_0_FEMALE	string	framexml
+VOICEMACRO_8_Or_1	string	framexml
+VOICEMACRO_8_Or_1_FEMALE	string	framexml
+VOICEMACRO_8_Sc_0	string	framexml
+VOICEMACRO_8_Sc_0_FEMALE	string	framexml
+VOICEMACRO_8_Sc_1	string	framexml
+VOICEMACRO_8_Sc_1_FEMALE	string	framexml
+VOICEMACRO_8_Ta_0	string	framexml
+VOICEMACRO_8_Ta_0_FEMALE	string	framexml
+VOICEMACRO_8_Ta_1	string	framexml
+VOICEMACRO_8_Ta_1_FEMALE	string	framexml
+VOICEMACRO_8_Tr_0	string	framexml
+VOICEMACRO_8_Tr_0_FEMALE	string	framexml
+VOICEMACRO_8_Tr_1	string	framexml
+VOICEMACRO_8_Tr_1_FEMALE	string	framexml
+VOICEMACRO_8_Tr_2	string	framexml
+VOICEMACRO_8_Tr_2_FEMALE	string	framexml
+VOICEMACRO_LABEL	string	framexml
+VOICEMACRO_LABEL_AID1	string	framexml
+VOICEMACRO_LABEL_ATTACKMYTARGET1	string	framexml
+VOICEMACRO_LABEL_ATTACKMYTARGET2	string	framexml
+VOICEMACRO_LABEL_CHARGE1	string	framexml
+VOICEMACRO_LABEL_CHEER1	string	framexml
+VOICEMACRO_LABEL_CONGRATULATIONS1	string	framexml
+VOICEMACRO_LABEL_CONGRATULATIONS2	string	framexml
+VOICEMACRO_LABEL_CONGRATULATIONS3	string	framexml
+VOICEMACRO_LABEL_FLEE1	string	framexml
+VOICEMACRO_LABEL_FLEE2	string	framexml
+VOICEMACRO_LABEL_FLIRT1	string	framexml
+VOICEMACRO_LABEL_FOLLOW1	string	framexml
+VOICEMACRO_LABEL_FOLLOWME1	string	framexml
+VOICEMACRO_LABEL_FOLLOWME2	string	framexml
+VOICEMACRO_LABEL_FOLLOWME3	string	framexml
+VOICEMACRO_LABEL_GOODBYE1	string	framexml
+VOICEMACRO_LABEL_GOODBYE2	string	framexml
+VOICEMACRO_LABEL_HEALME1	string	framexml
+VOICEMACRO_LABEL_HEALME2	string	framexml
+VOICEMACRO_LABEL_HELLO1	string	framexml
+VOICEMACRO_LABEL_HELP1	string	framexml
+VOICEMACRO_LABEL_HELPME1	string	framexml
+VOICEMACRO_LABEL_HELPME2	string	framexml
+VOICEMACRO_LABEL_INCOMING1	string	framexml
+VOICEMACRO_LABEL_INCOMING2	string	framexml
+VOICEMACRO_LABEL_JOKE1	string	framexml
+VOICEMACRO_LABEL_NO1	string	framexml
+VOICEMACRO_LABEL_OPENFIRE1	string	framexml
+VOICEMACRO_LABEL_OPENFIRE2	string	framexml
+VOICEMACRO_LABEL_OUTOFMANA1	string	framexml
+VOICEMACRO_LABEL_OUTOFMANA2	string	framexml
+VOICEMACRO_LABEL_RASPBERRY1	string	framexml
+VOICEMACRO_LABEL_RASPBERRY2	string	framexml
+VOICEMACRO_LABEL_SILLY1	string	framexml
+VOICEMACRO_LABEL_THANKYOU1	string	framexml
+VOICEMACRO_LABEL_THANKYOU2	string	framexml
+VOICEMACRO_LABEL_THANKYOU3	string	framexml
+VOICEMACRO_LABEL_TRAIN1	string	framexml
+VOICEMACRO_LABEL_WAITHERE1	string	framexml
+VOICEMACRO_LABEL_WAITHERE2	string	framexml
+VOICEMACRO_LABEL_YES1	string	framexml
+VOICEMACRO_LABEL_YOUREWELCOME1	string	framexml
+VOICEMACRO_LABEL_YOUREWELCOME2	string	framexml
+VSABSORBOTHEROTHER	string	framexml
+VSABSORBOTHERSELF	string	framexml
+VSABSORBSELFOTHER	string	framexml
+VSBLOCKOTHEROTHER	string	framexml
+VSBLOCKOTHERSELF	string	framexml
+VSBLOCKSELFOTHER	string	framexml
+VSDEFLECTOTHEROTHER	string	framexml
+VSDEFLECTOTHERSELF	string	framexml
+VSDEFLECTSELFOTHER	string	framexml
+VSDODGEOTHEROTHER	string	framexml
+VSDODGEOTHERSELF	string	framexml
+VSDODGESELFOTHER	string	framexml
+VSENVIRONMENTALDAMAGE_DROWNING_OTHER	string	framexml
+VSENVIRONMENTALDAMAGE_DROWNING_SELF	string	framexml
+VSENVIRONMENTALDAMAGE_FALLING_OTHER	string	framexml
+VSENVIRONMENTALDAMAGE_FALLING_SELF	string	framexml
+VSENVIRONMENTALDAMAGE_FATIGUE_OTHER	string	framexml
+VSENVIRONMENTALDAMAGE_FATIGUE_SELF	string	framexml
+VSENVIRONMENTALDAMAGE_FIRE_OTHER	string	framexml
+VSENVIRONMENTALDAMAGE_FIRE_SELF	string	framexml
+VSENVIRONMENTALDAMAGE_LAVA_OTHER	string	framexml
+VSENVIRONMENTALDAMAGE_LAVA_SELF	string	framexml
+VSENVIRONMENTALDAMAGE_SLIME_OTHER	string	framexml
+VSENVIRONMENTALDAMAGE_SLIME_SELF	string	framexml
+VSEVADEOTHEROTHER	string	framexml
+VSEVADEOTHERSELF	string	framexml
+VSEVADESELFOTHER	string	framexml
+VSIMMUNEOTHEROTHER	string	framexml
+VSIMMUNEOTHERSELF	string	framexml
+VSIMMUNESELFOTHER	string	framexml
+VSPARRYOTHEROTHER	string	framexml
+VSPARRYOTHERSELF	string	framexml
+VSPARRYSELFOTHER	string	framexml
+VSRESISTOTHEROTHER	string	framexml
+VSRESISTOTHERSELF	string	framexml
+VSRESISTSELFOTHER	string	framexml
+VULNERABLE_TRAILER	string	framexml
+ValidateFramePosition	function	framexml
+VerbalAbuseTip1	table	framexml
+VerbalAbuseTip1Text	table	framexml
+VerbalAbuseTip2	table	framexml
+VerbalAbuseTip2Text	table	framexml
+VerbalAbuseTip3	table	framexml
+VerbalAbuseTip3Text	table	framexml
+VerticalMultiBar3	lod	framexml
+VerticalMultiBar4	lod	framexml
+VoiceMacroMenu	table	framexml
+VoiceMacroMenuButton1	table	framexml
+VoiceMacroMenuButton10	table	framexml
+VoiceMacroMenuButton10ShortcutText	table	framexml
+VoiceMacroMenuButton11	table	framexml
+VoiceMacroMenuButton11ShortcutText	table	framexml
+VoiceMacroMenuButton12	table	framexml
+VoiceMacroMenuButton12ShortcutText	table	framexml
+VoiceMacroMenuButton13	table	framexml
+VoiceMacroMenuButton13ShortcutText	table	framexml
+VoiceMacroMenuButton14	table	framexml
+VoiceMacroMenuButton14ShortcutText	table	framexml
+VoiceMacroMenuButton15	table	framexml
+VoiceMacroMenuButton15ShortcutText	table	framexml
+VoiceMacroMenuButton16	table	framexml
+VoiceMacroMenuButton16ShortcutText	table	framexml
+VoiceMacroMenuButton17	table	framexml
+VoiceMacroMenuButton17ShortcutText	table	framexml
+VoiceMacroMenuButton18	table	framexml
+VoiceMacroMenuButton18ShortcutText	table	framexml
+VoiceMacroMenuButton19	table	framexml
+VoiceMacroMenuButton19ShortcutText	table	framexml
+VoiceMacroMenuButton1ShortcutText	table	framexml
+VoiceMacroMenuButton2	table	framexml
+VoiceMacroMenuButton20	table	framexml
+VoiceMacroMenuButton20ShortcutText	table	framexml
+VoiceMacroMenuButton21	table	framexml
+VoiceMacroMenuButton21ShortcutText	table	framexml
+VoiceMacroMenuButton22	table	framexml
+VoiceMacroMenuButton22ShortcutText	table	framexml
+VoiceMacroMenuButton23	table	framexml
+VoiceMacroMenuButton23ShortcutText	table	framexml
+VoiceMacroMenuButton24	table	framexml
+VoiceMacroMenuButton24ShortcutText	table	framexml
+VoiceMacroMenuButton25	table	framexml
+VoiceMacroMenuButton25ShortcutText	table	framexml
+VoiceMacroMenuButton26	table	framexml
+VoiceMacroMenuButton26ShortcutText	table	framexml
+VoiceMacroMenuButton27	table	framexml
+VoiceMacroMenuButton27ShortcutText	table	framexml
+VoiceMacroMenuButton28	table	framexml
+VoiceMacroMenuButton28ShortcutText	table	framexml
+VoiceMacroMenuButton29	table	framexml
+VoiceMacroMenuButton29ShortcutText	table	framexml
+VoiceMacroMenuButton2ShortcutText	table	framexml
+VoiceMacroMenuButton3	table	framexml
+VoiceMacroMenuButton30	table	framexml
+VoiceMacroMenuButton30ShortcutText	table	framexml
+VoiceMacroMenuButton31	table	framexml
+VoiceMacroMenuButton31ShortcutText	table	framexml
+VoiceMacroMenuButton32	table	framexml
+VoiceMacroMenuButton32ShortcutText	table	framexml
+VoiceMacroMenuButton3ShortcutText	table	framexml
+VoiceMacroMenuButton4	table	framexml
+VoiceMacroMenuButton4ShortcutText	table	framexml
+VoiceMacroMenuButton5	table	framexml
+VoiceMacroMenuButton5ShortcutText	table	framexml
+VoiceMacroMenuButton6	table	framexml
+VoiceMacroMenuButton6ShortcutText	table	framexml
+VoiceMacroMenuButton7	table	framexml
+VoiceMacroMenuButton7ShortcutText	table	framexml
+VoiceMacroMenuButton8	table	framexml
+VoiceMacroMenuButton8ShortcutText	table	framexml
+VoiceMacroMenuButton9	table	framexml
+VoiceMacroMenuButton9ShortcutText	table	framexml
+VoiceMacroMenu_Click	function	framexml
+VoiceMacroMenu_OnLoad	function	framexml
+WAISTSLOT	string	framexml
+WARLOCK_INTELLECT_TOOLTIP	string	framexml
+WARRIOR_STRENGTH_TOOLTIP	string	framexml
+WATER_COLLISION	string	framexml
+WATER_DETAIL	string	framexml
+WEATHER_DETAIL	string	framexml
+WHISPER	string	framexml
+WHISPER_MESSAGE	string	framexml
+WHO	string	framexml
+WHOFRAME_DROPDOWN_LIST	table	framexml
+WHOS_TO_DISPLAY	number	framexml
+WHO_FRAME_SHOWN_TEMPLATE	string	framexml
+WHO_FRAME_TOTAL_TEMPLATE	string	framexml
+WHO_FRAME_TOTAL_TEMPLATE_P1	string	framexml
+WHO_LIST	string	framexml
+WHO_LIST_FORMAT	string	framexml
+WHO_LIST_GUILD_FORMAT	string	framexml
+WHO_NUM_RESULTS	string	framexml
+WHO_NUM_RESULTS_P1	string	framexml
+WHO_TAG_CLASS	string	framexml
+WHO_TAG_GUILD	string	framexml
+WHO_TAG_NAME	string	framexml
+WHO_TAG_RACE	string	framexml
+WHO_TAG_ZONE	string	framexml
+WIDESCREEN_TAG	string	framexml
+WINDOWED_MAXIMIZED	string	framexml
+WINDOWED_MODE	string	framexml
+WORLDMAP_BUTTON	string	framexml
+WORLDMAP_POI_TEXTURE_WIDTH	number	framexml
+WORLDSTATECOREFRAME_BUTTON_TEXT_OFFSET	number	framexml
+WORLDSTATESCOREFRAME_BASE_WIDTH	number	framexml
+WORLDSTATESCOREFRAME_COLUMN_SPACING	number	framexml
+WORLD_APPEARANCE	string	framexml
+WORLD_LOD	string	framexml
+WORLD_MAP	string	framexml
+WORLD_PORT_ROOT_TIMER	string	framexml
+WRISTSLOT	string	framexml
+WRONG_SLOT_FOR_ITEM	string	framexml
+WhoFrame	table	framexml
+WhoFrameAddFriendButton	table	framexml
+WhoFrameAddFriendButtonText	table	framexml
+WhoFrameButton1	table	framexml
+WhoFrameButton10	table	framexml
+WhoFrameButton10Class	table	framexml
+WhoFrameButton10Level	table	framexml
+WhoFrameButton10Name	table	framexml
+WhoFrameButton10Variable	table	framexml
+WhoFrameButton11	table	framexml
+WhoFrameButton11Class	table	framexml
+WhoFrameButton11Level	table	framexml
+WhoFrameButton11Name	table	framexml
+WhoFrameButton11Variable	table	framexml
+WhoFrameButton12	table	framexml
+WhoFrameButton12Class	table	framexml
+WhoFrameButton12Level	table	framexml
+WhoFrameButton12Name	table	framexml
+WhoFrameButton12Variable	table	framexml
+WhoFrameButton13	table	framexml
+WhoFrameButton13Class	table	framexml
+WhoFrameButton13Level	table	framexml
+WhoFrameButton13Name	table	framexml
+WhoFrameButton13Variable	table	framexml
+WhoFrameButton14	table	framexml
+WhoFrameButton14Class	table	framexml
+WhoFrameButton14Level	table	framexml
+WhoFrameButton14Name	table	framexml
+WhoFrameButton14Variable	table	framexml
+WhoFrameButton15	table	framexml
+WhoFrameButton15Class	table	framexml
+WhoFrameButton15Level	table	framexml
+WhoFrameButton15Name	table	framexml
+WhoFrameButton15Variable	table	framexml
+WhoFrameButton16	table	framexml
+WhoFrameButton16Class	table	framexml
+WhoFrameButton16Level	table	framexml
+WhoFrameButton16Name	table	framexml
+WhoFrameButton16Variable	table	framexml
+WhoFrameButton17	table	framexml
+WhoFrameButton17Class	table	framexml
+WhoFrameButton17Level	table	framexml
+WhoFrameButton17Name	table	framexml
+WhoFrameButton17Variable	table	framexml
+WhoFrameButton1Class	table	framexml
+WhoFrameButton1Level	table	framexml
+WhoFrameButton1Name	table	framexml
+WhoFrameButton1Variable	table	framexml
+WhoFrameButton2	table	framexml
+WhoFrameButton2Class	table	framexml
+WhoFrameButton2Level	table	framexml
+WhoFrameButton2Name	table	framexml
+WhoFrameButton2Variable	table	framexml
+WhoFrameButton3	table	framexml
+WhoFrameButton3Class	table	framexml
+WhoFrameButton3Level	table	framexml
+WhoFrameButton3Name	table	framexml
+WhoFrameButton3Variable	table	framexml
+WhoFrameButton4	table	framexml
+WhoFrameButton4Class	table	framexml
+WhoFrameButton4Level	table	framexml
+WhoFrameButton4Name	table	framexml
+WhoFrameButton4Variable	table	framexml
+WhoFrameButton5	table	framexml
+WhoFrameButton5Class	table	framexml
+WhoFrameButton5Level	table	framexml
+WhoFrameButton5Name	table	framexml
+WhoFrameButton5Variable	table	framexml
+WhoFrameButton6	table	framexml
+WhoFrameButton6Class	table	framexml
+WhoFrameButton6Level	table	framexml
+WhoFrameButton6Name	table	framexml
+WhoFrameButton6Variable	table	framexml
+WhoFrameButton7	table	framexml
+WhoFrameButton7Class	table	framexml
+WhoFrameButton7Level	table	framexml
+WhoFrameButton7Name	table	framexml
+WhoFrameButton7Variable	table	framexml
+WhoFrameButton8	table	framexml
+WhoFrameButton8Class	table	framexml
+WhoFrameButton8Level	table	framexml
+WhoFrameButton8Name	table	framexml
+WhoFrameButton8Variable	table	framexml
+WhoFrameButton9	table	framexml
+WhoFrameButton9Class	table	framexml
+WhoFrameButton9Level	table	framexml
+WhoFrameButton9Name	table	framexml
+WhoFrameButton9Variable	table	framexml
+WhoFrameColumnHeader1	table	framexml
+WhoFrameColumnHeader1HighlightTexture	table	framexml
+WhoFrameColumnHeader1Left	table	framexml
+WhoFrameColumnHeader1Middle	table	framexml
+WhoFrameColumnHeader1Right	table	framexml
+WhoFrameColumnHeader2	table	framexml
+WhoFrameColumnHeader2HighlightTexture	table	framexml
+WhoFrameColumnHeader2Left	table	framexml
+WhoFrameColumnHeader2Middle	table	framexml
+WhoFrameColumnHeader2Right	table	framexml
+WhoFrameColumnHeader3	table	framexml
+WhoFrameColumnHeader3HighlightTexture	table	framexml
+WhoFrameColumnHeader3Left	table	framexml
+WhoFrameColumnHeader3Middle	table	framexml
+WhoFrameColumnHeader3Right	table	framexml
+WhoFrameColumnHeader4	table	framexml
+WhoFrameColumnHeader4HighlightTexture	table	framexml
+WhoFrameColumnHeader4Left	table	framexml
+WhoFrameColumnHeader4Middle	table	framexml
+WhoFrameColumnHeader4Right	table	framexml
+WhoFrameColumnHeader5	lod	framexml
+WhoFrameColumnHeaderTemplate	lod	framexml
+WhoFrameColumn_SetWidth	function	framexml
+WhoFrameDropDown	table	framexml
+WhoFrameDropDownButton	table	framexml
+WhoFrameDropDownButtonDisabledTexture	table	framexml
+WhoFrameDropDownButtonHighlightTexture	table	framexml
+WhoFrameDropDownButtonNormalTexture	table	framexml
+WhoFrameDropDownButtonPushedTexture	table	framexml
+WhoFrameDropDownButton_OnClick	function	framexml
+WhoFrameDropDownHighlightTexture	table	framexml
+WhoFrameDropDownLeft	table	framexml
+WhoFrameDropDownMiddle	table	framexml
+WhoFrameDropDownRight	table	framexml
+WhoFrameDropDownText	table	framexml
+WhoFrameDropDown_Initialize	function	framexml
+WhoFrameDropDown_OnLoad	function	framexml
+WhoFrameEditBox	table	framexml
+WhoFrameEditBox_OnEnterPressed	function	framexml
+WhoFrameGroupInviteButton	table	framexml
+WhoFrameGroupInviteButtonText	table	framexml
+WhoFrameLFGButton	lod	framexml
+WhoFrameLFGButtonText	lod	framexml
+WhoFrameLFGFrame	lod	framexml
+WhoFrameLFGFrameLeft	lod	framexml
+WhoFrameLFGFrameMiddle	lod	framexml
+WhoFrameLFGFrameRight	lod	framexml
+WhoFrameTotals	table	framexml
+WhoFrameWhoButton	table	framexml
+WhoFrameWhoButtonText	table	framexml
+WhoFrame_GetDefaultWhoCommand	function	framexml
+WhoListScrollFrame	table	framexml
+WhoListScrollFrameScrollBar	table	framexml
+WhoListScrollFrameScrollBarScrollDownButton	table	framexml
+WhoListScrollFrameScrollBarScrollUpButton	table	framexml
+WhoListScrollFrameScrollBarThumbTexture	table	framexml
+WhoListScrollFrameScrollChildFrame	table	framexml
+WhoList_Update	function	framexml
+WorldFrame	table	framexml
+WorldFrame_OnUpdate	function	framexml
+WorldMapButton	table	framexml
+WorldMapButton_OnClick	function	framexml
+WorldMapButton_OnUpdate	function	framexml
+WorldMapContinentButton_OnClick	function	framexml
+WorldMapContinentDropDown	table	framexml
+WorldMapContinentDropDownButton	table	framexml
+WorldMapContinentDropDownButtonDisabledTexture	table	framexml
+WorldMapContinentDropDownButtonHighlightTexture	table	framexml
+WorldMapContinentDropDownButtonNormalTexture	table	framexml
+WorldMapContinentDropDownButtonPushedTexture	table	framexml
+WorldMapContinentDropDownLeft	table	framexml
+WorldMapContinentDropDownMiddle	table	framexml
+WorldMapContinentDropDownRight	table	framexml
+WorldMapContinentDropDownText	table	framexml
+WorldMapContinentsDropDown_Initialize	function	framexml
+WorldMapContinentsDropDown_OnLoad	function	framexml
+WorldMapCorpse	table	framexml
+WorldMapCorpseTemplate	lod	framexml
+WorldMapDetailFrame	table	framexml
+WorldMapDetailTile1	table	framexml
+WorldMapDetailTile10	table	framexml
+WorldMapDetailTile11	table	framexml
+WorldMapDetailTile12	table	framexml
+WorldMapDetailTile2	table	framexml
+WorldMapDetailTile3	table	framexml
+WorldMapDetailTile4	table	framexml
+WorldMapDetailTile5	table	framexml
+WorldMapDetailTile6	table	framexml
+WorldMapDetailTile7	table	framexml
+WorldMapDetailTile8	table	framexml
+WorldMapDetailTile9	table	framexml
+WorldMapFlag1	table	framexml
+WorldMapFlag1Texture	table	framexml
+WorldMapFlag2	table	framexml
+WorldMapFlag2Texture	table	framexml
+WorldMapFlagTemplate	lod	framexml
+WorldMapFrame	table	framexml
+WorldMapFrameAreaDescription	table	framexml
+WorldMapFrameAreaFrame	table	framexml
+WorldMapFrameAreaLabel	table	framexml
+WorldMapFrameCloseButton	table	framexml
+WorldMapFrame_LoadContinents	function	framexml
+WorldMapFrame_LoadZones	function	framexml
+WorldMapFrame_OnEvent	function	framexml
+WorldMapFrame_OnLoad	function	framexml
+WorldMapFrame_PingPlayerPosition	function	framexml
+WorldMapFrame_Update	function	framexml
+WorldMapHighlight	table	framexml
+WorldMapMagnifyingGlassButton	table	framexml
+WorldMapMicroButton	table	framexml
+WorldMapPOI_OnClick	function	framexml
+WorldMapPOI_OnEnter	function	framexml
+WorldMapPOI_OnLeave	function	framexml
+WorldMapParty1	table	framexml
+WorldMapParty1Icon	table	framexml
+WorldMapParty2	table	framexml
+WorldMapParty2Icon	table	framexml
+WorldMapParty3	table	framexml
+WorldMapParty3Icon	table	framexml
+WorldMapParty4	table	framexml
+WorldMapParty4Icon	table	framexml
+WorldMapPing	table	framexml
+WorldMapPlayer	table	framexml
+WorldMapPositioningGuide	table	framexml
+WorldMapRaid1	table	framexml
+WorldMapRaid10	table	framexml
+WorldMapRaid10Icon	table	framexml
+WorldMapRaid11	table	framexml
+WorldMapRaid11Icon	table	framexml
+WorldMapRaid12	table	framexml
+WorldMapRaid12Icon	table	framexml
+WorldMapRaid13	table	framexml
+WorldMapRaid13Icon	table	framexml
+WorldMapRaid14	table	framexml
+WorldMapRaid14Icon	table	framexml
+WorldMapRaid15	table	framexml
+WorldMapRaid15Icon	table	framexml
+WorldMapRaid16	table	framexml
+WorldMapRaid16Icon	table	framexml
+WorldMapRaid17	table	framexml
+WorldMapRaid17Icon	table	framexml
+WorldMapRaid18	table	framexml
+WorldMapRaid18Icon	table	framexml
+WorldMapRaid19	table	framexml
+WorldMapRaid19Icon	table	framexml
+WorldMapRaid1Icon	table	framexml
+WorldMapRaid2	table	framexml
+WorldMapRaid20	table	framexml
+WorldMapRaid20Icon	table	framexml
+WorldMapRaid21	table	framexml
+WorldMapRaid21Icon	table	framexml
+WorldMapRaid22	table	framexml
+WorldMapRaid22Icon	table	framexml
+WorldMapRaid23	table	framexml
+WorldMapRaid23Icon	table	framexml
+WorldMapRaid24	table	framexml
+WorldMapRaid24Icon	table	framexml
+WorldMapRaid25	table	framexml
+WorldMapRaid25Icon	table	framexml
+WorldMapRaid26	table	framexml
+WorldMapRaid26Icon	table	framexml
+WorldMapRaid27	table	framexml
+WorldMapRaid27Icon	table	framexml
+WorldMapRaid28	table	framexml
+WorldMapRaid28Icon	table	framexml
+WorldMapRaid29	table	framexml
+WorldMapRaid29Icon	table	framexml
+WorldMapRaid2Icon	table	framexml
+WorldMapRaid3	table	framexml
+WorldMapRaid30	table	framexml
+WorldMapRaid30Icon	table	framexml
+WorldMapRaid31	table	framexml
+WorldMapRaid31Icon	table	framexml
+WorldMapRaid32	table	framexml
+WorldMapRaid32Icon	table	framexml
+WorldMapRaid33	table	framexml
+WorldMapRaid33Icon	table	framexml
+WorldMapRaid34	table	framexml
+WorldMapRaid34Icon	table	framexml
+WorldMapRaid35	table	framexml
+WorldMapRaid35Icon	table	framexml
+WorldMapRaid36	table	framexml
+WorldMapRaid36Icon	table	framexml
+WorldMapRaid37	table	framexml
+WorldMapRaid37Icon	table	framexml
+WorldMapRaid38	table	framexml
+WorldMapRaid38Icon	table	framexml
+WorldMapRaid39	table	framexml
+WorldMapRaid39Icon	table	framexml
+WorldMapRaid3Icon	table	framexml
+WorldMapRaid4	table	framexml
+WorldMapRaid40	table	framexml
+WorldMapRaid40Icon	table	framexml
+WorldMapRaid4Icon	table	framexml
+WorldMapRaid5	table	framexml
+WorldMapRaid5Icon	table	framexml
+WorldMapRaid6	table	framexml
+WorldMapRaid6Icon	table	framexml
+WorldMapRaid7	table	framexml
+WorldMapRaid7Icon	table	framexml
+WorldMapRaid8	table	framexml
+WorldMapRaid8Icon	table	framexml
+WorldMapRaid9	table	framexml
+WorldMapRaid9Icon	table	framexml
+WorldMapRaidUnitTemplate	lod	framexml
+WorldMapTextFont	table	framexml
+WorldMapTooltip	table	framexml
+WorldMapTooltipMoneyFrame	table	framexml
+WorldMapTooltipMoneyFrameCopperButton	table	framexml
+WorldMapTooltipMoneyFrameCopperButtonText	table	framexml
+WorldMapTooltipMoneyFrameGoldButton	table	framexml
+WorldMapTooltipMoneyFrameGoldButtonText	table	framexml
+WorldMapTooltipMoneyFrameSilverButton	table	framexml
+WorldMapTooltipMoneyFrameSilverButtonText	table	framexml
+WorldMapTooltipStatusBar	table	framexml
+WorldMapTooltipStatusBarTexture	table	framexml
+WorldMapTooltipTextLeft1	table	framexml
+WorldMapTooltipTextLeft10	table	framexml
+WorldMapTooltipTextLeft11	table	framexml
+WorldMapTooltipTextLeft12	table	framexml
+WorldMapTooltipTextLeft13	table	framexml
+WorldMapTooltipTextLeft14	table	framexml
+WorldMapTooltipTextLeft15	table	framexml
+WorldMapTooltipTextLeft16	table	framexml
+WorldMapTooltipTextLeft17	table	framexml
+WorldMapTooltipTextLeft18	table	framexml
+WorldMapTooltipTextLeft19	table	framexml
+WorldMapTooltipTextLeft2	table	framexml
+WorldMapTooltipTextLeft20	table	framexml
+WorldMapTooltipTextLeft21	table	framexml
+WorldMapTooltipTextLeft22	table	framexml
+WorldMapTooltipTextLeft23	table	framexml
+WorldMapTooltipTextLeft24	table	framexml
+WorldMapTooltipTextLeft25	table	framexml
+WorldMapTooltipTextLeft26	table	framexml
+WorldMapTooltipTextLeft27	table	framexml
+WorldMapTooltipTextLeft28	table	framexml
+WorldMapTooltipTextLeft29	table	framexml
+WorldMapTooltipTextLeft3	table	framexml
+WorldMapTooltipTextLeft30	table	framexml
+WorldMapTooltipTextLeft4	table	framexml
+WorldMapTooltipTextLeft5	table	framexml
+WorldMapTooltipTextLeft6	table	framexml
+WorldMapTooltipTextLeft7	table	framexml
+WorldMapTooltipTextLeft8	table	framexml
+WorldMapTooltipTextLeft9	table	framexml
+WorldMapTooltipTextRight1	table	framexml
+WorldMapTooltipTextRight10	table	framexml
+WorldMapTooltipTextRight11	table	framexml
+WorldMapTooltipTextRight12	table	framexml
+WorldMapTooltipTextRight13	table	framexml
+WorldMapTooltipTextRight14	table	framexml
+WorldMapTooltipTextRight15	table	framexml
+WorldMapTooltipTextRight16	table	framexml
+WorldMapTooltipTextRight17	table	framexml
+WorldMapTooltipTextRight18	table	framexml
+WorldMapTooltipTextRight19	table	framexml
+WorldMapTooltipTextRight2	table	framexml
+WorldMapTooltipTextRight20	table	framexml
+WorldMapTooltipTextRight21	table	framexml
+WorldMapTooltipTextRight22	table	framexml
+WorldMapTooltipTextRight23	table	framexml
+WorldMapTooltipTextRight24	table	framexml
+WorldMapTooltipTextRight25	table	framexml
+WorldMapTooltipTextRight26	table	framexml
+WorldMapTooltipTextRight27	table	framexml
+WorldMapTooltipTextRight28	table	framexml
+WorldMapTooltipTextRight29	table	framexml
+WorldMapTooltipTextRight3	table	framexml
+WorldMapTooltipTextRight30	table	framexml
+WorldMapTooltipTextRight4	table	framexml
+WorldMapTooltipTextRight5	table	framexml
+WorldMapTooltipTextRight6	table	framexml
+WorldMapTooltipTextRight7	table	framexml
+WorldMapTooltipTextRight8	table	framexml
+WorldMapTooltipTextRight9	table	framexml
+WorldMapTooltipTexture1	table	framexml
+WorldMapTooltipTexture2	table	framexml
+WorldMapTooltipTexture3	table	framexml
+WorldMapUnitTemplate	lod	framexml
+WorldMapUnit_OnEnter	function	framexml
+WorldMapZoneButton_OnClick	function	framexml
+WorldMapZoneDropDown	table	framexml
+WorldMapZoneDropDownButton	table	framexml
+WorldMapZoneDropDownButtonDisabledTexture	table	framexml
+WorldMapZoneDropDownButtonHighlightTexture	table	framexml
+WorldMapZoneDropDownButtonNormalTexture	table	framexml
+WorldMapZoneDropDownButtonPushedTexture	table	framexml
+WorldMapZoneDropDownLeft	table	framexml
+WorldMapZoneDropDownMiddle	table	framexml
+WorldMapZoneDropDownRight	table	framexml
+WorldMapZoneDropDownText	table	framexml
+WorldMapZoneDropDown_Initialize	function	framexml
+WorldMapZoneDropDown_OnLoad	function	framexml
+WorldMapZoomOutButton	table	framexml
+WorldMapZoomOutButtonText	table	framexml
+WorldMapZoomOutButton_OnClick	function	framexml
+WorldMap_CreatePOI	function	framexml
+WorldMap_GetPOITextureCoords	function	framexml
+WorldMap_UpdateContinentDropDownText	function	framexml
+WorldMap_UpdateZoneDropDownText	function	framexml
+WorldStateAlwaysUpFrame	table	framexml
+WorldStateAlwaysUpFrame_OnEvent	function	framexml
+WorldStateAlwaysUpFrame_OnLoad	function	framexml
+WorldStateAlwaysUpFrame_Update	function	framexml
+WorldStateAlwaysUpTemplate	lod	framexml
+WorldStateCaptureBarTemplate	lod	framexml
+WorldStateFrame_ToggleMinimap	function	framexml
+WorldStateScoreBattlegroundRunTime	table	framexml
+WorldStateScoreButton1	table	framexml
+WorldStateScoreButton10	table	framexml
+WorldStateScoreButton10Column1Icon	table	framexml
+WorldStateScoreButton10Column1Text	table	framexml
+WorldStateScoreButton10Column2Icon	table	framexml
+WorldStateScoreButton10Column2Text	table	framexml
+WorldStateScoreButton10Column3Icon	table	framexml
+WorldStateScoreButton10Column3Text	table	framexml
+WorldStateScoreButton10Column4Icon	table	framexml
+WorldStateScoreButton10Column4Text	table	framexml
+WorldStateScoreButton10Column5Icon	table	framexml
+WorldStateScoreButton10Column5Text	table	framexml
+WorldStateScoreButton10Column6Icon	table	framexml
+WorldStateScoreButton10Column6Text	table	framexml
+WorldStateScoreButton10Column7Icon	table	framexml
+WorldStateScoreButton10Column7Text	table	framexml
+WorldStateScoreButton10Deaths	table	framexml
+WorldStateScoreButton10FactionLeft	table	framexml
+WorldStateScoreButton10FactionRight	table	framexml
+WorldStateScoreButton10HonorGained	table	framexml
+WorldStateScoreButton10HonorableKills	table	framexml
+WorldStateScoreButton10KillingBlows	table	framexml
+WorldStateScoreButton10NameButton	table	framexml
+WorldStateScoreButton10NameButtonName	table	framexml
+WorldStateScoreButton10RankButton	table	framexml
+WorldStateScoreButton10RankButtonIcon	table	framexml
+WorldStateScoreButton11	table	framexml
+WorldStateScoreButton11Column1Icon	table	framexml
+WorldStateScoreButton11Column1Text	table	framexml
+WorldStateScoreButton11Column2Icon	table	framexml
+WorldStateScoreButton11Column2Text	table	framexml
+WorldStateScoreButton11Column3Icon	table	framexml
+WorldStateScoreButton11Column3Text	table	framexml
+WorldStateScoreButton11Column4Icon	table	framexml
+WorldStateScoreButton11Column4Text	table	framexml
+WorldStateScoreButton11Column5Icon	table	framexml
+WorldStateScoreButton11Column5Text	table	framexml
+WorldStateScoreButton11Column6Icon	table	framexml
+WorldStateScoreButton11Column6Text	table	framexml
+WorldStateScoreButton11Column7Icon	table	framexml
+WorldStateScoreButton11Column7Text	table	framexml
+WorldStateScoreButton11Deaths	table	framexml
+WorldStateScoreButton11FactionLeft	table	framexml
+WorldStateScoreButton11FactionRight	table	framexml
+WorldStateScoreButton11HonorGained	table	framexml
+WorldStateScoreButton11HonorableKills	table	framexml
+WorldStateScoreButton11KillingBlows	table	framexml
+WorldStateScoreButton11NameButton	table	framexml
+WorldStateScoreButton11NameButtonName	table	framexml
+WorldStateScoreButton11RankButton	table	framexml
+WorldStateScoreButton11RankButtonIcon	table	framexml
+WorldStateScoreButton12	table	framexml
+WorldStateScoreButton12Column1Icon	table	framexml
+WorldStateScoreButton12Column1Text	table	framexml
+WorldStateScoreButton12Column2Icon	table	framexml
+WorldStateScoreButton12Column2Text	table	framexml
+WorldStateScoreButton12Column3Icon	table	framexml
+WorldStateScoreButton12Column3Text	table	framexml
+WorldStateScoreButton12Column4Icon	table	framexml
+WorldStateScoreButton12Column4Text	table	framexml
+WorldStateScoreButton12Column5Icon	table	framexml
+WorldStateScoreButton12Column5Text	table	framexml
+WorldStateScoreButton12Column6Icon	table	framexml
+WorldStateScoreButton12Column6Text	table	framexml
+WorldStateScoreButton12Column7Icon	table	framexml
+WorldStateScoreButton12Column7Text	table	framexml
+WorldStateScoreButton12Deaths	table	framexml
+WorldStateScoreButton12FactionLeft	table	framexml
+WorldStateScoreButton12FactionRight	table	framexml
+WorldStateScoreButton12HonorGained	table	framexml
+WorldStateScoreButton12HonorableKills	table	framexml
+WorldStateScoreButton12KillingBlows	table	framexml
+WorldStateScoreButton12NameButton	table	framexml
+WorldStateScoreButton12NameButtonName	table	framexml
+WorldStateScoreButton12RankButton	table	framexml
+WorldStateScoreButton12RankButtonIcon	table	framexml
+WorldStateScoreButton13	table	framexml
+WorldStateScoreButton13Column1Icon	table	framexml
+WorldStateScoreButton13Column1Text	table	framexml
+WorldStateScoreButton13Column2Icon	table	framexml
+WorldStateScoreButton13Column2Text	table	framexml
+WorldStateScoreButton13Column3Icon	table	framexml
+WorldStateScoreButton13Column3Text	table	framexml
+WorldStateScoreButton13Column4Icon	table	framexml
+WorldStateScoreButton13Column4Text	table	framexml
+WorldStateScoreButton13Column5Icon	table	framexml
+WorldStateScoreButton13Column5Text	table	framexml
+WorldStateScoreButton13Column6Icon	table	framexml
+WorldStateScoreButton13Column6Text	table	framexml
+WorldStateScoreButton13Column7Icon	table	framexml
+WorldStateScoreButton13Column7Text	table	framexml
+WorldStateScoreButton13Deaths	table	framexml
+WorldStateScoreButton13FactionLeft	table	framexml
+WorldStateScoreButton13FactionRight	table	framexml
+WorldStateScoreButton13HonorGained	table	framexml
+WorldStateScoreButton13HonorableKills	table	framexml
+WorldStateScoreButton13KillingBlows	table	framexml
+WorldStateScoreButton13NameButton	table	framexml
+WorldStateScoreButton13NameButtonName	table	framexml
+WorldStateScoreButton13RankButton	table	framexml
+WorldStateScoreButton13RankButtonIcon	table	framexml
+WorldStateScoreButton14	table	framexml
+WorldStateScoreButton14Column1Icon	table	framexml
+WorldStateScoreButton14Column1Text	table	framexml
+WorldStateScoreButton14Column2Icon	table	framexml
+WorldStateScoreButton14Column2Text	table	framexml
+WorldStateScoreButton14Column3Icon	table	framexml
+WorldStateScoreButton14Column3Text	table	framexml
+WorldStateScoreButton14Column4Icon	table	framexml
+WorldStateScoreButton14Column4Text	table	framexml
+WorldStateScoreButton14Column5Icon	table	framexml
+WorldStateScoreButton14Column5Text	table	framexml
+WorldStateScoreButton14Column6Icon	table	framexml
+WorldStateScoreButton14Column6Text	table	framexml
+WorldStateScoreButton14Column7Icon	table	framexml
+WorldStateScoreButton14Column7Text	table	framexml
+WorldStateScoreButton14Deaths	table	framexml
+WorldStateScoreButton14FactionLeft	table	framexml
+WorldStateScoreButton14FactionRight	table	framexml
+WorldStateScoreButton14HonorGained	table	framexml
+WorldStateScoreButton14HonorableKills	table	framexml
+WorldStateScoreButton14KillingBlows	table	framexml
+WorldStateScoreButton14NameButton	table	framexml
+WorldStateScoreButton14NameButtonName	table	framexml
+WorldStateScoreButton14RankButton	table	framexml
+WorldStateScoreButton14RankButtonIcon	table	framexml
+WorldStateScoreButton15	table	framexml
+WorldStateScoreButton15Column1Icon	table	framexml
+WorldStateScoreButton15Column1Text	table	framexml
+WorldStateScoreButton15Column2Icon	table	framexml
+WorldStateScoreButton15Column2Text	table	framexml
+WorldStateScoreButton15Column3Icon	table	framexml
+WorldStateScoreButton15Column3Text	table	framexml
+WorldStateScoreButton15Column4Icon	table	framexml
+WorldStateScoreButton15Column4Text	table	framexml
+WorldStateScoreButton15Column5Icon	table	framexml
+WorldStateScoreButton15Column5Text	table	framexml
+WorldStateScoreButton15Column6Icon	table	framexml
+WorldStateScoreButton15Column6Text	table	framexml
+WorldStateScoreButton15Column7Icon	table	framexml
+WorldStateScoreButton15Column7Text	table	framexml
+WorldStateScoreButton15Deaths	table	framexml
+WorldStateScoreButton15FactionLeft	table	framexml
+WorldStateScoreButton15FactionRight	table	framexml
+WorldStateScoreButton15HonorGained	table	framexml
+WorldStateScoreButton15HonorableKills	table	framexml
+WorldStateScoreButton15KillingBlows	table	framexml
+WorldStateScoreButton15NameButton	table	framexml
+WorldStateScoreButton15NameButtonName	table	framexml
+WorldStateScoreButton15RankButton	table	framexml
+WorldStateScoreButton15RankButtonIcon	table	framexml
+WorldStateScoreButton16	table	framexml
+WorldStateScoreButton16Column1Icon	table	framexml
+WorldStateScoreButton16Column1Text	table	framexml
+WorldStateScoreButton16Column2Icon	table	framexml
+WorldStateScoreButton16Column2Text	table	framexml
+WorldStateScoreButton16Column3Icon	table	framexml
+WorldStateScoreButton16Column3Text	table	framexml
+WorldStateScoreButton16Column4Icon	table	framexml
+WorldStateScoreButton16Column4Text	table	framexml
+WorldStateScoreButton16Column5Icon	table	framexml
+WorldStateScoreButton16Column5Text	table	framexml
+WorldStateScoreButton16Column6Icon	table	framexml
+WorldStateScoreButton16Column6Text	table	framexml
+WorldStateScoreButton16Column7Icon	table	framexml
+WorldStateScoreButton16Column7Text	table	framexml
+WorldStateScoreButton16Deaths	table	framexml
+WorldStateScoreButton16FactionLeft	table	framexml
+WorldStateScoreButton16FactionRight	table	framexml
+WorldStateScoreButton16HonorGained	table	framexml
+WorldStateScoreButton16HonorableKills	table	framexml
+WorldStateScoreButton16KillingBlows	table	framexml
+WorldStateScoreButton16NameButton	table	framexml
+WorldStateScoreButton16NameButtonName	table	framexml
+WorldStateScoreButton16RankButton	table	framexml
+WorldStateScoreButton16RankButtonIcon	table	framexml
+WorldStateScoreButton17	table	framexml
+WorldStateScoreButton17Column1Icon	table	framexml
+WorldStateScoreButton17Column1Text	table	framexml
+WorldStateScoreButton17Column2Icon	table	framexml
+WorldStateScoreButton17Column2Text	table	framexml
+WorldStateScoreButton17Column3Icon	table	framexml
+WorldStateScoreButton17Column3Text	table	framexml
+WorldStateScoreButton17Column4Icon	table	framexml
+WorldStateScoreButton17Column4Text	table	framexml
+WorldStateScoreButton17Column5Icon	table	framexml
+WorldStateScoreButton17Column5Text	table	framexml
+WorldStateScoreButton17Column6Icon	table	framexml
+WorldStateScoreButton17Column6Text	table	framexml
+WorldStateScoreButton17Column7Icon	table	framexml
+WorldStateScoreButton17Column7Text	table	framexml
+WorldStateScoreButton17Deaths	table	framexml
+WorldStateScoreButton17FactionLeft	table	framexml
+WorldStateScoreButton17FactionRight	table	framexml
+WorldStateScoreButton17HonorGained	table	framexml
+WorldStateScoreButton17HonorableKills	table	framexml
+WorldStateScoreButton17KillingBlows	table	framexml
+WorldStateScoreButton17NameButton	table	framexml
+WorldStateScoreButton17NameButtonName	table	framexml
+WorldStateScoreButton17RankButton	table	framexml
+WorldStateScoreButton17RankButtonIcon	table	framexml
+WorldStateScoreButton18	table	framexml
+WorldStateScoreButton18Column1Icon	table	framexml
+WorldStateScoreButton18Column1Text	table	framexml
+WorldStateScoreButton18Column2Icon	table	framexml
+WorldStateScoreButton18Column2Text	table	framexml
+WorldStateScoreButton18Column3Icon	table	framexml
+WorldStateScoreButton18Column3Text	table	framexml
+WorldStateScoreButton18Column4Icon	table	framexml
+WorldStateScoreButton18Column4Text	table	framexml
+WorldStateScoreButton18Column5Icon	table	framexml
+WorldStateScoreButton18Column5Text	table	framexml
+WorldStateScoreButton18Column6Icon	table	framexml
+WorldStateScoreButton18Column6Text	table	framexml
+WorldStateScoreButton18Column7Icon	table	framexml
+WorldStateScoreButton18Column7Text	table	framexml
+WorldStateScoreButton18Deaths	table	framexml
+WorldStateScoreButton18FactionLeft	table	framexml
+WorldStateScoreButton18FactionRight	table	framexml
+WorldStateScoreButton18HonorGained	table	framexml
+WorldStateScoreButton18HonorableKills	table	framexml
+WorldStateScoreButton18KillingBlows	table	framexml
+WorldStateScoreButton18NameButton	table	framexml
+WorldStateScoreButton18NameButtonName	table	framexml
+WorldStateScoreButton18RankButton	table	framexml
+WorldStateScoreButton18RankButtonIcon	table	framexml
+WorldStateScoreButton19	table	framexml
+WorldStateScoreButton19Column1Icon	table	framexml
+WorldStateScoreButton19Column1Text	table	framexml
+WorldStateScoreButton19Column2Icon	table	framexml
+WorldStateScoreButton19Column2Text	table	framexml
+WorldStateScoreButton19Column3Icon	table	framexml
+WorldStateScoreButton19Column3Text	table	framexml
+WorldStateScoreButton19Column4Icon	table	framexml
+WorldStateScoreButton19Column4Text	table	framexml
+WorldStateScoreButton19Column5Icon	table	framexml
+WorldStateScoreButton19Column5Text	table	framexml
+WorldStateScoreButton19Column6Icon	table	framexml
+WorldStateScoreButton19Column6Text	table	framexml
+WorldStateScoreButton19Column7Icon	table	framexml
+WorldStateScoreButton19Column7Text	table	framexml
+WorldStateScoreButton19Deaths	table	framexml
+WorldStateScoreButton19FactionLeft	table	framexml
+WorldStateScoreButton19FactionRight	table	framexml
+WorldStateScoreButton19HonorGained	table	framexml
+WorldStateScoreButton19HonorableKills	table	framexml
+WorldStateScoreButton19KillingBlows	table	framexml
+WorldStateScoreButton19NameButton	table	framexml
+WorldStateScoreButton19NameButtonName	table	framexml
+WorldStateScoreButton19RankButton	table	framexml
+WorldStateScoreButton19RankButtonIcon	table	framexml
+WorldStateScoreButton1Column1Icon	table	framexml
+WorldStateScoreButton1Column1Text	table	framexml
+WorldStateScoreButton1Column2Icon	table	framexml
+WorldStateScoreButton1Column2Text	table	framexml
+WorldStateScoreButton1Column3Icon	table	framexml
+WorldStateScoreButton1Column3Text	table	framexml
+WorldStateScoreButton1Column4Icon	table	framexml
+WorldStateScoreButton1Column4Text	table	framexml
+WorldStateScoreButton1Column5Icon	table	framexml
+WorldStateScoreButton1Column5Text	table	framexml
+WorldStateScoreButton1Column6Icon	table	framexml
+WorldStateScoreButton1Column6Text	table	framexml
+WorldStateScoreButton1Column7Icon	table	framexml
+WorldStateScoreButton1Column7Text	table	framexml
+WorldStateScoreButton1Deaths	table	framexml
+WorldStateScoreButton1FactionLeft	table	framexml
+WorldStateScoreButton1FactionRight	table	framexml
+WorldStateScoreButton1HonorGained	table	framexml
+WorldStateScoreButton1HonorableKills	table	framexml
+WorldStateScoreButton1KillingBlows	table	framexml
+WorldStateScoreButton1NameButton	table	framexml
+WorldStateScoreButton1NameButtonName	table	framexml
+WorldStateScoreButton1RankButton	table	framexml
+WorldStateScoreButton1RankButtonIcon	table	framexml
+WorldStateScoreButton2	table	framexml
+WorldStateScoreButton20	table	framexml
+WorldStateScoreButton20Column1Icon	table	framexml
+WorldStateScoreButton20Column1Text	table	framexml
+WorldStateScoreButton20Column2Icon	table	framexml
+WorldStateScoreButton20Column2Text	table	framexml
+WorldStateScoreButton20Column3Icon	table	framexml
+WorldStateScoreButton20Column3Text	table	framexml
+WorldStateScoreButton20Column4Icon	table	framexml
+WorldStateScoreButton20Column4Text	table	framexml
+WorldStateScoreButton20Column5Icon	table	framexml
+WorldStateScoreButton20Column5Text	table	framexml
+WorldStateScoreButton20Column6Icon	table	framexml
+WorldStateScoreButton20Column6Text	table	framexml
+WorldStateScoreButton20Column7Icon	table	framexml
+WorldStateScoreButton20Column7Text	table	framexml
+WorldStateScoreButton20Deaths	table	framexml
+WorldStateScoreButton20FactionLeft	table	framexml
+WorldStateScoreButton20FactionRight	table	framexml
+WorldStateScoreButton20HonorGained	table	framexml
+WorldStateScoreButton20HonorableKills	table	framexml
+WorldStateScoreButton20KillingBlows	table	framexml
+WorldStateScoreButton20NameButton	table	framexml
+WorldStateScoreButton20NameButtonName	table	framexml
+WorldStateScoreButton20RankButton	table	framexml
+WorldStateScoreButton20RankButtonIcon	table	framexml
+WorldStateScoreButton21	table	framexml
+WorldStateScoreButton21Column1Icon	table	framexml
+WorldStateScoreButton21Column1Text	table	framexml
+WorldStateScoreButton21Column2Icon	table	framexml
+WorldStateScoreButton21Column2Text	table	framexml
+WorldStateScoreButton21Column3Icon	table	framexml
+WorldStateScoreButton21Column3Text	table	framexml
+WorldStateScoreButton21Column4Icon	table	framexml
+WorldStateScoreButton21Column4Text	table	framexml
+WorldStateScoreButton21Column5Icon	table	framexml
+WorldStateScoreButton21Column5Text	table	framexml
+WorldStateScoreButton21Column6Icon	table	framexml
+WorldStateScoreButton21Column6Text	table	framexml
+WorldStateScoreButton21Column7Icon	table	framexml
+WorldStateScoreButton21Column7Text	table	framexml
+WorldStateScoreButton21Deaths	table	framexml
+WorldStateScoreButton21FactionLeft	table	framexml
+WorldStateScoreButton21FactionRight	table	framexml
+WorldStateScoreButton21HonorGained	table	framexml
+WorldStateScoreButton21HonorableKills	table	framexml
+WorldStateScoreButton21KillingBlows	table	framexml
+WorldStateScoreButton21NameButton	table	framexml
+WorldStateScoreButton21NameButtonName	table	framexml
+WorldStateScoreButton21RankButton	table	framexml
+WorldStateScoreButton21RankButtonIcon	table	framexml
+WorldStateScoreButton22	table	framexml
+WorldStateScoreButton22Column1Icon	table	framexml
+WorldStateScoreButton22Column1Text	table	framexml
+WorldStateScoreButton22Column2Icon	table	framexml
+WorldStateScoreButton22Column2Text	table	framexml
+WorldStateScoreButton22Column3Icon	table	framexml
+WorldStateScoreButton22Column3Text	table	framexml
+WorldStateScoreButton22Column4Icon	table	framexml
+WorldStateScoreButton22Column4Text	table	framexml
+WorldStateScoreButton22Column5Icon	table	framexml
+WorldStateScoreButton22Column5Text	table	framexml
+WorldStateScoreButton22Column6Icon	table	framexml
+WorldStateScoreButton22Column6Text	table	framexml
+WorldStateScoreButton22Column7Icon	table	framexml
+WorldStateScoreButton22Column7Text	table	framexml
+WorldStateScoreButton22Deaths	table	framexml
+WorldStateScoreButton22FactionLeft	table	framexml
+WorldStateScoreButton22FactionRight	table	framexml
+WorldStateScoreButton22HonorGained	table	framexml
+WorldStateScoreButton22HonorableKills	table	framexml
+WorldStateScoreButton22KillingBlows	table	framexml
+WorldStateScoreButton22NameButton	table	framexml
+WorldStateScoreButton22NameButtonName	table	framexml
+WorldStateScoreButton22RankButton	table	framexml
+WorldStateScoreButton22RankButtonIcon	table	framexml
+WorldStateScoreButton23	lod	framexml
+WorldStateScoreButton2Column1Icon	table	framexml
+WorldStateScoreButton2Column1Text	table	framexml
+WorldStateScoreButton2Column2Icon	table	framexml
+WorldStateScoreButton2Column2Text	table	framexml
+WorldStateScoreButton2Column3Icon	table	framexml
+WorldStateScoreButton2Column3Text	table	framexml
+WorldStateScoreButton2Column4Icon	table	framexml
+WorldStateScoreButton2Column4Text	table	framexml
+WorldStateScoreButton2Column5Icon	table	framexml
+WorldStateScoreButton2Column5Text	table	framexml
+WorldStateScoreButton2Column6Icon	table	framexml
+WorldStateScoreButton2Column6Text	table	framexml
+WorldStateScoreButton2Column7Icon	table	framexml
+WorldStateScoreButton2Column7Text	table	framexml
+WorldStateScoreButton2Deaths	table	framexml
+WorldStateScoreButton2FactionLeft	table	framexml
+WorldStateScoreButton2FactionRight	table	framexml
+WorldStateScoreButton2HonorGained	table	framexml
+WorldStateScoreButton2HonorableKills	table	framexml
+WorldStateScoreButton2KillingBlows	table	framexml
+WorldStateScoreButton2NameButton	table	framexml
+WorldStateScoreButton2NameButtonName	table	framexml
+WorldStateScoreButton2RankButton	table	framexml
+WorldStateScoreButton2RankButtonIcon	table	framexml
+WorldStateScoreButton3	table	framexml
+WorldStateScoreButton3Column1Icon	table	framexml
+WorldStateScoreButton3Column1Text	table	framexml
+WorldStateScoreButton3Column2Icon	table	framexml
+WorldStateScoreButton3Column2Text	table	framexml
+WorldStateScoreButton3Column3Icon	table	framexml
+WorldStateScoreButton3Column3Text	table	framexml
+WorldStateScoreButton3Column4Icon	table	framexml
+WorldStateScoreButton3Column4Text	table	framexml
+WorldStateScoreButton3Column5Icon	table	framexml
+WorldStateScoreButton3Column5Text	table	framexml
+WorldStateScoreButton3Column6Icon	table	framexml
+WorldStateScoreButton3Column6Text	table	framexml
+WorldStateScoreButton3Column7Icon	table	framexml
+WorldStateScoreButton3Column7Text	table	framexml
+WorldStateScoreButton3Deaths	table	framexml
+WorldStateScoreButton3FactionLeft	table	framexml
+WorldStateScoreButton3FactionRight	table	framexml
+WorldStateScoreButton3HonorGained	table	framexml
+WorldStateScoreButton3HonorableKills	table	framexml
+WorldStateScoreButton3KillingBlows	table	framexml
+WorldStateScoreButton3NameButton	table	framexml
+WorldStateScoreButton3NameButtonName	table	framexml
+WorldStateScoreButton3RankButton	table	framexml
+WorldStateScoreButton3RankButtonIcon	table	framexml
+WorldStateScoreButton4	table	framexml
+WorldStateScoreButton4Column1Icon	table	framexml
+WorldStateScoreButton4Column1Text	table	framexml
+WorldStateScoreButton4Column2Icon	table	framexml
+WorldStateScoreButton4Column2Text	table	framexml
+WorldStateScoreButton4Column3Icon	table	framexml
+WorldStateScoreButton4Column3Text	table	framexml
+WorldStateScoreButton4Column4Icon	table	framexml
+WorldStateScoreButton4Column4Text	table	framexml
+WorldStateScoreButton4Column5Icon	table	framexml
+WorldStateScoreButton4Column5Text	table	framexml
+WorldStateScoreButton4Column6Icon	table	framexml
+WorldStateScoreButton4Column6Text	table	framexml
+WorldStateScoreButton4Column7Icon	table	framexml
+WorldStateScoreButton4Column7Text	table	framexml
+WorldStateScoreButton4Deaths	table	framexml
+WorldStateScoreButton4FactionLeft	table	framexml
+WorldStateScoreButton4FactionRight	table	framexml
+WorldStateScoreButton4HonorGained	table	framexml
+WorldStateScoreButton4HonorableKills	table	framexml
+WorldStateScoreButton4KillingBlows	table	framexml
+WorldStateScoreButton4NameButton	table	framexml
+WorldStateScoreButton4NameButtonName	table	framexml
+WorldStateScoreButton4RankButton	table	framexml
+WorldStateScoreButton4RankButtonIcon	table	framexml
+WorldStateScoreButton5	table	framexml
+WorldStateScoreButton5Column1Icon	table	framexml
+WorldStateScoreButton5Column1Text	table	framexml
+WorldStateScoreButton5Column2Icon	table	framexml
+WorldStateScoreButton5Column2Text	table	framexml
+WorldStateScoreButton5Column3Icon	table	framexml
+WorldStateScoreButton5Column3Text	table	framexml
+WorldStateScoreButton5Column4Icon	table	framexml
+WorldStateScoreButton5Column4Text	table	framexml
+WorldStateScoreButton5Column5Icon	table	framexml
+WorldStateScoreButton5Column5Text	table	framexml
+WorldStateScoreButton5Column6Icon	table	framexml
+WorldStateScoreButton5Column6Text	table	framexml
+WorldStateScoreButton5Column7Icon	table	framexml
+WorldStateScoreButton5Column7Text	table	framexml
+WorldStateScoreButton5Deaths	table	framexml
+WorldStateScoreButton5FactionLeft	table	framexml
+WorldStateScoreButton5FactionRight	table	framexml
+WorldStateScoreButton5HonorGained	table	framexml
+WorldStateScoreButton5HonorableKills	table	framexml
+WorldStateScoreButton5KillingBlows	table	framexml
+WorldStateScoreButton5NameButton	table	framexml
+WorldStateScoreButton5NameButtonName	table	framexml
+WorldStateScoreButton5RankButton	table	framexml
+WorldStateScoreButton5RankButtonIcon	table	framexml
+WorldStateScoreButton6	table	framexml
+WorldStateScoreButton6Column1Icon	table	framexml
+WorldStateScoreButton6Column1Text	table	framexml
+WorldStateScoreButton6Column2Icon	table	framexml
+WorldStateScoreButton6Column2Text	table	framexml
+WorldStateScoreButton6Column3Icon	table	framexml
+WorldStateScoreButton6Column3Text	table	framexml
+WorldStateScoreButton6Column4Icon	table	framexml
+WorldStateScoreButton6Column4Text	table	framexml
+WorldStateScoreButton6Column5Icon	table	framexml
+WorldStateScoreButton6Column5Text	table	framexml
+WorldStateScoreButton6Column6Icon	table	framexml
+WorldStateScoreButton6Column6Text	table	framexml
+WorldStateScoreButton6Column7Icon	table	framexml
+WorldStateScoreButton6Column7Text	table	framexml
+WorldStateScoreButton6Deaths	table	framexml
+WorldStateScoreButton6FactionLeft	table	framexml
+WorldStateScoreButton6FactionRight	table	framexml
+WorldStateScoreButton6HonorGained	table	framexml
+WorldStateScoreButton6HonorableKills	table	framexml
+WorldStateScoreButton6KillingBlows	table	framexml
+WorldStateScoreButton6NameButton	table	framexml
+WorldStateScoreButton6NameButtonName	table	framexml
+WorldStateScoreButton6RankButton	table	framexml
+WorldStateScoreButton6RankButtonIcon	table	framexml
+WorldStateScoreButton7	table	framexml
+WorldStateScoreButton7Column1Icon	table	framexml
+WorldStateScoreButton7Column1Text	table	framexml
+WorldStateScoreButton7Column2Icon	table	framexml
+WorldStateScoreButton7Column2Text	table	framexml
+WorldStateScoreButton7Column3Icon	table	framexml
+WorldStateScoreButton7Column3Text	table	framexml
+WorldStateScoreButton7Column4Icon	table	framexml
+WorldStateScoreButton7Column4Text	table	framexml
+WorldStateScoreButton7Column5Icon	table	framexml
+WorldStateScoreButton7Column5Text	table	framexml
+WorldStateScoreButton7Column6Icon	table	framexml
+WorldStateScoreButton7Column6Text	table	framexml
+WorldStateScoreButton7Column7Icon	table	framexml
+WorldStateScoreButton7Column7Text	table	framexml
+WorldStateScoreButton7Deaths	table	framexml
+WorldStateScoreButton7FactionLeft	table	framexml
+WorldStateScoreButton7FactionRight	table	framexml
+WorldStateScoreButton7HonorGained	table	framexml
+WorldStateScoreButton7HonorableKills	table	framexml
+WorldStateScoreButton7KillingBlows	table	framexml
+WorldStateScoreButton7NameButton	table	framexml
+WorldStateScoreButton7NameButtonName	table	framexml
+WorldStateScoreButton7RankButton	table	framexml
+WorldStateScoreButton7RankButtonIcon	table	framexml
+WorldStateScoreButton8	table	framexml
+WorldStateScoreButton8Column1Icon	table	framexml
+WorldStateScoreButton8Column1Text	table	framexml
+WorldStateScoreButton8Column2Icon	table	framexml
+WorldStateScoreButton8Column2Text	table	framexml
+WorldStateScoreButton8Column3Icon	table	framexml
+WorldStateScoreButton8Column3Text	table	framexml
+WorldStateScoreButton8Column4Icon	table	framexml
+WorldStateScoreButton8Column4Text	table	framexml
+WorldStateScoreButton8Column5Icon	table	framexml
+WorldStateScoreButton8Column5Text	table	framexml
+WorldStateScoreButton8Column6Icon	table	framexml
+WorldStateScoreButton8Column6Text	table	framexml
+WorldStateScoreButton8Column7Icon	table	framexml
+WorldStateScoreButton8Column7Text	table	framexml
+WorldStateScoreButton8Deaths	table	framexml
+WorldStateScoreButton8FactionLeft	table	framexml
+WorldStateScoreButton8FactionRight	table	framexml
+WorldStateScoreButton8HonorGained	table	framexml
+WorldStateScoreButton8HonorableKills	table	framexml
+WorldStateScoreButton8KillingBlows	table	framexml
+WorldStateScoreButton8NameButton	table	framexml
+WorldStateScoreButton8NameButtonName	table	framexml
+WorldStateScoreButton8RankButton	table	framexml
+WorldStateScoreButton8RankButtonIcon	table	framexml
+WorldStateScoreButton9	table	framexml
+WorldStateScoreButton9Column1Icon	table	framexml
+WorldStateScoreButton9Column1Text	table	framexml
+WorldStateScoreButton9Column2Icon	table	framexml
+WorldStateScoreButton9Column2Text	table	framexml
+WorldStateScoreButton9Column3Icon	table	framexml
+WorldStateScoreButton9Column3Text	table	framexml
+WorldStateScoreButton9Column4Icon	table	framexml
+WorldStateScoreButton9Column4Text	table	framexml
+WorldStateScoreButton9Column5Icon	table	framexml
+WorldStateScoreButton9Column5Text	table	framexml
+WorldStateScoreButton9Column6Icon	table	framexml
+WorldStateScoreButton9Column6Text	table	framexml
+WorldStateScoreButton9Column7Icon	table	framexml
+WorldStateScoreButton9Column7Text	table	framexml
+WorldStateScoreButton9Deaths	table	framexml
+WorldStateScoreButton9FactionLeft	table	framexml
+WorldStateScoreButton9FactionRight	table	framexml
+WorldStateScoreButton9HonorGained	table	framexml
+WorldStateScoreButton9HonorableKills	table	framexml
+WorldStateScoreButton9KillingBlows	table	framexml
+WorldStateScoreButton9NameButton	table	framexml
+WorldStateScoreButton9NameButtonName	table	framexml
+WorldStateScoreButton9RankButton	table	framexml
+WorldStateScoreButton9RankButtonIcon	table	framexml
+WorldStateScoreColumn1	table	framexml
+WorldStateScoreColumn1Text	table	framexml
+WorldStateScoreColumn2	table	framexml
+WorldStateScoreColumn2Text	table	framexml
+WorldStateScoreColumn3	table	framexml
+WorldStateScoreColumn3Text	table	framexml
+WorldStateScoreColumn4	table	framexml
+WorldStateScoreColumn4Text	table	framexml
+WorldStateScoreColumn5	table	framexml
+WorldStateScoreColumn5Text	table	framexml
+WorldStateScoreColumn6	table	framexml
+WorldStateScoreColumn6Text	table	framexml
+WorldStateScoreColumn7	table	framexml
+WorldStateScoreColumn7Text	table	framexml
+WorldStateScoreColumnTemplate	lod	framexml
+WorldStateScoreFrame	table	framexml
+WorldStateScoreFrameBottom	table	framexml
+WorldStateScoreFrameBottomLeft	table	framexml
+WorldStateScoreFrameBottomRight	table	framexml
+WorldStateScoreFrameCloseButton	table	framexml
+WorldStateScoreFrameDeaths	table	framexml
+WorldStateScoreFrameDeathsText	table	framexml
+WorldStateScoreFrameHK	table	framexml
+WorldStateScoreFrameHKText	table	framexml
+WorldStateScoreFrameHonorGained	table	framexml
+WorldStateScoreFrameHonorGainedText	table	framexml
+WorldStateScoreFrameKB	table	framexml
+WorldStateScoreFrameKBText	table	framexml
+WorldStateScoreFrameLabel	table	framexml
+WorldStateScoreFrameLeaveButton	table	framexml
+WorldStateScoreFrameLeaveButtonText	table	framexml
+WorldStateScoreFrameName	table	framexml
+WorldStateScoreFrameTab1	table	framexml
+WorldStateScoreFrameTab1HighlightTexture	table	framexml
+WorldStateScoreFrameTab1Left	table	framexml
+WorldStateScoreFrameTab1LeftDisabled	table	framexml
+WorldStateScoreFrameTab1Middle	table	framexml
+WorldStateScoreFrameTab1MiddleDisabled	table	framexml
+WorldStateScoreFrameTab1Right	table	framexml
+WorldStateScoreFrameTab1RightDisabled	table	framexml
+WorldStateScoreFrameTab1Text	table	framexml
+WorldStateScoreFrameTab2	table	framexml
+WorldStateScoreFrameTab2HighlightTexture	table	framexml
+WorldStateScoreFrameTab2Left	table	framexml
+WorldStateScoreFrameTab2LeftDisabled	table	framexml
+WorldStateScoreFrameTab2Middle	table	framexml
+WorldStateScoreFrameTab2MiddleDisabled	table	framexml
+WorldStateScoreFrameTab2Right	table	framexml
+WorldStateScoreFrameTab2RightDisabled	table	framexml
+WorldStateScoreFrameTab2Text	table	framexml
+WorldStateScoreFrameTab3	table	framexml
+WorldStateScoreFrameTab3HighlightTexture	table	framexml
+WorldStateScoreFrameTab3Left	table	framexml
+WorldStateScoreFrameTab3LeftDisabled	table	framexml
+WorldStateScoreFrameTab3Middle	table	framexml
+WorldStateScoreFrameTab3MiddleDisabled	table	framexml
+WorldStateScoreFrameTab3Right	table	framexml
+WorldStateScoreFrameTab3RightDisabled	table	framexml
+WorldStateScoreFrameTab3Text	table	framexml
+WorldStateScoreFrameTabButtonTemplate	lod	framexml
+WorldStateScoreFrameTab_OnClick	function	framexml
+WorldStateScoreFrameTimer	table	framexml
+WorldStateScoreFrameTimerLabel	table	framexml
+WorldStateScoreFrameTop	table	framexml
+WorldStateScoreFrameTopBackground	table	framexml
+WorldStateScoreFrameTopLeft	table	framexml
+WorldStateScoreFrameTopRight	table	framexml
+WorldStateScoreFrame_OnLoad	function	framexml
+WorldStateScoreFrame_Resize	function	framexml
+WorldStateScoreFrame_Update	function	framexml
+WorldStateScorePlayerCount	table	framexml
+WorldStateScoreScrollFrame	table	framexml
+WorldStateScoreScrollFrameScrollBar	table	framexml
+WorldStateScoreScrollFrameScrollBarScrollDownButton	table	framexml
+WorldStateScoreScrollFrameScrollBarScrollUpButton	table	framexml
+WorldStateScoreScrollFrameScrollBarThumbTexture	table	framexml
+WorldStateScoreScrollFrameScrollBarTop	table	framexml
+WorldStateScoreScrollFrameScrollChildFrame	table	framexml
+WorldStateScoreTemplate	lod	framexml
+WorldStateScoreWinnerFrame	table	framexml
+WorldStateScoreWinnerFrameLeft	table	framexml
+WorldStateScoreWinnerFrameRight	table	framexml
+WorldStateScoreWinnerFrameText	table	framexml
+XP	string	framexml
+XPBAR_LABEL	string	framexml
+YELL_MESSAGE	string	framexml
+YES	string	framexml
+YOU	string	framexml
+YOUR_BID	string	framexml
+YOU_LOOT_MONEY	string	framexml
+ZONE	string	framexml
+ZONE_COLON	string	framexml
+ZONE_UNDER_ATTACK	string	framexml
+ZOOM_IN	string	framexml
+ZOOM_OUT	string	framexml
+ZOOM_OUT_BUTTON_TEXT	string	framexml
+ZoneFadeInDuration	number	framexml
+ZoneFadeOutDuration	number	framexml
+ZoneHoldDuration	number	framexml
+ZoneTextFont	table	framexml
+ZoneTextFrame	table	framexml
+ZoneTextString	table	framexml
+_ERRORMESSAGE	function	framexml
+__framescript_meta	table	engine
+__pow	function	engine
+a	lod	framexml
+ability	lod	framexml
+abilityName	lod	framexml
+abilitySubText	lod	framexml
+abilityType	lod	framexml
+abs	function	engine
+acos	function	engine
+actionButtonType	lod	framexml
+allButtonsHidden	lod	framexml
+alpha	lod	framexml
+alwaysUpShown	lod	framexml
+anchor	lod	framexml
+anchorFrame	lod	framexml
+anchorPoint	lod	framexml
+anchorTo	lod	framexml
+anchorY	lod	framexml
+append	lod	framexml
+area	lod	framexml
+arg1	number	framexml
+arg3	lod	framexml
+arg4	lod	framexml
+armorReduction	lod	framexml
+asin	function	engine
+assert	function	lua
+atWarIndicator	lod	framexml
+atWarWith	lod	framexml
+atan	function	engine
+atan2	function	engine
+auction	lod	framexml
+avgWidth	lod	framexml
+b	lod	framexml
+background	lod	framexml
+bagTextureSuffix	lod	framexml
+bagsOpen	lod	framexml
+bagsVisible	lod	framexml
+bar	lod	framexml
+barMax	lod	framexml
+barMin	lod	framexml
+barValue	lod	framexml
+base	lod	framexml
+battlefieldPOI	lod	framexml
+bgTextureCount	lod	framexml
+bgTextureMiddle	lod	framexml
+bidAmount	lod	framexml
+bidAmountMoneyFrame	lod	framexml
+binding1	lod	framexml
+binding2	lod	framexml
+bit	table	engine
+blocked	lod	framexml
+body	lod	framexml
+bottom	lod	framexml
+bottomEither	lod	framexml
+bottomOffset	lod	framexml
+bottomleft	lod	framexml
+bottomright	lod	framexml
+buff	lod	framexml
+bullet	lod	framexml
+bulletIndex	lod	framexml
+bulletTitle1	lod	framexml
+bulletTitle2	lod	framexml
+bullets1	lod	framexml
+bullets2	lod	framexml
+button	table	framexml
+button1	lod	framexml
+button2	lod	framexml
+button2Text	lod	framexml
+buttonClass	lod	framexml
+buttonDeaths	lod	framexml
+buttonFactionLeft	lod	framexml
+buttonFactionRight	lod	framexml
+buttonHighlight	lod	framexml
+buttonHonorGained	lod	framexml
+buttonIcon	lod	framexml
+buttonKillingBlows	lod	framexml
+buttonKills	lod	framexml
+buttonLevel	lod	framexml
+buttonName	lod	framexml
+buttonOnClickFunc	lod	framexml
+buttonRank	lod	framexml
+buttonStatus	lod	framexml
+buttonText	lod	framexml
+buyMode	lod	framexml
+buybackButton	lod	framexml
+buybackIsUsable	lod	framexml
+buybackName	lod	framexml
+buybackNumAvailable	lod	framexml
+buybackPrice	lod	framexml
+buybackQuantity	lod	framexml
+buybackTexture	lod	framexml
+buyoutMoneyFrame	lod	framexml
+buyoutPrice	lod	framexml
+buyoutText	lod	framexml
+canBuyout	lod	framexml
+canCoop	lod	framexml
+canPickup	lod	framexml
+canToggleAtWar	lod	framexml
+canUse	lod	framexml
+cancels	lod	framexml
+candidate	lod	framexml
+captureBar	lod	framexml
+castingBarPosition	lod	framexml
+categoryCount	lod	framexml
+ceil	function	engine
+centerInfo	lod	framexml
+changed	lod	framexml
+channelName	lod	framexml
+chatFrame	lod	framexml
+chatGroup	lod	framexml
+chatOffset	lod	framexml
+chatTab	lod	framexml
+chatTabWidth	lod	framexml
+chatTypeInfo	lod	framexml
+check	lod	framexml
+checkButton	lod	framexml
+checkImage	lod	framexml
+checkRelic	lod	framexml
+checkbox	lod	framexml
+checked	lod	framexml
+checks	lod	framexml
+checksRequired	lod	framexml
+childWindow	lod	framexml
+class	lod	framexml
+classStatText	lod	framexml
+closed	lod	framexml
+cmdString	lod	framexml
+collapse	lod	framexml
+collectgarbage	function	lua
+color	lod	framexml
+colorBits	lod	framexml
+column	lod	framexml
+columnButton	lod	framexml
+columnButtonIcon	lod	framexml
+columnButtonText	lod	framexml
+columnData	lod	framexml
+columnTable	lod	framexml
+columnTextButton	lod	framexml
+comboPointHighlight	lod	framexml
+comboPointShine	lod	framexml
+command	lod	framexml
+commandName	lod	framexml
+connected	lod	framexml
+containerScale	lod	framexml
+containerShowing	lod	framexml
+contribution	lod	framexml
+cooldown	table	framexml
+copper	lod	framexml
+corpseX	lod	framexml
+corpseY	lod	framexml
+cos	function	engine
+cost	lod	framexml
+count	lod	framexml
+countString	lod	framexml
+counter	lod	framexml
+cpCost1	lod	framexml
+cpCost2	lod	framexml
+craftButton	lod	framexml
+craftButtonCost	lod	framexml
+craftButtonSubText	lod	framexml
+craftButtonText	lod	framexml
+craftIndex	lod	framexml
+craftName	lod	framexml
+craftSubSpellName	lod	framexml
+craftType	lod	framexml
+creatable	lod	framexml
+create	lod	framexml
+creator	lod	framexml
+currentChatFrame	lod	framexml
+currentPage	lod	framexml
+cursorMoney	lod	framexml
+cursorX	lod	framexml
+cursorY	lod	framexml
+d	lod	framexml
+dX	lod	framexml
+dY	lod	framexml
+damageTooltip	lod	framexml
+dashIndex	lod	framexml
+data	lod	framexml
+date	function	engine
+day	lod	framexml
+daysLeft	lod	framexml
+deaths	lod	framexml
+debuff	lod	framexml
+debuffColor	lod	framexml
+debuffCount	lod	framexml
+debuffFrame	lod	framexml
+debuffFrameSize	lod	framexml
+debuffSize	lod	framexml
+debuffStack	lod	framexml
+debuffTotal	lod	framexml
+debuffType	lod	framexml
+debuffWrap	lod	framexml
+debugbreak	function	engine
+debugdump	function	engine
+debuginfo	function	engine
+debugload	function	engine
+debugprint	function	engine
+debugprofilestart	function	engine
+debugprofilestop	function	engine
+debugstack	function	engine
+debugtimestamp	function	engine
+deg	function	engine
+delayText	lod	framexml
+depthBits	lod	framexml
+description	lod	framexml
+desiredHeight	lod	framexml
+dialog	lod	framexml
+displayType	lod	framexml
+displayedPrice	lod	framexml
+displayedText	lod	framexml
+dk	lod	framexml
+doToggle	lod	framexml
+dockRegion	lod	framexml
+dockWidth	lod	framexml
+dontHide	lod	framexml
+dotString	lod	framexml
+down	lod	framexml
+dropDownFrame	lod	framexml
+dropDownList	lod	framexml
+dropdown	lod	framexml
+dropdownLevel	lod	framexml
+durabilityOffset	lod	framexml
+duration	number	framexml
+dx	lod	framexml
+dy	lod	framexml
+dynamicIcon	lod	framexml
+dynamicTooltip	lod	framexml
+editbox	lod	framexml
+effectiveStat	lod	framexml
+elapsed	lod	framexml
+elapsedTime	number	framexml
+emptyKeyRingSlot	lod	framexml
+enable	number	framexml
+enchantButton	lod	framexml
+enchantIndex	lod	framexml
+end	lod	framexml
+endText	lod	framexml
+endX	lod	framexml
+endY	lod	framexml
+error	function	lua
+estimatedWaitTime	lod	framexml
+exclusive	lod	framexml
+exhaustionCountdown	lod	framexml
+exhaustionStateID	lod	framexml
+exhaustionStateMultiplier	lod	framexml
+exhaustionStateName	lod	framexml
+exp	function	engine
+expireTime	lod	framexml
+extendedUI	lod	framexml
+extendedUIShown	lod	framexml
+extendedUIState1	lod	framexml
+extendedUIState2	lod	framexml
+extendedUIState3	lod	framexml
+faction	lod	framexml
+factionBar	lod	framexml
+factionCheck	lod	framexml
+factionHeader	lod	framexml
+factionIndex	lod	framexml
+factionName	lod	framexml
+factionStanding	lod	framexml
+fadeInfo	lod	framexml
+family	lod	framexml
+file	lod	framexml
+fileName	lod	framexml
+finished	lod	framexml
+fixedWidth	lod	framexml
+flagFrame	lod	framexml
+flagTexture	lod	framexml
+flagToken	lod	framexml
+flagX	lod	framexml
+flagY	lod	framexml
+flash	lod	framexml
+flashTexture	lod	framexml
+flashTimer	lod	framexml
+floor	function	engine
+fontHeight	lod	framexml
+fontSize	lod	framexml
+forceDesaturated	lod	framexml
+foreach	function	engine
+foreachi	function	engine
+format	function	engine
+found	lod	framexml
+frame	lod	framexml
+frameDynamicButton	lod	framexml
+frameDynamicIcon	lod	framexml
+frameFlash	lod	framexml
+frameIcon	lod	framexml
+frameText	lod	framexml
+freeScreenHeight	lod	framexml
+frexp	function	engine
+friendButton	lod	framexml
+friendIndex	lod	framexml
+g	lod	framexml
+gcinfo	function	lua
+geterrorhandler	function	engine
+getfenv	function	lua
+getglobal	function	engine
+getmetatable	function	lua
+getn	function	engine
+getvalue	lod	framexml
+group	lod	framexml
+groupID	lod	framexml
+gsub	function	engine
+guild	lod	framexml
+guildIndex	lod	framexml
+guildInfoText	lod	framexml
+guildMOTD	lod	framexml
+guildName	lod	framexml
+h	lod	framexml
+hasAttachments	lod	framexml
+hasBottomLeft	lod	framexml
+hasBottomRight	lod	framexml
+hasEditBox	lod	framexml
+hasEnchant	lod	framexml
+hasItem	lod	framexml
+hasMoneyFrame	lod	framexml
+hasPetBar	lod	framexml
+hasReq	lod	framexml
+hasScrollBar	lod	framexml
+hasText	lod	framexml
+hasWideEditBox	lod	framexml
+height	lod	framexml
+hideAnyDockTabs	lod	framexml
+hideOnEscape	lod	framexml
+highBidder	lod	framexml
+highestRank	lod	framexml
+hk	lod	framexml
+honorGained	lod	framexml
+honorGainedAnchorFrame	lod	framexml
+honorableKills	lod	framexml
+hour	lod	framexml
+hours	lod	framexml
+i	lod	framexml
+icon	table	framexml
+iconTexture	lod	framexml
+iconWidth	lod	framexml
+id	lod	framexml
+ignoreButton	lod	framexml
+ignoreIndex	lod	framexml
+ignoreUp	lod	framexml
+inParty	lod	framexml
+inQueue	lod	framexml
+index	lod	framexml
+indexToSelect	lod	framexml
+info	lod	framexml
+infoText	lod	framexml
+instanceID	lod	framexml
+instanceName	lod	framexml
+instanceReset	lod	framexml
+interruptCinematic	lod	framexml
+invType	lod	framexml
+ipairs	function	lua
+isActive	number	framexml
+isAssistant	lod	framexml
+isCastable	number	framexml
+isCollapsed	lod	framexml
+isComplete	lod	framexml
+isDead	lod	framexml
+isExceptional	lod	framexml
+isExpanded	lod	framexml
+isGM	lod	framexml
+isHeader	lod	framexml
+isInQuestLog	lod	framexml
+isLast	lod	framexml
+isLastSlotEmpty	lod	framexml
+isLeader	lod	framexml
+isLearnSpell	lod	framexml
+isLearnable	lod	framexml
+isLocal	lod	framexml
+isPetLearnSpell	lod	framexml
+isPlusTwoBag	lod	framexml
+isQuestLog	lod	framexml
+isStaggered	lod	framexml
+isTradeskillSpell	lod	framexml
+isUsable	lod	framexml
+isVisible	lod	framexml
+isWatched	lod	framexml
+item	lod	framexml
+itemButton	lod	framexml
+itemCount	lod	framexml
+itemName	lod	framexml
+j	lod	framexml
+keyBindingButton1	lod	framexml
+keyBindingButton1NormalTexture	lod	framexml
+keyBindingButton1PushedTexture	lod	framexml
+keyBindingButton2	lod	framexml
+keyBindingButton2NormalTexture	lod	framexml
+keyBindingButton2PushedTexture	lod	framexml
+keyBindingDescription	lod	framexml
+keyOffset	lod	framexml
+keyPressed	lod	framexml
+killingBlows	lod	framexml
+label	lod	framexml
+lastButtonShown	lod	framexml
+lastOnline	lod	framexml
+ldexp	function	engine
+leader	lod	framexml
+left	lod	framexml
+leftInfo	lod	framexml
+leftOffset	lod	framexml
+level	number	framexml
+line	lod	framexml
+loadstring	function	lua
+localizedName	lod	framexml
+locked	lod	framexml
+log	function	engine
+log10	function	engine
+lootMaster	lod	framexml
+lootMethod	lod	framexml
+lowestIndex	lod	framexml
+lowestMessage	lod	framexml
+lowestTimer	lod	framexml
+loyalty	lod	framexml
+m	lod	framexml
+macroButton	lod	framexml
+macroIcon	lod	framexml
+macroName	lod	framexml
+macroPopupButton	lod	framexml
+macroPopupIcon	lod	framexml
+mainHandExpiration	lod	framexml
+mapFileName	lod	framexml
+mapName	lod	framexml
+mapPiece	lod	framexml
+mapPointX	lod	framexml
+mapPointY	lod	framexml
+masterName	lod	framexml
+masterVolume	lod	framexml
+material	lod	framexml
+math	table	lua
+max	function	framexml
+maxAnisotropy	lod	framexml
+maxDamage	lod	framexml
+maxLetters	lod	framexml
+maxOffHandDamage	lod	framexml
+maxPages	lod	framexml
+maxRank	lod	framexml
+maxStack	lod	framexml
+maxWidth	lod	framexml
+maxx	lod	framexml
+meetsPrereq	lod	framexml
+memberText	lod	framexml
+menu	lod	framexml
+menusVisible	lod	framexml
+message	function	framexml
+messageGroup	lod	framexml
+messageType	lod	framexml
+middleBgHeight	lod	framexml
+min	function	framexml
+minBid	lod	framexml
+minDamage	lod	framexml
+minIncrement	lod	framexml
+minLevel	lod	framexml
+minOffHandDamage	lod	framexml
+minx	lod	framexml
+mod	function	engine
+modKeys	lod	framexml
+mode	lod	framexml
+money	lod	framexml
+moneyCost	lod	framexml
+moneyFrame	lod	framexml
+month	lod	framexml
+msg	lod	framexml
+multiSample	lod	framexml
+multiple	lod	framexml
+name	string	framexml
+nameButton	lod	framexml
+nameLocationText	lod	framexml
+nameText	lod	framexml
+neededTextures	lod	framexml
+negBuff	lod	framexml
+negative	lod	framexml
+newAnchorX	lod	framexml
+newAnchorY	lod	framexml
+newLevel	lod	framexml
+newLineString	lod	framexml
+next	function	lua
+nextPage	lod	framexml
+node	lod	framexml
+none	lod	framexml
+normalText	lod	framexml
+notClosableByLogout	lod	framexml
+notExpanded	lod	framexml
+note	lod	framexml
+num2	lod	framexml
+numAlerts	lod	framexml
+numAlliance	lod	framexml
+numAvailable	lod	framexml
+numBatchAuctions	lod	framexml
+numBuffs	lod	framexml
+numDebuffs	lod	framexml
+numFriends	lod	framexml
+numHeaders	lod	framexml
+numHorde	lod	framexml
+numInStock	lod	framexml
+numItems	lod	framexml
+numLines	lod	framexml
+numLootToShow	lod	framexml
+numMacros	lod	framexml
+numObjectives	lod	framexml
+numPartyMembers	lod	framexml
+numPulloutEntries	lod	framexml
+numQuestChoices	lod	framexml
+numQuestRewards	lod	framexml
+numQuestSpellRewards	lod	framexml
+numQueued	lod	framexml
+numSingleHops	lod	framexml
+numSpells	lod	framexml
+numSubs	lod	framexml
+numTexturesTall	lod	framexml
+numTexturesWide	lod	framexml
+numberQueues	lod	framexml
+objectivesCompleted	lod	framexml
+offHandExpiration	lod	framexml
+offhandDamageTooltip	lod	framexml
+officernote	lod	framexml
+offscreenPadding	lod	framexml
+offscreenX	lod	framexml
+offscreenY	lod	framexml
+offset	lod	framexml
+offsetX	lod	framexml
+offsetY	lod	framexml
+onHide	lod	framexml
+online	lod	framexml
+onlinecount	lod	framexml
+opacity	lod	framexml
+overtime	lod	framexml
+owner	lod	framexml
+packageIcon	lod	framexml
+pairs	function	lua
+partyFrame	lod	framexml
+partyMemberFrame	lod	framexml
+partyMemberOnQuest	lod	framexml
+partyMembersOnQuest	lod	framexml
+partyX	lod	framexml
+partyY	lod	framexml
+pcall	function	lua
+percent	lod	framexml
+petActionButton	lod	framexml
+petActionIcon	lod	framexml
+petAutoCastModel	table	framexml
+petAutoCastableTexture	table	framexml
+pflag	lod	framexml
+physicalBonusNeg	lod	framexml
+physicalBonusPos	lod	framexml
+playerCount	lod	framexml
+playerReagentCount	lod	framexml
+playerX	lod	framexml
+playerY	lod	framexml
+pm	lod	framexml
+point	lod	framexml
+pointsSpent	lod	framexml
+posBuff	lod	framexml
+positive	lod	framexml
+prefix	lod	framexml
+prevPage	lod	framexml
+previousDockedFrame	lod	framexml
+price	lod	framexml
+pullOutFrame	lod	framexml
+pulloutButton	lod	framexml
+pulloutButtonName	lod	framexml
+pulloutHealthBar	lod	framexml
+pulloutManaBar	lod	framexml
+quality	lod	framexml
+quantity	lod	framexml
+questCheck	lod	framexml
+questDescription	lod	framexml
+questHighlight	lod	framexml
+questIndex	lod	framexml
+questItem	lod	framexml
+questLogTitle	lod	framexml
+questLogTitleText	lod	framexml
+questNormalText	lod	framexml
+questNumGroupMates	lod	framexml
+questObjectives	lod	framexml
+questTag	lod	framexml
+questTitle	lod	framexml
+questTitleTag	lod	framexml
+questWatchMaxWidth	lod	framexml
+questWatchTitleText	lod	framexml
+questionFrame	lod	framexml
+queueInstanceID	lod	framexml
+queueMapName	lod	framexml
+queueStatus	lod	framexml
+r	lod	framexml
+race	lod	framexml
+rad	function	engine
+radioButton	lod	framexml
+raidButton	lod	framexml
+raidGroup	lod	framexml
+raidTargetIconIndex	lod	framexml
+raidTargetIndex	lod	framexml
+random	function	engine
+randomseed	function	engine
+rank	lod	framexml
+rankCost	lod	framexml
+rankIndex	lod	framexml
+rankName	lod	framexml
+rankNumber	lod	framexml
+rawequal	function	lua
+rawget	function	lua
+rawset	function	lua
+readable	lod	framexml
+reagentToAnchorTo	lod	framexml
+refreshTime	lod	framexml
+relative	lod	framexml
+relativePoint	lod	framexml
+relativeTo	lod	framexml
+remainingRows	lod	framexml
+reputation	lod	framexml
+requiredBid	lod	framexml
+requiredLevel	lod	framexml
+requirements	lod	framexml
+requirementsMet	lod	framexml
+resistance	lod	framexml
+resistanceLevel	lod	framexml
+resolution	lod	framexml
+rewardsCount	lod	framexml
+right	lod	framexml
+rightBarTexture	lod	framexml
+rightOffset	lod	framexml
+rotationIncrement	lod	framexml
+rotationsPerSecond	lod	framexml
+rpoint	lod	framexml
+s	lod	framexml
+sX	lod	framexml
+sY	lod	framexml
+scoreButton	lod	framexml
+screenHeight	lod	framexml
+scroll	lod	framexml
+scrollBarOffset	lod	framexml
+scrollChildHeight	lod	framexml
+scrollChildX	lod	framexml
+scrollChildY	lod	framexml
+scrollFrame	lod	framexml
+scrollFrameHeight	lod	framexml
+scrollrange	lod	framexml
+seconds	lod	framexml
+selectedPet	lod	framexml
+sender	lod	framexml
+senderText	lod	framexml
+separator	lod	framexml
+server	lod	framexml
+serviceName	lod	framexml
+serviceSubText	lod	framexml
+serviceType	lod	framexml
+seterrorhandler	function	engine
+setfenv	function	lua
+setglobal	function	engine
+setmetatable	function	lua
+show	lod	framexml
+showAlert	lod	framexml
+showAllDockTabs	lod	framexml
+showDetails	lod	framexml
+showDurability	lod	framexml
+showLink	lod	framexml
+showLowerDenominations	lod	framexml
+showPlayers	lod	framexml
+showRightClickText	lod	framexml
+showScrollBar	lod	framexml
+showSell	lod	framexml
+showSmallerCoins	lod	framexml
+shown	lod	framexml
+shrinkFrames	lod	framexml
+sign	lod	framexml
+sin	function	engine
+size	lod	framexml
+skillLineTab	lod	framexml
+skillRank	lod	framexml
+skillRankFrameWidth	lod	framexml
+skillRankStart	lod	framexml
+slider	lod	framexml
+sliderValue	lod	framexml
+slot	lod	framexml
+slotTextureName	lod	framexml
+sort	function	engine
+sound	lod	framexml
+spacerFrame	lod	framexml
+spacing	lod	framexml
+sparkPosition	lod	framexml
+sqrt	function	engine
+stackCount	lod	framexml
+staggerAmount	lod	framexml
+standingID	lod	framexml
+start	number	framexml
+startX	lod	framexml
+startY	lod	framexml
+stat	lod	framexml
+state	lod	framexml
+staticPopup	lod	framexml
+stationeryIcon	lod	framexml
+status	string	framexml
+statusColor	lod	framexml
+statusText	lod	framexml
+strbyte	function	engine
+strchar	function	engine
+strfind	function	engine
+string	table	lua
+string1	lod	framexml
+string2	lod	framexml
+strlen	function	engine
+strlower	function	engine
+strrep	function	engine
+strsub	function	engine
+strupper	function	engine
+subClass	lod	framexml
+subgroup	lod	framexml
+subject	lod	framexml
+subjectText	lod	framexml
+surveyQuestion	lod	framexml
+tDeleteItem	function	framexml
+tab	lod	framexml
+tabCompleteIndex	lod	framexml
+tabFlash	lod	framexml
+tabName	lod	framexml
+tabWidth	lod	framexml
+table	table	lua
+tan	function	engine
+target	lod	framexml
+tdown	lod	framexml
+temp	string	framexml
+tempFrame	lod	framexml
+tempIndex	lod	framexml
+tempName	lod	framexml
+tempNode	lod	framexml
+tempTime	lod	framexml
+tempWidth	lod	framexml
+text	lod	framexml
+textColor	lod	framexml
+textStatusBar	lod	framexml
+textWidth	lod	framexml
+texture	string	framexml
+textureCount	lod	framexml
+textureFileHeight	lod	framexml
+textureFileWidth	lod	framexml
+textureHeight	lod	framexml
+textureIndex	lod	framexml
+textureName	lod	framexml
+texturePixelHeight	lod	framexml
+texturePixelWidth	lod	framexml
+textureWidth	lod	framexml
+textureX	lod	framexml
+textureY	lod	framexml
+this	table	engine
+ticketFrameHeight	lod	framexml
+ticketType	lod	framexml
+tier	lod	framexml
+tierUnlocked	lod	framexml
+time	function	framexml
+timeInQueue	lod	framexml
+timeleft	lod	framexml
+timeout	lod	framexml
+tinsert	function	engine
+title	lod	framexml
+titleButton	lod	framexml
+titleColor	lod	framexml
+titleIndex	lod	framexml
+titleText	lod	framexml
+token	lod	framexml
+tonumber	function	lua
+tooltip	lod	framexml
+tooltipText	lod	framexml
+top	lod	framexml
+topOffset	lod	framexml
+topleft	lod	framexml
+topright	lod	framexml
+tostring	function	lua
+totalBags	lod	framexml
+totalCopper	lod	framexml
+totalWidth	lod	framexml
+tradeItemButton	lod	framexml
+trainingPointCost	lod	framexml
+tremove	function	engine
+truncateCopper	lod	framexml
+truncateSmallCoins	lod	framexml
+tup	lod	framexml
+type	function	lua
+uiInfo	lod	framexml
+uiScale	lod	framexml
+unavailable	lod	framexml
+unit	lod	framexml
+unitButton	lod	framexml
+unitCurrHP	lod	framexml
+unitFrame	lod	framexml
+unitHPMax	number	framexml
+unitHPMin	number	framexml
+unitLevel	lod	framexml
+unitStatus	lod	framexml
+unpack	function	lua
+up	lod	framexml
+update	lod	framexml
+updateAllButtons	lod	framexml
+updateContainerFrameAnchors	function	framexml
+updateTime	lod	framexml
+value	lod	framexml
+var	lod	framexml
+variable	lod	framexml
+visibilityChanged	lod	framexml
+waitTime	lod	framexml
+wasRead	lod	framexml
+watchText	lod	framexml
+watchTextIndex	lod	framexml
+whileDead	lod	framexml
+whoIndex	lod	framexml
+width	number	framexml
+windowsVisible	lod	framexml
+worldMapPOI	lod	framexml
+x	lod	framexml
+x1	lod	framexml
+x2	lod	framexml
+xCoord1	lod	framexml
+xCoord2	lod	framexml
+xIndex	lod	framexml
+xOffset	lod	framexml
+xPos	lod	framexml
+xpcall	function	lua
+y	lod	framexml
+y1	lod	framexml
+y2	lod	framexml
+yCoord1	lod	framexml
+yCoord2	lod	framexml
+yOffset	lod	framexml
+yPos	lod	framexml
+year	lod	framexml
+yourBidText	lod	framexml
+z	lod	framexml
+zone	lod	framexml
+zoneIndex	lod	framexml
diff --git a/reference/1.12-message-catalog.tsv b/reference/1.12-message-catalog.tsv
new file mode 100644
index 00000000..1e73bb34
--- /dev/null
+++ b/reference/1.12-message-catalog.tsv
@@ -0,0 +1,470 @@
+# build 5875 CGGameUI message catalog (the 0xb4b498 table indexed by 0x496720)
+# 465 rows, ids 0x0..0x1d0; consumer bound `cmp id,0x1d1; jge` at 0x49672c
+# kind 0 -> 0x49a870(text, chan); 1 -> UI_INFO_MESSAGE 0xe1; 2 -> UI_ERROR_MESSAGE 0xe0; 3 -> console 0x63cd00
+# Vendored from the maintainer's analysis (`WOW_RE`); messages/catalog.rs is generated from it.
+id_hex	id_dec	row_va	key	kind	sound	type_tag	chan
+0x0	0	0xb4b498	ERR_INV_FULL	2	NONE	0x0	10
+0x1	1	0xb4b4ac	ERR_BANK_FULL	2	NONE	0x44	10
+0x2	2	0xb4b4c0	ERR_CANT_EQUIP_LEVEL_I	2	NONE	0x2	10
+0x3	3	0xb4b4d4	ERR_CANT_EQUIP_SKILL	2	NONE	0x29	10
+0x4	4	0xb4b4e8	ERR_CANT_EQUIP_EVER	2	NONE	0x3	10
+0x5	5	0xb4b4fc	ERR_CANT_EQUIP_RANK	2	NONE	0x44	10
+0x6	6	0xb4b510	ERR_CANT_EQUIP_REPUTATION	2	NONE	0x44	10
+0x7	7	0xb4b524	ERR_PROFICIENCY_NEEDED	2	NONE	0x30	10
+0x8	8	0xb4b538	ERR_WRONG_SLOT	2	NONE	0x1b	10
+0x9	9	0xb4b54c	ERR_BAG_FULL	2	NONE	0x1d	10
+0xa	10	0xb4b560	ERR_INTERNAL_BAG_ERROR	2	NONE	0x44	10
+0xb	11	0xb4b574	ERR_DESTROY_NONEMPTY_BAG	2	NONE	0x44	10
+0xc	12	0xb4b588	ERR_BAG_IN_BAG	2	NONE	0x1a	10
+0xd	13	0xb4b59c	ERR_TOO_MANY_SPECIAL_BAGS	2	NONE	0x44	10
+0xe	14	0xb4b5b0	ERR_TRADE_EQUIPPED_BAG	2	NONE	0x44	10
+0xf	15	0xb4b5c4	ERR_AMMO_ONLY	2	NONE	0x1c	10
+0x10	16	0xb4b5d8	ERR_NO_SLOT_AVAILABLE	2	NONE	0x44	10
+0x11	17	0xb4b5ec	ERR_WRONG_BAG_TYPE	2	NONE	0x44	10
+0x12	18	0xb4b600	ERR_ITEM_MAX_COUNT	2	NONE	0x1e	10
+0x13	19	0xb4b614	ERR_NOT_EQUIPPABLE	2	NONE	0x2c	10
+0x14	20	0xb4b628	ERR_CANT_STACK	2	NONE	0x44	10
+0x15	21	0xb4b63c	ERR_CANT_SWAP	2	NONE	0x44	10
+0x16	22	0xb4b650	ERR_SLOT_EMPTY	2	NONE	0x44	10
+0x17	23	0xb4b664	ERR_ITEM_NOT_FOUND	2	NONE	0x44	10
+0x18	24	0xb4b678	ERR_TOO_FEW_TO_SPLIT	2	NONE	0x44	10
+0x19	25	0xb4b68c	ERR_SPLIT_FAILED	2	NONE	0x44	10
+0x1a	26	0xb4b6a0	ERR_NOT_A_BAG	2	NONE	0x19	10
+0x1b	27	0xb4b6b4	ERR_NOT_OWNER	2	NONE	0x44	10
+0x1c	28	0xb4b6c8	ERR_ONLY_ONE_QUIVER	2	NONE	0x44	10
+0x1d	29	0xb4b6dc	ERR_NO_BANK_SLOT	2	NONE	0x44	10
+0x1e	30	0xb4b6f0	ERR_NO_BANK_HERE	2	NONE	0x44	10
+0x1f	31	0xb4b704	ERR_ITEM_LOCKED	2	NONE	0x3d	10
+0x20	32	0xb4b718	ERR_2HANDED_EQUIPPED	2	NONE	0x2a	10
+0x21	33	0xb4b72c	ERR_VENDOR_NOT_INTERESTED	2	NONE	0x44	10
+0x22	34	0xb4b740	ERR_VENDOR_HATES_YOU	2	NONE	0x44	10
+0x23	35	0xb4b754	ERR_VENDOR_SOLD_OUT	2	NONE	0x44	10
+0x24	36	0xb4b768	ERR_VENDOR_TOO_FAR	2	NONE	0x44	10
+0x25	37	0xb4b77c	ERR_NOT_ENOUGH_MONEY	2	NONE	0x28	10
+0x26	38	0xb4b790	ERR_RECEIVE_ITEM_S	0	ITEMGENERICSOUND	0x44	10
+0x27	39	0xb4b7a4	ERR_DROP_BOUND_ITEM	2	NONE	0x4	10
+0x28	40	0xb4b7b8	ERR_TRADE_BOUND_ITEM	2	NONE	0x3b	10
+0x29	41	0xb4b7cc	ERR_TRADE_QUEST_ITEM	2	NONE	0x3b	10
+0x2a	42	0xb4b7e0	ERR_TRADE_GROUND_ITEM	2	NONE	0x44	10
+0x2b	43	0xb4b7f4	ERR_TRADE_BAG	2	NONE	0x44	10
+0x2c	44	0xb4b808	ERR_SPELL_FAILED_S	2	NONE	0x44	10
+0x2d	45	0xb4b81c	ERR_ITEM_COOLDOWN	2	NONE	0x5	10
+0x2e	46	0xb4b830	ERR_POTION_COOLDOWN	2	NONE	0x2f	10
+0x2f	47	0xb4b844	ERR_FOOD_COOLDOWN	2	NONE	0x7	10
+0x30	48	0xb4b858	ERR_SPELL_COOLDOWN	2	NONE	0xc	10
+0x31	49	0xb4b86c	ERR_ABILITY_COOLDOWN	2	NONE	0x32	10
+0x32	50	0xb4b880	ERR_SPELL_ALREADY_KNOWN_S	2	NONE	0xd	10
+0x33	51	0xb4b894	ERR_PET_SPELL_ALREADY_KNOWN_S	2	NONE	0x44	10
+0x34	52	0xb4b8a8	ERR_PROFICIENCY_GAINED_S	0	NONE	0x44	23
+0x35	53	0xb4b8bc	ERR_SKILL_GAINED_S	0	NONE	0x44	23
+0x36	54	0xb4b8d0	ERR_SKILL_UP_SI	0	NONE	0x44	23
+0x37	55	0xb4b8e4	ERR_LEARN_SPELL_S	0	NONE	0x44	10
+0x38	56	0xb4b8f8	ERR_LEARN_ABILITY_S	0	NONE	0x44	10
+0x39	57	0xb4b90c	ERR_LEARN_RECIPE_S	0	NONE	0x44	10
+0x3a	58	0xb4b920	ERR_INVITE_PLAYER_S	0	NONE	0x44	10
+0x3b	59	0xb4b934	ERR_INVITE_SELF	2	NONE	0x44	10
+0x3c	60	0xb4b948	ERR_INVITED_TO_GROUP_S	0	NONE	0x44	10
+0x3d	61	0xb4b95c	ERR_ALREADY_IN_GROUP_S	0	NONE	0x14	10
+0x3e	62	0xb4b970	ERR_PLAYER_BUSY_S	0	NONE	0x44	10
+0x3f	63	0xb4b984	ERR_NEW_LEADER_S	0	NONE	0x44	10
+0x40	64	0xb4b998	ERR_NEW_LEADER_YOU	0	NONE	0x44	10
+0x41	65	0xb4b9ac	ERR_LEFT_GROUP_S	0	NONE	0x44	10
+0x42	66	0xb4b9c0	ERR_LEFT_GROUP_YOU	0	NONE	0x44	10
+0x43	67	0xb4b9d4	ERR_GROUP_DISBANDED	0	NONE	0x44	10
+0x44	68	0xb4b9e8	ERR_DECLINE_GROUP_S	0	igPlayerInviteDecline	0x44	10
+0x45	69	0xb4b9fc	ERR_JOINED_GROUP_S	0	NONE	0x44	10
+0x46	70	0xb4ba10	ERR_UNINVITE_YOU	0	NONE	0x44	10
+0x47	71	0xb4ba24	ERR_BAD_PLAYER_NAME_S	0	NONE	0x44	10
+0x48	72	0xb4ba38	ERR_NOT_IN_GROUP	0	NONE	0x44	10
+0x49	73	0xb4ba4c	ERR_TARGET_NOT_IN_GROUP_S	0	NONE	0x44	10
+0x4a	74	0xb4ba60	ERR_GROUP_FULL	0	NONE	0x8	10
+0x4b	75	0xb4ba74	ERR_NOT_LEADER	0	NONE	0x44	10
+0x4c	76	0xb4ba88	ERR_PLAYER_DIED_S	0	NONE	0x44	10
+0x4d	77	0xb4ba9c	ERR_GUILD_CREATE_S	0	LEVELUP	0x44	10
+0x4e	78	0xb4bab0	ERR_GUILD_INVITE_S	0	NONE	0x44	10
+0x4f	79	0xb4bac4	ERR_INVITED_TO_GUILD_SS	0	LEVELUP	0x44	10
+0x50	80	0xb4bad8	ERR_ALREADY_IN_GUILD_S	0	NONE	0x44	10
+0x51	81	0xb4baec	ERR_ALREADY_INVITED_TO_GUILD_S	0	NONE	0x44	10
+0x52	82	0xb4bb00	ERR_INVITED_TO_GUILD	0	NONE	0x44	10
+0x53	83	0xb4bb14	ERR_ALREADY_IN_GUILD	0	NONE	0x44	10
+0x54	84	0xb4bb28	ERR_GUILD_ACCEPT	0	NONE	0x44	10
+0x55	85	0xb4bb3c	ERR_GUILD_DECLINE_S	0	NONE	0x44	10
+0x56	86	0xb4bb50	ERR_GUILD_PERMISSIONS	0	NONE	0x3e	10
+0x57	87	0xb4bb64	ERR_GUILD_JOIN_S	0	NONE	0x44	10
+0x58	88	0xb4bb78	ERR_GUILD_FOUNDER_S	0	NONE	0x44	10
+0x59	89	0xb4bb8c	ERR_GUILD_PROMOTE_SSS	0	NONE	0x44	10
+0x5a	90	0xb4bba0	ERR_GUILD_DEMOTE_SSS	0	NONE	0x44	10
+0x5b	91	0xb4bbb4	ERR_GUILD_QUIT_S	0	NONE	0x44	10
+0x5c	92	0xb4bbc8	ERR_GUILD_LEAVE_S	0	NONE	0x44	10
+0x5d	93	0xb4bbdc	ERR_GUILD_REMOVE_SS	0	NONE	0x44	10
+0x5e	94	0xb4bbf0	ERR_GUILD_REMOVE_SELF	0	NONE	0x44	10
+0x5f	95	0xb4bc04	ERR_GUILD_DISBAND_S	0	NONE	0x44	10
+0x60	96	0xb4bc18	ERR_GUILD_DISBAND_SELF	0	NONE	0x44	10
+0x61	97	0xb4bc2c	ERR_GUILD_LEADER_S	0	NONE	0x44	10
+0x62	98	0xb4bc40	ERR_GUILD_LEADER_SELF	0	NONE	0x44	10
+0x63	99	0xb4bc54	ERR_GUILD_PLAYER_NOT_FOUND_S	0	NONE	0x44	10
+0x64	100	0xb4bc68	ERR_GUILD_PLAYER_NOT_IN_GUILD_S	0	NONE	0x44	10
+0x65	101	0xb4bc7c	ERR_GUILD_PLAYER_NOT_IN_GUILD	0	NONE	0x44	10
+0x66	102	0xb4bc90	ERR_GUILD_CANT_PROMOTE_S	0	NONE	0x44	10
+0x67	103	0xb4bca4	ERR_GUILD_CANT_DEMOTE_S	0	NONE	0x44	10
+0x68	104	0xb4bcb8	ERR_GUILD_NOT_IN_A_GUILD	0	NONE	0x44	10
+0x69	105	0xb4bccc	ERR_GUILD_INTERNAL	0	NONE	0x44	10
+0x6a	106	0xb4bce0	ERR_GUILD_LEADER_IS_S	0	NONE	0x44	10
+0x6b	107	0xb4bcf4	ERR_GUILD_LEADER_CHANGED_SS	0	NONE	0x44	10
+0x6c	108	0xb4bd08	ERR_GUILD_DISBANDED	0	NONE	0x44	10
+0x6d	109	0xb4bd1c	ERR_GUILD_NOT_ALLIED	0	NONE	0x44	10
+0x6e	110	0xb4bd30	ERR_GUILD_LEADER_LEAVE	0	NONE	0x44	10
+0x6f	111	0xb4bd44	ERR_GUILD_RANKS_LOCKED	0	NONE	0x44	10
+0x70	112	0xb4bd58	ERR_GUILD_RANK_IN_USE	0	NONE	0x44	10
+0x71	113	0xb4bd6c	ERR_GUILD_RANK_TOO_HIGH_S	0	NONE	0x44	10
+0x72	114	0xb4bd80	ERR_GUILD_RANK_TOO_LOW_S	0	NONE	0x44	10
+0x73	115	0xb4bd94	ERR_GUILD_NAME_INVALID	2	NONE	0x44	10
+0x74	116	0xb4bda8	ERR_GUILD_NAME_EXISTS_S	2	NONE	0x44	10
+0x75	117	0xb4bdbc	ERR_GUILD_ENTER_NAME	2	NONE	0x44	10
+0x76	118	0xb4bdd0	ERR_GUILD_NAME_TOO_SHORT	2	NONE	0x44	10
+0x77	119	0xb4bde4	ERR_GUILD_NAME_MIXED_LANGUAGES	2	NONE	0x44	10
+0x78	120	0xb4bdf8	ERR_GUILD_NAME_PROFANE	2	NONE	0x44	10
+0x79	121	0xb4be0c	ERR_GUILD_NAME_RESERVED	2	NONE	0x44	10
+0x7a	122	0xb4be20	ERR_GUILD_NAME_INVALID_SPACE	2	NONE	0x44	10
+0x7b	123	0xb4be34	ERR_GUILD_NAME_NAME_CONSECUTIVE_SPACES	2	NONE	0x44	10
+0x7c	124	0xb4be48	ERR_NO_GUILD_CHARTER	2	NONE	0x44	10
+0x7d	125	0xb4be5c	ERR_OUT_OF_RANGE	2	NONE	0xa	10
+0x7e	126	0xb4be70	ERR_PLAYER_DEAD	2	NONE	0x44	10
+0x7f	127	0xb4be84	ERR_CLIENT_LOCKED_OUT	2	NONE	0x44	10
+0x80	128	0xb4be98	ERR_KILLED_BY_S	0	NONE	0x44	10
+0x81	129	0xb4beac	ERR_LOOT_LOCKED	2	NONE	0x21	10
+0x82	130	0xb4bec0	ERR_LOOT_TOO_FAR	2	NONE	0x23	10
+0x83	131	0xb4bed4	ERR_LOOT_DIDNT_KILL	2	NONE	0x1f	10
+0x84	132	0xb4bee8	ERR_LOOT_BAD_FACING	2	NONE	0x20	10
+0x85	133	0xb4befc	ERR_LOOT_NOTSTANDING	2	NONE	0x44	10
+0x86	134	0xb4bf10	ERR_LOOT_STUNNED	2	NONE	0x44	10
+0x87	135	0xb4bf24	ERR_LOOT_NO_UI	2	NONE	0x44	10
+0x88	136	0xb4bf38	ERR_LOOT_WHILE_INVULNERABLE	2	NONE	0x44	10
+0x89	137	0xb4bf4c	ERR_QUEST_ACCEPTED_S	0	QUESTADDED	0x44	10
+0x8a	138	0xb4bf60	ERR_QUEST_COMPLETE_S	0	igQuestListComplete	0x44	10
+0x8b	139	0xb4bf74	ERR_QUEST_FAILED_S	0	igQuestFailed	0x44	10
+0x8c	140	0xb4bf88	ERR_QUEST_FAILED_BAG_FULL_S	0	igQuestFailed	0x44	10
+0x8d	141	0xb4bf9c	ERR_QUEST_FAILED_MAX_COUNT_S	0	igQuestFailed	0x44	10
+0x8e	142	0xb4bfb0	ERR_QUEST_FAILED_LOW_LEVEL	0	igQuestFailed	0x44	10
+0x8f	143	0xb4bfc4	ERR_QUEST_FAILED_MISSING_ITEMS	0	igQuestFailed	0x44	10
+0x90	144	0xb4bfd8	ERR_QUEST_FAILED_WRONG_RACE	0	igQuestFailed	0x44	10
+0x91	145	0xb4bfec	ERR_QUEST_FAILED_NOT_ENOUGH_MONEY	0	igQuestFailed	0x44	10
+0x92	146	0xb4c000	ERR_QUEST_ONLY_ONE_TIMED	0	igQuestFailed	0x44	10
+0x93	147	0xb4c014	ERR_QUEST_NEED_PREREQS	0	igQuestFailed	0x44	10
+0x94	148	0xb4c028	ERR_QUEST_ALREADY_ON	0	igQuestFailed	0x44	10
+0x95	149	0xb4c03c	ERR_QUEST_REWARD_EXP_I	0	NONE	0x44	10
+0x96	150	0xb4c050	ERR_QUEST_REWARD_ITEM_S	0	NONE	0x44	10
+0x97	151	0xb4c064	ERR_QUEST_REWARD_MONEY_S	0	NONE	0x44	10
+0x98	152	0xb4c078	ERR_QUEST_MUST_CHOOSE	2	igQuestFailed	0x44	10
+0x99	153	0xb4c08c	ERR_QUEST_LOG_FULL	2	igQuestFailed	0x44	10
+0x9a	154	0xb4c0a0	ERR_COMBAT_DAMAGE_SSI	0	NONE	0x44	10
+0x9b	155	0xb4c0b4	ERR_INSPECT_S	0	NONE	0x44	10
+0x9c	156	0xb4c0c8	ERR_CANT_USE_ITEM	2	NONE	0x33	10
+0x9d	157	0xb4c0dc	ERR_MUST_EQUIP_ITEM	2	NONE	0x31	10
+0x9e	158	0xb4c0f0	ERR_PASSIVE_ABILITY	2	NONE	0x44	10
+0x9f	159	0xb4c104	ERR_2HSKILLNOTFOUND	2	NONE	0x44	10
+0xa0	160	0xb4c118	ERR_NO_ATTACK_TARGET	2	NONE	0x26	10
+0xa1	161	0xb4c12c	ERR_INVALID_ATTACK_TARGET	2	NONE	0xb	10
+0xa2	162	0xb4c140	ERR_ATTACK_STUNNED	2	NONE	0x44	10
+0xa3	163	0xb4c154	ERR_ATTACK_PACIFIED	2	NONE	0x44	10
+0xa4	164	0xb4c168	ERR_ATTACK_MOUNTED	2	NONE	0x44	10
+0xa5	165	0xb4c17c	ERR_ATTACK_FLEEING	2	NONE	0x44	10
+0xa6	166	0xb4c190	ERR_ATTACK_CONFUSED	2	NONE	0x44	10
+0xa7	167	0xb4c1a4	ERR_ATTACK_CHARMED	2	NONE	0x44	10
+0xa8	168	0xb4c1b8	ERR_ATTACK_DEAD	2	NONE	0x44	10
+0xa9	169	0xb4c1cc	ERR_ATTACK_PREVENTED_BY_MECHANIC_S	2	NONE	0x44	10
+0xaa	170	0xb4c1e0	ERR_TAXISAMENODE	2	NONE	0x44	10
+0xab	171	0xb4c1f4	ERR_TAXINOSUCHPATH	1	NONE	0x44	10
+0xac	172	0xb4c208	ERR_TAXIUNSPECIFIEDSERVERERROR	2	NONE	0x44	10
+0xad	173	0xb4c21c	ERR_TAXINOTENOUGHMONEY	1	NONE	0x36	10
+0xae	174	0xb4c230	ERR_TAXITOOFARAWAY	1	NONE	0x44	10
+0xaf	175	0xb4c244	ERR_TAXINOVENDORNEARBY	1	NONE	0x44	10
+0xb0	176	0xb4c258	ERR_TAXINOTVISITED	1	NONE	0x44	10
+0xb1	177	0xb4c26c	ERR_TAXIPLAYERBUSY	2	NONE	0x44	10
+0xb2	178	0xb4c280	ERR_TAXIPLAYERALREADYMOUNTED	2	NONE	0x44	10
+0xb3	179	0xb4c294	ERR_TAXIPLAYERSHAPESHIFTED	2	NONE	0x44	10
+0xb4	180	0xb4c2a8	ERR_TAXIPLAYERMOVING	1	NONE	0x44	10
+0xb5	181	0xb4c2bc	ERR_TAXINOPATHS	2	NONE	0x44	10
+0xb6	182	0xb4c2d0	ERR_TAXINOTSTANDING	1	NONE	0x44	10
+0xb7	183	0xb4c2e4	ERR_NO_REPLY_TARGET	0	NONE	0x44	10
+0xb8	184	0xb4c2f8	ERR_GENERIC_NO_TARGET	2	NONE	0x2d	10
+0xb9	185	0xb4c30c	ERR_INITIATE_TRADE_S	0	NONE	0x44	10
+0xba	186	0xb4c320	ERR_TRADE_REQUEST_S	0	LEVELUP	0x44	10
+0xbb	187	0xb4c334	ERR_TRADE_BLOCKED_S	0	NONE	0x44	10
+0xbc	188	0xb4c348	ERR_TRADE_TARGET_DEAD	2	NONE	0x44	10
+0xbd	189	0xb4c35c	ERR_TRADE_TOO_FAR	2	NONE	0x44	10
+0xbe	190	0xb4c370	ERR_TRADE_CANCELLED	1	NONE	0x44	10
+0xbf	191	0xb4c384	ERR_TRADE_COMPLETE	1	NONE	0x44	10
+0xc0	192	0xb4c398	ERR_TRADE_BAG_FULL	2	NONE	0x44	10
+0xc1	193	0xb4c3ac	ERR_TRADE_TARGET_BAG_FULL	2	NONE	0x44	10
+0xc2	194	0xb4c3c0	ERR_TRADE_MAX_COUNT_EXCEEDED	2	NONE	0x44	10
+0xc3	195	0xb4c3d4	ERR_TRADE_TARGET_MAX_COUNT_EXCEEDED	2	NONE	0x44	10
+0xc4	196	0xb4c3e8	ERR_ALREADY_TRADING	2	NONE	0x44	10
+0xc5	197	0xb4c3fc	ERR_MOUNT_INVALIDMOUNTEE	2	NONE	0x44	10
+0xc6	198	0xb4c410	ERR_MOUNT_TOOFARAWAY	2	NONE	0x44	10
+0xc7	199	0xb4c424	ERR_MOUNT_ALREADYMOUNTED	2	NONE	0x44	10
+0xc8	200	0xb4c438	ERR_MOUNT_NOTMOUNTABLE	2	NONE	0x44	10
+0xc9	201	0xb4c44c	ERR_MOUNT_NOTYOURPET	2	NONE	0x44	10
+0xca	202	0xb4c460	ERR_MOUNT_OTHER	2	NONE	0x44	10
+0xcb	203	0xb4c474	ERR_MOUNT_LOOTING	2	NONE	0x44	10
+0xcc	204	0xb4c488	ERR_MOUNT_RACECANTMOUNT	2	NONE	0x44	10
+0xcd	205	0xb4c49c	ERR_MOUNT_SHAPESHIFTED	2	NONE	0x44	10
+0xce	206	0xb4c4b0	ERR_DISMOUNT_NOPET	2	NONE	0x44	10
+0xcf	207	0xb4c4c4	ERR_DISMOUNT_NOTMOUNTED	2	NONE	0x44	10
+0xd0	208	0xb4c4d8	ERR_DISMOUNT_NOTYOURPET	2	NONE	0x44	10
+0xd1	209	0xb4c4ec	ERR_SPELL_FAILED_TOTEMS	2	NONE	0x44	10
+0xd2	210	0xb4c500	ERR_SPELL_FAILED_REAGENTS	2	NONE	0x44	10
+0xd3	211	0xb4c514	ERR_SPELL_FAILED_REAGENTS_GENERIC	2	NONE	0x44	10
+0xd4	212	0xb4c528	ERR_SPELL_FAILED_EQUIPPED_ITEM	2	NONE	0x44	10
+0xd5	213	0xb4c53c	ERR_SPELL_FAILED_EQUIPPED_ITEM_CLASS_S	2	NONE	0x44	10
+0xd6	214	0xb4c550	ERR_SPELL_FAILED_SHAPESHIFT_FORM_S	2	NONE	0x44	10
+0xd7	215	0xb4c564	ERR_BADATTACKFACING	2	NONE	0x44	10
+0xd8	216	0xb4c578	ERR_BADATTACKPOS	2	NONE	0x44	10
+0xd9	217	0xb4c58c	ERR_CHEST_IN_USE	2	NONE	0x34	10
+0xda	218	0xb4c5a0	ERR_USE_CANT_OPEN	2	NONE	0x44	10
+0xdb	219	0xb4c5b4	ERR_USE_LOCKED	2	NONE	0x3d	10
+0xdc	220	0xb4c5c8	ERR_DOOR_LOCKED	2	NONE	0x3d	10
+0xdd	221	0xb4c5dc	ERR_BUTTON_LOCKED	2	NONE	0x3d	10
+0xde	222	0xb4c5f0	ERR_USE_LOCKED_WITH_ITEM_S	2	NONE	0x44	10
+0xdf	223	0xb4c604	ERR_USE_LOCKED_WITH_SPELL_S	2	NONE	0x44	10
+0xe0	224	0xb4c618	ERR_USE_LOCKED_WITH_SPELL_KNOWN_SI	2	NONE	0x44	10
+0xe1	225	0xb4c62c	ERR_USE_TOO_FAR	2	NONE	0x39	10
+0xe2	226	0xb4c640	ERR_USE_BAD_ANGLE	2	NONE	0x44	10
+0xe3	227	0xb4c654	ERR_USE_OBJECT_MOVING	2	NONE	0x44	10
+0xe4	228	0xb4c668	ERR_USE_SPELL_FOCUS	1	NONE	0x44	10
+0xe5	229	0xb4c67c	ERR_USE_DESTROYED	2	NONE	0x44	10
+0xe6	230	0xb4c690	ERR_SET_LOOT_FREEFORALL	0	NONE	0x44	10
+0xe7	231	0xb4c6a4	ERR_SET_LOOT_ROUNDROBIN	0	NONE	0x44	10
+0xe8	232	0xb4c6b8	ERR_SET_LOOT_MASTER	0	NONE	0x44	10
+0xe9	233	0xb4c6cc	ERR_SET_LOOT_GROUP	0	NONE	0x44	10
+0xea	234	0xb4c6e0	ERR_SET_LOOT_NBG	0	NONE	0x44	10
+0xeb	235	0xb4c6f4	ERR_SET_LOOT_THRESHOLD_S	0	NONE	0x44	10
+0xec	236	0xb4c708	ERR_NEW_LOOT_MASTER_S	0	NONE	0x44	10
+0xed	237	0xb4c71c	ERR_SPECIFY_MASTER_LOOTER	2	NONE	0x44	10
+0xee	238	0xb4c730	ERR_TAME_FAILED	2	NONE	0x44	10
+0xef	239	0xb4c744	ERR_CHAT_WHILE_DEAD	2	NONE	0x44	10
+0xf0	240	0xb4c758	ERR_CHAT_WRONG_FACTION	0	NONE	0x44	10
+0xf1	241	0xb4c76c	ERR_CHAT_PLAYER_NOT_FOUND_S	0	NONE	0x44	10
+0xf2	242	0xb4c780	ERR_NEWTAXIPATH	1	TaxiNodeDiscovered	0x44	10
+0xf3	243	0xb4c794	ERR_NO_PET	2	NONE	0x44	10
+0xf4	244	0xb4c7a8	ERR_NOTYOURPET	2	NONE	0x44	10
+0xf5	245	0xb4c7bc	ERR_PET_NOT_RENAMEABLE	2	NONE	0x44	10
+0xf6	246	0xb4c7d0	ERR_NULL_PETNAME	2	NONE	0x44	10
+0xf7	247	0xb4c7e4	ERR_INVALID_PETNAME	2	NONE	0x44	10
+0xf8	248	0xb4c7f8	ERR_QUEST_OBJECTIVE_COMPLETE_S	1	NONE	0x44	10
+0xf9	249	0xb4c80c	ERR_QUEST_UNKNOWN_COMPLETE	1	NONE	0x44	10
+0xfa	250	0xb4c820	ERR_QUEST_ADD_KILL_SII	1	NONE	0x44	10
+0xfb	251	0xb4c834	ERR_QUEST_ADD_FOUND_SII	1	NONE	0x44	10
+0xfc	252	0xb4c848	ERR_QUEST_ADD_ITEM_SII	1	NONE	0x44	10
+0xfd	253	0xb4c85c	ERR_CANNOTCREATEDIRECTORY	2	NONE	0x44	10
+0xfe	254	0xb4c870	ERR_CANNOTCREATEFILE	2	NONE	0x44	10
+0xff	255	0xb4c884	ERR_PLAYER_WRONG_FACTION	2	NONE	0x44	10
+0x100	256	0xb4c898	ERR_BANKSLOT_FAILED_TOO_MANY	2	NONE	0x44	10
+0x101	257	0xb4c8ac	ERR_BANKSLOT_INSUFFICIENT_FUNDS	2	NONE	0x16	10
+0x102	258	0xb4c8c0	ERR_BANKSLOT_NOTBANKER	2	NONE	0x44	10
+0x103	259	0xb4c8d4	ERR_FRIEND_DB_ERROR	0	NONE	0x44	10
+0x104	260	0xb4c8e8	ERR_FRIEND_LIST_FULL	0	NONE	0x44	10
+0x105	261	0xb4c8fc	ERR_FRIEND_ADDED_S	0	NONE	0x44	10
+0x106	262	0xb4c910	ERR_FRIEND_ONLINE_SS	0	FRIENDJOINGAME	0x44	10
+0x107	263	0xb4c924	ERR_FRIEND_OFFLINE_S	0	NONE	0x44	10
+0x108	264	0xb4c938	ERR_FRIEND_NOT_FOUND	0	NONE	0x44	10
+0x109	265	0xb4c94c	ERR_FRIEND_WRONG_FACTION	0	NONE	0x44	10
+0x10a	266	0xb4c960	ERR_FRIEND_REMOVED_S	0	NONE	0x44	10
+0x10b	267	0xb4c974	ERR_FRIEND_ERROR	0	NONE	0x44	10
+0x10c	268	0xb4c988	ERR_FRIEND_ALREADY_S	0	NONE	0x44	10
+0x10d	269	0xb4c99c	ERR_FRIEND_SELF	0	NONE	0x44	10
+0x10e	270	0xb4c9b0	ERR_IGNORE_FULL	0	NONE	0x44	10
+0x10f	271	0xb4c9c4	ERR_IGNORE_SELF	0	NONE	0x44	10
+0x110	272	0xb4c9d8	ERR_IGNORE_NOT_FOUND	0	NONE	0x44	10
+0x111	273	0xb4c9ec	ERR_IGNORE_ALREADY_S	0	NONE	0x44	10
+0x112	274	0xb4ca00	ERR_IGNORE_ADDED_S	0	NONE	0x44	10
+0x113	275	0xb4ca14	ERR_IGNORE_REMOVED_S	0	NONE	0x44	10
+0x114	276	0xb4ca28	ERR_IGNORE_AMBIGUOUS	0	NONE	0x44	10
+0x115	277	0xb4ca3c	ERR_ONLY_ONE_BOLT	2	NONE	0x44	10
+0x116	278	0xb4ca50	ERR_ONLY_ONE_AMMO	2	NONE	0x44	10
+0x117	279	0xb4ca64	ERR_SPELL_FAILED_EQUIPPED_SPECIFIC_ITEM	2	NONE	0x44	10
+0x118	280	0xb4ca78	ERR_WRONG_BAG_TYPE_SUBCLASS	2	NONE	0x1c	10
+0x119	281	0xb4ca8c	ERR_CANT_WRAP_STACKABLE	2	NONE	0x44	10
+0x11a	282	0xb4caa0	ERR_CANT_WRAP_EQUIPPED	2	NONE	0x44	10
+0x11b	283	0xb4cab4	ERR_CANT_WRAP_WRAPPED	2	NONE	0x44	10
+0x11c	284	0xb4cac8	ERR_CANT_WRAP_BOUND	2	NONE	0x44	10
+0x11d	285	0xb4cadc	ERR_CANT_WRAP_UNIQUE	2	NONE	0x44	10
+0x11e	286	0xb4caf0	ERR_CANT_WRAP_BAGS	2	NONE	0x44	10
+0x11f	287	0xb4cb04	ERR_OUT_OF_MANA	2	NONE	0xf	10
+0x120	288	0xb4cb18	ERR_OUT_OF_RAGE	2	NONE	0x3f	10
+0x121	289	0xb4cb2c	ERR_OUT_OF_FOCUS	2	NONE	0x44	10
+0x122	290	0xb4cb40	ERR_OUT_OF_ENERGY	2	NONE	0x40	10
+0x123	291	0xb4cb54	ERR_OUT_OF_HEALTH	2	NONE	0x44	10
+0x124	292	0xb4cb68	ERR_LOOT_GONE	2	NONE	0x44	10
+0x125	293	0xb4cb7c	ERR_MOUNT_FORCEDDISMOUNT	2	NONE	0x44	10
+0x126	294	0xb4cb90	ERR_AUTOFOLLOW_TOO_FAR	2	NONE	0x44	10
+0x127	295	0xb4cba4	ERR_UNIT_NOT_FOUND	2	NONE	0x44	10
+0x128	296	0xb4cbb8	ERR_INVALID_FOLLOW_TARGET	2	NONE	0x44	10
+0x129	297	0xb4cbcc	ERR_INVALID_INSPECT_TARGET	2	NONE	0x44	10
+0x12a	298	0xb4cbe0	ERR_GUILDEMBLEM_SUCCESS	2	NONE	0x44	10
+0x12b	299	0xb4cbf4	ERR_GUILDEMBLEM_INVALID_TABARD_COLORS	2	NONE	0x44	10
+0x12c	300	0xb4cc08	ERR_GUILDEMBLEM_NOGUILD	2	NONE	0x44	10
+0x12d	301	0xb4cc1c	ERR_GUILDEMBLEM_NOTGUILDMASTER	2	NONE	0x44	10
+0x12e	302	0xb4cc30	ERR_GUILDEMBLEM_NOTENOUGHMONEY	2	NONE	0x28	10
+0x12f	303	0xb4cc44	ERR_GUILDEMBLEM_INVALIDVENDOR	2	NONE	0x44	10
+0x130	304	0xb4cc58	ERR_EMBLEMERROR_NOTABARDGEOSET	2	NONE	0x44	10
+0x131	305	0xb4cc6c	ERR_SPELL_OUT_OF_RANGE	2	NONE	0x2e	10
+0x132	306	0xb4cc80	ERR_COMMAND_NEEDS_TARGET	0	NONE	0x44	10
+0x133	307	0xb4cc94	ERR_NOAMMO_S	2	NONE	0x1	10
+0x134	308	0xb4cca8	ERR_TOOBUSYTOFOLLOW	2	NONE	0x44	10
+0x135	309	0xb4ccbc	ERR_DUEL_REQUESTED	0	LEVELUP	0x44	10
+0x136	310	0xb4ccd0	ERR_DUEL_CANCELLED	1	NONE	0x44	10
+0x137	311	0xb4cce4	ERR_DEATHBINDALREADYBOUND	2	NONE	0x44	10
+0x138	312	0xb4ccf8	ERR_DEATHBIND_SUCCESS_S	0	NONE	0x44	10
+0x139	313	0xb4cd0c	ERR_NOEMOTEWHILERUNNING	2	NONE	0x44	10
+0x13a	314	0xb4cd20	ERR_ZONE_EXPLORED	1	NONE	0x44	10
+0x13b	315	0xb4cd34	ERR_ZONE_EXPLORED_XP	0	NONE	0x44	10
+0x13c	316	0xb4cd48	ERR_INVALID_ITEM_TARGET	2	NONE	0x33	10
+0x13d	317	0xb4cd5c	ERR_IGNORING_YOU_S	0	NONE	0x44	10
+0x13e	318	0xb4cd70	ERR_FISH_NOT_HOOKED	1	NONE	0x44	10
+0x13f	319	0xb4cd84	ERR_FISH_ESCAPED	1	NONE	0x44	10
+0x140	320	0xb4cd98	ERR_SPELL_FAILED_NOTUNSHEATHED	1	NONE	0x44	10
+0x141	321	0xb4cdac	ERR_PETITION_OFFERED_S	0	NONE	0x44	10
+0x142	322	0xb4cdc0	ERR_PETITION_SIGNED	0	igPlayerInviteAccept	0x44	10
+0x143	323	0xb4cdd4	ERR_PETITION_SIGNED_S	0	igPlayerInviteAccept	0x44	10
+0x144	324	0xb4cde8	ERR_PETITION_DECLINED_S	0	igPlayerInviteDecline	0x44	10
+0x145	325	0xb4cdfc	ERR_PETITION_ALREADY_SIGNED	2	igPlayerInviteDecline	0x44	10
+0x146	326	0xb4ce10	ERR_PETITION_IN_GUILD	2	igPlayerInviteDecline	0x44	10
+0x147	327	0xb4ce24	ERR_PETITION_CREATOR	2	igPlayerInviteDecline	0x44	10
+0x148	328	0xb4ce38	ERR_PETITION_NOT_ENOUGH_SIGNATURES	2	igPlayerInviteDecline	0x44	10
+0x149	329	0xb4ce4c	ERR_PETITION_NOT_SAME_SERVER	2	igPlayerInviteDecline	0x44	10
+0x14a	330	0xb4ce60	ERR_SPELL_UNLEARNED_S	0	NONE	0x44	10
+0x14b	331	0xb4ce74	ERR_PET_SPELL_ROOTED	2	NONE	0x44	10
+0x14c	332	0xb4ce88	ERR_PET_SPELL_AFFECTING_COMBAT	2	NONE	0x44	10
+0x14d	333	0xb4ce9c	ERR_PET_SPELL_OUT_OF_RANGE	2	NONE	0x44	10
+0x14e	334	0xb4ceb0	ERR_PET_SPELL_NOT_BEHIND	2	NONE	0x44	10
+0x14f	335	0xb4cec4	ERR_PET_SPELL_TARGETS_DEAD	2	NONE	0x44	10
+0x150	336	0xb4ced8	ERR_PET_SPELL_DEAD	2	NONE	0x44	10
+0x151	337	0xb4ceec	ERR_PET_SPELL_NOPATH	2	NONE	0x44	10
+0x152	338	0xb4cf00	ERR_ITEM_CANT_BE_DESTROYED	2	NONE	0x44	10
+0x153	339	0xb4cf14	ERR_TICKET_ALREADY_EXISTS	2	NONE	0x44	10
+0x154	340	0xb4cf28	ERR_TICKET_CREATE_ERROR	2	NONE	0x44	10
+0x155	341	0xb4cf3c	ERR_TICKET_UPDATE_ERROR	2	NONE	0x44	10
+0x156	342	0xb4cf50	ERR_TICKET_DB_ERROR	2	NONE	0x44	10
+0x157	343	0xb4cf64	ERR_TICKET_NO_TEXT	2	NONE	0x44	10
+0x158	344	0xb4cf78	ERR_OBJECT_IS_BUSY	2	NONE	0x44	10
+0x159	345	0xb4cf8c	ERR_EXHAUSTION_WELLRESTED	0	NONE	0x44	10
+0x15a	346	0xb4cfa0	ERR_EXHAUSTION_RESTED	0	NONE	0x44	10
+0x15b	347	0xb4cfb4	ERR_EXHAUSTION_NORMAL	0	NONE	0x44	10
+0x15c	348	0xb4cfc8	ERR_EXHAUSTION_TIRED	0	NONE	0x44	10
+0x15d	349	0xb4cfdc	ERR_EXHAUSTION_EXHAUSTED	0	NONE	0x44	10
+0x15e	350	0xb4cff0	ERR_NO_ITEMS_WHILE_SHAPESHIFTED	2	NONE	0x44	10
+0x15f	351	0xb4d004	ERR_CANT_INTERACT_SHAPESHIFTED	2	NONE	0x44	10
+0x160	352	0xb4d018	ERR_MAIL_QUEST_ITEM	2	NONE	0x3b	10
+0x161	353	0xb4d02c	ERR_MAIL_BOUND_ITEM	2	NONE	0x3b	10
+0x162	354	0xb4d040	ERR_MAIL_CONJURED_ITEM	2	NONE	0x44	10
+0x163	355	0xb4d054	ERR_MAIL_BAG	2	NONE	0x44	10
+0x164	356	0xb4d068	ERR_MAIL_TO_SELF	2	NONE	0x44	10
+0x165	357	0xb4d07c	ERR_MAIL_TARGET_NOT_FOUND	2	NONE	0x44	10
+0x166	358	0xb4d090	ERR_MAIL_DATABASE_ERROR	2	NONE	0x44	10
+0x167	359	0xb4d0a4	ERR_MAIL_SENT	1	NONE	0x44	10
+0x168	360	0xb4d0b8	ERR_NOT_HAPPY_ENOUGH	2	NONE	0x44	10
+0x169	361	0xb4d0cc	ERR_USE_CANT_IMMUNE	2	NONE	0x44	10
+0x16a	362	0xb4d0e0	ERR_CANT_BE_DISENCHANTED	2	NONE	0x44	10
+0x16b	363	0xb4d0f4	ERR_CANT_USE_DISARMED	2	NONE	0x44	10
+0x16c	364	0xb4d108	ERR_AUCTION_QUEST_ITEM	2	NONE	0x3b	10
+0x16d	365	0xb4d11c	ERR_AUCTION_BOUND_ITEM	2	NONE	0x3b	10
+0x16e	366	0xb4d130	ERR_AUCTION_CONJURED_ITEM	2	NONE	0x44	10
+0x16f	367	0xb4d144	ERR_AUCTION_WRAPPED_ITEM	2	NONE	0x44	10
+0x170	368	0xb4d158	ERR_AUCTION_LOOT_ITEM	2	NONE	0x44	10
+0x171	369	0xb4d16c	ERR_AUCTION_BAG	2	NONE	0x44	10
+0x172	370	0xb4d180	ERR_AUCTION_DATABASE_ERROR	2	NONE	0x44	10
+0x173	371	0xb4d194	ERR_AUCTION_BID_OWN	2	NONE	0x44	10
+0x174	372	0xb4d1a8	ERR_AUCTION_BID_INCREMENT	2	NONE	0x44	10
+0x175	373	0xb4d1bc	ERR_AUCTION_HIGHER_BID	2	NONE	0x44	10
+0x176	374	0xb4d1d0	ERR_AUCTION_MIN_BID	2	NONE	0x44	10
+0x177	375	0xb4d1e4	ERR_AUCTION_REPAIR_ITEM	2	NONE	0x44	10
+0x178	376	0xb4d1f8	ERR_AUCTION_STARTED	0	NONE	0x44	10
+0x179	377	0xb4d20c	ERR_AUCTION_REMOVED	0	NONE	0x44	10
+0x17a	378	0xb4d220	ERR_AUCTION_OUTBID_S	0	NONE	0x44	10
+0x17b	379	0xb4d234	ERR_AUCTION_WON_S	0	NONE	0x44	10
+0x17c	380	0xb4d248	ERR_AUCTION_SOLD_S	0	NONE	0x44	10
+0x17d	381	0xb4d25c	ERR_AUCTION_EXPIRED_S	0	NONE	0x44	10
+0x17e	382	0xb4d270	ERR_AUCTION_REMOVED_S	0	NONE	0x44	10
+0x17f	383	0xb4d284	ERR_AUCTION_BID_PLACED	0	NONE	0x44	10
+0x180	384	0xb4d298	ERR_LOGOUT_FAILED	2	NONE	0x44	10
+0x181	385	0xb4d2ac	ERR_QUEST_PUSH_SUCCESS_S	0	NONE	0x44	10
+0x182	386	0xb4d2c0	ERR_QUEST_PUSH_INVALID_S	0	NONE	0x44	10
+0x183	387	0xb4d2d4	ERR_QUEST_PUSH_ACCEPTED_S	0	NONE	0x44	10
+0x184	388	0xb4d2e8	ERR_QUEST_PUSH_DECLINED_S	0	NONE	0x44	10
+0x185	389	0xb4d2fc	ERR_QUEST_PUSH_TOO_FAR_S	0	NONE	0x44	10
+0x186	390	0xb4d310	ERR_QUEST_PUSH_BUSY_S	0	NONE	0x44	10
+0x187	391	0xb4d324	ERR_QUEST_PUSH_LOG_FULL_S	0	NONE	0x44	10
+0x188	392	0xb4d338	ERR_QUEST_PUSH_ONQUEST_S	0	NONE	0x44	10
+0x189	393	0xb4d34c	ERR_QUEST_PUSH_ALREADY_DONE_S	0	NONE	0x44	10
+0x18a	394	0xb4d360	ERR_RAID_GROUP_ONLY	2	NONE	0x44	10
+0x18b	395	0xb4d374	ERR_RAID_GROUP_FULL	2	NONE	0x44	10
+0x18c	396	0xb4d388	ERR_PVP_KILL_HONORABLE	1	NONE	0x44	10
+0x18d	397	0xb4d39c	ERR_PVP_KILL_DISHONORABLE	1	NONE	0x44	10
+0x18e	398	0xb4d3b0	ERR_SPELL_FAILED_ALREADY_AT_FULL_HEALTH	2	NONE	0x44	10
+0x18f	399	0xb4d3c4	ERR_SPELL_FAILED_ALREADY_AT_FULL_POWER_S	2	NONE	0x44	10
+0x190	400	0xb4d3d8	ERR_AUTOLOOT_MONEY_S	0	NONE	0x44	10
+0x191	401	0xb4d3ec	ERR_GENERIC_STUNNED	2	NONE	0x44	10
+0x192	402	0xb4d400	ERR_TARGET_STUNNED	2	NONE	0x44	10
+0x193	403	0xb4d414	ERR_MUST_REPAIR_DURABILITY	2	NONE	0x44	10
+0x194	404	0xb4d428	ERR_RAID_YOU_JOINED	0	NONE	0x44	10
+0x195	405	0xb4d43c	ERR_RAID_YOU_LEFT	0	NONE	0x44	10
+0x196	406	0xb4d450	ERR_RAID_MEMBER_ADDED_S	0	NONE	0x44	10
+0x197	407	0xb4d464	ERR_RAID_MEMBER_REMOVED_S	0	NONE	0x44	10
+0x198	408	0xb4d478	ERR_CLICK_ON_ITEM_TO_FEED	2	NONE	0x44	10
+0x199	409	0xb4d48c	ERR_TOO_MANY_CHAT_CHANNELS	0	NONE	0x44	10
+0x19a	410	0xb4d4a0	ERR_LOOT_ROLL_PENDING	2	NONE	0x44	10
+0x19b	411	0xb4d4b4	ERR_LOOT_PLAYER_NOT_FOUND	2	NONE	0x44	10
+0x19c	412	0xb4d4c8	ERR_NOT_IN_RAID	0	NONE	0x44	10
+0x19d	413	0xb4d4dc	ERR_LOGGING_OUT	2	NONE	0x44	10
+0x19e	414	0xb4d4f0	ERR_TARGET_LOGGING_OUT	2	NONE	0x44	10
+0x19f	415	0xb4d504	ERR_NOT_WHILE_MOUNTED	2	NONE	0x44	10
+0x1a0	416	0xb4d518	ERR_NOT_WHILE_SHAPESHIFTED	2	NONE	0x44	10
+0x1a1	417	0xb4d52c	ERR_NOT_IN_COMBAT	2	NONE	0x44	10
+0x1a2	418	0xb4d540	ERR_NOT_WHILE_DISARMED	2	NONE	0x44	10
+0x1a3	419	0xb4d554	ERR_PET_BROKEN	2	NONE	0x44	10
+0x1a4	420	0xb4d568	ERR_TALENT_WIPE_ERROR	2	NONE	0x44	10
+0x1a5	421	0xb4d57c	ERR_FEIGN_DEATH_RESISTED	2	NONE	0x44	10
+0x1a6	422	0xb4d590	ERR_MEETING_STONE_IN_QUEUE_S	0	NONE	0x44	10
+0x1a7	423	0xb4d5a4	ERR_MEETING_STONE_LEFT_QUEUE_S	0	NONE	0x44	10
+0x1a8	424	0xb4d5b8	ERR_MEETING_STONE_OTHER_MEMBER_LEFT	0	NONE	0x44	10
+0x1a9	425	0xb4d5cc	ERR_MEETING_STONE_PARTY_KICKED_FROM_QUEUE	0	NONE	0x44	10
+0x1aa	426	0xb4d5e0	ERR_MEETING_STONE_MEMBER_STILL_IN_QUEUE	0	NONE	0x44	10
+0x1ab	427	0xb4d5f4	ERR_MEETING_STONE_SUCCESS	0	NONE	0x44	10
+0x1ac	428	0xb4d608	ERR_MEETING_STONE_IN_PROGRESS	0	NONE	0x44	10
+0x1ad	429	0xb4d61c	ERR_MEETING_STONE_MEMBER_ADDED_S	0	NONE	0x44	10
+0x1ae	430	0xb4d630	ERR_MEETING_STONE_GROUP_FULL	2	NONE	0x44	10
+0x1af	431	0xb4d644	ERR_MEETING_STONE_NOT_LEADER	2	NONE	0x44	10
+0x1b0	432	0xb4d658	ERR_MEETING_STONE_INVALID_LEVEL	2	NONE	0x44	10
+0x1b1	433	0xb4d66c	ERR_MEETING_STONE_MUST_BE_LEADER	2	NONE	0x44	10
+0x1b2	434	0xb4d680	ERR_MEETING_STONE_NO_RAID_GROUP	2	NONE	0x44	10
+0x1b3	435	0xb4d694	ERR_GUILDEMBLEM_SAME	2	NONE	0x44	10
+0x1b4	436	0xb4d6a8	ERR_EQUIP_TRADE_ITEM	2	NONE	0x44	10
+0x1b5	437	0xb4d6bc	ERR_PVP_TOGGLE_ON	1	NONE	0x44	10
+0x1b6	438	0xb4d6d0	ERR_PVP_TOGGLE_OFF	1	NONE	0x44	10
+0x1b7	439	0xb4d6e4	ERR_GROUP_JOIN_BATTLEGROUND_DESERTERS	1	NONE	0x44	10
+0x1b8	440	0xb4d6f8	ERR_GROUP_JOIN_BATTLEGROUND_S	1	NONE	0x44	10
+0x1b9	441	0xb4d70c	ERR_GROUP_JOIN_BATTLEGROUND_FAIL	2	NONE	0x44	10
+0x1ba	442	0xb4d720	ERR_GROUP_JOIN_BATTLEGROUND_TOO_MANY	2	NONE	0x44	10
+0x1bb	443	0xb4d734	ERR_INVALID_PROMOTION_CODE	2	NONE	0x44	10
+0x1bc	444	0xb4d748	ERR_BG_PLAYER_JOINED_SS	0	NONE	0x44	10
+0x1bd	445	0xb4d75c	ERR_BG_PLAYER_LEFT_S	0	NONE	0x44	10
+0x1be	446	0xb4d770	ERR_RESTRICTED_ACCOUNT	2	NONE	0x44	10
+0x1bf	447	0xb4d784	ERR_PLAY_TIME_EXCEEDED	2	NONE	0x44	10
+0x1c0	448	0xb4d798	ERR_APPROACHING_PARTIAL_PLAY_TIME	0	NONE	0x44	10
+0x1c1	449	0xb4d7ac	ERR_APPROACHING_NO_PLAY_TIME	0	NONE	0x44	10
+0x1c2	450	0xb4d7c0	ERR_UNHEALTHY_TIME	0	NONE	0x44	10
+0x1c3	451	0xb4d7d4	ERR_CHAT_RESTRICTED	0	NONE	0x44	10
+0x1c4	452	0xb4d7e8	ERR_MAIL_REACHED_CAP	2	NONE	0x44	10
+0x1c5	453	0xb4d7fc	ERR_INVALID_RAID_TARGET	2	NONE	0x44	10
+0x1c6	454	0xb4d810	ERR_RAID_LEADER_READY_CHECK_START_S	0	NONE	0x44	10
+0x1c7	455	0xb4d824	ERR_READY_CHECK_IN_PROGRESS	2	NONE	0x44	10
+0x1c8	456	0xb4d838	ERR_DUNGEON_DIFFICULTY_FAILED	0	NONE	0x44	10
+0x1c9	457	0xb4d84c	ERR_DUNGEON_DIFFICULTY_CHANGED_S	0	NONE	0x44	10
+0x1ca	458	0xb4d860	ERR_TRADE_WRONG_REALM	2	NONE	0x44	10
+0x1cb	459	0xb4d874	ERR_CHAT_PLAYER_AMBIGUOUS_S	0	NONE	0x44	10
+0x1cc	460	0xb4d888	ERR_LOOT_CANT_LOOT_THAT_NOW	2	NONE	0x44	10
+0x1cd	461	0xb4d89c	ERR_LOOT_MASTER_INV_FULL	2	NONE	0x44	10
+0x1ce	462	0xb4d8b0	ERR_LOOT_MASTER_UNIQUE_ITEM	2	NONE	0x44	10
+0x1cf	463	0xb4d8c4	ERR_LOOT_MASTER_OTHER	2	NONE	0x44	10
+0x1d0	464	0xb4d8d8	ERR_FILTERING_YOU_S	0	NONE	0x44	10
diff --git a/reference/1.12-shapes.tsv b/reference/1.12-shapes.tsv
new file mode 100644
index 00000000..4bae74f5
--- /dev/null
+++ b/reference/1.12-shapes.tsv
@@ -0,0 +1,1763 @@
+# Lua binding shapes of the 1.12.1 client (WoW.exe build 5875): one row per registered
+# binding, name -> (argc, return arity, return kinds), with per-column confidence.
+#
+# 82 registrar tables, 1722 bindings, 1722 analysed, 0 unresolved registrar sites. Four
+# registration routes, extents read from the registrar's own literal: 0x704120
+# RegisterFunction loops; 0x701d80 widget method tables; the inlined base-library loop at
+# 0x811e28; and the four luaL_openlib 0x6f4dc0 tables (bit/math/table/string).
+#
+# Column contract:
+#   arity / arity_conf   sound. exact = one constant; set = a `|`-separated set of possible
+#     counts; unknown = `?`. An imprecise result is a set or `?`, never a wrong single
+#     number. Gate on this.
+#   kind `string?`       string or nil. lua_pushstring 0x6f3890 begins `test edx,edx ; jne`
+#     and tail-jumps to lua_pushnil when the char* is NULL, so `string` is emitted only where
+#     the pointer is a constant that resolves to a readable literal; every other
+#     lua_pushstring is `string?`. A miss path can show a fixed arity and still answer nil in
+#     that slot (GetMapInfo -> nil,0,0; GetChannelName -> 0,nil,0).
+#   kinds / kinds_conf   advisory unless kinds_conf == agree: the independent lua_push* trace
+#     length matches `eax` at every ret, and every ret was checked. A loop (GetTexCoord: 2
+#     textual pushes, 8 real) -> unverified. `agree` is about the binding's own ops:
+#     lua_gettable 0x6f3a40 and lua_rawget 0x6f3b00 replace the key on top with the looked-up
+#     value (recorded as `any`), and a callee that pushes on the binding's behalf is invisible
+#     to the trace, so the returned window may hold slots it never described (note
+#     `delegated-push`).
+#   argc / argc_conf     never gate on this. argc is a max over observed constant Lua stack
+#     indices, with no unknown state, and a silent lower bound when a binding delegates
+#     argument parsing to a helper. Such rows say lower-bound, but the detector is one level
+#     deep, so treat every argc as a floor.
+#   name       not a key. 60 names are registered from more than one table and 21 of those
+#     differ in arity between registrations: GetBuildInfo returns 5 on the glue screen (table
+#     0x8373b8) and 3 in-game (0x83de68); GetAddOnInfo 8 and 7. Key on `fn`, or on
+#     (table_va, name). Every such row carries the note name-not-unique.
+#   notes  stack-leak = the reference pushes a value and then returns 0 (or fewer): the
+#     disabled lottery/vendor stubs, which a faithful client does not copy. variadic = the
+#     count comes from lua_gettop, no constant exists. delegated-push = a foreign callee
+#     pushes on the binding's behalf, so `agree` covers this row's own ops only.
+#     cfg-truncated / indirect-branch / iteration-cap = an edge the walk could not resolve;
+#     such a row's arity is not covered by the soundness claim above.
+#
+# Vendored from the maintainer's analysis (`WOW_RE`); no generator for it lives in this repo.
+name	fn	pair_va	table_va	table_kind	argc	argc_conf	arity	arity_conf	kinds	kinds_conf	notes
+AbandonQuest	0x4dfe00	0x84b128	0x84b0f0	global	0	exact	0	exact	()	agree	
+AbandonSkill	0x4d3ab0	0x849d08	0x849cf8	global	1	exact	0	exact	()	agree	
+AcceptAreaSpiritHeal	0x48df20	0x83e468	0x83de68	global	0	exact	0	exact	()	agree	
+AcceptBattlefieldPort	0x4ab3b0	0x845810	0x8457e0	global	2	exact	0	exact	()	agree	
+AcceptContest	0x46d150	0x837478	0x8373b8	global	0	exact	0	exact	()	agree	
+AcceptDuel	0x4d4ce0	0x849fb8	0x849fa8	global	0	exact	0	exact	()	agree	
+AcceptEULA	0x46d070	0x837448	0x8373b8	global	0	exact	0	exact	()	agree	
+AcceptGroup	0x48aa80	0x83e158	0x83de68	global	0	exact	0	exact	()	agree	
+AcceptGuild	0x48aae0	0x83e168	0x83de68	global	0	exact	0	exact	()	agree	
+AcceptQuest	0x501d20	0x84e9e0	0x84e968	global	0	exact	0	exact	()	agree	
+AcceptResurrect	0x48a9a0	0x83e128	0x83de68	global	0	exact	0	exact	()	agree	
+AcceptScanning	0x46d0e0	0x837460	0x8373b8	global	0	exact	0	exact	()	agree	
+AcceptSkillUps	0x4d3d40	0x849d38	0x849cf8	global	0	exact	0	exact	()	agree	
+AcceptTOS	0x46d000	0x837430	0x8373b8	global	0	exact	0	exact	()	agree	
+AcceptTrade	0x4c06e0	0x847a30	0x8479f8	global	0	exact	0	exact	()	agree	
+AcceptXPLoss	0x48d0c0	0x83e350	0x83de68	global	0	exact	0	exact	()	agree	
+ActionHasRange	0x4e75d0	0x84bd90	0x84bd10	global	1	exact	1	exact	(nil) | (number)	agree	
+AddChatWindowChannel	0x4a1000	0x843730	0x843618	global	2	exact	0|1	set	() | (number)	agree	
+AddChatWindowMessages	0x4a0e80	0x843720	0x843618	global	2	exact	0	exact	()	agree	
+AddDoubleLine	0x531840	0x8541d8	0x854198	widget	10	exact	0	exact	()	agree	
+AddFontStrings	0x530c40	0x854198	0x854198	widget	2	lower-bound	0	exact	()	agree	
+AddFriend	0x5ad290	0x85d850	0x85d830	global	1	exact	0	exact	()	agree	
+AddHistoryLine	0x798960	0x87bc68	0x87bb68	widget	2	exact	0	exact	()	agree	
+AddIgnore	0x5ad5f0	0x85d890	0x85d830	global	1	exact	0	exact	()	agree	
+AddLine	0x531630	0x8541d0	0x854198	widget	6	exact	0	exact	()	agree	
+AddMessage	0x792900	0x87b640	0x87b5c0	widget	6	exact	0	exact	()	agree	name-not-unique
+AddMessage	0x795590	0x87ba20	0x87b960	widget	6	exact	0	exact	()	agree	name-not-unique
+AddOrDelIgnore	0x5ad5a0	0x85d888	0x85d830	global	1	exact	0	exact	()	agree	
+AddQuestWatch	0x4e1930	0x84b1e8	0x84b0f0	global	1	exact	0	exact	()	agree	
+AddSkillUp	0x4d3c30	0x849d20	0x849cf8	global	1	exact	0	exact	()	agree	
+AddTradeMoney	0x4c07f0	0x847a58	0x8479f8	global	0	exact	0	exact	()	agree	
+AdvanceTime	0x76eca0	0x8789b8	0x878948	widget	1	exact	0	exact	()	agree	
+AppendText	0x531e30	0x8541e8	0x854198	widget	2	exact	0	exact	()	agree	
+AppendToFile	0x515f90	0x85041c	0x8503f4	global	0	exact	?	unknown	?	unknown	
+AssistByName	0x489c40	0x83e070	0x83de68	global	1	exact	0	exact	()	agree	
+AssistUnit	0x489b80	0x83e068	0x83de68	global	1	exact	0	exact	()	agree	
+AtBottom	0x7931f0	0x87b688	0x87b5c0	widget	1	exact	1	exact	(nil) | (number)	agree	
+AtTop	0x793130	0x87b680	0x87b5c0	widget	1	exact	1	exact	(nil) | (number)	agree	
+AttackTarget	0x489b50	0x83e060	0x83de68	global	0	exact	0	exact	()	agree	
+AutoEquipCursorItem	0x48a040	0x83e098	0x83de68	global	0	exact	0	exact	()	agree	
+BankButtonIDToInvSlotID	0x4f8530	0x84d5dc	0x84d5dc	global	2	exact	1	exact	(number)	agree	
+BeginTrade	0x48aa60	0x83e148	0x83de68	global	0	exact	0	exact	()	agree	
+BindEnchant	0x48d2e0	0x83e380	0x83de68	global	0	exact	0	exact	()	agree	
+BuyGuildCharter	0x4f5260	0x84d01c	0x84d00c	global	1	exact	1	exact	(nil) | (number)	agree	
+BuyMerchantItem	0x4fb850	0x84da60	0x84da28	global	2	exact	0	exact	()	agree	
+BuyRandomPicks	0x4c4400	0x8481d8	0x8481b8	global	1	exact	0	exact	()	agree	
+BuySkillTier	0x4d3e50	0x849d48	0x849cf8	global	1	exact	0	exact	()	agree	
+BuyStableSlot	0x4cb080	0x848db8	0x848da0	global	0	exact	0	exact	()	agree	
+BuyTrainerService	0x4da210	0x84a490	0x84a3e0	global	1	exact	0	exact	()	agree	
+BuybackItem	0x4fb950	0x84da68	0x84da28	global	1	exact	0	exact	()	agree	
+CalculateAuctionDeposit	0x4ce1c0	0x8490b8	0x8490a8	global	1	exact	1	exact	(number)	agree	
+CameraOrSelectOrMoveStart	0x514190	0x850160	0x8500b8	global	0	exact	0	exact	()	agree	
+CameraOrSelectOrMoveStop	0x5141d0	0x850168	0x8500b8	global	1	exact	0	exact	()	agree	
+CameraZoomIn	0x50b400	0x84f7a0	0x84f7a0	global	1	exact	0	exact	()	agree	
+CameraZoomOut	0x50b450	0x84f7a8	0x84f7a0	global	1	exact	0	exact	()	agree	
+CanEditGuildInfo	0x4d1c40	0x849758	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanEditMOTD	0x4d1a80	0x849738	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanEditOfficerNote	0x4d1b60	0x849748	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanEditPublicNote	0x4d1af0	0x849740	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanGuildDemote	0x4d1930	0x849720	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanGuildInvite	0x4d19a0	0x849728	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanGuildPromote	0x4d18c0	0x849718	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanGuildRemove	0x4d1a10	0x849730	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanInspect	0x48a1b0	0x83e0d0	0x83de68	global	1	exact	1	exact	(nil) | (number)	agree	
+CanJoinBattlefieldAsGroup	0x4ac380	0x8458c8	0x8457e0	global	0	exact	1	exact	(nil) | (number)	agree	
+CanMerchantRepair	0x4fba80	0x84da70	0x84da28	global	0	exact	1	exact	(nil) | (number)	agree	
+CanNonSpaceWrap	0x79ead0	0x87c2d0	0x87c1d8	widget	1	exact	1	exact	(nil) | (number)	agree	
+CanSaveTabardNow	0x503910	0x84ee88	0x84ee40	widget	0	exact	1	exact	(nil) | (number)	agree	
+CanSendAuctionQuery	0x4cfbb0	0x849130	0x8490a8	global	0	exact	1	exact	(nil) | (number)	agree	
+CanShowResetInstances	0x48a720	0x83e518	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+CanSignPetition	0x4f45e0	0x84cec0	0x84cea0	global	0	exact	1	exact	(nil) | (number)	agree	
+CanViewOfficerNote	0x4d1bd0	0x849750	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+CancelAreaSpiritHeal	0x48df30	0x83e470	0x83de68	global	0	exact	0	exact	()	agree	
+CancelAuction	0x4d0260	0x849158	0x8490a8	global	1	exact	0	exact	()	agree	
+CancelDuel	0x4d4cf0	0x849fc0	0x849fa8	global	0	exact	0	exact	()	agree	
+CancelLogout	0x48ab40	0x83e178	0x83de68	global	0	exact	0	exact	()	agree	
+CancelMeetingStoneRequest	0x4ca5a0	0x848cf0	0x848ce8	global	0	exact	0	exact	()	agree	
+CancelPendingEquip	0x489960	0x83e020	0x83de68	global	1	exact	0	exact	()	agree	
+CancelPlayerBuff	0x4e49a0	0x84bb48	0x84bb20	global	1	exact	0	exact	()	agree	
+CancelRealmListQuery	0x46ed10	0x837ea8	0x837ea0	global	0	exact	0	exact	()	agree	
+CancelSkillUps	0x4d3e30	0x849d40	0x849cf8	global	0	lower-bound	0	exact	()	agree	delegated-push
+CancelTrackingBuff	0x4e4a80	0x84bb58	0x84bb20	global	0	exact	0	exact	()	agree	
+CancelTrade	0x48aa70	0x83e150	0x83de68	global	0	exact	0	exact	()	agree	
+CancelTradeAccept	0x4c06f0	0x847a38	0x8479f8	global	0	exact	0	exact	()	agree	
+CastPetAction	0x4be330	0x8475d8	0x8475a0	global	1	exact	0	exact	()	agree	
+CastShapeshiftForm	0x4b4810	0x8466c8	0x846648	global	1	exact	0	exact	()	agree	
+CastSpell	0x4b42f0	0x846688	0x846648	global	3	lower-bound	0	exact	()	agree	
+CastSpellByName	0x4b4ab0	0x8466d8	0x846648	global	2	exact	0	exact	()	agree	
+ChangeActionBarPage	0x4e7650	0x84bda0	0x84bd10	global	0	lower-bound	0	exact	()	agree	delegated-push
+ChangeChatColor	0x4a07f0	0x8436f0	0x843618	global	4	lower-bound	0	exact	()	agree	delegated-push
+ChangeRealm	0x46f0e0	0x837ec0	0x837ea0	global	2	exact	0	exact	()	agree	
+ChannelBan	0x4a0770	0x8436d0	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelInvite	0x4a0730	0x8436c0	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelKick	0x4a0750	0x8436c8	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelModerate	0x4a07d0	0x8436e8	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelModerator	0x4a06b0	0x8436a0	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelMute	0x4a06f0	0x8436b0	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelToggleAnnouncements	0x4a07b0	0x8436e0	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelUnban	0x4a0790	0x8436d8	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelUnmoderator	0x4a06d0	0x8436a8	0x843618	global	0	lower-bound	0	exact	()	agree	
+ChannelUnmute	0x4a0710	0x8436b8	0x843618	global	0	lower-bound	0	exact	()	agree	
+CheckBinderDist	0x48d210	0x83e370	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+CheckInbox	0x4aeab0	0x845f38	0x845eb0	global	0	lower-bound	0	exact	()	agree	delegated-push
+CheckInteractDistance	0x48ba00	0x83e290	0x83de68	global	2	exact	1	exact	(nil) | (number)	agree	
+CheckPetUntrainerDist	0x48d1c0	0x83e368	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+CheckReadyCheckTime	0x4bc120	0x8472b8	0x847240	global	0	exact	0	exact	()	agree	
+CheckSpiritHealerDist	0x48d120	0x83e358	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+CheckTalentMasterDist	0x48d170	0x83e360	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+Clear	0x793e60	0x87b6f8	0x87b5c0	widget	1	exact	0	exact	()	agree	name-not-unique
+Clear	0x795840	0x87ba28	0x87b960	widget	1	exact	0	exact	()	agree	name-not-unique
+ClearAllPoints	0x7a2b70	0x87ca48	0x87c9b8	widget	1	exact	0	exact	()	agree	
+ClearCursor	0x4895b0	0x83dfe8	0x83de68	global	0	exact	1	exact	()	unverified	
+ClearFocus	0x798e60	0x87bc88	0x87bb68	widget	1	exact	0	exact	()	agree	
+ClearFog	0x76f540	0x8789f8	0x878948	widget	1	exact	0	exact	()	agree	
+ClearInspectPlayer	0x4c9780	0x848590	0x8484d0	global	0	exact	0	exact	()	agree	
+ClearLines	0x531560	0x8541c8	0x854198	widget	1	exact	0	exact	()	agree	
+ClearModel	0x76db20	0x878958	0x878948	widget	1	exact	0	exact	()	agree	
+ClearSendMail	0x4adee0	0x845eb8	0x845eb0	global	0	exact	0	exact	()	agree	
+ClearTarget	0x489ff0	0x83e090	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+ClearTutorials	0x4b5a00	0x846b14	0x846b04	global	0	exact	0	exact	()	agree	
+Click	0x7826c0	0x879e20	0x879d00	widget	2	exact	0	exact	()	agree	
+ClickAuctionSellItemButton	0x4ce310	0x8490c0	0x8490a8	global	0	lower-bound	0	exact	()	agree	delegated-push
+ClickSendMailItemButton	0x4adef0	0x845ec0	0x845eb0	global	0	lower-bound	0	exact	()	agree	delegated-push
+ClickStablePet	0x4cb420	0x848de0	0x848da0	global	1	exact	1	exact	(nil) | (number)	agree	
+ClickTargetTradeButton	0x4c0080	0x847a08	0x8479f8	global	1	exact	0	exact	()	agree	
+ClickTradeButton	0x4bfdf0	0x847a00	0x8479f8	global	1	exact	0	exact	()	agree	
+CloseAuctionHouse	0x4ce160	0x8490a8	0x8490a8	global	0	exact	0	exact	()	agree	
+CloseBankFrame	0x4f87d0	0x84d5fc	0x84d5dc	global	0	exact	0	exact	()	agree	
+CloseBattlefield	0x4ab2f0	0x845848	0x8457e0	global	0	exact	0	exact	()	agree	
+CloseCraft	0x4f6c00	0x84d108	0x84d108	global	0	exact	0	exact	()	agree	
+CloseGossip	0x4e2b20	0x84b820	0x84b7e8	global	0	exact	0	exact	()	agree	
+CloseGuildRegistrar	0x4f5220	0x84d00c	0x84d00c	global	0	exact	0	exact	()	agree	
+CloseGuildRoster	0x4d2350	0x8497b8	0x8496d8	global	0	exact	0	exact	()	agree	
+CloseItemText	0x4e3b70	0x84ba40	0x84ba00	global	0	exact	0	exact	()	agree	
+CloseLoot	0x4c2ec0	0x847d28	0x847cf0	global	1	exact	0	exact	()	agree	
+CloseLottery	0x4c4210	0x8481b8	0x8481b8	global	0	exact	0	exact	()	agree	
+CloseMail	0x4aded0	0x845eb0	0x845eb0	global	0	exact	0	exact	()	agree	
+CloseMerchant	0x4fb120	0x84da28	0x84da28	global	0	exact	0	exact	()	agree	
+ClosePetStables	0x4cae40	0x848da0	0x848da0	global	0	exact	0	exact	()	agree	
+ClosePetition	0x4f43c0	0x84cea0	0x84cea0	global	0	exact	0	exact	()	agree	
+CloseQuest	0x501a10	0x84e968	0x84e968	global	0	exact	0	exact	()	agree	
+CloseTabardCreation	0x4f5900	0x84d0b4	0x84d0b4	global	0	exact	0	exact	()	agree	
+CloseTaxiMap	0x4dcce0	0x84add8	0x84ada8	global	0	exact	0	exact	()	agree	
+CloseTrade	0x4bfdc0	0x8479f8	0x8479f8	global	0	lower-bound	0	exact	()	agree	delegated-push
+CloseTradeSkill	0x4fd7f0	0x84ddd0	0x84ddd0	global	0	exact	0	exact	()	agree	
+CloseTrainer	0x4d8d50	0x84a3e8	0x84a3e0	global	0	exact	0	exact	()	agree	
+CollapseCraftSkillLine	0x4f7c10	0x84d188	0x84d108	global	1	exact	0	exact	()	agree	
+CollapseFactionHeader	0x4d6a50	0x84a0d0	0x84a0a8	global	1	exact	0	exact	()	agree	
+CollapseQuestHeader	0x4e1730	0x84b1c0	0x84b0f0	global	1	exact	0	exact	()	agree	
+CollapseSkillHeader	0x4d3b70	0x849d10	0x849cf8	global	1	exact	0	exact	()	agree	
+CollapseTradeSkillSubClass	0x5000c0	0x84de78	0x84ddd0	global	1	exact	0	exact	()	agree	
+CollapseTrainerSkillLine	0x4da6c0	0x84a4c0	0x84a3e0	global	1	exact	0	exact	()	agree	
+CompleteQuest	0x501d70	0x84e9f8	0x84e968	global	0	exact	0	exact	()	agree	
+ConfirmAcceptQuest	0x5021b0	0x84ea50	0x84e968	global	0	exact	0	exact	()	agree	
+ConfirmBindOnUse	0x48d770	0x83e3d8	0x83de68	global	0	exact	0	exact	()	agree	
+ConfirmBinder	0x48dd00	0x83e430	0x83de68	global	0	exact	0	exact	()	agree	
+ConfirmLootRoll	0x4c33e0	0x847d68	0x847cf0	global	2	exact	0	exact	()	agree	
+ConfirmPetUnlearn	0x48dca0	0x83e428	0x83de68	global	0	exact	0	exact	()	agree	
+ConfirmReadyCheck	0x4bc090	0x8472b0	0x847240	global	1	exact	0	exact	()	agree	
+ConfirmSummon	0x48b770	0x83e260	0x83de68	global	0	exact	0	exact	()	agree	
+ConfirmTalentWipe	0x48dc40	0x83e420	0x83de68	global	0	exact	0	exact	()	agree	
+ConsoleExec	0x515f10	0x850404	0x8503f4	global	1	exact	0	exact	()	agree	
+ContainerIDToInventoryID	0x4f94e0	0x84d688	0x84d688	global	1	exact	1	exact	(number)	agree	
+ContestAccepted	0x46d120	0x837470	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+ConvertToRaid	0x4bbc90	0x847280	0x847240	global	0	exact	0	exact	()	agree	
+CopyFontObject	0x7a01b0	0x87c7f0	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	delegated-push
+CreateCharacter	0x4719e0	0x8381b0	0x8380f8	global	1	exact	0	exact	()	agree	
+CreateFont	0x706040	0x872e84	0x872e74	global	1	lower-bound	1	exact	(any)	agree	delegated-push
+CreateFontString	0x773c30	0x878ee8	0x878ec0	widget	4	lower-bound	1	exact	(any)	agree	delegated-push
+CreateFrame	0x7060b0	0x872e8c	0x872e74	global	4	lower-bound	1	exact	(any)	agree	delegated-push
+CreateMacro	0x4f15b0	0x84c990	0x84c990	global	5	exact	0|1	set	() | (number)	agree	
+CreateMiniWorldMapArrowFrame	0x4a8c60	0x845100	0x845078	global	1	exact	0	exact	()	agree	
+CreateTexture	0x773a20	0x878ee0	0x878ec0	widget	4	lower-bound	1	exact	(any)	agree	delegated-push
+CreateTitleRegion	0x773910	0x878ed8	0x878ec0	widget	1	lower-bound	1	exact	(any)	agree	delegated-push
+CreateWorldMapArrowFrame	0x4a8bb0	0x8450f8	0x845078	global	1	exact	0	exact	()	agree	
+CursorCanGoInSlot	0x4c8ff0	0x848540	0x8484d0	global	0	lower-bound	1	exact	(nil) | (number)	agree	
+CursorHasItem	0x4895d0	0x83dff0	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+CursorHasMoney	0x489630	0x83e000	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+CursorHasSpell	0x489600	0x83dff8	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+CycleCharCustomization	0x471890	0x838188	0x8380f8	global	2	exact	0	exact	()	agree	
+CycleVariation	0x502ca0	0x84ee50	0x84ee40	widget	3	exact	0	exact	()	agree	
+DeclineGroup	0x48aab0	0x83e160	0x83de68	global	0	exact	0	exact	()	agree	
+DeclineGuild	0x48ab10	0x83e170	0x83de68	global	0	exact	0	exact	()	agree	
+DeclineQuest	0x501d30	0x84e9e8	0x84e968	global	0	exact	0	exact	()	agree	
+DeclineResurrect	0x48a9d0	0x83e130	0x83de68	global	0	exact	0	exact	()	agree	
+DefaultServerLogin	0x46d160	0x837480	0x8373b8	global	2	exact	0	exact	()	agree	
+DelIgnore	0x5ad640	0x85d898	0x85d830	global	1	exact	0	exact	()	agree	
+DeleteCharacter	0x4734c0	0x8385a8	0x838578	global	1	exact	0	exact	()	agree	
+DeleteCursorItem	0x4897b0	0x83e010	0x83de68	global	0	exact	0	exact	()	agree	
+DeleteFile	0x515f70	0x850414	0x8503f4	global	0	exact	?	unknown	?	unknown	
+DeleteGMTicket	0x48cb70	0x83e320	0x83de68	global	0	exact	0	exact	()	agree	
+DeleteInboxItem	0x4afcd0	0x845f88	0x845eb0	global	1	exact	0	exact	()	agree	
+DeleteMacro	0x4f1850	0x84c9a8	0x84c990	global	1	exact	0	exact	()	agree	
+DemoteAssistant	0x4bbdf0	0x847290	0x847240	global	1	exact	0	exact	()	agree	
+Disable	0x77ffd0	0x879d08	0x879d00	widget	1	exact	0	exact	()	agree	
+DisableAddOn	0x46d8a0	0x837508	0x8373b8	global	2	exact	0	exact	()	agree	name-not-unique
+DisableAddOn	0x48e760	0x83e4c8	0x83de68	global	1	exact	0	exact	()	agree	name-not-unique
+DisableAllAddOns	0x46d940	0x837510	0x8373b8	global	1	exact	0	exact	()	agree	name-not-unique
+DisableAllAddOns	0x48e7f0	0x83e4d0	0x83de68	global	0	exact	0	exact	()	agree	name-not-unique
+DisableDrawLayer	0x775680	0x878fb8	0x878ec0	widget	2	exact	0	exact	()	agree	
+DisconnectFromServer	0x46d340	0x837498	0x8373b8	global	0	exact	0	exact	()	agree	
+DisplayChannelOwner	0x4a05c0	0x843690	0x843618	global	0	lower-bound	0	exact	()	agree	
+DoCraft	0x4f7d10	0x84d198	0x84d108	global	1	exact	0	exact	()	agree	
+DoEmote	0x49fd30	0x843640	0x843618	global	2	exact	0	exact	()	agree	
+DoReadyCheck	0x4bc080	0x8472a8	0x847240	global	0	exact	0	exact	()	agree	
+DoTradeSkill	0x500280	0x84de98	0x84ddd0	global	2	exact	0	exact	()	agree	
+Dress	0x504cd0	0x84f198	0x84f190	widget	1	exact	0	exact	()	agree	
+DropCursorMoney	0x48aba0	0x83e198	0x83de68	global	0	exact	0	exact	()	agree	
+DropItemOnUnit	0x48d960	0x83e3f8	0x83de68	global	1	exact	0	exact	()	agree	
+EULAAccepted	0x46d040	0x837440	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+EditMacro	0x4f18b0	0x84c9b0	0x84c990	global	5	exact	?	unknown	() | (number)	unverified	
+Enable	0x77fef0	0x879d00	0x879d00	widget	1	exact	0	exact	()	agree	
+EnableAddOn	0x46d7b0	0x8374f8	0x8373b8	global	2	exact	0	exact	()	agree	name-not-unique
+EnableAddOn	0x48e690	0x83e4b8	0x83de68	global	1	exact	0	exact	()	agree	name-not-unique
+EnableAllAddOns	0x46d850	0x837500	0x8373b8	global	1	exact	0	exact	()	agree	name-not-unique
+EnableAllAddOns	0x48e720	0x83e4c0	0x83de68	global	0	exact	0	exact	()	agree	name-not-unique
+EnableDrawLayer	0x7755b0	0x878fb0	0x878ec0	widget	2	exact	0	exact	()	agree	
+EnableKeyboard	0x776ec0	0x879080	0x878ec0	widget	2	exact	0	exact	()	agree	
+EnableMouse	0x777070	0x879090	0x878ec0	widget	2	exact	0	exact	()	agree	
+EnableMouseWheel	0x7771f0	0x8790a0	0x878ec0	widget	2	exact	0	exact	()	agree	
+EnableSubtitles	0x78d940	0x87ab5c	0x87ab4c	widget	2	exact	0	exact	()	agree	
+EnterWorld	0x46d3c0	0x8374a8	0x8373b8	global	0	exact	0	exact	()	agree	
+EnumerateFrames	0x705f60	0x872e7c	0x872e74	global	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+EnumerateServerChannels	0x4a1790	0x843778	0x843618	global	0	exact	?	unknown	?	unknown	
+EquipCursorItem	0x489660	0x83e008	0x83de68	global	1	exact	0	exact	()	agree	
+EquipPendingItem	0x4898f0	0x83e018	0x83de68	global	1	exact	0	exact	()	agree	
+ExpandCraftSkillLine	0x4f7c90	0x84d190	0x84d108	global	1	exact	0	exact	()	agree	
+ExpandFactionHeader	0x4d6aa0	0x84a0f0	0x84a0a8	global	1	exact	0	exact	()	agree	
+ExpandQuestHeader	0x4e1780	0x84b1c8	0x84b0f0	global	1	exact	0	exact	()	agree	
+ExpandSkillHeader	0x4d3bd0	0x849d18	0x849cf8	global	1	exact	0	exact	()	agree	
+ExpandTradeSkillSubClass	0x500140	0x84de80	0x84ddd0	global	1	exact	0	exact	()	agree	
+ExpandTrainerSkillLine	0x4da740	0x84a4c8	0x84a3e0	global	1	exact	0	exact	()	agree	
+FactionToggleAtWar	0x4d6950	0x84a0c8	0x84a0a8	global	1	exact	0	exact	()	agree	
+FadeOut	0x531f00	0x8541f0	0x854198	widget	1	exact	0	exact	()	agree	
+FlagTutorial	0x4b59b0	0x846b0c	0x846b04	global	1	exact	0	exact	()	agree	
+FlipCameraYaw	0x50b6a0	0x84f840	0x84f7a0	global	1	exact	0	exact	()	agree	
+FollowByName	0x489ec0	0x83e088	0x83de68	global	2	exact	0	exact	()	agree	
+FollowUnit	0x489e00	0x83e080	0x83de68	global	1	exact	0	exact	()	agree	
+ForceLogout	0x48ab50	0x83e180	0x83de68	global	0	exact	0	exact	()	agree	
+ForceQuit	0x48ab60	0x83e188	0x83de68	global	0	exact	0	exact	()	agree	
+FrameXML_Debug	0x488440	0x83de68	0x83de68	global	1	exact	1	exact	(number)	agree	
+GMRequestPlayerInfo	0x48d4c0	0x83e3b8	0x83de68	global	0	exact	?	unknown	?	unknown	
+GMSurveyAnswerSubmit	0x48cd30	0x83e330	0x83de68	global	3	exact	0	exact	()	agree	
+GMSurveyCommentSubmit	0x48cef0	0x83e338	0x83de68	global	1	exact	0	exact	()	agree	
+GMSurveyQuestion	0x48cc00	0x83e328	0x83de68	global	1	exact	1	exact	(nil) | (string?)	agree	
+GMSurveySubmit	0x48cf80	0x83e340	0x83de68	global	0	exact	0	exact	()	agree	
+GetAbandonQuestItems	0x4dfbe0	0x84b120	0x84b0f0	global	0	exact	0|1	set	?	unknown	
+GetAbandonQuestName	0x4dfb60	0x84b118	0x84b0f0	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetActionAutocast	0x4e6f90	0x84bd28	0x84bd10	global	1	exact	2	exact	(nil,nil) | (nil,number) | (number,nil) | (number,number)	agree	
+GetActionBarToggles	0x4e7660	0x84bda8	0x84bd10	global	0	exact	4	exact	?	unknown	
+GetActionCooldown	0x4e6ed0	0x84bd20	0x84bd10	global	1	exact	3	exact	(number,number,number)	agree	
+GetActionCount	0x4e6e70	0x84bd18	0x84bd10	global	1	exact	1	exact	(number)	agree	
+GetActionText	0x4e7050	0x84bd30	0x84bd10	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetActionTexture	0x4e6e10	0x84bd10	0x84bd10	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetActiveLevel	0x501c20	0x84e9c8	0x84e968	global	1	exact	1	exact	(number)	agree	
+GetActiveTitle	0x501b30	0x84e9b8	0x84e968	global	1	exact	1	exact	(string?)	agree	
+GetAddOnDependencies	0x46d650	0x8374e8	0x8373b8	global	1	exact	?	unknown	?	unknown	name-not-unique
+GetAddOnDependencies	0x48e5e0	0x83e4b0	0x83de68	global	1	exact	?	unknown	?	unknown	name-not-unique
+GetAddOnEnableState	0x46d6f0	0x8374f0	0x8373b8	global	2	exact	1	exact	(number)	agree	
+GetAddOnInfo	0x46d460	0x8374d8	0x8373b8	global	1	exact	8	exact	?	unknown	name-not-unique
+GetAddOnInfo	0x48e390	0x83e4a0	0x83de68	global	1	exact	7	exact	?	unknown	name-not-unique
+GetAddOnMetadata	0x48e530	0x83e4a8	0x83de68	global	2	exact	1	exact	(string?)	agree	
+GetAdjustedSkillPoints	0x4d3cb0	0x849d30	0x849cf8	global	0	exact	1	exact	(number)	agree	
+GetAlpha	0x774dc0	0x878f68	0x878ec0	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetAlpha	0x79b690	0x87c170	0x87c128	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetAlpha	0x79ca90	0x87c1f0	0x87c1d8	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetAlpha	0x7a04b0	0x87c810	0x87c7c8	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetAltArrowKeyMode	0x799790	0x87bce0	0x87bb68	widget	1	exact	1	exact	(nil) | (number)	agree	
+GetAnchorType	0x5313e0	0x8541c0	0x854198	widget	1	exact	1	exact	(string)	agree	
+GetAreaSpiritHealerTime	0x48dee0	0x83e460	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetAuctionHouseDepositRate	0x4ce170	0x8490b0	0x8490a8	global	0	exact	1	exact	(number)	agree	
+GetAuctionInvTypes	0x4cfab0	0x849128	0x8490a8	global	2	exact	0|14	set	?	unknown	
+GetAuctionItemClasses	0x4cf970	0x849118	0x8490a8	global	0	exact	?	unknown	?	unknown	
+GetAuctionItemInfo	0x4cee40	0x8490f8	0x8490a8	global	2	exact	12	exact	?	unknown	
+GetAuctionItemLink	0x4cf2f0	0x849100	0x8490a8	global	2	exact	0|1	set	() | (string?)	agree	
+GetAuctionItemSubClasses	0x4cf9c0	0x849120	0x8490a8	global	1	exact	?	unknown	?	unknown	
+GetAuctionItemTimeLeft	0x4cf470	0x849108	0x8490a8	global	2	exact	1	exact	(number)	agree	
+GetAuctionSellItemInfo	0x4ce590	0x8490c8	0x8490a8	global	0	exact	6	exact	(nil,nil,number,number,nil,number) | (string?,string?,number,number,nil,number) | (string?,string?,number,number,number,number)	agree	
+GetAvailableLevel	0x501ba0	0x84e9c0	0x84e968	global	1	exact	1	exact	(number)	agree	
+GetAvailableRaces	0x471520	0x838120	0x8380f8	global	0	exact	?	unknown	?	unknown	
+GetAvailableTitle	0x501ac0	0x84e9b0	0x84e968	global	1	exact	1	exact	(string?)	agree	
+GetBackdrop	0x777370	0x8790b0	0x878ec0	widget	2	exact	0|1	set	() | (table)	unverified	
+GetBackdropBorderColor	0x777f60	0x8790d0	0x878ec0	widget	1	exact	?	unknown	() | (number,number,number,number)	unverified	
+GetBackdropColor	0x777bc0	0x8790c0	0x878ec0	widget	1	exact	?	unknown	() | (number,number,number,number)	unverified	
+GetBagName	0x4fa670	0x84d6d8	0x84d688	global	1	lower-bound	1	exact	(nil) | (string?)	agree	delegated-push
+GetBankSlotCost	0x4f8630	0x84d5ec	0x84d5dc	global	0	exact	1	exact	(number)	agree	
+GetBaseMip	0x489280	0x83df68	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetBattlefieldEstimatedWaitTime	0x4ab790	0x845838	0x8457e0	global	1	exact	1	exact	(number)	agree	
+GetBattlefieldFlagPosition	0x4ac230	0x8458c0	0x8457e0	global	1	exact	3	exact	(number,number,nil) | (number,number,string?)	agree	
+GetBattlefieldInfo	0x4ab0b0	0x8457e8	0x8457e0	global	0	exact	?	unknown	() | (string?,number,number,number,number,number,number,number) | (string?,string?,number,number,number,number,number,number,number)	unverified	
+GetBattlefieldInstanceExpiration	0x4ab6d0	0x845828	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetBattlefieldInstanceInfo	0x4ab1f0	0x8457f0	0x8457e0	global	1	exact	?	unknown	() | (number)	unverified	
+GetBattlefieldInstanceRunTime	0x4ab730	0x845830	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetBattlefieldMapIconScale	0x4ac3d0	0x8458d0	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetBattlefieldPortExpiration	0x4ab620	0x845820	0x8457e0	global	1	exact	1	exact	(number)	agree	
+GetBattlefieldPosition	0x4abf90	0x8458b0	0x8457e0	global	1	exact	3	exact	(number,number,nil) | (number,number,string?)	agree	
+GetBattlefieldScore	0x4ab9d0	0x845868	0x8457e0	global	1	exact	9	exact	(nil,number,number,number,number,number,number,nil,nil) | (string?,number,number,number,number,number,number,nil,nil) | (string?,number,number,number,number,number,number,nil,string?) | (string?,number,number,number,number,number,number,string?,nil) | (string?,number,number,number,number,number,number,string?,string?)	agree	
+GetBattlefieldStatData	0x4abdc0	0x845898	0x8457e0	global	2	exact	1	exact	(number)	agree	
+GetBattlefieldStatInfo	0x4abd00	0x845890	0x8457e0	global	1	exact	3	exact	(nil,nil,nil) | (string?,string?,string?)	agree	
+GetBattlefieldStatus	0x4ab4a0	0x845818	0x8457e0	global	1	exact	5	exact	(nil,nil,number,number,number) | (string,nil,number,number,number) | (string,string?,number,number,number)	agree	
+GetBattlefieldTimeWaited	0x4ab820	0x845840	0x8457e0	global	1	exact	1	exact	(number)	agree	
+GetBattlefieldWinner	0x4abc40	0x845870	0x8457e0	global	0	exact	1	exact	(nil) | (number)	agree	
+GetBidderAuctionItems	0x4cecd0	0x8490e8	0x8490a8	global	1	exact	0	exact	()	agree	
+GetBillingPlan	0x46dc40	0x837578	0x8373b8	global	0	exact	3	exact	(number,number,number)	agree	
+GetBillingTimeRemaining	0x46dbf0	0x837570	0x8373b8	global	0	exact	1	exact	(number)	agree	
+GetBillingTimeRested	0x46dcf0	0x837580	0x8373b8	global	0	exact	1	exact	(number)	agree	name-not-unique
+GetBillingTimeRested	0x48ec50	0x83e508	0x83de68	global	0	exact	1	exact	(number)	agree	name-not-unique
+GetBindLocation	0x48dae0	0x83e410	0x83de68	global	0	lower-bound	1	exact	(string?)	agree	delegated-push
+GetBinding	0x4b7f60	0x846c90	0x846c88	global	1	exact	?	unknown	?	unknown	
+GetBindingAction	0x4b8120	0x846ca8	0x846c88	global	1	exact	1	exact	(string?)	agree	
+GetBindingKey	0x4b80a0	0x846ca0	0x846c88	global	1	exact	?	unknown	?	unknown	
+GetBlendMode	0x79a890	0x87c138	0x87c128	widget	1	exact	1	exact	(string?)	agree	
+GetBlinkSpeed	0x798340	0x87bc30	0x87bb68	widget	1	exact	1	exact	(number)	agree	
+GetBlockChance	0x516f60	0x850660	0x850438	global	0	exact	1	exact	(number)	agree	
+GetBonusBarOffset	0x4e7620	0x84bd98	0x84bd10	global	0	exact	1	exact	(number)	agree	
+GetBottom	0x7a1ce0	0x87ca00	0x87c9b8	widget	1	exact	1	exact	(nil) | (number)	agree	
+GetBuildInfo	0x46cd70	0x8373b8	0x8373b8	global	0	lower-bound	5	exact	(string?,string?,string,string,string)	agree	name-not-unique;delegated-push
+GetBuildInfo	0x4884a0	0x83de70	0x83de68	global	0	exact	3	exact	(string,string,string)	agree	name-not-unique
+GetButtonState	0x780180	0x879d18	0x879d00	widget	1	exact	1	exact	(string?)	agree	
+GetBuybackItemInfo	0x4fb310	0x84da40	0x84da28	global	1	exact	6	exact	(nil,nil,number,number,number,number) | (string?,string?,number,number,number,nil) | (string?,string?,number,number,number,number)	agree	
+GetCVar	0x488ba0	0x83dee8	0x83de68	global	1	exact	1	exact	(string?)	agree	
+GetCVarDefault	0x488cf0	0x83def8	0x83de68	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetCenter	0x7a1810	0x87c9e0	0x87c9b8	widget	1	exact	2	exact	(nil,nil) | (number,number)	agree	
+GetChannelList	0x4a02d0	0x843678	0x843618	global	0	exact	?	unknown	?	unknown	
+GetChannelName	0x4a05e0	0x843698	0x843618	global	1	exact	3	exact	(number,string?,number)	agree	
+GetCharacterCreateFacing	0x471910	0x838198	0x8380f8	global	0	exact	1	exact	(number)	agree	
+GetCharacterInfo	0x4732a0	0x838598	0x838578	global	1	exact	8	exact	(nil,nil,nil,number,nil,nil,number,nil) | (string?,string?,string?,number,nil,string?,number,nil) | (string?,string?,string?,number,nil,string?,number,number) | (string?,string?,string?,number,string?,string?,number,nil) | (string?,string?,string?,number,string?,string?,number,number)	agree	
+GetCharacterListUpdate	0x473270	0x838588	0x838578	global	0	exact	0	exact	()	agree	
+GetCharacterSelectFacing	0x473650	0x8385c0	0x838578	global	0	exact	1	exact	(number)	agree	
+GetChatTypeIndex	0x4a0a80	0x843700	0x843618	global	1	exact	1	exact	(number)	agree	
+GetChatWindowChannels	0x4a0dc0	0x843718	0x843618	global	1	exact	?	unknown	?	unknown	
+GetChatWindowInfo	0x4a0ba0	0x843708	0x843618	global	1	exact	0|9	set	() | (string?,number,number,number,number,number,nil,nil,nil) | (string?,number,number,number,number,number,nil,nil,number) | (string?,number,number,number,number,number,nil,number,nil) | (string?,number,number,number,number,number,nil,number,number) | (string?,number,number,number,number,number,number,nil,nil) | (string?,number,number,number,number,number,number,nil,number) | (string?,number,number,number,number,number,number,number,nil) | (string?,number,number,number,number,number,number,number,number)	agree	
+GetChatWindowMessages	0x4a0d20	0x843710	0x843618	global	1	exact	?	unknown	?	unknown	
+GetChecked	0x799ca0	0x87bf7c	0x87bf74	widget	1	exact	1	exact	(nil) | (number)	agree	
+GetCheckedTexture	0x799d60	0x87bf84	0x87bf74	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetChildren	0x774180	0x878f08	0x878ec0	widget	1	lower-bound	?	unknown	?	unknown	delegated-push
+GetClassesForRace	0x471560	0x838128	0x8380f8	global	0	exact	?	unknown	?	unknown	
+GetCoinIcon	0x48d4e0	0x83e3c0	0x83de68	global	1	exact	1	exact	(string?)	agree	
+GetColorHSV	0x78ea00	0x87abf8	0x87abb0	widget	1	exact	3	exact	(number,number,number)	agree	
+GetColorRGB	0x78ed10	0x87ac08	0x87abb0	widget	1	exact	3	exact	(number,number,number)	agree	
+GetColorValueTexture	0x78e360	0x87abd0	0x87abb0	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetColorValueThumbTexture	0x78e630	0x87abe0	0x87abb0	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetColorWheelTexture	0x78dd80	0x87abb0	0x87abb0	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetColorWheelThumbTexture	0x78e070	0x87abc0	0x87abb0	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetComboPoints	0x51a190	0x850638	0x850438	global	0	exact	1	exact	(number)	agree	
+GetContainerItemCooldown	0x4f99b0	0x84d6a8	0x84d688	global	2	lower-bound	3	exact	(number,number,number)	agree	
+GetContainerItemInfo	0x4f9670	0x84d698	0x84d688	global	2	lower-bound	0|5	set	() | (string?,number,nil,number,nil) | (string?,number,nil,number,number) | (string?,number,number,number,nil) | (string?,number,number,number,number)	agree	
+GetContainerItemLink	0x4f9930	0x84d6a0	0x84d688	global	2	lower-bound	0|1	set	() | (string?)	agree	
+GetContainerNumSlots	0x4f9560	0x84d690	0x84d688	global	1	exact	1	exact	(number)	agree	
+GetCorpseMapPosition	0x4a86d0	0x8450c8	0x845078	global	0	exact	2	exact	(number,number)	agree	
+GetCorpseRecoveryDelay	0x48b5e0	0x83e238	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetCraftButtonToken	0x4f6c90	0x84d118	0x84d108	global	0	exact	1	exact	(string?)	agree	
+GetCraftDescription	0x4f7a90	0x84d180	0x84d108	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetCraftDisplaySkillLine	0x4f6cb0	0x84d120	0x84d108	global	0	exact	3	exact	(nil,number,number) | (string?,number,number)	agree	
+GetCraftIcon	0x4f7160	0x84d148	0x84d108	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetCraftInfo	0x4f6e90	0x84d130	0x84d108	global	1	exact	7	exact	(nil,nil,nil,number,nil,number,number) | (string?,nil,string,number,nil,number,number) | (string?,nil,string,number,number,number,number) | (string?,string?,string?,number,nil,number,number)	agree	
+GetCraftItemLink	0x4f72a0	0x84d158	0x84d108	global	1	exact	0|1	set	() | (string?)	agree	
+GetCraftName	0x4f6c10	0x84d110	0x84d108	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetCraftNumReagents	0x4f7420	0x84d160	0x84d108	global	1	exact	1	exact	(number)	agree	
+GetCraftReagentInfo	0x4f74d0	0x84d168	0x84d108	global	2	exact	4	exact	(nil,nil,nil,nil) | (nil,nil,number,number) | (string?,string?,number,number)	agree	
+GetCraftReagentItemLink	0x4f7730	0x84d170	0x84d108	global	2	exact	1	exact	(nil) | (string?)	agree	
+GetCraftSelectionIndex	0x4f7130	0x84d140	0x84d108	global	0	exact	1	exact	(number)	agree	
+GetCraftSkillLine	0x4f7210	0x84d150	0x84d108	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetCraftSpellFocus	0x4f78b0	0x84d178	0x84d108	global	1	exact	?	unknown	?	unknown	
+GetCurrentBindingSet	0x4b8200	0x846cb8	0x846c88	global	0	exact	1	exact	(number)	agree	
+GetCurrentLine	0x793720	0x87b6b0	0x87b5c0	widget	1	exact	1	exact	(number)	agree	
+GetCurrentMapContinent	0x4a7ed0	0x8450a0	0x845078	global	0	exact	1	exact	(number)	agree	
+GetCurrentMapZone	0x4a7f00	0x8450a8	0x845078	global	0	exact	1	exact	(number)	agree	
+GetCurrentMultisampleFormat	0x48c580	0x83e2c8	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetCurrentResolution	0x48bf10	0x83e2a0	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetCurrentScroll	0x793650	0x87b6a8	0x87b5c0	widget	1	exact	1	exact	(number)	agree	
+GetCursorMoney	0x48ab70	0x83e190	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetCursorPosition	0x46dad0	0x837548	0x8373b8	global	0	exact	2	exact	(number,number)	agree	name-not-unique
+GetCursorPosition	0x48b820	0x83e268	0x83de68	global	0	exact	2	exact	(number,number)	agree	name-not-unique
+GetDamageBonusStat	0x48b520	0x83e228	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetDebugStats	0x488af0	0x83ded8	0x83de68	global	0	exact	0	exact	()	agree	
+GetDefaultLanguage	0x49fcd0	0x843638	0x843618	global	0	exact	0|1	set	() | (string?)	agree	
+GetDisabledCheckedTexture	0x79a050	0x87bf94	0x87bf74	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetDisabledFontObject	0x780640	0x879d40	0x879d00	widget	1	lower-bound	?	unknown	()	unverified	delegated-push
+GetDisabledTextColor	0x781480	0x879da0	0x879d00	widget	1	exact	4	exact	(number,number,number,number)	agree	
+GetDisabledTexture	0x781cf0	0x879de0	0x879d00	widget	0	exact	?	unknown	?	unknown	delegated-push
+GetDodgeChance	0x516f00	0x850658	0x850438	global	0	exact	1	exact	(number)	agree	
+GetDoodadAnim	0x489060	0x83df40	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetDrawLayer	0x79a6c0	0x87c128	0x87c128	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetDrawLayer	0x79c660	0x87c1d8	0x87c1d8	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetEffectiveScale	0x774fc0	0x878f78	0x878ec0	widget	1	exact	1	exact	(number)	agree	
+GetFacialHairCustomization	0x471620	0x838138	0x8380f8	global	0	exact	1	exact	(string) | (string?)	agree	
+GetFacing	0x76eb20	0x8789a8	0x878948	widget	1	exact	1	exact	(number)	agree	
+GetFactionForRace	0x471450	0x838118	0x8380f8	global	0	exact	2	exact	(nil,nil) | (string?,string?)	agree	
+GetFactionInfo	0x4d64f0	0x84a0b0	0x84a0a8	global	1	lower-bound	11	exact	?	unknown	delegated-push
+GetFadeDuration	0x793da0	0x87b6f0	0x87b5c0	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetFadeDuration	0x7954d0	0x87ba18	0x87b960	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetFading	0x793a40	0x87b6d0	0x87b5c0	widget	1	exact	1	exact	(nil) | (number)	agree	name-not-unique
+GetFading	0x795170	0x87b9f8	0x87b960	widget	1	exact	1	exact	(nil) | (number)	agree	name-not-unique
+GetFarclip	0x488f00	0x83df20	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetFirstTradeSkill	0x5001c0	0x84de88	0x84ddd0	global	0	exact	1	exact	(number)	agree	
+GetFogColor	0x76f080	0x8789d0	0x878948	widget	1	exact	4	exact	(number,number,number,number)	agree	
+GetFogFar	0x76f480	0x8789f0	0x878948	widget	1	exact	1	exact	(number)	agree	
+GetFogNear	0x76f2d0	0x8789e0	0x878948	widget	1	exact	1	exact	(number)	agree	
+GetFont	0x7809a0	0x879d60	0x879d00	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFont	0x791f40	0x87b5d8	0x87b5c0	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFont	0x794510	0x87b978	0x87b960	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFont	0x796000	0x87ba98	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFont	0x7972d0	0x87bb80	0x87bb68	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFont	0x79d400	0x87c238	0x87c1d8	widget	1	exact	3	exact	(string?,number,string?)	agree	name-not-unique
+GetFont	0x7a0330	0x87c800	0x87c7c8	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFontObject	0x791dc0	0x87b5c8	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFontObject	0x794370	0x87b968	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFontObject	0x795e60	0x87ba88	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFontObject	0x797150	0x87bb70	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFontObject	0x79d0b0	0x87c228	0x87c1d8	widget	1	lower-bound	1	exact	(any) | (nil)	agree	name-not-unique;delegated-push
+GetFontObject	0x7a00f0	0x87c7e8	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetFontString	0x780c30	0x879d70	0x879d00	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetFrameLevel	0x7744a0	0x878f20	0x878ec0	widget	1	exact	1	exact	(number)	agree	
+GetFrameStrata	0x7742a0	0x878f10	0x878ec0	widget	1	exact	1	exact	(string?)	agree	
+GetFrameType	0x773640	0x878ec0	0x878ec0	widget	1	exact	1	exact	(string?)	agree	
+GetFramerate	0x4893e0	0x83deb8	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetFriendInfo	0x5ad060	0x85d838	0x85d830	global	1	lower-bound	6	exact	(string?,number,string?,string?,nil,string?) | (string?,number,string?,string?,number,string?)	agree	delegated-push
+GetGMStatus	0x48cfc0	0x83e348	0x83de68	global	0	exact	0	exact	()	agree	
+GetGMTicket	0x48c9a0	0x83e308	0x83de68	global	0	exact	0	exact	()	agree	
+GetGMTicketCategories	0x48d8d0	0x83e3f0	0x83de68	global	0	exact	?	unknown	()	unverified	delegated-push
+GetGameTime	0x515ee0	0x8503fc	0x8503f4	global	0	exact	2	exact	(number,number)	agree	
+GetGamma	0x4891c0	0x83df70	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetGossipActiveQuests	0x4e29b0	0x84b800	0x84b7e8	global	0	exact	?	unknown	?	unknown	
+GetGossipAvailableQuests	0x4e2930	0x84b7f8	0x84b7e8	global	0	exact	?	unknown	?	unknown	
+GetGossipOptions	0x4e28d0	0x84b7f0	0x84b7e8	global	0	exact	?	unknown	?	unknown	
+GetGossipText	0x4e28c0	0x84b7e8	0x84b7e8	global	0	exact	1	exact	(string?)	agree	
+GetGreetingText	0x501a30	0x84e978	0x84e968	global	0	exact	1	exact	(string?)	agree	
+GetGuildCharterCost	0x4f5230	0x84d014	0x84d00c	global	0	exact	1	exact	(number)	agree	
+GetGuildInfo	0x4c9330	0x848558	0x8484d0	global	1	exact	3	exact	(nil,nil,number) | (string?,string?,number)	agree	
+GetGuildInfoText	0x4d2370	0x8497c8	0x8496d8	global	0	exact	1	exact	(string?)	agree	
+GetGuildRecruitmentMode	0x4a0040	0x843788	0x843618	global	0	exact	1	exact	(number)	agree	
+GetGuildRosterInfo	0x4d1200	0x8496e8	0x8496d8	global	1	lower-bound	10	exact	?	unknown	delegated-push
+GetGuildRosterLastOnline	0x4d14a0	0x8496f0	0x8496d8	global	1	exact	4	exact	(nil,nil,nil,nil) | (number,number,number,number)	agree	
+GetGuildRosterMOTD	0x4d11f0	0x8496e0	0x8496d8	global	0	exact	1	exact	(string?)	agree	
+GetGuildRosterSelection	0x4d1890	0x849710	0x8496d8	global	0	exact	1	exact	(number)	agree	
+GetGuildRosterShowOffline	0x4d1e30	0x849770	0x8496d8	global	0	exact	1	exact	(nil) | (number)	agree	
+GetHairCustomization	0x4715d0	0x838130	0x8380f8	global	0	exact	1	exact	(string) | (string?)	agree	
+GetHeight	0x7a2030	0x87ca18	0x87c9b8	widget	1	exact	1	exact	(number)	agree	
+GetHighlightFontObject	0x7807c0	0x879d50	0x879d00	widget	1	lower-bound	?	unknown	()	unverified	delegated-push
+GetHighlightTextColor	0x781800	0x879db0	0x879d00	widget	1	exact	4	exact	(number,number,number,number)	agree	
+GetHighlightTexture	0x781f40	0x879df0	0x879d00	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetHistoryLines	0x799390	0x87bcb8	0x87bb68	widget	1	exact	1	exact	(number)	agree	
+GetHitRectInsets	0x775bf0	0x878ff0	0x878ec0	widget	1	exact	4	exact	(number,number,number,number)	agree	
+GetHorizontalScroll	0x791530	0x87b3e0	0x87b3c0	widget	1	exact	1	exact	(number)	agree	
+GetHorizontalScrollRange	0x7916f0	0x87b3f0	0x87b3c0	widget	1	exact	1	exact	(number)	agree	
+GetHyperlinkFormat	0x796c30	0x87bb10	0x87ba80	widget	1	exact	1	exact	(string?)	agree	
+GetID	0x775280	0x878f90	0x878ec0	widget	1	exact	1	exact	(number)	agree	
+GetIgnoreName	0x5ad460	0x85d870	0x85d830	global	1	lower-bound	1	exact	(string?)	agree	delegated-push
+GetInboxHeaderInfo	0x4aebc0	0x845f48	0x845eb0	global	1	lower-bound	13	exact	?	unknown	delegated-push
+GetInboxInvoiceInfo	0x4af360	0x845f58	0x845eb0	global	1	exact	7	exact	(nil,nil,nil,number,number,number,number) | (string,string?,string?,number,number,number,number)	agree	
+GetInboxItem	0x4af5d0	0x845f60	0x845eb0	global	1	exact	5	exact	(nil,nil,number,number,nil) | (string?,string?,number,number,nil) | (string?,string?,number,number,number)	agree	
+GetInboxNumItems	0x4aeb90	0x845f40	0x845eb0	global	0	exact	1	exact	(number)	agree	
+GetInboxText	0x4af110	0x845f50	0x845eb0	global	1	exact	4	exact	?	unknown	
+GetInputLanguage	0x799550	0x87bcc8	0x87bb68	widget	1	exact	1	exact	(string?)	agree	
+GetInsertMode	0x794ff0	0x87b9e8	0x87b960	widget	1	exact	1	exact	(string) | (string?)	agree	
+GetInspectHonorData	0x4c9620	0x848588	0x8484d0	global	0	exact	12	exact	(number,number,number,number,number,number,number,number,number,number,number,number)	agree	
+GetInspectPVPRankProgress	0x51ab00	0x8506c8	0x850438	global	0	exact	1	exact	(number)	agree	
+GetInstanceBootTimeRemaining	0x48b620	0x83e240	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetInventoryAlertStatus	0x4c94b0	0x848560	0x8484d0	global	1	exact	1	exact	(number)	agree	
+GetInventoryItemBroken	0x4c8590	0x8484e0	0x8484d0	global	1	lower-bound	1	exact	(nil) | (number)	agree	
+GetInventoryItemCooldown	0x4c8a60	0x8484f8	0x8484d0	global	1	lower-bound	3	exact	(number,number,number)	agree	
+GetInventoryItemCount	0x4c8680	0x8484e8	0x8484d0	global	1	lower-bound	1	exact	(number)	agree	
+GetInventoryItemLink	0x4c8c10	0x848500	0x8484d0	global	1	lower-bound	0|1	set	() | (string?)	agree	
+GetInventoryItemQuality	0x4c88d0	0x8484f0	0x8484d0	global	1	lower-bound	1	exact	(nil) | (number)	agree	
+GetInventoryItemTexture	0x4c82a0	0x8484d8	0x8484d0	global	1	lower-bound	1	exact	(nil) | (string?)	agree	
+GetInventorySlotInfo	0x4c81b0	0x8484d0	0x8484d0	global	1	exact	3	exact	(number,string?,nil) | (number,string?,number)	agree	
+GetItemInfo	0x48e070	0x83e490	0x83de68	global	1	exact	0|9	set	() | (string?,string?,number,number,string?,string?,number,string?,string?)	agree	
+GetItemQualityColor	0x48dfb0	0x83e488	0x83de68	global	1	exact	4	exact	(number,number,number,string?)	agree	
+GetJackpotAmount	0x4c45d0	0x8481f0	0x8481b8	global	0	exact	0	exact	(number)	unverified	stack-leak
+GetJustifyH	0x7926c0	0x87b628	0x87b5c0	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyH	0x794c90	0x87b9c8	0x87b960	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyH	0x796820	0x87bae8	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyH	0x797a50	0x87bbd0	0x87bb68	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyH	0x79e5f0	0x87c2a8	0x87c1d8	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetJustifyH	0x7a0c30	0x87c860	0x87c7c8	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyV	0x792840	0x87b638	0x87b5c0	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyV	0x794e10	0x87b9d8	0x87b960	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyV	0x7969c0	0x87baf8	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyV	0x797bd0	0x87bbe0	0x87bb68	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetJustifyV	0x79e7f0	0x87c2b8	0x87c1d8	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetJustifyV	0x7a0db0	0x87c870	0x87c7c8	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetLFGResults	0x4e98c0	0x84c1d8	0x84c170	global	1	exact	7	exact	?	unknown	
+GetLFGTypeEntries	0x4e9aa0	0x84c1e8	0x84c170	global	1	exact	?	unknown	?	unknown	
+GetLFGTypes	0x4e9a70	0x84c1e0	0x84c170	global	0	exact	5	exact	?	unknown	
+GetLanguageByIndex	0x49fbe0	0x843630	0x843618	global	1	exact	0|1	set	() | (string?)	agree	
+GetLastLotteryNumbers	0x4c4220	0x8481c0	0x8481b8	global	0	exact	0	exact	()	agree	
+GetLeft	0x7a1980	0x87c9e8	0x87c9b8	widget	1	exact	1	exact	(nil) | (number)	agree	
+GetLight	0x76e7d0	0x878998	0x878948	widget	1	exact	7|10|13	set	(number,number,number,number,number,number,number) | (number,number,number,number,number,number,number,number,number,number) | (number,number,number,number,number,number,number,number,number,number,number,number,number)	agree	
+GetLocale	0x46ce40	0x8373c0	0x8373b8	global	0	exact	1	exact	(string?)	agree	name-not-unique
+GetLocale	0x48d8b0	0x83e3e8	0x83de68	global	0	exact	1	exact	(string?)	agree	name-not-unique
+GetLookingForGroup	0x4e95d0	0x84c1b8	0x84c170	global	0	exact	4	exact	?	unknown	
+GetLootMethod	0x4e91b0	0x84c198	0x84c170	global	0	exact	2	exact	(string,nil) | (string,number)	agree	
+GetLootRollItemInfo	0x4c3050	0x847d48	0x847cf0	global	1	exact	5	exact	(nil,nil,number,number,nil) | (string?,string?,number,number,nil) | (string?,string?,number,number,number)	agree	
+GetLootRollItemLink	0x4c31f0	0x847d50	0x847cf0	global	1	exact	0|1	set	() | (string?)	agree	
+GetLootRollTimeLeft	0x4c32d0	0x847d58	0x847cf0	global	1	exact	1	exact	(number)	agree	
+GetLootSlotInfo	0x4c2c60	0x847d00	0x847cf0	global	1	exact	4	exact	(string?,string?,number,number)	agree	
+GetLootSlotLink	0x4c2d20	0x847d08	0x847cf0	global	1	exact	1	exact	(string?)	agree	
+GetLootThreshold	0x4e94e0	0x84c1a8	0x84c170	global	0	exact	1	exact	(number)	agree	
+GetLotteryPrizeInfo	0x4c44e0	0x8481e8	0x8481b8	global	1	exact	5	exact	(string?,string?,number,number,nil) | (string?,string?,number,number,number)	agree	
+GetLowerBackgroundFileName	0x502ea0	0x84ee60	0x84ee40	widget	1	exact	1	exact	(string?)	agree	
+GetLowerEmblemFileName	0x503070	0x84ee70	0x84ee40	widget	1	exact	1	exact	(string?)	agree	
+GetLowerEmblemTexture	0x503540	0x84ee80	0x84ee40	widget	2	exact	0	exact	()	agree	
+GetMacroIconInfo	0x4f1a30	0x84c9c0	0x84c990	global	1	exact	1	exact	(string?)	agree	
+GetMacroIndexByName	0x4f1b30	0x84c9d0	0x84c990	global	1	exact	1	exact	(number)	agree	
+GetMacroInfo	0x4f1760	0x84c9a0	0x84c990	global	1	exact	4	exact	(nil,nil,nil,nil) | (string?,nil,string?,nil) | (string?,nil,string?,number) | (string?,string?,string?,nil) | (string?,string?,string?,number)	agree	
+GetMapContinents	0x4a7ce0	0x845078	0x845078	global	0	exact	?	unknown	?	unknown	
+GetMapInfo	0x4a7e30	0x845098	0x845078	global	0	exact	3	exact	(string?,number,number)	agree	
+GetMapLandmarkInfo	0x4a8740	0x8450d8	0x845078	global	1	exact	5	exact	(nil,nil,number,number,number) | (string?,nil,number,number,number) | (string?,string?,number,number,number)	agree	
+GetMapOverlayInfo	0x4a8a00	0x8450f0	0x845078	global	1	exact	7	exact	(nil,number,number,number,number,number,number) | (string?,number,number,number,number,number,number)	agree	
+GetMapZones	0x4a7d10	0x845080	0x845078	global	1	exact	?	unknown	?	unknown	
+GetMasterLootCandidate	0x4c2f10	0x847d38	0x847cf0	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetMaxBytes	0x799040	0x87bc98	0x87bb68	widget	1	exact	1	exact	(number)	agree	
+GetMaxLetters	0x799200	0x87bca8	0x87bb68	widget	1	exact	1	exact	(number)	agree	
+GetMaxLines	0x7937e0	0x87b6b8	0x87b5c0	widget	1	exact	1	exact	(number)	agree	
+GetMaxResize	0x7761a0	0x879010	0x878ec0	widget	1	exact	2	exact	(number,number)	agree	
+GetMeetingStoneStatusText	0x4ca5b0	0x848cf8	0x848ce8	global	0	exact	1	exact	(string?)	agree	
+GetMerchantItemInfo	0x4fb150	0x84da38	0x84da28	global	1	exact	6	exact	(nil,nil,number,number,number,number) | (nil,string?,number,number,number,nil) | (nil,string?,number,number,number,number) | (string?,string?,number,number,number,nil) | (string?,string?,number,number,number,number)	agree	
+GetMerchantItemLink	0x4fb580	0x84da48	0x84da28	global	1	exact	0|1	set	() | (string?)	agree	
+GetMerchantItemMaxStack	0x4fb670	0x84da50	0x84da28	global	1	exact	1	exact	(number)	agree	
+GetMerchantNumItems	0x4fb130	0x84da30	0x84da28	global	0	exact	1	exact	(number)	agree	
+GetMinMaxValues	0x78f3f0	0x87b020	0x87b010	widget	1	exact	2	exact	(number,number)	agree	name-not-unique
+GetMinMaxValues	0x7906e0	0x87b280	0x87b260	widget	1	exact	2	exact	(number,number)	agree	name-not-unique
+GetMinResize	0x775f20	0x879000	0x878ec0	widget	1	exact	2	exact	(number,number)	agree	
+GetMinigameState	0x4c4df0	0x84839c	0x84838c	global	0	exact	?	unknown	()	unverified	
+GetMinigameType	0x4c4d50	0x84838c	0x84838c	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetMinimapZoneText	0x48a100	0x83e0c0	0x83de68	global	0	exact	1	exact	(string?)	agree	
+GetModel	0x76da50	0x878950	0x878948	widget	1	exact	1	exact	() | (string?)	unverified	
+GetModelScale	0x76ebe0	0x8789b0	0x878948	widget	1	exact	1	exact	(number)	agree	
+GetMoney	0x518160	0x850578	0x850438	global	0	exact	1	exact	(number)	agree	
+GetMoneyPrizes	0x4c45f0	0x8481f8	0x8481b8	global	0	exact	0	exact	(number,number,number)	unverified	stack-leak
+GetMouseFocus	0x48df40	0x83e478	0x83de68	global	0	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetMovieResolution	0x46cf10	0x837400	0x8373b8	global	0	exact	1	exact	(number)	agree	
+GetMovieSubtitles	0x46dbc0	0x837568	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+GetMultisampleFormats	0x48c360	0x83e2c0	0x83de68	global	0	exact	?	unknown	?	unknown	
+GetName	0x79ff60	0x87c7d8	0x87c7c8	widget	1	exact	1	exact	(nil) | (string?)	agree	name-not-unique
+GetName	0x7a1390	0x87c9c8	0x87c9b8	widget	1	exact	1	exact	(nil) | (string?)	agree	name-not-unique
+GetNameForRace	0x4713f0	0x838110	0x8380f8	global	0	exact	2	exact	(nil,nil) | (string?,string?)	agree	
+GetNetStats	0x48b8b0	0x83e270	0x83de68	global	0	exact	3	exact	(number,number,number)	agree	
+GetNextDrawTime	0x4c4630	0x848200	0x8481b8	global	0	exact	0	exact	(number)	unverified	stack-leak
+GetNextStableSlotCost	0x4cb3d0	0x848dd8	0x848da0	global	0	exact	1	exact	(number)	agree	
+GetNormalTexture	0x781bb0	0x879dc0	0x879d00	widget	0	exact	?	unknown	?	unknown	delegated-push
+GetNumActiveQuests	0x501aa0	0x84e9a8	0x84e968	global	0	exact	1	exact	(number)	agree	
+GetNumAddOns	0x46d420	0x8374d0	0x8373b8	global	0	exact	1	exact	(number)	agree	name-not-unique
+GetNumAddOns	0x48e350	0x83e498	0x83de68	global	0	exact	1	exact	(number)	agree	name-not-unique
+GetNumAuctionItems	0x4ced20	0x8490f0	0x8490a8	global	1	exact	2	exact	() | (number,number)	unverified	
+GetNumAvailableQuests	0x501a80	0x84e9a0	0x84e968	global	0	exact	1	exact	(number)	agree	
+GetNumBankSlots	0x4f85b0	0x84d5e4	0x84d5dc	global	0	exact	2	exact	(number,nil) | (number,number)	agree	
+GetNumBattlefieldFlagPositions	0x4ac1c0	0x8458b8	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetNumBattlefieldPositions	0x4abf00	0x8458a8	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetNumBattlefieldScores	0x4ab9a0	0x845860	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetNumBattlefieldStats	0x4abcd0	0x845888	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetNumBattlefields	0x4ab080	0x8457e0	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetNumBindings	0x4b7f40	0x846c88	0x846c88	global	0	exact	1	exact	(number)	agree	
+GetNumBuybackItems	0x4fc160	0x84dab0	0x84da28	global	0	exact	1	exact	(number)	agree	
+GetNumCharacters	0x473280	0x838590	0x838578	global	0	exact	1	exact	(number)	agree	
+GetNumChildren	0x774080	0x878f00	0x878ec0	widget	1	exact	1	exact	(number)	agree	
+GetNumCrafts	0x4f6e70	0x84d128	0x84d108	global	0	exact	1	exact	(number)	agree	
+GetNumFactions	0x4d64c0	0x84a0a8	0x84a0a8	global	0	exact	1	exact	(number)	agree	
+GetNumFrames	0x705f00	0x872e74	0x872e74	global	0	exact	1	exact	(number)	agree	
+GetNumFriends	0x5ad000	0x85d830	0x85d830	global	0	exact	1	exact	(number)	agree	
+GetNumGuildMembers	0x4d1190	0x8496d8	0x8496d8	global	1	exact	1	exact	(number)	agree	
+GetNumIgnores	0x5ad400	0x85d868	0x85d830	global	0	exact	1	exact	(number)	agree	
+GetNumLFGResults	0x4e9870	0x84c1d0	0x84c170	global	0	exact	2	exact	(number,number)	agree	
+GetNumLaguages	0x49fb30	0x843628	0x843618	global	0	exact	0|1	set	() | (number)	agree	
+GetNumLetters	0x7992c0	0x87bcb0	0x87bb68	widget	1	exact	1	exact	(number)	agree	
+GetNumLinesDisplayed	0x793590	0x87b6a0	0x87b5c0	widget	1	exact	1	exact	(number)	agree	
+GetNumLootItems	0x4c2c30	0x847cf8	0x847cf0	global	0	exact	1	exact	(number)	agree	
+GetNumLotteryPrizes	0x4c44b0	0x8481e0	0x8481b8	global	0	exact	0	exact	(number)	unverified	stack-leak
+GetNumMacroIcons	0x4f19f0	0x84c9b8	0x84c990	global	0	exact	1	exact	(number)	agree	
+GetNumMacros	0x4f1710	0x84c998	0x84c990	global	0	exact	2	exact	(number,number)	agree	
+GetNumMapLandmarks	0x4a8710	0x8450d0	0x845078	global	0	exact	1	exact	(number)	agree	
+GetNumMapOverlays	0x4a89d0	0x8450e8	0x845078	global	0	exact	1	exact	(number)	agree	
+GetNumMessages	0x7934d0	0x87b698	0x87b5c0	widget	1	exact	1	exact	(number)	agree	
+GetNumPackages	0x4ae430	0x845f08	0x845eb0	global	0	exact	1	exact	(number)	agree	
+GetNumPartyMembers	0x4e9050	0x84c170	0x84c170	global	0	exact	1	exact	(number)	agree	
+GetNumPastDrawResults	0x4c4660	0x848208	0x8481b8	global	0	exact	0	exact	(number)	unverified	stack-leak
+GetNumPetitionNames	0x4f44e0	0x84ceb0	0x84cea0	global	0	exact	1	exact	(number)	agree	
+GetNumPoints	0x7a2260	0x87ca28	0x87c9b8	widget	1	exact	1	exact	(number)	agree	
+GetNumQuestChoices	0x501f00	0x84ea28	0x84e968	global	0	exact	1	exact	(number)	agree	
+GetNumQuestItems	0x501f40	0x84ea30	0x84e968	global	0	exact	1	exact	(number)	agree	
+GetNumQuestLeaderBoards	0x4e0000	0x84b140	0x84b0f0	global	1	exact	1	exact	(number)	agree	
+GetNumQuestLogChoices	0x4e0a70	0x84b168	0x84b0f0	global	0	exact	1	exact	(number)	agree	
+GetNumQuestLogEntries	0x4df8b0	0x84b0f0	0x84b0f0	global	0	exact	2	exact	(number,number)	agree	
+GetNumQuestLogRewards	0x4e09e0	0x84b160	0x84b0f0	global	0	exact	1	exact	(number)	agree	
+GetNumQuestRewards	0x501ec0	0x84ea20	0x84e968	global	0	exact	1	exact	(number)	agree	
+GetNumQuestWatches	0x4e1860	0x84b1d8	0x84b0f0	global	0	exact	1	exact	(number)	agree	
+GetNumRaidMembers	0x4bb530	0x847240	0x847240	global	0	exact	1	exact	(number)	agree	
+GetNumRealms	0x46ed30	0x837eb0	0x837ea0	global	1	exact	1	exact	(number)	agree	
+GetNumRegions	0x773e60	0x878ef0	0x878ec0	widget	1	exact	1	exact	(number)	agree	
+GetNumRoutes	0x4dced0	0x84ae10	0x84ada8	global	1	exact	1	exact	(number)	agree	
+GetNumSavedInstances	0x4a18f0	0x843798	0x843618	global	0	exact	1	exact	(number)	agree	
+GetNumShapeshiftForms	0x4b4590	0x8466b8	0x846648	global	0	exact	1	exact	(number)	agree	
+GetNumSkillLines	0x4d35e0	0x849cf8	0x849cf8	global	0	exact	1	exact	(number)	agree	
+GetNumSpellTabs	0x4b3cb0	0x846648	0x846648	global	0	exact	1	exact	(number)	agree	
+GetNumStablePets	0x4cb1d0	0x848dc0	0x848da0	global	0	exact	1	exact	(number)	agree	
+GetNumStableSlots	0x4cb200	0x848dc8	0x848da0	global	0	exact	1	exact	(number)	agree	
+GetNumStationeries	0x4ae1f0	0x845ee8	0x845eb0	global	0	exact	1	exact	(number)	agree	
+GetNumTalentTabs	0x4f3010	0x84ccf0	0x84ccf0	global	0	exact	1	exact	(number)	agree	
+GetNumTalents	0x4f3160	0x84cd00	0x84ccf0	global	1	exact	1	exact	(number)	agree	
+GetNumTradeSkills	0x4fd800	0x84ddd8	0x84ddd0	global	0	exact	1	exact	(number)	agree	
+GetNumTrainerServices	0x4d8d90	0x84a3f0	0x84a3e0	global	0	exact	1	exact	(number)	agree	
+GetNumWhoResults	0x5ad690	0x85d8a8	0x85d830	global	0	exact	2	exact	(number,number)	agree	
+GetNumWorldStateUI	0x4c5a40	0x848414	0x848414	global	0	exact	1	exact	(number)	agree	
+GetNumber	0x798790	0x87bc58	0x87bb68	widget	1	exact	1	exact	(number)	agree	
+GetObjectType	0x79fda0	0x87c7c8	0x87c7c8	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetObjectType	0x7a11d0	0x87c9b8	0x87c9b8	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetObjectiveText	0x501a50	0x84e988	0x84e968	global	0	exact	1	exact	(string?)	agree	
+GetOrientation	0x78f1d0	0x87b010	0x87b010	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetOrientation	0x7904c0	0x87b270	0x87b260	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetOwnerAuctionItems	0x4cec80	0x8490e0	0x8490a8	global	1	exact	0	exact	()	agree	
+GetPVPLastWeekStats	0x51a6c0	0x8506a0	0x850438	global	0	exact	4	exact	(number,number,number,number)	agree	
+GetPVPLifetimeStats	0x51a7c0	0x8506a8	0x850438	global	0	exact	3	exact	(number,number,number)	agree	
+GetPVPRankInfo	0x51a930	0x8506b8	0x850438	global	2	lower-bound	2	exact	(nil,number) | (string?,number)	agree	delegated-push
+GetPVPRankProgress	0x51aa90	0x8506c0	0x850438	global	0	exact	1	exact	(number)	agree	
+GetPVPSessionStats	0x51a4b0	0x850688	0x850438	global	0	exact	2	exact	(number,number)	agree	
+GetPVPThisWeekStats	0x51a620	0x850698	0x850438	global	0	exact	2	exact	(number,number)	agree	
+GetPVPYesterdayStats	0x51a550	0x850690	0x850438	global	0	exact	3	exact	(number,number,number)	agree	
+GetPackageInfo	0x4ae450	0x845f10	0x845eb0	global	1	exact	3	exact	(nil,nil,number) | (string?,string?,number)	agree	
+GetParent	0x7a1460	0x87c9d0	0x87c9b8	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetParryChance	0x516fc0	0x850668	0x850438	global	0	exact	1	exact	(number)	agree	
+GetPartyLeaderIndex	0x4e9100	0x84c180	0x84c170	global	0	exact	1	exact	(number)	agree	
+GetPartyMember	0x4e9090	0x84c178	0x84c170	global	1	exact	1	exact	(nil) | (number)	agree	
+GetPastDrawResult	0x4c4690	0x848210	0x8481b8	global	1	exact	5	exact	(number,number,number,number,number)	agree	
+GetPetActionCooldown	0x4bdfa0	0x8475b0	0x8475a0	global	1	exact	3	exact	(number,number,number)	agree	
+GetPetActionInfo	0x4bdc50	0x8475a8	0x8475a0	global	1	exact	7	exact	?	unknown	
+GetPetActionsUsable	0x4be0b0	0x8475b8	0x8475a0	global	0	exact	1	exact	(nil) | (number)	agree	
+GetPetExperience	0x4be840	0x847660	0x8475a0	global	0	exact	2	exact	(number,number)	agree	
+GetPetFoodTypes	0x4bea10	0x847670	0x8475a0	global	0	exact	?	unknown	?	unknown	
+GetPetHappiness	0x4be900	0x847668	0x8475a0	global	0	exact	3	exact	(nil,number,number) | (number,number,number)	agree	
+GetPetIcon	0x4beb10	0x847678	0x8475a0	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetPetLoyalty	0x4be700	0x847650	0x8475a0	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetPetTimeRemaining	0x4be600	0x847640	0x8475a0	global	0	exact	1	exact	(nil) | (number)	agree	
+GetPetTrainingPoints	0x4be790	0x847658	0x8475a0	global	0	exact	2	exact	(number,number)	agree	
+GetPetitionInfo	0x4f43d0	0x84cea8	0x84cea0	global	0	exact	6	exact	(nil,nil,nil,number,nil,nil) | (string,string?,string?,number,nil,nil) | (string,string?,string?,number,nil,number) | (string,string?,string?,number,string?,nil) | (string,string?,string?,number,string?,number)	agree	
+GetPetitionNameInfo	0x4f4510	0x84ceb8	0x84cea0	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetPingPosition	0x4eefd0	0x84c580	0x84c538	widget	0	exact	2	exact	(number,number)	agree	
+GetPlayerBuff	0x4e45d0	0x84bb20	0x84bb20	global	2	exact	2	exact	(number,number)	agree	
+GetPlayerBuffApplications	0x4e48b0	0x84bb38	0x84bb20	global	1	exact	1	exact	(number)	agree	
+GetPlayerBuffDispelType	0x4e4800	0x84bb30	0x84bb20	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetPlayerBuffTexture	0x4e4740	0x84bb28	0x84bb20	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetPlayerBuffTimeLeft	0x4e4930	0x84bb40	0x84bb20	global	1	exact	1	exact	(number)	agree	
+GetPlayerMapPosition	0x4a8610	0x8450c0	0x845078	global	1	exact	2	exact	(number,number)	agree	
+GetPlayerTradeMoney	0x4c0700	0x847a40	0x8479f8	global	0	exact	1	exact	(number)	agree	
+GetPoint	0x7a2340	0x87ca30	0x87c9b8	widget	2	lower-bound	0|3|5	set	() | (string?,any,string?,number,number) | (string?,number,number)	agree	delegated-push
+GetPosition	0x76ea40	0x8789a0	0x878948	widget	1	exact	3	exact	(number,number,number)	agree	
+GetProgressText	0x501a60	0x84e990	0x84e968	global	0	exact	1	exact	(string?)	agree	
+GetPushedTextOffset	0x782180	0x879e00	0x879d00	widget	1	exact	2	exact	(number,number)	agree	
+GetPushedTexture	0x781cd0	0x879dd0	0x879d00	widget	0	exact	?	unknown	?	unknown	delegated-push
+GetQuestBackgroundMaterial	0x502230	0x84ea58	0x84e968	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetQuestGreenRange	0x4e17d0	0x84b1d0	0x84b0f0	global	0	exact	1	exact	(number)	agree	
+GetQuestIndexForTimer	0x4e15f0	0x84b1b8	0x84b0f0	global	1	exact	1	exact	(nil) | (number)	agree	
+GetQuestIndexForWatch	0x4e19b0	0x84b1f8	0x84b0f0	global	1	exact	1	exact	(nil) | (number)	agree	
+GetQuestItemInfo	0x501f80	0x84ea38	0x84e968	global	2	exact	5	exact	(string?,string?,number,number,nil) | (string?,string?,number,number,number)	agree	
+GetQuestItemLink	0x502090	0x84ea40	0x84e968	global	2	exact	1	exact	(nil) | (string?)	agree	
+GetQuestLogChoiceInfo	0x4e0cf0	0x84b178	0x84b0f0	global	1	exact	5	exact	(nil,nil,number,number,nil) | (string?,string?,number,number,nil) | (string?,string?,number,number,number)	agree	
+GetQuestLogItemLink	0x4e0ee0	0x84b180	0x84b0f0	global	2	exact	1	exact	(nil) | (string?)	agree	
+GetQuestLogLeaderBoard	0x4e0110	0x84b148	0x84b0f0	global	2	lower-bound	3	exact	(nil,nil,nil) | (string?,string,nil) | (string?,string,number)	agree	delegated-push
+GetQuestLogPushable	0x4e12b0	0x84b1a0	0x84b0f0	global	0	exact	1	exact	(nil) | (number)	agree	
+GetQuestLogQuestText	0x4dff20	0x84b138	0x84b0f0	global	0	exact	2	exact	(nil,nil) | (string?,string?)	agree	
+GetQuestLogRequiredMoney	0x4e1220	0x84b198	0x84b0f0	global	0	exact	1	exact	(number)	agree	
+GetQuestLogRewardInfo	0x4e0b00	0x84b170	0x84b0f0	global	1	exact	5	exact	(nil,nil,number,number,nil) | (string?,string?,number,number,nil) | (string?,string?,number,number,number)	agree	
+GetQuestLogRewardMoney	0x4e1070	0x84b188	0x84b0f0	global	0	exact	1	exact	(number)	agree	
+GetQuestLogRewardSpell	0x4e1130	0x84b190	0x84b0f0	global	0	exact	3	exact	(nil,nil,nil) | (nil,string?,nil) | (nil,string?,number) | (string?,string?,nil) | (string?,string?,number)	agree	
+GetQuestLogSelection	0x4dfb20	0x84b108	0x84b0f0	global	0	exact	1	exact	(number)	agree	
+GetQuestLogTimeLeft	0x4e08a0	0x84b150	0x84b0f0	global	0	exact	1	exact	(nil) | (number)	agree	
+GetQuestLogTitle	0x4df930	0x84b0f8	0x84b0f0	global	1	exact	6	exact	(string?,number,string?,nil,nil,nil) | (string?,number,string?,nil,nil,number) | (string?,number,string?,number,nil,nil) | (string?,number,string?,number,nil,number) | (string?,number,string?,number,number,nil) | (string?,number,string?,number,number,number)	agree	
+GetQuestMoneyToGet	0x501ea0	0x84ea18	0x84e968	global	0	exact	1	exact	(number)	agree	
+GetQuestReward	0x501d80	0x84ea00	0x84e968	global	1	exact	0	exact	()	agree	
+GetQuestText	0x501a40	0x84e980	0x84e968	global	0	exact	1	exact	(string?)	agree	
+GetQuestTimers	0x4e13d0	0x84b1b0	0x84b0f0	global	0	lower-bound	?	unknown	?	unknown	delegated-push
+GetRaidRosterInfo	0x4bb560	0x847248	0x847240	global	1	lower-bound	9	exact	?	unknown	delegated-push
+GetRaidRosterSelection	0x4bb890	0x847258	0x847240	global	0	exact	1	exact	(number)	agree	
+GetRaidTargetIndex	0x4bb4b0	0x8472a0	0x847240	global	1	exact	1	exact	(nil) | (number)	agree	
+GetRandomName	0x471980	0x8381a8	0x8380f8	global	0	exact	1	exact	(string?)	agree	
+GetRealZoneText	0x48a0c0	0x83e0b0	0x83de68	global	0	exact	1	exact	(string?)	agree	
+GetRealmCategories	0x46f1f0	0x837ec8	0x837ea0	global	0	exact	?	unknown	?	unknown	
+GetRealmInfo	0x46ee40	0x837eb8	0x837ea0	global	2	exact	8	exact	?	unknown	
+GetRealmName	0x48df90	0x83e480	0x83de68	global	0	exact	1	exact	(string?)	agree	
+GetRefreshRates	0x48c0d0	0x83e2b0	0x83de68	global	1	exact	?	unknown	?	unknown	
+GetRegions	0x773f60	0x878ef8	0x878ec0	widget	1	lower-bound	?	unknown	?	unknown	delegated-push
+GetReleaseTimeRemaining	0x48b5a0	0x83e230	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetRepairAllCost	0x4fbd60	0x84daa0	0x84da28	global	0	exact	1|2	set	(number) | (number,nil) | (number,number)	agree	
+GetResSicknessDuration	0x51a3a0	0x850680	0x850438	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetRestState	0x48d350	0x83e3a0	0x83de68	global	0	exact	3	exact	(nil,nil,nil) | (number,string?,number)	agree	
+GetRewardMoney	0x501dd0	0x84ea08	0x84e968	global	0	exact	1	exact	(number)	agree	
+GetRewardSpell	0x501df0	0x84ea10	0x84e968	global	0	exact	3	exact	(nil,nil,nil) | (nil,string?,nil) | (nil,string?,number) | (string?,string?,nil) | (string?,string?,number)	agree	
+GetRewardText	0x501a70	0x84e998	0x84e968	global	0	exact	1	exact	(string?)	agree	
+GetRight	0x7a1aa0	0x87c9f0	0x87c9b8	widget	1	exact	1	exact	(nil) | (number)	agree	
+GetSavedAccountName	0x46cdd0	0x8373c8	0x8373b8	global	0	exact	1	exact	(string?)	agree	
+GetSavedInstanceInfo	0x4a1920	0x8437a0	0x843618	global	1	exact	3	exact	(nil,number,nil) | (string?,number,number)	agree	
+GetScale	0x775080	0x878f80	0x878ec0	widget	1	exact	1	exact	(number)	agree	
+GetScreenHeight	0x46dd80	0x837410	0x8373b8	global	0	exact	1	exact	(number)	agree	name-not-unique
+GetScreenHeight	0x48b4d0	0x83e220	0x83de68	global	0	exact	1	exact	(number)	agree	name-not-unique
+GetScreenResolutions	0x48bc20	0x83e298	0x83de68	global	0	exact	?	unknown	?	unknown	
+GetScreenWidth	0x46dd30	0x837408	0x8373b8	global	0	exact	1	exact	(number)	agree	name-not-unique
+GetScreenWidth	0x48b480	0x83e218	0x83de68	global	0	exact	1	exact	(number)	agree	name-not-unique
+GetScript	0x774780	0x878f38	0x878ec0	widget	2	exact	1	exact	(any)	agree	
+GetScriptMemory	0x46da10	0x837538	0x8373b8	global	0	exact	1	exact	(number)	agree	
+GetScrollChild	0x791200	0x87b3c8	0x87b3c0	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetSelectedAuctionItem	0x4cfec0	0x849148	0x8490a8	global	1	exact	1	exact	(number)	agree	
+GetSelectedBattlefield	0x4ab360	0x845808	0x8457e0	global	0	exact	1	exact	(number)	agree	
+GetSelectedCategory	0x46f400	0x837ee0	0x837ea0	global	0	exact	1	exact	(number)	agree	
+GetSelectedClass	0x4716e0	0x838150	0x8380f8	global	0	exact	2	exact	(string?,string?)	agree	
+GetSelectedFaction	0x4d6c00	0x84a100	0x84a0a8	global	0	exact	1	exact	(number)	agree	
+GetSelectedFriend	0x5ad260	0x85d848	0x85d830	global	0	exact	1	exact	(number)	agree	
+GetSelectedIgnore	0x5ad570	0x85d880	0x85d830	global	0	exact	1	exact	(number)	agree	
+GetSelectedRace	0x471680	0x838140	0x8380f8	global	0	exact	1	exact	(number)	agree	
+GetSelectedSex	0x4716b0	0x838148	0x8380f8	global	0	exact	1	exact	(number)	agree	
+GetSelectedSkill	0x4d4090	0x849d58	0x849cf8	global	0	exact	1	exact	(number)	agree	
+GetSelectedStablePet	0x4cb810	0x848df0	0x848da0	global	0	exact	1	exact	(number)	agree	
+GetSelectedStationeryTexture	0x4ae3f0	0x845f00	0x845eb0	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetSendMailCOD	0x4ae1c0	0x845ee0	0x845eb0	global	0	exact	1	exact	(number)	agree	
+GetSendMailItem	0x4ae590	0x845f20	0x845eb0	global	0	exact	4	exact	(nil,nil,number,number) | (string?,string?,number,number)	agree	
+GetSendMailMoney	0x4ae150	0x845ed0	0x845eb0	global	0	exact	1	exact	(number)	agree	
+GetSendMailPrice	0x4ae730	0x845f28	0x845eb0	global	0	exact	1	exact	(number)	agree	
+GetServerName	0x46d280	0x837490	0x8373b8	global	0	exact	3	exact	(string?,nil,nil) | (string?,nil,number) | (string?,number,nil) | (string?,number,number)	agree	
+GetShadowColor	0x792240	0x87b5f8	0x87b5c0	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowColor	0x794810	0x87b998	0x87b960	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowColor	0x796340	0x87bab8	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowColor	0x7975d0	0x87bba0	0x87bb68	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowColor	0x79dbe0	0x87c268	0x87c1d8	widget	1	exact	4	exact	(number,number,number,number)	agree	name-not-unique
+GetShadowColor	0x7a07b0	0x87c830	0x87c7c8	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowOffset	0x7923c0	0x87b608	0x87b5c0	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowOffset	0x794990	0x87b9a8	0x87b960	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowOffset	0x7964e0	0x87bac8	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowOffset	0x797750	0x87bbb0	0x87bb68	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShadowOffset	0x79df60	0x87c278	0x87c1d8	widget	1	exact	2	exact	(number,number)	agree	name-not-unique
+GetShadowOffset	0x7a0930	0x87c840	0x87c7c8	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetShapeshiftFormCooldown	0x4b49a0	0x8466d0	0x846648	global	1	exact	3	exact	(number,number,number)	agree	
+GetShapeshiftFormInfo	0x4b45c0	0x8466c0	0x846648	global	1	exact	4	exact	(nil,nil,nil,nil) | (nil,string?,nil,nil) | (nil,string?,nil,number) | (nil,string?,number,nil) | (nil,string?,number,number) | (string?,string?,nil,nil) | (string?,string?,nil,number) | (string?,string?,number,nil) | (string?,string?,number,number)	agree	
+GetSkillLineInfo	0x4d3610	0x849d00	0x849cf8	global	1	exact	12|13	set	?	unknown	
+GetSpacing	0x792540	0x87b618	0x87b5c0	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetSpacing	0x794b10	0x87b9b8	0x87b960	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetSpacing	0x796680	0x87bad8	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetSpacing	0x7978d0	0x87bbc0	0x87bb68	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetSpacing	0x79e1d0	0x87c288	0x87c1d8	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetSpacing	0x7a0ab0	0x87c850	0x87c7c8	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetSpellAutocast	0x4b4180	0x846670	0x846648	global	0	lower-bound	2	exact	(nil,nil) | (nil,number) | (number,nil) | (number,number)	agree	
+GetSpellCooldown	0x4b40a0	0x846668	0x846648	global	0	lower-bound	3	exact	(number,number,number)	agree	
+GetSpellName	0x4b3fe0	0x846660	0x846648	global	0	lower-bound	2	exact	(nil,nil) | (string?,string?)	agree	
+GetSpellTabInfo	0x4b3ce0	0x846650	0x846648	global	1	lower-bound	4	exact	(nil,nil,number,number) | (string?,nil,number,number) | (string?,string,number,number) | (string?,string?,number,number)	agree	delegated-push
+GetSpellTexture	0x4b3e50	0x846658	0x846648	global	0	lower-bound	1	exact	(nil) | (string?)	agree	
+GetStablePetFoodTypes	0x4cba70	0x848e00	0x848da0	global	1	exact	?	unknown	?	unknown	
+GetStablePetInfo	0x4cb230	0x848dd0	0x848da0	global	1	exact	5	exact	(nil,nil,number,nil,nil) | (string?,string?,number,string?,nil) | (string?,string?,number,string?,string?)	agree	
+GetStationeryInfo	0x4ae230	0x845ef0	0x845eb0	global	1	exact	3	exact	(nil,nil,nil) | (string?,string?,nil) | (string?,string?,number)	agree	
+GetStatusBarColor	0x78fab0	0x87b050	0x87b010	widget	1	exact	4	exact	(number,number,number,number)	agree	
+GetStatusBarTexture	0x78f780	0x87b040	0x87b010	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetStringWidth	0x79e510	0x87c2a0	0x87c1d8	widget	1	exact	1	exact	(number)	agree	
+GetSubZoneText	0x48a0e0	0x83e0b8	0x83de68	global	0	exact	1	exact	(string?)	agree	
+GetSummonConfirmAreaName	0x48b720	0x83e258	0x83de68	global	0	exact	1	exact	(string?)	agree	
+GetSummonConfirmSummoner	0x48b6a0	0x83e250	0x83de68	global	0	exact	1	exact	(string?)	agree	
+GetSummonConfirmTimeLeft	0x48b660	0x83e248	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetTabardCreationCost	0x4f5910	0x84d0bc	0x84d0b4	global	0	exact	1	exact	(number)	agree	
+GetTabardInfo	0x4f5300	0x84d02c	0x84d00c	global	0	exact	0	exact	()	agree	
+GetTalentInfo	0x4f3200	0x84cd08	0x84ccf0	global	2	exact	8	exact	(nil,nil,number,number,number,number,nil,nil) | (string?,nil,number,number,number,number,nil,nil) | (string?,nil,number,number,number,number,nil,number) | (string?,nil,number,number,number,number,number,nil) | (string?,nil,number,number,number,number,number,number) | (string?,string?,number,number,number,number,nil,nil) | (string?,string?,number,number,number,number,nil,number) | (string?,string?,number,number,number,number,number,nil) | (string?,string?,number,number,number,number,number,number)	agree	
+GetTalentPrereqs	0x4f34d0	0x84cd10	0x84ccf0	global	2	exact	?	unknown	?	unknown	
+GetTalentTabInfo	0x4f3040	0x84ccf8	0x84ccf0	global	1	exact	4	exact	(nil,nil,number,nil) | (string?,nil,number,string?) | (string?,string?,number,string?)	agree	
+GetTargetTradeMoney	0x4c0750	0x847a48	0x8479f8	global	0	exact	1	exact	(number)	agree	
+GetTerrainMip	0x488fb0	0x83df30	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetTexCoord	0x79bdf0	0x87c1a8	0x87c128	widget	1	exact	8	exact	?	unknown	
+GetTexCoordModifiesRect	0x79c120	0x87c1c0	0x87c128	widget	1	exact	1	exact	(nil) | (number)	agree	
+GetTexLodBias	0x489110	0x83df50	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetText	0x780e10	0x879d80	0x879d00	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetText	0x7985c0	0x87bc48	0x87bb68	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetText	0x79d690	0x87c248	0x87c1d8	widget	1	exact	1	exact	(string?)	agree	name-not-unique
+GetTextColor	0x781100	0x879d90	0x879d00	widget	1	exact	4	exact	(number,number,number,number)	agree	name-not-unique
+GetTextColor	0x7920c0	0x87b5e8	0x87b5c0	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetTextColor	0x794690	0x87b988	0x87b960	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetTextColor	0x7961a0	0x87baa8	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+GetTextColor	0x797450	0x87bb90	0x87bb68	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetTextColor	0x79d840	0x87c258	0x87c1d8	widget	1	exact	4	exact	(number,number,number,number)	agree	name-not-unique
+GetTextColor	0x7a0630	0x87c820	0x87c7c8	widget	1	exact	?	unknown	()	unverified	name-not-unique;delegated-push
+GetTextFontObject	0x7804c0	0x879d30	0x879d00	widget	1	lower-bound	?	unknown	()	unverified	delegated-push
+GetTextHeight	0x782390	0x879e10	0x879d00	widget	1	exact	1	exact	(number)	agree	
+GetTextInsets	0x798c30	0x87bc78	0x87bb68	widget	1	exact	4	exact	(number,number,number,number)	agree	
+GetTextWidth	0x782290	0x879e08	0x879d00	widget	1	exact	1	exact	(number)	agree	
+GetTexture	0x79ba70	0x87c198	0x87c128	widget	1	exact	1	exact	(nil) | (string?)	agree	
+GetThumbTexture	0x7901c0	0x87b260	0x87b260	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetTime	0x515ea0	0x8503f4	0x8503f4	global	0	exact	1	exact	(number)	agree	
+GetTimeToWellRested	0x48d4b0	0x83e3b0	0x83de68	global	0	exact	1	exact	(nil)	agree	
+GetTimeVisible	0x793bf0	0x87b6e0	0x87b5c0	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetTimeVisible	0x795320	0x87ba08	0x87b960	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetTitleRegion	0x773820	0x878ed0	0x878ec0	widget	1	lower-bound	1	exact	(any) | (nil)	agree	delegated-push
+GetTitleText	0x501a20	0x84e970	0x84e968	global	0	exact	1	exact	(string?)	agree	
+GetTop	0x7a1bc0	0x87c9f8	0x87c9b8	widget	1	exact	1	exact	(nil) | (number)	agree	
+GetTrackingTexture	0x4e4a20	0x84bb50	0x84bb20	global	0	exact	1	exact	(nil) | (string?)	agree	
+GetTradePlayerItemInfo	0x4c0450	0x847a20	0x8479f8	global	1	exact	5	exact	(nil,nil,number,number,nil) | (string?,string?,number,number,nil) | (string?,string?,number,number,string?)	agree	
+GetTradePlayerItemLink	0x4c0650	0x847a28	0x8479f8	global	1	exact	0|1	set	() | (string?)	agree	
+GetTradeSkillCooldown	0x4fda20	0x84ddf8	0x84ddd0	global	1	exact	1	exact	(nil) | (number)	agree	
+GetTradeSkillIcon	0x4fdae0	0x84de00	0x84ddd0	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetTradeSkillInfo	0x4fd820	0x84dde0	0x84ddd0	global	1	exact	4	exact	(nil,nil,number,nil) | (string?,string,number,nil) | (string?,string,number,number) | (string?,string?,number,nil)	agree	
+GetTradeSkillInvSlotFilter	0x4fffd0	0x84de70	0x84ddd0	global	1	exact	1	exact	(nil) | (number)	agree	
+GetTradeSkillInvSlots	0x4ffc20	0x84de50	0x84ddd0	global	0	lower-bound	?	unknown	?	unknown	delegated-push
+GetTradeSkillItemLink	0x4ff410	0x84de20	0x84ddd0	global	1	exact	0|1	set	() | (string?)	agree	
+GetTradeSkillItemStats	0x4fdec0	0x84de18	0x84ddd0	global	1	lower-bound	?	unknown	?	unknown	delegated-push
+GetTradeSkillLine	0x4fdd40	0x84de10	0x84ddd0	global	0	exact	3	exact	(string,number,number) | (string?,number,number)	agree	
+GetTradeSkillNumMade	0x4fdc50	0x84de08	0x84ddd0	global	1	exact	2	exact	(number,number)	agree	
+GetTradeSkillNumReagents	0x4ff510	0x84de28	0x84ddd0	global	1	exact	1	exact	(number)	agree	
+GetTradeSkillReagentInfo	0x4ff5c0	0x84de30	0x84ddd0	global	2	exact	4	exact	(nil,nil,nil,nil) | (nil,nil,number,number) | (string?,string?,number,number)	agree	
+GetTradeSkillReagentItemLink	0x4ff800	0x84de38	0x84ddd0	global	2	exact	1	exact	(nil) | (string?)	agree	
+GetTradeSkillSelectionIndex	0x4fd9f0	0x84ddf0	0x84ddd0	global	0	exact	1	exact	(number)	agree	
+GetTradeSkillSubClassFilter	0x4ffd90	0x84de60	0x84ddd0	global	1	exact	1	exact	(nil) | (number)	agree	
+GetTradeSkillSubClasses	0x4ffb60	0x84de48	0x84ddd0	global	0	exact	?	unknown	?	unknown	
+GetTradeSkillTools	0x4ff980	0x84de40	0x84ddd0	global	1	exact	?	unknown	?	unknown	
+GetTradeTargetItemInfo	0x4c00f0	0x847a10	0x8479f8	global	1	exact	?	unknown	(nil,nil,number,number,nil,nil) | (string?,string?,number,number,nil,nil) | (string?,string?,number,number,nil,string?) | (string?,string?,number,number,number,nil) | (string?,string?,number,number,number,string?)	unverified	
+GetTradeTargetItemLink	0x4c0360	0x847a18	0x8479f8	global	1	exact	0|1	set	() | (string?)	agree	
+GetTradeskillRepeatCount	0x500230	0x84de90	0x84ddd0	global	0	exact	1	exact	(number)	agree	
+GetTrainerGreetingText	0x4d8f40	0x84a420	0x84a3e0	global	0	exact	1	exact	(string?)	agree	
+GetTrainerSelectionIndex	0x4d8f10	0x84a418	0x84a3e0	global	0	exact	1	exact	(number)	agree	
+GetTrainerServiceAbilityReq	0x4d96e0	0x84a458	0x84a3e0	global	2	exact	2	exact	(nil,nil) | (nil,number) | (string?,nil) | (string?,number)	agree	
+GetTrainerServiceCost	0x4d92f0	0x84a438	0x84a3e0	global	1	exact	3	exact	(number,number,number)	agree	delegated-push
+GetTrainerServiceDescription	0x4d9b40	0x84a468	0x84a3e0	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetTrainerServiceIcon	0x4d8f50	0x84a428	0x84a3e0	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetTrainerServiceInfo	0x4d8dc0	0x84a3f8	0x84a3e0	global	1	exact	4	exact	(string?,string?,string?,nil) | (string?,string?,string?,number)	agree	
+GetTrainerServiceLevelReq	0x4d93a0	0x84a440	0x84a3e0	global	1	exact	1	exact	(number)	agree	
+GetTrainerServiceNumAbilityReq	0x4d9600	0x84a450	0x84a3e0	global	1	exact	1	exact	(number)	agree	
+GetTrainerServiceSkillLine	0x4d9160	0x84a430	0x84a3e0	global	1	exact	1	exact	(nil) | (string?)	agree	
+GetTrainerServiceSkillReq	0x4d9410	0x84a448	0x84a3e0	global	1	exact	3	exact	(nil,number,nil) | (nil,number,number) | (string?,number,nil) | (string?,number,number)	agree	
+GetTrainerServiceStepIncrease	0x4da030	0x84a488	0x84a3e0	global	1	lower-bound	1	exact	(nil) | (string?)	agree	delegated-push
+GetTrainerServiceStepReq	0x4d9930	0x84a460	0x84a3e0	global	1	exact	2	exact	(nil,nil) | (nil,number) | (string?,nil) | (string?,number)	agree	
+GetTrainerServiceTypeFilter	0x4da510	0x84a4a8	0x84a3e0	global	1	exact	1	exact	(nil) | (number)	agree	
+GetTrainerSkillLineFilter	0x4da590	0x84a4b0	0x84a3e0	global	1	exact	1	exact	(nil) | (number)	agree	
+GetTrainerSkillLines	0x4da660	0x84a4b8	0x84a3e0	global	0	exact	?	unknown	?	unknown	
+GetUpperBackgroundFileName	0x502dc0	0x84ee58	0x84ee40	widget	1	exact	1	exact	(string?)	agree	
+GetUpperEmblemFileName	0x502f80	0x84ee68	0x84ee40	widget	1	exact	1	exact	(string?)	agree	
+GetUpperEmblemTexture	0x503160	0x84ee78	0x84ee40	widget	2	exact	0	exact	()	agree	
+GetValue	0x78f5d0	0x87b030	0x87b010	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetValue	0x7908c0	0x87b290	0x87b260	widget	1	exact	1	exact	(number)	agree	name-not-unique
+GetValueStep	0x790a70	0x87b2a0	0x87b260	widget	1	exact	1	exact	(number)	agree	
+GetVertexColor	0x79aa50	0x87c148	0x87c128	widget	1	exact	4	exact	(number,number,number,number)	agree	
+GetVerticalScroll	0x791610	0x87b3e8	0x87b3c0	widget	1	exact	1	exact	(number)	agree	
+GetVerticalScrollRange	0x7917d0	0x87b3f8	0x87b3c0	widget	1	exact	1	exact	(number)	agree	
+GetVideoCaps	0x48db40	0x83e418	0x83de68	global	0	exact	7	exact	?	unknown	
+GetWatchedFactionInfo	0x4d6820	0x84a0b8	0x84a0a8	global	0	exact	5	exact	(nil,number,number,number,number) | (string?,number,number,number,number)	agree	
+GetWaterDetail	0x488ec0	0x83df10	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetWeaponEnchantInfo	0x4c9790	0x848598	0x8484d0	global	0	exact	6	exact	(nil,nil,nil,nil,nil,nil) | (nil,nil,nil,number,nil,number) | (nil,nil,nil,number,number,number) | (number,nil,number,nil,nil,nil) | (number,nil,number,number,nil,number) | (number,nil,number,number,number,number) | (number,number,number,nil,nil,nil) | (number,number,number,number,nil,number) | (number,number,number,number,number,number)	agree	
+GetWhoInfo	0x5ad6e0	0x85d8b0	0x85d830	global	1	lower-bound	6	exact	(nil,nil,number,nil,nil,nil) | (string?,string?,number,string?,string?,string?)	agree	delegated-push
+GetWidth	0x7a1e00	0x87ca08	0x87c9b8	widget	1	exact	1	exact	(number)	agree	
+GetWorldDetail	0x488d70	0x83df00	0x83de68	global	0	exact	1	exact	(number)	agree	
+GetWorldLocMapPosition	0x4a88f0	0x8450e0	0x845078	global	3	exact	2	exact	(number,number)	agree	
+GetWorldStateUIInfo	0x4c5a70	0x84841c	0x848414	global	1	exact	1|10	set	(number) | (number,string?,string?,string?,string?,string?,string?,number,number,number)	agree	
+GetXPExhaustion	0x48d3f0	0x83e3a8	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+GetZonePVPInfo	0x48d540	0x83e3c8	0x83de68	global	0	exact	3	exact	(nil,nil,nil) | (nil,nil,number) | (string,string?,nil) | (string,string?,number)	agree	
+GetZoneText	0x48a0a0	0x83e0a8	0x83de68	global	0	exact	1	exact	(string?)	agree	
+GetZoom	0x4eec20	0x84c568	0x84c538	widget	0	exact	1	exact	(number)	agree	
+GetZoomLevels	0x4eebe0	0x84c560	0x84c538	widget	0	exact	1	exact	(number)	agree	
+GiveMasterLoot	0x4c2fd0	0x847d40	0x847cf0	global	2	exact	0	exact	()	agree	
+GuildControlAddRank	0x4d2210	0x8497a8	0x8496d8	global	1	exact	0	exact	()	agree	
+GuildControlDelRank	0x4d22e0	0x8497b0	0x8496d8	global	0	exact	0	exact	()	agree	
+GuildControlGetNumRanks	0x4d1e60	0x849778	0x8496d8	global	0	exact	1	exact	(number)	agree	
+GuildControlGetRankFlags	0x4d1fe0	0x849790	0x8496d8	global	0	exact	13	exact	?	unknown	
+GuildControlGetRankName	0x4d1e90	0x849780	0x8496d8	global	1	exact	1	exact	(nil) | (string?)	agree	
+GuildControlSaveRank	0x4d20d0	0x8497a0	0x8496d8	global	1	exact	0	exact	()	agree	
+GuildControlSetRank	0x4d1fa0	0x849788	0x8496d8	global	1	exact	0	exact	()	agree	
+GuildControlSetRankFlag	0x4d2070	0x849798	0x8496d8	global	2	exact	0	exact	()	agree	
+GuildDemoteByName	0x48b0f0	0x83e1e8	0x83de68	global	1	exact	0	exact	()	agree	
+GuildDisband	0x48b3a0	0x83e208	0x83de68	global	0	exact	0	exact	()	agree	
+GuildInfo	0x48b410	0x83e210	0x83de68	global	0	exact	0	exact	()	agree	
+GuildInviteByName	0x48aef0	0x83e1d0	0x83de68	global	1	exact	0	exact	()	agree	
+GuildLeave	0x48b330	0x83e200	0x83de68	global	0	exact	0	exact	()	agree	
+GuildPromoteByName	0x48b050	0x83e1e0	0x83de68	global	1	exact	0	exact	()	agree	
+GuildRoster	0x4d2360	0x8497c0	0x8496d8	global	0	exact	0	exact	()	agree	
+GuildRosterSetOfficerNote	0x4d1700	0x849700	0x8496d8	global	2	exact	0	exact	()	agree	
+GuildRosterSetPublicNote	0x4d15e0	0x8496f8	0x8496d8	global	2	exact	0	exact	()	agree	
+GuildSetLeaderByName	0x48b190	0x83e1f0	0x83de68	global	1	exact	0	exact	()	agree	
+GuildSetMOTD	0x48b270	0x83e1f8	0x83de68	global	1	exact	0	exact	()	agree	
+GuildUninviteByName	0x48afb0	0x83e1d8	0x83de68	global	1	exact	0	exact	()	agree	
+HasAction	0x4e70d0	0x84bd38	0x84bd10	global	1	exact	1	exact	(nil) | (number)	agree	
+HasCharCustomization	0x471820	0x838180	0x8380f8	global	1	exact	1	exact	(nil) | (number)	agree	
+HasFullControl	0x51a120	0x850630	0x850438	global	0	exact	1	exact	(nil) | (number)	agree	
+HasInspectHonorData	0x4c95e0	0x848578	0x8484d0	global	0	exact	1	exact	(nil) | (number)	agree	
+HasKey	0x48ae90	0x83e1c8	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+HasNewMail	0x4afea0	0x845f98	0x845eb0	global	0	exact	1	exact	(nil) | (number)	agree	
+HasPetSpells	0x4b4410	0x8466a8	0x846648	global	0	exact	2	exact	(nil,nil) | (number,string) | (number,string?)	agree	
+HasPetUI	0x4be670	0x847648	0x8475a0	global	0	exact	2	exact	(nil,nil) | (number,nil) | (number,number)	agree	
+HasScript	0x774680	0x878f30	0x878ec0	widget	2	exact	1	exact	(nil) | (number)	agree	
+HasSoulstone	0x48ac80	0x83e1b8	0x83de68	global	0	exact	1	exact	(nil) | (string) | (string?)	agree	
+HasWandEquipped	0x4c99a0	0x8485a0	0x8484d0	global	0	exact	1	exact	(nil) | (number)	agree	
+Hide	0x775810	0x878fc8	0x878ec0	widget	1	exact	0	exact	()	agree	name-not-unique
+Hide	0x79b830	0x87c180	0x87c128	widget	1	exact	0	exact	()	agree	name-not-unique
+Hide	0x79ce70	0x87c210	0x87c1d8	widget	1	exact	0	exact	()	agree	name-not-unique
+HideCursor	0x46db70	0x837558	0x8373b8	global	0	exact	0	exact	()	agree	
+HideFriendNameplates	0x489480	0x83dfd8	0x83de68	global	0	exact	0	exact	()	agree	
+HideNameplates	0x489460	0x83dfc8	0x83de68	global	0	exact	0	exact	()	agree	
+HideRepairCursor	0x4fbd00	0x84da90	0x84da28	global	0	exact	0	exact	()	agree	
+HighlightText	0x798870	0x87bc60	0x87bb68	widget	3	exact	0	exact	()	agree	
+InCinematic	0x48c930	0x83e2e8	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+InRepairMode	0x4fbd30	0x84da98	0x84da28	global	0	exact	1	exact	(nil) | (number)	agree	
+InboxItemCanDelete	0x4afe00	0x845f90	0x845eb0	global	1	exact	1	exact	(nil) | (number)	agree	
+InitializeTabardColors	0x502b10	0x84ee40	0x84ee40	widget	1	exact	0	exact	()	agree	
+InitiateTrade	0x48a120	0x83e0c8	0x83de68	global	1	exact	0	exact	()	agree	
+Insert	0x798400	0x87bc38	0x87bb68	widget	2	exact	0	exact	()	agree	
+InviteByName	0x48a420	0x83e0e8	0x83de68	global	1	exact	0	exact	()	agree	
+InviteToParty	0x48a3b0	0x83e0e0	0x83de68	global	1	exact	0	exact	()	agree	
+IsActionInRange	0x4e7550	0x84bd88	0x84bd10	global	1	exact	1	exact	(nil) | (number)	agree	
+IsAddOnLoadOnDemand	0x48e840	0x83e4e0	0x83de68	global	1	exact	1	exact	(nil) | (number)	agree	
+IsAddOnLoaded	0x48e8e0	0x83e4e8	0x83de68	global	1	exact	1	exact	(nil) | (number)	agree	
+IsAddonVersionCheckEnabled	0x46d9b0	0x837528	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+IsAltKeyDown	0x488600	0x83dea0	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+IsAttackAction	0x4e7280	0x84bd58	0x84bd10	global	1	exact	1	exact	(nil) | (number)	agree	
+IsAuctionSortReversed	0x4d0030	0x849150	0x8490a8	global	2	exact	0|1	set	() | (nil) | (number)	agree	
+IsAutoFocus	0x797d40	0x87bbf0	0x87bb68	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsAutoRepeatAction	0x4e7360	0x84bd68	0x84bd10	global	1	exact	1	exact	(nil) | (number)	agree	
+IsClampedToScreen	0x776cb0	0x879070	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsConnectedToServer	0x46d380	0x8374a0	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+IsConsumableAction	0x4e7470	0x84bd78	0x84bd10	global	1	exact	1	exact	(nil) | (number)	agree	
+IsControlKeyDown	0x4885c0	0x83de98	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+IsCurrentAction	0x4e72f0	0x84bd60	0x84bd10	global	1	exact	1	exact	(nil) | (number)	agree	
+IsCurrentCast	0x4b4370	0x846690	0x846648	global	0	lower-bound	1	exact	(nil) | (number)	agree	
+IsCurrentQuestFailed	0x4e0960	0x84b158	0x84b0f0	global	0	exact	1	exact	(nil) | (number)	agree	
+IsDesaturated	0x79c2c0	0x87c1d0	0x87c128	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsEnabled	0x7800b0	0x879d10	0x879d00	widget	1	exact	1	exact	(number)	agree	
+IsEquippedAction	0x4e74e0	0x84bd80	0x84bd10	global	1	exact	1	exact	(nil) | (number)	agree	
+IsFactionInactive	0x4d6af0	0x84a0e8	0x84a0a8	global	1	exact	1	exact	(nil) | (number)	agree	
+IsFishingLoot	0x4c2ee0	0x847d30	0x847cf0	global	0	exact	1	exact	(nil) | (number)	agree	
+IsFrameType	0x773700	0x878ec8	0x878ec0	widget	2	exact	1	exact	(nil) | (number)	agree	
+IsGuildLeader	0x516e40	0x850648	0x850438	global	0	exact	1	exact	(nil) | (number)	agree	
+IsInGuild	0x516de0	0x850640	0x850438	global	0	exact	1	exact	(nil) | (number)	agree	
+IsInInstance	0x48a750	0x83e520	0x83de68	global	0	exact	2	exact	() | (nil,string?) | (number,string?)	unverified	
+IsInMeetingStoneQueue	0x4ca570	0x848ce8	0x848ce8	global	0	exact	1	exact	(nil) | (number)	agree	
+IsInventoryItemLocked	0x4c8e60	0x848520	0x8484d0	global	0	lower-bound	1	exact	(nil) | (number)	agree	
+IsKeyboardEnabled	0x776f90	0x879088	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsLinuxClient	0x48c990	0x83e300	0x83de68	global	0	exact	1	exact	(nil)	agree	
+IsMacClient	0x48c980	0x83e2f8	0x83de68	global	0	exact	1	exact	(nil)	agree	
+IsMouseEnabled	0x777130	0x879098	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsMouseWheelEnabled	0x7772b0	0x8790a8	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsMouselooking	0x514270	0x850180	0x8500b8	global	0	exact	1	exact	(nil) | (number)	agree	
+IsMovable	0x7764d0	0x879028	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsMultiLine	0x797eb0	0x87bc00	0x87bb68	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsNumeric	0x798020	0x87bc10	0x87bb68	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsObjectType	0x79fe60	0x87c7d0	0x87c7c8	widget	2	exact	1	exact	(nil) | (number)	agree	name-not-unique
+IsObjectType	0x7a1290	0x87c9c0	0x87c9b8	widget	2	exact	1	exact	(nil) | (number)	agree	name-not-unique
+IsOwned	0x530fe0	0x8541b0	0x854198	widget	2	exact	1	exact	(nil) | (number)	agree	
+IsPartyLeader	0x4e9130	0x84c188	0x84c170	global	0	exact	1	exact	(nil) | (number)	agree	
+IsPassword	0x798190	0x87bc20	0x87bb68	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsPetAttackActive	0x4be0e0	0x8475c0	0x8475a0	global	1	exact	1	exact	(boolean)	agree	
+IsQuestCompletable	0x501d40	0x84e9f0	0x84e968	global	0	exact	1	exact	(nil) | (number)	agree	
+IsQuestWatched	0x4e1890	0x84b1e0	0x84b0f0	global	1	exact	1	exact	(nil) | (number)	agree	
+IsRaidLeader	0x4bb8c0	0x847260	0x847240	global	0	exact	1	exact	(nil) | (number)	agree	
+IsRaidOfficer	0x4bb910	0x847268	0x847240	global	0	exact	1	exact	(nil) | (number)	agree	
+IsResizable	0x776640	0x879038	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsResting	0x516ea0	0x850650	0x850438	global	0	exact	1	exact	(nil) | (number)	agree	
+IsShiftKeyDown	0x488590	0x83de90	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+IsShown	0x775990	0x878fd8	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	name-not-unique
+IsShown	0x79b9b0	0x87c190	0x87c128	widget	1	exact	1	exact	(nil) | (number)	agree	name-not-unique
+IsShown	0x79cff0	0x87c220	0x87c1d8	widget	1	exact	1	exact	(nil) | (number)	agree	name-not-unique
+IsSpellPassive	0x4b44e0	0x8466b0	0x846648	global	0	lower-bound	1	exact	(nil) | (number)	agree	
+IsTalentTrainer	0x4d8ed0	0x84a410	0x84a3e0	global	0	exact	1	exact	(nil) | (number)	agree	
+IsToplevel	0x7754f0	0x878fa8	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsTradeskillTrainer	0x4d8ea0	0x84a408	0x84a3e0	global	0	exact	1	exact	(nil) | (number)	agree	
+IsTrainerServiceLearnSpell	0x4d9e70	0x84a478	0x84a3e0	global	1	exact	2	exact	(nil,nil) | (number,nil) | (number,number)	agree	
+IsTrainerServiceSkillStep	0x4d9dd0	0x84a470	0x84a3e0	global	1	exact	1	exact	(nil) | (number)	agree	
+IsTrainerServiceTradeSkill	0x4d9f70	0x84a480	0x84a3e0	global	1	exact	1	exact	(nil) | (number)	agree	
+IsUnitOnQuest	0x4dfe10	0x84b130	0x84b0f0	global	2	exact	1	exact	(nil) | (number)	agree	
+IsUsableAction	0x4e73d0	0x84bd70	0x84bd10	global	1	exact	2	exact	(nil,nil) | (nil,number) | (number,nil) | (number,number)	agree	
+IsUserPlaced	0x776b40	0x879060	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	
+IsVendorActive	0x4c43d0	0x8481d0	0x8481b8	global	0	exact	0	exact	(number)	unverified	stack-leak
+IsVisible	0x7758d0	0x878fd0	0x878ec0	widget	1	exact	1	exact	(nil) | (number)	agree	name-not-unique
+IsVisible	0x79b8f0	0x87c188	0x87c128	widget	1	exact	1	exact	(nil) | (number)	agree	name-not-unique
+IsVisible	0x79cf30	0x87c218	0x87c1d8	widget	1	exact	1	exact	(nil) | (number)	agree	name-not-unique
+IsWindowsClient	0x48c960	0x83e2f0	0x83de68	global	0	exact	1	exact	(number)	agree	
+ItemTextGetCreator	0x4e3940	0x84ba08	0x84ba00	global	0	exact	1	exact	(nil) | (string?)	agree	
+ItemTextGetItem	0x4e38f0	0x84ba00	0x84ba00	global	0	exact	1	exact	(string?)	agree	
+ItemTextGetMaterial	0x4e39f0	0x84ba10	0x84ba00	global	0	exact	1	exact	(nil) | (string?)	agree	
+ItemTextGetPage	0x4e3ad0	0x84ba18	0x84ba00	global	0	exact	1	exact	(number)	agree	
+ItemTextGetText	0x4e3b00	0x84ba20	0x84ba00	global	0	exact	1	exact	(string?)	agree	
+ItemTextHasNextPage	0x4e3b10	0x84ba28	0x84ba00	global	0	exact	1	exact	(nil) | (number)	agree	
+ItemTextNextPage	0x4e3b60	0x84ba38	0x84ba00	global	0	exact	0	exact	()	agree	
+ItemTextPrevPage	0x4e3b50	0x84ba30	0x84ba00	global	0	exact	0	exact	()	agree	
+JoinBattlefield	0x4ab290	0x8457f8	0x8457e0	global	2	exact	0	exact	()	agree	
+JoinChannelByName	0x49ff00	0x843658	0x843618	global	3	exact	0|2	set	() | (number,nil) | (number,string?)	agree	
+Jump	0x513bd0	0x8500b8	0x8500b8	global	0	exact	0	exact	()	agree	
+KeyRingButtonIDToInvSlotID	0x4c8150	0x848508	0x8484d0	global	1	exact	1	exact	(number)	agree	
+LFGQuery	0x4e9760	0x84c1c8	0x84c170	global	3	exact	0	exact	()	agree	
+LaunchAddOnURL	0x46d5e0	0x8374e0	0x8373b8	global	1	exact	0	exact	()	agree	
+LaunchURL	0x46cf60	0x837418	0x8373b8	global	1	exact	0	exact	()	agree	
+LearnTalent	0x4f36a0	0x84cd18	0x84ccf0	global	2	exact	0	exact	()	agree	
+LeaveBattlefield	0x4abe60	0x845880	0x8457e0	global	0	exact	0	exact	()	agree	
+LeaveChannelByName	0x4a0000	0x843660	0x843618	global	1	exact	0	exact	()	agree	
+LeaveParty	0x4e9180	0x84c190	0x84c170	global	0	exact	0	exact	()	agree	
+ListChannelByName	0x4a00d0	0x843668	0x843618	global	0	lower-bound	0	exact	()	agree	
+ListChannels	0x4a01c0	0x843670	0x843618	global	0	exact	0	exact	()	agree	
+LoadAddOn	0x48e980	0x83e4f0	0x83de68	global	1	exact	2	exact	(nil,string) | (nil,string?) | (number,nil)	agree	
+LoadBindings	0x4b8220	0x846cc0	0x846c88	global	1	exact	0	exact	()	agree	
+LockHighlight	0x782840	0x879e28	0x879d00	widget	1	exact	0	exact	()	agree	
+LoggingChat	0x49fe40	0x843648	0x843618	global	0	exact	?	unknown	?	unknown	delegated-push
+LoggingCombat	0x49fef0	0x843650	0x843618	global	0	exact	?	unknown	?	unknown	delegated-push
+Logout	0x489390	0x83dfb0	0x83de68	global	0	exact	0	exact	()	agree	
+LootSlot	0x4c2e70	0x847d20	0x847cf0	global	1	exact	0	exact	()	agree	
+LootSlotIsCoin	0x4c2e00	0x847d18	0x847cf0	global	1	exact	1	exact	(nil) | (number)	agree	
+LootSlotIsItem	0x4c2d90	0x847d10	0x847cf0	global	1	exact	1	exact	(nil) | (number)	agree	
+Lower	0x775b20	0x878fe8	0x878ec0	widget	1	exact	0	exact	()	agree	
+MakeMinigameMove	0x4c4d80	0x848394	0x84838c	global	2	exact	0	exact	()	agree	
+MouselookStart	0x514210	0x850170	0x8500b8	global	0	exact	0	exact	()	agree	
+MouselookStop	0x514240	0x850178	0x8500b8	global	0	exact	0	exact	()	agree	
+MoveBackwardStart	0x513e80	0x8500e0	0x8500b8	global	0	exact	0	exact	()	agree	
+MoveBackwardStop	0x513eb0	0x8500e8	0x8500b8	global	0	exact	0	exact	()	agree	
+MoveForwardStart	0x513e20	0x8500d0	0x8500b8	global	0	exact	0	exact	()	agree	
+MoveForwardStop	0x513e50	0x8500d8	0x8500b8	global	0	exact	0	exact	()	agree	
+MoveViewDownStart	0x50b580	0x84f800	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewDownStop	0x50b590	0x84f808	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewInStart	0x50b4a0	0x84f7b0	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewInStop	0x50b4d0	0x84f7b8	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewLeftStart	0x50b540	0x84f7d0	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewLeftStop	0x50b550	0x84f7d8	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewOutStart	0x50b500	0x84f7c0	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewOutStop	0x50b510	0x84f7c8	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewRightStart	0x50b520	0x84f7e0	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewRightStop	0x50b530	0x84f7e8	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewUpStart	0x50b560	0x84f7f0	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+MoveViewUpStop	0x50b570	0x84f7f8	0x84f7a0	global	0	exact	?	unknown	?	unknown	
+NewGMTicket	0x48c9d0	0x83e310	0x83de68	global	2	exact	0	exact	()	agree	
+NextView	0x50b680	0x84f830	0x84f7a0	global	0	exact	0	exact	()	agree	
+NoPlayTime	0x48ebe0	0x83e500	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+NotWhileDeadError	0x48d340	0x83e398	0x83de68	global	0	exact	0	exact	()	agree	
+NotifyInspect	0x48a310	0x83e0d8	0x83de68	global	1	exact	0	exact	()	agree	
+NumLines	0x535ad0	0x8542d0	0x854198	widget	1	exact	1	exact	(number)	agree	
+NumTaxiNodes	0x4dcb00	0x84adb0	0x84ada8	global	0	exact	1	exact	(number)	agree	
+OfferPetition	0x4f4790	0x84ced0	0x84cea0	global	0	exact	0	exact	()	agree	
+OffhandHasWeapon	0x4c9570	0x848570	0x8484d0	global	0	exact	1	exact	(nil) | (number)	agree	
+OpenTrainer	0x4d8cf0	0x84a3e0	0x84a3e0	global	0	exact	0	exact	()	agree	
+OpeningCinematic	0x48c8c0	0x83e2e0	0x83de68	global	0	exact	0	exact	()	agree	
+PINEntered	0x46d1c0	0x837590	0x8373b8	global	8	lower-bound	0	exact	()	agree	
+PageDown	0x792e00	0x87b660	0x87b5c0	widget	1	exact	0	exact	()	agree	
+PageUp	0x792d30	0x87b658	0x87b5c0	widget	1	exact	0	exact	()	agree	
+PartialPlayTime	0x48eb70	0x83e4f8	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+PatchDownloadApply	0x46d410	0x8374c8	0x8373b8	global	0	exact	0	exact	()	agree	
+PatchDownloadCancel	0x46d400	0x8374c0	0x8373b8	global	0	exact	0	exact	()	agree	
+PatchDownloadProgress	0x46d3e0	0x8374b8	0x8373b8	global	0	exact	1	exact	(number)	agree	
+PetAbandon	0x4be4c0	0x847618	0x8475a0	global	0	exact	0	exact	()	agree	
+PetAggressiveMode	0x4be470	0x8475f0	0x8475a0	global	0	exact	0	exact	()	agree	
+PetAttack	0x4be4a0	0x847608	0x8475a0	global	0	exact	0	exact	()	agree	
+PetCanBeAbandoned	0x4be500	0x847630	0x8475a0	global	0	exact	1	exact	(nil) | (number)	agree	
+PetCanBeRenamed	0x4be580	0x847638	0x8475a0	global	0	exact	1	exact	(nil) | (number)	agree	
+PetDefensiveMode	0x4be460	0x8475e8	0x8475a0	global	0	exact	0	exact	()	agree	
+PetDismiss	0x4be4d0	0x847620	0x8475a0	global	0	exact	0	exact	()	agree	
+PetFollow	0x4be490	0x847600	0x8475a0	global	0	exact	0	exact	()	agree	
+PetHasActionBar	0x4bdc20	0x8475a0	0x8475a0	global	0	exact	1	exact	(nil) | (number)	agree	
+PetPassiveMode	0x4be450	0x8475e0	0x8475a0	global	0	exact	0	exact	()	agree	
+PetRename	0x4be4e0	0x847628	0x8475a0	global	1	exact	0	exact	()	agree	
+PetStopAttack	0x4be4b0	0x847610	0x8475a0	global	0	exact	0	exact	()	agree	
+PetWait	0x4be480	0x8475f8	0x8475a0	global	0	exact	0	exact	()	agree	
+PickupAction	0x4e71d0	0x84bd48	0x84bd10	global	1	exact	0	exact	()	agree	
+PickupBagFromSlot	0x4c8fa0	0x848538	0x8484d0	global	0	lower-bound	0	exact	()	agree	
+PickupContainerItem	0x4f9b30	0x84d6b0	0x84d688	global	2	lower-bound	0	exact	()	agree	
+PickupInventoryItem	0x4c8da0	0x848510	0x8484d0	global	0	lower-bound	0	exact	()	agree	
+PickupMacro	0x4f1ae0	0x84c9c8	0x84c990	global	1	exact	0	exact	()	agree	
+PickupMerchantItem	0x4fb760	0x84da58	0x84da28	global	1	exact	0	exact	()	agree	
+PickupPetAction	0x4be180	0x8475c8	0x8475a0	global	1	exact	0	exact	()	agree	
+PickupPlayerMoney	0x48abc0	0x83e1a0	0x83de68	global	1	exact	0	exact	()	agree	
+PickupSpell	0x4b42a0	0x846680	0x846648	global	0	lower-bound	0	exact	()	agree	
+PickupStablePet	0x4cb7a0	0x848de8	0x848da0	global	1	exact	0	exact	()	agree	
+PickupTradeMoney	0x4c0790	0x847a50	0x8479f8	global	1	exact	0	exact	()	agree	
+PingLocation	0x4eeca0	0x84c578	0x84c538	widget	3	exact	0	exact	()	agree	
+PitchDownStart	0x5140c0	0x850140	0x8500b8	global	0	exact	0	exact	()	agree	
+PitchDownStop	0x5140f0	0x850148	0x8500b8	global	0	exact	0	exact	()	agree	
+PitchUpStart	0x514060	0x850130	0x8500b8	global	0	exact	0	exact	()	agree	
+PitchUpStop	0x514090	0x850138	0x8500b8	global	0	exact	0	exact	()	agree	
+PlaceAction	0x4e7240	0x84bd50	0x84bd10	global	1	exact	0	exact	()	agree	
+PlaceAuctionBid	0x4cf610	0x849110	0x8490a8	global	3	exact	0	exact	()	agree	
+PlayCreditsMusic	0x46cef0	0x8373f0	0x8373b8	global	0	exact	0	exact	()	agree	
+PlayGlueMusic	0x46ceb0	0x8373e8	0x8373b8	global	1	exact	0	exact	()	agree	
+PlayMusic	0x458720	0x835a58	0x835a50	global	1	exact	0	exact	()	agree	
+PlaySound	0x4586d0	0x835a50	0x835a50	global	1	exact	0	exact	()	agree	
+PlaySoundFile	0x458780	0x835a60	0x835a50	global	1	exact	1	exact	(nil) | (number)	agree	
+PlayerHasSpells	0x4b43f0	0x8466a0	0x846648	global	0	exact	1	exact	(number)	agree	
+PositionMiniWorldMapArrowFrame	0x4a8f20	0x845118	0x845078	global	5	exact	0	exact	()	agree	
+PositionWorldMapArrowFrame	0x4a8d20	0x845110	0x845078	global	5	exact	0	exact	()	agree	
+PrevView	0x50b690	0x84f838	0x84f7a0	global	0	exact	0	exact	()	agree	
+ProcessMapClick	0x4a7f30	0x8450b0	0x845078	global	2	exact	0	exact	()	agree	
+PromoteByName	0x48a830	0x83e110	0x83de68	global	1	exact	0	exact	()	agree	
+PromoteToAssistant	0x4bbd20	0x847288	0x847240	global	1	exact	0	exact	()	agree	
+PromoteToPartyLeader	0x48a7c0	0x83e108	0x83de68	global	1	exact	0	exact	()	agree	
+PurchaseSlot	0x4f86b0	0x84d5f4	0x84d5dc	global	0	exact	0	exact	()	agree	
+PutItemInBackpack	0x4c8f70	0x848530	0x8484d0	global	0	exact	1	exact	(nil) | (number)	agree	
+PutItemInBag	0x4c8f00	0x848528	0x8484d0	global	0	lower-bound	1	exact	(nil) | (number)	agree	
+QueryAuctionItems	0x4ce980	0x8490d8	0x8490a8	global	9	exact	0	exact	()	agree	
+QuestChooseRewardError	0x5021a0	0x84ea48	0x84e968	global	0	exact	0	exact	()	agree	
+QuestLogPushQuest	0x4e1340	0x84b1a8	0x84b0f0	global	0	exact	0	exact	()	agree	
+Quit	0x4893b0	0x83dfb8	0x83de68	global	0	exact	0	exact	()	agree	
+QuitGame	0x46cea0	0x8373e0	0x8373b8	global	0	exact	0	exact	()	agree	
+Raise	0x775a50	0x878fe0	0x878ec0	widget	1	exact	0	exact	()	agree	
+RandomRoll	0x48c7b0	0x83e2d8	0x83de68	global	2	exact	0	exact	()	agree	
+RandomizeCharCustomization	0x471900	0x838190	0x8380f8	global	0	exact	0	exact	()	agree	
+ReadFile	0x515f50	0x85040c	0x8503f4	global	0	exact	?	unknown	?	unknown	
+RealmListDialogCancelled	0x46ed20	0x837ee8	0x837ea0	global	0	exact	0	exact	()	agree	
+RefreshUnit	0x505e40	0x84f204	0x84f1fc	widget	1	exact	0	exact	()	agree	
+RegisterAllEvents	0x774c20	0x878f58	0x878ec0	widget	1	exact	0	exact	()	agree	
+RegisterCVar	0x488b00	0x83dee0	0x83de68	global	2	exact	0	exact	()	agree	
+RegisterEvent	0x774a40	0x878f48	0x878ec0	widget	2	exact	0	exact	()	agree	
+RegisterForClicks	0x782490	0x879e18	0x879d00	widget	10	lower-bound	0	exact	()	agree	
+RegisterForDrag	0x776d60	0x879078	0x878ec0	widget	10	lower-bound	?	unknown	()	unverified	
+RegisterForSave	0x4884e0	0x83de80	0x83de68	global	1	exact	0	exact	()	agree	
+ReloadUI	0x4884d0	0x83de78	0x83de68	global	0	exact	0	exact	()	agree	
+RemoveChatWindowChannel	0x4a1260	0x843738	0x843618	global	2	exact	0	exact	()	agree	
+RemoveChatWindowMessages	0x4a0f40	0x843728	0x843618	global	2	exact	0	exact	()	agree	
+RemoveFriend	0x5ad2d0	0x85d858	0x85d830	global	1	exact	0	exact	()	agree	
+RemoveQuestWatch	0x4e1970	0x84b1f0	0x84b0f0	global	1	exact	0	exact	()	agree	
+RemoveSkillUp	0x4d3c70	0x849d28	0x849cf8	global	1	exact	0	exact	()	agree	
+RenameCharacter	0x473520	0x8385b0	0x838578	global	2	lower-bound	0|1	set	() | (nil) | (number)	agree	delegated-push
+RenamePetition	0x4f4930	0x84ced8	0x84cea0	global	1	exact	0	exact	()	agree	
+RepairAllItems	0x4fbfe0	0x84daa8	0x84da28	global	0	exact	0	exact	()	agree	
+ReplaceEnchant	0x48d300	0x83e388	0x83de68	global	0	exact	0	exact	()	agree	
+ReplaceIconTexture	0x76ed70	0x8789c0	0x878948	widget	2	exact	0	exact	()	agree	
+ReplaceTradeEnchant	0x48d330	0x83e390	0x83de68	global	0	exact	0	exact	()	agree	
+RepopMe	0x48a970	0x83e120	0x83de68	global	0	exact	0	exact	()	agree	
+RequestBattlefieldPositions	0x4abef0	0x8458a0	0x8457e0	global	0	exact	0	exact	()	agree	
+RequestBattlefieldScoreData	0x4ab990	0x845858	0x8457e0	global	0	exact	0	exact	()	agree	
+RequestInspectHonorData	0x4c9610	0x848580	0x8484d0	global	0	exact	0	exact	()	agree	
+RequestRaidInfo	0x4a1850	0x843780	0x843618	global	0	exact	0	exact	()	agree	
+RequestRealmList	0x46ecf0	0x837ea0	0x837ea0	global	1	exact	0	exact	()	agree	
+RequestTimePlayed	0x48a900	0x83e118	0x83de68	global	0	exact	0	exact	()	agree	
+ResetAddOns	0x46d9a0	0x837520	0x8373b8	global	0	exact	0	exact	()	agree	
+ResetCharCustomize	0x4713e0	0x838108	0x8380f8	global	0	exact	0	exact	()	agree	
+ResetChatColors	0x4a09e0	0x8436f8	0x843618	global	0	exact	0	exact	()	agree	
+ResetCursor	0x48ac70	0x83e1b0	0x83de68	global	0	exact	0	exact	()	agree	
+ResetDisabledAddOns	0x48e830	0x83e4d8	0x83de68	global	0	exact	0	exact	()	agree	
+ResetInstances	0x48a6b0	0x83e510	0x83de68	global	0	exact	0	exact	()	agree	
+ResetPerformanceValues	0x489430	0x83ded0	0x83de68	global	0	exact	0	exact	()	agree	
+ResetTutorials	0x4b5a10	0x846b1c	0x846b04	global	0	exact	0	exact	()	agree	
+ResetView	0x50b640	0x84f828	0x84f7a0	global	1	exact	0	exact	()	agree	
+RestartGx	0x48dab0	0x83e400	0x83de68	global	0	exact	0	exact	()	agree	
+RestoreVideoDefaults	0x48dad0	0x83e408	0x83de68	global	0	exact	0	exact	()	agree	
+ResurrectHasSickness	0x48aa00	0x83e138	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+ResurrectHasTimer	0x48aa30	0x83e140	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+RetrieveCorpse	0x48d260	0x83e378	0x83de68	global	0	exact	0	exact	()	agree	
+ReturnInboxItem	0x4afba0	0x845f80	0x845eb0	global	1	exact	0	exact	()	agree	
+RollOnLoot	0x4c3370	0x847d60	0x847cf0	global	2	exact	0	exact	()	agree	
+RunBinding	0x4b8180	0x846cb0	0x846c88	global	2	exact	0	exact	()	agree	delegated-push
+RunScript	0x48b980	0x83e288	0x83de68	global	1	exact	0	exact	()	agree	
+Save	0x502bd0	0x84ee48	0x84ee40	widget	1	exact	0	exact	()	agree	
+SaveAddOns	0x46d990	0x837518	0x8373b8	global	0	exact	0	exact	()	agree	
+SaveBindings	0x4b8260	0x846cc8	0x846c88	global	1	exact	0	exact	()	agree	
+SaveView	0x50b600	0x84f820	0x84f7a0	global	1	exact	0	exact	()	agree	
+ScanningAccepted	0x46d0b0	0x837458	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+Screenshot	0x46d3d0	0x8374b0	0x8373b8	global	0	exact	0	exact	()	agree	name-not-unique
+Screenshot	0x4893d0	0x83deb0	0x83de68	global	0	exact	0	exact	()	agree	name-not-unique
+ScrollDown	0x792c60	0x87b650	0x87b5c0	widget	1	exact	0	exact	()	agree	
+ScrollToBottom	0x792fa0	0x87b670	0x87b5c0	widget	1	exact	0	exact	()	agree	
+ScrollToTop	0x792ed0	0x87b668	0x87b5c0	widget	1	exact	0	exact	()	agree	
+ScrollUp	0x792b90	0x87b648	0x87b5c0	widget	1	exact	0	exact	()	agree	
+SelectActiveQuest	0x501ce0	0x84e9d8	0x84e968	global	1	exact	0	exact	()	agree	
+SelectAvailableQuest	0x501ca0	0x84e9d0	0x84e968	global	1	exact	0	exact	()	agree	
+SelectCharacter	0x473470	0x8385a0	0x838578	global	1	exact	0	exact	()	agree	
+SelectCraft	0x4f70f0	0x84d138	0x84d108	global	1	exact	0	exact	()	agree	
+SelectGossipActiveQuest	0x4e2ae0	0x84b818	0x84b7e8	global	1	exact	0	exact	()	agree	
+SelectGossipAvailableQuest	0x4e2aa0	0x84b810	0x84b7e8	global	1	exact	0	exact	()	agree	
+SelectGossipOption	0x4e2a30	0x84b808	0x84b7e8	global	2	exact	0	exact	()	agree	
+SelectPackage	0x4ae550	0x845f18	0x845eb0	global	1	exact	0	exact	()	agree	
+SelectQuestLogEntry	0x4dfae0	0x84b100	0x84b0f0	global	1	exact	0	exact	()	agree	
+SelectStationery	0x4ae380	0x845ef8	0x845eb0	global	1	exact	0	exact	()	agree	
+SelectTradeSkill	0x4fd9b0	0x84dde8	0x84ddd0	global	1	exact	0	exact	()	agree	
+SelectTrainerService	0x4d8e60	0x84a400	0x84a3e0	global	1	exact	0	exact	()	agree	
+SendAddonMessage	0x49f920	0x843620	0x843618	global	3	exact	0	exact	()	agree	
+SendChatMessage	0x49f1e0	0x843618	0x843618	global	4	lower-bound	0	exact	()	agree	delegated-push
+SendMail	0x4ae800	0x845f30	0x845eb0	global	3	lower-bound	0	exact	()	agree	delegated-push
+SendWho	0x5ad3b0	0x85d8a0	0x85d830	global	1	exact	0	exact	()	agree	
+SetAbandonQuest	0x4dfb50	0x84b110	0x84b0f0	global	0	exact	0	exact	()	agree	
+SetAction	0x5322a0	0x854200	0x854198	widget	2	lower-bound	1	exact	(nil) | (number)	agree	delegated-push
+SetActionBarToggles	0x4e76e0	0x84bdb0	0x84bd10	global	8	lower-bound	0	exact	()	agree	
+SetAddonVersionCheck	0x46d9e0	0x837530	0x8373b8	global	1	exact	0	exact	()	agree	
+SetAllPoints	0x7a2940	0x87ca40	0x87c9b8	widget	2	exact	0	exact	()	agree	
+SetAlpha	0x774e90	0x878f70	0x878ec0	widget	2	exact	0	exact	()	agree	name-not-unique
+SetAlpha	0x79b580	0x87c168	0x87c128	widget	2	exact	0	exact	()	agree	name-not-unique
+SetAlpha	0x79cb70	0x87c1f8	0x87c1d8	widget	2	exact	0	exact	()	agree	name-not-unique
+SetAlpha	0x7a03f0	0x87c808	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetAlphaGradient	0x79cc80	0x87c200	0x87c1d8	widget	3	exact	1	exact	(nil) | (number)	agree	
+SetAltArrowKeyMode	0x7996e0	0x87bcd8	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetArrowModel	0x4ee980	0x84c550	0x84c538	widget	2	exact	0	exact	()	agree	
+SetAuctionCompareItem	0x535d70	0x8542e8	0x854198	widget	4	exact	1	exact	(nil) | (number)	agree	
+SetAuctionItem	0x535810	0x8542c8	0x854198	widget	3	exact	1	exact	(nil) | (number)	agree	
+SetAuctionSellItem	0x535700	0x8542c0	0x854198	widget	1	exact	1	exact	(nil) | (number)	agree	
+SetAutoFocus	0x797c90	0x87bbe8	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetBackdrop	0x7776e0	0x8790b8	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetBackdropBorderColor	0x7780d0	0x8790d8	0x878ec0	widget	5	exact	0	exact	()	agree	
+SetBackdropColor	0x777d30	0x8790c8	0x878ec0	widget	5	exact	0	exact	()	agree	
+SetBagItem	0x534620	0x854288	0x854198	widget	3	exact	0|1|2	set	() | (nil) | (nil,number) | (number,number)	agree	
+SetBagPortaitTexture	0x4fa4f0	0x84d6d0	0x84d688	global	2	exact	0	exact	()	agree	
+SetBaseMip	0x4892b0	0x83df60	0x83de68	global	1	exact	0	exact	()	agree	
+SetBattlefieldScoreFaction	0x4abc90	0x845878	0x8457e0	global	1	exact	0	exact	()	agree	
+SetBinding	0x4b8000	0x846c98	0x846c88	global	2	lower-bound	1	exact	(nil) | (number)	agree	delegated-push
+SetBlendMode	0x79a950	0x87c140	0x87c128	widget	2	exact	0	exact	()	agree	
+SetBlinkSpeed	0x798250	0x87bc28	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetBlipTexture	0x4ee7e0	0x84c548	0x84c538	widget	2	exact	0	exact	()	agree	
+SetButtonState	0x780270	0x879d20	0x879d00	widget	3	exact	0	exact	()	agree	
+SetBuybackItem	0x536300	0x8542f8	0x854198	widget	2	exact	0	exact	()	agree	
+SetCVar	0x488c10	0x83def0	0x83de68	global	3	lower-bound	0	exact	()	agree	delegated-push
+SetCamera	0x76e0e0	0x878988	0x878948	widget	2	exact	0	exact	()	agree	
+SetChannelOwner	0x4a0490	0x843688	0x843618	global	0	lower-bound	0	exact	()	agree	
+SetChannelPassword	0x4a03a0	0x843680	0x843618	global	2	exact	0	exact	()	agree	
+SetCharCustomizeBackground	0x4713a0	0x838100	0x8380f8	global	1	exact	0	exact	()	agree	
+SetCharCustomizeFrame	0x471330	0x8380f8	0x8380f8	global	1	lower-bound	0	exact	()	agree	delegated-push
+SetCharSelectBackground	0x473230	0x838580	0x838578	global	1	exact	0	exact	()	agree	
+SetCharSelectModelFrame	0x4731c0	0x838578	0x838578	global	1	lower-bound	0	exact	()	agree	delegated-push
+SetCharacterCreateFacing	0x471930	0x8381a0	0x8380f8	global	1	exact	1	exact	()	unverified	
+SetCharacterSelectFacing	0x473670	0x8385c8	0x838578	global	1	exact	1	exact	()	unverified	
+SetChatWindowAlpha	0x4a15d0	0x843758	0x843618	global	2	exact	0	exact	()	agree	
+SetChatWindowColor	0x4a14f0	0x843750	0x843618	global	4	exact	0	exact	()	agree	
+SetChatWindowDocked	0x4a16b0	0x843768	0x843618	global	2	exact	0	exact	()	agree	
+SetChatWindowLocked	0x4a1650	0x843760	0x843618	global	2	exact	0	exact	()	agree	
+SetChatWindowName	0x4a13f0	0x843740	0x843618	global	2	exact	0	exact	()	agree	
+SetChatWindowShown	0x4a1730	0x843770	0x843618	global	2	exact	0	exact	()	agree	
+SetChatWindowSize	0x4a1470	0x843748	0x843618	global	2	exact	0	exact	()	agree	
+SetChecked	0x799bf0	0x87bf74	0x87bf74	widget	2	exact	0	exact	()	agree	
+SetCheckedTexture	0x799e50	0x87bf8c	0x87bf74	widget	2	exact	0	exact	()	agree	
+SetClampedToScreen	0x776c00	0x879068	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetColorHSV	0x78e920	0x87abf0	0x87abb0	widget	4	exact	0	exact	()	agree	
+SetColorRGB	0x78eae0	0x87ac00	0x87abb0	widget	5	exact	0	exact	()	agree	
+SetColorValueTexture	0x78e450	0x87abd8	0x87abb0	widget	2	exact	0	exact	()	agree	
+SetColorValueThumbTexture	0x78e720	0x87abe8	0x87abb0	widget	2	exact	0	exact	()	agree	
+SetColorWheelTexture	0x78de90	0x87abb8	0x87abb0	widget	2	exact	0	exact	()	agree	
+SetColorWheelThumbTexture	0x78e160	0x87abc8	0x87abb0	widget	2	exact	0	exact	()	agree	
+SetConsoleKey	0x488640	0x83dea8	0x83de68	global	1	exact	0	exact	()	agree	
+SetCraftItem	0x533cd0	0x854260	0x854198	widget	3	exact	0	exact	()	agree	
+SetCraftSpell	0x533e90	0x854268	0x854198	widget	2	exact	0	exact	()	agree	
+SetCurrentScreen	0x46ce60	0x8373d8	0x8373b8	global	1	exact	0	exact	()	agree	
+SetCursor	0x489490	0x83dfe0	0x83de68	global	1	exact	0|1	set	() | (nil) | (number)	agree	
+SetDesaturated	0x79c1e0	0x87c1c8	0x87c128	widget	2	exact	1	exact	(nil) | (number)	agree	
+SetDisabledCheckedTexture	0x79a140	0x87bf9c	0x87bf74	widget	2	exact	0	exact	()	agree	
+SetDisabledFontObject	0x780580	0x879d38	0x879d00	widget	1	lower-bound	?	unknown	()	unverified	delegated-push
+SetDisabledTextColor	0x781260	0x879d98	0x879d00	widget	5	exact	0	exact	()	agree	
+SetDisabledTexture	0x781ce0	0x879dd8	0x879d00	widget	0	lower-bound	?	unknown	()	unverified	delegated-push
+SetDoodadAnim	0x489090	0x83df48	0x83de68	global	1	exact	0	exact	()	agree	
+SetDrawLayer	0x79a780	0x87c130	0x87c128	widget	2	exact	0	exact	()	agree	name-not-unique
+SetDrawLayer	0x79c720	0x87c1e0	0x87c1d8	widget	2	exact	0	exact	()	agree	name-not-unique
+SetEuropeanNumbers	0x48dec0	0x83e458	0x83de68	global	1	exact	0	exact	()	agree	
+SetFacing	0x76dce0	0x878968	0x878948	widget	2	exact	0	exact	()	agree	
+SetFactionActive	0x4d6a00	0x84a0e0	0x84a0a8	global	1	exact	0	exact	()	agree	
+SetFactionInactive	0x4d69b0	0x84a0d8	0x84a0a8	global	1	exact	0	exact	()	agree	
+SetFadeDuration	0x793cb0	0x87b6e8	0x87b5c0	widget	2	exact	0	exact	()	agree	name-not-unique
+SetFadeDuration	0x7953e0	0x87ba10	0x87b960	widget	2	exact	0	exact	()	agree	name-not-unique
+SetFading	0x7939a0	0x87b6c8	0x87b5c0	widget	2	exact	0	exact	()	agree	name-not-unique
+SetFading	0x7950d0	0x87b9f0	0x87b960	widget	2	exact	0	exact	()	agree	name-not-unique
+SetFarclip	0x488f30	0x83df28	0x83de68	global	1	exact	0	exact	()	agree	
+SetFocus	0x798d90	0x87bc80	0x87bb68	widget	1	exact	0	exact	()	agree	
+SetFogColor	0x76ee60	0x8789c8	0x878948	widget	5	exact	0	exact	()	agree	
+SetFogFar	0x76f390	0x8789e8	0x878948	widget	2	exact	0	exact	()	agree	
+SetFogNear	0x76f1e0	0x8789d8	0x878948	widget	2	exact	0	exact	()	agree	
+SetFont	0x780880	0x879d58	0x879d00	widget	1	lower-bound	0	exact	()	agree	name-not-unique;delegated-push
+SetFont	0x791e80	0x87b5d0	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFont	0x794450	0x87b970	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFont	0x795f30	0x87ba90	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFont	0x797210	0x87bb78	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFont	0x79d4f0	0x87c240	0x87c1d8	widget	4	exact	1	exact	(nil) | (number)	agree	name-not-unique
+SetFont	0x7a0270	0x87c7f8	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFontObject	0x791d00	0x87b5c0	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFontObject	0x7942b0	0x87b960	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFontObject	0x795cb0	0x87ba80	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFontObject	0x797090	0x87bb68	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFontObject	0x79d1a0	0x87c230	0x87c1d8	widget	2	exact	0	exact	()	agree	name-not-unique
+SetFontObject	0x7a0030	0x87c7e0	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique;delegated-push
+SetFontString	0x780a60	0x879d68	0x879d00	widget	2	exact	0	exact	()	agree	
+SetFrameLevel	0x774560	0x878f28	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetFrameStrata	0x774360	0x878f18	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetGamma	0x4891f0	0x83df78	0x83de68	global	1	exact	0	exact	()	agree	
+SetGradient	0x79ae30	0x87c158	0x87c128	widget	8	exact	0	exact	()	agree	
+SetGradientAlpha	0x79b180	0x87c160	0x87c128	widget	10	exact	0	exact	()	agree	
+SetGuildInfoText	0x4d2380	0x8497d0	0x8496d8	global	1	exact	0	exact	()	agree	
+SetGuildRecruitmentMode	0x4a0060	0x843790	0x843618	global	1	lower-bound	0	exact	()	agree	delegated-push
+SetGuildRosterSelection	0x4d1820	0x849708	0x8496d8	global	1	exact	0	exact	()	agree	
+SetGuildRosterShowOffline	0x4d1e10	0x849768	0x8496d8	global	1	exact	0	exact	()	agree	
+SetHeight	0x7a2150	0x87ca20	0x87c9b8	widget	2	exact	0	exact	()	agree	
+SetHighlightFontObject	0x780700	0x879d48	0x879d00	widget	1	lower-bound	?	unknown	()	unverified	delegated-push
+SetHighlightTextColor	0x7815e0	0x879da8	0x879d00	widget	5	exact	0	exact	()	agree	
+SetHighlightTexture	0x781d00	0x879de8	0x879d00	widget	3	exact	0	exact	()	agree	
+SetHistoryLines	0x799450	0x87bcc0	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetHitRectInsets	0x775d50	0x878ff8	0x878ec0	widget	5	exact	0	exact	()	agree	
+SetHorizontalScroll	0x7912f0	0x87b3d0	0x87b3c0	widget	2	exact	0	exact	()	agree	
+SetHyperlink	0x531fd0	0x8541f8	0x854198	widget	2	exact	0	exact	()	agree	
+SetHyperlinkFormat	0x796b40	0x87bb08	0x87ba80	widget	2	exact	0	exact	()	agree	
+SetID	0x775340	0x878f98	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetIconTexture	0x4ee640	0x84c540	0x84c538	widget	2	exact	0	exact	()	agree	
+SetInboxItem	0x5354c0	0x8542b8	0x854198	widget	2	exact	1	exact	(nil) | (number)	agree	
+SetInsertMode	0x794ed0	0x87b9e0	0x87b960	widget	2	exact	0	exact	()	agree	
+SetInventoryItem	0x532ee0	0x854230	0x854198	widget	4	exact	2|3	set	(nil,nil) | (nil,nil,number) | (number,nil) | (number,nil,number) | (number,number,number)	agree	
+SetInventoryPortaitTexture	0x4c9150	0x848550	0x8484d0	global	2	lower-bound	0	exact	()	agree	
+SetJustifyH	0x792600	0x87b620	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyH	0x794bd0	0x87b9c0	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyH	0x796750	0x87bae0	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyH	0x797990	0x87bbc8	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyH	0x79e6b0	0x87c2b0	0x87c1d8	widget	2	exact	0	exact	()	agree	name-not-unique
+SetJustifyH	0x7a0b70	0x87c858	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyV	0x792780	0x87b630	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyV	0x794d50	0x87b9d0	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyV	0x7968f0	0x87baf0	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyV	0x797b10	0x87bbd8	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetJustifyV	0x79e8b0	0x87c2c0	0x87c1d8	widget	2	exact	0	exact	()	agree	name-not-unique
+SetJustifyV	0x7a0cf0	0x87c868	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetLayoutMode	0x488540	0x83de88	0x83de68	global	1	exact	0	exact	()	agree	
+SetLight	0x76e1e0	0x878990	0x878948	widget	14	exact	0	exact	()	agree	
+SetLookingForGroup	0x4e96b0	0x84c1c0	0x84c170	global	16	lower-bound	0	exact	()	agree	
+SetLootItem	0x533470	0x854238	0x854198	widget	2	exact	0	exact	()	agree	
+SetLootMethod	0x4e92a0	0x84c1a0	0x84c170	global	3	exact	0	exact	()	agree	
+SetLootPortrait	0x4c2b40	0x847cf0	0x847cf0	global	1	exact	1	exact	(nil) | (number)	agree	
+SetLootRollItem	0x5364a0	0x854300	0x854198	widget	2	exact	0	exact	()	agree	
+SetLootThreshold	0x4e9500	0x84c1b0	0x84c170	global	1	exact	0	exact	()	agree	
+SetMapToCurrentZone	0x4a7e20	0x845090	0x845078	global	0	exact	0	exact	()	agree	
+SetMapZoom	0x4a7db0	0x845088	0x845078	global	2	exact	0	exact	()	agree	
+SetMaskTexture	0x4ee4a0	0x84c538	0x84c538	widget	2	exact	0	exact	()	agree	
+SetMaxBytes	0x798f30	0x87bc90	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetMaxLetters	0x799110	0x87bca0	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetMaxLines	0x7938a0	0x87b6c0	0x87b5c0	widget	2	exact	0	exact	()	agree	
+SetMaxResize	0x7762a0	0x879018	0x878ec0	widget	3	exact	0	exact	()	agree	
+SetMerchantCompareItem	0x536080	0x8542f0	0x854198	widget	3	exact	1	exact	(nil) | (number)	agree	
+SetMerchantItem	0x534080	0x854270	0x854198	widget	2	exact	0	exact	()	agree	
+SetMinMaxValues	0x78f4b0	0x87b028	0x87b010	widget	3	exact	0	exact	()	agree	name-not-unique
+SetMinMaxValues	0x7907a0	0x87b288	0x87b260	widget	3	exact	0	exact	()	agree	name-not-unique
+SetMinResize	0x776020	0x879008	0x878ec0	widget	3	exact	0	exact	()	agree	
+SetMinimumWidth	0x530e50	0x8541a0	0x854198	widget	2	exact	0	exact	()	agree	
+SetModel	0x76d950	0x878948	0x878948	widget	2	exact	0	exact	()	agree	
+SetModelScale	0x76ddd0	0x878970	0x878948	widget	2	exact	0	exact	()	agree	
+SetMovable	0x776420	0x879020	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetMovieSubtitles	0x46db80	0x837560	0x8373b8	global	1	exact	0	exact	()	agree	
+SetMultiLine	0x797e00	0x87bbf8	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetMultisampleFormat	0x48c640	0x83e2d0	0x83de68	global	1	exact	0	exact	()	agree	
+SetNonSpaceWrap	0x79e9f0	0x87c2c8	0x87c1d8	widget	2	exact	0	exact	()	agree	
+SetNormalTexture	0x781960	0x879db8	0x879d00	widget	0	lower-bound	?	unknown	()	unverified	delegated-push
+SetNumber	0x798690	0x87bc50	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetNumeric	0x797f70	0x87bc08	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetOrientation	0x78f290	0x87b018	0x87b010	widget	2	exact	0	exact	()	agree	name-not-unique
+SetOrientation	0x790580	0x87b278	0x87b260	widget	2	exact	0	exact	()	agree	name-not-unique
+SetOwner	0x5310d0	0x8541b8	0x854198	widget	5	exact	0	exact	()	agree	
+SetPadding	0x530f10	0x8541a8	0x854198	widget	2	exact	0	exact	()	agree	
+SetParent	0x7a1550	0x87c9d8	0x87c9b8	widget	2	lower-bound	0	exact	()	agree	delegated-push
+SetPassword	0x7980e0	0x87bc18	0x87bb68	widget	2	exact	0	exact	()	agree	
+SetPetAction	0x532730	0x854208	0x854198	widget	2	exact	1	exact	(nil) | (number)	agree	
+SetPetStablePaperdoll	0x4cb870	0x848df8	0x848da0	global	1	exact	0	exact	()	agree	
+SetPlayerBuff	0x532b00	0x854218	0x854198	widget	2	exact	0	exact	()	agree	
+SetPlayerModel	0x4eeab0	0x84c558	0x84c538	widget	2	exact	0	exact	()	agree	
+SetPoint	0x7a2540	0x87ca38	0x87c9b8	widget	6	exact	0	exact	()	agree	
+SetPortraitTexture	0x519ef0	0x850628	0x850438	global	2	exact	0	exact	()	agree	
+SetPortraitToTexture	0x48d780	0x83e3e0	0x83de68	global	2	lower-bound	0	exact	()	agree	delegated-push
+SetPosition	0x76dc00	0x878960	0x878948	widget	4	exact	0	exact	()	agree	
+SetPreferredInfo	0x46f2c0	0x837ed0	0x837ea0	global	3	exact	0	exact	()	agree	
+SetPushedTextOffset	0x782030	0x879df8	0x879d00	widget	3	exact	0	exact	()	agree	
+SetPushedTexture	0x781cc0	0x879dc8	0x879d00	widget	0	lower-bound	?	unknown	()	unverified	delegated-push
+SetQuestItem	0x533610	0x854240	0x854198	widget	3	exact	0	exact	()	agree	
+SetQuestLogItem	0x533760	0x854248	0x854198	widget	3	exact	0	exact	()	agree	
+SetQuestLogRewardSpell	0x535c60	0x8542e0	0x854198	widget	1	exact	0	exact	()	agree	
+SetQuestRewardSpell	0x535bb0	0x8542d8	0x854198	widget	1	exact	0	exact	()	agree	
+SetRaidRosterSelection	0x4bb820	0x847250	0x847240	global	1	exact	0	exact	()	agree	
+SetRaidSubgroup	0x4bb990	0x847270	0x847240	global	2	exact	0	exact	()	agree	
+SetRaidTarget	0x4bbec0	0x847298	0x847240	global	2	exact	0	exact	()	agree	
+SetResizable	0x776590	0x879030	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetRotation	0x505f00	0x84f20c	0x84f1fc	widget	2	exact	0	exact	()	agree	
+SetSavedAccountName	0x46cdf0	0x8373d0	0x8373b8	global	1	exact	0	exact	()	agree	
+SetScale	0x775140	0x878f88	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetScreenResolution	0x48bfd0	0x83e2a8	0x83de68	global	1	exact	0	exact	()	agree	
+SetScript	0x7748d0	0x878f40	0x878ec0	widget	3	lower-bound	0	exact	()	agree	delegated-push
+SetScriptMemory	0x46da50	0x837540	0x8373b8	global	1	exact	0	exact	()	agree	
+SetScrollChild	0x790fa0	0x87b3c0	0x87b3c0	widget	2	lower-bound	0	exact	()	agree	delegated-push
+SetScrollFromBottom	0x793070	0x87b678	0x87b5c0	widget	2	exact	0	exact	()	agree	
+SetSelectedAuctionItem	0x4cfda0	0x849140	0x8490a8	global	2	exact	0	exact	()	agree	
+SetSelectedBattlefield	0x4ab300	0x845800	0x8457e0	global	1	exact	0	exact	()	agree	
+SetSelectedClass	0x4717c0	0x838168	0x8380f8	global	1	exact	0	exact	()	agree	
+SetSelectedFaction	0x4d6bb0	0x84a0f8	0x84a0a8	global	1	exact	0	exact	()	agree	
+SetSelectedFriend	0x5ad210	0x85d840	0x85d830	global	1	exact	0	exact	()	agree	
+SetSelectedIgnore	0x5ad520	0x85d878	0x85d830	global	1	exact	0	exact	()	agree	
+SetSelectedRace	0x471740	0x838158	0x8380f8	global	1	exact	0	exact	()	agree	
+SetSelectedSex	0x471780	0x838160	0x8380f8	global	1	exact	0	exact	()	agree	
+SetSelectedSkill	0x4d4020	0x849d50	0x849cf8	global	1	exact	0	exact	()	agree	
+SetSendMailCOD	0x4ae180	0x845ed8	0x845eb0	global	1	exact	0	exact	()	agree	
+SetSendMailItem	0x5353b0	0x8542b0	0x854198	widget	1	exact	1	exact	(nil) | (number)	agree	
+SetSendMailMoney	0x4ae0f0	0x845ec8	0x845eb0	global	1	exact	1	exact	(nil) | (number)	agree	
+SetSequence	0x76dec0	0x878978	0x878948	widget	2	exact	0	exact	()	agree	
+SetSequenceTime	0x76dfc0	0x878980	0x878948	widget	3	exact	0	exact	()	agree	
+SetShadowColor	0x792180	0x87b5f0	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowColor	0x794750	0x87b990	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowColor	0x796270	0x87bab0	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowColor	0x797510	0x87bb98	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowColor	0x79dd40	0x87c270	0x87c1d8	widget	5	exact	0	exact	()	agree	name-not-unique
+SetShadowColor	0x7a06f0	0x87c828	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowOffset	0x792300	0x87b600	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowOffset	0x7948d0	0x87b9a0	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowOffset	0x796410	0x87bac0	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowOffset	0x797690	0x87bba8	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShadowOffset	0x79e070	0x87c280	0x87c1d8	widget	3	exact	0	exact	()	agree	name-not-unique
+SetShadowOffset	0x7a0870	0x87c838	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetShapeshift	0x532920	0x854210	0x854198	widget	2	exact	1	exact	(nil) | (number)	agree	
+SetSlot	0x4c1880	0x847ce4	0x847ce4	widget	2	exact	0	exact	()	agree	
+SetSpacing	0x792480	0x87b610	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetSpacing	0x794a50	0x87b9b0	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetSpacing	0x7965b0	0x87bad0	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetSpacing	0x797810	0x87bbb8	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetSpacing	0x79e2b0	0x87c290	0x87c1d8	widget	2	exact	0	exact	()	agree	name-not-unique
+SetSpacing	0x7a09f0	0x87c848	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetSpell	0x532d10	0x854228	0x854198	widget	3	exact	1	exact	(nil) | (number)	agree	
+SetStatusBarColor	0x78fc20	0x87b058	0x87b010	widget	5	exact	0	exact	()	agree	
+SetStatusBarTexture	0x78f870	0x87b048	0x87b010	widget	3	exact	0	exact	()	agree	
+SetTalent	0x535170	0x8542a8	0x854198	widget	3	exact	0	exact	()	agree	
+SetTaxiMap	0x4dca50	0x84ada8	0x84ada8	global	1	exact	0	exact	()	agree	
+SetTerrainMip	0x488fe0	0x83df38	0x83de68	global	1	exact	0	exact	()	agree	
+SetTexCoord	0x79beb0	0x87c1b0	0x87c128	widget	17	lower-bound	0	exact	()	agree	
+SetTexCoordModifiesRect	0x79c080	0x87c1b8	0x87c128	widget	2	exact	0	exact	()	agree	
+SetTexLodBias	0x489140	0x83df58	0x83de68	global	1	exact	0	exact	()	agree	
+SetText	0x531b90	0x8541e0	0x854198	widget	7	exact	0	exact	()	agree	name-not-unique
+SetText	0x780d20	0x879d78	0x879d00	widget	2	exact	0	exact	()	agree	name-not-unique
+SetText	0x796a90	0x87bb00	0x87ba80	widget	2	exact	0	exact	()	agree	name-not-unique
+SetText	0x7984c0	0x87bc40	0x87bb68	widget	2	exact	0	exact	()	agree	name-not-unique
+SetText	0x79d760	0x87c250	0x87c1d8	widget	2	exact	0	exact	()	agree	name-not-unique
+SetTextColor	0x780ee0	0x879d88	0x879d00	widget	5	exact	0	exact	()	agree	name-not-unique
+SetTextColor	0x792000	0x87b5e0	0x87b5c0	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetTextColor	0x7945d0	0x87b980	0x87b960	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetTextColor	0x7960d0	0x87baa0	0x87ba80	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetTextColor	0x797390	0x87bb88	0x87bb68	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetTextColor	0x79d9c0	0x87c260	0x87c1d8	widget	5	exact	0	exact	()	agree	name-not-unique
+SetTextColor	0x7a0570	0x87c818	0x87c7c8	widget	1	lower-bound	?	unknown	()	unverified	name-not-unique
+SetTextFontObject	0x780400	0x879d28	0x879d00	widget	1	lower-bound	?	unknown	()	unverified	delegated-push
+SetTextHeight	0x79e3c0	0x87c298	0x87c1d8	widget	2	exact	0	exact	()	agree	
+SetTextInsets	0x798a60	0x87bc70	0x87bb68	widget	5	exact	0	exact	()	agree	
+SetTexture	0x79bb40	0x87c1a0	0x87c128	widget	5	exact	1	exact	(nil) | (number)	agree	
+SetThumbTexture	0x7902b0	0x87b268	0x87b260	widget	2	exact	0	exact	()	agree	
+SetTimeVisible	0x793b00	0x87b6d8	0x87b5c0	widget	2	exact	0	exact	()	agree	name-not-unique
+SetTimeVisible	0x795230	0x87ba00	0x87b960	widget	2	exact	0	exact	()	agree	name-not-unique
+SetToplevel	0x775440	0x878fa0	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetTrackingSpell	0x532c50	0x854220	0x854198	widget	1	exact	0	exact	()	agree	
+SetTradeMoney	0x4c0820	0x847a60	0x8479f8	global	1	exact	0	exact	()	agree	
+SetTradePlayerItem	0x5341e0	0x854278	0x854198	widget	2	exact	0	exact	()	agree	
+SetTradeSkillInvSlotFilter	0x4ffe60	0x84de68	0x84ddd0	global	3	exact	0	exact	()	agree	
+SetTradeSkillItem	0x533ac0	0x854258	0x854198	widget	3	exact	0	exact	()	agree	
+SetTradeSkillSubClassFilter	0x4ffc70	0x84de58	0x84ddd0	global	3	exact	0	exact	()	agree	
+SetTradeTargetItem	0x534410	0x854280	0x854198	widget	2	exact	0	exact	()	agree	
+SetTrainerService	0x5338b0	0x854250	0x854198	widget	2	exact	0	exact	()	agree	
+SetTrainerServiceTypeFilter	0x4da260	0x84a498	0x84a3e0	global	3	exact	0	exact	()	agree	
+SetTrainerSkillLineFilter	0x4da3f0	0x84a4a0	0x84a3e0	global	3	exact	0	exact	()	agree	
+SetUnit	0x505d70	0x84f1fc	0x84f1fc	widget	2	exact	0	exact	()	agree	name-not-unique
+SetUnit	0x5349b0	0x854290	0x854198	widget	2	exact	1	exact	(nil) | (number)	agree	name-not-unique
+SetUnitBuff	0x534ac0	0x854298	0x854198	widget	4	exact	0	exact	()	agree	
+SetUnitDebuff	0x534e30	0x8542a0	0x854198	widget	4	exact	0	exact	()	agree	
+SetUserPlaced	0x776a50	0x879058	0x878ec0	widget	2	exact	0	exact	()	agree	
+SetValue	0x78f690	0x87b038	0x87b010	widget	2	exact	0	exact	()	agree	name-not-unique
+SetValue	0x790980	0x87b298	0x87b260	widget	2	exact	0	exact	()	agree	name-not-unique
+SetValueStep	0x790b30	0x87b2a8	0x87b260	widget	2	exact	0	exact	()	agree	
+SetVertexColor	0x79abd0	0x87c150	0x87c128	widget	5	exact	0	exact	()	agree	name-not-unique
+SetVertexColor	0x79c830	0x87c1e8	0x87c1d8	widget	5	exact	0	exact	()	agree	name-not-unique
+SetVerticalScroll	0x791400	0x87b3d8	0x87b3c0	widget	2	exact	0	exact	()	agree	
+SetView	0x50b5b0	0x84f818	0x84f7a0	global	1	exact	0	exact	()	agree	
+SetWatchedFactionIndex	0x4d6b60	0x84a0c0	0x84a0a8	global	1	exact	0	exact	()	agree	
+SetWaterDetail	0x488ed0	0x83df18	0x83de68	global	1	exact	0	exact	()	agree	
+SetWhoToUI	0x5ad870	0x85d8b8	0x85d830	global	1	exact	0	exact	()	agree	
+SetWidth	0x7a1f20	0x87ca10	0x87c9b8	widget	2	exact	0	exact	()	agree	
+SetWorldDetail	0x488dd0	0x83df08	0x83de68	global	1	exact	0	exact	()	agree	
+SetZoom	0x4eec60	0x84c570	0x84c538	widget	2	exact	0	exact	()	agree	
+SetupFullscreenScale	0x48c270	0x83e2b8	0x83de68	global	1	exact	0	exact	()	agree	
+Show	0x775750	0x878fc0	0x878ec0	widget	1	exact	0	exact	()	agree	name-not-unique
+Show	0x79b770	0x87c178	0x87c128	widget	1	exact	0	exact	()	agree	name-not-unique
+Show	0x79cdb0	0x87c208	0x87c1d8	widget	1	exact	0	exact	()	agree	name-not-unique
+ShowBattlefieldList	0x4ab8c0	0x845850	0x8457e0	global	1	exact	0	exact	()	agree	
+ShowBuybackSellCursor	0x4fbbb0	0x84da80	0x84da28	global	1	lower-bound	0	exact	()	agree	
+ShowCloak	0x48de70	0x83e450	0x83de68	global	1	exact	0	exact	()	agree	
+ShowContainerSellCursor	0x4fa460	0x84d6c8	0x84d688	global	2	lower-bound	0	exact	()	agree	
+ShowContestNotice	0x46d0f0	0x837468	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+ShowCursor	0x46db60	0x837550	0x8373b8	global	0	exact	0	exact	()	agree	
+ShowEULANotice	0x46d010	0x837438	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+ShowFriendNameplates	0x489470	0x83dfd0	0x83de68	global	0	exact	0	exact	()	agree	
+ShowFriends	0x5ad340	0x85d860	0x85d830	global	0	exact	0	exact	()	agree	
+ShowHelm	0x48de20	0x83e448	0x83de68	global	1	exact	0	exact	()	agree	
+ShowInspectCursor	0x48ac60	0x83e1a8	0x83de68	global	0	exact	0	exact	()	agree	
+ShowInventorySellCursor	0x4c90b0	0x848548	0x8484d0	global	0	lower-bound	0	exact	()	agree	
+ShowMerchantSellCursor	0x4fbab0	0x84da78	0x84da28	global	1	lower-bound	0	exact	()	agree	
+ShowMiniWorldMapArrowFrame	0x4a9170	0x845128	0x845078	global	1	exact	0	exact	()	agree	
+ShowNameplates	0x489450	0x83dfc0	0x83de68	global	0	exact	0	exact	()	agree	
+ShowRepairCursor	0x4fbcc0	0x84da88	0x84da28	global	0	exact	0	exact	()	agree	
+ShowScanningNotice	0x46d080	0x837450	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+ShowTOSNotice	0x46cfa0	0x837420	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+ShowWorldMapArrowFrame	0x4a9120	0x845120	0x845078	global	1	exact	0	exact	()	agree	
+ShowingCloak	0x48ddc0	0x83e440	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+ShowingHelm	0x48dd60	0x83e438	0x83de68	global	0	exact	1	exact	(nil) | (number)	agree	
+SignPetition	0x4f46d0	0x84cec8	0x84cea0	global	1	exact	0	exact	()	agree	
+SitOrStand	0x48b920	0x83e278	0x83de68	global	0	exact	0	exact	()	agree	
+SortAuctionItems	0x4cfc00	0x849138	0x8490a8	global	2	exact	0	exact	()	agree	
+SortGuildRoster	0x4d1cb0	0x849760	0x8496d8	global	1	exact	0	exact	()	agree	
+SortRealms	0x46f330	0x837ed8	0x837ea0	global	1	exact	0	exact	()	agree	
+SortWho	0x5ad890	0x85d8c0	0x85d830	global	1	lower-bound	0	exact	()	agree	delegated-push
+SpellCanTargetUnit	0x6e6d00	0x86f958	0x86f950	global	1	exact	1	exact	(nil) | (number)	agree	
+SpellIsTargeting	0x6e6cd0	0x86f950	0x86f950	global	0	exact	1	exact	(nil) | (number)	agree	
+SpellStopCasting	0x6e6e80	0x86f970	0x86f950	global	0	exact	1	exact	(nil) | (number)	agree	
+SpellStopTargeting	0x6e6e30	0x86f968	0x86f950	global	0	exact	1	exact	(nil) | (number)	agree	
+SpellTargetUnit	0x6e6d90	0x86f960	0x86f950	global	1	exact	0	exact	()	agree	
+SplitContainerItem	0x4f9f70	0x84d6b8	0x84d688	global	3	lower-bound	0	exact	()	agree	
+StablePet	0x4cae50	0x848da8	0x848da0	global	0	exact	0	exact	()	agree	
+StartAuction	0x4ce770	0x8490d0	0x8490a8	global	3	exact	0	exact	()	agree	
+StartDuel	0x4d4c40	0x849fa8	0x849fa8	global	1	exact	0	exact	()	agree	
+StartDuelUnit	0x4d4c90	0x849fb0	0x849fa8	global	1	exact	0	exact	()	agree	
+StartMovie	0x78d770	0x87ab4c	0x87ab4c	widget	2	exact	1	exact	(nil) | (number)	agree	
+StartMoving	0x776700	0x879040	0x878ec0	widget	1	exact	0	exact	()	agree	
+StartSizing	0x776830	0x879048	0x878ec0	widget	2	exact	0	exact	()	agree	
+StatusDialogClick	0x46d270	0x837488	0x8373b8	global	0	exact	0	exact	()	agree	
+StopCinematic	0x48b970	0x83e280	0x83de68	global	0	exact	0	exact	()	agree	
+StopGlueMusic	0x46cf00	0x8373f8	0x8373b8	global	0	exact	0	exact	()	agree	
+StopMovie	0x78d870	0x87ab54	0x87ab4c	widget	1	exact	0	exact	()	agree	
+StopMovingOrSizing	0x776990	0x879050	0x878ec0	widget	1	exact	0	exact	()	agree	
+StopMusic	0x458770	0x835a68	0x835a50	global	0	exact	0	exact	()	agree	
+StrafeLeftStart	0x513fa0	0x850110	0x8500b8	global	0	exact	0	exact	()	agree	
+StrafeLeftStop	0x513fd0	0x850118	0x8500b8	global	0	exact	0	exact	()	agree	
+StrafeRightStart	0x514000	0x850120	0x8500b8	global	0	exact	0	exact	()	agree	
+StrafeRightStop	0x514030	0x850128	0x8500b8	global	0	exact	0	exact	()	agree	
+Stuck	0x489370	0x83dfa8	0x83de68	global	0	exact	0	exact	()	agree	
+SubmitNumbers	0x4c4290	0x8481c8	0x8481b8	global	4	exact	0|1	set	()	unverified	
+SurveyNotificationDone	0x46ddd0	0x837588	0x8373b8	global	1	exact	1	exact	()	unverified	
+SwapRaidSubgroup	0x4bbb00	0x847278	0x847240	global	2	exact	0	exact	()	agree	
+TOSAccepted	0x46cfd0	0x837428	0x8373b8	global	0	exact	1	exact	(nil) | (number)	agree	
+TakeInboxItem	0x4af8e0	0x845f70	0x845eb0	global	1	exact	0	exact	()	agree	
+TakeInboxMoney	0x4af7d0	0x845f68	0x845eb0	global	1	exact	0	exact	()	agree	
+TakeInboxTextItem	0x4afa60	0x845f78	0x845eb0	global	1	exact	0	exact	()	agree	
+TakeTaxiNode	0x4dcca0	0x84add0	0x84ada8	global	1	exact	0	exact	()	agree	
+TargetByName	0x489d60	0x83e078	0x83de68	global	2	exact	0	exact	()	agree	
+TargetLastEnemy	0x489b40	0x83e058	0x83de68	global	0	exact	0	exact	()	agree	
+TargetLastTarget	0x489b00	0x83e050	0x83de68	global	0	exact	0	exact	()	agree	
+TargetNearestEnemy	0x489a80	0x83e030	0x83de68	global	1	exact	0	exact	()	agree	
+TargetNearestFriend	0x489aa0	0x83e038	0x83de68	global	1	exact	0	exact	()	agree	
+TargetNearestPartyMember	0x489ac0	0x83e040	0x83de68	global	1	exact	0	exact	()	agree	
+TargetNearestRaidMember	0x489ae0	0x83e048	0x83de68	global	1	exact	0	exact	()	agree	
+TargetUnit	0x4899d0	0x83e028	0x83de68	global	1	exact	0	exact	()	agree	
+TaxiGetDestX	0x4dce30	0x84ae00	0x84ada8	global	2	exact	1	exact	(number)	agree	
+TaxiGetDestY	0x4dce80	0x84ae08	0x84ada8	global	2	exact	1	exact	(number)	agree	
+TaxiGetSrcX	0x4dcd90	0x84adf0	0x84ada8	global	2	exact	1	exact	(number)	agree	
+TaxiGetSrcY	0x4dcde0	0x84adf8	0x84ada8	global	2	exact	1	exact	(number)	agree	
+TaxiNodeCost	0x4dcc20	0x84adc8	0x84ada8	global	1	exact	1	exact	(number)	agree	
+TaxiNodeGetType	0x4dccf0	0x84ade0	0x84ada8	global	1	exact	1	exact	(string?)	agree	
+TaxiNodeName	0x4dcb30	0x84adb8	0x84ada8	global	1	exact	1	exact	(string?)	agree	
+TaxiNodePosition	0x4dcb80	0x84adc0	0x84ada8	global	1	exact	2	exact	(number,number)	agree	
+TaxiNodeSetCurrent	0x4dcd40	0x84ade8	0x84ada8	global	1	exact	1	exact	()	unverified	
+ToggleAutoRun	0x513de0	0x8500c8	0x8500b8	global	0	exact	0	exact	()	agree	
+ToggleCollision	0x489350	0x83df90	0x83de68	global	0	exact	0	exact	()	agree	
+ToggleCollisionDisplay	0x489360	0x83df98	0x83de68	global	0	exact	0	exact	()	agree	
+ToggleInputLanguage	0x799610	0x87bcd0	0x87bb68	widget	1	exact	0	exact	()	agree	
+ToggleMouseMove	0x50b5a0	0x84f810	0x84f7a0	global	0	exact	0	exact	()	agree	
+TogglePVP	0x48d700	0x83e3d0	0x83de68	global	0	exact	0	exact	()	agree	
+TogglePerformanceDisplay	0x489400	0x83dec0	0x83de68	global	0	exact	0	exact	()	agree	
+TogglePerformanceValues	0x489420	0x83dec8	0x83de68	global	0	exact	0	exact	()	agree	
+TogglePetAutocast	0x4be290	0x8475d0	0x8475a0	global	1	exact	0	exact	()	agree	
+TogglePlayerBounds	0x489440	0x83dfa0	0x83de68	global	0	exact	0	exact	()	agree	
+TogglePortals	0x489340	0x83df88	0x83de68	global	0	exact	0	exact	()	agree	
+ToggleRun	0x513d50	0x8500c0	0x8500b8	global	0	exact	0	exact	()	agree	
+ToggleSheath	0x48a070	0x83e0a0	0x83de68	global	0	exact	0	exact	()	agree	
+ToggleSpellAutocast	0x4b4240	0x846678	0x846648	global	0	lower-bound	0	exact	()	agree	
+ToggleTris	0x489330	0x83df80	0x83de68	global	0	exact	0	exact	()	agree	
+TryOn	0x504d90	0x84f1a0	0x84f190	widget	2	exact	0	exact	()	agree	
+TurnInGuildCharter	0x4f52d0	0x84d024	0x84d00c	global	0	exact	0	exact	()	agree	
+TurnLeftStart	0x513ee0	0x8500f0	0x8500b8	global	0	exact	0	exact	()	agree	
+TurnLeftStop	0x513f10	0x8500f8	0x8500b8	global	0	exact	0	exact	()	agree	
+TurnOrActionStart	0x514120	0x850150	0x8500b8	global	0	exact	0	exact	()	agree	
+TurnOrActionStop	0x514160	0x850158	0x8500b8	global	0	exact	0	exact	()	agree	
+TurnRightStart	0x513f40	0x850100	0x8500b8	global	0	exact	0	exact	()	agree	
+TurnRightStop	0x513f70	0x850108	0x8500b8	global	0	exact	0	exact	()	agree	
+TutorialsEnabled	0x4b5960	0x846b04	0x846b04	global	0	exact	1	exact	(nil) | (number)	agree	
+Undress	0x504c00	0x84f190	0x84f190	widget	1	exact	0	exact	()	agree	
+UninviteByName	0x48a610	0x83e100	0x83de68	global	1	exact	0	exact	()	agree	
+UninviteFromParty	0x48a510	0x83e0f0	0x83de68	global	1	exact	0	exact	()	agree	
+UninviteFromRaid	0x48a580	0x83e0f8	0x83de68	global	1	exact	0	exact	()	agree	
+UnitAffectingCombat	0x517e10	0x850560	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitArmor	0x5192e0	0x8505e0	0x850438	global	1	exact	5	exact	(number,number,number,number,number)	agree	
+UnitAttackBothHands	0x518810	0x8505a0	0x850438	global	1	exact	4	exact	?	unknown	
+UnitAttackPower	0x518f80	0x8505c8	0x850438	global	1	exact	3	exact	(number,number,number)	agree	
+UnitAttackSpeed	0x518e50	0x8505c0	0x850438	global	1	exact	2	exact	(number,nil) | (number,number)	agree	
+UnitBuff	0x519500	0x8505f0	0x850438	global	3	exact	1|2	set	(nil) | (nil,number) | (string?,number)	agree	delegated-push
+UnitCanAssist	0x516bb0	0x8504c8	0x850438	global	2	exact	1	exact	(nil) | (number)	agree	
+UnitCanAttack	0x516c50	0x8504d0	0x850438	global	2	exact	1	exact	(nil) | (number)	agree	
+UnitCanCooperate	0x516a70	0x8504c0	0x850438	global	2	exact	1	exact	(nil) | (number)	agree	
+UnitCharacterPoints	0x519420	0x8505e8	0x850438	global	1	exact	2	exact	?	unknown	
+UnitClass	0x518350	0x850588	0x850438	global	1	exact	2	exact	(nil,nil) | (string?,string?)	agree	
+UnitClassification	0x516d90	0x8504e8	0x850438	global	1	exact	1	exact	(string?)	agree	
+UnitCreatureFamily	0x51a310	0x850678	0x850438	global	1	exact	1	exact	(nil) | (string?)	agree	
+UnitCreatureType	0x51a280	0x850670	0x850438	global	1	exact	1	exact	(nil) | (string?)	agree	
+UnitDamage	0x518c20	0x8505a8	0x850438	global	1	exact	7	exact	(number,number,number,number,number,number,number)	agree	
+UnitDebuff	0x5198f0	0x8505f8	0x850438	global	3	exact	1|3	set	(nil) | (nil,number,nil) | (string?,number,nil) | (string?,number,string?)	agree	
+UnitDefense	0x519200	0x8505d8	0x850438	global	1	exact	2	exact	(number,number)	agree	
+UnitExists	0x515fb0	0x850438	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitFactionGroup	0x516630	0x8504a0	0x850438	global	1	exact	2	exact	(nil,nil) | (string?,string?)	agree	
+UnitHasRelicSlot	0x519e50	0x850620	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitHealth	0x5174d0	0x850510	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitHealthMax	0x5175b0	0x850518	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitInParty	0x516290	0x850468	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitInRaid	0x516350	0x850478	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsCharmed	0x516cf0	0x8504d8	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsCivilian	0x519de0	0x850618	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsConnected	0x517d50	0x850558	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsCorpse	0x5161c0	0x850458	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsDead	0x517ac0	0x850540	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsDeadOrGhost	0x517c70	0x850550	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsEnemy	0x516890	0x8504b0	0x850438	global	2	exact	1	exact	(nil) | (number)	agree	
+UnitIsFriend	0x516930	0x8504b8	0x850438	global	2	exact	1	exact	(nil) | (number)	agree	
+UnitIsGhost	0x517b90	0x850548	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsPVP	0x516460	0x850490	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsPVPFreeForAll	0x516540	0x850498	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsPartyLeader	0x516210	0x850460	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsPlayer	0x516150	0x850450	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsPlusMob	0x516d40	0x8504e0	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsTapped	0x519c90	0x850600	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsTappedByPlayer	0x519d00	0x850608	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsTrivial	0x519d70	0x850610	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitIsUnit	0x516070	0x850448	0x850438	global	2	exact	1	exact	(nil) | (number)	agree	
+UnitIsVisible	0x516030	0x850440	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitLevel	0x517fc0	0x850570	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitMana	0x517670	0x850520	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitManaMax	0x5177e0	0x850528	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitName	0x517020	0x8504f0	0x850438	global	2	lower-bound	2	exact	(nil,nil) | (string?,nil) | (string?,string?)	agree	delegated-push
+UnitOnTaxi	0x517a40	0x850538	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitPVPName	0x5172b0	0x8504f8	0x850438	global	1	exact	1	exact	() | (nil) | (string?)	unverified	
+UnitPVPRank	0x51a8a0	0x8506b0	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitPlayerControlled	0x516410	0x850488	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitPlayerOrPetInParty	0x5162f0	0x850470	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitPlayerOrPetInRaid	0x5163b0	0x850480	0x850438	global	1	exact	1	exact	(nil) | (number)	agree	
+UnitPowerType	0x517940	0x850530	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitRace	0x518200	0x850580	0x850438	global	1	exact	2	exact	(nil,nil) | (string?,string?)	agree	
+UnitRangedAttack	0x518b90	0x8505b8	0x850438	global	1	exact	2	exact	(number,number)	agree	
+UnitRangedAttackPower	0x5190c0	0x8505d0	0x850438	global	1	exact	3	exact	(number,number,number)	agree	
+UnitRangedDamage	0x518910	0x8505b0	0x850438	global	1	exact	6	exact	(number,number,number,number,number,number)	agree	
+UnitReaction	0x5167e0	0x8504a8	0x850438	global	2	exact	1	exact	(nil) | (number)	agree	
+UnitResistance	0x5184a0	0x850590	0x850438	global	2	exact	4	exact	(number,number,number,number)	agree	
+UnitSex	0x517e90	0x850568	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitStat	0x518600	0x850598	0x850438	global	2	exact	4	exact	(number,number,number,number)	agree	
+UnitXP	0x517350	0x850500	0x850438	global	1	exact	1	exact	(number)	agree	
+UnitXPMax	0x517410	0x850508	0x850438	global	1	exact	1	exact	(number)	agree	
+UnlockHighlight	0x782920	0x879e30	0x879d00	widget	1	exact	0	exact	()	agree	
+UnregisterAllEvents	0x774cf0	0x878f60	0x878ec0	widget	1	exact	0	exact	()	agree	
+UnregisterEvent	0x774b30	0x878f50	0x878ec0	widget	2	exact	0	exact	()	agree	
+UnstablePet	0x4caf20	0x848db0	0x848da0	global	1	exact	0	exact	()	agree	
+UpdateColorByID	0x7932b0	0x87b690	0x87b5c0	widget	5	exact	0	exact	()	agree	
+UpdateCustomizationBackground	0x471800	0x838170	0x8380f8	global	0	exact	0	exact	()	agree	
+UpdateCustomizationScene	0x471810	0x838178	0x8380f8	global	0	exact	0	exact	()	agree	
+UpdateGMTicket	0x48ca60	0x83e318	0x83de68	global	2	exact	0	exact	()	agree	
+UpdateInventoryAlertStatus	0x4c9560	0x848568	0x8484d0	global	0	exact	0	exact	()	agree	
+UpdateMapHighlight	0x4a7fa0	0x8450b8	0x845078	global	2	exact	8	exact	(nil,nil,number,number,number,number,number,number) | (nil,string?,number,number,number,number,number,number) | (nil,string?,number,number,number,number,number,number,number,number) | (string?,nil,number,number,number,number,number,number) | (string?,string?,number,number,number,number,number,number) | (string?,string?,number,number,number,number,number,number,number,number)	unverified	
+UpdateScrollChildRect	0x7918b0	0x87b400	0x87b3c0	widget	1	exact	0	exact	()	agree	
+UpdateSelectionCustomizationScene	0x473640	0x8385b8	0x838578	global	0	exact	0	exact	()	agree	
+UpdateSpells	0x4b43e0	0x846698	0x846648	global	0	exact	0	exact	()	agree	
+UpdateWorldMapArrowFrames	0x4a8d10	0x845108	0x845078	global	0	exact	0	exact	()	agree	
+UseAction	0x4e7140	0x84bd40	0x84bd10	global	3	exact	0	exact	()	agree	
+UseContainerItem	0x4fa0e0	0x84d6c0	0x84d688	global	3	lower-bound	0	exact	()	agree	
+UseInventoryItem	0x4c8de0	0x848518	0x8484d0	global	2	lower-bound	0	exact	()	agree	
+UseSoulstone	0x48ad70	0x83e1c0	0x83de68	global	0	exact	0	exact	()	agree	
+abs	0x7fade0	0x822c60	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+acos	0x7faed0	0x822c88	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+arshift	0x7facd0	0x822c48	0x822c18	stdlib	2	exact	1	exact	(number)	agree	
+asin	0x7faea0	0x822c80	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+assert	0x7031a0	0x811f00	0x811e28	baselib	2	exact	1	exact	?	unknown	
+atan	0x7faf00	0x822c90	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+atan2	0x7faf30	0x822c98	0x822c60	stdlib	2	exact	1	exact	(number)	agree	
+band	0x7faa90	0x822c20	0x822c18	stdlib	9	lower-bound	1	exact	(number)	agree	
+bnot	0x7faa50	0x822c18	0x822c18	stdlib	1	exact	1	exact	(number)	agree	
+bor	0x7fab10	0x822c28	0x822c18	stdlib	9	lower-bound	1	exact	(number)	agree	
+bxor	0x7fab90	0x822c30	0x822c18	stdlib	9	lower-bound	1	exact	(number)	agree	
+byte	0x7fc210	0x822db8	0x822d88	stdlib	2	exact	0|1	set	() | (number)	agree	
+ceil	0x7faf70	0x822ca0	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+char	0x7fc280	0x822da8	0x822d88	stdlib	8	lower-bound	1	exact	()	unverified	
+collectgarbage	0x703250	0x811f10	0x811e28	baselib	1	exact	0	exact	()	agree	
+concat	0x7fb830	0x822d40	0x822d40	stdlib	4	lower-bound	1	exact	?	unknown	delegated-push
+cos	0x7fae40	0x822c70	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+date	0x7033a0	0x811f30	0x811e28	baselib	2	exact	1	exact	(nil) | (string?) | (table)	agree	delegated-push
+debugbreak	0x702820	0x811e58	0x811e28	baselib	0	exact	0	exact	()	agree	
+debugdump	0x702810	0x811e50	0x811e28	baselib	0	exact	0	exact	()	agree	
+debuginfo	0x7027f0	0x811e40	0x811e28	baselib	0	exact	0	exact	()	agree	
+debugload	0x7027e0	0x811e38	0x811e28	baselib	0	exact	0	exact	()	agree	
+debugprint	0x702800	0x811e48	0x811e28	baselib	0	exact	0	exact	()	agree	
+debugprofilestart	0x702840	0x811e68	0x811e28	baselib	0	exact	0	exact	()	agree	
+debugprofilestop	0x702860	0x811e70	0x811e28	baselib	1	exact	1	exact	(number)	agree	
+debugstack	0x703760	0x811f40	0x811e28	baselib	1	exact	1	exact	?	unknown	
+debugtimestamp	0x702830	0x811e60	0x811e28	baselib	0	exact	0	exact	()	agree	
+deg	0x7fb140	0x822cf8	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+dump	0x7fc330	0x822dc8	0x822d88	stdlib	1	exact	1	exact	()	unverified	
+error	0x702970	0x811e88	0x811e28	baselib	2	exact	?	unknown	?	unknown	delegated-push
+exp	0x7fb100	0x822cf0	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+find	0x7fc3b0	0x822dd0	0x822d88	stdlib	4	exact	?	unknown	(nil) | (number,number)	unverified	delegated-push
+floor	0x7fafa0	0x822ca8	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+foreach	0x7fb590	0x822d48	0x822d40	stdlib	2	exact	0|1	set	?	unknown	
+foreachi	0x7fb4e0	0x822d50	0x822d40	stdlib	2	lower-bound	0|1	set	?	unknown	delegated-push
+format	0x7fd3d0	0x822dc0	0x822d88	stdlib	1	lower-bound	1	exact	?	unknown	
+frexp	0x7fb1a0	0x822cb8	0x822c60	stdlib	1	exact	2	exact	(number,number)	agree	
+gcinfo	0x703200	0x811f08	0x811e28	baselib	0	exact	2	exact	(number,number)	agree	
+geterrorhandler	0x702950	0x811e80	0x811e28	baselib	0	exact	1	exact	(any)	agree	
+getfenv	0x702ac0	0x811ea0	0x811e28	baselib	0	lower-bound	1	exact	?	unknown	delegated-push
+getglobal	0x7027b0	0x811e30	0x811e28	baselib	1	exact	1	exact	(any)	agree	
+getmetatable	0x7029f0	0x811e90	0x811e28	baselib	1	lower-bound	1	exact	?	unknown	delegated-push
+getn	0x7fb630	0x822d58	0x822d40	stdlib	1	lower-bound	1	exact	(number)	agree	delegated-push
+gfind	0x7fcfa0	0x822dd8	0x822d88	stdlib	2	exact	1	exact	?	unknown	
+gsub	0x7fd0e0	0x822de0	0x822d88	stdlib	4	exact	2	exact	(number)	unverified	delegated-push
+insert	0x7fb6b0	0x822d70	0x822d40	stdlib	2	lower-bound	0	exact	()	agree	delegated-push
+ipairs	0x702cd0	0x811eb8	0x811e28	baselib	2	exact	?	unknown	(any,value,number) | (number,any)	unverified	
+ldexp	0x7fb1f0	0x822cc0	0x822c60	stdlib	2	exact	1	exact	(number)	agree	
+len	0x7fbcf0	0x822d88	0x822d88	stdlib	1	exact	1	exact	(number)	agree	
+loadstring	0x703280	0x811f18	0x811e28	baselib	2	exact	1|2	set	?	unknown	
+log	0x7fb0a0	0x822ce0	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+log10	0x7fb0d0	0x822ce8	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+lower	0x7fbdf0	0x822d98	0x822d88	stdlib	1	exact	1	exact	()	unverified	
+lshift	0x7fac10	0x822c38	0x822c18	stdlib	2	exact	1	exact	(number)	agree	
+max	0x7fb2a0	0x822cd8	0x822c60	stdlib	9	lower-bound	1	exact	(number)	agree	
+min	0x7fb230	0x822cd0	0x822c60	stdlib	9	lower-bound	1	exact	(number)	agree	
+mod	0x7fad20	0x822c50	0x822c18	stdlib	2	exact	1	exact	(number)	agree	name-not-unique;delegated-push
+mod	0x7fafd0	0x822cb0	0x822c60	stdlib	2	exact	1	exact	(number)	agree	name-not-unique
+next	0x702c90	0x811eb0	0x811e28	baselib	1	exact	1|2	set	?	unknown	
+pairs	0x702da0	0x811ec0	0x811e28	baselib	1	exact	3	exact	(any,value,nil)	agree	
+pcall	0x7032f0	0x811f20	0x811e28	baselib	1	exact	?	unknown	?	unknown	variadic
+pow	0x7fb050	0x822d00	0x822c60	stdlib	2	exact	1	exact	(number)	agree	
+rad	0x7fb170	0x822d08	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+random	0x7fb310	0x822d10	0x822c60	stdlib	2	exact	1	exact	(number)	agree	
+randomseed	0x7fb450	0x822d18	0x822c60	stdlib	1	exact	0	exact	()	agree	
+rawequal	0x7030f0	0x811ee8	0x811e28	baselib	2	exact	1	exact	(boolean)	agree	
+rawget	0x703130	0x811ef0	0x811e28	baselib	2	exact	1	exact	?	unknown	
+rawset	0x703160	0x811ef8	0x811e28	baselib	3	exact	1	exact	?	unknown	
+remove	0x7fb770	0x822d78	0x822d40	stdlib	2	lower-bound	0|1	set	() | (any)	agree	delegated-push
+rep	0x7fc1a0	0x822db0	0x822d88	stdlib	2	exact	1	exact	()	unverified	
+rshift	0x7fac70	0x822c40	0x822c18	stdlib	2	exact	1	exact	(number)	agree	
+seterrorhandler	0x702900	0x811e78	0x811e28	baselib	1	lower-bound	0	exact	()	agree	delegated-push
+setfenv	0x702be0	0x811ea8	0x811e28	baselib	2	lower-bound	0	exact	?	unknown	delegated-push
+setglobal	0x702770	0x811e28	0x811e28	baselib	1	exact	0	exact	?	unknown	
+setmetatable	0x702a40	0x811e98	0x811e28	baselib	2	lower-bound	1	exact	?	unknown	delegated-push
+setn	0x7fb670	0x822d60	0x822d40	stdlib	2	lower-bound	0	exact	()	agree	delegated-push
+sin	0x7fae10	0x822c68	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+sort	0x7fb920	0x822d68	0x822d40	stdlib	2	lower-bound	0	exact	?	unknown	delegated-push
+sqrt	0x7fb020	0x822cc8	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+sub	0x7fbd30	0x822d90	0x822d88	stdlib	3	exact	1	exact	(string)	agree	
+tan	0x7fae70	0x822c78	0x822c60	stdlib	1	exact	1	exact	(number)	agree	
+time	0x7035a0	0x811f38	0x811e28	baselib	1	lower-bound	1	exact	?	unknown	delegated-push
+tonumber	0x702e30	0x811ed0	0x811e28	baselib	2	exact	1	exact	(nil) | (number)	agree	
+tostring	0x702f40	0x811ed8	0x811e28	baselib	1	lower-bound	1	exact	() | (string) | (string?) | (value)	unverified	delegated-push
+type	0x702df0	0x811ec8	0x811e28	baselib	1	exact	1	exact	(string?)	agree	
+unpack	0x7030a0	0x811ee0	0x811e28	baselib	1	lower-bound	?	unknown	?	unknown	delegated-push
+upper	0x7fc0c0	0x822da0	0x822d88	stdlib	1	exact	1	exact	()	unverified	
+xpcall	0x703340	0x811f28	0x811e28	baselib	2	exact	?	unknown	?	unknown	
diff --git a/reference/1.12-verb-events.tsv b/reference/1.12-verb-events.tsv
new file mode 100644
index 00000000..fece0a22
--- /dev/null
+++ b/reference/1.12-verb-events.tsv
@@ -0,0 +1,56 @@
+# The 1.12.1 client's FrameScript events fired from inside a Lua verb, keyed by the verb.
+# Generated by scripts/gen-reference-verb-events.py from reference/1.12-shapes.tsv,
+# reference/1.12-event-firesites.tsv and the maintainer's analysis.
+#
+# shape  body   = a fire site inside the verb's own extent.
+#        helper = a fire site inside a function that only registered verbs call
+#                 (at most 8 of them); `via` is that helper. A helper with any
+#                 non-verb caller produces a state event and is not here.
+# sites  the fire sites themselves.
+# A floor, not a census: a verb with no row may still fire an event.
+# A site past its candidate function's extent is left out rather than mis-filed.
+# 43 pairs over 41 verbs and 27 events; 2 site(s) past a verified extent.
+verb	event	shape	via	sites
+AddSkillUp	SKILL_LINES_CHANGED	helper	0x4d32d0	0x4d346f
+CancelSkillUps	SKILL_LINES_CHANGED	body	-	0x4d3e3a
+ChangeActionBarPage	ACTIONBAR_PAGE_CHANGED	body	-	0x4e7655
+ChangeChatColor	UPDATE_CHAT_COLOR	body	-	0x4a098b
+CheckInbox	MAIL_INBOX_UPDATE	body	-	0x4aeaf8
+ClickAuctionSellItemButton	NEW_AUCTION_UPDATE	body	-	0x4ce576
+ClickSendMailItemButton	MAIL_SEND_INFO_UPDATE	body	-	0x4ae0de
+ClickTargetTradeButton	TRADE_REPLACE_ENCHANT	helper	0x496170	0x496230
+CloseCraft	CRAFT_CLOSE	helper	0x4f5fe0	0x4f5fef
+CloseTrade	PLAYER_TRADE_MONEY	body	-	0x4bfdce
+CloseTradeSkill	TRADE_SKILL_CLOSE	helper	0x4fc870	0x4fc884
+CollapseCraftSkillLine	CRAFT_UPDATE	helper	0x4f6be0	0x4f6bf0
+CollapseQuestHeader	QUEST_LOG_UPDATE	helper	0x4ded30	0x4ded98|0x4dedba|0x4dedd6
+CollapseTradeSkillSubClass	TRADE_SKILL_UPDATE	helper	0x4fd750	0x4fd765
+CollapseTrainerSkillLine	TRAINER_UPDATE	helper	0x4d8cd0	0x4d8ce0
+ConfirmLootRoll	CANCEL_LOOT_ROLL	helper	0x61bdf0	0x61bf2a
+ConfirmLootRoll	CONFIRM_LOOT_ROLL	helper	0x61bdf0	0x61be8b
+DoTradeSkill	UPDATE_TRADESKILL_RECAST	helper	0x4fd770	0x4fd781
+DropCursorMoney	PLAYER_MONEY	helper	0x494cc0	0x494d10
+ExpandCraftSkillLine	CRAFT_UPDATE	helper	0x4f6be0	0x4f6bf0
+ExpandQuestHeader	QUEST_LOG_UPDATE	helper	0x4ded30	0x4ded98|0x4dedba|0x4dedd6
+ExpandTradeSkillSubClass	TRADE_SKILL_UPDATE	helper	0x4fd750	0x4fd765
+ExpandTrainerSkillLine	TRAINER_UPDATE	helper	0x4d8cd0	0x4d8ce0
+PetDismiss	PET_DISMISS_START	helper	0x4bd6e0	0x4bd722
+PickupPlayerMoney	PLAYER_MONEY	helper	0x494cc0	0x494d10
+PickupTradeMoney	PLAYER_MONEY	helper	0x494cc0	0x494d10
+RemoveSkillUp	SKILL_LINES_CHANGED	helper	0x4d3480	0x4d3598
+RollOnLoot	CANCEL_LOOT_ROLL	helper	0x61bdf0	0x61bf2a
+RollOnLoot	CONFIRM_LOOT_ROLL	helper	0x61bdf0	0x61be8b
+SelectGossipOption	GOSSIP_ENTER_CODE	helper	0x4e2320	0x4e237e
+SendMail	MAIL_SEND_INFO_UPDATE	body	-	0x4ae98d
+SetBinding	UPDATE_BINDINGS	body	-	0x4b805b
+SetCVar	CVAR_UPDATE	body	-	0x488cd5
+SetGuildRecruitmentMode	UPDATE_CHAT_WINDOWS	body	-	0x4a00a9
+SetSendMailCOD	SEND_MAIL_COD_CHANGED	helper	0x4adc70	0x4adc88
+SetSendMailMoney	SEND_MAIL_MONEY_CHANGED	helper	0x4adbe0	0x4adc44
+SetTradeSkillInvSlotFilter	TRADE_SKILL_UPDATE	helper	0x4fd730	0x4fd745
+SetTradeSkillSubClassFilter	TRADE_SKILL_UPDATE	helper	0x4fd710	0x4fd725
+SetTrainerServiceTypeFilter	TRAINER_UPDATE	helper	0x4d8c90	0x4d8ca0
+SetTrainerSkillLineFilter	TRAINER_UPDATE	helper	0x4d8cb0	0x4d8cc0
+SortWho	WHO_LIST_UPDATE	body	-	0x5ad9f2
+TogglePetAutocast	PET_BAR_UPDATE	helper	0x4bcbb0	0x4bcc81
+ToggleSpellAutocast	PET_BAR_UPDATE	helper	0x4bccb0	0x4bcdcb
diff --git a/reference/README.md b/reference/README.md
new file mode 100644
index 00000000..2f5644cd
--- /dev/null
+++ b/reference/README.md
@@ -0,0 +1,79 @@
+# `reference/`: verified facts about the 1.12.1 client, vendored
+
+Generated tables describing the reference client, committed so benilla can measure itself against
+them on any machine without re-deriving them. Data, not documentation: each has a generator beside
+it in `scripts/`.
+
+Nothing here is Blizzard content. A catalogue of names is not the thing named, the same way a
+comment may quote a byte address and `docs/MAP.md` may name a file.
+
+## `1.12-globals.tsv`
+
+The 1.12.1 client's entire global namespace: 21,555 names, `name<TAB>type<TAB>origin`.
+
+Where it comes from: a dump of `_G` inside the running reference client, which is the surface an
+addon sees (FrameXML-defined globals as well as engine ones), unioned with every global the shipped
+UI defines. The union matters because the twelve `Blizzard_*` addons are LoadOnDemand: a live dump
+only carries their globals if their windows were opened first, so the 1,986 rows a dump cannot see
+carry type `lod`. The table answers "is this a 1.12 name?", not "was this name live in one session".
+
+The `origin` column says whose job it is to provide the name, attributed by its definition site in
+the complete 1.12 shipped-UI corpus:
+
+| origin | count | meaning |
+|---|---|---|
+| `engine` | 1,104 | the C client provides it; benilla implements these in Rust |
+| `framexml` | 20,427 | the shipped UI defines it; the stock files run off the player's own install (`ui_script::reference_ui`) |
+| `lua` | 24 | Lua 5.0's own runtime |
+
+The `framexml` bulk is UI objects, `ContainerFrame1Item16IconTexture` and its 11,000 siblings,
+which materialize from the XML and are nobody's to implement. The number that matters for the API
+surface is the function split: 1,100 engine functions, 1,075 FrameXML functions. A name defined in
+shipped Lua is FrameXML's, and hardcoding it in Rust is a category error even when it works.
+
+Regenerating: `scripts/gen-reference-globals.py`, whose header carries the method and the traps. It
+needs a 1.12 install, its FrameXML extracted to a folder, and the maintainer's runtime capture of
+the reference client's `_G`, which is not in this repo, so it is a manual regeneration. The table is
+stable: it describes a client that shipped in 2006.
+
+Reading it: `scripts/api-coverage.sh` asks a real `UiScript::new()` what benilla exposes and reports
+`have / missing / beyond-1.12`. `crates/benilla-ui/src/script/tests/reference_surface.rs` is the
+gate: it fails if benilla grows a global that 1.12 does not have and nobody wrote down why.
+
+## `1.12-shapes.tsv` and `1.12-events.tsv`
+
+The binding-shape table (what each Lua verb takes and returns, gated by `ui_script/shape_gate.rs`)
+and the event table with the arguments each producer pushes (gated by
+`ui_script/event_shape_gate.rs`). Each file's header carries its column contract.
+
+Regenerating: `1.12-shapes.tsv` is vendored as the reference analysis writes it.
+`scripts/gen-reference-events.py` derives `1.12-events.tsv` from two more vendored tables,
+`1.12-event-catalog.tsv` (event id to name, off the client's name-pointer array) and
+`1.12-event-firesites.tsv` (every fire site with the format string it pushes), so it runs from any
+clone and reproduces the committed file byte for byte.
+
+## `1.12-message-catalog.tsv`
+
+The client's message registry (`0xb4b498`: id, key, kind, sound, chat type).
+`scripts/gen-message-catalog.py` re-shapes it into `crates/benilla-ui/src/messages/catalog.rs`,
+the table `CGGameUI::DisplayError` indexes.
+
+## `1.12-verb-events.tsv`
+
+Every event the reference fires from inside a Lua verb, keyed by the verb: the verb's own body, or
+a helper that only registered verbs call (`0x4d8c90` is the trainer's). The two tables above say
+what an event carries and whether something fires it; this one says who. A stock file that calls a
+verb for its side effect of an event repaints nothing when the verb fires nothing.
+
+Regenerating: `scripts/gen-reference-verb-events.py`, whose header carries the rule, the two
+families it drops (glue-space verbs, the unit-field bridge) and why getters are excluded (a getter's
+fire is a cache-miss re-query, a state event benilla's feeds fire off the packet). A fire site is
+attributed to a function by the verified function extents plus the disassembly's padding
+boundaries, and a site past its candidate's extent is left out rather than mis-filed. The fire
+sites and the shapes are the vendored tables above; the function names, their extents and the
+disassembly are the maintainer's, so this one is a manual regeneration.
+
+Reading it: `crates/benilla-app/src/ui_script/verb_event_gate.rs` is the gate. For every pair whose
+verb benilla registers, the module that registers the verb fires the event, or the pair is declared
+there: `ELSEWHERE` (a feed fires it on the state the verb changes, and the named file is checked
+too) or `GAP` (nothing does, with the reason).
diff --git a/scripts/api-coverage.sh b/scripts/api-coverage.sh
new file mode 100755
index 00000000..a864bbb6
--- /dev/null
+++ b/scripts/api-coverage.sh
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# Addon-API coverage: how much of the 1.12.1 client's global surface benilla's UI VM presents.
+#
+#   scripts/api-coverage.sh              # the report
+#   scripts/api-coverage.sh --missing    # + every engine global we do not have
+#   scripts/api-coverage.sh --beyond     # + every global we have that 1.12 does not
+#
+# The 1.12 side is `reference/1.12-globals.tsv`, the reference client's in-world `_G`
+# (scripts/gen-reference-globals.py); ours is a real `UiScript::new()` dumped through `pairs(_G)`.
+# Never quote the percentage alone: a missing global is an unbuilt feature or a hole in a shipped
+# one, and a global beyond 1.12 sends a feature-detecting addon down a path we cannot honour.
+set -u
+cd "$(dirname "$0")/.."
+
+REF="reference/1.12-globals.tsv"
+[ -f "$REF" ] || { echo "no $REF — run scripts/gen-reference-globals.py" >&2; exit 1; }
+
+show_missing=0
+show_beyond=0
+for a in "$@"; do
+  case "$a" in
+    --missing) show_missing=1 ;;
+    --beyond)  show_beyond=1 ;;
+    *) echo "usage: $0 [--missing] [--beyond]" >&2; exit 2 ;;
+  esac
+done
+
+ours=$(mktemp) || exit 1
+trap 'rm -f "$ours"' EXIT
+echo "asking benilla's VM what it exposes..." >&2
+if ! cargo run -q -p benilla-ui --example dump_globals >"$ours" 2>/dev/null; then
+  echo "dump_globals failed — build the workspace first" >&2
+  exit 1
+fi
+
+awk -F'\t' -v ref="$REF" -v show_missing="$show_missing" -v show_beyond="$show_beyond" '
+  # ── the reference side ──────────────────────────────────────────────────────────────────────
+  FNR == NR {
+    if ($0 ~ /^#/) next
+    origin[$1] = $3
+    n_ref[$3]++
+    if ($2 == "function") n_ref_fn[$3]++
+    next
+  }
+  # ── our side ───────────────────────────────────────────────────────────────────────────────
+  {
+    ours[$1] = $2
+    n_ours++
+    o = ($1 in origin) ? origin[$1] : "beyond"
+    if (o == "engine" || o == "lua") have++
+    else if (o == "framexml") transcribable[$1] = 1
+    else {
+      # Categorize the superset. Only the last bucket is an API-target question; the first two are
+      # benilla being benilla, and the third is our Lua runtime being 5.1 where 1.12 is 5.0.
+      if ($1 ~ /^Benilla/)                                    bridge[$1] = 1
+      else if ($1 ~ /^__/)                                    internal[$1] = 1
+      else if ($1 ~ /^(_G|_VERSION|coroutine|print|select)$/)  lua51[$1] = 1
+      else                                                     api[$1] = 1
+    }
+  }
+  END {
+    surface = n_ref["engine"] + n_ref["lua"]
+    missing = surface - have
+    pct = surface ? sprintf("%.0f%%", 100 * have / surface) : "-"
+    printf "\nthe 1.12.1 surface — %s (%d names: the running client'\''s _G, plus what the\n                       shipped UI defines behind a LoadOnDemand window)\n", ref, \
+      n_ref["engine"] + n_ref["framexml"] + n_ref["lua"]
+    printf "  engine    %5d functions, %5d other   <- benilla implements these in Rust\n", \
+      n_ref_fn["engine"], n_ref["engine"] - n_ref_fn["engine"]
+    printf "  framexml  %5d functions, %5d other   <- benilla transcribes these into assets/ui\n", \
+      n_ref_fn["framexml"], n_ref["framexml"] - n_ref_fn["framexml"]
+    printf "  lua       %5d functions, %5d other   <- mlua provides these\n", \
+      n_ref_fn["lua"], n_ref["lua"] - n_ref_fn["lua"]
+
+    printf "\nbenilla'\''s VM — %d globals (UiScript::new(), asked at runtime)\n\n", n_ours
+    printf "1.12 globals: %d   we have: %d (%s)   missing: %d   beyond-1.12: %d (listed)\n", \
+      surface, have, pct, missing, length(api)
+    print  "  ^ never quote this without the split: unbuilt-feature vs missing-verb vs superset."
+
+    printf "\nbeyond 1.12, by kind — every one of these is a deliberate exception or a bug:\n"
+    printf "  %3d  benilla host bridge      Benilla*, called only by our own FrameXML\n", length(bridge)
+    printf "  %3d  VM internals             __benilla_*, pushed by the tick\n", length(internal)
+    printf "  %3d  Lua 5.1 past 1.12'\''s 5.0  ", length(lua51); dump(lua51, "")
+    printf "  %3d  WoW API past 1.12        the phase-5 list\n", length(api)
+    printf "  %3d  ours in Rust that 1.12 defines in FrameXML\n", length(transcribable)
+    dump(transcribable, "       ")
+
+    if (show_beyond || length(api) <= 30) {
+      printf "\nWoW API beyond 1.12 (%d):\n", length(api)
+      dump(api, "  ")
+    }
+    if (show_missing) {
+      printf "\nmissing engine globals (%d):\n", missing
+      for (k in origin)
+        if ((origin[k] == "engine" || origin[k] == "lua") && !(k in ours)) miss[k] = 1
+      dump(miss, "  ")
+    }
+    print ""
+  }
+  # Print a set as wrapped, sorted, space-separated names.
+  function dump(set, indent,   k, sorted, i, n, line) {
+    n = 0
+    for (k in set) sorted[++n] = k
+    asort_names(sorted, n)
+    line = indent
+    for (i = 1; i <= n; i++) {
+      if (length(line) + length(sorted[i]) + 1 > 96) { print line; line = indent }
+      line = line sorted[i] " "
+    }
+    if (line != indent) print line
+  }
+  # Insertion sort — `asort` is a gawk extension and macOS ships BSD awk.
+  function asort_names(a, n,   i, j, t) {
+    for (i = 2; i <= n; i++) {
+      t = a[i]
+      for (j = i - 1; j >= 1 && a[j] > t; j--) a[j + 1] = a[j]
+      a[j + 1] = t
+    }
+  }
+' "$REF" "$ours"
diff --git a/scripts/check.sh b/scripts/check.sh
new file mode 100755
index 00000000..784f08cd
--- /dev/null
+++ b/scripts/check.sh
@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# The in-loop verify: fmt everywhere, clippy and test on the changed crates and their dependents.
+#
+# The change set is the fork point against main plus staged, unstaged and untracked files. A path
+# under crates/<dir>/ scopes that package, docs/ and *.md scope nothing, and any other path runs
+# scripts/gates.sh, the workspace-wide chain run at land.
+# CHECK_FULL=1 goes straight to gates.sh.
+#
+#   scripts/check.sh
+set -uo pipefail
+
+# Check the checkout you stand in when it is one of this repo, else this file's (as gates.sh does).
+here="$(cd "$(dirname "$0")/.." && pwd)"
+root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$root" ] && [ -f "$root/scripts/check.sh" ] || root="$here"
+cd "$root" || exit 1
+
+if [ "${CHECK_FULL:-}" = "1" ]; then
+    exec "$root/scripts/gates.sh"
+fi
+
+# ── The round's change set ───────────────────────────────────────────────────────────────────────
+base="$(git merge-base HEAD main 2>/dev/null || git rev-parse HEAD)"
+changed="$( { git diff --name-only "$base" HEAD 2>/dev/null
+              git diff --name-only HEAD 2>/dev/null
+              git ls-files --others --exclude-standard 2>/dev/null; } | sort -u )"
+
+if [ -z "$changed" ]; then
+    echo "check: no changes against main and a clean tree — nothing to verify"
+    exit 0
+fi
+
+# ── Map files → crate dirs; anything unmappable escalates to the full chain ──────────────────────
+dirs=""
+full_reason=""
+while IFS= read -r f; do
+    case "$f" in
+    docs/* | *.md) ;;                                 # provably gate-inert (gates.sh's docs-only rule)
+    crates/*/*) d="${f#crates/}"; dirs="$dirs DIR:crates/${d%%/*}" ;;
+    *) full_reason="$f" ;;
+    esac
+done <<EOF
+$changed
+EOF
+
+if [ -n "$full_reason" ]; then
+    echo "check: '$full_reason' is outside the crate map — the whole workspace could be affected."
+    echo "check: escalating to the full chain: scripts/gates.sh"
+    exec "$root/scripts/gates.sh"
+fi
+
+dirlist="$(printf '%s\n' $dirs | sed 's/.*DIR://' | sort -u)"
+if [ -z "$dirlist" ]; then
+    echo "check: docs-only round ($(printf '%s\n' "$changed" | wc -l | tr -d ' ') file(s)) — no gate can change; fmt only"
+    cargo fmt --all -- --check || exit 1
+    echo "check: green (docs only)"
+    exit 0
+fi
+
+# ── Changed crates → reverse-dependency closure, off cargo metadata ──────────────────────────────
+pkgs="$(python3 - "$root" $dirlist <<'PY'
+import json, subprocess, sys, os
+root, dirs = sys.argv[1], set(sys.argv[2:])
+meta = json.loads(subprocess.run(
+    ["cargo", "metadata", "--format-version", "1", "--no-deps"],
+    capture_output=True, text=True, cwd=root, check=True).stdout)
+by_dir, deps = {}, {}
+names = {p["name"] for p in meta["packages"]}
+for p in meta["packages"]:
+    by_dir[os.path.relpath(os.path.dirname(p["manifest_path"]), root)] = p["name"]
+    deps[p["name"]] = {d["name"] for d in p["dependencies"] if d["name"] in names}
+changed = {by_dir[d] for d in dirs if d in by_dir}
+missing = [d for d in dirs if d not in by_dir]
+if missing:  # a changed dir cargo doesn't know: not our map's to scope
+    print("FULL " + " ".join(missing)); sys.exit(0)
+scope = set(changed)
+grew = True
+while grew:
+    grew = False
+    for name, ds in deps.items():
+        if name not in scope and ds & scope:
+            scope.add(name); grew = True
+print(" ".join(sorted(scope)))
+PY
+)" || { echo "check: cargo metadata failed — falling back to the full chain"; exec "$root/scripts/gates.sh"; }
+
+case "$pkgs" in FULL*)
+    echo "check: changed path(s) not in the workspace map (${pkgs#FULL }) — full chain"
+    exec "$root/scripts/gates.sh" ;;
+esac
+
+pflags=""
+for p in $pkgs; do pflags="$pflags -p $p"; done
+echo "check: scope = $pkgs"
+echo "check:   (changed crates + everything that depends on them; full chain still runs at sync→land)"
+
+log="$(mktemp "${TMPDIR:-/tmp}/benilla-check.XXXXXX")"
+skips="$(mktemp "${TMPDIR:-/tmp}/benilla-check-skips.XXXXXX")"
+trap 'rm -f "$log" "$skips"' EXIT
+# Each gate logs to a file tailed afterwards: piping through `tail` would mask its exit code.
+run() {
+    local name="$1"; shift
+    if ! "$@" >"$log" 2>&1; then
+        echo "CHECK FAILED: $name"
+        tail -30 "$log"
+        exit 1
+    fi
+    echo "check ok: $name"
+}
+
+run fmt cargo fmt --all -- --check
+run clippy cargo clippy $pflags --all-targets -- -D warnings
+run test env BENILLA_SKIP_LOG="$skips" cargo test $pflags
+# Data-gated tests skip without the install or the addon corpus and libtest swallows their line,
+# so each skip is also logged to $BENILLA_SKIP_LOG and counted here.
+if [ -s "$skips" ]; then
+    echo "  test: $(wc -l <"$skips" | tr -d ' ') data-gated tests SKIPPED on this machine —"
+    sort "$skips" | uniq -c | sort -rn | sed 's/^ *\([0-9]*\) \(.*\)/    \1 × \2/'
+    echo "    (they run where the data is: docs/CONTRIBUTING.md, \"Setting up\")"
+fi
+
+echo "CHECK GREEN (scoped: $pkgs)"
+echo "  (land still pays the full chain once: scripts/gates.sh — memoized, so an already-gated tree is free)"
diff --git a/scripts/cine.sh b/scripts/cine.sh
new file mode 100755
index 00000000..24f0e12f
--- /dev/null
+++ b/scripts/cine.sh
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Play one cinematic on the probe and print what happened, as a timeline.
+#
+#   scripts/cine.sh                 # the human intro (81), parked in Stormwind
+#   scripts/cine.sh 41              # the dwarf intro
+#   scripts/cine.sh 81 --key W      # …and hold W mid-shot: does the body move?
+#   scripts/cine.sh 81 --at "-8913,554,94,0"
+#   scripts/cine.sh 81 --keep       # keep the raw log and trace paths, printed at the end
+#
+# Logs in as `.probe-identity`, else WOW_USER/WOW_PASS/WOW_CHAR. The body parks on flat ground
+# first, and did-it-fall/did-it-move print beside the timeline: a wedged or falling body sends no
+# movement. Sound is live but muted through a BENILLA_HOME config (`MasterVolume = "0"`), because
+# under WOW_NOSOUND `zone::start_music_stream` returns before it logs.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+id=81
+park="-8913,554,94,0"   # Stormwind Trade District: flat, solid, and a zone with music
+key=""
+keep=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --at)   park="$2"; shift 2 ;;
+        --key)  key="$2"; shift 2 ;;
+        --keep) keep=1; shift ;;
+        -*)     echo "cine.sh: unknown flag $1" >&2; exit 2 ;;
+        *)      id="$1"; shift ;;
+    esac
+done
+
+. "$PWD/scripts/probe-identity.sh"
+probe_identity cine.sh "$PWD" || exit 2
+char="$PROBE_CHAR"
+
+work="$(mktemp -d)"
+cfg="$work/cfg"
+mkdir -p "$cfg"
+printf '[cvars]\nMasterVolume = "0"\n' > "$cfg/config.toml"
+log="$work/run.log"
+trace="$work/move.trace"
+
+IFS=, read -r px py pz pmap <<< "$park"
+
+# The schedule, in probe-clock seconds; generous, because a cold start streams a city slowly.
+park_at=8
+play_at=20
+key_at=$((play_at + 8))
+# Shots run 25-102 s; leave room for the end, the resume and the cover to settle.
+exit_at=$((play_at + 120))
+
+echo "cine.sh: cinematic $id as $char, parked at $px $py $pz (map $pmap)"
+[ -n "$key" ] && echo "cine.sh: holding $key for 3 s at t=${key_at}s"
+echo "cine.sh: this takes about $((exit_at + 20)) s — the shot is played in full so the END is measured too"
+
+env BENILLA_HOME="$cfg" WOW_UNATTENDED=1 \
+    WOW_USER="$PROBE_USER" WOW_PASS="$PROBE_PASS" WOW_CHAR="$char" \
+    WOW_PROBE_CHAT=".go xyz $px $py $pz $pmap;.debug play cinematic $id" \
+    WOW_PROBE_CHAT_AT="$park_at" WOW_PROBE_CHAT_EVERY="$((play_at - park_at))" \
+    ${key:+WOW_PROBE_KEY="$key@$key_at:3"} \
+    WOW_MOVE_TRACE="$trace" WOW_MOVE_TRACE_TAGS="move,snd" \
+    WOW_PROBE_EXIT_AT="$exit_at" \
+    cargo run -q -p benilla > "$log" 2>&1 || true
+
+strip() { sed -E 's/\x1b\[[0-9;]*m//g'; }
+
+echo
+echo "── timeline ────────────────────────────────────────────────────────────────"
+strip < "$log" | grep -E \
+    "cinematic:|screen fade:|cinematic voice:|zone music:|ambience:|loading screen:|body held|probe-key:" \
+    | sed -E 's/^[0-9-]+T([0-9:.]+)Z +INFO +[a-z_:]+: /\1  /' || true
+
+echo
+echo "── the two control facts ───────────────────────────────────────────────────"
+if [ -s "$trace" ]; then
+    # Everything before the park is the login/teleport arc and says nothing about the cinematic.
+    after=$(awk -v t="$park_at" '$1=="t=" || $2+0 >= t' "$trace" 2>/dev/null || cat "$trace")
+    low=$(printf '%s\n' "$after" | grep -oE 'pos=\[[-0-9.]+,[-0-9.]+,[-0-9.]+\]' \
+          | sed -E 's/.*,//; s/\]//' | sort -n | head -1)
+    echo "did it FALL?  lowest z after the park: ${low:-<none>}   (park z was $pz)"
+    verbs=$(printf '%s\n' "$after" | grep -oE 'snd  [A-Za-z_]+' | sort | uniq -c | tr '\n' ' ')
+    echo "did it MOVE?  wire verbs sent: ${verbs:-<none>}"
+    echo "              (a StartForward means the body walked; only Heartbeats means it did not)"
+else
+    echo "no move trace written — the run did not reach the world"
+fi
+
+echo
+if [ "$keep" = 1 ]; then
+    echo "log:   $log"
+    echo "trace: $trace"
+else
+    rm -rf "$work"
+fi
diff --git a/scripts/doc-links.py b/scripts/doc-links.py
new file mode 100755
index 00000000..705a3609
--- /dev/null
+++ b/scripts/doc-links.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Fail on a doc link whose target is declared nowhere in the workspace.
+
+It reads rustdoc's unresolved-link warnings and fails on a `crate::`, `super::`, `self::` or
+`Self::` path whose leaf name is declared nowhere: the item is gone. Every other warning is a
+convention here, not rot (a private module named through its parent, another crate's module
+named with `crate::`, a bare name for an unimported bevy type).
+
+    scripts/doc-links.py            # the gate: exit 1 on any dead-target link
+    scripts/doc-links.py --report   # + the benign counts
+
+The leaf test is a loose declaration grep: a name declared anywhere counts, since what it catches
+is a deleted item, not a misspelled path.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def run_rustdoc() -> str:
+    out = subprocess.run(
+        ["cargo", "doc", "--workspace", "--no-deps", "--document-private-items"],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+    )
+    return out.stderr + out.stdout
+
+
+def declared_names() -> set[str]:
+    """Every name the workspace declares, in one scan: a grep per link is too slow for a gate."""
+    names: set[str] = set()
+    # `fn` gets its own pattern: in one alternation, `const fn foo` captures "fn" and never
+    # indexes `foo`.
+    pats = [
+        re.compile(r"\bfn\s+([A-Za-z_][A-Za-z0-9_]*)"),
+        re.compile(r"\b(?:struct|enum|trait|type|const|static|union|mod)\s+([A-Za-z_][A-Za-z0-9_]*)"),
+        re.compile(r"\bmacro_rules!\s+([A-Za-z_][A-Za-z0-9_]*)"),
+    ]
+    for rs in (ROOT / "crates").rglob("*.rs"):
+        try:
+            text = rs.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for pat in pats:
+            names.update(pat.findall(text))
+    names.discard("fn")
+    return names
+
+
+def main() -> int:
+    report = "--report" in sys.argv
+    text = run_rustdoc()
+    found = re.findall(r"warning: unresolved link to `([^`]+)`\n\s*--> ([^\s:]+):(\d+)", text)
+
+    names = declared_names()
+    dead, benign = [], 0
+    for target, path, line in found:
+        # Only a `crate::`/`super::`/`self::`/`Self::` path asserts a local item; a bare name may
+        # be a bevy type not imported for linking (`SystemParam`), which is not rot.
+        if not re.match(r"^(crate|super|self|Self)::", target):
+            benign += 1
+            continue
+        leaf = target.split("::")[-1].split("(")[0].strip()
+        if not leaf or not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", leaf):
+            benign += 1
+            continue
+        if leaf in names:
+            benign += 1
+        else:
+            dead.append((target, path, line))
+
+    if report:
+        print(f"doc-links: {len(found)} unresolved-link warnings")
+        print(f"doc-links: {benign} name something that still exists (see this file's header)")
+
+    if not dead:
+        print(f"doc-links ok: no doc link points at a deleted item ({len(found)} benign)")
+        return 0
+
+    print(f"doc-links FAILED: {len(dead)} doc link(s) point at something that no longer exists:\n")
+    for target, path, line in dead:
+        print(f"  {path}:{line}\n      [`{target}`]")
+    print(
+        "\nEach names an item declared nowhere in the workspace. Repoint it at whatever replaced\n"
+        "the thing, or drop the brackets — a dangling link promises navigation that is not there."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/gates.sh b/scripts/gates.sh
new file mode 100755
index 00000000..344a7b74
--- /dev/null
+++ b/scripts/gates.sh
@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# The land gate chain: every gate in order, stopping at the first failure.
+#
+# fmt, clippy, test, test-no-install, doc-links, pass-span-lint, player-build, player-tests,
+# enforcer, enforcer-no-install. A failure prints the gate's log tail and exits nonzero; a green
+# run stamps the tree, which then re-greens without running. GATES_FORCE=1 runs the chain anyway,
+# WOW_DATA picks the install (set and empty: none) and TMPDIR holds the scratch files; the script
+# sets BENILLA_REQUIRE_DATA, BENILLA_SKIP_LOG and WOW_WORLDVIEW_CHECK for its gates.
+#
+#   scripts/gates.sh
+set -uo pipefail
+
+# Gate the checkout $PWD is in, not this file's: a caller in one worktree may run another's copy
+# by absolute path. Outside a checkout of this repo, gate this file's own checkout.
+here="$(cd "$(dirname "$0")/.." && pwd)"
+root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$root" ] && [ -f "$root/scripts/gates.sh" ] || root="$here"
+cd "$root" || exit 1
+echo "gating: $root"
+
+# ── Green-stamp memoization ──────────────────────────────────────────────────────────────────────
+# A green run stamps target/.gates-green with the working tree's hash (untracked files included,
+# through a throwaway index that leaves the real one alone), rustc's version, this script's hash,
+# the install path and whether the addon corpus link is there: the data-gated tests and the
+# enforcer run only where the data resolves, and the link is gitignored, so the hash misses it.
+# The install is compared last: resolving it is a `cargo run`.
+stamp="target/.gates-green"
+corpus=""
+[ -d "$root/wow-addons-vanilla" ] && corpus="+corpus"
+tree_key() {
+    local tmpidx t
+    tmpidx="$(mktemp "${TMPDIR:-/tmp}/benilla-gates-idx.XXXXXX")" && rm -f "$tmpidx" || return 1
+    t="$( (export GIT_INDEX_FILE="$tmpidx"
+           git read-tree HEAD && git add -A . && git write-tree) 2>/dev/null )"
+    rm -f "$tmpidx"
+    [ -n "$t" ] || return 1
+    printf '%s|%s|%s' "$t" "$(rustc -V 2>/dev/null)" \
+        "$(shasum "$root/scripts/gates.sh" 2>/dev/null | cut -d' ' -f1)"
+}
+resolve_wow() { cargo run -q -p benilla-formats --example where 2>/dev/null || true; }
+# A delta only under docs/ or in top-level *.md files keeps the stamped verdict, since no gate
+# reads those paths; a gate that starts to read one must narrow this pattern.
+docs_only_delta() { # $1 = stamped tree, $2 = current tree
+    git cat-file -e "$1^{tree}" 2>/dev/null && git cat-file -e "$2^{tree}" 2>/dev/null || return 1
+    [ -z "$(git diff-tree -r --name-only "$1" "$2" 2>/dev/null | grep -vE '^(docs/|[^/]*\.md$)' || true)" ]
+}
+key_start="$(tree_key || true)"
+if [ "${GATES_FORCE:-}" != "1" ] && [ -n "$key_start" ] && [ -f "$stamp" ]; then
+    old="$(cat "$stamp" 2>/dev/null)"
+    old_key="${old%|*}" # tree|rustc|script — the part that must match (bar the tree, see below)
+    memo=""
+    if [ "$old_key" = "$key_start" ]; then
+        memo="this exact tree already passed"
+    elif [ "${old_key#*|}" = "${key_start#*|}" ] && docs_only_delta "${old_key%%|*}" "${key_start%%|*}"; then
+        memo="this tree differs from one that passed only under docs/ or in top-level *.md, which no gate reads"
+    fi
+    if [ -n "$memo" ] && [ "${old##*|}" = "$(resolve_wow)$corpus" ]; then
+        echo "ALL GATES GREEN (memoized — $memo; GATES_FORCE=1 re-runs)"
+        [ -d target ] && printf '%s\t%s\t%s\t%s\t%s\n' "$(date -u +%FT%TZ)" \
+            "$(git rev-parse --short HEAD 2>/dev/null || echo '-')" chain 0 memo >>target/.gates-timing 2>/dev/null
+        echo "  (a clean run is the fourth gate: scripts/smoke.sh — live logout/re-login round trip)"
+        exit 0
+    fi
+fi
+
+log="$(mktemp "${TMPDIR:-/tmp}/benilla-gates.XXXXXX")"
+skips="$(mktemp "${TMPDIR:-/tmp}/benilla-gates-skips.XXXXXX")"
+trap 'rm -f "$log" "$skips"' EXIT
+
+# libtest hides a passing test's output, so `install.rs`'s `skipped` also appends each data-gated
+# skip to `$BENILLA_SKIP_LOG`; this prints them, grouped, after a test rung and empties the file.
+report_skips() { # $1 = rung name
+    [ -s "$skips" ] || return 0
+    echo "  $1: $(wc -l <"$skips" | tr -d ' ') data-gated tests SKIPPED on this machine —"
+    sort "$skips" | uniq -c | sort -rn | sed 's/^ *\([0-9]*\) \(.*\)/    \1 × \2/'
+    echo "    (they run where the data is: docs/CONTRIBUTING.md, \"Setting up\")"
+    : >"$skips"
+}
+
+# ── Timing ───────────────────────────────────────────────────────────────────────────────────────
+# target/.gates-timing gets one tab-separated line per gate: UTC time, HEAD's short sha, gate,
+# seconds, verdict. A memo hit and a skipped gate are logged at 0 s, the whole chain as `chain`.
+timing="target/.gates-timing"
+chain_t0=$SECONDS
+tree_sha="$(git rev-parse --short HEAD 2>/dev/null || echo '-')"
+note_timing() { # $1 = gate, $2 = seconds, $3 = verdict
+    [ -d target ] || return 0
+    printf '%s\t%s\t%s\t%s\t%s\n' "$(date -u +%FT%TZ)" "$tree_sha" "$1" "$2" "$3" >>"$timing" 2>/dev/null || true
+}
+
+run() {
+    local name="$1"
+    shift
+    local t0=$SECONDS
+    if ! "$@" >"$log" 2>&1; then
+        echo "GATE FAILED: $name ($((SECONDS - t0)) s)"
+        note_timing "$name" "$((SECONDS - t0))" "FAILED"
+        tail -30 "$log"
+        exit 1
+    fi
+    echo "gate ok: $name ($((SECONDS - t0)) s)"
+    note_timing "$name" "$((SECONDS - t0))" "ok"
+}
+
+run fmt cargo fmt --all -- --check
+run clippy cargo clippy --workspace --all-targets -- -D warnings
+
+# test: where the install resolves and the `wow-addons-vanilla` corpus link exists,
+# BENILLA_REQUIRE_DATA=1 refuses a data-gated test that skips; with the install alone it would
+# fail every corpus test. `$wow_data` is resolved once, for player-tests and the stamp too.
+wow_data="$(resolve_wow)"
+require_data=""
+if [ -n "$wow_data" ] && [ -n "$corpus" ]; then
+    require_data=1
+else
+    echo "gates: NOTE — install or addon corpus not found here (install='${wow_data:-none}'," \
+         "corpus=$([ -d "$root/wow-addons-vanilla" ] && echo yes || echo no)):" \
+         "data-gated tests skip silently on this machine"
+fi
+run test env ${require_data:+BENILLA_REQUIRE_DATA=1} BENILLA_SKIP_LOG="$skips" cargo test --workspace
+report_skips test
+
+# test-no-install: refuses a test that reads the install without `wow_data_or_skip!`. `WOW_DATA=`
+# (set, empty) is the resolver's "no install"; no build reads it, so the test binaries are reused.
+run test-no-install env -u BENILLA_REQUIRE_DATA WOW_DATA= cargo test --workspace
+
+# doc-links: refuses a doc link to a `crate::`, `super::`, `self::` or `Self::` path whose leaf is
+# declared nowhere in the workspace. Narrow on purpose: every other unresolved link is a convention.
+run doc-links scripts/doc-links.py
+
+# pass-span-lint: refuses a second `pass_span` on a render pass whose span is still open, a fatal
+# wgpu validation error on Vulkan and a silent no-op on Metal and DX12, which no macOS run sees.
+run pass-span-lint scripts/pass-span-lint.py
+
+# player-build: `benilla` without `dev`, which compiles out the debug panel, perf HUD, inspector,
+# capture harness and probes, so it fails when any other code names one of them.
+run player-build cargo build -p benilla --no-default-features
+
+# player-tests: the unit tests of the `cfg(not(feature = "dev"))` code (the resolver skips the
+# source tree; the state folder sits beside the binary), which no other gate runs. WOW_DATA, which
+# a player build reads too, goes in for the shipped-UI tests that read FrameXML off the install; no
+# BENILLA_REQUIRE_DATA, since without `dev` only $BENILLA_ADDON_CORPUS finds the addon corpus.
+run player-tests env ${wow_data:+WOW_DATA="$wow_data"} BENILLA_SKIP_LOG="$skips" \
+    cargo test -p benilla-formats -p benilla-app --no-default-features --lib
+report_skips player-tests
+
+# enforcer: `benilla-worldview` boots the engine plugins with no server, login, UI or player, in a
+# small window, and refuses any system whose parameters need a gameplay resource, a coupling no
+# compiler sees. The client's own resolver decides whether there is an install, so it skips
+# exactly where the client could not run.
+if cargo run -q -p benilla-formats --example where >/dev/null 2>&1; then
+    run enforcer env WOW_WORLDVIEW_CHECK=10 cargo run -q -p benilla-worldview
+else
+    echo "gate SKIPPED: enforcer (no WoW install found — the engine boot check needs one;"
+    echo "             \`cargo run -p benilla-formats --example where\` says where it looked)"
+    note_timing enforcer 0 SKIPPED
+fi
+
+# enforcer-no-install: the engine boot with no client data, which a dev build reaches only under
+# `WOW_DATA=`; refuses a system that needs a resource inserted only when there is client data.
+# Five seconds suffice: with nothing to stream, every system validates in the first frames.
+run enforcer-no-install env WOW_DATA= WOW_WORLDVIEW_CHECK=5 cargo run -q -p benilla-worldview
+
+echo "ALL GATES GREEN ($((SECONDS - chain_t0)) s; per-gate seconds in $timing)"
+note_timing chain "$((SECONDS - chain_t0))" ok
+
+# Stamp only if the tree still hashes as it did at the start: an edit during the run would
+# otherwise memoize a green for a tree the chain never saw.
+key_end="$(tree_key || true)"
+if [ -n "$key_end" ] && [ "$key_end" = "$key_start" ] && [ -d target ]; then
+    printf '%s|%s%s\n' "$key_end" "$wow_data" "$corpus" > "$stamp" 2>/dev/null || true
+fi
+
+# The clean-run gate, scripts/smoke.sh, needs a server and a window: named here, not run.
+echo "  (a clean run is the fourth gate: scripts/smoke.sh — live logout/re-login round trip)"
diff --git a/scripts/gen-message-catalog.py b/scripts/gen-message-catalog.py
new file mode 100755
index 00000000..211f83e7
--- /dev/null
+++ b/scripts/gen-message-catalog.py
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+r"""Generate `crates/benilla-ui/src/messages/catalog.rs` from `reference/1.12-message-catalog.tsv`.
+
+The table is the reference's message registry at `0xb4b498`, which `CGGameUI::DisplayError`
+`0x496720` indexes by message id; this re-shapes it into a Rust static that ships with benilla.
+
+    python3 scripts/gen-message-catalog.py            # the vendored table -> the .rs, in place
+    python3 scripts/gen-message-catalog.py <tsv>      # another table
+
+It refuses rather than emits on a non-dense id range, a duplicate key or an unknown kind.
+"""
+import os
+import sys
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+TABLE = os.path.join(REPO, "reference", "1.12-message-catalog.tsv")
+OUT = os.path.join(REPO, "crates", "benilla-ui", "src", "messages", "catalog.rs")
+
+KINDS = {0: "Chat", 1: "Info", 2: "Error"}
+
+HEADER = """\
+//! The 1.12 client's message catalog, row for row.
+//!
+//! @generated by `scripts/gen-message-catalog.py` from `reference/1.12-message-catalog.tsv`.
+//! Do not edit by hand; regenerate.
+
+use super::{MessageRecord, MsgKind};
+
+/// Every row of `0xb4b498`, indexed by message id: the ids are dense `0..465`, so `CATALOG[id]`
+/// is the reference's `0xb4b498 + 20*id`.
+///
+/// `rustfmt` is off: the generator emits one row per line, and a rewrap would drift from it.
+#[rustfmt::skip]
+pub static CATALOG: [MessageRecord; {count}] = [
+"""
+
+
+def main(path: str) -> int:
+    if not os.path.exists(path):
+        raise SystemExit(f"no table at {path}")
+    rows = []
+    for line in open(path):
+        if line.startswith("#") or line.startswith("id_hex"):
+            continue
+        f = line.rstrip("\n").split("\t")
+        if len(f) != 8:
+            raise SystemExit(f"malformed row (expected 8 fields, got {len(f)}): {line!r}")
+        rows.append(
+            {
+                "id": int(f[1]),
+                "key": f[3],
+                "kind": int(f[4]),
+                "sound": f[5],
+                "type_tag": int(f[6], 16),
+                "chat_type": int(f[7]),
+            }
+        )
+
+    for want, r in enumerate(rows):
+        if r["id"] != want:
+            raise SystemExit(f"ids are not dense: expected {want}, got {r['id']}")
+    keys = [r["key"] for r in rows]
+    if len(set(keys)) != len(keys):
+        raise SystemExit("duplicate key in the catalog — by_key would be ambiguous")
+    for r in rows:
+        if r["kind"] not in KINDS:
+            raise SystemExit(
+                f"row {r['id']} ({r['key']}) has kind {r['kind']}, which MsgKind does not model"
+            )
+
+    out = [HEADER.replace("{count}", str(len(rows)))]
+    for r in rows:
+        sound = "None" if r["sound"] == "NONE" else f'Some("{r["sound"]}")'
+        out.append(
+            f'    MessageRecord {{ id: {r["id"]}, key: "{r["key"]}", '
+            f'kind: MsgKind::{KINDS[r["kind"]]}, sound: {sound}, '
+            f'type_tag: {r["type_tag"]:#04x}, chat_type: {r["chat_type"]} }},\n'
+        )
+    out.append("];\n")
+    with open(OUT, "w") as f:
+        f.write("".join(out))
+    print(f"wrote {os.path.relpath(OUT, REPO)} ({len(rows)} rows)")
+    return 0
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 2:
+        raise SystemExit(__doc__)
+    sys.exit(main(sys.argv[1] if len(sys.argv) == 2 else TABLE))
diff --git a/scripts/gen-reference-events.py b/scripts/gen-reference-events.py
new file mode 100755
index 00000000..fb7e7c09
--- /dev/null
+++ b/scripts/gen-reference-events.py
@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Regenerate `reference/1.12-events.tsv`: each 1.12 FrameScript event and the arguments it carries.
+
+    scripts/gen-reference-events.py [--catalog FILE] [--firesites FILE] [--out FILE]
+
+The inputs are vendored under `reference/`, so this runs from any clone and reproduces the
+committed table byte for byte:
+
+  - `1.12-event-catalog.tsv`   eventId -> name, off the name-pointer array at `.data 0xbe1198`
+  - `1.12-event-firesites.tsv` every `call` and tail-`jmp` to `FrameScript_SignalEvent`
+                               (`0x703e50`, no varargs) and `SignalEvent2` (`0x703f50`,
+                               printf-style), with the format string each site pushes
+
+A literal fire site is not every producer; the families are:
+
+  signal              a `0x703e50` site: `__fastcall(ecx = id)`, a plain `ret`, zero Lua values.
+  signal2             a `0x703f50` site: the pushed format string is the argument shape.
+  unit-field-bridge   the generic UpdateField -> event bridge (`0x51bbb0` registers one watch per
+                      named unit-window field; `0x51bd50` -> `0x515e50` fans out over the unit
+                      tokens and calls `0x703f50(id, "%s", token)`). Every named event id below
+                      `0xb6` is produced there and has no fire-site row.
+  token-fanout        the same `0x515e50` fan-out reached with a literal id in `edx`: also `%s`,
+                      also absent from the fire sites.
+
+Confidence, and what a consumer may gate on:
+
+  exact      every contributing producer's shape is known. Gate on this.
+  advisory   a contributing site's format declares more varargs than its caller pushes
+             (`0x496230` TRADE_REPLACE_ENCHANT, `0x5e4527`/`0x5e7960` UPDATE_TICKET), which hands
+             Lua undefined values; do not copy it.
+  none       no producer family reaches the name here, which does not mean it has none. Never
+             gate on it.
+
+Glue-space sites are dropped by address: `0x703d90` loads a separate name table for the glue
+screen, so the same id names a different event there. Their names are blank in the input, and
+dropping by address keeps a name filled in later from leaking through.
+"""
+import argparse
+import os
+import sys
+
+# The `Source\Glue\` fire-site ranges (`1.12-event-firesites.tsv`'s header): glue-space ids.
+GLUE_SITES = [(0x46AA34, 0x46AA34), (0x46BC9D, 0x46C52E), (0x46E73D, 0x46E73D), (0x47461E, 0x47461E)]
+# The three sites whose format string declares more varargs than the caller pushes.
+DECLARES_MORE_THAN_IT_PUSHES = {0x496230: "TRADE_REPLACE_ENCHANT", 0x5E4527: "UPDATE_TICKET", 0x5E7960: "UPDATE_TICKET"}
+# `0x515e50` callers with a literal id: the token fan-out reached outside the generic bridge.
+TOKEN_FANOUT_IDS = [0x10, 0x16, 0x1C, 0x1D, 0x1E, 0x29, 0xB7, 0xB8, 0xB9, 0xBA, 0xBB, 0x159, 0x197, 0x20A]
+# `0x51bbb0`'s walk bound (`cmp esi,0xb6`): every named unit-window field below it is watched.
+UNIT_WINDOW_FIELDS = 0xB6
+# The zero-argument format, spelled so the column is never empty.
+NONE = "()"
+
+
+REFERENCE = os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "reference"))
+
+
+def rows(path):
+    if not os.path.exists(path):
+        sys.exit(f"no table at {path}")
+    for line in open(path, encoding="utf-8"):
+        if line.startswith("#"):
+            continue
+        f = line.rstrip("\n").split("\t")
+        if f and f[0] in ("eventId", "fire_site_va"):
+            continue
+        yield f
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--catalog", default=os.path.join(REFERENCE, "1.12-event-catalog.tsv"))
+    ap.add_argument("--firesites", default=os.path.join(REFERENCE, "1.12-event-firesites.tsv"))
+    ap.add_argument("--out", default=os.path.join(REFERENCE, "1.12-events.tsv"))
+    a = ap.parse_args()
+
+    catalog = {}
+    for f in rows(a.catalog):
+        if len(f) >= 2 and f[1]:
+            catalog.setdefault(int(f[0]), f[1])
+    if len(catalog) < 300:
+        sys.exit(f"{a.catalog} gave only {len(catalog)} names — wrong path?")
+
+    # name -> {ids, producers, formats, notes}
+    ev = {}
+
+    def add(name, eid, producer, fmt, note=None):
+        e = ev.setdefault(name, {"ids": set(), "producers": set(), "formats": set(), "notes": []})
+        e["ids"].add(eid)
+        e["producers"].add(producer)
+        e["formats"].add(fmt)
+        if note and note not in e["notes"]:
+            e["notes"].append(note)
+
+    dropped_glue = 0
+    for f in rows(a.firesites):
+        if len(f) < 4:
+            continue
+        va = int(f[0], 16)
+        dispatcher, eid, name = f[1], f[2], f[3]
+        if any(lo <= va <= hi for lo, hi in GLUE_SITES):
+            dropped_glue += 1
+            continue
+        if not name or eid == "dyn":
+            continue
+        fmt = NONE if dispatcher == "SignalEvent" else (f[4] if len(f) > 4 and f[4] else NONE)
+        note = None
+        if va in DECLARES_MORE_THAN_IT_PUSHES:
+            note = f"0x{va:x} declares more varargs than it pushes — do not copy"
+        add(name, int(eid), "signal" if dispatcher == "SignalEvent" else "signal2", fmt, note)
+
+    for eid, name in catalog.items():
+        if eid < UNIT_WINDOW_FIELDS:
+            add(name, eid, "unit-field-bridge", "%s")
+    for eid in TOKEN_FANOUT_IDS:
+        if eid in catalog:
+            add(catalog[eid], eid, "token-fanout", "%s")
+
+    # Every remaining catalog name too, so "no producer found" differs from "not an event".
+    for eid, name in catalog.items():
+        if name not in ev:
+            ev.setdefault(name, {"ids": set(), "producers": set(), "formats": set(), "notes": []})["ids"].add(eid)
+
+    out = os.path.normpath(a.out)
+    with open(out, "w", encoding="utf-8") as fh:
+        fh.write(
+            "# The 1.12.1 client's FrameScript events and the arguments their producers push.\n"
+            "# Generated by scripts/gen-reference-events.py from reference/1.12-event-catalog.tsv\n"
+            "# and reference/1.12-event-firesites.tsv.\n"
+            "#\n"
+            "# arg_formats  `|`-separated, one per distinct producer shape. `()` = zero Lua values.\n"
+            "#              Directives: %s string, %d/%u number, %f number. An event with two\n"
+            "#              producers of different shapes carries both; which one fires depends\n"
+            "#              on the transition, not the name.\n"
+            "# conf         exact = gate on it. advisory = a contributing site declares more\n"
+            "#              varargs than it pushes. none = no producer family reaches it here,\n"
+            "#              which does not mean it has none; never gate on it.\n"
+            "# producers    signal (0x703e50, no varargs) | signal2 (0x703f50, format-driven) |\n"
+            "#              unit-field-bridge (0x51bbb0/0x51bd50 -> 0x515e50, always %s) |\n"
+            "#              token-fanout (0x515e50 with a literal id, also %s).\n"
+            f"# {len(ev)} events, {sum(1 for e in ev.values() if e['producers'])} with a known producer;"
+            f" {dropped_glue} glue-space fire sites dropped.\n"
+            "name\tids\tproducers\targ_formats\tconf\tnote\n"
+        )
+        for name in sorted(ev):
+            e = ev[name]
+            conf = "none" if not e["producers"] else ("advisory" if e["notes"] else "exact")
+            fh.write(
+                "\t".join(
+                    (
+                        name,
+                        "|".join(str(i) for i in sorted(e["ids"])),
+                        "|".join(sorted(e["producers"])),
+                        "|".join(sorted(e["formats"])) or "?",
+                        conf,
+                        "; ".join(e["notes"]),
+                    )
+                )
+                + "\n"
+            )
+    print(f"wrote {out}: {len(ev)} events, {sum(1 for e in ev.values() if e['producers'])} produced")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/gen-reference-globals.py b/scripts/gen-reference-globals.py
new file mode 100755
index 00000000..e447ae1d
--- /dev/null
+++ b/scripts/gen-reference-globals.py
@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""Regenerate `reference/1.12-globals.tsv`: the 1.12.1 client's global namespace, by origin.
+
+    scripts/gen-reference-globals.py --capture FILE --framexml DIR [--data DIR] [--drop NAME]...
+        [--out FILE]
+
+Each name in a capture of the running reference client's in-world `_G` gets one origin:
+
+  lua       Lua 5.0's own runtime, which mlua provides.
+  engine    the C client provides it; benilla implements these in Rust.
+  framexml  the shipped UI defines it (its Lua, its XML, or a `$parent`-composed child of one);
+            it runs off the player's own patch chain, never hardcoded in Rust.
+
+Attribution is by definition site in the complete 1.12 shipped-UI corpus:
+
+  - a name assigned or `function`-declared in shipped Lua, including Lua inside a FrameXML
+    document, is FrameXML's; indented assignments count, because FrameXML leaks globals out of
+    function bodies (`button = getglobal(...)`);
+  - a `name="..."` on any shipped XML element is FrameXML's, `virtual="true"` included: a virtual
+    `<Font>` is a real font object, and 1.12 registers named virtual frames too;
+  - `<a shipped name><a $parent suffix>` is a composed child (`ContainerFrame1Item16IconTexture`);
+  - LUA_5_0 wins over all of these: FrameXML's `string = getglobal(...)` would otherwise claim
+    the stdlib table.
+
+The capture (`--capture`, with `--drop` naming the capturing addon's own globals) and the
+extracted FrameXML (`--framexml`) are the maintainer's, not in this repo; the MPQs are the
+install's (`--data`, else `$WOW_DATA`, else `WoW/Data`). FrameXML alone is not the shipped UI:
+the twelve `Blizzard_*` addons live in the MPQs, and their `.lua` is reached through
+`<Script file=>` in their XML, not their `.toc`. A complete corpus is 233 files; the count is
+printed.
+"""
+import argparse
+import os
+import re
+import subprocess
+import sys
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# The twelve addons shipped inside the MPQs; an install's folder for each holds only a `.pub`.
+BLIZZARD_ADDONS = [
+    "Blizzard_AuctionUI", "Blizzard_BattlefieldMinimap", "Blizzard_BindingUI",
+    "Blizzard_CombatText", "Blizzard_CraftUI", "Blizzard_GMSurveyUI",
+    "Blizzard_InspectUI", "Blizzard_MacroUI", "Blizzard_RaidUI",
+    "Blizzard_TalentUI", "Blizzard_TradeSkillUI", "Blizzard_TrainerUI",
+]
+
+# Lua 5.0's globals as the 1.12 client exposes them: it removes `_G`, `print`, `require`,
+# `dofile`, `loadfile` and the `io`/`os`/`debug`/`coroutine` tables.
+LUA_5_0 = {
+    "assert", "collectgarbage", "error", "gcinfo", "getfenv", "getmetatable", "ipairs",
+    "loadstring", "math", "next", "pairs", "pcall", "rawequal", "rawget", "rawset",
+    "setfenv", "setmetatable", "string", "table", "tonumber", "tostring", "type",
+    "unpack", "xpcall",
+}
+
+LUA_ASSIGN = re.compile(r"^[ \t]*([A-Za-z_][A-Za-z0-9_]*)\s*=[^=]", re.M)
+LUA_FUNC = re.compile(r"^[ \t]*function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(", re.M)
+LUA_MULTI = re.compile(
+    r"^[ \t]*([A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_]*)+)\s*=[^=]", re.M
+)
+XML_ELEM = re.compile(r"<(\w+)([^>]*?)/?>", re.S)
+XML_NAME = re.compile(r'\bname\s*=\s*"([^"]*)"')
+PARENT_SUFFIX = re.compile(r'\bname\s*=\s*"\$parent([A-Za-z0-9_]*)"')
+# Lua inside a FrameXML document: an inline `<Script>` body (Fonts.xml's CHAT_FONT_HEIGHTS) and
+# every `<Scripts>` handler element (`<OnLoad>`, `<PreClick>`, ...), matched by shape so no handler
+# name is missed. `<Script file=>` is skipped: its file is already in the corpus.
+XML_SCRIPT = re.compile(
+    r"<((?:On|Pre|Post)\w+|Script)\b(?![^>]*\bfile\s*=)[^>]*>(.*?)</\1>", re.S
+)
+XML_REF = re.compile(rb'<(?:Script|Include)\s+file\s*=\s*"([^"]+)"', re.I)
+
+
+def captured_globals(fixture):
+    """`["globals"]["keys"]` out of the capture: the in-world `_G`, as (name, lua type)."""
+    recs, cur_t, inside = [], None, False
+    with open(fixture, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            if not inside:
+                inside = line.strip() == '["globals"] = {'
+                continue
+            if '["count"]' in line:
+                break
+            m = re.match(r'\s*\["t"\] = "([^"]*)",', line)
+            if m:
+                cur_t = m.group(1)
+                continue
+            m = re.match(r'\s*\["name"\] = "(.*)",\s*$', line)
+            if m:
+                recs.append((m.group(1), cur_t))
+                cur_t = None
+    return recs
+
+
+def join_ref(base, ref):
+    """Resolve a reference against the including file's directory, as `loader::join_ref` does."""
+    ref = ref.replace("\\", "/").strip()
+    parts = ref[1:].split("/") if ref.startswith("/") else (base.split("/") if base else []) + ref.split("/")
+    out = []
+    for p in parts:
+        if p in ("", "."):
+            continue
+        if p == ".." and out and out[-1] != "..":
+            out.pop()
+        else:
+            out.append(p)
+    return "/".join(out)
+
+
+def build_corpus(data, framexml):
+    """Every file of the 1.12 shipped UI, as {corpus-relative path: text}."""
+    archives = [os.path.join(data, f"{a}.MPQ") for a in ("patch-2", "patch", "interface", "base")]
+    archives = [a for a in archives if os.path.exists(a)]
+    mpqcat = os.path.join(REPO, "target", "debug", "examples", "mpqcat")
+    if not os.path.exists(mpqcat):
+        subprocess.run(
+            ["cargo", "build", "-q", "-p", "benilla-mpq", "--example", "mpqcat"],
+            cwd=REPO, check=True,
+        )
+
+    def mpq_read(archive_path):
+        for arc in archives:
+            r = subprocess.run([mpqcat, arc, archive_path], capture_output=True)
+            if r.returncode == 0:
+                return r.stdout
+        return None
+
+    files = {}
+    fx = framexml
+    for fn in sorted(os.listdir(fx)):
+        p = os.path.join(fx, fn)
+        if os.path.isfile(p):
+            files[f"FrameXML/{fn}"] = open(p, "rb").read()
+    print(f"  FrameXML: {len(files)} files")
+
+    for addon in BLIZZARD_ADDONS:
+        toc_rel = f"{addon}/{addon}.toc"
+        toc = mpq_read("Interface\\AddOns\\" + toc_rel.replace("/", "\\"))
+        if toc is None:
+            print(f"  !! {addon}: no .toc in any archive", file=sys.stderr)
+            continue
+        files[toc_rel] = toc
+        queue, seen = [], set()
+        for line in toc.decode("utf-8", "replace").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#"):
+                queue.append(join_ref(addon, line))
+        while queue:
+            rel = queue.pop(0)
+            if rel in seen:
+                continue
+            seen.add(rel)
+            data = mpq_read("Interface\\AddOns\\" + rel.replace("/", "\\"))
+            if data is None:
+                print(f"  !! {addon}: missing {rel}", file=sys.stderr)
+                continue
+            files[rel] = data
+            # The addons' `.lua` is reached only from their XML, never from the `.toc`.
+            if rel.lower().endswith(".xml"):
+                base = rel.rsplit("/", 1)[0] if "/" in rel else ""
+                for m in XML_REF.finditer(data):
+                    queue.append(join_ref(base, m.group(1).decode("utf-8", "replace")))
+        print(f"  {addon}: {1 + len(seen)} files")
+    return {k: v.decode("utf-8", "replace") for k, v in files.items()}
+
+
+def lua_defs(text, into):
+    into.update(LUA_ASSIGN.findall(text))
+    into.update(LUA_FUNC.findall(text))
+    for grp in LUA_MULTI.findall(text):
+        into.update(n.strip() for n in grp.split(","))
+
+
+def shipped_names(corpus):
+    """Every global the shipped UI defines, plus the `$parent` suffixes children compose with."""
+    names, suffixes = set(), set()
+    for rel, text in corpus.items():
+        if rel.lower().endswith(".lua"):
+            lua_defs(text, names)
+        elif rel.lower().endswith(".xml"):
+            for _tag, body in XML_SCRIPT.findall(text):
+                lua_defs(body, names)
+            suffixes.update(s for s in PARENT_SUFFIX.findall(text) if s)
+            for tag, attrs in XML_ELEM.findall(text):
+                # `<Binding name="ACTIONBUTTON1">` is a key-binding command, not a global.
+                if tag.lower() == "binding":
+                    continue
+                m = XML_NAME.search(attrs)
+                if m and "$parent" not in m.group(1):
+                    names.add(m.group(1))
+    return names, suffixes
+
+
+def composed(name, roots, suffixes, depth=0):
+    """Is `name` `<a shipped name><a $parent suffix>`, recursively? A numeric tail on the parent
+    side is allowed: `ContainerFrame1` and `Item16` come from Lua's `name..i`."""
+    if depth > 8:
+        return False
+    for i in range(1, len(name)):
+        head, tail = name[:i], name[i:]
+        if tail not in suffixes:
+            continue
+        if head in roots or head.rstrip("0123456789") in roots:
+            return True
+        if composed(head, roots, suffixes, depth + 1):
+            return True
+    return False
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--capture", help="a capture of the running client's in-world _G")
+    ap.add_argument("--framexml", help="the shipped FrameXML, extracted to a folder")
+    ap.add_argument("--data", help="the install's Data folder, which holds the MPQs",
+                    default=os.environ.get("WOW_DATA") or os.path.join(REPO, "WoW", "Data"))
+    # The capturing addon's own globals (its holder frame, SavedVariables and slash token) are the
+    # instrument, not the client. `__framescript_meta` stays in: it is the client's own shared
+    # frame metatable.
+    ap.add_argument("--drop", action="append", default=[], help="a global of the capturing addon")
+    ap.add_argument("--out", default=os.path.join(REPO, "reference", "1.12-globals.tsv"))
+    args = ap.parse_args()
+    if not args.capture or not args.framexml:
+        sys.exit(
+            "this table is derived from a runtime capture of the reference client's _G and the "
+            "extracted FrameXML, which are not in this repo: pass --capture and --framexml. The "
+            "committed reference/1.12-globals.tsv is the surface benilla tracks."
+        )
+    if not os.path.exists(args.capture):
+        sys.exit(f"no capture at {args.capture}")
+
+    print("building the 1.12 shipped-UI corpus...")
+    corpus = build_corpus(args.data, args.framexml)
+    print(f"  TOTAL: {len(corpus)} files" + ("" if len(corpus) == 233 else "  ** expected 233 **"))
+
+    recs = [(n, t) for n, t in captured_globals(args.capture) if n not in set(args.drop)]
+    defined, suffixes = shipped_names(corpus)
+    print(f"captured globals: {len(recs)}   shipped definitions: {len(defined)}   "
+          f"$parent suffixes: {len(suffixes)}")
+
+    rows, tally = [], {}
+    captured = set()
+    for name, t in recs:
+        captured.add(name)
+        if name in LUA_5_0:
+            origin = "lua"
+        elif name in defined or composed(name, defined, suffixes):
+            origin = "framexml"
+        else:
+            origin = "engine"
+        rows.append((name, t, origin))
+        tally[(origin, t)] = tally.get((origin, t), 0) + 1
+
+    # ── The LoadOnDemand names ─────────────────────────────────────────────────────────────────
+    # The twelve `Blizzard_*` addons are LoadOnDemand, so a live capture holds their globals only
+    # if their windows were opened first. Every name the shipped UI defines that the capture lacks
+    # joins with type `lod`: the table answers "is this a 1.12 name?", and the halves stay apart.
+    lod = 0
+    for name in sorted(defined - captured):
+        rows.append((name, "lod", "framexml"))
+        tally[("framexml", "lod")] = tally.get(("framexml", "lod"), 0) + 1
+        lod += 1
+    print(f"shipped-UI definitions the capture did not contain: {lod} (LoadOnDemand + unrealized)")
+
+    os.makedirs(os.path.dirname(args.out), exist_ok=True)
+    with open(args.out, "w") as f:
+        f.write("# The 1.12.1 client's global namespace. Generated by scripts/gen-reference-globals.py.\n")
+        f.write("# Source: a capture of the running client's in-world _G (the maintainer's),\n")
+        f.write("# attributed against the complete 1.12 shipped-UI corpus.\n")
+        f.write("# Also every name that corpus defines but the capture lacks, as type `lod`: the\n")
+        f.write("# twelve Blizzard_* addons are LoadOnDemand, so a live dump misses them unless\n")
+        f.write("# their windows were opened.\n")
+        f.write("# name\ttype\torigin(lua|engine|framexml)\n")
+        for row in sorted(rows):
+            f.write("\t".join(row) + "\n")
+
+    print(f"\nwrote {args.out}  ({len(rows)} names)")
+    for k in sorted(tally):
+        print(f"  {k[0]:9s} {k[1]:9s} {tally[k]}")
+
+
+main()
diff --git a/scripts/gen-reference-verb-events.py b/scripts/gen-reference-verb-events.py
new file mode 100755
index 00000000..46cd78a4
--- /dev/null
+++ b/scripts/gen-reference-verb-events.py
@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Regenerate `reference/1.12-verb-events.tsv`: the events 1.12 Lua verbs fire, keyed by verb.
+
+    scripts/gen-reference-verb-events.py --names FILE --extents FILE... --disasm FILE [--out FILE]
+
+A row says the reference fires `event` on the call path of the registered Lua binding `verb`:
+from the verb's body (`shape=body`), or from a helper that only registered verbs call
+(`shape=helper`, `via` = the helper's address; `0x4d8c90` is the trainer's). A helper with any
+non-verb caller (a packet handler, the cursor, the tutorial signal) fires a state event and is
+left out, and so is a hub (`ClearCursor` -> CURSOR_UPDATE, 49 callers).
+
+A site's function is the greatest start at or below it, over the union of: every function the
+analysis sizes, every named function start, every `call` target in the client's disassembly,
+every registered verb, and every address after a padding run (an `int3` run anywhere, or a `nop`
+run after a `ret`; a `nop` run after a `jmp` is a loop head, not a boundary). A site at or past
+`start + size` of a sized function is left unattributed rather than handed to it.
+
+Two families are dropped: glue-space verbs and sites (the GlueXML registrar, 0x46a000..0x476000)
+and the unit-field bridge and token fan-out ids below 0xb6, which are state events.
+
+A floor, not a census: a verb with no row may still fire an event, because the fire sites are
+only the two signal helpers' literal call sites and `shape=helper` stops one call deep.
+
+The fire sites and the binding shapes are the vendored `reference/` tables; the function names
+(`--names`), extents (`--extents`, the `size=` on each `fn` row) and disassembly (`--disasm`) are
+the maintainer's analysis, not in this repo, so this is a manual regeneration.
+"""
+import argparse
+import bisect
+import collections
+import os
+import re
+import sys
+
+# The GlueXML registrar's address range: an id fired there names a glue-screen event.
+GLUE = (0x46A000, 0x476000)
+# `0x51bbb0`'s walk bound: every named unit-window field below it fires through the generic bridge.
+UNIT_WINDOW_FIELDS = 0xB6
+# A helper "only verbs call" is trusted up to this many callers; past it, it is a hub.
+MAX_HELPER_CALLERS = 8
+
+LINE = re.compile(r"^\s*([0-9a-f]+):\t(\S+)(?:\s+(.*))?$")
+BRANCH = re.compile(r"^(call|jmp)\s+0x([0-9a-f]+)\s*$")
+SIZE = re.compile(r"\bsize=(\d+)")
+
+
+REFERENCE = os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "reference"))
+
+
+def rows(path):
+    if not os.path.exists(path):
+        sys.exit(f"no table at {path}")
+    for line in open(path, encoding="utf-8"):
+        if line.startswith("#"):
+            continue
+        f = line.rstrip("\n").split("\t")
+        if f and f[0] in ("name", "addr", "eventId", "fire_site_va"):
+            continue
+        yield f
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--names", help="the function names: `addr<TAB>kind` rows, `func` a start")
+    ap.add_argument("--extents", nargs="+", default=[], help="tables whose `fn` rows carry size=")
+    ap.add_argument("--disasm", help="the client's disassembly, one objdump line per instruction")
+    ap.add_argument("--out", default=os.path.join(REFERENCE, "1.12-verb-events.tsv"))
+    a = ap.parse_args()
+    if not (a.names and a.extents and a.disasm):
+        sys.exit(
+            "this table is derived from the maintainer's function names, extents and disassembly, "
+            "which are not in this repo: pass --names, --extents and --disasm. The committed "
+            "reference/1.12-verb-events.tsv is the surface benilla tracks."
+        )
+
+    starts = set()
+    for f in rows(a.names):
+        if len(f) >= 2 and f[1] == "func":
+            starts.add(int(f[0], 16))
+    if len(starts) < 1000:
+        sys.exit(f"{a.names} gave only {len(starts)} functions — wrong file?")
+
+    # Function extents: `size=` on the `fn` rows of the extent tables.
+    extent = {}  # fn start -> size in bytes
+    for path in a.extents:
+        for line in open(path, encoding="utf-8", errors="replace"):
+            if not line.startswith("fn\t"):
+                continue
+            f = line.rstrip("\n").split("\t")
+            m = SIZE.search(line)
+            if m and len(f) > 1 and f[1].startswith("0x"):
+                fn = int(f[1], 16)
+                extent[fn] = max(extent.get(fn, 0), int(m.group(1)))
+    if len(extent) < 5000:
+        sys.exit(f"the extent tables gave only {len(extent)} sized functions — wrong files?")
+    starts |= set(extent)
+
+    verbs = {}  # fn address -> name
+    for f in rows(os.path.join(REFERENCE, "1.12-shapes.tsv")):
+        if len(f) < 2:
+            continue
+        fn = int(f[1], 16)
+        if GLUE[0] <= fn < GLUE[1] or f[0].startswith("Get"):
+            # A getter's fire is a cache-miss re-query announced when the answer lands
+            # (`GetInboxText`, `GetAuctionItemInfo`): a state event, fired by benilla's feeds.
+            continue
+        verbs.setdefault(fn, f[0])
+    if len(verbs) < 1000:
+        sys.exit(f"1.12-shapes.tsv gave only {len(verbs)} verbs — wrong path?")
+    starts |= set(verbs)
+
+    sites = []  # (site va, event name)
+    for f in rows(os.path.join(REFERENCE, "1.12-event-firesites.tsv")):
+        if len(f) < 4 or not f[0].startswith("0x") or not f[3] or f[2] == "dyn":
+            continue
+        va, eid = int(f[0], 16), int(f[2])
+        if GLUE[0] <= va < GLUE[1] or eid < UNIT_WINDOW_FIELDS:
+            continue
+        sites.append((va, f[3]))
+    if len(sites) < 300:
+        sys.exit(f"1.12-event-firesites.tsv gave only {len(sites)} sites — wrong path?")
+
+    # One pass over the disassembly: every call/jmp edge, and every padding boundary (an `int3`
+    # run, or a `nop` run right after a `ret`). A `nop` run after a `jmp` is a loop head's
+    # alignment inside a function, not a start.
+    edges = []
+    after_pad = False
+    ended = False  # the previous real instruction was a `ret`
+    n_lines = 0
+    disasm = a.disasm
+    if not os.path.exists(disasm):
+        sys.exit(f"no disassembly at {disasm}")
+    for line in open(disasm, encoding="utf-8", errors="replace"):
+        m = LINE.match(line)
+        if not m:
+            continue
+        n_lines += 1
+        va, mnem, ops = int(m.group(1), 16), m.group(2), m.group(3) or ""
+        if mnem == "int3" or (mnem == "nop" and (ended or after_pad)):
+            after_pad = True
+            continue
+        if after_pad:
+            starts.add(va)
+            after_pad = False
+        ended = mnem == "ret"
+        b = BRANCH.match(f"{mnem} {ops}".strip())
+        if b:
+            edges.append((va, b.group(1), int(b.group(2), 16)))
+    if n_lines < 1_000_000:
+        sys.exit(f"{disasm} gave only {n_lines} lines — wrong file?")
+    starts |= {t for _, k, t in edges if k == "call"}
+    ordered = sorted(starts)
+
+    def enclosing(va):
+        """The function holding `va`; None when `va` lies past its candidate's extent."""
+        fn = ordered[bisect.bisect_right(ordered, va) - 1]
+        if fn in extent and va >= fn + extent[fn]:
+            return None
+        return fn
+
+    callers = collections.defaultdict(set)
+    for va, kind, target in edges:
+        if kind == "call" or target in starts:  # a jmp to a function start is a tail call
+            src = enclosing(va)
+            if src is not None and src != target:
+                callers[target].add(src)
+
+    # (verb, event) -> {"shape", "via", "sites"}
+    table = {}
+
+    def add(verb, event, shape, via, site):
+        row = table.setdefault((verb, event), {"shape": shape, "via": via, "sites": set()})
+        if shape == "body":  # a body fire outranks a helper fire for the same pair
+            row["shape"], row["via"] = "body", "-"
+        row["sites"].add(site)
+
+    unattributed = 0
+    for va, event in sites:
+        fn = enclosing(va)
+        if fn is None:
+            unattributed += 1
+            continue
+        if fn in verbs:
+            add(verbs[fn], event, "body", "-", va)
+            continue
+        cs = callers.get(fn, set())
+        if cs and len(cs) <= MAX_HELPER_CALLERS and all(c in verbs for c in cs):
+            for c in cs:
+                add(verbs[c], event, "helper", f"0x{fn:x}", va)
+
+    out = os.path.normpath(a.out)
+    with open(out, "w", encoding="utf-8") as fh:
+        fh.write(
+            "# The 1.12.1 client's FrameScript events fired from inside a Lua verb, keyed by the verb.\n"
+            "# Generated by scripts/gen-reference-verb-events.py from reference/1.12-shapes.tsv,\n"
+            "# reference/1.12-event-firesites.tsv and the maintainer's analysis.\n"
+            "#\n"
+            "# shape  body   = a fire site inside the verb's own extent.\n"
+            "#        helper = a fire site inside a function that only registered verbs call\n"
+            "#                 (at most 8 of them); `via` is that helper. A helper with any\n"
+            "#                 non-verb caller produces a state event and is not here.\n"
+            "# sites  the fire sites themselves.\n"
+            "# A floor, not a census: a verb with no row may still fire an event.\n"
+            "# A site past its candidate function's extent is left out rather than mis-filed.\n"
+            f"# {len(table)} pairs over {len({v for v, _ in table})} verbs and"
+            f" {len({e for _, e in table})} events; {unattributed} site(s) past a verified extent.\n"
+            "verb\tevent\tshape\tvia\tsites\n"
+        )
+        for (verb, event), row in sorted(table.items()):
+            fh.write(
+                "\t".join(
+                    (
+                        verb,
+                        event,
+                        row["shape"],
+                        row["via"],
+                        "|".join(f"0x{s:x}" for s in sorted(row["sites"])),
+                    )
+                )
+                + "\n"
+            )
+    print(
+        f"wrote {out}: {len(table)} pairs, {len({v for v, _ in table})} verbs,"
+        f" {len({e for _, e in table})} events"
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/genmap.sh b/scripts/genmap.sh
new file mode 100755
index 00000000..f4d72d3b
--- /dev/null
+++ b/scripts/genmap.sh
@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Generate docs/MAP.md, the map of what is built, from what is on disk.
+#
+# Regenerated and committed at every land; run it by hand only to look, never edit the output. No
+# timestamps, so an identical tree gives an identical map. No `pipefail`/`-e`: a grep that finds
+# nothing (a single-file lib, a crate with no bins) must not abort the generator.
+set -u
+cd "$(dirname "$0")/.."
+
+# Extract a quoted `key = "value"` field from a Cargo.toml.
+field() { grep -m1 "^$2" "$1" 2>/dev/null | sed -E "s/^$2[[:space:]]*=[[:space:]]*\"//; s/\".*$//"; }
+
+{
+  echo "# benilla — generated map"
+  echo
+  echo "> **GENERATED** by \`scripts/genmap.sh\` from the code — do not edit by hand; rerun the script"
+  echo "> when what's built changes. *What-is* only: the *what-changed* is in git. No timestamp —"
+  echo "> identical code yields an identical map."
+  echo
+
+  echo "## Crates"
+  echo
+  for ct in crates/*/Cargo.toml; do
+    name=$(field "$ct" name)
+    desc=$(field "$ct" description)
+    # Crates here write `bevy.workspace = true`: the trailing class accepts `.`, whitespace and `=`
+    # (`bevy = { … }`, `bevy="…"` too) and still rejects a `bevyfoo` crate.
+    if grep -qE '^(bevy|bevy_egui|avian3d)[.[:space:]=]' "$ct"; then bevy="Bevy"; else bevy="no Bevy"; fi
+    echo "- **$name** ($bevy) — ${desc:-—}"
+  done
+  echo
+
+  echo "## App subsystems — Bevy plugins in load order (\`crates/benilla-app/src/lib.rs\`)"
+  echo
+  # Accept bare (`add_plugins(FooPlugin)`) and path-qualified (`add_plugins(foo::FooPlugin)`)
+  # registrations; print the plugin type name either way.
+  grep -oE 'add_plugins\(([a-z_]+::)*[A-Za-z_]+Plugins?' crates/benilla-app/src/lib.rs \
+    | sed -E 's/add_plugins\(//; s/([a-z_]+::)+//' | awk '!seen[$0]++ {print "- " $0}'
+  echo
+
+  # `lib.rs` adds each dev group in one line, so their members are read out of `dev.rs`.
+  echo "### Behind the \`dev\` feature (\`crates/benilla-app/src/dev.rs\` — compiled out by \`--no-default-features\`)"
+  echo
+  grep -oE 'add_plugins\(([a-z_]+::)*[A-Za-z_]+Plugins?' crates/benilla-app/src/dev.rs \
+    | sed -E 's/add_plugins\(//; s/([a-z_]+::)+//' | awk '!seen[$0]++ {print "- " $0}'
+  echo
+
+  echo "## Modules (top-level, per crate)"
+  echo
+  for lib in crates/*/src/lib.rs crates/*/src/main.rs; do
+    [ -f "$lib" ] || continue
+    crate=$(echo "$lib" | sed -E 's@crates/([^/]+)/.*@\1@')
+    mods=$(grep -E '^[[:space:]]*(pub(\([a-z]+\))? )?mod [a-z_0-9]+;' "$lib" \
+      | sed -E 's/.*mod ([a-z_0-9]+);.*/\1/' | sort | tr '\n' ' ')
+    [ -n "$mods" ] && echo "- **$crate** ($(basename "$lib")): $mods"
+  done
+  echo
+
+  echo "## CLI binaries"
+  echo
+  # Both forms cargo accepts: `src/bin/<name>.rs` and `src/bin/<name>/main.rs`.
+  for b in crates/*/src/bin/*.rs crates/*/src/bin/*/main.rs; do
+    [ -f "$b" ] || continue
+    crate=$(echo "$b" | sed -E 's@crates/([^/]+)/.*@\1@')
+    case "$b" in
+      */main.rs) name=$(basename "$(dirname "$b")") ;;
+      *) name=$(basename "$b" .rs) ;;
+    esac
+    echo "- \`$name\` (in $crate)"
+  done | LC_ALL=C sort
+  echo
+
+  # Shaders are embedded and addressed by their owning crate, so the crate is part of the name.
+  echo "## WGSL shaders (\`crates/*/src/shaders/\`, embedded)"
+  echo
+  for s in crates/*/src/shaders/*.wgsl; do
+    [ -f "$s" ] || continue
+    crate=$(echo "$s" | sed -E 's@crates/([^/]+)/.*@\1@' | tr - _)
+    echo "- \`embedded://$crate/shaders/$(basename "$s")\`"
+  done
+  echo
+
+  echo "## Instruments — \`\$WOW_*\` switches (env-var read sites)"
+  echo
+  echo "> The headless/dev instrument fleet, discovered from the code: every \`WOW_*\` env var"
+  echo "> some \`.rs\` reads, and where it's read — the doc comment at the read site is the"
+  # Name no dev keys here: they are listed once, in the debug panel's footer.
+  echo "> semantics. (The in-window surfaces — the Ctrl+Shift dev-chord overlays — are plugins"
+  echo "> above; this indexes the switches that don't announce themselves.)"
+  echo
+  # Match any quoted "WOW_*" literal: reads also go through helpers (`knob("WOW_FX_AGE", …)`), and
+  # doc comments write the unquoted form. The probe registry `capture/probe_env.rs` is a table,
+  # not a read site, so it is left out.
+  grep -rHoE '"WOW_[A-Z0-9_]+"' crates --include='*.rs' 2>/dev/null \
+    | grep -v '^crates/benilla-app/src/capture/probe_env\.rs:' \
+    | sed -E 's@^crates/@@; s/:"/\t/; s/"$//' \
+    | awk -F'\t' '{print $2 "\t" $1}' | sort -u \
+    | awk -F'\t' '$1 != v { if (v) print line; v = $1; line = "- `" $1 "` — " $2; next }
+                  { line = line ", " $2 }
+                  END { if (v) print line }'
+  echo
+
+  # Every script, with the first sentence of its own header.
+  echo "## Scripts (\`scripts/\`)"
+  echo
+  for f in scripts/*.py scripts/*.sh; do
+    [ -f "$f" ] || continue
+    # The summary: the header's first non-empty content after the shebang, comment or docstring
+    # markers stripped, joined until its first blank line, cut at a sentence end or ~150 chars.
+    summary=$(LC_ALL=C awk '
+      NR == 1 && /^#!/ { next }
+      /^@echo off/ { next }
+      { line = $0
+        sub(/^[[:space:]]*(r?"""|#|\/\/|rem)[[:space:]]?/, "", line)
+        if (line ~ /^[[:space:]]*$/) { if (got) exit; else next }
+        if (line ~ /^"""/) exit
+        got = 1; out = out (out ? " " : "") line }
+      END { print out }' "$f" | sed -E 's/\*\*//g; s/^[A-Za-z0-9_.\/-]+ (—|--) //; s/^([^.]*[.!?])([[:space:]]|$).*/\1/; s/^(.{150}).+/\1…/')
+    echo "- \`${f#scripts/}\` — $summary"
+  done
+  echo
+
+} > docs/MAP.md
+
+echo "genmap: wrote docs/MAP.md"
diff --git a/scripts/mixsum.py b/scripts/mixsum.py
new file mode 100755
index 00000000..ece40149
--- /dev/null
+++ b/scripts/mixsum.py
@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Read a `$WOW_MIX_TAP` capture and say, in numbers, what the mix was doing when.
+
+The tap records the final mix to a stereo float-32 WAV. This prints a windowed RMS/peak envelope
+with a bar, and a `spans` report naming every silent stretch and every onset/offset edge: a hole
+is a silent span with a start and an end, and a linear fade-to-zero is a straight line in dBFS, a
+cut a cliff, a crossfade an overlap. `--json` for a machine, the default for a session log.
+
+    scripts/mixsum.py entry.wav                  # 250 ms windows, the envelope + the spans
+    scripts/mixsum.py entry.wav --window 0.1     # finer, for a click or a declick ramp
+    scripts/mixsum.py entry.wav --from 2 --to 12 # just the covered window
+    scripts/mixsum.py entry.wav --quiet          # the spans only, no per-window rows
+
+Pure stdlib, so it runs without installing anything. Python's `wave` module refuses format 3
+(IEEE float), so the tap's 44-byte header is parsed directly; it must match
+`sound::mix_tap::wav_header`.
+"""
+
+import argparse
+import json
+import math
+import struct
+import sys
+from array import array
+
+# Below this a window is silence: the tap is pre-clamp and dither-free, so true silence reads
+# -inf, and -80 dBFS still counts an audible fade tail as sound.
+SILENCE_DBFS = -80.0
+
+
+def read_tap(path):
+    """(sample_rate, interleaved float32 array). Tolerates the tap's crash-safe truncated tail."""
+    with open(path, "rb") as f:
+        head = f.read(44)
+        if len(head) < 44 or head[0:4] != b"RIFF" or head[8:12] != b"WAVE":
+            sys.exit(f"mixsum: {path} is not a RIFF/WAVE file")
+        fmt, channels, rate, _brate, _align, bits = struct.unpack("<HHIIHH", head[20:36])
+        if (fmt, channels, bits) != (3, 2, 32):
+            sys.exit(
+                f"mixsum: expected stereo float-32 (fmt 3), got fmt={fmt} ch={channels} bits={bits}"
+            )
+        if head[36:40] != b"data":
+            sys.exit("mixsum: no `data` chunk where the tap header puts it")
+        raw = f.read()
+    # The declared size is patched per flush and a hard kill can leave the file shorter: trust the
+    # bytes present, floored to whole frames.
+    usable = len(raw) - (len(raw) % 8)
+    samples = array("f")
+    samples.frombytes(raw[:usable])
+    if sys.byteorder == "big":
+        samples.byteswap()
+    return rate, samples
+
+
+def db(x):
+    return -math.inf if x <= 1e-12 else 20.0 * math.log10(x)
+
+
+def envelope(rate, samples, window_s, t_from, t_to):
+    """Per-window (t, rms_dbfs, peak_dbfs) over the requested slice."""
+    per_win = max(1, int(rate * window_s)) * 2  # interleaved: 2 samples per frame
+    lo = min(len(samples), int(t_from * rate) * 2)
+    hi = len(samples) if t_to is None else min(len(samples), int(t_to * rate) * 2)
+    out = []
+    for start in range(lo, hi, per_win):
+        chunk = samples[start : min(start + per_win, hi)]
+        if not chunk:
+            break
+        acc = 0.0
+        peak = 0.0
+        for v in chunk:
+            acc += v * v
+            a = abs(v)
+            if a > peak:
+                peak = a
+        out.append((start / 2 / rate, db(math.sqrt(acc / len(chunk))), db(peak)))
+    return out
+
+
+def spans(env, window_s, floor):
+    """Contiguous runs of silence and of sound, as (kind, start, end, duration)."""
+    runs = []
+    for t, rms, _peak in env:
+        kind = "silence" if rms < floor else "sound"
+        if runs and runs[-1][0] == kind:
+            runs[-1][2] = t + window_s
+        else:
+            runs.append([kind, t, t + window_s])
+    return [(k, a, b, b - a) for k, a, b in runs]
+
+
+def bar(rms_dbfs, floor=-72.0, width=40):
+    if rms_dbfs == -math.inf:
+        return ""
+    filled = int(round(max(0.0, (rms_dbfs - floor) / -floor) * width))
+    return "#" * max(0, min(width, filled))
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("wav", help="a $WOW_MIX_TAP capture")
+    ap.add_argument("--window", type=float, default=0.25, help="window seconds (default 0.25)")
+    ap.add_argument("--from", dest="t_from", type=float, default=0.0)
+    ap.add_argument("--to", dest="t_to", type=float, default=None)
+    ap.add_argument("--floor", type=float, default=SILENCE_DBFS, help="silence threshold, dBFS")
+    ap.add_argument("--quiet", action="store_true", help="spans only")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args()
+
+    rate, samples = read_tap(a.wav)
+    total = len(samples) / 2 / rate
+    env = envelope(rate, samples, a.window, a.t_from, a.t_to)
+    runs = spans(env, a.window, a.floor)
+
+    if a.json:
+        json.dump(
+            {
+                "path": a.wav,
+                "sample_rate": rate,
+                "duration_s": total,
+                "window_s": a.window,
+                "floor_dbfs": a.floor,
+                "windows": [
+                    {"t": t, "rms_dbfs": None if r == -math.inf else r,
+                     "peak_dbfs": None if p == -math.inf else p}
+                    for t, r, p in env
+                ],
+                "spans": [{"kind": k, "from": s, "to": e, "secs": d} for k, s, e, d in runs],
+            },
+            sys.stdout,
+            indent=2,
+        )
+        print()
+        return
+
+    print(f"mixsum: {a.wav} — {total:.1f}s stereo float-32 @ {rate} Hz, {a.window*1000:.0f} ms windows")
+    if not a.quiet:
+        for t, rms, peak in env:
+            r = "  -inf" if rms == -math.inf else f"{rms:6.1f}"
+            p = "  -inf" if peak == -math.inf else f"{peak:6.1f}"
+            print(f"  {t:7.2f}s  rms {r}  peak {p}  {bar(rms)}")
+    print(f"\nspans (silence = rms < {a.floor:.0f} dBFS):")
+    for kind, start, end, dur in runs:
+        print(f"  {kind:8}  {start:7.2f}s → {end:7.2f}s   {dur:6.2f}s")
+    holes = [r for r in runs if r[0] == "silence" and r[1] > 0.0]
+    if holes:
+        longest = max(holes, key=lambda r: r[3])
+        print(f"\nlongest interior silence: {longest[3]:.2f}s at {longest[1]:.2f}s")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/pass-span-lint.py b/scripts/pass-span-lint.py
new file mode 100755
index 00000000..87a602ab
--- /dev/null
+++ b/scripts/pass-span-lint.py
@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Refuse a second open `pass_span` on the same render pass (a wgpu validation error on Vulkan).
+
+bevy's `DiagnosticsRecorder::pass_span` is a timestamp pair plus a pipeline-statistics query, and
+wgpu allows one statistics query active at a time: a second `pass_span` on a pass whose span is
+still open is a validation error on backends with `PIPELINE_STATISTICS_QUERY`, which in wgpu 27 is
+Vulkan alone (Metal lacks it; wgpu-hal's DX12 arm has the line commented out). On Metal and DX12
+the nesting is a silent no-op, so no macOS build, test or run sees it.
+
+The shape it refuses, per function: `let g = <recorder>.pass_span(&mut P, …)` followed by another
+`.pass_span(&mut P, …)` before `g.end(&mut P)`. Timestamp-only spans (`time_span`) nest fine and
+are not looked at. Lexical, per file, reset at every `fn`: a span never outlives its function.
+
+Usage:  scripts/pass-span-lint.py [path …]      (default: every crates/**/*.rs)
+Exit:   0 clean, 1 findings.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+OPEN = re.compile(r"\blet\s+(?:mut\s+)?(\w+)\s*=\s*[\w.]+\.pass_span\(\s*&mut\s+(\w+)\s*,")
+ANY_OPEN = re.compile(r"\.pass_span\(\s*&mut\s+(\w+)\s*,")
+END = re.compile(r"\b(\w+)\.end\(\s*&mut\s+(\w+)\s*\)")
+FN = re.compile(r"^\s*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?fn\s+\w+")
+
+
+def lint(path: pathlib.Path) -> list[str]:
+    findings: list[str] = []
+    open_spans: list[tuple[str, str, int]] = []  # (guard, pass, line)
+    for lineno, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        line = raw.split("//", 1)[0]
+        if FN.match(line):
+            open_spans.clear()
+        m = OPEN.search(line)
+        if m:
+            guard, pass_name = m.group(1), m.group(2)
+        else:
+            m = ANY_OPEN.search(line)
+            guard, pass_name = (None, m.group(1)) if m else (None, None)
+        if pass_name is not None:
+            for outer_guard, outer_pass, outer_line in open_spans:
+                if outer_pass == pass_name:
+                    findings.append(
+                        f"{path}:{lineno}: a second pass_span on `{pass_name}` while "
+                        f"`{outer_guard}` (line {outer_line}) is still open — one "
+                        f"pipeline-statistics query at a time"
+                    )
+            if guard is not None:
+                open_spans.append((guard, pass_name, lineno))
+        e = END.search(line)
+        if e:
+            open_spans = [s for s in open_spans if s[0] != e.group(1)]
+    return findings
+
+
+def main() -> int:
+    args = [pathlib.Path(a) for a in sys.argv[1:]] or [pathlib.Path("crates")]
+    files: list[pathlib.Path] = []
+    for a in args:
+        files.extend(sorted(a.rglob("*.rs")) if a.is_dir() else [a])
+    findings = [f for p in files for f in lint(p)]
+    for f in findings:
+        print(f)
+    print(f"pass-span-lint: {'clean' if not findings else f'{len(findings)} finding(s)'} — "
+          f"{len(files)} file(s)")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/probe-identity.sh b/scripts/probe-identity.sh
new file mode 100755
index 00000000..120ced7b
--- /dev/null
+++ b/scripts/probe-identity.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Who a scripted run logs in as; sourced by smoke.sh, cine.sh and summon-live.sh, never run alone.
+#
+# A login kicks whoever holds the account, so there is no default: the checkout's `.probe-identity`
+# (tree root, uncommitted; `WOW_USER=…`, `WOW_PASS=…`, `WOW_CHAR=…`, one per line), else the
+# shell's WOW_USER, WOW_PASS and WOW_CHAR. The client refuses a scripted login on any account but
+# the declared one (`run_mode::account_guard`).
+#
+# `probe_identity <tag> <tree root>` sets PROBE_USER, PROBE_PASS, PROBE_CHAR, PROBE_DECLARED
+# (non-empty when the file supplied them) and PROBE_HOST, PROBE_AUTH_PORT from WOW_HOST (default
+# localhost:3724), and prints the identity it chose; a refusal prints why and returns 1.
+probe_identity() {
+    local tag="$1" root="$2" file="$2/.probe-identity" v ignored=""
+    PROBE_DECLARED=""
+    if [ -f "$file" ]; then
+        PROBE_USER="$(sed -n 's/^WOW_USER=//p' "$file" | head -1)"
+        PROBE_PASS="$(sed -n 's/^WOW_PASS=//p' "$file" | head -1)"
+        PROBE_CHAR="$(sed -n 's/^WOW_CHAR=//p' "$file" | head -1)"
+        if [ -z "$PROBE_USER" ] || [ -z "$PROBE_PASS" ] || [ -z "$PROBE_CHAR" ]; then
+            echo "$tag: REFUSING — $file is missing one of WOW_USER, WOW_PASS, WOW_CHAR"
+            return 1
+        fi
+        PROBE_DECLARED=1
+        for v in WOW_USER WOW_PASS WOW_CHAR; do
+            [ -n "${!v:-}" ] && ignored="$ignored $v"
+        done
+        [ -n "$ignored" ] && echo "$tag: ignoring$ignored — this checkout declares its own account (.probe-identity)"
+        echo "$tag: $PROBE_USER / $PROBE_CHAR (declared by .probe-identity)"
+    else
+        if [ -z "${WOW_USER:-}" ] || [ -z "${WOW_PASS:-}" ] || [ -z "${WOW_CHAR:-}" ]; then
+            echo "$tag: REFUSING — no account to log in as. A scripted run takes WOW_USER, WOW_PASS"
+            echo "       and WOW_CHAR from the environment, all three, or from a .probe-identity file"
+            echo "       at the tree root, naming a test account on your server whose login kicks"
+            echo "       nobody (docs/CONTRIBUTING.md, \"Setting up\")."
+            return 1
+        fi
+        PROBE_USER="$WOW_USER"
+        PROBE_PASS="$WOW_PASS"
+        PROBE_CHAR="$WOW_CHAR"
+        echo "$tag: $PROBE_USER / $PROBE_CHAR (from the environment)"
+    fi
+    # The server: WOW_HOST is `host` or `host:port`, the client's own spelling (realmlist.rs).
+    local host="${WOW_HOST:-localhost}"
+    PROBE_HOST="${host%%:*}"
+    PROBE_AUTH_PORT="${host##*:}"
+    [ "$PROBE_AUTH_PORT" != "$host" ] || PROBE_AUTH_PORT=3724
+    return 0
+}
+
+# `probe_server_or_skip <tag>` prints a skip and returns 1 when the auth port does not answer, or,
+# for a local server, the stock world port 8085; a remote world port comes from its realm list.
+probe_server_or_skip() {
+    local tag="$1" port ports="$PROBE_AUTH_PORT"
+    case "$PROBE_HOST" in localhost | 127.0.0.1) ports="$ports 8085" ;; esac
+    for port in $ports; do
+        if ! (exec 3<>"/dev/tcp/$PROBE_HOST/$port") 2>/dev/null; then
+            echo "$tag: SKIPPED — nothing listening on $PROBE_HOST:$port (auth $PROBE_AUTH_PORT; a local"
+            echo "       vmangos also serves the world on 8085). Start your 1.12.1 server, or point"
+            echo "       WOW_HOST at it."
+            return 1
+        fi
+    done
+    return 0
+}
diff --git a/scripts/smoke.sh b/scripts/smoke.sh
new file mode 100755
index 00000000..737adb88
--- /dev/null
+++ b/scripts/smoke.sh
@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# The clean-run gate: boot the real client, log out, re-enter, walk the realm list, check the log.
+#
+# Needs a server and opens a window for about a minute; gates.sh points at it but does not run it.
+# Logs in as the checkout's `.probe-identity`, else the shell's WOW_USER/WOW_PASS/WOW_CHAR
+# (scripts/probe-identity.sh). WOW_HOST is the server (default localhost), WOW_DATA the install
+# watched for writes (default the tree's WoW link), WOW_BG passes through to the client, and
+# WOW_SMOKE_KEEP=1 keeps the logs.
+#
+#   scripts/smoke.sh
+set -uo pipefail
+
+# Test $PWD's checkout when it is one of this repo, else this file's (the same rule as gates.sh).
+root="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$root" ] || [ ! -f "$root/scripts/smoke.sh" ]; then
+    root="$(cd "$(dirname "$0")/.." && pwd)"
+fi
+cd "$root" || exit 1
+echo "smoke: $root"
+
+# Resolve the account first, then unset every inherited WOW_* the case below does not keep, so
+# each leg runs on the switches it names; WOW_BG is kept because it only changes window stacking.
+. "$root/scripts/probe-identity.sh"
+probe_identity smoke "$root" || exit 1
+user="$PROBE_USER"
+pass="$PROBE_PASS"
+char="$PROBE_CHAR"
+inherited=""
+for v in $(env | sed -n 's/^\(WOW_[A-Za-z0-9_]*\)=.*/\1/p'); do
+    case "$v" in WOW_DATA | WOW_HOST | WOW_BG | WOW_SMOKE_KEEP) continue ;; esac
+    unset "$v"
+    # The account is in $user/$pass/$char now and each leg passes what it needs by name (the realm
+    # leg refuses a WOW_CHAR), so it leaves the environment either way. It was only "ignored"
+    # when the checkout's declared identity took its place.
+    [ -n "$PROBE_DECLARED" ] || case "$v" in WOW_USER | WOW_PASS | WOW_CHAR) continue ;; esac
+    inherited="$inherited $v"
+done
+[ -n "$inherited" ] &&
+    echo "smoke: ignoring inherited env —$inherited (each leg names its own; a gate is not shell-dependent)"
+
+# Check the server before the build: a refused connection would read as a client bug in the log.
+probe_server_or_skip smoke || exit 0
+
+log="$(mktemp "${TMPDIR:-/tmp}/benilla-smoke.XXXXXX")"
+stamp="$(mktemp "${TMPDIR:-/tmp}/benilla-smoke-stamp.XXXXXX")"
+before="$(mktemp "${TMPDIR:-/tmp}/benilla-smoke-before.XXXXXX")"
+# One EXIT trap, so an early `fail` strands no temp file; WOW_SMOKE_KEEP spares the log.
+trap 'rm -f "$stamp" "$before"; [ -n "${WOW_SMOKE_KEEP:-}" ] || rm -f "$log"' EXIT
+
+# The install is read-only: the run must add, remove and modify nothing in it. The sorted file
+# list catches additions and removals, `-newer` against the stamp catches edits in place; plain
+# POSIX `find` because `stat`'s format flag differs between BSD (-f) and GNU (-c).
+install_root=""
+if [ -n "${WOW_DATA:-}" ]; then
+    install_root="$WOW_DATA"
+elif [ -d "$root/WoW" ]; then
+    install_root="$root/WoW"
+fi
+# A running reference client (wow.exe) writes its own WTF files into a shared install, and this
+# watch cannot tell those from benilla's; note it so the verdict can say so.
+reference_client_before=""
+if pgrep -f '[w]ow\.exe' >/dev/null 2>&1; then
+    reference_client_before=1
+fi
+if [ -n "$install_root" ]; then
+    find -L "$install_root" -type f 2>/dev/null | sort >"$before"
+    echo "smoke: install read-only watch on $install_root ($(wc -l <"$before" | tr -d ' ') files)"
+    [ -n "$reference_client_before" ] && \
+        echo "smoke: NOTE — the reference client (wow.exe) is running; the install watch cannot attribute"
+fi
+
+# Build before the timed run: the timeout bounds the client, and a cold build takes minutes.
+if ! cargo build -q -p benilla >"$log" 2>&1; then
+    echo "SMOKE FAILED: the client did not build"
+    sed -E 's/\x1b\[[0-9;]*m//g' "$log" | tail -30
+    exit 1
+fi
+
+echo "smoke: running the logout/re-login round trip (~45 s, opens a window)…"
+# WOW_NOSOUND: the client opens no audio device (`sound/mod.rs`), so the run is silent.
+WOW_UNATTENDED=1 WOW_NOSOUND=1 WOW_USER="$user" WOW_PASS="$pass" WOW_CHAR="$char" WOW_LOGOUT_SMOKE=1 \
+    timeout 180 cargo run -q -p benilla >"$log" 2>&1
+code=$?
+
+# Strip ANSI once: the tracing level is colour-wrapped, and the checks below match plain text.
+plain="$(sed -E 's/\x1b\[[0-9;]*m//g' "$log")"
+
+fail() {
+    echo "SMOKE FAILED: $1"
+    [ -n "${WOW_SMOKE_KEEP:-}" ] && echo "  log: $log"
+    printf '%s\n' "$plain" | tail -30
+    exit 1
+}
+
+# Before the timeout check, which it usually explains: a WOW_CHAR not on the account leaves the
+# client waiting at the roster.
+printf '%s' "$plain" | grep -q "not on this account" &&
+    fail "$char is not on $user — the client sat at the roster (make it, or rig it: WOW_RIG=…)"
+[ $code -eq 124 ] && fail "the client did not exit within the timeout"
+printf '%s' "$plain" | grep -q "logout-smoke: empty roster" &&
+    fail "$user has no characters — the re-entry leg cannot run (make one, or rig it: WOW_RIG=…)"
+printf '%s' "$plain" | grep -q "logout-smoke: done" ||
+    fail "the round trip never completed (no 'logout-smoke: done')"
+
+# The re-entered character must be drivable: the leg lists what would block movement (a /logout
+# root must end with its session), and anything but `none` fails.
+sup="$(printf '%s\n' "$plain" | sed -n 's/.*logout-smoke: re-entered.*suppressors: \(.*\), done.*/\1/p' | tail -1)"
+printf '  %-24s %s\n' "re-entry suppressors" "${sup:-<unreported>}"
+[ "$sup" = "none" ] ||
+    fail "the re-entered character could not be driven — suppressors: ${sup:-<unreported>} \
+(1542: everything the ended session granted its mover dies with it)"
+
+# vmangos skips the logout root when resting, on a taxi or at account security >= `InstantLogout`
+# (`MiscHandler.cpp`, `CMSG_LOGOUT_REQUEST`); probe accounts are GM, so report whether the check
+# above met a real root. `player::wire_in::session_end_tests` forces the rooted case.
+if printf '%s\n' "$plain" | grep -q "mover mode Root granted"; then
+    printf '  %-24s %s\n' "rooted logout" "yes — the drivable check above is a real pass"
+else
+    printf '  %-24s %s\n' "rooted logout" \
+        "no (instant logout: GM probe / resting), so the check above did not run"
+fi
+
+errors="$(printf '%s\n' "$plain" | grep -cE ' ERROR ')"
+panics="$(printf '%s\n' "$plain" | grep -cE 'panicked at')"
+[ "$panics" -ne 0 ] && fail "$panics panic(s)"
+[ "$errors" -ne 0 ] && fail "$errors ERROR line(s)"
+
+# A marker counts once per edge it fires on. Each world entry builds a world VM beside the
+# character screen's glue VM (the reference's `0x490bd0`/`0x48fbf0` pair), so per-VM markers count
+# twice per login; half that means an entry adopted the glue VM and its spent `VmMemo`s.
+sessions=2            # world entries in this walk
+vms=$((sessions * 2)) # …and the Lua states they cost: a glue VM and a world VM each
+for marker in "Fonts.xml loaded"; do
+    n="$(printf '%s\n' "$plain" | grep -cF "$marker")"
+    printf '  %-24s %s\n' "$marker" "$n"
+    [ "$n" -eq "$vms" ] ||
+        fail "'$marker' happened $n time(s), expected $vms — one per VM built, two per login; \
+$sessions would mean the entry adopted the character screen's VM and inherited its spent VmMemos"
+done
+# The in-game UI and the keybinding table (`seed_bindings_for_vm`, run on the world-entry edge)
+# build once per login; one count for two logins means the second reused the first's frame tree.
+for marker in "UIParent.xml loaded" "commands registered"; do
+    n="$(printf '%s\n' "$plain" | grep -cF "$marker")"
+    printf '  %-24s %s\n' "$marker" "$n"
+    [ "$n" -eq "$sessions" ] ||
+        fail "'$marker' happened $n time(s), expected $sessions — once per login: the UI rebuilt per login and the keybinding table seeded on the entry edge"
+done
+
+# The shutdown tail runs once per session: at the /logout, and at the exit, which closes the window
+# as a player does. Counted off the saved-variables line, written only when the UI loaded.
+writes="$(printf '%s\n' "$plain" | grep -cF "saved variables: wrote")"
+printf '  %-24s %s\n' "shutdown writes" "$writes"
+[ "$writes" -eq "$sessions" ] ||
+    fail "the shutdown tail wrote $writes time(s), expected $sessions — a session ended without \
+saving (1528: the quit root must be observed in \`Last\`, after PostUpdate's exit_on_all_closed)"
+
+# The read-only verdict names each changed file, the whole lead to whatever wrote it.
+if [ -n "$install_root" ]; then
+    after="$(mktemp "${TMPDIR:-/tmp}/benilla-smoke-after.XXXXXX")"
+    find -L "$install_root" -type f 2>/dev/null | sort >"$after"
+    appeared="$(comm -13 "$before" "$after")"
+    vanished="$(comm -23 "$before" "$after")"
+    touched="$(find -L "$install_root" -type f -newer "$stamp" 2>/dev/null)"
+    rm -f "$after"
+    if [ -n "$appeared" ] || [ -n "$vanished" ] || [ -n "$touched" ]; then
+        if [ -n "$reference_client_before" ] || pgrep -f '[w]ow\.exe' >/dev/null 2>&1; then
+            echo "SMOKE INCONCLUSIVE: the install changed, but the REFERENCE CLIENT was running."
+            echo "  wow.exe writes its own WTF while it runs, and this watch is a whole-tree mtime"
+            echo "  diff — it cannot tell those writes from benilla's. This is NOT evidence that"
+            echo "  benilla wrote to the install, and it is not evidence that it did not."
+            echo "  Close the reference client and re-run to get a real reading."
+        else
+            echo "SMOKE FAILED: the run WROTE TO THE INSTALL — benilla never does."
+            echo "  Every file benilla persists goes through \`crate::local_state\` into"
+            echo "  \`benilla-config/\` beside the binary."
+        fi
+        [ -n "$appeared" ] && { echo "  added:"; printf '%s\n' "$appeared" | sed 's/^/    /'; }
+        [ -n "$vanished" ] && { echo "  removed:"; printf '%s\n' "$vanished" | sed 's/^/    /'; }
+        [ -n "$touched" ] && { echo "  modified:"; printf '%s\n' "$touched" | sed 's/^/    /'; }
+        exit 1
+    fi
+    echo "  install untouched         $(wc -l <"$before" | tr -d ' ') files"
+else
+    echo "  install                   not watched (no WoW link and no WOW_DATA — the read-only rule went unmeasured)"
+fi
+
+# ── The realm-list leg ───────────────────────────────────────────────────────────────────────
+# The realm list is a dialog over character select that the IO thread serves from the character
+# park; this drives Change Realm, Okay, Change Realm, Cancel, Okay against the real server and
+# fails anything but a completed walk.
+echo "smoke: running the realm-list boundary walk (~12 s, opens a window)…"
+rlog="$(mktemp "${TMPDIR:-/tmp}/benilla-smoke-realm.XXXXXX")"
+# No WOW_CHAR: the walk drives character select, and `realm_select::smoke` refuses a seated body.
+WOW_UNATTENDED=1 WOW_NOSOUND=1 WOW_USER="$user" WOW_PASS="$pass" WOW_REALM_SMOKE=1 \
+    timeout 120 cargo run -q -p benilla >"$rlog" 2>&1
+rcode=$?
+rplain="$(sed -E 's/\x1b\[[0-9;]*m//g' "$rlog")"
+[ -n "${WOW_SMOKE_KEEP:-}" ] || rm -f "$rlog"
+realm_fail() {
+    echo "SMOKE FAILED (realm leg): $1"
+    [ -n "${WOW_SMOKE_KEEP:-}" ] && echo "  log: $rlog"
+    printf '%s\n' "$rplain" | tail -30
+    exit 1
+}
+[ $rcode -eq 124 ] && realm_fail "the realm walk did not finish within the timeout"
+printf '%s' "$rplain" | grep -q "realm-smoke: FAILED" &&
+    realm_fail "$(printf '%s\n' "$rplain" | sed -n 's/.*realm-smoke: FAILED — //p' | tail -1)"
+printf '%s' "$rplain" | grep -q "realm-smoke: done" ||
+    realm_fail "the walk never completed (no 'realm-smoke: done')"
+rp="$(printf '%s\n' "$rplain" | grep -cE 'panicked at')"
+[ "$rp" -ne 0 ] && realm_fail "$rp panic(s)"
+printf '  %-24s %s\n' "realm walk" \
+    "$(printf '%s\n' "$rplain" | sed -n 's/.*realm-smoke: done — //p' | tail -1)"
+
+echo "SMOKE GREEN — ${sessions} logins + the realm walk, 0 errors, 0 panics$([ -n "$install_root" ] && echo ', install untouched')"
+[ -n "${WOW_SMOKE_KEEP:-}" ] && echo "log: $log"
+exit 0
diff --git a/scripts/soundprobe.py b/scripts/soundprobe.py
new file mode 100755
index 00000000..64dd984c
--- /dev/null
+++ b/scripts/soundprobe.py
@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""Read back a `$WOW_SOUND_PROBE` capture and name the mechanism behind a speaker-breaking sound.
+
+A measuring run leaves `pre.wav` (the mix as the game asked for it), `post.wav` (what was heard)
+and `timeline.jsonl` (levels, voices, deadline misses, kit starts and F9 marks, keyed to the
+sample offset in `pre.wav`). Only comparing the two WAVs with each other and with the timeline
+tells the mechanisms apart:
+
+    over-scale sum ............ pre past 1.0, post clean, gain well under 1
+    limiter not engaging ...... pre and post both past 1.0
+    underrun / missed deadline  both clean; `load>=1`, overruns, block-aligned steps in post
+    starved stream decoder .... both clean; hard steps to zero in post
+    non-finite samples ........ NaN/inf anywhere, invisible to every level meter
+    voice refusal ............. `refused` climbing near the mark
+    the limiter's own pumping . post clean but gain diving repeatedly
+
+Usage:
+    scripts/soundprobe.py                       # the default benilla-config/sound-probe
+    scripts/soundprobe.py <dir>                 # a capture directory
+    scripts/soundprobe.py <dir> --around 2.0    # widen the window read around each mark
+    scripts/soundprobe.py <dir> --json
+
+Pure stdlib, so it runs without installing anything. Windowed reductions use `max`/`min` on array
+slices so the hot loop stays in C; the per-sample passes run only near the marks.
+"""
+
+import argparse
+import json
+import math
+import os
+import struct
+import sys
+from array import array
+
+# A sample this close to full scale was clipped: below the renderer's 1.0 clamp, above the
+# limiter's 0.99 ceiling, so a limiter riding its ceiling reads as held, not clipped.
+CLIPPED = 0.999
+# Envelope resolution: 10 ms keeps a ten-minute capture to ~60 000 windows.
+WINDOW = 0.010
+# A sample-to-sample jump this large is not music: a zero-fill, a cut or a stepped parameter,
+# which no level meter sees.
+STEP = 0.30
+# kira's internal block: a step on a multiple of it is a block-level failure (a starved decoder
+# zero-filling a whole chunk), not a one-off click.
+BLOCK = 128
+
+
+def read_wav(path):
+    """(rate, interleaved float32 array). Tolerates the tap's crash-safe truncated tail."""
+    with open(path, "rb") as f:
+        head = f.read(44)
+        if len(head) < 44 or head[0:4] != b"RIFF" or head[8:12] != b"WAVE":
+            sys.exit(f"soundprobe: {path} is not a RIFF/WAVE file")
+        fmt, channels, rate, _br, _al, bits = struct.unpack("<HHIIHH", head[20:36])
+        if (fmt, channels, bits) != (3, 2, 32):
+            sys.exit(f"soundprobe: expected stereo float-32, got fmt={fmt} ch={channels} bits={bits}")
+        raw = f.read()
+    usable = len(raw) - (len(raw) % 8)
+    s = array("f")
+    s.frombytes(raw[:usable])
+    if sys.byteorder == "big":
+        s.byteswap()
+    return rate, s
+
+
+def envelope(samples, rate, window=WINDOW):
+    """Per-window peak |sample|, plus the count of clipped and non-finite samples in each."""
+    step = max(1, int(rate * window)) * 2
+    out = []
+    for i in range(0, len(samples), step):
+        seg = samples[i : i + step]
+        if not seg:
+            break
+        # Finiteness via a sum, not `max`/`min`: a comparison with NaN is false, so `max` can skip
+        # a NaN depending on where it sits, while a sum always propagates it.
+        if not math.isfinite(sum(seg)):
+            nf = sum(1 for v in seg if not math.isfinite(v))
+            finite = [v for v in seg if math.isfinite(v)]
+            peak = max(max(finite), -min(finite)) if finite else 0.0
+        else:
+            nf = 0
+            peak = max(max(seg), -min(seg))
+        clipped = sum(1 for v in seg if abs(v) >= CLIPPED) if peak >= CLIPPED else 0
+        out.append((i / 2 / rate, peak, clipped, nf))
+    return out
+
+
+def brightness(samples, rate, lo, hi):
+    """A crude high-frequency energy ratio for [lo,hi): `sum((x[n]-x[n-1])^2) / sum(x[n]^2)`.
+
+    A one-tap difference filter, not a spectrum: it rises with distortion of any origin and stays
+    flat for content that only got louder. Meaningful only against the same capture's baseline.
+    """
+    a, b = max(0, int(lo * rate)) * 2, min(len(samples), int(hi * rate) * 2)
+    num = den = 0.0
+    for ch in (0, 1):
+        prev = None
+        for i in range(a + ch, b, 2):
+            v = samples[i]
+            if v != v:
+                prev = None
+                continue
+            if prev is not None:
+                num += (v - prev) * (v - prev)
+            den += v * v
+            prev = v
+    return num / den if den > 1e-12 else 0.0
+
+
+def steps(samples, rate, lo, hi):
+    """Sample-to-sample discontinuities in [lo,hi) seconds: (time, jump, block_aligned)."""
+    a, b = max(0, int(lo * rate)) * 2, min(len(samples), int(hi * rate) * 2)
+    found = []
+    for ch in (0, 1):
+        prev = None
+        for i in range(a + ch, b, 2):
+            v = samples[i]
+            if prev is not None and v == v and prev == prev:
+                d = abs(v - prev)
+                if d >= STEP:
+                    frame = i // 2
+                    found.append((frame / rate, d, frame % BLOCK == 0))
+            prev = v
+    found.sort(key=lambda t: -t[1])
+    return found
+
+
+def load_timeline(path):
+    rows = []
+    if not os.path.exists(path):
+        return rows
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    rows.append(json.loads(line))
+                except json.JSONDecodeError:
+                    pass
+    return rows
+
+
+def db(x):
+    return -math.inf if x <= 0 else 20 * math.log10(x)
+
+
+def span(rows, kind, lo, hi, key=None):
+    """Rows of `kind` whose audio time falls in [lo,hi)."""
+    return [r for r in rows if r.get("ev") == kind and lo <= r.get("_at", -1) < hi]
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("dir", nargs="?", default=None)
+    ap.add_argument("--around", type=float, default=1.5, help="seconds either side of a mark")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args()
+
+    d = args.dir
+    if d is None:
+        for guess in ("benilla-config/sound-probe", "../benilla-config/sound-probe"):
+            if os.path.isdir(guess):
+                d = guess
+                break
+    if d is None or not os.path.isdir(d):
+        sys.exit("soundprobe: no capture directory — pass one (see WOW_SOUND_PROBE)")
+
+    pre_p, post_p = os.path.join(d, "pre.wav"), os.path.join(d, "post.wav")
+    if not os.path.exists(pre_p):
+        sys.exit(f"soundprobe: {pre_p} missing — was the run started with WOW_SOUND_PROBE=1?")
+    rate, pre = read_wav(pre_p)
+    _, post = read_wav(post_p) if os.path.exists(post_p) else (rate, array("f"))
+    rows = load_timeline(os.path.join(d, "timeline.jsonl"))
+    for r in rows:
+        r["_at"] = r.get("a", 0) / rate
+
+    pre_env, post_env = envelope(pre, rate), envelope(post, rate)
+    dur = len(pre) / 2 / rate
+    pre_peak = max((w[1] for w in pre_env), default=0.0)
+    post_peak = max((w[1] for w in post_env), default=0.0)
+    pre_clip = sum(w[2] for w in pre_env)
+    post_clip = sum(w[2] for w in post_env)
+    pre_nf = sum(w[3] for w in pre_env)
+    post_nf = sum(w[3] for w in post_env)
+    ticks = [r for r in rows if r.get("ev") == "tick"]
+    overruns = sum(r.get("overruns", 0) for r in ticks)
+    refused = sum(r.get("refused", 0) for r in ticks)
+    errors = sum(r.get("errors", 0) for r in ticks)
+    max_load = max((r.get("load", 0.0) for r in ticks), default=0.0)
+    max_voices = max((r.get("voices", 0) for r in ticks), default=0)
+    min_gain = min((r.get("gain", 1.0) for r in ticks), default=1.0)
+    marks = [r for r in rows if r.get("ev") == "mark"]
+
+    # The brightness baseline: the median of windows spread across this capture.
+    base = []
+    if dur > 1.0:
+        for k in range(1, 12):
+            t0 = dur * k / 12.0
+            b = brightness(post, rate, t0, min(dur, t0 + 0.25))
+            if b > 0:
+                base.append(b)
+    base.sort()
+    baseline = base[len(base) // 2] if base else 0.0
+
+    # ---- the verdict -----------------------------------------------------------------------
+    verdicts = []
+    if pre_nf or post_nf:
+        verdicts.append(
+            f"NON-FINITE SAMPLES — {pre_nf} pre, {post_nf} post. A NaN/inf is invisible to every "
+            "level meter and passes the limiter's own test untouched. This is a defect upstream "
+            "of the output and is almost certainly what you heard."
+        )
+    if post_clip:
+        verdicts.append(
+            f"THE LIMITER IS NOT HOLDING — {post_clip} clipped sample(s) in what was actually "
+            f"heard (post peak {post_peak:.3f}). It is installed but something is getting past it."
+        )
+    elif pre_clip:
+        verdicts.append(
+            f"over-scale sum, caught — the mix asked for {pre_peak:.2f}x full scale "
+            f"({db(pre_peak):+.1f} dBFS) and the output stayed clean (peak {post_peak:.3f}). "
+            "The limiter is engaging and holding the output."
+        )
+    if overruns:
+        verdicts.append(
+            f"UNDERRUNS — {overruns} missed mix deadline(s), peak load {max_load*100:.0f}% of "
+            "budget. This is audible as a crack and no limiter can touch it."
+        )
+    if errors:
+        verdicts.append(f"STREAM ERRORS — {errors} reported by the device layer.")
+    if refused:
+        verdicts.append(f"{refused} sound(s) refused — the voice arena filled.")
+    if min_gain < 0.5 and not pre_clip:
+        verdicts.append(
+            f"LIMITER PUMPING WITHOUT CAUSE — gain dove to {min_gain:.2f} ({db(min_gain):+.1f} dB) "
+            "with nothing over full scale. The fix would then be the complaint; try "
+            "`SoundOutputLimiter 0`."
+        )
+    if not verdicts:
+        verdicts.append(
+            "Nothing anomalous in levels, deadlines or finiteness. If you heard it in this "
+            "capture, the mechanism is in the waveform's content — check the marks below for "
+            "steps, and listen to post.wav at those offsets."
+        )
+
+    if args.json:
+        print(json.dumps({
+            "dir": d, "rate": rate, "duration": dur,
+            "pre": {"peak": pre_peak, "clipped": pre_clip, "nonfinite": pre_nf},
+            "post": {"peak": post_peak, "clipped": post_clip, "nonfinite": post_nf},
+            "overruns": overruns, "refused": refused, "errors": errors,
+            "max_load": max_load, "max_voices": max_voices, "min_gain": min_gain,
+            "marks": [r["_at"] for r in marks], "verdicts": verdicts,
+        }, indent=2))
+        return
+
+    print(f"\n  capture   {d}   {dur:.1f}s @ {rate} Hz")
+    print(f"  asked for peak {pre_peak:7.3f} ({db(pre_peak):+6.1f} dBFS)  clipped {pre_clip:>8}  nan {pre_nf}")
+    print(f"  heard     peak {post_peak:7.3f} ({db(post_peak):+6.1f} dBFS)  clipped {post_clip:>8}  nan {post_nf}")
+    print(f"  limiter   deepest gain {min_gain:.3f} ({db(min_gain):+.1f} dB)")
+    print(f"  health    overruns {overruns}   refused {refused}   stream errors {errors}"
+          f"   peak load {max_load*100:.0f}%   peak voices {max_voices}")
+    print("\n  VERDICT")
+    for v in verdicts:
+        print(f"    • {v}")
+
+    if not marks:
+        print("\n  No F9 marks in this capture. The worst moments by level:")
+        for t, pk, cl, _nf in sorted(pre_env, key=lambda w: -w[1])[:5]:
+            print(f"    {t:8.2f}s  asked {pk:.2f}x  clipped {cl}")
+        print()
+        return
+
+    print(f"\n  {len(marks)} MARK(S) — what was happening when you pressed F9\n")
+    for m in marks:
+        at = m["_at"]
+        lo, hi = max(0.0, at - args.around), at + args.around
+        pw = [w for w in pre_env if lo <= w[0] < hi]
+        qw = [w for w in post_env if lo <= w[0] < hi]
+        t = [r for r in ticks if lo <= r["_at"] < hi]
+        st = steps(post, rate, lo, hi)[:3]
+        plays = span(rows, "play", lo, hi)
+        print(f"  ── mark {m.get('n')} at {at:.2f}s " + "─" * 46)
+        print(f"     asked  peak {max((w[1] for w in pw), default=0):.3f}   clipped {sum(w[2] for w in pw)}")
+        print(f"     heard  peak {max((w[1] for w in qw), default=0):.3f}   clipped {sum(w[2] for w in qw)}")
+        print(f"     gain   {min((r.get('gain',1.0) for r in t), default=1.0):.3f}"
+              f"   voices {max((r.get('voices',0) for r in t), default=0)}"
+              f"   load {max((r.get('load',0.0) for r in t), default=0)*100:.0f}%"
+              f"   overruns {sum(r.get('overruns',0) for r in t)}"
+              f"   refused {sum(r.get('refused',0) for r in t)}")
+        harsh = brightness(post, rate, lo, hi)
+        if baseline > 0:
+            ratio = harsh / baseline
+            verdict = (
+                "MUCH harsher than this capture's norm — distortion of some kind"
+                if ratio >= 2.5
+                else "harsher than usual" if ratio >= 1.5
+                else "no harsher than usual — this moment was loud, not dirty"
+            )
+            print(f"     harsh  {harsh:.3f} vs baseline {baseline:.3f} ({ratio:.1f}x) — {verdict}")
+        if st:
+            worst = ", ".join(
+                f"{d_:.2f} at {ts:.3f}s{' [block-aligned]' if al else ''}" for ts, d_, al in st
+            )
+            print(f"     STEPS  {worst}")
+            if any(al for _, _, al in st):
+                print("            block-aligned → a starved decoder or a zero-filled chunk,")
+                print("            not a level problem. The limiter is irrelevant to this.")
+        else:
+            print("     steps  none above threshold — the waveform is continuous here")
+        if plays:
+            names = {}
+            for p in plays:
+                names[p.get("name", "?")] = names.get(p.get("name", "?"), 0) + 1
+            top = sorted(names.items(), key=lambda kv: -kv[1])[:6]
+            print(f"     sounds {len(plays)} started: " + ", ".join(f"{n}×{c}" for n, c in top))
+        print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/soundprobe.sh b/scripts/soundprobe.sh
new file mode 100755
index 00000000..45a8b195
--- /dev/null
+++ b/scripts/soundprobe.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Start the client in sound measuring mode: record the mix before and after the output limiter.
+#
+#   scripts/soundprobe.sh [client args…]   # play normally, press F9 when you hear it
+#   scripts/soundprobe.py                  # …then read the capture back
+#
+# Builds the `play` profile: a debug build stutters, and a stutter is a missed mix deadline, one of
+# the mechanisms the capture has to tell apart.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+cat <<'BANNER'
+
+  ── benilla · sound measuring mode ─────────────────────────────────────────
+    Recording two mixes at once: what the game ASKED for (before the limiter)
+    and what you actually HEARD (after it). One file cannot tell those apart;
+    two can, and that is the whole question.
+
+    ▶ PRESS F9 THE MOMENT YOU HEAR IT.
+      That stamps the exact sample. Without a mark I am scanning ten minutes
+      of audio guessing which second you meant; with one I read outward from
+      it. Press it every time — several marks is much better than one.
+
+    Then quit the client normally and run:  scripts/soundprobe.py
+  ───────────────────────────────────────────────────────────────────────────
+
+BANNER
+
+exec env WOW_SOUND_PROBE=1 cargo run -q --profile play -p benilla "$@"
diff --git a/scripts/summon-live.sh b/scripts/summon-live.sh
new file mode 100755
index 00000000..2acc97e1
--- /dev/null
+++ b/scripts/summon-live.sh
@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# Two-client live summon probe: a second account summons this checkout's character, which accepts.
+#
+# Both vmangos summon-request callers skip the caster (`Spell::EffectSummonPlayer`,
+# `HandleGroupSummonCommand`), so a second client summons. The summoner is SUMMON_USER/
+# SUMMON_PASS/SUMMON_CHAR, a GM test account whose login kicks nobody; the receiver is
+# `.probe-identity`, else WOW_USER/WOW_PASS/WOW_CHAR. WOW_HOST is the server, SUMMON_LIVE_KEEP=1
+# keeps the logs.
+#
+#   SUMMON_USER=… SUMMON_PASS=… SUMMON_CHAR=… scripts/summon-live.sh   # ~90 s, two small windows
+set -uo pipefail
+
+root="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$root" ] && [ -f "$root/scripts/summon-live.sh" ] || root="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$root" || exit 1
+echo "summon-live: $root"
+
+# The receiver logs in as this checkout's identity: a login kicks whoever holds the account.
+. "$root/scripts/probe-identity.sh"
+probe_identity summon-live "$root" || exit 1
+rx_user="$PROBE_USER"; rx_pass="$PROBE_PASS"; rx_char="$PROBE_CHAR"
+
+if [ -z "${SUMMON_USER:-}" ] || [ -z "${SUMMON_PASS:-}" ] || [ -z "${SUMMON_CHAR:-}" ]; then
+    echo "summon-live: REFUSING — the summoner needs a second account: SUMMON_USER, SUMMON_PASS"
+    echo "             and SUMMON_CHAR, a GM-level test account whose login kicks nobody."
+    exit 1
+fi
+tx_user="$SUMMON_USER"; tx_pass="$SUMMON_PASS"; tx_char="$SUMMON_CHAR"
+echo "summon-live: $tx_char ($tx_user) summons $rx_char ($rx_user)"
+
+probe_server_or_skip summon-live || exit 0
+
+# Build first so both clients start together: the probe timings count from process start.
+echo "summon-live: building…"
+cargo build -q -p benilla || { echo "summon-live: the client did not build"; exit 1; }
+
+work="$(mktemp -d "${TMPDIR:-/tmp}/benilla-summon.XXXXXX")"
+trap '[ -n "${SUMMON_LIVE_KEEP:-}" ] || rm -rf "$work"' EXIT
+
+# The receiver's Lua: `tostring` on every getter, so a missing dialog reports instead of raising.
+read -r -d '' chunk <<'LUA'
+ProbeLog("dialog visible=" .. tostring(StaticPopup1:IsVisible()))
+ProbeLog("dialog text=[" .. tostring(StaticPopup1Text:GetText()) .. "]")
+ProbeLog("summoner=[" .. tostring(GetSummonConfirmSummoner()) .. "]")
+ProbeLog("area=[" .. tostring(GetSummonConfirmAreaName()) .. "]")
+ProbeLog("timeleft=" .. tostring(GetSummonConfirmTimeLeft()))
+ProbeLog("zone before=[" .. GetZoneText() .. "]")
+StaticPopup_OnClick(StaticPopup1, 1)
+ProbeLog("accept pressed; dialog visible=" .. tostring(StaticPopup1:IsVisible()))
+-- The teleport is OBSERVED, not assumed: a frame that re-reads the zone ten seconds after the
+-- Accept, which is the only thing that distinguishes "we sent the packet" from "we were summoned".
+local watch = CreateFrame("Frame")
+watch.t = 0
+watch:SetScript("OnUpdate", function()
+    this.t = this.t + arg1
+    if this.t > 10 and not this.said then
+        this.said = 1
+        ProbeLog("zone after=[" .. GetZoneText() .. "]")
+    end
+end)
+LUA
+
+echo "summon-live: running (~90 s, opens two windows)…"
+# The receiver parks in Stormwind first: a green run leaves it at the destination, and the
+# before/after zone compare needs the same "before" on every run.
+WOW_UNATTENDED=1 WOW_NOSOUND=1 WOW_USER="$rx_user" WOW_PASS="$rx_pass" WOW_CHAR="$rx_char" \
+    WOW_PROBE=partner \
+    WOW_PROBE_CHAT=".go xyz -8913 554 94" WOW_PROBE_CHAT_AT=10 \
+    WOW_PROBE_LUA="$chunk" WOW_PROBE_LUA_AT=34 \
+    WOW_PROBE_EXIT_AT=62 \
+    WOW_MOVE_TRACE="$work/rx.trace" WOW_MOVE_TRACE_TAGS=summon \
+    timeout 150 cargo run -q -p benilla >"$work/rx.log" 2>&1 &
+rx=$!
+
+# WOW_ALLOW_ACCOUNT=1 lifts the account guard for the shell-named summoner. `.group summon`, not
+# `.summon`, because `.summon` teleports without asking.
+WOW_UNATTENDED=1 WOW_NOSOUND=1 WOW_USER="$tx_user" WOW_PASS="$tx_pass" WOW_CHAR="$tx_char" WOW_ALLOW_ACCOUNT=1 \
+    WOW_PROBE_CHAT="/invite $rx_char;.group summon" \
+    WOW_PROBE_CHAT_AT=18 WOW_PROBE_CHAT_EVERY=10 \
+    WOW_PROBE_EXIT_AT=62 \
+    timeout 150 cargo run -q -p benilla >"$work/tx.log" 2>&1 &
+tx=$!
+
+wait $rx; rx_code=$?
+wait $tx; tx_code=$?
+
+strip() { sed -E 's/\x1b\[[0-9;]*m//g' "$1"; }
+trace="$(cat "$work/rx.trace" 2>/dev/null)"
+plog="$(strip "$work/rx.log" | sed -n 's/.*probe-log: //p')"
+
+echo
+echo "── the summoner"
+strip "$work/tx.log" | grep -E "probe-chat: sending|server says —|REFUSING" | sed 's/^.*INFO [^:]*: //'
+echo
+echo "── the receiver: the three links"
+printf '%s\n' "$trace"
+echo
+echo "── the receiver: what the dialog said"
+printf '%s\n' "$plog"
+
+fail() { echo; echo "SUMMON-LIVE FAILED: $1"; strip "$work/rx.log" | grep -E "ERROR" | tail -10; exit 1; }
+[ $rx_code -eq 124 ] && fail "the receiver did not exit within the timeout"
+[ $tx_code -eq 124 ] && fail "the summoner did not exit within the timeout"
+printf '%s' "$trace" | grep -q "recv SMSG_SUMMON_REQUEST" ||
+    fail "no summon request arrived — did the invite land? (see the summoner's lines above)"
+printf '%s' "$trace" | grep -q "fire CONFIRM_SUMMON" || fail "the request landed but no event fired"
+printf '%s' "$trace" | grep -q "SEND CMSG_SUMMON_RESPONSE" || fail "Accept sent no packet"
+printf '%s' "$plog" | grep -q "wants to summon you to" || fail "the dialog text never composed"
+# The character must move, and land where the dialog said: that ties GetSummonConfirmAreaName to
+# the server rather than to our own AreaTable lookup.
+before="$(printf '%s' "$plog" | sed -n 's/^zone before=\[\(.*\)\]$/\1/p')"
+after="$(printf '%s' "$plog" | sed -n 's/^zone after=\[\(.*\)\]$/\1/p')"
+area="$(printf '%s' "$plog" | sed -n 's/^area=\[\(.*\)\]$/\1/p')"
+[ -n "$after" ] || fail "the receiver never re-read its zone (the teleport went unobserved)"
+[ "$before" != "$after" ] ||
+    fail "the packet went out but the character never moved (still in $before) — if before and \
+after are BOTH the destination, the park at the top of the run did not take"
+[ "$after" = "$area" ] ||
+    fail "the dialog promised $area and the character landed in $after"
+
+echo
+echo "SUMMON-LIVE GREEN — asked, shown, accepted, and moved: $before → $after (the dialog's own $area)"
+[ -n "${SUMMON_LIVE_KEEP:-}" ] && echo "  logs: $work"
+exit 0
diff --git a/scripts/visual.sh b/scripts/visual.sh
new file mode 100755
index 00000000..b39332f5
--- /dev/null
+++ b/scripts/visual.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Visual A/B harness: capture deterministic screenshots and diff them against a baseline.
+#
+# One client process per scenario: server-less, clutter off, a pinned camera, a fixed game clock and
+# frame step (the `capture` module); `benilla-visual` diffs the PNGs. Opens a real window. Captures
+# hold Blizzard-derived imagery, so they stay under the gitignored target/visual/.
+#
+#   scripts/visual.sh list                  # print scenario names
+#   scripts/visual.sh capture <dir>         # capture every scenario into <dir>/
+#   scripts/visual.sh baseline              # capture into target/visual/baseline/
+#   scripts/visual.sh diff [--fail <mae>]   # capture target/visual/candidate/, diff vs baseline/
+#   scripts/visual.sh selfcheck [<mae>]     # capture twice from one build; demand identical
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+VIS=target/visual
+
+build() { cargo build -q -p benilla -p benilla-visual; }
+
+# The binary owns the scenario list (`capture/mod.rs`) and prints it under WOW_CAPTURE=list.
+scenarios() { WOW_CAPTURE=list cargo run -q -p benilla; }
+
+capture_into() {
+  local dir="$1"
+  mkdir -p "$dir"
+  local s
+  for s in $(scenarios); do
+    echo "capture $s -> $dir/$s.png"
+    WOW_CAPTURE="$s" WOW_CAPTURE_OUT="$dir/$s.png" cargo run -q -p benilla
+  done
+}
+
+cmd="${1:-}"
+case "$cmd" in
+  list)
+    build
+    scenarios
+    ;;
+  capture)
+    build
+    capture_into "${2:?usage: visual.sh capture <dir>}"
+    ;;
+  baseline)
+    build
+    capture_into "$VIS/baseline"
+    echo "baseline written to $VIS/baseline"
+    ;;
+  diff)
+    shift
+    build
+    capture_into "$VIS/candidate"
+    echo "--- diff candidate vs baseline ---"
+    ./target/debug/benilla-visual diff-dir "$VIS/baseline" "$VIS/candidate" --out "$VIS/diff" "$@"
+    ;;
+  selfcheck) # selfcheck [<mae>] — the tolerance defaults to 0 (bit-identical)
+    # A diff is evidence only if capture is deterministic: two sweeps from one build must match bit
+    # for bit. Run it after touching anything the capture clock feeds.
+    build
+    capture_into "$VIS/self-a"
+    capture_into "$VIS/self-b"
+    echo "--- selfcheck: self-a vs self-b, one build, two runs ---"
+    # Keep the bar at 0 and add no waits: a nonzero result is a harness regression or a renderer
+    # defect, such as draw order following spawn order, which varies with thread-pool asset loads.
+    ./target/debug/benilla-visual diff-dir "$VIS/self-a" "$VIS/self-b" --out "$VIS/self-diff" \
+      --fail "${2:-0}"
+    echo "selfcheck OK — the harness clock is a pure function of the build"
+    ;;
+  *)
+    echo "usage: visual.sh {list | capture <dir> | baseline | diff [--fail <mae>] | selfcheck}" >&2
+    exit 1
+    ;;
+esac
diff --git a/scripts/vplsum.py b/scripts/vplsum.py
new file mode 100755
index 00000000..d7fa0a76
--- /dev/null
+++ b/scripts/vplsum.py
@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Read a `vpl`/`bub` overlay trace and say where the motion came from: projection, solve or snap.
+
+    # walk a town with friendly plates on, tracing one line per plate per frame
+    WOW_WIN=1440x810 WOW_NOSOUND=1 WOW_GM=off \
+      WOW_UNATTENDED=1 WOW_USER=probeN WOW_PASS=pprobeN WOW_CHAR=Probe<n> \
+      WOW_PROBE_CHAT=".go xyz -9465 74 58 0" WOW_PROBE_CHAT_AT=10 \
+      WOW_PROBE_KEY="Shift@20:3;V@20.5:0.2;W@24:8" \
+      WOW_MOVE_TRACE=/tmp/vpl.trace WOW_MOVE_TRACE_TAGS=vpl \
+      WOW_PROBE_EXIT_AT=34 cargo run -q -p benilla
+    python3 scripts/vplsum.py /tmp/vpl.trace --from 24 --to 32     # the walk leg only
+
+Jitter in a moving overlay has four causes the eye cannot tell apart: a noisy camera, a stale
+anchor, the anti-overlap solve relocating a plate, or the pixel snap quantizing its glide. Every
+`vpl` line carries the world anchor, the camera pose, the raw projected point, the solved rect and
+the snapped rect, so telling them apart is arithmetic.
+
+Read it in this order:
+
+* projection smoothness: the raw projected point's frame-to-frame acceleration, per unit; small
+  (~0.05 px at 60 fps) clears the camera and the anchor.
+* off-screen: plates drawn for a unit that is not on screen. Must be 0.
+* solve jumps: a plate moving further than its own projection did; some is the reference's own
+  anti-overlap bounce, hundreds of pixels in a frame is a defect.
+* snap: the pixel snap's extra per-frame displacement, at most half a device pixel; more means
+  the snap is on the wrong grid.
+
+Pick one leg with `--from`/`--to`: a run is a login, a teleport, a stand and a walk, and their
+average describes none of them.
+
+It reads the chat bubble's `bub` lines too, detected from the file: same projector and
+`overhead_anchor` as the plate but no anti-overlap solver, so there is no `solved=` stage and the
+SOLVE section is skipped. The ANCHOR section matters most for it, because the bubble rides the
+posed head attachment, which bobs with the run cycle:
+
+    WOW_MOVE_TRACE=/tmp/bub.trace WOW_MOVE_TRACE_TAGS=bub \
+      WOW_PROBE_CHAT="hello" WOW_PROBE_CHAT_AT=20 WOW_PROBE_KEY="W@20:6" ... cargo run -q -p benilla
+    python3 scripts/vplsum.py /tmp/bub.trace --from 20 --to 26
+"""
+
+import argparse
+import re
+import sys
+from collections import defaultdict
+
+# One regex for both overlays: `solved=` (the plate's anti-overlap solve) is optional, and the
+# final rect is `plate=` or `frame=`.
+LINE = re.compile(
+    r"t=\s*([\d.]+) (vpl|bub)\s+e=(\d+) vp=\((\d+),(\d+)\) anchor=\[([-\d.,e]+)\] "
+    r"cam=\[([-\d.,e]+)\] fwd=\[([-\d.,e]+)\] scr=\(([-\d.e]+),([-\d.e]+)\) "
+    r"(?:solved=\(([-\d.e]+),([-\d.e]+)\) )?(?:plate|frame)=\(([-\d.e]+),([-\d.e]+)\)"
+)
+
+# A step this far past the plate's own projected motion is a jump, not a glide: about a quarter of
+# the plate's height, the smallest relocation a viewer reads as the plate moving by itself.
+JUMP_PX = 4.0
+# Frames further apart than this are a gap (the plate blinked out), never differenced.
+GAP_S = 0.1
+
+
+def vec3(s):
+    return [float(v) for v in s.split(",")]
+
+
+def load(path, lo, hi):
+    """-> (tag, viewport, {entity: [(t, anchor, cam, scr, solved, rect)]}, {t: overlay count})
+
+    A bubble line has no solver stage, so its `solved` slot mirrors the raw point.
+    """
+    rows, frames, vp, tag = defaultdict(list), defaultdict(int), None, None
+    for line in open(path):
+        m = LINE.match(line)
+        if not m:
+            continue
+        t = float(m.group(1))
+        if not (lo <= t <= hi):
+            continue
+        tag = m.group(2)
+        vp = (float(m.group(4)), float(m.group(5)))
+        frames[t] += 1
+        scr = (float(m.group(9)), float(m.group(10)))
+        solved = (
+            (float(m.group(11)), float(m.group(12)))
+            if m.group(11) is not None
+            else scr
+        )
+        rows[int(m.group(3))].append(
+            (
+                t,
+                vec3(m.group(6)),
+                vec3(m.group(7)),
+                scr,
+                solved,
+                (float(m.group(13)), float(m.group(14))),
+            )
+        )
+    for s in rows.values():
+        s.sort()
+    return tag, vp, rows, frames
+
+
+def stat(vals, fmt="{:6.3f}"):
+    if not vals:
+        return "     —"
+    v = sorted(abs(x) for x in vals)
+    return " ".join(
+        fmt.format(x) for x in (v[len(v) // 2], v[int(0.9 * (len(v) - 1))], v[-1])
+    )
+
+
+def on_screen(p, vp):
+    return 0.0 <= p[0] <= vp[0] and 0.0 <= p[1] <= vp[1]
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("trace")
+    ap.add_argument("--from", dest="lo", type=float, default=0.0)
+    ap.add_argument("--to", dest="hi", type=float, default=1e9)
+    ap.add_argument("--worst", type=int, default=10, help="how many jumps to name")
+    a = ap.parse_args()
+
+    tag, vp, rows, frames = load(a.trace, a.lo, a.hi)
+    if not rows:
+        sys.exit(
+            f"{a.trace}: no `vpl`/`bub` lines in [{a.lo}, {a.hi}] — "
+            "was WOW_MOVE_TRACE_TAGS=vpl (or =bub) set?"
+        )
+    what = "plates" if tag == "vpl" else "bubbles"
+
+    ts = sorted(frames)
+    dts = sorted(b - a_ for a_, b in zip(ts, ts[1:]) if b - a_ < GAP_S)
+    drawn = sum(len(s) for s in rows.values())
+    off = sum(1 for s in rows.values() for r in s if not on_screen(r[3], vp))
+    print(
+        f"viewport {vp[0]:.0f}x{vp[1]:.0f}   frames {len(ts)} in [{ts[0]:.2f},{ts[-1]:.2f}]   "
+        f"dt med {1000 * dts[len(dts) // 2]:.1f} ms   {what}/frame {drawn / len(ts):.2f}"
+    )
+    print(f"OFF-SCREEN {what} drawn: {off}/{drawn} ({100 * off / drawn:.1f}%)   [must be 0]")
+
+    snap, jumps, steps = [], [], 0
+    for e, s in rows.items():
+        for p, q in zip(s, s[1:]):
+            if q[0] - p[0] > GAP_S:
+                continue
+            steps += 1
+            d_scr = [q[3][i] - p[3][i] for i in (0, 1)]
+            d_sol = [q[4][i] - p[4][i] for i in (0, 1)]
+            d_pl = [q[5][i] - p[5][i] for i in (0, 1)]
+            snap.append(max(abs(d_pl[i] - d_sol[i]) for i in (0, 1)))
+            solve = max(abs(d_sol[i] - d_scr[i]) for i in (0, 1))
+            if solve >= JUMP_PX:
+                jumps.append((solve, q[0], e, p[5], q[5], p[3], q[3]))
+    print(f"SNAP  extra px/frame (med p90 max): {stat(snap)}   [≤ half a device pixel]")
+    if tag == "vpl":
+        print(
+            f"SOLVE jumps ≥ {JUMP_PX:.0f} px: {len(jumps)}/{steps} steps "
+            f"({100 * len(jumps) / max(steps, 1):.2f}%)"
+        )
+    for j in sorted(jumps, reverse=True)[: a.worst]:
+        print(
+            f"   t={j[1]:8.3f} e={j[2]:<5d} {j[0]:7.1f} px   "
+            f"plate ({j[3][0]:7.1f},{j[3][1]:6.1f}) -> ({j[4][0]:7.1f},{j[4][1]:6.1f})   "
+            f"scr ({j[5][0]:8.1f},{j[5][1]:7.1f}) -> ({j[6][0]:8.1f},{j[6][1]:7.1f})"
+        )
+
+    # The world anchor's own motion by axis: horizontal is the unit gliding, vertical is the run
+    # cycle moving the posed head attachment (plus terrain). A standing unit reads 0 in both.
+    print("\nANCHOR motion — the world point's own Δ per frame, yd (med p90 max):")
+    for e, s in sorted(rows.items(), key=lambda kv: -len(kv[1]))[:8]:
+        pairs = [(a_, b) for a_, b in zip(s, s[1:]) if b[0] - a_[0] < GAP_S]
+        if len(pairs) < 10:
+            continue
+        horiz = [
+            ((b[1][0] - a_[1][0]) ** 2 + (b[1][2] - a_[1][2]) ** 2) ** 0.5 for a_, b in pairs
+        ]
+        vert = [b[1][1] - a_[1][1] for a_, b in pairs]
+        ys = [r[1][1] for r in s]
+        print(
+            f"   e={e:<5d} n={len(pairs):<5d} horiz {stat(horiz, '{:7.4f}')}   "
+            f"vert {stat(vert, '{:7.4f}')}   vert span {max(ys) - min(ys):.4f} yd"
+        )
+
+    print("\nPROJECTION smoothness — |Δ| and |ΔΔ| of the raw point, per unit (med p90 max):")
+    for e, s in sorted(rows.items(), key=lambda kv: -len(kv[1]))[:8]:
+        vis = [r for r in s if on_screen(r[3], vp)]
+        if len(vis) < 30:
+            continue
+        d = [
+            [b[3][i] - a_[3][i] for i in (0, 1)]
+            for a_, b in zip(vis, vis[1:])
+            if b[0] - a_[0] < GAP_S
+        ]
+        dd = [[b[i] - a_[i] for i in (0, 1)] for a_, b in zip(d, d[1:])]
+        anchor = max(
+            (abs(b[1][i] - a_[1][i]) for a_, b in zip(s, s[1:]) for i in (0, 1)), default=0.0
+        )
+        print(
+            f"   e={e:<5d} n={len(vis):<5d} anchor {anchor:6.4f} yd/frame   "
+            f"|Δx| {stat([v[0] for v in d])}   |ΔΔx| {stat([v[0] for v in dd])}   "
+            f"|ΔΔy| {stat([v[1] for v in dd])}"
+        )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/third_party/kira/BENILLA.md b/third_party/kira/BENILLA.md
index d2fb6c33..c5b7cb65 100644
--- a/third_party/kira/BENILLA.md
+++ b/third_party/kira/BENILLA.md
@@ -10,8 +10,8 @@ upstream files are CRLF and are left so, except the one file patched.
 
 The mixer runs on benilla's own audio render thread (`sound/output`), and with a raid buffing
 itself — a dozen live voices, most of them spatial — that thread cost **~1.5 ms of every 60 Hz
-frame** on the M2 Air (decision 1945: a sampled profile of the crowd rig's Blackrock leg with
-sound on, `Track::process` two thirds of it). Upstream's sub-track `process` spatializes **every
+frame** on an M2 Air (a sampled profile with a dozen spatial voices playing, `Track::process`
+two thirds of it). Upstream's sub-track `process` spatializes **every
 frame**: two vector normalizes, a length, the attenuation curve and a dB→amplitude `powf` per
 frame per spatial track, then two more `powf`s per frame for the volume tween and the fade. At
 48 kHz × 12 tracks that is ~1.7 M `powf`s a second plus the vector math, for gains that change
diff --git a/third_party/lua-src/BENILLA.md b/third_party/lua-src/BENILLA.md
index 4e4722db..f5dc6a09 100644
--- a/third_party/lua-src/BENILLA.md
+++ b/third_party/lua-src/BENILLA.md
@@ -1,82 +1,67 @@
-# benilla's `lua-src` fork — what differs from upstream, and how to check
+# benilla's `lua-src` fork: what differs from upstream, and how to check
 
-Upstream: [`mlua-rs/lua-src-rs`](https://github.com/mlua-rs/lua-src-rs), MIT, version `550.0.0` —
+Upstream: [`mlua-rs/lua-src-rs`](https://github.com/mlua-rs/lua-src-rs), MIT, version `550.0.0`,
 the version mlua 0.11 resolves to. Wired in through `[patch.crates-io]` in the workspace root.
 
 ## Why a fork exists at all
 
-**benilla's Lua has to accept exactly the grammar the 1.12.1 client's Lua accepts — no more and no
-less.** Every hunk below is that one rule: three restore 5.0 constructs 5.1 deleted, three delete
-5.1 constructs 5.0 never had. A grammar difference in either direction is invisible to every
-instrument we own until an addon trips over it, and the corpus *asks about* the difference
-directly (decisions 1208, 2101).
+benilla's Lua has to accept exactly the grammar the 1.12.1 client's Lua accepts, no more and no
+less. Every hunk below is that one rule: three restore 5.0 constructs 5.1 deleted, three delete 5.1
+constructs 5.0 never had. A grammar difference in either direction is invisible to every instrument
+until an addon trips over it, and the addon corpus asks about the difference directly.
 
-The 1.12 addon corpus is Lua **5.0** code. It uses the iterator-less generic-for:
+The 1.12 addon corpus is Lua 5.0 code. It uses the iterator-less generic-for:
 
 ```lua
 for k, v in someTable do ... end        -- no pairs(), no iterator function
 ```
 
-**183 of 218 corpus addons are reached by it** (118 carry it, 65 inherit it through a declared
-dependency), across 1,163 sites. On stock Lua 5.1 it raises `attempt to call a table value`, and it
-is the **first session-start error for 60 of 218 addons — three quarters of everything that breaks
-once the client is actually running**, eleven times the next cause.
+183 of 218 corpus addons are reached by it (118 carry it, 65 inherit it through a declared
+dependency), across 1,163 sites. On stock Lua 5.1 it raises `attempt to call a table value`, the
+first session-start error for 60 of the 218.
 
-Lua 5.1 removed it at the **opcode** level, which is why no layer above the VM can reach it. Every
-other dialect gap this project has closed was reachable from inside Lua — `table.setn` is a library
-function, `bit` is a library, `print` is a global (decisions 1194, 1196). This one is not:
+Lua 5.1 removed it at the opcode level, which is why no layer above the VM can reach it: a `__call`
+metamethod would need a per-type default metatable for tables, which 5.1 does not have; rewriting
+the chunk source means parsing Lua with a regex; and `lua-src` ships 5.1 through 5.5, every one of
+which removed it.
 
-- a `__call` metamethod would work, but the tables are the addon's own and Lua 5.1 has no
-  per-*type* default metatable for tables;
-- rewriting the chunk source means parsing Lua with a regex to tell `in t do` from `in pairs(t) do`,
-  and getting that wrong changes behaviour silently;
-- there is no `lua50` backend — `lua-src` ships 5.1 through 5.5 and every one of them removed it.
+## What is not being done
 
-## What is NOT being done
-
-**benilla is not adopting Lua 5.0.** We stay on 5.1.5 and restore the behaviour of a single opcode
+benilla is not adopting Lua 5.0. It stays on 5.1.5 and restores the behaviour of a single opcode
 that Lua itself shipped and labelled `/* for compatibility only */`. Every other 5.1 fix, and the
-whole of mlua's surface, stay exactly as upstream. That is a far smaller commitment than a version
-downgrade, and it is the entire reason this is a one-hunk fork rather than a vendored 5.0.
+whole of mlua's surface, stay exactly as upstream.
 
 ## The delta, and the command that proves it
 
-**Current state: eight hunks, in three files.** `src/lib.rs` additionally differs by having Lua
-5.2/5.3/5.4/5.5 stripped from the `Version` enum (with their source trees deleted) — benilla builds
-5.1 and only 5.1, and a fork that still *offered* the other four would answer a request for one with
-a missing directory at build time instead of a compile error.
+Eight hunks in three files. `src/lib.rs` additionally differs by having Lua 5.2/5.3/5.4/5.5 stripped
+from the `Version` enum (with their source trees deleted): benilla builds 5.1 and only 5.1, and a
+fork that still offered the other four would answer a request for one with a missing directory at
+build time instead of a compile error.
 
-**Five hunks restore what 5.1 changed or removed:**
+Five hunks restore what 5.1 changed or removed:
 
-| file | hunk | why | record |
-|---|---|---|---|
-| `lvm.c` | 5.0's `OP_TFORPREP` table→`next` substitution, folded into the top of `OP_TFORLOOP` | `for k, v in someTable do` raised "attempt to call a table value"; it was the first session-start error for **60** corpus addons | 1215 |
-| `luaconf.h` | `LUA_COMPAT_LSTR` `1` → `2` | 5.1 kept 5.0's nesting machinery and put an advisory error in front of it; two corpus addons died on "nesting of `[[...]]` is deprecated" | — |
-| `luaconf.h` | `LUA_QL(x)` back to 5.0's `` `x' `` from 5.1's `'x'` | every Lua error message quotes a program element, and `WoW.exe`'s own `.rdata` carries all five formats in the 5.0 spelling (`` bad argument #%d to `%s' (%s) ``, `` attempt to %s %s `%s' (a %s value) ``, `` %s:%d: %s near `%s' `` at the client's `0x87217c`, …). ~80 corpus addons ship AceLibrary, whose `argCheck` parses its own caller back out of `debugstack()` with a pattern that requires the backquote | 2122 |
-| `lparser.c` | 5.0's compat-semicolon skip restored at the top of `constructor()`'s field loop — 5.0's own line, verbatim, comment included | one extra `;` after a field separator inside a table constructor (`Back_Title = AL["Factions"];;`, ×20 in AtlasLoot's `ButtonRegistry.lua`) parses on the client and died here with "unexpected symbol near `;`"; statement-level `;;` stays rejected by both dialects | 1315 |
-| `lparser.c` | `recfield`'s `cc->nh++` moved back INSIDE its `TK_NAME` arm — 5.0's own placement | a `[expr] = value` constructor field must credit **neither** `OP_NEWTABLE` size hint, so the table is born on the dummy node, the first store rehashes, and the dense integer keys land in an ARRAY part that `next` walks ascending. 5.1 pre-sizes a node vector instead and leaves them in the hash, where `next` is slot order — so every list in every saved-variables file came back scrambled (Bagnon's keyring drew first) | 2111 |
+| file | hunk | why |
+|---|---|---|
+| `lvm.c` | 5.0's `OP_TFORPREP` table-to-`next` substitution, folded into the top of `OP_TFORLOOP` | `for k, v in someTable do` raised "attempt to call a table value" |
+| `luaconf.h` | `LUA_COMPAT_LSTR` `1` to `2` | 5.1 kept 5.0's `[[...]]` nesting machinery and put an advisory error in front of it; two corpus addons died on "nesting of `[[...]]` is deprecated" |
+| `luaconf.h` | `LUA_QL(x)` back to 5.0's `` `x' `` from 5.1's `'x'` | every Lua error message quotes a program element, and `WoW.exe`'s own `.rdata` carries all five formats in the 5.0 spelling |
+| `lparser.c` | 5.0's compat-semicolon skip restored at the top of `constructor()`'s field loop, 5.0's own line verbatim | one extra `;` after a field separator inside a table constructor (`Back_Title = AL["Factions"];;`, which AtlasLoot writes) is accepted by the client and was a parse error here |
+| `lparser.c` | `recfield`'s `cc->nh++` moved back inside its `TK_NAME` arm, 5.0's own placement | a `[expr] = value` constructor field credits neither `OP_NEWTABLE` size hint in 5.0, so the table is born on the dummy node |
 
-**Three delete what 5.1 added** — all in `lparser.c`, all byte-read out of the client's own parser
+Three delete what 5.1 added, all in `lparser.c`, all byte-read out of the client's own parser
 (`simpleexp 0x6fd240`, `getunopr 0x6fe0a0`, `getbinopr 0x6fe0c0`), all landing on 5.0's own
 `unexpected symbol` at `prefixexp 0x6fde40`:
 
-| hunk | why | record |
-|---|---|---|
-| `simpleexp`'s `case TK_DOTS` deleted — `...` is no longer an expression | the Ace2 corpus **asks** which interpreter it is on by compiling `return function(...) return ... end`; 170 `loadstring` sites in the 219-addon corpus are that question and 92 library files gate on it. Answering `true` put Cartographer on its client-2.0 branch, hooking `CloseSpecialWindows` — a name 1.12 does not have. Also restores 5.0's rule that **every** vararg function gets its `arg` table | 1208, 2101 |
-| `getunopr`'s `case '#'` deleted — no length operator | the client's `getunopr` tests exactly two tokens (`-`, `not`) and its `OPR_NOUNOPR` is **2**: a three-member enum, 5.0's. 5.0 asks a table with `table.getn` and a string with `string.len` | 2101 |
-| `getbinopr`'s `case '%'` deleted — no modulo operator | the client's `getbinopr` switch is based at `'*'` (0x2A), so `%` (0x25) is below its range and reaches `OPR_NOBINOPR` = **14**: a fifteen-member `BinOpr`, 5.0's. 5.0 spells it `math.mod` | 2101 |
+| hunk | why |
+|---|---|
+| `simpleexp`'s `case TK_DOTS` deleted: `...` is not an expression | the Ace2 corpus asks which interpreter it is on by compiling `return function(...) return ... end`; 170 `loadstring` sites in the corpus are that question, and 92 library files in 24 folders branch on the answer |
+| `getunopr`'s `case '#'` deleted: no length operator | the client's `getunopr` tests exactly two tokens (`-`, `not`) and its `OPR_NOUNOPR` is 2, a three-member enum; 5.0 asks a table with `table.getn` and a string with `string.len` |
+| `getbinopr`'s `case '%'` deleted: no modulo operator | the client's `getbinopr` switch is based at `'*'` (0x2A), so `%` (0x25) is below its range and reaches `OPR_NOBINOPR` = 14, a fifteen-member `BinOpr`; 5.0 spells it `math.mod` |
 
-The ordering was deliberate and it held: the fork landed **inert**, byte-identical to upstream, so
-the build pipeline was proven transparent *before* any behavioural payload went into it — and when
-the suite then moved, the patch was the only thing that could have moved it. Every hunk is measured
-against the corpus rather than argued: the long-string one alone took loaded 134 → 139 and
-survivors 99 → 104.
-
-**The deletions are safe because nothing the reference runs uses those constructs, and that was
-scanned rather than assumed** (2101 §4): a comment/string-stripping scan of the extracted 1.12
-FrameXML (177 files), GlueXML, Blizzard's own addons and the director's installed AddOns folder
-finds **zero** sites of all three. Our own engine Lua did use them and was rewritten into the 5.0
-spellings; the rule now is that no chunk of ours may use a construct the client's parser rejects.
+The deletions are safe because nothing the reference runs uses those constructs: a comment- and
+string-stripping scan of the 1.12 FrameXML (177 files), GlueXML, Blizzard's own addons and the
+corpus finds zero sites of all three. No chunk of benilla's own Lua may use a construct the client's
+parser rejects.
 
 To verify the Lua sources against upstream at any time:
 
@@ -86,20 +71,13 @@ diff -r third_party/lua-src/lua-5.1.5 \
   ~/.cargo/registry/src/*/lua-src-550.0.0/lua-5.1.5
 ```
 
-That must print **exactly** the eight hunks in the tables above and nothing else. If it ever prints
-more, something crept in.
+That must print exactly the eight hunks in the tables above and nothing else.
 
-## Status of the payload
+## The generic-for, in detail
 
-**Landed.** The reverse-engineering answer this was deliberately blocked on came back from
-`wow-5875-re` (`system/ui/scratch/lua-generic-for.md`) and is what the `lvm.c` comment cites, detail
-by detail: a **bare type-tag** test that never consults a metatable (so a table carrying `__call`
-still gets `next`), the **global** `next` read raw and fetched fresh at every loop entry (so an addon
-assigning `next = myfn` changes every later generic-for in the session), and userdata *not*
-substituted.
-
-Waiting was the right call twice over. Checking stock 5.0 first corrected two assumptions the
-project had already written down — the substitution happens in `OP_TFORPREP`, an opcode 5.1 deleted,
-*not* in `OP_TFORLOOP`; and the test is a bare `ttistable` with no `__call` check. Stock 5.0 was
-corroboration, never the authority: the client links 5.0 but may be modified, and only the byte-read
-of the client settles what it actually does.
+The `lvm.c` comment carries the three details that are the client's own, each byte-read there: the
+substitution test is a bare type-tag equality that never consults a metatable (a table carrying
+`__call` still gets `next`); the callee is the global `next`, read raw and fetched fresh at every loop
+entry (an addon assigning `next = myfn` changes every later generic-for in the session); and userdata
+is not substituted. The substitution happens in `OP_TFORPREP`, an opcode 5.1 deleted, so the top of
+`OP_TFORLOOP` is where 5.1 can host it.
diff --git a/third_party/lua-src/Cargo.toml b/third_party/lua-src/Cargo.toml
index 37eef0d0..e9b55b2d 100644
--- a/third_party/lua-src/Cargo.toml
+++ b/third_party/lua-src/Cargo.toml
@@ -7,11 +7,8 @@
 # error for 60 of 218 addons at session start, three quarters of everything that breaks in a running
 # session. It is not reachable from inside Lua: not a library function, not a global, an OPCODE.
 #
-# WHAT IS AND IS NOT CHANGED. **Right now: nothing.** The `lua-5.1.5/` tree here is byte-identical
-# to upstream's, and this fork was landed inert on purpose — the pipeline is proven transparent
-# BEFORE any behavioural payload goes into it, so that when the suite moves, the patch is the only
-# thing that could have moved it. `BENILLA.md` carries the current state and the one command that
-# verifies the sources against upstream.
+# WHAT IS AND IS NOT CHANGED: `BENILLA.md` lists every hunk against upstream's `lua-5.1.5/` tree
+# (eight, in three files) and the one command that verifies the sources against the registry copy.
 #
 # When the payload does land we are still NOT adopting Lua 5.0: we stay on 5.1.5 and restore the
 # behaviour of one opcode Lua itself shipped and labelled "for compatibility only", so every other
diff --git a/third_party/lua-src/lua-5.1.5/lparser.c b/third_party/lua-src/lua-5.1.5/lparser.c
index 13e7d04c..cdaf099b 100644
--- a/third_party/lua-src/lua-5.1.5/lparser.c
+++ b/third_party/lua-src/lua-5.1.5/lparser.c
@@ -509,22 +509,17 @@ static void constructor (LexState *ls, expdesc *t) {
   checknext(ls, '{');
   do {
     lua_assert(cc.v.k == VVOID || cc.tostore > 0);
-    /* BENILLA: Lua 5.0's constructor compat-semicolon, restored (decision 1315;
-    ** see third_party/lua-src/BENILLA.md). 5.0 opened this loop with exactly the
-    ** line below -- its own comment read "compatibility only", a Lua 4.0 leftover
-    ** (4.0 separated a constructor's list part from its record part with `;`).
-    ** 5.1 deleted the line, so one extra `;` after a field separator -- the
-    ** `Back_Title = AL["Factions"];;` shape AtlasLoot's ButtonRegistry.lua writes
-    ** twenty times -- became "unexpected symbol near ';'" here while the 1.12.1
-    ** client (Lua 5.0) accepts it. Statement-level `;;` stays rejected by both,
-    ** which is the half wow-5875-re byte-verified first (system/ui/scratch/
-    ** lua-dialect.md 9.1), and byte-verified in the client itself rather than
-    ** inferred from stock 5.0: constructor is 0x6fd430, and its loop head
-    ** 0x6fd4a0 calls testnext(ls,';') WITHOUT testing EAX -- a skip, not a
-    ** separator check -- while the loop's continuation at 0x6fd4f5/0x6fd505 does
-    ** test it. Of the 16 call sites of testnext 0x6fccf0 image-wide, the only
-    ** other consumer of `;' is chunk 0x6fcccc, at STATEMENT level, with no such
-    ** head skip. This line restores the constructor context only. */
+    /* BENILLA: Lua 5.0's constructor compat-semicolon, restored (see
+    ** third_party/lua-src/BENILLA.md). 5.0 opened this loop with exactly the
+    ** line below, a Lua 4.0 leftover; 5.1 deleted it, so one extra `;' after a
+    ** field separator (`Back_Title = AL["Factions"];;', which AtlasLoot writes)
+    ** raised "unexpected symbol near ';'" while the 1.12.1 client accepts it.
+    ** Statement-level `;;' stays rejected by both. Byte-read in the client:
+    ** constructor is 0x6fd430, and its loop head 0x6fd4a0 calls testnext(ls,';')
+    ** without testing EAX (a skip, not a separator check), while the loop's
+    ** continuation at 0x6fd4f5/0x6fd505 does test it; of testnext 0x6fccf0's 16
+    ** call sites, the only other `;' consumer is chunk 0x6fcccc, at statement
+    ** level, with no such head skip. */
     testnext(ls, ';');  /* compatibility only */
     if (ls->t.token == '}') break;
     closelistfield(fs, &cc);
@@ -766,39 +761,32 @@ static void simpleexp (LexState *ls, expdesc *v) {
       init_exp(v, VFALSE, 0);
       break;
     }
-    /* BENILLA: 5.1's vararg EXPRESSION arm, deleted (decision 2101; see
+    /* BENILLA: 5.1's vararg EXPRESSION arm, deleted (see
     ** third_party/lua-src/BENILLA.md). Lua 5.0 has no grammar for `...' as a
-    ** value -- a vararg function reads its extra arguments out of the implicit
-    ** `arg' table -- and `...' as an expression is the construct the Ace2 corpus
-    ** uses to ASK which interpreter it is running:
+    ** value: a vararg function reads its extra arguments out of the implicit
+    ** `arg' table. `...' as an expression is how the Ace2 corpus asks which
+    ** interpreter it is on:
     **
     **     local lua51 = loadstring("return function(...) return ... end") and true or false
     **
-    ** 170 loadstring sites across the 219-addon corpus are that question, and 92
-    ** library files in 24 folders gate on it (decision 1208). Answering it wrong
-    ** makes every one of them take a client-2.0 branch on a 1.12 client -- which
-    ** is how Cartographer came to hook `CloseSpecialWindows', a name 1.12 does
-    ** not have.
+    ** and 92 library files in 24 folders branch on the answer, taking a
+    ** client-2.0 path on a 1.12 client when it is wrong.
     **
-    ** Byte-verified in the client itself, not inferred from stock 5.0. simpleexp
-    ** is 0x6fd240; it switches on `token - 0x7B' bounded at 0xA3, indexes the
-    ** byte table at 0x6fd338 and jumps through the 8-entry table at 0x6fd318.
-    ** TK_DOTS is 0x118 (TK_NAME is 0x116 -- wow-5875-re system/ui/scratch/
-    ** lua-dialect.md 9), so its index byte is 0x9D, whose value is 7: the DEFAULT
-    ** arm, 0x6fd30a, which tail-jumps to primaryexp 0x6fdb00. The seven real arms
-    ** are `{', TK_FALSE, TK_FUNCTION, TK_NIL, TK_TRUE, TK_NUMBER and TK_STRING --
-    ** stock Lua 5.0's simpleexp exactly, with no vararg case.
+    ** Byte-read in the client: simpleexp is 0x6fd240; it switches on
+    ** `token - 0x7B' bounded at 0xA3, indexes the byte table at 0x6fd338 and
+    ** jumps through the 8-entry table at 0x6fd318. TK_DOTS is 0x118, so its
+    ** index byte is 0x9D, whose value is 7: the DEFAULT arm, 0x6fd30a, which
+    ** tail-jumps to primaryexp 0x6fdb00. The seven real arms are `{', TK_FALSE,
+    ** TK_FUNCTION, TK_NIL, TK_TRUE, TK_NUMBER and TK_STRING: stock Lua 5.0's
+    ** simpleexp exactly, with no vararg case. So `...' as a value reaches
+    ** prefixexp 0x6fde40, whose head accepts only `(' or TK_NAME and otherwise
+    ** raises "unexpected symbol" (0x871e80); deleting the arm reproduces that
+    ** error here, verbatim.
     **
-    ** So `...' as a value reaches prefixexp 0x6fde40, whose head accepts only `('
-    ** or TK_NAME and otherwise raises "unexpected symbol" (0x871e80) -- the same
-    ** reject site lua-dialect.md 9 documents for a stray `;'. Deleting the arm
-    ** reproduces that error here, verbatim.
-    **
-    ** It also restores 5.0's `arg' rule for free: the deleted line cleared
-    ** VARARG_NEEDSARG for any function that mentioned `...', so `arg' was not
-    ** built for it. With the arm gone, NEEDSARG is never cleared and EVERY vararg
-    ** function gets its `arg' table -- which is what 5.0 does and what all 177
-    ** files of the shipped 1.12 FrameXML read. */
+    ** It also restores 5.0's `arg' rule: the deleted line cleared
+    ** VARARG_NEEDSARG for any function that mentioned `...', so with the arm
+    ** gone every vararg function gets its `arg' table, which is what 5.0 does
+    ** and what the shipped 1.12 FrameXML reads. */
     case '{': {  /* constructor */
       constructor(ls, v);
       return;
@@ -821,15 +809,14 @@ static UnOpr getunopr (int op) {
   switch (op) {
     case TK_NOT: return OPR_NOT;
     case '-': return OPR_MINUS;
-    /* BENILLA: 5.1's `#' length operator, deleted (decision 2101). 5.0 asks a
-    ** table for its size with table.getn/getn and a string with string.len; the
-    ** operator does not exist and neither does its __len metamethod.
-    ** Byte-verified: getunopr is 0x6fe0a0, a leaf with exactly TWO token tests
-    ** -- `cmp ecx,0x2D' (`-') then `cmp ecx,0x10E' (TK_NOT), then setne/inc -- so
-    ** its OPR_NOUNOPR is 2, i.e. the enum has three members, not 5.1's four. The
-    ** metamethod-name pool at 0x871896 agrees: no __len (wow-5875-re
-    ** system/ui/scratch/lua-dialect.md 1, discriminator 4). A `#' therefore
-    ** reaches simpleexp's default arm and raises "unexpected symbol near `#'". */
+    /* BENILLA: 5.1's `#' length operator, deleted. 5.0 asks a table for its
+    ** size with table.getn and a string with string.len; the operator does not
+    ** exist and neither does its __len metamethod. Byte-read in the client:
+    ** getunopr is 0x6fe0a0, a leaf with exactly two token tests, `cmp ecx,0x2D'
+    ** (`-') then `cmp ecx,0x10E' (TK_NOT), so its OPR_NOUNOPR is 2: a
+    ** three-member enum, not 5.1's four. The metamethod-name pool at 0x871896
+    ** has no __len. A `#' therefore reaches simpleexp's default arm and raises
+    ** "unexpected symbol near `#'". */
     default: return OPR_NOUNOPR;
   }
 }
@@ -841,16 +828,14 @@ static BinOpr getbinopr (int op) {
     case '-': return OPR_SUB;
     case '*': return OPR_MUL;
     case '/': return OPR_DIV;
-    /* BENILLA: 5.1's `%' modulo operator, deleted (decision 2101). 5.0 spells it
-    ** math.mod (and the bare global `mod'), which this VM already publishes.
-    ** Byte-verified: getbinopr is 0x6fe0c0 and its switch is based at `ecx-0x2A'
-    ** -- `*', the LOWEST token it handles. `%' is 0x25, below the base, so it is
+    /* BENILLA: 5.1's `%' modulo operator, deleted. 5.0 spells it math.mod
+    ** (and the bare global `mod'), which this VM publishes. Byte-read in the
+    ** client: getbinopr is 0x6fe0c0 and its switch is based at `ecx-0x2A' (`*',
+    ** the lowest token it handles). `%' is 0x25, below the base, so it is
     ** outside the range test (`cmp eax,0xF2; ja') and falls to the default,
-    ** 0x6fe129, `mov eax,0xE' = OPR_NOBINOPR 14 -- a 15-member BinOpr, 5.0's, not
-    ** 5.1's 16-member one with OPR_MOD. Had 5.1's `%' case been present the
-    ** switch would have been based at 0x25. The metamethod pool has no __mod
-    ** either (wow-5875-re system/ui/scratch/lua-dialect.md 1, discriminator 4).
-    ** priority[] is indexed by the BinOpr enum, which is untouched -- only the
+    ** 0x6fe129, `mov eax,0xE' = OPR_NOBINOPR 14: a 15-member BinOpr, 5.0's, not
+    ** 5.1's 16-member one with OPR_MOD. The metamethod pool has no __mod either.
+    ** priority[] is indexed by the BinOpr enum, which is untouched; only the
     ** token that reaches OPR_MOD is gone. */
     case '^': return OPR_POW;
     case TK_CONCAT: return OPR_CONCAT;
diff --git a/third_party/lua-src/lua-5.1.5/luaconf.h b/third_party/lua-src/lua-5.1.5/luaconf.h
index b2e29f17..fc3a12c8 100644
--- a/third_party/lua-src/lua-5.1.5/luaconf.h
+++ b/third_party/lua-src/lua-5.1.5/luaconf.h
@@ -201,7 +201,7 @@
 ** CHANGE it if you want a different appearance.
 */
 /*
-** BENILLA (decision 2122): 1.12's Lua is 5.0, which quotes every program element in an error
+** BENILLA: 1.12's Lua is 5.0, which quotes every program element in an error
 ** message with a BACKQUOTE and an apostrophe. 5.1 introduced this macro and made it two
 ** apostrophes. Read out of WoW.exe's own .rdata, which carries all five of the formats this macro
 ** feeds, in the 5.0 spelling:
@@ -368,9 +368,8 @@
 ** off the advisory error when nesting [[...]].
 */
 /* BENILLA: 2, the 5.0 behaviour. 1.12.1 ships Lua 5.0, where `[[ ... [[ ... ]] ... ]]`
-** nests; 5.1 kept the machinery and put an advisory error in front of it. Two corpus
-** addons stop loading on "nesting of [[...]] is deprecated" — a 5.1 opinion about a
-** dialect we are not targeting. Same family as the OP_TFORPREP restoration (1215).
+** nests; 5.1 kept the machinery and put an advisory error in front of it, on which two
+** corpus addons stop loading ("nesting of [[...]] is deprecated").
 */
 #define LUA_COMPAT_LSTR		2
 
diff --git a/third_party/lua-src/lua-5.1.5/lvm.c b/third_party/lua-src/lua-5.1.5/lvm.c
index 50c89e75..b412a29c 100644
--- a/third_party/lua-src/lua-5.1.5/lvm.c
+++ b/third_party/lua-src/lua-5.1.5/lvm.c
@@ -680,42 +680,35 @@ void luaV_execute (lua_State *L, int nexeccalls) {
       }
       case OP_TFORLOOP: {
         StkId cb = ra + 3;  /* call base */
-        /* BENILLA: Lua 5.0's OP_TFORPREP, folded into the loop opcode.
-        ** See third_party/lua-src/BENILLA.md and benilla decision 1215.
+        /* BENILLA: Lua 5.0's OP_TFORPREP, folded into the loop opcode (see
+        ** third_party/lua-src/BENILLA.md).
         **
-        ** 5.0 ran this ONCE at loop entry in its own opcode (index 30, 157 bytes, verified in
-        ** the 1.12.1 client at 0x6f94a2): when a generic-for's generator is a table, the table
-        ** becomes the STATE and the generator becomes the global `next`. 5.1 deleted the opcode,
-        ** so `for k, v in someTable do` -- which 183 of 218 corpus addons are reached by, and
-        ** which is the first session-start error for 60 of them -- raises "attempt to call a
-        ** table value".
+        ** 5.0 ran this once at loop entry in its own opcode (index 30, 157 bytes, at
+        ** 0x6f94a2 in the 1.12.1 client): when a generic-for's generator is a table, the
+        ** table becomes the STATE and the generator becomes the global `next`. 5.1 deleted
+        ** the opcode, so `for k, v in someTable do`, which most 1.12 addons use, raised
+        ** "attempt to call a table value".
         **
-        ** Placing it here is timing-exact rather than approximate: 5.1's parser emits a JMP
-        ** straight to this instruction, so the top of TFORLOOP IS 5.0's prep point, before the
-        ** first call. It is self-clearing -- after one pass `ra` holds a function, so the test
-        ** fails on every later iteration -- which is what makes an entry-only rule safe to
-        ** express as a per-iteration check.
+        ** The top of TFORLOOP is 5.0's prep point exactly: 5.1's parser emits a JMP straight
+        ** to this instruction, before the first call. The check is self-clearing, since after
+        ** one pass `ra` holds a function, so an entry-only rule is safe as a per-iteration
+        ** test.
         **
-        ** Three details are the client's, not conveniences, each byte-verified in wow-5875-re
-        ** system/ui/scratch/lua-generic-for.md:
-        **   - the test is a BARE TYPE TAG equality. The handler makes no metatable access at
-        **     all, so a table carrying __call still gets `next` and never reaches tryfuncTM.
-        **     "not callable" and "no __call" are different conditions and both diverge here.
-        **   - the callee is the GLOBAL `next`, read RAW (no __index) from the thread's own
+        ** Three details are the client's, each byte-read there:
+        **   - the test is a BARE TYPE TAG equality. The handler makes no metatable access, so
+        **     a table carrying __call still gets `next` and never reaches tryfuncTM.
+        **   - the callee is the GLOBAL `next`, read raw (no __index) from the thread's own
         **     globals table, fetched fresh at every loop entry. An addon that assigns
-        **     `next = myfn` therefore changes every later generic-for in the session. That is
-        **     observable, and it is reproduced rather than improved on.
+        **     `next = myfn` therefore changes every later generic-for in the session.
         **   - userdata is NOT substituted (tag mismatch), so it still reaches __call, and a
         **     nil/string/number generator still raises on iteration 1, not at entry.
         **
-        ** KNOWN, MEASURED DIVERGENCE THIS DOES NOT CLOSE. 5.0's generic-for has two hidden
-        ** locals, not three: ra+2 is the first user variable AND the control, so assigning to it
-        ** inside the body changes what the next iteration is asked for. 5.1 gives the control
-        ** its own slot, and this patch does not move it -- that is a register-layout property
-        ** owned by the code generator, not by this handler. Measured before shipping
-        ** (scripts/generic-for-control-census.py): 95 addons contain the shape, concentrated in
-        ** two files nearly everything embeds -- Dewdrop-2.0.lua (123 sites) and AceEvent-2.0.lua
-        ** (113). Recorded rather than hidden; closing it is a separate change.
+        ** Deviation from 1.12 this does not close: 5.0's generic-for has two hidden locals,
+        ** not three, so ra+2 is the first user variable AND the control, and assigning to it
+        ** inside the body changes what the next iteration asks for. 5.1 gives the control its
+        ** own slot, a register-layout property of the code generator, not of this handler.
+        ** 95 corpus addons contain the shape, concentrated in Dewdrop-2.0.lua (123 sites) and
+        ** AceEvent-2.0.lua (113).
         */
         if (ttistable(ra)) {
           setobjs2s(L, ra+1, ra);